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

package/dist/server/types.js

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

package/dist/server/url.js

@@ -0,0 +1,43 @@
+import { requireEnv } from "./env.js";
+
+//#region src/server/url.ts
+const DEFAULT_AUTH_PATH = "/auth";
+/** @internal */
+function normalizeUrl(url) {
+	return url.replace(/\/$/, "");
+}
+/** @internal */
+function normalizeAuthPath(path) {
+	if (path === void 0 || path.trim() === "") return DEFAULT_AUTH_PATH;
+	const trimmed = path.trim();
+	if (trimmed === "/") return "";
+	return `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
+}
+/** @internal */
+function authUrl(siteUrl, path) {
+	return `${normalizeUrl(siteUrl)}${normalizeAuthPath(path)}`;
+}
+/** @internal */
+function authUrlFromEnv(path) {
+	return authUrl(requireEnv("CONVEX_SITE_URL"), path);
+}
+/** @internal */
+function appUrlFromEnv() {
+	return normalizeUrl(requireEnv("APP_URL"));
+}
+/** @internal */
+function isLocalHost(host) {
+	if (host === void 0) return false;
+	const raw = host.includes("://") ? host : `http://${host}`;
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		return false;
+	}
+	return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+}
+
+//#endregion
+export { appUrlFromEnv, authUrlFromEnv, isLocalHost, normalizeAuthPath, normalizeUrl };
+//# sourceMappingURL=url.js.map

package/dist/server/user/account.js

