@chidchanun/bcp 0.2.5 → 0.2.7

package/docs/api-reference.md

@@ -164,23 +164,33 @@ Related guides: [Database](database.md), [Database Migrations](database-migratio
 
 ## `bcp/auth`
 
-Server-only Authentication Platform v2 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,
@@ -192,45 +202,107 @@ import {
     type AuthSessionStore,
     type AuthSessionStoreRecord,
     type AuthUser,
+    type AuthorizationContext,
+    type AuthorizationMatch,
+    type AuthorizationPolicy,
     type MemoryAuthSessionStore,
+    type PermissionCheckOptions,
+    type PermissionRequirement,
+    type RequirePermissionOptions,
 } from "bcp/auth";
 ```
 
-The default mode remains stateless signed JWT-cookie authentication.
+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.
 
-`logoutAll()`, `revokeSession()`, and `revokeUserSessions()` require server-side session state. `requireGuest()` / `createGuestGuard()` support login/register routes that should redirect already-authenticated users.
+Authorization & Security v2 adds permission checks, permission route guards and resource-aware policy functions:
 
-Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [JWT Sessions](session-auth.md).
+- `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/observability`
+
+Server-only Observability Platform v2 APIs.
+
+```ts
+import {
+    createHealthRegistry,
+    createMetricsRegistry,
+    createMetricsResponse,
+    createRequestMetricsMiddleware,
+    type CounterMetric,
+    type GaugeMetric,
+    type HealthCheck,
+    type HealthCheckOptions,
+    type HealthCheckReportItem,
+    type HealthCheckResult,
+    type HealthRegistry,
+    type HealthReport,
+    type HistogramMetric,
+    type HistogramOptions,
+    type MetricDefinitionOptions,
+    type MetricLabels,
+    type MetricLabelValue,
+    type MetricsRegistry,
+    type RequestMetricsOptions,
+} from "bcp/observability";
+```
+
+`createMetricsRegistry()` provides process-local counters, gauges and histograms. `createMetricsResponse()` renders Prometheus-compatible text exposition. `createRequestMetricsMiddleware()` measures HTTP request counts and duration using bounded `method` / `status` labels by default and intentionally does not label by raw path.
+
+`createHealthRegistry()` registers synchronous or asynchronous liveness/readiness checks, applies per-check timeouts and produces JSON health responses with HTTP `200` when all checks pass or `503` when any check fails.
+
+The built-in registry is process-local. Multi-instance deployments should scrape each process/container or aggregate through external monitoring infrastructure.
+
+Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.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 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/development-logging.md

@@ -1,6 +1,21 @@
 # Logging and observability
 
-BCP Framework 0.1.23 adds a structured server logger and upgrades development request timing output while keeping framework-internal browser/bootstrap traffic quiet by default.
+BCP Framework 0.1.23 added the structured server logger and development request timing output. BCP Framework `0.2.7` complements that logging layer with process-local metrics and health/readiness primitives through `bcp/observability`.
+
+Use these layers together:
+
+```text
+bcp/server
+  -> structured event/request logs
+
+bcp/observability
+  -> counters, gauges, histograms
+  -> Prometheus exposition
+  -> request metrics middleware
+  -> health/readiness checks
+```
+
+See [Observability Platform v2](observability.md) for the `0.2.7` metrics and health APIs.
 
 ## Server logger
 
@@ -205,6 +220,34 @@ ssr.render
 
 They are therefore visible when `BCP_LOG_LEVEL=debug` and stay out of normal `info` output.
 
+## Metrics vs logs
+
+Logs and metrics serve different purposes.
+
+Use structured logs when you need per-event context:
+
+```text
+request ID
+operation
+error stack
+resource identity
+diagnostic fields
+```
+
+Use metrics when you need aggregate trends:
+
+```text
+request count
+status distribution
+latency buckets
+queue depth
+worker count
+```
+
+Avoid copying high-cardinality log fields such as request IDs, user IDs or raw paths into metric labels.
+
+The `0.2.7` request metrics middleware follows this rule by using `method` and `status` labels by default.
+
 ## Errors
 
 Pass an `Error` as a structured field: