@scopeblind/passport 0.3.0

package/README.md

@@ -0,0 +1,184 @@
+# @scopeblind/passport
+
+Portable cryptographic identity for AI agents and coaches. Ed25519 keypairs, immutable manifests, ownership attestations, and verifiable evidence receipts.
+
+## Why
+
+Machine decisions need portable, verifiable proof. This SDK provides the identity layer: agents and coaches get Ed25519 keypairs, sign immutable manifests declaring their capabilities, and produce receipts that anyone can verify without calling ScopeBlind.
+
+- **Portable** — Export a passport bundle to any platform. No vendor lock-in.
+- **Verifiable** — Ed25519 signatures over canonical JSON. Verify offline, no API calls.
+- **Privacy-preserving** — No PII required. Identity is a key fingerprint.
+
+## Install
+
+```bash
+npm install @scopeblind/passport
+```
+
+Requires Node.js >= 18. Browser entrypoint available at `@scopeblind/passport/browser`.
+
+## Quick Start
+
+```typescript
+import {
+  generatePassportKey,
+  createCoachManifest,
+  verifyManifest,
+} from '@scopeblind/passport';
+
+// 1. Generate an Ed25519 keypair
+const key = generatePassportKey('coach');
+console.log(key.kid); // sb:coach:7Xq9...
+
+// 2. Create an immutable manifest
+const manifest = createCoachManifest(key, {
+  display_name: 'Atlas Nova',
+  model_family: 'claude',
+  system_prompt_hash: 'sha256:a1b2c3...',
+  capabilities: ['debate', 'analysis'],
+});
+
+// 3. Verify the signature
+const result = verifyManifest(manifest);
+console.log(result.valid); // true
+```
+
+## API
+
+### Key Generation
+
+```typescript
+// Generate a new Ed25519 keypair for a coach or agent
+const coachKey = generatePassportKey('coach');
+const agentKey = generatePassportKey('agent');
+
+// Derive a passport ID from an existing public key
+const kid = derivePassportId('coach', publicKeyBytes);
+// => "sb:coach:7Xq9kM..."
+```
+
+### Manifests
+
+Manifests are **immutable once signed**. Config changes produce a new version.
+
+```typescript
+// Coach manifest (for AI coaches/tutors)
+const manifest = createCoachManifest(key, {
+  display_name: 'Atlas Nova',
+  model_family: 'claude',
+  system_prompt_hash: 'sha256:...',
+  capabilities: ['debate', 'analysis', 'coaching'],
+});
+
+// Agent manifest (for autonomous AI agents)
+const agentManifest = createAgentManifest(key, {
+  display_name: 'Research Bot',
+  model_family: 'gpt-4',
+  tool_names: ['web_search', 'file_read'],
+  max_actions_per_turn: 10,
+});
+
+// Verify any manifest
+const result = verifyManifest(manifest);
+// { valid: true, kid: 'sb:coach:...', type: 'scopeblind:coach-manifest' }
+```
+
+### Ownership Attestations
+
+Prove a coach owns an agent (or vice versa):
+
+```typescript
+const attestation = createOwnershipAttestation(coachKey, {
+  subject_kid: agentKey.kid,
+  relationship: 'owns',
+});
+```
+
+### Evidence Receipts
+
+Sign verifiable evidence of machine decisions:
+
+```typescript
+import {
+  generateIssuerKey,
+  signReceipt,
+  createArenaBattleReceipt,
+} from '@scopeblind/passport';
+
+// Generate an issuer keypair (server-side)
+const issuer = generateIssuerKey();
+
+// Sign a battle receipt
+const receipt = createArenaBattleReceipt(issuer, {
+  battle_id: 'battle_abc123',
+  arena_id: 'blindllm',
+  participants: [
+    { kid: coach1.kid, role: 'coach', model_family: 'claude' },
+    { kid: coach2.kid, role: 'coach', model_family: 'gpt-4' },
+  ],
+  outcome: { winner_kid: coach1.kid, method: 'judge_decision' },
+});
+
+// Anyone can verify the receipt
+const verified = verifyEnvelope(receipt);
+```
+
+### Portable Export/Import
+
+Export a passport for migration to another platform:
+
+```typescript
+import {
+  exportPassportBundle,
+  serializeBundle,
+  importPassportBundle,
+} from '@scopeblind/passport';
+
+// Export (includes secret key — handle securely)
+const bundle = exportPassportBundle(key, manifest);
+const json = serializeBundle(bundle);
+
+// Import on another platform
+const imported = importPassportBundle(json);
+console.log(imported.key.kid); // same kid, different machine
+```
+
+### Display Helpers
+
+```typescript
+import { formatKidShort, getCoachSummary } from '@scopeblind/passport';
+
+formatKidShort('sb:coach:7Xq9kMvR...'); // "7Xq9kM"
+getCoachSummary(manifest); // "Atlas Nova (claude) — sb:coach:7Xq9kM"
+```
+
+### Browser Entrypoint
+
+For browser environments (uses IndexedDB for key storage):
+
+```typescript
+import { ... } from '@scopeblind/passport/browser';
+```
+
+## Types
+
+All types are exported and fully documented:
+
+- `PassportKeyPair` — Ed25519 keypair with kid and role
+- `CoachManifest` / `AgentManifest` — Immutable signed manifests
+- `OwnershipAttestation` — Cross-key ownership proof
+- `SignedEnvelope` — Canonical JSON wrapper with Ed25519 signature
+- `ArenaBattleReceipt` / `CoachUpliftReceipt` / `FormalDebateReceipt` — Evidence types
+- `PortablePassportBundle` — Exportable passport + manifest bundle
+
+## Design Decisions
+
+- **Ed25519 only** — Single algorithm, no negotiation. P-256 DPoP bindings reserved for future lease validation.
+- **Canonical JSON** — Deterministic serialization (ASCII-only keys, sorted). Same input always produces same bytes.
+- **Immutable manifests** — Config changes produce a new version with `previous_version` link. No in-place mutation.
+- **No blockchain** — Verification is pure cryptography. No tokens, no chain, no consensus.
+
+## License
+
+FSL-1.1-MIT — Source-available, converts to MIT after 2 years.

