switchroom 0.7.15 → 0.10.0

package/telegram-plugin/tests/vault-grant-union.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Static-source contract pin for the grant-union behavior shipped to
+ * fix #1051's silent-token-overwrite bug class.
+ *
+ * The bug: when an operator approved a vault_request_access card for
+ * key A and then later approved a second card for key B, the second
+ * mint OVERWROTE the agent's `.vault-token` file with a single-key
+ * grant. Both grants existed in the broker DB but the agent could
+ * only authenticate against the most-recent one — `vault get keyA`
+ * after the second approval returned VAULT-BROKER-DENIED.
+ *
+ * Fix: before minting, the gateway lists the agent's existing
+ * non-expired grants (using the new passphrase-attested list_grants
+ * path) and unions their keys with the new key. The fresh grant
+ * covers OLD ∪ NEW; the old grant ages out via TTL.
+ *
+ * This file pins the wiring at the call site so a future refactor
+ * can't silently drop the union step.
+ */
+
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, "..", "gateway", "gateway.ts"),
+  "utf-8",
+);
+
+function extractPerformBlock(): string {
+  const start = gatewaySrc.indexOf("async function performVaultAccessApproval");
+  if (start < 0) throw new Error("performVaultAccessApproval not found");
+  // Bound the block by the next top-level `async function` keyword.
+  const restAfter = gatewaySrc.slice(start + 1);
+  const endRel = restAfter.indexOf("\nasync function ");
+  return gatewaySrc.slice(start, start + 1 + (endRel >= 0 ? endRel : restAfter.length));
+}
+
+describe("performVaultAccessApproval unions keys with the agent's existing grant (#1051)", () => {
+  const block = extractPerformBlock();
+
+  it("calls listGrantsViaBroker BEFORE mintGrantViaBroker", () => {
+    // fails when: a refactor drops the list step. Without it the
+    // mint covers only [pending.key] and OVERWRITES the agent's
+    // .vault-token, stranding the previous approval's grant from
+    // the agent's perspective.
+    const listIdx = block.indexOf("listGrantsViaBroker(");
+    const mintIdx = block.indexOf("mintGrantViaBroker(");
+    expect(listIdx, "listGrantsViaBroker call missing in performVaultAccessApproval").toBeGreaterThan(0);
+    expect(mintIdx, "mintGrantViaBroker call missing").toBeGreaterThan(0);
+    expect(listIdx, "list MUST happen BEFORE mint").toBeLessThan(mintIdx);
+  });
+
+  it("forwards an attestation to listGrantsViaBroker (#1115 follow-up: passphrase OR posture)", () => {
+    // The non-admin agent socket needs operator-attestation to call
+    // list_grants (#1051's broker-side gate widening). Pre-#1115-
+    // follow-up this had to be the operator passphrase. Post-fix the
+    // gateway threads either `{ passphrase }` or
+    // `{ attest_via_posture: true }` via `brokerAuthOpts`, depending
+    // on whether the operator typed the passphrase or the host is
+    // running telegram-id posture. The call must forward the auth
+    // opts object intact.
+    const listMatch = block.match(/listGrantsViaBroker\([^)]+\)/);
+    expect(listMatch, "listGrantsViaBroker call shape").not.toBeNull();
+    expect(listMatch![0], "attestation MUST be forwarded (brokerAuthOpts)").toMatch(/brokerAuthOpts/);
+  });
+
+  it("unions existing key_allow with the new key before minting", () => {
+    // Pin the union semantics. The mint call must pass a Set-like
+    // union of existing keys + new key, not just [pending.key].
+    expect(block).toMatch(/key_allow/);
+    expect(block).toMatch(/new Set/);
+    // The Set MUST be seeded from the existing grant's keys.
+    expect(block).toMatch(/existingReadKeys|active\[0\]/);
+  });
+
+  it("includes write_allow union for write-scope requests", () => {
+    // Mirror the read-side union for write scope.
+    expect(block).toMatch(/write_allow/);
+    expect(block).toMatch(/writeKeys\.add|writeKeys\.size/);
+  });
+
+  it("concurrent Approve taps queue into a single pending-op (#1051)", () => {
+    // Without the queue, a second Approve tap before the operator
+    // types their passphrase OVERWRITES the first stage's pending
+    // op — the first card's grant never mints. The new shape has
+    // `items: [...]` so a second tap APPENDS, and the text-handler
+    // drains every queued stage off one passphrase entry.
+    //
+    // Anchor on the producer site inside handleVaultRequestAccessCallback.
+    const callbackHandler =
+      gatewaySrc
+        .split("async function handleVaultRequestAccessCallback")[1]
+        ?.split("\nasync function ")[0] ?? "";
+    // The producer reads any existing pending op, and APPENDS to
+    // items[] rather than overwriting.
+    expect(callbackHandler).toMatch(/pendingVaultOps\.get\(pending\.chat_id\)/);
+    // `items` declared (either as `items: [...]` literal or `const items = ...`).
+    expect(callbackHandler).toMatch(/\bitems\b/);
+    expect(callbackHandler).toMatch(/passphrase-for-access-approve/);
+
+    // The consumer (text-handler) loops over items. Anchor on the
+    // unique consumer code (the `else if` branch that handles a
+    // passphrase reply), not the type-discriminator string itself —
+    // the latter appears in the PendingVaultOp type definition too,
+    // so a naive split lands on the wrong slice.
+    const textHandlerIdx = gatewaySrc.indexOf("else if (pendingVault.kind === 'passphrase-for-access-approve')");
+    expect(textHandlerIdx, "text-handler consumer branch not found").toBeGreaterThan(0);
+    const textHandler = gatewaySrc.slice(textHandlerIdx, textHandlerIdx + 3000);
+    expect(textHandler, "text-handler MUST iterate items").toMatch(/for\s*\(\s*const\s+item\s+of\s+pendingVault\.items/);
+    // Each iteration looks up the staged access (sibling-stage may
+    // have been denied / expired between tap and passphrase reply).
+    expect(textHandler).toMatch(/pendingVaultRequestAccesses\.get\(item\.stageId\)/);
+  });
+
+  it("gracefully proceeds with single-key mint when listGrants fails", () => {
+    // Non-blocker: if listGrants returns unreachable/error, the
+    // gateway should STILL mint the new grant (without union) so
+    // the operator's tap-to-approve doesn't get blocked on a
+    // transient broker issue. Documented intent.
+    expect(block).toMatch(/list\.kind === 'ok'/);
+    // A comment explaining the fallback behavior must be present so
+    // a future reader knows the gracefully-degraded path is
+    // intentional.
+    // The comment is split across multiple // lines, so collapse
+    // whitespace + comment prefixes before matching.
+    const flattened = block.replace(/\n\s*\/\/\s*/g, " ");
+    expect(flattened).toMatch(/(without union|edge case|fall.?back|fail closed|degrade)/i);
+  });
+});

