@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/artifact-uploads.ts

@@ -0,0 +1,370 @@
+// F276.1 — every Lens artifact reaches the cloud, so the owner can open it on a phone.
+//
+// THE DEFECT THIS CLOSES, in Christian's words (2026-08-25): "Alle Lens billeder bør da
+// placeres i Cloud så jeg kan tilgå dem fra alle steder og maskiner eller kan jeg jo ikke
+// se dem på min iPhone PWA." He was right, and measuring it found something larger — the
+// whole Lens surface reads from 127.0.0.1, so on a phone it does not merely show broken
+// images, it shows "daemon offline". Lens had never worked on his phone at all.
+//
+// A QUEUE, NOT AN INLINE UPLOAD. Three reasons, each of which has a failure attached:
+//   · a capture must not get slower, or people stop running them;
+//   · an upload failure must not fail the RUN — the local copy is still valid evidence,
+//     and losing a run because object storage hiccuped is the worse outcome;
+//   · the backfill of 6588 historic files (F276.4) is this same operation at scale, so it
+//     uses this machinery rather than a second implementation that drifts from it.
+//
+// WHAT IS DELIBERATELY NOT HERE: deletion. The local copy stays. It is the fast path on
+// the Mac and the fallback when a cloud copy is missing, and removing a working path
+// before its replacement is proven is the naked cutover the harness contract forbids.
+
+import type { Database } from 'bun:sqlite';
+import type { LensStorage } from './storage.ts';
+import type { CloudClientLike } from './service.ts';
+
+/**
+ * The queue's schema, owned by the module that reads and writes it.
+ *
+ * It lives here rather than inline in state.ts so a test can build a real queue table
+ * WITHOUT calling getDb — which is a module-level singleton that ignores its path
+ * argument after the first call. A second test file that touched it handed the next
+ * file someone else's database, and the assertion that failed named a value that test
+ * had never written. One definition, two callers, no copy to drift.
+ */
+export const UPLOAD_QUEUE_DDL = `
+  CREATE TABLE IF NOT EXISTS lens_artifact_uploads (
+    artifact_key TEXT PRIMARY KEY,
+    project_slug TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    cloud_artifact_id TEXT,
+    attempts INTEGER NOT NULL DEFAULT 0,
+    last_error TEXT,
+    enqueued_at INTEGER NOT NULL,
+    uploaded_at INTEGER,
+    claimed_at INTEGER
+  );
+  CREATE INDEX IF NOT EXISTS lens_artifact_uploads_status_idx
+    ON lens_artifact_uploads (status, enqueued_at);
+`;
+
+/** Create the queue table if it is not there. Idempotent. */
+export function ensureUploadQueue(db: Database): void {
+  db.exec(UPLOAD_QUEUE_DDL);
+  // Additive for daemons whose table predates F276.5.
+  try {
+    db.exec('ALTER TABLE lens_artifact_uploads ADD COLUMN claimed_at INTEGER');
+  } catch {
+    // column already exists
+  }
+}
+
+/** A claim older than this is treated as abandoned and returns to the queue. Long
+ *  enough that a genuinely slow 7 MB upload is never stolen mid-flight; short enough
+ *  that a daemon killed mid-batch does not strand its rows for a human to notice. */
+export const CLAIM_TTL_MS = 10 * 60 * 1000;
+
+export interface UploadRow {
+  artifact_key: string;
+  project_slug: string;
+  status: 'pending' | 'uploading' | 'done' | 'failed' | 'skipped';
+  cloud_artifact_id: string | null;
+  attempts: number;
+  last_error: string | null;
+  enqueued_at: number;
+  uploaded_at: number | null;
+}
+
+/** Give up after this many tries. A key that fails five times is broken in a way
+ *  retrying will not fix (bytes gone, file corrupt), and an infinite retry would
+ *  hide it behind a queue that never drains. */
+export const MAX_ATTEMPTS = 5;
+
+/**
+ * Queue an artifact for upload. Idempotent BY THE SCHEMA — artifact_key is the
+ * primary key, so enqueueing the same key twice does nothing.
+ *
+ * That is not a micro-optimisation: F276.4 re-runs the backfill over 6588 files and
+ * must not create 6588 duplicates on the second pass. Expressing it in the table
+ * rather than in a guard means no caller can forget it.
+ */
+export function enqueueArtifact(db: Database, projectSlug: string, key: string | null): void {
+  if (!key) return;
+  db.prepare(
+    `INSERT OR IGNORE INTO lens_artifact_uploads (artifact_key, project_slug, status, enqueued_at)
+     VALUES (?, ?, 'pending', ?)`,
+  ).run(key, projectSlug, Date.now());
+}
+
+/** Queue several at once — the flow path has one per step. */
+export function enqueueArtifacts(db: Database, projectSlug: string, keys: (string | null)[]): void {
+  for (const k of keys) enqueueArtifact(db, projectSlug, k);
+}
+
+export interface DrainResult {
+  /** Uploaded successfully in this pass. */
+  uploaded: number;
+  /** Failed this pass but will be retried. */
+  retryable: number;
+  /** Given up on (attempts exhausted, or the bytes are gone). */
+  abandoned: number;
+  /** Still waiting AFTER this pass — so a caller can tell "done" from "batch full". */
+  remaining: number;
+  /** Why nothing happened, when nothing happened. Stated rather than implied by a
+   *  row of zeros, because "queue empty" and "not signed in" look identical in
+   *  counts and mean completely different things. */
+  idle_reason: string | null;
+}
+
+/**
+ * Upload one batch. Returns counts AND, when nothing moved, the reason.
+ *
+ * The `idle_reason` field exists because of the failure this whole epic is about: a
+ * result of all zeros could mean the queue is empty, or that we are signed out, or
+ * that storage is unprovisioned. Three different situations, one indistinguishable
+ * report — so the reason is stated.
+ */
+export async function drainUploads(
+  db: Database,
+  storage: LensStorage,
+  cloud: CloudClientLike | null,
+  opts: {
+    batch?: number;
+    projectId?: (slug: string) => Promise<string | null>;
+    /** Injectable clock, so the stale-claim path is testable without waiting 10 minutes. */
+    now?: () => number;
+  } = {},
+): Promise<DrainResult> {
+  const empty = (reason: string | null): DrainResult => ({
+    uploaded: 0,
+    retryable: 0,
+    abandoned: 0,
+    remaining: pendingCount(db),
+    idle_reason: reason,
+  });
+
+  if (!cloud) return empty('not signed in to cardmem — run `cardmem login`; nothing was uploaded');
+
+  const batch = Math.max(1, Math.min(opts.batch ?? 25, 200));
+  const now = opts.now?.() ?? Date.now();
+  releaseStaleClaims(db, now);
+  const rows = claimBatch(db, batch, now);
+
+  if (rows.length === 0) {
+    // "Nothing to do" and "another drain has everything claimed" both produce zero rows
+    // and mean opposite things — the first says stop, the second says come back. Say
+    // which one it is rather than letting a row of zeros stand for both.
+    const inFlight = db
+      .query("SELECT COUNT(*) AS n FROM lens_artifact_uploads WHERE status = 'uploading'")
+      .get() as { n: number } | undefined;
+    return empty(
+      Number(inFlight?.n ?? 0) > 0
+        ? `${inFlight!.n} artifact(s) are claimed by another drain in flight — nothing to take right now`
+        : null,
+    );
+  }
+
+  let uploaded = 0;
+  let retryable = 0;
+  let abandoned = 0;
+  const projectIds = new Map<string, string | null>();
+
+  for (const row of rows) {
+    try {
+      // Resolve the cloud project id once per slug per pass. Guessing one would put a
+      // project's screenshots into a different project's store.
+      if (!projectIds.has(row.project_slug)) {
+        projectIds.set(row.project_slug, await resolveProjectId(cloud, row.project_slug, opts.projectId));
+      }
+      const projectId = projectIds.get(row.project_slug);
+      if (!projectId) throw new Error(`project ${row.project_slug} is not known to cardmem`);
+
+      const bytes = await storage.get(row.artifact_key);
+      if (!bytes) {
+        // The row claims an artifact and the storage does not have it. Retrying cannot
+        // conjure bytes, so this is ABANDONED immediately rather than burning five
+        // attempts — and it is recorded as a distinct outcome, because a missing file
+        // is a finding, not a transient error.
+        markFailed(db, row.artifact_key, 'bytes are GONE from local storage', MAX_ATTEMPTS);
+        abandoned++;
+        continue;
+      }
+
+      const placed = await cloud.callTool<{ artifact_id: string }>('cardmem_place_artifact', {
+        project_id: projectId,
+        name: artifactName(row.artifact_key),
+        mime: row.artifact_key.endsWith('.webm') ? 'video/webm' : 'image/png',
+        base64: bytes.toString('base64'),
+        source: 'lens',
+      });
+
+      db.prepare(
+        `UPDATE lens_artifact_uploads
+         SET status = 'done', cloud_artifact_id = ?, uploaded_at = ?, last_error = NULL,
+             attempts = attempts + 1
+         WHERE artifact_key = ?`,
+      ).run(placed.artifact_id, Date.now(), row.artifact_key);
+      uploaded++;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const attempts = row.attempts + 1;
+      markFailed(db, row.artifact_key, msg, attempts);
+      if (attempts >= MAX_ATTEMPTS) abandoned++;
+      else retryable++;
+    }
+  }
+
+  return { uploaded, retryable, abandoned, remaining: pendingCount(db), idle_reason: null };
+}
+
+/**
+ * Take a batch of rows OUT of the pending pool in the same statement that reads them.
+ *
+ * THE BUG THIS CLOSES, measured 2026-08-25: the old code selected `status='pending'`,
+ * uploaded (hundreds of ms of network), and only then wrote `done`. For that whole
+ * window the row still read `pending` to anyone else — and two drains exist by design,
+ * the daemon's 30 s background tick and the HTTP route. On project xrt81-com that put
+ * 16 of 27 files in the cloud twice, ids ~65 ms apart, while the local queue showed a
+ * flawless 27. A count taken on the side that does the writing cannot see a duplicate
+ * it wrote twice.
+ *
+ * `artifact_key` being the PRIMARY KEY makes ENQUEUEING idempotent, which is true and
+ * is an acceptance criterion on F276.4. It says nothing about DRAINING. Idempotent
+ * insert and exactly-once processing are different properties.
+ */
+function claimBatch(db: Database, batch: number, now: number): UploadRow[] {
+  return db
+    .prepare(
+      `UPDATE lens_artifact_uploads
+          SET status = 'uploading', claimed_at = ?
+        WHERE artifact_key IN (
+          SELECT artifact_key FROM lens_artifact_uploads
+           WHERE status = 'pending' AND attempts < ?
+           ORDER BY enqueued_at ASC LIMIT ?
+        )
+        RETURNING *`,
+    )
+    .all(now, MAX_ATTEMPTS, batch) as UploadRow[];
+}
+
+/**
+ * Return rows whose claim went stale to the queue.
+ *
+ * Without this, the cure for double-upload becomes a cause of never-upload: a daemon
+ * killed mid-batch would leave its rows in `uploading` forever, and they would be
+ * invisible to `pending` and to `failed` alike — the silent gap this epic is about,
+ * reintroduced by its own fix.
+ */
+export function releaseStaleClaims(db: Database, now: number = Date.now()): number {
+  const r = db
+    .prepare(
+      `UPDATE lens_artifact_uploads
+          SET status = 'pending', claimed_at = NULL
+        WHERE status = 'uploading' AND (claimed_at IS NULL OR claimed_at < ?)`,
+    )
+    .run(now - CLAIM_TTL_MS);
+  return Number(r.changes ?? 0);
+}
+
+function markFailed(db: Database, key: string, error: string, attempts: number): void {
+  db.prepare(
+    `UPDATE lens_artifact_uploads
+     SET attempts = ?, last_error = ?, status = ?
+     WHERE artifact_key = ?`,
+  ).run(attempts, error.slice(0, 500), attempts >= MAX_ATTEMPTS ? 'failed' : 'pending', key);
+}
+
+/** Rows that are not finished — pending AND in flight elsewhere. A row another drain
+ *  is currently uploading is still not done, and excluding it would make `remaining: 0`
+ *  mean "nothing left" while an upload is still running. */
+function pendingCount(db: Database): number {
+  const r = db
+    .query(
+      `SELECT COUNT(*) AS n FROM lens_artifact_uploads
+        WHERE (status = 'pending' AND attempts < ?) OR status = 'uploading'`,
+    )
+    .get(MAX_ATTEMPTS) as { n: number } | undefined;
+  return Number(r?.n ?? 0);
+}
+
+async function resolveProjectId(
+  cloud: CloudClientLike,
+  slug: string,
+  override?: (slug: string) => Promise<string | null>,
+): Promise<string | null> {
+  if (override) return override(slug);
+  const res = await cloud.callTool<{ projects?: Array<{ id: string; slug: string }> }>(
+    'cardmem_list_projects',
+    {},
+  );
+  return res?.projects?.find((p) => p.slug === slug)?.id ?? null;
+}
+
+/** A readable filename from an artifact key, so the Artifacts surface is browsable
+ *  rather than a wall of hashes. `cardmem/flows/<run>/step-3.png` → `lens-flows-<run>-step-3.png`. */
+export function artifactName(key: string): string {
+  const cleaned = key.replace(/^[^/]+\//, '').replace(/\//g, '-');
+  return `lens-${cleaned}`;
+}
+
+/** What the queue holds, for the surface and for a human asking "is it done yet?". */
+export function uploadStats(db: Database): {
+  pending: number;
+  done: number;
+  failed: number;
+  /** Claimed by a drain and in flight right now (F276.5). Its own bucket: in-flight and
+   *  not-yet-started are different facts, and sharing one value of `status` between them
+   *  is what let two drains upload the same file. */
+  uploading: number;
+  /** Held back on purpose (F276.4). Counted SEPARATELY from failed: one is a decision
+   *  the owner made, the other is something broken, and a queue that shows them as one
+   *  number cannot be used to tell whether the backfill is finished. */
+  skipped: number;
+  total: number;
+  /** pending + uploading + done + failed + skipped. If this ever differs from `total`,
+   *  a row is in a state nothing counts — the silent gap this epic exists to close. */
+  accounted: number;
+} {
+  const row = db
+    .query(
+      `SELECT
+         SUM(CASE WHEN status = 'pending' AND attempts < ? THEN 1 ELSE 0 END) AS pending,
+         SUM(CASE WHEN status = 'done' THEN 1 ELSE 0 END) AS done,
+         SUM(CASE WHEN status = 'failed' OR (status = 'pending' AND attempts >= ?) THEN 1 ELSE 0 END) AS failed,
+         SUM(CASE WHEN status = 'uploading' THEN 1 ELSE 0 END) AS uploading,
+         SUM(CASE WHEN status = 'skipped' THEN 1 ELSE 0 END) AS skipped,
+         COUNT(*) AS total
+       FROM lens_artifact_uploads`,
+    )
+    .get(MAX_ATTEMPTS, MAX_ATTEMPTS) as Record<string, number> | undefined;
+  const pending = Number(row?.pending ?? 0);
+  const done = Number(row?.done ?? 0);
+  const failed = Number(row?.failed ?? 0);
+  const skipped = Number(row?.skipped ?? 0);
+  const uploading = Number(row?.uploading ?? 0);
+  return {
+    pending,
+    done,
+    failed,
+    uploading,
+    skipped,
+    total: Number(row?.total ?? 0),
+    accounted: pending + uploading + done + failed + skipped,
+  };
+}
+
+/** Map artifact keys → their cloud artifact id, for the read path. Only 'done' rows,
+ *  so a queued-but-not-yet-uploaded key resolves to nothing rather than to a url that
+ *  404s — a link in the durable form pointing at nothing is worse than no link. */
+export function cloudIdsFor(db: Database, keys: string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  if (keys.length === 0) return out;
+  const placeholders = keys.map(() => '?').join(',');
+  const rows = db
+    .query(
+      `SELECT artifact_key, cloud_artifact_id FROM lens_artifact_uploads
+       WHERE status = 'done' AND cloud_artifact_id IS NOT NULL
+         AND artifact_key IN (${placeholders})`,
+    )
+    .all(...keys) as Array<{ artifact_key: string; cloud_artifact_id: string }>;
+  for (const r of rows) out.set(r.artifact_key, r.cloud_artifact_id);
+  return out;
+}

package/src/auth/index.ts

@@ -0,0 +1,294 @@
+// F074.4 — Lens auth as a pluggable pre-step.
+//
+// Capturing an authenticated surface must not assume one auth model. An auth
+// adapter runs against a fresh browser context BEFORE the page loads, leaving
+// it authenticated — exactly the `prepareContext` hook browser.ts/capture.ts
+// already expose.
+//
+// SECURITY: the actual secret (a session token / a storageState file holding
+// a session cookie) is NEVER passed in the capture call. The call names an
+// adapter + non-secret params (cookie name, domain, which ENV VAR holds the
+// secret); the daemon resolves the secret from its own env. So a project's
+// MCP/HTTP request can request an authenticated capture without ever
+// transmitting the credential.
+//
+// Two adapters ship first:
+//   - storageState : Playwright's storageState JSON (cookies + localStorage).
+//                    Covers cardmem's Better Auth signed session cookie —
+//                    reuses the artifact F037's auth.setup.ts already produces.
+//   - cookieJwt    : a single named cookie holding a JWT. Covers cms.
+
+import { readFileSync } from 'node:fs';
+import type { BrowserContext } from 'playwright';
+
+export type AuthEnv = Record<string, string | undefined>;
+
+export interface StorageStateAuth {
+  adapter: 'storageState';
+  /** Name of the env var holding either a path to a storageState.json or the
+   *  JSON itself. Default LENS_STORAGE_STATE. */
+  stateEnv?: string;
+  /** F074.12 — direct path to a storageState.json on the daemon host. When set,
+   *  used WITHOUT env indirection, so a credential can be injected without a
+   *  daemon restart (env vars only reach NEW launchd spawns). A relative path is
+   *  resolved against the repo root by loadManifest. The path is NOT a secret —
+   *  the gitignored file it points at is — so this preserves "secret never in
+   *  the call". Takes precedence over stateEnv. */
+  statePath?: string;
+}
+
+export interface CookieJwtAuth {
+  adapter: 'cookieJwt';
+  /** Cookie name to set (e.g. "projects.session_token"). */
+  cookieName: string;
+  /** Cookie domain (e.g. "localhost"). */
+  domain: string;
+  /** Cookie path. Default "/". */
+  path?: string;
+  /** Name of the env var holding the token value. Secret never in the call. */
+  tokenEnv: string;
+  httpOnly?: boolean;
+  secure?: boolean;
+}
+
+export interface MintEndpointAuth {
+  adapter: 'mintEndpoint';
+  /** URL the daemon POSTs (with the secret) just before capture. The endpoint
+   *  mints a SHORT-LIVED, READ-ONLY session and returns it as a Playwright
+   *  storageState JSON ({cookies, origins}). */
+  url: string;
+  /** HTTP method. Default POST. */
+  method?: 'POST' | 'GET';
+  /** Env var holding the narrow "mint a lens session" secret (NOT an admin
+   *  session). Sent as `Authorization: Bearer <secret>`. */
+  secretEnv?: string;
+  /** OR a gitignored file holding the secret (relative path → resolved against
+   *  the repo root by loadManifest). Avoids the env-var restart friction.
+   *  Takes precedence over secretEnv. */
+  secretPath?: string;
+  /** Optional extra non-secret headers. */
+  headers?: Record<string, string>;
+  /** Optional JSON body sent with the (POST) mint call — e.g. `{org, site}` so
+   *  the endpoint can mint a session targeting a SPECIFIC site on-demand instead
+   *  of a fixed LENS_ACTIVE_ORG/SITE env default (the cms F151 org/site pattern).
+   *  Validated by the endpoint against its site registry; never carries a secret.
+   *  Ignored for GET. */
+  body?: Record<string, unknown>;
+}
+
+export type AuthConfig = StorageStateAuth | CookieJwtAuth | MintEndpointAuth;
+
+interface StorageStateShape {
+  cookies?: Array<Record<string, unknown>>;
+  origins?: Array<{ origin: string; localStorage?: Array<{ name: string; value: string }> }>;
+}
+
+async function applyStorageState(
+  context: BrowserContext,
+  cfg: StorageStateAuth,
+  env: AuthEnv,
+): Promise<void> {
+  // F074.12 — statePath (a filesystem path, already absolutised by loadManifest)
+  // wins over the env-var indirection. Either way `raw` is a path or inline JSON.
+  let raw: string | undefined;
+  let sourceLabel: string;
+  if (cfg.statePath) {
+    raw = cfg.statePath;
+    sourceLabel = `statePath ${cfg.statePath}`;
+  } else {
+    const name = cfg.stateEnv ?? 'LENS_STORAGE_STATE';
+    raw = env[name];
+    sourceLabel = `env ${name}`;
+    if (!raw) throw new Error(`storageState auth: set auth.statePath or ${sourceLabel}`);
+  }
+  let json: StorageStateShape;
+  try {
+    json = raw.trim().startsWith('{')
+      ? (JSON.parse(raw) as StorageStateShape)
+      : (JSON.parse(readFileSync(raw, 'utf-8')) as StorageStateShape);
+  } catch (err) {
+    throw new Error(`storageState auth: could not load ${sourceLabel}: ${err instanceof Error ? err.message : err}`);
+  }
+  await applyStorageStateJson(context, json);
+}
+
+/** F074.22 — Chromium's CDP setCookie silently rejects a `secure` / `__Secure-` /
+ *  `__Host-` cookie set with only `domain` (no `url`): the source scheme is read
+ *  as non-secure, so a Secure cookie is refused and never lands — the next
+ *  navigation then redirects to login (a mystery 307). curl has no such
+ *  source-scheme check, which is why the SAME cookie value authenticates via curl
+ *  but not via Playwright. Synthesize an `https://<host><path>` url so the secure
+ *  source is explicit and the cookie is accepted.
+ *
+ *  F236.fix — but ONLY for cookies that are already host-scoped. A url makes the
+ *  cookie HOST-ONLY (Playwright can't take url+domain together), so collapsing a
+ *  DOMAIN-WIDE cookie (leading-dot domain, e.g. `.cardmem.com` — valid on the apex
+ *  AND every subdomain) to `https://cardmem.com/` silently dropped it on every
+ *  subdomain navigation (www.cardmem.com, app.trailmem.com) → login. The leading
+ *  dot is the RFC-6265 / Playwright signal for a domain cookie: keep `domain`+`path`
+ *  for those so they still reach subdomains. Host-specific secure cookies (no dot)
+ *  and `__Host-` (which MUST be host-only per spec) keep the url synthesis. */
+export function prepareCookies(
+  cookies: Array<Record<string, unknown>>,
+): Array<Record<string, unknown>> {
+  return cookies.map((c) => {
+    const name = typeof c.name === 'string' ? c.name : '';
+    const isSecure = c.secure === true || name.startsWith('__Secure-') || name.startsWith('__Host-');
+    if (!isSecure || c.url || typeof c.domain !== 'string') return c;
+    const domain = c.domain as string;
+    // A leading-dot domain is domain-wide (apex + all subdomains). `__Host-` is the
+    // one exception: the prefix REQUIRES a host-only cookie, so it always takes the
+    // url path even with a dotted domain.
+    const domainWide = domain.startsWith('.') && !name.startsWith('__Host-');
+    if (domainWide) return c; // keep domain+path so subdomains still get the cookie
+    const host = domain.replace(/^\./, '');
+    const path = typeof c.path === 'string' ? c.path : '/';
+    const { domain: _domain, path: _path, ...rest } = c;
+    return { ...rest, url: `https://${host}${path}` };
+  });
+}
+
+/** Apply a Playwright storageState shape (cookies + localStorage) to a context.
+ *  Shared by the storageState adapter and the mintEndpoint adapter (which fetches
+ *  the same shape just-in-time). */
+async function applyStorageStateJson(context: BrowserContext, json: StorageStateShape): Promise<void> {
+  if (json.cookies?.length) {
+    // Secure/prefixed cookies with only a domain need a synthesized https url
+    // (see prepareCookies) — else Chromium silently drops them.
+    await context.addCookies(prepareCookies(json.cookies) as unknown as Parameters<BrowserContext['addCookies']>[0]);
+    // F074.22 — LENS_AUTH_DEBUG surfaces what Chromium actually RETAINED after
+    // apply (values never logged), so a failed authed capture is evidence, not a
+    // mystery. A cookie that was dropped simply won't appear here.
+    if (process.env.LENS_AUTH_DEBUG) {
+      const retained = await context.cookies();
+      console.error(
+        '[lens-auth] cookies retained after apply:',
+        JSON.stringify(retained.map((c) => ({ name: c.name, domain: c.domain, path: c.path, secure: c.secure, httpOnly: c.httpOnly, expires: c.expires }))),
+      );
+    }
+  }
+  for (const o of json.origins ?? []) {
+    const items = o.localStorage ?? [];
+    if (!items.length) continue;
+    await context.addInitScript(
+      (payload: { origin: string; items: Array<{ name: string; value: string }> }) => {
+        if (location.origin === payload.origin) {
+          for (const it of payload.items) localStorage.setItem(it.name, it.value);
+        }
+      },
+      { origin: o.origin, items },
+    );
+  }
+}
+
+// F074.13 — mintEndpoint: the daemon POSTs to a protected endpoint on the target
+// app just before capture, which mints a SHORT-LIVED, READ-ONLY session and
+// returns it as a Playwright storageState JSON ({cookies, origins}). The daemon
+// applies it to the fresh context and discards it with the context after the
+// capture. No standing credential sits anywhere: scope is read-only, lifetime is
+// minutes, exposure is nothing-on-disk + nothing-in-the-cc-transcript (daemon-
+// minted), and injection needs no daemon restart. The only stored secret is a
+// NARROW "mint a lens session" key (NOT an admin session), via secretEnv or a
+// gitignored secretPath.
+async function applyMintEndpoint(
+  context: BrowserContext,
+  cfg: MintEndpointAuth,
+  env: AuthEnv,
+): Promise<void> {
+  // Resolve the narrow mint secret — secretPath (gitignored file, no restart)
+  // wins over secretEnv. The secret is NOT in the manifest/call, only its source.
+  let secret: string | undefined;
+  if (cfg.secretPath) {
+    try {
+      secret = readFileSync(cfg.secretPath, 'utf-8').trim();
+    } catch (err) {
+      throw new Error(`mintEndpoint auth: could not read secretPath ${cfg.secretPath}: ${err instanceof Error ? err.message : err}`);
+    }
+  } else if (cfg.secretEnv) {
+    secret = env[cfg.secretEnv];
+    if (!secret) throw new Error(`mintEndpoint auth: env ${cfg.secretEnv} is not set`);
+  } else {
+    throw new Error('mintEndpoint auth: set auth.secretPath or auth.secretEnv');
+  }
+
+  // Optional JSON body (POST only) — lets the endpoint mint a session for a
+  // SPECIFIC org/site rather than a fixed env default. GET can't carry a body.
+  const method = cfg.method ?? 'POST';
+  const sendBody = method !== 'GET' && cfg.body != null;
+  let res: Response;
+  try {
+    res = await fetch(cfg.url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${secret}`,
+        Accept: 'application/json',
+        ...(sendBody ? { 'Content-Type': 'application/json' } : {}),
+        ...(cfg.headers ?? {}),
+      },
+      ...(sendBody ? { body: JSON.stringify(cfg.body) } : {}),
+    });
+  } catch (err) {
+    throw new Error(`mintEndpoint auth: request to ${cfg.url} failed: ${err instanceof Error ? err.message : err}`);
+  }
+  if (!res.ok) {
+    throw new Error(`mintEndpoint auth: ${cfg.url} returned ${res.status} ${res.statusText}`);
+  }
+  let json: StorageStateShape;
+  try {
+    json = (await res.json()) as StorageStateShape;
+  } catch (err) {
+    throw new Error(`mintEndpoint auth: ${cfg.url} did not return JSON storageState: ${err instanceof Error ? err.message : err}`);
+  }
+  if (!json.cookies?.length && !json.origins?.length) {
+    throw new Error(`mintEndpoint auth: ${cfg.url} returned a storageState with no cookies/origins`);
+  }
+  await applyStorageStateJson(context, json);
+}
+
+async function applyCookieJwt(
+  context: BrowserContext,
+  cfg: CookieJwtAuth,
+  env: AuthEnv,
+): Promise<void> {
+  const token = env[cfg.tokenEnv];
+  if (!token) throw new Error(`cookieJwt auth: env ${cfg.tokenEnv} is not set`);
+  await context.addCookies([
+    {
+      name: cfg.cookieName,
+      value: token,
+      domain: cfg.domain,
+      path: cfg.path ?? '/',
+      httpOnly: cfg.httpOnly ?? true,
+      secure: cfg.secure ?? false,
+      sameSite: 'Lax',
+    },
+  ]);
+}
+
+/** Run the configured auth adapter against a fresh context. */
+export async function applyAuth(
+  context: BrowserContext,
+  cfg: AuthConfig,
+  env: AuthEnv = process.env,
+): Promise<void> {
+  switch (cfg.adapter) {
+    case 'storageState':
+      return applyStorageState(context, cfg, env);
+    case 'cookieJwt':
+      return applyCookieJwt(context, cfg, env);
+    case 'mintEndpoint':
+      return applyMintEndpoint(context, cfg, env);
+    default:
+      throw new Error(`unknown auth adapter: ${(cfg as AuthConfig).adapter}`);
+  }
+}
+
+/** Resolve an AuthConfig to a `prepareContext` callback the capture/verify
+ *  layer can pass straight through. Returns undefined when cfg is absent. */
+export function authPrepare(
+  cfg: AuthConfig | undefined,
+  env: AuthEnv = process.env,
+): ((context: BrowserContext) => Promise<void>) | undefined {
+  if (!cfg) return undefined;
+  return (context: BrowserContext) => applyAuth(context, cfg, env);
+}