@chidchanun/bcp 0.2.4 → 0.2.6

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -85,10 +85,12 @@
       "source": "packages/client/src/auth.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-auth",
-      "summary": "Authentication, login/logout/session rotation and route authorization guards.",
+      "summary": "Authentication Platform v2 plus permission checks, authorization policies and auth/guest/role/permission route guards.",
       "guides": [
         "/docs/authentication",
+        "/docs/auth-session-store",
         "/docs/auth-route-guards",
+        "/docs/authorization-security",
         "/docs/session-auth"
       ]
     },
@@ -97,9 +99,10 @@
       "source": "packages/client/src/server.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-server",
-      "summary": "Request context, cookies, logging, production hardening, upload, storage, response and session APIs.",
+      "summary": "Request context, cookies, CSRF/same-origin protection, logging, production hardening, upload, storage, response and session APIs.",
       "guides": [
         "/docs/server-request-apis",
+        "/docs/authorization-security",
         "/docs/file-upload",
         "/docs/storage",
         "/docs/storage-ecosystem",

package/docs/api-reference.md

@@ -164,53 +164,109 @@ Related guides: [Database](database.md), [Database Migrations](database-migratio
 
 ## `bcp/auth`
 
-Authentication and authorization APIs.
+Server-only authentication and authorization APIs.
 
 ```ts
 import {
+    AuthorizationError,
+    assertPermission,
     auth,
+    authorize,
+    can,
+    cannot,
     createAuth,
     createAuthGuard,
+    createGuestGuard,
+    createMemoryAuthSessionStore,
+    createPermissionGuard,
     createRoleGuard,
+    defineAuthorizationPolicy,
     getGuardAuth,
     getSession,
+    getUserPermissions,
+    hasPermission,
     login,
     logout,
+    logoutAll,
     requireAuth,
+    requireGuest,
+    requirePermission,
     requireRole,
+    revokeSession,
+    revokeUserSessions,
     rotateSession,
+    type AuthApi,
+    type AuthLoginOptions,
+    type AuthOptions,
+    type AuthSession,
+    type AuthSessionStore,
+    type AuthSessionStoreRecord,
+    type AuthUser,
+    type AuthorizationContext,
+    type AuthorizationMatch,
+    type AuthorizationPolicy,
+    type MemoryAuthSessionStore,
+    type PermissionCheckOptions,
+    type PermissionRequirement,
+    type RequirePermissionOptions,
 } from "bcp/auth";
 ```
 
-Related guides: [Authentication](authentication.md), [Auth Route Guards](auth-route-guards.md), [JWT Sessions](session-auth.md).
+The default authentication mode remains stateless signed JWT-cookie authentication.
+
+Configure `AuthOptions.store` to enable server-side session revocation and `idleTimeout`. `createMemoryAuthSessionStore()` is provided for development/testing; production multi-instance applications should implement `AuthSessionStore` with shared durable storage.
+
+Authorization & Security v2 adds permission checks, permission route guards and resource-aware policy functions:
+
+- `hasPermission()` / `assertPermission()` for flat permission or scope fields,
+- `requirePermission()` / `createPermissionGuard()` for route protection,
+- `defineAuthorizationPolicy()` for application policy definitions,
+- `can()` / `cannot()` for policy checks,
+- `authorize()` for throwing `AuthorizationError` when a policy denies access.
+
+Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [Authorization & Security v2](authorization-security.md), [JWT Sessions](session-auth.md).
 
 ## `bcp/server`
 
 Server request/runtime APIs.
 
-This entrypoint includes request context, cookies, logging, graceful shutdown hooks, multipart upload helpers, storage adapters, file delivery, response helpers and low-level session primitives.
+This entrypoint includes request context, cookies, CSRF and same-origin protection, logging, graceful shutdown hooks, multipart upload helpers, storage adapters, file delivery, response helpers and low-level session primitives.
 
 ```ts
 import {
     clientIp,
     cookies,
+    createCsrfToken,
     createLocalStorage,
     createLogger,
     createS3Storage,
     createStorageResponse,
+    destroyCsrfToken,
     getProductionHardeningConfig,
     headers,
+    isSafeHttpMethod,
+    isSameOriginRequest,
     json,
     redirect,
     registerShutdownHook,
     requestId,
     requestMethod,
     requestUrl,
+    requireCsrfRequest,
+    requireSameOriginRequest,
     storeMultipartFile,
+    verifyCsrfRequest,
+    verifyCsrfToken,
+    RequestSecurityError,
+    type CsrfTokenOptions,
+    type SameOriginOptions,
+    type VerifyCsrfRequestOptions,
 } from "bcp/server";
 ```
 
-Related guides: [Server Request APIs](server-request-apis.md), [File Upload](file-upload.md), [Storage](storage.md), [Storage Ecosystem](storage-ecosystem.md), [Production Hardening](production-hardening.md).
+`requireSameOriginRequest()` protects unsafe cookie-authenticated mutations by validating `Origin`/`Referer`. `createCsrfToken()` and `requireCsrfRequest()` provide signed double-submit style CSRF protection. `BCP_CSRF_SECRET` is preferred when configured and falls back to `BCP_SESSION_SECRET`.
+
+Related guides: [Server Request APIs](server-request-apis.md), [Authorization & Security v2](authorization-security.md), [File Upload](file-upload.md), [Storage](storage.md), [Storage Ecosystem](storage-ecosystem.md), [Production Hardening](production-hardening.md).
 
 ## `bcp/server-only`
 

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 and Authorization & Security v2 with route guards through the server-only `bcp/auth` entrypoint.
 
 ## Protect a route tree
 
@@ -18,22 +18,52 @@ 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:
-            null,
+            "/dashboard",
     });
 ```
 
+Behavior:
+
+```text
+anonymous user
+    ↓
+page continues
+
+signed-in user
+    ↓
+303 /dashboard
+```
+
+Use `redirectTo: null` to return `409 Already authenticated` instead of redirecting.
+
+The low-level form is `requireGuest()`.
+
 ## Require a role
 
 ```ts
