@opengeni/db 0.23.0 → 0.26.0

package/drizzle/0165_document_authority_foundation.sql

@@ -0,0 +1,259 @@
+-- deployment-mode: maintenance
+-- Durable organization/workspace/personal authority for Documents and chunks.
+-- Existing workspace-visible rows remain workspace authority. Existing private
+-- rows remain personal authority, anchored to their original workspace and
+-- immutable creating subject. Collections/bases are not authority boundaries.
+
+SET lock_timeout = '5s';
+SET statement_timeout = '10min';
+
+-- Reject a mixed-version cutover before taking table locks. Repeat after the
+-- locks to close the connect-before-lock race. Deployment still owns the
+-- external stop/no-restart protocol after this migration commits.
+DO $document_writer_drain_before_lock$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app')
+    AND EXISTS (
+      SELECT 1
+      FROM pg_stat_activity
+      WHERE datname = current_database()
+        AND usename = 'opengeni_app'
+        AND pid <> pg_backend_pid()
+    )
+  THEN
+    RAISE EXCEPTION 'document authority activation requires all opengeni_app sessions to be stopped'
+      USING ERRCODE = '55000';
+  END IF;
+END
+$document_writer_drain_before_lock$;
+
+-- Both tables already use FORCE RLS. The migration role owns them but may not
+-- be a superuser, so temporarily restore the ordinary owner bypass inside this
+-- transaction. Runtime roles remain subject to RLS throughout the cutover.
+-- The final policy block restores FORCE before this migration can commit.
+ALTER TABLE "documents" NO FORCE ROW LEVEL SECURITY;
+ALTER TABLE "document_chunks" NO FORCE ROW LEVEL SECURITY;
+
+DO $document_writer_drain_after_lock$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app')
+    AND EXISTS (
+      SELECT 1
+      FROM pg_stat_activity
+      WHERE datname = current_database()
+        AND usename = 'opengeni_app'
+        AND pid <> pg_backend_pid()
+    )
+  THEN
+    RAISE EXCEPTION 'document authority activation requires all opengeni_app sessions to be stopped'
+      USING ERRCODE = '55000';
+  END IF;
+END
+$document_writer_drain_after_lock$;
+
+-- This is a protocol cutover, not a replay adapter. Stop the API and every
+-- worker, wait for all document-index Temporal workflows to close, and settle
+-- every queued/indexing document before applying the migration. The row check
+-- is the database-verifiable half of that drain and prevents a legacy
+-- three-field activity payload from being resumed under the new authority
+-- contract.
+DO $document_index_drain$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM "documents" WHERE "status" IN ('queued', 'indexing')
+  ) THEN
+    RAISE EXCEPTION 'migration 0165 requires every queued/indexing document to settle before cutover'
+      USING ERRCODE = '55000',
+        HINT = 'Stop API/workers, close document-index workflows, and retry after documents are ready or failed.';
+  END IF;
+END
+$document_index_drain$;
+
+ALTER TABLE "documents" ADD COLUMN "authority_kind" text;
+ALTER TABLE "documents" ADD COLUMN "authority_workspace_id" uuid;
+ALTER TABLE "documents" ADD COLUMN "authority_subject_id" text;
+
+ALTER TABLE "document_chunks" ADD COLUMN "authority_kind" text;
+ALTER TABLE "document_chunks" ADD COLUMN "authority_workspace_id" uuid;
+ALTER TABLE "document_chunks" ADD COLUMN "authority_subject_id" text;
+
+-- Deterministic legacy backfill. Migration 0126 already guarantees every
+-- private row has a non-empty creator, so this never widens an ambiguous row.
+UPDATE "documents"
+SET "authority_kind" = CASE WHEN "visibility" = 'private' THEN 'personal' ELSE 'workspace' END,
+    "authority_workspace_id" = "workspace_id",
+    "authority_subject_id" = CASE WHEN "visibility" = 'private' THEN "created_by" ELSE NULL END;
+
+-- The document is the canonical parent for every chunk identity field. Repair
+-- any legacy drift before freezing future writes with the trigger below.
+UPDATE "document_chunks" AS chunk
+SET "account_id" = document."account_id",
+    "workspace_id" = document."workspace_id",
+    "base_id" = document."base_id",
+    "file_id" = document."file_id"
+FROM "documents" AS document
+WHERE document."id" = chunk."document_id"
+  AND (
+    chunk."account_id" IS DISTINCT FROM document."account_id"
+    OR chunk."workspace_id" IS DISTINCT FROM document."workspace_id"
+    OR chunk."base_id" IS DISTINCT FROM document."base_id"
+    OR chunk."file_id" IS DISTINCT FROM document."file_id"
+  );
+
+UPDATE "document_chunks" AS chunk
+SET "authority_kind" = document."authority_kind",
+    "authority_workspace_id" = document."authority_workspace_id",
+    "authority_subject_id" = document."authority_subject_id"
+FROM "documents" AS document
+WHERE document."id" = chunk."document_id";
+
+ALTER TABLE "documents" ALTER COLUMN "authority_kind" SET NOT NULL;
+ALTER TABLE "documents" ALTER COLUMN "authority_kind" SET DEFAULT 'workspace';
+ALTER TABLE "document_chunks" ALTER COLUMN "authority_kind" SET NOT NULL;
+ALTER TABLE "document_chunks" ALTER COLUMN "authority_kind" SET DEFAULT 'workspace';
+
+ALTER TABLE "documents"
+  ADD CONSTRAINT "documents_authority_workspace_fk"
+  FOREIGN KEY ("authority_workspace_id", "account_id")
+  REFERENCES "workspaces"("id", "account_id") ON DELETE RESTRICT;
+ALTER TABLE "document_chunks"
+  ADD CONSTRAINT "document_chunks_authority_workspace_fk"
+  FOREIGN KEY ("authority_workspace_id", "account_id")
+  REFERENCES "workspaces"("id", "account_id") ON DELETE RESTRICT;
+
+ALTER TABLE "documents" ADD CONSTRAINT "documents_authority_chk" CHECK (
+  ("authority_kind" = 'organization' AND "authority_workspace_id" IS NULL AND "authority_subject_id" IS NULL)
+  OR ("authority_kind" = 'workspace' AND "authority_workspace_id" = "workspace_id" AND "authority_subject_id" IS NULL)
+  OR (
+    "authority_kind" = 'personal'
+    AND "authority_workspace_id" = "workspace_id"
+    AND NULLIF(btrim("authority_subject_id"), '') IS NOT NULL
+    AND octet_length(convert_to("authority_subject_id", 'UTF8')) <= 1024
+    AND "authority_subject_id" = "created_by"
+  )
+);
+ALTER TABLE "documents" ADD CONSTRAINT "documents_authority_visibility_chk" CHECK (
+  ("authority_kind" = 'personal') = ("visibility" = 'private')
+);
+ALTER TABLE "document_chunks" ADD CONSTRAINT "document_chunks_authority_chk" CHECK (
+  ("authority_kind" = 'organization' AND "authority_workspace_id" IS NULL AND "authority_subject_id" IS NULL)
+  OR ("authority_kind" = 'workspace' AND "authority_workspace_id" = "workspace_id" AND "authority_subject_id" IS NULL)
+  OR (
+    "authority_kind" = 'personal'
+    AND "authority_workspace_id" = "workspace_id"
+    AND NULLIF(btrim("authority_subject_id"), '') IS NOT NULL
+    AND octet_length(convert_to("authority_subject_id", 'UTF8')) <= 1024
+  )
+);
+
+CREATE INDEX "documents_authority_idx" ON "documents" (
+  "account_id", "authority_kind", "authority_workspace_id", "authority_subject_id", "status"
+);
+CREATE INDEX "document_chunks_authority_idx" ON "document_chunks" (
+  "account_id", "authority_kind", "authority_workspace_id", "authority_subject_id"
+);
+
+CREATE OR REPLACE FUNCTION opengeni_private.apply_document_authority()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  IF TG_OP = 'UPDATE' AND (
+    NEW.authority_kind IS DISTINCT FROM OLD.authority_kind
+    OR NEW.authority_workspace_id IS DISTINCT FROM OLD.authority_workspace_id
+    OR NEW.authority_subject_id IS DISTINCT FROM OLD.authority_subject_id
+    OR NEW.created_by IS DISTINCT FROM OLD.created_by
+    OR NEW.visibility IS DISTINCT FROM OLD.visibility
+  ) THEN
+    RAISE EXCEPTION 'document authority is immutable';
+  END IF;
+
+  IF NEW.authority_kind IS NULL OR (
+    NEW.authority_kind = 'workspace'
+    AND NEW.authority_workspace_id IS NULL
+    AND NEW.visibility = 'private'
+  ) THEN
+    NEW.authority_kind := CASE WHEN NEW.visibility = 'private' THEN 'personal' ELSE 'workspace' END;
+  END IF;
+  CASE NEW.authority_kind
+    WHEN 'organization' THEN
+      NEW.authority_workspace_id := NULL;
+      NEW.authority_subject_id := NULL;
+      NEW.visibility := 'workspace';
+    WHEN 'workspace' THEN
+      NEW.authority_workspace_id := NEW.workspace_id;
+      NEW.authority_subject_id := NULL;
+      NEW.visibility := 'workspace';
+    WHEN 'personal' THEN
+      NEW.authority_workspace_id := NEW.workspace_id;
+      NEW.authority_subject_id := coalesce(NULLIF(btrim(NEW.authority_subject_id), ''), NULLIF(btrim(NEW.created_by), ''));
+      NEW.visibility := 'private';
+    ELSE
+      RAISE EXCEPTION 'invalid document authority kind: %', NEW.authority_kind;
+  END CASE;
+  RETURN NEW;
+END
+$$;
+
+CREATE TRIGGER documents_authority_guard
+BEFORE INSERT OR UPDATE ON "documents"
+FOR EACH ROW EXECUTE FUNCTION opengeni_private.apply_document_authority();
+
+CREATE OR REPLACE FUNCTION opengeni_private.apply_document_chunk_authority()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+DECLARE parent "documents"%ROWTYPE;
+BEGIN
+  IF TG_OP = 'UPDATE' AND (
+    NEW.authority_kind IS DISTINCT FROM OLD.authority_kind
+    OR NEW.authority_workspace_id IS DISTINCT FROM OLD.authority_workspace_id
+    OR NEW.authority_subject_id IS DISTINCT FROM OLD.authority_subject_id
+    OR NEW.document_id IS DISTINCT FROM OLD.document_id
+  ) THEN
+    RAISE EXCEPTION 'document chunk authority is immutable';
+  END IF;
+  SELECT * INTO parent FROM "documents" WHERE "id" = NEW.document_id;
+  IF NOT FOUND
+    OR parent.account_id IS DISTINCT FROM NEW.account_id
+    OR parent.workspace_id IS DISTINCT FROM NEW.workspace_id
+    OR parent.base_id IS DISTINCT FROM NEW.base_id
+    OR parent.file_id IS DISTINCT FROM NEW.file_id
+  THEN
+    RAISE EXCEPTION 'document chunk parent identity mismatch';
+  END IF;
+  NEW.authority_kind := parent.authority_kind;
+  NEW.authority_workspace_id := parent.authority_workspace_id;
+  NEW.authority_subject_id := parent.authority_subject_id;
+  RETURN NEW;
+END
+$$;
+
+CREATE TRIGGER document_chunks_authority_guard
+BEFORE INSERT OR UPDATE ON "document_chunks"
+FOR EACH ROW EXECUTE FUNCTION opengeni_private.apply_document_chunk_authority();
+
+DO $$
+DECLARE table_name text;
+BEGIN
+  FOREACH table_name IN ARRAY ARRAY['documents', 'document_chunks'] LOOP
+    IF EXISTS (
+      SELECT 1 FROM pg_policies
+      WHERE schemaname = current_schema() AND tablename = table_name
+        AND policyname = 'workspace_isolation'
+    ) THEN
+      EXECUTE format('DROP POLICY workspace_isolation ON %I', table_name);
+    END IF;
+    EXECUTE format(
+      'CREATE POLICY document_authority_isolation ON %I '
+      || 'USING (opengeni_private.scoped_knowledge_scope_visible('
+      || 'account_id, authority_kind, authority_workspace_id, authority_subject_id)) '
+      || 'WITH CHECK (opengeni_private.scoped_knowledge_scope_visible('
+      || 'account_id, authority_kind, authority_workspace_id, authority_subject_id))',
+      table_name
+    );
+    EXECUTE format('ALTER TABLE %I ENABLE ROW LEVEL SECURITY', table_name);
+    EXECUTE format('ALTER TABLE %I FORCE ROW LEVEL SECURITY', table_name);
+  END LOOP;
+END
+$$;

