protect-mcp 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 interface ProtectPolicy {
     tools: Record<string, ToolPolicy>;
+    /** Default trust tier for unidentified agents (default: "unknown") */
+    default_tier?: TrustTier;
+    /** Policy engine mode */
+    policy_engine?: PolicyEngineMode;
+    /** External PDP endpoint (when policy_engine is "external" or "hybrid") */
+    external?: ExternalPDPConfig;
 }
 interface ToolPolicy {
     /**
@@ -15,6 +21,71 @@ interface ToolPolicy {
     rate_limit?: string;
     /** Explicitly block this tool */
     block?: boolean;
+    /** Minimum trust tier required for this tool (v2) */
+    min_tier?: TrustTier;
+    /** Tier-specific rate limits (v2) */
+    rate_limits?: Partial<Record<TrustTier, {
+        max: number;
+        window: string;
+    }>>;
+}
+type TrustTier = 'unknown' | 'signed-known' | 'evidenced' | 'privileged';
+type PolicyEngineMode = 'built-in' | 'external' | 'hybrid';
+interface ExternalPDPConfig {
+    /** HTTP endpoint for the external policy decision point */
+    endpoint: string;
+    /** Response format: 'opa' | 'cerbos' | 'generic' */
+    format?: 'opa' | 'cerbos' | 'generic';
+    /** Timeout in milliseconds (default: 500) */
+    timeout_ms?: number;
+    /** Fallback decision when external PDP is unreachable */
+    fallback?: 'allow' | 'deny';
+}
+/**
+ * Decision context sent to external PDPs.
+ * Transport-agnostic: works with OPA, Cerbos, or custom engines.
+ */
+interface DecisionContext {
+    v: 1;
+    actor: {
+        id?: string;
+        tier: TrustTier;
+        manifest_hash?: string;
+    };
+    action: {
+        tool: string;
+        operation?: string;
+    };
+    target: {
+        service: string;
+        resource_id?: string;
+    };
+    credential_ref?: string;
+    mode: 'shadow' | 'enforce';
+    request_metadata: Record<string, unknown>;
+}
+/** Response from an external PDP */
+interface ExternalDecision {
+    allowed: boolean;
+    reason?: string;
+    /** Additional metadata from the PDP */
+    metadata?: Record<string, unknown>;
+}
+interface CredentialConfig {
+    /** How the credential is injected: header, query, body */
+    inject: 'header' | 'query' | 'env';
+    /** Header name, query param name, or env var name */
+    name: string;
+    /** Environment variable that holds the actual secret */
+    value_env: string;
+}
+interface SigningConfig {
+    /** Path to the Ed25519 private key file (JSON with privateKey, publicKey) */
+    key_path?: string;
+    /** Issuer identifier (e.g., "my-gateway.example.com") */
+    issuer?: string;
+    /** Whether signing is enabled (default: true when key_path is set) */
+    enabled?: boolean;
 }
 interface RateLimit {
     count: number;
@@ -38,15 +109,17 @@ interface JsonRpcResponse {
 }
 interface DecisionLog {
     /** Schema version */
-    v: 1;
+    v: 1 | 2;
     /** Tool name that was called */
     tool: string;
     /** Decision: allow or deny */
     decision: 'allow' | 'deny';
     /** Why this decision was made */
-    reason_code: 'policy_allow' | 'policy_block' | 'rate_limit_exceeded' | 'observe_mode' | 'default_allow';
+    reason_code: 'policy_allow' | 'policy_block' | 'rate_limit_exceeded' | 'observe_mode' | 'default_allow' | 'tier_insufficient' | 'external_pdp_allow' | 'external_pdp_deny' | 'external_pdp_error';
     /** SHA-256 digest of the canonicalized policy file */
     policy_digest: string;
+    /** Which policy engine made the decision */
+    policy_engine?: PolicyEngineMode;
     /** Unique request identifier */
     request_id: string;
     /** Unix timestamp (ms) */
@@ -54,7 +127,11 @@ interface DecisionLog {
     /** Remaining rate limit budget (if rate limit is configured) */
     rate_limit_remaining?: number;
     /** Operating mode */
-    mode: 'observe' | 'enforce';
+    mode: 'shadow' | 'enforce';
+    /** Trust tier of the agent at decision time (v2) */
+    tier?: TrustTier;
+    /** Credential label used (v2, never the actual secret) */
+    credential_ref?: string;
 }
 interface ProtectConfig {
     /** Command to spawn (first element of child process) */
@@ -67,11 +144,75 @@ interface ProtectConfig {
     policyDigest: string;
     /** ScopeBlind tenant slug (optional, for future API integration) */
     slug?: string;
-    /** Whether to enforce policy (default: false = observe mode) */
+    /** Whether to enforce policy (default: false = shadow mode) */
     enforce?: boolean;
     /** Verbose debug logging to stderr */
     verbose?: boolean;
+    /** Signing configuration */
+    signing?: SigningConfig;
+    /** Credential vault: maps credential labels to injection config */
+    credentials?: Record<string, CredentialConfig>;
+}
+
+/**
+ * @scopeblind/protect-mcp — Trust Tier Admission Evaluator
+ *
+ * Evaluates an agent's presented credentials at connection start
+ * and assigns a trust tier. The tier is used for per-tool policy
+ * evaluation throughout the session.
+ *
+ * Tiers (ascending): unknown → signed-known → evidenced → privileged
+ *
+ * Sprint 2: Simple evaluation (has valid manifest = signed-known).
+ * Full evidence evaluation (evidenced tier) is stubbed.
+ */
+
+/**
+ * Minimal manifest info needed for tier evaluation.
+ * This is not the full manifest — just the fields admission cares about.
+ */
+interface ManifestPresentation {
+    /** Agent identifier (e.g., sb:agent:xxxx) */
+    agent_id: string;
+    /** SHA-256 hash of the canonical manifest */
+    manifest_hash: string;
+    /** Ed25519 public key (hex) */
+    public_key?: string;
+    /** Whether the manifest signature was verified */
+    signature_valid?: boolean;
+    /** Optional evidence summary for tier upgrade */
+    evidence_summary?: {
+        receipt_count: number;
+        epoch_span: number;
+        issuer_count: number;
+    };
 }
+/**
+ * Result of tier admission evaluation.
+ */
+interface AdmissionResult {
+    tier: TrustTier;
+    agent_id?: string;
+    manifest_hash?: string;
+    reason: string;
+}
+/**
+ * Explicit tier overrides from the operator's config.
+ * Maps agent IDs to explicitly assigned tiers.
+ */
+type TierOverrides = Record<string, TrustTier>;
+/**
+ * Evaluate an agent's trust tier based on their presented credentials.
+ *
+ * @param manifest - Manifest presentation from the agent (or null if none)
+ * @param overrides - Operator-configured tier overrides
+ * @returns AdmissionResult with assigned tier
+ */
+declare function evaluateTier(manifest: ManifestPresentation | null, overrides?: TierOverrides): AdmissionResult;
+/**
+ * Check if a trust tier meets the minimum required tier.
+ */
+declare function meetsMinTier(actual: TrustTier, required: TrustTier): boolean;
 
 /**
  * ProtectGateway — stdio MITM proxy for MCP servers.
@@ -79,17 +220,31 @@ interface ProtectConfig {
  * Sits between an MCP client (stdin/stdout) and a wrapped MCP server (child process).
  * Intercepts `tools/call` requests for policy enforcement and decision logging.
  * Passes through all other JSON-RPC messages transparently.
+ *
+ * v2 features:
+ * - Shadow mode (default): observe + signed receipts, no blocking
+ * - Trust-tier gating: evaluate manifest at admission, assign tier
+ * - Credential vault: inject secrets, agent never sees raw keys
+ * - BYOPE: pluggable policy decision via external HTTP webhook
+ * - Signed receipts: every decision produces a signed artifact
  */
 declare class ProtectGateway {
     private child;
     private config;
     private rateLimitStore;
     private clientReader;
+    private currentTier;
+    private admissionResult;
     constructor(config: ProtectConfig);
     /**
      * Start the gateway: spawn child process and wire up message relay.
      */
     start(): Promise<void>;
+    /**
+     * Set the trust tier for this session.
+     * Called at admission (first interaction) or by explicit manifest presentation.
+     */
+    setManifest(manifest: ManifestPresentation | null): AdmissionResult;
     /**
      * Handle a message from the MCP client (stdin).
      * Intercept tools/call requests; pass through everything else.
@@ -104,8 +259,13 @@ declare class ProtectGateway {
      * Intercept a tools/call request. Returns a JSON-RPC error response if denied, null if allowed.
      */
     private interceptToolCall;
+    /**
+     * Get the applicable rate limit spec based on the agent's tier.
+     */
+    private getTierRateLimit;
     /**
      * Emit a structured decision log to stderr.
+     * If signing is enabled, also emits a signed artifact.
      */
     private emitDecisionLog;
     /**
@@ -131,14 +291,19 @@ declare class ProtectGateway {
 }
 
 /**
- * Load and validate a policy file. Returns the policy and its digest.
+ * Load and validate a policy file. Returns the policy, credentials, signing config, and digest.
  */
 declare function loadPolicy(path: string): {
     policy: ProtectPolicy;
     digest: string;
+    credentials?: Record<string, CredentialConfig>;
+    signing?: SigningConfig;
 };
 /**
  * Get the policy for a specific tool. Falls back to "*" wildcard, then default-allow.
+ *
+ * Backwards compatible: old policies with just { block, rate_limit, require }
+ * still work. New policies can add { min_tier, rate_limits }.
  */
 declare function getToolPolicy(toolName: string, policy: ProtectPolicy | null): ToolPolicy;
 /**
@@ -154,4 +319,514 @@ declare function checkRateLimit(key: string, limit: RateLimit, store: Map<string
     remaining: number;
 };
 
-export { type DecisionLog, type JsonRpcRequest, type JsonRpcResponse, type ProtectConfig, ProtectGateway, type ProtectPolicy, type RateLimit, type ToolPolicy, checkRateLimit, getToolPolicy, loadPolicy, parseRateLimit };
+/**
+ * @scopeblind/protect-mcp — Credential Vault
+ *
+ * Config-driven credential injection for MCP tool calls.
+ * The agent NEVER sees the raw credential. protect-mcp holds
+ * the secret and injects it into the appropriate context.
+ *
+ * Credentials are referenced by label in the policy and receipts.
+ * The actual secret value is read from environment variables.
+ *
+ * Example config:
+ * {
+ *   "credentials": {
+ *     "stripe_api": {
+ *       "inject": "header",
+ *       "name": "Authorization",
+ *       "value_env": "STRIPE_KEY"
+ *     },
+ *     "github_token": {
+ *       "inject": "header",
+ *       "name": "Authorization",
+ *       "value_env": "GITHUB_TOKEN"
+ *     }
+ *   }
+ * }
+ */
+
+/**
+ * Result of credential resolution.
+ */
+interface CredentialResolution {
+    /** Whether the credential was found and resolved */
+    resolved: boolean;
+    /** The credential label (safe to log, never the actual value) */
+    label: string;
+    /** Error message if resolution failed */
+    error?: string;
+    /** The resolved value (NEVER log this) */
+    value?: string;
+    /** How the credential should be injected */
+    inject?: 'header' | 'query' | 'env';
+    /** Injection target name (header name, query param, env var) */
+    name?: string;
+}
+/**
+ * Resolve a credential from the vault.
+ * Reads the actual secret from the environment variable specified in config.
+ *
+ * @param label - Credential label (e.g., "stripe_api")
+ * @param credentials - Credential configuration map
+ * @returns CredentialResolution (value is only populated on success)
+ */
+declare function resolveCredential(label: string, credentials: Record<string, CredentialConfig> | undefined): CredentialResolution;
+/**
+ * Get the list of configured credential labels (safe to log).
+ *
+ * @param credentials - Credential configuration map
+ * @returns Array of credential labels
+ */
+declare function listCredentialLabels(credentials: Record<string, CredentialConfig> | undefined): string[];
+/**
+ * Validate credential configuration at startup.
+ * Checks that all referenced environment variables exist.
+ *
+ * @param credentials - Credential configuration map
+ * @returns Array of warnings for missing env vars
+ */
+declare function validateCredentials(credentials: Record<string, CredentialConfig> | undefined): string[];
+
+/**
+ * @scopeblind/protect-mcp — Signing Integration
+ *
+ * Produces signed v2 artifact receipts for tool call decisions.
+ * Uses @veritasacta/artifacts as a required dependency (Sprint 2+).
+ *
+ * If signing is configured, every decision produces a signed artifact.
+ * If signing fails, the receipt is emitted unsigned with signature: null
+ * and a warning — never crashes, never silently drops.
+ */
+
+/**
+ * Initialize the signing subsystem.
+ * Loads the key file and dynamically imports @veritasacta/artifacts.
+ *
+ * @param config - Signing configuration
+ * @returns Array of warnings (empty = success)
+ */
+declare function initSigning(config: SigningConfig | undefined): Promise<string[]>;
+/**
+ * Sign a decision log entry as a v2 artifact.
+ *
+ * Returns the signed artifact JSON string, or null if signing is not configured.
+ * On signing failure, returns an unsigned artifact with a warning.
+ */
+declare function signDecision(entry: DecisionLog): {
+    signed: string | null;
+    artifact_type: string;
+    warning?: string;
+};
+/**
+ * Get the signer's public key info for discovery/verification.
+ */
+declare function getSignerInfo(): {
+    publicKey: string;
+    kid: string;
+    issuer: string;
+} | null;
+/**
+ * Check if signing is available.
+ */
+declare function isSigningEnabled(): boolean;
+
+/**
+ * @scopeblind/protect-mcp — External PDP Adapter
+ *
+ * BYOPE (Bring Your Own Policy Engine) — sends decision context
+ * to an external Policy Decision Point via HTTP webhook.
+ *
+ * Supports OPA, Cerbos, and generic JSON formats.
+ * ScopeBlind always signs the receipt regardless of who made the decision.
+ *
+ * Sprint 2: One HTTP webhook adapter. More adapters later.
+ */
+
+/**
+ * Query an external PDP for a policy decision.
+ *
+ * @param context - The decision context (transport-agnostic)
+ * @param config - External PDP configuration
+ * @returns ExternalDecision with allow/deny and optional metadata
+ */
+declare function queryExternalPDP(context: DecisionContext, config: ExternalPDPConfig): Promise<ExternalDecision>;
+/**
+ * Build a DecisionContext from a tool call.
+ */
+declare function buildDecisionContext(toolName: string, tier: TrustTier, opts: {
+    agentId?: string;
+    manifestHash?: string;
+    credentialRef?: string;
+    mode: 'shadow' | 'enforce';
+    slug?: string;
+    requestMetadata?: Record<string, unknown>;
+}): DecisionContext;
+
+/**
+ * @scopeblind/protect-mcp — Audit Bundle Export
+ *
+ * Creates self-contained audit bundles that can be verified offline.
+ * A bundle includes receipts, optional anchors, and the signing keys
+ * needed to verify everything — no network calls required.
+ *
+ * Format:
+ * {
+ *   format: "scopeblind:audit-bundle",
+ *   version: 1,
+ *   exported_at: ISO-8601,
+ *   tenant: string,
+ *   time_range: { from, to },
+ *   receipts: [...signed v2 artifacts...],
+ *   anchors: [...optional audit anchors...],
+ *   verification: {
+ *     algorithm: "ed25519",
+ *     signing_keys: [...JWK keys needed to verify all receipts...],
+ *     instructions: "..."
+ *   }
+ * }
+ */
+
+interface AuditBundleOptions {
+    /** Tenant/service identifier */
+    tenant: string;
+    /** Time range for exported receipts */
+    timeRange?: {
+        from: string;
+        to: string;
+    };
+    /** Signed v2 artifacts (decision_receipts and/or gateway_restraints) */
+    receipts: Record<string, unknown>[];
+    /** Optional audit anchors */
+    anchors?: Record<string, unknown>[];
+    /** JWK signing keys used by the receipts */
+    signingKeys: Array<{
+        kty: string;
+        crv: string;
+        kid: string;
+        x: string;
+        use?: string;
+    }>;
+}
+interface AuditBundle {
+    format: 'scopeblind:audit-bundle';
+    version: 1;
+    exported_at: string;
+    tenant: string;
+    time_range: {
+        from: string;
+        to: string;
+    } | null;
+    receipts: Record<string, unknown>[];
+    anchors: Record<string, unknown>[];
+    verification: {
+        algorithm: 'ed25519';
+        signing_keys: Array<{
+            kty: string;
+            crv: string;
+            kid: string;
+            x: string;
+            use?: string;
+        }>;
+        instructions: string;
+    };
+}
+/**
+ * Create a self-contained audit bundle for offline verification.
+ *
+ * The bundle contains everything needed to verify all receipts:
+ * - The signed receipts themselves
+ * - The public keys used to sign them
+ * - Verification instructions
+ *
+ * No network access required to verify.
+ */
+declare function createAuditBundle(opts: AuditBundleOptions): AuditBundle;
+/**
+ * Collect decision log entries into signed receipts suitable for bundling.
+ * Filters for entries that have attached signed artifacts.
+ */
+declare function collectSignedReceipts(logs: DecisionLog[]): Record<string, unknown>[];
+
+/**
+ * Agent identity format: sb:agent:{first 32 hex chars of SHA-256(public key bytes)}
+ * Example: "sb:agent:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
+ */
+type AgentId = `sb:agent:${string}`;
+/**
+ * Builder identity format: sb:builder:{hash}
+ */
+type BuilderId = `sb:builder:${string}`;
+/**
+ * Ed25519 public key in prefixed format: "ed25519:{base64url}"
+ */
+type Ed25519PublicKey = `ed25519:${string}`;
+/**
+ * SHA-256 hash in prefixed format: "sha256:{hex}"
+ */
+type SHA256Hash = `sha256:${string}`;
+/**
+ * Manifest lifecycle status.
+ * - active:    Agent is operational. Operators should grant access per policy.
+ * - suspended: Temporarily disabled. Builder is investigating. Reversible.
+ * - revoked:   Permanently disabled. Irreversible. New keypair needed.
+ */
+type ManifestStatus = 'active' | 'suspended' | 'revoked';
+/**
+ * ScopeBlind disclosure modes — governance decision, not implementation detail.
+ * - private: Minimum-disclosure. Unlinkable, single-use identity.
+ * - scoped:  Pseudonymous. Deterministic per-service hash.
+ * - named:   Full attribution. Explicit identifier.
+ */
+type DisclosureMode = 'private' | 'scoped' | 'named';
+/**
+ * The five evidence types in the Agent Economy taxonomy.
+ * Evidence and claims/interpretation are ALWAYS separate layers.
+ */
+type EvidenceType = 'arena' | 'benchmark' | 'work' | 'restraint' | 'attestation';
+interface AgentManifest {
+    /** Spec version. Always "0.1" for this version. */
+    manifest_version: '0.1';
+    /** Stable agent identity: sb:agent:{public_key_hash} */
+    id: AgentId;
+    /** Monotonically increasing version number. Starts at 1. */
+    version: number;
+    /**
+     * SHA-256 of the previous manifest version's canonical JSON.
+     * Null for the first version. Creates an append-only version chain.
+     */
+    previous_version: SHA256Hash | null;
+    /** ISO 8601 timestamp — when this manifest version was created. */
+    created_at: string;
+    /** ISO 8601 timestamp — when this manifest was last modified. */
+    updated_at: string;
+    /** ISO 8601 timestamp — when this manifest expires. Null means no expiry. */
+    expires_at: string | null;
+    /** Lifecycle status of this agent. */
+    status: ManifestStatus;
+    /** Human-readable reason when suspended or revoked. Null if active. */
+    status_reason: string | null;
+    /** ISO 8601 timestamp of last status change. Null if always active. */
+    status_changed_at: string | null;
+    identity: ManifestIdentity;
+    capabilities: ManifestCapabilities;
+    config: ManifestConfig;
+    evidence_summary: EvidenceSummary;
+    lease_compatibility: LeaseCompatibility;
+    signature: ManifestSignature;
+}
+interface ManifestIdentity {
+    /** Ed25519 public key: "ed25519:{base64url}" */
+    public_key: Ed25519PublicKey;
+    /** Key algorithm. Always "Ed25519" in v0.1. */
+    key_algorithm: 'Ed25519';
+    /** Builder information. All fields optional — builder can remain pseudonymous. */
+    builder: ManifestBuilder;
+}
+interface ManifestBuilder {
+    /** Builder's display name. Optional. */
+    name?: string;
+    /** Builder's contact information. Optional. */
+    contact?: string;
+    /** ScopeBlind builder identity. Optional. */
+    id?: BuilderId;
+}
+interface ManifestCapabilities {
+    /**
+     * SHA-256 hash of the model identifier string.
+     * Hides exact model while allowing change detection.
+     */
+    model_family_hash: SHA256Hash;
+    /** Declared tool usage categories (e.g., "file_read", "web_search"). */
+    tool_categories: string[];
+    /** Which ScopeBlind disclosure modes this agent supports. */
+    supported_disclosure_modes: DisclosureMode[];
+    /** Declared maximum context window size. Optional. */
+    max_context_tokens?: number;
+    /** ISO 639-1 language codes the agent supports. Optional. */
+    languages?: string[];
+}
+interface ManifestConfig {
+    /** SHA-256 of the system prompt text. Config hash, not config. */
+    system_prompt_hash: SHA256Hash;
+    /** SHA-256 of the canonical JSON of tool definitions. */
+    tool_definitions_hash: SHA256Hash;
+    /** SHA-256 of the canonical JSON of model parameters. */
+    parameters_hash: SHA256Hash;
+    /** Builder's internal version label. Optional. */
+    config_version?: string;
+}
+interface EvidenceSummaryEntry {
+    /** Total number of receipts of this type. */
+    count: number;
+    /** ISO 8601 timestamp of the most recent receipt. */
+    latest_at: string;
+    /** Identity of the primary issuer for this evidence type. */
+    issuer: string;
+}
+interface EvidenceSummary {
+    arena: EvidenceSummaryEntry;
+    benchmark: EvidenceSummaryEntry;
+    work: EvidenceSummaryEntry;
+    restraint: EvidenceSummaryEntry;
+    attestation: EvidenceSummaryEntry;
+}
+interface LeaseCompatibility {
+    /** Minimum protect-mcp policy version this agent supports. Optional. */
+    min_policy_version?: string;
+    /** Rate limit thresholds the agent is designed to work within. Optional. */
+    accepted_rate_limits?: {
+        default?: string;
+        max_burst?: string;
+    };
+    /** Tools the agent must have access to in order to function. Optional. */
+    required_tools?: string[];
+    /** Tools the agent can use but doesn't require. Optional. */
+    optional_tools?: string[];
+}
+interface ManifestSignature {
+    /** Signature algorithm. Always "Ed25519" in v0.1. */
+    algorithm: 'Ed25519';
+    /** Identity of the signer. Self-signed in v1 trust model. */
+    signer: AgentId | string;
+    /** Base64url-encoded signature over canonical JSON of all fields except signature. */
+    value: string;
+}
+/**
+ * Issuer type classifies who is signing the evidence receipt.
+ * - platform:  Automated platform (arena, benchmark suite, task marketplace)
+ * - human:     Individual human attestor
+ * - gateway:   protect-mcp or similar gateway (generates restraint evidence)
+ * - evaluator: Evaluation framework or benchmarking system
+ */
+type IssuerType = 'platform' | 'human' | 'gateway' | 'evaluator';
+interface EvidenceIssuer {
+    /** Issuer identity string (domain, sb:user:..., etc.) */
+    id: string;
+    /** What kind of entity is issuing this evidence. */
+    type: IssuerType;
+    /** Issuer's Ed25519 public key for signature verification. */
+    public_key: Ed25519PublicKey;
+}
+interface EvidenceReceiptBase {
+    /** Spec version. Always "0.1" for this version. */
+    receipt_version: '0.1';
+    /** Unique receipt identifier: "ev:{type}:{hash}" */
+    receipt_id: string;
+    /** Which of the 5 evidence types this receipt represents. */
+    evidence_type: EvidenceType;
+    /** Which agent this evidence is about. */
+    agent_id: AgentId;
+    /** Who signed this evidence receipt. */
+    issuer: EvidenceIssuer;
+    /** ISO 8601 timestamp — when this receipt was issued. */
+    issued_at: string;
+    /** ISO 8601 timestamp — hard expiry. Null if using freshness_window. */
+    expires_at: string | null;
+    /** Freshness window in seconds. Consumer decides if fresh enough. */
+    freshness_window_seconds: number;
+    signature: {
+        algorithm: 'Ed25519';
+        signer: string;
+        value: string;
+    };
+}
+interface ArenaPayload {
+    battle_id: string;
+    /** SHA-256 hash of opponent agent ID (privacy: don't reveal opponent). */
+    opponent_hash: SHA256Hash;
+    outcome: 'win' | 'loss' | 'tie';
+    /** Optional category tag for the prompt. */
+    prompt_category?: string;
+    platform: string;
+}
+interface BenchmarkPayload {
+    suite_id: string;
+    suite_version: string;
+    scores: {
+        overall: number;
+        categories?: Record<string, number>;
+    };
+    run_id: string;
+    /** SHA-256 hash of benchmark configuration (reproducibility). */
+    run_config_hash?: SHA256Hash;
+}
+interface WorkPayload {
+    task_id: string;
+    task_category: string;
+    outcome: 'success' | 'partial' | 'failure';
+    /** Optional quantification of work done. */
+    item_count?: number;
+    error_count?: number;
+    /** Link to human reviewer's attestation receipt. */
+    reviewer_attestation_id?: string;
+}
+interface RestraintPayload {
+    policy_digest: string;
+    /** ISO 8601 — start of the observation window. */
+    window_start: string;
+    /** ISO 8601 — end of the observation window. */
+    window_end: string;
+    total_calls: number;
+    allow_count: number;
+    deny_count: number;
+    deny_reason_codes: string[];
+    mode: 'observe' | 'enforce';
+}
+interface AttestationPayload {
+    /** Narrow, specific statement about observed behavior. NOT a general endorsement. */
+    statement: string;
+    /** Scope of the attestation (e.g., "invoice_processing"). */
+    scope: string;
+    /** ISO 8601 — start of the observation period. */
+    observed_period_start: string;
+    /** ISO 8601 — end of the observation period. */
+    observed_period_end: string;
+    attestor_type: 'human' | 'organization';
+}
+interface ArenaReceipt extends EvidenceReceiptBase {
+    evidence_type: 'arena';
+    payload: ArenaPayload;
+}
+interface BenchmarkReceipt extends EvidenceReceiptBase {
+    evidence_type: 'benchmark';
+    payload: BenchmarkPayload;
+}
+interface WorkReceipt extends EvidenceReceiptBase {
+    evidence_type: 'work';
+    payload: WorkPayload;
+}
+interface RestraintReceipt extends EvidenceReceiptBase {
+    evidence_type: 'restraint';
+    payload: RestraintPayload;
+}
+interface AttestationReceipt extends EvidenceReceiptBase {
+    evidence_type: 'attestation';
+    payload: AttestationPayload;
+}
+/** Union type for all evidence receipt variants. */
+type EvidenceReceipt = ArenaReceipt | BenchmarkReceipt | WorkReceipt | RestraintReceipt | AttestationReceipt;
+/** Check if a string is a valid agent ID format. */
+declare function isAgentId(s: string): s is AgentId;
+/** Check if a string is a valid evidence type. */
+declare function isEvidenceType(s: string): s is EvidenceType;
+/** Check if a string is a valid manifest status. */
+declare function isManifestStatus(s: string): s is ManifestStatus;
+/** Check if a string is a valid disclosure mode. */
+declare function isDisclosureMode(s: string): s is DisclosureMode;
+/**
+ * Validate the structural integrity of a manifest (types and required fields).
+ * Does NOT verify the cryptographic signature — use verifyManifestSignature() for that.
+ *
+ * Returns an array of error strings. Empty array = valid.
+ */
+declare function validateManifest(manifest: unknown): string[];
+/**
+ * Validate the structural integrity of an evidence receipt.
+ * Does NOT verify the cryptographic signature.
+ *
+ * Returns an array of error strings. Empty array = valid.
+ */
+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 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 TierOverrides, type ToolPolicy, type TrustTier, type WorkPayload, type WorkReceipt, buildDecisionContext, checkRateLimit, collectSignedReceipts, createAuditBundle, evaluateTier, getSignerInfo, getToolPolicy, initSigning, isAgentId, isDisclosureMode, isEvidenceType, isManifestStatus, isSigningEnabled, listCredentialLabels, loadPolicy, meetsMinTier, parseRateLimit, queryExternalPDP, resolveCredential, signDecision, validateCredentials, validateEvidenceReceipt, validateManifest };