@iislee/opencodex 2.11.0 → 2.35.0

package/src/lab/public/signature.ts

@@ -0,0 +1,243 @@
+import {
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign as signBytes,
+  verify as verifyBytes,
+} from "node:crypto";
+import { ensureLabDirs, labPublicPublisherKeyPath } from "../paths";
+import { hardenSecretPath } from "../../lib/windows-secret-acl";
+import {
+  buildPublicEvidenceBundle,
+  canonicalPublicEvidenceContent,
+  expectedPublicBundleIdentityFromNormalized,
+  normalizePublicEvidenceContent,
+  type BuildPublicEvidenceBundleInput,
+} from "./bundle";
+import { validatePublicEvidenceAuthorities } from "./community-authority";
+import { privateRegularFileSize, readPrivateRegularFile } from "./file-safety";
+import { publicEvidenceId } from "./ids";
+import { cleanupStalePrivateFileStages, publishPrivateFileExclusive } from "./private-file";
+import { validatePublicEvidencePrivacy, validatePublicEvidenceRecordPrivacy } from "./privacy";
+import type {
+  PublicEvidenceBundleV1,
+  PublicPublisherV1,
+} from "./types";
+import { PublicEvidenceValidationError } from "./validate";
+
+const MAX_PRIVATE_KEY_BYTES = 8 * 1024;
+const PRIVATE_KEY_FILE_OPTIONS = {
+  maxBytes: MAX_PRIVATE_KEY_BYTES,
+  errorCode: "public_publisher_key_unsafe",
+  errorMessage: "public publisher key path is not a bounded private regular file with 0600 permissions",
+  requireMode600: true,
+} as const;
+
+export interface PublicPublisherHandle {
+  publisher: PublicPublisherV1;
+  privateKeyPath: string;
+}
+
+function publicKeyBase64(privateKeyPem: string): string {
+  const publicKey = createPublicKey(privateKeyPem);
+  return publicKey.export({ type: "spki", format: "der" }).toString("base64");
+}
+
+function publisherForPrivateKey(privateKeyPem: string): PublicPublisherV1 {
+  const publicKey = publicKeyBase64(privateKeyPem);
+  return {
+    algorithm: "ed25519",
+    keyId: publicEvidenceId("publisher_key", { algorithm: "ed25519", publicKey }),
+    publicKey,
+  };
+}
+
+/**
+ * The bounded errno-shaped code from a failed ACL harden, or null when the cause
+ * carries none.
+ *
+ * Only the code is allowed into the message. `hardenSecretPath` already sanitizes
+ * its own diagnostic prose, but this error is what reaches a CI log, so what
+ * crosses that boundary is re-checked here rather than trusted: an errno code has
+ * no separator, no lowercase and a bounded length, and therefore cannot carry the
+ * key pathname or the username component inside it.
+ */
+function aclFailureCode(error: unknown): string | null {
+  if (!(error instanceof Error) || !("code" in error)) return null;
+  const code = (error as NodeJS.ErrnoException).code;
+  return typeof code === "string" && /^[A-Z][A-Z0-9_]{1,30}$/.test(code) ? code : null;
+}
+
+function requirePublisherKeyAcl(path: string, timeoutMemoKey = path): void {
+  privateRegularFileSize(path, PRIVATE_KEY_FILE_OPTIONS);
+  let hardened: { ok: boolean };
+  let hardeningError: unknown;
+  try {
+    hardened = hardenSecretPath(path, { required: true, timeoutMemoKey });
+  } catch (error) {
+    hardeningError = error;
+    hardened = { ok: false };
+  }
+  if (!hardened.ok) {
+    // Name the cause in the message, not only on `cause`. Every harden failure
+    // reaches a CI log as this one string, and the three that occur there need
+    // different fixes: ETIMEDOUT is the budget, EACLIDENTITY is the effective-SID
+    // lookup, EICACLS is icacls refusing the path. A message identical across all
+    // three cannot be acted on without a Windows box to re-run it under (#2152).
+    const code = aclFailureCode(hardeningError);
+    const failure = new PublicEvidenceValidationError(
+      "public_publisher_key_unsafe",
+      code
+        ? `public publisher key ACL hardening did not complete (${code})`
+        : "public publisher key ACL hardening did not complete",
+    );
+    if (hardeningError !== undefined) {
+      (failure as Error & { cause?: unknown }).cause = hardeningError;
+    }
+    throw failure;
+  }
+}
+
+function readRestrictedPrivateKey(path: string): string {
+  cleanupStalePrivateFileStages(path);
+  // Prove the pathname is the expected private regular file before applying any
+  // platform ACL operation, then fail closed if Windows per-user ACL hardening
+  // cannot be established. The helper is a no-op success on non-Windows.
+  requirePublisherKeyAcl(path);
+  const pem = readPrivateRegularFile(path, PRIVATE_KEY_FILE_OPTIONS).toString("utf8");
+  const key = createPrivateKey(pem);
+  if (key.asymmetricKeyType !== "ed25519") {
+    throw new Error("public publisher key must be Ed25519");
+  }
+  return pem;
+}
+
+function createPrivateKeyFile(path: string): string {
+  const { privateKey } = generateKeyPairSync("ed25519", {
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    publicKeyEncoding: { type: "spki", format: "pem" },
+  });
+  publishPrivateFileExclusive(path, Buffer.from(privateKey, "utf8"), {
+    // On Windows, harden the empty stage before private key bytes are written.
+    // A required ACL failure therefore cannot strand secret bytes in a stage.
+    prepareStage: stagePath => requirePublisherKeyAcl(stagePath, path),
+  });
+  return readRestrictedPrivateKey(path);
+}
+
+export function loadExistingPublicPublisher(configDir?: string): PublicPublisherHandle | null {
+  const privateKeyPath = labPublicPublisherKeyPath(configDir);
+  try {
+    const privateKeyPem = readRestrictedPrivateKey(privateKeyPath);
+    return { publisher: publisherForPrivateKey(privateKeyPem), privateKeyPath };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export function getOrCreatePublicPublisher(configDir?: string): PublicPublisherHandle {
+  ensureLabDirs(configDir);
+  const existing = loadExistingPublicPublisher(configDir);
+  if (existing) return existing;
+  const privateKeyPath = labPublicPublisherKeyPath(configDir);
+  const privateKeyPem = createPrivateKeyFile(privateKeyPath);
+  return { publisher: publisherForPrivateKey(privateKeyPem), privateKeyPath };
+}
+
+/** Centralized descriptor-bound signing primitive for the installation publisher key. */
+export function signPublicPublisherDigest(handle: PublicPublisherHandle, digestHex: string): string {
+  if (!/^[0-9a-f]{64}$/.test(digestHex)) {
+    throw new PublicEvidenceValidationError("invalid_digest", "publisher signing digest must be lowercase sha256 hex");
+  }
+  const privateKeyPem = readRestrictedPrivateKey(handle.privateKeyPath);
+  return signBytes(null, Buffer.from(digestHex, "hex"), createPrivateKey(privateKeyPem)).toString("base64");
+}
+
+export interface SignPublicEvidenceBundleInput extends Omit<BuildPublicEvidenceBundleInput, "publisher"> {
+  configDir?: string;
+}
+
+function assertLocalArtifactExportAuthority(input: SignPublicEvidenceBundleInput): void {
+  if (input.artifacts.length !== 0) {
+    throw new PublicEvidenceValidationError(
+      "public_artifact_authority_required",
+      "artifact bytes require reviewed public_export policy authority before local signing",
+    );
+  }
+}
+
+export function signPublicEvidenceBundle(input: SignPublicEvidenceBundleInput): PublicEvidenceBundleV1 {
+  // Validate every caller-controlled invariant before publisher identity state is touched.
+  assertLocalArtifactExportAuthority(input);
+  const normalized = normalizePublicEvidenceContent({
+    records: input.records,
+    artifacts: input.artifacts,
+    createdDayUtc: input.createdDayUtc,
+  });
+  validatePublicEvidenceAuthorities(normalized.records);
+  for (const record of normalized.records) validatePublicEvidenceRecordPrivacy(record);
+
+  const handle = getOrCreatePublicPublisher(input.configDir);
+  const unsigned = buildPublicEvidenceBundle({ ...normalized, publisher: handle.publisher });
+  validatePublicEvidencePrivacy(unsigned);
+  return {
+    ...unsigned,
+    signature: {
+      algorithm: "ed25519",
+      signedDigest: unsigned.bundleDigest,
+      signature: signPublicPublisherDigest(handle, unsigned.bundleDigest),
+    },
+  };
+}
+
+export type PublicBundleVerificationResult =
+  | { status: "cryptographically_valid" }
+  | { status: "digest_invalid" }
+  | { status: "signature_invalid" }
+  | { status: "schema_rejected" };
+
+export function verifyPublicEvidenceBundle(bundle: PublicEvidenceBundleV1): PublicBundleVerificationResult {
+  try {
+    const raw = bundle as unknown as Record<string, unknown>;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { status: "schema_rejected" };
+    const allowed = new Set([
+      "schemaVersion",
+      "exportPolicyVersion",
+      "bundleId",
+      "createdDayUtc",
+      "publisher",
+      "records",
+      "artifacts",
+      "bundleDigest",
+      "signature",
+    ]);
+    if (Object.keys(raw).some((key) => !allowed.has(key))) return { status: "schema_rejected" };
+    if (bundle.schemaVersion !== "public_evidence_bundle_v1" || bundle.exportPolicyVersion !== "public_export_policy_v1") {
+      return { status: "schema_rejected" };
+    }
+    if (!bundle.signature || bundle.signature.algorithm !== "ed25519") return { status: "schema_rejected" };
+    if (Object.keys(bundle.signature).some((key) => !["algorithm", "signedDigest", "signature"].includes(key))) {
+      return { status: "schema_rejected" };
+    }
+    const canonical = canonicalPublicEvidenceContent(bundle);
+    if (!canonical.canonical) return { status: "schema_rejected" };
+    const expected = expectedPublicBundleIdentityFromNormalized(canonical.normalized, bundle.publisher);
+    if (bundle.bundleId !== expected.bundleId || bundle.bundleDigest !== expected.bundleDigest) {
+      return { status: "digest_invalid" };
+    }
+    if (bundle.signature.signedDigest !== bundle.bundleDigest) return { status: "signature_invalid" };
+    const key = createPublicKey({
+      key: Buffer.from(bundle.publisher.publicKey, "base64"),
+      type: "spki",
+      format: "der",
+    });
+    if (key.asymmetricKeyType !== "ed25519") return { status: "signature_invalid" };
+    const signature = Buffer.from(bundle.signature.signature, "base64");
+    if (signature.toString("base64") !== bundle.signature.signature) return { status: "signature_invalid" };
+    const valid = verifyBytes(null, Buffer.from(bundle.bundleDigest, "hex"), key, signature);
+    return valid ? { status: "cryptographically_valid" } : { status: "signature_invalid" };
+  } catch {
+    return { status: "schema_rejected" };
+  }
+}

package/src/lab/public/storage.ts

@@ -0,0 +1,105 @@
+import { join } from "node:path";
+import { isSha256Hex, jcsStringify } from "../digest";
+import { ensureLabDirs } from "../paths";
+import { MAX_PUBLIC_BUNDLE_BYTES } from "./bundle";
+import { validatePublicEvidenceAuthorities } from "./community-authority";
+import { readPrivateRegularFile } from "./file-safety";
+import { cleanupStalePrivateFileStages, publishPrivateFileExclusive } from "./private-file";
+import { validatePublicEvidencePrivacy } from "./privacy";
+import { parseStrictPublicJson } from "./strict-json";
+import type { PublicEvidenceBundleV1 } from "./types";
+import { verifyPublicEvidenceBundle } from "./signature";
+import { PublicEvidenceValidationError } from "./validate";
+
+function encodedBytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function bundlePath(bundleId: string, configDir?: string): string {
+  if (!isSha256Hex(bundleId)) throw new Error("public bundle id must be lowercase sha256 hex");
+  return join(ensureLabDirs(configDir).exportDir, `${bundleId}.json`);
+}
+
+function assertLocalArtifactExportAuthority(bundle: PublicEvidenceBundleV1): void {
+  if (bundle.artifacts.length !== 0) {
+    throw new PublicEvidenceValidationError(
+      "public_artifact_authority_required",
+      "artifact bytes require reviewed public_export policy authority before local export storage",
+    );
+  }
+}
+
+function readLocalExport(path: string): Buffer {
+  cleanupStalePrivateFileStages(path);
+  return readPrivateRegularFile(path, {
+    maxBytes: MAX_PUBLIC_BUNDLE_BYTES,
+    errorCode: "public_file_unsafe",
+    errorMessage: "public export is not a private regular file with 0600 permissions",
+    sizeErrorCode: "public_file_too_large",
+    sizeErrorMessage: "public bundle exceeds 2 MiB",
+    requireMode600: true,
+  });
+}
+
+function existingBody(path: string): string | null {
+  try {
+    return readLocalExport(path).toString("utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function validateLocalBundle(bundle: PublicEvidenceBundleV1): void {
+  const verification = verifyPublicEvidenceBundle(bundle);
+  if (verification.status !== "cryptographically_valid") {
+    throw new PublicEvidenceValidationError(verification.status, `public bundle verification failed: ${verification.status}`);
+  }
+  assertLocalArtifactExportAuthority(bundle);
+  validatePublicEvidenceAuthorities(bundle.records);
+  validatePublicEvidencePrivacy(bundle);
+}
+
+export function storePublicEvidenceBundle(
+  bundle: PublicEvidenceBundleV1,
+  configDir?: string,
+): { path: string; created: boolean } {
+  validateLocalBundle(bundle);
+  const body = jcsStringify(bundle) + "\n";
+  if (encodedBytes(body) > MAX_PUBLIC_BUNDLE_BYTES) {
+    throw new PublicEvidenceValidationError("public_file_too_large", "public bundle exceeds 2 MiB");
+  }
+  const path = bundlePath(bundle.bundleId, configDir);
+  const existing = existingBody(path);
+  if (existing !== null) {
+    if (existing === body) return { path, created: false };
+    throw new PublicEvidenceValidationError("public_export_conflict", "public export id collision with different bytes");
+  }
+
+  const published = publishPrivateFileExclusive(path, Buffer.from(body, "utf8"));
+  if (!published.created) {
+    const raced = existingBody(path);
+    if (raced === body) return { path, created: false };
+    throw new PublicEvidenceValidationError("public_export_conflict", "public export id collision with different bytes");
+  }
+  return { path, created: true };
+}
+
+/** Backward-compatible local storage helper for callers that need the private path. */
+export function writePublicEvidenceBundle(bundle: PublicEvidenceBundleV1, configDir?: string): string {
+  return storePublicEvidenceBundle(bundle, configDir).path;
+}
+
+export function readPublicEvidenceBundle(bundleId: string, configDir?: string): PublicEvidenceBundleV1 {
+  const bytes = readLocalExport(bundlePath(bundleId, configDir));
+  const raw = parseStrictPublicJson(bytes, "public export", "public_file_json");
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new PublicEvidenceValidationError("public_file_json", "public export must contain a bundle object");
+  }
+  const parsed = raw as PublicEvidenceBundleV1;
+  if (parsed.bundleId !== bundleId) {
+    throw new PublicEvidenceValidationError("public_file_identity", "public export filename does not match bundle id");
+  }
+  validateLocalBundle(parsed);
+  return parsed;
+}

package/src/lab/public/strict-json.ts

@@ -0,0 +1,206 @@
+import { PublicEvidenceValidationError } from "./validate";
+
+const MAX_PUBLIC_JSON_BYTES = 2 * 1024 * 1024;
+const MAX_PUBLIC_JSON_DEPTH = 8;
+const MAX_PUBLIC_JSON_OBJECT_KEYS = 64;
+const MAX_PUBLIC_JSON_ARRAY_ELEMENTS = 512;
+const MAX_PUBLIC_JSON_STRING_BYTES = 384 * 1024;
+
+function isJsonWhitespace(value: string | undefined): boolean {
+  return value === " " || value === "\n" || value === "\r" || value === "\t";
+}
+
+function malformedJson(code: string, message: string): never {
+  throw new PublicEvidenceValidationError(code, message);
+}
+
+function assertStrictPublicJsonShape(text: string, invalidCode: string): void {
+  let index = 0;
+  let depth = 0;
+
+  function invalid(message: string): never {
+    return malformedJson(invalidCode, message);
+  }
+
+  function skipWhitespace(): void {
+    while (isJsonWhitespace(text[index])) index += 1;
+  }
+
+  function parseStringToken(): string {
+    if (text[index] !== '"') invalid("public JSON contains an invalid string token");
+    const start = index;
+    index += 1;
+    let escaped = false;
+    while (index < text.length) {
+      const ch = text[index++]!;
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (ch === '"') {
+        if (Buffer.byteLength(text.slice(start + 1, index - 1), "utf8") > MAX_PUBLIC_JSON_STRING_BYTES) {
+          invalid(`public JSON string exceeds ${MAX_PUBLIC_JSON_STRING_BYTES} bytes`);
+        }
+        try {
+          const decoded = JSON.parse(text.slice(start, index));
+          if (typeof decoded !== "string") invalid("public JSON contains an invalid string token");
+          return decoded;
+        } catch (error) {
+          if (error instanceof PublicEvidenceValidationError) throw error;
+          invalid("public JSON contains an invalid string token");
+        }
+      }
+      if (ch.charCodeAt(0) < 0x20) invalid("public JSON contains an invalid control character");
+    }
+    invalid("public JSON contains an unterminated string token");
+  }
+
+  function parseScalar(): void {
+    const start = index;
+    while (index < text.length) {
+      const ch = text[index];
+      if (ch === "," || ch === "]" || ch === "}" || isJsonWhitespace(ch)) break;
+      index += 1;
+    }
+    if (start === index) invalid("public JSON contains an invalid value");
+    try {
+      const parsed = JSON.parse(text.slice(start, index));
+      if (parsed !== null && typeof parsed === "object") invalid("public JSON contains an invalid scalar value");
+    } catch (error) {
+      if (error instanceof PublicEvidenceValidationError) throw error;
+      invalid("public JSON contains an invalid scalar value");
+    }
+  }
+
+  function enterContainer(): void {
+    depth += 1;
+    if (depth > MAX_PUBLIC_JSON_DEPTH) {
+      invalid(`public JSON nesting depth exceeds ${MAX_PUBLIC_JSON_DEPTH}`);
+    }
+  }
+
+  function parseArray(): void {
+    enterContainer();
+    try {
+      index += 1;
+      skipWhitespace();
+      if (text[index] === "]") {
+        index += 1;
+        return;
+      }
+      let elementCount = 0;
+      while (index < text.length) {
+        elementCount += 1;
+        if (elementCount > MAX_PUBLIC_JSON_ARRAY_ELEMENTS) {
+          invalid(`public JSON array exceeds ${MAX_PUBLIC_JSON_ARRAY_ELEMENTS} elements`);
+        }
+        parseValue();
+        skipWhitespace();
+        if (text[index] === "]") {
+          index += 1;
+          return;
+        }
+        if (text[index] !== ",") invalid("public JSON array is malformed");
+        index += 1;
+        skipWhitespace();
+        if (text[index] === "]") invalid("public JSON array contains a trailing comma");
+      }
+      invalid("public JSON array is unterminated");
+    } finally {
+      depth -= 1;
+    }
+  }
+
+  function parseObject(): void {
+    enterContainer();
+    try {
+      index += 1;
+      skipWhitespace();
+      if (text[index] === "}") {
+        index += 1;
+        return;
+      }
+      const keys = new Set<string>();
+      while (index < text.length) {
+        if (text[index] !== '"') invalid("public JSON object key must be a string");
+        const key = parseStringToken();
+        if (keys.has(key)) {
+          throw new PublicEvidenceValidationError("duplicate_json_key", "duplicate JSON object key");
+        }
+        keys.add(key);
+        if (keys.size > MAX_PUBLIC_JSON_OBJECT_KEYS) {
+          invalid(`public JSON object exceeds ${MAX_PUBLIC_JSON_OBJECT_KEYS} keys`);
+        }
+        skipWhitespace();
+        if (text[index] !== ":") invalid("public JSON object is missing a colon");
+        index += 1;
+        parseValue();
+        skipWhitespace();
+        if (text[index] === "}") {
+          index += 1;
+          return;
+        }
+        if (text[index] !== ",") invalid("public JSON object is malformed");
+        index += 1;
+        skipWhitespace();
+        if (text[index] === "}") invalid("public JSON object contains a trailing comma");
+      }
+      invalid("public JSON object is unterminated");
+    } finally {
+      depth -= 1;
+    }
+  }
+
+  function parseValue(): void {
+    skipWhitespace();
+    const ch = text[index];
+    if (ch === "{") {
+      parseObject();
+      return;
+    }
+    if (ch === "[") {
+      parseArray();
+      return;
+    }
+    if (ch === '"') {
+      parseStringToken();
+      return;
+    }
+    parseScalar();
+  }
+
+  skipWhitespace();
+  if (index === text.length) invalid("public JSON is empty");
+  parseValue();
+  skipWhitespace();
+  if (index !== text.length) invalid("public JSON contains trailing data");
+}
+
+export function parseStrictPublicJson(
+  bytes: Uint8Array,
+  label = "public JSON",
+  invalidCode = "public_json",
+  maxBytes = MAX_PUBLIC_JSON_BYTES,
+): unknown {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+    throw new PublicEvidenceValidationError(invalidCode, `${label} byte limit is invalid`);
+  }
+  if (bytes.byteLength > maxBytes) {
+    throw new PublicEvidenceValidationError(invalidCode, `${label} exceeds ${maxBytes} bytes`);
+  }
+  const buffer = Buffer.from(bytes);
+  const text = buffer.toString("utf8");
+  if (!Buffer.from(text, "utf8").equals(buffer)) {
+    throw new PublicEvidenceValidationError(invalidCode, `${label} is not valid UTF-8 JSON`);
+  }
+  assertStrictPublicJsonShape(text, invalidCode);
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new PublicEvidenceValidationError(invalidCode, `${label} is not valid JSON`);
+  }
+}

package/src/lab/public/time.ts

@@ -0,0 +1,26 @@
+import { PublicEvidenceValidationError } from "./validate";
+
+/** Largest timestamp whose ISO-8601 year still fits the four-digit YYYY form. */
+const MAX_PUBLIC_DAY_TIMESTAMP_MS = Date.UTC(9999, 11, 31, 23, 59, 59, 999);
+
+/** Convert a bounded JavaScript timestamp into the public UTC day bucket. */
+export function publicUtcDay(timestampMs: number): string {
+  if (
+    !Number.isInteger(timestampMs)
+    || timestampMs < 0
+    || timestampMs > MAX_PUBLIC_DAY_TIMESTAMP_MS
+  ) {
+    throw new PublicEvidenceValidationError(
+      "public_selection_time",
+      "invalid observation completion timestamp",
+    );
+  }
+  const date = new Date(timestampMs);
+  if (!Number.isFinite(date.getTime())) {
+    throw new PublicEvidenceValidationError(
+      "public_selection_time",
+      "invalid observation completion timestamp",
+    );
+  }
+  return date.toISOString().slice(0, 10);
+}