@mulverse/mulguard-core 1.0.0

package/index.js

@@ -0,0 +1,142 @@
+/**
+ *
+ * :::warning Experimental
+ * `@mulverse/mulguard-core` is under active development.
+ * :::
+ *
+ * This is the main entry point to the MulGuard library.
+ *
+ * Based on the {@link https://developer.mozilla.org/en-US/docs/Web/API/Request Request}
+ * and {@link https://developer.mozilla.org/en-US/docs/Web/API/Response Response} Web standard APIs.
+ * Primarily used to implement framework-specific packages,
+ * but it can also be used directly.
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn
+ * npm install @mulverse/mulguard-core
+ * ```
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { Auth } from "@mulverse/mulguard-core"
+ *
+ * const request = new Request("https://example.com")
+ * const response = await Auth(request, {...})
+ *
+ * console.log(response instanceof Response) // true
+ * ```
+ *
+ * ## Resources
+ *
+ * - [Getting started](https://authjs.dev/getting-started)
+ * - [Guides](https://authjs.dev/guides)
+ *
+ * @module @mulverse/mulguard-core
+ */
+import { assertConfig } from "./lib/utils/assert.js";
+import { AuthError, CredentialsSignin, ErrorPageLoop, isClientError, } from "./errors.js";
+import { AuthInternal, raw, skipCSRFCheck } from "./lib/index.js";
+import { setEnvDefaults, createActionURL } from "./lib/utils/env.js";
+import renderPage from "./lib/pages/index.js";
+import { setLogger } from "./lib/utils/logger.js";
+import { toInternalRequest, toResponse } from "./lib/utils/web.js";
+import { isAuthAction } from "./lib/utils/actions.js";
+export { customFetch } from "./lib/symbols.js";
+export { skipCSRFCheck, raw, setEnvDefaults, createActionURL, isAuthAction };
+/**
+ * Core functionality provided by Auth.js.
+ *
+ * Receives a standard {@link Request} and returns a {@link Response}.
+ *
+ * @example
+ * ```ts
+ * import { Auth } from "@mulverse/mulguard-core"
+ *
+ * const request = new Request("https://example.com")
+ * const response = await Auth(request, {
+ *   providers: [Google],
+ *   secret: "...",
+ *   trustHost: true,
+ * })
+ *```
+ * @see [Documentation](https://authjs.dev)
+ */
+export async function Auth(request, config) {
+    const logger = setLogger(config);
+    const internalRequest = await toInternalRequest(request, config);
+    // There was an error parsing the request
+    if (!internalRequest)
+        return Response.json(`Bad request.`, { status: 400 });
+    const warningsOrError = assertConfig(internalRequest, config);
+    if (Array.isArray(warningsOrError)) {
+        warningsOrError.forEach(logger.warn);
+    }
+    else if (warningsOrError) {
+        // If there's an error in the user config, bail out early
+        logger.error(warningsOrError);
+        const htmlPages = new Set([
+            "signin",
+            "signout",
+            "error",
+            "verify-request",
+        ]);
+        if (!htmlPages.has(internalRequest.action) ||
+            internalRequest.method !== "GET") {
+            const message = "There was a problem with the server configuration. Check the server logs for more information.";
+            return Response.json({ message }, { status: 500 });
+        }
+        const { pages, theme } = config;
+        // If this is true, the config required auth on the error page
+        // which could cause a redirect loop
+        const authOnErrorPage = pages?.error &&
+            internalRequest.url.searchParams
+                .get("callbackUrl")
+                ?.startsWith(pages.error);
+        // Either there was no error page configured or the configured one contains infinite redirects
+        if (!pages?.error || authOnErrorPage) {
+            if (authOnErrorPage) {
+                logger.error(new ErrorPageLoop(`The error page ${pages?.error} should not require authentication`));
+            }
+            const page = renderPage({ theme }).error("Configuration");
+            return toResponse(page);
+        }
+        const url = `${internalRequest.url.origin}${pages.error}?error=Configuration`;
+        return Response.redirect(url);
+    }
+    const isRedirect = request.headers?.has("X-Auth-Return-Redirect");
+    const isRaw = config.raw === raw;
+    try {
+        const internalResponse = await AuthInternal(internalRequest, config);
+        if (isRaw)
+            return internalResponse;
+        const response = toResponse(internalResponse);
+        const url = response.headers.get("Location");
+        if (!isRedirect || !url)
+            return response;
+        return Response.json({ url }, { headers: response.headers });
+    }
+    catch (e) {
+        const error = e;
+        logger.error(error);
+        const isAuthError = error instanceof AuthError;
+        if (isAuthError && isRaw && !isRedirect)
+            throw error;
+        // If the CSRF check failed for POST/session, return a 400 status code.
+        // We should not redirect to a page as this is an API route
+        if (request.method === "POST" && internalRequest.action === "session")
+            return Response.json(null, { status: 400 });
+        const isClientSafeErrorType = isClientError(error);
+        const type = isClientSafeErrorType ? error.type : "Configuration";
+        const params = new URLSearchParams({ error: type });
+        if (error instanceof CredentialsSignin)
+            params.set("code", error.code);
+        const pageKind = (isAuthError && error.kind) || "error";
+        const pagePath = config.pages?.[pageKind] ?? `${config.basePath}/${pageKind.toLowerCase()}`;
+        const url = `${internalRequest.url.origin}${pagePath}?${params}`;
+        if (isRedirect)
+            return Response.json({ url });
+        return Response.redirect(url);
+    }
+}

