create-jen-app 1.2.3 → 1.2.4

package/templates/static/lib/core/loader-schema.js

@@ -0,0 +1,81 @@
+/**
+ * Type-safe loader data schema pattern.
+ * Ensures loader return type matches component props type at compile time.
+ *
+ * @example
+ * ```typescript
+ * type PageData = { posts: Post[]; count: number };
+ *
+ * export const loader = defineLoader<PageData>(async (ctx) => {
+ *   return {
+ *     posts: await fetchPosts(),
+ *     count: 42,
+ *   };
+ * });
+ *
+ * export default function Page({ data }: { data: PageData }) {
+ *   return <div>{data.count} posts</div>;
+ * }
+ * ```
+ */
+export function defineLoader(handler) {
+  return async (ctx) => {
+    const result = handler(ctx);
+    return Promise.resolve(result);
+  };
+}
+/**
+ * Validates that loader data matches expected schema.
+ * Runtime check to catch type mismatches in development.
+ *
+ * @example
+ * ```typescript
+ * const data = validateLoaderData(result, { posts: 'array', count: 'number' });
+ * ```
+ */
+export function validateLoaderData(data, schema) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error(`Expected object, got ${typeof data}`);
+  }
+  const obj = data;
+  for (const [key, type] of Object.entries(schema)) {
+    const value = obj[key];
+    // Determine actual type (arrays are objects, so treat both as "object")
+    let actualType = typeof value;
+    if (value === null) {
+      actualType = "object"; // null is typeof 'object' in JavaScript
+    } else if (Array.isArray(value)) {
+      actualType = type === "array" ? "array" : "object";
+    }
+    if (actualType !== type) {
+      throw new Error(
+        `Loader data mismatch: expected ${key} to be ${type}, got ${actualType}`,
+      );
+    }
+  }
+  return obj;
+}
+/**
+ * Middleware data schema for type-safe middleware → loader flow.
+ *
+ * @example
+ * ```typescript
+ * type MiddlewareData = { userId: number; isAdmin: boolean };
+ * type PageData = { user: User; canDelete: boolean };
+ *
+ * export const middleware = defineMiddleware<MiddlewareData>(async (ctx) => {
+ *   return { userId: 42, isAdmin: true };
+ * });
+ *
+ * export const loader = defineLoader<PageData>(async (ctx) => {
+ *   const { userId, isAdmin } = ctx.data as MiddlewareData;
+ *   return { user: await getUser(userId), canDelete: isAdmin };
+ * });
+ * ```
+ */
+export function defineMiddleware(handler) {
+  return async (ctx) => {
+    const result = handler(ctx);
+    return Promise.resolve(result);
+  };
+}

package/templates/static/lib/core/middleware-hooks.js

