@shipfox/api-auth 10.1.0 → 11.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "10.1.0",
+  "version": "11.0.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.1.0",
-    "@shipfox/api-auth-dto": "10.1.0",
+    "@shipfox/api-auth-context": "11.0.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": "11.0.0",
     "@shipfox/inter-module": "0.2.2",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.4",

package/src/core/administration.ts

@@ -1,7 +1,8 @@
-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,
@@ -10,6 +11,12 @@ import {
   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';
@@ -29,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);
 }
 
@@ -55,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,
@@ -79,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> {
@@ -89,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,
     }),
@@ -101,7 +125,7 @@ export async function bootstrapFirstAdminOwner(
       targetId: params.actorId,
       reason: 'Initial administrator owner bootstrap',
       correlationId: params.correlationId,
-      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+      idempotencyKeyFingerprint: hashOpaqueToken(params.idempotencyKey),
     }),
   });
 }
@@ -160,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,
@@ -174,7 +198,7 @@ export async function grantAdministratorRole(
       targetId: params.userId,
       reason: params.reason,
       correlationId: params.correlationId,
-      idempotencyKeyFingerprint: hashAdministrationValue(params.idempotencyKey),
+      idempotencyKeyFingerprint: hashOpaqueToken(params.idempotencyKey),
     }),
   });
 }
@@ -189,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,
@@ -202,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.test.ts

