@chidchanun/bcp 0.2.4 → 0.2.6

package/README.md

@@ -1,14 +1,14 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, database access, validation, uploads, storage and standalone Node.js production deployment.
+BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, authorization, database access, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.4 — Application Packaging`
+> **Development target:** `0.2.6 — Authorization & Security v2`
 >
-> `0.2.4` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.6` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## 0.2 platform
 
-`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, and `0.2.4` adds deployment-oriented application packaging without intentionally removing the existing public application model.
+`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, `0.2.4` added Application Packaging, `0.2.5` added Authentication Platform v2, and `0.2.6` adds permission/policy authorization plus CSRF and same-origin request protection without intentionally removing the existing public application model.
 
 Machine-readable platform contracts:
 
@@ -31,8 +31,9 @@ docs/api-manifest.json
 | Routing | Static, dynamic, catch-all, optional catch-all and route groups |
 | Server data | Route `loader.ts`, request-scoped server APIs |
 | Mutations | Route-owned `actions.ts` and `<Form>` |
-| Authorization | `guard.ts`, `requireAuth()`, `requireRole()` |
-| Authentication | JWT cookie sessions and auth helpers |
+| Authentication | JWT cookie sessions, optional server-side session stores, revocation, logout-all, idle timeout and rotation |
+| Authorization | Auth/guest/role/permission route guards, flat permissions and resource-aware policies |
+| Request security | Same-origin validation and signed CSRF tokens for unsafe mutations |
 | Middleware | Middleware System v2 with onion execution |
 | Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
@@ -155,8 +156,6 @@ await db.connect();
 await db.disconnect();
 ```
 
-`db.close()` remains available for backward-compatible shutdown handling.
-
 Migration CLI:
 
 ```bash
@@ -166,8 +165,6 @@ bcp db status
 bcp db rollback
 ```
 
-BCP makes framework migration bookkeeping provider-aware. Application migration SQL itself is not automatically translated between SQL dialects.
-
 Read more:
 
 - [Database](docs/database.md)
@@ -175,18 +172,12 @@ Read more:
 
 ## Application Packaging — 0.2.4
 
-Create a fresh production build and convert it into a deployment-oriented package:
+Create a fresh production build and deployment package:
 
 ```bash
 bcp package
 ```
 
-Framework-repository development can also run:
-
-```bash
-npm run package
-```
-
 Output:
 
 ```text
@@ -206,30 +197,179 @@ Output:
 └─ README.md
 ```
 
-The package layer:
+Read more:
 
-- runs a fresh `bcp build` before packaging,
-- strips application `devDependencies` from the deployment package,
-- derives a production-only npm v3 lock graph when safe,
-- records `npm ci --omit=dev` when the production lock is available,
-- falls back explicitly to `npm install --omit=dev` when a safe lock cannot be produced,
-- writes deployment/runtime metadata,
-- records environment variable names without copying `.env` values,
-- creates SHA-256 file integrity metadata,
-- generates a Node 24 Alpine Docker starter.
+- [Application Packaging](docs/application-packaging.md)
+- [Deployment](docs/deployment.md)
 
-The current package target is:
+## Authentication Platform v2 — 0.2.5
 
-```text
-standalone-node
+Stateless signed JWT-cookie authentication remains supported:
+
+```ts
+import {
+    auth,
+    login,
+    logout,
+} from "bcp/auth";
 ```
 
-Native executable, desktop, Android and iOS packaging remain later roadmap work.
+Applications that need centralized revocation can add a server-side session store:
+
+```ts
+import {
+    createAuth,
+    createMemoryAuthSessionStore,
+} from "bcp/auth";
+
+const sessionStore =
+    createMemoryAuthSessionStore();
+
+export const appAuth =
+    createAuth({
+        store: sessionStore,
+        idleTimeout: 60 * 30,
+    });
+```
+
+With a store configured, authentication requires both a valid signed JWT cookie and an active `sid` record. The built-in memory store is intended for development/tests; production multi-instance deployments should implement `AuthSessionStore` with shared storage.
 
 Read more:
 
