@open-everywhere/core 0.1.0

package/agent/connections/connector-auth.ts

@@ -0,0 +1,984 @@
+// Reusable `auth` builders for the host-side MCP connections — the credential is injected in the framework
+// process, never the sandbox (pinned by scripts/credential-isolation-test.ts). Every getToken gates first.
+
+import {
+  defineInteractiveAuthorization,
+  type ConnectionAuthProvider,
+  type ConnectionAuthResolver,
+  type InteractiveAuthorizationDefinition,
+  type JsonValue,
+  type TokenResult,
+} from "eve/connections";
+import type { SessionContext } from "eve/context";
+import { once, type ApprovalStatus } from "eve/tools/approval";
+import { connectorToolPermissionKind } from "../approvals/session-grant.js";
+// THE ROUTINE PERMISSION CARD'S SEAM (OPE-1357). A LEAF import — routine-permission-offer.ts imports
+// nothing, so this file still does not reach approvals/flow.ts's channel and card graph. The slot is
+// filled by flow.ts at its own module load; an empty slot answers the empty clause.
+import { offerRoutinePermissionCardFor } from "../approvals/routine-permission-offer.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { routinePermissionKeyStamped } from "../routines/routine.js";
+// Both annotations below are the NARROW arm (`ApprovalPolicy`), never the union: a CONNECTION may not
+// author the configuration arm — eve's own resolver drops it (see `connectorApprovalPolicy`).
+import type { ApprovalPolicy } from "eve/tools/approval";
+import {
+  assertConnectorGranted,
+  boundConnectorCredential,
+  surfaceContextFromAuth,
+} from "../access/connector-scope.js";
+import { vercelConnectorOf } from "../access/connector-credentials.js";
+import { assertCredentialEndpointHostAllowed } from "../access/credential-endpoints.js";
+import { classifyConnectorOpTier, isConnectorOpTool, parseQualifiedToolName } from "../access/consequence.js";
+import { effectiveConnectorOpTier, joinConnectorOpTiers } from "../access/connector-op-gating.js";
+import { sharedVaultSubjectFor } from "../access/group-request.js";
+import { rawVaultSubject, SHARED_VAULT_SUBJECT_PREFIX } from "../identity/oauth-vault-share.js";
+import { connectorOpTieringEnabled, connectorLinkSetVaultEnabled, connectorMemberPlaneEnabled } from "./connector-flags.js";
+// THE MEMBER PLANE (OPE-944). member-plane.ts is a LEAF — it imports nothing, which is why the two
+// attribute NAMES and the unverified sentinel are passed to its readers rather than imported by it.
+import {
+  memberPlaneRefusalMessage,
+  memberPlaneVerdict,
+  nonMemberWakeFromAuth,
+  personalConnectorWriteVerdict,
+  personalWriteRefusalMessage,
+  requesterFromAuth,
+  roomVouchedInternalFrom,
+  type MemberPlaneAuthLike,
+} from "../access/member-plane.js";
+import { OE_REQUESTER_ATTR, REQUESTER_UNVERIFIED } from "../access/requester-identity.js";
+import { OE_CHAT_NONMEMBER_ATTR, untrustedIngestedThisTurn } from "../access/taint-signal.js";
+import { getSecretVia } from "../access/credentials.js";
+import { withDuplicateApprovalGuard } from "../access/approval-dedupe.js";
+import { resolvePartition } from "../memory/partition.js";
+import { actingPrincipalId, bindFrom, deploymentOrg, unattendedFrom } from "../identity/binding.js";
+import { appendAudit } from "../audit/audit.js";
+import {
+  requireUserAuthFlow,
+  userAuthFlowProvider,
+  userAuthRequiredSignal,
+  type ConsentCarriage,
+} from "./user-auth-flow.js";
+import { randomUUID } from "node:crypto";
+import { recordConsentDetour, type ConsentOrigin } from "./consent-resume.js";
+import { resolveReplyTarget } from "../channels/reply-post.js";
+import { currentSessionId } from "../identity/binding.js";
+import { delegatedNonMemberWakeThisTurn, delegatedRequesterThisTurn } from "../identity/delegated-binding.js";
+import {
+  connectorAuthRequiredThisTurn,
+  connectorAuthUrlThisTurn,
+  markConnectorAuthRequired,
+  connectorAuthRequiredError,
+  clearConnectorAuthRequired,
+  freshGrantConfirmed,
+} from "./auth-retry-memo.js";
+
+// Core carries ZERO @vercel/connect / @vercel/oidc references: the builders below route their OAuth work
+// through the vendor-neutral {@link requireUserAuthFlow} port, which fails closed with no adapter wired.
+
+function requesterForAuthority(auth: MemberPlaneAuthLike | undefined) {
+  const delegated = delegatedRequesterThisTurn(undefined);
+  if (delegated?.kind === "requester") return { kind: "requester" as const, principalId: delegated.principalId };
+  if (delegated?.kind === "unverified") return { kind: "unverified" as const };
+  if (delegated?.kind === "none") return { kind: "none" as const };
+  return requesterFromAuth(auth, OE_REQUESTER_ATTR, REQUESTER_UNVERIFIED);
+}
+
+function nonMemberWakeForAuthority(auth: MemberPlaneAuthLike | undefined): boolean {
+  return delegatedNonMemberWakeThisTurn(undefined) ?? nonMemberWakeFromAuth(auth, OE_CHAT_NONMEMBER_ATTR);
+}
+
+/**
+ * A fixed API key, shared service identity. The secret resolves by ref through its explicit home `broker`
+ * at call time — never a raw process.env read, and it never enters the sandbox.
+ */
+export function appStaticToken(opts: {
+  /** The connection's runtime name (its agent/connections/*.ts slug) — the grant key. */
+  readonly connector: string;
+  /** Reference to the secret (env key / db ref / Connect ref), never the value. */
+  readonly secretRef: string;
+  /** The secret's HOME broker ("env" | "db" | ...) — REQUIRED (no selected default). */
+  readonly broker: string;
+}): ConnectionAuthResolver {
+  return async (ctx: SessionContext): Promise<ConnectionAuthProvider> => ({
+    principalType: "app",
+    async getToken() {
+      await assertConnectorGranted(opts.connector, ctx.session.auth); // gate first — fail closed
+      return { token: await getSecretVia(opts.broker, opts.secretRef) };
+    },
+  });
+}
+
+/**
+ * Out-of-band service OAuth — the vault owns refresh, so getToken stays non-interactive. The mint runs
+ * through the registered UserAuthFlowProvider, which throws when no connector-OAuth adapter is wired.
+ */
+export function appConnectToken(opts: {
+  readonly connector: string;
+  /** The provider connector ref (a provider connector id, e.g. "oauth/mcp-notion-app"). */
+  readonly vercelConnector: string;
+}): ConnectionAuthResolver {
+  return async (ctx: SessionContext): Promise<ConnectionAuthProvider> => ({
+    principalType: "app",
+    async getToken(o) {
+      await assertConnectorGranted(opts.connector, ctx.session.auth); // gate first — fail closed
+      return requireUserAuthFlow(opts.connector).mintServiceToken(opts.vercelConnector, o);
+    },
+  });
+}
+
+/**
+ * Resolves WHICH credential the calling surface is bound to and authorizes with that, so one connection
+ * serves different surfaces different keys. `fallbackSecretRef` covers a raw grant with no bound credential.
+ */
+export function appProviderToken(opts: {
+  readonly connector: string;
+  /** Static secret used when the surface has no provider credential bound (raw grant). */
+  readonly fallbackSecretRef?: string;
+  /** The fallback secret's HOME broker ("env" | "db" | ...) — REQUIRED alongside fallbackSecretRef
+   *  (no selected default; an unstamped fallback fails closed at resolution). */
+  readonly fallbackBroker?: string;
+  /** The connection's MCP transport URL (OPE-523) — when present, the bound credential's
+   *  `endpoints.hosts` (if it declares any) is checked against this URL before the token is
+   *  returned. Absent ⇒ no transport check runs (a caller with no URL to check, e.g. a test). */
+  readonly directUrl?: string;
+}): ConnectionAuthResolver {
+  return async (ctx: SessionContext): Promise<ConnectionAuthProvider> => ({
+    principalType: "app",
+    async getToken(o) {
+      // #101 part c: if this connector already returned needsAuthorization THIS turn, fail fast —
+      // no gate, no broker lookup, no mint. Deterministic within a turn; reset on the next.
+      if (connectorAuthRequiredThisTurn(opts.connector)) throw connectorAuthRequiredError(opts.connector);
+      await assertConnectorGranted(opts.connector, ctx.session.auth); // gate first — fail closed
+      const cred = await boundConnectorCredential(opts.connector, ctx.session.auth);
+      return resolveAppTokenFromCred(opts, cred, o);
+    },
+  });
+}
+
+/**
+ * RESOLUTION-TIME fallback is ALLOWED — the `!cred` branch, where no credential is bound for this surface.
+ * AUTH-FAILURE fallback is FORBIDDEN: a failure under a resolved credential propagates, never retries.
+ */
+export async function resolveAppTokenFromCred(
+  opts: { readonly connector: string; readonly fallbackSecretRef?: string; readonly fallbackBroker?: string; readonly directUrl?: string },
+  cred: import("../access/connector-credentials.js").ResolvedConnectorCredential | null,
+  o: unknown,
+): Promise<TokenResult> {
+  if (!cred) {
+    if (opts.fallbackSecretRef) return { token: await getSecretVia(opts.fallbackBroker, opts.fallbackSecretRef) };
+    throw new Error(
+      `connection "${opts.connector}": no credential bound for this surface and no fallback secret — ` +
+        `grant it with connectors: [{ name: "${opts.connector}", credential: "<id>", contentOrigin: … }], ` +
+        `or give the connection its own fallback secretRef.`,
+    );
+  }
+  // The transport check runs BEFORE the broker or mint lookup. An absent `directUrl` or `endpoints` ⇒ no check.
+  if (opts.directUrl !== undefined) {
+    assertCredentialEndpointHostAllowed(cred.endpoints, opts.directUrl, `connection "${opts.connector}" credential "${cred.credential}"`);
+  }
+  if (cred.type === "api-key") {
+    if (!cred.secretRef) throw new Error(`connection "${opts.connector}": api-key credential has no secretRef`);
+    // Honour the credential's HOME broker — an api-key credential always carries its mandatory stamp
+    // (assertConnectorCredentialsValid); there is no selected default, so an absent broker here fails closed.
+    return { token: await getSecretVia(cred.broker, cred.secretRef) };
+  }
+  if (cred.type === "service-oauth") {
+    const connector = vercelConnectorOf(cred);
+    if (!connector)
+      throw new Error(`connection "${opts.connector}": service-oauth credential has no vercel-connect home`);
+    return requireUserAuthFlow(opts.connector).mintServiceToken(connector, o);
+  }
+  throw new Error(
+    `connection "${opts.connector}": credential type "${cred.type}" is not valid on an app connection ` +
+      `(user-principal credentials resolve in the DM universe — arm connectors.userPrincipal and wire ` +
+      `userAwareProviderToken to mint a per-user token).`,
+  );
+}
+
+// The per-user branch: a `user-oauth` credential AND a resolved `mode:dm` mint with subject `{type:"user"}`,
+// so the token acts as the HUMAN. Every other path runs the shared app body byte-for-byte.
+
+/** Params for the per-user token mint (a `{type:"user"}` subject + optional per-call scoping). */
+export interface ConnectUserTokenParams {
+  readonly subject: { readonly type: "user"; readonly id: string; readonly issuer?: string };
+  readonly scopes?: readonly string[];
+  readonly resources?: readonly string[];
+}
+
+/** Mints a per-user token. Injectable (DI seam) so tests exercise the subject-branch without a live
+ *  auth-flow adapter; the default delegates to the registered {@link UserAuthFlowProvider}. */
+export type ConnectUserTokenMinter = (vercelConnector: string, params: ConnectUserTokenParams) => Promise<TokenResult>;
+
+/**
+ * Mints an end-user AUTHORIZATION URL — the page a human opens to connect their OWN account, no vendor
+ * dashboard needed. Injectable (DI seam) so the auth-required branch tests offline.
+ */
+export type ConnectAuthorizationStarter = (
+  vercelConnector: string,
+  params: { readonly subject: { readonly type: "user"; readonly id: string } },
+  /** `consent` (OPE-1619) is the opaque record of the request this detour interrupted — the adapter
+   *  persists it beside the pending-authorization row and hands it back at the callback, so the
+   *  return hop can resume that request. Absent ⇒ nothing to resume, and the flow is unchanged. */
+  options: { readonly expiresInMs?: number; readonly consent?: ConsentCarriage },
+) => Promise<{ url: string }>;
+
+/**
+ * The authorization URL is CAPABILITY-BEARING: long enough to complete the third-party OAuth, short enough
+ * not to linger. Exported so connector-card.ts mints with the SAME window — one TTL for every link OE issues.
+ */
+export const AUTH_URL_TTL_MS = 15 * 60 * 1000;
+
+/**
+ * Audit one real mint attempt (`connector.mint`) — outcome class and this process's environment claim,
+ * never token material. The sibling `connector.use` row only proves the gate passed.
+ */
+async function auditMintOutcome(connector: string, detail: Readonly<Record<string, unknown>>): Promise<void> {
+  const flow = userAuthFlowProvider();
+  const oidcEnv = flow ? await flow.environmentClaim() : "unregistered";
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "connector",
+    workspace: "connector",
+    action: "connector.mint",
+    detail: { connector, oidcEnv, ...detail },
+  });
+}
+
+// The widened starter for the agent-facing `connector` card: same registered provider, either subject — a
+// personal click mints `{type:"user"}`, a service click `{type:"app"}`. Injectable, like the user-only one.
+
+/** An OAuth subject the connector card can request a URL for — the clicker's own user account, or the
+ *  shared org service (app) account. `id` is present only for the user subject (the surface principal). */
+export type ConnectorAuthSubject =
+  | { readonly type: "user"; readonly id: string }
+  | { readonly type: "app" };
+
+/** Mints an authorization URL for EITHER subject shape (see the block above). CAPABILITY-BEARING:
+ *  whoever opens the returned URL binds the named subject's third-party account. NEVER log it. */
+export type ConnectorAuthorizationStarter = (
+  vercelConnector: string,
+  params: { readonly subject: ConnectorAuthSubject },
+  options: { readonly expiresInMs?: number },
+) => Promise<{ url: string }>;
+
+/** The default subject-flexible starter — delegates to the registered {@link UserAuthFlowProvider}
+ *  (fail closed when no connector-OAuth adapter is wired). `vercelConnector` doubles as the error label. */
+export const defaultConnectorAuthStarter: ConnectorAuthorizationStarter = (vercelConnector, params, options) =>
+  requireUserAuthFlow(vercelConnector).startAuthorization(vercelConnector, params, options);
+
+// One authoritative copy of the auth-required message, so a second connector-plane OAuth transport can relay
+// byte-identical text — only the middle "how to authorize" clause would differ by transport.
+
+function personalAuthUrlClause(url: string): string {
+  return `Open this personal link to connect it (expires soon): ${url} — complete the sign-in, then ask again. `;
+}
+
+/** The full auth-required message the model relays to the user. `authorizeClause` is the transport-
+ *  specific middle (a {@link personalAuthUrlClause} link, or a no-URL fallback). Everything else — the
+ *  "acts as YOU" framing and the RETRY-on-"I've connected" instruction (#112) — is shared verbatim. */
+function connectorAuthRequiredUserMessage(connector: string, authorizeClause: string): string {
+  return (
+    `connection "${connector}": your personal account isn't connected yet. ` +
+    authorizeClause +
+    `This connector acts as YOU with YOUR own access — not the shared service account. ` +
+    `If they later say they've completed the sign-in, RETRY the operation to re-check — ` +
+    `never claim it is still unconnected without a fresh attempt.`
+  );
+}
+
+/**
+ * Resolve the DM caller's `{mode, principalId}` from `ctx.session.auth`. Fail-soft: an unresolvable surface
+ * yields `{}`, so the caller fails closed. 🔴 The ACTING principal, never the bound one — a token mints AS it.
+ */
+export async function resolveDmPrincipal(
+  auth: import("eve/context").SessionAuth,
+): Promise<{ mode?: string; principalId?: string; platform?: string; workspace?: string; org?: string; trust?: string; declaredTrust?: string }> {
+  const bindCtx = await surfaceContextFromAuth(auth);
+  if (!bindCtx) return {};
+  try {
+    const b = bindFrom(bindCtx);
+    // `platform`, `org` and `workspace` feed the shared vault-subject derivation. 🔴 `declaredTrust` is the
+    // OPERATOR'S own declaration, deliberately NOT `b.trust` — that field is a join the platform mapper wins.
+    return { mode: b.mode, principalId: actingPrincipalId(b), platform: b.platform, workspace: b.workspace, org: resolvePartition(bindCtx).org, trust: b.trust, declaredTrust: b.declaredTrust };
+  } catch {
+    return {}; // unresolved — the caller's mode check fails closed
+  }
+}
+
+/**
+ * The EFFECTIVE user-OAuth vault subject — shared iff the caller is a confirmed link-set member, else their
+ * own QUALIFIED raw subject. The ONE composer (credential-grant-owner.ts calls it too); it THROWS without both.
+ */
+export async function effectiveUserVaultSubject(
+  connector: string,
+  org: string | undefined,
+  platform: string | undefined,
+  workspace: string | undefined,
+  principalId: string,
+): Promise<string> {
+  if (!org || !platform) {
+    throw new Error(
+      `connection "${connector}": cannot key a per-user credential — this DM surface resolved no ` +
+        `${!org ? "org" : "platform"}, and a vault subject must be qualified by both. Fail closed.`,
+    );
+  }
+  const raw = rawVaultSubject(org, platform, workspace, principalId);
+  if (!connectorLinkSetVaultEnabled()) return raw; // flag off → this account's own qualified subject
+  return (await sharedVaultSubjectFor(org, connector, platform, principalId, workspace)) ?? raw;
+}
+
+/** Classify a mint error as user-authorization-required. The registered {@link UserAuthFlowProvider}
+ *  is authoritative (it owns its own vendor error shape); on the no-adapter path (a unit test injecting
+ *  `mintUser`) fall back to the transport-neutral OAuth reason string ({@link userAuthRequiredSignal}). */
+function classifyUserAuthRequired(e: unknown): boolean {
+  const flow = userAuthFlowProvider();
+  return flow ? flow.isUserAuthRequired(e) : userAuthRequiredSignal(e);
+}
+
+/**
+ * Mid-turn SELF-HEAL: eve resumes a pre-consent turn, so turn.started never clears the per-turn memo. A cheap
+ * `hasFreshGrant` probe on the SAME provider ref and subject clears it; absent, no, or a throw ⇒ false.
+ */
+async function memoSelfHealsUserGrant(
+  connector: string,
+  auth: import("eve/context").SessionAuth,
+): Promise<boolean> {
+  const flow = userAuthFlowProvider();
+  if (!flow?.hasFreshGrant) return false; // no probe-capable flow ⇒ short-circuit unchanged
+  const cred = await boundConnectorCredential(connector, auth); // fail-soft (null on any failure)
+  if (cred?.type !== "user-oauth") return false; // only the per-user DM path carries a probe subject
+  const providerRef = vercelConnectorOf(cred);
+  if (!providerRef) return false;
+  const { mode, principalId, platform, workspace, org } = await resolveDmPrincipal(auth);
+  // Same fail-closed shape as the mint's user branch. `org`/`platform` join the guard because
+  // effectiveUserVaultSubject now THROWS without them (OPE-286) — this probe is a fail-SOFT churn
+  // protection, so it must answer "leave the short-circuit standing", never propagate an error out
+  // of getToken. The mint path below deliberately keeps the throw.
+  if (mode !== "dm" || !principalId || !org || !platform) return false;
+  // C.3: probe the SAME subject the mint would use (shared iff linked+ratified; else raw), so the
+  // self-heal never checks a different vault row than the one the fall-through mint targets (threat (j)).
+  const subjectId = await effectiveUserVaultSubject(connector, org, platform, workspace, principalId);
+  const probe = flow.hasFreshGrant.bind(flow);
+  if (!(await freshGrantConfirmed(() => probe(providerRef, { type: "user", id: subjectId })))) return false;
+  clearConnectorAuthRequired(connector); // targeted — this connector's flag + URL only, not the whole memo
+  return true;
+}
+
+/**
+ * The consent detour's ORIGIN. 🔴 `actorId` is PASSED IN, never re-derived — on a coalesced shared window
+ * the acting principal names the wrong person. `ctx` must be the tool's REAL SessionContext. Fail-soft.
+ */
+async function consentOriginFromAuth(
+  ctx: SessionContext,
+  actorId: string,
+): Promise<ConsentOrigin | undefined> {
+  try {
+    const bindCtx = await surfaceContextFromAuth(ctx.session.auth);
+    if (!bindCtx) return undefined;
+    const target = resolveReplyTarget(bindCtx);
+    if (!target) return undefined;
+    const b = bindFrom(bindCtx);
+    const sessionId = currentSessionId(ctx as unknown as import("../identity/binding.js").BindableContext);
+    return {
+      org: b.org,
+      surfaceKey: `${b.platform}/${b.workspace}/${b.surface}`,
+      target,
+      principalId: actorId,
+      ...(sessionId ? { sessionId } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The consent carriage for one detour, or undefined when this turn has no conversation to return to.
+ * NEVER THROWS: the person's authorization link must not depend on the resume plane working.
+ */
+async function consentCarriageFor(
+  connector: string,
+  ctx: SessionContext,
+  actorId: string,
+): Promise<ConsentCarriage | undefined> {
+  try {
+    const origin = await consentOriginFromAuth(ctx, actorId);
+    if (!origin) return undefined;
+    return await recordConsentDetour({
+      connector,
+      origin,
+      nowMs: Date.now(),
+      ttlMs: AUTH_URL_TTL_MS,
+      detourId: randomUUID(),
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Provider-routed auth that mints a PER-USER token in a DM and is byte-identical to {@link appProviderToken}
+ * on every other path. Wire it behind connectors.userPrincipal; `mintUser` is injectable for tests.
+ */
+export function userAwareProviderToken(
+  opts: { readonly connector: string; readonly fallbackSecretRef?: string; readonly fallbackBroker?: string; readonly directUrl?: string },
+  deps: { readonly mintUser?: ConnectUserTokenMinter; readonly startAuth?: ConnectAuthorizationStarter } = {},
+): ConnectionAuthResolver {
+  // Defaults delegate to the registered UserAuthFlowProvider (fail closed when no connector-OAuth
+  // adapter is wired). Tests inject `mintUser`/`startAuth` directly, so they never need a registered flow.
+  const mintUser = deps.mintUser ?? ((ref, params) => requireUserAuthFlow(opts.connector).mintUserToken(ref, params));
+  const startAuth =
+    deps.startAuth ?? ((ref, params, options) => requireUserAuthFlow(opts.connector).startAuthorization(ref, params, options));
+  return async (ctx: SessionContext): Promise<ConnectionAuthProvider> => ({
+    // principalType stays "app": OE resolves the human's identity from its OWN binding and passes a `{type:"user"}` subject to Connect per call.
+    // It does not delegate universe selection to eve's principal resolver, and the eve-native interactive consent flow is deliberately not used.
+    principalType: "app",
+    async getToken(o) {
+      // Short-circuit a connector already known auth-required this turn, repeating the SAME cached URL.
+      // Unless the human consented mid-turn — the grant probe self-heals and falls through to a real mint.
+      if (connectorAuthRequiredThisTurn(opts.connector) && !(await memoSelfHealsUserGrant(opts.connector, ctx.session.auth)))
+        throw connectorAuthRequiredError(opts.connector, connectorAuthUrlThisTurn(opts.connector));
+      await assertConnectorGranted(opts.connector, ctx.session.auth); // gate first — fail closed (DM wall included)
+      const cred = await boundConnectorCredential(opts.connector, ctx.session.auth);
+
+      // The per-user branch: a user-oauth credential (DM universe only) + a positively-dm surface.
+      if (cred?.type === "user-oauth") {
+        // OPE-523: the MCP-transport boot check, same rule + same message shape as the app path in
+        // resolveAppTokenFromCred — a user-oauth credential is checked here because it never reaches
+        // that shared function (it mints and returns before falling through).
+        if (opts.directUrl !== undefined) {
+          assertCredentialEndpointHostAllowed(cred.endpoints, opts.directUrl, `connection "${opts.connector}" credential "${cred.credential}"`);
+        }
+        const { mode, principalId, platform, workspace, org, trust, declaredTrust } = await resolveDmPrincipal(ctx.session.auth);
+        // principal-gate: presence — this id becomes the OAuth `subject.id` a personal token is minted
+        // AS, so a turn with nobody acting must not reach it. The spelling is the trap here and the
+        // reason this marker is worth more than most: `principalId` READS like the bound principal,
+        // which a fire always has (its attested creator), but `resolveDmPrincipal` above returns
+        // `actingPrincipalId(b)` — so this genuinely refuses a fire, and anyone "fixing" the field to
+        // the bound one would silently turn a live fence into an unsatisfiable check.
+        //
+        // 🔴 IT RUNS BEFORE THE MEMBER PLANE (OPE-944), AND THAT ORDER IS DELIBERATE. The member
+        // arm below mints for the turn's VERIFIED REQUESTER rather than for this id, so it could
+        // have been placed first — but keeping the presence gate ahead of it means a turn with
+        // NOBODY acting never reaches the member plane at all. On a live channel turn the acting
+        // principal is the last delivery's author and is present; it is absent on a FIRE, which
+        // has no business minting anyone's personal token. Refusing that here is one refusal
+        // instead of two, and it is the refusal `lint:principal-gate` rule 5 pins.
+        if (!principalId) {
+          throw new Error(
+            `connection "${opts.connector}": cannot mint a per-user token — this surface has no ` +
+              `resolvable user identity (principalId). Fail closed.`,
+          );
+        }
+        // THE MEMBER PLANE — the one designed way a per-user credential mints off a shared seat. It mints for the
+        // turn's ONE VERIFIED REQUESTER. `cred.memberPlane` is not the admission; the verdict below is.
+        let memberRequester: string | undefined;
+        if (mode !== "dm") {
+          // Defence in depth, unchanged for every credential that did NOT come through the member
+          // plane: a user-oauth cred otherwise resolves only in a DM (resolver.ts), and a leaked one
+          // never mints off a shared seat.
+          if (cred.memberPlane !== true) {
+            throw new Error(
+              `connection "${opts.connector}": a per-user credential resolved on a non-DM surface ` +
+                `(mode "${mode ?? "unresolved"}") — refusing to mint a personal token off a shared seat.`,
+            );
+          }
+          const verdict = memberPlaneVerdict({
+            armed: connectorMemberPlaneEnabled(),
+            // G1b — the plane needs the per-op tiering it depends on for its READ-ONLY rule (G5).
+            opTiered: connectorOpTieringEnabled(),
+            // The binding exists only because access/request.ts found the grant, so reaching here
+            // with `memberPlane: true` IS the grant. Passed explicitly anyway: `memberPlaneVerdict`
+            // is the ONE place the gates are joined, and a gate it cannot see is a gate nobody reviews.
+            granted: true,
+            requester: requesterForAuthority(ctx.session.auth),
+            nonMemberWake: nonMemberWakeForAuthority(ctx.session.auth),
+            // G4b — the operator's declaration for THIS room is the membership vouch, and absence is not "internal".
+            // The second conjunct is the demotion: the mapper's `external` verdict outranks a tenant-grain declaration.
+            roomVouchedInternal: roomVouchedInternalFrom(declaredTrust, trust),
+            // No op is named at the MINT — the read-only gate (G5) runs at the per-op approval seam
+            // (connectorOpApproval below), which is the only site that knows the op and the only one
+            // that runs BEFORE the op executes.
+          });
+          if (!verdict.admit) {
+            await auditMintOutcome(opts.connector, { subject: "user", plane: "member", outcome: "refused", reason: verdict.reason });
+            throw new Error(memberPlaneRefusalMessage(opts.connector, verdict.reason));
+          }
+          memberRequester = verdict.requesterPrincipalId;
+        }
+        // Whose account this token acts as: the ACTING principal on the DM path, the VERIFIED REQUESTER on the
+        // member plane. eve keeps only the last coalesced delivery's auth, so re-deriving the actor reopens OPE-673.
+        const actorId = memberRequester ?? principalId;
+        const connector = vercelConnectorOf(cred);
+        if (!connector)
+          throw new Error(`connection "${opts.connector}": user-oauth credential has no vercel-connect home`);
+        // C.3: derive the vault subject ONCE (shared iff linked+ratified; else raw) and thread it
+        // through the mint, the auth-URL mint, and the self-heal probe so all three address the SAME
+        // vault row (threat (j)). Flag-off / unlinked ⇒ this account's OWN qualified subject (OPE-286).
+        const subjectId = await effectiveUserVaultSubject(opts.connector, org, platform, workspace, actorId);
+        try {
+          const minted = await mintUser(connector, { subject: { type: "user", id: subjectId } });
+          // `shared` records ONLY whether link-set keying was used — never the subject value/token.
+          // Read off the SHAPE, not off `subjectId !== principalId`: since OPE-286 the raw branch is
+          // qualified too, so it never equals the bare principal id and that comparison would report
+          // every single mint as shared. The prefix is the property that actually distinguishes them.
+          await auditMintOutcome(opts.connector, {
+            subject: "user",
+            outcome: "ok",
+            shared: subjectId.startsWith(SHARED_VAULT_SUBJECT_PREFIX),
+            // WHICH PLANE ADMITTED THIS MINT — positive-only, like every other provenance stamp here,
+            // so a DM mint's row is byte-identical to before. It is the ONE observable that tells a
+            // personal token minted in a private DM apart from one minted into a shared room.
+            ...(memberRequester === undefined ? {} : { plane: "member", requester: memberRequester }),
+          });
+          return minted;
+        } catch (e) {
+          // The registered UserAuthFlowProvider owns its error shape; fall back to the generic OAuth
+          // "user authorization required" reason on the no-adapter test path (userAuthRequiredSignal).
+          const authRequired = classifyUserAuthRequired(e);
+          await auditMintOutcome(opts.connector, {
+            subject: "user",
+            outcome: authRequired ? "auth-required" : "error",
+            name: e instanceof Error ? e.name : "unknown",
+            ...(authRequired ? {} : { message: e instanceof Error ? e.message.slice(0, 160) : String(e).slice(0, 160) }),
+          });
+          if (authRequired) {
+            // #112 self-serve: mint a PERSONAL, short-lived authorization URL the user opens to connect
+            // their OWN account (no dashboard needed). If the mint ITSELF fails, degrade to the no-URL
+            // copy — never mask the auth-required signal with a secondary error.
+            let url: string | undefined;
+            try {
+              // Record the detour BEFORE the link is minted: it rides the mint as opaque carriage, so the return hop can
+              // resume THIS request. It carries conversation addresses only, and it expires with the link.
+              const consent = await consentCarriageFor(opts.connector, ctx, actorId);
+              // CAPABILITY-BEARING: whoever completes this URL binds THEIR third-party account to
+              // principalId. NEVER log it host-side (no console/audit) — it may appear ONLY in the
+              // thrown message below, which flows to the user's own DM.
+              url = (
+                await startAuth(
+                  connector,
+                  { subject: { type: "user", id: subjectId } },
+                  { expiresInMs: AUTH_URL_TTL_MS, ...(consent ? { consent } : {}) },
+                )
+              ).url;
+            } catch {
+              /* URL mint failed — degrade to the no-URL copy; still auth-required */
+            }
+            // Memoise (WITH the url): this connector is now known auth-required for the rest of THIS
+            // turn, so a retry short-circuits above with the SAME link instead of re-minting (#101 part c).
+            markConnectorAuthRequired(opts.connector, url);
+            const authorizeClause = url
+              ? personalAuthUrlClause(url)
+              : `Authorize it in your browser (connector "${connector}"), then ask again. `;
+            throw new Error(connectorAuthRequiredUserMessage(opts.connector, authorizeClause));
+          }
+          throw e;
+        }
+      }
+
+      // Every non-user path: the shared app body, byte-for-byte.
+      return resolveAppTokenFromCred(opts, cred, o);
+    },
+  });
+}
+
+// Tier-aware replacement for the connection's blanket `once()`: READ never prompts, WRITE prompts once per
+// session per op, DESTRUCTIVE prompts PER CALL — a first delete's approval never silences a second.
+
+/**
+ * An `approval` policy: reads open, writes gated once per op, destructive gated per call. 🔴 The read arm
+ * stays SYNCHRONOUS — it is the hot path; only the non-read arm awaits the member-plane credential read.
+ */
+export function connectorOpApproval(deps: ConnectorOpApprovalDeps = {}): ApprovalPolicy {
+  return (ctx): ApprovalStatus | Promise<ApprovalStatus> => {
+    // Defensive: eve only invokes a connection's approval for that connection's ops, so this
+    // is effectively always a `<connection>__<op>` name; treat anything else as not-applicable.
+    if (!isConnectorOpTool(ctx.toolName)) return "not-applicable";
+    // The EFFECTIVE tier: the built-in verb verdict, a consumer arm's lowering (floored at `write`), then any
+    // config-declared raise. Never `read` unless the built-in said `read`, so no arm can skip the card.
+    const tier = effectiveConnectorOpTier(ctx.toolName);
+    if (tier === "read") return "not-applicable"; // reads never prompt
+    return decideConnectorWrite(ctx, tier, deps.boundCredential ?? boundConnectorCredential, deps.dmPrincipal ?? resolveDmPrincipal);
+  };
+}
+
+/**
+ * Injectable dependencies for {@link connectorOpApproval} — a DI seam because the personal-write decision is
+ * a security gate, and a gate whose only test needs a live eve session is a gate nobody re-tests.
+ */
+export interface ConnectorOpApprovalDeps {
+  readonly boundCredential?: typeof boundConnectorCredential;
+  /** The is-DM predicate. THE SAME ONE THE MINT SITE TRUSTS — deliberately not a second reading of
+   *  "is this a channel", so the approval seam and the mint can never disagree about the surface. */
+  readonly dmPrincipal?: typeof resolveDmPrincipal;
+}
+
+/** The refusal for a qualified name this plane cannot resolve to a connection (OPE-1286). Names the
+ *  tool and says which plane owns the name, so the model reports a routing problem rather than
+ *  concluding the connector is down. */
+export function unresolvableConnectionRefusalMessage(toolName: string): string {
+  return (
+    `the tool "${toolName}" does not name a connection this plane can resolve. ` +
+    `A name in a reserved namespace belongs to the credential-grant plane, not to the connector plane. ` +
+    `The op did not run.`
+  );
+}
+
+/**
+ * The NON-READ half of {@link connectorOpApproval}, and the one site that decides a PERSONAL-credential write:
+ * a shared room is DENIED, a PROVEN DM takes the ordinary card. An unproven DM is not a DM — fail closed.
+ */
+async function decideConnectorWrite(
+  ctx: { readonly toolName: string; readonly approvedTools: ReadonlySet<string>; readonly session?: { readonly auth?: unknown } },
+  tier: ReturnType<typeof effectiveConnectorOpTier>,
+  boundCredential: typeof boundConnectorCredential,
+  dmPrincipal: typeof resolveDmPrincipal,
+): Promise<ApprovalStatus> {
+  const auth = ctx.session?.auth;
+  if (auth !== undefined && auth !== null) {
+    const sessionAuth = auth as Parameters<typeof boundConnectorCredential>[1];
+    // 🔴 The WHOLE slug, never the head segment: a connection slug may itself contain `__`, so a first-`__`
+    // split reads another connection's binding. `parseQualifiedToolName` is the tree's one parse of the name.
+    const connection = parseQualifiedToolName(ctx.toolName)?.connection;
+    // A name that parses to NO connection is a RESERVED namespace — refuse it rather than read the HEAD
+    // segment's binding. Defensive: eve invokes a connection's approval only for that connection's own ops.
+    if (connection === undefined) {
+      return { type: "denied", reason: unresolvableConnectionRefusalMessage(ctx.toolName) };
+    }
+    const bound = await boundCredential(connection, sessionAuth);
+    const memberPlaneBinding = bound?.memberPlane === true;
+    const personalCredential = bound?.principal === "user";
+    // Only the arm that USES the surface resolves it. A throw reads as an UNREADABLE surface, not an error —
+    // `{}` denies for a personal credential, which is the fail-closed direction.
+    const unreadableSurface: Awaited<ReturnType<typeof resolveDmPrincipal>> = {};
+    const surface =
+      personalCredential && !memberPlaneBinding ? await dmPrincipal(sessionAuth).catch(() => unreadableSurface) : unreadableSurface;
+    const verdict = personalConnectorWriteVerdict({
+      memberPlaneBinding,
+      personalCredential,
+      ...(surface.mode === undefined ? {} : { surfaceMode: surface.mode }),
+      ...(surface.principalId === undefined ? {} : { actingPrincipalId: surface.principalId }),
+      requester: requesterForAuthority(auth as MemberPlaneAuthLike),
+    });
+    if (!verdict.prompt) {
+      return { type: "denied", reason: personalWriteRefusalMessage(connection, verdict.reason) };
+    }
+  }
+  if (tier === "destructive") return "user-approval"; // per-call ALWAYS — never honour the once-per-op memo
+  if (ctx.approvedTools.has(ctx.toolName)) return "not-applicable"; // this write already approved this session
+  return "user-approval"; // a not-yet-approved write → prompt
+}
+
+/**
+ * The connection `approval` policy for the arming flag. 🔴 The return MUST stay a BARE FUNCTION: eve's resolver
+ * drops a configuration arm — so this site has NO response half, and an Approve click binds to no requester.
+ */
+export function connectorApprovalPolicy(): ApprovalPolicy {
+  // 🔴 The flag is read PER CALL, never at build: a connection file calls this at MODULE level, so a build-time
+  // read captures whatever the flag said before register-config ran. Both branches are built here.
+  const tiered = connectorOpApproval();
+  const blanket = once();
+  return withDuplicateApprovalGuard(
+    withUnattendedConnectorFence((ctx) => (connectorOpTieringEnabled() ? tiered : blanket)(ctx)),
+  );
+}
+
+// The unattended fence: an unattended run never parks on a WRITE- or DESTRUCTIVE-tier card. A write whose OWN
+// tool a routine declared is lifted and audited; the rest refuse. READS pass through — under the shipped flag
+// default the wrapped `once()` still prompts, so an unattended read parks as before. DESTRUCTIVE or TAINTED:
+// never lifted. An unreadable bag or surface stands down to the wrapped decision, unless an arm lowered the op.
+
+/**
+ * The approvals plane's `ask-unattended` refusal sentence, VERBATIM. Duplicated rather than imported because
+ * flow.ts drags in the whole card graph; scripts/connector-unattended-fence-test.ts §1 pins the two equal.
+ */
+export const ASK_UNATTENDED_SENTENCE =
+  "An unattended run cannot wait on an approval card; arm the permission on the routine's creation card, or ask a person to do this.";
+
+/**
+ * The plane's sentence for the same refusal on a TAINTED turn, VERBATIM: no standing grant lifts a taint
+ * floor, so the plain advice would be wrong. Duplicated and pinned like {@link ASK_UNATTENDED_SENTENCE}.
+ */
+export const TAINTED_ASK_UNATTENDED_SENTENCE =
+  "This turn read external content, so this action needs a person to confirm it — and this run is unattended, so there is nobody to ask. No standing grant lifts that; ask a person to do this, or raise it again in a turn that has not read anything external.";
+
+/**
+ * The connector plane's own remedy for a poisoned fire: a fire has no other turn, so the plane's advice is
+ * unactionable here. Only `contentOrigin: "internal"` lifts the taint, and this is advice — no verdict moves.
+ */
+export const TAINTED_CONNECTOR_ORIGIN_ADVICE =
+  "A fire has no other turn. A connector read marks every fire untrusted while its grant declares `contentOrigin: \"external\"` or declares nothing. Only `contentOrigin: \"internal\"` changes that, and it asserts that org members author everything the connection returns. Do not declare it to unblock a routine.";
+
+/**
+ * The refusal a fenced unattended op throws back: it names the op, the tier and the exact declaration to arm.
+ * A TAINTED turn gets the plane's tainted sentence and the origin advice instead — arming lifts nothing.
+ */
+export function unattendedConnectorRefusalMessage(
+  connection: string,
+  toolName: string,
+  tier: ReturnType<typeof effectiveConnectorOpTier>,
+  tainted: boolean,
+): string {
+  // The advice names THIS TOOL, never its connection: one declared-permission row lifts one tool,
+  // so coaching the human toward a connection-shaped string would coach them toward a declaration
+  // that is refused at propose time and would lift nothing if it were not.
+  const declaration = !tainted && tier === "write" ? `Declare "tool:${toolName}" on the routine's creation card to lift it. ` : "";
+  const origin = tainted ? `${TAINTED_CONNECTOR_ORIGIN_ADVICE} ` : "";
+  return (
+    `connection "${connection}": the ${tier}-tier op "${toolName}" needs approval and nobody is attending this run. ` +
+    `${tainted ? TAINTED_ASK_UNATTENDED_SENTENCE : ASK_UNATTENDED_SENTENCE} ${declaration}${origin}` +
+    `The op did not run.`
+  );
+}
+
+/** Injectable dependencies for {@link withUnattendedConnectorFence} — the surface resolve, the grant
+ *  read and the audit write. A DI seam for the same reason {@link ConnectorOpApprovalDeps} is one:
+ *  this is a security gate, and the defaults reach an operational store and an audit chain. */
+export interface UnattendedConnectorFenceDeps {
+  readonly surfaceContext?: typeof surfaceContextFromAuth;
+  /** Does a live declared permission of `kind` exist under `grantKey` for `org` right now? The dep
+   *  and the `grantKey` field beside it keep their spelling because they mirror the frozen card args
+   *  (OPE-1303); the plane's word for what they name is "declared permission". */
+  readonly grantExists?: (org: string, grantKey: string, kind: string, nowIso: string) => Promise<boolean>;
+  readonly audit?: typeof appendAudit;
+  /**
+   * Has this turn ingested untrusted external content? THE SAME read the approvals plane makes, injectable
+   * because it answers off a per-turn slot a hook seeds. 🔴 A throw is treated as POISONED, never as clean.
+   */
+  readonly tainted?: () => boolean;
+}
+
+/** The default grant read — the SAME `getSessionApproval` row the arming click wrote through
+ *  routines/declared-permissions.ts, under the SAME routine key the fire's bag carries. Fail-soft to `false`: an
+ *  unreadable store must never invent a lift. */
+async function routinePermissionExists(org: string, grantKey: string, kind: string, nowIso: string): Promise<boolean> {
+  return (await getOperationalStore().getSessionApproval(org, grantKey, kind, nowIso)) !== null;
+}
+
+/** What the fence needs to know about the turn behind an `ApprovalContext`, or `null` when the
+ *  surface will not bind at all (fence stands down — see the header's FAIL-SOFT note). */
+interface FencedTurnFacts {
+  readonly unattended: boolean;
+  readonly org: string;
+  readonly platform: string;
+  readonly workspace: string;
+  readonly surface?: string;
+  /** `platform/workspace/surface` — the audit scope a permission card freezes (OPE-1357). Taken off
+   *  the same `resolvePartition` read the audit rows are attributed from, never re-composed. */
+  readonly surfaceKey: string;
+  readonly principalId?: string;
+  /** The routine's declared-permission key off the fire's own bag, or undefined when this unattended
+   *  run is not a routine fire (a webhook fire, an eve schedule) and so can hold no declared
+   *  permission. `grantKey` is the PERSISTED wire spelling of that key (OPE-1303). */
+  readonly grantKey?: string;
+}
+
+async function fencedTurnFacts(
+  auth: import("eve/context").SessionAuth,
+  surfaceContext: typeof surfaceContextFromAuth,
+): Promise<FencedTurnFacts | null> {
+  const ctx = await surfaceContext(auth).catch(() => null);
+  if (!ctx) return null;
+  // Read through `routinePermissionKeyStamped`, which refuses a key outside the routine namespace. 🔴 The bag
+  // is picked at OBJECT level (`current ?? initiator`), as identity/binding.ts does — per-attribute widens it.
+  const grantKey = routinePermissionKeyStamped((auth.current ?? auth.initiator)?.attributes);
+  try {
+    const binding = bindFrom(ctx);
+    const partition = resolvePartition(ctx);
+    return {
+      // principal-gate: presence — a card is the only other answer here, and a card needs somebody
+      // in the room to click it. `unattendedFrom` is the ruled derivation (OPE-440/OPE-497); reading
+      // `binding.principalId` instead would answer "a human is present" for every fire, because a
+      // fire binds as its routine's ATTESTED creator.
+      unattended: unattendedFrom(binding),
+      org: partition.org,
+      platform: partition.platform,
+      workspace: partition.workspace,
+      surfaceKey: partition.surfaceKey,
+      ...(partition.surface === undefined ? {} : { surface: partition.surface }),
+      ...(binding.principalId === undefined ? {} : { principalId: binding.principalId }),
+      ...(grantKey === undefined ? {} : { grantKey }),
+    };
+  } catch {
+    return null; // an unbindable surface — stand down, exactly as the header states
+  }
+}
+
+/** Run `fn` and answer `fallback` on ANY failure — a rejected promise OR a SYNCHRONOUS throw. The
+ *  plain `.catch()` these replace missed the second, so an injected dependency that threw rejected
+ *  the whole approval policy, and a policy that rejects is nobody's answer. */
+async function callAsync<T>(fn: () => Promise<T>, fallback: T): Promise<T> {
+  try {
+    return await fn();
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * The taint read, and it FAILS CLOSED: a throw reads as POISONED, so the op is refused rather than lifted.
+ * Rejecting is barred — a policy that rejects is nobody's answer. The live reader catches its own failures.
+ */
+function taintedOrPoisoned(read: () => boolean): boolean {
+  try {
+    return read();
+  } catch {
+    return true; // unable to prove the turn is clean ⇒ treat it as poisoned
+  }
+}
+
+/** True for a decision that would actually raise a card. A local three-line copy of
+ *  access/approval-dedupe.ts's own predicate rather than an import: that module is the duplicate-card
+ *  guard's, this plane is the connector plane's, and eve's `ApprovalStatus` union is the shared
+ *  contract both read. */
+function decisionWouldPrompt(decision: ApprovalStatus): boolean {
+  if (decision === true || decision === "user-approval") return true;
+  return typeof decision === "object" && decision !== null && decision.type === "user-approval";
+}
+
+/** Wrap a connector-op approval policy so an UNATTENDED run never parks on a card — see the block above. */
+export function withUnattendedConnectorFence(
+  policy: ApprovalPolicy,
+  deps: UnattendedConnectorFenceDeps = {},
+): ApprovalPolicy {
+  const surfaceContext = deps.surfaceContext ?? surfaceContextFromAuth;
+  const permissionExists = deps.grantExists ?? routinePermissionExists;
+  const audit = deps.audit ?? appendAudit;
+  const tainted = deps.tainted ?? untrustedIngestedThisTurn;
+  return async (ctx): Promise<ApprovalStatus> => {
+    const decision = await policy(ctx);
+    if (!isConnectorOpTool(ctx.toolName)) return decision;
+    // The parse decides applicability, never the lookup key — the key is the WHOLE tool name. The parse answers
+    // no `connection` for a RESERVED namespace, and names the connection the refusal and the audit rows report.
+    const connection = parseQualifiedToolName(ctx.toolName)?.connection;
+    // The JOIN of the built-in and the seam — the second unattended floor. An arm may LOWER a verdict to `write`,
+    // which is the liftable tier, so reading the seam alone would make a lowered delete liftable on a fire.
+    const baseTier = classifyConnectorOpTier(ctx.toolName);
+    const seamTier = effectiveConnectorOpTier(ctx.toolName);
+    const tier = joinConnectorOpTiers(baseTier, seamTier);
+    if (tier === "read") return decision; // reads are OPEN; the tier classifier is untouched
+    // The fence engages on an arm's lowering too: a lowered destructive op can answer `not-applicable` off the
+    // session memo, with no card to fall back on, and an unattended fire would then execute it unaudited.
+    const seamBelowBuiltIn = tier !== seamTier;
+    if (!decisionWouldPrompt(decision) && !seamBelowBuiltIn) return decision;
+    // An arm-lowered op is UNLIFTABLE — the arm floor is `write`, so the join is `destructive` and the lift arm
+    // requires `write`. Each stand-down below refuses instead of returning the wrapped decision when it lowered.
+    const poisoned = taintedOrPoisoned(tainted);
+    const loweredRefusal = (): ApprovalStatus => ({
+      type: "denied",
+      reason: unattendedConnectorRefusalMessage(connection ?? "", ctx.toolName, tier, poisoned),
+    });
+    // The no-connection stand-down, held back to here so it can read `seamBelowBuiltIn`. `undefined` is a
+    // RESERVED namespace (`grant__…`) or a malformed reserved name — the credential-grant plane, not
+    // this one, and the arm is never consulted for such a name, so `seamBelowBuiltIn` is false there. An
+    // EMPTY connection is a name of the shape `__<verb>`, whose parse answers `connection: ""`; that
+    // is NOT `undefined`, so the arm IS consulted and can lower it. The two cases are not alike.
+    if (connection === undefined || connection.length === 0) return seamBelowBuiltIn ? loweredRefusal() : decision;
+    const auth = ctx.session?.auth;
+    if (auth === undefined || auth === null) return seamBelowBuiltIn ? loweredRefusal() : decision; // unreadable bag
+    const facts = await fencedTurnFacts(auth as import("eve/context").SessionAuth, surfaceContext);
+    if (facts === null) return seamBelowBuiltIn ? loweredRefusal() : decision; // an unbindable surface
+    // A PROVEN ATTENDED TURN PASSES THROUGH ON EVERY PATH, arm or no arm: the read succeeded, so
+    // attendedness is known rather than unknown, and a human is there to answer whatever the wrapped
+    // policy said. This is the arm a consumer registers an arm FOR.
+    if (!facts.unattended) return decision;
+    // PER-TOOL: the key is the whole qualified name, so a row for one tool leaves every other tool
+    // on the same connection refused. A LEGACY `connector.op:<slug>` row cannot satisfy this lookup
+    // — different prefix, different value — which is how it is refused rather than widened.
+    const kind = connectorToolPermissionKind(ctx.toolName);
+    const nowIso = new Date().toISOString();
+    // DESTRUCTIVE-NEVER: only the WRITE tier is liftable, so only a write can be lifted.
+    // TAINTED-NEVER: a turn that has read external content is never lifted, at either tier.
+    const lifted =
+      !poisoned &&
+      tier === "write" &&
+      facts.grantKey !== undefined &&
+      (await callAsync(() => permissionExists(facts.org, facts.grantKey as string, kind, nowIso), false));
+    const where = {
+      org: facts.org,
+      platform: facts.platform,
+      workspace: facts.workspace,
+      ...(facts.surface === undefined ? {} : { surface: facts.surface }),
+      ...(facts.principalId === undefined ? {} : { principalId: facts.principalId }),
+    };
+    // IDS AND VERBS ONLY, never the op's arguments. Best-effort: an injected audit that throws must not turn a
+    // refusal into a rejected approval policy.
+    if (lifted) {
+      await callAsync(
+        () =>
+          audit({
+            ...where,
+            action: "connector.unattended_lift",
+            detail: { connection, op: ctx.toolName, tier, grant: kind, routine: facts.grantKey },
+          }),
+        undefined,
+      );
+      return "not-applicable";
+    }
+    await callAsync(
+      () =>
+        audit({
+          ...where,
+          action: "connector.refused",
+          detail: {
+            connection,
+            op: ctx.toolName,
+            tier,
+            reason: poisoned ? "ask-unattended-tainted" : "ask-unattended",
+            grant: kind,
+            ...(poisoned ? { tainted: true } : {}),
+            ...(facts.grantKey === undefined ? { routine: null } : { routine: facts.grantKey }),
+          },
+        }),
+      undefined,
+    );
+    // The routine permission card: one click in the routine's own room arms the declaration this refusal coaches.
+    // It adds a clause and nothing else — the four conditions below, and neither seam bound can move a verdict.
+    const routineKey = facts.grantKey;
+    const requestedBy = facts.principalId;
+    const card =
+      tier === "write" && routineKey !== undefined && requestedBy !== undefined
+        ? await offerRoutinePermissionCardFor({
+            org: facts.org,
+            declaration: `tool:${ctx.toolName}`,
+            // The kind the planner would freeze. The seam needs it for the CAPPED path, where it
+            // records this refusal on the run ledger itself rather than reaching the planner.
+            grantKind: connectorToolPermissionKind(ctx.toolName),
+            grantKey: routineKey,
+            scopeKey: facts.surfaceKey,
+            requestedBy,
+            tainted: poisoned,
+            // NO WAIT ON THIS PLANE: a wait here holds the connector call, and the durable step around it, open. The card
+            // still answers its own question — a click writes the standing row the NEXT unattended fire's lift arm reads.
+            waitBudgetMs: 0,
+          })
+        : { clause: "" };
+    return { type: "denied", reason: unattendedConnectorRefusalMessage(connection, ctx.toolName, tier, poisoned) + card.clause };
+  };
+}
+
+/**
+ * Interactive OAuth on behalf of the end user — the DM/personal universe. Pins `principalType: "user"` and
+ * runs the hard gate in getToken. NEVER grant a user-principal connector to a domain binding.
+ */
+export function userInteractiveOAuth<Resume extends JsonValue = JsonValue>(opts: {
+  readonly connector: string;
+  readonly getToken: InteractiveAuthorizationDefinition<Resume>["getToken"];
+  readonly startAuthorization: InteractiveAuthorizationDefinition<Resume>["startAuthorization"];
+  readonly completeAuthorization: InteractiveAuthorizationDefinition<Resume>["completeAuthorization"];
+  readonly displayName?: string;
+  readonly evict?: InteractiveAuthorizationDefinition<Resume>["evict"];
+}): ConnectionAuthResolver {
+  // defineInteractiveAuthorization pins principalType: "user" itself (interactive OAuth
+  // is user-only), so we don't pass it.
+  return async (ctx: SessionContext): Promise<ConnectionAuthProvider> =>
+    defineInteractiveAuthorization<Resume>({
+      displayName: opts.displayName,
+      async getToken(o) {
+        await assertConnectorGranted(opts.connector, ctx.session.auth); // gate first — fail closed
+        return opts.getToken(o);
+      },
+      startAuthorization: opts.startAuthorization,
+      completeAuthorization: opts.completeAuthorization,
+      evict: opts.evict,
+    });
+}