@chidchanun/bcp 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 All notable framework changes are tracked here before release.
 
+## 0.1.8 - JWT cookie sessions and auth preset
+
+### Authentication
+
+- Added `createSessionToken()` and `verifySessionToken()` to `bcp/server` for HS256 JWT session tokens.
+- Added `createSession()` to sign a token and store it in an HttpOnly cookie with secure production defaults.
+- Added `getSession()` to read and verify the active session cookie and return typed claims or `null` for invalid, expired or tampered tokens.
+- Added `destroySession()` to expire the configured session cookie.
+- Session tokens use `BCP_SESSION_SECRET` by default and reject secrets shorter than 32 bytes.
+- Token verification validates HS256 signatures with constant-time comparison plus expiration, optional issuer and optional audience checks.
+- JWT cookie defaults are `bcp_session`, 12-hour lifetime, `HttpOnly`, `SameSite=Lax`, `Path=/`, and `Secure` when `NODE_ENV=production`.
+- Added low-level and high-level session option types through the existing server-only `bcp/server` entrypoint.
+
+### create-bcp-app
+
+- Added interactive Authentication selection with `None` and `JWT Cookie` presets.
+- Added the non-interactive `--auth <preset>` option with `none` and `jwt-cookie` values.
+- JWT Cookie projects generate `lib/auth.ts` plus `/api/auth/login`, `/api/auth/logout` and `/api/auth/me` route handlers.
+- Generated auth projects add `BCP_SESSION_SECRET=` to `.env.example`.
+- Generated `authenticateCredentials(email, password)` returns `null` until the application connects its own database lookup and password-hash verification, keeping the starter secure by default.
+- MySQL projects now generate a reusable `db` pool configured through `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` and `DB_NAME`, with development pool reuse through `globalThis`.
+
+### Reliability
+
+- Added unit coverage for token round-trips, signature tampering, wrong secrets, issuer/audience mismatches, expiration, missing/short secrets and cookie lifecycle behavior.
+- Added development integration coverage for login-style session creation, authenticated reads and logout cookie expiration.
+- Added standalone production E2E coverage for the same JWT cookie session lifecycle after production bundling.
+- Added create-app regression coverage for JWT Cookie scaffolding, secure credential-verification defaults and authentication-disabled projects.
+- Added a basic application session API fixture and package-smoke checks for the session runtime and public helper surface.
+
+## 0.1.7 - Server request context and cookies
+
+### Server APIs
+
+- Added the server-only `bcp/server` entrypoint for request-scoped helpers.
+- Added `headers()` for reading an isolated copy of the active request headers.
+- Added `requestUrl()` for reading an isolated copy of the active request URL, including pathname and search parameters.
+- Added `requestMethod()` for reading the normalized HTTP method of the active request.
+- Added `requestId()` with incoming `X-Request-Id` reuse and stable per-request UUID generation when no valid ID is supplied.
+- Added `bearerToken()` for extracting Bearer credentials without imposing a JWT implementation.
+- Added `clientIp()` with direct socket addresses by default and explicit `trustProxy` support for `Forwarded`, `X-Forwarded-For` and `X-Real-IP`.
+- Forwarded client IP values are accepted only when they validate as IPv4 or IPv6 addresses, and IPv4-mapped IPv6 addresses are normalized.
+- Added `json()` as a typed convenience wrapper around the standard Web `Response.json()` API.
+- Added `redirect()` with relative URL resolution, HTTP/HTTPS validation and support for 301, 302, 303, 307 and 308 responses; the default redirect status is 307.
+- Added `cookies()` with request-cookie `get`, `getAll` and `has` helpers.
+- Added response-cookie `set` and `delete` support with domain, path, expires, max-age, HttpOnly, Secure and SameSite attributes.
+- Response cookies created through `cookies()` are merged with cookies already present on the returned `Response` and remain separate `Set-Cookie` header values, including redirect responses.
+- Request state is isolated with Node.js `AsyncLocalStorage` so concurrent requests do not share URL, method, request ID, header or cookie data.
+- `bcp/server` is blocked from page/client graphs by the application boundary validator and is currently intended for API route handlers.
+
+### Reliability
+
+- Added request-context unit tests for URL/header access, cookie parsing, concurrent request isolation, response cookie serialization, deletion and validation.
+- Added auth-request unit coverage for HTTP methods, incoming/generated request IDs, Bearer parsing, direct IP addresses, trusted proxy precedence and invalid forwarded-IP rejection.
+- Added response-helper unit coverage for JSON responses, relative and absolute redirects, redirect status validation and protocol validation.
+- Added client-boundary coverage for the new `bcp/server` entrypoint.
+- Added development integration coverage for request URL/header helpers, auth request helpers, direct/proxy client IPs, JSON responses, redirects and response cookies through the full dev gateway stack.
+- Added standalone production E2E coverage to verify `bcp/server` resolution, auth request helpers, direct/proxy client IPs, helper responses and multiple `Set-Cookie` values after production bundling.
+- Package smoke checks verify that the `bcp/server` entrypoint and request-context runtime are included in publish artifacts.
+
 ## 0.1.6 - Critical CSS and release visibility
 
 ### Performance
