@shipfox/api-auth 9.2.0 → 9.3.0

package/drizzle/meta/_journal.json

@@ -15,6 +15,13 @@
       "when": 1785065259979,
       "tag": "0001_brainy_shriek",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1785075183023,
+      "tag": "0002_burly_whizzer",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "9.2.0",
+  "version": "9.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -26,20 +26,21 @@
     "@node-rs/argon2": "^2.0.2",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "9.2.0",
-    "@shipfox/api-auth-dto": "9.2.0",
-    "@shipfox/api-email-challenges": "1.1.4",
-    "@shipfox/api-workspaces-dto": "9.2.0",
+    "@shipfox/api-common-dto": "9.2.0",
+    "@shipfox/api-auth-context": "9.3.0",
+    "@shipfox/api-auth-dto": "9.3.0",
+    "@shipfox/api-email-challenges": "1.1.5",
+    "@shipfox/api-workspaces-dto": "9.3.0",
     "@shipfox/inter-module": "0.2.2",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.4",
     "@shipfox/node-auth-root-key": "0.2.3",
-    "@shipfox/node-fastify": "0.3.3",
+    "@shipfox/node-fastify": "0.3.4",
     "@shipfox/node-jwt": "0.3.2",
     "@shipfox/node-email": "0.3.4",
-    "@shipfox/node-mailer": "0.2.3",
-    "@shipfox/node-module": "1.0.2",
-    "@shipfox/node-opentelemetry": "0.6.2",
+    "@shipfox/node-mailer": "0.2.4",
+    "@shipfox/node-module": "1.0.3",
+    "@shipfox/node-opentelemetry": "0.6.3",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.4.4",
     "@shipfox/node-rate-limit": "0.3.2",

package/src/config.ts

