@masheev/better-auth 0.0.0-stage → 1.7.5

package/dist/plugins/jwt/index.mjs

@@ -0,0 +1,214 @@
+import { mergeSchema } from "../../db/schema.mjs";
+import { sessionMiddleware } from "../../api/routes/session.mjs";
+import { APIError as APIError$1 } from "../../api/index.mjs";
+import { PACKAGE_VERSION } from "../../version.mjs";
+import { getJwksAdapter } from "./adapter.mjs";
+import { createJwk, generateExportedKeyPair, toExpJWT } from "./utils.mjs";
+import { getJwtToken, resolveSigningKey, signJWT } from "./sign.mjs";
+import { createCookieCacheSigner } from "./cookie-cache.mjs";
+import { schema } from "./schema.mjs";
+import { verifyJWT } from "./verify.mjs";
+import { BetterAuthError } from "@better-auth/core/error";
+import { createAuthEndpoint, createAuthMiddleware } from "@better-auth/core/api";
+import * as z from "zod";
+//#region src/plugins/jwt/index.ts
+const signJWTBodySchema = z.object({
+	payload: z.record(z.string(), z.any()),
+	overrideOptions: z.record(z.string(), z.any()).optional()
+});
+const verifyJWTBodySchema = z.object({
+	token: z.string(),
+	issuer: z.string().optional()
+});
+const jwt = (options) => {
+	if (options?.jwt?.sign && !options.jwks?.remoteUrl) throw new BetterAuthError("options.jwks.remoteUrl must be set when using options.jwt.sign");
+	if (options?.jwks?.remoteUrl && !options.jwks?.keyPairConfig?.alg) throw new BetterAuthError("options.jwks.keyPairConfig.alg must be specified when options.jwks.remoteUrl is used for OpenID metadata");
+	const jwksPath = options?.jwks?.jwksPath ?? "/jwks";
+	if (typeof jwksPath !== "string" || jwksPath.length === 0 || !jwksPath.startsWith("/") || jwksPath.includes("..")) throw new BetterAuthError("options.jwks.jwksPath must be a non-empty string starting with '/' and not contain '..'");
+	return {
+		id: "jwt",
+		version: PACKAGE_VERSION,
+		options,
+		init(ctx) {
+			if (!options?.sessionCookieCache) return;
+			if (ctx.options.session?.cookieCache?.strategy !== "jwt") throw new BetterAuthError("`jwt({ sessionCookieCache: true })` requires `session.cookieCache.strategy = \"jwt\"`.");
+			if (options.jwt?.sign) throw new BetterAuthError("`jwt({ sessionCookieCache: true })` requires locally managed JWT plugin keys and does not support `jwt.sign`.");
+			const gracePeriod = options.jwks?.gracePeriod;
+			const cookieMaxAge = ctx.options.session.cookieCache.maxAge || 300;
+			if (gracePeriod !== void 0 && cookieMaxAge > gracePeriod) ctx.logger.warn(`[better-auth] \`session.cookieCache.maxAge\` (${cookieMaxAge}s) exceeds the JWT plugin JWKS grace period (${gracePeriod}s). Rotated keys may stop verifying cookie-cache JWTs before the cookie expires.`);
+			return { context: { sessionConfig: {
+				...ctx.sessionConfig,
+				cookieCacheSigner: createCookieCacheSigner(options)
+			} } };
+		},
+		endpoints: {
+			getJwks: createAuthEndpoint(jwksPath, {
+				method: "GET",
+				metadata: { openapi: {
+					operationId: "getJSONWebKeySet",
+					description: "Get the JSON Web Key Set",
+					responses: { "200": {
+						description: "JSON Web Key Set retrieved successfully",
+						content: { "application/json": { schema: {
+							type: "object",
+							properties: { keys: {
+								type: "array",
+								description: "Array of public JSON Web Keys",
+								items: {
+									type: "object",
+									properties: {
+										kid: {
+											type: "string",
+											description: "Key ID uniquely identifying the key, corresponds to the 'id' from the stored Jwk"
+										},
+										kty: {
+											type: "string",
+											description: "Key type (e.g., 'RSA', 'EC', 'OKP')"
+										},
+										alg: {
+											type: "string",
+											description: "Algorithm intended for use with the key (e.g., 'EdDSA', 'RS256')"
+										},
+										use: {
+											type: "string",
+											description: "Intended use of the public key (e.g., 'sig' for signature)",
+											enum: ["sig"],
+											nullable: true
+										},
+										n: {
+											type: "string",
+											description: "Modulus for RSA keys (base64url-encoded)",
+											nullable: true
+										},
+										e: {
+											type: "string",
+											description: "Exponent for RSA keys (base64url-encoded)",
+											nullable: true
+										},
+										crv: {
+											type: "string",
+											description: "Curve name for elliptic curve keys (e.g., 'Ed25519', 'P-256')",
+											nullable: true
+										},
+										x: {
+											type: "string",
+											description: "X coordinate for elliptic curve keys (base64url-encoded)",
+											nullable: true
+										},
+										y: {
+											type: "string",
+											description: "Y coordinate for elliptic curve keys (base64url-encoded)",
+											nullable: true
+										}
+									},
+									required: [
+										"kid",
+										"kty",
+										"alg"
+									]
+								}
+							} },
+							required: ["keys"]
+						} } }
+					} }
+				} }
+			}, async (ctx) => {
+				if (options?.jwks?.remoteUrl) throw new APIError$1("NOT_FOUND");
+				const adapter = getJwksAdapter(ctx.context.adapter, options);
+				let keySets = await adapter.getAllKeys(ctx);
+				if (!keySets || keySets?.length === 0) {
+					await createJwk(ctx, options);
+					keySets = await adapter.getAllKeys(ctx);
+				}
+				if (!keySets?.length) throw new BetterAuthError("No key sets found. Make sure you have a key in your database.");
+				const now = Date.now();
+				const gracePeriod = (options?.jwks?.gracePeriod ?? 3600 * 24 * 30) * 1e3;
+				const keys = keySets.filter((key) => {
+					if (!key.expiresAt) return true;
+					return key.expiresAt.getTime() + gracePeriod > now;
+				});
+				const keyPairConfig = options?.jwks?.keyPairConfig;
+				const defaultCrv = keyPairConfig ? "crv" in keyPairConfig ? keyPairConfig.crv : void 0 : void 0;
+				return ctx.json({ keys: keys.map((keySet) => {
+					return {
+						alg: keySet.alg ?? options?.jwks?.keyPairConfig?.alg ?? "EdDSA",
+						crv: keySet.crv ?? defaultCrv,
+						...JSON.parse(keySet.publicKey),
+						kid: keySet.id
+					};
+				}) });
+			}),
+			getToken: createAuthEndpoint("/token", {
+				method: "GET",
+				requireHeaders: true,
+				use: [sessionMiddleware],
+				metadata: { openapi: {
+					operationId: "getJSONWebToken",
+					description: "Get a JWT token",
+					responses: { 200: {
+						description: "Success",
+						content: { "application/json": { schema: {
+							type: "object",
+							properties: { token: { type: "string" } }
+						} } }
+					} }
+				} }
+			}, async (ctx) => {
+				const jwt = await getJwtToken(ctx, options);
+				return ctx.json({ token: jwt });
+			}),
+			signJWT: createAuthEndpoint.serverOnly({
+				method: "POST",
+				metadata: { $Infer: { body: {} } },
+				body: signJWTBodySchema
+			}, async (c) => {
+				const jwt = await signJWT(c, {
+					options: {
+						...options,
+						...c.body.overrideOptions
+					},
+					payload: c.body.payload
+				});
+				return c.json({ token: jwt });
+			}),
+			verifyJWT: createAuthEndpoint.serverOnly({
+				method: "POST",
+				metadata: { $Infer: {
+					body: {},
+					response: {}
+				} },
+				body: verifyJWTBodySchema
+			}, async (ctx) => {
+				const overrideOptions = ctx.body.issuer ? {
+					...options,
+					jwt: {
+						...options?.jwt,
+						issuer: ctx.body.issuer
+					}
+				} : options;
+				const payload = await verifyJWT(ctx.body.token, overrideOptions);
+				return ctx.json({ payload });
+			})
+		},
+		hooks: { after: [{
+			matcher(context) {
+				return context.path === "/get-session";
+			},
+			handler: createAuthMiddleware(async (ctx) => {
+				if (options?.disableSettingJwtHeader) return;
+				const session = ctx.context.session || ctx.context.newSession;
+				if (session && session.session) {
+					const jwt = await getJwtToken(ctx, options);
+					const exposedHeaders = ctx.context.responseHeaders?.get("access-control-expose-headers") || "";
+					const headersSet = new Set(exposedHeaders.split(",").map((header) => header.trim()).filter(Boolean));
+					headersSet.add("set-auth-jwt");
+					ctx.setHeader("set-auth-jwt", jwt);
+					ctx.setHeader("Access-Control-Expose-Headers", Array.from(headersSet).join(", "));
+				}
+			})
+		}] },
+		schema: mergeSchema(schema, options?.schema)
+	};
+};
+//#endregion
+export { createJwk, generateExportedKeyPair, getJwtToken, jwt, resolveSigningKey, signJWT, toExpJWT, verifyJWT };

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

