@agent-native/core 0.40.2 → 0.41.1

package/dist/server/recap-image-route.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Combined handler for the recap-image routes. Mount as a PREFIX handler at
+ * `/_agent-native/recap-image`; the framework strips the mount prefix, so:
+ *   - `event.url.pathname === "/"`           → POST upload (authenticated)
+ *   - `event.url.pathname === "/<token>.png"` → GET/HEAD serve (anonymous)
+ */
+export declare function createRecapImageHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<unknown>>;
+//# sourceMappingURL=recap-image-route.d.ts.map

package/dist/server/recap-image-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recap-image-route.d.ts","sourceRoot":"","sources":["../../src/server/recap-image-route.ts"],"names":[],"mappings":"AA+MA;;;;;GAKG;AACH,wBAAgB,uBAAuB,2FAoBtC"}

package/dist/server/recap-image-route.js

@@ -0,0 +1,200 @@
+/**
+ * Routes for signed, content-only recap PNG images.
+ *
+ *   POST /_agent-native/recap-image
+ *     Auth: `Authorization: Bearer <token>` — accepts the SAME tokens the MCP /
+ *     action surface accepts: a legacy `sessions` bearer (desktop/native) OR a
+ *     connect-minted MCP OAuth access token (the `agent-native connect` token,
+ *     audience-bound to this app's `{origin}/_agent-native/mcp` resource). A
+ *     normal browser session cookie is also accepted. Rejects unauthenticated
+ *     callers with 401.
+ *     Body: raw `image/png` bytes, or JSON `{ "pngBase64": "..." }`. Capped at
+ *     ~5 MB. Stores the PNG and returns `{ imageUrl: "<origin>/_agent-native/
+ *     recap-image/<token>.png" }`.
+ *
+ *   GET /_agent-native/recap-image/<token>.png
+ *     ANONYMOUS (no auth) so GitHub's camo image proxy can fetch it into a
+ *     private-repo PR comment. Returns the stored PNG with a strict
+ *     `Content-Type: image/png` and a long immutable cache header. 404 on an
+ *     unknown/malformed token. Only ever serves opaque image bytes — no plan
+ *     data leaks through this route.
+ */
+import { defineEventHandler, getHeader, getMethod, readRawBody, setResponseHeader, setResponseStatus, } from "h3";
+import { getSession } from "./auth.js";
+import { getAppUrl } from "./google-oauth.js";
+import { RECAP_IMAGE_CONTENT_TYPE, RECAP_IMAGE_MAX_BYTES, getRecapImage, isValidRecapImageToken, saveRecapImage, } from "./recap-image-store.js";
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Long immutable cache — the bytes for a given token never change. */
+const RECAP_IMAGE_CACHE_CONTROL = "public, max-age=31536000, immutable, stale-while-revalidate=604800, stale-if-error=86400";
+function isPngBuffer(buf) {
+    return (buf.byteLength >= PNG_MAGIC.byteLength &&
+        buf.subarray(0, 8).equals(PNG_MAGIC));
+}
+/**
+ * Resolve a session for the upload route. Reuses the SAME acceptance the MCP /
+ * action surface uses:
+ *   1. `getSession(event)` — browser cookie, ACCESS_TOKEN, and legacy bearer
+ *      (`sessions` table) tokens.
+ *   2. A connect-minted MCP OAuth access token, verified through the MCP
+ *      surface's canonical `verifyAuth` with this app's MCP resource as the
+ *      expected audience and `allowDevOpen: false`. `getSession` only honors
+ *      this token on the `/_agent-native/actions/*` surface, so we mirror that
+ *      verification here for the recap-image upload route.
+ */
+async function resolveUploadSession(event) {
+    const session = await getSession(event).catch(() => null);
+    if (session?.email)
+        return session;
+    // Trim once and reuse the trimmed value everywhere. Match verifyAuth's check
+    // exactly — a literal, case-sensitive `Bearer ` prefix (not `/i`, not `\s+`) —
+    // so this pre-check never accepts a header that verifyAuth would then reject
+    // (e.g. lowercase `bearer` or a tab separator).
+    const authHeader = getHeader(event, "authorization")?.trim();
+    if (!authHeader || !/^Bearer \S/.test(authHeader))
+        return null;
+    try {
+        const [{ getMcpOAuthResource }, { verifyAuth, resolveOrgIdFromDomain }] = await Promise.all([
+            import("../mcp/oauth-route.js"),
+            import("../mcp/build-server.js"),
+        ]);
+        const result = await verifyAuth(authHeader, undefined, {
+            resourceUrl: getMcpOAuthResource(event),
+            allowDevOpen: false,
+        });
+        const identity = result.authed ? result.identity : undefined;
+        if (!identity?.userEmail)
+            return null;
+        const orgId = identity.orgId ?? (await resolveOrgIdFromDomain(identity.orgDomain));
+        return {
+            email: identity.userEmail,
+            token: authHeader.replace(/^Bearer /, "").trim(),
+            ...(orgId ? { orgId } : {}),
+        };
+    }
+    catch (error) {
+        console.error("[recap-image] bearer verification error:", error);
+        return null;
+    }
+}
+/**
+ * Extract PNG bytes from the request. Supports raw `image/png` bytes and JSON
+ * `{ pngBase64 }`. Returns `null` on a malformed/oversized/non-PNG payload.
+ */
+async function readPngFromRequest(event) {
+    const raw = await readRawBody(event, false).catch(() => undefined);
+    if (!raw || raw.byteLength === 0)
+        return null;
+    if (raw.byteLength > RECAP_IMAGE_MAX_BYTES)
+        return null;
+    const contentType = (getHeader(event, "content-type") || "").toLowerCase();
+    if (contentType.includes("application/json")) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.toString("utf8"));
+        }
+        catch {
+            return null;
+        }
+        const base64 = parsed?.pngBase64;
+        if (typeof base64 !== "string" || !base64)
+            return null;
+        let bytes;
+        try {
+            bytes = Buffer.from(base64, "base64");
+        }
+        catch {
+            return null;
+        }
+        if (bytes.byteLength === 0 || bytes.byteLength > RECAP_IMAGE_MAX_BYTES) {
+            return null;
+        }
+        return isPngBuffer(bytes) ? bytes : null;
+    }
+    // Default: treat the raw body as PNG bytes (image/png or unspecified).
+    return isPngBuffer(raw) ? raw : null;
+}
+/** POST /_agent-native/recap-image — authenticated upload. */
+async function handleUpload(event) {
+    const session = await resolveUploadSession(event);
+    if (!session?.email) {
+        setResponseStatus(event, 401);
+        return { error: "Authentication required" };
+    }
+    const png = await readPngFromRequest(event);
+    if (!png) {
+        setResponseStatus(event, 400);
+        return {
+            error: "Expected a PNG image (Content-Type: image/png raw bytes, or JSON { pngBase64 }), at most 5 MB.",
+        };
+    }
+    try {
+        const { token } = await saveRecapImage(png, { ownerEmail: session.email });
+        const imageUrl = getAppUrl(event, `/_agent-native/recap-image/${token}.png`);
+        setResponseStatus(event, 201);
+        return { imageUrl };
+    }
+    catch (error) {
+        console.error("[recap-image] failed to store image:", error);
+        setResponseStatus(event, 500);
+        return { error: "Failed to store recap image" };
+    }
+}
+/** GET/HEAD /_agent-native/recap-image/<token>.png — anonymous, content-only. */
+async function handleServe(event, segment) {
+    // Require the strict `<hex>.png` shape — no directory traversal, no
+    // alternate extensions, no extra path segments.
+    const match = /^([0-9a-f]+)\.png$/i.exec(segment);
+    const token = match?.[1]?.toLowerCase() ?? "";
+    if (!isValidRecapImageToken(token)) {
+        setResponseStatus(event, 404);
+        return { error: "Not found" };
+    }
+    const stored = await getRecapImage(token).catch(() => null);
+    if (!stored) {
+        setResponseStatus(event, 404);
+        return { error: "Not found" };
+    }
+    // Strict image/png on read regardless of what was stored, plus a long
+    // immutable cache and a cross-origin policy so the camo proxy can fetch it.
+    const headers = {
+        "Content-Type": RECAP_IMAGE_CONTENT_TYPE,
+        "Cache-Control": RECAP_IMAGE_CACHE_CONTROL,
+        "CDN-Cache-Control": RECAP_IMAGE_CACHE_CONTROL,
+        "Cross-Origin-Resource-Policy": "cross-origin",
+        "Content-Length": String(stored.bytes.byteLength),
+    };
+    for (const [name, value] of Object.entries(headers)) {
+        setResponseHeader(event, name, value);
+    }
+    if (getMethod(event) === "HEAD")
+        return "";
+    const body = new ArrayBuffer(stored.bytes.byteLength);
+    new Uint8Array(body).set(stored.bytes);
+    return new Response(body, { headers });
+}
+/**
+ * Combined handler for the recap-image routes. Mount as a PREFIX handler at
+ * `/_agent-native/recap-image`; the framework strips the mount prefix, so:
+ *   - `event.url.pathname === "/"`           → POST upload (authenticated)
+ *   - `event.url.pathname === "/<token>.png"` → GET/HEAD serve (anonymous)
+ */
+export function createRecapImageHandler() {
+    return defineEventHandler(async (event) => {
+        const segment = (event.url?.pathname || "").replace(/^\/+/, "").split("/")[0] || "";
+        const method = getMethod(event);
+        if (!segment) {
+            if (method === "POST")
+                return handleUpload(event);
+            setResponseStatus(event, 405);
+            setResponseHeader(event, "Allow", "POST");
+            return { error: "Method not allowed" };
+        }
+        if (method === "GET" || method === "HEAD") {
+            return handleServe(event, segment);
+        }
+        setResponseStatus(event, 405);
+        setResponseHeader(event, "Allow", "GET, HEAD");
+        return { error: "Method not allowed" };
+    });
+}
+//# sourceMappingURL=recap-image-route.js.map

