provenance-protocol 0.3.0 → 0.5.0

package/SPEC.md

@@ -251,8 +251,30 @@ provenance:npm:@scope/package-name
 provenance:pypi:package-name
 provenance:huggingface:owner/space-name
 provenance:clawmarket:listing-id
+provenance:domain:agent.example.com
+provenance:domain:example.com/agents/research
 ```
 
+### Domain identifiers
+
+`provenance:domain:<hostname>` is for an agent that runs as a service and has no
+public repository — which is most commercial agents. Control is proven exactly as
+it is for a repository: the declaration is served from the location the
+identifier names, and only someone with write access to that location could have
+put it there.
+
+The hostname must match exactly. A subdomain is a different party for this
+purpose, and treating `agent.example.com` as covered by `example.com` would be
+the whole attack.
+
+Optional path segments allow several agents under one domain — those segments
+must appear in the retrieval path.
+
+Without this form, a hosted service serving its own declaration could never be
+verified as its operator's: the signature would check out while the location
+check reported `unchecked`, so no verifier could conclude the declaration was
+genuinely theirs.
+
 Add `provenance_id` to your PROVENANCE.yml to link your file to your
 index entry and claim your agent profile.
 
@@ -408,27 +430,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "provenance-protocol",
-  "version": "0.3.0",
+  "version": "0.5.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 && node test/location.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';
@@ -131,6 +131,26 @@ export function checkLocation(provenanceId, retrievedFrom) {
     return 'unchecked';
   }
 
+  // provenance:domain:<hostname>[/<path>] — for an agent that runs as a service
+  // and has no public repository. Control is proven the same way as with a
+  // repo: whoever put the file there had write access to the location. Most
+  // commercial agents are this shape, so without it they could never be
+  // verified as their operator's.
+  if (id.platform === 'domain') {
+    const [declaredHost, ...declaredPath] = id.path.split('/').filter(Boolean);
+    if (!declaredHost) return 'unchecked';
+    // Exact host match. A subdomain is a different party as far as this is
+    // concerned, and treating it as the same would be the whole attack.
+    if (url.hostname.toLowerCase() !== declaredHost.toLowerCase()) return 'mismatch';
+    if (declaredPath.length === 0) return 'match';
+    const segs = url.pathname.split('/').filter(Boolean).map((x) => x.toLowerCase());
+    const want = declaredPath.map((x) => x.toLowerCase());
+    for (let i = 0; i + want.length <= segs.length; i++) {
+      if (want.every((part, j) => segs[i + j] === part)) return 'match';
+    }
+    return 'mismatch';
+  }
+
   const platform = HOST_PLATFORMS.find(([host]) => host.test(url.hostname))?.[1];
   if (!platform) return 'unchecked';
   if (platform !== id.platform) return 'mismatch';
@@ -282,9 +302,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.