@open-everywhere/core 0.1.0

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

@@ -0,0 +1,246 @@
+// The clicker comes from the surface's own verified interaction envelope, never from the payload, and the ask's `ownerPrincipalId` must equal it; the approve CAS re-checks pending and unexpired on top.
+// "Not yours" and "gone" give ONE answer so the button cannot confirm an ask id, and this route never throws.
+
+import { appendAudit } from "../audit/audit.js";
+import { bridgeSlackForm } from "../channels/slack-bridge.js";
+import { deploymentOrg } from "../identity/binding.js";
+import { tryPrincipalKey } from "../identity/principal-key.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { approveCredentialGrant, declineCredentialGrant, type ApproveGrantOutcome, type GrantAuditStamps } from "./credential-grant-flow.js";
+import { GRANT_MODE_WORDS, grantModePhrase, parseGrantCardActionId, type GrantCardAnswer } from "./credential-grant-card.js";
+import { connectorDisplayName, grantActionPhrase, grantExpiryPhrase } from "./credential-grant-copy.js";
+import { type CredentialGrantMode, type CredentialGrantRow } from "../operational/credential-grant-rows.js";
+
+export const GRANT_CARD_CLICK_ACTION = "grant.card_click";
+
+/** The account that tapped, as the surface's own verified interaction envelope named it. */
+export interface GrantClicker {
+  readonly platform: string;
+  /** The tenant rung a tenant-scoped platform needs. Absent/blank on a globally-scoped platform. */
+  readonly tenant?: string;
+  readonly nativeId: string;
+}
+
+export interface GrantClickResult {
+  readonly outcome: "approved" | "declined" | "not-yours" | "gone" | "failed";
+  /** The message to show ONLY the clicker. Plain text — the interaction answer has no formatter. */
+  readonly text: string;
+}
+
+export interface GrantClickInput extends GrantAuditStamps {
+  readonly askId: string;
+  readonly answer: GrantCardAnswer;
+  readonly clicker: GrantClicker;
+  readonly nowMs: number;
+}
+
+/** `clicker` MUST come from the surface's own verified interaction envelope, never from the click payload's body fields. This function cannot tell the difference, so the provider's own test pins it. */
+export async function resolveGrantCardClick(input: GrantClickInput): Promise<GrantClickResult> {
+  // At most one audit row per tap, and the floor is zero: the latch closes on the ATTEMPT, so a tap whose row was dropped and whose copy then threw leaves no row at all. Absence of a row is not evidence that no tap happened.
+  let noted = false;
+  const note = async (outcome: GrantClickResult["outcome"], failure?: GrantClickFailure): Promise<void> => {
+    if (noted) return;
+    noted = true;
+    await noteClick(input, outcome, failure);
+  };
+  try {
+    const store = getOperationalStore();
+    const ask = await store.getCredentialGrantAsk(input.org, input.askId);
+    // The clicker's key is composed through the SAME composer the mint used
+    // (identity/principal-key.ts), never a second spelling — a divergent one would compare a string
+    // that matches nobody and refuse a genuine owner.
+    const clickerKey = tryPrincipalKey(input.clicker.platform, input.clicker.tenant, input.clicker.nativeId);
+    if (ask === null || clickerKey === undefined || ask.ownerPrincipalId !== clickerKey) {
+      // ONE answer for three cases: the ask is not this person's, the ask is gone, and this
+      // deployment cannot name the clicker's tenant. See the header — splitting them makes the button
+      // an oracle.
+      await note("not-yours");
+      return { outcome: "not-yours", text: "That request is not yours to answer, or it is no longer open." };
+    }
+
+    if (input.answer === "decline") {
+      const declined = await declineCredentialGrant(input, ask.id, clickerKey, input.nowMs);
+      await note(declined ? "declined" : "gone");
+      return declined
+        ? { outcome: "declined", text: "Declined. Nothing was granted, and the conversation that asked has been told." }
+        : { outcome: "gone", text: "That request is no longer open — it was already answered, or it expired." };
+    }
+
+    const mode: CredentialGrantMode = input.answer;
+    // NO `standingMs` ARGUMENT, DELIBERATELY. A `standing` button is the CEILING, not a free span:
+    // `credentialGrantExpiry` falls to GRANT_STANDING_MAX_MS when no narrower span is given, and this
+    // route offers the owner no way to name one. The card's own label is derived from that same
+    // constant, so the button says exactly what the row will carry.
+    const approved = await approveCredentialGrant(input, ask.id, mode, clickerKey, input.nowMs);
+    if (!approved.approved) {
+      if (approved.reason === "not_pending_or_expired") {
+        await note("gone");
+        return { outcome: "gone", text: "That request is no longer open — it was already answered, or it expired." };
+      }
+      // The refusal reason goes on the audit row, not only into the owner's ephemeral text. The row and the sentence come from ONE value, so they cannot drift.
+      const prompted = approved.prompted === true;
+      await note("failed", approved.reason === "consent_required" ? { linkDelivered: prompted, reason: approved.reason } : { reason: approved.reason });
+      return { outcome: "failed", text: grantApproveFailureText(approved.reason, prompted) };
+    }
+    await note("approved");
+    return { outcome: "approved", text: grantApprovedClickText(approved.grant, input.nowMs) };
+  } catch (err) {
+    console.log(`[open-everywhere:grant] card click for ask ${input.askId} did not resolve: ${String(err)}`);
+    // A throw is an outcome and still writes a row. Its reason is the route's own (`click_threw`), never one of the approve verdicts, because the approve never returned.
+    await note("failed", { reason: "click_threw" });
+    return { outcome: "failed", text: "That could not be answered right now. Nothing changed, and nothing was granted. Try the button again." };
+  }
+}
+
+/** The approve half is derived from the copy switch's own union, so a reason with no sentence does not compile and a reason the row cannot carry does not either. `not_pending_or_expired` is excluded because it is answered as `gone`. */
+export type GrantClickFailureReason = Exclude<GrantApproveFailure["reason"], "not_pending_or_expired"> | "click_threw";
+
+interface GrantClickFailure {
+  readonly reason: GrantClickFailureReason;
+  /** `consent_required` only: whether the connect link actually reached the owner's DM. */
+  readonly linkDelivered?: boolean;
+}
+
+/** The private answer the owner reads the instant they approve. It deliberately names no mounted tool and no raw instant; `nowMs` is the click's own clock, and the golden pack pins the sentence byte for byte. */
+export function grantApprovedClickText(grant: Pick<CredentialGrantRow, "connector" | "mcpTool" | "expiresAt">, nowMs: number): string {
+  const action = grantActionPhrase(grant.connector, grant.mcpTool);
+  return (
+    `Approved. That conversation can ${action} with your ${connectorDisplayName(grant.connector)} account ${grantExpiryPhrase(grant.expiresAt, nowMs)}. ` +
+    "Nothing else is granted. I will tell you the first time it is used."
+  );
+}
+
+/** The refusing half of {@link ApproveGrantOutcome}, named so the copy below can switch on it
+ *  EXHAUSTIVELY — no `default` arm, so a new refusal reason fails to compile until somebody has
+ *  written the sentence an owner reads for it. */
+type GrantApproveFailure = Extract<ApproveGrantOutcome, { approved: false }>;
+
+/** What the owner is told when their approval minted nothing. Each arm says what happened, that it cost them nothing, and the next step; it never names an internal reason they cannot act on. */
+export function grantApproveFailureText(reason: GrantApproveFailure["reason"], prompted: boolean): string {
+  switch (reason) {
+    case "consent_required":
+      return prompted
+        ? "Not yet — I have just sent you the link to connect your account. Nothing has been granted."
+        : // Two things reach this arm, and the old copy named only one of them: the deployment cannot
+          // cold-address the owner at all, OR the owner has asked it to stop sending them direct
+          // messages and the link is a direct message (OPE-1855). The second remedy is the owner's
+          // own and an operator cannot apply it, so the sentence offers both without naming an
+          // internal reason.
+          "Your own account is not connected yet, and this deployment could not send you the link to connect it. Nothing has been granted. " +
+          "If you have asked me to stop sending you direct messages, say here that I may message you again and press Approve once more. Otherwise ask an operator to check the connector setup.";
+    case "catalogue_unreachable":
+      return "Your account could not be reached just now, so nothing was granted and nothing was spent. Press Approve again in a moment.";
+    case "tool_absent":
+      return "Your account does not offer what they asked for, so there was nothing to lend. Nothing was granted, this request is closed, and the person who asked has been told.";
+    case "frozen_args_unknown":
+      return "That request pins values the tool does not take, so the grant could never have been spent. Nothing was granted, this request is closed, and the person who asked has been told.";
+    case "owner_unresolvable":
+      // 🔴 IT LEAVES THE ASK PENDING, so "ask them to raise it again" would be wrong advice: the
+      // anti-nag rule refuses a fresh ask for the same thing while this one is open, and it stays
+      // open until its TTL. Nothing the owner does fixes it either — their account is not named in a
+      // form this deployment can resolve a credential for — so the copy points at the operator.
+      return "This deployment cannot resolve your account for that connector, so nothing could ever be spent under the grant. Nothing was granted. An operator fixes this, not another tap.";
+    case "standing_unavailable":
+      // 🔴 IT LEAVES THE ASK PENDING, so the copy sends the owner back to the card rather than telling
+      // them to ask for a fresh one (OPE-2160). That holds because the reason has exactly ONE
+      // producer, the PRE-CAS check in `credential-grant-flow.ts`; the post-CAS belt on the same rule
+      // answers `mint_refused`, whose own sentence says to raise a fresh ask. The card for such an ask
+      // never rendered this button, so the sentence says what IS answerable and why the long arm is
+      // missing — an owner who taps a button that was not offered is owed the reason, not a bare "no".
+      return (
+        `A grant for ${GRANT_MODE_WORDS.standing} needs a room this deployment can name, and this request did not come from one — ` +
+        "so it would stop working the moment that conversation ends. Nothing was granted and nothing was spent. " +
+        `Approve ${grantModePhrase("once")} or ${grantModePhrase("session")} on the same card instead, or ask an operator to declare that room into a domain.`
+      );
+    case "not_pending_or_expired":
+    case "mint_refused":
+      // `not_pending_or_expired` never reaches here, because the caller answers it with its own `gone` outcome. It is listed so the switch stays exhaustive over the union rather than over the arms that reach it today.
+      return "That could not be granted. Nothing changed, and nothing was granted. Ask them to raise it again.";
+  }
+}
+
+// The Slack door: the front route decides only whether the action id is ours, and never learns who the owner is. Everything below that happens here.
+
+/** The Slack interactivity fields this door reads, and deliberately nothing else. */
+interface SlackGrantClickPayload {
+  readonly actions?: readonly { readonly action_id?: unknown }[];
+  readonly user?: { readonly id?: unknown };
+  readonly channel?: { readonly id?: unknown };
+  readonly team?: { readonly id?: unknown };
+}
+
+export type GrantClickEphemeral = (channelId: string, userId: string, text: string) => Promise<void>;
+
+async function bridgeEphemeral(channelId: string, userId: string, text: string): Promise<void> {
+  const body = new URLSearchParams({ channel: channelId, text, user: userId });
+  await bridgeSlackForm("chat.postEphemeral", body.toString());
+}
+
+/** The clicker is the signed payload's `user.id`, never a button value, and the org is `deploymentOrg()`, never a payload field, so a replayed body can choose neither the approver nor the tenant. False means "not ours"; every other path returns true. */
+export async function handleGrantCardClick(payload: unknown, deps: { readonly ephemeral?: GrantClickEphemeral } = {}): Promise<boolean> {
+  const p = payload as SlackGrantClickPayload | null | undefined;
+  const first = p?.actions?.[0];
+  const actionId = typeof first?.action_id === "string" ? first.action_id : undefined;
+  const parsed = parseGrantCardActionId(actionId);
+  if (parsed === undefined) return false; // not ours
+  const answer = deps.ephemeral ?? bridgeEphemeral;
+  try {
+    const clickerId = typeof p?.user?.id === "string" ? p.user.id : undefined;
+    const channelId = typeof p?.channel?.id === "string" ? p.channel.id : undefined;
+    const teamId = typeof p?.team?.id === "string" ? p.team.id : undefined;
+    if (clickerId === undefined || channelId === undefined) {
+      console.error(`[open-everywhere:grant] malformed grant click "${String(actionId)}" — no user or channel; ignoring`);
+      return true; // it WAS ours — fail soft, never forward a half-understood payload
+    }
+    const result = await resolveGrantCardClick({
+      answer: parsed.answer,
+      askId: parsed.askId,
+      // The tenant rung: Slack person ids are issued PER WORKSPACE, so a key composed without the
+      // team id names nobody and every owner check would refuse. `tryPrincipalKey` returns undefined
+      // on a blank tenant, which `resolveGrantCardClick` reports as "not yours" — the fail-CLOSED
+      // direction, and the honest one.
+      clicker: { nativeId: clickerId, platform: "slack", ...(teamId === undefined ? {} : { tenant: teamId }) },
+      nowMs: Date.now(),
+      org: deploymentOrg(),
+      platform: "slack",
+      surface: channelId,
+      workspace: teamId ?? "unknown",
+    });
+    // THE ANSWER IS EPHEMERAL — visible to the owner alone. The owner's DM is a 1:1, so a public post
+    // there would be visible only to them anyway; the ephemeral is what keeps that true if a card is
+    // ever delivered anywhere else. Best-effort: the decision already stands, and a lost notice costs
+    // the owner an explanation, never the outcome.
+    await answer(channelId, clickerId, result.text).catch((err: unknown) => {
+      console.error(`[open-everywhere:grant] grant click answer failed to post: ${String(err)}`);
+    });
+    return true;
+  } catch (err) {
+    console.error(`[open-everywhere:grant] grant click "${String(actionId)}" did not resolve: ${String(err)}`);
+    return true;
+  }
+}
+
+/** One audit row per tap — ids, the outcome and, on a `failed` one, WHY. Never the purpose and never
+ *  a credential: the reason is a closed host-authored enum, so no vendor or model bytes ride it.
+ *  Best-effort: a click must not fail because a row could not be written. */
+async function noteClick(input: GrantClickInput, outcome: GrantClickResult["outcome"], failure?: GrantClickFailure): Promise<void> {
+  try {
+    await appendAudit({
+      action: GRANT_CARD_CLICK_ACTION,
+      detail: {
+        answer: input.answer,
+        askId: input.askId,
+        clicker: input.clicker.nativeId,
+        outcome,
+        ...(failure === undefined ? {} : { reason: failure.reason }),
+        ...(failure?.linkDelivered === undefined ? {} : { linkDelivered: failure.linkDelivered }),
+      },
+      org: input.org,
+      platform: input.platform,
+      workspace: input.workspace,
+      ...(input.surface === undefined ? {} : { surface: input.surface }),
+    });
+  } catch (err) {
+    console.warn(`[open-everywhere:audit] ${GRANT_CARD_CLICK_ACTION} row was not written: ${String(err)}`);
+  }
+}

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

