provenance-protocol 0.1.3 → 0.2.1

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "provenance-protocol",
-  "version": "0.1.3",
-  "description": "SDK for querying the Provenance agent identity index",
+  "version": "0.2.1",
+  "description": "The Provenance Protocol \u2014 open standard for AI agent identity \u2014 and its reference SDK",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
+  "bin": {
+    "provenance": "./src/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
@@ -13,6 +16,10 @@
     "./keygen": {
       "types": "./src/keygen.d.ts",
       "import": "./src/keygen.js"
+    },
+    "./verify": {
+      "types": "./src/verify.d.ts",
+      "import": "./src/verify.js"
     }
   },
   "files": [
@@ -20,7 +27,13 @@
     "src/index.d.ts",
     "src/keygen.js",
     "src/keygen.d.ts",
-    "README.md"
+    "src/verify.d.ts",
+    "src/verify.js",
+    "src/cli.js",
+    "README.md",
+    "SPEC.md",
+    "schema/provenance-0.1.json",
+    "test-vectors/"
   ],
   "keywords": [
     "ai-agent",
@@ -28,7 +41,10 @@
     "provenance",
     "trust",
     "llm",
-    "verification"
+    "verification",
+    "ed25519",
+    "offline-verification",
+    "standard"
   ],
   "license": "MIT",
   "repository": {
@@ -38,5 +54,8 @@
   "homepage": "https://getprovenance.dev",
   "engines": {
     "node": ">=14.0.0"
+  },
+  "scripts": {
+    "test": "node test/verify.test.mjs"
   }
 }

