@chidchanun/bcp 0.2.3 → 0.2.5

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.5 — Authentication Platform 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,73 @@ 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.5 — Authentication Platform v2
+
+`0.2.5` keeps stateless signed JWT-cookie authentication as the default and adds optional server-side session state for revocation and inactivity policy.
 
 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 |
+| `authentication.md` | Auth core, revocation, logout-all, rotation and idle timeout |
+| `auth-session-store.md` | `AuthSessionStore`, memory adapter and production-store guidance |
+| `auth-route-guards.md` | Auth, guest and role route guards |
+| `api-reference.md` | Public Authentication Platform v2 exports |
+| `platform-manifest.json` | Authentication v2 capability flags |
+| `api-manifest.json` | `bcp/auth` guide ownership |
+| `releases/0.2.5.md` | Authentication Platform v2 release notes |
 
-Primary command:
+Primary public entrypoint:
 
-```bash
-bcp config check
+```ts
+import {
+    auth,
+    createAuth,
+    createMemoryAuthSessionStore,
+    login,
+    logout,
+    logoutAll,
+    requireAuth,
+    requireGuest,
+    requireRole,
+} from "bcp/auth";
 ```
 
-JSON diagnostics:
+## Authentication security model
 
-```bash
-bcp config check --json
+Default mode:
+
+```text
+signed HttpOnly JWT cookie
+      ↓
+signature + expiry validation
+      ↓
+authenticated session
 ```
 
+Optional revocable mode:
+
+```text
+signed HttpOnly JWT cookie
+      +
+server-side sid store
+      ↓
+revocable authenticated session
+```
+
+The built-in memory store is intended for development/tests. Multi-process production systems should implement `AuthSessionStore` using shared durable storage.
+
 ## Update rule
 
 When framework behavior or public surface changes:
@@ -103,76 +144,24 @@ 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/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.5` | `releases/0.2.5.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 +169,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 +177,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 +195,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 +215,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 +229,7 @@ npm run docs:sync -- --ref=v0.2.1
 
 ## Release validation
 