@@ -0,0 +1,338 @@
+// The phrases every user-facing grant message is built from: no grant string may carry a minted `grant__` name, a raw platform id, a uuid or an ISO instant, and the copy test reds when one survives. The rule is about the HOST's ids, never the requester's data — the frozen arguments are still shown in full.
+
+// TYPE-ONLY, and it must stay that way: `operational/credential-grant-rows.ts` imports this module at
+// RUNTIME for its own phrases, so a value import here would close the loop.
+import type { CredentialGrantMode } from "../operational/credential-grant-rows.js";
+
+/** The vendor's name as a person writes it. An id this tree has no reviewed spelling for capitalises rather than guessing a brand name. */
+const CONNECTOR_DISPLAY_NAMES: Readonly<Record<string, string>> = {
+  notion: "Notion",
+};
+
+/** `notion` → `Notion`. Never an id the reader has to decode. */
+export function connectorDisplayName(connector: string): string {
+  const known = Object.prototype.hasOwnProperty.call(CONNECTOR_DISPLAY_NAMES, connector) ? CONNECTOR_DISPLAY_NAMES[connector] : undefined;
+  if (known !== undefined) return known;
+  const flat = labelWithoutIds(connector);
+  return flat.length === 0 ? "that connector" : `${flat.slice(0, 1).toUpperCase()}${flat.slice(1)}`;
+}
+
+/** The reviewed translation of one vendor tool into what it does; extend it in the same diff as `GRANT_DEFAULT_TOOLS`. The fallback says "read" because borrowShape refuses every tier but `read`. */
+const GRANT_ACTION_PHRASES: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  notion: { "notion-fetch": "read a Notion page" },
+};
+
+function reviewedActionPhrase(connector: string, mcpTool: string | undefined): string | undefined {
+  const perConnector = Object.prototype.hasOwnProperty.call(GRANT_ACTION_PHRASES, connector) ? GRANT_ACTION_PHRASES[connector] : undefined;
+  if (perConnector === undefined || mcpTool === undefined) return undefined;
+  return Object.prototype.hasOwnProperty.call(perConnector, mcpTool) ? perConnector[mcpTool] : undefined;
+}
+
+/** What a grant of `mcpTool` on `connector` lets a conversation DO, for a human. Never a tool id. */
+export function grantActionPhrase(connector: string, mcpTool: string | undefined): string {
+  return reviewedActionPhrase(connector, mcpTool) ?? `read one thing in ${connectorDisplayName(connector)}`;
+}
+
+/** Is the action phrase the reviewed one, or the generic floor? The floor is true of every read tool the vendor publishes, so the card says so out loud and steers to decline — never by printing the vendor's tool id instead. */
+export function grantActionIsReviewed(connector: string, mcpTool: string | undefined): boolean {
+  return reviewedActionPhrase(connector, mcpTool) !== undefined;
+}
+
+/**
+ * WHICH ARGUMENTS OF A REVIEWED VENDOR TOOL NAME ITS TARGET, and what that target is called.
+ *
+ * 🔴 IT IS A REVIEWED TABLE, NOT AN INFERENCE, AND THAT IS THE WHOLE CONTROL (cold review, OPE-2018).
+ * "The grant freezes at least one argument" is NOT "the grant is pinned to one target":
+ * `access/grant-schema-pin.ts` pins the frozen keys and leaves every other declared property free,
+ * and `access/mcp-call-fence.ts` enforces exactly that set. A grant that froze a `filter` and left
+ * `id` open would let the model choose the page — so a sentence spelled off the key COUNT would tell
+ * the model to present page Y as the target the grant named, which is the defect this ticket exists
+ * to close, re-created in the host's own voice.
+ *
+ * So only a pair this deployment has REVIEWED can be said to be pinned, and only when EVERY key named
+ * here is frozen. Extend it in the same diff as {@link GRANT_ACTION_PHRASES}: the two describe one
+ * vendor tool, and a pair reviewed for a verb but not for its target would say "read a Notion page"
+ * and then claim a pin it cannot check.
+ */
+const GRANT_PINNED_TARGETS: Readonly<Record<string, Readonly<Record<string, { readonly noun: string; readonly keys: readonly string[] }>>>> = {
+  notion: { "notion-fetch": { keys: ["id"], noun: "Notion page" } },
+};
+
+function reviewedTarget(connector: string, mcpTool: string | undefined): { readonly noun: string; readonly keys: readonly string[] } | undefined {
+  const perConnector = Object.prototype.hasOwnProperty.call(GRANT_PINNED_TARGETS, connector) ? GRANT_PINNED_TARGETS[connector] : undefined;
+  if (perConnector === undefined || mcpTool === undefined) return undefined;
+  return Object.prototype.hasOwnProperty.call(perConnector, mcpTool) ? perConnector[mcpTool] : undefined;
+}
+
+/**
+ * Does this grant pin the TARGET of its lent tool — not merely some argument of it?
+ *
+ * True only for a reviewed (connector, tool) pair whose every target key is frozen. Everything else
+ * answers false, including a pair this deployment carries no reviewed description for: there the host
+ * cannot say which argument names the target, and a guess is worse than silence.
+ *
+ * TWO CALLERS, ONE ANSWER. `tools/grant_tools.ts` spends it on the description's pin sentence AND on
+ * whether the reply footer may name the grant's target as the source that was fetched. The two must
+ * never disagree — a footer naming a target the call did not have to use is a host-vouched false
+ * source, which `channels/reply-provenance.ts` calls worse than no footer at all.
+ */
+export function grantTargetIsPinned(connector: string, mcpTool: string | undefined, frozenKeys: readonly string[]): boolean {
+  const target = reviewedTarget(connector, mcpTool);
+  return target !== undefined && target.keys.every((key) => frozenKeys.includes(key));
+}
+
+/**
+ * WHAT A CONST-PINNED LENT TOOL READS, AND WHERE TO GO FOR ANYTHING ELSE (OPE-2018).
+ *
+ * The MODEL reads this in its own tool list, beside the schema's `const`. The `const` names the one
+ * value the fence admits. It does not say that the tool answers about that ONE target and no other,
+ * and it names no other road. A seat holding a page-pinned Notion grant therefore called the lent
+ * tool for a DIFFERENT page and then presented the pinned page's body as the page it was asked about
+ * (leg 023, boards #227 and #228, 2026-09-21). So this sentence states the bound in words, and it
+ * names the road the 2026-09-19 precedence ruling sends org work down: the organisation's own
+ * connector.
+ *
+ * `targetLabel` is the REQUESTER'S OWN WORDS, recovered from the row's `resource` column and already
+ * bounded by `quotedPurpose` when that column was composed. It renders as quoted data, exactly as
+ * the owner's card renders it, and it is NOT run through {@link grantDisplayLabel}: a requester who
+ * pinned a uuid must read it back in full, which is the same rule the card keeps. `undefined` means
+ * the column holds no recoverable label; the sentence then names the fixed arguments, which the
+ * schema spells out in full beside it.
+ *
+ * `undefined` when {@link grantTargetIsPinned} says this grant does not pin its tool's target. The
+ * caller then says nothing about a pin, because there is no true sentence to say.
+ */
+export function grantPinnedTargetSentence(connector: string, mcpTool: string | undefined, targetLabel: string | undefined, frozenKeys: readonly string[]): string | undefined {
+  const target = reviewedTarget(connector, mcpTool);
+  if (target === undefined || !grantTargetIsPinned(connector, mcpTool, frozenKeys)) return undefined;
+  const vendor = connectorDisplayName(connector);
+  const one = targetLabel === undefined || targetLabel.length === 0 ? `the one ${target.noun} its fixed arguments name` : `the ${target.noun} "${targetLabel}"`;
+  const other = `any other ${target.noun}`;
+  return (
+    `PINNED TO ONE TARGET: this tool reads exactly ${one}, and nothing else. ` +
+    `Use this organisation's own ${vendor} connector for ${other}. ` +
+    `This tool cannot reach ${other}. What it returns describes ${one} — never present it as ${other}.`
+  );
+}
+
+/** The four shapes a user-facing grant string may never carry: a minted tool name, a bare snowflake, a uuid, an ISO instant. A runtime guard as well as a lint, because two inputs are display labels resolved by other planes. */
+export const GRANT_ID_LEAK_PATTERNS: readonly { readonly name: string; readonly re: RegExp }[] = [
+  { name: "a minted tool name", re: /grant__/u },
+  { name: "a bare 17-20 digit id", re: /(?<![\w-])\d{17,20}(?![\w-])/u },
+  { name: "a uuid", re: /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/iu },
+  { name: "an ISO instant", re: /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/u },
+];
+
+/** One display label, or the empty string when it carries a leak shape. It flattens and does NOT strip quotes — a quoted room label and a name like O'Brien are legitimate — but removes newlines and a runaway length. */
+function labelWithoutIds(label: string | undefined): string {
+  const flat = (label ?? "").replace(/[\r\n]+/gu, " ").trim().slice(0, LABEL_MAX);
+  return GRANT_ID_LEAK_PATTERNS.some(({ re }) => re.test(flat)) ? "" : flat;
+}
+
+/** How long a display label may be before this module cuts it. A bound rather than a taste: a label
+ *  comes off another plane, and a card is a message with a platform cap. */
+const LABEL_MAX = 120;
+
+/** The asking conversation, named from a friendly surface label and rendered as quoted data. The fallback names no id: a failed label lookup is no reason to print a snowflake at somebody. */
+export function grantConversationPhrase(label: string | undefined): string {
+  const flat = labelWithoutIds(label);
+  return flat.length === 0 ? "that conversation" : `the ${flat} conversation`;
+}
+
+/** The person who asked, by display name, or a phrase admitting this deployment cannot name them. Never the principal key — the `grant.asked` audit row still carries it. */
+export function grantRequesterPhrase(label: string | undefined): string {
+  return grantDisplayLabel(label) ?? "Someone this deployment cannot name";
+}
+
+/** One display label, guarded, because a label comes off another plane that may answer with a platform id. It returns `undefined` rather than a phrase, since its two callers disagree about the fallback. */
+export function grantDisplayLabel(label: string | undefined): string | undefined {
+  const flat = labelWithoutIds(label);
+  return flat.length === 0 ? undefined : flat;
+}
+
+/** The credential owner by handle, or `the owner` when nothing readable is held; the fallback is reachable, because the handle itself falls back to the native platform id. Lower case: callers spend it mid-sentence. */
+export function grantOwnerPhrase(ownerSlug: string | undefined): string {
+  const flat = labelWithoutIds(ownerSlug);
+  return flat.length === 0 ? "the owner" : flat;
+}
+
+/** One instant as a room reads it: a clock time in UTC, never the ISO instant, and no date, because this notice fires on the call it discloses. `undefined` on an unparsable stamp, never the raw bytes. */
+export function grantClockPhrase(atIso: string): string | undefined {
+  const at = Date.parse(atIso);
+  if (!Number.isFinite(at)) return undefined;
+  const d = new Date(at);
+  return `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())} UTC`;
+}
+
+/** How long a grant lasts in a person's terms. The clock is UTC and says so, a span past 36 hours also carries the date, and an unparsable stamp names no time rather than printing the raw column. */
+export function grantExpiryPhrase(expiresAtIso: string, nowMs: number): string {
+  const at = Date.parse(expiresAtIso);
+  if (!Number.isFinite(at)) return "until it expires";
+  const remaining = at - nowMs;
+  if (remaining <= 0) return "until it expires (it already has)";
+  return `for the next ${grantSpanWords(remaining)} (until ${grantClockWords(new Date(at), remaining)})`;
+}
+
+/**
+ * HOW LONG A GRANT REALLY RUNS — THE ONE SPELLING (OPE-2160), for every surface that states a live
+ * grant's span to a person or to the model.
+ *
+ * 🔴 A `standing` ROW WHOSE KEY IS NOT CONVERSATION-STABLE NEVER READS IN DAYS. Such a row binds to
+ * one eve session and dies when that session rotates — 7 days, a 12-hour quiet gap, a turn or token
+ * backstop, or any deploy that changes the eve build — while its `expiresAt` column still carries
+ * `GRANT_STANDING_MAX_MS`. Reading the column alone told the model, and through it the room, that a
+ * dead-on-rotation grant had 30 days left. `grantScopeKeyForMode` refuses to MINT that row now, so
+ * this arm speaks for the rows minted before the refusal existed, and it is the belt behind it.
+ *
+ * `conversationStable` is `grantScopeKeyIsConversationStable` (`credential-grant-key-shape.ts`) of
+ * the ROW's own `scopeKey` — never of the ask's `domainScopeKey`, which is a different question with
+ * the opposite fail-closed direction.
+ *
+ * 🔴 EVERY SURFACE THAT STATES A LIVE GRANT'S SPAN CALLS THIS, and there are three: the lent tool's
+ * description and its cache fingerprint (`tools/grant_tools.ts`), the owner's first-use direct message
+ * (`credential-grant-notice.ts`) and the disclosure line every granted call puts in the room
+ * (`operational/credential-grant-rows.ts` `credentialGrantDisclosureLine`). A fourth surface that
+ * states a span belongs here too. {@link grantExpiryPhrase} stays the renderer underneath and is what
+ * a caller uses when it holds an EXPIRY and no row — the approve-time surfaces, which cannot mint the
+ * dishonest row at all.
+ *
+ * 🔴 `once` AND `session` KEEP THE COLUMN'S SPAN, and that is not an oversight. Their own mode word
+ * already tells the reader the grant belongs to one call or to one conversation, and their ceilings —
+ * one hour and twelve hours — are inside a seat generation rather than many times longer than one.
+ * The defect this function exists for is a span the key cannot carry, and only `standing` has one.
+ */
+export function grantSpanPhrase(facts: { readonly mode: CredentialGrantMode; readonly conversationStable: boolean; readonly expiresAt: string; readonly nowMs: number }): string {
+  if (facts.mode === "standing" && !facts.conversationStable) return GRANT_SESSION_BOUND_SPAN;
+  return grantExpiryPhrase(facts.expiresAt, facts.nowMs);
+}
+
+/** What a session-bound grant's span is honestly called. No number: the span is one conversation's
+ *  life, which nothing here can measure in hours. */
+export const GRANT_SESSION_BOUND_SPAN = "for as long as this conversation lasts, and no longer";
+
+/** A span of milliseconds as the one unit a reader would use. Rounded — a grant's ceiling is a round
+ *  number of hours or days, and "11.98 hours" reads as a machine talking. */
+function grantSpanWords(ms: number): string {
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 90) return plural(Math.max(1, minutes), "minute");
+  const hours = Math.round(ms / 3_600_000);
+  if (hours < 36) return plural(hours, "hour");
+  return plural(Math.round(ms / 86_400_000), "day");
+}
+
+/** `22:29 UTC`, and `8 Oct, 22:29 UTC` once the span is long enough that a bare clock time would read
+ *  as today. UTC is named rather than assumed — see {@link grantExpiryPhrase}. */
+function grantClockWords(at: Date, remainingMs: number): string {
+  const clock = `${pad(at.getUTCHours())}:${pad(at.getUTCMinutes())} UTC`;
+  if (remainingMs < 36 * 3_600_000) return clock;
+  return `${String(at.getUTCDate())} ${MONTHS[at.getUTCMonth()] ?? ""}, ${clock}`;
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+
+function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+function plural(n: number, unit: string): string {
+  return `${String(n)} ${unit}${n === 1 ? "" : "s"}`;
+}
+
+/** One live grant as the owner reads it: what it can do, how long, and the reason they were given. Nothing names the chat, since no stored row carries a friendly label; `quotedPurpose` arrives already sanitised. */
+export interface GrantHoldingFacts {
+  readonly connector: string;
+  readonly mcpTool: string | undefined;
+  /** The requester's own sentence, already run through `quotedPurpose`. Rendered as quoted data. */
+  readonly quotedPurpose: string;
+  readonly expiresAt: string;
+  readonly nowMs: number;
+}
+
+/** One live grant in a clause — THE one rendering, spent by both the owner's numbered list and the confirmation that names what ended, so the two cannot drift. */
+export function grantHoldingPhrase(facts: GrantHoldingFacts): string {
+  const action = grantActionPhrase(facts.connector, facts.mcpTool);
+  const reason = facts.quotedPurpose.length === 0 ? "" : ` They asked for it to "${facts.quotedPurpose}".`;
+  return `${action.slice(0, 1).toUpperCase()}${action.slice(1)}, ${grantExpiryPhrase(facts.expiresAt, facts.nowMs)}.${reason}`;
+}
+
+/** What the owner reads when they hold no live grant; it never reads as a failure. It claims only what was QUERIED — the account they are messaging from — because a grant can be owned by their key on another platform. */
+export const GRANT_NONE_LIVE_TEXT =
+  "I can see nothing you are lending from the account you are messaging me with. If you approved a grant from a different account, ask me there.";
+
+/** One grant a revoke ended, as the owner's confirmation renders it. `told` is the OUTCOME of the borrowing room's notice, never the intention to send one. */
+export interface GrantRevokedHolding {
+  readonly phrase: string;
+  /** TRUE only when the borrowing conversation actually received its notice. */
+  readonly told: boolean;
+}
+
+/** The owner's confirmation after a revoke: it names each grant that ended and whether its room was reached, and states what remains even when that is nothing. The numbers are NEW, because ending a grant renumbers the list. */
+export function grantRevokedOwnerText(ended: readonly GrantRevokedHolding[], remaining: readonly string[]): string {
+  // The empty answer reprints the live list: nothing matched almost always because the grant already ended, and the fresh list is what the reader would otherwise ask for next.
+  const rest = remainingText(remaining);
+  if (ended.length === 0) {
+    return `Nothing was ended — none of what you named is still live. It may have ended already, or run out.\n\n${rest}`;
+  }
+  const lead = ended.length === 1 ? "That grant is ended." : `${String(ended.length)} grants are ended.`;
+  const one = ended.length === 1;
+  const untold = ended.filter((holding) => !holding.told).length;
+  // The room post is BEST-EFFORT, so this clause reports what happened and never what was attempted. The refusal half is always true and is stated unconditionally: the grant is ended in the store before any post is tried.
+  const toldClause =
+    untold === 0
+      ? `The conversation that held ${one ? "it" : "them"} has been told, and the next call it tries is refused.`
+      : untold === ended.length
+        ? `I could not reach the conversation that held ${one ? "it" : "them"}, so ${one ? "it has" : "they have"} not been told. The next call ${one ? "it tries is" : "they try is"} refused either way.`
+        : "I told the conversations I could reach and marked the rest below. The next call any of them tries is refused either way.";
+  const what = ended.map((holding) => (holding.told ? `• ${holding.phrase}` : `• ${holding.phrase} — not told, I could not reach that conversation`)).join("\n");
+  return `${lead} ${toldClause}\n${what}\n\n${rest}`;
+}
+
+/** What the owner still lends, numbered — the tail of every revoke answer, including one that ended
+ *  nothing. One renderer, so the two answers cannot disagree about what is left. */
+function remainingText(remaining: readonly string[]): string {
+  if (remaining.length === 0) return "You are not lending your account to anything now.";
+  return [
+    `You still lend ${remaining.length === 1 ? "one grant" : `${String(remaining.length)} grants`}:`,
+    ...remaining.map((phrase, i) => `${String(i + 1)}. ${phrase}`),
+    "These numbers are NEW — ending a grant renumbers the rest. Use the numbers in this list, never the ones from before.",
+  ].join("\n");
+}
+
+/** The borrowing room's notice. It says the owner ended the grant and never why, and it does not promise the tool disappears: the mount projects existence, so the borrowed tool still appears and every call on it is refused. */
+export function grantRevokedRoomText(connector: string, mcpTool: string | undefined): string {
+  return (
+    `The owner has ended the credential grant this conversation held — it can no longer ${grantActionPhrase(connector, mcpTool)} with their ` +
+    `${connectorDisplayName(connector)} account. The borrowed tool may still appear in your tool list; every call on it is now refused. ` +
+    "Do not ask for it again unless somebody here asks you to."
+  );
+}
+
+/** Who is reading a refusal. The credential owner reads "you"; anyone else reads the owner's name. */
+export type GrantCopyAudience = "owner" | "seat";
+
+export interface GrantDuplicateFacts {
+  readonly connector: string;
+  readonly mcpTool: string | undefined;
+  /** The live grant's expiry, as the row carries it. Rendered as a duration and a clock time, never
+   *  as the instant itself. Absent when the caller could not read the live row. */
+  readonly expiresAt: string | undefined;
+  readonly nowMs: number;
+  /** The owner's display name, for the `seat` audience. The `owner` audience says "you". */
+  readonly ownerLabel: string | undefined;
+  readonly conversationLabel: string | undefined;
+}
+
+/** The duplicate refusal, in two audiences decided from the PRINCIPAL KEYS by the caller, never from prose. The last sentence is audience-split because only the OWNER can end a grant early. */
+export function grantDuplicateRefusalText(audience: GrantCopyAudience, facts: GrantDuplicateFacts): string {
+  const action = grantActionPhrase(facts.connector, facts.mcpTool);
+  const when = facts.expiresAt === undefined ? "" : `, ${grantExpiryPhrase(facts.expiresAt, facts.nowMs)}`;
+  const holder = grantConversationPhrase(facts.conversationLabel);
+  const from = audience === "owner" ? "from you" : `from ${grantRequesterPhrase(facts.ownerLabel)}`;
+  // Say "while this one is live", never "until it expires": a ONCE grant is spent by its own first call and the at-most-one read matches `status='active'` alone, so the next ask is admitted well before the expiry.
+  const again =
+    audience === "owner"
+      ? "You can end it early — send me a direct message and ask. Until then a new request stays refused while this one is live."
+      : `Only ${grantRequesterPhrase(facts.ownerLabel)} can end it early, so a new request stays refused while this one is live.`;
+  const lead = holder === "that conversation" ? "That conversation" : holder.replace(/^the /u, "The ");
+  return `${lead} already has this grant ${from} (${action}${when}). Nothing new was requested — use the grant that is already there. ${again}`;
+}