@private.me/xbind 1.2.0

package/dist-standalone/connect.js

@@ -0,0 +1,274 @@
+/**
+ * @module connect
+ * High-level connect() API for zero-config XBind connections.
+ *
+ * Enables: `const service = await connect('payments-service')`
+ *
+ * Combines:
+ * - Service discovery
+ * - Trust verification
+ * - Agent creation
+ * - Connection establishment
+ *
+ * @example
+ * ```ts
+ * import { connect } from '@private.me/xbind';
+ *
+ * // Connect by name (uses registry):
+ * const payments = await connect('payments-service');
+ *
+ * // Connect by domain (uses .well-known):
+ * const payments = await connect('payments.example.com');
+ *
+ * // Connect by URL (direct):
+ * const payments = await connect('https://api.payments.com/xbind');
+ *
+ * // Use the connection:
+ * await payments.send({
+ *   to: payments.did,
+ *   payload: { action: 'createCharge', amount: 100 },
+ *   scope: 'payments',
+ * });
+ * ```
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { fromBase64, toBase64 } from"./_deps/crypto/index.js";
+import { Agent } from './agent.js';
+import { ServiceDiscovery } from './discovery.js';
+import { HttpsTransportAdapter } from './transport.js';
+import { MemoryTrustRegistry } from './trust-registry.js';
+import { importPublicKey } from './identity.js';
+/**
+ * Connect error codes.
+ */
+export var ConnectErrorCode;
+(function (ConnectErrorCode) {
+    ConnectErrorCode["DISCOVERY_FAILED"] = "CONNECT_DISCOVERY_FAILED";
+    ConnectErrorCode["AGENT_CREATION_FAILED"] = "CONNECT_AGENT_CREATION_FAILED";
+    ConnectErrorCode["TRUST_VERIFICATION_FAILED"] = "CONNECT_TRUST_VERIFICATION_FAILED";
+    ConnectErrorCode["INVALID_SERVICE_INFO"] = "CONNECT_INVALID_SERVICE_INFO";
+})(ConnectErrorCode || (ConnectErrorCode = {}));
+/**
+ * Connect to a service with zero configuration.
+ *
+ * @param nameOrUrl - Service name, domain, or URL
+ * @param options - Connection options
+ * @returns Connection or error
+ *
+ * @example
+ * ```ts
+ * // Minimal:
+ * const connection = await connect('payments-service');
+ * if (connection.ok) {
+ *   await connection.value.agent.send({
+ *     to: connection.value.did,
+ *     payload: { action: 'test' },
+ *     scope: 'test',
+ *   });
+ * }
+ *
+ * // With options:
+ * const connection = await connect('payments-service', {
+ *   name: 'billing-service',
+ *   xchange: true, // Use faster Xchange mode
+ *   splitChannel: true, // Use split-channel by default
+ * });
+ * ```
+ */
+export async function connect(nameOrUrl, options = {}) {
+    // Step 1: Discover service
+    const discovery = options.discovery || new ServiceDiscovery();
+    const serviceResult = await discovery.discover(nameOrUrl);
+    if (!serviceResult.ok) {
+        return err({
+            code: ConnectErrorCode.DISCOVERY_FAILED,
+            message: `Failed to discover service: ${serviceResult.error.message}`,
+            hint: serviceResult.error.hint,
+            cause: serviceResult.error,
+        });
+    }
+    const service = serviceResult.value;
+    // Step 2: Validate service info
+    if (!service.did || !service.endpoint || !service.publicKey) {
+        return err({
+            code: ConnectErrorCode.INVALID_SERVICE_INFO,
+            message: 'Service info missing required fields (did, endpoint, publicKey)',
+            hint: 'Service must provide complete metadata',
+        });
+    }
+    // Step 3: Create trust registry and add service
+    const registry = options.registry || new MemoryTrustRegistry();
+    try {
+        // Import public key (convert from base64 string)
+        const publicKeyBytes = fromBase64(service.publicKey);
+        const publicKeyResult = await importPublicKey(publicKeyBytes);
+        if (!publicKeyResult.ok) {
+            return err({
+                code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
+                message: 'Invalid service public key',
+                cause: publicKeyResult.error,
+            });
+        }
+        // Add to trust registry
+        await registry.add({
+            did: service.did,
+            publicKey: publicKeyResult.value,
+            x25519PublicKey: service.x25519PublicKey
+                ? await importPublicKey(fromBase64(service.x25519PublicKey)).then(r => r.ok ? r.value : undefined)
+                : undefined,
+            mlKemPublicKey: service.mlKemPublicKey
+                ? fromBase64(service.mlKemPublicKey)
+                : undefined,
+        });
+    }
+    catch (error) {
+        return err({
+            code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
+            message: 'Failed to verify service public key',
+            cause: error,
+        });
+    }
+    // Step 4: Create transport
+    const transport = options.transport || new HttpsTransportAdapter({
+        baseUrl: service.endpoint,
+    });
+    // Step 5: Create agent
+    const agentName = options.name || `client-${Date.now()}`;
+    const agentOptions = {
+        name: agentName,
+        registry,
+        transport,
+        xchange: options.xchange,
+        postQuantumSig: options.postQuantumSig,
+    };
+    const agentResult = await Agent.create(agentOptions);
+    if (!agentResult.ok) {
+        return err({
+            code: ConnectErrorCode.AGENT_CREATION_FAILED,
+            message: 'Failed to create agent',
+            cause: agentResult.error,
+        });
+    }
+    // Step 6: Return connection
+    return ok({
+        agent: agentResult.value,
+        service,
+        did: service.did,
+        endpoint: service.endpoint,
+    });
+}
+/**
+ * Accept an invite and establish connection.
+ *
+ * @param inviteUrl - Invite URL
+ * @param options - Connection options
+ * @returns Connection or error
+ *
+ * @example
+ * ```ts
+ * const connection = await acceptInvite('https://xbind.to/invite/abc123', {
+ *   name: 'my-service',
+ * });
+ *
+ * if (connection.ok) {
+ *   console.log('Connected to:', connection.value.service.name);
+ * }
+ * ```
+ */
+export async function acceptInvite(inviteUrl, options = {}) {
+    const { InviteService } = await import('./invite.js');
+    const inviteService = new InviteService();
+    // Get invite details
+    const inviteResult = await inviteService.get(inviteUrl);
+    if (!inviteResult.ok) {
+        return err({
+            code: ConnectErrorCode.DISCOVERY_FAILED,
+            message: `Failed to get invite: ${inviteResult.error.message}`,
+            cause: inviteResult.error,
+        });
+    }
+    const invite = inviteResult.value;
+    // Convert invite.from to ServiceInfo
+    const service = {
+        name: invite.from.name,
+        did: invite.from.did,
+        endpoint: invite.from.endpoint,
+        publicKey: invite.from.publicKey,
+        x25519PublicKey: invite.from.x25519PublicKey,
+        mlKemPublicKey: invite.from.mlKemPublicKey,
+    };
+    // Connect to service (same as connect())
+    // Create trust registry and add service
+    const registry = options.registry || new MemoryTrustRegistry();
+    try {
+        // Import public key (convert from base64 string)
+        const publicKeyBytes = fromBase64(service.publicKey);
+        const publicKeyResult = await importPublicKey(publicKeyBytes);
+        if (!publicKeyResult.ok) {
+            return err({
+                code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
+                message: 'Invalid service public key',
+                cause: publicKeyResult.error,
+            });
+        }
+        await registry.add({
+            did: service.did,
+            publicKey: publicKeyResult.value,
+            x25519PublicKey: service.x25519PublicKey
+                ? await importPublicKey(fromBase64(service.x25519PublicKey)).then(r => r.ok ? r.value : undefined)
+                : undefined,
+            mlKemPublicKey: service.mlKemPublicKey
+                ? fromBase64(service.mlKemPublicKey)
+                : undefined,
+        });
+    }
+    catch (error) {
+        return err({
+            code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
+            message: 'Failed to verify service public key',
+            cause: error,
+        });
+    }
+    const transport = options.transport || new HttpsTransportAdapter({
+        baseUrl: service.endpoint,
+    });
+    const agentName = options.name || `client-${Date.now()}`;
+    const agentOptions = {
+        name: agentName,
+        registry,
+        transport,
+        xchange: options.xchange,
+        postQuantumSig: options.postQuantumSig,
+    };
+    const agentResult = await Agent.create(agentOptions);
+    if (!agentResult.ok) {
+        return err({
+            code: ConnectErrorCode.AGENT_CREATION_FAILED,
+            message: 'Failed to create agent',
+            cause: agentResult.error,
+        });
+    }
+    // Accept the invite
+    const acceptResult = await inviteService.accept({
+        inviteUrl,
+        acceptor: {
+            name: agentOptions.name,
+            did: agentResult.value.did,
+            endpoint: options.endpoint || '', // Agent's endpoint (where it can be reached), empty for client-only agents
+            publicKey: toBase64(agentResult.value.identity.rawPublicKey),
+            x25519PublicKey: agentResult.value.identity.rawX25519PublicKey
+                ? toBase64(agentResult.value.identity.rawX25519PublicKey)
+                : undefined,
+        },
+    });
+    if (!acceptResult.ok) {
+        // Connection created but invite acceptance failed - still return connection
+        // (invite acceptance is for tracking/notification, not required for connectivity)
+    }
+    return ok({
+        agent: agentResult.value,
+        service,
+        did: service.did,
+        endpoint: service.endpoint,
+    });
+}

