@broberg/lens 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# @broberg/lens
+
+Make any app **Cardmem-Lens-compliant** in a few lines: expose the fleet-standard
+**mint endpoint** so Lens can log *past the auth wall* and screenshot the **real
+authed surface** — including in production — instead of a login page.
+
+```bash
+npm i @broberg/lens
+```
+
+## What it is
+
+Cardmem **Lens** verifies the surface users actually see, which is almost always
+**behind a login**. Lens can't hard-code every app's auth, so each app exposes one
+endpoint that mints a **short-lived, read-only** session on demand; Lens calls it
+just before capture, uses the session, and discards it.
+
+The contract is identical in every repo — only *how you mint the session* differs.
+So this package ships the uniform, security-sensitive **~80%** as a headless core;
+you supply the auth-specific **20%** (a `createLensSession` hook that mints + signs
+your own session cookie).
+
+> Implements the fleet F098.1 mint standard (cardmem `docs/LENS-MINT-ENDPOINT.md`).
+> `components` owns + publishes it; cardmem owns the spec.
+
+## The contract
+
+`POST /api/lens-session`, header `Authorization: Bearer <LENS_MINT_SECRET>` →
+**200** with a Playwright **storageState** JSON the Lens daemon injects verbatim:
+
+```json
+{ "cookies": [ { "name": "<session-cookie>", "value": "<signed>", "domain": "<host>",
+    "path": "/", "httpOnly": true, "secure": true, "sameSite": "Lax",
+    "expires": 1733430000 } ],
+  "origins": [] }
+```
+
+`expires` is **unix seconds**. The core fills every field except `name`/`value`.
+
+## Next.js 16 (Stack A)
+
+`app/api/lens-session/route.ts`:
+
+```ts
+import { createLensRoute } from "@broberg/lens/next";
+import { signLensCookie } from "@/lib/auth"; // your app's signing
+
+export const { POST } = createLensRoute({
+  principal: "lens@myapp.local", // dedicated, read-only — NEVER cb@webhouse.dk
+  async createSession({ principal, expiresAt }) {
+    const value = await signLensCookie(principal, expiresAt);
+    return { name: "myapp.session_token", value };
+  },
+});
+```
+
+## Hono (Stack B)
+
+```ts
+import { Hono } from "hono";
+import { lensSessionHandler } from "@broberg/lens/hono";
+
+const app = new Hono();
+app.post("/api/lens-session", lensSessionHandler({
+  principal: "lens@myapp.local",
+  async createSession({ principal, expiresAt }) {
+    return { name: "myapp_session", value: await mintSession(principal, expiresAt) };
+  },
+}));
+```
+
+## Any other framework
+
+Call the core handler directly with a normalized request:
+
+```ts
+import { createLensMintHandler } from "@broberg/lens";
+
+const handle = createLensMintHandler({ principal, createSession });
+const res = await handle({ authorization, host, secure }); // → { status, body }
+```
+
+## Minting the session (the part you write)
+
+> ⚠️ **Issue a REAL session cookie your own auth accepts** — the same one your
+> SPA's auth-gate checks (`getSession()` / your JWT middleware). A synthetic token
+> can authenticate API routes (so `curl` looks green) yet the SPA still bounces to
+> login, and Lens captures a login wall. Mint via your framework's real session
+> machinery.
+
+- **Better Auth:** the cookie is signed (`<token>.<sig>`). Create the session via
+  `auth.$context → internalAdapter.createSession(userId, ctx)`, clamp its expiry to
+  `expiresAt`, then serialize the signed cookie. Cookie name = `<prefix>.session_token`.
+- **Supabase:** mint server-side with the service-role key for the dedicated lens
+  user; return the `sb-<ref>-auth-token` cookie `@supabase/ssr` reads.
+- **Custom JWT (jose/HS256):** sign a short-lived read-only JWT for the lens
+  principal; return it as your session cookie.
+
+## What the core guarantees
+
+- **Ships dark:** `503` until `LENS_MINT_SECRET` is set (read per-request — flip it
+  on without a restart).
+- **`401` + constant-time** bearer compare (`crypto.timingSafeEqual` over SHA-256
+  digests — length-independent, never throws).
+- **Never cb@:** constructing with `principal: "cb@webhouse.dk"` (or a blank
+  principal) **throws** — the lens identity must be a dedicated read-only user.
+- **TTL clamp** to `[60s, 10min]` (default 10min); `expiresAt` is handed to your
+  hook so you clamp your session row to the same TTL.
+- **Basic rate-limit** (default 30/min) → `429`.
+- **Cookie domain** = `cookieDomain ?? LENS_COOKIE_DOMAIN ?? request host` — never
+  the bound socket address (which is `0.0.0.0` on Fly/proxy hosts → the browser
+  never sends the cookie → a silent false-green).
+
+## Read-only is enforced by YOUR app
+
+This package mints the session; it does **not** enforce read-only from inside the
+endpoint. Add a server-side **write-guard**: if the authenticated principal is the
+lens user, reject every mutating request (`POST`/`PUT`/`PATCH`/`DELETE` + write
+RPC/tools) with `403`. Give the lens principal enough *read* access to render the
+target surfaces (often admin-level read). For PII surfaces, capture `no_diff`
+smoke — never a stored pixel baseline.
+
+> Runs on the **Node runtime** (the core uses `node:crypto`) — not Next's Edge
+> runtime. Mint endpoints hit a DB to create a session anyway, so Node is correct.
+
+## API
+
+```ts
+interface LensCookie { name: string; value: string; domain?: string; path?: string;
+  httpOnly?: boolean; secure?: boolean; sameSite?: "Lax" | "Strict" | "None"; expires?: number; }
+interface LensSessionContext { principal: string; host: string; secure: boolean; ttlMs: number; expiresAt: number; }
+type CreateLensSession = (ctx: LensSessionContext) => Promise<LensCookie | LensCookie[]> | LensCookie | LensCookie[];
+interface LensMintOptions { secret?: string; createSession: CreateLensSession; principal: string;
+  ttlMs?: number; cookieDomain?: string; maxPerMinute?: number; }
+
+function createLensMintHandler(opts: LensMintOptions): (req: { authorization: string | null; host: string; secure: boolean }) => Promise<{ status: number; body: unknown }>;
+// @broberg/lens/next → createLensRoute(opts): { POST(req: Request): Promise<Response> }
+// @broberg/lens/hono → lensSessionHandler(opts): (c: Context) => Promise<Response>
+```
+
+MIT · part of the [`@broberg/*`](https://github.com/broberg-ai/components) shared-library family.

package/dist/chunk-4QJFODYF.js

@@ -0,0 +1,91 @@
+import { createHash, timingSafeEqual } from 'crypto';
+
+// src/index.ts
+var DEFAULT_TTL_MS = 10 * 60 * 1e3;
+var MIN_TTL_MS = 60 * 1e3;
+var DEFAULT_MAX_PER_MINUTE = 30;
+var FORBIDDEN_PRINCIPAL = "cb@webhouse.dk";
+function safeEqual(a, b) {
+  const ha = createHash("sha256").update(a).digest();
+  const hb = createHash("sha256").update(b).digest();
+  return timingSafeEqual(ha, hb);
+}
+function parseBearer(authorization) {
+  if (!authorization) return null;
+  const m = authorization.match(/^Bearer\s+(.+)$/i);
+  return m ? m[1].trim() : null;
+}
+function clampTtl(ttlMs) {
+  if (!Number.isFinite(ttlMs)) return DEFAULT_TTL_MS;
+  return Math.min(Math.max(ttlMs, MIN_TTL_MS), DEFAULT_TTL_MS);
+}
+function createLensMintHandler(opts) {
+  const principal = (opts.principal ?? "").trim();
+  if (!principal) {
+    throw new Error(
+      '@broberg/lens: `principal` is required \u2014 the dedicated read-only lens identity (e.g. "lens@yourapp.local").'
+    );
+  }
+  if (principal.toLowerCase() === FORBIDDEN_PRINCIPAL) {
+    throw new Error(
+      `@broberg/lens: refusing ${FORBIDDEN_PRINCIPAL} as the lens principal \u2014 it must be a dedicated read-only identity, never the human admin.`
+    );
+  }
+  const maxPerMinute = opts.maxPerMinute ?? DEFAULT_MAX_PER_MINUTE;
+  let windowStart = Date.now();
+  let count = 0;
+  function withinRate() {
+    if (maxPerMinute <= 0) return true;
+    const now = Date.now();
+    if (now - windowStart >= 6e4) {
+      windowStart = now;
+      count = 0;
+    }
+    count += 1;
+    return count <= maxPerMinute;
+  }
+  return async function handle(req) {
+    const secret = opts.secret ?? process.env.LENS_MINT_SECRET;
+    if (!secret) {
+      return { status: 503, body: { error: "lens-session disabled (LENS_MINT_SECRET unset)" } };
+    }
+    const provided = parseBearer(req.authorization);
+    if (!provided || !safeEqual(provided, secret)) {
+      return { status: 401, body: { error: "unauthorized" } };
+    }
+    if (!withinRate()) {
+      return { status: 429, body: { error: "rate limited" } };
+    }
+    const ttlMs = clampTtl(opts.ttlMs ?? DEFAULT_TTL_MS);
+    const expiresAt = Date.now() + ttlMs;
+    const ctx = {
+      principal,
+      host: req.host,
+      secure: req.secure,
+      ttlMs,
+      expiresAt
+    };
+    const minted = await opts.createSession(ctx);
+    const cookies = Array.isArray(minted) ? minted : [minted];
+    const fallbackDomain = opts.cookieDomain ?? process.env.LENS_COOKIE_DOMAIN ?? req.host;
+    const expiresSec = Math.floor(expiresAt / 1e3);
+    const storageState = {
+      cookies: cookies.map((c) => ({
+        name: c.name,
+        value: c.value,
+        domain: c.domain ?? fallbackDomain,
+        path: c.path ?? "/",
+        httpOnly: c.httpOnly ?? true,
+        secure: c.secure ?? req.secure,
+        sameSite: c.sameSite ?? "Lax",
+        expires: c.expires ?? expiresSec
+      })),
+      origins: []
+    };
+    return { status: 200, body: storageState };
+  };
+}
+
+export { createLensMintHandler };
+//# sourceMappingURL=chunk-4QJFODYF.js.map
+//# sourceMappingURL=chunk-4QJFODYF.js.map

package/dist/chunk-4QJFODYF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"chunk-4QJFODYF.js","sourcesContent":["// @broberg/lens — Lens-mint compliance core (F036).\n//\n// The fleet auth standard (cardmem F098.1, docs/LENS-MINT-ENDPOINT.md): the Lens\n// daemon POSTs to your app's `POST /api/lens-session` with a NARROW bearer; you\n// mint a SHORT-LIVED, READ-ONLY session for a DEDICATED lens principal (never\n// cb@webhouse.dk) and return it as a Playwright storageState. Lens injects those\n// cookies before capture, so it screenshots the REAL authed surface — incl. prod.\n//\n// This module is the UNIFORM + SECURE ~80% every app shares: ship-dark, a\n// constant-time bearer check, a never-cb principal guard, TTL clamp, basic\n// rate-limit, and the fixed storageState assembly. The app supplies only the\n// auth-specific 20% — a `createLensSession(ctx)` hook that mints + SIGNS its own\n// session cookie. Framework adapters live in `./next` and `./hono`.\n\nimport { createHash, timingSafeEqual } from \"node:crypto\";\n\n/** Default + max session TTL: 10 minutes — long enough for a capture run. */\nconst DEFAULT_TTL_MS = 10 * 60 * 1000;\n/** Floor so a misconfigured app can't mint an instantly-dead session. */\nconst MIN_TTL_MS = 60 * 1000;\nconst DEFAULT_MAX_PER_MINUTE = 30;\n\n/** The permanent human admin — the lens principal must NEVER be this. */\nconst FORBIDDEN_PRINCIPAL = \"cb@webhouse.dk\";\n\n/**\n * A single cookie the app's `createLensSession` hook returns. Only `name` +\n * `value` are required; the core fills the rest (`domain`, `path`, `secure`,\n * `expires`, …) from the request + options.\n */\nexport interface LensCookie {\n  name: string;\n  value: string;\n  domain?: string;\n  path?: string;\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: \"Lax\" | \"Strict\" | \"None\";\n  /** unix SECONDS. Omit to let the core stamp it from the clamped TTL. */\n  expires?: number;\n}\n\n/** What the app's `createLensSession` hook receives. */\nexport interface LensSessionContext {\n  /** The dedicated read-only lens principal (e.g. \"lens@myapp.local\"). */\n  principal: string;\n  /** Request host — the default cookie domain. */\n  host: string;\n  /** Whether the request arrived over https — the default cookie `secure`. */\n  secure: boolean;\n  /** The clamped TTL, in ms. */\n  ttlMs: number;\n  /** When the session must expire (unix MS). Clamp your session row to this. */\n  expiresAt: number;\n}\n\n/** The app-supplied session minter — the auth-specific 20%. */\nexport type CreateLensSession = (\n  ctx: LensSessionContext,\n) => Promise<LensCookie | LensCookie[]> | LensCookie | LensCookie[];\n\nexport interface LensMintOptions {\n  /**\n   * The narrow bearer secret. Defaults to `process.env.LENS_MINT_SECRET`, read\n   * per-request so the endpoint ships dark and flips on without a restart.\n   */\n  secret?: string;\n  /** App-supplied session minter (mints + signs the principal's cookie). */\n  createSession: CreateLensSession;\n  /** The dedicated read-only lens identity. Required; never cb@webhouse.dk. */\n  principal: string;\n  /** Session TTL in ms. Default 600_000; clamped to [60_000, 600_000]. */\n  ttlMs?: number;\n  /**\n   * Force a cookie domain (e.g. \".myapp.com\" for cross-subdomain capture). Else\n   * `process.env.LENS_COOKIE_DOMAIN`, else the request host. NEVER derive it\n   * from the bound socket address — on Fly/proxy hosts that is \"0.0.0.0\", and\n   * the browser then never sends the cookie (silent false-green).\n   */\n  cookieDomain?: string;\n  /** Basic per-handler fixed-window rate-limit. Default 30/min; 0 disables. */\n  maxPerMinute?: number;\n}\n\n/** A normalized request — what the framework adapters extract + pass in. */\nexport interface LensMintRequest {\n  authorization: string | null;\n  host: string;\n  secure: boolean;\n}\n\n/** The fixed Playwright storageState the Lens daemon consumes verbatim. */\nexport interface LensStorageState {\n  cookies: Array<{\n    name: string;\n    value: string;\n    domain: string;\n    path: string;\n    httpOnly: boolean;\n    secure: boolean;\n    sameSite: \"Lax\" | \"Strict\" | \"None\";\n    expires: number;\n  }>;\n  origins: never[];\n}\n\nexport interface LensMintResponse {\n  status: number;\n  body: LensStorageState | { error: string };\n}\n\n/** Length-independent constant-time compare (hash → equal-length → compare). */\nfunction safeEqual(a: string, b: string): boolean {\n  const ha = createHash(\"sha256\").update(a).digest();\n  const hb = createHash(\"sha256\").update(b).digest();\n  return timingSafeEqual(ha, hb);\n}\n\nfunction parseBearer(authorization: string | null): string | null {\n  if (!authorization) return null;\n  const m = authorization.match(/^Bearer\\s+(.+)$/i);\n  return m ? m[1]!.trim() : null;\n}\n\nfunction clampTtl(ttlMs: number): number {\n  if (!Number.isFinite(ttlMs)) return DEFAULT_TTL_MS;\n  return Math.min(Math.max(ttlMs, MIN_TTL_MS), DEFAULT_TTL_MS);\n}\n\n/**\n * Build the normalized Lens-mint handler. Wrap it with `@broberg/lens/next` or\n * `@broberg/lens/hono`, or call the returned function directly with a\n * `{ authorization, host, secure }` request from any framework.\n *\n * Throws at construction if `principal` is missing/blank or is cb@webhouse.dk.\n */\nexport function createLensMintHandler(\n  opts: LensMintOptions,\n): (req: LensMintRequest) => Promise<LensMintResponse> {\n  const principal = (opts.principal ?? \"\").trim();\n  if (!principal) {\n    throw new Error(\n      '@broberg/lens: `principal` is required — the dedicated read-only lens identity (e.g. \"lens@yourapp.local\").',\n    );\n  }\n  if (principal.toLowerCase() === FORBIDDEN_PRINCIPAL) {\n    throw new Error(\n      `@broberg/lens: refusing ${FORBIDDEN_PRINCIPAL} as the lens principal — it must be a dedicated read-only identity, never the human admin.`,\n    );\n  }\n\n  const maxPerMinute = opts.maxPerMinute ?? DEFAULT_MAX_PER_MINUTE;\n  let windowStart = Date.now();\n  let count = 0;\n  function withinRate(): boolean {\n    if (maxPerMinute <= 0) return true;\n    const now = Date.now();\n    if (now - windowStart >= 60_000) {\n      windowStart = now;\n      count = 0;\n    }\n    count += 1;\n    return count <= maxPerMinute;\n  }\n\n  return async function handle(req: LensMintRequest): Promise<LensMintResponse> {\n    // Ship-dark: inert until the secret is provisioned. Read per-request.\n    const secret = opts.secret ?? process.env.LENS_MINT_SECRET;\n    if (!secret) {\n      return { status: 503, body: { error: \"lens-session disabled (LENS_MINT_SECRET unset)\" } };\n    }\n\n    const provided = parseBearer(req.authorization);\n    if (!provided || !safeEqual(provided, secret)) {\n      return { status: 401, body: { error: \"unauthorized\" } };\n    }\n\n    // Rate-limit only authenticated requests — the only holder of a valid bearer\n    // is the daemon, so this caps the mint rate if the secret ever leaks.\n    if (!withinRate()) {\n      return { status: 429, body: { error: \"rate limited\" } };\n    }\n\n    const ttlMs = clampTtl(opts.ttlMs ?? DEFAULT_TTL_MS);\n    const expiresAt = Date.now() + ttlMs;\n    const ctx: LensSessionContext = {\n      principal,\n      host: req.host,\n      secure: req.secure,\n      ttlMs,\n      expiresAt,\n    };\n\n    const minted = await opts.createSession(ctx);\n    const cookies = Array.isArray(minted) ? minted : [minted];\n    const fallbackDomain = opts.cookieDomain ?? process.env.LENS_COOKIE_DOMAIN ?? req.host;\n    const expiresSec = Math.floor(expiresAt / 1000);\n\n    const storageState: LensStorageState = {\n      cookies: cookies.map((c) => ({\n        name: c.name,\n        value: c.value,\n        domain: c.domain ?? fallbackDomain,\n        path: c.path ?? \"/\",\n        httpOnly: c.httpOnly ?? true,\n        secure: c.secure ?? req.secure,\n        sameSite: c.sameSite ?? \"Lax\",\n        expires: c.expires ?? expiresSec,\n      })),\n      origins: [],\n    };\n\n    return { status: 200, body: storageState };\n  };\n}\n"]}

