@xemahq/xema 0.26.0 → 0.28.0

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);
+    }
+  }
+}