From bfd0e8d177e6161ce32e89b268ec001154be6320 Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Fri, 20 Mar 2026 02:38:47 -0400 Subject: [PATCH] Strengthen release validation and policy docs --- .github/workflows/validate.yml | 21 +++++++----- CHANGELOG.md | 62 +++++++++++++++++++++++++++++----- ONBOARDING.md | 6 ++++ README.md | 8 ++++- SECURITY.md | 59 +++++++++++++++++++++++++------- SPEC.md | 1 + scripts/validate-cards.mjs | 18 ---------- 7 files changed, 127 insertions(+), 48 deletions(-) diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index eed3eac..9b10be4 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -10,14 +10,17 @@ jobs: validate-current-release: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - name: Checkout + uses: actions/checkout@v4 - - uses: actions/setup-node@v4 + - name: Setup Node + uses: actions/setup-node@v4 with: node-version: 22 + cache: npm - name: Install dependencies - run: npm install + run: npm ci - name: Validate current-line schema and card integrity run: npm run validate:current @@ -25,8 +28,7 @@ jobs: - name: Verify release checksums run: npm run validate:checksums - # This verifies release-level integrity, including URL resolution and bundle reproducibility. - - name: Validate release-level manifest, bundle, and upstream bindings + - name: Release validation run: npm run validate:release # Mirror enforcement stays explicit because publish-time mirror availability can lag normal CI. @@ -35,14 +37,17 @@ jobs: validate-legacy-compatibility: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - name: Checkout + uses: actions/checkout@v4 - - uses: actions/setup-node@v4 + - name: Setup Node + uses: actions/setup-node@v4 with: node-version: 22 + cache: npm - name: Install dependencies - run: npm install + run: npm ci - name: Validate legacy compatibility line run: npm run validate:legacy diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a655e8..4e7a172 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,17 +1,61 @@ # Changelog -This changelog records release-line differences that are visible in the checked-in schemas, cards, and discovery artifacts. +This changelog records release-line differences that are visible in the checked-in schemas, cards, discovery artifacts, and release validation flow. -## v1.1.0 (current line) +## [1.1.0] -- Card schema remains closed with `additionalProperties: false`, but the allowed card surface is reduced to binding fields such as identity, lifecycle, verb binding, schema links, routing, networks, and license. -- Descriptive card fields present in v1.0.0, including `slug`, `display_name`, `description`, `capabilities`, and `meta`, are not part of the v1.1.0 card schema. -- `schemas_mirror` is a required peer to `schemas`, so each card carries both authoritative upstream schema URLs and CommandLayer mirror URLs. -- Canonical schema references in current cards move to tagged HTTPS source URLs instead of the IPFS-based request/receipt references used in v1.0.0 cards. -- The current card schema tightens several bindings: `version` is fixed to `1.1.0`, `entry` is pinned to the `v1.1.0` x402 form, and `implements` is limited to exactly one verb. -- Discovery and repository docs for the current line define a clearer authority split: root `v1.1.0` artifacts are canonical, `dist-pin/agent-cards/v1.1.0/` is derivative, and `v1.0.0` is retained only for compatibility. +### Why 1.1.0 happened -## v1.0.0 (legacy line) +`v1.1.0` establishes the current canonical Agent Cards line around flat, directly inspectable bindings and reproducible release artifacts. The goal is to remove migration-era ambiguity from cards, discovery descriptors, and publication surfaces so reviewers can validate the current release line without inferring hidden inheritance or historical packaging assumptions. + +### Added + +- Flat `v1.1.0` agent card structure aligned directly to the current protocol schema surfaces. +- Required `schemas_mirror` bindings alongside authoritative upstream schema URLs for each current-line card. +- Release validation and checksum-oriented artifact discipline for canonical root artifacts plus the derivative `dist-pin/` publish bundle. +- Clearer metadata around current published artifacts, including manifest and discovery authority boundaries. + +### Changed + +- `v1.1.0` cards now bind directly to current Commons and Commercial protocol surfaces rather than older shared or inherited descriptor patterns. +- Descriptor and publication surfaces were simplified so root repository artifacts are authoritative, `.well-known/` stays discovery-only, and `dist-pin/agent-cards/v1.1.0/` is explicitly derivative. +- Current-line schema references moved to tagged HTTPS source URLs and `commandlayer.org` mirror URLs. +- Validation for the current line is centered on canonical cards, manifest alignment, checksums, and reproducible release artifacts. + +### Removed + +- Legacy or shared structural patterns carried forward from `v1.0.0` where they were no longer needed for the current line. +- Deprecated descriptive card fields from the current-line schema surface, including `slug`, `display_name`, `description`, `capabilities`, and `meta`. +- Deprecated internal migration-era packaging assumptions that made the publication path harder to inspect. + +### Flattened + +- Current-line cards are intentionally flat and minimal, publishing binding facts directly instead of relying on `_shared` composition for `v1.1.0`. +- Current release validation treats the repository root as the authority surface and the publish bundle as a reproducible copy, not a second source of truth. + +### Moved + +- Current schema bindings moved from legacy IPFS-era and descriptor-led references to direct tagged HTTPS schema URLs plus explicit public mirror URLs. +- Current publication expectations moved toward manifest-checked, checksum-covered, release-validated root artifacts. + +### Legacy status + +- `v1.0.0` remains legacy-compatible where documented, but it is no longer the current canonical working line. +- `v1.0.0` artifacts are retained for archival compatibility and migration review, not as the preferred source for new integrations. + +### Breaking or non-breaking? + +- For consumers already treating `v1.1.0` as a distinct release line, this is the authoritative current line and not a surprise patch over `v1.0.0`. +- For tooling that depended on `v1.0.0` shared schema paths, broader descriptor assumptions, descriptive card fields, or older publication layouts, migrating to `v1.1.0` is a breaking change and requires updates. + +### Migration notes + +- Treat `v1.1.0` as the authoritative current line. +- Update tooling that expects `v1.0.0` shared schema paths, descriptor-led inheritance, or IPFS-era schema bindings. +- Expect current cards to expose only the minimal binding fields required by the `v1.1.0` schema. +- Use the root package validation and release commands, and validate against the canonical root artifacts plus `checksums.txt`. + +## [1.0.0] - Legacy compatibility line retained in-tree for archival and migration purposes. - Looser schema and descriptor enforcement, including a permissive descriptor schema and a broader card field set. diff --git a/ONBOARDING.md b/ONBOARDING.md index e988550..afbfe37 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -21,6 +21,12 @@ Agent Cards v1.1.0 is the current canonical release line. Root repository artifa Do not add new `_shared` helpers for v1.1.0. Do not add descriptive fields to current-line cards; if the detail is not a binding fact, keep it in external documentation or in the linked protocol schemas instead. +## Historical scripts + +The `scripts/archive/` directory is retained for historical reference only. It is not part of the current `v1.1.0` workflow and should not be treated as an active or supported execution path. + +Use the root package scripts and documented current validation and release commands instead. + ## Legacy / compatibility - `v1.0.0` is superseded by `v1.1.0`. diff --git a/README.md b/README.md index 6908269..64016be 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,16 @@ Agent Cards are CommandLayer's canonical discovery and binding artifacts. They bind ENS names to a single verb, the authoritative request/receipt schemas for that verb, the public schema mirrors, and the semver-pinned x402 entrypoint. They do not act as product pages, feature summaries, or semantic substitutes for the linked protocol schemas. -In these cards, `x402://...` is the protocol-form entry identifier used by CommandLayer agents. It represents a standardized action endpoint (verb + route + version). See `https://docs.x402.org/` for the external protocol definition. +In these cards, `x402://...` is the protocol-form entry identifier used by CommandLayer agents. It represents a standardized action endpoint (verb + route + version). See the external x402 protocol specification at `https://docs.x402.org/` for the canonical protocol definition. See `CHANGELOG.md` for version differences. +## x402 compatibility + +Commercial CommandLayer flows may reference payment proof or settlement artifacts aligned with the x402 protocol model where applicable. CommandLayer does not define the x402 protocol itself; it interoperates with that payment context as an external protocol surface. + +See the x402 protocol specification for the canonical definition: `https://docs.x402.org/`. + ## Authority Model - **Current canonical release line:** `v1.1.0` diff --git a/SECURITY.md b/SECURITY.md index f113db3..11e32ae 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,18 +1,53 @@ -# Security Policy — Agent Cards +# Security Policy This repository publishes discovery metadata, schema bindings, manifests, and checksums for CommandLayer Agent Cards. -Report security issues that could affect integrity, routing, or trust in the published artifacts, including: -- incorrect or malicious card, manifest, or discovery bindings -- checksum drift or release-bundle mismatches -- incorrect `entry` routing or schema references -- changes that could cause consumers to resolve the wrong artifact +## Reporting a vulnerability -For responsible disclosure, email `dev@commandlayer.org` with: -- a short description of the issue -- affected files, URLs, or versions -- reproduction steps or proof of impact +Please report suspected security issues to: `dev@commandlayer.org` -Please do not publish exploit details or active abuse techniques before we have had a reasonable chance to review and coordinate a fix. +Include: +- affected repository and version +- reproduction steps +- proof of concept, if available +- impact assessment +- any suggested mitigations -Responses are handled on a best-effort basis. We will review credible reports, ask follow-up questions if needed, and coordinate remediation or publication when appropriate. +Please do not open public issues for unpatched vulnerabilities. + +## Supported reporting path + +Email is the supported intake path for private vulnerability reports affecting this repository's trust, validation, release, or publication surfaces. If we need follow-up context, we may continue the discussion by email and ask for a minimal private reproduction or patch suggestion. + +## Disclosure process + +After receiving a report, we will: +1. acknowledge receipt +2. validate and reproduce the issue +3. assess severity and affected surfaces +4. prepare a fix or mitigation +5. coordinate disclosure as appropriate + +We ask reporters to avoid public disclosure until remediation or coordinated disclosure timing has been agreed. + +## Response targets + +- Initial acknowledgment: within 3 business days +- Triage or status update after review: within 7 business days +- Fix timeline: depends on severity, impact, and release scope + +## Scope + +This policy covers: +- schema integrity issues with security implications +- validation bypasses +- artifact substitution or release integrity issues +- signing or verification related issues +- metadata or publication issues that could mislead integrators about trust surfaces + +## Out of scope + +This policy does not cover: +- general feature requests +- stylistic documentation issues +- unsupported historical artifacts unless they create active security risk diff --git a/SPEC.md b/SPEC.md index b41e5b8..66a0379 100644 --- a/SPEC.md +++ b/SPEC.md @@ -66,6 +66,7 @@ The schema also requires `schemas.request`, `schemas.receipt`, `schemas_mirror.r - `$id` MUST match the card's canonical HTTPS path - `entry` MUST be `x402:////v1.1.0` - `x402://` is the protocol-form entry identifier used by CommandLayer agents; it represents a standardized action endpoint (verb + route + version). See `https://docs.x402.org/` for the external protocol reference +- Commercial artifacts MAY include x402-aligned payment proof or settlement references where applicable. The x402 protocol is external to this specification and should be treated as its own canonical protocol surface at `https://docs.x402.org/`. - v1.0.0 MAY remain in the repository only as a legacy archival compatibility surface ## 6. Binding rules diff --git a/scripts/validate-cards.mjs b/scripts/validate-cards.mjs index 902794c..2e99d7e 100644 --- a/scripts/validate-cards.mjs +++ b/scripts/validate-cards.mjs @@ -241,22 +241,4 @@ function main() { validateCurrentLine("Release"); } -function validateLegacyLine() { - console.log("▶ Validating legacy compatibility line (v1.0.0)."); - const legacyCards = collectJsonFiles("agents/v1.0.0"); - for (const file of legacyCards) validateCard(file); - if (process.exitCode) process.exit(process.exitCode); - console.log("✅ Legacy validation completed successfully."); -} - -const mode = getMode(); - -function main() { - if (mode === "legacy") { - validateLegacyLine(); - return; - } - validateCurrentLine(); -} - main();