@chidchanun/bcp 0.2.5 → 0.2.6

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."
+        );
+    }
+}