@chidchanun/bcp 0.2.3 → 0.2.5

package/docs/auth-route-guards.md

@@ -1,6 +1,6 @@
 # Auth Route Guards
 
-BCP Framework `0.1.17` integrates the Authentication Core with route guards through the server-only `bcp/auth` entrypoint.
+BCP Framework integrates Authentication Platform v2 with route guards through the server-only `bcp/auth` entrypoint.
 
 ## Protect a route tree
 
@@ -18,22 +18,73 @@ export const guard =
     });
 ```
 
-The guard redirects unauthenticated requests to `/login` with status `303` by default. A `303` is suitable for guards that may run before form actions because it converts a redirected mutation request into a normal GET request to the login page.
+The guard redirects unauthenticated requests to `/login` with status `303` by default.
 
-To return `401 Unauthorized` instead of redirecting:
+To return `401 Unauthorized` instead:
+
+```ts
+export const guard =
+    createAuthGuard({
+        redirectTo:
+            null,
+    });
+```
+
+## Guest-only routes — 0.2.5
+
+Login, registration, and password-recovery entry pages often should not remain accessible after the user has already authenticated.
+
+Use `createGuestGuard()`:
 
 ```ts
 import {
-    createAuthGuard,
+    createGuestGuard,
 } from "bcp/auth";
 
 export const guard =
