astro-sessionkit 0.1.14 → 0.1.16

package/src/core/config.ts

@@ -0,0 +1,153 @@
+// ============================================================================
+// Configuration Store
+// ============================================================================
+
+import type {SessionKitConfig, AccessHooks, ProtectionRule, Session, SessionContext} from "./types";
+import {isValidPattern, isValidRedirectPath} from "./validation";
+
+/**
+ * Internal config with defaults applied
+ */
+export interface ResolvedConfig {
+    loginPath: string;
+    protect: ProtectionRule[];
+    access: Required<Omit<AccessHooks, "check">> & {
+        check?: AccessHooks["check"];
+    };
+    runWithContext?: <T>(context: SessionContext, fn: () => T) => T | Promise<T>;
+    getContextStore?: () => SessionContext | undefined;
+    setContextStore?: (context: SessionContext) => void;
+    globalProtect: boolean;
+    exclude: string[];
+    debug: boolean;
+}
+
+const DEFAULT_CONFIG: ResolvedConfig = {
+    loginPath: "/login",
+    protect: [],
+    access: {
+        getRole: (session: Session | null) => session?.role ?? null,
+        getPermissions: (session: Session | null) => session?.permissions ?? [],
+        check: undefined,
+    },
+    globalProtect: false,
+    exclude: [],
+    debug: false,
+};
+
+let config: ResolvedConfig = { ...DEFAULT_CONFIG };
+
+/**
+ * Set configuration (called by integration)
+ */
+export function setConfig(userConfig: SessionKitConfig): void {
+    // Start with default config
+    const newConfig: ResolvedConfig = { ...DEFAULT_CONFIG };
+
+    // Validate and set loginPath
+    if (userConfig.loginPath !== undefined) {
+        if (!isValidRedirectPath(userConfig.loginPath)) {
+            throw new Error(
+                `[SessionKit] Invalid loginPath: "${userConfig.loginPath}". Must start with / and be less than 500 characters.`
+            );
+        }
+        newConfig.loginPath = userConfig.loginPath;
+    }
+
+    // Validate protection rules
+    if (userConfig.protect) {
+        for (const rule of userConfig.protect) {
+            // Validate pattern
+            if (!isValidPattern(rule.pattern)) {
+                throw new Error(
+                    `[SessionKit] Invalid pattern: "${rule.pattern}". ` +
+                    `Patterns must start with / and be less than 1000 characters.`
+                );
+            }
+
+            // Validate redirectTo if present
+            if (rule.redirectTo && !isValidRedirectPath(rule.redirectTo)) {
+                throw new Error(
+                    `[SessionKit] Invalid redirectTo: "${rule.redirectTo}". ` +
+                    `Must start with / and be less than 500 characters.`
+                );
+            }
+        }
+        newConfig.protect = [...userConfig.protect];
+    }
+
+    // Validate context store getter/setter pair
+    if ((userConfig.getContextStore && !userConfig.setContextStore) || (!userConfig.getContextStore && userConfig.setContextStore)) {
+        throw new Error(
+            '[SessionKit] Both getContextStore and setContextStore must be provided together if using custom context storage.'
+        );
+    }
+
+    // Set access hooks
+    if (userConfig.access) {
+        newConfig.access = {
+            getRole: userConfig.access.getRole ?? DEFAULT_CONFIG.access.getRole,
+            getPermissions: userConfig.access.getPermissions ?? DEFAULT_CONFIG.access.getPermissions,
+            check: userConfig.access.check,
+        };
+
+        // Migration/Safety: If user misplaced globalProtect/exclude/debug in access object,
+        // we honor them but warn about it.
+        const anyAccess = userConfig.access as any;
+        if (anyAccess.globalProtect !== undefined && userConfig.globalProtect === undefined) {
+            newConfig.globalProtect = anyAccess.globalProtect;
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn('[SessionKit] Deprecation: globalProtect should be at the top level of configuration, not inside "access".');
+            }
+        }
+        if (anyAccess.exclude !== undefined && userConfig.exclude === undefined) {
+            newConfig.exclude = anyAccess.exclude;
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn('[SessionKit] Deprecation: exclude should be at the top level of configuration, not inside "access".');
+            }
+        }
+        if (anyAccess.debug !== undefined && userConfig.debug === undefined) {
+            newConfig.debug = anyAccess.debug;
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn('[SessionKit] Deprecation: debug should be at the top level of configuration, not inside "access".');
+            }
+        }
+    }
+
+    // Set context hooks
+    newConfig.runWithContext = userConfig.runWithContext;
+    newConfig.getContextStore = userConfig.getContextStore;
+    newConfig.setContextStore = userConfig.setContextStore;
+    
+    if (userConfig.globalProtect !== undefined) {
+        newConfig.globalProtect = userConfig.globalProtect;
+    }
+
+    if (userConfig.exclude !== undefined) {
+        for (const pattern of userConfig.exclude) {
+            if (!isValidPattern(pattern)) {
+                throw new Error(
+                    `[SessionKit] Invalid exclude pattern: "${pattern}". ` +
+                    `Patterns must start with / and be less than 1000 characters.`
+                );
+            }
+        }
+        newConfig.exclude = [...userConfig.exclude];
+    } else if (newConfig.exclude.length === 0) {
+        newConfig.exclude = [...DEFAULT_CONFIG.exclude];
+    }
+
+    if (userConfig.debug !== undefined) {
+        newConfig.debug = userConfig.debug;
+    }
+
+    // Atomic update
+    config = Object.freeze(newConfig);
+}
+
+/**
+ * Get current configuration
+ */
+export function getConfig(): ResolvedConfig {
+    return config;
+}

package/src/core/context.ts

@@ -0,0 +1,30 @@
+// ============================================================================
+// Session Context (AsyncLocalStorage)
+// ============================================================================
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { SessionContext } from "./types";
+import { getConfig } from "./config";
+
+const als = new AsyncLocalStorage<SessionContext>();
+
+/**
+ * Run a function with session context available
+ */
+export function runWithContext<T>(
+  context: SessionContext,
+  fn: () => T
+): T {
+  return als.run(context, fn);
+}
+
+/**
+ * Get the current session context (only available inside middleware chain)
+ */
+export function getContextStore(): SessionContext | undefined {
+  const customGetter = getConfig().getContextStore;
+  if (customGetter) {
+    return customGetter();
+  }
+  return als.getStore();
+}

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;
+}