@masheev/better-auth 0.0.0-stage → 1.7.5

package/dist/plugins/jwt/types.d.mts

@@ -0,0 +1,256 @@
+import { Session, User } from "../../types/models.mjs";
+import { InferOptionSchema } from "../../types/plugins.mjs";
+import { schema } from "./schema.mjs";
+import { Awaitable, GenericEndpointContext } from "@better-auth/core";
+import { JWTPayload } from "jose";
+
+//#region src/plugins/jwt/types.d.ts
+interface JwtOptions {
+  /**
+   * Use the JWT plugin's locally managed signing keys for JWT session cookie
+   * cache values.
+   *
+   * Requires `session.cookieCache.strategy` to be set to `"jwt"`.
+   *
+   * @default false
+   */
+  sessionCookieCache?: boolean | undefined;
+  jwks?: {
+    /**
+     * Disables the /jwks endpoint and uses this endpoint in discovery.
+     *
+     * Useful if jwks are not managed at /jwks or
+     * if your jwks are signed with a certificate and placed on your CDN.
+     */
+    remoteUrl?: string | undefined;
+    /**
+     * Key pair configuration
+     * @description A subset of the options available for the generateKeyPair function
+     *
+     * @see https://github.com/panva/jose/blob/main/src/runtime/node/generate.ts
+     *
+     * @default { alg: 'EdDSA', crv: 'Ed25519' }
+     */
+    keyPairConfig?: JWKOptions | undefined;
+    /**
+     * Additional key pair configurations to provision so per-resource
+     * `signingAlgorithm` overrides (see the OAuth provider plugin's
+     * resource entity) can resolve a key for algorithms other than
+     * {@link keyPairConfig}.
+     *
+     * Lazily minted: the first `signJWT` call that pins an algorithm
+     * present here mints the row on demand. Subsequent calls reuse it.
+     * This avoids needing to coordinate with migration ordering at
+     * plugin init — entries here are only materialized after the
+     * `jwks` table exists.
+     *
+     * Algorithms not present in either {@link keyPairConfig} or this
+     * list will throw with a descriptive error message identifying
+     * the configured default, so misconfiguration is diagnosable.
+     *
+     * @example
+     * ```ts
+     * jwt({
+     *   jwks: {
+     *     keyPairConfig: { alg: "EdDSA" },
+     *     keyPairConfigs: [{ alg: "ES256" }, { alg: "RS256" }],
+     *   },
+     * })
+     * ```
+     */
+    keyPairConfigs?: readonly JWKOptions[] | undefined;
+    /**
+     * Disable private key encryption
+     * @description Disable the encryption of the private key in the database
+     *
+     * @default false
+     */
+    disablePrivateKeyEncryption?: boolean | undefined;
+    /**
+     * The key rotation interval in seconds.
+     *
+     * @default undefined (disabled)
+     */
+    rotationInterval?: number | undefined;
+    /**
+     * The grace period in seconds.
+     *
+     * @default 2592000 (30 days)
+     */
+    gracePeriod?: number | undefined;
+    /**
+     * The path of the endpoint exposing the JWKS.
+     * When set, this replaces the default /jwks endpoint.
+     * The old endpoint will return 404.
+     *
+     * @default /jwks
+     * @example "/.well-known/jwks.json"
+     */
+    jwksPath?: string | undefined;
+  } | undefined;
+  jwt?: {
+    /**
+     * The issuer of the JWT
+     */
+    issuer?: string | undefined;
+    /**
+     * The audience of the JWT
+     */
+    audience?: string | string[] | undefined;
+    /**
+     * Set the "exp" (Expiration Time) Claim.
+     *
+     * - If a `number` is passed as an argument it is used as the claim directly.
+     * - If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+     *   claim.
+     * - If a `string` is passed as an argument it is resolved to a time span, and then added to the
+     *   current unix timestamp and used as the claim.
+     *
+     * Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+     * day".
+     *
+     * Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+     * "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+     * "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+     * alias for a year.
+     *
+     * If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+     * subtracted from the current unix timestamp. A "from now" suffix can also be used for
+     * readability when adding to the current unix timestamp.
+     *
+     * @default 15m
+     */
+    expirationTime?: number | string | Date | undefined;
+    /**
+     * A function that is called to define the payload of the JWT
+     */
+    definePayload?: (session: {
+      user: User & Record<string, any>;
+      session: Session & Record<string, any>;
+    }) => Awaitable<Record<string, any>> | undefined;
+    /**
+     * A function that is called to get the subject of the JWT
+     *
+     * @default session.user.id
+     */
+    getSubject?: (session: {
+      user: User & Record<string, any>;
+      session: Session & Record<string, any>;
+    }) => Awaitable<string> | undefined;
+    /**
+     * A custom function to remote sign the jwt payload.
+     *
+     * All headers, such as `alg` and `kid`,
+     * MUST be defined within this function.
+     * You can safely define the header `typ: 'JWT'`.
+     *
+     * The optional `header` argument carries extra protected-header
+     * parameters the caller requires (e.g. `typ: "logout+jwt"` for
+     * OIDC Back-Channel Logout). Merge them into the signed header so
+     * such profiles stay conformant; `alg`/`kid` remain yours to set.
+     *
+     * The optional `signingConfig` third argument carries the
+     * per-call signing overrides (e.g. an OAuth protected resource pinned
+     * to a specific kid/alg). Implementations are free to ignore
+     * it for backward compatibility, but remote KMS integrations
+     * SHOULD honor it so per-resource pinning works end-to-end.
+     *
+     * @requires jwks.remoteUrl
+     * @invalidates other jwt.* options
+     */
+    sign?: ((payload: JWTPayload, header?: {
+      typ?: string;
+      cty?: string;
+    }, signingConfig?: {
+      signingKeyId?: string | undefined;
+      signingAlgorithm?: JWSAlgorithms | undefined;
+    }) => Awaitable<string>) | undefined;
+  } | undefined;
+  /**
+   * Disables setting JWTs through middleware.
+   *
+   * Recommended to set `true` when using an oAuth provider plugin
+   * like OIDC or MCP where session payloads should not be signed.
+   *
+   * @default false
+   */
+  disableSettingJwtHeader?: boolean | undefined;
+  /**
+   * Custom schema for the admin plugin
+   */
+  schema?: InferOptionSchema<typeof schema> | undefined;
+  /**
+   * Custom adapter for the jwt plugin
+   *
+   * This will override the default adapter
+   *
+   * @default adapter from the database
+   */
+  adapter?: {
+    /**
+     * A custom function to get the JWKS from the database or
+     * other source
+     *
+     * This will override the default getJwks from the database
+     *
+     * @param ctx - The context of the request
+     * @returns The JWKS
+     */
+    getJwks?: (ctx: GenericEndpointContext) => Promise<Jwk[] | null | undefined>;
+    /**
+     * A custom function to create a new key in the database or
+     * other source
+     *
+     * This will override the default createJwk from the database
+     *
+     * @param data - The key to create
+     * @returns The created key
+     */
+    createJwk?: (data: Omit<Jwk, "id">, ctx: GenericEndpointContext) => Promise<Jwk>;
+  };
+}
+/**
+ * Asymmetric (JWS) Supported.
+ *
+ * @see https://github.com/panva/jose/issues/210
+ */
+type JWKOptions = {
+  alg: "EdDSA";
+  crv?: "Ed25519" | undefined;
+} | {
+  alg: "ES256";
+  crv?: never | undefined;
+} | {
+  alg: "ES512";
+  crv?: never | undefined;
+} | {
+  alg: "PS256";
+  modulusLength?: number | undefined;
+} | {
+  alg: "RS256";
+  modulusLength?: number | undefined;
+};
+type JWSAlgorithms = JWKOptions["alg"];
+interface Jwk {
+  id: string;
+  publicKey: string;
+  privateKey: string;
+  createdAt: Date;
+  expiresAt?: Date;
+  alg?: JWSAlgorithms | undefined;
+  crv?: ("Ed25519" | "P-256" | "P-521") | undefined;
+}
+/**
+ * A fully resolved signing key ready for JWT signing.
+ * Produced by `resolveSigningKey`, consumed by `signJWT`.
+ * Separates key resolution from signing so callers can
+ * read the `alg` before constructing the JWT payload
+ * (required for OIDC hash claims like at_hash).
+ */
+interface ResolvedSigningKey {
+  alg: string;
+  kid: string;
+  privateKey: CryptoKey | Uint8Array;
+}
+//#endregion
+export { JWKOptions, JWSAlgorithms, Jwk, JwtOptions, ResolvedSigningKey };

