@nauth-toolkit/core 0.1.0

package/src/adapters/fastify.adapter.ts

@@ -0,0 +1,416 @@
+/**
+ * Fastify Framework Adapter
+ *
+ * Adapts NAuth to work with Fastify with proper AsyncLocalStorage support.
+ *
+ * **Context Management:**
+ * - First hook (clientInfo) initializes AsyncLocalStorage context
+ * - Context is stored on request object for subsequent hooks
+ * - Each hook restores context using ContextStorage.enterStore()
+ * - Route handlers MUST use wrapRouteHandler() for context access
+ *
+ * **Why Context Restoration is Needed:**
+ * Unlike Express where middleware runs in a continuous call stack,
+ * Fastify hooks run independently. Each hook invocation loses the
+ * AsyncLocalStorage context, so we store it on the request and restore it.
+ */
+
+import {
+  NAuthAdapter,
+  NAuthRequest,
+  NAuthResponse,
+  NAuthCookieOptions,
+  NAuthRequestAttributes,
+  NAuthMiddlewareHandler,
+  NAuthResponseInterceptorHandler,
+  NAuthRouteHandler,
+  MiddlewareOptions,
+} from '../platform/interfaces';
+import { ContextStorage } from '../utils/context-storage';
+
+// Symbol for storing context on request (avoids property name collisions)
+const NAUTH_CONTEXT_STORE = Symbol.for('nauth.contextStore');
+const NAUTH_ATTRIBUTES = Symbol.for('nauth.attributes');
+
+// ============================================================================
+// Fastify Adapter
+// ============================================================================
+
+/**
+ * Fastify Adapter Implementation
+ *
+ * Provides NAuth integration for Fastify applications.
+ */
+export class FastifyAdapter implements NAuthAdapter {
+  public readonly name = 'FastifyAdapter';
+
+  /**
+   * Register a middleware handler as Fastify hook
+   *
+   * Handles context initialization for first hook and restoration for subsequent hooks.
+   */
+  public registerMiddleware(name: string, handler: NAuthMiddlewareHandler, options?: MiddlewareOptions): FastifyHook {
+    const initializesContext = options?.initializesContext || name === 'clientInfo';
+
+    return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+      // Ensure we have attribute storage
+      this.ensureAttributes(request);
+
+      const nauthReq = new FastifyRequestWrapper(request);
+      const nauthRes = new FastifyResponseWrapper(reply);
+
+      if (initializesContext) {
+        // First hook - initialize context
+        await ContextStorage.run(async () => {
+          // Store context on request for subsequent hooks
+          (request as FastifyRequestWithContext)[NAUTH_CONTEXT_STORE] = ContextStorage.getStore();
+          await this.executeHandler(handler, nauthReq, nauthRes);
+        });
+      } else {
+        // Subsequent hook - restore context
+        const store = (request as FastifyRequestWithContext)[NAUTH_CONTEXT_STORE];
+
+        if (store) {
+          await ContextStorage.enterStore(store, async () => {
+            await this.executeHandler(handler, nauthReq, nauthRes);
+          });
+        } else {
+          // No context available - execute without context
+          // This shouldn't happen if clientInfo runs first
+          await this.executeHandler(handler, nauthReq, nauthRes);
+        }
+      }
+    };
+  }
+
+  /**
+   * Execute handler with proper async flow control
+   */
+  private async executeHandler(handler: NAuthMiddlewareHandler, req: NAuthRequest, res: NAuthResponse): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      const result = handler(req, res, () => {
+        resolve();
+      });
+
+      if (result instanceof Promise) {
+        result.then(() => resolve()).catch(reject);
+      }
+    });
+  }
+
+  /**
+   * Register a response interceptor using Fastify onSend hook
+   *
+   * The onSend hook receives the serialized payload before sending.
+   */
+  public registerResponseInterceptor(handler: NAuthResponseInterceptorHandler): FastifyOnSendHook {
+    return async (request: FastifyRequest, reply: FastifyReply, payload: unknown): Promise<unknown> => {
+      this.ensureAttributes(request);
+
+      const nauthReq = new FastifyRequestWrapper(request);
+      const nauthRes = new FastifyResponseWrapper(reply);
+
+      // Restore context for interceptor
+      const store = (request as FastifyRequestWithContext)[NAUTH_CONTEXT_STORE];
+
+      if (!store) {
+        // No context - pass through unchanged
+        return payload;
+      }
+
+      return ContextStorage.enterStore(store, async () => {
+        try {
+          let parsedPayload = payload;
+
+          // Parse JSON payload if needed (Fastify serializes before onSend)
+          const contentType = reply.getHeader('content-type') as string | undefined;
+          const isJson = contentType?.includes('application/json');
+
+          if (isJson && typeof payload === 'string') {
+            try {
+              parsedPayload = JSON.parse(payload);
+            } catch {
+              // Not valid JSON, use as-is
+            }
+          }
+
+          const modifiedBody = await handler(nauthReq, nauthRes, parsedPayload);
+
+          // Re-serialize if we parsed it
+          if (modifiedBody !== parsedPayload && isJson && typeof modifiedBody === 'object') {
+            return JSON.stringify(modifiedBody);
+          }
+
+          return modifiedBody !== parsedPayload ? modifiedBody : payload;
+        } catch {
+          // On error, return original payload
+          return payload;
+        }
+      });
+    };
+  }
+
+  /**
+   * Wrap a route handler to ensure context is available
+   *
+   * For Fastify, this is REQUIRED for route handlers to access ContextStorage.
+   */
+  public wrapRouteHandler<T>(handler: NAuthRouteHandler<T>): FastifyRouteHandler {
+    return async (request: FastifyRequest, reply: FastifyReply): Promise<T | void> => {
+      this.ensureAttributes(request);
+
+      const nauthReq = new FastifyRequestWrapper(request);
+      const nauthRes = new FastifyResponseWrapper(reply);
+
+      // Restore context
+      const store = (request as FastifyRequestWithContext)[NAUTH_CONTEXT_STORE];
+
+      if (store) {
+        return ContextStorage.enterStore(store, async () => {
+          return handler(nauthReq, nauthRes);
+        });
+      }
+
+      // No context - execute without (shouldn't happen with proper setup)
+      return handler(nauthReq, nauthRes);
+    };
+  }
+
+  /**
+   * Ensure attribute storage exists on request
+   */
+  private ensureAttributes(request: FastifyRequest): void {
+    if (!(request as FastifyRequestWithContext)[NAUTH_ATTRIBUTES]) {
+      (request as FastifyRequestWithContext)[NAUTH_ATTRIBUTES] = {};
+    }
+  }
+}
+
+// ============================================================================
+// Fastify Request Wrapper
+// ============================================================================
+
+/**
+ * Wraps Fastify request into NAuthRequest interface
+ */
+class FastifyRequestWrapper implements NAuthRequest {
+  constructor(private readonly request: FastifyRequest) {}
+
+  get raw(): unknown {
+    return this.request;
+  }
+
+  get method(): string {
+    return this.request.method.toUpperCase();
+  }
+
+  get path(): string {
+    // Fastify provides routeOptions.url for path, or extract from url
+    return this.request.url.split('?')[0];
+  }
+
+  get url(): string {
+    return this.request.url;
+  }
+
+  get body(): Record<string, unknown> {
+    return (this.request.body as Record<string, unknown>) || {};
+  }
+
+  get query(): Record<string, unknown> {
+    return (this.request.query as Record<string, unknown>) || {};
+  }
+
+  get params(): Record<string, string> {
+    return (this.request.params as Record<string, string>) || {};
+  }
+
+  get headers(): Record<string, string | string[] | undefined> {
+    return this.request.headers as Record<string, string | string[] | undefined>;
+  }
+
+  get cookies(): Record<string, string | undefined> {
+    // Fastify with @fastify/cookie
+    return ((this.request as FastifyRequestWithCookies).cookies as Record<string, string | undefined>) || {};
+  }
+
+  get ip(): string {
+    return this.request.ip || '0.0.0.0';
+  }
+
+  get attributes(): NAuthRequestAttributes {
+    // Return isolated storage
+    return (this.request as FastifyRequestWithContext)[NAUTH_ATTRIBUTES] || {};
+  }
+
+  public getHeader(name: string): string | undefined {
+    const val = this.request.headers[name.toLowerCase()];
+    if (Array.isArray(val)) return val[0];
+    return val;
+  }
+}
+
+// ============================================================================
+// Fastify Response Wrapper
+// ============================================================================
+
+/**
+ * Wraps Fastify reply into NAuthResponse interface
+ */
+class FastifyResponseWrapper implements NAuthResponse {
+  constructor(private readonly reply: FastifyReply) {}
+
+  get raw(): unknown {
+    return this.reply;
+  }
+
+  public status(code: number): this {
+    this.reply.code(code);
+    return this;
+  }
+
+  public header(name: string, value: string | string[]): this {
+    this.reply.header(name, value);
+    return this;
+  }
+
+  public setCookie(name: string, value: string, options?: NAuthCookieOptions): this {
+    // Fastify with @fastify/cookie
+    const replyWithCookies = this.reply as FastifyReplyWithCookies;
+    if (typeof replyWithCookies.setCookie === 'function') {
+      replyWithCookies.setCookie(name, value, this.convertCookieOptions(options));
+    }
+    return this;
+  }
+
+  public clearCookie(name: string, options?: NAuthCookieOptions): this {
+    const replyWithCookies = this.reply as FastifyReplyWithCookies;
+    if (typeof replyWithCookies.clearCookie === 'function') {
+      replyWithCookies.clearCookie(name, this.convertCookieOptions(options));
+    } else if (typeof replyWithCookies.setCookie === 'function') {
+      // Fallback: set empty cookie with immediate expiry
+      replyWithCookies.setCookie(name, '', {
+        ...this.convertCookieOptions(options),
+        maxAge: 0,
+        expires: new Date(0),
+      });
+    }
+    return this;
+  }
+
+  public send(body: unknown): void {
+    this.reply.send(body);
+  }
+
+  public json(body: unknown): void {
+    // Fastify auto-serializes objects
+    this.reply.send(body);
+  }
+
+  public redirect(url: string, status?: number): void {
+    if (status) {
+      this.reply.redirect(status, url);
+    } else {
+      this.reply.redirect(url);
+    }
+  }
+
+  public isSent(): boolean {
+    return this.reply.sent;
+  }
+
+  /**
+   * Convert NAuth cookie options to Fastify cookie options
+   */
+  private convertCookieOptions(options?: NAuthCookieOptions): Record<string, unknown> {
+    if (!options) return {};
+
+    return {
+      httpOnly: options.httpOnly,
+      secure: options.secure,
+      sameSite: options.sameSite,
+      domain: options.domain,
+      path: options.path,
+      maxAge: options.maxAge,
+      expires: options.expires,
+    };
+  }
+}
+
+// ============================================================================
+// Fastify Type Definitions (minimal, for internal use)
+// ============================================================================
+
+interface FastifyRequest {
+  method: string;
+  url: string;
+  body: unknown;
+  query: unknown;
+  params: unknown;
+  headers: Record<string, string | string[] | undefined>;
+  ip: string;
+}
+
+interface FastifyRequestWithCookies extends FastifyRequest {
+  cookies?: Record<string, string>;
+}
+
+interface FastifyRequestWithContext extends FastifyRequest {
+  [NAUTH_CONTEXT_STORE]?: Map<string, unknown>;
+  [NAUTH_ATTRIBUTES]?: NAuthRequestAttributes;
+}
+
+interface FastifyReply {
+  code(statusCode: number): this;
+  header(name: string, value: string | string[]): this;
+  send(payload?: unknown): this;
+  redirect(url: string): this;
+  redirect(statusCode: number, url: string): this;
+  getHeader(name: string): string | undefined;
+  sent: boolean;
+}
+
+interface FastifyReplyWithCookies extends FastifyReply {
+  setCookie?(name: string, value: string, options?: Record<string, unknown>): this;
+  clearCookie?(name: string, options?: Record<string, unknown>): this;
+}
+
+type FastifyHook = (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+type FastifyOnSendHook = (request: FastifyRequest, reply: FastifyReply, payload: unknown) => Promise<unknown>;
+type FastifyRouteHandler = (request: FastifyRequest, reply: FastifyReply) => Promise<unknown>;
+
+// ============================================================================
+// Convenience Export
+// ============================================================================
+
+/**
+ * Convenience function for wrapping Fastify route handlers
+ *
+ * @deprecated Use adapter.wrapRouteHandler() instead. This is kept for backward compatibility.
+ *
+ * @example
+ * ```typescript
+ * // Old way (deprecated):
+ * fastify.get('/me', withNAuthContext(async (request, reply) => {...}));
+ *
+ * // New way (recommended):
+ * const handler = nauth.adapter.wrapRouteHandler(async (req, res) => {...});
+ * fastify.get('/me', handler);
+ * ```
+ */
+export function withNAuthContext<T>(
+  handler: (request: FastifyRequest, reply: FastifyReply) => Promise<T>,
+): (request: FastifyRequest, reply: FastifyReply) => Promise<T | void> {
+  return async (request: FastifyRequest, reply: FastifyReply): Promise<T | void> => {
+    const store = (request as FastifyRequestWithContext)[NAUTH_CONTEXT_STORE];
+
+    if (store) {
+      return ContextStorage.enterStore(store, async () => {
+        return handler(request, reply);
+      });
+    }
+
+    // No context - execute without
+    return handler(request, reply);
+  };
+}

package/src/adapters/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Platform Adapters
+ *
+ * Framework-specific adapters that implement NAuthAdapter interface.
+ */
+
+// Platform interfaces (for custom adapter development)
+export * from '../platform/interfaces';
+
+// Built-in adapters
+export { ExpressAdapter, ExpressMiddlewareType } from './express.adapter';
+export { FastifyAdapter } from './fastify.adapter';
+
+// Legacy export for backward compatibility (deprecated)
+// TODO: Remove in next major version
+export { withNAuthContext } from './fastify.adapter';

package/src/adapters/storage.factory.ts

@@ -0,0 +1,143 @@
+/**
+ * Storage Adapter Factory Functions
+ *
+ * Provides clean factory functions for creating storage adapters.
+ * These factories handle proper initialization and simplify configuration.
+ *
+ * @example
+ * ```typescript
+ * import { createDatabaseStorageAdapter, createRedisStorageAdapter } from '@nauth-toolkit/express';
+ *
+ * export const authConfig = {
+ *   // Database adapter (uses existing TypeORM connection)
+ *   storageAdapter: createDatabaseStorageAdapter(),
+ *
+ *   // Or Redis adapter
+ *   storageAdapter: createRedisStorageAdapter(process.env.REDIS_URL),
+ * };
+ * ```
+ */
+
+import { StorageAdapter } from '../interfaces/storage-adapter.interface';
+
+/**
+ * Create a database storage adapter
+ *
+ * Uses the existing TypeORM connection. Make sure storage entities are included
+ * in your DataSource configuration:
+ *
+ * ```typescript
+ * import { getNAuthStorageEntities } from '@nauth-toolkit/database-typeorm-postgres';
+ * const dataSource = new DataSource({
+ *   entities: [...getNAuthEntities(), ...getNAuthStorageEntities()],
+ * });
+ * ```
+ *
+ * @returns DatabaseStorageAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { createDatabaseStorageAdapter } from '@nauth-toolkit/express';
+ *
+ * export const authConfig = {
+ *   storageAdapter: createDatabaseStorageAdapter(),
+ *   // ... other config
+ * };
+ * ```
+ */
+export function createDatabaseStorageAdapter(): StorageAdapter {
+  // Lazy import to avoid bundling if not used
+  const { DatabaseStorageAdapter } = require('@nauth-toolkit/storage-database');
+  return new DatabaseStorageAdapter(null, null, null);
+}
+
+/**
+ * Create a Redis storage adapter
+ *
+ * Creates and connects a Redis client automatically using the `redis` package (node-redis).
+ * The client connection is managed internally by the adapter.
+ *
+ * Supports both single-instance Redis and Redis Cluster configurations.
+ *
+ * @param url - Redis connection URL (default: 'redis://localhost:6379')
+ *   Supports authentication in URL format:
+ *   - redis://localhost:6379 (no auth)
+ *   - redis://:password@localhost:6379 (password only)
+ *   - redis://username:password@localhost:6379 (username + password)
+ *   - rediss://localhost:6379 (TLS/SSL, with optional auth)
+ * @returns RedisStorageAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { createRedisStorageAdapter, createRedisClusterAdapter } from '@nauth-toolkit/express';
+ *
+ * export const authConfig = {
+ *   // Single-instance Redis
+ *   storageAdapter: createRedisStorageAdapter(process.env.REDIS_URL),
+ *
+ *   // Or Redis Cluster (for production high-availability)
+ *   storageAdapter: createRedisClusterAdapter([
+ *     { url: 'redis://redis-node-1:6379' },
+ *     { url: 'redis://redis-node-2:6379' },
+ *     { url: 'redis://redis-node-3:6379' },
+ *   ]),
+ * };
+ * ```
+ */
+export function createRedisStorageAdapter(url: string = 'redis://localhost:6379'): StorageAdapter {
+  // Lazy import to avoid bundling if not used
+  const { RedisStorageAdapter } = require('@nauth-toolkit/storage-redis');
+  const { createClient } = require('redis');
+
+  const redisClient = createClient({ url });
+
+  // Don't connect here - let adapter.initialize() handle connection
+  // This ensures proper error handling and allows initialize() to wait for connection
+
+  return new RedisStorageAdapter(redisClient);
+}
+
+/**
+ * Create a Redis Cluster storage adapter
+ *
+ * Creates and connects a Redis Cluster client automatically using the `redis` package (node-redis).
+ * The cluster client handles automatic topology discovery, command routing, and failover.
+ *
+ * **Production Use:**
+ * Use Redis Cluster for high-availability production deployments. The cluster automatically:
+ * - Discovers cluster topology
+ * - Routes commands to correct nodes based on key hash slots
+ * - Handles node failures and redirects (MOVED/ASK errors)
+ * - Provides high availability and horizontal scaling
+ *
+ * @param nodes - Array of cluster node URLs
+ * @returns RedisStorageAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { createRedisClusterAdapter } from '@nauth-toolkit/express';
+ *
+ * export const authConfig = {
+ *   // Redis Cluster with 3 nodes
+ *   storageAdapter: createRedisClusterAdapter([
+ *     { url: 'redis://redis-node-1:6379' },
+ *     { url: 'redis://redis-node-2:6379' },
+ *     { url: 'redis://redis-node-3:6379' },
+ *   ]),
+ * };
+ * ```
+ */
+export function createRedisClusterAdapter(nodes: Array<{ url: string }>): StorageAdapter {
+  // Lazy import to avoid bundling if not used
+  const { RedisStorageAdapter } = require('@nauth-toolkit/storage-redis');
+  const { createCluster } = require('redis');
+
+  const clusterClient = createCluster({
+    rootNodes: nodes,
+  });
+
+  // Don't connect here - let adapter.initialize() handle connection
+  // This ensures proper error handling and allows initialize() to wait for connection
+
+  return new RedisStorageAdapter(clusterClient);
+}