Support Wiki

Comprehensive documentation for the Loose Lips Sink Ships Chrome extension. Covers installation, configuration, enterprise deployment, and every setting available.

Getting Started

Loose Lips Sink Ships is a Chrome browser extension that detects and redacts personally identifiable information (PII) in text, documents, and images. It is designed for Australian government and enterprise environments where PII must never leave the browser unredacted.

Requirements

Installation

From Chrome Web Store

  1. Visit the Chrome Web Store listing
  2. Click Add to Chrome
  3. Confirm the permissions dialog
  4. The extension icon appears in your toolbar

Developer / Side-load Install

  1. Clone the repository: git clone https://github.com/bmaidev/looselipssinkships.extension.git
  2. Run vendor/setup.sh to download Tesseract.js and pdf.js dependencies
  3. Open chrome://extensions and enable Developer mode
  4. Click Load unpacked and select the repository root folder
  5. Verify the extension icon appears in your toolbar

Enable Gemini Nano (Optional)

  1. Navigate to chrome://flags
  2. Enable #optimization-guide-on-device-model — set to Enabled BypassPerfRequirement
  3. Enable #prompt-api-for-gemini-nano — set to Enabled
  4. Restart Chrome
  5. The green dot in the extension popup confirms Nano is available

Quick Start

After installation, the extension is active on all pages in Auto mode. Here is what happens by default:

Detection Modes

The detectionMode setting controls which engines are used and in what order. The extension supports five modes, each with a different privacy and capability trade-off.

Auto Default

Progressive escalation through all available tiers: Local → Hosted → Cloud.

Fallback chain

  1. Gemini Nano (on-device AI) — tried first if enabled and available
  2. Regex + Vector — always-available local fallback; runs if Nano is unavailable or fails
  3. Hosted models — tried if configured and the above steps produced no result
  4. Cloud providers (Azure PII, Purview) — tried only if no hosted provider could handle the request

If regexAfterAi is enabled (belt-and-suspenders mode), regex also runs as a second pass after Nano to catch anything the AI missed.

Best for: Most deployments. Maximises privacy by preferring local processing, but can escalate when higher-quality detection is needed.

AI Only

Uses only AI-capable providers. Will not fall back to regex.

Fallback chain

  1. Gemini Nano (local AI)
  2. Hosted AI models (organisation-hosted LLMs with text capability)
  3. Cloud AI (Azure PII, which uses NLP-based entity recognition)

Throws an error if no AI provider is available.

Best for: Environments where regex false positives are unacceptable and AI-quality detection is required.

Regex Only

Uses only the built-in regex pattern engine. No data leaves the device under any circumstances.

Fallback chain

  1. Regex engine — the sole provider; no escalation

Best for: Air-gapped networks, highest-security environments, or when deterministic pattern matching is preferred over probabilistic AI.

Hosted Only

Routes all text through organisation-hosted models. Falls back to regex if no hosted provider is available.

Fallback chain

  1. Hosted models (e.g., on-premises LLM)
  2. Regex engine (fallback if no hosted provider is reachable)

Best for: Organisations that operate their own AI infrastructure and want all detection to go through their own endpoints.

Cloud Only

Sends text directly to cloud providers. Falls back to regex if no cloud provider is available or configured.

Fallback chain

  1. Cloud providers (Azure PII, Purview)
  2. Regex engine (fallback if cloud is unavailable)

Best for: Environments where Azure PII accuracy is paramount and cloud data transmission is acceptable. Note that text is sent to external Azure endpoints.

Providers

Providers are organised into three tiers: Local, Hosted, and Cloud. The pipeline always prefers the highest-privacy tier first.

Gemini Nano Local

Chrome's built-in on-device language model. Runs entirely within the browser with no network requests.

Regex Engine Local

Pattern-based detection using the 17 built-in Australian PII type definitions. Always available as a fallback.

Vector Names Local

Cosine-similarity name detection using a vector embedding approach. Runs alongside regex when enableVectorFallback is true.

Azure PII Cloud

Azure AI Language PII detection service. Supports both API key (Direct) and OAuth2 (Enterprise) authentication.

Direct Mode (API Key)