package/drizzle/0166_connection_disconnect_idempotency.sql

@@ -0,0 +1,49 @@
+-- deployment-mode: rolling
+-- Bind a subject-owned connection disconnect to one caller-frozen generation
+-- and operation key. Exact retries converge only while the produced generation
+-- remains current; reconnecting permanently fences delayed old requests.
+
+CREATE TABLE "connection_disconnect_operations" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "account_id" uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id" uuid NOT NULL REFERENCES "workspaces"("id") ON DELETE CASCADE,
+  "connection_id" uuid NOT NULL REFERENCES "connections"("id") ON DELETE CASCADE,
+  "subject_id" text NOT NULL,
+  "idempotency_key" text NOT NULL,
+  "expected_version" integer NOT NULL,
+  "result_version" integer NOT NULL,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "connection_disconnect_operations_subject_key_uq"
+    UNIQUE ("workspace_id", "subject_id", "idempotency_key"),
+  CONSTRAINT "connection_disconnect_operations_connection_generation_uq"
+    UNIQUE ("workspace_id", "connection_id", "expected_version"),
+  CONSTRAINT "connection_disconnect_operations_identity_check"
+    CHECK (
+      length("subject_id") BETWEEN 1 AND 512
+      AND length("idempotency_key") BETWEEN 1 AND 200
+      AND "idempotency_key" = btrim("idempotency_key")
+      AND "expected_version" > 0
+      AND "result_version" = "expected_version" + 1
+    )
+);
+
+ALTER TABLE "connection_disconnect_operations" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "connection_disconnect_operations" FORCE ROW LEVEL SECURITY;
+CREATE POLICY workspace_subject_isolation ON "connection_disconnect_operations"
+  USING (
+    opengeni_private.workspace_rls_visible("account_id", "workspace_id")
+    AND "subject_id" = nullif(current_setting('opengeni.subject_id', true), '')
+  )
+  WITH CHECK (
+    opengeni_private.workspace_rls_visible("account_id", "workspace_id")
+    AND "subject_id" = nullif(current_setting('opengeni.subject_id', true), '')
+  );
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    REVOKE ALL PRIVILEGES ON TABLE "connection_disconnect_operations" FROM opengeni_app;
+    GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE "connection_disconnect_operations" TO opengeni_app;
+  END IF;
+END
+$$;

