@shipfox/api-auth 9.2.0 → 9.3.0

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

@@ -0,0 +1,41 @@
+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 {pgTable} from './common.js';
+import {users} from './users.js';
+
+export interface StoredAdminGrant {
+  id: string;
+  userId: string;
+  role: AdminRole;
+  revokedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface StoredAdminCommandResult {
+  grant: StoredAdminGrant;
+}
+
+export const adminCommandResults = pgTable(
+  'admin_command_results',
+  {
+    id: uuidv7PrimaryKey(),
+    actorId: uuid('actor_id')
+      .notNull()
+      .references(() => users.id, {onDelete: 'cascade'}),
+    idempotencyKeyFingerprint: text('idempotency_key_fingerprint').notNull(),
+    command: text('command').notNull(),
+    requestFingerprint: text('request_fingerprint').notNull(),
+    result: jsonb('result').$type<StoredAdminCommandResult>().notNull(),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('auth_admin_command_results_actor_key_unique').on(
+      table.actorId,
+      table.idempotencyKeyFingerprint,
+    ),
+  ],
+);
+
+export type AdminCommandResultDb = typeof adminCommandResults.$inferSelect;

package/src/index.test.ts

@@ -3,6 +3,7 @@ import {
   AUTH_USER_SIGNED_UP,
   authEventSchemas,
 } from '@shipfox/api-auth-dto';
+import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
 import {createAuthModule} from './index.js';
 import {passwordLoginMethods} from './login-methods.js';
 
@@ -55,6 +56,7 @@ describe('authModule', () => {
       preflightInvitationAcceptance: vi.fn(),
       acceptInvitation: vi.fn(),
       requireActiveMembership: vi.fn(),
+      getWorkspaceOperatingState: vi.fn(),
     },
     signupPolicy,
   });
@@ -73,9 +75,10 @@ describe('authModule', () => {
         preflightInvitationAcceptance: vi.fn(),
         acceptInvitation: vi.fn(),
         requireActiveMembership: vi.fn(),
+        getWorkspaceOperatingState: vi.fn(),
       },
     });
-    expect(module.routes).toHaveLength(1);
+    expect(module.routes).toHaveLength(2);
     const signupPolicy = buildAuthRoutes.mock.calls[0]?.[2];
 
     expect(signupPolicy).toEqual(expect.objectContaining({isSignupAllowed: expect.any(Function)}));
