@frontmcp/utils 0.0.1 → 0.7.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.0.1
+
+- Initial release
+- Extracted utilities from @frontmcp/sdk, @frontmcp/cli, and @frontmcp/adapters
+- Added naming utilities: splitWords, toCase, sepFor, shortHash, ensureMaxLen, idFromString
+- Added URI utilities: isValidMcpUri, extractUriScheme, isValidMcpUriTemplate, parseUriTemplate, matchUriTemplate, expandUriTemplate, extractTemplateParams, isUriTemplate
+- Added path utilities: trimSlashes, joinPath
+- Added content utilities: sanitizeToJson, inferMimeType
+- Added HTTP utilities: validateBaseUrl
+- Added FS utilities: fileExists, readJSON, writeJSON, ensureDir, isDirEmpty, runCmd

package/README.md

@@ -0,0 +1,110 @@
+# @frontmcp/utils
+
+Shared utility functions for the FrontMCP ecosystem. Provides generic, protocol-neutral utilities for string manipulation, URI handling, path operations, content processing, and more.
+
+## Installation
+
+```bash
+npm install @frontmcp/utils
+# or
+yarn add @frontmcp/utils
+```
+
+## Features
+
+### Naming Utilities
+
+```typescript
+import { splitWords, toCase, shortHash, ensureMaxLen, idFromString } from '@frontmcp/utils';
+
+// Split strings into words (handles camelCase, PascalCase, delimiters)
+splitWords('myFunctionName'); // ['my', 'Function', 'Name']
+
+// Convert to different cases
+toCase(['my', 'function'], 'snake'); // 'my_function'
+toCase(['my', 'function'], 'kebab'); // 'my-function'
+toCase(['my', 'function'], 'camel'); // 'myFunction'
+
+// Generate short hashes
+shortHash('some-string'); // '6-char hex hash'
+
+// Truncate with hash for uniqueness
+ensureMaxLen('very-long-name-that-exceeds-limit', 20);
+
+// Sanitize to valid ID
+idFromString('My Function Name!'); // 'My-Function-Name'
+```
+
+### URI Utilities
+
+```typescript
+import {
+  isValidMcpUri,
+  extractUriScheme,
+  parseUriTemplate,
+  matchUriTemplate,
+  expandUriTemplate,
+} from '@frontmcp/utils';
+
+// Validate RFC 3986 URIs
+isValidMcpUri('https://example.com/resource'); // true
+isValidMcpUri('/path/without/scheme'); // false
+
+// Extract scheme
+extractUriScheme('https://example.com'); // 'https'
+
+// RFC 6570 URI Templates
+const params = matchUriTemplate('users/{userId}/posts/{postId}', 'users/123/posts/456');
+// { userId: '123', postId: '456' }
+
+expandUriTemplate('users/{userId}', { userId: '123' }); // 'users/123'
+```
+
+### Path Utilities
+
+```typescript
+import { trimSlashes, joinPath } from '@frontmcp/utils';
+
+trimSlashes('/path/to/resource/'); // 'path/to/resource'
+joinPath('api', 'v1', 'users'); // '/api/v1/users'
+```
+
+### Content Utilities
+
+```typescript
+import { sanitizeToJson, inferMimeType } from '@frontmcp/utils';
+
+// Sanitize values to JSON-safe objects
+sanitizeToJson({ date: new Date(), fn: () => {} }); // { date: '2024-01-01T00:00:00.000Z' }
+
+// Infer MIME type from extension
+inferMimeType('document.json'); // 'application/json'
+inferMimeType('image.png'); // 'image/png'
+```
+
+### HTTP Utilities
+
+```typescript
+import { validateBaseUrl } from '@frontmcp/utils';
+
+// Validate and normalize URLs
+const url = validateBaseUrl('https://api.example.com');
+// Throws for invalid URLs or unsupported protocols (file://, javascript:)
+```
+
+### File System Utilities
+
+```typescript
+import { fileExists, readJSON, writeJSON, ensureDir, isDirEmpty } from '@frontmcp/utils';
+
+// Async file operations
+await fileExists('/path/to/file');
+await readJSON<Config>('/path/to/config.json');
+await writeJSON('/path/to/output.json', { key: 'value' });
+await ensureDir('/path/to/directory');
+await isDirEmpty('/path/to/directory');
+```
+
+## License
+
+Apache-2.0

