@bitkyc08/opencodex 2.19.0 → 2.21.0

package/src/lab/paths.ts

@@ -81,10 +81,25 @@ export function labScratchDir(configDir = getConfigDir()): string {
   return join(labRoot(configDir), "scratch");
 }
 
+/** Shared Lab export directory. Public evidence bundles intentionally live here too. */
 export function labExportDir(configDir = getConfigDir()): string {
   return join(labRoot(configDir), "export");
 }
 
+export function labCommunityDir(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "community");
+}
+
+export function labPublicOriginDir(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "public-origin-v1");
+}
+
+export const LAB_PUBLIC_PUBLISHER_KEY_FILE = "publisher-ed25519.pem";
+
+export function labPublicPublisherKeyPath(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), LAB_PUBLIC_PUBLISHER_KEY_FILE);
+}
+
 /** Opaque per-installation salt for local fingerprinting (never exported as evidence). */
 export function labInstallationSaltPath(configDir = getConfigDir()): string {
   return join(labRoot(configDir), "installation-salt.bin");
@@ -110,15 +125,21 @@ export function ensureLabDirs(configDir = getConfigDir()): {
   artifactsDir: string;
   scratchDir: string;
   exportDir: string;
+  communityDir: string;
+  publicOriginDir: string;
 } {
   const root = labRoot(configDir);
   const artifactsDir = labArtifactsDir(configDir);
   const scratchDir = labScratchDir(configDir);
   const exportDir = labExportDir(configDir);
+  const communityDir = labCommunityDir(configDir);
+  const publicOriginDir = labPublicOriginDir(configDir);
   ensureRestrictedDir(root, root);
   ensureRestrictedDir(artifactsDir, root);
   ensureRestrictedDir(scratchDir, root);
   ensureRestrictedDir(exportDir, root);
+  ensureRestrictedDir(communityDir, root);
+  ensureRestrictedDir(publicOriginDir, root);
   return {
     root,
     ledgerPath: labLedgerPath(configDir),
@@ -126,5 +147,7 @@ export function ensureLabDirs(configDir = getConfigDir()): {
     artifactsDir,
     scratchDir,
     exportDir,
+    communityDir,
+    publicOriginDir,
   };
 }

package/src/lab/public/bundle.ts

@@ -0,0 +1,217 @@
+import { jcsStringify } from "../digest";
+import { publicEvidenceId } from "./ids";
+import {
+  PUBLIC_EVIDENCE_BUNDLE_SCHEMA_VERSION,
+  PUBLIC_EXPORT_POLICY_VERSION,
+  type PublicArtifactV1,
+  type PublicEvidenceBundleUnsignedV1,
+  type PublicEvidenceRecordV1,
+  type PublicPublisherV1,
+} from "./types";
+import { PublicEvidenceValidationError, validatePublicEvidenceRecord } from "./validate";
+
+export const MAX_PUBLIC_BUNDLE_BYTES = 2 * 1024 * 1024;
+export const MAX_PUBLIC_BUNDLE_RECORDS = 256;
+export const MAX_PUBLIC_BUNDLE_ARTIFACTS = 16;
+export const MAX_PUBLIC_ARTIFACT_BYTES = 256 * 1024;
+export const MAX_PUBLIC_ARTIFACT_BYTES_TOTAL = 1024 * 1024;
+
+export interface PublicEvidenceContentInput {
+  records: PublicEvidenceRecordV1[];
+  artifacts: PublicArtifactV1[];
+  createdDayUtc: string;
+}
+
+export interface BuildPublicEvidenceBundleInput extends PublicEvidenceContentInput {
+  publisher: PublicPublisherV1;
+}
+
+/** Deterministic, locale-independent code-unit ordering for canonical identity. */
+function compareCanonicalId(a: string, b: string): number {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function utcDay(value: string): string {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw new PublicEvidenceValidationError("invalid_day", "createdDayUtc must be YYYY-MM-DD");
+  }
+  const parsed = new Date(`${value}T00:00:00.000Z`);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== value) {
+    throw new PublicEvidenceValidationError("invalid_day", "createdDayUtc must be a real UTC day");
+  }
+  return value;
+}
+
+function validatePublisher(publisher: PublicPublisherV1): PublicPublisherV1 {
+  const raw = publisher as unknown as Record<string, unknown>;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new PublicEvidenceValidationError("invalid_publisher", "publisher must be an object");
+  }
+  const keys = Object.keys(raw);
+  if (keys.some((key) => !["algorithm", "keyId", "publicKey"].includes(key))) {
+    throw new PublicEvidenceValidationError("unknown_field", "publisher contains unknown fields");
+  }
+  if (publisher.algorithm !== "ed25519") {
+    throw new PublicEvidenceValidationError("unsupported_algorithm", "publisher must use ed25519");
+  }
+  if (!/^[0-9a-f]{64}$/.test(publisher.keyId)) {
+    throw new PublicEvidenceValidationError("invalid_publisher", "publisher.keyId must be sha256 hex");
+  }
+  if (typeof publisher.publicKey !== "string" || publisher.publicKey.length === 0 || publisher.publicKey.length > 1024) {
+    throw new PublicEvidenceValidationError("invalid_publisher", "publisher.publicKey is invalid");
+  }
+  const publicKeyBytes = Buffer.from(publisher.publicKey, "base64");
+  if (publicKeyBytes.byteLength === 0 || publicKeyBytes.toString("base64") !== publisher.publicKey) {
+    throw new PublicEvidenceValidationError("invalid_publisher", "publisher.publicKey must use canonical base64");
+  }
+  const expectedKeyId = publicEvidenceId("publisher_key", {
+    algorithm: publisher.algorithm,
+    publicKey: publisher.publicKey,
+  });
+  if (publisher.keyId !== expectedKeyId) {
+    throw new PublicEvidenceValidationError("publisher_key_id_mismatch", "publisher.keyId does not match public key");
+  }
+  return { algorithm: "ed25519", keyId: publisher.keyId, publicKey: publisher.publicKey };
+}
+
+function validateArtifacts(artifacts: PublicArtifactV1[]): PublicArtifactV1[] {
+  if (!Array.isArray(artifacts) || artifacts.length > MAX_PUBLIC_BUNDLE_ARTIFACTS) {
+    throw new PublicEvidenceValidationError("array_too_large", `artifacts exceeds ${MAX_PUBLIC_BUNDLE_ARTIFACTS}`);
+  }
+  let aggregate = 0;
+  const ids = new Set<string>();
+  return artifacts.map((artifact, index) => {
+    const raw = artifact as unknown as Record<string, unknown>;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}] must be an object`);
+    }
+    if (Object.keys(raw).some((key) => !["artifactId", "artifactClass", "mediaType", "byteCount", "contentBase64"].includes(key))) {
+      throw new PublicEvidenceValidationError("unknown_field", `artifacts[${index}] contains unknown fields`);
+    }
+    if (!/^[0-9a-f]{64}$/.test(artifact.artifactId)) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}].artifactId is invalid`);
+    }
+    if (typeof artifact.artifactClass !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:+-]{0,255}$/.test(artifact.artifactClass)) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}].artifactClass is invalid`);
+    }
+    if (typeof artifact.mediaType !== "string" || artifact.mediaType.length === 0 || artifact.mediaType.length > 256) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}].mediaType is invalid`);
+    }
+    if (!Number.isInteger(artifact.byteCount) || artifact.byteCount < 0 || artifact.byteCount > MAX_PUBLIC_ARTIFACT_BYTES) {
+      throw new PublicEvidenceValidationError("artifact_too_large", `artifacts[${index}].byteCount is invalid`);
+    }
+    let bytes: Buffer;
+    try {
+      bytes = Buffer.from(artifact.contentBase64, "base64");
+    } catch {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}].contentBase64 is invalid`);
+    }
+    if (bytes.byteLength !== artifact.byteCount || bytes.toString("base64") !== artifact.contentBase64) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}] byte count or base64 is non-canonical`);
+    }
+    const expectedArtifactId = publicEvidenceId("artifact", {
+      artifactClass: artifact.artifactClass,
+      mediaType: artifact.mediaType,
+      byteCount: artifact.byteCount,
+      contentBase64: artifact.contentBase64,
+    });
+    if (artifact.artifactId !== expectedArtifactId) {
+      throw new PublicEvidenceValidationError("artifact_id_mismatch", `artifacts[${index}].artifactId mismatch`);
+    }
+    aggregate += artifact.byteCount;
+    if (aggregate > MAX_PUBLIC_ARTIFACT_BYTES_TOTAL) {
+      throw new PublicEvidenceValidationError("artifact_aggregate_too_large", "artifact aggregate exceeds 1 MiB");
+    }
+    if (ids.has(artifact.artifactId)) {
+      throw new PublicEvidenceValidationError("duplicate_id", "artifacts contains duplicate ids");
+    }
+    ids.add(artifact.artifactId);
+    return { ...artifact };
+  });
+}
+
+/** Validate all publisher-independent bundle content before any signing-key state is touched. */
+export function normalizePublicEvidenceContent(input: PublicEvidenceContentInput): PublicEvidenceContentInput {
+  if (!Array.isArray(input.records) || input.records.length > MAX_PUBLIC_BUNDLE_RECORDS) {
+    throw new PublicEvidenceValidationError("array_too_large", `records exceeds ${MAX_PUBLIC_BUNDLE_RECORDS}`);
+  }
+  const records = input.records
+    .map(validatePublicEvidenceRecord)
+    .sort((a, b) => compareCanonicalId(a.recordId, b.recordId));
+  if (new Set(records.map((record) => record.recordId)).size !== records.length) {
+    throw new PublicEvidenceValidationError("duplicate_id", "records contains duplicate ids");
+  }
+  const artifacts = validateArtifacts(input.artifacts)
+    .sort((a, b) => compareCanonicalId(a.artifactId, b.artifactId));
+  const artifactIds = new Set(artifacts.map((artifact) => artifact.artifactId));
+  for (const record of records) {
+    for (const artifactId of record.artifactRefs ?? []) {
+      if (!artifactIds.has(artifactId)) {
+        throw new PublicEvidenceValidationError("artifact_ref_missing", `record ${record.recordId} references a missing public artifact`);
+      }
+    }
+  }
+  return { records, artifacts, createdDayUtc: utcDay(input.createdDayUtc) };
+}
+
+export function canonicalPublicEvidenceContent(
+  input: PublicEvidenceContentInput,
+): { canonical: boolean; normalized: PublicEvidenceContentInput } {
+  const normalized = normalizePublicEvidenceContent(input);
+  const canonical = input.records.length === normalized.records.length
+    && input.artifacts.length === normalized.artifacts.length
+    && input.records.every((record, index) => record.recordId === normalized.records[index]!.recordId)
+    && input.artifacts.every((artifact, index) => artifact.artifactId === normalized.artifacts[index]!.artifactId);
+  return { canonical, normalized };
+}
+
+export function hasCanonicalPublicEvidenceOrder(input: PublicEvidenceContentInput): boolean {
+  return canonicalPublicEvidenceContent(input).canonical;
+}
+
+function buildFromNormalizedContent(
+  normalized: PublicEvidenceContentInput,
+  publisherInput: PublicPublisherV1,
+): PublicEvidenceBundleUnsignedV1 {
+  const publisher = validatePublisher(publisherInput);
+  const content = {
+    schemaVersion: PUBLIC_EVIDENCE_BUNDLE_SCHEMA_VERSION,
+    exportPolicyVersion: PUBLIC_EXPORT_POLICY_VERSION,
+    createdDayUtc: normalized.createdDayUtc,
+    publisher,
+    records: normalized.records,
+    artifacts: normalized.artifacts,
+  };
+  const bundleId = publicEvidenceId("bundle", content);
+  const bundleDigest = publicEvidenceId("bundle_digest", { ...content, bundleId });
+  const bundle: PublicEvidenceBundleUnsignedV1 = { ...content, bundleId, bundleDigest };
+  if (new TextEncoder().encode(jcsStringify(bundle)).byteLength > MAX_PUBLIC_BUNDLE_BYTES) {
+    throw new PublicEvidenceValidationError("bundle_too_large", "public bundle exceeds 2 MiB");
+  }
+  return bundle;
+}
+
+export function buildPublicEvidenceBundle(input: BuildPublicEvidenceBundleInput): PublicEvidenceBundleUnsignedV1 {
+  return buildFromNormalizedContent(normalizePublicEvidenceContent(input), input.publisher);
+}
+
+export function expectedPublicBundleIdentityFromNormalized(
+  normalized: PublicEvidenceContentInput,
+  publisher: PublicPublisherV1,
+): { bundleId: string; bundleDigest: string } {
+  const rebuilt = buildFromNormalizedContent(normalized, publisher);
+  return { bundleId: rebuilt.bundleId, bundleDigest: rebuilt.bundleDigest };
+}
+
+export function expectedPublicBundleIdentity(bundle: PublicEvidenceBundleUnsignedV1): { bundleId: string; bundleDigest: string } {
+  return expectedPublicBundleIdentityFromNormalized(
+    normalizePublicEvidenceContent({
+      records: bundle.records,
+      artifacts: bundle.artifacts,
+      createdDayUtc: bundle.createdDayUtc,
+    }),
+    bundle.publisher,
+  );
+}

