@chidchanun/bcp 0.2.5 → 0.2.7

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

@@ -4,6 +4,11 @@ import {
     type AuthSession,
     type AuthUser,
 } from "./auth.js";
+import {
+    hasPermission,
+    type AuthorizationMatch,
+    type PermissionRequirement,
+} from "./authorization.js";
 import {
     redirect,
     type RedirectStatus,
@@ -31,7 +36,15 @@ extends AuthOptions {
 export interface RequireRoleOptions
 extends RequireAuthOptions {
     roleField?: string;
-    match?: "any" | "all";
+    match?: AuthorizationMatch;
+    forbiddenRedirectTo?: string | URL | null;
+    forbiddenRedirectStatus?: RedirectStatus;
+}
+
+export interface RequirePermissionOptions
+extends RequireAuthOptions {
+    permissionField?: string;
+    match?: AuthorizationMatch;
     forbiddenRedirectTo?: string | URL | null;
     forbiddenRedirectStatus?: RedirectStatus;
 }
@@ -186,25 +199,59 @@ export async function requireRole<
                     )
             );
 
-    if (!allowed) {
-        if (
-            forbiddenRedirectTo !== null
-        ) {
-            return redirect(
-                forbiddenRedirectTo,
-                forbiddenRedirectStatus
-            );
-        }
+    return finalizeAuthorization(
+        allowed,
+        authenticated,
+        forbiddenRedirectTo,
+        forbiddenRedirectStatus
+    );
+}
 
-        return new Response(
-            "Forbidden",
+export async function requirePermission<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    requiredPermission:
+        PermissionRequirement,
+    options:
+        RequirePermissionOptions = {}
+): Promise<AuthGuardResult<TUser, TData>> {
+    const {
+        permissionField =
+            "permissions",
+        match = "any",
+        forbiddenRedirectTo = null,
+        forbiddenRedirectStatus = 303,
+        ...authOptions
+    } = options;
+    const authenticated =
+        await requireAuth<TUser, TData>(
+            authOptions
+        );
+
+    if (
+        authenticated instanceof Response
+    ) {
+        return authenticated;
+    }
+
+    const allowed =
+        hasPermission(
+            authenticated.auth.user,
+            requiredPermission,
             {
-                status: 403,
+                field:
+                    permissionField,
+                match,
             }
         );
-    }
 
-    return authenticated;
+    return finalizeAuthorization(
+        allowed,
+        authenticated,
+        forbiddenRedirectTo,
+        forbiddenRedirectStatus
+    );
 }
 
 export function createAuthGuard<
@@ -245,6 +292,22 @@ export function createRoleGuard<
         );
 }
 
+export function createPermissionGuard<
+    TUser extends AuthUser = AuthUser,
+    TData extends object = Record<string, never>
+>(
+    requiredPermission:
+        PermissionRequirement,
+    options:
+        RequirePermissionOptions = {}
+): AuthGuardFunction<TUser, TData> {
+    return () =>
+        requirePermission<TUser, TData>(
+            requiredPermission,
+            options
+        );
+}
+
 export function getGuardAuth<
     TUser extends AuthUser = AuthUser,
     TData extends object = Record<string, never>
@@ -293,6 +356,39 @@ export function getGuardAuth<
         AuthSession<TUser, TData>;
 }
 
