@shipfox/api-auth 18.0.0 → 20.0.0

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

@@ -0,0 +1,133 @@
+import {createApp, type FastifyInstance} from '@shipfox/node-fastify';
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {InvalidOAuthConfigurationError} from '#core/errors.js';
+import {createOAuthRoutes} from './oauth.js';
+
+let ipCounter = 1;
+const CLIENT_ID_PATTERN = /^client_[0-9a-f-]{36}$/u;
+
+function uniqueIp(): string {
+  ipCounter += 1;
+  return `198.51.100.${ipCounter}`;
+}
+
+describe('OAuth route factories', () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    app = await createApp({
+      fastifyOptions: {trustProxy: true},
+      routes: [createOAuthRoutes({apiPublicUrl: 'https://api.example.test/'})],
+      swagger: false,
+    });
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('serves protected-resource and authorization-server metadata', async () => {
+    const resource = await app.inject({
+      method: 'GET',
+      url: '/.well-known/oauth-protected-resource',
+    });
+    expect(resource.statusCode).toBe(200);
+    expect(resource.json()).toEqual({
+      resource: 'https://api.example.test/mcp',
+      authorization_servers: ['https://api.example.test'],
+      scopes_supported: ['read'],
+    });
+
+    const server = await app.inject({
+      method: 'GET',
+      url: '/.well-known/oauth-authorization-server',
+    });
+    expect(server.statusCode).toBe(200);
+    expect(server.json()).toEqual({
+      issuer: 'https://api.example.test',
+      authorization_endpoint: 'https://api.example.test/oauth/authorize',
+      token_endpoint: 'https://api.example.test/oauth/token',
+      registration_endpoint: 'https://api.example.test/oauth/register',
+      response_types_supported: ['code'],
+      grant_types_supported: ['authorization_code', 'refresh_token'],
+      code_challenge_methods_supported: ['S256'],
+      token_endpoint_auth_methods_supported: ['none'],
+      scopes_supported: ['read'],
+      client_id_metadata_document_supported: true,
+    });
+  });
+
+  it('creates a public registration with no client secret', async () => {
+    const result = await app.inject({
+      method: 'POST',
+      url: '/oauth/register',
+      headers: {'x-forwarded-for': uniqueIp()},
+      payload: {
+        client_name: 'Desktop agent',
+        redirect_uris: ['http://127.0.0.1:43123/callback'],
+      },
+    });
+
+    expect(result.statusCode).toBe(201);
+    expect(result.json()).toEqual({
+      client_id: expect.stringMatching(CLIENT_ID_PATTERN),
+      client_name: 'Desktop agent',
+      redirect_uris: ['http://127.0.0.1:43123/callback'],
+      grant_types: ['authorization_code'],
+      response_types: ['code'],
+      token_endpoint_auth_method: 'none',
+      scope: 'read',
+    });
+  });
+
+  it('rejects non-loopback HTTP redirects', async () => {
+    const result = await app.inject({
+      method: 'POST',
+      url: '/oauth/register',
+      headers: {'x-forwarded-for': uniqueIp()},
+      payload: {
+        client_name: 'Desktop agent',
+        redirect_uris: ['http://client.example/callback'],
+      },
+    });
+
+    expect(result.statusCode).toBe(400);
+  });
+
+  it('rejects an invalid injected public URL before mounting routes', () => {
+    expect(() => createOAuthRoutes({apiPublicUrl: 'http://api.example.test'})).toThrow(
+      InvalidOAuthConfigurationError,
+    );
+  });
+
+  it('returns 429 and Retry-After after the registration IP budget is exhausted', async () => {
+    const ip = uniqueIp();
+    const payload = {
+      client_name: 'Desktop agent',
+      redirect_uris: ['https://client.example/callback'],
+    };
+
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+      const result = await app.inject({
+        method: 'POST',
+        url: '/oauth/register',
+        headers: {'x-forwarded-for': ip},
+        payload,
+      });
+      expect(result.statusCode).toBe(201);
+    }
+
+    const blocked = await app.inject({
+      method: 'POST',
+      url: '/oauth/register',
+      headers: {'x-forwarded-for': ip},
+      payload,
+    });
+    expect(blocked.statusCode).toBe(429);
+    expect(blocked.headers['retry-after']).toEqual(expect.any(String));
+    expect(blocked.json()).toEqual({
+      code: 'rate-limited',
+      details: {retry_after_seconds: expect.any(Number)},
+    });
+  });
+});

