@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/git-json.mjs

@@ -0,0 +1,54 @@
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+import { parseStrictJson } from './strict-json.mjs';
+
+const requireFromHere = createRequire(import.meta.url);
+
+let loadedSourceHash;
+
+/** Git-object primitives of `@xemahq/distribution-source-hash`; no kernel is consulted. */
+function gitObjectReader() {
+  loadedSourceHash ??= requireFromHere('@xemahq/distribution-source-hash');
+  return loadedSourceHash;
+}
+
+/**
+ * Read + parse a JSON file out of an exact Git commit (never the work tree).
+ *
+ * This is the seam every authored source file crosses on its way into a lock
+ * or an index — `xema-biome.json`, a platform service's `package.json`,
+ * `cross-repo-build-inputs.json`, the committed generated biome index — so it
+ * parses STRICTLY: a duplicated object key is refused, naming the commit, the
+ * path and the JSON pointer of the object. `JSON.parse` would keep the last
+ * occurrence, which is how a `resources` declaration was dropped from a sealed
+ * lock with every reader agreeing (see `strict-json.mjs`).
+ *
+ * The commit check, the buffer ceiling and the exact-UTF-8 decode are the
+ * source-hash package's own (loaded WITHOUT the kernel check hashing needs, so
+ * the source checkout, which runs before any kernel is built, can read a record
+ * too); only the parse differs from its
+ * `readGitJsonAtCommit`, which is lenient and is therefore not delegated to.
+ */
+export function readGitJsonAtCommit(repoDir, repoRelativePath, commit) {
+  const sourceHash = gitObjectReader();
+  sourceHash.assertGitCommitExists(repoDir, commit);
+  let raw;
+  try {
+    raw = execFileSync(
+      'git',
+      ['-C', repoDir, 'show', `${commit}:${repoRelativePath}`],
+      {
+        encoding: 'buffer',
+        maxBuffer: sourceHash.GIT_OBJECT_MAX_BUFFER_BYTES,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    );
+  } catch {
+    throw new Error(
+      `cannot read "${repoRelativePath}" from Git commit "${commit}"`,
+    );
+  }
+  const context = `Git object "${commit}:${repoRelativePath}"`;
+  return parseStrictJson(sourceHash.decodeExactUtf8(raw, context), context);
+}

package/edition/git-source-auth.mjs

@@ -0,0 +1,131 @@
+// git-source-auth — the ONE place the edition library turns a read token into git
+// authentication for a repository URL, shared by every script that fetches or
+// lists a repository (first-party and customer sources alike).
+//
+// The credential reaches git through GIT_CONFIG_* environment variables, never
+// argv, a file or a clone's config, and it is scoped to the ORIGIN of the URL it
+// is for: `http.<origin>/.extraHeader` is applied by git only to URLs under that
+// origin, and redirects are not followed for a credentialed fetch. Source
+// credentials are declared only by the data root's edition-workspace.json
+// (`sourceRepositoryUrlPrefix` + `sourceAuthUsername`), the token comes from
+// SOURCE_READ_TOKEN_ENV, and `holdSource` / `withSourceGitEnv` are the hold and the
+// environment every network git call on a source passes: a definition never names
+// a credential, a URL outside the prefix is fetched with none, and git runs
+// isolated from the user's own git configuration (global and system config,
+// ~/.netrc, credential helpers, URL rewrites).
+//
+// Why this is not `gitEnvWithAuth` of the CLI's runtime (src/runtime/sources/kinds/git.ts):
+// the edition library is plain ESM that `node` runs straight from this directory
+// and that the evidence verifier bundle is built from, so it cannot import the CLI's
+// TypeScript sources or its compiled CommonJS output. The shape is the same
+// on purpose (Basic `<declared username>:<token>`, `Authorization` header, origin
+// scope; the username is a required argument, never a built-in default), so there is exactly ONE implementation per runtime.
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { canonicalPublicHttpsRepositoryUrl } from './canonical-repository-url.mjs';
+
+/** The fixed environment variable holding the source read token. */
+export const SOURCE_READ_TOKEN_ENV = 'EVIDENCE_REPOSITORIES_TOKEN';
+
+/** Whether `canonicalUrl` names a repository under the workspace's `sourceRepositoryUrlPrefix`. */
+export function isUnderSourcePrefix(canonicalUrl, prefix) {
+  return canonicalUrl.startsWith(prefix) && canonicalUrl.length > prefix.length;
+}
+
+/** A definition does not declare source credentials; the data root does. */
+export function assertSourceDeclaresNoCredential(source) {
+  for (const key of ['authTokenEnv', 'authUsername']) {
+    if (source[key] !== undefined) {
+      throw new Error(
+        `source "${source.name}" declares "${key}". A definition does not declare source credentials; ` +
+          'the data root\'s edition-workspace.json does (`sourceRepositoryUrlPrefix` + `sourceAuthUsername`, ' +
+          `token from ${SOURCE_READ_TOKEN_ENV}). Remove the key.`,
+      );
+    }
+  }
+}
+
+/** The source's url, which must already be written in its canonical public https form. */
+export function assertCanonicalSourceUrl(source) {
+  const context = `source "${source.name}" url`;
+  const canonical = canonicalPublicHttpsRepositoryUrl(source.url, context);
+  if (canonical !== source.url) {
+    throw new Error(`${context} ${JSON.stringify(source.url)} is not in its canonical form (${canonical})`);
+  }
+  return canonical;
+}
+
+const INHERITED_GIT_VARIABLES = /^(GIT_CONFIG_(COUNT|KEY_\d+|VALUE_\d+|PARAMETERS|GLOBAL|NOSYSTEM)|GIT_ASKPASS|SSH_ASKPASS|GIT_SSL_NO_VERIFY|HOME|XDG_CONFIG_HOME)$/;
+
+/**
+ * THE HOLD, pure: refuses a source that declares a credential or whose URL is not canonical, and
+ * decides whether the workspace credential covers it. A covered source needs the token in
+ * SOURCE_READ_TOKEN_ENV (unset is refused, never replaced by an ambient credential). Spawns nothing.
+ */
+export function holdSource(source, workspace, env = process.env) {
+  assertSourceDeclaresNoCredential(source);
+  const url = assertCanonicalSourceUrl(source);
+  if (!isUnderSourcePrefix(url, workspace.sourceRepositoryUrlPrefix)) {return { url, credential: null };}
+  const token = env[SOURCE_READ_TOKEN_ENV];
+  if (typeof token !== 'string' || token.length === 0) {
+    throw new Error(
+      `source "${source.name}" is under the workspace's sourceRepositoryUrlPrefix ${workspace.sourceRepositoryUrlPrefix}, ` +
+        `which needs a read token, but ${SOURCE_READ_TOKEN_ENV} is unset or empty`,
+    );
+  }
+  const username = workspace.sourceAuthUsername;
+  if (typeof username !== 'string' || username.length === 0 || username.includes(':')) {
+    throw new Error(
+      `a git username is required to authenticate git against ${url} (non-empty, no ":"); ` +
+        'it is declared, never defaulted: `sourceAuthUsername` in edition-workspace.json',
+    );
+  }
+  return { url, credential: { origin: new URL(url).origin, username, token } };
+}
+
+function isolatedGitEnv({ credential }, env, home) {
+  const base = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!INHERITED_GIT_VARIABLES.test(key)) {base[key] = value;}
+  }
+  const entries = [
+    ['credential.helper', ''],
+    ['http.extraHeader', ''],
+  ];
+  if (credential !== null) {
+    const basic = Buffer.from(`${credential.username}:${credential.token}`, 'utf8').toString('base64');
+    entries.push(['http.followRedirects', 'false'], [`http.${credential.origin}/.extraHeader`, `Authorization: Basic ${basic}`]);
+  }
+  const config = { GIT_CONFIG_COUNT: String(entries.length) };
+  entries.forEach(([key, value], index) => {
+    config[`GIT_CONFIG_KEY_${index}`] = key;
+    config[`GIT_CONFIG_VALUE_${index}`] = value;
+  });
+  return {
+    ...base,
+    ...config,
+    GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_CONFIG_NOSYSTEM: '1',
+    HOME: home,
+    XDG_CONFIG_HOME: home,
+    GIT_TERMINAL_PROMPT: '0',
+  };
+}
+
+/**
+ * Run `fn(gitEnv)` with the git environment for one declared source; the hold comes first, before
+ * anything is created or spawned. The environment points HOME at an empty directory that exists
+ * only for the duration of `fn`.
+ */
+export function withSourceGitEnv(source, { workspace, env = process.env }, fn) {
+  const decision = holdSource(source, workspace, env);
+  const home = mkdtempSync(join(tmpdir(), 'xema-git-home-'));
+  try {
+    return fn(isolatedGitEnv(decision, env, home));
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+}

package/edition/image-delivery-entitlement-descriptor.mjs

@@ -0,0 +1,106 @@
+// `entitlement.json`: the file `xema-edition evidence statement entitlement
+// accept` writes beside the signed statement, and the ONE reader of it
+// (`verify-evidence --entitlement`). Writer and reader share this module so the
+// shape is stated once.
+//
+// Every field but `evidence` is an UNAUTHENTICATED convenience for the operator
+// and for `verify-evidence`'s early refusals: the signed statement stays the
+// authority (`validateEntitlementStatementBinding`). The file names no workflow
+// SHA: the commit the entitlement's certificate is held to is stated by the
+// caller of the verifier (`--entitlement-workflow-sha`), never by the evidence.
+
+import { dirname, join } from 'node:path';
+
+export const ENTITLEMENT_DESCRIPTOR_FILE = 'entitlement.json';
+export const ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION = 2;
+
+const ENTITLEMENT_DESCRIPTOR_KEYS = Object.freeze([
+  'schemaVersion',
+  'distributionId',
+  'customerId',
+  'mode',
+  'targetRegistry',
+  'idempotencyKey',
+  'distributionStatementDigest',
+  'evidence',
+]);
+
+/** The document `accept` writes. `evidence` is the kernel Sigstore evidence descriptor of the signed statement. */
+export function entitlementDescriptorDocument({
+  distributionId,
+  customerId,
+  mode,
+  targetRegistry,
+  idempotencyKey,
+  distributionStatementDigest,
+  evidence,
+}) {
+  return {
+    schemaVersion: ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION,
+    distributionId,
+    customerId,
+    mode,
+    targetRegistry,
+    idempotencyKey,
+    distributionStatementDigest,
+    evidence,
+  };
+}
+
+/**
+ * Parse an `entitlement.json`: exactly the keys `accept` writes, at the one
+ * schema version, with `evidence` parsed by the kernel's Sigstore evidence
+ * descriptor schema. Any other shape is refused.
+ */
+export function parseEntitlementDescriptorDocument(raw, schemas) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${ENTITLEMENT_DESCRIPTOR_FILE} must be a JSON object`);
+  }
+  if (raw.schemaVersion !== ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION) {
+    throw new Error(
+      `${ENTITLEMENT_DESCRIPTOR_FILE} has schemaVersion ${JSON.stringify(raw.schemaVersion)}; ` +
+        `this verifier reads schemaVersion ${ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION} only (accept the entitlement again with this CLI)`,
+    );
+  }
+  const keys = Object.keys(raw).sort();
+  const expected = [...ENTITLEMENT_DESCRIPTOR_KEYS].sort();
+  if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+    throw new Error(
+      `${ENTITLEMENT_DESCRIPTOR_FILE} must hold exactly the keys ${ENTITLEMENT_DESCRIPTOR_KEYS.join(', ')}; it holds ${keys.join(', ')}`,
+    );
+  }
+  for (const key of ['distributionId', 'customerId', 'mode', 'idempotencyKey', 'distributionStatementDigest']) {
+    if (typeof raw[key] !== 'string' || raw[key] === '') {
+      throw new Error(`${ENTITLEMENT_DESCRIPTOR_FILE} "${key}" must be a non-empty string`);
+    }
+  }
+  if (raw.targetRegistry !== null && (typeof raw.targetRegistry !== 'string' || raw.targetRegistry === '')) {
+    throw new Error(`${ENTITLEMENT_DESCRIPTOR_FILE} "targetRegistry" must be null or a non-empty string`);
+  }
+  return { ...raw, evidence: schemas.SigstoreEvidenceDescriptorSchema.parse(raw.evidence) };
+}
+
+/**
+ * Refuse an `entitlement.json` that states another request than the one being
+ * verified. `expected` holds the caller's flags and the completeness statement
+ * digest the verifier has just verified.
+ */
+export function assertEntitlementDescriptorStates(document, expected) {
+  for (const key of ['distributionId', 'customerId', 'mode', 'targetRegistry', 'distributionStatementDigest']) {
+    if (document[key] !== expected[key]) {
+      throw new Error(
+        `${ENTITLEMENT_DESCRIPTOR_FILE} states ${key} ${JSON.stringify(document[key])}, ` +
+          `not the ${JSON.stringify(expected[key])} this verification was asked for`,
+      );
+    }
+  }
+}
+
+/**
+ * The evidence descriptor's paths are relative to the directory `accept` sealed
+ * (the one holding `entitlement.json`), which lies inside the evidence root the
+ * descriptor file itself was read from.
+ */
+export function entitlementEvidenceRoot(evidenceRoot, entitlementDescriptorPath) {
+  return dirname(join(evidenceRoot, entitlementDescriptorPath));
+}

package/edition/image-evidence-replay-state.mjs

@@ -0,0 +1,242 @@
+import { randomUUID } from 'node:crypto';
+import {
+  closeSync,
+  constants as fsConstants,
+  fstatSync,
+  fsyncSync,
+  openSync,
+  readSync,
+  realpathSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+
+import {
+  canonicalJsonBytes,
+  parseCanonicalJsonBytes,
+} from './image-evidence.mjs';
+
+const MAX_REPLAY_STATE_BYTES = 64 * 1024;
+
+function openRegularFileNoFollow(path) {
+  const descriptor = openSync(
+    path,
+    fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW,
+  );
+  const metadata = fstatSync(descriptor);
+  if (!metadata.isFile()) {
+    closeSync(descriptor);
+    throw new Error(`replay state "${path}" is not a regular file`);
+  }
+  if ((metadata.mode & 0o777) !== 0o600) {
+    closeSync(descriptor);
+    throw new Error(`replay state "${path}" must have exact mode 0600`);
+  }
+  if (
+    typeof process.getuid === 'function' &&
+    metadata.uid !== process.getuid()
+  ) {
+    closeSync(descriptor);
+    throw new Error(`replay state "${path}" must be owned by the verifier`);
+  }
+  return descriptor;
+}
+
+function assertTrustedStateDirectory(path) {
+  const descriptor = openSync(
+    path,
+    fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW,
+  );
+  try {
+    const metadata = fstatSync(descriptor);
+    if (!metadata.isDirectory()) {
+      throw new Error(`replay state parent "${path}" is not a directory`);
+    }
+    if ((metadata.mode & 0o777) !== 0o700) {
+      throw new Error(
+        `replay state parent "${path}" must have exact mode 0700`,
+      );
+    }
+    if (
+      typeof process.getuid === 'function' &&
+      metadata.uid !== process.getuid()
+    ) {
+      throw new Error(
+        `replay state parent "${path}" must be owned by the verifier`,
+      );
+    }
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function writeDurableReplacement(path, value) {
+  const directory = realpathSync(dirname(path));
+  const temporaryPath = join(
+    directory,
+    `.${basename(path)}.${randomUUID()}.tmp`,
+  );
+  let descriptor;
+  try {
+    descriptor = openSync(
+      temporaryPath,
+      fsConstants.O_CREAT |
+        fsConstants.O_EXCL |
+        fsConstants.O_WRONLY |
+        fsConstants.O_NOFOLLOW,
+      0o600,
+    );
+    writeFileSync(descriptor, canonicalJsonBytes(value));
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = undefined;
+    renameSync(temporaryPath, path);
+    const directoryDescriptor = openSync(directory, fsConstants.O_RDONLY);
+    try {
+      fsyncSync(directoryDescriptor);
+    } finally {
+      closeSync(directoryDescriptor);
+    }
+  } finally {
+    if (descriptor !== undefined) {closeSync(descriptor);}
+    removeIfPresent(temporaryPath);
+  }
+}
+
+/** Remove `path`; only its absence is tolerated. */
+function removeIfPresent(path) {
+  try {
+    unlinkSync(path);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {throw error;}
+  }
+}
+
+export async function verifyAndAdvanceReplayState({
+  statePath,
+  distributionId,
+  trustPolicyDigest,
+  parseReplayState,
+  verify,
+}) {
+  if (!isAbsolute(statePath)) {
+    throw new Error('replay state path must be absolute');
+  }
+  const stateDirectory = realpathSync(dirname(statePath));
+  if (stateDirectory !== dirname(statePath)) {
+    throw new Error('replay state parent path must be canonical');
+  }
+  assertTrustedStateDirectory(stateDirectory);
+  const canonicalStatePath = join(stateDirectory, basename(statePath));
+  const lockPath = `${canonicalStatePath}.lock`;
+  let lockDescriptor;
+  try {
+    lockDescriptor = openSync(
+      lockPath,
+      fsConstants.O_CREAT |
+        fsConstants.O_EXCL |
+        fsConstants.O_WRONLY |
+        fsConstants.O_NOFOLLOW,
+      0o600,
+    );
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      throw new Error(
+        `replay state "${canonicalStatePath}" is locked by another verifier; explicit operator reconciliation is required for a stale lock`,
+      );
+    }
+    throw error;
+  }
+
+  try {
+    writeFileSync(
+      lockDescriptor,
+      `${process.pid} ${new Date().toISOString()}\n`,
+    );
+    fsyncSync(lockDescriptor);
+    const stateDescriptor = openRegularFileNoFollow(canonicalStatePath);
+    let state;
+    try {
+      const before = fstatSync(stateDescriptor);
+      if (before.size > MAX_REPLAY_STATE_BYTES) {
+        throw new Error(`replay state exceeds ${MAX_REPLAY_STATE_BYTES} bytes`);
+      }
+      const stateBytes = Buffer.alloc(before.size);
+      let offset = 0;
+      while (offset < stateBytes.length) {
+        const count = readSync(
+          stateDescriptor,
+          stateBytes,
+          offset,
+          stateBytes.length - offset,
+          offset,
+        );
+        if (count === 0) {
+          throw new Error('replay state was truncated while reading');
+        }
+        offset += count;
+      }
+      if (readSync(stateDescriptor, Buffer.alloc(1), 0, 1, offset) !== 0) {
+        throw new Error('replay state grew while reading');
+      }
+      const after = fstatSync(stateDescriptor);
+      for (const field of ['dev', 'ino', 'size', 'mtimeMs', 'ctimeMs']) {
+        if (after[field] !== before[field]) {
+          throw new Error('replay state changed while reading');
+        }
+      }
+      state = parseReplayState(
+        parseCanonicalJsonBytes(stateBytes, 'distribution image replay state'),
+      );
+    } finally {
+      closeSync(stateDescriptor);
+    }
+    if (
+      state.distributionId !== distributionId ||
+      state.trustPolicyDigest !== trustPolicyDigest
+    ) {
+      throw new Error(
+        'replay state does not match the selected distribution and committed trust policy',
+      );
+    }
+
+    const verified = await verify(state);
+    const completeness = verified.completenessStatement.predicate;
+    if (completeness.releaseSequence <= state.lastReleaseSequence) {
+      throw new Error(
+        'verified completeness evidence does not advance releaseSequence',
+      );
+    }
+    if (completeness.nonce === state.lastCompletenessNonce) {
+      throw new Error(
+        'verified completeness evidence reuses the last accepted nonce',
+      );
+    }
+    if (
+      verified.completenessStatementDigest ===
+      state.lastCompletenessStatementDigest
+    ) {
+      throw new Error(
+        'verified completeness evidence reuses the last accepted statement',
+      );
+    }
+    const nextState = parseReplayState({
+      schemaVersion: 1,
+      distributionId,
+      trustPolicyDigest,
+      lastReleaseSequence: completeness.releaseSequence,
+      lastCompletenessStatementDigest: verified.completenessStatementDigest,
+      lastCompletenessNonce: completeness.nonce,
+    });
+    writeDurableReplacement(canonicalStatePath, nextState);
+    return { verified, replayState: nextState };
+  } finally {
+    try {
+      closeSync(lockDescriptor);
+    } finally {
+      unlinkSync(lockPath);
+    }
+  }
+}