cursedbelt-server 1.0.0

package/src/server/middleware/zValidator.spec.ts

@@ -0,0 +1,251 @@
+import { describe, expect, test } from 'bun:test';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { ChunkStore } from 'cursedbelt-core/ctgr/chunk-store';
+import { encodeRequest } from 'cursedbelt-core/ctgr';
+import type { CursedbeltEnv } from '../context';
+import { CTGR_ROUTE_PATTERN, unGETify } from '../ctgr';
+import {
+  toValidationIssues,
+  VALIDATION_ERROR_CODE,
+  type ValidationIssue,
+  validationEnvelope,
+} from '../errors';
+import { zValidator } from './zValidator';
+
+const ORIGIN = 'http://localhost';
+const json = (path: string, body: unknown) =>
+  new Request(ORIGIN + path, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+interface ValidationEnvelope {
+  error: { message: string; code?: string; context?: { issues?: ValidationIssue[] } };
+}
+
+describe('zValidator — acceptance contract', () => {
+  // The spec's headline scenarios: a bad body maps every zod issue to context.issues,
+  // a good body passes through, an all-optional patch accepts the empty object.
+  const schema = z.object({ name: z.string(), age: z.number() });
+  const app = new Hono<CursedbeltEnv>().post('/test', zValidator(schema), (c) =>
+    c.json(c.get('validatedBody') as object),
+  );
+
+  test('maps each zod issue to a validation issue in the canonical envelope', async () => {
+    const res = await app.fetch(json('/test', { name: 123, age: 'old' }));
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as ValidationEnvelope;
+    expect(body.error.context?.issues).toHaveLength(2);
+    expect(body.error.context?.issues?.[0].path).toBe('name');
+    expect(body.error.context?.issues?.[1].path).toBe('age');
+    expect(body.error.code).toBe('validation');
+    // Every issue carries a human-readable, zod-authored message.
+    expect(body.error.context?.issues?.[0].message).toBeTruthy();
+  });
+
+  test('a valid body passes through unchanged', async () => {
+    const res = await app.fetch(json('/test', { name: 'Alice', age: 30 }));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ name: 'Alice', age: 30 });
+  });
+
+  test('a partial (all-optional) patch schema accepts the empty object', async () => {
+    const patchApp = new Hono<CursedbeltEnv>().post('/p', zValidator(schema.partial()), (c) =>
+      c.json({ ok: true, body: c.get('validatedBody') as object }),
+    );
+    const res = await patchApp.fetch(json('/p', {}));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, body: {} });
+  });
+
+  test('produces the envelope without an errorEnvelope onError handler mounted', async () => {
+    // A bare Hono app (no onError) still gets the 400 envelope — zValidator returns
+    // the response directly, it never throws.
+    const bare = new Hono().post('/x', zValidator(z.object({ a: z.string() })), (c) =>
+      c.json({ ok: true }),
+    );
+    const res = await bare.fetch(json('/x', { a: 1 }));
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as ValidationEnvelope).error.code).toBe('validation');
+  });
+});
+
+describe('zValidator — typed access', () => {
+  test('the parsed value is readable via both c.req.valid and c.get', async () => {
+    const schema = z.object({ name: z.string() });
+    const app = new Hono<CursedbeltEnv>().post('/x', zValidator(schema), (c) => {
+      const viaValid = c.req.valid('json'); // typed z.infer<typeof schema>
+      const viaGet = c.get('validatedBody');
+      return c.json({ viaValid, equal: viaValid === viaGet });
+    });
+    const res = await app.fetch(json('/x', { name: 'Bo' }));
+    expect(await res.json()).toEqual({ viaValid: { name: 'Bo' }, equal: true });
+  });
+
+  test('zod coerces, defaults, and strips before the handler sees the body', async () => {
+    const schema = z.object({
+      title: z.string(),
+      pinned: z.boolean().default(false),
+    });
+    const app = new Hono<CursedbeltEnv>().post('/x', zValidator(schema), (c) =>
+      c.json(c.req.valid('json')),
+    );
+    const res = await app.fetch(json('/x', { title: 'hi', junk: 'dropped' }));
+    // .default() filled `pinned`; unknown `junk` stripped (default zod object mode).
+    expect(await res.json()).toEqual({ title: 'hi', pinned: false });
+  });
+
+  test('.passthrough()/looseObject keeps unknown keys for dynamic-data fields', async () => {
+    const schema = z.looseObject({ kind: z.string() });
+    const app = new Hono<CursedbeltEnv>().post('/x', zValidator(schema), (c) =>
+      c.json(c.req.valid('json')),
+    );
+    const res = await app.fetch(json('/x', { kind: 'step', extra: { nested: 1 } }));
+    expect(await res.json()).toEqual({ kind: 'step', extra: { nested: 1 } });
+  });
+});
+
+describe('zValidator — coercion boundary (the #1 ajv→zod regression)', () => {
+  test('a numeric query param uses z.coerce.number() and arrives as a number', async () => {
+    const query = z.object({
+      limit: z.coerce.number().default(20),
+      page: z.coerce.number().optional(),
+    });
+    const app = new Hono<CursedbeltEnv>().get('/list', zValidator(query, 'query'), (c) =>
+      c.json(c.req.valid('query')),
+    );
+    const res = await app.fetch(new Request(`${ORIGIN}/list?limit=5&page=3`));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ limit: 5, page: 3 });
+  });
+
+  test('a JSON body number is strict — a stringified number is rejected, not coerced', async () => {
+    const schema = z.object({ amount: z.number() });
+    const app = new Hono<CursedbeltEnv>().post('/x', zValidator(schema), (c) =>
+      c.json(c.req.valid('json')),
+    );
+    const res = await app.fetch(json('/x', { amount: '123' }));
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as ValidationEnvelope).error.context?.issues?.[0].path).toBe(
+      'amount',
+    );
+  });
+});
+
+describe('zValidator — date-time enforcement', () => {
+  // zod's z.iso.datetime() ENFORCES (ajv often only annotated); a partial date is a 400.
+  const schema = z.object({ startsAt: z.iso.datetime() });
+  const app = new Hono<CursedbeltEnv>().post('/ev', zValidator(schema), (c) =>
+    c.json(c.req.valid('json')),
+  );
+
+  test('rejects a partial date like "2024-01"', async () => {
+    const res = await app.fetch(json('/ev', { startsAt: '2024-01' }));
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as ValidationEnvelope).error.context?.issues?.[0].path).toBe(
+      'startsAt',
+    );
+  });
+
+  test('accepts a full ISO datetime', async () => {
+    const res = await app.fetch(json('/ev', { startsAt: '2024-01-15T10:00:00Z' }));
+    expect(res.status).toBe(200);
+  });
+});
+
+describe('zValidator — param target + nested paths', () => {
+  test('validates a path param', async () => {
+    const schema = z.object({ id: z.coerce.number() });
+    const app = new Hono<CursedbeltEnv>().get('/n/:id', zValidator(schema, 'param'), (c) =>
+      c.json(c.req.valid('param')),
+    );
+    expect(await (await app.fetch(new Request(`${ORIGIN}/n/42`))).json()).toEqual({ id: 42 });
+  });
+
+  test('a nested-object issue gets a dotted path', async () => {
+    const schema = z.object({ address: z.object({ city: z.string() }) });
+    const app = new Hono<CursedbeltEnv>().post('/x', zValidator(schema), (c) =>
+      c.json({ ok: true }),
+    );
+    const res = await app.fetch(json('/x', { address: { city: 9 } }));
+    expect(((await res.json()) as ValidationEnvelope).error.context?.issues?.[0].path).toBe(
+      'address.city',
+    );
+  });
+});
+
+describe('zValidator — ctgr GET-tunnel integration (the protection-critical path)', () => {
+  // A mutation tunnels through a `/ctgr<XX>` GET twin; unGETify decodes the real body
+  // onto c.get('ctgrDecoded'). zValidator MUST validate that, not the empty GET body.
+  const schema = z.object({ body: z.string(), pinned: z.boolean().default(false) });
+  const makeApp = () => {
+    const app = new Hono<CursedbeltEnv>();
+    app.use(CTGR_ROUTE_PATTERN, unGETify(new ChunkStore()));
+    // Both the real verb route AND its GET twin run the same validated handler.
+    const handler = zValidator(schema);
+    app.on('POST', '/notes', handler, (c) => c.json({ ok: true, body: c.req.valid('json') }));
+    app.on('GET', '/ctgrpo/notes', handler, (c) => c.json({ ok: true, body: c.req.valid('json') }));
+    return app;
+  };
+
+  test('a tunnelled POST validates the decoded body (not the empty GET body)', async () => {
+    const enc = await encodeRequest('POST', '/notes', { body: 'hi' });
+    const res = await makeApp().fetch(new Request(ORIGIN + enc.chunks[0].url));
+    expect(res.status).toBe(200);
+    // Decoded body validated + defaulted, despite the transport being a body-less GET.
+    expect(await res.json()).toEqual({ ok: true, body: { body: 'hi', pinned: false } });
+  });
+
+  test('a tunnelled POST with an invalid decoded body returns the 400 envelope', async () => {
+    const enc = await encodeRequest('POST', '/notes', { body: 123 });
+    const res = await makeApp().fetch(new Request(ORIGIN + enc.chunks[0].url));
+    expect(res.status).toBe(400);
+    const env = (await res.json()) as ValidationEnvelope;
+    expect(env.error.code).toBe('validation');
+    expect(env.error.context?.issues?.[0].path).toBe('body');
+  });
+
+  test('the direct (non-tunnelled) verb route still validates the live body', async () => {
+    const res = await makeApp().fetch(json('/notes', { body: 'direct' }));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, body: { body: 'direct', pinned: false } });
+  });
+});
+
+describe('validationEnvelope — shared builder contract (cursedbelt-core/errors)', () => {
+  test('toValidationIssues maps zod issues to { path, message }', () => {
+    const result = z.object({ a: z.string(), b: z.number() }).safeParse({ a: 1, b: 'x' });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(toValidationIssues(result.error)).toEqual([
+      { path: 'a', message: expect.any(String) },
+      { path: 'b', message: expect.any(String) },
+    ]);
+  });
+
+  test('validationEnvelope builds the canonical rich { error } shape from issues', () => {
+    const issues: ValidationIssue[] = [{ path: 'x', message: 'bad' }];
+    const { error } = validationEnvelope(issues);
+    expect(error).toMatchObject({
+      name: 'ApiError',
+      message: 'Validation failed',
+      code: 'validation',
+      status: 400,
+      context: { issues },
+      isOperational: true,
+    });
+    expect(typeof error.timestamp).toBe('string');
+    expect(validationEnvelope(issues, 'Custom').error.message).toBe('Custom');
+    expect(VALIDATION_ERROR_CODE).toBe('validation');
+  });
+
+  test('validationEnvelope accepts a ZodError directly (the middleware path)', () => {
+    const result = z.object({ name: z.string() }).safeParse({ name: 1 });
+    if (result.success) return;
+    const env = validationEnvelope(result.error);
+    expect(env.error.code).toBe('validation');
+    expect(env.error.context?.issues).toEqual([{ path: 'name', message: expect.any(String) }]);
+  });
+});

