Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

36.2 KB
Raw Blame
import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
import {
  decideResumeCommit,
  RELAY_PROTOCOL_LIMITS,
  type DeviceCredentialInstalled,
  type DeviceResumeConfirmed
} from '@orca-cloud/relay-contract'
import type { RelayDatabase, SqlRow } from './database.js'
import { changes, HeapWindowReaper } from './heap-window-reaper.js'
import { ResumeConfirmedAuditBuffer } from './resume-confirmed-audit-buffer.js'

const CREDENTIAL_GRACE_MS = 24 * 60 * 60 * 1000
// Issue below released desktops’ zero-tolerance inviteTtlMs ceiling so clients lagging by this margin can still pair.
const INVITE_ISSUE_SKEW_MARGIN_MS = 30 * 1000
// Terminal invite readers recheck state/expiry; retain one week only for pairing support, with audit events already durable.
const TERMINAL_INVITE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000
// Readers require active/unconsumed and unexpired ≤30s deadlines; settled rows cannot authorize again, so one day is forensic margin.
const INACTIVE_AUTHORIZATION_RETENTION_MS = 24 * 60 * 60 * 1000
// Confirm retries must match the same request and per-phone connection basis; keep one week for pairing support.
export const CONFIRM_RESULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000
// Nothing in the relay reads audit events back; 90 days covers support and incident questions.
export const AUDIT_EVENT_RETENTION_MS = 90 * 24 * 60 * 60 * 1000
// Bounded so one cycle cannot hold row locks or grow WAL without limit; the backlog drains over
// however many cycles it takes.
const REAP_BATCH_ROWS = 5000
// Unindexed, a drained reap rescans the whole heap; retention is days, so minutes of reap lag are harmless.
const UNINDEXED_REAP_PAUSE_MS = 5 * 60 * 1000
// At ~14 rows/page and ~9 ticks/min, budget reaps ~3M rows/day (~2–3 days for 7.4M backlog); empty walks read ~1MB/tick.
const CONFIRM_RESULT_REAP_BUDGET = {
  pagesPerStatement: 16,
  maxPagesPerTick: 128,
  maxRowsPerTick: 250,
  budgetMs: 250
}

export type RelayIdentity = { userId: string; relayHostId: string }
export type CredentialReservation = RelayIdentity & {
  credentialKind: 'invite' | 'resume'
  relayDeviceId: string
  tokenHash: string
  reservationId: string
  leaseExpiresAt: number
  acceptedCredentialVersion?: number
  acceptedAs?: 'current' | 'grace'
  resumeExpiresAt?: number
  graceExpiresAt?: number
}

export type InstallInput = RelayIdentity & {
  relayDeviceId: string
  reqId: string
  newResumeTokenHash: string
  expectedCurrentHash?: string
  owningControlGeneration: number
  authorization:
    | { mode: 'relay-basis'; basisConnId: string }
    | { mode: 'authenticated-direct'; directAuthId: string }
}

export class RelayStoreError extends Error {
  constructor(readonly code: string) {
    super(code)
  }
}

export function hashCredential(token: string): string {
  return createHash('sha256').update(token).digest('base64url')
}

function equalHash(left: string, right: string): boolean {
  const leftBytes = Buffer.from(left)
  const rightBytes = Buffer.from(right)
  return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes)
}

function number(row: SqlRow, field: string): number {
  const value = Number(row[field])
  if (!Number.isSafeInteger(value)) throw new RelayStoreError(`invalid_${field}`)
  return value
}

function optionalNumber(row: SqlRow, field: string): number | undefined {
  return row[field] === null || row[field] === undefined ? undefined : number(row, field)
}

function string(row: SqlRow, field: string): string {
  const value = row[field]
  if (typeof value !== 'string') throw new RelayStoreError(`invalid_${field}`)
  return value
}

// Memory confirms renew a device at most this often (design decision 3: at most once a day of use).
export const RESUME_RENEWAL_INTERVAL_MS = 24 * 60 * 60 * 1000

function tokenFamily(device: SqlRow) {
  return {
    currentVersion: number(device, 'current_version'),
    currentHash: string(device, 'current_hash'),
    currentExpiresAt: number(device, 'current_expires_at'),
    graceVersion: optionalNumber(device, 'grace_version'),
    graceHash: typeof device.grace_hash === 'string' ? device.grace_hash : undefined,
    graceExpiresAt: optionalNumber(device, 'grace_expires_at'),
    revokedAt: optionalNumber(device, 'revoked_at')
  }
}

