How wxk-ai/genguard works
1. What this repository is
- GenGuard is a Chrome Manifest V3 browser extension that runs entirely on-device.
- Its purpose is to detect PII/confidential data before the user submits text into GenAI sites such as ChatGPT and Gemini.
- The architecture is centered on local inference and local browser integration, not a backend service.
2. High-level extension shape
- The repo splits into three main extension surfaces:
- Content scripts in src/content-scripts that attach to target pages.
- Background/service worker logic in src/background/service-worker.ts for extension-wide orchestration.
- Side panel UI in src/sidepanel for user controls, scoring thresholds, and status.
- src/App.tsx / src/main.tsx and src/sidepanel/* indicate React-based UI entry points, while Vite builds the extension bundle.
3. User-facing runtime flow
- The likely primary flow is: user types into a GenAI prompt box → content script observes/reads the text → core detection pipeline scores and annotates it → highlights/redactions are shown inline.
- The side panel acts as the control plane: enabling/disabling protection, adjusting risk thresholds, and viewing state/history.
- The background service worker is the extension coordinator, handling MV3 lifecycle constraints and shared Chrome API interactions.
4. Page integration boundary
- src/content-scripts/chatgpt-injector.ts and src/content-scripts/gemini-injector.ts show site-specific integration points.
- src/content-scripts/inline-highlighter.ts suggests a UI overlay layer for marking detected spans directly inside text inputs or prompt editors.
- These scripts are the boundary between the extension and the host web app DOM, where detection results become visible to the user.
5. Core detection engine
- src/core/engine.ts is the central orchestration layer that probably combines multiple detection strategies into one scan result.
- The engine feeds text through detectors, aggregates findings, and likely produces the risk score and redaction/highlight metadata used by the UI.
- This is the main internal boundary between extension/UI code and the ML/text-analysis subsystem.
6. Detector subsystem
- src/core/detectors contains multiple detection approaches:
- regex-detector.ts for deterministic pattern matching.
- ner-detector.ts for model-based named entity recognition.
- context-scorer.ts for contextual/risk scoring around found entities.
- pii-patterns.json for curated PII patterns.
- ner-model-contract.ts defines the model interface, which keeps the ML runtime decoupled from the rest of the app.
- Architecturally, this is a layered detection stack: fast rules first, then deeper semantic analysis.
7. Model and tokenizer runtime
- src/lib/ort-engine.ts is the bridge to ONNX Runtime Web, which is bundled under public/ort/.
- src/core/tokenizer/sentencepiece-tokenizer.ts is a custom tokenizer implementation in TypeScript, used to keep inference fully local and avoid heavier third-party wrappers.
- src/lib/model-store.ts likely manages loading/caching of model assets from public/models/, and src/core/types.ts defines shared contracts for detections and scan output.
8. OCR and document extraction
- The repository supports non-text inputs through src/core/extractors.
- pdf-extractor.ts indicates PDF text extraction, likely using a bundled PDF worker or browser-side PDF parsing.
- image-ocr.ts and the ocr/ pipeline files (ocr-engine.ts, ocr-pipeline.ts, preprocess/postprocess/CTC decode) show a full offline OCR stack for screenshots or images.
- This means the scan pipeline can ingest text from multiple modalities before it reaches the detectors.
9. Persistence and local history
- src/lib/history-store.ts and src/lib/model-store.ts suggest browser-local persistence for scan history, state, and model availability.
- Given the zero-knowledge design, persistence is expected to stay inside browser storage rather than any remote database.
- The extension likely uses Chrome storage APIs to remember user settings, thresholds, and recent scan outcomes.
10. Operational model and security boundary
- The README emphasizes that no user content leaves the browser unless explicitly permitted.
- There are no cloud APIs, telemetry pipelines, or server-side components in the tree, which is a major architectural constraint.
- The security boundary is therefore local-only: host page DOM input → extension scripts → local ML/rule engine → local UI feedback.
11. Build and packaging
- The project uses TypeScript + React + Vite with Chrome extension packaging under MV3.
- public/ort/* contains prebuilt ONNX Runtime WASM artifacts, and manifest.json defines the extension runtime contract.
- package.json, vite.config.ts, and the separate sidepanel/index.html point to a multi-entry build that produces the extension bundle in dist/.
12. Key architectural diagram anchors
- Draw the main external boundary as “Chrome browser / target GenAI pages.”
- Inside the extension, show three zones: content scripts, service worker, and side panel UI.
- Connect them to the shared core pipeline (engine, detectors, OCR, tokenizer, ONNX runtime).
- Add local persistence for settings/history and local model assets as separate on-device storage layers.
Main entry points: engine.ts Scan engine · ner-detector.ts NER detector · service-worker.ts Service worker · chatgpt-injector.ts ChatGPT hook
Components 22
Browser boundary
Host pages and Chrome runtime surfaces the extension interacts with
- GenAI pages · Target sites where user prompt text is entered and inspected
Extension surfaces
Manifest V3 entry points and UI surfaces inside the extension
- ChatGPT hook · Site-specific integration for ChatGPT prompt areas
src/content-scripts/chatgpt-injector.ts - Gemini hook · Site-specific integration for Gemini prompt areas
src/content-scripts/gemini-injector.ts - Inline marks · Renders detected spans and redactions inside page editors
src/content-scripts/inline-highlighter.ts - Service worker · Extension-wide coordination and Chrome API boundary
src/background/service-worker.ts - Side panel · User-facing controls for protection state and thresholds
src/sidepanel/App.tsx - Panel entry · Side panel runtime entry point
src/sidepanel/main.tsx - App entry · Main extension UI entry point for shared React rendering
src/main.tsx
Core pipeline
Shared scanning, detection, and extraction logic
- Scan engine · Coordinates extraction, detection, and scoring
src/core/engine.ts - Regex rules · Deterministic PII pattern matching
src/core/detectors/regex-detector.ts - NER detector · Named-entity detection backed by a local model contract
src/core/detectors/ner-detector.ts - Context score · Adds surrounding-text risk weighting and confidence
src/core/detectors/context-scorer.ts - OCR pipeline · Preprocesses, decodes, and postprocesses image text extraction
src/core/extractors/ocr/ocr-pipeline.ts - PDF extractor · Extracts text from PDF documents before scanning
src/core/extractors/pdf-extractor.ts - Tokenizer · Local tokenization used by model-based inference
src/core/tokenizer/sentencepiece-tokenizer.ts
Local assets
On-device persistence and bundled model/runtime assets
- ORT bridge · Connects the app to ONNX Runtime Web execution
src/lib/ort-engine.ts - Model store · Loads and caches local model assets
src/lib/model-store.ts - History store · Persists settings and scan history in browser storage
src/lib/history-store.ts - Model assets · Bundled local model files used by inference
public - ORT WASM · Prebuilt ONNX Runtime WebAssembly artifacts
public/ort/ort-wasm-simd-threaded.mjs
Build
Top-level packaging and entry configuration
- Manifest · Declares MV3 extension entry points and permissions
manifest.json - Vite config · Builds the multi-entry extension bundle
vite.config.ts
Connections 25
- GenAI pages → ChatGPT hook: injects · Content script attaches to ChatGPT pages
- GenAI pages → Gemini hook: injects · Content script attaches to Gemini pages
- ChatGPT hook → Inline marks: renders · Detected spans are marked inline in the editor
- Gemini hook → Inline marks: renders · Detected spans are marked inline in the editor
- ChatGPT hook → Scan engine: scans text · Observed prompt text is sent into the detection pipeline
- Gemini hook → Scan engine: scans text · Observed prompt text is sent into the detection pipeline
- Service worker → Scan engine: coordinates · Background worker orchestrates shared scan requests and lifecycle
- Side panel → History store: reads state · UI loads saved settings and recent outcomes
- Side panel → Service worker: controls · Panel toggles protection and updates thresholds through the worker
- App entry → Side panel: boots · Shared React entry points into the UI layer
- Scan engine → PDF extractor: extracts · PDF text is normalized before detection
- Scan engine → OCR pipeline: extracts · Image and screenshot text is recovered offline
- Scan engine → Regex rules: applies · Rule-based patterns run as the fast first pass
- Scan engine → NER detector: applies · Model-based entity detection augments rules
- Scan engine → Context score: scores · Findings are reweighted by surrounding context
- NER detector → Tokenizer: tokenizes · NER model input is prepared locally
- NER detector → ORT bridge: runs on · Inference executes through the ONNX Runtime bridge
- ORT bridge → ORT WASM: loads · Runtime assets are loaded from bundled WASM files
- Model store → Model assets: loads · Local model artifacts are fetched from bundled assets
- NER detector → Model store: fetches model · Model lifecycle and caching are mediated through the store
- Service worker → History store: persists · Shared settings and scan history are kept locally
- Manifest → Service worker: declares · MV3 background entry point is registered in the manifest
- Manifest → Panel entry: declares · Side panel entry point is registered in the manifest
- Vite config → App entry: bundles · Build pipeline includes the main extension UI entry
- Vite config → Panel entry: bundles · Build pipeline includes the side panel entry