@hellocoop/email-verification
Version:
Functions for generating and verifying JWT tokens used in the Email Verification Protocol
74 lines • 2.76 kB
TypeScript
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