@shipfox/api-auth 10.1.0 → 10.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "10.1.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.1.0",
-    "@shipfox/api-auth-dto": "10.1.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,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.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.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,22 @@ 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() {
@@ -145,7 +142,7 @@ export async function revokeAdminGrant(params: {grantId: string}): Promise<Admin
   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()
@@ -208,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);
 }
@@ -234,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(
@@ -264,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,
@@ -301,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,
@@ -349,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,