@shipfox/api-auth 10.0.0 → 10.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "10.0.0",
+  "version": "10.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -27,10 +27,10 @@
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
     "@shipfox/api-common-dto": "9.2.0",
-    "@shipfox/api-auth-context": "10.0.0",
-    "@shipfox/api-auth-dto": "10.0.0",
+    "@shipfox/api-auth-context": "10.2.0",
+    "@shipfox/api-auth-dto": "10.2.0",
     "@shipfox/api-email-challenges": "1.1.6",
-    "@shipfox/api-workspaces-dto": "10.0.0",
+    "@shipfox/api-workspaces-dto": "10.2.0",
     "@shipfox/inter-module": "0.2.2",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.4",

package/src/core/administration.ts

@@ -1,14 +1,22 @@
-import {createHash, timingSafeEqual} from 'node:crypto';
+import {timingSafeEqual} from 'node:crypto';
 import type {AdminRole} from '@shipfox/api-auth-dto';
 import {createAdministrationActionEvent} from '@shipfox/api-common-dto';
 import type {TimestampIdCursor} from '@shipfox/node-drizzle';
+import {hashOpaqueToken} from '@shipfox/node-tokens';
 import {config} from '#config.js';
 import {
   bootstrapFirstAdminOwner as bootstrapFirstAdminOwnerInDb,
   grantAdminRoleWithAudit,
+  hasActiveAdminOwner,
   listAdminGrantSummaries,
   revokeAdminGrantWithAudit,
 } from '#db/admin-grants.js';
+import {
+  reactivateUserWithAudit,
+  revokeUserSessionsWithAudit,
+  suspendUserWithAudit,
+  type UserModerationResult,
+} from '#db/admin-user-moderation.js';
 import {findAdministratorUser as findAdministratorUserInDb} from '#db/admin-users.js';
 import {requireAdminRole} from './admin-role.js';
 import type {AdminGrant} from './entities/admin-grant.js';