package/src/server/middleware/zValidator.ts

@@ -0,0 +1,114 @@
+/*
+ * zValidator — the cursedbelt request-validation middleware. ONE zod schema per
+ * endpoint drives server validation, the client form resolver, and the inferred TS
+ * types; this is the server half. A zod failure is mapped to the canonical
+ * `{ error: { message, code, context: { issues } } }` envelope via the shared
+ * `validationEnvelope` builder (cursedbelt-core/errors) — the SAME builder cursedshell's
+ * service-router uses — so clients parse field-level errors identically everywhere,
+ * with no per-route (or per-layer) validation drift.
+ *
+ * Two things make this a cursedbelt primitive rather than a bare `@hono/zod-validator`
+ * call:
+ *
+ *  1. **ctgr-awareness.** A mutating request tunnels through a `/ctgr<XX>` GET twin
+ *     (task 25); `unGETify` decodes the real body onto `c.get('ctgrDecoded').body`.
+ *     The raw request that reaches this middleware is a *GET with no body*, so reading
+ *     `c.req.json()` would validate `undefined` and every tunneled call would 400.
+ *     We therefore read the ctgr-decoded body first and fall back to the live request
+ *     only for direct (non-tunnelled) calls. This is exactly why a route must use
+ *     `zValidator` and never the raw `@hono/zod-validator`.
+ *  2. **The canonical envelope.** `@hono/zod-validator`'s default failure body is its
+ *     own shape; cursedbelt maps every zod issue to a `ValidationIssue` under
+ *     `context.issues` with the `validation` error code — the shared contract the
+ *     client data layer parses.
+ *
+ * On success the parsed value (zod has coerced `z.coerce.*`, applied `.default()`s,
+ * and stripped unknown keys) is exposed two ways so handlers can use whichever reads
+ * best: the idiomatic typed `c.req.valid('json')`, and the convenience
+ * `c.get('validatedBody')`.
+ */
+import type { Env, MiddlewareHandler } from 'hono';
+import type { ZodType, z } from 'zod';
+import type { CursedbeltEnv } from '../context';
+import { validationEnvelope } from '../errors';
+
+/** The request locations a schema can validate. Mirrors Hono's body/non-body split. */
+export type ZValidatorTarget = 'json' | 'form' | 'query' | 'param';
+
+/**
+ * Read the value a target validates against. The body targets (`json`/`form`) prefer
+ * the ctgr-decoded body so a tunnelled mutation validates its real payload; the
+ * URL-bound targets (`query`/`param`) are never tunnelled (GETs go direct) and read
+ * from the live request. A query object collapses single-valued keys to a string so
+ * `z.string()`/`z.coerce.number()` field schemas see a scalar (repeated keys stay an
+ * array) — matching Hono's own validator semantics.
+ */
+async function readTarget(
+  c: Parameters<MiddlewareHandler<CursedbeltEnv>>[0],
+  target: ZValidatorTarget,
+): Promise<unknown> {
+  if (target === 'json' || target === 'form') {
+    const decoded = c.get('ctgrDecoded');
+    if (decoded) return decoded.body;
+    if (target === 'json') return c.req.json().catch(() => undefined);
+    return c.req.parseBody();
+  }
+  if (target === 'param') return c.req.param();
+  return Object.fromEntries(
+    Object.entries(c.req.queries()).map(([key, values]) =>
+      values.length === 1 ? [key, values[0]] : [key, values],
+    ),
+  );
+}
+
+/**
+ * Validate a request `target` against a zod `schema`. Mount per route ahead of the
+ * handler:
+ *
+ * ```ts
+ * register('post', '/notes', zValidator(CreateNoteSchema), (c) => {
+ *   const body = c.req.valid('json'); // typed z.infer<typeof CreateNoteSchema>
+ *   // …
+ * });
+ * ```
+ *
+ * On failure responds `400` with the canonical envelope (field errors under
+ * `context.issues`); never throws, so it produces the same body whether or not the
+ * app mounts the {@link errorEnvelope} `onError` handler. On success the parsed value
+ * is available as both `c.req.valid(target)` and `c.get('validatedBody')`.
+ */
+export function zValidator<
+  Schema extends ZodType,
+  Target extends ZValidatorTarget = 'json',
+  E extends Env = CursedbeltEnv,
+  P extends string = string,
+>(
+  schema: Schema,
+  target: Target = 'json' as Target,
+): MiddlewareHandler<
+  E,
+  P,
+  { in: { [K in Target]: z.input<Schema> }; out: { [K in Target]: z.output<Schema> } }
+> {
+  const handler: MiddlewareHandler<CursedbeltEnv> = async (c, next) => {
+    const raw = await readTarget(c, target);
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+      return c.json(validationEnvelope(result.error), 400);
+    }
+    // Expose the parsed value both ways (typed `c.req.valid` + convenience getter).
+    c.req.addValidatedData(target, result.data as Record<string, unknown>);
+    c.set('validatedBody', result.data);
+    await next();
+  };
+  // The body is written against the concrete `CursedbeltEnv` (so the ctgr/validatedBody
+  // accessors type-check); the public signature is the generic, schema-typed
+  // MiddlewareHandler that flows `c.req.valid(target)` into the handler. Hono's Context
+  // is invariant in its Env, so this widening goes through `unknown` — the same cast
+  // a hand-rolled typed middleware (e.g. @hono/zod-validator) performs.
+  return handler as unknown as MiddlewareHandler<
+    E,
+    P,
+    { in: { [K in Target]: z.input<Schema> }; out: { [K in Target]: z.output<Schema> } }
+  >;
+}

