@periodic/tungsten 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,357 @@
+/**
+ * Core type definitions for Tungsten authentication primitives
+ */
+/**
+ * Key provider abstraction for multi-tenant JWT signing/verification
+ */
+interface KeyProvider {
+    /**
+     * Get signing key for JWT creation
+     * @param kid - Optional key ID for rotation
+     */
+    getSigningKey(kid?: string): Promise<SigningKey>;
+    /**
+     * Get verification key for JWT validation
+     * @param kid - Key ID from JWT header
+     */
+    getVerificationKey(kid: string): Promise<VerificationKey>;
+}
+/**
+ * Signing key for JWT creation
+ */
+interface SigningKey {
+    kid: string;
+    algorithm: 'HS256' | 'RS256';
+    key: string | Uint8Array;
+}
+/**
+ * Verification key for JWT validation
+ */
+interface VerificationKey {
+    algorithm: 'HS256' | 'RS256';
+    key: string | Uint8Array;
+}
+/**
+ * JWT payload structure
+ */
+interface JWTPayload {
+    sub: string;
+    iat?: number;
+    exp?: number;
+    iss?: string;
+    aud?: string | string[];
+    jti?: string;
+    [key: string]: unknown;
+}
+/**
+ * Options for signing access tokens
+ */
+interface SignAccessTokenOptions {
+    expiresIn: string | number;
+    issuer?: string;
+    audience?: string | string[];
+    keyProvider: KeyProvider;
+    kid?: string;
+}
+/**
+ * Options for verifying access tokens
+ */
+interface VerifyAccessTokenOptions {
+    keyProvider: KeyProvider;
+    issuer?: string;
+    audience?: string | string[];
+    clockTolerance?: number;
+}
+/**
+ * Options for refresh token rotation
+ */
+interface RotateRefreshTokenOptions {
+    keyProvider: KeyProvider;
+    onTokenReused?: (jti: string) => Promise<void>;
+}
+/**
+ * Result of refresh token rotation
+ */
+interface RefreshTokenRotationResult {
+    accessToken: string;
+    refreshToken: string;
+    payload: JWTPayload;
+}
+/**
+ * Options for API key generation
+ */
+interface GenerateApiKeyOptions {
+    prefix?: string;
+    length?: number;
+}
+/**
+ * Security event hook for monitoring
+ */
+interface SecurityEventHook {
+    onTokenReused?(jti: string, metadata: Record<string, unknown>): Promise<void>;
+    onTokenExpired?(jti: string, metadata: Record<string, unknown>): Promise<void>;
+    onInvalidSignature?(metadata: Record<string, unknown>): Promise<void>;
+    onPasswordHashingFailure?(error: Error): Promise<void>;
+}
+/**
+ * Instrumentation adapter for metrics
+ */
+interface InstrumentationAdapter {
+    recordTokenGeneration(duration: number, metadata: Record<string, unknown>): void;
+    recordTokenVerification(duration: number, success: boolean, metadata: Record<string, unknown>): void;
+    recordPasswordHashing(duration: number, metadata: Record<string, unknown>): void;
+    recordPasswordVerification(duration: number, success: boolean): void;
+}
+/**
+ * Cookie configuration options
+ */
+interface CookieOptions {
+    name: string;
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    maxAge?: number;
+}
+/**
+ * TOTP configuration options
+ */
+interface TOTPOptions {
+    period?: number;
+    digits?: number;
+    algorithm?: 'SHA1' | 'SHA256' | 'SHA512';
+    window?: number;
+}
+/**
+ * TOTP verification result
+ */
+interface TOTPVerificationResult {
+    valid: boolean;
+    delta?: number;
+}
+
+/**
+ * JWT access and refresh token utilities with HS256/RS256 support
+ */
+
+/**
+ * Sign an access token with JWT
+ */
+declare function signAccessToken(payload: JWTPayload, options: SignAccessTokenOptions): Promise<string>;
+/**
+ * Verify an access token
+ */
+declare function verifyAccessToken(token: string, options: VerifyAccessTokenOptions): Promise<JWTPayload>;
+/**
+ * Rotate refresh token with replay protection
+ */
+declare function rotateRefreshToken(oldRefreshToken: string, options: RotateRefreshTokenOptions): Promise<RefreshTokenRotationResult>;
+/**
+ * Timing-safe string comparison
+ */
+declare function timingSafeCompare(a: string, b: string): boolean;
+
+/**
+ * Argon2id password hashing with secure defaults
+ */
+declare function hashPassword(password: string): Promise<string>;
+declare function verifyPassword(password: string, hash: string): Promise<boolean>;
+declare function needsRehash(hash: string): Promise<boolean>;
+
+/**
+ * API key generation and verification utilities
+ */
+
+/**
+ * Generate a cryptographically secure API key
+ * @param options - Generation options
+ * @returns API key with optional prefix
+ */
+declare function generateApiKey(options?: GenerateApiKeyOptions): string;
+/**
+ * Hash an API key for storage
+ * @param apiKey - Plain API key
+ * @returns Hashed key (hex encoded)
+ */
+declare function hashApiKey(apiKey: string): string;
+/**
+ * Verify an API key against a stored hash
+ * @param apiKey - Plain API key
+ * @param hash - Stored hash
+ * @returns True if key matches hash
+ */
+declare function verifyApiKey(apiKey: string, hash: string): boolean;
+/**
+ * Extract prefix from an API key
+ * @param apiKey - API key with potential prefix
+ * @returns Prefix or empty string
+ */
+declare function extractPrefix(apiKey: string): string;
+
+/**
+ * Opaque token generation for session identifiers
+ */
+/**
+ * Generate a cryptographically secure opaque token
+ * @returns Base64url encoded token
+ */
+declare function generateOpaqueToken(): string;
+/**
+ * Hash an opaque token for storage
+ * @param token - Plain opaque token
+ * @returns Hashed token (hex encoded)
+ */
+declare function hashOpaqueToken(token: string): string;
+
+/**
+ * TOTP (Time-based One-Time Password) implementation (RFC 6238)
+ */
+
+/**
+ * Generate a TOTP secret
+ * @returns Base32 encoded secret
+ */
+declare function generateTOTPSecret(): string;
+/**
+ * Generate a TOTP code
+ * @param secret - Base32 encoded secret
+ * @param options - TOTP options
+ * @returns 6-digit TOTP code
+ */
+declare function generateTOTP(secret: string, options?: TOTPOptions): string;
+/**
+ * Verify a TOTP code
+ * @param code - User-provided code
+ * @param secret - Base32 encoded secret
+ * @param options - TOTP options
+ * @returns Verification result with delta
+ */
+declare function verifyTOTP(code: string, secret: string, options?: TOTPOptions): TOTPVerificationResult;
+
+/**
+ * HMAC request signing and verification
+ */
+/**
+ * Sign a payload with HMAC
+ * @param payload - Data to sign (string or object)
+ * @param secret - Signing secret
+ * @param algorithm - HMAC algorithm (default: sha256)
+ * @returns Hex-encoded signature
+ */
+declare function signPayload(payload: string | Record<string, unknown>, secret: string, algorithm?: string): string;
+/**
+ * Verify a payload signature
+ * @param payload - Data to verify
+ * @param signature - Expected signature
+ * @param secret - Signing secret
+ * @param algorithm - HMAC algorithm (default: sha256)
+ * @returns True if signature is valid
+ */
+declare function verifySignature(payload: string | Record<string, unknown>, signature: string, secret: string, algorithm?: string): boolean;
+/**
+ * Sign a request with timestamp to prevent replay attacks
+ * @param payload - Request data
+ * @param secret - Signing secret
+ * @param timestamp - Unix timestamp (default: current time)
+ * @returns Object with signature and timestamp
+ */
+declare function signRequest(payload: string | Record<string, unknown>, secret: string, timestamp?: number): {
+    signature: string;
+    timestamp: number;
+};
+/**
+ * Verify a signed request with timestamp validation
+ * @param payload - Request data
+ * @param signature - Request signature
+ * @param timestamp - Request timestamp
+ * @param secret - Signing secret
+ * @param maxAge - Maximum age in seconds (default: 300)
+ * @returns True if signature and timestamp are valid
+ */
+declare function verifyRequest(payload: string | Record<string, unknown>, signature: string, timestamp: number, secret: string, maxAge?: number): boolean;
+
+/**
+ * Cookie configuration helpers
+ */
+
+/**
+ * Get secure cookie defaults for production
+ */
+declare function getSecureCookieDefaults(isProduction?: boolean): Partial<CookieOptions>;
+/**
+ * Generate Set-Cookie header value
+ */
+declare function serializeCookie(name: string, value: string, options: CookieOptions): string;
+/**
+ * Parse Cookie header value
+ */
+declare function parseCookie(cookieHeader: string): Record<string, string>;
+/**
+ * Create a cookie deletion header
+ */
+declare function deleteCookie(name: string, options?: Partial<CookieOptions>): string;
+
+/**
+ * Key provider implementations for multi-tenant JWT signing
+ */
+
+/**
+ * Simple in-memory key provider for single-tenant applications
+ */
+declare class SimpleKeyProvider implements KeyProvider {
+    private signingKey;
+    private verificationKey;
+    constructor(secret: string, algorithm?: 'HS256' | 'RS256', kid?: string);
+    getSigningKey(_kid?: string): Promise<SigningKey>;
+    getVerificationKey(_kid: string): Promise<VerificationKey>;
+}
+/**
+ * Rotating key provider with multiple keys
+ */
+declare class RotatingKeyProvider implements KeyProvider {
+    private keys;
+    private currentKid;
+    constructor(initialKey: {
+        kid: string;
+        secret: string;
+        algorithm: 'HS256' | 'RS256';
+    });
+    /**
+     * Add a new key to the rotation
+     */
+    addKey(kid: string, secret: string, algorithm: 'HS256' | 'RS256'): void;
+    /**
+     * Set the current signing key
+     */
+    setCurrentKey(kid: string): void;
+    /**
+     * Remove an old key from rotation
+     */
+    removeKey(kid: string): void;
+    getSigningKey(kid?: string): Promise<SigningKey>;
+    getVerificationKey(kid: string): Promise<VerificationKey>;
+    /**
+     * Get all available key IDs
+     */
+    getKeyIds(): string[];
+}
+/**
+ * Multi-tenant key provider
+ */
+declare class MultiTenantKeyProvider implements KeyProvider {
+    private tenants;
+    constructor();
+    /**
+     * Register a tenant with its key provider
+     */
+    registerTenant(tenantId: string, keyProvider: KeyProvider): void;
+    /**
+     * Unregister a tenant
+     */
+    unregisterTenant(tenantId: string): void;
+    getSigningKey(kid?: string): Promise<SigningKey>;
+    getVerificationKey(kid: string): Promise<VerificationKey>;
+}
+
+export { type CookieOptions, type GenerateApiKeyOptions, type InstrumentationAdapter, type JWTPayload, type KeyProvider, MultiTenantKeyProvider, type RefreshTokenRotationResult, type RotateRefreshTokenOptions, RotatingKeyProvider, type SecurityEventHook, type SignAccessTokenOptions, type SigningKey, SimpleKeyProvider, type TOTPOptions, type TOTPVerificationResult, type VerificationKey, type VerifyAccessTokenOptions, deleteCookie, extractPrefix, generateApiKey, generateOpaqueToken, generateTOTP, generateTOTPSecret, getSecureCookieDefaults, hashApiKey, hashOpaqueToken, hashPassword, needsRehash, parseCookie, rotateRefreshToken, serializeCookie, signAccessToken, signPayload, signRequest, timingSafeCompare, verifyAccessToken, verifyApiKey, verifyPassword, verifyRequest, verifySignature, verifyTOTP };

