@superdangerous/app-framework 4.9.0

package/src/middleware/openapi.ts

@@ -0,0 +1,305 @@
+/**
+ * OpenAPI Documentation Middleware
+ * Provides automatic API documentation generation
+ */
+
+import swaggerJsdoc from "swagger-jsdoc";
+import swaggerUi from "swagger-ui-express";
+import { Express } from "express";
+
+export interface OpenAPIConfig {
+  title: string;
+  version: string;
+  description?: string;
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+  contact?: {
+    name?: string;
+    email?: string;
+    url?: string;
+  };
+  license?: {
+    name: string;
+    url?: string;
+  };
+  tags?: Array<{
+    name: string;
+    description?: string;
+  }>;
+}
+
+/**
+ * Generate OpenAPI specification
+ * @param config OpenAPI configuration
+ * @param apis Array of file patterns for API routes
+ */
+export function generateOpenAPISpec(
+  config: OpenAPIConfig,
+  apis: string[],
+): object {
+  const options: swaggerJsdoc.Options = {
+    definition: {
+      openapi: "3.0.0",
+      info: {
+        title: config.title,
+        version: config.version,
+        description: config.description,
+        contact: config.contact,
+        license: config.license,
+      },
+      servers: config.servers || [
+        {
+          url: "http://localhost:3000",
+          description: "Development server",
+        },
+      ],
+      tags: config.tags,
+      components: {
+        schemas: {
+          ApiResponse: {
+            type: "object",
+            properties: {
+              success: {
+                type: "boolean",
+                description: "Indicates if the request was successful",
+              },
+              data: {
+                type: "object",
+                description: "Response data payload",
+              },
+              error: {
+                type: "object",
+                properties: {
+                  code: {
+                    type: "string",
+                    description: "Error code",
+                  },
+                  message: {
+                    type: "string",
+                    description: "Error message",
+                  },
+                  details: {
+                    type: "object",
+                    description: "Additional error details",
+                  },
+                },
+              },
+              message: {
+                type: "string",
+                description: "Optional success message",
+              },
+              metadata: {
+                type: "object",
+                properties: {
+                  timestamp: {
+                    type: "string",
+                    format: "date-time",
+                    description: "Response timestamp",
+                  },
+                  version: {
+                    type: "string",
+                    description: "API version",
+                  },
+                  pagination: {
+                    type: "object",
+                    properties: {
+                      page: { type: "integer" },
+                      limit: { type: "integer" },
+                      total: { type: "integer" },
+                      hasMore: { type: "boolean" },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          ValidationError: {
+            type: "object",
+            properties: {
+              field: {
+                type: "string",
+                description: "Field that failed validation",
+              },
+              message: {
+                type: "string",
+                description: "Validation error message",
+              },
+            },
+          },
+          ErrorResponse: {
+            type: "object",
+            properties: {
+              success: {
+                type: "boolean",
+                enum: [false],
+              },
+              error: {
+                type: "object",
+                properties: {
+                  code: { type: "string" },
+                  message: { type: "string" },
+                  details: { type: "object" },
+                },
+                required: ["code", "message"],
+              },
+            },
+            required: ["success", "error"],
+          },
+        },
+        securitySchemes: {
+          sessionAuth: {
+            type: "apiKey",
+            in: "cookie",
+            name: "connect.sid",
+            description: "Session-based authentication",
+          },
+          bearerAuth: {
+            type: "http",
+            scheme: "bearer",
+            bearerFormat: "JWT",
+            description: "JWT bearer token authentication",
+          },
+        },
+        responses: {
+          BadRequest: {
+            description: "Bad request",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/ErrorResponse",
+                },
+              },
+            },
+          },
+          Unauthorized: {
+            description: "Authentication required",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/ErrorResponse",
+                },
+              },
+            },
+          },
+          Forbidden: {
+            description: "Access denied",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/ErrorResponse",
+                },
+              },
+            },
+          },
+          NotFound: {
+            description: "Resource not found",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/ErrorResponse",
+                },
+              },
+            },
+          },
+          InternalError: {
+            description: "Internal server error",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/ErrorResponse",
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    apis,
+  };
+
+  return swaggerJsdoc(options);
+}
+
+/**
+ * Setup OpenAPI documentation UI
+ * @param app Express application
+ * @param config OpenAPI configuration
+ * @param apis Array of file patterns for API routes
+ * @param path Path to serve documentation (default: /api-docs)
+ */
+export function setupOpenAPIDocumentation(
+  app: Express,
+  config: OpenAPIConfig,
+  apis: string[],
+  path: string = "/api-docs",
+): void {
+  const swaggerSpec = generateOpenAPISpec(config, apis);
+
+  // Serve OpenAPI spec as JSON
+  app.get(`${path}/spec.json`, (_req, res) => {
+    res.json(swaggerSpec);
+  });
+
+  // Serve Swagger UI
+  app.use(
+    path,
+    swaggerUi.serve,
+    swaggerUi.setup(swaggerSpec, {
+      customSiteTitle: `${config.title} - API Documentation`,
+      customfavIcon: "/favicon.ico",
+      customCss: `
+        .swagger-ui .topbar { display: none }
+        .swagger-ui .info { margin-bottom: 40px }
+        .swagger-ui .scheme-container { display: none }
+      `,
+      swaggerOptions: {
+        persistAuthorization: true,
+        displayRequestDuration: true,
+        docExpansion: "none",
+        filter: true,
+        showExtensions: true,
+        showCommonExtensions: true,
+        displayOperationId: false,
+      },
+    }),
+  );
+}
+
+/**
+ * Example JSDoc annotation for OpenAPI
+ *
+ * @swagger
+ * /api/resource:
+ *   get:
+ *     summary: Get all resources
+ *     tags: [Resources]
+ *     responses:
+ *       200:
+ *         description: Successful response
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ApiResponse'
+ *       500:
+ *         $ref: '#/components/responses/InternalError'
+ */
+
+/**
+ * OpenAPI operation decorator (for future TypeScript decorator support)
+ */
+export function ApiOperation(operation: any) {
+  return function (
+    target: any,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    // Store OpenAPI metadata for later processing
+    if (!target._openapi) {
+      target._openapi = {};
+    }
+    target._openapi[propertyKey] = operation;
+    return descriptor;
+  };
+}