package/telegram-plugin/tests/vault-key-regex-allows-slash.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Contract pin for #1047 — the gateway's vault-key regex was stricter
+ * than the broker's, so canonical slash-namespaced keys like
+ * `fatsecret/client_id` couldn't be requested via the in-band
+ * approval card flow. Filed by gymbro after hitting
+ * VAULT-BROKER-DENIED on `fatsecret/client_id` and being unable to
+ * call `vault_request_access` because of the schema regex.
+ *
+ * Three call sites use the regex:
+ *   1. `vault_request_save` execute (telegram-plugin/gateway/gateway.ts ~3549)
+ *   2. `vault_request_access` execute (~3633)
+ *   3. The rename-the-staged-key text-message handler (~5185)
+ *
+ * All three must accept the canonical slash-namespaced shape used by
+ * production keys: `fatsecret/client_id`, `mff/agent-private-key`,
+ * `microsoft/ken-tokens`. The broker itself has no key-shape regex
+ * (just `z.string().min(1)` in protocol.ts), so the gateway should
+ * mirror that posture — accept what the broker accepts.
+ *
+ * This is a static-source pin — the regex literal must appear in the
+ * gateway source. A runtime test would need a full bot harness;
+ * static-source mirrors the convention used elsewhere in this file
+ * tree (see jtbd-talk-from-anywhere.test.ts, vault-request-access-tool.test.ts).
+ */
+
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, "..", "gateway", "gateway.ts"),
+  "utf-8",
+);
+
+/** The exported regex literal — what the gateway actually validates against. */
+function extractVaultKeyRegex(): RegExp {
+  // The shared constant declaration. Anchored on the `VAULT_KEY_REGEX
+  // = /` prefix and the `/` immediately before the line terminator
+  // (the regex has no flags). The source includes `/` inside the
+  // character class, so a greedy match up to end-of-line is the
+  // safe extraction strategy.
+  const m = gatewaySrc.match(/const\s+VAULT_KEY_REGEX\s*=\s*\/(.+)\/\s*$/m);
+  if (!m) throw new Error("VAULT_KEY_REGEX constant not found in gateway.ts");
+  return new RegExp(m[1]);
+}
+
+/** Either inline literal with `/`, OR a reference to VAULT_KEY_REGEX. */
+const ACCEPTS_SLASH = /\[A-Za-z0-9_(\/|\\\/|\.)+-\]|VAULT_KEY_REGEX/;
+
+describe("vault-key regex accepts canonical slash-namespaced keys (#1047)", () => {
+  it("vault_request_save validation includes '/' in the charclass", () => {
+    // Anchor on the unique error message so a refactor that moves
+    // the validation can still be located.
+    const ix = gatewaySrc.indexOf("vault_request_save: key must match");
+    expect(ix, "could not find vault_request_save key error message").toBeGreaterThan(0);
+    const window = gatewaySrc.slice(Math.max(0, ix - 400), ix);
+    expect(
+      window,
+      "vault_request_save validation should accept '/' (e.g. fatsecret/client_id)",
+    ).toMatch(ACCEPTS_SLASH);
+  });
+
+  it("vault_request_access validation includes '/' in the charclass", () => {
+    const ix = gatewaySrc.indexOf("vault_request_access: key must match");
+    expect(ix, "could not find vault_request_access key error message").toBeGreaterThan(0);
+    const window = gatewaySrc.slice(Math.max(0, ix - 400), ix);
+    expect(
+      window,
+      "vault_request_access validation should accept '/' (e.g. fatsecret/client_id)",
+    ).toMatch(ACCEPTS_SLASH);
+  });
+
+  it("rename-staged-key validation includes '/' in the charclass", () => {
+    // The rename handler for the [✏️ Rename] button on a
+    // vault_request_save card. If this stays strict, operators can't
+    // rename a staged key to a canonical namespaced form.
+    const ix = gatewaySrc.indexOf("Key must match");
+    expect(ix, "could not find rename validation error message").toBeGreaterThan(0);
+    const window = gatewaySrc.slice(Math.max(0, ix - 400), ix);
+    expect(
+      window,
+      "rename handler should accept '/' (e.g. fatsecret/client_id)",
+    ).toMatch(ACCEPTS_SLASH);
+  });
+
+  it("/vault audit one-tap Allow callback validation includes '/' in the charclass", () => {
+    // Reviewer-caught oversight on #1049: the
+    // handleVaultRecentDenialCallback handler (#969 P2b) validates
+    // the keyName parsed from the inline-button callback_data with
+    // its own copy of the key regex. Without this site updated, the
+    // exact bug from #1047 — operator opens /vault audit on a
+    // denied `fatsecret/client_id`, taps [Allow] — would surface
+    // "Invalid key name" even though the agent-initiated card flow
+    // works.
+    const ix = gatewaySrc.indexOf("'Invalid key name'");
+    expect(ix, "could not find /vault audit Invalid key name error").toBeGreaterThan(0);
+    const window = gatewaySrc.slice(Math.max(0, ix - 400), ix);
+    expect(
+      window,
+      "/vault audit one-tap allow should accept '/' (e.g. fatsecret/client_id)",
+    ).toMatch(ACCEPTS_SLASH);
+  });
+
+  it("user-facing rename error message names the slash as allowed", () => {
+    // The visible error text guides the operator on what's allowed.
+    // If we widened the regex but didn't update the message, the
+    // operator is told `/` is disallowed even though it isn't.
+    // The VAULT_KEY_REGEX_LABEL string is the canonical user-visible
+    // hint and includes the `/` shape.
+    const m = gatewaySrc.match(/const\s+VAULT_KEY_REGEX_LABEL\s*=\s*"([^"]+)"/);
+    expect(m, "VAULT_KEY_REGEX_LABEL constant not found").not.toBeNull();
+    expect(m![1], "label must mention '/' as allowed").toMatch(/\//);
+  });
+});
+
+describe("vault-key regex: regression guards (the fix doesn't break the original shape)", () => {
+  // Anchored to the live VAULT_KEY_REGEX constant declaration so the
+  // test runs the same regex the gateway runs. A breaking refactor
+  // (typo, accidental tightening) fails loudly here.
+  const re = extractVaultKeyRegex();
+
+  it.each([
+    ["telegram_bot_token", true, "underscores + lowercase"],
+    ["MY_TOKEN", true, "uppercase + underscore"],
+    ["api.key", true, "dot namespace"],
+    ["fatsecret/client_id", true, "slash namespace (the bug)"],
+    ["fatsecret/credentials", true, "slash namespace"],
+    ["mff/agent-private-key", true, "slash namespace with hyphen"],
+    ["microsoft/ken-tokens", true, "slash namespace from issue"],
+    ["k", true, "single char"],
+    ["a".repeat(200), true, "max length"],
+    ["", false, "empty rejected"],
+    ["a".repeat(201), false, "over-length rejected"],
+    ["key with space", false, "space rejected"],
+    ['key"with"quotes', false, "quotes rejected"],
+    ["key\nwith\nnewlines", false, "newlines rejected"],
+  ] as const)("VAULT_KEY_REGEX: %s — should %s (%s)", (input, expected) => {
+    expect(re.test(input), `${JSON.stringify(input)} (${expected ? "accept" : "reject"})`).toBe(expected);
+  });
+});

