@shipfox/api-auth 9.2.0 → 10.0.0

package/src/presentation/routes/administration.ts

@@ -0,0 +1,276 @@
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import {
+  administratorUserLookupQuerySchema,
+  administratorUserSummarySchema,
+  bootstrapAdminOwnerBodySchema,
+  bootstrapAdminOwnerResponseSchema,
+  grantAdminRoleBodySchema,
+  grantAdminRoleResponseSchema,
+  listAdminGrantsQuerySchema,
+  listAdminGrantsResponseSchema,
+  revokeAdminGrantBodySchema,
+  revokeAdminGrantResponseSchema,
+} from '@shipfox/api-auth-dto';
+import {decodeTimestampIdCursor, encodeTimestampIdCursor} from '@shipfox/node-drizzle';
+import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+import {z} from 'zod';
+import {requireAdminRole} from '#core/admin-role.js';
+import {
+  bootstrapFirstAdminOwner,
+  findAdministratorUserSummary,
+  grantAdministratorRole,
+  listAdministratorGrantSummaries,
+  revokeAdministratorGrant,
+} from '#core/administration.js';
+import type {AdminGrant} from '#core/entities/admin-grant.js';
+import type {
+  AdministratorGrantSummary,
+  AdministratorUserSummary,
+} from '#core/entities/administrator-read-model.js';
+import {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
+  AdminRoleRequiredError,
+  InvalidAdminBootstrapTokenError,
+  LastAdminOwnerError,
+  UserNotFoundError,
+} from '#core/errors.js';
+import {getClientContext} from '#presentation/auth/jwt-auth.js';
+import {createAuthIpRateLimitPreHandler} from './rate-limit.js';
+
+const idempotencyKeyMaxLength = 256;
+
+function requireActorId(request: FastifyRequest): string {
+  const client = getClientContext(request);
+  if (!client) {
+    throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+  }
+  return client.userId;
+}
+
+function requireIdempotencyKey(request: FastifyRequest): string {
+  const value = request.headers['idempotency-key'];
+  const key = Array.isArray(value) ? value[0] : value;
+  if (!key || key.trim().length === 0 || key.length > idempotencyKeyMaxLength) {
+    throw new ClientError('Idempotency-Key header is required', 'idempotency-key-required', {
+      status: 400,
+    });
+  }
+  return key;
+}
+
+async function requireAdministratorObserver(request: FastifyRequest): Promise<void> {
+  await requireAdminRole({userId: requireActorId(request), minimumRole: 'admin-observer'});
+}
+
+function toAdminGrantDto(grant: AdminGrant) {
+  return {
+    id: grant.id,
+    user_id: grant.userId,
+    role: grant.role,
+    revoked_at: grant.revokedAt?.toISOString() ?? null,
+    created_at: grant.createdAt.toISOString(),
+    updated_at: grant.updatedAt.toISOString(),
+  };
+}
+
+function toAdministratorUserSummaryDto(user: AdministratorUserSummary) {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    status: user.status,
+    email_verified_at: user.emailVerifiedAt?.toISOString() ?? null,
+    created_at: user.createdAt.toISOString(),
+    admin_role: user.adminRole,
+  };
+}
+
+function toAdministratorGrantSummaryDto(grant: AdministratorGrantSummary) {
+  return {
+    grant_id: grant.grantId,
+    role: grant.role,
+    created_at: grant.createdAt.toISOString(),
+    revoked_at: grant.revokedAt?.toISOString() ?? null,
+    user: grant.user,
+  };
+}
+
+function translateAdministrationError(error: unknown): never {
+  if (error instanceof AdminRoleRequiredError) {
+    throw new ClientError('Administrator role required', 'forbidden', {
+      status: 403,
+      details: {required_role: error.minimumRole},
+    });
+  }
+  if (error instanceof InvalidAdminBootstrapTokenError) {
+    throw new ClientError('Bootstrap token is invalid', 'bootstrap-token-invalid', {
+      status: 403,
+    });
+  }
+  if (error instanceof AdminBootstrapClosedError) {
+    throw new ClientError('First administrator owner already exists', 'bootstrap-closed', {
+      status: 409,
+    });
+  }
+  if (error instanceof AdminGrantAlreadyExistsError) {
+    throw new ClientError('Administrator grant already exists', 'grant-already-exists', {
+      status: 409,
+    });
+  }
+  if (error instanceof AdminGrantNotFoundError) {
+    throw new ClientError('Administrator grant not found', 'not-found', {status: 404});
+  }
+  if (error instanceof UserNotFoundError) {
+    throw new ClientError('User not found', 'not-found', {status: 404});
+  }
+  if (error instanceof LastAdminOwnerError) {
+    throw new ClientError('Cannot remove the final active administrator owner', 'last-owner', {
+      status: 409,
+    });
+  }
+  if (error instanceof AdminIdempotencyKeyReuseError) {
+    throw new ClientError(
+      'Idempotency-Key was already used for a different command',
+      'idempotency-key-reused',
+      {status: 409},
+    );
+  }
+  throw error;
+}
+
+const bootstrapRoute = defineRoute({
+  method: 'POST',
+  path: '/bootstrap',
+  description: 'Claim the first administrator owner role with the deployment bootstrap token.',
+  schema: {
+    body: bootstrapAdminOwnerBodySchema,
+    response: {201: bootstrapAdminOwnerResponseSchema},
+  },
+  preHandler: createAuthIpRateLimitPreHandler('bootstrap'),
+  errorHandler: translateAdministrationError,
+  handler: async (request, reply) => {
+    const actorId = requireActorId(request);
+    const grant = await bootstrapFirstAdminOwner({
+      actorId,
+      bootstrapToken: request.body.bootstrap_token,
+      idempotencyKey: requireIdempotencyKey(request),
+      correlationId: request.id,
+    });
+    reply.code(201);
+    return toAdminGrantDto(grant);
+  },
+});
+
+const listRoute = defineRoute({
+  method: 'GET',
+  path: '/',
+  description: 'List bounded local administrator grant summaries.',
+  schema: {
+    querystring: listAdminGrantsQuerySchema,
+    response: {200: listAdminGrantsResponseSchema},
+  },
+  errorHandler: translateAdministrationError,
+  handler: async (request) => {
+    const {limit, cursor} = request.query;
+    const decodedCursor = decodeTimestampIdCursor(cursor);
+    if (cursor && !decodedCursor) {
+      throw new ClientError('Invalid cursor', 'invalid-cursor', {status: 400});
+    }
+
+    const result = await listAdministratorGrantSummaries({
+      actorId: requireActorId(request),
+      limit,
+      ...(decodedCursor ? {cursor: decodedCursor} : {}),
+    });
+    return {
+      grants: result.grants.map(toAdministratorGrantSummaryDto),
+      next_cursor: result.nextCursor ? encodeTimestampIdCursor(result.nextCursor) : null,
+    };
+  },
+});
+
+const userLookupRoute = defineRoute({
+  method: 'GET',
+  path: '/',
+  description: 'Find one administrator-safe user summary by exact ID or email.',
+  schema: {
+    querystring: administratorUserLookupQuerySchema,
+    response: {200: administratorUserSummarySchema},
+  },
+  preHandler: [requireAdministratorObserver, createAuthIpRateLimitPreHandler('lookup')],
+  errorHandler: translateAdministrationError,
+  handler: async (request) => {
+    const {id, user_id: userId, email} = request.query;
+    const lookupId = id ?? userId;
+    const actorId = requireActorId(request);
+    const user = lookupId
+      ? await findAdministratorUserSummary({actorId, id: lookupId})
+      : email
+        ? await findAdministratorUserSummary({actorId, email})
+        : undefined;
+    if (!user) throw new UserNotFoundError(lookupId ?? email ?? 'unknown');
+    return toAdministratorUserSummaryDto(user);
+  },
+});
+
+const grantRoute = defineRoute({
+  method: 'POST',
+  path: '/',
+  description: 'Grant a local administrator role to an active user.',
+  schema: {
+    body: grantAdminRoleBodySchema,
+    response: {201: grantAdminRoleResponseSchema},
+  },
+  errorHandler: translateAdministrationError,
+  handler: async (request, reply) => {
+    const actorId = requireActorId(request);
+    const grant = await grantAdministratorRole({
+      actorId,
+      userId: request.body.user_id,
+      role: request.body.role,
+      reason: request.body.reason,
+      idempotencyKey: requireIdempotencyKey(request),
+      correlationId: request.id,
+    });
+    reply.code(201);
+    return toAdminGrantDto(grant);
+  },
+});
+
+const revokeRoute = defineRoute({
+  method: 'DELETE',
+  path: '/:grantId',
+  description: 'Revoke a local administrator grant.',
+  schema: {
+    params: z.object({grantId: z.string().uuid()}),
+    body: revokeAdminGrantBodySchema,
+    response: {200: revokeAdminGrantResponseSchema},
+  },
+  errorHandler: translateAdministrationError,
+  handler: async (request) => {
+    const grant = await revokeAdministratorGrant({
+      actorId: requireActorId(request),
+      grantId: request.params.grantId,
+      reason: request.body.reason,
+      idempotencyKey: requireIdempotencyKey(request),
+      correlationId: request.id,
+    });
+    return toAdminGrantDto(grant);
+  },
+});
+
+export const administrationRoutes: RouteGroup = {
+  prefix: '/admin/auth/admin-grants',
+  auth: AUTH_USER,
+  routes: [bootstrapRoute, listRoute, grantRoute, revokeRoute],
+};
+
+export const administrationUserRoutes: RouteGroup = {
+  prefix: '/admin/auth/users',
+  auth: AUTH_USER,
+  routes: [userLookupRoute],
+};

