@antasphere/chassis-server 1.0.0

package/src/testing/helpers.ts

@@ -0,0 +1,254 @@
+import { PostgreSqlContainer, type StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import pg from 'pg';
+import type { Hono } from 'hono';
+import type { ToolIdentity } from '@antasphere/chassis-contract';
+import type { EmailDriver, EmailMessage } from '../email/driver.js';
+
+/**
+ * Delivering driver that records instead of sending. Exists because
+ * change-email tokens are stateless JWTs (never stored in the verification
+ * table) — the only way a test can obtain the link is to capture the
+ * outbound mail. Passed via the `email` boot override.
+ */
+export class RecordingEmailDriver implements EmailDriver {
+  readonly name = 'smtp' as const; // narrowest honest label the union allows
+  readonly delivers = true;
+  readonly sent: EmailMessage[] = [];
+  async send(message: EmailMessage): Promise<void> {
+    this.sent.push(message);
+  }
+}
+
+/**
+ * The first-boot claim credential every test app boots with (PRDCT-1347:
+ * POST /setup ALWAYS requires a token now). Suites that exercise the
+ * generated-token path override it with an empty SETUP_TOKEN.
+ */
+export const SETUP_TOKEN = 'integration-test-setup-token';
+
+/** Matches the compose stack: Postgres 17 with pgvector available. */
+export const PG_IMAGE = 'pgvector/pgvector:pg17';
+
+export async function startPostgres(): Promise<StartedPostgreSqlContainer> {
+  return new PostgreSqlContainer(PG_IMAGE).start();
+}
+
+/**
+ * What the harness needs of a boot result: the three handles every suite
+ * drives (`app`, `db.pool`, `jobs`). Any `BootResult` of `createPlatform`
+ * satisfies it, whatever the tool.
+ */
+export interface BootResultLike {
+  app: Hono;
+  db: { pool: pg.Pool };
+  jobs: { stop: () => Promise<void> };
+}
+
+/** A tool's boot function, as `createPlatform(tool).boot` hands it out. */
+export type BootFn<TResult extends BootResultLike, TOverrides> = (
+  source?: NodeJS.ProcessEnv,
+  overrides?: TOverrides
+) => Promise<TResult>;
+
+export type TestApp<TResult extends BootResultLike = BootResultLike> = TResult & {
+  stop: () => Promise<void>;
+};
+
+/**
+ * The scope names and the probe routes of the tool a suite runs against. The
+ * chassis suite (`test/integration`) never spells a tool's vocabulary: where
+ * it needs "some valid scope" or "some authenticated tool route", it takes
+ * them from here.
+ */
+export interface ChassisTestHost<TResult extends BootResultLike, TOverrides> {
+  boot: BootFn<TResult, TOverrides>;
+  /**
+   * The host tool's migration history, the folder its boot applies: the suite's
+   * migration checks run it a second time by hand. The chassis's own host gives
+   * `test/host/drizzle` (the chassis tables alone); a tool gives its `packages/db/drizzle`.
+   */
+  migrationsDir: string;
+  /**
+   * The host tool's disaster-recovery shell library (`scripts/lib/dr-lib.sh` in a
+   * tool): the suite's dump check sources it and runs its verifier on a real pg_dump.
+   */
+  drLib: string;
+  /** The host tool's identity: where the suite reads the key prefix a minted key must carry. */
+  identity: ToolIdentity;
+  /** The host tool's OAuth client id at the hub: the cloud boots' `HUB_CLIENT_ID`, and the fake hub's. */
+  hubClientId: string;
+  scopes: {
+    /** The scope behind the chassis read surfaces (`/me`, the files reads). */
+    read: string;
+    /** The scope behind the chassis mutations. */
+    write: string;
+    /** The dedicated opt-in scope of the workspace export. */
+    dataExport: string;
+  };
+  /**
+   * An authenticated, workspace-scoped GET route of the TOOL (under the read
+   * scope) that answers 200 to any principal the gates let through.
+   */
+  probeRoute: string;
+}
+
+/** Postgres `admin_shutdown`: what a backend answers a still-connected client when the server stops. */
+const ADMIN_SHUTDOWN = '57P01';
+
+/** How long `endPool` waits for the sockets, so that a teardown can never hang on one. */
+const POOL_CLOSE_TIMEOUT_MS = 10_000;
+
+/**
+ * End a pool and wait until every one of its clients has REALLY closed
+ * (PRDCT-2547). `pool.end()` alone does not say that: pg-pool takes each
+ * client off its list and only then calls `client.end()`, so its promise
+ * resolves while the sockets are still open. A suite that stops its container
+ * right after (`await app.stop(); await container.stop()`) then races the
+ * server's shutdown: the backend answers the still-connected client with
+ * `57P01`, the client hands it to the pool, the pool has no `error` listener,
+ * and Node reports an unhandled error: the run fails with every test passed.
+ *
+ * The pool emits `remove` from the callback of `client.end()`, which pg calls
+ * on the connection's `end`, the socket's close. So: count the clients, end
+ * the pool, wait for as many `remove`. The `error` listener is the net under
+ * it (a wait that timed out): it takes `57P01` on this ENDING pool and nothing
+ * else, any other error is thrown as it was before.
+ *
+ * A ceiling that expires SAYS so, in one `console.warn` line with the number
+ * of clients still open: it does not throw (the listener stays the net), but
+ * a chronically slow teardown is then visible instead of leaning on the
+ * listener in silence. `ceilingMs` exists for the helper's own unit test.
+ */
+export async function endPool(pool: pg.Pool, ceilingMs: number = POOL_CLOSE_TIMEOUT_MS): Promise<void> {
+  pool.on('error', (err: Error & { code?: string }) => {
+    if (err.code !== ADMIN_SHUTDOWN) throw err;
+  });
+  let open = pool.totalCount;
+  let timer: NodeJS.Timeout | undefined;
+  const closed = new Promise<void>((resolve) => {
+    if (open === 0) return resolve();
+    pool.on('remove', () => {
+      if (--open === 0) resolve();
+    });
+    timer = setTimeout(() => {
+      console.warn(
+        `endPool: ${open} pool client(s) still open after the ${ceilingMs} ms ceiling; the teardown goes on`
+      );
+      resolve();
+    }, ceilingMs);
+    timer.unref();
+  });
+  await pool.end();
+  await closed;
+  clearTimeout(timer);
+}
+
+/**
+ * Binds `createTestApp` to a boot function: boots the real app (real
+ * migrations, real Better Auth) against a database.
+ */
+export function makeCreateTestApp<TResult extends BootResultLike, TOverrides>(
+  boot: BootFn<TResult, TOverrides>
+): (
+  connectionString: string,
+  extraEnv?: Record<string, string>,
+  overrides?: TOverrides
+) => Promise<TestApp<TResult>> {
+  return async (connectionString, extraEnv = {}, overrides) => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'chassis-test-'));
+    const result = await boot(
+      {
+        DATABASE_URL: connectionString,
+        DATA_DIR: dataDir,
+        AUTH_SECRET: 'integration-test-secret-0123456789abcdef0123456789abcdef',
+        SETUP_TOKEN,
+        NODE_ENV: 'test',
+        LOG_LEVEL: 'error',
+        PUBLIC_BASE_URL: 'http://localhost:3000',
+        // app.request() has no socket; trusting XFF lets tests exercise the
+        // per-IP bucket behavior deliberately.
+        TRUST_PROXY: 'true',
+        // Generous general-API quota so unrelated suites never trip it while
+        // still exercising the consume path; the api-quota suite overrides
+        // these with tight values via extraEnv.
+        API_RATE_LIMIT_PER_MINUTE: '100000',
+        API_RATE_LIMIT_BURST: '10000',
+        ...extraEnv
+      },
+      overrides
+    );
+    return {
+      ...result,
+      stop: async () => {
+        await result.jobs.stop().catch(() => {});
+        await endPool(result.db.pool);
+      }
+    };
+  };
+}
+
+/**
+ * Assert a boot REFUSES with a message matching `re`. Never `expect(boot)
+ * .rejects.toThrow(...)` directly: when the refusal is missing the promise
+ * resolves with a live BootResult, vitest tries to serialise it for the
+ * failure message (OOM, worker crash), and the app is never stopped.
+ */
+export async function expectBootRefusal(boot: Promise<TestApp>, re: RegExp): Promise<void> {
+  let app: TestApp | undefined;
+  try {
+    app = await boot;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (!re.test(message)) throw new Error(`boot refused for the wrong reason: ${message}`);
+    return;
+  }
+  await app.stop();
+  throw new Error(`boot succeeded but a refusal matching ${re} was expected`);
+}
+
+/** Create an extra empty database inside the shared container. */
+export async function createDatabase(container: StartedPostgreSqlContainer, name: string): Promise<string> {
+  const client = new pg.Client({ connectionString: container.getConnectionUri() });
+  await client.connect();
+  await client.query(`CREATE DATABASE ${name}`);
+  await client.end();
+  const base = new URL(container.getConnectionUri());
+  base.pathname = `/${name}`;
+  return base.toString();
+}
+
+/** Deliberate state isolation: wipe all rows, keep the schema. */
+export async function truncateAll(connectionString: string): Promise<void> {
+  const client = new pg.Client({ connectionString });
+  await client.connect();
+  try {
+    const res = await client.query<{ tablename: string }>(
+      `SELECT tablename FROM pg_tables WHERE schemaname = 'public'`
+    );
+    const tables = res.rows.map((r) => `"${r.tablename}"`).join(', ');
+    if (tables.length > 0) {
+      await client.query(`TRUNCATE ${tables} RESTART IDENTITY CASCADE`);
+    }
+  } finally {
+    await client.end();
+  }
+}
+
+/** Read a JSON body without fighting Response's `unknown` under strict TS. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function readJson(res: Response): Promise<any> {
+  return res.json();
+}
+
+export function extractCookie(res: Response): string {
+  const setCookie = res.headers.get('set-cookie');
+  if (!setCookie) throw new Error('no set-cookie header in response');
+  return setCookie
+    .split(',')
+    .map((part) => part.split(';')[0]?.trim())
+    .filter(Boolean)
+    .join('; ');
+}

package/src/testing/index.ts

@@ -0,0 +1,11 @@
+/**
+ * The test harness of a chassis-based tool: the container and database
+ * helpers, the recording mail driver, the fake hub and the SSO dances — ONE
+ * copy, parametrized by the boot function, shared by the chassis suite
+ * (`packages/chassis-server/test`) and by the tool's own tests. Never imported
+ * by production code.
+ */
+export * from './helpers.js';
+export * from './fake-hub.js';
+export * from './sso-helpers.js';
+export * from './setup-origins.js';