-    createAuthGuard({
+    createGuestGuard({
+        redirectTo:
+            "/dashboard",
+    });
+```
+
+Behavior:
+
+```text
+anonymous user
+    ↓
+page continues
+
+signed-in user
+    ↓
+303 /dashboard
+```
+
+Use `redirectTo: null` to return `409 Already authenticated` instead of redirecting:
+
+```ts
+export const guard =
+    createGuestGuard({
         redirectTo:
             null,
     });
 ```
 
+The low-level form is `requireGuest()`:
+
+```ts
+import {
+    requireGuest,
+} from "bcp/auth";
+
+export function guard() {
+    return requireGuest({
+        redirectTo:
+            "/dashboard",
+    });
+}
+```
+
 ## Require a role
 
 ```ts
@@ -125,8 +176,7 @@ export async function guard() {
         await requireAuth<AppUser>();
 
     if (
-        result instanceof
-        Response
+        result instanceof Response
     ) {
         return result;
     }
@@ -137,8 +187,7 @@ export async function guard() {
         return new Response(
             "Forbidden",
             {
-                status:
-                    403,
+                status: 403,
             }
         );
     }
@@ -147,6 +196,14 @@ export async function guard() {
 }
 ```
 
+## Session-store policies apply inside guards
+
+`requireAuth()`, `requireRole()`, and `requireGuest()` all use the same `auth()` runtime.
+
+When auth options include a server-side store and idle timeout, guard evaluation observes revocation and inactivity before allowing the route.
+
+For shared application configuration, create a small app auth module and expose guard helpers that use the same store instead of constructing unrelated stores inside each route file.
+
 ## Auth data in child guards and loaders
 
 Successful auth helpers return guard data in this shape:
@@ -165,7 +222,7 @@ Successful auth helpers return guard data in this shape:
 }
 ```
 
-Because BCP merges parent guard data into child guards and page loaders, descendants can read the authenticated session without verifying the cookie again.
+BCP merges parent guard data into child guards and page loaders, so descendants can reuse the authenticated session.
 
 Use `getGuardAuth()` for typed access:
 
@@ -195,36 +252,14 @@ export async function loader({
 }
 ```
 
-## Low-level role checks
-
-`requireRole()` is also available directly:
-
-```ts
-import {
-    requireRole,
-} from "bcp/auth";
-
-export function guard() {
-    return requireRole<AppUser>(
-        "admin"
-    );
-}
-```
-
 ## Standalone production behavior
 
-BCP 0.1.24 keeps `bcp/auth` inside the same production guard runtime graph as `runWithRequestContext()`. This guarantees that `requireAuth()`, `requireRole()`, `auth()`, `getSession()` and `cookies()` observe the active request after `bcp build`, rather than resolving through a second framework request-context instance.
-
-This fixes the production-only failure:
+`bcp/auth` stays inside the production guard/runtime request-context graph. `requireAuth()`, `requireGuest()`, `requireRole()`, `auth()`, `getSession()`, and `cookies()` therefore observe the active request after `bcp build`.
 
-```text
-BCP Framework: server request APIs can only be used while handling a request.
-```
-
-No application guard changes are required. Continue importing authentication helpers from `bcp/auth` normally.
-
-The production form-action bundle applies the same runtime unification because route guards may execute before an action.
+The production form-action bundle uses the same runtime boundary because guards may execute before an action.
 
 ## Security boundary
 
-`bcp/auth` is server-only. BCP blocks it from page/client graphs and maps its browser export to the server-only runtime guard. Authentication and authorization checks should stay in guards, loaders, actions, API routes, or other server modules.
+`bcp/auth` is server-only. BCP blocks it from page/client graphs and maps its browser export to the server-only runtime guard.
+
+Authentication and authorization checks should stay in guards, loaders, actions, API routes, or other server modules.

package/docs/auth-session-store.md

@@ -0,0 +1,204 @@
+# Auth Session Stores
+
+BCP Framework `0.2.5 — Authentication Platform v2` adds an optional server-side session-store contract to `bcp/auth`.
+
+The existing signed JWT cookie mode remains the default. Applications that do not configure a store continue to use stateless authentication exactly as before.
+
+A session store is useful when the application needs server-side revocation, logout across devices, idle expiration, or explicit session administration.
+
+## Why use a store?
+
+A signed JWT proves that the cookie was issued by the application and has not been modified. By itself, however, a JWT remains valid until it expires.
+
+With an auth session store enabled, BCP checks both:
+
+```text
+signed JWT cookie
+      +
+server-side sid record
+      ↓
+active authenticated session
+```
+
+This allows an application to invalidate a session before the JWT's normal expiry.
+
+## Memory store
+
+BCP includes a small in-memory implementation for local development, tests, prototypes, and single-process experiments:
+
+```ts
+import {
+    createAuth,
+    createMemoryAuthSessionStore,
+} from "bcp/auth";
+
+const sessionStore =
+    createMemoryAuthSessionStore();
+
+export const appAuth =
+    createAuth({
+        store:
+            sessionStore,
+    });
+```
+
+The memory store is process-local and is cleared when the Node.js process restarts. It is not a shared production session database.
+
+For multiple processes, containers, or servers, implement `AuthSessionStore` using a shared service such as Redis or a database.
+
+## Store contract
+
+```ts
+import type {
+    AuthSessionStore,
+    AuthSessionStoreRecord,
+} from "bcp/auth";
+```
+
+The contract is:
+
+```ts
+interface AuthSessionStore {
+    set(
+        record: AuthSessionStoreRecord
+    ): Promise<void> | void;
+
+    get(
+        sid: string
+    ):
+        | Promise<AuthSessionStoreRecord | null>
+        | AuthSessionStoreRecord
+        | null;
+
+    touch(
+        sid: string,
+        lastSeenAt: number
+    ): Promise<void> | void;
+
+    revoke(
+        sid: string,
+        revokedAt?: number
+    ): Promise<boolean> | boolean;
+
+    revokeUser(
+        userId: string,
+        revokedAt?: number
+    ): Promise<number> | number;
+}
+```
+
+Store records contain only session-control metadata:
+
+```ts
+interface AuthSessionStoreRecord {
+    sid: string;
+    userId: string;
+    createdAt: number;
+    expiresAt: number;
+    lastSeenAt: number;
+    revokedAt?: number | null;
+}
+```
+
+`userId` is an opaque normalized identifier generated by BCP. Application stores should preserve it exactly as received.
+
+## Logout and revocation
+
+Normal logout revokes the active server-side `sid` before expiring the browser cookie when a store is configured:
+
+```ts
+await appAuth.logout();
+```
+
+Revoke a known session:
+
+```ts
+await appAuth.revokeSession(
+    sessionId
+);
+```
+
+Revoke all stored sessions belonging to a user:
+
+```ts
+await appAuth.revokeUserSessions(
+    userId
+);
+```
+
+Logout the current browser and revoke all stored sessions for that user:
+
+```ts
+const revokedCount =
+    await appAuth.logoutAll();
+```
+
+`logoutAll()` requires a session store. Stateless-only authentication cannot invalidate JWT cookies held by other devices before those tokens expire.
+
+## Idle timeout
+
+An optional idle timeout can be applied when a session store is enabled:
+
+```ts
+const appAuth =
+    createAuth({
+        store:
+            sessionStore,
+        idleTimeout:
+            60 * 30,
+    });
+```
+
+The value is measured in seconds.
+
+Every successful `auth()` check updates `lastSeenAt`. If the stored session has been inactive for at least the configured interval, BCP revokes it and authentication returns `null`.
+
+Because idle timeout depends on server-side state, configuring `idleTimeout` without a store is rejected instead of silently pretending to enforce the policy.
+
+## Session rotation
+
+`rotateSession()` issues a new `sid` while keeping the current user and session data:
+
+```ts
+const nextSession =
+    await appAuth.rotateSession();
+```
+
+When a store is configured, the previous `sid` is revoked as part of rotation so an older cookie cannot continue to authenticate through the server-side session check.
+
+Typical rotation points include:
+
+- successful re-authentication,
+- password changes,
+- role or permission elevation,
+- sensitive account changes.
+
+## Production implementation guidance
+
+A production store should provide atomic, durable operations for `set`, `get`, `touch`, `revoke`, and `revokeUser`.
+
+Recommended properties:
+
+- shared across all application instances,
+- expiration based on `expiresAt`,
+- indexed lookup by `sid`,
+- indexed lookup by normalized `userId`,
+- atomic revocation,
+- bounded cleanup of expired records,
+- no storage of passwords or raw session secrets.
+
+The JWT remains HttpOnly and signed by `BCP_SESSION_SECRET`; the session store is an additional revocation/lifecycle layer, not a replacement for cookie security.
+
+## Backward compatibility
+
+This remains valid in `0.2.5`:
+
+```ts
+import {
+    auth,
+    login,
+    logout,
+} from "bcp/auth";
+```
+
+Without `store`, BCP continues operating in stateless JWT-cookie mode.

package/docs/authentication.md

@@ -1,7 +1,6 @@
 # Authentication
 
-BCP Framework 0.1.16 adds a server-only authentication layer through `bcp/auth`.
-It builds on the signed JWT cookie/session primitives from `bcp/server` and provides a higher-level API for application authentication.
+BCP Framework `0.2.5 — Authentication Platform v2` extends the server-only `bcp/auth` entrypoint with optional server-side session state, revocation, idle timeout, logout-all, and guest route guards while preserving the existing signed JWT-cookie mode.
 
 ## Environment
 
@@ -52,13 +51,9 @@ const session =
 if (!session) {
     // Not authenticated.
 }
-
-console.log(
-    session?.user.id
-);
 ```
 
-`getSession()` is an alias for `auth()` when that naming is clearer in application code.
+`getSession()` remains an alias for `auth()`.
 
 ## Typed auth factory
 
@@ -113,56 +108,150 @@ await appAuth.login(
 );
 ```
 
-Read it later:
+## Stateless mode remains the default
+
+Without a server-side store, authentication remains a signed JWT cookie:
+
+```text
+browser cookie
+   ↓
+HS256 signature + expiry validation
+   ↓
+authenticated session
+```
+
+This is backward-compatible with earlier BCP versions.
+
+A stateless JWT cannot normally be invalidated on another device before expiry. Applications that need revocation can enable the `0.2.5` session-store contract.
+
+## Revocable sessions
 
 ```ts
-const session =
-    await appAuth.auth();
+import {
+    createAuth,
+    createMemoryAuthSessionStore,
+} from "bcp/auth";
+
+const store =
+    createMemoryAuthSessionStore();
+
+export const appAuth =
+    createAuth<AppUser>({
+        store,
+    });
+```
+
+With a store configured, authentication requires both a valid signed cookie and an active server-side `sid` record.
+
+The built-in memory store is intended for development and tests. Multi-instance production applications should implement `AuthSessionStore` using a shared database or Redis-like service.
+
+See [Auth Session Stores](auth-session-store.md).
+
+## Logout
+
+```ts
+await appAuth.logout();
+```
+
+In stateless mode this expires the browser cookie.
+
+When a store is configured, BCP also revokes the current `sid` before expiring the cookie.
+
+## Logout from all sessions
+
+With a session store:
+
+```ts
+const revokedCount =
+    await appAuth.logoutAll();
+```
+
+This revokes every stored session for the current user and expires the current browser cookie.
+
+`logoutAll()` intentionally requires a server-side store because stateless JWTs held by other devices cannot be centrally invalidated.
 
-console.log(
-    session?.user.email
+## Explicit revocation
+
+A factory configured with a store can revoke a known session:
+
+```ts
+await appAuth.revokeSession(
+    sid
 );
-console.log(
-    session?.data?.tenantId
+```
+
+Or revoke every stored session for a user:
+
+```ts
+await appAuth.revokeUserSessions(
+    userId
 );
 ```
 
-## Logout
+Low-level forms are also exported:
 
 ```ts
-await logout();
+import {
+    revokeSession,
+    revokeUserSessions,
+} from "bcp/auth";
 ```
 
-Or with a factory:
+## Idle timeout
+
+Server-side session state can enforce inactivity expiration:
 
 ```ts
-await appAuth.logout();
+const appAuth =
+    createAuth<AppUser>({
+        store,
+        idleTimeout:
+            60 * 30,
+    });
 ```
 
-Logout expires the configured authentication cookie.
+`idleTimeout` is measured in seconds. Each successful `auth()` check updates `lastSeenAt`.
+
+If the session has been inactive for at least the configured duration, BCP revokes it and returns `null`.
+
+BCP rejects `idleTimeout` when no store is configured so an application cannot accidentally believe it is enforcing server-side inactivity policy when it is not.
 
 ## Session rotation
 
-Each auth login receives a unique `sid` (session identifier). `rotateSession()` keeps the current user and session data but issues a new `sid`, JWT, expiry window, and cookie.
+Each login receives a unique `sid`. `rotateSession()` keeps the current user/session data but issues a new session identifier, JWT, expiry window, and cookie.
 
 ```ts
 const rotated =
     await appAuth.rotateSession();
+```
 
-if (rotated) {
-    console.log(
-        rotated.sid
-    );
-}
+When a session store is configured, the previous `sid` is revoked as part of rotation.
+
+Good rotation points include successful re-authentication, password changes, permission elevation, or other security-sensitive account changes.
+
+## Guest-only pages
+
+Authentication Platform v2 adds `requireGuest()` / `createGuestGuard()` for routes such as login and registration pages.
+
+```ts
+import {
+    createGuestGuard,
+} from "bcp/auth";
+
+export const guard =
+    createGuestGuard({
+        redirectTo:
+            "/dashboard",
+    });
 ```
 
-Rotation returns `null` when no valid auth session exists.
+Anonymous users continue to the page. Authenticated users are redirected with `303` by default.
 
-A useful policy is to rotate after a security-sensitive event such as a privilege change or successful re-authentication.
+See [Auth Route Guards](auth-route-guards.md).
 
 ## Session shape
 
-An authenticated session contains the user, optional application session data, and signed JWT claims:
+An authenticated session contains the user, optional application data, and signed JWT claims:
 
 ```ts
 {
@@ -176,26 +265,21 @@ An authenticated session contains the user, optional application session data, a
 }
 ```
 
+Server-side session-store metadata is not embedded as application payload data.
+
 ## Security notes
 
-- `bcp/auth` is server-only and must not be imported into pages or client islands.
-- Never put passwords, password hashes, API secrets, access keys, or other sensitive credentials in the auth user/session payload. JWT cookie payloads are signed, not encrypted.
-- Keep `BCP_SESSION_SECRET` out of source control and use a strong random value of at least 32 bytes.
-- Authentication verifies identity/session state. Application authorization such as roles and permissions belongs in route guards or server actions.
-- Use HTTPS in production so Secure cookies are transmitted only over encrypted connections.
+- `bcp/auth` is server-only and must not be imported into browser/client graphs.
+- JWT cookie payloads are signed, not encrypted. Do not store passwords, password hashes, API secrets, access keys, or private credentials in the auth payload.
+- Keep `BCP_SESSION_SECRET` outside source control and use a strong random value of at least 32 bytes.
+- Use HTTPS in production so Secure cookies travel only over encrypted connections.
+- The memory session store is process-local; use a shared durable store when revocation must work across multiple processes/containers.
+- Authentication establishes identity/session state. Fine-grained authorization remains a route guard, action, API, or application policy concern.
 
 ## create-bcp-app
 
-When `JWT Cookie` authentication is selected, generated applications use `createAuth()` internally and expose helpers from `lib/auth.ts`:
-
-```ts
-import {
-    auth,
-    getSession,
-    login,
-    logout,
-    rotateSession,
-} from "@/lib/auth";
-```
+When `JWT Cookie` authentication is selected, generated applications use `createAuth()` internally and expose application helpers from `lib/auth.ts`.
 
 The generated `authenticateCredentials()` intentionally returns `null` until the application implements its own user lookup and password verification strategy.
+
+Generated projects stay stateless by default. Applications can opt into a session store explicitly without changing the public auth entrypoint.