@open-agent-toolkit/cli 0.2.29 → 0.2.31

package/assets/skills/explainer-kit/schemas/publish-receipt.v2.schema.json

@@ -0,0 +1,215 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.publish-receipt/v2",
+  "title": "PublishReceiptV2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "provider",
+    "publishedAt",
+    "publicAccess",
+    "roots",
+    "sentinel",
+    "artifacts"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "explainer-kit.publish-receipt/v2"
+    },
+    "provider": {
+      "const": "s3-static"
+    },
+    "publishedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "publicAccess": {
+      "enum": ["public", "protected"]
+    },
+    "roots": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["s3Uri", "publicBaseUrl"],
+      "properties": {
+        "s3Uri": {
+          "type": "string",
+          "pattern": "^s3://[a-z0-9][a-z0-9.-]{1,61}[a-z0-9](?:/[^\\s/?#\\\\]+(?:/[^\\s/?#\\\\]+)*)?$"
+        },
+        "publicBaseUrl": {
+          "type": "string",
+          "pattern": "^https://[^\\s/?#@]+(?::[0-9]+)?(?:/[^\\s/?#\\\\]+(?:/[^\\s/?#\\\\]+)*)?$"
+        }
+      }
+    },
+    "sentinel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "relativePath",
+        "objectVerification",
+        "publicVerification",
+        "deleted"
+      ],
+      "properties": {
+        "relativePath": {
+          "$ref": "#/$defs/safeRelativePath"
+        },
+        "objectVerification": {
+          "$ref": "#/$defs/objectVerification"
+        },
+        "publicVerification": {
+          "$ref": "#/$defs/publicVerification"
+        },
+        "deleted": {
+          "type": "boolean"
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/artifact"
+      },
+      "uniqueItems": true
+    },
+    "publicRootPolicy": {
+      "description": "Present only when EXPLAINER_KIT_ALLOW_PRIVATE_PUBLIC_ROOT was set and the public root was in fact a non-public address, so a publication made with the anti-SSRF control disabled is distinguishable in durable evidence.",
+      "enum": ["private-allowed"]
+    }
+  },
+  "$defs": {
+    "hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "safeRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    },
+    "source": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "artifactId"],
+          "properties": {
+            "kind": {
+              "const": "manifest"
+            },
+            "artifactId": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "name"],
+          "properties": {
+            "kind": {
+              "const": "auxiliary"
+            },
+            "name": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      ]
+    },
+    "objectVerification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "method", "hash"],
+      "properties": {
+        "status": {
+          "const": "verified"
+        },
+        "method": {
+          "enum": ["service-checksum", "authenticated-download"]
+        },
+        "hash": {
+          "$ref": "#/$defs/hash"
+        }
+      }
+    },
+    "publicVerification": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "httpStatus", "hash"],
+          "properties": {
+            "status": {
+              "const": "verified"
+            },
+            "httpStatus": {
+              "type": "integer",
+              "minimum": 200,
+              "maximum": 299
+            },
+            "hash": {
+              "$ref": "#/$defs/hash"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "status": {
+              "const": "skipped-protected"
+            }
+          }
+        }
+      ]
+    },
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source",
+        "relativePath",
+        "hash",
+        "s3Uri",
+        "publicUrl",
+        "contentType",
+        "objectVerification",
+        "publicVerification"
+      ],
+      "properties": {
+        "source": {
+          "$ref": "#/$defs/source"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/safeRelativePath"
+        },
+        "hash": {
+          "$ref": "#/$defs/hash"
+        },
+        "s3Uri": {
+          "type": "string",
+          "pattern": "^s3://[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]/[^\\s?#\\\\]+$"
+        },
+        "publicUrl": {
+          "type": "string",
+          "pattern": "^https://[^\\s/?#@]+(?::[0-9]+)?/[^\\s?#\\\\]+$"
+        },
+        "contentType": {
+          "type": "string",
+          "minLength": 1
+        },
+        "objectVerification": {
+          "$ref": "#/$defs/objectVerification"
+        },
+        "publicVerification": {
+          "$ref": "#/$defs/publicVerification"
+        }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/publish-request.v2.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.publish-request/v2",
+  "title": "S3StaticPublishRequestV2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "provider",
+    "s3Uri",
+    "publicBaseUrl",
+    "awsRegion",
+    "publicAccess",
+    "siteRoot",
+    "manifestPath"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.publish-request/v2" },
+    "provider": { "const": "s3-static" },
+    "s3Uri": {
+      "type": "string",
+      "pattern": "^s3://[a-z0-9][a-z0-9.-]{1,61}[a-z0-9](?:/[^\\s/?#\\\\]+(?:/[^\\s/?#\\\\]+)*)?/?$"
+    },
+    "publicBaseUrl": {
+      "type": "string",
+      "pattern": "^https://[^\\s/?#@]+(?::[0-9]+)?(?:/[^\\s/?#\\\\]+(?:/[^\\s/?#\\\\]+)*)?/?$"
+    },
+    "awsRegion": { "type": "string", "minLength": 1 },
+    "awsProfile": { "type": "string", "minLength": 1 },
+    "publicAccess": { "enum": ["public", "protected"] },
+    "siteRoot": { "type": "string", "minLength": 1 },
+    "manifestPath": { "type": "string", "minLength": 1 }
+  }
+}