package/schema/provenance-0.1.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://getprovenance.dev/schema/0.1.json",
+  "title": "PROVENANCE.yml",
+  "description": "Provenance Protocol v0.1 schema for AI agent identity files",
+  "type": "object",
+  "required": [
+    "provenance",
+    "name",
+    "description"
+  ],
+  "properties": {
+    "provenance": {
+      "type": "string",
+      "description": "Spec version",
+      "enum": [
+        "0.1"
+      ]
+    },
+    "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 declaration itself 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 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."
+        },
+        "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/cli.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * provenance CLI
+ *
+ * npx provenance keygen
+ * npx provenance register --id provenance:github:org/agent --url https://...
+ * npx provenance status provenance:github:org/agent
+ * npx provenance revoke --id provenance:github:org/agent
+ */
+
+import { writeFileSync, readFileSync, existsSync } from 'fs';
+import { execSync } from 'child_process';
+import { generateProvenanceKeyPair, signChallenge, signForProvenance, signRevocation } from './keygen.js';
+
+const API = 'https://getprovenance.dev/api/agents';
+const KEY_FILE = '.provenance-key';
+
+function readPrivateKey() {
+  if (process.env.PROVENANCE_PRIVATE_KEY) return process.env.PROVENANCE_PRIVATE_KEY.trim();
+  if (existsSync(KEY_FILE)) return readFileSync(KEY_FILE, 'utf8').trim();
+  console.error(`No private key found. Set PROVENANCE_PRIVATE_KEY or run: npx provenance keygen`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      args[argv[i].slice(2)] = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+    } else {
+      args._ = args._ || [];
+      args._.push(argv[i]);
+    }
+  }
+  return args;
+}
+
+const [,, command, ...rest] = process.argv;
+const args = parseArgs(rest);
+
+// ── keygen ──────────────────────────────────────────────────────────────────
+
+if (command === 'keygen') {
+  const { publicKey, privateKey } = generateProvenanceKeyPair();
+
+  writeFileSync(KEY_FILE, privateKey, { mode: 0o600 });
+  try { execSync(`grep -qxF "${KEY_FILE}" .gitignore 2>/dev/null || echo "${KEY_FILE}" >> .gitignore`); } catch {}
+
+  console.log(`\nKeypair generated.\n`);
+  console.log(`Private key → ${KEY_FILE} (chmod 600, added to .gitignore)`);
+  console.log(`\nPublic key (add to PROVENANCE.yml):\n`);
+  console.log(`  identity:`);
+  console.log(`    public_key: "${publicKey}"`);
+  console.log(`    algorithm: ed25519`);
+  console.log(`\nNext: npx provenance register --id provenance:<platform>:<org>/<name>\n`);
+  process.exit(0);
+}
+
+// ── register ─────────────────────────────────────────────────────────────────
+
+if (command === 'register') {
+  const id = args.id || args._?.[0];
+  if (!id) { console.error('Usage: npx provenance register --id provenance:<platform>:<org>/<name> [options]'); process.exit(1); }
+
+  const privateKey = readPrivateKey();
+  const { publicKey } = (() => {
+    // derive public key from private key for display — we just use the stored one
+    // We can't derive public from private easily here, so read from PROVENANCE.yml or require --public-key
+    return { publicKey: args['public-key'] || null };
+  })();
+
+  // If no public key arg, re-generate won't work — need the stored public key
+  // Best path: require keygen was run, read public key from PROVENANCE.yml if present
+  let pubKey = args['public-key'];
+  if (!pubKey) {
+    if (existsSync('PROVENANCE.yml')) {
+      const yml = readFileSync('PROVENANCE.yml', 'utf8');
+      const match = yml.match(/public_key:\s*["']?([A-Za-z0-9+/=]+)["']?/);
+      if (match) pubKey = match[1];
+    }
+  }
+  if (!pubKey) {
+    console.error('Public key required. Pass --public-key or add identity.public_key to PROVENANCE.yml first.');
+    process.exit(1);
+  }
+
+  const signed_challenge = signChallenge(privateKey, id, 'REGISTER');
+
+  const body = {
+    provenance_id: id,
+    public_key: pubKey,
+    signed_challenge,
+    ...(args.url ? { url: args.url } : {}),
+    ...(args.name ? { name: args.name } : {}),
+    ...(args.description ? { description: args.description } : {}),
+    ...(args.capabilities ? { capabilities: args.capabilities.split(',').map(s => s.trim()) } : {}),
+    ...(args.constraints ? { constraints: args.constraints.split(',').map(s => s.trim()) } : {}),
+    ...(args.model ? { model_provider: args.model } : {}),
+    ...(args['model-id'] ? { model_id: args['model-id'] } : {}),
+  };
+
+  try {
+    const res = await fetch(`${API}/register`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      console.error(`\nRegistration failed: ${data.error}`);
+      if (data.hint) console.error(`Hint: ${data.hint}`);
+      process.exit(1);
+    }
+    console.log(`\n${data.created ? 'Registered' : 'Updated'}: ${id}`);
+    console.log(`identity: ${data.agent?.identity}`);
+    console.log(`profile:  https://getprovenance.dev/agent/${id.replace('provenance:', '').replace(':', '/')}\n`);
+  } catch (e) {
+    console.error('Network error:', e.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── status ───────────────────────────────────────────────────────────────────
+
+if (command === 'status') {
+  const id = args._?.[0] || args.id;
+  if (!id) { console.error('Usage: npx provenance status <provenance_id>'); process.exit(1); }
+
+  try {
+    const res = await fetch(`${API}/register?provenance_id=${encodeURIComponent(id)}`);
+    const data = await res.json();
+    if (!data.registered) { console.log(`\nNot registered: ${id}\n`); process.exit(0); }
+    const a = data.agent;
+    console.log(`\n${id}`);
+    console.log(`name:     ${a.name || '—'}`);
+    console.log(`identity: ${a.identity}`);
+    console.log(`status:   ${a.status}`);
+    console.log(`profile:  https://getprovenance.dev/agent/${id.replace('provenance:', '').replace(':', '/')}\n`);
+  } catch (e) {
+    console.error('Network error:', e.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── revoke ───────────────────────────────────────────────────────────────────
+
+if (command === 'revoke') {
+  const id = args.id || args._?.[0];
+  if (!id) { console.error('Usage: npx provenance revoke --id <provenance_id>'); process.exit(1); }
+
+  const privateKey = readPrivateKey();
+  const signed_challenge = signRevocation(privateKey, id);
+
+  try {
+    const res = await fetch(`${API}/revoke`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ provenance_id: id, signed_challenge }),
+    });
+    const data = await res.json();
+    if (!res.ok) { console.error(`Revocation failed: ${data.error}`); process.exit(1); }
+    console.log(`\nKey revoked for ${id}.`);
+    console.log(`Run npx provenance keygen && npx provenance register --id ${id} to re-register with a new key.\n`);
+  } catch (e) {
+    console.error('Network error:', e.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── help ─────────────────────────────────────────────────────────────────────
+
+console.log(`
+provenance <command>
+
+  keygen                          Generate an Ed25519 keypair
+  register --id <id> [options]    Register or update your agent
+  status <id>                     Check registration status
+  revoke --id <id>                Revoke your registered key
+
+register options:
+  --id           provenance:<platform>:<org>/<name>  (required)
+  --url          URL to your PROVENANCE.yml (for independent verification)
+  --name         Agent display name
+  --description  One-sentence description
+  --capabilities read:web,write:summaries
+  --constraints  no:pii,no:financial:transact
+  --model        anthropic / openai / etc.
+  --model-id     claude-sonnet-4-6 / gpt-4o / etc.
+  --public-key   Base64 public key (auto-read from PROVENANCE.yml if present)
+
+Full docs: https://getprovenance.dev/docs
+`);
+process.exit(0);

package/src/index.d.ts

@@ -8,6 +8,7 @@ export interface TrustProfile {
   platform?: string;
   name?: string;
   declared?: boolean;
+  identity_verified?: boolean;
   confidence?: number;
   age_days?: number | null;
   capabilities?: string[];
@@ -45,6 +46,8 @@ export interface VerifyResult {
 
 export interface GateOptions {
   requireDeclared?: boolean;
+  /** Require identity_verified: true — agent must have cryptographic proof of key ownership. */
+  requireVerified?: boolean;
   requireConstraints?: string[];
   requireCapabilities?: string[];
   requireClean?: boolean;

package/src/index.js

@@ -45,6 +45,35 @@ async function _verifyEd25519(publicKeyBase64, signatureBase64, message) {
 }
 
 const DEFAULT_API = 'https://getprovenance.dev';
+
+const SEVERITY_ORDER = ['low', 'medium', 'high', 'critical'];
+
+// Returns a failure reason string if clean check fails, null if passes.
+// requireClean: true | false | { minSeverity: 'low'|'medium'|'high'|'critical' }
+function _evaluateClean(requireClean, trust) {
+  if (!requireClean) return null;
+  if (trust.incidents === 0) return null;
+
+  // true = block on any open incident
+  if (requireClean === true) {
+    return `Agent has ${trust.incidents} open incident(s)`;
+  }
+
+  // { minSeverity } = block only if any open incident meets or exceeds that severity
+  if (requireClean.minSeverity) {
+    const threshold = SEVERITY_ORDER.indexOf(requireClean.minSeverity);
+    const incidents = trust.incidents_detail || [];
+    const blocking = incidents.filter(inc =>
+      SEVERITY_ORDER.indexOf(inc.severity || 'medium') >= threshold
+    );
+    if (blocking.length > 0) {
+      return `Agent has ${blocking.length} open incident(s) at or above severity '${requireClean.minSeverity}'`;
+    }
+    return null;
+  }
+
+  return null;
+}
 const DEFAULT_CACHE_TTL = 300; // 5 minutes
 
 // Simple LRU cache
@@ -106,7 +135,7 @@ export class Provenance {
    *   //   confidence: 0.9,           — internal signal, use declared/identity_verified for trust decisions
    *   //   capabilities: ['read:web', 'write:summaries'],
    *   //   constraints: ['no:financial:transact', 'no:pii'],
-   *   //   incidents: 0,
+   *   //   incidents: 0,              — open/investigating only; resolved don't block gate()
    *   //   model: { provider: 'anthropic', model_id: 'claude-sonnet-4-5' },
    *   //   status: 'active',
    *   // }
@@ -141,6 +170,8 @@ export class Provenance {
         capabilities: data.capabilities || [],
         constraints: data.constraints || [],
         incidents: data.incident_count || 0,
+        incidents_detail: data.incidents || [],
+        resolved_incidents: data.resolved_incidents || [],
         model: data.model || null,
         status: data.status || 'unknown',
         first_seen: data.timestamps?.first_seen || null,
@@ -260,11 +291,18 @@ export class Provenance {
    * Run all your trust requirements in one call.
    * Returns { allowed, reason, trust }.
    *
+   * requireClean accepts:
+   *   - true                    block on any open incident (default)
+   *   - false                   ignore incidents entirely
+   *   - { minSeverity }         block only if any open incident meets or exceeds severity
+   *                             severity order: low < medium < high < critical
+   *                             e.g. { minSeverity: 'high' } allows low/medium incidents
+   *
    * Example:
    *   const result = await provenance.gate('provenance:github:alice/agent', {
    *     requireDeclared: true,
    *     requireConstraints: ['no:financial:transact', 'no:pii'],
-   *     requireClean: true,
+   *     requireClean: { minSeverity: 'high' },
    *     requireMinAge: 30,
    *     requireMinConfidence: 0.7,
    *   });
@@ -275,6 +313,7 @@ export class Provenance {
    */
   async gate(provenanceId, {
     requireDeclared = false,
+    requireVerified = false,
     requireConstraints = [],
     requireCapabilities = [],
     requireClean = true,
@@ -321,8 +360,12 @@ export class Provenance {
     if (requireDeclared && !trust.declared) {
       return { allowed: false, reason: 'Agent has not declared a PROVENANCE.yml file', trust };
     }
-    if (requireClean && trust.incidents > 0) {
-      return { allowed: false, reason: `Agent has ${trust.incidents} open incident(s)`, trust };
+    if (requireVerified && !trust.identity_verified) {
+      return { allowed: false, reason: 'Agent identity is not cryptographically verified', trust };
+    }
+    if (requireClean) {
+      const blocked = _evaluateClean(requireClean, trust);
+      if (blocked) return { allowed: false, reason: blocked, trust };
     }
     if (requireMinConfidence && trust.confidence < requireMinConfidence) {
       return { allowed: false, reason: `Agent confidence ${trust.confidence} below required ${requireMinConfidence}`, trust };
@@ -466,6 +509,7 @@ export class Provenance {
   _evaluateGate(trust, options) {
     const {
       requireDeclared = false,
+      requireVerified = false,
       requireConstraints = [],
       requireCapabilities = [],
       requireClean = true,
@@ -482,6 +526,9 @@ export class Provenance {
     if (requireDeclared && !trust.declared) {
       return { allowed: false, reason: 'Agent has not declared a PROVENANCE.yml file', trust };
     }
+    if (requireVerified && !trust.identity_verified) {
+      return { allowed: false, reason: 'Agent identity is not cryptographically verified', trust };
+    }
     for (const c of requireConstraints) {
       if (!trust.constraints?.includes(c)) {
         return { allowed: false, reason: `Agent has not committed to constraint: ${c}`, trust };
@@ -492,8 +539,9 @@ export class Provenance {
         return { allowed: false, reason: `Agent does not have capability: ${c}`, trust };
       }
     }
-    if (requireClean && trust.incidents > 0) {
-      return { allowed: false, reason: `Agent has ${trust.incidents} open incident(s)`, trust };
+    if (requireClean) {
+      const blocked = _evaluateClean(requireClean, trust);
+      if (blocked) return { allowed: false, reason: blocked, trust };
     }
     if (requireMinAge > 0 && (trust.age_days || 0) < requireMinAge) {
       return { allowed: false, reason: `Agent is only ${trust.age_days || 0} days old (minimum: ${requireMinAge})`, trust };