@scopeblind/passport 0.3.0

package/dist/index.d.mts

@@ -0,0 +1,421 @@
+import { b as PassportRole, a as PassportKeyPair, A as AgentPublicProfile, c as AgentConfigAttestations, d as AgentCapabilities, e as AgentEvidencePointers, S as SignedEnvelope, f as AgentManifest, C as CoachContribution, g as CoachManifest, O as OwnershipAttestation, h as StatusRecord, M as Manifest, i as ArenaBattleReceipt, j as CoachUpliftReceipt, F as FormalDebateReceipt, P as PassportBundle } from './types-DHZHv2EE.mjs';
+export { k as AuthKeyBinding, B as BaseManifest, l as BattleParticipant, E as EncryptedPassportBundle, m as EvidenceReceipt, n as EvidenceReceiptType, o as FormalDebateParticipant, p as ManifestType, R as RestraintReceipt } from './types-DHZHv2EE.mjs';
+
+/**
+ * @scopeblind/passport — Key Generation
+ *
+ * Ed25519 key generation using @noble/curves (same library as @veritasacta/artifacts).
+ * Works in both Node.js and browser environments.
+ */
+
+declare function base58Encode(bytes: Uint8Array): string;
+/**
+ * Derive a passport ID from a public key.
+ * Format: sb:<role>:<first-12-chars-of-base58-pubkey>
+ */
+declare function derivePassportId(publicKey: Uint8Array, role: PassportRole): string;
+/**
+ * Generate a new Ed25519 passport keypair.
+ *
+ * @param role - 'coach' or 'agent'
+ * @returns A PassportKeyPair with the derived kid
+ */
+declare function generatePassportKey(role: PassportRole): PassportKeyPair;
+/**
+ * Get the hex-encoded private key seed (32 bytes) for signing.
+ * Compatible with @noble/curves ed25519.sign() which expects the seed.
+ */
+declare function getSigningKey(keyPair: PassportKeyPair): string;
+/**
+ * Get the hex-encoded public key for verification.
+ */
+declare function getVerifyKey(keyPair: PassportKeyPair): string;
+/**
+ * Compute SHA-256 hash of a string. Returns hex.
+ */
+declare function hashString(value: string): string;
+
+/**
+ * @scopeblind/passport — Manifest Creation & Signing
+ *
+ * Creates immutable, signed manifests for coaches and agents.
+ * Uses canonical JSON serialization + Ed25519 signing
+ * (same approach as @veritasacta/artifacts).
+ */
+
+/**
+ * Produce a deterministic JSON string (JCS-style sorted keys).
+ * Must match @veritasacta/artifacts canonicalize() output.
+ */
+declare function canonicalize(obj: Record<string, unknown>): string;
+/**
+ * SHA-256 hash of canonical JSON.
+ */
+declare function canonicalHash(obj: Record<string, unknown>): string;
+/**
+ * Sign any payload with the passport's Ed25519 key.
+ */
+declare function signPayload<T>(payload: T, keyPair: PassportKeyPair): SignedEnvelope<T>;
+interface CreateCoachManifestInput {
+    display_name: string;
+}
+/**
+ * Create and sign an immutable coach manifest.
+ */
+declare function createCoachManifest(keyPair: PassportKeyPair, input: CreateCoachManifestInput, previousVersion?: string | null, version?: string): SignedEnvelope<CoachManifest>;
+interface CreateAgentManifestInput {
+    public_profile: AgentPublicProfile;
+    configuration_attestations: Omit<AgentConfigAttestations, 'prompt_hash'> & {
+        /** The raw system prompt — will be hashed, NOT stored */
+        system_prompt: string;
+    };
+    capability_declarations: AgentCapabilities;
+    evidence_pointers?: AgentEvidencePointers;
+}
+/**
+ * Create and sign an immutable agent manifest.
+ * The system prompt is hashed (SHA-256) and never stored in the manifest.
+ */
+declare function createAgentManifest(keyPair: PassportKeyPair, input: CreateAgentManifestInput, previousVersion?: string | null, version?: string): SignedEnvelope<AgentManifest>;
+/**
+ * Create a signed ownership attestation (coach proves ownership of agent).
+ */
+declare function createOwnershipAttestation(coachKeyPair: PassportKeyPair, agentId: string, agentManifestVersion: string): SignedEnvelope<OwnershipAttestation>;
+/**
+ * Create a signed status change record.
+ */
+declare function createStatusRecord(signerKeyPair: PassportKeyPair, targetId: string, status: 'active' | 'suspended' | 'revoked', reason?: string): SignedEnvelope<StatusRecord>;
+/**
+ * Create a signed coach contribution (one canonical payload per battle).
+ */
+declare function createCoachContribution(coachKeyPair: PassportKeyPair, battleId: string, coachedSide: 'A' | 'B', noteHash: string, noteLength: number, upliftVerdict?: 'stronger' | 'same' | 'weaker'): SignedEnvelope<CoachContribution>;
+
+/**
+ * @scopeblind/passport — Verification
+ *
+ * Verify signed envelopes (manifests, attestations, contributions).
+ * Uses Ed25519 verification compatible with @veritasacta/artifacts.
+ */
+
+interface VerificationResult {
+    valid: boolean;
+    /** SHA-256 hash of the canonical payload */
+    hash?: string;
+    /** Error description if verification failed */
+    error?: string;
+}
+/**
+ * Verify a signed envelope's Ed25519 signature.
+ *
+ * @param envelope - The signed envelope to verify
+ * @param expectedPublicKey - Optional. If provided, also checks the signer matches.
+ */
+declare function verifyEnvelope<T>(envelope: SignedEnvelope<T>, expectedPublicKey?: Uint8Array): VerificationResult;
+/**
+ * Verify that a manifest is self-consistent (signature matches embedded public key).
+ */
+declare function verifyManifest(envelope: SignedEnvelope<Manifest>): VerificationResult;
+/**
+ * Verify an ownership attestation was signed by the claimed coach.
+ */
+declare function verifyOwnership(attestation: SignedEnvelope<OwnershipAttestation>, coachPublicKey: Uint8Array): VerificationResult;
+
+/**
+ * @scopeblind/passport — Display & UI Helpers
+ *
+ * Utilities for displaying passport identities in UIs.
+ * These are convenience functions, not core crypto.
+ */
+
+/**
+ * Format a passport kid for display.
+ * "sb:coach:3kFxGq7nY1Ka" → "3kFx…Y1Ka"
+ */
+declare function formatKidShort(kid: string): string;
+/**
+ * Format a passport kid with role label.
+ * "sb:coach:3kFxGq7nY1Ka" → "Coach 3kFx…Y1Ka"
+ */
+declare function formatKidLabeled(kid: string): string;
+/**
+ * Get a display-ready summary from a signed coach manifest.
+ */
+declare function getCoachSummary(envelope: SignedEnvelope<CoachManifest>): {
+    kid: string;
+    displayName: string;
+    shortId: string;
+    version: string;
+    createdAt: string;
+};
+/**
+ * Get a display-ready summary from a signed agent manifest.
+ */
+declare function getAgentSummary(envelope: SignedEnvelope<AgentManifest>): {
+    kid: string;
+    name: string;
+    shortId: string;
+    version: string;
+    domainLanes: string[];
+    createdAt: string;
+};
+/**
+ * Check if a manifest is a coach manifest.
+ */
+declare function isCoachManifest(manifest: Manifest): manifest is CoachManifest;
+/**
+ * Check if a manifest is an agent manifest.
+ */
+declare function isAgentManifest(manifest: Manifest): manifest is AgentManifest;
+
+/**
+ * @scopeblind/passport — Issuer Module
+ *
+ * Provides Ed25519 signing for server-side receipt issuance.
+ * Uses the SAME canonical envelope model as passport signing.
+ *
+ * Usage in Cloudflare Workers:
+ *   - Store issuer secret key as an environment secret
+ *   - Expose public key at /.well-known/blindllm-keys.json
+ *   - Sign receipts using createSignedReceipt()
+ */
+
+interface IssuerKeyPair {
+    /** Hex-encoded Ed25519 public key */
+    publicKeyHex: string;
+    /** Hex-encoded Ed25519 secret key seed (32 bytes) */
+    secretKeyHex: string;
+    /** Issuer ID: sb:issuer:<fingerprint> */
+    issuerId: string;
+}
+/**
+ * Generate a new issuer keypair.
+ * Call ONCE, store the result as environment secrets.
+ */
+declare function generateIssuerKey(): IssuerKeyPair;
+/**
+ * Sign a receipt payload with the issuer's key.
+ * Same canonical JSON + Ed25519 envelope as passport signing.
+ */
+declare function signReceipt<T>(payload: T, issuerSecretKeyHex: string, issuerId: string): SignedEnvelope<T>;
+interface CreateArenaBattleReceiptInput {
+    battleId: string;
+    laneId: string;
+    agentA: {
+        id: string;
+        manifest_version: string;
+    };
+    agentB: {
+        id: string;
+        manifest_version: string;
+    };
+    winner: 'A' | 'B' | 'tie';
+    coach?: {
+        id: string;
+        coached_side: 'A' | 'B';
+        note_hash: string;
+        note_length: number;
+    };
+}
+/**
+ * Create and sign a blindllm:arena-battle receipt.
+ */
+declare function createArenaBattleReceipt(input: CreateArenaBattleReceiptInput, issuerSecretKeyHex: string, issuerId: string): SignedEnvelope<ArenaBattleReceipt>;
+interface CreateCoachUpliftReceiptInput {
+    battleId: string;
+    coachId: string;
+    coachedSide: 'A' | 'B';
+    upliftVerdict: 'stronger' | 'same' | 'weaker';
+}
+/**
+ * Create and sign a blindllm:coach-uplift receipt.
+ */
+declare function createCoachUpliftReceipt(input: CreateCoachUpliftReceiptInput, issuerSecretKeyHex: string, issuerId: string): SignedEnvelope<CoachUpliftReceipt>;
+interface CreateFormalDebateReceiptInput {
+    debateId: string;
+    specId: string;
+    laneId: string;
+    artifactHash: string;
+    resolutionHash: string;
+    pro: {
+        id: string;
+        manifest_version: string;
+        coach_id?: string;
+    };
+    con: {
+        id: string;
+        manifest_version: string;
+        coach_id?: string;
+    };
+    audienceWinner: 'pro' | 'con' | 'tie';
+    judgeWinner: 'pro' | 'con' | 'tie';
+    restraintResult: 'clean' | 'flagged';
+}
+/**
+ * Create and sign a blindllm:formal-debate receipt.
+ */
+declare function createFormalDebateReceipt(input: CreateFormalDebateReceiptInput, issuerSecretKeyHex: string, issuerId: string): SignedEnvelope<FormalDebateReceipt>;
+/**
+ * Build a proper JWK Set payload for the issuer endpoint.
+ * x is base64url-encoded per RFC 8037 (not hex).
+ *
+ * Serve at: GET /.well-known/blindllm-keys.json
+ */
+declare function buildPublicKeyEndpoint(issuerPublicKeyHex: string, issuerId: string): {
+    keys: {
+        kty: string;
+        crv: string;
+        kid: string;
+        x: string;
+        use: string;
+    }[];
+    issuer: string;
+    updated_at: string;
+};
+/**
+ * Derive a full IssuerKeyPair from a single hex-encoded seed.
+ * Use this when the worker stores one secret (BLINDLLM_ISSUER_SEED)
+ * and needs to derive the public key and issuer ID at runtime.
+ */
+declare function deriveIssuerFromSeed(secretKeyHex: string): IssuerKeyPair;
+
+/**
+ * @scopeblind/passport — Export / Import
+ *
+ * Portable passport bundle format for cross-browser/machine transfer.
+ * Plain JSON first; encrypted bundles in a later sprint.
+ */
+
+/** Serializable passport bundle (hex-encoded keys, JSON-safe) */
+interface PortablePassportBundle {
+    /** Format version */
+    v: 1;
+    /** Export timestamp */
+    exported_at: string;
+    /** Passport data */
+    passport: {
+        kid: string;
+        role: 'coach' | 'agent';
+        created_at: string;
+        publicKeyHex: string;
+        secretKeyHex: string;
+    };
+    /** Signed manifests */
+    manifests: SignedEnvelope<Manifest>[];
+    /** Ownership attestations */
+    ownership_attestations: SignedEnvelope<OwnershipAttestation>[];
+    /** Status records */
+    status_records: SignedEnvelope<StatusRecord>[];
+}
+/**
+ * Export a PassportBundle to a portable JSON-serializable format.
+ * Keys are hex-encoded for safe transport.
+ */
+declare function exportPassportBundle(bundle: PassportBundle): PortablePassportBundle;
+/**
+ * Serialize a portable bundle to a JSON string.
+ */
+declare function serializeBundle(bundle: PortablePassportBundle): string;
+interface ImportResult {
+    valid: boolean;
+    bundle?: PassportBundle;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Parse and validate a portable passport bundle.
+ *
+ * Verifies:
+ *   1. JSON structure and version
+ *   2. Secret key → public key derivation coherence
+ *   3. kid matches the public key
+ *   4. Manifest signatures
+ *   5. Manifests belong to this passport's kid
+ */
+declare function importPassportBundle(json: string): ImportResult;
+
+/**
+ * Passport → @veritasacta/artifacts bridge
+ *
+ * Utilities for converting @scopeblind/passport receipts into
+ * v2 artifact envelopes that can be verified at scopeblind.com/verify
+ * and indexed by the receipt explorer.
+ *
+ * This bridge allows BlindLLM battle receipts, coach contributions,
+ * and agent manifests to be treated as standard Veritas Acta artifacts.
+ */
+/**
+ * Convert a passport SignedEnvelope to a v2 artifact envelope.
+ *
+ * Passport receipts already use JCS canonicalization + Ed25519 signing
+ * (same approach as @veritasacta/artifacts), so the conversion is
+ * primarily a metadata wrapper that adds the v2 format identifier.
+ */
+declare function passportToArtifact<T>(envelope: PassportSignedEnvelope<T>, options?: {
+    format?: string;
+    issuer?: string;
+}): ArtifactEnvelope<T>;
+/**
+ * Convert multiple passport receipts to artifact envelopes.
+ */
+declare function passportBatchToArtifacts<T>(envelopes: PassportSignedEnvelope<T>[], options?: {
+    format?: string;
+    issuer?: string;
+}): ArtifactEnvelope<T>[];
+/**
+ * Create a self-contained audit bundle from passport receipts.
+ * The bundle embeds the public keys for offline verification.
+ */
+declare function createPassportAuditBundle<T>(envelopes: PassportSignedEnvelope<T>[], keys: Record<string, {
+    pub: string;
+    issuer?: string;
+}>, options?: {
+    issuer?: string;
+}): AuditBundle<T>;
+/** Passport SignedEnvelope (matches @scopeblind/passport) */
+interface PassportSignedEnvelope<T> {
+    payload: T;
+    signature: {
+        alg?: string;
+        kid: string;
+        sig: string;
+        pub?: string;
+    };
+}
+/** v2 Artifact Envelope (matches @veritasacta/artifacts) */
+interface ArtifactEnvelope<T> {
+    version: string;
+    format: string;
+    payload: T;
+    signature: {
+        alg: string;
+        kid: string;
+        sig: string;
+        pub?: string;
+    };
+    meta?: {
+        issuer?: string;
+        source?: string;
+        timestamp?: number;
+    };
+}
+/** Audit Bundle */
+interface AuditBundle<T> {
+    version: string;
+    created_at: string;
+    issuer: string;
+    receipts: ArtifactEnvelope<T>[];
+    keys: Record<string, {
+        alg: string;
+        pub: string;
+        issuer?: string;
+    }>;
+    summary: {
+        total_receipts: number;
+        time_range: {
+            first: number;
+            last: number;
+        };
+    };
+}
+
+export { AgentCapabilities, AgentConfigAttestations, AgentEvidencePointers, AgentManifest, AgentPublicProfile, ArenaBattleReceipt, CoachContribution, CoachManifest, CoachUpliftReceipt, type CreateAgentManifestInput, type CreateArenaBattleReceiptInput, type CreateCoachManifestInput, type CreateCoachUpliftReceiptInput, type CreateFormalDebateReceiptInput, FormalDebateReceipt, type ImportResult, type IssuerKeyPair, Manifest, OwnershipAttestation, PassportBundle, PassportKeyPair, PassportRole, type PortablePassportBundle, SignedEnvelope, StatusRecord, type VerificationResult, base58Encode, buildPublicKeyEndpoint, canonicalHash, canonicalize, createAgentManifest, createArenaBattleReceipt, createCoachContribution, createCoachManifest, createCoachUpliftReceipt, createFormalDebateReceipt, createOwnershipAttestation, createPassportAuditBundle, createStatusRecord, deriveIssuerFromSeed, derivePassportId, exportPassportBundle, formatKidLabeled, formatKidShort, generateIssuerKey, generatePassportKey, getAgentSummary, getCoachSummary, getSigningKey, getVerifyKey, hashString, importPassportBundle, isAgentManifest, isCoachManifest, passportBatchToArtifacts, passportToArtifact, serializeBundle, signPayload, signReceipt, verifyEnvelope, verifyManifest, verifyOwnership };