provenance-protocol 0.2.1 → 0.3.0

package/README.md

@@ -30,11 +30,23 @@ const result = await verifyDeclaration(YAML.parse(fileContents), {
 });
 
 result.valid        // the signature verifies against the key in the file
+result.coverage     // 'declaration' (0.2) | 'identity' (0.1)
 result.location     // 'match' | 'mismatch' | 'unchecked'
 result.trustworthy  // valid AND served from the location it claims
 result.fingerprint  // SHA-256 of the key — store it to detect rotation
 ```
 
+`coverage` matters. Under spec **0.2** the signature covers the whole
+declaration, so deleting a constraint breaks it. Under **0.1** it covered only
+the identity and key — the declared capabilities and constraints were *not*
+protected, and a valid 0.1 signature says nothing about whether they were
+edited. Sign new declarations with 0.2:
+
+```js
+import { signDeclaration } from 'provenance-protocol/keygen';
+declaration.identity.signature = signDeclaration(privateKey, declaration);
+```
+
 A valid signature proves the declaration came from the holder of that private
 key and has not been altered. It does **not** prove who that holder is, that
 the declared capabilities are accurate, or that the declaration is current.
@@ -264,11 +276,11 @@ await fetch('https://getprovenance.dev/api/agents/revoke', {
 ## CLI
 
 ```bash
-npx provenance keygen
-npx provenance register --id provenance:github:your-org/your-agent --url https://github.com/...
-npx provenance status provenance:github:alice/my-agent
-npx provenance validate PROVENANCE.yml
-npx provenance revoke --id provenance:github:your-org/your-agent
+npx provenance-protocol keygen
+npx provenance-protocol register --id provenance:github:your-org/your-agent --url https://github.com/...
+npx provenance-protocol status provenance:github:alice/my-agent
+npx provenance-protocol validate PROVENANCE.yml
+npx provenance-protocol revoke --id provenance:github:your-org/your-agent
 ```
 
 Full CLI reference: [getprovenance.dev/docs#cli](https://getprovenance.dev/docs#cli)

package/SPEC.md

@@ -1,5 +1,5 @@
 # Provenance Protocol Specification
-**Version 0.1**
+**Versions 0.1 and 0.2**
 
 ---
 
@@ -299,7 +299,7 @@ identity:
 ```
 
 `public_key` is required when `identity` is present. `algorithm` is optional
-and defaults to `ed25519`; no other value is valid in v0.1.
+and defaults to `ed25519`; no other value is valid.
 
 `signature` is optional, and its presence changes what the block means:
 
@@ -315,7 +315,35 @@ Prefer the signed form wherever the agent has a public location. A verifier
 that finds a key with no signature has learned which key to challenge, and
 nothing about whether the file has been altered.
 
-### What gets signed
+### What gets signed — and this differs by version
+
+The `provenance` field selects the rule. A verifier MUST use the rule for the
+version the declaration declares, and MUST refuse to guess for a version it does
+not know.
+
+#### 0.2 — the whole declaration (use this)
+
+The signed message is the UTF-8 encoding of:
+
+```
+provenance-declaration-v1:<canonical JSON of the declaration>
+```
+
+The canonical JSON is produced from the **parsed** declaration, with
+`identity.signature` removed — it cannot cover itself — and with object keys
+sorted by Unicode code point recursively and no insignificant whitespace.
+
+Because canonicalisation applies to the parsed value rather than the file's
+bytes, comments, indentation, quoting style and key order do not affect the
+signature. A declaration can be reformatted without re-signing. Only JSON
+representable values may be signed; a parser that yields dates or other
+non-plain objects must be made to yield strings instead.
+
+Every field is covered, so deleting a constraint or adding a capability breaks
+the signature. `provenance_id` is not required to verify a 0.2 signature, though
+the location check still needs it.
+
+#### 0.1 — the identity only (legacy)
 
 The signed message is the UTF-8 encoding of:
 
