@broberg/lens-daemon 0.0.0-stage → 0.1.5

package/src/auth/index.ts

@@ -0,0 +1,301 @@
+// 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 { isAbsolute } from 'node:path';
+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) {
+    // F009.22 — a relative path here resolves against the DAEMON's cwd, i.e.
+    // some other repo's secret, which would then be sent to the caller's url.
+    // Callers resolve against their project root first (resolveAuthPaths).
+    if (!isAbsolute(cfg.secretPath)) {
+      throw new Error(`mintEndpoint auth: secretPath must be absolute by the time it is read (got "${cfg.secretPath}") — register the project or pass an absolute path`);
+    }
+    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);
+}