@chidchanun/bcp 0.2.4 → 0.2.6

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.

package/docs/authorization-security.md

@@ -0,0 +1,298 @@
+# Authorization & Security v2
+
+BCP Framework `0.2.6` adds permission- and policy-based authorization plus request-origin and CSRF protection primitives while keeping the existing authentication APIs backward compatible.
+
+## Permission checks
+
+Permission helpers are exported from the server-only `bcp/auth` entrypoint.
+
+```ts
+import {
+    hasPermission,
+    assertPermission,
+} from "bcp/auth";
+
+const user = {
+    id: 42,
+    permissions: [
+        "users.read",
+        "users.write",
+    ],
+};
+
+hasPermission(
+    user,
+    "users.read"
+); // true
+
+hasPermission(
+    user,
+    [
+        "users.read",
+        "users.delete",
+    ],
+    {
+        match: "all",
+    }
+); // false
+```
+
+The default permission field is `permissions`. Override it when an application uses another user shape:
+
+```ts
+hasPermission(
+    user,
+    "billing.read",
+    {
+        field: "scopes",
+    }
+);
+```
+
+`assertPermission()` throws `AuthorizationError` with status `403` when the requirement is not satisfied.
+
+## Permission route guards
+
+Protect a route tree with a permission requirement:
+
+```ts
+import {
+    createPermissionGuard,
+} from "bcp/auth";
+
+export const guard =
+    createPermissionGuard(
+        "users.read"
+    );
+```
+
+Require every permission:
+
+```ts
+export const guard =
+    createPermissionGuard(
+        [
+            "users.read",
+            "users.write",
+        ],
+        {
+            match: "all",
+        }
+    );
+```
+
+An unauthenticated request follows the normal `requireAuth()` behavior. An authenticated user without the required permission receives `403 Forbidden` by default.
+
+A custom permission field and forbidden redirect are supported:
+
+```ts
+export const guard =
+    createPermissionGuard(
+        "admin.access",
+        {
+            permissionField:
+                "scopes",
+            forbiddenRedirectTo:
+                "/forbidden",
+        }
+    );
+```
+
+The lower-level `requirePermission()` helper is available for custom guard logic.
+
+## Authorization policies
+
+Policies are useful when authorization depends on a resource, ownership, tenant, state, or other application-specific data instead of a flat permission string.
+
+```ts
+import {
+    defineAuthorizationPolicy,
+    authorize,
+    can,
+} from "bcp/auth";
+
+interface User {
+    id: number;
+}
+
+interface Project {
+    ownerId: number;
+}
+
+const updateProject =
+    defineAuthorizationPolicy<
+        User,
+        Project
+    >(
+        ({
+            user,
+            resource,
+        }) =>
+            resource?.ownerId ===
+            user.id
+    );
+
+const allowed =
+    await can(
+        updateProject,
+        {
+            user,
+            resource: project,
+        }
+    );
+
+await authorize(
+    updateProject,
+    {
+        user,
+        resource: project,
+    }
+);
+```
+
+`cannot()` is the inverse of `can()`. `authorize()` throws `AuthorizationError` when the policy returns a falsy result.
+
+Policies may be synchronous or asynchronous.
+
+## Same-origin mutation protection
+
+Request-security helpers are exported from `bcp/server`.
+
+```ts
+import {
+    requireSameOriginRequest,
+} from "bcp/server";
+
+export async function POST() {
+    await requireSameOriginRequest();
+
+    // mutation
+}
+```
+
+For unsafe HTTP methods BCP checks `Origin` first and then `Referer`. The application request origin is allowed automatically.
+
+Additional trusted origins can be declared explicitly:
+
+```ts
+await requireSameOriginRequest({
+    allowedOrigins: [
+        "https://admin.example.com",
+    ],
+});
+```
+
+Missing origin information is rejected for unsafe methods by default. Set `allowMissingOrigin: true` only when a trusted non-browser client cannot send either header and another protection is in place.
+
+## CSRF tokens
+
+BCP provides an HttpOnly double-submit style CSRF cookie plus a signed token returned to server code.
+
+Create a token during page rendering or another trusted same-origin response:
+
+```ts
+import {
+    createCsrfToken,
+} from "bcp/server";
+
+const csrfToken =
+    await createCsrfToken();
+```
+
+Pass the returned token to the page/form and submit it back in an application-controlled field or the default header:
+
+```text
+X-BCP-CSRF: <token>
+```
+
+Verify a mutation:
+
+```ts
+import {
+    requireCsrfRequest,
+} from "bcp/server";
+
+export async function POST() {
+    await requireCsrfRequest();
+
+    // protected mutation
+}
+```
+
+When a form token is parsed from `FormData`, pass it explicitly:
+
+```ts
+await requireCsrfRequest({
+    token:
+        String(
+            formData.get("csrf") ??
+            ""
+        ),
+});
+```
+
+`requireCsrfRequest()` combines same-origin validation and CSRF token validation for unsafe methods. Safe read requests do not require a token.
+
+## CSRF secret
+
+The token signer resolves secrets in this order:
+
+```text
+explicit options.secret
+BCP_CSRF_SECRET
+BCP_SESSION_SECRET
+```
+
+Secrets must contain at least 32 UTF-8 bytes.
+
+For deployments that want separate authentication and CSRF key rotation, define:
+
+```dotenv
+BCP_SESSION_SECRET=...
+BCP_CSRF_SECRET=...
+```
+
+The default CSRF cookie is:
+
+```text
+name      bcp_csrf
+HttpOnly  true
+SameSite  Lax
+Secure    true in production
+max age   2 hours
+```
+
+The cookie is signed but the token itself must still be treated as security-sensitive request state. Do not log CSRF tokens.
+
+## Lower-level verification
+
+The following helpers are available when applications need custom response behavior:
+
+```ts
+isSafeHttpMethod()
+isSameOriginRequest()
+verifyCsrfToken()
+verifyCsrfRequest()
+destroyCsrfToken()
+```
+
+`RequestSecurityError` uses status `403` and distinguishes `INVALID_ORIGIN` from `INVALID_CSRF_TOKEN`.
+
+## Security model
+
+Authorization and CSRF protection solve different problems:
+
+```text
+auth() / session
+    -> who is this user?
+
+permission / policy
+    -> may this user perform this operation?
+
+origin + CSRF
+    -> did this browser mutation come from an allowed application context?
+```
+
+Applications should still validate all mutation input and enforce authorization on the server. Client-side UI checks are only presentation logic and must not replace server authorization.
+
+`bcp/auth` and the request-security helpers in `bcp/server` are server-only surfaces.

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.4",
+  "versionTarget": "0.2.6",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -35,11 +35,13 @@
     },
     {
       "id": "authentication",
-      "title": "Authentication",
-      "description": "Authentication core, auth-aware route guards and JWT cookie sessions.",
+      "title": "Authentication & Authorization",
+      "description": "Authentication Platform v2, revocable sessions, permission/policy authorization, route guards and CSRF protection.",
       "pages": [
         { "route": "/docs/authentication", "source": "authentication.md", "title": "Authentication" },
+        { "route": "/docs/auth-session-store", "source": "auth-session-store.md", "title": "Auth Session Stores" },
         { "route": "/docs/auth-route-guards", "source": "auth-route-guards.md", "title": "Auth Route Guards" },
+        { "route": "/docs/authorization-security", "source": "authorization-security.md", "title": "Authorization & Security v2" },
         { "route": "/docs/session-auth", "source": "session-auth.md", "title": "JWT Sessions" }
       ]
     },
