@sigrun/sigrun 0.1.6 → 0.2.1

package/dist/server/routes/images.js

@@ -0,0 +1,274 @@
+/**
+ * The image-proxy routes (UI-blocks U7 Task 3, spec §11.2):
+ *
+ * - `GET /v1/image?u=<url>&e=<expiry>&s=<sig>[&as=png]` — the SIGNED
+ *   form: the signature (Task 1's HMAC over the exact bytes `u + "\n" +
+ *   e`) gates arbitrary-URL fetching. Rejections are 403 with a
+ *   distinguishable error: `malformed_expiry` (a non-numeric `e`),
+ *   `bad_signature` (the HMAC doesn't match), `expired` (it matches but
+ *   `now > e`). The verified `u` string is fetched VERBATIM — never
+ *   re-parsed or re-encoded between verify and fetch.
+ * - `GET /v1/image?src=<asset:slug/path | data:…>[&as=png]` — the
+ *   already-validated form (no signature): assets pass the §11.1
+ *   realpath containment check (an escape or a missing file is 404,
+ *   indistinguishable) and data URLs the §11.1 type and 192 KiB size
+ *   checks.
+ * - `POST /v1/image?as=png` — a `data:` source too long for a URL is
+ *   POSTed as the raw text body; the route's `bodyLimit` is the §11.1
+ *   192 KiB rule (an over-limit body is Fastify's 413 `too_large`).
+ *
+ * Fetches go through the on-disk LRU cache: a hit fresher than its
+ * clamped max-age re-serves without an upstream call; an older hit
+ * revalidates, and a refusal is never replaced by stale bytes.
+ * Concurrent requests for one URL share ONE in-flight upstream fetch
+ * (Review Focus 4). Failures are never cached. Responses carry the
+ * sniffed Content-Type, `X-Content-Type-Options: nosniff`, and
+ * `Cache-Control: private, max-age=<upstream hint clamped to 1 h–7 d>`.
+ */
+import { open, realpath } from "node:fs/promises";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { relative, sep } from "node:path";
+import { join } from "node:path";
+import { toPng } from "../images/convert.js";
+import { FetchRefusal, fetchImage, } from "../images/fetch.js";
+import { verify } from "../images/sign.js";
+import { isAcceptedImageType, sniffImage } from "../images/sniff.js";
+/** The Cache-Control clamp (spec §11.2): between 1 hour and 7 days. */
+const MAX_AGE_MIN_SECONDS = 3600;
+const MAX_AGE_MAX_SECONDS = 7 * 24 * 3600;
+/** The §11.1 data-URL cap: 192 KiB of base64 text (the POST bodyLimit). */
+const DATA_URL_MAX_CHARS = 192 * 1024;
+/** MIME types by sniffed image type. */
+const MIME = {
+    png: "image/png",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+};
+/** The real fetch deps: dns.lookup + the wall clock. */
+function defaultFetchDeps() {
+    return {
+        resolve: async (host) => {
+            const addresses = await dnsLookup(host, { all: true, verbatim: true });
+            return addresses.map((entry) => entry.address);
+        },
+        now: Date.now,
+    };
+}
+/** Resolve one requested asset path inside the package's assets dir
+ *  (the ext-assets.ts rule, spec §11.1): realpath BOTH sides; an escape
+ *  or a missing file is `undefined` (the route answers 404). */
+async function resolveContained(assetsDir, path) {
+    let realDir;
+    try {
+        realDir = await realpath(assetsDir);
+    }
+    catch {
+        return undefined;
+    }
+    const candidate = join(realDir, path);
+    let realFile;
+    try {
+        realFile = await realpath(candidate);
+    }
+    catch {
+        return undefined;
+    }
+    const rel = relative(realDir, realFile);
+    if (rel === "" || rel.startsWith("..") || rel.includes(`..${sep}`)) {
+        return undefined;
+    }
+    return realFile;
+}
+/** Read a whole (small, cache-bounded) file. */
+async function readAll(file) {
+    const handle = await open(file, "r");
+    try {
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Decode a §11.1 data URL (`data:image/png|jpeg|gif|webp;base64,…`). */
+function decodeDataUrl(src) {
+    const match = /^data:image\/(png|jpeg|gif|webp);base64,(.*)$/s.exec(src);
+    if (match === null)
+        return undefined;
+    return Buffer.from(match[2] ?? "", "base64");
+}
+/** Clamp the upstream max-age hint into the 1 h–7 d band. */
+function clampedMaxAge(maxAge) {
+    if (maxAge === undefined)
+        return MAX_AGE_MIN_SECONDS;
+    return Math.min(MAX_AGE_MAX_SECONDS, Math.max(MAX_AGE_MIN_SECONDS, maxAge));
+}
+/**
+ * Register the image-proxy routes. `ctx` carries the shared cache and
+ * the (test-injectable) fetch deps on `ctx.imageProxy`, populated by
+ * `createServer`.
+ */
+export function registerImageRoutes(app, ctx) {
+    const { cache, deps, key } = ctx.imageProxy;
+    /** In-flight upstream fetches (Review Focus 4): concurrent requests
+     *  for one (url, variant) share ONE fetch + ONE cache write. */
+    const inflight = new Map();
+    /** Fetch one URL through the cache, sharing in-flight work. */
+    async function fetchThroughCache(u, variant) {
+        const now = deps.now();
+        const hit = await cache.get(u, variant, now);
+        if (hit !== undefined && now - hit.addedAt < hit.maxAge * 1000) {
+            const chunks = [];
+            for await (const chunk of hit.stream)
+                chunks.push(chunk);
+            return { bytes: Buffer.concat(chunks), type: hit.type, maxAge: hit.maxAge };
+        }
+        // A stale hit is never served: close its pin and revalidate.
+        if (hit !== undefined)
+            hit.stream.destroy();
+        const inflightKey = `${variant}${u}`;
+        const existing = inflight.get(inflightKey);
+        if (existing !== undefined)
+            return await existing;
+        const work = (async () => {
+            const fetched = await fetchImage(u, deps);
+            // Cache the original variant first — `as=png` requests cache
+            // BOTH variants (the conversion reads the fetched bytes). The
+            // clamped hint is BOTH the response header and the cache TTL.
+            const maxAge = clampedMaxAge(fetched.maxAge);
+            await cache.put(u, "orig", fetched.type, fetched.bytes, deps.now(), maxAge);
+            if (variant === "png") {
+                const converted = await toPng(fetched.bytes);
+                await cache.put(u, "png", "png", converted, deps.now(), maxAge);
+                return {
+                    bytes: converted,
+                    type: "png",
+                    ...(fetched.maxAge === undefined ? {} : { maxAge: fetched.maxAge }),
+                };
+            }
+            return fetched;
+        })();
+        inflight.set(inflightKey, work);
+        try {
+            return await work;
+        }
+        finally {
+            inflight.delete(inflightKey);
+        }
+    }
+    /** Serve one resolved image. */
+    async function sendImage(reply, image) {
+        return await reply
+            .header("content-type", MIME[image.type])
+            .header("x-content-type-options", "nosniff")
+            .header("cache-control", `private, max-age=${clampedMaxAge(image.maxAge)}`)
+            .send(image.bytes);
+    }
+    /** Resolve the `src=` form (asset or data URL, both already
+     *  validated by §11.1's own rules — nothing to sign). */
+    async function resolveSource(src) {
+        if (src.startsWith("asset:")) {
+            const rest = src.slice("asset:".length);
+            const slash = rest.indexOf("/");
+            if (slash <= 0)
+                return "bad";
+            const slug = rest.slice(0, slash);
+            const path = rest.slice(slash + 1);
+            const binding = ctx.opened.extensionSurfaces.find((entry) => entry.extension === slug);
+            if (binding?.assetsDir === undefined)
+                return undefined;
+            const file = await resolveContained(binding.assetsDir, path);
+            if (file === undefined)
+                return undefined;
+            const bytes = await readAll(file);
+            const sniffed = sniffImage(bytes);
+            if (!isAcceptedImageType(sniffed))
+                return undefined;
+            return { bytes, type: sniffed };
+        }
+        if (src.startsWith("data:")) {
+            if (src.length > DATA_URL_MAX_CHARS)
+                return undefined;
+            const bytes = decodeDataUrl(src);
+            if (bytes === undefined)
+                return "bad";
+            const sniffed = sniffImage(bytes);
+            if (!isAcceptedImageType(sniffed))
+                return undefined;
+            return { bytes, type: sniffed };
+        }
+        return "bad";
+    }
+    app.get("/v1/image", async (request, reply) => {
+        const { u, e, s, src, as } = request.query;
+        const wantPng = as === "png";
+        // The src form: no signature (assets and data URLs carry their
+        // own §11.1 validation).
+        if (src !== undefined) {
+            const resolved = await resolveSource(src);
+            if (resolved === "bad") {
+                return await reply.code(400).send({ error: "bad_source" });
+            }
+            if (resolved === undefined) {
+                // Containment misses and over-long data URLs are 404/413 —
+                // indistinguishable from a missing asset / a too-large body.
+                if (src.startsWith("data:") && src.length > DATA_URL_MAX_CHARS) {
+                    return await reply.code(413).send({
+                        error: "too_large",
+                        maxBytes: DATA_URL_MAX_CHARS,
+                    });
+                }
+                return await reply.code(404).send({ error: "asset_not_found" });
+            }
+            const image = wantPng
+                ? { bytes: await toPng(resolved.bytes), type: "png" }
+                : resolved;
+            return await sendImage(reply, image);
+        }
+        // The signed form.
+        if (u === undefined || e === undefined || s === undefined) {
+            return await reply.code(400).send({ error: "bad_signature" });
+        }
+        if (!/^\d+$/.test(e)) {
+            return await reply.code(403).send({ error: "malformed_expiry" });
+        }
+        // Split the verify so the expired case names its own error: a
+        // signature that MATCHES but whose expiry passed is `expired`;
+        // a mismatch is `bad_signature`.
+        if (!verify(key, u, e, s, Number(e))) {
+            return await reply.code(403).send({ error: "bad_signature" });
+        }
+        if (Date.now() > Number(e)) {
+            return await reply.code(403).send({ error: "expired" });
+        }
+        try {
+            const image = await fetchThroughCache(u, wantPng ? "png" : "orig");
+            return await sendImage(reply, image);
+        }
+        catch (cause) {
+            if (cause instanceof FetchRefusal) {
+                return await reply
+                    .code(502)
+                    .send({ error: cause.reason, message: cause.message });
+            }
+            throw cause;
+        }
+    });
+    // The long-data-URL form: a `data:` source too long for a URL is
+    // POSTed as the raw body. `bodyLimit` is the §11.1 192 KiB rule; the
+    // server's one error handler turns an over-limit body into 413
+    // `too_large`. The `text/plain` string parser is already registered
+    // app-wide by the conversations route module (the JSONL import's
+    // raw-text parser).
+    app.post("/v1/image", { bodyLimit: DATA_URL_MAX_CHARS }, async (request, reply) => {
+        const src = typeof request.body === "string" ? request.body : "";
+        const resolved = await resolveSource(src);
+        if (resolved === "bad" || resolved === undefined) {
+            return await reply.code(400).send({ error: "bad_source" });
+        }
+        const image = request.query.as === "png"
+            ? { bytes: await toPng(resolved.bytes), type: "png" }
+            : resolved;
+        return await sendImage(reply, image);
+    });
+}

package/dist/server/routes/interactions.js

@@ -33,12 +33,12 @@
  * through the per-conversation answer route above.
  */
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
-import { AmbientDoc, AmbientOwnersDoc, } from "../../harness/ambient.js";
-import { InteractionDoc, InteractionsIndexDoc, applyAnswer, indexSettled, } from "../../harness/interactions.js";
+import { AmbientDoc, AmbientOwnersDoc, asAmbientRecord, } from "../../harness/ambient.js";
+import { InteractionDoc, InteractionsIndexDoc, answerFromBody, applyAnswer, asInteractionRecord, indexSettled, maskedAnswerValues, } from "../../harness/interactions.js";
 import { loadConversation } from "../conversation-handler.js";
 import { ID_PARAMS_SCHEMA, conversationId } from "../helpers.js";
 import { accessOf } from "@sigrun/shared/access";
-import { isSuperuser } from "../auth/principal.js";
+import { accessPrincipalOf } from "../auth/access-principal.js";
 import { SessionMetaDoc } from "../session-meta.js";
 /**
  * Path params for the answer route — `ID_PARAMS_SCHEMA`'s shape plus the
@@ -61,7 +61,7 @@ const ANSWER_PARAMS_SCHEMA = {
  */
 async function visibleTo(ctx, convId, principal) {
     const meta = await ctx.opened.harness.snapshot(SessionMetaDoc, convId, BACKGROUND_CONTEXT);
-    return (accessOf({ user: principal.user, superuser: isSuperuser(principal) }, meta ?? {}) !== "none");
+    return (accessOf(accessPrincipalOf(principal, ctx.opened.identity.users), meta ?? {}) !== "none");
 }
 /** Register the interaction-seam and ambient-surface routes. */
 export function registerInteractionRoutes(app, ctx) {
@@ -102,7 +102,10 @@ export function registerInteractionRoutes(app, ctx) {
                 // but a raced settle can leave a stale entry — serve only
                 // what still reads pending (the per-conversation list's guard).
                 if (record !== undefined && record.status === "pending") {
-                    interactions.push({ ...record, conversationId: id });
+                    interactions.push({
+                        ...asInteractionRecord(record),
+                        conversationId: id,
+                    });
                 }
             }
         }
@@ -128,11 +131,35 @@ export function registerInteractionRoutes(app, ctx) {
         for (const callId of pending) {
             const record = await opened.harness.snapshot(InteractionDoc, convId, callId, BACKGROUND_CONTEXT);
             if (record !== undefined && record.status === "pending") {
-                records.push(record);
+                records.push(asInteractionRecord(record));
             }
         }
         return { interactions: records };
     });
+    // The single-record read (U6 Task 2): ANY status — the channel's
+    // refetch path (Review Focus 1's “a GET returns the winning answer”;
+    // Review Focus 2's expired refetch; the transport `load`). The SAME
+    // §5.9 visibility half as the list (hidden → the indistinguishable
+    // 404), applied in-handler by the polling convention, and the same
+    // ACCESS as the list: read membership is enough (a read-only sharee
+    // watches the decision too — writes stay behind the answer route's
+    // write gate). The record rides as-is (envelope + body + details) —
+    // the stored answer carries only the SECRET_MASK for secret fields
+    // (never the values).
+    app.get("/v1/conversations/:id/interactions/:callId", {
+        schema: { params: ANSWER_PARAMS_SCHEMA },
+        preHandler: loadConversation(ctx),
+    }, async (request, reply) => {
+        const { callId } = request.params;
+        const conversation = request.conversation;
+        const record = await opened.harness.snapshot(InteractionDoc, conversation.id, callId, BACKGROUND_CONTEXT);
+        // Unknown callId (an empty doc materializes with kind "") is the
+        // same 404 as the answer route's.
+        if (record === undefined || record.kind === "") {
+            return await reply.code(404).send({ error: "no_such_interaction" });
+        }
+        return asInteractionRecord(record);
+    });
     // The ONE generic answer route: writes `answer` into the envelope with
     // first-answer-wins inside the commit. 404 for unknown/not-pending;
     // 400 for a malformed answer. `by` is "human" (the only v1 caller).
@@ -142,59 +169,13 @@ export function registerInteractionRoutes(app, ctx) {
     }, async (request, reply) => {
         const { callId } = request.params;
         const conversation = request.conversation;
-        const body = request.body;
-        // SAFETY: the spread of an explicitly-undefined InteractionAnswer
-        // builds an empty mutable scaffold — every field is optional, and
-        // each is set only after its body value passed validation, so the
-        // loose local type never leaks an unvalidated field.
-        const answer = {
-            ...undefined,
-        };
-        if (body !== undefined && body !== null) {
-            if (typeof body !== "object" || Array.isArray(body)) {
-                return await reply.code(400).send({ error: "invalid_body" });
-            }
-            const b = body;
-            const known = new Set(["ids", "values", "text"]);
-            const unknownKey = Object.keys(b).find((k) => !known.has(k));
-            if (unknownKey !== undefined) {
-                return await reply
-                    .code(400)
-                    .send({ error: "invalid_field", field: unknownKey });
-            }
-            if (b.ids !== undefined) {
-                if (!Array.isArray(b.ids) ||
-                    b.ids.some((v) => typeof v !== "string")) {
-                    return await reply
-                        .code(400)
-                        .send({ error: "invalid_body" });
-                }
-                answer.ids = b.ids;
-                // (mutable local; the wire type stays readonly)
-            }
-            if (b.values !== undefined) {
-                if (typeof b.values !== "object" || b.values === null) {
-                    return await reply.code(400).send({ error: "invalid_body" });
-                }
-                const values = {};
-                for (const [k, v] of Object.entries(b.values)) {
-                    if (typeof v !== "string" &&
-                        typeof v !== "number" &&
-                        typeof v !== "boolean") {
-                        return await reply
-                            .code(400)
-                            .send({ error: "invalid_field", field: `values.${k}` });
-                    }
-                    values[k] = v;
-                }
-                answer.values = values;
-            }
-            if (b.text !== undefined) {
-                if (typeof b.text !== "string") {
-                    return await reply.code(400).send({ error: "invalid_body" });
-                }
-                answer.text = b.text;
-            }
+        // Ruling 20: the route body is `{values}` ONLY (every field's value
+        // under its name); the legacy `{ids, text}` shapes are a 400 — no
+        // compatibility layer (ruling 16). An absent body is a 400 too: an
+        // answer carries values.
+        const answer = answerFromBody(request.body);
+        if (answer === null) {
+            return await reply.code(400).send({ error: "invalid_body" });
         }
         // The commit returns a plain outcome; reply shaping happens
         // AFTER the commit (a Fastify reply must never travel through
@@ -203,21 +184,29 @@ export function registerInteractionRoutes(app, ctx) {
             const draft = await tx.doc(InteractionDoc, conversation.id, callId, callId);
             // Unknown callId: the doc materializes empty — detect via kind
             // never having been seeded (an empty seed has kind "").
-            if (draft.kind === "")
+            if (draft.kind === "") {
                 return { found: false };
-            const applied = applyAnswer(draft, answer, "human", Date.now(), request.principal.user);
-            if (!applied)
+            }
+            // Review Focus 4: project the STORED (masked) answer for the
+            // response BEFORE the mutation — reading the tree is safe (the
+            // body is never mutated), and re-reading a mutated nested field
+            // after the write trips chord's settled-overlay check.
+            const stored = maskedAnswerValues(draft.body, answer);
+            const applied = applyAnswer(draft, answer, "human", Date.now(), request.principal.user, { conversationId: conversation.id });
+            if (!applied) {
+                // A loser of the first-answer-wins race: the delivery-table
+                // entry (when there is one) belongs to the WINNER — the loser
+                // never recorded one (applyAnswer guards on status), so there
+                // is nothing of the loser's to sweep. Sweeping here would
+                // destroy the winner's undelivered secret.
                 return { found: true, applied: false };
-            // NEVER re-read a mutated draft field (even before the next
-            // await): reading a newly-set nested value off the tracked
-            // draft trips chord's settled-overlay check. The response
-            // projects the INPUT answer — identical to what was written.
+            }
             const index = await tx.doc(InteractionsIndexDoc);
             indexSettled(index, conversation.id, callId);
             return {
                 found: true,
                 applied: true,
-                answer,
+                answer: stored,
             };
         }, BACKGROUND_CONTEXT);
         if (!committed.found) {
@@ -252,7 +241,7 @@ export function registerInteractionRoutes(app, ctx) {
             // absent (owner registration is session-global; surfaces are
             // conversation-scoped).
             if (surface !== undefined && surface.body !== undefined) {
-                surfaces.push(surface);
+                surfaces.push(asAmbientRecord(surface));
             }
         }
         return { ambient: surfaces };

package/dist/server/routes/jobs.js

@@ -22,16 +22,9 @@
  * the caller's write access and the job's own `overlap`.
  */
 import { accessOf } from "@sigrun/shared/access";
-import { isSuperuser } from "../auth/principal.js";
+import { accessPrincipalOf } from "../auth/access-principal.js";
 import { JobDeclaredError, JobNotFoundError } from "../../jobs/index.js";
 import { validateJobSpec } from "../../jobs/spec.js";
-/** The principal form `accessOf` takes (§5.9). */
-function accessPrincipal(request) {
-    return {
-        user: request.principal.user,
-        superuser: isSuperuser(request.principal),
-    };
-}
 /** The §5.9 resource form ({owner?, sharing?}) of a job row. */
 function resourceOf(row) {
     return {
@@ -64,6 +57,7 @@ async function domainError(reply, error) {
 export function registerJobRoutes(app, ctx) {
     const { opened } = ctx;
     const jobs = opened.jobs;
+    const accessPrincipal = (request) => accessPrincipalOf(request.principal, opened.identity.users);
     /**
      * Resolve one job for the access rule: the live record's row when it
      * exists; for a RETIRED job (the history routes' case) the newest