package/src/server/migration/runner.spec.ts

@@ -0,0 +1,88 @@
+import { Database } from 'bun:sqlite';
+import { describe, expect, test } from 'bun:test';
+import { addColumnIfMissing, applyRecommendedPragmas, columnExists, runMigrations } from './runner';
+import type { Migration } from './types';
+
+describe('runMigrations', () => {
+  test('applies pending migrations once, in order, and is idempotent', () => {
+    const db = new Database(':memory:');
+    const migs: Migration[] = [
+      { name: '0001_users', up: (d) => d.run('CREATE TABLE users (id TEXT PRIMARY KEY)') },
+      { name: '0002_email', up: (d) => addColumnIfMissing(d, 'users', 'email', 'TEXT') },
+    ];
+
+    expect(runMigrations(db, migs)).toEqual(['0001_users', '0002_email']);
+    expect(columnExists(db, 'users', 'email')).toBe(true);
+    // _migrations records exactly the applied set.
+    const recorded = db
+      .query('SELECT name FROM _migrations ORDER BY name')
+      .all()
+      .map((r) => (r as { name: string }).name);
+    expect(recorded).toEqual(['0001_users', '0002_email']);
+
+    // Re-running is a no-op.
+    expect(runMigrations(db, migs)).toEqual([]);
+
+    // Appending a new migration runs only the new one.
+    const migs2: Migration[] = [
+      ...migs,
+      { name: '0003_name', up: (d) => addColumnIfMissing(d, 'users', 'name', 'TEXT') },
+    ];
+    expect(runMigrations(db, migs2)).toEqual(['0003_name']);
+  });
+
+  test('a throwing migration rolls back its transaction and is not recorded', () => {
+    const db = new Database(':memory:');
+    const migs: Migration[] = [
+      {
+        name: '0001_boom',
+        up: (d) => {
+          d.run('CREATE TABLE t (id TEXT)');
+          throw new Error('boom');
+        },
+      },
+    ];
+    expect(() => runMigrations(db, migs)).toThrow('boom');
+    // The CREATE TABLE inside the failed transaction was rolled back...
+    const tables = db.query("SELECT name FROM sqlite_master WHERE type='table' AND name='t'").all();
+    expect(tables).toHaveLength(0);
+    // ...and the migration was not recorded, so it retries next time.
+    const recorded = db.query("SELECT name FROM _migrations WHERE name='0001_boom'").all();
+    expect(recorded).toHaveLength(0);
+  });
+
+  test('addColumnIfMissing / columnExists are idempotent', () => {
+    const db = new Database(':memory:');
+    db.run('CREATE TABLE t (id TEXT)');
+    expect(columnExists(db, 't', 'x')).toBe(false);
+    expect(addColumnIfMissing(db, 't', 'x', 'INTEGER')).toBe(true);
+    expect(addColumnIfMissing(db, 't', 'x', 'INTEGER')).toBe(false);
+    expect(columnExists(db, 't', 'x')).toBe(true);
+  });
+});
+
+describe('applyRecommendedPragmas', () => {
+  test('turns on foreign keys + busy timeout (set outside any transaction)', () => {
+    const db = new Database(':memory:');
+    applyRecommendedPragmas(db);
+    expect((db.query('PRAGMA foreign_keys').get() as { foreign_keys: number }).foreign_keys).toBe(
+      1,
+    );
+    expect((db.query('PRAGMA busy_timeout').get() as { timeout: number }).timeout).toBe(5000);
+  });
+
+  test('foreign keys are actually enforced after the pragma', () => {
+    const db = new Database(':memory:');
+    applyRecommendedPragmas(db);
+    runMigrations(db, [
+      {
+        name: '0001',
+        up: (d) => {
+          d.run('CREATE TABLE parent (id TEXT PRIMARY KEY)');
+          d.run('CREATE TABLE child (id TEXT PRIMARY KEY, parent_id TEXT REFERENCES parent(id))');
+        },
+      },
+    ]);
+    expect(() => db.run("INSERT INTO child (id, parent_id) VALUES ('c', 'ghost')")).toThrow();
+  });
+});

