@open-agent-toolkit/cli 0.2.30 → 0.2.31

package/assets/skills/explainer-kit/scripts/lib/s3-static.mjs

@@ -15,10 +15,25 @@ import { promisify } from 'node:util';
 import {
   catalogFromManifest,
   initiativeCatalogPath,
+  resolvePublicVerificationPolicy,
   serializeInitiativeCatalog,
   validateInitiativeCatalog,
 } from './catalog.mjs';
 import { validateContract } from './contracts.mjs';
+import { assertManifestPublishable } from './publication-policy.mjs';
+import {
+  composePublicationTarget,
+  describeRootDivergence,
+  isPrivatePublicHost,
+  normalizePublishRoots,
+  privatePublicRootAllowed,
+  rootDivergenceWarningSuppressed,
+} from './s3-roots.mjs';
+
+export {
+  composePublicationTarget,
+  normalizePublishRoots,
+} from './s3-roots.mjs';
 
 const execFile = promisify(execFileCallback);
 const SENTINEL_BODY = 'explainer-kit sentinel\n';
@@ -28,54 +43,6 @@ const AUTH_PATTERN =
   /(?:credential|expired|sso session|access key|invalidclienttokenid|unrecognizedclient|token)/i;
 const NOT_FOUND_PATTERN = /(?:\b404\b|not found|nosuchkey)/i;
 