// A device row's answer to a resume token: null when revoked, or neither hash is still valid.
function resumeReservation(
  device: SqlRow,
  relayHostId: string,
  tokenHash: string,
  reservationId: string,
  now: number
): CredentialReservation | null {
  if (optionalNumber(device, 'revoked_at') !== undefined) return null
  const currentHash = string(device, 'current_hash')
  const currentExpiresAt = number(device, 'current_expires_at')
  const graceHash = device.grace_hash
  const graceExpiresAt = optionalNumber(device, 'grace_expires_at')
  let acceptedAs: 'current' | 'grace'
  let acceptedCredentialVersion: number
  if (equalHash(currentHash, tokenHash) && currentExpiresAt > now) {
    acceptedAs = 'current'
    acceptedCredentialVersion = number(device, 'current_version')
  } else if (
    typeof graceHash === 'string' &&
    equalHash(graceHash, tokenHash) &&
    (graceExpiresAt ?? 0) > now
  ) {
    acceptedAs = 'grace'
    acceptedCredentialVersion = number(device, 'grace_version')
  } else {
    return null
  }
  return {
    userId: string(device, 'user_id'),
    relayHostId,
    relayDeviceId: string(device, 'relay_device_id'),
    credentialKind: 'resume',
    tokenHash,
    reservationId,
    leaseExpiresAt: now + RELAY_PROTOCOL_LIMITS.hostAttachDeadlineMs,
    acceptedCredentialVersion,
    acceptedAs,
    resumeExpiresAt: currentExpiresAt,
    graceExpiresAt
  }
}

export class RelayCredentialStore {
  // committed_at has no index, so a LIMIT delete would plan as a sequential scan of the whole table.
  private readonly confirmResultReaper = new HeapWindowReaper(
    'relay_confirm_results',
    'committed_at <= ?',
    CONFIRM_RESULT_REAP_BUDGET
  )
  private readonly unindexedReapResumesAt = new Map<string, number>()

  // Only memory confirms add to it, so its flush timer never starts on a director.
  readonly resumeAudit: ResumeConfirmedAuditBuffer

  constructor(
    private readonly database: RelayDatabase,
    private readonly now: () => number = Date.now
  ) {
    this.resumeAudit = new ResumeConfirmedAuditBuffer(database, now)
  }

