@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/attachments-config.js

@@ -0,0 +1,165 @@
+/**
+ * Inbound attachment config — the config foundation for issue #328 Phase 1
+ * (ChatGPT-style file/image upload in the composer, "Approach A").
+ *
+ * ── What this governs ────────────────────────────────────────────────────────
+ * A user can pick / drag / paste files into the composer; each is copied into the
+ * per-instance attachment store (reusing the `send_file` store, #112) and the
+ * keeper is pointed at the absolute paths so its `Read` tool can view them
+ * (native vision on images/PDFs). This module resolves the four knobs that gate
+ * that flow: whether it's enabled at all, a per-file size cap, a per-message file
+ * count cap, and an allow-list of file types.
+ *
+ * ── Config discipline (the `recovery`/`driveMode` pattern) ───────────────────
+ * Every field is an instance default (`PADDOCK_ATTACHMENTS_*` env, YAML instance
+ * file beneath it) with an optional PER-PROJECT override (`project.yaml` →
+ * {@link import("./projects.js").ProjectYaml.attachments}). An absent/invalid
+ * override field inherits the instance default, resolved at request time by
+ * {@link resolveAttachmentsConfig} — never baked into the DTO (mirrors how
+ * `recovery` resolves via {@link import("./recovery-config.js").resolveRecoveryConfig}).
+ * A malformed override is ignored rather than fatal so a hand-edited `project.yaml`
+ * can't wedge an upload.
+ *
+ * ── allowedTypes semantics ───────────────────────────────────────────────────
+ * Each entry is either a MIME pattern (contains `/`, `*` wildcards a segment —
+ * `image/*`, `*​/*`) or an extension (starts with `.` — `.csv`, `.ipynb`). A file
+ * is allowed if its MIME matches any MIME pattern OR its extension matches any
+ * extension entry. The sentinel `"*"` (or `"*​/*"`) allows everything (the
+ * default). The extension fallback matters because browsers report empty/generic
+ * MIME for many real attachments (`.md`, `.ts`, `.heic` → `""`/`text/plain`).
+ *
+ * NOTE: `File.type` / multipart content-type are client-provided and spoofable,
+ * so allowedTypes is a hygiene/UX guardrail, NOT a security boundary (no
+ * magic-byte sniffing in v1) — appropriate for a personal/LAN tool.
+ */
+/**
+ * The built-in attachment defaults (beneath env + YAML + per-project override):
+ * enabled, 25 MB/file, 10 files/message, allow-all.
+ */
+export const DEFAULT_ATTACHMENTS = Object.freeze({
+    enabled: true,
+    maxFileSizeMb: 25,
+    maxFilesPerMessage: 10,
+    allowedTypes: Object.freeze(["*"]),
+});
+/** 1 MB in bytes — the unit `maxFileSizeMb` is expressed in. */
+export const BYTES_PER_MB = 1024 * 1024;
+/** The per-file size cap in BYTES for a resolved config. */
+export function maxFileBytes(cfg) {
+    return cfg.maxFileSizeMb * BYTES_PER_MB;
+}
+/** True when `n` is a valid positive integer knob (size/count must be ≥ 1). */
+function isPositiveInt(n) {
+    return typeof n === "number" && Number.isInteger(n) && n >= 1 && Number.isFinite(n);
+}
+/**
+ * Normalise an allowedTypes list: keep only non-blank strings, trimmed and
+ * lower-cased (MIME + extensions are case-insensitive). Returns `undefined` when
+ * nothing valid remains (so an empty list never silently means "deny all").
+ */
+export function sanitizeAllowedTypes(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = value
+        .filter((e) => typeof e === "string")
+        .map((e) => e.trim().toLowerCase())
+        .filter((e) => e.length > 0);
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Validate + normalise an untrusted value (from `project.yaml` or a PATCH body)
+ * into an {@link AttachmentsOverride}, dropping any field that is missing or
+ * invalid, and returning `undefined` when nothing valid remains (so an empty
+ * override is never persisted). `enabled` must be a real boolean; the numeric
+ * knobs must be positive integers; `allowedTypes` must be a non-empty string
+ * array. Defensive by design — a malformed hand-edit degrades to "inherit the
+ * instance default", never a crash.
+ */
+export function sanitizeAttachmentsOverride(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const o = value;
+    const out = {};
+    if (typeof o.enabled === "boolean")
+        out.enabled = o.enabled;
+    if (isPositiveInt(o.maxFileSizeMb))
+        out.maxFileSizeMb = o.maxFileSizeMb;
+    if (isPositiveInt(o.maxFilesPerMessage))
+        out.maxFilesPerMessage = o.maxFilesPerMessage;
+    const types = sanitizeAllowedTypes(o.allowedTypes);
+    if (types)
+        out.allowedTypes = types;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Resolve the effective attachment config for a request: a valid per-project
+ * override wins field-by-field; every absent field inherits the instance default.
+ * Mirrors how `recovery`/`driveMode` resolve — the override is carried on disk
+ * only for the fields explicitly set, so an absent value transparently inherits
+ * the instance (env/YAML) default. The override is re-sanitised so a corrupt
+ * on-disk value can't leak through.
+ */
+export function resolveAttachmentsConfig(override, instanceDefault) {
+    const clean = sanitizeAttachmentsOverride(override) ?? {};
+    return {
+        enabled: clean.enabled ?? instanceDefault.enabled,
+        maxFileSizeMb: clean.maxFileSizeMb ?? instanceDefault.maxFileSizeMb,
+        maxFilesPerMessage: clean.maxFilesPerMessage ?? instanceDefault.maxFilesPerMessage,
+        allowedTypes: clean.allowedTypes ?? instanceDefault.allowedTypes,
+    };
+}
+/** The extension of a filename, lower-cased, WITH the leading dot (`.csv`), or "". */
+function extensionOf(filename) {
+    const base = filename.slice(filename.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    // No dot, or a dotfile with no extension (`.gitignore` → treat as no ext).
+    return dot > 0 ? base.slice(dot).toLowerCase() : "";
+}
+/**
+ * Does a concrete `mime` (e.g. `image/png`) match a MIME PATTERN entry (e.g.
+ * `image/*`, `*​/*`, `text/csv`)? `*` wildcards a whole segment. Both are
+ * lower-cased by the caller / sanitiser. A blank mime never matches a pattern
+ * (fall back to the extension test instead).
+ */
+function mimeMatches(pattern, mime) {
+    if (!mime)
+        return false;
+    const [pType, pSub] = pattern.split("/", 2);
+    const [mType, mSub] = mime.split("/", 2);
+    const seg = (p, m) => p === "*" || p === m;
+    return seg(pType, mType) && seg(pSub, mSub);
+}
+/**
+ * True when a file (identified by its browser-reported `mime` and its
+ * `filename`) is allowed by `allowedTypes`. Allowed if any entry matches: a
+ * MIME-pattern entry (contains `/`) is tested against `mime`; an extension entry
+ * (starts with `.`) against the filename's extension. The sentinel `"*"` /
+ * `"*​/*"` allows everything. See the module doc for why the extension fallback
+ * exists. `mime`/`filename` may be empty (browsers often omit one).
+ */
+export function isTypeAllowed(allowedTypes, mime, filename) {
+    const m = (mime ?? "").trim().toLowerCase();
+    const ext = extensionOf(filename ?? "");
+    for (const raw of allowedTypes) {
+        const entry = raw.trim().toLowerCase();
+        if (!entry)
+            continue;
+        // Allow-all sentinels.
+        if (entry === "*" || entry === "*/*")
+            return true;
+        if (entry.includes("/")) {
+            if (mimeMatches(entry, m))
+                return true;
+        }
+        else if (entry.startsWith(".")) {
+            if (ext && ext === entry)
+                return true;
+        }
+        else {
+            // A bare token (e.g. "png") — tolerate it as an extension match.
+            if (ext && ext === `.${entry}`)
+                return true;
+        }
+    }
+    return false;
+}

package/packages/server/dist/attachments-hint.d.ts

@@ -0,0 +1,53 @@
+/** The renderer hint carried per attachment (a subset of send_file's kinds). */
+export type AttachmentKind = "image" | "video" | "pdf" | "markdown" | "code" | "text" | "html" | "file";
+export declare const ATTACHMENTS_OPEN = "<paddock-attachments>";
+export declare const ATTACHMENTS_CLOSE = "</paddock-attachments>";
+/** The literal boundary between the attachment block and the user's real request. */
+export declare const ATTACHMENTS_REQUEST_MARKER = "</paddock-attachments>\n\n";
+/** One attachment as the server knows it when building the prompt block. */
+export interface PromptAttachment {
+    /** Opaque attachment-store id (`<uuid><ext>`), also the basename of `path`. */
+    id: string;
+    /** Original display filename (as uploaded). */
+    filename: string;
+    /** Renderer hint. */
+    kind: AttachmentKind;
+    /** Absolute path to the stored bytes, so the keeper's Read tool can open it. */
+    path: string;
+}
+/** A parsed attachment ref for the web (no absolute path — it fetches by id). */
+export interface ParsedAttachment {
+    id: string;
+    filename: string;
+    kind: AttachmentKind;
+}
+/**
+ * Infer a renderer {@link AttachmentKind} from a filename. Images/videos/PDFs get
+ * rich rendering; source/markup/text get a typed chip; everything else is a
+ * generic `file`. IMAGE is tested before VIDEO so `.webp` (image) never collides
+ * with `.webm` (video).
+ */
+export declare function inferAttachmentKind(filename: string, mime?: string): AttachmentKind;
+/**
+ * Build the attachment-wrapped prompt. Returns `message` unchanged when there are
+ * no attachments, so the caller can always wrap unconditionally.
+ */
+export declare function wrapAttachments(attachments: PromptAttachment[], message: string): string;
+/**
+ * Parse a (possibly) attachment-wrapped message into its attachment refs + the
+ * user's real request. If `text` isn't wrapped it's returned unchanged with an
+ * empty list. The block may be nested inside a preload wrapper, so we locate it
+ * anywhere in `text` rather than only at the very start.
+ */
+export declare function parseAttachmentsWrapper(text: string): {
+    attachments: ParsedAttachment[];
+    message: string;
+};
+/** Just the attachment ids referenced by a wrapped message (cleanup-on-delete). */
+export declare function parseAttachmentIds(text: string): string[];
+/**
+ * Recover the user's real request from a (possibly) attachment-wrapped message —
+ * the clean text with the `<paddock-attachments>` block removed. Used for chat
+ * display-name derivation (mirrors {@link import("./preload.js").stripPreloadWrapper}).
+ */
+export declare function stripAttachmentsWrapper(text: string): string;

package/packages/server/dist/attachments-hint.js

@@ -0,0 +1,140 @@
+/**
+ * The composer-attachment "hint" wrapper for issue #328 Phase 1.
+ *
+ * On a turn that carries uploaded files, the server prepends a delimited block to
+ * the prompt string — exactly like the `<project-context>` preload wrapper
+ * (preload.ts) — telling the keeper which files were attached and pointing its
+ * `Read` tool at their absolute paths (native vision on images/PDFs). The block
+ * is single-sourced HERE so the WS layer that BUILDS it and the web that STRIPS +
+ * PARSES it (for the transcript chips) can't drift.
+ *
+ *   <paddock-attachments>
+ *   The user attached these files. Use the Read tool to view images and PDFs;
+ *   each line is: id \t kind \t filename \t absolute-path.
+ *   <id>\t<kind>\t<filename>\t<abs path>
+ *   …
+ *   </paddock-attachments>
+ *
+ *   <the user's actual message>
+ *
+ * Both audiences read the same block: the keeper reads the human header + the
+ * visible absolute path in each line; the web parses the tab-delimited lines to
+ * rebuild image thumbnails / file chips from the attachment store on reload. The
+ * cleanup-on-delete path also parses it (via {@link parseAttachmentIds}) so an
+ * uploaded file's bytes are removed with its chat.
+ *
+ * The wrapper nests INSIDE the preload wrapper when both apply (attachments wrap
+ * the user's message first, then preload wraps the whole thing), so stripping the
+ * attachment block yields the same clean request the preload strip already
+ * expects.
+ */
+import { extname } from "node:path";
+export const ATTACHMENTS_OPEN = "<paddock-attachments>";
+export const ATTACHMENTS_CLOSE = "</paddock-attachments>";
+/** The literal boundary between the attachment block and the user's real request. */
+export const ATTACHMENTS_REQUEST_MARKER = `${ATTACHMENTS_CLOSE}\n\n`;
+const HEADER = "The user attached these files. Use the Read tool to view images and PDFs; " +
+    "each line is: id\\tkind\\tfilename\\tabsolute-path.";
+const IMAGE_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg", ".heic"]);
+const VIDEO_EXT = new Set([".mp4", ".webm", ".mov", ".m4v"]);
+const PDF_EXT = new Set([".pdf"]);
+const MARKDOWN_EXT = new Set([".md", ".mdx", ".markdown"]);
+const HTML_EXT = new Set([".html", ".htm"]);
+const CODE_EXT = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rb", ".go", ".rs",
+    ".java", ".c", ".h", ".cpp", ".cc", ".cs", ".php", ".swift", ".kt", ".sh",
+    ".bash", ".zsh", ".sql", ".json", ".yaml", ".yml", ".toml", ".css", ".scss",
+    ".xml",
+]);
+const TEXT_EXT = new Set([".txt", ".text", ".log", ".csv", ".tsv", ".env", ".ini"]);
+/**
+ * Infer a renderer {@link AttachmentKind} from a filename. Images/videos/PDFs get
+ * rich rendering; source/markup/text get a typed chip; everything else is a
+ * generic `file`. IMAGE is tested before VIDEO so `.webp` (image) never collides
+ * with `.webm` (video).
+ */
+export function inferAttachmentKind(filename, mime) {
+    const ext = extname(filename).toLowerCase();
+    if (IMAGE_EXT.has(ext) || (mime ?? "").startsWith("image/"))
+        return "image";
+    if (VIDEO_EXT.has(ext) || (mime ?? "").startsWith("video/"))
+        return "video";
+    if (PDF_EXT.has(ext) || mime === "application/pdf")
+        return "pdf";
+    if (MARKDOWN_EXT.has(ext))
+        return "markdown";
+    if (HTML_EXT.has(ext))
+        return "html";
+    if (CODE_EXT.has(ext))
+        return "code";
+    if (TEXT_EXT.has(ext) || (mime ?? "").startsWith("text/"))
+        return "text";
+    return "file";
+}
+/** A tab or newline in a field would corrupt the block; collapse to a space. */
+function sanitizeField(s) {
+    return s.replace(/[\t\r\n]+/g, " ").trim();
+}
+/**
+ * Build the attachment-wrapped prompt. Returns `message` unchanged when there are
+ * no attachments, so the caller can always wrap unconditionally.
+ */
+export function wrapAttachments(attachments, message) {
+    if (attachments.length === 0)
+        return message;
+    const lines = attachments.map((a) => `${a.id}\t${a.kind}\t${sanitizeField(a.filename)}\t${a.path}`);
+    return `${ATTACHMENTS_OPEN}\n${HEADER}\n${lines.join("\n")}\n${ATTACHMENTS_REQUEST_MARKER}${message}`;
+}
+/**
+ * Parse a (possibly) attachment-wrapped message into its attachment refs + the
+ * user's real request. If `text` isn't wrapped it's returned unchanged with an
+ * empty list. The block may be nested inside a preload wrapper, so we locate it
+ * anywhere in `text` rather than only at the very start.
+ */
+export function parseAttachmentsWrapper(text) {
+    const open = text.indexOf(ATTACHMENTS_OPEN);
+    if (open === -1)
+        return { attachments: [], message: text };
+    const bodyStart = open + ATTACHMENTS_OPEN.length;
+    const close = text.indexOf(ATTACHMENTS_CLOSE, bodyStart);
+    if (close === -1)
+        return { attachments: [], message: text };
+    const body = text.slice(bodyStart, close);
+    const attachments = [];
+    for (const line of body.split("\n")) {
+        const parts = line.split("\t");
+        // A data line is `id \t kind \t filename [\t path]`. The header line has no
+        // tabs, so it's naturally skipped.
+        if (parts.length < 3)
+            continue;
+        const [id, kind, filename] = parts;
+        if (!id || !filename)
+            continue;
+        attachments.push({
+            id: id.trim(),
+            filename: filename.trim(),
+            kind: (kind.trim() || "file"),
+        });
+    }
+    // Strip the whole block to recover the user's clean request: everything before
+    // the open tag + everything after the close marker. (Anything before the open
+    // tag is a preload wrapper we deliberately leave intact — existing behavior.)
+    const before = text.slice(0, open);
+    const afterClose = close + ATTACHMENTS_CLOSE.length;
+    const after = text.startsWith(ATTACHMENTS_REQUEST_MARKER, close)
+        ? text.slice(close + ATTACHMENTS_REQUEST_MARKER.length)
+        : text.slice(afterClose).replace(/^\n+/, "");
+    return { attachments, message: before + after };
+}
+/** Just the attachment ids referenced by a wrapped message (cleanup-on-delete). */
+export function parseAttachmentIds(text) {
+    return parseAttachmentsWrapper(text).attachments.map((a) => a.id);
+}
+/**
+ * Recover the user's real request from a (possibly) attachment-wrapped message —
+ * the clean text with the `<paddock-attachments>` block removed. Used for chat
+ * display-name derivation (mirrors {@link import("./preload.js").stripPreloadWrapper}).
+ */
+export function stripAttachmentsWrapper(text) {
+    return parseAttachmentsWrapper(text).message;
+}

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

@@ -0,0 +1,33 @@
+import type { ChatMessage } from "@herdctl/core";
+export declare class AttachmentStore {
+    private readonly root;
+    constructor(root: string);
+    init(): Promise<void>;
+    /** Persist bytes, returning an opaque id (`<uuid>` + the source's extension). */
+    save(bytes: Buffer, filenameForExt: string): Promise<string>;
+    /**
+     * The absolute on-disk path for a (validated) attachment id, or `null` if the
+     * id is malformed. Used to point the keeper's `Read` tool at an uploaded file
+     * (issue #328) — the store file IS the on-disk copy the agent reads. Does not
+     * check existence; pair with {@link exists} when that matters.
+     */
+    absolutePath(id: string): string | null;
+    /** True when a (validated) attachment id currently has bytes on disk. */
+    exists(id: string): Promise<boolean>;
+    /** Read an attachment by id (validated), with a content-type for serving. */
+    read(id: string): Promise<{
+        bytes: Buffer;
+        mime: string;
+    } | null>;
+    /** Best-effort removal of a set of attachments (used on chat delete). */
+    remove(ids: string[]): Promise<void>;
+}
+/**
+ * Extract the attachment ids a chat's transcript references, used to clean up a
+ * chat's attachments when it's deleted. Two sources:
+ *   - agent `send_file` tool outputs (#112) — the JSON envelope's `attachmentId`;
+ *   - user upload wrappers (#328) — the `<paddock-attachments>` block a user turn
+ *     carries, parsed by {@link parseAttachmentIds}.
+ * Inline `send_file` sends carry no id, so they're naturally skipped.
+ */
+export declare function collectAttachmentIds(messages: ChatMessage[]): string[];

package/packages/server/dist/attachments.js

@@ -0,0 +1,117 @@
+/**
+ * Attachment store for files shared via `mcp__paddock__send_file` (issue #112).
+ *
+ * When an agent sends a REAL file, we copy its bytes here AT SEND TIME and record
+ * only an opaque attachment id in the chat transcript (via the tool's output
+ * envelope). This makes a shared file an immutable snapshot — it renders
+ * identically forever, even if the original is later edited, moved, or deleted —
+ * and means the render endpoint only ever serves files that were explicitly
+ * sent, never an arbitrary path on the box. (Inline/virtual content is NOT stored
+ * here; it rides in the transcript envelope so it stays in the agent's context.)
+ *
+ * Layout: a flat directory of `<uuid><ext>` files. Ids are self-locating, so the
+ * serving endpoint needs only the id. Cleanup on chat delete parses the chat's
+ * transcript for the ids it referenced (see `collectAttachmentIds`).
+ */
+import { promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { contentTypeFor } from "./projects.js";
+import { SEND_FILE_TOOL_NAME } from "./send-file-mcp.js";
+import { ATTACHMENTS_OPEN, parseAttachmentIds } from "./attachments-hint.js";
+/** `<uuid>` optionally followed by a short `.ext` — the only shape we serve. */
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(\.[A-Za-z0-9]{1,8})?$/;
+export class AttachmentStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async init() {
+        await fs.mkdir(this.root, { recursive: true });
+    }
+    /** Persist bytes, returning an opaque id (`<uuid>` + the source's extension). */
+    async save(bytes, filenameForExt) {
+        const ext = path.extname(filenameForExt).toLowerCase().replace(/[^.a-z0-9]/g, "");
+        const id = `${randomUUID()}${ext}`;
+        await fs.mkdir(this.root, { recursive: true });
+        await fs.writeFile(path.join(this.root, id), bytes);
+        return id;
+    }
+    /**
+     * The absolute on-disk path for a (validated) attachment id, or `null` if the
+     * id is malformed. Used to point the keeper's `Read` tool at an uploaded file
+     * (issue #328) — the store file IS the on-disk copy the agent reads. Does not
+     * check existence; pair with {@link exists} when that matters.
+     */
+    absolutePath(id) {
+        if (!ID_RE.test(id))
+            return null;
+        return path.join(this.root, id);
+    }
+    /** True when a (validated) attachment id currently has bytes on disk. */
+    async exists(id) {
+        if (!ID_RE.test(id))
+            return false;
+        try {
+            const info = await fs.stat(path.join(this.root, id));
+            return info.isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Read an attachment by id (validated), with a content-type for serving. */
+    async read(id) {
+        if (!ID_RE.test(id))
+            return null;
+        try {
+            const bytes = await fs.readFile(path.join(this.root, id));
+            const mime = contentTypeFor(id);
+            return {
+                bytes,
+                // Non-image kinds (markdown/code/text/html) are fetched as text.
+                mime: mime === "application/octet-stream" ? "text/plain; charset=utf-8" : mime,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Best-effort removal of a set of attachments (used on chat delete). */
+    async remove(ids) {
+        await Promise.all(ids
+            .filter((id) => ID_RE.test(id))
+            .map((id) => fs.rm(path.join(this.root, id), { force: true }).catch(() => undefined)));
+    }
+}
+/**
+ * Extract the attachment ids a chat's transcript references, used to clean up a
+ * chat's attachments when it's deleted. Two sources:
+ *   - agent `send_file` tool outputs (#112) — the JSON envelope's `attachmentId`;
+ *   - user upload wrappers (#328) — the `<paddock-attachments>` block a user turn
+ *     carries, parsed by {@link parseAttachmentIds}.
+ * Inline `send_file` sends carry no id, so they're naturally skipped.
+ */
+export function collectAttachmentIds(messages) {
+    const ids = [];
+    for (const m of messages) {
+        // Agent-sent files (send_file tool output envelope).
+        if (m.toolCall?.toolName === SEND_FILE_TOOL_NAME && m.toolCall.output) {
+            try {
+                const env = JSON.parse(m.toolCall.output);
+                if (env?.paddockSendFile === 1 && env.source === "file" && env.attachmentId) {
+                    ids.push(env.attachmentId);
+                }
+            }
+            catch {
+                // Not our envelope / not JSON — skip.
+            }
+        }
+        // User-uploaded files (composer attachment wrapper). A user turn's content is
+        // the raw prompt string, which may carry the `<paddock-attachments>` block.
+        if (typeof m.content === "string" && m.content.includes(ATTACHMENTS_OPEN)) {
+            ids.push(...parseAttachmentIds(m.content));
+        }
+    }
+    return ids;
+}

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

@@ -0,0 +1,84 @@
+/**
+ * Provider-agnostic user authentication.
+ *
+ * Paddock has no login of its own — it is meant to sit behind a reverse proxy
+ * that has already authenticated the user against an OIDC IdP (Authentik,
+ * oauth2-proxy, Authelia, Cloudflare Access, Keycloak, …). This plugin turns
+ * that upstream identity into a `req.user` that the rest of the app can read,
+ * WITHOUT hardcoding any single provider. Behaviour is driven entirely by the
+ * `PADDOCK_AUTH_*` env vars resolved into `cfg.auth` (see config.ts + AUTH.md).
+ *
+ * Three modes:
+ *   - `none`            — no-op; every request is anonymous. Fully open (default).
+ *   - `trusted-header`  — read identity from proxy-set header(s). 401 if absent.
+ *                         Trust is network-level: only safe when the proxy is the
+ *                         sole path to paddock (it can forge headers otherwise).
+ *   - `jwt`             — verify a signed JWT (from a configured header) against a
+ *                         remote JWKS using `jose`. Zero-trust / spoof-proof:
+ *                         paddock holds no key material, only the JWKS URL, and
+ *                         rejects missing/invalid/expired tokens with 401.
+ *
+ * Paddock's health route (`/api/health`) is always exempt so the proxy and
+ * monitoring can poll a server that is otherwise locked down. Only registered
+ * routes may be exempted — see HEALTH_PATHS below for why (issue #569).
+ *
+ * Registered in app.ts BEFORE the routes so the `onRequest` hook guards every
+ * REST + WS request. The decorator + hook are added directly to the root app
+ * instance (no fastify-plugin wrapper needed) so they apply app-wide. The hook
+ * never throws past Fastify — auth failures are sent as a clean 401 JSON body
+ * and logged via `req.log`.
+ */
+import type { FastifyInstance } from "fastify";
+import type { AuthConfig } from "./config.js";
+/** The authenticated (or anonymous) principal attached to every request. */
+export interface AuthUser {
+    /** Stable identifier for the user (username / sub / email, per config). */
+    username: string;
+    /** Email, when the provider supplies one. */
+    email?: string;
+    /** Group / role memberships, when supplied. */
+    groups?: string[];
+    /** True for the synthetic principal used in `none` mode (no real identity). */
+    anonymous?: boolean;
+}
+declare module "fastify" {
+    interface FastifyRequest {
+        /**
+         * The authenticated principal. Always present once the auth plugin has run:
+         * a real user in trusted-header/jwt modes, or an anonymous principal in
+         * `none` mode.
+         */
+        user: AuthUser;
+    }
+}
+/**
+ * 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 declare const HEALTH_PATHS: ReadonlySet<string>;
+/**
+ * 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 declare function registerAuth(app: FastifyInstance, auth: AuthConfig): void;