package/src/lab/public/community-authority.ts

@@ -0,0 +1,175 @@
+import { loadCaseAuthority } from "../conformance/manifest";
+import {
+  FABRIC_COMPATIBILITY_VERSION,
+  FABRIC_SCENARIO_ID,
+  FABRIC_SCENARIO_VERSION,
+  FABRIC_SUITE_ID,
+  FABRIC_SUITE_VERSION,
+  FABRIC_TASK_CLASS_ID,
+  FABRIC_TASK_CLASS_VERSION,
+} from "../fabric/constants";
+import { loadFabricCaseAuthority } from "../fabric/manifest";
+import { verifierManifestDigest } from "../fabric/subject";
+import { findPublicRouteRegistryEntry } from "./registry";
+import type { PublicEvidenceBundleV1, PublicEvidenceRecordV1, PublicRouteSubjectV1 } from "./types";
+import { PublicEvidenceValidationError } from "./validate";
+
+type ProtocolCaseAuthority = ReturnType<typeof loadCaseAuthority>;
+
+interface ProtocolAuthoritySnapshot {
+  scenarioVersion: string;
+  suiteVersion: string;
+  sourceCommit: string;
+  load: () => ProtocolCaseAuthority;
+}
+
+// Public records are historical evidence. Never replace an authority entry when a
+// protocol version advances: retain the old loader and append a new snapshot.
+const PROTOCOL_AUTHORITY_SNAPSHOTS: readonly ProtocolAuthoritySnapshot[] = Object.freeze([
+  Object.freeze({
+    scenarioVersion: "1.0.0",
+    suiteVersion: "1.0.0",
+    sourceCommit: "3ad5bb6bd3f76f6879d84b78ea39edd3e01ec296",
+    load: loadCaseAuthority,
+  }),
+]);
+
+const cachedCaseAuthorities = new Map<string, ProtocolCaseAuthority>();
+let cachedFabricCaseAuthority: ReturnType<typeof loadFabricCaseAuthority> | null = null;
+let cachedVerifierManifestDigest: string | null = null;
+
+function protocolAuthorityKey(snapshot: ProtocolAuthoritySnapshot): string {
+  return `${snapshot.suiteVersion}\0${snapshot.scenarioVersion}`;
+}
+
+function caseAuthorityFor(record: PublicEvidenceRecordV1): ProtocolCaseAuthority {
+  const snapshot = PROTOCOL_AUTHORITY_SNAPSHOTS.find((candidate) =>
+    candidate.scenarioVersion === record.scenarioVersion
+    && candidate.suiteVersion === record.suiteVersion
+  );
+  if (!snapshot) {
+    throw new PublicEvidenceValidationError(
+      "public_authority",
+      "scenario/suite authority version is not retained",
+    );
+  }
+
+  const key = protocolAuthorityKey(snapshot);
+  const cached = cachedCaseAuthorities.get(key);
+  if (cached) return cached;
+
+  const authority = snapshot.load();
+  if (
+    String(authority.manifestDefaults.version) !== snapshot.scenarioVersion
+    || String(authority.manifestDefaults.suiteVersion) !== snapshot.suiteVersion
+    || authority.sourceCommit !== snapshot.sourceCommit
+  ) {
+    throw new Error("public protocol authority snapshot drift");
+  }
+  cachedCaseAuthorities.set(key, authority);
+  return authority;
+}
+
+function fabricCaseAuthority(): ReturnType<typeof loadFabricCaseAuthority> {
+  cachedFabricCaseAuthority ??= loadFabricCaseAuthority();
+  return cachedFabricCaseAuthority;
+}
+
+function reviewedVerifierManifestDigest(): string {
+  cachedVerifierManifestDigest ??= verifierManifestDigest();
+  return cachedVerifierManifestDigest;
+}
+
+function validateRouteAuthority(subject: PublicRouteSubjectV1): void {
+  const entry = findPublicRouteRegistryEntry(subject.providerId, subject.modelId);
+  if (!entry || !entry.adapterFamilies.includes(subject.adapterFamily)) {
+    throw new PublicEvidenceValidationError("public_authority", "public route is not in reviewed registry authority");
+  }
+}
+
+function validateAssertionAuthority(
+  record: PublicEvidenceRecordV1,
+  assertions: readonly { id: string; required: boolean }[],
+): void {
+  const allowed = new Map(assertions.map((assertion) => [assertion.id, assertion.required] as const));
+  if (allowed.size !== assertions.length) {
+    throw new PublicEvidenceValidationError("public_authority", "reviewed scenario assertion authority contains duplicates");
+  }
+  if (record.assertions.length !== allowed.size) {
+    throw new PublicEvidenceValidationError(
+      "public_authority",
+      "public assertion set does not exactly match reviewed scenario authority",
+    );
+  }
+  const seen = new Set<string>();
+  for (const assertion of record.assertions) {
+    if (seen.has(assertion.id)) {
+      throw new PublicEvidenceValidationError("public_authority", "public assertion set contains duplicate assertion ids");
+    }
+    seen.add(assertion.id);
+    if (!allowed.has(assertion.id) || allowed.get(assertion.id) !== assertion.required) {
+      throw new PublicEvidenceValidationError(
+        "public_authority",
+        "public assertion id/required flag is not in reviewed scenario authority",
+      );
+    }
+  }
+  for (const assertionId of allowed.keys()) {
+    if (!seen.has(assertionId)) {
+      throw new PublicEvidenceValidationError("public_authority", "public assertion set is missing reviewed scenario authority");
+    }
+  }
+}
+
+function validateTaskAuthority(record: PublicEvidenceRecordV1): void {
+  const fabricAuthority = fabricCaseAuthority();
+  const caseRecord = fabricAuthority.cases.find((candidate) => candidate.id === FABRIC_SCENARIO_ID);
+  if (
+    !caseRecord
+    || record.suiteId !== FABRIC_SUITE_ID
+    || record.suiteVersion !== FABRIC_SUITE_VERSION
+    || record.scenarioId !== FABRIC_SCENARIO_ID
+    || record.scenarioVersion !== FABRIC_SCENARIO_VERSION
+    || record.subject.subjectKind !== "task"
+    || record.subject.taskClassId !== FABRIC_TASK_CLASS_ID
+    || record.subject.taskClassVersion !== FABRIC_TASK_CLASS_VERSION
+    || record.subject.taskFixtureDigest !== caseRecord.fixture.digest
+    || record.subject.verifierManifestDigest !== reviewedVerifierManifestDigest()
+    || record.subject.fabricCompatibilityVersion !== FABRIC_COMPATIBILITY_VERSION
+  ) {
+    throw new PublicEvidenceValidationError("public_authority", "task scenario/verifier authority mismatch");
+  }
+  validateAssertionAuthority(record, caseRecord.assertions);
+  validateRouteAuthority(record.subject.route);
+}
+
+function validateScenarioAuthority(record: PublicEvidenceRecordV1): void {
+  if (record.evidenceLayer === "task_effectiveness") {
+    validateTaskAuthority(record);
+    return;
+  }
+
+  const authority = caseAuthorityFor(record);
+  const caseRecord = authority.cases.find((candidate) => candidate.id === record.scenarioId);
+  if (!caseRecord || caseRecord.suite !== record.suiteId) {
+    throw new PublicEvidenceValidationError("public_authority", "scenario/suite authority mismatch");
+  }
+  validateAssertionAuthority(record, caseRecord.assertions);
+
+  if (record.evidenceLayer === "live_route_compatibility") {
+    if (record.subject.subjectKind !== "route") {
+      throw new PublicEvidenceValidationError("public_authority", "live route subject mismatch");
+    }
+    validateRouteAuthority(record.subject);
+  }
+}
+
+/** Repository-owned authority gate used by both local signing and community imports. */
+export function validatePublicEvidenceAuthorities(records: readonly PublicEvidenceRecordV1[]): void {
+  for (const record of records) validateScenarioAuthority(record);
+}
+
+export function validateCommunityEvidenceAuthorities(bundle: PublicEvidenceBundleV1): PublicEvidenceBundleV1 {
+  validatePublicEvidenceAuthorities(bundle.records);
+  return bundle;
+}

