@xemahq/xema 0.59.0 → 0.60.1

package/edition/git-source-auth.mjs

@@ -1,131 +0,0 @@
-// 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

@@ -1,106 +0,0 @@
-// `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

@@ -1,242 +0,0 @@
-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);
-    }
-  }
-}