package/src/presentation/routes/index.test.ts

@@ -8,6 +8,7 @@ const workspaces = {
   preflightInvitationAcceptance: vi.fn(),
   acceptInvitation: vi.fn(),
   requireActiveMembership: vi.fn(),
+  getWorkspaceOperatingState: vi.fn(),
 };
 
 const disabledPasswordPaths = [

package/src/presentation/routes/rate-limit.ts

@@ -8,7 +8,10 @@ import {
   checkAuthRateLimit,
 } from '#core/rate-limit.js';
 
-const policies: Record<AuthRateLimitAction, Record<AuthRateLimitScope, AuthRateLimitPolicy>> = {
+const policies: Record<
+  AuthRateLimitAction,
+  Partial<Record<AuthRateLimitScope, AuthRateLimitPolicy>>
+> = {
   login: {
     ip: {limit: 60, windowSeconds: 5 * 60},
     email: {limit: 10, windowSeconds: 15 * 60},
@@ -17,6 +20,12 @@ const policies: Record<AuthRateLimitAction, Record<AuthRateLimitScope, AuthRateL
     ip: {limit: 30, windowSeconds: 60 * 60},
     email: {limit: 3, windowSeconds: 60 * 60},
   },
+  bootstrap: {
+    ip: {limit: 5, windowSeconds: 15 * 60},
+  },
+  lookup: {
+    ip: {limit: 60, windowSeconds: 5 * 60},
+  },
 };
 
 interface EmailBody {
@@ -34,12 +43,15 @@ async function enforceRateLimit(params: {
   scope: AuthRateLimitScope;
   identifier: string;
 }): Promise<void> {
+  const policy = policies[params.action][params.scope];
+  if (!policy) return;
+
   try {
     await checkAuthRateLimit({
       action: params.action,
       scope: params.scope,
       identifier: params.identifier,
-      ...policies[params.action][params.scope],
+      ...policy,
     });
   } catch (error) {
     if (error instanceof AuthRateLimitExceededError) {
@@ -117,3 +129,15 @@ export function createAuthRateLimitPreHandler(action: AuthRateLimitAction) {
     });
   };
 }
+
+export function createAuthIpRateLimitPreHandler(action: AuthRateLimitAction) {
+  return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+    await enforceRateLimit({
+      request,
+      reply,
+      action,
+      scope: 'ip',
+      identifier: request.ip,
+    });
+  };
+}

package/test/globalSetup.ts

@@ -1,5 +1,8 @@
 import './env.js';
-import {initializeEmailChallengesForTests} from '@shipfox/api-email-challenges/test';
+import {
+  initializeEmailChallengesForTests,
+  resetEmailChallengesForTests,
+} from '@shipfox/api-email-challenges/test';
 import {runMigrations} from '@shipfox/node-drizzle';
 import {closePostgresClient, createPostgresClient} from '@shipfox/node-postgres';
 import {sql} from 'drizzle-orm';
@@ -11,8 +14,9 @@ export async function setup() {
 
   await runMigrations(db(), migrationsPath, '__drizzle_migrations_auth');
   await initializeEmailChallengesForTests();
+  await resetEmailChallengesForTests();
   await db().execute(
-    sql`TRUNCATE auth_admin_grants, auth_outbox, auth_password_resets, auth_rate_limits, auth_refresh_tokens, auth_users CASCADE`,
+    sql`TRUNCATE auth_admin_command_results, auth_admin_grants, auth_outbox, auth_password_resets, auth_rate_limits, auth_refresh_tokens, auth_users CASCADE`,
   );
 
   closeDb();

package/test/routes.ts

@@ -8,6 +8,10 @@ import {and, desc, eq, sql} from 'drizzle-orm';
 import {db} from '#db/db.js';
 import {authOutbox} from '#db/schema/outbox.js';
 import {createJwtAuthMethod} from '#presentation/auth/jwt-auth.js';
+import {
+  administrationRoutes,
+  administrationUserRoutes,
+} from '#presentation/routes/administration.js';
 import {buildAuthRoutes} from '#presentation/routes/index.js';
 
 const testConfig = vi.hoisted(
@@ -48,11 +52,16 @@ const workspaces = workspaceTestDoubles as unknown as WorkspacesInterModuleClien
 
 vi.mock('#config.js', () => ({
   config: {
+    ADMIN_BOOTSTRAP_TOKEN: 'test-bootstrap-token',
     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_PASSWORD_ENABLED: true,
+    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,
@@ -147,7 +156,7 @@ export async function createAuthTestApp(params?: {
 }): Promise<FastifyInstance> {
   const appConfig: AppConfig = {
     auth: [createJwtAuthMethod()],
-    routes: [buildAuthRoutes(true, workspaces)],
+    routes: [buildAuthRoutes(true, workspaces), administrationRoutes, administrationUserRoutes],
     swagger: false,
   };
   if (params?.fastifyOptions) appConfig.fastifyOptions = params.fastifyOptions;