@scopeblind/passport 0.3.0 → 0.4.0

package/README.md

@@ -1,14 +1,16 @@
 # @scopeblind/passport
 
-Portable cryptographic identity for AI agents and coaches. Ed25519 keypairs, immutable manifests, ownership attestations, and verifiable evidence receipts.
+Portable cryptographic identity and local agent-pack builder for AI agents, MCP runtimes, and BlindLLM/OpenClaw-style flows.
 
-## Why
+## What it does
 
-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.
+- Generate Ed25519 passports for agents and coaches
+- Sign immutable manifests locally
+- Export portable passport bundles
+- Create a new local agent pack with `create`
+- Wrap an existing OpenClaw / MCP config with `wrap`
 
-- **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.
+The CLI is local-first. It does not upload prompts, context, or keys to ScopeBlind.
 
 ## Install
 
@@ -18,115 +20,85 @@ npm install @scopeblind/passport
 
 Requires Node.js >= 18. Browser entrypoint available at `@scopeblind/passport/browser`.
 
-## Quick Start
+## CLI First
 
-```typescript
-import {
-  generatePassportKey,
-  createCoachManifest,
-  verifyManifest,
-} from '@scopeblind/passport';
+Create a new agent pack:
 
-// 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
+```bash
+npx @scopeblind/passport create \
+  --name "Luna" \
+  --runtime openclaw \
+  --policy shadow
 ```
 
-## API
-
-### Key Generation
+Wrap an existing OpenClaw or MCP config:
 
-```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..."
+```bash
+npx @scopeblind/passport wrap \
+  --runtime openclaw \
+  --config ./openclaw.json \
+  --policy email-safe
 ```
 
-### Manifests
+Both commands generate:
 
-Manifests are **immutable once signed**. Config changes produce a new version.
+- `manifest.json`
+- `passport.bundle.json`
+- `protect-mcp.json`
+- `keys/gateway.json`
+- runtime-specific config guidance
+- `VERIFY.md`
 
-```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'],
-});
+## What the CLI is for
 
-// 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' }
-```
+This is not a no-code agent builder.
 
-### Ownership Attestations
+It is for:
 
-Prove a coach owns an agent (or vice versa):
+- giving an agent a portable identity
+- applying a `protect-mcp` policy pack
+- generating runtime glue for OpenClaw / Claude Desktop / Cursor / generic MCP
+- making the resulting pack independently verifiable
 
-```typescript
-const attestation = createOwnershipAttestation(coachKey, {
-  subject_kid: agentKey.kid,
-  relationship: 'owns',
-});
-```
+It is not for:
 
-### Evidence Receipts
+- hosted prompt management
+- agent marketplaces
+- non-local storage of context or secrets
 
-Sign verifiable evidence of machine decisions:
+## SDK Quick Start
 
 ```typescript
 import {
-  generateIssuerKey,
-  signReceipt,
-  createArenaBattleReceipt,
+  generatePassportKey,
+  createAgentManifest,
+  verifyManifest,
+  hashString,
 } 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' },
+const key = generatePassportKey('agent');
+
+const manifest = createAgentManifest(key, {
+  public_profile: {
+    name: 'Research Bot',
+    description: 'Fetches and summarizes MCP-backed research tasks',
+    domain_lanes: ['analysis:research'],
+  },
+  configuration_attestations: {
+    model_family_hash: hashString('runtime-managed'),
+    memory_mode: 'isolated',
+    system_prompt: 'Runtime-managed prompt placeholder',
+  },
+  capability_declarations: {
+    lease_template_compatibility: ['shadow'],
+    requested_tool_classes: ['mcp:general'],
+  },
 });
 
-// Anyone can verify the receipt
-const verified = verifyEnvelope(receipt);
+console.log(verifyManifest(manifest).valid); // true
 ```
 
-### Portable Export/Import
-
-Export a passport for migration to another platform:
+## Portable Export / Import
 
 ```typescript
 import {
@@ -135,50 +107,27 @@ import {
   importPassportBundle,
 } from '@scopeblind/passport';
 
-// Export (includes secret key — handle securely)
-const bundle = exportPassportBundle(key, manifest);
-const json = serializeBundle(bundle);
+const bundle = exportPassportBundle({
+  key,
+  manifests: [manifest],
+  ownership_attestations: [],
+  status_records: [],
+});
 
-// Import on another platform
+const json = serializeBundle(bundle);
 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"
+console.log(imported.valid); // true
 ```
 
-### 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
+## Why it fits the current stack
 
-## Design Decisions
+- `protect-mcp` handles tool policy and signed receipts
+- `@veritasacta/verify` handles independent verification
+- `@scopeblind/passport` handles portable identity + pack generation
 
-- **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.
+That split keeps the verifier MIT, keeps the local trust primitives local, and leaves the managed control plane as the paid product.
 
 ## License
 
