phaedo-mcp 0.2.1 → 0.3.0

package/signing-request.js

@@ -0,0 +1,217 @@
+// §8.3 signing ceremony — the MCP (server) half of the round-trip.
+//
+// The server holds the mandate; the phone holds the only key that can sign it. This module
+// deposits a SIGN REQUEST for the subject, polls for the signed result, and VERIFIES it —
+// reusing the escalation transport (relay lane, envelope crypto, first-answer-wins,
+// push-to-wake) but NOT its semantics. An escalation answer is approve/deny/modify — a
+// decision internal to the subject's system. A signature is a credential asserted to a
+// third party. Conflating them is the §10.2 action_binding failure mode one layer up, so
+// the request carries a distinct `kind` and the response is a signature or an explicit
+// refusal, never a decision verb.
+//
+// SIGN WHAT YOU SEE. The request carries the mandate OBJECT, not pre-computed bytes. The
+// phone renders that object AND derives the signing input from it, so it cannot be shown
+// one thing and made to sign another. The server re-derives the same bytes here and
+// verifies against them, which independently confirms the phone signed the mandate the
+// server actually built.
+
+import { Phaedo, b64uDec } from './lib/phaedo-crypto.js';
+import { signingInput, verifyEs256 } from './signing.js';
+
+const { Kdf, Envelope } = Phaedo;
+const DEFAULT_RELAY = 'https://phaedo-relay.fly.dev';
+
+const SIGN_REQUEST_KIND = 'sign_request';
+const SIGN_RESPONSE_KIND = 'sign_response';
+// AP2 mandates omit `signature` from the signing input (the field the signature fills).
+const AP2_SIGNATURE_FIELD = 'signature';
+
+export function relayBaseFromEnv(env = process.env) {
+  // PHAEDO_RELAY is the name every other lane reads (escalation, receipts, capture, delegation).
+  // This one read PHAEDO_RELAY_URL alone, so a self-hosted relay silently did NOT cover the §8.3
+  // signing ceremony — sign requests kept going to the default host. The old name is still
+  // honoured so an existing setup does not break.
+  return env.PHAEDO_RELAY || env.PHAEDO_RELAY_URL || DEFAULT_RELAY;
+}
+
+function relayAuthHeader(pairing) {
+  const id = pairing && pairing.relay_device_id;
+  const secret = pairing && pairing.relay_device_secret;
+  return id && secret ? { authorization: `Bearer ${id}:${secret}` } : {};
+}
+
+function genRequestId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
+  return `sig-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Build the encrypted SIGN REQUEST deposit body. Sealed under fp_sync_key, exactly like an
+ * escalation request, and posted to the same relay lane — the phone routes on `kind`.
+ * `mandate` is the object to be signed (unsigned; the `signature` field stays null/absent).
+ */
+export async function buildSignRequestDeposit(pairKeyB64u, requestId, mandate, { windowMs, now = () => new Date().toISOString() } = {}) {
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } finally {
+    pairKey.fill(0);
+  }
+  try {
+    const inner = { kind: SIGN_REQUEST_KIND, request_id: requestId, data: { mandate } };
+    const plaintext = new TextEncoder().encode(JSON.stringify(inner));
+    const envelope = await Envelope.wrap(plaintext, fpSyncKey, { artifact_kind: SIGN_REQUEST_KIND, created_at: now() });
+    plaintext.fill(0);
+    return { request_id: requestId, envelope, ...(windowMs ? { window_ms: windowMs } : {}) };
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+/**
+ * Decrypt the phone's SIGN RESPONSE. Returns the inner data — either
+ * `{ signature, encoding, signed_at }` or `{ refused: true, reason? }` — or null on any
+ * failure. A malformed or forged response must never crash the agent's resume path.
+ */
+export async function unwrapSignResponse(pairKeyB64u, body) {
+  if (!body || !body.envelope) return null;
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } catch { pairKey.fill(0); return null; }
+  pairKey.fill(0);
+  try {
+    const plaintext = await Envelope.unwrap(body.envelope, fpSyncKey);
+    const inner = JSON.parse(new TextDecoder().decode(plaintext));
+    if (inner && inner.kind === SIGN_RESPONSE_KIND && inner.data) return inner.data;
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+/**
+ * Verify a signed mandate. The mandate is re-canonicalized here (signature field omitted)
+ * and checked against the subject's published signing key — so a valid result means BOTH
+ * that the signature is genuine AND that the phone signed the exact mandate the server
+ * built. Returns { verified, reason? }.
+ *
+ * `signingPublicKey` is the base64 X9.63 point from `phaedo_signing_public_key` (published
+ * over the trusted pairing, §8.3 step 2). If it is missing, verification cannot proceed —
+ * that is distinct from a bad signature and is reported as such.
+ */
+export function verifySignedMandate({ mandate, signature, encoding = 'der', signingPublicKey }) {
+  if (!signingPublicKey) return { verified: false, reason: 'no-published-signing-key' };
+  if (typeof signature !== 'string' || !signature) return { verified: false, reason: 'no-signature' };
+  let sigBytes, keyBytes;
+  try {
+    sigBytes = Buffer.from(signature, 'base64');
+    keyBytes = Buffer.from(signingPublicKey, 'base64');
+  } catch {
+    return { verified: false, reason: 'undecodable' };
+  }
+  try {
+    const verified = verifyEs256({
+      payload: mandate,
+      signature: sigBytes,
+      publicKey: keyBytes,
+      encoding,
+      field: AP2_SIGNATURE_FIELD,
+    });
+    return verified ? { verified: true } : { verified: false, reason: 'signature-mismatch' };
+  } catch (e) {
+    // A malformed KEY (not a bad signature) throws in the core; surface it as its own
+    // reason rather than reporting "not the subject's signature".
+    return { verified: false, reason: `key-error:${String(e && e.message || e)}` };
+  }
+}
+
+/** The exact bytes the phone is asked to sign — exported so a caller/test can assert the
+ *  server and phone agree on them. */
+export function mandateSigningInput(mandate) {
+  return signingInput(mandate, { field: AP2_SIGNATURE_FIELD });
+}
+
+/**
+ * Deposit a SIGN REQUEST and wake the device. Returns
+ * { deposited, request_id, window_ms, expires_at } or { deposited:false, reason }.
+ */
+export async function depositSignRequest(pairing, mandate, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  if (!pairing || !pairing.pair_key) return { deposited: false, reason: 'unpaired' };
+  if (!pairing.relay_device_id) return { deposited: false, reason: 'no-relay-device-id' };
+  if (!mandate || typeof mandate !== 'object') return { deposited: false, reason: 'no-mandate' };
+  // A mandate that already carries a signature must not be re-sent for signing.
+  if (mandate.signature != null) return { deposited: false, reason: 'already-signed' };
+
+  const windowMs = Math.max(1000, Number(deps.windowMs) || 5 * 60 * 1000);
+  const relayBase = deps.relayBase || relayBaseFromEnv();
+  const requestId = deps.requestId || genRequestId();
+  try {
+    const body = await buildSignRequestDeposit(pairing.pair_key, requestId, mandate, { windowMs });
+    const res = await fetchFn(`${relayBase}/escalation/${encodeURIComponent(pairing.relay_device_id)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...relayAuthHeader(pairing) },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(deps.depositTimeoutMs || 8000),
+    });
+    if (!res || !res.ok) return { deposited: false, reason: `deposit-failed-${res && res.status}`, request_id: requestId };
+    let info = {};
+    try { info = await res.json(); } catch { /* body optional */ }
+    return { deposited: true, request_id: requestId, window_ms: windowMs, expires_at: info.expires_at, woke: info.woke };
+  } catch (e) {
+    return { deposited: false, reason: `deposit-error:${String(e && e.message || e)}`, request_id: requestId };
+  }
+}
+
+/**
+ * Poll ONCE for a signed mandate. Returns:
+ *   { resolved:true, signed:true, mandate }             — signature verified; mandate now carries it
+ *   { resolved:true, signed:false, reason:'refused' }   — the subject declined to sign
+ *   { resolved:true, signed:false, reason:'verify-failed', detail } — a response arrived but did not verify
+ *   { resolved:false, status:'pending' | 'expired' }
+ * Never throws. A verify failure is resolved-but-unsigned, never silently treated as signed.
+ */
+export async function pollSignOnce(pairing, requestId, mandate, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  if (!pairing || !pairing.pair_key || !requestId) return { resolved: false, status: 'expired', reason: 'bad-args' };
+  if (deps.expiresAt && (deps.now ? deps.now() : Date.now()) > deps.expiresAt) return { resolved: false, status: 'expired' };
+  const relayBase = deps.relayBase || relayBaseFromEnv();
+  let body = null;
+  try {
+    const res = await fetchFn(`${relayBase}/escalation/response/${encodeURIComponent(requestId)}`, {
+      headers: relayAuthHeader(pairing),
+      signal: AbortSignal.timeout(deps.pollTimeoutMs || 8000),
+    });
+    if (res && res.ok) body = await res.json();
+  } catch { /* transient */ }
+  if (!body) return { resolved: false, status: 'pending' };
+
+  const data = await unwrapSignResponse(pairing.pair_key, body);
+  if (!data) return { resolved: false, status: 'pending' };   // undecryptable → keep waiting, don't crash
+
+  if (data.refused === true) {
+    return { resolved: true, signed: false, reason: 'refused', request_id: requestId };
+  }
+
+  const check = verifySignedMandate({
+    mandate,
+    signature: data.signature,
+    encoding: data.encoding || 'der',
+    signingPublicKey: deps.signingPublicKey,
+  });
+  if (!check.verified) {
+    return { resolved: true, signed: false, reason: 'verify-failed', detail: check.reason, request_id: requestId };
+  }
+  return {
+    resolved: true,
+    signed: true,
+    request_id: requestId,
+    mandate: { ...mandate, signature: data.signature, signature_encoding: data.encoding || 'der',
+               signed_at: typeof data.signed_at === 'string' ? data.signed_at : undefined },
+  };
+}

