@peac/protocol 0.11.1 → 0.11.3

package/README.md

@@ -1,6 +1,6 @@
 # @peac/protocol
 
-PEAC protocol implementation - receipt issuance and verification
+PEAC protocol implementation: receipt issuance, offline verification, and JWKS resolution.
 
 ## Installation
 
@@ -8,9 +8,74 @@ PEAC protocol implementation - receipt issuance and verification
 pnpm add @peac/protocol
 ```
 
-## Documentation
+## What It Does
 
-See [peacprotocol.org](https://www.peacprotocol.org) for full documentation.
+`@peac/protocol` is Layer 3 of the PEAC stack. It provides `issue()` for signing receipts and `verifyLocal()` for offline verification with Ed25519 public keys. No network calls needed for verification.
+
+## How Do I Issue a Receipt?
+
+```typescript
+import { generateKeypair } from '@peac/crypto';
+import { issue } from '@peac/protocol';
+
+const { publicKey, privateKey } = await generateKeypair();
+
+const { jws } = await issue({
+  iss: 'https://api.example.com',
+  aud: 'https://client.example.com',
+  amt: 100,
+  cur: 'USD',
+  rail: 'stripe',
+  reference: 'pi_abc123',
+  privateKey,
+  kid: 'key-2026-02',
+});
+```
+
+## How Do I Verify a Receipt?
+
+```typescript
+import { verifyLocal } from '@peac/protocol';
+
+const result = await verifyLocal(jws, publicKey);
+
+if (result.valid && result.variant === 'commerce') {
+  console.log(result.claims.iss); // issuer
+  console.log(result.claims.amt); // amount
+  console.log(result.claims.cur); // currency
+} else if (!result.valid) {
+  console.log(result.code, result.message);
+}
+```
+
+## How Do I Verify with JWKS Discovery?
+
+```typescript
+import { verifyReceipt } from '@peac/protocol';
+
+// Resolves issuer's /.well-known/peac-issuer.json -> jwks_uri -> public key
+const result = await verifyReceipt(jws);
+
+if (result.ok) {
+  console.log('Issuer:', result.claims.iss);
+} else {
+  console.log(result.reason, result.details);
+}
+```
+
+## Integrates With
+
+- `@peac/crypto` (Layer 2): Ed25519 key generation and JWS encoding
+- `@peac/kernel` (Layer 0): Error codes and wire format constants
+- `@peac/schema` (Layer 1): Receipt claim validation
+- `@peac/mcp-server` (Layer 5): MCP tool server using protocol functions
+- `@peac/middleware-express` (Layer 3.5): Express middleware for automatic receipt issuance
+
+## Security
+
+- Verification is offline and deterministic: no network calls for `verifyLocal()`
+- Fail-closed: invalid or missing evidence always produces a verification failure
+- JWKS resolution (when used) is SSRF-hardened with HTTPS-only, private IP denial
 
 ## License
 

package/dist/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EAMd,MAAM,cAAc,CAAC;AAMtB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,gBAAgB,CAsFzE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsCpF;AAiBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAoD1F;AAkFD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+CtF;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAkD1D;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA2B9E"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EAOd,MAAM,cAAc,CAAC;AAMtB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,gBAAgB,CAoGzE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsCpF;AAiBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAoD1F;AAkFD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+CtF;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAkD1D;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA2B9E"}

package/dist/index.cjs

@@ -238,6 +238,17 @@ function parseIssuerConfig(json) {
       throw new Error("payment_rails must be an array");
     }
   }
+  let revokedKeys;
+  if (obj.revoked_keys !== void 0) {
+    if (!Array.isArray(obj.revoked_keys)) {
+      throw new Error("revoked_keys must be an array");
+    }
+    const result = schema.validateRevokedKeys(obj.revoked_keys);
+    if (!result.ok) {
+      throw new Error(`Invalid revoked_keys: ${result.error}`);
+    }
+    revokedKeys = result.value;
+  }
   return {
     version: obj.version,
     issuer: obj.issuer,
@@ -246,7 +257,8 @@ function parseIssuerConfig(json) {
     receipt_versions: obj.receipt_versions,
     algorithms: obj.algorithms,
     payment_rails: obj.payment_rails,
-    security_contact: obj.security_contact
+    security_contact: obj.security_contact,
+    revoked_keys: revokedKeys
   };
 }
 async function fetchIssuerConfig(issuerUrl) {
@@ -933,6 +945,53 @@ async function fetchPointerSafe(pointerUrl, options) {
 var DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
 var DEFAULT_MAX_CACHE_ENTRIES = 1e3;
 var jwksCache = /* @__PURE__ */ new Map();
+var KID_RETENTION_MS = 30 * 24 * 60 * 60 * 1e3;
+var MAX_KID_THUMBPRINT_ENTRIES = 1e4;
+var kidThumbprints = /* @__PURE__ */ new Map();
+function pruneExpiredKidEntries(now) {
+  for (const [key, entry] of kidThumbprints) {
+    if (now - entry.firstSeen >= KID_RETENTION_MS) {
+      kidThumbprints.delete(key);
+    }
+  }
+}
+function evictOldestKidEntries() {
+  if (kidThumbprints.size <= MAX_KID_THUMBPRINT_ENTRIES) return;
+  const entries = Array.from(kidThumbprints.entries()).sort(
+    (a, b) => a[1].firstSeen - b[1].firstSeen
+  );
+  const toRemove = kidThumbprints.size - MAX_KID_THUMBPRINT_ENTRIES;
+  for (let i = 0; i < toRemove; i++) {
+    kidThumbprints.delete(entries[i][0]);
+  }
+}
+function checkKidReuse(issuer, jwks, now) {
+  pruneExpiredKidEntries(now);
+  for (const key of jwks.keys) {
+    if (!key.kid || !key.x) continue;
+    const mapKey = `${issuer}|${key.kid}`;
+    const existing = kidThumbprints.get(mapKey);
+    if (existing) {
+      if (now - existing.firstSeen < KID_RETENTION_MS) {
+        if (existing.thumbprint !== key.x) {
+          return `Kid reuse detected: kid=${key.kid} for issuer ${issuer} maps to different key material`;
+        }
+      } else {
+        kidThumbprints.set(mapKey, { thumbprint: key.x, firstSeen: now });
+      }
+    } else {
+      kidThumbprints.set(mapKey, { thumbprint: key.x, firstSeen: now });
+    }
+  }
+  evictOldestKidEntries();
+  return null;
+}
+function clearKidThumbprints() {
+  kidThumbprints.clear();
+}
+function getKidThumbprintSize() {
+  return kidThumbprints.size;
+}
 function cacheGet(key, now) {
   const entry = jwksCache.get(key);
   if (!entry) return void 0;
@@ -1021,7 +1080,7 @@ async function resolveJWKS(issuerUrl, options) {
   if (!noCache) {
     const cached = cacheGet(normalizedIssuer, now);
     if (cached) {
-      return { ok: true, jwks: cached.jwks, fromCache: true };
+      return { ok: true, jwks: cached.jwks, fromCache: true, revokedKeys: cached.revokedKeys };
     }
   }
   if (!normalizedIssuer.startsWith("https://")) {
@@ -1116,14 +1175,28 @@ async function resolveJWKS(issuerUrl, options) {
       message: `JWKS has too many keys: ${jwks.keys.length} > ${kernel.VERIFIER_LIMITS.maxJwksKeys}`
     };
   }
+  const kidReuseError = checkKidReuse(normalizedIssuer, jwks, now);
+  if (kidReuseError) {
+    return {
+      ok: false,
+      code: "E_KID_REUSE_DETECTED",
+      message: kidReuseError
+    };
+  }
+  const revokedKeys = issuerConfig.revoked_keys?.map((entry) => ({
+    kid: entry.kid,
+    revoked_at: entry.revoked_at,
+    reason: entry.reason
+  }));
   if (!noCache) {
-    cacheSet(normalizedIssuer, { jwks, expiresAt: now + cacheTtlMs }, maxCacheEntries);
+    cacheSet(normalizedIssuer, { jwks, expiresAt: now + cacheTtlMs, revokedKeys }, maxCacheEntries);
   }
   return {
     ok: true,
     jwks,
     fromCache: false,
-    rawBytes: jwksResult.rawBytes
+    rawBytes: jwksResult.rawBytes,
+    revokedKeys
   };
 }
 
@@ -1184,6 +1257,25 @@ async function verifyReceipt(optionsOrJws) {
     if (!jwksResult.fromCache) {
       jwksFetchTime = performance.now() - jwksFetchStart;
     }
+    if (jwksResult.revokedKeys) {
+      const revokedEntry = jwksResult.revokedKeys.find((rk) => rk.kid === header.kid);
+      if (revokedEntry) {
+        const durationMs = performance.now() - startTime;
+        fireTelemetryHook(telemetry?.onReceiptVerified, {
+          receiptHash: hashReceipt(receiptJws),
+          valid: false,
+          reasonCode: "key_revoked",
+          issuer: payload.iss,
+          kid: header.kid,
+          durationMs
+        });
+        return {
+          ok: false,
+          reason: "key_revoked",
+          details: `Key kid=${header.kid} was revoked at ${revokedEntry.revoked_at}${revokedEntry.reason ? ` (reason: ${revokedEntry.reason})` : ""}`
+        };
+      }
+    }
     const jwk = jwksResult.jwks.keys.find((k) => k.kid === header.kid);
     if (!jwk) {
       const durationMs = performance.now() - startTime;
@@ -2770,6 +2862,7 @@ exports.VerificationReportBuilder = VerificationReportBuilder;
 exports.buildFailureReport = buildFailureReport;
 exports.buildSuccessReport = buildSuccessReport;
 exports.clearJWKSCache = clearJWKSCache;
+exports.clearKidThumbprints = clearKidThumbprints;
 exports.computeReceiptDigest = computeReceiptDigest;
 exports.createDefaultPolicy = createDefaultPolicy;
 exports.createDigest = createDigest;
@@ -2782,6 +2875,7 @@ exports.fetchPointerSafe = fetchPointerSafe;
 exports.fetchPointerWithDigest = fetchPointerWithDigest;
 exports.fetchPolicyManifest = fetchPolicyManifest;
 exports.getJWKSCacheSize = getJWKSCacheSize;
+exports.getKidThumbprintSize = getKidThumbprintSize;
 exports.getPurposeHeader = getPurposeHeader;
 exports.getReceiptHeader = getReceiptHeader;
 exports.getSSRFCapabilities = getSSRFCapabilities;