@shipfox/api-auth 19.0.0 → 20.0.0

package/dist/db/agent-access.js

@@ -1,6 +1,84 @@
-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 { 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, agentAuthorizationRequests, agentClients, agentGrants, agentPersonalAccessTokens, agentRefreshTokens, toAgentAuthorizationCode, toAgentAuthorizationRequest, toAgentClient, toAgentGrant, toAgentPersonalAccessToken, toAgentRefreshToken } from './schema/agent-access.js';
+import { users } from './schema/users.js';
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+const MILLISECONDS_PER_SECOND = 1000;
+function retentionCutoff(now, days) {
+    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) {
+    const value = limit ?? 1000;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error('Agent-access batch limit must be a positive integer');
+    }
+    return value;
+}
+let AgentAccessRetentionDeadlineExceededError = class AgentAccessRetentionDeadlineExceededError extends Error {
+    constructor(){
+        super('Agent-access retention deadline exceeded'), this.code = '57014';
+        this.name = 'AgentAccessRetentionDeadlineExceededError';
+    }
+};
+function retentionStatementTimeoutMs(deadlineMs) {
+    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, deadlineMs) {
+    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, grantId) {
+    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, userId) {
+    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, clientId) {
+    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) {
+    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 = new 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) {
+    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 async function createAgentClient(params) {
     return await db().transaction((tx)=>createAgentClientTx(tx, params));
 }
@@ -17,6 +95,31 @@ export async function createAgentClientTx(tx, params) {
     if (!row) throw new Error('Upsert returned no rows');
     return toAgentClient(row);
 }
+/**
+ * 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) {
+    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) {
     const executor = params.executor ?? db();
     const rows = await executor.select().from(agentClients).where(eq(agentClients.clientId, params.clientId)).limit(1);
@@ -34,12 +137,17 @@ export async function markAgentClientUnreferenced(tx, params) {
     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 async function createAgentAuthorizationRequest(params) {
     return await db().transaction((tx)=>createAgentAuthorizationRequestTx(tx, params));
 }
 export async function createAgentAuthorizationRequestTx(tx, params) {
+    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');
@@ -69,7 +177,15 @@ export async function consumeAgentAuthorizationRequest(params) {
 export async function createAgentGrant(params) {
     return await db().transaction((tx)=>createAgentGrantTx(tx, params));
 }
-export async function 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, params) {
+    if (!await lockAgentClient(tx, params.clientId)) {
+        throw new Error(`Agent client ${params.clientId} was not found`);
+    }
     const rows = await tx.insert(agentGrants).values(params).onConflictDoUpdate({
         target: [
             agentGrants.userId,
@@ -115,6 +231,7 @@ export async function createAgentAuthorizationCode(params) {
     return await db().transaction((tx)=>createAgentAuthorizationCodeTx(tx, params));
 }
 export async function createAgentAuthorizationCodeTx(tx, params) {
+    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');
@@ -136,10 +253,21 @@ export async function consumeAgentAuthorizationCode(params) {
     return await db().transaction((tx)=>consumeAgentAuthorizationCodeTx(tx, params));
 }
 /** Claims an authorization code exactly once, including its 60-second TTL. */ export async function consumeAgentAuthorizationCodeTx(tx, params) {
+    // 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.hashedCode, params.hashedCode), isNull(agentAuthorizationCodes.consumedAt), gt(agentAuthorizationCodes.expiresAt, sql`now()`))).returning();
+    }).where(and(eq(agentAuthorizationCodes.id, existing.id), eq(agentAuthorizationCodes.hashedCode, params.hashedCode), isNull(agentAuthorizationCodes.consumedAt), gt(agentAuthorizationCodes.expiresAt, sql`now()`))).returning();
     const row = rows[0];
     return row ? toAgentAuthorizationCode(row) : undefined;
 }
@@ -147,14 +275,18 @@ export async function createAgentRefreshToken(params) {
     return await db().transaction((tx)=>createAgentRefreshTokenTx(tx, params));
 }
 export async function createAgentRefreshTokenTx(tx, params) {
-    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);
 }
 export async function findAgentRefreshTokenByHash(params) {
     const executor = params.executor ?? db();
-    const rows = await executor.select().from(agentRefreshTokens).where(eq(agentRefreshTokens.hashedToken, params.hashedToken)).limit(1);
+    const rows = await executor.select().from(agentRefreshTokens).where(and(eq(agentRefreshTokens.hashedToken, params.hashedToken), isNull(agentRefreshTokens.revokedAt))).limit(1);
     const row = rows[0];
     return row ? toAgentRefreshToken(row) : undefined;
 }
@@ -164,25 +296,100 @@ export async function findActiveAgentRefreshTokenByHash(params) {
     const row = rows[0];
     return row ? toAgentRefreshToken(row) : undefined;
 }
