@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/auth.js

@@ -0,0 +1,247 @@
+import { createRemoteJWKSet, jwtVerify, } from "jose";
+/**
+ * Paths that must never require auth (proxy / monitoring health probes).
+ *
+ * **Every member must be a REGISTERED route** (see `routes/meta.ts`). Exempting a
+ * path that no route serves does not make it 404 — it makes the SPA not-found
+ * handler (`app.ts`) reachable *without a credential*, so the probe receives the
+ * HTML app shell with a 200 and reads a locked-down or half-broken instance as
+ * healthy. In the authenticated modes that inverts the truthful answer: an
+ * unregistered path 401s honestly, but an exempted unregistered one reports 200.
+ *
+ * This set previously carried five conventional aliases (`/healthz`, `/-/health`,
+ * `/health`, `/readyz`, `/livez`) that were never registered — issue #569.
+ * `test/integration/auth-health-paths.test.ts` now asserts every member resolves
+ * to a real route returning JSON, so the set cannot drift from the router again.
+ */
+export const HEALTH_PATHS = new Set([
+    "/api/health", // paddock's own health route (routes/meta.ts)
+]);
+/**
+ * Strip the query string and trailing slash so exemption matching is robust.
+ *
+ * Note the trailing-slash half only affects the AUTH decision, not routing: Fastify
+ * is not configured with `ignoreTrailingSlash`, so `/api/health/` is exempt here yet
+ * still matches no route and answers a JSON 404. That is deliberate — an honest loud
+ * failure for a probe on the slashed form, never a false 200 (see #569).
+ */
+function normalizePath(url) {
+    const q = url.indexOf("?");
+    let p = q === -1 ? url : url.slice(0, q);
+    if (p.length > 1 && p.endsWith("/"))
+        p = p.slice(0, -1);
+    return p;
+}
+// Immutable front-end static assets (issue #223). These are the compiled web
+// bundle — content-hashed JS/CSS/fonts under /assets, the /icons and /fonts sets,
+// the service worker, and the PWA manifest. They carry no secrets and no per-user
+// data. Serving them WITHOUT the JWT gate means a transient auth lapse (e.g. an
+// Authentik session-refresh window, or the outpost briefly not injecting the
+// header) no longer turns a chunk/asset fetch into a 401 → "Load failed" /
+// "module script failed". The app shell (index.html / client routes) and every
+// data route (/api, /ws) stay authenticated, so this exposes only the compiled,
+// non-sensitive front-end — nothing an authenticated user's browser doesn't
+// already download.
+const STATIC_ASSET_PREFIXES = ["/assets/", "/icons/", "/fonts/"];
+const STATIC_ASSET_FILES = new Set(["/sw.js", "/manifest.webmanifest", "/favicon.ico"]);
+function isStaticAsset(pathname) {
+    if (STATIC_ASSET_FILES.has(pathname))
+        return true;
+    return STATIC_ASSET_PREFIXES.some((prefix) => pathname.startsWith(prefix));
+}
+/**
+ * The Management API surface (issue #312). Exempt from THIS hook because it
+ * authenticates itself — see management-auth.ts — and because the browser modes
+ * are actively wrong for it:
+ *
+ *  - `jwt` mode reads `Authorization`, which COLLIDES head-on with an MCP
+ *    client's `Authorization: Bearer <management token>`;
+ *  - an SSO proxy in front answers with an HTML login redirect, which no MCP
+ *    client can follow and which breaks OAuth discovery (M2).
+ *
+ * This exemption is safe ONLY because `/mcp` runs its own authenticator and
+ * fails closed (404 when unconfigured, 401 otherwise) — it is never open, not
+ * even at `auth.mode: none`. Prefix-matched so M2's sub-paths inherit it.
+ */
+const MANAGEMENT_API_PREFIX = "/mcp";
+/**
+ * RFC 9728 protected-resource metadata (M2 discovery). Exempt for the same
+ * reason: an MCP client fetches this BEFORE it holds any credential, so gating
+ * it would make discovery impossible. The document is public by design — it
+ * names the authorization server and supported scopes, never a secret.
+ *
+ * Matched as a PREFIX because the path-inserted form is what clients actually
+ * request: for a resource at `/mcp` the metadata lives at
+ * `/.well-known/oauth-protected-resource/mcp`, not at the bare root.
+ */
+const PROTECTED_RESOURCE_METADATA_PREFIX = "/.well-known/oauth-protected-resource";
+function isManagementApiPath(pathname) {
+    return (pathname === MANAGEMENT_API_PREFIX ||
+        pathname.startsWith(`${MANAGEMENT_API_PREFIX}/`) ||
+        pathname === PROTECTED_RESOURCE_METADATA_PREFIX ||
+        pathname.startsWith(`${PROTECTED_RESOURCE_METADATA_PREFIX}/`));
+}
+function isExempt(url) {
+    const p = normalizePath(url);
+    return HEALTH_PATHS.has(p) || isStaticAsset(p) || isManagementApiPath(p);
+}
+const ANONYMOUS = Object.freeze({ username: "anonymous", anonymous: true });
+/** First non-empty value for a header (Fastify gives string | string[] | undefined). */
+function header(req, name) {
+    const v = req.headers[name.toLowerCase()];
+    const raw = Array.isArray(v) ? v[0] : v;
+    return raw && raw.trim().length > 0 ? raw.trim() : undefined;
+}
+/** Split a comma/space-delimited group header into a clean string[]. */
+function splitGroups(value) {
+    if (!value)
+        return undefined;
+    const parts = value
+        .split(/[,\s]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return parts.length ? parts : undefined;
+}
+/** Resolve a username from JWT claims using the configured/fallback claim chain. */
+function usernameFromClaims(payload, cfg) {
+    const pick = (key) => {
+        const v = payload[key];
+        return typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+    };
+    if (cfg.usernameClaim)
+        return pick(cfg.usernameClaim);
+    return pick("preferred_username") ?? pick("email") ?? pick("sub");
+}
+/** Extract groups from a JWT claim — accepts string[] or a delimited string. */
+function groupsFromClaims(payload, cfg) {
+    const v = payload[cfg.groupsClaim];
+    if (Array.isArray(v)) {
+        const arr = v.filter((g) => typeof g === "string" && g.trim().length > 0);
+        return arr.length ? arr.map((s) => s.trim()) : undefined;
+    }
+    if (typeof v === "string")
+        return splitGroups(v);
+    return undefined;
+}
+/** Read the token from the configured header, stripping `Bearer ` for Authorization. */
+function tokenFromRequest(req, cfg) {
+    const raw = header(req, cfg.jwtHeader);
+    if (!raw)
+        return undefined;
+    if (cfg.jwtHeader.toLowerCase() === "authorization") {
+        const m = /^Bearer\s+(.+)$/i.exec(raw);
+        return m ? m[1].trim() : raw;
+    }
+    return raw;
+}
+/**
+ * Register the auth layer on `app`. Adds a `user` request decorator and an
+ * `onRequest` hook that populates `req.user` (or replies 401). The decorator +
+ * hook are attached to the root app instance directly, so they guard every
+ * REST + WS request app-wide.
+ *
+ * In `jwt` mode the remote JWKS is created once and reused —
+ * `createRemoteJWKSet` fetches+caches keys and handles rotation, so we hold only
+ * the URL, never key material.
+ *
+ * Throws at registration time on a fatal misconfiguration (jwt mode without a
+ * JWKS URL) so the operator gets a clear startup failure instead of a server
+ * that rejects every request — failing closed but loudly.
+ */
+export function registerAuth(app, auth) {
+    const cfg = auth;
+    if (cfg.mode === "none") {
+        app.decorateRequest("user", null);
+        // This branch refuses nothing, so the management-API exemption changes no
+        // OUTCOME here — `/mcp` is reachable either way, and its own authenticator
+        // is what gates it (management-auth.ts). It is called out rather than
+        // applied because the rule that matters is "the browser hook never decides
+        // anything about /mcp", and in this mode the hook decides nothing at all.
+        app.addHook("onRequest", async (req) => {
+            req.user = ANONYMOUS;
+        });
+        app.log.info("auth: mode=none (open access — every request is anonymous)");
+        return;
+    }
+    // Decorate so the property exists on every request object up front (Fastify
+    // perf best-practice); the hook assigns the real value per request.
+    app.decorateRequest("user", null);
+    if (cfg.mode === "trusted-header") {
+        app.log.info({ userHeader: cfg.userHeader }, "auth: mode=trusted-header (identity trusted from proxy header)");
+        app.addHook("onRequest", async (req, reply) => {
+            if (isExempt(req.url)) {
+                req.user = ANONYMOUS;
+                return;
+            }
+            const username = header(req, cfg.userHeader);
+            if (!username) {
+                req.log.warn({ url: req.url, header: cfg.userHeader }, "auth: missing user header");
+                return reply.code(401).send({ error: "unauthorized", code: "auth_required" });
+            }
+            const user = { username };
+            if (cfg.emailHeader) {
+                const email = header(req, cfg.emailHeader);
+                if (email)
+                    user.email = email;
+            }
+            if (cfg.groupsHeader) {
+                const groups = splitGroups(header(req, cfg.groupsHeader));
+                if (groups)
+                    user.groups = groups;
+            }
+            req.user = user;
+        });
+        return;
+    }
+    // mode === "jwt"
+    if (!cfg.jwksUrl) {
+        throw new Error("auth: PADDOCK_AUTH_MODE=jwt requires PADDOCK_AUTH_JWKS_URL (the IdP's JWKS endpoint)");
+    }
+    let jwks;
+    try {
+        jwks = createRemoteJWKSet(new URL(cfg.jwksUrl));
+    }
+    catch (err) {
+        throw new Error(`auth: invalid PADDOCK_AUTH_JWKS_URL (${cfg.jwksUrl}): ${err.message}`);
+    }
+    app.log.info({ jwksUrl: cfg.jwksUrl, jwtHeader: cfg.jwtHeader, issuer: cfg.jwtIssuer, audience: cfg.jwtAudience }, "auth: mode=jwt (verifying signed tokens against remote JWKS)");
+    app.addHook("onRequest", async (req, reply) => {
+        if (isExempt(req.url)) {
+            req.user = ANONYMOUS;
+            return;
+        }
+        const token = tokenFromRequest(req, cfg);
+        if (!token) {
+            req.log.warn({ url: req.url, header: cfg.jwtHeader }, "auth: missing JWT");
+            return reply.code(401).send({ error: "unauthorized", code: "auth_required" });
+        }
+        let payload;
+        try {
+            ({ payload } = await jwtVerify(token, jwks, {
+                ...(cfg.jwtIssuer ? { issuer: cfg.jwtIssuer } : {}),
+                ...(cfg.jwtAudience ? { audience: cfg.jwtAudience } : {}),
+            }));
+        }
+        catch (err) {
+            // Invalid signature, expired, wrong issuer/audience, malformed, etc.
+            req.log.warn({ url: req.url, err: err.message }, "auth: JWT verification failed");
+            return reply.code(401).send({ error: "invalid token", code: "auth_invalid" });
+        }
+        const username = usernameFromClaims(payload, cfg);
+        if (!username) {
+            req.log.warn({ url: req.url, claim: cfg.usernameClaim }, "auth: JWT verified but no username claim present");
+            return reply.code(401).send({ error: "invalid token", code: "auth_no_subject" });
+        }
+        const user = { username };
+        const email = payload.email;
+        if (typeof email === "string" && email.trim().length > 0)
+            user.email = email.trim();
+        // Groups: prefer the JWT claim; allow a header override only if explicitly set.
+        const groups = cfg.groupsHeader
+            ? splitGroups(header(req, cfg.groupsHeader)) ?? groupsFromClaims(payload, cfg)
+            : groupsFromClaims(payload, cfg);
+        if (groups)
+            user.groups = groups;
+        req.user = user;
+    });
+}

package/packages/server/dist/background.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Background-job & Monitor enrichment — issue #230.
+ *
+ * Keepers launch a lot of *detached* work: background `Bash`
+ * (`run_in_background:true`), `Monitor` event streams, and the background-task
+ * ops (`BashOutput`/`TaskOutput`/`TaskStop`/`KillShell`). herdctl's parser
+ * renders each as a plain tool call, identical to a synchronous `Read`, and the
+ * eventual result arrives *separately* as a `<task-notification>` (surfaced by
+ * herdctl #363 as `origin.kind:"task-notification"`) that the web draws as a
+ * disconnected status pill.
+ *
+ * This pass reconnects the two. Everything needed is already in the parsed
+ * messages — no raw-JSONL re-scan, no positional id recovery — because the
+ * **task id** appears on both sides:
+ *
+ *   launch output  →  bg Bash:  "Command running in background with ID: <id>…"
+ *                     Monitor:  "Monitor started (task <id>, timeout …| persistent …)"
+ *   notification   →  <task-id><id></task-id> + <status>/<summary>/<event>
+ *
+ * We flag background tool calls, fold the matching notification(s) into the
+ * launching `toolCall` (final status + completion summary for bg Bash; the
+ * streamed `<event>` lines for Monitor), and mark the consumed notification
+ * messages so the web no longer scatters them as standalone pills.
+ *
+ * Pure and synchronous — composes after {@link enrichWithSubagents} over the same
+ * `EnrichedMessage[]`. No herdctl change.
+ */
+import type { EnrichedMessage } from "./subagents.js";
+/**
+ * Enrich background tool calls: flag them, parse task ids from launch outputs,
+ * index task-notifications by task id, fold status/summary/events into the
+ * launching `toolCall`, and mark the folded notification messages `bgConsumed`.
+ * Non-background tool calls and notification-free transcripts pass through
+ * unchanged (cheap early return).
+ */
+export declare function enrichWithBackground(messages: EnrichedMessage[]): EnrichedMessage[];

package/packages/server/dist/background.js

@@ -0,0 +1,137 @@
+import { isTerminatedTaskStatus } from "./recovery-config.js";
+/** Background-task *ops* — badge only (they operate on an already-detached task). */
+const BACKGROUND_OP_NAMES = new Set(["BashOutput", "TaskOutput", "TaskStop", "KillShell"]);
+/** bg `Bash` (and any tool) launch: "…running in background with ID: <id>…". */
+const BG_LAUNCH_RE = /running in (?:the )?background with ID: ([A-Za-z0-9]+)/i;
+/** `Monitor` launch: "Monitor started (task <id>, timeout … | persistent …)". */
+const MONITOR_LAUNCH_RE = /^Monitor started \(task ([A-Za-z0-9]+)/;
+/** `TaskStop` result: {"message":"Successfully stopped task: <id> (…)"}. */
+const STOPPED_TASK_RE = /stopped task:\s*([A-Za-z0-9]+)/i;
+/** Identify a background *launch* (Monitor / bg Bash) and its task id, else null. */
+function detectLaunch(tc) {
+    const output = tc.output ?? "";
+    if (tc.toolName === "Monitor") {
+        const m = MONITOR_LAUNCH_RE.exec(output);
+        if (m)
+            return { taskId: m[1], kind: "monitor" };
+        // A Monitor whose start was denied/errored has no task — still background.
+        return null;
+    }
+    const m = BG_LAUNCH_RE.exec(output);
+    if (m)
+        return { taskId: m[1], kind: "bash" };
+    return null;
+}
+/** Cheap gate: does this transcript contain any background-class tool call? */
+function hasBackgroundTool(messages) {
+    return messages.some((m) => {
+        const tc = m.toolCall;
+        if (!tc)
+            return false;
+        return (tc.toolName === "Monitor" ||
+            BACKGROUND_OP_NAMES.has(tc.toolName) ||
+            BG_LAUNCH_RE.test(tc.output ?? ""));
+    });
+}
+const tag = (content, name) => {
+    const m = new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(content);
+    const v = m?.[1]?.trim();
+    return v && v.length ? v : undefined;
+};
+/** True when a `role:"user"` message is an internal `<task-notification>` block. */
+function isTaskNotification(m) {
+    return (m.origin?.kind === "task-notification" ||
+        (m.role === "user" && m.content.trimStart().startsWith("<task-notification>")));
+}
+/**
+ * Enrich background tool calls: flag them, parse task ids from launch outputs,
+ * index task-notifications by task id, fold status/summary/events into the
+ * launching `toolCall`, and mark the folded notification messages `bgConsumed`.
+ * Non-background tool calls and notification-free transcripts pass through
+ * unchanged (cheap early return).
+ */
+export function enrichWithBackground(messages) {
+    if (!hasBackgroundTool(messages))
+        return messages;
+    // Pass 1 — index every task-notification by its task id.
+    const byTask = new Map();
+    for (const m of messages) {
+        if (!isTaskNotification(m))
+            continue;
+        const taskId = tag(m.content, "task-id");
+        if (!taskId)
+            continue;
+        let agg = byTask.get(taskId);
+        if (!agg) {
+            agg = { events: [] };
+            byTask.set(taskId, agg);
+        }
+        const event = tag(m.content, "event");
+        if (event !== undefined)
+            agg.events.push(event);
+        const status = tag(m.content, "status");
+        if (status) {
+            agg.status = status;
+            agg.completionSummary = tag(m.content, "summary");
+        }
+    }
+    // Pass 2 — attach to each background launch; collect the consumed task ids.
+    const consumed = new Set();
+    const attached = messages.map((m) => {
+        const tc = m.toolCall;
+        if (!tc)
+            return m;
+        const launch = detectLaunch(tc);
+        if (launch) {
+            const agg = byTask.get(launch.taskId);
+            const next = { ...tc, background: true, taskId: launch.taskId };
+            if (launch.kind === "monitor") {
+                if (agg?.events.length)
+                    next.monitorEvents = agg.events;
+                // A Monitor rarely gets an explicit <status>; it ends with a timeout
+                // *event* ("[Monitor timed out …]") or runs until TaskStop / session end.
+                const timedOut = agg?.events.some((e) => /monitor timed out/i.test(e));
+                next.taskStatus =
+                    agg?.status ??
+                        (timedOut ? "timed out" : /persistent/.test(tc.output ?? "") ? "persistent" : "running");
+            }
+            else {
+                next.taskStatus = agg?.status ?? "running";
+                if (agg?.completionSummary)
+                    next.taskResultSummary = agg.completionSummary;
+            }
+            if (agg)
+                consumed.add(launch.taskId);
+            return { ...m, toolCall: next };
+        }
+        if (BACKGROUND_OP_NAMES.has(tc.toolName)) {
+            // A background-task op — badge only. Recover a task id where cheap (TaskStop).
+            const stopped = STOPPED_TASK_RE.exec(tc.output ?? "");
+            return {
+                ...m,
+                toolCall: { ...tc, background: true, ...(stopped ? { taskId: stopped[1] } : {}) },
+            };
+        }
+        return m;
+    });
+    if (consumed.size === 0)
+        return attached;
+    // Pass 3 — mark folded notifications so the web drops the standalone pill.
+    // EXCEPTION (issue #301, Layer 2): a KILLED/STOPPED notification is NEVER folded
+    // away, even when its task id matches a launch. That's the turn-boundary-kill
+    // case (edspencer/herdctl#374) — the keeper is left alive-but-idle — and it must
+    // surface as a prominent standalone affordance ("keeper is idle" + Continue),
+    // not be reduced to a small "killed" chip on a scrolled-away tool block. The
+    // chip STILL renders (Pass 2 folded the status onto the launch); this only keeps
+    // the standalone notification turn alive so the recovery UI has something to hang.
+    return attached.map((m) => {
+        if (!isTaskNotification(m))
+            return m;
+        const taskId = tag(m.content, "task-id");
+        if (!taskId || !consumed.has(taskId))
+            return m;
+        if (isTerminatedTaskStatus(tag(m.content, "status")))
+            return m;
+        return { ...m, bgConsumed: true };
+    });
+}

package/packages/server/dist/bind-safety.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Safe-by-default bind guard (#435).
+ *
+ * Paddock runs code and spends Claude tokens, so a careless launch on a routable
+ * interface is a real footgun. Two things protect against it:
+ *
+ *  1. The bind host now defaults to `127.0.0.1` (see config.ts) — a fresh
+ *     source/tarball run is network-closed.
+ *  2. This guard couples EXPOSURE to AUTH: if the resolved bind host is
+ *     NON-loopback AND `auth.mode === "none"`, Paddock REFUSES to start — mirroring
+ *     the jwt-without-JWKS fail-closed behavior in auth.ts — unless the operator
+ *     sets `PADDOCK_DANGEROUSLY_ALLOW_OPEN` (accepts 1/true/yes), in which case it
+ *     starts but logs a loud one-line warning.
+ *
+ * Binding non-loopback WITH a real auth mode (`trusted-header`/`jwt`) is fine and
+ * needs no flag.
+ *
+ * Scope note: this is the APP/source-layer guard for bare-metal / tarball / VM /
+ * LXC-systemd runs. Inside a container the network namespace is the isolation
+ * boundary and the app can't see the host's port-publish posture, so the image
+ * keeps binding `0.0.0.0` and the deploy RECIPE carries the safe publish posture
+ * (see #406/#410) — this guard is not the container's police.
+ */
+import type { AuthMode } from "./config.js";
+/** Inputs the bind-safety decision is a pure function of. */
+export interface BindSafetyInput {
+    /** The resolved bind host (cfg.host). */
+    host: string;
+    /** The resolved auth mode (cfg.auth.mode). */
+    authMode: AuthMode;
+    /** Whether PADDOCK_DANGEROUSLY_ALLOW_OPEN is set (truthy). */
+    dangerouslyAllowOpen: boolean;
+}
+export type BindSafetyDecision = {
+    action: "allow";
+} | {
+    action: "warn";
+    message: string;
+} | {
+    action: "refuse";
+    message: string;
+};
+/**
+ * True when `host` names a loopback-only interface — one that is NOT reachable
+ * from other machines. Covers `localhost`, the whole IPv4 `127.0.0.0/8` block,
+ * the IPv6 loopback `::1`, and IPv4-mapped loopback (`::ffff:127.x.x.x`). Bracket
+ * forms (`[::1]`) and surrounding whitespace/case are normalized away.
+ *
+ * `0.0.0.0` and `::` (all interfaces) are NOT loopback — they are the footgun.
+ */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * Decide whether it's safe to bind `host` under `authMode`. Pure — the caller
+ * (assertBindSafety) resolves env and acts on the decision (throw / warn / go).
+ */
+export declare function evaluateBindSafety(input: BindSafetyInput): BindSafetyDecision;

package/packages/server/dist/bind-safety.js

@@ -0,0 +1,51 @@
+/**
+ * True when `host` names a loopback-only interface — one that is NOT reachable
+ * from other machines. Covers `localhost`, the whole IPv4 `127.0.0.0/8` block,
+ * the IPv6 loopback `::1`, and IPv4-mapped loopback (`::ffff:127.x.x.x`). Bracket
+ * forms (`[::1]`) and surrounding whitespace/case are normalized away.
+ *
+ * `0.0.0.0` and `::` (all interfaces) are NOT loopback — they are the footgun.
+ */
+export function isLoopbackHost(host) {
+    let h = host.trim().toLowerCase();
+    if (h.startsWith("[") && h.endsWith("]"))
+        h = h.slice(1, -1);
+    if (h === "localhost")
+        return true;
+    if (h === "::1")
+        return true;
+    // IPv4-mapped IPv6 loopback, e.g. ::ffff:127.0.0.1
+    const mapped = h.startsWith("::ffff:") ? h.slice("::ffff:".length) : h;
+    // IPv4 127.0.0.0/8 — first octet 127, and a plausible dotted-quad shape.
+    return /^127(?:\.\d{1,3}){3}$/.test(mapped);
+}
+/**
+ * Decide whether it's safe to bind `host` under `authMode`. Pure — the caller
+ * (assertBindSafety) resolves env and acts on the decision (throw / warn / go).
+ */
+export function evaluateBindSafety(input) {
+    const { host, authMode, dangerouslyAllowOpen } = input;
+    // Loopback bind, or a real auth mode gating a non-loopback bind: safe.
+    if (isLoopbackHost(host) || authMode !== "none")
+        return { action: "allow" };
+    // Non-loopback + auth.mode=none — the footgun.
+    if (dangerouslyAllowOpen) {
+        return {
+            action: "warn",
+            message: `SECURITY: binding ${host} with PADDOCK_AUTH_MODE=none and ` +
+                `PADDOCK_DANGEROUSLY_ALLOW_OPEN set — Paddock is OPEN and UNAUTHENTICATED ` +
+                `on a routable interface. Anyone who can reach this port can run code and ` +
+                `spend Claude tokens as you. Put an auth mode / reverse proxy in front of it.`,
+        };
+    }
+    return {
+        action: "refuse",
+        message: `refusing to start: bind host "${host}" is not loopback and ` +
+            `PADDOCK_AUTH_MODE=none, which would expose an unauthenticated Paddock (it ` +
+            `runs code and spends Claude tokens) on a routable interface. Choose one: ` +
+            `set an auth mode behind a reverse proxy (PADDOCK_AUTH_MODE=trusted-header|jwt); ` +
+            `bind loopback (HOST=127.0.0.1) and reach it via a proxy/sidecar; or — only ` +
+            `if you TRULY intend an open, unauthenticated server — set ` +
+            `PADDOCK_DANGEROUSLY_ALLOW_OPEN=1.`,
+    };
+}

package/packages/server/dist/brand.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Per-instance branding injection (issue #34).
+ *
+ * The SPA's look (wordmark, logo glyph, accent color) is configured per
+ * instance via `PADDOCK_BRAND_*` env (see config.ts `BrandConfig`). Rather than
+ * bake it in at build time — which would force one image per instance — we
+ * inject it into `index.html` at serve time:
+ *
+ *  - a `window.__PADDOCK_CONFIG__` global the SPA reads for name + logo, and
+ *  - a `:root` `<style>` overriding the `--accent*` CSS channels the buttons and
+ *    logo chip use.
+ *
+ * Injecting into the served HTML (rather than fetching config after load) means
+ * no title flash and no wrong-color flash before the first paint.
+ */
+import type { BrandConfig } from "./config.js";
+export declare const DEFAULT_ACCENT = "#c2603c";
+/** Parse a `#rgb` / `#rrggbb` hex color to `[r, g, b]` (0–255), or null. */
+export declare function hexToRgb(hex: string): [number, number, number] | null;
+/**
+ * The `:root` accent override for a given accent color, or null when it matches
+ * the default (so a default instance stays pixel-identical to the CSS defaults
+ * and only genuinely-branded instances get computed hover shades). An accent
+ * that doesn't parse as hex falls back to null (defaults apply).
+ *
+ * The 600/700 hover shades are derived by darkening — close enough to the
+ * hand-tuned terracotta ramp for a hover/active state, and it means an operator
+ * only has to pick ONE color.
+ */
+export declare function accentRootStyle(accent: string): string | null;
+/**
+ * Inject branding into the built `index.html`:
+ *  - replace the <title> with the configured name,
+ *  - add a `window.__PADDOCK_CONFIG__` script (name + logo for the SPA),
+ *  - add a `:root` accent override <style> (only when non-default).
+ *
+ * Everything is inserted just before `</head>` so it wins over the linked
+ * stylesheet's `--accent` defaults by source order. Idempotent-ish: called once
+ * at startup and the result cached.
+ */
+export declare function renderIndexHtml(rawHtml: string, brand: BrandConfig, openapi?: {
+    enabled: boolean;
+    path: string;
+}): string;

package/packages/server/dist/brand.js

@@ -0,0 +1,88 @@
+export const DEFAULT_ACCENT = "#c2603c";
+/** Parse a `#rgb` / `#rrggbb` hex color to `[r, g, b]` (0–255), or null. */
+export function hexToRgb(hex) {
+    const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return null;
+    let h = m[1];
+    if (h.length === 3)
+        h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+    const n = parseInt(h, 16);
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+/** Darken an RGB triple by `factor` (0–1), rounding + clamping to 0–255. */
+function darken([r, g, b], factor) {
+    const clamp = (v) => Math.max(0, Math.min(255, Math.round(v * factor)));
+    return [clamp(r), clamp(g), clamp(b)];
+}
+/** RGB triple as the space-separated channel string Tailwind's tokens expect. */
+function channels([r, g, b]) {
+    return `${r} ${g} ${b}`;
+}
+/**
+ * The `:root` accent override for a given accent color, or null when it matches
+ * the default (so a default instance stays pixel-identical to the CSS defaults
+ * and only genuinely-branded instances get computed hover shades). An accent
+ * that doesn't parse as hex falls back to null (defaults apply).
+ *
+ * The 600/700 hover shades are derived by darkening — close enough to the
+ * hand-tuned terracotta ramp for a hover/active state, and it means an operator
+ * only has to pick ONE color.
+ */
+export function accentRootStyle(accent) {
+    const rgb = hexToRgb(accent);
+    if (!rgb)
+        return null;
+    if (accent.trim().toLowerCase() === DEFAULT_ACCENT)
+        return null;
+    const base = channels(rgb);
+    const c600 = channels(darken(rgb, 0.86));
+    const c700 = channels(darken(rgb, 0.71));
+    return `:root{--accent:${base};--accent-600:${c600};--accent-700:${c700};}`;
+}
+/** Escape a string for safe interpolation into HTML text (title). */
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/** Serialize a value to JSON safe to embed inside a <script> tag. */
+function safeJson(value) {
+    // Escape `<` so a `</script>` (or `<!--`) in a value can't break out of the
+    // inline script; JSON.parse is unaffected by the < escape.
+    return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+/**
+ * Inject branding into the built `index.html`:
+ *  - replace the <title> with the configured name,
+ *  - add a `window.__PADDOCK_CONFIG__` script (name + logo for the SPA),
+ *  - add a `:root` accent override <style> (only when non-default).
+ *
+ * Everything is inserted just before `</head>` so it wins over the linked
+ * stylesheet's `--accent` defaults by source order. Idempotent-ish: called once
+ * at startup and the result cached.
+ */
+export function renderIndexHtml(rawHtml, brand, openapi) {
+    let html = rawHtml;
+    // 1. Title.
+    html = html.replace(/<title>[^<]*<\/title>/i, `<title>${escapeHtml(brand.name)}</title>`);
+    // 2. Config global + accent override, injected before </head>. The `openapi`
+    // block lets the SPA render (or hide) the "Swagger API" nav link without a
+    // round-trip — flash-free, same as the brand.
+    const config = safeJson({
+        brand: { name: brand.name, logo: brand.logo, accent: brand.accent },
+        ...(openapi ? { openapi } : {}),
+    });
+    const accentStyle = accentRootStyle(brand.accent);
+    const injection = `<script>window.__PADDOCK_CONFIG__=${config};</script>` +
+        (accentStyle ? `<style>${accentStyle}</style>` : "");
+    if (/<\/head>/i.test(html)) {
+        html = html.replace(/<\/head>/i, `${injection}</head>`);
+    }
+    else {
+        // No </head> (unexpected) — prepend so the config is still present.
+        html = injection + html;
+    }
+    return html;
+}