@@ -28,22 +36,22 @@ import {
 
 const ADMIN_OWNER_ROLE: AdminRole = 'admin-owner';
 const ADMIN_OBSERVER_ROLE: AdminRole = 'admin-observer';
+const ADMIN_OPERATOR_ROLE: AdminRole = 'admin-operator';
 const BOOTSTRAP_COMMAND = 'auth.admin_grant.bootstrap';
 const GRANT_COMMAND = 'auth.admin_grant.grant';
 const REVOKE_COMMAND = 'auth.admin_grant.revoke';
-
-export function hashAdministrationValue(value: string): string {
-  return createHash('sha256').update(value).digest('hex');
-}
+const SUSPEND_USER_COMMAND = 'auth.user.suspend';
+const REACTIVATE_USER_COMMAND = 'auth.user.reactivate';
+const REVOKE_USER_SESSIONS_COMMAND = 'auth.user.revoke-sessions';
 
 export function administrationCommandFingerprint(command: string, input: unknown): string {
-  return hashAdministrationValue(`${command}:${JSON.stringify(input)}`);
+  return hashOpaqueToken(`${command}:${JSON.stringify(input)}`);
 }
 
 function bootstrapTokenMatches(candidate: string, expected: string | undefined): boolean {
   if (!expected) return false;
-  const candidateHash = Buffer.from(hashAdministrationValue(candidate), 'hex');
-  const expectedHash = Buffer.from(hashAdministrationValue(expected), 'hex');
+  const candidateHash = Buffer.from(hashOpaqueToken(candidate), 'hex');
+  const expectedHash = Buffer.from(hashOpaqueToken(expected), 'hex');
   return timingSafeEqual(candidateHash, expectedHash);
 }
 
@@ -54,13 +62,14 @@ function administrationEvent(params: {
   targetType: string;
   targetId: string;
   reason: string;
+  requiredRole?: AdminRole;
   correlationId: string;
   idempotencyKeyFingerprint: string;
 }) {
   return createAdministrationActionEvent({
     actorId: params.actorId,
     actorRole: params.actorRole,
-    requiredRole: ADMIN_OWNER_ROLE,
+    requiredRole: params.requiredRole ?? ADMIN_OWNER_ROLE,
     command: params.command,
     targetType: params.targetType,
     targetId: params.targetId,
@@ -78,6 +87,22 @@ export interface AdministrationMutationContext {
   correlationId: string;
 }
 
+export interface AdministratorUserMutationResult {
+  user: AdministratorUserSummary;
+  correlationId: string;
+  sessionsRevoked: number;
+}
+
+function toAdministratorUserMutationResult(
+  result: UserModerationResult,
+): AdministratorUserMutationResult {
+  return {
+    user: result.user,
+    correlationId: result.correlationId,
+    sessionsRevoked: result.sessionsRevoked,
+  };
+}
+
 export async function bootstrapFirstAdminOwner(
   params: AdministrationMutationContext & {bootstrapToken: string},
 ): Promise<AdminGrant> {
@@ -88,7 +113,7 @@ export async function bootstrapFirstAdminOwner(
   return await bootstrapFirstAdminOwnerInDb({
     userId: params.actorId,
     actorId: params.actorId,
-    idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    idempotencyKeyFingerprint: hashOpaqueToken(params.idempotencyKey),
     requestFingerprint: administrationCommandFingerprint(BOOTSTRAP_COMMAND, {
       actorId: params.actorId,
     }),
@@ -100,11 +125,15 @@ export async function bootstrapFirstAdminOwner(
       targetId: params.actorId,
       reason: 'Initial administrator owner bootstrap',
       correlationId: params.correlationId,
-      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+      idempotencyKeyFingerprint: hashOpaqueToken(params.idempotencyKey),
     }),
   });
 }
 
+export async function getAdminBootstrapState(): Promise<'available' | 'closed'> {
+  return (await hasActiveAdminOwner()) ? 'closed' : 'available';
+}
+
 export async function findAdministratorUserSummary(
   params: {actorId: string} & ({id: string; email?: never} | {email: string; id?: never}),
 ): Promise<AdministratorUserSummary | undefined> {
@@ -155,7 +184,7 @@ export async function grantAdministratorRole(
     userId: params.userId,
     role: params.role,
     actorId: params.actorId,
-    idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    idempotencyKeyFingerprint: hashOpaqueToken(params.idempotencyKey),
     requestFingerprint: administrationCommandFingerprint(GRANT_COMMAND, {
       userId: params.userId,
       role: params.role,
@@ -169,7 +198,7 @@ export async function grantAdministratorRole(
       targetId: params.userId,
       reason: params.reason,
       correlationId: params.correlationId,
-      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+      idempotencyKeyFingerprint: hashOpaqueToken(params.idempotencyKey),
     }),
   });
 }
@@ -184,7 +213,7 @@ export async function revokeAdministratorGrant(
   return await revokeAdminGrantWithAudit({
     grantId: params.grantId,
     actorId: params.actorId,
-    idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    idempotencyKeyFingerprint: hashOpaqueToken(params.idempotencyKey),
     requestFingerprint: administrationCommandFingerprint(REVOKE_COMMAND, {
       grantId: params.grantId,
       reason: params.reason,
@@ -197,11 +226,109 @@ export async function revokeAdministratorGrant(
       targetId: params.grantId,
       reason: params.reason,
       correlationId: params.correlationId,
-      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+      idempotencyKeyFingerprint: hashOpaqueToken(params.idempotencyKey),
     }),
   });
 }
 
+export async function suspendAdministratorUser(
+  params: AdministrationMutationContext & {userId: string; reason: string},
+): Promise<AdministratorUserMutationResult> {
+  const actorRole = await requireAdminRole({
+    userId: params.actorId,
+    minimumRole: ADMIN_OPERATOR_ROLE,
+  });
+  const idempotencyKeyFingerprint = hashOpaqueToken(params.idempotencyKey);
+  return toAdministratorUserMutationResult(
+    await suspendUserWithAudit({
+      actorId: params.actorId,
+      userId: params.userId,
+      idempotencyKeyFingerprint,
+      requestFingerprint: administrationCommandFingerprint(SUSPEND_USER_COMMAND, {
+        userId: params.userId,
+        reason: params.reason,
+      }),
+      event: administrationEvent({
+        actorId: params.actorId,
+        actorRole,
+        requiredRole: ADMIN_OPERATOR_ROLE,
+        command: SUSPEND_USER_COMMAND,
+        targetType: 'user',
+        targetId: params.userId,
+        reason: params.reason,
+        correlationId: params.correlationId,
+        idempotencyKeyFingerprint,
+      }),
+    }),
+  );
+}
+
+export async function reactivateAdministratorUser(
+  params: AdministrationMutationContext & {userId: string; reason?: string},
+): Promise<AdministratorUserMutationResult> {
+  const actorRole = await requireAdminRole({
+    userId: params.actorId,
+    minimumRole: ADMIN_OPERATOR_ROLE,
+  });
+  const reason = params.reason ?? 'User reactivation requested by an administrator';
+  const idempotencyKeyFingerprint = hashOpaqueToken(params.idempotencyKey);
+  return toAdministratorUserMutationResult(
+    await reactivateUserWithAudit({
+      actorId: params.actorId,
+      userId: params.userId,
+      idempotencyKeyFingerprint,
+      requestFingerprint: administrationCommandFingerprint(REACTIVATE_USER_COMMAND, {
+        userId: params.userId,
+        reason,
+      }),
+      event: administrationEvent({
+        actorId: params.actorId,
+        actorRole,
+        requiredRole: ADMIN_OPERATOR_ROLE,
+        command: REACTIVATE_USER_COMMAND,
+        targetType: 'user',
+        targetId: params.userId,
+        reason,
+        correlationId: params.correlationId,
+        idempotencyKeyFingerprint,
+      }),
+    }),
+  );
+}
+
+export async function revokeAdministratorUserSessions(
+  params: AdministrationMutationContext & {userId: string; reason?: string},
+): Promise<AdministratorUserMutationResult> {
+  const actorRole = await requireAdminRole({
+    userId: params.actorId,
+    minimumRole: ADMIN_OPERATOR_ROLE,
+  });
+  const reason = params.reason ?? 'All active user sessions revoked by an administrator';
+  const idempotencyKeyFingerprint = hashOpaqueToken(params.idempotencyKey);
+  return toAdministratorUserMutationResult(
+    await revokeUserSessionsWithAudit({
+      actorId: params.actorId,
+      userId: params.userId,
+      idempotencyKeyFingerprint,
+      requestFingerprint: administrationCommandFingerprint(REVOKE_USER_SESSIONS_COMMAND, {
+        userId: params.userId,
+        reason,
+      }),
+      event: administrationEvent({
+        actorId: params.actorId,
+        actorRole,
+        requiredRole: ADMIN_OPERATOR_ROLE,
+        command: REVOKE_USER_SESSIONS_COMMAND,
+        targetType: 'user',
+        targetId: params.userId,
+        reason,
+        correlationId: params.correlationId,
+        idempotencyKeyFingerprint,
+      }),
+    }),
+  );
+}
+
 export {
   AdminBootstrapClosedError,
   AdminGrantAlreadyExistsError,

package/src/core/auth.ts

@@ -15,7 +15,7 @@ import {generateOpaqueToken, hashOpaqueToken} from '@shipfox/node-tokens';
 import {config} from '#config.js';
 import {consumePasswordReset, createPasswordReset} from '#db/password-resets.js';
 import {
-  createRefreshToken,
+  createRefreshTokenForActiveUser,
   findActiveRefreshTokenByHash,
   findRefreshTokenByHash,
   revokeRefreshSession,
@@ -127,12 +127,13 @@ async function createRefreshSession(
   refreshSessionId: string,
 ): Promise<{refreshToken: string; refreshSessionId: string}> {
   const refreshToken = generateOpaqueToken('refreshToken');
-  const session = await createRefreshToken({
+  const session = await createRefreshTokenForActiveUser({
     sessionId: refreshSessionId,
     userId: user.id,
     hashedToken: hashOpaqueToken(refreshToken),
     expiresAt: daysFromNow(config.AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS),
   });
+  if (!session) throw new InvalidCredentialsError();
   return {refreshToken, refreshSessionId: session.sessionId};
 }
 
@@ -491,12 +492,18 @@ export async function refreshAccessToken(params: {
   // revoked, or expired the token before this refresh could claim it.
   const nextRefreshToken = generateOpaqueToken('refreshToken');
   const rotated = await rotateRefreshToken({
+    userId: current.userId,
     id: current.id,
     currentHashedToken,
     nextHashedToken: hashOpaqueToken(nextRefreshToken),
     expiresAt: daysFromNow(config.AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS),
   });
   if (!rotated) {
+    const latestUser = await findUserById({id: current.userId});
+    if (latestUser?.status !== 'active') {
+      recordRefreshOutcome('rejected');
+      throw new TokenInvalidError('Refresh token is invalid or expired');
+    }
     const latest = await findRefreshTokenByHash({hashedToken: currentHashedToken});
     if (!latest || !isWithinRotationGrace(latest)) {
       recordRefreshOutcome('rejected');

package/src/db/admin-command.ts

@@ -0,0 +1,85 @@
+import type {
+  AdministrationActionEvent,
+  AdministrationActionEventMap,
+} from '@shipfox/api-common-dto';
+import {writeOutboxEvent} from '@shipfox/node-outbox';
+import {and, eq, sql} from 'drizzle-orm';
+import {AdminIdempotencyKeyReuseError} from '#core/errors.js';
+import type {db} from './db.js';
+import {
+  type AdminCommandResultDb,
+  adminCommandResults,
+  type StoredAdminCommandResult,
+} from './schema/admin-command-results.js';
+import {authOutbox} from './schema/outbox.js';
+
+export type Tx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
+
+export interface AdminCommandTransactionParams {
+  actorId: string;
+  idempotencyKeyFingerprint: string;
+  requestFingerprint: string;
+  event: AdministrationActionEvent;
+}
+
+export async function lockAdminCommand(
+  tx: Tx,
+  params: Pick<AdminCommandTransactionParams, 'actorId' | 'idempotencyKeyFingerprint'>,
+): Promise<void> {
+  await tx.execute(
+    sql`select pg_advisory_xact_lock(hashtext(${`auth_admin_command:${params.actorId}:${params.idempotencyKeyFingerprint}`}))`,
+  );
+}
+
+export async function lockAdminOwnerGrants(tx: Tx): Promise<void> {
+  await tx.execute(sql`select pg_advisory_xact_lock(hashtext('auth_admin_owner_grants'))`);
+}
+
+export async function findAdminCommandResult(
+  tx: Tx,
+  params: Pick<
+    AdminCommandTransactionParams,
+    'actorId' | 'idempotencyKeyFingerprint' | 'requestFingerprint'
+  > & {command: string},
+): Promise<AdminCommandResultDb | undefined> {
+  const rows = await tx
+    .select()
+    .from(adminCommandResults)
+    .where(
+      and(
+        eq(adminCommandResults.actorId, params.actorId),
+        eq(adminCommandResults.idempotencyKeyFingerprint, params.idempotencyKeyFingerprint),
+      ),
+    )
+    .limit(1);
+  const result = rows[0];
+  if (!result) return undefined;
+  if (
+    result.command !== params.command ||
+    result.requestFingerprint !== params.requestFingerprint
+  ) {
+    throw new AdminIdempotencyKeyReuseError();
+  }
+  return result;
+}
+
+export async function storeAdminCommandResult(
+  tx: Tx,
+  params: AdminCommandTransactionParams,
+  result: StoredAdminCommandResult,
+): Promise<void> {
+  await tx.insert(adminCommandResults).values({
+    actorId: params.actorId,
+    idempotencyKeyFingerprint: params.idempotencyKeyFingerprint,
+    command: params.event.command,
+    requestFingerprint: params.requestFingerprint,
+    result,
+  });
+}
+
+export async function writeAdminAction(tx: Tx, event: AdministrationActionEvent): Promise<void> {
+  await writeOutboxEvent<AdministrationActionEventMap>(tx, authOutbox, {
+    type: 'administration.action.performed',
+    payload: event,
+  });
+}

package/src/db/admin-grants.test.ts

@@ -1,7 +1,12 @@
 import {eq} from 'drizzle-orm';
 import {LastAdminOwnerError} from '#core/errors.js';
 import {userFactory} from '#test/index.js';
-import {createAdminGrant, findCurrentAdminRole, revokeAdminGrant} from './admin-grants.js';
+import {
+  createAdminGrant,
+  findCurrentAdminRole,
+  hasActiveAdminOwner,
+  revokeAdminGrant,
+} from './admin-grants.js';
 import {db} from './db.js';
 import {users} from './schema/users.js';
 
@@ -26,6 +31,17 @@ describe('admin grants db', () => {
     expect(await findCurrentAdminRole({userId: user.id})).toBeNull();
   });
 
+  test('reopens bootstrap when the sole owner user is suspended', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-owner'});
+
+    await expect(hasActiveAdminOwner()).resolves.toBe(true);
+
+    await db().update(users).set({status: 'suspended'}).where(eq(users.id, user.id));
+
+    await expect(hasActiveAdminOwner()).resolves.toBe(false);
+  });
+
   test('prevents revoking the final active owner but permits replacement first', async () => {
     const firstOwner = await userFactory.create({emailVerifiedAt: new Date()});
     const secondOwner = await userFactory.create({emailVerifiedAt: new Date()});

package/src/db/admin-grants.ts

@@ -1,15 +1,11 @@
 import type {AdminRole} from '@shipfox/api-auth-dto';
-import type {
-  AdministrationActionEvent,
-  AdministrationActionEventMap,
-} from '@shipfox/api-common-dto';
+import type {AdministrationActionEvent} from '@shipfox/api-common-dto';
 import {
   paginateTimestampIdRows,
   type TimestampIdCursor,
   timestampIdCursorWhere,
 } from '@shipfox/node-drizzle';
-import {writeOutboxEvent} from '@shipfox/node-outbox';
-import {and, desc, eq, isNull, sql} from 'drizzle-orm';
+import {and, desc, eq, isNull} from 'drizzle-orm';
 import {highestAdminRole} from '#core/admin-role-model.js';
 import type {AdminGrant} from '#core/entities/admin-grant.js';
 import type {AdministratorGrantSummary} from '#core/entities/administrator-read-model.js';
@@ -17,21 +13,40 @@ import {
   AdminBootstrapClosedError,
   AdminGrantAlreadyExistsError,
   AdminGrantNotFoundError,
-  AdminIdempotencyKeyReuseError,
   LastAdminOwnerError,
   UserNotFoundError,
 } from '#core/errors.js';
-import {db} from './db.js';
 import {
-  type AdminCommandResultDb,
-  adminCommandResults,
-  type StoredAdminGrant,
-} from './schema/admin-command-results.js';
+  findAdminCommandResult,
+  lockAdminCommand,
+  lockAdminOwnerGrants,
+  storeAdminCommandResult,
+  type Tx,
+  writeAdminAction,
+} from './admin-command.js';
+import {db} from './db.js';
+import type {StoredAdminGrant} from './schema/admin-command-results.js';
 import {adminGrants, toAdminGrant} from './schema/admin-grants.js';
-import {authOutbox} from './schema/outbox.js';
 import {users} from './schema/users.js';
 
-type Tx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
+type AdminOwnerQueryExecutor = ReturnType<typeof db> | Tx;
+
+function activeAdminOwnerWhere() {
+  return and(
+    eq(adminGrants.role, 'admin-owner'),
+    isNull(adminGrants.revokedAt),
+    eq(users.status, 'active'),
+  );
+}
+
+async function listActiveAdminOwners(executor: AdminOwnerQueryExecutor) {
+  return await executor
+    .select({id: adminGrants.id})
+    .from(adminGrants)
+    .innerJoin(users, eq(adminGrants.userId, users.id))
+    .where(activeAdminOwnerWhere())
+    .limit(2);
+}
 
 export interface CreateAdminGrantParams {
   userId: string;
@@ -111,11 +126,23 @@ export async function findCurrentAdminRole(params: {userId: string}): Promise<Ad
   return highestAdminRole(rows.map(({role}) => role));
 }
 
+/**
+ * An owner is active only while both the grant and its user account remain
+ * active. A suspended owner's grant is retained, but it intentionally does
+ * not prevent deployment-bound bootstrap recovery.
+ */
+export async function hasActiveAdminOwner(
+  executor: AdminOwnerQueryExecutor = db(),
+): Promise<boolean> {
+  const rows = await listActiveAdminOwners(executor);
+  return rows.length > 0;
+}
+
 export async function revokeAdminGrant(params: {grantId: string}): Promise<AdminGrant | undefined> {
   return await db().transaction(async (tx) => {
     // All owner grant changes share one lock so concurrent revocations cannot
     // both observe the same final owner and leave the instance ownerless.
-    await tx.execute(sql`select pg_advisory_xact_lock(hashtext('auth_admin_owner_grants'))`);
+    await lockAdminOwnerGrants(tx);
 
     const rows = await tx
       .select()
@@ -126,17 +153,7 @@ export async function revokeAdminGrant(params: {grantId: string}): Promise<Admin
     if (!grant) return undefined;
 
     if (grant.role === 'admin-owner') {
-      const activeOwners = await tx
-        .select({id: adminGrants.id})
-        .from(adminGrants)
-        .innerJoin(users, eq(adminGrants.userId, users.id))
-        .where(
-          and(
-            eq(adminGrants.role, 'admin-owner'),
-            isNull(adminGrants.revokedAt),
-            eq(users.status, 'active'),
-          ),
-        );
+      const activeOwners = await listActiveAdminOwners(tx);
       if (activeOwners.length <= 1) throw new LastAdminOwnerError();
     }
 
@@ -188,23 +205,10 @@ async function findCommandResult(
     command: string;
   },
 ): Promise<AdminGrant | undefined> {
-  const rows = await tx
-    .select()
-    .from(adminCommandResults)
-    .where(
-      and(
-        eq(adminCommandResults.actorId, params.actorId),
-        eq(adminCommandResults.idempotencyKeyFingerprint, params.idempotencyKeyFingerprint),
-      ),
-    )
-    .limit(1);
-  const result: AdminCommandResultDb | undefined = rows[0];
+  const result = await findAdminCommandResult(tx, params);
   if (!result) return undefined;
-  if (
-    result.command !== params.command ||
-    result.requestFingerprint !== params.requestFingerprint
-  ) {
-    throw new AdminIdempotencyKeyReuseError();
+  if (!('grant' in result.result)) {
+    throw new Error('Administrator command result has an unexpected shape');
   }
   return fromStoredAdminGrant(result.result.grant);
 }
@@ -214,29 +218,7 @@ async function storeCommandResult(
   params: AuditedAdminCommandParams,
   grant: AdminGrant,
 ): Promise<void> {
-  await tx.insert(adminCommandResults).values({
-    actorId: params.actorId,
-    idempotencyKeyFingerprint: params.idempotencyKeyFingerprint,
-    command: params.event.command,
-    requestFingerprint: params.requestFingerprint,
-    result: {grant: toStoredAdminGrant(grant)},
-  });
-}
-
-async function writeAdminAction(tx: Tx, event: AdministrationActionEvent): Promise<void> {
-  await writeOutboxEvent<AdministrationActionEventMap>(tx, authOutbox, {
-    type: 'administration.action.performed',
-    payload: event,
-  });
-}
-
-async function lockAdminCommand(
-  tx: Tx,
-  params: {actorId: string; idempotencyKeyFingerprint: string},
-) {
-  await tx.execute(
-    sql`select pg_advisory_xact_lock(hashtext(${`auth_admin_command:${params.actorId}:${params.idempotencyKeyFingerprint}`}))`,
-  );
+  await storeAdminCommandResult(tx, params, {grant: toStoredAdminGrant(grant)});
 }
 
 export async function bootstrapFirstAdminOwner(
@@ -244,7 +226,7 @@ export async function bootstrapFirstAdminOwner(
 ): Promise<AdminGrant> {
   return await db().transaction(async (tx) => {
     await lockAdminCommand(tx, params);
-    await tx.execute(sql`select pg_advisory_xact_lock(hashtext('auth_admin_owner_grants'))`);
+    await lockAdminOwnerGrants(tx);
 
     const existing = await findCommandResult(tx, {
       ...params,
@@ -252,19 +234,7 @@ export async function bootstrapFirstAdminOwner(
     });
     if (existing) return existing;
 
-    const activeOwners = await tx
-      .select({id: adminGrants.id})
-      .from(adminGrants)
-      .innerJoin(users, eq(adminGrants.userId, users.id))
-      .where(
-        and(
-          eq(adminGrants.role, 'admin-owner'),
-          isNull(adminGrants.revokedAt),
-          eq(users.status, 'active'),
-        ),
-      )
-      .limit(1);
-    if (activeOwners.length > 0) throw new AdminBootstrapClosedError();
+    if (await hasActiveAdminOwner(tx)) throw new AdminBootstrapClosedError();
 
     const userRows = await tx
       .select({id: users.id, status: users.status})
@@ -293,7 +263,7 @@ export async function grantAdminRoleWithAudit(
 ): Promise<AdminGrant> {
   return await db().transaction(async (tx) => {
     await lockAdminCommand(tx, params);
-    await tx.execute(sql`select pg_advisory_xact_lock(hashtext('auth_admin_owner_grants'))`);
+    await lockAdminOwnerGrants(tx);
 
     const existing = await findCommandResult(tx, {
       ...params,
@@ -341,7 +311,7 @@ export async function revokeAdminGrantWithAudit(
 ): Promise<AdminGrant> {
   return await db().transaction(async (tx) => {
     await lockAdminCommand(tx, params);
-    await tx.execute(sql`select pg_advisory_xact_lock(hashtext('auth_admin_owner_grants'))`);
+    await lockAdminOwnerGrants(tx);
 
     const existing = await findCommandResult(tx, {
       ...params,
@@ -358,17 +328,7 @@ export async function revokeAdminGrantWithAudit(
     if (!grant) throw new AdminGrantNotFoundError();
 
     if (grant.role === 'admin-owner') {
-      const activeOwners = await tx
-        .select({id: adminGrants.id})
-        .from(adminGrants)
-        .innerJoin(users, eq(adminGrants.userId, users.id))
-        .where(
-          and(
-            eq(adminGrants.role, 'admin-owner'),
-            isNull(adminGrants.revokedAt),
-            eq(users.status, 'active'),
-          ),
-        );
+      const activeOwners = await listActiveAdminOwners(tx);
       if (activeOwners.length <= 1) throw new LastAdminOwnerError();
     }