@guren/server 1.0.0-rc.9 → 1.1.0

package/dist/redis/index.d.ts

@@ -0,0 +1,366 @@
+import { R as RateLimitStore, a as RateLimitEntry } from '../client-CKXJLsTe.js';
+export { b as RedisClientOptions, c as createRedisClient } from '../client-CKXJLsTe.js';
+import { Redis } from 'ioredis';
+export { default as Redis, RedisOptions } from 'ioredis';
+import { S as SessionStore, h as SessionData, i as ApiTokenStore, j as ApiToken, O as OAuthStateStore, k as OAuthStatePayload } from '../api-token-BSSCLlFW.js';
+import { P as PasswordResetTokenStore, E as EmailVerificationTokenStore, a as EmailVerificationToken } from '../email-verification-CAeArjui.js';
+import 'hono';
+
+/**
+ * Options for RedisSessionStore.
+ */
+interface RedisSessionStoreOptions {
+    /**
+     * Key prefix for session keys.
+     * @default 'session:'
+     */
+    prefix?: string;
+}
+/**
+ * Redis-backed session store.
+ *
+ * @example
+ * ```ts
+ * import { createRedisClient } from '@guren/server/redis'
+ *
+ * const redis = createRedisClient({ url: process.env.REDIS_URL })
+ * const store = new RedisSessionStore(redis)
+ *
+ * app.use(createSessionMiddleware({ store }))
+ * ```
+ */
+declare class RedisSessionStore implements SessionStore {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: Redis, options?: RedisSessionStoreOptions);
+    /**
+     * Read session data from Redis.
+     */
+    read(id: string): Promise<SessionData | undefined>;
+    /**
+     * Write session data to Redis with TTL.
+     */
+    write(id: string, data: SessionData, ttlSeconds: number): Promise<void>;
+    /**
+     * Delete a session from Redis.
+     */
+    destroy(id: string): Promise<void>;
+    /**
+     * Get all session keys (for debugging/admin purposes).
+     * Note: This uses SCAN to avoid blocking Redis.
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Get the count of sessions (for monitoring).
+     */
+    size(): Promise<number>;
+    /**
+     * Clear all sessions.
+     * Use with caution in production!
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Options for RedisRateLimitStore.
+ */
+interface RedisRateLimitStoreOptions {
+    /**
+     * Key prefix for rate limit keys.
+     * @default 'ratelimit:'
+     */
+    prefix?: string;
+}
+/**
+ * Redis-backed rate limit store using fixed window algorithm.
+ * Uses Lua script for atomic increment operations.
+ *
+ * @example
+ * ```ts
+ * import { createRedisClient } from '@guren/server/redis'
+ *
+ * const redis = createRedisClient({ url: process.env.REDIS_URL })
+ * const store = new RedisRateLimitStore(redis)
+ *
+ * app.use(createRateLimitMiddleware({ store, limit: 100 }))
+ * ```
+ */
+declare class RedisRateLimitStore implements RateLimitStore {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: Redis, options?: RedisRateLimitStoreOptions);
+    /**
+     * Get current rate limit entry for a key.
+     */
+    get(key: string): Promise<RateLimitEntry | null>;
+    /**
+     * Increment the rate limit counter atomically.
+     */
+    increment(key: string, windowMs: number): Promise<RateLimitEntry>;
+    /**
+     * Reset the rate limit for a key.
+     */
+    reset(key: string): Promise<void>;
+    /**
+     * Get all rate limit keys (for debugging/admin purposes).
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Clear all rate limits.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Redis-backed rate limit store using sliding window algorithm.
+ * More accurate than fixed window but slightly more expensive.
+ */
+declare class RedisSlidingWindowRateLimitStore implements RateLimitStore {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: Redis, options?: RedisRateLimitStoreOptions);
+    /**
+     * Get current rate limit entry for a key.
+     */
+    get(key: string): Promise<RateLimitEntry | null>;
+    /**
+     * Increment the rate limit counter using sorted set.
+     * Each request is stored with its timestamp as score.
+     */
+    increment(key: string, windowMs: number): Promise<RateLimitEntry>;
+    /**
+     * Reset the rate limit for a key.
+     */
+    reset(key: string): Promise<void>;
+    /**
+     * Clear all rate limits.
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Options for RedisApiTokenStore.
+ */
+interface RedisApiTokenStoreOptions {
+    /**
+     * Key prefix for token keys.
+     * @default 'apitoken:'
+     */
+    prefix?: string;
+}
+/**
+ * Redis-backed API token store.
+ *
+ * Uses the following key structure:
+ * - `apitoken:{id}` - Token data (hash)
+ * - `apitoken:hash:{hashedToken}` - Maps hash to token ID
+ * - `apitoken:user:{userId}` - Set of token IDs for a user
+ *
+ * @example
+ * ```ts
+ * import { createRedisClient } from '@guren/server/redis'
+ *
+ * const redis = createRedisClient({ url: process.env.REDIS_URL })
+ * const store = new RedisApiTokenStore(redis)
+ *
+ * const { plainTextToken } = await createApiToken(store, {
+ *   name: 'API Token',
+ *   userId: user.id,
+ * })
+ * ```
+ */
+declare class RedisApiTokenStore implements ApiTokenStore {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: Redis, options?: RedisApiTokenStoreOptions);
+    /**
+     * Store a new API token.
+     */
+    store(token: ApiToken): Promise<void>;
+    /**
+     * Find a token by its hashed value.
+     */
+    findByHashedToken(hashedToken: string): Promise<ApiToken | null>;
+    /**
+     * Find all tokens for a user.
+     */
+    findByUserId(userId: string | number): Promise<ApiToken[]>;
+    /**
+     * Delete a token by its ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete all tokens for a user.
+     */
+    deleteForUser(userId: string | number): Promise<void>;
+    /**
+     * Update the last used timestamp.
+     */
+    updateLastUsed(id: string, timestamp: Date): Promise<void>;
+    /**
+     * Find a token by its ID.
+     */
+    private findById;
+    /**
+     * Serialize a token for Redis storage.
+     */
+    private serializeToken;
+    /**
+     * Deserialize a token from Redis storage.
+     */
+    private deserializeToken;
+    /**
+     * Clear all tokens (for testing).
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Options for RedisPasswordResetStore.
+ */
+interface RedisPasswordResetStoreOptions {
+    /**
+     * Key prefix for password reset keys.
+     * @default 'pwreset:'
+     */
+    prefix?: string;
+}
+/**
+ * Redis-backed password reset token store.
+ *
+ * Uses the following key structure:
+ * - `pwreset:{tokenId}` - Token data (JSON with email and expiresAt)
+ * - `pwreset:email:{email}` - Set of token IDs for an email
+ *
+ * @example
+ * ```ts
+ * import { createRedisClient } from '@guren/server/redis'
+ *
+ * const redis = createRedisClient({ url: process.env.REDIS_URL })
+ * const store = new RedisPasswordResetStore(redis)
+ *
+ * const { token } = await createPasswordResetToken(email, store, { expiresIn: 3600000 })
+ * ```
+ */
+declare class RedisPasswordResetStore implements PasswordResetTokenStore {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: Redis, options?: RedisPasswordResetStoreOptions);
+    /**
+     * Store a password reset token.
+     */
+    store(tokenId: string, email: string, expiresAt: Date): Promise<void>;
+    /**
+     * Find a token by its hash.
+     */
+    find(tokenId: string): Promise<{
+        email: string;
+        expiresAt: Date;
+    } | null>;
+    /**
+     * Delete a token by its hash.
+     */
+    delete(tokenId: string): Promise<void>;
+    /**
+     * Delete all tokens for an email.
+     */
+    deleteForEmail(email: string): Promise<void>;
+    /**
+     * Clear all tokens (for testing).
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Options for RedisEmailVerificationStore.
+ */
+interface RedisEmailVerificationStoreOptions {
+    /**
+     * Key prefix for email verification keys.
+     * @default 'emailverify:'
+     */
+    prefix?: string;
+}
+/**
+ * Redis-backed email verification token store.
+ *
+ * Uses the following key structure:
+ * - `emailverify:{tokenId}` - Token data (JSON)
+ * - `emailverify:email:{email}` - Set of token IDs for an email
+ *
+ * @example
+ * ```ts
+ * import { createRedisClient } from '@guren/server/redis'
+ *
+ * const redis = createRedisClient({ url: process.env.REDIS_URL })
+ * const store = new RedisEmailVerificationStore(redis)
+ *
+ * const { token } = await createEmailVerificationToken(email, store, { expiresIn: 86400000 })
+ * ```
+ */
+declare class RedisEmailVerificationStore implements EmailVerificationTokenStore {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: Redis, options?: RedisEmailVerificationStoreOptions);
+    /**
+     * Store an email verification token.
+     */
+    store(token: EmailVerificationToken): Promise<void>;
+    /**
+     * Find a token by its hash.
+     */
+    findByTokenId(tokenId: string): Promise<EmailVerificationToken | null>;
+    /**
+     * Delete a token by its hash.
+     */
+    delete(tokenId: string): Promise<void>;
+    /**
+     * Delete all tokens for an email.
+     */
+    deleteForEmail(email: string): Promise<void>;
+    /**
+     * Clear all tokens (for testing).
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Options for RedisOAuthStateStore.
+ */
+interface RedisOAuthStateStoreOptions {
+    /**
+     * Key prefix for OAuth state keys.
+     * @default 'oauthstate:'
+     */
+    prefix?: string;
+}
+/**
+ * Redis-backed OAuth state store.
+ *
+ * Required in production whenever more than one server process handles
+ * traffic (load balancers, serverless): the default MemoryOAuthStateStore
+ * is per-process, so the callback request may land on a process that never
+ * saw the state. Entries expire automatically via Redis TTL.
+ *
+ * @example
+ * ```ts
+ * import { createOAuthManager } from '@guren/core'
+ * import { createRedisClient, RedisOAuthStateStore } from '@guren/core/redis'
+ *
+ * const redis = createRedisClient({ url: process.env.REDIS_URL })
+ * const oauth = createOAuthManager({ stateStore: new RedisOAuthStateStore(redis) })
+ * ```
+ */
+declare class RedisOAuthStateStore implements OAuthStateStore {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: Redis, options?: RedisOAuthStateStoreOptions);
+    store(stateHash: string, payload: OAuthStatePayload): Promise<void>;
+    find(stateHash: string): Promise<OAuthStatePayload | null>;
+    delete(stateHash: string): Promise<void>;
+    /**
+     * Clear all states (for testing).
+     */
+    clear(): Promise<void>;
+}
+
+export { RedisApiTokenStore, type RedisApiTokenStoreOptions, RedisEmailVerificationStore, type RedisEmailVerificationStoreOptions, RedisOAuthStateStore, type RedisOAuthStateStoreOptions, RedisPasswordResetStore, type RedisPasswordResetStoreOptions, RedisRateLimitStore, type RedisRateLimitStoreOptions, RedisSessionStore, type RedisSessionStoreOptions, RedisSlidingWindowRateLimitStore };