@haverstack/server 0.8.0

package/src/routes/types.ts

@@ -0,0 +1,57 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import { requireOwner } from '../middleware/auth.js';
+import { readJson } from '../lib/json.js';
+import { serializeType } from '@haverstack/wire-types';
+import {
+  hashSchema,
+  StackQueryError,
+  StackNotFoundError,
+  StackValidationError,
+} from '@haverstack/core';
+import type { TypeSchema } from '@haverstack/core';
+
+export function typeRoutes(ctx: StackContext): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+  const { adapter, stack } = ctx;
+
+  app.get('/', async (c) => {
+    const types = await adapter.listTypes();
+    return c.json(types.map(serializeType));
+  });
+
+  app.get('/:id', async (c) => {
+    const id = decodeURIComponent(c.req.param('id'));
+    const type = await adapter.getType(id);
+    if (!type) throw new StackNotFoundError('Type not found');
+    return c.json(serializeType(type));
+  });
+
+  app.post('/', requireOwner(stack.ownerEntityId), async (c) => {
+    const body = await readJson<Record<string, unknown>>(c);
+    if (!body.id || typeof body.id !== 'string') throw new StackQueryError('id is required');
+    if (!body.name || typeof body.name !== 'string') throw new StackQueryError('name is required');
+    if (!body.schema || typeof body.schema !== 'object')
+      throw new StackQueryError('schema is required');
+    if (!body.schemaHash || typeof body.schemaHash !== 'string')
+      throw new StackQueryError('schemaHash is required');
+
+    const computedHash = await hashSchema(body.schema as TypeSchema);
+    if (body.schemaHash !== computedHash)
+      throw new StackValidationError([
+        { path: 'schemaHash', message: 'schemaHash does not match schema' },
+      ]);
+
+    // stack.defineType() (not adapter.saveType() directly) is what runs the
+    // schema-drift check: redefining an existing typeId with anything
+    // beyond additive evolution throws StackSchemaDriftError, which
+    // adapter.saveType() alone has no way to enforce — it's a raw write.
+    const type = await stack.defineType(body.id, body.name, body.schema as TypeSchema, {
+      ...(body.migratesFrom ? { migratesFrom: body.migratesFrom as string } : {}),
+    });
+    return c.json(serializeType(type), 201);
+  });
+
+  return app;
+}

package/src/routes/wellknown.ts

@@ -0,0 +1,55 @@
+import { Hono } from 'hono';
+import {
+  WIRE_PROTOCOL_VERSION,
+  AUTH_METHOD_DID_CHALLENGE,
+  CHANGE_TRANSPORT_SSE,
+} from '@haverstack/wire-types';
+import type { DiscoveryResponse } from '@haverstack/wire-types';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import type { Config } from '../config.js';
+
+export function wellknownRoutes(ctx: StackContext, config: Config): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+
+  app.get('/stack', (c) => {
+    const body: DiscoveryResponse = {
+      version: WIRE_PROTOCOL_VERSION,
+      entityId: ctx.stack.ownerEntityId,
+      timezone: ctx.stack.timezone,
+      // The server's own request-size ceilings are authoritative here,
+      // overriding the adapter's `null` — nothing at the storage layer
+      // imposes a limit, but this server enforces both. See
+      // docs/spec/wire-format.md § Discovery.
+      capabilities: {
+        ...ctx.stack.features,
+        limits: {
+          attachmentBytes: config.maxAttachmentBytes,
+          contentBytes: config.maxContentBytes,
+        },
+      },
+      // The DID challenge-response handshake is always implemented by this
+      // server, so it's always advertised — a client holding a DID
+      // credential learns at open() that there's a handshake to perform,
+      // rather than discovering it as a 404 partway through one.
+      auth: { methods: [AUTH_METHOD_DID_CHALLENGE] },
+      // Top-level rather than inside `capabilities`, which carries only
+      // what the `...ctx.stack.features` spread brings. An object rather
+      // than a boolean for the same reason `auth` is: the surface grows
+      // entries — another transport, batched frames — not more booleans.
+      //
+      // Both flags are literals with no override: GET /changes does resume
+      // and does honor `?include=record`, and a client acts on this answer
+      // without asking again. An override could only ever make discovery
+      // lie about the route beside it.
+      changes: {
+        transports: [CHANGE_TRANSPORT_SSE],
+        resume: true,
+        records: true,
+      },
+    };
+    return c.json(body);
+  });
+
+  return app;
+}