package/signing.js

@@ -0,0 +1,176 @@
+// §8.3 asymmetric signing — the verification half, server-side.
+//
+// The MCP server CANNOT sign: the subject's signing key is non-extractable inside the
+// phone's Secure Enclave (spec §8.3, verified on hardware 2026-07-23). What the server
+// does is (a) compute the exact bytes a signature covers, so the phone can be asked to
+// sign them, and (b) VERIFY a signature once the phone returns one. Signing itself is a
+// ceremony that belongs to the device holding the key, and deliberately stays there.
+//
+// PURE: no I/O, no globals. Crypto is node:crypto only — no third-party dependency is
+// introduced into the verification path.
+
+import { createPublicKey, verify as nodeVerify } from 'node:crypto';
+
+const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+
+// ── RFC 8785 canonical JSON (spec §6) ────────────────────────────────────────
+//
+// ⚠️ A FAITHFUL PORT. This is the FOURTH copy in the repo — envelope.js (extension),
+// mobile/src/lib/envelope.ts, the mirror in scripts/test_cross_compat.mjs, and now this
+// one. It MUST stay byte-identical to those three: a signature is only verifiable if every
+// implementation agrees on the bytes, so a divergence here silently produces signatures
+// nobody else can check. Locked by the published TC-CANON vectors in
+// mcp/test-signing.mjs — if this drifts, that suite fails.
+//
+// JSON.stringify already emits RFC 8785-conformant scalars in ECMAScript (shortest
+// round-trip numbers, minimal string escaping). What it does NOT do is order keys
+// recursively, and it silently turns non-finite numbers into null. Full RFC 8785 here =
+// UTF-16 code-unit key sort + explicit REJECTION of values JSON cannot express.
+const notJson = (v) => v === undefined || typeof v === 'function' || typeof v === 'symbol';
+
+export function canonicalStringify(value) {
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    throw new Error('canonicalStringify: non-finite numbers are not expressible in RFC 8785 JSON');
+  }
+  if (value === null || typeof value !== 'object') {
+    const s = JSON.stringify(typeof value === 'string' ? value.normalize('NFC') : value);
+    if (s === undefined) throw new Error('canonicalStringify: a ' + typeof value + ' is not expressible in JSON');
+    return s;
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(v => (notJson(v) ? 'null' : canonicalStringify(v))).join(',') + ']';
+  }
+  // §6.2 NFC — "Implementations MUST normalize text to NFC before canonicalization to avoid
+  // signature breakage from equivalent but byte different strings." It was implemented nowhere.
+  // This is the VERIFIER: if the phone ever normalizes and this does not, every signature it
+  // produces fails here, over text that looks identical in any log. KEYS too, and a post-NFC
+  // collision is REJECTED rather than silently dropping one. Byte-identical to envelope.js and
+  // mobile/src/lib/envelope.ts.
+  const seen = new Map();
+  for (const k of Object.keys(value)) {
+    if (notJson(value[k])) continue;
+    const nk = k.normalize('NFC');
+    if (seen.has(nk)) throw new Error('canonicalStringify: keys collide under NFC: ' + JSON.stringify(k));
+    seen.set(nk, value[k]);
+  }
+  const keys = [...seen.keys()].sort();   // UTF-16 code-unit order (RFC 8785 §3.2.3), post-NFC
+  const parts = [];
+  for (const k of keys) parts.push(JSON.stringify(k) + ':' + canonicalStringify(seen.get(k)));
+  return '{' + parts.join(',') + '}';
+}
+
+// ── What a signature covers ──────────────────────────────────────────────────
+
+/**
+ * The exact bytes a §8.3 signature is computed over: the §6 canonical serialization of
+ * the object with the signature field itself OMITTED. Omitting it is what makes the input
+ * well defined no matter how many signatures are later appended — the same construction
+ * §8.2 bootstrap mode uses for `digest`.
+ *
+ * @param {object} obj
+ * @param {{ field?: string }} [opts] field to omit (default 'signatures'; AP2 uses 'signature')
+ * @returns {Buffer} UTF-8 canonical bytes
+ */
+export function signingInput(obj, { field = 'signatures' } = {}) {
+  if (!isObj(obj)) throw new Error('signingInput: expected an object');
+  const rest = {};
+  for (const k of Object.keys(obj)) {
+    if (k !== field) rest[k] = obj[k];
+  }
+  return Buffer.from(canonicalStringify(rest), 'utf8');
+}
+
+// ── Key + signature encodings ────────────────────────────────────────────────
+
+/**
+ * Convert an X9.63 uncompressed EC point (0x04 || X || Y, 65 bytes) — what the Secure
+ * Enclave exports — into a node:crypto public key.
+ */
+export function publicKeyFromRawPoint(raw) {
+  const bytes = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+  if (bytes.length !== 65 || bytes[0] !== 0x04) {
+    throw new Error('publicKeyFromRawPoint: expected a 65-byte uncompressed P-256 point (0x04 || X || Y)');
+  }
+  return createPublicKey({
+    key: {
+      kty: 'EC',
+      crv: 'P-256',
+      x: bytes.subarray(1, 33).toString('base64url'),
+      y: bytes.subarray(33, 65).toString('base64url'),
+    },
+    format: 'jwk',
+  });
+}
+
+/**
+ * Convert a DER (X9.62) ECDSA signature — what SecKeyCreateSignature emits — into the raw
+ * r||s form (64 bytes) that JOSE ES256 and the W3C VC suites use.
+ *
+ * This conversion is the boundary the spec deferred: the enclave speaks DER, interoperable
+ * verifiers expect raw, and something has to translate. Doing it here means the wire form
+ * is the interoperable one while the device keeps using its native output.
+ */
+export function derToRawSignature(der) {
+  const b = Buffer.isBuffer(der) ? der : Buffer.from(der);
+  let i = 0;
+  if (b[i++] !== 0x30) throw new Error('derToRawSignature: not a DER SEQUENCE');
+  let seqLen = b[i++];
+  if (seqLen & 0x80) {                       // long form length
+    const n = seqLen & 0x7f;
+    if (n < 1 || n > 2) throw new Error('derToRawSignature: unsupported DER length');
+    seqLen = 0;
+    for (let k = 0; k < n; k++) seqLen = (seqLen << 8) | b[i++];
+  }
+  if (i + seqLen !== b.length) throw new Error('derToRawSignature: DER length mismatch');
+
+  const readInt = () => {
+    if (b[i++] !== 0x02) throw new Error('derToRawSignature: expected DER INTEGER');
+    const len = b[i++];
+    if (len & 0x80) throw new Error('derToRawSignature: unsupported INTEGER length');
+    let v = b.subarray(i, i + len);
+    i += len;
+    // DER integers are signed and minimally encoded: strip leading zero padding, then
+    // left-pad to the 32-byte field width the raw form requires.
+    while (v.length > 1 && v[0] === 0x00) v = v.subarray(1);
+    if (v.length > 32) throw new Error('derToRawSignature: integer wider than P-256 field');
+    return Buffer.concat([Buffer.alloc(32 - v.length), v]);
+  };
+
+  const r = readInt();
+  const s = readInt();
+  if (i !== b.length) throw new Error('derToRawSignature: trailing bytes after signature');
+  return Buffer.concat([r, s]);
+}
+
+// ── Verification ─────────────────────────────────────────────────────────────
+
+/**
+ * Verify a §8.3 ES256 signature over an object.
+ *
+ * Never throws on a bad signature — returns false. A malformed key or an unusable
+ * encoding still throws, because that is a caller bug rather than a failed verification,
+ * and the two must not be conflated (silently returning false for a broken key would
+ * report "not the subject's signature" when the truth is "we could not check").
+ *
+ * @param {object}  args.payload    the signed object (signature field may be present; it is omitted)
+ * @param {Buffer|Uint8Array} args.signature
+ * @param {Buffer|Uint8Array} args.publicKey  X9.63 uncompressed point (65 bytes)
+ * @param {'der'|'raw'} [args.encoding='raw']
+ * @param {string} [args.field='signatures']  which field to omit from the signing input
+ * @returns {boolean}
+ */
+export function verifyEs256({ payload, signature, publicKey, encoding = 'raw', field = 'signatures' }) {
+  if (encoding !== 'der' && encoding !== 'raw') {
+    throw new Error(`verifyEs256: unknown signature encoding '${encoding}'`);
+  }
+  const key = publicKeyFromRawPoint(publicKey);      // throws on a malformed key — deliberate
+  const data = signingInput(payload, { field });
+  const sig = Buffer.isBuffer(signature) ? signature : Buffer.from(signature);
+  try {
+    return nodeVerify('sha256', data, { key, dsaEncoding: encoding === 'der' ? 'der' : 'ieee-p1363' }, sig);
+  } catch {
+    // node throws on structurally invalid signature bytes; that is a failed verification,
+    // not a caller error.
+    return false;
+  }
+}

