@chidchanun/bcp 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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

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.7`. 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
 
@@ -196,6 +196,113 @@ export async function POST() {
 
 `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
@@ -338,6 +445,7 @@ 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/session-auth.md

@@ -0,0 +1,186 @@
+# JWT Cookie Sessions
+
+BCP Framework provides server-only JWT cookie session helpers through `bcp/server`.
+
+The current session implementation uses HS256 with Node.js `crypto`, requires a secret of at least 32 bytes, stores the token in an HttpOnly cookie by default and validates expiry before returning a session.
+
+## Environment
+
+Set a strong session secret in the server environment:
+
+```env
+BCP_SESSION_SECRET=replace-this-with-a-long-random-secret-at-least-32-bytes
+```
+
+Do not expose this value to browser code or prefix it as a public environment variable.
+
+## Create a session
+
+`createSession()` signs a JWT and stores it in a cookie. The default cookie name is `bcp_session` and the default lifetime is 12 hours.
+
+```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,
+    });
+}
+```
+
+By default BCP sets:
+
+- `HttpOnly`
+- `SameSite=Lax`
+- `Path=/`
+- `Secure` when `NODE_ENV=production`
+- `Max-Age` equal to the token lifetime
+
+Cookie and token behavior can be customized:
+
+```ts
+await createSession(
+    {
+        userId: 42,
+    },
+    {
+        cookieName: "access_token",
+        expiresIn: 60 * 60,
+        issuer: "my-app",
+        audience: [
+            "web",
+            "api",
+        ],
+        sameSite: "strict",
+        secure: true,
+        path: "/",
+    }
+);
+```
+
+## Read a session
+
+`getSession()` reads the cookie and verifies the JWT signature, expiration, issuer and audience when those options are provided.
+
+```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,
+    });
+}
+```
+
+Invalid, expired or tampered session tokens return `null` instead of throwing.
+
+## Destroy a session
+
+`destroySession()` expires the session cookie:
+
+```ts
+import {
+    destroySession,
+    json,
+} from "bcp/server";
+
+export async function POST() {
+    await destroySession();
+
+    return json({
+        success: true,
+    });
+}
+```
+
+When a custom cookie name, path or domain is used while creating the session, use the same values when destroying it.
+
+## Low-level token APIs
+
+BCP also exposes token-only helpers when an application needs to manage storage itself:
+
+```ts
+import {
+    createSessionToken,
+    verifySessionToken,
+} from "bcp/server";
+
+const token =
+    await createSessionToken(
+        {
+            userId: 42,
+        },
+        {
+            expiresIn: 3600,
+            issuer: "my-app",
+        }
+    );
+
+const claims =
+    await verifySessionToken<{
+        userId: number;
+    }>(
+        token,
+        {
+            issuer: "my-app",
+        }
+    );
+```
+
+`createSessionToken()` and `verifySessionToken()` use `BCP_SESSION_SECRET` unless an explicit `secret` option is supplied.
+
+## Security model
+
+BCP session tokens use HS256 and reject secrets shorter than 32 bytes. Verification validates the signature with a constant-time comparison and rejects malformed, expired or unsupported JWTs.
+
+JWT payloads are signed, not encrypted. Do not place passwords, API secrets or other confidential values in the session payload.
+
+Session revocation is not automatic for stateless JWTs. Applications that require immediate revocation should store a session identifier in the token and validate it against a server-side session table or another revocation store.
+
+## API route boundary
+
+These helpers are exported from `bcp/server` and remain server-only. In the current 0.1.x page/client pipeline, call them from API routes rather than modules reachable from the browser bundle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "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",

package/packages/client/src/server.ts

@@ -21,3 +21,16 @@ export {
 
     type RedirectStatus,
 } from "../../server/src/server-response.js";
+
+export {
+    createSession,
+    createSessionToken,
+    destroySession,
+    getSession,
+    verifySessionToken,
+
+    type SessionClaims,
+    type SessionCookieOptions,
+    type SessionPayload,
+    type SessionTokenOptions,
+} from "../../server/src/session.js";

package/packages/server/src/session.ts

