@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/trigger-session.js

@@ -0,0 +1,122 @@
+/**
+ * TriggerSessionStore — a Paddock-side sidecar mapping an *accreting* trigger
+ * (`run.session: "resume"`) to the ONE chat session it owns (Epic T / T1). A trigger
+ * whose run declares `session: "resume"` should build up a single long-lived
+ * transcript across every fire (a "manager" that accretes context) rather than
+ * spawning a fresh chat each time. To make that resume unambiguous, Paddock records
+ * the session id the trigger created on its FIRST fire and reuses it thereafter — so
+ * the binding survives a server restart (the resume rebinds off the reloaded sidecar).
+ *
+ * This is the unified successor to `ScheduleSessionStore` (issue #265): the same
+ * pattern, keyed by (project slug, TRIGGER name) instead of schedule name, so both
+ * schedule-type and event-type triggers can own an accreting session. A
+ * `session: "new"` trigger owns nothing — it gets a new chat every fire and never
+ * touches this store.
+ *
+ * Shape + concurrency: a `"<slug>\0<triggerName>" -> sessionId` map persisted as a
+ * plain JSON object — the exact ArchiveStore / RunProvenanceStore / ScheduleSessionStore
+ * sidecar pattern (lazy-loaded, write-through, serialised, corruption-tolerant,
+ * `0o600`), INCLUDING the in-flight-load-promise fix: {@link ensureLoaded} caches the
+ * load PROMISE (not just the resolved map) so concurrent first-callers share ONE read
+ * and can't each build a separate map and race on the assignment (a lost update).
+ * Reachable if several triggers fire in the same tick right after boot.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_FILE = "trigger-sessions.json";
+/** The composite key separator — NUL can't appear in a slug or trigger name. */
+const SEP = "\0";
+/** A session id we're willing to key on — mirrors RunProvenanceStore's guard. */
+function isSafeId(sessionId) {
+    return typeof sessionId === "string" && /^[A-Za-z0-9._-]+$/.test(sessionId);
+}
+export class TriggerSessionStore {
+    stateFile;
+    /** In-memory map of `<slug>\0<triggerName>` -> owned sessionId. */
+    state = null;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read (the
+     * RunProvenanceStore fix): caching only the resolved `state` would let several
+     * fires that begin before the first `fs.readFile` resolves each build their own
+     * map and race on the assignment — a lost update.
+     */
+    loadPromise = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    static key(slug, triggerName) {
+        return `${slug}${SEP}${triggerName}`;
+    }
+    /** Load the persisted map (lazily, deduped; tolerant of a missing/corrupt file). */
+    ensureLoaded() {
+        if (this.state)
+            return Promise.resolve(this.state);
+        if (!this.loadPromise) {
+            this.loadPromise = (async () => {
+                const map = new Map();
+                try {
+                    const raw = await fs.readFile(this.stateFile, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        for (const [k, v] of Object.entries(parsed)) {
+                            if (typeof v === "string" && isSafeId(v))
+                                map.set(k, v);
+                        }
+                    }
+                }
+                catch {
+                    /* missing or unreadable — start empty */
+                }
+                this.state = map;
+                return map;
+            })();
+        }
+        return this.loadPromise;
+    }
+    /** The session id this trigger owns, or undefined if it hasn't fired yet. Non-throwing. */
+    async get(slug, triggerName) {
+        const map = await this.ensureLoaded().catch(() => new Map());
+        return map.get(TriggerSessionStore.key(slug, triggerName));
+    }
+    /**
+     * Record the session a trigger owns (its first-fire chat). Idempotent for the same
+     * id; an unsafe/blank id is ignored. Overwrites if called again (used only on a
+     * fresh first fire, or to re-point after a stale id was cleared).
+     */
+    async set(slug, triggerName, sessionId) {
+        if (!isSafeId(sessionId))
+            return;
+        const key = TriggerSessionStore.key(slug, triggerName);
+        const map = await this.ensureLoaded();
+        if (map.get(key) === sessionId)
+            return; // no-op
+        map.set(key, sessionId);
+        await this.persist(map);
+    }
+    /**
+     * Forget a trigger's owned session — used when the recorded transcript has vanished
+     * (so the next fire re-creates one) or the trigger was removed. No-op if there was
+     * nothing recorded.
+     */
+    async clear(slug, triggerName) {
+        const key = TriggerSessionStore.key(slug, triggerName);
+        const map = await this.ensureLoaded();
+        if (!map.has(key))
+            return;
+        map.delete(key);
+        await this.persist(map);
+    }
+    /** Write-through, serialised so overlapping writes can't corrupt the file. */
+    persist(map) {
+        this.writing = this.writing.then(async () => {
+            const obj = {};
+            for (const [k, v] of map)
+                obj[k] = v;
+            const json = JSON.stringify(obj, null, 2);
+            await fs.writeFile(this.stateFile, json, { encoding: "utf8", mode: 0o600 }).catch(() => undefined);
+        });
+        return this.writing;
+    }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Unified trigger CRUD/registry service (Epic T "Unify Triggers", ticket T1).
+ *
+ * ONE registry over the single `startAgentTurn` execution core that subsumes what
+ * were two services — the Epic G `HookService` (event hooks) and the Epic D schedule
+ * registration (spread across `ProjectStore` + `HerdctlService`). A trigger is
+ * persisted per project (`project.yaml` `triggers` map) and armed against herdctl by
+ * type:
+ *
+ *   - **event** trigger → its OWN herdctl agent `trigger-<slug>-<name>` (tool config
+ *     = capability), fired by the in-process event bus (`onArchive` today).
+ *   - **schedule** trigger → forwarded into the keeper agent's `schedules` block (the
+ *     herdctl cron engine arms it — the cron TIMING), fired via
+ *     `setScheduleTriggerHandler`. It executes on its OWN scoped `trigger-<slug>-<name>`
+ *     agent (tool config = capability) when it declares a `run.tools` allow-list (T2 —
+ *     #307), else on the keeper with the project-agent default toolset.
+ *   - **webhook** trigger → shape reserved; persisted + validated but NOT armed and
+ *     never fired (the ingress is the deferred T6/#311).
+ *
+ * The service is the FROZEN surface T2–T5 build on (the analogue of the shipped
+ * `HookService`): reads come straight off the live project record (project.yaml is the
+ * source of truth, re-armed on restart); writes persist THEN arm (best-effort — a
+ * transient fleet hiccup never loses the persisted definition, it's re-armed from the
+ * record on the next boot / `ensureProjectAgent`).
+ */
+import type { ProjectStore } from "./projects.js";
+import type { HerdctlService } from "./herdctl.js";
+import type { PaddockTrigger, TriggerDto, TriggerEvent } from "./trigger-config.js";
+/** Project a persisted {@link PaddockTrigger} + its name/slug onto the {@link TriggerDto}. */
+export declare function toTriggerDto(slug: string, name: string, trigger: PaddockTrigger): TriggerDto;
+/**
+ * List/get/set/remove a project's triggers — the frozen surface T2 (schedule tool
+ * allow-list), T3 (REST + self-MCP verb collapse), T4 (Triggers tab) and T5 (sweeper
+ * fold-in) build on. Reads come off the live project record; writes persist THEN arm
+ * the trigger's herdctl agent / schedule.
+ */
+export declare class TriggerService {
+    private readonly projects;
+    private readonly herdctl;
+    constructor(projects: ProjectStore, herdctl: HerdctlService);
+    /** Every trigger declared by `slug`, as DTOs (empty when the project has none). */
+    list(slug: string): Promise<TriggerDto[]>;
+    /** One trigger by name, or `null` if the project declares no such trigger. */
+    get(slug: string, name: string): Promise<TriggerDto | null>;
+    /**
+     * The trigger whose registered agent is `agentName` (`trigger-<slug>-<name>`), or
+     * `null` — the reverse-map (mirrors `HookService.getByAgentName`). Resolved by
+     * matching the project's DECLARED triggers rather than by PARSING the agent string
+     * (a slug may contain hyphens, so `trigger-<slug>-<name>` isn't unambiguously
+     * splittable). Never throws (a missing project → `null`).
+     */
+    getByAgentName(slug: string, agentName: string): Promise<TriggerDto | null>;
+    /**
+     * Create or update a trigger: persist it to `project.yaml` (validates the name +
+     * sanitises the record via the Zod schema, throwing `ProjectError` on a malformed
+     * trigger), then arm it so it's immediately fireable. Returns the persisted
+     * trigger's DTO. The arm is best-effort — re-armed from the record on the next
+     * restart / `ensureProjectAgent` if it fails — so a transient fleet hiccup never
+     * loses the persisted definition.
+     */
+    set(slug: string, name: string, trigger: unknown): Promise<TriggerDto>;
+    /**
+     * Remove a trigger: delete it from `project.yaml` and unregister/disarm it. Returns
+     * whether a trigger actually existed (so a caller can echo `removed: false`).
+     */
+    remove(slug: string, name: string): Promise<boolean>;
+    /**
+     * The enabled EVENT triggers a project declares for `event` (the dispatcher's
+     * resolver — the analogue of `HookService.enabledForEvent`). Schedule/webhook
+     * triggers are never returned here (they fire on cron / an ingress, not the bus).
+     */
+    enabledForEvent(slug: string, event: TriggerEvent): Promise<TriggerDto[]>;
+    /**
+     * Arm a single trigger against herdctl (best-effort): an event trigger becomes its
+     * own `trigger-<slug>-<name>` agent; a schedule trigger is (re-)forwarded into the
+     * keeper's `schedules` block via a keeper re-register — which ALSO registers its OWN
+     * scoped `trigger-<slug>-<name>` agent when it declares a `run.tools` allow-list (T2,
+     * via `ensureProjectAgent` → `registerTriggerAgents`); a webhook trigger is reserved
+     * (nothing to arm — no ingress in T1).
+     */
+    private arm;
+    private dtosOf;
+}

package/packages/server/dist/triggers.js

@@ -0,0 +1,124 @@
+import { triggerAgentName } from "./herdctl.js";
+import { triggerRunsOnOwnAgent } from "./trigger-config.js";
+/** Project a persisted {@link PaddockTrigger} + its name/slug onto the {@link TriggerDto}. */
+export function toTriggerDto(slug, name, trigger) {
+    return { name, agentName: triggerAgentName(slug, name), ...trigger };
+}
+/**
+ * List/get/set/remove a project's triggers — the frozen surface T2 (schedule tool
+ * allow-list), T3 (REST + self-MCP verb collapse), T4 (Triggers tab) and T5 (sweeper
+ * fold-in) build on. Reads come off the live project record; writes persist THEN arm
+ * the trigger's herdctl agent / schedule.
+ */
+export class TriggerService {
+    projects;
+    herdctl;
+    constructor(projects, herdctl) {
+        this.projects = projects;
+        this.herdctl = herdctl;
+    }
+    /** Every trigger declared by `slug`, as DTOs (empty when the project has none). */
+    async list(slug) {
+        const project = await this.projects.get(slug); // throws not_found
+        return this.dtosOf(project);
+    }
+    /** One trigger by name, or `null` if the project declares no such trigger. */
+    async get(slug, name) {
+        const project = await this.projects.get(slug); // throws not_found
+        const trigger = project.triggers?.[name];
+        return trigger ? toTriggerDto(slug, name, trigger) : null;
+    }
+    /**
+     * The trigger whose registered agent is `agentName` (`trigger-<slug>-<name>`), or
+     * `null` — the reverse-map (mirrors `HookService.getByAgentName`). Resolved by
+     * matching the project's DECLARED triggers rather than by PARSING the agent string
+     * (a slug may contain hyphens, so `trigger-<slug>-<name>` isn't unambiguously
+     * splittable). Never throws (a missing project → `null`).
+     */
+    async getByAgentName(slug, agentName) {
+        const project = await this.projects.get(slug).catch(() => null);
+        if (!project)
+            return null;
+        for (const [name, trigger] of Object.entries(project.triggers ?? {})) {
+            if (triggerAgentName(slug, name) === agentName)
+                return toTriggerDto(slug, name, trigger);
+        }
+        return null;
+    }
+    /**
+     * Create or update a trigger: persist it to `project.yaml` (validates the name +
+     * sanitises the record via the Zod schema, throwing `ProjectError` on a malformed
+     * trigger), then arm it so it's immediately fireable. Returns the persisted
+     * trigger's DTO. The arm is best-effort — re-armed from the record on the next
+     * restart / `ensureProjectAgent` if it fails — so a transient fleet hiccup never
+     * loses the persisted definition.
+     */
+    async set(slug, name, trigger) {
+        const project = await this.projects.setTrigger(slug, name, trigger);
+        const rec = project.triggers?.[name];
+        if (!rec)
+            throw new Error(`trigger not persisted: ${name}`);
+        await this.arm(project, name, rec).catch(() => undefined);
+        return toTriggerDto(slug, name, rec);
+    }
+    /**
+     * Remove a trigger: delete it from `project.yaml` and unregister/disarm it. Returns
+     * whether a trigger actually existed (so a caller can echo `removed: false`).
+     */
+    async remove(slug, name) {
+        const before = await this.projects.get(slug); // throws not_found
+        const existed = Boolean(before.triggers?.[name]);
+        const rec = before.triggers?.[name];
+        const project = await this.projects.removeTrigger(slug, name);
+        if (rec) {
+            // Tear down the trigger's OWN scoped agent only if it HAD one — every event
+            // trigger, or a scoped schedule trigger with a `run.tools` allow-list (T2). An
+            // unscoped, keeper-run schedule never registered an agent, so skip the fleet call.
+            if (triggerRunsOnOwnAgent(rec)) {
+                await this.herdctl.removeTriggerAgent(slug, name).catch(() => undefined);
+            }
+            // A schedule trigger ALSO rode the keeper's forwarded `schedules` block (the cron
+            // timing) — re-register the keeper from the updated record so that arming is
+            // dropped (and any remaining scoped trigger agents are re-affirmed).
+            if (rec.trigger.type === "schedule") {
+                await this.herdctl.ensureProjectAgent(project).catch(() => undefined);
+            }
+        }
+        return existed;
+    }
+    /**
+     * The enabled EVENT triggers a project declares for `event` (the dispatcher's
+     * resolver — the analogue of `HookService.enabledForEvent`). Schedule/webhook
+     * triggers are never returned here (they fire on cron / an ingress, not the bus).
+     */
+    async enabledForEvent(slug, event) {
+        const project = await this.projects.get(slug).catch(() => null);
+        if (!project)
+            return [];
+        return this.dtosOf(project).filter((t) => t.trigger.type === "event" && t.trigger.on === event && t.enabled === true);
+    }
+    /**
+     * Arm a single trigger against herdctl (best-effort): an event trigger becomes its
+     * own `trigger-<slug>-<name>` agent; a schedule trigger is (re-)forwarded into the
+     * keeper's `schedules` block via a keeper re-register — which ALSO registers its OWN
+     * scoped `trigger-<slug>-<name>` agent when it declares a `run.tools` allow-list (T2,
+     * via `ensureProjectAgent` → `registerTriggerAgents`); a webhook trigger is reserved
+     * (nothing to arm — no ingress in T1).
+     */
+    async arm(project, name, trigger) {
+        if (trigger.trigger.type === "event") {
+            await this.herdctl.ensureTriggerAgent(project, name, trigger);
+        }
+        else if (trigger.trigger.type === "schedule") {
+            // Re-register the keeper so its forwarded `schedules` block picks up the new /
+            // edited schedule trigger (un-gated). ensureProjectAgent
+            // also re-runs registerTriggerAgents, so a scoped schedule (T2) gets its own agent
+            // armed here too. Idempotent.
+            await this.herdctl.ensureProjectAgent(project);
+        }
+        // webhook: shape reserved — nothing armed (deferred T6).
+    }
+    dtosOf(project) {
+        return Object.entries(project.triggers ?? {}).map(([name, trigger]) => toTriggerDto(project.slug, name, trigger));
+    }
+}

package/packages/server/dist/trusted-proxy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The compatibility default: loopback plus the private address space. See the
+ * module header for why this is the default and what it does not prove.
+ */
+export declare const DEFAULT_TRUSTED_PROXIES: readonly string[];
+/** Believe no peer at all — the strict posture. */
+export declare const TRUST_NONE = "none";
+/** Believe every peer — restores the pre-#474 behaviour. Reported loudly. */
+export declare const TRUST_ALL = "all";
+/** A resolved trust list plus how we came by it. */
+export interface TrustedProxies {
+    /**
+     * The entries as configured (already validated). Empty means "believe no
+     * peer". `["all"]` means "believe every peer".
+     */
+    entries: string[];
+    /**
+     * True when the operator named these peers (env or YAML), false when this is
+     * {@link DEFAULT_TRUSTED_PROXIES}. Only an explicit list is a control, so the
+     * guard warns when a forwarded scheme is believed under the default.
+     */
+    explicit: boolean;
+}
+/** The default list, wrapped. */
+export declare function defaultTrustedProxies(): TrustedProxies;
+export interface ParsedTrustedProxies {
+    trusted: TrustedProxies;
+    /** Entries that were dropped because they are not an IP, CIDR, or preset. */
+    errors: string[];
+    /** Advice worth logging at boot (currently: `all` disables the guard). */
+    warnings: string[];
+}
+/**
+ * Parse an operator-supplied list (a YAML array, or a comma/newline-delimited
+ * string) into a validated trust list.
+ *
+ * An unparseable entry is DROPPED with an error rather than taking the instance
+ * down — one typo in a CIDR must not stop Paddock booting. Note the direction of
+ * that failure: dropping an entry can only make the guard stricter (a peer stops
+ * being trusted), never more permissive, so the fail-safe way is also the safe
+ * way here.
+ *
+ * `undefined` / empty input means "the operator said nothing" and yields the
+ * default list; an explicit `none` yields an empty, explicit list.
+ */
+export declare function parseTrustedProxies(raw: string[] | string | undefined): ParsedTrustedProxies;
+/**
+ * Whether `addr` — the IMMEDIATE peer from the socket, never a header — is a
+ * trusted proxy. An unknown/absent address is never trusted.
+ */
+export declare function isTrustedProxy(addr: string | undefined, trusted: TrustedProxies): boolean;
+/**
+ * Whether `addr` is a loopback socket address — the client is on this host, so
+ * nothing was put on a wire. Covers IPv4 `127.0.0.0/8`, IPv6 `::1`, and the
+ * IPv4-mapped form Node reports on a dual-stack listener.
+ */
+export declare function isLoopbackAddress(addr: string | undefined): boolean;

package/packages/server/dist/trusted-proxy.js

@@ -0,0 +1,157 @@
+/**
+ * Which peers' `X-Forwarded-Proto` the `/mcp` transport guard believes (#474).
+ *
+ * #471 gave the Management API a plaintext guard: a bearer token must not cross
+ * a real network readable-in-transit, so `/mcp` refuses plaintext from anything
+ * but a loopback client. It also accepted `X-Forwarded-Proto: https` — from ANY
+ * peer, with no trust check — so the guard could be switched off by the very
+ * operator it protects, with a header copy-pasted out of a smoke-test recipe.
+ *
+ * ── What this is and is not ────────────────────────────────────────────────
+ * NOT an authentication control. A valid bearer token is still required, and an
+ * attacker who spoofs the header gains nothing they could not already do — they
+ * still need the credential. What the header could do was mislead an OPERATOR
+ * into believing their token was protected while it travelled in clear. So the
+ * job here is to make the "is this connection secure?" answer rest on something
+ * the caller cannot set: the immediate peer's address, taken from the socket.
+ *
+ * ── The trust list ─────────────────────────────────────────────────────────
+ * A forwarded scheme is believed only from a peer in the trusted list. Entries
+ * are IPs, CIDRs, or the {@link proxyAddr} preset names (`loopback`,
+ * `linklocal`, `uniquelocal`), plus two words of our own: `none` (believe no
+ * peer) and `all` (believe everyone — the pre-#474 behaviour, reportable and
+ * loud).
+ *
+ * The DEFAULT is {@link DEFAULT_TRUSTED_PROXIES}: loopback + link-local +
+ * unique-local (RFC1918 / fc00::/7 / fe80::/10). That is a COMPATIBILITY
+ * posture, chosen because in every deployment recipe the TLS terminator sits on
+ * the host or on a private container/pod network — an nginx or Caddy sidecar on
+ * a Compose bridge, an ingress in a pod network, a proxy on loopback. A peer
+ * with a PUBLIC address is never one of those, so believing it is always wrong;
+ * that case is now refused where it previously succeeded.
+ *
+ * The default's honest limit: it cannot tell your reverse proxy at 172.18.0.5
+ * from a laptop at 192.168.1.50, because nothing in an IP packet says which one
+ * is a proxy. Naming the proxy explicitly is what upgrades this from a footgun
+ * preventer to a control, and the guard says so at runtime — believing a
+ * forwarded scheme under the default list logs a one-per-peer warning.
+ *
+ * Deliberately NOT loopback-equivalent: the Docker bridge gateway (`172.17.0.1`).
+ * A request from another host to a `0.0.0.0`-published port is SNAT'd to that
+ * same address, so "peer is the gateway" does not prove the traffic stayed on
+ * the box. Smoke-test from INSIDE the container instead (`docker compose exec
+ * paddock curl http://127.0.0.1:4000/mcp …`), where the peer really is loopback.
+ */
+import proxyAddr from "proxy-addr";
+/**
+ * The compatibility default: loopback plus the private address space. See the
+ * module header for why this is the default and what it does not prove.
+ */
+export const DEFAULT_TRUSTED_PROXIES = ["loopback", "linklocal", "uniquelocal"];
+/** Believe no peer at all — the strict posture. */
+export const TRUST_NONE = "none";
+/** Believe every peer — restores the pre-#474 behaviour. Reported loudly. */
+export const TRUST_ALL = "all";
+/** The default list, wrapped. */
+export function defaultTrustedProxies() {
+    return { entries: [...DEFAULT_TRUSTED_PROXIES], explicit: false };
+}
+/**
+ * Parse an operator-supplied list (a YAML array, or a comma/newline-delimited
+ * string) into a validated trust list.
+ *
+ * An unparseable entry is DROPPED with an error rather than taking the instance
+ * down — one typo in a CIDR must not stop Paddock booting. Note the direction of
+ * that failure: dropping an entry can only make the guard stricter (a peer stops
+ * being trusted), never more permissive, so the fail-safe way is also the safe
+ * way here.
+ *
+ * `undefined` / empty input means "the operator said nothing" and yields the
+ * default list; an explicit `none` yields an empty, explicit list.
+ */
+export function parseTrustedProxies(raw) {
+    const errors = [];
+    const warnings = [];
+    const tokens = (Array.isArray(raw)
+        ? raw.map((v) => String(v))
+        : String(raw ?? "")
+            .split(/[\n,]/)
+            .map((v) => v))
+        .map((v) => v.trim().toLowerCase())
+        .filter((v) => v.length > 0);
+    if (tokens.length === 0)
+        return { trusted: defaultTrustedProxies(), errors, warnings };
+    if (tokens.includes(TRUST_ALL) || tokens.includes("*")) {
+        warnings.push(`managementApi.trustedProxies: "all" — every peer's X-Forwarded-Proto is believed, so the ` +
+            `/mcp plaintext guard can be switched off by any client that can reach this instance. ` +
+            `This is the pre-#474 behaviour; name your proxy's address instead.`);
+        return {
+            trusted: { entries: [TRUST_ALL], explicit: true },
+            errors,
+            warnings,
+        };
+    }
+    const entries = [];
+    for (const token of tokens) {
+        if (token === TRUST_NONE)
+            continue; // an explicit empty list
+        try {
+            proxyAddr.compile([token]);
+            entries.push(token);
+        }
+        catch {
+            errors.push(`managementApi.trustedProxies: "${token}" is not an IP address, CIDR, or one of ` +
+                `loopback/linklocal/uniquelocal/none/all — entry ignored`);
+        }
+    }
+    return { trusted: { entries, explicit: true }, errors, warnings };
+}
+/**
+ * Compiled matchers, keyed by the joined list. `proxyAddr.compile` parses every
+ * entry, so we do it once per distinct list rather than once per request.
+ */
+const compiled = new Map();
+function matcherFor(entries) {
+    const key = entries.join(",");
+    let fn = compiled.get(key);
+    if (!fn) {
+        if (entries.length === 0) {
+            fn = () => false;
+        }
+        else if (entries.length === 1 && entries[0] === TRUST_ALL) {
+            fn = () => true;
+        }
+        else {
+            const trust = proxyAddr.compile(entries);
+            fn = (addr) => trust(addr, 0);
+        }
+        compiled.set(key, fn);
+    }
+    return fn;
+}
+/**
+ * Whether `addr` — the IMMEDIATE peer from the socket, never a header — is a
+ * trusted proxy. An unknown/absent address is never trusted.
+ */
+export function isTrustedProxy(addr, trusted) {
+    if (!addr)
+        return false;
+    try {
+        return matcherFor(trusted.entries)(addr);
+    }
+    catch {
+        // proxyAddr throws on an address it cannot parse (it should not happen for a
+        // real socket, but a malformed value must not 500 the request).
+        return false;
+    }
+}
+/**
+ * Whether `addr` is a loopback socket address — the client is on this host, so
+ * nothing was put on a wire. Covers IPv4 `127.0.0.0/8`, IPv6 `::1`, and the
+ * IPv4-mapped form Node reports on a dual-stack listener.
+ */
+export function isLoopbackAddress(addr) {
+    if (!addr)
+        return false;
+    return isTrustedProxy(addr, { entries: ["loopback"], explicit: false });
+}