imprint-mcp 0.2.0

package/src/imprint/sensitive-keys.ts

@@ -0,0 +1,156 @@
+/**
+ * Shared list of sensitive credential key names. Used by `redact.ts` to scrub
+ * values, and by `credential-extract.ts` to detect login pairs.
+ *
+ * Case-insensitive; underscores and hyphens are stripped before matching, so
+ * `password`, `Pass_Word`, `PASS-WORD`, `pwd` all match.
+ */
+
+const SENSITIVE_KEYS = [
+  // Credentials — login identifiers
+  'user',
+  'username',
+  'user_name',
+  'userid',
+  'user_id',
+  'login',
+  'loginid',
+  'login_id',
+  // Credentials — passwords & secrets
+  'pass',
+  'password',
+  'passwd',
+  'pwd',
+  'pin',
+  'secret',
+  'credential',
+  'credentials',
+  // Tokens & session identifiers
+  'token',
+  'auth',
+  'authcode',
+  'auth_code',
+  'apikey',
+  'api_key',
+  'apitoken',
+  'api_token',
+  'accesstoken',
+  'access_token',
+  'refreshtoken',
+  'refresh_token',
+  'idtoken',
+  'id_token',
+  'sessionid',
+  'session_id',
+  'sessiontoken',
+  'session_token',
+  'authorization',
+  'authentication',
+  'bearer',
+  // CSRF / XSRF
+  'csrf',
+  'csrf_token',
+  'csrftoken',
+  'xsrf',
+  'xsrf_token',
+  'xsrftoken',
+  // MFA / OTP
+  'otp',
+  'totp',
+  'mfa_code',
+  'mfacode',
+  'verification_code',
+  'verificationcode',
+  'oktaemail',
+  'okta_email',
+  // Device / browser fingerprinting
+  'fingerprint',
+  // Site-specific (Discover & Go uses these)
+  'patronpassword',
+  'patron_password',
+  'patronnumber',
+  'patron_number',
+  'cardnumber',
+  'card_number',
+  'librarycard',
+  'library_card',
+  // Stripe / payments
+  'cvc',
+  'cvv',
+  'cardnum',
+  'card_num',
+  'creditcard',
+  'credit_card',
+  'cc_number',
+  // PII — contact
+  'email',
+  'emailaddress',
+  'email_address',
+  'phone',
+  'phonenumber',
+  'phone_number',
+  'mobile',
+  'cell',
+  'sms',
+  'smsnumber',
+  'sms_number',
+  // PII — names
+  'firstname',
+  'first_name',
+  'lastname',
+  'last_name',
+  'fullname',
+  'full_name',
+  'nameoncard',
+  'name_on_card',
+  // PII — government / identity
+  'ssn',
+  'socialsecurity',
+  'social_security',
+  'dateofbirth',
+  'date_of_birth',
+  'dob',
+];
+
+const SENSITIVE_KEY_SET = new Set(SENSITIVE_KEYS.map((k) => k.toLowerCase()));
+
+/** Subset of SENSITIVE_KEYS that specifically denote a credential (not PII).
+ *  Used by credential-extract.ts when looking for the password half of a
+ *  login form pair — we don't want to treat e.g. `dob` as a password. */
+const PASSWORD_LIKE_KEYS = new Set(
+  ['password', 'passwd', 'pwd', 'pin', 'patronpassword', 'patron_password'].map((k) =>
+    k.toLowerCase(),
+  ),
+);
+
+const SENSITIVE_HEADERS = [
+  'authorization',
+  'cookie',
+  'set-cookie',
+  'x-auth-token',
+  'x-api-key',
+  'x-apikey',
+  'x-csrf-token',
+  'x-xsrf-token',
+  'x-session-token',
+  'proxy-authorization',
+];
+
+const SENSITIVE_HEADER_SET = new Set(SENSITIVE_HEADERS.map((h) => h.toLowerCase()));
+
+export const normalizeKey = (s: string): string => s.toLowerCase().replace(/[-_]/g, '');
+
+/** True if the key name suggests a sensitive value (auth, payment, PII). */
+export function isSensitiveKey(key: string): boolean {
+  return SENSITIVE_KEY_SET.has(normalizeKey(key));
+}
+
+/** True if the key name suggests a *password* specifically (not arbitrary
+ *  PII). Used when pairing a username + password in extraction. */
+export function isSensitiveCredentialKey(key: string): boolean {
+  return PASSWORD_LIKE_KEYS.has(normalizeKey(key));
+}
+
+export function isSensitiveHeader(header: string): boolean {
+  return SENSITIVE_HEADER_SET.has(header.toLowerCase());
+}