@@ -0,0 +1,33 @@
+//#region src/plugins/jwt/schema.d.ts
+declare const schema: {
+  jwks: {
+    fields: {
+      publicKey: {
+        type: "string";
+        required: true;
+      };
+      privateKey: {
+        type: "string";
+        required: true;
+      };
+      createdAt: {
+        type: "date";
+        required: true;
+      };
+      expiresAt: {
+        type: "date";
+        required: false;
+      };
+      alg: {
+        type: "string";
+        required: false;
+      };
+      crv: {
+        type: "string";
+        required: false;
+      };
+    };
+  };
+};
+//#endregion
+export { schema };

package/dist/plugins/jwt/schema.mjs

@@ -0,0 +1,29 @@
+//#region src/plugins/jwt/schema.ts
+const schema = { jwks: { fields: {
+	publicKey: {
+		type: "string",
+		required: true
+	},
+	privateKey: {
+		type: "string",
+		required: true
+	},
+	createdAt: {
+		type: "date",
+		required: true
+	},
+	expiresAt: {
+		type: "date",
+		required: false
+	},
+	alg: {
+		type: "string",
+		required: false
+	},
+	crv: {
+		type: "string",
+		required: false
+	}
+} } };
+//#endregion
+export { schema };

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

@@ -0,0 +1,128 @@
+import { JWSAlgorithms, JwtOptions, ResolvedSigningKey } from "./types.mjs";
+import { GenericEndpointContext } from "@better-auth/core";
+
+//#region src/plugins/jwt/sign.d.ts
+type JWTPayloadWithOptional = {
+  /**
+   * JWT Issuer
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 RFC7519#section-4.1.1}
+   */
+  iss?: string | undefined;
+  /**
+   * JWT Subject
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2 RFC7519#section-4.1.2}
+   */
+  sub?: string | undefined;
+  /**
+   * JWT Audience
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 RFC7519#section-4.1.3}
+   */
+  aud?: string | string[] | undefined;
+  /**
+   * JWT ID
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7 RFC7519#section-4.1.7}
+   */
+  jti?: string | undefined;
+  /**
+   * JWT Not Before
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5 RFC7519#section-4.1.5}
+   */
+  nbf?: number | undefined;
+  /**
+   * JWT Expiration Time
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 RFC7519#section-4.1.4}
+   */
+  exp?: number | undefined;
+  /**
+   * JWT Issued At
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6 RFC7519#section-4.1.6}
+   */
+  iat?: number | undefined; /** Any other JWT Claim Set member. */
+  [propName: string]: unknown | undefined;
+};
+/**
+ * Per-call signing overrides shared by `resolveSigningKey()` and `signJWT()`.
+ *
+ * Both fields are optional. When set, they shift key selection away from the
+ * default "most recently created live key" behavior:
+ *
+ * - `signingKeyId` — load the exact JWKS row whose `id` equals this value
+ *   (matches the JWS `kid` header). Throws if not found; never auto-mints
+ *   a replacement (admin-provisioned key is the contract).
+ * - `signingAlgorithm` — load the most recent live key with that `alg`. If
+ *   none exists AND the algorithm is declared in `options.jwks.keyPairConfigs`
+ *   (or equals the primary `keyPairConfig.alg`), the key is lazy-minted on
+ *   demand. Otherwise throws with a descriptive error naming what IS
+ *   provisioned.
+ *
+ * Used by the OAuth provider plugin to honor per-resource `signingAlgorithm` /
+ * `signingKeyId` overrides without re-implementing key resolution.
+ */
+interface SigningKeyOverrides {
+  signingKeyId?: string | undefined;
+  signingAlgorithm?: JWSAlgorithms | undefined;
+}
+/**
+ * Resolves the JWKS signing key, decrypts it, and imports it
+ * for use with jose's SignJWT. Returns null when signing is
+ * delegated to a custom jwt.sign callback.
+ *
+ * Callers that need the signing algorithm before constructing
+ * the JWT payload (e.g. for OIDC at_hash) should call this
+ * first, read `.alg`, then pass the result to `signJWT` via
+ * the `resolvedKey` option to avoid a redundant DB lookup.
+ *
+ * When `overrides.signingKeyId` or `overrides.signingAlgorithm` is set, key
+ * selection follows the contract documented on {@link SigningKeyOverrides};
+ * without overrides this returns the most recently created live key, falling
+ * back to the primary `keyPairConfig.alg` when even that's absent so unpinned
+ * tokens stay on the configured default algorithm even after extra algorithms
+ * have been lazy-minted for audience pinning.
+ */
+declare function resolveSigningKey(ctx: GenericEndpointContext, options?: JwtOptions, overrides?: SigningKeyOverrides): Promise<ResolvedSigningKey | null>;
+declare function signJWT(ctx: GenericEndpointContext, config: {
+  options?: JwtOptions | undefined;
+  payload: JWTPayloadWithOptional; /** Pre-resolved key from resolveSigningKey. Skips redundant DB lookup. */
+  resolvedKey?: ResolvedSigningKey;
+  /**
+   * Extra JWS Protected Header parameters to merge with the defaults
+   * (`alg` and `kid`). Used by token profiles that require an explicit
+   * media type, such as OIDC Back-Channel Logout's `typ: "logout+jwt"`.
+   *
+   * @see https://www.rfc-editor.org/rfc/rfc8725#section-3.11
+   */
+  header?: {
+    typ?: string;
+    cty?: string;
+  };
+  /**
+   * Optional override for the signing key. When set, looks up the key
+   * by its `id` (matches the JWS `kid` header) via the JWKS adapter.
+   * Throws if no key with that id exists.
+   *
+   * When unset, falls back to the most recently created key with the
+   * primary `keyPairConfig.alg` (the historical default).
+   */
+  signingKeyId?: string | undefined;
+  /**
+   * Optional override for the signing algorithm. Selects the most
+   * recent key with this algorithm. When neither this nor
+   * `signingKeyId` is set, the most recent key matching
+   * `keyPairConfig.alg` is used (historical default).
+   *
+   * If both `signingKeyId` and `signingAlgorithm` are set, `signingKeyId`
+   * wins; the algorithm is validated to match the resolved key and
+   * the call throws on mismatch.
+   */
+  signingAlgorithm?: JWSAlgorithms | undefined;
+}): Promise<string>;
+declare function getJwtToken(ctx: GenericEndpointContext, options?: JwtOptions | undefined): Promise<string>;
+//#endregion
+export { getJwtToken, resolveSigningKey, signJWT };

