@antasphere/chassis-server 1.0.0

package/test/integration/account-recovery.test.ts

@@ -0,0 +1,236 @@
+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';
+
+/**
+ * Password reset / account recovery (WS3 feature B):
+ *  - self-serve reset is closed (400) with no email driver, open with one;
+ *  - the admin-generated reset link works with NO email driver (the SMTP-free
+ *    recovery path), is single-use, revokes the target's sessions, and is
+ *    authorization-gated (member 403, admin-on-owner 403);
+ *  - the self-serve flow does not leak whether an email exists.
+ */
+
+const OWNER = { email: 'owner@rec.test', name: 'Rec Owner', password: 'rec-owner-password-12' };
+const MEMBER = { email: 'member@rec.test', name: 'Rec Member', password: 'rec-member-password-1' };
+
+let container: StartedPostgreSqlContainer;
+
+const json = (body: unknown) => ({
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify(body)
+});
+
+async function signIn(app: TestApp, email: string, password: string): Promise<Response> {
+  return app.app.request('/api/v1/auth/sign-in/email', json({ email, password }));
+}
+
+beforeAll(async () => {
+  container = await startPostgres();
+});
+
+afterAll(async () => {
+  await container?.stop();
+});
+
+describe('no email driver (default)', () => {
+  let app: TestApp;
+  let ownerCookie: string;
+  let memberId: string;
+  let adminMemberId: string;
+
+  beforeAll(async () => {
+    app = await createTestApp(await createDatabase(container, 'rec_none'));
+    await app.app.request(
+      '/api/v1/setup',
+      json({ setupToken: 'integration-test-setup-token', instanceName: 'Rec', owner: OWNER })
+    );
+    ownerCookie = extractCookie(await signIn(app, OWNER.email, OWNER.password));
+
+    // Add a member (invite → accept) and a separate admin.
+    const inv = await readJson(
+      await app.app.request('/api/v1/invitations', {
+        ...json({ email: MEMBER.email, role: 'member' }),
+        headers: { 'content-type': 'application/json', cookie: ownerCookie }
+      })
+    );
+    const token = (inv.acceptUrl as string).split('/invite/')[1]!;
+    await app.app.request(
+      '/api/v1/invitations/accept',
+      json({ token, name: MEMBER.name, password: MEMBER.password })
+    );
+
+    const admin = { email: 'admin@rec.test', name: 'Rec Admin', password: 'rec-admin-password-12' };
+    const inv2 = await readJson(
+      await app.app.request('/api/v1/invitations', {
+        ...json({ email: admin.email, role: 'member' }),
+        headers: { 'content-type': 'application/json', cookie: ownerCookie }
+      })
+    );
+    const token2 = (inv2.acceptUrl as string).split('/invite/')[1]!;
+    await app.app.request(
+      '/api/v1/invitations/accept',
+      json({ token: token2, name: admin.name, password: admin.password })
+    );
+
+    const { members } = await readJson(
+      await app.app.request('/api/v1/members', { headers: { cookie: ownerCookie } })
+    );
+    memberId = members.find((m: { email: string }) => m.email === MEMBER.email).id;
+    adminMemberId = members.find((m: { email: string }) => m.email === admin.email).id;
+    // Promote the admin.
+    await app.app.request(`/api/v1/members/${adminMemberId}`, {
+      ...json({ role: 'admin' }),
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json', cookie: ownerCookie }
+    });
+  });
+
+  afterAll(async () => {
+    await app.stop();
+  });
+
+  it('reports passwordReset: false in discovery and closes self-serve reset', async () => {
+    const info = await readJson(await app.app.request('/api/v1/instance'));
+    expect(info.auth.passwordReset).toBe(false);
+
+    const res = await app.app.request(
+      '/api/v1/auth/request-password-reset',
+      json({ email: OWNER.email, redirectTo: 'http://localhost:3000/reset-password' })
+    );
+    expect(res.status).toBe(400); // RESET_PASSWORD_DISABLED
+  });
+
+  it('admin mints a working single-use reset link that revokes the target sessions', async () => {
+    // The member has a live session before the reset.
+    const memberCookie = extractCookie(await signIn(app, MEMBER.email, MEMBER.password));
+    expect((await app.app.request('/api/v1/me', { headers: { cookie: memberCookie } })).status).toBe(200);
+
+    const minted = await app.app.request(`/api/v1/members/${memberId}/reset-link`, {
+      method: 'POST',
+      headers: { cookie: ownerCookie }
+    });
+    expect(minted.status).toBe(200);
+    const { resetUrl } = await readJson(minted);
+    const token = new URL(resetUrl).searchParams.get('token')!;
+    expect(token).toBeTruthy();
+
+    const newPassword = 'rec-member-new-password-9';
+    const reset = await app.app.request('/api/v1/auth/reset-password', json({ newPassword, token }));
+    expect(reset.status).toBe(200);
+
+    // Old password is dead, the new one works.
+    expect((await signIn(app, MEMBER.email, MEMBER.password)).status).toBe(401);
+    expect((await signIn(app, MEMBER.email, newPassword)).status).toBe(200);
+
+    // The token is single-use.
+    const reuse = await app.app.request('/api/v1/auth/reset-password', json({ newPassword, token }));
+    expect(reuse.status).toBe(400);
+
+    // The pre-reset session was revoked.
+    expect((await app.app.request('/api/v1/me', { headers: { cookie: memberCookie } })).status).toBe(401);
+  });
+
+  it('refuses reset-link minting to non-admins and admin-on-owner', async () => {
+    // A plain member cannot mint at all (403 from the role gate).
+    const memberCookie = extractCookie(await signIn(app, MEMBER.email, 'rec-member-new-password-9'));
+    const asMember = await app.app.request(`/api/v1/members/${memberId}/reset-link`, {
+      method: 'POST',
+      headers: { cookie: memberCookie }
+    });
+    expect(asMember.status).toBe(403);
+
+    // An admin (non-owner) cannot mint for an owner.
+    const admin = { email: 'admin@rec.test', password: 'rec-admin-password-12' };
+    const adminCookie = extractCookie(await signIn(app, admin.email, admin.password));
+    const { members } = await readJson(
+      await app.app.request('/api/v1/members', { headers: { cookie: adminCookie } })
+    );
+    const ownerId = members.find((m: { email: string }) => m.email === OWNER.email).id;
+    const asAdmin = await app.app.request(`/api/v1/members/${ownerId}/reset-link`, {
+      method: 'POST',
+      headers: { cookie: adminCookie }
+    });
+    expect(asAdmin.status).toBe(403);
+  });
+});
+
+describe('with an email driver', () => {
+  let app: TestApp;
+
+  beforeAll(async () => {
+    // SMTP points at a dead port — sends fail, but Better Auth runs them in the
+    // background (errors swallowed), so the endpoint still answers generically
+    // and the verification row is created regardless.
+    app = await createTestApp(await createDatabase(container, 'rec_smtp'), {
+      EMAIL_DRIVER: 'smtp',
+      SMTP_URL: 'smtp://127.0.0.1:1',
+      EMAIL_FROM: 'Rec <noreply@rec.test>'
+    });
+    await app.app.request(
+      '/api/v1/setup',
+      json({ setupToken: 'integration-test-setup-token', instanceName: 'RecSmtp', owner: OWNER })
+    );
+  });
+
+  afterAll(async () => {
+    await app.stop();
+  });
+
+  it('reports passwordReset: true and completes a self-serve reset', async () => {
+    const info = await readJson(await app.app.request('/api/v1/instance'));
+    expect(info.auth.passwordReset).toBe(true);
+
+    const res = await app.app.request(
+      '/api/v1/auth/request-password-reset',
+      json({ email: OWNER.email, redirectTo: 'http://localhost:3000/reset-password' })
+    );
+    expect(res.status).toBe(200);
+
+    // Read the token the plugin stored, then complete the reset.
+    const { rows } = await app.db.pool.query<{ identifier: string }>(
+      `SELECT identifier FROM verification WHERE identifier LIKE 'reset-password:%' ORDER BY created_at DESC LIMIT 1`
+    );
+    const token = rows[0]!.identifier.replace('reset-password:', '');
+    const newPassword = 'rec-owner-new-password-77';
+    const reset = await app.app.request('/api/v1/auth/reset-password', json({ newPassword, token }));
+    expect(reset.status).toBe(200);
+    expect((await signIn(app, OWNER.email, newPassword)).status).toBe(200);
+  });
+
+  it('does not reveal whether an email exists (identical 200 for unknown)', async () => {
+    const before = await app.db.pool.query(
+      `SELECT count(*)::int AS n FROM verification WHERE identifier LIKE 'reset-password:%'`
+    );
+    const res = await app.app.request(
+      '/api/v1/auth/request-password-reset',
+      json({ email: 'nobody@rec.test', redirectTo: 'http://localhost:3000/reset-password' })
+    );
+    expect(res.status).toBe(200);
+    const after = await app.db.pool.query(
+      `SELECT count(*)::int AS n FROM verification WHERE identifier LIKE 'reset-password:%'`
+    );
+    // No new reset token minted for a non-existent account.
+    expect(after.rows[0].n).toBe(before.rows[0].n);
+  });
+
+  it('rate-limits repeated reset requests', async () => {
+    let sawRateLimit = false;
+    for (let i = 0; i < 10 && !sawRateLimit; i++) {
+      const r = await app.app.request(
+        '/api/v1/auth/request-password-reset',
+        json({ email: OWNER.email, redirectTo: 'http://localhost:3000/reset-password' })
+      );
+      if (r.status === 429) sawRateLimit = true;
+    }
+    expect(sawRateLimit).toBe(true);
+  });
+});

