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

package/dist/conformance/capability-verifier-adapter.d.ts

@@ -0,0 +1,66 @@
+/**
+ * CapabilityVerifier Adapter
+ *
+ * Adapts {@link verifyCapabilities} into the small, duck-typed verifier shape an
+ * entity-card consumer expects: given a list of capabilities and a verification
+ * context, return which capability names are `verified` (backed by a verified
+ * attestation) and which are `unverified` (self-declared or failed).
+ *
+ * The capability and verifier types are defined locally rather than imported
+ * from `@kya-os/mcp`: mcp-i-core pins `@kya-os/mcp@1.6.1`, which predates the
+ * entity-card export, so importing it would not resolve.
+ *
+ * Mapping:
+ *   - bare-string capability  → `unverified` (Level 1, self-declared)
+ *   - L2 object capability    → checked via {@link verifyCapabilities}; its
+ *     `valid` names become `verified`, its `invalid` names become `unverified`.
+ */
+import { type CapabilityVCSignatureVerifier } from './validate-level2.js';
+import type { DIDResolver } from '../delegation/vc-verifier.js';
+/**
+ * Duck-typed capability. A bare string is a Level 1 self-declared capability;
+ * an object with a `name` (and optional `attestations`) is a Level 2 attested
+ * capability.
+ */
+export type DuckTypedCapability = string | {
+    name: string;
+    attestations?: readonly unknown[];
+    [key: string]: unknown;
+};
+/** Context describing whose capabilities are being checked, and against whom. */
+export interface CapabilityVerificationContext {
+    /** The subject (agent) DID the capabilities are claimed for. */
+    subjectDid: string;
+    /** Issuer DIDs trusted to attest capabilities. */
+    trustedIssuers: readonly string[];
+}
+/** Partition of capability names by verification outcome. */
+export interface CapabilityVerificationResult {
+    /** Capability names backed by a verified attestation. */
+    verified: string[];
+    /** Capability names that are self-declared or failed verification. */
+    unverified: string[];
+}
+/** The duck-typed verifier returned by {@link createCapabilityVerifier}. */
+export type CapabilityVerifier = (capabilities: readonly DuckTypedCapability[], ctx: CapabilityVerificationContext) => Promise<CapabilityVerificationResult>;
+/** Options for {@link createCapabilityVerifier}. */
+export interface CreateCapabilityVerifierOptions {
+    /**
+     * Signature verifier for Level 2 attestations. Defaults to a VC-JWT verifier
+     * (see {@link createVcJwtSignatureVerifier}).
+     */
+    signatureVerifier?: CapabilityVCSignatureVerifier;
+    /**
+     * DID resolver for the default signature verifier. Ignored when a
+     * `signatureVerifier` is supplied.
+     */
+    didResolver?: DIDResolver;
+}
+/**
+ * Create a capability verifier.
+ *
+ * @param options - Optional signature-verifier / DID-resolver overrides.
+ * @returns A verifier mapping capabilities to `{ verified, unverified }`.
+ */
+export declare function createCapabilityVerifier(options?: CreateCapabilityVerifierOptions): CapabilityVerifier;
+//# sourceMappingURL=capability-verifier-adapter.d.ts.map