package/dist-standalone/did-document.d.ts

@@ -0,0 +1,65 @@
+import type { Result } from '@private.me/shared';
+/**
+ * DID Document representation for did:key and did:privateme DIDs.
+ *
+ * Mechanism 3: Includes service endpoints for viral exposure.
+ * When Bob receives a message from Alice, Bob's agent can resolve Alice's
+ * DID to retrieve the service endpoint, learning about PRIVATE.ME/xBind.
+ */
+export interface DidDocument {
+    '@context': string[];
+    id: string;
+    name?: string;
+    publicKey?: Array<{
+        id: string;
+        type: string;
+        controller: string;
+        publicKeyBase64?: string;
+        publicKeyMultibase?: string;
+    }>;
+    authentication?: string[];
+    assertionMethod?: string[];
+    keyAgreement?: string[];
+    service?: Array<{
+        id: string;
+        type: string;
+        serviceEndpoint: string | Record<string, unknown>;
+        description?: string;
+    }>;
+}
+/**
+ * Generate a DID document for a given DID.
+ *
+ * Includes service endpoints that advertise PRIVATE.ME/xBind.
+ * Both did:key and did:privateme DIDs generate the same service endpoints.
+ *
+ * @param did - The DID (did:key:z... or did:privateme:z...)
+ * @param rawPublicKey - The 32-byte Ed25519 public key
+ * @param name - Optional name for the identity
+ * @returns DID document with service endpoints
+ */
+export declare function generateDidDocument(did: string, rawPublicKey: Uint8Array, name?: string): Result<DidDocument, string>;
+/**
+ * Resolve a DID to its document (simulated).
+ *
+ * In a production system, this would query a DID resolver.
+ * For now, this generates a synthetic document based on the DID.
+ *
+ * @param did - The DID to resolve
+ * @param rawPublicKey - The 32-byte Ed25519 public key
+ * @returns DID document or error
+ */
+export declare function resolveDid(did: string, rawPublicKey: Uint8Array): Promise<Result<DidDocument, string>>;
+/**
+ * Extract service endpoints from a DID document.
+ *
+ * Filters for PRIVATE.ME service endpoints to provide discovery information.
+ *
+ * @param document - The DID document
+ * @returns Array of service endpoints advertising PRIVATE.ME services
+ */
+export declare function getServiceEndpoints(document: DidDocument): Array<{
+    type: string;
+    endpoint: string;
+    description?: string;
+}>;

