@shipfox/api-auth 10.1.0 → 10.2.0

package/src/db/admin-user-moderation.ts

@@ -0,0 +1,230 @@
+import type {AdministrationActionEvent} from '@shipfox/api-common-dto';
+import {and, eq, gt, isNull, sql} from 'drizzle-orm';
+import {hasMinimumAdminRole, highestAdminRole} from '#core/admin-role-model.js';
+import type {AdministratorUserSummary} from '#core/entities/administrator-read-model.js';
+import {AdminRoleRequiredError, LastAdminOwnerError, UserNotFoundError} from '#core/errors.js';
+import {
+  findAdminCommandResult,
+  lockAdminCommand,
+  lockAdminOwnerGrants,
+  storeAdminCommandResult,
+  type Tx,
+  writeAdminAction,
+} from './admin-command.js';
+import {findAdministratorUserSummary} from './admin-user-summary.js';
+import {db} from './db.js';
+import {lockUserSessionMutations} from './refresh-tokens.js';
+import type {
+  StoredAdministratorUserSummary,
+  StoredAdminUserModerationResult,
+} from './schema/admin-command-results.js';
+import {adminGrants} from './schema/admin-grants.js';
+import {refreshTokens} from './schema/refresh-tokens.js';
+import {users} from './schema/users.js';
+
+interface UserModerationCommandParams {
+  actorId: string;
+  userId: string;
+  idempotencyKeyFingerprint: string;
+  requestFingerprint: string;
+  event: AdministrationActionEvent;
+}
+
+function toStoredUserSummary(user: AdministratorUserSummary): StoredAdministratorUserSummary {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    emailVerifiedAt: user.emailVerifiedAt?.toISOString() ?? null,
+    status: user.status,
+    createdAt: user.createdAt.toISOString(),
+    adminRole: user.adminRole,
+  };
+}
+
+async function findUserSummary(tx: Tx, userId: string): Promise<StoredAdministratorUserSummary> {
+  const user = await findAdministratorUserSummary(tx, {id: userId});
+  if (!user) throw new Error('User summary query returned no rows');
+  return toStoredUserSummary(user);
+}
+
+function fromStoredResult(result: StoredAdminUserModerationResult) {
+  return {
+    user: {
+      id: result.user.id,
+      email: result.user.email,
+      name: result.user.name,
+      emailVerifiedAt: result.user.emailVerifiedAt ? new Date(result.user.emailVerifiedAt) : null,
+      status: result.user.status,
+      createdAt: new Date(result.user.createdAt),
+      adminRole: result.user.adminRole,
+    },
+    correlationId: result.correlationId,
+    sessionsRevoked: result.sessionsRevoked,
+  };
+}
+
+async function findCommandResult(
+  tx: Tx,
+  params: Pick<
+    UserModerationCommandParams,
+    'actorId' | 'idempotencyKeyFingerprint' | 'requestFingerprint'
+  > & {command: string},
+) {
+  const result = await findAdminCommandResult(tx, params);
+  if (!result) return undefined;
+  if (!('userModeration' in result.result)) {
+    throw new Error('Administrator command result has an unexpected shape');
+  }
+  return fromStoredResult(result.result.userModeration);
+}
+
+async function storeCommandResult(
+  tx: Tx,
+  params: UserModerationCommandParams,
+  result: StoredAdminUserModerationResult,
+): Promise<void> {
+  await storeAdminCommandResult(tx, params, {userModeration: result});
+}
+
+async function readTargetUserForUpdate(tx: Tx, userId: string) {
+  const rows = await tx
+    .select({id: users.id, status: users.status})
+    .from(users)
+    .where(eq(users.id, userId))
+    .limit(1)
+    .for('update');
+  const user = rows[0];
+  if (!user || user.status === 'deleted') throw new UserNotFoundError(userId);
+  return user;
+}
+
+async function requireActiveAdminOperator(tx: Tx, actorId: string): Promise<void> {
+  const actorRows = await tx
+    .select({status: users.status})
+    .from(users)
+    .where(eq(users.id, actorId))
+    .limit(1);
+  const actor = actorRows[0];
+  const grants = await tx
+    .select({role: adminGrants.role})
+    .from(adminGrants)
+    .where(and(eq(adminGrants.userId, actorId), isNull(adminGrants.revokedAt)));
+  const role = highestAdminRole(grants.map(({role}) => role));
+
+  if (actor?.status !== 'active' || !role || !hasMinimumAdminRole(role, 'admin-operator')) {
+    throw new AdminRoleRequiredError('admin-operator');
+  }
+}
+
+async function revokeActiveSessions(tx: Tx, userId: string): Promise<number> {
+  const revoked = await tx
+    .update(refreshTokens)
+    .set({revokedAt: sql`now()`, updatedAt: sql`now()`})
+    .where(
+      and(
+        eq(refreshTokens.userId, userId),
+        isNull(refreshTokens.revokedAt),
+        gt(refreshTokens.expiresAt, sql`now()`),
+      ),
+    )
+    .returning({sessionId: refreshTokens.sessionId});
+
+  return new Set(revoked.map(({sessionId}) => sessionId)).size;
+}
+
+async function executeUserModerationCommand(
+  params: UserModerationCommandParams & {
+    operation: 'suspend' | 'reactivate' | 'revoke-sessions';
+  },
+) {
+  return await db().transaction(async (tx) => {
+    await lockAdminCommand(tx, params);
+    if (params.operation === 'suspend') await lockAdminOwnerGrants(tx);
+
+    const existing = await findCommandResult(tx, {
+      ...params,
+      command: params.event.command,
+    });
+    if (existing) return existing;
+
+    await lockUserSessionMutations(tx, params.userId);
+    const user = await readTargetUserForUpdate(tx, params.userId);
+    await requireActiveAdminOperator(tx, params.actorId);
+    let sessionsRevoked = 0;
+
+    if (params.operation === 'suspend') {
+      if (user.status === 'active') {
+        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(2);
+        const targetIsActiveOwner = await tx
+          .select({id: adminGrants.id})
+          .from(adminGrants)
+          .where(
+            and(
+              eq(adminGrants.userId, user.id),
+              eq(adminGrants.role, 'admin-owner'),
+              isNull(adminGrants.revokedAt),
+            ),
+          )
+          .limit(1);
+        if (targetIsActiveOwner.length > 0 && activeOwners.length <= 1) {
+          throw new LastAdminOwnerError();
+        }
+
+        await tx
+          .update(users)
+          .set({status: 'suspended', updatedAt: sql`now()`})
+          .where(eq(users.id, user.id));
+      }
+      sessionsRevoked = await revokeActiveSessions(tx, user.id);
+    } else if (params.operation === 'reactivate' && user.status === 'suspended') {
+      await tx
+        .update(users)
+        .set({status: 'active', updatedAt: sql`now()`})
+        .where(eq(users.id, user.id));
+    } else if (params.operation === 'revoke-sessions') {
+      sessionsRevoked = await revokeActiveSessions(tx, user.id);
+    }
+
+    const summary = await findUserSummary(tx, user.id);
+    const result: StoredAdminUserModerationResult = {
+      user: summary,
+      correlationId: params.event.correlationId,
+      sessionsRevoked,
+    };
+    await writeAdminAction(tx, params.event);
+    await storeCommandResult(tx, params, result);
+    return fromStoredResult(result);
+  });
+}
+
+export type UserModerationResult = Awaited<ReturnType<typeof executeUserModerationCommand>>;
+
+export async function suspendUserWithAudit(
+  params: UserModerationCommandParams,
+): Promise<UserModerationResult> {
+  return await executeUserModerationCommand({...params, operation: 'suspend'});
+}
+
+export async function reactivateUserWithAudit(
+  params: UserModerationCommandParams,
+): Promise<UserModerationResult> {
+  return await executeUserModerationCommand({...params, operation: 'reactivate'});
+}
+
+export async function revokeUserSessionsWithAudit(
+  params: UserModerationCommandParams,
+): Promise<UserModerationResult> {
+  return await executeUserModerationCommand({...params, operation: 'revoke-sessions'});
+}

