Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
25.5 KB
Raw Blame
import type { DbClient, DbTransactionClient } from '../db.js'
import { decryptOAuthSecret, encryptOAuthSecret } from './encryption.js'

/**
 * Store for DCR (RFC 7591) dynamic clients — sibling of `store.ts` (spec 02 C2,
 * D-5, DEC-18). When an Authorization Server supports neither a pre-registered
 * client nor CIMD, control-api registers a client dynamically and persists its
 * credentials here with the same at-rest guarantees as `oauth_grants`.
 *
 * Every function takes `(db, encryptionKey, input)` (or `(db, key)` for the
 * key-only delete): the store owns no pool and no key. The `client_secret` and
 * the RFC 7592 `registration_access_token` are AES-256-GCM encrypted with
 * `encryptOAuthSecret` and never stored or returned in the clear except through
 * an explicit decrypt on read. `client_id` is the AS's public assignment and is
 * stored (and mirrored to `spec.oauth.id`) in plaintext by design.
 *
 * Keyed per-server-CR: `(owner_kind, server_namespace, server_name)` mirror the
 * pre-registered `${serverName}-oauth-client` Secret coordinates and
 * `oauth_grants` — the untrusted AS never names the primary key (DEC-18).
 */

/**
 * Identifies one `dynamic_clients` row. `ownerKind` defaults to `'mcpserver'`
 * (mirrors `resolveOwnerKind` in store.ts); remote OAuth servers are the only
 * dynamic-client owners today.
 */
export interface DynamicClientKey {
  ownerKind?: 'mcpserver'
  serverNamespace: string
  serverName: string
}

/** Resolve the owner domain of a key, defaulting to the mcpserver domain. */
function resolveOwnerKind(input: { ownerKind?: 'mcpserver' }): 'mcpserver' {
  return input.ownerKind ?? 'mcpserver'
}

/** One decrypted row of `dynamic_clients`. */
export interface DynamicClientRow {
  /** Surrogate row id; part of the identity a reclaim must still find unchanged. */
  id: string
  ownerKind: 'mcpserver'
  serverNamespace: string
  serverName: string
  issuer: string
  /** AS-assigned public client identifier (never encrypted). */
  clientId: string
  clientMode: 'public' | 'confidential'
  /** Plaintext client secret; undefined for a public client or when absent. */
  clientSecret?: string
  /** Plaintext RFC 7592 registration-management bearer; undefined when absent. */
  registrationAccessToken?: string
  /** RFC 7592 management endpoint; undefined when the AS returned none. */
  registrationClientUri?: string
  clientIdIssuedAt?: Date
  /** RFC 7591; null (non-expiring) is mapped to undefined. */
  clientSecretExpiresAt?: Date
  /** Saga install token that owns the row during the install; undefined = legacy. */
  installId?: string
  /** metadata.uid of the owning McpServer once bound; undefined = pending/legacy. */
  crUid?: string
  createdAt: Date
  updatedAt: Date
  /**
   * Age of the row (`NOW() - updated_at`) as measured by the database at read
   * time, so the pending-TTL decision never mixes the pod clock with the DB clock
   * that stamped `updated_at`.
   */
  ageMs: number
}

export type UpsertDynamicClientInput = DynamicClientKey & {
  issuer: string
  clientId: string
  clientMode: 'public' | 'confidential'
  /** Encrypted before storage; omit for a public client. */
  clientSecret?: string
  /** Encrypted before storage; omit when the AS returned none. */
  registrationAccessToken?: string
  registrationClientUri?: string
  /** RFC 7591 NumericDate (epoch seconds); absent → NULL. */
  clientIdIssuedAtSec?: number
  /** RFC 7591 NumericDate (epoch seconds); 0/absent (non-expiring) → NULL. */
  clientSecretExpiresAtSec?: number
}

/**
 * RFC 7591 NumericDate (absolute epoch seconds) → Date. `0` means "does not
 * expire" (RFC 7591 §3.2.1) and, like an absent value, maps to NULL.
 */
function numericDateToDate(seconds: number | undefined): Date | null {
  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) return null
  return new Date(seconds * 1000)
}

/**
 * Column values that carry the AS credentials of a dynamic client, encrypted and
 * date-normalized identically wherever an install-identity row is written (pending
 * insert / orphan reclaim), so the at-rest shape lives in ONE place (D4).
 */