package/src/presentation/routes/oauth.ts

@@ -0,0 +1,144 @@
+import {
+  type OAuthDynamicClientRegistrationResponseDto,
+  oauthAuthorizationServerMetadataSchema,
+  oauthDynamicClientRegistrationRequestSchema,
+  oauthDynamicClientRegistrationResponseSchema,
+  oauthProtectedResourceMetadataSchema,
+} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import {
+  InvalidOAuthClientMetadataError,
+  InvalidOAuthConfigurationError,
+  OAuthMetadataFetchError,
+  OAuthRedirectUriNotRegisteredError,
+} from '#core/errors.js';
+import {validateOAuthPublicOrigin} from '#core/oauth-client.js';
+import {registerOAuthClient} from '#core/oauth-client-resolver.js';
+import {createAuthIpRateLimitPreHandler} from './rate-limit.js';
+
+export interface CreateOAuthRoutesOptions {
+  /** Validated here and deliberately injected until production composition. */
+  apiPublicUrl: string;
+}
+
+function apiPublicOrigin(options: CreateOAuthRoutesOptions): string {
+  return validateOAuthPublicOrigin(options.apiPublicUrl);
+}
+
+function translateOAuthError(error: unknown): never {
+  if (
+    error instanceof InvalidOAuthClientMetadataError ||
+    error instanceof OAuthMetadataFetchError ||
+    error instanceof OAuthRedirectUriNotRegisteredError
+  ) {
+    throw new ClientError('OAuth client metadata is invalid', 'invalid-client-metadata', {
+      status: 400,
+    });
+  }
+  if (error instanceof InvalidOAuthConfigurationError) {
+    throw new ClientError('OAuth configuration is invalid', 'oauth-configuration-invalid', {
+      status: 500,
+    });
+  }
+  throw error;
+}
+
+function registrationResponse(
+  result: Awaited<ReturnType<typeof registerOAuthClient>>,
+): OAuthDynamicClientRegistrationResponseDto {
+  return {
+    client_id: result.metadata.clientId,
+    client_name: result.metadata.clientName,
+    redirect_uris: result.metadata.redirectUris,
+    grant_types: result.metadata.grantTypes,
+    response_types: result.metadata.responseTypes,
+    token_endpoint_auth_method: result.metadata.tokenEndpointAuthMethod,
+    scope: result.metadata.scope,
+  };
+}
+
+function createProtectedResourceMetadataRoute(origin: string) {
+  return defineRoute({
+    method: 'GET',
+    path: '/.well-known/oauth-protected-resource',
+    description: 'Describe the protected MCP resource and its authorization server.',
+    schema: {response: {200: oauthProtectedResourceMetadataSchema}},
+    handler: () => ({
+      resource: `${origin}/mcp`,
+      authorization_servers: [origin],
+      scopes_supported: ['read'],
+    }),
+  });
+}
+
+function createAuthorizationServerMetadataRoute(origin: string) {
+  return defineRoute({
+    method: 'GET',
+    path: '/.well-known/oauth-authorization-server',
+    description: 'Describe the MCP OAuth authorization server.',
+    schema: {response: {200: oauthAuthorizationServerMetadataSchema}},
+    handler: () => ({
+      issuer: origin,
+      authorization_endpoint: `${origin}/oauth/authorize`,
+      token_endpoint: `${origin}/oauth/token`,
+      registration_endpoint: `${origin}/oauth/register`,
+      response_types_supported: ['code'],
+      grant_types_supported: ['authorization_code', 'refresh_token'],
+      code_challenge_methods_supported: ['S256'],
+      token_endpoint_auth_methods_supported: ['none'],
+      scopes_supported: ['read'],
+      client_id_metadata_document_supported: true,
+    }),
+  });
+}
+
+function createDynamicRegistrationRoute() {
+  return defineRoute({
+    method: 'POST',
+    path: '/oauth/register',
+    description: 'Register a public OAuth client for MCP access.',
+    options: {bodyLimit: 32 * 1024},
+    schema: {
+      body: oauthDynamicClientRegistrationRequestSchema,
+      response: {201: oauthDynamicClientRegistrationResponseSchema},
+    },
+    preHandler: createAuthIpRateLimitPreHandler('oauth-register'),
+    errorHandler: translateOAuthError,
+    handler: async (request, reply) => {
+      const result = await registerOAuthClient({
+        clientName: request.body.client_name,
+        redirectUris: request.body.redirect_uris,
+        grantTypes: request.body.grant_types,
+        responseTypes: request.body.response_types,
+        tokenEndpointAuthMethod: request.body.token_endpoint_auth_method,
+        scope: request.body.scope,
+      });
+      reply.code(201);
+      return registrationResponse(result);
+    },
+  });
+}
+
+export function createOAuthMetadataRoutes(options: CreateOAuthRoutesOptions): RouteGroup {
+  const origin = apiPublicOrigin(options);
+  return {
+    prefix: '',
+    routes: [
+      createProtectedResourceMetadataRoute(origin),
+      createAuthorizationServerMetadataRoute(origin),
+    ],
+  };
+}
+
+export function createOAuthClientIdentificationRoutes(): RouteGroup {
+  return {prefix: '', routes: [createDynamicRegistrationRoute()]};
+}
+
+export function createOAuthRoutes(options: CreateOAuthRoutesOptions): RouteGroup {
+  const metadataRoutes = createOAuthMetadataRoutes(options);
+  const clientIdentificationRoutes = createOAuthClientIdentificationRoutes();
+  return {
+    prefix: '',
+    routes: [...metadataRoutes.routes, ...clientIdentificationRoutes.routes],
+  };
+}

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

