@kya-os/mcp-i-core 1.8.0 → 1.8.2

package/dist/runtime/base.d.ts

@@ -1,375 +0,0 @@
-/**
- * MCPIRuntimeBase - Provider-based runtime
- *
- * Core runtime that accepts providers for all platform-specific operations.
- * This enables the same runtime logic to work across Node.js, Cloudflare Workers,
- * and other platforms.
- */
-import { CryptoProvider, ClockProvider, FetchProvider, StorageProvider, NonceCacheProvider, IdentityProvider, AgentIdentity } from "../providers/base";
-import { type Ed25519JWK } from "../services/crypto.service.js";
-import { ProofVerifier } from "../services/proof-verifier.js";
-import type { DetachedProof } from "@kya-os/contracts/proof";
-import type { HandshakeRequest } from "@kya-os/contracts/handshake";
-import type { MCPIdentity, WellKnownConfig, WellKnownResponse } from "@kya-os/contracts/well-known";
-import type { AccessControlApiService } from "../services/access-control.service.js";
-import type { ProviderRuntimeConfig } from "../config";
-import { type OAuthIdentity } from "../identity/user-did-manager";
-import type { IAuditLogger } from "./audit-logger.js";
-/**
- * Interface for runtime instances that have AccessControlApiService available
- * This allows type-safe access to the access control service without using `as any`
- *
- * @deprecated AccessControlApiService is now directly available as protected property on MCPIRuntimeBase
- */
-export interface RuntimeWithAccessControl {
-    accessControlService?: AccessControlApiService;
-}
-type RuntimeRecord = Record<string, unknown>;
-type RuntimeHandshakeRequest = Partial<HandshakeRequest> & RuntimeRecord & {
-    audience?: string;
-    agentDid?: string;
-    clientInfo?: RuntimeRecord;
-    clientProtocolVersion?: unknown;
-    clientCapabilities?: unknown;
-    clientDid?: string;
-    oauthIdentity?: OAuthIdentity | null;
-};
-interface RuntimeHandshakeResponse {
-    sessionId: string;
-    agentDid: string;
-    timestamp: number;
-    capabilities: string[];
-    userDid?: string;
-    signature: string;
-}
-interface RuntimeSessionContext {
-    id?: string;
-    audience?: string;
-    createdAt?: number;
-    expiresAt?: number;
-    clientDid?: string;
-    userDid?: string;
-    agentDid?: string;
-    serverDid?: string;
-    nonce?: string;
-    delegationToken?: string;
-    consentProof?: string;
-    projectId?: string;
-    serverOrigin?: string;
-    userAgent?: string;
-    clientId?: string;
-    agentName?: string;
-    clientInfo?: Record<string, unknown>;
-    identityState?: "anonymous" | "authenticated";
-    oauthIdentity?: OAuthIdentity;
-    canonicalPayload?: string;
-    [key: string]: unknown;
-}
-interface StoredRuntimeSession extends RuntimeSessionContext {
-    id: string;
-    createdAt: number;
-    expiresAt: number;
-}
-interface LegacyProof {
-    timestamp: number;
-    nonce: string;
-    did: string;
-    signature: string;
-    algorithm: "Ed25519";
-    sessionId?: string;
-    audience?: string;
-}
-type RuntimeProof = LegacyProof | DetachedProof;
-type RuntimeAuditLogger = IAuditLogger | {
-    log: (event: string, data: unknown) => void;
-};
-export declare class MCPIRuntimeBase {
-    protected crypto: CryptoProvider;
-    protected clock: ClockProvider;
-    protected fetch: FetchProvider;
-    protected storage: StorageProvider;
-    protected nonceCache: NonceCacheProvider;
-    protected identity: IdentityProvider;
-    protected config: ProviderRuntimeConfig;
-    private cachedIdentity?;
-    private sessions;
-    private lastProof?;
-    private userDidManager?;
-    private interceptedCalls;
-    private cryptoService?;
-    protected proofVerifier?: ProofVerifier;
-    protected accessControlService?: AccessControlApiService;
-    /**
-     * Cached flag indicating whether @modelcontextprotocol/ext-apps is available.
-     * Set by subclasses after a successful dynamic import (avoids require() vs ESM issues).
-     * When undefined, falls back to synchronous require() probe.
-     */
-    private _extAppsAvailable?;
-    constructor(config: ProviderRuntimeConfig);
-    /**
-     * Initialize the runtime
-     */
-    initialize(): Promise<void>;
-    /**
-     * Get the current agent identity
-     */
-    getIdentity(): Promise<AgentIdentity>;
-    /**
-     * Handle MCP handshake request
-     *
-     * Phase 5: Anonymous Sessions Until OAuth
-     * - Sessions start anonymous (no userDid) unless OAuth identity provided
-     * - User DID is resolved via AgentShield after OAuth completes
-     * - Eliminates DID fragmentation (same user = same DID across sessions)
-     *
-     * @param request - Handshake request object (may include oauthIdentity for persistent user DID lookup)
-     * @returns Handshake response with session ID and agent DID
-     */
-    handleHandshake(request: RuntimeHandshakeRequest): Promise<RuntimeHandshakeResponse>;
-    /**
-     * Update session identity after OAuth resolution (Phase 5)
-     *
-     * Called after AgentShield identity/resolve returns a persistent user DID.
-     * Updates the session to authenticated state with the resolved DID.
-     *
-     * @param sessionId - MCP session ID
-     * @param userDid - Persistent user DID from AgentShield
-     * @param oauthIdentity - OAuth identity information
-     * @throws Error if session not found
-     */
-    updateSessionIdentity(sessionId: string, userDid: string, oauthIdentity?: {
-        provider: string;
-        subject: string;
-        email?: string;
-    }): Promise<void>;
-    /**
-     * Get session by ID
-     */
-    getSession(sessionId: string): StoredRuntimeSession | undefined;
-    /**
-     * Extract the correct provider for consent URL from tool protection config
-     *
-     * For password auth tools, the provider is in authorization.provider.
-     * For OAuth auth tools, the provider is in oauthProvider (legacy) or authorization.provider.
-     *
-     * Note: Not all authorization types have a provider field (e.g., 'none', 'mdl', 'webauthn').
-     * Only 'oauth', 'oauth2', 'password', and 'idv' types have provider.
-     *
-     * @param protection - Tool protection configuration
-     * @returns Provider name to use in consent URL, or undefined
-     */
-    private getConsentProvider;
-    /**
-     * Process tool call with automatic proof generation
-     * Returns clean result only - proof is stored for out-of-band retrieval
-     *
-     * @param toolName - Name of the tool being called
-     * @param args - Tool arguments
-     * @param handler - Tool execution handler
-     * @param session - Session context (expected fields: id, audience, nonce?, delegationToken?, consentProof?)
-     */
-    processToolCall<TArgs = unknown, TResult = unknown>(toolName: string, args: TArgs, handler: (args: TArgs) => Promise<TResult>, session?: RuntimeSessionContext): Promise<TResult | RuntimeRecord>;
-    /**
-     * Resume a tool call after authorization
-     *
-     * @param resumeToken - Token from DelegationRequiredError
-     * @param handler - Tool execution handler
-     * @param delegationToken - Delegation token from authorization
-     * @returns Tool execution result
-     */
-    resumeToolCall(resumeToken: string, handler: (args: unknown) => Promise<unknown>, delegationToken?: string): Promise<unknown>;
-    /**
-     * Generate a resume token for intercepted tool call
-     *
-     * Uses cryptographically secure random bytes for token generation.
-     * The token is used as an opaque lookup key in the interceptedCalls Map.
-     */
-    private generateResumeToken;
-    /**
-     * Clean up expired intercepted calls
-     */
-    private cleanupExpiredInterceptedCalls;
-    /**
-     * Build consent URL for AgentShield delegation flow
-     *
-     * Note: Parameter names use snake_case for AgentShield API compatibility.
-     * This is documented in docs/API_PARITY_GUIDE.md under "Field Naming Conventions".
-     *
-     * AgentShield API requires snake_case in URL parameters:
-     * - session_id (not sessionId)
-     * - agent_did (not agentDid)
-     * - resume_token (not resumeToken)
-     * - agent_name (human-readable agent name for dashboard display)
-     *
-     * @param toolName - Tool that requires delegation
-     * @param scopes - Required scopes for the tool
-     * @param session - Current session context
-     * @param resumeToken - Token to resume after delegation
-     * @param projectId - Project ID for AgentShield API
-     * @param provider - Provider name (e.g., "github", "credentials") to select specific auth method
-     * @returns Full consent URL with snake_case parameters
-     */
-    /**
-     * MCP Apps UI consent resource URI.
-     * Single shared resource for all consent flows - tool-specific data
-     * is passed via structuredContent in the tool result.
-     */
-    protected static readonly CONSENT_UI_RESOURCE_URI = "ui://mcpi-consent/authorize";
-    /**
-     * Check if the connected MCP client supports MCP Apps UI rendering.
-     * Returns false if @modelcontextprotocol/ext-apps is not installed
-     * or the client didn't advertise the io.modelcontextprotocol/ui capability.
-     *
-     * Override in subclasses to provide client capabilities from the MCP session.
-     */
-    protected hasUICapability(clientCapabilities?: Record<string, unknown>): boolean;
-    /**
-     * Mark the ext-apps SDK as available.
-     * Called by subclasses after a successful dynamic import() of the SDK,
-     * which avoids the CJS require() vs ESM incompatibility that causes
-     * the synchronous probe to fail in Cloudflare Workers.
-     */
-    setExtAppsAvailable(available: boolean): void;
-    /**
-     * Check if the MCP Apps inline consent UI is enabled.
-     * Requires BOTH conditions:
-     *   1. The SDK is available (set via setExtAppsAvailable(true) after dynamic import)
-     *   2. The config flag is enabled (config.inlineConsent === true OR MCPI_INLINE_CONSENT env var)
-     * This allows merging the feature while keeping it off by default.
-     */
-    protected isExtAppsAvailable(): boolean;
-    /**
-     * Build an MCP Apps-compatible tool result that renders an inline consent UI.
-     * Returns null when the host doesn't support MCP Apps or the SDK is unavailable,
-     * allowing callers to fall back to DelegationRequiredError.
-     *
-     * @param toolName - Tool requiring delegation
-     * @param scopes - Required scopes
-     * @param session - Current session context
-     * @param resumeToken - Token to resume after delegation
-     * @param projectId - AgentShield project ID
-     * @param serverUrl - Server URL for consent approval POST
-     * @param clientCapabilities - MCP client capabilities from the session
-     */
-    buildConsentUIResult(toolName: string, scopes: string[], session?: Record<string, unknown>, resumeToken?: string, projectId?: string, serverUrl?: string, clientCapabilities?: Record<string, unknown>, authMode?: "consent-only" | "credentials", provider?: string): Record<string, unknown> | null;
-    protected buildConsentUrl(toolName: string, scopes: string[], session?: RuntimeSessionContext, resumeToken?: string, projectId?: string, provider?: string): string;
-    /**
-     * Issue a new nonce and register it in the cache
-     * Use this to get a nonce for the session context before calling processToolCall
-     */
-    issueNonce(sessionId: string): Promise<string>;
-    /**
-     * Create cryptographic proof for data
-     */
-    createProof(data: unknown, session?: RuntimeSessionContext): Promise<RuntimeProof>;
-    /**
-     * Verify a proof
-     *
-     * Supports both old format (data, proof) and new DetachedProof format.
-     * When DetachedProof format is used, ProofVerifier is used if available.
-     *
-     * @param dataOrProof - Either raw data (old format) or DetachedProof (new format)
-     * @param proofOrSession - Either proof object (old format) or session context (new format)
-     * @returns true if proof is valid, false otherwise
-     */
-    verifyProof(dataOrProof: unknown, proofOrSession?: unknown): Promise<boolean>;
-    /**
-     * Legacy proof verification (backward compatibility)
-     * @internal
-     */
-    private verifyProofLegacy;
-    /**
-     * Verify a JWS proof (full compact JWS format: header.payload.signature)
-     *
-     * This method provides full cryptographic signature verification using CryptoService.
-     * Use this when you have a DetachedProof with JWS instead of raw signature.
-     *
-     * @param jws - Full compact JWS string (header.payload.signature)
-     * @param publicKeyJwk - Ed25519 public key in JWK format
-     * @param detachedPayload - Optional detached payload for detached JWS format
-     * @returns true if signature is valid, false otherwise
-     */
-    verifyProofJWS(jws: string, publicKeyJwk: Ed25519JWK, detachedPayload?: string | Uint8Array): Promise<boolean>;
-    /**
-     * Get current session
-     */
-    getCurrentSession(): Promise<StoredRuntimeSession | null>;
-    /**
-     * Get the last generated proof for out-of-band transport
-     */
-    getLastProof(): RuntimeProof | undefined;
-    /**
-     * Create well-known handler for identity verification
-     */
-    createWellKnownHandler(config?: WellKnownConfig): (path: string) => Promise<WellKnownResponse | MCPIdentity | null>;
-    /**
-     * Create debug endpoint (development only)
-     */
-    createDebugEndpoint(): (() => Promise<RuntimeRecord>) | null;
-    /**
-     * Get audit logger
-     */
-    getAuditLogger(): RuntimeAuditLogger | undefined;
-    /**
-     * Rotate keys
-     */
-    rotateKeys(): Promise<AgentIdentity>;
-    private signData;
-    private generateNonce;
-    /**
-     * Generate a unique session ID
-     * Uses mcpi_{uuid} format for MCP protocol compliance and traceability
-     */
-    private generateSessionId;
-    /**
-     * Log structured events in JSON format (NOT frozen audit format).
-     *
-     * **Important:** This method logs events in JSON format for general runtime events
-     * (e.g., "runtime_initialized", "tool_executed", "keys_rotated").
-     *
-     * **For frozen format audit logs** (MCP-I spec compliance), use `AuditLogger.logAuditRecord()`
-     * from `@kya-os/mcp-i/runtime` instead. The frozen format is:
-     * ```
-     * audit.v1 ts=<unix> session=<id> audience=<host> did=<did> kid=<kid> reqHash=<sha256:..> resHash=<sha256:..> verified=yes|no scope=<scopeId|->
-     * ```
-     *
-     * **Format:** JSON object with `event`, `data`, `timestamp`, and `timestampFormatted` fields.
-     *
-     * **Privacy:** If `includePayloads` is false (default), the `data` field is omitted.
-     *
-     * **Use Cases:**
-     * - Developer debugging and local logging
-     * - Runtime initialization events
-     * - Tool execution tracking (non-spec-compliant)
-     * - Key rotation events
-     *
-     * **NOT for:**
-     * - MCP-I spec-compliant audit logs (use `AuditLogger`)
-     * - Production audit trails (use `AuditLogger`)
-     * - Compliance requirements (use `AuditLogger`)
-     *
-     * @param event - Event name (e.g., "runtime_initialized", "tool_executed")
-     * @param data - Event data (only included if `includePayloads` is true)
-     *
-     * @example
-     * ```typescript
-     * // Logs: {"event":"runtime_initialized","timestamp":1234567890,"timestampFormatted":"2024-01-01T00:00:00Z"}
-     * this.logAudit("runtime_initialized", { did: "did:key:..." });
-     * ```
-     *
-     * @internal This is a private method for internal runtime events.
-     * Use AuditLogger for spec-compliant frozen format audit logs.
-     */
-    private logAudit;
-    private createDIDDocument;
-    private extractPublicKey;
-    /**
-     * Extract public key JWK from DID document
-     */
-    private extractPublicKeyJwk;
-    private bytesToBase64;
-    private base64ToBytes;
-    private bytesToHex;
-}
-export {};
-//# sourceMappingURL=base.d.ts.map