function encodeCredentialColumns(
  encryptionKey: Buffer,
  input: UpsertDynamicClientInput
): {
  clientSecretEncrypted: string | null
  registrationAccessTokenEncrypted: string | null
  registrationClientUri: string | null
  clientIdIssuedAt: Date | null
  clientSecretExpiresAt: Date | null
} {
  return {
    clientSecretEncrypted: input.clientSecret
      ? encryptOAuthSecret(encryptionKey, input.clientSecret)
      : null,
    registrationAccessTokenEncrypted: input.registrationAccessToken
      ? encryptOAuthSecret(encryptionKey, input.registrationAccessToken)
      : null,
    registrationClientUri: input.registrationClientUri ?? null,
    clientIdIssuedAt: numericDateToDate(input.clientIdIssuedAtSec),
    clientSecretExpiresAt: numericDateToDate(input.clientSecretExpiresAtSec),
  }
}

/**
 * Insert (or replace) the dynamic client for a server CR. Re-registration
 * overwrites in place (INSERT … ON CONFLICT DO UPDATE). `client_secret` and
 * `registration_access_token` are encrypted at rest; a public client stores NULL
 * for the secret.
 *
 * NO production caller: the remote-install saga now claims the name with
 * `insertDynamicClientPending` (ON CONFLICT DO NOTHING) so an install can never
 * clobber a live server's row. This clobbering upsert is retained ONLY as a store
 * primitive exercised by its own unit tests and as a row-seeder for other suites;
 * it must NOT be reintroduced into any install/reclaim path.
 */
export async function upsertDynamicClient(
  db: DbClient,
  encryptionKey: Buffer,
  input: UpsertDynamicClientInput
): Promise<void> {
  const ownerKind = resolveOwnerKind(input)
  const clientSecretEncrypted = input.clientSecret
    ? encryptOAuthSecret(encryptionKey, input.clientSecret)
    : null
  const registrationAccessTokenEncrypted = input.registrationAccessToken
    ? encryptOAuthSecret(encryptionKey, input.registrationAccessToken)
    : null

  await db.query(
    `INSERT INTO dynamic_clients (
       owner_kind, server_namespace, server_name, issuer, client_id, client_mode,
       client_secret_encrypted, registration_access_token_encrypted,
       registration_client_uri, client_id_issued_at, client_secret_expires_at,
       updated_at
     ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, NOW())
     ON CONFLICT (owner_kind, server_namespace, server_name)
     DO UPDATE SET
       issuer = EXCLUDED.issuer,
       client_id = EXCLUDED.client_id,
       client_mode = EXCLUDED.client_mode,
       client_secret_encrypted = EXCLUDED.client_secret_encrypted,
       registration_access_token_encrypted = EXCLUDED.registration_access_token_encrypted,
       registration_client_uri = EXCLUDED.registration_client_uri,
       client_id_issued_at = EXCLUDED.client_id_issued_at,
       client_secret_expires_at = EXCLUDED.client_secret_expires_at,
       updated_at = NOW()`,
    [
      ownerKind,
      input.serverNamespace,
      input.serverName,
      input.issuer,
      input.clientId,
      input.clientMode,
      clientSecretEncrypted,
      registrationAccessTokenEncrypted,
      input.registrationClientUri ?? null,
      numericDateToDate(input.clientIdIssuedAtSec),
      numericDateToDate(input.clientSecretExpiresAtSec),
    ]
  )
}

interface DynamicClientDbRow {
  id: string | number
  owner_kind: 'mcpserver'
  server_namespace: string
  server_name: string
  issuer: string
  client_id: string
  client_mode: 'public' | 'confidential'
  client_secret_encrypted: string | null
  registration_access_token_encrypted: string | null
  registration_client_uri: string | null
  client_id_issued_at: Date | null
  client_secret_expires_at: Date | null
  install_id: string | null
  cr_uid: string | null
  created_at: Date
  updated_at: Date
  age_ms: number
}

const SELECT_COLUMNS = `id, owner_kind, server_namespace, server_name, issuer, client_id, client_mode,
            client_secret_encrypted, registration_access_token_encrypted,
            registration_client_uri, client_id_issued_at, client_secret_expires_at,
            install_id, cr_uid, created_at, updated_at,
            (EXTRACT(EPOCH FROM (NOW() - updated_at)) * 1000)::float8 AS age_ms`