-FSL-1.1-MIT — Source-available, converts to MIT after 2 years.
+FSL-1.1-MIT — source-available, free to use, converts to MIT after 2 years.

package/dist/chunk-LEODYLAY.mjs

@@ -0,0 +1,401 @@
+// src/display.ts
+function formatKidShort(kid) {
+  const parts = kid.split(":");
+  const fingerprint = parts[2] || kid;
+  if (fingerprint.length <= 8) return fingerprint;
+  return `${fingerprint.slice(0, 4)}\u2026${fingerprint.slice(-4)}`;
+}
+function formatKidLabeled(kid) {
+  const parts = kid.split(":");
+  const role = parts[1] === "coach" ? "Coach" : parts[1] === "agent" ? "Agent" : "Unknown";
+  return `${role} ${formatKidShort(kid)}`;
+}
+function getCoachSummary(envelope) {
+  const m = envelope.payload;
+  return {
+    kid: m.id,
+    displayName: m.display_name,
+    shortId: formatKidShort(m.id),
+    version: m.version,
+    createdAt: m.created_at
+  };
+}
+function getAgentSummary(envelope) {
+  const m = envelope.payload;
+  return {
+    kid: m.id,
+    name: m.public_profile.name,
+    shortId: formatKidShort(m.id),
+    version: m.version,
+    domainLanes: m.public_profile.domain_lanes,
+    createdAt: m.created_at
+  };
+}
+function isCoachManifest(manifest) {
+  return manifest.type === "scopeblind:coach-manifest";
+}
+function isAgentManifest(manifest) {
+  return manifest.type === "scopeblind:agent-manifest";
+}
+
+// src/keys.ts
+import { ed25519 } from "@noble/curves/ed25519";
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function base58Encode(bytes) {
+  let num = BigInt("0x" + bytesToHex(bytes));
+  const chars = [];
+  while (num > 0n) {
+    const remainder = Number(num % 58n);
+    chars.unshift(BASE58_ALPHABET[remainder]);
+    num = num / 58n;
+  }
+  for (const b of bytes) {
+    if (b === 0) chars.unshift("1");
+    else break;
+  }
+  return chars.join("") || "1";
+}
+function derivePassportId(publicKey, role) {
+  const fingerprint = base58Encode(publicKey).slice(0, 12);
+  return `sb:${role}:${fingerprint}`;
+}
+function generatePassportKey(role) {
+  const secretKeyRaw = ed25519.utils.randomPrivateKey();
+  const publicKey = ed25519.getPublicKey(secretKeyRaw);
+  const secretKey = new Uint8Array(64);
+  secretKey.set(secretKeyRaw, 0);
+  secretKey.set(publicKey, 32);
+  const kid = derivePassportId(publicKey, role);
+  return {
+    publicKey,
+    secretKey,
+    kid,
+    role,
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function getSigningKey(keyPair) {
+  return bytesToHex(keyPair.secretKey.slice(0, 32));
+}
+function getVerifyKey(keyPair) {
+  return bytesToHex(keyPair.publicKey);
+}
+function hashString(value) {
+  const encoder = new TextEncoder();
+  return bytesToHex(sha256(encoder.encode(value)));
+}
+
+// src/manifest.ts
+import { ed25519 as ed255192 } from "@noble/curves/ed25519";
+import { sha256 as sha2562 } from "@noble/hashes/sha256";
+import { bytesToHex as bytesToHex2, utf8ToBytes } from "@noble/hashes/utils";
+function canonicalize(obj) {
+  return JSON.stringify(obj, (_key, value) => {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const sorted = {};
+      for (const k of Object.keys(value).sort()) {
+        sorted[k] = value[k];
+      }
+      return sorted;
+    }
+    return value;
+  });
+}
+function canonicalHash(obj) {
+  return bytesToHex2(sha2562(utf8ToBytes(canonicalize(obj))));
+}
+function signPayload(payload, keyPair) {
+  const message = utf8ToBytes(canonicalize(payload));
+  const sigBytes = ed255192.sign(message, keyPair.secretKey.slice(0, 32));
+  return {
+    payload,
+    signature: {
+      alg: "EdDSA",
+      kid: keyPair.kid,
+      sig: bytesToHex2(sigBytes)
+    }
+  };
+}
+function createCoachManifest(keyPair, input, previousVersion, version) {
+  const manifest = {
+    type: "scopeblind:coach-manifest",
+    id: keyPair.kid,
+    version: version || "1.0.0",
+    previous_version: previousVersion ?? null,
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    public_key: base58Encode(keyPair.publicKey),
+    display_name: input.display_name.trim().slice(0, 32)
+  };
+  return signPayload(manifest, keyPair);
+}
+function createAgentManifest(keyPair, input, previousVersion, version) {
+  const promptHash = hashString(input.configuration_attestations.system_prompt);
+  const manifest = {
+    type: "scopeblind:agent-manifest",
+    id: keyPair.kid,
+    version: version || "1.0.0",
+    previous_version: previousVersion ?? null,
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    public_key: base58Encode(keyPair.publicKey),
+    public_profile: input.public_profile,
+    configuration_attestations: {
+      model_family_hash: input.configuration_attestations.model_family_hash,
+      memory_mode: input.configuration_attestations.memory_mode,
+      prompt_hash: promptHash
+    },
+    capability_declarations: input.capability_declarations,
+    evidence_pointers: input.evidence_pointers || {}
+  };
+  return signPayload(manifest, keyPair);
+}
+function createOwnershipAttestation(coachKeyPair, agentId, agentManifestVersion) {
+  const attestation = {
+    type: "scopeblind:ownership-attestation",
+    coach_id: coachKeyPair.kid,
+    agent_id: agentId,
+    agent_manifest_version: agentManifestVersion,
+    granted_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return signPayload(attestation, coachKeyPair);
+}
+function createStatusRecord(signerKeyPair, targetId, status, reason) {
+  const record = {
+    type: "scopeblind:status-record",
+    target_id: targetId,
+    status,
+    changed_at: (/* @__PURE__ */ new Date()).toISOString(),
+    issuer_id: signerKeyPair.kid,
+    ...reason ? { reason } : {}
+  };
+  return signPayload(record, signerKeyPair);
+}
+function createCoachContribution(coachKeyPair, battleId, coachedSide, noteHash, noteLength, upliftVerdict) {
+  const contribution = {
+    type: "scopeblind:coach-contribution",
+    battle_id: battleId,
+    coach_id: coachKeyPair.kid,
+    coached_side: coachedSide,
+    note_hash: noteHash,
+    note_length: noteLength,
+    ...upliftVerdict ? { uplift_verdict: upliftVerdict } : {}
+  };
+  return signPayload(contribution, coachKeyPair);
+}
+
+// src/verify.ts
+import { ed25519 as ed255193 } from "@noble/curves/ed25519";
+import { hexToBytes as hexToBytes2, utf8ToBytes as utf8ToBytes2 } from "@noble/hashes/utils";
+function verifyEnvelope(envelope, expectedPublicKey) {
+  try {
+    if (!envelope.signature?.sig || !envelope.signature?.kid) {
+      return { valid: false, error: "missing_signature" };
+    }
+    const message = utf8ToBytes2(canonicalize(envelope.payload));
+    const hash = canonicalHash(envelope.payload);
+    const payload = envelope.payload;
+    let publicKeyBytes;
+    if (expectedPublicKey) {
+      publicKeyBytes = expectedPublicKey;
+    } else if (typeof payload.public_key === "string") {
+      publicKeyBytes = base58Decode(payload.public_key);
+    } else {
+      return { valid: false, error: "no_public_key_available" };
+    }
+    if (expectedPublicKey) {
+      const expectedKid = base58Encode(expectedPublicKey);
+      const signerFingerprint = envelope.signature.kid.split(":")[2];
+      const expectedFingerprint = expectedKid.slice(0, 12);
+      if (signerFingerprint !== expectedFingerprint) {
+        return { valid: false, hash, error: "kid_mismatch" };
+      }
+    }
+    const valid = ed255193.verify(
+      hexToBytes2(envelope.signature.sig),
+      message,
+      publicKeyBytes
+    );
+    return valid ? { valid: true, hash } : { valid: false, hash, error: "invalid_signature" };
+  } catch (err) {
+    return {
+      valid: false,
+      error: `verification_error: ${err instanceof Error ? err.message : "unknown"}`
+    };
+  }
+}
+function verifyManifest(envelope) {
+  return verifyEnvelope(envelope);
+}
+function verifyOwnership(attestation, coachPublicKey) {
+  const result = verifyEnvelope(attestation, coachPublicKey);
+  if (!result.valid) return result;
+  return result;
+}
+function base58Decode(str) {
+  const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+  let num = 0n;
+  for (const char of str) {
+    const idx = ALPHABET.indexOf(char);
+    if (idx === -1) throw new Error(`Invalid base58 character: ${char}`);
+    num = num * 58n + BigInt(idx);
+  }
+  const hex = num.toString(16).padStart(64, "0");
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+// src/portable.ts
+import { bytesToHex as bytesToHex3, hexToBytes as hexToBytes3 } from "@noble/hashes/utils";
+import { ed25519 as ed255194 } from "@noble/curves/ed25519";
+function exportPassportBundle(bundle) {
+  return {
+    v: 1,
+    exported_at: (/* @__PURE__ */ new Date()).toISOString(),
+    passport: {
+      kid: bundle.key.kid,
+      role: bundle.key.role,
+      created_at: bundle.key.created_at,
+      publicKeyHex: bytesToHex3(bundle.key.publicKey),
+      secretKeyHex: bytesToHex3(bundle.key.secretKey)
+    },
+    manifests: bundle.manifests,
+    ownership_attestations: bundle.ownership_attestations,
+    status_records: bundle.status_records
+  };
+}
+function serializeBundle(bundle) {
+  return JSON.stringify(bundle, null, 2);
+}
+function importPassportBundle(json) {
+  const errors = [];
+  const warnings = [];
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch {
+    return { valid: false, errors: ["Invalid JSON"], warnings };
+  }
+  const data = raw;
+  if (data.v !== 1) {
+    errors.push(`Unsupported bundle version: ${data.v}`);
+    return { valid: false, errors, warnings };
+  }
+  const passport = data.passport;
+  if (!passport) {
+    errors.push("Missing passport field");
+    return { valid: false, errors, warnings };
+  }
+  if (typeof passport.publicKeyHex !== "string" || typeof passport.secretKeyHex !== "string") {
+    errors.push("Missing or invalid key hex values");
+    return { valid: false, errors, warnings };
+  }
+  if (typeof passport.kid !== "string" || !passport.kid.startsWith("sb:")) {
+    errors.push("Invalid passport kid format");
+    return { valid: false, errors, warnings };
+  }
+  const role = passport.role;
+  if (role !== "coach" && role !== "agent") {
+    errors.push(`Invalid role: ${role}`);
+    return { valid: false, errors, warnings };
+  }
+  let publicKey;
+  let secretKey;
+  try {
+    publicKey = hexToBytes3(passport.publicKeyHex);
+    secretKey = hexToBytes3(passport.secretKeyHex);
+  } catch {
+    errors.push("Failed to decode key hex values");
+    return { valid: false, errors, warnings };
+  }
+  if (publicKey.length !== 32) {
+    errors.push(`Invalid public key length: ${publicKey.length} (expected 32)`);
+    return { valid: false, errors, warnings };
+  }
+  if (secretKey.length !== 64) {
+    errors.push(`Invalid secret key length: ${secretKey.length} (expected 64)`);
+    return { valid: false, errors, warnings };
+  }
+  const seed = secretKey.slice(0, 32);
+  let derivedPublicKey;
+  try {
+    derivedPublicKey = ed255194.getPublicKey(seed);
+  } catch {
+    errors.push("Secret key seed is not a valid Ed25519 private key");
+    return { valid: false, errors, warnings };
+  }
+  if (bytesToHex3(derivedPublicKey) !== bytesToHex3(publicKey)) {
+    errors.push("Key coherence failure: secret key does not derive to the claimed public key");
+    return { valid: false, errors, warnings };
+  }
+  const expectedKid = derivePassportId(publicKey, role);
+  if (passport.kid !== expectedKid) {
+    errors.push(`Kid mismatch: bundle claims ${passport.kid} but public key derives to ${expectedKid}`);
+    return { valid: false, errors, warnings };
+  }
+  const key = {
+    publicKey,
+    secretKey,
+    kid: passport.kid,
+    role,
+    created_at: passport.created_at || (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const rawManifests = Array.isArray(data.manifests) ? data.manifests : [];
+  const validManifests = [];
+  for (const m of rawManifests) {
+    const result = verifyManifest(m);
+    if (!result.valid) {
+      errors.push(`Manifest ${m.payload?.id || "unknown"} has invalid signature: ${result.error}`);
+      continue;
+    }
+    if (m.payload?.id && m.payload.id !== key.kid) {
+      warnings.push(`Dropped manifest ${m.payload.id}: does not belong to passport ${key.kid}`);
+      continue;
+    }
+    validManifests.push(m);
+  }
+  const bundle = {
+    key,
+    manifests: validManifests,
+    ownership_attestations: Array.isArray(data.ownership_attestations) ? data.ownership_attestations : [],
+    status_records: Array.isArray(data.status_records) ? data.status_records : []
+  };
+  return {
+    valid: errors.length === 0,
+    bundle,
+    errors,
+    warnings
+  };
+}
+
+export {
+  formatKidShort,
+  formatKidLabeled,
+  getCoachSummary,
+  getAgentSummary,
+  isCoachManifest,
+  isAgentManifest,
+  base58Encode,
+  derivePassportId,
+  generatePassportKey,
+  getSigningKey,
+  getVerifyKey,
+  hashString,
+  canonicalize,
+  canonicalHash,
+  signPayload,
+  createCoachManifest,
+  createAgentManifest,
+  createOwnershipAttestation,
+  createStatusRecord,
+  createCoachContribution,
+  verifyEnvelope,
+  verifyManifest,
+  verifyOwnership,
+  exportPassportBundle,
+  serializeBundle,
+  importPassportBundle
+};

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node