package/src/shutdown.ts

@@ -0,0 +1,56 @@
+import type { Logger } from 'pino';
+import type { StackContext } from './stack.js';
+
+/**
+ * The subset of node-server's return value shutdown() needs. `close()`
+ * mirrors Node's http.Server: it stops accepting new connections and waits
+ * for open ones to end before invoking the callback. `closeAllConnections()`
+ * (Node >=18.2) destroys every open connection immediately, which is what
+ * makes a pending close() callback fire once the grace period expires.
+ * Optional because node-server's `ServerType` also covers Http2Server, whose
+ * @types/node surface omits it even though the app only ever serves HTTP/1.
+ */
+export type ShutdownServer = {
+  close(callback: () => void): void;
+  closeAllConnections?(): void;
+};
+
+/**
+ * Builds the shutdown sequence: stop the server (bounded by `timeoutMs` so a
+ * client holding a keep-alive connection open can't block it indefinitely),
+ * then release the stack's resources. Does not call process.exit — callers
+ * decide the exit code so this stays unit-testable.
+ */
+export function createShutdownHandler(
+  server: ShutdownServer,
+  ctx: StackContext,
+  logger: Logger,
+  timeoutMs: number,
+): (signal: string) => Promise<void> {
+  return async (signal: string) => {
+    logger.info({ signal }, 'Shutting down');
+
+    // A change-feed stream never drains on its own, so server.close() below
+    // would wait out the full grace period every time. See
+    // src/lib/changeStreams.ts.
+    ctx.changeStreams.closeAll();
+
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        logger.warn({ timeoutMs }, 'Shutdown grace period exceeded; forcing connections closed');
+        server.closeAllConnections?.();
+      }, timeoutMs);
+      server.close(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+
+    await ctx.queryWorker.close();
+    await ctx.stack.flush();
+    await ctx.stack.close();
+    await ctx.tokens.close();
+    ctx.nonces.close();
+    logger.info('Clean shutdown complete');
+  };
+}

package/src/stack.ts

@@ -0,0 +1,96 @@
+import { LocalAdapter, NativeTokenStore, defaultTokenStorePath } from '@haverstack/adapter-local';
+import {
+  ARTICLE,
+  BOOKMARK,
+  CONTACT,
+  NOTE,
+  PAGE,
+  PHOTO,
+  PLACE,
+  TASK,
+  defineCommonsTypes,
+} from '@haverstack/commons';
+import { Stack } from '@haverstack/core';
+import type { StackTokenStore } from '@haverstack/core/wire';
+import type { Logger } from 'pino';
+import type { Config } from './config.js';
+import { AuthNonceStore, defaultNonceStorePath } from './lib/nonceStore.js';
+import { QueryWorkerPool } from './lib/queryWorker/pool.js';
+import { ChangeStreamRegistry } from './lib/changeStreams.js';
+
+export type StackContext = {
+  adapter: LocalAdapter;
+  stack: Stack;
+  // Typed as the interface, not NativeTokenStore, so routes and middleware
+  // bind to the contract. close() is the one lifecycle hook every
+  // implementation needs and the core interface doesn't declare.
+  tokens: StackTokenStore & { close(): Promise<void> };
+  // DID challenge-response nonces — see AuthNonceStore. Also kept outside
+  // the portable stack file, in its own sibling store beside the tokens.
+  nonces: AuthNonceStore;
+  // Runs ScopedStack.query() off the request thread with a per-request
+  // deadline. See docs/spec/wire-format.md § Bounding query cost and
+  // src/lib/queryWorker/pool.ts.
+  queryWorker: QueryWorkerPool;
+  // Open GET /changes SSE connections, so shutdown can end them promptly
+  // rather than waiting out the drain timeout. See src/lib/changeStreams.ts.
+  changeStreams: ChangeStreamRegistry;
+};
+
+export async function initStack(config: Config, logger: Logger): Promise<StackContext> {
+  // openOrInitialize() decides between open and create without a TOCTOU
+  // gap. entityId goes in as a lazy provider so openOrInitialize()'s own
+  // owner-mismatch check, which throws, never runs on the open path —
+  // ENTITY_ID divergence is a warning below, not a failure — and so a
+  // missing ENTITY_ID is an error only when creating a database.
+  const adapter = await LocalAdapter.openOrInitialize({
+    path: config.dbPath,
+    entityId: () => {
+      if (!config.entityId) {
+        throw new Error(
+          'ENTITY_ID is required when initializing a new database (DB_PATH does not exist yet)',
+        );
+      }
+      return config.entityId;
+    },
+    timezone: config.timezone,
+  });
+
+  if (config.entityId && config.entityId !== adapter.ownerEntityId) {
+    logger.warn(
+      { configuredEntityId: config.entityId, storedOwnerEntityId: adapter.ownerEntityId },
+      "ENTITY_ID does not match the stack's stored owner; the configured value is ignored",
+    );
+  }
+
+  const stack = await Stack.create(
+    adapter,
+    config.ownerName
+      ? { ownerProfile: { name: config.ownerName, handle: config.ownerHandle ?? undefined } }
+      : undefined,
+  );
+
+  // Opt-in (SEED_COMMONS_TYPES). defineType() is idempotent — an identical
+  // schema is a no-op preserving createdAt — so this is safe every boot.
+  if (config.seedCommonsTypes) {
+    await defineCommonsTypes(stack, [NOTE, BOOKMARK, TASK, CONTACT, ARTICLE, PLACE, PAGE, PHOTO]);
+  }
+
+  // Composed as a separate part rather than sniffed off the adapter: auth
+  // material lives in its own file beside stack.db (not inside the
+  // portable stack export) per docs/spec/wire-format.md § Authentication.
+  const tokens = await NativeTokenStore.open({ path: defaultTokenStorePath(config.dbPath) });
+  const nonces = AuthNonceStore.open(defaultNonceStorePath(config.dbPath));
+
+  // Spawned only once the adapter has opened and seeded stack.db: each
+  // worker opens its own connection to that same file, and idempotent
+  // seeding makes the race survivable rather than worth running.
+  const queryWorker = new QueryWorkerPool({
+    init: { dbPath: config.dbPath },
+    poolSize: config.queryWorkerPoolSize,
+    queueLimit: config.queryQueueLimit,
+    logger,
+  });
+
+  return { adapter, stack, tokens, nonces, queryWorker, changeStreams: new ChangeStreamRegistry() };
+}