@@ -323,12 +351,18 @@ The signed message is the UTF-8 encoding of:
 <provenance_id>:<public_key>
 ```
 
-where `<public_key>` is the same base64 string that appears in
-`identity.public_key`. Concatenating the two binds the key to the identity,
-so a key lifted from one declaration cannot be replayed under a different
-`provenance_id`.
+This binds the key to the identity, so a key lifted from one declaration cannot
+be replayed under a different `provenance_id`, and it requires `provenance_id`
+to be present.
 
-Signing a declaration therefore requires `provenance_id` to be present.
+**It does not cover any other field.** A 0.1 declaration's capabilities and
+constraints are not protected by its signature: someone with write access to the
+location can delete a declared constraint and the signature still verifies.
+Location and write access are the only controls there.
+
+0.1 declarations remain readable and verifiable — nothing published stops
+working — but new declarations SHOULD use 0.2, and a verifier SHOULD report
+which coverage it checked so a reader is not misled about what was proven.
 
 ### How to verify
 
@@ -344,10 +378,12 @@ anyone.
 
 ### What verification proves — and what it does not
 
-A valid signature proves:
+A valid signature proves the declaration was produced by the holder of that
+private key, and:
 
-- the declaration was produced by the holder of that private key, and
-- not one byte of `provenance_id` or `public_key` has changed since.
+- under **0.2**, that no field of the declaration has changed since;
+- under **0.1**, only that `provenance_id` and `public_key` have not changed —
+  everything else is unprotected.
 
 A valid signature does **not** prove:
 
@@ -405,19 +441,25 @@ they would re-check any other freshness signal.
 
 An implementation of this specification is conformant if it:
 
-1. Accepts every file that validates against `schema/provenance-0.1.json`.
+1. Accepts every file that validates against the schema for its declared
+   version — `schema/provenance-0.1.json` or `schema/provenance-0.2.json`.
 2. Treats `provenance`, `name` and `description` as required and everything
    else as optional.
 3. Ignores unrecognised top-level fields rather than rejecting the file.
    Future spec versions add fields; a `0.1` reader must not break on them.
 4. Treats `identity.signature` as optional, and an unsigned `identity`
    block as advertising a key rather than attesting the file.
-5. Reproduces every signature in `test-vectors/signatures-0.1.json` marked
-   `valid`, and refuses every one marked `invalid`.
-6. Treats a declaration whose `provenance_id` does not match its retrieval
+5. Applies the signing rule for the version the declaration declares, refuses
+   to guess for an unknown version, and reports which coverage it checked —
+   a reader must not be left thinking a 0.1 signature protected the
+   declared constraints.
+6. Reproduces every signature in `test-vectors/signatures-0.1.json` and every
+   declaration in `test-vectors/declarations-0.2.json` marked `valid`, and
+   refuses every one marked `invalid`.
+7. Treats a declaration whose `provenance_id` does not match its retrieval
    location as unverified.
 
-Points 5 and 6 are what make independent implementations agree. An
+Points 6 and 7 are what make independent implementations agree. An
 implementation that passes the test vectors interoperates with every other
 one that does, with no reference to any particular service.
 
@@ -442,10 +484,22 @@ monitors, attesters — are applications of the standard, not part of it.
 
 ## Versioning
 
-The `provenance` field records which spec version you are using.
-We commit to backwards compatibility — a `0.1` file will always be
-readable regardless of future spec versions.
-New versions add fields. Existing fields are never removed.
+The `provenance` field records which spec version you are using, and it is what
+a reader uses to decide how to interpret the file.
+
+We commit to backwards compatibility: a `0.1` file will always be readable and
+verifiable, whatever later versions say. Fields are never removed.
+
+Usually a new version only adds fields. Version 0.2 is the exception so far — it
+changed what an existing field *covers*, because `identity.signature` in 0.1
+protected only the identity and left the declared capabilities and constraints
+unprotected, which was weaker than readers assumed. Rather than redefine 0.1
+under declarations already published, 0.2 defines the stronger rule and the
+`provenance` field keeps the two apart. A verifier implements both and applies
+the one the declaration asks for.
+
+Where a version changes the meaning of an existing field, it will always do so
+by declaring a new version, never by reinterpreting an old one.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "provenance-protocol",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The Provenance Protocol \u2014 open standard for AI agent identity \u2014 and its reference SDK",
   "type": "module",
   "main": "./src/index.js",
@@ -33,7 +33,9 @@
     "README.md",
     "SPEC.md",
     "schema/provenance-0.1.json",
-    "test-vectors/"
+    "test-vectors/",
+    "src/canonical.js",
+    "schema/provenance-0.2.json"
   ],
   "keywords": [
     "ai-agent",
@@ -56,6 +58,6 @@
     "node": ">=14.0.0"
   },
   "scripts": {
-    "test": "node test/verify.test.mjs"
+    "test": "node test/verify.test.mjs && node test/declaration-signature.test.mjs"
   }
 }

package/schema/provenance-0.1.json

@@ -187,7 +187,7 @@
         },
         "signature": {
           "type": "string",
-          "description": "Base64 Ed25519 signature of '<provenance_id>:<public_key>' \u2014 proves you control the private key and that the declaration is unaltered. Optional: omit it when the key is published only for live challenge-response. Requires provenance_id."
+          "description": "Base64 Ed25519 signature of '<provenance_id>:<public_key>' \u2014 proves you control the private key under that identity. NOTE: in 0.1 it does NOT cover the rest of the declaration, so capabilities and constraints are not protected by it; spec 0.2 signs the whole declaration. Optional: omit it when the key is published only for live challenge-response. Requires provenance_id."
         },
         "algorithm": {
           "type": "string",

package/schema/provenance-0.2.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://getprovenance.dev/schema/0.2.json",
+  "title": "PROVENANCE.yml",
+  "description": "Provenance Protocol v0.2 schema for AI agent identity files",
+  "type": "object",
+  "required": [
+    "provenance",
+    "name",
+    "description"
+  ],
+  "properties": {
+    "provenance": {
+      "type": "string",
+      "description": "Spec version. 0.2 signs the whole declaration.",
+      "enum": [
+        "0.2"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable name for this agent",
+      "minLength": 1,
+      "maxLength": 100
+    },
+    "description": {
+      "type": "string",
+      "description": "What this agent does, in plain language",
+      "minLength": 1,
+      "maxLength": 1000
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version of the agent",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+.*$"
+    },
+    "model": {
+      "type": "object",
+      "description": "The LLM powering this agent",
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": [
+            "anthropic",
+            "openai",
+            "google",
+            "mistral",
+            "meta",
+            "local",
+            "other"
+          ],
+          "description": "LLM provider"
+        },
+        "model_id": {
+          "type": "string",
+          "description": "Specific model ID e.g. claude-sonnet-4-5"
+        }
+      },
+      "additionalProperties": false
+    },
+    "capabilities": {
+      "type": "array",
+      "description": "What this agent can do \u2014 standard vocabulary or domain:custom",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_-]*(:[a-z0-9_:-]+)?$"
+      },
+      "uniqueItems": true
+    },
+    "constraints": {
+      "type": "array",
+      "description": "Public commitments \u2014 what this agent will NEVER do",
+      "items": {
+        "type": "string",
+        "pattern": "^no:[a-z0-9_:-]+$"
+      },
+      "uniqueItems": true
+    },
+    "delegates": {
+      "type": "array",
+      "description": "Sub-agents this orchestrator spawns \u2014 required if delegate:agents capability declared",
+      "items": {
+        "type": "object",
+        "required": [
+          "provenance_id"
+        ],
+        "properties": {
+          "provenance_id": {
+            "type": "string",
+            "pattern": "^provenance:(github|npm|pypi|huggingface|clawmarket):.+$"
+          },
+          "purpose": {
+            "type": "string",
+            "maxLength": 200
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "skills": {
+      "type": "array",
+      "description": "External skills this agent depends on",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "source"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string",
+            "enum": [
+              "skillsmp",
+              "github",
+              "npm",
+              "custom"
+            ]
+          },
+          "url": {
+            "type": "string",
+            "format": "uri"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "description": "How this agent runs",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "task",
+            "persistent",
+            "scheduled"
+          ],
+          "description": "task: runs to completion | persistent: always on | scheduled: cron-like"
+        },
+        "trigger": {
+          "type": "string",
+          "enum": [
+            "api",
+            "webhook",
+            "schedule",
+            "event"
+          ],
+          "description": "What starts this agent"
+        }
+      },
+      "additionalProperties": false
+    },
+    "contact": {
+      "type": "object",
+      "description": "Who is responsible for this agent",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "email": {
+          "type": "string",
+          "format": "email"
+        }
+      },
+      "additionalProperties": false
+    },
+    "provenance_id": {
+      "type": "string",
+      "description": "Your Provenance identifier \u2014 links this file to your index entry",
+      "pattern": "^provenance:(github|npm|pypi|huggingface|clawmarket):.+$"
+    },
+    "identity": {
+      "type": "object",
+      "description": "Cryptographic identity. public_key alone advertises the key an agent will use to prove control live. Adding signature makes the entire declaration tamper-evident.",
+      "properties": {
+        "public_key": {
+          "type": "string",
+          "description": "Base64-encoded Ed25519 SPKI DER public key. Generate with: generateProvenanceKeyPair() from provenance-protocol/keygen"
+        },
+        "signature": {
+          "type": "string",
+          "description": "Base64 Ed25519 signature over 'provenance-declaration-v1:' followed by the canonical JSON of this parsed declaration with identity.signature removed. Covers every field, so editing capabilities or deleting a constraint breaks it. Generate with signDeclaration() from provenance-protocol/keygen. Optional: omit when the key is published only for live challenge-response."
+        },
+        "algorithm": {
+          "type": "string",
+          "enum": [
+            "ed25519"
+          ],
+          "description": "Signing algorithm. Always ed25519."
+        }
+      },
+      "required": [
+        "public_key"
+      ],
+      "additionalProperties": false
+    },
+    "ajp": {
+      "type": "object",
+      "description": "Agent Job Protocol endpoint \u2014 enables agent-to-agent job delegation",
+      "properties": {
+        "endpoint": {
+          "type": "string",
+          "format": "uri",
+          "description": "Base URL for your AJP implementation. Must accept POST /jobs, GET /jobs/:id, POST /jobs/:id/ack"
+        },
+        "version": {
+          "type": "string",
+          "enum": [
+            "0.1"
+          ],
+          "description": "AJP spec version"
+        }
+      },
+      "required": [
+        "endpoint"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/src/canonical.js

@@ -0,0 +1,98 @@
+/**
+ * provenance-protocol — canonical form for signing declarations
+ *
+ * Spec 0.1 signed only "<provenance_id>:<public_key>", so a signature proved
+ * key control but left the rest of the declaration unprotected: a constraint
+ * could be deleted and the signature would still verify. Spec 0.2 signs the
+ * whole declaration, which needs one canonical serialisation that every
+ * implementation agrees on byte for byte.
+ *
+ * Canonicalisation applies to the PARSED value, not the file's bytes. Comments,
+ * indentation, quoting style and key order therefore do not affect the
+ * signature — a declaration can be reformatted without re-signing, which is
+ * what anyone would expect.
+ *
+ * Rules:
+ *   - object keys sorted by Unicode code point, recursively
+ *   - no insignificant whitespace
+ *   - `identity.signature` removed before signing (it cannot cover itself)
+ *   - only JSON-representable values; anything else throws rather than being
+ *     silently coerced into an ambiguous signature
+ */
+
+const DOMAIN = 'provenance-declaration-v1';
+
+/** Thrown when a declaration contains something that cannot be canonicalised. */
+export class CanonicalError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CanonicalError';
+  }
+}
+
+function canonicalValue(value, path = '$') {
+  if (value === null) return 'null';
+
+  const type = typeof value;
+
+  if (type === 'string') return JSON.stringify(value);
+  if (type === 'boolean') return value ? 'true' : 'false';
+  if (type === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new CanonicalError(`${path}: non-finite numbers cannot be signed`);
+    }
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((item, i) => canonicalValue(item, `${path}[${i}]`)).join(',')}]`;
+  }
+
+  if (type === 'object') {
+    // A YAML parser may produce Dates, Maps, Buffers and so on. Signing those
+    // would depend on whichever serialisation happened to be used, so refuse.
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+      throw new CanonicalError(
+        `${path}: only plain objects can be signed (got ${value.constructor?.name ?? 'unknown type'}) — quote the value as a string`
+      );
+    }
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
+    const parts = keys.map(
+      (k) => `${JSON.stringify(k)}:${canonicalValue(value[k], `${path}.${k}`)}`
+    );
+    return `{${parts.join(',')}}`;
+  }
+
+  throw new CanonicalError(`${path}: values of type ${type} cannot be signed`);
+}
+
+/**
+ * The exact string a spec-0.2 declaration signature is computed over.
+ *
+ * Domain-separated so a declaration signature can never be replayed as a
+ * signature over some other kind of message.
+ *
+ * @param {object} declaration  Parsed declaration (its identity.signature is ignored)
+ * @returns {string}
+ */
+export function declarationSigningPayload(declaration) {
+  if (declaration === null || typeof declaration !== 'object' || Array.isArray(declaration)) {
+    throw new CanonicalError('Declaration must be a parsed object');
+  }
+
+  const { identity, ...rest } = declaration;
+  const covered = { ...rest };
+
+  if (identity !== undefined) {
+    if (identity === null || typeof identity !== 'object' || Array.isArray(identity)) {
+      throw new CanonicalError('$.identity must be an object when present');
+    }
+    // public_key and algorithm ARE covered; only the signature is excluded.
+    const { signature: _excluded, ...identityRest } = identity;
+    covered.identity = identityRest;
+  }
+
+  return `${DOMAIN}:${canonicalValue(covered)}`;
+}
+
+export { DOMAIN as DECLARATION_SIGNING_DOMAIN };