package/dist/conformance/capability-verifier-adapter.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * CapabilityVerifier Adapter
+ *
+ * Adapts {@link verifyCapabilities} into the small, duck-typed verifier shape an
+ * entity-card consumer expects: given a list of capabilities and a verification
+ * context, return which capability names are `verified` (backed by a verified
+ * attestation) and which are `unverified` (self-declared or failed).
+ *
+ * The capability and verifier types are defined locally rather than imported
+ * from `@kya-os/mcp`: mcp-i-core pins `@kya-os/mcp@1.6.1`, which predates the
+ * entity-card export, so importing it would not resolve.
+ *
+ * Mapping:
+ *   - bare-string capability  → `unverified` (Level 1, self-declared)
+ *   - L2 object capability    → checked via {@link verifyCapabilities}; its
+ *     `valid` names become `verified`, its `invalid` names become `unverified`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCapabilityVerifier = createCapabilityVerifier;
+const validate_level2_js_1 = require("./validate-level2.js");
+const vc_jwt_verifier_js_1 = require("./vc-jwt-verifier.js");
+/**
+ * Create a capability verifier.
+ *
+ * @param options - Optional signature-verifier / DID-resolver overrides.
+ * @returns A verifier mapping capabilities to `{ verified, unverified }`.
+ */
+function createCapabilityVerifier(options = {}) {
+    const signatureVerifier = options.signatureVerifier ??
+        (0, vc_jwt_verifier_js_1.createVcJwtSignatureVerifier)({ didResolver: options.didResolver });
+    return async (capabilities, ctx) => {
+        const list = Array.isArray(capabilities) ? capabilities : [];
+        const bareStrings = [];
+        const attested = [];
+        for (const capability of list) {
+            if (typeof capability === 'string') {
+                bareStrings.push(capability);
+            }
+            else {
+                attested.push(capability);
+            }
+        }
+        const result = await (0, validate_level2_js_1.verifyCapabilities)(attested, {
+            agentDid: ctx.subjectDid,
+            trustedIssuers: [...ctx.trustedIssuers],
+            signatureVerifier,
+        });
+        const verified = result.valid;
+        const verifiedSet = new Set(verified);
+        // A capability verified via its L2 attestation must not also appear as
+        // unverified — e.g. when the input mixes a bare-string and an attested
+        // object for the same name. Exclude already-verified names, and dedupe.
+        const unverified = Array.from(new Set([
+            ...bareStrings,
+            ...result.invalid.map((entry) => entry.capability),
+        ])).filter((name) => !verifiedSet.has(name));
+        return { verified, unverified };
+    };
+}
+//# sourceMappingURL=capability-verifier-adapter.js.map

package/dist/conformance/index.d.ts

