@matthesketh/fleet 1.8.1 → 1.11.1

package/dist/core/secrets-v2-migrate.js

@@ -0,0 +1,395 @@
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { addAgentDependency } from '../templates/app-unit-edit.js';
+import { generateAgentUnit } from '../templates/agent-unit.js';
+import { migrateComposeToV2 } from '../templates/compose-edit.js';
+import { credentialPathFor, encryptCredential, removeCredential } from './secrets-v2-creds.js';
+import { generateKeypair, reencryptForRecipient } from './secrets-v2-keypair.js';
+import { listSnapshots, restoreSnapshot, snapshotApp } from './secrets-v2-snapshot.js';
+import { loadManifest, saveManifest, VAULT_DIR } from './secrets.js';
+/** vault dir resolution. mirrors secrets-v2-cleanup.ts and
+ *  secrets-v2-install.ts — env override takes precedence so the generated
+ *  systemd unit never carries an operator-specific hardcoded path. */
+function resolveVaultDir() {
+    return process.env.FLEET_VAULT_DIR ?? VAULT_DIR;
+}
+import { findApp, load } from './registry.js';
+import { execSafe } from './exec.js';
+import { SecretsError } from './errors.js';
+import { validateApp } from './secrets-validate.js';
+const AGENT_UNIT_PATH = '/etc/systemd/system/fleet-secrets-agent@.service';
+const STEP_NAMES = {
+    1: 'snapshot app state',
+    2: 'generate per-app age keypair',
+    3: 're-encrypt vault blob for new recipient',
+    4: 'install fleet-secrets-agent@ systemd unit template',
+    5: 'migrate compose file to v2 socket mode',
+    6: 'add agent dependency to app systemd unit',
+    7: 'update manifest: mode=socket, recipient=<pub>',
+    8: 'encrypt private key as systemd credential',
+    9: 'enable and verify fleet-secrets-agent@<app>.service',
+    10: 'restart app container (docker compose up -d --force-recreate)',
+    11: 'health check app via HTTP /health',
+};
+async function pollHealth(url, deadlineMs = 30_000) {
+    const deadline = Date.now() + deadlineMs;
+    while (Date.now() < deadline) {
+        if (execSafe('curl', ['-sf', '--max-time', '5', url]).ok)
+            return true;
+        await new Promise(r => setTimeout(r, 250));
+    }
+    return false;
+}
+async function waitForSocket(socketPath, timeoutMs = 5000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (existsSync(socketPath))
+            return true;
+        await new Promise(r => setTimeout(r, 100));
+    }
+    return false;
+}
+function doRollback(opts) {
+    try {
+        restoreSnapshot(opts.snapInput, opts.snap);
+    }
+    catch { /* best-effort */ }
+    const bakPath = join(VAULT_DIR, `${opts.app}.env.age.v1.bak`);
+    if (existsSync(bakPath)) {
+        try {
+            unlinkSync(bakPath);
+        }
+        catch { /* best-effort */ }
+    }
+    if (opts.credentialWritten) {
+        try {
+            removeCredential(opts.app);
+        }
+        catch { /* best-effort */ }
+    }
+    if (opts.agentEnabled) {
+        try {
+            execSafe('systemctl', ['disable', '--now', `fleet-secrets-agent@${opts.app}.service`]);
+        }
+        catch { /* best-effort */ }
+    }
+    try {
+        execSafe('systemctl', ['daemon-reload']);
+    }
+    catch { /* best-effort */ }
+    if (!opts.noRestartApp && opts.failedStep >= 10) {
+        try {
+            execSafe('docker', ['compose', 'up', '-d', '--force-recreate'], { cwd: opts.composePath });
+        }
+        catch { /* best-effort */ }
+    }
+}
+export async function migrateAppToV2(opts) {
+    const { app, noRestartApp = false, dryRun = false } = opts;
+    const registry = load();
+    const appEntry = findApp(registry, app);
+    if (!appEntry) {
+        throw new SecretsError(`app '${app}' not found in fleet registry`);
+    }
+    const manifest = loadManifest();
+    if (manifest.apps[app]?.mode === 'socket') {
+        return {
+            app,
+            snapshotDir: null,
+            steps: [{ step: 1, name: 'already migrated to v2', ok: true }],
+            rolledBack: false,
+        };
+    }
+    if (dryRun) {
+        return {
+            app,
+            snapshotDir: null,
+            steps: Object.entries(STEP_NAMES).map(([n, name]) => ({ step: Number(n), name, ok: true })),
+            rolledBack: false,
+        };
+    }
+    const snapInput = {
+        app,
+        backupRoot: join(VAULT_DIR, 'backups'),
+        vaultDir: VAULT_DIR,
+        encryptedFile: `${app}.env.age`,
+        composeDir: appEntry.composePath,
+        composeFile: appEntry.composeFile ?? 'docker-compose.yml',
+        appUnitFile: `/etc/systemd/system/${app}.service`,
+    };
+    const steps = [];
+    const push = (step, ok, detail) => steps.push({ step, name: STEP_NAMES[step] ?? `step ${step}`, ok, detail });
+    let snap = null;
+    let credentialWritten = false;
+    let agentEnabled = false;
+    const rb = (failedStep, err) => {
+        push(failedStep, false, err instanceof Error ? err.message : String(err));
+        if (snap) {
+            doRollback({
+                snapInput, snap, app, credentialWritten, agentEnabled,
+                noRestartApp, failedStep, composePath: appEntry.composePath,
+            });
+        }
+    };
+    // step 1
+    try {
+        snap = snapshotApp(snapInput);
+        push(1, true, snap.dir);
+    }
+    catch (err) {
+        push(1, false, err instanceof Error ? err.message : String(err));
+        return { app, snapshotDir: null, steps, rolledBack: false };
+    }
+    // step 2
+    let keypair;
+    try {
+        keypair = generateKeypair();
+        push(2, true);
+    }
+    catch (err) {
+        rb(2, err);
+        return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+    }
+    // step 3
+    try {
+        const oldCiphertext = readFileSync(join(VAULT_DIR, `${app}.env.age`), 'utf-8');
+        const newCiphertext = reencryptForRecipient({
+            ciphertext: oldCiphertext,
+            oldKeyPath: '/etc/fleet/age.key',
+            newRecipient: keypair.publicKey,
+        });
+        renameSync(join(VAULT_DIR, `${app}.env.age`), join(VAULT_DIR, `${app}.env.age.v1.bak`));
+        writeFileSync(join(VAULT_DIR, `${app}.env.age`), newCiphertext);
+        push(3, true);
+    }
+    catch (err) {
+        rb(3, err);
+        return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+    }
+    // step 4
+    try {
+        const unitContent = generateAgentUnit(resolveVaultDir());
+        const existing = existsSync(AGENT_UNIT_PATH) ? readFileSync(AGENT_UNIT_PATH, 'utf-8') : null;
+        if (existing !== unitContent) {
+            writeFileSync(AGENT_UNIT_PATH, unitContent, { mode: 0o644 });
+        }
+        push(4, true);
+    }
+    catch (err) {
+        rb(4, err);
+        return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+    }
+    // step 5
+    try {
+        const composePath = join(appEntry.composePath, appEntry.composeFile ?? 'docker-compose.yml');
+        writeFileSync(composePath, migrateComposeToV2(readFileSync(composePath, 'utf-8'), app, appEntry.serviceName));
+        push(5, true);
+    }
+    catch (err) {
+        rb(5, err);
+        return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+    }
+    // step 6
+    try {
+        const unitPath = `/etc/systemd/system/${app}.service`;
+        writeFileSync(unitPath, addAgentDependency(readFileSync(unitPath, 'utf-8'), app));
+        push(6, true);
+    }
+    catch (err) {
+        rb(6, err);
+        return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+    }
+    // step 7
+    try {
+        const mf = loadManifest();
+        mf.apps[app] = { ...mf.apps[app], mode: 'socket', recipient: keypair.publicKey };
+        saveManifest(mf);
+        push(7, true);
+    }
+    catch (err) {
+        rb(7, err);
+        return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+    }
+    // step 8
+    try {
+        encryptCredential({ name: `${app}-age-key`, plaintext: keypair.privateKey, outputPath: credentialPathFor(app) });
+        credentialWritten = true;
+        push(8, true);
+    }
+    catch (err) {
+        rb(8, err);
+        return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+    }
+    // step 9
+    try {
+        const reload = execSafe('systemctl', ['daemon-reload']);
+        if (!reload.ok)
+            throw new SecretsError(`systemctl daemon-reload failed: ${reload.stderr}`);
+        const enable = execSafe('systemctl', ['enable', '--now', `fleet-secrets-agent@${app}.service`]);
+        if (!enable.ok)
+            throw new SecretsError(`systemctl enable failed: ${enable.stderr}`);
+        agentEnabled = true;
+        const active = execSafe('systemctl', ['is-active', `fleet-secrets-agent@${app}.service`]);
+        if (active.stdout.trim() !== 'active') {
+            throw new SecretsError(`agent not active: ${active.stdout.trim()}`);
+        }
+        if (!await waitForSocket(`/run/fleet-secrets/${app}.sock`)) {
+            throw new SecretsError(`agent socket did not appear within 5s: /run/fleet-secrets/${app}.sock`);
+        }
+        push(9, true);
+    }
+    catch (err) {
+        rb(9, err);
+        return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+    }
+    // step 10
+    if (noRestartApp) {
+        push(10, true);
+    }
+    else {
+        try {
+            execSafe('docker', ['compose', 'up', '-d', '--force-recreate'], { cwd: appEntry.composePath });
+            push(10, true);
+        }
+        catch (err) {
+            rb(10, err);
+            return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+        }
+    }
+    // step 11
+    if (noRestartApp) {
+        push(11, true);
+    }
+    else {
+        try {
+            const port = appEntry.port;
+            const url = port ? `http://localhost:${port}/health` : 'http://localhost/health';
+            if (!await pollHealth(url))
+                throw new SecretsError(`health check timed out after 30s for ${url}`);
+            push(11, true);
+        }
+        catch (err) {
+            rb(11, err);
+            return { app, snapshotDir: snap.dir, steps, rolledBack: true };
+        }
+    }
+    return { app, snapshotDir: snap.dir, steps, rolledBack: false };
+}
+const REVERT_STEP_NAMES = {
+    1: 'disable fleet-secrets-agent@<app>.service (best-effort)',
+    2: 'remove systemd credential for app (best-effort)',
+    3: 'remove .v1.bak file if present (best-effort)',
+    4: 'restore snapshot (vault blob, manifest, compose, unit)',
+    5: 'systemctl daemon-reload',
+    6: 'restart app container (docker compose up -d --force-recreate)',
+    7: 'validate v1 unseal-based secrets',
+};
+export async function revertAppFromV2(opts) {
+    const { app, snapshotTimestamp } = opts;
+    const registry = load();
+    const appEntry = findApp(registry, app);
+    if (!appEntry) {
+        throw new SecretsError(`app '${app}' not found in fleet registry`);
+    }
+    const manifest = loadManifest();
+    if (manifest.apps[app]?.mode !== 'socket') {
+        throw new SecretsError(`app '${app}' is not in v2 (socket) mode — nothing to revert`);
+    }
+    const snapshots = listSnapshots(join(VAULT_DIR, 'backups'), app);
+    if (snapshots.length === 0) {
+        throw new SecretsError(`no snapshots found for app '${app}' — cannot revert`);
+    }
+    let snap;
+    if (snapshotTimestamp !== undefined) {
+        const found = snapshots.find(s => s.timestamp === snapshotTimestamp);
+        if (!found) {
+            throw new SecretsError(`no snapshot with timestamp '${snapshotTimestamp}' found for app '${app}'`);
+        }
+        snap = found;
+    }
+    else {
+        snap = snapshots[0];
+    }
+    const snapInput = {
+        app,
+        backupRoot: join(VAULT_DIR, 'backups'),
+        vaultDir: VAULT_DIR,
+        encryptedFile: `${app}.env.age`,
+        composeDir: appEntry.composePath,
+        composeFile: appEntry.composeFile ?? 'docker-compose.yml',
+        appUnitFile: `/etc/systemd/system/${app}.service`,
+    };
+    const steps = [];
+    const push = (step, ok, detail) => steps.push({ step, name: REVERT_STEP_NAMES[step] ?? `step ${step}`, ok, detail });
+    // step 1 — best-effort: disable agent unit
+    const disableResult = execSafe('systemctl', ['disable', '--now', `fleet-secrets-agent@${app}.service`]);
+    if (!disableResult.ok) {
+        push(1, false, `disable failed (best-effort): ${disableResult.stderr}`);
+    }
+    else {
+        push(1, true, 'agent unit disabled');
+    }
+    // step 2 — best-effort: remove credential
+    try {
+        removeCredential(app);
+        push(2, true, 'credential removed');
+    }
+    catch (err) {
+        push(2, false, `removeCredential failed (best-effort): ${err.message}`);
+    }
+    // step 3 — best-effort: remove v1 backup file
+    const bakPath = join(VAULT_DIR, `${app}.env.age.v1.bak`);
+    try {
+        if (existsSync(bakPath)) {
+            unlinkSync(bakPath);
+        }
+        push(3, true);
+    }
+    catch (err) {
+        push(3, false, `.v1.bak removal failed (best-effort): ${err.message}`);
+    }
+    // step 4 — restore snapshot (mandatory)
+    try {
+        restoreSnapshot(snapInput, snap);
+        push(4, true);
+    }
+    catch (err) {
+        push(4, false, err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+    // step 5 — daemon-reload (mandatory)
+    try {
+        const reload = execSafe('systemctl', ['daemon-reload']);
+        if (!reload.ok)
+            throw new SecretsError(`systemctl daemon-reload failed: ${reload.stderr}`);
+        push(5, true);
+    }
+    catch (err) {
+        push(5, false, err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+    // step 6 — restart app (mandatory)
+    try {
+        execSafe('docker', ['compose', 'up', '-d', '--force-recreate'], { cwd: appEntry.composePath });
+        push(6, true);
+    }
+    catch (err) {
+        push(6, false, err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+    // step 7 — validate v1 secrets (mandatory)
+    try {
+        const validation = validateApp(app);
+        if (!validation.ok) {
+            throw new SecretsError(`v1 secrets validation failed — missing keys: ${validation.missing.join(', ')}`);
+        }
+        push(7, true);
+    }
+    catch (err) {
+        push(7, false, err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+    const mandatoryStepNums = new Set([4, 5, 6, 7]);
+    const ok = steps.filter(s => mandatoryStepNums.has(s.step)).every(s => s.ok);
+    return { app, snapshotUsed: snap.timestamp, steps, ok };
+}

package/dist/core/secrets-v2-ops.d.ts

@@ -0,0 +1,36 @@
+export interface V2AppStatus {
+    name: string;
+    mode: 'unseal' | 'socket';
+    agentActive: boolean;
+    socketOk: boolean;
+    lastSealedAt: string;
+    recipient?: string;
+    keyCount: number;
+}
+export interface V2StatusReport {
+    apps: V2AppStatus[];
+    v1Count: number;
+    v2Count: number;
+}
+export interface V2DriftCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface V2DriftResult {
+    app: string;
+    ok: boolean;
+    checks: V2DriftCheck[];
+}
+/**
+ * Verify the deployed v2 state of an app matches what's recorded in the manifest.
+ * Each check returns ok/detail; the overall ok is true only if all checks pass.
+ *
+ * @param app The app name to check.
+ * @param socketPathOverride Test-only injection point. In production, the socket
+ *   path is derived from the app name (`/run/fleet-secrets/<app>.sock`). Tests
+ *   pass a temp-dir path to avoid mocking node:net. Do not set this in
+ *   production code.
+ */
+export declare function getV2Status(): V2StatusReport;
+export declare function detectV2Drift(app: string, socketPathOverride?: string): Promise<V2DriftResult>;

package/dist/core/secrets-v2-ops.js

@@ -0,0 +1,184 @@
+import { existsSync, statSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { credentialPathFor } from './secrets-v2-creds.js';
+import { execSafe } from './exec.js';
+import { loadManifest } from './secrets.js';
+const AGE_PUBKEY_RE = /^age1[a-z0-9]+$/;
+function checkRecipient(recipient) {
+    if (!recipient || !AGE_PUBKEY_RE.test(recipient)) {
+        return {
+            name: 'recipient_matches',
+            ok: false,
+            detail: `invalid age public key format: ${recipient ?? '(missing)'}`,
+        };
+    }
+    return {
+        name: 'recipient_matches',
+        ok: true,
+        detail: 'format only — full cryptographic check requires running agent',
+    };
+}
+function checkCredentialPresent(app) {
+    const credPath = credentialPathFor(app);
+    const present = existsSync(credPath);
+    return {
+        name: 'credential_present',
+        ok: present,
+        detail: present ? undefined : `not found: ${credPath}`,
+    };
+}
+function checkAgentActive(app) {
+    const unit = `fleet-secrets-agent@${app}.service`;
+    const result = execSafe('systemctl', ['is-active', unit]);
+    const active = result.stdout.trim() === 'active';
+    return {
+        name: 'agent_active',
+        ok: active,
+        detail: active ? undefined : `systemctl is-active: ${result.stdout.trim() || result.stderr.trim()}`,
+    };
+}
+function checkSocketPresent(socketPath) {
+    const present = existsSync(socketPath);
+    return {
+        name: 'socket_present',
+        ok: present,
+        detail: present ? undefined : `not found: ${socketPath}`,
+    };
+}
+function checkSocketPerms(socketPath) {
+    try {
+        const st = statSync(socketPath);
+        const perms = st.mode & 0o777;
+        const correct = perms === 0o660;
+        return {
+            name: 'socket_perms',
+            ok: correct,
+            detail: correct ? undefined : `expected 0o660, got 0o${perms.toString(8)}`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'socket_perms',
+            ok: false,
+            detail: `statSync failed: ${err.message}`,
+        };
+    }
+}
+function fetchFromSocket(socketPath, timeoutMs = 2000) {
+    return new Promise((resolve, reject) => {
+        const sock = createConnection(socketPath);
+        let response = '';
+        sock.setTimeout(timeoutMs, () => {
+            sock.destroy();
+            reject(new Error('socket fetch timed out'));
+        });
+        sock.on('error', (err) => reject(err));
+        sock.on('connect', () => {
+            sock.write('GET /health HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n');
+        });
+        sock.on('data', (chunk) => { response += chunk.toString(); });
+        sock.on('end', () => resolve(response));
+        sock.on('close', () => {
+            if (response)
+                resolve(response);
+        });
+    });
+}
+function parseJsonBody(raw) {
+    const sep = raw.indexOf('\r\n\r\n');
+    const body = sep === -1 ? raw : raw.slice(sep + 4);
+    return JSON.parse(body.trim());
+}
+async function checkSampleFetchKeys(app, socketPath, keyCount) {
+    try {
+        const raw = await fetchFromSocket(socketPath);
+        const data = parseJsonBody(raw);
+        if (data.app !== app) {
+            return {
+                name: 'sample_fetch_keys',
+                ok: false,
+                detail: `app mismatch: expected '${app}', got '${String(data.app)}'`,
+            };
+        }
+        const secrets = typeof data.secrets === 'number' ? data.secrets : -1;
+        if (keyCount > 0 && secrets <= 0) {
+            return {
+                name: 'sample_fetch_keys',
+                ok: false,
+                detail: `expected secrets > 0, got ${secrets}`,
+            };
+        }
+        return { name: 'sample_fetch_keys', ok: true };
+    }
+    catch (err) {
+        return {
+            name: 'sample_fetch_keys',
+            ok: false,
+            detail: err.message,
+        };
+    }
+}
+/**
+ * Verify the deployed v2 state of an app matches what's recorded in the manifest.
+ * Each check returns ok/detail; the overall ok is true only if all checks pass.
+ *
+ * @param app The app name to check.
+ * @param socketPathOverride Test-only injection point. In production, the socket
+ *   path is derived from the app name (`/run/fleet-secrets/<app>.sock`). Tests
+ *   pass a temp-dir path to avoid mocking node:net. Do not set this in
+ *   production code.
+ */
+export function getV2Status() {
+    const manifest = loadManifest();
+    const apps = [];
+    let v1Count = 0;
+    let v2Count = 0;
+    for (const [name, entry] of Object.entries(manifest.apps)) {
+        const mode = (entry.mode ?? 'unseal');
+        let agentActive = false;
+        let socketOk = false;
+        if (mode === 'socket') {
+            v2Count++;
+            const isActive = execSafe('systemctl', ['is-active', `fleet-secrets-agent@${name}.service`]);
+            agentActive = isActive.ok && isActive.stdout.trim() === 'active';
+            const socketPath = `/run/fleet-secrets/${name}.sock`;
+            if (existsSync(socketPath)) {
+                try {
+                    const perms = statSync(socketPath).mode & 0o777;
+                    socketOk = perms === 0o660;
+                }
+                catch { /* keep socketOk false */ }
+            }
+        }
+        else {
+            v1Count++;
+        }
+        apps.push({ name, mode, agentActive, socketOk, lastSealedAt: entry.lastSealedAt, recipient: entry.recipient, keyCount: entry.keyCount });
+    }
+    return { apps, v1Count, v2Count };
+}
+export async function detectV2Drift(app, socketPathOverride) {
+    const manifest = loadManifest();
+    const entry = manifest.apps[app];
+    if (!entry || entry.mode !== 'socket') {
+        return {
+            app,
+            ok: false,
+            checks: [{ name: 'mode', ok: false, detail: 'app not in v2 mode' }],
+        };
+    }
+    const socketPath = socketPathOverride ?? `/run/fleet-secrets/${app}.sock`;
+    const checks = [
+        checkRecipient(entry.recipient),
+        checkCredentialPresent(app),
+        checkAgentActive(app),
+        checkSocketPresent(socketPath),
+        checkSocketPerms(socketPath),
+        await checkSampleFetchKeys(app, socketPath, entry.keyCount),
+    ];
+    return {
+        app,
+        ok: checks.every(c => c.ok),
+        checks,
+    };
+}

package/dist/core/secrets-v2-protocol.d.ts

@@ -0,0 +1,19 @@
+export declare class ProtocolError extends Error {
+    constructor(message: string);
+}
+export interface ParsedRequest {
+    method: 'GET' | 'POST';
+    path: string;
+    body: string;
+}
+/**
+ * Parse a single HTTP/1.1 request from a Unix-socket read buffer.
+ *
+ * Callers must enforce an upper bound on `buf` size BEFORE invoking. This
+ * function will scan the full buffer for the header terminator (`\r\n\r\n`)
+ * and so does O(n) work on n bytes — feeding it arbitrarily large input is
+ * a DoS vector. The socket server should cap reads at a small multiple of
+ * MAX_BODY (e.g., 8 KiB) and call this only on bounded buffers.
+ */
+export declare function parseRequest(buf: Buffer): ParsedRequest;
+export declare function writeResponse(status: number, body: unknown): Buffer;

package/dist/core/secrets-v2-protocol.js

@@ -0,0 +1,60 @@
+export class ProtocolError extends Error {
+    constructor(message) { super(message); this.name = 'ProtocolError'; }
+}
+const MAX_BODY = 1024;
+const ALLOWED_METHODS = new Set(['GET', 'POST']);
+/**
+ * Parse a single HTTP/1.1 request from a Unix-socket read buffer.
+ *
+ * Callers must enforce an upper bound on `buf` size BEFORE invoking. This
+ * function will scan the full buffer for the header terminator (`\r\n\r\n`)
+ * and so does O(n) work on n bytes — feeding it arbitrarily large input is
+ * a DoS vector. The socket server should cap reads at a small multiple of
+ * MAX_BODY (e.g., 8 KiB) and call this only on bounded buffers.
+ */
+export function parseRequest(buf) {
+    const TERM = Buffer.from('\r\n\r\n');
+    const headerEnd = buf.indexOf(TERM);
+    if (headerEnd < 0)
+        throw new ProtocolError('incomplete request: no header terminator');
+    const bodyStart = headerEnd + TERM.length;
+    const bodyBytes = buf.length - bodyStart;
+    if (bodyBytes > MAX_BODY) {
+        throw new ProtocolError(`body too large: ${bodyBytes} > ${MAX_BODY}`);
+    }
+    const headerBlock = buf.slice(0, headerEnd).toString('utf-8');
+    const body = buf.slice(bodyStart).toString('utf-8');
+    const first = headerBlock.split('\r\n')[0] ?? '';
+    const m = first.match(/^([A-Z]+) (\S+) HTTP\/1\.1$/);
+    if (!m)
+        throw new ProtocolError(`malformed request line: ${first}`);
+    const method = m[1];
+    const path = m[2];
+    if (!ALLOWED_METHODS.has(method)) {
+        throw new ProtocolError(`method not allowed: ${method}`);
+    }
+    if (path.includes('?')) {
+        throw new ProtocolError('query string not supported');
+    }
+    return { method: method, path, body };
+}
+const STATUS = {
+    200: '200 OK',
+    400: '400 Bad Request',
+    404: '404 Not Found',
+    405: '405 Method Not Allowed',
+    413: '413 Payload Too Large',
+    429: '429 Too Many Requests',
+    500: '500 Internal Server Error',
+};
+export function writeResponse(status, body) {
+    const statusLine = STATUS[status] ?? `${status} Unknown`;
+    const json = JSON.stringify(body);
+    const buf = Buffer.from(json, 'utf-8');
+    const head = `HTTP/1.1 ${statusLine}\r\n` +
+        `Content-Type: application/json\r\n` +
+        `Content-Length: ${buf.length}\r\n` +
+        `Connection: close\r\n` +
+        `\r\n`;
+    return Buffer.concat([Buffer.from(head, 'utf-8'), buf]);
+}