@chidchanun/bcp 0.2.5 → 0.2.6

package/docs/auth-route-guards.md

@@ -1,6 +1,6 @@
 # Auth Route Guards
 
-BCP Framework integrates Authentication Platform v2 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
 
@@ -30,7 +30,7 @@ export const guard =
     });
 ```
 
-## Guest-only routes — 0.2.5
+## Guest-only routes — 0.2.5+
 
 Login, registration, and password-recovery entry pages often should not remain accessible after the user has already authenticated.
 
@@ -60,30 +60,9 @@ signed-in user
 303 /dashboard
 ```
 
-Use `redirectTo: null` to return `409 Already authenticated` instead of redirecting:
+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",
-    });
-}
-```
+The low-level form is `requireGuest()`.
 
 ## Require a role
 
@@ -110,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:
@@ -198,7 +206,7 @@ export async function guard() {
 
 ## Session-store policies apply inside guards
 
-`requireAuth()`, `requireRole()`, and `requireGuest()` all use the same `auth()` runtime.
+`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.
 
@@ -254,7 +262,7 @@ export async function loader({
 
 ## Standalone production behavior
 
-`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`.
+`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`.
 
 The production form-action bundle uses the same runtime boundary because guards may execute before an action.
 

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.5",
+  "versionTarget": "0.2.6",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -35,12 +35,13 @@
     },
     {
       "id": "authentication",
-      "title": "Authentication",
-      "description": "Authentication Platform v2, revocable session stores, guest/auth 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" }
       ]
     },
@@ -106,7 +107,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.5", "source": "releases/0.2.5.md", "version": "0.2.5", "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" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "releaseState": "unreleased",
-  "baseline": "authentication-platform-v2",
+  "baseline": "authorization-security-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -53,6 +53,12 @@
     "authLogoutAll": true,
     "authIdleTimeout": true,
     "authGuestGuard": true,
+    "authorizationSecurityV2": true,
+    "permissionAuthorization": true,
+    "authorizationPolicies": true,
+    "permissionRouteGuards": true,
+    "sameOriginProtection": true,
+    "csrfProtection": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -92,7 +98,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.4",
+    "previousBaseline": "0.2.5",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -107,7 +113,8 @@
     "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.5.md"
+    "releaseNotes": "releases/0.2.6.md"
   }
 }