@redaktyn/cli 0.0.0-stage → 1.5.7

package/LICENSE

@@ -0,0 +1,26 @@
+Redaktyn Software License
+
+Copyright (c) 2026 Redaktyn. All rights reserved.
+
+This software is made available to customers and evaluators of Redaktyn for one purpose: to be installed and run in
+connection with a Redaktyn workspace. No other right is granted.
+
+You may not, and may not allow anyone else to:
+
+  1. copy, modify, translate or create derivative works of the software, except for the copying that running it
+     requires;
+  2. distribute, sell, lease, sublicense, publish or otherwise make the software available to a third party;
+  3. use the software, or anything learned from it, to build, train or improve a product or service that competes with
+     Redaktyn;
+  4. decompile, disassemble, reverse engineer, or otherwise attempt to extract the source code, algorithms, rules or
+     models of the software, except to the extent this restriction is forbidden by applicable law.
+
+Versions of this software published before this license was adopted remain available under the terms they were
+published with. This license applies to this version and to later versions.
+
+The software includes third-party components, each under its own license; for example, @noble/hashes is MIT licensed
+and its notice is kept in the file that contains it.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,630 @@
-# Temporary Holding Version
+# Redaktyn Fingerprint CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate HMAC-SHA256 secret fingerprints **locally on your machine** — nothing ever leaves your computer.
+
+Use this when you want to register a fingerprint for a secret in Redaktyn **without pasting its raw value** into any browser tab or dashboard.
+
+> Looking to **audit** Redaktyn rather than use it? See [`redaktyn-verify.mjs`](#redaktyn-verify--audit-the-claims)
+> below, or the full write-up in the Trust Center in your Redaktyn dashboard.
+
+---
+
+## Why this exists
+
+The Redaktyn **extension enrolment page** (`extension/secrets.html`) computes fingerprints in-browser with the same zero-knowledge guarantee. The dashboard opens that page when you add a secret. This CLI is for when you prefer to:
+
+- Generate fingerprints on an air-gapped machine
+- Automate registration in CI/CD pipelines
+- Audit the exact cryptography before trusting it
+- Never open a browser tab with the raw secret
+
+This CLI is for you.
+
+---
+
+## Requirements
+
+- **Node.js ≥ 18**
+- **`redaktyn-fingerprint.mjs`** — uses only Node.js built-in `crypto` (no npm packages required to run that script)
+- **`redaktyn-import.mjs`** — imports the digest helpers from `redaktyn-fingerprint.mjs` and otherwise uses built-ins only, so it also needs no npm install. Keep the two files together.
+- **`redaktyn-scan.mjs`** — uses the digest code that ships inside this package; there is nothing else to install.
+
+---
+
+## Quickstart
+
+### Interactive wizard (recommended for first-timers)
+
+From the **`cli`** directory (or invoke by path):
+
+```bash
+cd cli
+node redaktyn-fingerprint.mjs
+```
+
+The wizard will guide you through:
+1. Entering your Org ID (from Dashboard → Settings)
+2. Entering your org passphrase (masked input)
+   On a brand-new workspace that has no passphrase yet, one is generated for you, shown once, and recorded with the server once after you type `saved`. A passphrase you type yourself is refused for a new workspace, `REDAKTYN_PASSPHRASE` included (set it to the generated one for later runs). An `import` dry run records nothing and uses a throwaway passphrase. A workspace that already has a passphrase is unchanged: you type it.
+3. Adding one or more secrets (label + value, both masked)
+4. Showing you the exact crypto steps for transparency
+5. Printing copy-ready JSON to paste into the dashboard
+
+### Non-interactive (CI / scripting)
+
+```bash
+# Preferred: passphrase via env var (won't appear in shell history)
+export REDAKTYN_PASSPHRASE="your-org-passphrase"
+
+cd cli && node redaktyn-fingerprint.mjs \
+  --org-id  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
+  --label   "AWS_SECRET_ACCESS_KEY" \
+  --secret  "AKIAIOSFODNN7EXAMPLE..."
+```
+
+### Batch mode (multiple secrets at once)
+
+Create a plain-text file `secrets.txt`:
+
+```
+# Lines starting with # are ignored
+AWS_ACCESS_KEY:AKIAIOSFODNN7EXAMPLE
+DATABASE_PASSWORD:s3cr3tPassw0rd!
+STRIPE_SECRET_KEY:sk_live_abc123xyz
+GITHUB_TOKEN:ghp_xxxxxxxxxxxx
+```
+
+Run:
+
+```bash
+export REDAKTYN_PASSPHRASE="your-org-passphrase"
+
+cd cli && node redaktyn-fingerprint.mjs \
+  --org-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
+  --batch  secrets.txt
+```
+
+Outputs a JSON array — register each digest on Dashboard → **Secrets** (expand **"I already have a fingerprint from the CLI"** and paste, or POST `{ label, hmacHex, length }` via the API). Dashboard bulk import is removed; use this CLI batch mode plus the collapsible import panel or `POST /api/secrets`.
+
+### JSON output (for piping / automation)
+
+```bash
+node cli/redaktyn-fingerprint.mjs --org-id ... --label ... --secret ... --json
+```
+
+Output:
+```json
+{
+  "label": "AWS_SECRET_ACCESS_KEY",
+  "hmacHex": "64-lowercase-hex-chars...",
+  "length": 20
+}
+```
+
+---
+
+## All options
+
+| Flag | Description |
+|------|-------------|
+| `--org-id <uuid>` | Your organization UUID (Dashboard → Settings) |
+| `--label <str>` | Human-readable name, e.g. `AWS_SECRET_KEY` |
+| `--secret <str>` | The raw secret value to fingerprint |
+| `--passphrase <str>` | Org passphrase (**prefer** `REDAKTYN_PASSPHRASE` env var) |
+| `--batch <file>` | Path to a `LABEL:value` file for bulk generation |
+| `--json` | Output pure JSON, no colors or headers |
+| `--no-color` | Disable ANSI colors |
+| `--help` | Show full help |
+
+**Environment variables:**
+
+| Variable | Description |
+|----------|-------------|
+| `REDAKTYN_PASSPHRASE` | Org passphrase — preferred over `--passphrase` flag |
+| `NO_COLOR` | Disable ANSI colors (standard convention) |
+
+---
+
+## How the cryptography works
+
+This tool implements the same algorithm as the Redaktyn extension enrolment page and browser extension detection path, so the digests it produces are interchangeable with theirs.
+
+```
+Step 1 — Key derivation
+  Input:    passphrase (UTF-8) + orgId (UTF-8)
+  Salt:     SHA-256(orgId)          ← org-scoped, no secret leakage
+  KDF:      PBKDF2-SHA256, 600,000 iterations, 256-bit output
+            (KDF version pbkdf2-sha256-600k-v2, matching the browser extension)
+  Output:   32-byte HMAC key
+
+Step 2 — Secret canonicalization
+  • Unicode NFC normalization
+  • CRLF / CR  →  LF
+  • Strip invisible / zero-width characters used in bypass tricks
+  • Trim leading & trailing whitespace
+  • UUID strings: lowercase (case-insensitive matching)
+
+Step 3 — Fingerprint (three variants, all enrolled)
+  hmacHex          HMAC-SHA256(canonical secret, key)
+  hmacHexStripped  same, after removing every Unicode whitespace character
+  hmacHexLower     same as stripped, then lowercased
+
+  Output:   64-character lowercase hex strings  ←  these are stored
+```
+
+The two extra variants exist because a secret is trivially evaded otherwise:
+`Amit@123` enrolled as a single digest is missed the moment someone types
+`A mit@123` or `aMIt@123`. Enrolling only `hmacHex` leaves those gaps open.
+
+**What the server stores:** only the labels, the three digests and their lengths — never the raw secret or the HMAC key.
+
+You can verify this tool against extension-enrolled secrets by registering the same secret both ways and confirming the digests match. `redaktyn-verify recompute` computes the same digests again, independently of this tool.
+
+**LLM providers:** Neither `redaktyn-fingerprint.mjs` nor `redaktyn-scan.mjs` calls an LLM — all digest work is local crypto. Redaktyn deployments may optionally use providers such as **AWS Bedrock** as a fallback LLM on the server for separate AI-assisted features.
+
+---
+
+## Finding your Org ID
+
+1. Log in to the Redaktyn dashboard
+2. Go to **Settings** (sidebar, bottom)
+3. Scroll to **Organization Details**
+4. Copy the UUID shown under "Organization ID"
+
+---
+
+## Importing the fingerprint into the dashboard
+
+After generating the JSON:
+
+1. Dashboard → **Secrets** page
+2. Expand **"I already have a fingerprint from the CLI"** (collapsible panel — not a separate tab)
+3. Paste the JSON output into the smart paste zone
+4. Click **Register fingerprint**
+5. Extensions pick up the new fingerprint on next sync (within ~5 minutes)
+
+---
+
+## Security notes
+
+- **Never pass secrets via `--secret` flag in production** — the value may appear in process listings. Prefer interactive mode or `echo "value" | ...` piped from a password manager.
+- `REDAKTYN_PASSPHRASE` via env is safer than `--passphrase` (not in shell history by default, but visible in `/proc`).
+- For maximum safety: use the interactive wizard on a dedicated machine, then delete shell history.
+- The fingerprint CLI is plain JavaScript. Read it — there are no obfuscated sections.
+
+---
+
+## `redaktyn-connect` and `redaktyn-invite` — a developer who never holds admin credentials
+
+`redaktyn-import` and `redaktyn-scan` normally need an OWNER/ADMIN login token and the workspace
+passphrase. That is the right thing for an admin, and the wrong thing to hand a developer who only has to
+enrol one engagement's secrets. An invite gives them the narrow version instead.
+
+**Admin: mint a single-use link for one project.**
+
+```bash
+redaktyn-login                            # once: email + password, nothing to export or copy
+export REDAKTYN_PASSPHRASE='...'          # or leave it out and you are asked; it stays on this machine
+
+redaktyn-invite --project acme-engagement --can-enrol --expires-days 3
+# -> https://redaktyn.com/connect?code=ABCD1234#w=...
+#    in a terminal it then offers to copy the link; --copy always does, --no-copy never does
+```
+
+The project's scanning key is derived locally and sealed under a one-time key that exists only in the link's
+`#fragment`. The server stores ciphertext it cannot open, and the fragment is never sent to it. `--can-enrol`
+is off unless you ask: without it the link is scan-only. A link carries a key for **one** device, so it works
+once.
+
+**Developer: connect once, then work.**
+
+```bash
+redaktyn-connect                 # prompts for the link, so it stays out of shell history
+redaktyn-import --env .env                 # dry run, no environment variables needed
+redaktyn-import --env .env --apply
+redaktyn-scan --staged                     # also uses the saved key
+redaktyn-connect --status | --logout
+```
+
+What the developer has, and does not have:
+
+| | |
+|---|---|
+| Can | scan, and (with `--can-enrol`) register and re-fingerprint secrets **on that one project** |
+| Cannot | enrol anywhere else, delete or edit a secret, see another project's digests, or reach any admin route |
+| Holds | that project's key only (`HKDF(workspace key, project id)`), never the workspace key or passphrase |
+| Revoked by | an admin removing the device (`DELETE /api/users/:id`): it stops working at once, not when a token expires |
+
+The session lives in `~/.config/redaktyn/session.json` (directory `0700`, file `0600`), the same protection
+`~/.aws/credentials` relies on. It is a file and not the OS keychain on purpose: macOS `security
+add-generic-password` takes the secret as a command-line argument, which any process on the machine can read
+with `ps` while it runs. The token renews itself; if the session cannot be renewed, or an admin removed the
+device, the command says to ask for a new link. An admin's own `REDAKTYN_TOKEN` in the environment always takes
+precedence over a saved session.
+
+**Server note:** `--can-enrol` needs the `InviteEnrolGrant` table. Schema changes here are applied by hand
+(`npx prisma db push`), and an invite minted before that is refused with `ENROL_GRANTS_UNAVAILABLE` rather
+than quietly becoming a plain link.
+
+## `redaktyn-import` — bulk enrollment from files and vaults
+
+Enrollment used to mean typing every secret into the dashboard by hand, so coverage was
+whatever the admin remembered. The values are already sitting somewhere — a dotenv file,
+Vault, AWS Secrets Manager, Doppler, 1Password — and every one of those can already print
+JSON. `redaktyn-import` reads that, computes the digests **on your machine**, and sends
+only digests.
+
+Like `redaktyn-fingerprint`, it needs **no npm install** — Node 18+ and nothing else.
+
+### Quick start
+
+```bash
+redaktyn-login                        # once: your OWNER/ADMIN email and password
+
+# 1. See what it would do. It asks for the workspace passphrase (or read REDAKTYN_PASSPHRASE). This is the default; nothing is written.
+node cli/redaktyn-import.mjs --env .env.production --source prod
+
+# 2. Happy with the plan? Enroll it.
+node cli/redaktyn-import.mjs --env .env.production --source prod --apply
+```
+
+The dry run prints one line per key — the key name, the value's length, and the decision:
+
+```
+KEY                                   LEN  ACTION     WHY
+AWS_SECRET_ACCESS_KEY                  35  CREATE     new
+DATABASE_URL                           52  CREATE     new
+SLACK_WEBHOOK                          77  CREATE     new
+API_BASE_URL                           26  rejected   URL with no embedded credential or token
+NODE_ENV                               10  rejected   only 10 chars (minimum 12)
+PORT                                    4  rejected   only 4 chars (minimum 12)
+────────────────────────────────────────────────────────────────────────────────
+  3 to create · 3 filtered out
+  Scan budget: every paste up to the extension's 5,242,880-char hard limit is scanned.
+
+Dry run — nothing was sent. Re-run with --apply to register.
+```
+
+**Values are never printed** — not truncated, not masked, not even for a rejected key. A
+preview is the thing that gets screenshotted or piped into a CI log.
+
+### Vault recipes
+
+There are no vendor SDKs here and nothing to configure. Every vault CLI can already emit
+JSON, so `--stdin` covers all of them today:
+
+```bash
+# HashiCorp Vault (KV v1 and v2 envelopes are both unwrapped)
+vault kv get -format=json secret/prod | node cli/redaktyn-import.mjs --stdin --source vault
+
+# AWS Secrets Manager
+aws secretsmanager get-secret-value --secret-id prod \
+  --query SecretString --output text | node cli/redaktyn-import.mjs --stdin --source aws
+
+# …or pipe the whole envelope; SecretString is unwrapped for you
+aws secretsmanager get-secret-value --secret-id prod \
+  | node cli/redaktyn-import.mjs --stdin --source aws
+
+# Doppler
+doppler secrets download --no-file --format json \
+  | node cli/redaktyn-import.mjs --stdin --source doppler
+
+# 1Password
+op item get prod --format json | node cli/redaktyn-import.mjs --stdin --source 1password
+
+# GitHub Actions secrets cannot be read back by design — export from wherever they
+# were set, or enroll those with redaktyn-fingerprint.
+```
+
+Plus three file modes: `--env <file>` (dotenv, including `export ` prefixes, quotes,
+comments and multi-line values such as PEM keys), `--json <file>`, and `--yaml <file>`.
+YAML support is a **flat `key: value` subset only** — anything indented or listed is
+refused rather than half-parsed, because a nested document read as flat enrolls digests
+of values that are not the secrets.
+
+### Why this stays zero-knowledge
+
+The CLI runs on the admin's machine, so the vault credential and the plaintext both stay
+there. Reading vaults from the browser instead would be worse on every axis: AWS wants
+SigV4 and sends no CORS headers, Doppler's API cannot be called from a page, and the
+secret would have to pass through a web origin that anything injected into it can script.
+
+```
+On your machine                          │  Sent to the server
+─────────────────────────────────────────┼──────────────────────────────
+vault / .env / Doppler output            │
+  ↓                                      │
+canonicalize (NFC, CRLF→LF, trim, …)     │
+  ↓                                      │
+PBKDF2-SHA256(passphrase, orgId) → key   │
+  ↓                                      │
+HMAC-SHA256 × 3 variants                 │  { label, hmacHex, length,
+  + keyed scan prefilter                 │    hmacHexStripped, lengthStripped,
+                                         │    hmacHexLower, lengthLower,
+                                         │    scanPrefilter,
+                                         │    tags: ["import:prod"] }
+```
+
+The digest pipeline is imported from `redaktyn-fingerprint.mjs` rather than copied, so
+there is exactly one canonical form in this directory. A guard test enforces that.
+
+### What it decides, and what it refuses to decide
+
+Identity is the **key name as the label**, scoped to the tag `import:<source>`. Two
+imports from two vaults therefore never fight over the same row.
+
+| Situation | Action |
+|-----------|--------|
+| Key is not enrolled yet | **CREATE** — `POST /api/secrets` with the `import:<source>` tag |
+| Key is enrolled from this source, value changed | **ROTATE** — `PUT /api/secrets/:id/digest`, same row, same label, same detection history |
+| Key is enrolled from this source, value unchanged | skip — or **ROTATE** once if the stored row lacks a bypass variant or the scan prefilter |
+| This value is already enrolled under another label | skip, and says which label |
+| A secret with this label exists **outside** this source | **CONFLICT** — reported, left alone |
+| A secret from this source is missing from the input | reported, **never removed** |
+
+The last two are deliberate. Rotating a same-label secret would silently take over one
+that was enrolled by hand, and a vault read that fails or returns a subset must not be
+able to cause org-wide loss of protection.
+
+### The junk filter
+
+Vaults contain `PORT=8080`, `NODE_ENV=production` and `DEBUG=true` alongside real secrets.
+Enrolling `production` would end zero false positives in a single import — every paste
+containing the word would be blocked. So values are filtered by default:
+
+- shorter than 12 characters (`--min-length` to change)
+- all digits, booleans, version numbers, email addresses, filesystem paths
+- placeholders such as `changeme`
+- fewer than 5 distinct characters, or very low character diversity
+- URLs with **no** embedded credential and **no** token-shaped path segment
+
+That last rule keeps the URLs that are themselves secrets: a Postgres DSN with an inline
+password and a Slack webhook are both enrolled, while `https://api.example.com/v1` is not.
+
+The filter advises; you decide. `--allow-weak` enrolls the rejects anyway and marks each
+one as weak in the plan, so it cannot be used without seeing what it did.
+
+### The scan budget
+
+Detection slides one pass per distinct secret length, across three normalization passes,
+and past `MAX_SCAN_WINDOWS` the extension **refuses** to scan rather than hang, which is
+a hard block in sensitive contexts.
+
+Every secret this command enrols also carries a **scan prefilter**: three keyed 16-bit
+fingerprints that let the extension skip windows that cannot be that secret before
+signing them. That is what makes a bulk import cheap. Each length still costs a pass, but
+a pass over a fingerprinted length costs about 1/256 of what it used to. Largest paste
+still scanned, with every secret a different length:
+
+| Enrolled secrets | Window lengths | With prefilter (this CLI) | Without (enrolled before 2026-10-07) |
+|------------------|----------------|---------------------------|--------------------------------------|
+| 1                | 3              | 5,242,880 chars (the hard limit) | ~500,000 chars                |
+| 10               | 30             | 5,242,880 chars (the hard limit) | ~50,000 chars                 |
+| 50               | 150            | ~2,550,000 chars          | ~10,000 chars                        |
+| 100              | 300            | ~1,275,000 chars          | ~5,068 chars                         |
+| 200              | 600            | ~637,000 chars            | ~2,618 chars                         |
+
+The figure printed is a **floor**: the size any text of any shape is guaranteed to be
+scanned at, computed with the same arithmetic the extension's admission check uses and
+pinned to it by tests. Ordinary prose usually scans well past it.
+
+A secret enrolled before the prefilter existed has none, and every length it shares keeps
+the old cost. The plan accounts for that. Secrets **in this import** that lack one are
+re-sent once to add it (`rotate — value unchanged; adding missing variants`). Any left
+outside the import are counted, with what re-enrolling them would raise the ceiling to:
+
+```
+  Scan budget: 15 window lengths, pastes up to ~248,570 chars.
+  2 enrolled secrets have no scan prefilter (enrolled before 2026-10-07 or by an older client),
+  so every paste is checked against them the slow way. They are outside this import; re-enrolling them
+  from the dashboard, or importing them, raises this to ~5,242,880 chars.
+```
+
+**Against a server that predates the prefilter**, the CLI notices (its rows carry no
+`scanPrefilter` field, or it refuses the field on the first write) and registers without
+it, so the import still succeeds. Re-run it after the server updates and it adds the
+prefilter to each secret. `--report-json` includes `scanBudget.legacySecrets`,
+`maxPasteCharsIfReenrolled`, `atCharacterCap` and `serverStoresScanPrefilter`.
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--env <file>` | dotenv file |
+| `--json <file>` | JSON object of secrets |
+| `--yaml <file>` | flat `key: value` YAML only |
+| `--stdin` | JSON on stdin — how vault CLIs are consumed |
+| `--source <name>` | Provenance tag, stored as `import:<name>` (default: file name, or `stdin`) |
+| `--apply` | Actually enroll. Without it, dry run. |
+| `--yes` | Skip the confirmation prompt (CI) |
+| `--min-length <n>` | Minimum value length to accept (default 12) |
+| `--allow-weak` | Enroll values the filter rejected |
+| `--only <key\|glob>` | Only these keys (repeatable) |
+| `--exclude <key\|glob>` | Skip these keys (repeatable) |
+| `--server <url>` | Override `REDAKTYN_SERVER_URL` |
+| `--org-id <uuid>` | Override org id (must match the token) |
+| `--project <name\|id>` | Enrol into this project: hashed under the project's own key (HKDF of the org key and the project id) and compared only with that project's secrets. Without it, secrets go to the organisation's default project |
+| `--report-json` | Machine-readable plan, no table |
+| `--no-color` | Disable ANSI colors |
+
+**Signing in.** Run `redaktyn-login` once. It opens your browser on a code, like `gh auth login`: you are already signed in
+to the dashboard, so you check that the code matches the one in the terminal and press Approve. Nothing is typed into the
+terminal, and the token is never in a URL. Over SSH or in a container, `--no-browser` prints the link to open anywhere you are
+signed in. A machine with no browser at all can use `--password` (email and password in the terminal) or `--password-stdin`.
+The login token is kept in a file only you can read, so `redaktyn-import` and `redaktyn-invite` need no `export` for it; the
+password is never stored. Only an OWNER or ADMIN can approve. The server address defaults to `https://redaktyn.com`; only a
+self-hosted install sets `REDAKTYN_SERVER_URL` or `--server`. `redaktyn-login --status` shows who you are, `--logout` forgets
+it. A login that has aged out says so and asks you to log in again.
+
+**What the terminal shows.** On an interactive terminal every command uses one look: a banner, steps that end in a tick, boxed summaries, and for
+secrets a view of what is happening to them. `redaktyn-demo` runs the real fingerprint pipeline offline on a made-up secret (no account needed). On
+a real import the first secret is walked through normalise, key derivation and HMAC, and a box states what would leave the machine (requests, bytes,
+fields) before anything is sent, on a dry run too; `--show-request` prints the first request body exactly as built, digests shortened. The byte count
+is computed from the requests that are then sent, and a test fails if they ever differ. Piped output, CI and `TERM=dumb` get the plain lines scripts
+rely on; `NO_COLOR`, `REDAKTYN_NO_ANIMATION` and `REDAKTYN_ASCII` are honoured. Results (a link, `--report-json`) go to stdout, the display to stderr.
+
+**The passphrase prompt** says who is signed in, what it is asking for and that nothing shows while you type, then checks the answer against the workspace before anything is made from it, so a typo is refused with "try again (2 left)" instead of producing a link or digests that match nothing. Set `REDAKTYN_PASSPHRASE` to skip the prompt; it is checked the same way. A workspace with no stored verifier skips the check.
+
+**Environment** (all optional now): `REDAKTYN_PASSPHRASE` (otherwise you are asked), `REDAKTYN_SERVER_URL`
+(self-hosted only), `REDAKTYN_ORG_ID`, and `REDAKTYN_TOKEN` for scripts.
+
+`REDAKTYN_TOKEN` must be an **OWNER or ADMIN login token**, and when it is set it wins over a saved login.
+`REDAKTYN_DEVICE_TOKEN` is deliberately not accepted: an extension token can read the secret list, so a shell
+set up for `redaktyn-scan` would produce a dry run that looks perfect and then fail on the first write, after
+you had approved the plan. It is rejected up front instead.
+
+**For CI**, where nobody can type a password, mint a token per run and pass it as `REDAKTYN_TOKEN`:
+
+```bash
+export REDAKTYN_TOKEN=$(curl -s -X POST "https://redaktyn.com/api/auth/login" \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"ci@example.com","password":"…"}' | jq -r .token)
+```
+
+> **Correction (2026-10-10):** this section used to say the token could be copied out of a logged-in dashboard
+> (Local Storage → `vaultx_token`). That has not been true since the dashboard session moved to an HttpOnly
+> cookie, which script cannot read. Use `redaktyn-login`, or the call above.
+
+**Exit codes:** `0` plan printed or every write succeeded · `1` one or more writes failed ·
+`2` usage, auth or parse error.
+
+### CI example
+
+```yaml
+- name: Sync enrolled secrets from Doppler
+  env:
+    REDAKTYN_SERVER_URL: ${{ secrets.REDAKTYN_SERVER_URL }}
+    REDAKTYN_PASSPHRASE: ${{ secrets.REDAKTYN_PASSPHRASE }}
+    REDAKTYN_TOKEN:      ${{ secrets.REDAKTYN_ADMIN_TOKEN }}
+  run: |
+    doppler secrets download --no-file --format json \
+      | node cli/redaktyn-import.mjs --stdin --source doppler --apply --yes
+```
+
+---
+
+## `redaktyn-scan` — Pre-Commit & CI/CD Scanner (Zero-Knowledge)
+
+Protect your codebase **before** secrets reach an AI tool. `redaktyn-scan` runs the same
+zero-knowledge HMAC detection as the browser extension, but inside your git workflow and CI pipelines.
+
+### Quick start
+
+Reinstall the package: `npm install -g @redaktyn/cli`, or run a command with `npx -p @redaktyn/cli`.
+
+```bash
+# API base URL — for an EC2 deployment with no custom domain, use the public IP:
+#   export REDAKTYN_SERVER_URL="http://<EC2-PUBLIC-IP>"
+export REDAKTYN_SERVER_URL="https://your-api.example.com"
+export REDAKTYN_PASSPHRASE="your-org-passphrase"
+export REDAKTYN_DEVICE_TOKEN="eyJ…"   # extension JWT from popup → Connect, or admin JWT for CI
+
+# Scan staged changes before committing
+node cli/redaktyn-scan.mjs --staged
+
+# Install permanent git hook (runs automatically on every commit)
+node cli/redaktyn-scan.mjs install-hooks
+
+# Remove the hook
+node cli/redaktyn-scan.mjs uninstall-hooks
+
+# Scan a single file
+node cli/redaktyn-scan.mjs --file ./src/config.ts
+
+# Scan all text files under a directory
+node cli/redaktyn-scan.mjs --dir ./src --exclude "*.min.js"
+
+# Check connection and enrolled secret count
+node cli/redaktyn-scan.mjs status --json
+```
+
+Or from repo root via workspace bin: `npm run redaktyn-scan -- --staged` (passes flags after `--`).
+
+### CI/CD integration (GitHub Actions example)
+
+```yaml
+- name: Redaktyn secret scan
+  env:
+    REDAKTYN_SERVER_URL: ${{ secrets.REDAKTYN_SERVER_URL }}
+    REDAKTYN_PASSPHRASE: ${{ secrets.REDAKTYN_PASSPHRASE }}
+    REDAKTYN_TOKEN:      ${{ secrets.REDAKTYN_TOKEN }}
+  run: |
+    node cli/redaktyn-scan.mjs --staged --json
+```
+
+Exit code `1` when enrolled digests are found in the staged diff — blocks the commit or fails the CI job.
+
+### How it works (zero-knowledge)
+
+1. Derives an HMAC key from your passphrase (PBKDF2-SHA256, 600K iterations, org ID as salt) with the same digest code the browser extension uses, so its digests always match extension-enrolled secrets.
+2. Slides windows of each enrolled secret's length over added lines from the git diff.
+3. Sends **only 64-char hex HMAC digests** to `POST /api/cli/scan` — raw content never leaves your machine.
+4. Server checks digests against enrolled rows and returns label matches.
+
+**Scan flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--staged` | Scan git staged additions (`git diff --cached`) |
+| `--file <path>` | Scan a single file |
+| `--dir <path>` | Scan all text files under directory |
+| `--server <url>` | Override `REDAKTYN_SERVER_URL` |
+| `--org-id <uuid>` | Override org id (must match JWT) |
+| `--json` | JSON output (machine-readable, CI-friendly) |
+| `--verbose` | Extra diagnostic output |
+| `--exclude <pat>` | Skip paths containing pattern (repeatable) |
+| `install-hooks` | Write `.git/hooks/pre-commit` |
+| `uninstall-hooks` | Remove Redaktyn pre-commit hook |
+| `status` | Show connection + enrolled secret count |
+
+**Note:** scans use the primary normalization path. Secrets enrolled with **only** a whitespace-collapsed
+digest may require the browser extension for full bypass-variant parity.
+
+---
+
+## `redaktyn-verify` — audit the claims
+
+Where the other two tools *use* Redaktyn, this one **checks whether Redaktyn is
+telling the truth**. It has no dependencies and no imports from this repo — it
+reimplements the digest pipeline on its own, on purpose, so that agreeing with the extension and the CLI means something. Read it before running it; it is
+one file, and short.
+
+```bash
+curl -o redaktyn-verify.mjs https://your-api.example.com/api/verify/cli
+node redaktyn-verify.mjs --help
+```
+
+From the repo: `npm run verify -- <command>`.
+
+| Command | Checks |
+|---------|--------|
+| `recompute` | Derives the three digests from your own secret and compares them against what `GET /api/secrets` holds |
+| `build` | Hashes the served dashboard bundle and compares it to the Ed25519-signed release manifest |
+| `pin` | Records the current release-log head so a later rewrite is detectable |
+| `check` | Re-fetches the log and verifies your pinned release still reproduces |
+| `egress` | Asserts every field in a captured HAR against the published allowlist |
+
+```bash
+export REDAKTYN_SERVER="https://your-api.example.com"
+
+node redaktyn-verify.mjs recompute --org-id <uuid>     # prompts for passphrase + secret
+node redaktyn-verify.mjs recompute --org-id <uuid> --token <jwt>   # also compare vs server
+node redaktyn-verify.mjs build
+node redaktyn-verify.mjs pin
+node redaktyn-verify.mjs check
+node redaktyn-verify.mjs egress --har capture.har
+```
+
+Every command exits non-zero on failure, so all of them work as CI gates.
+`REDAKTYN_VERIFY_PIN` overrides where the pin is stored, which is what you want
+when the pin should live beside the job doing the checking.
+
+Each command prints what its result does **not** establish. For the reasoning
+behind the split — and the things none of this proves — see
+the Trust Center in your Redaktyn dashboard.
+
+---
+
+## License
+
+MIT — free to use, inspect, fork, and redistribute.