@chidchanun/bcp 0.1.15 → 0.1.17

package/docs/auth-route-guards.md

@@ -0,0 +1,216 @@
+# Auth Route Guards
+
+BCP Framework `0.1.17` integrates the Authentication Core with route guards through the server-only `bcp/auth` entrypoint.
+
+## Protect a route tree
+
+Create `guard.ts` in the route directory you want to protect:
+
+```ts
+import {
+    createAuthGuard,
+} from "bcp/auth";
+
+export const guard =
+    createAuthGuard({
+        redirectTo:
+            "/login",
+    });
+```
+
+The guard redirects unauthenticated requests to `/login` with status `303` by default. A `303` is suitable for guards that may run before form actions because it converts a redirected mutation request into a normal GET request to the login page.
+
+To return `401 Unauthorized` instead of redirecting:
+
+```ts
+import {
+    createAuthGuard,
+} from "bcp/auth";
+
+export const guard =
+    createAuthGuard({
+        redirectTo:
+            null,
+    });
+```
+
+## Require a role
+
+```ts
+import {
+    createRoleGuard,
+} from "bcp/auth";
+
+interface User {
+    id: number;
+    email: string;
+    role: string;
+}
+
+export const guard =
+    createRoleGuard<User>(
+        "admin",
+        {
+            redirectTo:
+                "/login",
+        }
+    );
+```
+
+An authenticated user without the required role receives `403 Forbidden` by default.
+
+You can redirect forbidden users instead:
+
+```ts
+export const guard =
+    createRoleGuard<User>(
+        "admin",
+        {
+            forbiddenRedirectTo:
+                "/forbidden",
+        }
+    );
+```
+
+## Require one of several roles
+
+The default role matching mode is `any`:
+
+```ts
+export const guard =
+    createRoleGuard<User>([
+        "admin",
+        "manager",
+    ]);
+```
+
+A user with either role is allowed.
+
+## Require all permissions
+
+`requireRole()` and `createRoleGuard()` can read another user field and require every value:
+
+```ts
+interface User {
+    id: number;
+    permissions: string[];
+}
+
+export const guard =
+    createRoleGuard<User>(
+        [
+            "users.read",
+            "users.write",
+        ],
+        {
+            roleField:
+                "permissions",
+            match:
+                "all",
+        }
+    );
+```
+
+## Inline guard logic
+
+Use `requireAuth()` when a guard needs additional application-specific checks:
+
+```ts
+import {
+    requireAuth,
+} from "bcp/auth";
+
+export async function guard() {
+    const result =
+        await requireAuth<AppUser>();
+
+    if (
+        result instanceof
+        Response
+    ) {
+        return result;
+    }
+
+    if (
+        !result.auth.user.active
+    ) {
+        return new Response(
+            "Forbidden",
+            {
+                status:
+                    403,
+            }
+        );
+    }
+
+    return result;
+}
+```
+
+## Auth data in child guards and loaders
+
+Successful auth helpers return guard data in this shape:
+
+```ts
+{
+    auth: {
+        sid,
+        user,
+        data,
+        iat,
+        exp,
+        iss,
+        aud,
+    },
+}
+```
+
+Because BCP merges parent guard data into child guards and page loaders, descendants can read the authenticated session without verifying the cookie again.
+
+Use `getGuardAuth()` for typed access:
+
+```ts
+import {
+    getGuardAuth,
+} from "bcp/auth";
+
+export async function loader({
+    guardData,
+}) {
+    const session =
+        getGuardAuth<AppUser>(
+            guardData
+        );
+
+    if (!session) {
+        throw new Error(
+            "Protected loader did not receive auth guard data."
+        );
+    }
+
+    return {
+        userId:
+            session.user.id,
+    };
+}
+```
+
+## Low-level role checks
+
+`requireRole()` is also available directly:
+
+```ts
+import {
+    requireRole,
+} from "bcp/auth";
+
+export function guard() {
+    return requireRole<AppUser>(
+        "admin"
+    );
+}
+```
+
+## Security boundary
+
+`bcp/auth` is server-only. BCP blocks it from page/client graphs and maps its browser export to the server-only runtime guard. Authentication and authorization checks should stay in guards, loaders, actions, API routes, or other server modules.