package/dist/hono.cjs

@@ -0,0 +1,109 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/index.ts
+var DEFAULT_TTL_MS = 10 * 60 * 1e3;
+var MIN_TTL_MS = 60 * 1e3;
+var DEFAULT_MAX_PER_MINUTE = 30;
+var FORBIDDEN_PRINCIPAL = "cb@webhouse.dk";
+function safeEqual(a, b) {
+  const ha = crypto.createHash("sha256").update(a).digest();
+  const hb = crypto.createHash("sha256").update(b).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+function parseBearer(authorization) {
+  if (!authorization) return null;
+  const m = authorization.match(/^Bearer\s+(.+)$/i);
+  return m ? m[1].trim() : null;
+}
+function clampTtl(ttlMs) {
+  if (!Number.isFinite(ttlMs)) return DEFAULT_TTL_MS;
+  return Math.min(Math.max(ttlMs, MIN_TTL_MS), DEFAULT_TTL_MS);
+}
+function createLensMintHandler(opts) {
+  const principal = (opts.principal ?? "").trim();
+  if (!principal) {
+    throw new Error(
+      '@broberg/lens: `principal` is required \u2014 the dedicated read-only lens identity (e.g. "lens@yourapp.local").'
+    );
+  }
+  if (principal.toLowerCase() === FORBIDDEN_PRINCIPAL) {
+    throw new Error(
+      `@broberg/lens: refusing ${FORBIDDEN_PRINCIPAL} as the lens principal \u2014 it must be a dedicated read-only identity, never the human admin.`
+    );
+  }
+  const maxPerMinute = opts.maxPerMinute ?? DEFAULT_MAX_PER_MINUTE;
+  let windowStart = Date.now();
+  let count = 0;
+  function withinRate() {
+    if (maxPerMinute <= 0) return true;
+    const now = Date.now();
+    if (now - windowStart >= 6e4) {
+      windowStart = now;
+      count = 0;
+    }
+    count += 1;
+    return count <= maxPerMinute;
+  }
+  return async function handle(req) {
+    const secret = opts.secret ?? process.env.LENS_MINT_SECRET;
+    if (!secret) {
+      return { status: 503, body: { error: "lens-session disabled (LENS_MINT_SECRET unset)" } };
+    }
+    const provided = parseBearer(req.authorization);
+    if (!provided || !safeEqual(provided, secret)) {
+      return { status: 401, body: { error: "unauthorized" } };
+    }
+    if (!withinRate()) {
+      return { status: 429, body: { error: "rate limited" } };
+    }
+    const ttlMs = clampTtl(opts.ttlMs ?? DEFAULT_TTL_MS);
+    const expiresAt = Date.now() + ttlMs;
+    const ctx = {
+      principal,
+      host: req.host,
+      secure: req.secure,
+      ttlMs,
+      expiresAt
+    };
+    const minted = await opts.createSession(ctx);
+    const cookies = Array.isArray(minted) ? minted : [minted];
+    const fallbackDomain = opts.cookieDomain ?? process.env.LENS_COOKIE_DOMAIN ?? req.host;
+    const expiresSec = Math.floor(expiresAt / 1e3);
+    const storageState = {
+      cookies: cookies.map((c) => ({
+        name: c.name,
+        value: c.value,
+        domain: c.domain ?? fallbackDomain,
+        path: c.path ?? "/",
+        httpOnly: c.httpOnly ?? true,
+        secure: c.secure ?? req.secure,
+        sameSite: c.sameSite ?? "Lax",
+        expires: c.expires ?? expiresSec
+      })),
+      origins: []
+    };
+    return { status: 200, body: storageState };
+  };
+}
+
+// src/hono.ts
+function lensSessionHandler(opts) {
+  const handle = createLensMintHandler(opts);
+  return async (c) => {
+    const url = new URL(c.req.url);
+    const host = c.req.header("x-forwarded-host") ?? c.req.header("host") ?? url.host;
+    const proto = c.req.header("x-forwarded-proto") ?? url.protocol.replace(":", "");
+    const res = await handle({
+      authorization: c.req.header("authorization") ?? null,
+      host,
+      secure: proto === "https"
+    });
+    return c.json(res.body, res.status);
+  };
+}
+
+exports.lensSessionHandler = lensSessionHandler;
+//# sourceMappingURL=hono.cjs.map
+//# sourceMappingURL=hono.cjs.map

package/dist/hono.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/hono.ts"],"names":["createHash","timingSafeEqual"],"mappings":"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","file":"hono.cjs","sourcesContent":["// @broberg/lens — Lens-mint compliance core (F036).\n//\n// The fleet auth standard (cardmem F098.1, docs/LENS-MINT-ENDPOINT.md): the Lens\n// daemon POSTs to your app's `POST /api/lens-session` with a NARROW bearer; you\n// mint a SHORT-LIVED, READ-ONLY session for a DEDICATED lens principal (never\n// cb@webhouse.dk) and return it as a Playwright storageState. Lens injects those\n// cookies before capture, so it screenshots the REAL authed surface — incl. prod.\n//\n// This module is the UNIFORM + SECURE ~80% every app shares: ship-dark, a\n// constant-time bearer check, a never-cb principal guard, TTL clamp, basic\n// rate-limit, and the fixed storageState assembly. The app supplies only the\n// auth-specific 20% — a `createLensSession(ctx)` hook that mints + SIGNS its own\n// session cookie. Framework adapters live in `./next` and `./hono`.\n\nimport { createHash, timingSafeEqual } from \"node:crypto\";\n\n/** Default + max session TTL: 10 minutes — long enough for a capture run. */\nconst DEFAULT_TTL_MS = 10 * 60 * 1000;\n/** Floor so a misconfigured app can't mint an instantly-dead session. */\nconst MIN_TTL_MS = 60 * 1000;\nconst DEFAULT_MAX_PER_MINUTE = 30;\n\n/** The permanent human admin — the lens principal must NEVER be this. */\nconst FORBIDDEN_PRINCIPAL = \"cb@webhouse.dk\";\n\n/**\n * A single cookie the app's `createLensSession` hook returns. Only `name` +\n * `value` are required; the core fills the rest (`domain`, `path`, `secure`,\n * `expires`, …) from the request + options.\n */\nexport interface LensCookie {\n  name: string;\n  value: string;\n  domain?: string;\n  path?: string;\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: \"Lax\" | \"Strict\" | \"None\";\n  /** unix SECONDS. Omit to let the core stamp it from the clamped TTL. */\n  expires?: number;\n}\n\n/** What the app's `createLensSession` hook receives. */\nexport interface LensSessionContext {\n  /** The dedicated read-only lens principal (e.g. \"lens@myapp.local\"). */\n  principal: string;\n  /** Request host — the default cookie domain. */\n  host: string;\n  /** Whether the request arrived over https — the default cookie `secure`. */\n  secure: boolean;\n  /** The clamped TTL, in ms. */\n  ttlMs: number;\n  /** When the session must expire (unix MS). Clamp your session row to this. */\n  expiresAt: number;\n}\n\n/** The app-supplied session minter — the auth-specific 20%. */\nexport type CreateLensSession = (\n  ctx: LensSessionContext,\n) => Promise<LensCookie | LensCookie[]> | LensCookie | LensCookie[];\n\nexport interface LensMintOptions {\n  /**\n   * The narrow bearer secret. Defaults to `process.env.LENS_MINT_SECRET`, read\n   * per-request so the endpoint ships dark and flips on without a restart.\n   */\n  secret?: string;\n  /** App-supplied session minter (mints + signs the principal's cookie). */\n  createSession: CreateLensSession;\n  /** The dedicated read-only lens identity. Required; never cb@webhouse.dk. */\n  principal: string;\n  /** Session TTL in ms. Default 600_000; clamped to [60_000, 600_000]. */\n  ttlMs?: number;\n  /**\n   * Force a cookie domain (e.g. \".myapp.com\" for cross-subdomain capture). Else\n   * `process.env.LENS_COOKIE_DOMAIN`, else the request host. NEVER derive it\n   * from the bound socket address — on Fly/proxy hosts that is \"0.0.0.0\", and\n   * the browser then never sends the cookie (silent false-green).\n   */\n  cookieDomain?: string;\n  /** Basic per-handler fixed-window rate-limit. Default 30/min; 0 disables. */\n  maxPerMinute?: number;\n}\n\n/** A normalized request — what the framework adapters extract + pass in. */\nexport interface LensMintRequest {\n  authorization: string | null;\n  host: string;\n  secure: boolean;\n}\n\n/** The fixed Playwright storageState the Lens daemon consumes verbatim. */\nexport interface LensStorageState {\n  cookies: Array<{\n    name: string;\n    value: string;\n    domain: string;\n    path: string;\n    httpOnly: boolean;\n    secure: boolean;\n    sameSite: \"Lax\" | \"Strict\" | \"None\";\n    expires: number;\n  }>;\n  origins: never[];\n}\n\nexport interface LensMintResponse {\n  status: number;\n  body: LensStorageState | { error: string };\n}\n\n/** Length-independent constant-time compare (hash → equal-length → compare). */\nfunction safeEqual(a: string, b: string): boolean {\n  const ha = createHash(\"sha256\").update(a).digest();\n  const hb = createHash(\"sha256\").update(b).digest();\n  return timingSafeEqual(ha, hb);\n}\n\nfunction parseBearer(authorization: string | null): string | null {\n  if (!authorization) return null;\n  const m = authorization.match(/^Bearer\\s+(.+)$/i);\n  return m ? m[1]!.trim() : null;\n}\n\nfunction clampTtl(ttlMs: number): number {\n  if (!Number.isFinite(ttlMs)) return DEFAULT_TTL_MS;\n  return Math.min(Math.max(ttlMs, MIN_TTL_MS), DEFAULT_TTL_MS);\n}\n\n/**\n * Build the normalized Lens-mint handler. Wrap it with `@broberg/lens/next` or\n * `@broberg/lens/hono`, or call the returned function directly with a\n * `{ authorization, host, secure }` request from any framework.\n *\n * Throws at construction if `principal` is missing/blank or is cb@webhouse.dk.\n */\nexport function createLensMintHandler(\n  opts: LensMintOptions,\n): (req: LensMintRequest) => Promise<LensMintResponse> {\n  const principal = (opts.principal ?? \"\").trim();\n  if (!principal) {\n    throw new Error(\n      '@broberg/lens: `principal` is required — the dedicated read-only lens identity (e.g. \"lens@yourapp.local\").',\n    );\n  }\n  if (principal.toLowerCase() === FORBIDDEN_PRINCIPAL) {\n    throw new Error(\n      `@broberg/lens: refusing ${FORBIDDEN_PRINCIPAL} as the lens principal — it must be a dedicated read-only identity, never the human admin.`,\n    );\n  }\n\n  const maxPerMinute = opts.maxPerMinute ?? DEFAULT_MAX_PER_MINUTE;\n  let windowStart = Date.now();\n  let count = 0;\n  function withinRate(): boolean {\n    if (maxPerMinute <= 0) return true;\n    const now = Date.now();\n    if (now - windowStart >= 60_000) {\n      windowStart = now;\n      count = 0;\n    }\n    count += 1;\n    return count <= maxPerMinute;\n  }\n\n  return async function handle(req: LensMintRequest): Promise<LensMintResponse> {\n    // Ship-dark: inert until the secret is provisioned. Read per-request.\n    const secret = opts.secret ?? process.env.LENS_MINT_SECRET;\n    if (!secret) {\n      return { status: 503, body: { error: \"lens-session disabled (LENS_MINT_SECRET unset)\" } };\n    }\n\n    const provided = parseBearer(req.authorization);\n    if (!provided || !safeEqual(provided, secret)) {\n      return { status: 401, body: { error: \"unauthorized\" } };\n    }\n\n    // Rate-limit only authenticated requests — the only holder of a valid bearer\n    // is the daemon, so this caps the mint rate if the secret ever leaks.\n    if (!withinRate()) {\n      return { status: 429, body: { error: \"rate limited\" } };\n    }\n\n    const ttlMs = clampTtl(opts.ttlMs ?? DEFAULT_TTL_MS);\n    const expiresAt = Date.now() + ttlMs;\n    const ctx: LensSessionContext = {\n      principal,\n      host: req.host,\n      secure: req.secure,\n      ttlMs,\n      expiresAt,\n    };\n\n    const minted = await opts.createSession(ctx);\n    const cookies = Array.isArray(minted) ? minted : [minted];\n    const fallbackDomain = opts.cookieDomain ?? process.env.LENS_COOKIE_DOMAIN ?? req.host;\n    const expiresSec = Math.floor(expiresAt / 1000);\n\n    const storageState: LensStorageState = {\n      cookies: cookies.map((c) => ({\n        name: c.name,\n        value: c.value,\n        domain: c.domain ?? fallbackDomain,\n        path: c.path ?? \"/\",\n        httpOnly: c.httpOnly ?? true,\n        secure: c.secure ?? req.secure,\n        sameSite: c.sameSite ?? \"Lax\",\n        expires: c.expires ?? expiresSec,\n      })),\n      origins: [],\n    };\n\n    return { status: 200, body: storageState };\n  };\n}\n","// @broberg/lens/hono — Stack B (Bun/Hono) adapter.\n//\n//   import { Hono } from \"hono\";\n//   import { lensSessionHandler } from \"@broberg/lens/hono\";\n//   app.post(\"/api/lens-session\", lensSessionHandler({\n//     principal: \"lens@myapp.local\",\n//     async createSession({ principal, expiresAt }) {\n//       const value = await signMySessionCookie(principal, expiresAt);\n//       return { name: \"myapp_session\", value };\n//     },\n//   }));\n//\n// `hono` is an optional peer dep — `import type` is erased at build, so the\n// package never bundles Hono and only needs it for typecheck.\n\nimport type { Context } from \"hono\";\nimport { createLensMintHandler, type LensMintOptions } from \"./index\";\n\nexport function lensSessionHandler(\n  opts: LensMintOptions,\n): (c: Context) => Promise<Response> {\n  const handle = createLensMintHandler(opts);\n  return async (c: Context): Promise<Response> => {\n    const url = new URL(c.req.url);\n    const host =\n      c.req.header(\"x-forwarded-host\") ?? c.req.header(\"host\") ?? url.host;\n    const proto = c.req.header(\"x-forwarded-proto\") ?? url.protocol.replace(\":\", \"\");\n    const res = await handle({\n      authorization: c.req.header(\"authorization\") ?? null,\n      host,\n      secure: proto === \"https\",\n    });\n    return c.json(res.body, res.status as 200 | 401 | 429 | 503);\n  };\n}\n"]}

package/dist/hono.d.cts

@@ -0,0 +1,6 @@
+import { Context } from 'hono';
+import { LensMintOptions } from './index.cjs';
+
+declare function lensSessionHandler(opts: LensMintOptions): (c: Context) => Promise<Response>;
+
+export { lensSessionHandler };

package/dist/hono.d.ts

@@ -0,0 +1,6 @@
+import { Context } from 'hono';
+import { LensMintOptions } from './index.js';
+
+declare function lensSessionHandler(opts: LensMintOptions): (c: Context) => Promise<Response>;
+
+export { lensSessionHandler };

package/dist/hono.js

@@ -0,0 +1,21 @@
+import { createLensMintHandler } from './chunk-4QJFODYF.js';
+
+// src/hono.ts
+function lensSessionHandler(opts) {
+  const handle = createLensMintHandler(opts);
+  return async (c) => {
+    const url = new URL(c.req.url);
+    const host = c.req.header("x-forwarded-host") ?? c.req.header("host") ?? url.host;
+    const proto = c.req.header("x-forwarded-proto") ?? url.protocol.replace(":", "");
+    const res = await handle({
+      authorization: c.req.header("authorization") ?? null,
+      host,
+      secure: proto === "https"
+    });
+    return c.json(res.body, res.status);
+  };
+}
+
+export { lensSessionHandler };
+//# sourceMappingURL=hono.js.map
+//# sourceMappingURL=hono.js.map

package/dist/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hono.ts"],"names":[],"mappings":";;;AAkBO,SAAS,mBACd,IAAA,EACmC;AACnC,EAAA,MAAM,MAAA,GAAS,sBAAsB,IAAI,CAAA;AACzC,EAAA,OAAO,OAAO,CAAA,KAAkC;AAC9C,IAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,CAAA,CAAE,IAAI,GAAG,CAAA;AAC7B,IAAA,MAAM,IAAA,GACJ,CAAA,CAAE,GAAA,CAAI,MAAA,CAAO,kBAAkB,CAAA,IAAK,CAAA,CAAE,GAAA,CAAI,MAAA,CAAO,MAAM,CAAA,IAAK,GAAA,CAAI,IAAA;AAClE,IAAA,MAAM,KAAA,GAAQ,CAAA,CAAE,GAAA,CAAI,MAAA,CAAO,mBAAmB,KAAK,GAAA,CAAI,QAAA,CAAS,OAAA,CAAQ,GAAA,EAAK,EAAE,CAAA;AAC/E,IAAA,MAAM,GAAA,GAAM,MAAM,MAAA,CAAO;AAAA,MACvB,aAAA,EAAe,CAAA,CAAE,GAAA,CAAI,MAAA,CAAO,eAAe,CAAA,IAAK,IAAA;AAAA,MAChD,IAAA;AAAA,MACA,QAAQ,KAAA,KAAU;AAAA,KACnB,CAAA;AACD,IAAA,OAAO,CAAA,CAAE,IAAA,CAAK,GAAA,CAAI,IAAA,EAAM,IAAI,MAA+B,CAAA;AAAA,EAC7D,CAAA;AACF","file":"hono.js","sourcesContent":["// @broberg/lens/hono — Stack B (Bun/Hono) adapter.\n//\n//   import { Hono } from \"hono\";\n//   import { lensSessionHandler } from \"@broberg/lens/hono\";\n//   app.post(\"/api/lens-session\", lensSessionHandler({\n//     principal: \"lens@myapp.local\",\n//     async createSession({ principal, expiresAt }) {\n//       const value = await signMySessionCookie(principal, expiresAt);\n//       return { name: \"myapp_session\", value };\n//     },\n//   }));\n//\n// `hono` is an optional peer dep — `import type` is erased at build, so the\n// package never bundles Hono and only needs it for typecheck.\n\nimport type { Context } from \"hono\";\nimport { createLensMintHandler, type LensMintOptions } from \"./index\";\n\nexport function lensSessionHandler(\n  opts: LensMintOptions,\n): (c: Context) => Promise<Response> {\n  const handle = createLensMintHandler(opts);\n  return async (c: Context): Promise<Response> => {\n    const url = new URL(c.req.url);\n    const host =\n      c.req.header(\"x-forwarded-host\") ?? c.req.header(\"host\") ?? url.host;\n    const proto = c.req.header(\"x-forwarded-proto\") ?? url.protocol.replace(\":\", \"\");\n    const res = await handle({\n      authorization: c.req.header(\"authorization\") ?? null,\n      host,\n      secure: proto === \"https\",\n    });\n    return c.json(res.body, res.status as 200 | 401 | 429 | 503);\n  };\n}\n"]}

package/dist/index.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/index.ts
+var DEFAULT_TTL_MS = 10 * 60 * 1e3;
+var MIN_TTL_MS = 60 * 1e3;
+var DEFAULT_MAX_PER_MINUTE = 30;
+var FORBIDDEN_PRINCIPAL = "cb@webhouse.dk";
+function safeEqual(a, b) {
+  const ha = crypto.createHash("sha256").update(a).digest();
+  const hb = crypto.createHash("sha256").update(b).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+function parseBearer(authorization) {
+  if (!authorization) return null;
+  const m = authorization.match(/^Bearer\s+(.+)$/i);
+  return m ? m[1].trim() : null;
+}
+function clampTtl(ttlMs) {
+  if (!Number.isFinite(ttlMs)) return DEFAULT_TTL_MS;
+  return Math.min(Math.max(ttlMs, MIN_TTL_MS), DEFAULT_TTL_MS);
+}
+function createLensMintHandler(opts) {
+  const principal = (opts.principal ?? "").trim();
+  if (!principal) {
+    throw new Error(
+      '@broberg/lens: `principal` is required \u2014 the dedicated read-only lens identity (e.g. "lens@yourapp.local").'
+    );
+  }
+  if (principal.toLowerCase() === FORBIDDEN_PRINCIPAL) {
+    throw new Error(
+      `@broberg/lens: refusing ${FORBIDDEN_PRINCIPAL} as the lens principal \u2014 it must be a dedicated read-only identity, never the human admin.`
+    );
+  }
+  const maxPerMinute = opts.maxPerMinute ?? DEFAULT_MAX_PER_MINUTE;
+  let windowStart = Date.now();
+  let count = 0;
+  function withinRate() {
+    if (maxPerMinute <= 0) return true;
+    const now = Date.now();
+    if (now - windowStart >= 6e4) {
+      windowStart = now;
+      count = 0;
+    }
+    count += 1;
+    return count <= maxPerMinute;
+  }
+  return async function handle(req) {
+    const secret = opts.secret ?? process.env.LENS_MINT_SECRET;
+    if (!secret) {
+      return { status: 503, body: { error: "lens-session disabled (LENS_MINT_SECRET unset)" } };
+    }
+    const provided = parseBearer(req.authorization);
+    if (!provided || !safeEqual(provided, secret)) {
+      return { status: 401, body: { error: "unauthorized" } };
+    }
+    if (!withinRate()) {
+      return { status: 429, body: { error: "rate limited" } };
+    }
+    const ttlMs = clampTtl(opts.ttlMs ?? DEFAULT_TTL_MS);
+    const expiresAt = Date.now() + ttlMs;
+    const ctx = {
+      principal,
+      host: req.host,
+      secure: req.secure,
+      ttlMs,
+      expiresAt
+    };
+    const minted = await opts.createSession(ctx);
+    const cookies = Array.isArray(minted) ? minted : [minted];
+    const fallbackDomain = opts.cookieDomain ?? process.env.LENS_COOKIE_DOMAIN ?? req.host;
+    const expiresSec = Math.floor(expiresAt / 1e3);
+    const storageState = {
+      cookies: cookies.map((c) => ({
+        name: c.name,
+        value: c.value,
+        domain: c.domain ?? fallbackDomain,
+        path: c.path ?? "/",
+        httpOnly: c.httpOnly ?? true,
+        secure: c.secure ?? req.secure,
+        sameSite: c.sameSite ?? "Lax",
+        expires: c.expires ?? expiresSec
+      })),
+      origins: []
+    };
+    return { status: 200, body: storageState };
+  };
+}
+
+exports.createLensMintHandler = createLensMintHandler;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["createHash","timingSafeEqual"],"mappings":"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","file":"index.cjs","sourcesContent":["// @broberg/lens — Lens-mint compliance core (F036).\n//\n// The fleet auth standard (cardmem F098.1, docs/LENS-MINT-ENDPOINT.md): the Lens\n// daemon POSTs to your app's `POST /api/lens-session` with a NARROW bearer; you\n// mint a SHORT-LIVED, READ-ONLY session for a DEDICATED lens principal (never\n// cb@webhouse.dk) and return it as a Playwright storageState. Lens injects those\n// cookies before capture, so it screenshots the REAL authed surface — incl. prod.\n//\n// This module is the UNIFORM + SECURE ~80% every app shares: ship-dark, a\n// constant-time bearer check, a never-cb principal guard, TTL clamp, basic\n// rate-limit, and the fixed storageState assembly. The app supplies only the\n// auth-specific 20% — a `createLensSession(ctx)` hook that mints + SIGNS its own\n// session cookie. Framework adapters live in `./next` and `./hono`.\n\nimport { createHash, timingSafeEqual } from \"node:crypto\";\n\n/** Default + max session TTL: 10 minutes — long enough for a capture run. */\nconst DEFAULT_TTL_MS = 10 * 60 * 1000;\n/** Floor so a misconfigured app can't mint an instantly-dead session. */\nconst MIN_TTL_MS = 60 * 1000;\nconst DEFAULT_MAX_PER_MINUTE = 30;\n\n/** The permanent human admin — the lens principal must NEVER be this. */\nconst FORBIDDEN_PRINCIPAL = \"cb@webhouse.dk\";\n\n/**\n * A single cookie the app's `createLensSession` hook returns. Only `name` +\n * `value` are required; the core fills the rest (`domain`, `path`, `secure`,\n * `expires`, …) from the request + options.\n */\nexport interface LensCookie {\n  name: string;\n  value: string;\n  domain?: string;\n  path?: string;\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: \"Lax\" | \"Strict\" | \"None\";\n  /** unix SECONDS. Omit to let the core stamp it from the clamped TTL. */\n  expires?: number;\n}\n\n/** What the app's `createLensSession` hook receives. */\nexport interface LensSessionContext {\n  /** The dedicated read-only lens principal (e.g. \"lens@myapp.local\"). */\n  principal: string;\n  /** Request host — the default cookie domain. */\n  host: string;\n  /** Whether the request arrived over https — the default cookie `secure`. */\n  secure: boolean;\n  /** The clamped TTL, in ms. */\n  ttlMs: number;\n  /** When the session must expire (unix MS). Clamp your session row to this. */\n  expiresAt: number;\n}\n\n/** The app-supplied session minter — the auth-specific 20%. */\nexport type CreateLensSession = (\n  ctx: LensSessionContext,\n) => Promise<LensCookie | LensCookie[]> | LensCookie | LensCookie[];\n\nexport interface LensMintOptions {\n  /**\n   * The narrow bearer secret. Defaults to `process.env.LENS_MINT_SECRET`, read\n   * per-request so the endpoint ships dark and flips on without a restart.\n   */\n  secret?: string;\n  /** App-supplied session minter (mints + signs the principal's cookie). */\n  createSession: CreateLensSession;\n  /** The dedicated read-only lens identity. Required; never cb@webhouse.dk. */\n  principal: string;\n  /** Session TTL in ms. Default 600_000; clamped to [60_000, 600_000]. */\n  ttlMs?: number;\n  /**\n   * Force a cookie domain (e.g. \".myapp.com\" for cross-subdomain capture). Else\n   * `process.env.LENS_COOKIE_DOMAIN`, else the request host. NEVER derive it\n   * from the bound socket address — on Fly/proxy hosts that is \"0.0.0.0\", and\n   * the browser then never sends the cookie (silent false-green).\n   */\n  cookieDomain?: string;\n  /** Basic per-handler fixed-window rate-limit. Default 30/min; 0 disables. */\n  maxPerMinute?: number;\n}\n\n/** A normalized request — what the framework adapters extract + pass in. */\nexport interface LensMintRequest {\n  authorization: string | null;\n  host: string;\n  secure: boolean;\n}\n\n/** The fixed Playwright storageState the Lens daemon consumes verbatim. */\nexport interface LensStorageState {\n  cookies: Array<{\n    name: string;\n    value: string;\n    domain: string;\n    path: string;\n    httpOnly: boolean;\n    secure: boolean;\n    sameSite: \"Lax\" | \"Strict\" | \"None\";\n    expires: number;\n  }>;\n  origins: never[];\n}\n\nexport interface LensMintResponse {\n  status: number;\n  body: LensStorageState | { error: string };\n}\n\n/** Length-independent constant-time compare (hash → equal-length → compare). */\nfunction safeEqual(a: string, b: string): boolean {\n  const ha = createHash(\"sha256\").update(a).digest();\n  const hb = createHash(\"sha256\").update(b).digest();\n  return timingSafeEqual(ha, hb);\n}\n\nfunction parseBearer(authorization: string | null): string | null {\n  if (!authorization) return null;\n  const m = authorization.match(/^Bearer\\s+(.+)$/i);\n  return m ? m[1]!.trim() : null;\n}\n\nfunction clampTtl(ttlMs: number): number {\n  if (!Number.isFinite(ttlMs)) return DEFAULT_TTL_MS;\n  return Math.min(Math.max(ttlMs, MIN_TTL_MS), DEFAULT_TTL_MS);\n}\n\n/**\n * Build the normalized Lens-mint handler. Wrap it with `@broberg/lens/next` or\n * `@broberg/lens/hono`, or call the returned function directly with a\n * `{ authorization, host, secure }` request from any framework.\n *\n * Throws at construction if `principal` is missing/blank or is cb@webhouse.dk.\n */\nexport function createLensMintHandler(\n  opts: LensMintOptions,\n): (req: LensMintRequest) => Promise<LensMintResponse> {\n  const principal = (opts.principal ?? \"\").trim();\n  if (!principal) {\n    throw new Error(\n      '@broberg/lens: `principal` is required — the dedicated read-only lens identity (e.g. \"lens@yourapp.local\").',\n    );\n  }\n  if (principal.toLowerCase() === FORBIDDEN_PRINCIPAL) {\n    throw new Error(\n      `@broberg/lens: refusing ${FORBIDDEN_PRINCIPAL} as the lens principal — it must be a dedicated read-only identity, never the human admin.`,\n    );\n  }\n\n  const maxPerMinute = opts.maxPerMinute ?? DEFAULT_MAX_PER_MINUTE;\n  let windowStart = Date.now();\n  let count = 0;\n  function withinRate(): boolean {\n    if (maxPerMinute <= 0) return true;\n    const now = Date.now();\n    if (now - windowStart >= 60_000) {\n      windowStart = now;\n      count = 0;\n    }\n    count += 1;\n    return count <= maxPerMinute;\n  }\n\n  return async function handle(req: LensMintRequest): Promise<LensMintResponse> {\n    // Ship-dark: inert until the secret is provisioned. Read per-request.\n    const secret = opts.secret ?? process.env.LENS_MINT_SECRET;\n    if (!secret) {\n      return { status: 503, body: { error: \"lens-session disabled (LENS_MINT_SECRET unset)\" } };\n    }\n\n    const provided = parseBearer(req.authorization);\n    if (!provided || !safeEqual(provided, secret)) {\n      return { status: 401, body: { error: \"unauthorized\" } };\n    }\n\n    // Rate-limit only authenticated requests — the only holder of a valid bearer\n    // is the daemon, so this caps the mint rate if the secret ever leaks.\n    if (!withinRate()) {\n      return { status: 429, body: { error: \"rate limited\" } };\n    }\n\n    const ttlMs = clampTtl(opts.ttlMs ?? DEFAULT_TTL_MS);\n    const expiresAt = Date.now() + ttlMs;\n    const ctx: LensSessionContext = {\n      principal,\n      host: req.host,\n      secure: req.secure,\n      ttlMs,\n      expiresAt,\n    };\n\n    const minted = await opts.createSession(ctx);\n    const cookies = Array.isArray(minted) ? minted : [minted];\n    const fallbackDomain = opts.cookieDomain ?? process.env.LENS_COOKIE_DOMAIN ?? req.host;\n    const expiresSec = Math.floor(expiresAt / 1000);\n\n    const storageState: LensStorageState = {\n      cookies: cookies.map((c) => ({\n        name: c.name,\n        value: c.value,\n        domain: c.domain ?? fallbackDomain,\n        path: c.path ?? \"/\",\n        httpOnly: c.httpOnly ?? true,\n        secure: c.secure ?? req.secure,\n        sameSite: c.sameSite ?? \"Lax\",\n        expires: c.expires ?? expiresSec,\n      })),\n      origins: [],\n    };\n\n    return { status: 200, body: storageState };\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+/**
+ * A single cookie the app's `createLensSession` hook returns. Only `name` +
+ * `value` are required; the core fills the rest (`domain`, `path`, `secure`,
+ * `expires`, …) from the request + options.
+ */
+interface LensCookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Lax" | "Strict" | "None";
+    /** unix SECONDS. Omit to let the core stamp it from the clamped TTL. */
+    expires?: number;
+}
+/** What the app's `createLensSession` hook receives. */
+interface LensSessionContext {
+    /** The dedicated read-only lens principal (e.g. "lens@myapp.local"). */
+    principal: string;
+    /** Request host — the default cookie domain. */
+    host: string;
+    /** Whether the request arrived over https — the default cookie `secure`. */
+    secure: boolean;
+    /** The clamped TTL, in ms. */
+    ttlMs: number;
+    /** When the session must expire (unix MS). Clamp your session row to this. */
+    expiresAt: number;
+}
+/** The app-supplied session minter — the auth-specific 20%. */
+type CreateLensSession = (ctx: LensSessionContext) => Promise<LensCookie | LensCookie[]> | LensCookie | LensCookie[];
+interface LensMintOptions {
+    /**
+     * The narrow bearer secret. Defaults to `process.env.LENS_MINT_SECRET`, read
+     * per-request so the endpoint ships dark and flips on without a restart.
+     */
+    secret?: string;
+    /** App-supplied session minter (mints + signs the principal's cookie). */
+    createSession: CreateLensSession;
+    /** The dedicated read-only lens identity. Required; never cb@webhouse.dk. */
+    principal: string;
+    /** Session TTL in ms. Default 600_000; clamped to [60_000, 600_000]. */
+    ttlMs?: number;
+    /**
+     * Force a cookie domain (e.g. ".myapp.com" for cross-subdomain capture). Else
+     * `process.env.LENS_COOKIE_DOMAIN`, else the request host. NEVER derive it
+     * from the bound socket address — on Fly/proxy hosts that is "0.0.0.0", and
+     * the browser then never sends the cookie (silent false-green).
+     */
+    cookieDomain?: string;
+    /** Basic per-handler fixed-window rate-limit. Default 30/min; 0 disables. */
+    maxPerMinute?: number;
+}
+/** A normalized request — what the framework adapters extract + pass in. */
+interface LensMintRequest {
+    authorization: string | null;
+    host: string;
+    secure: boolean;
+}
+/** The fixed Playwright storageState the Lens daemon consumes verbatim. */
+interface LensStorageState {
+    cookies: Array<{
+        name: string;
+        value: string;
+        domain: string;
+        path: string;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite: "Lax" | "Strict" | "None";
+        expires: number;
+    }>;
+    origins: never[];
+}
+interface LensMintResponse {
+    status: number;
+    body: LensStorageState | {
+        error: string;
+    };
+}
+/**
+ * Build the normalized Lens-mint handler. Wrap it with `@broberg/lens/next` or
+ * `@broberg/lens/hono`, or call the returned function directly with a
+ * `{ authorization, host, secure }` request from any framework.
+ *
+ * Throws at construction if `principal` is missing/blank or is cb@webhouse.dk.
+ */
+declare function createLensMintHandler(opts: LensMintOptions): (req: LensMintRequest) => Promise<LensMintResponse>;
+
+export { type CreateLensSession, type LensCookie, type LensMintOptions, type LensMintRequest, type LensMintResponse, type LensSessionContext, type LensStorageState, createLensMintHandler };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A single cookie the app's `createLensSession` hook returns. Only `name` +
+ * `value` are required; the core fills the rest (`domain`, `path`, `secure`,
+ * `expires`, …) from the request + options.
+ */
+interface LensCookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Lax" | "Strict" | "None";
+    /** unix SECONDS. Omit to let the core stamp it from the clamped TTL. */
+    expires?: number;
+}
+/** What the app's `createLensSession` hook receives. */
+interface LensSessionContext {
+    /** The dedicated read-only lens principal (e.g. "lens@myapp.local"). */
+    principal: string;
+    /** Request host — the default cookie domain. */
+    host: string;
+    /** Whether the request arrived over https — the default cookie `secure`. */
+    secure: boolean;
+    /** The clamped TTL, in ms. */
+    ttlMs: number;
+    /** When the session must expire (unix MS). Clamp your session row to this. */
+    expiresAt: number;
+}
+/** The app-supplied session minter — the auth-specific 20%. */
+type CreateLensSession = (ctx: LensSessionContext) => Promise<LensCookie | LensCookie[]> | LensCookie | LensCookie[];
+interface LensMintOptions {
+    /**
+     * The narrow bearer secret. Defaults to `process.env.LENS_MINT_SECRET`, read
+     * per-request so the endpoint ships dark and flips on without a restart.
+     */
+    secret?: string;
+    /** App-supplied session minter (mints + signs the principal's cookie). */
+    createSession: CreateLensSession;
+    /** The dedicated read-only lens identity. Required; never cb@webhouse.dk. */
+    principal: string;
+    /** Session TTL in ms. Default 600_000; clamped to [60_000, 600_000]. */
+    ttlMs?: number;
+    /**
+     * Force a cookie domain (e.g. ".myapp.com" for cross-subdomain capture). Else
+     * `process.env.LENS_COOKIE_DOMAIN`, else the request host. NEVER derive it
+     * from the bound socket address — on Fly/proxy hosts that is "0.0.0.0", and
+     * the browser then never sends the cookie (silent false-green).
+     */
+    cookieDomain?: string;
+    /** Basic per-handler fixed-window rate-limit. Default 30/min; 0 disables. */
+    maxPerMinute?: number;
+}
+/** A normalized request — what the framework adapters extract + pass in. */
+interface LensMintRequest {
+    authorization: string | null;
+    host: string;
+    secure: boolean;
+}
+/** The fixed Playwright storageState the Lens daemon consumes verbatim. */
+interface LensStorageState {
+    cookies: Array<{
+        name: string;
+        value: string;
+        domain: string;
+        path: string;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite: "Lax" | "Strict" | "None";
+        expires: number;
+    }>;
+    origins: never[];
+}
+interface LensMintResponse {
+    status: number;
+    body: LensStorageState | {
+        error: string;
+    };
+}
+/**
+ * Build the normalized Lens-mint handler. Wrap it with `@broberg/lens/next` or
+ * `@broberg/lens/hono`, or call the returned function directly with a
+ * `{ authorization, host, secure }` request from any framework.
+ *
+ * Throws at construction if `principal` is missing/blank or is cb@webhouse.dk.
+ */
+declare function createLensMintHandler(opts: LensMintOptions): (req: LensMintRequest) => Promise<LensMintResponse>;
+
+export { type CreateLensSession, type LensCookie, type LensMintOptions, type LensMintRequest, type LensMintResponse, type LensSessionContext, type LensStorageState, createLensMintHandler };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createLensMintHandler } from './chunk-4QJFODYF.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/next.cjs

