auth-vir 0.0.0 → 0.0.1

package/dist/cookie.d.ts

@@ -0,0 +1,50 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type AnyDuration } from 'date-vir';
+import { CreateJwtParams, type ParseJwtParams } from './jwt.js';
+import { 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 declare function generateCookie(userJwtData: Readonly<UserJwtData>, cookieConfig: Readonly<CookieParams>): Promise<string>;
+/**
+ * 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 declare function extractCookieJwt(rawCookie: string, jwtParams: Readonly<ParseJwtParams>): Promise<undefined | UserJwtData>;

package/dist/cookie.js

@@ -0,0 +1,38 @@
+import { check } from '@augment-vir/assert';
+import { safeMatch } from '@augment-vir/common';
+import { convertDuration } from 'date-vir';
+import { parseUrl } from 'url-vir';
+import { createUserJwt, parseUserJwt } from './user-jwt.js';
+/**
+ * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
+ *
+ * @category Internal
+ */
+export async function generateCookie(userJwtData, cookieConfig) {
+    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, jwtParams) {
+    const [auth] = safeMatch(rawCookie, /auth=[^;]+(?:;|$)/);
+    if (!auth) {
+        return undefined;
+    }
+    const rawJwt = auth.replace('auth=', '').replace(';', '');
+    const jwt = await parseUserJwt(rawJwt, jwtParams);
+    return jwt;
+}

package/dist/csrf-token.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Name of the header attached to responses that stores the CSRF token value.
+ *
+ * @category Internal
+ */
+export declare const csrfTokenHeaderName = "csrf-token";
+/**
+ * Generates a random, cryptographically secure CSRF token.
+ *
+ * @category Internal
+ */
+export declare function generateCsrfToken(): string;

package/dist/csrf-token.js

@@ -0,0 +1,15 @@
+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() {
+    return randomString(256);
+}

package/dist/hash.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare function hashPassword(password: string): Promise<undefined | string>;
+/**
+ * Checks if the given string will be truncated when passed through {@link hashPassword}. Passwords
+ * longer than this should not be accepted.
+ *
+ * @category Internal
+ */
+export declare function willHashTruncate(input: string): boolean;
+/**
+ * A utility that provides more accurate string byte size than doing `string.length`.
+ *
+ * @category Internal
+ */
+export declare function getByteLength(input: string): number;
+/**
+ * Checks if the given password is a match by comparing it to its previously computed and stored
+ * hash.
+ *
+ * @category Auth : Host
+ */
+export declare 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>;

package/dist/hash.js

@@ -0,0 +1,51 @@
+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) {
+    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) {
+    return getByteLength(input) > 72;
+}
+/**
+ * A utility that provides more accurate string byte size than doing `string.length`.
+ *
+ * @category Internal
+ */
+export function getByteLength(input) {
+    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, }) {
+    return await bcryptVerify({
+        hash,
+        password,
+    });
+}

package/dist/index.d.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/dist/index.js

@@ -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/dist/jwt-keys.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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>;
+}>;
+/**
+ * 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 declare function generateNewJwtKeys(): Promise<RawJwtKeys>;
+/**
+ * Parses an instance of {@link RawJwtKeys} and produces the final {@link JwtKeys} object required by
+ * all authentication functionality.
+ *
+ * @category Keys
+ */
+export declare function parseJwtKeys(rawKeys: Readonly<RawJwtKeys>): Promise<Readonly<JwtKeys>>;

package/dist/jwt-keys.js

@@ -0,0 +1,57 @@
+import { assertWrap } from '@augment-vir/assert';
+import { base64url } from 'jose';
+const signingKeyOptions = [
+    {
+        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() {
+    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) {
+    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),
+    };
+}

package/dist/jwt-keys.script.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/jwt-keys.script.js

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

package/dist/jwt.d.ts

