@chidchanun/bcp 0.2.3 → 0.2.5

package/README.md

@@ -2,13 +2,13 @@
 
 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.
 
-> **Development target:** `0.2.3 — Database Platform v2`
+> **Development target:** `0.2.5 — Authentication Platform v2`
 >
-> `0.2.3` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.5` 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, and `0.2.3` adds a provider-neutral SQL database platform with MySQL, PostgreSQL and SQLite support without intentionally removing public application entrypoints.
+`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, and `0.2.5` adds optional revocable authentication sessions and guest-aware route guards without intentionally removing the existing stateless JWT-cookie model.
 
 Machine-readable platform contracts:
 
@@ -31,8 +31,8 @@ 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 |
+| Authorization | `guard.ts`, `requireAuth()`, `requireGuest()`, `requireRole()` |
+| Authentication | JWT cookie sessions, optional server-side session stores, revocation, logout-all, idle timeout and rotation |
 | Middleware | Middleware System v2 with onion execution |
 | Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
@@ -43,7 +43,7 @@ docs/api-manifest.json
 | Caching | Response cache and revalidation primitives |
 | Configuration | Typed `bcp.config.*`, optional `bcp.environment.*`, startup diagnostics and `bcp config check` |
 | Developer tools | Generators, Doctor/Inspect v2, updater, route inspection and project metadata |
-| Production | Standalone Node.js build, hardening gateway, graceful shutdown, trusted proxy controls and HTTP timeouts |
+| Production | Standalone Node.js build, application packaging, production dependency pruning, deployment manifests, Docker starter, hardening and graceful shutdown |
 | Documentation | Manifest-driven docs navigation, platform metadata and public API reference |
 
 ## Requirements
@@ -80,7 +80,7 @@ Generated projects normally keep one framework dependency key:
 
 Do not install both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application.
 
-## Configuration
+## Configuration & environment
 
 Framework configuration stays in one of:
 
@@ -91,29 +91,16 @@ bcp.config.js
 bcp.config.mjs
 ```
 
-Example:
+Application environment validation can be declared in:
 
-```ts
-import {
-    defineConfig,
-} from "bcp/config";
-
-export default defineConfig({
-    server: {
-        port: 3000,
-        hostname: "0.0.0.0",
-    },
-    build: {
-        minify: true,
-        sourceMaps: false,
-    },
-    security: {
-        poweredByHeader: false,
-    },
-});
+```text
+bcp.environment.ts
+bcp.environment.mts
+bcp.environment.js
+bcp.environment.mjs
 ```
 
-Configuration precedence remains:
+Configuration precedence is:
 
 ```text
 CLI override
@@ -125,157 +112,169 @@ bcp.config.*
 framework defaults
 ```
 
-Read more: [Configuration](docs/configuration.md)
+Validate configuration and declared environment values with:
 
-## Environment Validation — 0.2.2
+```bash
+bcp config check
+bcp config check --json
+```
 
-Application-specific variables can be declared in an optional environment schema:
+Variables beginning with `BCP_PUBLIC_` may be embedded in browser output. Never expose application secrets through public-prefixed variables.
 
-```text
-bcp.environment.ts
-```
+Read more:
 
-Example:
+- [Configuration](docs/configuration.md)
+- [Environment Validation](docs/environment-validation.md)
+
+## Database Platform v2 — 0.2.3
+
+Application code uses one server-only database entrypoint across supported SQL providers:
 
 ```ts
 import {
-    defineEnvironment,
-} from "bcp/config";
-
-export default defineEnvironment({
-    DB_HOST: {
-        type: "string",
-        required: true,
-    },
-
-    DB_PORT: {
-        type: "number",
-        default: 3306,
-        min: 1,
-        max: 65535,
-    },
-
-    SESSION_SECRET: {
-        type: "string",
-        required: true,
-        secret: true,
-        minLength: 32,
-    },
-
-    FEATURE_ENABLED: {
-        type: "boolean",
-        default: false,
-    },
-
-    BCP_PUBLIC_API_URL: {
-        type: "url",
-        required: true,
-    },
-});
+    db,
+    createDatabase,
+} from "bcp/database";
 ```
 
-Supported types:
+Built-in SQL providers:
 
 ```text
-string
-number
-boolean
-url
+mysql
+postgresql
+sqlite
 ```
 
-Validate the current project:
+Lifecycle control:
 
-```bash
-bcp config check
-```
+```ts
+await db.connect();
 
-JSON diagnostics:
+// application work
 
-```bash
-bcp config check --json
+await db.disconnect();
 ```
 
-On Windows, where Microsoft SQL Server may provide another `bcp.exe`, prefer:
+`db.close()` remains available for backward-compatible shutdown handling.
 
-```powershell
-npm exec -- bcp-framework config check
-npm exec -- bcp-framework config check --json
+Migration CLI:
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
 ```
 
-`bcp dev` and `bcp build` also validate `bcp.environment.*` before startup/build. Invalid required values fail early.
+BCP makes framework migration bookkeeping provider-aware. Application migration SQL itself is not automatically translated between SQL dialects.
 
-The development supervisor watches:
+Read more:
 
-```text
-.env*
-bcp.config.*
-bcp.environment.*
-```
+- [Database](docs/database.md)
+- [Database Migrations](docs/database-migrations.md)
 
-and restarts the worker when one of those files changes.
+## Application Packaging — 0.2.4
 
-### Secret safety
+Create a fresh production build and convert it into a deployment-oriented package:
 
-Variables beginning with `BCP_PUBLIC_` can be embedded into browser bundles.
+```bash
+bcp package
+```
 
-A variable marked:
+Output:
 
-```ts
-secret: true
+```text
+.bcp-framework/package/
+├─ client/
+├─ server/
+│  └─ server.mjs
+├─ public/                 # when present
+├─ 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
 ```
 