package/dist/plugins/jwt/sign.mjs

@@ -0,0 +1,130 @@
+import { symmetricDecrypt } from "../../crypto/index.mjs";
+import { getJwksAdapter } from "./adapter.mjs";
+import { createJwk, toExpJWT } from "./utils.mjs";
+import { BetterAuthError } from "@better-auth/core/error";
+import { SignJWT, importJWK } from "jose";
+//#region src/plugins/jwt/sign.ts
+/**
+* Resolves the JWKS signing key, decrypts it, and imports it
+* for use with jose's SignJWT. Returns null when signing is
+* delegated to a custom jwt.sign callback.
+*
+* Callers that need the signing algorithm before constructing
+* the JWT payload (e.g. for OIDC at_hash) should call this
+* first, read `.alg`, then pass the result to `signJWT` via
+* the `resolvedKey` option to avoid a redundant DB lookup.
+*
+* When `overrides.signingKeyId` or `overrides.signingAlgorithm` is set, key
+* selection follows the contract documented on {@link SigningKeyOverrides};
+* without overrides this returns the most recently created live key, falling
+* back to the primary `keyPairConfig.alg` when even that's absent so unpinned
+* tokens stay on the configured default algorithm even after extra algorithms
+* have been lazy-minted for audience pinning.
+*/
+async function resolveSigningKey(ctx, options, overrides) {
+	if (options?.jwt?.sign) return null;
+	const adapter = getJwksAdapter(ctx.context.adapter, options);
+	let key;
+	if (overrides?.signingKeyId !== void 0) {
+		key = await adapter.getKeyById(ctx, overrides.signingKeyId);
+		if (!key) throw new BetterAuthError(`signJWT: signingKeyId "${overrides.signingKeyId}" not found in JWKS. The key must be provisioned before it can be referenced.`);
+		if (overrides.signingAlgorithm !== void 0) {
+			const configAlg = options?.jwks?.keyPairConfig?.alg ?? "EdDSA";
+			if ((key.alg ?? configAlg) !== overrides.signingAlgorithm) throw new BetterAuthError(`signJWT: signingKeyId "${overrides.signingKeyId}" has alg "${key.alg ?? `unset (inherits keyPairConfig.alg "${configAlg}")`}" but signingAlgorithm was set to "${overrides.signingAlgorithm}".`);
+		}
+	} else if (overrides?.signingAlgorithm !== void 0) {
+		key = await adapter.getLatestKeyByAlg(ctx, overrides.signingAlgorithm);
+		if (!key) {
+			const primaryAlg = options?.jwks?.keyPairConfig?.alg ?? "EdDSA";
+			const preconfig = options?.jwks?.keyPairConfigs?.find((c) => c.alg === overrides.signingAlgorithm);
+			const isPrimary = primaryAlg === overrides.signingAlgorithm;
+			if (preconfig || isPrimary) key = await createJwk(ctx, {
+				...options,
+				jwks: {
+					...options?.jwks,
+					keyPairConfig: preconfig ?? options?.jwks?.keyPairConfig
+				}
+			});
+			else {
+				const advertisedExtra = options?.jwks?.keyPairConfigs?.map((c) => c.alg).join(", ") || "none";
+				throw new BetterAuthError(`signJWT: no key with alg "${overrides.signingAlgorithm}" found in JWKS. The plugin auto-mints only one key matching keyPairConfig.alg="${primaryAlg}"; additional algs configured via keyPairConfigs: ${advertisedExtra}. Add "${overrides.signingAlgorithm}" to jwks.keyPairConfigs so the plugin provisions it on first use, or mint the key explicitly via createJwk().`);
+			}
+		}
+	} else {
+		const primaryAlg = options?.jwks?.keyPairConfig?.alg ?? "EdDSA";
+		key = await adapter.getLatestKeyByAlg(ctx, primaryAlg) ?? await adapter.getLatestKey(ctx);
+	}
+	if (!key || key.expiresAt && key.expiresAt < /* @__PURE__ */ new Date()) {
+		if (overrides?.signingKeyId !== void 0 || overrides?.signingAlgorithm !== void 0) throw new BetterAuthError("signJWT: requested signing key is expired and an explicit kid/alg was provided; not auto-minting a replacement. Rotate the key explicitly.");
+		key = await createJwk(ctx, options);
+	}
+	const privateWebKey = !options?.jwks?.disablePrivateKeyEncryption ? await symmetricDecrypt({
+		key: ctx.context.secretConfig,
+		data: JSON.parse(key.privateKey)
+	}).catch(() => {
+		throw new BetterAuthError("Failed to decrypt private key. Make sure the secret currently in use is the same as the one used to encrypt the private key. If you are using a different secret, either clean up your JWKS or disable private key encryption.");
+	}) : key.privateKey;
+	const alg = key.alg ?? options?.jwks?.keyPairConfig?.alg ?? "EdDSA";
+	const privateKey = await importJWK(JSON.parse(privateWebKey), alg);
+	return {
+		alg,
+		kid: key.id,
+		privateKey
+	};
+}
+async function signJWT(ctx, config) {
+	const { options } = config;
+	const payload = config.payload;
+	const nowSeconds = Math.floor(Date.now() / 1e3);
+	const iat = payload.iat;
+	let exp = payload.exp;
+	const defaultExp = toExpJWT(options?.jwt?.expirationTime ?? "15m", iat ?? nowSeconds);
+	exp = exp ?? defaultExp;
+	const nbf = payload.nbf;
+	const baseURLOrigin = typeof ctx.context.options.baseURL === "string" ? ctx.context.options.baseURL : "";
+	const iss = payload.iss;
+	const defaultIss = options?.jwt?.issuer ?? baseURLOrigin;
+	const aud = payload.aud;
+	const defaultAud = options?.jwt?.audience ?? baseURLOrigin;
+	if (options?.jwt?.sign) {
+		const jwtPayload = {
+			...payload,
+			iat,
+			exp,
+			nbf,
+			iss: iss ?? defaultIss,
+			aud: aud ?? defaultAud
+		};
+		return options.jwt.sign(jwtPayload, config.header, {
+			signingKeyId: config.signingKeyId,
+			signingAlgorithm: config.signingAlgorithm
+		});
+	}
+	const { alg, kid, privateKey } = config.resolvedKey ?? await resolveSigningKey(ctx, options, {
+		signingKeyId: config.signingKeyId,
+		signingAlgorithm: config.signingAlgorithm
+	});
+	const jwt = new SignJWT(payload).setProtectedHeader({
+		...config.header,
+		alg,
+		kid
+	}).setExpirationTime(exp).setIssuer(iss ?? defaultIss).setAudience(aud ?? defaultAud);
+	if (iat) jwt.setIssuedAt(iat);
+	if (payload.sub) jwt.setSubject(payload.sub);
+	if (payload.nbf) jwt.setNotBefore(payload.nbf);
+	if (payload.jti) jwt.setJti(payload.jti);
+	return await jwt.sign(privateKey);
+}
+async function getJwtToken(ctx, options) {
+	const payload = !options?.jwt?.definePayload ? ctx.context.session.user : await options.jwt.definePayload(ctx.context.session);
+	return await signJWT(ctx, {
+		options,
+		payload: {
+			iat: Math.floor(Date.now() / 1e3),
+			...payload,
+			sub: await options?.jwt?.getSubject?.(ctx.context.session) ?? ctx.context.session.user.id
+		}
+	});
+}
+//#endregion
+export { getJwtToken, resolveSigningKey, signJWT };