package/dist-standalone/did-document.js

@@ -0,0 +1,96 @@
+import { ok, err } from"./_deps/shared/index.js";
+import { toBase64 } from"./_deps/crypto/index.js";
+/**
+ * Generate a DID document for a given DID.
+ *
+ * Includes service endpoints that advertise PRIVATE.ME/xBind.
+ * Both did:key and did:privateme DIDs generate the same service endpoints.
+ *
+ * @param did - The DID (did:key:z... or did:privateme:z...)
+ * @param rawPublicKey - The 32-byte Ed25519 public key
+ * @param name - Optional name for the identity
+ * @returns DID document with service endpoints
+ */
+export function generateDidDocument(did, rawPublicKey, name) {
+    if (!did.startsWith('did:key:') && !did.startsWith('did:privateme:')) {
+        return err('INVALID_DID_FORMAT');
+    }
+    // Convert public key to base64 for inclusion in document
+    const publicKeyBase64 = toBase64(rawPublicKey);
+    const document = {
+        '@context': [
+            'https://www.w3.org/ns/did/v1',
+            'https://w3id.org/security/suites/ed25519-2020/v1',
+        ],
+        id: did,
+        publicKey: [
+            {
+                id: `${did}#key-1`,
+                type: 'Ed25519VerificationKey2020',
+                controller: did,
+                publicKeyBase64,
+            },
+        ],
+        authentication: [`${did}#key-1`],
+        assertionMethod: [`${did}#key-1`],
+        keyAgreement: [`${did}#key-1`],
+        service: [
+            {
+                id: `${did}#identity-provider`,
+                type: 'IdentityProvider',
+                serviceEndpoint: 'https://private.me',
+                description: 'PRIVATE.ME xBind Agent - M2M identity authentication',
+            },
+            {
+                id: `${did}#documentation`,
+                type: 'Documentation',
+                serviceEndpoint: 'https://private.me/docs/xbind.html',
+                description: 'Learn more about PRIVATE.ME/xBind protocol',
+            },
+        ],
+        ...(name ? { name } : {}),
+    };
+    return ok(document);
+}
+/**
+ * Resolve a DID to its document (simulated).
+ *
+ * In a production system, this would query a DID resolver.
+ * For now, this generates a synthetic document based on the DID.
+ *
+ * @param did - The DID to resolve
+ * @param rawPublicKey - The 32-byte Ed25519 public key
+ * @returns DID document or error
+ */
+export async function resolveDid(did, rawPublicKey) {
+    // In a production system, this would make an HTTP request to a DID resolver
+    // For now, generate a synthetic document
+    return generateDidDocument(did, rawPublicKey);
+}
+/**
+ * Extract service endpoints from a DID document.
+ *
+ * Filters for PRIVATE.ME service endpoints to provide discovery information.
+ *
+ * @param document - The DID document
+ * @returns Array of service endpoints advertising PRIVATE.ME services
+ */
+export function getServiceEndpoints(document) {
+    if (!document.service)
+        return [];
+    return document.service
+        .filter((svc) => {
+        const endpoint = typeof svc.serviceEndpoint === 'string' ? svc.serviceEndpoint : '';
+        return (endpoint.includes('private.me') ||
+            svc.type.includes('PRIVATE.ME') ||
+            svc.type === 'IdentityProvider' ||
+            svc.type === 'Documentation');
+    })
+        .map((svc) => ({
+        type: svc.type,
+        endpoint: typeof svc.serviceEndpoint === 'string'
+            ? svc.serviceEndpoint
+            : JSON.stringify(svc.serviceEndpoint),
+        description: svc.description,
+    }));
+}

