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

package/dist/providers/github.js

@@ -0,0 +1,79 @@
+import { createArcticOAuthClient, createOAuthProvider } from "../server/oauth/factory.js";
+import { defaultOAuthRedirectUri } from "./redirect.js";
+import { GitHub } from "arctic";
+
+//#region src/providers/github.ts
+/**
+* GitHub OAuth provider.
+*
+* ```ts
+* import { github } from "@estifanos-sh/convex-auth/providers/github";
+*
+* github({
+*   clientId: env.AUTH_GITHUB_ID!,
+*   clientSecret: env.AUTH_GITHUB_SECRET!,
+* })
+* ```
+*
+* @module
+*/
+const DEFAULT_SCOPES = ["user:email"];
+/**
+* Create a GitHub OAuth provider.
+*
+* GitHub is not OIDC by default, so this wrapper fetches the profile and email
+* data for you after the OAuth code exchange.
+*
+* @param config - GitHub OAuth client settings.
+* @returns A configured GitHub OAuth provider for `defineAuth`.
+* @throws {Error} When no callback URL can be derived and `redirectUri` is omitted.
+*
+* @example
+* ```ts
+* import { github } from "@estifanos-sh/convex-auth/providers/github";
+*
+* github({
+*   clientId: env.AUTH_GITHUB_ID!,
+*   clientSecret: env.AUTH_GITHUB_SECRET!,
+* })
+* ```
+*/
+function github(config) {
+	const scopes = config.scopes ?? DEFAULT_SCOPES;
+	const createProvider = (redirectUri) => new GitHub(config.clientId, config.clientSecret, config.redirectUri ?? defaultOAuthRedirectUri("github", redirectUri));
+	return createOAuthProvider({
+		id: "github",
+		provider: createArcticOAuthClient(createProvider, { pkce: "never" }),
+		scopes,
+		accountLinking: config.accountLinking,
+		updateProfileOnLogin: config.updateProfileOnLogin,
+		profile: async (tokens) => {
+			if (!tokens.accessToken) throw new Error("GitHub OAuth response is missing access_token.");
+			const accessToken = tokens.accessToken;
+			const [userResponse, emailResponse] = await Promise.all([fetch("https://api.github.com/user", { headers: { Authorization: `Bearer ${accessToken}` } }), fetch("https://api.github.com/user/emails", { headers: { Authorization: `Bearer ${accessToken}` } })]);
+			if (!userResponse.ok) throw new Error(`GitHub profile request failed: ${userResponse.status}`);
+			if (!emailResponse.ok) throw new Error(`GitHub email request failed: ${emailResponse.status}`);
+			const user = await userResponse.json();
+			const emails = await emailResponse.json();
+			const primaryEmail = emails.find((email) => email.primary)?.email ?? emails.find((email) => email.verified)?.email ?? user.email ?? void 0;
+			const verifiedEmail = emails.find((email) => email.primary)?.verified ?? emails.find((email) => email.verified)?.verified ?? false;
+			const allEmails = emails.filter((e) => typeof e.email === "string").map((e) => ({
+				email: e.email,
+				primary: e.primary === true,
+				verified: e.verified === true
+			}));
+			return {
+				id: String(user.id),
+				email: typeof primaryEmail === "string" ? primaryEmail : void 0,
+				emails: allEmails.length > 0 ? allEmails : void 0,
+				emailVerified: verifiedEmail,
+				name: typeof user.name === "string" ? user.name : void 0,
+				image: typeof user.avatar_url === "string" ? user.avatar_url : void 0
+			};
+		}
+	});
+}
+
+//#endregion
+export { github };
+//# sourceMappingURL=github.js.map

package/dist/providers/google.d.ts

