@desplega.ai/agent-swarm 1.119.6 → 1.121.0

package/src/be/db-queries/oauth.ts

@@ -1,107 +1,706 @@
 import type { OAuthApp, OAuthTokens } from "../../tracker/types";
+import { decryptSecret, encryptSecret, getEncryptionKey } from "../crypto";
 import { normalizeDateRequired } from "../date-utils";
 import { getDb } from "../db";
 
-// ── OAuth Apps ──
+type OAuthAppRow = Omit<
+  OAuthApp,
+  "clientSecretEncrypted" | "requiresRefreshTokenRotation" | "scopes"
+> & {
+  clientSecret: string | null;
+  clientSecretEncrypted: number;
+  requiresRefreshTokenRotation: number;
+  scopes: string;
+};
+
+export type OAuthAuthorizationStatus = "active" | "refresh-failed" | "expired" | "revoked";
+
+type OAuthAuthorizationRow = {
+  id: string;
+  appId: string;
+  label: string;
+  userId: string | null;
+  accountEmail: string | null;
+  identityJson: string | null;
+  accessToken: string;
+  refreshToken: string | null;
+  tokenType: string;
+  expiresAt: string | null;
+  scope: string | null;
+  tokensEncrypted: number;
+  tokenVersion: number;
+  status: OAuthAuthorizationStatus;
+  lastErrorMessage: string | null;
+  lastRefreshedAt: string | null;
+  connectedByUserId: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type OAuthAuthorization = Omit<OAuthAuthorizationRow, "tokensEncrypted"> & {
+  tokensEncrypted: boolean;
+};
+
+function parseScopeList(value: string): string[] {
+  try {
+    const parsed = JSON.parse(value);
+    if (Array.isArray(parsed)) {
+      return parsed.filter((item): item is string => typeof item === "string");
+    }
+  } catch {
+    // Legacy callers still pass comma-delimited scope strings.
+  }
+  return value
+    .split(",")
+    .map((scope) => scope.trim())
+    .filter(Boolean);
+}
+
+function storeScopeList(value: string | string[]): string {
+  return JSON.stringify(Array.isArray(value) ? value : parseScopeList(value));
+}
+
+function parseObject(value: string | null | undefined): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(value || "{}");
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function storageMetadata(metadata: string): {
+  metadata: string;
+  extraParamsJson: string | null;
+  tokenAuthStyle: "body" | "basic";
+  tokenBodyFormat: "form" | "json";
+  revocationUrl: string | null;
+} {
+  const parsed = parseObject(metadata);
+  const extraParams =
+    parsed.extraParams &&
+    typeof parsed.extraParams === "object" &&
+    !Array.isArray(parsed.extraParams)
+      ? parsed.extraParams
+      : null;
+  const tokenAuthStyle = parsed.tokenAuthStyle === "basic" ? "basic" : "body";
+  const tokenBodyFormat = parsed.tokenBodyFormat === "json" ? "json" : "form";
+  const revocationUrl = typeof parsed.revocationUrl === "string" ? parsed.revocationUrl : null;
+  const hasLiftedFields = [
+    "extraParams",
+    "tokenAuthStyle",
+    "tokenBodyFormat",
+    "revocationUrl",
+  ].some((key) => Object.hasOwn(parsed, key));
+  if (hasLiftedFields) {
+    delete parsed.extraParams;
+    delete parsed.tokenAuthStyle;
+    delete parsed.tokenBodyFormat;
+    delete parsed.revocationUrl;
+  }
+  return {
+    metadata: hasLiftedFields ? JSON.stringify(parsed) : metadata,
+    extraParamsJson: extraParams ? JSON.stringify(extraParams) : null,
+    tokenAuthStyle,
+    tokenBodyFormat,
+    revocationUrl,
+  };
+}
 
-function normalizeOAuthApp(row: OAuthApp): OAuthApp {
+function normalizeOAuthApp(row: OAuthAppRow): OAuthApp {
+  const encrypted = row.clientSecretEncrypted === 1;
   return {
     ...row,
+    clientSecret:
+      row.clientSecret == null
+        ? ""
+        : encrypted
+          ? decryptSecret(row.clientSecret, getEncryptionKey())
+          : row.clientSecret,
+    clientSecretEncrypted: encrypted,
+    scopes: parseScopeList(row.scopes).join(","),
+    requiresRefreshTokenRotation: row.requiresRefreshTokenRotation === 1,
     createdAt: normalizeDateRequired(row.createdAt),
     updatedAt: normalizeDateRequired(row.updatedAt),
   };
 }
 
-function normalizeOAuthTokens(row: OAuthTokens): OAuthTokens {
+function normalizeAuthorization(row: OAuthAuthorizationRow): OAuthAuthorization {
+  const encrypted = row.tokensEncrypted === 1;
+  const key = encrypted ? getEncryptionKey() : null;
   return {
     ...row,
+    accessToken: key ? decryptSecret(row.accessToken, key) : row.accessToken,
+    refreshToken:
+      row.refreshToken == null
+        ? null
+        : key
+          ? decryptSecret(row.refreshToken, key)
+          : row.refreshToken,
+    tokensEncrypted: encrypted,
     createdAt: normalizeDateRequired(row.createdAt),
     updatedAt: normalizeDateRequired(row.updatedAt),
   };
 }
 
+function rawOAuthAppByProvider(provider: string): OAuthAppRow | null {
+  return getDb()
+    .query(
+      `SELECT * FROM oauth_apps
+       WHERE provider = ? AND mcpServerId IS NULL
+       ORDER BY createdAt ASC, id ASC
+       LIMIT 1`,
+    )
+    .get(provider) as OAuthAppRow | null;
+}
+
+/** Exact (non-MCP) app lookup by id — used to target a specific row when the
+ * provider is ambiguous (N apps per provider are allowed). */
+function rawOAuthAppById(id: string): OAuthAppRow | null {
+  return getDb()
+    .query("SELECT * FROM oauth_apps WHERE id = ? AND mcpServerId IS NULL")
+    .get(id) as OAuthAppRow | null;
+}
+
+function rawDefaultAuthorizationForApp(appId: string): OAuthAuthorizationRow | null {
+  return getDb()
+    .query("SELECT * FROM oauth_authorizations WHERE appId = ? AND label = 'default'")
+    .get(appId) as OAuthAuthorizationRow | null;
+}
+
+function rawDefaultAuthorizationForProvider(provider: string): OAuthAuthorizationRow | null {
+  return getDb()
+    .query(
+      `SELECT z.*
+       FROM oauth_authorizations z
+       JOIN oauth_apps a ON a.id = z.appId
+       WHERE a.provider = ? AND a.mcpServerId IS NULL AND z.label = 'default'
+       ORDER BY a.createdAt ASC, a.id ASC
+       LIMIT 1`,
+    )
+    .get(provider) as OAuthAuthorizationRow | null;
+}
+
+export function getDefaultAuthorizationIdForProvider(provider: string): string | null {
+  return rawDefaultAuthorizationForProvider(provider)?.id ?? null;
+}
+
+// ── OAuth Apps ──
+
 export function getOAuthApp(provider: string): OAuthApp | null {
-  const row = getDb()
-    .query("SELECT * FROM oauth_apps WHERE provider = ?")
-    .get(provider) as OAuthApp | null;
+  const row = rawOAuthAppByProvider(provider);
+  return row ? normalizeOAuthApp(row) : null;
+}
+
+export function getOAuthAppById(id: string): OAuthApp | null {
+  const row = getDb().query("SELECT * FROM oauth_apps WHERE id = ?").get(id) as OAuthAppRow | null;
   return row ? normalizeOAuthApp(row) : null;
 }
 
-export function upsertOAuthApp(
+/** Resolve the (non-MCP) app id for a provider slug, or null if none. */
+export function getOAuthAppIdByProvider(provider: string): string | null {
+  return rawOAuthAppByProvider(provider)?.id ?? null;
+}
+
+/** Shared write payload for the OAuth-app create / update / provider-upsert
+ * paths. The row-resolution strategy is chosen by the calling function — never
+ * by this payload — so `id` is intentionally absent here. */
+type OAuthAppWriteData = {
+  clientId: string;
+  clientSecret: string;
+  authorizeUrl: string;
+  tokenUrl: string;
+  redirectUri: string;
+  scopes: string;
+  metadata?: string;
+  displayName?: string | null;
+  revocationUrl?: string | null;
+  userinfoUrl?: string | null;
+  scopeSeparator?: string;
+  tokenAuthStyle?: "body" | "basic";
+  tokenBodyFormat?: "form" | "json";
+  requiresRefreshTokenRotation?: boolean;
+  extraParams?: Record<string, string> | null;
+  source?: "manual" | "dcr" | "curated-prefill";
+};
+
+/** Insert a new row (when `existing` is null) or update the given row in place.
+ * Returns the row id either way. Callers pick the row-resolution strategy up
+ * front — this helper never resolves by provider on its own. */
+function writeOAuthApp(
+  existing: OAuthAppRow | null,
   provider: string,
-  data: {
-    clientId: string;
-    clientSecret: string;
-    authorizeUrl: string;
-    tokenUrl: string;
-    redirectUri: string;
-    scopes: string;
-    metadata?: string;
-  },
-): void {
-  // metadata is treated as a runtime-owned column (cloudId, webhookIds, etc.
-  // are written by OAuth callback + webhook-register flows). On INSERT we
-  // seed it with whatever the caller passed (or "{}"); on UPDATE we ONLY
-  // overwrite when the caller explicitly provided one — otherwise the
-  // existing value is preserved across server restarts.
+  data: OAuthAppWriteData,
+): string {
   const metadataProvided = data.metadata !== undefined;
-  const sql = metadataProvided
-    ? `INSERT INTO oauth_apps (provider, clientId, clientSecret, authorizeUrl, tokenUrl, redirectUri, scopes, metadata)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(provider) DO UPDATE SET
-         clientId = excluded.clientId,
-         clientSecret = excluded.clientSecret,
-         authorizeUrl = excluded.authorizeUrl,
-         tokenUrl = excluded.tokenUrl,
-         redirectUri = excluded.redirectUri,
-         scopes = excluded.scopes,
-         metadata = excluded.metadata,
-         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`
-    : `INSERT INTO oauth_apps (provider, clientId, clientSecret, authorizeUrl, tokenUrl, redirectUri, scopes, metadata)
-       VALUES (?, ?, ?, ?, ?, ?, ?, '{}')
-       ON CONFLICT(provider) DO UPDATE SET
-         clientId = excluded.clientId,
-         clientSecret = excluded.clientSecret,
-         authorizeUrl = excluded.authorizeUrl,
-         tokenUrl = excluded.tokenUrl,
-         redirectUri = excluded.redirectUri,
-         scopes = excluded.scopes,
-         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
-  if (metadataProvided) {
+  const lifted = metadataProvided ? storageMetadata(data.metadata as string) : null;
+  const encryptedSecret = encryptSecret(data.clientSecret, getEncryptionKey());
+  const scopeSeparator =
+    data.scopeSeparator ?? existing?.scopeSeparator ?? (provider === "linear" ? "," : " ");
+  const rotation =
+    data.requiresRefreshTokenRotation ??
+    (existing ? existing.requiresRefreshTokenRotation === 1 : provider === "jira");
+  const tokenAuthStyle =
+    data.tokenAuthStyle ?? lifted?.tokenAuthStyle ?? existing?.tokenAuthStyle ?? "body";
+  const tokenBodyFormat =
+    data.tokenBodyFormat ?? lifted?.tokenBodyFormat ?? existing?.tokenBodyFormat ?? "form";
+  const extraParamsJson =
+    data.extraParams !== undefined
+      ? data.extraParams == null
+        ? null
+        : JSON.stringify(data.extraParams)
+      : lifted
+        ? lifted.extraParamsJson
+        : (existing?.extraParamsJson ?? null);
+  const revocationUrl =
+    data.revocationUrl !== undefined
+      ? data.revocationUrl
+      : lifted
+        ? lifted.revocationUrl
+        : (existing?.revocationUrl ?? null);
+
+  if (existing) {
     getDb()
-      .query(sql)
+      .query(
+        `UPDATE oauth_apps SET
+           displayName = ?, clientId = ?, clientSecret = ?, clientSecretEncrypted = 1,
+           authorizeUrl = ?, tokenUrl = ?, revocationUrl = ?, userinfoUrl = ?,
+           redirectUri = ?, scopes = ?, scopeSeparator = ?, tokenAuthStyle = ?,
+           tokenBodyFormat = ?, requiresRefreshTokenRotation = ?, extraParamsJson = ?,
+           source = ?, metadata = ?, updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+         WHERE id = ?`,
+      )
       .run(
-        provider,
+        data.displayName !== undefined ? data.displayName : existing.displayName,
         data.clientId,
-        data.clientSecret,
+        encryptedSecret,
         data.authorizeUrl,
         data.tokenUrl,
+        revocationUrl,
+        data.userinfoUrl !== undefined ? data.userinfoUrl : existing.userinfoUrl,
         data.redirectUri,
-        data.scopes,
-        data.metadata as string,
+        storeScopeList(data.scopes),
+        scopeSeparator,
+        tokenAuthStyle,
+        tokenBodyFormat,
+        rotation ? 1 : 0,
+        extraParamsJson,
+        data.source ?? existing.source,
+        lifted?.metadata ?? existing.metadata,
+        existing.id,
       );
-  } else {
+    return existing.id;
+  }
+
+  const inserted = getDb()
+    .query(
+      `INSERT INTO oauth_apps (
+         provider, displayName, clientId, clientSecret, clientSecretEncrypted,
+         authorizeUrl, tokenUrl, revocationUrl, userinfoUrl, redirectUri, scopes,
+         scopeSeparator, tokenAuthStyle, tokenBodyFormat,
+         requiresRefreshTokenRotation, extraParamsJson, source, metadata
+       ) VALUES (?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING id`,
+    )
+    .get(
+      provider,
+      data.displayName ?? null,
+      data.clientId,
+      encryptedSecret,
+      data.authorizeUrl,
+      data.tokenUrl,
+      revocationUrl,
+      data.userinfoUrl ?? null,
+      data.redirectUri,
+      storeScopeList(data.scopes),
+      scopeSeparator,
+      tokenAuthStyle,
+      tokenBodyFormat,
+      rotation ? 1 : 0,
+      extraParamsJson,
+      data.source ?? "manual",
+      lifted?.metadata ?? "{}",
+    ) as { id: string };
+  return inserted.id;
+}
+
+/** Create a brand-new OAuth app row and return its id. ALWAYS inserts — it never
+ * resolves by provider, so a second app for the same provider can never clobber
+ * the first. User-facing create paths (HTTP `POST /api/oauth-apps` without an
+ * id, the MCP `oauth-app-upsert` action) MUST use this. */
+export function createOAuthApp(provider: string, data: OAuthAppWriteData): string {
+  return writeOAuthApp(null, provider, data);
+}
+
+/** Update exactly one existing (non-MCP) app by id. Throws when the id is
+ * unknown or refers to an MCP-managed app. Provider is immutable on edit. */
+export function updateOAuthAppById(id: string, data: OAuthAppWriteData): void {
+  const existing = rawOAuthAppById(id);
+  if (!existing) {
+    throw new Error(`OAuth app ${id} not found.`);
+  }
+  writeOAuthApp(existing, existing.provider, data);
+}
+
+/** Provider-keyed upsert — reserved for BOOT reconciliation (initLinear /
+ * initJira) and test seeding. Updates the oldest row for the provider, or
+ * inserts when none exists. Do NOT use for user-facing create/edit: with N apps
+ * per provider this silently clobbers a sibling row — the create path must use
+ * createOAuthApp and the edit path updateOAuthAppById. */
+export function upsertOAuthApp(provider: string, data: OAuthAppWriteData): void {
+  writeOAuthApp(rawOAuthAppByProvider(provider), provider, data);
+}
+
+// ── OAuth Authorizations ──
+
+export function listAuthorizationsForApp(appId: string): OAuthAuthorization[] {
+  const rows = getDb()
+    .query("SELECT * FROM oauth_authorizations WHERE appId = ? ORDER BY createdAt ASC, id ASC")
+    .all(appId) as OAuthAuthorizationRow[];
+  return rows.map(normalizeAuthorization);
+}
+
+export function getAuthorizationById(id: string): OAuthAuthorization | null {
+  const row = getDb()
+    .query("SELECT * FROM oauth_authorizations WHERE id = ?")
+    .get(id) as OAuthAuthorizationRow | null;
+  return row ? normalizeAuthorization(row) : null;
+}
+
+export function upsertAuthorization(data: {
+  id?: string;
+  appId: string;
+  label?: string;
+  userId?: string | null;
+  accountEmail?: string | null;
+  identityJson?: string | null;
+  accessToken: string;
+  refreshToken?: string | null;
+  tokenType?: string;
+  expiresAt?: string | null;
+  scope?: string | null;
+  status?: OAuthAuthorizationStatus;
+  lastErrorMessage?: string | null;
+  lastRefreshedAt?: string | null;
+  connectedByUserId?: string | null;
+}): OAuthAuthorization {
+  const label = data.label ?? "default";
+  const existing = data.id
+    ? getAuthorizationById(data.id)
+    : listAuthorizationsForApp(data.appId).find((row) => row.label === label);
+  const key = getEncryptionKey();
+  const accessToken = encryptSecret(data.accessToken, key);
+  const refreshToken =
+    data.refreshToken === undefined
+      ? undefined
+      : data.refreshToken == null
+        ? null
+        : encryptSecret(data.refreshToken, key);
+
+  if (existing) {
     getDb()
-      .query(sql)
+      .query(
+        `UPDATE oauth_authorizations SET
+           userId = ?, accountEmail = ?, identityJson = ?, accessToken = ?,
+           refreshToken = ?, tokenType = ?, expiresAt = ?, scope = ?,
+           tokensEncrypted = 1, tokenVersion = tokenVersion + 1, status = ?,
+           lastErrorMessage = ?, lastRefreshedAt = ?, connectedByUserId = ?,
+           updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+         WHERE id = ?`,
+      )
       .run(
-        provider,
-        data.clientId,
-        data.clientSecret,
-        data.authorizeUrl,
-        data.tokenUrl,
-        data.redirectUri,
-        data.scopes,
+        data.userId !== undefined ? data.userId : existing.userId,
+        data.accountEmail !== undefined ? data.accountEmail : existing.accountEmail,
+        data.identityJson !== undefined ? data.identityJson : existing.identityJson,
+        accessToken,
+        refreshToken === undefined
+          ? existing.refreshToken == null
+            ? null
+            : encryptSecret(existing.refreshToken, key)
+          : refreshToken,
+        data.tokenType ?? existing.tokenType,
+        data.expiresAt !== undefined ? data.expiresAt : existing.expiresAt,
+        data.scope !== undefined ? data.scope : existing.scope,
+        data.status ?? existing.status,
+        data.lastErrorMessage !== undefined ? data.lastErrorMessage : existing.lastErrorMessage,
+        data.lastRefreshedAt !== undefined ? data.lastRefreshedAt : existing.lastRefreshedAt,
+        data.connectedByUserId !== undefined ? data.connectedByUserId : existing.connectedByUserId,
+        existing.id,
       );
+    return getAuthorizationById(existing.id) as OAuthAuthorization;
   }
+
+  const id = data.id ?? crypto.randomUUID();
+  getDb()
+    .query(
+      `INSERT INTO oauth_authorizations (
+         id, appId, label, userId, accountEmail, identityJson,
+         accessToken, refreshToken, tokenType, expiresAt, scope,
+         tokensEncrypted, tokenVersion, status, lastErrorMessage,
+         lastRefreshedAt, connectedByUserId
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 1, ?, ?, ?, ?)`,
+    )
+    .run(
+      id,
+      data.appId,
+      label,
+      data.userId ?? null,
+      data.accountEmail ?? null,
+      data.identityJson ?? null,
+      accessToken,
+      refreshToken ?? null,
+      data.tokenType ?? "Bearer",
+      data.expiresAt ?? null,
+      data.scope ?? null,
+      data.status ?? "active",
+      data.lastErrorMessage ?? null,
+      data.lastRefreshedAt ?? null,
+      data.connectedByUserId ?? null,
+    );
+  return getAuthorizationById(id) as OAuthAuthorization;
 }
 
-// ── OAuth Tokens ──
+export function updateAuthorizationTokens(
+  id: string,
+  data: {
+    accessToken: string;
+    refreshToken?: string | null;
+    expiresAt?: string | null;
+    scope?: string | null;
+    expectedTokenVersion?: number;
+  },
+): OAuthAuthorization | null {
+  const existing = getAuthorizationById(id);
+  if (!existing) return null;
+  const expectedVersion = data.expectedTokenVersion ?? existing.tokenVersion;
+  const key = getEncryptionKey();
+  const encryptedRefresh =
+    data.refreshToken === undefined
+      ? existing.refreshToken == null
+        ? null
+        : encryptSecret(existing.refreshToken, key)
+      : data.refreshToken == null
+        ? null
+        : encryptSecret(data.refreshToken, key);
+  const result = getDb()
+    .query(
+      `UPDATE oauth_authorizations SET
+         accessToken = ?, refreshToken = ?, expiresAt = ?, scope = ?,
+         tokensEncrypted = 1, tokenVersion = tokenVersion + 1,
+         status = 'active', lastErrorMessage = NULL,
+         lastRefreshedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+       WHERE id = ? AND tokenVersion = ?`,
+    )
+    .run(
+      encryptSecret(data.accessToken, key),
+      encryptedRefresh,
+      data.expiresAt !== undefined ? data.expiresAt : existing.expiresAt,
+      data.scope !== undefined ? data.scope : existing.scope,
+      id,
+      expectedVersion,
+    );
+  return result.changes === 1 ? getAuthorizationById(id) : null;
+}
+
+/**
+ * Persist best-effort account identity (email + raw identity claims) captured
+ * after a successful token exchange. Never touches token material or
+ * tokenVersion — display-only metadata.
+ */
+export function updateAuthorizationIdentity(
+  id: string,
+  data: { accountEmail?: string | null; identityJson?: string | null },
+): void {
+  getDb()
+    .query(
+      `UPDATE oauth_authorizations SET
+         accountEmail = ?, identityJson = ?,
+         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+       WHERE id = ?`,
+    )
+    .run(data.accountEmail ?? null, data.identityJson ?? null, id);
+}
+
+/**
+ * Hard-delete a single authorization row (used by the multi-authorization
+ * DELETE endpoint after best-effort remote revocation). Bindings referencing
+ * it are detached via `ON DELETE SET NULL`.
+ */
+export function deleteAuthorizationById(id: string): boolean {
+  const result = getDb().query("DELETE FROM oauth_authorizations WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+
+/**
+ * Delete every authorization owned by a SPECIFIC app id. Scoped by app id (not
+ * provider) so deleting one of several same-provider apps never touches a
+ * sibling app's authorizations. Bindings referencing the rows detach via
+ * `ON DELETE SET NULL`.
+ */
+export function deleteAuthorizationsForApp(appId: string): number {
+  return getDb().query("DELETE FROM oauth_authorizations WHERE appId = ?").run(appId).changes;
+}
+
+// ── OAuth pending (DB-backed PKCE state for generic/tracker flows) ──
+
+/** Pending PKCE sessions are valid for 10 minutes (matches the GC window). */
+export const OAUTH_PENDING_TTL_MS = 10 * 60 * 1000;
+
+export type OAuthPendingFlow = "generic" | "tracker";
+
+export interface OAuthPendingRecord {
+  state: string;
+  appId: string;
+  label: string;
+  flow: OAuthPendingFlow;
+  /** Decrypted PKCE code verifier. */
+  codeVerifier: string;
+  nonce: string | null;
+  redirectUri: string;
+  finalRedirect: string | null;
+  userId: string | null;
+  contextJson: string;
+  createdAt: string;
+}
+
+type OAuthPendingRow = {
+  state: string;
+  appId: string;
+  label: string;
+  flow: OAuthPendingFlow;
+  codeVerifier: string;
+  nonce: string | null;
+  redirectUri: string;
+  finalRedirect: string | null;
+  userId: string | null;
+  contextJson: string;
+  createdAt: string;
+};
+
+/** Persist a pending PKCE session for a generic/tracker OAuth flow. */
+export function createOAuthPending(input: {
+  state: string;
+  appId: string;
+  label?: string;
+  flow?: OAuthPendingFlow;
+  /** Plaintext PKCE code verifier — encrypted at rest. */
+  codeVerifier: string;
+  nonce?: string | null;
+  redirectUri: string;
+  finalRedirect?: string | null;
+  userId?: string | null;
+  contextJson?: string;
+}): void {
+  getDb()
+    .query(
+      `INSERT INTO oauth_pending (
+         state, appId, label, flow, codeVerifier, nonce,
+         redirectUri, finalRedirect, userId, contextJson
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      input.state,
+      input.appId,
+      input.label ?? "default",
+      input.flow ?? "generic",
+      encryptSecret(input.codeVerifier, getEncryptionKey()),
+      input.nonce ?? null,
+      input.redirectUri,
+      input.finalRedirect ?? null,
+      input.userId ?? null,
+      input.contextJson ?? "{}",
+    );
+}
+
+/**
+ * Single-use consume of a generic/tracker pending row by `state`. Returns null
+ * for unknown states and for `mcp`-flow rows (those are owned by the MCP
+ * adapter), leaving the row untouched so the caller can fall through.
+ *
+ * Enforces the 10-minute TTL at consume time: an expired row is deleted and
+ * treated as invalid, so a stalled/failed GC timer cannot widen the validity
+ * window.
+ */
+export function consumeOAuthPending(state: string): OAuthPendingRecord | null {
+  return getDb().transaction(() => {
+    const row = getDb()
+      .query(
+        `SELECT state, appId, label, flow, codeVerifier, nonce, redirectUri,
+                finalRedirect, userId, contextJson, createdAt
+         FROM oauth_pending
+         WHERE state = ? AND flow IN ('generic', 'tracker')`,
+      )
+      .get(state) as OAuthPendingRow | null;
+    if (!row) return null;
+    // Single-use: always delete, whether valid or expired.
+    getDb().query("DELETE FROM oauth_pending WHERE state = ?").run(state);
+    const createdAt = normalizeDateRequired(row.createdAt);
+    const createdMs = new Date(createdAt).getTime();
+    if (Number.isNaN(createdMs) || Date.now() - createdMs > OAUTH_PENDING_TTL_MS) {
+      return null;
+    }
+    return {
+      ...row,
+      codeVerifier: decryptSecret(row.codeVerifier, getEncryptionKey()),
+      createdAt,
+    };
+  })();
+}
+
+/** GC expired generic/tracker pending rows. MCP rows are GC'd separately. */
+export function gcOAuthPending(olderThanMs = 10 * 60 * 1000): number {
+  const cutoff = new Date(Date.now() - olderThanMs).toISOString();
+  return getDb()
+    .query("DELETE FROM oauth_pending WHERE flow IN ('generic', 'tracker') AND createdAt < ?")
+    .run(cutoff).changes;
+}
+
+/**
+ * Persist a `refresh-failed` status + scrubbed error message on an
+ * authorization whose refresh just failed. Never clobbers a `revoked` row (a
+ * disconnected authorization is terminal, not "failing"). Best-effort by id —
+ * no optimistic-concurrency guard, since a successful refresh always bumps
+ * status back to `active` and clears the message anyway.
+ */
+export function markAuthorizationRefreshFailed(
+  id: string,
+  message: string | null,
+): OAuthAuthorization | null {
+  const result = getDb()
+    .query(
+      `UPDATE oauth_authorizations SET
+         status = 'refresh-failed', lastErrorMessage = ?,
+         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+       WHERE id = ? AND status != 'revoked'`,
+    )
+    .run(message, id);
+  return result.changes === 1 ? getAuthorizationById(id) : null;
+}
+
+// ── Provider-string compatibility adapters ──
 
 export function getOAuthTokens(provider: string): OAuthTokens | null {
-  const row = getDb()
-    .query("SELECT * FROM oauth_tokens WHERE provider = ?")
-    .get(provider) as OAuthTokens | null;
-  return row ? normalizeOAuthTokens(row) : null;
+  const row = rawDefaultAuthorizationForProvider(provider);
+  if (!row) return null;
+  const authorization = normalizeAuthorization(row);
+  // A revoked authorization is a disconnected connection: the row is kept for
+  // referential continuity (script_credential_bindings.oauth_authorization_id,
+  // ON DELETE SET NULL) but must read as "no tokens" to provider-string callers.
+  if (authorization.status === "revoked") return null;
+  return {
+    id: authorization.id,
+    provider,
+    accessToken: authorization.accessToken,
+    refreshToken: authorization.refreshToken,
+    expiresAt: authorization.expiresAt ?? "",
+    scope: authorization.scope,
+    tokenVersion: authorization.tokenVersion,
+    createdAt: authorization.createdAt,
+    updatedAt: authorization.updatedAt,
+  };
 }
 
 export function storeOAuthTokens(
@@ -109,23 +708,25 @@ export function storeOAuthTokens(
   data: {
     accessToken: string;
     refreshToken?: string | null;
-    expiresAt: string;
+    expiresAt: string | null;
     scope?: string | null;
   },
 ): void {
-  // TODO(secrets-cipher): encrypt OAuth tokens at rest with src/be/crypto/secrets-cipher.ts.
-  getDb()
-    .query(
-      `INSERT INTO oauth_tokens (provider, accessToken, refreshToken, expiresAt, scope)
-       VALUES (?, ?, ?, ?, ?)
-       ON CONFLICT(provider) DO UPDATE SET
-         accessToken = excluded.accessToken,
-         refreshToken = COALESCE(excluded.refreshToken, oauth_tokens.refreshToken),
-         expiresAt = excluded.expiresAt,
-         scope = COALESCE(excluded.scope, oauth_tokens.scope),
-         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`,
-    )
-    .run(provider, data.accessToken, data.refreshToken ?? null, data.expiresAt, data.scope ?? null);
+  const app = rawOAuthAppByProvider(provider);
+  if (!app) throw new Error(`OAuth app ${provider} is not configured`);
+  const existing = rawDefaultAuthorizationForApp(app.id);
+  upsertAuthorization({
+    ...(existing ? { id: existing.id } : {}),
+    appId: app.id,
+    label: "default",
+    accessToken: data.accessToken,
+    ...(data.refreshToken != null && data.refreshToken !== ""
+      ? { refreshToken: data.refreshToken }
+      : {}),
+    expiresAt: data.expiresAt,
+    ...(data.scope != null ? { scope: data.scope } : {}),
+    status: "active",
+  });
 }
 
 export function updateOAuthTokensAfterRefresh(
@@ -134,98 +735,179 @@ export function updateOAuthTokensAfterRefresh(
   data: {
     accessToken: string;
     refreshToken: string;
-    expiresAt: string;
+    expiresAt: string | null;
     scope?: string | null;
+    expectedTokenVersion?: number;
   },
 ): void {
-  const result = getDb()
-    .query(
-      `UPDATE oauth_tokens
-       SET accessToken = ?,
-           refreshToken = ?,
-           expiresAt = ?,
-           scope = COALESCE(?, scope),
-           updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
-       WHERE provider = ? AND refreshToken = ?`,
-    )
-    .run(
-      data.accessToken,
-      data.refreshToken,
-      data.expiresAt,
-      data.scope ?? null,
-      provider,
-      expectedRefreshToken,
-    );
-
-  if (result.changes === 1) return;
-
-  const current = getOAuthTokens(provider);
+  const current = rawDefaultAuthorizationForProvider(provider);
   if (!current) {
     throw new Error(`OAuth token refresh persistence failed for ${provider}: token row missing`);
   }
-  if (current.refreshToken !== expectedRefreshToken) {
+  const normalized = normalizeAuthorization(current);
+  if (normalized.refreshToken !== expectedRefreshToken) {
     throw new Error(
       `OAuth token refresh persistence failed for ${provider}: stored refresh token changed during refresh`,
     );
   }
-  throw new Error(`OAuth token refresh persistence failed for ${provider}: no rows updated`);
+  const updated = updateAuthorizationTokens(current.id, {
+    accessToken: data.accessToken,
+    refreshToken: data.refreshToken,
+    expiresAt: data.expiresAt,
+    ...(data.scope != null ? { scope: data.scope } : {}),
+    expectedTokenVersion: data.expectedTokenVersion ?? current.tokenVersion,
+  });
+  if (updated) return;
+
+  const latest = getAuthorizationById(current.id);
+  if (!latest) {
+    throw new Error(`OAuth token refresh persistence failed for ${provider}: token row missing`);
+  }
+  if (latest.refreshToken === expectedRefreshToken) {
+    throw new Error(`OAuth token refresh persistence failed for ${provider}: no rows updated`);
+  }
+  throw new Error(
+    `OAuth token refresh persistence failed for ${provider}: stored refresh token changed during refresh`,
+  );
 }
 
-/**
- * Presence-flags-only projection of oauth_tokens for the background refresh
- * sweep. Deliberately excludes token values so sweep code can never leak
- * them into logs.
- */
-export type OAuthTokenSweepRow = {
+export type AuthorizationSweepRow = {
+  authorizationId: string;
+  appId: string;
   provider: string;
-  hasApp: boolean;
+  label: string;
+  status: OAuthAuthorizationStatus;
   hasRefreshToken: boolean;
   expiresAt: string;
   updatedAt: string;
 };
 
-export function listOAuthTokenSweepRows(): OAuthTokenSweepRow[] {
+/**
+ * Every provider-facing authorization (any label; DCR/MCP apps excluded) the
+ * background sweep should consider. Keyed by authorization id — the sweep skips
+ * `revoked` rows and refreshes `refresh-failed` ones each pass so transient
+ * provider outages self-heal.
+ */
+export function listAuthorizationSweepRows(): AuthorizationSweepRow[] {
   const rows = getDb()
     .query(
-      `SELECT t.provider,
-              CASE WHEN a.provider IS NOT NULL THEN 1 ELSE 0 END AS hasApp,
-              CASE WHEN t.refreshToken IS NOT NULL AND t.refreshToken != '' THEN 1 ELSE 0 END AS hasRefreshToken,
-              t.expiresAt,
-              t.updatedAt
-       FROM oauth_tokens t
-       LEFT JOIN oauth_apps a ON a.provider = t.provider
-       ORDER BY t.provider ASC`,
+      `SELECT z.id AS authorizationId,
+              z.appId AS appId,
+              a.provider AS provider,
+              z.label AS label,
+              z.status AS status,
+              CASE WHEN z.refreshToken IS NOT NULL AND z.refreshToken != '' THEN 1 ELSE 0 END AS hasRefreshToken,
+              COALESCE(z.expiresAt, '') AS expiresAt,
+              z.updatedAt AS updatedAt
+       FROM oauth_authorizations z
+       JOIN oauth_apps a ON a.id = z.appId
+       WHERE a.mcpServerId IS NULL
+       ORDER BY a.provider ASC, z.label ASC`,
     )
     .all() as Array<{
+    authorizationId: string;
+    appId: string;
     provider: string;
-    hasApp: number;
+    label: string;
+    status: OAuthAuthorizationStatus;
     hasRefreshToken: number;
     expiresAt: string;
     updatedAt: string;
   }>;
   return rows.map((row) => ({
+    authorizationId: row.authorizationId,
+    appId: row.appId,
     provider: row.provider,
-    hasApp: row.hasApp === 1,
+    label: row.label,
+    status: row.status,
     hasRefreshToken: row.hasRefreshToken === 1,
     expiresAt: normalizeDateRequired(row.expiresAt),
     updatedAt: normalizeDateRequired(row.updatedAt),
   }));
 }
 
+export type KeepAliveAuthorization = {
+  authorizationId: string;
+  appId: string;
+  provider: string;
+  label: string;
+  displayName: string | null;
+};
+
+/**
+ * Active, refreshable authorizations whose app opts into keep-alive: either it
+ * rotates refresh tokens (`requiresRefreshTokenRotation=1`) or sets the
+ * `keepAlive` metadata flag. Replaces the hardcoded `["linear","jira"]` list;
+ * migrated tracker rows qualify automatically (jira via rotation, linear via
+ * the metadata backfill).
+ */
+export function listKeepAliveAuthorizations(): KeepAliveAuthorization[] {
+  const rows = getDb()
+    .query(
+      `SELECT z.id AS authorizationId,
+              z.appId AS appId,
+              a.provider AS provider,
+              z.label AS label,
+              a.displayName AS displayName
+       FROM oauth_authorizations z
+       JOIN oauth_apps a ON a.id = z.appId
+       WHERE a.mcpServerId IS NULL
+         AND z.status = 'active'
+         AND z.refreshToken IS NOT NULL AND z.refreshToken != ''
+         AND (
+           a.requiresRefreshTokenRotation = 1
+           OR (json_valid(a.metadata) = 1 AND json_extract(a.metadata, '$.keepAlive') IN (1, 'true'))
+         )
+       ORDER BY a.provider ASC, z.label ASC`,
+    )
+    .all() as Array<{
+    authorizationId: string;
+    appId: string;
+    provider: string;
+    label: string;
+    displayName: string | null;
+  }>;
+  return rows.map((row) => ({
+    authorizationId: row.authorizationId,
+    appId: row.appId,
+    provider: row.provider,
+    label: row.label,
+    displayName: row.displayName,
+  }));
+}
+
 export function deleteOAuthTokens(provider: string): void {
-  getDb().query("DELETE FROM oauth_tokens WHERE provider = ?").run(provider);
+  const app = rawOAuthAppByProvider(provider);
+  if (!app) return;
+  const existing = rawDefaultAuthorizationForApp(app.id);
+  if (!existing) return;
+  // Disconnect revokes in place — clear token fields and mark revoked but KEEP
+  // the row so script_credential_bindings.oauth_authorization_id survives and a
+  // later reconnect (upsert by appId+label='default') reuses the same id. Real
+  // deletion of an authorization only happens via oauth_apps CASCADE.
+  getDb()
+    .query(
+      `UPDATE oauth_authorizations SET
+         accessToken = ?, refreshToken = NULL, expiresAt = NULL, scope = NULL,
+         tokensEncrypted = 1, tokenVersion = tokenVersion + 1,
+         status = 'revoked', lastErrorMessage = NULL, lastRefreshedAt = NULL,
+         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+       WHERE id = ?`,
+    )
+    .run(encryptSecret("", getEncryptionKey()), existing.id);
 }
 
 export function isTokenExpiringSoon(provider: string, bufferMs = 5 * 60 * 1000): boolean {
   const tokens = getOAuthTokens(provider);
   if (!tokens) return true;
   const expiresAt = new Date(tokens.expiresAt).getTime();
+  if (Number.isNaN(expiresAt)) return true;
   return expiresAt - Date.now() < bufferMs;
 }
 
 // ── OAuth Refresh Locks ──
 
-export function acquireOAuthRefreshLock(provider: string, ttlMs: number): string | null {
+export function acquireOAuthRefreshLock(lockKey: string, ttlMs: number): string | null {
   const owner = crypto.randomUUID();
   const now = Date.now();
   const expiresAt = new Date(now + ttlMs).toISOString();
@@ -233,25 +915,25 @@ export function acquireOAuthRefreshLock(provider: string, ttlMs: number): string
 
   getDb()
     .query(
-      `INSERT INTO oauth_refresh_locks (provider, owner, expiresAt, createdAt, updatedAt)
+      `INSERT INTO oauth_refresh_locks (lockKey, owner, expiresAt, createdAt, updatedAt)
        VALUES (?, ?, ?, ?, ?)
-       ON CONFLICT(provider) DO UPDATE SET
+       ON CONFLICT(lockKey) DO UPDATE SET
          owner = excluded.owner,
          expiresAt = excluded.expiresAt,
          updatedAt = excluded.updatedAt
        WHERE oauth_refresh_locks.expiresAt <= ?`,
     )
-    .run(provider, owner, expiresAt, nowIso, nowIso, nowIso);
+    .run(lockKey, owner, expiresAt, nowIso, nowIso, nowIso);
 
   const row = getDb()
-    .query("SELECT owner FROM oauth_refresh_locks WHERE provider = ?")
-    .get(provider) as { owner: string } | null;
+    .query("SELECT owner FROM oauth_refresh_locks WHERE lockKey = ?")
+    .get(lockKey) as { owner: string } | null;
 
   return row?.owner === owner ? owner : null;
 }
 
-export function releaseOAuthRefreshLock(provider: string, owner: string): void {
+export function releaseOAuthRefreshLock(lockKey: string, owner: string): void {
   getDb()
-    .query("DELETE FROM oauth_refresh_locks WHERE provider = ? AND owner = ?")
-    .run(provider, owner);
+    .query("DELETE FROM oauth_refresh_locks WHERE lockKey = ? AND owner = ?")
+    .run(lockKey, owner);
 }