@bitkyc08/opencodex 2.19.0 → 2.21.0

package/src/lab/public/community.ts

@@ -0,0 +1,479 @@
+import { lstatSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { jcsStringify } from "../digest";
+import { ensureLabDirs, labCommunityDir } from "../paths";
+import { validateCommunityEvidenceAuthorities } from "./community-authority";
+import { communityBundleFileName } from "./community-files";
+import { privateRegularFileSize, readPrivateRegularFile } from "./file-safety";
+import { withPublicEvidenceMutationLock } from "./mutation-lock";
+import { recordLocalPublicOrigin } from "./origin";
+import {
+  cleanupStalePrivateFileStages,
+  cleanupStalePrivateFileStagesInDir,
+  isPrivateFileStageName,
+  publishPrivateFileExclusive,
+} from "./private-file";
+import { validatePublicEvidencePrivacy } from "./privacy";
+import { verifyPublicEvidenceRevocation } from "./revocation";
+import { loadExistingPublicPublisher, verifyPublicEvidenceBundle } from "./signature";
+import { parseStrictPublicJson } from "./strict-json";
+import type {
+  CommunityEvidenceSummaryV1,
+  PublicEvidenceBundleV1,
+  PublicEvidenceRevocationV1,
+} from "./types";
+import { PublicEvidenceValidationError } from "./validate";
+
+const MAX_IMPORT_BYTES = 2 * 1024 * 1024;
+const MAX_CACHE_FILES = 512;
+const MAX_CACHE_BYTES = 64 * 1024 * 1024;
+const MAX_DEPTH = 8;
+const MAX_OBJECT_KEYS = 64;
+const MAX_ARRAY_ELEMENTS = 512;
+const MAX_GENERIC_STRING_BYTES = 384 * 1024;
+const COMMUNITY_MUTATION_LOCK_NAME = ".mutation-lock";
+const COMMUNITY_BUNDLE_FILE_RE = /^bundle-([0-9a-f]{64})-([0-9a-f]{64})\.json$/;
+const COMMUNITY_REVOCATION_FILE_RE = /^revocation-([0-9a-f]{64})\.json$/;
+
+const COMMUNITY_FILE_OPTIONS = {
+  maxBytes: MAX_IMPORT_BYTES,
+  errorCode: "community_unsafe_target",
+  errorMessage: "community object is not a bounded private regular file",
+  sizeErrorCode: "community_size",
+  sizeErrorMessage: "community file exceeds bound",
+} as const;
+
+type CommunitySummaryCache = {
+  directory: string;
+  fingerprint: string;
+  evidence: CommunityEvidenceSummaryV1[];
+};
+
+let communitySummaryCache: CommunitySummaryCache | null = null;
+
+function assertId(value: string): string {
+  if (!/^[0-9a-f]{64}$/.test(value)) {
+    throw new PublicEvidenceValidationError("community_id", "community object id invalid");
+  }
+  return value;
+}
+
+function scanStructure(value: unknown, depth = 0): void {
+  if (depth > MAX_DEPTH) {
+    throw new PublicEvidenceValidationError("community_depth", "community JSON nesting depth exceeded");
+  }
+  if (typeof value === "string") {
+    if (new TextEncoder().encode(value).byteLength > MAX_GENERIC_STRING_BYTES || value.includes("\0")) {
+      throw new PublicEvidenceValidationError("community_string", "community string invalid or oversized");
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > MAX_ARRAY_ELEMENTS) {
+      throw new PublicEvidenceValidationError("community_array", "community array bound exceeded");
+    }
+    for (const item of value) scanStructure(item, depth + 1);
+    return;
+  }
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value);
+    if (keys.length > MAX_OBJECT_KEYS) {
+      throw new PublicEvidenceValidationError("community_object", "community object key bound exceeded");
+    }
+    for (const key of keys) {
+      if (new TextEncoder().encode(key).byteLength > 4096) {
+        throw new PublicEvidenceValidationError("community_key", "community key oversized");
+      }
+      scanStructure((value as Record<string, unknown>)[key], depth + 1);
+    }
+  }
+}
+
+function boundedInput(raw: unknown): unknown {
+  let bytes: Buffer;
+  if (raw instanceof Uint8Array) {
+    bytes = Buffer.from(raw);
+  } else if (typeof raw === "string") {
+    bytes = Buffer.from(raw, "utf8");
+  } else {
+    scanStructure(raw);
+    bytes = Buffer.from(jcsStringify(raw), "utf8");
+  }
+  if (bytes.byteLength > MAX_IMPORT_BYTES) {
+    throw new PublicEvidenceValidationError("community_size", "community import exceeds 2 MiB");
+  }
+  const parsed = parseStrictPublicJson(bytes, "community import");
+  scanStructure(parsed);
+  return parsed;
+}
+
+function assertCommunityArtifactAuthority(bundle: PublicEvidenceBundleV1): void {
+  if (bundle.artifacts.length !== 0) {
+    throw new PublicEvidenceValidationError(
+      "public_artifact_authority_required",
+      "community artifact bytes require reviewed public_export policy authority",
+    );
+  }
+}
+
+function verifiedBundle(raw: unknown): PublicEvidenceBundleV1 {
+  const result = verifyPublicEvidenceBundle(raw as PublicEvidenceBundleV1);
+  if (result.status !== "cryptographically_valid") {
+    throw new PublicEvidenceValidationError(result.status, "community bundle verification failed");
+  }
+  const bundle = validateCommunityEvidenceAuthorities(raw as PublicEvidenceBundleV1);
+  assertCommunityArtifactAuthority(bundle);
+  validatePublicEvidencePrivacy(bundle);
+  return bundle;
+}
+
+function bundleObjectPath(publisherKeyId: string, bundleId: string, configDir?: string): string {
+  return join(
+    labCommunityDir(configDir),
+    communityBundleFileName(assertId(publisherKeyId), assertId(bundleId)),
+  );
+}
+
+function revocationObjectPath(revocationId: string, configDir?: string): string {
+  return join(labCommunityDir(configDir), `revocation-${assertId(revocationId)}.json`);
+}
+
+function readBounded(path: string): Buffer {
+  cleanupStalePrivateFileStages(path);
+  return readPrivateRegularFile(path, COMMUNITY_FILE_OPTIONS);
+}
+
+function cacheUsage(configDir?: string): { names: string[]; bytes: number } {
+  ensureLabDirs(configDir);
+  const dir = labCommunityDir(configDir);
+  cleanupStalePrivateFileStagesInDir(dir);
+  const names = readdirSync(dir)
+    .filter((name) => name !== COMMUNITY_MUTATION_LOCK_NAME && !isPrivateFileStageName(name))
+    .sort();
+  if (names.length > MAX_CACHE_FILES) {
+    throw new PublicEvidenceValidationError("community_cache_bound", "community cache file bound exceeded");
+  }
+  let bytes = 0;
+  for (const name of names) {
+    bytes += privateRegularFileSize(join(dir, name), COMMUNITY_FILE_OPTIONS);
+    if (bytes > MAX_CACHE_BYTES) {
+      throw new PublicEvidenceValidationError("community_cache_bound", "community cache byte bound exceeded");
+    }
+  }
+  return { names, bytes };
+}
+
+function assertCacheCanAdd(byteCount: number, configDir?: string): void {
+  const usage = cacheUsage(configDir);
+  if (usage.names.length >= MAX_CACHE_FILES || usage.bytes + byteCount > MAX_CACHE_BYTES) {
+    throw new PublicEvidenceValidationError("community_cache_bound", "community cache capacity exceeded");
+  }
+}
+
+function persistAtLocked(
+  path: string,
+  kind: "bundle" | "revocation",
+  value: unknown,
+  configDir?: string,
+  onCommit?: () => void,
+): { path: string; created: boolean } {
+  const bytes = Buffer.from(jcsStringify(value), "utf8");
+  if (bytes.byteLength > MAX_IMPORT_BYTES) {
+    throw new PublicEvidenceValidationError("community_size", "community object exceeds bound");
+  }
+
+  let created = false;
+  try {
+    try {
+      const existing = readBounded(path);
+      if (!existing.equals(bytes)) {
+        throw new PublicEvidenceValidationError("community_conflict", `${kind} identity already exists with different bytes`);
+      }
+    } catch (error) {
+      if (error instanceof PublicEvidenceValidationError) throw error;
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      assertCacheCanAdd(bytes.byteLength, configDir);
+      const published = publishPrivateFileExclusive(path, bytes);
+      if (!published.created) {
+        const raced = readBounded(path);
+        if (!raced.equals(bytes)) {
+          throw new PublicEvidenceValidationError("community_conflict", `${kind} identity already exists with different bytes`);
+        }
+      } else {
+        created = true;
+        cacheUsage(configDir);
+      }
+    }
+
+    onCommit?.();
+    if (created) communitySummaryCache = null;
+    return { path, created };
+  } catch (error) {
+    if (created) {
+      try { unlinkSync(path); } catch { /* preserve commit error */ }
+      communitySummaryCache = null;
+    }
+    throw error;
+  }
+}
+
+function persistAt(
+  path: string,
+  kind: "bundle" | "revocation",
+  value: unknown,
+  configDir?: string,
+  onCommit?: () => void,
+): { path: string; created: boolean } {
+  return withPublicEvidenceMutationLock(
+    configDir,
+    () => persistAtLocked(path, kind, value, configDir, onCommit),
+  );
+}
+
+function readJson(path: string): unknown {
+  const parsed = parseStrictPublicJson(readBounded(path), "stored community object");
+  scanStructure(parsed);
+  return parsed;
+}
+
+function files(configDir?: string): string[] {
+  return cacheUsage(configDir).names;
+}
+
+function readVerifiedBundleAt(path: string): PublicEvidenceBundleV1 {
+  return verifiedBundle(readJson(path));
+}
+
+function bundleFromName(name: string, configDir?: string): PublicEvidenceBundleV1 | null {
+  const match = COMMUNITY_BUNDLE_FILE_RE.exec(name);
+  if (!match) return null;
+  const publisherKeyId = match[1]!;
+  const bundleId = match[2]!;
+  const bundle = readVerifiedBundleAt(bundleObjectPath(publisherKeyId, bundleId, configDir));
+  if (bundle.bundleId !== bundleId || bundle.publisher.keyId !== publisherKeyId) {
+    throw new PublicEvidenceValidationError("community_identity_mismatch", "stored community bundle does not match filename identity");
+  }
+  return bundle;
+}
+
+function bundlesFromNames(names: readonly string[], configDir?: string): PublicEvidenceBundleV1[] {
+  const bundles: PublicEvidenceBundleV1[] = [];
+  for (const name of names) {
+    const bundle = bundleFromName(name, configDir);
+    if (bundle) bundles.push(bundle);
+  }
+  return bundles;
+}
+
+function restoreOwnPublisherOrigin(bundle: PublicEvidenceBundleV1, configDir?: string): void {
+  const local = loadExistingPublicPublisher(configDir);
+  if (!local) return;
+  if (
+    local.publisher.algorithm !== bundle.publisher.algorithm
+    || local.publisher.keyId !== bundle.publisher.keyId
+    || local.publisher.publicKey !== bundle.publisher.publicKey
+  ) return;
+  recordLocalPublicOrigin({ publisherKeyId: bundle.publisher.keyId, bundleId: bundle.bundleId }, configDir);
+}
+
+export function importCommunityEvidenceBundle(
+  raw: unknown,
+  configDir?: string,
+): { created: boolean; status: "cryptographically_valid"; bundleId: string; publisherKeyId: string; path: string } {
+  const bundle = verifiedBundle(boundedInput(raw));
+  ensureLabDirs(configDir);
+  const stored = persistAt(
+    bundleObjectPath(bundle.publisher.keyId, bundle.bundleId, configDir),
+    "bundle",
+    bundle,
+    configDir,
+    () => restoreOwnPublisherOrigin(bundle, configDir),
+  );
+  return { ...stored, status: "cryptographically_valid", bundleId: bundle.bundleId, publisherKeyId: bundle.publisher.keyId };
+}
+
+function readCommunityEvidenceBundleForPublisherLocked(
+  bundleId: string,
+  publisherKeyId: string,
+  configDir?: string,
+): PublicEvidenceBundleV1 {
+  const bundle = readVerifiedBundleAt(bundleObjectPath(publisherKeyId, bundleId, configDir));
+  if (bundle.bundleId !== bundleId || bundle.publisher.keyId !== publisherKeyId) {
+    throw new PublicEvidenceValidationError("community_identity_mismatch", "stored community bundle does not match filename identity");
+  }
+  return bundle;
+}
+
+export function readCommunityEvidenceBundleForPublisher(
+  bundleId: string,
+  publisherKeyId: string,
+  configDir?: string,
+): PublicEvidenceBundleV1 {
+  return withPublicEvidenceMutationLock(
+    configDir,
+    () => readCommunityEvidenceBundleForPublisherLocked(bundleId, publisherKeyId, configDir),
+  );
+}
+
+type RevocationMetadata = {
+  publisher?: { keyId?: unknown };
+  targets?: Array<{ kind?: unknown; id?: unknown }>;
+};
+
+function resolveTargetBundle(
+  revocation: unknown,
+  bundles: readonly PublicEvidenceBundleV1[],
+): PublicEvidenceBundleV1 {
+  if (!revocation || typeof revocation !== "object") {
+    throw new PublicEvidenceValidationError("revocation_target", "revocation target metadata unavailable");
+  }
+  const raw = revocation as RevocationMetadata;
+  if (!Array.isArray(raw.targets) || typeof raw.publisher?.keyId !== "string") {
+    throw new PublicEvidenceValidationError("revocation_target", "revocation targets or publisher unavailable");
+  }
+  const publisherKeyId = assertId(raw.publisher.keyId);
+  const publisherBundles = bundles
+    .filter((bundle) => bundle.publisher.keyId === publisherKeyId)
+    .sort((a, b) => a.bundleId.localeCompare(b.bundleId));
+  const bundleTargets = raw.targets.filter((target) => target.kind === "bundle" && typeof target.id === "string");
+  if (bundleTargets.length > 0) {
+    const targetIds = new Set(bundleTargets.map((target) => target.id));
+    if (targetIds.size !== 1) {
+      throw new PublicEvidenceValidationError("revocation_target", "revocation bundle targets are ambiguous");
+    }
+    const id = [...targetIds][0]!;
+    const candidate = publisherBundles.find((bundle) => bundle.bundleId === id);
+    if (!candidate) throw new PublicEvidenceValidationError("revocation_target", "revocation target bundle not found");
+    return candidate;
+  }
+  const fullyMatching = publisherBundles.filter((bundle) => raw.targets!.every((target) =>
+    target.kind === "record" && typeof target.id === "string"
+      && bundle.records.some((record) => record.recordId === target.id),
+  ));
+  if (fullyMatching.length === 0) {
+    throw new PublicEvidenceValidationError(
+      "revocation_target",
+      "revocation targets do not resolve to a verified bundle for the same publisher",
+    );
+  }
+  return fullyMatching[0]!;
+}
+
+function findTargetBundleLocked(revocation: unknown, configDir?: string): PublicEvidenceBundleV1 {
+  const names = files(configDir);
+  const raw = revocation as RevocationMetadata;
+  const publisherKeyId = typeof raw?.publisher?.keyId === "string" ? assertId(raw.publisher.keyId) : null;
+  const directBundleIds = Array.isArray(raw?.targets)
+    ? [...new Set(raw.targets.filter((target) => target.kind === "bundle" && typeof target.id === "string").map((target) => target.id as string))]
+    : [];
+  if (publisherKeyId && directBundleIds.length === 1) {
+    try {
+      return readCommunityEvidenceBundleForPublisherLocked(
+        assertId(directBundleIds[0]!),
+        publisherKeyId,
+        configDir,
+      );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new PublicEvidenceValidationError(
+          "revocation_target",
+          "revocation target bundle not found",
+        );
+      }
+      throw error;
+    }
+  }
+  return resolveTargetBundle(revocation, bundlesFromNames(names, configDir));
+}
+
+export function importCommunityEvidenceRevocation(
+  raw: unknown,
+  configDir?: string,
+): { created: boolean; status: "cryptographically_valid"; revocationId: string; path: string } {
+  const parsed = boundedInput(raw);
+  ensureLabDirs(configDir);
+  return withPublicEvidenceMutationLock(configDir, () => {
+    const targetBundle = findTargetBundleLocked(parsed, configDir);
+    const verified = verifyPublicEvidenceRevocation(parsed, targetBundle);
+    if (verified.status !== "cryptographically_valid") {
+      throw new PublicEvidenceValidationError(verified.status, verified.detail ?? "community revocation verification failed");
+    }
+    const stored = persistAtLocked(
+      revocationObjectPath(verified.revocation.revocationId, configDir),
+      "revocation",
+      verified.revocation,
+      configDir,
+    );
+    return { ...stored, status: "cryptographically_valid", revocationId: verified.revocation.revocationId };
+  });
+}
+
+function communityFingerprint(names: readonly string[], configDir?: string): string {
+  const dir = labCommunityDir(configDir);
+  return names.map((name) => {
+    const stat = lstatSync(join(dir, name));
+    return [name, stat.dev, stat.ino, stat.mode, stat.nlink, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+  }).join("\n");
+}
+
+function copySummaries(evidence: readonly CommunityEvidenceSummaryV1[]): CommunityEvidenceSummaryV1[] {
+  return evidence.map((row) => ({ ...row }));
+}
+
+function listCommunityEvidenceLocked(configDir?: string): CommunityEvidenceSummaryV1[] {
+  const names = files(configDir);
+  const directory = labCommunityDir(configDir);
+  const fingerprint = communityFingerprint(names, configDir);
+  if (communitySummaryCache?.directory === directory && communitySummaryCache.fingerprint === fingerprint) {
+    return copySummaries(communitySummaryCache.evidence);
+  }
+
+  const bundles = bundlesFromNames(names, configDir);
+  const revocations: PublicEvidenceRevocationV1[] = [];
+
+  for (const name of names) {
+    if (!COMMUNITY_REVOCATION_FILE_RE.test(name)) continue;
+    const raw = readJson(join(directory, name));
+    let targetBundle: PublicEvidenceBundleV1;
+    try {
+      targetBundle = resolveTargetBundle(raw, bundles);
+    } catch (error) {
+      if (error instanceof PublicEvidenceValidationError) continue;
+      throw error;
+    }
+    const verified = verifyPublicEvidenceRevocation(raw, targetBundle);
+    if (verified.status === "cryptographically_valid") revocations.push(verified.revocation);
+  }
+
+  const evidence = bundles.map((bundle) => {
+    const revoked = new Set<string>();
+    const bundleRecordIds = new Set(bundle.records.map((record) => record.recordId));
+    for (const revocation of revocations) {
+      if (revocation.publisher.keyId !== bundle.publisher.keyId
+        || revocation.publisher.publicKey !== bundle.publisher.publicKey) {
+        continue;
+      }
+      if (revocation.targets.some((target) => target.kind === "bundle" && target.id === bundle.bundleId)) {
+        for (const record of bundle.records) revoked.add(record.recordId);
+      }
+      for (const target of revocation.targets) {
+        if (target.kind === "record" && bundleRecordIds.has(target.id)) revoked.add(target.id);
+      }
+    }
+    return {
+      trustClass: "community_untrusted_v1" as const,
+      status: "cryptographically_valid" as const,
+      bundleId: bundle.bundleId,
+      publisherKeyId: bundle.publisher.keyId,
+      activeRecordCount: bundle.records.filter((record) => !revoked.has(record.recordId)).length,
+      revokedRecordCount: bundle.records.filter((record) => revoked.has(record.recordId)).length,
+    };
+  }).sort((a, b) => a.bundleId.localeCompare(b.bundleId) || a.publisherKeyId.localeCompare(b.publisherKeyId));
+
+  communitySummaryCache = { directory, fingerprint, evidence: copySummaries(evidence) };
+  return copySummaries(evidence);
+}
+
+export function listCommunityEvidence(configDir?: string): CommunityEvidenceSummaryV1[] {
+  return withPublicEvidenceMutationLock(configDir, () => listCommunityEvidenceLocked(configDir));
+}

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

@@ -0,0 +1,155 @@
+import {
+  closeSync,
+  constants as fsConstants,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  unlinkSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isPrivateFileStageName } from "./private-file";
+import { PublicEvidenceValidationError } from "./validate";
+
+const O_NOFOLLOW = (fsConstants as { O_NOFOLLOW?: number }).O_NOFOLLOW ?? 0;
+
+export interface PrivateRegularFileReadOptions {
+  maxBytes: number;
+  errorCode: string;
+  errorMessage: string;
+  sizeErrorCode?: string;
+  sizeErrorMessage?: string;
+  requireMode600?: boolean;
+}
+
+function sizeError(options: PrivateRegularFileReadOptions): PublicEvidenceValidationError {
+  return new PublicEvidenceValidationError(
+    options.sizeErrorCode ?? options.errorCode,
+    options.sizeErrorMessage ?? options.errorMessage,
+  );
+}
+
+/**
+ * Heal only the publication-specific hard link left behind when the final name was linked
+ * but the parent-directory durability check failed. The stage must be target-scoped and
+ * inode-identical to the final file; unrelated hard links remain and are rejected below.
+ */
+function recoverPublishedPrivateFileStage(path: string): void {
+  if (process.platform === "win32") return;
+  const finalStats = lstatSync(path);
+  if (finalStats.isSymbolicLink() || !finalStats.isFile() || finalStats.nlink <= 1) return;
+
+  const dir = dirname(path);
+  const prefix = `.${basename(path)}.`;
+  const candidates: string[] = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.startsWith(prefix) || !isPrivateFileStageName(name)) continue;
+    const stagePath = join(dir, name);
+    try {
+      const stageStats = lstatSync(stagePath);
+      if (
+        stageStats.isFile()
+        && !stageStats.isSymbolicLink()
+        && stageStats.dev === finalStats.dev
+        && stageStats.ino === finalStats.ino
+      ) {
+        candidates.push(stagePath);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+  if (candidates.length === 0) return;
+
+  // The final directory entry already exists. Make that entry durable before deleting
+  // the recovery witness. A real fsync failure propagates and the strict read stays closed.
+  let dirFd: number | null = null;
+  try {
+    dirFd = openSync(dir, fsConstants.O_RDONLY);
+    fsyncSync(dirFd);
+  } finally {
+    if (dirFd !== null) closeSync(dirFd);
+  }
+
+  for (const stagePath of candidates) {
+    try {
+      const stageStats = lstatSync(stagePath);
+      if (
+        stageStats.isFile()
+        && !stageStats.isSymbolicLink()
+        && stageStats.dev === finalStats.dev
+        && stageStats.ino === finalStats.ino
+      ) {
+        unlinkSync(stagePath);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}
+
+function withPrivateRegularFile<T>(
+  path: string,
+  options: PrivateRegularFileReadOptions,
+  consume: (fd: number, size: number) => T,
+): T {
+  let pathStats = lstatSync(path);
+  if (!pathStats.isSymbolicLink() && pathStats.isFile() && pathStats.nlink > 1) {
+    recoverPublishedPrivateFileStage(path);
+    pathStats = lstatSync(path);
+  }
+  if (pathStats.isSymbolicLink() || !pathStats.isFile() || pathStats.nlink !== 1) {
+    throw new PublicEvidenceValidationError(options.errorCode, options.errorMessage);
+  }
+  if (pathStats.size > options.maxBytes) throw sizeError(options);
+
+  const fd = openSync(path, fsConstants.O_RDONLY | O_NOFOLLOW);
+  try {
+    const stats = fstatSync(fd);
+    if (
+      !stats.isFile()
+      || stats.nlink !== 1
+      || stats.dev !== pathStats.dev
+      || stats.ino !== pathStats.ino
+    ) {
+      throw new PublicEvidenceValidationError(options.errorCode, options.errorMessage);
+    }
+    if (stats.size > options.maxBytes) throw sizeError(options);
+    if (options.requireMode600 && process.platform !== "win32" && (stats.mode & 0o777) !== 0o600) {
+      throw new PublicEvidenceValidationError(options.errorCode, options.errorMessage);
+    }
+    return consume(fd, stats.size);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Inspect a file only after proving that the pathname and checked descriptor refer to
+ * the same private regular file. This keeps quota scans descriptor-bound without
+ * reading every cached object into memory.
+ */
+export function privateRegularFileSize(
+  path: string,
+  options: PrivateRegularFileReadOptions,
+): number {
+  return withPrivateRegularFile(path, options, (_fd, size) => size);
+}
+
+/**
+ * Read bytes only after proving that the pathname and the consumed descriptor refer to
+ * the same private regular file. The lstat/dev+ino comparison keeps the protection on
+ * platforms where O_NOFOLLOW is unavailable instead of silently following a symlink.
+ */
+export function readPrivateRegularFile(
+  path: string,
+  options: PrivateRegularFileReadOptions,
+): Buffer {
+  return withPrivateRegularFile(path, options, (fd) => {
+    const bytes = readFileSync(fd);
+    if (bytes.byteLength > options.maxBytes) throw sizeError(options);
+    return bytes;
+  });
+}

package/src/lab/public/ids.ts

@@ -0,0 +1,26 @@
+import { domainHash, jcsStringify } from "../digest";
+
+export type PublicEvidenceIdKind =
+  | "subject"
+  | "record"
+  | "bundle"
+  | "bundle_digest"
+  | "artifact"
+  | "publisher_key"
+  | "revocation"
+  | "route_registry";
+
+const PUBLIC_EVIDENCE_DOMAIN: Record<PublicEvidenceIdKind, string> = {
+  subject: "ocx-lab-public:subject:v1",
+  record: "ocx-lab-public:record:v1",
+  bundle: "ocx-lab-public:bundle:v1",
+  bundle_digest: "ocx-lab-public:bundle-digest:v1",
+  artifact: "ocx-lab-public:artifact:v1",
+  publisher_key: "ocx-lab-public:publisher-key:v1",
+  revocation: "ocx-lab-public:revocation:v1",
+  route_registry: "ocx-lab-public:route-registry:v1",
+};
+
+export function publicEvidenceId(kind: PublicEvidenceIdKind, payload: unknown): string {
+  return domainHash(PUBLIC_EVIDENCE_DOMAIN[kind], jcsStringify(payload));
+}

package/src/lab/public/index.ts

@@ -0,0 +1,16 @@
+export * from "./types";
+export * from "./ids";
+export * from "./registry";
+export * from "./validate";
+export * from "./privacy";
+export * from "./project";
+export * from "./bundle";
+export * from "./signature";
+export * from "./storage";
+export * from "./community-authority";
+export * from "./revocation";
+export * from "./community";
+export * from "./strict-json";
+export * from "./origin";
+export * from "./operator";
+export * from "./purge";