package/dist/index.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Core type definitions for Tungsten authentication primitives
+ */
+/**
+ * Key provider abstraction for multi-tenant JWT signing/verification
+ */
+interface KeyProvider {
+    /**
+     * Get signing key for JWT creation
+     * @param kid - Optional key ID for rotation
+     */
+    getSigningKey(kid?: string): Promise<SigningKey>;
+    /**
+     * Get verification key for JWT validation
+     * @param kid - Key ID from JWT header
+     */
+    getVerificationKey(kid: string): Promise<VerificationKey>;
+}
+/**
+ * Signing key for JWT creation
+ */
+interface SigningKey {
+    kid: string;
+    algorithm: 'HS256' | 'RS256';
+    key: string | Uint8Array;
+}
+/**
+ * Verification key for JWT validation
+ */
+interface VerificationKey {
+    algorithm: 'HS256' | 'RS256';
+    key: string | Uint8Array;
+}
+/**
+ * JWT payload structure
+ */
+interface JWTPayload {
+    sub: string;
+    iat?: number;
+    exp?: number;
+    iss?: string;
+    aud?: string | string[];
+    jti?: string;
+    [key: string]: unknown;
+}
+/**
+ * Options for signing access tokens
+ */
+interface SignAccessTokenOptions {
+    expiresIn: string | number;
+    issuer?: string;
+    audience?: string | string[];
+    keyProvider: KeyProvider;
+    kid?: string;
+}
+/**
+ * Options for verifying access tokens
+ */
+interface VerifyAccessTokenOptions {
+    keyProvider: KeyProvider;
+    issuer?: string;
+    audience?: string | string[];
+    clockTolerance?: number;
+}
+/**
+ * Options for refresh token rotation
+ */
+interface RotateRefreshTokenOptions {
+    keyProvider: KeyProvider;
+    onTokenReused?: (jti: string) => Promise<void>;
+}
+/**
+ * Result of refresh token rotation
+ */
+interface RefreshTokenRotationResult {
+    accessToken: string;
+    refreshToken: string;
+    payload: JWTPayload;
+}
+/**
+ * Options for API key generation
+ */
+interface GenerateApiKeyOptions {
+    prefix?: string;
+    length?: number;
+}
+/**
+ * Security event hook for monitoring
+ */
+interface SecurityEventHook {
+    onTokenReused?(jti: string, metadata: Record<string, unknown>): Promise<void>;
+    onTokenExpired?(jti: string, metadata: Record<string, unknown>): Promise<void>;
+    onInvalidSignature?(metadata: Record<string, unknown>): Promise<void>;
+    onPasswordHashingFailure?(error: Error): Promise<void>;
+}
+/**
+ * Instrumentation adapter for metrics
+ */
+interface InstrumentationAdapter {
+    recordTokenGeneration(duration: number, metadata: Record<string, unknown>): void;
+    recordTokenVerification(duration: number, success: boolean, metadata: Record<string, unknown>): void;
+    recordPasswordHashing(duration: number, metadata: Record<string, unknown>): void;
+    recordPasswordVerification(duration: number, success: boolean): void;
+}
+/**
+ * Cookie configuration options
+ */
+interface CookieOptions {
+    name: string;
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    maxAge?: number;
+}
+/**
+ * TOTP configuration options
+ */
+interface TOTPOptions {
+    period?: number;
+    digits?: number;
+    algorithm?: 'SHA1' | 'SHA256' | 'SHA512';
+    window?: number;
+}
+/**
+ * TOTP verification result
+ */
+interface TOTPVerificationResult {
+    valid: boolean;
+    delta?: number;
+}
+
+/**
+ * JWT access and refresh token utilities with HS256/RS256 support
+ */
+
+/**
+ * Sign an access token with JWT
+ */
+declare function signAccessToken(payload: JWTPayload, options: SignAccessTokenOptions): Promise<string>;
+/**
+ * Verify an access token
+ */
+declare function verifyAccessToken(token: string, options: VerifyAccessTokenOptions): Promise<JWTPayload>;
+/**
+ * Rotate refresh token with replay protection
+ */
+declare function rotateRefreshToken(oldRefreshToken: string, options: RotateRefreshTokenOptions): Promise<RefreshTokenRotationResult>;
+/**
+ * Timing-safe string comparison
+ */
+declare function timingSafeCompare(a: string, b: string): boolean;
+
+/**
+ * Argon2id password hashing with secure defaults
+ */
+declare function hashPassword(password: string): Promise<string>;
+declare function verifyPassword(password: string, hash: string): Promise<boolean>;
+declare function needsRehash(hash: string): Promise<boolean>;
+
+/**
+ * API key generation and verification utilities
+ */
+
+/**
+ * Generate a cryptographically secure API key
+ * @param options - Generation options
+ * @returns API key with optional prefix
+ */
+declare function generateApiKey(options?: GenerateApiKeyOptions): string;
+/**
+ * Hash an API key for storage
+ * @param apiKey - Plain API key
+ * @returns Hashed key (hex encoded)
+ */
+declare function hashApiKey(apiKey: string): string;
+/**
+ * Verify an API key against a stored hash
+ * @param apiKey - Plain API key
+ * @param hash - Stored hash
+ * @returns True if key matches hash
+ */
+declare function verifyApiKey(apiKey: string, hash: string): boolean;
+/**
+ * Extract prefix from an API key
+ * @param apiKey - API key with potential prefix
+ * @returns Prefix or empty string
+ */
+declare function extractPrefix(apiKey: string): string;
+
+/**
+ * Opaque token generation for session identifiers
+ */
+/**
+ * Generate a cryptographically secure opaque token
+ * @returns Base64url encoded token
+ */
+declare function generateOpaqueToken(): string;
+/**
+ * Hash an opaque token for storage
+ * @param token - Plain opaque token
+ * @returns Hashed token (hex encoded)
+ */
+declare function hashOpaqueToken(token: string): string;
+
+/**
+ * TOTP (Time-based One-Time Password) implementation (RFC 6238)
+ */
+
+/**
+ * Generate a TOTP secret
+ * @returns Base32 encoded secret
+ */
+declare function generateTOTPSecret(): string;
+/**
+ * Generate a TOTP code
+ * @param secret - Base32 encoded secret
+ * @param options - TOTP options
+ * @returns 6-digit TOTP code
+ */
+declare function generateTOTP(secret: string, options?: TOTPOptions): string;
+/**
+ * Verify a TOTP code
+ * @param code - User-provided code
+ * @param secret - Base32 encoded secret
+ * @param options - TOTP options
+ * @returns Verification result with delta
+ */
+declare function verifyTOTP(code: string, secret: string, options?: TOTPOptions): TOTPVerificationResult;
+
+/**
+ * HMAC request signing and verification
+ */
+/**
+ * Sign a payload with HMAC
+ * @param payload - Data to sign (string or object)
+ * @param secret - Signing secret
+ * @param algorithm - HMAC algorithm (default: sha256)
+ * @returns Hex-encoded signature
+ */
+declare function signPayload(payload: string | Record<string, unknown>, secret: string, algorithm?: string): string;
+/**
+ * Verify a payload signature
+ * @param payload - Data to verify
+ * @param signature - Expected signature
+ * @param secret - Signing secret
+ * @param algorithm - HMAC algorithm (default: sha256)
+ * @returns True if signature is valid
+ */
+declare function verifySignature(payload: string | Record<string, unknown>, signature: string, secret: string, algorithm?: string): boolean;
+/**
+ * Sign a request with timestamp to prevent replay attacks
+ * @param payload - Request data
+ * @param secret - Signing secret
+ * @param timestamp - Unix timestamp (default: current time)
+ * @returns Object with signature and timestamp
+ */
+declare function signRequest(payload: string | Record<string, unknown>, secret: string, timestamp?: number): {
+    signature: string;
+    timestamp: number;
+};
+/**
+ * Verify a signed request with timestamp validation
+ * @param payload - Request data
+ * @param signature - Request signature
+ * @param timestamp - Request timestamp
+ * @param secret - Signing secret
+ * @param maxAge - Maximum age in seconds (default: 300)
+ * @returns True if signature and timestamp are valid
+ */
+declare function verifyRequest(payload: string | Record<string, unknown>, signature: string, timestamp: number, secret: string, maxAge?: number): boolean;
+
+/**
+ * Cookie configuration helpers
+ */
+
+/**
+ * Get secure cookie defaults for production
+ */
+declare function getSecureCookieDefaults(isProduction?: boolean): Partial<CookieOptions>;
+/**
+ * Generate Set-Cookie header value
+ */
+declare function serializeCookie(name: string, value: string, options: CookieOptions): string;
+/**
+ * Parse Cookie header value
+ */
+declare function parseCookie(cookieHeader: string): Record<string, string>;
+/**
+ * Create a cookie deletion header
+ */
+declare function deleteCookie(name: string, options?: Partial<CookieOptions>): string;
+
+/**
+ * Key provider implementations for multi-tenant JWT signing
+ */
+
+/**
+ * Simple in-memory key provider for single-tenant applications
+ */
+declare class SimpleKeyProvider implements KeyProvider {
+    private signingKey;
+    private verificationKey;
+    constructor(secret: string, algorithm?: 'HS256' | 'RS256', kid?: string);
+    getSigningKey(_kid?: string): Promise<SigningKey>;
+    getVerificationKey(_kid: string): Promise<VerificationKey>;
+}
+/**
+ * Rotating key provider with multiple keys
+ */
+declare class RotatingKeyProvider implements KeyProvider {
+    private keys;
+    private currentKid;
+    constructor(initialKey: {
+        kid: string;
+        secret: string;
+        algorithm: 'HS256' | 'RS256';
+    });
+    /**
+     * Add a new key to the rotation
+     */
+    addKey(kid: string, secret: string, algorithm: 'HS256' | 'RS256'): void;
+    /**
+     * Set the current signing key
+     */
+    setCurrentKey(kid: string): void;
+    /**
+     * Remove an old key from rotation
+     */
+    removeKey(kid: string): void;
+    getSigningKey(kid?: string): Promise<SigningKey>;
+    getVerificationKey(kid: string): Promise<VerificationKey>;
+    /**
+     * Get all available key IDs
+     */
+    getKeyIds(): string[];
+}
+/**
+ * Multi-tenant key provider
+ */
+declare class MultiTenantKeyProvider implements KeyProvider {
+    private tenants;
+    constructor();
+    /**
+     * Register a tenant with its key provider
+     */
+    registerTenant(tenantId: string, keyProvider: KeyProvider): void;
+    /**
+     * Unregister a tenant
+     */
+    unregisterTenant(tenantId: string): void;
+    getSigningKey(kid?: string): Promise<SigningKey>;
+    getVerificationKey(kid: string): Promise<VerificationKey>;
+}
+
+export { type CookieOptions, type GenerateApiKeyOptions, type InstrumentationAdapter, type JWTPayload, type KeyProvider, MultiTenantKeyProvider, type RefreshTokenRotationResult, type RotateRefreshTokenOptions, RotatingKeyProvider, type SecurityEventHook, type SignAccessTokenOptions, type SigningKey, SimpleKeyProvider, type TOTPOptions, type TOTPVerificationResult, type VerificationKey, type VerifyAccessTokenOptions, deleteCookie, extractPrefix, generateApiKey, generateOpaqueToken, generateTOTP, generateTOTPSecret, getSecureCookieDefaults, hashApiKey, hashOpaqueToken, hashPassword, needsRehash, parseCookie, rotateRefreshToken, serializeCookie, signAccessToken, signPayload, signRequest, timingSafeCompare, verifyAccessToken, verifyApiKey, verifyPassword, verifyRequest, verifySignature, verifyTOTP };