@@ -0,0 +1,325 @@
+import { LOG_LEVELS } from "../../shared/log.js";
+import { ErrorCode } from "../../shared/codes.js";
+import { queueAuthEvent } from "../events.js";
+import { authDb } from "../db.js";
+import { log } from "../log.js";
+import { ConvexError } from "convex/values";
+
+//#region src/server/user/account.ts
+function mergeExtend(existing, incoming) {
+	if (!incoming) return;
+	const existingRecord = typeof existing === "object" && existing !== null && !Array.isArray(existing) ? existing : void 0;
+	return existingRecord ? {
+		...existingRecord,
+		...incoming
+	} : incoming;
+}
+function effectiveUserUpdateMode(source, policy, providerUpdateProfileOnLogin) {
+	const authority = policy?.authority ?? "app";
+	let mode = source === "login" ? policy?.updateProfileOnLogin ?? "missing" : policy?.updateProfileFromScim ?? "always";
+	if (source === "login" && policy === void 0 && providerUpdateProfileOnLogin !== void 0) mode = providerUpdateProfileOnLogin === false ? "never" : "always";
+	if (authority === "app") return mode === "never" ? "never" : "missing";
+	if (authority === "connection" && source === "scim") return mode === "never" ? "never" : "missing";
+	if (authority === "scim" && source === "login") return mode === "never" ? "never" : "missing";
+	return mode;
+}
+function isUserFieldMissing(value) {
+	return value === void 0 || value === null || value === "";
+}
+function buildUserPatchData(args) {
+	if (args.mode === "never") return {};
+	if (args.mode === "always") return args.nextUser;
+	return Object.fromEntries(Object.entries(args.nextUser).filter(([key, value]) => {
+		if (value === void 0) return false;
+		return isUserFieldMissing(args.currentUser[key]);
+	}));
+}
+/**
+* Resolve (create, link, or update) the user for a sign-in and ensure the
+* provider account row exists, returning both IDs.
+*
+* Security: an OAuth provider whose `accountLinking` is `"sameConnection"`
+* (the default for Connection connections) never globally merges users by
+* email across IdPs/tenants. Such a connection may only link to a user it
+* already owns via its own account/externalId (resolved upstream as
+* `existingAccount`/`opts.existingUserId`); the email is still recorded as
+* verified on the resolved user, but cross-user email linking is disabled.
+*
+* @param account - Either an already-resolved existing account, or the
+*   `providerAccountId` (and optional secret) to create/link one.
+* @param opts.existingUserId - Pre-resolved user (e.g. from SCIM externalId).
+* @param opts.source - Provisioning source (`"login"` or `"scim"`), affecting
+*   the profile-update policy.
+* @internal
+*/
+async function upsertUserAndAccount(ctx, sessionId, account, args, config, opts) {
+	const userId = await defaultCreateOrUpdateUser(ctx, sessionId, "existingAccount" in account ? account.existingAccount : null, args, config, opts?.existingUserId ?? null, opts?.provisioningUser, opts?.source ?? "login");
+	return {
+		userId,
+		accountId: await createOrUpdateAccount(ctx, userId, account, args, config)
+	};
+}
+async function resolveUserIdByLinking(ctx, args, profile, shouldLinkViaEmail, shouldLinkViaPhone, existingUserIdOverride, config) {
+	const [emailLookup, phoneLookup] = await Promise.all([typeof profile.email === "string" && shouldLinkViaEmail ? uniqueUserWithVerifiedEmail(ctx, profile.email, config) : Promise.resolve(null), typeof profile.phone === "string" && shouldLinkViaPhone ? uniqueUserWithVerifiedPhone(ctx, profile.phone, config) : Promise.resolve(null)]);
+	const emailUserId = emailLookup?._id ?? null;
+	const phoneUserId = phoneLookup?._id ?? null;
+	if (emailUserId !== null && phoneUserId !== null) {
+		if (emailUserId === phoneUserId) {
+			log(LOG_LEVELS.DEBUG, `Email and phone resolve to same user, linking: ${emailUserId}`);
+			return emailUserId;
+		}
+		throw new ConvexError({
+			code: ErrorCode.AMBIGUOUS_USER_LINK,
+			message: "Verified email and phone resolve to different users; cannot safely link."
+		});
+	}
+	if (emailUserId !== null) {
+		log(LOG_LEVELS.DEBUG, `Found existing email verified user, linking: ${emailUserId}`);
+		return emailUserId;
+	}
+	if (phoneUserId !== null) {
+		log(LOG_LEVELS.DEBUG, `Found existing phone verified user, linking: ${phoneUserId}`);
+		return phoneUserId;
+	}
+	log(LOG_LEVELS.DEBUG, "No existing verified users found, creating new user");
+	return existingUserIdOverride;
+}
+async function checkAllowLink(args, config, userId) {
+	const isConnectionLink = args.provider.type === "oauth" || args.provider.type === "connection";
+	const isCredentialsLink = args.provider.type === "credentials";
+	if (config.connection?.hooks?.allowLink === void 0 || !isConnectionLink && !isCredentialsLink) return true;
+	return await config.connection.hooks.allowLink({
+		protocol: isCredentialsLink ? "credentials" : args.provider.type === "oauth" && typeof args.accountExtend?.identity?.protocol === "string" ? args.accountExtend.identity.protocol : "oidc",
+		connectionId: typeof args.accountExtend?.identity?.connectionId === "string" ? args.accountExtend.identity.connectionId : void 0,
+		profile: args.profile,
+		userId
+	}) !== false;
+}
+/**
+* Persist the emails this sign-in asserts onto the resolved user.
+*
+* The profile's primary email is recorded as the primary `UserEmail`
+* row; any provider-reported secondaries (e.g. GitHub `/user/emails`)
+* are recorded non-primary, each keeping its own verified state.
+* Provenance (`source`, `provider`, `connectionId`) is captured so Connection
+* linking can stay connection-scoped.
+*
+* @param db - The component-backed auth DB facade.
+* @param userId - The resolved (created or linked) user.
+* @param args - The create-or-update args (provider, accountExtend, emails).
+* @param profile - The provisioned profile (already destructured).
+* @param emailVerified - Whether the primary email is verified.
+*/
+async function recordOwnedEmails(db, userId, args, profile, emailVerified) {
+	const identity = args.accountExtend?.identity;
+	const protocol = typeof identity?.protocol === "string" ? identity.protocol : void 0;
+	const source = protocol === "saml" ? "saml" : protocol === "oidc" ? "oidc" : args.provider.type === "oauth" ? "oauth" : "password";
+	const provider = typeof args.provider.id === "string" ? args.provider.id : void 0;
+	const connectionId = typeof identity?.connectionId === "string" ? identity.connectionId : void 0;
+	const primaryEmail = typeof profile.email === "string" ? profile.email.toLowerCase() : null;
+	if (primaryEmail !== null) await db.emails.upsert({
+		userId,
+		email: primaryEmail,
+		verified: emailVerified,
+		isPrimary: true,
+		source,
+		provider,
+		connectionId
+	});
+	for (const entry of args.emails ?? []) {
+		const addr = entry.email.toLowerCase();
+		if (addr === primaryEmail) continue;
+		await db.emails.upsert({
+			userId,
+			email: addr,
+			verified: entry.verified === true,
+			isPrimary: false,
+			source,
+			provider,
+			connectionId
+		});
+	}
+}
+async function updateExistingUser(db, userId, userData, source, provisioningUser, providerUpdateProfileOnLogin) {
+	const currentUser = await db.users.get({ id: userId });
+	const mode = effectiveUserUpdateMode(source, provisioningUser, providerUpdateProfileOnLogin);
+	const patchData = buildUserPatchData({
+		currentUser: currentUser ?? {},
+		nextUser: userData,
+		mode
+	});
+	if (Object.keys(patchData).length === 0) return;
+	try {
+		await db.users.update(userId, patchData);
+	} catch (error) {
+		throw new ConvexError({
+			code: ErrorCode.USER_UPDATE_FAILED,
+			message: `Could not update user document with ID \`${userId}\`, either the user has been deleted but their account has not, or the profile data doesn't match the \`users\` table schema: ${error instanceof Error ? error.message : String(error)}`
+		});
+	}
+}
+async function defaultCreateOrUpdateUser(ctx, existingSessionId, existingAccount, args, config, existingUserIdOverride, provisioningUser, source) {
+	log(LOG_LEVELS.DEBUG, "defaultCreateOrUpdateUser args:", {
+		existingAccountId: existingAccount?._id,
+		existingSessionId,
+		args: {
+			...args,
+			provider: {
+				id: args.provider.id,
+				type: args.provider.type
+			}
+		}
+	});
+	const existingUserId = existingAccount?.userId ?? null;
+	const db = authDb(ctx, config);
+	const { provider, profile: { id: _profileId, emailVerified: profileEmailVerified, phoneVerified: profilePhoneVerified, ...profile } } = args;
+	const emailVerified = profileEmailVerified === true;
+	const phoneVerified = profilePhoneVerified ?? false;
+	const connectionScopedLinking = provider.type === "oauth" && provider.accountLinking === "sameConnection";
+	const shouldLinkViaEmail = !connectionScopedLinking && (args.shouldLinkViaEmail || emailVerified || provider.type === "email");
+	const shouldLinkViaPhone = !connectionScopedLinking && (args.shouldLinkViaPhone || phoneVerified || provider.type === "phone");
+	let userId = existingUserId ?? existingUserIdOverride;
+	if (existingUserId === null) {
+		userId = await resolveUserIdByLinking(ctx, args, profile, shouldLinkViaEmail, shouldLinkViaPhone, existingUserIdOverride, config);
+		if (userId !== null && !await checkAllowLink(args, config, userId)) userId = null;
+	}
+	const userData = {
+		...emailVerified ? { emailVerificationTime: Date.now() } : null,
+		...phoneVerified ? { phoneVerificationTime: Date.now() } : null,
+		...profile
+	};
+	const existingOrLinkedUserId = userId;
+	if (userId !== null) {
+		const providerUpdateProfileOnLogin = args.provider.type === "oauth" ? args.provider.updateProfileOnLogin ?? true : void 0;
+		await updateExistingUser(db, userId, userData, source, provisioningUser, providerUpdateProfileOnLogin);
+	} else {
+		if (source === "login" && provisioningUser?.createOnSignIn === false) throw new ConvexError({
+			code: ErrorCode.NOT_AUTHORIZED,
+			message: "This Connection connection does not allow creating users on sign-in."
+		});
+		userId = await db.users.create(userData);
+	}
+	await recordOwnedEmails(db, userId, args, profile, emailVerified === true);
+	log(LOG_LEVELS.DEBUG, "Emitting auth event for user lifecycle change");
+	if (existingOrLinkedUserId === null) await queueAuthEvent(ctx, config, {
+		kind: "user.created",
+		actor: { type: "system" },
+		subject: {
+			type: "user",
+			id: userId
+		},
+		targets: [{
+			kind: "user",
+			id: userId
+		}],
+		outcome: "success",
+		data: {
+			type: args.type,
+			provider: args.provider.id,
+			profile: args.profile
+		}
+	});
+	else await queueAuthEvent(ctx, config, {
+		kind: "user.updated",
+		actor: { type: "system" },
+		subject: {
+			type: "user",
+			id: userId
+		},
+		targets: [{
+			kind: "user",
+			id: userId
+		}],
+		outcome: "success",
+		data: {
+			existingUserId: existingOrLinkedUserId,
+			type: args.type,
+			provider: args.provider.id,
+			profile: args.profile
+		}
+	});
+	if (emailVerified && typeof args.profile.email === "string") await queueAuthEvent(ctx, config, {
+		kind: "email.verified",
+		actor: { type: "system" },
+		subject: {
+			type: "email",
+			id: args.profile.email
+		},
+		targets: [{
+			kind: "user",
+			id: userId
+		}],
+		outcome: "success",
+		data: {
+			userId,
+			email: args.profile.email
+		}
+	});
+	if (phoneVerified && typeof args.profile.phone === "string") await queueAuthEvent(ctx, config, {
+		kind: "phone.verified",
+		actor: { type: "system" },
+		subject: {
+			type: "phone",
+			id: args.profile.phone
+		},
+		targets: [{
+			kind: "user",
+			id: userId
+		}],
+		outcome: "success",
+		data: {
+			userId,
+			phone: args.profile.phone
+		}
+	});
+	return userId;
+}
+async function uniqueUserWithVerifiedEmail(ctx, email, config) {
+	return await authDb(ctx, config).users.get({ verifiedEmail: email });
+}
+async function uniqueUserWithVerifiedPhone(ctx, phone, config) {
+	return await authDb(ctx, config).users.get({ verifiedPhone: phone });
+}
+async function createOrUpdateAccount(ctx, userId, account, args, config) {
+	const db = authDb(ctx, config);
+	const mergedExtend = "existingAccount" in account ? mergeExtend(account.existingAccount.extend, args.accountExtend) : args.accountExtend;
+	const isNewAccount = !("existingAccount" in account);
+	const accountId = "existingAccount" in account ? account.existingAccount._id : await db.accounts.create({
+		userId,
+		provider: args.provider.id,
+		providerAccountId: account.providerAccountId,
+		secret: account.secret,
+		extend: mergedExtend
+	});
+	if (isNewAccount) await queueAuthEvent(ctx, config, {
+		kind: "account.linked",
+		actor: {
+			type: "user",
+			id: userId
+		},
+		subject: {
+			type: "account",
+			id: accountId
+		},
+		targets: [{
+			kind: "user",
+			id: userId
+		}],
+		outcome: "success",
+		data: {
+			provider: args.provider.id,
+			providerAccountId: account.providerAccountId
+		}
+	});
+	if ("existingAccount" in account && account.existingAccount.userId !== userId) await db.accounts.update(accountId, { userId });
+	const accountPatchData = {};
+	if (mergedExtend) accountPatchData.extend = mergedExtend;
+	if (args.profile.emailVerified) accountPatchData.emailVerified = args.profile.email;
+	if (args.profile.phoneVerified) accountPatchData.phoneVerified = args.profile.phone;
+	if (Object.keys(accountPatchData).length > 0) await db.accounts.update(accountId, accountPatchData);
+	return accountId;
+}
+
+//#endregion
+export { upsertUserAndAccount };
+//# sourceMappingURL=account.js.map

