@sigrun/sigrun 0.2.0 → 0.3.0

package/dist/server/auth/own-host.js

@@ -0,0 +1,115 @@
+/**
+ * The C5 own-host rule (proxy-trust Task 4b): a peer that IS this host —
+ * loopback (127.0.0.0/8, ::1) or any current interface address — can
+ * reach the server without traversing the forward-auth proxy, because
+ * every local process shares those source addresses. Trusting such a
+ * peer through a CIDR RANGE would let any local process impersonate
+ * users, so an own-host peer vouches only when:
+ *
+ *  1. the shared secret is configured (`secret` + `secretHeader`) — the
+ *     existing secret check then decides; or
+ *  2. that exact address is listed explicitly in `trustedProxies` (a
+ *     bare address, or a /32 (IPv4) / /128 (IPv6) entry) — an explicit
+ *     operator decision, which the boot warning surfaces.
+ *
+ * Otherwise both identity-trust paths (the request pipeline's proxy
+ * method and onboarding's `resolveProxyIdentity`) reject exactly the
+ * way an untrusted peer is rejected, with the OWN_HOST diagnostic.
+ */
+import { networkInterfaces } from "node:os";
+import { isIP } from "node:net";
+import { normalizePeerAddress } from "./ip.js";
+/** Interface addresses refresh at most this often (milliseconds). */
+const CACHE_TTL_MS = 30_000;
+let testAddresses;
+let cached;
+/** The seam override, or the real interface list (cached ≤ 30 s). */
+function ownHostAddresses() {
+    if (testAddresses !== undefined)
+        return testAddresses;
+    const now = Date.now();
+    if (cached === undefined || now - cached.readAt >= CACHE_TTL_MS) {
+        const addresses = [];
+        for (const entries of Object.values(networkInterfaces())) {
+            for (const entry of entries ?? [])
+                addresses.push(entry.address);
+        }
+        cached = { addresses, readAt: now };
+    }
+    return cached.addresses;
+}
+function isLoopback(address) {
+    if (address === "::1")
+        return true;
+    if (isIP(address) !== 4)
+        return false;
+    return address.split(".")[0] === "127";
+}
+/** Loopback (127.0.0.0/8, ::1) or any current interface address; `::ffff:` unwrapped. */
+export function isOwnHostAddress(address) {
+    if (address === undefined)
+        return false;
+    const candidate = normalizePeerAddress(address);
+    if (isLoopback(candidate))
+        return true;
+    return ownHostAddresses().some((entry) => normalizePeerAddress(entry) === candidate);
+}
+/** True when `address` is listed exactly in `cidrs`: a bare address, or a /32 (IPv4) or /128 (IPv6) entry for it. */
+export function listedExactly(address, cidrs) {
+    const candidate = normalizePeerAddress(address);
+    for (const raw of cidrs) {
+        const entry = raw.trim();
+        if (entry === "")
+            continue;
+        const slash = entry.indexOf("/");
+        if (slash === -1) {
+            if (normalizePeerAddress(entry) === candidate)
+                return true;
+            continue;
+        }
+        const base = normalizePeerAddress(entry.slice(0, slash));
+        if (base !== candidate)
+            continue;
+        const prefix = Number(entry.slice(slash + 1));
+        const family = isIP(candidate);
+        if (family === 4 && prefix === 32)
+            return true;
+        if (family === 6 && prefix === 128)
+            return true;
+    }
+    return false;
+}
+/** The C5 rule: false only for an own-host peer reached through a range with no shared secret configured. */
+export function ownHostPeerPermitted(address, trustedProxies, secretConfigured) {
+    if (!isOwnHostAddress(address))
+        return true;
+    if (secretConfigured)
+        return true;
+    return listedExactly(address, trustedProxies);
+}
+/** Test seam: replace the interface addresses (loopback stays implicit); `undefined` restores os.networkInterfaces(). */
+export function setOwnHostAddressesForTests(addresses) {
+    testAddresses = addresses;
+    cached = undefined;
+}
+/** Explicitly listed own-host entries (verbatim spellings), for the boot warning. */
+export function listedOwnHostEntries(trustedProxies) {
+    return trustedProxies.filter((entry) => {
+        const trimmed = entry.trim();
+        if (trimmed === "")
+            return false;
+        const slash = trimmed.indexOf("/");
+        const base = slash === -1 ? trimmed : trimmed.slice(0, slash);
+        if (slash !== -1) {
+            const prefix = Number(trimmed.slice(slash + 1));
+            const family = isIP(normalizePeerAddress(base));
+            if (family === 4 && prefix !== 32)
+                return false;
+            if (family === 6 && prefix !== 128)
+                return false;
+            if (family === 0)
+                return false;
+        }
+        return isOwnHostAddress(base);
+    });
+}

