@sanctuary-framework/mcp-server 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -6,7 +6,6 @@ import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 interface SanctuaryConfig {
     version: string;
     storage_path: string;
-    principal_id?: string;
     state: {
         encryption: "aes-256-gcm";
         key_protection: "passphrase" | "hardware-key" | "none";
@@ -146,17 +145,31 @@ interface AuditEntry {
     result: "success" | "failure";
     details?: Record<string, unknown>;
 }
+interface AuditLogConfig {
+    /** Maximum total size of stored audit entries in bytes. Default: 100 MB. */
+    maxTotalSizeBytes?: number;
+    /** Maximum number of stored audit entry files to retain. Default: 100_000. */
+    maxEntries?: number;
+}
 declare class AuditLog {
     private storage;
     private encryptionKey;
     private entries;
     private counter;
-    constructor(storage: StorageBackend, masterKey: Uint8Array);
+    private readonly maxTotalSizeBytes;
+    private readonly maxEntries;
+    private rotationInFlight;
+    constructor(storage: StorageBackend, masterKey: Uint8Array, config?: AuditLogConfig);
     /**
      * Append an audit entry.
      */
     append(layer: AuditEntry["layer"], operation: string, identityId: string, details?: Record<string, unknown>, result?: "success" | "failure"): void;
     private persistEntry;
+    /**
+     * Prune oldest audit entries when storage exceeds configured limits.
+     * Entries are sorted by key (timestamp-based) so oldest are pruned first.
+     */
+    private maybeRotate;
     /**
      * Query the audit log with filtering.
      */
@@ -762,7 +775,18 @@ declare class StateStore {
     private masterKey;
     private versionCache;
     private contentHashes;
+    private namespaceKeyCache;
+    private static readonly KEY_CACHE_TTL_MS;
+    private static readonly KEY_CACHE_MAX_ENTRIES;
     constructor(storage: StorageBackend, masterKey: Uint8Array);
+    /**
+     * Get or derive a namespace encryption key, with caching.
+     * Cache entries expire after 15 minutes and are evicted LRU when
+     * the cache exceeds 128 entries.
+     */
+    private getNamespaceKey;
+    /** Invalidate all cached namespace keys (call on master key rotation). */
+    invalidateKeyCache(): void;
     private versionKey;
     /**
      * Get or initialize the content hash map for a namespace.
@@ -906,6 +930,10 @@ declare class IdentityManager {
     getDefault(): StoredIdentity | undefined;
     getPrimaryIdentityId(): string | null;
     list(): PublicIdentity[];
+    /** List identities with rotation count (for dashboard display). */
+    listWithRotationCount(): Array<PublicIdentity & {
+        rotation_count: number;
+    }>;
 }
 
 /**
@@ -1185,7 +1213,7 @@ declare class PolicyStore {
  */
 type LayerStatus = "active" | "degraded" | "inactive";
 type DegradationSeverity = "info" | "warning" | "critical";
-type DegradationCode = "NO_TEE" | "PROCESS_ISOLATION_ONLY" | "COMMITMENT_ONLY" | "NO_ZK_PROOFS" | "SELF_REPORTED_ATTESTATION" | "NO_SELECTIVE_DISCLOSURE" | "BASIC_SYBIL_ONLY";
+type DegradationCode = "NO_TEE" | "PROCESS_ISOLATION_ONLY" | "COMMITMENT_ONLY" | "NO_ZK_PROOFS" | "SELF_REPORTED_ATTESTATION" | "NO_SELECTIVE_DISCLOSURE" | "BASIC_SYBIL_ONLY" | "NO_REPUTATION_HISTORY" | "LOW_TIER_DOMINANCE" | "STALE_REPUTATION" | "DISPUTE_ON_RECORD" | "NO_VERASCORE_LINK";
 interface SHRLayerL1 {
     status: LayerStatus;
     encryption: string;
@@ -1478,6 +1506,23 @@ interface ReputationSummary {
     };
     aggregate_metrics: Record<string, MetricAggregate>;
 }
+/**
+ * L4 attestation evidence summary for the SHR degradation emitter and the
+ * dashboard evidence widget. Derived from the stored attestations; does not
+ * include Verascore-link state (tracked separately via audit log).
+ */
+interface L4AttestationSummary {
+    /** Total number of attestations covered by the summary */
+    attestation_count: number;
+    /** Count of attestations at each sovereignty tier */
+    tier_distribution: Record<SovereigntyTier, number>;
+    /** ISO timestamp of the most recent attestation, or null if none */
+    most_recent_attestation_at: string | null;
+    /** Count of attestations with outcome_result === "disputed" */
+    dispute_count: number;
+    /** Count of attestations per context label */
+    context_breakdown: Record<string, number>;
+}
 /** Portable reputation bundle */
 interface ReputationBundle {
     version: "SANCTUARY_REP_V1";
@@ -1557,6 +1602,20 @@ declare class ReputationStore {
      * Create a principal's guarantee for a new agent.
      */
     createGuarantee(principalIdentity: StoredIdentity, agentDid: string, scope: string, durationSeconds: number, identityEncryptionKey: Uint8Array, maxLiability?: number): Promise<Guarantee>;
+    /**
+     * Summarize attestations for the L4 degradation emitter and dashboard widget.
+     *
+     * Returns aggregate evidence about the identity's reputation state —
+     * counts, tier distribution, recency, dispute counts, context coverage —
+     * without exposing raw attestations. The caller combines this with an
+     * audit-log check for Verascore link state to produce the final
+     * `L4Evidence` struct consumed by the SHR generator.
+     *
+     * @param participantDid - If provided, only count attestations where the
+     *   `participant_did` matches. If omitted, covers all attestations in the
+     *   store.
+     */
+    summarizeForSHR(participantDid?: string): Promise<L4AttestationSummary>;
     /**
      * Load attestations for tier-weighted scoring.
      * Applies basic context/counterparty filtering, returns full StoredAttestations
@@ -1567,6 +1626,11 @@ declare class ReputationStore {
         counterparty_did?: string;
     }): Promise<StoredAttestation[]>;
     private loadAll;
+    /**
+     * Cursor-based async iterator that loads attestations in pages.
+     * Prevents OOM at 100K+ records by reading and decrypting in batches.
+     */
+    loadAllPaginated(pageSize?: number): AsyncGenerator<StoredAttestation[]>;
 }
 
 /**
@@ -2664,12 +2728,56 @@ declare function loadPrincipalPolicy(storagePath: string): Promise<PrincipalPoli
  * signs it with a specified identity, and returns the complete signed SHR.
  */
 
+/**
+ * Observed L4 reputation state used by the emitter. Callers gather these
+ * facts from the reputation store + audit log; the emitter derives
+ * degradations from them. Keeping evidence as plain data keeps the
+ * generator synchronous and easy to test.
+ */
+interface L4Evidence {
+    /** Total attestations attributed to the signing identity */
+    attestation_count: number;
+    /** Count of attestations at each sovereignty tier */
+    tier_distribution: Record<SovereigntyTier, number>;
+    /** ISO timestamp of most recent attestation, or null when none exist */
+    most_recent_attestation_at: string | null;
+    /** Count of attestations with outcome_result === "disputed" */
+    dispute_count: number;
+    /** Attestation count per context label (optional; used by dashboard) */
+    context_breakdown?: Record<string, number>;
+    /**
+     * True iff the `reputation_publish` tool has been successfully invoked
+     * for this identity (i.e., there is at least one success audit entry).
+     */
+    verascore_linked: boolean;
+    /**
+     * Optional overrides for the emitter thresholds. Defaults apply when
+     * omitted or when a field is missing.
+     */
+    thresholds?: {
+        freshness_window_days?: number;
+        low_tier_dominance_threshold?: number;
+    };
+}
 interface SHRGeneratorOptions {
     config: SanctuaryConfig;
     identityManager: IdentityManager;
     masterKey: Uint8Array;
     /** Override validity window (milliseconds). Default: 1 hour. */
     validityMs?: number;
+    /**
+     * Optional L4 reputation evidence. When provided, the generator emits
+     * L4 degradations (NO_REPUTATION_HISTORY, LOW_TIER_DOMINANCE,
+     * STALE_REPUTATION, DISPUTE_ON_RECORD, NO_VERASCORE_LINK) accordingly
+     * and downgrades `layers.l4.status` to `degraded` when any fire.
+     * When omitted, L4 is left at "active" (backward-compatible).
+     */
+    l4Evidence?: L4Evidence;
+    /**
+     * Clock override for deterministic testing of staleness behavior.
+     * Defaults to the current wall clock.
+     */
+    now?: Date;
 }
 /**
  * Generate and sign a Sovereignty Health Report.
@@ -3364,6 +3472,279 @@ declare function createBridgeCommitment(outcome: ConcordiaOutcome, identity: Sto
  */
 declare function verifyBridgeCommitment(commitment: BridgeCommitment, outcome: ConcordiaOutcome, committerPublicKey: Uint8Array): BridgeVerificationResult;
 
+/**
+ * Sanctuary Dashboard — Protection Snapshot Aggregator
+ *
+ * Pulls unified protection state from the existing subsystems
+ * (IdentityManager, AuditLog, ClientManager, BaselineTracker, policy)
+ * and returns a single typed snapshot consumed by the API + HTML.
+ *
+ * The aggregator is the single source of truth for dashboard state.
+ * It is pure (no I/O beyond what the injected sources already do) and
+ * safe to call repeatedly — callers control freshness.
+ */
+
+type LayerState = "full" | "degraded" | "compromised";
+type OverallStatus = "healthy" | "degraded" | "compromised";
+interface AgentInfo {
+    display_name: string;
+    did: string | null;
+    did_fingerprint: string | null;
+    identity_count: number;
+    primary_identity_id: string | null;
+}
+interface L1Status {
+    label: string;
+    state: LayerState;
+    headline: string;
+    encryption: string;
+    injection_blocked_today: number;
+    memory_attest_ready: boolean;
+}
+interface L2Status {
+    label: string;
+    state: LayerState;
+    headline: string;
+    isolation_type: string;
+    tee_available: boolean;
+    tee_status: string;
+    sandbox_status: string;
+}
+interface L3Status {
+    label: string;
+    state: LayerState;
+    headline: string;
+    did_active: boolean;
+    vc_count: number;
+    proofs_today: number;
+}
+/** A single L4 degradation surfaced to the dashboard widget. */
+interface L4ActiveDegradation {
+    code: string;
+    severity: "info" | "warning" | "critical";
+    description: string;
+    mitigation?: string;
+}
+interface L4Status {
+    label: string;
+    state: LayerState;
+    headline: string;
+    score: number | null;
+    profile_url: string | null;
+    claim_cta: string | null;
+    /**
+     * Evidence surfaced under the L4 tile so users can tell what underlies
+     * the reputation state. Null when no reputation store is wired in
+     * (standalone mode, some tests).
+     */
+    evidence?: {
+        attestation_count: number;
+        tier_distribution: Record<SovereigntyTier, number>;
+        most_recent_attestation_at: string | null;
+        dispute_count: number;
+        context_breakdown: Record<string, number>;
+        verascore_linked: boolean;
+    };
+    /**
+     * SHR-aligned L4 layer score (0-100) when evidence is available.
+     * Computed with the same scoring model the gateway adapter uses so
+     * counterparties and the dashboard agree on the number.
+     */
+    layer_score?: number;
+    /** Active L4 degradations rendered under the widget. */
+    active_degradations?: L4ActiveDegradation[];
+}
+interface ActivityEntry {
+    timestamp: string;
+    tool: string;
+    server: string;
+    tier: 1 | 2 | 3;
+    result: "allowed" | "denied" | "approved" | "pending";
+}
+interface PendingApproval {
+    id: string;
+    operation: string;
+    tier: 1 | 2;
+    reason: string;
+    created_at: string;
+}
+interface UpstreamServerStatus {
+    name: string;
+    state: string;
+    tool_count: number;
+    error?: string;
+}
+interface ProtectionSnapshot {
+    overall: {
+        status: OverallStatus;
+        light: "green" | "yellow" | "red";
+        headline: string;
+    };
+    agent: AgentInfo;
+    layers: {
+        l1: L1Status;
+        l2: L2Status;
+        l3: L3Status;
+        l4: L4Status;
+    };
+    activity: ActivityEntry[];
+    pending_approvals: PendingApproval[];
+    audit: AuditEntry[];
+    upstream_servers: UpstreamServerStatus[];
+    mode: "co-located" | "standalone";
+    server_version: string;
+    generated_at: string;
+}
+interface ReputationLookup {
+    score: number | null;
+    profile_url: string | null;
+}
+interface AggregatorSources {
+    mode: "co-located" | "standalone";
+    server_version: string;
+    identityManager?: IdentityManager;
+    auditLog?: AuditLog;
+    clientManager?: ClientManager;
+    baseline?: BaselineTracker;
+    policy?: PrincipalPolicy;
+    activity?: ActivityEntry[];
+    pendingApprovals?: PendingApproval[];
+    reputation?: ReputationLookup;
+    teeAvailable?: boolean;
+    /**
+     * Pre-computed L4 reputation evidence for the primary identity. When
+     * present the dashboard renders the evidence widget under the L4 tile
+     * and computes an SHR-aligned L4 layer score. Providers build this
+     * via `gatherL4Evidence` from `shr/tools.ts`.
+     */
+    l4Evidence?: L4Evidence;
+    /** Clock override for deterministic staleness rendering in tests. */
+    l4Now?: Date;
+}
+/**
+ * Pull a unified protection snapshot from the injected sources.
+ *
+ * Any missing source degrades gracefully — standalone mode may have
+ * no ClientManager or live activity feed, for example, and the
+ * aggregator returns a coherent snapshot with empty arrays rather
+ * than throwing.
+ */
+declare function getProtectionSnapshot(sources: AggregatorSources): Promise<ProtectionSnapshot>;
+
+/**
+ * Sanctuary Dashboard — HTTP API + SSE
+ *
+ * Request router for the unified dashboard. Pure functions that
+ * take a request + sources and produce a response so the transport
+ * layer (node:http) and tests can exercise the same code paths.
+ */
+
+interface ApprovalHandlers {
+    allow: (id: string) => Promise<boolean>;
+    deny: (id: string) => Promise<boolean>;
+}
+interface StreamEvent {
+    type: "snapshot" | "activity" | "approval";
+    data: unknown;
+}
+
+/**
+ * Sanctuary Dashboard — HTTP Server
+ *
+ * Thin wrapper around node:http that wires the request handler
+ * from api.ts. No Express. Listens on 127.0.0.1 by default.
+ *
+ * Exposes a minimal event emitter (publish / subscribe) so callers
+ * can push live activity + approval events to SSE clients without
+ * the server layer needing to know about aggregator internals.
+ */
+
+interface DashboardServerOptions {
+    port?: number;
+    host?: string;
+    authToken?: string;
+    mode: "co-located" | "standalone";
+    sources: AggregatorSources;
+    approvals?: ApprovalHandlers;
+}
+interface DashboardHandle {
+    url: string;
+    port: number;
+    host: string;
+    stop: () => Promise<void>;
+    /** Push an event to all connected SSE clients. */
+    publish: (event: StreamEvent) => void;
+    /**
+     * Push a fresh activity entry. Exposes a simple shortcut so callers
+     * (e.g. the Sanctuary proxy / upstream clients) can report tool calls
+     * without constructing a StreamEvent themselves.
+     */
+    publishActivity: (entry: ActivityEntry) => void;
+    /** Push a new pending approval (already added by the approval channel). */
+    publishApproval: (approval: PendingApproval) => void;
+}
+declare function startDashboardServer(options: DashboardServerOptions): Promise<DashboardHandle>;
+
+/**
+ * Sanctuary Dashboard — Single-Page HTML
+ *
+ * Hero shield + four layer cards + live activity feed + approval queue +
+ * audit trail. Vanilla HTML/CSS/JS in one string, matching the convention
+ * established by server/src/cocoon/fortress-view.ts.
+ *
+ * The initial snapshot is embedded server-side so the page renders
+ * correctly without JavaScript. Live updates layer on via SSE + REST.
+ */
+
+/** Hero copy. Change here if we ever A/B test. */
+declare const HERO_COPY = "Your agent is protected.";
+interface DashboardHTMLOptions {
+    snapshot: ProtectionSnapshot;
+    authToken?: string;
+}
+declare function renderDashboardHTML(options: DashboardHTMLOptions): string;
+
+/**
+ * Sanctuary Sovereignty Dashboard — public surface.
+ *
+ * Consumers import `startDashboard` to bring up the hero-shield UI
+ * on port 3501 (default). The rest of the exports are types + utilities
+ * for tests and callers that want to wire in live events.
+ */
+
+interface StartDashboardOptions {
+    port?: number;
+    host?: string;
+    authToken?: string;
+    mode: "co-located" | "standalone";
+    serverVersion: string;
+    auditLog?: AuditLog;
+    identityManager?: IdentityManager;
+    clientManager?: ClientManager;
+    baseline?: BaselineTracker;
+    policy?: PrincipalPolicy;
+    reputation?: ReputationLookup;
+    teeAvailable?: boolean;
+    approvals?: ApprovalHandlers;
+    /** Seed activity entries (most recent first). Runtime entries arrive via publishActivity. */
+    initialActivity?: ActivityEntry[];
+    /** Seed pending approvals. Runtime approvals arrive via publishApproval. */
+    initialPendingApprovals?: PendingApproval[];
+    /**
+     * Pre-computed L4 reputation evidence. When provided the dashboard
+     * renders the L4 evidence widget (attestation count, tier distribution,
+     * disputes, freshness, active degradations). Typically supplied by the
+     * server after L4 tools are constructed.
+     */
+    l4Evidence?: L4Evidence;
+}
+/**
+ * High-level entry point used by callers (CLI, standalone service).
+ * Returns a DashboardHandle that exposes `stop()` and `publish*`
+ * helpers for driving live updates.
+ */
+declare function startDashboard(options: StartDashboardOptions): Promise<DashboardHandle>;
+
 /**
  * Sanctuary MCP Server — Main Entry Point
  *
@@ -3397,4 +3778,4 @@ declare function createSanctuaryServer(options?: {
     storage?: StorageBackend;
 }): Promise<SanctuaryServer>;
 
-export { ATTESTATION_VERSION, ApprovalGate, type AttestationBody, type AttestationVerificationResult, AuditLog, AutoApproveChannel, BaselineTracker, type BridgeAttestationRequest, type BridgeAttestationResult, type BridgeCommitment, type BridgeVerificationResult, TEMPLATES as CONTEXT_GATE_TEMPLATES, CallbackApprovalChannel, ClientManager, CommitmentStore, type ConcordiaOutcome, type ConnectionState, type ContextAction, type ContextFilterResult, ContextGateEnforcer, type ContextGatePolicy, ContextGatePolicyStore, type ContextGateRule, type ContextGateTemplate, DashboardApprovalChannel, type DashboardConfig, type DetectionResult, type EnforcerConfig, type FederationCapabilities, type FederationPeer, FederationRegistry, type FieldClassification, type FieldFilterResult, FilesystemStorage, type GateResult, type HandshakeChallenge, type HandshakeCompletion, type HandshakeResponse, type HandshakeResult, InMemoryModelProvenanceStore, InjectionDetector, type InjectionDetectorConfig, type InjectionSignal, MODEL_PRESETS, MemoryStorage, type ModelProvenance, type ModelProvenanceStore, type PedersenCommitment, type PeerTrustEvaluation, type PolicyRecommendation, PolicyStore, type PrincipalPolicy, type ProviderCategory, ProxyRouter, type ProxyRouterOptions, ReputationStore, type SHRBody, type SHRGeneratorOptions, type SHRVerificationResult, type SanctuaryConfig, type SanctuaryServer, type SignedAttestation, type SignedSHR, type SovereigntyProfile, SovereigntyProfileStore, type SovereigntyProfileUpdate, type SovereigntyTier, StateStore, StderrApprovalChannel, TIER_WEIGHTS, type TierMetadata, type TieredAttestation, type UpstreamConnection, type UpstreamServer, type UpstreamTool, WebhookApprovalChannel, type WebhookCallbackPayload, type WebhookConfig, type WebhookPayload, type ZKProofOfKnowledge, type ZKRangeProof, canonicalize, classifyField, completeHandshake, computeWeightedScore, createBridgeCommitment, createDefaultProfile, createPedersenCommitment, createProofOfKnowledge, createRangeProof, createSanctuaryServer, evaluateField, filterContext, generateAttestation, generateSHR, generateSystemPrompt, getTemplate, initiateHandshake, listTemplateIds, loadConfig, loadPrincipalPolicy, recommendPolicy, resolveTier, respondToHandshake, signPayload, tierDistribution, verifyAttestation, verifyBridgeCommitment, verifyCompletion, verifyPedersenCommitment, verifyProofOfKnowledge, verifyRangeProof, verifySHR, verifySignature };
+export { ATTESTATION_VERSION, type ActivityEntry, type AggregatorSources, ApprovalGate, type ApprovalHandlers, type AttestationBody, type AttestationVerificationResult, AuditLog, AutoApproveChannel, BaselineTracker, type BridgeAttestationRequest, type BridgeAttestationResult, type BridgeCommitment, type BridgeVerificationResult, TEMPLATES as CONTEXT_GATE_TEMPLATES, CallbackApprovalChannel, ClientManager, CommitmentStore, type ConcordiaOutcome, type ConnectionState, type ContextAction, type ContextFilterResult, ContextGateEnforcer, type ContextGatePolicy, ContextGatePolicyStore, type ContextGateRule, type ContextGateTemplate, DashboardApprovalChannel, type DashboardConfig, type DashboardHandle, type DashboardServerOptions, type DetectionResult, type EnforcerConfig, type FederationCapabilities, type FederationPeer, FederationRegistry, type FieldClassification, type FieldFilterResult, FilesystemStorage, type GateResult, HERO_COPY, type HandshakeChallenge, type HandshakeCompletion, type HandshakeResponse, type HandshakeResult, InMemoryModelProvenanceStore, InjectionDetector, type InjectionDetectorConfig, type InjectionSignal, type L1Status, type L2Status, type L3Status, type L4Status, MODEL_PRESETS, MemoryStorage, type ModelProvenance, type ModelProvenanceStore, type PedersenCommitment, type PeerTrustEvaluation, type PendingApproval, type PolicyRecommendation, PolicyStore, type PrincipalPolicy, type ProtectionSnapshot, type ProviderCategory, ProxyRouter, type ProxyRouterOptions, type ReputationLookup, ReputationStore, type SHRBody, type SHRGeneratorOptions, type SHRVerificationResult, type SanctuaryConfig, type SanctuaryServer, type SignedAttestation, type SignedSHR, type SovereigntyProfile, SovereigntyProfileStore, type SovereigntyProfileUpdate, type SovereigntyTier, type StartDashboardOptions, StateStore, StderrApprovalChannel, type StreamEvent, TIER_WEIGHTS, type TierMetadata, type TieredAttestation, type UpstreamConnection, type UpstreamServer, type UpstreamTool, WebhookApprovalChannel, type WebhookCallbackPayload, type WebhookConfig, type WebhookPayload, type ZKProofOfKnowledge, type ZKRangeProof, canonicalize, classifyField, completeHandshake, computeWeightedScore, createBridgeCommitment, createDefaultProfile, createPedersenCommitment, createProofOfKnowledge, createRangeProof, createSanctuaryServer, evaluateField, filterContext, generateAttestation, generateSHR, generateSystemPrompt, getProtectionSnapshot, getTemplate, initiateHandshake, listTemplateIds, loadConfig, loadPrincipalPolicy, recommendPolicy, renderDashboardHTML, resolveTier, respondToHandshake, signPayload, startDashboard, startDashboardServer, tierDistribution, verifyAttestation, verifyBridgeCommitment, verifyCompletion, verifyPedersenCommitment, verifyProofOfKnowledge, verifyRangeProof, verifySHR, verifySignature };