@chidchanun/bcp 0.2.4 → 0.2.5

package/docs/releases/0.2.5.md

@@ -0,0 +1,152 @@
+# BCP Framework 0.2.5
+
+## Authentication Platform v2
+
+`0.2.5` expands `bcp/auth` from signed JWT-cookie authentication into an optional revocable session platform while preserving the stateless mode used by existing applications.
+
+## Highlights
+
+### Server-side auth session store contract
+
+New public types:
+
+```ts
+import type {
+    AuthSessionStore,
+    AuthSessionStoreRecord,
+} from "bcp/auth";
+```
+
+The contract provides:
+
+```text
+set
+get
+touch
+revoke
+revokeUser
+```
+
+Applications can back this contract with Redis, SQL, or another shared server-side store.
+
+### Built-in memory store
+
+Development and tests can use:
+
+```ts
+import {
+    createMemoryAuthSessionStore,
+} from "bcp/auth";
+```
+
+The memory adapter is process-local and intentionally not presented as a distributed production session database.
+
+### Revocable sessions
+
+When an auth store is configured, a valid signed JWT must also have an active server-side `sid` record.
+
+BCP can therefore invalidate a session before the cookie's JWT expiry.
+
+New APIs include:
+
+```text
+logoutAll()
+revokeSession()
+revokeUserSessions()
+```
+
+Normal `logout()` also revokes the current `sid` when a store is enabled.
+
+### Idle timeout
+
+`AuthOptions` now accepts:
+
+```ts
+idleTimeout: number
+```
+
+The value is measured in seconds and requires a session store.
+
+Successful authentication updates the store's `lastSeenAt`. Sessions that exceed the inactivity window are revoked and rejected.
+
+BCP intentionally rejects `idleTimeout` without a store instead of silently providing a false sense of server-side inactivity enforcement.
+
+### Session rotation
+
+`rotateSession()` continues issuing a fresh `sid`, JWT, expiry, and cookie.
+
+With a session store enabled, the previous `sid` is revoked so old cookies no longer pass the server-side session check.
+
+### Guest route guards
+
+New APIs:
+
+```ts
+requireGuest()
+createGuestGuard()
+```
+
+These support login, registration, and similar pages that should continue for anonymous users but redirect users who are already authenticated.
+
+Default authenticated-user behavior is a `303` redirect. `redirectTo: null` returns `409 Already authenticated`.
+
+## Backward compatibility
+
+The default remains stateless signed JWT-cookie authentication:
+
+```ts
+import {
+    auth,
+    login,
+    logout,
+} from "bcp/auth";
+```
+
+Applications do not need to configure a session store unless they need centralized revocation or idle-timeout behavior.
+
+No existing public application entrypoint is intentionally removed in this release.
+
+## Security guidance
+
+- JWT payloads remain signed rather than encrypted.
+- Do not place passwords, password hashes, tokens, API keys, or credentials in auth payload data.
+- Keep `BCP_SESSION_SECRET` outside source control and at least 32 bytes long.
+- Use a shared durable session-store implementation for production applications that run multiple Node.js processes or containers.
+- The built-in memory store is suitable for local development/tests and process-local prototypes.
+
+## Documentation
+
+Updated guides:
+
+```text
+docs/authentication.md
+docs/auth-session-store.md
+docs/auth-route-guards.md
+docs/api-reference.md
+```
+
+## Validation
+
+`0.2.5` adds unit and package smoke coverage for:
+
+```text
+session-store registration and lookup
+session revocation
+session rotation with revocation
+logout-all
+idle timeout
+guest route guards
+bcp/auth publish surface
+Authentication Platform v2 package contents
+```
+
+Before tagging or publishing, run the complete RC sequence:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",

package/packages/client/src/auth.ts