package/dist/server/recap-image-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recap-image-route.js","sourceRoot":"","sources":["../../src/server/recap-image-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,iBAAiB,GAElB,MAAM,IAAI,CAAC;AACZ,OAAO,EAAE,UAAU,EAAoB,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,cAAc,GACf,MAAM,wBAAwB,CAAC;AAEhC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAEhF,uEAAuE;AACvE,MAAM,yBAAyB,GAC7B,0FAA0F,CAAC;AAE7F,SAAS,WAAW,CAAC,GAAW;IAC9B,OAAO,CACL,GAAG,CAAC,UAAU,IAAI,SAAS,CAAC,UAAU;QACtC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CACrC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,KAAK,UAAU,oBAAoB,CACjC,KAAc;IAEd,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,OAAO,EAAE,KAAK;QAAE,OAAO,OAAO,CAAC;IAEnC,6EAA6E;IAC7E,+EAA+E;IAC/E,6EAA6E;IAC7E,gDAAgD;IAChD,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,EAAE,eAAe,CAAC,EAAE,IAAI,EAAE,CAAC;IAC7D,IAAI,CAAC,UAAU,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/D,IAAI,CAAC;QACH,MAAM,CAAC,EAAE,mBAAmB,EAAE,EAAE,EAAE,UAAU,EAAE,sBAAsB,EAAE,CAAC,GACrE,MAAM,OAAO,CAAC,GAAG,CAAC;YAChB,MAAM,CAAC,uBAAuB,CAAC;YAC/B,MAAM,CAAC,wBAAwB,CAAC;SACjC,CAAC,CAAC;QACL,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,UAAU,EAAE,SAAS,EAAE;YACrD,WAAW,EAAE,mBAAmB,CAAC,KAAK,CAAC;YACvC,YAAY,EAAE,KAAK;SACpB,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,IAAI,CAAC,QAAQ,EAAE,SAAS;YAAE,OAAO,IAAI,CAAC;QACtC,MAAM,KAAK,GACT,QAAQ,CAAC,KAAK,IAAI,CAAC,MAAM,sBAAsB,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;QACvE,OAAO;YACL,KAAK,EAAE,QAAQ,CAAC,SAAS;YACzB,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE;YAChD,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5B,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,0CAA0C,EAAE,KAAK,CAAC,CAAC;QACjE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,kBAAkB,CAAC,KAAc;IAC9C,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACnE,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,GAAG,CAAC,UAAU,GAAG,qBAAqB;QAAE,OAAO,IAAI,CAAC;IAExD,MAAM,WAAW,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAE3E,IAAI,WAAW,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC7C,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,MAAM,GAAI,MAAkC,EAAE,SAAS,CAAC;QAC9D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACvD,IAAI,KAAa,CAAC;QAClB,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,GAAG,qBAAqB,EAAE,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3C,CAAC;IAED,uEAAuE;IACvE,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC;AAED,8DAA8D;AAC9D,KAAK,UAAU,YAAY,CAAC,KAAc;IACxC,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;QACpB,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;IAC9C,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO;YACL,KAAK,EACH,gGAAgG;SACnG,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3E,MAAM,QAAQ,GAAG,SAAS,CACxB,KAAK,EACL,8BAA8B,KAAK,MAAM,CAC1C,CAAC;QACF,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,EAAE,QAAQ,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,sCAAsC,EAAE,KAAK,CAAC,CAAC;QAC7D,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC;IAClD,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,KAAK,UAAU,WAAW,CAAC,KAAc,EAAE,OAAe;IACxD,oEAAoE;IACpE,gDAAgD;IAChD,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC9C,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAChC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAChC,CAAC;IAED,sEAAsE;IACtE,4EAA4E;IAC5E,MAAM,OAAO,GAA2B;QACtC,cAAc,EAAE,wBAAwB;QACxC,eAAe,EAAE,yBAAyB;QAC1C,mBAAmB,EAAE,yBAAyB;QAC9C,8BAA8B,EAAE,cAAc;QAC9C,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC;KAClD,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,MAAM;QAAE,OAAO,EAAE,CAAC;IAE3C,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACtD,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvC,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,kBAAkB,CAAC,KAAK,EAAE,KAAc,EAAE,EAAE;QACjD,MAAM,OAAO,GACX,CAAC,KAAK,CAAC,GAAG,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACtE,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAEhC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,MAAM,KAAK,MAAM;gBAAE,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;YAClD,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC9B,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAC1C,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;QACzC,CAAC;QAED,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YAC1C,OAAO,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACrC,CAAC;QACD,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;QAC/C,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Routes for signed, content-only recap PNG images.\n *\n *   POST /_agent-native/recap-image\n *     Auth: `Authorization: Bearer <token>` — accepts the SAME tokens the MCP /\n *     action surface accepts: a legacy `sessions` bearer (desktop/native) OR a\n *     connect-minted MCP OAuth access token (the `agent-native connect` token,\n *     audience-bound to this app's `{origin}/_agent-native/mcp` resource). A\n *     normal browser session cookie is also accepted. Rejects unauthenticated\n *     callers with 401.\n *     Body: raw `image/png` bytes, or JSON `{ \"pngBase64\": \"...\" }`. Capped at\n *     ~5 MB. Stores the PNG and returns `{ imageUrl: \"<origin>/_agent-native/\n *     recap-image/<token>.png\" }`.\n *\n *   GET /_agent-native/recap-image/<token>.png\n *     ANONYMOUS (no auth) so GitHub's camo image proxy can fetch it into a\n *     private-repo PR comment. Returns the stored PNG with a strict\n *     `Content-Type: image/png` and a long immutable cache header. 404 on an\n *     unknown/malformed token. Only ever serves opaque image bytes — no plan\n *     data leaks through this route.\n */\nimport {\n  defineEventHandler,\n  getHeader,\n  getMethod,\n  readRawBody,\n  setResponseHeader,\n  setResponseStatus,\n  type H3Event,\n} from \"h3\";\nimport { getSession, type AuthSession } from \"./auth.js\";\nimport { getAppUrl } from \"./google-oauth.js\";\nimport {\n  RECAP_IMAGE_CONTENT_TYPE,\n  RECAP_IMAGE_MAX_BYTES,\n  getRecapImage,\n  isValidRecapImageToken,\n  saveRecapImage,\n} from \"./recap-image-store.js\";\n\nconst PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);\n\n/** Long immutable cache — the bytes for a given token never change. */\nconst RECAP_IMAGE_CACHE_CONTROL =\n  \"public, max-age=31536000, immutable, stale-while-revalidate=604800, stale-if-error=86400\";\n\nfunction isPngBuffer(buf: Buffer): boolean {\n  return (\n    buf.byteLength >= PNG_MAGIC.byteLength &&\n    buf.subarray(0, 8).equals(PNG_MAGIC)\n  );\n}\n\n/**\n * Resolve a session for the upload route. Reuses the SAME acceptance the MCP /\n * action surface uses:\n *   1. `getSession(event)` — browser cookie, ACCESS_TOKEN, and legacy bearer\n *      (`sessions` table) tokens.\n *   2. A connect-minted MCP OAuth access token, verified through the MCP\n *      surface's canonical `verifyAuth` with this app's MCP resource as the\n *      expected audience and `allowDevOpen: false`. `getSession` only honors\n *      this token on the `/_agent-native/actions/*` surface, so we mirror that\n *      verification here for the recap-image upload route.\n */\nasync function resolveUploadSession(\n  event: H3Event,\n): Promise<AuthSession | null> {\n  const session = await getSession(event).catch(() => null);\n  if (session?.email) return session;\n\n  // Trim once and reuse the trimmed value everywhere. Match verifyAuth's check\n  // exactly — a literal, case-sensitive `Bearer ` prefix (not `/i`, not `\\s+`) —\n  // so this pre-check never accepts a header that verifyAuth would then reject\n  // (e.g. lowercase `bearer` or a tab separator).\n  const authHeader = getHeader(event, \"authorization\")?.trim();\n  if (!authHeader || !/^Bearer \\S/.test(authHeader)) return null;\n\n  try {\n    const [{ getMcpOAuthResource }, { verifyAuth, resolveOrgIdFromDomain }] =\n      await Promise.all([\n        import(\"../mcp/oauth-route.js\"),\n        import(\"../mcp/build-server.js\"),\n      ]);\n    const result = await verifyAuth(authHeader, undefined, {\n      resourceUrl: getMcpOAuthResource(event),\n      allowDevOpen: false,\n    });\n    const identity = result.authed ? result.identity : undefined;\n    if (!identity?.userEmail) return null;\n    const orgId =\n      identity.orgId ?? (await resolveOrgIdFromDomain(identity.orgDomain));\n    return {\n      email: identity.userEmail,\n      token: authHeader.replace(/^Bearer /, \"\").trim(),\n      ...(orgId ? { orgId } : {}),\n    };\n  } catch (error) {\n    console.error(\"[recap-image] bearer verification error:\", error);\n    return null;\n  }\n}\n\n/**\n * Extract PNG bytes from the request. Supports raw `image/png` bytes and JSON\n * `{ pngBase64 }`. Returns `null` on a malformed/oversized/non-PNG payload.\n */\nasync function readPngFromRequest(event: H3Event): Promise<Buffer | null> {\n  const raw = await readRawBody(event, false).catch(() => undefined);\n  if (!raw || raw.byteLength === 0) return null;\n  if (raw.byteLength > RECAP_IMAGE_MAX_BYTES) return null;\n\n  const contentType = (getHeader(event, \"content-type\") || \"\").toLowerCase();\n\n  if (contentType.includes(\"application/json\")) {\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw.toString(\"utf8\"));\n    } catch {\n      return null;\n    }\n    const base64 = (parsed as { pngBase64?: unknown })?.pngBase64;\n    if (typeof base64 !== \"string\" || !base64) return null;\n    let bytes: Buffer;\n    try {\n      bytes = Buffer.from(base64, \"base64\");\n    } catch {\n      return null;\n    }\n    if (bytes.byteLength === 0 || bytes.byteLength > RECAP_IMAGE_MAX_BYTES) {\n      return null;\n    }\n    return isPngBuffer(bytes) ? bytes : null;\n  }\n\n  // Default: treat the raw body as PNG bytes (image/png or unspecified).\n  return isPngBuffer(raw) ? raw : null;\n}\n\n/** POST /_agent-native/recap-image — authenticated upload. */\nasync function handleUpload(event: H3Event): Promise<unknown> {\n  const session = await resolveUploadSession(event);\n  if (!session?.email) {\n    setResponseStatus(event, 401);\n    return { error: \"Authentication required\" };\n  }\n\n  const png = await readPngFromRequest(event);\n  if (!png) {\n    setResponseStatus(event, 400);\n    return {\n      error:\n        \"Expected a PNG image (Content-Type: image/png raw bytes, or JSON { pngBase64 }), at most 5 MB.\",\n    };\n  }\n\n  try {\n    const { token } = await saveRecapImage(png, { ownerEmail: session.email });\n    const imageUrl = getAppUrl(\n      event,\n      `/_agent-native/recap-image/${token}.png`,\n    );\n    setResponseStatus(event, 201);\n    return { imageUrl };\n  } catch (error) {\n    console.error(\"[recap-image] failed to store image:\", error);\n    setResponseStatus(event, 500);\n    return { error: \"Failed to store recap image\" };\n  }\n}\n\n/** GET/HEAD /_agent-native/recap-image/<token>.png — anonymous, content-only. */\nasync function handleServe(event: H3Event, segment: string): Promise<unknown> {\n  // Require the strict `<hex>.png` shape — no directory traversal, no\n  // alternate extensions, no extra path segments.\n  const match = /^([0-9a-f]+)\\.png$/i.exec(segment);\n  const token = match?.[1]?.toLowerCase() ?? \"\";\n  if (!isValidRecapImageToken(token)) {\n    setResponseStatus(event, 404);\n    return { error: \"Not found\" };\n  }\n\n  const stored = await getRecapImage(token).catch(() => null);\n  if (!stored) {\n    setResponseStatus(event, 404);\n    return { error: \"Not found\" };\n  }\n\n  // Strict image/png on read regardless of what was stored, plus a long\n  // immutable cache and a cross-origin policy so the camo proxy can fetch it.\n  const headers: Record<string, string> = {\n    \"Content-Type\": RECAP_IMAGE_CONTENT_TYPE,\n    \"Cache-Control\": RECAP_IMAGE_CACHE_CONTROL,\n    \"CDN-Cache-Control\": RECAP_IMAGE_CACHE_CONTROL,\n    \"Cross-Origin-Resource-Policy\": \"cross-origin\",\n    \"Content-Length\": String(stored.bytes.byteLength),\n  };\n  for (const [name, value] of Object.entries(headers)) {\n    setResponseHeader(event, name, value);\n  }\n\n  if (getMethod(event) === \"HEAD\") return \"\";\n\n  const body = new ArrayBuffer(stored.bytes.byteLength);\n  new Uint8Array(body).set(stored.bytes);\n  return new Response(body, { headers });\n}\n\n/**\n * Combined handler for the recap-image routes. Mount as a PREFIX handler at\n * `/_agent-native/recap-image`; the framework strips the mount prefix, so:\n *   - `event.url.pathname === \"/\"`           → POST upload (authenticated)\n *   - `event.url.pathname === \"/<token>.png\"` → GET/HEAD serve (anonymous)\n */\nexport function createRecapImageHandler() {\n  return defineEventHandler(async (event: H3Event) => {\n    const segment =\n      (event.url?.pathname || \"\").replace(/^\\/+/, \"\").split(\"/\")[0] || \"\";\n    const method = getMethod(event);\n\n    if (!segment) {\n      if (method === \"POST\") return handleUpload(event);\n      setResponseStatus(event, 405);\n      setResponseHeader(event, \"Allow\", \"POST\");\n      return { error: \"Method not allowed\" };\n    }\n\n    if (method === \"GET\" || method === \"HEAD\") {\n      return handleServe(event, segment);\n    }\n    setResponseStatus(event, 405);\n    setResponseHeader(event, \"Allow\", \"GET, HEAD\");\n    return { error: \"Method not allowed\" };\n  });\n}\n"]}