package/src/types.ts

@@ -0,0 +1,9 @@
+import type { TokenSession } from '@haverstack/core';
+
+/** Hono context variable map shared across all route files. */
+export type AppEnv = {
+  Variables: {
+    auth: TokenSession | null;
+    requestId: string;
+  };
+};

package/src/wireError.ts

@@ -0,0 +1,21 @@
+import type { Context } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import type { AppEnv } from './types.js';
+
+/**
+ * `{ error: { code, message } }` responses for failures outside the core
+ * `StackError` taxonomy — thrown core errors instead flow through
+ * `errorMiddleware` via `serializeError()`. `code` is a server-local
+ * extension for these (not `WireErrorCode`): `unauthorized` for a missing
+ * or invalid bearer token has no core class, per
+ * docs/spec/wire-format.md § Error responses ("no verified DID behind the
+ * request at all" predates any Stack operation).
+ */
+export function wireError(
+  c: Context<AppEnv>,
+  status: ContentfulStatusCode,
+  code: string,
+  message: string,
+): Response {
+  return c.json({ error: { code, message } }, status);
+}

package/tests/app.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createApp } from '../src/app.js';
+import { buildTestApp, testConfig, logger, req, TEST_TOKEN, type TestApp } from './setup.js';
+
+const NOTE_TYPE_ID = 'com.example.test/note@1';
+
+describe('request body size limit', () => {
+  let t: TestApp;
+  beforeEach(async () => {
+    t = await buildTestApp();
+    await t.ctx.stack.defineType(NOTE_TYPE_ID, 'Note', {
+      body: { kind: 'text' as const, required: false as const },
+    });
+  });
+  afterEach(async () => {
+    await t.cleanup();
+  });
+
+  it('returns a conforming 413 for an oversized POST /records body', async () => {
+    const smallApp = createApp(t.ctx, { ...testConfig(t.dbPath), maxContentBytes: 100 }, logger);
+    const { status, data } = await req(smallApp, 'POST', '/records', {
+      token: TEST_TOKEN,
+      body: { typeId: NOTE_TYPE_ID, content: { body: 'x'.repeat(500) } },
+    });
+    expect(status).toBe(413);
+    expect((data as { error: { code: string } }).error.code).toBe('payload_too_large');
+  });
+
+  it('returns a conforming 413 for an oversized PATCH body', async () => {
+    const smallApp = createApp(t.ctx, { ...testConfig(t.dbPath), maxContentBytes: 5000 }, logger);
+    const created = await req(smallApp, 'POST', '/records', {
+      token: TEST_TOKEN,
+      body: { typeId: NOTE_TYPE_ID, content: { body: 'short' } },
+    });
+    const id = (created.data as { id: string }).id;
+
+    const { status, data } = await req(smallApp, 'PATCH', `/records/${id}`, {
+      token: TEST_TOKEN,
+      body: { contentPatch: { body: 'x'.repeat(6000) } },
+    });
+    expect(status).toBe(413);
+    expect((data as { error: { code: string } }).error.code).toBe('payload_too_large');
+  });
+
+  it('succeeds for a body just under the limit', async () => {
+    const smallApp = createApp(t.ctx, { ...testConfig(t.dbPath), maxContentBytes: 500 }, logger);
+    const { status } = await req(smallApp, 'POST', '/records', {
+      token: TEST_TOKEN,
+      body: { typeId: NOTE_TYPE_ID, content: { body: 'well under the limit' } },
+    });
+    expect(status).toBe(200);
+  });
+
+  it('fires before JSON parsing, not after', async () => {
+    const smallApp = createApp(t.ctx, { ...testConfig(t.dbPath), maxContentBytes: 10 }, logger);
+    const res = await smallApp.request('/records', {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${TEST_TOKEN}`, 'Content-Type': 'application/json' },
+      // Not valid JSON at all — if the limit ran after parsing, this would
+      // surface as a parse/bad_request failure instead of a clean 413.
+      body: 'not valid json, and also over the 10-byte limit',
+    });
+    expect(res.status).toBe(413);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe('payload_too_large');
+  });
+
+  it('applies to routes outside the original per-prefix list (e.g. POST /attachments/gc)', async () => {
+    const smallApp = createApp(t.ctx, { ...testConfig(t.dbPath), maxContentBytes: 10 }, logger);
+    const { status } = await req(smallApp, 'POST', '/attachments/gc', {
+      token: TEST_TOKEN,
+      body: { graceMs: 999999, dryRun: true },
+    });
+    expect(status).toBe(413);
+  });
+
+  it('excludes POST /attachments so its own, larger ceiling still applies', async () => {
+    const smallApp = createApp(t.ctx, { ...testConfig(t.dbPath), maxContentBytes: 10 }, logger);
+    const res = await smallApp.request('/attachments', {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${TEST_TOKEN}`, 'Content-Type': 'text/plain' },
+      body: 'x'.repeat(1000), // well over the 10-byte content limit, under maxAttachmentBytes
+    });
+    expect(res.status).toBe(200);
+  });
+});

