provenance-protocol 0.1.3 → 0.2.1

package/src/verify.d.ts

@@ -0,0 +1,85 @@
+/**
+ * provenance-protocol — offline verification (TypeScript definitions)
+ *
+ * Verifies a PROVENANCE.yml declaration without contacting any service.
+ * Works anywhere the Web Crypto API exists: modern browsers, Node 18+.
+ */
+
+/** Whether a declaration was served from the location its provenance_id names. */
+export type LocationCheck = 'match' | 'mismatch' | 'unchecked';
+
+export interface VerificationResult {
+  /** An identity.signature was present to check. */
+  signed: boolean;
+  /** The signature verified against identity.public_key. */
+  valid: boolean;
+  /** Why the result is not a clean pass, or null when it is. */
+  reason: string | null;
+  provenanceId: string | null;
+  publicKey: string | null;
+  /** SHA-256 of the public key, hex. Store it to detect key rotation. */
+  fingerprint: string | null;
+  location: LocationCheck;
+  /**
+   * Signature valid AND retrieval location confirmed. Only both together
+   * justify treating the declaration as the named project owner's.
+   */
+  trustworthy: boolean;
+}
+
+export interface VerifyOptions {
+  /** URL the declaration was fetched from, for the location check. */
+  retrievedFrom?: string;
+}
+
+/**
+ * Verify a parsed PROVENANCE.yml declaration offline.
+ *
+ * Declarations are YAML — parse with your own library and pass the object;
+ * this module is dependency-free by design.
+ *
+ * A valid signature proves the declaration came from the holder of that
+ * private key and is unaltered. 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.
+ */
+export function verifyDeclaration(
+  declaration: unknown,
+  options?: VerifyOptions
+): Promise<VerificationResult>;
+
+/** SHA-256 of the raw public key bytes, hex encoded. Use it to detect key rotation. */
+export function keyFingerprint(publicKeyBase64: string): Promise<string>;
+
+/** Split a provenance id into its platform and path, or null if malformed. */
+export function parseProvenanceId(
+  provenanceId: string
+): { platform: string; path: string } | null;
+
+/**
+ * Does a retrieval location agree with the declaration's own provenance_id?
+ * Returns 'unchecked' when the location cannot be interpreted, so an unknown
+ * host is never reported as agreement.
+ */
+export function checkLocation(provenanceId: string, retrievedFrom: string): LocationCheck;
+
+/**
+ * Verify a live challenge response against a key you already hold.
+ * The nonce must be single-use and unpredictable.
+ */
+export function verifyChallenge(
+  publicKeyBase64: string,
+  provenanceId: string,
+  nonce: string,
+  signatureBase64: string
+): Promise<boolean>;
+
+/**
+ * Verify an owner-signed revocation. Confirms it came from the key holder;
+ * it does not tell you whether a revocation exists.
+ */
+export function verifyRevocation(
+  publicKeyBase64: string,
+  provenanceId: string,
+  signatureBase64: string
+): Promise<boolean>;

package/src/verify.js

