@tiangong-lca/pcr 0.3.0 → 0.4.0

package/packages/pcr-core/src/read-context.mjs

@@ -1,505 +0,0 @@
-import { createHash } from "node:crypto";
-import {
-  closeSync,
-  constants as fsConstants,
-  fstatSync,
-  lstatSync,
-  openSync,
-  readFileSync,
-  realpathSync,
-} from "node:fs";
-import path from "node:path";
-
-import {
-  PCR_ID_ALIAS_REGISTRY_PATH,
-  pcrIdAliasValidationDependencies,
-  pcrIdAliasSourcePcrPathStates,
-  readPcrIdAliases,
-} from "./pcr-id-aliases.mjs";
-import { parseYaml } from "./yaml-lite.mjs";
-
-const CATALOG_PATH = "library/catalog.yaml";
-const MANAGED_READ_FLAGS =
-  fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK;
-const contextBindings = new WeakMap();
-const contextAliasDependencyPaths = new WeakMap();
-const contextAliasSourcePathStates = new WeakMap();
-const contextSessions = new WeakMap();
-const contextCatalogs = new WeakMap();
-const contextObservers = new WeakMap();
-
-export class PcrReadContextStaleError extends Error {
-  constructor({ root, source, reason }) {
-    super(`PCR read context is stale for ${source}: ${reason}.`);
-    this.name = "PcrReadContextStaleError";
-    this.code = "PCR_READ_CONTEXT_STALE";
-    this.details = { root, source, reason };
-  }
-}
-
-/**
- * Bind repeated PCR reads to one validated repository state. The context is
- * deliberately independent from the process-global catalog cache: callers
- * may retain it only while all catalog-declared inputs remain byte-identical.
- */
-export function createPcrReadContext({
-  root,
-  onAliasValidation = null,
-  beforeAliasValidation = null,
-  onBindingCheck = null,
-  onCatalogSnapshot = null,
-  onPcrArtifactRead = null,
-  beforeBoundSourceOpen = null,
-  validatedAliasReuse = null,
-}) {
-  const rootPath = canonicalRoot(root);
-  const catalogSource = readRepositoryFile({ root: rootPath, relativePath: CATALOG_PATH });
-  const catalog = parseCatalog(catalogSource.text, rootPath);
-  const dependencyPaths = catalogDependencyPaths(catalog, rootPath);
-  const aliasDependencyPathsBefore = pcrIdAliasValidationDependencies({ root: rootPath });
-  const aliasSourcePathStatesBefore = pcrIdAliasSourcePcrPathStates({ root: rootPath });
-  const boundPaths = [CATALOG_PATH, ...dependencyPaths, ...aliasDependencyPathsBefore];
-  const bindingsBefore = captureBindings({
-    root: rootPath,
-    relativePaths: boundPaths,
-    beforeBoundSourceOpen,
-  });
-  if (bindingsBefore.get(CATALOG_PATH) !== catalogSource.sha256) {
-    throw new PcrReadContextStaleError({
-      root: rootPath,
-      source: CATALOG_PATH,
-      reason: "catalog changed after its dependency declarations were read",
-    });
-  }
-  const aliasFingerprintBefore = aliasInputFingerprint({
-    bindings: bindingsBefore,
-    aliasDependencyPaths: aliasDependencyPathsBefore,
-    aliasSourcePathStates: aliasSourcePathStatesBefore,
-  });
-  let aliases;
-  if (validatedAliasReuse !== null) {
-    const declaredRegistry = parseYaml(readRepositoryFile({
-      root: rootPath,
-      relativePath: declaredPath(catalog.pcr_id_aliases?.path, "pcr_id_aliases.path", rootPath),
-    }).text);
-    const declaredAliases = Array.isArray(declaredRegistry?.aliases)
-      ? structuredClone(declaredRegistry.aliases).sort(compareAliases)
-      : null;
-    const attestedAliases = Array.isArray(validatedAliasReuse?.aliases)
-      ? structuredClone(validatedAliasReuse.aliases).sort(compareAliases)
-      : null;
-    if (
-      validatedAliasReuse?.fingerprint !== aliasFingerprintBefore ||
-      attestedAliases === null ||
-      declaredAliases === null ||
-      stableJson(attestedAliases) !== stableJson(declaredAliases)
-    ) {
-      throw new PcrReadContextStaleError({
-        root: rootPath,
-        source: PCR_ID_ALIAS_REGISTRY_PATH,
-        reason: "validated alias reuse attestation does not match current bound inputs",
-      });
-    }
-    aliases = attestedAliases;
-  } else {
-    beforeAliasValidation?.({ root: rootPath });
-    aliases = readPcrIdAliases({ root: rootPath });
-    onAliasValidation?.({
-      root: rootPath,
-      aliases: deepFreeze(structuredClone(aliases)),
-    });
-  }
-  const aliasDependencyPathsAfter = pcrIdAliasValidationDependencies({ root: rootPath });
-  const aliasSourcePathStatesAfter = pcrIdAliasSourcePcrPathStates({ root: rootPath });
-  if (!sameStrings(aliasDependencyPathsBefore, aliasDependencyPathsAfter)) {
-    throw new PcrReadContextStaleError({
-      root: rootPath,
-      source: PCR_ID_ALIAS_REGISTRY_PATH,
-      reason: "alias validation dependencies changed while aliases were validated",
-    });
-  }
-  if (!sameRecords(aliasSourcePathStatesBefore, aliasSourcePathStatesAfter)) {
-    throw new PcrReadContextStaleError({
-      root: rootPath,
-      source: PCR_ID_ALIAS_REGISTRY_PATH,
-      reason: "alias source PCR path states changed while aliases were validated",
-    });
-  }
-  const bindingsAfter = captureBindings({
-    root: rootPath,
-    relativePaths: boundPaths,
-    beforeBoundSourceOpen,
-  });
-  assertBindingSnapshotsMatch({ root: rootPath, before: bindingsBefore, after: bindingsAfter });
-  if (aliasInputFingerprint({
-    bindings: bindingsAfter,
-    aliasDependencyPaths: aliasDependencyPathsAfter,
-    aliasSourcePathStates: aliasSourcePathStatesAfter,
-  }) !== aliasFingerprintBefore) {
-    throw new PcrReadContextStaleError({
-      root: rootPath,
-      source: PCR_ID_ALIAS_REGISTRY_PATH,
-      reason: "alias reuse inputs changed while the read context was created",
-    });
-  }
-
-  const aliasByPcrId = new Map();
-  for (const alias of aliases) {
-    aliasByPcrId.set(String(alias?.source_pcr_id), deepFreeze(structuredClone(alias)));
-  }
-  const immutableAliases = deepFreeze([...aliasByPcrId.values()].map((alias) => structuredClone(alias)));
-  const context = {
-    root: rootPath,
-    aliases: immutableAliases,
-    findPcrIdAlias(pcrId, { root: requestedRoot = rootPath } = {}) {
-      assertPcrReadContextFresh({ context, root: requestedRoot });
-      const alias = aliasByPcrId.get(String(pcrId));
-      return alias ? structuredClone(alias) : null;
-    },
-  };
-  Object.defineProperty(context, "_pcrReadContext", { value: true });
-  contextBindings.set(context, bindingsAfter);
-  contextAliasDependencyPaths.set(context, aliasDependencyPathsAfter);
-  contextAliasSourcePathStates.set(context, aliasSourcePathStatesAfter);
-  contextObservers.set(context, { onBindingCheck, onCatalogSnapshot, onPcrArtifactRead });
-  return Object.freeze(context);
-}
-
-export function pcrReadContextAliasInputFingerprint({ root }) {
-  const rootPath = canonicalRoot(root);
-  const dependencyPaths = pcrIdAliasValidationDependencies({ root: rootPath });
-  const sourcePathStates = pcrIdAliasSourcePcrPathStates({ root: rootPath });
-  const bindings = captureBindings({
-    root: rootPath,
-    relativePaths: [CATALOG_PATH, ...dependencyPaths],
-  });
-  return aliasInputFingerprint({
-    bindings,
-    aliasDependencyPaths: dependencyPaths,
-    aliasSourcePathStates: sourcePathStates,
-  });
-}
-
-export function isPcrReadContext(value) {
-  return Boolean(
-    value?._pcrReadContext === true &&
-      typeof value.root === "string" &&
-      contextBindings.has(value),
-  );
-}
-
-export function assertPcrReadContextFresh({ context, root }) {
-  if (!isPcrReadContext(context)) {
-    throw new TypeError("context must be created by createPcrReadContext");
-  }
-  let canonicalRequestedRoot;
-  try {
-    canonicalRequestedRoot = canonicalRoot(root ?? context.root);
-  } catch {
-    throw new PcrReadContextStaleError({
-      root: context.root,
-      source: CATALOG_PATH,
-      reason: "requested root is unavailable",
-    });
-  }
-  if (canonicalRequestedRoot !== context.root) {
-    throw new PcrReadContextStaleError({
-      root: context.root,
-      source: CATALOG_PATH,
-      reason: "context belongs to another repository root",
-    });
-  }
-  if (contextSessions.get(context)?.root === context.root) {
-    return context;
-  }
-  contextObservers.get(context)?.onBindingCheck?.({ root: context.root });
-  let currentAliasDependencyPaths;
-  try {
-    currentAliasDependencyPaths = pcrIdAliasValidationDependencies({ root: context.root });
-  } catch {
-    throw new PcrReadContextStaleError({
-      root: context.root,
-      source: PCR_ID_ALIAS_REGISTRY_PATH,
-      reason: "alias validation dependencies are unavailable",
-    });
-  }
-  if (!sameStrings(contextAliasDependencyPaths.get(context) ?? [], currentAliasDependencyPaths)) {
-    throw new PcrReadContextStaleError({
-      root: context.root,
-      source: PCR_ID_ALIAS_REGISTRY_PATH,
-      reason: "alias validation dependency set changed",
-    });
-  }
-  const currentAliasSourcePathStates = pcrIdAliasSourcePcrPathStates({ root: context.root });
-  if (!sameRecords(contextAliasSourcePathStates.get(context) ?? [], currentAliasSourcePathStates)) {
-    throw new PcrReadContextStaleError({
-      root: context.root,
-      source: PCR_ID_ALIAS_REGISTRY_PATH,
-      reason: "alias source PCR path state changed",
-    });
-  }
-  for (const [relativePath, expectedSha256] of contextBindings.get(context) ?? []) {
-    let actualSha256;
-    try {
-      actualSha256 = readRepositoryFile({ root: context.root, relativePath }).sha256;
-    } catch {
-      throw new PcrReadContextStaleError({
-        root: context.root,
-        source: relativePath,
-        reason: "bound source is unavailable",
-      });
-    }
-    if (actualSha256 !== expectedSha256) {
-      throw new PcrReadContextStaleError({
-        root: context.root,
-        source: relativePath,
-        reason: "exact-byte fingerprint changed",
-      });
-    }
-  }
-  return context;
-}
-
-export function withPcrReadContextSession({ context, root, read }) {
-  assertPcrReadContextFresh({ context, root });
-  const active = contextSessions.get(context);
-  if (active) {
-    active.depth += 1;
-    try {
-      return readSynchronously(read);
-    } finally {
-      active.depth -= 1;
-    }
-  }
-  const session = { root: context.root, depth: 1 };
-  contextSessions.set(context, session);
-  try {
-    return readSynchronously(read);
-  } finally {
-    contextSessions.delete(context);
-    assertPcrReadContextFresh({ context, root });
-  }
-}
-
-export function getPcrReadContextCatalog({ context, root, readCatalog }) {
-  assertPcrReadContextFresh({ context, root });
-  if (!contextCatalogs.has(context)) {
-    const entries = readCatalog(context.root);
-    const entriesById = new Map(entries.map((entry) => [entry.id, structuredClone(entry)]));
-    contextCatalogs.set(context, entriesById);
-    contextObservers.get(context)?.onCatalogSnapshot?.({
-      root: context.root,
-      entryCount: entriesById.size,
-    });
-  }
-  return contextCatalogs.get(context);
-}
-
-export function observePcrReadContextArtifactRead({ context, root, relativePath }) {
-  assertPcrReadContextFresh({ context, root });
-  contextObservers.get(context)?.onPcrArtifactRead?.({
-    root: context.root,
-    relative_path: String(relativePath),
-  });
-}
-
-export function findPcrIdAliasInReadContext({ context, root, pcrId }) {
-  assertPcrReadContextFresh({ context, root });
-  return context.findPcrIdAlias(pcrId);
-}
-
-function canonicalRoot(root) {
-  const resolved = path.resolve(root);
-  const stats = lstatSync(resolved);
-  if (stats.isSymbolicLink() || !stats.isDirectory()) {
-    throw new Error(`PCR repository root is not a canonical directory: ${resolved}`);
-  }
-  return realpathSync(resolved);
-}
-
-function parseCatalog(text, root) {
-  let catalog;
-  try {
-    catalog = parseYaml(text);
-  } catch (error) {
-    throw new PcrReadContextStaleError({
-      root,
-      source: CATALOG_PATH,
-      reason: `catalog could not be parsed (${error instanceof Error ? error.message : String(error)})`,
-    });
-  }
-  if (!catalog || typeof catalog !== "object" || Array.isArray(catalog)) {
-    throw new PcrReadContextStaleError({ root, source: CATALOG_PATH, reason: "catalog is not an object" });
-  }
-  return catalog;
-}
-
-function catalogDependencyPaths(catalog, root) {
-  const paths = [
-    declaredPath(catalog.pcr_index, "pcr_index", root),
-    declaredPath(catalog.pcr_id_aliases?.path, "pcr_id_aliases.path", root),
-    ...declaredPaths(catalog.classification_mappings, "classification_mappings", root),
-    ...declaredPaths(catalog.classification_coverage_indexes ?? [], "classification_coverage_indexes", root),
-  ];
-  if (!paths.includes(PCR_ID_ALIAS_REGISTRY_PATH)) {
-    throw new PcrReadContextStaleError({
-      root,
-      source: CATALOG_PATH,
-      reason: `pcr_id_aliases.path must be ${PCR_ID_ALIAS_REGISTRY_PATH}`,
-    });
-  }
-  return [...new Set(paths)];
-}
-
-function declaredPaths(value, name, root) {
-  if (!Array.isArray(value)) {
-    throw new PcrReadContextStaleError({ root, source: CATALOG_PATH, reason: `${name} must be an array` });
-  }
-  return value.map((entry) => declaredPath(entry, name, root));
-}
-
-function declaredPath(value, name, root) {
-  if (typeof value !== "string" || value.trim() !== value || value.length === 0) {
-    throw new PcrReadContextStaleError({ root, source: CATALOG_PATH, reason: `${name} must be a canonical path` });
-  }
-  const normalized = path.posix.normalize(value);
-  if (normalized !== value || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) {
-    throw new PcrReadContextStaleError({ root, source: CATALOG_PATH, reason: `${name} escapes the repository root` });
-  }
-  return normalized;
-}
-
-function captureBindings({ root, relativePaths, beforeBoundSourceOpen = null }) {
-  return new Map(
-    relativePaths.map((relativePath) => [
-      relativePath,
-      readRepositoryFile({ root, relativePath, beforeBoundSourceOpen }).sha256,
-    ]),
-  );
-}
-
-function assertBindingSnapshotsMatch({ root, before, after }) {
-  for (const [relativePath, beforeSha256] of before) {
-    if (after.get(relativePath) !== beforeSha256) {
-      throw new PcrReadContextStaleError({
-        root,
-        source: relativePath,
-        reason: "bound source changed while aliases were validated",
-      });
-    }
-  }
-}
-
-function readRepositoryFile({ root, relativePath, beforeBoundSourceOpen = null }) {
-  const filePath = path.join(root, ...relativePath.split("/"));
-  const before = assertContainedRegularFile({ root, relativePath, filePath });
-  beforeBoundSourceOpen?.({ root, relativePath });
-  const descriptor = openSync(filePath, MANAGED_READ_FLAGS);
-  try {
-    const opened = fstatSync(descriptor);
-    if (!opened.isFile()) {
-      throw new Error(`bound source is not a regular file: ${relativePath}`);
-    }
-    const after = assertContainedRegularFile({ root, relativePath, filePath });
-    if (!sameFileIdentity(opened, before.at(-1)) || !sameFileIdentity(opened, after.at(-1)) || !samePathChain(before, after)) {
-      throw new Error(`bound source path changed while it was being opened: ${relativePath}`);
-    }
-    const bytes = readFileSync(descriptor);
-    return {
-      text: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
-      sha256: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
-    };
-  } finally {
-    closeSync(descriptor);
-  }
-}
-
-function assertContainedRegularFile({ root, relativePath, filePath }) {
-  const segments = relativePath.split("/");
-  let currentPath = root;
-  const chain = [];
-  for (const [index, segment] of segments.entries()) {
-    currentPath = path.join(currentPath, segment);
-    const stats = lstatSync(currentPath);
-    if (stats.isSymbolicLink() || (index === segments.length - 1 ? !stats.isFile() : !stats.isDirectory())) {
-      throw new Error(`bound source is not a canonical file: ${relativePath}`);
-    }
-    chain.push(stats);
-  }
-  const realFile = realpathSync(filePath);
-  if (!isInside(root, realFile)) {
-    throw new Error(`bound source escapes the repository root: ${relativePath}`);
-  }
-  return chain;
-}
-
-function isInside(root, candidate) {
-  const relative = path.relative(root, candidate);
-  return relative !== "" && !path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`);
-}
-
-function deepFreeze(value) {
-  if (!value || typeof value !== "object" || Object.isFrozen(value)) {
-    return value;
-  }
-  for (const child of Object.values(value)) {
-    deepFreeze(child);
-  }
-  return Object.freeze(value);
-}
-
-function sameStrings(left, right) {
-  return left.length === right.length && left.every((value, index) => value === right[index]);
-}
-
-function sameFileIdentity(left, right) {
-  return left.dev === right.dev && left.ino === right.ino;
-}
-
-function samePathChain(left, right) {
-  return left.length === right.length && left.every(
-    (stats, index) => sameFileIdentity(stats, right[index]),
-  );
-}
-
-function sameRecords(left, right) {
-  return left.length === right.length && left.every(
-    (entry, index) => entry.path === right[index].path && entry.state === right[index].state,
-  );
-}
-
-function compareAliases(left, right) {
-  return String(left?.source_pcr_id ?? "").localeCompare(String(right?.source_pcr_id ?? ""));
-}
-
-function stableJson(value) {
-  if (Array.isArray(value)) {
-    return `[${value.map((entry) => stableJson(entry)).join(",")}]`;
-  }
-  if (value && typeof value === "object") {
-    return `{${Object.keys(value)
-      .sort()
-      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
-      .join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-function aliasInputFingerprint({ bindings, aliasDependencyPaths, aliasSourcePathStates }) {
-  const sources = [CATALOG_PATH, ...aliasDependencyPaths]
-    .filter((value, index, values) => values.indexOf(value) === index)
-    .sort()
-    .map((relativePath) => ({ relative_path: relativePath, sha256: bindings.get(relativePath) }));
-  return `sha256:${createHash("sha256").update(JSON.stringify({
-    sources,
-    source_path_states: aliasSourcePathStates,
-  })).digest("hex")}`;
-}
-
-function readSynchronously(read) {
-  const result = read();
-  if (result && typeof result.then === "function") {
-    throw new TypeError("PCR read context sessions require a synchronous callback; use an explicit async API.");
-  }
-  return result;
-}

package/packages/pcr-core/src/schema-validation.mjs

@@ -1,142 +0,0 @@
-import Ajv2020 from "ajv/dist/2020.js";
-
-export class ContractSchemaError extends Error {
-  constructor({ code = "PCR_SCHEMA_INVALID", contract, entityKind, source = null, issues }) {
-    const location = source ? ` at ${source}` : "";
-    const details = issues.map((issue) => `${issue.instance_path}: ${issue.message}`).join("; ");
-    super(`${entityKind} schema validation failed${location}: ${details}`);
-    this.name = "ContractSchemaError";
-    this.code = code;
-    this.contract = contract;
-    this.entity_kind = entityKind;
-    this.schema_id = contract;
-    this.source = source;
-    this.issues = structuredClone(issues);
-    this.errors = structuredClone(issues);
-  }
-
-  toJSON() {
-    return {
-      code: this.code,
-      entity_kind: this.entity_kind,
-      schema_id: this.schema_id,
-      source: this.source,
-      errors: structuredClone(this.errors),
-    };
-  }
-}
-
-export function createSchemaRegistry(schemas, entityKinds = {}) {
-  const ajv = new Ajv2020({
-    allErrors: true,
-    coerceTypes: false,
-    removeAdditional: false,
-    strict: true,
-    useDefaults: false,
-    validateSchema: true,
-  });
-
-  for (const schema of schemas) {
-    if (!schema?.$id) {
-      throw new Error("Every registered JSON Schema requires a stable $id.");
-    }
-    ajv.addSchema(schema);
-  }
-
-  return {
-    assert(contract, value, options = {}) {
-      const entityKind = options.entityKind ?? entityKinds[contract] ?? contract;
-      const result = validateRegisteredSchema(ajv, contract, value, entityKind);
-      if (!result.valid) {
-        throw new ContractSchemaError({
-          code: options.code,
-          contract,
-          entityKind,
-          source: options.source,
-          issues: result.errors,
-        });
-      }
-      return value;
-    },
-    validate(contract, value, options = {}) {
-      return validateRegisteredSchema(
-        ajv,
-        contract,
-        value,
-        options.entityKind ?? entityKinds[contract] ?? contract,
-      );
-    },
-  };
-}
-
-export function formatContractIssues(issues) {
-  return issues.map((issue) => `${issue.instance_path}: ${issue.message}`);
-}
-
-export function normalizeSchemaErrors(errors) {
-  return errors
-    .map((error) => {
-      const instancePath = issuePath(error);
-      return {
-        code: `schema.${error.keyword}`,
-        instance_path: instancePath,
-        schema_path: error.schemaPath,
-        keyword: error.keyword,
-        message: error.message ?? "is invalid",
-        params: stableClone(error.params ?? {}),
-      };
-    })
-    .sort(compareSchemaErrors);
-}
-
-function validateRegisteredSchema(ajv, contract, value, entityKind) {
-  const validate = ajv.getSchema(contract);
-  if (!validate) {
-    throw new Error(`JSON Schema contract is not registered: ${contract}`);
-  }
-  const valid = validate(value);
-  const errors = valid ? [] : normalizeSchemaErrors(validate.errors ?? []);
-  return {
-    valid,
-    code: valid ? null : "PCR_SCHEMA_INVALID",
-    entity_kind: entityKind,
-    schema_id: contract,
-    errors,
-    // Backward-compatible alias for the earlier internal registry API.
-    issues: errors,
-  };
-}
-
-function compareSchemaErrors(left, right) {
-  return (
-    left.instance_path.localeCompare(right.instance_path) ||
-    left.keyword.localeCompare(right.keyword) ||
-    left.schema_path.localeCompare(right.schema_path) ||
-    left.message.localeCompare(right.message) ||
-    JSON.stringify(left.params).localeCompare(JSON.stringify(right.params))
-  );
-}
-
-function issuePath(error) {
-  if (error.keyword === "required" && error.params?.missingProperty) {
-    const escaped = String(error.params.missingProperty)
-      .replaceAll("~", "~0")
-      .replaceAll("/", "~1");
-    return `${error.instancePath}/${escaped}` || "/";
-  }
-  return error.instancePath || "/";
-}
-
-function stableClone(value) {
-  if (Array.isArray(value)) {
-    return value.map(stableClone);
-  }
-  if (!value || typeof value !== "object") {
-    return value;
-  }
-  return Object.fromEntries(
-    Object.keys(value)
-      .sort()
-      .map((key) => [key, stableClone(value[key])]),
-  );
-}

package/packages/pcr-core/src/source-context.mjs

@@ -1,13 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import path from "node:path";
-
-// Scope a storage adapter to one synchronous consumption request. No process-global
-// root cache or change to the repository reader's default authority boundary.
-const sources = new AsyncLocalStorage();
-export function withPcrSource(root, source, callback) {
-  return sources.run({ root: path.resolve(root), source }, callback);
-}
-export function pcrSource(root) {
-  const current = sources.getStore();
-  return current && path.resolve(root) === current.root ? current.source : null;
-}