@antasphere/chassis-server 1.0.0

package/test/unit/observability.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { Writable } from 'node:stream';
+import { pino } from 'pino';
+import { REDACT_PATHS } from '@antasphere/chassis-server/logger';
+import { buildCsp, inlineScriptHashes } from '@antasphere/chassis-server/middleware';
+
+describe('pino redaction (secrets never reach the stream)', () => {
+  it('censors passwords, tokens, auth headers, and connection strings', () => {
+    const lines: string[] = [];
+    const sink = new Writable({
+      write(chunk, _enc, cb) {
+        lines.push(String(chunk));
+        cb();
+      }
+    });
+    // Uses the REAL redaction list exported from logger.ts, so this test
+    // cannot drift from what production logs.
+    const log = pino({ redact: { paths: REDACT_PATHS, censor: '[redacted]' } }, sink);
+
+    log.info(
+      {
+        req: { headers: { authorization: 'Bearer super-secret', cookie: 'session=abc' } },
+        body: { password: 'hunter2', token: 'tok_123', secret: 's3cr3t' },
+        DATABASE_URL: 'postgres://u:p@h/db',
+        RESEND_API_KEY: 're_live_deadbeef',
+        BREVO_API_KEY: 'xkeysib-deadbeef',
+        S3_SECRET_ACCESS_KEY: 's3-super-secret',
+        SETUP_TOKEN: 'setup-deadbeef'
+      },
+      'test'
+    );
+
+    const out = lines.join('');
+    expect(out).not.toContain('super-secret');
+    expect(out).not.toContain('session=abc');
+    expect(out).not.toContain('hunter2');
+    expect(out).not.toContain('tok_123');
+    expect(out).not.toContain('postgres://u:p@h/db');
+    expect(out).not.toContain('re_live_deadbeef');
+    expect(out).not.toContain('xkeysib-deadbeef');
+    expect(out).not.toContain('s3-super-secret');
+    expect(out).not.toContain('setup-deadbeef');
+    expect(out).toContain('[redacted]');
+  });
+});
+
+describe('CSP with inline-script hashes', () => {
+  it('hashes each non-empty inline script and skips src scripts', () => {
+    const html = `<html><head>
+      <script src="/app.js"></script>
+      <script>console.log("boot")</script>
+      <script type="module">start()</script>
+      <script></script>
+    </head></html>`;
+    const hashes = inlineScriptHashes(html);
+    expect(hashes).toHaveLength(2);
+    for (const h of hashes) expect(h).toMatch(/^'sha256-[A-Za-z0-9+/=]+'$/);
+
+    const csp = buildCsp(hashes);
+    expect(csp).toContain(`script-src 'self' ${hashes[0]} ${hashes[1]}`);
+    expect(csp).toContain("frame-ancestors 'none'");
+    expect(csp).toContain("object-src 'none'");
+  });
+});

