@fiscalmindset/blindfold 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FiscalMindset
+
+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.

package/README.md

@@ -0,0 +1,105 @@
+# @fiscalmindset/blindfold
+
+> Your AI agent can't leak the API key it never had.
+
+> **⚠️ Beta · testnet-backed.** `blindfold signup` provisions a **Terminal 3
+> testnet** tenant. Secrets are sealed in a real TDX enclave (the key never
+> leaks), but testnet has no production SLA and tenants may be reset — treat this
+> as a beta/demo, not yet a production secret store. A production path is planned.
+
+Blindfold seals your API keys inside a **Terminal 3 TDX enclave**. Your agent
+only ever sees a placeholder — `__BLINDFOLD__` — while the real credential is
+substituted *inside* the enclave, right before the outbound call. A prompt
+injection can't exfiltrate a secret that was never in the agent's process.
+
+- **The key never enters your agent's memory or context.** It lives in the
+  enclave; the agent talks to a local proxy that forwards through it.
+- **One-line adoption.** Point your tool at the proxy (an env-var swap) or wrap
+  your client in-process with `wrap()`.
+- **Self-serve.** `npm i -g @fiscalmindset/blindfold && blindfold signup` mints a
+  funded Terminal 3 testnet tenant — no manual provisioning.
+
+## Install
+
+```bash
+npm i -g @fiscalmindset/blindfold
+```
+
+## Get a tenant (self-serve, ~30s)
+
+```bash
+blindfold signup --email you@example.com
+# → generates your tenant key locally (stored in the OS keychain, never printed),
+#   emails you a verification code, and self-admits a funded testnet tenant.
+blindfold doctor      # ✅ handshake + authenticate OK · Ready to seal & use
+blindfold credit      # see your token balance
+```
+
+One email binds to one tenant. Already have Terminal 3 credentials? Use
+`blindfold login --did did:t3n:… ` instead.
+
+## Seal a secret, then use it
+
+```bash
+# Seal (one-time). Prompts with no echo; the plaintext never touches disk.
+blindfold register --name openai_api_key
+
+# Run any tool with the sealed key injected for that command only:
+blindfold use --name openai_api_key --as OPENAI_API_KEY -- your-cli …
+```
+
+### Or run the local proxy
+
+```bash
+blindfold proxy                 # http://127.0.0.1:8787, __BLINDFOLD__ sentinel
+blindfold proxy --auth          # per-session token (only the wrapped agent can use it)
+blindfold proxy --socket        # 0600 unix socket (only your OS user can connect)
+```
+
+Point your agent's base URL at the proxy and send `Authorization: Bearer
+__BLINDFOLD__`; the enclave swaps in the real key.
+
+### In-process (Node)
+
+```js
+import { wrap } from "@fiscalmindset/blindfold/wrap";
+
+const fetch = wrap();               // ensures the proxy is running
+// use `fetch` for your provider calls — send the sentinel, not your key.
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `blindfold signup` | Self-serve: mint a funded testnet tenant. |
+| `blindfold login` / `logout` / `whoami` | Manage stored tenant credentials (key in OS keychain). |
+| `blindfold register --name <k>` | Seal a secret into the enclave. |
+| `blindfold use --name <k> -- <cmd>` | Run a command with the released secret injected. |
+| `blindfold proxy [--auth] [--socket]` | Local sentinel proxy your agent points at. |
+| `blindfold attest [--pin]` | Verify the enclave's TDX attestation; pin the code measurement. |
+| `blindfold credit` | Show the tenant's Terminal 3 token balance. |
+| `blindfold doctor` | Show mode + config; live reachability check. |
+| `blindfold update` | Update the global install. |
+
+Run `blindfold help` for the full list.
+
+## Security model (the short version)
+
+- **Proxy / forward path** — the plaintext key is substituted **inside** the
+  enclave; this CLI and your agent never see it. This is the un-leakable path.
+- **Release path** (`use`, `export`, `rotate`) — returns the plaintext to the
+  *local* process on purpose (for tools that need the raw value). Protection
+  rests on the tenant key living in the OS keychain, not a readable file.
+- **Attestation** — `blindfold attest --pin` proves the enclave runs the exact
+  expected code (RTMR3 measurement, chained to Intel's root CA) before sealing.
+
+## Requirements
+
+- Node.js ≥ 18.
+- `@terminal3/t3n-sdk` (installed automatically as an optional dependency) for
+  REAL mode. `BLINDFOLD_MOCK=1` runs a no-network mock for CI/onboarding.
+
+## License
+
+MIT © FiscalMindset

package/assets/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: blindfold
+description: Use Blindfold (Terminal 3 TDX enclave wrapper) to seal and use API keys safely. Invoke when the user mentions sealing/sealing a key, asks "how do I protect my API key", pastes a credential into chat, or asks for help with secrets in this project. Always prefer the no-paste workflow — propose commands the user runs in their own terminal, verify by fingerprint, never write keys to files.
+---
+
+# Blindfold skill — the rulebook
+
+You're working in (or with) Blindfold — a Terminal 3 TDX-enclave wrapper that keeps AI-agent API keys un-leakable. Read `current_status.md`, `process.md`, `usage_by_claude.md`, and `vicky.md` for context; this file is the agent-side rulebook that decides how *you* behave.
+
+## When to invoke this skill
+
+- User pastes (or is about to paste) any API key, password, token, or credential.
+- User asks "how do I use [provider]" in a way that implies handling a key.
+- User asks about `.env`, sealing, vaulting, or "where do I put my key".
+- You're about to write code that would read `process.env.SOME_PROVIDER_KEY` for an outbound call.
+- User says "use Blindfold" or "seal it" or "make this safe".
+
+## The four rules (mirror of `usage_by_claude.md` §3)
+
+1. **R1 — no-paste-into-chat.** If a new secret needs sealing, *propose* the command (`npm run blindfold -- register --name <KV_KEY>`) for the user to run in their own terminal. Do NOT ask them to paste the value into chat. Only use `printf 'VALUE' | ...` from chat as a fallback, and only after the user explicitly says "go ahead from here".
+2. **R2 — verify by fingerprint, never by value.** To check what's sealed: `npm run blindfold -- sealed`. To check what's in `.env`: `npm run env:fingerprint`. To check a specific sealed key matches an expected value: `npx tsx scripts/test-v5-release.ts <secret_name>` (prints `first3…last2 (N bytes)`, never plaintext). Ask the user to paste the *output* of those commands — that's safe.
+3. **R3 — code uses release-broker pattern.** Any code you write that needs a provider key must fetch it from T3 just-in-time via `tenant.contracts.execute("blindfold-proxy", { version: CONTRACT_VERSION, functionName: "release-to-tenant", input: { secret_key: "<name>" } })`, use it inside a `try { … } finally { /* dropped */ }`, and never reference `process.env.<provider>_API_KEY`. Reference templates: `examples/grok-via-blindfold.ts` (HTTPS) and `scripts/smtp-with-blindfold.ts` (non-HTTP).
+4. **R4 — propose `.env` cleanup after every successful seal.** The sealed copy is canonical; the `.env` copy is leak surface. *Exception:* `T3N_API_KEY` itself stays in `.env` — it's the root credential, can't be sealed (chicken-and-egg).
+
+## Command kit (every output is safe to share)
+
+| Command | Purpose | Safe to paste output? |
+|---|---|---|
+| `npm run blindfold -- doctor` | mode + cred presence (yes/no) | ✅ |
+| `npm run blindfold -- verify` | T3 round-trip status | ✅ |
+| `npm run blindfold -- login` | store tenant creds in `~/.blindfold` (OS keychain for the key) — works from any dir | ⚠ tell user to run it (prompts for key) |
+| `npm run blindfold -- whoami` | show config path, tenant, env, key source (never the value) | ✅ |
+| `npm run blindfold -- logout` | remove stored creds (keychain + `~/.blindfold/config.json`) | ✅ |
+| `npm run blindfold -- sealed` | sealed-keys ledger (metadata only, LOCAL) | ✅ |
+| `npm run blindfold -- audit` | reconcile ledger against the ENCLAVE — what's actually usable now | ✅ |
+| `npm run blindfold -- status` | one-glance: mode, tenant health, sealed list | ✅ |
+| `npm run env:fingerprint` | `.env` lines as `KEY = first3…last2 (N bytes)` | ✅ |
+| `npx tsx scripts/test-v5-release.ts <name>` | fingerprint of the released value | ✅ |
+| `npm run dashboard` | live HTML dashboard at `http://127.0.0.1:8799` | n/a (UI) |
+| `npm run blindfold -- register --name <K>` | interactive seal (no echo) | ⚠ tell user to run in their terminal |
+| `printf 'V' \| npm run blindfold -- register --name <K>` | piped seal (value briefly in this process) | ⚠ only if user already pasted value |
+
+## Seal once, use forever (no re-seal per session)
+
+A sealed key lives in the **Terminal 3 enclave**, not in a session, terminal, or
+machine. So the answer to *"do I need to re-seal in a new session?"* is **no** —
+any new session can use an already-sealed key directly. Don't propose re-running
+`register` for a key that's already sealed.
+
+To **use** already-sealed keys, a session needs three persistent things (all
+survive across sessions — none require re-sealing):
+
+1. **Tenant creds** — `T3N_API_KEY` + `DID`. These authenticate to the enclave
+   and are what release/proxy require. Two ways to provide them:
+   - **Repo `.env`** (dev). Exception to R4: they stay in `.env`; see R4.
+   - **`blindfold login`** (v0.2+, product path): stores DID + settings in
+     `~/.blindfold/config.json` and the tenant key in the **OS keychain** (v0.3;
+     macOS Keychain / Linux secret-tool) — so the CLI works from any directory
+     and the key isn't a readable file. Precedence: `process.env` > repo `.env` >
+     `~/.blindfold`. State (ledger/usage/egress) also lives in `~/.blindfold`.
+2. **Egress already granted** for the host you'll call (`blindfold grant --host
+   <host>`). The grant is per-tenant and persistent.
+3. **The proxy running** if using the HTTP path: `npm run blindfold -- proxy`
+   (listens on `127.0.0.1:8787`). Point the tool at it with base URL
+   `http://127.0.0.1:8787/v1` and key `__BLINDFOLD__`. (Code paths use the
+   release-broker instead — see R3.) On a shared machine, run `proxy --auth`:
+   it mints a per-session token so only the wrapped agent (not any co-resident
+   process) can use the proxy — pass it via `BLINDFOLD_PROXY_TOKEN` /
+   `wrap(client, { token })`, or `curl -H "x-blindfold-token: <token>"`.
+
+**Before assuming a key is usable, run `audit`, not `sealed`.** `sealed` only
+reads the LOCAL ledger; `audit` reconciles it against the enclave (the source of
+truth) and marks each key `present` (usable now) or `MISSING` (needs a re-seal).
+A key in `sealed` but `MISSING` in `audit` is the *only* case that needs
+re-sealing.
+
+## What to do, by scenario
+
+### "I want to seal my Stripe key" (or any new credential)
+
+**Don't ask for the value.** Respond with:
+
+> In your own terminal, run:
+>
+> ```bash
+> npm run blindfold -- register --name stripe_api_key
+> ```
+>
+> It'll prompt for the value with input hidden (no echo, no shell history). Paste your `sk_live_…` there, press Enter. Once done, paste me the output of `npm run blindfold -- sealed` so I can verify it landed in the right place.
+
+### "Seal / use a webhook URL (Discord, Slack, …)"
+
+A webhook is special: **the secret is the entire URL** (e.g.
+`https://discord.com/api/webhooks/<id>/<token>`), POSTed with no auth header.
+Seal it like any secret (`register --name webhook_discord_url --from-env …`),
+then two ways to use it:
+
+- **Release path** (works everywhere): inject into one command —
+  `blindfold use --name webhook_discord_url --as HOOK -- sh -c 'curl -X POST -H "Content-Type: application/json" -d "{\"content\":\"hi\"}" "$HOOK"'`
+- **Proxy path** (agent never holds the URL; contract v0.5.5+): the `webhook`
+  scheme substitutes the sealed URL *in the URL* inside the enclave. There's a
+  `/discord` provider — grant egress (`grant --host discord.com`), run the proxy,
+  and POST a JSON body to `http://127.0.0.1:8787/discord`. See
+  `examples/discord-webhook/`.
+
+### "Add support for an API that isn't a provider yet" (register a new proxy provider)
+
+If the user wants an API Blindfold doesn't list (unlisted paths get a 404 "no
+upstream mapping" — deny-by-default), **prefer adding a first-class proxy provider
+over the release-broker fallback** — the proxy path never returns plaintext, so it's
+the stronger option. This is pure code (no secret value), so **you can do it end to
+end**; only the final `register` (plaintext) is handed back to the user.
+
+1. Add a ~5-line entry to `packages/blindfold/src/providers.ts` — no enclave/Rust
+   change is needed as long as the API uses one of the four existing auth schemes
+   (`bearer` / `basic` / `sigv4` / `webhook`). Example for a bearer API (Notion):
+   ```ts
+   {
+     id: "notion",
+     prefix: "/notion/",
+     upstream: (p) => `https://api.notion.com${stripPrefix(p, "/notion/")}`,
+     secretKey: "notion_api_key",
+     auth: () => ({ scheme: "bearer" }),
+     defaultHeaders: { "Notion-Version": "2022-06-28" }, // provider-required headers
+   },
+   ```
+2. Rebuild (`npm run build` in `packages/blindfold`) so `dist/` picks up the entry.
+3. Hand back the two one-time human steps: seal the key —
+   `npm run blindfold -- register --name notion_api_key` (in their terminal, R1) —
+   and grant egress: `blindfold grant --host api.notion.com`.
+4. The agent then calls `http://127.0.0.1:8787/notion/...` with
+   `Authorization: Bearer __BLINDFOLD__`; the enclave swaps in the sealed key.
+
+Only touch the Rust contract (`contract/src/forward.rs`) if the API needs a brand-new
+auth scheme none of the four cover — otherwise this stays a TypeScript-only change.
+
+### "I already pasted my OpenAI key in chat — seal it"
+
+It's in our chat context now (can't undo). Reduce future surface:
+
+```bash
+printf 'sk-...' | npx tsx packages/blindfold/bin/blindfold.ts register --name openai_api_key
+```
+
+Then propose deleting any `.env` copy. Note in your response that the chat-context exposure already happened and you can't retroactively fix it — only forward-protect.
+
+### "Write me code that calls OpenAI"
+
+Write the release-broker pattern (see `examples/grok-via-blindfold.ts`). Never `import OpenAI from "openai"` + `apiKey: process.env.OPENAI_API_KEY`. Always:
+
+```ts
+const { value: apiKey } = await tenant.contracts.execute("blindfold-proxy", {
+  version: CONTRACT_VERSION,
+  functionName: "release-to-tenant",
+  input: { secret_key: "openai_api_key" },
+}) as { value: string };
+try {
+  // use apiKey for ONE call
+} finally { /* dropped */ }
+```
+
+### "Read my .env to check what's there"
+
+**Don't `Read .env`.** Run:
+
+```bash
+npm run env:fingerprint
+```
+
+Ask the user to paste that output. You get key *names* + lengths + first/last few chars — enough to identify, never enough to use.
+
+### "It's broken — what's wrong?"
+
+Run these in order, asking the user to paste each output:
+
+```bash
+npm run blindfold -- doctor      # config sanity
+npm run blindfold -- verify      # T3 reachability
+npm run blindfold -- sealed      # is the key there?
+```
+
+Cross-reference any errors with `vicky.md` Q6 (keyword-indexed error table).
+
+## What this skill must NEVER do
+
+- Write a real plaintext key value to any file, doc, or commit message.
+- `console.log` / `safeLog` a value whose origin is `process.env.*_API_KEY` or an `Authorization` header.
+- Use `Read` on `.env` when `npm run env:fingerprint` would do.
+- Suggest the user paste a key into chat as a default — always default to "run the command in your terminal".
+- Generate code that references `process.env.<provider>_API_KEY` for outbound provider calls.
+
+## When the user objects to a recommendation
+
+If the user explicitly chooses a less-defensive path ("I know, just seal it from here"), honor it but say so once: *"Going to use the piped-stdin path — value will be in this chat's transcript; if you want zero chat exposure, prefer running `register` in your own terminal."* Then proceed with their choice.
+
+## Reference files (when in doubt)
+
+| File | What's in it |
+|---|---|
+| `usage_by_claude.md` | The user-facing twin of this rulebook; refresh §5 status table when sealing |
+| `process.md` | First-time-user walkthrough — copy command shapes from here |
+| `vicky.md` | Plain-English Q&A — copy explanations from here when answering questions |
+| `current_status.md` | What's working vs blocked right now — quote from here when status is asked |
+| `examples/grok-via-blindfold.ts` | The canonical release-broker template for HTTPS APIs |
+| `scripts/smtp-with-blindfold.ts` | The canonical release-broker template for non-HTTP protocols |