package/src/imprint/session-diff.ts

@@ -0,0 +1,409 @@
+/**
+ * Dual-pass session diff: aligns requests from two independent executions
+ * and classifies values as constant, server-derived, or browser-minted.
+ */
+
+import type { CapturedRequest, Session } from './types.ts';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type ValueClassification = 'constant' | 'browser_minted' | 'server_derived';
+
+export interface ClassifiedValue {
+  classification: ValueClassification;
+  /** e.g. "url_param:correlationId", "header:x-csrf-token", "body:$.transaction.id" */
+  location: string;
+  originalSeq: number;
+  value1: string;
+  value2: string;
+  /** For server_derived: seq of the response that produced this value in run 2. */
+  producerSeq?: number;
+  /** For server_derived: where in the producer response the value was found. */
+  producerPath?: string;
+  suggestedStateName?: string;
+}
+
+interface AlignedRequestPair {
+  originalSeq: number;
+  replaySeq: number;
+  /** 0–1 based on URL path, method, body structure similarity. */
+  confidence: number;
+}
+
+interface DiffResult {
+  classifications: ClassifiedValue[];
+  alignedPairs: AlignedRequestPair[];
+  unmatchedOriginal: number[];
+  unmatchedReplay: number[];
+}
+
+export interface CapturedReplayRequest {
+  seq: number;
+  timestamp: number;
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: string;
+  resourceType: string;
+  response?: {
+    status: number;
+    headers: Record<string, string>;
+    body?: string;
+    mimeType?: string;
+  };
+}
+
+// ─── Alignment ──────────────────────────────────────────────────────────────
+
+interface RequestLike {
+  seq: number;
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: string;
+  response?: { status: number; headers: Record<string, string>; body?: string };
+}
+
+function urlPathname(raw: string): string {
+  try {
+    const u = new URL(raw);
+    return `${u.hostname}${u.pathname}`;
+  } catch {
+    return raw;
+  }
+}
+
+function alignmentKey(req: RequestLike): string {
+  return `${req.method}\t${urlPathname(req.url)}`;
+}
+
+function jsonKeySet(body: string | undefined): Set<string> | null {
+  if (!body) return null;
+  try {
+    const obj = JSON.parse(body);
+    if (typeof obj !== 'object' || obj === null) return null;
+    return new Set(Object.keys(obj));
+  } catch {
+    return null;
+  }
+}
+
+function keySetSimilarity(a: Set<string> | null, b: Set<string> | null): number {
+  if (!a || !b || a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const k of a) if (b.has(k)) intersection++;
+  return intersection / Math.max(a.size, b.size);
+}
+
+/**
+ * Align requests from two runs by (method, URL_pathname, relative_sequence).
+ * Returns pairs with confidence scores. Low-confidence pairs (< 0.3) excluded.
+ */
+export function alignRequests(run1: RequestLike[], run2: RequestLike[]): AlignedRequestPair[] {
+  const groups1 = new Map<string, RequestLike[]>();
+  const groups2 = new Map<string, RequestLike[]>();
+
+  for (const r of run1) {
+    const key = alignmentKey(r);
+    const arr = groups1.get(key) ?? [];
+    arr.push(r);
+    groups1.set(key, arr);
+  }
+  for (const r of run2) {
+    const key = alignmentKey(r);
+    const arr = groups2.get(key) ?? [];
+    arr.push(r);
+    groups2.set(key, arr);
+  }
+
+  const pairs: AlignedRequestPair[] = [];
+  const usedRun2Seqs = new Set<number>();
+
+  for (const [key, g1] of groups1) {
+    const g2 = groups2.get(key);
+    if (!g2) continue;
+
+    // Match by relative position within group
+    for (let i = 0; i < g1.length; i++) {
+      // biome-ignore lint/style/noNonNullAssertion: bounded by loop condition
+      const r1 = g1[i]!;
+      if (i < g2.length) {
+        // biome-ignore lint/style/noNonNullAssertion: bounded by loop condition
+        const r2 = g2[i]!;
+        if (usedRun2Seqs.has(r2.seq)) continue;
+
+        let confidence = 0.7; // base for method+path match at same position
+        const bodySim = keySetSimilarity(jsonKeySet(r1.body), jsonKeySet(r2.body));
+        if (bodySim > 0) confidence = Math.min(1.0, confidence + bodySim * 0.3);
+
+        if (confidence >= 0.3) {
+          pairs.push({ originalSeq: r1.seq, replaySeq: r2.seq, confidence });
+          usedRun2Seqs.add(r2.seq);
+        }
+      }
+    }
+  }
+
+  return pairs;
+}
+
+// ─── Value extraction ───────────────────────────────────────────────────────
+
+const SKIP_HEADERS = new Set([
+  'user-agent',
+  'accept',
+  'accept-language',
+  'accept-encoding',
+  'connection',
+  'host',
+  'sec-fetch-dest',
+  'sec-fetch-mode',
+  'sec-fetch-site',
+  'sec-ch-ua',
+  'sec-ch-ua-mobile',
+  'sec-ch-ua-platform',
+  'upgrade-insecure-requests',
+  'cache-control',
+  'pragma',
+  'content-length',
+  'content-type',
+  'origin',
+  'referer',
+]);
+
+interface ExtractedValue {
+  location: string;
+  value: string;
+}
+
+function extractUrlParams(url: string): ExtractedValue[] {
+  try {
+    const u = new URL(url);
+    const result: ExtractedValue[] = [];
+    for (const [key, val] of u.searchParams) {
+      result.push({ location: `url_param:${key}`, value: val });
+    }
+    return result;
+  } catch {
+    return [];
+  }
+}
+
+function extractHeaderValues(headers: Record<string, string>): ExtractedValue[] {
+  const result: ExtractedValue[] = [];
+  for (const [name, value] of Object.entries(headers)) {
+    if (!SKIP_HEADERS.has(name.toLowerCase())) {
+      result.push({ location: `header:${name}`, value });
+    }
+  }
+  return result;
+}
+
+function extractJsonBodyValues(body: string | undefined, prefix = 'body'): ExtractedValue[] {
+  if (!body) return [];
+  try {
+    const obj = JSON.parse(body);
+    return flattenObject(obj, prefix);
+  } catch {
+    return [{ location: prefix, value: body }];
+  }
+}
+
+function flattenObject(obj: unknown, prefix: string): ExtractedValue[] {
+  if (obj === null || obj === undefined) return [];
+  if (typeof obj !== 'object') {
+    return [{ location: prefix, value: String(obj) }];
+  }
+  const result: ExtractedValue[] = [];
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      result.push(...flattenObject(obj[i], `${prefix}[${i}]`));
+    }
+  } else {
+    for (const [key, val] of Object.entries(obj as Record<string, unknown>)) {
+      result.push(...flattenObject(val, `${prefix}.${key}`));
+    }
+  }
+  return result;
+}
+
+function extractRequestValues(req: RequestLike): ExtractedValue[] {
+  return [
+    ...extractUrlParams(req.url),
+    ...extractHeaderValues(req.headers),
+    ...extractJsonBodyValues(req.body),
+  ];
+}
+
+// ─── Producer search ────────────────────────────────────────────────────────
+
+interface ProducerMatch {
+  seq: number;
+  path: string;
+}
+
+function searchPriorResponses(
+  value: string,
+  requests: RequestLike[],
+  beforeSeq: number,
+): ProducerMatch | null {
+  if (value.length < 4) return null; // skip trivially short values
+
+  for (let i = requests.length - 1; i >= 0; i--) {
+    // biome-ignore lint/style/noNonNullAssertion: bounded by loop condition
+    const req = requests[i]!;
+    if (req.seq >= beforeSeq) continue;
+    const resp = req.response;
+    if (!resp) continue;
+
+    // Search response body
+    if (resp.body?.includes(value)) {
+      const path = findJsonPath(resp.body, value);
+      return { seq: req.seq, path: path ?? 'body(substring)' };
+    }
+
+    // Search response headers
+    for (const [hName, hVal] of Object.entries(resp.headers)) {
+      if (hVal.includes(value)) {
+        return { seq: req.seq, path: `response_header:${hName}` };
+      }
+    }
+  }
+  return null;
+}
+
+function findJsonPath(body: string, value: string): string | null {
+  try {
+    const obj = JSON.parse(body);
+    return findInObject(obj, value, '$');
+  } catch {
+    return null;
+  }
+}
+
+function findInObject(obj: unknown, target: string, path: string): string | null {
+  if (obj === null || obj === undefined) return null;
+  if (typeof obj === 'string' && obj === target) return path;
+  if (typeof obj === 'number' && String(obj) === target) return path;
+  if (typeof obj !== 'object') return null;
+
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      const found = findInObject(obj[i], target, `${path}[${i}]`);
+      if (found) return found;
+    }
+  } else {
+    for (const [key, val] of Object.entries(obj as Record<string, unknown>)) {
+      const found = findInObject(val, target, `${path}.${key}`);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+// ─── State name suggestion ──────────────────────────────────────────────────
+
+function suggestStateName(location: string): string {
+  // url_param:context.correlationIdentifier → correlation_identifier
+  // header:x-csrf-token → csrf_token
+  // body.transaction.id → transaction_id
+  const raw = location.replace(/^(url_param|header|body):?/, '').replace(/^x-/, '');
+
+  return raw
+    .replace(/[.\[\]]/g, '_')
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .replace(/[^a-zA-Z0-9_]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '')
+    .toLowerCase();
+}
+
+// ─── Main diff ──────────────────────────────────────────────────────────────
+
+export function diffTriagedSessions(
+  original: Session,
+  replay: { requests: CapturedReplayRequest[] },
+): DiffResult {
+  const pairs = alignRequests(original.requests, replay.requests);
+  const pairedOrigSeqs = new Set(pairs.map((p) => p.originalSeq));
+  const pairedReplaySeqs = new Set(pairs.map((p) => p.replaySeq));
+
+  const classifications: ClassifiedValue[] = [];
+
+  for (const pair of pairs) {
+    if (pair.confidence < 0.5) continue;
+
+    const r1 = original.requests.find((r) => r.seq === pair.originalSeq);
+    const r2 = replay.requests.find((r) => r.seq === pair.replaySeq);
+    if (!r1 || !r2) continue;
+
+    const vals1 = extractRequestValues(r1);
+    const vals2 = extractRequestValues(r2);
+
+    const map2 = new Map(vals2.map((v) => [v.location, v.value]));
+
+    for (const v1 of vals1) {
+      const v2Value = map2.get(v1.location);
+      if (v2Value === undefined) continue; // field only in run 1
+
+      if (v1.value === v2Value) {
+        classifications.push({
+          classification: 'constant',
+          location: v1.location,
+          originalSeq: pair.originalSeq,
+          value1: v1.value,
+          value2: v2Value,
+        });
+        continue;
+      }
+
+      // Value differs — check if it came from a prior response in run 2
+      const producer = searchPriorResponses(v2Value, replay.requests, pair.replaySeq);
+
+      if (producer) {
+        const name = suggestStateName(v1.location);
+        classifications.push({
+          classification: 'server_derived',
+          location: v1.location,
+          originalSeq: pair.originalSeq,
+          value1: v1.value,
+          value2: v2Value,
+          producerSeq: producer.seq,
+          producerPath: producer.path,
+          suggestedStateName: name || undefined,
+        });
+      } else {
+        const name = suggestStateName(v1.location);
+        classifications.push({
+          classification: 'browser_minted',
+          location: v1.location,
+          originalSeq: pair.originalSeq,
+          value1: v1.value,
+          value2: v2Value,
+          suggestedStateName: name || undefined,
+        });
+      }
+    }
+  }
+
+  return {
+    classifications,
+    alignedPairs: pairs,
+    unmatchedOriginal: original.requests
+      .filter((r) => !pairedOrigSeqs.has(r.seq))
+      .map((r) => r.seq),
+    unmatchedReplay: replay.requests.filter((r) => !pairedReplaySeqs.has(r.seq)).map((r) => r.seq),
+  };
+}
+
+/**
+ * Triage run-2 requests by aligning them against run-1's already-triaged set.
+ * No narration or LLM call needed — the first triage acts as the oracle.
+ */
+export function triageByAlignment(
+  run1TriagedRequests: CapturedRequest[],
+  run2AllRequests: CapturedReplayRequest[],
+): number[] {
+  const aligned = alignRequests(run1TriagedRequests, run2AllRequests);
+  return aligned.filter((pair) => pair.confidence >= 0.5).map((pair) => pair.replaySeq);
+}