@hellocoop/web-identity/dist/types/utils/dns-discovery.d.ts

Functions for generating and verifying JWT tokens used in the Verified Email Autocomplete protocol

import type { JWK } from 'jose';
import { WebIdentityError } from '../errors.js';
/**
 * Error thrown when DNS discovery fails
 */
export declare class DNSDiscoveryError extends WebIdentityError {
    constructor(message: string);
}
/**
 * Error thrown when JWKS fetching fails
 */
export declare class JWKSFetchError extends WebIdentityError {
    constructor(message: string);
}
/**
 * Discovers the web-identity issuer for an email address or domain via DNS TXT record lookup
 * Looks for TXT record with format: "iss=issuer.example" at "email._web-identity.$EMAIL_DOMAIN"
 *
 * NOTE: Spec should clarify that there can only be one iss= record per domain
 *
 * @param emailOrDomain - Email address or domain to lookup
 * @returns Promise resolving to issuer identifier (domain, not URL)
 * @throws DNSDiscoveryError if no issuer is found or DNS lookup fails
 */
export declare function discoverIssuer(emailOrDomain: string): Promise<string>;
/**
 * Web Identity metadata structure from /.well-known/web-identity
 */
export interface WebIdentityMetadata {
    issuance_endpoint: string;
    jwks_uri: string;
    signing_alg_values_supported?: string[];
}
/**
 * JWKS response structure
 */
export interface JWKSResponse {
    keys: JWK[];
}
/**
 * Options for HTTP requests
 */
export interface RequestOptions {
    /** Request timeout in milliseconds (default: 10000) */
    timeout?: number;
    /** Cache timeout in milliseconds (default: 300000 - 5 minutes) */
    cacheTimeout?: number;
}
/**
 * Fetches web-identity metadata from an issuer domain
 * Follows the spec path: https://issuer.example/.well-known/web-identity
 * Supports redirects to different subdomains of the same issuer domain
 *
 * @param issuerIdentifier - Issuer identifier (domain, e.g., "issuer.example")
 * @param options - Optional request configuration
 * @returns Promise resolving to web-identity metadata
 * @throws JWKSFetchError if metadata cannot be fetched or parsed
 */
export declare function fetchWebIdentityMetadata(issuerIdentifier: string, options?: RequestOptions): Promise<WebIdentityMetadata>;
/**
 * Fetches JWKS (JSON Web Key Set) from a JWKS URI
 *
 * @param jwksUri - JWKS URI from web-identity metadata
 * @param options - Optional request configuration
 * @returns Promise resolving to JWKS response
 * @throws JWKSFetchError if JWKS cannot be fetched or parsed
 */
export declare function fetchJWKS(jwksUri: string, options?: RequestOptions): Promise<JWKSResponse>;
/**
 * Clears the in-memory caches for metadata and JWKS
 * Useful for testing or when you want to force fresh fetches
 */
export declare function clearCaches(): void;
//# sourceMappingURL=dns-discovery.d.ts.map