@@ -95,8 +98,9 @@ describe('authModule', () => {
     const publisher = authModule.publishers?.find((pub) => pub.name === 'auth');
     const events = authModule.subscribers?.map((subscriber) => subscriber.event);
 
-    expect(publisher?.eventSchemas).toBe(authEventSchemas);
+    expect(publisher?.eventSchemas).not.toBe(authEventSchemas);
     expect(Object.keys(publisher?.eventSchemas ?? {}).sort()).toEqual([
+      ADMINISTRATION_ACTION_PERFORMED,
       AUTH_PASSWORD_RESET_SEND_REQUESTED,
       AUTH_USER_SIGNED_UP,
     ]);

package/src/index.ts

@@ -3,6 +3,7 @@ import {
   type AuthEventMap,
   authEventSchemas,
 } from '@shipfox/api-auth-dto';
+import {administrationActionEventSchemas} from '@shipfox/api-common-dto';
 import type {ShipfoxModule} from '@shipfox/node-module';
 import {subscriberFactory} from '@shipfox/node-module';
 import {config} from '#config.js';
@@ -16,10 +17,13 @@ import {createLeaseTokenAuthMethod} from '#presentation/auth/lease-token-auth.js
 import {createRunnerSessionAuthMethod} from '#presentation/auth/runner-session-auth.js';
 import {createAuthE2eRoutes} from '#presentation/e2eRoutes/index.js';
 import {createAuthInterModulePresentation} from '#presentation/inter-module.js';
+import {administrationRoutes} from '#presentation/routes/administration.js';
 import {buildAuthRoutes} from '#presentation/routes/index.js';
 import {onPasswordResetSendRequested} from '#presentation/subscribers/index.js';
 import {passwordLoginMethods} from './login-methods.js';
 
+const authPublisherEventSchemas = {...authEventSchemas, ...administrationActionEventSchemas};
+
 export type {AdminRole, JobLeaseTokenClaims, RunnerSessionTokenClaims} from '@shipfox/api-auth-dto';
 export {
   ADMIN_ROLES,
@@ -29,6 +33,12 @@ export {
   requireAdminRole,
   revokeAdminGrant,
 } from '#core/admin-role.js';
+export {
+  bootstrapFirstAdminOwner,
+  grantAdministratorRole,
+  listAdministratorGrants,
+  revokeAdministratorGrant,
+} from '#core/administration.js';
 export type {
   CreateSessionForUserError,
   CreateSessionForUserParams,
@@ -41,9 +51,14 @@ export {findUserByEmail} from '#core/email-owner.js';
 export type {AdminGrant} from '#core/entities/admin-grant.js';
 export type {User, UserStatus} from '#core/entities/user.js';
 export {
+  AdminBootstrapClosedError,
+  AdminGrantAlreadyExistsError,
+  AdminGrantNotFoundError,
+  AdminIdempotencyKeyReuseError,
   AdminRoleRequiredError,
   AuthDependencyUnavailableError,
   EmailNotVerifiedError,
+  InvalidAdminBootstrapTokenError,
   InvalidCredentialsError,
   LastAdminOwnerError,
   SignupNotAllowedError,
@@ -95,9 +110,12 @@ export function createAuthModule({
     database: {db, migrationsPath, databaseNamespace: 'auth'},
     auth: [createJwtAuthMethod(), createLeaseTokenAuthMethod(), createRunnerSessionAuthMethod()],
     loginMethods: passwordLoginMethods(config.AUTH_PASSWORD_ENABLED),
-    routes: [buildAuthRoutes(config.AUTH_PASSWORD_ENABLED, workspaces, signupPolicy)],
+    routes: [
+      buildAuthRoutes(config.AUTH_PASSWORD_ENABLED, workspaces, signupPolicy),
+      administrationRoutes,
+    ],
     e2eRoutes: [createAuthE2eRoutes(workspaces)],
-    publishers: [{name: 'auth', table: authOutbox, db, eventSchemas: authEventSchemas}],
+    publishers: [{name: 'auth', table: authOutbox, db, eventSchemas: authPublisherEventSchemas}],
     subscribers: [subscriber(AUTH_PASSWORD_RESET_SEND_REQUESTED, onPasswordResetSendRequested)],
     interModulePresentations: [createAuthInterModulePresentation()],
   };

package/src/metrics/instance.ts

@@ -3,7 +3,7 @@ import {instanceMetrics} from '@shipfox/node-opentelemetry';
 export type AuthTokenType = 'session' | 'job_lease' | 'runner_session';
 export type AuthTokenVerificationOutcome = 'ok' | 'rejected';
 export type AuthTokenRefreshOutcome = 'rotated' | 'grace' | 'rejected';
-export type AuthRateLimitAction = 'login' | 'email-send';
+export type AuthRateLimitAction = 'login' | 'email-send' | 'bootstrap';
 export type AuthRateLimitScope = 'ip' | 'email';
 export type AuthRateLimitOutcome = 'allowed' | 'blocked' | 'unavailable';
 

package/src/presentation/auth/refresh-cookie.test.ts

@@ -6,6 +6,10 @@ vi.mock('#config.js', () => ({
     AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
     AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: 14,
     AUTH_PASSWORD_ENABLED: true,
+    AUTH_SIGNUP_GATE_ENABLED: false,
+    AUTH_SIGNUP_ALLOWED_EMAIL_DOMAINS: '',
+    AUTH_SIGNUP_ALLOWED_EMAILS: '',
+    AUTH_SIGNUP_NOT_ALLOWED_MESSAGE: undefined,
   },
 }));
 

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

@@ -14,6 +14,7 @@ describe('auth E2E routes', () => {
           preflightInvitationAcceptance: vi.fn(),
           acceptInvitation: vi.fn(),
           requireActiveMembership: vi.fn(),
+          getWorkspaceOperatingState: vi.fn(),
         }),
       ],
       swagger: false,

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

@@ -0,0 +1,253 @@
+import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
+import {sql} from 'drizzle-orm';
+import type {FastifyInstance} from 'fastify';
+import {db} from '#db/db.js';
+import {authOutbox} from '#db/schema/outbox.js';
+import {createAuthTestApp, createVerifiedSession, resetCapturedMail} from '#test/routes.js';
+
+const BOOTSTRAP_TOKEN = 'test-bootstrap-token';
+
+async function resetAdministrationState(): Promise<void> {
+  await db().execute(
+    sql`TRUNCATE auth_admin_command_results, auth_admin_grants, auth_outbox, auth_rate_limits CASCADE`,
+  );
+}
+
+function authHeaders(token: string, idempotencyKey: string) {
+  return {
+    authorization: `Bearer ${token}`,
+    'idempotency-key': idempotencyKey,
+  };
+}
+
+describe('Auth administration routes', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(async () => {
+    resetCapturedMail();
+    await resetAdministrationState();
+  });
+
+  afterAll(async () => {
+    await resetAdministrationState();
+    await app.close();
+  });
+
+  test('requires an authenticated session for bootstrap', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: {'idempotency-key': 'anonymous-bootstrap'},
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+
+    expect(response.statusCode).toBe(401);
+  });
+
+  test('rejects an invalid bootstrap token without writing a grant or event', async () => {
+    const account = await createVerifiedSession('admin-bootstrap-invalid');
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(account.token, 'invalid-bootstrap'),
+      payload: {bootstrap_token: 'wrong-token'},
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json().code).toBe('bootstrap-token-invalid');
+    await expect(db().select().from(authOutbox)).resolves.toHaveLength(0);
+  });
+
+  test('rate-limits repeated bootstrap attempts by source IP', async () => {
+    const account = await createVerifiedSession('admin-bootstrap-rate-limit');
+
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const response = await app.inject({
+        method: 'POST',
+        url: '/admin/v1/auth/admin-grants/bootstrap',
+        headers: authHeaders(account.token, `bootstrap-rate-limit-${attempt}`),
+        payload: {bootstrap_token: 'wrong-token'},
+      });
+      expect(response.statusCode).toBe(403);
+    }
+
+    const blocked = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(account.token, 'bootstrap-rate-limit-blocked'),
+      payload: {bootstrap_token: 'wrong-token'},
+    });
+    expect(blocked.statusCode).toBe(429);
+    expect(blocked.json().code).toBe('rate-limited');
+  });
+
+  test('bootstraps exactly one owner and permanently closes bootstrap', async () => {
+    const first = await createVerifiedSession('admin-bootstrap-first');
+    const second = await createVerifiedSession('admin-bootstrap-second');
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(first.token, 'bootstrap-first'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+
+    expect(response.statusCode).toBe(201);
+    expect(response.json()).toMatchObject({user_id: first.userId, role: 'admin-owner'});
+
+    const repeated = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(first.token, 'bootstrap-first'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(repeated.statusCode).toBe(201);
+    expect(repeated.json().id).toBe(response.json().id);
+
+    const secondAttempt = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(second.token, 'bootstrap-second'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(secondAttempt.statusCode).toBe(409);
+    expect(secondAttempt.json().code).toBe('bootstrap-closed');
+
+    const events = await db().select().from(authOutbox);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.eventType).toBe(ADMINISTRATION_ACTION_PERFORMED);
+    expect(events[0]?.payload).toMatchObject({
+      actorId: first.userId,
+      actorRole: 'admin-owner',
+      requiredRole: 'admin-owner',
+      command: 'auth.admin_grant.bootstrap',
+      result: 'succeeded',
+    });
+    expect(JSON.stringify(events[0]?.payload)).not.toContain(BOOTSTRAP_TOKEN);
+  });
+
+  test('lets an owner list, grant, and revoke roles with idempotent audited mutations', async () => {
+    const owner = await createVerifiedSession('admin-grant-owner');
+    const target = await createVerifiedSession('admin-grant-target');
+
+    const bootstrap = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'grant-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+    expect(bootstrap.statusCode).toBe(201);
+
+    const grant = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants',
+      headers: authHeaders(owner.token, 'grant-observer'),
+      payload: {
+        user_id: target.userId,
+        role: 'admin-observer',
+        reason: 'Support investigation',
+      },
+    });
+    expect(grant.statusCode).toBe(201);
+
+    const repeatedGrant = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants',
+      headers: authHeaders(owner.token, 'grant-observer'),
+      payload: {
+        user_id: target.userId,
+        role: 'admin-observer',
+        reason: 'Support investigation',
+      },
+    });
+    expect(repeatedGrant.statusCode).toBe(201);
+    expect(repeatedGrant.json().id).toBe(grant.json().id);
+
+    const grants = await app.inject({
+      method: 'GET',
+      url: '/admin/v1/auth/admin-grants',
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+    expect(grants.statusCode).toBe(200);
+    expect(grants.json().grants).toEqual(
+      expect.arrayContaining([expect.objectContaining({user_id: target.userId})]),
+    );
+
+    const revoked = await app.inject({
+      method: 'DELETE',
+      url: `/admin/v1/auth/admin-grants/${grant.json().id}`,
+      headers: authHeaders(owner.token, 'revoke-observer'),
+      payload: {reason: 'Support investigation complete'},
+    });
+    expect(revoked.statusCode).toBe(200);
+    expect(revoked.json()).toMatchObject({id: grant.json().id, revoked_at: expect.any(String)});
+
+    const repeatedRevoke = await app.inject({
+      method: 'DELETE',
+      url: `/admin/v1/auth/admin-grants/${grant.json().id}`,
+      headers: authHeaders(owner.token, 'revoke-observer'),
+      payload: {reason: 'Support investigation complete'},
+    });
+    expect(repeatedRevoke.statusCode).toBe(200);
+    expect(repeatedRevoke.json().revoked_at).toBe(revoked.json().revoked_at);
+
+    const events = await db().select().from(authOutbox);
+    expect(events).toHaveLength(3);
+    expect(events.map((event) => event.eventType)).toEqual(
+      Array(3).fill(ADMINISTRATION_ACTION_PERFORMED),
+    );
+  });
+
+  test('protects the final active owner and rejects idempotency-key reuse', async () => {
+    const owner = await createVerifiedSession('admin-final-owner');
+    const target = await createVerifiedSession('admin-final-target');
+
+    await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants/bootstrap',
+      headers: authHeaders(owner.token, 'final-bootstrap'),
+      payload: {bootstrap_token: BOOTSTRAP_TOKEN},
+    });
+
+    const firstGrant = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants',
+      headers: authHeaders(owner.token, 'role-key'),
+      payload: {user_id: target.userId, role: 'admin-observer', reason: 'Initial review'},
+    });
+    expect(firstGrant.statusCode).toBe(201);
+
+    const reusedKey = await app.inject({
+      method: 'POST',
+      url: '/admin/v1/auth/admin-grants',
+      headers: authHeaders(owner.token, 'role-key'),
+      payload: {user_id: target.userId, role: 'admin-operator', reason: 'Different command'},
+    });
+    expect(reusedKey.statusCode).toBe(409);
+    expect(reusedKey.json().code).toBe('idempotency-key-reused');
+
+    const finalOwnerRevoke = await app.inject({
+      method: 'DELETE',
+      url: `/admin/v1/auth/admin-grants/${
+        (
+          await app.inject({
+            method: 'GET',
+            url: '/admin/v1/auth/admin-grants',
+            headers: {authorization: `Bearer ${owner.token}`},
+          })
+        )
+          .json()
+          .grants.find((grant: {user_id: string}) => grant.user_id === owner.userId).id
+      }`,
+      headers: authHeaders(owner.token, 'revoke-final-owner'),
+      payload: {reason: 'Attempt to remove final owner'},
+    });
+    expect(finalOwnerRevoke.statusCode).toBe(409);
+    expect(finalOwnerRevoke.json().code).toBe('last-owner');
+  });
+});