@@ -0,0 +1,111 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/index.ts
+var DEFAULT_TTL_MS = 10 * 60 * 1e3;
+var MIN_TTL_MS = 60 * 1e3;
+var DEFAULT_MAX_PER_MINUTE = 30;
+var FORBIDDEN_PRINCIPAL = "cb@webhouse.dk";
+function safeEqual(a, b) {
+  const ha = crypto.createHash("sha256").update(a).digest();
+  const hb = crypto.createHash("sha256").update(b).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+function parseBearer(authorization) {
+  if (!authorization) return null;
+  const m = authorization.match(/^Bearer\s+(.+)$/i);
+  return m ? m[1].trim() : null;
+}
+function clampTtl(ttlMs) {
+  if (!Number.isFinite(ttlMs)) return DEFAULT_TTL_MS;
+  return Math.min(Math.max(ttlMs, MIN_TTL_MS), DEFAULT_TTL_MS);
+}
+function createLensMintHandler(opts) {
+  const principal = (opts.principal ?? "").trim();
+  if (!principal) {
+    throw new Error(
+      '@broberg/lens: `principal` is required \u2014 the dedicated read-only lens identity (e.g. "lens@yourapp.local").'
+    );
+  }
+  if (principal.toLowerCase() === FORBIDDEN_PRINCIPAL) {
+    throw new Error(
+      `@broberg/lens: refusing ${FORBIDDEN_PRINCIPAL} as the lens principal \u2014 it must be a dedicated read-only identity, never the human admin.`
+    );
+  }
+  const maxPerMinute = opts.maxPerMinute ?? DEFAULT_MAX_PER_MINUTE;
+  let windowStart = Date.now();
+  let count = 0;
+  function withinRate() {
+    if (maxPerMinute <= 0) return true;
+    const now = Date.now();
+    if (now - windowStart >= 6e4) {
+      windowStart = now;
+      count = 0;
+    }
+    count += 1;
+    return count <= maxPerMinute;
+  }
+  return async function handle(req) {
+    const secret = opts.secret ?? process.env.LENS_MINT_SECRET;
+    if (!secret) {
+      return { status: 503, body: { error: "lens-session disabled (LENS_MINT_SECRET unset)" } };
+    }
+    const provided = parseBearer(req.authorization);
+    if (!provided || !safeEqual(provided, secret)) {
+      return { status: 401, body: { error: "unauthorized" } };
+    }
+    if (!withinRate()) {
+      return { status: 429, body: { error: "rate limited" } };
+    }
+    const ttlMs = clampTtl(opts.ttlMs ?? DEFAULT_TTL_MS);
+    const expiresAt = Date.now() + ttlMs;
+    const ctx = {
+      principal,
+      host: req.host,
+      secure: req.secure,
+      ttlMs,
+      expiresAt
+    };
+    const minted = await opts.createSession(ctx);
+    const cookies = Array.isArray(minted) ? minted : [minted];
+    const fallbackDomain = opts.cookieDomain ?? process.env.LENS_COOKIE_DOMAIN ?? req.host;
+    const expiresSec = Math.floor(expiresAt / 1e3);
+    const storageState = {
+      cookies: cookies.map((c) => ({
+        name: c.name,
+        value: c.value,
+        domain: c.domain ?? fallbackDomain,
+        path: c.path ?? "/",
+        httpOnly: c.httpOnly ?? true,
+        secure: c.secure ?? req.secure,
+        sameSite: c.sameSite ?? "Lax",
+        expires: c.expires ?? expiresSec
+      })),
+      origins: []
+    };
+    return { status: 200, body: storageState };
+  };
+}
+
+// src/next.ts
+function createLensRoute(opts) {
+  const handle = createLensMintHandler(opts);
+  return {
+    async POST(req) {
+      const url = new URL(req.url);
+      const host = req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? url.host;
+      const proto = req.headers.get("x-forwarded-proto") ?? url.protocol.replace(":", "");
+      const res = await handle({
+        authorization: req.headers.get("authorization"),
+        host,
+        secure: proto === "https"
+      });
+      return Response.json(res.body, { status: res.status });
+    }
+  };
+}
+
+exports.createLensRoute = createLensRoute;
+//# sourceMappingURL=next.cjs.map
+//# sourceMappingURL=next.cjs.map

package/dist/next.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/next.ts"],"names":["createHash","timingSafeEqual"],"mappings":"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","file":"next.cjs","sourcesContent":["// @broberg/lens — Lens-mint compliance core (F036).\n//\n// The fleet auth standard (cardmem F098.1, docs/LENS-MINT-ENDPOINT.md): the Lens\n// daemon POSTs to your app's `POST /api/lens-session` with a NARROW bearer; you\n// mint a SHORT-LIVED, READ-ONLY session for a DEDICATED lens principal (never\n// cb@webhouse.dk) and return it as a Playwright storageState. Lens injects those\n// cookies before capture, so it screenshots the REAL authed surface — incl. prod.\n//\n// This module is the UNIFORM + SECURE ~80% every app shares: ship-dark, a\n// constant-time bearer check, a never-cb principal guard, TTL clamp, basic\n// rate-limit, and the fixed storageState assembly. The app supplies only the\n// auth-specific 20% — a `createLensSession(ctx)` hook that mints + SIGNS its own\n// session cookie. Framework adapters live in `./next` and `./hono`.\n\nimport { createHash, timingSafeEqual } from \"node:crypto\";\n\n/** Default + max session TTL: 10 minutes — long enough for a capture run. */\nconst DEFAULT_TTL_MS = 10 * 60 * 1000;\n/** Floor so a misconfigured app can't mint an instantly-dead session. */\nconst MIN_TTL_MS = 60 * 1000;\nconst DEFAULT_MAX_PER_MINUTE = 30;\n\n/** The permanent human admin — the lens principal must NEVER be this. */\nconst FORBIDDEN_PRINCIPAL = \"cb@webhouse.dk\";\n\n/**\n * A single cookie the app's `createLensSession` hook returns. Only `name` +\n * `value` are required; the core fills the rest (`domain`, `path`, `secure`,\n * `expires`, …) from the request + options.\n */\nexport interface LensCookie {\n  name: string;\n  value: string;\n  domain?: string;\n  path?: string;\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: \"Lax\" | \"Strict\" | \"None\";\n  /** unix SECONDS. Omit to let the core stamp it from the clamped TTL. */\n  expires?: number;\n}\n\n/** What the app's `createLensSession` hook receives. */\nexport interface LensSessionContext {\n  /** The dedicated read-only lens principal (e.g. \"lens@myapp.local\"). */\n  principal: string;\n  /** Request host — the default cookie domain. */\n  host: string;\n  /** Whether the request arrived over https — the default cookie `secure`. */\n  secure: boolean;\n  /** The clamped TTL, in ms. */\n  ttlMs: number;\n  /** When the session must expire (unix MS). Clamp your session row to this. */\n  expiresAt: number;\n}\n\n/** The app-supplied session minter — the auth-specific 20%. */\nexport type CreateLensSession = (\n  ctx: LensSessionContext,\n) => Promise<LensCookie | LensCookie[]> | LensCookie | LensCookie[];\n\nexport interface LensMintOptions {\n  /**\n   * The narrow bearer secret. Defaults to `process.env.LENS_MINT_SECRET`, read\n   * per-request so the endpoint ships dark and flips on without a restart.\n   */\n  secret?: string;\n  /** App-supplied session minter (mints + signs the principal's cookie). */\n  createSession: CreateLensSession;\n  /** The dedicated read-only lens identity. Required; never cb@webhouse.dk. */\n  principal: string;\n  /** Session TTL in ms. Default 600_000; clamped to [60_000, 600_000]. */\n  ttlMs?: number;\n  /**\n   * Force a cookie domain (e.g. \".myapp.com\" for cross-subdomain capture). Else\n   * `process.env.LENS_COOKIE_DOMAIN`, else the request host. NEVER derive it\n   * from the bound socket address — on Fly/proxy hosts that is \"0.0.0.0\", and\n   * the browser then never sends the cookie (silent false-green).\n   */\n  cookieDomain?: string;\n  /** Basic per-handler fixed-window rate-limit. Default 30/min; 0 disables. */\n  maxPerMinute?: number;\n}\n\n/** A normalized request — what the framework adapters extract + pass in. */\nexport interface LensMintRequest {\n  authorization: string | null;\n  host: string;\n  secure: boolean;\n}\n\n/** The fixed Playwright storageState the Lens daemon consumes verbatim. */\nexport interface LensStorageState {\n  cookies: Array<{\n    name: string;\n    value: string;\n    domain: string;\n    path: string;\n    httpOnly: boolean;\n    secure: boolean;\n    sameSite: \"Lax\" | \"Strict\" | \"None\";\n    expires: number;\n  }>;\n  origins: never[];\n}\n\nexport interface LensMintResponse {\n  status: number;\n  body: LensStorageState | { error: string };\n}\n\n/** Length-independent constant-time compare (hash → equal-length → compare). */\nfunction safeEqual(a: string, b: string): boolean {\n  const ha = createHash(\"sha256\").update(a).digest();\n  const hb = createHash(\"sha256\").update(b).digest();\n  return timingSafeEqual(ha, hb);\n}\n\nfunction parseBearer(authorization: string | null): string | null {\n  if (!authorization) return null;\n  const m = authorization.match(/^Bearer\\s+(.+)$/i);\n  return m ? m[1]!.trim() : null;\n}\n\nfunction clampTtl(ttlMs: number): number {\n  if (!Number.isFinite(ttlMs)) return DEFAULT_TTL_MS;\n  return Math.min(Math.max(ttlMs, MIN_TTL_MS), DEFAULT_TTL_MS);\n}\n\n/**\n * Build the normalized Lens-mint handler. Wrap it with `@broberg/lens/next` or\n * `@broberg/lens/hono`, or call the returned function directly with a\n * `{ authorization, host, secure }` request from any framework.\n *\n * Throws at construction if `principal` is missing/blank or is cb@webhouse.dk.\n */\nexport function createLensMintHandler(\n  opts: LensMintOptions,\n): (req: LensMintRequest) => Promise<LensMintResponse> {\n  const principal = (opts.principal ?? \"\").trim();\n  if (!principal) {\n    throw new Error(\n      '@broberg/lens: `principal` is required — the dedicated read-only lens identity (e.g. \"lens@yourapp.local\").',\n    );\n  }\n  if (principal.toLowerCase() === FORBIDDEN_PRINCIPAL) {\n    throw new Error(\n      `@broberg/lens: refusing ${FORBIDDEN_PRINCIPAL} as the lens principal — it must be a dedicated read-only identity, never the human admin.`,\n    );\n  }\n\n  const maxPerMinute = opts.maxPerMinute ?? DEFAULT_MAX_PER_MINUTE;\n  let windowStart = Date.now();\n  let count = 0;\n  function withinRate(): boolean {\n    if (maxPerMinute <= 0) return true;\n    const now = Date.now();\n    if (now - windowStart >= 60_000) {\n      windowStart = now;\n      count = 0;\n    }\n    count += 1;\n    return count <= maxPerMinute;\n  }\n\n  return async function handle(req: LensMintRequest): Promise<LensMintResponse> {\n    // Ship-dark: inert until the secret is provisioned. Read per-request.\n    const secret = opts.secret ?? process.env.LENS_MINT_SECRET;\n    if (!secret) {\n      return { status: 503, body: { error: \"lens-session disabled (LENS_MINT_SECRET unset)\" } };\n    }\n\n    const provided = parseBearer(req.authorization);\n    if (!provided || !safeEqual(provided, secret)) {\n      return { status: 401, body: { error: \"unauthorized\" } };\n    }\n\n    // Rate-limit only authenticated requests — the only holder of a valid bearer\n    // is the daemon, so this caps the mint rate if the secret ever leaks.\n    if (!withinRate()) {\n      return { status: 429, body: { error: \"rate limited\" } };\n    }\n\n    const ttlMs = clampTtl(opts.ttlMs ?? DEFAULT_TTL_MS);\n    const expiresAt = Date.now() + ttlMs;\n    const ctx: LensSessionContext = {\n      principal,\n      host: req.host,\n      secure: req.secure,\n      ttlMs,\n      expiresAt,\n    };\n\n    const minted = await opts.createSession(ctx);\n    const cookies = Array.isArray(minted) ? minted : [minted];\n    const fallbackDomain = opts.cookieDomain ?? process.env.LENS_COOKIE_DOMAIN ?? req.host;\n    const expiresSec = Math.floor(expiresAt / 1000);\n\n    const storageState: LensStorageState = {\n      cookies: cookies.map((c) => ({\n        name: c.name,\n        value: c.value,\n        domain: c.domain ?? fallbackDomain,\n        path: c.path ?? \"/\",\n        httpOnly: c.httpOnly ?? true,\n        secure: c.secure ?? req.secure,\n        sameSite: c.sameSite ?? \"Lax\",\n        expires: c.expires ?? expiresSec,\n      })),\n      origins: [],\n    };\n\n    return { status: 200, body: storageState };\n  };\n}\n","// @broberg/lens/next — Next.js 16 route-handler adapter.\n//\n// Mount at `app/api/lens-session/route.ts`:\n//\n//   import { createLensRoute } from \"@broberg/lens/next\";\n//   export const { POST } = createLensRoute({\n//     principal: \"lens@myapp.local\",\n//     async createSession({ principal, expiresAt }) {\n//       const value = await signMySessionCookie(principal, expiresAt);\n//       return { name: \"myapp.session_token\", value };\n//     },\n//   });\n//\n// Uses Web `Request`/`Response` — no `next`/`react` import, so it runs on the\n// Node runtime route handlers serve from. (node:crypto in the core means this is\n// NOT for the Edge runtime — mint endpoints hit a DB anyway, so Node is right.)\n\nimport { createLensMintHandler, type LensMintOptions } from \"./index\";\n\nexport function createLensRoute(opts: LensMintOptions): {\n  POST: (req: Request) => Promise<Response>;\n} {\n  const handle = createLensMintHandler(opts);\n  return {\n    async POST(req: Request): Promise<Response> {\n      const url = new URL(req.url);\n      const host =\n        req.headers.get(\"x-forwarded-host\") ?? req.headers.get(\"host\") ?? url.host;\n      const proto =\n        req.headers.get(\"x-forwarded-proto\") ?? url.protocol.replace(\":\", \"\");\n      const res = await handle({\n        authorization: req.headers.get(\"authorization\"),\n        host,\n        secure: proto === \"https\",\n      });\n      return Response.json(res.body, { status: res.status });\n    },\n  };\n}\n"]}

package/dist/next.d.cts

@@ -0,0 +1,7 @@
+import { LensMintOptions } from './index.cjs';
+
+declare function createLensRoute(opts: LensMintOptions): {
+    POST: (req: Request) => Promise<Response>;
+};
+
+export { createLensRoute };

package/dist/next.d.ts

@@ -0,0 +1,7 @@
+import { LensMintOptions } from './index.js';
+
+declare function createLensRoute(opts: LensMintOptions): {
+    POST: (req: Request) => Promise<Response>;
+};
+
+export { createLensRoute };

package/dist/next.js

@@ -0,0 +1,23 @@
+import { createLensMintHandler } from './chunk-4QJFODYF.js';
+
+// src/next.ts
+function createLensRoute(opts) {
+  const handle = createLensMintHandler(opts);
+  return {
+    async POST(req) {
+      const url = new URL(req.url);
+      const host = req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? url.host;
+      const proto = req.headers.get("x-forwarded-proto") ?? url.protocol.replace(":", "");
+      const res = await handle({
+        authorization: req.headers.get("authorization"),
+        host,
+        secure: proto === "https"
+      });
+      return Response.json(res.body, { status: res.status });
+    }
+  };
+}
+
+export { createLensRoute };
+//# sourceMappingURL=next.js.map
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/next.ts"],"names":[],"mappings":";;;AAmBO,SAAS,gBAAgB,IAAA,EAE9B;AACA,EAAA,MAAM,MAAA,GAAS,sBAAsB,IAAI,CAAA;AACzC,EAAA,OAAO;AAAA,IACL,MAAM,KAAK,GAAA,EAAiC;AAC1C,MAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,GAAA,CAAI,GAAG,CAAA;AAC3B,MAAA,MAAM,IAAA,GACJ,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,kBAAkB,CAAA,IAAK,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,MAAM,CAAA,IAAK,GAAA,CAAI,IAAA;AACxE,MAAA,MAAM,KAAA,GACJ,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,mBAAmB,KAAK,GAAA,CAAI,QAAA,CAAS,OAAA,CAAQ,GAAA,EAAK,EAAE,CAAA;AACtE,MAAA,MAAM,GAAA,GAAM,MAAM,MAAA,CAAO;AAAA,QACvB,aAAA,EAAe,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,eAAe,CAAA;AAAA,QAC9C,IAAA;AAAA,QACA,QAAQ,KAAA,KAAU;AAAA,OACnB,CAAA;AACD,MAAA,OAAO,QAAA,CAAS,KAAK,GAAA,CAAI,IAAA,EAAM,EAAE,MAAA,EAAQ,GAAA,CAAI,QAAQ,CAAA;AAAA,IACvD;AAAA,GACF;AACF","file":"next.js","sourcesContent":["// @broberg/lens/next — Next.js 16 route-handler adapter.\n//\n// Mount at `app/api/lens-session/route.ts`:\n//\n//   import { createLensRoute } from \"@broberg/lens/next\";\n//   export const { POST } = createLensRoute({\n//     principal: \"lens@myapp.local\",\n//     async createSession({ principal, expiresAt }) {\n//       const value = await signMySessionCookie(principal, expiresAt);\n//       return { name: \"myapp.session_token\", value };\n//     },\n//   });\n//\n// Uses Web `Request`/`Response` — no `next`/`react` import, so it runs on the\n// Node runtime route handlers serve from. (node:crypto in the core means this is\n// NOT for the Edge runtime — mint endpoints hit a DB anyway, so Node is right.)\n\nimport { createLensMintHandler, type LensMintOptions } from \"./index\";\n\nexport function createLensRoute(opts: LensMintOptions): {\n  POST: (req: Request) => Promise<Response>;\n} {\n  const handle = createLensMintHandler(opts);\n  return {\n    async POST(req: Request): Promise<Response> {\n      const url = new URL(req.url);\n      const host =\n        req.headers.get(\"x-forwarded-host\") ?? req.headers.get(\"host\") ?? url.host;\n      const proto =\n        req.headers.get(\"x-forwarded-proto\") ?? url.protocol.replace(\":\", \"\");\n      const res = await handle({\n        authorization: req.headers.get(\"authorization\"),\n        host,\n        secure: proto === \"https\",\n      });\n      return Response.json(res.body, { status: res.status });\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@broberg/lens",
+  "version": "0.1.0",
+  "description": "Make any app Cardmem-Lens-compliant: a headless POST /api/lens-session mint endpoint (narrow Bearer → short-lived, read-only Playwright storageState) so Lens can log past the auth wall and screenshot the real authed surface, incl. prod. Framework-agnostic core + thin Next.js / Hono adapters. Implements the fleet F098.1 mint standard.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "files": ["dist", "README.md"],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js",
+      "require": "./dist/next.cjs"
+    },
+    "./hono": {
+      "types": "./dist/hono.d.ts",
+      "import": "./dist/hono.js",
+      "require": "./dist/hono.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "hono": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "hono": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "hono": "^4.6.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "lens",
+    "cardmem",
+    "visual-regression",
+    "playwright",
+    "storagestate",
+    "auth",
+    "session",
+    "screenshot",
+    "broberg"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/broberg-ai/components",
+    "directory": "packages/lens"
+  },
+  "publishConfig": { "access": "public" }
+}