@shipfox/api-auth 19.0.0 → 20.0.0

package/src/index.test.ts

@@ -1,12 +1,21 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
 import {
   AUTH_PASSWORD_RESET_SEND_REQUESTED,
   AUTH_USER_SIGNED_UP,
   authEventSchemas,
 } from '@shipfox/api-auth-dto';
 import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
+import {createAuthMaintenanceActivities} from '#temporal/activities/index.js';
 import {createAuthModule} from './index.js';
 import {passwordLoginMethods} from './login-methods.js';
 
+const expectedWorkflowsPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'dist/temporal/workflows/index.js',
+);
+
 type SignupPolicyLike = {
   isSignupAllowed(params: {
     email: string;
@@ -110,4 +119,22 @@ describe('authModule', () => {
     ]);
     expect(events).toEqual(expect.arrayContaining([AUTH_PASSWORD_RESET_SEND_REQUESTED]));
   });
+
+  test('registers the agent-access retention worker', () => {
+    const worker = authModule.workers?.[0];
+    expect(worker).toEqual(
+      expect.objectContaining({
+        taskQueue: 'auth-agent-access-maintenance',
+        workflowsPath: expectedWorkflowsPath,
+        workflows: [
+          {
+            name: 'agentAccessRetentionCron',
+            id: 'auth-agent-access-retention',
+            cronSchedule: '10 * * * *',
+          },
+        ],
+      }),
+    );
+    expect(worker?.activities).toBe(createAuthMaintenanceActivities);
+  });
 });

package/src/index.ts