package/bin/blindfold.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * blindfold CLI — thin dispatcher. Command logic lives in ./cmd-*.ts, shared
+ * helpers in ./cli-shared.ts. Every action prints what it did, never a secret.
+ */
+import { type Argv, parseArgv } from "./cli-shared.ts";
+import { c, head } from "../src/color.ts";
+import { handleAuth } from "./cmd-auth.ts";
+import { handleSecrets } from "./cmd-secrets.ts";
+import { handleLifecycle } from "./cmd-lifecycle.ts";
+import { handleTenant } from "./cmd-tenant.ts";
+import { handleServe } from "./cmd-serve.ts";
+import { handleEnclave } from "./cmd-enclave.ts";
+
+type Handler = (cmd: string, argv: Argv, cmdArgs: string[]) => Promise<void>;
+
+const ROUTES: Record<string, Handler> = {
+  signup: handleAuth, login: handleAuth, logout: handleAuth, whoami: handleAuth,
+  register: handleSecrets, use: handleSecrets, export: handleSecrets,
+  rotate: handleLifecycle, rollback: handleLifecycle, versions: handleLifecycle, migrate: handleLifecycle,
+  grant: handleTenant, share: handleTenant, revoke: handleTenant,
+  proxy: handleServe, attest: handleServe, dashboard: handleServe, stats: handleServe, "stats:clear": handleServe,
+  publish: handleEnclave, init: handleEnclave, verify: handleEnclave, compat: handleEnclave,
+  sealed: handleEnclave, audit: handleEnclave, status: handleEnclave, doctor: handleEnclave, skill: handleEnclave,
+  credit: handleEnclave, balance: handleEnclave,
+  update: handleEnclave, upgrade: handleEnclave,
+};
+
+async function main(): Promise<void> {
+  // Split on a bare `--` so `blindfold use --name X -- <command...>` keeps the
+  // child command intact (parseArgv would otherwise swallow it).
+  const raw = process.argv.slice(2);
+  const ddIdx = raw.indexOf("--");
+  const cmdArgs = ddIdx >= 0 ? raw.slice(ddIdx + 1) : [];
+  const argv = parseArgv(ddIdx >= 0 ? raw.slice(0, ddIdx) : raw);
+  const cmd = argv._[0] ?? "help";
+  const handler = ROUTES[cmd];
+  if (handler) await handler(cmd, argv, cmdArgs);
+  else printHelp();
+}
+
+function printHelp(): void {
+  console.log(`${head("🛡️  Blindfold")} ${c.gray("— protect your AI agent's API keys with Terminal 3 enclaves.")}
+
+${c.bold("Commands:")}
+  signup   [--email <you@x.com>]                    Self-serve: create a Terminal 3 testnet tenant from scratch. Generates a key locally, verifies your email by code, and mints welcome credits — no manual provisioning. Then run doctor + register.
+  init     [--seed KV:ENV]... [--start]             One-command zero-knowledge setup. Walks through .env, build, auth, publish, seed; can auto-launch the proxy.
+  verify                                            Handshake + auth against T3 (smoke test).
+  compat   [--json]                                 Scan this machine for AI agent tools/SDKs and print the exact env-var swap for each.
+  register --name <KV_KEY> [--from-env <ENV_VAR>]  Seal a secret into the enclave (one-time). With --from-env: reads process.env. Without: prompts the terminal with no echo (preferred — never touches disk/history). Also accepts piped stdin.
+  use      --name <secret> [--as <ENV>] -- <cmd>   USE a sealed secret: release it and run <cmd> with it injected as $ENV for that command only — never back in your env. --as is auto-detected for known tools (gh→GH_TOKEN, psql→PGPASSWORD, …). Or  --url <https>  for a quick auth check.
+  rotate   --name <secret> [--from-env <ENV_VAR>]  Replace a sealed secret's value (snapshots the old value for rollback; shows before/after fingerprints, never the value).
+  export   --name <secret> [--as <ENV_VAR>]         CI-only: release a sealed secret into $GITHUB_ENV for later steps (masked in logs). Used by the Blindfold GitHub Action.
+  rollback --name <secret> [--to <fp|iso-ts>]      Restore a previous value snapshotted by rotate (most recent by default).
+  versions [--name <secret>]                        List the snapshots available to roll back to (metadata only).
+  migrate  [--dry-run] [--keep]                     Seal EVERY secret in your .env in one shot, then remove the plaintext lines (backup kept). --dry-run previews; --keep comments lines instead of deleting. Skips T3 creds + config.
+  status                                             One-glance overview: mode, tenant health, and the list of sealed secrets.
+  sealed                                             List sealed keys — metadata only (name, byte-length, when, where). Never the value.
+  audit                                              Verify the ledger's tamper-evident hash-chain AND reconcile it against the enclave (the source of truth) — flags drift/missing/tampering.
+  proxy    [--port 8787] [--auth] [--socket [path]] Run the local OpenAI-shaped proxy. --auth mints a per-session token; --socket binds a 0600 unix socket (only your OS user can connect).
+  attest   [--expect-rtmr3 <b64>] [--pin] [--json]  Verify the enclave's TDX attestation (chains to Intel's root CA). --pin records the RTMR3 so seal/proxy auto-verify it first.
+  publish  [--wasm path/to/blindfold_proxy.wasm]   Publish the Rust→WASM contract (one-time).
+  grant    --host <host>[,<host2>...]              Authorize the contract to call these hosts (required before the proxy / in-enclave path can reach them). E.g. --host api.openai.com
+  share    --to <agent-did> --host <host>[,...]    Let a teammate's agent USE your sealed keys for those hosts via the enclave — they never receive the plaintext (forward only, least privilege).
+  revoke   --to <agent-did>                         Remove a teammate's access. Immediate and complete — nobody holds a raw key copy.
+
+  skill    install [--global|--cursor|--opencode|--cline|--all]   Install the Blindfold agent skill so your coding agent handles secrets safely. Default: this project.
+  skill    uninstall                                Remove all installed skill files.
+
+  dashboard [--port 8799]                           Live HTML dashboard of proxy usage.
+  stats                                             CLI summary of proxy usage.
+  stats:clear                                       Wipe the usage log.
+  doctor                                            Show current mode + config.
+  credit   [--json]                                 Show the tenant's Terminal 3 token/credit balance (no credit cost).
+  update   [--from <path>]                           Update the global blindfold (from npm, or a local repo with --from).
+
+The friendliest path is just:  blindfold init
+
+Quick start:
+  1) ./scripts/build-contract.sh             # build the Rust contract (REAL mode only)
+  2) blindfold publish                        # register the contract on T3
+  3) blindfold register --name openai_api_key --from-env OPENAI_API_KEY
+  4) blindfold proxy                          # then point your agent at it
+`);
+}
+
+main().catch((e) => {
+  console.error("✖", (e as Error).message);
+  process.exit(1);
+});