package/drizzle/0167_document_index_replay_authority.sql

@@ -0,0 +1,61 @@
+-- deployment-mode: rolling
+-- Resolve only the immutable document authority tuple for historical
+-- three-field document-index Temporal payloads. The ordinary documents policy
+-- remains unchanged: personal content is still invisible without its exact
+-- subject. This SECURITY DEFINER capability returns no content and manually
+-- enforces the caller's already-applied account/workspace RLS context before
+-- reading the exact document identity.
+
+DO $document_index_authority_resolver$
+DECLARE data_schema text := current_schema();
+BEGIN
+  EXECUTE format($ddl$
+    CREATE OR REPLACE FUNCTION opengeni_private.resolve_document_index_authority(
+      p_account_id uuid,
+      p_workspace_id uuid,
+      p_document_id uuid
+    )
+    RETURNS TABLE (
+      authority_kind text,
+      authority_workspace_id uuid,
+      authority_subject_id text
+    )
+    LANGUAGE plpgsql
+    SECURITY DEFINER
+    SET search_path = pg_catalog
+    AS $body$
+    BEGIN
+      IF p_account_id IS DISTINCT FROM opengeni_private.current_account_id()
+        OR p_workspace_id IS DISTINCT FROM opengeni_private.current_workspace_id()
+      THEN
+        RAISE EXCEPTION 'document index authority lookup requires exact account/workspace RLS context'
+          USING ERRCODE = '42501';
+      END IF;
+
+      RETURN QUERY
+      SELECT
+        document.authority_kind,
+        document.authority_workspace_id,
+        document.authority_subject_id
+      FROM %1$I.documents document
+      WHERE document.account_id = p_account_id
+        AND document.workspace_id = p_workspace_id
+        AND document.id = p_document_id
+      LIMIT 1;
+    END;
+    $body$;
+  $ddl$, data_schema);
+END
+$document_index_authority_resolver$;
+
+REVOKE ALL ON FUNCTION opengeni_private.resolve_document_index_authority(uuid, uuid, uuid)
+  FROM PUBLIC;
+
+DO $runtime_grant$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT EXECUTE ON FUNCTION opengeni_private.resolve_document_index_authority(uuid, uuid, uuid)
+      TO opengeni_app;
+  END IF;
+END
+$runtime_grant$;