package/dist/plugins/jwt/utils.d.mts

@@ -0,0 +1,41 @@
+import { Jwk, JwtOptions } from "./types.mjs";
+import { GenericEndpointContext } from "@better-auth/core";
+import * as _$jose from "jose";
+
+//#region src/plugins/jwt/utils.d.ts
+/**
+ * Converts an expirationTime to ISO seconds expiration time (the format of JWT exp)
+ *
+ * See https://github.com/panva/jose/blob/main/src/lib/jwt_claims_set.ts#L245
+ *
+ * @param expirationTime - see options.jwt.expirationTime
+ * @param iat - the iat time to consolidate on
+ * @returns
+ */
+declare function toExpJWT(expirationTime: number | Date | string, iat: number): number;
+declare function generateExportedKeyPair(options?: JwtOptions | undefined): Promise<{
+  publicWebKey: _$jose.JWK;
+  privateWebKey: _$jose.JWK;
+  alg: "EdDSA" | "ES256" | "ES512" | "PS256" | "RS256";
+  cfg: {
+    crv?: "Ed25519" | undefined;
+  } | {
+    crv?: never | undefined;
+  } | {
+    crv?: never | undefined;
+  } | {
+    modulusLength?: number | undefined;
+  } | {
+    modulusLength?: number | undefined;
+  };
+}>;
+/**
+ * Creates a Jwk on the database
+ *
+ * @param ctx
+ * @param options
+ * @returns
+ */
+declare function createJwk(ctx: GenericEndpointContext, options?: JwtOptions | undefined): Promise<Jwk>;
+//#endregion
+export { createJwk, generateExportedKeyPair, toExpJWT };

