create-jen-app 1.2.2 → 1.2.4

package/templates/ssr-isr/lib/jdb/utils.js

@@ -0,0 +1,176 @@
+import fs from "fs/promises";
+import crypto from "crypto";
+/**
+ * Ensure a directory exists, creating it recursively if necessary.
+ * Idempotent: does not throw if the directory already exists.
+ *
+ * @param dir Directory path to ensure exists.
+ * @throws Error if directory creation fails.
+ */
+export async function ensureDir(dir) {
+  try {
+    await fs.access(dir);
+  } catch {
+    await fs.mkdir(dir, { recursive: true });
+  }
+}
+/**
+ * Read and parse a JSON file from disk.
+ * Returns null if the file does not exist (ENOENT).
+ * Other errors (invalid JSON, permission denied, etc.) are re-thrown.
+ *
+ * @template T The expected JSON structure type.
+ * @param file Path to the JSON file to read.
+ * @returns Parsed JSON data, or null if file does not exist.
+ * @throws Error if the file exists but cannot be read or parsed.
+ */
+export async function readJSON(file) {
+  try {
+    const data = await fs.readFile(file, "utf-8");
+    return JSON.parse(data);
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+}
+/**
+ * Write data as JSON to a file atomically using a temporary file.
+ * Atomic writes prevent corruption if the process crashes during writing.
+ * The temporary file is renamed to the target file only after writing completes successfully.
+ *
+ * @param file Path to the target file (will be created or overwritten).
+ * @param data Object to serialize as JSON with pretty-printing (2-space indent).
+ * @throws Error if writing or renaming fails.
+ */
+export async function writeJSON(file, data) {
+  const tempFile = `${file}.tmp`;
+  await fs.writeFile(tempFile, JSON.stringify(data, null, 2));
+  await fs.rename(tempFile, file);
+}
+/**
+ * Generate a unique identifier for a new document.
+ * Uses cryptographically secure UUID v4 generation.
+ *
+ * @returns A UUID string suitable for use as a document _id.
+ */
+export function generateId() {
+  return crypto.randomUUID();
+}
+/**
+ * Test whether a document matches a filter query.
+ * Supports MongoDB-like query syntax including operators ($eq, $ne, $gt, etc.) and logical operators ($or, $and).
+ * Processes each field condition and returns false if any condition fails (AND semantics).
+ * Logical operators $or and $and are processed separately with their respective semantics.
+ *
+ * @param doc The document to test.
+ * @param filter The filter query to apply.
+ * @returns True if the document matches all filter conditions, false otherwise.
+ *
+ * @example
+ * matchFilter({ name: 'John', age: 30 }, { name: 'John' }) // true
+ * matchFilter({ age: 25 }, { age: { $gte: 18 } }) // true
+ * matchFilter({ name: 'Jane' }, { $or: [{ name: 'John' }, { name: 'Jane' }] }) // true
+ */
+export function matchFilter(doc, filter) {
+  for (const key in filter) {
+    if (key === "$or") {
+      // OR: at least one filter must match
+      if (!filter.$or.some((f) => matchFilter(doc, f))) return false;
+      continue;
+    }
+    if (key === "$and") {
+      // AND: all filters must match
+      if (!filter.$and.every((f) => matchFilter(doc, f))) return false;
+      continue;
+    }
+    const val = doc[key];
+    const cond = filter[key];
+    // If condition is an object (not array), it contains operators
+    if (typeof cond === "object" && cond !== null && !Array.isArray(cond)) {
+      for (const op in cond) {
+        const target = cond[op];
+        switch (op) {
+          case "$eq":
+            if (val !== target) return false;
+            break;
+          case "$ne":
+            if (val === target) return false;
+            break;
+          case "$gt":
+            if (!(val > target)) return false;
+            break;
+          case "$gte":
+            if (!(val >= target)) return false;
+            break;
+          case "$lt":
+            if (!(val < target)) return false;
+            break;
+          case "$lte":
+            if (!(val <= target)) return false;
+            break;
+          case "$in":
+            if (!target.includes(val)) return false;
+            break;
+          case "$nin":
+            if (target.includes(val)) return false;
+            break;
+          case "$regex":
+            if (!new RegExp(target).test(val)) return false;
+            break;
+        }
+      }
+    } else {
+      // Simple equality check
+      if (val !== cond) return false;
+    }
+  }
+  return true;
+}
+/**
+ * Apply update operators to a document, modifying it in place.
+ * Automatically updates the _updated timestamp to the current time.
+ * Supports $set, $unset, $inc, $push, and $pull operators.
+ *
+ * @param doc The document to update (modified in place).
+ * @param update Update specification with operators.
+ *
+ * @example
+ * const doc = { name: 'John', age: 30, tags: ['js'] };
+ * applyUpdate(doc, { $set: { name: 'Jane' }, $inc: { age: 1 }, $push: { tags: 'ts' } });
+ * // doc is now { name: 'Jane', age: 31, tags: ['js', 'ts'], _updated: <current-timestamp> }
+ */
+export function applyUpdate(doc, update) {
+  const now = Date.now();
+  doc._updated = now;
+  for (const op in update) {
+    const fields = update[op];
+    for (const key in fields) {
+      const val = fields[key];
+      switch (op) {
+        case "$set":
+          // Set field to the specified value
+          doc[key] = val;
+          break;
+        case "$unset":
+          // Remove the field from the document
+          delete doc[key];
+          break;
+        case "$inc":
+          // Increment numeric field by the specified amount
+          doc[key] = (doc[key] || 0) + val;
+          break;
+        case "$push":
+          // Append to array (create array if doesn't exist)
+          if (!Array.isArray(doc[key])) doc[key] = [];
+          doc[key].push(val);
+          break;
+        case "$pull":
+          // Remove all occurrences of value from array
+          if (Array.isArray(doc[key])) {
+            doc[key] = doc[key].filter((item) => item !== val);
+          }
+          break;
+      }
+    }
+  }
+}

package/templates/ssr-isr/lib/middleware/builtins/body-parser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Request body parsing middleware.
+ * Reads and parses the request body based on Content-Type header.
+ * Supports JSON, URL-encoded form data, and plain text.
+ *
+ * GET and HEAD requests are passed through without parsing since they have no body.
+ * Parsed body is available in ctx.body. If parsing fails, the raw string is stored
+ * and an error message is attached to ctx.parseError for error handling downstream.
+ *
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(bodyParser);
+ * // ctx.body is now populated with parsed request body
+ */
+export function bodyParser(ctx: any, next: any): Promise<any>;

package/templates/ssr-isr/lib/middleware/builtins/body-parser.js

@@ -0,0 +1,56 @@
+/**
+ * Request body parsing middleware.
+ * Reads and parses the request body based on Content-Type header.
+ * Supports JSON, URL-encoded form data, and plain text.
+ *
+ * GET and HEAD requests are passed through without parsing since they have no body.
+ * Parsed body is available in ctx.body. If parsing fails, the raw string is stored
+ * and an error message is attached to ctx.parseError for error handling downstream.
+ *
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(bodyParser);
+ * // ctx.body is now populated with parsed request body
+ */
+export async function bodyParser(ctx, next) {
+  // GET and HEAD requests have no body; skip parsing
+  if (ctx.req.method === "GET" || ctx.req.method === "HEAD") {
+    return next();
+  }
+  // Collect all data chunks from the request stream
+  const chunks = [];
+  await new Promise((resolve, reject) => {
+    ctx.req.on("data", (chunk) => chunks.push(chunk));
+    ctx.req.on("end", () => {
+      const data = Buffer.concat(chunks).toString();
+      const contentType = ctx.req.headers["content-type"] || "";
+      try {
+        // Parse based on Content-Type header
+        if (contentType.includes("application/json")) {
+          // Parse JSON, allowing empty bodies
+          if (!data || data.trim() === "") {
+            ctx.body = {};
+          } else {
+            ctx.body = JSON.parse(data);
+          }
+        } else if (contentType.includes("application/x-www-form-urlencoded")) {
+          // Parse URL-encoded form data as URLSearchParams
+          ctx.body = new URLSearchParams(data);
+        } else {
+          // Store raw string for other content types
+          ctx.body = data;
+        }
+      } catch (e) {
+        // On parse error, store the error and fall back to raw string
+        const error = e instanceof Error ? e.message : String(e);
+        console.error("Body parser error:", error);
+        ctx.parseError = error;
+        ctx.body = data; // Raw string on failure
+      }
+      resolve();
+    });
+    ctx.req.on("error", reject);
+  });
+  await next();
+}

package/templates/ssr-isr/lib/middleware/builtins/cors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CORS middleware with security defaults
+ * Prevents insecure origin sharing with credentials
+ */
+interface CORSOptions {
+  origin?: string | string[] | ((origin: string) => boolean) | "*";
+  methods?: string[];
+  allowedHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+}
+export declare function cors(
+  options?: CORSOptions,
+): (ctx: any, next: () => Promise<void>) => Promise<void>;
+export {};

package/templates/ssr-isr/lib/middleware/builtins/cors.js

@@ -0,0 +1,54 @@
+export function cors(options = {}) {
+  const defaults = {
+    origin: ["http://localhost:3000", "http://localhost:5173"],
+    methods: ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+    credentials: false, // Changed: credentials should be false with CORS by default for security
+    maxAge: 86400,
+  };
+  const opts = { ...defaults, ...options };
+  return async (ctx, next) => {
+    const origin = ctx.req.headers.origin;
+    // Validate origin against whitelist
+    let allowOrigin = false;
+    if (Array.isArray(opts.origin)) {
+      allowOrigin = origin && opts.origin.includes(origin);
+    } else if (typeof opts.origin === "function") {
+      allowOrigin = origin && opts.origin(origin);
+    } else if (opts.origin === "*") {
+      // DANGEROUS: only use with credentials: false
+      if (opts.credentials) {
+        console.warn(
+          "SECURITY WARNING: CORS origin '*' with credentials=true is insecure. Origin set to empty.",
+        );
+        allowOrigin = false;
+      } else {
+        allowOrigin = true;
+      }
+    } else if (opts.origin === origin) {
+      allowOrigin = true;
+    }
+    if (allowOrigin && origin) {
+      ctx.response.header("Access-Control-Allow-Origin", origin);
+    }
+    if (opts.credentials) {
+      ctx.response.header("Access-Control-Allow-Credentials", "true");
+    }
+    if (ctx.req.method === "OPTIONS") {
+      ctx.response.header(
+        "Access-Control-Allow-Methods",
+        opts.methods?.join(","),
+      );
+      ctx.response.header(
+        "Access-Control-Allow-Headers",
+        opts.allowedHeaders?.join(","),
+      );
+      if (opts.maxAge) {
+        ctx.response.header("Access-Control-Max-Age", opts.maxAge);
+      }
+      ctx.response.status(204).send();
+      return;
+    }
+    await next();
+  };
+}

package/templates/ssr-isr/lib/middleware/builtins/logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Middleware that logs HTTP requests and responses with timing information.
+ * Records the request method and path on entry, then logs the status code and elapsed time on exit.
+ * If a request ID is set in ctx.state.requestId (typically by request-id middleware),
+ * it is included in log lines for request tracing.
+ *
+ * This middleware should be registered early in the middleware chain to capture timing
+ * for all downstream handlers.
+ *
+ * Log format:
+ * - Request: "[requestId] -> METHOD /path"
+ * - Response: "[requestId] <- METHOD /path 200 (45.32ms)"
+ *
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(logger);
+ */
+export function logger(ctx: any, next: any): Promise<void>;

package/templates/ssr-isr/lib/middleware/builtins/logger.js

@@ -0,0 +1,34 @@
+import { log } from "../../shared/log.js";
+/**
+ * Middleware that logs HTTP requests and responses with timing information.
+ * Records the request method and path on entry, then logs the status code and elapsed time on exit.
+ * If a request ID is set in ctx.state.requestId (typically by request-id middleware),
+ * it is included in log lines for request tracing.
+ *
+ * This middleware should be registered early in the middleware chain to capture timing
+ * for all downstream handlers.
+ *
+ * Log format:
+ * - Request: "[requestId] -> METHOD /path"
+ * - Response: "[requestId] <- METHOD /path 200 (45.32ms)"
+ *
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(logger);
+ */
+export async function logger(ctx, next) {
+  const start = performance.now();
+  // Log request entry with method and URL.
+  const method = ctx.req.method;
+  const url = ctx.url.pathname;
+  const id = ctx.state.requestId ? `[${ctx.state.requestId}]` : "";
+  log.info(`${id} -> ${method} ${url}`);
+  try {
+    await next();
+  } finally {
+    // Log response exit with status and elapsed time.
+    const ms = (performance.now() - start).toFixed(2);
+    log.info(`${id} <- ${method} ${url} ${ctx.res.statusCode} (${ms}ms)`);
+  }
+}

package/templates/ssr-isr/lib/middleware/builtins/rate-limit.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Rate limiting middleware that protects against brute force and DDoS attacks.
+ * Tracks request count per client IP within a time window and rejects excess requests.
+ * Uses in-memory storage, suitable for single-server deployments; use Redis for distributed systems.
+ *
+ * Automatically cleans up expired records every minute to prevent memory leaks.
+ * Respects X-Forwarded-For header for deployments behind a proxy or load balancer.
+ *
+ * @param options Rate limiting configuration.
+ * @param options.windowMs Time window in milliseconds (default: 15 minutes).
+ * @param options.max Maximum requests per IP per window (default: 100).
+ * @param options.message Error message sent to rate-limited clients (default: "Too many requests...").
+ * @param options.statusCode HTTP status for rate-limited responses (default: 429 Too Many Requests).
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(rateLimit({
+ *   windowMs: 15 * 60 * 1000,
+ *   max: 100
+ * }));
+ */
+export function rateLimit(options?: {}): (ctx: any, next: any) => Promise<void>;

package/templates/ssr-isr/lib/middleware/builtins/rate-limit.js

@@ -0,0 +1,79 @@
+/**
+ * Rate limiting middleware that protects against brute force and DDoS attacks.
+ * Tracks request count per client IP within a time window and rejects excess requests.
+ * Uses in-memory storage, suitable for single-server deployments; use Redis for distributed systems.
+ *
+ * Automatically cleans up expired records every minute to prevent memory leaks.
+ * Respects X-Forwarded-For header for deployments behind a proxy or load balancer.
+ *
+ * @param options Rate limiting configuration.
+ * @param options.windowMs Time window in milliseconds (default: 15 minutes).
+ * @param options.max Maximum requests per IP per window (default: 100).
+ * @param options.message Error message sent to rate-limited clients (default: "Too many requests...").
+ * @param options.statusCode HTTP status for rate-limited responses (default: 429 Too Many Requests).
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(rateLimit({
+ *   windowMs: 15 * 60 * 1000,
+ *   max: 100
+ * }));
+ */
+export function rateLimit(options = {}) {
+  const defaults = {
+    windowMs: 15 * 60 * 1000, // 15 minutes.
+    max: 100, // 100 requests per window.
+    message: "Too many requests, please try again later.",
+    statusCode: 429,
+  };
+  const opts = { ...defaults, ...options };
+  // In-memory store mapping IP addresses to request records.
+  const hits = new Map();
+  // Cleanup old records every minute to prevent memory leak.
+  // Records outside their window are garbage collected.
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, record] of hits.entries()) {
+      if (now > record.resetTime) {
+        hits.delete(key);
+      }
+    }
+  }, 60 * 1000);
+  return async (ctx, next) => {
+    // Extract the client IP address. Check X-Forwarded-For header for proxied requests.
+    let ip = ctx.req.headers["x-forwarded-for"];
+    if (typeof ip === "string") {
+      ip = ip.split(",")[0].trim(); // Get first IP if multiple are listed.
+    } else {
+      ip = ctx.req.socket.remoteAddress || "unknown";
+    }
+    const now = Date.now();
+    let record = hits.get(ip);
+    // Initialize or reset the request record if the window has expired.
+    if (!record || now > record.resetTime) {
+      record = {
+        count: 0,
+        resetTime: now + opts.windowMs,
+        firstRequest: now,
+      };
+      hits.set(ip, record);
+    }
+    record.count++;
+    const remaining = opts.max - record.count;
+    // Set standard rate-limit headers following GitHub API conventions.
+    ctx.response.header("RateLimit-Limit", opts.max);
+    ctx.response.header("RateLimit-Remaining", Math.max(0, remaining));
+    ctx.response.header("RateLimit-Reset", Math.ceil(record.resetTime / 1000));
+    if (record.count > opts.max) {
+      // Rate limit exceeded. Respond with retry-after header and error message.
+      const retryAfter = Math.ceil((record.resetTime - now) / 1000);
+      ctx.response.header("Retry-After", retryAfter);
+      ctx.response.status(opts.statusCode).json({
+        error: opts.message,
+        retryAfter,
+      });
+      return;
+    }
+    await next();
+  };
+}