package/jwt.d.ts

@@ -0,0 +1,132 @@
+/**
+ *
+ *
+ * This module contains functions and types
+ * to encode and decode {@link https://authjs.dev/concepts/session-strategies#jwt-session JWT}s
+ * issued and used by Auth.js.
+ *
+ * The JWT issued by Auth.js is _encrypted by default_, using the _A256CBC-HS512_ algorithm ({@link https://www.rfc-editor.org/rfc/rfc7518.html#section-5.2.5 JWE}).
+ * It uses the `AUTH_SECRET` environment variable or the passed `secret` property to derive a suitable encryption key.
+ *
+ * :::info Note
+ * Auth.js JWTs are meant to be used by the same app that issued them.
+ * If you need JWT authentication for your third-party API, you should rely on your Identity Provider instead.
+ * :::
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn
+ * npm install @auth/core
+ * ```
+ *
+ * You can then import this submodule from `@auth/core/jwt`.
+ *
+ * ## Usage
+ *
+ * :::warning Warning
+ * This module *will* be refactored/changed. We do not recommend relying on it right now.
+ * :::
+ *
+ *
+ * ## Resources
+ *
+ * - [What is a JWT session strategy](https://authjs.dev/concepts/session-strategies#jwt-session)
+ * - [RFC7519 - JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519)
+ *
+ * @module jwt
+ */
+import { Awaitable } from "./types.js";
+import type { LoggerInstance } from "./lib/utils/logger.js";
+/** Issues a JWT. By default, the JWT is encrypted using "A256CBC-HS512". */
+export declare function encode<Payload = JWT>(params: JWTEncodeParams<Payload>): Promise<string>;
+/** Decodes an Auth.js issued JWT. */
+export declare function decode<Payload = JWT>(params: JWTDecodeParams): Promise<Payload | null>;
+type GetTokenParamsBase = {
+    secret?: JWTDecodeParams["secret"];
+    salt?: JWTDecodeParams["salt"];
+};
+export interface GetTokenParams<R extends boolean = false> extends GetTokenParamsBase {
+    /** The request containing the JWT either in the cookies or in the `Authorization` header. */
+    req: Request | {
+        headers: Headers | Record<string, string>;
+    };
+    /**
+     * Use secure prefix for cookie name, unless URL in `NEXTAUTH_URL` is http://
+     * or not set (e.g. development or test instance) case use unprefixed name
+     */
+    secureCookie?: boolean;
+    /** If the JWT is in the cookie, what name `getToken()` should look for. */
+    cookieName?: string;
+    /**
+     * `getToken()` will return the raw JWT if this is set to `true`
+     *
+     * @default false
+     */
+    raw?: R;
+    decode?: JWTOptions["decode"];
+    logger?: LoggerInstance | Console;
+}
+/**
+ * Takes an Auth.js request (`req`) and returns either the Auth.js issued JWT's payload,
+ * or the raw JWT string. We look for the JWT in the either the cookies, or the `Authorization` header.
+ */
+export declare function getToken<R extends boolean = false>(params: GetTokenParams<R>): Promise<R extends true ? string : JWT | null>;
+export interface DefaultJWT extends Record<string, unknown> {
+    name?: string | null;
+    email?: string | null;
+    picture?: string | null;
+    sub?: string;
+    iat?: number;
+    exp?: number;
+    jti?: string;
+}
+/**
+ * Returned by the `jwt` callback when using JWT sessions
+ *
+ * [`jwt` callback](https://authjs.dev/reference/core/types#jwt)
+ */
+export interface JWT extends Record<string, unknown>, DefaultJWT {
+}
+export interface JWTEncodeParams<Payload = JWT> {
+    /**
+     * The maximum age of the Auth.js issued JWT in seconds.
+     *
+     * @default 30 * 24 * 60 * 60 // 30 days
+     */
+    maxAge?: number;
+    /** Used in combination with `secret`, to derive the encryption secret for JWTs. */
+    salt: string;
+    /** Used in combination with `salt`, to derive the encryption secret for JWTs. */
+    secret: string | string[];
+    /** The JWT payload. */
+    token?: Payload;
+}
+export interface JWTDecodeParams {
+    /** Used in combination with `secret`, to derive the encryption secret for JWTs. */
+    salt: string;
+    /**
+     * Used in combination with `salt`, to derive the encryption secret for JWTs.
+     *
+     * @note
+     * You can also pass an array of secrets, in which case the first secret that successfully
+     * decrypts the JWT will be used. This is useful for rotating secrets without invalidating existing sessions.
+     * The newer secret should be added to the start of the array, which will be used for all new sessions.
+     */
+    secret: string | string[];
+    /** The Auth.js issued JWT to be decoded */
+    token?: string;
+}
+export interface JWTOptions {
+    /**
+     * The maximum age of the Auth.js issued JWT in seconds.
+     *
+     * @default 30 * 24 * 60 * 60 // 30 days
+     */
+    maxAge: number;
+    /** Override this method to control the Auth.js issued JWT encoding. */
+    encode: (params: JWTEncodeParams) => Awaitable<string>;
+    /** Override this method to control the Auth.js issued JWT decoding. */
+    decode: (params: JWTDecodeParams) => Awaitable<JWT | null>;
+}
+export {};
+//# sourceMappingURL=jwt.d.ts.map