package/dist/browser.d.mts

@@ -0,0 +1,44 @@
+import { P as PassportBundle, a as PassportKeyPair, S as SignedEnvelope, M as Manifest } from './types-DHZHv2EE.mjs';
+
+/**
+ * @scopeblind/passport — Browser Storage Adapter
+ *
+ * IndexedDB-based storage for passport keys and manifests.
+ * Separate from core package — import from '@scopeblind/passport/browser'.
+ */
+
+/**
+ * Store a passport keypair in IndexedDB.
+ */
+declare function storeKey(key: PassportKeyPair): Promise<void>;
+/**
+ * Load a passport keypair by kid.
+ */
+declare function loadKey(kid: string): Promise<PassportKeyPair | null>;
+/**
+ * Load the first coach passport found (for single-coach UX).
+ */
+declare function loadCoachKey(): Promise<PassportKeyPair | null>;
+/**
+ * List all stored passport keys.
+ */
+declare function listKeys(): Promise<PassportKeyPair[]>;
+/**
+ * Store a signed manifest.
+ */
+declare function storeManifest(envelope: SignedEnvelope<Manifest>): Promise<void>;
+/**
+ * Load a manifest by passport ID.
+ */
+declare function loadManifest(passportId: string): Promise<SignedEnvelope<Manifest> | null>;
+/**
+ * Export all passport data as a PassportBundle (unencrypted).
+ * Encryption (EncryptedPassportBundle) is Sprint 3.
+ */
+declare function exportAllPassports(): Promise<PassportBundle[]>;
+/**
+ * Clear all passport data from IndexedDB.
+ */
+declare function clearAll(): Promise<void>;
+
+export { clearAll, exportAllPassports, listKeys, loadCoachKey, loadKey, loadManifest, storeKey, storeManifest };

package/dist/browser.d.ts

@@ -0,0 +1,44 @@
+import { P as PassportBundle, a as PassportKeyPair, S as SignedEnvelope, M as Manifest } from './types-DHZHv2EE.js';
+
+/**
+ * @scopeblind/passport — Browser Storage Adapter
+ *
+ * IndexedDB-based storage for passport keys and manifests.
+ * Separate from core package — import from '@scopeblind/passport/browser'.
+ */
+
+/**
+ * Store a passport keypair in IndexedDB.
+ */
+declare function storeKey(key: PassportKeyPair): Promise<void>;
+/**
+ * Load a passport keypair by kid.
+ */
+declare function loadKey(kid: string): Promise<PassportKeyPair | null>;
+/**
+ * Load the first coach passport found (for single-coach UX).
+ */
+declare function loadCoachKey(): Promise<PassportKeyPair | null>;
+/**
+ * List all stored passport keys.
+ */
+declare function listKeys(): Promise<PassportKeyPair[]>;
+/**
+ * Store a signed manifest.
+ */
+declare function storeManifest(envelope: SignedEnvelope<Manifest>): Promise<void>;
+/**
+ * Load a manifest by passport ID.
+ */
+declare function loadManifest(passportId: string): Promise<SignedEnvelope<Manifest> | null>;
+/**
+ * Export all passport data as a PassportBundle (unencrypted).
+ * Encryption (EncryptedPassportBundle) is Sprint 3.
+ */
+declare function exportAllPassports(): Promise<PassportBundle[]>;
+/**
+ * Clear all passport data from IndexedDB.
+ */
+declare function clearAll(): Promise<void>;
+
+export { clearAll, exportAllPassports, listKeys, loadCoachKey, loadKey, loadManifest, storeKey, storeManifest };