@@ -105,7 +107,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.4", "source": "releases/0.2.4.md", "version": "0.2.4", "state": "unreleased" },
+    { "route": "/releases/0.2.6", "source": "releases/0.2.6.md", "version": "0.2.6", "state": "unreleased" },
+    { "route": "/releases/0.2.5", "source": "releases/0.2.5.md", "version": "0.2.5" },
+    { "route": "/releases/0.2.4", "source": "releases/0.2.4.md", "version": "0.2.4" },
     { "route": "/releases/0.2.3", "source": "releases/0.2.3.md", "version": "0.2.3" },
     { "route": "/releases/0.2.2", "source": "releases/0.2.2.md", "version": "0.2.2" },
     { "route": "/releases/0.2.1", "source": "releases/0.2.1.md", "version": "0.2.1" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "releaseState": "unreleased",
-  "baseline": "application-packaging",
+  "baseline": "authorization-security-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -47,6 +47,18 @@
     "formActions": true,
     "middlewareV2": true,
     "jwtCookieSessions": true,
+    "authenticationPlatformV2": true,
+    "authSessionStore": true,
+    "authSessionRevocation": true,
+    "authLogoutAll": true,
+    "authIdleTimeout": true,
+    "authGuestGuard": true,
+    "authorizationSecurityV2": true,
+    "permissionAuthorization": true,
+    "authorizationPolicies": true,
+    "permissionRouteGuards": true,
+    "sameOriginProtection": true,
+    "csrfProtection": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -86,7 +98,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.3",
+    "previousBaseline": "0.2.5",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -99,7 +111,10 @@
     "apiReference": "api-reference.md",
     "environmentValidation": "environment-validation.md",
     "applicationPackaging": "application-packaging.md",
+    "authentication": "authentication.md",
+    "authSessionStore": "auth-session-store.md",
+    "authorizationSecurity": "authorization-security.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.4.md"
+    "releaseNotes": "releases/0.2.6.md"
   }
 }