  async createInvite(identity: RelayIdentity, relayDeviceId: string): Promise<{
    inviteToken: string
    expiresAt: number
    maxAttempts: number
  }> {
    const inviteToken = randomBytes(32).toString('base64url')
    const tokenHash = hashCredential(inviteToken)
    const now = this.now()
    const expiresAt = now + RELAY_PROTOCOL_LIMITS.inviteTtlMs - INVITE_ISSUE_SKEW_MARGIN_MS
    await this.database.transaction(async (transaction) => {
      await this.consumeRateWith(transaction, `account:${identity.userId}`, 'invite-mint', 30, 60_000, now)
      await transaction.query(
        `UPDATE relay_invites SET state = ?, updated_at = ?
         WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?
           AND state IN (?, ?, ?)`,
        [
          'invalidated', now, identity.userId, identity.relayHostId, relayDeviceId,
          'available', 'reserved', 'cooldown'
        ]
      )
      await this.auditWith(transaction, {
        type: 'invite-created',
        ...identity,
        relayDeviceId,
        detail: { expiresAt }
      })
      await transaction.query(
        `INSERT INTO relay_invites
         (user_id, relay_host_id, relay_device_id, token_hash, state, attempt_count,
          max_attempts, expires_at, created_at, updated_at)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
        [
          identity.userId, identity.relayHostId, relayDeviceId, tokenHash, 'available', 0,
          RELAY_PROTOCOL_LIMITS.inviteMaxAttempts, expiresAt, now, now
        ]
      )
    })
    return { inviteToken, expiresAt, maxAttempts: RELAY_PROTOCOL_LIMITS.inviteMaxAttempts }
  }

  async reserveCredential(
    relayHostId: string,
    token: string,
    reservationId: string = randomUUID()
  ): Promise<CredentialReservation | null> {
    const tokenHash = hashCredential(token)
    const now = this.now()
    return await this.database.transaction(async (transaction) => {
      const inviteRows = await transaction.query(
        `SELECT * FROM relay_invites WHERE relay_host_id = ? AND token_hash = ?`,
        [relayHostId, tokenHash]
      )
      const invite = inviteRows[0]
      if (invite && equalHash(string(invite, 'token_hash'), tokenHash)) {
        const expiresAt = number(invite, 'expires_at')
        const attempts = number(invite, 'attempt_count')
        const maxAttempts = number(invite, 'max_attempts')
        let state = string(invite, 'state')
        const reservationExpiresAt = optionalNumber(invite, 'reservation_expires_at')
        if (expiresAt <= now) state = 'expired'
        else if (state === 'reserved' && (reservationExpiresAt ?? 0) <= now) {
          await transaction.query(
            `UPDATE relay_invites SET state = ?, reservation_id = NULL,
             reservation_expires_at = NULL, cooldown_until = ?, updated_at = ?
             WHERE token_hash = ?`,
            [
              'cooldown',
              now + RELAY_PROTOCOL_LIMITS.inviteAttemptCooldownMs,
              now,
              tokenHash
            ]
          )
          return null
        }
        const cooldownUntil = optionalNumber(invite, 'cooldown_until') ?? 0
        if (
          (state !== 'available' && !(state === 'cooldown' && cooldownUntil <= now)) ||
          attempts >= maxAttempts
        ) {
          return null
        }
        const leaseExpiresAt = Math.min(
          expiresAt,
          now + RELAY_PROTOCOL_LIMITS.inviteReservationLeaseMs
        )
        await transaction.query(
          `UPDATE relay_invites SET state = ?, attempt_count = ?, reservation_id = ?,
           reservation_expires_at = ?, cooldown_until = NULL, updated_at = ?
           WHERE token_hash = ?`,
          ['reserved', attempts + 1, reservationId, leaseExpiresAt, now, tokenHash]
        )
        return {
          userId: string(invite, 'user_id'),
          relayHostId,
          relayDeviceId: string(invite, 'relay_device_id'),
          credentialKind: 'invite',
          tokenHash,
          reservationId,
          leaseExpiresAt
        }
      }

      const deviceRows = await transaction.query(
        `SELECT * FROM relay_devices
         WHERE relay_host_id = ? AND (current_hash = ? OR grace_hash = ?)`,
        [relayHostId, tokenHash, tokenHash]
      )
      const device = deviceRows[0]
      return device ? resumeReservation(device, relayHostId, tokenHash, reservationId, now) : null
    })
  }

  // Step 6's one-read resume. Only `none` may fall through to the invite path: a device row
  // that refuses this token closes the phone (4401), as reserveCredential would.
  async lookupResume(
    relayHostId: string,
    token: string,
    reservationId: string = randomUUID()
  ): Promise<
    | { outcome: 'none' }
    | { outcome: 'refused' }
    | { outcome: 'resume'; reservation: CredentialReservation }
  > {
    const tokenHash = hashCredential(token)
    const rows = await this.database.query(
      `SELECT * FROM relay_devices
       WHERE relay_host_id = ? AND (current_hash = ? OR grace_hash = ?)`,
      [relayHostId, tokenHash, tokenHash]
    )
    const device = rows[0]
    if (!device) return { outcome: 'none' }
    const reservation = resumeReservation(device, relayHostId, tokenHash, reservationId, this.now())
    return reservation ? { outcome: 'resume', reservation } : { outcome: 'refused' }
  }

  async recordConnectionBasis(input: CredentialReservation & {
    basisConnId: string
    owningControlGeneration: number
    deadline: number
  }): Promise<void> {
    const now = this.now()
    await this.database.query(
      `INSERT INTO relay_connection_bases
       (basis_conn_id, user_id, relay_host_id, relay_device_id, owning_control_generation,
        credential_kind, invite_token_hash, accepted_credential_version, accepted_as,
        deadline, active, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
      [
        input.basisConnId, input.userId, input.relayHostId, input.relayDeviceId,
        input.owningControlGeneration, input.credentialKind,
        input.credentialKind === 'invite' ? input.tokenHash : null,
        input.acceptedCredentialVersion, input.acceptedAs, input.deadline, 1, now
      ]
    )
  }

  async failReservation(reservation: CredentialReservation): Promise<void> {
    if (reservation.credentialKind !== 'invite') return
    const now = this.now()
    await this.database.transaction(async (transaction) => {
      const rows = await transaction.query(
        `SELECT attempt_count, max_attempts FROM relay_invites
         WHERE token_hash = ? AND reservation_id = ? AND state = ?`,
        [reservation.tokenHash, reservation.reservationId, 'reserved']
      )
      const invite = rows[0]
      if (!invite) return
      const exhausted = number(invite, 'attempt_count') >= number(invite, 'max_attempts')
      await transaction.query(
        `UPDATE relay_invites SET state = ?, reservation_id = NULL,
         reservation_expires_at = NULL, cooldown_until = ?, updated_at = ?
         WHERE token_hash = ? AND reservation_id = ?`,
        [
          exhausted ? 'invalidated' : 'cooldown',
          exhausted ? null : now + RELAY_PROTOCOL_LIMITS.inviteAttemptCooldownMs,
          now,
          reservation.tokenHash,
          reservation.reservationId
        ]
      )
    })
  }

  async recordDirectAuthorization(input: RelayIdentity & {
    relayDeviceId: string
    directAuthId: string
    owningControlGeneration: number
    deadline: number
  }): Promise<void> {
    await this.database.query(
      `INSERT INTO relay_direct_authorizations
       (direct_auth_id, user_id, relay_host_id, relay_device_id,
        owning_control_generation, deadline)
       VALUES (?, ?, ?, ?, ?, ?)`,
      [
        input.directAuthId, input.userId, input.relayHostId, input.relayDeviceId,
        input.owningControlGeneration, input.deadline
      ]
    )
  }

  async installCredential(input: InstallInput): Promise<DeviceCredentialInstalled> {
    let lastError: unknown
    for (let attempt = 0; attempt <= 3; attempt++) {
      try {
        return await this.installCredentialOnce(input)
      } catch (error) {
        if (error instanceof RelayStoreError) throw error
        const committed = await this.installStatus(input)
        if (committed) return committed
        const code = (error as { code?: unknown }).code
        const retryable = ['23505', '40P01', '55P03', '40001'].includes(String(code))
        if (!retryable || attempt === 3) throw error
        lastError = error
      }
    }
    throw lastError
  }

  private async installCredentialOnce(input: InstallInput): Promise<DeviceCredentialInstalled> {
    return await this.database.transaction(async (transaction) => {
      const existing = await this.installStatusWith(transaction, input)
      if (existing) return existing
      const now = this.now()
      const basisInviteHash = await this.validateInstallAuthorization(transaction, input, now)
      const devices = await transaction.query(
        `SELECT * FROM relay_devices
         WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?`,
        [input.userId, input.relayHostId, input.relayDeviceId]
      )
      const current = devices[0]
      if (input.expectedCurrentHash) {
        if (!current || !equalHash(string(current, 'current_hash'), input.expectedCurrentHash)) {
          throw new RelayStoreError('current_hash_mismatch')
        }
      }
      const currentVersion = current ? number(current, 'current_version') + 1 : 1
      const resumeExpiresAt = now + RELAY_PROTOCOL_LIMITS.resumeTtlMs
      const graceExpiresAt = current ? now + CREDENTIAL_GRACE_MS : undefined
      await transaction.query(
        `INSERT INTO relay_devices
         (user_id, relay_host_id, relay_device_id, current_hash, current_version,
          current_expires_at, grace_hash, grace_version, grace_expires_at, updated_at)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         ON CONFLICT (user_id, relay_host_id, relay_device_id) DO UPDATE SET
          current_hash = excluded.current_hash,
          current_version = excluded.current_version,
          current_expires_at = excluded.current_expires_at,
          grace_hash = excluded.grace_hash,
          grace_version = excluded.grace_version,
          grace_expires_at = excluded.grace_expires_at,
          revoked_at = NULL,
          updated_at = excluded.updated_at`,
        [
          input.userId, input.relayHostId, input.relayDeviceId, input.newResumeTokenHash,
          currentVersion, resumeExpiresAt, current ? string(current, 'current_hash') : null,
          current ? number(current, 'current_version') : null, graceExpiresAt, now
        ]
      )
      if (basisInviteHash) {
        await transaction.query(
          `UPDATE relay_invites SET state = ?, reservation_id = NULL,
           reservation_expires_at = NULL, updated_at = ? WHERE token_hash = ?`,
          ['consumed', now, basisInviteHash]
        )
      } else {
        await transaction.query(
          `UPDATE relay_invites SET state = ?, reservation_id = NULL,
           reservation_expires_at = NULL, updated_at = ?
           WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?
             AND state IN (?, ?, ?)`,
          [
            'invalidated', now, input.userId, input.relayHostId, input.relayDeviceId,
            'available', 'reserved', 'cooldown'
          ]
        )
      }
      await transaction.query(
        `UPDATE relay_direct_authorizations SET consumed_at = ?
         WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?
           AND consumed_at IS NULL`,
        [now, input.userId, input.relayHostId, input.relayDeviceId]
      )
      const result: DeviceCredentialInstalled = {
        v: 1,
        reqId: input.reqId,
        authorizationMode: input.authorization.mode,
        currentVersion,
        resumeExpiresAt,
        ...(graceExpiresAt === undefined ? {} : { graceExpiresAt })
      }
      await transaction.query(
        `INSERT INTO relay_install_results
         (user_id, relay_host_id, relay_device_id, req_id, authorization_mode,
          result_json, committed_at) VALUES (?, ?, ?, ?, ?, ?, ?)`,
        [
          input.userId, input.relayHostId, input.relayDeviceId, input.reqId,
          input.authorization.mode, JSON.stringify(result), now
        ]
      )
      await this.auditWith(transaction, {
        type: 'credential-installed',
        userId: input.userId,
        relayHostId: input.relayHostId,
        relayDeviceId: input.relayDeviceId,
        detail: { reqId: input.reqId, authorizationMode: input.authorization.mode, currentVersion }
      })
      return result
    })
  }

  async installStatus(input: RelayIdentity & {
    relayDeviceId: string
    reqId: string
  }): Promise<DeviceCredentialInstalled | null> {
    return await this.installStatusWith(this.database, input)
  }

  async confirmResume(input: RelayIdentity & {
    reqId: string
    basisConnId: string
    owningControlGeneration: number
  }): Promise<DeviceResumeConfirmed> {
    return await this.database.transaction(async (transaction) => {
      const prior = await transaction.query(
        `SELECT basis_conn_id, result_json FROM relay_confirm_results
         WHERE user_id = ? AND relay_host_id = ? AND req_id = ?`,
        [input.userId, input.relayHostId, input.reqId]
      )
      if (prior[0]) {
        if (string(prior[0], 'basis_conn_id') !== input.basisConnId) {
          throw new RelayStoreError('confirmation_tuple_mismatch')
        }
        return JSON.parse(string(prior[0], 'result_json')) as DeviceResumeConfirmed
      }
      const rows = await transaction.query(
        `SELECT * FROM relay_connection_bases WHERE basis_conn_id = ?`,
        [input.basisConnId]
      )
      const basis = rows[0]
      const now = this.now()
      if (
        !basis ||
        string(basis, 'user_id') !== input.userId ||
        string(basis, 'relay_host_id') !== input.relayHostId ||
        string(basis, 'credential_kind') !== 'resume' ||
        number(basis, 'owning_control_generation') !== input.owningControlGeneration ||
        number(basis, 'active') !== 1 ||
        number(basis, 'deadline') < now
      ) {
        throw new RelayStoreError('confirmation_not_active')
      }
      const relayDeviceId = string(basis, 'relay_device_id')
      await transaction.query(
        `UPDATE relay_devices SET updated_at = updated_at
         WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?`,
        [input.userId, input.relayHostId, relayDeviceId]
      )
      const devices = await transaction.query(
        `SELECT * FROM relay_devices
         WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?`,
        [input.userId, input.relayHostId, relayDeviceId]
      )
      const device = devices[0]
      if (!device) throw new RelayStoreError('credential_not_found')
      const acceptedVersion = number(basis, 'accepted_credential_version')
      const decision = decideResumeCommit(tokenFamily(device), acceptedVersion, now)
      if (decision.startsWith('reject-')) throw new RelayStoreError(decision)
      const renewed = decision === 'renew-current'
      const resumeExpiresAt = renewed
        ? now + RELAY_PROTOCOL_LIMITS.resumeTtlMs
        : number(device, 'current_expires_at')
      if (renewed) {
        await transaction.query(
          `UPDATE relay_devices SET current_expires_at = ?, updated_at = ?
           WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?`,
          [resumeExpiresAt, now, input.userId, input.relayHostId, relayDeviceId]
        )
      }
      const result: DeviceResumeConfirmed = {
        v: 1,
        reqId: input.reqId,
        currentVersion: number(device, 'current_version'),
        acceptedAs: string(basis, 'accepted_as') as 'current' | 'grace',
        renewed,
        resumeExpiresAt,
        ...(optionalNumber(device, 'grace_expires_at') === undefined
          ? {}
          : { graceExpiresAt: optionalNumber(device, 'grace_expires_at') })
      }
      await transaction.query(
        `INSERT INTO relay_confirm_results
         (user_id, relay_host_id, req_id, basis_conn_id, tuple_json, result_json, committed_at)
         VALUES (?, ?, ?, ?, ?, ?, ?)`,
        [
          input.userId, input.relayHostId, input.reqId, input.basisConnId,
          JSON.stringify({
            relayDeviceId,
            acceptedCredentialVersion: acceptedVersion,
            acceptedAs: result.acceptedAs,
            confirmDeadline: number(basis, 'deadline'),
            owningControlGeneration: input.owningControlGeneration
          }),
          JSON.stringify(result),
          now
        ]
      )
      await this.auditWith(transaction, {
        type: 'resume-confirmed',
        userId: input.userId,
        relayHostId: input.relayHostId,
        relayDeviceId,
        detail: { reqId: input.reqId, basisConnId: input.basisConnId, renewed }
      })
      return result
    })
  }

  // Memory confirm reads one device and renews at most daily; current-version replies always use renewed:true with stored expiry so phones schedule future renewals.
  async confirmMemoryResume(
    input: RelayIdentity & {
      reqId: string
      basisConnId: string
      relayDeviceId: string
      acceptedCredentialVersion: number
      acceptedAs: 'current' | 'grace'
    },
    options: { onRenewalFailure?: (error: unknown) => void } = {}
  ): Promise<DeviceResumeConfirmed> {
    const now = this.now()
    const devices = await this.database.query(
      `SELECT * FROM relay_devices
       WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?`,
      [input.userId, input.relayHostId, input.relayDeviceId]
    )
    const device = devices[0]
    if (!device) throw new RelayStoreError('credential_not_found')
    const decision = decideResumeCommit(tokenFamily(device), input.acceptedCredentialVersion, now)
    if (decision.startsWith('reject-')) throw new RelayStoreError(decision)
    const renewed = decision === 'renew-current'
    let resumeExpiresAt = number(device, 'current_expires_at')
    const renewalDue = resumeExpiresAt < now + RELAY_PROTOCOL_LIMITS.resumeTtlMs - RESUME_RENEWAL_INTERVAL_MS
    if (renewed && renewalDue) {
      // A failing renewal still answers the expiry the database holds, but must stay visible:
      // left failing, phones age toward re-pairing.
      resumeExpiresAt = await this.renewResume(input, device, now).catch((error: unknown) => {
        options.onRenewalFailure?.(error)
        return resumeExpiresAt
      })
    }
    this.resumeAudit.add({
      userId: input.userId,
      relayHostId: input.relayHostId,
      relayDeviceId: input.relayDeviceId,
      detail: { reqId: input.reqId, basisConnId: input.basisConnId, renewed }
    })
    return {
      v: 1,
      reqId: input.reqId,
      currentVersion: number(device, 'current_version'),
      acceptedAs: input.acceptedAs,
      renewed,
      resumeExpiresAt,
      ...(optionalNumber(device, 'grace_expires_at') === undefined
        ? {}
        : { graceExpiresAt: optionalNumber(device, 'grace_expires_at') })
    }
  }

  // Guard against revoke/install since the read; on no-op keep the expiry read, which the database still holds.
  private async renewResume(
    identity: RelayIdentity & { relayDeviceId: string },
    device: SqlRow,
    now: number
  ): Promise<number> {
    const renewedTo = now + RELAY_PROTOCOL_LIMITS.resumeTtlMs
    const rows = await this.database.query(
      `UPDATE relay_devices SET current_expires_at = ?, updated_at = ?
       WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?
         AND current_version = ? AND current_hash = ? AND revoked_at IS NULL
         AND current_expires_at < ?
       RETURNING current_expires_at`,
      [
        renewedTo, now, identity.userId, identity.relayHostId, identity.relayDeviceId,
        number(device, 'current_version'), string(device, 'current_hash'),
        now + RELAY_PROTOCOL_LIMITS.resumeTtlMs - RESUME_RENEWAL_INTERVAL_MS
      ]
    )
    return rows[0] ? number(rows[0], 'current_expires_at') : number(device, 'current_expires_at')
  }

  async deactivateBasis(basisConnId: string): Promise<void> {
    await this.database.query(`UPDATE relay_connection_bases SET active = ? WHERE basis_conn_id = ?`, [
      0,
      basisConnId
    ])
  }

  async revoke(identity: RelayIdentity, relayDeviceId: string): Promise<void> {
    await this.database.transaction(async (transaction) => {
      const now = this.now()
      await transaction.query(
        `UPDATE relay_devices SET revoked_at = ?, updated_at = ?
         WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?`,
        [now, now, identity.userId, identity.relayHostId, relayDeviceId]
      )
      await transaction.query(
        `UPDATE relay_invites SET state = ?, updated_at = ?
         WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ?`,
        ['invalidated', now, identity.userId, identity.relayHostId, relayDeviceId]
      )
      await this.auditWith(transaction, {
        type: 'device-revoked',
        ...identity,
        relayDeviceId,
        detail: {}
      })
    })
  }

  async resolveResume(
    relayHostId: string,
    token: string
  ): Promise<{ userId: string; relayDeviceId: string } | null> {
    const found = await this.lookupResume(relayHostId, token)
    return found.outcome === 'resume'
      ? { userId: found.reservation.userId, relayDeviceId: found.reservation.relayDeviceId }
      : null
  }

  async validateInviteForMove(relayHostId: string, token: string): Promise<boolean> {
    return Boolean(await this.resolveInviteForMove(relayHostId, token))
  }

  async resolveInviteForMove(
    relayHostId: string,
    token: string
  ): Promise<{ userId: string; relayDeviceId: string } | null> {
    const tokenHash = hashCredential(token)
    const rows = await this.database.query(
      `SELECT user_id, relay_device_id, token_hash, state, attempt_count, max_attempts, expires_at
       FROM relay_invites WHERE relay_host_id = ? AND token_hash = ?`,
      [relayHostId, tokenHash]
    )
    const invite = rows[0]
    const valid = Boolean(
      invite &&
        equalHash(string(invite, 'token_hash'), tokenHash) &&
        ['available', 'reserved', 'cooldown'].includes(string(invite, 'state')) &&
        number(invite, 'attempt_count') < number(invite, 'max_attempts') &&
        number(invite, 'expires_at') > this.now()
    )
    return valid && invite
      ? { userId: string(invite, 'user_id'), relayDeviceId: string(invite, 'relay_device_id') }
      : null
  }

  async consumeRate(input: {
    scopeKey: string
    kind: string
    limit: number
    windowMs: number
  }): Promise<void> {
    await this.database.transaction(async (transaction) => {
      await this.consumeRateWith(
        transaction,
        input.scopeKey,
        input.kind,
        input.limit,
        input.windowMs,
        this.now()
      )
    })
  }

  async cleanup(): Promise<void> {
    const now = this.now()
    await this.database.transaction(async (transaction) => {
      await transaction.query(
        `UPDATE relay_invites SET state = ?, reservation_id = NULL,
         reservation_expires_at = NULL, updated_at = ?
         WHERE expires_at <= ? AND state IN (?, ?, ?)`,
        ['expired', now, now, 'available', 'reserved', 'cooldown']
      )
      await transaction.query(
        `UPDATE relay_invites SET state = ?, reservation_id = NULL,
         reservation_expires_at = NULL, cooldown_until = ?, updated_at = ?
         WHERE state = ? AND reservation_expires_at <= ? AND expires_at > ?`,
        ['cooldown', now + RELAY_PROTOCOL_LIMITS.inviteAttemptCooldownMs, now, 'reserved', now, now]
      )
      await transaction.query(
        `UPDATE relay_connection_bases SET active = ? WHERE active = ? AND deadline <= ?`,
        [0, 1, now]
      )
      await transaction.query(
        `UPDATE relay_direct_authorizations SET consumed_at = ?
         WHERE consumed_at IS NULL AND deadline <= ?`,
        [now, now]
      )
      await transaction.query(
        `DELETE FROM relay_rate_windows WHERE window_started_at < ?`,
        [now - 24 * 60 * 60 * 1000]
      )
    })
    await this.reapSettledCredentials(now)
  }

  // Idempotent reaping stays outside transition transaction or locks last across unrelated batch deletes.
  private async reapSettledCredentials(now: number): Promise<void> {
    await this.reapUnindexed(
      'relay_invites',
      'state IN (?, ?, ?) AND updated_at <= ?',
      ['expired', 'consumed', 'invalidated', now - TERMINAL_INVITE_RETENTION_MS],
      now
    )
    // Use indexed active/deadline range to avoid scanning 1.5GB drained heap; both readers reject expired deadlines regardless of flag, so one-day-old bases are unusable.
    await this.reapBatch('relay_connection_bases', 'active = ? AND deadline <= ?', [
      0,
      now - INACTIVE_AUTHORIZATION_RETENTION_MS
    ])
    // consumed_at, not deadline: consumption is what settles this row, and it can happen well
    // before the deadline, so measuring from it retains the row for the full window either way.
    await this.reapUnindexed(
      'relay_direct_authorizations',
      'consumed_at IS NOT NULL AND consumed_at <= ?',
      [now - INACTIVE_AUTHORIZATION_RETENTION_MS],
      now
    )
    await this.confirmResultReaper.reap(this.database, [now - CONFIRM_RESULT_RETENTION_MS])
    // Ordered so the plan walks relay_audit_events_at from its oldest entry: unordered, a LIMIT
    // can plan as a sequential scan that rereads the retained rows before reaching the old ones.
    await this.reapBatch('relay_audit_events', 'at <= ?', [now - AUDIT_EVENT_RETENTION_MS], 'at')
  }

  // Paused before the delete, so an overlapping or failed reap waits too; only a full batch (a backlog) clears it.
  private async reapUnindexed(
    table: string,
    predicate: string,
    params: unknown[],
    now: number
  ): Promise<void> {
    if (now < (this.unindexedReapResumesAt.get(table) ?? 0)) {
      return
    }
    this.unindexedReapResumesAt.set(table, now + UNINDEXED_REAP_PAUSE_MS)
    if ((await this.reapBatch(table, predicate, params)) >= REAP_BATCH_ROWS) {
      this.unindexedReapResumesAt.delete(table)
    }
  }

  // Delete located physical ctid/rowid; PostgreSQL ANY(TID array) guarantees TID scan, while IN can hash-join a full heap scan.
  private async reapBatch(
    table: string,
    predicate: string,
    params: unknown[],
    orderBy?: string
  ): Promise<number> {
    const sqlite = this.database.dialect === 'sqlite'
    const address = sqlite ? 'rowid' : 'ctid'
    const order = orderBy ? `ORDER BY ${orderBy} ` : ''
    const batch = `SELECT ${address} FROM ${table} WHERE ${predicate} ${order}LIMIT ${REAP_BATCH_ROWS}`
    const rows = await this.database.query(
      sqlite
        ? `DELETE FROM ${table} WHERE rowid IN (${batch})`
        : `DELETE FROM ${table} WHERE ctid = ANY(ARRAY(${batch}))`,
      params
    )
    return changes(rows)
  }

  private async installStatusWith(
    database: RelayDatabase,
    input: RelayIdentity & { relayDeviceId: string; reqId: string }
  ): Promise<DeviceCredentialInstalled | null> {
    const rows = await database.query(
      `SELECT result_json FROM relay_install_results
       WHERE user_id = ? AND relay_host_id = ? AND relay_device_id = ? AND req_id = ?`,
      [input.userId, input.relayHostId, input.relayDeviceId, input.reqId]
    )
    return rows[0] ? (JSON.parse(string(rows[0], 'result_json')) as DeviceCredentialInstalled) : null
  }

  private async validateInstallAuthorization(
    transaction: RelayDatabase,
    input: InstallInput,
    now: number
  ): Promise<string | null> {
    if (input.authorization.mode === 'relay-basis') {
      const rows = await transaction.query(
        `SELECT * FROM relay_connection_bases WHERE basis_conn_id = ?`,
        [input.authorization.basisConnId]
      )
      const basis = rows[0]
      if (
        !basis ||
        string(basis, 'user_id') !== input.userId ||
        string(basis, 'relay_host_id') !== input.relayHostId ||
        string(basis, 'relay_device_id') !== input.relayDeviceId ||
        string(basis, 'credential_kind') !== 'invite' ||
        number(basis, 'owning_control_generation') !== input.owningControlGeneration ||
        number(basis, 'active') !== 1 ||
        number(basis, 'deadline') < now
      ) {
        throw new RelayStoreError('invalid_relay_basis')
      }
      return string(basis, 'invite_token_hash')
    }
    const rows = await transaction.query(
      `SELECT * FROM relay_direct_authorizations WHERE direct_auth_id = ?`,
      [input.authorization.directAuthId]
    )
    const direct = rows[0]
    if (
      !direct ||
      string(direct, 'user_id') !== input.userId ||
      string(direct, 'relay_host_id') !== input.relayHostId ||
      string(direct, 'relay_device_id') !== input.relayDeviceId ||
      number(direct, 'owning_control_generation') !== input.owningControlGeneration ||
      number(direct, 'deadline') < now ||
      optionalNumber(direct, 'consumed_at') !== undefined
    ) {
      throw new RelayStoreError('invalid_direct_authorization')
    }
    await transaction.query(
      `UPDATE relay_direct_authorizations SET consumed_at = ? WHERE direct_auth_id = ?`,
      [now, input.authorization.directAuthId]
    )
    return null
  }

  private async consumeRateWith(
    transaction: RelayDatabase,
    scopeKey: string,
    kind: string,
    limit: number,
    windowMs: number,
    now: number
  ): Promise<void> {
    const windowStartedAt = Math.floor(now / windowMs) * windowMs
    const rows = await transaction.query(
      `INSERT INTO relay_rate_windows
       (scope_key, window_kind, window_started_at, count) VALUES (?, ?, ?, ?)
       ON CONFLICT (scope_key, window_kind, window_started_at) DO UPDATE
       SET count = relay_rate_windows.count + 1 RETURNING count`,
      [scopeKey, kind, windowStartedAt, 1]
    )
    if (number(rows[0]!, 'count') > limit) throw new RelayStoreError('rate_limit_exceeded')
  }

  private async auditWith(
    transaction: RelayDatabase,
    event: RelayIdentity & {
      type: string
      relayDeviceId?: string
      detail: Record<string, unknown>
    }
  ): Promise<void> {
    await transaction.query(
      `INSERT INTO relay_audit_events
       (id, at, type, user_id, relay_host_id, relay_device_id, detail_json)
       VALUES (?, ?, ?, ?, ?, ?, ?)`,
      [
        randomUUID(), this.now(), event.type, event.userId, event.relayHostId,
        event.relayDeviceId, JSON.stringify(event.detail)
      ]
    )
  }
}