@shipfox/api-auth 9.3.0 → 10.1.0

package/src/presentation/routes/administration.ts

@@ -1,23 +1,35 @@
 import {AUTH_USER} from '@shipfox/api-auth-context';
 import {
+  adminBootstrapStateSchema,
+  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,
+  getAdminBootstrapState,
   grantAdministratorRole,
-  listAdministratorGrants,
+  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,
@@ -52,6 +64,10 @@ function requireIdempotencyKey(request: FastifyRequest): string {
   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,
@@ -63,9 +79,31 @@ function toAdminGrantDto(grant: AdminGrant) {
   };
 }
 
+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 owner role required', 'forbidden', {
+    throw new ClientError('Administrator role required', 'forbidden', {
       status: 403,
       details: {required_role: error.minimumRole},
     });
@@ -129,17 +167,66 @@ const bootstrapRoute = defineRoute({
   },
 });
 
+const bootstrapStateRoute = defineRoute({
+  method: 'GET',
+  path: '/bootstrap-state',
+  description: 'Read whether first administrator owner bootstrap is available.',
+  schema: {response: {200: adminBootstrapStateSchema}},
+  preHandler: createAuthIpRateLimitPreHandler('bootstrap-state'),
+  errorHandler: translateAdministrationError,
+  handler: async () => ({state: await getAdminBootstrapState()}),
+});
+
 const listRoute = defineRoute({
   method: 'GET',
   path: '/',
-  description: 'List local administrator grants.',
-  schema: {response: {200: listAdminGrantsResponseSchema}},
+  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) => ({
-    grants: (await listAdministratorGrants({actorId: requireActorId(request)})).map(
-      toAdminGrantDto,
-    ),
-  }),
+  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({
@@ -189,7 +276,19 @@ const revokeRoute = defineRoute({
 });
 
 export const administrationRoutes: RouteGroup = {
-  prefix: '/admin/v1/auth/admin-grants',
+  prefix: '/admin/auth/admin-grants',
   auth: AUTH_USER,
   routes: [bootstrapRoute, listRoute, grantRoute, revokeRoute],
 };
+
+export const administrationBootstrapRoutes: RouteGroup = {
+  prefix: '/admin/auth',
+  auth: AUTH_USER,
+  routes: [bootstrapStateRoute],
+};
+
+export const administrationUserRoutes: RouteGroup = {
+  prefix: '/admin/auth/users',
+  auth: AUTH_USER,
+  routes: [userLookupRoute],
+};

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

@@ -23,6 +23,12 @@ const policies: Record<
   bootstrap: {
     ip: {limit: 5, windowSeconds: 15 * 60},
   },
+  'bootstrap-state': {
+    ip: {limit: 60, windowSeconds: 5 * 60},
+  },
+  lookup: {
+    ip: {limit: 60, windowSeconds: 5 * 60},
+  },
 };
 
 interface EmailBody {

package/test/routes.ts

@@ -8,7 +8,11 @@ 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} from '#presentation/routes/administration.js';
+import {
+  administrationBootstrapRoutes,
+  administrationRoutes,
+  administrationUserRoutes,
+} from '#presentation/routes/administration.js';
 import {buildAuthRoutes} from '#presentation/routes/index.js';
 
 const testConfig = vi.hoisted(
@@ -153,7 +157,12 @@ export async function createAuthTestApp(params?: {
 }): Promise<FastifyInstance> {
   const appConfig: AppConfig = {
     auth: [createJwtAuthMethod()],
-    routes: [buildAuthRoutes(true, workspaces), administrationRoutes],
+    routes: [
+      buildAuthRoutes(true, workspaces),
+      administrationBootstrapRoutes,
+      administrationRoutes,
+      administrationUserRoutes,
+    ],
     swagger: false,
   };
   if (params?.fastifyOptions) appConfig.fastifyOptions = params.fastifyOptions;