astro-sessionkit 0.1.15 → 0.1.16

package/src/core/guardMiddleware.ts

@@ -0,0 +1,131 @@
+// ============================================================================
+// Route Guard Middleware - Enforces protection rules
+// ============================================================================
+
+import type {APIContext, MiddlewareHandler} from "astro";
+import { getContextStore } from "./context";
+import { getConfig } from "./config";
+import { matchesPattern } from "./matcher";
+import type { ProtectionRule, Session } from "./types";
+import { isValidSessionStructure } from "./validation";
+
+/**
+ * Check if session satisfies a protection rule
+ */
+async function checkRule(rule: ProtectionRule, session: Session | null): Promise<boolean> {
+  const { access } = getConfig();
+
+  // Custom check overrides everything
+  if (access.check) {
+    try {
+      return await access.check(rule, session);
+    } catch (error) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.error('[SessionKit] Error in custom access check hook:', error);
+      }
+      return false;
+    }
+  }
+
+  // Custom allow function
+  if ("allow" in rule) {
+    try {
+      return await rule.allow(session);
+    } catch (error) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.error('[SessionKit] Error in custom rule allow function:', error);
+      }
+      return false;
+    }
+  }
+
+  // Must be authenticated and have a valid session structure for all other checks
+  if (!session || !isValidSessionStructure(session)) {
+    return false;
+  }
+
+  // Single role check
+  if ("role" in rule) {
+    const userRole = access.getRole(session);
+    return userRole === rule.role;
+  }
+
+  // Multiple roles check (user must have ONE of these)
+  if ("roles" in rule) {
+    const userRole = access.getRole(session);
+    return userRole !== null && rule.roles.includes(userRole);
+  }
+
+  // Single permission check
+  if ("permission" in rule) {
+    const userPermissions = access.getPermissions(session);
+    return userPermissions.includes(rule.permission);
+  }
+
+  // Multiple permissions check (user must have ALL of these)
+  if ("permissions" in rule) {
+    const userPermissions = access.getPermissions(session);
+    return rule.permissions.every((p) => userPermissions.includes(p));
+  }
+
+  // No specific rule matched - allow by default
+  return true;
+}
+
+/**
+ * Create route guard middleware
+ */
+export function createGuardMiddleware(): MiddlewareHandler {
+  return async (context : APIContext, next) => {
+    const { protect, loginPath, globalProtect, exclude } = getConfig();
+    
+    // No rules configured and no global protect - skip
+    if (protect.length === 0 && !globalProtect) {
+      return next();
+    }
+
+    let pathname: string;
+    try {
+      pathname = new URL(context.request.url).pathname;
+    } catch {
+      // Fallback if URL is invalid (unlikely in Astro)
+      pathname = "/";
+    }
+    const sessionContext = getContextStore();
+    const session = sessionContext?.session ?? null;
+
+    // Find matching rule
+    const rule = protect.find((r) => matchesPattern(r.pattern, pathname));
+    
+    // No matching rule - check global protection
+    if (!rule) {
+      if (globalProtect) {
+        // Skip if path is in exclude list
+        if (exclude.some((pattern) => matchesPattern(pattern, pathname))) {
+          return next();
+        }
+        
+        // Skip if it's the login page itself (to avoid redirect loops)
+        if (pathname === loginPath) {
+          return next();
+        }
+
+        // Require valid session
+        if (!session || !isValidSessionStructure(session)) {
+          return context.redirect(loginPath);
+        }
+      }
+      return next();
+    }
+
+    // Check if access is allowed
+    const allowed = await checkRule(rule, session);
+
+    if (!allowed) {
+      const redirectTo = rule.redirectTo ?? loginPath;
+      return context.redirect(redirectTo);
+    }
+
+    return next();
+  };
+}

package/src/core/logger.ts

@@ -0,0 +1,31 @@
+import { getConfig } from "./config";
+
+/**
+ * Log message if debug mode is enabled
+ */
+export function debug(message: string, ...args: any[]): void {
+  const { debug } = getConfig();
+  if (debug) {
+    console.debug(`[SessionKit] ${message}`, ...args);
+  }
+}
+
+/**
+ * Log error message. Always logs unless in production, but can be forced via debug flag.
+ */
+export function error(message: string, ...args: any[]): void {
+  const { debug } = getConfig();
+  if (debug || process.env.NODE_ENV !== 'production') {
+    console.error(`[SessionKit] ${message}`, ...args);
+  }
+}
+
+/**
+ * Log warning message. Always logs unless in production, but can be forced via debug flag.
+ */
+export function warn(message: string, ...args: any[]): void {
+  const { debug } = getConfig();
+  if (debug || process.env.NODE_ENV !== 'production') {
+    console.warn(`[SessionKit] ${message}`, ...args);
+  }
+}

