@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/encryption/index.d.ts

@@ -0,0 +1,222 @@
+import { A as AppKeyring, H as HashAlgorithm, P as PasswordHashOptions, d as HmacOptions, R as RandomStringOptions } from '../app-key-CsBfRC_Q.js';
+export { D as DecryptOptions, a as EncryptOptions, b as EncryptedPayload, E as Encrypter, c as EncrypterConfig, e as createEncrypter, f as decrypt, g as deriveAppKey, h as deriveAppKeyring, q as encodeDerivedKey, i as encrypt, j as generateAppKey, k as generateKey, l as getAppKeyringFromEnv, m as getEncrypter, n as normalizeAppKey, p as parseAppKey, o as parsePreviousAppKeys, s as setEncrypter } from '../app-key-CsBfRC_Q.js';
+
+interface SignedMessageClaims {
+    purpose?: string;
+    iat: number;
+    exp?: number;
+    [key: string]: unknown;
+}
+interface SignMessageOptions {
+    purpose?: string;
+    expiresIn?: number;
+}
+interface VerifySignedMessageOptions {
+    purpose?: string;
+    allowExpired?: boolean;
+}
+declare class MessageSigner {
+    private readonly keyring;
+    constructor(keyring: AppKeyring);
+    sign<T extends Record<string, unknown>>(payload: T, options?: SignMessageOptions): string;
+    verify<T extends Record<string, unknown> = Record<string, unknown>>(token: string, options?: VerifySignedMessageOptions): (T & SignedMessageClaims) | null;
+}
+
+interface SignedUrlOptions {
+    expiresIn?: number;
+}
+interface VerifySignedUrlOptions {
+    requireExpiration?: boolean;
+}
+declare function signUrl(value: string, keyring: AppKeyring, options?: SignedUrlOptions): string;
+declare function verifySignedUrl(value: string, keyring: AppKeyring, options?: VerifySignedUrlOptions): boolean;
+
+/**
+ * Hash a value using the specified algorithm.
+ *
+ * @example
+ * ```typescript
+ * hash('hello') // SHA-256 by default
+ * hash('hello', 'sha512')
+ * hash('hello', 'md5')
+ * ```
+ */
+declare function hash(value: string | Buffer, algorithm?: HashAlgorithm, encoding?: 'hex' | 'base64'): string;
+/**
+ * Create an HMAC signature.
+ *
+ * @example
+ * ```typescript
+ * hmac('message', 'secret-key')
+ * hmac('message', 'secret-key', { algorithm: 'sha512' })
+ * ```
+ */
+declare function hmac(value: string | Buffer, key: string | Buffer, options?: HmacOptions): string;
+/**
+ * Verify an HMAC signature.
+ */
+declare function verifyHmac(value: string | Buffer, signature: string, key: string | Buffer, options?: HmacOptions): boolean;
+/**
+ * Create a SHA-256 hash.
+ */
+declare function sha256(value: string | Buffer): string;
+/**
+ * Create a SHA-512 hash.
+ */
+declare function sha512(value: string | Buffer): string;
+/**
+ * Create an MD5 hash (not secure, use only for checksums).
+ */
+declare function md5(value: string | Buffer): string;
+/**
+ * Hash a password using scrypt.
+ *
+ * @example
+ * ```typescript
+ * const hashed = await hashPassword('mypassword')
+ * // Returns: $scrypt$N=16384,r=8,p=1$salt$hash
+ * ```
+ */
+declare function hashPassword(password: string, options?: PasswordHashOptions): Promise<string>;
+/**
+ * Verify a password against a hash.
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyPassword('mypassword', hashedPassword)
+ * ```
+ */
+declare function verifyPassword(password: string, hash: string): Promise<boolean>;
+/**
+ * Check if a password needs to be rehashed (parameters changed).
+ */
+declare function needsRehash(hash: string, options?: PasswordHashOptions): boolean;
+/**
+ * Constant-time string comparison.
+ */
+declare function secureCompare(a: string, b: string): boolean;
+/**
+ * Check if a value matches a hash.
+ */
+declare function check(value: string | Buffer, hash: string, algorithm?: HashAlgorithm): boolean;
+
+/**
+ * Generate a cryptographically secure random string.
+ *
+ * @example
+ * ```typescript
+ * randomString(32) // 32-character alphanumeric string
+ * randomString(16, { charset: 'hex' }) // 16-character hex string
+ * randomString(24, { charset: 'url-safe' }) // URL-safe string
+ * ```
+ */
+declare function randomString(length: number, options?: RandomStringOptions): string;
+/**
+ * Generate random bytes.
+ *
+ * @example
+ * ```typescript
+ * const bytes = random(32) // 32 random bytes
+ * ```
+ */
+declare function random(length: number): Buffer;
+/**
+ * Generate random bytes as hex string.
+ */
+declare function randomHex(length: number): string;
+/**
+ * Generate random bytes as base64 string.
+ */
+declare function randomBase64(length: number): string;
+/**
+ * Generate random bytes as URL-safe base64 string.
+ */
+declare function randomBase64Url(length: number): string;
+/**
+ * Generate a UUID v4.
+ *
+ * @example
+ * ```typescript
+ * const id = uuid() // e.g., '550e8400-e29b-41d4-a716-446655440000'
+ * ```
+ */
+declare function uuid(): string;
+/**
+ * Generate a secure random integer.
+ *
+ * @example
+ * ```typescript
+ * randomInt(1, 100) // Random number between 1 and 100 (inclusive)
+ * ```
+ */
+declare function randomInt(min: number, max: number): number;
+/**
+ * Generate a random token suitable for URLs.
+ *
+ * @example
+ * ```typescript
+ * const token = urlSafeToken(32) // URL-safe 32-character token
+ * ```
+ */
+declare function urlSafeToken(length?: number): string;
+/**
+ * Generate a secure random password.
+ *
+ * @example
+ * ```typescript
+ * const password = generatePassword(16) // Random 16-character password
+ * ```
+ */
+declare function generatePassword(length?: number, options?: {
+    uppercase?: boolean;
+    lowercase?: boolean;
+    numbers?: boolean;
+    symbols?: boolean;
+}): string;
+/**
+ * Generate a random OTP (One-Time Password).
+ *
+ * @example
+ * ```typescript
+ * const otp = generateOtp(6) // e.g., '482901'
+ * ```
+ */
+declare function generateOtp(length?: number): string;
+/**
+ * Generate a random slug-friendly string.
+ *
+ * @example
+ * ```typescript
+ * const slug = generateSlug() // e.g., 'a8b2c4d6e8'
+ * ```
+ */
+declare function generateSlug(length?: number): string;
+/**
+ * Shuffle an array using Fisher-Yates algorithm with secure random.
+ *
+ * @example
+ * ```typescript
+ * const shuffled = shuffle([1, 2, 3, 4, 5])
+ * ```
+ */
+declare function shuffle<T>(array: T[]): T[];
+/**
+ * Pick a random element from an array.
+ *
+ * @example
+ * ```typescript
+ * const item = pick(['a', 'b', 'c']) // Random element
+ * ```
+ */
+declare function pick<T>(array: T[]): T;
+/**
+ * Pick multiple random elements from an array.
+ *
+ * @example
+ * ```typescript
+ * const items = sample(['a', 'b', 'c', 'd'], 2) // Two random elements
+ * ```
+ */
+declare function sample<T>(array: T[], count: number): T[];
+
+export { AppKeyring, HashAlgorithm, HmacOptions, MessageSigner, PasswordHashOptions, RandomStringOptions, type SignMessageOptions, type SignedMessageClaims, type SignedUrlOptions, type VerifySignedMessageOptions, type VerifySignedUrlOptions, check, generateOtp, generatePassword, generateSlug, hash, hashPassword, hmac, md5, needsRehash, pick, random, randomBase64, randomBase64Url, randomHex, randomInt, randomString, sample, secureCompare, sha256, sha512, shuffle, signUrl, urlSafeToken, uuid, verifyHmac, verifyPassword, verifySignedUrl };