package/dist/browser.js

@@ -0,0 +1,180 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/browser.ts
+var browser_exports = {};
+__export(browser_exports, {
+  clearAll: () => clearAll,
+  exportAllPassports: () => exportAllPassports,
+  listKeys: () => listKeys,
+  loadCoachKey: () => loadCoachKey,
+  loadKey: () => loadKey,
+  loadManifest: () => loadManifest,
+  storeKey: () => storeKey,
+  storeManifest: () => storeManifest
+});
+module.exports = __toCommonJS(browser_exports);
+var DB_NAME = "scopeblind-passport";
+var DB_VERSION = 1;
+var STORE_KEYS = "keys";
+var STORE_MANIFESTS = "manifests";
+var STORE_ATTESTATIONS = "attestations";
+var STORE_STATUS = "status";
+function openDB() {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_KEYS)) {
+        db.createObjectStore(STORE_KEYS, { keyPath: "kid" });
+      }
+      if (!db.objectStoreNames.contains(STORE_MANIFESTS)) {
+        db.createObjectStore(STORE_MANIFESTS, { keyPath: "payload.id" });
+      }
+      if (!db.objectStoreNames.contains(STORE_ATTESTATIONS)) {
+        db.createObjectStore(STORE_ATTESTATIONS, { autoIncrement: true });
+      }
+      if (!db.objectStoreNames.contains(STORE_STATUS)) {
+        db.createObjectStore(STORE_STATUS, { autoIncrement: true });
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+function serializeKey(key) {
+  return {
+    kid: key.kid,
+    role: key.role,
+    created_at: key.created_at,
+    publicKey: Array.from(key.publicKey),
+    secretKey: Array.from(key.secretKey)
+  };
+}
+function deserializeKey(stored) {
+  return {
+    kid: stored.kid,
+    role: stored.role,
+    created_at: stored.created_at,
+    publicKey: new Uint8Array(stored.publicKey),
+    secretKey: new Uint8Array(stored.secretKey)
+  };
+}
+async function storeKey(key) {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_KEYS, "readwrite");
+    tx.objectStore(STORE_KEYS).put(serializeKey(key));
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+async function loadKey(kid) {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_KEYS, "readonly");
+    const request = tx.objectStore(STORE_KEYS).get(kid);
+    request.onsuccess = () => {
+      resolve(request.result ? deserializeKey(request.result) : null);
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+async function loadCoachKey() {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_KEYS, "readonly");
+    const request = tx.objectStore(STORE_KEYS).getAll();
+    request.onsuccess = () => {
+      const keys = (request.result || []).map(deserializeKey);
+      const coach = keys.find((k) => k.role === "coach");
+      resolve(coach || null);
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+async function listKeys() {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_KEYS, "readonly");
+    const request = tx.objectStore(STORE_KEYS).getAll();
+    request.onsuccess = () => {
+      resolve((request.result || []).map(deserializeKey));
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+async function storeManifest(envelope) {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_MANIFESTS, "readwrite");
+    tx.objectStore(STORE_MANIFESTS).put(envelope);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+async function loadManifest(passportId) {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_MANIFESTS, "readonly");
+    const request = tx.objectStore(STORE_MANIFESTS).get(passportId);
+    request.onsuccess = () => resolve(request.result || null);
+    request.onerror = () => reject(request.error);
+  });
+}
+async function exportAllPassports() {
+  const keys = await listKeys();
+  const bundles = [];
+  for (const key of keys) {
+    const manifest = await loadManifest(key.kid);
+    bundles.push({
+      key,
+      manifests: manifest ? [manifest] : [],
+      ownership_attestations: [],
+      status_records: []
+    });
+  }
+  return bundles;
+}
+async function clearAll() {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(
+      [STORE_KEYS, STORE_MANIFESTS, STORE_ATTESTATIONS, STORE_STATUS],
+      "readwrite"
+    );
+    tx.objectStore(STORE_KEYS).clear();
+    tx.objectStore(STORE_MANIFESTS).clear();
+    tx.objectStore(STORE_ATTESTATIONS).clear();
+    tx.objectStore(STORE_STATUS).clear();
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearAll,
+  exportAllPassports,
+  listKeys,
+  loadCoachKey,
+  loadKey,
+  loadManifest,
+  storeKey,
+  storeManifest
+});