package/test/unit/openapi-doc.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it, vi } from 'vitest';
+import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { registerOpenApiDoc } from '@antasphere/chassis-server/api';
+
+/**
+ * PLT-3: `api.doc()` runs the whole synchronous OpenAPI generator inside the
+ * request handler, on an endpoint that is unauthenticated by design and
+ * therefore never reaches the per-principal quota — an anonymous event-loop
+ * DoS that starves /healthz and trips the container healthcheck.
+ */
+function apiWithRoutes(): OpenAPIHono {
+  const api = new OpenAPIHono();
+  api.openapi(
+    createRoute({
+      method: 'get',
+      path: '/things',
+      responses: {
+        200: { description: 'ok', content: { 'application/json': { schema: z.object({ a: z.string() }) } } }
+      }
+    }),
+    (c) => c.json({ a: 'b' }, 200)
+  );
+  return api;
+}
+
+const CONFIG = { openapi: '3.1.0', info: { title: 'Test API', version: '1' } };
+
+describe('registerOpenApiDoc', () => {
+  it('generates the document exactly ONCE, at registration', async () => {
+    const api = apiWithRoutes();
+    const spy = vi.spyOn(api, 'getOpenAPIDocument');
+    registerOpenApiDoc(api, CONFIG);
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    for (let i = 0; i < 25; i++) {
+      const res = await api.request('/openapi.json');
+      expect(res.status).toBe(200);
+    }
+    // Not once more, however hard it is hammered.
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('serves a byte-identical, correctly typed, cacheable document', async () => {
+    const api = apiWithRoutes();
+    registerOpenApiDoc(api, CONFIG);
+    const first = await api.request('/openapi.json');
+    const second = await api.request('/openapi.json');
+    expect(first.headers.get('content-type')).toContain('application/json');
+    expect(first.headers.get('cache-control')).toBe('public, max-age=300');
+    const a = await first.text();
+    const b = await second.text();
+    expect(a).toBe(b);
+    expect(JSON.parse(a)).toMatchObject({ info: { title: 'Test API' }, paths: { '/things': {} } });
+  });
+});
+
+/**
+ * The other half of PLT-3, and the half `registerOpenApiDoc` alone cannot
+ * prove: the API app has to actually USE it. Reverting `api/index.ts` to
+ * `api.doc('/openapi.json', …)` restores the per-request generator while every
+ * test above stays green, because none of them touch `api/index.ts`. Assert on
+ * the source, the same way head-rewrite.test.ts guards the dead HEAD idiom.
+ */
+describe('the API app does not register a per-request document generator', () => {
+  it('never calls api.doc() — registerOpenApiDoc is the only registration', () => {
+    // The routers live in two places since the chassis extraction: the generic
+    // ones here, the tool's in the app that composes it. This audits the
+    // generic ones; the tool audits its own in its own unit suite
+    // (apps/server/test/unit/api-registrations.test.ts in the tool template).
+    const apiDirs = [join(import.meta.dirname, '../../src/api')];
+    const offenders: string[] = [];
+    let registrations = 0;
+    const files = apiDirs.flatMap((dir) => readdirSync(dir).map((file) => join(dir, file)));
+    for (const file of files) {
+      // Skip the helper's own definition — we are auditing its CALLERS.
+      if (!file.endsWith('.ts') || file.endsWith('/openapi-doc.ts')) continue;
+      const code = readFileSync(file, 'utf8')
+        .split('\n')
+        .filter((line) => {
+          const t = line.trim();
+          return !t.startsWith('//') && !t.startsWith('*') && !t.startsWith('/*');
+        })
+        .join('\n');
+      if (/\bapi\.doc\d?\s*\(/.test(code)) offenders.push(file);
+      registrations += (code.match(/registerOpenApiDoc\s*\(/g) ?? []).length;
+    }
+    expect(offenders).toEqual([]);
+    // index.ts imports it and calls it exactly once.
+    expect(registrations).toBe(1);
+  });
+});

package/test/unit/rate-limit-consume-on.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { Hono } from 'hono';
+import { RateLimiterMemory } from 'rate-limiter-flexible';
+import { emailKeyOf, rateLimit } from '@antasphere/chassis-server/middleware';
+
+/**
+ * AF-4: the login wall consumed its buckets on ARRIVAL, before any credential
+ * was verified — and one of its keys is `email:<addr>` read straight out of
+ * the request body. Ten POSTs naming a victim therefore emptied that account's
+ * bucket and locked the owner out for the window, and the owner's own correct
+ * sign-ins spent the same budget.
+ *
+ * `consumeOn: 'failure'` keeps the brute-force wall exactly as tight (a wrong
+ * password IS a failure and still costs a point, an exhausted bucket still
+ * 429s before the handler runs) while a successful sign-in costs nothing.
+ */
+const ip = () => '203.0.113.9';
+
+function loginApp(limiter: RateLimiterMemory, consumeOn: 'arrival' | 'failure') {
+  const app = new Hono();
+  app.use('/sign-in', rateLimit(limiter, ip, emailKeyOf, { consumeOn }));
+  app.post('/sign-in', async (c) => {
+    const body = (await c.req.json()) as { email: string; password: string };
+    if (body.password !== 'correct-horse') return c.json({ error: 'bad credentials' }, 401);
+    return c.json({ ok: true });
+  });
+  return app;
+}
+
+const attempt = (app: Hono, password: string) =>
+  app.request('/sign-in', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ email: 'victim@example.com', password })
+  });
+
+describe('rateLimit consumeOn', () => {
+  it('a SUCCESSFUL sign-in costs the account nothing', async () => {
+    const limiter = new RateLimiterMemory({ points: 3, duration: 900 });
+    const app = loginApp(limiter, 'failure');
+    for (let i = 0; i < 10; i++) {
+      const res = await attempt(app, 'correct-horse');
+      expect(res.status).toBe(200);
+    }
+    expect(await limiter.get('email:victim@example.com')).toBeNull();
+  });
+
+  it('a FAILED sign-in still costs a point — the brute-force wall is intact', async () => {
+    const limiter = new RateLimiterMemory({ points: 3, duration: 900 });
+    const app = loginApp(limiter, 'failure');
+    expect((await attempt(app, 'wrong')).status).toBe(401);
+    expect((await attempt(app, 'wrong')).status).toBe(401);
+    expect((await attempt(app, 'wrong')).status).toBe(401);
+    // Fourth arrival finds an empty bucket and is refused BEFORE the handler.
+    const fourth = await attempt(app, 'wrong');
+    expect(fourth.status).toBe(429);
+    expect(await fourth.json()).toMatchObject({ error: { code: 'rate_limited' } });
+  });
+
+  it('consumeOn arrival — the old behaviour — burns the victim budget on success', async () => {
+    // Pinning the contrast, so a revert to the default is loud.
+    const limiter = new RateLimiterMemory({ points: 3, duration: 900 });
+    const app = loginApp(limiter, 'arrival');
+    for (let i = 0; i < 3; i++) expect((await attempt(app, 'correct-horse')).status).toBe(200);
+    expect((await attempt(app, 'correct-horse')).status).toBe(429);
+  });
+
+  it('defaults to arrival so every other surface is unchanged', async () => {
+    const limiter = new RateLimiterMemory({ points: 1, duration: 900 });
+    const app = new Hono();
+    app.use('/send', rateLimit(limiter, ip));
+    app.post('/send', (c) => c.json({ sent: true }));
+    expect((await app.request('/send', { method: 'POST' })).status).toBe(200);
+    expect((await app.request('/send', { method: 'POST' })).status).toBe(429);
+  });
+});

package/test/unit/rate-limit.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import type { Context } from 'hono';
+import { makeClientIp } from '@antasphere/chassis-server/middleware';
+
+/**
+ * makeClientIp reads the RIGHTMOST x-forwarded-for hop (the one the trusted
+ * proxy appended/set) — the leftmost is client-claimed and spoofable. The
+ * stub has no socket, so getConnInfo throws and the fallback is 'unknown'.
+ */
+function stubContext(xff?: string): Context {
+  return {
+    req: {
+      header: (name: string) => (name.toLowerCase() === 'x-forwarded-for' ? xff : undefined)
+    }
+  } as unknown as Context;
+}
+
+describe('makeClientIp (rightmost XFF hop)', () => {
+  it('picks the rightmost hop when TRUST_PROXY is on', () => {
+    const clientIp = makeClientIp(true);
+    expect(clientIp(stubContext('6.6.6.6, 203.0.113.9'))).toBe('203.0.113.9');
+  });
+
+  it('returns the single hop when there is only one', () => {
+    const clientIp = makeClientIp(true);
+    expect(clientIp(stubContext('203.0.113.9'))).toBe('203.0.113.9');
+  });
+
+  it('trims whitespace around the selected hop', () => {
+    const clientIp = makeClientIp(true);
+    expect(clientIp(stubContext('a,   203.0.113.9  '))).toBe('203.0.113.9');
+  });
+
+  it('ignores x-forwarded-for entirely when TRUST_PROXY is off', () => {
+    const clientIp = makeClientIp(false);
+    // Header ignored → no socket in the stub → 'unknown' fallback.
+    expect(clientIp(stubContext('6.6.6.6, 203.0.113.9'))).toBe('unknown');
+  });
+});

package/test/unit/readyz-storage.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'vitest';
+import { healthRoutes } from '@antasphere/chassis-server/routes';
+import { createRuntimeState } from '@antasphere/chassis-server/util';
+
+/**
+ * OPS-4: /readyz must be a LIVE claim about the backing store, not a memory
+ * of the boot-time probe.
+ *
+ * The failure this guards is not theoretical: a restore that dies after
+ * wiping /data leaves the app running against storage it cannot write, and
+ * the old readiness route — a boot-time boolean — kept answering 200. A load
+ * balancer therefore kept sending it traffic, and the operator's own drill
+ * reported the instance healthy.
+ */
+function readyState() {
+  const state = createRuntimeState();
+  state.ready = true;
+  state.reason = '';
+  return state;
+}
+
+describe('/readyz asserts storage reachability', () => {
+  it('503s with reason "storage" when the store is unwritable, even though boot said ready', async () => {
+    const state = readyState();
+    const app = healthRoutes(state, {
+      probeStorage: () => Promise.reject(new Error('EROFS: /data/tmp is read-only'))
+    });
+
+    const res = await app.request('/readyz');
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ status: 'unavailable', reason: 'storage' });
+  });
+
+  it('200s when the store is writable', async () => {
+    const app = healthRoutes(readyState(), { probeStorage: () => Promise.resolve() });
+    const res = await app.request('/readyz');
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: 'ready' });
+  });
+
+  it('never leaks the driver error text to the unauthenticated endpoint', async () => {
+    const app = healthRoutes(readyState(), {
+      probeStorage: () => Promise.reject(new Error('s3: bucket acme-prod-secrets AccessDenied'))
+    });
+    const body = await (await app.request('/readyz')).text();
+    expect(body).not.toContain('acme-prod-secrets');
+    expect(body).not.toContain('AccessDenied');
+  });
+
+  it('flips back to 503 when a healthy instance loses its storage later', async () => {
+    let fail = false;
+    let clock = 0;
+    const app = healthRoutes(readyState(), {
+      probeStorage: () => (fail ? Promise.reject(new Error('gone')) : Promise.resolve()),
+      storageProbeTtlMs: 10,
+      now: () => clock
+    });
+
+    expect((await app.request('/readyz')).status).toBe(200);
+    fail = true;
+    clock += 1000; // past the success TTL
+    expect((await app.request('/readyz')).status).toBe(503);
+  });
+
+  it('caches a SUCCESS for the TTL but never caches a FAILURE', async () => {
+    let probes = 0;
+    let fail = false;
+    let clock = 0;
+    const app = healthRoutes(readyState(), {
+      probeStorage: () => {
+        probes++;
+        return fail ? Promise.reject(new Error('gone')) : Promise.resolve();
+      },
+      storageProbeTtlMs: 10_000,
+      now: () => clock
+    });
+
+    await app.request('/readyz');
+    await app.request('/readyz');
+    await app.request('/readyz');
+    expect(probes, 'successes are cached for the TTL').toBe(1);
+
+    clock += 10_001;
+    fail = true;
+    await app.request('/readyz');
+    await app.request('/readyz');
+    // A failure must re-probe every time so recovery is seen immediately.
+    expect(probes).toBe(3);
+
+    fail = false;
+    expect((await app.request('/readyz')).status).toBe(200);
+  });
+
+  it('coalesces concurrent probes into one call', async () => {
+    let probes = 0;
+    let release!: () => void;
+    const gate = new Promise<void>((r) => (release = r));
+    const app = healthRoutes(readyState(), {
+      probeStorage: () => {
+        probes++;
+        return gate;
+      }
+    });
+
+    const all = Promise.all([app.request('/readyz'), app.request('/readyz'), app.request('/readyz')]);
+    release();
+    for (const res of await all) expect(res.status).toBe(200);
+    expect(probes).toBe(1);
+  });
+
+  it('reports the failure to the logger hook', async () => {
+    const seen: unknown[] = [];
+    const app = healthRoutes(readyState(), {
+      probeStorage: () => Promise.reject(new Error('EROFS')),
+      onStorageFailure: (err) => seen.push(err)
+    });
+    await app.request('/readyz');
+    expect(seen).toHaveLength(1);
+    expect((seen[0] as Error).message).toBe('EROFS');
+  });
+
+  it('keeps draining and not-yet-ready ahead of the storage probe', async () => {
+    let probes = 0;
+    const state = createRuntimeState(); // ready=false, reason='booting'
+    const app = healthRoutes(state, {
+      probeStorage: () => {
+        probes++;
+        return Promise.resolve();
+      }
+    });
+
+    let res = await app.request('/readyz');
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ status: 'unavailable', reason: 'booting' });
+
+    state.ready = true;
+    state.reason = '';
+    state.draining = true;
+    res = await app.request('/readyz');
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ status: 'unavailable', reason: 'draining' });
+    expect(probes, 'no pointless writes against the store while shutting down').toBe(0);
+  });
+
+  it('/healthz stays dependency-free — it must not touch storage', async () => {
+    let probes = 0;
+    const app = healthRoutes(readyState(), {
+      probeStorage: () => {
+        probes++;
+        return Promise.reject(new Error('gone'));
+      }
+    });
+    const res = await app.request('/healthz');
+    expect(res.status).toBe(200);
+    expect(probes).toBe(0);
+  });
+});