package/dist/server/recap-image-store.d.ts

@@ -0,0 +1,41 @@
+/** Maximum stored image size (~5 MB of raw PNG bytes). */
+export declare const RECAP_IMAGE_MAX_BYTES: number;
+/** Only `image/png` is ever stored or served. */
+export declare const RECAP_IMAGE_CONTENT_TYPE = "image/png";
+/**
+ * Stored recap images older than this are pruned on the next write (30 days).
+ * Each PR push uploads a fresh screenshot under a new token; without expiry the
+ * table — and the set of anonymously-fetchable image URLs — would grow without
+ * bound. 30 days comfortably outlives any PR's review window.
+ */
+export declare const RECAP_IMAGE_TTL_MS: number;
+export declare function ensureRecapImageTable(): Promise<void>;
+/**
+ * Delete recap images older than {@link RECAP_IMAGE_TTL_MS}. Called best-effort
+ * after each write so the table stays bounded. Returns the number of rows
+ * removed. Dialect-agnostic (a plain `DELETE ... WHERE created_at < ?`).
+ */
+export declare function pruneExpiredRecapImages(now?: number): Promise<number>;
+/** Generate a long, unguessable lowercase-hex token (default 32 bytes → 64 hex chars). */
+export declare function generateRecapImageToken(byteLength?: number): string;
+/** True when `token` matches the strict hex token format (no traversal characters). */
+export declare function isValidRecapImageToken(token: string | undefined | null): boolean;
+export interface StoredRecapImage {
+    bytes: Buffer;
+    contentType: string;
+}
+/**
+ * Store PNG bytes and return the freshly minted token. Caller is responsible
+ * for enforcing the size cap before calling (we re-check defensively here too).
+ */
+export declare function saveRecapImage(png: Buffer, options?: {
+    ownerEmail?: string | null;
+}): Promise<{
+    token: string;
+}>;
+/**
+ * Load a stored image by token. Returns `null` for an unknown or malformed
+ * token. Never returns anything but the opaque image bytes — no plan data.
+ */
+export declare function getRecapImage(token: string): Promise<StoredRecapImage | null>;
+//# sourceMappingURL=recap-image-store.d.ts.map