package/dist/plugins/jwt/utils.mjs

@@ -0,0 +1,64 @@
+import { sec } from "../../utils/time.mjs";
+import { symmetricEncrypt } from "../../crypto/index.mjs";
+import { getJwksAdapter } from "./adapter.mjs";
+import { exportJWK, generateKeyPair } from "jose";
+//#region src/plugins/jwt/utils.ts
+/**
+* Converts an expirationTime to ISO seconds expiration time (the format of JWT exp)
+*
+* See https://github.com/panva/jose/blob/main/src/lib/jwt_claims_set.ts#L245
+*
+* @param expirationTime - see options.jwt.expirationTime
+* @param iat - the iat time to consolidate on
+* @returns
+*/
+function toExpJWT(expirationTime, iat) {
+	if (typeof expirationTime === "number") return expirationTime;
+	else if (expirationTime instanceof Date) return Math.floor(expirationTime.getTime() / 1e3);
+	else return iat + sec(expirationTime);
+}
+async function generateExportedKeyPair(options) {
+	const { alg, ...cfg } = options?.jwks?.keyPairConfig ?? {
+		alg: "EdDSA",
+		crv: "Ed25519"
+	};
+	const { publicKey, privateKey } = await generateKeyPair(alg, {
+		...cfg,
+		extractable: true
+	});
+	return {
+		publicWebKey: await exportJWK(publicKey),
+		privateWebKey: await exportJWK(privateKey),
+		alg,
+		cfg
+	};
+}
+/**
+* Creates a Jwk on the database
+*
+* @param ctx
+* @param options
+* @returns
+*/
+async function createJwk(ctx, options) {
+	const { publicWebKey, privateWebKey, alg, cfg } = await generateExportedKeyPair(options);
+	const explicitCrv = cfg && "crv" in cfg ? cfg.crv : void 0;
+	const derivedCrv = typeof publicWebKey.crv === "string" ? publicWebKey.crv : void 0;
+	const crv = explicitCrv ?? derivedCrv;
+	const stringifiedPrivateWebKey = JSON.stringify(privateWebKey);
+	const privateKeyEncryptionEnabled = !options?.jwks?.disablePrivateKeyEncryption;
+	const jwk = {
+		alg,
+		...crv ? { crv } : {},
+		publicKey: JSON.stringify(publicWebKey),
+		privateKey: privateKeyEncryptionEnabled ? JSON.stringify(await symmetricEncrypt({
+			key: ctx.context.secretConfig,
+			data: stringifiedPrivateWebKey
+		})) : stringifiedPrivateWebKey,
+		createdAt: /* @__PURE__ */ new Date(),
+		...options?.jwks?.rotationInterval ? { expiresAt: new Date(Date.now() + options.jwks.rotationInterval * 1e3) } : {}
+	};
+	return await getJwksAdapter(ctx.context.adapter, options).createJwk(ctx, jwk);
+}
+//#endregion
+export { createJwk, generateExportedKeyPair, toExpJWT };

package/dist/plugins/jwt/verify.d.mts

@@ -0,0 +1,11 @@
+import { JwtOptions } from "./types.mjs";
+import { JWTPayload } from "jose";
+
+//#region src/plugins/jwt/verify.d.ts
+/**
+ * Verify a JWT token using the JWKS public keys
+ * Returns the payload if valid, null otherwise
+ */
+declare function verifyJWT<T extends JWTPayload = JWTPayload>(token: string, options?: JwtOptions): Promise<(T & Required<Pick<JWTPayload, "sub" | "aud">>) | null>;
+//#endregion
+export { verifyJWT };