/** Read one dynamic client, decrypting its secret and registration token. */
export async function getDynamicClient(
  db: DbClient,
  encryptionKey: Buffer,
  key: DynamicClientKey
): Promise<DynamicClientRow | null> {
  const ownerKind = resolveOwnerKind(key)
  const result = await db.query(
    `SELECT ${SELECT_COLUMNS}
       FROM dynamic_clients
      WHERE owner_kind = $1 AND server_namespace = $2 AND server_name = $3`,
    [ownerKind, key.serverNamespace, key.serverName]
  )
  if (result.rows.length === 0) return null
  const row = result.rows[0] as DynamicClientDbRow
  return {
    id: String(row.id),
    ownerKind: row.owner_kind,
    serverNamespace: row.server_namespace,
    serverName: row.server_name,
    issuer: row.issuer,
    clientId: row.client_id,
    clientMode: row.client_mode,
    clientSecret: row.client_secret_encrypted
      ? decryptOAuthSecret(encryptionKey, row.client_secret_encrypted)
      : undefined,
    registrationAccessToken: row.registration_access_token_encrypted
      ? decryptOAuthSecret(encryptionKey, row.registration_access_token_encrypted)
      : undefined,
    registrationClientUri: row.registration_client_uri ?? undefined,
    clientIdIssuedAt: row.client_id_issued_at ?? undefined,
    clientSecretExpiresAt: row.client_secret_expires_at ?? undefined,
    installId: row.install_id ?? undefined,
    crUid: row.cr_uid ?? undefined,
    createdAt: row.created_at,
    updatedAt: row.updated_at,
    ageMs: Number(row.age_ms),
  }
}

/**
 * Whether any dynamic client of `issuer` in this server namespace carries `clientId`,
 * pending, bound or legacy alike: every row stands for a client that may still be live
 * at its AS (teardown deletes the row). A client_id is only unique within its AS, so a
 * row of another issuer is another client. Reads no encrypted column.
 */
export async function isDynamicClientIdRegistered(
  db: DbClient,
  input: { serverNamespace: string; issuer: string; clientId: string; ownerKind?: 'mcpserver' }
): Promise<boolean> {
  const result = await db.query(
    `SELECT 1
       FROM dynamic_clients
      WHERE owner_kind = $1 AND server_namespace = $2 AND client_id = $3 AND issuer = $4
      LIMIT 1`,
    [resolveOwnerKind(input), input.serverNamespace, input.clientId, input.issuer]
  )
  return result.rows.length > 0
}

/** The installation identity of a dynamic client, without any credential material. */
export interface DynamicClientBinding {
  clientId: string
  /** Install nonce the client's redirect URI was registered with; undefined = legacy row. */
  installId?: string
  /** metadata.uid of the McpServer the row is bound to; undefined = pending or legacy. */
  crUid?: string
}

/**
 * Read which installation a server's dynamic client belongs to. Reads no encrypted
 * column, so the consent paths can check the binding without decrypting a secret they
 * may never use.
 */
export async function getDynamicClientBinding(
  db: DbClient,
  key: DynamicClientKey
): Promise<DynamicClientBinding | null> {
  const result = await db.query(
    `SELECT client_id, install_id, cr_uid
       FROM dynamic_clients
      WHERE owner_kind = $1 AND server_namespace = $2 AND server_name = $3`,
    [resolveOwnerKind(key), key.serverNamespace, key.serverName]
  )
  if (result.rows.length === 0) return null
  const row = result.rows[0] as Pick<DynamicClientDbRow, 'client_id' | 'install_id' | 'cr_uid'>
  return {
    clientId: row.client_id,
    installId: row.install_id ?? undefined,
    crUid: row.cr_uid ?? undefined,
  }
}

/**
 * Metadata-only view of a `dynamic_clients` row whose confidential secret is at
 * or near expiry — enough for the DCR lifecycle decision (§5) without touching
 * any encrypted material.
 */
export interface ExpiringDynamicClient {
  serverNamespace: string
  serverName: string
  clientMode: 'confidential'
  /** Non-null by construction (the enumeration filters out NULL expiry). */
  clientSecretExpiresAt: Date
}

/**
 * Enumerate confidential dynamic clients whose `client_secret_expires_at` is at
 * or before `now + withinMs` (mini-spec L §5). METADATA-ONLY: it never decrypts
 * the secret or the registration token, so it needs no `encryptionKey`.
 *
 * The filter already realizes the §5 table's structure: `public` and
 * non-expiring rows are excluded (C1/C2), healthy rows fall outside `withinMs`
 * (C3), and the returned set covers BOTH expiring (C4, `now < exp`) and expired
 * (C5, `exp ≤ now`) — the caller splits them with `classifyDcrSecretDecision`.
 */
