@fiscalmindset/blindfold 0.4.0

package/bin/cmd-auth.ts

@@ -0,0 +1,193 @@
+/** CLI command group (auto-split from the dispatcher; bodies unchanged). */
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { loadBlindfoldEnv, configPath, homeDir, stateDir } from "../src/env.ts";
+import { keychainAvailable, keychainBackend, keychainSet, keychainDelete } from "../src/keychain.ts";
+import { readSecretLine, readLine } from "../src/prompt.ts";
+import { registerSecret, registerContract } from "../src/register.ts";
+import { startProxy } from "../src/proxy.ts";
+import { attest, attestationGate, writePinnedRtmr3 } from "../src/attest.ts";
+import { startDashboard } from "../src/dashboard.ts";
+import { clearUsage, defaultLogPath, readUsage } from "../src/usage-log.ts";
+import { runInit, runVerify } from "../src/init.ts";
+import { runCompat } from "../src/compat.ts";
+import { defaultSealedLogPath, readSealed, verifyLedgerChain } from "../src/sealed-ledger.ts";
+import { type Argv, die, assetPath, fingerprint, resolveEnvVar } from "./cli-shared.ts";
+import { c, head, ok } from "../src/color.ts";
+
+/**
+ * Persist tenant credentials the way `login` does: DID + settings into the
+ * 0600 config file, the tenant key into the OS keychain (or the config file as
+ * a 0600 fallback). Shared by `login` and `signup`.
+ */
+function saveTenantCredentials(
+  did: string,
+  key: string,
+  env: "testnet" | "production",
+  forceFile: boolean,
+): { inKeychain: boolean; triedKeychain: boolean; cfg: string } {
+  const cfg = configPath();
+  let existing: Record<string, string> = {};
+  try { if (fs.existsSync(cfg)) existing = JSON.parse(fs.readFileSync(cfg, "utf8")); } catch { /* overwrite */ }
+  const merged: Record<string, string> = { ...existing, DID: did, BLINDFOLD_T3_ENV: env };
+  const triedKeychain = !forceFile && keychainAvailable();
+  const inKeychain = triedKeychain && keychainSet(did, key);
+  if (inKeychain) {
+    merged.T3N_API_KEY_STORE = "keychain";
+    delete merged.T3N_API_KEY;
+  } else {
+    merged.T3N_API_KEY = key;
+    merged.T3N_API_KEY_STORE = "file";
+  }
+  fs.mkdirSync(homeDir(), { recursive: true });
+  fs.writeFileSync(cfg, JSON.stringify(merged, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(cfg, 0o600); } catch { /* best effort */ }
+  return { inKeychain, triedKeychain, cfg };
+}
+
+export async function handleAuth(cmd: string, argv: Argv, cmdArgs: string[]): Promise<void> {
+  switch (cmd) {
+    case "signup": {
+      // Self-serve provisioning: create a fresh Terminal 3 testnet tenant with
+      // no manual step on the T3 side. Generates a key locally, eth-auths,
+      // proves the email via OTP, and self-admits (mints welcome credits).
+      const env = String(argv.flags.env ?? "").toLowerCase() === "production" ? "production" : "testnet";
+      if (env === "production") {
+        die("signup (self-admit) is testnet-only. Production tenants are provisioned by Terminal 3 directly.");
+      }
+      const email = argv.flags.email
+        ? String(argv.flags.email)
+        : (await readLine("Email for your tenant (a verification code will be sent): ")).trim();
+      if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) die("Enter a valid email address (e.g. you@example.com).");
+
+      console.log(`${head("blindfold signup")} — creating a Terminal 3 ${c.cyan("testnet")} tenant for ${c.cyan(email)}`);
+      console.log(c.dim("  A fresh tenant key (secp256k1) is generated locally and stored in your keychain — never printed.\n"));
+
+      // T3's Level-1 self-admit requires a first + last name on the profile.
+      // Default from the email local part (minus any +tag) so signup stays a
+      // single prompt; --first/--last override.
+      const localPart = (email.split("@")[0] ?? "user").split("+")[0] ?? "user";
+      const firstName = argv.flags.first ? String(argv.flags.first) : (localPart || "Blindfold");
+      const lastName = argv.flags.last ? String(argv.flags.last) : "Tenant";
+
+      const { signupTenant, SignupEmailTakenError } = await import("../src/t3-client.ts");
+      // Allow a non-interactive OTP (for scripted/remote tests): --otp <code>.
+      const presetOtp = argv.flags.otp ? String(argv.flags.otp).trim() : "";
+      // Persisted by onKeyReady the moment the email verifies — captured here so
+      // both the success and the post-verify-failure paths can report where the
+      // key landed (and so a failed admit never strands an unrecoverable key).
+      let saved: { inKeychain: boolean; cfg: string } | null = null;
+      let res;
+      try {
+        res = await signupTenant({
+          env,
+          email,
+          profile: { first_name: firstName, last_name: lastName },
+          onKeyReady: (key, did) => {
+            saved = saveTenantCredentials(did, key, env, Boolean(argv.flags.file));
+          },
+          getOtpCode: async () => {
+            if (presetOtp) return presetOtp;
+            process.stderr.write(c.yellow(`  A verification code was emailed to ${email}.\n`));
+            return (await readLine("  Enter the code: ")).trim();
+          },
+        });
+      } catch (e) {
+        if (e instanceof SignupEmailTakenError) {
+          console.error(c.red(`✖ ${e.message}`));
+          console.error(c.dim("  This email already has a tenant. Either:"));
+          console.error(c.dim(`    • log in with that tenant's key:  blindfold login --did ${e.existingDid}`));
+          console.error(c.dim("    • or sign up with a different email (Gmail '+' aliases work: you+blindfold@gmail.com)."));
+          process.exit(1);
+        }
+        // If the key was already saved (email verified, only the self-admit
+        // failed), the tenant is recoverable — say so instead of implying loss.
+        if (saved) {
+          const s = saved as { inKeychain: boolean; cfg: string };
+          console.error(c.red(`✖ Email verified and tenant key saved, but self-admit failed: ${(e as Error).message}`));
+          console.error(c.dim(`  Your key + DID are stored in ${s.inKeychain ? `the ${keychainBackend()}` : `${s.cfg} (0600)`} — not lost.`));
+          console.error(c.dim("  The tenant just wasn't funded. Check `blindfold credit`, or re-run `blindfold signup` with a fresh email for a new funded tenant."));
+          process.exit(1);
+        }
+        die(`signup failed: ${(e as Error).message}`);
+        return;
+      }
+
+      if (res.admitStatus === "refused") {
+        die(`Terminal 3 refused self-admit (${res.refusedReason ?? "unknown"})${res.refusedDetail ? `: ${res.refusedDetail}` : ""}.`);
+        return;
+      }
+
+      const { inKeychain, cfg } = saved ?? saveTenantCredentials(res.did, res.key, env, Boolean(argv.flags.file));
+      const verb = res.admitStatus === "already-admitted" ? "confirmed (already registered)" : "created";
+      console.log(ok(`\n✓ Tenant ${verb}: ${c.bold(res.did)}`));
+      console.log(`  Tenant key stored in ${inKeychain ? `the ${keychainBackend()}` : `${cfg} (0600)`} — never printed.`);
+      if (res.grantedCredits) {
+        console.log(ok(`  Welcome credits minted: ${res.grantedCredits} base units.`));
+      } else {
+        console.log(c.yellow("  No welcome credits were minted (the testnet dial may be 0). Check `blindfold credit`."));
+      }
+      console.log(`\n  Next:`);
+      console.log(`    ${c.bold("blindfold doctor")}    ${c.dim("# confirm T3 reachability")}`);
+      console.log(`    ${c.bold("blindfold credit")}    ${c.dim("# see your token balance")}`);
+      console.log(`    ${c.bold("blindfold register --name openai_key")}   ${c.dim("# seal your first secret")}`);
+      return;
+    }
+    case "login": {
+      // Store tenant credentials in ~/.blindfold/config.json so the CLI works
+      // from any directory, installed globally, without a repo .env.
+      const did = argv.flags.did
+        ? String(argv.flags.did)
+        : (await readSecretLine("Tenant DID (did:t3n:…): ")).trim();
+      if (!/^did:t3n:[0-9a-fA-F]+$/.test(did)) die('DID must look like "did:t3n:<hex>".');
+      const key = argv.flags.key
+        ? String(argv.flags.key)
+        : (await readSecretLine("T3N_API_KEY (0x…, hidden): ")).trim();
+      if (!/^0x[0-9a-fA-F]{64}$/.test(key)) die("T3N_API_KEY must be a 0x-prefixed 32-byte hex.");
+      const env = String(argv.flags.env ?? "").toLowerCase() === "production" ? "production" : "testnet";
+
+      // Prefer the OS keychain for the tenant key; the config file then holds
+      // only non-secret DID + settings. Fall back to a 0600 file when no
+      // keychain exists OR the keychain write fails (e.g. err 1312 in a
+      // non-interactive session). --file forces the file path.
+      const { inKeychain, triedKeychain, cfg } = saveTenantCredentials(did, key, env, Boolean(argv.flags.file));
+      console.log(`✓ Saved tenant key to ${inKeychain ? `the ${keychainBackend()}` : `${cfg} (mode 0600)`}. Blindfold now works from any directory.`);
+      console.log(`  Tenant: ${did}  ·  env: ${env}  ·  key: stored (never printed)`);
+      if (!inKeychain && !argv.flags.file) {
+        console.log(triedKeychain
+          ? `  (Keychain write unavailable here — stored in a 0600 file. Run \`blindfold login\` in an interactive desktop session to use ${keychainBackend()}.)`
+          : `  (No OS keychain found — stored in a 0600 file. On macOS/Linux/Windows an interactive session uses the OS credential store automatically.)`);
+      }
+      console.log(`  Verify: blindfold doctor`);
+      return;
+    }
+    case "logout": {
+      const cfg = configPath();
+      let did = "";
+      let store = "";
+      try { if (fs.existsSync(cfg)) { const o = JSON.parse(fs.readFileSync(cfg, "utf8")); did = o.DID ?? ""; store = o.T3N_API_KEY_STORE ?? ""; } } catch { /* ignore */ }
+      let removed = false;
+      if (store === "keychain" && did && keychainAvailable()) { if (keychainDelete(did)) { console.log("✓ Removed tenant key from the OS keychain."); removed = true; } }
+      if (fs.existsSync(cfg)) { fs.rmSync(cfg, { force: true }); console.log(`✓ Removed ${cfg}.`); removed = true; }
+      if (!removed) console.log("Nothing to remove — no saved credentials at " + cfg);
+      else console.log("Tenant credentials cleared from this machine.");
+      return;
+    }
+    case "whoami": {
+      const cfg = configPath();
+      let store = "";
+      try { if (fs.existsSync(cfg)) store = (JSON.parse(fs.readFileSync(cfg, "utf8")).T3N_API_KEY_STORE) ?? ""; } catch { /* ignore */ }
+      const env = loadBlindfoldEnv();
+      const keySource = !env.t3nApiKey ? "MISSING"
+        : process.env.T3N_API_KEY && store === "keychain" ? `set (${keychainBackend()})`
+        : store === "file" ? "set (config file, 0600)"
+        : "set (env / repo .env)";
+      console.log(`${c.bold("config:")}  ${c.gray(cfg)}${fs.existsSync(cfg) ? "" : "  (not present)"}`);
+      console.log(`${c.bold("tenant:")}  ${c.cyan(env.did || "(none — run `blindfold login`)")}`);
+      console.log(`${c.bold("env:")}     ${env.t3Env}   ·   key: ${c.green(keySource)}`);
+      return;
+    }
+  }
+}