package/dist/plugins/jwt/verify.mjs

@@ -0,0 +1,45 @@
+import { getJwksAdapter } from "./adapter.mjs";
+import { getCurrentAuthEndpointContext } from "@better-auth/core/context";
+import { base64 } from "@better-auth/utils/base64";
+import { importJWK, jwtVerify } from "jose";
+//#region src/plugins/jwt/verify.ts
+/**
+* Verify a JWT token using the JWKS public keys
+* Returns the payload if valid, null otherwise
+*/
+async function verifyJWT(token, options) {
+	const ctx = getCurrentAuthEndpointContext();
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) return null;
+		const headerStr = new TextDecoder().decode(base64.decode(parts[0]));
+		const kid = JSON.parse(headerStr).kid;
+		if (!kid) {
+			ctx.context.logger.debug("JWT missing kid in header");
+			return null;
+		}
+		const keys = await getJwksAdapter(ctx.context.adapter, options).getAllKeys(ctx);
+		if (!keys || keys.length === 0) {
+			ctx.context.logger.debug("No JWKS keys available");
+			return null;
+		}
+		const key = keys.find((k) => k.id === kid);
+		if (!key) {
+			ctx.context.logger.debug(`No JWKS key found for kid: ${kid}`);
+			return null;
+		}
+		const cryptoKey = await importJWK(JSON.parse(key.publicKey), key.alg ?? options?.jwks?.keyPairConfig?.alg ?? "EdDSA");
+		const baseURLOrigin = typeof ctx.context.options.baseURL === "string" ? ctx.context.options.baseURL : void 0;
+		const { payload } = await jwtVerify(token, cryptoKey, {
+			issuer: options?.jwt?.issuer ?? baseURLOrigin,
+			audience: options?.jwt?.audience ?? baseURLOrigin
+		});
+		if (!payload.sub || !payload.aud) return null;
+		return payload;
+	} catch (error) {
+		ctx.context.logger.debug("JWT verification failed", error);
+		return null;
+	}
+}
+//#endregion
+export { verifyJWT };

package/dist/plugins/last-login-method/client.d.mts

@@ -0,0 +1,48 @@
+//#region src/plugins/last-login-method/client.d.ts
+/**
+ * Configuration for the client-side last login method plugin
+ */
+interface LastLoginMethodClientConfig {
+  /**
+   * Name of the cookie to read the last login method from
+   * @default "better-auth.last_used_login_method"
+   */
+  cookieName?: string | undefined;
+  /**
+   * Domain for the cookie. Required when using cross-subdomain cookies
+   * so the client can properly clear the cookie set by the server.
+   *
+   * Should match the `domain` value in your server's
+   * `crossSubDomainCookies` configuration.
+   *
+   * @example ".example.com"
+   */
+  domain?: string | undefined;
+}
+/**
+ * Client-side plugin to retrieve the last used login method
+ */
+declare const lastLoginMethodClient: (config?: LastLoginMethodClientConfig) => {
+  id: "last-login-method-client";
+  version: string;
+  getActions(): {
+    /**
+     * Get the last used login method from cookies
+     * @returns The last used login method or null if not found
+     */
+    getLastUsedLoginMethod: () => string | null;
+    /**
+     * Clear the last used login method cookie
+     * This sets the cookie with an expiration date in the past
+     */
+    clearLastUsedLoginMethod: () => void;
+    /**
+     * Check if a specific login method was the last used
+     * @param method The method to check
+     * @returns True if the method was the last used, false otherwise
+     */
+    isLastUsedLoginMethod: (method: string) => boolean;
+  };
+};
+//#endregion
+export { LastLoginMethodClientConfig, lastLoginMethodClient };

package/dist/plugins/last-login-method/client.mjs

@@ -0,0 +1,48 @@
+import { parseCookies } from "../../cookies/cookie-utils.mjs";
+import { PACKAGE_VERSION } from "../../version.mjs";
+//#region src/plugins/last-login-method/client.ts
+function getCookieValue(name) {
+	if (typeof document === "undefined") return null;
+	return parseCookies(document.cookie).get(name) ?? null;
+}
+/**
+* Client-side plugin to retrieve the last used login method
+*/
+const lastLoginMethodClient = (config = {}) => {
+	const cookieName = config.cookieName || "better-auth.last_used_login_method";
+	return {
+		id: "last-login-method-client",
+		version: PACKAGE_VERSION,
+		getActions() {
+			return {
+				/**
+				* Get the last used login method from cookies
+				* @returns The last used login method or null if not found
+				*/
+				getLastUsedLoginMethod: () => {
+					return getCookieValue(cookieName);
+				},
+				/**
+				* Clear the last used login method cookie
+				* This sets the cookie with an expiration date in the past
+				*/
+				clearLastUsedLoginMethod: () => {
+					if (typeof document !== "undefined") {
+						const domainPart = config.domain ? ` domain=${config.domain};` : "";
+						document.cookie = `${cookieName}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;${domainPart}`;
+					}
+				},
+				/**
+				* Check if a specific login method was the last used
+				* @param method The method to check
+				* @returns True if the method was the last used, false otherwise
+				*/
+				isLastUsedLoginMethod: (method) => {
+					return getCookieValue(cookieName) === method;
+				}
+			};
+		}
+	};
+};
+//#endregion
+export { lastLoginMethodClient };

