@chidchanun/bcp 0.2.5 → 0.2.7

package/docs/releases/0.2.6.md

@@ -0,0 +1,194 @@
+# BCP Framework 0.2.6 — Authorization & Security v2
+
+`0.2.6` expands the server authorization model and adds request-origin/CSRF protection primitives while preserving the existing Authentication Platform v2 and route model.
+
+> Release state: unreleased development target until RC validation, tagging and npm publication complete.
+
+## Authorization primitives
+
+`bcp/auth` now provides flat permission checks:
+
+```ts
+hasPermission()
+assertPermission()
+getUserPermissions()
+```
+
+Permission requirements accept one permission or multiple permissions with `any` / `all` matching.
+
+The default user field is:
+
+```text
+permissions
+```
+
+Applications can select another field, such as `scopes`.
+
+## Permission route guards
+
+Route guards can require permissions directly:
+
+```ts
+requirePermission()
+createPermissionGuard()
+```
+
+Unauthenticated behavior remains consistent with `requireAuth()`. Authenticated users that fail the permission check receive `403 Forbidden` by default or can be redirected explicitly.
+
+## Policy authorization
+
+Resource-aware application policies are now supported through:
+
+```ts
+defineAuthorizationPolicy()
+can()
+cannot()
+authorize()
+AuthorizationError
+```
+
+Policies receive a typed context containing:
+
+```ts
+{
+    user,
+    resource,
+    data,
+}
+```
+
+Policies may be synchronous or asynchronous. `authorize()` throws a `403`-classified `AuthorizationError` when access is denied.
+
+## Same-origin protection
+
+`bcp/server` adds request-origin validation for unsafe methods:
+
+```ts
+isSafeHttpMethod()
+isSameOriginRequest()
+requireSameOriginRequest()
+```
+
+The current request origin is always allowed. Additional origins may be listed explicitly.
+
+For unsafe methods, BCP checks `Origin` first and then `Referer`. Missing origin information is rejected by default unless the application explicitly enables `allowMissingOrigin`.
+
+Malformed, opaque, or unsupported origins are treated as denied instead of surfacing as server errors.
+
+## CSRF protection
+
+Signed CSRF tokens are available through:
+
+```ts
+createCsrfToken()
+destroyCsrfToken()
+verifyCsrfToken()
+verifyCsrfRequest()
+requireCsrfRequest()
+```
+
+The default request header is:
+
+```text
+X-BCP-CSRF
+```
+
+The default cookie is:
+
+```text
+bcp_csrf
+```
+
+CSRF cookies are HttpOnly, SameSite=Lax by default, Secure in production, and use a two-hour default lifetime.
+
+Token signing resolves secrets in this order:
+
+```text
+explicit secret
+BCP_CSRF_SECRET
+BCP_SESSION_SECRET
+```
+
+Secrets must contain at least 32 UTF-8 bytes.
+
+`requireCsrfRequest()` combines same-origin validation and token validation for unsafe methods. GET, HEAD and OPTIONS do not require CSRF tokens.
+
+## Security error classification
+
+`RequestSecurityError` reports status `403` and distinguishes:
+
+```text
+INVALID_ORIGIN
+INVALID_CSRF_TOKEN
+```
+
+This allows API routes/actions to map request-security failures to application-specific error responses while retaining a stable security classification.
+
+## Compatibility
+
+`0.2.6` does not intentionally remove existing public entrypoints or authentication behavior.
+
+Existing APIs remain available:
+
+```text
+auth()
+login()
+logout()
+logoutAll()
+rotateSession()
+requireAuth()
+requireGuest()
+requireRole()
+createAuthGuard()
+createGuestGuard()
+createRoleGuard()
+```
+
+Stateless JWT-cookie authentication remains supported. Revocable stores introduced in `0.2.5` are unchanged.
+
+## Testing and packaging
+
+The release adds unit coverage for:
+
+- permission `any` / `all` matching,
+- resource authorization policies,
+- permission route guards,
+- same-origin mutation validation,
+- signed CSRF tokens,
+- invalid CSRF token rejection,
+- cross-origin request rejection.
+
+Prepared npm package smoke coverage verifies that the `bcp/auth` and `bcp/server` public entrypoints include the Authorization & Security v2 APIs and implementation files.
+
+## Documentation
+
+New guide:
+
+```text
+docs/authorization-security.md
+```
+
+Updated documentation contracts include:
+
+```text
+docs/platform-manifest.json
+docs/docs-web-manifest.json
+docs/api-manifest.json
+docs/api-reference.md
+README.md
+```
+
+## Release validation
+
+Before publishing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+The final `v0.2.6` Git tag must point to the exact commit that passed the complete RC sequence.

package/docs/releases/0.2.7.md