@@ -59,58 +89,87 @@ export const guard =
 
 An authenticated user without the required role receives `403 Forbidden` by default.
 
-You can redirect forbidden users instead:
+Require one of several roles:
 
 ```ts
 export const guard =
-    createRoleGuard<User>(
+    createRoleGuard<User>([
         "admin",
-        {
-            forbiddenRedirectTo:
-                "/forbidden",
-        }
-    );
+        "manager",
+    ]);
 ```
 
-## Require one of several roles
-
-The default role matching mode is `any`:
+Require all values from a role field:
 
 ```ts
 export const guard =
-    createRoleGuard<User>([
-        "admin",
-        "manager",
-    ]);
+    createRoleGuard<User>(
+        [
+            "admin",
+            "billing",
+        ],
+        {
+            match: "all",
+        }
+    );
 ```
 
-A user with either role is allowed.
+## Require permissions — 0.2.6+
 
-## Require all permissions
-
-`requireRole()` and `createRoleGuard()` can read another user field and require every value:
+Authorization & Security v2 adds a dedicated permission guard instead of requiring applications to overload role configuration.
 
 ```ts
+import {
+    createPermissionGuard,
+} from "bcp/auth";
+
 interface User {
     id: number;
     permissions: string[];
 }
 
 export const guard =
-    createRoleGuard<User>(
+    createPermissionGuard<User>(
+        "users.read"
+    );
+```
+
+The default permission field is `permissions`.
+
+Require every permission:
+
+```ts
+export const guard =
+    createPermissionGuard<User>(
         [
             "users.read",
             "users.write",
         ],
         {
-            roleField:
-                "permissions",
-            match:
-                "all",
+            match: "all",
         }
     );
 ```
 
+Use another user field such as `scopes`:
+
+```ts
+export const guard =
+    createPermissionGuard<User>(
+        "billing.read",
+        {
+            permissionField:
+                "scopes",
+        }
+    );
+```
+
+The low-level form is `requirePermission()`.
+
+Authenticated users without the required permission receive `403 Forbidden` by default. Use `forbiddenRedirectTo` when the application prefers a redirect.
+
+For authorization decisions that depend on a resource or ownership rather than a flat permission, use the policy APIs documented in [Authorization & Security v2](authorization-security.md).
+
 ## Inline guard logic
 
 Use `requireAuth()` when a guard needs additional application-specific checks:
@@ -125,8 +184,7 @@ export async function guard() {
         await requireAuth<AppUser>();
 
     if (
-        result instanceof
-        Response
+        result instanceof Response
     ) {
         return result;
     }
@@ -137,8 +195,7 @@ export async function guard() {
         return new Response(
             "Forbidden",
             {
-                status:
-                    403,
+                status: 403,
             }
         );
     }
@@ -147,6 +204,14 @@ export async function guard() {
 }
 ```
 
+## Session-store policies apply inside guards
+
+`requireAuth()`, `requireRole()`, `requirePermission()`, 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 +230,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 +260,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()`, `requirePermission()`, `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.