-- [Application Packaging](docs/application-packaging.md)
-- [Deployment](docs/deployment.md)
+- [Authentication](docs/authentication.md)
+- [Auth Session Stores](docs/auth-session-store.md)
+- [Auth Route Guards](docs/auth-route-guards.md)
+
+## Authorization & Security v2 — 0.2.6
+
+### Permissions
+
+Use flat permissions directly from `bcp/auth`:
+
+```ts
+import {
+    hasPermission,
+    requirePermission,
+} from "bcp/auth";
+
+hasPermission(
+    user,
+    "users.read"
+);
+
+await requirePermission(
+    [
+        "users.read",
+        "users.write",
+    ],
+    {
+        match: "all",
+    }
+);
+```
+
+Route trees can use a permission guard:
+
+```ts
+import {
+    createPermissionGuard,
+} from "bcp/auth";
+
+export const guard =
+    createPermissionGuard(
+        "admin.access"
+    );
+```
+
+The default permission field is `permissions`. Applications can select another field such as `scopes`.
+
+### Resource policies
+
+For ownership, tenant or resource-state rules:
+
+```ts
+import {
+    authorize,
+    defineAuthorizationPolicy,
+} from "bcp/auth";
+
+const updateProject =
+    defineAuthorizationPolicy(
+        ({
+            user,
+            resource,
+        }) =>
+            resource.ownerId ===
+            user.id
+    );
+
+await authorize(
+    updateProject,
+    {
+        user,
+        resource: project,
+    }
+);
+```
+
+Available policy helpers:
+
+```text
+can()
+cannot()
+authorize()
+AuthorizationError
+```
+
+### Same-origin and CSRF protection
+
+Request-security helpers are exposed from `bcp/server`:
+
+```ts
+import {
+    createCsrfToken,
+    requireCsrfRequest,
+    requireSameOriginRequest,
+} from "bcp/server";
+```
+
+Protect an unsafe API/action mutation with origin validation:
+
+```ts
+await requireSameOriginRequest();
+```
+
+For signed CSRF protection:
+
+```ts
+const csrfToken =
+    await createCsrfToken();
+
+// Render/send csrfToken through the trusted application UI.
+
+await requireCsrfRequest({
+    token: submittedToken,
+});
+```
+
+Default CSRF header/cookie:
+
+```text
+X-BCP-CSRF
+bcp_csrf
+```
+
+Secret resolution:
+
+```text
+explicit options.secret
+    ↓
+BCP_CSRF_SECRET
+    ↓
+BCP_SESSION_SECRET
+```
+
+Read more: [Authorization & Security v2](docs/authorization-security.md)
 
 ## Public entrypoints
 
@@ -292,16 +432,14 @@ bcp generate middleware
 bcp generate migration create_users
 ```
 
-Page/API/middleware generators require `--force` before replacing an existing scaffold target.
-
 ## Application model
 
 ```text
 Browser
   ↓
-Security / middleware / cache
+Origin / CSRF / middleware / cache
   ↓
-Route guard
+Authentication + authorization guard
   ↓
 Loader / action / API route
   ↓
@@ -310,24 +448,6 @@ React SSR
 Hydration / SPA navigation
 ```
 
-Typical route structure:
-
-```text
-app/
-├─ layout.tsx
-├─ page.tsx
-├─ dashboard/
-│  ├─ guard.ts
-│  └─ users/
-│     └─ [id]/
-│        ├─ loader.ts
-│        ├─ actions.ts
-│        └─ page.tsx
-└─ api/
-   └─ upload/
-      └─ route.ts
-```
-
 ## Production build
 
 Raw standalone build:
@@ -337,23 +457,13 @@ npm run build
 npm run start
 ```
 
-Output:
-
-```text
-.bcp-framework/build/
-├─ client/
-├─ public/
-└─ server/
-   └─ server.mjs
-```
-
 Deployment package:
 
 ```bash
 bcp package
 ```
 
-Both current targets remain Node.js `standalone-node` applications. Production hardening includes configurable request/header/keep-alive/shutdown timeouts, trusted-proxy handling and graceful `SIGTERM` / `SIGINT` shutdown.
+Both current targets remain Node.js `standalone-node` applications.
 
 ## Documentation Platform
 
@@ -367,14 +477,6 @@ docs/platform-manifest.json
 docs/api-manifest.json
 ```
 
-The manifests provide navigation order, routes, Markdown sources, version/release state, public entrypoints and API guide ownership.
-
-Read more:
-
-- [Documentation Source Map](docs/README.md)
-- [Documentation Platform](docs/documentation-platform.md)
-- [Application Packaging](docs/application-packaging.md)
-
 ## Release validation
 
 Framework releases must pass:
@@ -389,7 +491,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.4` adds Application Packaging unit and prepared-package smoke checks covering production dependency metadata, production lock pruning, environment-value exclusion, deployment metadata and the `bcp package` CLI surface.
+`0.2.6` adds Authorization & Security v2 unit and prepared-package smoke checks covering permission matching, policy authorization, permission route guards, same-origin mutation validation and signed CSRF tokens.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -408,12 +510,14 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.2` | Configuration & Environment v2 |
 | `0.2.3` | Database Platform v2 |
 | `0.2.4` | Application Packaging |
+| `0.2.5` | Authentication Platform v2 |
+| `0.2.6` | Authorization & Security v2 |
 
 ## Roadmap
 
-`0.2.4 — Application Packaging` establishes the deployment artifact contract for the existing standalone Node.js runtime.
+`0.2.6 — Authorization & Security v2` establishes the permission/policy and browser-mutation security layer on top of Authentication Platform v2.
 
-The next planned framework milestone can build on this package contract without changing the current Node.js deployment model. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+The next `0.2.x` milestone can build on the existing runtime, database, auth, security and packaging contracts. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License
 

package/docs/README.md

@@ -2,9 +2,9 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.2`
+> **Documentation target:** BCP Framework `0.2.6 — Authorization & Security v2`
 >