package/src/presentation/routes/administration.ts

@@ -0,0 +1,195 @@
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import {
+  bootstrapAdminOwnerBodySchema,
+  bootstrapAdminOwnerResponseSchema,
+  grantAdminRoleBodySchema,
+  grantAdminRoleResponseSchema,
+  listAdminGrantsResponseSchema,
+  revokeAdminGrantBodySchema,
+  revokeAdminGrantResponseSchema,
+} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+import {z} from 'zod';
+import {
+  bootstrapFirstAdminOwner,
+  grantAdministratorRole,
+  listAdministratorGrants,
+  revokeAdministratorGrant,
+} from '#core/administration.js';
+import type {AdminGrant} from '#core/entities/admin-grant.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;
+}
+
+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 translateAdministrationError(error: unknown): never {
+  if (error instanceof AdminRoleRequiredError) {
+    throw new ClientError('Administrator owner 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 local administrator grants.',
+  schema: {response: {200: listAdminGrantsResponseSchema}},
+  errorHandler: translateAdministrationError,
+  handler: async (request) => ({
+    grants: (await listAdministratorGrants({actorId: requireActorId(request)})).map(
+      toAdminGrantDto,
+    ),
+  }),
+});
+
+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/v1/auth/admin-grants',
+  auth: AUTH_USER,
+  routes: [bootstrapRoute, listRoute, grantRoute, revokeRoute],
+};

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,9 @@ 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},
+  },
 };
 
 interface EmailBody {
@@ -34,12 +40,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 +126,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,
+    });
+  };
+}