-export function normalizePublishRoots(s3Uri, publicBaseUrl) {
-  if (typeof s3Uri !== 'string' || !s3Uri.startsWith('s3://')) {
-    throw publishError('E_PUBLISH_ROOTS', 'S3 root must use s3://.');
-  }
-  const withoutScheme = s3Uri.slice('s3://'.length).replace(/\/+$/, '');
-  const slash = withoutScheme.indexOf('/');
-  const bucket = slash === -1 ? withoutScheme : withoutScheme.slice(0, slash);
-  const keyPrefix =
-    slash === -1
-      ? ''
-      : withoutScheme
-          .slice(slash + 1)
-          .split('/')
-          .filter(Boolean)
-          .join('/');
-  if (!bucket || /\s/.test(bucket)) {
-    throw publishError('E_PUBLISH_ROOTS', 'S3 root has an invalid bucket.');
-  }
-
-  let publicUrl;
-  try {
-    publicUrl = new URL(publicBaseUrl);
-  } catch {
-    throw publishError('E_PUBLISH_ROOTS', 'Public root must be a valid URL.');
-  }
-  if (
-    publicUrl.protocol !== 'https:' ||
-    publicUrl.username ||
-    publicUrl.password ||
-    publicUrl.search ||
-    publicUrl.hash
-  ) {
-    throw publishError(
-      'E_PUBLISH_ROOTS',
-      'Public root must be credential-free HTTPS without query or fragment.',
-    );
-  }
-  publicUrl.pathname = publicUrl.pathname.replace(/\/+$/, '');
-  const normalizedPublic = publicUrl.toString().replace(/\/$/, '');
-  const normalizedS3 = `s3://${bucket}${keyPrefix ? `/${keyPrefix}` : ''}`;
-  return {
-    bucket,
-    keyPrefix,
-    s3Uri: normalizedS3,
-    publicBaseUrl: normalizedPublic,
-  };
-}
-
 export function createSentinelRelativePath(
   runId,
   randomBytes = nodeRandomBytes,
@@ -115,6 +82,14 @@ export async function publishS3Static(request, dependencies = {}) {
   const siteRoot = resolve(cwd, request.siteRoot);
   const manifestPath = resolve(cwd, request.manifestPath);
   const manifest = await readJson(manifestPath, 'manifest');
+  const buildRecord =
+    manifest.outcome === 'incomplete'
+      ? await readJson(
+          resolve(dirname(manifestPath), manifest.buildRecord?.path ?? ''),
+          'build record',
+        )
+      : undefined;
+  assertManifestPublishable(manifest, { buildRecord });
   const manifestValidation = validateContract('manifest', manifest);
   if (!manifestValidation.valid) {
     throw publishError(
@@ -136,12 +111,33 @@ export async function publishS3Static(request, dependencies = {}) {
     manifest.runId,
     randomBytes,
   );
-  const sentinelTargetPath = targetPath(sentinelRelativePath, roots);
-  const catalog = catalogFromManifest(manifest, roots.publicBaseUrl);
+  const sentinelTargetPath = composePublicationTarget(
+    sentinelRelativePath,
+    roots,
+  );
+  // Resolved before the catalog is built: the catalog is hashed and uploaded
+  // before any public verification runs, so it must carry the policy up front.
+  const publicAccess =
+    request.schemaVersion === 'explainer-kit.publish-request/v1'
+      ? 'public'
+      : request.publicAccess;
+  const verificationPolicy = resolvePublicVerificationPolicy(publicAccess);
+
+  const divergence = describeRootDivergence(roots);
+  if (divergence && !rootDivergenceWarningSuppressed()) {
+    (dependencies.warn ?? ((message) => console.warn(message)))(
+      `explainer-kit: ${divergence}`,
+    );
+  }
+
+  const catalog = catalogFromManifest(manifest, roots.publicBaseUrl, {
+    publicAccess,
+  });
   const catalogValidation = validateInitiativeCatalog(
     catalog,
     manifest,
     roots.publicBaseUrl,
+    { publicAccess },
   );
   if (!catalogValidation.valid) {
     throw publishError(
@@ -164,6 +160,7 @@ export async function publishS3Static(request, dependencies = {}) {
   const sentinelBodyPath = join(sentinelDirectory, 'sentinel.txt');
   const catalogBodyPath = join(sentinelDirectory, 'catalog.json');
   const catalogArtifact = {
+    source: { kind: 'auxiliary', name: 'catalog' },
     manifestPath: catalogManifestPath,
     publishPath: catalogPublishPath,
     filePath: catalogBodyPath,
@@ -192,21 +189,41 @@ export async function publishS3Static(request, dependencies = {}) {
       { sleep },
     );
     sentinelUploaded = true;
-    await runAws(
+    const sentinelMetadata = await readObjectMetadata(
       command,
       headObjectArgs(roots, sentinelRelativePath, awsOptions),
       { sleep },
     );
-    const sentinelResponse = await httpGet(sentinelTargetPath.publicUrl);
-    if (
-      sentinelResponse.status < 200 ||
-      sentinelResponse.status > 299 ||
-      !responseBytes(sentinelResponse.body).equals(Buffer.from(SENTINEL_BODY))
-    ) {
-      throw publishError(
-        'E_PUBLISH_ROOTS',
-        'Public root did not serve the uploaded sentinel.',
-      );
+    const sentinelObjectVerification = await verifyObjectBytes({
+      command,
+      metadata: sentinelMetadata,
+      roots,
+      relativePath: sentinelRelativePath,
+      expectedHash: fileHash(Buffer.from(SENTINEL_BODY)),
+      downloadPath: join(sentinelDirectory, 'sentinel-download.txt'),
+      awsOptions,
+      sleep,
+    });
+    let sentinelPublicVerification = {
+      status: verificationPolicy.receiptSkipStatus,
+    };
+    if (verificationPolicy.verifyPublicly) {
+      const sentinelResponse = await httpGet(sentinelTargetPath.publicUrl);
+      if (
+        sentinelResponse.status < 200 ||
+        sentinelResponse.status > 299 ||
+        !responseBytes(sentinelResponse.body).equals(Buffer.from(SENTINEL_BODY))
+      ) {
+        throw publishError(
+          'E_PUBLISH_ROOTS',
+          'Public root did not serve the uploaded sentinel.',
+        );
+      }
+      sentinelPublicVerification = {
+        status: 'verified',
+        httpStatus: sentinelResponse.status,
+        hash: fileHash(responseBytes(sentinelResponse.body)),
+      };
     }
     await runAws(
       command,
@@ -217,7 +234,7 @@ export async function publishS3Static(request, dependencies = {}) {
 
     const receiptArtifacts = [];
     for (const artifact of publicationArtifacts) {
-      const target = targetPath(artifact.publishPath, roots);
+      const target = composePublicationTarget(artifact.publishPath, roots);
       const metadata = await readExistingMetadata(
         command,
         headObjectArgs(roots, artifact.publishPath, awsOptions),
@@ -238,51 +255,88 @@ export async function publishS3Static(request, dependencies = {}) {
           { sleep },
         );
       }
-      const uploadedMetadata = await runAws(
+      const uploadedMetadata = await readObjectMetadata(
         command,
         headObjectArgs(roots, artifact.publishPath, awsOptions),
         { sleep },
       );
-      assertMetadata(uploadedMetadata.stdout, artifact);
-      const response = await httpGet(target.publicUrl);
-      if (response.status < 200 || response.status > 299) {
-        throw publishError(
-          'E_PUBLISH_VERIFY',
-          `Public verification failed for ${artifact.manifestPath}.`,
-        );
-      }
-      const servedType = headerValue(response.headers, 'content-type');
-      if (!contentTypesMatch(servedType, artifact.contentType)) {
-        throw publishError(
-          'E_PUBLISH_VERIFY',
-          `Public content type mismatch for ${artifact.manifestPath}.`,
-        );
-      }
-      if (fileHash(responseBytes(response.body)) !== artifact.hash) {
-        throw publishError(
-          'E_PUBLISH_VERIFY',
-          `Public bytes do not match the manifest for ${artifact.manifestPath}.`,
-        );
+      assertMetadata(uploadedMetadata, artifact);
+      const objectVerification = await verifyObjectBytes({
+        command,
+        metadata: uploadedMetadata,
+        roots,
+        relativePath: artifact.publishPath,
+        expectedHash: artifact.hash,
+        downloadPath: join(
+          sentinelDirectory,
+          `object-${receiptArtifacts.length}.download`,
+        ),
+        awsOptions,
+        sleep,
+      });
+      let publicVerification = {
+        status: verificationPolicy.receiptSkipStatus,
+      };
+      if (verificationPolicy.verifyPublicly) {
+        const response = await httpGet(target.publicUrl);
+        if (response.status < 200 || response.status > 299) {
+          throw publishError(
+            'E_PUBLISH_VERIFY',
+            `Public verification failed for ${artifact.manifestPath}.`,
+          );
+        }
+        const servedType = headerValue(response.headers, 'content-type');
+        if (!contentTypesMatch(servedType, artifact.contentType)) {
+          throw publishError(
+            'E_PUBLISH_VERIFY',
+            `Public content type mismatch for ${artifact.manifestPath}.`,
+          );
+        }
+        const publicHash = fileHash(responseBytes(response.body));
+        if (publicHash !== artifact.hash) {
+          throw publishError(
+            'E_PUBLISH_VERIFY',
+            `Public bytes do not match the manifest for ${artifact.manifestPath}.`,
+          );
+        }
+        publicVerification = {
+          status: 'verified',
+          httpStatus: response.status,
+          hash: publicHash,
+        };
       }
       receiptArtifacts.push({
+        source: artifact.source,
         relativePath: artifact.manifestPath,
         hash: artifact.hash,
         s3Uri: target.s3Uri,
         publicUrl: target.publicUrl,
-        httpStatus: response.status,
         contentType: artifact.contentType,
+        objectVerification,
+        publicVerification,
       });
     }
 
     const receipt = {
-      schemaVersion: 'explainer-kit.publish-receipt/v1',
+      schemaVersion: 'explainer-kit.publish-receipt/v2',
       provider: 's3-static',
       publishedAt: now(),
+      publicAccess,
+      // Durable trace for the anti-SSRF opt-in. Without it, a run that
+      // published to an internal address with the control disabled is
+      // indistinguishable in retained evidence from one that did not, because
+      // the variable is read straight from the environment and enters no other
+      // record. Emitted only in that exceptional case, so ordinary receipts are
+      // byte-identical to before.
+      ...(privatePublicRootAllowed() &&
+        isPrivatePublicHost(new URL(roots.publicBaseUrl).hostname) && {
+          publicRootPolicy: 'private-allowed',
+        }),
       roots: { s3Uri: roots.s3Uri, publicBaseUrl: roots.publicBaseUrl },
       sentinel: {
         relativePath: sentinelRelativePath,
-        uploadVerified: true,
-        publicVerified: true,
+        objectVerification: sentinelObjectVerification,
+        publicVerification: sentinelPublicVerification,
         deleted: sentinelDeleted,
       },
       artifacts: receiptArtifacts,
@@ -375,6 +429,7 @@ async function collectArtifacts(manifest, siteRoot) {
     }
     const contentType = contentTypeFor(publishPath, entry.mediaType);
     artifacts.push({
+      source: { kind: 'manifest', artifactId: entry.id },
       manifestPath: entry.renderedPath,
       publishPath,
       filePath,
@@ -411,6 +466,8 @@ function putObjectArgs({
       cacheControl,
       '--metadata',
       `explainer-sha256=${hash.slice('sha256:'.length)}`,
+      '--checksum-sha256',
+      Buffer.from(hash.slice('sha256:'.length), 'hex').toString('base64'),
       '--no-cli-pager',
     ],
     awsOptions,
@@ -426,6 +483,8 @@ function headObjectArgs(roots, relativePath, awsOptions) {
       roots.bucket,
       '--key',
       objectKey(roots, relativePath),
+      '--checksum-mode',
+      'ENABLED',
       '--output',
       'json',
       '--no-cli-pager',
@@ -434,6 +493,24 @@ function headObjectArgs(roots, relativePath, awsOptions) {
   );
 }
 
+function getObjectArgs(roots, relativePath, downloadPath, awsOptions) {
+  return withAwsOptions(
+    [
+      's3api',
+      'get-object',
+      '--bucket',
+      roots.bucket,
+      '--key',
+      objectKey(roots, relativePath),
+      '--checksum-mode',
+      'ENABLED',
+      downloadPath,
+      '--no-cli-pager',
+    ],
+    awsOptions,
+  );
+}
+
 function deleteObjectArgs(roots, relativePath, awsOptions) {
   return withAwsOptions(
     [
@@ -500,6 +577,11 @@ async function readExistingMetadata(command, args, { sleep }) {
   }
 }
 
+async function readObjectMetadata(command, args, { sleep }) {
+  const result = await runAws(command, args, { sleep });
+  return parseAwsJson(result.stdout);
+}
+
 function matchesPublishedArtifact(metadata, artifact) {
   return (
     metadata?.Metadata?.['explainer-sha256'] ===
@@ -509,20 +591,75 @@ function matchesPublishedArtifact(metadata, artifact) {
   );
 }
 
-function assertMetadata(stdout, artifact) {
-  let metadata;
+function assertMetadata(metadata, artifact) {
+  if (!matchesPublishedArtifact(metadata, artifact)) {
+    throw publishError(
+      'E_PUBLISH_VERIFY',
+      `Uploaded metadata mismatch for ${artifact.manifestPath}.`,
+    );
+  }
+}
+
+async function verifyObjectBytes({
+  command,
+  metadata,
+  roots,
+  relativePath,
+  expectedHash,
+  downloadPath,
+  awsOptions,
+  sleep,
+}) {
+  const expectedBase64 = Buffer.from(
+    expectedHash.slice('sha256:'.length),
+    'hex',
+  ).toString('base64');
+  if (typeof metadata.ChecksumSHA256 === 'string') {
+    if (metadata.ChecksumSHA256 !== expectedBase64) {
+      throw publishError(
+        'E_PUBLISH_VERIFY',
+        `Authenticated object checksum mismatch for ${relativePath}.`,
+      );
+    }
+    return {
+      status: 'verified',
+      method: 'service-checksum',
+      hash: expectedHash,
+    };
+  }
+
   try {
-    metadata = JSON.parse(stdout || '{}');
+    await runAws(
+      command,
+      getObjectArgs(roots, relativePath, downloadPath, awsOptions),
+      { sleep },
+    );
   } catch {
     throw publishError(
       'E_PUBLISH_VERIFY',
-      'AWS returned invalid object metadata.',
+      `Authenticated object-byte verification is unavailable for ${relativePath}.`,
     );
   }
-  if (!matchesPublishedArtifact(metadata, artifact)) {
+  if (fileHash(await readFile(downloadPath)) !== expectedHash) {
     throw publishError(
       'E_PUBLISH_VERIFY',
-      `Uploaded metadata mismatch for ${artifact.manifestPath}.`,
+      `Authenticated object bytes do not match ${relativePath}.`,
+    );
+  }
+  return {
+    status: 'verified',
+    method: 'authenticated-download',
+    hash: expectedHash,
+  };
+}
+
+function parseAwsJson(stdout) {
+  try {
+    return JSON.parse(stdout || '{}');
+  } catch {
+    throw publishError(
+      'E_PUBLISH_VERIFY',
+      'AWS returned invalid object metadata.',
     );
   }
 }
@@ -554,17 +691,6 @@ function objectKey(roots, relativePath) {
   return roots.keyPrefix ? `${roots.keyPrefix}/${relativePath}` : relativePath;
 }
 
-function targetPath(relativePath, roots) {
-  const suffix = relativePath
-    .split('/')
-    .map((part) => encodeURIComponent(part))
-    .join('/');
-  return {
-    s3Uri: `${roots.s3Uri}/${relativePath}`,
-    publicUrl: `${roots.publicBaseUrl}/${suffix}`,
-  };
-}
-
 function fileHash(bytes) {
   return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
 }
@@ -596,9 +722,13 @@ async function defaultCommand(file, args) {
   return execFile(file, args, { maxBuffer: 1024 * 1024 });
 }
 
-async function defaultHttpGet(url) {
-  const response = await fetch(url, {
-    redirect: 'follow',
+export async function defaultHttpGet(url, { fetchImpl = fetch } = {}) {
+  // A canonical public artifact URL is uploaded to a known key and should never
+  // legitimately redirect. Following redirects turned public verification into
+  // an outbound GET primitive that a third party could bounce inward, so a
+  // redirect is a verification failure rather than something to chase.
+  const response = await fetchImpl(url, {
+    redirect: 'error',
     signal: AbortSignal.timeout(15_000),
   });
   return {

package/assets/skills/explainer-kit/scripts/lib/set-plan.mjs

@@ -14,6 +14,7 @@ export async function planExplainerSet({
     schemaVersion: 'explainer-kit.set-plan-request/v1',
     recipe: structuredClone(recipe),
     factBase: structuredClone(factBase),
+    sourceIds: structuredClone(sourceIds),
     discovery: structuredClone(discovery),
   });
   const callback =

package/assets/skills/explainer-kit/scripts/lib/terminal-evidence.mjs

@@ -0,0 +1,157 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { canonicalHash, validateContract } from './contracts.mjs';
+
+export const TERMINAL_EVIDENCE_VERSION = 'explainer-kit.terminal-evidence/v1';
+export const VISUAL_REVIEW_EVIDENCE_VERSION =
+  'explainer-kit.visual-review-evidence/v1';
+export const EVIDENCE_REASON_MAX_COUNT = 50;
+
+export function createTerminalEvidence({
+  runId,
+  outcome,
+  manifest,
+  reasons,
+  evidenceDisposition,
+  supersededBy,
+} = {}) {
+  const evidence = {
+    schemaVersion: TERMINAL_EVIDENCE_VERSION,
+    runId,
+    outcome,
+    ...(manifest && { manifestHash: canonicalHash(manifest) }),
+    reasons: structuredClone(reasons),
+    evidenceDisposition,
+    ...(supersededBy && {
+      supersededBy: structuredClone(supersededBy),
+    }),
+  };
+  assertTerminalEvidence(evidence, { manifest });
+  return evidence;
+}
+
+export function assertTerminalEvidence(evidence, { manifest } = {}) {
+  const validation = validateContract('terminal-evidence', evidence, {
+    manifest,
+  });
+  if (!validation.valid) {
+    throw new Error(
+      `Invalid terminal evidence: ${validation.errors
+        .map(({ path, code }) => `${path} [${code}]`)
+        .join('; ')}`,
+    );
+  }
+  return evidence;
+}
+
+export function createVisualReviewEvidence({
+  request,
+  attempt,
+  result,
+  failureKind,
+} = {}) {
+  const evidence = {
+    schemaVersion: VISUAL_REVIEW_EVIDENCE_VERSION,
+    requestHash: request?.requestHash,
+    attempt,
+    disposition: failureKind
+      ? 'failed'
+      : result?.disposition === 'pass'
+        ? 'pass'
+        : 'correct',
+    reasons: failureKind
+      ? [{ stage: 'visual-review', kind: failureKind, count: 1 }]
+      : result?.disposition === 'pass'
+        ? []
+        : findingReasons(result?.findings),
+  };
+  assertVisualReviewEvidence(evidence, { request, attempt });
+  return evidence;
+}
+
+export function assertVisualReviewEvidence(
+  evidence,
+  { request, attempt } = {},
+) {
+  const validation = validateContract('visual-review-evidence', evidence, {
+    visualReviewRequest: request,
+    attempt,
+  });
+  if (!validation.valid) {
+    throw new Error(
+      `Invalid retained visual evidence: ${validation.errors
+        .map(({ path, code }) => `${path} [${code}]`)
+        .join('; ')}`,
+    );
+  }
+  return evidence;
+}
+
+export function evidenceReason(stage, kind, { artifactId, count = 1 } = {}) {
+  return {
+    stage,
+    kind,
+    ...(artifactId !== undefined && { artifactId }),
+    count,
+  };
+}
+
+export function projectThrownReason(stage, kind = 'pipeline-failure') {
+  return evidenceReason(stage, kind);
+}
+
+export async function readTerminalEvidenceFile(
+  runRoot,
+  { manifest, expectedBytes, expectedHash } = {},
+) {
+  if (typeof runRoot !== 'string' || runRoot.length === 0) {
+    throw new TypeError('Terminal evidence run root must be a path string.');
+  }
+  const canonicalRunRoot = await realpath(runRoot);
+  const evidencePath = resolve(canonicalRunRoot, 'terminal-evidence.json');
+  const stats = await lstat(evidencePath);
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error(
+      'Terminal evidence must be a regular file, not a symbolic link.',
+    );
+  }
+  const canonicalEvidencePath = await realpath(evidencePath);
+  if (canonicalEvidencePath !== evidencePath) {
+    throw new Error('Terminal evidence must remain within the run root.');
+  }
+  const bytes = await readFile(canonicalEvidencePath);
+  const hash = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+  if (expectedHash !== undefined && hash !== expectedHash) {
+    throw new Error('Terminal evidence bytes changed while staging.');
+  }
+  if (
+    expectedBytes !== undefined &&
+    !bytes.equals(Buffer.from(expectedBytes))
+  ) {
+    throw new Error('Terminal evidence bytes changed while staging.');
+  }
+  let evidence;
+  try {
+    evidence = JSON.parse(bytes.toString('utf8'));
+  } catch {
+    throw new Error('Terminal evidence must contain valid JSON.');
+  }
+  assertTerminalEvidence(evidence, { manifest });
+  return { evidence, bytes, hash };
+}
+
+function findingReasons(findings) {
+  const counts = new Map();
+  let total = 0;
+  for (const finding of Array.isArray(findings) ? findings : []) {
+    if (total >= EVIDENCE_REASON_MAX_COUNT) break;
+    const artifactId = finding?.artifactId;
+    counts.set(artifactId, (counts.get(artifactId) ?? 0) + 1);
+    total += 1;
+  }
+  return [...counts].map(([artifactId, count]) =>
+    evidenceReason('visual-review', 'finding', { artifactId, count }),
+  );
+}