package/src/middleware/requestLogging.ts

@@ -0,0 +1,92 @@
+import type { NextFunction, Request, Response } from "express";
+import { randomUUID } from "crypto";
+import { createLogger } from "../core/logger.js";
+
+export interface RequestLoggingOptions {
+  logger?: any;
+  /**
+   * Paths to skip logging for (commonly health checks or metrics)
+   */
+  skipPaths?: Array<string | RegExp>;
+  /**
+   * Whether to log the request payload (truncated)
+   */
+  logPayload?: boolean;
+  /**
+   * Maximum number of characters from the payload to log
+   */
+  maxPayloadLength?: number;
+}
+
+const defaultSkips = [/^\/health/, /^\/api\/health/];
+
+function shouldSkip(path: string, patterns: Array<string | RegExp>) {
+  return patterns.some((pattern) => {
+    if (pattern instanceof RegExp) {
+      return pattern.test(path);
+    }
+    return path.startsWith(pattern);
+  });
+}
+
+function safePayload(body: unknown, maxLength: number): string | undefined {
+  if (!body || typeof body !== "object") return undefined;
+  const serialized = JSON.stringify(body);
+  if (serialized.length <= maxLength) return serialized;
+  return `${serialized.slice(0, maxLength)}…`;
+}
+
+/**
+ * Express middleware that assigns a request ID and logs completion.
+ * Uses the framework logger so request logs land in the same files as the app.
+ */
+export function createRequestLoggingMiddleware(
+  options: RequestLoggingOptions = {},
+) {
+  const logger =
+    options.logger ||
+    // Avoid forcing the consumer to initialize logging before use
+    createLogger("http");
+  const skipPatterns = options.skipPaths || defaultSkips;
+  const logPayload = options.logPayload ?? false;
+  const maxPayloadLength = options.maxPayloadLength ?? 2000;
+
+  return function requestLogging(
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ) {
+    const startedAt = process.hrtime.bigint();
+    const requestId = (req as any).requestId || randomUUID();
+    (req as any).requestId = requestId;
+    res.locals.requestId = requestId;
+    res.setHeader("x-request-id", requestId);
+
+    res.on("finish", () => {
+      if (shouldSkip(req.path, skipPatterns)) return;
+
+      const durationMs =
+        Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+
+      // Prefer the richer logRequest helper if available
+      if (typeof logger.logRequest === "function") {
+        logger.logRequest(req, res, Number(durationMs.toFixed(2)));
+        return;
+      }
+
+      logger.info("Request completed", {
+        method: req.method,
+        path: req.originalUrl || req.url,
+        status: res.statusCode,
+        durationMs: Number(durationMs.toFixed(2)),
+        requestId,
+        userAgent: req.get("user-agent"),
+        payload: logPayload
+          ? safePayload(req.body, maxPayloadLength)
+          : undefined,
+      });
+    });
+
+    next();
+  };
+}