package/docs/authentication.md

@@ -0,0 +1,201 @@
+# Authentication
+
+BCP Framework 0.1.16 adds a server-only authentication layer through `bcp/auth`.
+It builds on the signed JWT cookie/session primitives from `bcp/server` and provides a higher-level API for application authentication.
+
+## Environment
+
+Set a session secret with at least 32 bytes:
+
+```env
+BCP_SESSION_SECRET=replace-with-a-long-random-secret-at-least-32-bytes
+```
+
+The default cookie is `bcp_session`. It is HttpOnly, uses `SameSite=Lax`, has a 12-hour lifetime, and is Secure automatically when `NODE_ENV=production`.
+
+## Basic usage
+
+```ts
+import {
+    auth,
+    login,
+    logout,
+} from "bcp/auth";
+
+export async function POST() {
+    await login({
+        id: 42,
+        email: "user@example.com",
+        role: "admin",
+    });
+
+    return Response.json({
+        ok: true,
+    });
+}
+```
+
+Read the current authenticated session:
+
+```ts
+import {
+    auth,
+} from "bcp/auth";
+
+const session =
+    await auth<{
+        id: number;
+        email: string;
+        role: string;
+    }>();
+
+if (!session) {
+    // Not authenticated.
+}
+
+console.log(
+    session?.user.id
+);
+```
+
+`getSession()` is an alias for `auth()` when that naming is clearer in application code.
+
+## Typed auth factory
+
+For application-wide types and cookie settings, create a typed auth instance:
+
+```ts
+import {
+    createAuth,
+} from "bcp/auth";
+
+interface AppUser {
+    id: number;
+    email: string;
+    role: "admin" | "user";
+}
+
+interface AppSessionData {
+    tenantId: string;
+}
+
+export const appAuth =
+    createAuth<
+        AppUser,
+        AppSessionData
+    >({
+        cookieName:
+            "app_session",
+        expiresIn:
+            60 * 60 * 8,
+        issuer:
+            "my-app",
+        audience:
+            "web",
+    });
+```
+
+Login with typed session data:
+
+```ts
+await appAuth.login(
+    {
+        id: 42,
+        email: "user@example.com",
+        role: "admin",
+    },
+    {
+        data: {
+            tenantId:
+                "tenant-1",
+        },
+    }
+);
+```
+
+Read it later:
+
+```ts
+const session =
+    await appAuth.auth();
+
+console.log(
+    session?.user.email
+);
+console.log(
+    session?.data?.tenantId
+);
+```
+
+## Logout
+
+```ts
+await logout();
+```
+
+Or with a factory:
+
+```ts
+await appAuth.logout();
+```
+
+Logout expires the configured authentication cookie.
+
+## Session rotation
+
+Each auth login receives a unique `sid` (session identifier). `rotateSession()` keeps the current user and session data but issues a new `sid`, JWT, expiry window, and cookie.
+
+```ts
+const rotated =
+    await appAuth.rotateSession();
+
+if (rotated) {
+    console.log(
+        rotated.sid
+    );
+}
+```
+
+Rotation returns `null` when no valid auth session exists.
+
+A useful policy is to rotate after a security-sensitive event such as a privilege change or successful re-authentication.
+
+## Session shape
+
+An authenticated session contains the user, optional application session data, and signed JWT claims:
+
+```ts
+{
+    sid: string;
+    user: AppUser;
+    data?: AppSessionData;
+    iat: number;
+    exp: number;
+    iss?: string;
+    aud?: string | string[];
+}
+```
+
+## Security notes
+
+- `bcp/auth` is server-only and must not be imported into pages or client islands.
+- Never put passwords, password hashes, API secrets, access keys, or other sensitive credentials in the auth user/session payload. JWT cookie payloads are signed, not encrypted.
+- Keep `BCP_SESSION_SECRET` out of source control and use a strong random value of at least 32 bytes.
+- Authentication verifies identity/session state. Application authorization such as roles and permissions belongs in route guards or server actions.
+- Use HTTPS in production so Secure cookies are transmitted only over encrypted connections.
+
+## create-bcp-app
+
+When `JWT Cookie` authentication is selected, generated applications use `createAuth()` internally and expose helpers from `lib/auth.ts`:
+
+```ts
+import {
+    auth,
+    getSession,
+    login,
+    logout,
+    rotateSession,
+} from "@/lib/auth";
+```
+
+The generated `authenticateCredentials()` intentionally returns `null` until the application implements its own user lookup and password verification strategy.