package/templates/ssr-isr/lib/middleware/builtins/request-id.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Request ID middleware that assigns unique identifiers to incoming requests.
+ * Enables request tracing and correlation across logs and API calls.
+ *
+ * If the client provides an X-Request-ID header, that ID is used. Otherwise, a new UUID is generated.
+ * The request ID is attached to both the response header (for client visibility) and ctx.state
+ * (for other middleware like logger to use in log entries).
+ *
+ * This middleware should be registered early in the chain to ensure all downstream handlers
+ * have access to the request ID.
+ *
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(requestId);
+ * // All requests now have a unique X-Request-ID header
+ * // Available in ctx.state.requestId for logging and tracing
+ */
+export function requestId(ctx: any, next: any): Promise<void>;

package/templates/ssr-isr/lib/middleware/builtins/request-id.js

@@ -0,0 +1,29 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Request ID middleware that assigns unique identifiers to incoming requests.
+ * Enables request tracing and correlation across logs and API calls.
+ *
+ * If the client provides an X-Request-ID header, that ID is used. Otherwise, a new UUID is generated.
+ * The request ID is attached to both the response header (for client visibility) and ctx.state
+ * (for other middleware like logger to use in log entries).
+ *
+ * This middleware should be registered early in the chain to ensure all downstream handlers
+ * have access to the request ID.
+ *
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(requestId);
+ * // All requests now have a unique X-Request-ID header
+ * // Available in ctx.state.requestId for logging and tracing
+ */
+export async function requestId(ctx, next) {
+  // Use client-provided request ID if available (supports request tracing across service boundaries)
+  // Otherwise generate a new UUID for this request
+  const id = ctx.req.headers["x-request-id"] || randomUUID();
+  // Set response header so client can track the request
+  ctx.response.header("X-Request-ID", id);
+  // Attach to context state for access by other middleware (especially logger)
+  ctx.state.requestId = id;
+  await next();
+}