-> **Release state:** unreleased development target. Do not label `0.2.2` as published until RC validation, tagging and npm publication complete.
+> **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
 ## Documentation architecture
 
@@ -41,32 +41,78 @@ manifest-driven sync
 
 Framework source and tests remain authoritative for runtime behavior.
 
-## 0.2.2 — Configuration & Environment v2
+## Current 0.2.x milestones
 
-`0.2.2` adds an optional typed application environment schema while preserving the established framework configuration precedence.
+| Version | Milestone |
+| --- | --- |
+| `0.2.0` | Framework Platform |
+| `0.2.1` | Documentation Platform |
+| `0.2.2` | Configuration & Environment v2 |
+| `0.2.3` | Database Platform v2 |
+| `0.2.4` | Application Packaging |
+| `0.2.5` | Authentication Platform v2 |
+| `0.2.6` | Authorization & Security v2 |
+
+## 0.2.6 — Authorization & Security v2
+
+`0.2.6` adds server-side permission checks, resource-aware authorization policies, permission route guards, same-origin mutation validation and signed CSRF protection.
 
 New/updated documentation sources:
 
 | Source | Purpose |
 | --- | --- |
-| `environment-validation.md` | `bcp.environment.*`, validation rules, CLI checks and secret/public boundaries |
-| `configuration.md` | Framework configuration precedence and diagnostics workflow |
-| `platform-manifest.json` | Declares typed environment/config diagnostics capabilities |
-| `api-manifest.json` | Maps `bcp/config` to configuration and environment guides |
-| `releases/0.2.2.md` | Configuration & Environment v2 release notes |
+| `authorization-security.md` | Permissions, policies, permission guards, same-origin validation and CSRF APIs |
+| `auth-route-guards.md` | Auth/guest/role/permission route guard guidance |
+| `api-reference.md` | Public authorization and request-security exports |
+| `platform-manifest.json` | Authorization/security capability flags |
+| `api-manifest.json` | `bcp/auth` and `bcp/server` guide ownership |
+| `releases/0.2.6.md` | Authorization & Security v2 release notes |
 
-Primary command:
+Primary authorization APIs:
 
-```bash
-bcp config check
+```ts
+import {
+    authorize,
+    can,
+    createPermissionGuard,
+    defineAuthorizationPolicy,
+    hasPermission,
+    requirePermission,
+} from "bcp/auth";
 ```
 
-JSON diagnostics:
+Primary browser-mutation security APIs:
 
-```bash
-bcp config check --json
+```ts
+import {
+    createCsrfToken,
+    requireCsrfRequest,
+    requireSameOriginRequest,
+} from "bcp/server";
+```
+
+## Security model
+
+The `0.2.6` server model separates concerns:
+
+```text
+authentication
+    -> identify a signed/revocable session
+
+authorization
+    -> permissions + policies + route guards
+
+request security
+    -> Origin/Referer validation + signed CSRF token
+
+input validation
+    -> application schema/domain checks
 ```
 
+All authorization decisions must remain server-side. Client UI permission checks may improve presentation but do not replace route/action/API enforcement.
+
+CSRF tokens use `BCP_CSRF_SECRET` when configured and otherwise fall back to `BCP_SESSION_SECRET`. Security secrets must contain at least 32 UTF-8 bytes.
+
 ## Update rule
 
 When framework behavior or public surface changes:
