@boxxy/server 0.0.1 → 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { serverConfigSchema } from './config/server-config-schema.ts';
+export type { ServerConfig } from './config/server-config-schema.ts';
+export { noCallerProof } from './no-caller-proof.ts';
+export { loadServerRules } from './rules/load-server-rules.ts';
+export type { RulesCheckout } from './rules/load-server-rules.ts';
+export { readRulesCheckout } from './rules/read-rules-checkout.ts';
+export type { CheckoutAnswer } from './rules/read-rules-checkout.ts';
+export { serveApi } from './serve-api.ts';
+export type { ApiListeners } from './serve-api.ts';
+export { startServer } from './start-server.ts';
+export type { RunningServer, StartAnswer, StartServerInput } from './start-server.ts';
+export type { ServerDeps, ServerLog } from './types.ts';

package/dist/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/no-caller-proof.d.ts

@@ -0,0 +1,2 @@
+import type { CallerProof } from '@boxxy/model';
+export declare const noCallerProof: CallerProof;

package/dist/outbox/create-off-outbox.d.ts

@@ -0,0 +1,3 @@
+import type { ClaimStore, Clock } from '@boxxy/model';
+import type { OutboxControl } from '../types.ts';
+export declare function createOffOutbox(store: ClaimStore, clock: Clock): OutboxControl;

package/dist/outbox/start-outbox-sender.d.ts

@@ -0,0 +1,10 @@
+import type { SenderDeps } from '@boxxy/dispatch';
+import type { OutboxControl, ServerLog } from '../types.ts';
+export interface OutboxSenderInput extends SenderDeps {
+    readonly idleMs: number;
+    readonly log: ServerLog;
+}
+export interface OutboxSender extends OutboxControl {
+    readonly stop: () => Promise<void>;
+}
+export declare function startOutboxSender(input: OutboxSenderInput): OutboxSender;

package/dist/read-limited-request.d.ts

@@ -0,0 +1 @@
+export declare function readLimitedRequest(request: Request, maxBytes: number): Promise<Request | null>;

package/dist/rules/create-rules-holder.d.ts

@@ -0,0 +1,20 @@
+import type { LoadRejection, LoadResult } from '@boxxy/model';
+import type { RulesState, ServerLog } from '../types.ts';
+interface RulesHolder {
+    readonly state: () => RulesState;
+    readonly loadProposed: (text: string) => LoadResult;
+    readonly texts: () => ReadonlyMap<string, string>;
+    readonly reload: () => Promise<void>;
+}
+export type RulesHolderAnswer = {
+    readonly kind: 'loaded';
+    readonly holder: RulesHolder;
+} | {
+    readonly kind: 'rejected';
+    readonly reason: string;
+} | {
+    readonly kind: 'refused';
+    readonly rejections: readonly LoadRejection[];
+};
+export declare function createRulesHolder(folder: string, log: ServerLog): Promise<RulesHolderAnswer>;
+export {};

package/dist/rules/load-server-rules.d.ts

@@ -0,0 +1,7 @@
+import type { LoadResult } from '@boxxy/model';
+export interface RulesCheckout {
+    readonly commit: string;
+    readonly files: ReadonlyMap<string, Uint8Array>;
+}
+export declare function loadServerRules(checkout: RulesCheckout): LoadResult;
+export declare function makeProposedRulesLoader(checkout: RulesCheckout): (text: string) => LoadResult;

package/dist/rules/read-rules-checkout.d.ts

@@ -0,0 +1,9 @@
+import type { RulesCheckout } from './load-server-rules.ts';
+export type CheckoutAnswer = {
+    readonly kind: 'read';
+    readonly checkout: RulesCheckout;
+} | {
+    readonly kind: 'rejected';
+    readonly reason: string;
+};
+export declare function readRulesCheckout(folder: string): Promise<CheckoutAnswer>;

package/dist/serve-api.d.ts

