provenance-protocol 0.2.2 → 0.4.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.

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:
 
@@ -372,27 +408,49 @@ This is the same division of labour as a machine-readable passport: the
 document proves its own integrity offline, while identity binding and
 current standing are looked up.
 
+### Every signed payload is domain-separated
+
+An agent's key signs several different things. Each payload MUST carry the
+prefix for its purpose, so that a signature obtained for one purpose can never
+be presented as another:
+
+| Purpose | Signed payload |
+|---|---|
+| Declaration (0.2) | `provenance-declaration-v1:<canonical JSON>` |
+| Live proof of key control | `provenance-challenge-v1:<provenance_id>:<nonce>` |
+| Revocation | `provenance-revocation-v1:<provenance_id>` |
+
+This is not a precaution against something hypothetical. In 0.1 a challenge was
+signed as `<provenance_id>:<nonce>` and a revocation as
+`<provenance_id>:REVOKE` — **the same payload with a chosen nonce.** Any
+publicly reachable endpoint that signs a caller-supplied nonce in the 0.1 form
+therefore hands out valid revocation signatures for its own key, and a stranger
+can revoke the agent. Supplying the public key as the nonce likewise reproduces
+the 0.1 declaration signature.
+
+An endpoint that signs a caller-supplied value MUST use the separated challenge
+form, and MUST NOT sign the 0.1 payload. Verifiers SHOULD require the separated
+form from any agent that exposes a public challenge endpoint.
+
+The 0.1 payloads remain defined so existing deployments keep working, but they
+are unsafe to expose and are superseded.
+
 ### Live proof of key control
 
 A signature on a file proves the file's origin. It does not prove that the
-agent running right now controls that key. For that, a receiving system
-issues a nonce and the agent returns a signature over:
-
-```
-<provenance_id>:<nonce>
-```
+agent running right now controls that key. For that, a receiving system issues
+a nonce and the agent returns a signature over
+`provenance-challenge-v1:<provenance_id>:<nonce>`.
 
-Nonces must be single-use and unpredictable. The receiving system verifies
-the signature against the public key it already holds for that
-`provenance_id`.
+Nonces must be single-use and unpredictable. The receiving system verifies the
+signature against the public key it already holds for that `provenance_id`.
 
 ### Revocation
 
-A key holder revokes a `provenance_id` by signing:
-
-```
-<provenance_id>:REVOKE
-```
+A key holder revokes a `provenance_id` by signing
+`provenance-revocation-v1:<provenance_id>`. The payload contains no
+caller-supplied input, so it cannot be produced by a challenge endpoint however
+that endpoint is called.
 
 Revocation is the one operation that cannot be verified offline — a verifier
 has no way to know a revocation has been issued without asking. Implementations
@@ -405,19 +463,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 +506,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.2",
+  "version": "0.4.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 && node test/payload-separation.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,134 @@
+/**
+ * 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
+ */
+
+/** Thrown when a declaration contains something that cannot be canonicalised. */
+export class CanonicalError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CanonicalError';
+  }
+}
+
+const DOMAIN = 'provenance-declaration-v1';
+
+/**
+ * Every distinct thing an agent key signs gets its own prefix, so a signature
+ * obtained for one purpose can never be presented as another.
+ *
+ * This is not theoretical. Spec 0.1 signed a challenge as "<id>:<nonce>" and a
+ * revocation as "<id>:REVOKE" — the same payload with a chosen nonce. Any
+ * publicly reachable endpoint that signs a caller-supplied nonce therefore
+ * hands out valid revocation signatures for its own key, letting a stranger
+ * revoke the agent. A key lifted into the nonce likewise reproduces the 0.1
+ * declaration payload.
+ *
+ * The separated forms below cannot be confused with each other whatever the
+ * caller supplies.
+ */
+export const CHALLENGE_DOMAIN = 'provenance-challenge-v1';
+export const REVOCATION_DOMAIN = 'provenance-revocation-v1';
+
+/** Payload for proving live control of a key. Nonce must be single-use. */
+export function challengePayload(provenanceId, nonce) {
+  if (typeof provenanceId !== 'string' || provenanceId.length === 0) {
+    throw new CanonicalError('provenanceId is required');
+  }
+  if (typeof nonce !== 'string' || nonce.length === 0) {
+    throw new CanonicalError('nonce is required');
+  }
+  return `${CHALLENGE_DOMAIN}:${provenanceId}:${nonce}`;
+}
+
+/** Payload for revoking a provenance id. Carries no caller-supplied input. */
+export function revocationPayload(provenanceId) {
+  if (typeof provenanceId !== 'string' || provenanceId.length === 0) {
+    throw new CanonicalError('provenanceId is required');
+  }
+  return `${REVOCATION_DOMAIN}:${provenanceId}`;
+}
+
+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 };

