@kungfu-tech/buildchain 3.0.2 → 3.0.3-alpha.1

package/scripts/observed-evidence.mjs

@@ -24,6 +24,40 @@ function assertHex(value, label) {
   if (!/^[0-9a-f]{64}$/.test(String(value || ""))) throw new Error(`${label} must be a lowercase sha256 hex digest`);
 }
 
+function requiredHeader(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized || /[\r\n]/.test(normalized)) throw new Error(`${label} must be a non-empty single-line value`);
+  return normalized;
+}
+
+function validatePublicationEntry({ entry, kind, root, snapshotId, requireSnapshotDocument = false, requireHeaders = false }) {
+  const source = safeRelative(entry.source, `${kind}.source`);
+  const key = safeRelative(entry.key, `${kind}.key`);
+  const file = path.resolve(root, source);
+  if (file !== root && !file.startsWith(`${root}${path.sep}`)) throw new Error(`${kind}.source escapes artifact root`);
+  if (!fs.statSync(file).isFile()) throw new Error(`${kind}.source is not a file: ${source}`);
+  assertHex(entry.sha256, `${kind}.sha256`);
+  const actual = sha256(file);
+  if (actual !== entry.sha256) throw new Error(`${kind}.sha256 does not match ${source}`);
+  if (requireSnapshotDocument) {
+    const document = readJson(file);
+    if (document.snapshotId !== snapshotId) throw new Error(`${kind} document snapshotId does not match manifest`);
+  }
+  return {
+    kind,
+    source,
+    key,
+    file,
+    sha256: actual,
+    contentType: requireHeaders
+      ? requiredHeader(entry.contentType, `${kind}.contentType`)
+      : String(entry.contentType || "application/json"),
+    cacheControl: requireHeaders
+      ? requiredHeader(entry.cacheControl, `${kind}.cacheControl`)
+      : String(entry.cacheControl || ""),
+  };
+}
+
 export function validateObservedEvidenceBundle({ manifestPath, artifactRoot = path.dirname(manifestPath) }) {
   const resolvedManifest = path.resolve(manifestPath);
   const root = path.resolve(artifactRoot);
@@ -36,26 +70,39 @@ export function validateObservedEvidenceBundle({ manifestPath, artifactRoot = pa
   if (!Number.isFinite(Date.parse(manifest.snapshot?.observedAt || ""))) throw new Error("snapshot.observedAt must be ISO-8601");
   const immutable = manifest.publication?.immutable || {};
   const latest = manifest.publication?.latest || {};
-  const entries = [["immutable", immutable], ["latest", latest]].map(([kind, entry]) => {
-    const source = safeRelative(entry.source, `${kind}.source`);
-    const key = safeRelative(entry.key, `${kind}.key`);
-    const file = path.resolve(root, source);
-    if (file !== root && !file.startsWith(`${root}${path.sep}`)) throw new Error(`${kind}.source escapes artifact root`);
-    if (!fs.statSync(file).isFile()) throw new Error(`${kind}.source is not a file: ${source}`);
-    assertHex(entry.sha256, `${kind}.sha256`);
-    const actual = sha256(file);
-    if (actual !== entry.sha256) throw new Error(`${kind}.sha256 does not match ${source}`);
-    const document = readJson(file);
-    if (document.snapshotId !== snapshotId) throw new Error(`${kind} document snapshotId does not match manifest`);
-    return { kind, source, key, file, sha256: actual, contentType: entry.contentType || "application/json" };
-  });
-  if (!entries[0].key.includes(`/${snapshotId}.json`)) throw new Error("immutable key must bind snapshot.id below a versioned path");
-  if (entries[0].key === entries[1].key) throw new Error("immutable and latest keys must differ");
+  const immutableEntry = validatePublicationEntry({ entry: immutable, kind: "immutable", root, snapshotId, requireSnapshotDocument: true });
+  const latestEntry = validatePublicationEntry({ entry: latest, kind: "latest", root, snapshotId, requireSnapshotDocument: true });
+  const projectionInput = manifest.publication?.projections ?? [];
+  if (!Array.isArray(projectionInput) || projectionInput.length > 16) {
+    throw new Error("publication.projections must be an array with at most 16 entries");
+  }
+  const projections = projectionInput.map((entry, index) => validatePublicationEntry({
+    entry,
+    kind: `projection[${index}]`,
+    root,
+    snapshotId,
+    requireHeaders: true,
+  }));
+  const entries = [immutableEntry, ...projections, latestEntry];
+  if (!immutableEntry.key.includes(`/${snapshotId}.json`)) throw new Error("immutable key must bind snapshot.id below a versioned path");
+  if (new Set(entries.map((entry) => entry.key)).size !== entries.length) {
+    throw new Error("immutable, projection, and latest keys must be unique");
+  }
   const invalidationPaths = [...new Set(manifest.publication?.invalidationPaths || [])];
   if (invalidationPaths.some((entry) => typeof entry !== "string" || !entry.startsWith("/") || entry.includes(".."))) {
     throw new Error("invalidation paths must be absolute viewer paths without traversal");
   }
-  return { manifest, manifestPath: resolvedManifest, artifactRoot: root, snapshotId, entries, invalidationPaths };
+  return {
+    manifest,
+    manifestPath: resolvedManifest,
+    artifactRoot: root,
+    snapshotId,
+    entries,
+    immutable: immutableEntry,
+    latest: latestEntry,
+    projections,
+    invalidationPaths,
+  };
 }
 
 function defaultRunner(args) {
@@ -79,6 +126,8 @@ function headEvidence(result) {
     snapshotId: String(value.Metadata?.["snapshot-id"] || ""),
     etag: String(value.ETag || "").replaceAll('"', ""),
     versionId: String(value.VersionId || ""),
+    contentType: String(value.ContentType || ""),
+    cacheControl: String(value.CacheControl || ""),
   };
 }
 
@@ -90,7 +139,7 @@ function putArgs({ bucket, entry, snapshotId, immutable }) {
   const args = [
     "s3api", "put-object", "--bucket", bucket, "--key", entry.key, "--body", entry.file,
     "--content-type", entry.contentType,
-    "--cache-control", immutable ? "public,max-age=31536000,immutable" : "public,max-age=0,must-revalidate",
+    "--cache-control", entry.cacheControl || (immutable ? "public,max-age=31536000,immutable" : "public,max-age=0,must-revalidate"),
     "--checksum-sha256", base64Digest(entry.sha256),
     "--metadata", `snapshot-id=${snapshotId},sha256=${entry.sha256}`,
   ];
@@ -98,10 +147,39 @@ function putArgs({ bucket, entry, snapshotId, immutable }) {
   return args;
 }
 
+function copySource(bucket, key, versionId) {
+  const encoded = `${encodeURIComponent(bucket)}/${key.split("/").map(encodeURIComponent).join("/")}`;
+  return `${encoded}?versionId=${encodeURIComponent(versionId)}`;
+}
+
+function rollbackMutableEntries({ commandRunner, bucket, applied }) {
+  const operations = [];
+  for (const { entry, previous } of [...applied].reverse()) {
+    const result = previous
+      ? commandRunner([
+          "s3api", "copy-object", "--bucket", bucket, "--key", entry.key,
+          "--copy-source", copySource(bucket, entry.key, previous.versionId),
+          "--metadata-directive", "COPY",
+        ])
+      : commandRunner(["s3api", "delete-object", "--bucket", bucket, "--key", entry.key]);
+    operations.push({ action: previous ? "restore-previous-version" : "remove-new-projection", key: entry.key, status: result.status });
+    if (result.status !== 0) {
+      throw new Error(`rollback failed for ${entry.key}: ${result.stderr || result.stdout}`);
+    }
+  }
+  return operations;
+}
+
 function assertHeadMatches(head, entry, snapshotId, label) {
   if (!head || head.sha256 !== entry.sha256 || head.snapshotId !== snapshotId) {
     throw new Error(`${label} object does not match the admitted snapshot and sha256`);
   }
+  if (
+    entry.kind.startsWith("projection[") &&
+    (head.contentType !== entry.contentType || head.cacheControl !== entry.cacheControl)
+  ) {
+    throw new Error(`${label} object does not match the admitted content type and cache control`);
+  }
 }
 
 export function publishObservedEvidence(options, { commandRunner = defaultRunner } = {}) {
@@ -110,7 +188,7 @@ export function publishObservedEvidence(options, { commandRunner = defaultRunner
   if (!bucket) throw new Error("bucket is required");
   const distributionId = String(options.distributionId || "").trim();
   const dryRun = options.dryRun !== false;
-  const [immutable, latest] = bundle.entries;
+  const { immutable, latest, projections } = bundle;
   const receipt = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-observed-evidence-publication-receipt",
@@ -121,8 +199,17 @@ export function publishObservedEvidence(options, { commandRunner = defaultRunner
     bucket,
     distributionId,
     immutable: { key: immutable.key, sha256: immutable.sha256, status: "planned" },
+    projections: projections.map((entry) => ({
+      key: entry.key,
+      sha256: entry.sha256,
+      contentType: entry.contentType,
+      cacheControl: entry.cacheControl,
+      status: "planned",
+    })),
     latest: { key: latest.key, sha256: latest.sha256, status: "planned" },
+    previousProjections: [],
     previousLatest: null,
+    rollback: { status: "not-needed", operations: [] },
     invalidationPaths: bundle.invalidationPaths,
     operations: [],
   };
@@ -147,21 +234,52 @@ export function publishObservedEvidence(options, { commandRunner = defaultRunner
   assertHeadMatches(verifiedImmutable, immutable, bundle.snapshotId, "verified immutable");
   receipt.immutable.verification = verifiedImmutable;
 
-  receipt.previousLatest = headEvidence(headObject(commandRunner, bucket, latest.key));
-  const latestPut = commandRunner(putArgs({ bucket, entry: latest, snapshotId: bundle.snapshotId, immutable: false }));
-  receipt.operations.push({ action: "advance-latest", status: latestPut.status });
-  if (latestPut.status !== 0) throw new Error(`latest alias update failed: ${latestPut.stderr || latestPut.stdout}`);
-  const verifiedLatest = headEvidence(headObject(commandRunner, bucket, latest.key));
-  assertHeadMatches(verifiedLatest, latest, bundle.snapshotId, "verified latest");
-  receipt.latest = { ...receipt.latest, status: "written", verification: verifiedLatest };
-
-  if (distributionId && bundle.invalidationPaths.length > 0) {
-    const invalidation = commandRunner([
-      "cloudfront", "create-invalidation", "--distribution-id", distributionId,
-      "--paths", ...bundle.invalidationPaths,
-    ]);
-    receipt.operations.push({ action: "invalidate-cdn", status: invalidation.status, result: jsonOutput(invalidation) });
-    if (invalidation.status !== 0) throw new Error(`CloudFront invalidation failed: ${invalidation.stderr || invalidation.stdout}`);
+  const mutableEntries = [...projections, latest];
+  const previousByKey = new Map(mutableEntries.map((entry) => [entry.key, headEvidence(headObject(commandRunner, bucket, entry.key))]));
+  if (projections.length > 0) {
+    for (const [key, previous] of previousByKey) {
+      if (previous && !previous.versionId) {
+        throw new Error(`mutable projection transaction requires bucket versioning before replacing ${key}`);
+      }
+    }
+  }
+  receipt.previousProjections = projections.map((entry) => ({ key: entry.key, previous: previousByKey.get(entry.key) }));
+  receipt.previousLatest = previousByKey.get(latest.key);
+  const applied = [];
+  try {
+    for (const [index, projection] of projections.entries()) {
+      const put = commandRunner(putArgs({ bucket, entry: projection, snapshotId: bundle.snapshotId, immutable: false }));
+      receipt.operations.push({ action: "advance-projection", key: projection.key, status: put.status });
+      if (put.status !== 0) throw new Error(`projection update failed for ${projection.key}: ${put.stderr || put.stdout}`);
+      applied.push({ entry: projection, previous: previousByKey.get(projection.key) });
+      const verified = headEvidence(headObject(commandRunner, bucket, projection.key));
+      assertHeadMatches(verified, projection, bundle.snapshotId, `verified projection ${projection.key}`);
+      receipt.projections[index] = { ...receipt.projections[index], status: "written", verification: verified };
+    }
+
+    const latestPut = commandRunner(putArgs({ bucket, entry: latest, snapshotId: bundle.snapshotId, immutable: false }));
+    receipt.operations.push({ action: "advance-latest", status: latestPut.status });
+    if (latestPut.status !== 0) throw new Error(`latest alias update failed: ${latestPut.stderr || latestPut.stdout}`);
+    applied.push({ entry: latest, previous: previousByKey.get(latest.key) });
+    const verifiedLatest = headEvidence(headObject(commandRunner, bucket, latest.key));
+    assertHeadMatches(verifiedLatest, latest, bundle.snapshotId, "verified latest");
+    receipt.latest = { ...receipt.latest, status: "written", verification: verifiedLatest };
+
+    if (distributionId && bundle.invalidationPaths.length > 0) {
+      const invalidation = commandRunner([
+        "cloudfront", "create-invalidation", "--distribution-id", distributionId,
+        "--paths", ...bundle.invalidationPaths,
+      ]);
+      receipt.operations.push({ action: "invalidate-cdn", status: invalidation.status, result: jsonOutput(invalidation) });
+      if (invalidation.status !== 0) throw new Error(`CloudFront invalidation failed: ${invalidation.stderr || invalidation.stdout}`);
+    }
+  } catch (error) {
+    if (projections.length > 0 && applied.length > 0) {
+      receipt.rollback.status = "applying";
+      receipt.rollback.operations = rollbackMutableEntries({ commandRunner, bucket, applied });
+      receipt.rollback.status = "restored";
+    }
+    throw error;
   }
   receipt.status = "published";
   receipt.publishedAt = new Date().toISOString();