@@ -0,0 +1,205 @@
+# BCP Framework 0.2.7 — Observability Platform v2
+
+> Release state: unreleased until RC validation, tagging and npm publication complete.
+
+BCP Framework `0.2.7` adds a dependency-free server observability platform while preserving the existing logging/runtime model.
+
+## Highlights
+
+### New `bcp/observability` entrypoint
+
+```ts
+import {
+    createHealthRegistry,
+    createMetricsRegistry,
+    createMetricsResponse,
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
+```
+
+The entrypoint is server-only and uses the same browser boundary as other server runtime APIs.
+
+### Metrics registry
+
+Applications can create process-local:
+
+- counters,
+- gauges,
+- histograms.
+
+Example:
+
+```ts
+const metrics =
+    createMetricsRegistry();
+
+const requests =
+    metrics.counter(
+        "app_requests_total",
+        {
+            labelNames: [
+                "method",
+            ],
+        }
+    );
+
+requests.inc(
+    1,
+    {
+        method: "GET",
+    }
+);
+```
+
+Metric definitions validate names, labels and number values. Re-registering the same metric with an incompatible type, label set or histogram buckets fails explicitly.
+
+### Prometheus text output
+
+```ts
+return createMetricsResponse(
+    metrics
+);
+```
+
+The generated response uses Prometheus-compatible text exposition metadata and `Cache-Control: no-store`.
+
+### HTTP request metrics middleware
+
+```ts
+const requestMetrics =
+    createRequestMetricsMiddleware(
+        metrics
+    );
+```
+
+Default metrics:
+
+```text
+bcp_http_requests_total
+bcp_http_request_duration_seconds
+```
+
+Default labels:
+
+```text
+method
+status
+```
+
+Raw URL paths are intentionally not included by default to avoid unbounded metric cardinality.
+
+### Health and readiness checks
+
+```ts
+const health =
+    createHealthRegistry();
+
+health.register(
+    "database",
+    async () => {
+        await db.query(
+            "SELECT 1"
+        );
+
+        return true;
+    }
+);
+```
+
+Health responses use:
+
+```text
+200 healthy
+503 unhealthy
+```
+
+Checks run independently and include duration metadata.
+
+### Health timeouts
+
+Each health check has a default timeout of 5 seconds and may configure its own timeout.
+
+Thrown or timed-out checks become unhealthy report items rather than rejecting the whole health operation.
+
+## Public APIs
+
+### Metrics
+
+```text
+createMetricsRegistry()
+createMetricsResponse()
+createRequestMetricsMiddleware()
+```
+
+Metric interfaces:
+
+```text
+CounterMetric
+GaugeMetric
+HistogramMetric
+MetricsRegistry
+MetricLabels
+MetricDefinitionOptions
+HistogramOptions
+RequestMetricsOptions
+```
+
+### Health
+
+```text
+createHealthRegistry()
+```
+
+Health interfaces:
+
+```text
+HealthRegistry
+HealthCheck
+HealthCheckResult
+HealthCheckOptions
+HealthReport
+HealthCheckReportItem
+```
+
+## Compatibility
+
+`0.2.7` has no intentional breaking changes from `0.2.6`.
+
+Existing applications do not need to create a metrics or health registry. The new platform is opt-in.
+
+Existing structured logging through `bcp/server` remains unchanged.
+
+## Operational notes
+
+Metrics are process-local. Multi-process and multi-container deployments should expose/scrape metrics for each instance or aggregate through deployment infrastructure.
+
+The built-in platform does not provide distributed aggregation or an OpenTelemetry exporter in this release.
+
+Health check error details may contain operational information. Applications should decide whether health endpoints are publicly accessible and avoid returning secrets from custom check details.
+
+Metrics endpoints should normally be protected by an internal network, reverse proxy or application authorization boundary when operational data is sensitive.
+
+## Validation coverage
+
+`0.2.7` adds unit and prepared-package checks for:
+
+- counter accumulation,
+- gauge set/increment/decrement,
+- histogram bucket/count output,
+- Prometheus response metadata,
+- incompatible metric registration,
+- request status/method timing metrics,
+- no raw path labels in default request metrics,
+- healthy/unhealthy reports,
+- HTTP 503 readiness behavior,
+- health check timeout handling,
+- `bcp/observability` npm export availability,
+- documentation/platform/API manifest parity.
+
+## Documentation
+
+See:
+
+- [Observability Platform v2](../observability.md)
+- [Logging](../development-logging.md)
+- [API Reference](../api-reference.md)

package/docs/security.md

@@ -1,6 +1,6 @@
 # Security
 
-BCP Framework applies a security gateway in both development and standalone production modes.
+BCP Framework applies a security gateway in both development and standalone production modes and exposes server-side mutation protection primitives through `bcp/server`.
 
 ## Default response headers
 