@@ -36,7 +96,7 @@ All notable framework changes are tracked here before release.
 
 - Tailwind projects now install the official `@tailwindcss/cli` package and compile CSS before starting BCP.
 - Development runs Tailwind in watch mode alongside `bcp dev` using `concurrently`.
-- Production builds minify Tailwind CSS before `bcp build`.
+- Production builds minify Tailwind CSS before the BCP production build.
 - Generated Tailwind CSS is served through a framework API stylesheet endpoint with cache disabled during development.
 - Root layout automatically links the generated stylesheet.
 - Tailwind source detection is explicitly rooted at the generated project so utility classes in `app/` and other project files are discovered.

package/README.md

@@ -2,7 +2,7 @@
 
 BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, security defaults and standalone production builds.
 
-> Current development version: `0.1.6`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current development version: `0.1.8`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -121,6 +121,188 @@ export function GET() {
 
 Supported methods include GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS. HEAD falls back to GET when no explicit HEAD handler exists, and OPTIONS is generated automatically when appropriate.
 
+## Server request APIs
+
+BCP 0.1.7 adds request-scoped server helpers through `bcp/server`. In the current 0.1.x client pipeline these helpers are intended for API routes and are rejected from page/client module graphs.
+
+```ts
+import {
+    bearerToken,
+    clientIp,
+    cookies,
+    json,
+    requestId,
+    requestMethod,
+    requestUrl,
+} from "bcp/server";
+
+export async function GET() {
+    const url =
+        await requestUrl();
+
+    return json({
+        pathname:
+            url.pathname,
+        method:
+            await requestMethod(),
+        requestId:
+            await requestId(),
+        bearerToken:
+            await bearerToken(),
+        clientIp:
+            await clientIp(),
+        session:
+            (
+                await cookies()
+            ).get(
+                "session"
+            )?.value ?? null,
+    });
+}
+```
+
+`requestId()` reuses a valid incoming `X-Request-Id` or generates one stable UUID for the request. `bearerToken()` extracts a Bearer credential without decoding or verifying it. `clientIp()` uses the direct socket address by default; applications behind a trusted reverse proxy can explicitly use `clientIp({ trustProxy: true })` to read validated `Forwarded`, `X-Forwarded-For` or `X-Real-IP` values.
+
+Response cookies and redirects can be composed for login-style flows:
+
+```ts
+import {
+    cookies,
+    redirect,
+} from "bcp/server";
+
+export async function POST() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "session",
+        "session-token",
+        {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: "/",
+            maxAge: 60 * 60 * 12,
+        }
+    );
+
+    return redirect(
+        "/dashboard",
+        303
+    );
+}
+```
+
+`redirect()` defaults to status `307`; supported statuses are `301`, `302`, `303`, `307` and `308`. Use `cookieStore.delete("session")` to expire a cookie. See [Server Request APIs](docs/server-request-apis.md) for proxy trust, URL handling, response helpers, request isolation, cookie options and boundary details.
+
+## JWT cookie sessions
+
+BCP 0.1.8 adds HS256 JWT cookie sessions directly to `bcp/server`. Configure a server-only secret of at least 32 bytes:
+
+```env
+BCP_SESSION_SECRET=replace-this-with-a-long-random-secret-at-least-32-bytes
+```
+
+Login-style APIs can create an HttpOnly session cookie without manually signing or serializing the JWT:
+
+```ts
+import {
+    createSession,
+    json,
+} from "bcp/server";
+
+export async function POST() {
+    await createSession(
+        {
+            userId: 42,
+            email: "user@example.com",
+            role: "admin",
+        },
+        {
+            issuer: "my-app",
+            audience: "my-app-users",
+        }
+    );
+
+    return json({
+        success: true,
+    });
+}
+```
+
+Protected API routes can verify and read the session:
+
+```ts
+import {
+    getSession,
+    json,
+} from "bcp/server";
+
+export async function GET() {
+    const session =
+        await getSession<{
+            userId: number;
+            email: string;
+            role: string;
+        }>({
+            issuer: "my-app",
+            audience: "my-app-users",
+        });
+
+    if (!session) {
+        return json(
+            {
+                error: "Unauthorized",
+            },
+            {
+                status: 401,
+            }
+        );
+    }
+
+    return json({
+        userId:
+            session.userId,
+        email:
+            session.email,
+        role:
+            session.role,
+    });
+}
+```
+
+Use `destroySession()` to expire the cookie. Low-level `createSessionToken()` and `verifySessionToken()` helpers are also available when an application needs to manage token storage itself. JWT payloads are signed, not encrypted, so sensitive secrets must not be stored inside them. See [JWT Cookie Sessions](docs/session-auth.md) for options and the security model.
+
+## create-bcp-app auth preset
+
+BCP 0.1.8 can scaffold the JWT cookie foundation automatically:
+
+```bash
+npx create-bcp-app my-app --database mysql --auth jwt-cookie
+```
+
+Interactive setup offers `None` and `JWT Cookie`. Selecting JWT Cookie creates:
+
+```text
+lib/auth.ts
+app/api/auth/login/route.ts
+app/api/auth/logout/route.ts
+app/api/auth/me/route.ts
+```
+
+and adds:
+
+```env
+BCP_SESSION_SECRET=
+```
+
+to `.env.example`.
+
+The generated `authenticateCredentials(email, password)` returns `null` by default. Applications must connect it to their own database lookup and password-hash verification before login can succeed. This is intentional so a newly generated project does not trust user identity supplied directly by the browser.
+
+The generated MySQL preset uses a reusable `db` pool and separate `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` and `DB_NAME` settings.
+
 ## Metadata
 
 ```ts
@@ -262,6 +444,8 @@ No real npm publish command is run automatically by the repository.
 
 - [Getting Started](docs/getting-started.md)
 - [Application Modules](docs/application-modules.md)
+- [Server Request APIs](docs/server-request-apis.md)
+- [JWT Cookie Sessions](docs/session-auth.md)
 - [Routing](docs/routing.md)
 - [Configuration](docs/configuration.md)
 - [Caching](docs/caching.md)

package/docs/server-request-apis.md

@@ -0,0 +1,404 @@
+# Server Request APIs
+
+BCP Framework 0.1.7 introduces request-scoped server helpers through `bcp/server`.
+
+These APIs are server-only and are intended for API route handlers in the current 0.1.x client pipeline. Importing `bcp/server` from a page, layout, client island or another module reachable from the browser bundle is rejected by the client-boundary validator.
+
+## Headers
+
+Use `headers()` to read a copy of the current request headers:
+
+```ts
+import {
+    headers,
+} from "bcp/server";
+
+export async function GET() {
+    const requestHeaders =
+        await headers();
+
+    return Response.json({
+        userAgent:
+            requestHeaders.get(
+                "user-agent"
+            ),
+        requestId:
+            requestHeaders.get(
+                "x-request-id"
+            ),
+    });
+}
+```
+
+The returned `Headers` object is a copy. Mutating it does not modify the original incoming request.
+
+## Request URL
+
+Use `requestUrl()` to read the complete URL of the current request, including pathname and search parameters:
+
+```ts
+import {
+    json,
+    requestUrl,
+} from "bcp/server";
+
+export async function GET() {
+    const url =
+        await requestUrl();
+
+    return json({
+        pathname:
+            url.pathname,
+        query:
+            url.searchParams.get(
+                "query"
+            ),
+    });
+}
+```
+
+The returned `URL` is a copy. Mutating it does not change the request context seen by another helper call.
+
+## Request method
+
+`requestMethod()` returns the normalized uppercase HTTP method for the active request:
+
+```ts
+import {
+    requestMethod,
+} from "bcp/server";
+
+export async function POST() {
+    return Response.json({
+        method:
+            await requestMethod(),
+    });
+}
+```
+
+A POST request returns `"POST"`, a GET request returns `"GET"`, and so on.
+
+## Request ID
+
+`requestId()` provides one stable identifier for the active request:
+
+```ts
+import {
+    requestId,
+} from "bcp/server";
+
+export async function GET() {
+    const id =
+        await requestId();
+
+    return Response.json({
+        requestId:
+            id,
+    });
+}
+```
+
+When the incoming request includes a valid `X-Request-Id`, BCP preserves that value. If the header is missing, blank, longer than 256 characters or contains control characters, BCP generates a UUID once and every `requestId()` call in that request returns the same generated value.
+
+## Bearer tokens
+
+Use `bearerToken()` to extract an HTTP Bearer credential from the `Authorization` header:
+
+```ts
+import {
+    bearerToken,
+} from "bcp/server";
+
+export async function GET() {
+    const token =
+        await bearerToken();
+
+    if (!token) {
+        return Response.json(
+            {
+                error:
+                    "Unauthorized",
+            },
+            {
+                status:
+                    401,
+            }
+        );
+    }
+
+    return Response.json({
+        authenticated:
+            true,
+    });
+}
+```
+
+The `Bearer` scheme is matched case-insensitively. BCP returns the credential string after the scheme and does not decode, verify or assume JWT. Missing authorization and non-Bearer schemes return `null`.
+
+## Client IP
+
+`clientIp()` reads the direct connection address attached to the BCP request context:
+
+```ts
+import {
+    clientIp,
+} from "bcp/server";
+
+export async function GET() {
+    return Response.json({
+        ip:
+            await clientIp(),
+    });
+}
+```
+
+Proxy forwarding headers are not trusted by default. Applications behind a trusted reverse proxy can opt in explicitly:
+
+```ts
+const ip =
+    await clientIp({
+        trustProxy:
+            true,
+    });
+```
+
+When `trustProxy` is enabled, BCP checks client-address sources in this order:
+
+1. the standardized `Forwarded` header (`for=`)
+2. the first usable value in `X-Forwarded-For`
+3. `X-Real-IP`
+4. the direct connection address
+
+Do not enable `trustProxy` when clients can connect directly without a trusted proxy stripping or replacing forwarding headers, because forwarded client-IP headers can otherwise be spoofed.
+
+IPv4-mapped IPv6 addresses such as `::ffff:127.0.0.1` are normalized to `127.0.0.1`.
+
+## JSON responses
+
+`json()` is a small wrapper around the standard Web `Response.json()` API. It accepts the response body and an optional `ResponseInit`:
+
+```ts
+import {
+    json,
+} from "bcp/server";
+
+export function POST() {
+    return json(
+        {
+            success: true,
+        },
+        {
+            status: 201,
+            headers: {
+                "x-created": "yes",
+            },
+        }
+    );
+}
+```
+
+BCP keeps the Web Response model, so existing `Response` objects and `Response.json()` continue to work alongside the helper.
+
+## Redirect responses
+
+Use `redirect()` to create HTTP redirects. Relative destinations are resolved against the current request URL:
+
+```ts
+import {
+    redirect,
+} from "bcp/server";
+
+export function POST() {
+    return redirect(
+        "/dashboard",
+        303
+    );
+}
+```
+
+The default status is `307`. Supported redirect statuses are `301`, `302`, `303`, `307` and `308`. Redirect destinations must use HTTP or HTTPS. Absolute HTTP/HTTPS URLs are also supported.
+
+A common login-style flow can combine response cookies and redirects:
+
+```ts
+import {
+    cookies,
+    redirect,
+} from "bcp/server";
+
+export async function POST() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "session",
+        "session-token",
+        {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: "/",
+        }
+    );
+
+    return redirect(
+        "/dashboard",
+        303
+    );
+}
+```
+
+BCP applies pending response cookies after the handler resolves, so cookies created before `redirect()` are preserved on the redirect response.
+
+## Request cookies
+
+Use `cookies()` to inspect cookies sent by the client:
+
+```ts
+import {
+    cookies,
+} from "bcp/server";
+
+export async function GET() {
+    const cookieStore =
+        await cookies();
+
+    return Response.json({
+        session:
+            cookieStore.get(
+                "session"
+            )?.value ?? null,
+        hasTheme:
+            cookieStore.has(
+                "theme"
+            ),
+        all:
+            cookieStore.getAll(),
+    });
+}
+```
+
+Request cookie values are percent-decoded when possible. Invalid percent encoding is preserved instead of failing the request.
+
+## Setting response cookies
+
+`cookies().set()` records a `Set-Cookie` value that BCP applies to the API response:
+
+```ts
+import {
+    cookies,
+} from "bcp/server";
+
+export async function POST() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "session",
+        "session-token",
+        {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: "/",
+            maxAge: 60 * 60 * 12,
+        }
+    );
+
+    return Response.json({
+        success: true,
+    });
+}
+```
+
+The object form is also supported:
+
+```ts
+cookieStore.set({
+    name: "refreshToken",
+    value: "token-value",
+    httpOnly: true,
+    secure: true,
+    sameSite: "strict",
+    path: "/api",
+    expires:
+        new Date(
+            Date.now() +
+            7 * 24 * 60 * 60 * 1000
+        ),
+});
+```
+
+Supported response-cookie options are:
+
+- `domain`
+- `path`
+- `expires`
+- `maxAge`
+- `httpOnly`
+- `secure`
+- `sameSite`: `"lax"`, `"strict"` or `"none"`
+
+Multiple response cookies remain separate `Set-Cookie` header values. Cookies already present on the returned `Response` are preserved.
+
+## Deleting cookies
+
+Deleting a cookie emits an expired cookie with `Max-Age=0`:
+
+```ts
+export async function DELETE() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.delete(
+        "session"
+    );
+
+    return Response.json({
+        success: true,
+    });
+}
+```
+
+When the original cookie uses a custom path or domain, supply the same values when deleting it:
+
+```ts
+cookieStore.delete(
+    "session",
+    {
+        path: "/admin",
+        domain: "example.com",
+    }
+);
+```
+
+## Request isolation
+
+BCP stores request state with Node.js `AsyncLocalStorage`. Concurrent requests receive independent URL, method, request ID, headers and cookies, so request data from one user is not shared with another request.
+
+Calling a request-scoped helper without an active BCP request context throws an error. A relative `redirect()` also requires the active request context because it resolves the destination against the current URL.
+
+## Client boundary
+
+This is invalid in the current 0.1.x page/client pipeline:
+
+```tsx
+import {
+    cookies,
+} from "bcp/server";
+
+export default function Page() {
+    return null;
+}
+```
+
+Move the server operation behind an API route instead:
+
+```text
+page/client
+    -> fetch("/api/session")
+    -> API route
+    -> bcp/server
+```
+
+Future server-rendered data primitives can extend these helpers to page-level server execution without exposing them to the browser bundle.