provenance-protocol 0.1.4 → 0.2.1

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/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 };

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>;