package/dist/plugins/last-login-method/index.d.mts

@@ -0,0 +1,127 @@
+import * as _$_better_auth_core0 from "@better-auth/core";
+import { GenericEndpointContext } from "@better-auth/core";
+import * as _$better_call0 from "better-call";
+
+//#region src/plugins/last-login-method/index.d.ts
+declare module "@better-auth/core" {
+  interface BetterAuthPluginRegistry<AuthOptions, Options> {
+    "last-login-method": {
+      creator: typeof lastLoginMethod;
+    };
+  }
+}
+/**
+ * Configuration for tracking different authentication methods
+ */
+interface LastLoginMethodOptions {
+  /**
+   * Name of the cookie to store the last login method
+   * @default "better-auth.last_used_login_method"
+   */
+  cookieName?: string | undefined;
+  /**
+   * Cookie expiration time in seconds
+   * @default 2592000 (30 days)
+   */
+  maxAge?: number | undefined;
+  /**
+   * Custom method to resolve the last login method
+   * @param ctx - The context from the hook
+   * @returns The last login method
+   */
+  customResolveMethod?: ((ctx: GenericEndpointContext) => string | null) | undefined;
+  /**
+   * Store the last login method in the database. This will create a new field in the user table.
+   * @default false
+   */
+  storeInDatabase?: boolean | undefined;
+  /**
+   * A hook to run before the last login method is stored in the cookie.
+   * Useful if you are required to follow GDPR or other regulations to ensure that you're allowed to store the last login method in the cookie.
+   *
+   * @param ctx - The context from the hook
+   * @param lastUsedLoginMethod - The last login method
+   * @returns `true` to store the cookie, `false` to skip storing it (authentication continues either way)
+   */
+  beforeStoreCookie?: ((ctx: GenericEndpointContext, lastUsedLoginMethod: string) => Promise<boolean> | boolean) | undefined;
+  /**
+   * Custom schema for the plugin
+   * @default undefined
+   */
+  schema?: {
+    user?: {
+      lastLoginMethod?: string;
+    };
+  } | undefined;
+}
+/**
+ * Plugin to track the last used login method
+ */
+declare const lastLoginMethod: <O extends LastLoginMethodOptions>(userConfig?: O | undefined) => {
+  id: "last-login-method";
+  version: string;
+  init(ctx: _$_better_auth_core0.AuthContext): {
+    options: {
+      databaseHooks: {
+        user: {
+          create: {
+            before(user: {
+              id: string;
+              createdAt: Date;
+              updatedAt: Date;
+              email: string;
+              emailVerified: boolean;
+              name: string;
+              image?: string | null | undefined;
+            } & Record<string, unknown>, context: GenericEndpointContext | null): Promise<{
+              data: {
+                lastLoginMethod: string;
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+              };
+            } | undefined>;
+          };
+        };
+        session: {
+          create: {
+            after(session: {
+              id: string;
+              createdAt: Date;
+              updatedAt: Date;
+              userId: string;
+              expiresAt: Date;
+              token: string;
+              ipAddress?: string | null | undefined;
+              userAgent?: string | null | undefined;
+            } & Record<string, unknown>, context: GenericEndpointContext | null): Promise<void>;
+          };
+        };
+      };
+    };
+  };
+  hooks: {
+    after: {
+      matcher(): true;
+      handler: _$better_call0.Middleware<_$better_call0.MiddlewareOptions, (inputContext: _$better_call0.MiddlewareInputContext<_$better_call0.MiddlewareOptions>) => Promise<void>>;
+    }[];
+  };
+  schema: O["storeInDatabase"] extends true ? {
+    user: {
+      fields: {
+        lastLoginMethod: {
+          type: "string";
+          required: false;
+          input: false;
+        };
+      };
+    };
+  } : undefined;
+  options: NoInfer<O>;
+};
+//#endregion
+export { LastLoginMethodOptions, lastLoginMethod };