auth-vir 0.0.0 → 0.0.1

package/package.json

@@ -1,13 +1,68 @@
 {
-  "name": "auth-vir",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "MIT",
-  "type": "commonjs"
+    "name": "auth-vir",
+    "version": "0.0.1",
+    "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
+    "keywords": [
+        "auth",
+        "jwt",
+        "csrf",
+        "hash",
+        "password",
+        "secure",
+        "cookie"
+    ],
+    "homepage": "https://github.com/electrovir/auth-vir",
+    "bugs": {
+        "url": "https://github.com/electrovir/auth-vir/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/electrovir/auth-vir.git"
+    },
+    "license": "(MIT or CC0 1.0)",
+    "author": {
+        "name": "electrovir",
+        "url": "https://github.com/electrovir"
+    },
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "bin": "",
+    "scripts": {
+        "build": "virmator frontend build",
+        "compile": "virmator compile",
+        "docs": "virmator docs",
+        "start": "virmator frontend",
+        "test": "virmator test web",
+        "test:coverage": "npm run test coverage",
+        "test:docs": "virmator docs check",
+        "test:update": "npm test update"
+    },
+    "dependencies": {
+        "@augment-vir/assert": "^31.11.0",
+        "@augment-vir/common": "^31.11.0",
+        "date-vir": "^7.3.1",
+        "hash-wasm": "^4.12.0",
+        "jose": "^6.0.10",
+        "object-shape-tester": "^5.1.5",
+        "url-vir": "^2.1.3"
+    },
+    "devDependencies": {
+        "@augment-vir/test": "^31.11.0",
+        "@web/dev-server-esbuild": "^1.0.4",
+        "@web/test-runner": "^0.20.1",
+        "@web/test-runner-commands": "^0.9.0",
+        "@web/test-runner-playwright": "^0.11.0",
+        "@web/test-runner-visual-regression": "^0.10.0",
+        "istanbul-smart-text-reporter": "^1.1.5",
+        "markdown-code-example-inserter": "^3.0.3",
+        "typedoc": "^0.28.2"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
 }

package/src/auth.ts

@@ -0,0 +1,168 @@
+import {CookieParams, extractCookieJwt, generateCookie} from './cookie.js';
+import {csrfTokenHeaderName, generateCsrfToken} from './csrf-token.js';
+import {ParseJwtParams} from './jwt.js';
+
+/**
+ * All possible headers container types supported by {@link extractUserIdFromRequestHeaders}.
+ *
+ * @category Internal
+ */
+export type HeaderContainer = Record<string, string[] | undefined | string | number> | Headers;
+
+function readHeader(headers: HeaderContainer, headerName: string): string | undefined {
+    if (headers instanceof Headers) {
+        return headers.get(headerName) || undefined;
+    } else {
+        const value = headers[headerName];
+
+        if (value == undefined) {
+            return undefined;
+        } else if (Array.isArray(value)) {
+            return value[0];
+        } else {
+            return String(value);
+        }
+    }
+}
+
+/**
+ * Extract the user id from a request by checking both the request cookie and CSRF token. This is
+ * used by host (backend) code to help verify a request. After extracting the user id using this,
+ * you should compare it to users stored in your database.
+ *
+ * @category Auth : Host
+ * @returns The extracted user id or `undefined` if no valid auth headers exist.
+ */
+export async function extractUserIdFromRequestHeaders(
+    headers: HeaderContainer,
+    jwtParams: Readonly<ParseJwtParams>,
+): Promise<string | undefined> {
+    try {
+        const csrfToken = readHeader(headers, csrfTokenHeaderName);
+        const cookie = readHeader(headers, 'cookie');
+
+        if (!cookie || !csrfToken) {
+            return undefined;
+        }
+
+        const jwt = await extractCookieJwt(cookie, jwtParams);
+
+        if (!jwt || jwt.csrfToken !== csrfToken) {
+            return undefined;
+        }
+
+        return jwt.userId;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Used by host (backend) code to set headers on a response object.
+ *
+ * @category Auth : Host
+ */
+export async function generateSuccessfulLoginHeaders(
+    userId: string,
+    /** The id from your database of the user you're authenticating. */
+    cookieConfig: Readonly<CookieParams>,
+) {
+    const csrfToken = generateCsrfToken();
+
+    return {
+        'set-cookie': await generateCookie(
+            {
+                csrfToken,
+                userId,
+            },
+            cookieConfig,
+        ),
+        [csrfTokenHeaderName]: csrfToken,
+    };
+}
+
+/**
+ * Store auth data on a client (frontend) after receiving an auth response from the host (backend).
+ * Specifically, this stores the CSRF token into local storage (which doesn't need to be a secret).
+ * Alternatively, if the given response failed, this will wipe the existing (if anyone) stored CSRF
+ * token.
+ *
+ * @category Auth : Client
+ * @throws Error if no CSRF token header is found.
+ */
+export function handleAuthResponse(
+    response: Readonly<Pick<Response, 'ok' | 'headers'>>,
+    overrides: {
+        /**
+         * Allows mocking or overriding the global `localStorage`.
+         *
+         * @default globalThis.localStorage
+         */
+        localStorage?: Pick<Storage, 'setItem' | 'removeItem'>;
+        /** Override the default CSRF token header name. */
+        csrfHeaderName?: string;
+    } = {},
+) {
+    if (!response.ok) {
+        wipeCurrentCsrfToken(overrides);
+        return;
+    }
+    const headerName = overrides.csrfHeaderName || csrfTokenHeaderName;
+
+    const csrfToken = response.headers.get(headerName);
+
+    if (!csrfToken) {
+        wipeCurrentCsrfToken(overrides);
+        throw new Error('Did not receive any CSRF token.');
+    }
+
+    (overrides.localStorage || globalThis.localStorage).setItem(headerName, csrfToken);
+}
+
+/**
+ * Used in client (frontend) code to retrieve the current CSRF token in order to send it with
+ * requests to the host (backend).
+ *
+ * @category Auth : Client
+ */
+export function getCurrentCsrfToken(
+    overrides: {
+        /**
+         * Allows mocking or overriding the global `localStorage`.
+         *
+         * @default globalThis.localStorage
+         */
+        localStorage?: Pick<Storage, 'getItem'>;
+        /** Override the default CSRF token header name. */
+        csrfHeaderName?: string;
+    } = {},
+): string | undefined {
+    return (
+        (overrides.localStorage || globalThis.localStorage).getItem(
+            overrides.csrfHeaderName || csrfTokenHeaderName,
+        ) || undefined
+    );
+}
+
+/**
+ * Wipes the current stored CSRF token. This should be used by client (frontend) code to logout a
+ * user or react to a session timeout.
+ *
+ * @category Auth : Client
+ */
+export function wipeCurrentCsrfToken(
+    overrides: {
+        /**
+         * Allows mocking or overriding the global `localStorage`.
+         *
+         * @default globalThis.localStorage
+         */
+        localStorage?: Pick<Storage, 'removeItem'>;
+        /** Override the default CSRF token header name. */
+        csrfHeaderName?: string;
+    } = {},
+) {
+    return (overrides.localStorage || globalThis.localStorage).removeItem(
+        overrides.csrfHeaderName || csrfTokenHeaderName,
+    );
+}

package/src/cookie.ts

@@ -0,0 +1,85 @@
+import {check} from '@augment-vir/assert';
+import {safeMatch, type PartialWithUndefined} from '@augment-vir/common';
+import {convertDuration, type AnyDuration} from 'date-vir';
+import {parseUrl} from 'url-vir';
+import {CreateJwtParams, type ParseJwtParams} from './jwt.js';
+import {createUserJwt, parseUserJwt, UserJwtData} from './user-jwt.js';
+
+/**
+ * Parameters for {@link generateCookie}.
+ *
+ * @category Internal
+ */
+export type CookieParams = {
+    /**
+     * The origin of the host (backend) service that cookies will be included in all requests to.
+     * This should be restricted to just your host (backend) origin for security purposes.
+     *
+     * @example 'https://www.example.com'
+     */
+    hostOrigin: string;
+    /**
+     * The max duration of this cookie. Or, in other words, the max user session duration before
+     * they're logged out.
+     */
+    cookieDuration: AnyDuration;
+    /**
+     * All JWT parameters required for generating the encrypted JWT that will be embedded in the
+     * Cookie. Note that all JWT keys contained herein should never shared with any frontend,
+     * client, etc.
+     */
+    jwtParams: Readonly<CreateJwtParams>;
+} & PartialWithUndefined<{
+    /**
+     * Is set to `true` (which should only be done in development environments), the cookie will be
+     * allowed in insecure requests (non HTTPS requests).
+     *
+     * @default false
+     */
+    isDev: boolean;
+}>;
+
+/**
+ * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
+ *
+ * @category Internal
+ */
+export async function generateCookie(
+    userJwtData: Readonly<UserJwtData>,
+    cookieConfig: Readonly<CookieParams>,
+) {
+    return [
+        `auth=${await createUserJwt(userJwtData, cookieConfig.jwtParams)}`,
+        `Domain=${parseUrl(cookieConfig.hostOrigin).hostname}`,
+        'HttpOnly',
+        'Path=/',
+        'SameSite=Strict',
+        `MAX-AGE=${convertDuration(cookieConfig.cookieDuration, {seconds: true}).seconds}`,
+        cookieConfig.isDev ? '' : 'Secure',
+    ]
+        .filter(check.isTruthy)
+        .join('; ');
+}
+
+/**
+ * Extract an auth cookie from a cookie string. Used in host (backend) code.
+ *
+ * @category Internal
+ * @returns The extracted auth Cookie JWT data or `undefined` if no valid auth JWT data was found.
+ */
+export async function extractCookieJwt(
+    rawCookie: string,
+    jwtParams: Readonly<ParseJwtParams>,
+): Promise<undefined | UserJwtData> {
+    const [auth] = safeMatch(rawCookie, /auth=[^;]+(?:;|$)/);
+
+    if (!auth) {
+        return undefined;
+    }
+
+    const rawJwt = auth.replace('auth=', '').replace(';', '');
+
+    const jwt = await parseUserJwt(rawJwt, jwtParams);
+
+    return jwt;
+}

package/src/csrf-token.ts

@@ -0,0 +1,17 @@
+import {randomString} from '@augment-vir/common';
+
+/**
+ * Name of the header attached to responses that stores the CSRF token value.
+ *
+ * @category Internal
+ */
+export const csrfTokenHeaderName = 'csrf-token';
+
+/**
+ * Generates a random, cryptographically secure CSRF token.
+ *
+ * @category Internal
+ */
+export function generateCsrfToken(): string {
+    return randomString(256);
+}

package/src/hash.ts

@@ -0,0 +1,65 @@
+import {bcrypt, bcryptVerify} from 'hash-wasm';
+
+/**
+ * Hashes a password using the bcrypt algorithm so passwords don't need to be stored in plain text.
+ * The output of this function is safe to store in a database for future credential comparisons.
+ *
+ * @category Auth : Host
+ * @returns `undefined` if the password is too long (and would be truncated by the bcrypt hashing
+ *   algorithm). Otherwise, the hashed output.
+ * @see https://wikipedia.org/wiki/Bcrypt
+ */
+export async function hashPassword(password: string): Promise<undefined | string> {
+    if (willHashTruncate(password)) {
+        return undefined;
+    }
+
+    const salt = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(salt);
+
+    return await bcrypt({
+        costFactor: 10,
+        password: password.normalize(),
+        salt,
+    });
+}
+
+/**
+ * Checks if the given string will be truncated when passed through {@link hashPassword}. Passwords
+ * longer than this should not be accepted.
+ *
+ * @category Internal
+ */
+export function willHashTruncate(input: string): boolean {
+    return getByteLength(input) > 72;
+}
+
+/**
+ * A utility that provides more accurate string byte size than doing `string.length`.
+ *
+ * @category Internal
+ */
+export function getByteLength(input: string): number {
+    return new Blob([input]).size;
+}
+
+/**
+ * Checks if the given password is a match by comparing it to its previously computed and stored
+ * hash.
+ *
+ * @category Auth : Host
+ */
+export async function doesPasswordMatchHash({
+    password,
+    hash,
+}: {
+    /** The password entered by the user in their login attempt. */
+    password: string;
+    /** The stored password hash for that user. */
+    hash: string;
+}): Promise<boolean> {
+    return await bcryptVerify({
+        hash,
+        password,
+    });
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './auth.js';
+export * from './cookie.js';
+export * from './csrf-token.js';
+export * from './hash.js';
+export * from './jwt-keys.js';
+export * from './jwt.js';
+export * from './mock-local-storage.js';
+export * from './user-jwt.js';

package/src/jwt-keys.script.ts

@@ -0,0 +1,3 @@
+import {generateNewJwtKeys} from './jwt-keys.js';
+
+console.info(await generateNewJwtKeys());

package/src/jwt-keys.ts

@@ -0,0 +1,111 @@
+import {assertWrap} from '@augment-vir/assert';
+import {base64url} from 'jose';
+
+/**
+ * The keys required to sign and encrypt the JWT in their raw form for storage in a secure secrets
+ * database (such as AWS Secrets Manager) for later parsing by {@link parseJwtKeys}.
+ *
+ * These keys should be kept secret and never shared with any frontend, client, etc.
+ *
+ * @category Internal
+ */
+export type RawJwtKeys = Readonly<{
+    encryptionKey: string;
+    signingKey: string;
+}>;
+
+/**
+ * The keys required to sign and encrypt the JWT.
+ *
+ * These keys should be kept secret and never shared with any frontend, client, etc.
+ *
+ * @category Internal
+ */
+export type JwtKeys = Readonly<{
+    /**
+     * Encryption key for JWTs. This is a Uint8Array because `EncryptJWT.encrypt` does not support
+     * `CryptoKey` for our chosen encryption algorithm.
+     */
+    encryptionKey: Readonly<Uint8Array>;
+    /** Signing key for JWTs. */
+    signingKey: Readonly<CryptoKey>;
+}>;
+
+const signingKeyOptions: [HmacKeyGenParams, boolean, ReadonlyArray<KeyUsage>] = [
+    {
+        name: 'HMAC',
+        hash: 'SHA-512',
+    },
+    true,
+    [
+        'sign',
+        'verify',
+    ],
+];
+
+/**
+ * Generate fresh and serialized JWT signing and encryption keys. These should be stored in a secure
+ * secrets database (such as AWS Secrets Manager) for later parsing by {@link parseJwtKeys}.
+ *
+ * These keys should be kept secret and never shared with any frontend, client, etc.
+ *
+ * @category Keys
+ */
+export async function generateNewJwtKeys(): Promise<RawJwtKeys> {
+    return {
+        encryptionKey: assertWrap.isDefined(
+            (
+                await globalThis.crypto.subtle.exportKey(
+                    'jwk',
+                    await globalThis.crypto.subtle.generateKey(
+                        {
+                            name: 'AES-GCM',
+                            length: 256,
+                        },
+                        true,
+                        [
+                            'encrypt',
+                            'decrypt',
+                        ],
+                    ),
+                )
+            ).k,
+        ),
+        signingKey: assertWrap.isDefined(
+            (
+                await globalThis.crypto.subtle.exportKey(
+                    'jwk',
+                    await globalThis.crypto.subtle.generateKey(...signingKeyOptions),
+                )
+            ).k,
+        ),
+    };
+}
+
+/**
+ * Parses an instance of {@link RawJwtKeys} and produces the final {@link JwtKeys} object required by
+ * all authentication functionality.
+ *
+ * @category Keys
+ */
+export async function parseJwtKeys(rawKeys: Readonly<RawJwtKeys>): Promise<Readonly<JwtKeys>> {
+    if (!rawKeys.encryptionKey) {
+        throw new Error('JWT encryption key is empty');
+    } else if (!rawKeys.signingKey) {
+        throw new Error('JWT signing key is empty');
+    }
+    return {
+        encryptionKey: base64url.decode(rawKeys.encryptionKey),
+        signingKey: await crypto.subtle.importKey(
+            'jwk',
+            {
+                k: rawKeys.signingKey,
+                alg: 'HS512',
+                ext: signingKeyOptions[1],
+                key_ops: [...signingKeyOptions[2]],
+                kty: 'oct',
+            },
+            ...signingKeyOptions,
+        ),
+    };
+}