@@ -4,6 +4,9 @@ export {
     getSession,
     login,
     logout,
+    logoutAll,
+    revokeSession,
+    revokeUserSessions,
     rotateSession,
 
     type AuthApi,
@@ -13,17 +16,30 @@ export {
     type AuthUser,
 } from "../../server/src/auth.js";
 
+export {
+    createMemoryAuthSessionStore,
+
+    type AuthSessionStore,
+    type AuthSessionStoreRecord,
+    type MemoryAuthSessionStore,
+} from "../../server/src/auth-session-store.js";
+
 export {
     createAuthGuard,
+    createGuestGuard,
     createRoleGuard,
     getGuardAuth,
     requireAuth,
+    requireGuest,
     requireRole,
 
     type AuthGuardData,
     type AuthGuardFunction,
     type AuthGuardResult,
+    type GuestGuardFunction,
+    type GuestGuardResult,
     type RequireAuthOptions,
+    type RequireGuestOptions,
     type RequireRoleOptions,
     type RequiredRole,
 } from "../../server/src/auth-guard.js";

package/packages/server/src/auth-guard.ts

@@ -18,10 +18,13 @@ export interface AuthGuardData<
 
 export interface RequireAuthOptions
 extends AuthOptions {
-    redirectTo?:
-        string |
-        URL |
-        null;
+    redirectTo?: string | URL | null;
+    redirectStatus?: RedirectStatus;
+}
+
+export interface RequireGuestOptions
+extends AuthOptions {
+    redirectTo?: string | URL | null;
     redirectStatus?: RedirectStatus;
 }
 
@@ -29,10 +32,7 @@ export interface RequireRoleOptions
 extends RequireAuthOptions {
     roleField?: string;
     match?: "any" | "all";
-    forbiddenRedirectTo?:
-        string |
-        URL |
-        null;
+    forbiddenRedirectTo?: string | URL | null;
     forbiddenRedirectStatus?: RedirectStatus;
 }
 
@@ -47,16 +47,20 @@ export type AuthGuardResult<
     | AuthGuardData<TUser, TData>
     | Response;
 
+export type GuestGuardResult =
+    | Record<string, never>
+    | Response;
+
 export type AuthGuardFunction<
     TUser extends AuthUser = AuthUser,
     TData extends object = Record<string, never>
 > = () => Promise<
-    AuthGuardResult<
-        TUser,
-        TData
-    >
+    AuthGuardResult<TUser, TData>
 >;
 
+export type GuestGuardFunction =
+    () => Promise<GuestGuardResult>;
+
 export async function requireAuth<
     TUser extends AuthUser = AuthUser,
     TData extends object = Record<string, never>
@@ -69,23 +73,18 @@ export async function requireAuth<
         ...authOptions
     } = options;
     const session =
-        await auth<
-            TUser,
-            TData
-        >(
+        await auth<TUser, TData>(
             authOptions
         );
 
     if (!session) {
         if (
-            redirectTo ===
-            null
+            redirectTo === null
         ) {
             return new Response(
                 "Unauthorized",
                 {
-                    status:
-                        401,
+                    status: 401,
                 }
             );
         }
@@ -97,11 +96,47 @@ export async function requireAuth<
     }
 
     return {
-        auth:
-            session,
+        auth: session,
     };
 }
 
+export async function requireGuest<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    options: RequireGuestOptions = {}
+): Promise<GuestGuardResult> {
+    const {
+        redirectTo = "/",
+        redirectStatus = 303,
+        ...authOptions
+    } = options;
+    const session =
+        await auth<TUser, TData>(
+            authOptions
+        );
+
+    if (!session) {
+        return {};
+    }
+
+    if (
+        redirectTo === null
+    ) {
+        return new Response(
+            "Already authenticated",
+            {
+                status: 409,
+            }
+        );
+    }
+
+    return redirect(
+        redirectTo,
+        redirectStatus
+    );
+}
+
 export async function requireRole<
     TUser extends AuthUser = AuthUser,
     TData extends object = Record<string, never>
@@ -121,16 +156,12 @@ export async function requireRole<
         ...authOptions
     } = options;
     const authenticated =