package/src/server/migration/runner.ts

@@ -0,0 +1,87 @@
+import type { Database } from 'bun:sqlite';
+import { applyCcPragmas } from 'cwip/sqlite';
+import type { Migration } from './types';
+
+/**
+ * The versioned SQLite migration runner — a tiny `_migrations`-sentinel runner, NOT
+ * a schema-first ORM. It replaces the old scattered guarded-`ALTER` /
+ * `addColumnIfMissing` pattern with ordered, once-only migrations whose names are
+ * recorded once applied. Business tables stay raw (`db.query` + `data JSON`); only
+ * the *plumbing* tables get Kysely types (see `../db/kysely`).
+ */
+
+/**
+ * Apply the recommended connection PRAGMAs. **Call this BEFORE {@link runMigrations}
+ * and OUTSIDE any transaction** — `PRAGMA foreign_keys` is silently ignored inside a
+ * transaction, and the runner wraps each migration in one. Idempotent; safe on boot.
+ *
+ * This is now a straight alias of cwip's `applyCcPragmas`: the CC storage tier pins
+ * ONE pragma profile monorepo-wide (`CC_PRAGMAS` — WAL + NORMAL + busy_timeout 5000 +
+ * foreign_keys ON + wal_autocheckpoint 1000), and the belt-local copy that used to
+ * live here was the second implementation the spec forbids. The per-pragma
+ * `PragmaOptions` overrides are gone with it — a handle that drifts from the profile
+ * is a `pragma-drift` violation, not a configuration choice.
+ *
+ * @deprecated Prefer cwip's `assertCcPragmas`, which additionally verifies each
+ * pragma took and installs the WAL transaction-lifetime guard.
+ */
+export function applyRecommendedPragmas(db: Database): void {
+  applyCcPragmas(db);
+}
+
+/**
+ * Run every pending migration exactly once, in array order, each inside its own
+ * transaction, recording its `name` in `_migrations`. Returns the names actually
+ * applied this call (empty when already up to date — re-running is a no-op).
+ *
+ * Set the connection PRAGMAs first via {@link applyRecommendedPragmas} (foreign-key
+ * enforcement cannot be turned on inside the per-migration transaction).
+ */
+export function runMigrations(db: Database, migrations: readonly Migration[]): string[] {
+  db.run(
+    'CREATE TABLE IF NOT EXISTS _migrations (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)',
+  );
+
+  const applied = new Set(
+    (db.query('SELECT name FROM _migrations').all() as Array<{ name: string }>).map((r) => r.name),
+  );
+  const insert = db.prepare('INSERT INTO _migrations (name, applied_at) VALUES (?, ?)');
+  const ran: string[] = [];
+
+  for (const m of migrations) {
+    if (applied.has(m.name)) continue;
+    const apply = db.transaction(() => {
+      m.up(db);
+      insert.run(m.name, new Date().toISOString());
+    });
+    apply();
+    ran.push(m.name);
+  }
+  return ran;
+}
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+/** Does `table` have a column named `column`? (via `PRAGMA table_info`). */
+export function columnExists(db: Database, table: string, column: string): boolean {
+  const rows = db.query(`PRAGMA table_info(${quoteIdent(table)})`).all() as Array<{ name: string }>;
+  return rows.some((r) => r.name === column);
+}
+
+/**
+ * Add a column if it is missing (idempotent). Returns true when it was added. A
+ * migration helper for the rare evolve-in-place case; the canonical schema is built
+ * fresh by `0001_initial`, so new migrations normally `CREATE` rather than `ALTER`.
+ */
+export function addColumnIfMissing(
+  db: Database,
+  table: string,
+  column: string,
+  ddl: string,
+): boolean {
+  if (columnExists(db, table, column)) return false;
+  db.run(`ALTER TABLE ${quoteIdent(table)} ADD COLUMN ${quoteIdent(column)} ${ddl}`);
+  return true;
+}