package/dist-standalone/did-privateme.d.ts

@@ -0,0 +1,70 @@
+import type { Result } from '@private.me/shared';
+/**
+ * Mechanism 4: Convert Ed25519 public key to did:privateme DID.
+ *
+ * Format: did:privateme:z + base58btc(0xed01 || publicKey)
+ *
+ * This is a new DID method identifier for PRIVATE.ME ACIs.
+ * It uses the same base58btc encoding as did:key for compatibility,
+ * but signals that the identity is backed by PRIVATE.ME infrastructure.
+ *
+ * Backward compatible: agents accept both did:key and did:privateme formats.
+ *
+ * @param rawPublicKey - 32-byte Ed25519 public key
+ * @returns DID in format did:privateme:z...
+ */
+export declare function publicKeyToPrivateMeDid(rawPublicKey: Uint8Array): string;
+/**
+ * Extract raw 32-byte public key from a did:privateme DID.
+ *
+ * Format: did:privateme:z + base58btc(0xed01 || publicKey)
+ *
+ * @param did - DID in format did:privateme:z...
+ * @returns 32-byte public key or error
+ */
+export declare function privateMeDidToPublicKeyBytes(did: string): Result<Uint8Array, string>;
+/**
+ * Determine if a DID is in the new did:privateme format.
+ *
+ * @param did - The DID to check
+ * @returns true if DID is did:privateme format, false otherwise
+ */
+export declare function isPrivateMeDid(did: string): boolean;
+/**
+ * Determine if a DID is in the did:key format.
+ *
+ * @param did - The DID to check
+ * @returns true if DID is did:key format, false otherwise
+ */
+export declare function isDidKeyFormat(did: string): boolean;
+/**
+ * Convert between DID formats (did:key ↔ did:privateme).
+ *
+ * Allows backward compatibility between old did:key and new did:privateme formats.
+ * The public key remains the same; only the method identifier changes.
+ *
+ * @param did - Source DID in either format
+ * @returns Converted DID in the other format, or error
+ */
+export declare function convertDidFormat(did: string): Result<string, string>;
+/**
+ * Normalize a DID to the canonical format (did:privateme).
+ *
+ * All DIDs are converted to did:privateme format for consistency.
+ * Existing did:key DIDs are automatically upgraded.
+ *
+ * @param did - Source DID in any supported format
+ * @returns Normalized DID in did:privateme format
+ */
+export declare function normalizeDid(did: string): Result<string, string>;
+/**
+ * Parse a DID into method, identifier, and fragment.
+ *
+ * @param did - Full DID string
+ * @returns Parsed DID components or error
+ */
+export declare function parseDid(did: string): Result<{
+    method: string;
+    identifier: string;
+    fragment?: string;
+}, string>;