@@ -0,0 +1,50 @@
+import { Elysia } from 'elysia';
+import type { ServerDeps } from './types.ts';
+export declare const maxRequestBytes: number;
+export type ApiListeners = ReturnType<typeof serveApi>;
+export declare function serveApi(deps: ServerDeps): {
+    owner: import("elysia/types").AddRoute<"", "local", import("elysia").DefaultSingleton, {
+        typebox: {};
+        error: [];
+    }, import("elysia").DefaultMetadata, {}, import("elysia").DefaultEphemeral, import("elysia").DefaultEphemeral, "get", "/healthz", import("elysia/types").IntersectIfObjectSchema<import("elysia").UnwrapRoute<import("elysia").InputSchema<never> & {
+        beforeHandle?: unknown;
+        afterHandle?: unknown;
+        error?: unknown;
+    }, {}, "/healthz">, import("elysia/types").MergeScopedSchemas<{}, {}, {}>>, {}, (route: {
+        server: import("elysia").Server | null;
+        redirect: import("elysia").redirect;
+        set: {
+            headers: import("elysia").HTTPHeaders;
+            status?: number | keyof import("elysia").StatusMap;
+            cookie?: Record<string, import("elysia").BaseCookie>;
+            redirect?: never;
+        };
+        status: <const Code extends number | keyof import("elysia").StatusMap, const T = import("elysia").StatusResponse<Code>>(code: Code, response?: T) => import("elysia").ElysiaStatus<Code, T, import("elysia").NumericStatus<Code>>;
+        problem: typeof import("elysia").problem;
+        defer: (fn: import("elysia/types").AfterResponseHandler<NoInfer<import("elysia/types").IntersectIfObjectSchema<import("elysia").UnwrapRoute<import("elysia").InputSchema<never> & {
+            beforeHandle?: unknown;
+            afterHandle?: unknown;
+            error?: unknown;
+        }, {}, "/healthz">, import("elysia/types").MergeScopedSchemas<{}, {}, {}>>>, NoInfer<import("elysia").DefaultSingleton & {
+            derive: {};
+        }>>) => import("elysia/types").MaybePromise<void>;
+        readonly path: string;
+        route?: string;
+        rid?: string;
+        request: Request;
+        store: {};
+        body: unknown;
+        query: Record<string, string | undefined>;
+        params: {};
+        headers: Record<string, string | undefined>;
+        cookie: Record<string, import("elysia").Cookie<unknown>>;
+    }) => Promise<Response>, import("elysia").InputSchema<never> & {
+        beforeHandle?: unknown;
+        afterHandle?: unknown;
+        error?: unknown;
+    }>;
+    worker: Elysia<"", "local", import("elysia").DefaultSingleton, {
+        typebox: {};
+        error: [];
+    }, import("elysia").DefaultMetadata, {}, import("elysia").DefaultEphemeral, import("elysia").DefaultEphemeral>;
+};

package/dist/start-server.d.ts

@@ -0,0 +1,18 @@
+import type { ServerLog } from './types.ts';
+export interface StartServerInput {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly log: ServerLog;
+}
+export interface RunningServer {
+    readonly ownerPort: number;
+    readonly workerPort: number;
+    readonly stop: () => Promise<void>;
+}
+export type StartAnswer = {
+    readonly kind: 'started';
+    readonly server: RunningServer;
+} | {
+    readonly kind: 'refused';
+    readonly message: string;
+};
+export declare function startServer(input: StartServerInput): Promise<StartAnswer>;

package/dist/test-utils/build-mcp-request.d.ts

@@ -0,0 +1,8 @@
+interface MCPRequestInput {
+    readonly path: '/mcp' | '/mcp/session';
+    readonly method: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly token?: string;
+}
+export declare function buildMCPRequest(request: MCPRequestInput): Request;
+export {};

package/dist/test-utils/build-rpc-request.d.ts

@@ -0,0 +1,7 @@
+interface RPCRequestInput {
+    readonly procedure: string;
+    readonly input: unknown;
+    readonly token?: string;
+}
+export declare function buildRPCRequest(request: RPCRequestInput): Request;
+export {};

package/dist/test-utils/build-session-input.d.ts

@@ -0,0 +1 @@
+export declare function buildSessionInput(procedure: string, attempt: string): unknown;

package/dist/test-utils/create-fake-caller-proof.d.ts

