provenance-protocol 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # provenance-protocol
 
-SDK for querying the [Provenance](https://provenance.dev) agent identity index.
+SDK for querying the [Provenance](https://getprovenance.dev) agent identity index.
 
 Drop this into any receiving system — marketplace, API, agent orchestrator —
 to verify an AI agent's identity and trust profile before allowing it in.
@@ -127,8 +127,88 @@ if (result.fallback) {
 | `incidents` | number | Number of open incidents |
 | `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 |
 
 ---
 
-## MIT License — provenance.dev
+## Registering your own agent
+
+```js
+import { Provenance } from 'provenance-protocol';
+import { generateProvenanceKeyPair, signChallenge } from 'provenance-protocol/keygen';
+
+const provenance = new Provenance();
+
+// One-time: generate a keypair
+const { publicKey, privateKey } = generateProvenanceKeyPair();
+// Store privateKey as PROVENANCE_PRIVATE_KEY env var — never commit it
+
+// Sign proof of key ownership for registration
+const provenanceId = 'provenance:github:your-org/your-agent';
+const signed_challenge = signChallenge(privateKey, provenanceId, 'REGISTER');
+
+await provenance.register({
+  id: provenanceId,
+  url: 'https://github.com/your-org/your-agent',
+  name: 'Your Agent',
+  description: 'What it does',
+  capabilities: ['read:web', 'write:summaries'],
+  constraints: ['no:pii'],
+  public_key: publicKey,
+  signed_challenge,          // proves you control the private key
+});
+// → { created: true, identity_verified: true, confidence: 1.0 }
+```
+
+## Revoking a compromised key
+
+```js
+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 }),
+});
+// Then generate a new keypair and re-register
+```
+
+---
+
+## CLI
+
+```bash
+npx provenance keygen
+npx provenance register --id provenance:github:your-org/your-agent --url https://github.com/...
+npx provenance status provenance:github:alice/my-agent
+npx provenance validate PROVENANCE.yml
+npx provenance revoke --id provenance:github:your-org/your-agent
+```
+
+Full CLI reference: [getprovenance.dev/docs#cli](https://getprovenance.dev/docs#cli)
+
+---
+
+## Layers
+
+`provenance-protocol` is the identity layer. Protocols that build on it:
+
+| Package | Purpose |
+|---|---|
+| `provenance-protocol` | Agent identity, trust, and registration (this package) |
+| [`ajp-protocol`](https://www.npmjs.com/package/ajp-protocol) | Agent Job Protocol — agent-to-agent job delegation |
+
+---
+
+## Full documentation
+
+[getprovenance.dev/docs](https://getprovenance.dev/docs)
+
+---
+
+## MIT License — getprovenance.dev

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "provenance-protocol",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "SDK for querying the Provenance agent identity index",
   "type": "module",
   "main": "./src/index.js",
@@ -9,11 +9,17 @@
     ".": {
       "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",
     "README.md"
   ],
   "keywords": [
@@ -29,7 +35,7 @@
     "type": "git",
     "url": "https://github.com/ilucky21c/provenance-protocol"
   },
-  "homepage": "https://provenance.dev",
+  "homepage": "https://getprovenance.dev",
   "engines": {
     "node": ">=14.0.0"
   }

package/src/index.d.ts

@@ -164,7 +164,17 @@ export interface RegisterProfile {
   model_id?: string;
   contact_url?: string;
   ajp_endpoint?: string;
+  /**
+   * Base64-encoded Ed25519 SPKI DER public key.
+   * When provided, signed_challenge is also required.
+   */
   public_key?: string;
+  /**
+   * Base64 Ed25519 signature of `${provenance_id}:REGISTER` using your private key.
+   * Required when public_key is provided — proves you control the key you're registering.
+   * Generate with: signChallenge(privateKey, provenanceId, 'REGISTER') from provenance-protocol/keygen
+   */
+  signed_challenge?: string;
   version?: string;
 }
 

package/src/index.js

@@ -44,7 +44,7 @@ async function _verifyEd25519(publicKeyBase64, signatureBase64, message) {
   return subtle.verify('Ed25519', cryptoKey, sigBuffer, msgBuffer);
 }
 
-const DEFAULT_API = 'https://provenance.dev';
+const DEFAULT_API = 'https://getprovenance.dev';
 const DEFAULT_CACHE_TTL = 300; // 5 minutes
 
 // Simple LRU cache
@@ -100,9 +100,10 @@ export class Provenance {
    *   const trust = await provenance.check('provenance:github:alice/research-assistant');
    *   // {
    *   //   found: true,
-   *   //   declared: true,       — has PROVENANCE.yml
-   *   //   age_days: 142,        — how long this agent has existed publicly
-   *   //   confidence: 0.9,
+   *   //   declared: true,            — has PROVENANCE.yml
+   *   //   identity_verified: true,   — cryptographic proof of ownership
+   *   //   age_days: 142,             — how long this agent has existed publicly
+   *   //   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,
@@ -132,6 +133,7 @@ export class Provenance {
         platform: data.platform,
         name: data.name,
         declared: data.declared,
+        identity_verified: data.identity_verified || false,
         confidence: data.confidence,
         age_days: data.timestamps?.first_seen
           ? Math.floor((Date.now() - new Date(data.timestamps.first_seen)) / 86400000)
@@ -510,7 +512,6 @@ export class Provenance {
     // → github/alice/research-assistant
     return provenanceId.replace('provenance:', '').replace(':', '/');
   }
-}
 
   // ── Self-registration ─────────────────────────────────────────────────────
 
@@ -518,30 +519,28 @@ export class Provenance {
    * Register or update this agent in the Provenance index.
    * Call once at agent startup — idempotent, safe to call on every boot.
    *
-   * Example:
-   *   import { provenance } from 'provenance-protocol';
-   *
-   *   await provenance.register({
-   *     id: 'provenance:github:your-org/your-agent',
-   *     url: 'https://github.com/your-org/your-agent',
-   *     name: 'Your Agent',
-   *     description: 'What it does',
-   *     capabilities: ['read:web', 'write:summaries'],
-   *     constraints: ['no:pii', 'no:financial:transact'],
-   *   });
+   * To register with cryptographic proof (identity_verified: true, confidence: 1.0),
+   * provide public_key and signed_challenge:
+   *   import { signChallenge } from 'provenance-protocol/keygen';
+   *   const signed_challenge = signChallenge(process.env.PROVENANCE_PRIVATE_KEY, id, 'REGISTER');
    *
    * @param {object} profile
-   * @param {string} profile.id            provenance:<platform>:<owner>/<name>
-   * @param {string} profile.url           Canonical URL (GitHub repo, package page, etc.)
-   * @param {string} [profile.name]        Display name
-   * @param {string} [profile.description] One-sentence description
+   * @param {string} profile.id              provenance:<platform>:<owner>/<name>
+   *                                         Platforms: github, huggingface, npm, pypi, clawmarket, custom
+   *                                         Use "custom" for private agents without a public repo.
+   * @param {string} [profile.url]           Canonical URL. Optional for custom platform agents.
+   * @param {string} [profile.readme_summary] 2-3 sentence plain-English description shown on profile.
+   *                                          For private agents without a README — write it yourself.
+   * @param {string} [profile.name]          Display name
+   * @param {string} [profile.description]   One-sentence description
    * @param {string[]} [profile.capabilities]
    * @param {string[]} [profile.constraints]
    * @param {string} [profile.model_provider]
    * @param {string} [profile.model_id]
    * @param {string} [profile.contact_url]
    * @param {string} [profile.ajp_endpoint]
-   * @param {string} [profile.public_key]  Ed25519 public key: "ed25519:<base64>"
+   * @param {string} [profile.public_key]    Ed25519 SPKI DER public key (base64)
+   * @param {string} [profile.signed_challenge] Signature of `${id}:REGISTER` — required with public_key
    * @param {string} [profile.version]
    * @returns {{ created: boolean, updated: boolean, agent: object }}
    */

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');
+}