offrouter-core 0.2.0 → 0.2.2

package/src/audit.ts

@@ -1,553 +0,0 @@
-/**
- * Redacted audit log store for OffRouter V1.
- *
- * V1 keeps only digests, short redacted previews (opt-in), and decision
- * summaries. Raw prompt text and secrets are never persisted by default.
- *
- * In-memory only for this task; file/JSONL backend comes after the interface
- * stabilizes (see design: ~/.offrouter/audit/*.jsonl).
- */
-import { randomBytes } from "node:crypto";
-import { redact, REDACTED } from "./secrets.js";
-import type {
-  FallbackChainEntry,
-  FallbackReason,
-  PolicyDenial,
-  RouteDecision,
-  RouteRequest,
-  SelectedRoute,
-} from "./types.js";
-
-/** Default max chars kept for an opt-in redacted prompt preview. */
-export const DEFAULT_PREVIEW_MAX_CHARS = 80;
-
-/** Cancellation lifecycle for an audited request/decision in-process. */
-export type CancellationState = "active" | "cancelled" | "completed";
-
-/** High-level audit event kind. */
-export type AuditRecordKind =
-  | "route_decision"
-  | "api_key_fallback"
-  | "cancellation";
-
-/**
- * Append-only audit record. Intentionally omits raw prompt text.
- * `promptPreviewRedacted` appears only when explicitly requested at append.
- */
-export interface AuditRecord {
-  recordId: string;
-  kind: AuditRecordKind;
-  timestamp: string;
-  requestId: string;
-  decisionId?: string;
-  profile?: string;
-  harnessKind?: string;
-  /** Prompt content login digest (sha256:..., etc.). Never the prompt itself. */
-  promptDigest?: string;
-  /**
-   * Short, redacted preview. Present only when the append opted into previews.
-   * Never the full raw user prompt.
-   */
-  promptPreviewRedacted?: string;
-  /** Digest-oriented decision summary from routing. */
-  auditSummary?: string;
-  reason: string;
-  explanation: string;
-  route?: SelectedRoute | null;
-  fallbackChain?: FallbackChainEntry[];
-  /** Explicit API-key fallback reason when paid capacity was used. */
-  apiKeyFallbackReason?: FallbackReason | string;
-  policyDenials?: PolicyDenial[];
-  blocked?: boolean;
-  needsConfiguration?: boolean;
-  cancellationState?: CancellationState;
-  cancelledAt?: string;
-}
-
-export interface AppendDecisionOptions {
-  /**
-   * When true, store a short redacted preview derived from promptPreview.
-   * Default false — digests and summaries only.
-   */
-  includePromptPreview?: boolean;
-  /** Max chars of redacted preview when includePromptPreview is true. */
-  previewMaxChars?: number;
-  /**
-   * Known secret values to strip in addition to pattern-based redaction.
-   * Never stored; used only during redaction.
-   */
-  knownSecrets?: Iterable<string>;
-  /** Initial cancellation state; default "active" for successful routes. */
-  cancellationState?: CancellationState;
-  /** Override clock for tests. */
-  now?: () => Date;
-}
-
-export interface ListAuditOptions {
-  requestId?: string;
-  decisionId?: string;
-  kind?: AuditRecordKind;
-  /** Max records to return (most recent first). */
-  limit?: number;
-}
-
-export interface MarkCancelledOptions {
-  reason?: string;
-  now?: () => Date;
-}
-
-/**
- * Audit log contract. Implementations must never persist raw secrets or full
- * prompt bodies by default.
- */
-export interface AuditStore {
-  appendDecision(
-    request: RouteRequest,
-    decision: RouteDecision,
-    options?: AppendDecisionOptions,
-  ): Promise<AuditRecord>;
-
-  /**
-   * Record that an API-key fallback was used, with an audited reason.
-   * Always redacted; never log the delegated prompt or credential material.
-   */
-  recordApiKeyFallback(input: {
-    requestId: string;
-    decisionId?: string;
-    reason: FallbackReason | string;
-    explanation: string;
-    route?: SelectedRoute | null;
-    /** Optional digest already present on the route request/decision. */
-    promptDigest?: string;
-    knownSecrets?: Iterable<string>;
-    now?: () => Date;
-  }): Promise<AuditRecord>;
-
-  markCancelled(
-    requestId: string,
-    options?: MarkCancelledOptions,
-  ): Promise<AuditRecord | undefined>;
-
-  markCompleted(
-    requestId: string,
-    options?: { now?: () => Date },
-  ): Promise<AuditRecord | undefined>;
-
-  getCancellationState(
-    requestId: string,
-  ): Promise<CancellationState | undefined>;
-
-  list(options?: ListAuditOptions): Promise<AuditRecord[]>;
-
-  get(recordId: string): Promise<AuditRecord | undefined>;
-
-  /**
-   * JSON-safe diagnostic view. Must never include raw prompt text or secrets.
-   */
-  toJSON(): Record<string, unknown>;
-}
-
-export interface InMemoryAuditStoreOptions {
-  /** Optional hard cap on retained records (FIFO eviction of oldest). */
-  maxRecords?: number;
-  /** Default known secrets used for every redaction pass. */
-  knownSecrets?: Iterable<string>;
-  now?: () => Date;
-}
-
-function newId(prefix: string): string {
-  return `${prefix}_${randomBytes(8).toString("hex")}`;
-}
-
-function clampPreview(text: string, maxChars: number): string {
-  if (text.length <= maxChars) return text;
-  return `${text.slice(0, Math.max(0, maxChars - 1))}…`;
-}
-
-/**
- * Strip secret-like patterns and optionally known secrets from free text.
- * Safe for empty/undefined values.
- */
-function safeRedact(
-  value: string | undefined,
-  knownSecrets: Iterable<string>,
-): string {
-  if (value == null || value === "") return value ?? "";
-  return redact(value, knownSecrets);
-}
-
-function looksLikeApiKeyFallback(decision: RouteDecision): boolean {
-  if (decision.route?.authTier === "api-key") {
-    if (decision.reason === "api_key_fallback") return true;
-    if (
-      decision.fallbackChain?.some(
-        (e) => e.reason === "api_key_fallback" || e.authTier === "api-key",
-      )
-    ) {
-      return true;
-    }
-    // Any API-key selection with a subscription fallback reason counts.
-    if (
-      decision.fallbackChain?.some(
-        (e) =>
-          e.reason === "subscription_exhausted" ||
-          e.reason === "subscription_degraded" ||
-          e.reason === "subscription_unconfigured" ||
-          e.reason === "provider_error",
-      )
-    ) {
-      return true;
-    }
-  }
-  return decision.reason === "api_key_fallback";
-}
-
-function extractApiKeyFallbackReason(
-  decision: RouteDecision,
-): FallbackReason | string | undefined {
-  if (!looksLikeApiKeyFallback(decision)) return undefined;
-  const chainHit = decision.fallbackChain?.find(
-    (e) => e.reason === "api_key_fallback",
-  );
-  if (chainHit) return chainHit.reason;
-  const exhausted = decision.fallbackChain?.find(
-    (e) =>
-      e.reason === "subscription_exhausted" ||
-      e.reason === "subscription_degraded" ||
-      e.reason === "subscription_unconfigured" ||
-      e.reason === "provider_error",
-  );
-  if (exhausted) return exhausted.reason;
-  if (decision.route?.authTier === "api-key") return "api_key_fallback";
-  return decision.reason;
-}
-
-/**
- * In-memory audit store for tests and single-process V1 use.
- * Appends are serialized so concurrent writers cannot interleave corruptly.
- */
-export class InMemoryAuditStore implements AuditStore {
-  readonly #records: AuditRecord[] = [];
-  readonly #byId = new Map<string, AuditRecord>();
-  /** Latest cancellation-bearing record per requestId. */
-  readonly #latestByRequest = new Map<string, AuditRecord>();
-  readonly #maxRecords: number | undefined;
-  readonly #defaultKnownSecrets: string[];
-  readonly #now: () => Date;
-  #chain: Promise<unknown> = Promise.resolve();
-
-  constructor(options: InMemoryAuditStoreOptions = {}) {
-    this.#maxRecords = options.maxRecords;
-    this.#defaultKnownSecrets = options.knownSecrets
-      ? [...options.knownSecrets].filter((s) => typeof s === "string" && s.length > 0)
-      : [];
-    this.#now = options.now ?? (() => new Date());
-  }
-
-  /** Serialize mutations so concurrent appends stay ordered and consistent. */
-  #exclusive<T>(fn: () => T | Promise<T>): Promise<T> {
-    const run = this.#chain.then(fn, fn);
-    this.#chain = run.then(
-      () => undefined,
-      () => undefined,
-    );
-    return run;
-  }
-
-  async appendDecision(
-    request: RouteRequest,
-    decision: RouteDecision,
-    options: AppendDecisionOptions = {},
-  ): Promise<AuditRecord> {
-    return this.#exclusive(() => {
-      const known = mergeKnown(
-        this.#defaultKnownSecrets,
-        options.knownSecrets,
-      );
-      const now = (options.now ?? this.#now)();
-      const includePreview = options.includePromptPreview === true;
-      const maxChars = options.previewMaxChars ?? DEFAULT_PREVIEW_MAX_CHARS;
-
-      const apiKeyFallbackReason = extractApiKeyFallbackReason(decision);
-      const kind: AuditRecordKind = apiKeyFallbackReason
-        ? "api_key_fallback"
-        : "route_decision";
-
-      const initialCancellation: CancellationState | undefined =
-        options.cancellationState ??
-        (decision.blocked || decision.route == null ? "completed" : "active");
-
-      // Drop any raw-looking fields that might have leaked into reason/explanation.
-      const reason = safeRedact(decision.reason, known);
-      const explanation = safeRedact(decision.explanation, known);
-      const auditSummary = decision.auditSummary
-        ? safeRedact(decision.auditSummary, known)
-        : safeRedact(
-            `decision=${decision.decisionId} digest=${request.task.promptDigest}`,
-            known,
-          );
-
-      // Guard: never let raw promptPreview appear in stored free text.
-      const rawPreview = request.task.promptPreview;
-      const redactedStoredPreview = includePreview
-        ? clampPreview(safeRedact(rawPreview, known), maxChars)
-        : undefined;
-
-      const record: AuditRecord = {
-        recordId: newId("aud"),
-        kind,
-        timestamp: now.toISOString(),
-        requestId: request.requestId,
-        decisionId: decision.decisionId,
-        profile: request.harness.profile,
-        harnessKind: request.harness.kind,
-        promptDigest: request.task.promptDigest,
-        auditSummary,
-        reason,
-        explanation,
-        route: decision.route ?? null,
-        fallbackChain: decision.fallbackChain
-          ? decision.fallbackChain.map((e) => ({ ...e }))
-          : undefined,
-        apiKeyFallbackReason,
-        policyDenials: decision.policyDenials
-          ? decision.policyDenials.map((d) => ({
-              ...d,
-              message: safeRedact(d.message, known),
-            }))
-          : undefined,
-        blocked: decision.blocked,
-        needsConfiguration: decision.needsConfiguration,
-        cancellationState: initialCancellation,
-      };
-
-      if (redactedStoredPreview !== undefined) {
-        // If redaction wiped the value entirely, keep a stable redacted token.
-        record.promptPreviewRedacted =
-          redactedStoredPreview.length > 0
-            ? redactedStoredPreview
-            : REDACTED;
-      }
-
-      // Assert default path never embeds raw preview (defensive for tests + misuse).
-      this.#assertNoRawLeak(record, rawPreview, known);
-
-      this.#push(record);
-      return structuredClone(record);
-    });
-  }
-
-  async recordApiKeyFallback(input: {
-    requestId: string;
-    decisionId?: string;
-    reason: FallbackReason | string;
-    explanation: string;
-    route?: SelectedRoute | null;
-    promptDigest?: string;
-    knownSecrets?: Iterable<string>;
-    now?: () => Date;
-  }): Promise<AuditRecord> {
-    return this.#exclusive(() => {
-      const known = mergeKnown(
-        this.#defaultKnownSecrets,
-        input.knownSecrets,
-      );
-      const now = (input.now ?? this.#now)();
-      const record: AuditRecord = {
-        recordId: newId("aud"),
-        kind: "api_key_fallback",
-        timestamp: now.toISOString(),
-        requestId: input.requestId,
-        decisionId: input.decisionId,
-        promptDigest: input.promptDigest,
-        reason: safeRedact(String(input.reason), known),
-        explanation: safeRedact(input.explanation, known),
-        route: input.route ?? null,
-        apiKeyFallbackReason: safeRedact(String(input.reason), known),
-        cancellationState: "active",
-      };
-      this.#push(record);
-      return structuredClone(record);
-    });
-  }
-
-  async markCancelled(
-    requestId: string,
-    options: MarkCancelledOptions = {},
-  ): Promise<AuditRecord | undefined> {
-    return this.#exclusive(() => {
-      const latest = this.#latestByRequest.get(requestId);
-      if (!latest) return undefined;
-      if (latest.cancellationState === "cancelled") {
-        return structuredClone(latest);
-      }
-      const now = (options.now ?? this.#now)();
-      const known = this.#defaultKnownSecrets;
-      const update: AuditRecord = {
-        ...latest,
-        recordId: newId("aud"),
-        kind: "cancellation",
-        timestamp: now.toISOString(),
-        cancellationState: "cancelled",
-        cancelledAt: now.toISOString(),
-        reason: options.reason
-          ? safeRedact(options.reason, known)
-          : "cancelled",
-        explanation: options.reason
-          ? safeRedact(options.reason, known)
-          : "Request cancelled in-process.",
-      };
-      this.#push(update);
-      return structuredClone(update);
-    });
-  }
-
-  async markCompleted(
-    requestId: string,
-    options: { now?: () => Date } = {},
-  ): Promise<AuditRecord | undefined> {
-    return this.#exclusive(() => {
-      const latest = this.#latestByRequest.get(requestId);
-      if (!latest) return undefined;
-      if (
-        latest.cancellationState === "completed" ||
-        latest.cancellationState === "cancelled"
-      ) {
-        return structuredClone(latest);
-      }
-      const now = (options.now ?? this.#now)();
-      const update: AuditRecord = {
-        ...latest,
-        recordId: newId("aud"),
-        kind: latest.kind === "cancellation" ? "cancellation" : latest.kind,
-        timestamp: now.toISOString(),
-        cancellationState: "completed",
-      };
-      this.#push(update);
-      return structuredClone(update);
-    });
-  }
-
-  async getCancellationState(
-    requestId: string,
-  ): Promise<CancellationState | undefined> {
-    const latest = this.#latestByRequest.get(requestId);
-    return latest?.cancellationState;
-  }
-
-  async list(options: ListAuditOptions = {}): Promise<AuditRecord[]> {
-    let rows = this.#records.slice();
-    if (options.requestId) {
-      rows = rows.filter((r) => r.requestId === options.requestId);
-    }
-    if (options.decisionId) {
-      rows = rows.filter((r) => r.decisionId === options.decisionId);
-    }
-    if (options.kind) {
-      rows = rows.filter((r) => r.kind === options.kind);
-    }
-    // Most recent first.
-    rows = rows.slice().reverse();
-    if (options.limit !== undefined && options.limit >= 0) {
-      rows = rows.slice(0, options.limit);
-    }
-    return rows.map((r) => structuredClone(r));
-  }
-
-  async get(recordId: string): Promise<AuditRecord | undefined> {
-    const hit = this.#byId.get(recordId);
-    return hit ? structuredClone(hit) : undefined;
-  }
-
-  toJSON(): Record<string, unknown> {
-    // Never surface free-text that might contain secrets beyond redacted fields.
-    return {
-      kind: "in-memory-audit",
-      recordCount: this.#records.length,
-      requestIds: [...new Set(this.#records.map((r) => r.requestId))],
-      // Digests only — no previews in the diagnostic surface.
-      digests: this.#records
-        .map((r) => r.promptDigest)
-        .filter((d): d is string => typeof d === "string"),
-      kinds: this.#records.reduce<Record<string, number>>((acc, r) => {
-        acc[r.kind] = (acc[r.kind] ?? 0) + 1;
-        return acc;
-      }, {}),
-    };
-  }
-
-  #push(record: AuditRecord): void {
-    this.#records.push(record);
-    this.#byId.set(record.recordId, record);
-    this.#latestByRequest.set(record.requestId, record);
-
-    if (
-      this.#maxRecords !== undefined &&
-      this.#records.length > this.#maxRecords
-    ) {
-      const overflow = this.#records.length - this.#maxRecords;
-      const removed = this.#records.splice(0, overflow);
-      for (const old of removed) {
-        this.#byId.delete(old.recordId);
-        // Only drop latest mapping if it still points at the evicted record.
-        const latest = this.#latestByRequest.get(old.requestId);
-        if (latest?.recordId === old.recordId) {
-          this.#latestByRequest.delete(old.requestId);
-        }
-      }
-    }
-  }
-
-  #assertNoRawLeak(
-    record: AuditRecord,
-    rawPreview: string,
-    knownSecrets: string[],
-  ): void {
-    if (!rawPreview || rawPreview.length < 8) return;
-    const blobs = [
-      record.auditSummary,
-      record.reason,
-      record.explanation,
-      record.promptPreviewRedacted,
-      ...(record.policyDenials?.map((d) => d.message) ?? []),
-    ]
-      .filter((s): s is string => typeof s === "string")
-      .join("\n");
-
-    // Allow the case where the "preview" is only a digest-like token or was fully redacted.
-    if (blobs.includes(rawPreview)) {
-      // Self-heal by scrubbing — should not happen under normal use.
-      if (record.auditSummary?.includes(rawPreview)) {
-        record.auditSummary = redact(record.auditSummary, knownSecrets).replaceAll(
-          rawPreview,
-          REDACTED,
-        );
-      }
-      if (record.explanation.includes(rawPreview)) {
-        record.explanation = redact(record.explanation, knownSecrets).replaceAll(
-          rawPreview,
-          REDACTED,
-        );
-      }
-      if (record.reason.includes(rawPreview)) {
-        record.reason = redact(record.reason, knownSecrets).replaceAll(
-          rawPreview,
-          REDACTED,
-        );
-      }
-    }
-  }
-}
-
-function mergeKnown(
-  base: readonly string[],
-  extra: Iterable<string> | undefined,
-): string[] {
-  const out = [...base];
-  if (extra) {
-    for (const s of extra) {
-      if (typeof s === "string" && s.length > 0) out.push(s);
-    }
-  }
-  return out;
-}