package/bin/cmd-enclave.ts

@@ -0,0 +1,373 @@
+/** CLI command group (auto-split from the dispatcher; bodies unchanged). */
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { loadBlindfoldEnv, configPath, homeDir, stateDir } from "../src/env.ts";
+import { keychainAvailable, keychainBackend, keychainSet, keychainDelete } from "../src/keychain.ts";
+import { readSecretLine } from "../src/prompt.ts";
+import { registerSecret, registerContract } from "../src/register.ts";
+import { startProxy } from "../src/proxy.ts";
+import { attest, attestationGate, writePinnedRtmr3 } from "../src/attest.ts";
+import { startDashboard } from "../src/dashboard.ts";
+import { clearUsage, defaultLogPath, readUsage } from "../src/usage-log.ts";
+import { runInit, runVerify } from "../src/init.ts";
+import { runCompat } from "../src/compat.ts";
+import { defaultSealedLogPath, readSealed, verifyLedgerChain } from "../src/sealed-ledger.ts";
+import { type Argv, die, assetPath, fingerprint, resolveEnvVar } from "./cli-shared.ts";
+import { c, ok, bad, warn, head } from "../src/color.ts";
+
+export async function handleEnclave(cmd: string, argv: Argv, cmdArgs: string[]): Promise<void> {
+  switch (cmd) {
+    case "credit":
+    case "balance": {
+      // Show the tenant's token/credit balance (a session-authed read that costs
+      // no credit — works even when exhausted). Avoids discovering "0 credits"
+      // only when a seal/forward fails with a 403.
+      const env = loadBlindfoldEnv();
+      const BASE = 1_000_000; // 1 token = 1,000,000 base units
+      const { openT3Client } = await import("../src/t3-client.ts");
+      const client = await openT3Client(env);
+      try {
+        const b = await client.getBalance();
+        const tok = (n: number) => (n / BASE).toLocaleString(undefined, { maximumFractionDigits: 6 });
+        if (argv.flags.json) { console.log(JSON.stringify(b, null, 2)); return; }
+        console.log(head(`💳 Terminal 3 credit`) + c.gray(` — ${env.did || "(no tenant)"}  (${env.mock ? "MOCK" : env.t3Env})`));
+        console.log(`  available:  ${c.bold(tok(b.available) + " tokens")}  ${c.gray("(" + b.available.toLocaleString() + " base units)")}`);
+        console.log(`  reserved:   ${b.reserved.toLocaleString()} base units`);
+        console.log(`  status:     ${b.creditExhausted ? warn("⚠ EXHAUSTED") : ok("✅ ok")}`);
+        if (b.creditExhausted) {
+          console.log(`  Top up testnet credits, then re-check with \`blindfold credit\`:`);
+          console.log(`    https://docs.terminal3.io/developers/adk/get-started/prerequisites/request-test-tokens`);
+          process.exitCode = 1;
+        }
+      } finally {
+        await client.close();
+      }
+      return;
+    }
+
+    case "update":
+    case "upgrade": {
+      // Update the globally-installed blindfold. Prefer the repo SOURCE if one is
+      // reachable (dev). Otherwise fall back to the SCOPED npm package
+      // (@fiscalmindset/blindfold) — never the bare `blindfold` name, which is an
+      // UNRELATED package. Source resolution: --from, BLINDFOLD_SRC, repo at cwd.
+      const PKG = "@fiscalmindset/blindfold";
+      const { spawnSync } = await import("node:child_process");
+      const run = (cmd: string, args: string[], cwd?: string) =>
+        spawnSync(cmd, args, { stdio: "inherit", cwd });
+      let from = argv.flags.from ? String(argv.flags.from) : (process.env.BLINDFOLD_SRC || "");
+      if (!from) {
+        for (const cand of [path.resolve(process.cwd(), "packages", "blindfold"), process.cwd()]) {
+          try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(cand, "package.json"), "utf8"));
+            if ((pkg.name === PKG || pkg.name === "blindfold") && pkg.bin?.blindfold) { from = cand; break; }
+          } catch { /* not the package dir */ }
+        }
+      }
+      if (!from) {
+        // No local source → update from the published scoped package.
+        console.log(head("↻ Updating global blindfold from npm") + c.gray(` (${PKG}@latest)…`));
+        const r = run("npm", ["install", "-g", `${PKG}@latest`]);
+        if (r.status !== 0) {
+          console.log("");
+          console.log(bad("npm update failed") + c.gray(" — not published yet, or offline."));
+          console.log("  Update from your repo checkout instead — one of:");
+          console.log(c.cyan("    blindfold update --from /path/to/packages/blindfold"));
+          console.log(c.cyan("    cd <repo> && blindfold update"));
+          console.log(c.gray("    (or export BLINDFOLD_SRC=/path/to/packages/blindfold)"));
+          process.exitCode = 1;
+          return;
+        }
+        console.log(ok("✓ blindfold updated to the latest published version."));
+        return;
+      }
+      console.log(head(`↻ Updating global blindfold`) + c.gray(` from ${from}`));
+      if (run("npm", ["run", "build"], from).status !== 0) die("build failed");
+      const pack = spawnSync("npm", ["pack"], { cwd: from, encoding: "utf8" });
+      const tgz = (pack.stdout || "").trim().split("\n").pop() || "";
+      if (!tgz) die("npm pack produced no tarball");
+      const tgzPath = path.join(from, tgz);
+      const inst = run("npm", ["install", "-g", tgzPath]);
+      try { fs.rmSync(tgzPath, { force: true }); } catch { /* ignore */ }
+      if (inst.status !== 0) die("global install failed");
+      console.log(ok(`✓ blindfold updated.`) + c.gray(" Open a NEW shell if the command still looks stale."));
+      return;
+    }
+
+    case "publish": {
+      const wasmPath =
+        (argv.flags.wasm as string | undefined) ??
+        assetPath("contract/target/wasm32-wasip2/release/blindfold_proxy.wasm", "blindfold_proxy.wasm");
+      if (!fs.existsSync(wasmPath)) {
+        die(`no wasm found at ${wasmPath} — run scripts/build-contract.sh first`);
+      }
+      const wasm = fs.readFileSync(wasmPath);
+      const r = await registerContract(new Uint8Array(wasm.buffer, wasm.byteOffset, wasm.byteLength));
+      console.log(`✓ Published contract. contract_id=${r.contractId}`);
+      return;
+    }
+    case "init": {
+      const seedFlag = argv.flags.seed;
+      const seedArr = Array.isArray(seedFlag) ? (seedFlag as string[]) : seedFlag ? [String(seedFlag)] : [];
+      await runInit({
+        skipBuild: !!argv.flags["skip-build"],
+        skipPublish: !!argv.flags["skip-publish"],
+        seed: seedArr,
+        yes: !!argv.flags.yes,
+        start: !!argv.flags.start,
+      });
+      return;
+    }
+    case "verify": {
+      await runVerify();
+      return;
+    }
+    case "compat": {
+      await runCompat({ json: !!argv.flags.json });
+      return;
+    }
+    case "sealed": {
+      // List sealed keys (metadata only) for the current ledger.
+      const entries = readSealed();
+      if (entries.length === 0) {
+        console.log(`No sealed-keys ledger yet at ${defaultSealedLogPath()}.`);
+        console.log(`Seal one with:  blindfold register --name <KV_KEY>`);
+        return;
+      }
+      console.log(head("🔐 Sealed keys") + c.gray(`  (source: ${defaultSealedLogPath()})`) + "\n");
+      console.log("  WHEN                  NAME                       BYTES  MODE   WHERE");
+      console.log("  ────                  ────                       ─────  ────   ─────");
+      for (const e of entries) {
+        const when = e.t.replace("T", " ").slice(0, 19);
+        const where = e.map_name.length > 60 ? e.map_name.slice(0, 57) + "…" : e.map_name;
+        console.log(`  ${when}   ${e.name.padEnd(26)}  ${String(e.length).padStart(5)}  ${e.mode.padEnd(5)}  ${where}/${e.name}`);
+      }
+      console.log("\n  (values are NOT stored in this ledger — only metadata. The canonical copy lives in the enclave.)");
+      return;
+    }
+    case "audit": {
+      // (1) Tamper-evidence: verify the local ledger's hash-chain.
+      // (2) Reconcile against the enclave — the actual source of truth.
+      console.log("🔍 Blindfold audit\n");
+      const chain = verifyLedgerChain();
+      console.log("  1. Ledger integrity (tamper-evidence)");
+      if (chain.total === 0) {
+        console.log("     (ledger is empty)");
+      } else if (chain.ok) {
+        const chained = chain.total - chain.legacy;
+        console.log(`     ✅ hash-chain intact — ${chained} chained entr${chained === 1 ? "y" : "ies"}${chain.legacy ? `, ${chain.legacy} legacy (pre-chain, unverifiable)` : ""}`);
+      } else {
+        console.log(`     ✖ TAMPERED — the chain breaks at entry #${chain.firstBrokenIndex} (a line was edited or removed after it was written)`);
+        process.exitCode = 1;
+      }
+
+      const env = loadBlindfoldEnv();
+      if (env.mock) {
+        console.log("\n  2. Enclave reconciliation: skipped (MOCK mode)");
+        return;
+      }
+      const realEntries = readSealed().filter((e) => e.mode === "real");
+      const latest = new Map<string, (typeof realEntries)[number]>();
+      for (const e of realEntries) latest.set(e.name, e); // last write wins
+      console.log(`\n  2. Enclave reconciliation — the enclave is the source of truth (${latest.size} secret${latest.size === 1 ? "" : "s"})`);
+      if (latest.size === 0) {
+        console.log("     (nothing sealed)");
+        return;
+      }
+      const { openT3Client } = await import("../src/t3-client.ts");
+      const client = await openT3Client(env);
+      let okCount = 0, drift = 0, missing = 0;
+      try {
+        for (const e of latest.values()) {
+          const v = await client.verifySecret(e.name);
+          if (!v.present) {
+            missing++;
+            console.log(`     ✖ ${e.name.padEnd(22)} MISSING in enclave  (ledger claims ${e.length} B)`);
+          } else if (v.length !== e.length) {
+            drift++;
+            console.log(`     ⚠ ${e.name.padEnd(22)} length drift: enclave ${v.length} B vs ledger ${e.length} B  fp=${v.fingerprint}`);
+          } else {
+            okCount++;
+            console.log(`     ✅ ${e.name.padEnd(22)} present (${v.length} B, fp=${v.fingerprint})`);
+          }
+        }
+      } finally {
+        await client.close();
+      }
+      console.log(`\n  Summary: ${okCount} verified · ${drift} drift · ${missing} missing · ledger ${chain.ok ? "intact" : "TAMPERED"}`);
+      if (drift > 0 || missing > 0 || !chain.ok) process.exitCode = 1;
+      return;
+    }
+    case "status": {
+      // One-glance overview: health + sealed inventory + what to do next.
+      const env = loadBlindfoldEnv();
+      console.log(head("🛡️  Blindfold status") + "\n");
+      console.log(`  mode:    ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL"}   ·   T3 env: ${env.t3Env}`);
+      if (env.t3BaseUrl) console.log(`  node:    ${env.t3BaseUrl}  (override)`);
+      if (!env.mock) {
+        try {
+          const { openT3Client } = await import("../src/t3-client.ts");
+          const client = await openT3Client(env);
+          const info = await client.me();
+          console.log(`  tenant:  ${ok("✅ " + info.tenant)}  (status=${info.status ?? "?"})`);
+        } catch (e) {
+          console.log(`  tenant:  ${bad("✖ " + (e as Error).message.slice(0, 90))}`);
+          console.log(`           → run \`blindfold doctor\` for a full diagnosis.`);
+          process.exitCode = 1;
+        }
+      }
+      const entries = readSealed();
+      const latest = new Map<string, (typeof entries)[number]>();
+      for (const e of entries) latest.set(e.name, e); // last write wins
+      console.log(`\n  Sealed secrets (${latest.size}):`);
+      if (latest.size === 0) {
+        console.log(`    (none yet)   seal one:  blindfold register --name <X> --from-env <X>`);
+      } else {
+        for (const e of latest.values()) {
+          console.log(`    • ${e.name.padEnd(22)} ${String(e.length).padStart(4)} B   ${e.mode}`);
+        }
+      }
+      console.log(`\n  Next:  blindfold use --name <secret> -- <command>     (use it, no code)`);
+      return;
+    }
+    case "doctor": {
+      const env = loadBlindfoldEnv();
+      console.log(head("🩺 Blindfold doctor"));
+      console.log(`  mode:               ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL (T3)"}`);
+      console.log(`  T3N_API_KEY set:    ${env.t3nApiKey ? "yes" : "NO ✖"}`);
+      console.log(`  DID set:            ${env.did ? "yes" : "NO ✖"}`);
+      console.log(`  T3 environment:     ${env.t3Env}`);
+      console.log(`  node URL:           ${env.t3BaseUrl || `(SDK default for ${env.t3Env})`}`);
+      console.log(`  default proxy port: ${env.port}`);
+      if (!env.mock && (!env.t3nApiKey || !env.did)) {
+        console.log("");
+        console.log(`  ⚠  REAL mode is selected but credentials are missing.`);
+        console.log(`     Claim them: https://docs.terminal3.io/developers/adk/get-started/prerequisites/request-test-tokens`);
+        console.log(`     Or run \`npm run setup\` and the wizard will walk you through it.`);
+        process.exitCode = 1;
+        return;
+      }
+      if (env.mock) return;
+
+      // LIVE check: authenticate, then read the tenant behind the key. This is
+      // what catches the painful "key authenticates but has no tenant" case,
+      // which the server otherwise reports only as a bare HTTP 500.
+      console.log("");
+      console.log("  Live check (handshake + authenticate + me) …");
+      const { openT3Client } = await import("../src/t3-client.ts");
+      let client;
+      try {
+        client = await openT3Client(env);
+        console.log(`  auth:               ${ok("✅ handshake + authenticate OK")}`);
+      } catch (e) {
+        console.log(`  auth:               ${bad("✖ " + (e as Error).message)}`);
+        console.log(`     → Check T3N_API_KEY is a 0x 32-byte hex private key and DID looks like did:t3n:<hex>.`);
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const info = await client.me();
+        console.log(`  tenant:             ✅ ${info.tenant}  (status=${info.status ?? "?"})`);
+        const didHex = env.did.replace(/^did:t3n:/, "").toLowerCase();
+        const meHex = info.tenant.replace(/^did:t3n:/, "").toLowerCase();
+        if (meHex && didHex && meHex !== didHex) {
+          console.log("");
+          console.log(`  ⚠  DID MISMATCH: your .env DID (${env.did}) is not this key's tenant.`);
+          console.log(`     The tenant DID is server-assigned, not derived from the key address.`);
+          console.log(`     Fix: set  DID=${info.tenant}  in .env  (writes/seals target this tenant).`);
+          process.exitCode = 1;
+        } else if (info.status && info.status !== "active") {
+          console.log(`  ⚠  tenant status is "${info.status}" (not active) — seals/writes may fail.`);
+          process.exitCode = 1;
+        } else {
+          console.log(`  ${ok("✅ Ready to seal & use secrets on this tenant.")}`);
+        }
+      } catch (e) {
+        const msg = (e as Error).message;
+        console.log(`  tenant:             ✖ ${msg}`);
+        console.log("");
+        if (/InsufficientCredit|forbidden|403/i.test(msg)) {
+          console.log(`  ⚠  This key has a tenant but NO CREDITS. Seals/writes need credit.`);
+          console.log(`     Fix: request testnet credits / claim tokens, then re-run \`blindfold doctor\`:`);
+          console.log(`       https://docs.terminal3.io/developers/adk/get-started/prerequisites/request-test-tokens`);
+        } else if (/500|internal_error/i.test(msg)) {
+          console.log(`  ⚠  This key AUTHENTICATES but its tenant is unusable: a read-only me()`);
+          console.log(`     returns a server error. Every seal/write with it will also 500.`);
+          console.log(`     Fix one of:`);
+          console.log(`       • switch .env to a key whose tenant is active (check with this doctor),`);
+          console.log(`       • point at a healthy node:  T3_BASE_URL=<leader-node-url>  (if the node itself is unhealthy), or`);
+          console.log(`       • ask Terminal 3 to provision/claim a tenant for this key.`);
+        } else {
+          console.log(`  ⚠  Could not read the tenant behind this key — seals/writes will likely fail.`);
+          console.log(`     Verify the key is provisioned, or switch to a key that passes this doctor.`);
+        }
+        process.exitCode = 1;
+      }
+      return;
+    }
+    case "skill": {
+      const sub = argv._[1] ?? "help";
+      const skillSource = assetPath(".claude/skills/blindfold/SKILL.md", "SKILL.md");
+      if (!fs.existsSync(skillSource)) {
+        die(`skill source not found at ${skillSource} — reinstall Blindfold or run from the repo.`);
+      }
+      const skillContent = fs.readFileSync(skillSource, "utf-8");
+
+      if (sub === "install") {
+        const targets: { label: string; dir: string }[] = [];
+        const global = !!argv.flags.global;
+        const cursor = !!argv.flags.cursor;
+        const opencode = !!argv.flags.opencode;
+        const cline = !!argv.flags.cline;
+        const all = !!argv.flags.all;
+
+        if (global || all) targets.push({ label: "global (all Claude Code sessions)", dir: path.join(process.env.HOME ?? "~", ".claude", "skills", "blindfold") });
+        if (cursor || all) targets.push({ label: "Cursor", dir: path.resolve(".cursor", "rules") });
+        if (opencode || all) targets.push({ label: "OpenCode", dir: path.resolve(".opencode", "skills", "blindfold") });
+        if (cline || all) targets.push({ label: "Cline", dir: path.resolve(".cline", "rules") });
+        if (!global && !cursor && !opencode && !cline && !all) {
+          targets.push({ label: "this project (Claude Code)", dir: path.resolve(".claude", "skills", "blindfold") });
+        }
+
+        for (const t of targets) {
+          fs.mkdirSync(t.dir, { recursive: true });
+          const dest = path.join(t.dir, t.dir.includes("rules") ? "blindfold.md" : "SKILL.md");
+          fs.writeFileSync(dest, skillContent);
+          console.log(`  ✓ ${t.label} → ${dest}`);
+        }
+        console.log(`\n✓ Blindfold skill installed (${targets.length} target${targets.length > 1 ? "s" : ""})`);
+        console.log(`  Your coding agent will now handle secrets safely — try asking it to "seal my API key".`);
+      } else if (sub === "uninstall") {
+        const locations = [
+          path.resolve(".claude", "skills", "blindfold", "SKILL.md"),
+          path.join(process.env.HOME ?? "~", ".claude", "skills", "blindfold", "SKILL.md"),
+          path.resolve(".cursor", "rules", "blindfold.md"),
+          path.resolve(".opencode", "skills", "blindfold", "SKILL.md"),
+          path.resolve(".cline", "rules", "blindfold.md"),
+        ];
+        let removed = 0;
+        for (const loc of locations) {
+          if (fs.existsSync(loc)) { fs.unlinkSync(loc); console.log(`  ✓ removed ${loc}`); removed++; }
+        }
+        console.log(removed ? `\n✓ Removed ${removed} skill file(s).` : "  No skill files found to remove.");
+      } else {
+        console.log(`blindfold skill — install the Blindfold agent skill for your coding agent.
+
+  blindfold skill install                   Install for this project (Claude Code auto-discovers it)
+  blindfold skill install --global          Install globally (~/.claude/skills/, all sessions)
+  blindfold skill install --cursor          Install for Cursor (.cursor/rules/)
+  blindfold skill install --opencode        Install for OpenCode (.opencode/skills/)
+  blindfold skill install --cline           Install for Cline (.cline/rules/)
+  blindfold skill install --all             Install for all of the above at once
+
+  blindfold skill uninstall                 Remove all installed skill files
+
+What it does: teaches your coding agent to seal keys safely — no pasting secrets
+into chat, release-broker pattern in generated code, fingerprint-only verification.`);
+      }
+      return;
+    }
+  }
+}