@shipfox/api-auth 19.0.0 → 20.0.0

package/src/db/agent-access.ts

@@ -1,4 +1,5 @@
-import {and, asc, eq, gt, inArray, isNull, lt, or, sql} from 'drizzle-orm';
+import {and, asc, eq, gt, inArray, isNotNull, isNull, lte, notExists, or, sql} from 'drizzle-orm';
+import {config} from '#config.js';
 import type {
   AgentAuthorizationCode,
   AgentAuthorizationRequest,
@@ -7,6 +8,14 @@ import type {
   AgentPersonalAccessToken,
   AgentRefreshToken,
 } from '#core/entities/agent-access.js';
+import {
+  AGENT_ACCESS_RETENTION_TIMEOUT_MARGIN_MS,
+  AGENT_AUTHORIZATION_RETENTION_DAYS,
+  AGENT_CLIENT_RETENTION_DAYS,
+  AGENT_GRANT_RETENTION_DAYS,
+  AGENT_PAT_RETENTION_DAYS,
+  AGENT_REFRESH_TOKEN_RETENTION_DAYS,
+} from './agent-access-retention.js';
 import {db} from './db.js';
 import {
   agentAuthorizationCodes,
@@ -22,11 +31,124 @@ import {
   toAgentPersonalAccessToken,
   toAgentRefreshToken,
 } from './schema/agent-access.js';
+import {users} from './schema/users.js';
 
 export type AgentAccessTx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
 
 type AgentAccessExecutor = ReturnType<typeof db> | AgentAccessTx;
 
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+const MILLISECONDS_PER_SECOND = 1000;
+
+function retentionCutoff(now: Date, days: number): Date {
+  if (!Number.isFinite(days) || days < 0) {
+    throw new Error('Agent-access retention must be a non-negative finite number of days');
+  }
+  return new Date(now.getTime() - days * MILLISECONDS_PER_DAY);
+}
+
+function batchLimit(limit: number | undefined): number {
+  const value = limit ?? 1000;
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error('Agent-access batch limit must be a positive integer');
+  }
+  return value;
+}
+
+class AgentAccessRetentionDeadlineExceededError extends Error {
+  readonly code = '57014';
+
+  constructor() {
+    super('Agent-access retention deadline exceeded');
+    this.name = 'AgentAccessRetentionDeadlineExceededError';
+  }
+}
+
+function retentionStatementTimeoutMs(deadlineMs: number): number {
+  if (!Number.isFinite(deadlineMs)) {
+    throw new Error('Agent-access retention deadline must be a finite timestamp');
+  }
+  const remainingMs = Math.floor(
+    deadlineMs - Date.now() - AGENT_ACCESS_RETENTION_TIMEOUT_MARGIN_MS,
+  );
+  if (remainingMs < 1) throw new AgentAccessRetentionDeadlineExceededError();
+  return remainingMs;
+}
+
+async function prepareAgentAccessRetentionStatement(
+  tx: AgentAccessTx,
+  deadlineMs: number | undefined,
+): Promise<void> {
+  if (deadlineMs === undefined) return;
+  const timeout = `${retentionStatementTimeoutMs(deadlineMs)}ms`;
+  await tx.execute(
+    sql`select set_config('statement_timeout', ${timeout}, true), set_config('lock_timeout', ${timeout}, true)`,
+  );
+}
+
+async function requireActiveAgentGrant(tx: AgentAccessTx, grantId: string): Promise<AgentGrant> {
+  const grant = await lockAgentGrant(tx, {grantId});
+  if (!grant) throw new Error(`Agent grant ${grantId} was not found`);
+  if (grant.revokedAt || grant.terminalAt) {
+    throw new Error(`Agent grant ${grantId} is no longer active`);
+  }
+  return grant;
+}
+
+async function isActiveUser(tx: AgentAccessTx, userId: string): Promise<boolean> {
+  const rows = await tx
+    .select({id: users.id})
+    .from(users)
+    .where(and(eq(users.id, userId), eq(users.status, 'active')))
+    .limit(1);
+  return rows.length > 0;
+}
+
+async function lockAgentClient(
+  tx: AgentAccessTx,
+  clientId: string,
+): Promise<AgentClient | undefined> {
+  const rows = await tx
+    .select()
+    .from(agentClients)
+    .where(eq(agentClients.id, clientId))
+    .for('update')
+    .limit(1);
+  const row = rows[0];
+  return row ? toAgentClient(row) : undefined;
+}
+
+function validateRotationGraceSeconds(graceSeconds: number): number {
+  if (!Number.isFinite(graceSeconds) || graceSeconds < 0) {
+    throw new Error('Agent refresh rotation grace must be a non-negative finite number of seconds');
+  }
+  return graceSeconds;
+}
+
+/** Returns the default sliding lifetime for a newly issued agent refresh token. */
+export function agentRefreshTokenExpiresAt(now: Date = new Date()): Date {
+  return new Date(now.getTime() + config.AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS * MILLISECONDS_PER_DAY);
+}
+
+/**
+ * A rotated token remains usable for an access-token-only grace response. The
+ * row must still exist; pruning deliberately turns later replays into plain
+ * unknown-token responses.
+ */
+export function isWithinAgentRefreshRotationGrace(params: {
+  rotatedAt: Date | null;
+  now?: Date;
+  graceSeconds?: number | undefined;
+}): boolean {
+  if (!params.rotatedAt) return false;
+  const now = params.now ?? new Date();
+  const graceSeconds = validateRotationGraceSeconds(
+    params.graceSeconds ?? config.AUTH_REFRESH_ROTATION_GRACE_SECONDS,
+  );
+  const elapsedMs = now.getTime() - params.rotatedAt.getTime();
+  return elapsedMs >= 0 && elapsedMs <= graceSeconds * MILLISECONDS_PER_SECOND;
+}
+
 export interface CreateAgentClientParams {
   clientId: string;
   name: string;
@@ -59,6 +181,42 @@ export async function createAgentClientTx(
   return toAgentClient(row);
 }
 
+export interface UpsertCimdAgentClientParams {
+  clientId: string;
+  name: string;
+  redirectUris: string[];
+}
+
+/**
+ * Stores the latest validated CIMD identity. The generic client upsert above
+ * intentionally preserves registration metadata; CIMD documents are the
+ * source of truth and therefore use this explicit update path.
+ */
+export async function upsertCimdAgentClient(
+  params: UpsertCimdAgentClientParams,
+): Promise<AgentClient> {
+  return await db().transaction(async (tx) => {
+    const rows = await tx
+      .insert(agentClients)
+      .values({...params, kind: 'cimd'})
+      .onConflictDoUpdate({
+        target: agentClients.clientId,
+        set: {
+          name: params.name,
+          redirectUris: params.redirectUris,
+          kind: 'cimd',
+          lastSeenAt: sql`now()`,
+          unreferencedAt: null,
+          updatedAt: sql`now()`,
+        },
+      })
+      .returning();
+    const row = rows[0];
+    if (!row) throw new Error('CIMD client upsert returned no row');
+    return toAgentClient(row);
+  });
+}
+
 export async function findAgentClientByClientId(params: {
   clientId: string;
   executor?: AgentAccessExecutor;
@@ -90,7 +248,17 @@ export async function markAgentClientUnreferenced(
   await tx
     .update(agentClients)
     .set({unreferencedAt: sql`now()`, updatedAt: sql`now()`})
-    .where(eq(agentClients.id, params.clientUuid));
+    .where(
+      and(
+        eq(agentClients.id, params.clientUuid),
+        notExists(
+          tx
+            .select({id: agentGrants.id})
+            .from(agentGrants)
+            .where(eq(agentGrants.clientId, params.clientUuid)),
+        ),
+      ),
+    );
 }
 
 export interface CreateAgentAuthorizationRequestParams {
@@ -114,6 +282,9 @@ export async function createAgentAuthorizationRequestTx(
   tx: AgentAccessTx,
   params: CreateAgentAuthorizationRequestParams,
 ): Promise<AgentAuthorizationRequest> {
+  if (!(await lockAgentClient(tx, params.clientId))) {
+    throw new Error(`Agent client ${params.clientId} was not found`);
+  }
   const rows = await tx.insert(agentAuthorizationRequests).values(params).returning();
   const row = rows[0];
   if (!row) throw new Error('Insert returned no rows');
@@ -182,10 +353,19 @@ export async function createAgentGrant(params: CreateAgentGrantParams): Promise<
   return await db().transaction((tx) => createAgentGrantTx(tx, params));
 }
 
+/**
+ * Creates or reauthorizes a grant while holding its client row lock. A newly
+ * created grant has no live child until its first authorization code or refresh
+ * token is issued, so approval callers must compose that first child creation
+ * with this Tx helper in one database transaction.
+ */
 export async function createAgentGrantTx(
   tx: AgentAccessTx,
   params: CreateAgentGrantParams,
 ): Promise<AgentGrant> {
+  if (!(await lockAgentClient(tx, params.clientId))) {
+    throw new Error(`Agent client ${params.clientId} was not found`);
+  }
   const rows = await tx
     .insert(agentGrants)
     .values(params)
@@ -271,6 +451,7 @@ export async function createAgentAuthorizationCodeTx(
   tx: AgentAccessTx,
   params: CreateAgentAuthorizationCodeParams,
 ): Promise<AgentAuthorizationCode> {
+  await requireActiveAgentGrant(tx, params.grantId);
   const rows = await tx.insert(agentAuthorizationCodes).values(params).returning();
   const row = rows[0];
   if (!row) throw new Error('Insert returned no rows');
@@ -322,11 +503,27 @@ export async function consumeAgentAuthorizationCodeTx(
   tx: AgentAccessTx,
   params: {hashedCode: string},
 ): Promise<AgentAuthorizationCode | undefined> {
+  // Read the binding before taking the grant lock. The conditional update below
+  // re-checks consumed_at and expiry after the lock, so concurrent exchanges
+  // still have exactly one winner even when both read the code first.
+  const existingRows = await tx
+    .select()
+    .from(agentAuthorizationCodes)
+    .where(eq(agentAuthorizationCodes.hashedCode, params.hashedCode))
+    .limit(1);
+  const existing = existingRows[0];
+  if (!existing) return undefined;
+
+  const grant = await lockAgentGrant(tx, {grantId: existing.grantId});
+  if (!grant || grant.revokedAt || grant.terminalAt) return undefined;
+  if (!(await isActiveUser(tx, grant.userId))) return undefined;
+
   const rows = await tx
     .update(agentAuthorizationCodes)
     .set({consumedAt: sql`now()`, updatedAt: sql`now()`})
     .where(
       and(
+        eq(agentAuthorizationCodes.id, existing.id),
         eq(agentAuthorizationCodes.hashedCode, params.hashedCode),
         isNull(agentAuthorizationCodes.consumedAt),
         gt(agentAuthorizationCodes.expiresAt, sql`now()`),
@@ -340,7 +537,8 @@ export async function consumeAgentAuthorizationCodeTx(
 export interface CreateAgentRefreshTokenParams {
   grantId: string;
   hashedToken: string;
-  expiresAt: Date;
+  /** Defaults to the configured 14-day lifetime. */
+  expiresAt?: Date;
 }
 
 export async function createAgentRefreshToken(
@@ -353,7 +551,11 @@ export async function createAgentRefreshTokenTx(
   tx: AgentAccessTx,
   params: CreateAgentRefreshTokenParams,
 ): Promise<AgentRefreshToken> {
-  const rows = await tx.insert(agentRefreshTokens).values(params).returning();
+  await requireActiveAgentGrant(tx, params.grantId);
+  const rows = await tx
+    .insert(agentRefreshTokens)
+    .values({...params, expiresAt: params.expiresAt ?? agentRefreshTokenExpiresAt()})
+    .returning();
   const row = rows[0];
   if (!row) throw new Error('Insert returned no rows');
   return toAgentRefreshToken(row);
@@ -367,7 +569,12 @@ export async function findAgentRefreshTokenByHash(params: {
   const rows = await executor
     .select()
     .from(agentRefreshTokens)
-    .where(eq(agentRefreshTokens.hashedToken, params.hashedToken))
+    .where(
+      and(
+        eq(agentRefreshTokens.hashedToken, params.hashedToken),
+        isNull(agentRefreshTokens.revokedAt),
+      ),
+    )
     .limit(1);
   const row = rows[0];
   return row ? toAgentRefreshToken(row) : undefined;
@@ -394,11 +601,133 @@ export async function findActiveAgentRefreshTokenByHash(params: {
   return row ? toAgentRefreshToken(row) : undefined;
 }
 
+/** Finds the one live refresh token currently attached to a grant. */
+export async function findActiveAgentRefreshTokenByGrantId(params: {
+  grantId: string;
+  executor?: AgentAccessExecutor;
+}): Promise<AgentRefreshToken | undefined> {
+  const executor = params.executor ?? db();
+  const rows = await executor
+    .select()
+    .from(agentRefreshTokens)
+    .where(
+      and(
+        eq(agentRefreshTokens.grantId, params.grantId),
+        isNull(agentRefreshTokens.rotatedAt),
+        isNull(agentRefreshTokens.revokedAt),
+        gt(agentRefreshTokens.expiresAt, sql`now()`),
+      ),
+    )
+    .limit(1);
+  const row = rows[0];
+  return row ? toAgentRefreshToken(row) : undefined;
+}
+
+export type AgentRefreshTokenReplayResult =
+  | {
+      kind: 'grace';
+      grant: AgentGrant;
+      predecessor: AgentRefreshToken;
+      successor: AgentRefreshToken;
+    }
+  | {
+      kind: 'reused';
+      grant: AgentGrant;
+      predecessor: AgentRefreshToken;
+    };
+
+/**
+ * Resolves a replay of a retained, rotated token. A grace hit returns the one
+ * live successor so the caller can mint an access token without issuing a new
+ * refresh cookie. A replay after grace revokes the complete grant family.
+ * Missing or pruned rows return undefined and therefore remain plain 401s.
+ */
+export async function resolveAgentRefreshTokenReplay(params: {
+  hashedToken: string;
+  now?: Date;
+  graceSeconds?: number;
+}): Promise<AgentRefreshTokenReplayResult | undefined> {
+  return await db().transaction((tx) => resolveAgentRefreshTokenReplayTx(tx, params));
+}
+
+export async function resolveAgentRefreshTokenReplayTx(
+  tx: AgentAccessTx,
+  params: {
+    hashedToken: string;
+    now?: Date;
+    graceSeconds?: number;
+  },
+): Promise<AgentRefreshTokenReplayResult | undefined> {
+  const rows = await tx
+    .select()
+    .from(agentRefreshTokens)
+    .where(
+      and(
+        eq(agentRefreshTokens.hashedToken, params.hashedToken),
+        isNull(agentRefreshTokens.revokedAt),
+      ),
+    )
+    .limit(1);
+  const existing = rows[0];
+  if (!existing) return undefined;
+
+  const grant = await lockAgentGrant(tx, {grantId: existing.grantId});
+  if (!grant || grant.revokedAt || grant.terminalAt) return undefined;
+  if (!(await isActiveUser(tx, grant.userId))) return undefined;
+
+  const currentRows = await tx
+    .select()
+    .from(agentRefreshTokens)
+    .where(and(eq(agentRefreshTokens.id, existing.id), isNull(agentRefreshTokens.revokedAt)))
+    .limit(1);
+  const current = currentRows[0];
+  if (!current?.rotatedAt) return undefined;
+
+  const now = params.now ?? new Date();
+  if (
+    isWithinAgentRefreshRotationGrace({
+      rotatedAt: current.rotatedAt,
+      now,
+      graceSeconds: params.graceSeconds,
+    })
+  ) {
+    const successorRows = await tx
+      .select()
+      .from(agentRefreshTokens)
+      .where(
+        and(
+          eq(agentRefreshTokens.grantId, current.grantId),
+          isNull(agentRefreshTokens.rotatedAt),
+          isNull(agentRefreshTokens.revokedAt),
+          gt(agentRefreshTokens.expiresAt, now),
+        ),
+      )
+      .limit(1);
+    const successor = successorRows[0];
+    if (!successor) return undefined;
+    return {
+      kind: 'grace',
+      grant,
+      predecessor: toAgentRefreshToken(current),
+      successor: toAgentRefreshToken(successor),
+    };
+  }
+
+  const revokedGrant = await revokeAgentGrantTx(tx, {grantId: current.grantId});
+  if (!revokedGrant) return undefined;
+  return {
+    kind: 'reused',
+    grant: revokedGrant,
+    predecessor: toAgentRefreshToken(current),
+  };
+}
+
 /** Rotates a refresh token atomically; a concurrent rotation cannot win twice. */
 export async function rotateAgentRefreshToken(params: {
   hashedToken: string;
   replacementHashedToken: string;
-  replacementExpiresAt: Date;
+  /** Defaults to the configured 14-day sliding lifetime. */
+  replacementExpiresAt?: Date;
 }): Promise<AgentRefreshToken | undefined> {
   return await db().transaction((tx) => rotateAgentRefreshTokenTx(tx, params));
 }
@@ -408,14 +737,33 @@ export async function rotateAgentRefreshTokenTx(
   params: {
     hashedToken: string;
     replacementHashedToken: string;
-    replacementExpiresAt: Date;
+    replacementExpiresAt?: Date;
   },
 ): Promise<AgentRefreshToken | undefined> {
+  const replacementExpiresAt = params.replacementExpiresAt ?? agentRefreshTokenExpiresAt();
+  const existingRows = await tx
+    .select()
+    .from(agentRefreshTokens)
+    .where(
+      and(
+        eq(agentRefreshTokens.hashedToken, params.hashedToken),
+        isNull(agentRefreshTokens.revokedAt),
+      ),
+    )
+    .limit(1);
+  const existing = existingRows[0];
+  if (!existing) return undefined;
+
+  const grant = await lockAgentGrant(tx, {grantId: existing.grantId});
+  if (!grant || grant.revokedAt || grant.terminalAt) return undefined;
+  if (!(await isActiveUser(tx, grant.userId))) return undefined;
+
   const rows = await tx
     .update(agentRefreshTokens)
     .set({rotatedAt: sql`now()`, lastUsedAt: sql`now()`, updatedAt: sql`now()`})
     .where(
       and(
+        eq(agentRefreshTokens.id, existing.id),
         eq(agentRefreshTokens.hashedToken, params.hashedToken),
         isNull(agentRefreshTokens.rotatedAt),
         isNull(agentRefreshTokens.revokedAt),
@@ -426,17 +774,38 @@ export async function rotateAgentRefreshTokenTx(
   const row = rows[0];
   if (!row) return undefined;
 
-  return await createAgentRefreshTokenTx(tx, {
-    grantId: row.grantId,
-    hashedToken: params.replacementHashedToken,
-    expiresAt: params.replacementExpiresAt,
-  });
+  await tx
+    .update(agentGrants)
+    .set({lastUsedAt: sql`now()`, updatedAt: sql`now()`})
+    .where(eq(agentGrants.id, row.grantId));
+
+  const successorRows = await tx
+    .insert(agentRefreshTokens)
+    .values({
+      grantId: row.grantId,
+      hashedToken: params.replacementHashedToken,
+      expiresAt: replacementExpiresAt,
+    })
+    .returning();
+  const successor = successorRows[0];
+  if (!successor) throw new Error('Insert returned no rows');
+  return toAgentRefreshToken(successor);
 }
 
 export async function revokeAgentRefreshToken(params: {
   id: string;
 }): Promise<AgentRefreshToken | undefined> {
   return await db().transaction(async (tx) => {
+    const existingRows = await tx
+      .select()
+      .from(agentRefreshTokens)
+      .where(eq(agentRefreshTokens.id, params.id))
+      .limit(1);
+    const existing = existingRows[0];
+    if (!existing) return undefined;
+    const grant = await lockAgentGrant(tx, {grantId: existing.grantId});
+    if (!grant) return undefined;
+
     const rows = await tx
       .update(agentRefreshTokens)
       .set({revokedAt: sql`now()`, updatedAt: sql`now()`})
@@ -447,6 +816,148 @@ export async function revokeAgentRefreshToken(params: {
   });
 }
 
+/** Revokes a grant and every refresh-token generation in its family. */
+export async function revokeAgentGrant(params: {grantId: string}): Promise<AgentGrant | undefined> {
+  return await db().transaction((tx) => revokeAgentGrantTx(tx, params));
+}
+
+export async function revokeAgentGrantTx(
+  tx: AgentAccessTx,
+  params: {grantId: string},
+): Promise<AgentGrant | undefined> {
+  const grant = await lockAgentGrant(tx, params);
+  if (!grant) return undefined;
+
+  const rows = await tx
+    .update(agentGrants)
+    .set({
+      revokedAt: grant.revokedAt ?? sql`now()`,
+      terminalAt: grant.terminalAt ?? sql`now()`,
+      updatedAt: sql`now()`,
+    })
+    .where(eq(agentGrants.id, grant.id))
+    .returning();
+  const updatedGrant = rows[0];
+  if (!updatedGrant) return undefined;
+
+  await tx
+    .update(agentRefreshTokens)
+    .set({revokedAt: sql`now()`, updatedAt: sql`now()`})
+    .where(and(eq(agentRefreshTokens.grantId, grant.id), isNull(agentRefreshTokens.revokedAt)));
+
+  return toAgentGrant(updatedGrant);
+}
+
+export interface TransitionAgentGrantsToTerminalParams {
+  limit?: number;
+  now?: Date;
+  deadlineMs?: number | undefined;
+}
+
+/**
+ * Marks grants terminal once they have no usable refresh token or authorization
+ * code left. Each candidate is locked before its children are inspected so a
+ * concurrent code exchange or token rotation cannot create a live child after
+ * the decision.
+ */
+export async function transitionAgentGrantsToTerminal(
+  params: TransitionAgentGrantsToTerminalParams = {},
+): Promise<number> {
+  return await db().transaction((tx) => transitionAgentGrantsToTerminalTx(tx, params));
+}
+
+export async function transitionAgentGrantsToTerminalTx(
+  tx: AgentAccessTx,
+  params: TransitionAgentGrantsToTerminalParams = {},
+): Promise<number> {
+  const limit = batchLimit(params.limit);
+  const now = params.now ?? new Date();
+  const liveRefreshTokens = tx
+    .select({id: agentRefreshTokens.id})
+    .from(agentRefreshTokens)
+    .where(
+      and(
+        eq(agentRefreshTokens.grantId, agentGrants.id),
+        isNull(agentRefreshTokens.rotatedAt),
+        isNull(agentRefreshTokens.revokedAt),
+        gt(agentRefreshTokens.expiresAt, now),
+      ),
+    );
+  const liveAuthorizationCodes = tx
+    .select({id: agentAuthorizationCodes.id})
+    .from(agentAuthorizationCodes)
+    .where(
+      and(
+        eq(agentAuthorizationCodes.grantId, agentGrants.id),
+        isNull(agentAuthorizationCodes.consumedAt),
+        gt(agentAuthorizationCodes.expiresAt, now),
+      ),
+    );
+  await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+  const candidates = await tx
+    .select({id: agentGrants.id})
+    .from(agentGrants)
+    .where(
+      and(
+        isNull(agentGrants.terminalAt),
+        or(
+          isNotNull(agentGrants.revokedAt),
+          and(notExists(liveRefreshTokens), notExists(liveAuthorizationCodes)),
+        ),
+      ),
+    )
+    .orderBy(asc(agentGrants.createdAt), asc(agentGrants.id))
+    .limit(limit);
+
+  let transitioned = 0;
+  for (const candidate of candidates) {
+    await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+    const grant = await lockAgentGrant(tx, {grantId: candidate.id});
+    if (!grant || grant.terminalAt) continue;
+
+    if (!grant.revokedAt) {
+      await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+      const liveRefreshTokens = await tx
+        .select({id: agentRefreshTokens.id})
+        .from(agentRefreshTokens)
+        .where(
+          and(
+            eq(agentRefreshTokens.grantId, grant.id),
+            isNull(agentRefreshTokens.rotatedAt),
+            isNull(agentRefreshTokens.revokedAt),
+            gt(agentRefreshTokens.expiresAt, now),
+          ),
+        )
+        .limit(1);
+      if (liveRefreshTokens.length > 0) continue;
+
+      await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+      const liveAuthorizationCodes = await tx
+        .select({id: agentAuthorizationCodes.id})
+        .from(agentAuthorizationCodes)
+        .where(
+          and(
+            eq(agentAuthorizationCodes.grantId, grant.id),
+            isNull(agentAuthorizationCodes.consumedAt),
+            gt(agentAuthorizationCodes.expiresAt, now),
+          ),
+        )
+        .limit(1);
+      if (liveAuthorizationCodes.length > 0) continue;
+    }
+
+    await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+    const rows = await tx
+      .update(agentGrants)
+      .set({terminalAt: now, updatedAt: now})
+      .where(and(eq(agentGrants.id, grant.id), isNull(agentGrants.terminalAt)))
+      .returning({id: agentGrants.id});
+    if (rows.length > 0) transitioned += 1;
+  }
+
+  return transitioned;
+}
+
 export interface CreateAgentPersonalAccessTokenParams {
   userId: string;
   workspaceId: string;
@@ -493,30 +1004,68 @@ export async function findActiveAgentPersonalAccessTokenByHash(params: {
 }): Promise<AgentPersonalAccessToken | undefined> {
   const executor = params.executor ?? db();
   const rows = await executor
-    .select()
+    .select({token: agentPersonalAccessTokens})
     .from(agentPersonalAccessTokens)
+    .innerJoin(users, eq(agentPersonalAccessTokens.userId, users.id))
     .where(
       and(
         eq(agentPersonalAccessTokens.hashedToken, params.hashedToken),
         isNull(agentPersonalAccessTokens.revokedAt),
         gt(agentPersonalAccessTokens.expiresAt, sql`now()`),
+        eq(users.status, 'active'),
       ),
     )
     .limit(1);
-  const row = rows[0];
+  const row = rows[0]?.token;
   return row ? toAgentPersonalAccessToken(row) : undefined;
 }
 
 export async function markAgentPersonalAccessTokenUsed(params: {
   id: string;
+  throttleSeconds?: number;
 }): Promise<AgentPersonalAccessToken | undefined> {
+  const throttleSeconds = params.throttleSeconds ?? 60;
+  if (!Number.isFinite(throttleSeconds) || throttleSeconds < 0) {
+    throw new Error('PAT last-used throttle must be a non-negative finite number of seconds');
+  }
+
   const rows = await db()
     .update(agentPersonalAccessTokens)
     .set({lastUsedAt: sql`now()`, updatedAt: sql`now()`})
-    .where(eq(agentPersonalAccessTokens.id, params.id))
+    .where(
+      and(
+        eq(agentPersonalAccessTokens.id, params.id),
+        isNull(agentPersonalAccessTokens.revokedAt),
+        gt(agentPersonalAccessTokens.expiresAt, sql`now()`),
+        or(
+          isNull(agentPersonalAccessTokens.lastUsedAt),
+          lte(
+            agentPersonalAccessTokens.lastUsedAt,
+            sql`now() - (${throttleSeconds} || ' seconds')::interval`,
+          ),
+        ),
+      ),
+    )
     .returning();
   const row = rows[0];
-  return row ? toAgentPersonalAccessToken(row) : undefined;
+  if (row) return toAgentPersonalAccessToken(row);
+
+  // A valid token can intentionally skip the write inside the throttle
+  // window. Return its current row so callers can distinguish that from an
+  // invalid, expired, or revoked token.
+  const existingRows = await db()
+    .select()
+    .from(agentPersonalAccessTokens)
+    .where(
+      and(
+        eq(agentPersonalAccessTokens.id, params.id),
+        isNull(agentPersonalAccessTokens.revokedAt),
+        gt(agentPersonalAccessTokens.expiresAt, sql`now()`),
+      ),
+    )
+    .limit(1);
+  const existing = existingRows[0];
+  return existing ? toAgentPersonalAccessToken(existing) : undefined;
 }
 
 export async function revokeAgentPersonalAccessToken(params: {
@@ -534,96 +1083,409 @@ export async function revokeAgentPersonalAccessToken(params: {
 }
 
 export interface PruneAgentAccessParams {
+  /** Overrides every retention horizon for deterministic maintenance tests. */
   retentionDays?: number;
   limit?: number;
   now?: Date;
+  /** Absolute epoch deadline used to bound every PostgreSQL statement. */
+  deadlineMs?: number;
 }
 
-/** Deletes terminal credentials and ephemeral authorization rows in bounded batches. */
-export async function pruneAgentAccess(params: PruneAgentAccessParams = {}): Promise<number> {
-  const now = params.now ?? new Date();
-  const retentionDays = params.retentionDays ?? 7;
-  const limit = params.limit ?? 1000;
-  const cutoff = new Date(now.getTime() - retentionDays * 24 * 60 * 60 * 1000);
+export interface PruneAgentAccessResult {
+  deleted: number;
+  transitioned: number;
+}
 
-  return await db().transaction(async (tx) => {
-    const requestIds = tx
-      .select({id: agentAuthorizationRequests.id})
-      .from(agentAuthorizationRequests)
-      .where(
-        or(
-          lt(agentAuthorizationRequests.consumedAt, cutoff),
-          and(
-            isNull(agentAuthorizationRequests.consumedAt),
-            lt(agentAuthorizationRequests.expiresAt, cutoff),
-          ),
+interface AgentAccessRetentionCutoffs {
+  authorization: Date;
+  refreshToken: Date;
+  grant: Date;
+  pat: Date;
+  client: Date;
+}
+
+async function deleteExpiredAgentAuthorizationRequests(
+  tx: AgentAccessTx,
+  cutoff: Date,
+  limit: number,
+  deadlineMs: number | undefined,
+): Promise<number> {
+  await prepareAgentAccessRetentionStatement(tx, deadlineMs);
+  const candidates = await tx
+    .select({id: agentAuthorizationRequests.id})
+    .from(agentAuthorizationRequests)
+    .where(lte(agentAuthorizationRequests.expiresAt, cutoff))
+    .orderBy(asc(agentAuthorizationRequests.expiresAt), asc(agentAuthorizationRequests.id))
+    .limit(limit);
+  if (candidates.length === 0) return 0;
+
+  await prepareAgentAccessRetentionStatement(tx, deadlineMs);
+  const rows = await tx
+    .delete(agentAuthorizationRequests)
+    .where(
+      inArray(
+        agentAuthorizationRequests.id,
+        candidates.map(({id}) => id),
+      ),
+    )
+    .returning({id: agentAuthorizationRequests.id});
+  return rows.length;
+}
+
+async function deleteExpiredAgentAuthorizationCodes(
+  tx: AgentAccessTx,
+  cutoff: Date,
+  limit: number,
+  deadlineMs: number | undefined,
+): Promise<number> {
+  await prepareAgentAccessRetentionStatement(tx, deadlineMs);
+  const candidates = await tx
+    .select({id: agentAuthorizationCodes.id})
+    .from(agentAuthorizationCodes)
+    .where(lte(agentAuthorizationCodes.expiresAt, cutoff))
+    .orderBy(asc(agentAuthorizationCodes.expiresAt), asc(agentAuthorizationCodes.id))
+    .limit(limit);
+  if (candidates.length === 0) return 0;
+
+  await prepareAgentAccessRetentionStatement(tx, deadlineMs);
+  const rows = await tx
+    .delete(agentAuthorizationCodes)
+    .where(
+      inArray(
+        agentAuthorizationCodes.id,
+        candidates.map(({id}) => id),
+      ),
+    )
+    .returning({id: agentAuthorizationCodes.id});
+  return rows.length;
+}
+
+async function deleteRetainedAgentRefreshTokens(
+  tx: AgentAccessTx,
+  cutoff: Date,
+  limit: number,
+  deadlineMs: number | undefined,
+): Promise<number> {
+  await prepareAgentAccessRetentionStatement(tx, deadlineMs);
+  const candidates = await tx
+    .select({id: agentRefreshTokens.id})
+    .from(agentRefreshTokens)
+    .where(
+      or(
+        lte(agentRefreshTokens.rotatedAt, cutoff),
+        lte(agentRefreshTokens.revokedAt, cutoff),
+        and(
+          isNull(agentRefreshTokens.rotatedAt),
+          isNull(agentRefreshTokens.revokedAt),
+          lte(agentRefreshTokens.expiresAt, cutoff),
         ),
-      )
-      .orderBy(asc(agentAuthorizationRequests.expiresAt), asc(agentAuthorizationRequests.id))
-      .limit(limit);
-    const codeIds = tx
-      .select({id: agentAuthorizationCodes.id})
-      .from(agentAuthorizationCodes)
+      ),
+    )
+    .orderBy(asc(agentRefreshTokens.expiresAt), asc(agentRefreshTokens.id))
+    .limit(limit);
+  if (candidates.length === 0) return 0;
+
+  await prepareAgentAccessRetentionStatement(tx, deadlineMs);
+  const rows = await tx
+    .delete(agentRefreshTokens)
+    .where(
+      inArray(
+        agentRefreshTokens.id,
+        candidates.map(({id}) => id),
+      ),
+    )
+    .returning({id: agentRefreshTokens.id});
+  return rows.length;
+}
+
+async function deleteRetainedAgentPersonalAccessTokens(
+  tx: AgentAccessTx,
+  cutoff: Date,
+  limit: number,
+  deadlineMs: number | undefined,
+): Promise<number> {
+  await prepareAgentAccessRetentionStatement(tx, deadlineMs);
+  const candidates = await tx
+    .select({id: agentPersonalAccessTokens.id})
+    .from(agentPersonalAccessTokens)
+    .where(
+      or(
+        lte(agentPersonalAccessTokens.revokedAt, cutoff),
+        and(
+          isNull(agentPersonalAccessTokens.revokedAt),
+          lte(agentPersonalAccessTokens.expiresAt, cutoff),
+        ),
+      ),
+    )
+    .orderBy(asc(agentPersonalAccessTokens.expiresAt), asc(agentPersonalAccessTokens.id))
+    .limit(limit);
+  if (candidates.length === 0) return 0;
+
+  await prepareAgentAccessRetentionStatement(tx, deadlineMs);
+  const rows = await tx
+    .delete(agentPersonalAccessTokens)
+    .where(
+      inArray(
+        agentPersonalAccessTokens.id,
+        candidates.map(({id}) => id),
+      ),
+    )
+    .returning({id: agentPersonalAccessTokens.id});
+  return rows.length;
+}
+
+async function pruneTerminalAgentGrants(
+  tx: AgentAccessTx,
+  params: {cutoff: Date; now: Date; limit: number; deadlineMs: number | undefined},
+): Promise<number> {
+  const remainingCodes = tx
+    .select({id: agentAuthorizationCodes.id})
+    .from(agentAuthorizationCodes)
+    .where(eq(agentAuthorizationCodes.grantId, agentGrants.id));
+  const remainingRefreshTokens = tx
+    .select({id: agentRefreshTokens.id})
+    .from(agentRefreshTokens)
+    .where(eq(agentRefreshTokens.grantId, agentGrants.id));
+  await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+  const candidates = await tx
+    .select({id: agentGrants.id, clientId: agentGrants.clientId})
+    .from(agentGrants)
+    .where(
+      and(
+        lte(agentGrants.terminalAt, params.cutoff),
+        notExists(remainingCodes),
+        notExists(remainingRefreshTokens),
+      ),
+    )
+    .orderBy(asc(agentGrants.terminalAt), asc(agentGrants.id))
+    .limit(params.limit)
+    .for('update');
+  if (candidates.length === 0) return 0;
+
+  const grantIds = candidates.map(({id}) => id);
+  // Child retention runs before this function. Do not delete a child merely
+  // because its grant reached the 90-day horizon: a child can have been
+  // revoked after the grant became terminal and still needs its own 30-day
+  // replay/forensics window. Such a grant waits for the next sweep.
+  await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+  const remainingCodeGrants = await tx
+    .select({grantId: agentAuthorizationCodes.grantId})
+    .from(agentAuthorizationCodes)
+    .where(inArray(agentAuthorizationCodes.grantId, grantIds));
+  await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+  const remainingRefreshTokenGrants = await tx
+    .select({grantId: agentRefreshTokens.grantId})
+    .from(agentRefreshTokens)
+    .where(inArray(agentRefreshTokens.grantId, grantIds));
+  const grantsWithChildren = new Set([
+    ...remainingCodeGrants.map(({grantId}) => grantId),
+    ...remainingRefreshTokenGrants.map(({grantId}) => grantId),
+  ]);
+  const deletableGrantIds = grantIds.filter((grantId) => !grantsWithChildren.has(grantId));
+  if (deletableGrantIds.length === 0) return 0;
+
+  await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+  const deletedGrants = await tx
+    .delete(agentGrants)
+    .where(inArray(agentGrants.id, deletableGrantIds))
+    .returning({id: agentGrants.id, clientId: agentGrants.clientId});
+
+  const clientIds = new Set(deletedGrants.map(({clientId}) => clientId));
+  if (clientIds.size > 0) {
+    await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+    await tx
+      .update(agentClients)
+      .set({
+        unreferencedAt: sql`coalesce(${agentClients.unreferencedAt}, ${params.now})`,
+        updatedAt: params.now,
+      })
       .where(
-        or(
-          lt(agentAuthorizationCodes.consumedAt, cutoff),
-          and(
-            isNull(agentAuthorizationCodes.consumedAt),
-            lt(agentAuthorizationCodes.expiresAt, cutoff),
+        and(
+          inArray(agentClients.id, [...clientIds]),
+          notExists(
+            tx
+              .select({id: agentGrants.id})
+              .from(agentGrants)
+              .where(eq(agentGrants.clientId, agentClients.id)),
           ),
         ),
-      )
-      .orderBy(asc(agentAuthorizationCodes.expiresAt), asc(agentAuthorizationCodes.id))
-      .limit(limit);
-    const refreshTokenIds = tx
-      .select({id: agentRefreshTokens.id})
-      .from(agentRefreshTokens)
-      .where(
+      );
+  }
+
+  return deletedGrants.length;
+}
+
+async function pruneUnreferencedAgentClients(
+  tx: AgentAccessTx,
+  params: {cutoff: Date; now: Date; limit: number; deadlineMs: number | undefined},
+): Promise<number> {
+  const liveAuthorizationRequests = tx
+    .select({id: agentAuthorizationRequests.id})
+    .from(agentAuthorizationRequests)
+    .where(
+      and(
+        eq(agentAuthorizationRequests.clientId, agentClients.id),
+        isNull(agentAuthorizationRequests.consumedAt),
+        gt(agentAuthorizationRequests.expiresAt, params.now),
+      ),
+    );
+  await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+  const candidates = await tx
+    .select({id: agentClients.id})
+    .from(agentClients)
+    .where(
+      and(
         or(
-          lt(agentRefreshTokens.rotatedAt, cutoff),
-          and(isNull(agentRefreshTokens.rotatedAt), lt(agentRefreshTokens.revokedAt, cutoff)),
+          lte(agentClients.unreferencedAt, params.cutoff),
           and(
-            isNull(agentRefreshTokens.rotatedAt),
-            isNull(agentRefreshTokens.revokedAt),
-            lt(agentRefreshTokens.expiresAt, cutoff),
+            isNull(agentClients.unreferencedAt),
+            lte(agentClients.createdAt, params.cutoff),
+            notExists(
+              tx
+                .select({id: agentGrants.id})
+                .from(agentGrants)
+                .where(eq(agentGrants.clientId, agentClients.id)),
+            ),
           ),
         ),
-      )
-      .orderBy(asc(agentRefreshTokens.expiresAt), asc(agentRefreshTokens.id))
-      .limit(limit);
-    const patIds = tx
-      .select({id: agentPersonalAccessTokens.id})
-      .from(agentPersonalAccessTokens)
-      .where(
+        notExists(liveAuthorizationRequests),
+      ),
+    )
+    .orderBy(asc(agentClients.unreferencedAt), asc(agentClients.createdAt), asc(agentClients.id))
+    .limit(params.limit)
+    .for('update');
+
+  if (candidates.length === 0) return 0;
+
+  const candidateIds = candidates.map(({id}) => id);
+  await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+  const grantsForCandidates = await tx
+    .select({clientId: agentGrants.clientId})
+    .from(agentGrants)
+    .where(inArray(agentGrants.clientId, candidateIds));
+  await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+  const liveRequestsForCandidates = await tx
+    .select({clientId: agentAuthorizationRequests.clientId})
+    .from(agentAuthorizationRequests)
+    .where(
+      and(
+        inArray(agentAuthorizationRequests.clientId, candidateIds),
+        isNull(agentAuthorizationRequests.consumedAt),
+        gt(agentAuthorizationRequests.expiresAt, params.now),
+      ),
+    );
+  const protectedClientIds = new Set([
+    ...grantsForCandidates.map(({clientId}) => clientId),
+    ...liveRequestsForCandidates.map(({clientId}) => clientId),
+  ]);
+  const deletableClientIds = candidateIds.filter((id) => !protectedClientIds.has(id));
+  if (deletableClientIds.length === 0) return 0;
+
+  await prepareAgentAccessRetentionStatement(tx, params.deadlineMs);
+  const rows = await tx
+    .delete(agentClients)
+    .where(
+      and(
+        inArray(agentClients.id, deletableClientIds),
         or(
-          lt(agentPersonalAccessTokens.revokedAt, cutoff),
-          and(
-            isNull(agentPersonalAccessTokens.revokedAt),
-            lt(agentPersonalAccessTokens.expiresAt, cutoff),
-          ),
+          lte(agentClients.unreferencedAt, params.cutoff),
+          and(isNull(agentClients.unreferencedAt), lte(agentClients.createdAt, params.cutoff)),
         ),
-      )
-      .orderBy(asc(agentPersonalAccessTokens.expiresAt), asc(agentPersonalAccessTokens.id))
-      .limit(limit);
-
-    const [requests, codes, refreshTokens, pats] = await Promise.all([
-      tx
-        .delete(agentAuthorizationRequests)
-        .where(inArray(agentAuthorizationRequests.id, requestIds))
-        .returning({id: agentAuthorizationRequests.id}),
-      tx
-        .delete(agentAuthorizationCodes)
-        .where(inArray(agentAuthorizationCodes.id, codeIds))
-        .returning({id: agentAuthorizationCodes.id}),
-      tx
-        .delete(agentRefreshTokens)
-        .where(inArray(agentRefreshTokens.id, refreshTokenIds))
-        .returning({id: agentRefreshTokens.id}),
-      tx
-        .delete(agentPersonalAccessTokens)
-        .where(inArray(agentPersonalAccessTokens.id, patIds))
-        .returning({id: agentPersonalAccessTokens.id}),
-    ]);
-    return requests.length + codes.length + refreshTokens.length + pats.length;
+        notExists(
+          tx
+            .select({id: agentGrants.id})
+            .from(agentGrants)
+            .where(eq(agentGrants.clientId, agentClients.id)),
+        ),
+        notExists(
+          tx
+            .select({id: agentAuthorizationRequests.id})
+            .from(agentAuthorizationRequests)
+            .where(
+              and(
+                eq(agentAuthorizationRequests.clientId, agentClients.id),
+                isNull(agentAuthorizationRequests.consumedAt),
+                gt(agentAuthorizationRequests.expiresAt, params.now),
+              ),
+            ),
+        ),
+      ),
+    )
+    .returning({id: agentClients.id});
+  return rows.length;
+}
+
+/**
+ * Transitions inactive grants and deletes retained agent-access rows in bounded
+ * batches. The caller can override the common horizon in tests; production uses
+ * the per-row windows from the agent-access retention policy.
+ */
+export async function pruneAgentAccess(params: PruneAgentAccessParams = {}): Promise<number> {
+  return (await pruneAgentAccessBatch(params)).deleted;
+}
+
+/** Runs one bounded retention transaction and reports terminal transitions separately. */
+export async function pruneAgentAccessBatch(
+  params: PruneAgentAccessParams = {},
+): Promise<PruneAgentAccessResult> {
+  const now = params.now ?? new Date();
+  const limit = batchLimit(params.limit);
+  const retentionDays = params.retentionDays;
+  const authorizationCutoff = retentionCutoff(
+    now,
+    retentionDays ?? AGENT_AUTHORIZATION_RETENTION_DAYS,
+  );
+  const refreshTokenCutoff = retentionCutoff(
+    now,
+    retentionDays ?? AGENT_REFRESH_TOKEN_RETENTION_DAYS,
+  );
+  const grantCutoff = retentionCutoff(now, retentionDays ?? AGENT_GRANT_RETENTION_DAYS);
+  const patCutoff = retentionCutoff(now, retentionDays ?? AGENT_PAT_RETENTION_DAYS);
+  const clientCutoff = retentionCutoff(now, retentionDays ?? AGENT_CLIENT_RETENTION_DAYS);
+  const cutoffs: AgentAccessRetentionCutoffs = {
+    authorization: authorizationCutoff,
+    refreshToken: refreshTokenCutoff,
+    grant: grantCutoff,
+    pat: patCutoff,
+    client: clientCutoff,
+  };
+
+  return await db().transaction(async (tx) => {
+    // This runs first so grants whose last child expired can be terminalized in
+    // the same maintenance tick. It takes the same grant row lock as code
+    // exchange and refresh rotation.
+    const transitioned = await transitionAgentGrantsToTerminalTx(tx, {
+      limit,
+      now,
+      deadlineMs: params.deadlineMs,
+    });
+    const deleted =
+      (await deleteExpiredAgentAuthorizationRequests(
+        tx,
+        cutoffs.authorization,
+        limit,
+        params.deadlineMs,
+      )) +
+      (await deleteExpiredAgentAuthorizationCodes(
+        tx,
+        cutoffs.authorization,
+        limit,
+        params.deadlineMs,
+      )) +
+      (await deleteRetainedAgentRefreshTokens(tx, cutoffs.refreshToken, limit, params.deadlineMs)) +
+      (await deleteRetainedAgentPersonalAccessTokens(tx, cutoffs.pat, limit, params.deadlineMs)) +
+      (await pruneTerminalAgentGrants(tx, {
+        cutoff: cutoffs.grant,
+        now,
+        limit,
+        deadlineMs: params.deadlineMs,
+      })) +
+      (await pruneUnreferencedAgentClients(tx, {
+        cutoff: cutoffs.client,
+        now,
+        limit,
+        deadlineMs: params.deadlineMs,
+      }));
+    return {deleted, transitioned};
   });
 }