@shipfox/api-auth 19.0.0 → 20.0.0

package/src/core/oauth-client-resolver.test.ts

@@ -0,0 +1,198 @@
+import {describe, expect, it, vi} from '@shipfox/vitest/vi';
+import type {AgentClient} from './entities/agent-access.js';
+import {InvalidOAuthClientMetadataError} from './errors.js';
+import {OAUTH_CIMD_CACHE_MAX_AGE_SECONDS} from './oauth-client.js';
+import {
+  createOAuthClientResolver,
+  OAUTH_CIMD_CACHE_MAX_ENTRIES,
+  type ResolvedOAuthClient,
+  registerOAuthClient,
+} from './oauth-client-resolver.js';
+
+const clientId = 'https://client.example/.well-known/oauth-client';
+const redirectUri = 'https://client.example/callback';
+
+function client(overrides: Partial<AgentClient> = {}): AgentClient {
+  const now = new Date('2026-09-01T00:00:00.000Z');
+  return {
+    id: crypto.randomUUID(),
+    clientId,
+    name: 'Desktop agent',
+    redirectUris: [redirectUri],
+    kind: 'cimd',
+    lastSeenAt: now,
+    unreferencedAt: null,
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+function fetched(): ResolvedOAuthClient['metadata'] {
+  return {
+    clientId,
+    clientName: 'Desktop agent',
+    redirectUris: [redirectUri],
+    grantTypes: ['authorization_code'],
+    responseTypes: ['code'],
+    tokenEndpointAuthMethod: 'none',
+    scope: 'read',
+  };
+}
+
+describe('OAuth client resolver', () => {
+  it('caches successful CIMD resolution while rate limiting every request', async () => {
+    let nowMs = Date.parse('2026-09-01T00:00:00.000Z');
+    const findClient = vi.fn(async () => undefined);
+    const fetchMetadata = vi.fn(async () => ({metadata: fetched(), cacheMaxAgeSeconds: 60}));
+    const upsertCimdClient = vi.fn(async () => client());
+    const checkCimdRateLimit = vi.fn(async () => undefined);
+    const resolver = createOAuthClientResolver({
+      findClient,
+      fetchMetadata,
+      upsertCimdClient,
+      checkCimdRateLimit,
+      now: () => new Date(nowMs),
+    });
+
+    const first = await resolver.resolve({clientId, requestIp: '198.51.100.10', redirectUri});
+    nowMs += 30_000;
+    const second = await resolver.resolve({clientId, requestIp: '198.51.100.10', redirectUri});
+    nowMs += 31_000;
+    const third = await resolver.resolve({clientId, requestIp: '198.51.100.10', redirectUri});
+
+    expect(first).toEqual(second);
+    expect(third).not.toEqual(first);
+    expect(fetchMetadata).toHaveBeenCalledTimes(2);
+    expect(upsertCimdClient).toHaveBeenCalledTimes(2);
+    expect(findClient).toHaveBeenCalledTimes(2);
+    expect(checkCimdRateLimit).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not cache a no-store CIMD response', async () => {
+    const findClient = vi.fn(async () => undefined);
+    const fetchMetadata = vi.fn(async () => ({metadata: fetched(), cacheMaxAgeSeconds: 0}));
+    const resolver = createOAuthClientResolver({
+      findClient,
+      fetchMetadata,
+      upsertCimdClient: async () => client(),
+      checkCimdRateLimit: async () => undefined,
+    });
+
+    await resolver.resolve({clientId, requestIp: '198.51.100.10'});
+    await resolver.resolve({clientId, requestIp: '198.51.100.10'});
+
+    expect(fetchMetadata).toHaveBeenCalledTimes(2);
+  });
+
+  it('clamps CIMD cache freshness to the process maximum', async () => {
+    let nowMs = Date.parse('2026-09-01T00:00:00.000Z');
+    const fetchMetadata = vi.fn(async () => ({metadata: fetched(), cacheMaxAgeSeconds: 999_999}));
+    const resolver = createOAuthClientResolver({
+      findClient: async () => undefined,
+      fetchMetadata,
+      upsertCimdClient: async () => client(),
+      checkCimdRateLimit: async () => undefined,
+      now: () => new Date(nowMs),
+    });
+
+    await resolver.resolve({clientId, requestIp: '198.51.100.10'});
+    nowMs += (OAUTH_CIMD_CACHE_MAX_AGE_SECONDS + 1) * 1000;
+    await resolver.resolve({clientId, requestIp: '198.51.100.10'});
+
+    expect(fetchMetadata).toHaveBeenCalledTimes(2);
+  });
+
+  it('bounds the number of cached CIMD clients', async () => {
+    const clientIds = Array.from(
+      {length: OAUTH_CIMD_CACHE_MAX_ENTRIES + 1},
+      (_, index) => `https://client.example/.well-known/oauth-client-${index}`,
+    );
+    const fetchMetadata = vi.fn(async (resolvedClientId: string) => ({
+      metadata: {...fetched(), clientId: resolvedClientId},
+      cacheMaxAgeSeconds: 60,
+    }));
+    const resolver = createOAuthClientResolver({
+      findClient: async () => undefined,
+      fetchMetadata,
+      upsertCimdClient: async (params) => client({clientId: params.clientId}),
+      checkCimdRateLimit: async () => undefined,
+    });
+
+    for (const resolvedClientId of clientIds) {
+      await resolver.resolve({clientId: resolvedClientId, requestIp: '198.51.100.10'});
+    }
+    const firstClientId = clientIds[0];
+    if (firstClientId === undefined) throw new Error('Expected a non-empty client ID list');
+    await resolver.resolve({clientId: firstClientId, requestIp: '198.51.100.10'});
+
+    expect(fetchMetadata).toHaveBeenCalledTimes(clientIds.length + 1);
+  });
+
+  it('requires a source IP before resolving CIMD metadata', async () => {
+    const fetchMetadata = vi.fn();
+    const checkCimdRateLimit = vi.fn(async () => undefined);
+    const resolver = createOAuthClientResolver({
+      findClient: async () => undefined,
+      fetchMetadata,
+      checkCimdRateLimit,
+    });
+
+    await expect(resolver.resolve({clientId})).rejects.toBeInstanceOf(
+      InvalidOAuthClientMetadataError,
+    );
+    expect(fetchMetadata).not.toHaveBeenCalled();
+    expect(checkCimdRateLimit).not.toHaveBeenCalled();
+  });
+
+  it('returns registered clients without treating opaque IDs as CIMD URLs', async () => {
+    const registered = client({clientId: 'client_opaque', kind: 'registered'});
+    const fetchMetadata = vi.fn();
+    const checkCimdRateLimit = vi.fn(async () => undefined);
+    const resolver = createOAuthClientResolver({
+      findClient: async () => registered,
+      fetchMetadata,
+      checkCimdRateLimit,
+    });
+
+    const result = await resolver.resolve({
+      clientId: registered.clientId,
+      requestIp: '198.51.100.10',
+      redirectUri,
+    });
+
+    expect(result.kind).toBe('registered');
+    expect(result.client).toBe(registered);
+    expect(fetchMetadata).not.toHaveBeenCalled();
+    expect(checkCimdRateLimit).not.toHaveBeenCalled();
+  });
+
+  it('rejects a redirect before persisting a fetched client', async () => {
+    const upsertCimdClient = vi.fn(async () => client());
+    const resolver = createOAuthClientResolver({
+      findClient: async () => undefined,
+      fetchMetadata: async () => ({metadata: fetched(), cacheMaxAgeSeconds: 60}),
+      upsertCimdClient,
+      checkCimdRateLimit: async () => undefined,
+    });
+
+    await expect(
+      resolver.resolve({
+        clientId,
+        requestIp: '198.51.100.10',
+        redirectUri: 'https://client.example/other',
+      }),
+    ).rejects.toMatchObject({name: 'OAuthRedirectUriNotRegisteredError'});
+    expect(upsertCimdClient).not.toHaveBeenCalled();
+  });
+
+  it('does not drop explicitly supplied empty registration values', async () => {
+    await expect(
+      registerOAuthClient({
+        clientName: 'Desktop agent',
+        redirectUris: [redirectUri],
+        scope: '',
+      }),
+    ).rejects.toBeInstanceOf(InvalidOAuthClientMetadataError);
+  });
+});

package/src/core/oauth-client-resolver.ts

@@ -0,0 +1,253 @@
+import {
+  createAgentClient,
+  findAgentClientByClientId,
+  upsertCimdAgentClient,
+} from '#db/agent-access.js';
+import {type FetchedCimdMetadata, fetchClientIdMetadata} from './cimd.js';
+import type {AgentClient} from './entities/agent-access.js';
+import {InvalidOAuthClientMetadataError} from './errors.js';
+import {
+  assertOAuthClientMetadataMatchesRequest,
+  metadataForAgentClient,
+  OAUTH_CIMD_CACHE_MAX_AGE_SECONDS,
+  OAUTH_CLIENT_ID_MAX_BYTES,
+  type OAuthGrantType,
+  type ValidatedOAuthClientMetadata,
+  validateOAuthClientId,
+  validateOAuthDynamicClientRegistration,
+} from './oauth-client.js';
+import {checkAuthRateLimit} from './rate-limit.js';
+
+export interface ResolvedOAuthClient {
+  client: AgentClient;
+  metadata: ValidatedOAuthClientMetadata;
+  kind: AgentClient['kind'];
+}
+
+export interface ResolveOAuthClientParams {
+  clientId: string;
+  requestIp?: string | undefined;
+  redirectUri?: string | undefined;
+  tokenEndpointAuthMethod?: string | undefined;
+}
+
+type FetchMetadata = (clientId: string) => Promise<FetchedCimdMetadata>;
+type FindClient = (params: {clientId: string}) => Promise<AgentClient | undefined>;
+type UpsertCimdClient = (params: {
+  clientId: string;
+  name: string;
+  redirectUris: string[];
+}) => Promise<AgentClient>;
+type CheckCimdRateLimit = (ip: string) => Promise<void>;
+
+interface CachedCimdClient {
+  expiresAt: number;
+  resolved: ResolvedOAuthClient;
+}
+
+export interface OAuthClientResolver {
+  resolve(params: ResolveOAuthClientParams): Promise<ResolvedOAuthClient>;
+  clearCache(): void;
+}
+
+export interface OAuthClientResolverOptions {
+  fetchMetadata?: FetchMetadata;
+  findClient?: FindClient;
+  upsertCimdClient?: UpsertCimdClient;
+  checkCimdRateLimit?: CheckCimdRateLimit;
+  now?: () => Date;
+}
+
+/** Bounds process-wide CIMD metadata retained between authorization requests. */
+export const OAUTH_CIMD_CACHE_MAX_ENTRIES = 1024;
+
+function assertClientIdBounded(clientId: string): void {
+  if (
+    clientId.length === 0 ||
+    clientId.trim() !== clientId ||
+    Buffer.byteLength(clientId, 'utf8') > OAUTH_CLIENT_ID_MAX_BYTES
+  ) {
+    throw new InvalidOAuthClientMetadataError();
+  }
+}
+
+function normalizedCacheAge(seconds: number): number {
+  if (!Number.isFinite(seconds) || seconds <= 0) return 0;
+  return Math.min(Math.floor(seconds), OAUTH_CIMD_CACHE_MAX_AGE_SECONDS);
+}
+
+function pruneExpiredCache(cache: Map<string, CachedCimdClient>, nowMs: number): void {
+  for (const [clientId, cached] of cache) {
+    if (cached.expiresAt <= nowMs) cache.delete(clientId);
+  }
+}
+
+function cacheCimdClient(
+  cache: Map<string, CachedCimdClient>,
+  clientId: string,
+  cached: CachedCimdClient,
+  nowMs: number,
+): void {
+  pruneExpiredCache(cache, nowMs);
+  if (!cache.has(clientId) && cache.size >= OAUTH_CIMD_CACHE_MAX_ENTRIES) {
+    const oldest = cache.keys().next();
+    if (!oldest.done) cache.delete(oldest.value);
+  }
+  cache.set(clientId, cached);
+}
+
+function registeredMetadata(client: AgentClient): ResolvedOAuthClient {
+  return {client, metadata: metadataForAgentClient(client), kind: client.kind};
+}
+
+function assertResolvedClientMatchesRequest(
+  resolved: ResolvedOAuthClient,
+  params: ResolveOAuthClientParams,
+): void {
+  assertOAuthClientMetadataMatchesRequest({
+    metadata: resolved.metadata,
+    redirectUri: params.redirectUri,
+    tokenEndpointAuthMethod: params.tokenEndpointAuthMethod,
+  });
+}
+
+async function resolveCachedClient(
+  params: ResolveOAuthClientParams,
+  cached: CachedCimdClient,
+  checkCimdRateLimit: CheckCimdRateLimit,
+): Promise<ResolvedOAuthClient> {
+  if (params.requestIp === undefined) throw new InvalidOAuthClientMetadataError();
+  await checkCimdRateLimit(params.requestIp);
+  assertResolvedClientMatchesRequest(cached.resolved, params);
+  return cached.resolved;
+}
+
+export function createOAuthClientResolver(
+  options: OAuthClientResolverOptions = {},
+): OAuthClientResolver {
+  const cache = new Map<string, CachedCimdClient>();
+  const now = options.now ?? (() => new Date());
+  const findClient = options.findClient ?? findAgentClientByClientId;
+  const fetchMetadata = options.fetchMetadata ?? ((clientId) => fetchClientIdMetadata(clientId));
+  const upsertCimdClient = options.upsertCimdClient ?? upsertCimdAgentClient;
+  const checkCimdRateLimit =
+    options.checkCimdRateLimit ??
+    (async (requestIp: string) => {
+      await checkAuthRateLimit({
+        action: 'oauth-cimd',
+        scope: 'ip',
+        identifier: requestIp,
+        limit: 30,
+        windowSeconds: 60 * 60,
+      });
+    });
+
+  const resolve = async (params: ResolveOAuthClientParams): Promise<ResolvedOAuthClient> => {
+    assertClientIdBounded(params.clientId);
+
+    const cached = cache.get(params.clientId);
+    if (cached) {
+      if (cached.expiresAt > now().getTime()) {
+        return await resolveCachedClient(params, cached, checkCimdRateLimit);
+      }
+      cache.delete(params.clientId);
+    }
+
+    const existing = await findClient({clientId: params.clientId});
+    if (existing?.kind === 'registered') {
+      const resolved = registeredMetadata(existing);
+      assertResolvedClientMatchesRequest(resolved, params);
+      return resolved;
+    }
+
+    if (params.requestIp === undefined) throw new InvalidOAuthClientMetadataError();
+    await checkCimdRateLimit(params.requestIp);
+    validateOAuthClientId(params.clientId);
+    const fetched = await fetchMetadata(params.clientId);
+    if (fetched.metadata.clientId !== params.clientId) {
+      throw new InvalidOAuthClientMetadataError();
+    }
+    assertOAuthClientMetadataMatchesRequest({
+      metadata: fetched.metadata,
+      redirectUri: params.redirectUri,
+      tokenEndpointAuthMethod: params.tokenEndpointAuthMethod,
+    });
+    const client = await upsertCimdClient({
+      clientId: fetched.metadata.clientId,
+      name: fetched.metadata.clientName,
+      redirectUris: fetched.metadata.redirectUris,
+    });
+    const resolved: ResolvedOAuthClient = {
+      client,
+      metadata: fetched.metadata,
+      kind: 'cimd',
+    };
+    const cacheAge = normalizedCacheAge(fetched.cacheMaxAgeSeconds);
+    if (cacheAge > 0) {
+      const nowMs = now().getTime();
+      cacheCimdClient(
+        cache,
+        params.clientId,
+        {expiresAt: nowMs + cacheAge * 1000, resolved},
+        nowMs,
+      );
+    }
+    return resolved;
+  };
+
+  return {
+    resolve,
+    clearCache: () => cache.clear(),
+  };
+}
+
+export interface RegisterOAuthClientParams {
+  clientName: string;
+  redirectUris: string[];
+  grantTypes?: OAuthGrantType[] | undefined;
+  responseTypes?: 'code'[] | undefined;
+  tokenEndpointAuthMethod?: 'none' | undefined;
+  scope?: string | undefined;
+}
+
+export interface RegisteredOAuthClient {
+  client: AgentClient;
+  metadata: ValidatedOAuthClientMetadata;
+}
+
+export async function registerOAuthClient(
+  input: RegisterOAuthClientParams,
+): Promise<RegisteredOAuthClient> {
+  const validated = validateOAuthDynamicClientRegistration({
+    client_name: input.clientName,
+    redirect_uris: input.redirectUris,
+    ...(input.grantTypes !== undefined ? {grant_types: input.grantTypes} : {}),
+    ...(input.responseTypes !== undefined ? {response_types: input.responseTypes} : {}),
+    ...(input.tokenEndpointAuthMethod !== undefined
+      ? {token_endpoint_auth_method: input.tokenEndpointAuthMethod}
+      : {}),
+    ...(input.scope !== undefined ? {scope: input.scope} : {}),
+  });
+  const client = await createAgentClient({
+    clientId: `client_${crypto.randomUUID()}`,
+    name: validated.clientName,
+    redirectUris: validated.redirectUris,
+    kind: 'registered',
+  });
+  return {
+    client,
+    metadata: {
+      clientId: client.clientId,
+      ...validated,
+    },
+  };
+}
+
+const defaultOAuthClientResolver = createOAuthClientResolver();
+
+export async function resolveOAuthClient(
+  params: ResolveOAuthClientParams,
+  resolver: OAuthClientResolver = defaultOAuthClientResolver,
+): Promise<ResolvedOAuthClient> {
+  return await resolver.resolve(params);
+}

package/src/core/oauth-client.test.ts

@@ -0,0 +1,157 @@
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {
+  InvalidOAuthClientMetadataError,
+  InvalidOAuthConfigurationError,
+  OAuthRedirectUriNotRegisteredError,
+} from './errors.js';
+import {
+  assertOAuthClientMetadataMatchesRequest,
+  assertOAuthRedirectUriRegistered,
+  oauthRedirectUriMatches,
+  validateOAuthClientId,
+  validateOAuthClientMetadataDocument,
+  validateOAuthDynamicClientRegistration,
+  validateOAuthPublicOrigin,
+  validateOAuthRedirectUri,
+} from './oauth-client.js';
+
+describe('OAuth client validation', () => {
+  it('accepts HTTPS redirects and loopback HTTP redirects', () => {
+    expect(validateOAuthRedirectUri('https://client.example/callback').protocol).toBe('https:');
+    expect(validateOAuthRedirectUri('http://localhost:43123/callback').hostname).toBe('localhost');
+    expect(validateOAuthRedirectUri('http://127.0.0.1/callback').hostname).toBe('127.0.0.1');
+    expect(validateOAuthRedirectUri('http://[::1]:43123/callback').hostname).toBe('[::1]');
+  });
+
+  it('allows only a loopback port variation during redirect matching', () => {
+    expect(
+      oauthRedirectUriMatches('http://127.0.0.1:43123/callback', 'http://127.0.0.1:51999/callback'),
+    ).toBe(true);
+    expect(
+      oauthRedirectUriMatches('http://[::1]:43123/callback', 'http://[::1]:51999/callback'),
+    ).toBe(true);
+    expect(
+      oauthRedirectUriMatches('http://127.0.0.1:43123/callback', 'http://127.0.0.1:51999/other'),
+    ).toBe(false);
+    expect(
+      oauthRedirectUriMatches(
+        'http://localhost:43123/callback',
+        'http://localhost:51999/./callback',
+      ),
+    ).toBe(false);
+    expect(
+      oauthRedirectUriMatches(
+        'https://client.example/callback',
+        'https://client.example:443/callback',
+      ),
+    ).toBe(false);
+  });
+
+  it('rejects private-use and non-loopback HTTP redirect schemes', () => {
+    for (const value of [
+      'http://client.example/callback',
+      'com.example.app:/oauth/callback',
+      'https://client.example/callback#fragment',
+      'https://user:password@client.example/callback',
+    ]) {
+      expect(() => validateOAuthRedirectUri(value)).toThrow(InvalidOAuthClientMetadataError);
+    }
+  });
+
+  it('requires CIMD client IDs to be HTTPS URLs with a path', () => {
+    expect(validateOAuthClientId('https://client.example/.well-known/oauth-client').pathname).toBe(
+      '/.well-known/oauth-client',
+    );
+    for (const value of ['https://client.example', 'http://client.example/oauth-client']) {
+      expect(() => validateOAuthClientId(value)).toThrow(InvalidOAuthClientMetadataError);
+    }
+  });
+
+  it('normalizes and validates the injected API origin', () => {
+    expect(validateOAuthPublicOrigin('https://api.example.test/')).toBe('https://api.example.test');
+    expect(validateOAuthPublicOrigin('http://localhost:3000/')).toBe('http://localhost:3000');
+    expect(() => validateOAuthPublicOrigin('https://api.example.test/v1')).toThrow(
+      InvalidOAuthConfigurationError,
+    );
+  });
+
+  it('validates registration bounds and the CIMD identity contract', () => {
+    const registration = validateOAuthDynamicClientRegistration({
+      client_name: 'Desktop agent',
+      redirect_uris: ['https://client.example/callback'],
+      token_endpoint_auth_method: 'none',
+      scope: 'read',
+    });
+    expect(registration).toMatchObject({
+      clientName: 'Desktop agent',
+      responseTypes: ['code'],
+      tokenEndpointAuthMethod: 'none',
+      scope: 'read',
+    });
+
+    expect(() =>
+      validateOAuthDynamicClientRegistration({
+        client_name: 'Desktop agent',
+        redirect_uris: ['https://client.example/callback'],
+        grant_types: ['authorization_code', 'refresh_token'],
+      }),
+    ).toThrow(InvalidOAuthClientMetadataError);
+
+    expect(() =>
+      validateOAuthDynamicClientRegistration({
+        client_name: 'é'.repeat(200),
+        redirect_uris: ['https://client.example/callback'],
+      }),
+    ).toThrow(InvalidOAuthClientMetadataError);
+
+    expect(() =>
+      validateOAuthClientMetadataDocument(
+        {
+          client_id: 'https://client.example/.well-known/oauth-client',
+          client_name: 'Desktop agent',
+          redirect_uris: ['https://client.example/callback'],
+          token_endpoint_auth_method: 'client_secret_basic',
+        },
+        'https://client.example/.well-known/oauth-client',
+      ),
+    ).toThrow(InvalidOAuthClientMetadataError);
+
+    expect(() =>
+      validateOAuthClientMetadataDocument(
+        {
+          client_id: 'https://other.example/.well-known/oauth-client',
+          client_name: 'Desktop agent',
+          redirect_uris: ['https://client.example/callback'],
+        },
+        'https://client.example/.well-known/oauth-client',
+      ),
+    ).toThrow(InvalidOAuthClientMetadataError);
+  });
+
+  it('checks redirect membership and public-client authentication', () => {
+    const metadata = validateOAuthDynamicClientRegistration({
+      client_name: 'Desktop agent',
+      redirect_uris: ['http://127.0.0.1:43123/callback'],
+    });
+    const clientMetadata = {
+      clientId: 'client_123',
+      ...metadata,
+    };
+
+    expect(() =>
+      assertOAuthClientMetadataMatchesRequest({
+        metadata: clientMetadata,
+        redirectUri: 'http://127.0.0.1:43124/callback',
+      }),
+    ).not.toThrow();
+    expect(() =>
+      assertOAuthRedirectUriRegistered(metadata.redirectUris, 'https://other.example/callback'),
+    ).toThrow(OAuthRedirectUriNotRegisteredError);
+    expect(() =>
+      assertOAuthClientMetadataMatchesRequest({
+        metadata: clientMetadata,
+        tokenEndpointAuthMethod: 'client_secret_basic',
+      }),
+    ).toThrow(InvalidOAuthClientMetadataError);
+  });
+});