@@ -73,7 +73,13 @@ vi.mock('#config.js', () => ({
 vi.mock('@shipfox/node-mailer', () => ({mailer: testConfig.mailer}));
 
 const listMembershipsByUserMock = vi.fn(() =>
-  Promise.resolve({memberships: [] as Array<{workspaceId: string; role: 'admin'}>}),
+  Promise.resolve({
+    memberships: [] as Array<{
+      workspaceId: string;
+      role: 'admin';
+      workspaceStatus: 'active' | 'suspended' | 'deleted';
+    }>,
+  }),
 );
 const workspaces = {
   listMembershipsForTokenClaims: listMembershipsByUserMock,
@@ -492,7 +498,6 @@ describe('auth core', () => {
   test('refreshAccessToken rejects a lost rotation claim when the token was revoked', async () => {
     const user = await userFactory.create({emailVerifiedAt: new Date()});
     const loginResult = await login({email: user.email, password: user.plainPassword});
-    listMembershipsByUserMock.mockClear();
     vi.spyOn(refreshTokenDb, 'rotateRefreshToken').mockImplementationOnce(async () => {
       await logout({refreshToken: loginResult.refreshToken});
       return undefined;
@@ -501,7 +506,9 @@ describe('auth core', () => {
     const raced = refreshAccessToken({refreshToken: loginResult.refreshToken});
 
     await expect(raced).rejects.toBeInstanceOf(TokenInvalidError);
-    expect(listMembershipsByUserMock).not.toHaveBeenCalled();
+    await expect(
+      verifyUserToken({token: loginResult.token, secret: userAccessTokenKey()}),
+    ).resolves.toMatchObject({sub: user.id});
   });
 
   test('refreshAccessToken rejects reuse past the grace window and revokes the session', async () => {
@@ -524,6 +531,9 @@ describe('auth core', () => {
         })
       : undefined;
     expect(successor).toBeUndefined();
+    await expect(
+      verifyUserToken({token: refreshed.token, secret: userAccessTokenKey()}),
+    ).resolves.toMatchObject({sub: user.id});
   });
 
   test('refreshAccessToken rejects refresh tokens for inactive users', async () => {
@@ -597,6 +607,9 @@ describe('auth core', () => {
 
     expect(currentRefresh.user.id).toBe(user.id);
     await expect(otherRefresh).rejects.toBeInstanceOf(TokenInvalidError);
+    await expect(
+      verifyUserToken({token: loginResult.token, secret: userAccessTokenKey()}),
+    ).resolves.toMatchObject({sub: user.id});
   });
 
   test('changePassword rejects unknown users and invalid current passwords', async () => {
@@ -696,8 +709,8 @@ describe('auth core', () => {
     const workspaceB = crypto.randomUUID();
     listMembershipsByUserMock.mockResolvedValueOnce({
       memberships: [
-        {workspaceId: workspaceA, role: 'admin'},
-        {workspaceId: workspaceB, role: 'admin'},
+        {workspaceId: workspaceA, role: 'admin', workspaceStatus: 'active'},
+        {workspaceId: workspaceB, role: 'admin', workspaceStatus: 'suspended'},
       ],
     });
 
@@ -706,8 +719,8 @@ describe('auth core', () => {
     const claims = await verifyUserToken({token: result.token, secret: userAccessTokenKey()});
     expect(claims.name).toBe(user.name);
     expect(claims.memberships).toEqual([
-      {workspaceId: workspaceA, role: 'admin'},
-      {workspaceId: workspaceB, role: 'admin'},
+      {workspaceId: workspaceA, role: 'admin', workspaceStatus: 'active'},
+      {workspaceId: workspaceB, role: 'admin', workspaceStatus: 'suspended'},
     ]);
   });
 
@@ -718,7 +731,7 @@ describe('auth core', () => {
 
     const newWorkspaceId = crypto.randomUUID();
     listMembershipsByUserMock.mockResolvedValueOnce({
-      memberships: [{workspaceId: newWorkspaceId, role: 'admin'}],
+      memberships: [{workspaceId: newWorkspaceId, role: 'admin', workspaceStatus: 'active'}],
     });
     const refreshed = await refreshAccessToken({refreshToken: loginResult.refreshToken});
 
@@ -726,7 +739,9 @@ describe('auth core', () => {
       token: refreshed.token,
       secret: userAccessTokenKey(),
     });
-    expect(refreshedClaims.memberships).toEqual([{workspaceId: newWorkspaceId, role: 'admin'}]);
+    expect(refreshedClaims.memberships).toEqual([
+      {workspaceId: newWorkspaceId, role: 'admin', workspaceStatus: 'active'},
+    ]);
   });
 
   test('login fails closed when listMembershipsByUser throws', async () => {
@@ -738,7 +753,7 @@ describe('auth core', () => {
     await expect(promise).rejects.toBeInstanceOf(AuthDependencyUnavailableError);
   });
 
-  test('refresh fails closed when listMembershipsByUser throws', async () => {
+  test('does not rotate a refresh token when listMembershipsByUser throws', async () => {
     const user = await userFactory.create({emailVerifiedAt: new Date()});
     listMembershipsByUserMock.mockResolvedValueOnce({memberships: []});
     const loginResult = await login({email: user.email, password: user.plainPassword});
@@ -747,5 +762,9 @@ describe('auth core', () => {
     const promise = refreshAccessToken({refreshToken: loginResult.refreshToken});
 
     await expect(promise).rejects.toBeInstanceOf(AuthDependencyUnavailableError);
+
+    const retry = await refreshAccessToken({refreshToken: loginResult.refreshToken});
+    expect(retry.token).toEqual(expect.any(String));
+    expect(retry.refreshToken).toEqual(expect.any(String));
   });
 });

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,
@@ -46,7 +46,7 @@ import {
   TokenInvalidError,
   UserNotFoundError,
 } from './errors.js';
-import {signUserToken} from './jwt.js';
+import {signUserToken, type TokenMembership} from './jwt.js';
 import {hashPassword, verifyPassword} from './password.js';
 import type {SignupPolicy} from './ports.js';
 import {createEnvironmentSignupPolicy} from './signup-policy.js';
@@ -95,21 +95,30 @@ function recordRefreshOutcome(outcome: AuthTokenRefreshOutcome): void {
   recordTokenRefreshed(outcome);
 }
 
-async function signAccessToken(
-  user: User,
+type TokenMemberships = TokenMembership[];
+
+async function loadTokenMemberships(
+  userId: string,
   workspaces: WorkspacesInterModuleClient,
-  refreshSessionId: string,
-): Promise<string> {
+): Promise<TokenMemberships> {
   const memberships = await workspaces
-    .listMembershipsForTokenClaims({userId: user.id})
+    .listMembershipsForTokenClaims({userId})
     .catch((error: unknown) => {
       throw new AuthDependencyUnavailableError('workspaces', error);
     });
+  return memberships.memberships;
+}
+
+async function signAccessToken(
+  user: User,
+  memberships: TokenMemberships,
+  refreshSessionId: string,
+): Promise<string> {
   return await signUserToken({
     userId: user.id,
     email: user.email,
     name: user.name,
-    memberships: memberships.memberships,
+    memberships,
     refreshSessionId,
     secret: userAccessTokenKey(),
     expiresIn: config.AUTH_JWT_EXPIRES_IN,
@@ -127,12 +136,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};
 }
 
@@ -141,7 +151,8 @@ async function createSessionTokens(
   workspaces: WorkspacesInterModuleClient,
 ): Promise<{token: string; refreshToken: string; adminRole: AdminRole | null}> {
   const refreshSessionId = crypto.randomUUID();
-  const token = await signAccessToken(user, workspaces, refreshSessionId);
+  const memberships = await loadTokenMemberships(user.id, workspaces);
+  const token = await signAccessToken(user, memberships, refreshSessionId);
   const adminRole = await getCurrentAdminRole({userId: user.id});
   const {refreshToken} = await createRefreshSession(user, refreshSessionId);
   return {token, refreshToken, adminRole};
@@ -334,7 +345,7 @@ export async function signupWithInvitation(
     }
   }
 
-  // Step 4: Issue session. signAccessToken reads memberships through the
+  // Step 4: Issue session. createSessionTokens reads memberships through the
   // workspaces module API, so a successful accept is reflected in the JWT.
   const {token, refreshToken, adminRole} = await createSessionTokens(user, params.workspaces);
 
@@ -478,7 +489,8 @@ export async function refreshAccessToken(params: {
   // second tab); past it, reuse of a retired token means a compromised session.
   if (current.rotatedAt) {
     if (isWithinRotationGrace(current)) {
-      const token = await signAccessToken(user, params.workspaces, current.sessionId);
+      const memberships = await loadTokenMemberships(user.id, params.workspaces);
+      const token = await signAccessToken(user, memberships, current.sessionId);
       recordRefreshOutcome('grace');
       return {token, refreshToken: undefined, user, adminRole};
     }
@@ -487,27 +499,37 @@ export async function refreshAccessToken(params: {
     throw new TokenInvalidError('Refresh token reused after rotation');
   }
 
+  // Keep the external membership snapshot ahead of rotation so an outage
+  // cannot retire a refresh token that the caller can still retry.
+  const memberships = await loadTokenMemberships(user.id, params.workspaces);
+
   // Losing the CAS requires a state check: another request may have rotated,
   // 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');
       throw new TokenInvalidError('Refresh token is invalid or expired');
     }
-    const token = await signAccessToken(user, params.workspaces, latest.sessionId);
+    const token = await signAccessToken(user, memberships, latest.sessionId);
     recordRefreshOutcome('grace');
     return {token, refreshToken: undefined, user, adminRole};
   }
 
-  const token = await signAccessToken(user, params.workspaces, current.sessionId);
+  const token = await signAccessToken(user, memberships, current.sessionId);
   recordRefreshOutcome('rotated');
   return {token, refreshToken: nextRefreshToken, user, adminRole};
 }

package/src/core/jwt.test.ts

@@ -12,8 +12,8 @@ describe('jwt', () => {
     const userId = crypto.randomUUID();
     const email = `jwt-${crypto.randomUUID()}@example.com`;
     const memberships: TokenMembership[] = [
-      {workspaceId: crypto.randomUUID(), role: 'admin'},
-      {workspaceId: crypto.randomUUID(), role: 'admin'},
+      {workspaceId: crypto.randomUUID(), role: 'admin', workspaceStatus: 'active'},
+      {workspaceId: crypto.randomUUID(), role: 'admin', workspaceStatus: 'suspended'},
     ];
 
     const token = await signUserToken({
@@ -140,7 +140,7 @@ describe('jwt', () => {
   test('rejects a token with non-UUID workspaceId in memberships', async () => {
     const token = await new SignJWT({
       email: `jwt-${crypto.randomUUID()}@example.com`,
-      memberships: [{workspaceId: 'not-a-uuid', role: 'admin'}],
+      memberships: [{workspaceId: 'not-a-uuid', role: 'admin', workspaceStatus: 'active'}],
     })
       .setProtectedHeader({alg: 'HS256'})
       .setSubject(crypto.randomUUID())
@@ -151,10 +151,26 @@ describe('jwt', () => {
     await expect(verifyUserToken({token, secret: SECRET})).rejects.toThrow();
   });
 
+  test('accepts legacy tokens with missing workspace status as active', async () => {
+    const token = await new SignJWT({
+      email: `jwt-${crypto.randomUUID()}@example.com`,
+      memberships: [{workspaceId: crypto.randomUUID(), role: 'admin'}],
+    })
+      .setProtectedHeader({alg: 'HS256'})
+      .setSubject(crypto.randomUUID())
+      .setIssuedAt()
+      .setExpirationTime('7d')
+      .sign(encodeSecret(SECRET));
+
+    await expect(verifyUserToken({token, secret: SECRET})).resolves.toMatchObject({
+      memberships: [{workspaceId: expect.any(String), role: 'admin', workspaceStatus: 'active'}],
+    });
+  });
+
   test('rejects a token with unknown role value', async () => {
     const token = await new SignJWT({
       email: `jwt-${crypto.randomUUID()}@example.com`,
-      memberships: [{workspaceId: crypto.randomUUID(), role: 'owner'}],
+      memberships: [{workspaceId: crypto.randomUUID(), role: 'owner', workspaceStatus: 'active'}],
     })
       .setProtectedHeader({alg: 'HS256'})
       .setSubject(crypto.randomUUID())

package/src/core/jwt.ts

@@ -1,4 +1,4 @@
-import {workspaceRoleSchema} from '@shipfox/api-workspaces-dto';
+import {workspaceRoleSchema, workspaceStatusSchema} from '@shipfox/api-workspaces-dto';
 import {signHs256, verifyHs256} from '@shipfox/node-jwt';
 import {z} from 'zod';
 import {recordTokenIssued, recordTokenVerified} from '#metrics/index.js';
@@ -6,6 +6,7 @@ import {recordTokenIssued, recordTokenVerified} from '#metrics/index.js';
 export const tokenMembershipSchema = z.object({
   workspaceId: z.string().uuid(),
   role: workspaceRoleSchema,
+  workspaceStatus: workspaceStatusSchema.default('active'),
 });
 
 export type TokenMembership = z.infer<typeof tokenMembershipSchema>;

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,
+  });
+}