@open-everywhere/core 0.1.0

package/agent/access/credential-grant-flow.ts

@@ -0,0 +1,735 @@
+// The credential-grant lifecycle: the ask, the owner's answer, the mint, and the two ways a live grant dies. Every terminal state answers a prober alike, and the requester's turn never blocks on the owner.
+
+import { randomUUID } from "node:crypto";
+import { appendAudit } from "../audit/audit.js";
+import { getOperationalStore } from "../operational/provider.js";
+import {
+  mintBorrowToken,
+  ownerHasConnectorConsent,
+  readBorrowToolSchema,
+  resolveBorrowConnection,
+  startOwnerConnectorAuthorization,
+  withinBorrowDeadline,
+  borrowDeadline,
+  type BorrowConnection,
+  type GrantBorrowDeps,
+} from "../connections/grant-mcp-borrow.js";
+import {
+  credentialGrantExpiry,
+  credentialGrantFromAsk,
+  credentialGrantMintVerdict,
+  GRANT_ASK_TTL_MS,
+  type GrantMintInput,
+  type GrantMintRefusal,
+} from "./credential-grant.js";
+import {
+  approveGrantCard,
+  declineGrantCard,
+  deliverGrantCard,
+  deliverGrantConsentPrompt,
+  expireGrantCard,
+  refuseGrantCard,
+  type GrantApproveGate,
+  type GrantAskWorkerOrigin,
+  type GrantCardDelivery,
+} from "./credential-grant-card.js";
+import { grantOwnerSubject } from "./credential-grant-owner.js";
+import { grantScopeKeyForMode } from "./credential-grant-scope.js";
+import { postGrantResolution, type GrantNoticeOutcome } from "./credential-grant-resolution.js";
+import { pinFrozenArgsIntoSchema } from "./grant-schema-pin.js";
+import {
+  grantAuditResource,
+  grantBorrowResourceLabel,
+  grantFrozenArgsDigest,
+  grantToolSlug,
+  quotedPurpose,
+  type CredentialGrantAskRow,
+  type CredentialGrantMode,
+  type CredentialGrantRow,
+  type GrantJsonObject,
+} from "../operational/credential-grant-rows.js";
+
+/** The audit stamps every row on this plane carries. The caller resolves them from the partition. */
+export interface GrantAuditStamps {
+  readonly org: string;
+  readonly platform: string;
+  readonly workspace: string;
+  readonly surface?: string;
+}
+
+/** What a requester's turn hands in to raise an ask. */
+export interface AskForGrantInput extends GrantAuditStamps {
+  readonly requesterPrincipalId: string | undefined;
+  readonly requesterLabel: string;
+  readonly ownerPrincipalId: string;
+  readonly ownerPlatform: string;
+  readonly ownerNativeId: string;
+  readonly ownerHandle: string;
+  readonly connector: string;
+  /** THE VENDOR MCP TOOL this ask would lend, in the vendor's own exact bytes (OPE-1136). */
+  readonly mcpTool: string;
+  /** THE ARGUMENTS THE ASK FIXES. `{}` is a borrow that fixes nothing — a WIDER grant than a frozen
+   *  one, and the card says so out loud rather than letting silence read as narrowness. */
+  readonly frozenArgs: GrantJsonObject;
+  /** WHAT THE REQUESTER CALLS THE TARGET, in human words ("Quarterly report"). It rides into the
+   *  mounted tool name as a slug and onto the owner's card as quoted data. Model-authored. */
+  readonly targetLabel: string;
+  /** The ASKING SESSION's key — what a `once` or `session` grant binds to, and what the ask row is
+   *  filed under whatever mode the owner ends up tapping. */
+  readonly scopeKey: string;
+  /**
+   * THE ROOM'S DOMAIN-SHAPED SEAT KEY (OPE-1950), from `credential-grant-scope.ts`
+   * `grantDomainScopeKey` — what a `standing` grant binds to instead of {@link scopeKey}, so a
+   * 30-day tap outlives the seat rotations inside those 30 days.
+   *
+   * Absent when the room resolves no windowed domain. The seat then keeps the exact-session rule for
+   * what it may READ, which is the pre-OPE-1950 behaviour — and since OPE-2160 no standing grant may
+   * be MINTED from such an ask at all: the owner's card offers no 30-day arm and the mint refuses it.
+   * There is no broader seat to name, so a 30-day promise is not made rather than made narrower.
+   */
+  readonly domainScopeKey?: string;
+  /** MODEL-AUTHORED. Recorded and rendered as quoted data; never as copy. */
+  readonly purpose: string;
+  /**
+   * Where the owner's answer is reported back — a JSON {@link import("../channels/reply-post.js").ReplyTarget},
+   * resolved from the requester's SESSION BINDING. Absent on a surface with no mid-turn post arm.
+   */
+  readonly requesterTarget?: string;
+  readonly requestedMode: CredentialGrantMode;
+  /** Does the requesting room's domain declare the grant role for this connector? */
+  readonly domainGrantsConnector: boolean;
+  /**
+   * DID A PERSON ASK FOR THIS BORROW IN THEIR OWN WORDS (OPE-1978)? It is written to `detail.explicit`
+   * on the `grant.asked` row and NOTHING else: no card turns on it, no budget counts it, and no
+   * refusal reads it. The prompt owns the rule — a seat may raise an ask only on the person's word,
+   * and otherwise suggests the road once — and this field is how an operator MEASURES whether the
+   * prompt is holding.
+   *
+   * 🔴 IT IS A DETERMINISTIC READ OF THE PERSON'S DELIVERED WORDS, never a model claim: the caller
+   * resolves it from the own-account grammar's stamp (`connections/own-account-ask.ts`, carried by
+   * `connections/own-account-carriage.ts`).
+   *
+   * 🔴 WHAT THE GRAMMAR RECOGNISES. It needs a vendor word beside an ACCOUNT NOUN — "my notion
+   * account", "my own notion.so login". The seat prompt's lend trigger (`GRANTS_SECTION`,
+   * `instructions/seat-prompt.ts`) needs an account word too (OPE-2175), and its vendor-bearing example
+   * ("lend it my Notion account") reads `true`. A possessive about content ("my Notion workspace")
+   * reads `false` here and is a content ask in the prompt, so the two agree. The prompt's vendor-less
+   * examples ("use my own login") still read `false`, so read the field as a rate whose FLOOR is that,
+   * never as a verdict on one row, and never as evidence that the prompt is not holding.
+   */
+  readonly explicit: boolean;
+  /**
+   * WHO RAISED IT, when a DELEGATED WORKER did (OPE-1343). It reaches the CARD and nothing else —
+   * see {@link GrantAskWorkerOrigin} for why no row carries it. Absent ⇒ a seat raised the ask, and
+   * every byte of the card is what it was before.
+   */
+  readonly workerOrigin?: GrantAskWorkerOrigin;
+  /**
+   * THE REQUESTING ROOM'S FRIENDLY NAME (OPE-1589) — `#proj-chat`, `#proj-chat · thread "Q3"` — as
+   * the CALLER resolved it through `approvals/scope-label.ts` `friendlyScopeLabel`.
+   *
+   * 🔴 IT REACHES THE CARD AND NOTHING ELSE, exactly like {@link GrantAskWorkerOrigin}. No row
+   * carries it, nothing joins on it, and the label lookup is fail-open — so an absent one costs the
+   * card its room name and never the ask.
+   */
+  readonly conversationLabel?: string;
+  readonly nowMs: number;
+}
+
+/** What the requester's turn learns. `sent` never means "approved" — it means the owner was asked. */
+export type AskForGrantOutcome =
+  | { readonly sent: true; readonly askId: string; readonly ownerHandle: string; readonly toolName: string }
+  | {
+      readonly sent: false;
+      readonly reason: GrantMintRefusal | "owner_unreachable";
+      /**
+       * THE LIVE GRANT THAT REFUSED THIS ASK (OPE-1589) — present only on `grant_already_live`, and
+       * only so the refusal copy can say what that grant DOES and when it ends. It carries no id: the
+       * caller composes a sentence from it and never renders a field of it raw.
+       */
+      readonly liveGrant?: { readonly mcpTool: string | undefined; readonly expiresAt: string };
+    };
+
+/**
+ * Raise one ask and DM the owner's card.
+ *
+ * The mint verdict runs BEFORE the row is written, so a refused ask leaves nothing behind. The card
+ * delivery runs AFTER the row is written and BEFORE the requester is told, so a delivery failure
+ * closes the row rather than leaving a pending ask nobody was shown.
+ */
+export async function askForCredentialGrant(input: AskForGrantInput): Promise<AskForGrantOutcome> {
+  const store = getOperationalStore();
+  const nowIso = new Date(input.nowMs).toISOString();
+  // 🔴 THE ROW ID IS MINTED FIRST, BEFORE THE VERDICT (OPE-1136). The mounted name's collision suffix
+  // is a fragment of this id, so the name and the row it names have to be decided from one value.
+  // Minting it at the insert instead would spell a name out of an id no row ever carried.
+  const askId = randomUUID();
+  // `?? ""` rather than an early refusal: `borrowShape` owns the "this tool name cannot be slugified"
+  // arm, and the verdict's refusal ORDER is the contract. An empty slug simply loses there.
+  const toolSlug = grantToolSlug(input.mcpTool) ?? "";
+  // HOST-COMPOSED, from the ask's own three model-authored parts. It is what the card, the disclosure
+  // line and the refusal copy call this grant; nothing parses it back.
+  const resource = grantBorrowResourceLabel(input.targetLabel, input.mcpTool, input.frozenArgs);
+  // THE AT-MOST-ONE READ, on the BORROW key: the same tool frozen two ways is two decisions the owner
+  // made, so it is two grants. See `liveBorrowCredentialGrant` for the whole relaxation.
+  const live = await liveBorrowGrantInReach(input, grantFrozenArgsDigest(input.frozenArgs), nowIso);
+  // The anti-nag read is keyed on the requester as well as the owner, so two people asking one owner are two decisions and one person asking twice is one. It keys on the tool slug and the composed label, because the mounted name carries a per-row collision suffix and could never match.
+  const liveAsk =
+    input.requesterPrincipalId === undefined
+      ? null
+      : await store.liveCredentialGrantAsk(input.org, input.requesterPrincipalId, input.ownerPrincipalId, toolSlug, resource, nowIso);
+  const mintInput: GrantMintInput = {
+    borrow: {
+      mcpTool: input.mcpTool,
+      rowId: askId,
+      takenToolNames: await takenGrantToolNames(input.org, input.scopeKey, input.domainScopeKey, nowIso),
+      targetLabel: input.targetLabel,
+    },
+    connector: input.connector,
+    domainGrantsConnector: input.domainGrantsConnector,
+    liveAsk: liveAsk ?? undefined,
+    liveGrant: live ?? undefined,
+    ownerHandle: input.ownerHandle,
+    ownerPrincipalId: input.ownerPrincipalId,
+    requesterPrincipalId: input.requesterPrincipalId,
+  };
+  const verdict = credentialGrantMintVerdict(mintInput);
+  const requesterPrincipalId = input.requesterPrincipalId;
+  if (!verdict.ok || requesterPrincipalId === undefined) {
+    await auditGrant(input, "grant.refused", input.requesterPrincipalId, {
+      connector: input.connector,
+      gate: verdict.ok ? "unverified_requester" : verdict.reason,
+      // 🔴 NAMES, NEVER THE FROZEN VALUES. See {@link grantAuditResource}.
+      resource: grantAuditResource({ frozenArgs: input.frozenArgs, mcpTool: input.mcpTool, resource }),
+      scopeKey: input.scopeKey,
+      // OPE-1950: the domain scope the refusal was decided in. It is what an operator — and the
+      // S-DISCORD-GRANT leg — joins a `grant_already_live` refusal to the standing grant that caused
+      // it by, once that grant is domain-keyed and no longer names the asking session.
+      ...(input.domainScopeKey === undefined ? {} : { domainScopeKey: input.domainScopeKey }),
+      verb: toolSlug,
+    });
+    return {
+      reason: verdict.ok ? "unverified_requester" : verdict.reason,
+      sent: false,
+      ...(live === null || (verdict.ok ? "unverified_requester" : verdict.reason) !== "grant_already_live"
+        ? {}
+        : { liveGrant: { expiresAt: live.expiresAt, mcpTool: live.mcpTool } }),
+    };
+  }
+  const ask: CredentialGrantAskRow = {
+    connector: input.connector,
+    createdAt: nowIso,
+    expiresAt: new Date(input.nowMs + GRANT_ASK_TTL_MS).toISOString(),
+    // 🔴 THE BORROW TRIO, WRITTEN TOGETHER. `grantBorrowColumnsProblem` refuses any other spelling at
+    // the store, because the transport dials `mcpTool`, the fence pins `frozenArgs` and the mount
+    // spells `toolName` — three readers of one decision.
+    frozenArgs: input.frozenArgs,
+    id: askId,
+    mcpTool: input.mcpTool,
+    ownerNativeId: input.ownerNativeId,
+    ownerPlatform: input.ownerPlatform,
+    ownerPrincipalId: input.ownerPrincipalId,
+    // PINNED HERE, from the handle the requester's turn resolved. The card the owner reads and the
+    // tool name the chat later mounts must name the same person, and nothing downstream carries a
+    // display handle to re-derive it from.
+    ownerSlug: verdict.ownerSlug,
+    purpose: input.purpose,
+    requestedMode: input.requestedMode,
+    requesterPrincipalId,
+    // PINNED HERE, from the requester's SESSION BINDING. The owner answers minutes later from their
+    // own DM, in a request that carries no trace of the requesting room — so this column is the only
+    // thing that can name the conversation the resolution goes back to.
+    ...(input.requesterTarget === undefined ? {} : { requesterTarget: input.requesterTarget }),
+    resource,
+    scopeKey: input.scopeKey,
+    // OPE-1950: recorded beside the session key so the APPROVE path can bind a standing grant to the
+    // domain. It is written on every ask, whatever mode was requested, because the owner's card
+    // offers all three buttons and their answer is the one that decides.
+    ...(input.domainScopeKey === undefined ? {} : { domainScopeKey: input.domainScopeKey }),
+    status: "pending",
+    toolName: verdict.toolName,
+    verb: toolSlug,
+  };
+  await store.addCredentialGrantAsk(input.org, ask);
+  // `input` IS the DM road's `where` — GrantAuditStamps and DmDeliveryWhere are the same four
+  // columns, so the refusal row and the grant's own audit rows name one subject.
+  const delivery: GrantCardDelivery = await deliverGrantCard(ask, input, input.requesterLabel, input.workerOrigin, input.conversationLabel);
+  if (!delivery.delivered) {
+    // The owner was never shown the card, so the ask must not sit pending. Close it in the same
+    // breath and tell the requester the truth: this deployment cannot ask that person here.
+    await store.decideCredentialGrantAsk(input.org, ask.id, ["pending"], "expired", nowIso);
+    await auditGrant(input, "grant.refused", ask.requesterPrincipalId, {
+      askId: ask.id,
+      connector: ask.connector,
+      gate: "owner_unreachable",
+      // OPE-2063: who was asked, and in which session and domain — the fields the other
+      // `grant.refused` rows carry, so a session wait and an operator can join this row.
+      owner: ask.ownerPrincipalId,
+      reason: delivery.reason,
+      resource: grantAuditResource(ask),
+      scopeKey: ask.scopeKey,
+      ...(ask.domainScopeKey === undefined ? {} : { domainScopeKey: ask.domainScopeKey }),
+      verb: ask.verb,
+    });
+    return { reason: "owner_unreachable", sent: false };
+  }
+  // PIN WHERE THE CARD LANDED (OPE-1112). The TTL sweep runs minutes later, in a process that holds
+  // nothing from this turn, and rewriting the card to `expired` needs an address only this moment
+  // knows. Best-effort: a lost stamp costs the cosmetic rewrite, never the ask.
+  try {
+    await store.setCredentialGrantAskCard(input.org, ask.id, delivery.surfaceId, delivery.messageId);
+  } catch (err) {
+    log(`card locus for ask ${ask.id} could not be stamped: ${String(err)}`);
+  }
+  await auditGrant(input, "grant.asked", ask.requesterPrincipalId, {
+    askId: ask.id,
+    connector: ask.connector,
+    // OPE-1978, MEASUREMENT ONLY: did a person's own words ask for this borrow? Nothing downstream
+    // branches on it — see {@link AskForGrantInput.explicit} for what the grammar recognises, and why
+    // a low rate is not evidence that the prompt rule is failing.
+    explicit: input.explicit,
+    owner: ask.ownerPrincipalId,
+    purpose: quotedPurpose(ask.purpose),
+    requestedMode: ask.requestedMode,
+    resource: grantAuditResource(ask),
+    scopeKey: ask.scopeKey,
+    // OPE-1950: the scope a STANDING answer to this ask would bind to. The row names both, because
+    // the ask cannot know which button the owner will tap.
+    ...(ask.domainScopeKey === undefined ? {} : { domainScopeKey: ask.domainScopeKey }),
+    toolName: ask.toolName,
+    verb: ask.verb,
+  });
+  return { askId: ask.id, ownerHandle: ask.ownerSlug, sent: true, toolName: verdict.toolName };
+}
+
+/**
+ * THE LIVE GRANT THAT ALREADY COVERS THIS BORROW, if one does — the at-most-one read behind
+ * `grant_already_live`. It reads the asking SESSION's own rows first, then the domain's live standing
+ * rows (OPE-1950).
+ *
+ * 🔴 THE DOMAIN ARM IS THE ANTI-NAG HALF OF THE RULING. Once a standing grant is domain-keyed, the
+ * seat that rotates in next asks under a session key the grant does not carry — so without this read
+ * every rotation would put a fresh card in the owner's DM for a credential they had already lent for
+ * 30 days, which is the same defect the ruling closes, pointed at the owner instead of the seat.
+ *
+ * It WIDENS NOTHING: a refusal is the narrow direction, and the domain arm is gated on `standing` so a
+ * once- or session-mode row can never answer here.
+ */
+async function liveBorrowGrantInReach(input: AskForGrantInput, frozenArgsDigest: string, nowIso: string): Promise<CredentialGrantRow | null> {
+  const store = getOperationalStore();
+  const read = async (scopeKey: string): Promise<CredentialGrantRow | null> =>
+    await store.liveBorrowCredentialGrant(input.org, input.ownerPrincipalId, input.connector, input.mcpTool, frozenArgsDigest, scopeKey, nowIso);
+  const own = await read(input.scopeKey);
+  if (own !== null) return own;
+  const domainScopeKey = input.domainScopeKey;
+  if (domainScopeKey === undefined || domainScopeKey === input.scopeKey) return null;
+  const shared = await read(domainScopeKey);
+  return shared !== null && shared.mode === "standing" ? shared : null;
+}
+
+/**
+ * Every mounted name this chat has claimed: from its grant rows, live or dead, and from its pending asks, because a name is claimed at ask time. Two asks composed at the same instant can still pin one name, and the mount-side dedupe is the backstop for that.
+ * 🔴 IT READS THE DOMAIN'S LIVE STANDING ROWS TOO (OPE-1950). Those rows mount in this chat, so a name one of them holds is taken here — and a second grant handed the same mounted name is a tool the model cannot tell apart from the first.
+ */
+async function takenGrantToolNames(org: string, scopeKey: string, domainScopeKey: string | undefined, nowIso: string): Promise<readonly string[]> {
+  const store = getOperationalStore();
+  const names: string[] = [];
+  const claim = (row: { readonly toolName?: string }): void => {
+    if (row.toolName !== undefined) names.push(row.toolName);
+  };
+  for (const row of await store.credentialGrantsForScope(org, scopeKey)) claim(row);
+  for (const ask of await store.pendingCredentialGrantAsksForScope(org, scopeKey, nowIso)) claim(ask);
+  if (domainScopeKey !== undefined && domainScopeKey !== scopeKey) {
+    for (const row of await store.liveStandingCredentialGrantsForScope(org, domainScopeKey, nowIso)) claim(row);
+  }
+  return names;
+}
+
+/** What an owner's click resolves to. `approved` carries the grant the mount will project. */
+export type ApproveGrantOutcome =
+  | { readonly approved: true; readonly grant: CredentialGrantRow }
+  | {
+      readonly approved: false;
+      /**
+       * WHY NOTHING WAS MINTED. Four of these leave the ask ALIVE and three close it:
+       *
+       * · `not_pending_or_expired` — the CAS lost. Already answered, or past the card's TTL.
+       * · `mint_refused` — the tree changed between the card and the click (design's re-run reason).
+       * · `owner_unresolvable` — this deployment cannot name the owner's own credential row.
+       * · `consent_required` — the owner has not connected their own account yet. THE ASK STAYS
+       *   PENDING and they were sent a link; pressing Approve again after connecting works.
+       * · `catalogue_unreachable` — the connection could not be read. THE ASK STAYS PENDING, so a
+       *   network blip costs a retry rather than the owner's decision.
+       * · `tool_absent` / `frozen_args_unknown` — the owner said yes and the connection cannot honour
+       *   it. The ask is CLOSED, the card is rewritten and the requester is told.
+       * · `standing_unavailable` — the tap asked for the standing mode on an ask that carries no
+       *   domain key (OPE-2160). THE ASK STAYS PENDING, because the card's other arms are still
+       *   answerable and the owner has spent nothing. It has ONE producer, the pre-CAS check, for
+       *   exactly that reason: the post-CAS belt on the same rule answers `mint_refused`, whose copy
+       *   matches the state a burnt ask is really in.
+       */
+      readonly reason:
+        | "not_pending_or_expired"
+        | "mint_refused"
+        | "standing_unavailable"
+        | "owner_unresolvable"
+        | "consent_required"
+        | "catalogue_unreachable"
+        | GrantApproveGate;
+      /** `consent_required` only: whether the connect link actually reached the owner's DM. False
+       *  means this deployment cannot cold-address them, which the click route must say out loud
+       *  rather than telling them to check a message that was never sent. */
+      readonly prompted?: boolean;
+    };
+
+/** Longer than the ask's own TTL on purpose: a link that died before the authorization finished would strand the owner mid-flow with nothing to press. */
+const GRANT_CONSENT_LINK_TTL_MS = 60 * 60 * 1000;
+
+/** The approve CAS carries status pending and expires_at greater than the click time, so a late or second click mints nothing and nothing here re-reads the row and decides. The mode is the button the owner pressed, which may be wider than the requested one, and the owner's answer wins. */
+export async function approveCredentialGrant(
+  stamps: GrantAuditStamps,
+  askId: string,
+  mode: CredentialGrantMode,
+  approverPrincipalId: string,
+  nowMs: number,
+  standingMs?: number,
+  /** THE BORROW DIAL'S TEST SEAM, and nothing production passes. The click route calls this function
+   *  with five arguments, so the default is the real connector registry, the real user-auth flow and
+   *  the real `fetch`. A tier-1 test hands in a fake MCP server here and drives the REAL catalogue
+   *  read through it — see `connections/grant-mcp-borrow.ts`. */
+  borrowDeps: GrantBorrowDeps = {},
+): Promise<ApproveGrantOutcome> {
+  const store = getOperationalStore();
+  const nowIso = new Date(nowMs).toISOString();
+  const grantId = randomUUID();
+
+  // Both pre-CAS reads are idempotent and run before the approve CAS, so a timeout, a network failure or an unconnected owner leaves the ask exactly as it was. A read after the CAS would burn the owner's decision on a blip.
+  const pending = await store.getCredentialGrantAsk(stamps.org, askId);
+  // Not a control — the CAS below is. This is the cheap short-circuit that keeps a stale card from
+  // dialling a vendor before it loses.
+  if (pending === null || pending.status !== "pending" || pending.expiresAt <= nowIso) return { approved: false, reason: "not_pending_or_expired" };
+
+  // 🔴 THE STANDING ARM IS REFUSED WHERE NO DOMAIN KEY EXISTS (OPE-2160), and it is refused HERE —
+  // before the vendor is dialled and before the approve CAS — so the ask stays pending and the owner
+  // can still answer one of the arms the card did offer. `grantCardActions` omits the standing button
+  // on exactly this ask, so nothing a person can tap reaches this line; a forged or hand-built action
+  // id can, which is what this is for. Binding the mode to the session instead would mint a row that
+  // reads "30 days" and dies with the next seat rotation.
+  if (grantScopeKeyForMode(mode, pending.scopeKey, pending.domainScopeKey) === undefined) return { approved: false, reason: "standing_unavailable" };
+
+  const catalogue = await readApprovedToolSchema(stamps, pending, borrowDeps);
+  if (!catalogue.ok) {
+    if (catalogue.reason === "tool_absent" || catalogue.reason === "frozen_args_unknown") await closeRefusedAsk(stamps, pending, catalogue.reason, approverPrincipalId, nowIso);
+    return catalogue.reason === "consent_required"
+      ? { approved: false, prompted: catalogue.prompted, reason: "consent_required" }
+      : { approved: false, reason: catalogue.reason };
+  }
+
+  const ask = await store.approveCredentialGrantAsk(stamps.org, askId, mode, grantId, nowIso);
+  if (ask === null) return { approved: false, reason: "not_pending_or_expired" };
+  // The mint verdict runs again here because the approval is what spends the credential and the tier can move between the card and the click. The owner slug and the mounted name are read from the row, never re-derived.
+  const verdict = credentialGrantMintVerdict({
+    borrow: { mcpTool: ask.mcpTool ?? "", rowId: ask.id, takenToolNames: [], targetLabel: "" },
+    connector: ask.connector,
+    domainGrantsConnector: true,
+    // 🔴 BOTH "already live" ARMS ARE UNDEFINED ON THE APPROVE PATH, DELIBERATELY. This ask IS the
+    // pending one, so feeding it back as `liveAsk` would make the owner's own approval refuse itself;
+    // and the at-most-one GRANT rule was decided when the ask was raised. What this re-run is for is
+    // the tree CHANGING between the ask and the click, because the approval is what actually spends
+    // the credential.
+    liveAsk: undefined,
+    liveGrant: undefined,
+    ownerHandle: ask.ownerSlug,
+    ownerPrincipalId: ask.ownerPrincipalId,
+    requesterPrincipalId: ask.requesterPrincipalId,
+  });
+  if (!verdict.ok || verdict.ownerSlug !== ask.ownerSlug) return { approved: false, reason: "mint_refused" };
+  const grant = credentialGrantFromAsk(ask, {
+    expiresAt: credentialGrantExpiry(mode, nowMs, standingMs),
+    grantId,
+    // 🔴 THE SNAPSHOT IS WHAT THE CATALOGUE READ RETURNED, with the frozen arguments `const`-pinned
+    // into the vendor's own schema (`access/grant-schema-pin.ts`). It is the schema the mount offers
+    // for this grant's whole life: re-reading the vendor per mount would let a vendor widen a grant
+    // the owner had already answered.
+    inputSchema: catalogue.schema,
+    mode,
+    nowIso,
+    ownerSlug: ask.ownerSlug,
+    tier: verdict.tier,
+  });
+  // THE BELT BEHIND THE PRE-CAS REFUSAL ABOVE (OPE-2160). `credentialGrantFromAsk` is the only thing
+  // that composes a row, and it refuses a `standing` mode with no domain key — so this arm cannot be
+  // reached while the two read one rule. It is not dead: the type makes the rule unforgettable, and a
+  // future caller that skipped the pre-CAS check would land here rather than mint the forbidden row.
+  // 🔴 IT ANSWERS `mint_refused`, NOT `standing_unavailable`, AND THE DIFFERENCE IS THE ASK'S STATE
+  // (cold review). The CAS above has already moved the row to `approved`, so the owner cannot answer
+  // this card again — which is exactly what `mint_refused` means and what its copy tells them.
+  // `standing_unavailable` promises the card is still answerable, and only the PRE-CAS arm can keep
+  // that promise.
+  if (grant === undefined) return { approved: false, reason: "mint_refused" };
+  // A THROW BETWEEN THE TWO WRITES FAILS CLOSED, and it is worth naming: the ask is already
+  // `approved` and the grant row does not exist, so nothing is spendable. The requester simply raises
+  // a fresh ask — the at-most-one rule blocks on a live GRANT, never on a spent ask — and the owner
+  // sees a new card. The alternative (mint first, then CAS) would let a lost CAS leave a live grant
+  // nobody approved, which is the failure direction that must not exist.
+  await store.addCredentialGrant(stamps.org, grant);
+  await auditGrant(stamps, "grant.granted", approverPrincipalId, {
+    askId: ask.id,
+    connector: grant.connector,
+    expiresAt: grant.expiresAt,
+    grantId: grant.id,
+    mode: grant.mode,
+    owner: grant.ownerPrincipalId,
+    requester: grant.requesterPrincipalId,
+    resource: grantAuditResource(grant),
+    scopeKey: grant.scopeKey,
+    tier: grant.tier,
+    verb: grant.verb,
+  });
+  // The room notice runs after the grant row and the audit row and is fail-soft: a room that cannot be posted into must never cost a grant the owner approved. The asked mode is read from the pre-CAS row, because the CAS overwrites requested_mode with the mode the owner tapped.
+  await postGrantResolution(ask, { askedMode: pending.requestedMode, grant, kind: "approved" }, nowMs);
+  // 🔴 THE OWNER'S OWN CARD IS REWRITTEN LAST (OPE-1278). Cosmetic, like the sweep's expiry rewrite
+  // and the catalogue refusal's rewrite: the grant is already minted and the room already told, so a
+  // failed edit here must cost nothing but the stale buttons. Before this, an approve left the live
+  // card reading "Tap one button to answer" under a request that had already closed.
+  try {
+    await approveGrantCard(ask, grant, nowMs);
+  } catch (err) {
+    log(`ask ${ask.id}: the owner's card could not be rewritten after approval: ${String(err)}`);
+  }
+  return { approved: true, grant };
+}
+
+/** What the approve-time catalogue read decided. `ok` carries the schema the grant row will pin. */
+type ApprovedToolSchema =
+  | { readonly ok: true; readonly schema: GrantJsonObject }
+  | { readonly ok: false; readonly reason: "consent_required"; readonly prompted: boolean }
+  | { readonly ok: false; readonly reason: "owner_unresolvable" | "catalogue_unreachable" | GrantApproveGate };
+
+/** The tool name and the frozen arguments are model-authored, so the owner's own token reads the vendor catalogue and snapshots the granted tool's schema. Every byte goes through the fence, and an ask naming no tool returns tool_absent rather than a quiet pass. */
+async function readApprovedToolSchema(stamps: GrantAuditStamps, ask: CredentialGrantAskRow, deps: GrantBorrowDeps): Promise<ApprovedToolSchema> {
+  const mcpTool = ask.mcpTool;
+  if (mcpTool === undefined) return { ok: false, reason: "tool_absent" };
+  const frozenArgs = ask.frozenArgs ?? {};
+  const owner = await grantOwnerSubject(stamps.org, ask.connector, ask.ownerPrincipalId);
+  if (owner === undefined) return { ok: false, reason: "owner_unresolvable" };
+
+  // 🔴 ONE CLOCK FOR THE WHOLE READ. The probe, the mint, the handshake and the `tools/list` all
+  // spend this single budget, because the thing being bounded is the work held after the OWNER'S
+  // TAP is acknowledged. A separate bound for every leg would multiply the total host wait. See
+  // `BORROW_APPROVE_READ_BUDGET_MS`.
+  const deadline = borrowDeadline();
+
+  let conn: BorrowConnection;
+  try {
+    conn = resolveBorrowConnection(ask.connector, deps);
+  } catch (err) {
+    log(`ask ${ask.id}: the ${ask.connector} borrow connection could not be resolved: ${String(err)}`);
+    return { ok: false, reason: "catalogue_unreachable" };
+  }
+
+  // THE CONSENT PROBE. `false` is the only answer that stops here: `undefined` means the flow cannot
+  // answer (see `ownerHasConnectorConsent`), and treating an unknown as "not connected" would post a
+  // connect link at an owner who is already connected.
+  const consent = await withinBorrowDeadline(deadline, "the consent probe", async () => await ownerHasConnectorConsent(conn, owner.vaultSubject)).catch(
+    // A probe that failed has told us nothing. If it threw, the budget is untouched and the read proceeds; if it ran out of time, the shared budget is spent, the mint is refused by name and the ask is left pending.
+    () => undefined,
+  );
+  if (consent === false) {
+    let prompted = false;
+    try {
+      const url = await startOwnerConnectorAuthorization(conn, owner.vaultSubject, GRANT_CONSENT_LINK_TTL_MS);
+      prompted = await deliverGrantConsentPrompt(ask, stamps, url);
+    } catch (err) {
+      // 🔴 THE ERROR IS LOGGED WITHOUT THE URL. `startAuthorization` returns a capability-bearing
+      // link; a failure before it returns has none, and one after it must never carry it into a log.
+      log(`ask ${ask.id}: no ${ask.connector} connect link could be minted for the owner: ${String(err)}`);
+    }
+    return { ok: false, prompted, reason: "consent_required" };
+  }
+
+  let entry: Awaited<ReturnType<typeof readBorrowToolSchema>>;
+  try {
+    const token = await withinBorrowDeadline(deadline, "the owner's token mint", async () => await mintBorrowToken(conn, owner.vaultSubject, deps));
+    entry = await readBorrowToolSchema(conn, mcpTool, frozenArgs, token, deps, deadline);
+  } catch (err) {
+    // 🔴 UNREACHABLE IS NOT ABSENT. A timeout, a fence refusal on a malformed response, an expired
+    // authorization — none of them says the tool does not exist, and closing the ask on one would
+    // throw away an approval over a blip. The ask stays pending on its own TTL and the owner can
+    // press again.
+    log(`ask ${ask.id}: the ${ask.connector} tool catalogue could not be read: ${String(err)}`);
+    return { ok: false, reason: "catalogue_unreachable" };
+  }
+  if (!entry.found) {
+    // The names the connection DID publish are logged, never posted: they are vendor bytes, and the
+    // owner's card and the requester's notice are host-authored copy.
+    log(`ask ${ask.id}: the ${ask.connector} connection publishes no tool the ask names (${String(entry.published.length)} published)`);
+    return { ok: false, reason: "tool_absent" };
+  }
+  const pinned = pinFrozenArgsIntoSchema(entry.inputSchema, frozenArgs);
+  if (!pinned.ok) {
+    log(`ask ${ask.id}: the ask freezes ${String(pinned.unknownKeys.length)} argument(s) the ${ask.connector} tool does not declare`);
+    return { ok: false, reason: "frozen_args_unknown" };
+  }
+  return { ok: true, schema: pinned.schema };
+}
+
+/** The CAS is the decider: a row this call did not win is left entirely alone, because the sweep posts its own lapse notice and writes its own row. The three effects after it are best-effort and must never throw into an approval path. */
+async function closeRefusedAsk(
+  stamps: GrantAuditStamps,
+  ask: CredentialGrantAskRow,
+  gate: GrantApproveGate,
+  approverPrincipalId: string,
+  nowIso: string,
+): Promise<void> {
+  const won = await getOperationalStore().decideCredentialGrantAsk(stamps.org, ask.id, ["pending"], "expired", nowIso);
+  if (!won) return;
+  await auditGrant(stamps, "grant.refused", approverPrincipalId, {
+    askId: ask.id,
+    connector: ask.connector,
+    gate,
+    owner: ask.ownerPrincipalId,
+    resource: grantAuditResource(ask),
+    verb: ask.verb,
+  });
+  await postGrantResolution(ask, { gate, kind: "refused" }, Date.parse(nowIso));
+  try {
+    await refuseGrantCard(ask, gate);
+  } catch (err) {
+    log(`ask ${ask.id}: the owner's card could not be rewritten after a ${gate} refusal: ${String(err)}`);
+  }
+}
+
+/** One line of operator log for this plane. Never carries a token, a connect URL or a vendor body. */
+function log(line: string): void {
+  console.log(`[open-everywhere:grant] ${line}`);
+}
+
+/** The owner declined. A decline writes nothing but the terminal state and its row. */
+export async function declineCredentialGrant(stamps: GrantAuditStamps, askId: string, declinerPrincipalId: string, nowMs: number): Promise<boolean> {
+  const store = getOperationalStore();
+  const nowIso = new Date(nowMs).toISOString();
+  const decided = await store.decideCredentialGrantAsk(stamps.org, askId, ["pending"], "declined", nowIso);
+  if (!decided) return false;
+  await auditGrant(stamps, "grant.declined", declinerPrincipalId, { askId, reason: "declined" });
+  // The room hears "no" without hearing WHY. A person's reason for refusing their own credential is
+  // theirs, and §6.2's argument about socially-observed consent applies just as hard to a
+  // socially-observed justification. The row is re-read because `decideCredentialGrantAsk` returns
+  // only whether THIS call decided it — the notice needs the ask's pinned target.
+  const ask = await store.getCredentialGrantAsk(stamps.org, askId);
+  if (ask !== null) {
+    await postGrantResolution(ask, { kind: "declined" }, nowMs);
+    try {
+      await declineGrantCard(ask);
+    } catch (err) {
+      log(`ask ${askId}: the owner's card could not be rewritten after decline: ${String(err)}`);
+    }
+  }
+  return true;
+}
+
+/** The owner revoked a live grant. Route is recorded so the log says HOW it was revoked. */
+export async function revokeCredentialGrant(
+  stamps: GrantAuditStamps,
+  grantId: string,
+  revokerPrincipalId: string,
+  route: "thread" | "card" | "vault" | "cascade",
+  nowMs: number,
+): Promise<boolean> {
+  const store = getOperationalStore();
+  const revoked = await store.revokeCredentialGrant(stamps.org, grantId, new Date(nowMs).toISOString());
+  if (revoked) await auditGrant(stamps, "grant.revoked", revokerPrincipalId, { grantId, route });
+  return revoked;
+}
+
+/** The daily TTL sweep is a tidy-up and a notice, never a control: both CAS statements carry expires_at, so an unswept row is already unspendable. The CAS decides before any notice goes out, and asks are swept row by row because each one owes two messages to addresses only its own row holds. */
+export async function sweepCredentialGrants(org: string, nowIso: string): Promise<GrantSweepReport> {
+  const store = getOperationalStore();
+  let asks = 0;
+  let requesterNotices = 0;
+  let cardsUpdated = 0;
+  const staleBefore = new Date(Date.parse(nowIso) - GRANT_LAPSE_NOTICE_MAX_AGE_MS).toISOString();
+  for (const ask of await store.listExpiredCredentialGrantAsks(org, nowIso)) {
+    try {
+      const won = await store.decideCredentialGrantAsk(org, ask.id, ["pending"], "expired", nowIso);
+      if (!won) continue; // a click won the race — it posts its own answer and audits its own row
+      asks++;
+      // A backlog row goes terminal silently: a lapse notice is only information while somebody may still be waiting for the answer. The row always expires, and only the two messages are withheld.
+      const fresh = ask.expiresAt > staleBefore;
+      const notice: GrantSweepNotice = fresh ? await postGrantResolution(ask, { kind: "expired" }, Date.parse(nowIso)) : "withheld_stale";
+      if (notice === "sent") requesterNotices++;
+      // The card is told WHAT ACTUALLY HAPPENED to the notice. It says "the person who asked has
+      // been told" only when they were — the two are decided independently, and a card that assumed
+      // the notice landed would state a falsehood to the owner whenever it did not.
+      const cardUpdated = fresh && (await expireGrantCard(ask, notice === "sent"));
+      if (cardUpdated) cardsUpdated++;
+      // The sweep stamps a marker partition, the kind in platform and the identifier in workspace, because the ask row carries no requester partition to reuse. The notice outcome is a closed enum, since failed, no_target and withheld_stale ask different things of a reader.
+      await auditGrant({ org, platform: "grant", workspace: "sweep" }, "grant.expired", ask.requesterPrincipalId, {
+        askId: ask.id,
+        cardUpdated,
+        cause: "ttl",
+        connector: ask.connector,
+        notice,
+        owner: ask.ownerPrincipalId,
+        resource: grantAuditResource(ask),
+        verb: ask.verb,
+      });
+    } catch (err) {
+      log(`sweep: ask ${ask.id} could not be expired: ${String(err)}`);
+    }
+  }
+  return { asks, cardsUpdated, grants: await store.expireCredentialGrants(org, nowIso), requesterNotices };
+}
+
+/** How far past its expiry an ask may be and still earn a lapse notice. Wider than one sweep interval, so an ordinary late tick still notifies, while the backlog and a cron gap do not. */
+const GRANT_LAPSE_NOTICE_MAX_AGE_MS = 48 * 60 * 60 * 1000;
+
+/** The notice outcomes, plus withheld_stale, where nothing was attempted because the ask lapsed longer ago than the notice age limit. */
+type GrantSweepNotice = GrantNoticeOutcome | "withheld_stale";
+
+/** What one org's sweep did. The two notice counters are ≤ `asks`: a row whose requester pinned no
+ *  target, whose owner's surface has no edit transport, or that lapsed longer ago than
+ *  {@link GRANT_LAPSE_NOTICE_MAX_AGE_MS}, is expired without them. */
+export interface GrantSweepReport {
+  /** Asks THIS call moved `pending` → `expired`. A row a racing click decided is not counted. */
+  readonly asks: number;
+  /** Grants moved `active` → `expired` by the bulk statement. */
+  readonly grants: number;
+  readonly requesterNotices: number;
+  readonly cardsUpdated: number;
+}
+
+/** One audit row on this plane. Best-effort, like every `appendAudit` caller: a lost row never
+ *  throws into the flow it was recording. */
+export async function auditGrant(
+  stamps: GrantAuditStamps,
+  action:
+    | "grant.asked"
+    | "grant.granted"
+    | "grant.declined"
+    | "grant.expired"
+    | "grant.used"
+    | "grant.refused"
+    | "grant.revoked"
+    | "grant.notified"
+    | "grant.undisclosed"
+    // The ask verb never mounted (`tools/request_credential_grant.ts`) — a refusal one step EARLIER
+    // than every name above, where no ask exists yet to be refused.
+    | "grant.mount_refused"
+    // The BORROWED tool never mounted (`tools/grant_tools.ts`, OPE-1972) — a live standing grant the
+    // seat's attendance or grain refused. One step LATER than every name above: the grant exists and
+    // this seat is not the conversation it was tapped in.
+    | "grant.mount_withheld",
+  principalId: string | undefined,
+  detail: Readonly<Record<string, unknown>>,
+): Promise<void> {
+  await appendAudit({
+    action,
+    detail,
+    org: stamps.org,
+    platform: stamps.platform,
+    ...(principalId === undefined ? {} : { principalId }),
+    ...(stamps.surface === undefined ? {} : { surface: stamps.surface }),
+    workspace: stamps.workspace,
+  });
+}