@@ -1,6 +1,10 @@
 import {bool, createConfig, num, str} from '@shipfox/config';
 
 export const config = createConfig({
+  ADMIN_BOOTSTRAP_TOKEN: str({
+    desc: 'Deployment secret accepted once to create the first administrator owner. Set it before bootstrap and remove or rotate it after successful bootstrap.',
+    default: undefined,
+  }),
   AUTH_JWT_EXPIRES_IN: str({
     desc: 'How long an access token stays valid. Accepts a duration string such as 15m, 1h, or 7d.',
     default: '15m',

package/src/core/administration.ts

@@ -0,0 +1,172 @@
+import {createHash, timingSafeEqual} from 'node:crypto';
+import type {AdminRole} from '@shipfox/api-auth-dto';
+import {createAdministrationActionEvent} from '@shipfox/api-common-dto';
+import {config} from '#config.js';
+import {
+  bootstrapFirstAdminOwner as bootstrapFirstAdminOwnerInDb,
+  grantAdminRoleWithAudit,
+  listAdminGrants,
+  revokeAdminGrantWithAudit,
+} from '#db/admin-grants.js';
+import {requireAdminRole} from './admin-role.js';
+import type {AdminGrant} from './entities/admin-grant.js';
+import {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
+  InvalidAdminBootstrapTokenError,
+  LastAdminOwnerError,
+  UserNotFoundError,
+} from './errors.js';
+
+const ADMIN_OWNER_ROLE: AdminRole = 'admin-owner';
+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');
+}
+
+export function administrationCommandFingerprint(command: string, input: unknown): string {
+  return hashAdministrationValue(`${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');
+  return timingSafeEqual(candidateHash, expectedHash);
+}
+
+function administrationEvent(params: {
+  actorId: string;
+  actorRole: AdminRole;
+  command: string;
+  targetType: string;
+  targetId: string;
+  reason: string;
+  correlationId: string;
+  idempotencyKeyFingerprint: string;
+}) {
+  return createAdministrationActionEvent({
+    actorId: params.actorId,
+    actorRole: params.actorRole,
+    requiredRole: ADMIN_OWNER_ROLE,
+    command: params.command,
+    targetType: params.targetType,
+    targetId: params.targetId,
+    reason: params.reason,
+    result: 'succeeded',
+    correlationId: params.correlationId,
+    idempotencyKeyFingerprint: params.idempotencyKeyFingerprint,
+    occurredAt: new Date().toISOString(),
+  });
+}
+
+export interface AdministrationMutationContext {
+  actorId: string;
+  idempotencyKey: string;
+  correlationId: string;
+}
+
+export async function bootstrapFirstAdminOwner(
+  params: AdministrationMutationContext & {bootstrapToken: string},
+): Promise<AdminGrant> {
+  if (!bootstrapTokenMatches(params.bootstrapToken, config.ADMIN_BOOTSTRAP_TOKEN)) {
+    throw new InvalidAdminBootstrapTokenError();
+  }
+
+  return await bootstrapFirstAdminOwnerInDb({
+    userId: params.actorId,
+    actorId: params.actorId,
+    idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    requestFingerprint: administrationCommandFingerprint(BOOTSTRAP_COMMAND, {
+      actorId: params.actorId,
+    }),
+    event: administrationEvent({
+      actorId: params.actorId,
+      actorRole: ADMIN_OWNER_ROLE,
+      command: BOOTSTRAP_COMMAND,
+      targetType: 'user',
+      targetId: params.actorId,
+      reason: 'Initial administrator owner bootstrap',
+      correlationId: params.correlationId,
+      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    }),
+  });
+}
+
+export async function listAdministratorGrants(params: {actorId: string}): Promise<AdminGrant[]> {
+  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OWNER_ROLE});
+  return await listAdminGrants();
+}
+
+export async function grantAdministratorRole(
+  params: AdministrationMutationContext & {userId: string; role: AdminRole; reason: string},
+): Promise<AdminGrant> {
+  const actorRole = await requireAdminRole({
+    userId: params.actorId,
+    minimumRole: ADMIN_OWNER_ROLE,
+  });
+  return await grantAdminRoleWithAudit({
+    userId: params.userId,
+    role: params.role,
+    actorId: params.actorId,
+    idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    requestFingerprint: administrationCommandFingerprint(GRANT_COMMAND, {
+      userId: params.userId,
+      role: params.role,
+      reason: params.reason,
+    }),
+    event: administrationEvent({
+      actorId: params.actorId,
+      actorRole,
+      command: GRANT_COMMAND,
+      targetType: 'user',
+      targetId: params.userId,
+      reason: params.reason,
+      correlationId: params.correlationId,
+      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    }),
+  });
+}
+
+export async function revokeAdministratorGrant(
+  params: AdministrationMutationContext & {grantId: string; reason: string},
+): Promise<AdminGrant> {
+  const actorRole = await requireAdminRole({
+    userId: params.actorId,
+    minimumRole: ADMIN_OWNER_ROLE,
+  });
+  return await revokeAdminGrantWithAudit({
+    grantId: params.grantId,
+    actorId: params.actorId,
+    idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    requestFingerprint: administrationCommandFingerprint(REVOKE_COMMAND, {
+      grantId: params.grantId,
+      reason: params.reason,
+    }),
+    event: administrationEvent({
+      actorId: params.actorId,
+      actorRole,
+      command: REVOKE_COMMAND,
+      targetType: 'admin-grant',
+      targetId: params.grantId,
+      reason: params.reason,
+      correlationId: params.correlationId,
+      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+    }),
+  });
+}
+
+export {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
+  InvalidAdminBootstrapTokenError,
+  LastAdminOwnerError,
+  UserNotFoundError,
+};

package/src/core/auth-default-signup-policy.test.ts

@@ -0,0 +1,65 @@
+import {provisionUser, signup} from '#core/auth.js';
+
+const testConfig = vi.hoisted(() => ({
+  AUTH_JWT_EXPIRES_IN: '15m',
+  AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: 14,
+  AUTH_REFRESH_ROTATION_GRACE_SECONDS: 30,
+  AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
+  AUTH_SIGNUP_GATE_ENABLED: true,
+  AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: 'allowed.example',
+  AUTH_SIGNUP_ALLOWED_EMAILS: '',
+  AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: undefined as string | undefined,
+  CLIENT_BASE_URL: 'https://app.example.test',
+}));
+
+vi.mock('#config.js', () => ({config: testConfig}));
+
+describe('low-level account creation defaults', () => {
+  test('signup uses the environment policy when no policy is supplied', async () => {
+    const email = `signup-default-${crypto.randomUUID()}@allowed.example`;
+
+    const user = await signup({email, password: 'correct horse battery staple'});
+
+    expect(user.email).toBe(email);
+  });
+
+  test('signup rejects an unlisted email when no policy is supplied', async () => {
+    const email = `signup-default-${crypto.randomUUID()}@blocked.example`;
+
+    await expect(signup({email, password: 'correct horse battery staple'})).rejects.toMatchObject({
+      name: 'SignupNotAllowedError',
+    });
+  });
+
+  test('provisionUser uses the environment policy when no policy is supplied', async () => {
+    const email = `provision-default-${crypto.randomUUID()}@allowed.example`;
+
+    const user = await provisionUser({email});
+
+    expect(user.email).toBe(email);
+  });
+
+  test('provisionUser rejects an unlisted email when no policy is supplied', async () => {
+    const email = `provision-default-${crypto.randomUUID()}@blocked.example`;
+
+    await expect(provisionUser({email})).rejects.toMatchObject({
+      name: 'SignupNotAllowedError',
+    });
+  });
+
+  test('an explicit policy overrides the environment policy for both paths', async () => {
+    const signupEmail = `signup-override-${crypto.randomUUID()}@blocked.example`;
+    const provisionEmail = `provision-override-${crypto.randomUUID()}@blocked.example`;
+    const isSignupAllowed = vi.fn().mockResolvedValue({allowed: true});
+    const signupPolicy = {isSignupAllowed};
+
+    await signup({
+      email: signupEmail,
+      password: 'correct horse battery staple',
+      signupPolicy,
+    });
+    await provisionUser({email: provisionEmail, signupPolicy});
+
+    expect(isSignupAllowed).toHaveBeenCalledTimes(2);
+  });
+});

package/src/core/auth.test.ts

@@ -61,6 +61,10 @@ vi.mock('#config.js', () => ({
     AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: 14,
     AUTH_REFRESH_ROTATION_GRACE_SECONDS: 30,
     AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
+    AUTH_SIGNUP_GATE_ENABLED: false,
+    AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: '',
+    AUTH_SIGNUP_ALLOWED_EMAILS: '',
+    AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: undefined,
     CLIENT_BASE_URL: testConfig.clientBaseUrl,
   },
   mailer: testConfig.mailer,
@@ -77,6 +81,7 @@ const workspaces = {
   preflightInvitationAcceptance: vi.fn(),
   acceptInvitation: vi.fn(),
   requireActiveMembership: vi.fn(),
+  getWorkspaceOperatingState: vi.fn(),
 };
 
 const login = (params: {email: string; password: string}) => coreLogin({...params, workspaces});

package/src/core/auth.ts

@@ -49,15 +49,14 @@ import {
 import {signUserToken} from './jwt.js';
 import {hashPassword, verifyPassword} from './password.js';
 import type {SignupPolicy} from './ports.js';
+import {createEnvironmentSignupPolicy} from './signup-policy.js';
 
 const RESET_TTL_HOURS = 1;
 const PASSWORD_VERIFICATION_PURPOSE = 'password-verification';
 const DEFAULT_SIGNUP_NOT_ALLOWED_MESSAGE =
   'This Shipfox deployment does not accept new accounts right now.';
 
-const defaultSignupPolicy: SignupPolicy = {
-  isSignupAllowed: async () => ({allowed: true}),
-};
+const defaultSignupPolicy: SignupPolicy = createEnvironmentSignupPolicy();
 
 async function assertSignupAllowed(params: {
   signupPolicy?: SignupPolicy | undefined;

package/src/core/errors.ts

@@ -97,6 +97,41 @@ export class LastAdminOwnerError extends Error {
   }
 }
 
+export class AdminGrantNotFoundError extends Error {
+  constructor() {
+    super('Administrator grant not found');
+    this.name = 'AdminGrantNotFoundError';
+  }
+}
+
+export class AdminGrantAlreadyExistsError extends Error {
+  constructor() {
+    super('Administrator grant already exists');
+    this.name = 'AdminGrantAlreadyExistsError';
+  }
+}
+
+export class AdminBootstrapClosedError extends Error {
+  constructor() {
+    super('First administrator owner has already been created');
+    this.name = 'AdminBootstrapClosedError';
+  }
+}
+
+export class InvalidAdminBootstrapTokenError extends Error {
+  constructor() {
+    super('Bootstrap token is invalid');
+    this.name = 'InvalidAdminBootstrapTokenError';
+  }
+}
+
+export class AdminIdempotencyKeyReuseError extends Error {
+  constructor() {
+    super('Idempotency key was already used for a different command');
+    this.name = 'AdminIdempotencyKeyReuseError';
+  }
+}
+
 export class TokenInvalidError extends Error {
   constructor(reason?: string) {
     super(reason ? `Invalid token: ${reason}` : 'Invalid token');

package/src/db/admin-grants.ts

@@ -1,12 +1,32 @@
 import type {AdminRole} from '@shipfox/api-auth-dto';
+import type {
+  AdministrationActionEvent,
+  AdministrationActionEventMap,
+} from '@shipfox/api-common-dto';
+import {writeOutboxEvent} from '@shipfox/node-outbox';
 import {and, asc, eq, isNull, sql} from 'drizzle-orm';
 import {highestAdminRole} from '#core/admin-role-model.js';
 import type {AdminGrant} from '#core/entities/admin-grant.js';
-import {LastAdminOwnerError} from '#core/errors.js';
+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';
 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];
+
 export interface CreateAdminGrantParams {
   userId: string;
   role: AdminRole;
@@ -81,3 +101,240 @@ export async function revokeAdminGrant(params: {grantId: string}): Promise<Admin
     return row ? toAdminGrant(row) : undefined;
   });
 }
+
+interface AuditedAdminCommandParams {
+  actorId: string;
+  idempotencyKeyFingerprint: string;
+  requestFingerprint: string;
+  event: AdministrationActionEvent;
+}
+
+function toStoredAdminGrant(grant: AdminGrant): StoredAdminGrant {
+  return {
+    id: grant.id,
+    userId: grant.userId,
+    role: grant.role,
+    revokedAt: grant.revokedAt?.toISOString() ?? null,
+    createdAt: grant.createdAt.toISOString(),
+    updatedAt: grant.updatedAt.toISOString(),
+  };
+}
+
+function fromStoredAdminGrant(grant: StoredAdminGrant): AdminGrant {
+  return {
+    id: grant.id,
+    userId: grant.userId,
+    role: grant.role,
+    revokedAt: grant.revokedAt ? new Date(grant.revokedAt) : null,
+    createdAt: new Date(grant.createdAt),
+    updatedAt: new Date(grant.updatedAt),
+  };
+}
+
+async function findCommandResult(
+  tx: Tx,
+  params: Pick<
+    AuditedAdminCommandParams,
+    'actorId' | 'idempotencyKeyFingerprint' | 'requestFingerprint'
+  > & {
+    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];
+  if (!result) return undefined;
+  if (
+    result.command !== params.command ||
+    result.requestFingerprint !== params.requestFingerprint
+  ) {
+    throw new AdminIdempotencyKeyReuseError();
+  }
+  return fromStoredAdminGrant(result.result.grant);
+}
+
+async function storeCommandResult(
+  tx: Tx,
+  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}`}))`,
+  );
+}
+
+export async function bootstrapFirstAdminOwner(
+  params: AuditedAdminCommandParams & {userId: string},
+): 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'))`);
+
+    const existing = await findCommandResult(tx, {
+      ...params,
+      command: params.event.command,
+    });
+    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();
+
+    const userRows = await tx
+      .select({id: users.id, status: users.status})
+      .from(users)
+      .where(eq(users.id, params.userId))
+      .limit(1);
+    const user = userRows[0];
+    if (user?.status !== 'active') throw new UserNotFoundError(params.userId);
+
+    const rows = await tx
+      .insert(adminGrants)
+      .values({userId: params.userId, role: 'admin-owner'})
+      .returning();
+    const row = rows[0];
+    if (!row) throw new Error('Bootstrap grant insert returned no rows');
+
+    const grant = toAdminGrant(row);
+    await writeAdminAction(tx, params.event);
+    await storeCommandResult(tx, params, grant);
+    return grant;
+  });
+}
+
+export async function grantAdminRoleWithAudit(
+  params: AuditedAdminCommandParams & {userId: string; role: AdminRole},
+): 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'))`);
+
+    const existing = await findCommandResult(tx, {
+      ...params,
+      command: params.event.command,
+    });
+    if (existing) return existing;
+
+    const userRows = await tx
+      .select({id: users.id, status: users.status})
+      .from(users)
+      .where(eq(users.id, params.userId))
+      .limit(1);
+    const user = userRows[0];
+    if (user?.status !== 'active') throw new UserNotFoundError(params.userId);
+
+    const activeRows = await tx
+      .select({id: adminGrants.id})
+      .from(adminGrants)
+      .where(
+        and(
+          eq(adminGrants.userId, params.userId),
+          eq(adminGrants.role, params.role),
+          isNull(adminGrants.revokedAt),
+        ),
+      )
+      .limit(1);
+    if (activeRows.length > 0) throw new AdminGrantAlreadyExistsError();
+
+    const rows = await tx
+      .insert(adminGrants)
+      .values({userId: params.userId, role: params.role})
+      .returning();
+    const row = rows[0];
+    if (!row) throw new Error('Administrator grant insert returned no rows');
+
+    const grant = toAdminGrant(row);
+    await writeAdminAction(tx, params.event);
+    await storeCommandResult(tx, params, grant);
+    return grant;
+  });
+}
+
+export async function revokeAdminGrantWithAudit(
+  params: AuditedAdminCommandParams & {grantId: string},
+): 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'))`);
+
+    const existing = await findCommandResult(tx, {
+      ...params,
+      command: params.event.command,
+    });
+    if (existing) return existing;
+
+    const rows = await tx
+      .select()
+      .from(adminGrants)
+      .where(and(eq(adminGrants.id, params.grantId), isNull(adminGrants.revokedAt)))
+      .limit(1);
+    const grant = rows[0];
+    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'),
+          ),
+        );
+      if (activeOwners.length <= 1) throw new LastAdminOwnerError();
+    }
+
+    const updated = await tx
+      .update(adminGrants)
+      .set({revokedAt: new Date(), updatedAt: new Date()})
+      .where(and(eq(adminGrants.id, grant.id), isNull(adminGrants.revokedAt)))
+      .returning();
+    const updatedRow = updated[0];
+    if (!updatedRow) throw new AdminGrantNotFoundError();
+
+    const revoked = toAdminGrant(updatedRow);
+    await writeAdminAction(tx, params.event);
+    await storeCommandResult(tx, params, revoked);
+    return revoked;
+  });
+}

package/src/db/db.ts

@@ -1,5 +1,6 @@
 import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
 import {pgClient} from '@shipfox/node-postgres';
+import {adminCommandResults} from './schema/admin-command-results.js';
 import {adminGrants} from './schema/admin-grants.js';
 import {authOutbox} from './schema/outbox.js';
 import {passwordResets} from './schema/password-resets.js';
@@ -9,6 +10,7 @@ import {users} from './schema/users.js';
 
 export const schema = {
   adminGrants,
+  adminCommandResults,
   users,
   passwordResets,
   refreshTokens,