-Before publishing `0.2.2`:
+Before publishing `0.2.5`:
 
 ```bash
 npm run typecheck
@@ -274,16 +240,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,
+Authentication Platform v2 validation covers:
+
+- stateless JWT backward compatibility,
+- session-store registration and lookup,
+- session revocation,
+- logout-all,
+- idle timeout,
+- rotation with old-session revocation,
+- guest route guards,
+- public `bcp/auth` 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 +271,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.

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -85,9 +85,10 @@
       "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 with JWT cookies, optional revocable session stores, idle timeout, logout-all and auth/guest/role route guards.",
       "guides": [
         "/docs/authentication",
+        "/docs/auth-session-store",
         "/docs/auth-route-guards",
         "/docs/session-auth"
       ]

package/docs/api-reference.md

@@ -164,25 +164,45 @@ Related guides: [Database](database.md), [Database Migrations](database-migratio
 
 ## `bcp/auth`
 
-Authentication and authorization APIs.
+Server-only Authentication Platform v2 APIs.
 
 ```ts
 import {
     auth,
     createAuth,
     createAuthGuard,
+    createGuestGuard,
+    createMemoryAuthSessionStore,
     createRoleGuard,
     getGuardAuth,
     getSession,
     login,
     logout,
+    logoutAll,
     requireAuth,
+    requireGuest,
     requireRole,
+    revokeSession,
+    revokeUserSessions,
     rotateSession,
+    type AuthApi,
+    type AuthLoginOptions,
+    type AuthOptions,
+    type AuthSession,
+    type AuthSessionStore,
+    type AuthSessionStoreRecord,
+    type AuthUser,
+    type MemoryAuthSessionStore,
 } from "bcp/auth";
 ```
 
-Related guides: [Authentication](authentication.md), [Auth Route Guards](auth-route-guards.md), [JWT Sessions](session-auth.md).
+The default 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.
+
+Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [JWT Sessions](session-auth.md).
 
 ## `bcp/server`
 

package/docs/application-packaging.md

@@ -0,0 +1,243 @@
+# Application Packaging
+
+BCP Framework `0.2.4` adds an application packaging layer on top of the standalone Node.js production build.
+
+The goal is to turn a BCP project into a deployment-oriented directory that contains the built application, production dependency metadata, deployment metadata and container starter files without copying source-only development dependencies or project secrets.
+
+## Create a package
+
+From the application root:
+
+```bash
+bcp package
+```
+
+`bcp package` always runs a fresh production build first. This prevents an older `.bcp-framework/build` directory from being packaged accidentally.
+
+The output is written to:
+
+```text
+.bcp-framework/
+└── package/
+    ├── client/
+    ├── server/
+    │   └── server.mjs
+    ├── public/                 # when the application has public assets
+    ├── manifest.json
+    ├── package.json
+    ├── package-lock.json       # when a safe npm v3 production lock can be derived
+    ├── bcp.package.json
+    ├── bcp.deployment.json
+    ├── bcp.env.json
+    ├── Dockerfile
+    ├── .dockerignore
+    └── README.md
+```
+
+The current packaging target is:
+
+```text
+standalone-node
+```
+
+Native executable, desktop and mobile packaging are not part of `0.2.4`.
+
+## Production dependencies
+
+The generated package-level `package.json` keeps runtime metadata only:
+
+- `dependencies`
+- `optionalDependencies`
+- `peerDependencies`
+- supported peer metadata / overrides when present
+- `engines.node`
+- the standalone `start` script
+
+`devDependencies` are intentionally excluded.
+
+When the project has an npm lockfile v3 that can be safely converted to the production dependency graph, BCP writes a pruned `package-lock.json` and records:
+
+```bash
+npm ci --omit=dev
+```
+
+as the deployment install command.
+
+If a safe production lock cannot be derived, packaging continues without copying an unsafe lockfile and records:
+
+```bash
+npm install --omit=dev
+```
+
+instead. The CLI prints a warning in that case.
+
+This fallback is intentional: an application package must not pretend to be reproducibly locked when the framework cannot prove the lock metadata is safe for the standalone artifact.
+
+## Package manifest
+
+`bcp.package.json` describes the produced artifact. It includes:
+
+- schema version
+- target runtime
+- BCP Framework version
+- application name/version
+- Node.js requirement
+- entrypoint and start command
+- dependency installation command
+- whether a production lockfile is included
+- build/deployment/environment manifest paths
+- package file inventory
+- byte size and SHA-256 digest for each packaged file
+
+Example shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "target": "standalone-node",
+  "frameworkVersion": "0.2.4",
+  "application": {
+    "name": "my-app",
+    "version": "0.1.0"
+  },
+  "runtime": {
+    "node": ">=24.11.0",
+    "entrypoint": "server/server.mjs",
+    "startCommand": "npm start"
+  },
+  "install": {
+    "command": "npm ci --omit=dev",
+    "lockfile": true,
+    "devDependenciesIncluded": false
+  }
+}
+```
+
+The file inventory allows deployment tooling to verify an application package before shipping it to a server or container image.
+
+## Deployment manifest
+
+`bcp.deployment.json` is a small deployment contract for the current package target. It records:
+
+```text
+runtime: Node.js
+install: npm ci --omit=dev (or npm install --omit=dev fallback)
+start: npm start
+entrypoint: server/server.mjs
+container starter: Dockerfile
+```
+
+Future deployment adapters can consume this manifest without changing the current standalone Node.js contract.
+
+## Environment manifest and secret safety
+
+BCP application packages do **not** copy project `.env` files.
+
+`bcp.env.json` contains metadata only. When files such as `.env.example` exist, BCP can record declared variable names, but it does not record their values.
+
+For example:
+
+```dotenv
+DATABASE_URL=postgresql://user:password@example/db
+BCP_SESSION_SECRET=secret
+```
+
+is represented only as names such as:
+
+```json
+{
+  "declaredKeys": [
+    "BCP_SESSION_SECRET",
+    "DATABASE_URL"
+  ],
+  "valuesIncluded": false,
+  "environmentFilesIncluded": false
+}
+```
+
+Supply real secrets through your deployment environment, secret manager or container/orchestrator configuration.
+
+Runtime server overrides remain available through:
+
+```text
+BCP_HOSTNAME
+BCP_PORT
+```
+
+## Run the package
+
+After copying `.bcp-framework/package` to the target machine:
+
+```bash
+cd package
+npm ci --omit=dev
+npm start
+```
+
+If `bcp.package.json` says `lockfile: false`, use the recorded install command instead.
+
+You can also start the bundled entrypoint directly after dependencies are installed:
+
+```bash
+node server/server.mjs
+```
+
+## Docker
+
+The generated package contains a starter `Dockerfile`:
+
+```bash
+docker build -t my-bcp-app .
+docker run --rm -p 3000:3000 my-bcp-app
+```
+
+Pass runtime environment values with the deployment mechanism you normally use. Do not bake secrets into the image.
+
+## Build vs package
+
+Use `bcp build` when you need the framework's raw standalone build output:
+
+```text
+.bcp-framework/build/
+```
+
+Use `bcp package` when you need a deployment-oriented artifact:
+
+```text
+.bcp-framework/package/
+```
+
+In short:
+
+```text
+source application
+    ↓
+bcp build
+    ↓
+standalone build
+    ↓
+bcp package
+    ↓
+deployment package + production metadata
+```
+
+## Determinism
+
+The packaging layer writes sorted dependency metadata and a sorted file inventory. File hashes are calculated from the final package content.
+
+The underlying BCP build currently retains its build identifier/timestamp behavior, so `0.2.4` does not promise byte-for-byte identical packages across independent build invocations. The integrity manifest is intended for verification of a specific produced artifact, not as a claim of fully reproducible builds.
+
+## Validation
+
+Framework release validation includes Application Packaging unit and packed-package smoke coverage.
+
+Recommended project validation is:
+
+```bash
+bcp package
+cd .bcp-framework/package
+npm ci --omit=dev
+npm start
+```
+
+Then exercise representative routes, API endpoints and any optional runtime providers used by the application.