package/dist/server/utils/bearer.js

@@ -0,0 +1,24 @@
+//#region src/server/utils/bearer.ts
+/**
+* Extract a bearer token from an HTTP `Authorization` header.
+*
+* @module
+*/
+const BEARER_PATTERN = /^Bearer\s+(.+)$/i;
+/**
+* Return the bearer token carried in a request's `Authorization` header, or
+* `null` when the header is absent or does not use the `Bearer` scheme.
+*
+* The scheme is matched case-insensitively per RFC 6750, and the captured
+* token is trimmed of surrounding whitespace.
+*/
+function extractBearerToken(request) {
+	const header = request.headers.get("Authorization");
+	if (header === null) return null;
+	const match = BEARER_PATTERN.exec(header);
+	return match ? match[1].trim() : null;
+}
+
+//#endregion
+export { extractBearerToken };
+//# sourceMappingURL=bearer.js.map

package/dist/server/utils/cache.js

@@ -0,0 +1,51 @@
+//#region src/server/utils/cache.ts
+/**
+* Create a synchronous TTL cache.
+*
+* ```ts
+* const jwksCache = createCache({
+*   capacity: 128,
+*   timeToLiveMs: 60 * 60 * 1000,
+*   lookup: (url) => createRemoteJWKSet(new URL(url)),
+* });
+* const jwks = jwksCache.get(url);
+* ```
+*/
+function createCache(opts) {
+	const { capacity, timeToLiveMs, lookup } = opts;
+	const store = /* @__PURE__ */ new Map();
+	function evictExpired() {
+		const now = Date.now();
+		for (const [key, entry] of store) if (entry.expiresAt <= now) store.delete(key);
+	}
+	function evictOldest() {
+		if (store.size < capacity) return;
+		const firstKey = store.keys().next().value;
+		if (firstKey !== void 0) store.delete(firstKey);
+	}
+	return {
+		get(key) {
+			const existing = store.get(key);
+			if (existing && existing.expiresAt > Date.now()) return existing.value;
+			if (existing) store.delete(key);
+			evictExpired();
+			evictOldest();
+			const value = lookup(key);
+			store.set(key, {
+				value,
+				expiresAt: Date.now() + timeToLiveMs
+			});
+			return value;
+		},
+		invalidate(key) {
+			store.delete(key);
+		},
+		clear() {
+			store.clear();
+		}
+	};
+}
+
+//#endregion
+export { createCache };
+//# sourceMappingURL=cache.js.map