package/dist/server/recap-image-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recap-image-store.d.ts","sourceRoot":"","sources":["../../src/server/recap-image-store.ts"],"names":[],"mappings":"AAsBA,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,QAAkB,CAAC;AAErD,iDAAiD;AACjD,eAAO,MAAM,wBAAwB,cAAc,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAA2B,CAAC;AAW3D,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAuB3D;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,GAAE,MAAmB,GACvB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,0FAA0F;AAC1F,wBAAgB,uBAAuB,CAAC,UAAU,SAAK,GAAG,MAAM,CAE/D;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAC/B,OAAO,CAET;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAC3C,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB5B;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAqBlC"}

package/dist/server/recap-image-store.js

@@ -0,0 +1,138 @@
+/**
+ * SQL persistence for signed, content-only recap PNG images.
+ *
+ * The PR visual-recap GitHub Action renders a recap plan to a PNG and uploads
+ * it through `POST /_agent-native/recap-image` (authenticated with the same
+ * `agent-native connect` bearer token the MCP / action surface accepts). The
+ * stored bytes are then served anonymously from
+ * `GET /_agent-native/recap-image/<token>.png` so GitHub's camo image proxy can
+ * fetch them into a (private-repo) PR comment without a login. The interactive
+ * plan itself stays login-gated; this store only ever holds opaque image bytes
+ * keyed by a long, unguessable token.
+ *
+ * Follows the same raw-SQL pattern as observability/store.ts and usage/store.ts
+ * — framework-owned tables use `getDbExec()` with dialect-agnostic
+ * `CREATE TABLE IF NOT EXISTS` DDL (additive only; never drops/renames/alters)
+ * rather than Drizzle ORM, which is reserved for template-level schemas. The
+ * PNG is stored as base64 TEXT so it is portable across SQLite, Neon/Postgres,
+ * libSQL/Turso, and D1 without per-dialect blob/bytea handling.
+ */
+import { randomBytes } from "node:crypto";
+import { getDbExec, intType, retryOnDdlRace } from "../db/client.js";
+/** Maximum stored image size (~5 MB of raw PNG bytes). */
+export const RECAP_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
+/** Only `image/png` is ever stored or served. */
+export const RECAP_IMAGE_CONTENT_TYPE = "image/png";
+/**
+ * Stored recap images older than this are pruned on the next write (30 days).
+ * Each PR push uploads a fresh screenshot under a new token; without expiry the
+ * table — and the set of anonymously-fetchable image URLs — would grow without
+ * bound. 30 days comfortably outlives any PR's review window.
+ */
+export const RECAP_IMAGE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Token format for the public `<token>.png` path. Hex-only so it can never
+ * contain a path separator, `.`, or `..` — no directory traversal is possible
+ * via the token path param.
+ */
+const TOKEN_PATTERN = /^[0-9a-f]{32,128}$/;
+let _initPromise;
+export async function ensureRecapImageTable() {
+    if (!_initPromise) {
+        _initPromise = (async () => {
+            const client = getDbExec();
+            await retryOnDdlRace(() => client.execute(`
+        CREATE TABLE IF NOT EXISTS recap_images (
+          token TEXT PRIMARY KEY,
+          png_base64 TEXT NOT NULL,
+          content_type TEXT NOT NULL DEFAULT '${RECAP_IMAGE_CONTENT_TYPE}',
+          byte_length ${intType()} NOT NULL DEFAULT 0,
+          owner_email TEXT,
+          created_at ${intType()} NOT NULL
+        )
+      `));
+        })().catch((error) => {
+            // Allow a later call to retry if the first init lost a DDL race.
+            _initPromise = undefined;
+            throw error;
+        });
+    }
+    return _initPromise;
+}
+/**
+ * Delete recap images older than {@link RECAP_IMAGE_TTL_MS}. Called best-effort
+ * after each write so the table stays bounded. Returns the number of rows
+ * removed. Dialect-agnostic (a plain `DELETE ... WHERE created_at < ?`).
+ */
+export async function pruneExpiredRecapImages(now = Date.now()) {
+    await ensureRecapImageTable();
+    const client = getDbExec();
+    const { rowsAffected } = await client.execute({
+        sql: `DELETE FROM recap_images WHERE created_at < ?`,
+        args: [now - RECAP_IMAGE_TTL_MS],
+    });
+    return rowsAffected;
+}
+/** Generate a long, unguessable lowercase-hex token (default 32 bytes → 64 hex chars). */
+export function generateRecapImageToken(byteLength = 32) {
+    return randomBytes(byteLength).toString("hex");
+}
+/** True when `token` matches the strict hex token format (no traversal characters). */
+export function isValidRecapImageToken(token) {
+    return typeof token === "string" && TOKEN_PATTERN.test(token);
+}
+/**
+ * Store PNG bytes and return the freshly minted token. Caller is responsible
+ * for enforcing the size cap before calling (we re-check defensively here too).
+ */
+export async function saveRecapImage(png, options = {}) {
+    if (png.byteLength > RECAP_IMAGE_MAX_BYTES) {
+        throw new Error("recap image exceeds maximum size");
+    }
+    await ensureRecapImageTable();
+    const client = getDbExec();
+    const token = generateRecapImageToken();
+    await client.execute({
+        sql: `INSERT INTO recap_images
+      (token, png_base64, content_type, byte_length, owner_email, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)`,
+        args: [
+            token,
+            png.toString("base64"),
+            RECAP_IMAGE_CONTENT_TYPE,
+            png.byteLength,
+            options.ownerEmail ?? null,
+            Date.now(),
+        ],
+    });
+    // Best-effort retention: expire old images so the table and the set of public
+    // image URLs stay bounded. Never let a cleanup failure fail the upload.
+    await pruneExpiredRecapImages().catch(() => { });
+    return { token };
+}
+/**
+ * Load a stored image by token. Returns `null` for an unknown or malformed
+ * token. Never returns anything but the opaque image bytes — no plan data.
+ */
+export async function getRecapImage(token) {
+    if (!isValidRecapImageToken(token))
+        return null;
+    await ensureRecapImageTable();
+    const client = getDbExec();
+    const { rows } = await client.execute({
+        sql: `SELECT png_base64, content_type FROM recap_images WHERE token = ? LIMIT 1`,
+        args: [token],
+    });
+    const row = rows[0];
+    if (!row || typeof row.png_base64 !== "string")
+        return null;
+    return {
+        bytes: Buffer.from(row.png_base64, "base64"),
+        // Stored content type is always image/png; never trust it for response
+        // headers — the route hard-codes image/png — but surface it for callers.
+        contentType: typeof row.content_type === "string"
+            ? row.content_type
+            : RECAP_IMAGE_CONTENT_TYPE,
+    };
+}
+//# sourceMappingURL=recap-image-store.js.map