package/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["src/jwt.ts"],"names":[],"mappings":"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"}

package/jwt.js

@@ -0,0 +1,123 @@
+/**
+ *
+ *
+ * This module contains functions and types
+ * to encode and decode {@link https://authjs.dev/concepts/session-strategies#jwt-session JWT}s
+ * issued and used by Auth.js.
+ *
+ * The JWT issued by Auth.js is _encrypted by default_, using the _A256CBC-HS512_ algorithm ({@link https://www.rfc-editor.org/rfc/rfc7518.html#section-5.2.5 JWE}).
+ * It uses the `AUTH_SECRET` environment variable or the passed `secret` property to derive a suitable encryption key.
+ *
+ * :::info Note
+ * Auth.js JWTs are meant to be used by the same app that issued them.
+ * If you need JWT authentication for your third-party API, you should rely on your Identity Provider instead.
+ * :::
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn
+ * npm install @auth/core
+ * ```
+ *
+ * You can then import this submodule from `@auth/core/jwt`.
+ *
+ * ## Usage
+ *
+ * :::warning Warning
+ * This module *will* be refactored/changed. We do not recommend relying on it right now.
+ * :::
+ *
+ *
+ * ## Resources
+ *
+ * - [What is a JWT session strategy](https://authjs.dev/concepts/session-strategies#jwt-session)
+ * - [RFC7519 - JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519)
+ *
+ * @module jwt
+ */
+import { hkdf } from "@panva/hkdf";
+import { EncryptJWT, base64url, calculateJwkThumbprint, jwtDecrypt } from "jose";
+import { defaultCookies, SessionStore } from "./lib/utils/cookie.js";
+import { MissingSecret } from "./errors.js";
+import * as cookie from "./lib/vendored/cookie.js";
+const { parse: parseCookie } = cookie;
+const DEFAULT_MAX_AGE = 30 * 24 * 60 * 60; // 30 days
+const now = () => (Date.now() / 1000) | 0;
+const alg = "dir";
+const enc = "A256CBC-HS512";
+/** Issues a JWT. By default, the JWT is encrypted using "A256CBC-HS512". */
+export async function encode(params) {
+    const { token = {}, secret, maxAge = DEFAULT_MAX_AGE, salt } = params;
+    const secrets = Array.isArray(secret) ? secret : [secret];
+    const encryptionSecret = await getDerivedEncryptionKey(enc, secrets[0], salt);
+    const thumbprint = await calculateJwkThumbprint({ kty: "oct", k: base64url.encode(encryptionSecret) }, `sha${encryptionSecret.byteLength << 3}`);
+    // @ts-expect-error `jose` allows any object as payload.
+    return await new EncryptJWT(token)
+        .setProtectedHeader({ alg, enc, kid: thumbprint })
+        .setIssuedAt()
+        .setExpirationTime(now() + maxAge)
+        .setJti(crypto.randomUUID())
+        .encrypt(encryptionSecret);
+}
+/** Decodes an Auth.js issued JWT. */
+export async function decode(params) {
+    const { token, secret, salt } = params;
+    const secrets = Array.isArray(secret) ? secret : [secret];
+    if (!token)
+        return null;
+    const { payload } = await jwtDecrypt(token, async ({ kid, enc }) => {
+        for (const secret of secrets) {
+            const encryptionSecret = await getDerivedEncryptionKey(enc, secret, salt);
+            if (kid === undefined)
+                return encryptionSecret;
+            const thumbprint = await calculateJwkThumbprint({ kty: "oct", k: base64url.encode(encryptionSecret) }, `sha${encryptionSecret.byteLength << 3}`);
+            if (kid === thumbprint)
+                return encryptionSecret;
+        }
+        throw new Error("no matching decryption secret");
+    }, {
+        clockTolerance: 15,
+        keyManagementAlgorithms: [alg],
+        contentEncryptionAlgorithms: [enc, "A256GCM"],
+    });
+    return payload;
+}
+export async function getToken(params) {
+    const { secureCookie, cookieName = defaultCookies(secureCookie ?? false).sessionToken.name, decode: _decode = decode, salt = cookieName, secret, logger = console, raw, req, } = params;
+    if (!req)
+        throw new Error("Must pass `req` to JWT getToken()");
+    const headers = req.headers instanceof Headers ? req.headers : new Headers(req.headers);
+    const sessionStore = new SessionStore({ name: cookieName, options: { secure: secureCookie } }, parseCookie(headers.get("cookie") ?? ""), logger);
+    let token = sessionStore.value;
+    const authorizationHeader = headers.get("authorization");
+    if (!token && authorizationHeader?.split(" ")[0] === "Bearer") {
+        const urlEncodedToken = authorizationHeader.split(" ")[1];
+        token = decodeURIComponent(urlEncodedToken);
+    }
+    if (!token)
+        return null;
+    if (raw)
+        return token;
+    if (!secret)
+        throw new MissingSecret("Must pass `secret` if not set to JWT getToken()");
+    try {
+        return await _decode({ token, secret, salt });
+    }
+    catch {
+        return null;
+    }
+}
+async function getDerivedEncryptionKey(enc, keyMaterial, salt) {
+    let length;
+    switch (enc) {
+        case "A256CBC-HS512":
+            length = 64;
+            break;
+        case "A256GCM":
+            length = 32;
+            break;
+        default:
+            throw new Error("Unsupported JWT Content Encryption Algorithm");
+    }
+    return await hkdf("sha256", keyMaterial, salt, `Auth.js Generated Encryption Key (${salt})`, length);
+}