package/content/content.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Content utilities for JSON sanitization and MIME type inference.
+ *
+ * Provides functions for safely converting JavaScript values to JSON-compatible
+ * formats and inferring content types from file extensions.
+ */
+/**
+ * Sanitize arbitrary JS values into JSON-safe objects.
+ *
+ * Handles:
+ * - Functions and symbols → dropped (undefined)
+ * - BigInt → string
+ * - Date → ISO string
+ * - Error → { name, message, stack }
+ * - Map → plain object
+ * - Set → array
+ * - Circular references → dropped (undefined)
+ *
+ * @param value - Any JavaScript value
+ * @returns JSON-safe version of the value
+ *
+ * @example
+ * sanitizeToJson({ date: new Date(), fn: () => {} })
+ * // { date: '2024-01-01T00:00:00.000Z' }
+ *
+ * sanitizeToJson(new Map([['key', 'value']]))
+ * // { key: 'value' }
+ */
+export declare function sanitizeToJson(value: unknown): unknown;
+/**
+ * Infer MIME type from file extension or content.
+ *
+ * @param uri - The URI or filename to infer from
+ * @param content - Optional content to help infer type
+ * @returns Inferred MIME type, defaults to 'text/plain'
+ *
+ * @example
+ * inferMimeType('document.json') // 'application/json'
+ * inferMimeType('image.png') // 'image/png'
+ * inferMimeType('unknown', '{"key": "value"}') // 'application/json'
+ * inferMimeType('unknown', '<html>') // 'text/html'
+ */
+export declare function inferMimeType(uri: string, content?: unknown): string;

package/content/index.d.ts

@@ -0,0 +1 @@
+export { sanitizeToJson, inferMimeType } from './content';

package/crypto/browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Browser Crypto Provider
+ *
+ * Implementation using @noble/hashes and @noble/ciphers for cross-platform support.
+ * These libraries work in both Node.js and browsers.
+ */
+import type { CryptoProvider } from './types';
+/**
+ * Browser-compatible crypto provider using @noble libraries.
+ */
+export declare const browserCrypto: CryptoProvider;