@@ -4,5 +4,7 @@
  * See docs/conformance-levels for the spec page (introduced in
  * modelcontextprotocol-identity#46).
  */
-export { validateLevel2, DEFAULT_TRUSTED_ISSUERS, type CapabilityName, type CapabilityAttestation, type CapabilityAttestationCredential, type Level2Capability, type ManifestCapabilities, type CapabilityVCSignatureVerifier, type CapabilityStatusListResolver, type ValidateLevel2Options, type ValidateLevel2Result, type InvalidCapability, } from './validate-level2.js';
+export { verifyCapabilities, validateLevel2, DEFAULT_TRUSTED_ISSUERS, type CapabilityName, type CapabilityAttestation, type CapabilityAttestationCredential, type Level2Capability, type ManifestCapabilities, type CapabilityVCSignatureVerifier, type CapabilityStatusListResolver, type ValidateLevel2Options, type ValidateLevel2Result, type InvalidCapability, } from './validate-level2.js';
+export { createVcJwtSignatureVerifier, createCombinedDidResolver, type VcJwtVerifierOptions, } from './vc-jwt-verifier.js';
+export { createCapabilityVerifier, type DuckTypedCapability, type CapabilityVerificationContext, type CapabilityVerificationResult, type CapabilityVerifier, type CreateCapabilityVerifierOptions, } from './capability-verifier-adapter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/conformance/index.js

@@ -6,8 +6,14 @@
  * modelcontextprotocol-identity#46).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_TRUSTED_ISSUERS = exports.validateLevel2 = void 0;
+exports.createCapabilityVerifier = exports.createCombinedDidResolver = exports.createVcJwtSignatureVerifier = exports.DEFAULT_TRUSTED_ISSUERS = exports.validateLevel2 = exports.verifyCapabilities = void 0;
 var validate_level2_js_1 = require("./validate-level2.js");
+Object.defineProperty(exports, "verifyCapabilities", { enumerable: true, get: function () { return validate_level2_js_1.verifyCapabilities; } });
 Object.defineProperty(exports, "validateLevel2", { enumerable: true, get: function () { return validate_level2_js_1.validateLevel2; } });
 Object.defineProperty(exports, "DEFAULT_TRUSTED_ISSUERS", { enumerable: true, get: function () { return validate_level2_js_1.DEFAULT_TRUSTED_ISSUERS; } });
+var vc_jwt_verifier_js_1 = require("./vc-jwt-verifier.js");
+Object.defineProperty(exports, "createVcJwtSignatureVerifier", { enumerable: true, get: function () { return vc_jwt_verifier_js_1.createVcJwtSignatureVerifier; } });
+Object.defineProperty(exports, "createCombinedDidResolver", { enumerable: true, get: function () { return vc_jwt_verifier_js_1.createCombinedDidResolver; } });
+var capability_verifier_adapter_js_1 = require("./capability-verifier-adapter.js");
+Object.defineProperty(exports, "createCapabilityVerifier", { enumerable: true, get: function () { return capability_verifier_adapter_js_1.createCapabilityVerifier; } });
 //# sourceMappingURL=index.js.map

package/dist/conformance/validate-level2.d.ts

@@ -174,11 +174,15 @@ export interface ValidateLevel2Result {
     warnings: string[];
 }
 /**
- * Validate an MCP-I agent's declared capabilities at Level 2.
+ * Verify an MCP-I agent's declared capability attestations (Level 2).
+ *
+ * Named for the action it performs — verifying capability ATTESTATIONS — rather
+ * than the conformance level. {@link validateLevel2} remains exported as a
+ * non-breaking `@deprecated` alias.
  *
  * @example
  * ```ts
- * const result = await validateLevel2(manifest.capabilities, {
+ * const result = await verifyCapabilities(manifest.capabilities, {
  *   agentDid: 'did:web:securebank.example',
  *   trustedIssuers: ['did:web:knowthat.ai'],
  *   signatureVerifier: myEd25519Verifier,
@@ -189,5 +193,11 @@ export interface ValidateLevel2Result {
  * console.log(result.warnings); // []
  * ```
  */
-export declare function validateLevel2(capabilities: unknown, options: ValidateLevel2Options): Promise<ValidateLevel2Result>;
+export declare function verifyCapabilities(capabilities: unknown, options: ValidateLevel2Options): Promise<ValidateLevel2Result>;
+/**
+ * @deprecated Renamed to {@link verifyCapabilities}. Retained as a non-breaking
+ * alias — the two are referentially identical. Prefer `verifyCapabilities` in
+ * new code; this alias will be removed in a future major.
+ */
+export declare const validateLevel2: typeof verifyCapabilities;
 //# sourceMappingURL=validate-level2.d.ts.map

package/dist/conformance/validate-level2.js

@@ -24,8 +24,8 @@
  * the missing attestation context.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_TRUSTED_ISSUERS = void 0;
-exports.validateLevel2 = validateLevel2;
+exports.validateLevel2 = exports.DEFAULT_TRUSTED_ISSUERS = void 0;
+exports.verifyCapabilities = verifyCapabilities;
 const utils_js_1 = require("../delegation/utils.js");
 /**
  * Default trusted issuer registry.
@@ -37,11 +37,15 @@ exports.DEFAULT_TRUSTED_ISSUERS = [
     'did:web:knowthat.ai',
 ];
 /**
- * Validate an MCP-I agent's declared capabilities at Level 2.
+ * Verify an MCP-I agent's declared capability attestations (Level 2).
+ *
+ * Named for the action it performs — verifying capability ATTESTATIONS — rather
+ * than the conformance level. {@link validateLevel2} remains exported as a
+ * non-breaking `@deprecated` alias.
  *
  * @example
  * ```ts
- * const result = await validateLevel2(manifest.capabilities, {
+ * const result = await verifyCapabilities(manifest.capabilities, {
  *   agentDid: 'did:web:securebank.example',
  *   trustedIssuers: ['did:web:knowthat.ai'],
  *   signatureVerifier: myEd25519Verifier,
@@ -52,7 +56,7 @@ exports.DEFAULT_TRUSTED_ISSUERS = [
  * console.log(result.warnings); // []
  * ```
  */
-async function validateLevel2(capabilities, options) {
+async function verifyCapabilities(capabilities, options) {
     const result = {
         valid: [],
         invalid: [],
@@ -118,6 +122,12 @@ async function validateLevel2(capabilities, options) {
     }
     return result;
 }
+/**
+ * @deprecated Renamed to {@link verifyCapabilities}. Retained as a non-breaking
+ * alias — the two are referentially identical. Prefer `verifyCapabilities` in
+ * new code; this alias will be removed in a future major.
+ */
+exports.validateLevel2 = verifyCapabilities;
 async function validateCapability(capability, ctx) {
     const reasons = [];
     if (!Array.isArray(capability.attestations) || capability.attestations.length === 0) {

package/dist/conformance/vc-jwt-verifier.d.ts

@@ -0,0 +1,55 @@
+/**
+ * VC-JWT Signature Verifier
+ *
+ * A {@link CapabilityVCSignatureVerifier} (the pluggable signature hook accepted
+ * by {@link verifyCapabilities}) that cryptographically verifies a capability
+ * attestation presented as a compact VC-JWT (JWS).
+ *
+ * Flow:
+ *   1. If no compact JWS was supplied (object-form VC) → reject. There is
+ *      nothing to verify cryptographically.
+ *   2. Resolve the credential's `issuer` DID via a combined, pluggable resolver
+ *      (did:key built in, plus the did:web resolver).
+ *   3. Select the verification method whose id matches the JWS header `kid`.
+ *   4. Import its `publicKeyJwk` as an EdDSA key and verify the compact JWS.
+ *
+ * The verifier never throws — every failure path returns
+ * `{ valid: false, reason }` so it composes cleanly inside the validator's
+ * per-attestation loop.
+ *
+ * @see ./validate-level2.ts — the validator this plugs into.
+ */
+import { type DidWebFetch } from '../delegation/did-web-resolver.js';
+import type { DIDResolver } from '../delegation/vc-verifier.js';
+import type { CapabilityVCSignatureVerifier } from './validate-level2.js';
+/** Options for {@link createVcJwtSignatureVerifier}. */
+export interface VcJwtVerifierOptions {
+    /**
+     * DID resolver used to fetch the issuer's verification keys. Defaults to a
+     * combined did:key + did:web resolver (see {@link createCombinedDidResolver}).
+     */
+    didResolver?: DIDResolver;
+    /**
+     * Pluggable fetch passed to the default did:web resolver. Ignored when a
+     * `didResolver` is supplied. Defaults to the global `fetch`.
+     */
+    fetch?: DidWebFetch;
+}
+/**
+ * Create a DID resolver that dispatches by method: did:key is resolved locally,
+ * did:web is fetched over HTTPS, and every other method resolves to `null`.
+ *
+ * @param options - Optional pluggable fetch for the did:web branch.
+ */
+export declare function createCombinedDidResolver(options?: {
+    fetch?: DidWebFetch;
+}): DIDResolver;
+/**
+ * Create a VC-JWT signature verifier suitable for
+ * {@link verifyCapabilities}'s `signatureVerifier` option.
+ *
+ * @param options - DID resolver / fetch overrides.
+ * @returns A `(vc, rawJwt) => Promise<{ valid; reason? }>` function.
+ */
+export declare function createVcJwtSignatureVerifier(options?: VcJwtVerifierOptions): CapabilityVCSignatureVerifier;
+//# sourceMappingURL=vc-jwt-verifier.d.ts.map

package/dist/conformance/vc-jwt-verifier.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * VC-JWT Signature Verifier
+ *
+ * A {@link CapabilityVCSignatureVerifier} (the pluggable signature hook accepted
+ * by {@link verifyCapabilities}) that cryptographically verifies a capability
+ * attestation presented as a compact VC-JWT (JWS).
+ *
+ * Flow:
+ *   1. If no compact JWS was supplied (object-form VC) → reject. There is
+ *      nothing to verify cryptographically.
+ *   2. Resolve the credential's `issuer` DID via a combined, pluggable resolver
+ *      (did:key built in, plus the did:web resolver).
+ *   3. Select the verification method whose id matches the JWS header `kid`.
+ *   4. Import its `publicKeyJwk` as an EdDSA key and verify the compact JWS.
+ *
+ * The verifier never throws — every failure path returns
+ * `{ valid: false, reason }` so it composes cleanly inside the validator's
+ * per-attestation loop.
+ *
+ * @see ./validate-level2.ts — the validator this plugs into.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCombinedDidResolver = createCombinedDidResolver;
+exports.createVcJwtSignatureVerifier = createVcJwtSignatureVerifier;
+const jose_1 = require("jose");
+const did_key_resolver_js_1 = require("../delegation/did-key-resolver.js");
+const did_web_resolver_js_1 = require("../delegation/did-web-resolver.js");
+/**
+ * Create a DID resolver that dispatches by method: did:key is resolved locally,
+ * did:web is fetched over HTTPS, and every other method resolves to `null`.
+ *
+ * @param options - Optional pluggable fetch for the did:web branch.
+ */
+function createCombinedDidResolver(options = {}) {
+    const didKey = (0, did_key_resolver_js_1.createDidKeyResolver)();
+    const didWeb = (0, did_web_resolver_js_1.createDidWebResolver)({ fetch: options.fetch });
+    return {
+        resolve: async (did) => {
+            if (did.startsWith('did:key:'))
+                return didKey.resolve(did);
+            if (did.startsWith('did:web:'))
+                return didWeb.resolve(did);
+            return null;
+        },
+    };
+}
+/**
+ * Create a VC-JWT signature verifier suitable for
+ * {@link verifyCapabilities}'s `signatureVerifier` option.
+ *
+ * @param options - DID resolver / fetch overrides.
+ * @returns A `(vc, rawJwt) => Promise<{ valid; reason? }>` function.
+ */
+function createVcJwtSignatureVerifier(options = {}) {
+    const resolver = options.didResolver ?? createCombinedDidResolver({ fetch: options.fetch });
+    return async (vc, rawJwt) => {
+        if (rawJwt === undefined) {
+            return { valid: false, reason: 'no compact JWS' };
+        }
+        const issuerDid = extractIssuerDid(vc);
+        if (!issuerDid) {
+            return { valid: false, reason: 'VC missing issuer' };
+        }
+        let kid;
+        try {
+            kid = (0, jose_1.decodeProtectedHeader)(rawJwt).kid;
+        }
+        catch {
+            return { valid: false, reason: 'malformed JWS protected header' };
+        }
+        let didDoc;
+        try {
+            didDoc = await resolver.resolve(issuerDid);
+        }
+        catch (err) {
+            return {
+                valid: false,
+                reason: `issuer resolution failed: ${errorMessage(err)}`,
+            };
+        }
+        if (!didDoc) {
+            return { valid: false, reason: `could not resolve issuer ${issuerDid}` };
+        }
+        const method = selectVerificationMethod(didDoc, kid);
+        if (!method?.publicKeyJwk) {
+            return {
+                valid: false,
+                reason: kid
+                    ? `no verification method matching kid ${kid}`
+                    : 'no verification method with a publicKeyJwk',
+            };
+        }
+        try {
+            const key = await (0, jose_1.importJWK)(method.publicKeyJwk, 'EdDSA');
+            await (0, jose_1.compactVerify)(rawJwt, key);
+            return { valid: true };
+        }
+        catch (err) {
+            return {
+                valid: false,
+                reason: `signature verification failed: ${errorMessage(err)}`,
+            };
+        }
+    };
+}
+/**
+ * Select the verification method to verify against.
+ *
+ * When the JWS carries a `kid`, prefer an exact id match; only when none exists
+ * fall back to matching by fragment — so a fragment-only kid (`#key-1`) and a
+ * fully-qualified id (`did:web:example#key-1`), both common across did:web
+ * documents and JWTs, still resolve to the same key, while a later exact match
+ * is never shadowed by an earlier fragment-only one. Stays fail-closed: a kid
+ * that matches no method is rejected, and a wrongly-matched key fails the
+ * subsequent signature check. Without a `kid`, fall back to the first method
+ * with a `publicKeyJwk`.
+ */
+function selectVerificationMethod(didDoc, kid) {
+    const methods = didDoc.verificationMethod ?? [];
+    if (kid) {
+        const exact = methods.find((method) => method.id === kid);
+        if (exact)
+            return exact;
+        const kidFragment = fragmentOf(kid);
+        return methods.find((method) => fragmentOf(method.id) === kidFragment);
+    }
+    return methods.find((method) => method.publicKeyJwk);
+}
+/** The fragment of a DID-URL reference (the part after `#`), or the whole ref if none. */
+function fragmentOf(ref) {
+    const hash = ref.indexOf('#');
+    return hash >= 0 ? ref.slice(hash + 1) : ref;
+}
+function extractIssuerDid(vc) {
+    const issuer = vc.issuer;
+    if (typeof issuer === 'string')
+        return issuer;
+    if (issuer && typeof issuer === 'object' && typeof issuer.id === 'string') {
+        return issuer.id;
+    }
+    return undefined;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=vc-jwt-verifier.js.map

package/dist/delegation/did-web-resolver.d.ts

@@ -0,0 +1,60 @@
+/**
+ * did:web Resolver
+ *
+ * Resolves did:web DIDs to DID Documents by fetching the well-known document
+ * over HTTPS, per the did:web method spec.
+ *
+ * URL mapping (did:web method spec §3.2):
+ *   did:web:example.com         → https://example.com/.well-known/did.json
+ *   did:web:example.com:a:b     → https://example.com/a/b/did.json
+ *   did:web:example.com%3A3000  → https://example.com:3000/.well-known/did.json
+ *
+ * Percent-encoded characters in each colon-separated segment are decoded
+ * (notably `%3A` for a host:port colon).
+ *
+ * The fetch implementation is pluggable so callers — and tests — can supply
+ * their own transport; it defaults to the global `fetch`. The resolver never
+ * throws: a non-did:web input, non-OK response, malformed document, or
+ * transport error all resolve to `null`.
+ *
+ * Mirrors the shape of {@link createDidKeyResolver}.
+ *
+ * @see https://w3c-ccg.github.io/did-method-web/
+ */
+import type { DIDResolver } from './vc-verifier';
+/** Minimal subset of a fetch `Response` consumed by the resolver. */
+export interface DidWebFetchResponse {
+    ok: boolean;
+    json(): Promise<unknown>;
+}
+/**
+ * Pluggable fetch signature. The global `fetch` satisfies this structurally,
+ * so it is the default.
+ */
+export type DidWebFetch = (url: string) => Promise<DidWebFetchResponse>;
+/** Options for {@link createDidWebResolver}. */
+export interface DidWebResolverOptions {
+    /** Transport used to retrieve the DID document. Defaults to global `fetch`. */
+    fetch?: DidWebFetch;
+    /**
+     * Max time (ms) to wait for the DID document before failing closed (returning
+     * `null`). Guards against a stalled issuer endpoint hanging verification.
+     * Defaults to {@link DEFAULT_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Convert a did:web DID into the HTTPS URL of its DID document.
+ *
+ * @param did - The did:web DID to map.
+ * @returns The document URL, or `null` if the DID is not a well-formed did:web.
+ */
+export declare function didWebToUrl(did: string): string | null;
+/**
+ * Create a did:web resolver.
+ *
+ * @param options - Optional pluggable fetch transport.
+ * @returns A {@link DIDResolver} for did:web DIDs.
+ */
+export declare function createDidWebResolver(options?: DidWebResolverOptions): DIDResolver;
+//# sourceMappingURL=did-web-resolver.d.ts.map

package/dist/delegation/did-web-resolver.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * did:web Resolver
+ *
+ * Resolves did:web DIDs to DID Documents by fetching the well-known document
+ * over HTTPS, per the did:web method spec.
+ *
+ * URL mapping (did:web method spec §3.2):
+ *   did:web:example.com         → https://example.com/.well-known/did.json
+ *   did:web:example.com:a:b     → https://example.com/a/b/did.json
+ *   did:web:example.com%3A3000  → https://example.com:3000/.well-known/did.json
+ *
+ * Percent-encoded characters in each colon-separated segment are decoded
+ * (notably `%3A` for a host:port colon).
+ *
+ * The fetch implementation is pluggable so callers — and tests — can supply
+ * their own transport; it defaults to the global `fetch`. The resolver never
+ * throws: a non-did:web input, non-OK response, malformed document, or
+ * transport error all resolve to `null`.
+ *
+ * Mirrors the shape of {@link createDidKeyResolver}.
+ *
+ * @see https://w3c-ccg.github.io/did-method-web/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.didWebToUrl = didWebToUrl;
+exports.createDidWebResolver = createDidWebResolver;
+/** did:web method prefix. */
+const DID_WEB_PREFIX = 'did:web:';
+/** Default time budget (ms) for retrieving a DID document before failing closed. */
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * Convert a did:web DID into the HTTPS URL of its DID document.
+ *
+ * @param did - The did:web DID to map.
+ * @returns The document URL, or `null` if the DID is not a well-formed did:web.
+ */
+function didWebToUrl(did) {
+    if (!did.startsWith(DID_WEB_PREFIX)) {
+        return null;
+    }
+    const identifier = did.slice(DID_WEB_PREFIX.length);
+    if (identifier.length === 0) {
+        return null;
+    }
+    const segments = identifier.split(':');
+    let host;
+    let path;
+    try {
+        host = decodeURIComponent(segments[0]);
+        path = segments.slice(1).map((segment) => decodeURIComponent(segment));
+    }
+    catch {
+        // Malformed percent-encoding (decodeURIComponent throws URIError).
+        return null;
+    }
+    if (host.length === 0 || path.some((segment) => segment.length === 0)) {
+        return null;
+    }
+    const suffix = path.length === 0
+        ? '/.well-known/did.json'
+        : `/${path.join('/')}/did.json`;
+    return `https://${host}${suffix}`;
+}
+/**
+ * Create a did:web resolver.
+ *
+ * @param options - Optional pluggable fetch transport.
+ * @returns A {@link DIDResolver} for did:web DIDs.
+ */
+function createDidWebResolver(options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const doFetch = options.fetch ?? ((url) => fetch(url, { signal: AbortSignal.timeout(timeoutMs) }));
+    return {
+        resolve: async (did) => {
+            const url = didWebToUrl(did);
+            if (!url) {
+                return null;
+            }
+            let response;
+            try {
+                response = await withTimeout(doFetch(url), timeoutMs);
+            }
+            catch {
+                // Transport error, abort, or timeout → fail closed.
+                return null;
+            }
+            if (!response.ok) {
+                return null;
+            }
+            let doc;
+            try {
+                doc = await response.json();
+            }
+            catch {
+                return null;
+            }
+            return isDidDocument(doc) ? doc : null;
+        },
+    };
+}
+/**
+ * Minimal structural check: a DID Document is an object with a string `id`.
+ */
+function isDidDocument(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.id === 'string');
+}
+/**
+ * Reject if `promise` does not settle within `ms`, so a stalled fetch fails
+ * closed (the resolver returns `null`) instead of hanging verification
+ * indefinitely. The default transport additionally aborts the underlying request
+ * via `AbortSignal.timeout`; this race also bounds a custom transport.
+ */
+async function withTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`did:web fetch timed out after ${ms}ms`)), ms);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=did-web-resolver.js.map

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export { MemoryStatusListStorage } from "./delegation/storage/memory-statuslist-
 export { MemoryDelegationGraphStorage } from "./delegation/storage/memory-graph-storage";
 export { buildDelegationProofJWT, buildChainString, type DelegationProofOptions, type Ed25519PrivateJWK, } from "./delegation/outbound-proof";
 export { createDidKeyResolver, isEd25519DidKey, extractPublicKeyFromDidKey, publicKeyToJwk, resolveDidKeySync, } from "./delegation/did-key-resolver";
+export { createDidWebResolver, didWebToUrl, type DidWebFetch, type DidWebFetchResponse, type DidWebResolverOptions, } from "./delegation/did-web-resolver";
 export { canonicalizeJSON, createUnsignedVCJWT, completeVCJWT, parseVCJWT, type VCJWTHeader, type VCJWTPayload, type EncodeVCAsJWTOptions, } from "./delegation/utils";
-export { validateLevel2, DEFAULT_TRUSTED_ISSUERS, type CapabilityName, type CapabilityAttestation, type CapabilityAttestationCredential, type Level2Capability, type ManifestCapabilities, type CapabilityVCSignatureVerifier, type CapabilityStatusListResolver, type ValidateLevel2Options, type ValidateLevel2Result, type InvalidCapability, } from "./conformance/index.js";
+export { verifyCapabilities, validateLevel2, DEFAULT_TRUSTED_ISSUERS, type CapabilityName, type CapabilityAttestation, type CapabilityAttestationCredential, type Level2Capability, type ManifestCapabilities, type CapabilityVCSignatureVerifier, type CapabilityStatusListResolver, type ValidateLevel2Options, type ValidateLevel2Result, type InvalidCapability, createVcJwtSignatureVerifier, createCombinedDidResolver, type VcJwtVerifierOptions, createCapabilityVerifier, type DuckTypedCapability, type CapabilityVerificationContext, type CapabilityVerificationResult, type CapabilityVerifier, type CreateCapabilityVerifierOptions, } from "./conformance/index.js";
 //# sourceMappingURL=index.d.ts.map