provenance-protocol 0.1.2 → 0.1.4

package/README.md

@@ -21,9 +21,10 @@ const trust = await provenance.check('provenance:github:alice/research-assistant
 console.log(trust);
 // {
 //   found: true,
+//   identity: 'verified',       // 'inferred' | 'declared' | 'verified'
+//   identity_verified: true,
 //   declared: true,
 //   age_days: 142,
-//   confidence: 0.9,
 //   capabilities: ['read:web', 'write:summaries'],
 //   constraints: ['no:financial:transact', 'no:pii'],
 //   incidents: 0,
@@ -39,11 +40,11 @@ The most useful method for receiving systems.
 
 ```js
 const result = await provenance.gate('provenance:github:alice/agent', {
-  requireDeclared: true,                                  // must have PROVENANCE.yml
+  requireDeclared: true,                                    // must have PROVENANCE.yml
+  requireVerified: true,                                    // must have identity_verified: true
   requireConstraints: ['no:financial:transact', 'no:pii'], // must have committed to these
-  requireClean: true,                                     // no open incidents
-  requireMinAge: 30,                                      // must be at least 30 days old
-  requireMinConfidence: 0.7,                              // classification confidence
+  requireClean: true,                                       // no open incidents
+  requireMinAge: 30,                                        // must be at least 30 days old
 });
 
 if (!result.allowed) {
@@ -119,35 +120,42 @@ if (result.fallback) {
 | Field | Type | Description |
 |---|---|---|
 | `found` | boolean | Agent exists in Provenance index |
-| `declared` | boolean | Has a PROVENANCE.yml file |
+| `identity` | string | `'inferred'` \| `'declared'` \| `'verified'` — see below |
+| `identity_verified` | boolean | Cryptographic key ownership confirmed against a public URL |
+| `declared` | boolean | Agent has a PROVENANCE.yml (or registered via API with full fields) |
 | `age_days` | number | Days since first indexed |
-| `confidence` | number | 0–1 classification confidence |
 | `capabilities` | string[] | What the agent declares it can do |
 | `constraints` | string[] | What the agent has publicly committed never to do |
 | `incidents` | number | Number of open incidents |
-| `status` | string | active / suspended / removed |
+| `status` | string | `active` / `suspended` / `removed` |
 | `model` | object | `{ provider, model_id }` if declared |
 | `public_key` | string\|null | Base64 Ed25519 public key, if registered |
-| `identity_verified` | boolean | Cryptographic proof of key ownership confirmed |
 | `ajp_endpoint` | string\|null | AJP job endpoint URL, if the agent accepts delegated jobs |
 | `first_seen` | string | ISO date of first public appearance |
 
+### Identity states
+
+| State | Meaning |
+|---|---|
+| `inferred` | Indexed by crawler from a public repo. No PROVENANCE.yml, no self-registration. |
+| `declared` | Agent registered itself (or has PROVENANCE.yml) but without cryptographic key verification. |
+| `verified` | Agent registered with a keypair and the public key was confirmed against a publicly fetchable PROVENANCE.yml. **Independently auditable** — anyone can re-verify without trusting the Provenance registry. |
+
 ---
 
 ## Registering your own agent
 
-```js
-import { Provenance } from 'provenance-protocol';
-import { generateProvenanceKeyPair, signChallenge } from 'provenance-protocol/keygen';
+### Public repo (GitHub / HuggingFace / npm)
 
-const provenance = new Provenance();
+Push a `PROVENANCE.yml` containing your public key to the repo, then register. The server fetches the file and confirms the key — independently verifiable by anyone.
 
-// One-time: generate a keypair
-const { publicKey, privateKey } = generateProvenanceKeyPair();
-// Store privateKey as PROVENANCE_PRIVATE_KEY env var — never commit it
+```js
+import { generateProvenanceKeyPair, signForProvenance, signChallenge } from 'provenance-protocol/keygen';
 
-// Sign proof of key ownership for registration
+const { publicKey, privateKey } = generateProvenanceKeyPair();
 const provenanceId = 'provenance:github:your-org/your-agent';
+
+// Add to PROVENANCE.yml → commit → push, then:
 const signed_challenge = signChallenge(privateKey, provenanceId, 'REGISTER');
 
 await provenance.register({
@@ -158,11 +166,34 @@ await provenance.register({
   capabilities: ['read:web', 'write:summaries'],
   constraints: ['no:pii'],
   public_key: publicKey,
-  signed_challenge,          // proves you control the private key
+  signed_challenge,
 });
-// → { created: true, identity_verified: true, confidence: 1.0 }
+// → { created: true, agent: { identity: 'verified', identity_verified: true } }
 ```
 
+### Private agent (no public repo)
+
+Use `provenance:custom:` platform. Host your `PROVENANCE.yml` at any public URL you control and pass it as `url` — this makes the identity independently verifiable. Without a `url`, verification is registry-dependent (key control only).
+
+```js
+const provenanceId = 'provenance:custom:your-org/your-agent';
+const signed_challenge = signChallenge(privateKey, provenanceId, 'REGISTER');
+
+await provenance.register({
+  id: provenanceId,
+  url: 'https://yourdomain.com/.well-known/provenance.yml', // optional but recommended
+  name: 'Your Agent',
+  description: 'What it does',
+  capabilities: ['read:web'],
+  constraints: ['no:pii'],
+  public_key: publicKey,
+  signed_challenge,
+});
+// → { created: true, agent: { identity: 'verified', identity_verified: true } }
+```
+
+See [getprovenance.dev/docs#ai-quickstart](https://getprovenance.dev/docs#ai-quickstart) for full automated scripts.
+
 ## Revoking a compromised key
 
 ```js

package/package.json

@@ -1,19 +1,29 @@
 {
   "name": "provenance-protocol",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "SDK for querying the Provenance agent identity index",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
+  "bin": {
+    "provenance": "./src/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
+    },
+    "./keygen": {
+      "types": "./src/keygen.d.ts",
+      "import": "./src/keygen.js"
     }
   },
   "files": [
     "src/index.js",
     "src/index.d.ts",
+    "src/keygen.js",
+    "src/keygen.d.ts",
+    "src/cli.js",
     "README.md"
   ],
   "keywords": [

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/keygen.d.ts

@@ -0,0 +1,48 @@
+/**
+ * provenance-protocol — Key generation and signing utilities (TypeScript definitions)
+ * Node.js only. Not for browser use.
+ */
+
+export interface KeyPair {
+  /** Base64-encoded SPKI DER public key. Put this in PROVENANCE.yml identity.public_key */
+  publicKey: string;
+  /** Base64-encoded PKCS8 DER private key. Store as PROVENANCE_PRIVATE_KEY env var. Never commit. */
+  privateKey: string;
+}
+
+/**
+ * Generate a new Ed25519 keypair for Provenance identity.
+ * Run once during agent setup.
+ */
+export function generateProvenanceKeyPair(): KeyPair;
+
+/**
+ * Sign a challenge nonce from a receiving system.
+ * Returns a base64-encoded signature over `${provenanceId}:${nonce}`.
+ *
+ * @param privateKeyBase64  Your PROVENANCE_PRIVATE_KEY (base64 PKCS8 DER)
+ * @param provenanceId      Your agent's Provenance ID
+ * @param nonce             The nonce sent by the receiving system
+ */
+export function signChallenge(privateKeyBase64: string, provenanceId: string, nonce: string): string;
+
+/**
+ * Sign your PROVENANCE.yml identity claim.
+ *
+ * Produces the `identity.signature` value for PROVENANCE.yml.
+ * Signs `${provenanceId}:${publicKeyBase64}` — binding the keypair to your specific agent ID.
+ * Run once during setup, after generateProvenanceKeyPair().
+ *
+ * @param privateKeyBase64  Your PROVENANCE_PRIVATE_KEY (base64 PKCS8 DER)
+ * @param provenanceId      Your agent's Provenance ID
+ * @param publicKeyBase64   The public key you generated (base64 SPKI DER)
+ * @returns                 Base64 signature — put in PROVENANCE.yml identity.signature
+ */
+export function signForProvenance(privateKeyBase64: string, provenanceId: string, publicKeyBase64: string): string;
+
+/**
+ * Sign a revocation request — clears your agent's public key and identity_verified status.
+ * Use when your private key is compromised or you're rotating keys.
+ * Send the result as signed_challenge to POST /api/agents/revoke.
+ */
+export function signRevocation(privateKeyBase64: string, provenanceId: string): string;

package/src/keygen.js

@@ -0,0 +1,142 @@
+/**
+ * provenance-protocol — Key generation and signing utilities
+ *
+ * Agent operators use this to:
+ *   1. Generate an Ed25519 keypair once (setup)
+ *   2. Put the public key in PROVENANCE.yml under identity.public_key
+ *   3. Keep the private key in their environment (never committed, never shared)
+ *   4. Sign challenges from receiving systems at runtime
+ *
+ * Usage (one-time setup):
+ *   import { generateProvenanceKeyPair } from 'provenance-protocol/keygen';
+ *   const { publicKey, privateKey } = generateProvenanceKeyPair();
+ *   // Add publicKey to your PROVENANCE.yml:
+ *   //   identity:
+ *   //     public_key: "<publicKey>"
+ *   // Store privateKey as an environment variable: PROVENANCE_PRIVATE_KEY=<privateKey>
+ *
+ * Usage (runtime — signing challenges):
+ *   import { signChallenge } from 'provenance-protocol/keygen';
+ *   const signature = signChallenge(process.env.PROVENANCE_PRIVATE_KEY, provenanceId, nonce);
+ *   // Return signature to the receiving system
+ *
+ * Note: This module uses Node.js built-in crypto. It is Node-only (not browser).
+ * The verification side (in index.js) uses Web Crypto and works everywhere.
+ */
+
+import { generateKeyPairSync, sign, createPrivateKey } from 'crypto';
+
+/**
+ * Generate a new Ed25519 keypair for use with Provenance identity.
+ *
+ * Run this once during agent setup. Add the public key to PROVENANCE.yml.
+ * Store the private key securely as an environment variable.
+ *
+ * @returns {{ publicKey: string, privateKey: string }}
+ *   publicKey  — base64-encoded SPKI DER. Goes in PROVENANCE.yml identity.public_key
+ *   privateKey — base64-encoded PKCS8 DER. Store as PROVENANCE_PRIVATE_KEY env var
+ *
+ * Example:
+ *   const { publicKey, privateKey } = generateProvenanceKeyPair();
+ *   console.log('Add to PROVENANCE.yml:');
+ *   console.log('identity:');
+ *   console.log(`  public_key: "${publicKey}"`);
+ *   console.log('\nStore as environment variable:');
+ *   console.log(`PROVENANCE_PRIVATE_KEY=${privateKey}`);
+ */
+export function generateProvenanceKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'der' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'der' },
+  });
+
+  return {
+    publicKey: Buffer.from(publicKey).toString('base64'),
+    privateKey: Buffer.from(privateKey).toString('base64'),
+  };
+}
+
+/**
+ * Sign a challenge from a receiving system.
+ *
+ * Call this when a receiving system sends you a nonce to prove your identity.
+ * The signed message is always `${provenanceId}:${nonce}` — this binds the
+ * signature to your specific identity and prevents replay attacks.
+ *
+ * @param {string} privateKeyBase64  Your PROVENANCE_PRIVATE_KEY (base64 PKCS8 DER)
+ * @param {string} provenanceId     Your provenance ID, e.g. "provenance:github:alice/agent"
+ * @param {string} nonce            The nonce sent by the receiving system
+ * @returns {string}                Base64-encoded signature to return to the receiver
+ *
+ * Example:
+ *   app.post('/prove-identity', (req, res) => {
+ *     const { provenanceId, nonce } = req.body;
+ *     const signature = signChallenge(
+ *       process.env.PROVENANCE_PRIVATE_KEY,
+ *       provenanceId,
+ *       nonce
+ *     );
+ *     res.json({ signature });
+ *   });
+ */
+export function signChallenge(privateKeyBase64, provenanceId, nonce) {
+  const keyBuffer = Buffer.from(privateKeyBase64, 'base64');
+  const privateKey = createPrivateKey({ key: keyBuffer, format: 'der', type: 'pkcs8' });
+  const message = Buffer.from(`${provenanceId}:${nonce}`, 'utf8');
+  return sign(null, message, privateKey).toString('base64');
+}
+
+/**
+ * Sign your PROVENANCE.yml identity claim.
+ *
+ * Call this once after generating your keypair to produce the `identity.signature`
+ * value that goes into PROVENANCE.yml. The signature proves you control the private
+ * key that matches the public key in the file.
+ *
+ * The signed message is `${provenanceId}:${publicKeyBase64}` — this binds the key
+ * pair to your specific Provenance ID, preventing key reuse across identities.
+ *
+ * @param {string} privateKeyBase64  Your PROVENANCE_PRIVATE_KEY (base64 PKCS8 DER)
+ * @param {string} provenanceId     Your agent's Provenance ID, e.g. "provenance:github:alice/agent"
+ * @param {string} publicKeyBase64  The public key you're registering (base64 SPKI DER)
+ * @returns {string}                Base64-encoded signature — put this in identity.signature
+ *
+ * Example (one-time setup):
+ *   import { generateProvenanceKeyPair, signForProvenance } from 'provenance-protocol/keygen';
+ *   const { publicKey, privateKey } = generateProvenanceKeyPair();
+ *   const id = 'provenance:github:your-org/your-agent';
+ *   const signature = signForProvenance(privateKey, id, publicKey);
+ *   console.log('Add to PROVENANCE.yml:');
+ *   console.log('identity:');
+ *   console.log(`  public_key: "${publicKey}"`);
+ *   console.log(`  signature: "${signature}"`);
+ */
+/**
+ * Sign a revocation request.
+ *
+ * Call this when you want to revoke your agent's cryptographic identity —
+ * e.g. if your private key was compromised or you're rotating keys.
+ *
+ * @param {string} privateKeyBase64  Your current PROVENANCE_PRIVATE_KEY
+ * @param {string} provenanceId     Your agent's Provenance ID
+ * @returns {string}                Base64 signature — send as signed_challenge to POST /api/agents/revoke
+ *
+ * Example:
+ *   import { signRevocation } from 'provenance-protocol/keygen';
+ *   const signed_challenge = signRevocation(process.env.PROVENANCE_PRIVATE_KEY, provenanceId);
+ *   await fetch('https://getprovenance.dev/api/agents/revoke', {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify({ provenance_id: provenanceId, signed_challenge }),
+ *   });
+ */
+export function signRevocation(privateKeyBase64, provenanceId) {
+  return signChallenge(privateKeyBase64, provenanceId, 'REVOKE');
+}
+
+export function signForProvenance(privateKeyBase64, provenanceId, publicKeyBase64) {
+  const keyBuffer = Buffer.from(privateKeyBase64, 'base64');
+  const privateKey = createPrivateKey({ key: keyBuffer, format: 'der', type: 'pkcs8' });
+  const message = Buffer.from(`${provenanceId}:${publicKeyBase64}`, 'utf8');
+  return sign(null, message, privateKey).toString('base64');
+}