@@ -29,6 +29,10 @@ const policies: Record<
   lookup: {
     ip: {limit: 60, windowSeconds: 5 * 60},
   },
+  directory: {
+    ip: {limit: 60, windowSeconds: 5 * 60},
+    actor: {limit: 60, windowSeconds: 5 * 60},
+  },
   impersonate: {
     // Bounds mint and probing attempts: the IP bucket bounds aggregate source
     // traffic, and the actor bucket is a per-actor cap that prevents an actor
@@ -39,6 +43,18 @@ const policies: Record<
     ip: {limit: 20, windowSeconds: 15 * 60},
     actor: {limit: 20, windowSeconds: 15 * 60},
   },
+  'oauth-register': {
+    ip: {limit: 10, windowSeconds: 60 * 60},
+  },
+  'oauth-cimd': {
+    ip: {limit: 30, windowSeconds: 60 * 60},
+  },
+  'oauth-authorize': {
+    ip: {limit: 30, windowSeconds: 5 * 60},
+  },
+  'oauth-token': {
+    ip: {limit: 60, windowSeconds: 5 * 60},
+  },
 };
 
 interface EmailBody {

package/src/presentation/routes/registration/signup.ts

@@ -15,6 +15,57 @@ import {SIGNUP_DENIAL_MESSAGE_MAX_LENGTH, type SignupPolicy} from '#core/ports.j
 import {setRefreshTokenCookie} from '#presentation/auth/refresh-cookie.js';
 import {toUserDto} from '#presentation/dto/user.js';
 
+function handleEmailChallengeError(error: unknown): void {
+  if (!(error instanceof EmailChallengeError)) return;
+  throw new ClientError(error.message, `email-challenge-${error.code}`, {
+    status: error.code === 'limited' ? 429 : 400,
+    ...(error.retryAt ? {details: {retry_at: error.retryAt.toISOString()}} : {}),
+  });
+}
+
+function handleSignupPolicyError(error: unknown): void {
+  if (error instanceof EmailTakenError) {
+    throw new ClientError('Email already registered', 'email-taken', {status: 409});
+  }
+  if (error instanceof SignupNotAllowedError) {
+    const message = error.message.slice(0, SIGNUP_DENIAL_MESSAGE_MAX_LENGTH);
+    throw new ClientError(message, 'signup-not-allowed', {
+      status: 403,
+      details: {message, ...(error.format ? {format: error.format} : {})},
+    });
+  }
+}
+
+function handleInvitationError(error: unknown): void {
+  if (error instanceof TokenInvalidError) {
+    throw new ClientError('Invitation token is invalid', 'invitation-token-invalid', {status: 410});
+  }
+  if (error instanceof TokenAlreadyUsedError) {
+    throw new ClientError('Invitation has already been accepted', 'invitation-token-used', {
+      status: 410,
+    });
+  }
+  if (error instanceof TokenExpiredError) {
+    throw new ClientError('Invitation has expired', 'invitation-token-expired', {status: 410});
+  }
+  if (error instanceof InvitationEmailMismatchError) {
+    throw new ClientError(
+      'Signup email does not match the invitation',
+      'invitation-email-mismatch',
+      {
+        status: 403,
+      },
+    );
+  }
+}
+
+function handleSignupError(error: unknown): never {
+  handleEmailChallengeError(error);
+  handleSignupPolicyError(error);
+  handleInvitationError(error);
+  throw error;
+}
+
 export function createSignupRoute(
   workspaces: WorkspacesInterModuleClient,
   signupPolicy?: SignupPolicy,
@@ -30,47 +81,7 @@ export function createSignupRoute(
         201: signupResponseSchema,
       },
     },
-    errorHandler: (error) => {
-      if (error instanceof EmailChallengeError) {
-        throw new ClientError(error.message, `email-challenge-${error.code}`, {
-          status: error.code === 'limited' ? 429 : 400,
-          ...(error.retryAt ? {details: {retry_at: error.retryAt.toISOString()}} : {}),
-        });
-      }
-      if (error instanceof EmailTakenError) {
-        throw new ClientError('Email already registered', 'email-taken', {status: 409});
-      }
-      if (error instanceof SignupNotAllowedError) {
-        const message = error.message.slice(0, SIGNUP_DENIAL_MESSAGE_MAX_LENGTH);
-        throw new ClientError(message, 'signup-not-allowed', {
-          status: 403,
-          details: {message, ...(error.format ? {format: error.format} : {})},
-        });
-      }
-      if (error instanceof TokenInvalidError) {
-        throw new ClientError('Invitation token is invalid', 'invitation-token-invalid', {
-          status: 410,
-        });
-      }
-      if (error instanceof TokenAlreadyUsedError) {
-        throw new ClientError('Invitation has already been accepted', 'invitation-token-used', {
-          status: 410,
-        });
-      }
-      if (error instanceof TokenExpiredError) {
-        throw new ClientError('Invitation has expired', 'invitation-token-expired', {
-          status: 410,
-        });
-      }
-      if (error instanceof InvitationEmailMismatchError) {
-        throw new ClientError(
-          'Signup email does not match the invitation',
-          'invitation-email-mismatch',
-          {status: 403},
-        );
-      }
-      throw error;
-    },
+    errorHandler: handleSignupError,
     handler: async (request, reply) => {
       const {email, password, name, invitation_token} = request.body;
 

package/src/temporal/activities/agent-access-retention.ts

@@ -0,0 +1,76 @@
+import {Context} from '@temporalio/activity';
+import {pruneAgentAccessBatch} from '#db/agent-access.js';
+import {
+  AGENT_ACCESS_RETENTION_BATCH_LIMIT,
+  AGENT_ACCESS_RETENTION_MAX_ITERATIONS,
+  AGENT_ACCESS_RETENTION_TIME_BUDGET_MS,
+} from '#db/agent-access-retention.js';
+
+export interface AgentAccessRetentionResult {
+  deleted: number;
+  transitioned: number;
+  iterations: number;
+  timedOut: boolean;
+}
+
+function isAgentAccessRetentionTimeout(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  const details = error as {cause?: unknown; code?: unknown};
+  if (details.code === '55P03' || details.code === '57014') return true;
+  return details.cause !== undefined && details.cause !== error
+    ? isAgentAccessRetentionTimeout(details.cause)
+    : false;
+}
+
+/**
+ * Drains bounded retention batches for the current tick. Heartbeats continue
+ * while a database batch waits on a lock, and the wall-clock budget keeps the
+ * activity inside its five-minute Temporal start-to-close timeout.
+ */
+export async function agentAccessRetentionActivity(): Promise<AgentAccessRetentionResult> {
+  const ctx = Context.current();
+  const startedAt = Date.now();
+  const deadline = startedAt + AGENT_ACCESS_RETENTION_TIME_BUDGET_MS;
+  const result: AgentAccessRetentionResult = {
+    deleted: 0,
+    transitioned: 0,
+    iterations: 0,
+    timedOut: false,
+  };
+  const heartbeat = () => ctx.heartbeat(result);
+  const heartbeatTimer = setInterval(heartbeat, 15_000);
+
+  try {
+    while (result.iterations < AGENT_ACCESS_RETENTION_MAX_ITERATIONS) {
+      if (Date.now() >= deadline) {
+        result.timedOut = true;
+        break;
+      }
+
+      try {
+        const batch = await pruneAgentAccessBatch({
+          limit: AGENT_ACCESS_RETENTION_BATCH_LIMIT,
+          deadlineMs: deadline,
+        });
+        result.deleted += batch.deleted;
+        result.transitioned += batch.transitioned;
+        result.iterations += 1;
+        heartbeat();
+
+        if (batch.deleted === 0 && batch.transitioned === 0) break;
+      } catch (error) {
+        if (!isAgentAccessRetentionTimeout(error)) throw error;
+        result.timedOut = true;
+        break;
+      }
+    }
+
+    if (result.iterations >= AGENT_ACCESS_RETENTION_MAX_ITERATIONS) {
+      result.timedOut = true;
+    }
+    heartbeat();
+    return result;
+  } finally {
+    clearInterval(heartbeatTimer);
+  }
+}

package/src/temporal/activities/index.ts

@@ -0,0 +1,5 @@
+import {agentAccessRetentionActivity} from './agent-access-retention.js';
+
+export function createAuthMaintenanceActivities() {
+  return {agentAccessRetentionActivity};
+}

package/src/temporal/constants.ts

@@ -0,0 +1 @@
+export const AUTH_AGENT_ACCESS_MAINTENANCE_TASK_QUEUE = 'auth-agent-access-maintenance';

package/src/temporal/workflows/agent-access-retention-cron.ts

@@ -0,0 +1,23 @@
+import {log, proxyActivities} from '@temporalio/workflow';
+import type {createAuthMaintenanceActivities} from '../activities/index.js';
+
+const {agentAccessRetentionActivity} = proxyActivities<
+  ReturnType<typeof createAuthMaintenanceActivities>
+>({
+  startToCloseTimeout: '5 minutes',
+  heartbeatTimeout: '1 minute',
+  // Retry on the next cron tick so a timed-out attempt cannot overlap its own sweep.
+  retry: {maximumAttempts: 1},
+});
+
+export async function agentAccessRetentionCron(): Promise<void> {
+  const result = await agentAccessRetentionActivity();
+  if (result.deleted > 0 || result.transitioned > 0 || result.timedOut) {
+    log.info('Agent-access retention sweep complete', {
+      deleted: result.deleted,
+      transitioned: result.transitioned,
+      iterations: result.iterations,
+      timedOut: result.timedOut,
+    });
+  }
+}

package/src/temporal/workflows/index.ts

@@ -0,0 +1 @@
+export {agentAccessRetentionCron} from './agent-access-retention-cron.js';

package/test/globalSetup.ts

@@ -16,7 +16,7 @@ export async function setup() {
   await initializeEmailChallengesForTests();
   await resetEmailChallengesForTests();
   await db().execute(
-    sql`TRUNCATE auth_admin_command_results, auth_admin_grants, auth_outbox, auth_password_resets, auth_rate_limits, auth_refresh_tokens, auth_users CASCADE`,
+    sql`TRUNCATE auth_agent_pats, auth_agent_refresh_tokens, auth_agent_authorization_codes, auth_agent_grants, auth_agent_authorization_requests, auth_agent_clients, 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

@@ -151,7 +151,9 @@ export function extractToken(url: string): string {
 
 export function getSetCookie(res: {headers: OutgoingHttpHeaders}): string {
   const header = res.headers['set-cookie'];
-  const value = Array.isArray(header) ? header[0] : typeof header === 'string' ? header : undefined;
+  let value: string | undefined;
+  if (Array.isArray(header)) value = header[0];
+  else if (typeof header === 'string') value = header;
   expect(value).toBeDefined();
   return value ?? '';
 }