@shipfox/api-server 2.0.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@shipfox/api-server",
+  "license": "MIT",
+  "private": false,
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/server"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./instrumentation": {
+      "development": {
+        "types": "./src/instrumentation.ts",
+        "default": "./src/instrumentation.ts"
+      },
+      "default": {
+        "types": "./dist/instrumentation.d.ts",
+        "default": "./dist/instrumentation.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@shipfox/api-auth": "2.0.0",
+    "@shipfox/api-agent": "2.0.0",
+    "@shipfox/api-dispatcher": "2.0.0",
+    "@shipfox/annotations": "2.0.0",
+    "@shipfox/api-integration-core": "2.0.0",
+    "@shipfox/api-definitions": "2.0.0",
+    "@shipfox/api-logs": "2.0.0",
+    "@shipfox/api-projects": "2.0.0",
+    "@shipfox/api-workspaces": "2.0.0",
+    "@shipfox/api-triggers": "2.0.0",
+    "@shipfox/config": "1.2.1",
+    "@shipfox/node-fastify": "0.2.1",
+    "@shipfox/node-error-monitoring": "0.1.2",
+    "@shipfox/api-workflows": "2.0.0",
+    "@shipfox/node-module": "0.2.0",
+    "@shipfox/api-secrets": "2.0.0",
+    "@shipfox/node-postgres": "0.4.1",
+    "@shipfox/api-runners": "2.0.0",
+    "@shipfox/node-opentelemetry": "0.5.0"
+  },
+  "devDependencies": {
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/typescript": "1.1.6"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,33 @@
+import {parseApiTrustProxy} from './config.js';
+
+describe('parseApiTrustProxy', () => {
+  it.each([
+    ['false', false],
+    [' true ', true],
+    ['1', 1],
+    ['3', 3],
+    ['127.0.0.1', '127.0.0.1'],
+    ['10.0.0.0/8', '10.0.0.0/8'],
+    ['2001:db8::/32', '2001:db8::/32'],
+  ])('parses %s', (value, expected) => {
+    const result = parseApiTrustProxy(value);
+
+    expect(result).toBe(expected);
+  });
+
+  it.each([
+    '',
+    '0',
+    '-1',
+    '1.5',
+    'maybe',
+    '9007199254740992',
+    '1'.repeat(400),
+    '10.0.0.0/99',
+    '2001:db8::/129',
+  ])('rejects %s', (value) => {
+    const act = () => parseApiTrustProxy(value);
+
+    expect(act).toThrow('API_TRUST_PROXY');
+  });
+});

package/src/config.ts

@@ -0,0 +1,54 @@
+import {isIP} from 'node:net';
+import {bool, createConfig, port, str} from '@shipfox/config';
+
+export type ApiTrustProxy = false | true | number | string;
+
+const INTEGER_PATTERN = /^\d+$/;
+
+export const config = createConfig({
+  E2E_ENABLED: bool({
+    desc: 'Enables the end-to-end test routes under /__e2e. Keep it false in production.',
+    default: false,
+  }),
+  E2E_ADMIN_API_KEY: str({
+    desc: 'Bearer token that protects the E2E admin routes. Set it when E2E_ENABLED is true.',
+    default: undefined,
+  }),
+  API_PORT: port({
+    desc: 'Port the API HTTP server listens on. When unset, the shared PORT setting controls the server port.',
+    default: undefined,
+  }),
+  API_TRUST_PROXY: str({
+    desc: 'Controls how the API trusts proxy headers for client IP detection. Use false when clients connect directly, true only when every caller is a trusted proxy, a positive hop count such as 1, or a trusted proxy IP/CIDR such as 10.0.0.0/8.',
+    default: 'false',
+  }),
+});
+
+function parseCidr(value: string): boolean {
+  const [address, prefix, extra] = value.split('/');
+  if (!address || !prefix || extra !== undefined || isIP(address) === 0) return false;
+
+  const maxPrefix = isIP(address) === 4 ? 32 : 128;
+  if (!INTEGER_PATTERN.test(prefix)) return false;
+
+  const prefixNumber = Number(prefix);
+  return prefixNumber >= 0 && prefixNumber <= maxPrefix;
+}
+
+export function parseApiTrustProxy(value: string): ApiTrustProxy {
+  const trimmed = value.trim();
+  if (trimmed === 'false') return false;
+  if (trimmed === 'true') return true;
+
+  if (INTEGER_PATTERN.test(trimmed)) {
+    const hops = Number(trimmed);
+    if (Number.isSafeInteger(hops) && hops > 0) return hops;
+    throw new Error('API_TRUST_PROXY hop count must be a positive safe integer');
+  }
+
+  if (isIP(trimmed) !== 0 || parseCidr(trimmed)) return trimmed;
+
+  throw new Error(
+    'API_TRUST_PROXY must be false, true, a positive hop count, or a trusted proxy IP/CIDR',
+  );
+}

package/src/e2e.test.ts

@@ -0,0 +1,101 @@
+import {closeApp, createApp, defineRoute} from '@shipfox/node-fastify';
+import {afterEach, describe, expect, it} from '@shipfox/vitest/vi';
+import {createE2eAdminAuthMethod, createE2eRouteGroup} from './e2e.js';
+
+const pingRoute = defineRoute({
+  method: 'POST',
+  path: '/ping',
+  description: 'E2E test route.',
+  handler: () => ({ok: true}),
+});
+
+describe('E2E route gating', () => {
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('does not mount E2E routes when E2E is disabled', async () => {
+    const app = await createApp({
+      auth: [createE2eAdminAuthMethod({E2E_ENABLED: false, E2E_ADMIN_API_KEY: 'secret'})],
+      routes: createE2eRouteGroup([pingRoute], {E2E_ENABLED: false, E2E_ADMIN_API_KEY: 'secret'}),
+      swagger: false,
+    });
+
+    const res = await app.inject({method: 'POST', url: '/__e2e/ping'});
+
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('does not mount E2E routes when the admin key is missing', async () => {
+    const app = await createApp({
+      auth: [createE2eAdminAuthMethod({E2E_ENABLED: true})],
+      routes: createE2eRouteGroup([pingRoute], {E2E_ENABLED: true}),
+      swagger: false,
+    });
+
+    const res = await app.inject({method: 'POST', url: '/__e2e/ping'});
+
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('rejects missing E2E admin bearer tokens', async () => {
+    const app = await createApp({
+      auth: [createE2eAdminAuthMethod({E2E_ENABLED: true, E2E_ADMIN_API_KEY: 'secret'})],
+      routes: createE2eRouteGroup([pingRoute], {E2E_ENABLED: true, E2E_ADMIN_API_KEY: 'secret'}),
+      swagger: false,
+    });
+
+    const res = await app.inject({method: 'POST', url: '/__e2e/ping'});
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects invalid E2E admin bearer tokens', async () => {
+    const app = await createApp({
+      auth: [createE2eAdminAuthMethod({E2E_ENABLED: true, E2E_ADMIN_API_KEY: 'secret'})],
+      routes: createE2eRouteGroup([pingRoute], {E2E_ENABLED: true, E2E_ADMIN_API_KEY: 'secret'}),
+      swagger: false,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/__e2e/ping',
+      headers: {authorization: 'Bearer wrong'},
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('allows valid E2E admin bearer tokens', async () => {
+    const app = await createApp({
+      auth: [createE2eAdminAuthMethod({E2E_ENABLED: true, E2E_ADMIN_API_KEY: 'secret'})],
+      routes: createE2eRouteGroup([pingRoute], {E2E_ENABLED: true, E2E_ADMIN_API_KEY: 'secret'}),
+      swagger: false,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/__e2e/ping',
+      headers: {authorization: 'Bearer secret'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ok: true});
+  });
+
+  it('allows a mixed-case E2E admin bearer scheme', async () => {
+    const app = await createApp({
+      auth: [createE2eAdminAuthMethod({E2E_ENABLED: true, E2E_ADMIN_API_KEY: 'secret'})],
+      routes: createE2eRouteGroup([pingRoute], {E2E_ENABLED: true, E2E_ADMIN_API_KEY: 'secret'}),
+      swagger: false,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/__e2e/ping',
+      headers: {authorization: 'bEaReR secret'},
+    });
+
+    expect(res.statusCode).toBe(200);
+  });
+});

package/src/e2e.ts

@@ -0,0 +1,61 @@
+import {timingSafeEqual} from 'node:crypto';
+import {
+  type AuthMethod,
+  ClientError,
+  type RouteExport,
+  type RouteGroup,
+} from '@shipfox/node-fastify';
+
+export const AUTH_E2E_ADMIN = 'e2e-admin';
+
+export interface E2eConfig {
+  E2E_ENABLED: boolean;
+  E2E_ADMIN_API_KEY?: string | undefined;
+}
+
+const BEARER_RE = /^Bearer /iu;
+
+export function shouldMountE2eRoutes(config: E2eConfig): boolean {
+  return config.E2E_ENABLED && Boolean(config.E2E_ADMIN_API_KEY);
+}
+
+function extractBearerToken(header: string | undefined): string | undefined {
+  return header?.replace(BEARER_RE, '');
+}
+
+function tokensMatch(actual: string, expected: string): boolean {
+  const actualBuffer = Buffer.from(actual);
+  const expectedBuffer = Buffer.from(expected);
+  return (
+    actualBuffer.length === expectedBuffer.length && timingSafeEqual(actualBuffer, expectedBuffer)
+  );
+}
+
+export function createE2eAdminAuthMethod(config: E2eConfig): AuthMethod {
+  return {
+    name: AUTH_E2E_ADMIN,
+    authenticate: async (request) => {
+      await Promise.resolve();
+      const expected = config.E2E_ADMIN_API_KEY;
+      const actual = extractBearerToken(request.headers.authorization);
+
+      if (!expected || !actual || !tokensMatch(actual, expected)) {
+        throw new ClientError('Missing or invalid E2E admin API key', 'unauthorized', {
+          status: 401,
+        });
+      }
+    },
+  };
+}
+
+export function createE2eRouteGroup(routes: RouteExport[], config: E2eConfig): RouteGroup[] {
+  if (!shouldMountE2eRoutes(config) || routes.length === 0) return [];
+
+  return [
+    {
+      prefix: '/__e2e',
+      auth: AUTH_E2E_ADMIN,
+      routes,
+    },
+  ];
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export {defaultModules} from './modules.js';
+export type {CreateServerOptions, RunServerOptions, ServerHandle} from './server.js';
+export {createServer, runServer} from './server.js';

package/src/instrumentation.ts

@@ -0,0 +1,8 @@
+import {startInstanceInstrumentation} from '@shipfox/node-opentelemetry';
+
+// The metrics API has no proxy meter: instruments created before this preload
+// completes bind to a no-op provider for the process lifetime.
+await startInstanceInstrumentation({
+  serviceName: 'api',
+  instrumentations: {fastify: true, http: true, pg: true},
+});

package/src/modules.test.ts

@@ -0,0 +1,137 @@
+import {defaultModules} from './modules.js';
+
+const mocks = vi.hoisted(() => ({
+  buildAgentToolCatalogs: vi.fn(),
+  buildAgentToolSelectionCatalogs: vi.fn(),
+  createDefinitionsModule: vi.fn(),
+  createIntegrationsContext: vi.fn(),
+  createProjectsModule: vi.fn(),
+  createWorkspaceConnectionSnapshotLoader: vi.fn(),
+  deleteSecrets: vi.fn(),
+  getIntegrationConnectionById: vi.fn(),
+  getSecret: vi.fn(),
+  loadRunningLeasedStep: vi.fn(),
+  setAgentToolMaterializationServices: vi.fn(),
+  setSecrets: vi.fn(),
+  setSourceControl: vi.fn(),
+}));
+
+vi.mock('@shipfox/api-agent', () => ({agentModule: {name: 'agent'}}));
+vi.mock('@shipfox/annotations', () => ({annotationsModule: {name: 'annotations'}}));
+vi.mock('@shipfox/api-auth', () => ({authModule: {name: 'auth'}}));
+vi.mock('@shipfox/api-definitions', () => ({
+  createDefinitionsModule: mocks.createDefinitionsModule,
+}));
+vi.mock('@shipfox/api-dispatcher', () => ({dispatcherModule: {name: 'dispatcher'}}));
+vi.mock('@shipfox/api-integration-core', () => ({
+  buildAgentToolCatalogs: mocks.buildAgentToolCatalogs,
+  buildAgentToolSelectionCatalogs: mocks.buildAgentToolSelectionCatalogs,
+  createIntegrationsContext: mocks.createIntegrationsContext,
+  createWorkspaceConnectionSnapshotLoader: mocks.createWorkspaceConnectionSnapshotLoader,
+  getIntegrationConnectionById: mocks.getIntegrationConnectionById,
+}));
+vi.mock('@shipfox/api-logs', () => ({logsModule: {name: 'logs'}}));
+vi.mock('@shipfox/api-projects', () => ({createProjectsModule: mocks.createProjectsModule}));
+vi.mock('@shipfox/api-runners', () => ({runnersModule: {name: 'runners'}}));
+vi.mock('@shipfox/api-secrets', () => ({
+  deleteSecrets: mocks.deleteSecrets,
+  getSecret: mocks.getSecret,
+  secretsModule: {name: 'secrets'},
+  setSecrets: mocks.setSecrets,
+}));
+vi.mock('@shipfox/api-triggers', () => ({triggersModule: {name: 'triggers'}}));
+vi.mock('@shipfox/api-workflows', () => ({
+  loadRunningLeasedStep: mocks.loadRunningLeasedStep,
+  setAgentToolMaterializationServices: mocks.setAgentToolMaterializationServices,
+  setSourceControl: mocks.setSourceControl,
+  workflowsModule: {name: 'workflows'},
+}));
+vi.mock('@shipfox/api-workspaces', () => ({workspacesModule: {name: 'workspaces'}}));
+
+describe('defaultModules', () => {
+  beforeEach(() => {
+    mocks.buildAgentToolCatalogs.mockReset();
+    mocks.buildAgentToolSelectionCatalogs.mockReset();
+    mocks.createDefinitionsModule.mockReset();
+    mocks.createIntegrationsContext.mockReset();
+    mocks.createProjectsModule.mockReset();
+    mocks.createWorkspaceConnectionSnapshotLoader.mockReset();
+    mocks.deleteSecrets.mockReset();
+    mocks.getIntegrationConnectionById.mockReset();
+    mocks.getSecret.mockReset();
+    mocks.loadRunningLeasedStep.mockReset();
+    mocks.setAgentToolMaterializationServices.mockReset();
+    mocks.setSecrets.mockReset();
+    mocks.setSourceControl.mockReset();
+
+    mocks.createIntegrationsContext.mockResolvedValue({
+      module: {name: 'integrations'},
+      registry: {},
+      sourceControl: {provider: 'source-control'},
+    });
+    mocks.buildAgentToolCatalogs.mockResolvedValue(new Map());
+    mocks.buildAgentToolSelectionCatalogs.mockResolvedValue(new Map());
+    mocks.createWorkspaceConnectionSnapshotLoader.mockReturnValue(vi.fn());
+    mocks.createProjectsModule.mockReturnValue({name: 'projects'});
+    mocks.createDefinitionsModule.mockReturnValue({name: 'definitions'});
+  });
+
+  it('returns the API modules in lifecycle order', async () => {
+    const modules = await defaultModules();
+
+    expect(modules.map((module) => module.name)).toEqual([
+      'auth',
+      'workspaces',
+      'secrets',
+      'agent',
+      'integrations',
+      'projects',
+      'definitions',
+      'workflows',
+      'annotations',
+      'runners',
+      'logs',
+      'triggers',
+      'dispatcher',
+    ]);
+  });
+
+  it('uses the leased-step loader and namespaced Linear secrets', async () => {
+    await defaultModules();
+
+    expect(mocks.createIntegrationsContext).toHaveBeenCalledWith({
+      secrets: {
+        deleteSecrets: mocks.deleteSecrets,
+        linear: {
+          deleteSecrets: expect.any(Function),
+          getSecret: expect.any(Function),
+          setSecrets: expect.any(Function),
+        },
+      },
+      agentTools: {loadLeasedAgentStep: mocks.loadRunningLeasedStep},
+    });
+
+    const integrationsOptions = mocks.createIntegrationsContext.mock.calls[0]?.[0] as {
+      secrets: {
+        linear: {
+          deleteSecrets: (params: {namespace: string}) => unknown;
+          getSecret: (params: {namespace: string}) => unknown;
+          setSecrets: (params: {namespace: string}) => unknown;
+        };
+      };
+    };
+    integrationsOptions.secrets.linear.getSecret({namespace: 'workspace'});
+    integrationsOptions.secrets.linear.setSecrets({namespace: 'workspace'});
+    integrationsOptions.secrets.linear.deleteSecrets({namespace: 'workspace'});
+
+    expect(mocks.getSecret).toHaveBeenCalledWith({
+      namespace: 'system/integrations/linear/workspace',
+    });
+    expect(mocks.setSecrets).toHaveBeenCalledWith({
+      namespace: 'system/integrations/linear/workspace',
+    });
+    expect(mocks.deleteSecrets).toHaveBeenCalledWith({
+      namespace: 'system/integrations/linear/workspace',
+    });
+  });
+});

package/src/modules.ts

@@ -0,0 +1,90 @@
+import {annotationsModule} from '@shipfox/annotations';
+import {agentModule} from '@shipfox/api-agent';
+import {authModule} from '@shipfox/api-auth';
+import {createDefinitionsModule} from '@shipfox/api-definitions';
+import {dispatcherModule} from '@shipfox/api-dispatcher';
+import {
+  buildAgentToolCatalogs,
+  buildAgentToolSelectionCatalogs,
+  createIntegrationsContext,
+  createWorkspaceConnectionSnapshotLoader,
+  getIntegrationConnectionById,
+} from '@shipfox/api-integration-core';
+import {logsModule} from '@shipfox/api-logs';
+import {createProjectsModule} from '@shipfox/api-projects';
+import {runnersModule} from '@shipfox/api-runners';
+import {deleteSecrets, getSecret, secretsModule, setSecrets} from '@shipfox/api-secrets';
+import {triggersModule} from '@shipfox/api-triggers';
+import {
+  loadRunningLeasedStep,
+  setAgentToolMaterializationServices,
+  setSourceControl,
+  workflowsModule,
+} from '@shipfox/api-workflows';
+import {workspacesModule} from '@shipfox/api-workspaces';
+import type {ShipfoxModule} from '@shipfox/node-module';
+
+export async function defaultModules(): Promise<ShipfoxModule[]> {
+  const integrations = await createIntegrationsContext({
+    secrets: {
+      deleteSecrets,
+      linear: {
+        getSecret: (params) =>
+          getSecret({
+            ...params,
+            namespace: `system/integrations/linear/${params.namespace}`,
+          }),
+        setSecrets: (params) =>
+          setSecrets({
+            ...params,
+            namespace: `system/integrations/linear/${params.namespace}`,
+          }),
+        deleteSecrets: (params) =>
+          deleteSecrets({
+            ...params,
+            namespace: `system/integrations/linear/${params.namespace}`,
+          }),
+      },
+    },
+    agentTools: {loadLeasedAgentStep: loadRunningLeasedStep},
+  });
+  const [agentToolSelectionCatalogs, agentToolCatalogs] = await Promise.all([
+    buildAgentToolSelectionCatalogs(integrations.registry),
+    buildAgentToolCatalogs(integrations.registry),
+  ]);
+  const loadWorkspaceConnectionSnapshot = createWorkspaceConnectionSnapshotLoader(
+    integrations.registry,
+  );
+
+  // The checkout-token route resolves intents and mints credentials through the
+  // source-control service; wire it into the workflows module before serving.
+  setSourceControl(integrations.sourceControl);
+  setAgentToolMaterializationServices({
+    catalogs: agentToolCatalogs,
+    loadWorkspaceConnectionSnapshot,
+    getIntegrationConnectionById,
+  });
+  const projectsModule = createProjectsModule({sourceControl: integrations.sourceControl});
+  const definitionsModule = createDefinitionsModule({
+    sourceControl: integrations.sourceControl,
+    agentToolSelectionCatalogs,
+    loadWorkspaceConnectionSnapshot,
+    getIntegrationConnectionById,
+  });
+
+  return [
+    authModule,
+    workspacesModule,
+    secretsModule,
+    agentModule,
+    integrations.module,
+    projectsModule,
+    definitionsModule,
+    workflowsModule,
+    annotationsModule,
+    runnersModule,
+    logsModule,
+    triggersModule,
+    dispatcherModule,
+  ];
+}