-        await requireAuth<
-            TUser,
-            TData
-        >(
+        await requireAuth<TUser, TData>(
             authOptions
         );
 
     if (
-        authenticated instanceof
-        Response
+        authenticated instanceof Response
     ) {
         return authenticated;
     }
@@ -157,8 +188,7 @@ export async function requireRole<
 
     if (!allowed) {
         if (
-            forbiddenRedirectTo !==
-            null
+            forbiddenRedirectTo !== null
         ) {
             return redirect(
                 forbiddenRedirectTo,
@@ -169,8 +199,7 @@ export async function requireRole<
         return new Response(
             "Forbidden",
             {
-                status:
-                    403,
+                status: 403,
             }
         );
     }
@@ -185,10 +214,19 @@ export function createAuthGuard<
     options: RequireAuthOptions = {}
 ): AuthGuardFunction<TUser, TData> {
     return () =>
-        requireAuth<
-            TUser,
-            TData
-        >(
+        requireAuth<TUser, TData>(
+            options
+        );
+}
+
+export function createGuestGuard<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    options: RequireGuestOptions = {}
+): GuestGuardFunction {
+    return () =>
+        requireGuest<TUser, TData>(
             options
         );
 }
@@ -201,10 +239,7 @@ export function createRoleGuard<
     options: RequireRoleOptions = {}
 ): AuthGuardFunction<TUser, TData> {
     return () =>
-        requireRole<
-            TUser,
-            TData
-        >(
+        requireRole<TUser, TData>(
             requiredRole,
             options
         );
@@ -214,18 +249,16 @@ export function getGuardAuth<
     TUser extends AuthUser = AuthUser,
     TData extends object = Record<string, never>
 >(
-    guardData:
-        Readonly<{
-            auth?: unknown;
-        }>
+    guardData: Readonly<{
+        auth?: unknown;
+    }>
 ): AuthSession<TUser, TData> | null {
     const value =
         guardData.auth;
 
     if (
         !value ||
-        typeof value !==
-            "object" ||
+        typeof value !== "object" ||
         Array.isArray(
             value
         )
@@ -235,24 +268,17 @@ export function getGuardAuth<
 
     const session =
         value as Partial<
-            AuthSession<
-                TUser,
-                TData
-            >
+            AuthSession<TUser, TData>
         >;
 
     if (
-        typeof session.sid !==
-            "string" ||
-        session.sid.trim().length ===
-            0 ||
-        typeof session.iat !==
-            "number" ||
+        typeof session.sid !== "string" ||
+        session.sid.trim().length === 0 ||
+        typeof session.iat !== "number" ||
         !Number.isFinite(
             session.iat
         ) ||
-        typeof session.exp !==
-            "number" ||
+        typeof session.exp !== "number" ||
         !Number.isFinite(
             session.exp
         ) ||
@@ -264,18 +290,14 @@ export function getGuardAuth<
     }
 
     return value as
-        AuthSession<
-            TUser,
-            TData
-        >;
+        AuthSession<TUser, TData>;
 }
 
 function normalizeRequiredRoles(
     value: RequiredRole
 ): string[] {
     const roles =
-        typeof value ===
-            "string"
+        typeof value === "string"
             ? [
                 value,
             ]
@@ -289,12 +311,10 @@ function normalizeRequiredRoles(
         );
 
     if (
-        normalized.length ===
-            0 ||
+        normalized.length === 0 ||
         normalized.some(
             (role) =>
-                role.length ===
-                0
+                role.length === 0
         )
     ) {
         throw new TypeError(
@@ -324,14 +344,12 @@ function readAssignedRoles(
 
     const value =
         (
-            user as
-            unknown as
+            user as unknown as
             Record<string, unknown>
         )[field];
 
     if (
-        typeof value ===
-        "string"
+        typeof value === "string"
     ) {
         const role =
             value.trim();
@@ -353,8 +371,7 @@ function readAssignedRoles(
                 (
                     role
                 ): role is string =>
-                    typeof role ===
-                    "string"
+                    typeof role === "string"
             )
             .map(
                 (role) =>
@@ -373,8 +390,7 @@ function isGuardAuthUser(
 ): value is AuthUser {
     if (
         !value ||
-        typeof value !==
-            "object" ||
+        typeof value !== "object" ||
         Array.isArray(
             value
         )
@@ -389,13 +405,10 @@ function isGuardAuthUser(
         ).id;
 
     return (
-        typeof id ===
-            "string" &&
-        id.trim().length >
-            0
+        typeof id === "string" &&
+        id.trim().length > 0
     ) || (
-        typeof id ===
-            "number" &&
+        typeof id === "number" &&
         Number.isFinite(
             id
         )