export async function listExpiringDynamicClients(
  db: DbClient,
  opts: { withinMs: number }
): Promise<ExpiringDynamicClient[]> {
  const result = await db.query(
    `SELECT server_namespace, server_name, client_mode, client_secret_expires_at
       FROM dynamic_clients
      WHERE client_mode = 'confidential'
        AND client_secret_expires_at IS NOT NULL
        AND client_secret_expires_at <= NOW() + ($1::bigint * INTERVAL '1 millisecond')
      ORDER BY server_namespace, server_name`,
    [opts.withinMs]
  )
  return result.rows.map(r => {
    const row = r as {
      server_namespace: string
      server_name: string
      client_mode: 'confidential'
      client_secret_expires_at: Date
    }
    return {
      serverNamespace: row.server_namespace,
      serverName: row.server_name,
      clientMode: row.client_mode,
      clientSecretExpiresAt: row.client_secret_expires_at,
    }
  })
}

/**
 * RFC 7592 management handle of a dynamic client: the endpoint and the bearer
 * needed to DELETE it at the AS. Present only when both were persisted.
 */
export interface DynamicClientRegistrationHandle {
  registrationClientUri: string
  registrationAccessToken: string
}

/**
 * How long a `pending` row (install_id set, cr_uid NULL) is treated as an
 * in-flight install before an unfinished saga's row becomes reclaimable. Chosen
 * above the longest possible saga (discovery + probe + DCR + create + attach,
 * each bounded ≤ 15s), so a live install never has its own row reclaimed.
 */
export const PENDING_TTL_MS = 10 * 60_000

/**
 * The three lifetimes an existing `dynamic_clients` row can have at INSERT-conflict
 * or teardown time. `in-use` and `in-progress` belong to someone and must not be
 * touched; `reclaimable` (orphan/legacy) may be taken over.
 */
export type ExistingDynamicClientClass = 'in-use' | 'in-progress' | 'reclaimable'

/**
 * Decide who owns a conflicting `dynamic_clients` row — the one rule for "whose
 * row is this?" (D4). Pure and total; the caller supplies the row's DB-measured
 * age, the pending TTL, and `liveCrUid` (the uid of a live McpServer with this
 * name, when one exists).
 *
 * `liveCrUid` is only meaningful if it was read AFTER the row it is classified
 * with: a CR created and bound between an earlier K8s read and the row read would
 * otherwise make a live install's row look orphaned.
 *
 * A live CR owns the name unconditionally: it covers a bound-live row AND the
 * pre-check→INSERT TOCTOU race where the CR appeared after the pending INSERT.
 * With no live CR, a bound row (cr_uid set) is an orphan of a gone install, a
 * fresh pending row is another saga in flight, an expired pending row is a
 * crashed saga, and a legacy row (both NULL, no live CR) is treated by name as
 * today — all reclaimable except the fresh pending one.
 */
export function classifyExistingDynamicClient(
  row: { installId: string | null; crUid: string | null; ageMs: number },
  ctx: { pendingTtlMs: number; liveCrUid?: string }
): ExistingDynamicClientClass {
  if (ctx.liveCrUid !== undefined) return 'in-use'
  if (row.crUid != null) return 'reclaimable'
  if (row.installId != null) {
    // In-progress iff age is strictly under the TTL; at exactly the TTL the row is
    // expired and reclaimable.
    return row.ageMs < ctx.pendingTtlMs ? 'in-progress' : 'reclaimable'
  }
  return 'reclaimable'
}

/**
 * Claim the name for a new install by inserting a PENDING row (install_id set,
 * cr_uid NULL) with `ON CONFLICT (owner_kind, server_namespace, server_name) DO
 * NOTHING`. Never overwrites an existing row — that is the whole point over
 * `upsertDynamicClient`: a live server's credentials are never clobbered. Returns
 * `{ inserted: false }` on conflict so the caller can classify the existing row.
 */