@@ -0,0 +1,83 @@
+import type { AnyObject, PartialWithUndefined } from '@augment-vir/common';
+import { type AnyDuration, type DateLike } from 'date-vir';
+import { JwtKeys } from './jwt-keys.js';
+/**
+ * Params for {@link createJwt}.
+ *
+ * @category Internal
+ */
+export type CreateJwtParams = Readonly<{
+    /**
+     * The keys required to sign and encrypt the JWT.
+     *
+     * These keys should be kept secret and never shared with any frontend, client, etc.
+     */
+    jwtKeys: Readonly<JwtKeys>;
+    /**
+     * The name of the company, the name of the service, or the URL to the service that originally
+     * issued the JWT. The same value must be used when creating and parsing a JWT or the parse will
+     * fail.
+     *
+     * This name can be anything you want.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1
+     */
+    issuer: string;
+    /**
+     * The arbitrary name or URL of the client intended to consume the JWT. The host and client must
+     * both know this name in order for the token to be signed and read correctly.
+     *
+     * This name can be anything you want.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3
+     */
+    audience: string;
+    /**
+     * The duration until the JWT expires.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4
+     */
+    jwtDuration: Readonly<AnyDuration>;
+}> & Readonly<PartialWithUndefined<{
+    /**
+     * Set a custom issued at date.
+     *
+     * This should usually not be overridden.
+     *
+     * @default Date.now()
+     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6
+     */
+    issuedAt: DateLike;
+    /**
+     * Set a custom date for when the JWT will become valid. The JWT will be considered
+     * invalid and not be processed until this date.
+     *
+     * This should usually not be overridden.
+     *
+     * @default
+     * none, the JWT will be immediately valid
+     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5
+     */
+    notValidUntil: DateLike;
+}>>;
+/**
+ * Creates a signed and encrypted JWT that contains the given data.
+ *
+ * @category Internal
+ */
+export declare function createJwt<JwtData extends AnyObject = AnyObject>(
+/** The data to be included in the JWT. */
+data: JwtData, params: Readonly<CreateJwtParams>): Promise<string>;
+/**
+ * Params for {@link parseJwt}.
+ *
+ * @category Internal
+ */
+export type ParseJwtParams = Readonly<Pick<CreateJwtParams, 'issuer' | 'audience' | 'jwtKeys'>>;
+/**
+ * Parse and extract all data from an encrypted and signed JWT.
+ *
+ * @category Internal
+ * @throws Errors if the decryption, signature verification, or other JWT requirements fail
+ */
+export declare function parseJwt<JwtData extends AnyObject = AnyObject>(encryptedJwt: string, params: Readonly<ParseJwtParams>): Promise<JwtData>;

package/dist/jwt.js

@@ -0,0 +1,61 @@
+import { check } from '@augment-vir/assert';
+import { calculateRelativeDate, createFullDateInUserTimezone, getNowInUtcTimezone, toTimestamp, } from 'date-vir';
+import { EncryptJWT, jwtDecrypt, jwtVerify, SignJWT } from 'jose';
+const encryptionProtectedHeader = { alg: 'dir', enc: 'A256GCM' };
+const signingProtectedHeader = { alg: 'HS512' };
+/**
+ * Creates a signed and encrypted JWT that contains the given data.
+ *
+ * @category Internal
+ */
+export async function createJwt(
+/** The data to be included in the JWT. */
+data, params) {
+    const rawJwt = new SignJWT({ data: data })
+        .setProtectedHeader(signingProtectedHeader)
+        .setIssuedAt(params.issuedAt
+        ? toTimestamp(createFullDateInUserTimezone(params.issuedAt))
+        : undefined)
+        .setIssuer(params.issuer)
+        .setAudience(params.audience)
+        .setExpirationTime(toTimestamp(calculateRelativeDate(getNowInUtcTimezone(), params.jwtDuration)));
+    if (params.notValidUntil) {
+        rawJwt.setNotBefore(toTimestamp(createFullDateInUserTimezone(params.notValidUntil)));
+    }
+    const signedJwt = await rawJwt.sign(params.jwtKeys.signingKey);
+    return await new EncryptJWT({ jwt: signedJwt })
+        .setProtectedHeader(encryptionProtectedHeader)
+        .encrypt(params.jwtKeys.encryptionKey);
+}
+/**
+ * Parse and extract all data from an encrypted and signed JWT.
+ *
+ * @category Internal
+ * @throws Errors if the decryption, signature verification, or other JWT requirements fail
+ */
+export async function parseJwt(encryptedJwt, params) {
+    const decryptedJwt = await jwtDecrypt(encryptedJwt, params.jwtKeys.encryptionKey);
+    if (!check.deepEquals(decryptedJwt.protectedHeader, encryptionProtectedHeader)) {
+        throw new Error('Invalid encryption protected header.');
+    }
+    else if (!check.isString(decryptedJwt.payload.jwt)) {
+        throw new TypeError('Decrypted jwt is not a string.');
+    }
+    const verifiedJwt = await jwtVerify(decryptedJwt.payload.jwt, params.jwtKeys.signingKey, {
+        issuer: params.issuer,
+        audience: params.audience,
+        requiredClaims: [
+            'iat',
+            'aud',
+            'iss',
+        ],
+    });
+    if (!verifiedJwt.payload.iat || verifiedJwt.payload.iat * 1000 > Date.now()) {
+        throw new Error('"iat" claim timestamp check failed');
+    }
+    const data = verifiedJwt.payload.data;
+    if (!check.deepEquals(verifiedJwt.protectedHeader, signingProtectedHeader)) {
+        throw new Error('Invalid signing protected header.');
+    }
+    return data;
+}

package/dist/mock-local-storage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `accessRecord` type for {@link createMockLocalStorage}'s output.
+ *
+ * @category Internal
+ */
+export type MockLocalStorageAccessRecord = {
+    getItem: string[];
+    removeItem: string[];
+    setItem: {
+        key: string;
+        value: string;
+    }[];
+    key: number[];
+};
+/**
+ * Create an empty `accessRecord` object, this is to be used in conjunction with
+ * {@link createMockLocalStorage}.
+ *
+ * @category Mock
+ */
+export declare function createEmptyMockLocalStorageAccessRecord(): MockLocalStorageAccessRecord;
+/**
+ * Create a LocalStorage mock.
+ *
+ * @category Mock
+ */
+export declare function createMockLocalStorage(
+/** Set values in here to initialize the mocked localStorage data store contents. */
+init?: Record<string, string>): {
+    localStorage: Storage;
+    store: Record<string, string>;
+    accessRecord: MockLocalStorageAccessRecord;
+};