package/crypto/encrypted-blob.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Encrypted Blob Utilities
+ *
+ * Higher-level helpers for encrypting/decrypting JSON-serializable data
+ * using AES-256-GCM. All operations are synchronous.
+ *
+ * @module @frontmcp/utils/crypto
+ */
+import type { EncBlob } from './types';
+export type EncryptedBlob = EncBlob;
+/**
+ * Error thrown when encrypted blob operations fail.
+ */
+export declare class EncryptedBlobError extends Error {
+    constructor(message: string);
+}
+/**
+ * Encrypt a value using AES-256-GCM.
+ *
+ * @param data - Value to encrypt (will be JSON serialized)
+ * @param key - 32-byte encryption key
+ * @returns Encrypted blob with base64url-encoded fields
+ * @throws EncryptedBlobError if key is invalid or data cannot be serialized
+ *
+ * @example
+ * ```typescript
+ * const key = hkdfSha256(ikm, salt, info, 32);
+ * const blob = encryptValue({ secret: 'data' }, key);
+ * // blob.alg === 'A256GCM'
+ * // blob.iv, blob.tag, blob.data are base64url strings
+ * ```
+ */
+export declare function encryptValue<T>(data: T, key: Uint8Array): EncryptedBlob;
+/**
+ * Decrypt an encrypted blob and parse the JSON result.
+ *
+ * @param blob - Encrypted blob to decrypt
+ * @param key - 32-byte encryption key (must match encryption key)
+ * @returns Decrypted and parsed value
+ * @throws EncryptedBlobError if decryption or parsing fails
+ *
+ * @example
+ * ```typescript
+ * const decrypted = decryptValue<MyType>(blob, key);
+ * ```
+ */
+export declare function decryptValue<T>(blob: EncryptedBlob, key: Uint8Array): T;
+/**
+ * Try to decrypt an encrypted blob, returning null on failure.
+ *
+ * @param blob - Encrypted blob to decrypt
+ * @param key - 32-byte encryption key
+ * @returns Decrypted value or null if decryption/parsing fails
+ *
+ * @example
+ * ```typescript
+ * const result = tryDecryptValue<MyType>(blob, key);
+ * if (result !== null) {
+ *   // Use decrypted data
+ * }
+ * ```
+ */
+export declare function tryDecryptValue<T>(blob: EncryptedBlob, key: Uint8Array): T | null;
+/**
+ * Serialize an encrypted blob to a JSON string for storage.
+ *
+ * @param blob - Encrypted blob to serialize
+ * @returns JSON string representation
+ *
+ * @example
+ * ```typescript
+ * const blob = encryptValue(data, key);
+ * const str = serializeBlob(blob);
+ * // Store str in database/redis/etc.
+ * ```
+ */
+export declare function serializeBlob(blob: EncryptedBlob): string;
+/**
+ * Deserialize a JSON string back to an encrypted blob.
+ *
+ * @param str - JSON string to deserialize
+ * @returns Encrypted blob
+ * @throws EncryptedBlobError if string is not a valid encrypted blob
+ *
+ * @example
+ * ```typescript
+ * const blob = deserializeBlob(storedString);
+ * const data = decryptValue(blob, key);
+ * ```
+ */
+export declare function deserializeBlob(str: string): EncryptedBlob;
+/**
+ * Try to deserialize a JSON string to an encrypted blob, returning null on failure.
+ *
+ * @param str - JSON string to deserialize
+ * @returns Encrypted blob or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const blob = tryDeserializeBlob(storedString);
+ * if (blob !== null) {
+ *   const data = tryDecryptValue(blob, key);
+ * }
+ * ```
+ */
+export declare function tryDeserializeBlob(str: string): EncryptedBlob | null;
+/**
+ * Check if a value is a valid encrypted blob structure.
+ *
+ * @param value - Value to check
+ * @returns true if value is a valid EncryptedBlob
+ */
+export declare function isValidEncryptedBlob(value: unknown): value is EncryptedBlob;
+/**
+ * Encrypt and serialize in one step.
+ *
+ * @param data - Value to encrypt
+ * @param key - 32-byte encryption key
+ * @returns JSON string of encrypted blob
+ *
+ * @example
+ * ```typescript
+ * const encrypted = encryptAndSerialize({ secret: 'data' }, key);
+ * // Store encrypted string
+ * ```
+ */
+export declare function encryptAndSerialize<T>(data: T, key: Uint8Array): string;
+/**
+ * Deserialize and decrypt in one step.
+ *
+ * @param str - JSON string of encrypted blob
+ * @param key - 32-byte encryption key
+ * @returns Decrypted and parsed value
+ * @throws EncryptedBlobError if deserialization or decryption fails
+ *
+ * @example
+ * ```typescript
+ * const data = deserializeAndDecrypt<MyType>(storedString, key);
+ * ```
+ */
+export declare function deserializeAndDecrypt<T>(str: string, key: Uint8Array): T;
+/**
+ * Try to deserialize and decrypt, returning null on any failure.
+ *
+ * @param str - JSON string of encrypted blob
+ * @param key - 32-byte encryption key
+ * @returns Decrypted value or null if any step fails
+ *
+ * @example
+ * ```typescript
+ * const data = tryDeserializeAndDecrypt<MyType>(storedString, key);
+ * if (data !== null) {
+ *   // Use decrypted data
+ * }
+ * ```
+ */
+export declare function tryDeserializeAndDecrypt<T>(str: string, key: Uint8Array): T | null;