package/src/core/matcher.ts

@@ -0,0 +1,61 @@
+// ============================================================================
+// Route Pattern Matching
+// ============================================================================
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function globToRegex(pattern: string): RegExp {
+  let regex = "";
+  let i = 0;
+
+  while (i < pattern.length) {
+    const char = pattern[i];
+    const next = pattern[i + 1];
+
+    // Handle **
+    if (char === "*" && next === "*") {
+      const isAtEnd = i + 2 === pattern.length;
+      const prevIsSlash = i > 0 && pattern[i - 1] === "/";
+
+      if (prevIsSlash) {
+        // Handle "/**"
+        if (isAtEnd) {
+          // "/**" at end matches everything from that point
+          if (regex.endsWith("/")) regex = regex.slice(0, -1);
+          regex += "(?:/.*)?";
+        } else if (pattern[i + 2] === "/") {
+          // "/**/" matches zero or more segments
+          if (regex.endsWith("/")) regex = regex.slice(0, -1);
+          regex += "(?:/.*)?";
+          i += 1; // skip one extra for the trailing slash
+        } else {
+          regex += ".*";
+        }
+      } else {
+        regex += ".*";
+      }
+
+      i += 2;
+      continue;
+    }
+
+    // Handle *
+    if (char === "*") {
+      // one or more segments (to maintain backward compatibility with previous tests)
+      regex += "[^/]+(?:/[^/]+)*";
+      i += 1;
+      continue;
+    }
+
+    regex += escapeRegex(char as string);
+    i += 1;
+  }
+
+  return new RegExp(`^${regex}$`);
+}
+
+export function matchesPattern(pattern: string, path: string): boolean {
+  return globToRegex(pattern).test(path);
+}

package/src/core/sessionMiddleware.ts

@@ -0,0 +1,65 @@
+// ============================================================================
+// Session Middleware - Loads session into AsyncLocalStorage
+// ============================================================================
+
+import type {MiddlewareHandler} from "astro";
+import {runWithContext as defaultRunWithContext} from "./context";
+import {isValidSessionStructure} from "./validation";
+import type {Session} from "./types";
+import {getConfig} from "./config";
+import {warn} from "./logger";
+
+/**
+ * Session key used to store session in context.session
+ */
+const SESSION_KEY = "__session__";
+
+/**
+ * Main session middleware
+ *
+ * Reads session from context.session.get('__session__') and makes it available
+ * throughout the request via AsyncLocalStorage
+ */
+export const sessionMiddleware: MiddlewareHandler = async (context, next) => {
+    // Get session from context.session store
+    const rawSession = context.session?.get<Session>(SESSION_KEY) ?? null;
+
+    // Validate session structure if present
+    let session: Session | null = null;
+
+    if (rawSession) {
+        if (isValidSessionStructure(rawSession)) {
+            session = rawSession;
+        } else {
+            // Invalid session structure - log warning and treat as unauthenticated
+            warn(
+                'Invalid session structure detected. Session will be ignored. ' +
+                'Ensure context.session.set("__session__", ...) has the correct structure. ' +
+                'Received: ' + JSON.stringify(rawSession)
+            );
+            session = null;
+        }
+    }
+
+    // Run the rest of the request chain with session context
+    const config = getConfig();
+
+    // If getContextStore is provided, but runWithContext is NOT,
+    // we assume the user is managing the context at a superior level
+    // and we should NOT wrap the call in our default runner.
+    if (config.getContextStore && !config.runWithContext) {
+        // Initialize context store if setter is provided
+        const store = config.getContextStore();
+        if (store) {
+            store.session = session;
+        } else if (config.setContextStore) {
+            config.setContextStore({session});
+        } else if (process.env.NODE_ENV !== 'production') {
+            console.error('[SessionKit] getContextStore returned undefined, cannot set session');
+        }
+        return next();
+    }
+
+    const runner = config.runWithContext ?? defaultRunWithContext;
+    return runner({session}, () => next());
+};

package/src/core/types.ts