package/dist/mock-local-storage.js

@@ -0,0 +1,56 @@
+/**
+ * Create an empty `accessRecord` object, this is to be used in conjunction with
+ * {@link createMockLocalStorage}.
+ *
+ * @category Mock
+ */
+export function createEmptyMockLocalStorageAccessRecord() {
+    return {
+        getItem: [],
+        removeItem: [],
+        setItem: [],
+        key: [],
+    };
+}
+/**
+ * Create a LocalStorage mock.
+ *
+ * @category Mock
+ */
+export function createMockLocalStorage(
+/** Set values in here to initialize the mocked localStorage data store contents. */
+init = {}) {
+    const store = init;
+    const accessRecord = createEmptyMockLocalStorageAccessRecord();
+    const mockLocalStorage = {
+        clear() {
+            Object.keys(store).forEach((key) => {
+                delete store[key];
+            });
+        },
+        getItem(key) {
+            accessRecord.getItem.push(key);
+            return store[key] ?? null;
+        },
+        get length() {
+            return Object.keys(store).length;
+        },
+        key(index) {
+            accessRecord.key.push(index);
+            return Object.keys(store)[index] ?? null;
+        },
+        removeItem(key) {
+            accessRecord.removeItem.push(key);
+            delete store[key];
+        },
+        setItem(key, value) {
+            accessRecord.setItem.push({ key, value });
+            store[key] = value;
+        },
+    };
+    return {
+        localStorage: mockLocalStorage,
+        store,
+        accessRecord,
+    };
+}

package/dist/user-jwt.d.ts

@@ -0,0 +1,38 @@
+import { CreateJwtParams, ParseJwtParams } from './jwt.js';
+/**
+ * Shape definition and source of truth for {@link UserJwtData}.
+ *
+ * @category Internal
+ */
+export declare const userJwtDataShape: import("object-shape-tester").ShapeDefinition<{
+    /** The id from your database of the user you're authenticating. */
+    userId: string;
+    /**
+     * CSRF token. This can be any cryptographically secure randomized string.
+     *
+     * Consider using {@link generateCsrfToken} to generate this.
+     */
+    csrfToken: string;
+}, false>;
+/**
+ * Data required for user JWTs.
+ *
+ * @category Internal
+ */
+export type UserJwtData = typeof userJwtDataShape.runtimeType;
+/**
+ * Creates a new signed and encrypted {@link UserJwtData} when a client (frontend) successfully
+ * authenticates with the host (backend). This is used by host (backend) code to establish a new
+ * user session. The output of this function should be sent to the client (frontend) for storage.
+ *
+ * @category Internal
+ */
+export declare function createUserJwt(data: Readonly<UserJwtData>, params: Readonly<CreateJwtParams>): Promise<string>;
+/**
+ * Parses a {@link UserJwtData} generated from {@link createUserJwt}. This should be used on the host
+ * (backend) to a client (frontend) request. Do not use this function in client (frontend) code: it
+ * requires JWT signing keys which should not be shared with any client (frontend).
+ *
+ * @category Internal
+ */
+export declare function parseUserJwt(encryptedJwt: string, params: Readonly<ParseJwtParams>): Promise<UserJwtData | undefined>;

package/dist/user-jwt.js

@@ -0,0 +1,41 @@
+import { defineShape, isValidShape } from 'object-shape-tester';
+import { createJwt, parseJwt } from './jwt.js';
+/**
+ * Shape definition and source of truth for {@link UserJwtData}.
+ *
+ * @category Internal
+ */
+export const userJwtDataShape = defineShape({
+    /** The id from your database of the user you're authenticating. */
+    userId: '',
+    /**
+     * CSRF token. This can be any cryptographically secure randomized string.
+     *
+     * Consider using {@link generateCsrfToken} to generate this.
+     */
+    csrfToken: '',
+});
+/**
+ * Creates a new signed and encrypted {@link UserJwtData} when a client (frontend) successfully
+ * authenticates with the host (backend). This is used by host (backend) code to establish a new
+ * user session. The output of this function should be sent to the client (frontend) for storage.
+ *
+ * @category Internal
+ */
+export async function createUserJwt(data, params) {
+    return await createJwt(data, params);
+}
+/**
+ * Parses a {@link UserJwtData} generated from {@link createUserJwt}. This should be used on the host
+ * (backend) to a client (frontend) request. Do not use this function in client (frontend) code: it
+ * requires JWT signing keys which should not be shared with any client (frontend).
+ *
+ * @category Internal
+ */
+export async function parseUserJwt(encryptedJwt, params) {
+    const parsed = await parseJwt(encryptedJwt, params);
+    if (!isValidShape(parsed, userJwtDataShape)) {
+        throw new TypeError('Verified jwt has wrong data.');
+    }
+    return parsed;
+}