@open-everywhere/core 0.1.0

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

@@ -0,0 +1,306 @@
+// What a credential grant BINDS TO, per mode (OPE-1950, narrowed by OPE-1972, extended to the solo topology by OPE-2012). `once` and `session` bind to the asking eve session and die with it; `standing` binds to the OWNER and to THE ROOM'S OWN CONVERSATION, and survives a seat rotation inside it.
+// 🔴 THIS FILE WIDENS ONE AXIS AND NOTHING ELSE. A standing grant still names one org, one owner, one connector, one vendor tool and one frozen-argument set — every one of those rides the ROW, so no lookup here can reach across them. What changes is the scope key alone: a conversation-stable key instead of a session id.
+// 🔴 AND THE KEY NAMES A CONVERSATION, NOT A DOMAIN'S WHOLE TRAFFIC (OPE-1972). A tapped card is one person's consent given in one conversation, so a key is admitted only where that conversation is the one running: an ATTENDED turn on the seat that IS the room's own conversation. A thread seat, a one-shot routine fire and a job wake all carry the room's name and are none of them that conversation, so they keep the exact-session rule for what they READ — and, since OPE-2160, are offered no 30-day arm to mint at all.
+// 🔴 THE ROOM'S OWN CONVERSATION HAS TWO SHAPES, AND WHICH ONE A ROOM HAS DEPENDS ON WHETHER IT IS SEATED (OPE-2012). A room the standing-seat capability SEATS has the domain's STANDING seat as its conversation, and the key names the domain. A room it does not seat — which is every room while `window.topology` is unarmed, the shipped default — has no seat at all (`memory/domain.ts` `windowedSupervisorEnabled`), so its own wake classifies `native` and the key names THAT ROOM: `oe-grant-room::<domain>::<room key>`. Both facts are required, so a `native` wake in a SEATED room (a routing regression, or the runtime privacy floor standing the seat down) mints nothing and keeps the exact-session rule exactly as it did before this arm existed; since OPE-2160 such a seat is offered no 30-day arm either.
+// 🔴 AND THE ROOM KEY'S BOUNDARY IS THE ROOM, THREADS INCLUDED — NOT THE ROOM'S MAIN CONVERSATION. An unseated deployment stamps no grain at all, so a platform thread reply classifies `native` like every other wake, and `domainKeyOf` collapses a thread onto its parent room anyway. Nothing there can tell a thread from the room, so the key claims no boundary it cannot keep. It is still strictly NARROWER than the domain key, which reaches every room declared into the domain — the cross-room reach board #226 leg 51 measured stays shut.
+
+import { bindFrom, isSubagentChildContext, stampedWindowGrainOf, unattendedFrom, windowGrainOf, type BindableContext, type WindowGrain } from "../identity/binding.js";
+import { domainForChannel, windowedSupervisorEnabled } from "../memory/domain.js";
+import { domainKeyOf, resolvePartition } from "../memory/partition.js";
+import type { CredentialGrantMode, CredentialGrantRow } from "../operational/credential-grant-rows.js";
+import { getConfig } from "./config.js";
+// 🔴 THE KEY'S SHAPE LIVES IN A LEAF MODULE (OPE-2160). A stored ROW has to read the same shapes —
+// `operational/credential-grant-rows.ts` states a span against them — and importing THIS module from
+// there would close a cycle through `memory/domain.ts`. The prefixes are spelled once, over there.
+import {
+  GRANT_DOMAIN_KEY_PREFIX,
+  GRANT_KEY_SEGMENT_SEPARATOR,
+  GRANT_ROOM_KEY_PREFIX,
+} from "./credential-grant-key-shape.js";
+
+/**
+ * THE GRAIN THAT IS A SEATED ROOM'S OWN CONVERSATION (OPE-1972) — the domain's STANDING seat, which
+ * is the only seat that spans a domain's rooms.
+ *
+ * 🔴 IT IS A WHITELIST, NOT A BLACKLIST OF THE GRAINS WE HAPPEN TO KNOW ABOUT. `thread` is the grain
+ * every triggered fire lands on (`routines/fire-window.ts` `TRIGGERED_FIRE_GRAIN`) as well as every
+ * thread a seated deployment stamps, and `task` is the delegated worker. Naming the admitted grains
+ * means a fifth grain refuses rather than inherits.
+ */
+const GRANT_CONVERSATION_GRAIN: WindowGrain = "standing";
+
+/**
+ * THE GRAIN AN UNSEATED ROOM'S OWN CONVERSATION CARRIES (OPE-2012) — everything, because an unseated
+ * deployment stamps no grain and every token it mints classifies `native`.
+ *
+ * 🔴 IT IS ADMITTED ON A NARROWER KEY, AND ONLY WHERE THE ROOM HAS NO SEAT, WHICH IS WHY IT IS
+ * ADMITTED AT ALL. `native` is also what an unclassifiable token fail-softs to (`identity/binding.ts`
+ * `classifyTokenGrain`), so admitting it on the DOMAIN key would hand a lost stamp the whole domain's
+ * grants. It reaches one room instead. It does NOT exclude that room's threads: there is nothing on
+ * an unseated deployment that could tell one from the room, so the room is the smallest unit this
+ * key can honestly name.
+ */
+const GRANT_ROOM_GRAIN: WindowGrain = "native";
+
+/** Why a conversation-stable key was NOT admitted for this seat. The two OPE-1972 gates report the
+ *  key they withheld beside the reason, because the mount writes an audit row naming what it refused
+ *  and a reason with no key names nothing.
+ *
+ *  🔴 `non_standing_grain` KEEPS ITS NAME AND WIDENS ITS MEANING (OPE-2012): it is the seat that is
+ *  not the room's own conversation at all — `thread` and `task` — now that `native` is admitted on the
+ *  room key. The word is the audit vocabulary an operator already greps and every stored row already
+ *  carries, so it is not re-spelled for a distinction the rows cannot make retrospectively. */
+export type GrantDomainScopeGate = "unreadable" | "unresolved_mode" | "dm" | "no_domain" | "unattended" | "non_standing_grain" | "ambiguous_domain_name";
+
+/** What {@link grantDomainScopeVerdict} answers. `scopeKey` rides an ADMITTED verdict, and also the
+ *  two withheld verdicts where a key exists and was refused (`unattended`, `non_standing_grain`) —
+ *  never the five where none was minted (`unreadable`, `unresolved_mode`, `dm`, `no_domain`,
+ *  `ambiguous_domain_name`). */
+export type GrantDomainScopeVerdict =
+  | { readonly admitted: true; readonly scopeKey: string }
+  | { readonly admitted: false; readonly gate: GrantDomainScopeGate; readonly scopeKey?: string };
+
+/**
+ * MAY THIS SEAT REACH A CONVERSATION-STABLE SCOPE KEY, and if not, which gate refused it?
+ *
+ * The key comes from the room's own DECLARED DOMAIN MEMBERSHIP, in one of two shapes decided by the
+ * seat's grain: `oe-grant-domain::<domain name>` for the domain's standing seat, and
+ * `oe-grant-room::<domain name>::<room key>` for a room's own `native` seat (OPE-2012). This function
+ * answers a VERDICT and never `undefined`: an ADMITTED verdict carries the key, and a refused one
+ * carries the gate plus, for the two gates that refuse a key that was minted, the key they withheld —
+ * which is what the mount's `grant.mount_withheld` row names. `grantDomainScopeKey` below is the
+ * flattening every call site reads.
+ *
+ * 🔴 IT IS NOT THE SEAT'S REGISTRY KEY, and that is the correction OPE-1950 needed. An earlier
+ * revision asked `supervisorGrainFor` for the `channel_session` key the room's standing seat rotates
+ * under. That key is byte-identical to the seat's, which reads well — and it exists only where the
+ * `window.topology` capability is ARMED (it ships `false`), and even then is PER-CHANNEL under the
+ * default `solo` window mode. So the owner's ruling — a 30-day tap means 30 days — would have held on
+ * one armed instance and nowhere else. Domain MEMBERSHIP is the thing a room has whatever the
+ * topology gate says, so the binding is read from it and the seat key is not consulted at all.
+ *
+ * 🔴 IT IS THE ROOM'S EXPLICITLY DECLARED DOMAIN, AND THE `org` CATCH-ALL DOES NOT COUNT (Tommy's
+ * ruling on the narrowing, 2026-09-19). `domainForChannel` answers only when an operator named this
+ * room into a domain — through a `reach` entry or a roster — and `undefined` otherwise. The wider
+ * `standingSeatDomainFor` would fall back to the deployment's `org` pseudo-domain, and a room that
+ * reaches that only through the catch-all has no declared domain of its own: binding a standing grant
+ * there would make it spendable in EVERY room of the deployment, which is the widening the ruling
+ * refuses. A room with no declared domain falls back to the asking session for what it may READ —
+ * the exact-session rule, unchanged, which is the fail-closed direction rather than an invented key.
+ * Since OPE-2160 it may MINT no standing grant at all: see `grantScopeKeyForMode`.
+ *
+ * 🔴 A DM OR MPIM ANSWERS `undefined`, AND THAT ARM IS A SECURITY CONTROL RATHER THAN A TIDY-UP. A
+ * domain's `reach` can be workspace-grain (`reach: ["slack/T1"]`), which matches a DM's surface key
+ * as readily as a channel's — so without this a privately-approved standing grant would mount in
+ * every room of the domain, one person's private consent spent by another room's people. A DM keeps
+ * the exact-session rule; binding one to a DM-shaped scope of its own is a separate decision, and
+ * this refuses rather than taking it silently.
+ *
+ * 🔴 AN UNRESOLVED MODE IS REFUSED TOO, because the DM arm above fails OPEN without it.
+ * `bindFrom` GAP-FILLS an unclassified conversation to `"channel"` and says so only through
+ * `modeResolved` (`identity/binding.ts`): a Teams personal chat carrying no `conversationType`, or
+ * any context no platform mapper classified, would otherwise read as a room and mint the domain key.
+ * Requiring the positive flag costs nothing real — every shipped platform mapper returns a mode — and
+ * it closes the one shape where a private conversation could pass for a public one.
+ *
+ * The input is the partition's DOMAIN key, never its surface key: a Discord thread's domain key names
+ * the PARENT channel (`memory/partition.ts` `domainKeyOf`), so a thread binds to the domain its
+ * parent channel is in rather than minting a scope of its own. That collapse is exactly why the
+ * GRAIN gate below exists: without it, a thread of a declared channel reads the channel's key.
+ *
+ * 🔴 NOBODY IN THE ROOM MEANS NO KEY (OPE-1972). A grant is one person's credential spent on another
+ * person's ask, and it audits under both names — so a delivery with no acting principal has nobody to
+ * record as having asked and nobody to read the "acting as <owner>" line. `unattendedFrom` is the
+ * ratified spelling of that question (`identity/binding.ts`, `lint:principal-gate` rule 5 refuses any
+ * other), and it is fail-closed over three independent host-set facts. Before this gate the ONLY
+ * attendance filter on a borrowed tool was `JOB_WAKE_TOOLS`, which covers a durable JOB wake and
+ * nothing else — so a plain one-shot routine fire, which is not a job wake, mounted the domain's
+ * standing grants and could spend the granting person's credential with the room empty.
+ *
+ * 🔴 ATTENDANCE IS THE ONLY GATE A FIRE MEETS ON THE ROOM ARM, AND IT HOLDS WITHOUT A SINGLE STAMP.
+ * On the domain arm a fire is refused twice over — the grain gate below, then attendance — but an
+ * unseated room stamps no grain, so only attendance is left. `hooks/fire-carriage.ts` records the
+ * measured shape that makes this worth stating: on a deployed instance a fire can arrive with its
+ * whole attribute bag gone. `unattendedDelivery`'s third arm reads eve's SCHEDULE AUTH SLOT
+ * (`isScheduleOriginatedAuth` — authenticator, principalId and principalType, never the attributes),
+ * which is the arm written for exactly that case, so a fire that lost every stamp is still unattended.
+ *
+ * 🔴 AND THE GRAIN GATE IS THE OTHER HALF ON THE DOMAIN ARM, because attendance alone does not make a
+ * seat the conversation the card was tapped in. Every triggered fire lands on `thread`
+ * (`routines/fire-window.ts` `TRIGGERED_FIRE_GRAIN`), and so does every real platform thread a seated
+ * deployment stamps — a Notion page comment, a Slack thread reply. Those are attended, and they are
+ * still not the domain's own conversation, so the key is withheld and they keep the exact-session
+ * rule. The measured leak is board #226 leg 51: a standing grant tapped in a Discord room of
+ * `e2e-unified` was spent two hours later by a Notion-comment thread seat of the same domain, on an
+ * ordinary org read. That leak was CROSS-ROOM, which is why the room arm closes it by key rather than
+ * by grain.
+ *
+ * 🔴 AN UNSEATED ROOM TAKES THE OTHER ARM (OPE-2012), and it needs BOTH of its facts. A `native` wake
+ * in a room `windowedSupervisorEnabled` does not seat is that room's own conversation — nothing stands
+ * for it, so the wake keeps eve's own session and classifies `native`, which is exactly the
+ * `native-by-design` posture `access/window-routing.ts` records. It is admitted on the ROOM key, never
+ * the domain one, so it reaches strictly fewer rows than the `standing` arm does: one room of one
+ * domain, where the standing seat reaches every room of it. The board #226 shape was CROSS-ROOM — a
+ * Discord room's grant spent by a Notion-comment seat of the same domain — and those two rooms resolve
+ * two different room keys, so it cannot come back through this arm.
+ *
+ * 🔴 A `native` WAKE IN A SEATED ROOM IS REFUSED, AND THAT ARM IS A SECURITY CONTROL RATHER THAN
+ * TIDINESS. `access/window-routing.ts` records two things that produce one: a routing regression, and
+ * the runtime privacy floor standing the seat down — which is a room that has just been judged to need
+ * its seat stood down, typically because an outsider is present. Minting a 30-day binding there is the
+ * last thing this plane should do, so the seat check runs beside the grain check and such a wake keeps,
+ * for what it READS, the exact-session rule it had before this arm existed — and, since OPE-2160, is
+ * offered no 30-day arm to mint.
+ *
+ * 🔴 THE ROOM KEY DOES NOT EXCLUDE THE ROOM'S THREADS, AND SAYING IT DID WOULD BE THE WORST DEFECT
+ * CLASS HERE. An unseated deployment stamps no `oe_grain` at all, so a thread reply classifies
+ * `native` like every other wake in the room, and `domainKeyOf` collapses a thread onto its parent
+ * room regardless. There is nothing left to tell them apart, so the key names the ROOM — its own
+ * conversation and its threads — and the owner's card (`credential-grant-card.ts`) says exactly that.
+ * The THREAD grain gate below is still the control it was on the domain arm, where a seated
+ * deployment does stamp one.
+ *
+ * 🔴 THE ROOM KEY IS A PAIR, SO IT REFUSES A DOMAIN NAME IT COULD NOT PACK UNAMBIGUOUSLY. The key is
+ * `<domain name>::<room key>`, and a domain name containing `::` would make two different pairs spell
+ * one string — which is the only way this key could ever collide across rooms. Domain names are
+ * operator-chosen and nothing validates them against that shape (`memory/domain.ts`
+ * `assertDomainsValid` refuses one reserved PREFIX and no charset), so the pair is refused here rather
+ * than assumed: `ambiguous_domain_name`, no key, and the seat keeps the exact-session rule for what it
+ * READS while being offered no 30-day arm to mint (OPE-2160). The room
+ * key itself needs no such guard — with a `::`-free first segment the split point is the FIRST `::`
+ * after the prefix, whatever the room key contains.
+ */
+/**
+ * THE GRAIN OF THE CONVERSATION THIS CONTEXT BELONGS TO (OPE-2023), which is the grain this whole rule
+ * asks about — never the grain of the session in hand.
+ *
+ * 🔴 THE TWO DIVERGE ONLY INSIDE A DELEGATED WORKER, and that is the case this exists for. Since
+ * OPE-2023 a lent tool mounts on the WORKERS of the conversation it was lent to, so a worker is what
+ * spends its conversation's grants — while `windowGrainOf` answers `task` for every worker by the
+ * subagent-child override. Asking it here would refuse every worker at `non_standing_grain`, which
+ * would leave both keyed arms reachable by nothing at all; and re-admitting them outside this function
+ * would be a SECOND SPELLING of a rule this file states is spelled once. eve copies the parent's whole
+ * auth bag into the child, so the host's `oe_grain` stamp on a worker describes the SEAT it was
+ * spawned from, and reading it here lets a worker inherit every gate below unchanged — the room arm
+ * and the domain arm alike.
+ *
+ * 🔴 IT WIDENS NOTHING. The stamp is host-set and model-unreachable (channels/unified-window.ts
+ * §AUTH-ATTRIBUTE PROVENANCE), a non-child answers exactly what it answered before, and a child whose
+ * stamp is unreadable falls back to `task`, which both arms refuse. A worker of a THREAD seat still
+ * reads `thread` and is still refused, so the cross-room reach board #226 leg 51 measured stays shut.
+ */
+export function conversationGrainOf(ctx: BindableContext): WindowGrain {
+  if (!isSubagentChildContext(ctx)) return windowGrainOf(ctx);
+  // 🔴 AN ABSENT STAMP FALLS TO THE ROOM GRAIN, NOT TO `task` (cold review). An UNSEATED deployment —
+  // the shipped default — stamps no grain at all: `stampUnifiedWindowAuth` is the writer and
+  // `windowEnabledFor` only diverts a surface `windowedSupervisorEnabled` seats, so an unseated seat's
+  // own grain comes from its TOKEN. A child does not inherit that token, so an absent stamp inside a
+  // child means the PARENT carried none, and only an unseated room produces that. Falling back to
+  // `windowGrainOf` would answer `task` for every such worker, close the ROOM arm, and leave OPE-2012's
+  // 30-day survival dead on the default deployment — neither mintable nor spendable.
+  // It widens nothing. The DOMAIN arm needs a positive `standing` stamp, and the ROOM arm below
+  // independently requires `!windowedSupervisorEnabled(roomKey, domains)` — a seated room always
+  // stamps, so an unstamped child there reads `native`, fails the room arm on seating, and is refused
+  // `non_standing_grain` exactly as it was.
+  return stampedWindowGrainOf(ctx) ?? GRANT_ROOM_GRAIN;
+}
+
+export function grantDomainScopeVerdict(ctx: BindableContext): GrantDomainScopeVerdict {
+  try {
+    const binding = bindFrom(ctx);
+    // PROVENANCE FIRST: a gap-filled mode is not a classification, and the DM arm below is only a
+    // control while the value it reads was actually answered by a mapper.
+    if (binding.modeResolved !== true) return { admitted: false, gate: "unresolved_mode" };
+    if (binding.mode === "dm" || binding.mode === "mpim") return { admitted: false, gate: "dm" };
+    const roomKey = domainKeyOf(resolvePartition(ctx));
+    const domains = getConfig().loadDomains();
+    const domain = domainForChannel(roomKey, domains);
+    if (domain === undefined || domain.name.length === 0) return { admitted: false, gate: "no_domain" };
+    // WHICH SHAPE OF KEY THIS SEAT WOULD REACH (OPE-2012). The ROOM arm needs BOTH facts: a `native`
+    // grain AND a room that has NO standing seat, which is the same question `access/window-routing.ts`
+    // asks to call such a wake `native-by-design`. Every other case is measured against the domain arm,
+    // so a refused thread, task or seat-down wake still reports the DOMAIN key it was withheld — the
+    // reach an operator reading the audit row needs to see.
+    const grain = conversationGrainOf(ctx);
+    const roomArm = grain === GRANT_ROOM_GRAIN && !windowedSupervisorEnabled(roomKey, domains);
+    if (roomArm && domain.name.includes(GRANT_KEY_SEGMENT_SEPARATOR)) return { admitted: false, gate: "ambiguous_domain_name" };
+    const scopeKey = roomArm
+      ? `${GRANT_ROOM_KEY_PREFIX}${domain.name}${GRANT_KEY_SEGMENT_SEPARATOR}${roomKey}`
+      : `${GRANT_DOMAIN_KEY_PREFIX}${domain.name}`;
+    // THE TWO OPE-1972 GATES, and they run LAST so each reports the key it withheld. The gates above
+    // mint no key at all, so there is nothing for them to name.
+    if (unattendedFrom(binding)) return { admitted: false, gate: "unattended", scopeKey };
+    if (!roomArm && grain !== GRANT_CONVERSATION_GRAIN) return { admitted: false, gate: "non_standing_grain", scopeKey };
+    return { admitted: true, scopeKey };
+  } catch {
+    // An unreadable binding, partition, grain or domain config leaves the caller on the session key. Fail closed.
+    return { admitted: false, gate: "unreadable" };
+  }
+}
+
+/** The conversation-stable key this seat may reach — domain-shaped or room-shaped — or `undefined`
+ *  when it may reach none. THE READER EVERY CALL SITE USES — the mint, the mount, the execute backstop
+ *  and the own-account gate — so the rule above moves in one place. Every one of them treats the key
+ *  as OPAQUE and compares it for equality, so the two shapes need no reader of their own; a caller
+ *  that must say WHY takes {@link grantDomainScopeVerdict}, and one that must say HOW WIDE takes
+ *  {@link grantScopeReachOf}. */
+export function grantDomainScopeKey(ctx: BindableContext): string | undefined {
+  const verdict = grantDomainScopeVerdict(ctx);
+  return verdict.admitted ? verdict.scopeKey : undefined;
+}
+
+/**
+ * The scope key a grant of `mode` binds to, given the asking session's key and the room's domain key —
+ * or `undefined` when the mode may not be minted against these keys at all.
+ *
+ * 🔴 IT IS DECIDED FROM THE APPROVED MODE, NOT THE REQUESTED ONE. The owner's card offers the
+ * buttons and their answer wins (`access/credential-grant-card.ts`), so an ask raised as `session`
+ * can be approved `standing` and an ask raised as `standing` can be approved `once`. Deciding this
+ * from the requested mode would mint exactly the row the ruling forbids — a standing grant keyed to a
+ * session that rotates out from under it — or, in the other direction, a once-mode grant reachable
+ * from every seat in the domain. The ask row therefore carries BOTH keys and the mint picks here.
+ *
+ * 🔴 A `standing` MODE WITH NO DOMAIN KEY REFUSES, AND THAT IS THE WHOLE OF OPE-2160. It used to fall
+ * back to `sessionScopeKey`, which minted the exact row the paragraph above forbids: the clock still
+ * stamped `GRANT_STANDING_MAX_MS`, so the owner read "30 days" on the card and on the lent tool, and
+ * the row became unreachable the moment the asking seat rotated — 7 days, a 12-hour quiet gap, a turn
+ * or token backstop, or any deploy that changes the eve build. Nobody was told; the audit trail showed
+ * a live, unexpired, unrevoked grant nobody could spend for another 29 days. The fallback is therefore
+ * a REFUSAL, not a narrowing: a 30-day promise is only ever made where the mechanism can keep it. The
+ * owner's card omits the standing arm on such an ask, so this refusal is the belt behind that
+ * control rather than the control itself.
+ */
+export function grantScopeKeyForMode(mode: CredentialGrantMode, sessionScopeKey: string, domainScopeKey: string | undefined): string | undefined {
+  if (mode !== "standing") return sessionScopeKey;
+  return domainScopeKey !== undefined && domainScopeKey.length > 0 ? domainScopeKey : undefined;
+}
+
+/**
+ * May the seat identified by `sessionScopeKey` (in the room whose domain key is `domainScopeKey`)
+ * reach `grant`? THE EXECUTE BACKSTOP'S copy of the scope rule, and its only caller is
+ * `credential-grant-broker.ts`.
+ *
+ * 🔴 IT IS NOT THE ONLY SPELLING OF THE RULE, so a change here is half a change. The MOUNT
+ * (`tools/grant_tools.ts`) and the OWN-ACCOUNT GATE (`connections/own-account-gate.ts`) read
+ * `credential-grant-reach.ts` `credentialGrantsInReach`, whose half of the rule lives in two SQL
+ * predicates. Anything that narrows or widens what a seat may reach has to move BOTH.
+ * The OPE-1972 attendance and grain gates are NOT a third spelling: they decide the `domainScopeKey`
+ * this predicate and that SQL are both HANDED, upstream of either, so a seat those gates refuse
+ * arrives here with `undefined` and is already on the exact-session rule.
+ * The two differ on STATE, deliberately: the SQL filters a domain-keyed row to active, unexpired and
+ * unrevoked, while this predicate ignores status entirely, because the broker has already run
+ * `credentialGrantStateRefusal` and a second state test here would refuse with the wrong word.
+ *
+ * 🔴 THE CONVERSATION ARM IS GATED ON `mode === "standing"`. Without that conjunct a once- or
+ * session-mode row that somehow carried a domain- or room-shaped key would be reachable from every
+ * seat that resolves the same key, and the exact-session rule those two modes keep would be decided by
+ * the shape of a string instead of by the mode the owner tapped.
+ */
+export function grantScopeAdmits(
+  grant: Pick<CredentialGrantRow, "scopeKey" | "mode">,
+  sessionScopeKey: string,
+  domainScopeKey: string | undefined,
+): boolean {
+  if (sessionScopeKey.length > 0 && grant.scopeKey === sessionScopeKey) return true;
+  return grant.mode === "standing" && domainScopeKey !== undefined && domainScopeKey.length > 0 && grant.scopeKey === domainScopeKey;
+}