@@ -0,0 +1,277 @@
+/**
+ * provenance-protocol — offline verification
+ *
+ * Verifies a PROVENANCE.yml declaration without contacting any service.
+ * No network, no account, no API key. See SPEC.md § Signing and Verification.
+ *
+ *   import { verifyDeclaration } from 'provenance-protocol/verify';
+ *
+ *   const result = await verifyDeclaration(parsedYaml, {
+ *     retrievedFrom: 'https://github.com/alice/research-assistant',
+ *   });
+ *
+ * Declarations are YAML. Parse them with whatever library you already use and
+ * pass the resulting object — this module stays dependency-free on purpose.
+ *
+ * Uses the Web Crypto API (crypto.subtle): all modern browsers, Node 18+.
+ */
+
+/** Signature algorithm for spec v0.1. No other value is valid. */
+const ALGORITHM = 'ed25519';
+
+function subtle() {
+  const s = globalThis.crypto?.subtle;
+  if (!s) throw new Error('Web Crypto API (crypto.subtle) not available');
+  return s;
+}
+
+function fromBase64(value) {
+  if (typeof value !== 'string' || value.length === 0) throw new Error('not base64');
+  // atob is available in browsers and Node 18+; avoids depending on Buffer.
+  const binary = atob(value.replace(/\s+/g, ''));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function toHex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+async function verifyEd25519(publicKeyBase64, signatureBase64, message) {
+  const key = await subtle().importKey(
+    'spki',
+    fromBase64(publicKeyBase64),
+    { name: 'Ed25519' },
+    false,
+    ['verify']
+  );
+  return subtle().verify(
+    'Ed25519',
+    key,
+    fromBase64(signatureBase64),
+    new TextEncoder().encode(message)
+  );
+}
+
+/**
+ * SHA-256 of the raw public key bytes, hex encoded.
+ *
+ * Use it to detect key rotation: store the fingerprint you saw for a
+ * provenance_id, and treat a different one later as a material change rather
+ * than a silent update. See SPEC.md § Signing and Verification (Continuity).
+ *
+ * @param {string} publicKeyBase64  Base64 SPKI DER Ed25519 public key
+ * @returns {Promise<string>}
+ */
+export async function keyFingerprint(publicKeyBase64) {
+  const digest = await subtle().digest('SHA-256', fromBase64(publicKeyBase64));
+  return toHex(new Uint8Array(digest));
+}
+
+/**
+ * Where a declaration claims to live, parsed out of its provenance_id.
+ *
+ * @param {string} provenanceId  e.g. 'provenance:github:alice/agent'
+ * @returns {{ platform: string, path: string } | null}
+ */
+export function parseProvenanceId(provenanceId) {
+  if (typeof provenanceId !== 'string') return null;
+  const match = /^provenance:([a-z0-9-]+):(.+)$/i.exec(provenanceId.trim());
+  if (!match) return null;
+  return { platform: match[1].toLowerCase(), path: match[2] };
+}
+
+const HOST_PLATFORMS = [
+  [/(^|\.)github\.com$/i, 'github'],
+  [/(^|\.)githubusercontent\.com$/i, 'github'],
+  [/(^|\.)huggingface\.co$/i, 'huggingface'],
+  [/(^|\.)npmjs\.com$/i, 'npm'],
+  [/(^|\.)registry\.npmjs\.org$/i, 'npm'],
+  [/(^|\.)pypi\.org$/i, 'pypi'],
+];
+
+/**
+ * Does a retrieval location agree with the declaration's own provenance_id?
+ *
+ * A declaration served from somewhere other than the location it names was
+ * placed there by someone who may have no control over the named project —
+ * the re-hosting case. A conformant verifier treats that as unverified
+ * however good the signature is.
+ *
+ * Returns 'unchecked' when the location cannot be interpreted, so an unknown
+ * host is never reported as agreement.
+ *
+ * @param {string} provenanceId
+ * @param {string} retrievedFrom  URL the declaration was fetched from
+ * @returns {'match' | 'mismatch' | 'unchecked'}
+ */
+export function checkLocation(provenanceId, retrievedFrom) {
+  const id = parseProvenanceId(provenanceId);
+  if (!id || typeof retrievedFrom !== 'string') return 'unchecked';
+
+  let url;
+  try {
+    url = new URL(retrievedFrom);
+  } catch {
+    return 'unchecked';
+  }
+
+  const platform = HOST_PLATFORMS.find(([host]) => host.test(url.hostname))?.[1];
+  if (!platform) return 'unchecked';
+  if (platform !== id.platform) return 'mismatch';
+
+  // github/huggingface ids are owner/repo; npm and pypi are package names.
+  const segments = url.pathname.split('/').filter(Boolean);
+  const expected = id.path.toLowerCase().split('/').filter(Boolean);
+  if (expected.length === 0) return 'unchecked';
+
+  // The declared path must appear as consecutive segments of the URL path.
+  // Covers both https://github.com/owner/repo and raw/blob URLs beneath it.
+  const haystack = segments.map((s) => s.toLowerCase());
+  for (let i = 0; i + expected.length <= haystack.length; i++) {
+    if (expected.every((part, j) => haystack[i + j] === part)) return 'match';
+  }
+  return 'mismatch';
+}
+
+/**
+ * Verify a parsed PROVENANCE.yml declaration offline.
+ *
+ * Checks the identity signature against the public key inside the file, and —
+ * 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.
+ *
+ * @param {object} declaration  Parsed PROVENANCE.yml
+ * @param {object} [options]
+ * @param {string} [options.retrievedFrom]  URL the declaration was fetched from
+ * @returns {Promise<{
+ *   signed: boolean,
+ *   valid: boolean,
+ *   reason: string | null,
+ *   provenanceId: string | null,
+ *   publicKey: string | null,
+ *   fingerprint: string | null,
+ *   location: 'match' | 'mismatch' | 'unchecked',
+ *   trustworthy: boolean
+ * }>}
+ */
+export async function verifyDeclaration(declaration, options = {}) {
+  const base = {
+    signed: false,
+    valid: false,
+    reason: null,
+    provenanceId: null,
+    publicKey: null,
+    fingerprint: null,
+    location: 'unchecked',
+    trustworthy: false,
+  };
+
+  if (declaration === null || typeof declaration !== 'object') {
+    return { ...base, reason: 'Declaration must be a parsed object' };
+  }
+
+  const provenanceId =
+    typeof declaration.provenance_id === 'string' ? declaration.provenance_id : null;
+  const identity =
+    declaration.identity !== null && typeof declaration.identity === 'object'
+      ? declaration.identity
+      : null;
+  const publicKey = typeof identity?.public_key === 'string' ? identity.public_key : null;
+  const signature = typeof identity?.signature === 'string' ? identity.signature : null;
+
+  const location = options.retrievedFrom
+    ? checkLocation(provenanceId, options.retrievedFrom)
+    : 'unchecked';
+
+  const result = { ...base, provenanceId, publicKey, location };
+
+  if (!identity) return { ...result, reason: 'No identity block' };
+  if (!publicKey) return { ...result, reason: 'identity.public_key is missing' };
+
+  const algorithm = identity.algorithm ?? ALGORITHM;
+  if (String(algorithm).toLowerCase() !== ALGORITHM) {
+    return { ...result, reason: `Unsupported algorithm: ${algorithm}` };
+  }
+
+  try {
+    result.fingerprint = await keyFingerprint(publicKey);
+  } catch {
+    return { ...result, reason: 'identity.public_key is not a valid Ed25519 key' };
+  }
+
+  // A key with no signature advertises which key to challenge later. It says
+  // nothing about whether this file has been altered.
+  if (!signature) {
+    return { ...result, reason: 'identity.signature is absent — key advertised, file not attested' };
+  }
+  result.signed = true;
+
+  if (!provenanceId) {
+    return { ...result, reason: 'provenance_id is required to verify a signature' };
+  }
+
+  let valid;
+  try {
+    valid = await verifyEd25519(publicKey, signature, `${provenanceId}:${publicKey}`);
+  } catch {
+    return { ...result, reason: 'identity.signature is malformed' };
+  }
+
+  if (!valid) return { ...result, reason: 'Signature does not verify' };
+
+  return {
+    ...result,
+    valid: true,
+    // Signature proves integrity; location binds it to a project someone
+    // controls. Only both together justify treating the file as the owner's.
+    trustworthy: location === 'match',
+    reason: location === 'match' ? null : 'Signature valid, but retrieval location was not confirmed',
+  };
+}
+
+/**
+ * Verify a live challenge response offline, against a key you already hold.
+ *
+ * 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.
+ *
+ * @param {string} publicKeyBase64
+ * @param {string} provenanceId
+ * @param {string} nonce            Single-use, unpredictable
+ * @param {string} signatureBase64
+ * @returns {Promise<boolean>}
+ */
+export async function verifyChallenge(publicKeyBase64, provenanceId, nonce, signatureBase64) {
+  try {
+    return await verifyEd25519(publicKeyBase64, signatureBase64, `${provenanceId}:${nonce}`);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify an owner-signed revocation offline.
+ *
+ * Confirms the revocation 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 verifyRevocation(publicKeyBase64, provenanceId, signatureBase64) {
+  try {
+    return await verifyEd25519(publicKeyBase64, signatureBase64, `${provenanceId}:REVOKE`);
+  } catch {
+    return false;
+  }
+}

package/test-vectors/README.md

@@ -0,0 +1,52 @@
+# Test vectors
+
+Normative test data for Provenance Protocol v0.1. An implementation that
+reproduces these results interoperates with every other implementation that
+does, without reference to any service.
+
+## signatures-0.1.json
+
+Ed25519 signature vectors for the three signed messages in the protocol:
+
+| Message | Used for |
+|---|---|
+| `<provenance_id>:<public_key>` | `identity.signature` in `PROVENANCE.yml` |
+| `<provenance_id>:<nonce>` | live proof that a running agent holds the key |
+| `<provenance_id>:REVOKE` | owner-signed revocation |
+
+Each vector carries the exact message, the public key, the signature, and
+whether it must verify. Ed25519 is deterministic (RFC 8032), so signing the
+given message with the given private key must reproduce the given signature
+byte for byte.
+
+The four negative vectors are the cases that matter in practice: a signature
+from the wrong key, an altered `provenance_id`, a substituted public key
+(the re-hosting attack), and a malformed signature.
+
+The private key in this file is test data. Never use it for anything.
+
+## Running them
+
+Any Ed25519 implementation works. With Node:
+
+```js
+import { readFileSync } from 'node:fs';
+
+const { vectors } = JSON.parse(readFileSync('signatures-0.1.json', 'utf8'));
+
+for (const v of vectors) {
+  const key = await crypto.subtle.importKey(
+    'spki', Buffer.from(v.public_key, 'base64'), { name: 'Ed25519' }, false, ['verify']
+  );
+  let got;
+  try {
+    got = await crypto.subtle.verify(
+      'Ed25519', key, Buffer.from(v.signature, 'base64'), new TextEncoder().encode(v.message)
+    ) ? 'valid' : 'invalid';
+  } catch { got = 'invalid'; }
+  console.log(got === v.expect ? `PASS ${v.id}` : `FAIL ${v.id}`);
+}
+```
+
+See [SPEC.md](../SPEC.md#signing-and-verification) for what a valid signature
+does and does not prove.

package/test-vectors/signatures-0.1.json

@@ -0,0 +1,80 @@
+{
+  "$comment": "Normative test vectors for Provenance Protocol v0.1 signatures. Ed25519 is deterministic (RFC 8032): a correct implementation reproduces these signatures byte for byte.",
+  "spec_version": "0.1",
+  "algorithm": "ed25519",
+  "encodings": {
+    "public_key": "base64 of SPKI DER",
+    "private_key": "base64 of PKCS8 DER",
+    "signature": "base64 of raw 64-byte Ed25519 signature",
+    "message": "UTF-8 bytes of the message string"
+  },
+  "keypair": {
+    "provenance_id": "provenance:github:example/research-agent",
+    "public_key": "MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+    "private_key": "MC4CAQAwBQYDK2VwBCIEIMzkaPUByQh5c1/dZ9on5XWDP+0IBFrCyiAXAvhtBAFg",
+    "$comment": "Test key only. Never use in production."
+  },
+  "vectors": [
+    {
+      "id": "identity-signature-valid",
+      "purpose": "identity.signature in PROVENANCE.yml \u2014 binds the declaration to the key holder",
+      "message_template": "<provenance_id>:<public_key>",
+      "message": "provenance:github:example/research-agent:MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "public_key": "MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "signature": "TCnS9o9yiDboy3SFlG65ThO6IDAhv09rlrDWOdvX2xZj3uAI5efbIw8xIXHxErtcaJAtg3BtDvXX+bv5RhLIDQ==",
+      "expect": "valid"
+    },
+    {
+      "id": "challenge-signature-valid",
+      "purpose": "live proof that a running agent controls the declared key",
+      "message_template": "<provenance_id>:<nonce>",
+      "nonce": "a7f3c1e9b2d84056",
+      "message": "provenance:github:example/research-agent:a7f3c1e9b2d84056",
+      "public_key": "MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "signature": "HV/AjVj/53ZIMZkyR5Ov1p8z6t3ZkZoHlr1bgePlQRXYWCTxzKJvHfmQgI78HCmYeMSf5OaW+GcIXOUQcLhGAw==",
+      "expect": "valid"
+    },
+    {
+      "id": "revocation-signature-valid",
+      "purpose": "owner-signed revocation of a provenance id",
+      "message_template": "<provenance_id>:REVOKE",
+      "message": "provenance:github:example/research-agent:REVOKE",
+      "public_key": "MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "signature": "GPnNOjmVhk4Wxlq3M1KUiyAlI6nkwhq5/SeXQiRkhuLMnuLwJ0qywdlP4CpvgorGLRjP9pUfLSBLOD6Mc5E/Bw==",
+      "expect": "valid"
+    },
+    {
+      "id": "identity-signature-wrong-key",
+      "purpose": "signature made by a different private key must not verify",
+      "message": "provenance:github:example/research-agent:MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "public_key": "MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "signature": "BqgcrtjZf2KS0p4zQwq/GA/c6jLNyx+PjOEVEZuvMC/1+kHlT4QLv7KuXWCR5vWB6mb+ap79effgYooumTnXCg==",
+      "expect": "invalid"
+    },
+    {
+      "id": "identity-signature-tampered-id",
+      "purpose": "the provenance id was altered after signing",
+      "message": "provenance:github:attacker/fork:MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "public_key": "MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "signature": "TCnS9o9yiDboy3SFlG65ThO6IDAhv09rlrDWOdvX2xZj3uAI5efbIw8xIXHxErtcaJAtg3BtDvXX+bv5RhLIDQ==",
+      "expect": "invalid"
+    },
+    {
+      "id": "identity-signature-substituted-key",
+      "purpose": "public_key swapped for another key \u2014 re-hosting attack",
+      "message": "provenance:github:example/research-agent:MCowBQYDK2VwAyEAm2AoU5BzkoMKTs+tjy8LIPu9FjivA0UbnnhekU5OK48=",
+      "public_key": "MCowBQYDK2VwAyEAm2AoU5BzkoMKTs+tjy8LIPu9FjivA0UbnnhekU5OK48=",
+      "signature": "TCnS9o9yiDboy3SFlG65ThO6IDAhv09rlrDWOdvX2xZj3uAI5efbIw8xIXHxErtcaJAtg3BtDvXX+bv5RhLIDQ==",
+      "expect": "invalid"
+    },
+    {
+      "id": "identity-signature-malformed",
+      "purpose": "signature is not valid base64 of a 64-byte signature",
+      "message": "provenance:github:example/research-agent:MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "public_key": "MCowBQYDK2VwAyEAfKySY8lFCvOXFoTg1nagyZKUYYvAKW+2GvYh+oD9460=",
+      "signature": "not-a-signature",
+      "expect": "invalid",
+      "note": "Implementations may either return invalid or raise an error while decoding. Both are conformant; the requirement is that it must not verify."
+    }
+  ]
+}