@opengeni/db 3.7.4 → 4.0.0-canary.0

package/drizzle/0405_tool_gateway_approval_capabilities.sql

@@ -0,0 +1,184 @@
+-- deployment-mode: maintenance
+-- Current-human HTTP tool calls use hash-only, single-use approval capabilities
+-- instead of trusting a caller-provided approval boolean.
+-- This changes the exact runtime-posture table/grant/RLS contract. Stop every
+-- API, control worker, and turn worker before applying it, and never restart a
+-- pre-0404 image after commit.
+
+SET LOCAL lock_timeout = '5s';
+SET LOCAL statement_timeout = '5min';
+
+DO $tool_gateway_approval_runtime_drain_before$
+DECLARE
+  configured_roles_text text := nullif(
+    current_setting('opengeni.migration_application_roles', true), ''
+  );
+  configured_roles jsonb;
+BEGIN
+  IF configured_roles_text IS NULL THEN
+    RAISE EXCEPTION
+      '0404 tool gateway approval activation requires an explicit application database role list'
+      USING ERRCODE = '55000';
+  END IF;
+  BEGIN
+    configured_roles := configured_roles_text::jsonb;
+  EXCEPTION WHEN OTHERS THEN
+    RAISE EXCEPTION
+      '0404 tool gateway approval activation received a malformed application database role list'
+      USING ERRCODE = '55000';
+  END;
+  IF jsonb_typeof(configured_roles) <> 'array'
+    OR jsonb_array_length(configured_roles) NOT BETWEEN 1 AND 16
+    OR EXISTS (
+      SELECT 1 FROM jsonb_array_elements(configured_roles) AS roles(value)
+      WHERE jsonb_typeof(value) <> 'string'
+        OR btrim(value #>> '{}') = ''
+        OR octet_length(value #>> '{}') > 63
+    )
+    OR (
+      SELECT count(*) FROM jsonb_array_elements_text(configured_roles)
+    ) <> (
+      SELECT count(DISTINCT value)
+      FROM jsonb_array_elements_text(configured_roles) AS roles(value)
+    )
+  THEN
+    RAISE EXCEPTION
+      '0404 tool gateway approval activation received an invalid application database role list'
+      USING ERRCODE = '55000';
+  END IF;
+  IF EXISTS (
+    SELECT 1 FROM pg_stat_activity activity
+    JOIN jsonb_array_elements_text(configured_roles) roles(role_name)
+      ON roles.role_name = activity.usename
+    WHERE activity.datname = current_database()
+      AND activity.pid <> pg_backend_pid()
+  )
+  THEN
+    RAISE EXCEPTION
+      '0404 tool gateway approval activation requires all configured OpenGeni application database sessions to be stopped'
+      USING ERRCODE = '55000';
+  END IF;
+END
+$tool_gateway_approval_runtime_drain_before$;
+
+CREATE TABLE "tool_gateway_approval_capabilities" (
+  "token_hash" text PRIMARY KEY,
+  "account_id" uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id" uuid NOT NULL REFERENCES "workspaces"("id") ON DELETE CASCADE,
+  "subject_id" text NOT NULL,
+  "operation_id" uuid NOT NULL,
+  "catalog_digest" text NOT NULL,
+  "server_id" text NOT NULL,
+  "tool_name" text NOT NULL,
+  "arguments_digest" text NOT NULL,
+  "authority_digest" text NOT NULL,
+  "expires_at" timestamptz NOT NULL,
+  "consumed_at" timestamptz,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "tool_gateway_approval_capabilities_workspace_account_fk"
+    FOREIGN KEY ("workspace_id", "account_id")
+    REFERENCES "workspaces"("id", "account_id") ON DELETE CASCADE,
+  CONSTRAINT "tool_gateway_approval_capabilities_token_hash_chk"
+    CHECK ("token_hash" ~ '^[0-9a-f]{64}$'),
+  CONSTRAINT "tool_gateway_approval_capabilities_catalog_digest_chk"
+    CHECK ("catalog_digest" ~ '^[0-9a-f]{64}$'),
+  CONSTRAINT "tool_gateway_approval_capabilities_arguments_digest_chk"
+    CHECK ("arguments_digest" ~ '^[0-9a-f]{64}$'),
+  CONSTRAINT "tool_gateway_approval_capabilities_authority_digest_chk"
+    CHECK ("authority_digest" ~ '^[0-9a-f]{64}$'),
+  CONSTRAINT "tool_gateway_approval_capabilities_subject_chk"
+    CHECK (length(btrim("subject_id")) BETWEEN 1 AND 1024),
+  CONSTRAINT "tool_gateway_approval_capabilities_identity_chk"
+    CHECK (
+      length("server_id") BETWEEN 1 AND 256
+      AND length("tool_name") BETWEEN 1 AND 512
+    ),
+  CONSTRAINT "tool_gateway_approval_capabilities_expiry_chk"
+    CHECK ("expires_at" > "created_at" AND "expires_at" <= "created_at" + interval '10 minutes')
+);
+
+CREATE UNIQUE INDEX "tool_gateway_approval_capabilities_operation_uq"
+  ON "tool_gateway_approval_capabilities" ("workspace_id", "subject_id", "operation_id");
+CREATE INDEX "tool_gateway_approval_capabilities_expires_idx"
+  ON "tool_gateway_approval_capabilities" ("expires_at", "token_hash");
+CREATE INDEX "tool_gateway_approval_capabilities_live_subject_expiry_idx"
+  ON "tool_gateway_approval_capabilities" (
+    "workspace_id", "subject_id", "expires_at", "token_hash"
+  )
+  WHERE "consumed_at" IS NULL;
+
+ALTER TABLE "tool_gateway_approval_capabilities" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "tool_gateway_approval_capabilities" FORCE ROW LEVEL SECURITY;
+CREATE POLICY "workspace_subject_isolation" ON "tool_gateway_approval_capabilities"
+  USING (
+    opengeni_private.workspace_rls_visible("account_id", "workspace_id")
+    AND "subject_id" = opengeni_private.current_subject_id()
+  )
+  WITH CHECK (
+    opengeni_private.workspace_rls_visible("account_id", "workspace_id")
+    AND "subject_id" = opengeni_private.current_subject_id()
+  );
+
+REVOKE ALL ON "tool_gateway_approval_capabilities" FROM PUBLIC;
+
+-- The application role list is drain detection only. Remove any explicit ACL
+-- inherited from owner default privileges, including an old side of a runtime
+-- role rotation. The post-migration role provisioner grants only the exact
+-- current target application role.
+DO $tool_gateway_approval_table_acl_reset$
+DECLARE
+  data_schema text := pg_catalog.current_schema();
+  role_name text;
+BEGIN
+  EXECUTE pg_catalog.format(
+    'REVOKE ALL ON TABLE %I.tool_gateway_approval_capabilities FROM PUBLIC',
+    data_schema
+  );
+  FOR role_name IN
+    SELECT grantee_role.rolname
+    FROM pg_catalog.pg_class relation
+    CROSS JOIN LATERAL pg_catalog.aclexplode(
+      coalesce(
+        relation.relacl,
+        pg_catalog.acldefault('r', relation.relowner)
+      )
+    ) privilege
+    INNER JOIN pg_catalog.pg_roles grantee_role
+      ON grantee_role.oid = privilege.grantee
+    WHERE relation.oid = pg_catalog.to_regclass(
+        pg_catalog.format('%I.tool_gateway_approval_capabilities', data_schema)
+      )
+      AND privilege.grantee <> 0
+      AND privilege.grantee <> relation.relowner
+    GROUP BY grantee_role.rolname
+    ORDER BY grantee_role.rolname COLLATE "C"
+  LOOP
+    EXECUTE pg_catalog.format(
+      'REVOKE ALL ON TABLE %I.tool_gateway_approval_capabilities FROM %I',
+      data_schema,
+      role_name
+    );
+  END LOOP;
+END
+$tool_gateway_approval_table_acl_reset$;
+
+DO $tool_gateway_approval_runtime_drain_after$
+DECLARE
+  configured_roles jsonb := current_setting(
+    'opengeni.migration_application_roles', false
+  )::jsonb;
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_stat_activity activity
+    JOIN jsonb_array_elements_text(configured_roles) roles(role_name)
+      ON roles.role_name = activity.usename
+    WHERE activity.datname = current_database()
+      AND activity.pid <> pg_backend_pid()
+  )
+  THEN
+    RAISE EXCEPTION
+      '0404 tool gateway approval activation observed a configured OpenGeni application database session after schema installation'
+      USING ERRCODE = '55000';
+  END IF;
+END
+$tool_gateway_approval_runtime_drain_after$;

package/drizzle/0406_workspace_html_site_sources.sql

@@ -0,0 +1,71 @@
+-- deployment-mode: rolling
+-- Retain editable source and exact requested-tool identities beside each
+-- immutable Workspace HTML artifact version. Existing versions remain valid:
+-- their source columns stay NULL and readers derive a one-file index.html
+-- source bundle from the already-verified published HTML.
+
+SET LOCAL lock_timeout = '5s';
+SET LOCAL statement_timeout = '5min';
+
+ALTER TABLE "workspace_artifact_versions"
+  ADD COLUMN "source_key" text,
+  ADD COLUMN "source_sha256" text,
+  ADD COLUMN "source_size_bytes" integer,
+  ADD COLUMN "requested_tools" jsonb NOT NULL DEFAULT '[]'::jsonb;
+
+ALTER TABLE "workspace_artifact_versions"
+  DROP CONSTRAINT "workspace_artifact_versions_content_chk";
+
+ALTER TABLE "workspace_artifact_versions"
+  ADD CONSTRAINT "workspace_artifact_versions_content_chk" CHECK (
+    "content_type" = 'text/html'
+    AND "content_sha256" ~ '^[0-9a-f]{64}$'
+    AND "size_bytes" BETWEEN 1 AND 4194304
+    AND length("content_key") BETWEEN 1 AND 1024
+    AND (
+      (
+        "source_key" IS NULL
+        AND "source_sha256" IS NULL
+        AND "source_size_bytes" IS NULL
+      ) OR (
+        "source_key" IS NOT NULL
+        AND "source_sha256" IS NOT NULL
+        AND "source_size_bytes" IS NOT NULL
+        AND
+        length("source_key") BETWEEN 1 AND 1024
+        AND "source_sha256" ~ '^[0-9a-f]{64}$'
+        AND "source_size_bytes" BETWEEN 1 AND 4194304
+      )
+    )
+    AND jsonb_typeof("requested_tools") = 'array'
+    AND jsonb_array_length("requested_tools") <= 128
+  ) NOT VALID;
+
+ALTER TABLE "workspace_artifact_versions"
+  VALIDATE CONSTRAINT "workspace_artifact_versions_content_chk";
+
+ALTER TABLE "workspace_artifact_events"
+  ADD COLUMN "request_digest" text;
+
+ALTER TABLE "workspace_artifact_events"
+  ADD CONSTRAINT "workspace_artifact_events_request_digest_chk"
+  CHECK (
+    "request_digest" IS NULL
+    OR "request_digest" ~ '^[0-9a-f]{64}$'
+  ) NOT VALID;
+
+ALTER TABLE "workspace_artifact_events"
+  VALIDATE CONSTRAINT "workspace_artifact_events_request_digest_chk";
+
+ALTER TABLE "workspace_artifact_events"
+  DROP CONSTRAINT "workspace_artifact_events_type_chk";
+
+ALTER TABLE "workspace_artifact_events"
+  ADD CONSTRAINT "workspace_artifact_events_type_chk"
+  CHECK ("type" IN ('published', 'rolled_back', 'archived', 'restored')) NOT VALID;
+
+ALTER TABLE "workspace_artifact_events"
+  VALIDATE CONSTRAINT "workspace_artifact_events_type_chk";
+
+CREATE INDEX "workspace_artifacts_status_list_idx"
+  ON "workspace_artifacts" ("workspace_id", "status", "updated_at");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/db",
-  "version": "3.7.4",
+  "version": "4.0.0-canary.0",
   "description": "OpenGeni persistence: Drizzle schema, RLS-scoped query layer, the SQL migration runner, and role provisioning.",
   "license": "Apache-2.0",
   "repository": {
@@ -78,11 +78,11 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/codemode": "^0.4.22",
-    "@opengeni/codex": "^0.2.20",
-    "@opengeni/config": "^0.22.5",
-    "@opengeni/contracts": "^2.9.2",
-    "@opengeni/network": "^0.2.3",
+    "@opengeni/codemode": "^0.4.27-canary.0",
+    "@opengeni/codex": "^0.2.21-canary.0",
+    "@opengeni/config": "^1.0.0-canary.0",
+    "@opengeni/contracts": "^2.13.0-canary.0",
+    "@opengeni/network": "^0.3.0-canary.0",
     "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.7"
   },

package/src/automations.ts

@@ -223,6 +223,8 @@ export async function createAutomationTrigger(
     createdBySubjectId: string;
     request: CreateAutomationTriggerRequest;
     adapterId: string;
+    /** Trusted database-only admission seam. Throwing rolls creation back. */
+    beforeCreateCommit?: (tx: Database) => Promise<void>;
   },
 ): Promise<AutomationTrigger> {
   return await withWorkspaceRls(
@@ -289,6 +291,7 @@ export async function createAutomationTrigger(
             throw new Error("Automation Pack trigger must use its frozen manifest template");
           }
         }
+        await input.beforeCreateCommit?.(tx);
         const [head] = await tx
           .insert(schema.automationTriggers)
           .values({
@@ -438,6 +441,8 @@ export async function updateAutomationTrigger(
     triggerId: string;
     subjectId: string;
     request: UpdateAutomationTriggerRequest;
+    /** Trusted database-only admission seam. Throwing rolls the revision back. */
+    beforeUpdateCommit?: (tx: Database) => Promise<void>;
   },
 ): Promise<AutomationTrigger | null> {
   return await withWorkspaceRls(
@@ -478,6 +483,7 @@ export async function updateAutomationTrigger(
             "Pack-owned automation triggers must be managed through their Pack setup API",
           );
         }
+        await input.beforeUpdateCommit?.(tx);
         const revisionNumber = existing.head.currentRevision + 1;
         const [head] = await tx
           .update(schema.automationTriggers)
@@ -696,7 +702,9 @@ export async function claimAutomationRun(
           .for("update")
           .limit(1);
         if (!row) return null;
-        if (row.status === "dispatched" || row.status === "skipped") return mapRunExecution(row);
+        if (row.status === "dispatched" || row.status === "skipped" || row.status === "failed") {
+          return mapRunExecution(row);
+        }
         const [updated] = await tx
           .update(schema.automationRuns)
           .set({

package/src/capability-integrations.ts

@@ -176,6 +176,8 @@ export type ApiIntegrationRuntime = {
   providerDomain: string;
   authScheme: Record<string, unknown>;
   connectionRef: McpServerConnectionRef | null;
+  /** Live credential authority revision used to invalidate stale human approvals. */
+  connectionAuthorityGeneration: number | null;
   allowedTools: string[];
   requireApproval: true | string[];
   revision: StoredApiIntegrationRevision;
@@ -843,6 +845,7 @@ export async function listInstalledApiIntegrationsInRlsContext(
       runtimeKey: schema.integrationFacetBindings.runtimeKey,
       bindingConfig: schema.integrationFacetBindings.config,
       connectionId: schema.integrationFacetBindings.connectionId,
+      connectionAuthorityGeneration: schema.connections.authorityGeneration,
       revision: schema.integrationSpecRevisions.spec,
     })
     .from(schema.integrationFacetBindings)
@@ -890,6 +893,10 @@ export async function listInstalledApiIntegrationsInRlsContext(
         eq(schema.integrationSpecRevisions.status, "active"),
       ),
     )
+    .leftJoin(
+      schema.connections,
+      eq(schema.connections.id, schema.integrationFacetBindings.connectionId),
+    )
     .where(
       and(
         eq(schema.capabilityPluginInstallations.workspaceId, workspaceId),
@@ -998,6 +1005,7 @@ export async function listInstalledApiIntegrationsInRlsContext(
         providerDomain: row.providerDomain,
         authScheme: objectValue(row.authScheme),
         connectionRef,
+        connectionAuthorityGeneration: row.connectionAuthorityGeneration,
         allowedTools,
         requireApproval,
         revision,

package/src/codemode-operations.ts

@@ -92,6 +92,14 @@ export async function submitCodemodeOperation(
     { accountId: input.accountId, workspaceId: input.workspaceId },
     async (scopedDb) =>
       await scopedDb.transaction(async (tx) => {
+        // Serialize the caller-owned id before testing for an existing row.
+        // Without this fence, two first submissions can both observe absence
+        // and the later insert fails its unique constraint instead of replaying.
+        await tx.execute(sql`
+          select pg_advisory_xact_lock(
+            hashtextextended(${`codemode-operation:${input.workspaceId}:${call.operationId}`}, 0)
+          )
+        `);
         const [existing] = await tx
           .select()
           .from(schema.sessionAttemptCodemodeCalls)
@@ -213,7 +221,13 @@ export async function getCodemodeOperation(
 }
 
 export type ClaimCodemodeOperationResult =
-  | { status: "claimed"; operation: CodemodeOperationValue; claimId: string }
+  | {
+      status: "claimed";
+      operation: CodemodeOperationValue;
+      claimId: string;
+      reclaimed: boolean;
+    }
+  | { status: "execution_owner_lost"; operation: CodemodeOperationValue; claimId: string }
   | { status: "already_running" | "terminal"; operation: CodemodeOperationValue }
   | { status: "rejected"; operation: CodemodeOperationValue | null };
 
@@ -250,30 +264,20 @@ export async function claimCodemodeOperation(
         }
         const now = input.now ?? new Date();
         const claimExpiresAt = new Date(now.getTime() + boundedClaimLeaseMs(input.claimLeaseMs));
+        let reclaimed = false;
         if (row.state === "running") {
           if (!row.claimExpiresAt || row.claimExpiresAt.getTime() > now.getTime()) {
             return { status: "already_running", operation: mapOperation(row) };
           }
           if (row.executionStartedAt) {
-            const [unknown] = await tx
-              .update(schema.sessionAttemptCodemodeCalls)
-              .set({
-                state: "outcome_unknown",
-                errorCode: "worker_lost_during_execution",
-                errorMessage:
-                  "The execution owner disappeared after the tool call began. Inspect actual state before retrying.",
-                completedAt: now,
-                updatedAt: now,
-              })
-              .where(
-                and(
-                  eq(schema.sessionAttemptCodemodeCalls.operationId, input.operationId),
-                  eq(schema.sessionAttemptCodemodeCalls.state, "running"),
-                  eq(schema.sessionAttemptCodemodeCalls.claimId, row.claimId!),
-                ),
-              )
-              .returning();
-            return { status: "terminal", operation: mapOperation(unknown ?? row) };
+            if (!row.claimId) {
+              throw new Error("Codemode running operation is missing its claim id");
+            }
+            return {
+              status: "execution_owner_lost",
+              operation: mapOperation(row),
+              claimId: row.claimId,
+            };
           }
           const [requeued] = await tx
             .update(schema.sessionAttemptCodemodeCalls)
@@ -294,6 +298,7 @@ export async function claimCodemodeOperation(
             .returning();
           if (!requeued) throw new Error("Codemode expired claim recovery lost its row lock");
           row = requeued;
+          reclaimed = true;
         }
         if (isTerminalState(row.state)) return { status: "terminal", operation: mapOperation(row) };
 
@@ -353,7 +358,12 @@ export async function claimCodemodeOperation(
           )
           .returning();
         if (!claimed) throw new Error("Codemode operation claim lost its row lock");
-        return { status: "claimed", operation: mapOperation(claimed), claimId: input.claimId };
+        return {
+          status: "claimed",
+          operation: mapOperation(claimed),
+          claimId: input.claimId,
+          reclaimed,
+        };
       }),
   );
 }

package/src/codex-token-resolver.ts

@@ -101,7 +101,12 @@ type CodexCredentialStatusTarget = {
 // onto the OLD in-flight refresh and writing stale rotated tokens over the freshly
 // connected credential. Concurrent calls for the SAME credential still coalesce,
 // so the one-time refresh token is never double-spent.
-const inflight = new Map<string, Promise<CodexTokenSnapshot>>();
+export type CodexCredentialTokenSnapshot = CodexTokenSnapshot & {
+  /** Exact credential-row version whose bearer is about to reach the provider. */
+  credentialVersion: number;
+};
+
+const inflight = new Map<string, Promise<CodexCredentialTokenSnapshot>>();
 const CODEX_TOKEN_REFRESH_TIMEOUT_MS = 6_000;
 
 export type CodexTokenDeadlineClock = {
@@ -235,17 +240,21 @@ export function buildCodexTokenResolver(
   // clobber the newly-active account. The single-flight map needs zero change.
   credentialId: string,
   deps: CodexAuthDeps,
-): { getToken: () => Promise<CodexTokenSnapshot>; refresh: () => Promise<CodexTokenSnapshot> } {
-  const snapshot = (cred: CodexCredentialForRun): CodexTokenSnapshot => ({
+): {
+  getToken: () => Promise<CodexCredentialTokenSnapshot>;
+  refresh: () => Promise<CodexCredentialTokenSnapshot>;
+} {
+  const snapshot = (cred: CodexCredentialForRun): CodexCredentialTokenSnapshot => ({
     accessToken: cred.tokens.accessToken,
     chatgptAccountId: cred.chatgptAccountId,
     isFedramp: cred.isFedramp,
+    credentialVersion: cred.version,
   });
 
   const performRefresh = async (
     refreshDb: Database,
     cred: CodexCredentialForRun,
-  ): Promise<CodexTokenSnapshot> => {
+  ): Promise<CodexCredentialTokenSnapshot> => {
     try {
       // Bound even injected/custom refresh implementations that ignore abort
       // signals. The provider client has its own AbortController timeout; this
@@ -287,6 +296,7 @@ export function buildCodexTokenResolver(
         accessToken: tokens.access_token,
         chatgptAccountId: cred.chatgptAccountId,
         isFedramp: cred.isFedramp,
+        credentialVersion: cred.version + 1,
       };
     } catch (error) {
       if (error instanceof CodexReloginRequired) {
@@ -305,7 +315,7 @@ export function buildCodexTokenResolver(
 
   // ALL refreshes — whether proactive or a 401 retry — coalesce locally and then
   // serialize globally before any rotating refresh token reaches the provider.
-  const doRefresh = (cred: CodexCredentialForRun): Promise<CodexTokenSnapshot> => {
+  const doRefresh = (cred: CodexCredentialForRun): Promise<CodexCredentialTokenSnapshot> => {
     const key = `${cred.id}:${cred.version}`;
     const existing = inflight.get(key);
     if (existing) {
@@ -346,7 +356,7 @@ export function buildCodexTokenResolver(
     return promise;
   };
 
-  const resolve = async (force: boolean): Promise<CodexTokenSnapshot> => {
+  const resolve = async (force: boolean): Promise<CodexCredentialTokenSnapshot> => {
     const cred = await deps.loadCredential(db, settings, workspaceId, credentialId);
     if (!cred) {
       throw new CodexReloginRequired("No Codex subscription is connected for this workspace.");

package/src/connection-token-resolver.ts

@@ -114,6 +114,8 @@ export type ResolveConnectionCredentialResult =
   | {
       status: "ok";
       headers: Record<string, string>;
+      /** Credential authority is owned by the embedding host, not the native connection store. */
+      authoritySource?: "host";
       /** Present when the credential bundle or embedding host supplied explicit placements. */
       placements?: ConnectionCredentialPlacement[];
       connectionId: string;
@@ -133,6 +135,8 @@ export type ResolveConnectionCredentialResult =
       status: "auth_needed";
       reason: McpCredentialAuthNeededReason;
       providerDomain: string;
+      /** Credential authority is owned by the embedding host, not the native connection store. */
+      authoritySource?: "host";
       provider?: string;
       connectionId?: string;
       scopes?: string[];
@@ -158,6 +162,10 @@ export type ResolveConnectionCredentialInput = {
   /** Defaults to header-only MCP transport. */
   credentialTarget?: "mcp" | "http_api";
   forceRefresh?: boolean;
+  /** Internal lookup mode. Preflight must not refresh credentials or record provider usage. */
+  credentialResolutionMode?: "execution" | "preflight";
+  /** Frozen provider authority generation captured by the calling integration/catalog. */
+  expectedAuthorityGeneration?: number;
   /** Exact immutable accepted-work authority; never credential-bearing. */
   connectionUseAuthority?: unknown;
   /** Exact accepted attempt plus one stable physical-provider request id. */
@@ -270,6 +278,9 @@ export function buildHostConnectionTokenResolver(
       serverId: input.serverId,
       connectionRef: {
         providerDomain: input.connectionRef.providerDomain,
+        ...(input.connectionRef.authoritySource
+          ? { authoritySource: input.connectionRef.authoritySource }
+          : {}),
         ...(input.connectionRef.provider ? { provider: input.connectionRef.provider } : {}),
         ...(input.connectionRef.connectionId
           ? { connectionId: input.connectionRef.connectionId }
@@ -303,6 +314,7 @@ export function buildHostConnectionTokenResolver(
         status: "auth_needed",
         reason: result.reason,
         providerDomain: result.providerDomain,
+        authoritySource: "host",
         ...(result.provider ? { provider: result.provider } : {}),
         ...(result.connectionId ? { connectionId: result.connectionId } : {}),
         ...(result.scopes ? { scopes: [...result.scopes] } : {}),
@@ -339,6 +351,7 @@ export function buildHostConnectionTokenResolver(
     return {
       status: "ok",
       headers,
+      authoritySource: "host",
       ...(explicitPlacements ? { placements: explicitPlacements } : {}),
       connectionId: result.connectionId,
       ...(expiresAt !== undefined ? { expiresAt } : {}),
@@ -712,6 +725,7 @@ export function buildConnectionTokenResolver(
     destinationUrl: string,
     inputCredentialTarget: "mcp" | "http_api",
     connectionUseAttribution?: ConnectionUseAttribution,
+    recordUsage = true,
   ): Promise<ResolveConnectionCredentialResult> => {
     if (cred.status !== "active") {
       return authNeededForStatus(cred, ref);
@@ -753,7 +767,9 @@ export function buildConnectionTokenResolver(
           : {}),
       };
     }
-    await deps.recordUsed(db, cred.workspaceId, cred.id, cred.subjectId);
+    if (recordUsage) {
+      await deps.recordUsed(db, cred.workspaceId, cred.id, cred.subjectId);
+    }
     return {
       status: "ok",
       headers: material.headers,
@@ -830,11 +846,15 @@ export function buildConnectionTokenResolver(
   };
 
   return async (input) => {
+    const credentialResolutionMode = input.credentialResolutionMode ?? "execution";
     let ref = input.connectionRef;
     let subjectId = input.subjectId;
     let credentialWorkspaceId = input.workspaceId;
-    let expectedAuthorityGeneration: number | undefined;
+    let expectedAuthorityGeneration = input.expectedAuthorityGeneration;
     let connectionUseAttribution: ConnectionUseAttribution | undefined;
+    if (ref.authoritySource === "host") {
+      return authNeeded(ref, "unsupported_auth", ref.connectionId);
+    }
     // Repository-scoped provider bindings require a broker that can prove the
     // selected-resource boundary. The generic standalone credential store has
     // no provider-specific containment adapter, so it must fail closed instead
@@ -870,6 +890,16 @@ export function buildConnectionTokenResolver(
           ref.connectionId,
         );
       }
+      if (
+        expectedAuthorityGeneration !== undefined &&
+        authorization.attribution.connectionGeneration !== expectedAuthorityGeneration
+      ) {
+        return authNeeded(
+          ref,
+          authorityReasonForScope(ref.subjectScope === "subject"),
+          ref.connectionId,
+        );
+      }
       connectionUseAttribution = authorization.attribution;
       expectedAuthorityGeneration = authorization.attribution.connectionGeneration;
       const expectedPersonal = authorization.attribution.scope !== "workspace";
@@ -906,6 +936,12 @@ export function buildConnectionTokenResolver(
           authority.connectionId,
         );
       }
+      if (
+        expectedAuthorityGeneration !== undefined &&
+        authority.connectionGeneration !== expectedAuthorityGeneration
+      ) {
+        return authNeeded(ref, authorityReasonForScope(expectedPersonal), authority.connectionId);
+      }
       connectionUseAttribution = authorization.attribution;
       expectedAuthorityGeneration = authority.connectionGeneration;
       // Personal resources are organization-user owned and may originate in a
@@ -950,7 +986,19 @@ export function buildConnectionTokenResolver(
     if (!connectionBindingMatches(cred, ref, input.destinationUrl)) {
       return authNeeded(ref, "missing_connection", cred.id);
     }
-    if (shouldRefresh(cred, input.forceRefresh === true, deps.now())) {
+    const now = deps.now();
+    if (
+      credentialResolutionMode === "preflight" &&
+      cred.kind === "oauth2" &&
+      (input.forceRefresh === true ||
+        (cred.expiresAt !== null && cred.expiresAt.getTime() <= now.getTime()))
+    ) {
+      return authNeeded(ref, "refresh_failed", cred.id);
+    }
+    if (
+      credentialResolutionMode === "execution" &&
+      shouldRefresh(cred, input.forceRefresh === true, now)
+    ) {
       try {
         cred = await refreshSingleFlight(cred, ref);
       } catch (error) {
@@ -998,6 +1046,7 @@ export function buildConnectionTokenResolver(
       input.destinationUrl,
       input.credentialTarget ?? "mcp",
       connectionUseAttribution,
+      credentialResolutionMode === "execution",
     );
   };
 }