package/test/unit/request-quota.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest';
+import { RateLimiterMemory } from 'rate-limiter-flexible';
+import type { EntitlementService, Principal, RequestQuota } from '@antasphere/chassis-contract';
+import { createRequestQuota, principalBucketKey } from '@antasphere/chassis-server/middleware';
+import type { Logger } from '@antasphere/chassis-server/logger';
+
+/**
+ * The general per-principal quota service: bucket keys derive from the
+ * AUTHENTICATED principal identity only, limits come from the
+ * EntitlementService seam, and backend/entitlement failures fail OPEN (the
+ * quota is a cost control, not an authz boundary).
+ */
+
+const noopLogger = { error: () => {}, info: () => {}, warn: () => {} } as unknown as Logger;
+
+function principal(overrides: Partial<Principal> = {}): Principal {
+  return {
+    userId: 'user-1',
+    email: 'u@example.test',
+    name: 'U',
+    workspaceId: 'ws-1',
+    role: 'member',
+    origin: 'local',
+    via: 'session',
+    scopes: null,
+    ...overrides
+  };
+}
+
+function stubEntitlements(quota: RequestQuota | (() => RequestQuota)): EntitlementService {
+  return {
+    check: async () => ({ allowed: true }),
+    getRequestQuota: async () => (typeof quota === 'function' ? quota() : quota)
+  };
+}
+
+const memoryMake = (prefix: string, points: number, duration: number) =>
+  new RateLimiterMemory({ keyPrefix: `rl:${prefix}`, points, duration });
+
+describe('principalBucketKey', () => {
+  it('keys API-key principals by the key id, not the user', () => {
+    const p = principal({ via: 'api_key', apiKeyId: 'key-abc', scopes: new Set(['things:read']) });
+    expect(principalBucketKey(p)).toBe('key:key-abc');
+  });
+
+  it('keys OAuth principals by the token subject (userId)', () => {
+    const p = principal({ via: 'oauth', scopes: new Set(['things:read']) });
+    expect(principalBucketKey(p)).toBe('oauth:user-1');
+  });
+
+  it('keys session principals by the user id', () => {
+    expect(principalBucketKey(principal())).toBe('session:user-1');
+  });
+
+  it('gives two API keys of the same user distinct buckets', () => {
+    const a = principal({ via: 'api_key', apiKeyId: 'key-a', scopes: new Set() });
+    const b = principal({ via: 'api_key', apiKeyId: 'key-b', scopes: new Set() });
+    expect(principalBucketKey(a)).not.toBe(principalBucketKey(b));
+  });
+});
+
+describe('createRequestQuota', () => {
+  it('trips at the sustained threshold with a retry hint and recovers headers state', async () => {
+    const quota = createRequestQuota({
+      entitlements: stubEntitlements({ perMinute: 3, burstPerSecond: 0 }),
+      make: memoryMake,
+      logger: noopLogger
+    });
+    const p = principal();
+
+    for (let i = 0; i < 3; i++) {
+      const d = await quota.consume(p);
+      expect(d?.ok).toBe(true);
+      expect(d?.limit).toBe(3);
+      expect(d?.remaining).toBe(2 - i);
+    }
+
+    const rejected = await quota.consume(p);
+    expect(rejected?.ok).toBe(false);
+    expect(rejected?.remaining).toBe(0);
+    expect(rejected?.retryAfterSeconds).toBeGreaterThanOrEqual(1);
+    expect(rejected?.retryAfterSeconds).toBeLessThanOrEqual(60);
+  });
+
+  it('isolates principals: A exhausted, B unaffected', async () => {
+    const quota = createRequestQuota({
+      entitlements: stubEntitlements({ perMinute: 2, burstPerSecond: 0 }),
+      make: memoryMake,
+      logger: noopLogger
+    });
+    const keyA = principal({ via: 'api_key', apiKeyId: 'key-a', scopes: new Set() });
+    const keyB = principal({ via: 'api_key', apiKeyId: 'key-b', scopes: new Set() });
+
+    await quota.consume(keyA);
+    await quota.consume(keyA);
+    expect((await quota.consume(keyA))?.ok).toBe(false);
+    expect((await quota.consume(keyB))?.ok).toBe(true);
+  });
+
+  it('returns null (disabled) when perMinute is 0', async () => {
+    const quota = createRequestQuota({
+      entitlements: stubEntitlements({ perMinute: 0, burstPerSecond: 100 }),
+      make: memoryMake,
+      logger: noopLogger
+    });
+    expect(await quota.consume(principal())).toBeNull();
+  });
+
+  it('caps 1-second spikes without burning sustained points, and a fresh window recovers', async () => {
+    const quota = createRequestQuota({
+      entitlements: stubEntitlements({ perMinute: 100, burstPerSecond: 2 }),
+      make: memoryMake,
+      logger: noopLogger
+    });
+    const p = principal();
+
+    expect((await quota.consume(p))?.ok).toBe(true);
+    expect((await quota.consume(p))?.ok).toBe(true);
+
+    const spiked = await quota.consume(p);
+    expect(spiked?.ok).toBe(false);
+    expect(spiked?.retryAfterSeconds).toBe(1);
+    // The rejected spike reported the sustained bucket untouched: 2 consumed.
+    expect(spiked?.remaining).toBe(98);
+
+    await new Promise((r) => setTimeout(r, 1100));
+    const recovered = await quota.consume(p);
+    expect(recovered?.ok).toBe(true);
+    // 3 sustained points consumed in total — the 429 burned none.
+    expect(recovered?.remaining).toBe(97);
+  });
+
+  it('fails open (null) when the entitlement lookup throws', async () => {
+    const quota = createRequestQuota({
+      entitlements: {
+        check: async () => ({ allowed: true }),
+        getRequestQuota: async () => {
+          throw new Error('plan service down');
+        }
+      },
+      make: memoryMake,
+      logger: noopLogger
+    });
+    expect(await quota.consume(principal())).toBeNull();
+  });
+});

