@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/lab/ledger/store.ts

@@ -0,0 +1,263 @@
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  statSync,
+  writeSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { jcsStringify } from "../digest";
+import { MAX_SERIALIZED_EVENT_BYTES } from "../constants";
+import type { LabEvent, LedgerCorruption, ReplayResult } from "../events/types";
+import { LabValidationError, validateLabEvent } from "../events/validate";
+import { ensureLabDirs, labLedgerPath } from "../paths";
+
+export interface LedgerStore {
+  path: string;
+  append(event: LabEvent): void;
+  replay(): ReplayResult;
+}
+
+/** Durable append of one validated event as a single JSONL line + fsync. */
+export function appendLabEvent(ledgerPath: string, event: LabEvent): void {
+  const validated = validateLabEvent(event);
+  mkdirSync(dirname(ledgerPath), { recursive: true, mode: 0o700 });
+  const line = `${jcsStringify(validated)}\n`;
+  const bytes = new TextEncoder().encode(line);
+  const fd = openSync(ledgerPath, "a", 0o600);
+  try {
+    let written = 0;
+    while (written < bytes.byteLength) {
+      const n = writeSync(fd, bytes, written, bytes.byteLength - written);
+      if (n <= 0) {
+        throw new LabValidationError("short_write", "ledger append made no progress");
+      }
+      written += n;
+    }
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function processLine(
+  line: string,
+  lineNumber: number,
+  lineHasTrailingNewline: boolean,
+  events: LabEvent[],
+  seenIds: Set<string>,
+  corruptions: LedgerCorruption[],
+): void {
+  if (!lineHasTrailingNewline) {
+    corruptions.push({
+      kind: "partial_line",
+      lineNumber,
+      detail: "partial final JSONL line (missing trailing newline)",
+    });
+    return;
+  }
+  if (line.trim() === "") {
+    corruptions.push({ kind: "malformed_line", lineNumber, detail: "empty line" });
+    return;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    corruptions.push({ kind: "malformed_line", lineNumber, detail: "JSON parse failed" });
+    return;
+  }
+
+  let event: LabEvent;
+  try {
+    event = validateLabEvent(parsed);
+  } catch (err) {
+    corruptions.push({
+      kind: "invalid_event",
+      lineNumber,
+      detail: err instanceof Error ? err.message : String(err),
+    });
+    return;
+  }
+
+  if (seenIds.has(event.eventId)) {
+    corruptions.push({
+      kind: "duplicate_event",
+      lineNumber,
+      eventId: event.eventId,
+      detail: "duplicate eventId",
+    });
+    return;
+  }
+  seenIds.add(event.eventId);
+  events.push(event);
+}
+
+function processBufferedLines(
+  buf: Buffer,
+  state: {
+    lineNumber: number;
+    totalLineCount: number;
+    skippingOversizedLine: boolean;
+    events: LabEvent[];
+    seenIds: Set<string>;
+    corruptions: LedgerCorruption[];
+  },
+): { carry: Buffer; skippingOversizedLine: boolean } {
+  let start = 0;
+  let skipping = state.skippingOversizedLine;
+
+  while (start < buf.length) {
+    const newlineIdx = buf.indexOf(0x0a, start);
+    if (newlineIdx < 0) {
+      const tail = buf.subarray(start);
+      if (skipping) {
+        return { carry: Buffer.alloc(0), skippingOversizedLine: true };
+      }
+      if (tail.length > MAX_SERIALIZED_EVENT_BYTES) {
+        state.lineNumber += 1;
+        state.totalLineCount += 1;
+        state.corruptions.push({
+          kind: "malformed_line",
+          lineNumber: state.lineNumber,
+          detail: `line exceeds ${MAX_SERIALIZED_EVENT_BYTES} bytes without newline`,
+        });
+        // Drop the oversized prefix immediately. Keeping it would defeat the
+        // replay memory bound and count the same line again at EOF.
+        return { carry: Buffer.alloc(0), skippingOversizedLine: true };
+      }
+      return { carry: tail, skippingOversizedLine: false };
+    }
+
+    const lineBytes = buf.subarray(start, newlineIdx);
+    start = newlineIdx + 1;
+
+    if (skipping) {
+      skipping = false;
+      continue;
+    }
+
+    state.lineNumber += 1;
+    state.totalLineCount += 1;
+    // Decode only complete JSONL lines. Keeping incomplete line bytes as Buffer
+    // carry naturally preserves UTF-8 code points split across read chunks.
+    processLine(lineBytes.toString("utf8"), state.lineNumber, true, state.events, state.seenIds, state.corruptions);
+  }
+
+  return { carry: Buffer.alloc(0), skippingOversizedLine: skipping };
+}
+
+/**
+ * Replay the JSONL ledger using chunked reads (no whole-file string buffer).
+ * Malformed or partial lines contribute no evidence and are reported as corruption.
+ */
+export function replayLabLedger(ledgerPath: string): ReplayResult {
+  const corruptions: LedgerCorruption[] = [];
+  const events: LabEvent[] = [];
+  if (!existsSync(ledgerPath)) {
+    return { events, corruptions, validLineCount: 0, totalLineCount: 0 };
+  }
+  const size = statSync(ledgerPath).size;
+  if (size === 0) {
+    return {
+      events,
+      corruptions: [{ kind: "empty_ledger", detail: "ledger file is empty" }],
+      validLineCount: 0,
+      totalLineCount: 0,
+    };
+  }
+
+  const fd = openSync(ledgerPath, "r");
+  const chunkSize = 64 * 1024;
+  const chunk = Buffer.alloc(chunkSize);
+  let carry: Buffer = Buffer.alloc(0);
+  let lineNumber = 0;
+  let totalLineCount = 0;
+  const seenIds = new Set<string>();
+  let offset = 0;
+  let skippingOversizedLine = false;
+
+  const state = {
+    lineNumber,
+    totalLineCount,
+    skippingOversizedLine,
+    events,
+    seenIds,
+    corruptions,
+  };
+
+  try {
+    while (offset < size) {
+      const toRead = Math.min(chunkSize, size - offset);
+      const n = readSync(fd, chunk, 0, toRead, offset);
+      if (n <= 0) break;
+      offset += n;
+
+      // `chunk` is reused by readSync, so any bytes retained beyond this
+      // iteration must be detached from it before the next read.
+      const combined = carry.length > 0
+        ? Buffer.concat([carry, chunk.subarray(0, n)])
+        : Buffer.from(chunk.subarray(0, n));
+      const result = processBufferedLines(combined, state);
+      carry = result.carry.length > 0 ? Buffer.from(result.carry) : Buffer.alloc(0);
+      skippingOversizedLine = result.skippingOversizedLine;
+      state.skippingOversizedLine = skippingOversizedLine;
+      lineNumber = state.lineNumber;
+      totalLineCount = state.totalLineCount;
+    }
+
+    if (carry.length > 0) {
+      if (skippingOversizedLine) {
+        lineNumber += 1;
+        totalLineCount += 1;
+        corruptions.push({
+          kind: "malformed_line",
+          lineNumber,
+          detail: `oversized line exceeds ${MAX_SERIALIZED_EVENT_BYTES} bytes`,
+        });
+      } else if (carry.length > MAX_SERIALIZED_EVENT_BYTES) {
+        lineNumber += 1;
+        totalLineCount += 1;
+        corruptions.push({
+          kind: "malformed_line",
+          lineNumber,
+          detail: `partial line exceeds ${MAX_SERIALIZED_EVENT_BYTES} bytes`,
+        });
+      } else {
+        lineNumber += 1;
+        totalLineCount += 1;
+        processLine(carry.toString("utf8"), lineNumber, false, events, seenIds, corruptions);
+      }
+    }
+  } finally {
+    closeSync(fd);
+  }
+
+  return {
+    events,
+    corruptions,
+    validLineCount: events.length,
+    totalLineCount,
+  };
+}
+
+export function openLedgerStore(configDir?: string): LedgerStore {
+  const paths = ensureLabDirs(configDir);
+  return {
+    path: paths.ledgerPath,
+    append(event: LabEvent) {
+      appendLabEvent(paths.ledgerPath, event);
+    },
+    replay() {
+      return replayLabLedger(paths.ledgerPath);
+    },
+  };
+}
+
+export function defaultLedgerPath(configDir?: string): string {
+  return labLedgerPath(configDir);
+}

package/src/lab/live/credential-lease.ts

@@ -0,0 +1,53 @@
+import { LAB_CREDENTIAL_LEASE, type LabCredentialLeaseV1, type LabDestinationV1 } from "./types";
+
+export class LabCredentialError extends Error {
+  override readonly name = "LabCredentialError";
+  constructor(message: string, readonly code: "harness_failure" | "budget_exhausted") { super(message); }
+}
+
+interface LeaseState { destinationFingerprint: string; transportId: string; remaining: number }
+const LEASE_STATE = new WeakMap<object, LeaseState>();
+type InternalLease = LabCredentialLeaseV1 & { toJSON(): never };
+
+export interface CreateLeaseOptions {
+  destination: LabDestinationV1;
+  transportId?: string;
+  budget?: number;
+}
+
+/** Trusted credential owner may associate secret state with this opaque capability outside Lab. */
+export function createCredentialLease(opts: CreateLeaseOptions): LabCredentialLeaseV1 {
+  const budget = opts.budget ?? 1;
+  if (!Number.isInteger(budget) || budget <= 0) throw new LabCredentialError("invalid credential lease budget", "harness_failure");
+  let lease!: InternalLease;
+  lease = {
+    [LAB_CREDENTIAL_LEASE]: true,
+    get remainingRequests(): number { return LEASE_STATE.get(lease)?.remaining ?? 0; },
+    consume(): void {
+      const state = LEASE_STATE.get(lease);
+      if (!state) throw new LabCredentialError("unknown credential lease", "harness_failure");
+      if (state.remaining <= 0) throw new LabCredentialError("credential lease exhausted", "budget_exhausted");
+      state.remaining -= 1;
+    },
+    toJSON(): never { throw new LabCredentialError("credential lease is non-serializable", "harness_failure"); },
+  };
+  LEASE_STATE.set(lease, {
+    destinationFingerprint: opts.destination.fingerprint,
+    transportId: opts.transportId ?? "default",
+    remaining: budget,
+  });
+  return Object.freeze(lease);
+}
+
+export function isCredentialLease(value: unknown): value is LabCredentialLeaseV1 {
+  return typeof value === "object" && value !== null && LEASE_STATE.has(value as object)
+    && (value as LabCredentialLeaseV1)[LAB_CREDENTIAL_LEASE] === true;
+}
+
+export function assertLeaseScope(lease: LabCredentialLeaseV1, destination: LabDestinationV1, transportId = "default"): void {
+  const state = LEASE_STATE.get(lease as object);
+  if (!state) throw new LabCredentialError("unknown credential lease", "harness_failure");
+  if (state.destinationFingerprint !== destination.fingerprint || state.transportId !== transportId) {
+    throw new LabCredentialError("credential lease scope mismatch", "harness_failure");
+  }
+}

package/src/lab/live/destination.ts

@@ -0,0 +1,155 @@
+import { isIP } from "node:net";
+import { assessUrlDestination, resolvePublicAddresses } from "../../lib/destination-policy";
+import { localFingerprint } from "../digest";
+import { readInstallationSalt } from "../subject/installation-salt";
+import { TransportError } from "./transport";
+import type { DnsResolver, LabDestinationV1 } from "./types";
+
+export class LabDestinationError extends Error {
+  override readonly name = "LabDestinationError";
+  constructor(message: string, readonly code: string) { super(message); }
+}
+
+function normalizeBasePath(pathname: string): string {
+  if (!pathname || pathname === "/") return "";
+  const trimmed = pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+function addressUrl(scheme: "http" | "https", address: string): string {
+  return `${scheme}://${isIP(address) === 6 ? `[${address}]` : address}/`;
+}
+
+function validateResolvedAddress(
+  scheme: "http" | "https",
+  address: { address: string; family: 4 | 6 },
+  allowPrivateNetwork: boolean,
+  labRunApproval: boolean,
+): boolean {
+  const actualFamily = isIP(address.address);
+  if ((actualFamily !== 4 && actualFamily !== 6) || actualFamily !== address.family) {
+    throw new LabDestinationError("resolver returned an invalid address/family", "harness_failure");
+  }
+  const assessment = assessUrlDestination(addressUrl(scheme, address.address));
+  if (!assessment) throw new LabDestinationError("resolver address could not be classified", "harness_failure");
+  if (["metadata", "link-local", "unspecified"].includes(assessment.kind)) {
+    throw new LabDestinationError("blocked resolved destination", "harness_failure");
+  }
+  const privateAnswer = ["private", "loopback", "localhost"].includes(assessment.kind);
+  if (privateAnswer && (!allowPrivateNetwork || !labRunApproval)) {
+    throw new LabDestinationError("resolved private network requires allowPrivateNetwork and labRunApproval", "harness_failure");
+  }
+  return privateAnswer;
+}
+
+function canonicalAddresses(addresses: ReadonlyArray<{ address: string; family: 4 | 6 }>): Array<{ address: string; family: 4 | 6 }> {
+  const unique = new Map<string, { address: string; family: 4 | 6 }>();
+  for (const row of addresses) unique.set(`${row.family}:${row.address}`, { ...row });
+  return [...unique.values()].sort((a, b) => a.family - b.family || (a.address < b.address ? -1 : a.address > b.address ? 1 : 0));
+}
+
+function addressSetKey(addresses: ReadonlyArray<{ address: string; family: 4 | 6 }>): string {
+  return canonicalAddresses(addresses).map((row) => `${row.family}:${row.address}`).join(",");
+}
+
+async function withResolutionTimeout<T>(timeoutMs: number, operation: () => Promise<T>): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise<T>((_, reject) => {
+        timer = setTimeout(() => reject(new TransportError("connect_timeout", "destination resolution timed out")), timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+export interface CreateDestinationOptions {
+  baseUrl: string;
+  allowPrivateNetwork?: boolean;
+  labRunApproval?: boolean;
+  resolve?: DnsResolver;
+  connectTimeoutMs?: number;
+  configDir?: string;
+}
+
+/** Resolve once, policy-check every answer, then freeze the exact snapshot used by all later stages. */
+export async function createLabDestination(opts: CreateDestinationOptions): Promise<LabDestinationV1> {
+  let parsed: URL;
+  try { parsed = new URL(opts.baseUrl); } catch { throw new LabDestinationError("invalid provider baseUrl", "harness_failure"); }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new LabDestinationError("unsupported URL scheme", "harness_failure");
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new LabDestinationError("provider destination may not contain userinfo, query, or fragment", "harness_failure");
+  }
+  const scheme = parsed.protocol === "https:" ? "https" as const : "http" as const;
+  const literal = assessUrlDestination(parsed.toString());
+  if (literal && ["metadata", "link-local", "unspecified"].includes(literal.kind)) {
+    throw new LabDestinationError("blocked destination", "harness_failure");
+  }
+  const allowPrivate = opts.allowPrivateNetwork === true;
+  const approved = opts.labRunApproval === true;
+  const literalPrivate = Boolean(literal && ["private", "loopback", "localhost"].includes(literal.kind));
+  if (literalPrivate && (!allowPrivate || !approved)) {
+    throw new LabDestinationError("private network requires allowPrivateNetwork and labRunApproval", "harness_failure");
+  }
+
+  const connectTimeoutMs = opts.connectTimeoutMs ?? 10_000;
+  if (!Number.isInteger(connectTimeoutMs) || connectTimeoutMs <= 0) {
+    throw new LabDestinationError("invalid connect timeout", "harness_failure");
+  }
+
+  let addresses: Array<{ address: string; family: 4 | 6 }>;
+  let privateNetwork = literalPrivate;
+  if (opts.resolve) {
+    try { addresses = await withResolutionTimeout(connectTimeoutMs, () => opts.resolve!(parsed.hostname)); }
+    catch (error) {
+      if (error instanceof TransportError || error instanceof LabDestinationError) throw error;
+      throw new LabDestinationError("DNS resolution failed", "network_blocked");
+    }
+    if (addresses.length === 0) throw new LabDestinationError("DNS resolution returned no addresses", "network_blocked");
+    for (const row of addresses) privateNetwork = validateResolvedAddress(scheme, row, allowPrivate, approved) || privateNetwork;
+  } else {
+    try {
+      const resolved = await withResolutionTimeout(connectTimeoutMs, () => resolvePublicAddresses(parsed.toString(), {
+        context: "Lab provider destination",
+        allowPrivateNetwork: allowPrivate && approved,
+      }));
+      addresses = resolved.addresses.map((row) => ({ address: row.address, family: row.family === 6 ? 6 as const : 4 as const }));
+      privateNetwork = resolved.privateNetwork || privateNetwork;
+    } catch (error) {
+      if (error instanceof TransportError || error instanceof LabDestinationError) throw error;
+      throw new LabDestinationError("DNS destination policy failed", "network_blocked");
+    }
+  }
+  const frozenAddresses = Object.freeze(canonicalAddresses(addresses).map((row) => Object.freeze(row)));
+  const port = parsed.port ? Number(parsed.port) : scheme === "https" ? 443 : 80;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) throw new LabDestinationError("invalid destination port", "harness_failure");
+  const snapshot = {
+    scheme,
+    host: parsed.hostname.toLowerCase(),
+    port,
+    basePath: normalizeBasePath(parsed.pathname),
+    sniHost: parsed.hostname.toLowerCase(),
+    addresses: frozenAddresses,
+    privateNetwork,
+  };
+  const salt = readInstallationSalt(opts.configDir);
+  const fingerprint = localFingerprint("endpoint", {
+    scheme: snapshot.scheme, host: snapshot.host, port: snapshot.port, basePath: snapshot.basePath,
+  }, salt);
+  return Object.freeze({ ...snapshot, fingerprint });
+}
+
+/** Detect any attempted replacement/re-resolution of the approved immutable address set. */
+export function assertDestinationAddressSet(destination: LabDestinationV1, addresses: Array<{ address: string; family: 4 | 6 }>): void {
+  if (addressSetKey(destination.addresses) !== addressSetKey(addresses)) {
+    throw new LabDestinationError("destination address set mismatch", "destination_mismatch");
+  }
+}
+
+export function assertHostSniMatch(destination: LabDestinationV1, host: string, sni?: string): void {
+  if (host.toLowerCase() !== destination.host) throw new LabDestinationError("host mismatch", "host_sni_mismatch");
+  if (sni !== undefined && sni.toLowerCase() !== destination.sniHost) throw new LabDestinationError("SNI mismatch", "host_sni_mismatch");
+}