@chidchanun/bcp 0.2.5 → 0.2.7

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, observability, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.5 — Authentication Platform v2`
+> **Development target:** `0.2.7 — Observability Platform v2`
 >
-> `0.2.5` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.7` 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, `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.
+`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, `0.2.6` added Authorization & Security v2, and `0.2.7` adds dependency-free metrics, Prometheus exposition, request metrics and health/readiness checks without intentionally changing the existing application model.
 
 Machine-readable platform contracts:
 
@@ -31,13 +31,14 @@ 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()`, `requireGuest()`, `requireRole()` |
 | 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 |
+| Observability | Structured logs, counters/gauges/histograms, Prometheus output, request metrics and health/readiness checks |
 | Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
 | Database | Provider-neutral MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
-| Logging | Structured logger, request logger and request IDs |
 | Uploads | Buffered multipart helpers and production multipart streaming |
 | Storage | Local + S3-compatible storage, streaming, list/copy/move, metadata, bulk delete and signed URLs |
 | Caching | Response cache and revalidation primitives |
@@ -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,7 +172,7 @@ 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
@@ -200,8 +197,6 @@ Output:
 └─ README.md
 ```
 
-The package layer creates production-only dependency metadata, deployment/environment manifests, SHA-256 file integrity metadata and a Node 24 Alpine Docker starter.
-
 Read more:
 
 - [Application Packaging](docs/application-packaging.md)
@@ -209,7 +204,7 @@ Read more:
 
 ## Authentication Platform v2 — 0.2.5
 
-The existing stateless JWT-cookie mode remains available:
+Stateless signed JWT-cookie authentication remains supported:
 
 ```ts
 import {
@@ -232,49 +227,169 @@ const sessionStore =
 
 export const appAuth =
     createAuth({
-        store:
-            sessionStore,
-        idleTimeout:
-            60 * 30,
+        store: sessionStore,
+        idleTimeout: 60 * 30,
     });
 ```
 
-With a store configured, authentication requires both a valid signed JWT cookie and an active `sid` record.
+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:
+
+- [Authentication](docs/authentication.md)
+- [Auth Session Stores](docs/auth-session-store.md)
+- [Auth Route Guards](docs/auth-route-guards.md)
 
-New lifecycle APIs:
+## Authorization & Security v2 — 0.2.6
+
+Use flat permissions directly from `bcp/auth`:
 
 ```ts
-await appAuth.logout();
-await appAuth.logoutAll();
-await appAuth.revokeSession(sid);
-await appAuth.revokeUserSessions(userId);
-await appAuth.rotateSession();
-```
+import {
+    hasPermission,
+    requirePermission,
+} from "bcp/auth";
 
-`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.
+hasPermission(
+    user,
+    "users.read"
+);
+
+await requirePermission(
+    [
+        "users.read",
+        "users.write",
+    ],
+    {
+        match: "all",
+    }
+);
+```
 
-Guest-only login/register routes can use:
+Resource-aware policies:
 
 ```ts
 import {
-    createGuestGuard,
+    authorize,
+    defineAuthorizationPolicy,
 } from "bcp/auth";
 
-export const guard =
-    createGuestGuard({
-        redirectTo:
-            "/dashboard",
-    });
+const updateProject =
+    defineAuthorizationPolicy(
+        ({
+            user,
+            resource,
+        }) =>
+            resource.ownerId ===
+            user.id
+    );
+
+await authorize(
+    updateProject,
+    {
+        user,
+        resource: project,
+    }
+);
 ```
 
-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.
+Request-security helpers are exposed from `bcp/server`:
 
-Read more:
+```ts
+import {
+    createCsrfToken,
+    requireCsrfRequest,
+    requireSameOriginRequest,
+} from "bcp/server";
+```
 
-- [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)
+Read more: [Authorization & Security v2](docs/authorization-security.md)
+
+## Observability Platform v2 — 0.2.7
+
+Create one application metrics registry:
+
+```ts
+import {
+    createMetricsRegistry,
+} from "bcp/observability";
+
+export const metrics =
+    createMetricsRegistry();
+```
+
+Supported metric types:
+
+```text
+counter
+gauge
+histogram
+```
+
+Expose Prometheus-compatible text:
+
+```ts
+import {
+    createMetricsResponse,
+} from "bcp/observability";
+
+export function GET() {
+    return createMetricsResponse(
+        metrics
+    );
+}
+```
+
+Instrument HTTP requests through Middleware System v2:
+
+```ts
+import {
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
+
+export const requestMetrics =
+    createRequestMetricsMiddleware(
+        metrics
+    );
+```
+
+Default request metrics use only bounded labels:
+
+```text
+bcp_http_requests_total{method,status}
+bcp_http_request_duration_seconds{method,status}
+```
+
+Raw paths are not attached by default.
+
+Health/readiness registry:
+
+```ts
+import {
+    createHealthRegistry,
+} from "bcp/observability";
+
+export const health =
+    createHealthRegistry();
+
+health.register(
+    "database",
+    async () => {
+        await db.query("SELECT 1");
+        return true;
+    }
+);
+```
+
+Use:
+
+```ts
+return health.response();
+```
+
+Health responses return `200` when every check passes and `503` when any registered dependency is unhealthy or times out.
+
+Read more: [Observability Platform v2](docs/observability.md)
 
 ## Public entrypoints
 
@@ -289,6 +404,7 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
@@ -337,40 +453,23 @@ 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
   ↓
 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
