provenance-protocol 0.3.0 → 0.4.0

package/SPEC.md

@@ -408,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:
+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>`.
 
-```
-<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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "provenance-protocol",
-  "version": "0.3.0",
+  "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",
@@ -58,6 +58,6 @@
     "node": ">=14.0.0"
   },
   "scripts": {
-    "test": "node test/verify.test.mjs && node test/declaration-signature.test.mjs"
+    "test": "node test/verify.test.mjs && node test/declaration-signature.test.mjs && node test/payload-separation.test.mjs"
   }
 }

package/src/canonical.js

@@ -20,8 +20,6 @@
  *     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) {
@@ -30,6 +28,44 @@ export class CanonicalError extends Error {
   }
 }
 
+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';
 

package/src/keygen.d.ts

@@ -61,3 +61,15 @@ export function signRevocation(privateKeyBase64: string, provenanceId: string):
  * @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,7 +25,7 @@
  */
 
 import { generateKeyPairSync, sign, createPrivateKey } from 'crypto';
-import { declarationSigningPayload } from './canonical.js';
+import { declarationSigningPayload, challengePayload, revocationPayload } from './canonical.js';
 
 /**
  * Generate a new Ed25519 keypair for use with Provenance identity.
@@ -58,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
@@ -149,6 +154,47 @@ export function signRevocation(privateKeyBase64, provenanceId) {
  * @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' });

package/src/verify.d.ts

@@ -93,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,7 +16,7 @@
  * Uses the Web Crypto API (crypto.subtle): all modern browsers, Node 18+.
  */
 
-import { declarationSigningPayload } from './canonical.js';
+import { declarationSigningPayload, challengePayload, revocationPayload } from './canonical.js';
 
 /** Signature algorithm. Ed25519 in every spec version so far. */
 const ALGORITHM = 'ed25519';
@@ -282,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.