package/drizzle/0168_workspace_instruction_policy_operation_receipts.sql

@@ -0,0 +1,44 @@
+-- deployment-mode: rolling
+
+-- Immutable revision and activation rows are also the durable receipts for
+-- policy-administration mutations. Legacy rows remain untouched and project
+-- their immutable row id as a compatibility operation identity; new writers
+-- persist stable UUIDs plus a secret-safe fingerprint of the complete canonical
+-- request so only byte-equivalent semantics can replay the original result.
+ALTER TABLE "workspace_instruction_policy_revisions"
+  ADD COLUMN IF NOT EXISTS "operation_id" uuid,
+  ADD COLUMN IF NOT EXISTS "request_fingerprint" text;
+
+ALTER TABLE "workspace_instruction_policy_revisions"
+  ADD CONSTRAINT "workspace_instruction_policy_revisions_operation_receipt_chk"
+  CHECK (
+    ("operation_id" IS NULL AND "request_fingerprint" IS NULL)
+    OR (
+      "operation_id" IS NOT NULL
+      AND "request_fingerprint" ~ '^[0-9a-f]{64}$'
+    )
+  );
+
+CREATE UNIQUE INDEX IF NOT EXISTS
+  "workspace_instruction_policy_revisions_workspace_operation_uq"
+  ON "workspace_instruction_policy_revisions" ("workspace_id", "operation_id")
+  WHERE "operation_id" IS NOT NULL;
+
+ALTER TABLE "workspace_instruction_policy_activation_events"
+  ADD COLUMN IF NOT EXISTS "operation_id" uuid,
+  ADD COLUMN IF NOT EXISTS "request_fingerprint" text;
+
+ALTER TABLE "workspace_instruction_policy_activation_events"
+  ADD CONSTRAINT "workspace_instruction_policy_events_operation_receipt_chk"
+  CHECK (
+    ("operation_id" IS NULL AND "request_fingerprint" IS NULL)
+    OR (
+      "operation_id" IS NOT NULL
+      AND "request_fingerprint" ~ '^[0-9a-f]{64}$'
+    )
+  );
+
+CREATE UNIQUE INDEX IF NOT EXISTS
+  "workspace_instruction_policy_events_workspace_operation_uq"
+  ON "workspace_instruction_policy_activation_events" ("workspace_id", "operation_id")
+  WHERE "operation_id" IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/db",
-  "version": "0.23.0",
+  "version": "0.26.0",
   "description": "OpenGeni persistence: Drizzle schema, RLS-scoped query layer, the SQL migration runner, and role provisioning.",
   "license": "Apache-2.0",
   "repository": {
@@ -51,8 +51,8 @@
   },
   "dependencies": {
     "@opengeni/codex": "^0.2.10",
-    "@opengeni/config": "^0.10.3",
-    "@opengeni/contracts": "^0.32.0",
+    "@opengeni/config": "^0.10.6",
+    "@opengeni/contracts": "^0.35.0",
     "@opengeni/network": "^0.1.1",
     "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.7"

package/src/connection-token-resolver.ts

@@ -34,7 +34,14 @@ import {
 } from "./index";
 
 export type ResolveConnectionCredentialResult =
-  | { status: "ok"; headers: Record<string, string>; connectionId: string; expiresAt?: Date | null }
+  | {
+      status: "ok";
+      headers: Record<string, string>;
+      connectionId: string;
+      /** Exact durable version when the credential came from the local connection store. */
+      connectionVersion?: number;
+      expiresAt?: Date | null;
+    }
   | {
       status: "auth_needed";
       reason: McpCredentialAuthNeededReason;
@@ -337,6 +344,29 @@ export type ConnectionBrokerDeps = {
   now: () => Date;
 };
 
+export type PermanentConnectionRefreshFailure = {
+  workspaceId: string;
+  connectionId: string;
+  connectionVersion: number;
+  subjectId: string | null;
+  providerDomain: string;
+  httpStatus: number;
+  oauthErrorCode: string | null;
+};
+
+export type ConnectionTokenResolverOptions = {
+  /** Provider-aware transport override used by local/integration adapters. */
+  refreshTransport?: RefreshTransportOptions;
+  /**
+   * Optional provider adapter for an atomic, metadata-aware permanent refresh
+   * transition. Returning true means the adapter owned the transition (even if
+   * its CAS lost to newer truth); false falls back to generic needs_reauth.
+   */
+  transitionPermanentRefreshFailure?: (
+    failure: PermanentConnectionRefreshFailure,
+  ) => Promise<boolean>;
+};
+
 export type RefreshTransportOptions = {
   fetchImpl?: FetchLike;
   dnsLookup?: DnsLookup;
@@ -361,6 +391,7 @@ export function buildConnectionTokenResolver(
   db: Database,
   settings: Settings,
   deps: ConnectionBrokerDeps = defaultDeps,
+  options: ConnectionTokenResolverOptions = {},
 ): (input: ResolveConnectionCredentialInput) => Promise<ResolveConnectionCredentialResult> {
   type CredentialLookupInput = Pick<
     ResolveConnectionCredentialInput,
@@ -439,6 +470,7 @@ export function buildConnectionTokenResolver(
       status: "ok",
       headers,
       connectionId: cred.id,
+      connectionVersion: cred.version,
       expiresAt: cred.expiresAt,
     };
   };
@@ -451,7 +483,7 @@ export function buildConnectionTokenResolver(
     if (!key) {
       throw new Error("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is not configured");
     }
-    const refreshed = await deps.refresh(cred, ref, settings);
+    const refreshed = await deps.refresh(cred, ref, settings, options.refreshTransport);
     const refreshRecord: Parameters<typeof recordConnectionTokenRefresh>[1] = {
       id: cred.id,
       version: cred.version,
@@ -541,19 +573,31 @@ export function buildConnectionTokenResolver(
         // Only a rejected grant may poison the connection; transient failures
         // (network errors, AS 5xx) leave it active so the next resolve retries.
         if (isPermanentRefreshError(error)) {
-          await deps
-            .setStatus(
-              db,
-              input.workspaceId,
-              "needs_reauth",
-              error instanceof Error ? error.message : String(error),
-              {
+          let handled = false;
+          if (options.transitionPermanentRefreshFailure) {
+            try {
+              handled = await options.transitionPermanentRefreshFailure({
+                workspaceId: cred.workspaceId,
+                connectionId: cred.id,
+                connectionVersion: cred.version,
+                subjectId: cred.subjectId,
+                providerDomain: cred.providerDomain,
+                httpStatus: error.httpStatus,
+                oauthErrorCode: error.oauthErrorCode,
+              });
+            } catch {
+              handled = false;
+            }
+          }
+          if (!handled) {
+            await deps
+              .setStatus(db, input.workspaceId, "needs_reauth", error.message, {
                 id: cred.id,
                 version: cred.version,
                 subjectId: cred.subjectId,
-              },
-            )
-            .catch(() => undefined);
+              })
+              .catch(() => undefined);
+          }
         }
         return authNeeded(ref, "refresh_failed", cred.id);
       }
@@ -629,18 +673,20 @@ function canonicalResource(value: string): string {
 
 export class ConnectionRefreshHttpError extends Error {
   readonly httpStatus: number;
+  readonly oauthErrorCode: string | null;
 
-  constructor(httpStatus: number) {
+  constructor(httpStatus: number, oauthErrorCode: string | null = null) {
     super(`connection refresh failed with HTTP ${httpStatus}`);
     this.name = "ConnectionRefreshHttpError";
     this.httpStatus = httpStatus;
+    this.oauthErrorCode = oauthErrorCode;
   }
 }
 
 // The token endpoint rejecting the grant itself means re-auth is the only way
 // forward. 429 (throttling) and 408 are transient despite being 4xx; network
 // failures and AS 5xx are likewise retryable.
-function isPermanentRefreshError(error: unknown): boolean {
+function isPermanentRefreshError(error: unknown): error is ConnectionRefreshHttpError {
   return (
     error instanceof ConnectionRefreshHttpError &&
     error.httpStatus >= 400 &&
@@ -817,8 +863,10 @@ export async function refreshOAuthConnectionCredential(
     throw new ConnectionRefreshHttpError(response.status);
   }
   if (!response.ok) {
-    await cancelResponseBody(response);
-    throw new ConnectionRefreshHttpError(response.status);
+    throw new ConnectionRefreshHttpError(
+      response.status,
+      await readOAuthRefreshErrorCode(response),
+    );
   }
   const payload = await readResponseJsonBounded<Record<string, unknown>>(
     response,
@@ -853,6 +901,21 @@ export async function refreshOAuthConnectionCredential(
   };
 }
 
+async function readOAuthRefreshErrorCode(response: Response): Promise<string | null> {
+  try {
+    const payload = await readResponseJsonBounded<Record<string, unknown>>(
+      response,
+      OAUTH_MAX_RESPONSE_BYTES,
+      "OAuth refresh error response",
+    );
+    const code = stringValue(payload.error);
+    return code && /^[a-z0-9_.-]{1,64}$/i.test(code) ? code : null;
+  } catch {
+    await cancelResponseBody(response);
+    return null;
+  }
+}
+
 function expiresAtFromTokenResponse(
   payload: Record<string, unknown>,
   fallback: Date | null,