@chidchanun/bcp 0.1.7 → 0.1.9

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.9",
   "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/bundler/src/server-production.ts

@@ -22,6 +22,10 @@ import type {
     Route,
 } from "../../router/src/index.js";
 
+import {
+    findPageLoaderFile,
+} from "../../server/src/page-loader.js";
+
 import type {
     PartialHydrationBuildManifest,
 } from "./partial-hydration.js";
@@ -416,6 +420,26 @@ function createServerEntry(
                 `const ${pageName} = ${pageModuleName}.default;`
             );
 
+            const loaderFile =
+                findPageLoaderFile(
+                    route.filePath
+                );
+            let loaderName =
+                "null";
+
+            if (loaderFile) {
+                loaderName =
+                    `Loader${routeIndex}`;
+                imports.push(
+                    `import { loader as ${loaderName} } from ${JSON.stringify(
+                        toImportSpecifier(
+                            entryDirectory,
+                            loaderFile
+                        )
+                    )};`
+                );
+            }
+
             const layoutModules:
                 Array<{
                     name: string;
@@ -630,6 +654,7 @@ function createServerEntry(
   error: ${errorName},
   notFound: ${notFoundName},
   metadataSources: [${metadataSources.join(", ")}],
+  loader: ${loaderName},
   hydration: ${JSON.stringify(hydration)},
   client: ${JSON.stringify(client)}
 }`);

package/packages/client/src/index.tsx

@@ -17,6 +17,10 @@ export {
     type NavigationState,
 } from "./navigation-state.js";
 
+export {
+    useLoaderData,
+} from "./loader-data.js";
+
 export {
     createIsland,
     type BcpIslandMetadata,

package/packages/client/src/loader-data.tsx

@@ -0,0 +1,99 @@
+import {
+    createContext,
+    createElement,
+    useContext,
+    type ReactNode,
+} from "react";
+
+const LOADER_DATA_PARAM =
+    "__bcp_loader_data";
+const MISSING_LOADER_DATA =
+    Symbol(
+        "bcp-loader-data"
+    );
+
+const LoaderDataContext =
+    createContext<unknown>(
+        MISSING_LOADER_DATA
+    );
+
+export interface BcpLoaderDataProviderProps {
+    data: unknown;
+    children?: ReactNode;
+}
+
+export function BcpLoaderDataProvider({
+    data,
+    children,
+}: BcpLoaderDataProviderProps) {
+    return createElement(
+        LoaderDataContext.Provider,
+        {
+            value:
+                data,
+        },
+        children
+    );
+}
+
+export function useLoaderData<
+    T = unknown
+>(): T {
+    const contextValue =
+        useContext(
+            LoaderDataContext
+        );
+
+    if (
+        contextValue !==
+        MISSING_LOADER_DATA
+    ) {
+        return contextValue as T;
+    }
+
+    if (
+        typeof document !==
+        "undefined"
+    ) {
+        const element =
+            document.getElementById(
+                "__BCP_DATA__"
+            );
+
+        if (element) {
+            try {
+                const frameworkData =
+                    JSON.parse(
+                        element.textContent ||
+                        "{}"
+                    ) as {
+                        params?: Record<
+                            string,
+                            unknown
+                        >;
+                    };
+                const params =
+                    frameworkData.params;
+
+                if (
+                    params &&
+                    Object.prototype
+                        .hasOwnProperty.call(
+                            params,
+                            LOADER_DATA_PARAM
+                        )
+                ) {
+                    return params[
+                        LOADER_DATA_PARAM
+                    ] as T;
+                }
+            } catch {
+                // Fall through to the framework error below.
+            }
+        }
+    }
+
+    throw new Error(
+        "BCP Framework: useLoaderData() was used on a route without loader data. Add loader.ts next to page.tsx."
+    );
+}