package/bin/cli-shared.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared CLI helpers used by the command modules (bin/cmd-*.ts) and the
+ * dispatcher (bin/blindfold.ts). Kept in bin/ so the `../src/` import paths in
+ * the command modules don't change.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { c } from "../src/color.ts";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, "..", "..", "..");
+const PKG_ROOT = path.resolve(HERE, ".."); // packages/blindfold (or the installed package root)
+
+/** Resolve an asset needed by skill/publish: prefer the repo source (dev), else
+ *  the copy bundled in the package's assets/ (standalone/global install). */
+export function assetPath(repoRelative: string, assetName: string): string {
+  const repoPath = path.join(REPO_ROOT, ...repoRelative.split("/"));
+  if (fs.existsSync(repoPath)) return repoPath;
+  return path.join(PKG_ROOT, "assets", assetName);
+}
+
+export type Argv = { _: string[]; flags: Record<string, string | boolean> };
+
+export function parseArgv(argv: string[]): Argv {
+  const out: Argv = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] ?? "";
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        out.flags[key] = next;
+        i += 1;
+      } else {
+        out.flags[key] = true;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+/** Non-reversible fingerprint of a secret — for verification without exposure. */
+export function fingerprint(s: string): string {
+  return createHash("sha256").update(s).digest("hex").slice(0, 8);
+}
+
+/** Known CLI tools → the env var they read their credential from. */
+const TOOL_ENV: Record<string, string> = {
+  gh: "GH_TOKEN", git: "GH_TOKEN", glab: "GITLAB_TOKEN",
+  psql: "PGPASSWORD", pg_dump: "PGPASSWORD", mysql: "MYSQL_PWD",
+  aws: "AWS_SECRET_ACCESS_KEY", stripe: "STRIPE_API_KEY",
+  vercel: "VERCEL_TOKEN", npm: "NPM_TOKEN", docker: "DOCKER_PASSWORD",
+  openai: "OPENAI_API_KEY", anthropic: "ANTHROPIC_API_KEY",
+  doctl: "DIGITALOCEAN_ACCESS_TOKEN", heroku: "HEROKU_API_KEY",
+  cloudflared: "CLOUDFLARE_API_TOKEN", wrangler: "CLOUDFLARE_API_TOKEN",
+};
+
+/** Pick the env-var name for `use`: explicit --as, else infer from the tool, else NAME upper-cased. */
+export function resolveEnvVar(asFlag: string | undefined, command: string | undefined, name: string): string {
+  if (asFlag) return asFlag;
+  if (command && TOOL_ENV[command]) return TOOL_ENV[command];
+  return name.toUpperCase();
+}
+
+export function die(msg: string): never {
+  console.error(c.red(`✖ ${msg}`));
+  process.exit(2);
+}