@open-everywhere/core 0.1.0

package/agent/connections/own-account-gate.ts

@@ -0,0 +1,361 @@
+// THE LIVE HALF of the own-account gate: the four facts the pure decision needs, and the one writer of the
+// `connector.acting_identity` row. 🔴 The caller keys on `refusal`, never on `identity`.
+
+import { auditToolAction } from "../audit/tool-action.js";
+import { getConfig } from "../access/config.js";
+import { domainsAdmitCredentialGrant, isCredentialGrantConnector } from "../access/credential-grant.js";
+import { credentialGrantsInReach, domainScopeKeyInReach, sessionScopeKeyInReach } from "../access/credential-grant-reach.js";
+import { requesterThisTurn } from "../access/requester-identity.js";
+import { requesterMessagesThisTurn } from "../access/requester-messages.js";
+import { askBodyOf } from "../hooks/own-account-ask.js";
+import { currentSessionId, currentTurnId, isSubagentChildContext, type BindableContext } from "../identity/binding.js";
+import { tryPrincipalKey } from "../identity/principal-key.js";
+import type { Domain } from "../memory/domain.js";
+import { resolvePartition } from "../memory/partition.js";
+import { credentialGrantStateRefusal, type CredentialGrantRow } from "../operational/credential-grant-rows.js";
+import { adoptedOwnAccountAsk } from "./own-account-carriage.js";
+import { ownAccountVendorFor } from "./own-account-vendors.js";
+import {
+  actingIdentityAuditDetail,
+  decideActingIdentity,
+  namedOwnAccountVendor,
+  type ActingIdentityVerdict,
+  type OwnAccountAsk,
+  type OwnAccountVendor,
+} from "./own-account-ask.js";
+
+/** Every edge the gate touches, injected so the decision is drivable with no host. */
+export interface ConnectorActingIdentityDeps {
+  /** The vendor the calling tool reaches, and the words a person writes for it. */
+  readonly vendor: OwnAccountVendor;
+  /** The requester's own recognised ask, or the adopted parent stamp inside a worker. */
+  readonly ask: () => OwnAccountAsk | undefined;
+  /** Live personal grants in this seat's reach. Throwing resolves NO grant, which with an ask in hand is a REFUSAL. */
+  readonly grants: () => Promise<readonly CredentialGrantRow[]>;
+  /**
+   * WHOSE own account is being asked for — the single verified human on this turn, as a principal key
+   * (OPE-1950). A grant answers this ask only when THEY own it; see {@link holdsPersonalGrant}.
+   * `undefined` when no single human is verified, which holds nothing.
+   */
+  readonly askerPrincipalId?: string;
+  /** A personal-consent ask can be raised from this surface at all. Changes the sentence, not the verdict. */
+  readonly consentRouteAvailable: () => boolean;
+  /** This tree admits a credential grant for the vendor AT ALL — the deployment half of the route
+   *  above. Changes the sentence, not the verdict; see `ActingIdentityInput.deploymentAdmitsGrant`.
+   *  Throwing resolves `false`, the same fail-soft direction the consent route takes. */
+  readonly deploymentAdmitsGrant: () => boolean;
+  /** ISO now, for the grant's own expiry read. */
+  readonly nowIso: string;
+  /** The tool name the row names, so an auditor can join a refusal to the read it stopped. */
+  readonly tool: string;
+  /** Writes the one row. Best-effort by contract, exactly like `auditToolAction`. */
+  readonly audit: (detail: Record<string, unknown>) => Promise<void>;
+  /** This caller can issue the call under the requester's OWN credential. False for every
+   *  team-credential read tool in this tree — see `ActingIdentityInput.callerCanSpendPersonal`. */
+  readonly callerCanSpendPersonal?: boolean;
+}
+
+/**
+ * The audit action every acting-identity decision writes. ONE row per gated call, whichever way it goes:
+ * a trail that records only refusals cannot answer "which account read this page".
+ */
+export const CONNECTOR_ACTING_IDENTITY_ACTION = "connector.acting_identity";
+
+/**
+ * Does the ASKER hold a SPENDABLE personal grant here? 🔴 Spendable, not merely present: a revoked,
+ * burned or expired row is one the broker refuses, so counting it would answer the ask with a grant
+ * that cannot run.
+ *
+ * 🔴 IT IS KEYED ON THE OWNER AS WELL AS THE CONNECTOR (OPE-1950). The question this answers is
+ * "may this person act as THEMSELVES here", so only a row whose owner IS the asker can answer it —
+ * and since a standing grant now binds to the room's domain, the input set reaches rows other people
+ * own. Without the owner conjunct, requester Y in any room of the domain reads owner O's grant as
+ * their own and is handed `personalRouteRefusal` for a grant Y cannot spend; the day a caller passes
+ * `callerCanSpendPersonal: true` the same mismatch becomes a cross-owner widening instead of a
+ * confusing sentence.
+ *
+ * `undefined` for `ownerPrincipalId` — no single verified human on the turn — holds NOTHING. That is
+ * the fail-closed direction: an unverified caller cannot be the owner of anything.
+ */
+export function holdsPersonalGrant(rows: readonly CredentialGrantRow[], connector: string, ownerPrincipalId: string | undefined, nowIso: string): boolean {
+  if (ownerPrincipalId === undefined) return false;
+  return rows.some(
+    (row) => row.connector === connector && row.ownerPrincipalId === ownerPrincipalId && credentialGrantStateRefusal(row, nowIso) === undefined,
+  );
+}
+
+/**
+ * The gate: decide the acting identity, write the row, hand back the verdict. A caller never reads `reason`
+ * to pick a credential — a caller that branched on it would be a second copy of the decision.
+ */
+export async function decideConnectorActingIdentity(deps: ConnectorActingIdentityDeps): Promise<ActingIdentityVerdict> {
+  const ask = safeAsk(deps.ask);
+  // The store is only asked when an ask was recognised: the ordinary turn must not pay a round trip
+  // to be told what it already knows, and a lookup failure must not be able to refuse a read nobody
+  // asked to personalise.
+  const personalGrantHeld = ask === undefined ? false : holdsPersonalGrant(await safeGrants(deps.grants), ask.connector, deps.askerPrincipalId, deps.nowIso);
+  const verdict = decideActingIdentity({
+    callerCanSpendPersonal: deps.callerCanSpendPersonal ?? false,
+    connector: deps.vendor.connector,
+    ...(ask === undefined ? {} : { ask }),
+    consentRouteAvailable: ask === undefined ? false : safeRouteFact(deps.consentRouteAvailable),
+    deploymentAdmitsGrant: ask === undefined ? false : safeRouteFact(deps.deploymentAdmitsGrant),
+    personalGrantHeld,
+  });
+  await deps.audit(actingIdentityAuditDetail(verdict, deps.vendor.connector, deps.tool)).catch(() => undefined);
+  return verdict;
+}
+
+/** No ask on an unreadable turn — the floor that keeps a read failure from inventing a refusal. */
+function safeAsk(read: () => OwnAccountAsk | undefined): OwnAccountAsk | undefined {
+  try {
+    return read();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * No rows when the store cannot answer. With an ask in hand that resolves to a REFUSAL: silence about a grant
+ * is never evidence that one exists.
+ */
+async function safeGrants(read: () => Promise<readonly CredentialGrantRow[]>): Promise<readonly CredentialGrantRow[]> {
+  try {
+    return await read();
+  } catch {
+    return [];
+  }
+}
+
+/** A route fact the refusal's SENTENCE reads — the consent route, or the deployment half of it.
+ *  A resolver that throws resolves `false`, so the refusal says there is no route to start. That is
+ *  the sentence a member can act on if it is wrong (they ask an operator), unlike an offer of a tool
+ *  that is not mounted. Neither fact can change the verdict, so this direction costs no read. */
+function safeRouteFact(read: () => boolean): boolean {
+  try {
+    return read();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The ask THIS session runs under. The adopted STAMP answers first — it is a worker's only source — and the
+ * requester's words are a SEAT's fallback, each reduced through `askBodyOf` so no colleague's line matches.
+ */
+function ownAccountAskForTurn(ctx: BindableContext, vendors: readonly OwnAccountVendor[]): OwnAccountAsk | undefined {
+  const adopted = adoptedOwnAccountAsk(ctx, vendors);
+  if (adopted !== undefined) return adopted;
+  try {
+    if (isSubagentChildContext(ctx)) return undefined;
+  } catch {
+    return undefined;
+  }
+  return ownAccountAskFromMessages(requesterMessagesThisTurn(), vendors);
+}
+
+/**
+ * The fallback's whole body, pure so a suite can drive it. A named export because the REDUCTION is the
+ * load-bearing part, and an inline copy could be deleted without a test noticing.
+ */
+export function ownAccountAskFromMessages(messages: readonly string[], vendors: readonly OwnAccountVendor[]): OwnAccountAsk | undefined {
+  const bodies = messages.map((message) => askBodyOf(message)).filter((body): body is string => body !== undefined);
+  return namedOwnAccountVendor(bodies, vendors);
+}
+
+/** Domains, fail-soft — an unreadable config resolves none, which makes the consent route read as
+ *  unavailable and changes the refusal's SENTENCE only (never its verdict). */
+function safeDomains(): readonly Domain[] {
+  try {
+    return getConfig().loadDomains();
+  } catch {
+    return [];
+  }
+}
+
+/** The domains this surface resolves into — the same per-surface read `request_credential_grant`'s
+ *  own mount does, because the question is identical: may a grant ask be raised from here? */
+function domainsForCtx(ctx: BindableContext): readonly Domain[] {
+  try {
+    const p = resolvePartition(ctx);
+    const names = new Set(getConfig().domainsForSurface({ surface: p.surface ?? p.surfaceKey, workspaceKey: p.workspaceKey }));
+    return safeDomains().filter((d) => names.has(d.name));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The single verified human on this turn, as a principal key — WHOSE own account an own-account ask
+ * is for. Fail-soft: an unreadable turn or an unverified caller answers `undefined`, which holds no
+ * grant at all (see {@link holdsPersonalGrant}).
+ */
+function askerKey(ctx: BindableContext): string | undefined {
+  try {
+    const p = resolvePartition(ctx);
+    const verdict = requesterThisTurn(currentTurnId(ctx));
+    return verdict.kind === "requester" ? tryPrincipalKey(p.platform, p.workspace, verdict.principalId) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Every edge of the gate, bound to one live turn. Shared by the two ROADS a connector read can take, so both
+ * write the SAME `connector.acting_identity` row from the same decision rather than two near-copies of it.
+ */
+function actingIdentityDepsForTurn(ctx: BindableContext, vendor: OwnAccountVendor, tool: string): ConnectorActingIdentityDeps {
+  // WHOSE account the ask is for. Composed through the SAME composer the grant plane's owner half
+  // uses (`identity/principal-key.ts`), so the key compared against `grant.ownerPrincipalId` is one
+  // grammar rather than two spellings. `undefined` on an unverified turn holds nothing.
+  const asker = askerKey(ctx);
+  return {
+    ask: () => ownAccountAskForTurn(ctx, [vendor]),
+    ...(asker === undefined ? {} : { askerPrincipalId: asker }),
+    audit: async (detail) => {
+      await auditToolAction(ctx, CONNECTOR_ACTING_IDENTITY_ACTION, detail);
+    },
+    consentRouteAvailable: () => domainsAdmitCredentialGrant(domainsForCtx(ctx), vendor.connector),
+    deploymentAdmitsGrant: () => isCredentialGrantConnector(vendor.connector),
+    grants: async () => {
+      // 🔴 THE SAME TWO READERS THE GRANTED-TOOL MOUNT USES (access/credential-grant-reach.ts), which is
+      // what keeps the gate and the mount from ever answering differently about one session. The session
+      // key is the ROOT SEAT's inside a worker — a one-shot worker's own session ends before anybody taps
+      // anything, so no grant was ever scoped to it — and `undefined` for a child that cannot name its
+      // seat, which holds nothing. OPE-1950: a `standing` grant binds to the room's DOMAIN instead, and
+      // OPE-2023 made that key reachable from the worker the seat delegates to.
+      const scope = sessionScopeKeyInReach(ctx);
+      if (scope === undefined) return [];
+      return await credentialGrantsInReach(resolvePartition(ctx).org, scope, domainScopeKeyInReach(ctx), new Date().toISOString());
+    },
+    nowIso: new Date().toISOString(),
+    tool,
+    vendor,
+  };
+}
+
+/**
+ * The one call a connector read makes: decide the acting identity for `vendor`, write the row and hand back
+ * the verdict. The caller REFUSES on `verdict.refusal` and otherwise runs under `verdict.identity`.
+ */
+export async function connectorActingIdentityForTurn(ctx: BindableContext, vendor: OwnAccountVendor, tool: string): Promise<ActingIdentityVerdict> {
+  return await decideConnectorActingIdentity(actingIdentityDepsForTurn(ctx, vendor, tool));
+}
+
+/**
+ * THE SECOND ROAD to a vendor: the sandbox REST route, where the egress firewall stamps the team credential
+ * and no tool call ever reaches {@link connectorActingIdentityForTurn} (OPE-1947). The access plane withholds
+ * that vendor's credentialed hosts when the turn carries an own-account stamp, and it calls this to leave the
+ * SAME `connector.acting_identity` row the tool road writes — so "which account read this page" is answered
+ * from one trail whichever road the turn took.
+ *
+ * 🔴 IT IS A DIFFERENT NAME ON PURPOSE. `lint:own-account-gate` counts `connectorActingIdentityForTurn` call
+ * sites to prove every recognised connector has a gated TOOL site, and that census must stay exact: this road
+ * is generic over whatever connector the stamp named, so it can name none and would satisfy the rule for a
+ * connector whose tool road is still ungated.
+ *
+ * `route` names the road rather than a tool — there is no tool call to join to.
+ *
+ * 🔴 THE VERDICT IS READ, and by one caller: a DELEGATING seat's worker (OPE-1976). The withholding closes the
+ * road by failing that worker — under the one-credential-per-host-per-session invariant (OPE-1549) it may not
+ * narrow the firewall it shares with its seat — so the sentence this verdict carries is the only thing that
+ * can reach the member. `hooks/egress.ts` fails the worker WITH it, and the seat reads it off the settlement
+ * notification. Every other caller still ignores it: the refusal already happened when the host left the reach.
+ *
+ * `writeRow` is false once this session has already written its row — see {@link noteOwnAccountRouteRefusal}.
+ * The DECISION is still computed, because a later pass must be able to speak the sentence it has no row left
+ * to write.
+ */
+async function routeActingIdentityForTurn(
+  ctx: BindableContext,
+  vendor: OwnAccountVendor,
+  route: string,
+  writeRow: boolean,
+): Promise<ActingIdentityVerdict> {
+  const deps = actingIdentityDepsForTurn(ctx, vendor, route);
+  return await decideConnectorActingIdentity(writeRow ? deps : { ...deps, audit: async () => undefined });
+}
+
+/**
+ * The route label the row carries in place of a tool name. There is no tool call on this road, so the row
+ * names the CONNECTIONS whose credential the firewall did not stamp — which is what joins the refusal to the
+ * road it stopped, exactly as a tool name joins one to the read it stopped.
+ *
+ * EVERY connection, deduped and sorted, never the first of them: one vendor's key can sit on two connections
+ * in one reach, and a label naming one of them would describe a road the session still has.
+ */
+export function ownAccountRouteLabel(viaConnections: readonly string[]): string {
+  return `egress:${[...new Set(viaConnections)].sort().join(",")}`;
+}
+
+/**
+ * Sessions whose route refusal has already been written, so ONE decision leaves ONE row rather than one per
+ * enforcement pass.
+ *
+ * 🔴 KEYED ON THE SESSION, NOT ON THE TURN, unlike the egress plane's own memo (`access/request.ts`). Two
+ * reasons, and the first is mechanical: a worker meets this writer at `session.started`, where there is no
+ * turn id at all, and again at every `turn.started` — a turn-keyed memo holds for neither, so one ask left
+ * two rows. The second is that it is the honest grain. Only a delegated worker reaches this road, and a
+ * worker adopts its requester's ask for its WHOLE life, so its road to that vendor is withheld once and
+ * stays withheld; there are no reads on this road to count one row each.
+ *
+ * Fail-direction is the plane's: an unreadable session id SKIPS the memo and writes again, so it may only
+ * ever DUPLICATE a row, never drop one.
+ */
+const routeRefusalWritten = new Set<string>();
+const ROUTE_REFUSAL_MEMO_MAX = 512;
+
+/**
+ * WHAT THE EGRESS PLANE CALLS when a session's own-account ask cost it the vendor's credentialed hosts.
+ *
+ * The access plane already writes its own `egress.own_account_refusal` row, which answers "what did this
+ * plane withhold". It does not answer "which account read this page" — that trail is
+ * `connector.acting_identity`, and the REST skill road reaches no connector tool, so a refusal there used to
+ * leave that trail EMPTY (OPE-1947). This writes the gate's own row for it, from the same decision.
+ *
+ * 🔴 WHICH SESSIONS REACH IT. A DELEGATED WORKER adopts its seat's stamp before its own egress pass compiles,
+ * so its pass carries refusals and this writes. A SEAT does not: its firewall compiles at `turn.started`,
+ * before `message.received` writes the stamp, and on any LATER turn `turnHalfAdmits` refuses the adoption.
+ * A seat's own reads are gated by {@link connectorActingIdentityForTurn} at the connector tools instead.
+ *
+ * An empty list is a no-op, so the caller needs no branch. It is `await`-able for a suite and floated by the
+ * live caller: the hosts are already withheld by the time this runs, so a store outage can only cost a row.
+ *
+ * It RETURNS the verdict, whose `refusal` is the sentence a delegating seat's worker is failed with
+ * (OPE-1976). `undefined` means there was nothing withheld to decide about. 🔴 The memo gates the ROW, never
+ * the decision: a worker meets this writer at `session.started` and again at every `turn.started`, and the
+ * pass that must SPEAK the refusal is not always the pass that wrote the row.
+ */
+export async function noteOwnAccountRouteRefusal(
+  ctx: BindableContext,
+  refusals: readonly { readonly connector: string; readonly viaConnection: string }[],
+): Promise<ActingIdentityVerdict | undefined> {
+  const first = refusals[0];
+  if (first === undefined) return undefined;
+  // One row, not one per host: the DECISION is per connector and identical for every host it cost, and the
+  // trail reads "which account", not "how many hosts". The route label carries the connections instead.
+  return await routeActingIdentityForTurn(
+    ctx,
+    ownAccountVendorFor(first.connector),
+    ownAccountRouteLabel(refusals.map((r) => r.viaConnection)),
+    !memoHolds(ctx, first.connector),
+  );
+}
+
+/** Has this session already written its row? `false` wherever the address cannot be read, which writes again
+ *  — the direction that can only ever duplicate. The session is this one's OWN id, never the delegation
+ *  root's: two workers of one seat are two roads, and keying on the root would silence the second. */
+function memoHolds(ctx: BindableContext, connector: string): boolean {
+  let session: string | undefined;
+  try {
+    session = currentSessionId(ctx);
+  } catch {
+    return false;
+  }
+  if (session === undefined) return false;
+  const key = [session, connector].join("\u0000");
+  if (routeRefusalWritten.has(key)) return true;
+  if (routeRefusalWritten.size >= ROUTE_REFUSAL_MEMO_MAX) routeRefusalWritten.clear();
+  routeRefusalWritten.add(key);
+  return false;
+}

package/agent/connections/own-account-vendors.ts

@@ -0,0 +1,117 @@
+// THE OWN-ACCOUNT VENDOR REGISTRY — the ONE list of vendors the grammar recognises and their spoken aliases,
+// read by both the stamp producer and every gated call site. Derived from two reviewed sources, and I/O-free.
+
+import { getConfig } from "../access/config.js";
+import { humanActingSupport, isHumanActing, type ConnectorCredentials } from "../access/connector-credentials.js";
+import { credentialGrantConnectors } from "../access/credential-grant.js";
+import type { OwnAccountVendor } from "./own-account-ask.js";
+
+/**
+ * The words a person writes for a vendor, beyond the connector id itself. 🔴 Every entry is a LONG word: an
+ * alias is matched with no word boundary, so a short one binds ordinary English and refuses honest reads.
+ */
+export const OWN_ACCOUNT_VENDOR_ALIASES: Readonly<Record<string, readonly string[]>> = {
+  github: ["github.com"],
+  notion: ["notion.so"],
+};
+
+/**
+ * The shortest alias this registry admits — the floor at which an alias stops fitting inside common English
+ * words. Module-local: {@link ownAccountVendorAliasProblems} is the shape every caller reads it through.
+ */
+const OWN_ACCOUNT_VENDOR_MIN_ALIAS_CHARS = 4;
+
+/**
+ * Shape problems in {@link OWN_ACCOUNT_VENDOR_ALIASES}, as reviewer-facing lines; empty means sound.
+ * Exported so the suite drives the rule rather than restating it.
+ */
+export function ownAccountVendorAliasProblems(table: Readonly<Record<string, readonly string[]>> = OWN_ACCOUNT_VENDOR_ALIASES): string[] {
+  const problems: string[] = [];
+  for (const [connector, aliases] of Object.entries(table)) {
+    const seen = new Set<string>([connector]);
+    for (const alias of aliases) {
+      if (alias !== alias.toLowerCase()) problems.push(`${connector}: alias "${alias}" is not lower-case — the grammar lower-cases the sentence, never the alias`);
+      if (alias.length < OWN_ACCOUNT_VENDOR_MIN_ALIAS_CHARS) {
+        problems.push(
+          `${connector}: alias "${alias}" is shorter than ${OWN_ACCOUNT_VENDOR_MIN_ALIAS_CHARS} characters — a vendor word is ` +
+            `matched with no word boundary, so a short alias binds ordinary words to ${connector} and refuses reads nobody ` +
+            `asked to personalise`,
+        );
+      }
+      if (seen.has(alias)) problems.push(`${connector}: alias "${alias}" is a duplicate — the connector id is already a vendor word`);
+      seen.add(alias);
+    }
+  }
+  return problems;
+}
+
+/** One vendor as the grammar recognises it: its connector id plus whatever aliases this registry
+ *  declares for it. A connector with no entry is its own only word, which is the ordinary case. */
+export function ownAccountVendorFor(connector: string): OwnAccountVendor {
+  const aliases = OWN_ACCOUNT_VENDOR_ALIASES[connector];
+  return aliases === undefined || aliases.length === 0 ? { connector } : { aliases, connector };
+}
+
+/**
+ * The connectors whose catalogue declares `humanActing.supported` AND holds a `human-acting` credential.
+ * 🔴 An unreadable config THROWS, or reuses the last good list — never `[]`, which silently drops a vendor.
+ */
+export function humanActingConnectors(catalogues?: readonly ConnectorCredentials[]): readonly string[] {
+  if (catalogues !== undefined) return declaredHumanActing(catalogues);
+  let list: readonly ConnectorCredentials[];
+  try {
+    list = getConfig().loadConnectorCredentials?.() ?? [];
+  } catch (err) {
+    if (lastGoodHumanActing !== undefined) return lastGoodHumanActing;
+    throw new OwnAccountVendorsUnavailableError(err);
+  }
+  lastGoodHumanActing = declaredHumanActing(list);
+  return lastGoodHumanActing;
+}
+
+/** The last successfully derived list. See {@link humanActingConnectors} for why an empty list is
+ *  never an acceptable answer to a failed read. */
+let lastGoodHumanActing: readonly string[] | undefined;
+
+/** Test-only reset, so a suite can drive the throwing arm after a successful read. */
+export function _resetHumanActingCacheForTest(): void {
+  lastGoodHumanActing = undefined;
+}
+
+/** The pure half — both declaration halves, over catalogues the caller supplies. */
+function declaredHumanActing(catalogues: readonly ConnectorCredentials[]): readonly string[] {
+  return catalogues.filter((c) => humanActingSupport(c) === "supported" && c.credentials.some((cred) => isHumanActing(cred))).map((c) => c.connector);
+}
+
+/**
+ * The config could not be read and no earlier read succeeded, so which vendors the grammar recognises is
+ * UNKNOWN. A named type, so the producer can say "unknown" rather than treat it as "no ask".
+ */
+export class OwnAccountVendorsUnavailableError extends Error {
+  constructor(cause: unknown) {
+    super(
+      `own-account vendors are unavailable: the connector-credential catalogue could not be read, so which vendors declare a ` +
+        `human-acting credential family is unknown. Resolving this as "none" would silently drop a vendor from the own-account ` +
+        `stamp and answer a delegated worker's read with the deployment's own credential (OPE-1641). Cause: ` +
+        `${cause instanceof Error ? cause.message : String(cause)}`,
+    );
+    this.name = "OwnAccountVendorsUnavailableError";
+  }
+}
+
+/**
+ * Every vendor the grammar recognises, with its aliases — the list the STAMP PRODUCER reads. A vendor with
+ * no gated call site is inert; the reverse is the defect. It propagates the error rather than shortening.
+ */
+export function ownAccountAskVendors(): readonly OwnAccountVendor[] {
+  const connectors = new Set<string>([...credentialGrantConnectors(), ...humanActingConnectors()]);
+  return [...connectors].sort().map((connector) => ownAccountVendorFor(connector));
+}
+
+/**
+ * The half of the list that CANNOT fail — the credential-grant connectors, a reviewed module-level literal.
+ * 🔴 The DEGRADED answer, and only the producer may use it: it is strictly narrower than the real list.
+ */
+export function credentialGrantVendors(): readonly OwnAccountVendor[] {
+  return [...credentialGrantConnectors()].sort().map((connector) => ownAccountVendorFor(connector));
+}

package/agent/connections/user-auth-flow.ts

@@ -0,0 +1,102 @@
+// The USER-AUTH-FLOW port — the connector plane's vendor-neutral seam for OAuth minting and interactive
+// authorization. Core ships ZERO OAuth-vendor SDK imports, and an unregistered flow throws at mint time.
+
+import type { TokenResult } from "eve/connections";
+
+/** An OAuth subject a token / authorization URL is minted for — the end user's OWN account, or the
+ *  shared org service (app) account. `id` is present only for the user subject (the surface principal). */
+export type UserAuthSubject =
+  | { readonly type: "user"; readonly id: string; readonly issuer?: string }
+  | { readonly type: "app" };
+
+/**
+ * OPAQUE CONSENT CARRIAGE: the adapter PERSISTS it verbatim and echoes it back, never reading a field.
+ * connections/consent-resume.ts owns the real type. 🔴 Nothing secret rides it — conversation addresses only.
+ */
+export type ConsentCarriage = unknown;
+
+/** Per-user token mint parameters — the user subject + optional per-call scoping. */
+export interface UserTokenMintParams {
+  readonly subject: { readonly type: "user"; readonly id: string; readonly issuer?: string };
+  readonly scopes?: readonly string[];
+  readonly resources?: readonly string[];
+}
+
+/**
+ * The vendor-neutral user-auth-flow port. One provider satisfies every method structurally; the
+ * adapter that implements it is the ONLY place an OAuth-vendor SDK is named for the connector plane.
+ */
+export interface UserAuthFlowProvider {
+  /** Mint a NON-interactive SERVICE token (the shared app identity) for `providerRef`. `getTokenOptions`
+   *  is the opaque per-call options object eve hands a `ConnectionAuthProvider.getToken` — forwarded
+   *  verbatim so the provider can honour any per-call down-scoping eve passes. */
+  mintServiceToken(providerRef: string, getTokenOptions: unknown): Promise<TokenResult>;
+  /** Mint a PER-USER token bound to the given user subject — it acts as the HUMAN, not the service. */
+  mintUserToken(providerRef: string, params: UserTokenMintParams): Promise<TokenResult>;
+  /** Start an interactive authorization flow for a subject; returns a CAPABILITY-BEARING URL the human
+   *  opens to connect the named account. Whoever opens it binds that account — the caller NEVER logs it. */
+  startAuthorization(
+    providerRef: string,
+    params: { readonly subject: UserAuthSubject },
+    options: { readonly expiresInMs?: number; readonly consent?: ConsentCarriage },
+  ): Promise<{ url: string }>;
+  /** Classify an error thrown by {@link mintUserToken} as "the user must authorize their OWN account
+   *  first". The provider owns its own error shape, so this classification belongs with it (a future
+   *  own-rolled adapter throws a different error class — it still answers this the same way). */
+  isUserAuthRequired(error: unknown): boolean;
+  /** A diagnostic identity stamp for the mint audit — the host deployment's environment claim, never
+   *  token material (the workflow-vs-route namespace discriminator; see connector-auth.ts auditMintOutcome). */
+  environmentClaim(): Promise<string>;
+  /** OPTIONAL cheap probe: does a user grant for this subject+providerRef exist RIGHT NOW? Used by the
+   *  per-turn auth memo to self-heal when consent completes mid-turn (eve auto-resumes the pre-consent
+   *  turn, so turn.started never refires and the stale flag would refuse a fresh grant — OPE-93).
+   *  MUST be cheap (local vault/DB read; never a network mint). Absent ⇒ memo behaves as before. */
+  hasFreshGrant?(providerRef: string, subject: UserAuthSubject): Promise<boolean>;
+}
+
+let registeredFlow: UserAuthFlowProvider | undefined;
+
+/** Called once at boot by the adapter wiring when the connector-OAuth adapter is present. Last wins. */
+export function registerUserAuthFlow(flow: UserAuthFlowProvider): void {
+  registeredFlow = flow;
+}
+
+/** Test seam / rollback: forget the registered flow — the builders then fail closed rather than half-authing. */
+export function resetUserAuthFlow(): void {
+  registeredFlow = undefined;
+}
+
+/** The registered user-auth-flow provider, or undefined when no connector-OAuth adapter is wired. Used
+ *  by the classification/audit paths that must degrade softly when none is registered (the injected-deps
+ *  test path); the MINT paths use {@link requireUserAuthFlow} (fail closed). */
+export function userAuthFlowProvider(): UserAuthFlowProvider | undefined {
+  return registeredFlow;
+}
+
+/**
+ * The registered flow, or a clear throw when none is wired — the fail-closed accessor every real MINT routes
+ * through. `connector` labels the error with the offending connection.
+ */
+export function requireUserAuthFlow(connector: string): UserAuthFlowProvider {
+  if (!registeredFlow) {
+    throw new Error(
+      `connection "${connector}": no user-auth-flow provider is registered — the connector-OAuth adapter ` +
+        `(own-rolled OAuth) is not wired. Register it at boot (register-adapters.ts), or ` +
+        `use a fixed-key credential.`,
+    );
+  }
+  return registeredFlow;
+}
+
+/**
+ * GENERIC fallback classifier for the no-adapter path: it matches the transport-neutral OAuth reason only,
+ * never a vendor error class. A registered flow is always authoritative.
+ */
+export function userAuthRequiredSignal(e: unknown): boolean {
+  if (!(e instanceof Error)) return false;
+  const code = (e as { code?: unknown }).code;
+  return (
+    (typeof code === "string" && /user_authorization_required/i.test(code)) ||
+    /user[_ ]?authorization[_ ]?required/i.test(e.message)
+  );
+}