run402 4.52.0 → 4.54.0

package/cli.mjs

@@ -68,6 +68,7 @@ AUTHORITY — who may act, and with what credential
   auth        Manage project user authentication (magic link, passwords, settings)
   ci          Link GitHub Actions OIDC deploy bindings
   operator    Operator (human/email) session — login, then overview across your wallets
+  source-access Your gitvault member-key wrappers (status) + recovery bundle (export)
 
 DELIVER — reach a human when something happens
   deliveries     Did a notification actually land (list, get)
@@ -438,6 +439,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "source-access": {
+    const { run } = await import("./lib/source-access.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "auth": {
     const { run } = await import("./lib/auth.mjs");
     await run(sub, rest);

package/git-remote-run402.mjs

@@ -409,7 +409,7 @@ async function main(argv) {
    */
   const openVault = async (repoDir) => {
     const result = await getSdk().gitvault.resolveOrCreateAddress({ address, allow_create: false, ...(repoDir ? { repo_dir: repoDir } : {}) });
-    return result.handle.vault;
+    return { vault: result.handle.vault, resolution: result.resolution };
   };
 
   /**
@@ -448,7 +448,7 @@ async function main(argv) {
       addressForm === "id"
         ? await getSdk().gitvault.openOrCreate({ ...target, repo_dir: repoDir })
         : await getSdk().gitvault.resolveOrCreateAddress({ address, repo_dir: repoDir, allow_create: true });
-    if (addressForm === "id" && repoDir) await pinGitvaultRepo(repoDir, result.handle.repo_id);
+    if (addressForm === "id" && repoDir) await pinGitvaultRepo(repoDir, result.handle.repo_id, undefined, { project_id: target.project_id, org_id: target.org_id });
     if (!result.found && result.created) {
       note("");
       note(`vault ${result.handle.repo_id} allocated (genesis ${result.created.genesis_sha256}) — one-shot recovery receipt, keep many copies:`);
@@ -485,8 +485,26 @@ async function main(argv) {
     let vault;
     let state;
     try {
-      vault = await openVault(repoDir ?? undefined);
-      state = await vault.materialize();
+      const opened = await openVault(repoDir ?? undefined);
+      vault = opened.vault;
+      try {
+        state = await vault.materialize();
+      } catch (err) {
+        // An OFFLINE (id-carrying pin) resolution discovers a stale pin on
+        // its FIRST repo-scoped read (client-surface spec, id-pinning
+        // requirement): recover once — clear the pin, re-resolve — and retry
+        // only when re-resolution lands on a DIFFERENT vault; a same-id
+        // answer means the pin was fine and the refusal below is real. git
+        // always runs `list` first in a helper session, so this one site
+        // heals the pin for the `fetch`/`push` that follows it.
+        const recovered = repoDir && opened.resolution?.offline
+          ? await getSdk().gitvault.recoverStalePin({ address, repo_dir: repoDir, resolution: opened.resolution, error: err })
+          : null;
+        if (!recovered) throw err;
+        note(`pinned vault ${opened.resolution.repo_id} no longer resolves — re-resolved to ${recovered.resolution.repo_id}, retrying`);
+        vault = recovered.handle.vault;
+        state = await vault.materialize();
+      }
     } catch (err) {
       // An unallocated vault is not an error here: `list` is the read half of
       // the protocol dance and must never create anything on its own (D2
@@ -594,7 +612,7 @@ async function main(argv) {
         // first) — only the sizing is unavailable.
         let vault;
         try {
-          vault = await openVault(repoDir);
+          vault = (await openVault(repoDir)).vault;
         } catch (err) {
           if (!isVaultNotFound(err)) throw err;
           note("dry-run: no vault allocated for this project yet — a real push would allocate one (push-to-create) before publishing; object/byte sizing is not knowable until then");
@@ -680,6 +698,11 @@ async function main(argv) {
       // The transaction is atomic, so a failure failed every ref in it. Report
       // it against each one rather than letting some look like they landed.
       if (err?.code === "GIT_INVOCATION_REPO_UNRESOLVED") repoRefusalNote(err);
+      // Force-spelling truth (gitvault-force-spelling-and-pin-fold): render
+      // the SDK's own `git push --force` next_action beside git's per-ref
+      // rejection — humans read stderr, agents read the structured error.
+      const forceHint = Array.isArray(err?.body?.next_actions) ? err.body.next_actions.find((a) => a?.action === "git push --force") : null;
+      if (forceHint?.why) note(`hint: ${forceHint.action} — ${forceHint.why}`);
       const reason = describeError(err);
       for (const spec of allowed) out(`error ${spec.dst} ${reason}`);
     }

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.52.0",
+  "surface_version": "4.54.0",
   "verbs": [
     "repos create",
     "repos list",

package/lib/command-manifest.mjs

@@ -392,6 +392,8 @@ export const COMMAND_MANIFEST = [
   { path: ["agent", "status"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["agent", "verify-email"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["agent", "passkey"], positionals: [p("action")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["enroll"] },
+  { path: ["source-access", "status"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the caller's live source-access wrapper set from the gateway" },
+  { path: ["source-access", "export"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--out", "-"], runStyle: "sub", skipBehavioral: "exports the live member recovery bundle (stamps recovery-posture export evidence server-side)" },
   { path: ["operator", "login"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], skipBehavioral: "opens a browser / loopback listener" },
   { path: ["operator", "logout"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["operator", "overview"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },

package/lib/doctor.mjs

@@ -51,6 +51,7 @@ const DOCTOR_CHECK_NAMES = [
   "tier",
   "operator_health",
   "runtime_staleness",
+  "recovery_posture",
   "gitvault",
   "source_scan",
 ];
@@ -132,6 +133,12 @@ Checks performed:
   - Function runtime staleness: deployed functions running an older platform
     runtime than the current gateway build (refresh with 'run402 functions
     rebuild --all'; re-bundles from your stored source, no source change)
+  - Recovery posture: per vault-owning org, whether a human owner has a
+    working control-plane login and whether any member holds a working
+    source-access key (wrapper custody), plus a legacy-custody warning —
+    the org's disaster backstops if the agent machine dies. Evidence
+    levels: "configured" is what the platform verified, never proof an
+    off-platform passkey or saved code still exists.
   - gitvault: the active project's vault — activation policy, whether THIS
     machine can produce the capture a 'required' policy demands, open
     unvaulted-override journals, and where the keystore lives (back it up:
@@ -406,12 +413,13 @@ export async function run(sub, args = []) {
   }
 
   // 6. Operator health snapshot (v1.55 + v1.56 verification attempt detail).
-  // Both checks below ride the SAME operator-status read (runtime_staleness
-  // reuses the response operator_health already pulled), so the whole block
-  // is gated on wanting EITHER — --only runtime_staleness alone still needs
-  // this read, but --only-ing neither skips it entirely, same "don't do the work of a
-  // check nobody asked for" discipline the rest of --only follows.
-  if (wanted("operator_health") || wanted("runtime_staleness")) try {
+  // The checks below all ride the SAME operator-status read (runtime_staleness
+  // and recovery_posture reuse the response operator_health already pulled),
+  // so the whole block is gated on wanting ANY — --only runtime_staleness
+  // alone still needs this read, but --only-ing none skips it entirely, same
+  // "don't do the work of a check nobody asked for" discipline the rest of
+  // --only follows.
+  if (wanted("operator_health") || wanted("runtime_staleness") || wanted("recovery_posture")) try {
     const sdk = getSdk();
     const status = await sdk.admin.getOperatorStatus();
     const gaps = [];
@@ -502,6 +510,53 @@ export async function run(sub, args = []) {
         });
       }
     }
+
+    // 6c. Org recovery posture (gitvault-recovery-custody). One entry per
+    // vault-owning org the caller can see; rides the same operator-status
+    // read. Evidence levels, not guarantees: "configured" names what the
+    // platform VERIFIED — it can never observe whether an off-platform
+    // passkey or saved code still exists. The two headline facts mirror the
+    // feed events org_recovery_posture_degraded/_recovered; each gap line
+    // carries its remedy (Anticipatory), same shape as the reachability gaps
+    // above.
+    if (wanted("recovery_posture")) {
+      const posture = status.recovery_posture;
+      if (!Array.isArray(posture)) {
+        // Gateway older than gitvault-recovery-custody doesn't surface it.
+        checks.push({
+          name: "recovery_posture",
+          status: "skipped",
+          ...(verbose && { hint: "operator status has no 'recovery_posture' block; requires a gitvault-recovery-custody gateway." }),
+        });
+      } else if (posture.length === 0) {
+        // No vault-owning org in the caller's view — nothing to lose, nothing to advise.
+        checks.push({ name: "recovery_posture", status: "ok", value: { orgs: [] } });
+      } else {
+        const gaps = [];
+        for (const org of posture) {
+          const label = `org ${org.org_id} (${org.vault_count} vault${org.vault_count === 1 ? "" : "s"})`;
+          if (org.control_plane_configured === false) {
+            gaps.push(`${label}: no human owner with a working control-plane login — if this org's agent machine dies, nobody can sign in to recover it. Invite a backup human (run402 org invite create ${org.org_id} --email <their-email> --role owner) and have them complete login at console.run402.com.`);
+          }
+          if (org.source_backup_configured === false) {
+            gaps.push(`${label}: no human member holds a working source-access key — vault history has no member-side decryption backup. Have a member complete source enrollment at console.run402.com/account → Source access.`);
+          }
+          if (org.custody_legacy_present === true) {
+            gaps.push(`${label}: a member key is still on single-credential legacy custody (one passkey, no recovery code — losing that one credential loses source access). Re-enroll at console.run402.com/account to move to wrapper custody with a recovery code.`);
+          }
+        }
+        checks.push(
+          gaps.length > 0
+            ? {
+                name: "recovery_posture",
+                status: "warning",
+                value: { orgs: posture, gaps },
+                hint: "These are the org's disaster-recovery backstops — the same facts arrive as org_recovery_posture_degraded/_recovered feed events. After enrolling, export the recovery bundle (run402 source-access export) and store it separately from the code.",
+              }
+            : { name: "recovery_posture", status: "ok", value: { orgs: posture } },
+        );
+      }
+    }
   } catch (err) {
     // Operator status endpoint may not be reachable if the operator-binding
     // substrate isn't deployed yet on the target API. Don't fail the whole
@@ -518,6 +573,11 @@ export async function run(sub, args = []) {
       status: "skipped",
       message: describeCheckFailure("operator status check", err),
     });
+    if (wanted("recovery_posture")) checks.push({
+      name: "recovery_posture",
+      status: "skipped",
+      message: describeCheckFailure("operator status check", err),
+    });
   }
 
   // 6c. gitvault (add-gitvault). Doctor was completely silent about the vault

package/lib/repos.mjs

@@ -65,7 +65,8 @@ Then plain git, forever:
 Occasional:
   run402 repos snapshot [--project <id>] [--repo <repo_id>] [--message <text>] [--checkpoint] [--dry-run] [--allow-dirty] [--manifest-out <path>]
   run402 repos mirror   [<destination>] [--off] [--backfill] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>] [--project <id>] [--repo <repo_id>]
-  run402 repos recover  <source> --out <dir> [--repo <repo_id>] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>] [--human]
+  run402 repos recover  <source> --out <dir> [--repo <repo_id>] [--profile <name> | --ambient] [--region <r>] [--endpoint <url>]
+                        [--bundle <file>] [--code <SRC1-…>] [--receipt <file>] [--rp-id <host>] [--human]
 
 Lifecycle:
   run402 repos rename <new_name> [--repo <repo_id> | --project <project_id>]
@@ -164,6 +165,15 @@ Subcommands:
            mirror's validity, never freshness — read both honesty statements
            before relying on the result. \`--human\` renders a short summary
            instead of JSON.
+           A human member under wrapper custody (no keystore) recovers with
+           their exported recovery bundle + source recovery code:
+           \`--bundle <file>\` (omit to use the mirror's own
+           member-recovery-bundles/ sidecar) + \`--code\` (prompted, hidden,
+           when omitted) + \`--receipt <pin.json>\` (the vault's one-shot
+           recovery receipt — key material never substitutes for the trust
+           anchor). A raw WebAuthn PRF output is NOT a supported input; a
+           code with no exported bundle refuses by name (a server-side
+           wrapper row that was never exported is not offline backup).
   fsck     Walks the head chain AND materializes
            the ref map, advancing BOTH
            local trust pins — reported EXPLICITLY as local_state_changed +
@@ -291,6 +301,19 @@ Options:
   --region <r>      mirror / recover: AWS region for an s3:// destination
   --endpoint <url>  mirror / recover: an S3-compatible endpoint override
   --out <dir>       recover: where to materialize the recovered repository
+  --bundle <file>   recover: an exported r402s-member-recovery-bundle/v1 (from
+                    \`run402 source-access export\` or the console's download).
+                    Omit to use the mirror's member-recovery-bundles/ sidecar.
+  --code <SRC1-…>   recover: the source recovery code that opens the bundle.
+                    Prefer omitting it — with --bundle set it is prompted with
+                    hidden input, so it never lands in shell history.
+  --receipt <file>  recover: the vault's recovery-receipt pin as JSON (the
+                    one-shot receipt from repo creation). Required for trusted
+                    recovery when no keystore holds it — without any pin the
+                    result is labeled unauthenticated_salvage.
+  --rp-id <host>    recover: the seal-time ceremony host bound into the
+                    wrapper context (default: the bundle's own rp_id, then
+                    console.run402.com — where every wrapper is sealed today)
   --budget <n>      fsck: heads walked in this call (write mode persists the
                     verified prefix, so a budget-exceeded run resumes; a
                     --no-write run does not, since nothing was persisted)
@@ -340,6 +363,7 @@ Examples:
   run402 repos gc
   run402 repos access --human
   run402 repos recover s3://acme-vault-mirror --out ./restored --human
+  run402 repos recover ./mirror-copy --out ./restored --receipt ./recovery-receipt.json --bundle ./run402-source-recovery-bundle.json
   run402 repos delete --project prj_xyz --force
 `;
 
@@ -1556,6 +1580,19 @@ async function fsck(args) {
       if (result.mirror.data_loss_detected) {
         console.error(`DATA LOSS DETECTED: ${result.mirror.absences.filter((x) => x.adjudication === "unexplained_absence").length} object(s) are unexplained absences.`);
       }
+      // gitvault-recovery-custody: member recovery-bundle sidecars, reported
+      // as UNVERIFIED availability hints — nothing about them is chain-
+      // authenticated; they only say bundle + source recovery code can
+      // recover this mirror with no server.
+      if (Array.isArray(result.mirror.member_recovery_bundles) && result.mirror.member_recovery_bundles.length > 0) {
+        for (const b of result.mirror.member_recovery_bundles) {
+          console.error(
+            b.parse_error
+              ? `member recovery bundle (unverified hint): ${b.key} — does not parse (${b.parse_error})`
+              : `member recovery bundle (unverified hint): ${b.key} — ${b.ek_fingerprint} [${b.wrapper_kinds.join(", ")}]; recover with \`run402 repos recover <source> --receipt <pin.json>\` + the source recovery code`,
+          );
+        }
+      }
       printMirrorHonesty(result.mirror);
     }
     printVerboseStats(a, sdk);
@@ -1876,6 +1913,9 @@ function formatRecoverHuman(result, outDir) {
   if (result.data_loss_detected) {
     lines.push(`DATA LOSS DETECTED: ${result.absences.filter((x) => x.adjudication === "unexplained_absence").length} object(s) are unexplained absences.`);
   }
+  if (result.member_recovery) {
+    lines.push(`Decrypted via member recovery bundle${result.member_recovery.bundle_key ? ` ${result.member_recovery.bundle_key}` : ""} + source recovery code (no keystore).`);
+  }
   lines.push(`Layout: ${result.layout}` + (result.layout === "bare" ? " (no working files — not a failed recovery)" : ""));
   if (result.retained_refs?.warning) {
     lines.push(`refs/r402/retain: ${result.retained_refs.warning}`);
@@ -1885,9 +1925,40 @@ function formatRecoverHuman(result, outDir) {
   return lines.join("\n");
 }
 
+/**
+ * Read the source recovery code without echoing it (TTY) — a recovery code
+ * is long-lived key material; it must never land in shell history (prefer
+ * the prompt over `--code <value>`) and never echo into a scrollback.
+ * Non-TTY stdin (piped) reads one line verbatim.
+ */
+async function promptSourceRecoveryCode() {
+  const { stdin, stderr } = process;
+  if (!stdin.isTTY) {
+    const chunks = [];
+    for await (const c of stdin) {
+      chunks.push(c);
+      const s = Buffer.concat(chunks).toString("utf8");
+      if (s.includes("\n")) return s.slice(0, s.indexOf("\n")).trim();
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+  }
+  const { createInterface } = await import("node:readline");
+  stderr.write("Source recovery code (SRC1-…, input hidden): ");
+  return await new Promise((resolve) => {
+    const rl = createInterface({ input: stdin, terminal: true });
+    // Mute the echo: readline in terminal mode writes through _writeToOutput.
+    rl._writeToOutput = () => {};
+    rl.question("", (answer) => {
+      rl.close();
+      stderr.write("\n");
+      resolve(answer.trim());
+    });
+  });
+}
+
 async function recover(args) {
   const a = normalizeArgv(args);
-  const valueFlags = ["--out", "--repo", "--profile", "--region", "--endpoint"];
+  const valueFlags = ["--out", "--repo", "--profile", "--region", "--endpoint", "--bundle", "--code", "--receipt", "--rp-id"];
   assertKnownFlags(a, [...valueFlags, "--ambient", "--human", "-v", "--verbose", "--help", "-h"], valueFlags);
   const [source] = requirePositionalCount(a, valueFlags, {
     min: 1, max: 1, command: "run402 repos recover <source> --out <dir>",
@@ -1906,6 +1977,18 @@ async function recover(args) {
   const repoId = flagValue(a, "--repo");
   const region = flagValue(a, "--region");
   const endpoint = flagValue(a, "--endpoint");
+  // gitvault-recovery-custody — the human-member path: --bundle (the exported
+  // r402s-member-recovery-bundle/v1; omit to use the mirror's own
+  // member-recovery-bundles/ sidecar) + the source recovery code. --receipt
+  // supplies the recovery-receipt pin when no keystore holds one (a member
+  // has no keystore); --rp-id overrides the seal-time ceremony host.
+  const bundlePath = flagValue(a, "--bundle");
+  const receiptPath = flagValue(a, "--receipt");
+  const rpId = flagValue(a, "--rp-id");
+  let code = flagValue(a, "--code");
+  const memberBundle = bundlePath != null ? readJsonFile("--bundle", bundlePath) : undefined;
+  const recoveryReceipt = receiptPath != null ? readJsonFile("--receipt", receiptPath) : undefined;
+  if (memberBundle !== undefined && code == null) code = await promptSourceRecoveryCode();
   try {
     const result = await sdk.gitvault.recover({
       source, out_dir: outDir,
@@ -1913,6 +1996,10 @@ async function recover(args) {
       ...(credential ? { credential } : {}),
       ...(region != null ? { region } : {}),
       ...(endpoint != null ? { endpoint } : {}),
+      ...(memberBundle !== undefined ? { member_bundle: memberBundle } : {}),
+      ...(code != null ? { source_recovery_code: code } : {}),
+      ...(recoveryReceipt !== undefined ? { recovery_receipt: recoveryReceipt } : {}),
+      ...(rpId != null ? { rp_id: rpId } : {}),
     });
     if (human) {
       console.log(formatRecoverHuman(result, outDir));
@@ -1924,6 +2011,9 @@ async function recover(args) {
     printJson(sdk, result);
     await spillIfLarge(result.repo_id, "recover", result);
     console.error(`recovered generation ${result.recovered_generation} for ${result.repo_id} into ${outDir}` + (result.chain_break ? ` (chain break at ${result.chain_break.generation} — fell back to the newest fully-verified generation)` : "") + ".");
+    if (result.member_recovery) {
+      console.error(`decrypted via member recovery bundle${result.member_recovery.bundle_key ? ` ${result.member_recovery.bundle_key}` : ""} (wrapper ${result.member_recovery.wrapper_id}, ${result.member_recovery.ek_fingerprint}) + source recovery code — no keystore involved.`);
+    }
     if (result.data_loss_detected) {
       console.error(`DATA LOSS DETECTED: ${result.absences.filter((x) => x.adjudication === "unexplained_absence").length} object(s) are unexplained absences — see "absences" in the result above.`);
     }

package/lib/source-access.mjs

@@ -0,0 +1,159 @@
+/**
+ * `run402 source-access` — a human member's source-access custody, read side.
+ *
+ * Gateway subsystem: gitvault-recovery-custody (/agent/v1/source-access/*).
+ * A member's gitvault decryption key exists only as sealed `swrap2_` wrappers
+ * (passkey PRF and/or source recovery code). Enrollment, activation, and
+ * revocation are BROWSER ceremonies (WebAuthn) at console.run402.com/account
+ * — this command family is deliberately read-only: `status` (what wrappers
+ * exist, their states, the custody scheme) and `export` (the versioned
+ * member recovery bundle that makes the recovery code work with NO run402
+ * server). A server-side wrapper row alone is NOT offline backup — the
+ * exported bundle, kept in your own storage separately from the code, is.
+ *
+ * Auth: your control-plane (human) session — `run402 operator login
+ * --loopback` first. Without one the request falls back to the active
+ * WALLET identity, which answers for the AGENT principal (normally no
+ * wrappers) — truthful, but probably not what a human wanted; a stderr note
+ * says so.
+ */
+import { writeFileSync } from "node:fs";
+import { getSdk } from "./sdk.mjs";
+import { reportSdkError } from "./sdk-errors.mjs";
+import {
+  normalizeArgv,
+  hasHelp,
+  assertKnownFlags,
+  flagValue,
+  requirePositionalCount,
+  failUnknownSubcommand,
+} from "./argparse.mjs";
+import { readControlPlaneSession, isControlPlaneSessionExpired } from "../core-dist/control-plane-session.js";
+
+const HELP = `run402 source-access — your source-access key wrappers (gitvault member custody)
+
+Usage:
+  run402 source-access status
+  run402 source-access export [--out <file> | --out -]
+
+Commands:
+  status   Your source-access key + wrapper set: custody scheme, each
+           wrapper's kind (webauthn_prf / recovery_code) and state
+           (pending / active / revoked). Principal-scoped — only ever YOUR
+           wrappers. Read-only.
+  export   Download your versioned member recovery bundle
+           (r402s-member-recovery-bundle/v1): key identity + every ACTIVE
+           wrapper ciphertext. Together with your source recovery code —
+           kept SEPARATELY — it recovers your vaults with no run402 server
+           (\`run402 repos recover <mirror> --bundle <file> --receipt <pin>\`).
+           Writes run402-source-recovery-bundle-<fingerprint>.json (0600) in
+           the current directory unless --out says otherwise; the full JSON
+           also goes to stdout (pipe contract). To make the bundle travel
+           WITH a vault mirror, copy it to member-recovery-bundles/<name>.json
+           under the mirrored prefix — recover finds it there automatically.
+
+Options:
+  --out <file>   export: where to write the bundle (0600). \`--out -\` skips
+                 the file and prints to stdout only.
+  --json         Already the default output; accepted for consistency.
+
+Auth:
+  Sign in as YOURSELF first: run402 operator login --loopback
+  (Without a control-plane session the call answers for the active WALLET's
+  agent principal — normally an empty wrapper set.)
+
+Enrollment / activation / revocation / code replacement are browser
+ceremonies: console.run402.com/account → Source access.
+
+Examples:
+  run402 operator login --loopback
+  run402 source-access status
+  run402 source-access export --out ./bundle.json
+`;
+
+/** The cached control-plane WRITE session's bearer, or null (falls back to wallet SIWX with a stderr note). */
+function controlPlaneToken() {
+  const cp = readControlPlaneSession();
+  if (cp && !isControlPlaneSessionExpired(cp, Date.now())) return cp.control_plane_session_token;
+  return null;
+}
+
+function tokenOptsWithNote(command) {
+  const token = controlPlaneToken();
+  if (!token) {
+    process.stderr.write(
+      `no control-plane (human) session — ${command} will answer for the active WALLET's agent principal, which normally holds no wrappers. Run 'run402 operator login --loopback' to see your own.\n`,
+    );
+    return {};
+  }
+  return { token };
+}
+
+async function status(args) {
+  assertKnownFlags(args, ["--json", "--help", "-h"]);
+  requirePositionalCount(args, [], { min: 0, max: 0, command: "run402 source-access status", missing: "" });
+  const sdk = getSdk();
+  try {
+    const result = await sdk.operator.session.sourceAccessWrappers(tokenOptsWithNote("status"));
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.encryption_key) {
+      console.error("no source-access key enrolled — enroll at console.run402.com/account → Source access.");
+      return;
+    }
+    const active = result.wrappers.filter((w) => w.state === "active");
+    const pending = result.wrappers.filter((w) => w.state === "pending");
+    console.error(
+      `${result.encryption_key.ek_fingerprint} (${result.encryption_key.custody_scheme}, ${result.encryption_key.state}): ` +
+        `${active.length} active wrapper(s) [${active.map((w) => w.kind).join(", ") || "none"}]` +
+        (pending.length > 0 ? `, ${pending.length} pending (unfinished enrollment — finish or it expires)` : "") + ".",
+    );
+    if (active.length > 0 && !active.some((w) => w.kind === "recovery_code")) {
+      console.error("no recovery_code wrapper — a passkey-only key has no offline/no-server recovery path; add a recovery code at console.run402.com/account.");
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function exportBundle(args) {
+  assertKnownFlags(args, ["--out", "--json", "--help", "-h"], ["--out"]);
+  requirePositionalCount(args, ["--out"], { min: 0, max: 0, command: "run402 source-access export", missing: "" });
+  const out = flagValue(args, "--out");
+  const sdk = getSdk();
+  try {
+    const bundle = await sdk.operator.session.sourceAccessRecoveryBundle(tokenOptsWithNote("export"));
+    // Full JSON to stdout regardless — the pipe contract is sacred; the file
+    // is the keep-a-copy convenience (0600 — the bundle is ciphertext the
+    // platform cannot open, but it is still half of a recovery credential).
+    console.log(JSON.stringify(bundle, null, 2));
+    if (out !== "-") {
+      const path = out ?? `run402-source-recovery-bundle-${(bundle.ek_fingerprint || "key").slice(0, 11)}.json`;
+      writeFileSync(path, JSON.stringify(bundle, null, 2) + "\n", { mode: 0o600 });
+      console.error(`bundle written to ${path} (0600).`);
+    }
+    console.error("keep this bundle SEPARATELY from your source recovery code — together they are equivalent to your member private key.");
+    console.error("to make it travel with a vault mirror: copy it to member-recovery-bundles/<name>.json under the mirrored prefix; `run402 repos recover` finds it there.");
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+export async function run(sub, args = []) {
+  args = normalizeArgv(args);
+  if (!sub || sub === "--help" || sub === "-h" || hasHelp(args)) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "status":
+      await status(args);
+      break;
+    case "export":
+      await exportBundle(args);
+      break;
+    default:
+      failUnknownSubcommand("source-access", sub, {
+        hint: "Run `run402 source-access --help` for usage (subcommands: status, export).",
+      });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.52.0",
+  "version": "4.54.0",
   "description": "CLI for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.",
   "type": "module",
   "bin": {

package/sdk/dist/namespaces/gitvault.crypto.d.ts

@@ -562,5 +562,46 @@ export declare function checkPinManifestConservation(prior: readonly {
 /** The synthetic ledger id a path-addressed `key_envelope` gets — mirrors the gateway's `keyEnvelopeLedgerId` exactly (drift here breaks receipt pairing at upload finalize). */
 export declare function keyEnvelopeLedgerId(epoch: string, fingerprint: string, rotationId: string | null): string;
 export declare function pinManifestLedgerId(pinManifestVersion: string): string;
+export declare const SOURCE_WRAP_BLOB_PREFIX = "swrap2_";
+export declare const SOURCE_RC_DISPLAY_PREFIX = "SRC1";
+export type SourceWrapperKind = "webauthn_prf" | "recovery_code";
+export interface SourceWrapperContextFields {
+    /** The seal-time ceremony host (`location.hostname` of the sealing page — `console.run402.com` for every wrapper sealed today). */
+    rp_id: string;
+    principal_id: string;
+    encryption_key_id: string;
+    wrapper_id: string;
+    kind: SourceWrapperKind;
+    /** WebAuthn `public_subject` for `webauthn_prf` wrappers; always null in the JCS for `recovery_code`. */
+    credential_subject: string | null;
+    /** The raw 32-byte member public key — the context binds its FULL SHA-256, never the truncated `ek_` fingerprint. */
+    member_public_key: Uint8Array;
+}
+/** The pinned canonical context for one wrapper — BOTH the KEK HKDF-info suffix AND the AEAD AAD. */
+export declare function buildSourceWrapperContext(fields: SourceWrapperContextFields): Uint8Array;
+/**
+ * Open a `swrap2_...` wrapper blob back into the 32-byte member scalar.
+ * `ikm` is the UTF-8 bytes of the normalized code CORE (`recovery_code`) or
+ * the raw PRF output (`webauthn_prf` — only ever exercised by browser
+ * surfaces; offline recovery refuses raw PRF as an input by policy, at the
+ * recover layer). A failed AEAD is `WRAPPER_DID_NOT_OPEN` — the truthful
+ * cause-neutral error: wrong code, corrupt blob, and wrong context (rp_id
+ * included) are indistinguishable here. The caller MUST compare the derived
+ * FULL public key against the published one before trusting the scalar.
+ */
+export declare function openSourceWrapper(input: {
+    kind: SourceWrapperKind;
+    ikm: Uint8Array;
+    blob: string;
+    context: Uint8Array;
+}): Uint8Array;
+/**
+ * Pinned normalization (ONE canonical accepted form): uppercase; strip every
+ * char outside [0-9A-Z]; map I→1, L→1, O→0; drop a leading "SRC1" when the
+ * result is 37 chars; require exactly 33 chars; validate the check character
+ * (`RECOVERY_CODE_CHECKSUM_INVALID` — a local typo, caught before any KEK
+ * derivation or wrapper read). Returns the 32-char CORE (the KEK ikm).
+ */
+export declare function normalizeSourceRecoveryCode(input: string): string;
 export { bytesToHex, hexToBytes };
 //# sourceMappingURL=gitvault.crypto.d.ts.map