package/dist/server/recap-image-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recap-image-store.js","sourceRoot":"","sources":["../../src/server/recap-image-store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * SQL persistence for signed, content-only recap PNG images.\n *\n * The PR visual-recap GitHub Action renders a recap plan to a PNG and uploads\n * it through `POST /_agent-native/recap-image` (authenticated with the same\n * `agent-native connect` bearer token the MCP / action surface accepts). The\n * stored bytes are then served anonymously from\n * `GET /_agent-native/recap-image/<token>.png` so GitHub's camo image proxy can\n * fetch them into a (private-repo) PR comment without a login. The interactive\n * plan itself stays login-gated; this store only ever holds opaque image bytes\n * keyed by a long, unguessable token.\n *\n * Follows the same raw-SQL pattern as observability/store.ts and usage/store.ts\n * — framework-owned tables use `getDbExec()` with dialect-agnostic\n * `CREATE TABLE IF NOT EXISTS` DDL (additive only; never drops/renames/alters)\n * rather than Drizzle ORM, which is reserved for template-level schemas. The\n * PNG is stored as base64 TEXT so it is portable across SQLite, Neon/Postgres,\n * libSQL/Turso, and D1 without per-dialect blob/bytea handling.\n */\nimport { randomBytes } from \"node:crypto\";\nimport { getDbExec, intType, retryOnDdlRace } from \"../db/client.js\";\n\n/** Maximum stored image size (~5 MB of raw PNG bytes). */\nexport const RECAP_IMAGE_MAX_BYTES = 5 * 1024 * 1024;\n\n/** Only `image/png` is ever stored or served. */\nexport const RECAP_IMAGE_CONTENT_TYPE = \"image/png\";\n\n/**\n * Stored recap images older than this are pruned on the next write (30 days).\n * Each PR push uploads a fresh screenshot under a new token; without expiry the\n * table — and the set of anonymously-fetchable image URLs — would grow without\n * bound. 30 days comfortably outlives any PR's review window.\n */\nexport const RECAP_IMAGE_TTL_MS = 30 * 24 * 60 * 60 * 1000;\n\n/**\n * Token format for the public `<token>.png` path. Hex-only so it can never\n * contain a path separator, `.`, or `..` — no directory traversal is possible\n * via the token path param.\n */\nconst TOKEN_PATTERN = /^[0-9a-f]{32,128}$/;\n\nlet _initPromise: Promise<void> | undefined;\n\nexport async function ensureRecapImageTable(): Promise<void> {\n  if (!_initPromise) {\n    _initPromise = (async () => {\n      const client = getDbExec();\n      await retryOnDdlRace(() =>\n        client.execute(`\n        CREATE TABLE IF NOT EXISTS recap_images (\n          token TEXT PRIMARY KEY,\n          png_base64 TEXT NOT NULL,\n          content_type TEXT NOT NULL DEFAULT '${RECAP_IMAGE_CONTENT_TYPE}',\n          byte_length ${intType()} NOT NULL DEFAULT 0,\n          owner_email TEXT,\n          created_at ${intType()} NOT NULL\n        )\n      `),\n      );\n    })().catch((error) => {\n      // Allow a later call to retry if the first init lost a DDL race.\n      _initPromise = undefined;\n      throw error;\n    });\n  }\n  return _initPromise;\n}\n\n/**\n * Delete recap images older than {@link RECAP_IMAGE_TTL_MS}. Called best-effort\n * after each write so the table stays bounded. Returns the number of rows\n * removed. Dialect-agnostic (a plain `DELETE ... WHERE created_at < ?`).\n */\nexport async function pruneExpiredRecapImages(\n  now: number = Date.now(),\n): Promise<number> {\n  await ensureRecapImageTable();\n  const client = getDbExec();\n  const { rowsAffected } = await client.execute({\n    sql: `DELETE FROM recap_images WHERE created_at < ?`,\n    args: [now - RECAP_IMAGE_TTL_MS],\n  });\n  return rowsAffected;\n}\n\n/** Generate a long, unguessable lowercase-hex token (default 32 bytes → 64 hex chars). */\nexport function generateRecapImageToken(byteLength = 32): string {\n  return randomBytes(byteLength).toString(\"hex\");\n}\n\n/** True when `token` matches the strict hex token format (no traversal characters). */\nexport function isValidRecapImageToken(\n  token: string | undefined | null,\n): boolean {\n  return typeof token === \"string\" && TOKEN_PATTERN.test(token);\n}\n\nexport interface StoredRecapImage {\n  bytes: Buffer;\n  contentType: string;\n}\n\n/**\n * Store PNG bytes and return the freshly minted token. Caller is responsible\n * for enforcing the size cap before calling (we re-check defensively here too).\n */\nexport async function saveRecapImage(\n  png: Buffer,\n  options: { ownerEmail?: string | null } = {},\n): Promise<{ token: string }> {\n  if (png.byteLength > RECAP_IMAGE_MAX_BYTES) {\n    throw new Error(\"recap image exceeds maximum size\");\n  }\n  await ensureRecapImageTable();\n  const client = getDbExec();\n  const token = generateRecapImageToken();\n  await client.execute({\n    sql: `INSERT INTO recap_images\n      (token, png_base64, content_type, byte_length, owner_email, created_at)\n      VALUES (?, ?, ?, ?, ?, ?)`,\n    args: [\n      token,\n      png.toString(\"base64\"),\n      RECAP_IMAGE_CONTENT_TYPE,\n      png.byteLength,\n      options.ownerEmail ?? null,\n      Date.now(),\n    ],\n  });\n  // Best-effort retention: expire old images so the table and the set of public\n  // image URLs stay bounded. Never let a cleanup failure fail the upload.\n  await pruneExpiredRecapImages().catch(() => {});\n  return { token };\n}\n\n/**\n * Load a stored image by token. Returns `null` for an unknown or malformed\n * token. Never returns anything but the opaque image bytes — no plan data.\n */\nexport async function getRecapImage(\n  token: string,\n): Promise<StoredRecapImage | null> {\n  if (!isValidRecapImageToken(token)) return null;\n  await ensureRecapImageTable();\n  const client = getDbExec();\n  const { rows } = await client.execute({\n    sql: `SELECT png_base64, content_type FROM recap_images WHERE token = ? LIMIT 1`,\n    args: [token],\n  });\n  const row = rows[0] as\n    | { png_base64?: unknown; content_type?: unknown }\n    | undefined;\n  if (!row || typeof row.png_base64 !== \"string\") return null;\n  return {\n    bytes: Buffer.from(row.png_base64, \"base64\"),\n    // Stored content type is always image/png; never trust it for response\n    // headers — the route hard-codes image/png — but surface it for callers.\n    contentType:\n      typeof row.content_type === \"string\"\n        ? row.content_type\n        : RECAP_IMAGE_CONTENT_TYPE,\n  };\n}\n"]}

package/dist/styles/rich-markdown-editor.css

@@ -128,10 +128,12 @@
   font-family:
     ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
   font-size: 0.86em;
-  /* Fixed dark code surface (theme-independent) so the github-dark token palette
-     below stays legible — matches the read-side Shiki convention. */
-  background: hsl(220 13% 11%);
-  color: hsl(220 14% 90%);
+  /* Theme-aware code surface: follows the app's muted/foreground/border tokens
+     so block code respects light and dark mode (the token palette below is
+     tuned to read on a muted surface in both). */
+  background: hsl(var(--muted));
+  color: hsl(var(--foreground));
+  border: 1px solid hsl(var(--border));
   border-radius: 6px;
   padding: 0.8em 1em;
   margin: 0.55em 0;
@@ -147,53 +149,59 @@
   color: inherit;
 }
 
-/* highlight.js (lowlight) token palette — github-dark. Scoped to block code so
-   inline `code` keeps its own background. No highlight.js base theme is imported;
-   these rules are the entire theme, so the dark `pre` surface above is safe. */
+/* highlight.js (lowlight) token palette. Scoped to block code so inline `code`
+   keeps its own background. No highlight.js base theme is imported; these rules
+   are the entire theme, tuned (mid-lightness HSL) to read on the muted surface
+   above in both light and dark mode. */
 .an-rich-md-prose pre code .hljs-comment,
 .an-rich-md-prose pre code .hljs-quote {
-  color: #8b949e;
+  color: hsl(var(--muted-foreground));
   font-style: italic;
 }
 .an-rich-md-prose pre code .hljs-keyword,
 .an-rich-md-prose pre code .hljs-selector-tag,
 .an-rich-md-prose pre code .hljs-literal,
-.an-rich-md-prose pre code .hljs-doctag,
-.an-rich-md-prose pre code .hljs-deletion {
-  color: #ff7b72;
+.an-rich-md-prose pre code .hljs-doctag {
+  color: hsl(280 60% 58%);
 }
 .an-rich-md-prose pre code .hljs-string,
 .an-rich-md-prose pre code .hljs-regexp,
 .an-rich-md-prose pre code .hljs-addition {
-  color: #a5d6ff;
+  color: hsl(140 52% 40%);
 }
 .an-rich-md-prose pre code .hljs-number,
 .an-rich-md-prose pre code .hljs-symbol,
+.an-rich-md-prose pre code .hljs-literal {
+  color: hsl(28 78% 48%);
+}
 .an-rich-md-prose pre code .hljs-meta {
-  color: #79c0ff;
+  color: hsl(var(--muted-foreground));
 }
 .an-rich-md-prose pre code .hljs-title,
 .an-rich-md-prose pre code .hljs-title.function_,
 .an-rich-md-prose pre code .hljs-section {
-  color: #d2a8ff;
+  color: hsl(210 72% 52%);
 }
 .an-rich-md-prose pre code .hljs-built_in,
 .an-rich-md-prose pre code .hljs-type,
 .an-rich-md-prose pre code .hljs-title.class_,
 .an-rich-md-prose pre code .hljs-variable.language_ {
-  color: #ffa657;
+  color: hsl(190 64% 40%);
 }
 .an-rich-md-prose pre code .hljs-attr,
 .an-rich-md-prose pre code .hljs-attribute,
 .an-rich-md-prose pre code .hljs-property,
 .an-rich-md-prose pre code .hljs-params {
-  color: #79c0ff;
+  color: hsl(35 68% 46%);
 }
 .an-rich-md-prose pre code .hljs-name,
 .an-rich-md-prose pre code .hljs-tag,
 .an-rich-md-prose pre code .hljs-selector-id,
 .an-rich-md-prose pre code .hljs-selector-class {
-  color: #7ee787;
+  color: hsl(350 62% 52%);
+}
+.an-rich-md-prose pre code .hljs-deletion {
+  color: hsl(0 62% 52%);
 }
 .an-rich-md-prose pre code .hljs-emphasis {
   font-style: italic;
@@ -202,6 +210,47 @@
   font-weight: 600;
 }
 
+/* In dark mode, lift the token lightness for contrast on the dark muted surface. */
+.dark .an-rich-md-prose pre code .hljs-keyword,
+.dark .an-rich-md-prose pre code .hljs-selector-tag,
+.dark .an-rich-md-prose pre code .hljs-literal,
+.dark .an-rich-md-prose pre code .hljs-doctag {
+  color: hsl(280 72% 72%);
+}
+.dark .an-rich-md-prose pre code .hljs-string,
+.dark .an-rich-md-prose pre code .hljs-regexp,
+.dark .an-rich-md-prose pre code .hljs-addition {
+  color: hsl(140 48% 62%);
+}
+.dark .an-rich-md-prose pre code .hljs-number,
+.dark .an-rich-md-prose pre code .hljs-symbol,
+.dark .an-rich-md-prose pre code .hljs-literal {
+  color: hsl(30 85% 65%);
+}
+.dark .an-rich-md-prose pre code .hljs-title,
+.dark .an-rich-md-prose pre code .hljs-title.function_,
+.dark .an-rich-md-prose pre code .hljs-section {
+  color: hsl(210 80% 70%);
+}
+.dark .an-rich-md-prose pre code .hljs-built_in,
+.dark .an-rich-md-prose pre code .hljs-type,
+.dark .an-rich-md-prose pre code .hljs-title.class_,
+.dark .an-rich-md-prose pre code .hljs-variable.language_ {
+  color: hsl(190 70% 62%);
+}
+.dark .an-rich-md-prose pre code .hljs-attr,
+.dark .an-rich-md-prose pre code .hljs-attribute,
+.dark .an-rich-md-prose pre code .hljs-property,
+.dark .an-rich-md-prose pre code .hljs-params {
+  color: hsl(40 78% 66%);
+}
+.dark .an-rich-md-prose pre code .hljs-name,
+.dark .an-rich-md-prose pre code .hljs-tag,
+.dark .an-rich-md-prose pre code .hljs-selector-id,
+.dark .an-rich-md-prose pre code .hljs-selector-class {
+  color: hsl(350 72% 68%);
+}
+
 .an-rich-md-prose hr {
   border: none;
   border-top: 1px solid hsl(var(--border));

package/dist/templates/default/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+overrides:
+  "@assistant-ui/store": ">=0.2.9 <0.2.14"
+  "@assistant-ui/tap": "^0.5.14"
+
+allowBuilds:
+  better-sqlite3: true
+  esbuild: true

package/dist/templates/workspace-root/package.json

@@ -23,10 +23,5 @@
     "tsx": "catalog:",
     "typescript": "^6.0.3"
   },
-  "pnpm": {
-    "overrides": {
-      "better-auth": "1.6.0"
-    }
-  },
   "packageManager": "pnpm@10.14.0"
 }

package/dist/templates/workspace-root/pnpm-workspace.yaml

@@ -2,6 +2,11 @@ packages:
   - "packages/*"
   - "apps/*"
 
+overrides:
+  "@assistant-ui/store": ">=0.2.9 <0.2.14"
+  "@assistant-ui/tap": "^0.5.14"
+  better-auth: "1.6.0"
+
 onlyBuiltDependencies:
   - "@swc/core"
   - better-sqlite3
@@ -10,3 +15,12 @@ onlyBuiltDependencies:
   - esbuild
   - lightningcss
   - node-pty
+
+allowBuilds:
+  "@swc/core": true
+  better-sqlite3: true
+  canvas: true
+  electron: true
+  esbuild: true
+  lightningcss: true
+  node-pty: true

package/docs/content/cloneable-saas.md

@@ -68,6 +68,16 @@ The result: Claude-Code-level flexibility for each user, with normal SaaS deploy
 
 You don't have to. Every template is also available as a hosted app on `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com`, and so on. Use the hosted version for free or paid; fork only when you want to change something the hosted version doesn't expose.
 
+## Try it with a skill {#try-with-a-skill}
+
+Don't want to scaffold a whole app yet? Add agent-native superpowers to a coding agent you already use — Claude Code, Codex, or Cursor — with a single command. Installing the **Plans** skill turns the plans your agent writes into structured, reviewable docs with diagrams, wireframes, and inline comments:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
+
+That one command installs the skill instructions, registers the hosted MCP connector, and signs you in — no marketplace browsing, no manual OAuth. Then run `/visual-plan` in your agent. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for more skills, local/offline installs, and how app-backed skills work.
+
 ## Building on this
 
 - [**Getting Started**](/docs/getting-started) — clone your first template and run it locally