package/agent/access/credential-grant.ts

@@ -0,0 +1,284 @@
+// The credential-grant plane: one person's credential serving one CHAT, for one vendor tool with the owner's frozen arguments, until a stated time. The schema and mount are a routing and honesty control and never narrow the credential, which is why v1 mounts granted tools on conversational seats only.
+
+import { classifyConnectorOpTier } from "./consequence.js";
+import { connectorDisplayName, grantDuplicateRefusalText, type GrantCopyAudience, type GrantDuplicateFacts } from "./credential-grant-copy.js";
+import { grantScopeKeyForMode } from "./credential-grant-scope.js";
+import {
+  grantOwnerSlug,
+  grantTargetSlug,
+  grantToolSlug,
+  isGrantNameSegment,
+  nextGrantBorrowToolName,
+  type CredentialGrantAskRow,
+  type CredentialGrantMode,
+  type CredentialGrantRow,
+  type GrantJsonObject,
+} from "../operational/credential-grant-rows.js";
+import { isQualifiedPrincipalKey } from "../identity/principal-key.js";
+
+/** The minimum shape this module reads off a domain, so a caller can pass a bare bag in a test. The grant declaration is its own field rather than a credential override, because the MEMBER plane reads that field too. */
+export interface GrantBoundDomain {
+  readonly name?: string;
+  /** The connectors whose personal credentials this domain's rooms may raise grant asks for; each must appear in CREDENTIAL_GRANT_ROLES. Absent or empty admits NO grant, and there is no org-wide fallback. */
+  readonly credentialGrants?: readonly string[];
+}
+
+/** One provider's GRANT role — the (connector, personal credential id) pair a declaration names. */
+export interface CredentialGrantRole {
+  readonly connector: string;
+  readonly role: string;
+}
+
+/** The (connector, personal credential) pairs this tree admits grants for — the only place core enumerates vendors here. Naming one grants nothing (the domain must declare it too) and a connector missing from it admits no grant at all. */
+export const CREDENTIAL_GRANT_ROLES: readonly CredentialGrantRole[] = [
+  { connector: "notion", role: "user-oauth" },
+];
+
+/** Is this a connector the tree admits grants for? Read at DISPATCH as well as at mint, because a grant row outlives the list: removing a connector leaves every row already minted for it. */
+export function isCredentialGrantConnector(connector: string): boolean {
+  return CREDENTIAL_GRANT_ROLES.some((r) => r.connector === connector);
+}
+
+export function credentialGrantConnectors(): readonly string[] {
+  return [...new Set(CREDENTIAL_GRANT_ROLES.map((r) => r.connector))].sort();
+}
+
+/** An OR across the domains a surface resolves into, matching `memberPlaneGrants`. `false` is a refusal, never an org default, and BOTH halves must say yes: a domain naming a connector with no grant role declares nothing spendable. */
+export function domainsAdmitCredentialGrant(domains: readonly (GrantBoundDomain | undefined)[], connector: string): boolean {
+  if (!isCredentialGrantConnector(connector)) return false;
+  return domains.some((domain) => (domain?.credentialGrants ?? []).includes(connector));
+}
+
+/** Shape problems in one domain's `credentialGrants`, as operator-facing lines. An unadmitted connector is refused at BOOT rather than ignored at runtime, because silence there reads as "grants are off for a reason". */
+export function credentialGrantDeclarationProblems(domain: GrantBoundDomain): readonly string[] {
+  const declared = domain.credentialGrants;
+  if (declared === undefined) return [];
+  const name = domain.name ?? "(unnamed)";
+  const bad: string[] = [];
+  if (!Array.isArray(declared)) return [`  "${name}" \`credentialGrants\` must be a list of connector ids`];
+  const seen = new Set<string>();
+  const admitted = credentialGrantConnectors();
+  for (const connector of declared) {
+    if (typeof connector !== "string" || connector.trim().length === 0) {
+      bad.push(`  "${name}" \`credentialGrants\` holds an entry that is not a non-empty connector id`);
+      continue;
+    }
+    if (seen.has(connector)) bad.push(`  "${name}" \`credentialGrants\` names "${connector}" more than once`);
+    seen.add(connector);
+    if (!admitted.includes(connector)) {
+      bad.push(
+        `  "${name}" \`credentialGrants\` names "${connector}", which this tree admits no credential-grant role for — ` +
+          `add the (connector, personal credential) pair to CREDENTIAL_GRANT_ROLES ` +
+          `(packages/core/agent/access/credential-grant.ts) in the same diff, or delete the entry ` +
+          `(admitted today: ${admitted.length > 0 ? admitted.join(", ") : "none"})`,
+      );
+    }
+  }
+  return bad;
+}
+
+/** Why a grant could not be minted. Every arm is a refusal the requester's turn reports out loud. */
+export type GrantMintRefusal =
+  | "no_domain_grant"
+  | "unverified_requester"
+  | "illegal_owner_handle"
+  | "unresolvable_owner"
+  | "owner_unresolved"
+  | "grant_already_live"
+  | "ask_already_pending"
+  | "write_verb_out_of_slice"
+  | "illegal_tool_name"
+  | "illegal_connector_id";
+
+export interface GrantBorrowMintInput {
+  /** The vendor MCP tool, in the vendor's exact bytes. It decides the tier and, slugified, the verb segment of the mounted name; the bytes are never re-derived from the name. */
+  readonly mcpTool: string;
+  /** The granted target's human label, slugified into the tail of the mounted name. MODEL-AUTHORED but bounded: the slugifier admits only `[a-z0-9_]`, the composer truncates, and the owner reads the composed name; an unslugifiable label falls back to the tool slug. */
+  readonly targetLabel: string;
+  /** The ask row's own id, and the source of the collision suffix. Passed in because this function is pure, and because the row the caller writes must carry the same id the name was spelled from. */
+  readonly rowId: string;
+  /** The mounted names already claimed in this chat, LIVE OR DEAD — the mount projects existence, so a dead row still holds its name. `[]` is the honest answer for the first grant in a chat, and the only way to say it. */
+  readonly takenToolNames: readonly string[];
+}
+
+export interface GrantMintInput {
+  readonly domainGrantsConnector: boolean;
+  /** Exactly one verified human this turn, or undefined. */
+  readonly requesterPrincipalId: string | undefined;
+  readonly ownerPrincipalId: string;
+  /** The owner's display handle, slugified into the mounted name's owner segment. */
+  readonly ownerHandle: string;
+  readonly connector: string;
+  /** What this ask would borrow, and it is REQUIRED: a grant lends one vendor MCP tool. One object, so `takenToolNames` cannot be forgotten — "nothing is claimed" is spelled `[]`. */
+  readonly borrow: GrantBorrowMintInput;
+  /** A live grant already held for the same key — the at-most-one rule. The key is the CALLER's to read: (owner, connector, mcpTool, frozen-args digest, scope), so the same tool frozen to two resources is two grants. */
+  readonly liveGrant: CredentialGrantRow | undefined;
+  /** A pending, unexpired ask already held for the same tuple — the anti-nag control. A second ask while one is pending answers "already asked" and sends nothing, because an owner who is paged turns the feature off. */
+  readonly liveAsk: CredentialGrantAskRow | undefined;
+}
+
+export type GrantMintVerdict =
+  | { readonly ok: true; readonly ownerSlug: string; readonly tier: "read" | "write" | "destructive"; readonly toolName: string }
+  | { readonly ok: false; readonly reason: GrantMintRefusal };
+
+/** May this grant be minted, and under what name? PURE, so the whole decision table is testable without a store; the at-most-one rule is what keeps the mounted name unique inside one chat. */
+export function credentialGrantMintVerdict(input: GrantMintInput): GrantMintVerdict {
+  if (!input.domainGrantsConnector) return { ok: false, reason: "no_domain_grant" };
+  // A coalesced turn keeps only the last delivery's auth, so an ask with no single verified requester has nobody to record as having spent the owner's credential.
+  if (input.requesterPrincipalId === undefined) return { ok: false, reason: "unverified_requester" };
+  // The owner's key is checked at MINT, not at spend: a malformed key names nobody, so the grant would mount and every call would then refuse. The broker keeps its own backstop arm.
+  if (!isQualifiedPrincipalKey(input.ownerPrincipalId)) return { ok: false, reason: "unresolvable_owner" };
+  const shape = borrowShape(input.connector, input.borrow);
+  if (!shape.ok) return shape;
+  const ownerSlug = grantOwnerSlug(input.ownerHandle);
+  if (ownerSlug === undefined) return { ok: false, reason: "illegal_owner_handle" };
+  if (input.liveGrant !== undefined) return { ok: false, reason: "grant_already_live" };
+  // Checked LAST, deliberately: every refusal above is a permanent property of the ask, and the requester should hear it even while an earlier ask is still pending.
+  if (input.liveAsk !== undefined) return { ok: false, reason: "ask_already_pending" };
+  const toolName = shape.name(ownerSlug);
+  // A name past GRANT_TOOL_NAME_MAX refuses here rather than mounting a tool a model provider would reject: this function is pure and callers read it as total, so a composer failure must arrive as a refusal.
+  if (toolName === undefined) return { ok: false, reason: "illegal_tool_name" };
+  return { ok: true, ownerSlug, tier: shape.tier, toolName };
+}
+
+type GrantMintShape =
+  | { readonly ok: true; readonly tier: "read" | "write" | "destructive"; name(ownerSlug: string): string | undefined }
+  | { readonly ok: false; readonly reason: GrantMintRefusal };
+
+/** The tier is the one the owner's own DM would get: classifyConnectorOpTier is handed `<connector>__<mcpTool>`, so a borrowed op classifies byte-identically. It reads the VENDOR's bytes, never the slug. */
+function borrowShape(connector: string, borrow: GrantBorrowMintInput): GrantMintShape {
+  // A connector id that cannot be a name segment is a DEPLOYMENT fault, not a bad ask, so it refuses under its own name. Folding it into `illegal_tool_name` would send the requester into a retry loop.
+  if (!isGrantNameSegment(connector)) return { ok: false, reason: "illegal_connector_id" };
+  const toolSlug = grantToolSlug(borrow.mcpTool);
+  if (toolSlug === undefined) return { ok: false, reason: "illegal_tool_name" };
+  const tier = classifyConnectorOpTier(`${connector}__${borrow.mcpTool}`);
+  // Only a `read` tier mints today: a write borrow records the owner's name at the vendor on an act the requester drove, and it lands in its own slice — refused by name here rather than shipping untested.
+  if (tier !== "read") return { ok: false, reason: "write_verb_out_of_slice" };
+  // An unslugifiable target label is NOT a refusal: the name falls back to the tool slug, which is still legal and still unique once the collision suffix is applied.
+  const targetSlug = grantTargetSlug(borrow.targetLabel);
+  return {
+    name: (ownerSlug) => tryCompose(() => nextGrantBorrowToolName(ownerSlug, connector, toolSlug, targetSlug, borrow.rowId, borrow.takenToolNames)),
+    ok: true,
+    tier,
+  };
+}
+
+/** Run a name composer, turning its throw into `undefined` so a pure verdict stays a verdict. */
+function tryCompose(compose: () => string | undefined): string | undefined {
+  try {
+    return compose();
+  } catch {
+    return undefined;
+  }
+}
+
+/** What the duplicate refusal knows about the grant that already exists — all optional, because a caller that read none must still get an id-free sentence. `audience` is decided from the principal keys by the caller. */
+export interface GrantDuplicateContext extends Omit<GrantDuplicateFacts, "connector"> {
+  readonly audience: GrantCopyAudience;
+}
+
+/** The refusal copy the requester's turn reports. Each line names the boundary, never a bare "no". */
+export function grantMintRefusalMessage(connector: string, reason: GrantMintRefusal, duplicate?: GrantDuplicateContext): string {
+  switch (reason) {
+    case "no_domain_grant":
+      return `This room's domain does not admit credential grants for ${connectorDisplayName(connector)}. An operator declares the grant role on the domain before anyone can ask.`;
+    case "unverified_requester":
+      return "This turn names no single verified requester, so there is nobody to record as having asked. Ask again in a turn that carries one verified author.";
+    case "illegal_owner_handle":
+      return "That owner's handle carries no characters a tool name can hold, so the grant could not be named. Link the account to a readable handle first.";
+    case "unresolvable_owner":
+      return "That owner is not named in a form this deployment can resolve a credential for, so nothing could ever be spent under the grant. Ask again naming the owner by their linked account.";
+    case "owner_unresolved":
+      return "That owner id is not a user id on this conversation's platform, so it names nobody here. Name the owner as they appear in this room, or give their full principal key.";
+    case "grant_already_live":
+      // One composer for both audiences; `duplicate` carries the facts that make the sentence specific. A caller that read none still gets a sentence with no id in it, which this arm must never lose.
+      return grantDuplicateRefusalText(duplicate?.audience ?? "seat", {
+        connector,
+        conversationLabel: duplicate?.conversationLabel,
+        expiresAt: duplicate?.expiresAt,
+        mcpTool: duplicate?.mcpTool,
+        nowMs: duplicate?.nowMs ?? 0,
+        ownerLabel: duplicate?.ownerLabel,
+      });
+    case "ask_already_pending":
+      return "You already asked that person for this, and they have not answered yet. Do not ask again — they were sent one card, and a second ask would page them again for the same decision. Say in the room that the ask is still with them, and carry on with something else.";
+    case "write_verb_out_of_slice":
+      return "That call mutates. Credential grants admit read operations today; a write grant records the owner's name at the vendor on the requester's act, and it needs its own slice.";
+    case "illegal_tool_name":
+      return `That tool name carries no characters a mounted tool name can hold, so the grant could not be named. Name the ${connectorDisplayName(connector)} tool exactly as the connection publishes it.`;
+    case "illegal_connector_id":
+      return `This deployment spells the ${connectorDisplayName(connector)} connector id in a form a mounted tool name cannot hold, so no grant for it can be named. Nothing about the ask was wrong — an operator fixes this, not a retry.`;
+  }
+}
+
+/** A once-mode grant's TTL. Short: the grant is meant to be spent in the turn that asked for it. */
+const GRANT_ONCE_TTL_MS = 60 * 60 * 1000;
+/** A session-mode grant's TTL. It is scoped to the chat anyway, so the clock is only a backstop. */
+const GRANT_SESSION_TTL_MS = 12 * 60 * 60 * 1000;
+/** The ceiling on a standing grant. Standing means standing FOR A NAMED SCOPE: a grant with no ceiling is ambient use wearing a grant's clothes. */
+export const GRANT_STANDING_MAX_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** When a grant of `mode` minted at `nowMs` expires. `requestedMs` only narrows a standing grant. */
+export function credentialGrantExpiry(mode: CredentialGrantMode, nowMs: number, requestedMs?: number): string {
+  const ceiling = mode === "once" ? GRANT_ONCE_TTL_MS : mode === "session" ? GRANT_SESSION_TTL_MS : GRANT_STANDING_MAX_MS;
+  const span = mode === "standing" && typeof requestedMs === "number" && requestedMs > 0 ? Math.min(requestedMs, ceiling) : ceiling;
+  return new Date(nowMs + span).toISOString();
+}
+
+/** A pending ask's own TTL — minutes-to-hours, and deliberately NOT the grant's. */
+export const GRANT_ASK_TTL_MS = 30 * 60 * 1000;
+
+/**
+ * The grant row an approved ask mints. Pure: the caller writes it and owns the ids and the clock.
+ *
+ * 🔴 `undefined` MEANS THE MODE MAY NOT BE MINTED AGAINST THIS ASK, AND IT BINDS NOTHING (OPE-2160).
+ * The one case today is a `standing` mode on an ask that carries no domain key: the row would bind to
+ * the asking session and still stamp a 30-day expiry, which is the promise the mechanism cannot keep.
+ * The refusal lives here rather than in the caller because this function is the only thing that
+ * composes the row — a caller that forgot the rule would write the forbidden row, and now it cannot
+ * spell one. `access/credential-grant-flow.ts` refuses the click before the approve CAS, so a row this
+ * function refuses is a case the card never offered.
+ */
+export function credentialGrantFromAsk(
+  ask: CredentialGrantAskRow,
+  fields: {
+    readonly grantId: string;
+    readonly ownerSlug: string;
+    readonly tier: "read" | "write" | "destructive";
+    readonly mode: CredentialGrantMode;
+    readonly nowIso: string;
+    readonly expiresAt: string;
+    /** The vendor tool's schema with each frozen argument pinned in place, read from the LIVE connection at approve time. A grant that carries none mounts nothing. */
+    readonly inputSchema?: GrantJsonObject;
+  },
+): CredentialGrantRow | undefined {
+  // 🔴 DECIDED FROM THE MODE THE OWNER TAPPED (OPE-1950), never from the requested one: a standing
+  // grant binds to the room's domain-shaped seat key when the ask recorded one, and every other
+  // mode keeps the asking session. The ask carries both keys precisely so this line can choose.
+  // 🔴 AND A `standing` MODE WITH NO KEY REFUSES RATHER THAN FALLING BACK (OPE-2160) — see this
+  // function's own note, and `grantScopeKeyForMode`.
+  const scopeKey = grantScopeKeyForMode(fields.mode, ask.scopeKey, ask.domainScopeKey);
+  if (scopeKey === undefined) return undefined;
+  return {
+    id: fields.grantId,
+    askId: ask.id,
+    requesterPrincipalId: ask.requesterPrincipalId,
+    ownerPrincipalId: ask.ownerPrincipalId,
+    ownerSlug: fields.ownerSlug,
+    connector: ask.connector,
+    verb: ask.verb,
+    resource: ask.resource,
+    // The borrow columns are copied from the ask, never recomputed: the owner answered a card rendered from that row, so re-deriving any of them could mint a grant they never read.
+    ...(ask.mcpTool === undefined ? {} : { mcpTool: ask.mcpTool }),
+    ...(ask.frozenArgs === undefined ? {} : { frozenArgs: ask.frozenArgs }),
+    ...(ask.toolName === undefined ? {} : { toolName: ask.toolName }),
+    ...(fields.inputSchema === undefined ? {} : { inputSchema: fields.inputSchema }),
+    scopeKey,
+    mode: fields.mode,
+    tier: fields.tier,
+    status: "active",
+    purpose: ask.purpose,
+    createdAt: fields.nowIso,
+    expiresAt: fields.expiresAt,
+  };
+}