@xemahq/xema 0.26.0 → 0.28.0

package/edition/sealed-evidence-accept.mjs

@@ -0,0 +1,82 @@
+// How every evidence accept seals its output: the output is BUILT from what
+// the accept re-derives, never renamed from the staging, and the staging does
+// not outlive the accept.
+//
+//   * the staging must hold EXACTLY the files stage recorded (and the signer
+//     was asked for) - nothing else, no link, no stray directory;
+//   * the output is built in a private sibling, verified where it is sealed,
+//     and moved into place by one rename;
+//   * a refused accept removes the sibling AND the staging, so no
+//     signed-but-unaccepted bundle is left for a later step to pick up; a
+//     successful accept removes the staging too. Only the argument refusals
+//     before the first read (`reserveSealing`) leave it in place.
+
+import { existsSync, lstatSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { compareStrings } from './lib.mjs';
+
+/** Every file below `root`, relative and sorted; a link or any other non-file entry is refused. */
+export function listFilesBelow(root, prefix = '') {
+  const files = [];
+  for (const name of readdirSync(join(root, prefix))) {
+    const relative = `${prefix}${name}`;
+    const stat = lstatSync(join(root, relative));
+    if (stat.isDirectory()) {
+      files.push(...listFilesBelow(root, `${relative}/`));
+    } else if (stat.isFile()) {
+      files.push(relative);
+    } else {
+      throw new Error(`staging entry ${join(root, relative)} is not a regular file or directory`);
+    }
+  }
+  return files.sort(compareStrings);
+}
+
+/** The staging holds EXACTLY the recorded files: nothing missing, nothing extra. */
+export function assertStagedExactly(stagingDirectory, recordedFiles) {
+  const expected = [...recordedFiles].sort(compareStrings);
+  const actual = listFilesBelow(stagingDirectory);
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(
+      `staging directory ${stagingDirectory} does not hold exactly what stage recorded: ` +
+        `expected=${expected.join(',')} actual=${actual.join(',')}`,
+    );
+  }
+}
+
+/** The private sibling an accept builds its output in; refuses an existing output or an accept already running here. */
+export function reserveSealing(outputDirectory, label) {
+  if (existsSync(outputDirectory)) {
+    throw new Error(`${label} output already exists: ${outputDirectory}`);
+  }
+  const sealing = `${outputDirectory}.accepting-${process.pid}`;
+  if (existsSync(sealing)) {
+    throw new Error(`${label} output is already being accepted: ${sealing}`);
+  }
+  return sealing;
+}
+
+/**
+ * Run `build(sealing)` (which fills the sibling), then move it to
+ * `outputDirectory`. The staging is removed whether the accept is refused or
+ * succeeds; a refused accept also removes the sibling.
+ */
+export function sealAccepted({ stagingDirectory, sealing, outputDirectory, build }) {
+  let result;
+  try {
+    result = build(sealing);
+    renameSync(sealing, outputDirectory);
+  } catch (error) {
+    rmSync(sealing, { recursive: true, force: true });
+    discardStaging(stagingDirectory);
+    throw error;
+  }
+  discardStaging(stagingDirectory);
+  return result;
+}
+
+/** Remove a staging directory (and nothing above it). */
+export function discardStaging(stagingDirectory) {
+  rmSync(stagingDirectory, { recursive: true, force: true });
+}