@estifanos-sh/convex-auth 0.0.1-preview.0

package/dist/server/token/refresh.js

@@ -0,0 +1,35 @@
+import { ErrorCode } from "../../shared/codes.js";
+import { envOptionalNumber, readConfigSync } from "../env.js";
+import { maybeRedact } from "../log.js";
+import { ConvexError } from "convex/values";
+
+//#region src/server/token/refresh.ts
+const REFRESH_TOKEN_DIVIDER = "|";
+/** @internal Encode the `(refreshTokenId, sessionId)` pair into a refresh token. */
+const encodeRefreshToken = (refreshTokenId, sessionId) => `${refreshTokenId}${REFRESH_TOKEN_DIVIDER}${sessionId}`;
+const DEFAULT_SESSION_INACTIVE_DURATION_MS = 1e3 * 60 * 60 * 24 * 30;
+/** @internal */
+const REFRESH_TOKEN_REUSE_WINDOW_MS = 10 * 1e3;
+const refreshTokenExpirationTime = (config, now = Date.now()) => now + (config.session?.inactiveDurationMs ?? readConfigSync(envOptionalNumber("AUTH_SESSION_INACTIVE_DURATION_MS")) ?? DEFAULT_SESSION_INACTIVE_DURATION_MS);
+/** @internal */
+const parseRefreshToken = (refreshToken) => {
+	const parts = refreshToken.split(REFRESH_TOKEN_DIVIDER);
+	const message = `Can't parse refresh token: ${maybeRedact(refreshToken)}`;
+	if (parts.length !== 2) throw new ConvexError({
+		code: ErrorCode.INVALID_REFRESH_TOKEN,
+		message
+	});
+	const [refreshTokenId, sessionId] = parts;
+	if (refreshTokenId == null || sessionId == null) throw new ConvexError({
+		code: ErrorCode.INVALID_REFRESH_TOKEN,
+		message
+	});
+	return {
+		refreshTokenId,
+		sessionId
+	};
+};
+
+//#endregion
+export { REFRESH_TOKEN_REUSE_WINDOW_MS, encodeRefreshToken, parseRefreshToken, refreshTokenExpirationTime };
+//# sourceMappingURL=refresh.js.map

package/dist/server/tokens.js