package/dist-standalone/did-privateme.js

@@ -0,0 +1,121 @@
+import { ok, err } from"./_deps/shared/index.js";
+import { publicKeyToDid, didToPublicKeyBytes } from './identity.js';
+/**
+ * Mechanism 4: Convert Ed25519 public key to did:privateme DID.
+ *
+ * Format: did:privateme:z + base58btc(0xed01 || publicKey)
+ *
+ * This is a new DID method identifier for PRIVATE.ME ACIs.
+ * It uses the same base58btc encoding as did:key for compatibility,
+ * but signals that the identity is backed by PRIVATE.ME infrastructure.
+ *
+ * Backward compatible: agents accept both did:key and did:privateme formats.
+ *
+ * @param rawPublicKey - 32-byte Ed25519 public key
+ * @returns DID in format did:privateme:z...
+ */
+export function publicKeyToPrivateMeDid(rawPublicKey) {
+    // Use same encoding as did:key, but with privateme method
+    const didKeyFormat = publicKeyToDid(rawPublicKey);
+    // Replace did:key: with did:privateme:
+    return didKeyFormat.replace(/^did:key:/, 'did:privateme:');
+}
+/**
+ * Extract raw 32-byte public key from a did:privateme DID.
+ *
+ * Format: did:privateme:z + base58btc(0xed01 || publicKey)
+ *
+ * @param did - DID in format did:privateme:z...
+ * @returns 32-byte public key or error
+ */
+export function privateMeDidToPublicKeyBytes(did) {
+    if (!did.startsWith('did:privateme:z')) {
+        return err('INVALID_DID_FORMAT');
+    }
+    // Convert to did:key format temporarily for parsing
+    const didKeyFormat = did.replace(/^did:privateme:/, 'did:key:');
+    // Use the existing parser
+    const result = didToPublicKeyBytes(didKeyFormat);
+    if (!result.ok) {
+        return err(result.error);
+    }
+    return ok(result.value);
+}
+/**
+ * Determine if a DID is in the new did:privateme format.
+ *
+ * @param did - The DID to check
+ * @returns true if DID is did:privateme format, false otherwise
+ */
+export function isPrivateMeDid(did) {
+    return did.startsWith('did:privateme:');
+}
+/**
+ * Determine if a DID is in the did:key format.
+ *
+ * @param did - The DID to check
+ * @returns true if DID is did:key format, false otherwise
+ */
+export function isDidKeyFormat(did) {
+    return did.startsWith('did:key:');
+}
+/**
+ * Convert between DID formats (did:key ↔ did:privateme).
+ *
+ * Allows backward compatibility between old did:key and new did:privateme formats.
+ * The public key remains the same; only the method identifier changes.
+ *
+ * @param did - Source DID in either format
+ * @returns Converted DID in the other format, or error
+ */
+export function convertDidFormat(did) {
+    if (isDidKeyFormat(did)) {
+        // Convert did:key to did:privateme
+        return ok(did.replace(/^did:key:/, 'did:privateme:'));
+    }
+    if (isPrivateMeDid(did)) {
+        // Convert did:privateme to did:key
+        return ok(did.replace(/^did:privateme:/, 'did:key:'));
+    }
+    return err('UNSUPPORTED_DID_FORMAT');
+}
+/**
+ * Normalize a DID to the canonical format (did:privateme).
+ *
+ * All DIDs are converted to did:privateme format for consistency.
+ * Existing did:key DIDs are automatically upgraded.
+ *
+ * @param did - Source DID in any supported format
+ * @returns Normalized DID in did:privateme format
+ */
+export function normalizeDid(did) {
+    if (isPrivateMeDid(did)) {
+        // Already in target format
+        return ok(did);
+    }
+    if (isDidKeyFormat(did)) {
+        // Convert to did:privateme
+        return ok(did.replace(/^did:key:/, 'did:privateme:'));
+    }
+    return err('UNSUPPORTED_DID_FORMAT');
+}
+/**
+ * Parse a DID into method, identifier, and fragment.
+ *
+ * @param did - Full DID string
+ * @returns Parsed DID components or error
+ */
+export function parseDid(did) {
+    const fragmentMatch = did.indexOf('#');
+    const base = fragmentMatch >= 0 ? did.substring(0, fragmentMatch) : did;
+    const fragment = fragmentMatch >= 0 ? did.substring(fragmentMatch + 1) : undefined;
+    const parts = base.split(':');
+    if (parts.length < 3 || parts[0] !== 'did') {
+        return err('INVALID_DID_FORMAT');
+    }
+    return ok({
+        method: parts[1],
+        identifier: parts.slice(2).join(':'),
+        fragment,
+    });
+}