package/src/db/admin-user-summary.ts

@@ -0,0 +1,51 @@
+import {and, eq, isNull} from 'drizzle-orm';
+import {highestAdminRole} from '#core/admin-role-model.js';
+import type {AdministratorUserSummary} from '#core/entities/administrator-read-model.js';
+import type {db} from './db.js';
+import {adminGrants} from './schema/admin-grants.js';
+import {users} from './schema/users.js';
+
+type Tx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
+export type AdministratorUserSummaryExecutor = ReturnType<typeof db> | Tx;
+
+type AdministratorUserLookup = {id: string; email?: never} | {email: string; id?: never};
+
+export async function findAdministratorUserSummary(
+  executor: AdministratorUserSummaryExecutor,
+  params: AdministratorUserLookup,
+): Promise<AdministratorUserSummary | undefined> {
+  const identifier = 'id' in params ? eq(users.id, params.id) : eq(users.email, params.email);
+  const rows = await executor
+    .select({
+      id: users.id,
+      email: users.email,
+      name: users.name,
+      emailVerifiedAt: users.emailVerifiedAt,
+      status: users.status,
+      createdAt: users.createdAt,
+      adminRole: adminGrants.role,
+    })
+    .from(users)
+    .leftJoin(
+      adminGrants,
+      and(
+        eq(adminGrants.userId, users.id),
+        isNull(adminGrants.revokedAt),
+        eq(users.status, 'active'),
+      ),
+    )
+    .where(identifier);
+
+  const first = rows[0];
+  if (!first) return undefined;
+
+  return {
+    id: first.id,
+    email: first.email,
+    name: first.name,
+    emailVerifiedAt: first.emailVerifiedAt,
+    status: first.status,
+    createdAt: first.createdAt,
+    adminRole: highestAdminRole(rows.flatMap(({adminRole}) => (adminRole ? [adminRole] : []))),
+  } satisfies AdministratorUserSummary;
+}