package/docs/releases/0.1.16.md

@@ -0,0 +1,53 @@
+# BCP Framework 0.1.16
+
+## Authentication Core
+
+BCP 0.1.16 introduces the server-only `bcp/auth` entrypoint.
+
+### New APIs
+
+- `auth()` reads and validates the current authentication session.
+- `getSession()` is an auth-focused alias for `auth()`.
+- `login(user, options)` creates an authenticated JWT cookie session.
+- `logout(options)` expires the authentication cookie.
+- `rotateSession(options)` preserves the authenticated user/session data while issuing a new session identifier and token.
+- `createAuth<User, SessionData>(defaults)` creates a typed application auth instance with shared cookie/token configuration.
+
+### Session identity
+
+Every login now receives a random UUID `sid`. Session rotation always issues a new `sid`, so rotation produces a distinct signed token even if it happens within the same second.
+
+### Security
+
+- `bcp/auth` is exported as server-only in the package manifest.
+- The client-boundary validator blocks `bcp/auth` from page/client graphs.
+- The same validator now explicitly blocks direct `bcp/database` imports from client graphs as well.
+- Existing JWT signing, expiration, issuer/audience validation, HttpOnly cookies, production Secure defaults, and minimum 32-byte session secrets remain provided by the underlying session runtime.
+
+### create-bcp-app
+
+The JWT Cookie preset now uses the framework auth core through `createAuth()` while keeping the existing starter helper names and API routes compatible.
+
+Generated `lib/auth.ts` also exposes:
+
+```ts
+export const auth = frameworkAuth.auth;
+export const getSession = frameworkAuth.getSession;
+export const login = frameworkAuth.login;
+export const logout = frameworkAuth.logout;
+export const rotateSession = frameworkAuth.rotateSession;
+```
+
+`authenticateCredentials()` still returns `null` until the application implements its own user lookup and password verification.
+
+### Tests
+
+0.1.16 adds regression coverage for:
+
+- typed login/read/logout lifecycle;
+- typed `createAuth()` defaults;
+- session rotation and changing `sid` values;
+- invalid auth payload rejection;
+- published `bcp/auth` export wiring;
+- client-boundary blocking for auth/database;
+- JWT Cookie scaffold integration with the framework auth core.

package/docs/releases/0.1.17.md

@@ -0,0 +1,36 @@
+# BCP Framework 0.1.17
+
+## Auth + Route Guard Integration
+
+BCP Framework 0.1.17 connects the Authentication Core introduced in 0.1.16 with the existing scoped route guard system.
+
+### New `bcp/auth` guard helpers
+
+- `requireAuth()` verifies the active BCP auth session and returns it as guard data.
+- `requireRole()` verifies authentication plus one or more roles/permissions.
+- `createAuthGuard()` creates a guard function that can be exported directly from `guard.ts`.
+- `createRoleGuard()` creates a role-protected guard function.
+- `getGuardAuth()` safely reads typed auth data from merged `guardData`.
+
+Successful auth helpers return the session under `guardData.auth`, so child guards and page loaders can reuse the authenticated user without verifying the cookie again.
+
+### Unauthorized and forbidden behavior
+
+- Unauthenticated requests redirect to `/login` with HTTP `303` by default.
+- `redirectTo: null` returns `401 Unauthorized` instead.
+- Authenticated users that fail a role requirement receive `403 Forbidden` by default.
+- `forbiddenRedirectTo` can redirect insufficient-role users to a custom page.
+
+### Role matching
+
+- A single role can be required with `requireRole("admin")`.
+- Multiple roles default to `match: "any"`.
+- `match: "all"` requires every requested value.
+- `roleField` allows permission arrays or custom role fields such as `permissions` instead of the default `role` field.
+
+### Reliability
+
+- Added unit coverage for authentication redirects, 401 mode, role allow/deny behavior, custom role fields and guard factories.
+- Added page-guard pipeline integration coverage proving auth data flows from a parent auth guard into child guards.
+- Added publish-surface regression coverage for the route guard helpers exposed through `bcp/auth`.
+- Added dedicated Auth Route Guards documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "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",
@@ -48,6 +48,11 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/database.ts"
     },