@@ -1,20 +1,3 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 /**
  * Type definitions note:
  * Route module types (middleware field, hydrate field) are defined in core/types.ts.

package/templates/static/lib/core/paths.js

@@ -1,20 +1,3 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 import { join } from "node:path";
 /**
  * Resolve an absolute path relative to the configured site directory.

package/templates/static/lib/core/routes/advanced.js

@@ -0,0 +1,114 @@
+/**
+ * Cache for storing evaluated route configurations
+ */
+const advancedConfigCache = new Map();
+/**
+ * Extract advanced routing config from a route module
+ *
+ * @param module Route module
+ * @returns Advanced route configuration
+ */
+export function extractAdvancedConfig(module) {
+  return module?.routeConfig ?? {};
+}
+/**
+ * Get advanced route config with caching
+ *
+ * @param filePath Route file path
+ * @returns Cached or newly evaluated config
+ */
+export async function getAdvancedRouteConfig(filePath) {
+  if (advancedConfigCache.has(filePath)) {
+    return advancedConfigCache.get(filePath);
+  }
+  try {
+    const module = await import(`file://${filePath}`);
+    const config = extractAdvancedConfig(module);
+    advancedConfigCache.set(filePath, config);
+    return config;
+  } catch {
+    const config = {};
+    advancedConfigCache.set(filePath, config);
+    return config;
+  }
+}
+/**
+ * Synchronously get advanced route config
+ *
+ * @param filePath Route file path
+ * @returns Configuration (empty if unavailable)
+ */
+export function getAdvancedRouteConfigSync(filePath) {
+  if (advancedConfigCache.has(filePath)) {
+    return advancedConfigCache.get(filePath);
+  }
+  const config = {};
+  advancedConfigCache.set(filePath, config);
+  return config;
+}
+/**
+ * Clear the advanced config cache
+ */
+export function clearAdvancedConfigCache() {
+  advancedConfigCache.clear();
+}
+/**
+ * Validate query parameters against a schema
+ *
+ * @param query Parsed query parameters
+ * @param schema Validation rules
+ * @returns { valid: boolean; errors: string[] }
+ */
+export function validateQueryParams(query, schema) {
+  const errors = [];
+  for (const [key, rule] of Object.entries(schema)) {
+    const value = query[key];
+    // Check required
+    if (rule.required && !value) {
+      errors.push(`Query parameter '${key}' is required`);
+      continue;
+    }
+    if (!value) continue;
+    // Check type
+    if (rule.type === "number" && isNaN(Number(value))) {
+      errors.push(`Query parameter '${key}' must be a number`);
+    }
+    if (rule.type === "boolean" && !["true", "false"].includes(value)) {
+      errors.push(`Query parameter '${key}' must be 'true' or 'false'`);
+    }
+    // Check enum
+    if (rule.enum && !rule.enum.includes(value)) {
+      errors.push(
+        `Query parameter '${key}' must be one of: ${rule.enum.join(", ")}`,
+      );
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+/**
+ * Apply defaults and coerce query parameters
+ *
+ * @param query Raw query parameters
+ * @param schema Validation schema
+ * @returns Processed query parameters
+ */
+export function processQueryParams(query, schema) {
+  const processed = { ...query };
+  for (const [key, rule] of Object.entries(schema)) {
+    let value = processed[key];
+    // Apply default
+    if (!value && rule.default !== undefined) {
+      value = rule.default;
+      processed[key] = value;
+    }
+    // Coerce type
+    if (value) {
+      if (rule.type === "number") {
+        processed[key] = Number(value);
+      } else if (rule.type === "boolean") {
+        processed[key] = value === "true";
+      }
+    }
+  }
+  return processed;
+}

package/templates/static/lib/core/routes/handlers.js

@@ -0,0 +1,181 @@
+import { scanRoutes } from "./scan.js";
+/**
+ * Handles redirects configured at the application level
+ *
+ * @param pathname URL path to check
+ * @param redirects Array of redirect configurations
+ * @returns Redirect target or null
+ *
+ * @example
+ * const redirect = getRedirect("/old-page", [
+ *   { from: "/old-page", to: "/new-page", status: 301 }
+ * ]);
+ * // Returns: { to: "/new-page", status: 301 }
+ */
+export function getRedirect(pathname, redirects) {
+  for (const r of redirects) {
+    // Exact match
+    if (r.from === pathname) {
+      return { to: r.to, status: r.status ?? 301 };
+    }
+    // Prefix match (for pattern-based redirects)
+    if (r.from.endsWith("*")) {
+      const prefix = r.from.slice(0, -1);
+      if (pathname.startsWith(prefix)) {
+        // Preserve the remaining path
+        const remaining = pathname.slice(prefix.length);
+        const target = r.to.endsWith("*")
+          ? r.to.slice(0, -1) + remaining
+          : r.to;
+        return { to: target, status: r.status ?? 301 };
+      }
+    }
+  }
+  return null;
+}
+/**
+ * Send a redirect response
+ *
+ * @param res ServerResponse object
+ * @param location Target URL
+ * @param status HTTP status code (default 301)
+ */
+export function sendRedirect(res, location, status = 301) {
+  res.statusCode = status;
+  res.setHeader("Location", location);
+  res.setHeader("content-type", "text/plain; charset=utf-8");
+  res.end(`Redirecting to ${location}`);
+}
+/**
+ * Send a 404 response with optional custom handler
+ *
+ * @param res ServerResponse object
+ * @param config 404 handler configuration
+ * @param pathname The path that was not found
+ */
+export function send404(res, config, pathname) {
+  res.statusCode = 404;
+  // Prefer JSON response if available
+  if (config.json) {
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(config.json));
+    return;
+  }
+  // Fallback to HTML
+  if (config.html) {
+    res.setHeader("content-type", "text/html; charset=utf-8");
+    res.end(config.html);
+    return;
+  }
+  // Default 404 response
+  res.setHeader("content-type", "text/plain; charset=utf-8");
+  res.end(`404 Not Found: ${pathname}`);
+}
+/**
+ * Find a custom 404 handler for a given pathname
+ * Searches the route tree for a matching 404 handler route
+ *
+ * @param config Framework configuration
+ * @param pathname URL path that was not found
+ * @returns NotFoundConfig with appropriate handler or null
+ *
+ * @example
+ * // With routes:
+ * // - (home).tsx
+ * // - /docs/(...rest).tsx (handles docs with custom 404)
+ * // - /api/(...rest).tsx (handles api with custom 404)
+ *
+ * // getNotFoundHandler(config, "/api/unknown") returns handler for /api/(...rest)
+ */
+export function getNotFoundHandler(config, pathname) {
+  const routes = scanRoutes(config);
+  // Find catch-all routes that match this pathname
+  let bestMatch = null;
+  let bestMatchLength = 0;
+  for (const route of routes) {
+    // Check if this is a catch-all route
+    if (!route.urlPath.includes("*")) continue;
+    // Extract the prefix before the catch-all
+    const prefix = route.urlPath.split("*")[0];
+    if (!prefix) continue; // Skip root catch-all for now
+    // Check if pathname matches this prefix
+    if (pathname.startsWith(prefix)) {
+      if (prefix.length > bestMatchLength) {
+        bestMatch = route;
+        bestMatchLength = prefix.length;
+      }
+    }
+  }
+  if (bestMatch) {
+    return { handler: bestMatch };
+  }
+  return null;
+}
+/**
+ * Create a default 404 HTML page
+ *
+ * @param pathname Path that was not found
+ * @returns HTML string
+ */
+export function createDefault404Html(pathname) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>404 Not Found</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      margin: 0;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    }
+    .container {
+      text-align: center;
+      background: white;
+      padding: 2rem;
+      border-radius: 8px;
+      box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+    }
+    h1 {
+      font-size: 3rem;
+      margin: 0;
+      color: #333;
+    }
+    p {
+      margin: 1rem 0 0 0;
+      color: #666;
+    }
+    .path {
+      font-family: monospace;
+      background: #f5f5f5;
+      padding: 0.5rem 1rem;
+      margin: 1rem 0;
+      border-radius: 4px;
+      color: #333;
+    }
+    a {
+      color: #667eea;
+      text-decoration: none;
+      margin-top: 1rem;
+      display: inline-block;
+    }
+    a:hover {
+      text-decoration: underline;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>404</h1>
+    <p>Page Not Found</p>
+    <div class="path">${pathname}</div>
+    <a href="/">Go Home</a>
+  </div>
+</body>
+</html>`;
+}

package/templates/static/lib/core/routes/match.js

@@ -1,20 +1,78 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
+/**
+ * Custom error type for invalid route parameters
+ */
+export class InvalidRouteParamError extends Error {
+  constructor(paramName, paramValue, reason) {
+    super(`Invalid route parameter "${paramName}": ${reason}`);
+    this.name = "InvalidRouteParamError";
+  }
+}
+/**
+ * Validates a route parameter to prevent path traversal and injection attacks.
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
+ * Security checks:
+ * - Rejects ".." (directory traversal)
+ * - Rejects leading "/" (absolute paths)
+ * - Rejects null bytes (\0)
+ * - Rejects unicode encoding tricks (e.g., %2e%2e are decoded by decodeURIComponent first)
+ * - For catch-all routes (*rest), allows "/" and other separators but still rejects traversal
+ * - For regular params, only allows alphanumeric, underscore, hyphen, dot
  *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * @param paramName Parameter name (e.g., "id", "rest")
+ * @param paramValue The decoded parameter value
+ * @param isCatchAll Whether this is a catch-all route parameter (allows more characters)
+ * @throws InvalidRouteParamError if validation fails
  */
+export function validateRouteParam(paramName, paramValue, isCatchAll = false) {
+  // Check for null bytes
+  if (paramValue.includes("\0")) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "contains null bytes",
+    );
+  }
+  // Check for leading forward slash (absolute path)
+  if (paramValue.startsWith("/")) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "cannot start with /",
+    );
+  }
+  // Check for directory traversal: ".." as a complete component or at any position
+  if (paramValue.includes("..")) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "contains .. (directory traversal)",
+    );
+  }
+  // Check for backslash (Windows path separator) to prevent escaping
+  if (paramValue.includes("\\")) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "contains backslash",
+    );
+  }
+  // For catch-all parameters, allow more flexible paths with /, but still reject dangerous patterns
+  if (isCatchAll) {
+    // Additional check: if someone passes %2e%2e or other encoded traversal, it's already decoded
+    // by decodeURIComponent, so the ".." check above will catch it. Just verify no empty path components
+    // that could indicate traversal (though ".." is already blocked above)
+    return;
+  }
+  // For regular route parameters, only allow safe characters
+  // Allow: alphanumeric, underscore, hyphen, dot
+  if (!/^[a-zA-Z0-9_.-]+$/.test(paramValue)) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "contains invalid characters (only alphanumeric, underscore, hyphen, dot allowed)",
+    );
+  }
+}
 /**
  * Matches a URL pathname against a list of routes and returns the matching route with extracted parameters.
  *
@@ -23,7 +81,8 @@
  * 2. For each route, compile its regex pattern and test against pathname
  * 3. On first match, extract captured groups as parameters
  * 4. URL-decode parameter values to handle special characters
- * 5. Return matched route and parameters
+ * 5. Validate all parameters to prevent path traversal attacks
+ * 6. Return matched route and parameters
  *
  * Route specificity:
  * - Static routes (no parameters) are tried before dynamic routes
@@ -34,6 +93,7 @@
  * @param pathname URL path to match, e.g., "/posts/42" or "/docs/api/reference"
  *
  * @returns MatchResult object with matched route and parameters, or null if no route matches
+ * @throws InvalidRouteParamError if any parameter contains invalid/dangerous content
  *
  * @example
  * const routes = scanRoutes(config);
@@ -47,16 +107,28 @@ export function matchRoute(routes, pathname) {
   for (const r of routes) {
     const re = new RegExp(r.pattern);
     const m = pathname.match(re);
-    if (!m) continue;
+    if (!m) {
+      console.error(
+        `[Route Match] Pattern "${r.pattern}" did not match "${pathname}"`,
+      );
+      continue;
+    }
     /**
      * Extract captured groups from the regex match.
      * Captured group 0 is the entire match; groups 1+ are the parameters.
      * Each parameter name from r.paramNames corresponds to its regex group by index.
      * URL-decode parameter values since they came from a URL path.
+     * Then validate each parameter to prevent path traversal attacks.
      */
     const params = {};
     for (let i = 0; i < r.paramNames.length; i++) {
-      params[r.paramNames[i]] = decodeURIComponent(m[i + 1] ?? "");
+      const paramName = r.paramNames[i];
+      const paramValue = decodeURIComponent(m[i + 1] ?? "");
+      // Determine if this is a catch-all parameter (typically named "rest" or ends with "*")
+      const isCatchAll = paramName === "rest" || r.pattern.includes("*");
+      // Validate the parameter to prevent path traversal and injection attacks
+      validateRouteParam(paramName, paramValue, isCatchAll);
+      params[paramName] = paramValue;
     }
     return { route: r, params };
   }