astro-sessionkit 0.1.14 → 0.1.16

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";

package/src/integration.ts

@@ -0,0 +1,58 @@
+// ============================================================================
+// Astro Integration
+// ============================================================================
+
+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, SessionKitConfig } from "./core/types";

package/src/middleware.ts

@@ -0,0 +1,5 @@
+// ============================================================================
+// Middleware Entry Point
+// ============================================================================
+
+export { sessionMiddleware as onRequest } from "./core/sessionMiddleware";

package/src/server.ts

@@ -0,0 +1,245 @@
+// ============================================================================
+// Public Server API - Use these in your Astro components/endpoints
+// ============================================================================
+
+import {getContextStore} from "./core/context";
+import {isValidSessionStructure} from "./core/validation";
+import type {Session} from "./core/types";
+import type {APIContext} from "astro";
+
+/**
+ * Get the current session (returns null if not authenticated)
+ *
+ * @example
+ * ```ts
+ * // In .astro component
+ * const session = getSession();
+ * if (session) {
+ *   console.log('User ID:', session.userId);
+ * }
+ * ```
+ */
+export function getSession(): Session | null {
+    const context = getContextStore();
+    return context?.session ?? null;
+}
+
+/**
+ * Get the current session or throw if not authenticated
+ *
+ * @throws {Response} 401 Unauthorized if no session
+ *
+ * @example
+ * ```ts
+ * // In API endpoint
+ * const session = requireSession();
+ * // TypeScript knows session is not null here
+ * ```
+ */
+export function requireSession(): Session {
+    const session = getSession();
+
+    if (!session) {
+        throw new Response("Unauthorized", {status: 401});
+    }
+
+    return session;
+}
+
+/**
+ * Check if user is authenticated
+ */
+export function isAuthenticated(): boolean {
+    return getSession() !== null;
+}
+
+/**
+ * Check if user has a specific role
+ */
+export function hasRole(role: string): boolean {
+    const session = getSession();
+    if (!session) return false;
+
+    // Check primary role
+    if (session.role === role) return true;
+
+    // Check additional roles
+    return session.roles?.includes(role) ?? false;
+}
+
+/**
+ * Check if user has a specific permission
+ */
+export function hasPermission(permission: string): boolean {
+    const session = getSession();
+    if (!session) return false;
+
+    return session.permissions?.includes(permission) ?? false;
+}
+
+/**
+ * Check if user has ALL of the specified permissions
+ */
+export function hasAllPermissions(...permissions: string[]): boolean {
+    const session = getSession();
+    if (!session) return false;
+
+    const userPermissions = session.permissions ?? [];
+    return permissions.every((p) => userPermissions.includes(p));
+}
+
+/**
+ * Check if user has ANY of the specified permissions
+ */
+export function hasAnyPermission(...permissions: string[]): boolean {
+    const session = getSession();
+    if (!session) return false;
+
+    const userPermissions = session.permissions ?? [];
+    return permissions.some((p) => userPermissions.includes(p));
+}
+
+// ============================================================================
+// Session Management
+// ============================================================================
+
+/**
+ * Check if a specific role has a specific permission.
+ *
+ * This checks if the current user has the specified role and if that role
+ * is associated with the specified permission.
+ *
+ * @param role - The role to check
+ * @param permission - The permission to check
+ *
+ * @example
+ * ```ts
+ * if (hasRolePermission("admin", "delete users")) {
+ *   // ...
+ * }
+ * ```
+ */
+export function hasRolePermission(role: string, permission: string): boolean {
+    return hasRole(role) && hasPermission(permission);
+}
+
+/**
+ * Set session data in context.locals.session
+ *
+ * Use this after successful authentication to register the user's session.
+ * This does NOT handle session storage (cookies, Redis, etc.) - you must do that separately.
+ *
+ * @param context - Astro API context
+ * @param session - Session data to set
+ *
+ * @throws {Error} If session structure is invalid
+ *
+ * @example
+ * ```ts
+ * // In API endpoint after verifying credentials
+ * export const POST: APIRoute = async (context) => {
+ *   const { email, password } = await context.request.json();
+ *   const user = await verifyCredentials(email, password);
+ *
+ *   if (user) {
+ *     // Register session with SessionKit
+ *     setSession(context, {
+ *       userId: user.id,
+ *       email: user.email,
+ *       role: user.role,
+ *       permissions: user.permissions
+ *     });
+ *
+ *     // YOU must also store the session (cookie, Redis, etc.)
+ *     context.cookies.set('session_id', sessionId, { httpOnly: true });
+ *
+ *     return new Response(JSON.stringify({ success: true }));
+ *   }
+ * };
+ * ```
+ */
+export function setSession(context: APIContext, session: Session): void {
+    // Validate session structure
+    if (!isValidSessionStructure(session)) {
+        throw new Error(
+            '[SessionKit] Invalid session structure. Session must have a valid userId and follow the Session interface.'
+        );
+    }
+
+    // Set in context.locals for SessionKit middleware to read
+    context.session?.set('__session__', session);
+}
+
+/**
+ * Clear session from context.locals.session
+ *
+ * Use this during logout. This does NOT delete session storage (cookies, Redis, etc.) -
+ * you must do that separately.
+ *
+ * @param context - Astro API context
+ *
+ * @example
+ * ```ts
+ * // In logout endpoint
+ * export const POST: APIRoute = async (context) => {
+ *   // Clear from SessionKit
+ *   clearSession(context);
+ *
+ *   // YOU must also delete the session storage
+ *   context.cookies.delete('session_id');
+ *   await db.deleteSession(sessionId);
+ *
+ *   return context.redirect('/');
+ * };
+ * ```
+ */
+export function clearSession(context: APIContext): void {
+    context.session?.delete('__session__');
+}
+
+/**
+ * Update specific fields in the current session
+ *
+ * Useful for updating session data without replacing the entire session.
+ * The updated session is validated before being set.
+ *
+ * @param context - Astro API context
+ * @param updates - Partial session data to merge
+ *
+ * @throws {Error} If no session exists or updated session is invalid
+ *
+ * @example
+ * ```ts
+ * // Update user's role after promotion
+ * export const POST: APIRoute = async (context) => {
+ *   updateSession(context, {
+ *     role: 'admin',
+ *     permissions: ['admin:read', 'admin:write']
+ *   });
+ *
+ *   // YOU must also update session storage
+ *   await db.updateSession(sessionId, updatedData);
+ *
+ *   return new Response(JSON.stringify({ success: true }));
+ * };
+ * ```
+ */
+export function updateSession(context: APIContext, updates: Partial<Session>): void {
+    const currentSession = context.session?.get<Session>('__session__');
+
+    if (!currentSession) {
+        throw new Error('[SessionKit] Cannot update session: no session exists');
+    }
+
+    // Merge updates with current session
+    const updatedSession = {...currentSession, ...updates};
+
+    // Validate merged session
+    if (!isValidSessionStructure(updatedSession)) {
+        throw new Error(
+            '[SessionKit] Invalid session structure after update. Ensure all fields are valid.'
+        );
+    }
+
+    context.session?.set('__session__', updatedSession);
+}