@@ -40,6 +40,58 @@ server: {
 
 Requests exceeding the limit are rejected by the outer gateway with HTTP 413 before reaching the API handler.
 
+## Same-origin mutation protection — 0.2.6+
+
+Cookie-authenticated unsafe requests can validate their browser origin:
+
+```ts
+import {
+    requireSameOriginRequest,
+} from "bcp/server";
+
+await requireSameOriginRequest();
+```
+
+BCP validates `Origin` first and falls back to `Referer`. GET, HEAD and OPTIONS are treated as safe methods. Unsafe methods without origin information are rejected by default.
+
+Additional trusted origins can be configured per check with `allowedOrigins`.
+
+Malformed, opaque or unsupported origins are denied instead of surfacing as server errors.
+
+## CSRF protection — 0.2.6+
+
+BCP also exposes signed CSRF tokens:
+
+```ts
+import {
+    createCsrfToken,
+    requireCsrfRequest,
+} from "bcp/server";
+
+const token =
+    await createCsrfToken();
+
+// Render the token through a trusted application response,
+// then submit it with the mutation.
+
+await requireCsrfRequest({
+    token: submittedToken,
+});
+```
+
+Default header/cookie:
+
+```text
+X-BCP-CSRF
+bcp_csrf
+```
+
+Token signing uses `BCP_CSRF_SECRET` when configured and otherwise falls back to `BCP_SESSION_SECRET`. Secrets must contain at least 32 UTF-8 bytes.
+
+`requireCsrfRequest()` combines same-origin validation and CSRF token verification for unsafe methods.
+
+Read more: [Authorization & Security v2](authorization-security.md).
+
 ## Static assets
 
 Public asset resolution decodes the URL, rejects null bytes, resolves the candidate beneath `public/`, resolves filesystem symlinks and verifies the final real path remains inside the public directory. This prevents path and symlink traversal from escaping the public root.
@@ -55,3 +107,5 @@ Security config values reject carriage return, line feed and null bytes to preve
 ## Deployment note
 
 The security gateway is the outer production layer, so security headers and body limits also apply to response-cache hits, middleware responses, static assets and error responses.
+
+Authorization, same-origin checks and CSRF validation remain request-handler/guard responsibilities and should be enforced wherever a mutation or protected operation occurs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -62,6 +62,11 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/auth.ts"
     },
+    "./observability": {
+      "types": "./packages/client/src/observability.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/observability.ts"
+    },
     "./server": {
       "types": "./packages/client/src/server.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -28,6 +28,7 @@ const SERVER_ONLY_IMPORTS =
         "bcp/server-only",
         "bcp/database",
         "bcp/auth",
+        "bcp/observability",
     ]);
 
 export function validateClientBoundaries(

package/packages/client/src/auth.ts

@@ -24,13 +24,32 @@ export {
     type MemoryAuthSessionStore,
 } from "../../server/src/auth-session-store.js";
 
+export {
+    assertPermission,
+    authorize,
+    can,
+    cannot,
+    defineAuthorizationPolicy,
+    getUserPermissions,
+    hasPermission,
+    AuthorizationError,
+
+    type AuthorizationContext,
+    type AuthorizationMatch,
+    type AuthorizationPolicy,
+    type PermissionCheckOptions,
+    type PermissionRequirement,
+} from "../../server/src/authorization.js";
+
 export {
     createAuthGuard,
     createGuestGuard,
+    createPermissionGuard,
     createRoleGuard,
     getGuardAuth,
     requireAuth,
     requireGuest,
+    requirePermission,
     requireRole,
 
     type AuthGuardData,
@@ -40,6 +59,7 @@ export {
     type GuestGuardResult,
     type RequireAuthOptions,
     type RequireGuestOptions,
+    type RequirePermissionOptions,
     type RequireRoleOptions,
     type RequiredRole,
 } from "../../server/src/auth-guard.js";

package/packages/client/src/observability.ts

@@ -0,0 +1,22 @@
+export {
+    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 "../../server/src/observability.js";

package/packages/client/src/server.ts

@@ -15,6 +15,22 @@ export {
     type ResponseCookieOptions,
 } from "../../server/src/request-context.js";
 
+export {
+    createCsrfToken,
+    destroyCsrfToken,
+    isSafeHttpMethod,
+    isSameOriginRequest,
+    requireCsrfRequest,
+    requireSameOriginRequest,
+    verifyCsrfRequest,
+    verifyCsrfToken,
+    RequestSecurityError,
+
+    type CsrfTokenOptions,
+    type SameOriginOptions,
+    type VerifyCsrfRequestOptions,
+} from "../../server/src/request-security.js";
+
 export {
     attachRequestId,
     createLogger,