@iislee/opencodex 2.11.0 → 2.31.0

package/src/lab/public/privacy.ts

@@ -0,0 +1,143 @@
+import { isIP } from "node:net";
+import type {
+  PublicArtifactV1,
+  PublicEvidenceBundleUnsignedV1,
+  PublicEvidenceBundleV1,
+  PublicEvidenceRecordV1,
+  PublicEvidenceSubjectV1,
+} from "./types";
+import { PublicEvidenceValidationError } from "./validate";
+
+const FORBIDDEN_PUBLIC_STRING_PATTERNS: ReadonlyArray<{ label: string; pattern: RegExp }> = [
+  { label: "URL", pattern: /(?:https?|file):\/\//i },
+  {
+    label: "local path",
+    pattern:
+      /(?:[A-Za-z]:[\\/]|\\\\[A-Za-z0-9._-]+\\|(?:^|[\s"'([{=:])\/(?:Users|home|root|tmp|var|opt|private|etc|mnt|media|srv|usr|dev|run|Library|System|Applications|Volumes|bin|sbin|lib|lib64|proc|sys|boot|Network|cores|nix|snap|app)(?:\/|$))/i,
+  },
+  { label: "email", pattern: /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i },
+  { label: "IP address", pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b|\[[0-9a-f:]{2,}\]/i },
+  { label: "query string", pattern: /[?&][A-Za-z0-9_.~-]+=/ },
+  { label: "authorization/header material", pattern: /\b(?:authorization|proxy-authorization|cookie|set-cookie|x-api-key|api[_-]?key|bearer)\b/i },
+  { label: "credential", pattern: /\b(?:sk-[A-Za-z0-9_-]{8,}|gh[opusr]_[A-Za-z0-9]{8,}|github_pat_[A-Za-z0-9_]{8,}|AKIA[0-9A-Z]{12,})\b/ },
+  { label: "private key", pattern: /-----BEGIN [^-]*PRIVATE KEY-----/i },
+  { label: "local request/decision/Fabric id", pattern: /\b(?:request|decision|fabric)_[A-Za-z0-9_-]{6,}\b/i },
+  { label: "account/project/tenant context", pattern: /\b(?:account|tenant|project|organization|deployment)[=:][^\s]+/i },
+  { label: "precise timestamp", pattern: /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/ },
+];
+
+const PUBLIC_TEXT_ARTIFACT_MEDIA_TYPES = new Set([
+  "application/json",
+  "application/json; charset=utf-8",
+  "text/markdown",
+  "text/markdown; charset=utf-8",
+  "text/plain",
+  "text/plain; charset=utf-8",
+]);
+
+function containsIpLiteral(value: string): boolean {
+  if (isIP(value) !== 0) return true;
+  for (const candidate of value.match(/[0-9A-Fa-f:]{2,}/g) ?? []) {
+    if (candidate.includes(":") && isIP(candidate) === 6) return true;
+  }
+  return false;
+}
+
+function assertPrivacySafeString(value: string, field: string): void {
+  // `PUBLIC_IDENTIFIER` intentionally permits `:` for reviewed identifiers, so use
+  // Node's IP parser to validate colon-bearing candidates instead of rejecting them
+  // with a broad regex. This catches both whole-string and embedded IPv6 literals.
+  if (containsIpLiteral(value)) {
+    throw new PublicEvidenceValidationError(
+      "privacy_rejected",
+      `${field} contains forbidden IP address material`,
+    );
+  }
+  for (const { label, pattern } of FORBIDDEN_PUBLIC_STRING_PATTERNS) {
+    if (pattern.test(value)) {
+      throw new PublicEvidenceValidationError(
+        "privacy_rejected",
+        `${field} contains forbidden ${label} material`,
+      );
+    }
+  }
+}
+
+function scanSubject(subject: PublicEvidenceSubjectV1, field: string): void {
+  if (subject.subjectKind === "protocol") {
+    assertPrivacySafeString(subject.compatibilityVersion, `${field}.compatibilityVersion`);
+    assertPrivacySafeString(subject.adapterFamily, `${field}.adapterFamily`);
+    assertPrivacySafeString(subject.inboundProtocol, `${field}.inboundProtocol`);
+    assertPrivacySafeString(subject.upstreamProtocol, `${field}.upstreamProtocol`);
+    assertPrivacySafeString(subject.surface, `${field}.surface`);
+    return;
+  }
+  if (subject.subjectKind === "route") {
+    assertPrivacySafeString(subject.providerId, `${field}.providerId`);
+    assertPrivacySafeString(subject.modelId, `${field}.modelId`);
+    assertPrivacySafeString(subject.adapterFamily, `${field}.adapterFamily`);
+    assertPrivacySafeString(subject.compatibilityVersion, `${field}.compatibilityVersion`);
+    return;
+  }
+  scanSubject(subject.route, `${field}.route`);
+  assertPrivacySafeString(subject.taskClassId, `${field}.taskClassId`);
+  assertPrivacySafeString(subject.taskClassVersion, `${field}.taskClassVersion`);
+  assertPrivacySafeString(subject.fabricCompatibilityVersion, `${field}.fabricCompatibilityVersion`);
+}
+
+function scanArtifact(artifact: PublicArtifactV1, index: number): void {
+  const field = `bundle.artifacts[${index}]`;
+  assertPrivacySafeString(artifact.artifactClass, `${field}.artifactClass`);
+  assertPrivacySafeString(artifact.mediaType, `${field}.mediaType`);
+
+  if (!PUBLIC_TEXT_ARTIFACT_MEDIA_TYPES.has(artifact.mediaType.toLowerCase())) {
+    throw new PublicEvidenceValidationError(
+      "privacy_rejected",
+      `${field}.mediaType is not in the closed public text-artifact set`,
+    );
+  }
+  if (typeof artifact.contentBase64 !== "string") {
+    throw new PublicEvidenceValidationError("privacy_rejected", `${field}.contentBase64 is invalid`);
+  }
+  const bytes = Buffer.from(artifact.contentBase64, "base64");
+  if (bytes.toString("base64") !== artifact.contentBase64 || bytes.byteLength !== artifact.byteCount) {
+    throw new PublicEvidenceValidationError(
+      "privacy_rejected",
+      `${field}.contentBase64 is non-canonical or does not match byteCount`,
+    );
+  }
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new PublicEvidenceValidationError("privacy_rejected", `${field} is not valid UTF-8 text`);
+  }
+  assertPrivacySafeString(text, `${field}.content`);
+}
+
+export function validatePublicEvidenceRecordPrivacy(record: PublicEvidenceRecordV1): void {
+  assertPrivacySafeString(record.suiteId, "record.suiteId");
+  assertPrivacySafeString(record.suiteVersion, "record.suiteVersion");
+  assertPrivacySafeString(record.scenarioId, "record.scenarioId");
+  assertPrivacySafeString(record.scenarioVersion, "record.scenarioVersion");
+  scanSubject(record.subject, "record.subject");
+  for (const [index, assertion] of record.assertions.entries()) {
+    assertPrivacySafeString(assertion.id, `record.assertions[${index}].id`);
+  }
+  for (const [index, incident] of (record.incidentRefs ?? []).entries()) {
+    assertPrivacySafeString(incident.corpusId, `record.incidentRefs[${index}].corpusId`);
+  }
+}
+
+/**
+ * Second-pass CL-10 export privacy boundary. Hashes, signatures and publisher public-key
+ * bytes are intentionally not pattern-scanned; every human-semantic public string and
+ * every final text artifact byte is scanned before local signing/storage or import.
+ */
+export function validatePublicEvidencePrivacy(
+  bundle: PublicEvidenceBundleUnsignedV1 | PublicEvidenceBundleV1,
+): void {
+  assertPrivacySafeString(bundle.createdDayUtc, "bundle.createdDayUtc");
+  for (const record of bundle.records) validatePublicEvidenceRecordPrivacy(record);
+  for (const [index, artifact] of bundle.artifacts.entries()) scanArtifact(artifact, index);
+}

package/src/lab/public/private-file.ts

@@ -0,0 +1,261 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  constants as fsConstants,
+  fsyncSync,
+  linkSync,
+  lstatSync,
+  openSync,
+  readdirSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs";
+import type { Stats } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+export type PrivateFileCommitFault = "before_publish" | "parent_directory_sync" | null;
+let privateFileCommitFaultForTests: PrivateFileCommitFault = null;
+let privateFileCleanupSyncFaultForTests = false;
+const PRIVATE_STAGE_RE = /^\..+\.(\d+)\.[0-9a-f-]{36}\.tmp$/;
+export const PRIVATE_FILE_STAGE_RETENTION_MS = 24 * 60 * 60 * 1000;
+
+export interface PrivateFilePublishOptions {
+  /** Validate or harden the empty stage before caller-controlled bytes are written. */
+  prepareStage?: (stagePath: string) => void;
+}
+
+function cleanup(path: string): void {
+  try { unlinkSync(path); } catch { /* absent/already removed */ }
+}
+
+function pidDefinitelyDead(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ESRCH";
+  }
+}
+
+function staleTempPrefix(finalPath: string): string {
+  return `.${basename(finalPath)}.`;
+}
+
+function fsyncParentBestEffort(path: string): void {
+  if (process.platform === "win32") return;
+  let fd: number | null = null;
+  try {
+    fd = openSync(dirname(path), fsConstants.O_RDONLY);
+    fsyncSync(fd);
+  } catch {
+    // Cleanup durability is best-effort after unlink. Publication and crash-witness
+    // retirement use the strict path below and never swallow POSIX failures.
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}
+
+function fsyncParentStrict(path: string): void {
+  if (process.platform === "win32") return;
+  let fd: number | null = null;
+  try {
+    fd = openSync(dirname(path), fsConstants.O_RDONLY);
+    fsyncSync(fd);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code ?? "unknown";
+    const wrapped = new Error(`private-file parent directory sync failed (${code})`);
+    (wrapped as Error & { cause?: unknown }).cause = error;
+    throw wrapped;
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}
+
+function fsyncParentForPublication(path: string): void {
+  // Node does not provide a portable directory-fsync contract on Windows. The
+  // exclusive hard-link publication remains atomic there, while POSIX requires
+  // the parent directory sync before publication is reported as durable.
+  if (process.platform === "win32") return;
+  if (privateFileCommitFaultForTests === "parent_directory_sync") {
+    throw new Error("synthetic private-file parent directory sync failure");
+  }
+  fsyncParentStrict(path);
+}
+
+export function isPrivateFileStageName(name: string): boolean {
+  return PRIVATE_STAGE_RE.test(name);
+}
+
+function isPrivateRegularStage(stats: Stats): boolean {
+  return stats.isFile() && !stats.isSymbolicLink();
+}
+
+function shouldReclaimPrivateFileStage(dir: string, name: string, nowMs: number): boolean {
+  const match = PRIVATE_STAGE_RE.exec(name);
+  if (!match) return false;
+  const pid = Number(match[1]);
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+
+  let stats: Stats;
+  try {
+    stats = lstatSync(join(dir, name));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+  if (!isPrivateRegularStage(stats)) return false;
+
+  const expired = nowMs - stats.mtimeMs > PRIVATE_FILE_STAGE_RETENTION_MS;
+  const dead = pid !== process.pid && pidDefinitelyDead(pid);
+  return expired || dead;
+}
+
+/** Reclaim private-file stages whose writer is dead or whose crash witness is past the retention window. */
+export function cleanupStalePrivateFileStagesInDir(dir: string): void {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  const nowMs = Date.now();
+  const reclaimable = names.filter((name) => shouldReclaimPrivateFileStage(dir, name, nowMs));
+  if (reclaimable.length === 0) return;
+
+  // A stale stage can be the hard-link witness for a final name that was linked
+  // before a crash or directory-sync failure. Make that final directory entry
+  // durable before removing any such witness.
+  if (process.platform !== "win32" && privateFileCleanupSyncFaultForTests) {
+    throw new Error("synthetic private-file cleanup parent directory sync failure");
+  }
+  fsyncParentStrict(join(dir, "."));
+
+  let changed = false;
+  for (const name of reclaimable) {
+    try {
+      unlinkSync(join(dir, name));
+      changed = true;
+    } catch {
+      // Another cleanup or writer may have removed it after enumeration.
+    }
+  }
+  if (changed) fsyncParentBestEffort(join(dir, "."));
+}
+
+/** Reclaim staging links from dead writers or expired crash witnesses. */
+export function cleanupStalePrivateFileStages(finalPath: string): void {
+  cleanupStalePrivateFileStagesInDir(dirname(finalPath));
+}
+
+/** Remove only stage links that already reference the durable final inode. */
+function cleanupPublishedPrivateFileStages(finalPath: string): void {
+  let finalStats;
+  try {
+    finalStats = lstatSync(finalPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  if (!finalStats.isFile() || finalStats.isSymbolicLink()) return;
+
+  const dir = dirname(finalPath);
+  const prefix = staleTempPrefix(finalPath);
+  let changed = false;
+  for (const name of readdirSync(dir)) {
+    if (!name.startsWith(prefix) || !PRIVATE_STAGE_RE.test(name)) continue;
+    const stagePath = join(dir, name);
+    try {
+      const stageStats = lstatSync(stagePath);
+      if (!stageStats.isFile() || stageStats.isSymbolicLink()) continue;
+      if (stageStats.dev !== finalStats.dev || stageStats.ino !== finalStats.ino) continue;
+      unlinkSync(stagePath);
+      changed = true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+  if (changed) fsyncParentBestEffort(finalPath);
+}
+
+function writeAll(fd: number, bytes: Uint8Array): void {
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const count = writeSync(fd, bytes, offset, bytes.byteLength - offset);
+    if (count <= 0) throw new Error("private file write made no progress");
+    offset += count;
+  }
+}
+
+/**
+ * Publish immutable mode-0600 bytes without ever exposing a partially-written final path.
+ * The caller owns EEXIST comparison semantics because some objects are idempotent and
+ * others are identity conflicts. Staging files are target-scoped and stale stages from
+ * definitely-dead writers are reclaimed on the next read or publication attempt.
+ */
+export function publishPrivateFileExclusive(
+  finalPath: string,
+  bytes: Uint8Array,
+  options: PrivateFilePublishOptions = {},
+): { created: boolean } {
+  cleanupStalePrivateFileStages(finalPath);
+  const tempPath = join(
+    dirname(finalPath),
+    `${staleTempPrefix(finalPath)}${process.pid}.${randomUUID()}.tmp`,
+  );
+  let fd: number | null = null;
+  let preservePublishedStage = false;
+  try {
+    fd = openSync(tempPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+    // Secret callers can harden the empty stage before any sensitive bytes exist.
+    // A failure here can therefore leave at most an empty cleanup witness.
+    options.prepareStage?.(tempPath);
+    writeAll(fd, bytes);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = null;
+
+    if (privateFileCommitFaultForTests === "before_publish") {
+      throw new Error("synthetic private-file commit failure before publish");
+    }
+
+    try {
+      linkSync(tempPath, finalPath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+        // A prior publication may have linked the final entry but failed while
+        // syncing the parent directory. Re-sync before reporting idempotent success,
+        // then remove only stages that are hard links to that durable final inode.
+        fsyncParentForPublication(finalPath);
+        cleanupPublishedPrivateFileStages(finalPath);
+        return { created: false };
+      }
+      throw error;
+    }
+    try {
+      fsyncParentForPublication(finalPath);
+    } catch (error) {
+      // The final name exists, but POSIX durability was not established. Keep this
+      // exact hard-link stage so a retry can re-sync and then identify it by inode.
+      preservePublishedStage = true;
+      throw error;
+    }
+    return { created: true };
+  } finally {
+    if (fd !== null) closeSync(fd);
+    if (!preservePublishedStage) {
+      cleanup(tempPath);
+      fsyncParentBestEffort(finalPath);
+    }
+  }
+}
+
+/** Test-only fault seam at the atomic publication point. Import this module directly in tests. */
+export function setPrivateFileCommitFaultForTests(fault: PrivateFileCommitFault): void {
+  privateFileCommitFaultForTests = fault;
+}
+
+/** Test-only fault seam for strict stale-stage cleanup durability. */
+export function setPrivateFileCleanupSyncFaultForTests(enabled: boolean): void {
+  privateFileCleanupSyncFaultForTests = enabled;
+}

package/src/lab/public/project.ts

@@ -0,0 +1,124 @@
+import type { CompatibilityVerdict } from "../constants";
+import type { ObservationEvent, ProtocolSubjectV1 } from "../events/types";
+import { validatePublicEvidenceAuthorities } from "./community-authority";
+import { publicEvidenceId } from "./ids";
+import { validatePublicEvidenceRecordPrivacy } from "./privacy";
+import { publicUtcDay } from "./time";
+import {
+  PUBLIC_ADAPTER_FAMILIES,
+  type PublicAdapterFamily,
+  type PublicEvidenceProjectionResult,
+  type PublicEvidenceRecordV1,
+  type PublicIncidentRefV1,
+  type PublicProtocolSubjectV1,
+} from "./types";
+import {
+  isPublicIncidentRef,
+  PublicEvidenceValidationError,
+  validatePublicEvidenceRecord,
+} from "./validate";
+
+const PROJECTOR_INVARIANT_ERROR_CODES = new Set([
+  "subject_id_mismatch",
+  "record_id_mismatch",
+]);
+
+export interface ProjectPublicEvidenceRecordInput {
+  observation: ObservationEvent;
+  verdict: CompatibilityVerdict;
+  incidentRefs?: string[];
+  publicArtifactRefs?: string[];
+}
+
+function asPublicAdapterFamily(value: string): PublicAdapterFamily | undefined {
+  return (PUBLIC_ADAPTER_FAMILIES as readonly string[]).includes(value)
+    ? value as PublicAdapterFamily
+    : undefined;
+}
+
+function projectProtocolSubject(subject: ProtocolSubjectV1): PublicProtocolSubjectV1 | undefined {
+  const adapterFamily = asPublicAdapterFamily(subject.effectiveAdapter);
+  if (!adapterFamily) return undefined;
+  return {
+    subjectKind: "protocol",
+    compatibilityVersion: subject.opencodexCompatibilityVersion,
+    adapterFamily,
+    inboundProtocol: subject.inboundProtocol,
+    upstreamProtocol: subject.upstreamProtocol,
+    surface: subject.surface,
+  };
+}
+
+function projectIncidentRefs(values: string[] | undefined): PublicIncidentRefV1[] | undefined {
+  if (values === undefined) return undefined;
+  if (values.some((value) => !isPublicIncidentRef(value))) return undefined;
+  return values.map((corpusId) => ({ corpusId }));
+}
+
+/**
+ * Project one local observation into the closed public V1 record shape and apply the
+ * complete reviewed authority/privacy boundary before exposing it as exportable.
+ *
+ * Route and task observations deliberately fail closed here. Persisted RouteSubjectV1
+ * contains installation-salted provider-instance and endpoint identity, so the exact
+ * public/default route cannot be proven from ledger bytes alone. Dropping those fields
+ * would broaden a private exact route into a misleading public claim.
+ */
+export function projectPublicEvidenceRecord(
+  input: ProjectPublicEvidenceRecordInput,
+): PublicEvidenceProjectionResult {
+  const { observation } = input;
+
+  if (observation.evidenceLayer === "live_route_compatibility" || observation.evidenceLayer === "task_effectiveness") {
+    return { status: "not_exportable", reason: "private_route_identity" };
+  }
+  if (observation.evidenceLayer !== "protocol_conformance" || observation.subject.subjectKind !== "protocol") {
+    return { status: "not_exportable", reason: "unsupported_subject" };
+  }
+
+  const subject = projectProtocolSubject(observation.subject);
+  if (!subject) return { status: "not_exportable", reason: "unsupported_adapter_family" };
+
+  const incidentRefs = projectIncidentRefs(input.incidentRefs);
+  if (input.incidentRefs !== undefined && incidentRefs === undefined) {
+    return { status: "not_exportable", reason: "unsafe_public_field" };
+  }
+
+  try {
+    const subjectId = publicEvidenceId("subject", subject);
+    const withoutRecordId: Omit<PublicEvidenceRecordV1, "recordId"> = {
+      subjectId,
+      evidenceLayer: "protocol_conformance",
+      suiteId: observation.suiteId,
+      suiteVersion: observation.suiteVersion,
+      scenarioId: observation.scenarioId,
+      scenarioVersion: observation.scenarioVersion,
+      verdict: input.verdict,
+      observedDayUtc: publicUtcDay(observation.completedAt),
+      subject,
+      assertions: observation.assertions.map((assertion) => ({
+        id: assertion.id,
+        required: assertion.required,
+        passed: assertion.passed,
+      })),
+      ...(incidentRefs !== undefined ? { incidentRefs } : {}),
+      ...(input.publicArtifactRefs !== undefined ? { artifactRefs: [...input.publicArtifactRefs] } : {}),
+    };
+    const record = validatePublicEvidenceRecord({
+      recordId: publicEvidenceId("record", withoutRecordId),
+      ...withoutRecordId,
+    });
+    validatePublicEvidenceAuthorities([record]);
+    validatePublicEvidenceRecordPrivacy(record);
+    return { status: "exportable", record };
+  } catch (error) {
+    if (error instanceof PublicEvidenceValidationError) {
+      if (PROJECTOR_INVARIANT_ERROR_CODES.has(error.code)) throw error;
+      return { status: "not_exportable", reason: "unsafe_public_field", detailCode: error.code };
+    }
+    if (error instanceof TypeError && error.message.startsWith("jcsStringify:")) {
+      return { status: "not_exportable", reason: "unsafe_public_field" };
+    }
+    throw error;
+  }
+}

package/src/lab/public/purge-test-fault.ts

@@ -0,0 +1,21 @@
+export type PublicEvidencePurgeFaultForTests =
+  | "before_export_delete"
+  | "export_directory_sync"
+  | null;
+
+let purgeFaultForTests: PublicEvidencePurgeFaultForTests = null;
+
+/** Arms the internal deterministic fault seam and returns a scoped restore handle. */
+export function setPublicEvidencePurgeFaultForTests(
+  fault: PublicEvidencePurgeFaultForTests,
+): () => void {
+  const previous = purgeFaultForTests;
+  purgeFaultForTests = fault;
+  return () => {
+    purgeFaultForTests = previous;
+  };
+}
+
+export function publicEvidencePurgeFaultForTests(): PublicEvidencePurgeFaultForTests {
+  return purgeFaultForTests;
+}