package/src/db/admin-users.ts

@@ -1,58 +1,13 @@
-import type {AdminRole} from '@shipfox/api-auth-dto';
-import {and, eq, isNull} from 'drizzle-orm';
-import {highestAdminRole} from '#core/admin-role-model.js';
-import type {UserStatus} from '#core/entities/user.js';
+import type {AdministratorUserSummary} from '#core/entities/administrator-read-model.js';
+import {findAdministratorUserSummary} from './admin-user-summary.js';
 import {db} from './db.js';
-import {adminGrants} from './schema/admin-grants.js';
-import {users} from './schema/users.js';
 
-export interface AdministratorUserRecord {
-  id: string;
-  email: string;
-  name: string | null;
-  emailVerifiedAt: Date | null;
-  status: UserStatus;
-  createdAt: Date;
-  adminRole: AdminRole | null;
-}
+export type AdministratorUserRecord = AdministratorUserSummary;
 
 type AdministratorUserLookup = {id: string; email?: never} | {email: string; id?: never};
 
 export async function findAdministratorUser(
   params: AdministratorUserLookup,
 ): Promise<AdministratorUserRecord | undefined> {
-  const identifier = 'id' in params ? eq(users.id, params.id) : eq(users.email, params.email);
-  const rows = await db()
-    .select({
-      id: users.id,
-      email: users.email,
-      name: users.name,
-      emailVerifiedAt: users.emailVerifiedAt,
-      status: users.status,
-      createdAt: users.createdAt,
-      adminRole: adminGrants.role,
-    })
-    .from(users)
-    .leftJoin(
-      adminGrants,
-      and(
-        eq(adminGrants.userId, users.id),
-        isNull(adminGrants.revokedAt),
-        eq(users.status, 'active'),
-      ),
-    )
-    .where(identifier);
-
-  const first = rows[0];
-  if (!first) return undefined;
-
-  return {
-    id: first.id,
-    email: first.email,
-    name: first.name,
-    emailVerifiedAt: first.emailVerifiedAt,
-    status: first.status,
-    createdAt: first.createdAt,
-    adminRole: highestAdminRole(rows.flatMap(({adminRole}) => (adminRole ? [adminRole] : []))),
-  };
+  return await findAdministratorUserSummary(db(), params);
 }

package/src/db/refresh-tokens.ts

@@ -2,6 +2,13 @@ import {and, eq, gt, isNull, ne, sql} from 'drizzle-orm';
 import type {RefreshToken} from '#core/entities/refresh-token.js';
 import {db} from './db.js';
 import {refreshTokens, toRefreshToken} from './schema/refresh-tokens.js';