package/crypto/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Cross-Platform Crypto Module
+ *
+ * Provides cryptographic operations that work in both Node.js and browser environments.
+ * Uses native crypto in Node.js and @noble/hashes + @noble/ciphers in browsers.
+ */
+import type { CryptoProvider, EncBlob } from './types';
+export { isRsaPssAlg, jwtAlgToNodeAlg } from './jwt-alg';
+/**
+ * Get the crypto provider for the current runtime environment.
+ * Lazily initializes the provider.
+ *
+ * Note: this module intentionally avoids importing any Node-only crypto modules
+ * at module-load time so it can be used in browser builds without pulling them in.
+ */
+export declare function getCrypto(): CryptoProvider;
+export declare function rsaVerify(jwtAlg: string, data: Buffer, publicJwk: JsonWebKey, signature: Buffer): boolean;
+/**
+ * Generate a UUID v4 string.
+ */
+export declare function randomUUID(): string;
+/**
+ * Generate cryptographically secure random bytes.
+ * @param length - Number of bytes to generate (must be a positive integer)
+ * @throws Error if length is not a positive integer
+ */
+export declare function randomBytes(length: number): Uint8Array;
+/**
+ * Compute SHA-256 hash.
+ */
+export declare function sha256(data: string | Uint8Array): Uint8Array;
+/**
+ * Compute SHA-256 hash and return as hex string.
+ */
+export declare function sha256Hex(data: string | Uint8Array): string;
+/**
+ * Compute HMAC-SHA256.
+ */
+export declare function hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array;
+/**
+ * HKDF-SHA256 key derivation (RFC 5869).
+ * @param ikm - Input keying material
+ * @param salt - Salt value (can be empty)
+ * @param info - Context and application specific information
+ * @param length - Length of output keying material in bytes (1 to 8160)
+ * @throws Error if length is not a positive integer or exceeds HKDF limits
+ */
+export declare function hkdfSha256(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array, length: number): Uint8Array;
+/**
+ * Encrypt using AES-256-GCM.
+ * @param key - 32-byte encryption key (AES-256)
+ * @param plaintext - Data to encrypt
+ * @param iv - 12-byte initialization vector (96 bits, recommended for GCM)
+ * @throws Error if key is not 32 bytes or IV is not 12 bytes
+ */
+export declare function encryptAesGcm(key: Uint8Array, plaintext: Uint8Array, iv: Uint8Array): {
+    ciphertext: Uint8Array;
+    tag: Uint8Array;
+};
+/**
+ * Decrypt using AES-256-GCM.
+ * @param key - 32-byte encryption key (AES-256)
+ * @param ciphertext - Encrypted data
+ * @param iv - 12-byte initialization vector (96 bits)
+ * @param tag - 16-byte authentication tag
+ * @throws Error if key is not 32 bytes, IV is not 12 bytes, or tag is not 16 bytes
+ */
+export declare function decryptAesGcm(key: Uint8Array, ciphertext: Uint8Array, iv: Uint8Array, tag: Uint8Array): Uint8Array;
+/**
+ * Constant-time comparison to prevent timing attacks.
+ * @param a - First byte array to compare
+ * @param b - Second byte array to compare
+ * @throws Error if arrays have different lengths
+ */
+export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Convert a Uint8Array to hex string.
+ */
+export declare function bytesToHex(data: Uint8Array): string;
+/**
+ * Encode a Uint8Array to base64url string.
+ * RFC 4648 Section 5: Base64 with URL and filename safe alphabet.
+ */
+export declare function base64urlEncode(data: Uint8Array): string;
+/**
+ * Decode a base64url string to Uint8Array.
+ */
+export declare function base64urlDecode(data: string): Uint8Array;
+/**
+ * Compute SHA-256 hash and return as base64url string.
+ * Commonly used for PKCE code_challenge (S256 method).
+ */
+export declare function sha256Base64url(data: string | Uint8Array): string;
+export type { CryptoProvider, EncBlob };
+export { isNode, isBrowser, assertNode } from './runtime';
+export { type EncryptedBlob, EncryptedBlobError, encryptValue, decryptValue, tryDecryptValue, serializeBlob, deserializeBlob, tryDeserializeBlob, isValidEncryptedBlob, encryptAndSerialize, deserializeAndDecrypt, tryDeserializeAndDecrypt, } from './encrypted-blob';
+export { MIN_CODE_VERIFIER_LENGTH, MAX_CODE_VERIFIER_LENGTH, DEFAULT_CODE_VERIFIER_LENGTH, PkceError, generateCodeVerifier, generateCodeChallenge, verifyCodeChallenge, generatePkcePair, isValidCodeVerifier, isValidCodeChallenge, type PkcePair, } from './pkce';
+export { type SecretData, type SecretPersistenceOptions, type SecretValidationResult, secretDataSchema, validateSecretData, parseSecretData, isSecretPersistenceEnabled, resolveSecretPath, loadSecret, saveSecret, deleteSecret, generateSecret, createSecretData, getOrCreateSecret, clearCachedSecret, isSecretCached, } from './secret-persistence';

package/crypto/jwt-alg.d.ts

@@ -0,0 +1,8 @@
+/**
+ * JWT algorithm helpers.
+ *
+ * This module is intentionally dependency-free (no Node-only imports) so it can be safely re-used
+ * from both browser-compatible and Node-only code.
+ */
+export declare function jwtAlgToNodeAlg(jwtAlg: string): string;
+export declare function isRsaPssAlg(jwtAlg: string): boolean;

