provenance-protocol 0.1.1 → 0.1.2

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.2",
   "description": "SDK for querying the Provenance agent identity index",
   "type": "module",
   "main": "./src/index.js",
@@ -29,7 +29,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 }}
    */