package/src/server/migration/types.ts

@@ -0,0 +1,17 @@
+import type { Database } from 'bun:sqlite';
+
+/**
+ * One ordered, immutable schema migration. `name` is recorded in the `_migrations`
+ * sentinel once applied, so a migration's `up()` runs exactly once across the life
+ * of a database. Corrections land as NEW migrations — never edit a shipped one, and
+ * never rename one that has been applied (the name is its identity).
+ *
+ * `up()` runs inside the runner's per-migration transaction; throw to abort + roll
+ * back that migration (the sentinel row is not written, so it retries next boot).
+ */
+export interface Migration {
+  /** Unique, lexically-ordered name, e.g. `0001_initial`. Immutable once applied. */
+  readonly name: string;
+  /** Apply the migration. Runs inside the runner's transaction. */
+  up(db: Database): void;
+}

package/src/server/net/outboundGuard.spec.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'bun:test';
+import { assertPublicOutboundUrl, assertResolvedPublicUrl, OUTBOUND_URL_BLOCKED } from './outboundGuard';
+
+const code = (fn: () => unknown): string | undefined => {
+  try {
+    fn();
+  } catch (error) {
+    return (error as { code?: string }).code;
+  }
+  return undefined;
+};
+
+describe('assertPublicOutboundUrl — SSRF guard', () => {
+  it('allows ordinary public http/https targets', () => {
+    expect(assertPublicOutboundUrl('https://example.com/api').hostname).toBe('example.com');
+    expect(assertPublicOutboundUrl('http://93.184.216.34/').hostname).toBe('93.184.216.34'); // a public IP literal
+    expect(assertPublicOutboundUrl('https://8.8.8.8/').hostname).toBe('8.8.8.8');
+  });
+
+  it('blocks the cloud metadata address (the headline SSRF)', () => {
+    expect(code(() => assertPublicOutboundUrl('http://169.254.169.254/latest/meta-data/'))).toBe(OUTBOUND_URL_BLOCKED);
+  });
+
+  it('blocks loopback and localhost in every common form', () => {
+    for (const url of [
+      'http://127.0.0.1/',
+      'http://127.1/',
+      'http://localhost:4747/',
+      'http://LOCALHOST/',
+      'http://[::1]/',
+      'http://0.0.0.0/',
+      'http://2130706433/', // decimal 127.0.0.1
+      'http://0x7f000001/', // hex 127.0.0.1
+    ])
+      expect(code(() => assertPublicOutboundUrl(url))).toBe(OUTBOUND_URL_BLOCKED);
+  });
+
+  it('blocks the RFC1918 private ranges and CGNAT', () => {
+    for (const url of [
+      'http://10.0.0.5/',
+      'http://172.16.9.9/',
+      'http://172.31.255.255/',
+      'http://192.168.1.1/',
+      'http://100.64.0.1/',
+    ])
+      expect(code(() => assertPublicOutboundUrl(url))).toBe(OUTBOUND_URL_BLOCKED);
+  });
+
+  it('allows a public IP adjacent to a blocked range', () => {
+    expect(() => assertPublicOutboundUrl('http://172.32.0.1/')).not.toThrow(); // just outside 172.16/12
+    expect(() => assertPublicOutboundUrl('http://11.0.0.1/')).not.toThrow();
+  });
+
+  it('blocks IPv6 loopback, unique-local and link-local', () => {
+    for (const url of ['http://[::1]/', 'http://[fc00::1]/', 'http://[fd00:ec2::254]/', 'http://[fe80::1]/', 'http://[::ffff:127.0.0.1]/'])
+      expect(code(() => assertPublicOutboundUrl(url))).toBe(OUTBOUND_URL_BLOCKED);
+  });
+
+  it('blocks internal-only hostnames and cloud metadata name', () => {
+    for (const url of ['http://metadata.google.internal/', 'http://db.internal/', 'http://svc.cluster.local/', 'http://foo.localhost/'])
+      expect(code(() => assertPublicOutboundUrl(url))).toBe(OUTBOUND_URL_BLOCKED);
+  });
+
+  it('rejects non-http schemes, credentials, and malformed URLs', () => {
+    expect(code(() => assertPublicOutboundUrl('file:///etc/passwd'))).toBe(OUTBOUND_URL_BLOCKED);
+    expect(code(() => assertPublicOutboundUrl('gopher://example.com/'))).toBe(OUTBOUND_URL_BLOCKED);
+    expect(code(() => assertPublicOutboundUrl('http://user:pass@example.com/'))).toBe(OUTBOUND_URL_BLOCKED);
+    expect(code(() => assertPublicOutboundUrl('not a url'))).toBe(OUTBOUND_URL_BLOCKED);
+  });
+
+  it('honors an explicit host allowlist for a configured internal integration', () => {
+    expect(() => assertPublicOutboundUrl('http://localhost:4747/', { allowHosts: ['localhost'] })).not.toThrow();
+    // …but only the named host; a different internal host is still refused.
+    expect(code(() => assertPublicOutboundUrl('http://127.0.0.1/', { allowHosts: ['localhost'] }))).toBe(OUTBOUND_URL_BLOCKED);
+  });
+});
+
+describe('assertResolvedPublicUrl — DNS-aware guard', () => {
+  it('passes an IP literal without a DNS lookup', async () => {
+    expect((await assertResolvedPublicUrl('https://8.8.8.8/')).hostname).toBe('8.8.8.8');
+  });
+
+  it('still blocks a private IP literal', async () => {
+    let blocked = false;
+    await assertResolvedPublicUrl('http://169.254.169.254/').catch((e) => {
+      blocked = (e as { code?: string }).code === OUTBOUND_URL_BLOCKED;
+    });
+    expect(blocked).toBe(true);
+  });
+});