@antasphere/chassis-server 1.0.0

package/test/host/drizzle/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1791388822563,
+      "tag": "0000_chassis_baseline",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1791388823563,
+      "tag": "0001_last_owner_guard",
+      "breakpoints": true
+    }
+  ]
+}

package/test/host/drizzle.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'drizzle-kit';
+
+/**
+ * The chassis's own migration history, for its own test host: the chassis
+ * tables alone, generated from the chassis schema into `test/host/drizzle`
+ * (`pnpm db:generate` in this package). A tool's history starts from these
+ * tables and adds its own; this one exists so the chassis suite boots without
+ * a tool beside it.
+ */
+export default defineConfig({
+  dialect: 'postgresql',
+  // drizzle-kit resolves paths from the package root, where pnpm runs it.
+  schema: '../chassis-db/src/schema.ts',
+  out: './test/host/drizzle',
+  verbose: true,
+  strict: true
+});

package/test/host/identity.ts

@@ -0,0 +1,41 @@
+import type { ToolIdentity } from '@antasphere/chassis-contract';
+import type { ChassisRoutesCopy } from '@antasphere/chassis-contract/routes';
+import type { ToolCopy } from '@antasphere/chassis-server';
+
+/**
+ * The identity of the test tools of this package (`minimal-tool.ts`, and the
+ * slot-less tool of `empty-tool.test.ts`): a tool called Things. Every value
+ * is its own, the key prefix included: the suite reads the prefix from its
+ * host (`host.identity.apiKeyPrefix`), so no file of this package spells a
+ * real tool's.
+ */
+export const THINGS_IDENTITY = {
+  slug: 'things',
+  displayName: 'Things',
+  apiKeyPrefix: 'thg',
+  scopes: { read: 'things:read', write: 'things:write', dataExport: 'things:export' },
+  cliKeyScopesLabel: 'things:read+write',
+  cloud: { url: 'https://things.antasphere.test' },
+  cli: { bin: 'things', envPrefix: 'THINGS', legacyConfigDir: 'things' },
+  mcp: { serverName: 'things', toolPrefix: 'things_' },
+  otelServiceName: 'things',
+  imageName: 'example.test/things'
+} as const satisfies ToolIdentity;
+
+/** The same tool's wording of the chassis refusals that name a domain (the `copy` slot). */
+export const THINGS_COPY: ToolCopy = {
+  guestForbidden: 'Guest access is limited to the things you were invited to',
+  guestTarget:
+    'This member is an external guest of one thing: their account is not this workspace’s to recover',
+  fileInUse: 'This file is referenced by a thing',
+  mail: {
+    tagline: 'A place for things. A test tool.',
+    invitePitch: 'Join to see the things the team keeps there, and to add your own.',
+    invitePreheader: 'their things, and a place for yours.'
+  }
+};
+
+/** And its wording of the OpenAPI document (`defineChassisRoutes`' third argument). */
+export const THINGS_ROUTES_COPY: ChassisRoutesCopy = {
+  fileInUseOpenApi: 'file_in_use: referenced by a thing'
+};

package/test/host/minimal-host.ts

@@ -0,0 +1,35 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createPlatform } from '@antasphere/chassis-server';
+import type { ChassisTestHost } from '@antasphere/chassis-server/testing';
+import { THINGS_IDENTITY } from './identity.js';
+import {
+  MIGRATIONS_FIXTURE,
+  minimalTool,
+  THINGS_ROUTE,
+  THINGS_SCOPES,
+  type MinimalBootOverrides,
+  type MinimalBootResult
+} from './minimal-tool.js';
+
+/**
+ * The chassis package's host of the suite (`test/integration`): the chassis
+ * composition bound to the minimal test tool. `@chassis-test/host` resolves
+ * here under this package's vitest config; the tool's app aliases the same
+ * specifier to its own host, over its real composition.
+ */
+export type HostBootResult = MinimalBootResult;
+export type HostBootOverrides = MinimalBootOverrides;
+
+const here = dirname(fileURLToPath(import.meta.url));
+const platform = createPlatform(minimalTool);
+
+export const host: ChassisTestHost<HostBootResult, HostBootOverrides> = {
+  boot: (source, overrides) => platform.boot(source, overrides),
+  migrationsDir: MIGRATIONS_FIXTURE,
+  drLib: join(here, 'dr-lib.sh'),
+  identity: THINGS_IDENTITY,
+  hubClientId: 'tool-things-cloud',
+  scopes: THINGS_SCOPES,
+  probeRoute: THINGS_ROUTE
+};

