omna-plugin 0.6.3__tar.gz

omna_plugin-0.6.3/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+
+# PyInstaller work directory (dist/ is already ignored above).
+build/
+.DS_Store

omna_plugin-0.6.3/.python-version

@@ -0,0 +1 @@
+3.12

omna_plugin-0.6.3/CLAUDE.md

@@ -0,0 +1,74 @@
+# omna-plugin/CLAUDE.md
+
+## What this repo is
+Product #4 of Omna: **the plugin** — ONE command that masks everything an AI sees from this machine and will replace the Mac app. The Chrome extension STAYS alongside it (owner decision 2026-10-18 — never plan an extension sunset). This repo is Stage 1 (the mail-room proxy + coding tools via base URL); Stages 1b–5 (report, Mac system proxy + certificate via mitmproxy, VPN extension, Windows/Linux, Mac-app sunset) are in the Product Spec §6. Thin Python shell
+(`src/omna_plugin/`) over the compiled `omna-pii-mask` engine wheel (built from the private
+`omna-workspace/bindings/omna-core-py`; never copy engine code here). Strategy and the blueprint live in
+`~/Developer/Omna Labs/Omna Notes/:Vision/Omna Plugin — Product Spec.md` §6. Plans: Stage 1 =
+`docs/superpowers/plans/2026-09-17-product-4-plugin.md` (done); **Stages 2+3 =
+`docs/superpowers/plans/2026-09-17-stage-2-3-mac-coverage.md`** (the architecture decisions with their
+reasons are Product Spec §6.9 — read it before touching Stage 2/3 code).
+
+## Stage 2/3 shape (decided 2026-09-17): three doors, one mail room
+- **Mail room** = `pipeline.py` (mask → forward → restore → receipt). Every door calls it; one `MaskingSession`.
+- **API door** = `proxy.py` on 127.0.0.1:7788 (Stage 1, unchanged; tools use a base URL).
+- **System door** = a `mitmproxy` "regular" listener on 127.0.0.1:7789 behind a macOS PAC that names ONLY
+  AI hostnames (`policy.json`); `allow_hosts` decrypts only those; a local CA "Omna Local Certificate
+  Authority" in `~/.omna/ca` is trusted once (one `sudo` batch, printed before it runs); `launchd` keeps it alive.
+- **Deep door** = `mitmproxy` "local" mode per app name (its signed "Mitmproxy Redirector" network
+  extension; no Swift of ours). Only for apps that ignore the system proxy.
+- **Policy** = `~/.omna/policy.json`: hosts, tools on/off, apps mask/bypass (by process name via `lsof`),
+  deep-capture apps, doors, masking style. A bypass is always receipted. Pinned apps are refused and named
+  in `omna status`. **The menu bar writes this file from ANOTHER process**, so anything it can toggle must be
+  re-read from disk, not captured at start-up — `OmnaAddon._fresh()` (mtime-gated) and `proxy._live_style()`
+  do that for `restore_browser` and `style`. Before 2026-09-21 they did not, and the menu-bar restore toggle
+  silently did nothing until a restart. Everything else (hosts, per-app rules) is fixed when the door starts.
+- **Masking style** = `style.py`, the ONLY place that decides. `style_for_door(door, requested)` for the three
+  doors; `style_for_extension(requested, system_door_on)` for Omna's Chrome extension, which masks inside the
+  browser and reads its answer from `/omna/health`'s `style` field (#143). A realistic fake value cannot
+  survive being masked a second time — it looks like real data to the next masker — so the extension keeps
+  numbered tokens while the system door is on. A refusal is always returned with a printable sentence.
+- `mitmproxy` is a library dependency, used as-is (fork-free). Verified hook/option names are listed at the
+  top of the Stage 2+3 plan; trust that list over memory.
+
+## Token literals: two pieces, always
+Never type a full placeholder token (open bracket, KIND, underscore, digits, close bracket) in any file in
+this repo — write it as two adjacent string pieces, e.g. `"[EMAIL_" "1]"` in Python. A Claude Code
+session that is itself wired to the plugin restores every full token literal into the real value from the
+registry while writing the file (that is the restore-in-tool-calls feature working). On 2026-09-17 this put
+the owner's real e-mail into a plan file; caught before commit. Same trick as the runtime-built fake keys.
+
+## Vocabulary (use these words)
+- Product name: **the plugin**. "Proxy" is the plumbing word for how it works.
+- Masking layers: L1 Deterministic, L2 Secrets, L3 Contextual (the privacy-filter model), L4 Fusion.
+  Fast masking = L1+L2 (default). Smart masking = +L3 (`--smart`).
+- Never say "compliant". Say "masks secrets and PII".
+
+## Rules
+- Tests first; `.venv/bin/pytest -q` must be green before any commit. The proxy tests use an in-process
+  fake upstream (`tests/test_proxy.py`); no network in tests.
+- **Nothing in this repo may send anything to Omna.** The only outbound connection is the user's own
+  request to their own provider. Crashes go to `~/.omna/crashes.jsonl` (`crashlog.py`), masked by the
+  engine before they are written and sent only when the person runs `omna crash --send`. A test reads
+  `crashlog.py`'s own source and fails if `httpx`/`requests`/`socket` ever appear in it — that test is
+  the guard on the product's central claim, so do not weaken it.
+- The dashboard needs the token in `~/.omna/dashboard.token` (#134); CORS is answered only for
+  localhost origins plus `policy.cors_origins` (#137a). Both exist because loopback is not a security
+  boundary — do not "simplify" either back to open.
+- Never log or persist a real value except in `registry.json` (0600, AES-256-GCM via `vault.py`, key in
+  the macOS Keychain; plaintext fallback with a loud `omna status` line where there is no Keychain).
+  Receipts are counts only. Tests must never touch the real Keychain — `tests/conftest.py` forces
+  `OMNA_REGISTRY_ENCRYPTION=off` for the whole suite; opt in with the in-memory fake in `test_vault.py`.
+- Keep the gateway contract: forward `anthropic-beta`/`anthropic-version` verbatim, never reshape the
+  `system` array, never buffer SSE, forward upstream error bodies unmodified, never touch `thinking`,
+  `signature`, `cache_control`, or base64 `data`.
+- Live verification = a nested headless run: `env -u CLAUDECODE ANTHROPIC_BASE_URL=http://127.0.0.1:7788
+  claude -p "..." --allowedTools Read,Write` with a file containing a fake key; check `omna log`.
+- Claude Code hooks (re-checked live on 2.1.310, 2026-10-25): PostToolUse `updatedToolOutput` DOES replace a
+  tool result before the model sees it (all tools). Typed prompts still CANNOT be rewritten (`updatedPrompt` is
+  gone; UserPromptSubmit can only block or add context). Hooks = optional second layer, never the main door.
+
+## Publishing (owner-manual)
+The public GitHub repo `gaurjin/omna-plugin` already exists (tags up to `v0.5.1` pushed). Releasing a
+new version: `git tag vX.Y.Z && git push origin vX.Y.Z` → update the version pin in `README.md` and
+`install.sh` to match → `uv build && uv publish`. The installer URL in README assumes that repo path.

omna_plugin-0.6.3/Casks/omna.rb

@@ -0,0 +1,46 @@
+cask "omna" do
+  version "0.6.2"
+  sha256 "19e7a44651c56af66ee43837416ae3118a30a3f38444dcde7edea3a7af891cc1"
+
+  url "https://github.com/gaurjin/omna-plugin/releases/download/v#{version}/omna-#{version}-macos-arm64.zip",
+      verified: "github.com/gaurjin/omna-plugin/"
+  name "Omna"
+  desc "Masks secrets and PII before your prompt leaves the machine"
+  homepage "https://omna.dev/"
+
+  # Apple Silicon only, for the same reason the engine has no source
+  # distribution: it ships as an architecture-specific compiled wheel.
+  depends_on arch: :arm64
+  depends_on macos: ">= :ventura"
+
+  binary "omna/omna"
+
+  caveats <<~EOS
+    Wire up your tools (Claude Code, aider, Codex CLI, VS Code, Continue) and,
+    on a Mac, the system proxy + local certificate:
+
+      omna init
+      omna start -d
+      omna status
+
+    "omna init" asks for your password once, and prints every command it will
+    run as administrator before running it.
+
+    To remove Omna completely, run this FIRST:
+
+      omna uninstall
+
+    It un-wires your tools, removes the certificate and system proxy, and
+    deletes the encryption keys from your Keychain. Homebrew cannot reach the
+    Keychain, so "brew uninstall" alone would leave those two keys behind.
+  EOS
+
+  # Everything Omna writes on disk lives in one directory. Verified 2026-09-20:
+  # `brew uninstall --zap` does remove it — but it canNOT remove the two
+  # Keychain items (the registry key and the receipts key), because a zap
+  # stanza only trashes files. Hence the caveat above telling people to run
+  # `omna uninstall` first, which does.
+  zap trash: [
+    "~/.omna",
+  ]
+end

omna_plugin-0.6.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaurav Jain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omna_plugin-0.6.3/PKG-INFO

@@ -0,0 +1,479 @@
+Metadata-Version: 2.5
+Name: omna-plugin
+Version: 0.6.3
+Summary: Omna — local privacy proxy for AI coding tools. Masks secrets and PII before a prompt leaves your machine, restores them in the reply.
+Project-URL: Homepage, https://omna.dev
+Project-URL: Repository, https://github.com/gaurjin/omna-plugin
+Author-email: gaurav <gaurjin@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: aider,anthropic,claude-code,dlp,openai,pii,privacy,proxy,secrets
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Requires-Dist: mitmproxy<13,>=12.2
+Requires-Dist: omna-pii-mask<0.3,>=0.2.10
+Requires-Dist: pillow>=10
+Requires-Dist: pystray<1,>=0.19
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: starlette>=0.38
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Omna — mask secrets and PII before your prompt leaves the machine
+
+A small local proxy for AI coding tools. Point Claude Code, aider, Codex CLI or any
+Anthropic/OpenAI SDK app at `http://127.0.0.1:7788` and every request is masked on
+the way out, sent to the provider with **your own key or login**, and un-masked on
+the way back. The tool never notices. The model never sees the real values.
+
+```
+you type:     "fix the config, SUPPORT_EMAIL=jane.doe@example.com AWS_ACCESS_KEY_ID=AKIA…"
+model sees:   "fix the config, SUPPORT_EMAIL=[EMAIL_1] AWS_ACCESS_KEY_ID=[SECRET_GENERIC_SECRET_1]"
+you get back: "…set SUPPORT_EMAIL to jane.doe@example.com…"   ← restored, streaming, inside tool calls too
+```
+
+- **Secrets** (240 rules: AWS, GitHub, Stripe, OpenAI, Anthropic, database URLs, JWTs, private keys, …) never
+  reach the provider. They become numbered tokens like `[SECRET_AWS_KEY_1]` that live only in the proxy's memory,
+  never on disk, and are put back only in what comes *back* from the model, so when Claude edits the line that
+  holds a key, the edit still matches your file. `--no-restore-secrets` redacts them for good instead.
+- **Personal data** (emails, phones, SSNs and 50 international ID formats with real checksum validation,
+  cards, IBANs, IPs, names) becomes stable tokens: `[EMAIL_1]` is the same address in every request, so
+  prompt caching keeps working.
+- **Nothing is sent to Omna.** The only network destination is the provider you were already using.
+  A local receipt log (counts only, hash-chained) shows what was caught.
+- **16 ms** to mask a 68 KB request — measured, not estimated, on an M5 MacBook Air, and it is on top of a
+  call that already takes seconds. You will not feel it. ([How it was measured](#speed).)
+
+Same compiled engine as the Omna Mac app, browser extension and the `omna` Python library.
+
+## Install (macOS Apple Silicon, Linux x86_64/aarch64)
+
+```sh
+curl -fsSL https://omna.dev/cli/install.sh | bash
+```
+
+That installs the `omna` command (via [uv](https://docs.astral.sh/uv/)), wires Claude Code, and starts the
+proxy.
+
+### Installing without piping to a shell
+
+Piping a script from the internet straight into a shell means running it before you have read it.
+If that bothers you — and for a privacy tool it reasonably might — **you never have to do it.**
+Every step the installer takes, you can take yourself:
+
+```sh
+# 1. Read the script first, if you want to see what the one-liner does.
+curl -fsSL https://omna.dev/cli/install.sh -o install.sh && less install.sh
+
+# 2. Or skip it entirely — this is all it really does:
+uv tool install --python 3.12 omna-plugin        # or: pipx install omna-plugin
+omna init            # Claude Code: ANTHROPIC_BASE_URL in ~/.claude/settings.json + a SessionStart hook
+omna start -d        # background proxy on 127.0.0.1:7788
+omna status
+```
+
+The installer has no privileged step of its own: it installs `uv` if you do not have it, runs the
+`uv tool install` above, and calls `omna init`. `omna init` is the only part that asks for `sudo`,
+it prints the exact commands before it runs them, and `omna uninstall` reverses all of it.
+
+### Or with Homebrew
+
+```sh
+brew tap gaurjin/omna https://github.com/gaurjin/omna-plugin
+brew install --cask omna
+```
+
+This installs a single self-contained binary — Python, every dependency and the masking engine
+baked in — signed with our Developer ID and notarized by Apple. Two commands rather than one
+because the recipe lives in this repo instead of a separate tap; see
+[docs/homebrew.md](docs/homebrew.md) for why, and [docs/signing.md](docs/signing.md) for how to
+verify the signature yourself.
+
+Run `omna uninstall` **before** `brew uninstall` — Homebrew cannot remove the encryption keys
+Omna stores in your Keychain, and `omna uninstall` does.
+
+`omna init` also wires **aider**, **Codex CLI**, **VS Code** (Copilot Chat and similar chat
+extensions), and **Continue** automatically if each is already installed/configured — nothing is
+added for a tool you don't have. Wire one later, or a tool you didn't have yet: `omna enable aider`
+/ `codex` / `continue`; `omna disable` reverts it. VS Code is Mac-only for now (`omna init`'s Mac
+step); see [omna.dev/help/plugin-supported-tools](https://omna.dev/help/plugin-supported-tools) for
+the full list, including the tools that only offer an in-app setting (Cursor, Cline, Windsurf — one
+line, typed once, inside the tool) and the ones not supported yet, with the real reason why.
+
+On a Mac, `omna init` also does one more thing: it trusts a local certificate ("Omna Local
+Certificate Authority") and points the system proxy at Omna via a PAC file that names only AI
+hostnames, so apps that don't use `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` (a desktop chat app, a
+browser) are masked too — not just Claude Code. That's one `sudo` password prompt, printed before
+it runs. Pass `--no-system` to skip it and wire Claude Code only. `omna uninstall` reverts it.
+
+On a Mac, `omna init` also starts a menu-bar icon (`omna menubar`) showing live status — secrets
+kept off the wire, personal values tokenised, requests masked, what's covered, and masking
+overhead in ms, each on its own line. Its top line is the toggle itself (click, or the native
+checkmark, to pause/resume masking), and it's the only thing Omna adds to System Settings → Login
+Items: the masking proxy has no login item of its own, the menu-bar process supervises it.
+Quitting the icon only stops that one process: relaunch it any time from Spotlight/Launchpad as
+**Omna Plugin** (a small `.app` at `/Applications/Omna Plugin.app`, kept distinct from the native
+Omna Mac app so the two never collide — though it now shares that app's icon, so look for the name
+if you have both installed), or turn on its **Launch at Login** toggle so it comes back on its own
+after every reboot or log-out. Its **Keep Local Reports** toggle turns the receipt log off entirely
+(not just hides it) for anyone who doesn't want even anonymous counts kept on their machine —
+`omna status`/`omna report`/`omna log` still run, they just have nothing new to show while it's off.
+
+Cursor and Cline only offer an in-app setting (paste `http://127.0.0.1:7788` / `/v1` — see the docs
+link above for the exact menu path). Any custom SDK app uses the same address, by hand:
+
+```sh
+export ANTHROPIC_BASE_URL=http://127.0.0.1:7788   # Anthropic SDK
+export OPENAI_BASE_URL=http://127.0.0.1:7788/v1   # OpenAI SDK, Cursor BYOK
+```
+
+## What is covered
+
+| Surface | How | Turn it off |
+|---|---|---|
+| Claude Code, aider, Codex CLI, VS Code, Continue | wired automatically by `omna init` (each only if already installed) | `omna disable claude-code` / `aider` / `codex` / `continue` |
+| Cursor, Cline, Windsurf | one in-app setting, typed once — [full instructions](https://omna.dev/help/plugin-supported-tools) | unset it in the tool |
+| Custom SDK apps | `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` set by hand | unset the env var |
+| Browsers (claude.ai, chatgpt.com, gemini, … — a named list, not every site; add your own with `omna hosts add SITE`) | the system proxy (PAC + a local certificate), set up by `omna init` on a Mac | `omna hosts remove SITE` for one site, `omna init --no-system` or `omna uninstall` for all of them |
+| Desktop AI apps that honour the system proxy | same system proxy as browsers | same as above |
+| Desktop apps that ignore the system proxy | `omna capture app NAME` (Stage 3, per app, its own signed network extension) | `omna bypass app NAME` (stops masking; there's no command yet to release the app from capture itself) |
+| Any specific app, at any layer | `omna bypass app NAME` — tunnelled through untouched, still receipted | `omna mask app NAME` |
+
+On a chat website, Omna masks what **you** send (your messages, pastes and files). The site's own
+security checks (Cloudflare's robot check, ChatGPT's anti-abuse check) and its own usage and error
+reports are forwarded byte-for-byte and receipted as `passthrough-security-check` /
+`passthrough-site-report`. Editing them got people signed out of claude.ai, so Omna never does.
+
+**Attached files** are masked inside and stay the same kind of file: text, `.env` and code files,
+Word `.docx`, Excel `.xlsx`, LibreOffice `.odt` / `.ods` and `.rtf` (only the text changes;
+formatting, styles and images are kept). PDFs, old `.doc` / `.xls`, PowerPoint and images cannot be
+masked in place by a network proxy, so they go as they are and `omna log` says
+`file NOT masked (pdf)`. (Omna's Chrome extension masks PDFs and screenshots on the AI websites.)
+
+It makes no difference how a file or text gets into the chat box — the + button, drag and drop,
+or a paste (some sites turn a long paste into a file) — and Perplexity's uploads to its own Amazon
+storage are covered too. A value Omna finds once is masked everywhere it appears in that message.
+
+## Try it in 30 seconds
+
+```sh
+omna mask "email jane.doe@example.com, key AKIAIOSFODNN7EXAMPLE, phone 212-555-0199"
+# email [EMAIL_1], key [SECRET_AWS_KEY_1], phone [PHONE_1]
+
+omna mask --realistic "email jane.doe@example.com, key AKIAIOSFODNN7EXAMPLE, phone 212-555-0199"
+# email robert.jones@example.org, key [SECRET_AWS_KEY_N], phone 415-555-0128
+#  ...the key stays a label on purpose. See "Two masking styles" below.
+
+omna log         # one line per request: time, route, status, ms, what was masked (or "file NOT masked")
+omna log --verify
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `omna start [-d] [--smart] [--no-restore-secrets]` | Run the proxy (foreground, or `-d` in the background). `--smart` adds the on-device Contextual model for prose names (809 MB download once, slower). |
+| `omna stop` / `omna ensure` | Stop the background proxy / start it if it is not running (the Claude Code hook calls this). |
+| `omna status` | Running? Claude Code wired? Receipts today. |
+| `omna menubar` | Mac status icon (starts automatically): click the top line to pause/resume, see live counts (secrets kept off the wire, personal values tokenised, requests masked, coverage, masking overhead), toggle Launch at Login, Keep Local Reports, **Restore Real Values in Browser** or **Use Realistic Fake Values in Browser**, or uninstall. Both take effect on the next request — no restart. |
+| `omna log [-n 20] [--verify] [--json]` | Local receipts. `--verify` checks the hash chain. |
+| `omna report [--days 7] [--json] [--html FILE]` | Weekly summary from the receipts: requests enabled, distinct secrets kept off the wire, PII tokenised, destinations, chain status, masking cost. |
+| `omna report --export FILE` | Write a **counts-only** copy of that report, safe to hand to a company admin — numbers plus your org/department tags. No prompt text, no real values, no usernames, no file paths, no app names. |
+| `omna report --merge FILE...` | Add up exported files into one company view plus a per-department view. A machine whose file is collected twice is counted once. |
+| `omna enroll [--org NAME] [--dept NAME] [--forget]` | Tag this machine so its exports can be grouped. With no arguments, shows the current tags. Nothing is sent anywhere — see below. |
+| `omna mask [TEXT or -]` | Mask a string or stdin. |
+| `omna style [tokens\|realistic]` | How a masked value is written: a numbered token (the default, every door) or a realistic fake value (your browser only — refused for anything that writes files). Prints what changed and which doors it affects. |
+| `omna allow VALUE` | Never mask this exact value again (false positive). |
+| `omna forget` | Wipe the token registry and its encryption key (tokens renumber). |
+| `omna crash [--show N] [--send] [--clear]` | What broke on this machine. Masked by Omna's own engine before it is written to disk, and **never sent anywhere** — `--send` opens a GitHub issue pre-filled with the report you just read, and you submit it or close the tab. |
+| `omna verify-model` | Re-hash the on-device Contextual model and compare it to the hash this engine was built against. Does the full check every time, never a cached answer. |
+| `omna dashboard` | Open the live dashboard. It is protected by a local token (`~/.omna/dashboard.token`, owner-only), so another program on your machine cannot read your numbers over HTTP. |
+| `omna mappings` | Open the Mappings Review screen — every value Omna has masked, real values hidden until you click Reveal. Same token as the dashboard. |
+| `omna init [--project] [--no-system]` / `omna uninstall` | Wire / un-wire Claude Code, aider, Codex CLI, VS Code and Continue (each only if already installed), and (on a Mac, unless `--no-system`) the system proxy + certificate. `init` backs up every settings file it touches first and removes only its own keys on uninstall. |
+| `omna tools` / `omna enable TOOL` / `omna disable TOOL` | Show, or turn on/off, which tools Omna covers. `enable`/`disable claude-code`, `aider`, `codex`, or `continue` also wire/unwire it (same as `init`/`uninstall`); other tool names (Cursor) just record the policy today. |
+| `omna apps` / `omna bypass app NAME` / `omna mask app NAME` | Show, or set, what happens to an app's traffic through the system proxy: `mask` (default) tokenises it like everything else, `bypass` tunnels it through untouched (still receipted, so you can see what wasn't masked). |
+| `omna capture app NAME` | Stage 3: deep-capture an app that ignores the system proxy, via its own signed network extension. |
+| `omna hosts` / `omna hosts add HOST` / `omna hosts remove HOST` | Show, or add/remove, the hostnames the system proxy treats as AI traffic. |
+
+## Speed
+
+Measured on a MacBook Air M5 with Claude Code 2.1.274, a 4-request task (read a file, write a file, answer):
+
+| | direct | through omna |
+|---|---|---|
+| wall time | 8.8 s | 9.8 s |
+| fast masking, 68 KB request body | | **16 ms** |
+
+Fast masking (rules + checksums, the default) is the 16 ms. Smart masking (`--smart`, which adds the
+on-device Contextual model for prose names) is slower and off by default — it is a deliberate choice you
+make, not a surprise you discover.
+
+`omna status` reports the real average for **your** machine and your traffic
+(`avg_mask_ms_this_run`), so you never have to take this table's word for it.
+
+The proxy relays the stream as it arrives (pings included), forwards `anthropic-beta`, `anthropic-version`,
+`cache_control` and the `system` array untouched, and forwards provider errors unmodified, per Claude Code's
+[gateway compatibility guide](https://code.claude.com/docs/en/llm-gateway-protocol).
+
+## What is stored on your machine
+
+| File (`~/.omna/`) | Contents | Permissions |
+|---|---|---|
+| `registry.json` | token → real value for reversible PII (needed to restore replies). Secrets are never in it; they live in the running proxy's memory only. | 0600 + **encrypted** |
+| `receipts.jsonl` | one hash-chained line per request: route, status, ms, counts per entity. No values. | 0600 |
+| `ruleset.json` | your allowlist and custom patterns (`{"allowlist": [...], "custom_rules": [{"label": "CUSTOMER_ID", "pattern": "ACME-\\d{6}"}]}`). Created with loopback addresses (`127.0.0.1`, `0.0.0.0`, `::1`, `localhost`) allowlisted. | |
+| `proxy.log`, `omna.pid` | background-process housekeeping | |
+| `policy.json` | which tools/apps/hosts are covered, and — only if you ran `omna enroll` — an organisation name, a department name, and a random device id. | 0600 |
+| `crashes.jsonl` | the last 50 crashes: error type, message, stack frames (filenames only), versions. Masked by the engine before it is written, so a value that leaked into an error message is a token here too. Never sent. | 0600 |
+| `dashboard.token` | the local secret the dashboard asks for. | 0600 |
+
+### What Omna sends, and to whom
+
+Nothing, to us. The plugin makes exactly one kind of outbound connection: the request you were
+already making, to the AI provider you were already using, with your own key.
+
+There is no analytics call, no crash reporter phoning home, no licence check, no update ping.
+When something crashes, it is written to `~/.omna/crashes.jsonl` on your machine and stays there —
+`omna crash` shows you the exact bytes, and `omna crash --send` opens a pre-filled GitHub issue
+that **you** submit, or close. That is a deliberate difference from tools that ship an opt-in
+crash reporter: an opt-in promise is something you have to trust, and a file on your disk is
+something you can read.
+
+### Where the real values live, and what protects them
+
+`registry.json` is the only file Omna writes that contains real values, so it is
+the only one that needs more than file permissions.
+
+It is sealed with **AES-256-GCM**. The key is 32 random bytes kept in your
+**macOS Keychain** — never on disk next to the file it opens, and never sent
+anywhere. GCM also authenticates, so a file that someone edited fails to open
+instead of quietly handing back changed mappings.
+
+- `omna status` always tells you which state you are in, in plain words.
+- If your machine has no Keychain (Linux, CI, a headless box), the registry
+  stays as it was before: plaintext at `0600`. Omna says so loudly rather than
+  refusing to run — and on that kind of machine, turn on full-disk encryption.
+- `OMNA_REGISTRY_ENCRYPTION=off` opts out entirely and touches the Keychain not
+  at all.
+- If the key is ever lost, Omna keeps masking but stops writing, so it can never
+  overwrite mappings it cannot read. `omna forget` starts cleanly from scratch.
+- `omna forget` and `omna uninstall` remove the key along with the file.
+
+## Company reports, without a server
+
+A company with 100 laptops does not want 100 separate reports, and Omna does not
+want their prompts. So the rollup is done with files, not a backend:
+
+1. IT tags each machine at install time (or later with `omna enroll`):
+   `curl -fsSL https://omna.dev/cli/install.sh | sh -s -- --org "Acme Inc" --dept engineering`
+2. Each machine writes a counts-only file: `omna report --export machine.json`
+3. Whoever is collecting them runs `omna report --merge *.json` and gets a
+   company total plus a per-department breakdown.
+
+**Nothing is uploaded.** There is no Omna server in this picture at all — the
+files move however that company already moves files. The export is an
+allowlist of number fields, so a new field added to the report later cannot
+quietly start riding along. It deliberately leaves out your home path (which
+carries your username) and which apps you run. The device id is random and
+local; it exists so two files can be told apart and a duplicate can be spotted,
+and `omna enroll --forget` deletes it.
+
+## Two masking styles: numbered tokens, or realistic fake values
+
+Omna can write a masked value in one of two ways. **Numbered tokens are the
+default, everywhere**, and most people never need to change it.
+
+| | what the AI receives | when it suits |
+|---|---|---|
+| **tokens** (default) | `email [EMAIL_N]` | anything that writes files, and anywhere you want a mistake to be obvious |
+| **realistic** | `email robert.jones@example.org` | chat and prose, where ordinary-looking text gets you a better answer |
+
+```sh
+omna style              # what is in force, door by door
+omna style realistic    # switch on realistic values (browser only — see below)
+omna style tokens       # back to the default
+
+omna mask --realistic "email jane.doe@acme.com, key AKIAIOSFODNN7EXAMPLE"
+# email michael.jones63@example.org, key [SECRET_AWS_KEY_N]
+```
+
+### Why both exist, and why the realistic style is refused for coding tools
+
+A numbered token fails **loudly**. If a restore ever breaks, a leftover
+`[EMAIL_N]` sitting in your code is visibly wrong and somebody notices
+immediately.
+
+A realistic fake value fails **silently**. A leftover `robert.jones@example.org`
+looks like ordinary data. Nobody notices, and it gets committed to a repository
+for ever.
+
+So this is a safety trade, not a preference — and Omna decides it for you where
+the stakes are one-sided:
+
+| Door | What it reaches | Realistic values |
+|---|---|---|
+| API door | Claude Code, aider, Codex, Continue, VS Code | **refused** — they all write files |
+| System door | your browser and the chat websites | allowed |
+| Deep door | a named desktop app, captured individually | **refused** — that list can hold an editor |
+| Omna's Chrome extension | the browser, masked before the request leaves it | allowed, unless the system door is also on — see below |
+
+A refusal is never quiet: `omna style realistic` prints which doors kept
+numbered tokens and why, `omna status` shows the style per door, and every
+receipt records which style that request actually used.
+
+### The Chrome extension, and the one case it keeps numbered tokens
+
+If you also run Omna's Chrome extension, it masks inside the browser before the
+request ever leaves it, so it has to be told which style to use. It asks the
+plugin — on the same 60-second check-in it was already making — and does what
+it is told. It never decides for itself: with the plugin not running, or
+answering anything other than "realistic", it uses numbered tokens.
+
+There is one case where the plugin answers "tokens" even though you asked for
+realistic: **while the system door is also on.** Both halves would then mask the
+same browser request, one after the other, and the second pass cannot tell a
+stand-in from real data. A numbered token has brackets, so it is walked straight
+past and comes back to you unchanged. A realistic fake value looks exactly like
+a real e-mail — that is the whole point of it — so it would be masked a second
+time and nothing could put your real value back. `omna style` prints this, in
+those words, on the `browser ext` line.
+
+**Secrets are never given a fake value, under any style.** An API key, a token,
+a password or a private key always becomes a numbered `[SECRET_…]` label. A fake
+API key that looked real is the worst thing this program could hand you.
+
+### What the realistic style guarantees
+
+- **Stability** — the same real value always becomes the same fake value, on
+  every request and after a restart. Otherwise the provider's prompt cache is
+  thrown away and the AI sees the conversation change under it between turns.
+- **Uniqueness** — a generated value is checked against the text being masked
+  and against every real value Omna already knows, and regenerated on a clash,
+  so restoring can never put back the wrong thing. If no unique value can be
+  made, Omna falls back to the numbered token.
+- **Reversibility** — real values come back in replies, in streamed replies and
+  inside tool-call arguments, exactly as they do with tokens.
+- **Nothing invented can belong to anybody** — e-mail addresses use the reserved
+  `example.org` domains, phone numbers the reserved `555-01xx` range, IP
+  addresses the documentation ranges, and Social Security numbers an area
+  number that is never issued. A generated card number is deliberately left
+  failing its checksum: one that passed might be somebody's real card.
+
+## Reviewing what was masked
+
+`omna mappings` opens a screen showing every personal value Omna has masked on
+this machine — behind the same `~/.omna/dashboard.token` as the dashboard,
+never a second password to manage. It shows more than "what was masked":
+which layer caught it (L1 rules, L2 secrets, L3 the contextual model), whether
+a checksum actually validated it, which style it was last written in (tokens
+or realistic — a value masked before the two-style feature existed says
+"unknown", never a guessed default), how many times it has been sent, when
+last, and to which provider and app.
+
+Real values are never on the page until you ask. Each row is hidden by
+default; click **reveal** to fetch just that one, or **reveal all** for every
+row on the current page. Nothing is embedded in the page source ahead of
+time, so a screenshot or a browser extension reading the DOM sees nothing
+until you click. Search, filter by entity type, sort any column, and
+paginate are all built in.
+
+**Secrets never appear here.** They are memory-only from the moment they are
+caught and are never written to the registry — the page says so, rather than
+silently omitting them.
+
+**Delete** removes one mapping — its token, its real value, and its
+realistic-style fake together, so a "deleted" value can't keep resolving
+through the fake path. The same real value gets a brand-new token or fake the
+next time it's seen; the deleted one never comes back. **Clear all** is the
+same as `omna forget` — it also resets your secret counters and your
+encryption key.
+
+## Reading browser replies: real values or labels
+
+**Use Realistic Fake Values in Browser** (menu bar, off by default) is the same
+switch as `omna style realistic`, for people who would rather not open a
+terminal. It changes only how a masked value is WRITTEN, in the browser.
+
+**Restore Real Values in Browser** (menu bar, on by default) decides what you
+read back in a browser reply: the real name, or the `[EMAIL_1]` label that was
+actually sent. **Masking is not affected by it and is never optional** — this
+only changes what comes back.
+
+It is scoped to the browser on purpose. The coding tools always get real values
+put back, because there a label reaching the tool breaks it: Claude Code would
+write `[SECRET_AWS_KEY_1]` into your file instead of editing the real line.
+
+If you also run the Chrome extension, the plugin steps aside and lets the
+extension handle the browser reply. It has to: neither half knows the other's
+list, so whoever restores second could swap in a different person's value. That
+is true of the `[EMAIL_1]` labels, which both sides number independently, and
+worse of realistic fake values, where two generators draw ordinary names out of
+one small pool and the wrong substitution reads as perfectly correct data. The
+extension tags the requests it handles so the plugin knows, per request, to
+leave that reply alone — masking still happens either way.
+
+## What it refuses
+
+A request to an inference path (`/v1/messages`, `/v1/chat/completions`, `/v1/responses`, …) whose body cannot be
+parsed as JSON (compressed, malformed, wrong content type) is answered with `400 omna_refused` and never forwarded.
+Non-inference uploads (`/v1/files`, audio) pass through unmasked and are marked `passthrough` in the receipt.
+If the proxy is not running, the tool's requests fail to connect: nothing leaves unmasked.
+
+## Honest limits (v1)
+
+- A pinned app (one that rejects our certificate on purpose, e.g. it checks the cert fingerprint itself) is
+  refused, never forwarded unmasked, and named: `omna status` shows `refused: AppName → host ×N (pinned)`
+  with the exact `omna bypass app "AppName"` command to let it through untouched instead.
+- If the daemon goes down, what a browser does next depends on whether it already loaded the PAC file: one
+  that hasn't yet falls back to DIRECT (unmasked) until `launchd` restarts the daemon (seconds); one that
+  already cached the proxy address instead fails closed (a connection error, nothing loads) until then. This
+  Mac's `file://` PAC is not honoured by Safari/Chrome, so the PAC itself is served by the proxy — an honest
+  limit either way, not a fail-closed guarantee like the coding-CLI door.
+- Firefox, Node, Python, Java, Ruby and Deno keep their own certificate lists and ignore the macOS
+  keychain, so each needs one line to trust the local certificate — all of them are in
+  [docs/certificate-trust.md](docs/certificate-trust.md). (Firefox: `about:config` →
+  `security.enterprise_roots.enabled` = `true`. Node: `NODE_EXTRA_CA_CERTS`, which `omna init`
+  already sets for VS Code.) Safari, Chrome, Edge, Brave, curl and Go need nothing.
+- Fast masking (rules + checksums) runs by default. Prose names in free text need `--smart`, which loads a
+  local model and slows each request; it is off by default.
+- Windows: no engine wheel yet (WSL works).
+- A tool's own cloud features (for example Cursor tab-completion) never pass through a local proxy.
+- Model thinking blocks are passed through untouched in both directions (the API requires it), so a name the
+  model mentions inside its thinking shows as a token there.
+- Two engine quirks are worked around here and logged upstream: assignment-style secrets keep their variable
+  name outside the token (so `AWS_ACCESS_KEY_ID=[SECRET_GENERIC_SECRET_1]`, not one anonymous token), and a
+  secret span no longer swallows the newline after it. One known false positive remains: prose like
+  "authorization context: something" can be flagged as a generic secret.
+- This masks secrets and PII. It does not make anything "compliant".
+- No exceptions, not even for us: with Claude Code wired to this proxy, Claude reading this
+  README's own demo values (the fake email/AWS key/phone two sections up) sees them as tokens
+  too, same as it would see yours. That's the proxy working as designed, not a bug — it is a
+  side effect worth knowing if you develop this repo with Claude Code pointed at itself.
+
+## Free vs paid
+
+Everything in this repository is free. The paid layer, for teams, is the proof: a signed weekly evidence pack
+built from these receipts, per-machine coverage, and org-wide rulesets. See a sample at
+[omna.dev/sample-report](https://omna.dev/sample-report).
+
+## Development
+
+```sh
+uv venv .venv && uv pip install -p .venv/bin/python -e '.[dev]'
+.venv/bin/pytest -q          # 205 tests, ~7 s (fake upstream, no network)
+.venv/bin/omna start          # foreground, then: ANTHROPIC_BASE_URL=http://127.0.0.1:7788 claude
+```
+
+MIT for this shell. The engine wheel (`omna-pii-mask`) is binary-only.