@xdelivered/emberflow 0.2.0

package/server/apiStore.test.ts

@@ -0,0 +1,324 @@
+import { mkdirSync, writeFileSync, rmSync, renameSync, readFileSync as rf, existsSync as ex } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ApiStore } from './apiStore';
+
+let root: string;
+beforeEach(() => {
+  root = join(tmpdir(), `apistore-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(root, 'claims', 'claims'), { recursive: true });
+  mkdirSync(join(root, 'billing'), { recursive: true });
+  writeFileSync(
+    join(root, 'claims', 'claims', 'create.json'),
+    JSON.stringify({
+      id: 'create-claim',
+      name: 'Create claim',
+      version: 1,
+      nodes: [],
+      edges: [],
+      http: { method: 'POST', path: '/claims' },
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+    }),
+  );
+  writeFileSync(
+    join(root, 'claims', 'claims', 'create.scenarios.json'),
+    JSON.stringify([{ name: 'happy', input: { body: {} } }]),
+  );
+  writeFileSync(
+    join(root, 'billing', 'charge.json'),
+    JSON.stringify({
+      id: 'charge',
+      name: 'Charge',
+      version: 1,
+      nodes: [],
+      edges: [],
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+    }),
+  );
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+describe('ApiStore read', () => {
+  it('lists all operations across the tree with ids and http', () => {
+    const store = new ApiStore(root);
+    const ids = store.list().map((o) => o.id).sort();
+    expect(ids).toEqual(['charge', 'create-claim']);
+    const create = store.list().find((o) => o.id === 'create-claim')!;
+    expect(create.http).toEqual({ method: 'POST', path: '/claims' });
+  });
+
+  it('loads a single operation by id and merges its scenarios sidecar', () => {
+    const store = new ApiStore(root);
+    const op = store.load('create-claim')!;
+    expect(op.name).toBe('Create claim');
+    expect(op.scenarios).toEqual([{ name: 'happy', input: { body: {} } }]);
+  });
+
+  it('maps an id to its on-disk relative path', () => {
+    const store = new ApiStore(root);
+    expect(store.pathOf('create-claim')).toBe('claims/claims/create');
+    expect(store.pathOf('charge')).toBe('billing/charge');
+    expect(store.pathOf('nope')).toBeUndefined();
+  });
+
+  it('listSummaries returns each op with its path and http', () => {
+    const summaries = new ApiStore(root).listSummaries();
+    const create = summaries.find((s) => s.id === 'create-claim')!;
+    expect(create.path).toBe('claims/claims/create');
+    expect(create.http).toEqual({ method: 'POST', path: '/claims' });
+    expect(create.name).toBe('Create claim');
+    const charge = summaries.find((s) => s.id === 'charge')!;
+    expect(charge.path).toBe('billing/charge');
+    expect(charge.http).toBeUndefined();
+  });
+
+  it('groups operations into an api/folder tree', () => {
+    const tree = new ApiStore(root).tree();
+    const claims = tree.apis.find((a) => a.name === 'claims')!;
+    expect(claims.folders.map((f) => f.name)).toEqual(['claims']);
+    expect(claims.folders[0].operations.map((o) => o.id)).toEqual(['create-claim']);
+    const billing = tree.apis.find((a) => a.name === 'billing')!;
+    expect(billing.operations.map((o) => o.id)).toEqual(['charge']);
+  });
+});
+
+describe('ApiStore write', () => {
+  it('saves a new operation into an api/folder with its scenario sidecar', () => {
+    const store = new ApiStore(root);
+    store.save(
+      {
+        id: 'del-claim',
+        name: 'Delete claim',
+        version: 1,
+        nodes: [],
+        edges: [],
+        http: { method: 'DELETE', path: '/claims/:id' },
+        scenarios: [{ id: 's', name: 's', input: {} }],
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      },
+      'claims/claims/delete',
+    );
+    const main = JSON.parse(rf(join(root, 'claims', 'claims', 'delete.json'), 'utf8'));
+    expect(main.id).toBe('del-claim');
+    expect(main.scenarios).toBeUndefined(); // scenarios live in the sidecar
+    expect(ex(join(root, 'claims', 'claims', 'delete.scenarios.json'))).toBe(true);
+    expect(store.load('del-claim')!.scenarios).toEqual([{ id: 's', name: 's', input: {} }]);
+  });
+
+  it('removes an operation and its sidecar by id', () => {
+    const store = new ApiStore(root);
+    expect(store.remove('create-claim')).toBe(true);
+    expect(store.load('create-claim')).toBeUndefined();
+    expect(ex(join(root, 'claims', 'claims', 'create.json'))).toBe(false);
+    expect(ex(join(root, 'claims', 'claims', 'create.scenarios.json'))).toBe(false);
+    expect(store.remove('nope')).toBe(false);
+  });
+
+  it('saves op-level mocks alongside scenarios in an object-shaped sidecar', () => {
+    const store = new ApiStore(root);
+    store.save(
+      {
+        id: 'del-claim',
+        name: 'Delete claim',
+        version: 1,
+        nodes: [],
+        edges: [],
+        scenarios: [{ id: 's', name: 's', input: {} }],
+        mocks: { dbNode: { rows: [] } },
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      },
+      'claims/claims/delete',
+    );
+    const sidecar = JSON.parse(rf(join(root, 'claims', 'claims', 'delete.scenarios.json'), 'utf8'));
+    expect(sidecar).toEqual({ scenarios: [{ id: 's', name: 's', input: {} }], mocks: { dbNode: { rows: [] } } });
+    const loaded = store.load('del-claim')!;
+    expect(loaded.scenarios).toEqual([{ id: 's', name: 's', input: {} }]);
+    expect(loaded.mocks).toEqual({ dbNode: { rows: [] } });
+  });
+
+  it('re-saving with scenarios only preserves the sidecar\'s existing top-level mocks untouched', () => {
+    const store = new ApiStore(root);
+    store.save(
+      {
+        id: 'del-claim',
+        name: 'Delete claim',
+        version: 1,
+        nodes: [],
+        edges: [],
+        scenarios: [{ id: 's', name: 's', input: {} }],
+        mocks: { dbNode: { rows: [] } },
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      },
+      'claims/claims/delete',
+    );
+    // Re-save as if a caller edited only scenarios and passed a flow object
+    // that never carried `mocks` at all (e.g. a client that doesn't round-trip
+    // unknown fields) — the sidecar's mocks must survive untouched.
+    store.save(
+      {
+        id: 'del-claim',
+        name: 'Delete claim',
+        version: 1,
+        nodes: [],
+        edges: [],
+        scenarios: [{ id: 's', name: 's', input: {} }, { id: 's2', name: 's2', input: {} }],
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      },
+      'claims/claims/delete',
+    );
+    const loaded = store.load('del-claim')!;
+    expect(loaded.scenarios).toEqual([{ id: 's', name: 's', input: {} }, { id: 's2', name: 's2', input: {} }]);
+    expect(loaded.mocks).toEqual({ dbNode: { rows: [] } });
+  });
+
+  it('loads a legacy bare-array sidecar (no mocks) exactly as before', () => {
+    const store = new ApiStore(root);
+    const op = store.load('create-claim')!;
+    expect(op.scenarios).toEqual([{ name: 'happy', input: { body: {} } }]);
+    expect(op.mocks).toBeUndefined();
+  });
+});
+
+describe('ApiStore.existsAt', () => {
+  it('reports true for an existing op path and false for a free one', () => {
+    const store = new ApiStore(root);
+    expect(store.existsAt('billing/charge')).toBe(true);
+    expect(store.existsAt('billing/refund')).toBe(false);
+    expect(store.existsAt('claims/claims/create')).toBe(true);
+  });
+});
+
+describe('ApiStore stale-cache resistance (out-of-band disk edits)', () => {
+  it('still finds a renamed op after a warm scan, and finds new ops without reconstruction', () => {
+    const store = new ApiStore(root);
+    // Warm the index.
+    expect(store.load('charge')).toBeDefined();
+
+    // Rename on disk out-of-band (same in-file id, new path).
+    renameSync(join(root, 'billing', 'charge.json'), join(root, 'billing', 'renamed.json'));
+    expect(store.load('charge')).toBeDefined();
+    expect(store.pathOf('charge')).toBe('billing/renamed');
+
+    // Add a brand-new op file on disk after construction.
+    writeFileSync(
+      join(root, 'billing', 'refund.json'),
+      JSON.stringify({
+        id: 'refund',
+        name: 'Refund',
+        version: 1,
+        nodes: [],
+        edges: [],
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      }),
+    );
+    expect(store.load('refund')).toBeDefined();
+  });
+
+  it('warns when two files share the same in-file id', () => {
+    writeFileSync(
+      join(root, 'billing', 'dup.json'),
+      JSON.stringify({
+        id: 'charge', // duplicate of billing/charge.json's id
+        name: 'Duplicate charge',
+        version: 1,
+        nodes: [],
+        edges: [],
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      }),
+    );
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    new ApiStore(root).list();
+    expect(warn.mock.calls.some(([msg]) => String(msg).includes('duplicate operation id "charge"'))).toBe(true);
+    warn.mockRestore();
+  });
+
+  it('warns when saving over a file that holds a different op id', () => {
+    const store = new ApiStore(root);
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    store.save(
+      {
+        id: 'new-id',
+        name: 'New name',
+        version: 1,
+        nodes: [],
+        edges: [],
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      },
+      'billing/charge', // currently holds id 'charge'
+    );
+    expect(warn.mock.calls.some(([msg]) => String(msg).includes('overwriting') && String(msg).includes('"charge"'))).toBe(true);
+    warn.mockRestore();
+  });
+});
+
+describe('ApiStore.resolveAuth', () => {
+  it('inherits an api-level _meta policy, op overrides win', () => {
+    mkdirSync(join(root, 'svc'), { recursive: true });
+    writeFileSync(join(root, 'svc', '_meta.json'), JSON.stringify({ auth: { scheme: 'bearer', secretRef: 'T' } }));
+    writeFileSync(
+      join(root, 'svc', 'pub.json'),
+      JSON.stringify({
+        id: 'pub-op-id',
+        name: 'Public op',
+        version: 1,
+        nodes: [],
+        edges: [],
+        http: { method: 'GET', path: '/pub', auth: 'none' },
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      }),
+    );
+    writeFileSync(
+      join(root, 'svc', 'sec.json'),
+      JSON.stringify({
+        id: 'sec-op-id',
+        name: 'Secure op',
+        version: 1,
+        nodes: [],
+        edges: [],
+        http: { method: 'GET', path: '/sec' },
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      }),
+    );
+    const store = new ApiStore(root);
+    expect(store.resolveAuth('sec-op-id')).toEqual({ scheme: 'bearer', secretRef: 'T' });
+    expect(store.resolveAuth('pub-op-id')).toBeNull();
+  });
+
+  it('_meta.json is not listed as an operation', () => {
+    writeFileSync(join(root, '_meta.json'), JSON.stringify({ auth: { scheme: 'apiKey', secretRef: 'K' } }));
+    expect(new ApiStore(root).list().some((o) => (o.id as string) === '_meta')).toBe(false);
+  });
+
+  it('fails closed (throws) when a present _meta.json in the chain is unparseable, instead of silently resolving to public', () => {
+    mkdirSync(join(root, 'svc'), { recursive: true });
+    // Corrupt JSON — e.g. a partial write or a typo.
+    writeFileSync(join(root, 'svc', '_meta.json'), '{ "auth": { "scheme": "bearer", ');
+    writeFileSync(
+      join(root, 'svc', 'op.json'),
+      JSON.stringify({
+        id: 'broken-meta-op',
+        name: 'Broken meta op',
+        version: 1,
+        nodes: [],
+        edges: [],
+        http: { method: 'GET', path: '/svc-op' },
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+      }),
+    );
+    const store = new ApiStore(root);
+    expect(() => store.resolveAuth('broken-meta-op')).toThrow(/unparseable/i);
+  });
+});

package/server/apiStore.ts

@@ -0,0 +1,241 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { AuthPolicy, HttpTrigger, WorkflowDefinition } from '../src/engine';
+
+export interface OpSummary { id: string; name: string; path: string; http?: HttpTrigger }
+export interface FolderNode { name: string; folders: FolderNode[]; operations: OpSummary[] }
+export interface ApiNode { name: string; folders: FolderNode[]; operations: OpSummary[] }
+export interface ApiTree { apis: ApiNode[] }
+
+/** File-backed store over an `apis/<api>/<folder…>/<op>.json` tree. Keys ops by
+ *  their in-file `id`; tracks each op's relative path (POSIX, no `.json`). */
+export class ApiStore {
+  readonly dir: string;
+  /** id → relative path (POSIX, no extension). Rebuilt on every scan. */
+  private index = new Map<string, string>();
+
+  constructor(dir: string) {
+    this.dir = dir;
+    mkdirSync(this.dir, { recursive: true });
+  }
+
+  private sidecarFor(relPath: string): string {
+    return join(this.dir, ...relPath.split('/')) + '.scenarios.json';
+  }
+
+  /** Sidecar files come in two shapes: the legacy bare array (scenarios only —
+   *  still written when an op has no mocks, for human-editability/back-compat)
+   *  and `{ scenarios?, mocks? }`, used once an op carries op-level mocks. */
+  private withSidecar(flow: WorkflowDefinition, relPath: string): WorkflowDefinition {
+    const path = this.sidecarFor(relPath);
+    if (!existsSync(path)) return flow;
+    try {
+      const raw = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+      if (Array.isArray(raw)) {
+        return raw.length > 0 ? { ...flow, scenarios: raw as WorkflowDefinition['scenarios'] } : flow;
+      }
+      if (raw && typeof raw === 'object') {
+        const { scenarios, mocks } = raw as { scenarios?: WorkflowDefinition['scenarios']; mocks?: Record<string, unknown> };
+        let out = flow;
+        if (Array.isArray(scenarios) && scenarios.length > 0) out = { ...out, scenarios };
+        if (mocks && typeof mocks === 'object') out = { ...out, mocks };
+        return out;
+      }
+      return flow;
+    } catch (err) {
+      console.warn(`[apiStore] skipping unparseable ${relPath}.scenarios.json: ${String(err)}`);
+      return flow;
+    }
+  }
+
+  /** Reads just the sidecar's top-level `mocks`, ignoring `scenarios` — used
+   *  by `save` to preserve mocks when the incoming flow doesn't carry them. */
+  private readSidecarMocks(relPath: string): Record<string, unknown> | undefined {
+    const path = this.sidecarFor(relPath);
+    if (!existsSync(path)) return undefined;
+    try {
+      const raw = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+      if (Array.isArray(raw) || !raw || typeof raw !== 'object') return undefined;
+      const { mocks } = raw as { mocks?: Record<string, unknown> };
+      return mocks && typeof mocks === 'object' ? mocks : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Recursively collect operation files as { flow, relPath }. */
+  private scan(): Array<{ flow: WorkflowDefinition; relPath: string }> {
+    const out: Array<{ flow: WorkflowDefinition; relPath: string }> = [];
+    this.index = new Map();
+    const walk = (absDir: string, relParts: string[]): void => {
+      for (const entry of readdirSync(absDir)) {
+        const abs = join(absDir, entry);
+        if (statSync(abs).isDirectory()) {
+          walk(abs, [...relParts, entry]);
+          continue;
+        }
+        if (entry === '_meta.json') continue;
+        if (!entry.endsWith('.json') || entry.endsWith('.scenarios.json')) continue;
+        const relPath = [...relParts, entry.slice(0, -'.json'.length)].join('/');
+        try {
+          const flow = JSON.parse(readFileSync(abs, 'utf8')) as WorkflowDefinition;
+          const existing = this.index.get(flow.id);
+          if (existing !== undefined && existing !== relPath) {
+            console.warn(`[apiStore] duplicate operation id "${flow.id}" at ${existing} and ${relPath} — only one is reachable`);
+          } else {
+            this.index.set(flow.id, relPath);
+          }
+          out.push({ flow, relPath });
+        } catch (err) {
+          console.warn(`[apiStore] skipping unparseable ${relPath}.json: ${String(err)}`);
+        }
+      }
+    };
+    walk(this.dir, []);
+    return out;
+  }
+
+  list(): WorkflowDefinition[] {
+    return this.scan().map(({ flow, relPath }) => this.withSidecar(flow, relPath));
+  }
+
+  /** One entry per operation with its on-disk relative path and `http` metadata
+   *  (id/name/http from the file itself), for the studio's tree view. */
+  listSummaries(): OpSummary[] {
+    return this.scan().map(({ flow, relPath }) => ({ id: flow.id, name: flow.name, path: relPath, http: flow.http }));
+  }
+
+  /** True when an operation file already sits at `relPath` — used by
+   *  POST /operations to refuse to silently overwrite an existing op with a
+   *  brand-new one saved at the same path. */
+  existsAt(relPath: string): boolean {
+    const abs = join(this.dir, ...relPath.split('/')) + '.json';
+    return existsSync(abs);
+  }
+
+  load(id: string): WorkflowDefinition | undefined {
+    const relPath = this.pathOf(id);
+    if (!relPath) return undefined;
+    const abs = join(this.dir, ...relPath.split('/')) + '.json';
+    if (!existsSync(abs)) return undefined;
+    try {
+      const flow = JSON.parse(readFileSync(abs, 'utf8')) as WorkflowDefinition;
+      return this.withSidecar(flow, relPath);
+    } catch (err) {
+      console.warn(`[apiStore] skipping unparseable ${relPath}.json: ${String(err)}`);
+      return undefined;
+    }
+  }
+
+  /** id → relative path. Always rescans so it reflects the current on-disk state
+   *  (files may be added/renamed/deleted out-of-band by a coding agent). */
+  pathOf(id: string): string | undefined {
+    this.scan();
+    return this.index.get(id);
+  }
+
+  tree(): ApiTree {
+    const ops = this.scan();
+    const apis = new Map<string, ApiNode>();
+    const folderAt = (parent: { folders: FolderNode[] }, name: string): FolderNode => {
+      let f = parent.folders.find((x) => x.name === name);
+      if (!f) { f = { name, folders: [], operations: [] }; parent.folders.push(f); }
+      return f;
+    };
+    for (const { flow, relPath } of ops) {
+      const parts = relPath.split('/'); // [api, ...folders, opName]
+      const apiName = parts[0];
+      let api = apis.get(apiName);
+      if (!api) { api = { name: apiName, folders: [], operations: [] }; apis.set(apiName, api); }
+      const folderParts = parts.slice(1, -1);
+      let container: { folders: FolderNode[]; operations: OpSummary[] } = api;
+      for (const fp of folderParts) container = folderAt(container, fp);
+      container.operations.push({ id: flow.id, name: flow.name, path: relPath, http: flow.http });
+    }
+    return { apis: [...apis.values()] };
+  }
+
+  save(flow: WorkflowDefinition, relPath: string): void {
+    const abs = join(this.dir, ...relPath.split('/')) + '.json';
+    if (existsSync(abs)) {
+      try {
+        const existing = JSON.parse(readFileSync(abs, 'utf8')) as WorkflowDefinition;
+        if (existing.id !== undefined && existing.id !== flow.id) {
+          console.warn(`[apiStore] overwriting ${relPath} which held a different op id "${existing.id}"`);
+        }
+      } catch {
+        // unparseable existing file — nothing sensible to compare, proceed with the write.
+      }
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    const { scenarios, mocks, ...rest } = flow;
+    writeFileSync(abs, `${JSON.stringify(rest, null, 2)}\n`, 'utf8');
+    const sidecar = this.sidecarFor(relPath);
+    // A flow argument that doesn't carry `mocks` at all (undefined — not an
+    // empty object) means the caller never touched op-level mocks (e.g. a
+    // scenario-only edit round-tripped through a client that doesn't forward
+    // unknown fields) — preserve whatever is already on disk rather than
+    // silently dropping it.
+    const effectiveMocks = mocks !== undefined ? mocks : this.readSidecarMocks(relPath);
+    const hasScenarios = scenarios !== undefined && scenarios.length > 0;
+    const hasMocks = effectiveMocks !== undefined && Object.keys(effectiveMocks).length > 0;
+    if (hasMocks) {
+      writeFileSync(
+        sidecar,
+        `${JSON.stringify({ ...(hasScenarios ? { scenarios } : {}), mocks: effectiveMocks }, null, 2)}\n`,
+        'utf8',
+      );
+    } else if (hasScenarios) {
+      writeFileSync(sidecar, `${JSON.stringify(scenarios, null, 2)}\n`, 'utf8');
+    } else if (existsSync(sidecar)) {
+      rmSync(sidecar);
+    }
+    this.index.set(flow.id, relPath);
+  }
+
+  remove(id: string): boolean {
+    const relPath = this.pathOf(id);
+    if (!relPath) return false;
+    const abs = join(this.dir, ...relPath.split('/')) + '.json';
+    if (!existsSync(abs)) return false;
+    rmSync(abs);
+    const sidecar = this.sidecarFor(relPath);
+    if (existsSync(sidecar)) rmSync(sidecar);
+    this.index.delete(id);
+    return true;
+  }
+
+  /** Resolves the effective auth policy for an operation: walks the op's path
+   *  from the API root down through each folder, reading `_meta.json`'s `auth`
+   *  (nearest ancestor default), then applies the op's own `http.auth`
+   *  override — `'none'` -> explicitly public (null), a policy object -> that
+   *  policy, `'inherit'`/absent -> the inherited default. Returns the
+   *  effective policy or null (no auth — public by default). */
+  resolveAuth(id: string): AuthPolicy | null {
+    const relPath = this.pathOf(id);
+    if (!relPath) return null;
+    const parts = relPath.split('/'); // [api, ...folders, opName]
+    let inherited: AuthPolicy | null = null;
+    for (let depth = 1; depth < parts.length; depth++) {
+      const metaPath = join(this.dir, ...parts.slice(0, depth), '_meta.json');
+      if (!existsSync(metaPath)) continue;
+      try {
+        const meta = JSON.parse(readFileSync(metaPath, 'utf8')) as { auth?: AuthPolicy };
+        if (meta.auth) inherited = meta.auth;
+      } catch (err) {
+        // A present-but-corrupt _meta.json (partial write, typo, etc.) must
+        // never silently resolve to `null` (= public) — that's a fail-open
+        // security hole. Fail closed: throw and let the caller deny the op
+        // rather than mount it open. A merely ABSENT _meta.json is fine (see
+        // the `existsSync` check above) — only a broken one throws.
+        const metaRelPath = `${parts.slice(0, depth).join('/')}/_meta.json`;
+        throw new Error(`unparseable _meta.json at ${metaRelPath} — refusing to resolve auth (fail closed): ${String(err)}`);
+      }
+    }
+    const op = this.load(id);
+    const override = op?.http?.auth;
+    if (override === 'none') return null;
+    if (override && override !== 'inherit') return override;
+    return inherited;
+  }
+}

package/server/auth/enforce.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { enforceAuth } from './enforce';
+import { createDefaultVerifierRegistry } from './verifiers';
+import { isHttpError } from '../../src/engine';
+
+const verifiers = createDefaultVerifierRegistry();
+
+describe('enforceAuth', () => {
+  it('passes with a valid bearer token and returns user', () => {
+    const r = enforceAuth({
+      policy: { scheme: 'bearer', secretRef: 'T' },
+      request: { headers: { authorization: 'Bearer t' } },
+      secrets: { T: 't' },
+      verifiers,
+    });
+    expect(r.user).toEqual({ scheme: 'bearer' });
+  });
+
+  it('401s on a bad token', () => {
+    try {
+      enforceAuth({
+        policy: { scheme: 'bearer', secretRef: 'T' },
+        request: { headers: {} },
+        secrets: { T: 't' },
+        verifiers,
+      });
+      expect.unreachable();
+    } catch (e) {
+      expect(isHttpError(e) && e.status).toBe(401);
+    }
+  });
+
+  it('500s when the named verifier is missing (fail closed)', () => {
+    try {
+      enforceAuth({
+        policy: { scheme: 'bearer', secretRef: 'T', verify: 'ghost' },
+        request: { headers: {} },
+        secrets: { T: 't' },
+        verifiers,
+      });
+      expect.unreachable();
+    } catch (e) {
+      expect(isHttpError(e) && e.status).toBe(500);
+      expect(isHttpError(e) && (e.body as { error?: string })?.error).toBe('auth misconfigured: no verifier ghost');
+    }
+  });
+
+  it('500s when the secret is unresolved (fail closed)', () => {
+    try {
+      enforceAuth({
+        policy: { scheme: 'bearer', secretRef: 'MISSING' },
+        request: { headers: { authorization: 'Bearer t' } },
+        secrets: {},
+        verifiers,
+      });
+      expect.unreachable();
+    } catch (e) {
+      expect(isHttpError(e) && e.status).toBe(500);
+    }
+  });
+});

package/server/auth/enforce.ts

@@ -0,0 +1,6 @@
+// Re-exports the shared enforceAuth from src/engine/authVerify.ts. Kept as its
+// own module (rather than importing src/engine directly at call sites) so the
+// server-side auth call path has a stable, server-scoped entry point mirroring
+// the file map in the plan; the underlying logic is shared with the
+// requireAuth node (src/nodes/requireAuth.ts) to avoid divergence.
+export { enforceAuth } from '../../src/engine';

package/server/auth/types.ts

@@ -0,0 +1,5 @@
+// AuthPolicy/VerifyResult/Verifier are plain data/logic types shared with
+// src/engine/authVerify.ts (also used by src/nodes/requireAuth.ts, which is
+// bundled into the browser build — so src/ must not import from server/).
+// Re-exported here rather than redefined, to avoid divergence.
+export type { AuthPolicy, VerifyResult, Verifier } from '../../src/engine';

package/server/auth/verifiers.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { bearerVerifier, apiKeyVerifier, createDefaultVerifierRegistry } from './verifiers';
+import { isHttpError } from '../../src/engine';
+
+const call = (v: () => unknown) => {
+  try {
+    v();
+    return null;
+  } catch (e) {
+    return e;
+  }
+};
+
+describe('default verifiers', () => {
+  it('bearer accepts a matching token', () => {
+    const r = bearerVerifier({ request: { headers: { authorization: 'Bearer s3cret' } }, policy: { scheme: 'bearer', secretRef: 'T' }, secret: 's3cret' });
+    expect(r.user).toEqual({ scheme: 'bearer' });
+  });
+  it('bearer 401s a wrong/missing token', () => {
+    const e = call(() => bearerVerifier({ request: { headers: {} }, policy: { scheme: 'bearer', secretRef: 'T' }, secret: 's3cret' }));
+    expect(isHttpError(e) && e.status).toBe(401);
+  });
+  it('bearer 500s when the secret is unset (fail closed)', () => {
+    const e = call(() => bearerVerifier({ request: { headers: { authorization: 'Bearer x' } }, policy: { scheme: 'bearer', secretRef: 'T' }, secret: undefined }));
+    expect(isHttpError(e) && e.status).toBe(500);
+  });
+  it('apiKey reads the configured header', () => {
+    const r = apiKeyVerifier({ request: { headers: { 'x-api-key': 'k' } }, policy: { scheme: 'apiKey', secretRef: 'K' }, secret: 'k' });
+    expect(r.user).toEqual({ scheme: 'apiKey' });
+  });
+  it('registry seeds bearer + apiKey', () => {
+    const reg = createDefaultVerifierRegistry();
+    expect(reg.get('bearer')).toBe(bearerVerifier);
+    expect(reg.get('apiKey')).toBe(apiKeyVerifier);
+    expect(reg.get('nope')).toBeUndefined();
+  });
+});