protect-mcp 0.4.2 → 0.4.3

package/dist/index.d.ts

@@ -6,6 +6,8 @@ interface ProtectPolicy {
     policy_engine?: PolicyEngineMode;
     /** External PDP endpoint (when policy_engine is "external" or "hybrid") */
     external?: ExternalPDPConfig;
+    /** Directory containing .cedar policy files (when policy_engine is "cedar") */
+    cedar_dir?: string;
 }
 interface ToolPolicy {
     /**
@@ -32,7 +34,7 @@ interface ToolPolicy {
     }>>;
 }
 type TrustTier = 'unknown' | 'signed-known' | 'evidenced' | 'privileged';
-type PolicyEngineMode = 'built-in' | 'external' | 'hybrid';
+type PolicyEngineMode = 'built-in' | 'external' | 'hybrid' | 'cedar';
 interface ExternalPDPConfig {
     /** HTTP endpoint for the external policy decision point */
     endpoint: string;
@@ -134,6 +136,18 @@ interface DecisionLog {
     tier?: TrustTier;
     /** Credential label used (v2, never the actual secret) */
     credential_ref?: string;
+    /** OpenTelemetry trace ID (32 hex chars) — links receipts to OTel traces */
+    otel_trace_id?: string;
+    /** OpenTelemetry span ID (16 hex chars) — links this receipt to a specific span */
+    otel_span_id?: string;
+    /** Rekor transparency log anchor (if anchored) */
+    log_anchor?: {
+        transparency_log: string;
+        log_index: number;
+        integrated_time: string;
+        receipt_hash: string;
+        verify_url: string;
+    };
 }
 interface ProtectConfig {
     /** Command to spawn (first element of child process) */
@@ -294,13 +308,49 @@ interface EvaluateTierOptions {
  * @param manifest - Manifest presentation from the agent (or null if none)
  * @param opts - Evaluation options (overrides, evidence store, thresholds)
  * @returns AdmissionResult with assigned tier
+ *
+ * @patent Patent-protected construction. Covered by Apache 2.0 patent grant
+ * for users of this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
  */
 declare function evaluateTier(manifest: ManifestPresentation | null, opts?: TierOverrides | EvaluateTierOptions): AdmissionResult;
 /**
  * Check if a trust tier meets the minimum required tier.
+ *
+ * @patent Patent-protected construction. Covered by Apache 2.0 patent grant
+ * for users of this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
  */
 declare function meetsMinTier(actual: TrustTier, required: TrustTier): boolean;
 
+/**
+ * @scopeblind/protect-mcp — Cedar Policy Evaluator (Local WASM)
+ *
+ * Evaluates Cedar policies locally using @cedar-policy/cedar-wasm.
+ * No external server required. Same deterministic evaluation as
+ * AWS Verified Permissions / AgentCore Policy.
+ *
+ * Cedar is loaded as an optional dependency — if the WASM module
+ * isn't installed, this module exports stubs that return fallback decisions.
+ */
+
+interface CedarPolicySet {
+    /** Raw concatenated Cedar source */
+    source: string;
+    /** SHA-256 digest of the sorted, concatenated policy source */
+    digest: string;
+    /** Number of individual .cedar files loaded */
+    fileCount: number;
+    /** Filenames loaded */
+    files: string[];
+}
+
+/**
+ * MCP tool-calling gateway that intercepts JSON-RPC requests,
+ * evaluates policy, and emits signed decision receipts.
+ *
+ * @standard Standard MCP proxy pattern — JSON-RPC stdio interception.
+ */
 declare class ProtectGateway {
     private child;
     private config;
@@ -316,10 +366,19 @@ declare class ProtectGateway {
     private readonly approvalNonce;
     private currentTier;
     private admissionResult;
+    /** Notification config for approval gates (SMS, webhook, email) */
+    private notificationConfig;
     /** HTTP transport mode: pending response resolvers keyed by JSON-RPC id */
     private pendingResponses;
     private httpMode;
+    /** Loaded Cedar policy set (when policy_engine is "cedar") */
+    private cedarPolicySet;
     constructor(config: ProtectConfig);
+    /**
+     * Set the Cedar policy set for local evaluation.
+     * Called during CLI startup when --cedar flag is used.
+     */
+    setCedarPolicies(policySet: CedarPolicySet): void;
     start(): Promise<void>;
     setManifest(manifest: ManifestPresentation | null): AdmissionResult;
     private handleClientMessage;
@@ -328,6 +387,15 @@ declare class ProtectGateway {
     private injectParamsCredentials;
     private interceptToolCall;
     private getTierRateLimit;
+    /**
+     * Emit a decision log entry with OTel-compatible trace IDs and optional
+     * signed receipt generation.
+     *
+     * @patent Patent-protected construction — decision receipts with configurable
+     * disclosure and issuer-blind properties. Covered by Apache 2.0 patent grant
+     * for users of this code. Clean-room reimplementation requires a patent license.
+     * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+     */
     private emitDecisionLog;
     private makeErrorResponse;
     private sendToChild;
@@ -432,6 +500,11 @@ interface CredentialResolution {
  * @param label - Credential label (e.g., "stripe_api")
  * @param credentials - Credential configuration map
  * @returns CredentialResolution (value is only populated on success)
+ *
+ * @patent Patent-protected construction — privacy-preserving credential presentation.
+ * Covered by Apache 2.0 patent grant for users of this code. Clean-room
+ * reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
  */
 declare function resolveCredential(label: string, credentials: Record<string, CredentialConfig> | undefined): CredentialResolution;
 /**
@@ -439,6 +512,11 @@ declare function resolveCredential(label: string, credentials: Record<string, Cr
  *
  * @param credentials - Credential configuration map
  * @returns Array of credential labels
+ *
+ * @patent Patent-protected construction — privacy-preserving credential presentation.
+ * Covered by Apache 2.0 patent grant for users of this code. Clean-room
+ * reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
  */
 declare function listCredentialLabels(credentials: Record<string, CredentialConfig> | undefined): string[];
 /**
@@ -447,6 +525,11 @@ declare function listCredentialLabels(credentials: Record<string, CredentialConf
  *
  * @param credentials - Credential configuration map
  * @returns Array of warnings for missing env vars
+ *
+ * @patent Patent-protected construction — privacy-preserving credential presentation.
+ * Covered by Apache 2.0 patent grant for users of this code. Clean-room
+ * reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
  */
 declare function validateCredentials(credentials: Record<string, CredentialConfig> | undefined): string[];
 
@@ -467,6 +550,8 @@ declare function validateCredentials(credentials: Record<string, CredentialConfi
  *
  * @param config - Signing configuration
  * @returns Array of warnings (empty = success)
+ *
+ * @standard RFC 8032 (Ed25519), RFC 8785 (JCS)
  */
 declare function initSigning(config: SigningConfig | undefined): Promise<string[]>;
 /**
@@ -474,6 +559,8 @@ declare function initSigning(config: SigningConfig | undefined): Promise<string[
  *
  * Returns the signed artifact JSON string, or null if signing is not configured.
  * On signing failure, returns an unsigned artifact with a warning.
+ *
+ * @standard RFC 8032 (Ed25519), RFC 8785 (JCS)
  */
 declare function signDecision(entry: DecisionLog): {
     signed: string | null;
@@ -482,6 +569,8 @@ declare function signDecision(entry: DecisionLog): {
 };
 /**
  * Get the signer's public key info for discovery/verification.
+ *
+ * @standard RFC 8032 (Ed25519), RFC 8785 (JCS)
  */
 declare function getSignerInfo(): {
     publicKey: string;
@@ -490,6 +579,8 @@ declare function getSignerInfo(): {
 } | null;
 /**
  * Check if signing is available.
+ *
+ * @standard RFC 8032 (Ed25519), RFC 8785 (JCS)
  */
 declare function isSigningEnabled(): boolean;
 
@@ -1007,6 +1098,11 @@ declare function isDisclosureMode(s: string): s is DisclosureMode;
  * Does NOT verify the cryptographic signature — use verifyManifestSignature() for that.
  *
  * Returns an array of error strings. Empty array = valid.
+ *
+ * @patent Patent-protected construction — agent manifest format for portable agent
+ * identity with evidence chains. Covered by Apache 2.0 patent grant for users of
+ * this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
  */
 declare function validateManifest(manifest: unknown): string[];
 /**
@@ -1014,7 +1110,1338 @@ declare function validateManifest(manifest: unknown): string[];
  * Does NOT verify the cryptographic signature.
  *
  * Returns an array of error strings. Empty array = valid.
+ *
+ * @patent Patent-protected construction — evidence receipt format for portable agent
+ * identity with evidence chains. Covered by Apache 2.0 patent grant for users of
+ * this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
  */
 declare function validateEvidenceReceipt(receipt: unknown): string[];
 
-export { type AdmissionResult, type AgentId, type AgentManifest, type ArenaPayload, type ArenaReceipt, type AttestationPayload, type AttestationReceipt, type AuditBundle, type AuditBundleOptions, type BenchmarkPayload, type BenchmarkReceipt, type BuilderId, type ComplianceReport, type CredentialConfig, type DecisionContext, type DecisionLog, type DisclosureMode, type Ed25519PublicKey, type EvidenceIssuer, type EvidenceReceipt, type EvidenceReceiptBase, type EvidenceSummary, type EvidenceSummaryEntry, type EvidenceType, type ExternalDecision, type ExternalPDPConfig, type IssuerType, type JsonRpcRequest, type JsonRpcResponse, type LeaseCompatibility, type ManifestBuilder, type ManifestCapabilities, type ManifestConfig, type ManifestIdentity, type ManifestPresentation, type ManifestSignature, type ManifestStatus, type PolicyEngineMode, type ProtectConfig, ProtectGateway, type ProtectPolicy, type RateLimit, type RestraintPayload, type RestraintReceipt, type SHA256Hash, type SigningConfig, type SimulationResult, type SimulationSummary, type TierOverrides, type ToolPolicy, type TrustTier, type WorkPayload, type WorkReceipt, buildDecisionContext, checkRateLimit, collectSignedReceipts, createAuditBundle, evaluateTier, formatReportMarkdown, formatSimulation, generateReport, getSignerInfo, getToolPolicy, initSigning, isAgentId, isDisclosureMode, isEvidenceType, isManifestStatus, isSigningEnabled, listCredentialLabels, loadPolicy, meetsMinTier, parseLogFile, parseRateLimit, queryExternalPDP, resolveCredential, signDecision, simulate, validateCredentials, validateEvidenceReceipt, validateManifest };
+/**
+ * Sigstore Rekor Transparency Log Anchoring
+ *
+ * Anchors receipt hashes to the Sigstore Rekor transparency log,
+ * providing independent temporal proof that a receipt existed at a
+ * specific point in time. The inclusion proof makes backdating
+ * receipts cryptographically detectable.
+ *
+ * Uses the Rekor public instance (rekor.sigstore.dev) — free, no account needed.
+ *
+ * Usage:
+ *   import { anchorToRekor, verifyRekorAnchor } from './rekor-anchor.js';
+ *
+ *   // Anchor a receipt hash
+ *   const anchor = await anchorToRekor(receiptHash, signature, publicKey);
+ *
+ *   // Verify an anchor
+ *   const valid = await verifyRekorAnchor(anchor.logIndex, receiptHash);
+ */
+interface RekorAnchor {
+    /** Rekor log index */
+    logIndex: number;
+    /** Rekor entry UUID */
+    uuid: string;
+    /** Inclusion timestamp (RFC 3339) */
+    integratedTime: string;
+    /** SHA-256 hash of the receipt that was anchored */
+    receiptHash: string;
+    /** Rekor log ID */
+    logID: string;
+    /** Body of the Rekor entry (base64) */
+    body: string;
+}
+interface RekorVerification {
+    valid: boolean;
+    logIndex: number;
+    integratedTime: string;
+    receiptHashMatch: boolean;
+}
+/**
+ * Anchor a receipt hash to the Sigstore Rekor transparency log.
+ *
+ * Creates a "hashedrekord" entry containing the SHA-256 hash of the receipt,
+ * the Ed25519 signature, and the public key. The Rekor server returns an
+ * inclusion proof with a timestamp.
+ *
+ * @param receiptHash - SHA-256 hex hash of the receipt content
+ * @param signature - Ed25519 signature (base64)
+ * @param publicKeyPem - Ed25519 public key in PEM format
+ * @returns RekorAnchor with log index, UUID, and timestamp
+ *
+ * @standard Integration with Sigstore Rekor transparency log — standard transparency anchoring.
+ */
+declare function anchorToRekor(receiptHash: string, signature: string, publicKeyPem: string): Promise<RekorAnchor>;
+/**
+ * Verify that a receipt hash was anchored to Rekor at a specific log index.
+ *
+ * Fetches the entry from Rekor and checks that the hash matches.
+ * This is the "trust but verify" path — anyone can check the anchor
+ * without contacting ScopeBlind.
+ *
+ * @param logIndex - The Rekor log index to verify
+ * @param expectedHash - The expected SHA-256 hash of the receipt
+ *
+ * @standard Integration with Sigstore Rekor transparency log — standard transparency anchoring.
+ */
+declare function verifyRekorAnchor(logIndex: number, expectedHash: string): Promise<RekorVerification>;
+/**
+ * Compute the SHA-256 hash of a receipt for anchoring.
+ * Uses JCS-compatible canonical JSON (sorted keys).
+ *
+ * @standard RFC 8785 (JCS), SHA-256
+ */
+declare function hashReceipt(receipt: Record<string, unknown>): string;
+/**
+ * Create a log_anchor field for embedding in receipts.
+ * This field can be added to any Acta receipt to provide
+ * temporal proof of existence.
+ *
+ * @standard Integration with Sigstore Rekor transparency log — standard transparency anchoring.
+ */
+declare function createLogAnchorField(anchor: RekorAnchor): {
+    transparency_log: string;
+    log_index: number;
+    integrated_time: string;
+    receipt_hash: string;
+    verify_url: string;
+};
+
+/**
+ * Hash-Based Selective Disclosure for Veritas Acta Receipts
+ *
+ * Enables per-field redaction of receipt payloads while preserving
+ * signature validity. Uses salted SHA-256 commitments — the receipt
+ * structure and non-redacted fields remain verifiable, but redacted
+ * fields are replaced with their salted hash.
+ *
+ * This is NOT zero-knowledge proof — it's practical, fast, and
+ * covers 90% of the privacy use cases:
+ * - Prove an agent followed HIPAA policy without revealing patient_id
+ * - Prove a tool call was rate-limited without revealing the API endpoint
+ * - Prove a deny decision occurred without revealing the prompt
+ *
+ * The salt is per-field and per-receipt, preventing rainbow table attacks.
+ * The field owner (receipt issuer) holds the salts and can selectively
+ * reveal fields to specific auditors.
+ *
+ * Usage:
+ *   import { redactFields, revealField, verifyRedactedReceipt } from './selective-disclosure.js';
+ *
+ *   // Redact sensitive fields
+ *   const { redacted, salts } = redactFields(receipt, ['patient_id', 'ssn', 'timestamp']);
+ *
+ *   // The redacted receipt has: "patient_id": "sha256:salt+..."
+ *   // The signature still verifies against the original
+ *
+ *   // Reveal a specific field to an auditor
+ *   const revealed = revealField(redacted, salts, 'patient_id');
+ *
+ *   // Verify a redacted receipt (checks that redacted fields are valid commitments)
+ *   const valid = verifyRedactedReceipt(redacted, originalSignature, publicKey);
+ */
+interface RedactionSalt {
+    field: string;
+    salt: string;
+    originalValue: unknown;
+}
+interface RedactedResult {
+    /** The receipt with sensitive fields replaced by salted commitments */
+    redacted: Record<string, unknown>;
+    /** The salts needed to reveal each redacted field */
+    salts: RedactionSalt[];
+    /** Fields that were redacted */
+    redactedFields: string[];
+    /** SHA-256 hash of the original (unredacted) receipt for verification */
+    originalHash: string;
+}
+/**
+ * Redact specified fields in a receipt payload, replacing them with
+ * salted SHA-256 commitments.
+ *
+ * @param receipt - The full receipt object
+ * @param fieldsToRedact - Array of field paths to redact (dot notation for nested: "payload.patient_id")
+ * @returns RedactedResult with the redacted receipt and the salts
+ *
+ * @patent Patent-protected construction. Covered by Apache 2.0 patent grant
+ * for users of this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+ */
+declare function redactFields(receipt: Record<string, unknown>, fieldsToRedact: string[]): RedactedResult;
+/**
+ * Reveal a previously redacted field using its salt.
+ *
+ * @param redactedReceipt - The redacted receipt
+ * @param salts - The salt array from redactFields()
+ * @param fieldPath - The field to reveal (dot notation)
+ * @returns A new receipt with the specified field revealed
+ *
+ * @patent Patent-protected construction. Covered by Apache 2.0 patent grant
+ * for users of this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+ */
+declare function revealField(redactedReceipt: Record<string, unknown>, salts: RedactionSalt[], fieldPath: string): Record<string, unknown>;
+/**
+ * Verify that a redacted field's commitment matches the revealed value.
+ *
+ * An auditor can check: "does sha256(salt + value) equal the commitment
+ * in the receipt?" without needing the issuer's cooperation.
+ *
+ * @param commitment - The commitment string from _commitments
+ * @param salt - The salt (hex)
+ * @param value - The claimed original value
+ * @returns true if the commitment is valid
+ *
+ * @patent Patent-protected construction. Covered by Apache 2.0 patent grant
+ * for users of this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+ */
+declare function verifyCommitment(commitment: string, salt: string, value: unknown): boolean;
+/**
+ * Verify all commitments in a redacted receipt given a set of salts.
+ *
+ * @param redactedReceipt - The redacted receipt with _commitments
+ * @param salts - The salts for all redacted fields
+ * @returns Object with valid flag and per-field results
+ *
+ * @patent Patent-protected construction. Covered by Apache 2.0 patent grant
+ * for users of this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+ */
+declare function verifyAllCommitments(redactedReceipt: Record<string, unknown>, salts: RedactionSalt[]): {
+    valid: boolean;
+    fields: Record<string, boolean>;
+};
+/**
+ * Create a disclosure package for a specific auditor.
+ * Contains only the salts for fields the auditor needs to see.
+ *
+ * @param allSalts - Full salt array from redactFields()
+ * @param fieldsToDisclose - Array of field paths to include
+ * @returns Disclosure package (JSON-serializable)
+ *
+ * @patent Patent-protected construction. Covered by Apache 2.0 patent grant
+ * for users of this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+ */
+declare function createDisclosurePackage(allSalts: RedactionSalt[], fieldsToDisclose: string[]): {
+    version: string;
+    disclosed_fields: string[];
+    salts: Array<{
+        field: string;
+        salt: string;
+        value: unknown;
+    }>;
+};
+
+/**
+ * Notification system for protect-mcp approval gates.
+ * Sends SMS (Twilio), webhook, or browser push notifications
+ * when a tool call requires human approval.
+ */
+interface NotificationConfig {
+    /** Twilio SMS notification */
+    sms?: {
+        accountSid: string;
+        authToken: string;
+        from: string;
+        to: string;
+    };
+    /** Webhook notification (Slack, PagerDuty, custom) */
+    webhook?: {
+        url: string;
+        method?: "POST" | "PUT";
+        headers?: Record<string, string>;
+        /** Template: 'slack' | 'pagerduty' | 'custom' */
+        template?: "slack" | "pagerduty" | "custom";
+    };
+    /** Email notification */
+    email?: {
+        to: string;
+        /** Uses Resend API if configured, falls back to SMTP */
+        resendApiKey?: string;
+    };
+}
+interface ApprovalNotification {
+    requestId: string;
+    toolName: string;
+    agentId?: string;
+    policyName?: string;
+    reason: string;
+    traceUrl?: string;
+    approveUrl?: string;
+    timestamp: string;
+}
+/**
+ * Send approval notification through configured channels.
+ * Non-blocking — errors are logged, not thrown.
+ */
+declare function sendApprovalNotification(config: NotificationConfig, notification: ApprovalNotification): Promise<void>;
+/**
+ * Parse notification config from environment variables.
+ * SCOPEBLIND_SMS_TO, SCOPEBLIND_TWILIO_SID, etc.
+ */
+declare function parseNotificationConfigFromEnv(): NotificationConfig | null;
+
+/**
+ * Hugging Face Dataset Export
+ *
+ * Exports Veritas Acta receipt chains as HF-compatible datasets.
+ * Produces JSONL format with structured fields for ML research.
+ *
+ * Usage:
+ *   npx protect-mcp export-hf --output dataset.jsonl
+ *   npx protect-mcp export-hf --output dataset.jsonl --format parquet
+ */
+interface HFReceiptRow {
+    /** Unique receipt identifier */
+    receipt_id: string;
+    /** Receipt type: decision, execution, outcome, policy_load, observation, approval */
+    receipt_type: string;
+    /** Tool that was called */
+    tool_name: string | null;
+    /** Decision verdict: allow, deny, null */
+    decision: string | null;
+    /** Agent identifier (pseudonymous) */
+    agent_id: string | null;
+    /** Issuer identifier */
+    issuer_id: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** SHA-256 hash of the active policy at decision time */
+    policy_hash: string | null;
+    /** Typed causal edges to other receipts */
+    edges: Array<{
+        receipt_id: string;
+        relation: string;
+    }>;
+    /** Number of edges (for quick filtering) */
+    edge_count: number;
+    /** Ed25519 signature (hex) */
+    signature: string | null;
+    /** Whether the receipt has a valid signature */
+    signed: boolean;
+    /** Context hash for selective disclosure */
+    context_hash: string | null;
+    /** Chain ID linking related receipts */
+    chain_id: string | null;
+}
+interface HFDatasetMetadata {
+    /** Dataset name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Number of rows */
+    num_rows: number;
+    /** Receipt type distribution */
+    type_distribution: Record<string, number>;
+    /** Decision distribution */
+    decision_distribution: Record<string, number>;
+    /** Time range */
+    time_range: {
+        from: string;
+        to: string;
+    };
+    /** Unique agents */
+    unique_agents: number;
+    /** Unique tools */
+    unique_tools: number;
+    /** Export timestamp */
+    exported_at: string;
+    /** License */
+    license: "MIT";
+    /** Tags for HF Hub */
+    tags: string[];
+}
+/**
+ * Convert raw receipt objects to HF-compatible rows.
+ */
+declare function receiptsToHFRows(receipts: Record<string, unknown>[]): HFReceiptRow[];
+/**
+ * Generate dataset metadata for HF Hub.
+ */
+declare function generateHFMetadata(rows: HFReceiptRow[], name?: string): HFDatasetMetadata;
+/**
+ * Export receipts as JSONL (one JSON object per line).
+ */
+declare function exportJSONL(rows: HFReceiptRow[]): string;
+/**
+ * Generate a HuggingFace dataset card (README.md) for the dataset repo.
+ */
+declare function generateDatasetCard(metadata: HFDatasetMetadata): string;
+
+/**
+ * WebAuthn/Passkey Approval for protect-mcp Human-in-the-Loop Gates
+ *
+ * Enables biometric (FaceID, TouchID, Windows Hello, YubiKey) approval
+ * of agent tool calls. When an agent requests a tool that requires
+ * human approval, the system generates a WebAuthn challenge. The human
+ * authenticates with their biometric device, producing a cryptographic
+ * proof that a specific human authorized a specific action.
+ *
+ * The WebAuthn assertion is embedded in the approval receipt as the
+ * `authenticator_data` field, creating an unforgeable binding between
+ * biological intent and machine execution.
+ *
+ * Flow:
+ *   1. Agent requests `db_write` → policy says `require_approval`
+ *   2. protect-mcp generates a WebAuthn challenge containing the tool
+ *      name, request ID, and a timestamp
+ *   3. Human receives notification (SMS/Slack/browser) with the challenge
+ *   4. Human authenticates with FaceID/TouchID/YubiKey
+ *   5. The WebAuthn assertion is verified server-side
+ *   6. A signed approval receipt is emitted with the authenticator data
+ *   7. The agent's tool call is unblocked
+ *
+ * Usage:
+ *   import { createApprovalChallenge, verifyApprovalAssertion } from './webauthn-approval.js';
+ *
+ *   // Server-side: create challenge
+ *   const challenge = createApprovalChallenge(requestId, toolName, agentId);
+ *
+ *   // Client-side: browser calls navigator.credentials.get() with challenge
+ *   // ... user authenticates with biometric ...
+ *
+ *   // Server-side: verify the assertion
+ *   const result = verifyApprovalAssertion(challenge, assertion, credentialId);
+ */
+interface ApprovalChallenge {
+    /** Random challenge bytes (base64url) */
+    challenge: string;
+    /** Request ID of the tool call being approved */
+    requestId: string;
+    /** Tool name being approved */
+    toolName: string;
+    /** Agent requesting the approval */
+    agentId?: string;
+    /** Timestamp when challenge was created */
+    createdAt: string;
+    /** Challenge expiry (seconds) */
+    timeoutSeconds: number;
+    /** Relying party ID (domain) */
+    rpId: string;
+    /** SHA-256 hash of the challenge context (for receipt embedding) */
+    contextHash: string;
+}
+interface ApprovalAssertion {
+    /** Credential ID used (base64url) */
+    credentialId: string;
+    /** Authenticator data (base64url) */
+    authenticatorData: string;
+    /** Client data JSON (base64url) */
+    clientDataJSON: string;
+    /** Signature (base64url) */
+    signature: string;
+    /** User handle (base64url, optional) */
+    userHandle?: string;
+}
+interface ApprovalResult {
+    /** Whether the assertion is valid */
+    valid: boolean;
+    /** The credential ID used */
+    credentialId: string;
+    /** Authenticator type detected */
+    authenticatorType: 'platform' | 'cross-platform' | 'unknown';
+    /** Whether user verification was performed (biometric) */
+    userVerified: boolean;
+    /** Signature counter (for cloning detection) */
+    signCount: number;
+    /** Context hash that was signed */
+    contextHash: string;
+    /** Timestamp of approval */
+    approvedAt: string;
+}
+/**
+ * Create a WebAuthn challenge for approving a tool call.
+ *
+ * The challenge contains the tool name and request ID so the
+ * approval is cryptographically bound to a specific action.
+ *
+ * @param requestId - The request ID of the pending tool call
+ * @param toolName - The tool being approved
+ * @param agentId - The agent requesting approval (optional)
+ * @param rpId - Relying party ID (default: scopeblind.com)
+ * @param timeoutSeconds - Challenge timeout (default: 300 = 5 minutes)
+ */
+declare function createApprovalChallenge(requestId: string, toolName: string, agentId?: string, rpId?: string, timeoutSeconds?: number): ApprovalChallenge;
+/**
+ * Generate the WebAuthn PublicKeyCredentialRequestOptions
+ * that the browser needs to call navigator.credentials.get().
+ *
+ * This is sent to the client for the biometric prompt.
+ */
+declare function toCredentialRequestOptions(challenge: ApprovalChallenge, allowCredentials?: Array<{
+    id: string;
+    type: 'public-key';
+}>): {
+    publicKey: {
+        challenge: ArrayBuffer;
+        rpId: string;
+        timeout: number;
+        userVerification: 'required';
+        allowCredentials?: Array<{
+            id: ArrayBuffer;
+            type: 'public-key';
+        }>;
+    };
+};
+/**
+ * Verify a WebAuthn assertion from the client.
+ *
+ * This is a simplified verification that checks the structure
+ * and extracts the authenticator data. For production use with
+ * full signature verification, use the @simplewebauthn/server package.
+ *
+ * @param challenge - The original challenge
+ * @param assertion - The assertion from navigator.credentials.get()
+ * @returns ApprovalResult with verification details
+ */
+declare function verifyApprovalAssertion(challenge: ApprovalChallenge, assertion: ApprovalAssertion): ApprovalResult;
+/**
+ * Create the approval receipt payload for embedding in an Acta receipt.
+ *
+ * This is the data that gets signed into the DAG as an acta:approval node,
+ * proving a human biometrically authorized a specific machine action.
+ */
+declare function createApprovalReceiptPayload(challenge: ApprovalChallenge, result: ApprovalResult): {
+    type: 'acta:approval';
+    approval_method: 'webauthn';
+    tool_name: string;
+    request_id: string;
+    agent_id?: string;
+    authenticator_type: string;
+    user_verified: boolean;
+    context_hash: string;
+    approved_at: string;
+    credential_id_hash: string;
+};
+
+/**
+ * W3C DID/VC Mapping for ScopeBlind Passport Manifests
+ *
+ * Maps passport manifests to W3C Verifiable Credential format
+ * and generates did:key identifiers from Ed25519 public keys.
+ *
+ * @standard W3C DID/VC interoperability — standard mapping, not patent-protected.
+ * Implements W3C Decentralized Identifiers (DID) v1.0 and Verifiable Credentials
+ * Data Model v1.1.
+ */
+/**
+ * Generate a did:key identifier from an Ed25519 public key (hex).
+ *
+ * @standard W3C DID/VC interoperability — standard mapping, not patent-protected.
+ */
+declare function ed25519ToDIDKey(publicKeyHex: string): string;
+/**
+ * Convert a passport manifest to a W3C Verifiable Credential.
+ *
+ * @standard W3C DID/VC interoperability — standard mapping, not patent-protected.
+ */
+declare function manifestToVC(manifest: {
+    agent_id: string;
+    display_name?: string;
+    public_key: string;
+    capabilities?: string[];
+    policy_digest?: string;
+    created_at?: string;
+    signature?: string;
+}): {
+    '@context': string[];
+    type: string[];
+    issuer: string;
+    issuanceDate: string;
+    credentialSubject: Record<string, unknown>;
+    proof?: Record<string, unknown>;
+};
+/**
+ * Convert a decision receipt to a W3C Verifiable Presentation.
+ *
+ * @standard W3C DID/VC interoperability — standard mapping, not patent-protected.
+ */
+declare function receiptToVP(receipt: Record<string, unknown>, issuerPublicKey: string): {
+    '@context': string[];
+    type: string[];
+    holder: string;
+    verifiableCredential: Record<string, unknown>[];
+};
+
+/**
+ * E2B MicroVM Sandboxing for Agent Evaluation
+ *
+ * Provides isolated, disposable execution environments for testing
+ * AI agent tool calls safely. Agents can run real MCP tools
+ * (including destructive operations) inside sandboxes without
+ * affecting the host system.
+ *
+ * Uses E2B (e2b.dev) for sub-second microVM startup, or falls back
+ * to Docker containers for self-hosted deployments.
+ *
+ * Every tool call inside the sandbox produces a signed receipt,
+ * creating a verifiable "safety transcript" of the agent's behavior.
+ *
+ * Usage:
+ *   import { createSandbox, runInSandbox, destroySandbox } from './sandbox.js';
+ *
+ *   // Create a disposable sandbox
+ *   const sandbox = await createSandbox({ template: 'node-20' });
+ *
+ *   // Run an agent's tool call inside the sandbox
+ *   const result = await runInSandbox(sandbox, {
+ *     tool: 'execute_command',
+ *     args: { command: 'npm test' },
+ *   });
+ *
+ *   // Sandbox is destroyed after evaluation
+ *   await destroySandbox(sandbox);
+ */
+interface SandboxConfig {
+    /** E2B template (e.g., 'node-20', 'python-3.11') or Docker image */
+    template: string;
+    /** Timeout in seconds (default: 300 = 5 minutes) */
+    timeoutSeconds?: number;
+    /** Maximum memory in MB (default: 512) */
+    memoryMB?: number;
+    /** Files to mount into the sandbox */
+    files?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Whether to use E2B cloud or local Docker (default: 'e2b') */
+    runtime?: 'e2b' | 'docker';
+    /** E2B API key (from env E2B_API_KEY if not provided) */
+    apiKey?: string;
+}
+interface Sandbox {
+    /** Unique sandbox ID */
+    id: string;
+    /** Runtime type */
+    runtime: 'e2b' | 'docker';
+    /** Creation timestamp */
+    createdAt: string;
+    /** Status */
+    status: 'running' | 'completed' | 'failed' | 'destroyed';
+    /** Tool call receipts generated inside the sandbox */
+    receipts: SandboxReceipt[];
+}
+interface SandboxToolCall {
+    /** Tool name to execute */
+    tool: string;
+    /** Tool arguments */
+    args: Record<string, unknown>;
+}
+interface SandboxResult {
+    /** Whether the tool call succeeded */
+    success: boolean;
+    /** Tool output */
+    output: string;
+    /** Error message if failed */
+    error?: string;
+    /** Execution time in milliseconds */
+    durationMs: number;
+    /** Exit code (for commands) */
+    exitCode?: number;
+}
+interface SandboxReceipt {
+    /** Tool that was called */
+    tool: string;
+    /** Decision (from protect-mcp policy evaluation) */
+    decision: 'allow' | 'deny' | 'require_approval';
+    /** Whether it was executed */
+    executed: boolean;
+    /** Result if executed */
+    result?: SandboxResult;
+    /** Timestamp */
+    timestamp: string;
+    /** Policy rule that matched */
+    policyRule?: string;
+}
+interface SafetyTranscript {
+    /** Sandbox ID */
+    sandboxId: string;
+    /** Template used */
+    template: string;
+    /** Total tool calls attempted */
+    totalCalls: number;
+    /** Calls allowed */
+    allowed: number;
+    /** Calls denied */
+    denied: number;
+    /** Calls requiring approval */
+    requireApproval: number;
+    /** Success rate of executed calls */
+    successRate: number;
+    /** All receipts */
+    receipts: SandboxReceipt[];
+    /** Duration of the evaluation */
+    durationMs: number;
+    /** Timestamp */
+    evaluatedAt: string;
+    /** Safety score (0-100) */
+    safetyScore: number;
+}
+/**
+ * Create a disposable sandbox for agent evaluation.
+ *
+ * If E2B_API_KEY is set, uses E2B cloud microVMs.
+ * Otherwise, falls back to local Docker containers.
+ */
+declare function createSandbox(config: SandboxConfig): Promise<Sandbox>;
+/**
+ * Run a tool call inside the sandbox with protect-mcp policy evaluation.
+ */
+declare function runInSandbox(sandbox: Sandbox, toolCall: SandboxToolCall, policy?: Record<string, unknown>): Promise<SandboxReceipt>;
+/**
+ * Generate a safety transcript from a sandbox evaluation.
+ * This is the "graduation certificate" for an agent.
+ */
+declare function generateSafetyTranscript(sandbox: Sandbox, template: string): SafetyTranscript;
+/**
+ * Destroy a sandbox and clean up resources.
+ */
+declare function destroySandbox(sandbox: Sandbox): Promise<void>;
+
+/**
+ * Evidence Authenticity via TLSNotary / zkTLS (Beta)
+ *
+ * ⚠️ BETA: This module defines the interface for evidence authenticity
+ * proofs. The TLSNotary integration is planned for Q3 2026 when the
+ * tooling stabilizes. The interface is stable and forward-compatible.
+ *
+ * Problem: When an agent fetches external data (API calls, web scraping)
+ * and submits it as evidence to an Acta receipt, there's currently no
+ * proof the data is authentic. The agent could fabricate the response.
+ *
+ * Solution: TLSNotary (tlsnotary.org) enables an agent to prove it
+ * fetched specific data from a specific server without revealing
+ * session cookies or API keys. The TLS session is notarized by a
+ * third-party verifier, producing a cryptographic proof of authenticity.
+ *
+ * This module defines:
+ * 1. The EvidenceAttestation format (for embedding in receipts)
+ * 2. The verification interface (for checking attestations)
+ * 3. Placeholder implementations that will be replaced with
+ *    real TLSNotary integration when the SDK matures
+ *
+ * Usage:
+ *   import { createEvidenceAttestation, verifyEvidenceAttestation } from './evidence-authenticity.js';
+ *
+ *   // Create an attestation for data fetched from an API
+ *   const attestation = await createEvidenceAttestation({
+ *     url: 'https://api.example.com/data',
+ *     responseHash: sha256(responseBody),
+ *     method: 'GET',
+ *     timestamp: new Date().toISOString(),
+ *   });
+ *
+ *   // Embed in receipt
+ *   receipt.evidence_attestation = attestation;
+ *
+ *   // Verify
+ *   const valid = await verifyEvidenceAttestation(attestation);
+ */
+/**
+ * Evidence attestation format — embedded in receipts to prove
+ * the authenticity of externally fetched data.
+ */
+interface EvidenceAttestation {
+    /** Version of the attestation format */
+    version: '0.1-beta';
+    /** Attestation method */
+    method: 'self-reported' | 'tlsnotary' | 'oracle' | 'witness';
+    /** URL that was fetched */
+    url: string;
+    /** HTTP method used */
+    httpMethod: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** SHA-256 hash of the response body */
+    responseHash: string;
+    /** Response status code */
+    statusCode: number;
+    /** TLS server certificate fingerprint (SHA-256 of DER) */
+    serverCertFingerprint?: string;
+    /** Timestamp of the fetch */
+    fetchedAt: string;
+    /** Notary public key (for TLSNotary attestations) */
+    notaryPublicKey?: string;
+    /** Notary signature over the attestation */
+    notarySignature?: string;
+    /** Whether this attestation has been cryptographically verified */
+    verified: boolean;
+    /** Verification details */
+    verificationNote: string;
+}
+/**
+ * Input for creating an evidence attestation.
+ */
+interface EvidenceAttestationInput {
+    /** URL that was fetched */
+    url: string;
+    /** HTTP method */
+    httpMethod?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** SHA-256 hash of the response body */
+    responseHash: string;
+    /** Response status code */
+    statusCode?: number;
+    /** Timestamp */
+    timestamp?: string;
+}
+/**
+ * Create an evidence attestation for externally fetched data.
+ *
+ * Current implementation: self-reported (the agent declares what it
+ * fetched, but there's no third-party proof). This is clearly marked
+ * as `method: 'self-reported'` in the attestation.
+ *
+ * Future: When TLSNotary SDK matures, this will produce
+ * `method: 'tlsnotary'` attestations with cryptographic proofs.
+ *
+ * @param input - Details of the fetch to attest
+ * @returns EvidenceAttestation for embedding in a receipt
+ *
+ * @patent Patent-protected construction — evidence authenticity attestation with
+ * TLSNotary/zkTLS integration. Covered by Apache 2.0 patent grant for users of
+ * this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+ */
+declare function createEvidenceAttestation(input: EvidenceAttestationInput): Promise<EvidenceAttestation>;
+/**
+ * Verify an evidence attestation.
+ *
+ * For self-reported attestations, this always returns { valid: false }
+ * with a note explaining that self-reported data cannot be verified.
+ *
+ * For TLSNotary attestations, this will verify the notary's signature
+ * over the TLS session transcript.
+ *
+ * @patent Patent-protected construction — evidence authenticity attestation with
+ * TLSNotary/zkTLS integration. Covered by Apache 2.0 patent grant for users of
+ * this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+ */
+declare function verifyEvidenceAttestation(attestation: EvidenceAttestation): Promise<{
+    valid: boolean;
+    method: string;
+    note: string;
+}>;
+/**
+ * Hash a response body for attestation.
+ * Uses SHA-256 for consistency with the rest of the receipt format.
+ */
+declare function hashResponseBody(body: string | Buffer): string;
+/**
+ * Create an attestation field for embedding in a receipt payload.
+ * This is the format that goes into the `evidence_attestation`
+ * field of an Acta receipt.
+ *
+ * @patent Patent-protected construction — evidence authenticity attestation with
+ * TLSNotary/zkTLS integration. Covered by Apache 2.0 patent grant for users of
+ * this code. Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+ */
+declare function createAttestationField(attestation: EvidenceAttestation): {
+    evidence_authenticity: {
+        version: string;
+        method: string;
+        url_hash: string;
+        response_hash: string;
+        fetched_at: string;
+        verified: boolean;
+        note: string;
+    };
+};
+
+/**
+ * C2PA Content Credential Integration
+ *
+ * Embeds Veritas Acta provenance into C2PA (Coalition for Content
+ * Provenance and Authenticity) manifest assertions. This enables
+ * the "right-click to verify" UX — any content generated during
+ * a governed agent session carries its Acta receipt chain as a
+ * Content Credential.
+ *
+ * C2PA is backed by Adobe, Microsoft, BBC, and others. By embedding
+ * Acta receipts as C2PA assertions, AI-generated content becomes
+ * traceable through the existing content provenance ecosystem.
+ *
+ * Usage:
+ *   import { createC2PAManifest, embedInImage, embedInDocument } from './c2pa-credentials.js';
+ *
+ *   // Create a C2PA manifest from an Acta receipt chain
+ *   const manifest = createC2PAManifest(receipts, {
+ *     title: 'AI-generated report',
+ *     generator: 'protect-mcp v0.3.3',
+ *   });
+ *
+ *   // The manifest can be embedded in images, PDFs, or documents
+ *   // using c2patool or the C2PA Rust/JS SDK
+ */
+/**
+ * C2PA Manifest structure compatible with the C2PA specification.
+ * This is the JSON representation that c2patool can consume.
+ */
+interface C2PAManifest {
+    /** C2PA claim generator identifier */
+    claim_generator: string;
+    /** C2PA claim generator version */
+    claim_generator_info: Array<{
+        name: string;
+        version: string;
+        icon?: {
+            format: string;
+            identifier: string;
+        };
+    }>;
+    /** Title of the content */
+    title: string;
+    /** Assertions about the content */
+    assertions: C2PAAssertion[];
+    /** Ingredients (source materials) */
+    ingredients?: C2PAIngredient[];
+}
+interface C2PAAssertion {
+    /** Assertion label (URI) */
+    label: string;
+    /** Assertion data */
+    data: Record<string, unknown>;
+    /** Whether this assertion is hashed (for privacy) */
+    is_hash?: boolean;
+}
+interface C2PAIngredient {
+    /** Title of the ingredient */
+    title: string;
+    /** Relationship to the output */
+    relationship: 'parentOf' | 'componentOf' | 'inputTo';
+    /** Hash of the ingredient */
+    hash?: string;
+}
+interface C2PAOptions {
+    /** Title of the generated content */
+    title: string;
+    /** Generator name (default: 'protect-mcp') */
+    generator?: string;
+    /** Generator version */
+    version?: string;
+    /** Whether to include full receipt data or only hashes */
+    includeFullReceipts?: boolean;
+    /** Additional assertions to include */
+    additionalAssertions?: C2PAAssertion[];
+}
+/**
+ * Create a C2PA manifest from an Acta receipt chain.
+ *
+ * The manifest contains:
+ * - An `acta.decision-provenance` assertion with the receipt chain summary
+ * - An `acta.policy-compliance` assertion showing policy adherence
+ * - Standard C2PA actions (c2pa.actions) documenting what the agent did
+ *
+ * @param receipts - Array of Acta receipts from the agent session
+ * @param options - Configuration for the manifest
+ * @returns C2PA manifest JSON (compatible with c2patool)
+ */
+declare function createC2PAManifest(receipts: Array<Record<string, unknown>>, options: C2PAOptions): C2PAManifest;
+/**
+ * Export the C2PA manifest as JSON for use with c2patool.
+ *
+ * Usage:
+ *   const json = exportC2PAManifestJSON(manifest);
+ *   fs.writeFileSync('manifest.json', json);
+ *   // Then: c2patool output.jpg -m manifest.json -o signed-output.jpg
+ */
+declare function exportC2PAManifestJSON(manifest: C2PAManifest): string;
+/**
+ * Generate a c2patool command for embedding the manifest into a file.
+ *
+ * @param manifestPath - Path to the manifest JSON file
+ * @param inputPath - Path to the input file (image, PDF, etc.)
+ * @param outputPath - Path for the signed output file
+ * @returns The c2patool command to run
+ */
+declare function generateC2PACommand(manifestPath: string, inputPath: string, outputPath: string): string;
+/**
+ * Verify that a file contains valid Acta C2PA assertions.
+ *
+ * @param c2paManifestJson - The C2PA manifest JSON extracted from a file
+ * @returns Verification result
+ */
+declare function verifyActaC2PAAssertions(c2paManifestJson: string): {
+    hasActaProvenance: boolean;
+    receiptCount: number;
+    merkleRoot: string | null;
+    complianceRate: string | null;
+    verifyUrl: string | null;
+};
+
+/**
+ * Prediction Lifecycle Bridge
+ *
+ * Bridges Veritas Acta prediction receipts to external forecasting
+ * platforms (Metaculus, Manifold Markets) for calibration tracking.
+ *
+ * Status: Experimental
+ */
+interface PredictionReceipt {
+    receipt_id: string;
+    receipt_type: 'prediction';
+    issuer_id: string;
+    event_time: string;
+    payload: {
+        claim: string;
+        probability: number;
+        resolution_criteria: string;
+        resolution_deadline: string;
+        domain?: string;
+        tags?: string[];
+    };
+    signature: string;
+}
+interface PredictionResolution {
+    receipt_id: string;
+    receipt_type: 'resolution';
+    parent_receipts: string[];
+    payload: {
+        resolved: boolean;
+        resolution_value: 'true' | 'false' | 'ambiguous';
+        resolution_source: string;
+        resolution_time: string;
+    };
+    signature: string;
+}
+interface CalibrationScore {
+    total_predictions: number;
+    resolved: number;
+    brier_score: number;
+    calibration_buckets: Array<{
+        bucket: string;
+        predicted_probability: number;
+        actual_frequency: number;
+        count: number;
+    }>;
+}
+/**
+ * Compute Brier score from a set of predictions and their resolutions
+ */
+declare function computeCalibration(predictions: PredictionReceipt[], resolutions: Map<string, PredictionResolution>): CalibrationScore;
+/**
+ * Format prediction for Metaculus API submission (placeholder)
+ */
+declare function toMetaculusFormat(prediction: PredictionReceipt): {
+    question_url?: string;
+    prediction_value: number;
+    acta_receipt_id: string;
+    acta_signature: string;
+};
+/**
+ * Format prediction for Manifold Markets API submission (placeholder)
+ */
+declare function toManifoldFormat(prediction: PredictionReceipt): {
+    probability: number;
+    acta_receipt_id: string;
+    acta_signature: string;
+};
+
+/**
+ * Agent-to-Agent Receipt Exchange
+ *
+ * Middleware for multi-agent systems (CrewAI, LangGraph, AutoGen) that
+ * propagates receipts across agent boundaries. Each hop produces a
+ * chained receipt, enabling end-to-end accountability tracing.
+ *
+ * Status: Beta — API may change
+ *
+ * @example
+ * ```typescript
+ * import { ReceiptPropagator } from 'protect-mcp/agent-exchange';
+ *
+ * const propagator = new ReceiptPropagator({ issuer: 'agent-alpha' });
+ *
+ * // Agent A delegates to Agent B
+ * const delegation = propagator.delegate('agent-beta', {
+ *   tools: ['read_file', 'search_web'],
+ *   scope: 'task-123',
+ *   ttl: 3600,
+ * });
+ *
+ * // Agent B receives the delegation and wraps its actions
+ * const action = propagator.wrapAction('read_file', {
+ *   delegation_receipt: delegation.receipt_id,
+ *   args: { path: 'data.json' },
+ * });
+ *
+ * // Verify the full chain
+ * const chain = propagator.traceChain(action.receipt_id);
+ * // Returns: [delegation_receipt, action_receipt]
+ * ```
+ */
+interface DelegationReceipt {
+    receipt_id: string;
+    receipt_type: 'delegation';
+    issuer_id: string;
+    event_time: string;
+    payload: {
+        /** The agent receiving delegated authority */
+        delegate_id: string;
+        /** Tools the delegate is authorized to use */
+        authorized_tools: string[];
+        /** Scope identifier for this delegation */
+        scope: string;
+        /** Time-to-live in seconds */
+        ttl: number;
+        /** Expiry timestamp */
+        expires_at: string;
+        /** Maximum number of tool calls allowed */
+        max_calls?: number;
+        /** Whether the delegate can further sub-delegate */
+        allow_subdelegation: boolean;
+    };
+    parent_receipts: string[];
+    signature?: string;
+}
+interface ActionReceipt {
+    receipt_id: string;
+    receipt_type: 'execution';
+    issuer_id: string;
+    event_time: string;
+    payload: {
+        tool_name: string;
+        decision: 'allow' | 'deny';
+        delegation_receipt: string;
+        scope: string;
+        call_index: number;
+    };
+    parent_receipts: string[];
+    signature?: string;
+}
+interface PropagatorConfig {
+    /** Issuer ID for this agent */
+    issuer: string;
+    /** Optional signing function (receipt → signed receipt) */
+    signer?: (receipt: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Propagates receipts across agent boundaries in multi-agent systems.
+ * Each hop produces a chained receipt enabling end-to-end accountability.
+ *
+ * @patent Patent-protected construction — delegated signing with receipt chain
+ * propagation. Covered by Apache 2.0 patent grant for users of this code.
+ * Clean-room reimplementation requires a patent license.
+ * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+ */
+declare class ReceiptPropagator {
+    private issuer;
+    private signer?;
+    private receipts;
+    private delegationCallCounts;
+    constructor(config: PropagatorConfig);
+    /**
+     * Create a delegation receipt authorizing another agent to use specific tools.
+     *
+     * @patent Patent-protected construction — delegated signing with receipt chain
+     * propagation. Covered by Apache 2.0 patent grant for users of this code.
+     * Clean-room reimplementation requires a patent license.
+     * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+     */
+    delegate(delegateId: string, options: {
+        tools: string[];
+        scope: string;
+        ttl: number;
+        maxCalls?: number;
+        allowSubdelegation?: boolean;
+        parentReceipts?: string[];
+    }): DelegationReceipt;
+    /**
+     * Wrap a tool call with a receipt that references the delegation.
+     * Validates the delegation is still valid (not expired, within call limit,
+     * tool is authorized).
+     *
+     * @patent Patent-protected construction — delegated signing with receipt chain
+     * propagation. Covered by Apache 2.0 patent grant for users of this code.
+     * Clean-room reimplementation requires a patent license.
+     * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+     */
+    wrapAction(toolName: string, options: {
+        delegation_receipt: string;
+        args?: Record<string, unknown>;
+    }): ActionReceipt;
+    /**
+     * Trace the full receipt chain from a given receipt back to the root delegation.
+     *
+     * @patent Patent-protected construction — delegated signing with receipt chain
+     * propagation. Covered by Apache 2.0 patent grant for users of this code.
+     * Clean-room reimplementation requires a patent license.
+     * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+     */
+    traceChain(receiptId: string): Array<DelegationReceipt | ActionReceipt>;
+    /**
+     * Export all receipts as a JSON array (for verification, archival, or Trace visualization).
+     */
+    exportAll(): Array<DelegationReceipt | ActionReceipt>;
+    /**
+     * Validate that a delegation chain is intact and all signatures verify.
+     *
+     * @patent Patent-protected construction — delegated signing with receipt chain
+     * propagation. Covered by Apache 2.0 patent grant for users of this code.
+     * Clean-room reimplementation requires a patent license.
+     * @see {@link https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/}
+     */
+    validateChain(receiptId: string): {
+        valid: boolean;
+        chain_length: number;
+        issues: string[];
+    };
+}
+/**
+ * Create a LangGraph-compatible state channel that propagates receipts.
+ *
+ * Usage with LangGraph:
+ * ```typescript
+ * import { createReceiptChannel } from 'protect-mcp/agent-exchange';
+ *
+ * const channel = createReceiptChannel('orchestrator');
+ *
+ * // In your LangGraph node:
+ * const result = await channel.withDelegation('worker-agent', ['read_file'], async (ctx) => {
+ *   // ctx.delegation is the delegation receipt
+ *   // Agent B's actions will reference this delegation
+ *   return await agentB.run(ctx.delegation);
+ * });
+ * ```
+ */
+declare function createReceiptChannel(orchestratorId: string): {
+    propagator: ReceiptPropagator;
+    withDelegation<T>(delegateId: string, tools: string[], fn: (ctx: {
+        delegation: DelegationReceipt;
+        propagator: ReceiptPropagator;
+    }) => Promise<T>, options?: {
+        ttl?: number;
+        maxCalls?: number;
+        scope?: string;
+    }): Promise<{
+        result: T;
+        delegation: DelegationReceipt;
+        chain: Array<DelegationReceipt | ActionReceipt>;
+    }>;
+};
+
+/**
+ * Confidential Computing Interface
+ *
+ * Defines the interface for TEE (Trusted Execution Environment) attestation
+ * and confidential inference integration. When enabled, agents must prove
+ * they generated their keys inside a secure enclave and their code hasn't
+ * been tampered with before receiving elevated trust tiers.
+ *
+ * Status: Beta — Enterprise feature
+ *
+ * Supported attestation providers:
+ * - AWS Nitro Enclaves (via attestation documents)
+ * - Intel TDX (via DCAP quotes)
+ * - AMD SEV-SNP (via attestation reports)
+ * - Generic COSE-signed attestations
+ *
+ * @example
+ * ```typescript
+ * import { ConfidentialGate, verifyAttestation } from 'protect-mcp/confidential';
+ *
+ * const gate = new ConfidentialGate({
+ *   require_attestation: true,
+ *   accepted_providers: ['nitro', 'tdx'],
+ *   min_trust_tier: 'evidenced',
+ * });
+ *
+ * // Agent presents attestation during handshake
+ * const result = gate.evaluateAttestation(attestationDoc);
+ * // result: { accepted: true, tier: 'privileged', provider: 'nitro' }
+ * ```
+ */
+type AttestationProvider = 'nitro' | 'tdx' | 'sev_snp' | 'generic';
+interface AttestationDocument {
+    /** The attestation provider */
+    provider: AttestationProvider;
+    /** Raw attestation bytes (base64-encoded) */
+    attestation: string;
+    /** Public key generated inside the enclave */
+    enclave_public_key: string;
+    /** Measurements / PCR values */
+    measurements: Record<string, string>;
+    /** Timestamp of attestation */
+    timestamp: string;
+    /** Optional: Nonce used for freshness */
+    nonce?: string;
+}
+interface AttestationResult {
+    /** Whether the attestation was accepted */
+    accepted: boolean;
+    /** Resulting trust tier */
+    tier: 'unknown' | 'signed' | 'evidenced' | 'privileged';
+    /** Provider that issued the attestation */
+    provider: AttestationProvider;
+    /** Reason for acceptance or rejection */
+    reason: string;
+    /** Receipt documenting the attestation evaluation */
+    receipt_id?: string;
+}
+interface ConfidentialGateConfig {
+    /** Require attestation for elevated trust tiers */
+    require_attestation: boolean;
+    /** Accepted attestation providers */
+    accepted_providers: AttestationProvider[];
+    /** Minimum trust tier that requires attestation */
+    min_trust_tier: 'signed' | 'evidenced' | 'privileged';
+    /** Expected measurement values (PCRs) for validation */
+    expected_measurements?: Record<string, string>;
+    /** Maximum age of attestation document (seconds) */
+    max_attestation_age?: number;
+}
+declare class ConfidentialGate {
+    private config;
+    constructor(config: ConfidentialGateConfig);
+    /**
+     * Evaluate an attestation document and determine the resulting trust tier.
+     */
+    evaluateAttestation(doc: AttestationDocument): AttestationResult;
+    /**
+     * Check if an agent's current tier requires attestation.
+     */
+    requiresAttestation(currentTier: string): boolean;
+    /**
+     * Generate an attestation receipt documenting the evaluation.
+     */
+    toReceipt(result: AttestationResult, agentId: string): Record<string, unknown>;
+}
+/**
+ * Configuration for confidential model inference.
+ * Wraps model API calls to ensure data privacy during evaluation.
+ */
+interface ConfidentialInferenceConfig {
+    /** Provider for confidential inference */
+    provider: 'local_tee' | 'homomorphic' | 'secure_enclave';
+    /** Whether to encrypt prompts before sending to the model */
+    encrypt_prompts: boolean;
+    /** Whether to verify model outputs came from the expected enclave */
+    verify_outputs: boolean;
+    /** Homomorphic encryption key (for 'homomorphic' provider) */
+    he_public_key?: string;
+}
+/**
+ * Wraps a model inference call with confidential computing guarantees.
+ *
+ * In 'local_tee' mode: The model runs inside a TEE and provides attestation
+ * that the inference was performed correctly.
+ *
+ * In 'homomorphic' mode: Prompts are encrypted client-side and the model
+ * operates on ciphertext (using Zama Concrete ML or similar).
+ *
+ * In 'secure_enclave' mode: Uses NVIDIA Confidential Computing or similar
+ * hardware to ensure the model cannot see plaintext data.
+ *
+ * Status: Interface only — implementation requires specific TEE/HE SDK integration
+ */
+declare function confidentialInference(_prompt: string, _config: ConfidentialInferenceConfig): Promise<{
+    response: string;
+    attestation?: AttestationDocument;
+    encrypted: boolean;
+    receipt: Record<string, unknown>;
+}>;
+
+export { type ActionReceipt, type AdmissionResult, type AgentId, type AgentManifest, type ApprovalAssertion, type ApprovalChallenge, type ApprovalNotification, type ApprovalResult, type ArenaPayload, type ArenaReceipt, type AttestationDocument, type AttestationPayload, type AttestationProvider, type AttestationReceipt, type AttestationResult, type AuditBundle, type AuditBundleOptions, type BenchmarkPayload, type BenchmarkReceipt, type BuilderId, type C2PAAssertion, type C2PAIngredient, type C2PAManifest, type C2PAOptions, type CalibrationScore, type ComplianceReport, ConfidentialGate, type ConfidentialGateConfig, type ConfidentialInferenceConfig, type CredentialConfig, type DecisionContext, type DecisionLog, type DelegationReceipt, type DisclosureMode, type Ed25519PublicKey, type EvidenceAttestation, type EvidenceAttestationInput, type EvidenceIssuer, type EvidenceReceipt, type EvidenceReceiptBase, type EvidenceSummary, type EvidenceSummaryEntry, type EvidenceType, type ExternalDecision, type ExternalPDPConfig, type HFDatasetMetadata, type HFReceiptRow, type IssuerType, type JsonRpcRequest, type JsonRpcResponse, type LeaseCompatibility, type ManifestBuilder, type ManifestCapabilities, type ManifestConfig, type ManifestIdentity, type ManifestPresentation, type ManifestSignature, type ManifestStatus, type NotificationConfig, type PolicyEngineMode, type PredictionReceipt, type PredictionResolution, type PropagatorConfig, type ProtectConfig, ProtectGateway, type ProtectPolicy, type RateLimit, ReceiptPropagator, type RedactedResult, type RedactionSalt, type RekorAnchor, type RekorVerification, type RestraintPayload, type RestraintReceipt, type SHA256Hash, type SafetyTranscript, type Sandbox, type SandboxConfig, type SandboxReceipt, type SandboxResult, type SandboxToolCall, type SigningConfig, type SimulationResult, type SimulationSummary, type TierOverrides, type ToolPolicy, type TrustTier, type WorkPayload, type WorkReceipt, anchorToRekor, buildDecisionContext, checkRateLimit, collectSignedReceipts, computeCalibration, confidentialInference, createApprovalChallenge, createApprovalReceiptPayload, createAttestationField, createAuditBundle, createC2PAManifest, createDisclosurePackage, createEvidenceAttestation, createLogAnchorField, createReceiptChannel, createSandbox, destroySandbox, ed25519ToDIDKey, evaluateTier, exportC2PAManifestJSON, exportJSONL, formatReportMarkdown, formatSimulation, generateC2PACommand, generateDatasetCard, generateHFMetadata, generateReport, generateSafetyTranscript, getSignerInfo, getToolPolicy, hashReceipt, hashResponseBody, initSigning, isAgentId, isDisclosureMode, isEvidenceType, isManifestStatus, isSigningEnabled, listCredentialLabels, loadPolicy, manifestToVC, meetsMinTier, parseLogFile, parseNotificationConfigFromEnv, parseRateLimit, queryExternalPDP, receiptToVP, receiptsToHFRows, redactFields, resolveCredential, revealField, runInSandbox, sendApprovalNotification, signDecision, simulate, toCredentialRequestOptions, toManifoldFormat, toMetaculusFormat, validateCredentials, validateEvidenceReceipt, validateManifest, verifyActaC2PAAssertions, verifyAllCommitments, verifyApprovalAssertion, verifyCommitment, verifyEvidenceAttestation, verifyRekorAnchor };