package/test/integration/account.test.ts

@@ -0,0 +1,120 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import type { StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+import { desc, eq } from 'drizzle-orm';
+import { auditLog } from '@antasphere/chassis-db';
+import {
+  createDatabase,
+  createTestApp,
+  extractCookie,
+  readJson,
+  startPostgres,
+  type TestApp
+} from './helpers.js';
+
+/**
+ * Self-service account management (WS3 feature C): change your own name and
+ * password through Better-Auth-native routes, mounted under /api/v1/auth.
+ * Email change (M6) needs a delivering email driver; this app has none, so
+ * the endpoint answers 400 — the full flows live in email-change.test.ts.
+ */
+
+const OWNER = { email: 'owner@acct.test', name: 'Acct Owner', password: 'acct-owner-password-12' };
+
+let container: StartedPostgreSqlContainer;
+let app: TestApp;
+
+const json = (body: unknown) => ({
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify(body)
+});
+
+const withCookie = (cookie: string, body: unknown) => ({
+  method: 'POST',
+  headers: { 'content-type': 'application/json', cookie },
+  body: JSON.stringify(body)
+});
+
+async function signIn(email: string, password: string): Promise<Response> {
+  return app.app.request('/api/v1/auth/sign-in/email', json({ email, password }));
+}
+
+beforeAll(async () => {
+  container = await startPostgres();
+  app = await createTestApp(await createDatabase(container, 'acct'));
+  await app.app.request(
+    '/api/v1/setup',
+    json({ setupToken: 'integration-test-setup-token', instanceName: 'Acct', owner: OWNER })
+  );
+});
+
+afterAll(async () => {
+  await app?.stop();
+  await container?.stop();
+});
+
+describe('profile: change your own name', () => {
+  it('updates the name and /me reflects it', async () => {
+    const cookie = extractCookie(await signIn(OWNER.email, OWNER.password));
+    const res = await app.app.request(
+      '/api/v1/auth/update-user',
+      withCookie(cookie, { name: 'Renamed Owner' })
+    );
+    expect(res.status).toBe(200);
+    const me = await readJson(await app.app.request('/api/v1/me', { headers: { cookie } }));
+    expect(me.user.name).toBe('Renamed Owner');
+  });
+});
+
+describe('change password', () => {
+  it('rejects a wrong current password', async () => {
+    const cookie = extractCookie(await signIn(OWNER.email, OWNER.password));
+    const res = await app.app.request(
+      '/api/v1/auth/change-password',
+      withCookie(cookie, { currentPassword: 'not-the-password', newPassword: 'acct-owner-brandnew-1' })
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it('changes the password, revokes other sessions, and lands in the audit log', async () => {
+    const sessionA = extractCookie(await signIn(OWNER.email, OWNER.password));
+    const sessionB = extractCookie(await signIn(OWNER.email, OWNER.password));
+    const newPassword = 'acct-owner-changed-42';
+
+    const res = await app.app.request(
+      '/api/v1/auth/change-password',
+      withCookie(sessionA, {
+        currentPassword: OWNER.password,
+        newPassword,
+        revokeOtherSessions: true
+      })
+    );
+    expect(res.status).toBe(200);
+
+    // The other session is dead; sign-in works only with the new password.
+    expect((await app.app.request('/api/v1/me', { headers: { cookie: sessionB } })).status).toBe(401);
+    expect((await signIn(OWNER.email, OWNER.password)).status).toBe(401);
+    expect((await signIn(OWNER.email, newPassword)).status).toBe(200);
+
+    // The change was audited (Better Auth routes bypass the /api/v1 middleware;
+    // an after-hook records it).
+    const [row] = await app.db.db
+      .select()
+      .from(auditLog)
+      .where(eq(auditLog.action, 'user.password_change'))
+      .orderBy(desc(auditLog.id))
+      .limit(1);
+    expect(row).toBeTruthy();
+  });
+});
+
+describe('change email without an email driver', () => {
+  it('answers 400 (self-serve change needs a delivering driver; see email-change.test.ts)', async () => {
+    const cookie = extractCookie(await signIn(OWNER.email, 'acct-owner-changed-42'));
+    const res = await app.app.request(
+      '/api/v1/auth/change-email',
+      withCookie(cookie, { newEmail: 'new@acct.test' })
+    );
+    expect(res.status).toBe(400);
+  });
+});

package/test/integration/api-quota.test.ts

@@ -0,0 +1,208 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import type { StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+import {
+  createDatabase,
+  createTestApp,
+  extractCookie,
+  readJson,
+  startPostgres,
+  type TestApp,
+  host
+} from './helpers.js';
+
+/**
+ * I3 — general per-principal API quota. The security property under test:
+ * every authenticated /api/v1 request consumes from a bucket keyed by the
+ * AUTHENTICATED principal identity (API-key id / session user id), so one
+ * principal exhausting its quota cannot touch another's, and no
+ * client-supplied header can rotate or escape a bucket. Exempt surfaces
+ * (public discovery, setup, the Better-Auth routes, /healthz) stay outside
+ * the quota entirely.
+ */
+
+const OWNER = { email: 'owner@quota.test', name: 'Quota Owner', password: 'quota-owner-password-1' };
+
+const json = (body: unknown) => ({
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify(body)
+});
+
+let container: StartedPostgreSqlContainer;
+
+beforeAll(async () => {
+  container = await startPostgres();
+});
+
+afterAll(async () => {
+  await container?.stop();
+});
+
+describe('sustained quota: isolation, threshold, headers, exemptions', () => {
+  let url: string;
+  let app: TestApp;
+  let replica: TestApp | undefined;
+  let ownerCookie: string;
+  let keyA: string;
+  let keyB: string;
+
+  const quotaEnv = { API_RATE_LIMIT_PER_MINUTE: '5', API_RATE_LIMIT_BURST: '1000' };
+
+  beforeAll(async () => {
+    url = await createDatabase(container, 'quota_sustained');
+    app = await createTestApp(url, quotaEnv);
+    await app.app.request(
+      '/api/v1/setup',
+      json({ setupToken: 'integration-test-setup-token', instanceName: 'Quota', owner: OWNER })
+    );
+    const signIn = await app.app.request(
+      '/api/v1/auth/sign-in/email',
+      json({ email: OWNER.email, password: OWNER.password })
+    );
+    ownerCookie = extractCookie(signIn);
+
+    // Two keys for the SAME user — isolation must hold per key, not per user.
+    // These two mints are the session bucket's only pre-test consumption (2/5).
+    const mint = (name: string) =>
+      app.app.request('/api/v1/api-keys', {
+        ...json({ name, scopes: [host.scopes.read] }),
+        headers: { 'content-type': 'application/json', cookie: ownerCookie }
+      });
+    keyA = (await readJson(await mint('key-a'))).key;
+    keyB = (await readJson(await mint('key-b'))).key;
+  });
+
+  afterAll(async () => {
+    await replica?.stop();
+    await app?.stop();
+  });
+
+  const me = (headers: Record<string, string>, target: TestApp = app) =>
+    target.app.request('/api/v1/me', { headers });
+
+  it('serves RateLimit headers on successful responses so agents can self-throttle', async () => {
+    const res = await me({ authorization: `Bearer ${keyA}` });
+    expect(res.status).toBe(200);
+    expect(res.headers.get('ratelimit-limit')).toBe('5');
+    expect(res.headers.get('ratelimit-remaining')).toBe('4');
+    expect(Number(res.headers.get('ratelimit-reset'))).toBeGreaterThan(0);
+    expect(res.headers.get('x-ratelimit-limit')).toBe('5');
+  });
+
+  it('trips at the configured threshold with Retry-After and the standard envelope', async () => {
+    // 4 more requests exhaust key A's 5-point bucket.
+    for (let i = 0; i < 4; i++) {
+      expect((await me({ authorization: `Bearer ${keyA}` })).status).toBe(200);
+    }
+    const limited = await me({ authorization: `Bearer ${keyA}` });
+    expect(limited.status).toBe(429);
+    const body = await readJson(limited);
+    expect(body.error.code).toBe('rate_limited');
+    const retryAfter = Number(limited.headers.get('retry-after'));
+    expect(retryAfter).toBeGreaterThanOrEqual(1);
+    expect(retryAfter).toBeLessThanOrEqual(60);
+    expect(limited.headers.get('ratelimit-remaining')).toBe('0');
+    expect(limited.headers.get('x-ratelimit-remaining')).toBe('0');
+  });
+
+  it('cannot escape or rotate the bucket via client headers (the XFF trap)', async () => {
+    // TRUST_PROXY=true in the harness, so XFF IS believed for the client IP —
+    // and the quota must still hold, because its key is the principal.
+    for (const spoof of ['198.51.100.7', '198.51.100.8']) {
+      const res = await me({ authorization: `Bearer ${keyA}`, 'x-forwarded-for': spoof });
+      expect(res.status).toBe(429);
+    }
+  });
+
+  it("leaves principal B untouched while A is exhausted (same user's other key)", async () => {
+    const res = await me({ authorization: `Bearer ${keyB}` });
+    expect(res.status).toBe(200);
+    // Fresh bucket: B consumed exactly one point.
+    expect(res.headers.get('ratelimit-remaining')).toBe('4');
+  });
+
+  it("leaves the same user's SESSION untouched (third distinct bucket)", async () => {
+    const res = await me({ cookie: ownerCookie });
+    expect(res.status).toBe(200);
+  });
+
+  it('does not catch exempt surfaces: /healthz, discovery, setup, the auth routes', async () => {
+    expect((await app.app.request('/healthz')).status).toBe(200);
+    expect((await app.app.request('/api/v1/instance')).status).toBe(200);
+    // Setup answers its own domain error (already set up), never the quota's 429.
+    const setup = await app.app.request(
+      '/api/v1/setup',
+      json({ setupToken: 'integration-test-setup-token', instanceName: 'X', owner: OWNER })
+    );
+    expect(setup.status).toBe(410);
+    // The auth surfaces keep their own walls; the exhausted general quota
+    // must not block a sign-in.
+    const signIn = await app.app.request(
+      '/api/v1/auth/sign-in/email',
+      json({ email: OWNER.email, password: OWNER.password })
+    );
+    expect(signIn.status).toBe(200);
+  });
+
+  it('memory backend is per-replica: a second instance has its own buckets (Redis path = scale drill)', async () => {
+    replica = await createTestApp(url, quotaEnv);
+    // Key A is exhausted on the first instance…
+    expect((await me({ authorization: `Bearer ${keyA}` })).status).toBe(429);
+    // …but the second replica (no REDIS_URL → RateLimiterMemory) starts fresh.
+    // With REDIS_URL set the buckets are shared — proven by the I2 scale
+    // drill, which this quota rides via the same limiter factory.
+    expect((await me({ authorization: `Bearer ${keyA}` }, replica)).status).toBe(200);
+  });
+});
+
+describe('burst cap: 1-second spikes 429 and a fresh window recovers', () => {
+  let app: TestApp;
+  let key: string;
+
+  beforeAll(async () => {
+    const url = await createDatabase(container, 'quota_burst');
+    app = await createTestApp(url, { API_RATE_LIMIT_PER_MINUTE: '1000', API_RATE_LIMIT_BURST: '2' });
+    await app.app.request(
+      '/api/v1/setup',
+      json({ setupToken: 'integration-test-setup-token', instanceName: 'Burst', owner: OWNER })
+    );
+    const signIn = await app.app.request(
+      '/api/v1/auth/sign-in/email',
+      json({ email: OWNER.email, password: OWNER.password })
+    );
+    const cookie = extractCookie(signIn);
+    const mint = await app.app.request('/api/v1/api-keys', {
+      ...json({ name: 'burst', scopes: [host.scopes.read] }),
+      headers: { 'content-type': 'application/json', cookie }
+    });
+    key = (await readJson(mint)).key;
+  });
+
+  afterAll(async () => {
+    await app?.stop();
+  });
+
+  it('caps the spike, keeps the sustained budget intact, and recovers after the window', async () => {
+    const statuses: number[] = [];
+    let limited: Response | null = null;
+    for (let i = 0; i < 3; i++) {
+      const res = await app.app.request('/api/v1/me', { headers: { authorization: `Bearer ${key}` } });
+      statuses.push(res.status);
+      if (res.status === 429) limited = res;
+    }
+    // In-process requests land within one second: 2 pass, the spike 429s.
+    expect(statuses.filter((s) => s === 200)).toHaveLength(2);
+    expect(limited).not.toBeNull();
+    expect(limited!.headers.get('retry-after')).toBe('1');
+    expect((await readJson(limited!)).error.code).toBe('rate_limited');
+
+    // A fresh 1 s window recovers…
+    await new Promise((r) => setTimeout(r, 1200));
+    const recovered = await app.app.request('/api/v1/me', {
+      headers: { authorization: `Bearer ${key}` }
+    });
+    expect(recovered.status).toBe(200);
+    // …and the rejected spike burned NO sustained points: 3 successes total.
+    expect(recovered.headers.get('ratelimit-remaining')).toBe('997');
+  });
+});