+/** Finds the one live refresh token currently attached to a grant. */ export async function findActiveAgentRefreshTokenByGrantId(params) {
+    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;
+}
+/**
+ * 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) {
+    return await db().transaction((tx)=>resolveAgentRefreshTokenReplayTx(tx, params));
+}
+export async function resolveAgentRefreshTokenReplayTx(tx, params) {
+    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) {
     return await db().transaction((tx)=>rotateAgentRefreshTokenTx(tx, params));
 }
 export async function rotateAgentRefreshTokenTx(tx, params) {
+    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.hashedToken, params.hashedToken), isNull(agentRefreshTokens.rotatedAt), isNull(agentRefreshTokens.revokedAt), gt(agentRefreshTokens.expiresAt, sql`now()`))).returning();
+    }).where(and(eq(agentRefreshTokens.id, existing.id), eq(agentRefreshTokens.hashedToken, params.hashedToken), isNull(agentRefreshTokens.rotatedAt), isNull(agentRefreshTokens.revokedAt), gt(agentRefreshTokens.expiresAt, sql`now()`))).returning();
     const row = rows[0];
     if (!row) return undefined;
-    return await createAgentRefreshTokenTx(tx, {
+    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: params.replacementExpiresAt
-    });
+        expiresAt: replacementExpiresAt
+    }).returning();
+    const successor = successorRows[0];
+    if (!successor) throw new Error('Insert returned no rows');
+    return toAgentRefreshToken(successor);
 }
 export async function revokeAgentRefreshToken(params) {
     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()`
@@ -191,6 +398,76 @@ export async function revokeAgentRefreshToken(params) {
         return row ? toAgentRefreshToken(row) : undefined;
     });
 }
+/** Revokes a grant and every refresh-token generation in its family. */ export async function revokeAgentGrant(params) {
+    return await db().transaction((tx)=>revokeAgentGrantTx(tx, params));
+}
+export async function revokeAgentGrantTx(tx, params) {
+    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);
+}
+/**
+ * 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 = {}) {
+    return await db().transaction((tx)=>transitionAgentGrantsToTerminalTx(tx, params));
+}
+export async function transitionAgentGrantsToTerminalTx(tx, params = {}) {
+    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 async function createAgentPersonalAccessToken(params) {
     return await db().transaction((tx)=>createAgentPersonalAccessTokenTx(tx, params));
 }
@@ -208,17 +485,29 @@ export async function findAgentPersonalAccessTokenByHash(params) {
 }
 export async function findActiveAgentPersonalAccessTokenByHash(params) {
     const executor = params.executor ?? db();
-    const rows = await executor.select().from(agentPersonalAccessTokens).where(and(eq(agentPersonalAccessTokens.hashedToken, params.hashedToken), isNull(agentPersonalAccessTokens.revokedAt), gt(agentPersonalAccessTokens.expiresAt, sql`now()`))).limit(1);
-    const row = rows[0];
+    const rows = await executor.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]?.token;
     return row ? toAgentPersonalAccessToken(row) : undefined;
 }
 export async function markAgentPersonalAccessTokenUsed(params) {
+    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)).returning();
+    }).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) {
     const rows = await db().update(agentPersonalAccessTokens).set({
@@ -228,39 +517,188 @@ export async function revokeAgentPersonalAccessToken(params) {
     const row = rows[0];
     return row ? toAgentPersonalAccessToken(row) : undefined;
 }
-/** Deletes terminal credentials and ephemeral authorization rows in bounded batches. */ export async function pruneAgentAccess(params = {}) {
+async function deleteExpiredAgentAuthorizationRequests(tx, cutoff, limit, deadlineMs) {
+    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, cutoff, limit, deadlineMs) {
+    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, cutoff, limit, deadlineMs) {
+    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(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, cutoff, limit, deadlineMs) {
+    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, params) {
+    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(and(inArray(agentClients.id, [
+            ...clientIds
+        ]), notExists(tx.select({
+            id: agentGrants.id
+        }).from(agentGrants).where(eq(agentGrants.clientId, agentClients.id)))));
+    }
+    return deletedGrants.length;
+}
+async function pruneUnreferencedAgentClients(tx, params) {
+    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(lte(agentClients.unreferencedAt, params.cutoff), and(isNull(agentClients.unreferencedAt), lte(agentClients.createdAt, params.cutoff), notExists(tx.select({
+        id: agentGrants.id
+    }).from(agentGrants).where(eq(agentGrants.clientId, agentClients.id))))), 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(lte(agentClients.unreferencedAt, params.cutoff), and(isNull(agentClients.unreferencedAt), lte(agentClients.createdAt, params.cutoff))), 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 = {}) {
+    return (await pruneAgentAccessBatch(params)).deleted;
+}
+/** Runs one bounded retention transaction and reports terminal transitions separately. */ export async function pruneAgentAccessBatch(params = {}) {
     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);
+    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 = {
+        authorization: authorizationCutoff,
+        refreshToken: refreshTokenCutoff,
+        grant: grantCutoff,
+        pat: patCutoff,
+        client: clientCutoff
+    };
     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)))).orderBy(asc(agentAuthorizationRequests.expiresAt), asc(agentAuthorizationRequests.id)).limit(limit);
-        const codeIds = tx.select({
-            id: agentAuthorizationCodes.id
-        }).from(agentAuthorizationCodes).where(or(lt(agentAuthorizationCodes.consumedAt, cutoff), and(isNull(agentAuthorizationCodes.consumedAt), lt(agentAuthorizationCodes.expiresAt, cutoff)))).orderBy(asc(agentAuthorizationCodes.expiresAt), asc(agentAuthorizationCodes.id)).limit(limit);
-        const refreshTokenIds = tx.select({
-            id: agentRefreshTokens.id
-        }).from(agentRefreshTokens).where(or(lt(agentRefreshTokens.rotatedAt, cutoff), and(isNull(agentRefreshTokens.rotatedAt), lt(agentRefreshTokens.revokedAt, cutoff)), and(isNull(agentRefreshTokens.rotatedAt), isNull(agentRefreshTokens.revokedAt), lt(agentRefreshTokens.expiresAt, cutoff)))).orderBy(asc(agentRefreshTokens.expiresAt), asc(agentRefreshTokens.id)).limit(limit);
-        const patIds = tx.select({
-            id: agentPersonalAccessTokens.id
-        }).from(agentPersonalAccessTokens).where(or(lt(agentPersonalAccessTokens.revokedAt, cutoff), and(isNull(agentPersonalAccessTokens.revokedAt), lt(agentPersonalAccessTokens.expiresAt, 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;
+        // 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
+        };
     });
 }