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

package/dist/app-key-CsBfRC_Q.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Encryption options.
+ */
+interface EncryptOptions {
+    /**
+     * Whether to serialize the value before encryption.
+     */
+    serialize?: boolean;
+}
+/**
+ * Decryption options.
+ */
+interface DecryptOptions {
+    /**
+     * Whether to deserialize the value after decryption.
+     */
+    deserialize?: boolean;
+}
+/**
+ * Encrypter configuration.
+ */
+interface EncrypterConfig {
+    /**
+     * Encryption key (base64 encoded, 32 bytes for AES-256).
+     */
+    key: string;
+    /**
+     * Previous encryption keys used for decryption fallback during key rotation.
+     */
+    previousKeys?: string[];
+    /**
+     * Encryption cipher to use.
+     */
+    cipher?: 'aes-256-gcm' | 'aes-256-cbc';
+}
+/**
+ * Encrypted payload structure.
+ */
+interface EncryptedPayload {
+    /**
+     * Initialization vector (base64).
+     */
+    iv: string;
+    /**
+     * Encrypted value (base64).
+     */
+    value: string;
+    /**
+     * Authentication tag for GCM mode (base64).
+     */
+    tag?: string;
+    /**
+     * MAC for CBC mode (hex).
+     */
+    mac?: string;
+}
+/**
+ * Hash algorithm options.
+ */
+type HashAlgorithm = 'sha256' | 'sha384' | 'sha512' | 'md5' | 'sha1';
+/**
+ * HMAC options.
+ */
+interface HmacOptions {
+    /**
+     * Hash algorithm to use.
+     */
+    algorithm?: HashAlgorithm;
+    /**
+     * Output encoding.
+     */
+    encoding?: 'hex' | 'base64';
+}
+/**
+ * Password hash options.
+ */
+interface PasswordHashOptions {
+    /**
+     * Memory cost (for scrypt/argon2).
+     */
+    memory?: number;
+    /**
+     * CPU cost (for scrypt/argon2).
+     */
+    cost?: number;
+    /**
+     * Salt length in bytes.
+     */
+    saltLength?: number;
+    /**
+     * Key length in bytes.
+     */
+    keyLength?: number;
+}
+/**
+ * Random string options.
+ */
+interface RandomStringOptions {
+    /**
+     * Character set to use.
+     */
+    charset?: 'alphanumeric' | 'alphabetic' | 'numeric' | 'hex' | 'base64' | 'url-safe';
+}
+
+/**
+ * Encrypter for secure data encryption using AES.
+ *
+ * @example
+ * ```typescript
+ * const encrypter = new Encrypter({ key: 'base64-encoded-32-byte-key' })
+ *
+ * // Encrypt
+ * const encrypted = encrypter.encrypt({ userId: 123, role: 'admin' })
+ *
+ * // Decrypt
+ * const data = encrypter.decrypt(encrypted)
+ * ```
+ */
+declare class Encrypter {
+    /**
+     * Encryption key.
+     */
+    protected key: Buffer;
+    protected previousKeys: Buffer[];
+    /**
+     * Cipher algorithm.
+     */
+    protected cipher: 'aes-256-gcm' | 'aes-256-cbc';
+    constructor(config: EncrypterConfig);
+    /**
+     * Encrypt a value.
+     */
+    encrypt(value: unknown, options?: EncryptOptions): string;
+    /**
+     * Decrypt a value.
+     */
+    decrypt<T = unknown>(payload: string, options?: DecryptOptions): T;
+    /**
+     * Encrypt a string (no serialization).
+     */
+    encryptString(value: string): string;
+    /**
+     * Decrypt a string (no deserialization).
+     */
+    decryptString(payload: string): string;
+    /**
+     * Encrypt using AES-256-GCM.
+     */
+    protected encryptGcm(data: string): string;
+    /**
+     * Decrypt using AES-256-GCM.
+     */
+    protected decryptGcm(payload: EncryptedPayload): string;
+    /**
+     * Encrypt using AES-256-CBC with HMAC.
+     */
+    protected encryptCbc(data: string): string;
+    /**
+     * Decrypt using AES-256-CBC with HMAC verification.
+     */
+    protected decryptCbc(payload: EncryptedPayload): string;
+    /**
+     * Create HMAC for CBC mode.
+     */
+    protected createMac(iv: Buffer, encrypted: Buffer, key?: Buffer): string;
+    /**
+     * Constant-time string comparison.
+     */
+    protected secureCompare(a: string, b: string): boolean;
+    /**
+     * Get the encryption key (base64).
+     */
+    getKey(): string;
+    protected tryDecryptWithKeys(run: (key: Buffer) => string): string;
+}
+/**
+ * Generate a random encryption key.
+ */
+declare function generateKey(): string;
+/**
+ * Create an encrypter instance.
+ */
+declare function createEncrypter(config: EncrypterConfig): Encrypter;
+/**
+ * Set the global encrypter.
+ */
+declare function setEncrypter(encrypter: Encrypter): void;
+/**
+ * Get the global encrypter.
+ */
+declare function getEncrypter(): Encrypter;
+/**
+ * Encrypt a value using the global encrypter.
+ */
+declare function encrypt(value: unknown, options?: EncryptOptions): string;
+/**
+ * Decrypt a value using the global encrypter.
+ */
+declare function decrypt<T = unknown>(payload: string, options?: DecryptOptions): T;
+
+interface AppKeyring {
+    current: Buffer;
+    previous: Buffer[];
+}
+declare function normalizeAppKey(rawKey: string, envName?: string): string;
+declare function parseAppKey(rawKey: string, envName?: string): Buffer;
+declare function parsePreviousAppKeys(rawKeys: string | undefined, envName?: string): Buffer[];
+declare function getAppKeyringFromEnv(env?: NodeJS.ProcessEnv): AppKeyring;
+declare function deriveAppKey(rootKey: Buffer, purpose: string): Buffer;
+declare function deriveAppKeyring(keyring: AppKeyring, purpose: string): AppKeyring;
+declare function encodeDerivedKey(key: Buffer): string;
+declare function generateAppKey(): string;
+
+export { type AppKeyring as A, type DecryptOptions as D, Encrypter as E, type HashAlgorithm as H, type PasswordHashOptions as P, type RandomStringOptions as R, type EncryptOptions as a, type EncryptedPayload as b, type EncrypterConfig as c, type HmacOptions as d, createEncrypter as e, decrypt as f, deriveAppKey as g, deriveAppKeyring as h, encrypt as i, generateAppKey as j, generateKey as k, getAppKeyringFromEnv as l, getEncrypter as m, normalizeAppKey as n, parsePreviousAppKeys as o, parseAppKey as p, encodeDerivedKey as q, setEncrypter as s };