package/src/middleware/session.ts

@@ -0,0 +1,238 @@
+/**
+ * Session Configuration Middleware
+ * Standardized session management for Express applications
+ */
+
+import session from "express-session";
+import { Express } from "express";
+import { createLogger } from "../core/index.js";
+
+let logger: any; // Will be initialized when needed
+
+function ensureLogger() {
+  if (!logger) {
+    logger = createLogger("SessionMiddleware");
+  }
+  return logger;
+}
+
+export interface SessionConfig {
+  secret?: string;
+  name?: string;
+  maxAge?: number;
+  secure?: boolean;
+  sameSite?: "lax" | "strict" | "none";
+  trustProxy?: boolean;
+  resave?: boolean;
+  saveUninitialized?: boolean;
+  rolling?: boolean;
+  store?: "memory" | session.Store;
+}
+
+/**
+ * Configure session middleware with sensible defaults
+ */
+export function configureSession(app: Express, config: SessionConfig = {}) {
+  const {
+    secret = process.env.SESSION_SECRET || "change-this-secret-in-production",
+    name = "app.sid",
+    maxAge = 3600000, // 1 hour
+    secure = process.env.NODE_ENV === "production",
+    sameSite = "lax",
+    trustProxy = true,
+    resave = false,
+    saveUninitialized = false,
+    rolling = true,
+    store = "memory",
+  } = config;
+
+  // Warn about insecure settings in production
+  if (process.env.NODE_ENV === "production") {
+    if (secret === "change-this-secret-in-production") {
+      ensureLogger().warn(
+        "Using default session secret in production! Set SESSION_SECRET environment variable.",
+      );
+    }
+    if (store === "memory") {
+      ensureLogger().warn(
+        "Using memory session store in production! Consider using Redis or another persistent store.",
+      );
+    }
+    if (!secure) {
+      ensureLogger().warn(
+        "Session cookies are not secure in production! Consider enabling secure cookies.",
+      );
+    }
+  }
+
+  // Trust proxy if configured
+  if (trustProxy) {
+    app.set("trust proxy", 1);
+  }
+
+  // Suppress MemoryStore warning in production
+  let originalWarn: typeof console.warn | undefined;
+  if (process.env.NODE_ENV === "production" && store === "memory") {
+    originalWarn = console.warn;
+    console.warn = (msg: string, ...args: any[]) => {
+      if (typeof msg === "string" && !msg.includes("MemoryStore")) {
+        originalWarn!(msg, ...args);
+      }
+    };
+  }
+
+  const sessionConfig: session.SessionOptions = {
+    secret,
+    name,
+    resave,
+    saveUninitialized,
+    rolling,
+    cookie: {
+      secure,
+      httpOnly: true,
+      maxAge,
+      sameSite,
+      path: "/",
+    },
+  };
+
+  // Add store if provided
+  if (store !== "memory") {
+    sessionConfig.store = store;
+  }
+
+  // Apply middleware
+  app.use(session(sessionConfig));
+
+  // Restore console.warn if it was modified
+  if (originalWarn) {
+    // Restore after a brief delay to ensure session is initialized
+    setTimeout(() => {
+      console.warn = originalWarn!;
+    }, 100);
+  }
+
+  if (
+    process.env.NODE_ENV === "development" &&
+    process.env.LOG_LEVEL?.toLowerCase() === "debug"
+  ) {
+    ensureLogger().debug("Session middleware configured", {
+      name,
+      secure,
+      sameSite,
+      maxAge: `${maxAge / 1000}s`,
+      store: store === "memory" ? "memory" : "custom",
+    });
+  }
+}
+
+/**
+ * Create a Redis session store (OPTIONAL)
+ *
+ * Redis is an optional dependency for persistent session storage in production.
+ * If Redis packages are not installed, the framework gracefully falls back to memory store.
+ *
+ * To enable Redis sessions:
+ * 1. Install optional dependencies: `npm install connect-redis redis`
+ * 2. Set REDIS_URL environment variable (optional, defaults to redis://localhost:6379)
+ * 3. Use createRedisStore() in your session configuration
+ *
+ * For desktop applications with single users, memory store is usually sufficient.
+ *
+ * @param redisUrl - Optional Redis connection URL (defaults to REDIS_URL env var or redis://localhost:6379)
+ * @returns Redis store instance or 'memory' string on failure
+ */
+export async function createRedisStore(redisUrl?: string) {
+  try {
+    // @ts-expect-error - Optional dependency
+    const RedisStore = (await import(/* @vite-ignore */ "connect-redis"))
+      .default;
+    // @ts-expect-error - Optional dependency
+    const { createClient } = await import(/* @vite-ignore */ "redis");
+
+    const redisClient = createClient({
+      url: redisUrl || process.env.REDIS_URL || "redis://localhost:6379",
+    });
+
+    await redisClient.connect();
+
+    ensureLogger().info("Redis session store connected");
+
+    return new RedisStore({
+      client: redisClient,
+      prefix: "session:",
+    });
+  } catch (_error: any) {
+    ensureLogger().error("Failed to create Redis store:", _error.message);
+    ensureLogger().warn("Falling back to memory store");
+    return "memory" as const;
+  }
+}
+
+/**
+ * Session utilities
+ */
+export const sessionUtils = {
+  /**
+   * Regenerate session ID (for security after login)
+   */
+  regenerateSession(req: any): Promise<void> {
+    return new Promise((resolve, reject) => {
+      req.session.regenerate((err: any) => {
+        if (err) {
+          ensureLogger().error("Failed to regenerate session:", err);
+          reject(err);
+        } else {
+          resolve();
+        }
+      });
+    });
+  },
+
+  /**
+   * Save session explicitly
+   */
+  saveSession(req: any): Promise<void> {
+    return new Promise((resolve, reject) => {
+      req.session.save((err: any) => {
+        if (err) {
+          ensureLogger().error("Failed to save session:", err);
+          reject(err);
+        } else {
+          resolve();
+        }
+      });
+    });
+  },
+
+  /**
+   * Destroy session
+   */
+  destroySession(req: any): Promise<void> {
+    return new Promise((resolve, reject) => {
+      req.session.destroy((err: any) => {
+        if (err) {
+          ensureLogger().error("Failed to destroy session:", err);
+          reject(err);
+        } else {
+          resolve();
+        }
+      });
+    });
+  },
+
+  /**
+   * Touch session to extend expiry
+   */
+  touchSession(req: any): void {
+    if (req.session) {
+      req.session.touch();
+    }
+  },
+};
+
+export default {
+  configureSession,
+  createRedisStore,
+  sessionUtils,
+};