package/crypto/node.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Node.js Crypto Provider
+ *
+ * Implementation using Node.js native crypto module.
+ */
+import crypto from 'node:crypto';
+import type { CryptoProvider } from './types';
+export { isRsaPssAlg, jwtAlgToNodeAlg } from './jwt-alg';
+/**
+ * Node.js crypto provider implementation.
+ */
+export declare const nodeCrypto: CryptoProvider;
+/**
+ * RSA JWK structure for public keys
+ */
+export interface RsaJwk {
+    kty: 'RSA';
+    kid: string;
+    alg: string;
+    use: 'sig';
+    n: string;
+    e: string;
+}
+/**
+ * RSA key pair structure
+ */
+export interface RsaKeyPair {
+    /** Private key for signing */
+    privateKey: crypto.KeyObject;
+    /** Public key for verification */
+    publicKey: crypto.KeyObject;
+    /** Public key in JWK format */
+    publicJwk: RsaJwk;
+}
+/**
+ * Generate an RSA key pair with the specified modulus length
+ *
+ * @param modulusLength - Key size in bits (default: 2048, suitable for short-lived OAuth/JWT verification; use 3072+ for longer-term keys)
+ * @param alg - JWT algorithm (default: 'RS256')
+ * @returns RSA key pair with private, public keys and JWK
+ */
+export declare function generateRsaKeyPair(modulusLength?: number, alg?: string): RsaKeyPair;
+/**
+ * Sign data using RSA with the specified algorithm.
+ *
+ * For RSA-PSS (PS256/PS384/PS512), callers must pass appropriate padding/saltLength options.
+ */
+export declare function rsaSign(algorithm: string, data: Buffer, privateKey: crypto.KeyObject, options?: Omit<crypto.SignKeyObjectInput, 'key'>): Buffer;
+export declare function rsaVerify(jwtAlg: string, data: Buffer, publicJwk: JsonWebKey, signature: Buffer): boolean;
+/**
+ * Create a JWT signed with an RSA key
+ *
+ * @param payload - JWT payload
+ * @param privateKey - RSA private key
+ * @param kid - Key ID for the JWT header
+ * @param alg - JWT algorithm (default: 'RS256')
+ * @returns Signed JWT string
+ */
+export declare function createSignedJwt(payload: Record<string, unknown>, privateKey: crypto.KeyObject, kid: string, alg?: string): string;

package/crypto/pkce/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities
+ *
+ * Implements RFC 7636 for secure authorization flows.
+ * Used for webhook callbacks, OAuth flows, and tool approval.
+ *
+ * @module @frontmcp/utils/pkce
+ */
+export { MIN_CODE_VERIFIER_LENGTH, MAX_CODE_VERIFIER_LENGTH, DEFAULT_CODE_VERIFIER_LENGTH, PkceError, generateCodeVerifier, generateCodeChallenge, verifyCodeChallenge, generatePkcePair, isValidCodeVerifier, isValidCodeChallenge, type PkcePair, } from './pkce';

package/crypto/pkce/pkce.d.ts

