@crouton-kit/capture 1.4.2 → 1.4.11

package/src/session/coordinator.ts

@@ -161,103 +161,10 @@ export async function beginSessionStop(sessionDir: string): Promise<SessionStopA
   };
 }
 
-// ---------------------------------------------------------------------------
-// Neutral recorder-handle scan + lifecycle transaction. Owned here so tab/reset
-// and recorder start never import a motion feature (A2). Motion CONSEQUENCES
-// (orphan finalize, markers/meta, viewport restore) stay in recorder.ts.
-// ---------------------------------------------------------------------------
-
-export interface RecorderHandleRecord {
-  recId: string; pid: number; socketPath: string; targetId: string;
-  url: string | null; startedAt: string; state: string; birth: PidBirth; markers: unknown;
-  /** The recording's control-socket admission token (64 lowercase hex chars,
-   * server-generated by the recorder bridge at boot). Required — a handle
-   * without a structurally valid nonce is malformed; there is no
-   * unauthenticated or legacy handle shape. */
-  nonce: string;
-}
-export type RecorderHandleClassification = 'live' | 'dead' | 'malformed' | 'unknown';
-export interface ScannedRecorderHandle {
-  recId: string; recDir: string; classification: RecorderHandleClassification;
-  record: RecorderHandleRecord | null; // null iff malformed
-}
 export interface LifecycleSeams {
   pidBirthProvider?: PidBirthProvider; nowNs?: () => bigint;
   sleep?: (ms: number) => Promise<void>; token?: () => string;
   acquireTimeoutMs?: number; leaseMs?: number;
-  /** How long a graceful recorder stop waits for the bridge process's own
-   * verified exit before escalating to an identity-checked SIGTERM
-   * (default ~2000ms) — injectable so tests with never-exiting placeholder
-   * children stay fast. */
-  stopExitTimeoutMs?: number;
-}
-
-/** Structural gate for a recorder control-socket nonce — the exact shape the
- * bridge generates (`crypto.randomBytes(32).toString('hex')`). */
-export const RECORDER_NONCE = /^[0-9a-f]{64}$/;
-
-function parseRecorderHandle(raw: unknown): RecorderHandleRecord | null {
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
-  const r = raw as Record<string, unknown>;
-  if (typeof r.recId !== 'string' || !r.recId) return null;
-  if (!Number.isSafeInteger(r.pid) || (r.pid as number) <= 0) return null;
-  if (typeof r.socketPath !== 'string' || !r.socketPath) return null;
-  if (typeof r.targetId !== 'string' || !r.targetId) return null;
-  if (!(r.url === null || typeof r.url === 'string')) return null;
-  if (typeof r.startedAt !== 'string' || !r.startedAt) return null;
-  if (typeof r.state !== 'string' || !r.state) return null;
-  if (!isBirth(r.birth)) return null;
-  if (typeof r.nonce !== 'string' || !RECORDER_NONCE.test(r.nonce)) return null;
-  return { recId: r.recId, pid: r.pid as number, socketPath: r.socketPath, targetId: r.targetId,
-    url: r.url as string | null, startedAt: r.startedAt, state: r.state, birth: r.birth as PidBirth, markers: r.markers,
-    nonce: r.nonce };
-}
-
-/** True iff the recorded process is the same birth-identity still alive. */
-export function recorderProcessAlive(record: Pick<RecorderHandleRecord, 'pid' | 'birth'>, provider: PidBirthProvider = processPidBirthProvider): boolean {
-  const now = provider.read(record.pid);
-  return now.status === 'found' && sameBirth(now.identity, record.birth);
-}
-
-export function scanRecorderHandles(sessionDir: string, seams: LifecycleSeams = {}): ScannedRecorderHandle[] {
-  const provider = seams.pidBirthProvider ?? processPidBirthProvider;
-  const recsRoot = path.join(assertUnderCaptureRoot(sessionDir), 'motion', 'recs');
-  let entries: fs.Dirent[];
-  try { entries = fs.readdirSync(recsRoot, { withFileTypes: true }); }
-  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error; }
-  const out: ScannedRecorderHandle[] = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const recDir = path.join(recsRoot, entry.name);
-    let raw: unknown;
-    try { raw = JSON.parse(readPrivateFile(path.join(recDir, 'recorder.json')).toString('utf-8')); }
-    catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue; // no handle
-      out.push({ recId: entry.name, recDir, classification: 'malformed', record: null }); continue;
-    }
-    const record = parseRecorderHandle(raw);
-    if (!record) { out.push({ recId: entry.name, recDir, classification: 'malformed', record: null }); continue; }
-    const read = provider.read(record.pid);
-    const classification: RecorderHandleClassification =
-      read.status === 'unknown' ? 'unknown'
-      : (read.status === 'found' && sameBirth(read.identity, record.birth) && record.state === 'recording') ? 'live'
-      : 'dead';
-    out.push({ recId: entry.name, recDir, classification, record });
-  }
-  return out;
-}
-
-/** Reset-time pointer hygiene: reset does NOT remove dead handles — it only
- * clears a session pointer that no longer names a LIVE recorder. Dead handles
- * are left intact so motion's own reapDeadHandles / session-stop teardown
- * orphan-finalizes them on the next start/stop, preserving their partial frames
- * as meta.json in the bundle. */
-export async function clearDanglingRecorderPointer(sessionDir: string, scan: ScannedRecorderHandle[]): Promise<void> {
-  const active = getActiveSession();
-  if (active && active.dir === sessionDir && active.activeRecId
-      && !scan.some(h => h.recId === active.activeRecId && h.classification === 'live')) {
-    await updateSessionState(sessionDir, { activeRecId: null });
-  }
 }
 
 export async function withSessionLifecycle<T>(sessionDir: string, action: () => Promise<T>, seams: LifecycleSeams = {}): Promise<T> {

package/src/session/har-redact.ts

@@ -1,30 +1,30 @@
 /**
- * Render-time credential redaction for HAR request URLs — the ONE narrow
- * carve-out in Capture's otherwise no-redaction posture.
+ * Render-time credential redaction for HAR request URLs and header values —
+ * the ONE narrow carve-out in Capture's otherwise no-redaction posture.
  *
  * Capture preserves browser evidence rather than redacting it, and the HAR
  * artifact on disk remains full fidelity: this module is applied only where a
- * URL is rendered into a `session har` block, never on collection, never on
- * the stored `har.json`/live NDJSON, and never on the value a `--filter-url`
- * pattern is matched against. Its whole job is to keep a dashboard/API session
- * token out of an agent's transcript and terminal scrollback while leaving the
- * request itself identifiable — the parameter name, ordering, and every
- * non-credential value survive untouched, so the row still joins to the
+ * URL or header is rendered into a `session har` block, never on collection,
+ * never on the stored `har.json`/live NDJSON, and never on the value a
+ * `--filter-url` pattern is matched against. Its whole job is to keep a
+ * dashboard/API session token out of an agent's transcript and terminal
+ * scrollback while leaving the request identifiable — names, ordering, and
+ * every non-credential value survive untouched, so the row still joins to the
  * artifact record it came from.
  *
- * Matching is on the parameter NAME only; no value is ever inspected, so this
- * cannot depend on the shape of any observed secret.
+ * Matching is on the name only; no value is ever inspected, so this cannot
+ * depend on the shape of any observed secret.
  */
 
 /** Replacement text for a credential-like parameter value in rendered output. */
 export const REDACTED_VALUE = 'REDACTED';
 
 /**
- * Parameter names that are credential-bearing on their own. Compared after
- * normalization (lowercased, every non-alphanumeric character dropped), so
- * `api_key`, `API-Key`, and `apiKey` all reduce to `apikey`.
+ * Credential-bearing names. Compared after normalization (lowercased, every
+ * non-alphanumeric character dropped), so `api_key`, `API-Key`, and `apiKey`
+ * all reduce to `apikey`.
  */
-const CREDENTIAL_PARAM_NAMES: ReadonlySet<string> = new Set([
+const CREDENTIAL_NAMES: ReadonlySet<string> = new Set([
   'key',
   'apikey',
   'accesskey',
@@ -49,11 +49,11 @@ const CREDENTIAL_PARAM_NAMES: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Fragments that make ANY containing parameter name credential-bearing —
+ * Fragments that make ANY containing name credential-bearing —
  * `access_token`, `refresh-token`, `clientSecret`, `x-amz-signature`, and the
  * rest of the long tail no exact list keeps up with.
  */
-const CREDENTIAL_PARAM_FRAGMENTS: readonly string[] = [
+const CREDENTIAL_NAME_FRAGMENTS: readonly string[] = [
   'token',
   'secret',
   'password',
@@ -65,9 +65,10 @@ const CREDENTIAL_PARAM_FRAGMENTS: readonly string[] = [
   'signature',
   'authorization',
   'sessionid',
+  'loid',
 ];
 
-function normalizeParamName(raw: string): string {
+function normalizeCredentialName(raw: string): string {
   let decoded = raw;
   try {
     decoded = decodeURIComponent(raw.replace(/\+/g, ' '));
@@ -77,12 +78,17 @@ function normalizeParamName(raw: string): string {
   return decoded.toLowerCase().replace(/[^a-z0-9]/g, '');
 }
 
-/** Whether a query/fragment parameter name names a credential. */
-export function isCredentialParamName(raw: string): boolean {
-  const name = normalizeParamName(raw);
+/** Whether a query parameter or header name names a credential. */
+export function isCredentialName(raw: string): boolean {
+  const name = normalizeCredentialName(raw);
   if (name === '') return false;
-  if (CREDENTIAL_PARAM_NAMES.has(name)) return true;
-  return CREDENTIAL_PARAM_FRAGMENTS.some((fragment) => name.includes(fragment));
+  if (CREDENTIAL_NAMES.has(name)) return true;
+  return CREDENTIAL_NAME_FRAGMENTS.some((fragment) => name.includes(fragment));
+}
+
+/** Render a credential-valued header without exposing its value. */
+export function redactHeaderCredential(name: string, value: string): string {
+  return isCredentialName(name) ? `redacted · ${value.length} chars` : value;
 }
 
 /** Redacts credential values in one `a=1&b=2` parameter section. */
@@ -93,7 +99,7 @@ function redactParamSection(section: string): string {
       const eq = pair.indexOf('=');
       if (eq < 0) return pair;
       const name = pair.slice(0, eq);
-      return isCredentialParamName(name) ? `${name}=${REDACTED_VALUE}` : pair;
+      return isCredentialName(name) ? `${name}=${REDACTED_VALUE}` : pair;
     })
     .join('&');
 }

package/src/session-context.ts

@@ -16,6 +16,7 @@ import {
   ensurePrivateDir,
   parseRegisteredLogTailer,
   readPrivateFile,
+  registerArtifactRoot,
   removeArtifactTree,
   unlinkPrivateFile,
   writeJsonPrivate,
@@ -165,6 +166,7 @@ export function isActiveStateCandidate(value: unknown): value is ActiveSessionSt
     && validLogs
     && (record.port === undefined || record.port === null || (Number.isInteger(record.port) && (record.port as number) > 0 && (record.port as number) <= 65535))
     && nullableString(record.bridgeSocket)
+    && (record.networkOffline === undefined || typeof record.networkOffline === 'boolean')
     && nullablePid(record.bridgePid)
     && nullableString(record.activeRecId)
     && nullableString(record.stoppedAt)
@@ -202,6 +204,14 @@ function clearActiveEntry(expected: ActiveEntryIdentity | null): void {
  * preserves a stale pointer for the invocation error path. Normal command
  * consumers retain the default eager stale-index cleanup.
  */
+export function readSessionState(sessionDir: string): ActiveSessionState {
+  const canonical = assertUnderCaptureRoot(path.resolve(sessionDir));
+  const raw = readPrivateFile(sessionMetaPath(canonical)).toString('utf-8');
+  const parsed = JSON.parse(raw) as unknown;
+  if (!isActiveStateCandidate(parsed) || parsed.dir !== canonical) throw new Error(`invalid session metadata: ${sessionMetaPath(canonical)}`);
+  return parsed;
+}
+
 export function getActiveSession({ cleanStale = true }: { cleanStale?: boolean } = {}): ActiveSessionState | null {
   const pointer = readActivePointer();
   const clean = (): void => { if (cleanStale) clearActiveEntry(pointer.entry); };
@@ -212,6 +222,7 @@ export function getActiveSession({ cleanStale = true }: { cleanStale?: boolean }
   }
 
   try {
+    registerArtifactRoot(path.dirname(path.resolve(index.dir)));
     const sessionDir = assertUnderCaptureRoot(path.resolve(index.dir));
     if (sessionDir !== index.dir) throw new Error('active session directory escaped capture root');
 
@@ -223,15 +234,8 @@ export function getActiveSession({ cleanStale = true }: { cleanStale?: boolean }
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
     }
 
-    const raw = readPrivateFile(sessionMetaPath(sessionDir)).toString('utf-8');
-    const parsed = JSON.parse(raw) as unknown;
-    if (!isActiveStateCandidate(parsed)) {
-      clean();
-      return null;
-    }
-
-    const state = parsed as ActiveSessionState;
-    if (state.sessionId !== index.sessionId || state.dir !== sessionDir) {
+    const state = readSessionState(sessionDir);
+    if (state.sessionId !== index.sessionId) {
       clean();
       return null;
     }

package/src/cdp/bridge/protocol.ts

@@ -1,224 +0,0 @@
-/**
- * Wire protocol between `capture cdp --browser` and the held bridge process
- * (`capture __bridge-serve`). Newline-delimited JSON over a Unix domain
- * socket — one request per connection, one response, then the socket closes.
- */
-
-export interface BridgeRequest {
-  reqId: number;
-  /** CDP method, e.g. "Browser.grantPermissions". Omit when only waiting for an event. */
-  method?: string;
-  params?: Record<string, unknown>;
-  /**
-   * Target (page or worker) to scope this call to, via a flattened
-   * `Target.attachToTarget` session on the SAME held browser websocket.
-   * Required for domains that live on a target rather than the browser
-   * itself (`ServiceWorker.*`, `Page.*`, ...) — omit for pure browser-level
-   * domains (`Browser.*`, `Target.*`).
-   */
-  targetId?: string;
-  /** CDP event name to observe after this request is armed. Observation is future-only and scoped to this request's actual flattened target session (`undefined` without `targetId`); one event broadcasts to all already-armed same-key requests. */
-  waitEvent?: string;
-  timeoutMs?: number;
-}
-
-export interface BridgeResponseOk {
-  reqId: number;
-  ok: true;
-  result?: unknown;
-  event?: unknown;
-}
-
-export interface BridgeResponseErr {
-  reqId: number;
-  ok: false;
-  error: string;
-}
-
-export type BridgeResponse = BridgeResponseOk | BridgeResponseErr;
-
-// ---------------------------------------------------------------------------
-// Recorder-mode protocol — the SAME NDJSON-over-unix-socket wire format as
-// above, specialized for `capture motion rec` (see ../recorder-bridge.ts).
-// The generic `BridgeRequest`/`BridgeResponse` are unchanged and still
-// govern `capture cdp --browser` / `session start --hold`; a recorder-mode
-// bridge process (spawned in recorder mode, see ../bridge/spawn.ts) speaks
-// this union instead, one request per connection, one response, same as
-// the plain bridge.
-// ---------------------------------------------------------------------------
-
-/**
- * The three-way clock baseline the design's "Recorder timing model" requires to convert
- * screencast-frame and Tracing timestamps into the authoritative `performance.now()` domain.
- * `performanceNowMs`/`wallClockMs` are read synchronously when the recorder arms (`rec-start`);
- * `firstScreencastTimestampSec`/`firstTraceEventTsUs` cannot be — no frame or trace batch has
- * necessarily arrived yet at that instant — so they are filled in opportunistically as the
- * recorder's own screencast/tracing handlers observe the first occurrence of each, and stay
- * `null` (with `baselinesPending: true`) until then. `rec-stop`'s response carries the same
- * object read again at stop time — the flush path a caller uses to get the completed baselines
- * for `markers.json` even when `rec-start`'s own response returned it still pending.
- */
-export interface RecorderClockBaselines {
-  performanceNowMs: number;
-  wallClockMs: number;
-  /** First `Page.screencastFrame`'s `metadata.timestamp` (wall-clock seconds), or `null` if none had arrived yet at the moment this snapshot was taken. */
-  firstScreencastTimestampSec: number | null;
-  /** First `Tracing.dataCollected` batch's earliest event `ts` (trace-clock microseconds), or `null` if none had arrived yet at the moment this snapshot was taken. */
-  firstTraceEventTsUs: number | null;
-  /** `true` while either timestamp above is still `null`. */
-  baselinesPending: boolean;
-}
-
-/**
- * Arms the recorder on its held tab connection: enables the motion-rec CDP
- * domains, starts `Page.startScreencast` + `Tracing`, injects the
- * Mutation/Resize/Performance observers, and captures the clock baseline.
- * A recorder process only accepts one `rec-start` while `state==="idle"`.
- *
- * `nonce` (here and on every other recorder request shape) is the
- * per-recording control-socket admission token: the recorder bridge process
- * generates it at boot (64 lowercase hex chars, 256 bits) and hands it back
- * to its starter over a private boot file; every request line must carry it
- * verbatim, and the server constant-time-compares it BEFORE any handler
- * runs. There is no unauthenticated request shape and no compatibility
- * lane — a missing or mismatched nonce is answered `ok:false error:
- * 'unauthorized'` with no side effects.
- */
-export interface RecStartRequest {
-  reqId: number;
-  type: 'rec-start';
-  /** Per-recording control-socket admission token — see the doc comment above. */
-  nonce: string;
-}
-
-export interface RecStartResponseOk {
-  reqId: number;
-  ok: true;
-  type: 'rec-start';
-  /** Returned for the caller to persist into `markers.json` — the recorder itself does not write that file. */
-  markers: RecorderClockBaselines;
-}
-
-/**
- * Stops screencast + tracing, flushes the injected observers, and tears
- * down the recorder's subscriptions (not the socket — the caller closes
- * the bridge process once it has read the response). Returns counts for
- * the caller's `meta.json`; the recorder itself does not write that file.
- */
-export interface RecStopRequest {
-  reqId: number;
-  type: 'rec-stop';
-  /** Per-recording control-socket admission token — see `RecStartRequest`. */
-  nonce: string;
-}
-
-export interface RecStopResponseOk {
-  reqId: number;
-  ok: true;
-  type: 'rec-stop';
-  frameCount: number;
-  eventCount: number;
-  durationMs: number;
-  /** The clock baselines re-read at stop time — the flush path for a `rec-start` response whose baselines were still pending. */
-  markers: RecorderClockBaselines;
-}
-
-/**
- * A CDP request routed through the recorder's held tab connection — the
- * mechanism intervening session commands (`click`, `type`, `navigate`, ...)
- * use during a composed recording. Setting `mark` brackets the dispatch
- * with two performance.now() reads taken in the page's execution context
- * (`../timing.ts`'s `withDocumentPerformanceNow`) and appends a labeled
- * input-landmark record to `events.jsonl`, tying the action to the frame
- * timeline — this is the "marked CDP request message" the protocol
- * supports. Omit `mark` for a plain passthrough call (still observed
- * natively by the recorder's own event subscriptions, just not logged as a
- * distinct input landmark). Omit `method` for a wait-event-only request;
- * the bridge arms a future-only wait on the recorder tab websocket's
- * unscoped event envelope and returns the matched event in one response.
- */
-export interface RecCdpDispatchRequest {
-  reqId: number;
-  type: 'cdp';
-  /** Per-recording control-socket admission token — see `RecStartRequest`. */
-  nonce: string;
-  method: string;
-  params?: Record<string, unknown>;
-  mark?: string;
-  waitEvent?: string;
-  timeoutMs?: number;
-}
-
-export interface RecCdpWaitEventRequest {
-  reqId: number;
-  type: 'cdp';
-  /** Per-recording control-socket admission token — see `RecStartRequest`. */
-  nonce: string;
-  method?: undefined;
-  waitEvent: string;
-  timeoutMs?: number;
-}
-
-export type RecCdpRequest = RecCdpDispatchRequest | RecCdpWaitEventRequest;
-
-export interface RecCdpResponseOk {
-  reqId: number;
-  ok: true;
-  type: 'cdp';
-  result?: unknown;
-  event?: unknown;
-  /**
-   * Present iff this request armed a `waitEvent` AND carried a `method`. It
-   * reports the load-wait outcome SEPARATELY from the method result: a method
-   * dispatch that succeeds is always `ok:true` with its `result` preserved,
-   * regardless of whether the paired wait observed its event
-   * (`'observed'`, with `event` set) or the wait's own bounded timer elapsed
-   * first (`'bounded-timeout'`, no `event`). A wait-event-ONLY request (no
-   * `method`) whose wait times out is still `ok:false` — that path has no
-   * method result to preserve, so its timeout is a genuine failure.
-   */
-  waitOutcome?: 'observed' | 'bounded-timeout';
-}
-
-/**
- * The action-return HAR flush/health barrier. A recorder-routed page action
- * (`click`, `type`, `scroll`, `exec`, `navigate`) sends this after its settle
- * window and before claiming success, so every HAR entry/body/append the
- * recorder's streaming collector had already completed by then is durably in
- * the owning session's live HAR first. Deliberately NON-attributing: the
- * response reports store health only — `ok:true` means "all work completed at
- * request time has appended and no fatal store error is latched"; it never
- * says which entries belong to which action and carries no counts (the
- * collector cannot truthfully attribute concurrent traffic to one action).
- * Once the terminal `rec-stop` latch is claimed, HAR finalization belongs to
- * that one owner and a later `har-flush` is answered with a deterministic
- * `ok:false` rejection instead of sharing or re-driving the drain.
- */
-export interface RecHarFlushRequest {
-  reqId: number;
-  type: 'har-flush';
-  /** Per-recording control-socket admission token — see `RecStartRequest`. */
-  nonce: string;
-}
-
-/** Health-only: success carries no result fields beyond the envelope — see `RecHarFlushRequest`. */
-export interface RecHarFlushResponseOk {
-  reqId: number;
-  ok: true;
-  type: 'har-flush';
-}
-
-export type RecorderRequest = RecStartRequest | RecStopRequest | RecCdpRequest | RecHarFlushRequest;
-
-export interface RecorderResponseErr {
-  reqId: number;
-  ok: false;
-  type: RecorderRequest['type'];
-  error: string;
-}
-
-export type RecStartResponse = RecStartResponseOk | RecorderResponseErr;
-export type RecStopResponse = RecStopResponseOk | RecorderResponseErr;
-export type RecCdpResponse = RecCdpResponseOk | RecorderResponseErr;
-export type RecHarFlushResponse = RecHarFlushResponseOk | RecorderResponseErr;
-export type RecorderResponse = RecStartResponse | RecStopResponse | RecCdpResponse | RecHarFlushResponse;