@@ -0,0 +1,164 @@
+import { envOptionalString, requireEnv } from "./env.js";
+import { authUrlFromEnv } from "./url.js";
+import { generateRandomString } from "./random.js";
+import { withSpan } from "./utils/span.js";
+import { SignJWT, createLocalJWKSet, importPKCS8, jwtVerify } from "jose";
+
+//#region src/server/tokens.ts
+const DEFAULT_JWT_DURATION_MS = 1e3 * 60 * 60;
+const TOKEN_JTI_LENGTH = 24;
+const TOKEN_JTI_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+let cachedPrivateKeyPromise = null;
+const cachedIssuers = /* @__PURE__ */ new Map();
+const JWT_ALG = "EdDSA";
+function normalizePkcs8Pem(value) {
+	const trimmed = value.trim();
+	if (!trimmed.includes("-----BEGIN PRIVATE KEY-----")) return trimmed;
+	const withEscapedNewlines = trimmed.replace(/\\n/g, "\n");
+	if (withEscapedNewlines.includes("\n")) return withEscapedNewlines;
+	const beginMarker = "-----BEGIN PRIVATE KEY-----";
+	const endMarker = "-----END PRIVATE KEY-----";
+	const body = trimmed.replace(beginMarker, "").replace(endMarker, "").trim().replace(/\s+/g, "");
+	if (body.length === 0) return trimmed;
+	return `${beginMarker}\n${body.match(/.{1,64}/g)?.join("\n") ?? body}\n${endMarker}`;
+}
+const getPrivateKey = () => {
+	if (cachedPrivateKeyPromise === null) try {
+		cachedPrivateKeyPromise = importPKCS8(normalizePkcs8Pem(requireEnv("JWT_PRIVATE_KEY")), JWT_ALG).catch((error) => {
+			cachedPrivateKeyPromise = null;
+			throw error;
+		});
+	} catch (error) {
+		cachedPrivateKeyPromise = null;
+		throw error;
+	}
+	return cachedPrivateKeyPromise;
+};
+const getIssuer = (path) => {
+	const key = path ?? "";
+	let issuer = cachedIssuers.get(key);
+	if (issuer === void 0) {
+		issuer = authUrlFromEnv(path);
+		cachedIssuers.set(key, issuer);
+	}
+	return issuer;
+};
+if (envOptionalString("JWT_PRIVATE_KEY")) try {
+	getPrivateKey().catch((err) => {
+		console.error("[auth] JWT private key pre-warm failed", { err });
+	});
+} catch (err) {
+	console.error("[auth] JWT private key pre-warm threw synchronously", { err });
+}
+if (envOptionalString("CONVEX_SITE_URL")) try {
+	getIssuer();
+} catch (err) {
+	console.error("[auth] JWT issuer pre-warm threw", { err });
+}
+/** Lifetime of an issued OAuth access token, in seconds. Shared with the token endpoint's `expires_in`. */
+const OAUTH_ACCESS_TOKEN_DURATION_S = 900;
+/**
+* Sign an OAuth access token (EdDSA) for the given user, client, and scopes.
+*
+* The `aud` claim is `"convex"` so the token is a valid Convex identity
+* (`applicationID: "convex"`) — load-bearing: MCP tools run the user's queries
+* via `ctx.runQuery`, which requires Convex's identity layer to accept this
+* token. For that reason the access token must look like an ID-token-shaped JWT:
+* it carries NO `typ: "at+jwt"` header (Convex's validator rejects that RFC 9068
+* type), and is instead marked as an access token by a positive `token_use:
+* "access"` claim, which `verifyOAuthToken` checks (alongside the `client_id`
+* claim) to tell it apart from a session token. We don't issue OIDC ID tokens,
+* so there is no id-vs-access confusion for the `at+jwt` typ to guard against.
+*
+* When an RFC 8707 `resource` is supplied the token carries a `resource` claim
+* binding it to that protected resource; an MCP endpoint rejects tokens whose
+* `resource` does not match its own canonical resource.
+*
+* @internal
+*/
+async function generateOAuthToken(args) {
+	const privateKey = await withSpan("convex-auth.tokens.import-key", { alg: JWT_ALG }, () => getPrivateKey());
+	const exp = new Date(Date.now() + OAUTH_ACCESS_TOKEN_DURATION_S * 1e3);
+	return await withSpan("convex-auth.tokens.sign-oauth", { alg: JWT_ALG }, () => new SignJWT({
+		sub: args.userId,
+		aud: "convex",
+		token_use: "access",
+		scope: args.scopes.join(" "),
+		client_id: args.clientId,
+		...args.resource !== void 0 ? { resource: args.resource } : null
+	}).setProtectedHeader({ alg: JWT_ALG }).setIssuedAt().setJti(generateRandomString(TOKEN_JTI_LENGTH, TOKEN_JTI_ALPHABET)).setIssuer(args.issuer ?? getIssuer()).setExpirationTime(exp).sign(privateKey));
+}
+let cachedKeySet = null;
+/**
+* The local JWKS keyset, built once and reused. The `JWKS` env is static per
+* deployment, so caching also preserves jose's internal imported-key cache
+* across requests rather than re-importing keys on every verification.
+*/
+function getJwkSet() {
+	if (cachedKeySet === null) cachedKeySet = createLocalJWKSet(JSON.parse(requireEnv("JWKS")));
+	return cachedKeySet;
+}
+/**
+* Verify an OAuth access token against the local JWKS and issuer.
+*
+* When `opts.resource` is supplied, the token's RFC 8707 `resource` claim must
+* equal it exactly — a token bound to a different (or no) resource is rejected.
+* This is how an MCP endpoint enforces that a token was issued for *it*.
+*
+* @returns The token's user, client, scopes, and bound `resource`, or `null` if
+*   verification fails, the token is not an OAuth access token, or the resource
+*   assertion does not hold.
+* @internal
+*/
+async function verifyOAuthToken(token, opts) {
+	try {
+		const { payload } = await jwtVerify(token, getJwkSet(), {
+			issuer: opts?.issuer ?? getIssuer(),
+			audience: "convex",
+			algorithms: [JWT_ALG],
+			clockTolerance: 30
+		});
+		if (payload.token_use !== "access") return null;
+		const userId = payload.sub;
+		const clientId = payload.client_id;
+		const scope = payload.scope ?? "";
+		if (!userId || !clientId) return null;
+		const resourceClaim = payload.resource;
+		const resource = typeof resourceClaim === "string" ? resourceClaim : null;
+		if (opts?.resource !== void 0 && resource !== opts.resource) return null;
+		return {
+			userId,
+			clientId,
+			scopes: scope ? scope.split(" ") : [],
+			resource
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Sign a session access token (EdDSA) carrying the identity claims, audienced to Convex.
+*
+* Expiry is `config.jwt.durationMs` from now, defaulting to one hour.
+*
+* @internal
+*/
+async function generateToken(args, config) {
+	const privateKey = await withSpan("convex-auth.tokens.import-key", { alg: JWT_ALG }, () => getPrivateKey());
+	const expirationTime = new Date(Date.now() + (config.jwt?.durationMs ?? DEFAULT_JWT_DURATION_MS));
+	const claims = {
+		sub: args.identity.subject,
+		sid: args.identity.sessionId,
+		...args.identity.name !== void 0 ? { name: args.identity.name } : null,
+		...args.identity.email !== void 0 ? { email: args.identity.email } : null,
+		...args.identity.emailVerified !== void 0 ? { email_verified: args.identity.emailVerified } : null,
+		...args.identity.picture !== void 0 ? { picture: args.identity.picture } : null,
+		...args.identity.phoneNumber !== void 0 ? { phone_number: args.identity.phoneNumber } : null,
+		...args.identity.phoneNumberVerified !== void 0 ? { phone_number_verified: args.identity.phoneNumberVerified } : null
+	};
+	return await withSpan("convex-auth.tokens.sign", { alg: JWT_ALG }, () => new SignJWT(claims).setProtectedHeader({ alg: JWT_ALG }).setIssuedAt().setJti(generateRandomString(TOKEN_JTI_LENGTH, TOKEN_JTI_ALPHABET)).setIssuer(getIssuer(config.path)).setAudience("convex").setExpirationTime(expirationTime).sign(privateKey));
+}
+
+//#endregion
+export { OAUTH_ACCESS_TOKEN_DURATION_S, generateOAuthToken, generateToken, verifyOAuthToken };
+//# sourceMappingURL=tokens.js.map

package/dist/server/totp.js

@@ -0,0 +1,282 @@
+import { ErrorCode } from "../shared/codes.js";
+import { getAuthenticatedUserIdOrNull } from "./identity/claims.js";
+import { queueAuthEvent } from "./events.js";
+import { encodeRefreshToken, refreshTokenExpirationTime } from "./token/refresh.js";
+import { setActiveSpanAttributes } from "./utils/span.js";
+import { buildSessionIdentity, finalizeSessionIssuance, getAuthSessionId, sessionExpirationTime } from "./session/lifecycle.js";
+import { authFlowError } from "../shared/errors.js";
+import { toConvexError } from "./errors.js";
+import { maxSignInAttempts } from "./limits.js";
+import { buildKnownSignInIdentityAttributes } from "./telemetry.js";
+import { decryptSecret, encryptSecret } from "./secret.js";
+import { ConvexError } from "convex/values";
+import { decodeBase64urlIgnorePadding, encodeBase32LowerCaseNoPadding, encodeBase64urlNoPadding } from "@oslojs/encoding";
+import { createTOTPKeyURI, verifyTOTPWithGracePeriod } from "@oslojs/otp";
+
+//#region src/server/totp.ts
+/**
+* Server-side TOTP ceremony logic for two-factor authentication.
+*
+* Two single-word flows:
+*
+* - `setup`  — generate a TOTP secret and `otpauth://` URI for enrollment.
+* - `verify` — consume a TOTP code. Auto-detects:
+*     - first-time enrollment confirmation (caller passes `totpId`), or
+*     - 2FA sign-in challenge (no `totpId`).
+*/
+const TOTP_FLOWS = ["setup", "verify"];
+const convexError = (code, message) => toConvexError(authFlowError(code, message));
+const asConvexError = (error, code, message) => error instanceof ConvexError ? error : error instanceof Error ? toConvexError(authFlowError(code, error.message || message)) : convexError(code, message);
+/**
+* Encrypt a raw TOTP secret for storage. The secret bytes are base64url-encoded
+* and sealed with the server's {@link encryptSecret} (AES-GCM); the resulting
+* ciphertext string is stored UTF-8-encoded in the `TotpFactor.secret` bytes
+* field. Runs server-side because component functions cannot read
+* `AUTH_SECRET_ENCRYPTION_KEY`.
+*/
+async function encryptTotpSecret(secret) {
+	const ciphertext = await encryptSecret(encodeBase64urlNoPadding(secret));
+	const encoded = new TextEncoder().encode(ciphertext);
+	return encoded.buffer.slice(encoded.byteOffset, encoded.byteOffset + encoded.byteLength);
+}
+/**
+* Reverse {@link encryptTotpSecret}: decode the stored ciphertext bytes, decrypt
+* to the base64url secret, and return the raw secret bytes for verification.
+*/
+async function decryptTotpSecret(stored) {
+	return decodeBase64urlIgnorePadding(await decryptSecret(new TextDecoder().decode(stored)));
+}
+function resolveTotpFlow(params) {
+	const flow = params.flow;
+	if (typeof flow === "string" && TOTP_FLOWS.includes(flow)) return flow;
+	throw convexError(ErrorCode.TOTP_MISSING_FLOW, "Missing `flow` parameter. Expected one of: " + TOTP_FLOWS.join(", "));
+}
+function requireTotpVerifier(verifier) {
+	if (verifier != null) return verifier;
+	throw convexError(ErrorCode.TOTP_MISSING_VERIFIER, "Missing verifier for TOTP operation.");
+}
+function requireTotpCode(params) {
+	if (typeof params.code === "string") return params.code;
+	throw convexError(ErrorCode.TOTP_MISSING_CODE, "Missing TOTP code.");
+}
+function resolveTotpDispatch(params, verifier) {
+	if (resolveTotpFlow(params) === "setup") return {
+		flow: "setup",
+		params
+	};
+	const resolvedVerifier = requireTotpVerifier(verifier);
+	const code = requireTotpCode(params);
+	if (typeof params.totpId === "string" && params.totpId.length > 0) return {
+		flow: "verify",
+		code,
+		totpId: params.totpId,
+		verifier: resolvedVerifier,
+		intent: "enrollment"
+	};
+	return {
+		flow: "verify",
+		code,
+		verifier: resolvedVerifier,
+		intent: "challenge"
+	};
+}
+async function requireAuthenticatedUserId(ctx) {
+	try {
+		const userId = await getAuthenticatedUserIdOrNull(ctx);
+		if (userId === null) throw convexError(ErrorCode.TOTP_AUTH_REQUIRED, "Sign in first, then set up two-factor authentication.");
+		return userId;
+	} catch (error) {
+		if (error instanceof ConvexError) throw error;
+		throw asConvexError(error, ErrorCode.INTERNAL_ERROR, String(error));
+	}
+}
+/**
+* Drive the TOTP provider's `setup` / `verify` flow.
+*
+* `setup` issues an enrollment secret and `otpauth://` URI; `verify` either
+* confirms a first-time enrollment (when `params.totpId` is present) or
+* completes a 2FA challenge during sign-in.
+*
+* @internal
+*/
+const handleTotp = async (ctx, provider, args) => {
+	const dispatch = resolveTotpDispatch(args.params ?? {}, args.verifier);
+	const flowHandlers = {
+		setup: async () => {
+			const { params: setupParams } = dispatch;
+			const userId = await requireAuthenticatedUserId(ctx);
+			const secret = new Uint8Array(20);
+			crypto.getRandomValues(secret);
+			const base32Secret = encodeBase32LowerCaseNoPadding(secret);
+			let enrollment;
+			try {
+				enrollment = await ctx.runMutation(ctx.auth.config.component.factor.totp.createEnrollment, {
+					userId,
+					secret: await encryptTotpSecret(secret),
+					digits: provider.options.digits,
+					period: provider.options.period,
+					name: typeof setupParams.name === "string" ? setupParams.name : void 0,
+					createdAt: Date.now()
+				});
+			} catch (error) {
+				throw asConvexError(error, ErrorCode.INTERNAL_ERROR, `TOTP setup failed: ${String(error)}`);
+			}
+			const accountName = typeof setupParams.accountName === "string" && setupParams.accountName.length > 0 ? setupParams.accountName : enrollment.user.email ?? "user";
+			return {
+				kind: "totpSetup",
+				totpSetup: {
+					uri: createTOTPKeyURI(provider.options.issuer, accountName, secret, provider.options.period, provider.options.digits),
+					secret: base32Secret,
+					totpId: enrollment.totpId
+				},
+				verifier: enrollment.verifierId
+			};
+		},
+		verify: async () => {
+			if (dispatch.flow !== "verify") throw convexError(ErrorCode.TOTP_MISSING_FLOW, `Unexpected dispatch: ${dispatch.flow}`);
+			if (dispatch.intent === "enrollment") return await confirmEnrollment(dispatch.code, dispatch.totpId, dispatch.verifier);
+			return await verifyChallenge(dispatch.code, dispatch.verifier);
+		}
+	};
+	/**
+	* `verify` with `totpId`: completes a first-time enrollment after `setup`.
+	* Marks the TOTP factor as verified and signs the user in.
+	*/
+	async function confirmEnrollment(code, totpId, verifier) {
+		const userId = await requireAuthenticatedUserId(ctx);
+		const result = await verifyTotp({
+			code,
+			verifier,
+			intent: "enrollment",
+			authenticatedUserId: userId,
+			totpId
+		});
+		await queueAuthEvent(ctx, ctx.auth.config, {
+			kind: "totp.enrolled",
+			actor: {
+				type: "user",
+				id: userId
+			},
+			subject: {
+				type: "totp",
+				id: totpId
+			},
+			targets: [{
+				kind: "user",
+				id: userId
+			}],
+			outcome: "success",
+			data: { totpId }
+		});
+		return result;
+	}
+	/**
+	* `verify` without `totpId`: completes a 2FA challenge during sign-in.
+	* Looks up the user's verified TOTP factor, validates the code, signs in.
+	*/
+	async function verifyChallenge(code, verifier) {
+		return await verifyTotp({
+			code,
+			verifier,
+			intent: "challenge"
+		});
+	}
+	async function verifyTotp(input) {
+		const begun = await ctx.runMutation(ctx.auth.config.component.factor.totp.beginVerification, {
+			verifierId: input.verifier,
+			intent: input.intent,
+			authenticatedUserId: input.authenticatedUserId,
+			totpId: input.totpId,
+			maxAttemptsPerHour: maxSignInAttempts(ctx.auth.config)
+		});
+		if (begun.status === "invalid_verifier") throw convexError(ErrorCode.TOTP_INVALID_VERIFIER, "Invalid or expired TOTP verifier.");
+		if (begun.status === "limited") throw convexError(ErrorCode.RATE_LIMITED, "Too many TOTP attempts. Try again later.");
+		if (begun.status === "already_verified") throw convexError(ErrorCode.TOTP_ALREADY_VERIFIED, "TOTP enrollment is already verified.");
+		if (begun.status === "not_found") throw convexError(input.intent === "enrollment" ? ErrorCode.TOTP_NOT_FOUND : ErrorCode.TOTP_NO_ENROLLMENT, input.intent === "enrollment" ? "TOTP enrollment not found." : "No verified TOTP enrollment found.");
+		if (begun.status !== "ready") throw convexError(ErrorCode.INTERNAL_ERROR, "Unexpected TOTP verification state.");
+		if (!verifyTOTPWithGracePeriod(await decryptTotpSecret(begun.factor.secret), begun.factor.period, begun.factor.digits, input.code, 30)) throw convexError(ErrorCode.TOTP_INVALID_CODE, "Invalid TOTP code.");
+		const replaceSessionId = await getAuthSessionId(ctx) ?? void 0;
+		const completed = await ctx.runMutation(ctx.auth.config.component.factor.totp.completeVerification, {
+			verifierId: input.verifier,
+			intent: input.intent,
+			authenticatedUserId: input.authenticatedUserId,
+			totpId: input.totpId,
+			replaceSessionId,
+			sessionExpirationTime: sessionExpirationTime(ctx.auth.config),
+			refreshTokenExpirationTime: refreshTokenExpirationTime(ctx.auth.config),
+			now: Date.now()
+		});
+		if (completed.status !== "accepted") throw convexError(ErrorCode.TOTP_INVALID_VERIFIER, "Invalid or expired TOTP verifier.");
+		const userId = completed.user._id;
+		const sessionId = completed.sessionId;
+		setActiveSpanAttributes({
+			"auth.signin.result": "success",
+			...buildKnownSignInIdentityAttributes(ctx.auth.config, {
+				userId,
+				sessionId
+			}, completed.user.email)
+		});
+		if (completed.replacedSessionId !== void 0) {
+			const replacedSessionId = completed.replacedSessionId;
+			await queueAuthEvent(ctx, ctx.auth.config, {
+				kind: "session.invalidated",
+				actor: { type: "system" },
+				subject: {
+					type: "session",
+					id: replacedSessionId
+				},
+				targets: [{
+					kind: "user",
+					id: userId
+				}, {
+					kind: "session",
+					id: replacedSessionId
+				}],
+				outcome: "success",
+				data: {
+					userId,
+					reason: "replaced"
+				}
+			});
+		}
+		await queueAuthEvent(ctx, ctx.auth.config, {
+			kind: "session.signed_in",
+			actor: {
+				type: "user",
+				id: userId
+			},
+			subject: {
+				type: "session",
+				id: sessionId
+			},
+			targets: [{
+				kind: "user",
+				id: userId
+			}, {
+				kind: "session",
+				id: sessionId
+			}],
+			outcome: "success",
+			data: {
+				provider: "session",
+				method: provider.id
+			}
+		});
+		return {
+			kind: "signedIn",
+			session: await finalizeSessionIssuance(ctx.auth.config, {
+				userId,
+				sessionId,
+				identity: buildSessionIdentity(userId, sessionId, completed.user),
+				refreshToken: encodeRefreshToken(completed.refreshTokenId, sessionId)
+			})
+		};
+	}
+	const handler = flowHandlers[dispatch.flow];
+	if (!handler) throw convexError(ErrorCode.TOTP_MISSING_FLOW, `Unknown TOTP flow: ${dispatch.flow}`);
+	return handler();
+};
+
+//#endregion
+export { handleTotp };
+//# sourceMappingURL=totp.js.map