package/dist-standalone/did-web.d.ts

@@ -0,0 +1,73 @@
+/**
+ * did:web resolver — resolves DIDs hosted on developer domains.
+ *
+ * Implements the W3C did:web method:
+ *   did:web:example.com -> https://example.com/.well-known/did.json
+ *   did:web:example.com:path:to -> https://example.com/path/to/did.json
+ *
+ * Enables direct agent-to-agent communication without a centralized registry.
+ * Implements TrustRegistry interface for drop-in use with Agent class.
+ */
+import type { Result } from '@private.me/shared';
+import type { TrustRegistry, RegistryEntry, RegistryError } from './trust-registry.js';
+/** Options for DidWebResolver. */
+export interface DidWebResolverOptions {
+    /** Custom fetch implementation (for testing). */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Cache TTL in ms. Default: 300000 (5 min). */
+    readonly cacheTtlMs?: number;
+}
+/**
+ * Resolve did:web DIDs by fetching DID documents from the hosting domain.
+ *
+ * Implements TrustRegistry interface so it can be used as a drop-in
+ * replacement for MemoryTrustRegistry or HttpTrustRegistry.
+ */
+export declare class DidWebResolver implements TrustRegistry {
+    private readonly fetchFn;
+    private readonly cacheTtlMs;
+    private readonly cache;
+    constructor(opts?: DidWebResolverOptions);
+    /** Registration not supported for did:web (developers host their own). */
+    register(_did: string, _publicKey: Uint8Array, _name: string, _scopes?: string[], _x25519PublicKey?: Uint8Array): Promise<Result<void, RegistryError>>;
+    /**
+     * Resolve a did:web DID to its raw public key bytes.
+     * @param did - A did:web DID string.
+     * @returns Public key bytes or error.
+     */
+    resolve(did: string): Promise<Result<Uint8Array, RegistryError>>;
+    /**
+     * Check if a did:web DID has a specific scope.
+     * @param did - The DID to check.
+     * @param scope - The scope to verify.
+     * @returns True if scope is granted.
+     */
+    hasScope(did: string, scope: string): Promise<boolean>;
+    /**
+     * Check if a did:web DID has a specific receive scope.
+     * @param did - The DID to check.
+     * @param scope - The scope to verify.
+     * @returns True if receive scope is granted.
+     */
+    hasReceiveScope(did: string, scope: string): Promise<boolean>;
+    /** Revocation not supported for did:web (developer controls their domain). */
+    revoke(_did: string): Promise<Result<void, RegistryError>>;
+    /**
+     * Get the full registry entry for a did:web DID.
+     * @param did - The DID to look up.
+     * @returns Full entry or error.
+     */
+    getEntry(did: string): Promise<Result<RegistryEntry, RegistryError>>;
+    /** Number of cached entries (for testing). */
+    get cacheSize(): number;
+    /** Fetch and parse a DID document, with caching. */
+    private fetchEntry;
+}
+/**
+ * Convert a did:web DID to its HTTPS URL.
+ *   did:web:example.com -> https://example.com/.well-known/did.json
+ *   did:web:example.com:path:to -> https://example.com/path/to/did.json
+ * @param did - The did:web DID string.
+ * @returns HTTPS URL or null if invalid.
+ */
+export declare function didWebToUrl(did: string): string | null;