@@ -0,0 +1,147 @@
+// ============================================================================
+// Core Session Types
+// ============================================================================
+
+/**
+ * The session object stored in context.locals.session
+ * This is what your Astro app provides - we just read it.
+ */
+export interface Session {
+  /** Unique user identifier */
+  userId: string;
+
+  /** User's email (optional) */
+  email?: string;
+
+  /** Primary role */
+  role?: string;
+
+  /** Additional roles for multi-role scenarios */
+  roles?: string[];
+
+  /** Fine-grained permissions */
+  permissions?: string[];
+
+  /** Any additional custom data */
+  [key: string]: unknown;
+}
+
+/**
+ * What we store in AsyncLocalStorage
+ */
+export interface SessionContext {
+  session: Session | null;
+}
+
+// ============================================================================
+// Route Protection Rules
+// ============================================================================
+
+interface BaseProtectionRule {
+  /** Glob pattern for route matching: "/admin/**", "/dashboard/*", "/settings" */
+  pattern: string;
+
+  /** Where to redirect if access denied (defaults to global loginPath) */
+  redirectTo?: string;
+}
+
+/** Protect by single role */
+export interface RoleProtectionRule extends BaseProtectionRule {
+  role: string;
+}
+
+/** Protect by multiple roles (user must have ONE of these) */
+export interface RolesProtectionRule extends BaseProtectionRule {
+  roles: string[];
+}
+
+/** Protect by single permission */
+export interface PermissionProtectionRule extends BaseProtectionRule {
+  permission: string;
+}
+
+/** Protect by multiple permissions (user must have ALL of these) */
+export interface PermissionsProtectionRule extends BaseProtectionRule {
+  permissions: string[];
+}
+
+/** Protect with custom function */
+export interface CustomProtectionRule extends BaseProtectionRule {
+  allow: (session: Session | null) => boolean | Promise<boolean>;
+}
+
+/** Union of all protection rule types */
+export type ProtectionRule =
+  | RoleProtectionRule
+  | RolesProtectionRule
+  | PermissionProtectionRule
+  | PermissionsProtectionRule
+  | CustomProtectionRule;
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Optional hooks for custom role/permission extraction
+ */
+export interface AccessHooks {
+  /** Extract role from session (default: session.role) */
+  getRole?: (session: Session | null) => string | null;
+
+  /** Extract permissions from session (default: session.permissions ?? []) */
+  getPermissions?: (session: Session | null) => string[];
+
+  /** Custom access check that overrides all built-in logic */
+  check?: (rule: ProtectionRule, session: Session | null) => boolean | Promise<boolean>;
+}
+
+/**
+ * SessionKit configuration
+ */
+export interface SessionKitConfig {
+  /** Default redirect path for protected routes (default: "/login") */
+  loginPath?: string;
+
+  /** Route protection rules */
+  protect?: ProtectionRule[];
+
+  /** Custom access hooks */
+  access?: AccessHooks;
+
+  /** 
+   * Custom session context runner (optional)
+   * Use this to provide your own AsyncLocalStorage implementation or wrap the request
+   */
+  runWithContext?: <T>(context: SessionContext, fn: () => T) => T;
+
+  /**
+   * Custom session context getter (optional)
+   * Use this to provide your own way to retrieve the session context
+   */
+  getContextStore?: () => SessionContext | undefined;
+
+  /**
+   * Custom session context setter (optional)
+   * Use this to provide your own way to initialize the session context
+   */
+  setContextStore?: (context: SessionContext) => void;
+
+  /**
+   * Enable global session verification for all routes.
+   * If true, any route not explicitly ignored will require an active session.
+   * @default false
+   */
+  globalProtect?: boolean;
+
+  /**
+   * Routes to exclude from global protection (only if globalProtect is true)
+   */
+  exclude?: string[];
+
+  /**
+   * Enable debug logging
+   * @default false
+   */
+  debug?: boolean;
+}

package/src/core/validation.ts