package/src/lab/public/community-files.ts

@@ -0,0 +1,29 @@
+const COMMUNITY_ID_FRAGMENT = "[0-9a-f]{64}";
+const COMMUNITY_BUNDLE_FILE_RE = new RegExp(
+  `^bundle-(${COMMUNITY_ID_FRAGMENT})-(${COMMUNITY_ID_FRAGMENT})\\.json$`,
+);
+const COMMUNITY_REVOCATION_FILE_RE = new RegExp(
+  `^revocation-(${COMMUNITY_ID_FRAGMENT})\\.json$`,
+);
+
+export interface CommunityBundleFileIdentity {
+  publisherKeyId: string;
+  bundleId: string;
+}
+
+export function communityBundleFileName(publisherKeyId: string, bundleId: string): string {
+  return `bundle-${publisherKeyId}-${bundleId}.json`;
+}
+
+export function communityRevocationFileName(revocationId: string): string {
+  return `revocation-${revocationId}.json`;
+}
+
+export function parseCommunityBundleFileName(name: string): CommunityBundleFileIdentity | null {
+  const match = COMMUNITY_BUNDLE_FILE_RE.exec(name);
+  return match ? { publisherKeyId: match[1]!, bundleId: match[2]! } : null;
+}
+
+export function isCommunityRevocationFileName(name: string): boolean {
+  return COMMUNITY_REVOCATION_FILE_RE.test(name);
+}