@@ -89,7 +135,7 @@ Current sections:
 ```text
 Getting Started
 Routing & Data
-Authentication
+Authentication & Authorization
 Database
 Runtime & Infrastructure
 Storage & Uploads
@@ -103,76 +149,25 @@ Important current routes:
 
 | Website route | Markdown source |
 | --- | --- |
-| `/docs/configuration` | `configuration.md` |
-| `/docs/environment-validation` | `environment-validation.md` |
-| `/docs/platform-contract` | `platform-contract.md` |
-| `/docs/documentation-platform` | `documentation-platform.md` |
-| `/docs/migration-0.2` | `migration-0.2.md` |
+| `/docs/authentication` | `authentication.md` |
+| `/docs/auth-session-store` | `auth-session-store.md` |
+| `/docs/auth-route-guards` | `auth-route-guards.md` |
+| `/docs/authorization-security` | `authorization-security.md` |
+| `/docs/application-packaging` | `application-packaging.md` |
+| `/docs/database` | `database.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.2` | `releases/0.2.2.md` |
+| `/releases/0.2.6` | `releases/0.2.6.md` |
 
 Every route/source pair is validated by unit tests.
 
-## Configuration source model
-
-Framework settings:
-
-```text
-bcp.config.ts
-bcp.config.mts
-bcp.config.js
-bcp.config.mjs
-```
-
-Application environment schema:
-
-```text
-bcp.environment.ts
-bcp.environment.mts
-bcp.environment.js
-bcp.environment.mjs
-```
-
-Only one file from each convention may exist at a time.
-
-The environment schema is optional. Existing applications without `bcp.environment.*` continue to use the previous environment-loading behavior.
-
-Configuration precedence remains:
-
-```text
-CLI override
-    ↓
-BCP_* environment
-    ↓
-bcp.config.*
-    ↓
-framework defaults
-```
-
-See [Environment Validation](environment-validation.md).
-
-## Environment security boundary
-
-`BCP_PUBLIC_*` values may be embedded into browser bundles. They must never contain credentials/private secrets.
-
-A variable declared with:
-
-```ts
-secret: true
-```
-
-must not use the `BCP_PUBLIC_` prefix. The configuration validator treats that combination as an error.
-
-`secret: true` is validation/tooling metadata and does not encrypt a value.
-
 ## Platform manifest
 
-`docs/platform-manifest.json` describes the supported framework baseline, including:
+`docs/platform-manifest.json` describes:
 
 ```text
 framework version/release state
 Node/React/runtime baseline
-production build target
+production build/package target
 public package entrypoints
 CLI command families
 capability flags
@@ -180,14 +175,6 @@ previous-baseline compatibility intent
 documentation contract files
 ```
 
-`0.2.2` declares the additional capabilities:
-
-```text
-typedEnvironmentSchema
-configurationDiagnostics
-configCheckCli
-```
-
 The supported production target remains:
 
 ```text
@@ -196,7 +183,7 @@ standalone-node
 
 ## API manifest
 
-`docs/api-manifest.json` describes the public package entrypoints documentation tooling may present as supported API surfaces.
+`docs/api-manifest.json` describes public package entrypoints documentation tooling may present as supported APIs.
 
 Current entrypoints:
 
@@ -214,13 +201,6 @@ bcp/server-only
 bcp/middleware
 ```
 
-`bcp/config` owns both:
-
-```text
-/docs/configuration
-/docs/environment-validation
-```
-
 The API-manifest entrypoint set must match the platform public-entrypoint set exactly.
 
 ## bcp-docs-web synchronization
@@ -241,14 +221,6 @@ load referenced Markdown
 synchronize CMS/search/navigation
 ```
 
-Examples from the docs-web project:
-
-```powershell
-npm run docs:sync -- --dry-run
-npm run docs:sync -- --publish-new
-npm run docs:sync -- --ref=v0.2.1
-```
-
 ## Source conventions
 
 - one H1 per Markdown page,
@@ -263,7 +235,7 @@ npm run docs:sync -- --ref=v0.2.1
 
 ## Release validation
 
-Before publishing `0.2.2`:
+Before publishing `0.2.6`:
 
 ```bash
 npm run typecheck
@@ -274,16 +246,17 @@ npm run test:e2e
 npm run rc:check
 ```
 
-Configuration & Environment v2 validation covers:
-
-- typed environment rules/defaults,
-- project `bcp.environment.*` loading,
-- public/secret safety boundary,
-- production diagnostics,
-- `bcp config check` CLI parsing,
-- dev schema watching,
-- public `bcp/config` exports,
-- prepared npm package files,
+Authorization & Security v2 validation covers:
+
+- permission normalization and any/all matching,
+- permission route guards,
+- sync/async authorization policies,
+- `AuthorizationError` denial behavior,
+- same-origin mutation checks,
+- signed CSRF tokens,
+- malformed/cross-origin rejection,
+- public `bcp/auth` and `bcp/server` exports,
+- prepared npm package contents,
 - docs/platform/API version parity.
 
 The final release tag must point to the exact commit that passed the complete RC sequence.
@@ -304,19 +277,3 @@ release notes
 ```
 
 `bcp-docs-web` remains the presentation/search/navigation layer for this content.
-
-## Next direction
-
-Planned next milestone:
-
-```text
-0.2.3 — Database Platform v2
-```
-
-Focus:
-
-- database adapter contract,
-- PostgreSQL support,
-- SQLite support,
-- connection lifecycle improvements,
-- provider-consistent migration workflows.