package/test/host/minimal-tool.ts

@@ -0,0 +1,123 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createDb, schema } from '@antasphere/chassis-db';
+import {
+  auditedSizeBytes,
+  declareRouteEntitlements,
+  declaredContentLength,
+  defineChassisContract
+} from '@antasphere/chassis-contract';
+import { defineChassisRoutes, fileUploadRoute } from '@antasphere/chassis-contract/routes';
+import type { BootOverrides, BootResult, ToolDefinition } from '@antasphere/chassis-server';
+import { createScopeAllowlist, requireAuth } from '@antasphere/chassis-server/middleware';
+import { THINGS_COPY, THINGS_IDENTITY, THINGS_ROUTES_COPY } from './identity.js';
+
+/**
+ * The MINIMAL test tool: the smallest tool that fills the required slots of
+ * `createPlatform` and gives the chassis suite something of a tool's to aim
+ * at. Its own three scope names, one tiny probe route per scope, the required
+ * blob policy, no domain, no env extension, no jobs, no buckets, no public
+ * app, no MCP tools.
+ *
+ * The migrations are a FIXTURE read by path, not an import (same stance as
+ * `empty-tool.test.ts`): the chassis's own history, `test/host/drizzle`,
+ * generated from the chassis schema by `pnpm db:generate` in this package
+ * (the chassis tables and nothing else). A tool's history starts from the
+ * same tables and adds its own; the tool's host of this suite boots on it.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+export const MIGRATIONS_FIXTURE = join(here, 'drizzle');
+
+export const THINGS_SCOPES = THINGS_IDENTITY.scopes;
+type ThingsScope = (typeof THINGS_SCOPES)[keyof typeof THINGS_SCOPES];
+
+/** The probe routes, one per scope: authenticated, workspace-scoped, and empty. */
+export const THINGS_ROUTE = '/api/v1/things';
+const THINGS_EXPORT_ROUTE = '/api/v1/things/export';
+
+const contract = defineChassisContract({
+  scopes: [THINGS_SCOPES.read, THINGS_SCOPES.write, THINGS_SCOPES.dataExport]
+});
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+type NoEnv = {};
+type NoDomain = Record<string, never>;
+
+export type MinimalBootOverrides = BootOverrides;
+export type MinimalBootResult = BootResult<NoEnv, NoDomain>;
+
+export const minimalTool: ToolDefinition<NoEnv, NoDomain> = {
+  identity: THINGS_IDENTITY,
+  runtime: {
+    version: '0.0.0-test',
+    findMigrationsDir: () => MIGRATIONS_FIXTURE,
+    publicDir: join(here, 'no-dashboard-build')
+  },
+  db: (url) => createDb(url, schema),
+  scopes: {
+    oauth: [
+      'openid',
+      'profile',
+      'email',
+      'offline_access',
+      THINGS_SCOPES.read,
+      THINGS_SCOPES.write,
+      THINGS_SCOPES.dataExport
+    ],
+    cliKey: [THINGS_SCOPES.read, THINGS_SCOPES.write],
+    requiredScopeFor: createScopeAllowlist<ThingsScope>({
+      ...THINGS_SCOPES,
+      rules: [
+        (path, _method, isRead) => {
+          if (path === THINGS_ROUTE) return isRead ? THINGS_SCOPES.read : THINGS_SCOPES.write;
+          if (path === THINGS_EXPORT_ROUTE && isRead) return THINGS_SCOPES.dataExport;
+          return null;
+        }
+      ]
+    }),
+    contractRoutes: defineChassisRoutes(contract, THINGS_IDENTITY, THINGS_ROUTES_COPY)
+  },
+  services: () => ({}),
+  api: {
+    // TEST FIXTURE ONLY: `undefined` is the whole-workspace view, for every member. The suite's
+    // files tests never assert member-to-member privacy (that proof is the tool's, SL-B1), so
+    // nothing here reads as a policy to copy: a real tool MUST return a per-principal scope.
+    filePolicy: () => ({ blobInUse: async () => false, blobReadScope: () => undefined }),
+    routes: (api) => {
+      api.use('/things', requireAuth());
+      api.use('/things/*', requireAuth());
+      api.get('/things', (c) => c.json({ things: [], nextCursor: null }, 200));
+      api.post('/things', (c) => c.json({ thing: { id: 'thing' } }, 201));
+      api.get('/things/export', (c) => c.json({ things: [] }, 200));
+    }
+  },
+  // The billing rail (slot 22): the generic files upload is the one metered
+  // route of the minimal tool — a price on the chassis' own route is the
+  // tool's declaration, never the chassis'. The limit's oss value is the
+  // operator's cap and so is the paid tier's (what discovery advertises is
+  // what the instance serves, PRDCT-2653); the free value is a fifth of it,
+  // so a suite can upload above the free value and below the cap as a pro
+  // account. Self-hosted instances read the oss value alone.
+  entitlements: (env) => {
+    const capBytes = env.MAX_FILE_SIZE_MB * 1024 * 1024;
+    return {
+      actions: [{ key: 'files.upload', creditsPerUnit: 5, unit: 'bytes', label: 'Upload a file' }],
+      limits: { 'files.maxBytes': { oss: capBytes, free: Math.floor(capBytes / 5), pro: capBytes } },
+      features: { 'things.premium': { free: false, pro: true } },
+      routes: declareRouteEntitlements([
+        {
+          route: fileUploadRoute,
+          meter: { key: 'files.upload', unit: 'bytes', quantity: auditedSizeBytes },
+          limit: { key: 'files.maxBytes', value: declaredContentLength }
+        }
+      ])
+    };
+  },
+  mcp: {
+    registerTools: () => {},
+    instructions: (info) => `MCP endpoint of the "${info.instanceName}" instance.`,
+    errorHints: {},
+    scopes: { read: THINGS_SCOPES.read, write: THINGS_SCOPES.write }
+  },
+  copy: THINGS_COPY
+};

package/test/integration/account-oracle-uniformity.test.ts

@@ -0,0 +1,284 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import type { StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+import {
+  createDatabase,
+  createTestApp,
+  extractCookie,
+  readJson,
+  startPostgres,
+  type TestApp
+} from './helpers.js';
+
+/**
+ * PRDCT-1437 — the account-existence oracle, closed on both remaining doors.
+ *
+ * Door 1: minting a change-email link succeeds for ANY new address; consuming
+ * it used to answer a raw 500 when the address already had an account
+ * anywhere on the instance (the update died at the `user.email` UNIQUE
+ * constraint) versus a 302 when it did not — a mint-then-consume oracle for
+ * any owner, free on a "yes". The consume now answers the SAME observables on
+ * both branches: 302 to the callback, a session cookie for the target, no
+ * error param — the email just does not change on a collision.
+ *
+ * Door 2: the public invitation/collaborator lookups no longer carry
+ * `accountExists` (asserted in their own suites); this file pins door 1.
+ */
+
+const OWNER = { email: 'owner@oracle.test', name: 'Oracle Owner', password: 'oracle-owner-pass-1' };
+const MEMBER = { email: 'member@oracle.test', name: 'Oracle Member', password: 'oracle-member-pass-1' };
+/** An account that exists on the instance but NOT in this workspace. */
+const ELSEWHERE_EMAIL = 'elsewhere@oracle.test';
+
+let container: StartedPostgreSqlContainer;
+let app: TestApp;
+let ownerCookie: string;
+let memberId: string;
+
+let ipCounter = 0;
+const nextIp = () => `10.67.${Math.floor(ipCounter / 250)}.${(ipCounter++ % 250) + 1}`;
+
+const json = (body: unknown, headers: Record<string, string> = {}) => ({
+  method: 'POST',
+  headers: { 'content-type': 'application/json', 'x-forwarded-for': nextIp(), ...headers },
+  body: JSON.stringify(body)
+});
+
+async function memberEmail(): Promise<string> {
+  const { rows } = await app.db.pool.query<{ email: string }>(
+    `SELECT u.email FROM "user" u JOIN workspace_members m ON m.user_id = u.id WHERE m.id = $1`,
+    [memberId]
+  );
+  return rows[0]!.email;
+}
+
+/** Mint a change-email link for the member; must succeed (200). */
+async function mint(newEmail: string): Promise<string> {
+  const res = await app.app.request(
+    `/api/v1/members/${memberId}/change-email-link`,
+    json({ newEmail }, { cookie: ownerCookie })
+  );
+  expect(res.status).toBe(200);
+  return (await readJson(res)).verifyUrl as string;
+}
+
+interface Observables {
+  status: number;
+  location: string | null;
+  hasSessionCookie: boolean;
+  hasErrorParam: boolean;
+  body: string;
+}
+
+/** Consume a link logged out; returns the FULL observable set a prober reads. */
+async function consume(verifyUrl: string): Promise<Observables> {
+  const res = await app.app.request(verifyUrl, { headers: { 'x-forwarded-for': nextIp() } });
+  const location = res.headers.get('location');
+  const setCookie = res.headers.get('set-cookie') ?? '';
+  const body = res.status === 200 ? await res.text() : '';
+  return {
+    status: res.status,
+    location,
+    hasSessionCookie: /better-auth\.session_token=[^;]/.test(setCookie),
+    hasErrorParam: (location ?? '').includes('error='),
+    body
+  };
+}
+
+/** Rewrite (or drop) the callbackURL query param on a minted verify URL. */
+function withCallback(verifyUrl: string, callbackURL: string | null): string {
+  const u = new URL(verifyUrl, 'http://localhost:3000');
+  if (callbackURL === null) u.searchParams.delete('callbackURL');
+  else u.searchParams.set('callbackURL', callbackURL);
+  return u.pathname + u.search;
+}
+
+/** Every observable must agree between the taken and the free consume. */
+function expectIdentical(taken: Observables, free: Observables): void {
+  expect(taken.status).toBe(free.status);
+  expect(taken.location).toBe(free.location);
+  expect(taken.hasSessionCookie).toBe(free.hasSessionCookie);
+  expect(taken.hasErrorParam).toBe(false);
+  expect(free.hasErrorParam).toBe(false);
+  expect(taken.body).toBe(free.body);
+}
+
+beforeAll(async () => {
+  container = await startPostgres();
+  app = await createTestApp(await createDatabase(container, 'oracle_uniform'));
+  await app.app.request(
+    '/api/v1/setup',
+    json({ setupToken: 'integration-test-setup-token', instanceName: 'Oracle', owner: OWNER })
+  );
+  ownerCookie = extractCookie(
+    await app.app.request(
+      '/api/v1/auth/sign-in/email',
+      json({ email: OWNER.email, password: OWNER.password })
+    )
+  );
+
+  // The member whose email the owner "changes" while probing.
+  const inv = await readJson(
+    await app.app.request(
+      '/api/v1/invitations',
+      json({ email: MEMBER.email, role: 'member' }, { cookie: ownerCookie })
+    )
+  );
+  const token = (inv.acceptUrl as string).split('/invite/')[1]!;
+  expect(
+    (
+      await app.app.request(
+        '/api/v1/invitations/accept',
+        json({ token, name: MEMBER.name, password: MEMBER.password })
+      )
+    ).status
+  ).toBe(200);
+  const members = await readJson(
+    await app.app.request('/api/v1/members', { headers: { cookie: ownerCookie } })
+  );
+  memberId = members.members.find((m: { email: string }) => m.email === MEMBER.email).id;
+
+  // The probed address: an account that exists on the instance but holds no
+  // membership in this workspace (another tenant's user, say) — so the mint's
+  // workspace-scoped advisory pre-check does NOT catch it and the collision
+  // would only surface at consumption, exactly the oracle's shape.
+  await app.db.pool.query(
+    `INSERT INTO "user" (id, name, email, email_verified, created_at, updated_at)
+     VALUES ('oracle-elsewhere-user', 'Elsewhere', $1, true, now(), now())`,
+    [ELSEWHERE_EMAIL]
+  );
+}, 120_000);
+
+afterAll(async () => {
+  await app?.stop();
+  await container?.stop();
+});
+
+/**
+ * Consume, once for a FRESH unused address (the change goes through) and once
+ * for ELSEWHERE_EMAIL (a collision), under the SAME callbackURL shape, and
+ * assert every observable agrees. A counter hands each call a distinct fresh
+ * address, since every successful free consume renames the member.
+ */
+let freshCounter = 0;
+async function bothWaysUnder(callbackURL: string | null): Promise<{ taken: Observables; free: Observables }> {
+  const fresh = `fresh${freshCounter++}@oracle.test`;
+  const free = await consume(withCallback(await mint(fresh), callbackURL));
+  const taken = await consume(withCallback(await mint(ELSEWHERE_EMAIL), callbackURL));
+  return { taken, free };
+}
+
+describe('the change-email consume answers uniformly (door 1)', () => {
+  it('the minted shape (relative callbackURL): taken ≡ free, and only free renames the member', async () => {
+    const before = await memberEmail();
+    const { taken, free } = await bothWaysUnder('/account');
+    expectIdentical(taken, free);
+    expect(free.status).toBeGreaterThanOrEqual(300);
+    expect(free.status).toBeLessThan(400);
+    // The free consume renamed the member; the collision left both accounts.
+    expect(await memberEmail()).not.toBe(before);
+    const { rows } = await app.db.pool.query(`SELECT 1 FROM "user" WHERE email = $1`, [ELSEWHERE_EMAIL]);
+    expect(rows.length).toBe(1);
+  });
+
+  it('Repro A — no callbackURL (the JSON path): taken ≡ free, both user:null (no user record leaks)', async () => {
+    const { taken, free } = await bothWaysUnder(null);
+    expectIdentical(taken, free);
+    expect(free.status).toBe(200);
+    // The free JSON must be normalized to user:null — a leaked user record is
+    // the whole oracle this repro exposed.
+    expect(JSON.parse(free.body)).toEqual({ status: true, user: null });
+    expect(JSON.parse(taken.body)).toEqual({ status: true, user: null });
+  });
+
+  it('Repro B — absolute SAME-ORIGIN callbackURL: taken ≡ free (both redirect, no oracle)', async () => {
+    const { taken, free } = await bothWaysUnder('http://localhost:3000/account');
+    expectIdentical(taken, free);
+    expect(free.status).toBeGreaterThanOrEqual(300);
+    expect(free.status).toBeLessThan(400);
+  });
+
+  // CAVEAT: this harness runs with NODE_ENV=test, which makes Better Auth
+  // skip ITS OWN callbackURL origin check — so these two assertions exercise
+  // safeRedirectLocation (our defence-in-depth layer) alone, not production's
+  // stacked guards. Do not read them as proof the upstream guard works.
+  it('an untrusted absolute callbackURL is refused IDENTICALLY on both branches (no open redirect)', async () => {
+    const { taken, free } = await bothWaysUnder('http://evil.example/x');
+    expect(taken.status).toBe(free.status);
+    expect(taken.location).toBe(free.location);
+    for (const o of [taken, free]) {
+      expect(o.location ?? '').not.toContain('evil.example');
+    }
+  });
+
+  it('a tab-smuggled protocol-relative callbackURL never redirects off-origin, and both branches agree', async () => {
+    const { taken, free } = await bothWaysUnder('/\t/evil.example');
+    expect(taken.status).toBe(free.status);
+    expect(taken.location).toBe(free.location);
+    for (const o of [taken, free]) {
+      // The one thing that must never happen: a Location resolving off-origin.
+      const loc = o.location;
+      if (loc) {
+        const resolved = new URL(loc, 'http://localhost:3000');
+        expect(resolved.origin).toBe('http://localhost:3000');
+      }
+    }
+  });
+
+  it('never answers 5xx on the consume path, and the collision-branch session authenticates the target', async () => {
+    const res = await app.app.request(withCallback(await mint(ELSEWHERE_EMAIL), '/account'), {
+      headers: { 'x-forwarded-for': nextIp() }
+    });
+    expect(res.status).toBeLessThan(500);
+    // The link is sign-in-equivalent by design (LESSONS M6) — on the collision
+    // branch too, and for the TARGET member, never the probed account.
+    const cookie = extractCookie(res);
+    const me = await readJson(await app.app.request('/api/v1/me', { headers: { cookie } }));
+    expect(me.user.email).toBe(await memberEmail());
+    expect(me.user.email).not.toBe(ELSEWHERE_EMAIL);
+  });
+
+  it('an invalid token keeps its ordinary error redirect (uniformity never hides real failures)', async () => {
+    const res = await app.app.request('/api/v1/auth/verify-email?token=not-a-jwt&callbackURL=%2Faccount', {
+      headers: { 'x-forwarded-for': nextIp() }
+    });
+    expect(res.status).toBeGreaterThanOrEqual(300);
+    expect(res.status).toBeLessThan(400);
+    expect(res.headers.get('location')).toContain('error=');
+  });
+});
+
+/** Mint an invitation and return its accept token. */
+async function inviteToken(email: string): Promise<string> {
+  const inv = await readJson(
+    await app.app.request('/api/v1/invitations', json({ email, role: 'member' }, { cookie: ownerCookie }))
+  );
+  return (inv.acceptUrl as string).split('/invite/')[1]!;
+}
+
+describe('the invitation accept answers uniformly to a credential-less probe (door 2)', () => {
+  it('existing and fresh emails answer credentials_required alike; existence surfaces only on a committed create', async () => {
+    // ELSEWHERE_EMAIL has an account on the instance; the fresh one does not.
+    const takenToken = await inviteToken(ELSEWHERE_EMAIL);
+    const freshToken = await inviteToken('door2-fresh@oracle.test');
+
+    const probe = (token: string, body: Record<string, unknown> = {}) =>
+      app.app.request('/api/v1/invitations/accept', json({ token, ...body }));
+
+    // Credential-less: the account-existence bit is not readable for free —
+    // same status, same code on both. (The old oracle answered 409
+    // account_exists for the existing email, 400 for the fresh one.)
+    const taken = await probe(takenToken);
+    const fresh = await probe(freshToken);
+    expect(taken.status).toBe(fresh.status);
+    expect(taken.status).toBe(400);
+    expect((await readJson(taken)).error.code).toBe('credentials_required');
+    expect((await readJson(fresh)).error.code).toBe('credentials_required');
+
+    // Existence surfaces ONLY after real credentials are committed — the
+    // inherent signup collision, not a free pre-credential probe. The invite
+    // stays alive (nothing created on the collision branch).
+    const withCreds = await probe(takenToken, { name: 'Probe', password: 'a-probe-password-123' });
+    expect(withCreds.status).toBe(409);
+    expect((await readJson(withCreds)).error.code).toBe('account_exists');
+  });
+});