@@ -0,0 +1,140 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities per RFC 7636
+ *
+ * PKCE is used to secure authorization flows by generating a cryptographically
+ * random code verifier and deriving a code challenge using SHA-256.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7636
+ */
+/**
+ * Minimum length for code verifier per RFC 7636
+ */
+export declare const MIN_CODE_VERIFIER_LENGTH = 43;
+/**
+ * Maximum length for code verifier per RFC 7636
+ */
+export declare const MAX_CODE_VERIFIER_LENGTH = 128;
+/**
+ * Default length for code verifier (64 chars provides ~384 bits of entropy)
+ */
+export declare const DEFAULT_CODE_VERIFIER_LENGTH = 64;
+/**
+ * Error thrown when PKCE parameters are invalid
+ */
+export declare class PkceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Generate a cryptographically random code verifier.
+ *
+ * The code verifier is a high-entropy cryptographic random string used in PKCE.
+ * It should be stored securely and never exposed to external systems.
+ *
+ * @param length - Length of verifier (43-128 chars per RFC 7636, default 64)
+ * @returns Base64url-encoded random string
+ * @throws {PkceError} If length is outside allowed range
+ *
+ * @example
+ * ```typescript
+ * const verifier = generateCodeVerifier(); // 64 chars (default)
+ * const shortVerifier = generateCodeVerifier(43); // minimum length
+ * const longVerifier = generateCodeVerifier(128); // maximum length
+ * ```
+ */
+export declare function generateCodeVerifier(length?: number): string;
+/**
+ * Generate a code challenge from a code verifier using S256 method.
+ *
+ * The code challenge is derived by applying SHA-256 to the code verifier
+ * and base64url encoding the result. This is the only method specified
+ * in RFC 7636 for security-sensitive applications.
+ *
+ * @param codeVerifier - The code verifier string
+ * @returns Base64url-encoded SHA-256 hash of the verifier
+ *
+ * @example
+ * ```typescript
+ * const verifier = generateCodeVerifier();
+ * const challenge = generateCodeChallenge(verifier);
+ * // Send `challenge` to external system, keep `verifier` secret
+ * ```
+ */
+export declare function generateCodeChallenge(codeVerifier: string): string;
+/**
+ * Verify that a code verifier matches a code challenge.
+ *
+ * This validates that SHA256(base64url(code_verifier)) === code_challenge.
+ * Used to verify callback responses in webhook/OAuth flows.
+ *
+ * @param codeVerifier - The original code verifier
+ * @param codeChallenge - The code challenge to verify against
+ * @returns true if the verifier produces the expected challenge
+ *
+ * @example
+ * ```typescript
+ * // When callback arrives with code_verifier
+ * const isValid = verifyCodeChallenge(callbackVerifier, storedChallenge);
+ * if (!isValid) {
+ *   throw new Error('PKCE validation failed');
+ * }
+ * ```
+ */
+export declare function verifyCodeChallenge(codeVerifier: string, codeChallenge: string): boolean;
+/**
+ * Result of generating a PKCE pair
+ */
+export interface PkcePair {
+    /** The secret code verifier (keep secure, never expose externally) */
+    codeVerifier: string;
+    /** The code challenge derived from the verifier (safe to share) */
+    codeChallenge: string;
+}
+/**
+ * Generate a complete PKCE pair (code verifier + code challenge).
+ *
+ * This is a convenience function that generates both values at once.
+ * The code_verifier should be stored securely (e.g., in Redis) while
+ * the code_challenge can be sent to external systems.
+ *
+ * @param length - Length of code verifier (default 64)
+ * @returns Object containing both codeVerifier and codeChallenge
+ * @throws {PkceError} If length is outside allowed range
+ *
+ * @example
+ * ```typescript
+ * const { codeVerifier, codeChallenge } = generatePkcePair();
+ *
+ * // Store verifier in Redis with TTL
+ * await redis.set(`challenge:${codeChallenge}`, {
+ *   verifier: codeVerifier,
+ *   sessionId: session.id,
+ *   expiresAt: Date.now() + 300000, // 5 minutes
+ * });
+ *
+ * // Send challenge to webhook (never send verifier!)
+ * await fetch(webhookUrl, {
+ *   body: JSON.stringify({ code_challenge: codeChallenge, ... })
+ * });
+ * ```
+ */
+export declare function generatePkcePair(length?: number): PkcePair;
+/**
+ * Validate that a string is a valid code verifier.
+ *
+ * Checks that the string:
+ * - Has a length between 43 and 128 characters
+ * - Contains only unreserved characters per RFC 7636 (A-Z, a-z, 0-9, -, ., _, ~)
+ *
+ * @param value - The string to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidCodeVerifier(value: string): boolean;
+/**
+ * Validate that a string is a valid code challenge.
+ *
+ * A valid code challenge is a base64url-encoded SHA-256 hash (43 characters).
+ *
+ * @param value - The string to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidCodeChallenge(value: string): boolean;

package/crypto/runtime.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Runtime Detection
+ *
+ * Utilities for detecting whether code is running in Node.js or browser environment.
+ */
+/**
+ * Check if running in Node.js environment.
+ */
+export declare function isNode(): boolean;
+/**
+ * Check if running in a browser-like environment with Web Crypto API.
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Assert that code is running in Node.js.
+ * @throws Error if not in Node.js environment
+ */
+export declare function assertNode(feature: string): void;