@open-agent-toolkit/cli 0.2.30 → 0.2.31

package/assets/skills/explainer-kit/scripts/lib/durability.mjs

@@ -4,7 +4,17 @@ import { readFile, realpath } from 'node:fs/promises';
 import { dirname, relative, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 
-import { canonicalHash, validateContract } from './contracts.mjs';
+import {
+  catalogFromManifest,
+  initiativeCatalogPath,
+  serializeInitiativeCatalog,
+  validateInitiativeCatalog,
+} from './catalog.mjs';
+import {
+  canonicalHash,
+  isVerifiablePublishReceipt,
+  validateContract,
+} from './contracts.mjs';
 import { writeFileAtomic, writeJsonAtomic } from './fs-safe.mjs';
 import { validateSafeRelativePath } from './safe-paths.mjs';
 
@@ -347,7 +357,14 @@ async function verifyCommitEvidence(evidence, { runRoot, manifest }) {
       };
 }
 
-async function verifyPublishEvidence(evidence, { runRoot, manifest }) {
+async function verifyPublishEvidence(
+  evidence,
+  { runRoot, manifest, options = {} },
+) {
+  // Injectable for the rejection-branch test below, exactly as `fetchImpl` is
+  // on `defaultHttpGet`: the branch fires only when the builder and validator
+  // disagree, which correct production code never does on purpose.
+  const buildCatalog = options.buildCatalog ?? catalogFromManifest;
   const expectedPath = joinWithin(runRoot, 'publish-receipt.json');
   if (resolve(evidence.receiptPath) !== expectedPath) {
     return {
@@ -370,15 +387,61 @@ async function verifyPublishEvidence(evidence, { runRoot, manifest }) {
       errors: [error('publish-receipt', errorMessage(caught))],
     };
   }
-  const validation = validateContract('publish-receipt', receipt, { manifest });
+  let catalogArtifact;
+  if (isVerifiablePublishReceipt(receipt)) {
+    try {
+      // Must rebuild the catalog under the policy the receipt declares. The
+      // connector embedded that policy in the catalog it hashed, so verifying a
+      // `protected` receipt against a `public`-shaped rebuild yields a
+      // different hash and rejects every protected publication as
+      // `cross-record-mismatch`.
+      const catalog = buildCatalog(manifest, receipt.roots?.publicBaseUrl, {
+        publicAccess: receipt.publicAccess,
+      });
+      // This is a builder/validator cross-check on a catalog rebuilt three
+      // lines above from the same inputs — durability never consumes catalog
+      // bytes from outside, only a recorded hash, so no externally-sourced
+      // catalog object exists here to validate. The value of the check is that
+      // `catalogFromManifest` and `validateInitiativeCatalog` are independent
+      // implementations of the same contract: if they ever diverge, this
+      // reports the specific contract violation instead of letting the
+      // divergence surface as an opaque `cross-record-mismatch`.
+      const catalogValidation = validateInitiativeCatalog(
+        catalog,
+        manifest,
+        receipt.roots?.publicBaseUrl,
+        { publicAccess: receipt.publicAccess },
+      );
+      if (!catalogValidation.valid) {
+        return {
+          verified: false,
+          errors: [
+            error(
+              'publish-receipt',
+              `Rebuilt initiative catalog is invalid: ${catalogValidation.errors[0].message}`,
+            ),
+          ],
+        };
+      }
+      catalogArtifact = {
+        relativePath: initiativeCatalogPath(manifest.slug),
+        hash: bufferHash(Buffer.from(serializeInitiativeCatalog(catalog))),
+      };
+    } catch (caught) {
+      return {
+        verified: false,
+        errors: [error('publish-receipt', errorMessage(caught))],
+      };
+    }
+  }
+  const validation = validateContract('publish-receipt', receipt, {
+    manifest,
+    ...(catalogArtifact && { catalogArtifact }),
+  });
   const errors = validation.errors.map(({ code, message }) =>
     error(code, message),
   );
-  if (
-    receipt.sentinel?.uploadVerified !== true ||
-    receipt.sentinel?.publicVerified !== true ||
-    receipt.sentinel?.deleted !== true
-  ) {
+  if (!sentinelVerificationComplete(receipt)) {
     errors.push(
       error(
         'sentinel-verification',
@@ -421,6 +484,25 @@ async function verifyPublishEvidence(evidence, { runRoot, manifest }) {
       };
 }
 
+function sentinelVerificationComplete(receipt) {
+  if (receipt.sentinel?.deleted !== true) return false;
+  if (receipt.schemaVersion === 'explainer-kit.publish-receipt/v1') {
+    return (
+      receipt.sentinel.uploadVerified === true &&
+      receipt.sentinel.publicVerified === true
+    );
+  }
+  if (receipt.schemaVersion !== 'explainer-kit.publish-receipt/v2') {
+    return false;
+  }
+  return (
+    receipt.sentinel.objectVerification?.status === 'verified' &&
+    (receipt.publicAccess === 'public'
+      ? receipt.sentinel.publicVerification?.status === 'verified'
+      : receipt.sentinel.publicVerification?.status === 'skipped-protected')
+  );
+}
+
 function appendEvidence(artifact, evidence) {
   artifact.durableEvidence ??= [];
   if (hasEvidence(artifact, evidence)) {

package/assets/skills/explainer-kit/scripts/lib/fs-safe.mjs

@@ -41,6 +41,11 @@ export async function createConfinedRunRoot(outputRoot, slug) {
 
   const normalizedSlug = normalizeSlug(slug);
   const requestedRoot = resolve(checkedRoot.normalizedPath);
+  if (basename(requestedRoot) === normalizedSlug) {
+    throw new Error(
+      `Output root already ends in run slug "${normalizedSlug}"; supply the parent output root to avoid double-nesting.`,
+    );
+  }
   await mkdir(requestedRoot, { recursive: true });
   const canonicalRoot = await realpath(requestedRoot);
   const runRoot = join(canonicalRoot, normalizedSlug);

package/assets/skills/explainer-kit/scripts/lib/internal-references.mjs

@@ -0,0 +1,538 @@
+const MAX_HTML_BYTES = 1_000_000;
+const MAX_ELEMENTS = 10_000;
+const MAX_REFERENCES = 20_000;
+const MAX_ERRORS = 100;
+const RAW_TEXT_ELEMENTS = new Set(['script', 'style']);
+const REFERENCE_ATTRIBUTES = new Set([
+  'href',
+  'poster',
+  'src',
+  'srcset',
+  'xlink:href',
+]);
+const SAFE_DATA_REFERENCE =
+  /^data:image\/(?:gif|jpeg|png|webp);base64,[a-z0-9+/]+={0,2}$/i;
+
+export function validateInternalReferences({ artifacts, manifestPaths } = {}) {
+  const errors = [];
+  const add = (artifactId, code, message, detail = {}) => {
+    if (errors.length >= MAX_ERRORS) return;
+    errors.push({ artifactId, code, message, ...detail });
+  };
+  if (!Array.isArray(artifacts) || !Array.isArray(manifestPaths)) {
+    add(
+      null,
+      'invalid-site-tree',
+      'Internal-reference validation requires artifacts and manifest paths.',
+    );
+    return { valid: false, errors };
+  }
+  const declaredPaths = new Set(manifestPaths);
+  if (
+    declaredPaths.size !== manifestPaths.length ||
+    manifestPaths.some((path) => !isCanonicalSitePath(path))
+  ) {
+    add(
+      null,
+      'invalid-site-tree',
+      'Manifest paths must be unique canonical site-relative files.',
+    );
+  }
+
+  const idsByPath = new Map();
+  const tokenized = [];
+  const boundPaths = new Set();
+  let referenceCount = 0;
+  for (const artifact of artifacts) {
+    if (
+      !isObject(artifact) ||
+      typeof artifact.artifactId !== 'string' ||
+      typeof artifact.renderedPath !== 'string' ||
+      typeof artifact.html !== 'string' ||
+      !declaredPaths.has(artifact.renderedPath)
+    ) {
+      add(
+        artifact?.artifactId ?? null,
+        'invalid-site-tree',
+        'Every rendered artifact must bind to one manifest-declared site path.',
+      );
+      continue;
+    }
+    if (boundPaths.has(artifact.renderedPath)) {
+      add(
+        artifact.artifactId,
+        'invalid-site-tree',
+        'Rendered artifact paths must be unique.',
+        { renderedPath: artifact.renderedPath },
+      );
+      continue;
+    }
+    boundPaths.add(artifact.renderedPath);
+    if (Buffer.byteLength(artifact.html, 'utf8') > MAX_HTML_BYTES) {
+      add(
+        artifact.artifactId,
+        'validation-bound',
+        `Rendered artifact exceeds the ${MAX_HTML_BYTES}-byte validation bound.`,
+      );
+      continue;
+    }
+    const parsed = tokenizeBoundedHtml(artifact.html);
+    if (!parsed.valid) {
+      add(artifact.artifactId, parsed.code, parsed.message, {
+        renderedPath: artifact.renderedPath,
+      });
+      continue;
+    }
+    const idCounts = new Map();
+    for (const element of parsed.elements) {
+      for (const attribute of element.attributes) {
+        if (attribute.name === 'id') {
+          idCounts.set(
+            attribute.value,
+            (idCounts.get(attribute.value) ?? 0) + 1,
+          );
+        }
+        if (REFERENCE_ATTRIBUTES.has(attribute.name)) {
+          referenceCount += 1;
+        }
+      }
+    }
+    idsByPath.set(artifact.renderedPath, idCounts);
+    tokenized.push({ artifact, elements: parsed.elements });
+  }
+  if (referenceCount > MAX_REFERENCES) {
+    add(
+      null,
+      'validation-bound',
+      `Rendered site exceeds the ${MAX_REFERENCES}-reference validation bound.`,
+    );
+    return { valid: false, errors };
+  }
+
+  for (const { artifact, elements } of tokenized) {
+    for (const element of elements) {
+      for (const attribute of element.attributes) {
+        if (!REFERENCE_ATTRIBUTES.has(attribute.name)) continue;
+        const references =
+          attribute.name === 'srcset'
+            ? parseSrcset(attribute.value)
+            : { valid: true, values: [attribute.value] };
+        if (!references.valid) {
+          add(
+            artifact.artifactId,
+            'malformed-srcset',
+            'srcset must contain bounded URL candidates with valid descriptors.',
+            referenceDetail(artifact, element, attribute, attribute.value),
+          );
+          continue;
+        }
+        for (const reference of references.values) {
+          validateReference({
+            artifact,
+            element,
+            attribute,
+            reference,
+            declaredPaths,
+            idsByPath,
+            add,
+          });
+        }
+      }
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function validateReference({
+  artifact,
+  element,
+  attribute,
+  reference,
+  declaredPaths,
+  idsByPath,
+  add,
+}) {
+  const detail = referenceDetail(artifact, element, attribute, reference);
+  if (
+    typeof reference !== 'string' ||
+    reference.length === 0 ||
+    hasUnsafeRawReferenceBytes(reference)
+  ) {
+    add(
+      artifact.artifactId,
+      'unsafe-reference',
+      'References must use a non-empty canonical raw form.',
+      detail,
+    );
+    return;
+  }
+  const scheme = reference.match(/^([a-z][a-z0-9+.-]*):/i)?.[1]?.toLowerCase();
+  if (scheme === 'data') {
+    if (
+      !isResourceAttribute(element.name, attribute.name) ||
+      !SAFE_DATA_REFERENCE.test(reference)
+    ) {
+      add(
+        artifact.artifactId,
+        'unsafe-scheme',
+        'Only bounded base64 image data references are allowed inline.',
+        detail,
+      );
+    }
+    return;
+  }
+  if (scheme) {
+    let external;
+    try {
+      external = new URL(reference);
+    } catch {
+      add(
+        artifact.artifactId,
+        'malformed-reference',
+        'Absolute reference is malformed.',
+        detail,
+      );
+      return;
+    }
+    if (
+      scheme !== 'https' ||
+      external.username ||
+      external.password ||
+      (element.name !== 'a' && element.name !== 'area') ||
+      attribute.name !== 'href'
+    ) {
+      add(
+        artifact.artifactId,
+        scheme === 'https' && isResourceAttribute(element.name, attribute.name)
+          ? 'external-resource'
+          : 'unsafe-scheme',
+        'External resources and unsafe navigation schemes are not allowed.',
+        detail,
+      );
+    }
+    return;
+  }
+  if (reference.startsWith('//')) {
+    add(
+      artifact.artifactId,
+      'unsafe-reference',
+      'Protocol-relative references are ambiguous.',
+      detail,
+    );
+    return;
+  }
+  if (reference.includes('?')) {
+    add(
+      artifact.artifactId,
+      'query-reference',
+      'Internal references cannot contain queries.',
+      detail,
+    );
+    return;
+  }
+  const [pathPart, rawFragment, ...extraFragments] = reference.split('#');
+  if (extraFragments.length > 0) {
+    add(
+      artifact.artifactId,
+      'malformed-reference',
+      'Internal references can contain at most one fragment delimiter.',
+      detail,
+    );
+    return;
+  }
+  if (pathPart.endsWith('/')) {
+    add(
+      artifact.artifactId,
+      'directory-reference',
+      'Internal links must name an explicit file such as index.html.',
+      detail,
+    );
+    return;
+  }
+  if (pathPart.startsWith('/')) {
+    add(
+      artifact.artifactId,
+      'site-root-escape',
+      'Internal references must be relative to the current artifact.',
+      detail,
+    );
+    return;
+  }
+  const base = new URL(artifact.renderedPath, 'https://explainer.invalid/');
+  let resolved;
+  try {
+    resolved = new URL(reference, base);
+  } catch {
+    add(
+      artifact.artifactId,
+      'malformed-reference',
+      'Relative reference is malformed.',
+      detail,
+    );
+    return;
+  }
+  if (
+    resolved.origin !== base.origin ||
+    resolved.protocol !== 'https:' ||
+    !resolved.pathname.startsWith('/site/')
+  ) {
+    add(
+      artifact.artifactId,
+      'site-root-escape',
+      'Internal reference resolves outside the generated site root.',
+      detail,
+    );
+    return;
+  }
+  const targetPath = resolved.pathname.slice(1);
+  if (!declaredPaths.has(targetPath)) {
+    add(
+      artifact.artifactId,
+      'missing-target',
+      'Internal reference does not resolve to a manifest-declared file.',
+      { ...detail, targetPath },
+    );
+    return;
+  }
+  if (rawFragment !== undefined) {
+    let fragment;
+    try {
+      fragment = decodeURIComponent(rawFragment);
+    } catch {
+      add(
+        artifact.artifactId,
+        'malformed-reference',
+        'Reference fragment is not valid percent-encoded text.',
+        detail,
+      );
+      return;
+    }
+    const targetCount = idsByPath.get(targetPath)?.get(fragment) ?? 0;
+    if (!fragment || targetCount === 0) {
+      add(
+        artifact.artifactId,
+        'missing-fragment',
+        'Internal reference fragment does not exist in the target document.',
+        { ...detail, targetPath, fragment },
+      );
+    } else if (targetCount > 1) {
+      add(
+        artifact.artifactId,
+        'ambiguous-fragment',
+        'Internal reference fragment resolves to multiple targets in the target document.',
+        { ...detail, targetPath, fragment },
+      );
+    }
+  }
+}
+
+function tokenizeBoundedHtml(html) {
+  const elements = [];
+  let cursor = 0;
+  while (cursor < html.length) {
+    const open = html.indexOf('<', cursor);
+    if (open < 0) break;
+    if (html.startsWith('<!--', open)) {
+      const close = html.indexOf('-->', open + 4);
+      if (close < 0) return malformedHtml();
+      cursor = close + 3;
+      continue;
+    }
+    const close = findTagEnd(html, open + 1);
+    if (close < 0) return malformedHtml();
+    const source = html.slice(open + 1, close);
+    if (/^\s*[!/]/.test(source)) {
+      cursor = close + 1;
+      continue;
+    }
+    const parsed = parseStartTag(source);
+    if (!parsed.valid) return malformedHtml();
+    elements.push(parsed.element);
+    if (elements.length > MAX_ELEMENTS) {
+      return {
+        valid: false,
+        code: 'validation-bound',
+        message: `Rendered artifact exceeds the ${MAX_ELEMENTS}-element validation bound.`,
+      };
+    }
+    cursor = close + 1;
+    if (RAW_TEXT_ELEMENTS.has(parsed.element.name)) {
+      const closing = indexOfCaseInsensitive(
+        html,
+        `</${parsed.element.name}`,
+        cursor,
+      );
+      if (closing < 0) return malformedHtml();
+      const closingEnd = findTagEnd(html, closing + 2);
+      if (closingEnd < 0) return malformedHtml();
+      cursor = closingEnd + 1;
+    }
+  }
+  return { valid: true, elements };
+}
+
+function findTagEnd(html, start) {
+  let quote = null;
+  for (let index = start; index < html.length; index += 1) {
+    const char = html[index];
+    if (quote) {
+      if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+    } else if (char === '>') {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function parseStartTag(source) {
+  const nameMatch = source.match(/^\s*([a-z][a-z0-9:-]*)/i);
+  if (!nameMatch) return { valid: false };
+  const name = nameMatch[1].toLowerCase();
+  const attributes = [];
+  let cursor = nameMatch[0].length;
+  while (cursor < source.length) {
+    while (/\s/.test(source[cursor] ?? '')) cursor += 1;
+    if (cursor >= source.length || source[cursor] === '/') break;
+    const attributeMatch = source
+      .slice(cursor)
+      .match(/^([^\s"'<>/=]+)(?:\s*=\s*)?/);
+    if (!attributeMatch) return { valid: false };
+    const attributeName = attributeMatch[1].toLowerCase();
+    cursor += attributeMatch[0].length;
+    const hasValue = attributeMatch[0].includes('=');
+    let value = '';
+    if (hasValue) {
+      const quote = source[cursor];
+      if (quote !== '"' && quote !== "'") return { valid: false };
+      const end = source.indexOf(quote, cursor + 1);
+      if (end < 0) return { valid: false };
+      value = decodeHtmlReferences(source.slice(cursor + 1, end));
+      cursor = end + 1;
+    }
+    attributes.push({ name: attributeName, value });
+  }
+  return { valid: true, element: { name, attributes } };
+}
+
+function parseSrcset(value) {
+  const values = [];
+  let cursor = 0;
+  while (cursor < value.length) {
+    while (/\s/.test(value[cursor] ?? '')) cursor += 1;
+    if (cursor >= value.length || value[cursor] === ',') {
+      return { valid: false, values: [] };
+    }
+    const dataReference =
+      value.slice(cursor, cursor + 'data:'.length).toLowerCase() === 'data:';
+    const urlStart = cursor;
+    if (dataReference) {
+      while (cursor < value.length && !/\s/.test(value[cursor])) {
+        cursor += 1;
+      }
+    } else {
+      while (cursor < value.length && !/[\s,]/.test(value[cursor])) {
+        cursor += 1;
+      }
+    }
+    const url = value.slice(urlStart, cursor);
+    if (!url) return { valid: false, values: [] };
+    values.push(url);
+    if (value[cursor] === ',') {
+      cursor += 1;
+      continue;
+    }
+    while (/\s/.test(value[cursor] ?? '')) cursor += 1;
+    const descriptorStart = cursor;
+    while (cursor < value.length && !/[\s,]/.test(value[cursor])) {
+      cursor += 1;
+    }
+    const descriptor = value.slice(descriptorStart, cursor);
+    if (descriptor && !/^(?:\d+w|(?:\d+(?:\.\d+)?|\.\d+)x)$/.test(descriptor)) {
+      return { valid: false, values: [] };
+    }
+    while (/\s/.test(value[cursor] ?? '')) cursor += 1;
+    if (cursor < value.length) {
+      if (value[cursor] !== ',') return { valid: false, values: [] };
+      cursor += 1;
+    }
+  }
+  return {
+    valid: values.length > 0,
+    values,
+  };
+}
+
+function hasUnsafeRawReferenceBytes(value) {
+  if (
+    value !== value.trim() ||
+    value.includes('\\') ||
+    value.includes('\0') ||
+    /%(?:2e|2f|5c)/i.test(value)
+  ) {
+    return true;
+  }
+  for (const char of value) {
+    const code = char.codePointAt(0);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+function isResourceAttribute(elementName, attributeName) {
+  return (
+    ['poster', 'src', 'srcset'].includes(attributeName) ||
+    (['href', 'xlink:href'].includes(attributeName) &&
+      !['a', 'area'].includes(elementName))
+  );
+}
+
+function isCanonicalSitePath(value) {
+  if (
+    typeof value !== 'string' ||
+    !/^site\/[a-z0-9._-]+(?:\/[a-z0-9._-]+)*$/i.test(value)
+  ) {
+    return false;
+  }
+  return value.split('/').every((segment) => !['.', '..'].includes(segment));
+}
+
+function referenceDetail(artifact, element, attribute, reference) {
+  return {
+    renderedPath: artifact.renderedPath,
+    element: element.name,
+    attribute: attribute.name,
+    reference,
+  };
+}
+
+function malformedHtml() {
+  return {
+    valid: false,
+    code: 'malformed-html',
+    message: 'Rendered HTML cannot be tokenized safely.',
+  };
+}
+
+function indexOfCaseInsensitive(source, search, fromIndex) {
+  return source.toLowerCase().indexOf(search.toLowerCase(), fromIndex);
+}
+
+function decodeHtmlReferences(value) {
+  return value.replace(
+    /&(?:amp|quot|apos|#39|#x27);/gi,
+    (entity) =>
+      ({
+        '&amp;': '&',
+        '&quot;': '"',
+        '&apos;': "'",
+        '&#39;': "'",
+        '&#x27;': "'",
+      })[entity.toLowerCase()] ?? entity,
+  );
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}