package/src/testing/setup-origins.ts

@@ -0,0 +1,58 @@
+/**
+ * The single URL table for the setup-transport rule (PLT-10).
+ *
+ * The rule is implemented TWICE on purpose: in TypeScript, where the server
+ * enforces it (`apps/server/src/setup-transport.ts`), and in shell, where
+ * setup.sh has to warn the operator before they discover it as a 403
+ * (`dr_origin_is_secure` in scripts/lib/dr-lib.sh). Two implementations of a
+ * security rule drift — the first shell version accepted
+ * `http://localhost.evil.test` as loopback — so both are driven from this one
+ * table, by test/unit/setup-transport.test.ts here and the app's test/unit/dr-lib.test.ts.
+ *
+ * Add a case here and BOTH implementations have to satisfy it. The contract for
+ * anything NOT listed: the shell twin may be stricter than the server (it only
+ * decides whether to print a warning) but never looser, because looser means
+ * setup.sh reassures the operator about an origin the server is about to 403.
+ */
+
+/** POST /api/v1/setup is accepted on these origins. */
+export const SECURE_SETUP_ORIGINS = [
+  // https anywhere: the credentials are protected in transit.
+  'https://platform.example.com',
+  'https://10.0.0.4:8443',
+  'https://platform.example.com/base',
+  // Plaintext on loopback: nothing leaves the host, which is what makes the
+  // `ssh -L` tunnel a legitimate way to finish setup on a TLS-less server.
+  'http://localhost:3000',
+  'http://LOCALHOST:3000',
+  'http://localhost',
+  'http://app.localhost:3000',
+  'http://127.0.0.1:3000',
+  'http://127.1.2.3:3000', // the whole 127.0.0.0/8 block is loopback
+  'http://127.0.0.1',
+  // URL parsing normalises dotted-shorthand IPv4: `127.0.0` IS 127.0.0.0 and
+  // `127.1` IS 127.0.0.1. Both are loopback, and both really do connect there.
+  'http://127.0.0:3000',
+  'http://127.1:3000',
+  'http://[::1]:3000',
+  'http://[::1]'
+] as const;
+
+/** POST /api/v1/setup is refused on these origins without the explicit opt-in. */
+export const INSECURE_SETUP_ORIGINS = [
+  'http://platform.example.com',
+  'http://platform.example.com:8080',
+  'http://203.0.113.10:3000',
+  'http://10.0.0.4:3000',
+  'http://192.168.1.20:3000',
+  // Hostnames somebody else controls that merely LOOK like loopback. A
+  // prefix/suffix match on the raw URL accepts every one of these.
+  'http://localhost.evil.test:3000',
+  'http://127.0.0.1.evil.test:3000',
+  'http://notlocalhost:3000',
+  'http://[::2]:3000',
+  'http://[2001:db8::1]:3000',
+  // 127-ish but not in 127.0.0.0/8: a hostname, not an address.
+  'http://1270.0.0.1:3000',
+  'http://127a.0.0.1:3000'
+] as const;