@@ -0,0 +1,56 @@
+import { OAuthMaterializedConfig } from "../server/types.js";
+
+//#region src/providers/google.d.ts
+/**
+ * Google OAuth provider.
+ *
+ * ```ts
+ * import { google } from "@estifanos-sh/convex-auth/providers/google";
+ *
+ * google({
+ *   clientId: env.AUTH_GOOGLE_ID!,
+ *   clientSecret: env.AUTH_GOOGLE_SECRET!,
+ * })
+ * ```
+ *
+ * @module
+ */
+/** Configuration for the {@link google} provider. */
+interface GoogleConfig {
+  /** OAuth client ID from the Google Cloud console. */
+  clientId: string;
+  /** OAuth client secret from the Google Cloud console. */
+  clientSecret: string;
+  /** Optional callback URL override. Defaults to the auth site URL plus `/callback/google`. */
+  redirectUri?: string;
+  /** Optional OAuth scopes. Defaults to `openid profile email`. */
+  scopes?: string[];
+  /** Account-linking strategy for existing users with matching email addresses. */
+  accountLinking?: "verifiedEmail" | "none";
+  /** On returning sign-in, refresh `User.name`/`image`/`email` from the new profile. Defaults to `true`. */
+  updateProfileOnLogin?: boolean;
+}
+/**
+ * Create a Google OAuth provider.
+ *
+ * Uses the Google OpenID Connect flow and requests `openid profile email` by
+ * default.
+ *
+ * @param config - Google OAuth client settings.
+ * @returns A configured Google OAuth provider for `defineAuth`.
+ * @throws {Error} When no callback URL can be derived and `redirectUri` is omitted.
+ *
+ * @example
+ * ```ts
+ * import { google } from "@estifanos-sh/convex-auth/providers/google";
+ *
+ * google({
+ *   clientId: env.AUTH_GOOGLE_ID!,
+ *   clientSecret: env.AUTH_GOOGLE_SECRET!,
+ * })
+ * ```
+ */
+declare function google(config: GoogleConfig): OAuthMaterializedConfig;
+//#endregion
+export { GoogleConfig, google };
+//# sourceMappingURL=google.d.ts.map

package/dist/providers/google.js

@@ -0,0 +1,59 @@
+import { createArcticOAuthClient, createOAuthProvider } from "../server/oauth/factory.js";
+import { defaultOAuthRedirectUri } from "./redirect.js";
+import { Google } from "arctic";
+
+//#region src/providers/google.ts
+/**
+* Google OAuth provider.
+*
+* ```ts
+* import { google } from "@estifanos-sh/convex-auth/providers/google";
+*
+* google({
+*   clientId: env.AUTH_GOOGLE_ID!,
+*   clientSecret: env.AUTH_GOOGLE_SECRET!,
+* })
+* ```
+*
+* @module
+*/
+const DEFAULT_SCOPES = [
+	"openid",
+	"profile",
+	"email"
+];
+/**
+* Create a Google OAuth provider.
+*
+* Uses the Google OpenID Connect flow and requests `openid profile email` by
+* default.
+*
+* @param config - Google OAuth client settings.
+* @returns A configured Google OAuth provider for `defineAuth`.
+* @throws {Error} When no callback URL can be derived and `redirectUri` is omitted.
+*
+* @example
+* ```ts
+* import { google } from "@estifanos-sh/convex-auth/providers/google";
+*
+* google({
+*   clientId: env.AUTH_GOOGLE_ID!,
+*   clientSecret: env.AUTH_GOOGLE_SECRET!,
+* })
+* ```
+*/
+function google(config) {
+	const scopes = config.scopes ?? DEFAULT_SCOPES;
+	const createProvider = (redirectUri) => new Google(config.clientId, config.clientSecret, config.redirectUri ?? defaultOAuthRedirectUri("google", redirectUri));
+	return createOAuthProvider({
+		id: "google",
+		provider: createArcticOAuthClient(createProvider, { pkce: "required" }),
+		scopes,
+		accountLinking: config.accountLinking,
+		updateProfileOnLogin: config.updateProfileOnLogin
+	});
+}
+
+//#endregion
+export { google };
+//# sourceMappingURL=google.js.map

package/dist/providers/index.d.ts