@@ -1,3 +1,5 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
 import {
   AUTH_PASSWORD_RESET_SEND_REQUESTED,
   type AuthEventMap,
@@ -24,9 +26,13 @@ import {
 } from '#presentation/routes/administration.js';
 import {buildAuthRoutes} from '#presentation/routes/index.js';
 import {onPasswordResetSendRequested} from '#presentation/subscribers/index.js';
+import {createAuthMaintenanceActivities} from '#temporal/activities/index.js';
+import {AUTH_AGENT_ACCESS_MAINTENANCE_TASK_QUEUE} from '#temporal/constants.js';
 import {passwordLoginMethods} from './login-methods.js';
 
 const authPublisherEventSchemas = {...authEventSchemas, ...administrationActionEventSchemas};
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const workflowsPath = resolve(packageRoot, 'dist/temporal/workflows/index.js');
 
 export type {AdminRole, JobLeaseTokenClaims, RunnerSessionTokenClaims} from '@shipfox/api-auth-dto';
 export {
@@ -60,6 +66,20 @@ export type {
   ProvisionUserParams,
 } from '#core/auth.js';
 export {createImpersonatedSessionToken, createSessionForUser, provisionUser} from '#core/auth.js';
+export type {
+  CimdAddress,
+  CimdAddressResolver,
+  CimdHttpRequester,
+  CimdHttpResponse,
+  FetchCimdMetadataOptions,
+  FetchedCimdMetadata,
+} from '#core/cimd.js';
+export {
+  fetchClientIdMetadata,
+  isPublicUnicastAddress,
+  OAUTH_CIMD_FETCH_TIMEOUT_MS,
+  OAUTH_CIMD_MAX_BODY_BYTES,
+} from '#core/cimd.js';
 export type {EmailOwner, FindUserByEmailParams} from '#core/email-owner.js';
 export {findUserByEmail} from '#core/email-owner.js';
 export type {AdminGrant} from '#core/entities/admin-grant.js';
@@ -80,7 +100,11 @@ export {
   InvalidAdminBootstrapTokenError,
   InvalidAdministratorUserDirectoryFilterError,
   InvalidCredentialsError,
+  InvalidOAuthClientMetadataError,
+  InvalidOAuthConfigurationError,
   LastAdminOwnerError,
+  OAuthMetadataFetchError,
+  OAuthRedirectUriNotRegisteredError,
   SignupNotAllowedError,
   UserNotFoundError,
 } from '#core/errors.js';
@@ -89,6 +113,38 @@ export {
   jobLeaseParamsFrom,
   verifyJobLeaseToken,
 } from '#core/job-lease-token.js';
+export type {OAuthGrantType, ValidatedOAuthClientMetadata} from '#core/oauth-client.js';
+export {
+  assertOAuthClientMetadataMatchesRequest,
+  assertOAuthRedirectUriRegistered,
+  isOAuthLoopbackRedirectUri,
+  metadataForAgentClient,
+  OAUTH_CIMD_CACHE_MAX_AGE_SECONDS,
+  OAUTH_CLIENT_ID_MAX_BYTES,
+  OAUTH_CLIENT_NAME_MAX_BYTES,
+  OAUTH_REDIRECT_URI_MAX_BYTES,
+  OAUTH_REDIRECT_URI_MAX_COUNT,
+  oauthRedirectUriMatches,
+  validateOAuthClientId,
+  validateOAuthClientMetadataDocument,
+  validateOAuthDynamicClientRegistration,
+  validateOAuthPublicOrigin,
+  validateOAuthRedirectUri,
+} from '#core/oauth-client.js';
+export type {
+  OAuthClientResolver,
+  OAuthClientResolverOptions,
+  RegisteredOAuthClient,
+  RegisterOAuthClientParams,
+  ResolvedOAuthClient,
+  ResolveOAuthClientParams,
+} from '#core/oauth-client-resolver.js';
+export {
+  createOAuthClientResolver,
+  OAUTH_CIMD_CACHE_MAX_ENTRIES,
+  registerOAuthClient,
+  resolveOAuthClient,
+} from '#core/oauth-client-resolver.js';
 export type {SignupDenialMessageFormat, SignupPolicy} from '#core/ports.js';
 export {
   issueRunnerSessionToken,
@@ -114,6 +170,12 @@ export {
   setRefreshTokenCookie,
 } from '#presentation/auth/refresh-cookie.js';
 export {createRunnerSessionAuthMethod} from '#presentation/auth/runner-session-auth.js';
+export type {CreateOAuthRoutesOptions} from '#presentation/routes/oauth.js';
+export {
+  createOAuthClientIdentificationRoutes,
+  createOAuthMetadataRoutes,
+  createOAuthRoutes,
+} from '#presentation/routes/oauth.js';
 
 const subscriber = subscriberFactory<AuthEventMap>();
 
@@ -140,6 +202,20 @@ export function createAuthModule({
     e2eRoutes: [createAuthE2eRoutes(workspaces)],
     publishers: [{name: 'auth', table: authOutbox, db, eventSchemas: authPublisherEventSchemas}],
     subscribers: [subscriber(AUTH_PASSWORD_RESET_SEND_REQUESTED, onPasswordResetSendRequested)],
+    workers: [
+      {
+        taskQueue: AUTH_AGENT_ACCESS_MAINTENANCE_TASK_QUEUE,
+        workflowsPath,
+        activities: createAuthMaintenanceActivities,
+        workflows: [
+          {
+            name: 'agentAccessRetentionCron',
+            id: 'auth-agent-access-retention',
+            cronSchedule: '10 * * * *',
+          },
+        ],
+      },
+    ],
     interModulePresentations: [createAuthInterModulePresentation()],
   };
 }

package/src/metrics/instance.ts

@@ -10,7 +10,11 @@ export type AuthRateLimitAction =
   | 'bootstrap-state'
   | 'lookup'
   | 'directory'
-  | 'impersonate';
+  | 'impersonate'
+  | 'oauth-register'
+  | 'oauth-cimd'
+  | 'oauth-authorize'
+  | 'oauth-token';
 export type AuthRateLimitScope = 'ip' | 'email' | 'actor';
 export type AuthRateLimitOutcome = 'allowed' | 'blocked' | 'unavailable';
 export type AuthImpersonationOutcome = 'succeeded' | 'failed';

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

@@ -43,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/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';