package/lib/actions/callback/handle-login.d.ts

@@ -0,0 +1,35 @@
+import type { AdapterAccount, AdapterSession, AdapterUser } from "../../../adapters.js";
+import type { Account, InternalOptions, User } from "../../../types.js";
+import type { JWT } from "../../../jwt.js";
+import type { SessionToken } from "../../utils/cookie.js";
+/**
+ * This function handles the complex flow of signing users in, and either creating,
+ * linking (or not linking) accounts depending on if the user is currently logged
+ * in, if they have account already and the authentication mechanism they are using.
+ *
+ * It prevents insecure behaviour, such as linking OAuth accounts unless a user is
+ * signed in and authenticated with an existing valid account.
+ *
+ * All verification (e.g. OAuth flows or email address verification flows) are
+ * done prior to this handler being called to avoid additional complexity in this
+ * handler.
+ */
+export declare function handleLoginOrRegister(sessionToken: SessionToken, _profile: User | AdapterUser | {
+    email: string;
+}, _account: AdapterAccount | Account | null, options: InternalOptions): Promise<{
+    user: User;
+    account: Account;
+    session?: undefined;
+    isNewUser?: undefined;
+} | {
+    session: AdapterSession | JWT | null;
+    user: AdapterUser;
+    isNewUser: boolean;
+    account: AdapterAccount;
+} | {
+    session: AdapterSession | JWT | null;
+    user: AdapterUser;
+    isNewUser: boolean;
+    account?: undefined;
+}>;
+//# sourceMappingURL=handle-login.d.ts.map

package/lib/actions/callback/handle-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-login.d.ts","sourceRoot":"","sources":["../../../src/lib/actions/callback/handle-login.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACZ,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACvE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AAE1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,YAAY,EAC1B,QAAQ,EAAE,IAAI,GAAG,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAChD,QAAQ,EAAE,cAAc,GAAG,OAAO,GAAG,IAAI,EACzC,OAAO,EAAE,eAAe;;;;;;;;;;;;;;;GAgTzB"}