-must not use `BCP_PUBLIC_`. BCP reports this as a configuration error.
+The package layer creates production-only dependency metadata, deployment/environment manifests, SHA-256 file integrity metadata and a Node 24 Alpine Docker starter.
 
-`secret: true` is tooling metadata; it does not encrypt environment values.
+Read more:
 
-Read more: [Environment Validation](docs/environment-validation.md)
+- [Application Packaging](docs/application-packaging.md)
+- [Deployment](docs/deployment.md)
 
-## Database Platform v2 — 0.2.3
+## Authentication Platform v2 — 0.2.5
 
-Application code uses the same server-only entrypoint across supported SQL providers:
+The existing stateless JWT-cookie mode remains available:
 
 ```ts
 import {
-    db,
-    createDatabase,
-} from "bcp/database";
+    auth,
+    login,
+    logout,
+} from "bcp/auth";
 ```
 
-Built-in providers:
+Applications that need centralized revocation can add a server-side session store:
 
-```text
-mysql
-postgresql
-sqlite
+```ts
+import {
+    createAuth,
+    createMemoryAuthSessionStore,
+} from "bcp/auth";
+
+const sessionStore =
+    createMemoryAuthSessionStore();
+
+export const appAuth =
+    createAuth({
+        store:
+            sessionStore,
+        idleTimeout:
+            60 * 30,
+    });
 ```
 
-Connections remain lazy, while explicit lifecycle control is available when needed:
+With a store configured, authentication requires both a valid signed JWT cookie and an active `sid` record.
 
-```ts
-await db.connect();
+New lifecycle APIs:
 
-// application work
-
-await db.disconnect();
+```ts
+await appAuth.logout();
+await appAuth.logoutAll();
+await appAuth.revokeSession(sid);
+await appAuth.revokeUserSessions(userId);
+await appAuth.rotateSession();
 ```
 
-`db.close()` remains available for backward-compatible shutdown handling.
+`idleTimeout` is enforced only when a server-side store is configured. BCP rejects the option in stateless-only mode rather than silently pretending to enforce inactivity expiration.
 
-Database migrations use the same CLI across providers:
+Guest-only login/register routes can use:
 
-```bash
-bcp db create create_users
-bcp db migrate
-bcp db status
-bcp db rollback
+```ts
+import {
+    createGuestGuard,
+} from "bcp/auth";
+
+export const guard =
+    createGuestGuard({
+        redirectTo:
+            "/dashboard",
+    });
 ```
 
-BCP makes its internal migration bookkeeping provider-aware. Application SQL itself is not automatically translated between SQL dialects.
+The built-in memory session store is intended for development/tests and process-local prototypes. Production applications running multiple processes or containers should implement `AuthSessionStore` with shared durable storage such as Redis or a database.
 
 Read more:
 
-- [Database](docs/database.md)
-- [Database Migrations](docs/database-migrations.md)
+- [Authentication](docs/authentication.md)
+- [Auth Session Stores](docs/auth-session-store.md)
+- [Auth Route Guards](docs/auth-route-guards.md)
+- [JWT Sessions](docs/session-auth.md)
 
 ## Public entrypoints
 
@@ -310,6 +309,7 @@ Core commands:
 ```bash
 bcp dev
 bcp build
+bcp package
 bcp start
 bcp routes
 bcp update
@@ -375,32 +375,20 @@ app/
 
 ## Production build
 
+Raw standalone build:
+
 ```bash
 npm run build
 npm run start
 ```
 
-Standalone output:
-
-```text
-.bcp-framework/build/
-├─ client/
-├─ public/
-└─ server/
-   └─ server.mjs
-```
-
-The current production target remains:
+Deployment package:
 
-```text
-standalone-node
+```bash
+bcp package
 ```
 
-Native `.exe`, desktop and mobile compilation remain later roadmap work.
-
-Production hardening includes configurable request/header/keep-alive/shutdown timeouts, trusted-proxy handling and graceful `SIGTERM` / `SIGINT` shutdown.
-
-Read more: [Production Hardening](docs/production-hardening.md)
+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.
 
 ## Documentation Platform
 
@@ -416,12 +404,6 @@ 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)
-- [Environment Validation](docs/environment-validation.md)
-
 ## Release validation
 
 Framework releases must pass:
@@ -436,7 +418,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.3` adds Database Platform v2 unit/package checks covering the adapter contract, MySQL/PostgreSQL/SQLite provider resolution, explicit connection lifecycle, failed-initialization retry behavior and provider-specific migration bookkeeping.
+`0.2.5` adds Authentication Platform v2 unit and prepared-package smoke checks covering session-store registration, revocation, logout-all, idle timeout, rotation and guest guards.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -454,12 +436,14 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `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 |
 
 ## Roadmap
 
-`0.2.3 — Database Platform v2` completes the planned database adapter contract, PostgreSQL support, SQLite support, connection lifecycle improvements and migration consistency across the built-in SQL providers.
+`0.2.5 — Authentication Platform v2` establishes optional revocable server-side auth state while preserving the original stateless JWT-cookie path.
 
-The next planned `0.2.x` focus is application packaging. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+A later security/authorization milestone can build on this session contract for broader permission and security policy features. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License