astro-sessionkit 0.1.20 → 0.1.21

package/dist/index.d.ts

@@ -1,5 +1,11 @@
-import { AstroIntegration } from 'astro';
+import { AstroCookies, AstroSession, AstroIntegration } from 'astro';
 
+interface SessionKitContext {
+    cookies: AstroCookies;
+    session?: AstroSession;
+    redirect: (path: string, status?: number) => Response;
+    [key: string]: any;
+}
 interface Session {
     userId: string;
     email?: string;
@@ -10,6 +16,7 @@ interface Session {
 }
 interface SessionContext {
     session: Session | null;
+    astroContext?: SessionKitContext;
 }
 interface BaseProtectionRule {
     pattern: string;
@@ -45,6 +52,7 @@ interface SessionKitConfig {
     setContextStore?: (context: SessionContext) => void;
     globalProtect?: boolean;
     exclude?: string[];
+    context?: any;
     debug?: boolean;
 }
 

package/dist/server.d.ts

@@ -1,5 +1,11 @@
-import { APIContext } from 'astro';
+import { AstroCookies, AstroSession } from 'astro';
 
+interface SessionKitContext {
+    cookies: AstroCookies;
+    session?: AstroSession;
+    redirect: (path: string, status?: number) => Response;
+    [key: string]: any;
+}
 interface Session {
     userId: string;
     email?: string;
@@ -17,8 +23,9 @@ declare function hasPermission(permission: string): boolean;
 declare function hasAllPermissions(...permissions: string[]): boolean;
 declare function hasAnyPermission(...permissions: string[]): boolean;
 declare function hasRolePermission(role: string, permission: string): boolean;
-declare function setSession(context: APIContext, session: Session): void;
-declare function clearSession(context: APIContext): void;
-declare function updateSession(context: APIContext, updates: Partial<Session>): void;
+declare function setSession(session: Session, context?: SessionKitContext): void;
+declare function clearSession(context?: SessionKitContext): void;
+declare function regenerateSession(context?: SessionKitContext): void;
+declare function updateSession(updates: Partial<Session>, context?: SessionKitContext): void;
 
-export { clearSession, getSession, hasAllPermissions, hasAnyPermission, hasPermission, hasRole, hasRolePermission, isAuthenticated, requireSession, setSession, updateSession };
+export { clearSession, getSession, hasAllPermissions, hasAnyPermission, hasPermission, hasRole, hasRolePermission, isAuthenticated, regenerateSession, requireSession, setSession, updateSession };

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,OAAO,CAAC;AActC,wBAAgB,UAAU,IAAI,OAAO,GAAG,IAAI,CAG3C;AAcD,wBAAgB,cAAc,IAAI,OAAO,CAQxC;AAKD,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAKD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAS7C;AAKD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAKzD;AAKD,wBAAgB,iBAAiB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAMnE;AAKD,wBAAgB,gBAAgB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAMlE;AAsBD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE3E;AAqCD,wBAAgB,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAUtE;AAyBD,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAEtD;AA6BD,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAkBlF"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,cAAc,CAAC;AAc7D,wBAAgB,UAAU,IAAI,OAAO,GAAG,IAAI,CAG3C;AAcD,wBAAgB,cAAc,IAAI,OAAO,CAQxC;AAKD,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAKD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAS7C;AAKD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAKzD;AAKD,wBAAgB,iBAAiB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAMnE;AAKD,wBAAgB,gBAAgB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAMlE;AAsBD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE3E;AAqCD,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAyB9E;AAyBD,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAiB9D;AAyBD,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAanE;AA6BD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAmC1F"}

package/dist/server.js

@@ -46,26 +46,61 @@ function hasAnyPermission(...permissions) {
 function hasRolePermission(role, permission) {
     return hasRole(role) && hasPermission(permission);
 }
-function setSession(context, session) {
+function setSession(session, context) {
+    const store = getContextStore();
+    const ctx = context || store?.astroContext;
+    if (!ctx) {
+        throw new Error('[SessionKit] Cannot set session: Astro context is missing. ' +
+            'Provide it as a second argument or ensure sessionMiddleware is running.');
+    }
     if (!isValidSessionStructure(session)) {
         throw new Error('[SessionKit] Invalid session structure. Session must have a valid userId and follow the Session interface.');
     }
-    context.session?.set('__session__', session);
+    if (store) {
+        store.session = session;
+    }
+    ctx.session?.set('__session__', session);
 }
 function clearSession(context) {
-    context.session?.delete('__session__');
+    const store = getContextStore();
+    const ctx = context || store?.astroContext;
+    if (!ctx) {
+        throw new Error('[SessionKit] Cannot clear session: Astro context is missing. ' +
+            'Provide it as an argument or ensure sessionMiddleware is running.');
+    }
+    if (store) {
+        store.session = null;
+    }
+    ctx.session?.delete('__session__');
+}
+function regenerateSession(context) {
+    const ctx = context || getContextStore()?.astroContext;
+    if (!ctx) {
+        throw new Error('[SessionKit] Cannot regenerate session: Astro context is missing. ' +
+            'Provide it as an argument or ensure sessionMiddleware is running.');
+    }
+    if (ctx.session?.regenerate) {
+        ctx.session.regenerate();
+    }
 }
-function updateSession(context, updates) {
-    const currentSession = context.session?.get('__session__');
-    if (!currentSession) {
-        throw new Error('[SessionKit] Cannot update session: no session exists');
+function updateSession(updates, context) {
+    const store = getContextStore();
+    const ctx = context || store?.astroContext;
+    if (!ctx) {
+        throw new Error('[SessionKit] Cannot update session: Astro context is missing. ' +
+            'Provide it as a second argument or ensure sessionMiddleware is running.');
     }
-    const updatedSession = { ...currentSession, ...updates };
-    if (!isValidSessionStructure(updatedSession)) {
-        throw new Error('[SessionKit] Invalid session structure after update. Ensure all fields are valid.');
+    const currentSession = store?.session || ctx.session?.get('__session__');
+    if (!currentSession || (currentSession instanceof Promise)) {
+        const session = currentSession instanceof Promise ? null : currentSession;
+        if (!session) {
+            throw new Error('[SessionKit] Cannot update session: no session exists');
+        }
     }
-    context.session?.set('__session__', updatedSession);
+    const session = currentSession;
+    const updatedSession = { ...session, ...updates };
+    setSession(updatedSession, ctx);
 }
 
-export { clearSession, getSession, hasAllPermissions, hasAnyPermission, hasPermission, hasRole, hasRolePermission, isAuthenticated, requireSession, setSession, updateSession };
+export { clearSession, getSession, hasAllPermissions, hasAnyPermission, hasPermission, hasRole, hasRolePermission, isAuthenticated, regenerateSession, requireSession, setSession, updateSession };
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sources":["../src/server.ts"],"sourcesContent":["// ============================================================================\n// Public Server API - Use these in your Astro components/endpoints\n// ============================================================================\n\nimport {getContextStore} from \"./core/context\";\nimport {isValidSessionStructure} from \"./core/validation\";\nimport type {Session} from \"./core/types\";\nimport type {APIContext} from \"astro\";\n\n/**\n * Get the current session (returns null if not authenticated)\n *\n * @example\n * ```ts\n * // In .astro component\n * const session = getSession();\n * if (session) {\n *   console.log('User ID:', session.userId);\n * }\n * ```\n */\nexport function getSession(): Session | null {\n    const context = getContextStore();\n    return context?.session ?? null;\n}\n\n/**\n * Get the current session or throw if not authenticated\n *\n * @throws {Response} 401 Unauthorized if no session\n *\n * @example\n * ```ts\n * // In API endpoint\n * const session = requireSession();\n * // TypeScript knows session is not null here\n * ```\n */\nexport function requireSession(): Session {\n    const session = getSession();\n\n    if (!session) {\n        throw new Response(\"Unauthorized\", {status: 401});\n    }\n\n    return session;\n}\n\n/**\n * Check if user is authenticated\n */\nexport function isAuthenticated(): boolean {\n    return getSession() !== null;\n}\n\n/**\n * Check if user has a specific role\n */\nexport function hasRole(role: string): boolean {\n    const session = getSession();\n    if (!session) return false;\n\n    // Check primary role\n    if (session.role === role) return true;\n\n    // Check additional roles\n    return session.roles?.includes(role) ?? false;\n}\n\n/**\n * Check if user has a specific permission\n */\nexport function hasPermission(permission: string): boolean {\n    const session = getSession();\n    if (!session) return false;\n\n    return session.permissions?.includes(permission) ?? false;\n}\n\n/**\n * Check if user has ALL of the specified permissions\n */\nexport function hasAllPermissions(...permissions: string[]): boolean {\n    const session = getSession();\n    if (!session) return false;\n\n    const userPermissions = session.permissions ?? [];\n    return permissions.every((p) => userPermissions.includes(p));\n}\n\n/**\n * Check if user has ANY of the specified permissions\n */\nexport function hasAnyPermission(...permissions: string[]): boolean {\n    const session = getSession();\n    if (!session) return false;\n\n    const userPermissions = session.permissions ?? [];\n    return permissions.some((p) => userPermissions.includes(p));\n}\n\n// ============================================================================\n// Session Management\n// ============================================================================\n\n/**\n * Check if a specific role has a specific permission.\n *\n * This checks if the current user has the specified role and if that role\n * is associated with the specified permission.\n *\n * @param role - The role to check\n * @param permission - The permission to check\n *\n * @example\n * ```ts\n * if (hasRolePermission(\"admin\", \"delete users\")) {\n *   // ...\n * }\n * ```\n */\nexport function hasRolePermission(role: string, permission: string): boolean {\n    return hasRole(role) && hasPermission(permission);\n}\n\n/**\n * Set session data in context.locals.session\n *\n * Use this after successful authentication to register the user's session.\n * This does NOT handle session storage (cookies, Redis, etc.) - you must do that separately.\n *\n * @param context - Astro API context\n * @param session - Session data to set\n *\n * @throws {Error} If session structure is invalid\n *\n * @example\n * ```ts\n * // In API endpoint after verifying credentials\n * export const POST: APIRoute = async (context) => {\n *   const { email, password } = await context.request.json();\n *   const user = await verifyCredentials(email, password);\n *\n *   if (user) {\n *     // Register session with SessionKit\n *     setSession(context, {\n *       userId: user.id,\n *       email: user.email,\n *       role: user.role,\n *       permissions: user.permissions\n *     });\n *\n *     // YOU must also store the session (cookie, Redis, etc.)\n *     context.cookies.set('session_id', sessionId, { httpOnly: true });\n *\n *     return new Response(JSON.stringify({ success: true }));\n *   }\n * };\n * ```\n */\nexport function setSession(context: APIContext, session: Session): void {\n    // Validate session structure\n    if (!isValidSessionStructure(session)) {\n        throw new Error(\n            '[SessionKit] Invalid session structure. Session must have a valid userId and follow the Session interface.'\n        );\n    }\n\n    // Set in context.locals for SessionKit middleware to read\n    context.session?.set('__session__', session);\n}\n\n/**\n * Clear session from context.locals.session\n *\n * Use this during logout. This does NOT delete session storage (cookies, Redis, etc.) -\n * you must do that separately.\n *\n * @param context - Astro API context\n *\n * @example\n * ```ts\n * // In logout endpoint\n * export const POST: APIRoute = async (context) => {\n *   // Clear from SessionKit\n *   clearSession(context);\n *\n *   // YOU must also delete the session storage\n *   context.cookies.delete('session_id');\n *   await db.deleteSession(sessionId);\n *\n *   return context.redirect('/');\n * };\n * ```\n */\nexport function clearSession(context: APIContext): void {\n    context.session?.delete('__session__');\n}\n\n/**\n * Update specific fields in the current session\n *\n * Useful for updating session data without replacing the entire session.\n * The updated session is validated before being set.\n *\n * @param context - Astro API context\n * @param updates - Partial session data to merge\n *\n * @throws {Error} If no session exists or updated session is invalid\n *\n * @example\n * ```ts\n * // Update user's role after promotion\n * export const POST: APIRoute = async (context) => {\n *   updateSession(context, {\n *     role: 'admin',\n *     permissions: ['admin:read', 'admin:write']\n *   });\n *\n *   // YOU must also update session storage\n *   await db.updateSession(sessionId, updatedData);\n *\n *   return new Response(JSON.stringify({ success: true }));\n * };\n * ```\n */\nexport function updateSession(context: APIContext, updates: Partial<Session>): void {\n    const currentSession = context.session?.get<Session>('__session__');\n\n    if (!currentSession) {\n        throw new Error('[SessionKit] Cannot update session: no session exists');\n    }\n\n    // Merge updates with current session\n    const updatedSession = {...currentSession, ...updates};\n\n    // Validate merged session\n    if (!isValidSessionStructure(updatedSession)) {\n        throw new Error(\n            '[SessionKit] Invalid session structure after update. Ensure all fields are valid.'\n        );\n    }\n\n    context.session?.set('__session__', updatedSession);\n}"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sources":["../src/server.ts"],"sourcesContent":["// ============================================================================\n// Public Server API - Use these in your Astro components/endpoints\n// ============================================================================\n\nimport {getContextStore} from \"./core/context\";\nimport {isValidSessionStructure} from \"./core/validation\";\nimport type {Session, SessionKitContext} from \"./core/types\";\n\n/**\n * Get the current session (returns null if not authenticated)\n *\n * @example\n * ```ts\n * // In .astro component\n * const session = getSession();\n * if (session) {\n *   console.log('User ID:', session.userId);\n * }\n * ```\n */\nexport function getSession(): Session | null {\n    const context = getContextStore();\n    return context?.session ?? null;\n}\n\n/**\n * Get the current session or throw if not authenticated\n *\n * @throws {Response} 401 Unauthorized if no session\n *\n * @example\n * ```ts\n * // In API endpoint\n * const session = requireSession();\n * // TypeScript knows session is not null here\n * ```\n */\nexport function requireSession(): Session {\n    const session = getSession();\n\n    if (!session) {\n        throw new Response(\"Unauthorized\", {status: 401});\n    }\n\n    return session;\n}\n\n/**\n * Check if user is authenticated\n */\nexport function isAuthenticated(): boolean {\n    return getSession() !== null;\n}\n\n/**\n * Check if user has a specific role\n */\nexport function hasRole(role: string): boolean {\n    const session = getSession();\n    if (!session) return false;\n\n    // Check primary role\n    if (session.role === role) return true;\n\n    // Check additional roles\n    return session.roles?.includes(role) ?? false;\n}\n\n/**\n * Check if user has a specific permission\n */\nexport function hasPermission(permission: string): boolean {\n    const session = getSession();\n    if (!session) return false;\n\n    return session.permissions?.includes(permission) ?? false;\n}\n\n/**\n * Check if user has ALL of the specified permissions\n */\nexport function hasAllPermissions(...permissions: string[]): boolean {\n    const session = getSession();\n    if (!session) return false;\n\n    const userPermissions = session.permissions ?? [];\n    return permissions.every((p) => userPermissions.includes(p));\n}\n\n/**\n * Check if user has ANY of the specified permissions\n */\nexport function hasAnyPermission(...permissions: string[]): boolean {\n    const session = getSession();\n    if (!session) return false;\n\n    const userPermissions = session.permissions ?? [];\n    return permissions.some((p) => userPermissions.includes(p));\n}\n\n// ============================================================================\n// Session Management\n// ============================================================================\n\n/**\n * Check if a specific role has a specific permission.\n *\n * This checks if the current user has the specified role and if that role\n * is associated with the specified permission.\n *\n * @param role - The role to check\n * @param permission - The permission to check\n *\n * @example\n * ```ts\n * if (hasRolePermission(\"admin\", \"delete users\")) {\n *   // ...\n * }\n * ```\n */\nexport function hasRolePermission(role: string, permission: string): boolean {\n    return hasRole(role) && hasPermission(permission);\n}\n\n/**\n * Set session data in context.locals.session\n *\n * Use this after successful authentication to register the user's session.\n * This does NOT handle session storage (cookies, Redis, etc.) - you must do that separately.\n *\n * @param session - Session data to set\n * @param context - Astro API context (optional if called within request context)\n *\n * @throws {Error} If session structure is invalid or context missing\n *\n * @example\n * ```ts\n * // In API endpoint after verifying credentials\n * export const POST: APIRoute = async (context) => {\n *   const { email, password } = await context.request.json();\n *   const user = await verifyCredentials(email, password);\n *\n *   if (user) {\n *     // Register session with SessionKit\n *     setSession({\n *       userId: user.id,\n *       email: user.email,\n *       role: user.role,\n *       permissions: user.permissions\n *     });\n *\n *     // YOU must also store the session (cookie, Redis, etc.)\n *     context.cookies.set('session_id', sessionId, { httpOnly: true });\n *\n *     return new Response(JSON.stringify({ success: true }));\n *   }\n * };\n * ```\n */\nexport function setSession(session: Session, context?: SessionKitContext): void {\n    const store = getContextStore();\n    const ctx = context || store?.astroContext;\n\n    if (!ctx) {\n        throw new Error(\n            '[SessionKit] Cannot set session: Astro context is missing. ' +\n            'Provide it as a second argument or ensure sessionMiddleware is running.'\n        );\n    }\n\n    // Validate session structure\n    if (!isValidSessionStructure(session)) {\n        throw new Error(\n            '[SessionKit] Invalid session structure. Session must have a valid userId and follow the Session interface.'\n        );\n    }\n\n    // Update ALS store if available for same-request consistency\n    if (store) {\n        store.session = session;\n    }\n\n    // Set in context.session for Astro to persist\n    ctx.session?.set('__session__', session);\n}\n\n/**\n * Clear session from context.locals.session\n *\n * Use this during logout. This does NOT delete session storage (cookies, Redis, etc.) -\n * you must do that separately.\n *\n * @param context - Astro API context (optional if called within request context)\n *\n * @example\n * ```ts\n * // In logout endpoint\n * export const POST: APIRoute = async (context) => {\n *   // Clear from SessionKit\n *   clearSession();\n *\n *   // YOU must also delete the session storage\n *   context.cookies.delete('session_id');\n *   await db.deleteSession(sessionId);\n *\n *   return context.redirect('/');\n * };\n * ```\n */\nexport function clearSession(context?: SessionKitContext): void {\n    const store = getContextStore();\n    const ctx = context || store?.astroContext;\n\n    if (!ctx) {\n        throw new Error(\n            '[SessionKit] Cannot clear session: Astro context is missing. ' +\n            'Provide it as an argument or ensure sessionMiddleware is running.'\n        );\n    }\n\n    // Update ALS store if available for same-request consistency\n    if (store) {\n        store.session = null;\n    }\n\n    ctx.session?.delete('__session__');\n}\n\n/**\n * Regenerate the session ID to prevent session fixation attacks\n *\n * Use this after a successful login or privilege change.\n * This is only supported if the underlying Astro session driver supports it.\n *\n * @param context - Astro API context (optional if called within request context)\n *\n * @example\n * ```ts\n * // In login endpoint\n * export const POST: APIRoute = async (context) => {\n *   const user = await authenticate(request);\n *   if (user) {\n *     // 1. Regenerate session ID\n *     regenerateSession();\n *\n *     // 2. Set new session data\n *     setSession({ userId: user.id, role: user.role });\n *   }\n * }\n * ```\n */\nexport function regenerateSession(context?: SessionKitContext): void {\n    const ctx = context || getContextStore()?.astroContext;\n\n    if (!ctx) {\n        throw new Error(\n            '[SessionKit] Cannot regenerate session: Astro context is missing. ' +\n            'Provide it as an argument or ensure sessionMiddleware is running.'\n        );\n    }\n\n    if (ctx.session?.regenerate) {\n        ctx.session.regenerate();\n    }\n}\n\n/**\n * Update specific fields in the current session\n *\n * Useful for updating session data without replacing the entire session.\n * The updated session is validated before being set.\n *\n * @param updates - Partial session data to merge\n * @param context - Astro API context (optional if called within request context)\n *\n * @throws {Error} If no session exists or updated session is invalid\n *\n * @example\n * ```ts\n * // Update user's role after promotion\n * export const POST: APIRoute = async (context) => {\n *   updateSession({\n *     role: 'admin',\n *     permissions: ['admin:read', 'admin:write']\n *   });\n *\n *   // YOU must also update session storage\n *   await db.updateSession(sessionId, updatedData);\n *\n *   return new Response(JSON.stringify({ success: true }));\n * };\n * ```\n */\nexport function updateSession(updates: Partial<Session>, context?: SessionKitContext): void {\n    const store = getContextStore();\n    const ctx = context || store?.astroContext;\n\n    if (!ctx) {\n        throw new Error(\n            '[SessionKit] Cannot update session: Astro context is missing. ' +\n            'Provide it as a second argument or ensure sessionMiddleware is running.'\n        );\n    }\n\n    // Get current session from ALS (preferred) or Astro session\n    const currentSession = store?.session || ctx.session?.get<Session>('__session__');\n\n    // Note: ctx.session.get might return a Promise in some Astro versions/drivers.\n    // However, since sessionMiddleware already awaits it, store.session should be populated.\n    // If store.session is missing but we are in a middleware-managed request, it means no session exists.\n    \n    if (!currentSession || (currentSession instanceof Promise)) {\n        // If it's a promise, we might have a sync/async mismatch, but usually getSession() handles this.\n        // For robustness, we check if we actually have a session object.\n        const session = currentSession instanceof Promise ? null : currentSession;\n        if (!session) {\n            throw new Error('[SessionKit] Cannot update session: no session exists');\n        }\n    }\n\n    // We can safely cast here if it's not a promise\n    const session = currentSession as Session;\n\n    // Merge updates with current session\n    const updatedSession = {...session, ...updates};\n\n    // Use setSession to handle validation and both store updates\n    setSession(updatedSession, ctx);\n}"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-sessionkit",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Simple session access and route protection for Astro applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -85,6 +85,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "bench": "vitest bench run bench/"
+    "bench": "vitest bench run bench/",
+    "playground:install": "cd playground && npm install",
+    "playground:dev": "cd playground && npm run dev"
   }
 }

package/src/core/config.ts

@@ -18,11 +18,15 @@ export interface ResolvedConfig {
     runWithContext?: <T>(context: SessionContext, fn: () => T) => T | Promise<T>;
     getContextStore?: () => SessionContext | undefined;
     setContextStore?: (context: SessionContext) => void;
+    context?: any;
     globalProtect: boolean;
     exclude: string[];
     debug: boolean;
 }
 
+const CONFIG_KEY = Symbol.for('astro-sessionkit.config');
+const globalStorage = globalThis as any;
+
 const DEFAULT_CONFIG: ResolvedConfig = {
     loginPath: "/login",
     protect: [],
@@ -36,7 +40,17 @@ const DEFAULT_CONFIG: ResolvedConfig = {
     debug: false,
 };
 
-let config: ResolvedConfig = { ...DEFAULT_CONFIG };
+// Initialize global storage if not present
+if (!globalStorage[CONFIG_KEY]) {
+    globalStorage[CONFIG_KEY] = Object.freeze({ ...DEFAULT_CONFIG });
+}
+
+/**
+ * Reset configuration to defaults (mainly for testing)
+ */
+export function resetConfig(): void {
+    globalStorage[CONFIG_KEY] = Object.freeze({ ...DEFAULT_CONFIG });
+}
 
 /**
  * Set configuration (called by integration)
@@ -113,7 +127,8 @@ export function setConfig(userConfig: SessionKitConfig): void {
     newConfig.runWithContext = userConfig.runWithContext;
     newConfig.getContextStore = userConfig.getContextStore;
     newConfig.setContextStore = userConfig.setContextStore;
-    
+    newConfig.context = userConfig.context;
+
     if (userConfig.globalProtect !== undefined) {
         newConfig.globalProtect = userConfig.globalProtect;
     }
@@ -137,12 +152,23 @@ export function setConfig(userConfig: SessionKitConfig): void {
     }
 
     // Atomic update
-    config = Object.freeze(newConfig);
+    globalStorage[CONFIG_KEY] = Object.freeze(newConfig);
 }
 
 /**
  * Get current configuration
  */
 export function getConfig(): ResolvedConfig {
-    return config;
+    return globalStorage[CONFIG_KEY] || DEFAULT_CONFIG;
+}
+
+// Handle injected configuration from Astro integration
+try {
+    // @ts-ignore
+    const injectedConfig = typeof __SESSIONKIT_CONFIG__ !== 'undefined' ? __SESSIONKIT_CONFIG__ : undefined;
+    if (injectedConfig) {
+        setConfig(injectedConfig);
+    }
+} catch (e) {
+    // Ignore errors in environments where __SESSIONKIT_CONFIG__ might be restricted
 }

package/src/core/context.ts

@@ -19,12 +19,35 @@ export function runWithContext<T>(
 }
 
 /**
- * Get the current session context (only available inside middleware chain)
+ * Get current Astro context (from middleware binding or explicit)
  */
-export function getContextStore(): SessionContext | undefined {
-  const customGetter = getConfig().getContextStore;
-  if (customGetter) {
-    return customGetter();
+export function getContextStore(): SessionContext {
+  const config = getConfig();
+  const getStore = config.getContextStore;
+  const context = (config as any).context || als;
+
+  const store = getStore
+      ? getStore()
+      : (context as AsyncLocalStorage<SessionContext>).getStore();
+
+  if (!store) {
+    return undefined as any;
   }
-  return als.getStore();
+
+  return store;
 }
+
+/**
+ * Check if context is available
+ */
+export function hasContext(): boolean {
+  const config = getConfig();
+  const getStore = config.getContextStore;
+  const context = (config as any).context || als;
+
+  const store = getStore
+      ? getStore()
+      : (context as AsyncLocalStorage<SessionContext>).getStore();
+
+  return !!store;
+}

package/src/core/guardMiddleware.ts

@@ -2,7 +2,7 @@
 // Route Guard Middleware - Enforces protection rules
 // ============================================================================
 
-import type {APIContext, MiddlewareHandler} from "astro";
+import type {MiddlewareHandler} from "astro";
 import { getContextStore } from "./context";
 import { getConfig } from "./config";
 import { matchesPattern } from "./matcher";
@@ -73,71 +73,91 @@ async function checkRule(rule: ProtectionRule, session: Session | null): Promise
  * Create route guard middleware
  */
 export function createGuardMiddleware(): MiddlewareHandler {
-  return async (context : APIContext, next) => {
-    const { protect, loginPath, globalProtect, exclude } = getConfig();
-    
+  return async (context, next) => {
     let pathname: string;
     try {
-      pathname = new URL(context.request.url).pathname;
+        pathname = new URL(context.request.url).pathname;
     } catch {
-      // Fallback if URL is invalid (unlikely in Astro)
-      pathname = "/";
+        pathname = "/";
     }
 
-    logger.debug(`[Guard] Pathname: ${pathname}, GlobalProtect: ${globalProtect}, Rules: ${protect.length}`);
+    const config = getConfig();
+    const {protect, loginPath, globalProtect, exclude, debug} = config;
+
+    if (debug) {
+        logger.debug(`[Guard] Pathname: ${pathname}, GlobalProtect: ${globalProtect}, Rules: ${protect.length}`);
+    }
 
     // No rules configured and no global protect - skip
     if (protect.length === 0 && !globalProtect) {
-      logger.debug(`[Guard] Skipping ${pathname} because no rules are configured and globalProtect is false`);
-      return next();
+        if (debug) {
+            logger.debug(`[Guard] Skipping ${pathname} because no rules are configured and globalProtect is false`);
+        }
+        return next();
     }
 
     const sessionContext = getContextStore();
     const session = sessionContext?.session ?? null;
 
+    if (debug) {
+        logger.debug(`[Guard] Session retrieved from store: ${session ? 'exists' : 'null'}`);
+    }
+
     // Find matching rule
     const rule = protect.find((r) => matchesPattern(r.pattern, pathname));
-    
-    if (rule) {
-      logger.debug(`[Guard] Found matching rule for ${pathname}:`, rule);
+
+    if (rule && debug) {
+        logger.debug(`[Guard] Found matching rule for ${pathname}:`, rule);
     }
 
     // No matching rule - check global protection
     if (!rule) {
-      if (globalProtect) {
-        // Skip if path is in exclude list
-        if (exclude.some((pattern) => matchesPattern(pattern, pathname))) {
-          logger.debug(`[GlobalProtect] Skipping ${pathname} because it matches an exclude pattern`);
-          return next();
-        }
-        
-        // Skip if it's the login page itself (to avoid redirect loops)
-        if (pathname === loginPath) {
-          logger.debug(`[GlobalProtect] Skipping ${pathname} because it is the loginPath`);
-          return next();
+        if (globalProtect) {
+            // Skip if path is in exclude list
+            if (exclude.some((pattern) => matchesPattern(pattern, pathname))) {
+                if (debug) {
+                    logger.debug(`[GlobalProtect] Skipping ${pathname} because it matches an exclude pattern`);
+                }
+                return next();
+            }
+
+            // Skip if it's the login page itself (to avoid redirect loops)
+            if (pathname === loginPath) {
+                if (debug) {
+                    logger.debug(`[GlobalProtect] Skipping ${pathname} because it is the loginPath`);
+                }
+                return next();
+            }
+
+            // Require valid session
+            if (!session || !isValidSessionStructure(session)) {
+                if (debug) {
+                    logger.debug(`[GlobalProtect] Redirecting to ${loginPath} because session is ${session ? 'invalid' : 'missing'}`);
+                }
+                return context.redirect(loginPath);
+            }
         }
 
-        // Require valid session
-        if (!session || !isValidSessionStructure(session)) {
-          logger.debug(`[GlobalProtect] Redirecting to ${loginPath} because session is ${session ? 'invalid' : 'missing'}`);
-          return context.redirect(loginPath);
+        if (debug) {
+            logger.debug(`[GlobalProtect] Allowing ${pathname} because session is valid or globalProtect is false`);
         }
-      }
-      
-      logger.debug(`[GlobalProtect] Allowing ${pathname} because session is valid or globalProtect is false`);
-      return next();
+        return next();
     }
 
     // Check if access is allowed
     const allowed = await checkRule(rule, session);
 
     if (!allowed) {
-      const redirectTo = rule.redirectTo ?? loginPath;
-      logger.debug(`[Guard] Redirecting to ${redirectTo} because access was denied by rule:`, rule);
-      return context.redirect(redirectTo);
+        const redirectTo = rule.redirectTo ?? loginPath;
+        if (debug) {
+            logger.debug(`[Guard] Redirecting to ${redirectTo} because access was denied by rule:`, rule);
+        }
+        return context.redirect(redirectTo);
     }
 
-    logger.debug(`[Guard] Allowing ${pathname} because access was granted by rule:`, rule);
+    if (debug) {
+        logger.debug(`[Guard] Allowing ${pathname} because access was granted by rule:`, rule);
+    }
     return next();
   };
 }

package/src/core/matcher.ts

@@ -6,7 +6,12 @@ function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+const regexCache = new Map<string, RegExp>();
+
 function globToRegex(pattern: string): RegExp {
+  const cached = regexCache.get(pattern);
+  if (cached) return cached;
+
   let regex = "";
   let i = 0;
 
@@ -53,7 +58,9 @@ function globToRegex(pattern: string): RegExp {
     i += 1;
   }
 
-  return new RegExp(`^${regex}$`);
+  const result = new RegExp(`^${regex}$`);
+  regexCache.set(pattern, result);
+  return result;
 }
 
 export function matchesPattern(pattern: string, path: string): boolean {

package/src/core/sessionMiddleware.ts

@@ -5,7 +5,7 @@
 import type {MiddlewareHandler} from "astro";
 import {runWithContext as defaultRunWithContext} from "./context";
 import {isValidSessionStructure} from "./validation";
-import type {Session} from "./types";
+import type {Session, SessionContext, SessionKitContext} from "./types";
 import {getConfig} from "./config";
 import * as logger from "./logger";
 
@@ -14,6 +14,11 @@ import * as logger from "./logger";
  */
 const SESSION_KEY = "__session__";
 
+/**
+ * Redundant logging prevention key
+ */
+const LOGGED_KEY = Symbol.for('astro-sessionkit.middleware.logged');
+
 /**
  * Main session middleware
  *
@@ -21,8 +26,11 @@ const SESSION_KEY = "__session__";
  * throughout the request via AsyncLocalStorage
  */
 export const sessionMiddleware: MiddlewareHandler = async (context, next) => {
+    const config = getConfig();
+    const {runWithContext, getContextStore, setContextStore, context: externalContext, debug} = config;
+
     // Get session from context.session store
-    const rawSession = context.session?.get<Session>(SESSION_KEY) ?? null;
+    const rawSession = await context.session?.get<Session>(SESSION_KEY) ?? null;
 
     // Validate session structure if present
     let session: Session | null = null;
@@ -42,24 +50,51 @@ export const sessionMiddleware: MiddlewareHandler = async (context, next) => {
     }
 
     // Run the rest of the request chain with session context
-    const config = getConfig();
+    const globalStorage = globalThis as any;
+    if (!globalStorage[LOGGED_KEY]) {
+        let contextStrategy = 'default';
+
+        if (runWithContext) {
+            contextStrategy = 'custom (runWithContext)';
+        } else if (getContextStore) {
+            contextStrategy = 'custom (getter/setter)';
+        } else if (externalContext) {
+            contextStrategy = 'custom (external AsyncLocalStorage)';
+        }
+
+        logger.debug(`[SessionKit] Middleware initialized (context: ${contextStrategy})`);
+        globalStorage[LOGGED_KEY] = true;
+    }
+
+    const runLogic = () => next();
+    const sessionContext: SessionContext = { session, astroContext: context as SessionKitContext };
 
     // 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) {
+    if (getContextStore && !runWithContext) {
         // Initialize context store if setter is provided
-        const store = config.getContextStore();
+        const store = getContextStore();
+        if (debug) {
+            logger.debug('[SessionMiddleware] Custom getContextStore returned:', !!store);
+        }
         if (store) {
             store.session = session;
-        } else if (config.setContextStore) {
-            config.setContextStore({session});
+        } else if (setContextStore) {
+            if (debug) {
+                logger.debug('[SessionMiddleware] Calling custom setContextStore');
+            }
+            setContextStore(sessionContext);
         } else {
             logger.error('getContextStore returned undefined, cannot set session');
         }
-        return next();
+        return runLogic();
+    }
+
+    if (debug) {
+        logger.debug('[SessionMiddleware] Using' + (runWithContext ? ' custom ' : ' default ') + 'runner');
     }
 
-    const runner = config.runWithContext ?? defaultRunWithContext;
-    return runner({session}, () => next());
+    const runner = runWithContext ?? defaultRunWithContext;
+    return runner(sessionContext, runLogic);
 };

package/src/core/types.ts

@@ -2,6 +2,18 @@
 // Core Session Types
 // ============================================================================
 
+import type {AstroCookies, AstroSession} from "astro";
+
+/**
+ * Minimal context required by SessionKit
+ */
+export interface SessionKitContext {
+  cookies: AstroCookies;
+  session?: AstroSession;
+  redirect: (path: string, status?: number) => Response;
+  [key: string]: any;
+}
+
 /**
  * The session object stored in context.locals.session
  * This is what your Astro app provides - we just read it.
@@ -31,6 +43,10 @@ export interface Session {
  */
 export interface SessionContext {
   session: Session | null;
+  /**
+   * Original Astro context (cookies, session, redirect, etc.)
+   */
+  astroContext?: SessionKitContext;
 }
 
 // ============================================================================
@@ -139,9 +155,15 @@ export interface SessionKitConfig {
    */
   exclude?: string[];
 
-  /**
-   * Enable debug logging
-   * @default false
-   */
-  debug?: boolean;
+    /**
+     * Optional external AsyncLocalStorage instance to use for session context.
+     * If provided, SessionKit will use this instead of its internal instance.
+     */
+    context?: any;
+
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
 }