package/src/keygen.d.ts

@@ -46,3 +46,30 @@ export function signForProvenance(privateKeyBase64: string, provenanceId: string
  * Send the result as signed_challenge to POST /api/agents/revoke.
  */
 export function signRevocation(privateKeyBase64: string, provenanceId: string): string;
+
+/**
+ * Sign a whole declaration — spec 0.2.
+ *
+ * Covers every field, so deleting a constraint or adding a capability breaks the
+ * signature. `signForProvenance` (spec 0.1) covers only the identity and key.
+ *
+ * Signs the canonical form of the PARSED declaration, so reformatting the file
+ * does not invalidate the signature.
+ *
+ * @param privateKeyBase64  Your PROVENANCE_PRIVATE_KEY (base64 PKCS8 DER)
+ * @param declaration       Parsed declaration; identity.signature is ignored
+ * @returns Base64 signature — put it in identity.signature
+ */
+export function signDeclaration(privateKeyBase64: string, declaration: object): string;
+
+/**
+ * Prove live control of a key against a nonce — domain-separated form.
+ *
+ * Use this for any endpoint a stranger can call. The legacy `signChallenge`
+ * signs the same payload shape as a revocation, so exposing that publicly lets
+ * a caller obtain a valid revocation signature for your own key.
+ */
+export function signAgentChallenge(privateKeyBase64: string, provenanceId: string, nonce: string): string;
+
+/** Revoke a provenance id — domain-separated form. Takes no caller-supplied input. */
+export function signAgentRevocation(privateKeyBase64: string, provenanceId: string): string;

package/src/keygen.js

@@ -25,6 +25,7 @@
  */
 
 import { generateKeyPairSync, sign, createPrivateKey } from 'crypto';
+import { declarationSigningPayload, challengePayload, revocationPayload } from './canonical.js';
 
 /**
  * Generate a new Ed25519 keypair for use with Provenance identity.
@@ -57,7 +58,12 @@ export function generateProvenanceKeyPair() {
 }
 
 /**
- * Sign a challenge from a receiving system.
+ * Sign a challenge from a receiving system — LEGACY, spec 0.1 form.
+ *
+ * Signs "<provenanceId>:<nonce>", which is indistinguishable from a revocation
+ * when the nonce is "REVOKE". NEVER expose an endpoint that calls this with a
+ * caller-supplied nonce: a stranger can use it to revoke your key. Use
+ * `signAgentChallenge` instead.
  *
  * Call this when a receiving system sends you a nonce to prove your identity.
  * The signed message is always `${provenanceId}:${nonce}` — this binds the
@@ -134,6 +140,68 @@ export function signRevocation(privateKeyBase64, provenanceId) {
   return signChallenge(privateKeyBase64, provenanceId, 'REVOKE');
 }
 
+/**
+ * Sign a whole declaration — spec 0.2.
+ *
+ * Covers every field, so deleting a constraint or adding a capability breaks
+ * the signature. `signForProvenance` (spec 0.1) covers only the identity and
+ * key, which leaves the rest of the declaration unprotected; prefer this.
+ *
+ * Signs the canonical form of the PARSED declaration, so reformatting the file
+ * does not invalidate the signature.
+ *
+ * @param {string} privateKeyBase64  Base64 PKCS8 DER private key
+ * @param {object} declaration       Parsed declaration; identity.signature is ignored
+ * @returns {string}                 Base64 signature — put it in identity.signature
+ */
+function _sign(privateKeyBase64, message) {
+  const privateKey = createPrivateKey({
+    key: Buffer.from(privateKeyBase64, 'base64'),
+    format: 'der',
+    type: 'pkcs8',
+  });
+  return sign(null, Buffer.from(message, 'utf8'), privateKey).toString('base64');
+}
+
+/**
+ * Prove live control of a key against a nonce — domain-separated form.
+ *
+ * Use this for any endpoint a stranger can call. The legacy `signChallenge`
+ * signs "<provenanceId>:<nonce>", which is the same shape as a revocation with
+ * nonce "REVOKE" — so exposing that publicly lets a caller obtain a valid
+ * revocation signature for your own key and revoke you. This form cannot be
+ * confused with a revocation or a declaration whatever nonce is supplied.
+ *
+ * @param {string} privateKeyBase64
+ * @param {string} provenanceId
+ * @param {string} nonce            Single-use and unpredictable
+ * @returns {string}                Base64 signature
+ */
+export function signAgentChallenge(privateKeyBase64, provenanceId, nonce) {
+  return _sign(privateKeyBase64, challengePayload(provenanceId, nonce));
+}
+
+/**
+ * Revoke a provenance id — domain-separated form.
+ *
+ * Takes no caller-supplied input, so it cannot be produced by a challenge
+ * endpoint however it is called.
+ *
+ * @param {string} privateKeyBase64
+ * @param {string} provenanceId
+ * @returns {string}                Base64 signature
+ */
+export function signAgentRevocation(privateKeyBase64, provenanceId) {
+  return _sign(privateKeyBase64, revocationPayload(provenanceId));
+}
+
+export function signDeclaration(privateKeyBase64, declaration) {
+  const keyBuffer = Buffer.from(privateKeyBase64, 'base64');
+  const privateKey = createPrivateKey({ key: keyBuffer, format: 'der', type: 'pkcs8' });
+  const message = Buffer.from(declarationSigningPayload(declaration), 'utf8');
+  return sign(null, message, privateKey).toString('base64');
+}
+
 export function signForProvenance(privateKeyBase64, provenanceId, publicKeyBase64) {
   const keyBuffer = Buffer.from(privateKeyBase64, 'base64');
   const privateKey = createPrivateKey({ key: keyBuffer, format: 'der', type: 'pkcs8' });

package/src/verify.d.ts

@@ -8,6 +8,9 @@
 /** Whether a declaration was served from the location its provenance_id names. */
 export type LocationCheck = 'match' | 'mismatch' | 'unchecked';
 
+/** What a signature was found to cover, per the declaration's spec version. */
+export type SignatureCoverage = 'declaration' | 'identity';
+
 export interface VerificationResult {
   /** An identity.signature was present to check. */
   signed: boolean;
@@ -20,6 +23,13 @@ export interface VerificationResult {
   /** SHA-256 of the public key, hex. Store it to detect key rotation. */
   fingerprint: string | null;
   location: LocationCheck;
+  /**
+   * 'declaration' (spec 0.2) — every field is covered; any edit breaks it.
+   * 'identity' (spec 0.1) — only the identity and key are covered, so the
+   * declared capabilities and constraints are NOT protected by the signature.
+   * null when no signature was checked.
+   */
+  coverage: SignatureCoverage | null;
   /**
    * Signature valid AND retrieval location confirmed. Only both together
    * justify treating the declaration as the named project owner's.
@@ -83,3 +93,16 @@ export function verifyRevocation(
   provenanceId: string,
   signatureBase64: string
 ): Promise<boolean>;
+
+/**
+ * Verify a live challenge response — domain-separated form. Prefer this over
+ * `verifyChallenge`, whose payload is indistinguishable from a revocation.
+ */
+export function verifyAgentChallenge(
+  publicKeyBase64: string, provenanceId: string, nonce: string, signatureBase64: string
+): Promise<boolean>;
+
+/** Verify a revocation — domain-separated form. */
+export function verifyAgentRevocation(
+  publicKeyBase64: string, provenanceId: string, signatureBase64: string
+): Promise<boolean>;

package/src/verify.js

@@ -16,9 +16,23 @@
  * Uses the Web Crypto API (crypto.subtle): all modern browsers, Node 18+.
  */
 
-/** Signature algorithm for spec v0.1. No other value is valid. */
+import { declarationSigningPayload, challengePayload, revocationPayload } from './canonical.js';
+
+/** Signature algorithm. Ed25519 in every spec version so far. */
 const ALGORITHM = 'ed25519';
 
+/**
+ * Which spec versions this module knows how to verify a signature for, and what
+ * the signature covers in each.
+ *
+ *   0.1 — signs "<provenance_id>:<public_key>". Proves key control under that
+ *         identity. Does NOT cover the rest of the declaration: a constraint can
+ *         be deleted and the signature still verifies.
+ *   0.2 — signs the canonical form of the whole declaration. Any change to any
+ *         field breaks it.
+ */
+const SIGNATURE_COVERAGE = { '0.1': 'identity', '0.2': 'declaration' };
+
 function subtle() {
   const s = globalThis.crypto?.subtle;
   if (!s) throw new Error('Web Crypto API (crypto.subtle) not available');
@@ -142,10 +156,14 @@ export function checkLocation(provenanceId, retrievedFrom) {
  * when `retrievedFrom` is given — whether the file was served from the
  * location it claims.
  *
- * A valid signature proves the declaration was produced by 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. Revocation and standing cannot be checked offline.
+ * What a valid signature proves depends on the spec version, and `coverage`
+ * reports which: 'declaration' (0.2) means every field is covered, so any edit
+ * breaks it; 'identity' (0.1) means only the identity and key are covered, so
+ * the declared capabilities and constraints are NOT protected by it.
+ *
+ * In neither case does a signature prove who the key holder is, that the
+ * declared capabilities are accurate, or that the declaration is current.
+ * Revocation and standing cannot be checked offline.
  *
  * @param {object} declaration  Parsed PROVENANCE.yml
  * @param {object} [options]
@@ -158,6 +176,7 @@ export function checkLocation(provenanceId, retrievedFrom) {
  *   publicKey: string | null,
  *   fingerprint: string | null,
  *   location: 'match' | 'mismatch' | 'unchecked',
+ *   coverage: 'declaration' | 'identity' | null,
  *   trustworthy: boolean
  * }>}
  */
@@ -170,6 +189,7 @@ export async function verifyDeclaration(declaration, options = {}) {
     publicKey: null,
     fingerprint: null,
     location: 'unchecked',
+    coverage: null,
     trustworthy: false,
   };
 
@@ -213,13 +233,39 @@ export async function verifyDeclaration(declaration, options = {}) {
   }
   result.signed = true;
 
-  if (!provenanceId) {
-    return { ...result, reason: 'provenance_id is required to verify a signature' };
+  const declaredVersion = typeof declaration.provenance === 'string' ? declaration.provenance : '0.1';
+  if (!provenanceId && declaredVersion === '0.1') {
+    // The 0.1 payload is built from provenance_id, so without it there is
+    // nothing to verify. A 0.2 signature covers the whole declaration and does
+    // not need it (though the location check still does).
+    return { ...result, reason: 'provenance_id is required to verify a 0.1 signature' };
+  }
+
+  // What the signature covers depends on the spec version the declaration
+  // declares, so the payload is built differently for each.
+  const specVersion = typeof declaration.provenance === 'string' ? declaration.provenance : '0.1';
+  const coverage = SIGNATURE_COVERAGE[specVersion];
+  if (!coverage) {
+    return {
+      ...result,
+      reason: `Spec version ${specVersion} is not known to this verifier — cannot check its signature`,
+    };
+  }
+  result.coverage = coverage;
+
+  let payload;
+  try {
+    payload =
+      coverage === 'declaration'
+        ? declarationSigningPayload(declaration)
+        : `${provenanceId}:${publicKey}`;
+  } catch (e) {
+    return { ...result, reason: `Declaration cannot be canonicalised: ${e.message}` };
   }
 
   let valid;
   try {
-    valid = await verifyEd25519(publicKey, signature, `${provenanceId}:${publicKey}`);
+    valid = await verifyEd25519(publicKey, signature, payload);
   } catch {
     return { ...result, reason: 'identity.signature is malformed' };
   }
@@ -236,9 +282,53 @@ export async function verifyDeclaration(declaration, options = {}) {
   };
 }
 
+/**
+ * Verify a live challenge response — domain-separated form.
+ *
+ * Pair with `signAgentChallenge`. Prefer this over `verifyChallenge`: the legacy
+ * payload is the same shape as a revocation, so any public endpoint signing it
+ * is a way to revoke the agent's own key.
+ *
+ * @param {string} publicKeyBase64
+ * @param {string} provenanceId
+ * @param {string} nonce            Single-use, unpredictable
+ * @param {string} signatureBase64
+ * @returns {Promise<boolean>}
+ */
+export async function verifyAgentChallenge(publicKeyBase64, provenanceId, nonce, signatureBase64) {
+  try {
+    return await verifyEd25519(publicKeyBase64, signatureBase64, challengePayload(provenanceId, nonce));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify a revocation — domain-separated form.
+ *
+ * Confirms it came from the key holder. It does not tell you whether a
+ * revocation exists; that requires asking an index.
+ *
+ * @param {string} publicKeyBase64
+ * @param {string} provenanceId
+ * @param {string} signatureBase64
+ * @returns {Promise<boolean>}
+ */
+export async function verifyAgentRevocation(publicKeyBase64, provenanceId, signatureBase64) {
+  try {
+    return await verifyEd25519(publicKeyBase64, signatureBase64, revocationPayload(provenanceId));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Verify a live challenge response offline, against a key you already hold.
  *
+ * LEGACY (spec 0.1 payload). Accepts "<provenanceId>:<nonce>", which is the same
+ * shape as a revocation with nonce "REVOKE" — so never verify against a peer
+ * that exposes this form publicly. Use `verifyAgentChallenge`.
+ *
  * The network equivalent in the main SDK looks the key up in the index; this
  * takes the key directly, so a system that already stores keys can verify
  * without contacting anyone.

package/test-vectors/declarations-0.2.json

@@ -0,0 +1,217 @@
+{
+  "$comment": "Normative test vectors for Provenance Protocol v0.2 declaration signatures. The signature covers the canonical form of the entire parsed declaration, excluding identity.signature itself.",
+  "spec_version": "0.2",
+  "algorithm": "ed25519",
+  "signing": {
+    "payload": "the string \"provenance-declaration-v1:\" followed by the canonical JSON of the parsed declaration with identity.signature removed",
+    "canonicalisation": "object keys sorted by code point recursively, no insignificant whitespace, applied to the PARSED value so formatting and key order do not matter"
+  },
+  "keypair": {
+    "public_key": "MCowBQYDK2VwAyEAyuDQn/j1dbeAd288fU7lRV5cFcm7Zsm42jwCKy07N98=",
+    "private_key": "MC4CAQAwBQYDK2VwBCIEICnsl5v8baf3DyJApejP5DG3cmx1xS4S5qewS1A28IMN",
+    "$comment": "Test key only. Never use in production."
+  },
+  "reference_payload": "provenance-declaration-v1:{\"capabilities\":[\"read:web\",\"write:summaries\"],\"constraints\":[\"no:pii\",\"no:financial:transact\"],\"description\":\"A bounded fixture declaration for the signing vectors.\",\"identity\":{\"algorithm\":\"ed25519\",\"public_key\":\"MCowBQYDK2VwAyEAyuDQn/j1dbeAd288fU7lRV5cFcm7Zsm42jwCKy07N98=\"},\"name\":\"Fixture Research Agent\",\"provenance\":\"0.2\",\"provenance_id\":\"provenance:github:example/research-agent\",\"version\":\"1.2.0\"}",
+  "vectors": [
+    {
+      "id": "declaration-signature-valid",
+      "expect": "valid",
+      "purpose": "a correctly signed 0.2 declaration",
+      "declaration": {
+        "provenance": "0.2",
+        "name": "Fixture Research Agent",
+        "description": "A bounded fixture declaration for the signing vectors.",
+        "version": "1.2.0",
+        "capabilities": [
+          "read:web",
+          "write:summaries"
+        ],
+        "constraints": [
+          "no:pii",
+          "no:financial:transact"
+        ],
+        "provenance_id": "provenance:github:example/research-agent",
+        "identity": {
+          "public_key": "MCowBQYDK2VwAyEAyuDQn/j1dbeAd288fU7lRV5cFcm7Zsm42jwCKy07N98=",
+          "algorithm": "ed25519",
+          "signature": "LqPe4bIXfa4qRhblNfp3VXElk2gG0x5UfTaHNKJGUDNbx4tRNXnJyXZZuu3BiC58Eur2JF719MieXU+EJe2pDg=="
+        }
+      }
+    },
+    {
+      "id": "declaration-key-order-irrelevant",
+      "expect": "valid",
+      "purpose": "the same declaration with keys in a different order must still verify",
+      "declaration": {
+        "identity": {
+          "signature": "LqPe4bIXfa4qRhblNfp3VXElk2gG0x5UfTaHNKJGUDNbx4tRNXnJyXZZuu3BiC58Eur2JF719MieXU+EJe2pDg==",
+          "algorithm": "ed25519",
+          "public_key": "MCowBQYDK2VwAyEAyuDQn/j1dbeAd288fU7lRV5cFcm7Zsm42jwCKy07N98="
+        },
+        "constraints": [
+          "no:pii",
+          "no:financial:transact"
+        ],
+        "capabilities": [
+          "read:web",
+          "write:summaries"
+        ],
+        "provenance_id": "provenance:github:example/research-agent",
+        "version": "1.2.0",
+        "description": "A bounded fixture declaration for the signing vectors.",
+        "name": "Fixture Research Agent",
+        "provenance": "0.2"
+      }
+    },
+    {
+      "id": "declaration-constraint-removed",
+      "expect": "invalid",
+      "purpose": "THE CASE 0.1 MISSED — deleting a declared constraint must break the signature",
+      "declaration": {
+        "provenance": "0.2",
+        "name": "Fixture Research Agent",
+        "description": "A bounded fixture declaration for the signing vectors.",
+        "version": "1.2.0",
+        "capabilities": [
+          "read:web",
+          "write:summaries"
+        ],
+        "constraints": [
+          "no:pii"
+        ],
+        "provenance_id": "provenance:github:example/research-agent",
+        "identity": {
+          "public_key": "MCowBQYDK2VwAyEAyuDQn/j1dbeAd288fU7lRV5cFcm7Zsm42jwCKy07N98=",
+          "algorithm": "ed25519",
+          "signature": "LqPe4bIXfa4qRhblNfp3VXElk2gG0x5UfTaHNKJGUDNbx4tRNXnJyXZZuu3BiC58Eur2JF719MieXU+EJe2pDg=="
+        }
+      }
+    },
+    {
+      "id": "declaration-capability-added",
+      "expect": "invalid",
+      "purpose": "granting the agent a new declared power must break the signature",
+      "declaration": {
+        "provenance": "0.2",
+        "name": "Fixture Research Agent",
+        "description": "A bounded fixture declaration for the signing vectors.",
+        "version": "1.2.0",
+        "capabilities": [
+          "read:web",
+          "write:summaries",
+          "financial:transact"
+        ],
+        "constraints": [
+          "no:pii",
+          "no:financial:transact"
+        ],
+        "provenance_id": "provenance:github:example/research-agent",
+        "identity": {
+          "public_key": "MCowBQYDK2VwAyEAyuDQn/j1dbeAd288fU7lRV5cFcm7Zsm42jwCKy07N98=",
+          "algorithm": "ed25519",
+          "signature": "LqPe4bIXfa4qRhblNfp3VXElk2gG0x5UfTaHNKJGUDNbx4tRNXnJyXZZuu3BiC58Eur2JF719MieXU+EJe2pDg=="
+        }
+      }
+    },
+    {
+      "id": "declaration-key-swapped",
+      "expect": "invalid",
+      "purpose": "substituting another public key must break the signature",
+      "declaration": {
+        "provenance": "0.2",
+        "name": "Fixture Research Agent",
+        "description": "A bounded fixture declaration for the signing vectors.",
+        "version": "1.2.0",
+        "capabilities": [
+          "read:web",
+          "write:summaries"
+        ],
+        "constraints": [
+          "no:pii",
+          "no:financial:transact"
+        ],
+        "provenance_id": "provenance:github:example/research-agent",
+        "identity": {
+          "public_key": "MCowBQYDK2VwAyEAiuHMTpGGFwJ8XGYRofeYY0s6rV1ywTl8nmLgHj08lew=",
+          "algorithm": "ed25519",
+          "signature": "LqPe4bIXfa4qRhblNfp3VXElk2gG0x5UfTaHNKJGUDNbx4tRNXnJyXZZuu3BiC58Eur2JF719MieXU+EJe2pDg=="
+        }
+      }
+    },
+    {
+      "id": "declaration-signed-with-wrong-key",
+      "expect": "invalid",
+      "purpose": "a signature made by a different private key must not verify",
+      "declaration": {
+        "provenance": "0.2",
+        "name": "Fixture Research Agent",
+        "description": "A bounded fixture declaration for the signing vectors.",
+        "version": "1.2.0",
+        "capabilities": [
+          "read:web",
+          "write:summaries"
+        ],
+        "constraints": [
+          "no:pii",
+          "no:financial:transact"
+        ],
+        "provenance_id": "provenance:github:example/research-agent",
+        "identity": {
+          "public_key": "MCowBQYDK2VwAyEAyuDQn/j1dbeAd288fU7lRV5cFcm7Zsm42jwCKy07N98=",
+          "algorithm": "ed25519",
+          "signature": "SgK3ou1XNPOTQDP+gbwvbHPcs8+21SQaxChiHT14c5mHvZ3XzNH8secDlS/fDkog7iBN0oKQrw5O7RjLr61LCw=="
+        }
+      }
+    },
+    {
+      "id": "declaration-0.1-signature-in-0.2-file",
+      "expect": "invalid",
+      "purpose": "an old identity-only signature must not satisfy 0.2",
+      "declaration": {
+        "provenance": "0.2",
+        "name": "Fixture Research Agent",
+        "description": "A bounded fixture declaration for the signing vectors.",
+        "version": "1.2.0",
+        "capabilities": [
+          "read:web",
+          "write:summaries"
+        ],
+        "constraints": [
+          "no:pii",
+          "no:financial:transact"
+        ],
+        "provenance_id": "provenance:github:example/research-agent",
+        "identity": {
+          "public_key": "MCowBQYDK2VwAyEAyuDQn/j1dbeAd288fU7lRV5cFcm7Zsm42jwCKy07N98=",
+          "algorithm": "ed25519",
+          "signature": "d4/wFYKJD8AQlKVDnC+JloeW7EnYUZ1pJoSG+HkM2wH/KMKYm8Dc6bdnCCNjtEIB/EiDei4+45DMdODPd9F0Cg=="
+        }
+      }
+    },
+    {
+      "id": "declaration-unknown-spec-version",
+      "expect": "invalid",
+      "purpose": "a verifier must refuse to guess the signing rule for a version it does not know",
+      "declaration": {
+        "provenance": "9.9",
+        "name": "Fixture Research Agent",
+        "description": "A bounded fixture declaration for the signing vectors.",
+        "version": "1.2.0",
+        "capabilities": [
+          "read:web",
+          "write:summaries"
+        ],
+        "constraints": [
+          "no:pii",
+          "no:financial:transact"
+        ],
+        "provenance_id": "provenance:github:example/research-agent",
+        "identity": {
+          "public_key": "MCowBQYDK2VwAyEAyuDQn/j1dbeAd288fU7lRV5cFcm7Zsm42jwCKy07N98=",
+          "algorithm": "ed25519",
+          "signature": "LqPe4bIXfa4qRhblNfp3VXElk2gG0x5UfTaHNKJGUDNbx4tRNXnJyXZZuu3BiC58Eur2JF719MieXU+EJe2pDg=="
+        }
+      }
+    }
+  ]
+}