UNPKG

@hellocoop/email-verification

Version:

Functions for generating and verifying JWT tokens used in the Email Verification Protocol

74 lines 2.76 kB
import type { JWK } from 'jose'; import { EmailVerificationError } from '../errors.js'; /** * Error thrown when DNS discovery fails */ export declare class DNSDiscoveryError extends EmailVerificationError { constructor(message: string); } /** * Error thrown when JWKS fetching fails */ export declare class JWKSFetchError extends EmailVerificationError { constructor(message: string); } /** * Discovers the email-verification issuer for an email address or domain via DNS TXT record lookup * Looks for TXT record with format: "iss=issuer.example" at "_email-verification.$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>; /** * Email Verification metadata structure from /.well-known/email-verification */ export interface EmailVerificationMetadata { 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 email-verification metadata from an issuer domain * Follows the spec path: https://issuer.example/.well-known/email-verification * 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 email-verification metadata * @throws JWKSFetchError if metadata cannot be fetched or parsed */ export declare function fetchEmailVerificationMetadata(issuerIdentifier: string, options?: RequestOptions): Promise<EmailVerificationMetadata>; /** * Fetches JWKS (JSON Web Key Set) from a JWKS URI * * @param jwksUri - JWKS URI from email-verification 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