FieldDescription
endpointAzure Language resource endpoint URL (e.g., https://myresource.cognitiveservices.azure.com)
apiKeyAPI key from the Azure portal — stored in chrome.storage.local
apiVersionAPI version string (default 2023-04-01)
languageLanguage code (default en)
domainDetection domain: none (general) or phi (health)
categoriesFilterArray of entity categories to detect (empty = all)

Enterprise Mode (OAuth2)

FieldDescription
connectionModeSet to enterprise
tenantIdAzure AD tenant ID (GUID)
clientIdApp Registration client ID (GUID)
endpointAzure Language resource endpoint URL

In Enterprise mode, the user signs in via Azure AD popup (PKCE flow). No API key is stored. See Azure OAuth2 for full setup.

Native Document Redaction

When nativeDocEnabled is true, Azure handles OCR, text extraction, PII detection, and document reconstruction server-side. Supports PDF, DOCX, and TXT files.

FieldDescription
sourceContainerUrlBlob storage URL for uploads. Direct: URL with SAS (read+list). Enterprise: plain URL.
targetContainerUrlBlob storage URL for results. Direct: URL with SAS (write+list). Enterprise: plain URL.
redactionPolicycharacterMask, entityMask, or noMask

Purview DLP Cloud

Microsoft Purview Data Loss Prevention via the Microsoft Graph API. Provides sensitivity label evaluation and DLP policy checking.

FieldDescription
tenantIdAzure AD tenant ID
clientIdApp Registration client ID
clientSecretClient secret (for application auth)
accessTokenPre-obtained access token (alternative to client secret)
graphEndpointGraph API endpoint (default https://graph.microsoft.com/beta)
useDelegatedAuthUse delegated (user) auth instead of application auth
dlpPolicyIdSpecific DLP policy ID to evaluate against
sensitiveInfoTypesArray of sensitive information type IDs to detect

The Purview provider also powers the Classification Gate.

Hosted Models Hosted

Organisation-hosted LLMs or OCR endpoints. Multiple instances can be configured. The extension connects to your own infrastructure.

FieldDescription
providerIdUnique identifier (e.g., agency_llm)
displayNameHuman-readable name shown in UI
endpointAPI base URL (e.g., https://internal-llm.agency.gov.au/v1)
apiKeyAPI key for authentication
apiModeopenai (chat completions API) or ocr_extract (OCR endpoint)
modelModel identifier (e.g., llama-3-70b)
maxTokensMaximum tokens for response (default 4096)
temperatureSampling temperature (default 0.0 for deterministic output)
timeoutRequest timeout in milliseconds (default 30000)
customHeadersAdditional HTTP headers as key-value object
capabilitiesArray of capabilities: ["text"], ["text","document"]
priorityNumeric priority (higher = tried first, default 30)
 
// Example hosted provider configuration
{
  "enabled": true,
  "providerId": "agency_llm",
  "displayName": "Agency LLM (On-Prem)",
  "endpoint": "https://internal-llm.agency.gov.au/v1",
  "apiKey": "",
  "apiMode": "openai",
  "model": "llama-3-70b",
  "maxTokens": 4096,
  "temperature": 0.0,
  "timeout": 30000,
  "customHeaders": {},
  "capabilities": ["text"],
  "priority": 30
}

PII Types

The extension ships with 17 built-in PII type definitions optimised for Australian data formats. Each type has an ID, display name, regex pattern, redaction token, and category.

IDNameTokenCategoryDescription
emailEmail Address[REDACTED_EMAIL]ContactStandard email addresses (user@domain.tld)
phone_auPhone Number (AU)[REDACTED_PHONE]ContactAustralian phone numbers: 04xx, (0x) xxxx xxxx, +61
phone_intlPhone Number (Intl)[REDACTED_PHONE]ContactInternational phone numbers with country code
tfnTax File Number[REDACTED_TFN]FinancialAustralian 8-9 digit tax file number
abnAustralian Business Number[REDACTED_ABN]Financial11-digit ABN
acnAustralian Company Number[REDACTED_ACN]Financial9-digit ACN (with ACN prefix)
medicareMedicare Number[REDACTED_MEDICARE]HealthAustralian Medicare card number (10-11 digits)
credit_cardCredit Card Number[REDACTED_CARD]FinancialVisa, Mastercard, Amex card numbers
bsbBSB Number[REDACTED_BSB]FinancialBank state branch number (6 digits with dash)
bank_accountBank Account Number[REDACTED_ACCOUNT]Financial6-10 digits following account/acct context
passportPassport Number[REDACTED_PASSPORT]IdentityAustralian passport (letter + 7 digits) and common formats
drivers_licenceDriver Licence Number[REDACTED_LICENCE]IdentityAustralian driver licence numbers (varies by state)
dobDate of Birth[REDACTED_DOB]IdentityCommon date formats with DOB context
street_addressStreet Address[REDACTED_ADDRESS]ContactAustralian-style street addresses (number + street name + type)
postcode_auAustralian Postcode[REDACTED_POSTCODE]Contact4-digit postcode when preceded by state abbreviation
ip_addressIP Address (v4)[REDACTED_IP]TechnicalIPv4 addresses
ipv6_addressIPv6 Address[REDACTED_IP]TechnicalIPv6 addresses

Custom PII Types

Add your own PII types via the Settings page or managed configuration. Custom types are appended to the built-in list.

// Example custom type in settings
{
  "customPiiTypes": [
    {
      "id": "custom_employee_id",
      "name": "Employee ID",
      "description": "Agency employee identifiers (EMP-XXXXX)",
      "token": "[REDACTED_EMPID]",
      "enabled": true,
      "regex": "EMP-\\d{5}",
      "flags": "gi",
      "category": "custom"
    }
  ]
}

Requirements for custom types:

Type Overrides

Override properties of built-in types without replacing them entirely. Useful for disabling specific types or changing their tokens.

// Disable TFN detection and change email token
{
  "piiTypeOverrides": {
    "tfn": { "enabled": false },
    "email": { "token": "[EMAIL_REMOVED]" }
  }
}

Overrides are merged at load time. The id field can never be overridden.

Text Protection

Three complementary systems protect text input across all web pages. They can be used independently or together.

Auto-Redact

Automatically scans and redacts PII as users type or paste content, without requiring a button click.

SettingTypeDefaultDescription
autoRedact.enabledbooleanfalseMaster toggle. Off by default; auto-enabled on AI chat sites if aiChatGuard.autoRedactOnAiSites is true.
autoRedact.debounceMsnumber2500Milliseconds to wait after typing pauses before scanning.
autoRedact.onPastebooleantrueImmediately redact pasted content (no debounce).
autoRedact.onlyOnAiSitesbooleantrueOnly auto-redact on detected AI chat sites (safer default).

Submit Guard

Intercepts form submissions and Enter-key presses to ensure redaction completes before data is sent.

SettingTypeDefaultDescription
submitGuard.enabledbooleantrueMaster toggle for submit interception.
submitGuard.interceptEnterbooleantrueIntercept Enter key in textareas (common in chat UIs).
submitGuard.interceptFormSubmitbooleantrueIntercept HTML form submit events.
submitGuard.interceptSendButtonsbooleantrueIntercept click events on send/submit buttons.
submitGuard.onlyOnAiSitesbooleantrueOnly active on detected AI chat sites by default.

Upload Guard

Intercepts file input changes to scan and redact documents before they are uploaded.

SettingTypeDefaultDescription
uploadGuard.enabledbooleantrueMaster toggle for upload interception.
uploadGuard.onlyOnAiSitesbooleantrueOnly active on detected AI chat sites by default.
uploadGuard.confirmBeforeUploadbooleantrueShow a confirmation dialog before allowing upload after redaction.

AI Chat Guard

The AI Chat Guard is a specialised protection layer that activates automatically when you visit any known AI chat service. It ensures PII is redacted before text can be submitted to AI platforms.

How It Works

When you navigate to a page matching a known AI chat domain:

  1. The extension detects the AI service via URL pattern matching against 30+ built-in domains
  2. A protection banner is injected at the top of the page indicating the guard is active
  3. Auto-redact activates on all text fields (if autoRedactOnAiSites is enabled)
  4. Submit interception blocks form submission and Enter key until redaction completes
  5. Upload interception scans files before they can be attached

Services Detected

The following AI chat services are detected automatically:

ServiceDomains
OpenAI / ChatGPTchat.openai.com, chatgpt.com, *.openai.com
Anthropic / Claudeclaude.ai, *.anthropic.com
Google Geminigemini.google.com, aistudio.google.com, bard.google.com, notebooklm.google.com
Microsoft Copilotcopilot.microsoft.com, copilot.cloud.microsoft, *.copilot.microsoft.com, bing.com/chat, edgeservices.bing.com
X / Grokgrok.x.ai, x.com/i/grok
Meta AImeta.ai, *.meta.ai
Perplexityperplexity.ai, *.perplexity.ai
Mistralchat.mistral.ai, *.mistral.ai
HuggingChathuggingface.co/chat
Coherecoral.cohere.com, dashboard.cohere.com
DeepSeekchat.deepseek.com, *.deepseek.com
Poepoe.com
You.comyou.com
Pipi.ai
Character.AIcharacter.ai, *.character.ai
Replikareplika.ai
Jasperapp.jasper.ai
Inflectioninflection.ai
Local / Self-hostedlocalhost, 127.0.0.1

Custom Domains

Add additional domains to the AI chat guard via the aiChatGuard.customAiDomains array:

{
  "aiChatGuard": {
    "customAiDomains": [
      "internal-ai.agency.gov.au",
      "*.llm.myorg.com"
    ]
  }
}

Protection Banner

When the AI Chat Guard is active, a banner is injected at the top of the page. The banner:

Document Processing

The extension processes 50+ file formats. Documents are handled by format-specific processors with a shared pipeline.

DOCX (Word)

DOCX files are ZIP archives containing XML. The extension:

  1. Unzips the DOCX container
  2. Parses the XML content (word/document.xml)
  3. Runs PII detection on extracted text
  4. Performs in-place XML replacement — PII tokens replace original text within the XML nodes
  5. Re-zips to produce a valid .docx file with formatting preserved

DOCX redaction preserves fonts, styles, tables, headers, footers, and other formatting. The output is a fully valid Word document.

XLSX / CSV

XLSX: Extracted as XML (similar to DOCX), converted to CSV, and redacted as text. The output is a redacted CSV file (format conversion preserves data but not Excel formatting).

CSV: Processed as plain text with PII detection applied to cell contents.

PDF

PDFs are handled through multiple paths depending on the document type:

Text-based PDFs

  1. pdf.js renders each page in an offscreen document
  2. Text is extracted with character positions
  3. PII detection runs on the extracted text
  4. If bounding boxes are available, black rectangles are drawn over PII regions
  5. Pages are flattened to images to prevent hidden text layer extraction

Scanned PDFs (OCR)

  1. pdf.js renders each page as a canvas image
  2. Tesseract.js OCR extracts text with word-level bounding boxes
  3. PII detection maps matches to OCR bounding boxes
  4. Black rectangles are drawn over PII regions at the pixel level
  5. Redacted pages are reassembled into a new PDF

Azure Native Document (Cloud)

When nativeDocEnabled is true, PDFs can be uploaded to Azure for server-side processing:

  1. File is uploaded to Azure Blob Storage (source container)
  2. Azure Language API processes the document (OCR + PII detection + redaction)
  3. Redacted file is downloaded from the target container

Images

PNG, JPEG, GIF, WebP, BMP, and TIFF images are supported:

  1. Image is loaded into an offscreen canvas
  2. Tesseract.js extracts text with word-level bounding boxes
  3. PII matches are mapped to bounding box coordinates
  4. Black rectangles are drawn over PII regions
  5. Redacted image is exported as PNG

There is no hidden text layer in redacted images. PII is permanently destroyed at the pixel level.

ZIP Archives

ZIP files are processed recursively:

  1. Archive is extracted to enumerate all entries
  2. Each text-based entry is individually redacted (using regex)
  3. Binary entries (images, PDFs) are kept as-is
  4. Redacted entries are repacked into a new ZIP archive

Text-based Files

The following file types are processed as plain text with PII detection applied directly:

.txt, .csv, .json, .jsonl, .xml, .yaml, .yml, .toml, .ini, .cfg, .conf, .env, .log, .md, .rst, .adoc, .tex, .rtf, .html, .htm, .py, .rb, .php, .js, .ts, .jsx, .tsx, .java, .cs, .go, .rs, .swift, .kt, .scala, .c, .cpp, .h, .hpp, .sql, .sh, .bash, .zsh, .ps1, .r, .m, .pl, and more.

Site Filtering

Control which websites the extension activates on. Three modes are available:

ModeBehaviour
all DefaultExtension is active on all sites
whitelistExtension is active only on listed sites
blacklistExtension is active everywhere except listed sites

If a site is filtered out (blacklisted or not whitelisted), the AI Chat Guard is also disabled on that site. The extension is fully inactive.

Pattern Syntax

Patterns support several formats:

PatternExampleMatches
Exact domainexample.comOnly example.com
Wildcard subdomain*.example.comsub.example.com, a.b.example.com, example.com
Suffix match*.gov.auAll Australian government sites
Full URL prefixhttps://portal.agency.gov.au/*All pages under that path
Dot prefix.gov.auAny hostname ending in .gov.au
 
// Whitelist example: only government sites
{
  "siteFilter": {
    "mode": "whitelist",
    "whitelist": [
      "*.gov.au",
      "*.defence.gov.au",
      "https://portal.internal.agency.gov.au/*"
    ]
  }
}

// Blacklist example: disable on internal tools
{
  "siteFilter": {
    "mode": "blacklist",
    "blacklist": [
      "jira.internal.com",
      "confluence.internal.com"
    ]
  }
}

Standalone Tool (redact.html)

The extension includes a standalone redaction tool at redact.html in the extension root. It provides a full-page interface for bulk document redaction.

How to Access

Features

Classification Gate

The Classification Gate prevents classified or sensitive documents from being uploaded to external services. It reads Microsoft Information Protection (MSIP) sensitivity labels embedded in DOCX and XLSX files.

MSIP Label Detection

OOXML files (DOCX, XLSX) store MSIP labels in docProps/custom.xml as key-value properties:

MSIP_Label_{GUID}_Enabled = true
MSIP_Label_{GUID}_Name = "PROTECTED"
MSIP_Label_{GUID}_SiteId = {tenant GUID}
MSIP_Label_{GUID}_Method = Standard | Privileged
MSIP_Label_{GUID}_ContentBits = 8

The gate reads these properties locally (Layer 1) without any API call. An optional Layer 2 check uses the Microsoft Graph API for deeper policy evaluation.

Gate Evaluation Flow

  1. Extract MSIP labels from the file's custom properties (local, instant)
  2. Check if any label matches the blockedLabels list — if yes, block the upload
  3. Check if the file is encrypted (ContentBits & 0x8) and blockEncrypted is true — if yes, block
  4. Check if any label matches the warnLabels list — if yes, show warning but allow
  5. Optionally query Graph API for additional policy evaluation (checkViaApi)
  6. If no restrictions are found, allow the upload

Australian PSPF Classification Table

The following table shows the recommended gate configuration aligned with the Australian Government Protective Security Policy Framework (PSPF):

ClassificationGate ActionRationale
UNOFFICIALAllowNo protective marking. No restrictions on sharing.
OFFICIALAllowStandard business information. Low business impact if compromised.
OFFICIAL: SensitiveWarnSensitive business information. Caution advised before sharing externally. User is warned but may proceed.
PROTECTEDBlockValuable or sensitive information. Must not leave controlled environment. Upload is blocked with no override.
SECRETBlockClassified material. Compromise could cause serious damage to national security. Upload is blocked absolutely.
TOP SECRETBlockClassified material. Compromise could cause exceptionally grave damage to national security. Upload is blocked absolutely.
 
// Recommended enterprise configuration
{
  "providers": {
    "purview": {
      "gateEnabled": true,
      "blockedLabels": ["PROTECTED", "SECRET", "TOP SECRET"],
      "warnLabels": ["OFFICIAL:Sensitive", "OFFICIAL: Sensitive"],
      "blockEncrypted": true
    }
  }
}

Encrypted File Blocking

When blockEncrypted is true (default), files with the MSIP encryption bit set (ContentBits & 0x8) are blocked regardless of their label name. This prevents Rights Management (RMS) protected documents from being uploaded.

Enterprise Deployment

The extension supports four deployment methods for organisations of all sizes. Each pushes configuration to chrome.storage.managed (or equivalent), which the extension reads at startup.

Microsoft Intune

For organisations using Microsoft Endpoint Manager / Intune to manage Chrome on Windows, macOS, or ChromeOS devices.

  1. In the Microsoft Intune admin center, navigate to Devices → Configuration profiles
  2. Create a new profile: Windows 10 and later → Templates → Administrative templates (custom)
  3. Add an OMA-URI setting for Chrome managed extensions:
    ./Device/Vendor/MSFT/Policy/Config/Chrome~Policy~googlechrome~Extensions/ExtensionSettings
  4. Set the value to a JSON string containing your extension ID and managed storage policy: 
    {
  "<extension-id>": {
    "installation_mode": "force_installed",
    "update_url": "https://clients2.google.com/service/update2/crx",
    "managed_storage": {
      "detectionMode": "auto",
      "providers": {
        "azure_pii": {
          "enabled": true,
          "connectionMode": "enterprise",
          "tenantId": "YOUR_TENANT_ID",
          "clientId": "YOUR_CLIENT_ID",
          "endpoint": "https://your-resource.cognitiveservices.azure.com"
        },
        "purview": {
          "gateEnabled": true,
          "blockedLabels": ["PROTECTED", "SECRET", "TOP SECRET"],
          "warnLabels": ["OFFICIAL:Sensitive"],
          "blockEncrypted": true
        }
      },
      "siteFilter": {
        "mode": "whitelist",
        "whitelist": ["*.gov.au"]
      },
      "_locked": {
        "detectionMode": true,
        "providers.azure_pii": true,
        "providers.purview.gateEnabled": true,
        "siteFilter": true
      },
      "_policyVersion": "2024.10.1"
    }
  }
}
  5. Assign the profile to the target device groups
  6. Devices receive the policy on next sync (typically within 15 minutes)

Group Policy (GPO)

For organisations using Active Directory Group Policy to manage Chrome on Windows devices.

  1. Download the Chrome ADMX templates and add to your Central Store
  2. Open Group Policy Management Editor
  3. Navigate to Computer Configuration → Administrative Templates → Google Chrome → Extensions
  4. Open Configure extension management settings
  5. Paste the same JSON structure as the Intune example above, with your extension ID as the key
  6. For managed storage specifically, create a registry key at:
    HKLM\SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\<extension-id>\policy
  7. Add REG_SZ values for each top-level setting, or use a single JSON blob via the ExtensionSettings policy
  8. Run gpupdate /force on target machines or wait for the next GP refresh cycle

Google Workspace

For organisations using Google Workspace (formerly G Suite) to manage Chrome on ChromeOS or managed Chrome browsers.

  1. Sign in to the Google Admin Console at admin.google.com
  2. Navigate to Devices → Chrome → Apps & extensions
  3. Select the target organisational unit (OU)
  4. Click the + button and add the extension by ID from the Chrome Web Store
  5. Set installation policy to Force install
  6. Under Policy for extensions, paste the managed storage JSON configuration
  7. Save and wait for devices in the OU to sync (typically within a few hours)

Small Business (Remote Config)

For organisations without MDM or managed Chrome browsers. Uses a JSON file hosted on any HTTPS server.

  1. Create a JSON configuration file with your desired settings (same schema as managed storage)
  2. Host it on any HTTPS endpoint accessible to your users (e.g., https://config.yourcompany.com/llss-config.json)
  3. In the extension settings, set the Config URL field to the JSON URL: 
    {
  "configUrl": "https://config.yourcompany.com/llss-config.json"
}
  4. The extension fetches the config on startup and caches it in chrome.storage.local
  5. Remote config supports the same _locked and _policyVersion fields as managed storage
  6. To update settings, simply update the hosted JSON file — the extension will pick up changes on next restart

Remote config has lower precedence than managed storage but higher than local user settings. If both are present, managed storage wins.

Managed Configuration

The extension merges settings from four sources in a strict precedence order.

Merge Precedence

Settings are merged from lowest to highest priority:

  1. Defaults — hardcoded DEFAULT_SETTINGS in the extension code
  2. Local user settings — stored in chrome.storage.local (user-editable)
  3. Remote config — fetched from configUrl (small business deployment)
  4. Managed storage — pushed via chrome.storage.managed (enterprise MDM) — highest priority

Each layer deep-merges into the previous. Arrays are replaced, not concatenated. The final merged object includes a _meta property with lock information.

Locked Settings (_locked)

The _locked map is an object where keys are dot-separated setting paths and values are booleans. Locked settings:

{
  "_locked": {
    "detectionMode": true,
    "providers.azure_pii": true,
    "aiChatGuard": true,
    "siteFilter.mode": true
  }
}

Policy Version (_policyVersion)

An optional string (e.g., "2024.10.1") attached to the merged _meta. Useful for administrators to track which policy version is deployed. Displayed in the extension's Settings page for troubleshooting.

Schema Versions

The extension migrates settings automatically as the schema evolves:

VersionChanges
v1Initial schema. Basic detection settings, PII types, UI toggles.
v2Added providers object (local_ai, regex, azure_pii, purview, hosted). Added enableDocumentUpload.
v3Added siteFilter, aiChatGuard, autoRedact, submitGuard, uploadGuard sections.
v4Migrated useManagedIdentity boolean to connectionMode string ("direct"/"enterprise") in Azure PII.
v5Added Classification Gate fields to Purview: gateEnabled, blockedLabels, warnLabels, blockEncrypted.

Current schema version: 5 (stored as schemaVersion: 5 in settings). Migration is automatic and non-destructive.

Azure OAuth2

Enterprise mode uses Azure AD OAuth2 with PKCE for secure, credential-free authentication to Azure Cognitive Services.

App Registration Setup

  1. In the Azure Portal, go to Azure Active Directory → App registrations → New registration
  2. Set the name (e.g., "LLSS Chrome Extension") and select Single tenant or Multi-tenant as needed
  3. Set the Redirect URI type to Web and enter the value from chrome.identity.getRedirectURL()
    (format: https://<extension-id>.chromiumapp.org/)
  4. Under Authentication, enable Allow public client flows (required for PKCE)
  5. Under API permissions, add Azure Cognitive Services → user_impersonation (delegated)
  6. If using Azure Blob Storage for native documents, also add Azure Storage → user_impersonation
  7. Grant admin consent for the tenant
  8. Copy the Application (client) ID and Directory (tenant) ID into the extension settings

PKCE Flow

The extension uses the Authorization Code Flow with Proof Key for Code Exchange (PKCE):

  1. Code verifier — 32 random bytes, base64url-encoded
  2. Code challenge — SHA-256 hash of the verifier, base64url-encoded (S256 method)
  3. Authorization request — chrome.identity.launchWebAuthFlow() opens the Azure AD login popup with the challenge
  4. Authorization code — extracted from the callback URL, validated against the state parameter
  5. Token exchange — POST to /oauth2/v2.0/token with the code and verifier
  6. Tokens stored — access token, refresh token, and ID token saved to chrome.storage.session (memory-only)

Tokens are stored in chrome.storage.session, which is memory-only and cleared when the browser closes. No credentials are ever written to disk.

Token Management

Sign In / Sign Out

// Sign in (from background script or popup)
const userInfo = await LLSS_AzureAuth.signIn(tenantId, clientId);
// Returns: { name: "Jane Smith", email: "jane@agency.gov.au", tenantId: "..." }

// Get token for API calls
const token = await LLSS_AzureAuth.getAccessToken(tenantId, clientId);

// Check status
const signedIn = await LLSS_AzureAuth.isSignedIn();

// Sign out (clears all tokens)
await LLSS_AzureAuth.signOut();

Managed Identity for Storage

In Enterprise mode with native document redaction:

Settings Reference

Complete reference for every setting in DEFAULT_SETTINGS. Settings are organised by section.

Detection

SettingTypeDefaultDescription
detectionModestring"auto"Detection mode: "auto", "ai_only", "regex_only", "cloud_only", or "hosted_only".
enableVectorFallbackbooleantrueRun the vector name detector alongside regex fallback.
vectorThresholdnumber0.45Confidence threshold for vector name detection (0 to 1).
regexAfterAibooleanfalseBelt-and-suspenders: also run regex after AI to catch anything missed.
customPiiTypesarray[]Custom PII type definitions (merged with built-in defaults).
piiTypeOverridesobject{}Override properties on built-in PII types (e.g., { "email": { "enabled": false } }).
sessionTimeoutMinutesnumber5Idle timeout in minutes before destroying the Gemini Nano AI session.

UI

SettingTypeDefaultDescription
showRedactButtonbooleantrueShow the green Redact button on all textareas and text inputs.
enableContentEditablebooleantrueAlso attach to contenteditable elements (rich text editors).
enableDocumentUploadbooleantrueShow the document upload button alongside the text redact button.

Site Filter

SettingTypeDefaultDescription
siteFilter.modestring"all"Filter mode: "all", "whitelist", or "blacklist".
siteFilter.whitelistarray[]URL patterns for whitelist mode.
siteFilter.blacklistarray[]URL patterns for blacklist mode.

AI Chat Guard

SettingTypeDefaultDescription
aiChatGuard.enabledbooleantrueMaster toggle for AI chat protection.
aiChatGuard.autoRedactOnAiSitesbooleantrueAuto-redact text before it can be submitted to AI services.
aiChatGuard.blockSubmitUntilRedactedbooleantrueBlock form submission until redaction completes on AI chat sites.
aiChatGuard.interceptUploadsbooleantrueIntercept file uploads on AI chat sites for scanning.
aiChatGuard.customAiDomainsarray[]Additional domains to treat as AI chat services.
aiChatGuard.showAiBannerbooleantrueShow a protection banner on detected AI chat sites.

Auto-Redact

SettingTypeDefaultDescription
autoRedact.enabledbooleanfalseAuto-redact PII as users type or paste. Off by default.
autoRedact.debounceMsnumber2500Debounce delay in ms before redacting after typing pauses.
autoRedact.onPastebooleantrueImmediately redact pasted content (no debounce).
autoRedact.onlyOnAiSitesbooleantrueOnly auto-redact on detected AI chat sites.

Submit Guard

SettingTypeDefaultDescription
submitGuard.enabledbooleantrueMaster toggle for submit interception.
submitGuard.interceptEnterbooleantrueIntercept Enter key in textareas.
submitGuard.interceptFormSubmitbooleantrueIntercept HTML form submit events.
submitGuard.interceptSendButtonsbooleantrueIntercept click on send/submit buttons.
submitGuard.onlyOnAiSitesbooleantrueOnly active on detected AI chat sites.

Upload Guard

SettingTypeDefaultDescription
uploadGuard.enabledbooleantrueMaster toggle for upload interception.
uploadGuard.onlyOnAiSitesbooleantrueOnly active on detected AI chat sites.
uploadGuard.confirmBeforeUploadbooleantrueShow confirmation dialog before allowing upload.

Providers

Local AI (Gemini Nano)

SettingTypeDefaultDescription
providers.local_ai.enabledbooleantrueUse Gemini Nano when available.

Regex

SettingTypeDefaultDescription
providers.regex.enabledbooleantrueAlways-available regex fallback.

Azure PII

SettingTypeDefaultDescription
providers.azure_pii.enabledbooleanfalseEnable Azure AI Language PII detection.
providers.azure_pii.endpointstring""Azure Language resource endpoint URL.
providers.azure_pii.apiKeystring""API key (Direct mode only).
providers.azure_pii.apiVersionstring"2023-04-01"API version string.
providers.azure_pii.languagestring"en"Detection language code.
providers.azure_pii.domainstring"none"Detection domain: "none" (general) or "phi" (health).
providers.azure_pii.categoriesFilterarray[]Entity categories to detect (empty = all).
providers.azure_pii.connectionModestring"direct""direct" (API key) or "enterprise" (OAuth2 PKCE).
providers.azure_pii.tenantIdstring""Azure AD tenant ID (Enterprise mode).
providers.azure_pii.clientIdstring""App Registration client ID (Enterprise mode).
providers.azure_pii.nativeDocEnabledbooleanfalseEnable server-side document redaction via Azure.
providers.azure_pii.sourceContainerUrlstring""Blob storage URL for source uploads.
providers.azure_pii.targetContainerUrlstring""Blob storage URL for redacted results.
providers.azure_pii.redactionPolicystring"entityMask"Redaction policy: "characterMask", "entityMask", or "noMask".

Purview DLP

SettingTypeDefaultDescription
providers.purview.enabledbooleanfalseEnable Microsoft Purview DLP.
providers.purview.tenantIdstring""Azure AD tenant ID.
providers.purview.clientIdstring""App Registration client ID.
providers.purview.clientSecretstring""Client secret for application auth.
providers.purview.accessTokenstring""Pre-obtained access token (alternative).
providers.purview.graphEndpointstring"https://graph.microsoft.com/beta"Graph API endpoint URL.
providers.purview.useDelegatedAuthbooleanfalseUse delegated (user) auth instead of application auth.
providers.purview.dlpPolicyIdstring""Specific DLP policy ID to evaluate.
providers.purview.sensitiveInfoTypesarray[]Sensitive info type IDs to detect.
providers.purview.gateEnabledbooleanfalseEnable Classification Gate (pre-upload label check).
providers.purview.blockedLabelsarray[]Sensitivity label names to block (e.g., ["PROTECTED","SECRET"]).
providers.purview.warnLabelsarray[]Sensitivity label names to warn but allow.
providers.purview.blockedSensitivitynumber0Block labels with sensitivity >= this value (0 = disabled).
providers.purview.blockEncryptedbooleantrueBlock files with encryption/RMS markers.
providers.purview.checkViaApibooleanfalseAlso evaluate via Graph API (requires auth).

Hosted Models

SettingTypeDefaultDescription
providers.hostedarray[]Array of hosted model configurations. Each entry follows the schema described in the Hosted Models section.

Debug & Misc

SettingTypeDefaultDescription
debugModebooleanfalseOutput detailed diagnostics to the browser console.
configUrlstring""Remote configuration URL (for small-business deployment without MDM).
schemaVersionnumber3Settings schema version. Auto-migrated on load. Do not set manually.

Troubleshooting

Debug Mode

Enable debug logging to get detailed diagnostics from every subsystem:

  1. Open the extension Settings page
  2. Scroll to the Troubleshooting section
  3. Toggle Debug mode on
  4. All subsystems will output [LLSS:subsystem] prefixed messages to the console

Subsystem labels include: nano, regex, vector, pipeline, azure-auth, azure-pii, purview-gate, document, offscreen, content-script, and more.

Error-level messages (LLSS_debug.error()) are always output regardless of debug mode, so critical failures are always visible.

Console Locations

Chrome extensions have three separate console contexts. You need to check the right one:

ConsoleHow to OpenWhat It Shows
Page Console Right-click page → Inspect → Console tab Content script logs, redact button interactions, auto-redact, submit/upload guard events, AI chat guard banner
Service Worker Console chrome://extensions → find extension → click "service worker" link Background script logs, pipeline execution, provider availability, Azure auth, token refresh, alarm events, managed config loading
Offscreen Console chrome://extensions → find extension → click "offscreen.html" link (when active) PDF rendering, Tesseract.js OCR, pixel redaction, canvas operations, worker pool status

Common Errors & Solutions

ErrorCauseSolution
No redaction providers available All configured providers are disabled or unavailable Ensure at least providers.regex.enabled is true. Check that Gemini Nano flags are enabled if using AI mode.
Provider 'local_ai' is not available Gemini Nano is not enabled or the model is not downloaded Enable Chrome flags (#optimization-guide-on-device-model and #prompt-api-for-gemini-nano), restart Chrome, and wait for the model to download.
Token exchange failed: HTTP 400 Azure AD app registration misconfigured Verify redirect URI matches chrome.identity.getRedirectURL(). Ensure "Allow public client flows" is enabled. Check client ID and tenant ID.
State mismatch — possible CSRF attack Auth flow interrupted or replayed Try signing in again. If persistent, clear extension data and re-authenticate.
Token refresh failed — sign in again Refresh token expired or revoked Sign out and sign in again. Check Azure AD Conditional Access policies for session lifetime limits.
Not signed in to Azure AD Enterprise mode requires OAuth2 but user has not signed in Open the popup or settings page and click the Azure AD Sign In button.
No API key configured Direct mode Azure PII requires an API key Enter the API key from Azure portal in Settings → Providers → Azure PII → API Key.
Document processing failed No provider could handle the document format Check the pipeline steps in the error message. Ensure vendor/setup.sh has been run for PDF/image support. Check the offscreen console for OCR errors.
ZIP processing not available ZIP parser module not loaded Ensure all extension files are intact. Reload the extension from chrome://extensions.
Offscreen document not available Chrome did not create the offscreen document Reload the extension. Check chrome://extensions for error badges. Ensure the offscreen permission is in manifest.json.
Graph API evaluation failed: 403 Purview API permissions insufficient Ensure the app registration has the required Graph API permissions and admin consent has been granted.

Performance Issues

Security & Privacy

Design Principles

No Telemetry

Provably Secure Redaction

Enterprise Mode Security