package/tests/changeFeedClient.ts

@@ -0,0 +1,156 @@
+/**
+ * A client-side reader for the change feed's SSE wire format
+ * (docs/spec/wire-format.md § Change feed). Hono's own `hono/streaming`
+ * ships an SSE *writer* (`streamSSE`) but nothing to consume one — that
+ * half is what this module provides, so tests/conformance.test.ts can
+ * drive changeFeedFixtures: open a connection, decode frames as they
+ * arrive, dispatch the fixture's `activity` mutations while it is still
+ * open, and collect what the connection produces.
+ */
+import type { Hono } from 'hono';
+import type { AppEnv } from '../src/app.js';
+
+export type DecodedFrame = {
+  /**
+   * SSE `id:`, when the wire line was present on *this* frame — not the
+   * persisted "last event ID" a spec-compliant EventSource client carries
+   * forward across events with no id of their own. changeFeedFixtures pins
+   * the literal per-frame wire content (a `reset` frame carries no id even
+   * immediately after a `record` frame that did), so this decoder resets
+   * per frame rather than inheriting.
+   */
+  id?: string;
+  event: string;
+  data: unknown;
+};
+
+/** Incremental SSE decoder: feed it raw chunks of the stream's text as they arrive. */
+export class SSEDecoder {
+  private buffer = '';
+  private eventName: string | undefined;
+  private id: string | undefined;
+  private dataLines: string[] = [];
+  private sawField = false;
+
+  /** Decode one chunk, returning any frames it completed. */
+  push(text: string): DecodedFrame[] {
+    this.buffer += text;
+    const frames: DecodedFrame[] = [];
+    let newlineIndex: number;
+    while ((newlineIndex = this.buffer.indexOf('\n')) !== -1) {
+      const rawLine = this.buffer.slice(0, newlineIndex);
+      this.buffer = this.buffer.slice(newlineIndex + 1);
+      const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+      if (line === '') {
+        const frame = this.dispatch();
+        if (frame) frames.push(frame);
+        continue;
+      }
+      if (line.startsWith(':')) continue; // comment line — a keepalive
+      const colonIndex = line.indexOf(':');
+      const field = colonIndex === -1 ? line : line.slice(0, colonIndex);
+      let value = colonIndex === -1 ? '' : line.slice(colonIndex + 1);
+      if (value.startsWith(' ')) value = value.slice(1);
+      this.sawField = true;
+      if (field === 'id') this.id = value;
+      else if (field === 'event') this.eventName = value;
+      else if (field === 'data') this.dataLines.push(value);
+      // 'retry' and any other field: not needed here, ignored.
+    }
+    return frames;
+  }
+
+  private dispatch(): DecodedFrame | undefined {
+    if (!this.sawField) return undefined; // a blank line with nothing since the last dispatch
+    const event = this.eventName ?? 'message';
+    const id = this.id;
+    const dataText = this.dataLines.join('\n');
+    this.eventName = undefined;
+    this.id = undefined;
+    this.dataLines = [];
+    this.sawField = false;
+    let data: unknown = dataText;
+    if (dataText) {
+      try {
+        data = JSON.parse(dataText);
+      } catch {
+        // Leave as raw text — a fixture asserting on parsed JSON fails loudly.
+      }
+    }
+    return { ...(id !== undefined && { id }), event, data };
+  }
+}
+
+export type ChangeFeedConnection = {
+  status: number;
+  /** Frames decoded so far, in arrival order. Mutated in place as more arrive. */
+  frames: DecodedFrame[];
+  /** Resolves with the first `count` frames once they've arrived, or rejects after timeoutMs. */
+  waitForFrames(count: number, timeoutMs?: number): Promise<DecodedFrame[]>;
+  /** Cancels the underlying reader and stops decoding. */
+  close(): Promise<void>;
+};
+
+export type OpenChangeFeedOpts = {
+  token?: string;
+  /** Additional headers, e.g. Last-Event-ID. */
+  headers?: Record<string, string>;
+};
+
+/**
+ * Opens an SSE connection against a Hono test app. `app.request()` resolves
+ * as soon as the response's headers are sent — the body stays open and
+ * readable while the server keeps writing — so a mutation dispatched via
+ * the ordinary `req()` helper while a connection from this function is
+ * still open reaches the same in-process stack and can produce frames on
+ * it, exactly as changeFeedFixtures' `activity` expects.
+ */
+export async function openChangeFeed(
+  app: Hono<AppEnv>,
+  path: string,
+  opts: OpenChangeFeedOpts = {},
+): Promise<ChangeFeedConnection> {
+  const headers: Record<string, string> = { Accept: 'text/event-stream' };
+  if (opts.token) headers['Authorization'] = `Bearer ${opts.token}`;
+  Object.assign(headers, opts.headers);
+
+  const res = await app.request(path, { headers });
+  const reader = res.body?.getReader();
+  const decoder = new SSEDecoder();
+  const textDecoder = new TextDecoder();
+  const frames: DecodedFrame[] = [];
+  let closed = false;
+
+  const pump = (async () => {
+    if (!reader) return;
+    while (!closed) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      frames.push(...decoder.push(textDecoder.decode(value, { stream: true })));
+    }
+  })();
+  // A rejected pump would otherwise surface as an unhandled rejection the
+  // moment close() cancels the reader mid-read.
+  pump.catch(() => {});
+
+  async function waitForFrames(count: number, timeoutMs = 2000): Promise<DecodedFrame[]> {
+    const start = Date.now();
+    while (frames.length < count) {
+      if (Date.now() - start > timeoutMs) {
+        throw new Error(
+          `Timed out after ${timeoutMs}ms waiting for ${count} frame(s); got ${frames.length}: ${JSON.stringify(frames)}`,
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    return frames.slice(0, count);
+  }
+
+  async function close(): Promise<void> {
+    closed = true;
+    if (reader) await reader.cancel().catch(() => {});
+    await pump;
+  }
+
+  return { status: res.status, frames, waitForFrames, close };
+}

package/tests/config.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { loadConfig } from '../src/config.js';
+
+const REQUIRED_ENV = {
+  DB_PATH: './stack.db',
+  OWNER_TOKEN: 'test-owner-token',
+  BASE_URL: 'https://stack.example.com',
+};
+
+describe('loadConfig', () => {
+  const savedEnv = { ...process.env };
+
+  beforeEach(() => {
+    for (const key of Object.keys(process.env)) delete process.env[key];
+    Object.assign(process.env, REQUIRED_ENV);
+  });
+
+  afterEach(() => {
+    for (const key of Object.keys(process.env)) delete process.env[key];
+    Object.assign(process.env, savedEnv);
+  });
+
+  it('accepts a well-formed DID as ENTITY_ID', () => {
+    process.env['ENTITY_ID'] = 'did:key:z6MkfooBar';
+    const config = loadConfig();
+    expect(config.entityId).toBe('did:key:z6MkfooBar');
+  });
+
+  it('rejects an ENTITY_ID that is not a DID', () => {
+    process.env['ENTITY_ID'] = 'not-a-did';
+    expect(() => loadConfig()).toThrow(/must be a DID/);
+  });
+
+  it('allows ENTITY_ID to be unset', () => {
+    const config = loadConfig();
+    expect(config.entityId).toBeNull();
+  });
+
+  it('reads OWNER_NAME and OWNER_HANDLE when set', () => {
+    process.env['OWNER_NAME'] = 'Jane';
+    process.env['OWNER_HANDLE'] = '@jane';
+    const config = loadConfig();
+    expect(config.ownerName).toBe('Jane');
+    expect(config.ownerHandle).toBe('@jane');
+  });
+
+  it('defaults OWNER_NAME and OWNER_HANDLE to null', () => {
+    const config = loadConfig();
+    expect(config.ownerName).toBeNull();
+    expect(config.ownerHandle).toBeNull();
+  });
+
+  it('leaves timezone undefined when TIMEZONE is unset', () => {
+    const config = loadConfig();
+    expect(config.timezone).toBeUndefined();
+  });
+
+  it('reads TIMEZONE when set', () => {
+    process.env['TIMEZONE'] = 'America/New_York';
+    const config = loadConfig();
+    expect(config.timezone).toBe('America/New_York');
+  });
+
+  it('defaults maxContentBytes to 1 MB', () => {
+    const config = loadConfig();
+    expect(config.maxContentBytes).toBe(1 * 1024 * 1024);
+  });
+
+  it('reads MAX_CONTENT_BYTES when set', () => {
+    process.env['MAX_CONTENT_BYTES'] = '2048';
+    const config = loadConfig();
+    expect(config.maxContentBytes).toBe(2048);
+  });
+
+  it('rejects an invalid MAX_CONTENT_BYTES', () => {
+    process.env['MAX_CONTENT_BYTES'] = 'not-a-number';
+    expect(() => loadConfig()).toThrow(/Invalid MAX_CONTENT_BYTES/);
+  });
+
+  it('refuses to start when BASE_URL is unset', () => {
+    delete process.env['BASE_URL'];
+    expect(() => loadConfig()).toThrow(/Missing required environment variable: BASE_URL/);
+  });
+
+  it('rejects a BASE_URL with no origin to bind a signature to', () => {
+    process.env['BASE_URL'] = 'not-a-url';
+    expect(() => loadConfig()).toThrow(/BASE_URL must be an absolute URL/);
+  });
+
+  it('derives authOrigin from BASE_URL', () => {
+    process.env['BASE_URL'] = 'https://stack.example.com/some/path';
+    const config = loadConfig();
+    expect(config.baseUrl).toBe('https://stack.example.com/some/path');
+    expect(config.authOrigin).toBe('https://stack.example.com');
+  });
+
+  it('defaults shutdownTimeoutMs to 10s', () => {
+    const config = loadConfig();
+    expect(config.shutdownTimeoutMs).toBe(10_000);
+  });
+
+  it('reads SHUTDOWN_TIMEOUT_MS when set', () => {
+    process.env['SHUTDOWN_TIMEOUT_MS'] = '5000';
+    const config = loadConfig();
+    expect(config.shutdownTimeoutMs).toBe(5000);
+  });
+
+  it('rejects an invalid SHUTDOWN_TIMEOUT_MS', () => {
+    process.env['SHUTDOWN_TIMEOUT_MS'] = 'not-a-number';
+    expect(() => loadConfig()).toThrow(/Invalid SHUTDOWN_TIMEOUT_MS/);
+  });
+});