export async function insertDynamicClientPending(
  db: DbClient,
  encryptionKey: Buffer,
  input: UpsertDynamicClientInput & { installId: string }
): Promise<{ inserted: boolean }> {
  const ownerKind = resolveOwnerKind(input)
  const creds = encodeCredentialColumns(encryptionKey, input)

  const result = await db.query(
    `INSERT INTO dynamic_clients (
       owner_kind, server_namespace, server_name, issuer, client_id, client_mode,
       client_secret_encrypted, registration_access_token_encrypted,
       registration_client_uri, client_id_issued_at, client_secret_expires_at,
       install_id, cr_uid, updated_at
     ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, NULL, NOW())
     ON CONFLICT (owner_kind, server_namespace, server_name) DO NOTHING
     RETURNING id`,
    [
      ownerKind,
      input.serverNamespace,
      input.serverName,
      input.issuer,
      input.clientId,
      input.clientMode,
      creds.clientSecretEncrypted,
      creds.registrationAccessTokenEncrypted,
      creds.registrationClientUri,
      creds.clientIdIssuedAt,
      creds.clientSecretExpiresAt,
      input.installId,
    ]
  )
  return { inserted: (result.rowCount ?? 0) > 0 }
}

/**
 * The identity of a `dynamic_clients` row as the caller read and classified it.
 * A reclaim only applies to the row in exactly this state.
 */
export type ObservedDynamicClient = Pick<DynamicClientRow, 'id' | 'installId' | 'crUid'>

/**
 * Take over a row the caller classified `reclaimable` (orphan or legacy) for a
 * new install, atomically. Does NOT classify: the caller did, from `observed` and
 * a live-CR read taken after it. This applies the takeover only if the row still
 * has the observed `id`, `install_id` AND `cr_uid` — one guard, evaluated on the
 * row-locked latest version, so:
 * - a concurrent reclaim that won first changed `install_id` → we lose;
 * - the owner binding its pending row (`cr_uid` NULL → uid) after our read →
 *   we lose, and a live install's client is never overwritten or revoked;
 * - the row deleted (teardown) → 0 rows → we lose (conservative; the operator's
 *   retry goes through the INSERT).
 * Re-classifying under the lock is deliberately absent: it would re-decide with a
 * K8s read that predates the locked version, which is exactly the stale-uid bug.
 *
 * The guard does not compare `updated_at`: every production writer that moves it
 * also changes `id` (INSERT), `install_id` (reclaim) or `cr_uid` (bind), so the
 * observed age can only have grown and an expired pending row stays expired.
 * `upsertDynamicClient` refreshes `updated_at` with identity intact and would break
 * that premise; it has no production caller and must not gain one on this table.
 *
 * Returns the OLD row's RFC 7592 handle (decrypted, when present) so the caller
 * can best-effort revoke the superseded client at the AS.
 *
 * The reclaim is a single statement, so the transaction adds no atomicity; the
 * runner is kept only as the injection point.
 *
 * `runInTransaction` is a REQUIRED injected runner (pass `withTransaction` from
 * db.ts) rather than a default import — this module sits on the config init path
 * (config → tokenHelper → callback → here), so importing db.ts's `withTransaction`
 * value at module top-level would close an init cycle back to `config` and leave
 * it undefined. The injection also lets tests bind the runner to a disposable pool.
 */
export async function reclaimOrphanDynamicClient(
  encryptionKey: Buffer,
  input: {
    key: DynamicClientKey
    newCredentials: UpsertDynamicClientInput
    newInstallId: string
    observed: ObservedDynamicClient
  },
  runInTransaction: <T>(work: (tx: DbTransactionClient) => Promise<T>) => Promise<T>
): Promise<{ reclaimed: boolean; oldHandle?: DynamicClientRegistrationHandle }> {
  const ownerKind = resolveOwnerKind(input.key)
  const creds = encodeCredentialColumns(encryptionKey, input.newCredentials)

  return runInTransaction(async tx => {
    const updated = await tx.query(
      `WITH prev AS (
         SELECT id, registration_client_uri, registration_access_token_encrypted
           FROM dynamic_clients
          WHERE owner_kind = $1 AND server_namespace = $2 AND server_name = $3
            AND id = $13
            AND install_id IS NOT DISTINCT FROM $14
            AND cr_uid IS NOT DISTINCT FROM $15
          FOR UPDATE
       )
       UPDATE dynamic_clients d
          SET issuer = $4,
              client_id = $5,
              client_mode = $6,
              client_secret_encrypted = $7,
              registration_access_token_encrypted = $8,
              registration_client_uri = $9,
              client_id_issued_at = $10,
              client_secret_expires_at = $11,
              install_id = $12,
              cr_uid = NULL,
              updated_at = NOW()
         FROM prev
        WHERE d.id = prev.id
       RETURNING prev.registration_client_uri, prev.registration_access_token_encrypted`,
      [
        ownerKind,
        input.key.serverNamespace,
        input.key.serverName,
        input.newCredentials.issuer,
        input.newCredentials.clientId,
        input.newCredentials.clientMode,
        creds.clientSecretEncrypted,
        creds.registrationAccessTokenEncrypted,
        creds.registrationClientUri,
        creds.clientIdIssuedAt,
        creds.clientSecretExpiresAt,
        input.newInstallId,
        input.observed.id,
        input.observed.installId ?? null,
        input.observed.crUid ?? null,
      ]
    )
    if ((updated.rowCount ?? 0) !== 1) return { reclaimed: false }
    const prev = updated.rows[0] as {
      registration_client_uri: string | null
      registration_access_token_encrypted: string | null
    }

    const oldHandle =
      prev.registration_client_uri && prev.registration_access_token_encrypted
        ? {
            registrationClientUri: prev.registration_client_uri,
            registrationAccessToken: decryptOAuthSecret(
              encryptionKey,
              prev.registration_access_token_encrypted
            ),
          }
        : undefined
    return { reclaimed: true, oldHandle }
  })
}