+import {users} from './schema/users.js';
+
+type Tx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
+
+export async function lockUserSessionMutations(tx: Tx, userId: string): Promise<void> {
+  await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${`auth_user_sessions:${userId}`}))`);
+}
 
 export interface CreateRefreshTokenParams {
   sessionId?: string | undefined;
@@ -26,6 +33,33 @@ export async function createRefreshToken(params: CreateRefreshTokenParams): Prom
   return toRefreshToken(row);
 }
 
+export async function createRefreshTokenForActiveUser(
+  params: CreateRefreshTokenParams,
+): Promise<RefreshToken | undefined> {
+  return await db().transaction(async (tx) => {
+    await lockUserSessionMutations(tx, params.userId);
+    const userRows = await tx
+      .select({status: users.status})
+      .from(users)
+      .where(eq(users.id, params.userId))
+      .limit(1);
+    if (userRows[0]?.status !== 'active') return undefined;
+
+    const rows = await tx
+      .insert(refreshTokens)
+      .values({
+        sessionId: params.sessionId,
+        userId: params.userId,
+        hashedToken: params.hashedToken,
+        expiresAt: params.expiresAt,
+      })
+      .returning();
+    const row = rows[0];
+    if (!row) throw new Error('Insert returned no rows');
+    return toRefreshToken(row);
+  });
+}
+
 /**
  * Looks up the live session token by hash — one that can still authenticate as
  * the current session. Returns `undefined` for revoked, expired, or already
@@ -108,12 +142,32 @@ export async function findRefreshTokenByHash(params: {
  * If the successor insert fails, the predecessor rotation rolls back.
  */
 export async function rotateRefreshToken(params: {
+  userId?: string | undefined;
   id: string;
   currentHashedToken: string;
   nextHashedToken: string;
   expiresAt: Date;
 }): Promise<RefreshToken | undefined> {
   return await db().transaction(async (tx) => {
+    const userId =
+      params.userId ??
+      (
+        await tx
+          .select({userId: refreshTokens.userId})
+          .from(refreshTokens)
+          .where(eq(refreshTokens.id, params.id))
+          .limit(1)
+      )[0]?.userId;
+    if (!userId) return undefined;
+
+    await lockUserSessionMutations(tx, userId);
+    const userRows = await tx
+      .select({status: users.status})
+      .from(users)
+      .where(eq(users.id, userId))
+      .limit(1);
+    if (userRows[0]?.status !== 'active') return undefined;
+
     const rotatedRows = await tx
       .update(refreshTokens)
       .set({

package/src/db/schema/admin-command-results.ts

@@ -1,6 +1,7 @@
 import type {AdminRole} from '@shipfox/api-auth-dto';
 import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
 import {jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {UserStatus} from '#core/entities/user.js';
 import {pgTable} from './common.js';
 import {users} from './users.js';
 
@@ -13,10 +14,30 @@ export interface StoredAdminGrant {
   updatedAt: string;
 }
 
-export interface StoredAdminCommandResult {
-  grant: StoredAdminGrant;
+export interface StoredAdministratorUserSummary {
+  id: string;
+  email: string;
+  name: string | null;
+  emailVerifiedAt: string | null;
+  status: UserStatus;
+  createdAt: string;
+  adminRole: AdminRole | null;
 }
 
+export interface StoredAdminUserModerationResult {
+  user: StoredAdministratorUserSummary;
+  correlationId: string;
+  sessionsRevoked: number;
+}
+
+export type StoredAdminCommandResult =
+  | {
+      grant: StoredAdminGrant;
+    }
+  | {
+      userModeration: StoredAdminUserModerationResult;
+    };
+
 export const adminCommandResults = pgTable(
   'admin_command_results',
   {

package/src/index.ts

@@ -40,7 +40,10 @@ export {
 export {
   bootstrapFirstAdminOwner,
   grantAdministratorRole,
+  reactivateAdministratorUser,
   revokeAdministratorGrant,
+  revokeAdministratorUserSessions,
+  suspendAdministratorUser,
 } from '#core/administration.js';
 export type {
   CreateSessionForUserError,

package/src/presentation/auth/bearer-token-auth.test.ts

@@ -13,9 +13,11 @@ interface TestClaims {
 describe('bearer-token-auth', () => {
   let app: FastifyInstance;
   let verifyToken: ReturnType<typeof vi.fn<(token: string) => Promise<TestClaims | null>>>;
+  let verifierErrorIsInvalid = true;
 
   beforeEach(async () => {
     verifyToken = vi.fn<(token: string) => Promise<TestClaims | null>>();
+    verifierErrorIsInvalid = true;
     app = Fastify();
     app.setValidatorCompiler(validatorCompiler);
     app.setSerializerCompiler(serializerCompiler);
@@ -24,6 +26,7 @@ describe('bearer-token-auth', () => {
     const authMethod = createBearerTokenAuthMethod({
       name: 'test-bearer',
       verifyToken,
+      isInvalidTokenError: () => verifierErrorIsInvalid,
       invalidTokenError: {message: 'Invalid test bearer token', code: 'invalid-test-token'},
       setContext: (request, claims) => {
         (request as FastifyRequest & Record<typeof CONTEXT_KEY, typeof claims>)[CONTEXT_KEY] =
@@ -96,4 +99,18 @@ describe('bearer-token-auth', () => {
     expect(res.json()).toEqual({code: 'invalid-test-token'});
     expect(verifyToken).toHaveBeenCalledWith('invalid-token');
   });
+
+  test('propagates verifier errors classified as service failures', async () => {
+    verifierErrorIsInvalid = false;
+    verifyToken.mockRejectedValue(new Error('database unavailable'));
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/protected',
+      headers: {authorization: 'Bearer valid-token'},
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().code).not.toBe('invalid-test-token');
+  });
 });

package/src/presentation/auth/bearer-token-auth.ts

@@ -9,6 +9,7 @@ interface UnauthorizedErrorParams {
 interface BearerTokenAuthMethodOptions<TClaims> {
   name: string;
   verifyToken: (token: string) => Promise<TClaims | null>;
+  isInvalidTokenError?: (error: unknown) => boolean;
   invalidTokenError: UnauthorizedErrorParams;
   setContext: (request: FastifyRequest, claims: TClaims) => void;
 }
@@ -27,7 +28,11 @@ export function createBearerTokenAuthMethod<TClaims>(
       const token = extractBearerToken(request.headers.authorization);
       if (!token) throwUnauthorized(missingBearerError);
 
-      const claims = await verifyBearerToken(token, options.verifyToken);
+      const claims = await verifyBearerToken(
+        token,
+        options.verifyToken,
+        options.isInvalidTokenError,
+      );
       if (!claims) throwUnauthorized(options.invalidTokenError);
 
       options.setContext(request, claims);
@@ -38,10 +43,12 @@ export function createBearerTokenAuthMethod<TClaims>(
 async function verifyBearerToken<TClaims>(
   token: string,
   verifyToken: (token: string) => Promise<TClaims | null>,
+  isInvalidTokenError: ((error: unknown) => boolean) | undefined,
 ): Promise<TClaims | null> {
   try {
     return await verifyToken(token);
-  } catch {
+  } catch (error) {
+    if (isInvalidTokenError && !isInvalidTokenError(error)) throw error;
     return null;
   }
 }

package/src/presentation/auth/jwt-auth.test.ts

@@ -116,7 +116,7 @@ describe('jwt-auth', () => {
     expect(res.statusCode).toBe(401);
   });
 
-  test('does not read user state during JWT validation', async () => {
+  test('keeps a legacy token verifiable during the migration window', async () => {
     const userId = crypto.randomUUID();
     const email = emailFor('jwt-stateless');
     const token = await signUserToken({

package/src/presentation/auth/jwt-auth.ts

@@ -13,6 +13,7 @@ import type {User} from '#core/entities/user.js';
 import type {UserTokenClaims} from '#core/jwt.js';
 import {verifyUserToken} from '#core/jwt.js';
 import {findActiveRefreshSession} from '#db/refresh-tokens.js';
+import {findUserById} from '#db/users.js';
 import {createBearerTokenAuthMethod} from './bearer-token-auth.js';
 
 const AUTHENTICATED_SESSION_CONTEXT_KEY = Symbol.for('@shipfox/api-auth/session');
@@ -31,6 +32,13 @@ export interface CreateJwtAuthMethodOptions {
   secret: string;
 }
 
+class InvalidJwtTokenError extends Error {
+  constructor() {
+    super('Invalid JWT');
+    this.name = 'InvalidJwtTokenError';
+  }
+}
+
 export function getClientContext(request: FastifyRequest): ClientContext | null {
   return getUserContext(request);
 }
@@ -77,7 +85,28 @@ export async function getAuthenticatedSessionContext(
 export function createJwtAuthMethod(): AuthMethod {
   return createBearerTokenAuthMethod({
     name: AUTH_USER,
-    verifyToken: (token) => verifyUserToken({token, secret: userAccessTokenKey()}),
+    verifyToken: async (token) => {
+      let claims: UserTokenClaims;
+      try {
+        claims = await verifyUserToken({token, secret: userAccessTokenKey()});
+      } catch {
+        throw new InvalidJwtTokenError();
+      }
+      const user = await findUserById({id: claims.sub});
+
+      // Legacy access tokens without a session claim remain verifiable for the
+      // migration window; known suspended or deleted users are still rejected.
+      if (user && user.status !== 'active') return null;
+      if (!claims.refreshSessionId) return claims;
+      if (!user) return null;
+
+      const session = await findActiveRefreshSession({
+        sessionId: claims.refreshSessionId,
+        userId: claims.sub,
+      });
+      return session ? claims : null;
+    },
+    isInvalidTokenError: (error) => error instanceof InvalidJwtTokenError,
     invalidTokenError: {message: 'Invalid or expired token', code: 'unauthorized'},
     setContext: (request, claims) => {
       const clientContext: ClientContext = buildUserContext({