package/dist/server/auth/pipeline.js

@@ -34,16 +34,28 @@
  *     request before handlers run) + a non-empty user header; a
  *     directory miss auto-provisions (`source:"proxy"`, admin:false)
  *     unless `autoProvision:false` → 403 `user_not_provisioned`.
+ *     Every proxy rejection (401/403) emits ONE sanitized `warn` naming
+ *     the socket peer + a short reason (release-readiness Task 1, spec
+ *     §3 — never tokens, cookies, identity-header VALUES, query
+ *     strings, or the full URL; a request presenting a Bearer/cookie
+ *     credential is a token attempt and stays silent).
  *     `token`: Bearer or the `sigrun_session` cookie → `tokens.verify`;
- *     the token's user must exist in the directory, else 401.
+ *     the token's user must exist in the directory, else 401 (no log —
+ *     token failures are not proxy diagnostics).
  *  6. **Empty list** (the naive workstation path): the trimmed
- *     `X-Sigrun-User` header verbatim, `admin: true`, method `"none"`.
+ *     `X-Sigrun-User` header DERIVED to its canonical key (`admin: true`,
+ *     method `"none"`). An unusable header (no derivable key) is a loud
+ *     400 `invalid_username`; an absent header behaves as before.
  */
 import { timingSafeEqual } from "node:crypto";
 import { ipAllowed } from "./ip.js";
 import { isLoopbackHost } from "./loopback.js";
+import { listedOwnHostEntries, ownHostPeerPermitted } from "./own-host.js";
+import { ProxyRejectReason, warnProxyRejected } from "./proxy-diagnostic.js";
+import { resolveProxyUser } from "./proxy-identity.js";
 import { AdmissionRefusedError } from "../../harness/identity/users.js";
 import { effectiveAdmin } from "../../harness/identity/groups.js";