@@ -0,0 +1,5 @@
+import type { CallerIdentity, CallerProof } from '@boxxy/model';
+export interface FakeCallerProof extends CallerProof {
+    setCaller: (caller: CallerIdentity | null) => void;
+}
+export declare function createFakeCallerProof(): FakeCallerProof;

package/dist/test-utils/create-test-server.d.ts

@@ -0,0 +1,30 @@
+import type { FakeForge } from '@boxxy/dispatch/test-utils/create-fake-forge';
+import type { TestDispatch } from '@boxxy/dispatch/test-utils/create-test-dispatch';
+import type { AttemptRow, CallerProof, Clock, PhaseName } from '@boxxy/model';
+import type { FakeNotifier } from '@boxxy/model/test-utils/create-fake-notifier';
+import type { FakePepysReader } from '@boxxy/model/test-utils/create-fake-pepys-reader';
+import type { TickReport } from '../tick/run-tick.ts';
+import type { ServerDeps } from '../types.ts';
+import type { FakeCallerProof } from './create-fake-caller-proof.ts';
+export interface TestServerOptions {
+    readonly hasPepys?: boolean;
+    readonly makeCallerProof?: (clock: Clock) => Promise<CallerProof>;
+}
+export interface TestServer {
+    readonly dispatch: TestDispatch;
+    readonly callerProof: FakeCallerProof;
+    readonly pepys: FakePepysReader;
+    readonly notifier: FakeNotifier;
+    readonly forge: FakeForge;
+    readonly workerToken: string;
+    readonly logged: readonly {
+        readonly message: string;
+        readonly fields: unknown;
+    }[];
+    readonly deps: ServerDeps;
+    readonly owner: (request: Request) => Promise<Response>;
+    readonly worker: (request: Request) => Promise<Response>;
+    readonly tick: () => Promise<TickReport>;
+    readonly seedStartedAttempt: (phase: PhaseName) => Promise<AttemptRow>;
+}
+export declare function createTestServer(options?: TestServerOptions): Promise<TestServer>;

package/dist/test-utils/list-owner-procedures.d.ts

@@ -0,0 +1,5 @@
+import type { ProcedureName } from '@boxxy/contract';
+export declare function listOwnerProcedures(): [ProcedureName][];
+export declare function listOwnerTools(): [string][];
+export declare function listSessionProcedures(): [ProcedureName][];
+export declare function listSessionTools(): [string][];

