@chidchanun/bcp 0.1.16 → 0.1.18

package/packages/client/src/auth.ts

@@ -12,3 +12,18 @@ export {
     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/middleware-loader.ts

@@ -5,6 +5,7 @@ import {
 } from "node:url";
 
 import type {
+    MiddlewareHandler,
     MiddlewareModule,
 } from "./middleware.js";
 
@@ -93,16 +94,17 @@ export function assertMiddlewareModule(
     module: MiddlewareModule,
     filePath = "middleware"
 ): void {
-    const handler =
+    const value =
         module.middleware ??
         module.default;
 
     if (
-        typeof handler !==
-        "function"
+        !isMiddlewareHandlerValue(
+            value
+        )
     ) {
         throw new Error(
-            `BCP Framework: ${filePath} must export a middleware(request) function or a default middleware function.`
+            `BCP Framework: ${filePath} must export a middleware function, a middleware function array, or a default equivalent.`
         );
     }
 
@@ -125,12 +127,12 @@ export function assertMiddlewareModule(
             ];
 
     for (
-        const value
+        const item
         of values
     ) {
         if (
-            typeof value !== "string" &&
-            !(value instanceof RegExp)
+            typeof item !== "string" &&
+            !(item instanceof RegExp)
         ) {
             throw new Error(
                 `BCP Framework: middleware matcher in ${filePath} must be a string, RegExp, or an array of them.`
@@ -138,3 +140,28 @@ export function assertMiddlewareModule(
         }
     }
 }
+
+function isMiddlewareHandlerValue(
+    value: unknown
+): value is
+    | MiddlewareHandler
+    | readonly MiddlewareHandler[] {
+    if (
+        typeof value ===
+        "function"
+    ) {
+        return true;
+    }
+
+    return (
+        Array.isArray(
+            value
+        ) &&
+        value.length > 0 &&
+        value.every(
+            (handler) =>
+                typeof handler ===
+                "function"
+        )
+    );
+}