@chidchanun/bcp 0.2.5 → 0.2.6

package/packages/server/src/request-security.ts

@@ -0,0 +1,596 @@
+import {
+    createHmac,
+    randomBytes,
+    timingSafeEqual,
+} from "node:crypto";
+
+import {
+    cookies,
+    headers,
+    requestMethod,
+    requestUrl,
+    type CookieSameSite,
+} from "./request-context.js";
+
+const DEFAULT_CSRF_COOKIE_NAME =
+    "bcp_csrf";
+const DEFAULT_CSRF_HEADER_NAME =
+    "x-bcp-csrf";
+const DEFAULT_CSRF_MAX_AGE =
+    60 * 60 * 2;
+const MINIMUM_SECRET_BYTES =
+    32;
+const SAFE_METHODS =
+    new Set([
+        "GET",
+        "HEAD",
+        "OPTIONS",
+    ]);
+
+export interface SameOriginOptions {
+    allowedOrigins?: readonly string[];
+    allowMissingOrigin?: boolean;
+}
+
+export interface CsrfTokenOptions {
+    secret?: string;
+    cookieName?: string;
+    headerName?: string;
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: CookieSameSite;
+}
+
+export interface VerifyCsrfRequestOptions
+extends
+    CsrfTokenOptions,
+    SameOriginOptions {
+    token?: string;
+}
+
+export class RequestSecurityError
+    extends Error {
+    readonly status = 403;
+    readonly code:
+        | "INVALID_ORIGIN"
+        | "INVALID_CSRF_TOKEN";
+
+    constructor(
+        code:
+            | "INVALID_ORIGIN"
+            | "INVALID_CSRF_TOKEN",
+        message: string
+    ) {
+        super(message);
+        this.name =
+            "RequestSecurityError";
+        this.code =
+            code;
+    }
+}
+
+export function isSafeHttpMethod(
+    method: string
+): boolean {
+    return SAFE_METHODS.has(
+        String(method)
+            .trim()
+            .toUpperCase()
+    );
+}
+
+export async function isSameOriginRequest(
+    options:
+        SameOriginOptions = {}
+): Promise<boolean> {
+    const method =
+        await requestMethod();
+
+    if (
+        isSafeHttpMethod(
+            method
+        )
+    ) {
+        return true;
+    }
+
+    const url =
+        await requestUrl();
+    const requestHeaders =
+        await headers();
+    const allowedOrigins =
+        new Set<string>([
+            url.origin,
+            ...normalizeAllowedOrigins(
+                options.allowedOrigins
+            ),
+        ]);
+    const originHeader =
+        requestHeaders.get(
+            "origin"
+        );
+
+    if (originHeader) {
+        const origin =
+            tryNormalizeOrigin(
+                originHeader
+            );
+
+        return origin !== null &&
+            allowedOrigins.has(
+                origin
+            );
+    }
+
+    const referer =
+        requestHeaders.get(
+            "referer"
+        );
+
+    if (referer) {
+        const origin =
+            tryNormalizeOrigin(
+                referer
+            );
+
+        return origin !== null &&
+            allowedOrigins.has(
+                origin
+            );
+    }
+
+    return options.allowMissingOrigin ===
+        true;
+}
+
+export async function requireSameOriginRequest(
+    options:
+        SameOriginOptions = {}
+): Promise<void> {
+    if (
+        !await isSameOriginRequest(
+            options
+        )
+    ) {
+        throw new RequestSecurityError(
+            "INVALID_ORIGIN",
+            "BCP Security: request origin is not allowed."
+        );
+    }
+}
+
+export async function createCsrfToken(
+    options:
+        CsrfTokenOptions = {}
+): Promise<string> {
+    const secret =
+        resolveCsrfSecret(
+            options.secret
+        );
+    const maxAge =
+        resolveMaxAge(
+            options.maxAge
+        );
+    const issuedAt =
+        currentUnixTime();
+    const nonce =
+        randomBytes(32)
+            .toString(
+                "base64url"
+            );
+    const payload =
+        `v1.${issuedAt}.${nonce}`;
+    const signature =
+        signToken(
+            payload,
+            secret
+        );
+    const token =
+        `${payload}.${signature}`;
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        resolveCookieName(
+            options.cookieName
+        ),
+        token,
+        {
+            httpOnly: true,
+            secure:
+                options.secure ??
+                process.env.NODE_ENV ===
+                    "production",
+            sameSite:
+                options.sameSite ??
+                "lax",
+            path:
+                options.path ??
+                "/",
+            domain:
+                options.domain,
+            maxAge,
+        }
+    );
+
+    return token;
+}
+
+export async function destroyCsrfToken(
+    options:
+        CsrfTokenOptions = {}
+): Promise<void> {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.delete(
+        resolveCookieName(
+            options.cookieName
+        ),
+        {
+            path:
+                options.path ??
+                "/",
+            domain:
+                options.domain,
+        }
+    );
+}
+
+export async function verifyCsrfToken(
+    token?: string,
+    options:
+        CsrfTokenOptions = {}
+): Promise<boolean> {
+    const cookieStore =
+        await cookies();
+    const cookieToken =
+        cookieStore.get(
+            resolveCookieName(
+                options.cookieName
+            )
+        )?.value;
+    const submittedToken =
+        token ??
+        (
+            await headers()
+        ).get(
+            resolveHeaderName(
+                options.headerName
+            )
+        ) ??
+        undefined;
+
+    if (
+        !cookieToken ||
+        !submittedToken ||
+        !safeStringEqual(
+            cookieToken,
+            submittedToken
+        )
+    ) {
+        return false;
+    }
+
+    const parts =
+        submittedToken.split(".");
+
+    if (
+        parts.length !== 4 ||
+        parts[0] !== "v1"
+    ) {
+        return false;
+    }
+
+    const issuedAt =
+        Number(
+            parts[1]
+        );
+
+    if (
+        !Number.isInteger(
+            issuedAt
+        ) ||
+        issuedAt < 0
+    ) {
+        return false;
+    }
+
+    const maxAge =
+        resolveMaxAge(
+            options.maxAge
+        );
+    const now =
+        currentUnixTime();
+
+    if (
+        issuedAt > now + 60 ||
+        now - issuedAt > maxAge
+    ) {
+        return false;
+    }
+
+    const payload =
+        parts
+            .slice(0, 3)
+            .join(".");
+    const expectedSignature =
+        signToken(
+            payload,
+            resolveCsrfSecret(
+                options.secret
+            )
+        );
+
+    return safeStringEqual(
+        parts[3],
+        expectedSignature
+    );
+}
+
+export async function verifyCsrfRequest(
+    options:
+        VerifyCsrfRequestOptions = {}
+): Promise<boolean> {
+    if (
+        isSafeHttpMethod(
+            await requestMethod()
+        )
+    ) {
+        return true;
+    }
+
+    if (
+        !await isSameOriginRequest(
+            options
+        )
+    ) {
+        return false;
+    }
+
+    return verifyCsrfToken(
+        options.token,
+        options
+    );
+}
+
+export async function requireCsrfRequest(
+    options:
+        VerifyCsrfRequestOptions = {}
+): Promise<void> {
+    if (
+        !await isSameOriginRequest(
+            options
+        )
+    ) {
+        throw new RequestSecurityError(
+            "INVALID_ORIGIN",
+            "BCP Security: request origin is not allowed."
+        );
+    }
+
+    if (
+        isSafeHttpMethod(
+            await requestMethod()
+        )
+    ) {
+        return;
+    }
+
+    if (
+        !await verifyCsrfToken(
+            options.token,
+            options
+        )
+    ) {
+        throw new RequestSecurityError(
+            "INVALID_CSRF_TOKEN",
+            "BCP Security: CSRF token is missing, expired, or invalid."
+        );
+    }
+}
+
+function resolveCsrfSecret(
+    explicitSecret:
+        string | undefined
+): string {
+    const secret =
+        explicitSecret ??
+        process.env.BCP_CSRF_SECRET ??
+        process.env.BCP_SESSION_SECRET;
+
+    if (!secret) {
+        throw new Error(
+            "BCP Security: BCP_CSRF_SECRET or BCP_SESSION_SECRET is required for CSRF tokens."
+        );
+    }
+
+    if (
+        Buffer.byteLength(
+            secret,
+            "utf8"
+        ) <
+        MINIMUM_SECRET_BYTES
+    ) {
+        throw new Error(
+            `BCP Security: CSRF secret must be at least ${MINIMUM_SECRET_BYTES} bytes.`
+        );
+    }
+
+    return secret;
+}
+
+function resolveCookieName(
+    value:
+        string | undefined
+): string {
+    const result =
+        value?.trim() ||
+        DEFAULT_CSRF_COOKIE_NAME;
+
+    if (
+        !/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(
+            result
+        )
+    ) {
+        throw new TypeError(
+            "BCP Security: CSRF cookie name is invalid."
+        );
+    }
+
+    return result;
+}
+
+function resolveHeaderName(
+    value:
+        string | undefined
+): string {
+    const result =
+        value?.trim().toLowerCase() ||
+        DEFAULT_CSRF_HEADER_NAME;
+
+    if (
+        !/^[a-z0-9!#$%&'*+\-.^_`|~]+$/.test(
+            result
+        )
+    ) {
+        throw new TypeError(
+            "BCP Security: CSRF header name is invalid."
+        );
+    }
+
+    return result;
+}
+
+function resolveMaxAge(
+    value:
+        number | undefined
+): number {
+    const maxAge =
+        value ??
+        DEFAULT_CSRF_MAX_AGE;
+
+    if (
+        !Number.isFinite(
+            maxAge
+        ) ||
+        maxAge <= 0
+    ) {
+        throw new TypeError(
+            "BCP Security: CSRF maxAge must be a positive finite number of seconds."
+        );
+    }
+
+    return Math.floor(
+        maxAge
+    );
+}
+
+function normalizeAllowedOrigins(
+    values:
+        readonly string[] |
+        undefined
+): string[] {
+    if (!values) {
+        return [];
+    }
+
+    return Array.from(
+        new Set(
+            values.map(
+                normalizeOrigin
+            )
+        )
+    );
+}
+
+function normalizeOrigin(
+    value: string
+): string {
+    const origin =
+        tryNormalizeOrigin(
+            value
+        );
+
+    if (!origin) {
+        throw new TypeError(
+            `BCP Security: invalid origin \"${value}\".`
+        );
+    }
+
+    return origin;
+}
+
+function tryNormalizeOrigin(
+    value: string
+): string | null {
+    try {
+        const url =
+            new URL(
+                value.trim()
+            );
+
+        if (
+            url.protocol !== "http:" &&
+            url.protocol !== "https:"
+        ) {
+            return null;
+        }
+
+        return url.origin;
+    } catch {
+        return null;
+    }
+}
+
+function signToken(
+    payload: string,
+    secret: string
+): string {
+    return createHmac(
+        "sha256",
+        secret
+    )
+        .update(
+            `bcp-csrf:${payload}`,
+            "utf8"
+        )
+        .digest(
+            "base64url"
+        );
+}
+
+function safeStringEqual(
+    left: string,
+    right: string
+): boolean {
+    const leftBuffer =
+        Buffer.from(
+            left,
+            "utf8"
+        );
+    const rightBuffer =
+        Buffer.from(
+            right,
+            "utf8"
+        );
+
+    return (
+        leftBuffer.length ===
+            rightBuffer.length &&
+        timingSafeEqual(
+            leftBuffer,
+            rightBuffer
+        )
+    );
+}
+
+function currentUnixTime():
+number {
+    return Math.floor(
+        Date.now() /
+        1000
+    );
+}