@kya-os/mcp-i-core 1.4.19 → 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 MCP-I Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -282,6 +282,20 @@ async function verifyMCPIProof(data: any, proof: any): Promise<boolean> {
 4. **Session Lifecycle**: Absolute lifetime limits
 5. **Audit Logging**: Built-in audit trail support
 
+### Progressive Verification
+
+**Signature verification requires a DID resolver and signature verifier.** If neither is configured, signature checks are skipped and the credential is treated as structurally valid. This is intentional for environments where DID resolution is not available (e.g., offline operation, testing, or edge deployments without network access).
+
+In production deployments, always configure a DID resolver to enable full cryptographic verification:
+
+```typescript
+const verifier = new DelegationCredentialVerifier({
+  resolveDID: async (did) => fetchDIDDocument(did),
+  verifySignature: async (vc, publicKey) => verifyEd25519(vc, publicKey),
+  resolveStatusList: async (url) => fetchStatusList(url),
+});
+```
+
 ## Testing
 
 The provider-based architecture makes testing straightforward:

package/dist/auth/handshake.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Authorization Handshake — Platform-agnostic Protocol Reference
+ *
+ * Orchestrates the authorization flow for MCP-I bouncer:
+ * 1. Check agent reputation (optional)
+ * 2. Verify delegation exists
+ * 3. Return needs_authorization error if missing
+ *
+ * This module uses only the global fetch API — no Node-specific imports.
+ * It is safe to run on Node.js, Cloudflare Workers, and any fetch-capable runtime.
+ *
+ * Flow:
+ * - If delegation exists + valid → allow (fast path)
+ * - If delegation missing → return needs_authorization with hints
+ * - If reputation too low (optional) → require authorization
+ */
+import { NeedsAuthorizationError } from "@kya-os/contracts/runtime";
+import { DelegationRecord } from "@kya-os/contracts/delegation";
+import { DelegationVerifier, VerifyDelegationResult } from "./types";
+export type { DelegationVerifier, VerifyDelegationResult };
+/**
+ * Agent reputation data from KTA
+ */
+export interface AgentReputation {
+    agentDid: string;
+    score: number;
+    totalInteractions: number;
+    successRate: number;
+    riskLevel: "low" | "medium" | "high" | "unknown";
+    updatedAt: number;
+}
+/**
+ * Configuration for auth handshake
+ */
+export interface AuthHandshakeConfig {
+    delegationVerifier: DelegationVerifier;
+    resumeTokenStore: ResumeTokenStore;
+    kta?: {
+        apiUrl: string;
+        apiKey?: string;
+        apiFormat?: "kta" | "argus";
+    };
+    bouncer: {
+        authorizationUrl: string;
+        resumeTokenTtl?: number;
+        requireAuthForUnknown?: boolean;
+        minReputationScore?: number;
+    };
+    debug?: boolean;
+}
+/**
+ * Result of auth handshake verification
+ */
+export interface VerifyOrHintsResult {
+    authorized: boolean;
+    delegation?: DelegationRecord;
+    credential?: {
+        agent_did: string;
+        user_did: string;
+        scopes: string[];
+        authorization: {
+            type: "oauth" | "oauth2" | "password" | "credential" | "webauthn" | "siwe" | "none";
+            provider?: string;
+            credentialType?: string;
+            rpId?: string;
+            userVerification?: "required" | "preferred" | "discouraged";
+            chainId?: number;
+            domain?: string;
+        };
+        [key: string]: unknown;
+    };
+    authError?: NeedsAuthorizationError;
+    reputation?: AgentReputation;
+    reason?: string;
+}
+/**
+ * Resume token store interface
+ */
+export interface ResumeTokenStore {
+    create(agentDid: string, scopes: string[], metadata?: Record<string, unknown>): Promise<string>;
+    get(token: string): Promise<{
+        agentDid: string;
+        scopes: string[];
+        createdAt: number;
+        expiresAt: number;
+        metadata?: Record<string, unknown>;
+    } | null>;
+    fulfill(token: string): Promise<void>;
+}
+/**
+ * Simple in-memory resume token store (for testing/development).
+ * Not suitable for multi-instance deployments.
+ */
+export declare class MemoryResumeTokenStore implements ResumeTokenStore {
+    private tokens;
+    private ttl;
+    constructor(ttlMs?: number);
+    create(agentDid: string, scopes: string[], metadata?: Record<string, unknown>): Promise<string>;
+    get(token: string): Promise<{
+        agentDid: string;
+        scopes: string[];
+        createdAt: number;
+        expiresAt: number;
+        metadata?: Record<string, unknown>;
+    } | null>;
+    fulfill(token: string): Promise<void>;
+    clear(): void;
+}
+/**
+ * Main auth handshake function.
+ *
+ * Verifies agent authorization or returns authorization hints.
+ */
+export declare function verifyOrHints(agentDid: string, scopes: string[], config: AuthHandshakeConfig, _resumeToken?: string): Promise<VerifyOrHintsResult>;
+/**
+ * Helper: Check if scopes are sensitive and require authorization.
+ */
+export declare function hasSensitiveScopes(scopes: string[]): boolean;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/auth/handshake.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * Authorization Handshake — Platform-agnostic Protocol Reference
+ *
+ * Orchestrates the authorization flow for MCP-I bouncer:
+ * 1. Check agent reputation (optional)
+ * 2. Verify delegation exists
+ * 3. Return needs_authorization error if missing
+ *
+ * This module uses only the global fetch API — no Node-specific imports.
+ * It is safe to run on Node.js, Cloudflare Workers, and any fetch-capable runtime.
+ *
+ * Flow:
+ * - If delegation exists + valid → allow (fast path)
+ * - If delegation missing → return needs_authorization with hints
+ * - If reputation too low (optional) → require authorization
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryResumeTokenStore = void 0;
+exports.verifyOrHints = verifyOrHints;
+exports.hasSensitiveScopes = hasSensitiveScopes;
+const runtime_1 = require("@kya-os/contracts/runtime");
+const logging_1 = require("../logging");
+/**
+ * Simple in-memory resume token store (for testing/development).
+ * Not suitable for multi-instance deployments.
+ */
+class MemoryResumeTokenStore {
+    tokens = new Map();
+    ttl;
+    constructor(ttlMs = 600_000) {
+        this.ttl = ttlMs;
+    }
+    async create(agentDid, scopes, metadata) {
+        const token = `rt_${Date.now()}_${Math.random().toString(36).substring(2, 18)}`;
+        const now = Date.now();
+        this.tokens.set(token, {
+            agentDid,
+            scopes,
+            createdAt: now,
+            expiresAt: now + this.ttl,
+            metadata,
+            fulfilled: false,
+        });
+        return token;
+    }
+    async get(token) {
+        const data = this.tokens.get(token);
+        if (!data)
+            return null;
+        if (Date.now() > data.expiresAt) {
+            this.tokens.delete(token);
+            return null;
+        }
+        if (data.fulfilled)
+            return null;
+        return {
+            agentDid: data.agentDid,
+            scopes: data.scopes,
+            createdAt: data.createdAt,
+            expiresAt: data.expiresAt,
+            metadata: data.metadata,
+        };
+    }
+    async fulfill(token) {
+        const data = this.tokens.get(token);
+        if (data) {
+            data.fulfilled = true;
+        }
+    }
+    clear() {
+        this.tokens.clear();
+    }
+}
+exports.MemoryResumeTokenStore = MemoryResumeTokenStore;
+/**
+ * Main auth handshake function.
+ *
+ * Verifies agent authorization or returns authorization hints.
+ */
+async function verifyOrHints(agentDid, scopes, config, _resumeToken) {
+    const startTime = Date.now();
+    if (config.debug) {
+        logging_1.logger.debug(`[AuthHandshake] Verifying ${agentDid} for scopes: ${scopes.join(", ")}`);
+    }
+    let reputation;
+    if (config.kta && config.bouncer.minReputationScore !== undefined) {
+        try {
+            reputation = await fetchAgentReputation(agentDid, config.kta);
+            if (config.debug) {
+                logging_1.logger.debug(`[AuthHandshake] Reputation score: ${reputation.score}`);
+            }
+            if (reputation.score < config.bouncer.minReputationScore) {
+                if (config.debug) {
+                    logging_1.logger.debug(`[AuthHandshake] Reputation ${reputation.score} < ${config.bouncer.minReputationScore}, requiring authorization`);
+                }
+                const authError = await buildNeedsAuthorizationError(agentDid, scopes, config, "Agent reputation score below threshold");
+                return {
+                    authorized: false,
+                    authError,
+                    reputation,
+                    reason: "Low reputation score",
+                };
+            }
+        }
+        catch (error) {
+            logging_1.logger.warn("[AuthHandshake] Failed to check reputation:", error);
+        }
+    }
+    let delegationResult;
+    try {
+        delegationResult = await config.delegationVerifier.verify(agentDid, scopes);
+    }
+    catch (error) {
+        logging_1.logger.error("[AuthHandshake] Delegation verification failed:", error);
+        const errorMessage = `Delegation verification error: ${error instanceof Error ? error.message : "Unknown error"}`;
+        const authError = await buildNeedsAuthorizationError(agentDid, scopes, config, errorMessage);
+        return {
+            authorized: false,
+            authError,
+            reason: errorMessage,
+        };
+    }
+    if (delegationResult.valid && delegationResult.delegation) {
+        if (config.debug) {
+            logging_1.logger.debug(`[AuthHandshake] Delegation valid, authorized (${Date.now() - startTime}ms)`);
+        }
+        return {
+            authorized: true,
+            delegation: delegationResult.delegation,
+            credential: delegationResult.credential,
+            reputation,
+            reason: "Valid delegation found",
+        };
+    }
+    if (config.debug) {
+        logging_1.logger.debug(`[AuthHandshake] No delegation found, returning needs_authorization (${Date.now() - startTime}ms)`);
+    }
+    const authError = await buildNeedsAuthorizationError(agentDid, scopes, config, delegationResult.reason ?? "No valid delegation found");
+    return {
+        authorized: false,
+        authError,
+        reputation,
+        reason: delegationResult.reason ?? "No delegation",
+    };
+}
+/**
+ * Fetch agent reputation from KTA.
+ */
+async function fetchAgentReputation(agentDid, ktaConfig) {
+    const apiUrl = ktaConfig.apiUrl.replace(/\/$/, "");
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (ktaConfig.apiKey) {
+        headers["X-API-Key"] = ktaConfig.apiKey;
+    }
+    const isArgusFormat = ktaConfig.apiFormat === "argus";
+    let response;
+    if (isArgusFormat) {
+        response = await fetch(`${apiUrl}/v1/reputation/${encodeURIComponent(agentDid)}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ include_details: false }),
+        });
+    }
+    else {
+        response = await fetch(`${apiUrl}/api/v1/reputation/${encodeURIComponent(agentDid)}`, {
+            method: "GET",
+            headers,
+        });
+    }
+    if (!response.ok) {
+        if (response.status === 404) {
+            return {
+                agentDid,
+                score: 50,
+                totalInteractions: 0,
+                successRate: 0,
+                riskLevel: "unknown",
+                updatedAt: Date.now(),
+            };
+        }
+        throw new Error(`KTA API error: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    const score = data.score ?? 50;
+    const levelRaw = (data.level ??
+        data.riskLevel ??
+        "unknown").toLowerCase();
+    const riskLevel = levelRaw === "low" || levelRaw === "medium" || levelRaw === "high"
+        ? levelRaw
+        : "unknown";
+    return {
+        agentDid: data.agent_did ??
+            data.agentDid ??
+            agentDid,
+        score,
+        totalInteractions: data.totalInteractions ?? 0,
+        successRate: data.successRate ?? 0,
+        riskLevel,
+        updatedAt: data.calculatedAt
+            ? new Date(data.calculatedAt).getTime()
+            : (data.updatedAt ?? Date.now()),
+    };
+}
+/**
+ * Build needs_authorization error with hints.
+ */
+async function buildNeedsAuthorizationError(agentDid, scopes, config, message) {
+    const resumeToken = await config.resumeTokenStore.create(agentDid, scopes, {
+        requestedAt: Date.now(),
+    });
+    const expiresAt = Date.now() + (config.bouncer.resumeTokenTtl ?? 600_000);
+    const authUrl = new URL(config.bouncer.authorizationUrl);
+    authUrl.searchParams.set("agent_did", agentDid);
+    authUrl.searchParams.set("scopes", scopes.join(","));
+    authUrl.searchParams.set("resume_token", resumeToken);
+    const authCode = resumeToken.substring(0, 8).toUpperCase();
+    const display = {
+        title: "Authorization Required",
+        hint: ["link", "qr"],
+        authorizationCode: authCode,
+        qrUrl: `https://chart.googleapis.com/chart?cht=qr&chs=300x300&chl=${encodeURIComponent(authUrl.toString())}`,
+    };
+    return (0, runtime_1.createNeedsAuthorizationError)({
+        message,
+        authorizationUrl: authUrl.toString(),
+        resumeToken,
+        expiresAt,
+        scopes,
+        display,
+    });
+}
+/**
+ * Helper: Check if scopes are sensitive and require authorization.
+ */
+function hasSensitiveScopes(scopes) {
+    const sensitivePatterns = [
+        "write",
+        "delete",
+        "admin",
+        "payment",
+        "transfer",
+        "execute",
+        "modify",
+    ];
+    return scopes.some((scope) => sensitivePatterns.some((pattern) => scope.toLowerCase().includes(pattern)));
+}
+//# sourceMappingURL=handshake.js.map

package/dist/auth/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Auth module — platform-agnostic authorization handshake reference implementation.
+ */
+export { verifyOrHints, hasSensitiveScopes, MemoryResumeTokenStore, type AuthHandshakeConfig, type VerifyOrHintsResult, type AgentReputation, type ResumeTokenStore, } from "./handshake";
+export type { DelegationVerifier, VerifyDelegationResult } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryResumeTokenStore = exports.hasSensitiveScopes = exports.verifyOrHints = void 0;
+/**
+ * Auth module — platform-agnostic authorization handshake reference implementation.
+ */
+var handshake_1 = require("./handshake");
+Object.defineProperty(exports, "verifyOrHints", { enumerable: true, get: function () { return handshake_1.verifyOrHints; } });
+Object.defineProperty(exports, "hasSensitiveScopes", { enumerable: true, get: function () { return handshake_1.hasSensitiveScopes; } });
+Object.defineProperty(exports, "MemoryResumeTokenStore", { enumerable: true, get: function () { return handshake_1.MemoryResumeTokenStore; } });
+//# sourceMappingURL=index.js.map

package/dist/auth/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Authorization types for mcp-i-core auth module.
+ *
+ * These are the minimal interfaces required by the auth handshake.
+ * Platform adapters (packages/mcp-i, packages/mcp-i-cloudflare) may extend
+ * these types with additional fields.
+ */
+import { DelegationRecord } from "@kya-os/contracts/delegation";
+/**
+ * Result of a delegation verification check.
+ * Structurally compatible with the full VerifyDelegationResult in packages/mcp-i.
+ */
+export interface VerifyDelegationResult {
+    /** Whether a valid delegation was found */
+    valid: boolean;
+    /** The delegation record (if found) */
+    delegation?: DelegationRecord;
+    /** Credential from AgentShield API (includes authorization method) */
+    credential?: {
+        agent_did: string;
+        user_did: string;
+        scopes: string[];
+        authorization: {
+            type: "oauth" | "oauth2" | "password" | "credential" | "webauthn" | "siwe" | "none";
+            provider?: string;
+            credentialType?: string;
+            rpId?: string;
+            userVerification?: "required" | "preferred" | "discouraged";
+            chainId?: number;
+            domain?: string;
+        };
+        [key: string]: unknown;
+    };
+    /** Reason for invalid result */
+    reason?: string;
+    /** Whether result came from cache */
+    cached?: boolean;
+}
+/**
+ * Minimal delegation verifier interface required by verifyOrHints().
+ * Concrete implementations live in packages/mcp-i (AgentShieldAPIDelegationVerifier, etc.).
+ */
+export interface DelegationVerifier {
+    verify(agentDid: string, scopes: string[]): Promise<VerifyDelegationResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Authorization types for mcp-i-core auth module.
+ *
+ * These are the minimal interfaces required by the auth handshake.
+ * Platform adapters (packages/mcp-i, packages/mcp-i-cloudflare) may extend
+ * these types with additional fields.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/delegation/index.d.ts

@@ -11,4 +11,5 @@ export * from './statuslist-manager';
 export * from './delegation-graph';
 export * from './cascading-revocation';
 export * from './utils';
+export * from './outbound-proof';
 //# sourceMappingURL=index.d.ts.map

package/dist/delegation/index.js

@@ -27,4 +27,5 @@ __exportStar(require("./statuslist-manager"), exports);
 __exportStar(require("./delegation-graph"), exports);
 __exportStar(require("./cascading-revocation"), exports);
 __exportStar(require("./utils"), exports);
+__exportStar(require("./outbound-proof"), exports);
 //# sourceMappingURL=index.js.map

package/dist/delegation/outbound-proof.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Outbound Delegation Proof
+ *
+ * Builds signed delegation proof JWTs for injection on outbound HTTP requests.
+ * Enables downstream services to independently verify the delegation chain
+ * without trusting the MCP server.
+ *
+ * Wire format: signed compact EdDSA JWT (60s TTL, per-call jti)
+ * Header injection: X-Delegation-Id, X-Delegation-Chain, X-Delegation-Proof, X-Scopes
+ *
+ * Related Spec: MCP-I §2 — Outbound Delegation Propagation
+ */
+import type { DelegationRecord } from "@kya-os/contracts/delegation";
+/**
+ * Ed25519 private key JWK (includes d for signing)
+ */
+export interface Ed25519PrivateJWK {
+    kty: "OKP";
+    crv: "Ed25519";
+    /** Base64url-encoded public key scalar */
+    x: string;
+    /** Base64url-encoded private key scalar */
+    d: string;
+    kid?: string;
+    use?: string;
+}
+/**
+ * Options for building a delegation proof JWT
+ */
+export interface DelegationProofOptions {
+    /** DID of the agent issuing the proof */
+    agentDid: string;
+    /** DID of the delegating user */
+    userDid: string;
+    /** Delegation VC credential ID */
+    delegationId: string;
+    /** Reference chain string (format: vc_id_1>del_id_1>...) */
+    delegationChain: string;
+    /** Scopes granted by the delegation */
+    scopes: string[];
+    /** Agent Ed25519 private key JWK (with d field) */
+    privateKeyJwk: Ed25519PrivateJWK;
+    /** Key ID for the JWT header (e.g. did:web:agent.example.com#key-1) */
+    kid: string;
+    /** Target service hostname (used as aud claim) */
+    targetHostname: string;
+}
+/**
+ * Build a signed delegation proof JWT.
+ *
+ * JWT is EdDSA-signed with the agent's Ed25519 key, 60s TTL, jti per call.
+ * Returns the compact JWT string.
+ *
+ * @throws when the private key cannot be imported or signing fails
+ */
+export declare function buildDelegationProofJWT(options: DelegationProofOptions): Promise<string>;
+/**
+ * Build a delegation reference chain string.
+ *
+ * For a single delegation: "vcId>delegationId"
+ * If vcId is absent: returns delegation.id
+ * If both are absent: returns empty string
+ *
+ * For multi-hop chains, callers concatenate per-hop results with ">".
+ *
+ * @example
+ *   buildChainString(del) // "vc_abc>del_123"
+ */
+export declare function buildChainString(delegation: DelegationRecord): string;
+//# sourceMappingURL=outbound-proof.d.ts.map

package/dist/delegation/outbound-proof.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Outbound Delegation Proof
+ *
+ * Builds signed delegation proof JWTs for injection on outbound HTTP requests.
+ * Enables downstream services to independently verify the delegation chain
+ * without trusting the MCP server.
+ *
+ * Wire format: signed compact EdDSA JWT (60s TTL, per-call jti)
+ * Header injection: X-Delegation-Id, X-Delegation-Chain, X-Delegation-Proof, X-Scopes
+ *
+ * Related Spec: MCP-I §2 — Outbound Delegation Propagation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDelegationProofJWT = buildDelegationProofJWT;
+exports.buildChainString = buildChainString;
+const jose_1 = require("jose");
+/**
+ * Build a signed delegation proof JWT.
+ *
+ * JWT is EdDSA-signed with the agent's Ed25519 key, 60s TTL, jti per call.
+ * Returns the compact JWT string.
+ *
+ * @throws when the private key cannot be imported or signing fails
+ */
+async function buildDelegationProofJWT(options) {
+    const { agentDid, userDid, delegationId, delegationChain, scopes, privateKeyJwk, kid, targetHostname, } = options;
+    const privateKey = await (0, jose_1.importJWK)(privateKeyJwk, "EdDSA");
+    const iat = Math.floor(Date.now() / 1000);
+    const exp = iat + 60;
+    const jwt = await new jose_1.SignJWT({
+        delegation_id: delegationId,
+        delegation_chain: delegationChain,
+        scope: scopes.join(","),
+    })
+        .setProtectedHeader({ alg: "EdDSA", kid })
+        .setIssuer(agentDid)
+        .setSubject(userDid)
+        .setJti(crypto.randomUUID())
+        .setAudience(targetHostname)
+        .setIssuedAt(iat)
+        .setExpirationTime(exp)
+        .sign(privateKey);
+    return jwt;
+}
+/**
+ * Build a delegation reference chain string.
+ *
+ * For a single delegation: "vcId>delegationId"
+ * If vcId is absent: returns delegation.id
+ * If both are absent: returns empty string
+ *
+ * For multi-hop chains, callers concatenate per-hop results with ">".
+ *
+ * @example
+ *   buildChainString(del) // "vc_abc>del_123"
+ */
+function buildChainString(delegation) {
+    if (!delegation.id && !delegation.vcId) {
+        return "";
+    }
+    if (!delegation.vcId) {
+        return delegation.id;
+    }
+    return `${delegation.vcId}>${delegation.id}`;
+}
+//# sourceMappingURL=outbound-proof.js.map

package/dist/identity/user-did-manager.js

@@ -222,9 +222,11 @@ class UserDidManager {
      */
     async generateUserDidWithKeyPair() {
         if (this.config.useDidWeb && this.config.didWebBaseUrl) {
-            // Generate did:web (requires web server setup)
-            // For now, fall back to did:key
-            // TODO: Implement did:web generation if needed
+            // did:web generation requires a web server to host the DID document.
+            // Currently falls back to did:key which is self-resolving.
+            // TODO(feature): Implement did:web generation when required for production use cases.
+            // This would involve generating the DID document and coordinating with
+            // the hosting infrastructure to serve it at the well-known URL.
             console.warn("[UserDidManager] did:web not yet implemented, using did:key");
         }
         // Generate Ed25519 keypair for user DID