/**
 * Bind a pending row to the McpServer that was just created: set its `cr_uid`,
 * guarded on `install_id = $installId AND cr_uid IS NULL` so it only ever binds
 * OUR pending row. `{ bound: false }` means the row was reclaimed out from under
 * this saga (TTL expired mid-install) — the caller must not proceed as owner.
 */
export async function bindDynamicClientToResource(
  db: DbClient,
  key: DynamicClientKey,
  installId: string,
  crUid: string
): Promise<{ bound: boolean }> {
  const ownerKind = resolveOwnerKind(key)
  const result = await db.query(
    `UPDATE dynamic_clients
        SET cr_uid = $5, updated_at = NOW()
      WHERE owner_kind = $1 AND server_namespace = $2 AND server_name = $3
        AND install_id = $4 AND cr_uid IS NULL`,
    [ownerKind, key.serverNamespace, key.serverName, installId, crUid]
  )
  return { bound: (result.rowCount ?? 0) === 1 }
}

/**
 * Compensation delete for a saga: removes ONLY the row this install owns
 * (`install_id = $installId`), so a concurrent install/reinstall of the same name
 * that already reclaimed the row is never destroyed. Returns rows removed.
 */
export async function deleteDynamicClientOwnedByInstall(
  db: DbClient,
  key: DynamicClientKey,
  installId: string
): Promise<number> {
  const ownerKind = resolveOwnerKind(key)
  const result = await db.query(
    `DELETE FROM dynamic_clients
      WHERE owner_kind = $1 AND server_namespace = $2 AND server_name = $3
        AND install_id = $4`,
    [ownerKind, key.serverNamespace, key.serverName, installId]
  )
  return result.rowCount ?? 0
}

/**
 * Teardown delete for an uninstall of CR uid `crUid`: removes the row bound to
 * THIS uid, or a legacy row (both columns NULL, from before install identity),
 * and returns its RFC 7592 handle in the SAME statement (`DELETE … RETURNING`) so
 * there is no read→await→delete window in which a concurrent reinstall could slip
 * a new row in. A pending row (reinstall in flight) or a row bound to a DIFFERENT
 * uid (reinstall already complete) does not match and is left intact.
 */
export async function claimDeleteDynamicClientForResource(
  db: DbClient,
  encryptionKey: Buffer,
  key: DynamicClientKey,
  crUid: string
): Promise<{ deleted: boolean; handle?: DynamicClientRegistrationHandle }> {
  const ownerKind = resolveOwnerKind(key)
  const result = await db.query(
    `DELETE FROM dynamic_clients
      WHERE owner_kind = $1 AND server_namespace = $2 AND server_name = $3
        AND (cr_uid = $4 OR (install_id IS NULL AND cr_uid IS NULL))
      RETURNING registration_client_uri, registration_access_token_encrypted`,
    [ownerKind, key.serverNamespace, key.serverName, crUid]
  )
  if (result.rows.length === 0) return { deleted: false }
  const row = result.rows[0] as {
    registration_client_uri: string | null
    registration_access_token_encrypted: string | null
  }
  const handle =
    row.registration_client_uri && row.registration_access_token_encrypted
      ? {
          registrationClientUri: row.registration_client_uri,
          registrationAccessToken: decryptOAuthSecret(
            encryptionKey,
            row.registration_access_token_encrypted
          ),
        }
      : undefined
  return { deleted: true, handle }
}