@@ -0,0 +1,694 @@
+import {
+    createHmac,
+    timingSafeEqual,
+} from "node:crypto";
+
+import {
+    cookies,
+    type CookieSameSite,
+} from "./request-context.js";
+
+const DEFAULT_COOKIE_NAME =
+    "bcp_session";
+const DEFAULT_EXPIRES_IN =
+    60 * 60 * 12;
+const MAX_TOKEN_LENGTH =
+    16 * 1024;
+const MINIMUM_SECRET_BYTES =
+    32;
+
+export interface SessionPayload {
+    [key: string]: unknown;
+}
+
+export interface SessionClaims
+extends SessionPayload {
+    iat: number;
+    exp: number;
+    iss?: string;
+    aud?:
+        string |
+        string[];
+}
+
+export interface SessionTokenOptions {
+    secret?: string;
+    expiresIn?: number;
+    issuer?: string;
+    audience?:
+        string |
+        string[];
+}
+
+export interface SessionCookieOptions
+extends SessionTokenOptions {
+    cookieName?: string;
+    path?: string;
+    domain?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?:
+        CookieSameSite;
+}
+
+export async function createSessionToken<
+    T extends object
+>(
+    payload: T,
+    options:
+        SessionTokenOptions = {}
+): Promise<string> {
+    assertPayload(
+        payload
+    );
+
+    const secret =
+        resolveSessionSecret(
+            options.secret
+        );
+    const expiresIn =
+        resolveExpiresIn(
+            options.expiresIn
+        );
+    const issuer =
+        resolveOptionalIssuer(
+            options.issuer
+        );
+    const audience =
+        options.audience ===
+        undefined
+            ? undefined
+            : normalizeAudience(
+                options.audience
+            );
+    const now =
+        Math.floor(
+            Date.now() /
+            1000
+        );
+
+    const header = {
+        alg:
+            "HS256",
+        typ:
+            "JWT",
+    };
+
+    const claims:
+        SessionClaims = {
+        ...payload,
+        iat:
+            now,
+        exp:
+            now +
+            expiresIn,
+    };
+
+    if (
+        issuer !==
+        undefined
+    ) {
+        claims.iss =
+            issuer;
+    }
+
+    if (
+        audience !==
+        undefined
+    ) {
+        claims.aud =
+            audience;
+    }
+
+    const encodedHeader =
+        encodeJson(
+            header
+        );
+    const encodedPayload =
+        encodeJson(
+            claims
+        );
+    const signingInput =
+        `${encodedHeader}.${encodedPayload}`;
+    const signature =
+        signHs256(
+            signingInput,
+            secret
+        );
+
+    return `${signingInput}.${signature}`;
+}
+
+export async function verifySessionToken<
+    T extends object =
+        SessionPayload
+>(
+    token: string,
+    options:
+        SessionTokenOptions = {}
+): Promise<(
+    T & SessionClaims
+) | null> {
+    const secret =
+        resolveSessionSecret(
+            options.secret
+        );
+    const issuer =
+        resolveOptionalIssuer(
+            options.issuer
+        );
+    const audience =
+        options.audience ===
+        undefined
+            ? undefined
+            : normalizeAudience(
+                options.audience
+            );
+
+    try {
+        if (
+            typeof token !==
+                "string" ||
+            token.length === 0 ||
+            token.length >
+                MAX_TOKEN_LENGTH
+        ) {
+            return null;
+        }
+
+        const parts =
+            token.split(".");
+
+        if (
+            parts.length !==
+            3
+        ) {
+            return null;
+        }
+
+        const [
+            encodedHeader,
+            encodedPayload,
+            signature,
+        ] = parts;
+
+        const header =
+            decodeJson(
+                encodedHeader
+            ) as Record<
+                string,
+                unknown
+            >;
+
+        if (
+            header.alg !==
+                "HS256" ||
+            (
+                header.typ !==
+                    undefined &&
+                header.typ !==
+                    "JWT"
+            )
+        ) {
+            return null;
+        }
+
+        const signingInput =
+            `${encodedHeader}.${encodedPayload}`;
+        const expectedSignature =
+            signHs256(
+                signingInput,
+                secret
+            );
+
+        if (
+            !safeEqual(
+                signature,
+                expectedSignature
+            )
+        ) {
+            return null;
+        }
+
+        const claims =
+            decodeJson(
+                encodedPayload
+            ) as Record<
+                string,
+                unknown
+            >;
+        const now =
+            Math.floor(
+                Date.now() /
+                1000
+            );
+
+        if (
+            typeof claims.iat !==
+                "number" ||
+            !Number.isFinite(
+                claims.iat
+            ) ||
+            typeof claims.exp !==
+                "number" ||
+            !Number.isFinite(
+                claims.exp
+            ) ||
+            claims.exp <=
+                now
+        ) {
+            return null;
+        }
+
+        if (
+            claims.nbf !==
+            undefined
+        ) {
+            if (
+                typeof claims.nbf !==
+                    "number" ||
+                !Number.isFinite(
+                    claims.nbf
+                ) ||
+                claims.nbf >
+                    now
+            ) {
+                return null;
+            }
+        }
+
+        if (
+            issuer !==
+                undefined &&
+            claims.iss !==
+                issuer
+        ) {
+            return null;
+        }
+
+        if (
+            audience !==
+                undefined &&
+            !audienceMatches(
+                claims.aud,
+                audience
+            )
+        ) {
+            return null;
+        }
+
+        return claims as
+            T & SessionClaims;
+    } catch {
+        return null;
+    }
+}
+
+export async function createSession<
+    T extends object
+>(
+    payload: T,
+    options:
+        SessionCookieOptions = {}
+): Promise<string> {
+    const expiresIn =
+        resolveExpiresIn(
+            options.expiresIn
+        );
+    const token =
+        await createSessionToken(
+            payload,
+            {
+                secret:
+                    options.secret,
+                expiresIn,
+                issuer:
+                    options.issuer,
+                audience:
+                    options.audience,
+            }
+        );
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        resolveCookieName(
+            options.cookieName
+        ),
+        token,
+        {
+            httpOnly:
+                options.httpOnly ??
+                true,
+            secure:
+                options.secure ??
+                process.env.NODE_ENV ===
+                    "production",
+            sameSite:
+                options.sameSite ??
+                "lax",
+            path:
+                options.path ??
+                "/",
+            domain:
+                options.domain,
+            maxAge:
+                expiresIn,
+        }
+    );
+
+    return token;
+}
+
+export async function getSession<
+    T extends object =
+        SessionPayload
+>(
+    options:
+        SessionCookieOptions = {}
+): Promise<(
+    T & SessionClaims
+) | null> {
+    const cookieStore =
+        await cookies();
+    const token =
+        cookieStore.get(
+            resolveCookieName(
+                options.cookieName
+            )
+        )?.value;
+
+    if (!token) {
+        return null;
+    }
+
+    return verifySessionToken<
+        T
+    >(
+        token,
+        {
+            secret:
+                options.secret,
+            issuer:
+                options.issuer,
+            audience:
+                options.audience,
+        }
+    );
+}
+
+export async function destroySession(
+    options:
+        SessionCookieOptions = {}
+): Promise<void> {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.delete(
+        resolveCookieName(
+            options.cookieName
+        ),
+        {
+            path:
+                options.path ??
+                "/",
+            domain:
+                options.domain,
+        }
+    );
+}
+
+function resolveSessionSecret(
+    explicitSecret:
+        string | undefined
+): string {
+    const secret =
+        explicitSecret ??
+        process.env.BCP_SESSION_SECRET;
+
+    if (!secret) {
+        throw new Error(
+            "BCP Framework: BCP_SESSION_SECRET is required for session tokens."
+        );
+    }
+
+    if (
+        Buffer.byteLength(
+            secret,
+            "utf8"
+        ) <
+        MINIMUM_SECRET_BYTES
+    ) {
+        throw new Error(
+            `BCP Framework: session secret must be at least ${MINIMUM_SECRET_BYTES} bytes.`
+        );
+    }
+
+    return secret;
+}
+
+function resolveExpiresIn(
+    value:
+        number | undefined
+): number {
+    const expiresIn =
+        value ??
+        DEFAULT_EXPIRES_IN;
+
+    if (
+        !Number.isFinite(
+            expiresIn
+        ) ||
+        expiresIn <= 0
+    ) {
+        throw new Error(
+            "BCP Framework: session expiresIn must be a positive finite number of seconds."
+        );
+    }
+
+    return Math.floor(
+        expiresIn
+    );
+}
+
+function resolveCookieName(
+    value:
+        string | undefined
+): string {
+    const cookieName =
+        value ??
+        DEFAULT_COOKIE_NAME;
+
+    assertNonEmptyString(
+        cookieName,
+        "cookieName"
+    );
+
+    return cookieName;
+}
+
+function resolveOptionalIssuer(
+    value:
+        string | undefined
+): string | undefined {
+    if (
+        value ===
+        undefined
+    ) {
+        return undefined;
+    }
+
+    assertNonEmptyString(
+        value,
+        "issuer"
+    );
+
+    return value;
+}
+
+function assertPayload(
+    payload:
+        object
+): void {
+    if (
+        payload === null ||
+        typeof payload !==
+            "object" ||
+        Array.isArray(
+            payload
+        )
+    ) {
+        throw new Error(
+            "BCP Framework: session payload must be a plain object."
+        );
+    }
+}
+
+function assertNonEmptyString(
+    value: string,
+    label: string
+): void {
+    if (
+        typeof value !==
+            "string" ||
+        value.trim().length ===
+            0
+    ) {
+        throw new Error(
+            `BCP Framework: session ${label} must be a non-empty string.`
+        );
+    }
+}
+
+function normalizeAudience(
+    value:
+        string |
+        string[]
+): string | string[] {
+    if (
+        typeof value ===
+        "string"
+    ) {
+        assertNonEmptyString(
+            value,
+            "audience"
+        );
+        return value;
+    }
+
+    if (
+        !Array.isArray(
+            value
+        ) ||
+        value.length ===
+            0
+    ) {
+        throw new Error(
+            "BCP Framework: session audience must contain at least one value."
+        );
+    }
+
+    for (
+        const audience
+        of value
+    ) {
+        assertNonEmptyString(
+            audience,
+            "audience"
+        );
+    }
+
+    return [
+        ...value,
+    ];
+}
+
+function audienceMatches(
+    claim: unknown,
+    expected:
+        string |
+        string[]
+): boolean {
+    const expectedValues =
+        typeof expected ===
+            "string"
+            ? [
+                expected,
+            ]
+            : expected;
+    const claimValues =
+        typeof claim ===
+            "string"
+            ? [
+                claim,
+            ]
+            : Array.isArray(
+                claim
+            )
+                ? claim.filter(
+                    (
+                        value
+                    ): value is string =>
+                        typeof value ===
+                        "string"
+                )
+                : [];
+
+    return expectedValues.some(
+        (value) =>
+            claimValues.includes(
+                value
+            )
+    );
+}
+
+function encodeJson(
+    value: unknown
+): string {
+    return Buffer.from(
+        JSON.stringify(
+            value
+        ),
+        "utf8"
+    ).toString(
+        "base64url"
+    );
+}
+
+function decodeJson(
+    value: string
+): unknown {
+    const decoded =
+        Buffer.from(
+            value,
+            "base64url"
+        ).toString(
+            "utf8"
+        );
+
+    return JSON.parse(
+        decoded
+    );
+}
+
+function signHs256(
+    signingInput: string,
+    secret: string
+): string {
+    return createHmac(
+        "sha256",
+        secret
+    )
+        .update(
+            signingInput,
+            "utf8"
+        )
+        .digest(
+            "base64url"
+        );
+}
+
+function safeEqual(
+    actual: string,
+    expected: string
+): boolean {
+    const actualBuffer =
+        Buffer.from(
+            actual,
+            "base64url"
+        );
+    const expectedBuffer =
+        Buffer.from(
+            expected,
+            "base64url"
+        );
+
+    return (
+        actualBuffer.length ===
+            expectedBuffer.length &&
+        timingSafeEqual(
+            actualBuffer,
+            expectedBuffer
+        )
+    );
+}