+import { deriveUsername } from "@sigrun/shared/usernames";
 /** One header read: Fastify headers may be string | string[]; first wins. */
 function headerOf(request, name) {
     const value = request.headers[name.toLowerCase()];
@@ -191,7 +203,34 @@ function isPublicPath(request, ctx) {
  */
 async function resolveProxy(request, ctx) {
     const { proxy, adminGroups } = ctx.config.auth;
+    // A request presenting a Bearer/cookie CREDENTIAL is attempting token
+    // auth (or riding the stage-3 service token), not claiming a proxy
+    // identity: when the token method is ALSO configured, suppress the
+    // rejection diagnostic — a denied credential is the token method's
+    // failure, which never logs (spec §3). The pipeline visits the proxy
+    // method FIRST for such a request (a trusted peer presenting a session
+    // without proxy headers is a legitimate client shape behind
+    // forward-auth), and a "missing secret" warn would fire even when the
+    // token then authenticates. In a PROXY-ONLY deployment the suppression
+    // does not apply: a rejected credential-bearing request there IS a
+    // proxy-method 401 and must log (spec §3 exempts token-auth failures,
+    // and no token method exists).
+    const attemptingToken = (bearerOf(request) !== undefined || sessionCookieOf(request) !== undefined) &&
+        ctx.methods.includes("token");
     if (!ipAllowed(request.socket.remoteAddress, proxy.trustedProxies)) {
+        if (!attemptingToken) {
+            warnProxyRejected(request, ProxyRejectReason.UNTRUSTED);
+        }
+        return { status: 401 };
+    }
+    // C5: an own-host peer (loopback or a local interface address) can
+    // originate from ANY local process, so trust through a range alone
+    // never vouches — the shared secret must be configured (its check
+    // then decides), or the exact address must be listed explicitly.
+    if (!ownHostPeerPermitted(request.socket.remoteAddress, proxy.trustedProxies, proxy.secret !== undefined && proxy.secretHeader !== undefined)) {
+        if (!attemptingToken) {
+            warnProxyRejected(request, ProxyRejectReason.OWN_HOST);
+        }
         return { status: 401 };
     }
     if (proxy.secret !== undefined && proxy.secretHeader !== undefined) {
@@ -199,41 +238,46 @@ async function resolveProxy(request, ctx) {
         const presented = headerOf(request, name);
         delete request.headers[name];
         if (presented === undefined || !timingSafeStringEqual(presented, proxy.secret)) {
+            if (!attemptingToken) {
+                warnProxyRejected(request, ProxyRejectReason.secretReason(proxy.secretHeader));
+            }
             return { status: 401 };
         }
     }
     const user = headerOf(request, proxy.userHeader);
-    if (user === undefined)
+    if (user === undefined) {
+        if (!attemptingToken) {
+            warnProxyRejected(request, ProxyRejectReason.missingHeaderReason(proxy.userHeader));
+        }
         return { status: 401 };
+    }
     const groups = headerOf(request, proxy.groupsHeader)
         ?.split(",")
         .map((group) => group.trim())
         .filter((group) => group !== "") ?? [];
-    const { users } = ctx.opened.identity;
-    // The invalid-username case (a proxy header that can't be a directory
-    // user) is a loud 403, not a 500: the proxy vouched for an identity
-    // this server can never represent.
-    if (!/^[a-z0-9][a-z0-9._-]*$/.test(user)) {
-        return { status: 403, error: "invalid_username" };
-    }
-    const existing = users.get(user);
-    if (existing === undefined && !proxy.autoProvision) {
-        return { status: 403, error: "user_not_provisioned" };
-    }
+    const { users, accounts } = ctx.opened.identity;
     let record;
     try {
-        record = existing ??
-            (await users.add({
-                user,
-                ...(headerOf(request, proxy.nameHeader) === undefined
-                    ? {}
-                    : { name: headerOf(request, proxy.nameHeader) }),
-                ...(headerOf(request, proxy.emailHeader) === undefined
-                    ? {}
-                    : { email: headerOf(request, proxy.emailHeader) }),
-                admin: false,
-                source: "proxy",
-            }));
+        const resolved = await resolveProxyUser({ users, accounts }, user, {
+            ...(headerOf(request, proxy.nameHeader) === undefined
+                ? {}
+                : { name: headerOf(request, proxy.nameHeader) }),
+            ...(headerOf(request, proxy.emailHeader) === undefined
+                ? {}
+                : { email: headerOf(request, proxy.emailHeader) }),
+        }, { provision: proxy.autoProvision });
+        // The invalid-username case is a loud 403, not a 500: the proxy
+        // vouched for an identity this server can never represent. The warn
+        // never carries the claimed value (spec §3).
+        if (resolved.kind === "invalid") {
+            warnProxyRejected(request, ProxyRejectReason.UNUSABLE);
+            return { status: 403, error: "invalid_username" };
+        }
+        if (resolved.kind === "not_provisioned") {
+            warnProxyRejected(request, ProxyRejectReason.UNTRUSTED_IDENTITY_SOURCE);
+            return { status: 403, error: "user_not_provisioned" };
+        }
+        record = resolved.record;
     }
     catch (error) {
         if (error instanceof AdmissionRefusedError) {
@@ -245,7 +289,7 @@ async function resolveProxy(request, ctx) {
     // setGroups avoids the write when the values are unchanged. Effective
     // admin is computed over the UPDATED record, so a group exit revokes
     // the request's grant immediately and host-side checks agree.
-    record = await users.setGroups(user, "proxy", groups);
+    record = await users.setGroups(record.user, "proxy", groups);
     return {
         user: record.user,
         ...(record.name === undefined ? {} : { name: record.name }),
@@ -283,6 +327,18 @@ export function resolveToken(request, ctx) {
 }
 /** The ONE request hook. Stages 1→5 in brief order; a stage replies or falls through. */
 export function registerAuthPipeline(app, ctx) {
+    // C5 boot warning: an explicitly listed own-host trust entry WITHOUT
+    // a shared secret is the one shape where a local process can still
+    // impersonate users by connecting directly. Surface it once per
+    // entry, at registration (a boot-time config warning, not a request
+    // diagnostic — the throttled warnProxyRejected does not apply).
+    const { proxy } = ctx.config.auth;
+    if (ctx.methods.includes("proxy") &&
+        !(proxy.secret !== undefined && proxy.secretHeader !== undefined)) {
+        for (const entry of listedOwnHostEntries(proxy.trustedProxies)) {
+            console.warn(`sigrun: trusting local address ${entry} without a shared secret lets any local process impersonate users; set server.auth.proxy.secretHeader`);
+        }
+    }
     app.addHook("onRequest", async (request, reply) => {
         // Stage 1: Host + Origin.
         const hostStatus = checkHost(request, ctx);
@@ -329,8 +385,17 @@ export function registerAuthPipeline(app, ctx) {
         // Stage 5/6: the configured methods, in order; the empty list is
         // the naive loopback path.
         if (ctx.methods.length === 0) {
+            const header = headerOf(request, "x-sigrun-user");
+            // The header is an unchecked (operator-typed) source: derive the
+            // canonical key on receipt, the same rule the CLI applies before
+            // sending. An unusable value is a loud 400, never a verbatim
+            // identity; an absent header keeps today's ownerless behavior.
+            const user = header === undefined ? undefined : deriveUsername(header);
+            if (header !== undefined && user === undefined) {
+                return await reply.code(400).send({ error: "invalid_username" });
+            }
             request.principal = {
-                user: headerOf(request, "x-sigrun-user"),
+                user,
                 admin: true,
                 service: false,
                 method: "none",

package/dist/server/auth/proxy-diagnostic.js

@@ -0,0 +1,60 @@
+/**
+ * The shared proxy-auth rejection diagnostic (proxy-trust C1), extracted
+ * from the request pipeline so the onboarding routes can report WHY they
+ * rejected a proxy identity with the same line and redaction contract.
+ *
+ * ONE `warn` per rejected request, naming the socket peer, the request
+ * method, a short reason, and — only when Fastify already resolved it —
+ * the ROUTE TEMPLATE (`routeOptions.url`, never the raw URL). The line
+ * must never carry API tokens, cookies, identity-header VALUES, query
+ * strings, or the full request URL; a header NAME appears only where the
+ * reason itself is "that configured header was absent/wrong" (its value
+ * never does). This is diagnostic logging, not evidence that the
+ * configured allowlist is correct.
+ *
+ * The throttle is per reason: one line per reason per 60 s, with a
+ * `(N suppressed)` suffix on the next emitted line for that reason —
+ * a flood of identical rejections cannot drown the log, and a DIFFERENT
+ * reason always emits immediately.
+ */
+/** One line per reason per this window; suppressed lines count up. */
+const THROTTLE_MS = 60_000;
+/** The reason vocabulary (byte-identical to the pipeline's originals). */
+export const ProxyRejectReason = {
+    UNTRUSTED: "untrusted proxy",
+    UNUSABLE: "unusable identity claim",
+    UNTRUSTED_IDENTITY_SOURCE: "untrusted identity source",
+    OWN_HOST: "own-host peer without shared secret",
+    secretReason: (header) => `missing or wrong shared secret (${header} header)`,
+    missingHeaderReason: (header) => `missing identity header (${header})`,
+};
+const throttle = new Map();
+let clock = () => Date.now();
+/** Test seam: inject the clock the throttle reads. */
+export function setProxyDiagnosticClock(now) {
+    clock = now;
+}
+/** Test seam: forget all throttle state (and restore the real clock). */
+export function resetProxyDiagnostic() {
+    throttle.clear();
+    clock = () => Date.now();
+}
+/**
+ * Emit one sanitized rejection line, throttled per reason. The line
+ * carries no values by construction: it is built from the method, the
+ * socket peer, the caller-supplied reason (a fixed string, or one naming
+ * a configured header), and the route template.
+ */
+export function warnProxyRejected(request, reason) {
+    const now = clock();
+    const entry = throttle.get(reason);
+    if (entry !== undefined && now - entry.lastEmit < THROTTLE_MS) {
+        entry.suppressed += 1;
+        return;
+    }
+    const suppressed = entry?.suppressed ?? 0;
+    throttle.set(reason, { lastEmit: now, suppressed: 0 });
+    const peer = request.socket.remoteAddress ?? "unknown";
+    const route = request.routeOptions.url;
+    console.warn(`sigrun: proxy auth rejected ${request.method} request from ${peer} (${reason})${route === undefined ? "" : ` on ${route}`}${suppressed > 0 ? ` (${suppressed} suppressed)` : ""}`);
+}

package/dist/server/auth/proxy-identity.js

@@ -0,0 +1,134 @@
+/**
+ * Proxy identity resolution (username-derivation D3): a trusted proxy
+ * header names an external subject, not necessarily a directory key.
+ * Folded subjects are linked to users; case variants of an existing key
+ * adopt it, and every other new identity gets a derived, suffixed key.
+ *
+ * The request pipeline owns trust and diagnostics. The claim route owns
+ * its lock; only the pipeline entry below acquires `withClaimLock`.
+ */
+import { deriveUsername, foldSubject, isUsernameKey, withSuffix, } from "@sigrun/shared/usernames";
+import { AccountLinkConflictError, } from "../../harness/identity/accounts.js";
+import { withClaimLock } from "./claim-lock.js";
+function identityParts(header) {
+    const subject = foldSubject(header);
+    const base = deriveUsername(header);
+    if (subject.length > 512 || base === undefined)
+        return undefined;
+    return { subject, base };
+}
+function linkedUser(deps, subject) {
+    const link = deps.accounts.lookup("proxy", subject);
+    return link === undefined ? undefined : deps.users.get(link.user);
+}
+function isAddConflict(error) {
+    return error instanceof Error && /^user ".*" already exists$/.test(error.message);
+}
+/** Lock-free resolution body; conflicts become a signal for the pipeline's retry. */
+async function provisionAttempt(deps, header, profile, opts) {
+    const parts = identityParts(header);
+    if (parts === undefined)
+        return { kind: "invalid" };
+    const linked = linkedUser(deps, parts.subject);
+    if (linked !== undefined)
+        return { kind: "user", record: linked };
+    if (isUsernameKey(parts.subject)) {
+        const existing = deps.users.get(parts.subject);
+        if (existing !== undefined) {
+            try {
+                await deps.accounts.link({
+                    provider: "proxy",
+                    subject: parts.subject,
+                    user: existing.user,
+                    via: "proxy",
+                });
+                return { kind: "user", record: existing };
+            }
+            catch (error) {
+                if (error instanceof AccountLinkConflictError)
+                    return { kind: "retry", error };
+                throw error;
+            }
+        }
+    }
+    if (!opts.provision)
+        return { kind: "not_provisioned" };
+    const key = withSuffix(parts.base, (candidate) => deps.users.get(candidate) !== undefined);
+    try {
+        const record = await deps.users.add({
+            user: key,
+            ...(profile.name === undefined ? {} : { name: profile.name }),
+            ...(profile.email === undefined ? {} : { email: profile.email }),
+            admin: opts.admin ?? false,
+            source: "proxy",
+        });
+        try {
+            await deps.accounts.link({
+                provider: "proxy",
+                subject: parts.subject,
+                user: record.user,
+                via: "proxy",
+            });
+            return { kind: "user", record };
+        }
+        catch (error) {
+            if (error instanceof AccountLinkConflictError) {
+                // Never leave the user created by this attempt attached to no
+                // identity when the link itself was refused.
+                await deps.users.remove(record.user);
+                return { kind: "retry", error };
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        if (isAddConflict(error))
+            return { kind: "retry", error: error };
+        throw error;
+    }
+}
+/** One lookup/lock pass. A retry is observed only AFTER the lock returns. */
+async function resolveOnce(deps, header, profile, opts) {
+    const parts = identityParts(header);
+    if (parts === undefined)
+        return { kind: "invalid" };
+    const linked = linkedUser(deps, parts.subject);
+    if (linked !== undefined)
+        return { kind: "user", record: linked };
+    return await withClaimLock(() => provisionAttempt(deps, header, profile, opts));
+}
+/** Pipeline entry: lookup outside the lock; on a miss, provision under it. */
+export async function resolveProxyUser(deps, header, profile, opts) {
+    const first = await resolveOnce(deps, header, profile, opts);
+    if (first.kind !== "retry")
+        return first;
+    // A second-process conflict retries resolution once, after the claim
+    // section has returned. A second conflict is a real failure, not a loop.
+    const second = await resolveOnce(deps, header, profile, opts);
+    if (second.kind === "retry")
+        throw second.error;
+    return second;
+}
+/** Lock-free body. Callers MUST already hold `withClaimLock`. */
+export async function provisionProxyUser(deps, header, profile, opts) {
+    const result = await provisionAttempt(deps, header, profile, opts);
+    if (result.kind === "retry")
+        throw result.error;
+    return result;
+}
+/** Read-only key computation for an already-vouched header. */
+export function previewProxyUser(deps, header) {
+    const parts = identityParts(header);
+    if (parts === undefined)
+        return undefined;
+    const linked = linkedUser(deps, parts.subject);
+    if (linked !== undefined)
+        return { user: linked.user, subject: header };
+    if (isUsernameKey(parts.subject) && deps.users.get(parts.subject) !== undefined) {
+        return { user: parts.subject, subject: header };
+    }
+    return {
+        user: withSuffix(parts.base, (candidate) => deps.users.get(candidate) !== undefined),
+        subject: header,
+    };
+}

package/dist/server/auth/proxy-only.js

@@ -0,0 +1,28 @@
+/**
+ * The C2 vouch rule for account-creating public paths (proxy-trust
+ * onboarding, spec Task 4): a proxy-only server bound beyond loopback
+ * admits accounts ONLY through a trusted proxy vouch. On such a boot
+ * every unvouched account-creating public path — the onboarding claim
+ * (setup-code and invite branches alike) and the login code-resume —
+ * refuses with 403 `proxy_identity_required`, and boot never mints or
+ * logs a setup code (it would be an unvouched account-creation path).
+ *
+ * The rule is deliberately about the CONFIGURED posture, not the
+ * request: the login code-resume has no proxy identity at all, so under
+ * `requiresProxyVouch` it always refuses. Mixed `[proxy, token]`
+ * deployments keep the setup-code/invite paths (token callers exist),
+ * and loopback binds keep them too (loopback is its own trust).
+ */
+import { isLoopbackHost } from "./loopback.js";
+/** Whether the configured auth methods are exactly proxy-only. */
+export function isProxyOnly(methods) {
+    return methods.includes("proxy") && !methods.includes("token");
+}
+/**
+ * Whether this boot requires a proxy vouch for account creation:
+ * proxy-only AND bound beyond loopback. The loopback test is the shared
+ * one (`127.0.0.0/8`, `::1`, `localhost`; `::ffff:127.*` unwrapped).
+ */
+export function requiresProxyVouch(methods, listenHost) {
+    return isProxyOnly(methods) && !isLoopbackHost(listenHost);
+}

package/dist/server/images/cache.js

@@ -8,8 +8,8 @@
  * only).
  *
  * Layout: each entry is one file `<sha256(u)>.<variant>` beside ONE
- * `index.json` (the metadata table: type, size, added-at, last-hit,
- * pin). The index is written atomically on every mutation, so a re-open
+ * `index.json` (the metadata table: type, size, added-at, clamped
+ * max-age, last-hit, pin). The index is written atomically on every mutation, so a re-open
  * (the same cache dir, a new process) serves the prior entries.
  *
  * Eviction never deletes a file currently being STREAMED or WRITTEN
@@ -74,7 +74,8 @@ export class ImageCache {
             return;
         }
         for (const [key, entry] of Object.entries(parsed.entries)) {
-            this.entries.set(key, { ...entry, pins: 0 });
+            // Pre-max-age indexes used the original default: one hour.
+            this.entries.set(key, { ...entry, maxAge: entry.maxAge ?? 3600, pins: 0 });
         }
     }
     /** One hit, or `undefined` on a miss. `now` stamps the LRU order. */
@@ -99,12 +100,17 @@ export class ImageCache {
         entry.pins += 1;
         await this.persist();
         const stream = createReadStream(file);
+        let unpinned = false;
         const unpin = () => {
+            // Node emits close after error: one hit releases one pin.
+            if (unpinned)
+                return;
+            unpinned = true;
             entry.pins -= 1;
         };
         stream.once("close", unpin);
         stream.once("error", unpin);
-        return { type: entry.type, stream };
+        return { type: entry.type, addedAt: entry.addedAt, maxAge: entry.maxAge, stream };
     }
     /**
      * Store one fetched image. The write is staged and renamed (atomic:
@@ -112,7 +118,7 @@ export class ImageCache {
      * is pinned for the write's duration — the eviction pass a same-key
      * overwrite triggers can never remove the file mid-rename.
      */
-    async put(u, variant, type, body, now) {
+    async put(u, variant, type, body, now, maxAge = 3600) {
         await this.open();
         if (this.closed)
             return;
@@ -122,6 +128,7 @@ export class ImageCache {
             type,
             size: body.byteLength,
             addedAt: at,
+            maxAge,
             lastHit: at,
             pins: 1,
         };
@@ -180,6 +187,7 @@ export class ImageCache {
                     type: entry.type,
                     size: entry.size,
                     addedAt: entry.addedAt,
+                    maxAge: entry.maxAge,
                     lastHit: entry.lastHit,
                 },
             ])),

package/dist/server/index.js

@@ -93,8 +93,9 @@ import { resolveWebuiBundle, serveWebuiBundle, } from "./static.js";
  * then the configured methods — the resolved principal stamps
  * `SessionMeta.owner` at create/fork/import.
  * @param options.listenHost the host the server will bind (fallback
- * `"0.0.0.0"` when omitted; `serve()` passes the dual-stack `::`);
- * the pipeline's Host check and the default method list
+ * `"0.0.0.0"` when omitted; `serve()` passes its ONE resolved host —
+ * `options.host` → `SIGRUN_LISTEN_HOST` → the dual-stack `::`, serving
+ * spec §1); the pipeline's Host check and the default method list
  * (`effectiveMethods`) both derive from it.
  * @param contributedBundles the extension-contributed webui-bundle registry
  * (build-and-webui Task 6 threads it here from boot; the serve-time
@@ -299,6 +300,13 @@ export async function createServer(opened, config, contributedBundles = [], opti
         commandCatalog,
         listenHost,
         methods,
+        // The listener record (release-readiness Task 1, serving spec §2):
+        // host + port are the server construction's inputs; `families`
+        // starts EMPTY (never listened) and `serve()` fills it in place
+        // with the measured families after `app.listen` resolves — the
+        // meta route reads whichever state exists at request time, never
+        // probing itself. A hand-built test server serves intent only.
+        listener: { host: listenHost, port: config.port, families: [] },
         env,
         // U4 §13.2: the harness's settings-changed fan-out (hub publish +
         // extension onSettingsChanged + the scheduler re-arm).