package/dist/test-utils/read-mcp-answer.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+declare const answerSchema: z.ZodObject<{
+    result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type MCPAnswer = z.infer<typeof answerSchema>;
+export declare function readMCPAnswer(response: Response): Promise<MCPAnswer>;
+export {};

package/dist/test-utils/wait-for.d.ts

@@ -0,0 +1 @@
+export declare function waitFor(check: () => boolean | Promise<boolean>, timeoutMs?: number): Promise<void>;

package/dist/tick/run-tick.d.ts

@@ -0,0 +1,24 @@
+import type { NoticeReport, SpawnSettings } from '@boxxy/dispatch';
+import type { AttemptId, CapacityBackoff, ClaimStore, Instant, LoadedRules, NewId, Notifier, RunnerId, SessionReading, WorkerKind } from '@boxxy/model';
+import type { ServerLog } from '../types.ts';
+export interface TickDeps {
+    readonly store: ClaimStore;
+    readonly runner: RunnerId;
+    readonly worker: WorkerKind;
+    readonly rules: LoadedRules;
+    readonly backoff: CapacityBackoff;
+    readonly spawn: SpawnSettings;
+    readonly notifier: Notifier;
+    readonly now: Instant;
+    readonly newId: NewId;
+    readonly readings: Map<AttemptId, SessionReading>;
+    readonly log: ServerLog;
+}
+export interface TickReport {
+    readonly claimed: number;
+    readonly read: number;
+    readonly strays: number;
+    readonly forgotten: number;
+    readonly notices: NoticeReport | null;
+}
+export declare function runTick(deps: TickDeps): Promise<TickReport>;

package/dist/tick/start-tick-loop.d.ts

@@ -0,0 +1,12 @@
+import type { ServerLog } from '../types.ts';
+export interface TickLoop {
+    readonly stop: () => Promise<void>;
+}
+interface TickLoopInput {
+    readonly runOnce: () => Promise<void>;
+    readonly intervalMs: number;
+    readonly failureMessage: string;
+    readonly log: ServerLog;
+}
+export declare function startTickLoop(input: TickLoopInput): TickLoop;
+export {};

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+import type { AtcSessionId, AttemptId, CallerIdentity, CallerProof, ClaimStore, Clock, Forge, LoadRejection, LoadResult, LoadedRules, NewId, OutboxStatus, PepysReader, RunnerId, SessionReading } from '@boxxy/model';
+export interface RulesState {
+    readonly rules: LoadedRules;
+    readonly lastRejected: {
+        readonly commit: string;
+        readonly rejections: readonly LoadRejection[];
+    } | null;
+}
+export interface OutboxControl {
+    readonly status: () => Promise<OutboxStatus>;
+    readonly nudge: () => void;
+}
+export interface ServerLog {
+    readonly warn: (message: string, fields: Readonly<Record<string, unknown>>) => void;
+}
+export interface ServerDeps {
+    readonly store: ClaimStore;
+    readonly runner: RunnerId;
+    readonly rulesState: () => RulesState;
+    readonly loadProposedRules: (text: string) => LoadResult;
+    readonly clock: Clock;
+    readonly newId: NewId;
+    readonly callerProof: CallerProof;
+    readonly workerTokenDigest: Uint8Array;
+    readonly pepys: PepysReader | null;
+    readonly forge: Forge | null;
+    readonly outbox: OutboxControl;
+    readonly readings: ReadonlyMap<AttemptId, SessionReading>;
+    readonly log: ServerLog;
+}
+export type Listener = 'owner' | 'worker';
+export type RequestScope = 'owner' | 'worker';
+export interface RequestContext {
+    readonly deps: ServerDeps;
+    readonly scope: RequestScope;
+    readonly request: Request;
+}
+export interface ProvenCall {
+    readonly session: AtcSessionId;
+    readonly caller: CallerIdentity;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boxxy/server",
-  "version": "0.0.1",
-  "description": "Placeholder that reserves the name; the first real version comes from the boxxy release",
+  "version": "0.1.3",
+  "description": "The boxxy server: the API behind its three doors, and the runner loop",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/apps/server#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
   "license": "MIT",
@@ -11,10 +11,54 @@
     "directory": "apps/server"
   },
   "files": [
-    "README.md",
-    "LICENSE"
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
   ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "start": "bun src/main.ts",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@boxxy/caller-proof-imp": "0.1.3",
+    "@boxxy/closeout": "0.1.3",
+    "@boxxy/content-hash": "0.1.3",
+    "@boxxy/contract": "0.1.3",
+    "@boxxy/dispatch": "0.1.3",
+    "@boxxy/forge-github": "0.1.3",
+    "@boxxy/model": "0.1.3",
+    "@boxxy/notifier-atc": "0.1.3",
+    "@boxxy/pepys": "0.1.3",
+    "@boxxy/planning": "0.1.3",
+    "@boxxy/rules": "0.1.3",
+    "@boxxy/store-sqlite": "0.1.3",
+    "@boxxy/worker-atc": "0.1.3",
+    "@modelcontextprotocol/server": "2.4.0",
+    "@orpc/client": "2.0.0-beta.50",
+    "@orpc/mcp": "2.0.0-beta.50",
+    "@orpc/server": "2.0.0-beta.50",
+    "elysia": "2.0.0-rc.0",
+    "exact-mirror": "1.2.6",
+    "openapi-types": "12.1.3",
+    "tiny-invariant": "1.3.3",
+    "ts-pattern": "5.9.2",
+    "typebox": "1.4.3",
+    "zod": "4.6.7"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
   }
 }

package/src/auth/authorize-call.ts