package/assets/skills/explainer-kit/schemas/run-request.schema.json

@@ -46,7 +46,10 @@
           "enum": ["none", "commit", "publish"]
         },
         "publish": {
-          "$ref": "explainer-kit.publish-request/v1"
+          "oneOf": [
+            { "$ref": "explainer-kit.publish-request/v1" },
+            { "$ref": "explainer-kit.publish-request/v2" }
+          ]
         }
       }
     },

package/assets/skills/explainer-kit/schemas/terminal-evidence.v1.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.terminal-evidence/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "runId",
+    "outcome",
+    "reasons",
+    "evidenceDisposition"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "explainer-kit.terminal-evidence/v1"
+    },
+    "runId": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "outcome": {
+      "enum": ["built-needs-review", "failed"]
+    },
+    "manifestHash": { "$ref": "#/$defs/hash" },
+    "reasons": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "items": { "$ref": "#/$defs/reason" }
+    },
+    "evidenceDisposition": {
+      "enum": ["retained", "partial", "unavailable", "superseded"]
+    },
+    "supersededBy": { "$ref": "#/$defs/supersededBy" }
+  },
+  "$defs": {
+    "hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "reason": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stage", "kind", "count"],
+      "properties": {
+        "stage": {
+          "enum": [
+            "planning",
+            "authoring",
+            "rendering",
+            "link-validation",
+            "browser-review",
+            "visual-review",
+            "durability",
+            "finalization"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "finding",
+            "provider-failure",
+            "pipeline-failure",
+            "superseded"
+          ]
+        },
+        "artifactId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000
+        },
+        "count": { "type": "integer", "minimum": 1, "maximum": 50 }
+      }
+    },
+    "supersededBy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runId", "manifestHash"],
+      "properties": {
+        "runId": { "type": "string", "minLength": 1, "maxLength": 2000 },
+        "manifestHash": { "$ref": "#/$defs/hash" }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/visual-review-evidence.v1.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.visual-review-evidence/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "requestHash",
+    "attempt",
+    "disposition",
+    "reasons"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "explainer-kit.visual-review-evidence/v1"
+    },
+    "requestHash": { "$ref": "#/$defs/hash" },
+    "attempt": { "enum": [1, 2] },
+    "disposition": { "enum": ["pass", "correct", "failed"] },
+    "reasons": {
+      "type": "array",
+      "minItems": 0,
+      "maxItems": 50,
+      "items": { "$ref": "#/$defs/reason" }
+    }
+  },
+  "$defs": {
+    "hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "reason": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stage", "kind", "count"],
+      "properties": {
+        "stage": {
+          "enum": [
+            "planning",
+            "authoring",
+            "rendering",
+            "link-validation",
+            "browser-review",
+            "visual-review",
+            "durability",
+            "finalization"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "finding",
+            "provider-failure",
+            "pipeline-failure",
+            "superseded"
+          ]
+        },
+        "artifactId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000
+        },
+        "count": { "type": "integer", "minimum": 1, "maximum": 50 }
+      }
+    }
+  }
+}

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

@@ -1,6 +1,85 @@
 import { canonicalStringify, validateContract } from './contracts.mjs';
 
