@shipfox/api-auth 18.0.0 → 20.0.0

package/drizzle/meta/_journal.json

@@ -22,6 +22,20 @@
       "when": 1785075183023,
       "tag": "0002_burly_whizzer",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1788171920746,
+      "tag": "0003_brainy_luckman",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1788195662870,
+      "tag": "0004_yummy_runaways",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-auth",
   "license": "MIT",
-  "version": "18.0.0",
+  "version": "20.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -24,12 +24,14 @@
   "dependencies": {
     "@fastify/cookie": "^11.0.2",
     "@node-rs/argon2": "^2.0.2",
+    "@temporalio/activity": "1.18.1",
+    "@temporalio/workflow": "1.18.1",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
     "@shipfox/api-common-dto": "15.0.0",
-    "@shipfox/api-auth-context": "18.0.0",
-    "@shipfox/api-auth-dto": "18.0.0",
-    "@shipfox/api-email-challenges": "1.1.11",
+    "@shipfox/api-auth-context": "20.0.0",
+    "@shipfox/api-auth-dto": "20.0.0",
+    "@shipfox/api-email-challenges": "1.1.12",
     "@shipfox/api-workspaces-dto": "15.0.0",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/config": "1.2.4",
@@ -39,12 +41,13 @@
     "@shipfox/node-jwt": "0.4.0",
     "@shipfox/node-email": "0.3.5",
     "@shipfox/node-mailer": "0.2.6",
-    "@shipfox/node-module": "1.0.7",
+    "@shipfox/node-module": "1.0.8",
     "@shipfox/node-opentelemetry": "0.6.5",
-    "@shipfox/node-outbox": "0.2.6",
+    "@shipfox/node-outbox": "0.2.7",
     "@shipfox/node-postgres": "0.5.1",
     "@shipfox/node-rate-limit": "0.4.0",
-    "@shipfox/node-tokens": "1.0.0"
+    "@shipfox/node-temporal": "0.4.6",
+    "@shipfox/node-tokens": "1.1.0"
   },
   "imports": {
     "#*": "./dist/*"
@@ -58,7 +61,7 @@
     }
   },
   "scripts": {
-    "build": "shipfox-swc",
+    "build": "shipfox-swc && shipfox-temporal-bundle dist/temporal/workflows/index.js",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
     "depcruise": "shipfox-depcruise",

package/src/core/admin-role.test.ts

@@ -1,7 +1,11 @@
 import {createAdminGrant} from '#db/admin-grants.js';
+import {db} from '#db/db.js';
+import {users} from '#db/schema/users.js';
 import {userFactory} from '#test/index.js';
 import {hasMinimumAdminRole, highestAdminRole, requireAdminRole} from './admin-role.js';
+import {listAdministratorUsers} from './administration.js';
 import type {AdminRoleRequiredError} from './errors.js';
+import {InvalidAdministratorUserDirectoryFilterError} from './errors.js';
 
 describe('admin role policy', () => {
   test.each([
@@ -23,6 +27,72 @@ describe('admin role policy', () => {
     expect(highestAdminRole([])).toBeNull();
   });
 
+  test('protects the administrator user directory with the observer role', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+
+    await expect(listAdministratorUsers({actorId: user.id, limit: 10})).rejects.toEqual(
+      expect.objectContaining<Partial<AdminRoleRequiredError>>({
+        minimumRole: 'admin-observer',
+      }),
+    );
+  });
+
+  test('bounds administrator user directory search input', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-observer'});
+
+    await expect(
+      listAdministratorUsers({
+        actorId: user.id,
+        limit: 10,
+        search: Array.from({length: 11}, () => 'term').join(' '),
+      }),
+    ).rejects.toThrow('at most 10 terms');
+    await expect(
+      listAdministratorUsers({actorId: user.id, limit: 10, search: 'x'.repeat(101)}),
+    ).rejects.toThrow('at most 100 characters');
+  });
+
+  test('rejects an active eligibility filter combined with a non-active status', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-observer'});
+
+    await expect(
+      listAdministratorUsers({
+        actorId: user.id,
+        limit: 10,
+        eligible: true,
+        status: 'suspended',
+      }),
+    ).rejects.toBeInstanceOf(InvalidAdministratorUserDirectoryFilterError);
+  });
+
+  test('caps the directory page size in the core operation', async () => {
+    const user = await userFactory.create({emailVerifiedAt: new Date()});
+    await createAdminGrant({userId: user.id, role: 'admin-observer'});
+    const marker = `admin-directory-cap-${crypto.randomUUID()}`;
+    await db()
+      .insert(users)
+      .values(
+        Array.from({length: 101}, (_, index) => ({
+          email: `${marker}-${index}@example.com`,
+          name: `Directory User ${index}`,
+          hashedPassword: null,
+          emailVerifiedAt: new Date(),
+        })),
+      );
+
+    const result = await listAdministratorUsers({
+      actorId: user.id,
+      limit: 1_000,
+      search: marker,
+    });
+
+    expect(result.users).toHaveLength(100);
+    expect(result.rows).toEqual(result.users);
+    expect(result.nextCursor).not.toBeNull();
+  });
+
   test('evaluates the current role from Auth storage for every required minimum', async () => {
     const user = await userFactory.create({emailVerifiedAt: new Date()});
     await createAdminGrant({userId: user.id, role: 'admin-operator'});

package/src/core/administration.ts

@@ -18,7 +18,10 @@ import {
   suspendUserWithAudit,
   type UserModerationResult,
 } from '#db/admin-user-moderation.js';
-import {findAdministratorUser as findAdministratorUserInDb} from '#db/admin-users.js';
+import {
+  findAdministratorUser as findAdministratorUserInDb,
+  listAdministratorUsers as listAdministratorUsersInDb,
+} from '#db/admin-users.js';
 import {
   type ImpersonationResult,
   impersonateUserWithAudit,
@@ -45,6 +48,7 @@ import {
   ImpersonationExpiredError,
   ImpersonationTargetNotActiveError,
   InvalidAdminBootstrapTokenError,
+  InvalidAdministratorUserDirectoryFilterError,
   InvalidCredentialsError,
   LastAdminOwnerError,
   UserNotFoundError,
@@ -53,6 +57,10 @@ import {
 const ADMIN_OWNER_ROLE: AdminRole = 'admin-owner';
 const ADMIN_OBSERVER_ROLE: AdminRole = 'admin-observer';
 const ADMIN_OPERATOR_ROLE: AdminRole = 'admin-operator';
+const ADMINISTRATOR_DIRECTORY_MAX_PAGE_SIZE = 100;
+const ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERMS = 10;
+const ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERM_LENGTH = 100;
+const ADMINISTRATOR_DIRECTORY_SEARCH_TERM_SEPARATOR = /\s+/g;
 const BOOTSTRAP_COMMAND = 'auth.admin_grant.bootstrap';
 const GRANT_COMMAND = 'auth.admin_grant.grant';
 const REVOKE_COMMAND = 'auth.admin_grant.revoke';
@@ -192,6 +200,75 @@ export async function findAdministratorUserSummary(
   return user;
 }
 
+export interface ListAdministratorUsersParams {
+  actorId: string;
+  limit: number;
+  cursor?: TimestampIdCursor | undefined;
+  search?: string | undefined;
+  status?: AdministratorUserSummary['status'] | undefined;
+  eligible?: boolean | undefined;
+}
+
+export interface ListAdministratorUsersResult {
+  /** Retained for compatibility with the original database-shaped result. */
+  rows: AdministratorUserSummary[];
+  users: AdministratorUserSummary[];
+  nextCursor: TimestampIdCursor | null;
+}
+
+function normalizeAdministratorUserDirectorySearch(search: string | undefined): string | undefined {
+  const normalizedSearch = search
+    ?.trim()
+    .replace(ADMINISTRATOR_DIRECTORY_SEARCH_TERM_SEPARATOR, ' ');
+  if (!normalizedSearch) return;
+
+  const terms = normalizedSearch.split(' ');
+  if (terms.length > ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERMS) {
+    throw new InvalidAdministratorUserDirectoryFilterError(
+      `Administrator user directory search accepts at most ${ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERMS} terms`,
+    );
+  }
+
+  if (terms.some((term) => term.length > ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERM_LENGTH)) {
+    throw new InvalidAdministratorUserDirectoryFilterError(
+      `Administrator user directory search terms must be at most ${ADMINISTRATOR_DIRECTORY_MAX_SEARCH_TERM_LENGTH} characters`,
+    );
+  }
+
+  return normalizedSearch;
+}
+
+function validateAdministratorUserDirectoryFilters(
+  params: ListAdministratorUsersParams,
+): string | undefined {
+  const normalizedSearch = normalizeAdministratorUserDirectorySearch(params.search);
+  if (params.eligible === true && params.status && params.status !== 'active') {
+    throw new InvalidAdministratorUserDirectoryFilterError(
+      'eligible users must have active status',
+    );
+  }
+  return normalizedSearch;
+}
+
+export async function listAdministratorUsers(
+  params: ListAdministratorUsersParams,
+): Promise<ListAdministratorUsersResult> {
+  await requireAdminRole({userId: params.actorId, minimumRole: ADMIN_OBSERVER_ROLE});
+  const normalizedSearch = validateAdministratorUserDirectoryFilters(params);
+  const result = await listAdministratorUsersInDb({
+    ...params,
+    limit: Math.min(params.limit, ADMINISTRATOR_DIRECTORY_MAX_PAGE_SIZE),
+    search: normalizedSearch,
+  });
+  return {
+    rows: result.rows,
+    // Keep the original `rows` result while exposing the domain-named field
+    // used by the directory route.
+    users: result.rows,
+    nextCursor: result.nextCursor,
+  };
+}
+
 export async function listAdministratorGrantSummaries(params: {
   actorId: string;
   limit: number;

package/src/core/auth.ts

@@ -442,11 +442,9 @@ export type CreateSessionForUserError =
 export async function createSessionForUser(
   params: CreateSessionForUserParams,
 ): Promise<CreateSessionForUserResult> {
-  const user = params.userId
-    ? await findUserById({id: params.userId})
-    : params.email
-      ? await findUserByEmail({email: emailSchema.parse(params.email)})
-      : undefined;
+  let user: User | undefined;
+  if (params.userId) user = await findUserById({id: params.userId});
+  else if (params.email) user = await findUserByEmail({email: emailSchema.parse(params.email)});
 
   if (!user) {
     throw new UserNotFoundError(params.userId ?? params.email ?? 'unknown');

package/src/core/cimd.test.ts

@@ -0,0 +1,213 @@
+import {describe, expect, it, vi} from '@shipfox/vitest/vi';
+import {
+  type CimdAddress,
+  type CimdHttpResponse,
+  fetchClientIdMetadata,
+  isPublicUnicastAddress,
+} from './cimd.js';
+import {InvalidOAuthClientMetadataError} from './errors.js';
+
+const clientId = 'https://client.example/.well-known/oauth-client';
+const publicAddress: CimdAddress = {address: '93.184.216.34', family: 4};
+const validDocument = {
+  client_id: clientId,
+  client_name: 'Desktop agent',
+  redirect_uris: ['https://client.example/callback'],
+  token_endpoint_auth_method: 'none',
+};
+
+function response(
+  document: unknown,
+  headers: Record<string, string | string[] | undefined> = {},
+  statusCode = 200,
+) {
+  return {
+    statusCode,
+    headers,
+    body: Buffer.from(JSON.stringify(document)),
+  };
+}
+
+describe('CIMD fetch', () => {
+  it('allows global unicast addresses and rejects special-use ranges', () => {
+    expect(isPublicUnicastAddress('93.184.216.34', 4)).toBe(true);
+    for (const address of [
+      '10.0.0.1',
+      '127.0.0.1',
+      '169.254.1.1',
+      '172.16.0.1',
+      '192.168.1.1',
+      '192.88.99.1',
+      '224.0.0.1',
+    ]) {
+      expect(isPublicUnicastAddress(address, 4)).toBe(false);
+    }
+    expect(isPublicUnicastAddress('2001:4860:4860::8888', 6)).toBe(true);
+    expect(isPublicUnicastAddress('2001:db8::1', 6)).toBe(false);
+    expect(isPublicUnicastAddress('fe80::1', 6)).toBe(false);
+    for (const address of ['2002:0a00:0001::1', '::ffff:10.0.0.1', '::', '1::2::3']) {
+      expect(isPublicUnicastAddress(address, 6)).toBe(false);
+    }
+    expect(isPublicUnicastAddress('fe80::1%eth0', 6)).toBe(false);
+  });
+
+  it('resolves once and passes the pinned public address to the request', async () => {
+    const resolveAddress = vi.fn(async () => [publicAddress]);
+    const request = vi.fn((params: {address: CimdAddress}) => {
+      expect(params.address).toEqual(publicAddress);
+      return Promise.resolve(response(validDocument, {'cache-control': 'max-age=30'}));
+    });
+
+    const result = await fetchClientIdMetadata(clientId, {resolveAddress, request});
+
+    expect(resolveAddress).toHaveBeenCalledTimes(1);
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(result.metadata).toMatchObject({
+      clientId,
+      clientName: 'Desktop agent',
+      redirectUris: ['https://client.example/callback'],
+    });
+    expect(result.cacheMaxAgeSeconds).toBe(30);
+  });
+
+  it('rejects a DNS answer containing a private or link-local address', async () => {
+    const request = vi.fn(async () => response(validDocument));
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress, {address: '169.254.1.1', family: 4}],
+        request,
+      }),
+    ).rejects.toMatchObject({
+      name: 'OAuthMetadataFetchError',
+      reason: 'private-address',
+    });
+    expect(request).not.toHaveBeenCalled();
+  });
+
+  it('rejects redirects, oversized bodies, malformed JSON, and identity mismatches', async () => {
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress],
+        request: async () => ({
+          statusCode: 302,
+          headers: {location: 'https://other.example'},
+          body: new Uint8Array(),
+        }),
+      }),
+    ).rejects.toMatchObject({name: 'OAuthMetadataFetchError', reason: 'redirected'});
+
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress],
+        maxBodyBytes: 8,
+        request: async () => response(validDocument),
+      }),
+    ).rejects.toMatchObject({name: 'OAuthMetadataFetchError', reason: 'response-too-large'});
+
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress],
+        request: async () => ({statusCode: 200, headers: {}, body: Buffer.from('{bad json')}),
+      }),
+    ).rejects.toBeInstanceOf(InvalidOAuthClientMetadataError);
+
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress],
+        request: async () =>
+          response({...validDocument, client_id: 'https://other.example/.well-known/client'}),
+      }),
+    ).rejects.toBeInstanceOf(InvalidOAuthClientMetadataError);
+  });
+
+  it('honors cache directives and rejects invalid response headers', async () => {
+    const cacheCases = [
+      ['no-store', 0],
+      ['no-cache', 0],
+      ['max-age = 0', 0],
+      ['max-age=30', 30],
+      ['max-age=999999', 900],
+      ['max-age=not-a-number', 900],
+      [undefined, 900],
+    ] as const;
+
+    for (const [cacheControl, expectedMaxAge] of cacheCases) {
+      const headers = cacheControl === undefined ? {} : {'cache-control': cacheControl};
+      const result = await fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress],
+        request: async () => response(validDocument, headers),
+      });
+      expect(result.cacheMaxAgeSeconds).toBe(expectedMaxAge);
+    }
+
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress],
+        request: async () => response(validDocument, {'content-length': '9'}),
+        maxBodyBytes: 8,
+      }),
+    ).rejects.toMatchObject({name: 'OAuthMetadataFetchError', reason: 'response-too-large'});
+
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress],
+        request: async () => response(validDocument, {'content-encoding': 'gzip'}),
+      }),
+    ).rejects.toMatchObject({name: 'OAuthMetadataFetchError', reason: 'invalid-response'});
+
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress],
+        request: async () => response(validDocument, {}, 500),
+      }),
+    ).rejects.toMatchObject({name: 'OAuthMetadataFetchError', reason: 'invalid-response'});
+  });
+
+  it('tries the next validated address after a connection failure', async () => {
+    const secondAddress: CimdAddress = {address: '93.184.216.35', family: 4};
+    const request = vi.fn(({address}: {address: CimdAddress}) => {
+      if (address === publicAddress) return Promise.reject(new Error('connection refused'));
+      return Promise.resolve(response(validDocument));
+    });
+
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress, secondAddress],
+        request,
+      }),
+    ).resolves.toMatchObject({metadata: {clientId}});
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(request).toHaveBeenLastCalledWith(expect.objectContaining({address: secondAddress}));
+  });
+
+  it('aborts an in-flight request when the overall timeout expires', async () => {
+    let signal: AbortSignal | undefined;
+    const request = vi.fn(
+      ({signal: requestSignal}: {signal?: AbortSignal}) =>
+        new Promise<CimdHttpResponse>((_resolve, reject) => {
+          signal = requestSignal;
+          requestSignal?.addEventListener('abort', () => reject(new Error('request aborted')), {
+            once: true,
+          });
+        }),
+    );
+
+    await expect(
+      fetchClientIdMetadata(clientId, {
+        resolveAddress: async () => [publicAddress],
+        request,
+        timeoutMs: 10,
+      }),
+    ).rejects.toMatchObject({name: 'OAuthMetadataFetchError', reason: 'timeout'});
+    expect(signal?.aborted).toBe(true);
+  });
+
+  it('does not fetch a credential-bearing client ID', async () => {
+    await expect(
+      fetchClientIdMetadata('https://user:password@client.example/.well-known/oauth-client', {
+        resolveAddress: async () => [publicAddress],
+        request: async () => response(validDocument),
+      }),
+    ).rejects.toBeInstanceOf(InvalidOAuthClientMetadataError);
+  });
+});