@@ -0,0 +1,16 @@
+import { CredentialsAuthorizeResult, CredentialsConfig, CredentialsProvisioning, credentials } from "./credentials.js";
+import { EmailConfig, OAuthProfile, OAuthTokens, PhoneConfig, WebAuthnAttestationEvidence, WebAuthnAttestationPolicy } from "../server/types.js";
+import { AnonymousConfig, anonymous } from "./anonymous.js";
+import { AppleConfig, apple } from "./apple.js";
+import { connection } from "./connection.js";
+import { CustomOAuthAuthorizationConfig, CustomOAuthConfig, CustomOAuthTokenConfig, custom } from "./custom.js";
+import { DeviceConfig, device } from "./device.js";
+import { EmailProviderConfig, email } from "./email.js";
+import { GitHubConfig, github } from "./github.js";
+import { GoogleConfig, google } from "./google.js";
+import { PasswordConfig, password } from "./password.js";
+import { WebAuthnAlgorithm, WebAuthnAuthenticationConfig, WebAuthnConfig, WebAuthnHint, WebAuthnRegistrationConfig, webauthn } from "./webauthn.js";
+import { TotpConfig, totp } from "./totp.js";
+import { MicrosoftConfig, microsoft } from "./microsoft.js";
+import { PhoneProviderConfig, phone } from "./phone.js";
+export { type AnonymousConfig, type AppleConfig, type CredentialsAuthorizeResult, type CredentialsConfig, type CredentialsProvisioning, type CustomOAuthAuthorizationConfig, type CustomOAuthConfig, type CustomOAuthTokenConfig, type DeviceConfig, type EmailConfig, type EmailProviderConfig, type GitHubConfig, type GoogleConfig, type MicrosoftConfig, type OAuthProfile, type OAuthTokens, type PasswordConfig, type PhoneConfig, type PhoneProviderConfig, type TotpConfig, type WebAuthnAlgorithm, type WebAuthnAttestationEvidence, type WebAuthnAttestationPolicy, type WebAuthnAuthenticationConfig, type WebAuthnConfig, type WebAuthnHint, type WebAuthnRegistrationConfig, anonymous, apple, connection, credentials, custom, device, email, github, google, microsoft, password, phone, totp, webauthn };

package/dist/providers/index.js

@@ -0,0 +1,16 @@
+import { credentials } from "./credentials.js";
+import { anonymous } from "./anonymous.js";
+import { apple } from "./apple.js";
+import { connection } from "./connection.js";
+import { custom } from "./custom.js";
+import { device } from "./device.js";
+import { email } from "./email.js";
+import { github } from "./github.js";
+import { google } from "./google.js";
+import { password } from "./password.js";
+import { webauthn } from "./webauthn.js";
+import { totp } from "./totp.js";
+import { microsoft } from "./microsoft.js";
+import { phone } from "./phone.js";
+
+export { anonymous, apple, connection, credentials, custom, device, email, github, google, microsoft, password, phone, totp, webauthn };

package/dist/providers/microsoft.d.ts

@@ -0,0 +1,59 @@
+import { OAuthMaterializedConfig } from "../server/types.js";
+
+//#region src/providers/microsoft.d.ts
+/**
+ * Microsoft OAuth provider.
+ *
+ * ```ts
+ * import { microsoft } from "@estifanos-sh/convex-auth/providers/microsoft";
+ *
+ * microsoft({
+ *   tenant: env.AUTH_MICROSOFT_TENANT_ID!,
+ *   clientId: env.AUTH_MICROSOFT_ID!,
+ *   clientSecret: env.AUTH_MICROSOFT_SECRET!,
+ * })
+ * ```
+ *
+ * @module
+ */
+/** Configuration for the {@link microsoft} provider. */
+interface MicrosoftConfig {
+  /** Microsoft Entra tenant ID or domain used to scope the OAuth issuer. */
+  tenant: string;
+  /** OAuth client ID from Microsoft Entra ID. */
+  clientId: string;
+  /** OAuth client secret for confidential clients, when required. */
+  clientSecret?: string | null;
+  /** Optional callback URL override. Defaults to the auth site URL plus `/callback/microsoft`. */
+  redirectUri?: string;
+  /** Optional OAuth scopes. Defaults to `openid profile email`. */
+  scopes?: string[];
+  /** Account-linking strategy for existing users with matching email addresses. */
+  accountLinking?: "verifiedEmail" | "none";
+  /** On returning sign-in, refresh `User.name`/`image`/`email` from the new profile. Defaults to `true`. */
+  updateProfileOnLogin?: boolean;
+}
+/**
+ * Create a Microsoft OAuth provider.
+ *
+ * This wrapper enables nonce handling and validates the returned ID token.
+ *
+ * @param config - Microsoft Entra ID client settings.
+ * @returns A configured Microsoft OAuth provider for `defineAuth`.
+ * @throws {Error} When no callback URL can be derived and `redirectUri` is omitted.
+ *
+ * @example
+ * ```ts
+ * import { microsoft } from "@estifanos-sh/convex-auth/providers/microsoft";
+ *
+ * microsoft({
+ *   tenant: env.AUTH_MICROSOFT_TENANT_ID!,
+ *   clientId: env.AUTH_MICROSOFT_ID!,
+ *   clientSecret: env.AUTH_MICROSOFT_SECRET!,
+ * })
+ * ```
+ */
+declare function microsoft(config: MicrosoftConfig): OAuthMaterializedConfig;
+//#endregion
+export { MicrosoftConfig, microsoft };
+//# sourceMappingURL=microsoft.d.ts.map