+    "./auth": {
+      "types": "./packages/client/src/auth.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/auth.ts"
+    },
     "./server": {
       "types": "./packages/client/src/server.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

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

@@ -22,7 +22,13 @@ const MODULE_EXTENSIONS = [
     ".cjs",
 ] as const;
 
-const SERVER_ONLY_IMPORTS = new Set(["bcp/server","bcp/server-only"])
+const SERVER_ONLY_IMPORTS =
+    new Set([
+        "bcp/server",
+        "bcp/server-only",
+        "bcp/database",
+        "bcp/auth",
+    ]);
 
 export function validateClientBoundaries(
     routes: Route[],
@@ -129,13 +135,17 @@ function visitClientModule(
             source
         )
     ) {
-        if (SERVER_ONLY_IMPORTS.has(specifier)){
+        if (
+            SERVER_ONLY_IMPORTS.has(
+                specifier
+            )
+        ) {
             throw new Error(
                 `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/client/src/auth.ts

@@ -0,0 +1,29 @@
+export {
+    auth,
+    createAuth,
+    getSession,
+    login,
+    logout,
+    rotateSession,
+
+    type AuthApi,
+    type AuthLoginOptions,
+    type AuthOptions,
+    type AuthSession,
+    type AuthUser,
+} from "../../server/src/auth.js";
+
+export {
+    createAuthGuard,
+    createRoleGuard,
+    getGuardAuth,
+    requireAuth,
+    requireRole,
+
+    type AuthGuardData,
+    type AuthGuardFunction,
+    type AuthGuardResult,
+    type RequireAuthOptions,
+    type RequireRoleOptions,
+    type RequiredRole,
+} from "../../server/src/auth-guard.js";

package/packages/server/src/auth-guard.ts

@@ -0,0 +1,403 @@
+import {
+    auth,
+    type AuthOptions,
+    type AuthSession,
+    type AuthUser,
+} from "./auth.js";
+import {
+    redirect,
+    type RedirectStatus,
+} from "./server-response.js";
+
+export interface AuthGuardData<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+> extends Record<string, unknown> {
+    auth: AuthSession<TUser, TData>;
+}
+
+export interface RequireAuthOptions
+extends AuthOptions {
+    redirectTo?:
+        string |
+        URL |
+        null;
+    redirectStatus?: RedirectStatus;
+}
+
+export interface RequireRoleOptions
+extends RequireAuthOptions {
+    roleField?: string;
+    match?: "any" | "all";
+    forbiddenRedirectTo?:
+        string |
+        URL |
+        null;
+    forbiddenRedirectStatus?: RedirectStatus;
+}
+
+export type RequiredRole =
+    string |
+    readonly string[];
+
+export type AuthGuardResult<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+> =
+    | AuthGuardData<TUser, TData>
+    | Response;
+
+export type AuthGuardFunction<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+> = () => Promise<
+    AuthGuardResult<
+        TUser,
+        TData
+    >
+>;
+
+export async function requireAuth<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    options: RequireAuthOptions = {}
+): Promise<AuthGuardResult<TUser, TData>> {
+    const {
+        redirectTo = "/login",
+        redirectStatus = 303,
+        ...authOptions
+    } = options;
+    const session =
+        await auth<
+            TUser,
+            TData
+        >(
+            authOptions
+        );
+
+    if (!session) {
+        if (
+            redirectTo ===
+            null
+        ) {
+            return new Response(
+                "Unauthorized",
+                {
+                    status:
+                        401,
+                }
+            );
+        }
+
+        return redirect(
+            redirectTo,
+            redirectStatus
+        );
+    }
+
+    return {
+        auth:
+            session,
+    };
+}
+
+export async function requireRole<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    requiredRole: RequiredRole,
+    options: RequireRoleOptions = {}
+): Promise<AuthGuardResult<TUser, TData>> {
+    const roles =
+        normalizeRequiredRoles(
+            requiredRole
+        );
+    const {
+        roleField = "role",
+        match = "any",
+        forbiddenRedirectTo = null,
+        forbiddenRedirectStatus = 303,
+        ...authOptions
+    } = options;
+    const authenticated =
+        await requireAuth<
+            TUser,
+            TData
+        >(
+            authOptions
+        );
+
+    if (
+        authenticated instanceof
+        Response
+    ) {
+        return authenticated;
+    }
+
+    const assignedRoles =
+        readAssignedRoles(
+            authenticated.auth.user,
+            roleField
+        );
+    const allowed =
+        match === "all"
+            ? roles.every(
+                (role) =>
+                    assignedRoles.includes(
+                        role
+                    )
+            )
+            : roles.some(
+                (role) =>
+                    assignedRoles.includes(
+                        role
+                    )
+            );
+
+    if (!allowed) {
+        if (
+            forbiddenRedirectTo !==
+            null
+        ) {
+            return redirect(
+                forbiddenRedirectTo,
+                forbiddenRedirectStatus
+            );
+        }
+
+        return new Response(
+            "Forbidden",
+            {
+                status:
+                    403,
+            }
+        );
+    }
+
+    return authenticated;
+}
+
+export function createAuthGuard<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    options: RequireAuthOptions = {}
+): AuthGuardFunction<TUser, TData> {
+    return () =>
+        requireAuth<
+            TUser,
+            TData
+        >(
+            options
+        );
+}
+
+export function createRoleGuard<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    requiredRole: RequiredRole,
+    options: RequireRoleOptions = {}
+): AuthGuardFunction<TUser, TData> {
+    return () =>
+        requireRole<
+            TUser,
+            TData
+        >(
+            requiredRole,
+            options
+        );
+}
+
+export function getGuardAuth<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    guardData:
+        Readonly<{
+            auth?: unknown;
+        }>
+): AuthSession<TUser, TData> | null {
+    const value =
+        guardData.auth;
+
+    if (
+        !value ||
+        typeof value !==
+            "object" ||
+        Array.isArray(
+            value
+        )
+    ) {
+        return null;
+    }
+
+    const session =
+        value as Partial<
+            AuthSession<
+                TUser,
+                TData
+            >
+        >;
+
+    if (
+        typeof session.sid !==
+            "string" ||
+        session.sid.trim().length ===
+            0 ||
+        typeof session.iat !==
+            "number" ||
+        !Number.isFinite(
+            session.iat
+        ) ||
+        typeof session.exp !==
+            "number" ||
+        !Number.isFinite(
+            session.exp
+        ) ||
+        !isGuardAuthUser(
+            session.user
+        )
+    ) {
+        return null;
+    }
+
+    return value as
+        AuthSession<
+            TUser,
+            TData
+        >;
+}
+
+function normalizeRequiredRoles(
+    value: RequiredRole
+): string[] {
+    const roles =
+        typeof value ===
+            "string"
+            ? [
+                value,
+            ]
+            : [
+                ...value,
+            ];
+    const normalized =
+        roles.map(
+            (role) =>
+                role.trim()
+        );
+
+    if (
+        normalized.length ===
+            0 ||
+        normalized.some(
+            (role) =>
+                role.length ===
+                0
+        )
+    ) {
+        throw new TypeError(
+            "BCP Auth Guard: required roles must contain non-empty strings."
+        );
+    }
+
+    return Array.from(
+        new Set(
+            normalized
+        )
+    );
+}
+
+function readAssignedRoles(
+    user: AuthUser,
+    roleField: string
+): string[] {
+    const field =
+        roleField.trim();
+
+    if (!field) {
+        throw new TypeError(
+            "BCP Auth Guard: roleField must be a non-empty string."
+        );
+    }
+
+    const value =
+        (
+            user as
+            unknown as
+            Record<string, unknown>
+        )[field];
+
+    if (
+        typeof value ===
+        "string"
+    ) {
+        const role =
+            value.trim();
+
+        return role
+            ? [
+                role,
+            ]
+            : [];
+    }
+
+    if (
+        Array.isArray(
+            value
+        )
+    ) {
+        return value
+            .filter(
+                (
+                    role
+                ): role is string =>
+                    typeof role ===
+                    "string"
+            )
+            .map(
+                (role) =>
+                    role.trim()
+            )
+            .filter(
+                Boolean
+            );
+    }
+
+    return [];
+}
+
+function isGuardAuthUser(
+    value: unknown
+): value is AuthUser {
+    if (
+        !value ||
+        typeof value !==
+            "object" ||
+        Array.isArray(
+            value
+        )
+    ) {
+        return false;
+    }
+
+    const id =
+        (
+            value as
+            Record<string, unknown>
+        ).id;
+
+    return (
+        typeof id ===
+            "string" &&
+        id.trim().length >
+            0
+    ) || (
+        typeof id ===
+            "number" &&
+        Number.isFinite(
+            id
+        )
+    );
+}

package/packages/server/src/auth.ts

@@ -0,0 +1,376 @@
+import {
+    randomUUID,
+} from "node:crypto";
+
+import {
+    createSession,
+    destroySession,
+    getSession as readSession,
+    type SessionClaims,
+    type SessionCookieOptions,
+} from "./session.js";
+
+export interface AuthUser {
+    id: string | number;
+}
+
+export interface AuthSession<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+> extends SessionClaims {
+    sid: string;
+    user: TUser;
+    data?: TData;
+}
+
+export interface AuthOptions
+extends SessionCookieOptions {}
+
+export interface AuthLoginOptions<
+    TData extends object = Record<string, never>
+> extends AuthOptions {
+    data?: TData;
+}
+
+export interface AuthApi<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+> {
+    auth(
+        options?: AuthOptions
+    ): Promise<AuthSession<TUser, TData> | null>;
+    getSession(
+        options?: AuthOptions
+    ): Promise<AuthSession<TUser, TData> | null>;
+    login(
+        user: TUser,
+        options?: AuthLoginOptions<TData>
+    ): Promise<AuthSession<TUser, TData>>;
+    logout(
+        options?: AuthOptions
+    ): Promise<void>;
+    rotateSession(
+        options?: AuthOptions
+    ): Promise<AuthSession<TUser, TData> | null>;
+}
+
+interface AuthSessionPayload<
+    TUser extends AuthUser,
+    TData extends object
+> {
+    sid: string;
+    user: TUser;
+    data?: TData;
+}
+
+export async function auth<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    options: AuthOptions = {}
+): Promise<AuthSession<TUser, TData> | null> {
+    const session =
+        await readSession<
+            AuthSessionPayload<
+                TUser,
+                TData
+            >
+        >(
+            options
+        );
+
+    if (!session) {
+        return null;
+    }
+
+    if (
+        typeof session.sid !==
+            "string" ||
+        session.sid.trim().length ===
+            0 ||
+        !isAuthUser(
+            session.user
+        )
+    ) {
+        return null;
+    }
+
+    if (
+        session.data !== undefined &&
+        !isPlainObject(
+            session.data
+        )
+    ) {
+        return null;
+    }
+
+    return session as
+        AuthSession<
+            TUser,
+            TData
+        >;
+}
+
+export async function getSession<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    options: AuthOptions = {}
+): Promise<AuthSession<TUser, TData> | null> {
+    return auth<
+        TUser,
+        TData
+    >(
+        options
+    );
+}
+
+export async function login<
+    TUser extends AuthUser,
+    TData extends object = Record<string, never>
+>(
+    user: TUser,
+    options:
+        AuthLoginOptions<TData> = {}
+): Promise<AuthSession<TUser, TData>> {
+    assertAuthUser(
+        user
+    );
+
+    if (
+        options.data !== undefined &&
+        !isPlainObject(
+            options.data
+        )
+    ) {
+        throw new TypeError(
+            "BCP Auth: session data must be a plain object."
+        );
+    }
+
+    const {
+        data,
+        ...sessionOptions
+    } = options;
+    const payload:
+        AuthSessionPayload<
+            TUser,
+            TData
+        > = {
+        sid:
+            randomUUID(),
+        user,
+        ...(data === undefined
+            ? {}
+            : {
+                data,
+            }),
+    };
+
+    await createSession(
+        payload,
+        sessionOptions
+    );
+
+    const session =
+        await auth<
+            TUser,
+            TData
+        >(
+            sessionOptions
+        );
+
+    if (!session) {
+        throw new Error(
+            "BCP Auth: login created a session but it could not be read back."
+        );
+    }
+
+    return session;
+}
+
+export async function logout(
+    options: AuthOptions = {}
+): Promise<void> {
+    await destroySession(
+        options
+    );
+}
+
+export async function rotateSession<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    options: AuthOptions = {}
+): Promise<AuthSession<TUser, TData> | null> {
+    const current =
+        await auth<
+            TUser,
+            TData
+        >(
+            options
+        );
+
+    if (!current) {
+        return null;
+    }
+
+    return login<
+        TUser,
+        TData
+    >(
+        current.user,
+        {
+            ...options,
+            issuer:
+                options.issuer ??
+                current.iss,
+            audience:
+                options.audience ??
+                current.aud,
+            ...(current.data === undefined
+                ? {}
+                : {
+                    data:
+                        current.data,
+                }),
+        }
+    );
+}
+
+export function createAuth<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    defaults: AuthOptions = {}
+): AuthApi<TUser, TData> {
+    return {
+        auth: (
+            options = {}
+        ) =>
+            auth<
+                TUser,
+                TData
+            >({
+                ...defaults,
+                ...options,
+            }),
+        getSession: (
+            options = {}
+        ) =>
+            auth<
+                TUser,
+                TData
+            >({
+                ...defaults,
+                ...options,
+            }),
+        login: (
+            user,
+            options = {}
+        ) => {
+            const {
+                data,
+                ...sessionOptions
+            } = options;
+
+            return login<
+                TUser,
+                TData
+            >(
+                user,
+                {
+                    ...defaults,
+                    ...sessionOptions,
+                    ...(data === undefined
+                        ? {}
+                        : {
+                            data,
+                        }),
+                }
+            );
+        },
+        logout: (
+            options = {}
+        ) =>
+            logout({
+                ...defaults,
+                ...options,
+            }),
+        rotateSession: (
+            options = {}
+        ) =>
+            rotateSession<
+                TUser,
+                TData
+            >({
+                ...defaults,
+                ...options,
+            }),
+    };
+}
+
+function assertAuthUser(
+    value: unknown
+): asserts value is AuthUser {
+    if (
+        !isAuthUser(
+            value
+        )
+    ) {
+        throw new TypeError(
+            "BCP Auth: user must be a plain object with a non-empty string or finite numeric id."
+        );
+    }
+}
+
+function isAuthUser(
+    value: unknown
+): value is AuthUser {
+    if (
+        !isPlainObject(
+            value
+        )
+    ) {
+        return false;
+    }
+
+    const id =
+        value.id;
+
+    return (
+        typeof id === "string" &&
+        id.trim().length > 0
+    ) || (
+        typeof id === "number" &&
+        Number.isFinite(
+            id
+        )
+    );
+}
+
+function isPlainObject(
+    value: unknown
+): value is Record<string, unknown> {
+    if (
+        value === null ||
+        typeof value !== "object" ||
+        Array.isArray(
+            value
+        )
+    ) {
+        return false;
+    }
+
+    const prototype =
+        Object.getPrototypeOf(
+            value
+        );
+
+    return (
+        prototype ===
+            Object.prototype ||
+        prototype ===
+            null
+    );
+}