@chidchanun/bcp 0.1.6 → 0.1.8

package/packages/server/src/session.ts

@@ -0,0 +1,694 @@
+import {
+    createHmac,
+    timingSafeEqual,
+} from "node:crypto";
+
+import {
+    cookies,
+    type CookieSameSite,
+} from "./request-context.js";
+
+const DEFAULT_COOKIE_NAME =
+    "bcp_session";
+const DEFAULT_EXPIRES_IN =
+    60 * 60 * 12;
+const MAX_TOKEN_LENGTH =
+    16 * 1024;
+const MINIMUM_SECRET_BYTES =
+    32;
+
+export interface SessionPayload {
+    [key: string]: unknown;
+}
+
+export interface SessionClaims
+extends SessionPayload {
+    iat: number;
+    exp: number;
+    iss?: string;
+    aud?:
+        string |
+        string[];
+}
+
+export interface SessionTokenOptions {
+    secret?: string;
+    expiresIn?: number;
+    issuer?: string;
+    audience?:
+        string |
+        string[];
+}
+
+export interface SessionCookieOptions
+extends SessionTokenOptions {
+    cookieName?: string;
+    path?: string;
+    domain?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?:
+        CookieSameSite;
+}
+
+export async function createSessionToken<
+    T extends object
+>(
+    payload: T,
+    options:
+        SessionTokenOptions = {}
+): Promise<string> {
+    assertPayload(
+        payload
+    );
+
+    const secret =
+        resolveSessionSecret(
+            options.secret
+        );
+    const expiresIn =
+        resolveExpiresIn(
+            options.expiresIn
+        );
+    const issuer =
+        resolveOptionalIssuer(
+            options.issuer
+        );
+    const audience =
+        options.audience ===
+        undefined
+            ? undefined
+            : normalizeAudience(
+                options.audience
+            );
+    const now =
+        Math.floor(
+            Date.now() /
+            1000
+        );
+
+    const header = {
+        alg:
+            "HS256",
+        typ:
+            "JWT",
+    };
+
+    const claims:
+        SessionClaims = {
+        ...payload,
+        iat:
+            now,
+        exp:
+            now +
+            expiresIn,
+    };
+
+    if (
+        issuer !==
+        undefined
+    ) {
+        claims.iss =
+            issuer;
+    }
+
+    if (
+        audience !==
+        undefined
+    ) {
+        claims.aud =
+            audience;
+    }
+
+    const encodedHeader =
+        encodeJson(
+            header
+        );
+    const encodedPayload =
+        encodeJson(
+            claims
+        );
+    const signingInput =
+        `${encodedHeader}.${encodedPayload}`;
+    const signature =
+        signHs256(
+            signingInput,
+            secret
+        );
+
+    return `${signingInput}.${signature}`;
+}
+
+export async function verifySessionToken<
+    T extends object =
+        SessionPayload
+>(
+    token: string,
+    options:
+        SessionTokenOptions = {}
+): Promise<(
+    T & SessionClaims
+) | null> {
+    const secret =
+        resolveSessionSecret(
+            options.secret
+        );
+    const issuer =
+        resolveOptionalIssuer(
+            options.issuer
+        );
+    const audience =
+        options.audience ===
+        undefined
+            ? undefined
+            : normalizeAudience(
+                options.audience
+            );
+
+    try {
+        if (
+            typeof token !==
+                "string" ||
+            token.length === 0 ||
+            token.length >
+                MAX_TOKEN_LENGTH
+        ) {
+            return null;
+        }
+
+        const parts =
+            token.split(".");
+
+        if (
+            parts.length !==
+            3
+        ) {
+            return null;
+        }
+
+        const [
+            encodedHeader,
+            encodedPayload,
+            signature,
+        ] = parts;
+
+        const header =
+            decodeJson(
+                encodedHeader
+            ) as Record<
+                string,
+                unknown
+            >;
+
+        if (
+            header.alg !==
+                "HS256" ||
+            (
+                header.typ !==
+                    undefined &&
+                header.typ !==
+                    "JWT"
+            )
+        ) {
+            return null;
+        }
+
+        const signingInput =
+            `${encodedHeader}.${encodedPayload}`;
+        const expectedSignature =
+            signHs256(
+                signingInput,
+                secret
+            );
+
+        if (
+            !safeEqual(
+                signature,
+                expectedSignature
+            )
+        ) {
+            return null;
+        }
+
+        const claims =
+            decodeJson(
+                encodedPayload
+            ) as Record<
+                string,
+                unknown
+            >;
+        const now =
+            Math.floor(
+                Date.now() /
+                1000
+            );
+
+        if (
+            typeof claims.iat !==
+                "number" ||
+            !Number.isFinite(
+                claims.iat
+            ) ||
+            typeof claims.exp !==
+                "number" ||
+            !Number.isFinite(
+                claims.exp
+            ) ||
+            claims.exp <=
+                now
+        ) {
+            return null;
+        }
+
+        if (
+            claims.nbf !==
+            undefined
+        ) {
+            if (
+                typeof claims.nbf !==
+                    "number" ||
+                !Number.isFinite(
+                    claims.nbf
+                ) ||
+                claims.nbf >
+                    now
+            ) {
+                return null;
+            }
+        }
+
+        if (
+            issuer !==
+                undefined &&
+            claims.iss !==
+                issuer
+        ) {
+            return null;
+        }
+
+        if (
+            audience !==
+                undefined &&
+            !audienceMatches(
+                claims.aud,
+                audience
+            )
+        ) {
+            return null;
+        }
+
+        return claims as
+            T & SessionClaims;
+    } catch {
+        return null;
+    }
+}
+
+export async function createSession<
+    T extends object
+>(
+    payload: T,
+    options:
+        SessionCookieOptions = {}
+): Promise<string> {
+    const expiresIn =
+        resolveExpiresIn(
+            options.expiresIn
+        );
+    const token =
+        await createSessionToken(
+            payload,
+            {
+                secret:
+                    options.secret,
+                expiresIn,
+                issuer:
+                    options.issuer,
+                audience:
+                    options.audience,
+            }
+        );
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        resolveCookieName(
+            options.cookieName
+        ),
+        token,
+        {
+            httpOnly:
+                options.httpOnly ??
+                true,
+            secure:
+                options.secure ??
+                process.env.NODE_ENV ===
+                    "production",
+            sameSite:
+                options.sameSite ??
+                "lax",
+            path:
+                options.path ??
+                "/",
+            domain:
+                options.domain,
+            maxAge:
+                expiresIn,
+        }
+    );
+
+    return token;
+}
+
+export async function getSession<
+    T extends object =
+        SessionPayload
+>(
+    options:
+        SessionCookieOptions = {}
+): Promise<(
+    T & SessionClaims
+) | null> {
+    const cookieStore =
+        await cookies();
+    const token =
+        cookieStore.get(
+            resolveCookieName(
+                options.cookieName
+            )
+        )?.value;
+
+    if (!token) {
+        return null;
+    }
+
+    return verifySessionToken<
+        T
+    >(
+        token,
+        {
+            secret:
+                options.secret,
+            issuer:
+                options.issuer,
+            audience:
+                options.audience,
+        }
+    );
+}
+
+export async function destroySession(
+    options:
+        SessionCookieOptions = {}
+): Promise<void> {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.delete(
+        resolveCookieName(
+            options.cookieName
+        ),
+        {
+            path:
+                options.path ??
+                "/",
+            domain:
+                options.domain,
+        }
+    );
+}
+
+function resolveSessionSecret(
+    explicitSecret:
+        string | undefined
+): string {
+    const secret =
+        explicitSecret ??
+        process.env.BCP_SESSION_SECRET;
+
+    if (!secret) {
+        throw new Error(
+            "BCP Framework: BCP_SESSION_SECRET is required for session tokens."
+        );
+    }
+
+    if (
+        Buffer.byteLength(
+            secret,
+            "utf8"
+        ) <
+        MINIMUM_SECRET_BYTES
+    ) {
+        throw new Error(
+            `BCP Framework: session secret must be at least ${MINIMUM_SECRET_BYTES} bytes.`
+        );
+    }
+
+    return secret;
+}
+
+function resolveExpiresIn(
+    value:
+        number | undefined
+): number {
+    const expiresIn =
+        value ??
+        DEFAULT_EXPIRES_IN;
+
+    if (
+        !Number.isFinite(
+            expiresIn
+        ) ||
+        expiresIn <= 0
+    ) {
+        throw new Error(
+            "BCP Framework: session expiresIn must be a positive finite number of seconds."
+        );
+    }
+
+    return Math.floor(
+        expiresIn
+    );
+}
+
+function resolveCookieName(
+    value:
+        string | undefined
+): string {
+    const cookieName =
+        value ??
+        DEFAULT_COOKIE_NAME;
+
+    assertNonEmptyString(
+        cookieName,
+        "cookieName"
+    );
+
+    return cookieName;
+}
+
+function resolveOptionalIssuer(
+    value:
+        string | undefined
+): string | undefined {
+    if (
+        value ===
+        undefined
+    ) {
+        return undefined;
+    }
+
+    assertNonEmptyString(
+        value,
+        "issuer"
+    );
+
+    return value;
+}
+
+function assertPayload(
+    payload:
+        object
+): void {
+    if (
+        payload === null ||
+        typeof payload !==
+            "object" ||
+        Array.isArray(
+            payload
+        )
+    ) {
+        throw new Error(
+            "BCP Framework: session payload must be a plain object."
+        );
+    }
+}
+
+function assertNonEmptyString(
+    value: string,
+    label: string
+): void {
+    if (
+        typeof value !==
+            "string" ||
+        value.trim().length ===
+            0
+    ) {
+        throw new Error(
+            `BCP Framework: session ${label} must be a non-empty string.`
+        );
+    }
+}
+
+function normalizeAudience(
+    value:
+        string |
+        string[]
+): string | string[] {
+    if (
+        typeof value ===
+        "string"
+    ) {
+        assertNonEmptyString(
+            value,
+            "audience"
+        );
+        return value;
+    }
+
+    if (
+        !Array.isArray(
+            value
+        ) ||
+        value.length ===
+            0
+    ) {
+        throw new Error(
+            "BCP Framework: session audience must contain at least one value."
+        );
+    }
+
+    for (
+        const audience
+        of value
+    ) {
+        assertNonEmptyString(
+            audience,
+            "audience"
+        );
+    }
+
+    return [
+        ...value,
+    ];
+}
+
+function audienceMatches(
+    claim: unknown,
+    expected:
+        string |
+        string[]
+): boolean {
+    const expectedValues =
+        typeof expected ===
+            "string"
+            ? [
+                expected,
+            ]
+            : expected;
+    const claimValues =
+        typeof claim ===
+            "string"
+            ? [
+                claim,
+            ]
+            : Array.isArray(
+                claim
+            )
+                ? claim.filter(
+                    (
+                        value
+                    ): value is string =>
+                        typeof value ===
+                        "string"
+                )
+                : [];
+
+    return expectedValues.some(
+        (value) =>
+            claimValues.includes(
+                value
+            )
+    );
+}
+
+function encodeJson(
+    value: unknown
+): string {
+    return Buffer.from(
+        JSON.stringify(
+            value
+        ),
+        "utf8"
+    ).toString(
+        "base64url"
+    );
+}
+
+function decodeJson(
+    value: string
+): unknown {
+    const decoded =
+        Buffer.from(
+            value,
+            "base64url"
+        ).toString(
+            "utf8"
+        );
+
+    return JSON.parse(
+        decoded
+    );
+}
+
+function signHs256(
+    signingInput: string,
+    secret: string
+): string {
+    return createHmac(
+        "sha256",
+        secret
+    )
+        .update(
+            signingInput,
+            "utf8"
+        )
+        .digest(
+            "base64url"
+        );
+}
+
+function safeEqual(
+    actual: string,
+    expected: string
+): boolean {
+    const actualBuffer =
+        Buffer.from(
+            actual,
+            "base64url"
+        );
+    const expectedBuffer =
+        Buffer.from(
+            expected,
+            "base64url"
+        );
+
+    return (
+        actualBuffer.length ===
+            expectedBuffer.length &&
+        timingSafeEqual(
+            actualBuffer,
+            expectedBuffer
+        )
+    );
+}