-const CATALOG_SCHEMA_VERSION = 'explainer-kit.initiative-catalog/v1';
+/**
+ * Bumped to v2 when the root `publicVerification` marker was added below.
+ *
+ * The catalog is serialized, hashed, and recorded as an auxiliary artifact in
+ * the publish receipt, so adding a root key changes the bytes. Released
+ * `0.2.30` emits the v1 shape, which has no such key: leaving both shapes under
+ * one version string would put two different wire formats behind one identifier
+ * for anyone parsing `catalog.json` by declared version.
+ *
+ * There is deliberately no v1 read path. Unlike `publish-request/v1` and
+ * `publish-receipt/v1`, which are retained because a v1 record can still be
+ * replayed, the catalog is regenerate-only and never reconstructed from a v1
+ * receipt: every rebuild site short-circuits on a non-v2 receipt
+ * (`durability.mjs` verifyPublishEvidence, `run.mjs` publicationValidationContext,
+ * and the normative `private-wrapper.mjs` example), and `0.2.30` emits
+ * `publish-receipt/v1` only. Accepting v1 here would be unreachable code. If a
+ * future reader ever does replay a v1-era catalog, it must reconstruct that
+ * shape explicitly rather than relaxing this constant.
+ */
+const CATALOG_SCHEMA_VERSION = 'explainer-kit.initiative-catalog/v2';
+
+export const PUBLIC_VERIFICATION_REQUIRED = 'required';
+export const PUBLIC_VERIFICATION_SKIPPED_BY_POLICY = 'skipped-by-policy';
+
+/**
+ * Single source of truth for public-verification state.
+ *
+ * The catalog is built, serialized and hashed *before* the first upload and long
+ * before any per-artifact public verification runs, so it can never carry a
+ * verification *outcome*: writing one would either require re-uploading the
+ * catalog or invalidate the hash the receipt records for it. It therefore
+ * carries verification *policy* only, and the authoritative outcome stays in the
+ * run's publish receipt, which the catalog's `runId` identifies.
+ *
+ * Both the catalog marker and the receipt's skipped status are derived from this
+ * one result so the two cannot drift apart.
+ */
+export function resolvePublicVerificationPolicy(publicAccess) {
+  return publicAccess === 'protected'
+    ? {
+        publicAccess: 'protected',
+        catalogMarker: PUBLIC_VERIFICATION_SKIPPED_BY_POLICY,
+        verifyPublicly: false,
+        receiptSkipStatus: 'skipped-protected',
+      }
+    : {
+        publicAccess: 'public',
+        catalogMarker: PUBLIC_VERIFICATION_REQUIRED,
+        verifyPublicly: true,
+        receiptSkipStatus: 'skipped-protected',
+      };
+}
+
+/**
+ * The public-access policy must be stated explicitly, never defaulted.
+ *
+ * It selects the catalog's `publicVerification` marker, which is part of the
+ * serialized bytes and therefore of the catalog hash the receipt records. An
+ * options bag that silently defaulted to the permissive `public` branch is what
+ * let four call sites omit it and still produce a plausible-looking catalog:
+ * the connector published `skipped-by-policy` for a `protected` run while the
+ * durability verifier rebuilt `required`, so the hashes diverged and no
+ * `protected` publication could ever be recorded durable.
+ *
+ * Passing `{ publicAccess: undefined }` is allowed and means `public` — that is
+ * the correct reading for `publish-request/v1` and `publish-receipt/v1`, which
+ * have no such field. Omitting the key entirely is a programming error.
+ */
+function requiredPublicAccess(options, caller) {
+  if (
+    options === null ||
+    typeof options !== 'object' ||
+    !('publicAccess' in options)
+  ) {
+    throw new TypeError(
+      `${caller} requires an explicit { publicAccess } policy: it selects the catalog's publicVerification marker and therefore its hash. Pass { publicAccess: undefined } for v1 records, which are public by definition.`,
+    );
+  }
+  return options.publicAccess;
+}
 
 export function initiativeCatalogPath(slug) {
   if (typeof slug !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) {
@@ -9,7 +88,8 @@ export function initiativeCatalogPath(slug) {
   return `site/initiatives/${slug}/catalog.json`;
 }
 
-export function catalogFromManifest(manifest, publicBaseUrl) {
+export function catalogFromManifest(manifest, publicBaseUrl, options) {
+  const publicAccess = requiredPublicAccess(options, 'catalogFromManifest');
   const validation = validateContract('manifest', manifest);
   if (!validation.valid) {
     throw new TypeError(
@@ -45,12 +125,24 @@ export function catalogFromManifest(manifest, publicBaseUrl) {
     slug: manifest.slug,
     recipe: structuredClone(manifest.recipe),
     createdAt: manifest.createdAt,
+    // Policy, never outcome. See resolvePublicVerificationPolicy.
+    publicVerification:
+      resolvePublicVerificationPolicy(publicAccess).catalogMarker,
     artifacts,
     sourceBacklinks: structuredClone(manifest.source.backlinks ?? []),
   };
 }
 
-export function validateInitiativeCatalog(catalog, manifest, publicBaseUrl) {
+export function validateInitiativeCatalog(
+  catalog,
+  manifest,
+  publicBaseUrl,
+  options,
+) {
+  const publicAccess = requiredPublicAccess(
+    options,
+    'validateInitiativeCatalog',
+  );
   const errors = [];
   let normalizedPublicBaseUrl;
   try {
@@ -83,6 +175,7 @@ export function validateInitiativeCatalog(catalog, manifest, publicBaseUrl) {
     'slug',
     'recipe',
     'createdAt',
+    'publicVerification',
     'artifacts',
     'sourceBacklinks',
   ]);
@@ -110,6 +203,19 @@ export function validateInitiativeCatalog(catalog, manifest, publicBaseUrl) {
       );
     }
   }
+  // Derived from the same resolver the receipt status comes from, so a catalog
+  // that disagrees with the run's resolved verification policy is rejected.
+  const expectedPublicVerification =
+    resolvePublicVerificationPolicy(publicAccess).catalogMarker;
+  if (catalog.publicVerification !== expectedPublicVerification) {
+    add(
+      errors,
+      '$.publicVerification',
+      'catalog-verification-policy',
+      `Catalog publicVerification must be ${expectedPublicVerification} for this run's public access policy.`,
+    );
+  }
+
   if (
     canonicalStringify(catalog.recipe) !== canonicalStringify(manifest?.recipe)
   ) {