package/test/unit/scopes.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { createScopeAllowlist } from '../../src/middleware/scopes.js';
+
+/**
+ * The chassis team routes in the fail-closed machine allowlist (PRDCT-2813):
+ * EXACT shapes and methods only. A method the route does not serve on a listed
+ * shape answers null (the gate's 403 `endpoint_not_allowed`), so a future
+ * handler on that shape stays unreachable to keys and tokens until opened
+ * consciously (verifier round 1, mutation #12: POST on the member path).
+ */
+const requiredScopeFor = createScopeAllowlist({ read: 'r', write: 'w', dataExport: 'x', rules: [] });
+const TEAM = '/api/v1/teams/11111111-2222-3333-4444-555555555555';
+
+describe('requiredScopeFor — teams (PRDCT-2813)', () => {
+  it('the list: GET under the read scope, POST under the write scope', () => {
+    expect(requiredScopeFor('/api/v1/teams', 'GET')).toBe('r');
+    expect(requiredScopeFor('/api/v1/teams', 'POST')).toBe('w');
+  });
+
+  it('the seat of one person: DELETE under the write scope, every other method closed', () => {
+    const seat = `${TEAM}/members/user-abc`;
+    expect(requiredScopeFor(seat, 'DELETE')).toBe('w');
+    expect(requiredScopeFor(seat, 'POST')).toBeNull();
+    expect(requiredScopeFor(seat, 'PUT')).toBeNull();
+    expect(requiredScopeFor(seat, 'PATCH')).toBeNull();
+  });
+
+  it('the roster: GET under the read scope, PUT closed', () => {
+    expect(requiredScopeFor(`${TEAM}/members`, 'GET')).toBe('r');
+    expect(requiredScopeFor(`${TEAM}/members`, 'PUT')).toBeNull();
+  });
+
+  it('a team id that is not a uuid is not a listed shape', () => {
+    expect(requiredScopeFor('/api/v1/teams/not-a-uuid', 'GET')).toBeNull();
+  });
+});
+
+describe('requiredScopeFor — members stay closed to machines (ADR 014, PRDCT-2816)', () => {
+  const MEMBER = '/api/v1/members/11111111-2222-3333-4444-555555555555';
+
+  it('the account deletion and the removal are UNLISTED for every method: sessions only', () => {
+    for (const method of ['POST', 'GET', 'PUT', 'PATCH', 'DELETE']) {
+      expect(requiredScopeFor(MEMBER, method)).toBeNull();
+      expect(requiredScopeFor(`${MEMBER}/remove`, method)).toBeNull();
+    }
+  });
+});
+
+describe('requiredScopeFor — the default workspace (PRDCT-2815)', () => {
+  const PATH = '/api/v1/me/default-workspace';
+
+  it('PUT is listed under the write scope', () => {
+    expect(requiredScopeFor(PATH, 'PUT')).toBe('w');
+  });
+
+  it('every other method on the path stays unlisted', () => {
+    for (const method of ['GET', 'POST', 'PATCH', 'DELETE']) {
+      expect(requiredScopeFor(PATH, method)).toBeNull();
+    }
+  });
+
+  it('a longer path and any other path under /me stay unlisted for PUT', () => {
+    expect(requiredScopeFor(`${PATH}/x`, 'PUT')).toBeNull();
+    expect(requiredScopeFor('/api/v1/me/anything', 'PUT')).toBeNull();
+  });
+});