package/telegram-plugin/tests/vault-posture-quarantine.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Regression for #1115 follow-up — vault-approval-posture config errors
+ * must NOT manifest as unhandled-rejection crash loops.
+ *
+ * Pre-fix (2026-05-13 overnight UAT discovery): when the operator
+ * declared `vault.broker.approvalAuth: telegram-id` in switchroom.yaml
+ * but the auto-unlock blob couldn't be read (e.g. agent UID can't
+ * access the operator's home dir), `resolveVaultApprovalPosture`
+ * threw, the startup IIFE in gateway.ts let the error propagate as an
+ * unhandled rejection, and `_switchroom_supervise` saw status=0 from
+ * the shutdown handler and respawned the gateway. 10 restarts in <60s
+ * before the supervisor's restart-cap kicked in. Each restart posted
+ * an "agent-crashed" operator-event card and the bridge was alive only
+ * in brief windows between restarts — inbound messages dropped.
+ *
+ * Post-fix: the startup catches the config-class error, writes a
+ * quarantine marker with reason `startup.config_error`, and calls
+ * `process.exit(78)` (sysexits EX_CONFIG). The supervisor short-
+ * circuits on exit 78 without restarting (`_switchroom_supervise` in
+ * `profiles/_base/start.sh.hbs`), so the operator sees ONE clean
+ * error and a quarantine file instead of a crash-loop log smear.
+ *
+ * These tests assert the contracts:
+ *   1. The reason code `startup.config_error` exists in both quarantine
+ *      modules (host-side and plugin-side stay in sync).
+ *   2. The quarantine marker writer accepts the new reason and writes
+ *      a parseable JSON file.
+ *   3. The reader at `src/agents/quarantine.ts` round-trips the new
+ *      reason.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { writeQuarantineMarker, QUARANTINE_FILENAME } from '../gateway/quarantine.js'
+import {
+  readQuarantineMarker,
+  type QuarantineReason,
+} from '../../src/agents/quarantine.js'
+
+let stateDir: string
+
+beforeEach(() => {
+  stateDir = mkdtempSync(join(tmpdir(), 'vault-posture-quarantine-'))
+})
+
+afterEach(() => {
+  rmSync(stateDir, { recursive: true, force: true })
+})
+
+describe('quarantine — startup.config_error reason', () => {
+  it('plugin-side writer accepts the new reason and writes a parseable marker', () => {
+    writeQuarantineMarker(
+      stateDir,
+      'startup.config_error',
+      'vault.broker.approvalAuth=telegram-id but blob unreadable',
+    )
+    const raw = readFileSync(join(stateDir, QUARANTINE_FILENAME), 'utf-8')
+    const parsed = JSON.parse(raw) as {
+      v: number
+      reason: string
+      ts: number
+      detail?: string
+    }
+    expect(parsed.v).toBe(1)
+    expect(parsed.reason).toBe('startup.config_error')
+    expect(typeof parsed.ts).toBe('number')
+    expect(parsed.detail).toContain('vault.broker.approvalAuth')
+  })
+
+  it('host-side reader round-trips the new reason', () => {
+    writeQuarantineMarker(stateDir, 'startup.config_error', 'detail goes here')
+    const m = readQuarantineMarker(stateDir)
+    expect(m).not.toBeNull()
+    expect(m!.reason).toBe('startup.config_error')
+    expect(m!.detail).toBe('detail goes here')
+  })
+
+  it('startup.unauthorized reason still round-trips (no regression)', () => {
+    writeQuarantineMarker(stateDir, 'startup.unauthorized', '401 Unauthorized')
+    const m = readQuarantineMarker(stateDir)
+    expect(m!.reason).toBe('startup.unauthorized')
+  })
+
+  it('type-level: both reasons accepted by QuarantineReason union', () => {
+    const accepted: QuarantineReason[] = ['startup.unauthorized', 'startup.config_error']
+    expect(accepted).toHaveLength(2)
+  })
+
+  it('marker survives in detail field — no truncation of operator-facing message', () => {
+    const longDetail =
+      'vault.broker.approvalAuth=telegram-id but reading auto-unlock blob at '
+      + '/state/agent/home/.switchroom/vault-auto-unlock failed: ENOENT no such '
+      + 'file or directory. Refusing to boot — silently falling back to '
+      + 'passphrase posture would invert the operator\'s declared security '
+      + 'posture. Either repair the auto-unlock blob (rerun `switchroom setup` '
+      + '/ `switchroom vault auto-unlock`) or remove vault.broker.approvalAuth '
+      + 'from switchroom.yaml.'
+    writeQuarantineMarker(stateDir, 'startup.config_error', longDetail)
+    const m = readQuarantineMarker(stateDir)
+    expect(m!.detail).toBe(longDetail)
+  })
+})