@@ -0,0 +1,137 @@
+// ============================================================================
+// Security Validation Utilities
+// ============================================================================
+
+import type {Session} from "./types";
+
+/**
+ * Validate that session has the expected structure
+ * Prevents crashes from malformed data and DoS attacks
+ */
+export function isValidSessionStructure(input: unknown): input is Session {
+    // Must be an object
+    if (!input || typeof input !== 'object') {
+        return false;
+    }
+
+    const session = input as any;
+
+    // Required: userId must be a non-empty string
+    if (typeof session.userId !== 'string' || !session.userId.trim()) {
+        return false;
+    }
+
+    // DoS protection: Limit userId length
+    if (session.userId.length > 255) {
+        return false;
+    }
+
+    // Optional fields validation (if present)
+    if (session.email !== undefined) {
+        if (typeof session.email !== 'string') {
+            return false;
+        }
+        // Reasonable email length limit
+        if (session.email.length > 320) {
+            return false;
+        }
+    }
+
+    if (session.role !== undefined && session.role !== null) {
+        if (typeof session.role !== 'string') {
+            return false;
+        }
+        // Reasonable role length limit
+        if (session.role.length > 100) {
+            return false;
+        }
+    }
+
+    if (session.roles !== undefined && session.roles !== null) {
+        if (!Array.isArray(session.roles)) {
+            return false;
+        }
+        // DoS protection: Limit array size
+        if (session.roles.length > 100) {
+            return false;
+        }
+        // All items must be strings with reasonable length
+        if (!session.roles.every((r: any) => typeof r === 'string' && r.length <= 100)) {
+            return false;
+        }
+    }
+
+    if (session.permissions !== undefined && session.permissions !== null) {
+        if (!Array.isArray(session.permissions)) {
+            return false;
+        }
+        // DoS protection: Limit array size
+        if (session.permissions.length > 500) {
+            return false;
+        }
+        // All items must be strings with reasonable length
+        if (!session.permissions.every((p: any) => typeof p === 'string' && p.length <= 200)) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Validate route patterns to prevent ReDoS attacks
+ */
+export function isValidPattern(pattern: string): boolean {
+
+    if (typeof pattern !== 'string' || pattern.length === 0) return false;
+
+    // Length limit
+    if (pattern.length > 1000) return false;
+
+    // Must start with /
+    if (!pattern.startsWith("/")) return false;
+
+    // ReDoS protection: reject 4+ consecutive asterisks anywhere
+    if (/\*{4,}/.test(pattern)) return false;
+
+    // Additional sanity: ensure any '*' run is 1..3
+    for (let i = 0; i < pattern.length; i++) {
+        if (pattern[i] !== "*") continue;
+
+        let j = i;
+        while (j < pattern.length && pattern[j] === "*") j++;
+
+        const run = j - i; // consecutive '*'
+        if (run < 1 || run > 3) return false; // (4+ already blocked above)
+
+        // Optional: keep your patterns segment-oriented.
+        // Wildcards should not be glued to letters (e.g., "/**abc").
+        const next = pattern[j];
+        if (next !== undefined && next !== "/") return false;
+
+        i = j - 1;
+    }
+
+    return true;
+}
+
+/**
+ * Validate redirect path (open redirect protection)
+ */
+export function isValidRedirectPath(path: string): boolean {
+
+    if (typeof path !== 'string') return false;
+
+    // Reasonable length limit
+    if (path.length === 0 || path.length > 500) return false;
+
+    // Must be a site-relative path (exactly one leading slash)
+    // Reject protocol-relative URLs like "//example.com"
+    if (!path.startsWith("/") || path.startsWith("//")) return false;
+
+    // Extra hardening: reject anything that looks like a URL scheme
+    // (e.g. "http://", "https://", "javascript:", "data:", etc.)
+    return !/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(path);
+
+
+}

package/src/guard.ts

@@ -0,0 +1,7 @@
+// ============================================================================
+// Guard Middleware Entry Point
+// ============================================================================
+
+import { createGuardMiddleware } from "./core/guardMiddleware";
+
+export const onRequest = createGuardMiddleware();

package/src/index.ts

@@ -0,0 +1,78 @@
+// ============================================================================
+// Astro SessionKit - Main Integration Entry Point
+// ============================================================================
+
+import type {AstroIntegration } from "astro";
+import { setConfig } from "./core/config";
+import type { SessionKitConfig } from "./core/types";
+
+/**
+ * SessionKit - Simple session access and route protection for Astro
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import sessionkit from 'astro-sessionkit';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     sessionkit({
+ *       loginPath: '/login',
+ *       protect: [
+ *         { pattern: '/admin/**', role: 'admin' },
+ *         { pattern: '/dashboard', roles: ['user', 'admin'] },
+ *         { pattern: '/settings', permissions: ['settings:write'] }
+ *       ]
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+export default function sessionkit(config: SessionKitConfig = {}): AstroIntegration {
+    // Store configuration
+    setConfig(config);
+
+    return {
+        name: "astro-sessionkit",
+        hooks: {
+            "astro:config:setup": ({ addMiddleware }) => {
+                // 1. Always add session context middleware first
+                addMiddleware({
+                    entrypoint: "astro-sessionkit/middleware",
+                    order: "pre",
+                });
+
+                // 2. Add route guard if there are protection rules or global protection is enabled
+                if ((config.protect && config.protect.length > 0) || config.globalProtect) {
+                    addMiddleware({
+                        entrypoint: "astro-sessionkit/guard",
+                        order: "pre",
+                    });
+                }
+            },
+        },
+    };
+}
+
+// ============================================================================
+// Re-export types for convenience
+// ============================================================================
+
+export type {
+    Session,
+    ProtectionRule,
+    RoleProtectionRule,
+    RolesProtectionRule,
+    PermissionProtectionRule,
+    PermissionsProtectionRule,
+    CustomProtectionRule,
+    SessionKitConfig,
+    AccessHooks,
+    SessionContext
+} from "./core/types";
+
+// ============================================================================
+// Version export
+// ============================================================================
+
+export const version = "0.1.0";