@chidchanun/bcp 0.1.6 → 0.1.8

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.6",
+  "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",
@@ -43,6 +43,11 @@
       "types": "./packages/client/src/config.ts",
       "default": "./packages/client/src/config.ts"
     },
+    "./server": {
+      "types": "./packages/client/src/server.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/server.ts"
+    },
     "./server-only": {
       "types": "./packages/client/src/server-only.d.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

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

@@ -22,6 +22,8 @@ const MODULE_EXTENSIONS = [
     ".cjs",
 ] as const;
 
+const SERVER_ONLY_IMPORTS = new Set(["bcp/server","bcp/server-only"])
+
 export function validateClientBoundaries(
     routes: Route[],
     rootDirectory: string
@@ -127,13 +129,13 @@ function visitClientModule(
             source
         )
     ) {
-        if (
-            specifier ===
-            "bcp/server-only"
-        ) {
+        if (SERVER_ONLY_IMPORTS.has(specifier)){
             throw new Error(
-                `BCP Framework: ${formatApplicationPath(rootDirectory, filePath)} imports bcp/server-only but is reachable from the client bundle for ${routeName}. Move the server dependency behind an API route.`
-            );
+                `BCP Framework: ${formatApplicationPath(
+                    rootDirectory,
+                    filePath
+                )} imports ${specifier} but is reachable from the client bundle for ${routeName}. Move the server dependency behind an API route.`
+            )
         }
 
         const dependency =

package/packages/bundler/src/server-production.ts

@@ -172,6 +172,12 @@ export async function buildProductionServer(
             "../../client/src/islands.tsx"
         );
 
+    const frameworkServerEntry =
+        path.resolve(
+            frameworkDirectory,
+            "../../client/src/server.ts"
+        );
+
     await build({
         absWorkingDir:
             rootDirectory,
@@ -223,6 +229,17 @@ export async function buildProductionServer(
                                 frameworkIslandEntry,
                         })
                     );
+
+                    buildApi.onResolve(
+                        {
+                            filter:
+                                /^bcp\/server$/,
+                        },
+                        () => ({
+                            path:
+                                frameworkServerEntry,
+                        })
+                    );
                 },
             },
         ],

package/packages/client/src/server.ts

@@ -0,0 +1,36 @@
+export {
+    bearerToken,
+    clientIp,
+    cookies,
+    headers,
+    requestId,
+    requestMethod,
+    requestUrl,
+
+    type ClientIpOptions,
+    type CookieSameSite,
+    type RequestCookie,
+    type RequestCookieStore,
+    type ResponseCookie,
+    type ResponseCookieOptions,
+} from "../../server/src/request-context.js";
+
+export {
+    json,
+    redirect,
+
+    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/index.ts

@@ -41,6 +41,8 @@ import {
     DevHmrServer,
 } from "./dev-hmr.js";
 
+import { runWithRequestContext, applyResponseCookies } from "./request-context.ts";
+
 /*
  * =====================================
  * Constants
@@ -1441,24 +1443,41 @@ async function handleApiRoute(
         );
 
     const response =
-        await handler(
+        await runWithRequestContext(
             request,
+
+            async () => {
+                const result =
+                    await handler(
+                        request,
+                        {
+                            params,
+                        }
+                    );
+
+                if (
+                    !(
+                        result instanceof
+                        Response
+                    )
+                ) {
+                    throw new Error(
+                        `API handler "${method} ${route.pathname}" must return a Response object.`
+                    );
+                }
+
+                return applyResponseCookies(
+                    result
+                );
+            },
             {
-                params,
+                remoteAddress:
+                    req.socket
+                        .remoteAddress ??
+                    null,
             }
         );
 
-    if (
-        !(
-            response instanceof
-            Response
-        )
-    ) {
-        throw new Error(
-            `API handler "${method} ${route.pathname}" must return a Response object.`
-        );
-    }
-
     await sendWebResponse(
         res,
         response,