package/vendor/authored-source.js

@@ -0,0 +1,250 @@
+// Where authored content comes FROM — the step-3 read path.
+//
+// Authored standing rules live in two places during the migration: the fingerprint A-home
+// (`fp.standing_rules`, Proposal 0007) and the §5 User Configuration (`standing_instructions`,
+// derived from the A-home on every write). The sequencing decision is that the §5 copy is
+// AUTHORITATIVE ON READ where both exist, so that step 3 can later delete the A-home and change
+// nothing about what readers see. Every reader routing through here is what makes that true.
+//
+// WHY A RESOLVER AND NOT `cfg.standing_instructions || fp.standing_rules`:
+//
+//   1. §5.4. A configuration that does not name the fingerprint it arrived with is not this
+//      subject's — stale, mis-routed, or hostile. Letting it govern would let one identity's
+//      authored rules apply to another. It must fall back, not be trusted.
+//   2. ABSENT and EMPTY are different. No §5 document at all means "this surface has not been
+//      migrated, use the A-home". A §5 document with an empty list means "the subject has no
+//      rules", and falling back there would RESURRECT rules the subject deleted — the same
+//      failure as the union-vs-tombstone bug in §10.5 revocation (#247).
+//   3. The caller needs to know WHICH home answered. A reader that cannot report its provenance
+//      cannot be verified on device, and "it works" would be indistinguishable from "it silently
+//      read the old home the whole time".
+//
+// Mirrored by mobile/src/lib/authoredSource.ts; kept honest by
+// scripts/test_mobile_authored_source_parity.mjs, which RUNS both over the same inputs.
+
+(function () {
+  'use strict';
+
+  /**
+   * WHICH HOME IS AUTHORITATIVE for authored rules — the step-3 cutover switch.
+   *
+   * It lives HERE, with the resolver, because "where does authored content live" is one question
+   * and both the reader and the writer must answer it identically. authored-write.js re-exports
+   * it; user-config.js reads it to decide whether a re-derive may overwrite standing_instructions.
+   * This module imports nothing, so every consumer can read it without an import cycle.
+   *
+   * 'fingerprint' — today. Rules live on the A-home; §5 is DERIVED from it on every write.
+   * 'config'      — after step 3. §5 is the source; the A-home is a mirror, and the derive must
+   *                 stop overwriting §5 or a routine fingerprint write erases authored rules.
+   *
+   * Flipping this IS the cutover. It ships only once the upgrade gate reads green against real
+   * device reports (owner decision 2026-07-27: release check, not runtime interlock).
+   *
+   * FLIPPED to 'config' on 2026-07-28 and REVERTED the same day, before any device carried it.
+   * The revert is the mechanism working: one constant, so a bad answer costs one line.
+   *
+   * A post-flip review found SIX confirmed paths that lose authored content, every one of them
+   * benign while the A-home is authoritative and live the moment it is not:
+   *   1. the phone's chokepoint replaces §5 wholesale from the mirror, so any authored save
+   *      destroys a §5-only rule (mobile/src/lib/authoredWrite.ts)
+   *   2. background.js never loads THIS module, so the vault write finalizer throws on every
+   *      service-worker write and §5 is never maintained there
+   *   3. the live /v1/profile sync path carries no §5 at all (popup.js silentSync)
+   *   4. popup.js _actOnOverride authors a rule outside the write chokepoint
+   *   5. the SW capture re-deposit strips the §5 envelope off the wire, so authored rules and
+   *      the irreplaceable example_corpus never reach the phone
+   *   6. a non-governing §5 document is never cleared, and absorbs authored content into a
+   *      document that can never govern — and is excluded from §8.2 backup at the same moment
+   *
+   * WHAT MUST BE TRUE BEFORE FLIPPING AGAIN — all six closed, plus:
+   *   - every authoring site routes through the chokepoint, enumerated BY BEHAVIOUR
+   *   - every reader routes through resolveStandingInstructions, likewise
+   *   - the upgrade gate is actually CONSULTED (it currently has zero production call sites)
+   *   - the phone advertises config_home_v0.2 only once it genuinely satisfies it
+   *   - a device pass on a build that carries the phone half
+   * See docs/state/current-state.md and scripts/test_cutover_readiness.mjs.
+   */
+  const AUTHORED_HOME = 'config';
+
+  // ── The upgrade gate, wired ────────────────────────────────────────────────────────────────
+  //
+  // `AUTHORED_HOME` ARMS the cutover. It does not perform it. The effective home is `'config'`
+  // only when the constant says so AND capabilities.js reports every reader current — so flipping
+  // the constant on a fleet where the phone or the agent is behind changes NOTHING until they
+  // catch up, instead of retiring the A-home out from under them.
+  //
+  // This is the wiring the gate was missing. `canRetireAHome` and `retirementBlockers` were
+  // correct and well tested and had ZERO production call sites: evidence was collected into
+  // `phaedo_peer_capabilities` and never asked. The 2026-07-28 flip shipped without the mechanism
+  // designed to authorise it ever being consulted, and six loss paths went with it.
+  //
+  // WHY A LATCH RATHER THAN A READ. The consumers (user-config.js, authored-write.js) are pure
+  // functions over a vault object, and the capability record lives outside the vault on purpose —
+  // it is fleet metadata, and the gate must be answerable without unlocking anything. Making
+  // those functions async, or handing them a storage handle, would put I/O on the authoring path.
+  // So the surface that CAN read storage pushes the record in, and the pure modules read it
+  // synchronously.
+  //
+  // IT FAILS CLOSED IN EVERY DIRECTION. Unset (nobody pushed a record), capabilities.js not
+  // loaded, an empty record, a reader that never reported, a reader on an older build, a report
+  // too old — all of them resolve to `'fingerprint'`. Silence is not consent; the only path to
+  // `'config'` is positive evidence from every reader.
+  let _peerCapabilities = null;
+
+  /**
+   * Publish what the fleet last reported. Called by whichever surface can read storage
+   * (background.js on startup, popup.js after each mailbox drain).
+   */
+  function setPeerCapabilities(known) {
+    _peerCapabilities = isObj(known) ? known : null;
+  }
+
+  /** What was last published. Exposed so a caller can show the subject the same evidence. */
+  function peerCapabilities() { return _peerCapabilities; }
+
+  /**
+   * The home that is actually in force, and why. Returns a REASON so a withheld cutover can be
+   * explained rather than merely observed — the same discipline `retirementBlockers` follows.
+   *
+   * @returns {{ home: string, armed: boolean, blockers: Array, reason: string }}
+   */
+  function effectiveAuthoredHomeDetail(now) {
+    // Read the PUBLISHED value, not the closure constant. `api.AUTHORED_HOME` is what every
+    // consumer sees, so reading anything else would let the module disagree with its own exports
+    // — and it is the value the cutover suites set to stage post-cutover conditions, which means
+    // they exercise this path rather than a parallel one.
+    const armed = (api && api.AUTHORED_HOME) || AUTHORED_HOME;
+    if (armed !== 'config') {
+      return { home: 'fingerprint', armed: false, blockers: [], reason: 'not_armed' };
+    }
+    const CAP = (typeof globalThis !== 'undefined' && globalThis.PhaedoCapabilities) || null;
+    if (!CAP || typeof CAP.retirementBlockers !== 'function') {
+      // The gate module is not present, so the fleet's state is unknowable here. Unknowable is
+      // not the same as fine — this is the `[].every(...)` trap the gate itself was built around.
+      return { home: 'fingerprint', armed: true, blockers: [], reason: 'gate_unavailable' };
+    }
+    if (!isObj(_peerCapabilities)) {
+      return { home: 'fingerprint', armed: true, blockers: [], reason: 'no_capability_record' };
+    }
+    // NAME THE ASKER. The extension's peers are the phone and the agent; passing nothing would
+    // fall back to checking all three including itself, which never reports and would block
+    // forever. See readersFor in capabilities.js.
+    const blockers = CAP.retirementBlockers(_peerCapabilities, now, { self: 'extension' });
+    if (blockers.length) {
+      return { home: 'fingerprint', armed: true, blockers, reason: 'readers_behind' };
+    }
+    return { home: 'config', armed: true, blockers: [], reason: 'fleet_current' };
+  }
+
+  /** The home in force. Use `effectiveAuthoredHomeDetail` when you need to explain a fallback. */
+  function effectiveAuthoredHome(now) {
+    return effectiveAuthoredHomeDetail(now).home;
+  }
+
+  /** Where an answer came from. Returned, never inferred by the caller. */
+  const SOURCE = {
+    CONFIG: 'config',            // §5 — the post-cutover home
+    FINGERPRINT: 'fingerprint',  // the A-home — the fallback step 3 removes
+    NONE: 'none',                // neither home had anything to say
+  };
+
+  function isObj(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+
+  /**
+   * The configuration's live instructions — those not buried by a §5.2 tombstone.
+   *
+   * Keyed by the FROZEN identity in sync-merge.js. When that module is absent (a reader that
+   * loads only the resolver) the tombstones cannot be evaluated, and the honest answer is to
+   * return the rules unchanged rather than guess: dropping rules we cannot key would lose
+   * authored content, and that is the worse direction here.
+   */
+  function withoutRevoked(cfg) {
+    const rules = cfg.standing_instructions;
+    const tombs = Array.isArray(cfg.revoked_instructions) ? cfg.revoked_instructions : [];
+    if (!tombs.length) return rules;
+    const SM = (typeof globalThis !== 'undefined' && globalThis.PhaedoSyncMerge) || null;
+    if (!SM || typeof SM.instructionKey !== 'function') return rules;
+    const dead = new Set(tombs.map((t) => (isObj(t) ? t.key : null)).filter(Boolean));
+    if (!dead.size) return rules;
+    return rules.filter((r) => !dead.has(SM.instructionKey(r)));
+  }
+
+  /**
+   * Does this configuration belong to this fingerprint? Mirrors config-sync.js `pairingHolds`
+   * deliberately rather than importing it: this module is loaded by readers that have no reason
+   * to pull in the transport, and the rule is three lines. Parity between the two is asserted in
+   * scripts/test_authored_source.mjs so the duplication cannot drift.
+   */
+  function configGoverns(cfg, fp) {
+    if (!isObj(cfg) || !isObj(fp)) return false;
+    if (typeof fp.fingerprint_id !== 'string' || !fp.fingerprint_id) return false;
+    if (cfg.fingerprint_id !== fp.fingerprint_id) return false;
+    if (typeof fp.subject_id === 'string' && fp.subject_id &&
+        typeof cfg.subject_id === 'string' && cfg.subject_id &&
+        cfg.subject_id !== fp.subject_id) return false;
+    return true;
+  }
+
+  /**
+   * The authoritative standing instructions, and where they came from.
+   *
+   * §5 wins whenever it is present AND governs — including when it is EMPTY, because an empty
+   * authored set is a statement ("I have no rules"), not an absence. Only a missing or
+   * non-governing configuration falls through to the A-home.
+   *
+   * @returns {{ rules: Array, source: string, reason?: string }}
+   */
+  function resolveStandingInstructions(fp, cfg) {
+    const aHome = isObj(fp) && Array.isArray(fp.standing_rules) ? fp.standing_rules : null;
+
+    if (isObj(cfg) && Array.isArray(cfg.standing_instructions)) {
+      if (configGoverns(cfg, fp)) {
+        // §5.2 tombstones are enforced HERE, not only at the merge. A device that has not merged
+        // since the revocation still holds the rule in `standing_instructions`; honouring the
+        // tombstone at read time is what makes the revocation take effect immediately rather
+        // than on the next sync. §10.5 learned this the hard way — ap2.js honoured its
+        // tombstones while the consult resolver did not, so one artifact gave two answers.
+        return { rules: withoutRevoked(cfg), source: SOURCE.CONFIG };
+      }
+      // Present but not this subject's. Fall back rather than trust it, and SAY so — a §5.4
+      // rejection that looks identical to "no configuration here" is how a mis-paired document
+      // would go unnoticed for months.
+      //
+      // BUT ITS DELETIONS STILL COUNT. The A-home has no revocation concept, and its copy is
+      // union-merged, so a rule the subject deleted comes back from any peer that still holds it
+      // — and falling back to that copy put the deleted rule into force again (measured
+      // 2026-08-12). Honouring the tombstones on a document we otherwise refuse is safe in a way
+      // that honouring its rules would not be: a tombstone can only ever REMOVE an instruction,
+      // never add one or change what it says. The worst it can do is withhold a rule the subject
+      // wanted; the alternative is obeying one they revoked, which is the direction that cannot
+      // be noticed from the outside.
+      if (aHome) {
+        return { rules: withoutRevoked({ standing_instructions: aHome, revoked_instructions: cfg.revoked_instructions }),
+                 source: SOURCE.FINGERPRINT, reason: 'config_pairing_failed' };
+      }
+      return { rules: [], source: SOURCE.NONE, reason: 'config_pairing_failed' };
+    }
+
+    if (aHome) return { rules: aHome, source: SOURCE.FINGERPRINT, reason: 'no_config' };
+    return { rules: [], source: SOURCE.NONE, reason: 'no_config' };
+  }
+
+  /**
+   * True once this surface would behave identically with the A-home deleted — i.e. §5 answered.
+   * This is the evidence a surface needs before it may advertise `config_home_v0.2` to the
+   * upgrade gate. Claiming the capability on the strength of "the code is deployed" rather than
+   * "the read actually resolved to §5" is exactly how a gate opens on the wrong evidence.
+   */
+  function readsFromConfigHome(fp, cfg) {
+    return resolveStandingInstructions(fp, cfg).source === SOURCE.CONFIG;
+  }
+
+  // Declared before the functions above can run (they only read it at call time), so
+  // `effectiveAuthoredHomeDetail` can consult the published value.
+  const api = {
+    AUTHORED_HOME, SOURCE, configGoverns, resolveStandingInstructions, readsFromConfigHome,
+    setPeerCapabilities, peerCapabilities, effectiveAuthoredHome, effectiveAuthoredHomeDetail,
+  };
+  if (typeof globalThis !== 'undefined') globalThis.PhaedoAuthoredSource = api;
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+})();