package/dist/server/utils/retry.js

@@ -0,0 +1,3 @@
+import { retryWithBackoff } from "../../shared/retry.js";
+
+export { retryWithBackoff };

package/dist/server/utils/span.js

@@ -0,0 +1,59 @@
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+
+//#region src/server/utils/span.ts
+/**
+* Thin wrapper around `@opentelemetry/api` tracing.
+*
+* @module
+*/
+const tracer = trace.getTracer("convex-auth");
+const INVALID_TRACE_ID = "00000000000000000000000000000000";
+const ACTIVE_CHECK_INTERVAL_MS = 5e3;
+let cachedActiveAt = 0;
+let cachedActive = false;
+function isTracingActive() {
+	const now = Date.now();
+	if (now - cachedActiveAt < ACTIVE_CHECK_INTERVAL_MS) return cachedActive;
+	const probe = tracer.startSpan("__convex-auth.probe");
+	const active = probe.isRecording() || probe.spanContext().traceId !== INVALID_TRACE_ID;
+	probe.end();
+	cachedActive = active;
+	cachedActiveAt = now;
+	return active;
+}
+/**
+* Run `fn` inside an OpenTelemetry span.
+*
+* If `fn` throws, the span is marked as errored and the exception is
+* recorded before re-throwing.
+*
+* When no tracer provider is registered, this is a cheap passthrough that
+* skips span creation altogether.
+*/
+async function withSpan(name, attributes, fn) {
+	if (!isTracingActive()) return fn();
+	return tracer.startActiveSpan(name, { attributes }, async (span) => {
+		try {
+			return await fn();
+		} catch (error) {
+			span.setStatus({ code: SpanStatusCode.ERROR });
+			if (error instanceof Error) span.recordException(error);
+			throw error;
+		} finally {
+			span.end();
+		}
+	});
+}
+/**
+* Attach attributes to the current active span when tracing is enabled.
+*/
+function setActiveSpanAttributes(attributes) {
+	if (!isTracingActive()) return;
+	const span = trace.getActiveSpan();
+	if (!span) return;
+	for (const [key, value] of Object.entries(attributes)) if (value !== void 0) span.setAttribute(key, value);
+}
+
+//#endregion
+export { setActiveSpanAttributes, withSpan };
+//# sourceMappingURL=span.js.map