@@ -0,0 +1,50 @@
+import type { ProcedureName } from '@boxxy/contract';
+import { access } from '@boxxy/contract';
+import invariant from 'tiny-invariant';
+import type { ProvenCall, RequestContext } from '../types.ts';
+
+export type CallAuthorization =
+  | { readonly kind: 'owner' }
+
+  // a session or hook call with a proven caller; `call` is null when no session holds the caller
+  | { readonly kind: 'session'; readonly call: ProvenCall | null }
+  | { readonly kind: 'refused'; readonly code: 'UNAUTHORIZED' | 'FORBIDDEN' };
+
+// The one check of who may call a procedure, from the access table. Every door runs it before any
+// handler, and no handler repeats it.
+export async function authorizeCall(
+  ctx: RequestContext,
+  path: readonly string[],
+): Promise<CallAuthorization> {
+  const name = path.join('.');
+
+  invariant(isProcedureName(name), `the router serves only contract procedures: ${name}`);
+
+  if (access[name].caller === 'owner') {
+    return ctx.scope === 'owner' ? { kind: 'owner' } : { kind: 'refused', code: 'FORBIDDEN' };
+  }
+
+  if (ctx.scope !== 'worker') {
+    return { kind: 'refused', code: 'UNAUTHORIZED' };
+  }
+
+  const caller = await ctx.deps.callerProof.prove(ctx.request);
+
+  if (caller === null) {
+    return { kind: 'refused', code: 'UNAUTHORIZED' };
+  }
+
+  const session = await ctx.deps.store.read((tx) => tx.findSessionByCaller(caller));
+
+  if (session === 'ambiguous') {
+    ctx.deps.log.warn('two sessions hold one caller', { procedure: name, ...caller });
+
+    return { kind: 'refused', code: 'FORBIDDEN' };
+  }
+
+  return { kind: 'session', call: session === null ? null : { session, caller } };
+}
+
+function isProcedureName(name: string): name is ProcedureName {
+  return Object.hasOwn(access, name);
+}

package/src/auth/is-browser-request.ts

@@ -0,0 +1,8 @@
+// A browser marks each request a page makes: `Origin` on every POST, `Sec-Fetch-Site` on every
+// request. No caller of the server is a page, and a page on a site that resolves to a listener can
+// send a write with no CORS preflight. `Sec-Fetch-Site: none` is an address typed by a person.
+export function isBrowserRequest(headers: Headers): boolean {
+  const site = headers.get('sec-fetch-site');
+
+  return headers.has('origin') || (site !== null && site !== 'none');
+}

package/src/auth/pick-request-scope.ts

@@ -0,0 +1,37 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import invariant from 'tiny-invariant';
+import type { Listener, RequestScope } from '../types.ts';
+
+interface ScopeInput {
+  readonly listener: Listener;
+
+  // the `Authorization` header, or null
+  readonly authorization: string | null;
+  readonly workerTokenDigest: Uint8Array;
+}
+
+const bearerPattern = /^Bearer (?<token>\S+)$/u;
+
+// Which scope a request runs in, from its listener and its bearer token alone. `null`: refuse it
+// with 401. On the worker listener no token is never the owner: a call that went around the
+// broker carries none.
+export function pickRequestScope(input: ScopeInput): RequestScope | null {
+  if (input.authorization === null) {
+    return input.listener === 'owner' ? 'owner' : null;
+  }
+
+  const token = bearerPattern.exec(input.authorization)?.groups?.['token'];
+
+  if (token === undefined) {
+    return null;
+  }
+
+  // equal-length digests, so the comparison takes the same time for every wrong token
+  return timingSafeEqual(buildTokenDigest(token), input.workerTokenDigest) ? 'worker' : null;
+}
+
+export function buildTokenDigest(token: string): Uint8Array {
+  invariant(token.length > 0, 'the worker token is never empty');
+
+  return createHash('sha256').update(token).digest();
+}

package/src/config/pick-server-secrets.ts