package/templates/ssr-isr/lib/middleware/builtins/security-headers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Security headers middleware that sets HTTP response headers for defense against common attacks.
+ * Implements a comprehensive security policy including:
+ * - Clickjacking protection (X-Frame-Options)
+ * - MIME type sniffing protection (X-Content-Type-Options)
+ * - XSS protection (X-XSS-Protection, Content-Security-Policy)
+ * - HTTPS enforcement (Strict-Transport-Security)
+ * - Referrer policy (Referrer-Policy)
+ * - Feature permissions (Permissions-Policy)
+ *
+ * CSP is configured permissively to work with most applications.
+ * Adjust directives based on your application's needs (inline scripts, external resources, etc.).
+ *
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(securityHeaders);
+ */
+export function securityHeaders(ctx: any, next: any): Promise<void>;

package/templates/ssr-isr/lib/middleware/builtins/security-headers.js

@@ -0,0 +1,53 @@
+/**
+ * Security headers middleware that sets HTTP response headers for defense against common attacks.
+ * Implements a comprehensive security policy including:
+ * - Clickjacking protection (X-Frame-Options)
+ * - MIME type sniffing protection (X-Content-Type-Options)
+ * - XSS protection (X-XSS-Protection, Content-Security-Policy)
+ * - HTTPS enforcement (Strict-Transport-Security)
+ * - Referrer policy (Referrer-Policy)
+ * - Feature permissions (Permissions-Policy)
+ *
+ * CSP is configured permissively to work with most applications.
+ * Adjust directives based on your application's needs (inline scripts, external resources, etc.).
+ *
+ * @returns Middleware function.
+ *
+ * @example
+ * kernel.use(securityHeaders);
+ */
+export async function securityHeaders(ctx, next) {
+  // Prevent DNS prefetch to reduce information leakage about visited sites.
+  ctx.response.header("X-DNS-Prefetch-Control", "off");
+  // Clickjacking protection. DENY prevents the page from being framed by any site.
+  ctx.response.header("X-Frame-Options", "DENY");
+  // HTTPS enforcement via HSTS. Tells browsers to always use HTTPS for this domain.
+  // max-age: 1 year, includeSubDomains: apply to all subdomains, preload: allow browser preload lists.
+  ctx.response.header(
+    "Strict-Transport-Security",
+    "max-age=31536000; includeSubDomains; preload",
+  );
+  // Prevent IE from opening files in unexpected applications.
+  ctx.response.header("X-Download-Options", "noopen");
+  // MIME type sniffing protection. Forces browsers to respect Content-Type header.
+  ctx.response.header("X-Content-Type-Options", "nosniff");
+  // XSS protection for older browsers that support X-XSS-Protection.
+  // Modern browsers use CSP instead, but this provides backward compatibility.
+  ctx.response.header("X-XSS-Protection", "1; mode=block");
+  // Referrer policy controls how much referrer information is sent to external sites.
+  ctx.response.header("Referrer-Policy", "strict-origin-when-cross-origin");
+  // Content Security Policy restricts which scripts, styles, and resources can load.
+  // This configuration allows self-origin for scripts and connect, includes unsafe-inline for styles.
+  // Adjust directives based on your application's needs (e.g., external CDNs, external APIs).
+  ctx.response.header(
+    "Content-Security-Policy",
+    "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self'; frame-ancestors 'none';",
+  );
+  // Permissions Policy (formerly Feature Policy) disables access to sensitive browser APIs.
+  // Disable: accelerometer, camera, geolocation, microphone, payment, etc.
+  ctx.response.header(
+    "Permissions-Policy",
+    "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()",
+  );
+  await next();
+}