@open-everywhere/core 0.1.0

package/dist/agent/connections/connector-auth.js

@@ -0,0 +1,745 @@
+// 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, } from "eve/connections";
+import { once } 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";
+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, } 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, } from "./user-auth-flow.js";
+import { randomUUID } from "node:crypto";
+import { recordConsentDetour } 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) {
+    const delegated = delegatedRequesterThisTurn(undefined);
+    if (delegated?.kind === "requester")
+        return { kind: "requester", principalId: delegated.principalId };
+    if (delegated?.kind === "unverified")
+        return { kind: "unverified" };
+    if (delegated?.kind === "none")
+        return { kind: "none" };
+    return requesterFromAuth(auth, OE_REQUESTER_ATTR, REQUESTER_UNVERIFIED);
+}
+function nonMemberWakeForAuthority(auth) {
+    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) {
+    return async (ctx) => ({
+        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) {
+    return async (ctx) => ({
+        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) {
+    return async (ctx) => ({
+        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, cred, o) {
+    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 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, detail) {
+    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 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 = (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) {
+    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, authorizeClause) {
+    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) {
+    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, org, platform, workspace, principalId) {
+    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) {
+    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, auth) {
+    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, actorId) {
+    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);
+        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, ctx, actorId) {
+    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, deps = {}) {
+    // 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) => ({
+        // 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;
+                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;
+                        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 = {}) {
+    return (ctx) => {
+        // 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);
+    };
+}
+/** 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) {
+    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, tier, boundCredential, dmPrincipal) {
+    const auth = ctx.session?.auth;
+    if (auth !== undefined && auth !== null) {
+        const sessionAuth = auth;
+        // 🔴 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 = {};
+        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),
+        });
+        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() {
+    // 🔴 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, toolName, tier, tainted) {
+    // 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.`);
+}
+/** 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, grantKey, kind, nowIso) {
+    return (await getOperationalStore().getSessionApproval(org, grantKey, kind, nowIso)) !== null;
+}
+async function fencedTurnFacts(auth, surfaceContext) {
+    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(fn, fallback) {
+    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) {
+    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) {
+    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, deps = {}) {
+    const surfaceContext = deps.surfaceContext ?? surfaceContextFromAuth;
+    const permissionExists = deps.grantExists ?? routinePermissionExists;
+    const audit = deps.audit ?? appendAudit;
+    const tainted = deps.tainted ?? untrustedIngestedThisTurn;
+    return async (ctx) => {
+        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 = () => ({
+            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, 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, 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(opts) {
+    // defineInteractiveAuthorization pins principalType: "user" itself (interactive OAuth
+    // is user-only), so we don't pass it.
+    return async (ctx) => defineInteractiveAuthorization({
+        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,
+    });
+}
+//# sourceMappingURL=connector-auth.js.map