@@ -0,0 +1,48 @@
+import type { ServerConfig } from './server-config-schema.ts';
+
+interface ServerSecrets {
+  readonly workerToken: string;
+  readonly atcToken: string;
+
+  // null: the configuration has no pepys section
+  readonly pepysSigningSecret: string | null;
+
+  // null: unset or empty, for a broker that adds the GitHub credential on the way out
+  readonly githubToken: string | null;
+}
+
+export type SecretsAnswer =
+  | { readonly kind: 'found'; readonly secrets: ServerSecrets }
+
+  // the name of each variable that is unset or empty, never a value
+  | { readonly kind: 'missing'; readonly names: readonly string[] };
+
+// The secrets come from the environment only. An empty variable counts as missing.
+export function pickServerSecrets(
+  config: ServerConfig,
+  env: Readonly<Record<string, string | undefined>>,
+): SecretsAnswer {
+  const needed = [
+    'BOXXY_WORKER_TOKEN',
+    'BOXXY_ATC_TOKEN',
+    ...(config.pepys === undefined ? [] : ['BOXXY_PEPYS_SIGNING_SECRET']),
+  ];
+
+  const names = needed.filter((name) => (env[name] ?? '') === '');
+
+  if (names.length > 0) {
+    return { kind: 'missing', names };
+  }
+
+  return {
+    kind: 'found',
+    secrets: {
+      workerToken: env['BOXXY_WORKER_TOKEN'] ?? '',
+      atcToken: env['BOXXY_ATC_TOKEN'] ?? '',
+      pepysSigningSecret:
+        config.pepys === undefined ? null : (env['BOXXY_PEPYS_SIGNING_SECRET'] ?? ''),
+      githubToken:
+        (env['BOXXY_GITHUB_TOKEN'] ?? '') === '' ? null : (env['BOXXY_GITHUB_TOKEN'] ?? null),
+    },
+  };
+}

package/src/config/read-caller-proof.ts

@@ -0,0 +1,36 @@
+import { impIdentityCallerProof } from '@boxxy/caller-proof-imp';
+import type { CallerProof, Clock } from '@boxxy/model';
+import { noCallerProof } from '../no-caller-proof.ts';
+import { readTrustedIssuers } from './read-trusted-issuers.ts';
+import type { ServerConfig } from './server-config-schema.ts';
+
+export type ProofAnswer =
+  | { readonly kind: 'read'; readonly callerProof: CallerProof }
+  | { readonly kind: 'refused'; readonly message: string };
+
+// The proof of who sent a session or hook call, from the trust documents in the configured
+// folders. With no `trustedIssuers` section, the proof proves nobody, so every such call is
+// refused. The adapter throws on a malformed trust document, so such a server never starts.
+export async function readCallerProof(
+  trustedIssuers: ServerConfig['trustedIssuers'],
+  clock: Clock,
+): Promise<ProofAnswer> {
+  if (trustedIssuers === undefined) {
+    return { kind: 'read', callerProof: noCallerProof };
+  }
+
+  const read = await readTrustedIssuers(trustedIssuers.folders);
+
+  if (read.kind === 'invalid') {
+    return { kind: 'refused', message: read.message };
+  }
+
+  return {
+    kind: 'read',
+    callerProof: impIdentityCallerProof({
+      issuers: read.issuers,
+      audience: trustedIssuers.audience,
+      clock,
+    }),
+  };
+}

package/src/config/read-server-config.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { ServerConfig } from './server-config-schema.ts';
+import { serverConfigSchema } from './server-config-schema.ts';
+
+export type ConfigAnswer =
+  | { readonly kind: 'read'; readonly config: ServerConfig }
+  | { readonly kind: 'invalid'; readonly message: string };
+
+// The configuration file, as JSON. A file that is missing, is no JSON, or fails the schema is
+// `invalid`, with a message that names the file and the field.
+export async function readServerConfig(path: string): Promise<ConfigAnswer> {
+  const file = Bun.file(path);
+
+  if (!(await file.exists())) {
+    return { kind: 'invalid', message: `no configuration file at ${path}` };
+  }
+
+  const text = await file.text();
+
+  const json = parseJSON(text);
+
+  if (json === undefined) {
+    return { kind: 'invalid', message: `the configuration file at ${path} is not JSON` };
+  }
+
+  const parsed = serverConfigSchema.safeParse(json);
+
+  return parsed.success
+    ? { kind: 'read', config: parsed.data }
+    : { kind: 'invalid', message: `${path}: ${z.prettifyError(parsed.error)}` };
+}
+
+function parseJSON(text: string): unknown {
+  try {
+    const value: unknown = JSON.parse(text);
+
+    return value;
+  } catch {
+    return undefined;
+  }
+}