+function finalizeAuthorization<
+    TUser extends AuthUser,
+    TData extends object
+>(
+    allowed: boolean,
+    authenticated:
+        AuthGuardData<TUser, TData>,
+    forbiddenRedirectTo:
+        string | URL | null,
+    forbiddenRedirectStatus:
+        RedirectStatus
+): Promise<AuthGuardResult<TUser, TData>> | AuthGuardData<TUser, TData> | Response {
+    if (allowed) {
+        return authenticated;
+    }
+
+    if (
+        forbiddenRedirectTo !== null
+    ) {
+        return redirect(
+            forbiddenRedirectTo,
+            forbiddenRedirectStatus
+        );
+    }
+
+    return new Response(
+        "Forbidden",
+        {
+            status: 403,
+        }
+    );
+}
+
 function normalizeRequiredRoles(
     value: RequiredRole
 ): string[] {

package/packages/server/src/authorization.ts

@@ -0,0 +1,368 @@
+export type AuthorizationMatch =
+    | "any"
+    | "all";
+
+export type PermissionRequirement =
+    | string
+    | readonly string[];
+
+export interface PermissionCheckOptions {
+    field?: string;
+    match?: AuthorizationMatch;
+}
+
+export interface AuthorizationContext<
+    TUser extends object = Record<string, unknown>,
+    TResource = unknown,
+    TData = unknown
+> {
+    user: TUser;
+    resource?: TResource;
+    data?: TData;
+}
+
+export type AuthorizationPolicy<
+    TUser extends object = Record<string, unknown>,
+    TResource = unknown,
+    TData = unknown
+> = (
+    context: AuthorizationContext<
+        TUser,
+        TResource,
+        TData
+    >
+) => boolean | Promise<boolean>;
+
+export class AuthorizationError
+    extends Error {
+    readonly status = 403;
+    readonly code = "FORBIDDEN";
+
+    constructor(
+        message = "Forbidden"
+    ) {
+        super(message);
+        this.name =
+            "AuthorizationError";
+    }
+}
+
+export function getUserPermissions(
+    user: object,
+    field = "permissions"
+): string[] {
+    const normalizedField =
+        normalizeField(
+            field
+        );
+    const value =
+        (
+            user as
+            Record<string, unknown>
+        )[normalizedField];
+
+    if (
+        typeof value === "string"
+    ) {
+        const permission =
+            value.trim();
+
+        return permission
+            ? [permission]
+            : [];
+    }
+
+    if (
+        !Array.isArray(
+            value
+        )
+    ) {
+        return [];
+    }
+
+    return Array.from(
+        new Set(
+            value
+                .filter(
+                    (
+                        permission
+                    ): permission is string =>
+                        typeof permission ===
+                        "string"
+                )
+                .map(
+                    (permission) =>
+                        permission.trim()
+                )
+                .filter(Boolean)
+        )
+    );
+}
+
+export function hasPermission(
+    user: object,
+    required:
+        PermissionRequirement,
+    options:
+        PermissionCheckOptions = {}
+): boolean {
+    const requiredPermissions =
+        normalizePermissions(
+            required
+        );
+    const assignedPermissions =
+        getUserPermissions(
+            user,
+            options.field
+        );
+    const match =
+        options.match ??
+        "any";
+
+    assertAuthorizationMatch(
+        match
+    );
+
+    return match === "all"
+        ? requiredPermissions.every(
+            (permission) =>
+                assignedPermissions.includes(
+                    permission
+                )
+        )
+        : requiredPermissions.some(
+            (permission) =>
+                assignedPermissions.includes(
+                    permission
+                )
+        );
+}
+
+export function assertPermission(
+    user: object,
+    required:
+        PermissionRequirement,
+    options:
+        PermissionCheckOptions = {}
+): void {
+    if (
+        !hasPermission(
+            user,
+            required,
+            options
+        )
+    ) {
+        throw new AuthorizationError();
+    }
+}
+
+export function defineAuthorizationPolicy<
+    TUser extends object,
+    TResource = unknown,
+    TData = unknown
+>(
+    policy:
+        AuthorizationPolicy<
+            TUser,
+            TResource,
+            TData
+        >
+): AuthorizationPolicy<
+    TUser,
+    TResource,
+    TData
+> {
+    if (
+        typeof policy !==
+        "function"
+    ) {
+        throw new TypeError(
+            "BCP Authorization: policy must be a function."
+        );
+    }
+
+    return policy;
+}
+
+export async function can<
+    TUser extends object,
+    TResource = unknown,
+    TData = unknown
+>(
+    policy:
+        AuthorizationPolicy<
+            TUser,
+            TResource,
+            TData
+        >,
+    context:
+        AuthorizationContext<
+            TUser,
+            TResource,
+            TData
+        >
+): Promise<boolean> {
+    assertAuthorizationContext(
+        context
+    );
+
+    return Boolean(
+        await policy(
+            context
+        )
+    );
+}
+
+export async function cannot<
+    TUser extends object,
+    TResource = unknown,
+    TData = unknown
+>(
+    policy:
+        AuthorizationPolicy<
+            TUser,
+            TResource,
+            TData
+        >,
+    context:
+        AuthorizationContext<
+            TUser,
+            TResource,
+            TData
+        >
+): Promise<boolean> {
+    return !await can(
+        policy,
+        context
+    );
+}
+
+export async function authorize<
+    TUser extends object,
+    TResource = unknown,
+    TData = unknown
+>(
+    policy:
+        AuthorizationPolicy<
+            TUser,
+            TResource,
+            TData
+        >,
+    context:
+        AuthorizationContext<
+            TUser,
+            TResource,
+            TData
+        >,
+    message = "Forbidden"
+): Promise<void> {
+    if (
+        !await can(
+            policy,
+            context
+        )
+    ) {
+        throw new AuthorizationError(
+            message
+        );
+    }
+}
+
+function normalizePermissions(
+    value:
+        PermissionRequirement
+): string[] {
+    const permissions =
+        typeof value === "string"
+            ? [value]
+            : [
+                ...value,
+            ];
+    const normalized =
+        permissions.map(
+            (permission) =>
+                permission.trim()
+        );
+
+    if (
+        normalized.length === 0 ||
+        normalized.some(
+            (permission) =>
+                permission.length === 0
+        )
+    ) {
+        throw new TypeError(
+            "BCP Authorization: required permissions must contain non-empty strings."
+        );
+    }
+
+    return Array.from(
+        new Set(
+            normalized
+        )
+    );
+}
+
+function normalizeField(
+    value: string
+): string {
+    const field =
+        value.trim();
+
+    if (!field) {
+        throw new TypeError(
+            "BCP Authorization: permission field must be a non-empty string."
+        );
+    }
+
+    return field;
+}
+
+function assertAuthorizationMatch(
+    value: string
+): asserts value is AuthorizationMatch {
+    if (
+        value !== "any" &&
+        value !== "all"
+    ) {
+        throw new TypeError(
+            "BCP Authorization: match must be either \"any\" or \"all\"."
+        );
+    }
+}
+
+function assertAuthorizationContext(
+    value: unknown
+): asserts value is AuthorizationContext<object> {
+    if (
+        !value ||
+        typeof value !== "object" ||
+        Array.isArray(
+            value
+        ) ||
+        !(
+            "user" in value
+        ) ||
+        !(
+            value as {
+                user?: unknown;
+            }
+        ).user ||
+        typeof (
+            value as {
+                user: unknown;
+            }
+        ).user !== "object" ||
+        Array.isArray(
+            (
+                value as {
+                    user: unknown;
+                }
+            ).user
+        )
+    ) {
+        throw new TypeError(
+            "BCP Authorization: context must contain a user object."
+        );
+    }
+}