package/telegram-plugin/tests/vault-request-access-tool.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Pin the agent-initiated vault ACL request flow shipped in #1012.
+ *
+ * Regressions guarded here:
+ *   1. `vault_request_access` MCP tool dropping from bridge.ts schema
+ *      (the agent would lose the tool with no compile-time signal).
+ *   2. `vault_request_access` missing from the gateway's ALLOWED_TOOLS
+ *      set (bridge would emit it but gateway would 403 with
+ *      `tool not allowed`).
+ *   3. The `vra:` callback prefix losing its dispatcher branch (taps
+ *      on [Approve] / [Deny] silently fall through to the trailing
+ *      "unknown callback" arm).
+ *   4. The 90-day TTL ceiling and `read|write` scope shape — both are
+ *      part of the threat model (agents can't request perpetual or
+ *      undefined-scope grants).
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const bridgeSrc = readFileSync(
+  resolve(__dirname, '..', 'bridge', 'bridge.ts'),
+  'utf-8',
+)
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+
+describe('vault_request_access (#1012)', () => {
+  it('bridge advertises the tool to MCP clients', () => {
+    // fails when: the schema is removed from TOOL_SCHEMAS — agents
+    // running the new tool will hit a generic "unknown tool" path
+    // before they ever see the gateway.
+    expect(bridgeSrc).toContain("name: 'vault_request_access'")
+  })
+
+  it('bridge schema declares the threat-model-critical fields', () => {
+    // fails when: a refactor drops `scope` (defaults to read) or
+    // `duration` (caps requested TTL at 90d). Both gates are part of
+    // the agent-can-only-request-not-mint boundary described in #1012.
+    const block = bridgeSrc.split("name: 'vault_request_access'")[1]?.split("name: '")[0] ?? ''
+    expect(block).toContain("'read'")
+    expect(block).toContain("'write'")
+    expect(block).toMatch(/duration/)
+    // Required fields: chat_id + key. Value is NOT required (this is
+    // an access request, not a save — the agent doesn't have the
+    // value, it wants permission to read it).
+    expect(block).toMatch(/required:\s*\[\s*'chat_id',\s*'key'\s*\]/)
+  })
+
+  it('gateway accepts vault_request_access in ALLOWED_TOOLS', () => {
+    // fails when: the ALLOWED_TOOLS set is touched and the entry
+    // gets dropped. Bridge would forward the call and the gateway
+    // would reject with `tool not allowed`.
+    expect(gatewaySrc).toMatch(/ALLOWED_TOOLS[\s\S]*?'vault_request_access'/)
+  })
+
+  it('gateway routes vault_request_access in executeToolCall', () => {
+    // fails when: the switch arm is dropped. Tool would be accepted
+    // by ALLOWED_TOOLS but fall through to the `unknown tool` branch.
+    expect(gatewaySrc).toMatch(/case\s+'vault_request_access':\s*\n\s*return\s+executeVaultRequestAccess/)
+  })
+
+  it('gateway dispatches vra: callback prefix', () => {
+    // fails when: the callback_query dispatcher loses the `vra:`
+    // branch. Operator taps on [Approve] / [Deny] would fall to the
+    // catch-all "unknown callback" path and the card would stay
+    // open forever.
+    expect(gatewaySrc).toMatch(/data\.startsWith\('vra:'\)/)
+    expect(gatewaySrc).toMatch(/handleVaultRequestAccessCallback/)
+  })
+
+  it('approve handler mints via broker (not direct grants.db write)', () => {
+    // fails when: someone tries to short-circuit by writing to the
+    // grants DB directly. The broker is the single point of grant
+    // issuance — bypassing it skips audit-log emission and breaks
+    // the path-as-identity ACL contract.
+    //
+    // The mint call lives in performVaultAccessApproval — the helper
+    // factored out so both the direct-approve path AND the
+    // tap-on-locked → passphrase-resume path drive identical minting
+    // (see telegram-plugin/tests/vault-request-access-unlock-resume.test.ts).
+    const mintHelperBlock =
+      gatewaySrc
+        .split('async function performVaultAccessApproval')[1]
+        ?.split('async function handleVaultRequestAccessCallback')[0] ?? ''
+    expect(mintHelperBlock).toMatch(/mintGrantViaBroker/)
+    // Description string must carry the audit breadcrumb so post-hoc
+    // forensics can tell agent-initiated grants apart from
+    // operator-host-CLI grants and from /vault audit one-tap grants.
+    expect(mintHelperBlock).toMatch(/vault_request_access/)
+    expect(mintHelperBlock).toMatch(/#1012/)
+  })
+
+  it('duration parser enforces the 90-day ceiling', () => {
+    // fails when: the cap is removed or widened without a corresponding
+    // doc/threat-model update. Agent-initiated grants must have a
+    // finite sunset; "never" must be refused outright.
+    const execBlock = gatewaySrc.split('async function executeVaultRequestAccess')[1]?.split('async function ')[0] ?? ''
+    expect(execBlock).toMatch(/NINETY_DAYS/)
+    expect(execBlock).toMatch(/90\s*\*\s*86400/)
+  })
+
+  it('approve handler is gated on the operator allowFrom list', () => {
+    // fails when: the access check is dropped. Without this gate any
+    // chat member could approve a grant — breaks the operator-only
+    // mint authority that's load-bearing for #1012's threat model.
+    const handlerBlock = gatewaySrc.split('async function handleVaultRequestAccessCallback')[1]?.split('async function handleVaultRequestSaveCallback')[0] ?? ''
+    expect(handlerBlock).toMatch(/loadAccess\(\)/)
+    expect(handlerBlock).toMatch(/allowFrom\.includes/)
+  })
+})

package/telegram-plugin/tests/vault-request-access-unlock-resume.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Contract pin for the tap-to-unlock-and-approve flow added on top of
+ * #1012 Phase 2 (#1030 broker passphrase-attested mint_grant).
+ *
+ * Before this PR: tapping Approve on a vault_request_access card
+ * without first unlocking the vault edited the card to "🔒 Vault is
+ * locked. Run /vault unlock... then ask the agent to re-issue." The
+ * operator had to (a) clear that card, (b) /vault unlock, (c) ask
+ * the agent to re-emit the request, (d) tap Approve again. Four steps
+ * for one decision.
+ *
+ * After this PR: the cache-miss tap keeps the card open, prompts for
+ * the passphrase as the next message, captures+caches it, deletes the
+ * passphrase message from chat, then auto-resumes the mint. One tap
+ * + one reply = one grant.
+ *
+ * Mirrors the `passphrase-for-deferred` flow from #44 (deferred-secret
+ * card's "🔓 Unlock vault & save"). Same idiom, same trust posture.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+
+describe('vault_request_access — tap-to-unlock-and-approve UX', () => {
+  it('declares the passphrase-for-access-approve PendingVaultOp variant', () => {
+    // fails when: the new PendingVaultOp kind is dropped. The
+    // resume flow leans on this discriminator — without it the
+    // text handler can't route the passphrase reply back to the
+    // staged request.
+    expect(gatewaySrc).toMatch(/kind:\s*['"]passphrase-for-access-approve['"]/)
+  })
+
+  it('Approve on a locked vault stages a passphrase prompt instead of clearing the card', () => {
+    // fails when: the cache-miss branch reverts to the old behaviour
+    // of editing the card to "ask the agent to re-issue." That UX
+    // is the four-step workaround we just replaced.
+    //
+    // Anchor: the approve-action block inside handleVaultRequestAccessCallback.
+    const approveBlock =
+      gatewaySrc.split('if (action === \'approve\')')[1]?.split('await ctx.answerCallbackQuery({ text: \'Unknown action\'')[0] ?? ''
+    expect(approveBlock).toMatch(/pendingVaultOps\.set/)
+    expect(approveBlock).toMatch(/passphrase-for-access-approve/)
+    // Card text must invite a passphrase reply, not punt to a
+    // /vault unlock detour.
+    expect(approveBlock).toMatch(/Reply with your passphrase/i)
+    // The "ask the agent to re-issue the request card" copy belonged
+    // to the pre-fix path. Should be gone from the cache-miss branch.
+    expect(approveBlock).not.toMatch(/ask the agent to re-issue the request card/)
+  })
+
+  it('passphrase intercept deletes the chat message and resumes mint', () => {
+    // fails when: the new pending-op handler stops calling
+    // deleteSensitiveMessage on the passphrase message OR stops
+    // routing into performVaultAccessApproval. Both are load-bearing:
+    //   - delete: prevents the passphrase from lingering in chat history
+    //   - resume: closes the "one decision" UX promise
+    //
+    // Anchor: the text-handler branch keyed on the new kind.
+    const handlerBlock =
+      gatewaySrc
+        .split("pendingVault.kind === 'passphrase-for-access-approve'")[1]
+        ?.split("pendingVault.kind === 'grant-wizard'")[0] ?? ''
+    expect(handlerBlock).toMatch(/deleteSensitiveMessage/)
+    expect(handlerBlock).toMatch(/performVaultAccessApproval/)
+    // Cache the passphrase so future operations in the same chat
+    // don't re-prompt within the TTL window.
+    expect(handlerBlock).toMatch(/vaultPassphraseCache\.set/)
+  })
+
+  it('expired-stage path edits the card cleanly, does not silently drop', () => {
+    // fails when: the resume path forgets to handle the edge case
+    // where the staged access entry's 10-min TTL elapsed between
+    // tap-on-locked and passphrase reply. Without this branch the
+    // operator types their passphrase, gets nothing visible back,
+    // and is confused about whether their secret leaked.
+    const handlerBlock =
+      gatewaySrc
+        .split("pendingVault.kind === 'passphrase-for-access-approve'")[1]
+        ?.split("pendingVault.kind === 'grant-wizard'")[0] ?? ''
+    expect(handlerBlock).toMatch(/expired before you replied|expired/)
+    expect(handlerBlock).toMatch(/editMessageText/)
+  })
+
+  it('mint failure (e.g. wrong passphrase) edits the card; does not silent-drop', () => {
+    // fails when: performVaultAccessApproval's error branch returns
+    // without editing the card. Without the edit, a wrong-passphrase
+    // attempt leaves the locked-vault prompt on screen forever and
+    // the operator can't tell whether the system saw their reply.
+    //
+    // Anchor: performVaultAccessApproval's `result.kind === 'error'`
+    // branch.
+    const mintHelper =
+      gatewaySrc.split('async function performVaultAccessApproval')[1]?.split('async function handleVaultRequestAccessCallback')[0] ?? ''
+    expect(mintHelper).toMatch(/result\.kind === 'error'/)
+    // After error: card edited AND pending entry dropped (no
+    // zombie staged request).
+    expect(mintHelper).toMatch(/editMessageText[\s\S]{0,400}mint_grant failed/)
+    expect(mintHelper).toMatch(/pendingVaultRequestAccesses\.delete/)
+  })
+})