package/dist/browser.mjs

@@ -0,0 +1,148 @@
+// src/browser.ts
+var DB_NAME = "scopeblind-passport";
+var DB_VERSION = 1;
+var STORE_KEYS = "keys";
+var STORE_MANIFESTS = "manifests";
+var STORE_ATTESTATIONS = "attestations";
+var STORE_STATUS = "status";
+function openDB() {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_KEYS)) {
+        db.createObjectStore(STORE_KEYS, { keyPath: "kid" });
+      }
+      if (!db.objectStoreNames.contains(STORE_MANIFESTS)) {
+        db.createObjectStore(STORE_MANIFESTS, { keyPath: "payload.id" });
+      }
+      if (!db.objectStoreNames.contains(STORE_ATTESTATIONS)) {
+        db.createObjectStore(STORE_ATTESTATIONS, { autoIncrement: true });
+      }
+      if (!db.objectStoreNames.contains(STORE_STATUS)) {
+        db.createObjectStore(STORE_STATUS, { autoIncrement: true });
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+function serializeKey(key) {
+  return {
+    kid: key.kid,
+    role: key.role,
+    created_at: key.created_at,
+    publicKey: Array.from(key.publicKey),
+    secretKey: Array.from(key.secretKey)
+  };
+}
+function deserializeKey(stored) {
+  return {
+    kid: stored.kid,
+    role: stored.role,
+    created_at: stored.created_at,
+    publicKey: new Uint8Array(stored.publicKey),
+    secretKey: new Uint8Array(stored.secretKey)
+  };
+}
+async function storeKey(key) {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_KEYS, "readwrite");
+    tx.objectStore(STORE_KEYS).put(serializeKey(key));
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+async function loadKey(kid) {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_KEYS, "readonly");
+    const request = tx.objectStore(STORE_KEYS).get(kid);
+    request.onsuccess = () => {
+      resolve(request.result ? deserializeKey(request.result) : null);
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+async function loadCoachKey() {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_KEYS, "readonly");
+    const request = tx.objectStore(STORE_KEYS).getAll();
+    request.onsuccess = () => {
+      const keys = (request.result || []).map(deserializeKey);
+      const coach = keys.find((k) => k.role === "coach");
+      resolve(coach || null);
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+async function listKeys() {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_KEYS, "readonly");
+    const request = tx.objectStore(STORE_KEYS).getAll();
+    request.onsuccess = () => {
+      resolve((request.result || []).map(deserializeKey));
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+async function storeManifest(envelope) {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_MANIFESTS, "readwrite");
+    tx.objectStore(STORE_MANIFESTS).put(envelope);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+async function loadManifest(passportId) {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_MANIFESTS, "readonly");
+    const request = tx.objectStore(STORE_MANIFESTS).get(passportId);
+    request.onsuccess = () => resolve(request.result || null);
+    request.onerror = () => reject(request.error);
+  });
+}
+async function exportAllPassports() {
+  const keys = await listKeys();
+  const bundles = [];
+  for (const key of keys) {
+    const manifest = await loadManifest(key.kid);
+    bundles.push({
+      key,
+      manifests: manifest ? [manifest] : [],
+      ownership_attestations: [],
+      status_records: []
+    });
+  }
+  return bundles;
+}
+async function clearAll() {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(
+      [STORE_KEYS, STORE_MANIFESTS, STORE_ATTESTATIONS, STORE_STATUS],
+      "readwrite"
+    );
+    tx.objectStore(STORE_KEYS).clear();
+    tx.objectStore(STORE_MANIFESTS).clear();
+    tx.objectStore(STORE_ATTESTATIONS).clear();
+    tx.objectStore(STORE_STATUS).clear();
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+export {
+  clearAll,
+  exportAllPassports,
+  listKeys,
+  loadCoachKey,
+  loadKey,
+  loadManifest,
+  storeKey,
+  storeManifest
+};