+Operational side channels:
+structured logs + metrics + health/readiness
 ```
 
 ## Production build
@@ -388,7 +487,7 @@ Deployment package:
 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
 
@@ -402,8 +501,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.
-
 ## Release validation
 
 Framework releases must pass:
@@ -418,7 +515,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`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.
+`0.2.7` adds Observability Platform v2 unit and prepared-package smoke checks covering metrics, Prometheus exposition, request timing, cardinality-safe default labels, health/readiness responses and timeout handling.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -438,12 +535,14 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `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.7` | Observability Platform v2 |
 
 ## Roadmap
 
-`0.2.5 — Authentication Platform v2` establishes optional revocable server-side auth state while preserving the original stateless JWT-cookie path.
+`0.2.7 — Observability Platform v2` establishes process-level metrics and health/readiness contracts on top of the existing structured logging and Middleware System v2 runtime.
 
-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.
+Future `0.2.x` work can add distributed tracing or exporter integrations without changing the application metrics/health contract introduced here. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 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.5 — Authentication Platform v2`
+> **Documentation target:** BCP Framework `0.2.7 — Observability Platform v2`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -51,62 +51,50 @@ Framework source and tests remain authoritative for runtime behavior.
 | `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.7` | Observability Platform v2 |
 
-## 0.2.5 — Authentication Platform v2
+## 0.2.7 — Observability 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.
+`0.2.7` adds a server-only observability layer without adding third-party runtime dependencies.
 
 New/updated documentation sources:
 
 | Source | Purpose |
 | --- | --- |
-| `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 |
+| `observability.md` | Metrics registry, Prometheus output, request metrics and health/readiness checks |
+| `api-reference.md` | Public `bcp/observability` exports |
+| `platform-manifest.json` | Observability capability flags and new public entrypoint |
+| `api-manifest.json` | `bcp/observability` guide ownership |
+| `docs-web-manifest.json` | Observability navigation and `0.2.7` release route |
+| `releases/0.2.7.md` | Observability Platform v2 release notes |
 
-Primary public entrypoint:
+Primary APIs:
 
 ```ts
 import {
-    auth,
-    createAuth,
-    createMemoryAuthSessionStore,
-    login,
-    logout,
-    logoutAll,
-    requireAuth,
-    requireGuest,
-    requireRole,
-} from "bcp/auth";
+    createHealthRegistry,
+    createMetricsRegistry,
+    createMetricsResponse,
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
 ```
 
-## Authentication security model
-
-Default mode:
+Runtime model:
 
 ```text
-signed HttpOnly JWT cookie
-      ↓
-signature + expiry validation
-      ↓
-authenticated session
+structured logs
+    +
+process-local metrics
+    +
+Prometheus exposition
+    +
+health/readiness checks
 ```
 
-Optional revocable mode:
-
-```text
-signed HttpOnly JWT cookie
-      +
-server-side sid store
-      ↓
-revocable authenticated session
-```
+The request metrics middleware intentionally uses bounded `method` and `status` labels by default rather than raw paths.
 
-The built-in memory store is intended for development/tests. Multi-process production systems should implement `AuthSessionStore` using shared durable storage.
+The built-in metrics registry is process-local; distributed aggregation remains deployment infrastructure or future exporter work.
 
 ## Update rule
 
@@ -130,7 +118,7 @@ Current sections:
 ```text
 Getting Started
 Routing & Data
-Authentication
+Authentication & Authorization
 Database
 Runtime & Infrastructure
 Storage & Uploads
@@ -145,12 +133,13 @@ Important current routes:
 | Website route | Markdown source |
 | --- | --- |
 | `/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/observability` | `observability.md` |
+| `/docs/development-logging` | `development-logging.md` |
 | `/docs/application-packaging` | `application-packaging.md` |
 | `/docs/database` | `database.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.5` | `releases/0.2.5.md` |
+| `/releases/0.2.7` | `releases/0.2.7.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -190,6 +179,7 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
@@ -229,7 +219,7 @@ synchronize CMS/search/navigation
 
 ## Release validation
 
-Before publishing `0.2.5`:
+Before publishing `0.2.7`:
 
 ```bash
 npm run typecheck
@@ -240,16 +230,16 @@ npm run test:e2e
 npm run rc:check
 ```
 
-Authentication Platform v2 validation covers:
+Observability 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,
+- counter/gauge/histogram behavior,
+- Prometheus exposition,
+- metric definition validation,
+- request count and duration middleware,
+- cardinality-safe default request labels,
+- health/readiness response semantics,
+- health check timeout handling,
+- public `bcp/observability` exports,
 - prepared npm package contents,
 - docs/platform/API version parity.
 

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -85,22 +85,35 @@
       "source": "packages/client/src/auth.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-auth",
-      "summary": "Authentication Platform v2 with JWT cookies, optional revocable session stores, idle timeout, logout-all and auth/guest/role route guards.",
+      "summary": "Authentication Platform v2 plus permission checks, authorization policies and auth/guest/role/permission route guards.",
       "guides": [
         "/docs/authentication",
         "/docs/auth-session-store",
         "/docs/auth-route-guards",
+        "/docs/authorization-security",
         "/docs/session-auth"
       ]
     },
+    {
+      "package": "bcp/observability",
+      "source": "packages/client/src/observability.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-observability",
+      "summary": "In-process metrics, Prometheus exposition, request metrics middleware and health/readiness checks.",
+      "guides": [
+        "/docs/observability",
+        "/docs/development-logging"
+      ]
+    },
     {
       "package": "bcp/server",
       "source": "packages/client/src/server.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-server",
-      "summary": "Request context, cookies, logging, production hardening, upload, storage, response and session APIs.",
+      "summary": "Request context, cookies, CSRF/same-origin protection, logging, production hardening, upload, storage, response and session APIs.",
       "guides": [
         "/docs/server-request-apis",
+        "/docs/authorization-security",
         "/docs/file-upload",
         "/docs/storage",
         "/docs/storage-ecosystem",