package/dist/auth/index.d.ts

@@ -0,0 +1,418 @@
+import { g as Authenticatable, G as Guard, U as UserProvider, S as Session, e as AuthCredentials, a7 as PasswordHasher, a8 as PlainObject, a9 as Model } from '../api-token-JOif2CtG.js';
+export { c as API_TOKEN_KEY, b as ApiToken, d as ApiTokenStore, aa as AttachContextOptions, a as AuthContext, A as AuthManager, ab as AuthManagerContract, f as AuthManagerOptions, B as BaseUserProvider, h as BearerTokenMiddlewareOptions, i as CreateApiTokenOptions, j as CreateApiTokenResult, k as GuardContext, l as GuardFactory, M as MemoryApiTokenStore, m as MemoryOAuthStateStore, o as ModelUserProvider, p as OAuthAuthorizeOptions, q as OAuthCallbackPayload, O as OAuthManager, r as OAuthManagerOptions, s as OAuthProviderConfig, t as OAuthProviderFactoryInput, u as OAuthStateConfig, v as OAuthStatePayload, w as OAuthStateStore, x as OAuthTokenResult, y as OAuthUserProfile, P as ProviderFactory, E as buildOAuthAuthorizeUrl, F as buildOAuthRedirectUrl, H as createApiToken, I as createBearerTokenMiddleware, J as createDiscordOAuthProviderConfig, K as createGitHubOAuthProviderConfig, L as createGoogleOAuthProviderConfig, N as createOAuthManager, Q as createOAuthState, T as exchangeOAuthCode, V as fetchOAuthUserProfile, W as getApiToken, X as getApiTokenOrFail, Z as getUserApiTokens, _ as parseApiToken, $ as parseOAuthRedirectUrl, a0 as revokeAllApiTokens, a1 as revokeApiToken, a2 as tokenCan, a3 as tokenCanAll, a4 as tokenCanAny, a5 as verifyApiToken, a6 as verifyOAuthState } from '../api-token-JOif2CtG.js';
+import 'hono';
+
+interface SessionGuardOptions {
+    provider: UserProvider;
+    sessionKey?: string;
+    rememberSessionKey?: string;
+    session: Session | undefined;
+}
+declare class SessionGuard<User extends Authenticatable = Authenticatable> implements Guard<User> {
+    private readonly options;
+    private cachedUser;
+    constructor(options: SessionGuardOptions);
+    private get currentSession();
+    private get provider();
+    private sessionKey;
+    private rememberSessionKey;
+    private loadRememberedUser;
+    private resolveUser;
+    check(): Promise<boolean>;
+    guest(): Promise<boolean>;
+    user<T = User>(): Promise<T | null>;
+    id(): Promise<unknown>;
+    private remember;
+    login<T = User>(user: T, remember?: boolean): Promise<void>;
+    logout(): Promise<void>;
+    attempt(credentials: AuthCredentials, remember?: boolean): Promise<boolean>;
+    validate(credentials: AuthCredentials): Promise<User | null>;
+    session<T extends Session = Session>(): T | undefined;
+}
+
+type Argon2Algorithm = 'argon2id' | 'argon2i' | 'argon2d';
+type SupportedAlgorithm = Argon2Algorithm | 'bcrypt';
+interface BunPasswordHasherOptions {
+    /**
+     * Hashing algorithm to use. Defaults to Bun's Argon2id implementation.
+     */
+    algorithm?: SupportedAlgorithm;
+    /** Argon2 memory cost (in kibibytes). */
+    memoryCost?: number;
+    /** Argon2 time cost (number of iterations). */
+    timeCost?: number;
+    /** Bcrypt cost factor (log rounds). */
+    cost?: number;
+}
+declare class ScryptHasher implements PasswordHasher {
+    private readonly algorithm;
+    private readonly memoryCost?;
+    private readonly timeCost?;
+    private readonly cost?;
+    constructor(options?: BunPasswordHasherOptions);
+    hash(plain: string): Promise<string>;
+    verify(hashed: string, plain: string): Promise<boolean>;
+    needsRehash(hashed: string): boolean;
+}
+
+interface NodeHasherOptions {
+    /** scrypt cost parameter (N). Defaults to 16384. */
+    cost?: number;
+    /** scrypt block size (r). Defaults to 8. */
+    memory?: number;
+    /** Salt length in bytes. Defaults to 16. */
+    saltLength?: number;
+    /** Derived key length in bytes. Defaults to 64. */
+    keyLength?: number;
+}
+/**
+ * Node.js-compatible password hasher using crypto.scrypt.
+ * Use this instead of ScryptHasher when deploying to non-Bun runtimes (e.g. AWS Lambda).
+ */
+declare class NodeHasher implements PasswordHasher {
+    private readonly options;
+    constructor(options?: NodeHasherOptions);
+    hash(plain: string): Promise<string>;
+    verify(hashed: string, plain: string): Promise<boolean>;
+    needsRehash(hashed: string): boolean;
+}
+
+declare abstract class AuthenticatableModel<TRecord extends PlainObject = PlainObject> extends Model<TRecord> {
+    static readonly createType: PlainObject & {
+        password?: string;
+        plainPassword?: string;
+    };
+    protected static passwordField: string;
+    protected static passwordHashField: string;
+    protected static passwordHasher: PasswordHasher | null;
+    protected static resolvePasswordField(): string;
+    protected static resolvePasswordHashField(): string;
+    protected static resolvePasswordHasher(): PasswordHasher;
+    protected static preparePersistencePayload(data: PlainObject): Promise<PlainObject>;
+}
+
+/**
+ * Hash a token using SHA-256 or SHA-512.
+ */
+declare function hashToken(token: string, algorithm?: 'sha256' | 'sha512'): string;
+/**
+ * Generate a secure random token.
+ */
+declare function generateToken(length?: number): string;
+/**
+ * Generate a random ID (16 bytes = 32 hex chars).
+ */
+declare function generateId(): string;
+/**
+ * Securely compare two hex strings using timing-safe comparison.
+ */
+declare function secureCompare(a: string, b: string): boolean;
+/**
+ * Securely compare two arbitrary strings using timing-safe comparison.
+ * Unlike secureCompare, this works with any string encoding (UUIDs, tokens, etc.).
+ */
+declare function secureStringCompare(a: string, b: string): boolean;
+/**
+ * Build a URL with token and optional email parameters.
+ */
+declare function buildTokenUrl(baseUrl: string, token: string, email?: string): string;
+/**
+ * Parse a URL to extract token and email parameters.
+ */
+declare function parseTokenUrl(url: string): {
+    token: string | null;
+    email: string | null;
+};
+
+/**
+ * Configuration for password reset tokens.
+ */
+interface PasswordResetConfig {
+    /** Token expiration time in milliseconds (default: 1 hour) */
+    expiresIn?: number;
+    /** Token byte length before encoding (default: 32) */
+    tokenLength?: number;
+}
+/**
+ * Storage interface for password reset tokens.
+ */
+interface PasswordResetTokenStore {
+    /** Store a token ID with associated email and expiration */
+    store(tokenId: string, email: string, expiresAt: Date): Promise<void>;
+    /** Find email by token ID, returns null if not found or expired */
+    find(tokenId: string): Promise<{
+        email: string;
+        expiresAt: Date;
+    } | null>;
+    /** Delete a token ID from storage */
+    delete(tokenId: string): Promise<void>;
+    /** Delete all tokens for an email */
+    deleteForEmail(email: string): Promise<void>;
+}
+/**
+ * In-memory token store for testing and development.
+ */
+declare class MemoryPasswordResetStore implements PasswordResetTokenStore {
+    private tokens;
+    store(tokenId: string, email: string, expiresAt: Date): Promise<void>;
+    find(tokenId: string): Promise<{
+        email: string;
+        expiresAt: Date;
+    } | null>;
+    delete(tokenId: string): Promise<void>;
+    deleteForEmail(email: string): Promise<void>;
+    /** Clear all tokens (useful for testing) */
+    clear(): void;
+}
+/**
+ * Result of creating a password reset token.
+ */
+interface PasswordResetTokenResult {
+    /** The plain-text token to send to the user (via email) */
+    token: string;
+    /** The token ID stored in the backing store */
+    tokenId: string;
+    /** When the token expires */
+    expiresAt: Date;
+}
+/**
+ * Create a password reset token for a user.
+ *
+ * @param email - The user's email address
+ * @param store - The token storage implementation
+ * @param config - Optional configuration
+ * @returns The token result containing plain token and hash
+ */
+declare function createPasswordResetToken(email: string, store: PasswordResetTokenStore, config?: PasswordResetConfig): Promise<PasswordResetTokenResult>;
+/**
+ * Verify a password reset token.
+ *
+ * @param token - The plain-text token from the reset URL
+ * @param store - The token storage implementation
+ * @param config - Optional configuration (must match createPasswordResetToken config)
+ * @returns The email if token is valid, null otherwise
+ */
+declare function verifyPasswordResetToken(token: string, store: PasswordResetTokenStore, _config?: PasswordResetConfig): Promise<string | null>;
+/**
+ * Complete a password reset by updating the user's password and invalidating the token.
+ *
+ * @param token - The plain-text token from the reset URL
+ * @param newPassword - The new password (should be validated by caller)
+ * @param store - The token storage implementation
+ * @param provider - The user provider to look up and update the user
+ * @param updatePassword - Function to update the user's password
+ * @param config - Optional configuration
+ * @returns The user if reset was successful, null if token is invalid
+ */
+declare function completePasswordReset<T extends Authenticatable>(token: string, newPassword: string, store: PasswordResetTokenStore, provider: UserProvider<T>, updatePassword: (user: T, password: string) => Promise<void>, _config?: PasswordResetConfig): Promise<T | null>;
+/**
+ * Build a password reset URL from a base URL and token.
+ */
+declare const buildPasswordResetUrl: typeof buildTokenUrl;
+/**
+ * Parse a password reset URL to extract the token and optional email.
+ */
+declare const parsePasswordResetUrl: typeof parseTokenUrl;
+
+/**
+ * Email verification token data stored in the backing store.
+ * Only the hashed token is stored for security.
+ */
+interface EmailVerificationToken {
+    email: string;
+    tokenId: string;
+    expiresAt: Date;
+    createdAt: Date;
+}
+/**
+ * Store interface for email verification tokens.
+ * Implement this to use database-backed storage.
+ */
+interface EmailVerificationTokenStore {
+    /**
+     * Store a new verification token.
+     */
+    store(token: EmailVerificationToken): Promise<void>;
+    /**
+     * Find a token by its opaque token ID.
+     */
+    findByTokenId(tokenId: string): Promise<EmailVerificationToken | null>;
+    /**
+     * Delete a token by its opaque token ID.
+     */
+    delete(tokenId: string): Promise<void>;
+    /**
+     * Delete all tokens for a given email.
+     */
+    deleteForEmail(email: string): Promise<void>;
+}
+/**
+ * In-memory store for testing purposes.
+ * Do NOT use in production - tokens will be lost on restart.
+ */
+declare class MemoryEmailVerificationStore implements EmailVerificationTokenStore {
+    private tokens;
+    store(token: EmailVerificationToken): Promise<void>;
+    findByTokenId(tokenId: string): Promise<EmailVerificationToken | null>;
+    delete(tokenId: string): Promise<void>;
+    deleteForEmail(email: string): Promise<void>;
+    /**
+     * Clear all tokens (useful for testing).
+     */
+    clear(): void;
+    /**
+     * Get the count of stored tokens (useful for testing).
+     */
+    get size(): number;
+}
+/**
+ * Configuration options for email verification.
+ */
+interface EmailVerificationConfig {
+    /**
+     * Token expiration time in milliseconds.
+     * @default 86400000 (24 hours)
+     */
+    expiresIn?: number;
+    /**
+     * Token byte length (before hex encoding).
+     * @default 32
+     */
+    tokenLength?: number;
+}
+/**
+ * Result of creating an email verification token.
+ */
+interface EmailVerificationTokenResult {
+    /**
+     * The raw token to send to the user via email.
+     * This is NOT stored - only the hash is stored.
+     */
+    token: string;
+    /**
+     * When the token expires.
+     */
+    expiresAt: Date;
+}
+/**
+ * Create a new email verification token.
+ *
+ * @param email - The email address to verify
+ * @param store - Token store implementation
+ * @param config - Optional configuration
+ * @returns The raw token to send via email
+ *
+ * @example
+ * ```ts
+ * const { token, expiresAt } = await createEmailVerificationToken(
+ *   user.email,
+ *   verificationStore
+ * )
+ *
+ * // Send email with verification link
+ * await sendEmail({
+ *   to: user.email,
+ *   subject: 'Verify your email',
+ *   html: `<a href="${buildVerificationUrl(baseUrl, token)}">Verify Email</a>`,
+ * })
+ * ```
+ */
+declare function createEmailVerificationToken(email: string, store: EmailVerificationTokenStore, config?: EmailVerificationConfig): Promise<EmailVerificationTokenResult>;
+/**
+ * Verify an email verification token.
+ *
+ * @param token - The raw token from the verification link
+ * @param store - Token store implementation
+ * @param config - Optional configuration (not currently used, reserved for future)
+ * @returns The email address if valid, null if invalid or expired
+ *
+ * @example
+ * ```ts
+ * const email = await verifyEmailToken(token, verificationStore)
+ *
+ * if (!email) {
+ *   return ctx.json({ error: 'Invalid or expired token' }, 400)
+ * }
+ *
+ * // Mark user as verified
+ * await User.update({ email }, { emailVerifiedAt: new Date() })
+ * ```
+ */
+declare function verifyEmailToken(token: string, store: EmailVerificationTokenStore, _config?: EmailVerificationConfig): Promise<string | null>;
+/**
+ * Complete email verification by consuming the token.
+ *
+ * @param token - The raw token from the verification link
+ * @param store - Token store implementation
+ * @param markVerified - Function to mark the user as verified
+ * @returns The result of markVerified if successful, null if token invalid
+ *
+ * @example
+ * ```ts
+ * const result = await completeEmailVerification(
+ *   token,
+ *   verificationStore,
+ *   async (email) => {
+ *     await User.update({ email }, { emailVerifiedAt: new Date() })
+ *     return User.findByEmail(email)
+ *   }
+ * )
+ *
+ * if (!result) {
+ *   return ctx.json({ error: 'Invalid or expired token' }, 400)
+ * }
+ *
+ * return ctx.redirect('/dashboard')
+ * ```
+ */
+declare function completeEmailVerification<T>(token: string, store: EmailVerificationTokenStore, markVerified: (email: string) => Promise<T>): Promise<T | null>;
+/**
+ * Build a verification URL.
+ */
+declare const buildVerificationUrl: typeof buildTokenUrl;
+/**
+ * Parse a verification URL to extract token and email.
+ */
+declare const parseVerificationUrl: typeof parseTokenUrl;
+/**
+ * Check if a user's email is verified.
+ * Helper function for use with User models.
+ *
+ * @param user - User object with emailVerifiedAt field
+ * @returns true if verified, false otherwise
+ *
+ * @example
+ * ```ts
+ * if (!isEmailVerified(user)) {
+ *   return ctx.redirect('/verify-email')
+ * }
+ * ```
+ */
+declare function isEmailVerified(user: {
+    emailVerifiedAt?: Date | null;
+} | null): boolean;
+/**
+ * Middleware factory to require verified email.
+ *
+ * @param options - Configuration options
+ * @returns Middleware function
+ *
+ * @example
+ * ```ts
+ * router.get('/dashboard', [DashboardController, 'index'],
+ *   requireAuthenticated(),
+ *   requireVerifiedEmail({ redirectTo: '/verify-email' })
+ * )
+ * ```
+ */
+declare function requireVerifiedEmail(options?: {
+    redirectTo?: string;
+    getUser?: (ctx: unknown) => Promise<{
+        emailVerifiedAt?: Date | null;
+    } | null>;
+}): (ctx: {
+    get: (key: string) => unknown;
+    redirect: (url: string) => Response;
+}, next: () => Promise<void>) => Promise<Response | undefined>;
+
+export { AuthCredentials, Authenticatable, AuthenticatableModel, type EmailVerificationConfig, type EmailVerificationToken, type EmailVerificationTokenResult, type EmailVerificationTokenStore, Guard, MemoryEmailVerificationStore, MemoryPasswordResetStore, NodeHasher, PasswordHasher, type PasswordResetConfig, type PasswordResetTokenResult, type PasswordResetTokenStore, ScryptHasher, SessionGuard, UserProvider, buildPasswordResetUrl, buildTokenUrl, buildVerificationUrl, completeEmailVerification, completePasswordReset, createEmailVerificationToken, createPasswordResetToken, generateId, generateToken, hashToken, isEmailVerified, parsePasswordResetUrl, parseTokenUrl, parseVerificationUrl, requireVerifiedEmail, secureCompare, secureStringCompare, verifyEmailToken, verifyPasswordResetToken };