package/src/testing/sso-helpers.ts

@@ -0,0 +1,178 @@
+import { expect } from 'vitest';
+import { extractCookie, readJson, type TestApp } from './helpers.js';
+import type { FakeHub, HubUserFixture } from './fake-hub.js';
+
+/**
+ * The SSO dance against the FakeHub, shared by the P3 (hub-sso) and P4
+ * (hub-entitlements) suites: initiate the sign-in leg, drive the callback
+ * with a hub-minted one-shot code, and hand back the session cookie.
+ */
+
+export const json = (body: unknown) => ({
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify(body)
+});
+
+let ipCounter = 0;
+/** Unique per-dance client IP — the login limiter (10/15min per IP) must never gate a suite. */
+export const nextIp = () => `10.99.${Math.floor(ipCounter / 250)}.${(ipCounter++ % 250) + 1}`;
+
+/**
+ * Seed a cloud-LOCAL workspace (`central_account_id NULL`) owned by the
+ * given user, straight into the database. Cloud setup mints NO workspace
+ * (user-scoped federation), so fixtures that need one — guest host
+ * workspaces, the P7 local-vs-projected contrast — seed it here; the state
+ * is exactly what a pre-flip instance (or break-glass recovery) leaves
+ * behind.
+ */
+export async function seedLocalWorkspace(app: TestApp, name: string, ownerEmail: string): Promise<string> {
+  const user = await app.db.pool.query(`SELECT id FROM "user" WHERE email = $1`, [ownerEmail]);
+  expect(user.rows).toHaveLength(1);
+  const ws = await app.db.pool.query(`INSERT INTO workspaces (name) VALUES ($1) RETURNING id`, [name]);
+  const workspaceId = ws.rows[0].id as string;
+  await app.db.pool.query(
+    `INSERT INTO workspace_members (workspace_id, user_id, role, origin, is_active)
+     VALUES ($1, $2, 'owner', 'local', true)`,
+    [workspaceId, user.rows[0].id]
+  );
+  return workspaceId;
+}
+
+/**
+ * Initiate the sign-in leg: returns the `state` plus the signed state
+ * cookie the callback must present (better-auth's double-submit check —
+ * a browser carries it automatically).
+ */
+export async function ssoInitiate(
+  app: TestApp
+): Promise<{ state: string; stateCookie: string; scope: string | null }> {
+  const init = json({ providerId: 'antasphere', callbackURL: '/' });
+  const signIn = await app.app.request('/api/v1/auth/sign-in/oauth2', {
+    ...init,
+    headers: { ...init.headers, 'x-forwarded-for': nextIp() }
+  });
+  expect(signIn.status).toBe(200);
+  const { url } = await readJson(signIn);
+  const state = new URL(url).searchParams.get('state')!;
+  expect(state).toBeTruthy();
+  // What the tool REALLY asked the hub for: the fake hub grants exactly this
+  // (FakeHub.mintCode), so a scope the tool stops requesting is a scope its
+  // grants stop carrying — in the suites as at the real hub.
+  return { state, stateCookie: extractCookie(signIn), scope: new URL(url).searchParams.get('scope') };
+}
+
+/** Initiate the SSO dance and drive the callback with a hub-minted code. */
+export async function ssoDance(app: TestApp, hub: FakeHub, fixture: HubUserFixture): Promise<Response> {
+  const { state, stateCookie, scope } = await ssoInitiate(app);
+  const code = hub.mintCode(fixture, scope);
+  return app.app.request(
+    `/api/v1/auth/oauth2/callback/antasphere?code=${encodeURIComponent(code)}&state=${encodeURIComponent(state)}`,
+    { headers: { cookie: stateCookie } }
+  );
+}
+
+/** A successful dance: 302 to the callbackURL with a live session cookie. */
+export async function ssoLogin(app: TestApp, hub: FakeHub, fixture: HubUserFixture): Promise<string> {
+  const res = await ssoDance(app, hub, fixture);
+  expect(res.status).toBe(302);
+  expect(res.headers.get('location')).toBe('/');
+  return extractCookie(res);
+}
+
+/** Assert a callback response is a session-less redirect carrying an error code. */
+export async function expectFailedLogin(app: TestApp, res: Response, errorContains: string): Promise<void> {
+  expect(res.status).toBe(302);
+  expect(res.headers.get('location')).toContain(errorContains);
+  const setCookie = res.headers.get('set-cookie');
+  if (setCookie) {
+    // Whatever cookies the failure path left behind must not resolve a session.
+    const me = await app.app.request('/api/v1/me', { headers: { cookie: extractCookie(res) } });
+    expect(me.status).toBe(401);
+  }
+}
+
+/**
+ * The in-process OAuth 2.1 dance against the instance's OWN authorization
+ * server (register once per app + PKCE + consent) — mints a Bearer JWT for
+ * the session's user, so suites can exercise the third credential path.
+ *
+ * Bound to the scope string the dance requests: the scope NAMES are the
+ * tool's, so each host binds its own (`openid <the tool's read scope>`).
+ */
+const oauthClientIds = new WeakMap<TestApp, string>();
+export function makeOauthBearer(scope: string): (app: TestApp, cookie: string) => Promise<string> {
+  return (app, cookie) => oauthBearerFor(scope, app, cookie);
+}
+
+async function oauthBearerFor(scope: string, app: TestApp, cookie: string): Promise<string> {
+  const { createHash, randomBytes } = await import('node:crypto');
+  const redirectUri = 'http://127.0.0.1:19999/callback';
+  let clientId = oauthClientIds.get(app);
+  if (!clientId) {
+    const register = await app.app.request(
+      '/api/v1/auth/oauth2/register',
+      json({
+        client_name: 'sso-helper-client',
+        redirect_uris: [redirectUri],
+        token_endpoint_auth_method: 'none',
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code']
+      })
+    );
+    expect([200, 201]).toContain(register.status);
+    clientId = (await readJson(register)).client_id as string;
+    oauthClientIds.set(app, clientId);
+  }
+  const verifier = randomBytes(48).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest().toString('base64url');
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    scope,
+    state: 'helper-state',
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+    resource: 'http://localhost:3000/mcp'
+  });
+  const authorize = await app.app.request(`/api/v1/auth/oauth2/authorize?${params}`, {
+    headers: { cookie }
+  });
+  let location: string;
+  if (authorize.status === 302) {
+    location = authorize.headers.get('location') ?? '';
+  } else {
+    expect(authorize.status).toBe(200);
+    location = (await readJson(authorize)).url;
+  }
+  let codeUrl: URL;
+  if (location.includes('/oauth/consent?')) {
+    const consent = await app.app.request('/api/v1/auth/oauth2/consent', {
+      method: 'POST',
+      headers: { cookie, 'content-type': 'application/json' },
+      body: JSON.stringify({ accept: true, oauth_query: location.split('?')[1] ?? '' })
+    });
+    expect(consent.status).toBe(200);
+    const body = await readJson(consent);
+    codeUrl = new URL(body.redirect_uri ?? body.url ?? '');
+  } else {
+    codeUrl = new URL(location);
+  }
+  const code = codeUrl.searchParams.get('code');
+  expect(code).toBeTruthy();
+  const token = await app.app.request('/api/v1/auth/oauth2/token', {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'authorization_code',
+      code: code!,
+      redirect_uri: redirectUri,
+      client_id: clientId,
+      code_verifier: verifier,
+      resource: 'http://localhost:3000/mcp'
+    })
+  });
+  expect(token.status).toBe(200);
+  return (await readJson(token)).access_token as string;
+}