package/dist/providers/microsoft.js

@@ -0,0 +1,98 @@
+import { createArcticOAuthClient, createOAuthProvider } from "../server/oauth/factory.js";
+import { defaultOAuthRedirectUri } from "./redirect.js";
+import { createRemoteJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
+import { MicrosoftEntraId } from "arctic";
+
+//#region src/providers/microsoft.ts
+/**
+* Microsoft OAuth provider.
+*
+* ```ts
+* import { microsoft } from "@estifanos-sh/convex-auth/providers/microsoft";
+*
+* microsoft({
+*   tenant: env.AUTH_MICROSOFT_TENANT_ID!,
+*   clientId: env.AUTH_MICROSOFT_ID!,
+*   clientSecret: env.AUTH_MICROSOFT_SECRET!,
+* })
+* ```
+*
+* @module
+*/
+const DEFAULT_SCOPES = [
+	"openid",
+	"profile",
+	"email"
+];
+/**
+* Create a Microsoft OAuth provider.
+*
+* This wrapper enables nonce handling and validates the returned ID token.
+*
+* @param config - Microsoft Entra ID client settings.
+* @returns A configured Microsoft OAuth provider for `defineAuth`.
+* @throws {Error} When no callback URL can be derived and `redirectUri` is omitted.
+*
+* @example
+* ```ts
+* import { microsoft } from "@estifanos-sh/convex-auth/providers/microsoft";
+*
+* microsoft({
+*   tenant: env.AUTH_MICROSOFT_TENANT_ID!,
+*   clientId: env.AUTH_MICROSOFT_ID!,
+*   clientSecret: env.AUTH_MICROSOFT_SECRET!,
+* })
+* ```
+*/
+function microsoft(config) {
+	const scopes = config.scopes ?? DEFAULT_SCOPES;
+	const createProvider = (redirectUri) => new MicrosoftEntraId(config.tenant, config.clientId, config.clientSecret ?? null, config.redirectUri ?? defaultOAuthRedirectUri("microsoft", redirectUri));
+	const issuer = `https://login.microsoftonline.com/${config.tenant}/v2.0`;
+	const jwks = createRemoteJWKSet(new URL(`${issuer}/discovery/v2.0/keys`));
+	return createOAuthProvider({
+		id: "microsoft",
+		provider: createArcticOAuthClient(createProvider, { pkce: "required" }),
+		scopes,
+		nonce: true,
+		accountLinking: config.accountLinking,
+		updateProfileOnLogin: config.updateProfileOnLogin,
+		validateTokens: async (tokens, ctx) => {
+			if (!ctx.nonce) throw new Error("Microsoft OAuth requires a nonce.");
+			if (!tokens.idToken) throw new Error("Microsoft OAuth response is missing id_token.");
+			const idToken = tokens.idToken;
+			const tokenAlg = decodeProtectedHeader(idToken).alg;
+			const verification = await (tokenAlg === "HS256" || tokenAlg === "HS384" || tokenAlg === "HS512" ? jwtVerify(idToken, (() => {
+				if (!config.clientSecret) throw new Error("Microsoft token uses symmetric signatures but clientSecret is missing.");
+				return new TextEncoder().encode(config.clientSecret);
+			})(), {
+				issuer,
+				audience: config.clientId,
+				requiredClaims: [
+					"iss",
+					"sub",
+					"aud",
+					"exp",
+					"iat"
+				],
+				clockTolerance: 10
+			}) : jwtVerify(idToken, jwks, {
+				issuer,
+				audience: config.clientId,
+				requiredClaims: [
+					"iss",
+					"sub",
+					"aud",
+					"exp",
+					"iat"
+				],
+				clockTolerance: 10
+			}));
+			if (verification.payload.nonce !== ctx.nonce) throw new Error("Microsoft OAuth nonce mismatch.");
+			if (Array.isArray(verification.payload.aud) && verification.payload.aud.length > 1 && verification.payload.azp !== config.clientId) throw new Error("Microsoft OAuth authorized party does not match client ID.");
+		}
+	});
+}
+
+//#endregion
+export { microsoft };
+//# sourceMappingURL=microsoft.js.map

package/dist/providers/password.d.ts

@@ -0,0 +1,68 @@
+import { CredentialsConfig } from "./credentials.js";
+import { ConvexCredentialsConfig, EmailConfig, GenericActionCtxWithAuthConfig } from "../server/types.js";
+import { Value } from "convex/values";
+import { DocumentByName, GenericDataModel, WithoutSystemFields } from "convex/server";
+
+//#region src/providers/password.d.ts
+/** Configuration for the {@link password} provider. */
+interface PasswordConfig<DataModel extends GenericDataModel> {
+  /**
+   * Uniquely identifies the provider, allowing multiple password providers.
+   */
+  id?: string;
+  /**
+   * Perform checks on provided params and customize the user information
+   * stored after sign up, including email normalization.
+   *
+   * Called for every flow.
+   */
+  profile?: (params: Record<string, Value | undefined>, ctx: GenericActionCtxWithAuthConfig<DataModel>) => WithoutSystemFields<DocumentByName<DataModel, "User">> & {
+    email: string;
+  };
+  /**
+   * Performs custom validation on a password during `signUp`, `verify`
+   * (when `newPassword` is set), and `change`.
+   *
+   * Default: non-empty, length >= 8.
+   *
+   * Throw an `Error` to reject the password.
+   */
+  validatePasswordRequirements?: (password: string) => void;
+  /**
+   * Hashing and verification functions. Defaults to scrypt.
+   */
+  crypto?: CredentialsConfig["crypto"];
+  /**
+   * Email provider for the `reset` flow. Issues OTPs that the `verify` flow
+   * accepts when `newPassword` is included.
+   */
+  reset?: EmailConfig | PasswordEmailProviderFactory;
+  /**
+   * Email provider for post-signup email confirmation. Issues OTPs that the
+   * `verify` flow accepts when `newPassword` is omitted.
+   */
+  verify?: EmailConfig | PasswordEmailProviderFactory;
+}
+type PasswordEmailProviderFactory = () => EmailConfig;
+/**
+ * Email and password authentication provider.
+ *
+ * Passwords are hashed with scrypt by default. Customize via `crypto`.
+ *
+ * Email verification is opt-in via the `verify` option. Password reset is
+ * opt-in via the `reset` option (typically the same email provider).
+ *
+ * @example
+ * ```ts
+ * password()
+ * password({ verify: myEmailProvider, reset: myEmailProvider })
+ * ```
+ *
+ * @typeParam DataModel - The Convex data model used by the auth context.
+ * @param config - Password flow hooks and optional verification providers.
+ * @returns A configured password provider for `defineAuth`.
+ */
+declare function password<DataModel extends GenericDataModel = GenericDataModel>(config?: PasswordConfig<DataModel>): ConvexCredentialsConfig;
+//#endregion
+export { PasswordConfig, password };
+//# sourceMappingURL=password.d.ts.map