@superdangerous/app-framework 4.9.0

package/dist/middleware/openapi.js

@@ -0,0 +1,258 @@
+/**
+ * OpenAPI Documentation Middleware
+ * Provides automatic API documentation generation
+ */
+import swaggerJsdoc from "swagger-jsdoc";
+import swaggerUi from "swagger-ui-express";
+/**
+ * Generate OpenAPI specification
+ * @param config OpenAPI configuration
+ * @param apis Array of file patterns for API routes
+ */
+export function generateOpenAPISpec(config, apis) {
+    const 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, config, apis, path = "/api-docs") {
+    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) {
+    return function (target, propertyKey, descriptor) {
+        // Store OpenAPI metadata for later processing
+        if (!target._openapi) {
+            target._openapi = {};
+        }
+        target._openapi[propertyKey] = operation;
+        return descriptor;
+    };
+}
+//# sourceMappingURL=openapi.js.map

package/dist/middleware/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../src/middleware/openapi.ts"],"names":[],"mappings":"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"}

package/dist/middleware/requestLogging.d.ts

@@ -0,0 +1,22 @@
+import type { NextFunction, Request, Response } from "express";
+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;
+}
+/**
+ * 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 declare function createRequestLoggingMiddleware(options?: RequestLoggingOptions): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=requestLogging.d.ts.map

package/dist/middleware/requestLogging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestLogging.d.ts","sourceRoot":"","sources":["../../src/middleware/requestLogging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAI/D,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,GAAG,CAAC;IACb;;OAEG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IACnC;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAoBD;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,qBAA0B,IAWjC,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,YAAY,UAmCrB"}

package/dist/middleware/requestLogging.js

@@ -0,0 +1,61 @@
+import { randomUUID } from "crypto";
+import { createLogger } from "../core/logger.js";
+const defaultSkips = [/^\/health/, /^\/api\/health/];
+function shouldSkip(path, patterns) {
+    return patterns.some((pattern) => {
+        if (pattern instanceof RegExp) {
+            return pattern.test(path);
+        }
+        return path.startsWith(pattern);
+    });
+}
+function safePayload(body, maxLength) {
+    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 = {}) {
+    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, res, next) {
+        const startedAt = process.hrtime.bigint();
+        const requestId = req.requestId || randomUUID();
+        req.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();
+    };
+}
+//# sourceMappingURL=requestLogging.js.map

package/dist/middleware/requestLogging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestLogging.js","sourceRoot":"","sources":["../../src/middleware/requestLogging.ts"],"names":[],"mappings":"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"}

package/dist/middleware/session.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Session Configuration Middleware
+ * Standardized session management for Express applications
+ */
+import session from "express-session";
+import { Express } from "express";
+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 declare function configureSession(app: Express, config?: SessionConfig): void;
+/**
+ * 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 declare function createRedisStore(redisUrl?: string): Promise<any>;
+/**
+ * Session utilities
+ */
+export declare const sessionUtils: {
+    /**
+     * Regenerate session ID (for security after login)
+     */
+    regenerateSession(req: any): Promise<void>;
+    /**
+     * Save session explicitly
+     */
+    saveSession(req: any): Promise<void>;
+    /**
+     * Destroy session
+     */
+    destroySession(req: any): Promise<void>;
+    /**
+     * Touch session to extend expiry
+     */
+    touchSession(req: any): void;
+};
+declare const _default: {
+    configureSession: typeof configureSession;
+    createRedisStore: typeof createRedisStore;
+    sessionUtils: {
+        /**
+         * Regenerate session ID (for security after login)
+         */
+        regenerateSession(req: any): Promise<void>;
+        /**
+         * Save session explicitly
+         */
+        saveSession(req: any): Promise<void>;
+        /**
+         * Destroy session
+         */
+        destroySession(req: any): Promise<void>;
+        /**
+         * Touch session to extend expiry
+         */
+        touchSession(req: any): void;
+    };
+};
+export default _default;
+//# sourceMappingURL=session.d.ts.map

package/dist/middleware/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/middleware/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,OAAO,MAAM,iBAAiB,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAYlC,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC;CAClC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,aAAkB,QA4FxE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,gBAyBvD;AAED;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB;;OAEG;2BACoB,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1C;;OAEG;qBACc,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAapC;;OAEG;wBACiB,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAavC;;OAEG;sBACe,GAAG,GAAG,IAAI;CAK7B,CAAC;;;;;QAxDA;;WAEG;+BACoB,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;QAa1C;;WAEG;yBACc,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;QAapC;;WAEG;4BACiB,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;QAavC;;WAEG;0BACe,GAAG,GAAG,IAAI;;;AAO9B,wBAIE"}

package/dist/middleware/session.js

@@ -0,0 +1,189 @@
+/**
+ * Session Configuration Middleware
+ * Standardized session management for Express applications
+ */
+import session from "express-session";
+import { createLogger } from "../core/index.js";
+let logger; // Will be initialized when needed
+function ensureLogger() {
+    if (!logger) {
+        logger = createLogger("SessionMiddleware");
+    }
+    return logger;
+}
+/**
+ * Configure session middleware with sensible defaults
+ */
+export function configureSession(app, config = {}) {
+    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;
+    if (process.env.NODE_ENV === "production" && store === "memory") {
+        originalWarn = console.warn;
+        console.warn = (msg, ...args) => {
+            if (typeof msg === "string" && !msg.includes("MemoryStore")) {
+                originalWarn(msg, ...args);
+            }
+        };
+    }
+    const sessionConfig = {
+        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) {
+    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) {
+        ensureLogger().error("Failed to create Redis store:", _error.message);
+        ensureLogger().warn("Falling back to memory store");
+        return "memory";
+    }
+}
+/**
+ * Session utilities
+ */
+export const sessionUtils = {
+    /**
+     * Regenerate session ID (for security after login)
+     */
+    regenerateSession(req) {
+        return new Promise((resolve, reject) => {
+            req.session.regenerate((err) => {
+                if (err) {
+                    ensureLogger().error("Failed to regenerate session:", err);
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    },
+    /**
+     * Save session explicitly
+     */
+    saveSession(req) {
+        return new Promise((resolve, reject) => {
+            req.session.save((err) => {
+                if (err) {
+                    ensureLogger().error("Failed to save session:", err);
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    },
+    /**
+     * Destroy session
+     */
+    destroySession(req) {
+        return new Promise((resolve, reject) => {
+            req.session.destroy((err) => {
+                if (err) {
+                    ensureLogger().error("Failed to destroy session:", err);
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    },
+    /**
+     * Touch session to extend expiry
+     */
+    touchSession(req) {
+        if (req.session) {
+            req.session.touch();
+        }
+    },
+};
+export default {
+    configureSession,
+    createRedisStore,
+    sessionUtils,
+};
+//# sourceMappingURL=session.js.map

package/dist/middleware/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/middleware/session.ts"],"names":[],"mappings":"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"}