@robelest/convex-auth 0.0.4-preview.25 → 0.0.4-preview.28

package/dist/otel.js

@@ -0,0 +1,82 @@
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+
+//#region src/otel.ts
+function resolveProcessors(input) {
+	if (input === void 0) return [];
+	if (Array.isArray(input)) return [...input];
+	return [input];
+}
+/**
+* Build a Node.js OpenTelemetry tracer provider for an app using Convex Auth.
+*
+* Convex Auth does not install this provider automatically. Provide it from your
+* application runtime when you want server-side spans, metrics, or logs to be
+* exported.
+*
+* @param config - Telemetry configuration supplied by the host application.
+* @returns A registered {@link NodeTracerProvider}.
+*
+* @example
+* ```ts
+* import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+* import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+* import { nodeTelemetry } from "@robelest/convex-auth/otel";
+*
+* const provider = nodeTelemetry({
+*   serviceName: "my-app",
+*   spanProcessor: new BatchSpanProcessor(new OTLPTraceExporter()),
+* });
+* ```
+*/
+function nodeTelemetry(config) {
+	const provider = new NodeTracerProvider({
+		resource: resourceFromAttributes({
+			[ATTR_SERVICE_NAME]: config.serviceName,
+			...config.serviceVersion ? { [ATTR_SERVICE_VERSION]: config.serviceVersion } : {},
+			...config.attributes
+		}),
+		spanProcessors: resolveProcessors(config.spanProcessor),
+		...config.tracerConfig
+	});
+	provider.register();
+	return provider;
+}
+/**
+* Build a browser OpenTelemetry tracer provider for an app using Convex Auth.
+*
+* Convex Auth does not install this provider automatically. Provide it from your
+* browser runtime when you want client-side Convex Auth spans to be exported.
+*
+* @param config - Telemetry configuration supplied by the host application.
+* @returns A registered {@link WebTracerProvider}.
+*
+* @example
+* ```ts
+* import { browserTelemetry } from "@robelest/convex-auth/otel";
+*
+* const provider = browserTelemetry({
+*   serviceName: "my-web-app",
+*   attributes: { deployment: "production" },
+* });
+* ```
+*/
+function browserTelemetry(config) {
+	const provider = new WebTracerProvider({
+		resource: resourceFromAttributes({
+			[ATTR_SERVICE_NAME]: config.serviceName,
+			...config.serviceVersion ? { [ATTR_SERVICE_VERSION]: config.serviceVersion } : {},
+			...config.attributes
+		}),
+		spanProcessors: resolveProcessors(config.spanProcessor),
+		...config.tracerConfig
+	});
+	provider.register();
+	return provider;
+}
+
+//#endregion
+export { browserTelemetry, nodeTelemetry };
+//# sourceMappingURL=otel.js.map

package/dist/providers/anonymous.d.ts

@@ -1,54 +1,35 @@
-import { GenericActionCtxWithAuthConfig } from "../server/types.js";
-import { DocumentByName, GenericDataModel, WithoutSystemFields } from "convex/server";
+import { ConvexCredentialsConfig, GenericActionCtxWithAuthConfig } from "../server/types.js";
 import { Value } from "convex/values";
+import { DocumentByName, GenericDataModel, WithoutSystemFields } from "convex/server";
 
 //#region src/providers/anonymous.d.ts
-/**
- * The available options to an {@link Anonymous} provider for Convex Auth.
- */
+/** Configuration for the {@link anonymous} provider. */
 interface AnonymousConfig<DataModel extends GenericDataModel> {
-  /**
-   * Uniquely identifies the provider, allowing to use
-   * multiple different {@link Anonymous} providers.
-   */
+  /** Stable provider identifier used in `signIn("<id>")`. */
   id?: string;
   /**
-   * Perform checks on provided params and customize the user
-   * information stored after sign in.
+   * Optional profile factory used when creating the anonymous user document.
+   * Must return a profile that includes `isAnonymous: true`.
    */
-  profile?: (
-  /**
-   * The values passed to the `signIn` function.
-   */
-  params: Record<string, Value | undefined>,
-  /**
-   * Convex ActionCtx in case you want to read from or write to
-   * the database.
-   */
-  ctx: GenericActionCtxWithAuthConfig<DataModel>) => WithoutSystemFields<DocumentByName<DataModel, "User">> & {
+  profile?: (params: Record<string, Value | undefined>, ctx: GenericActionCtxWithAuthConfig<DataModel>) => WithoutSystemFields<DocumentByName<DataModel, "User">> & {
     isAnonymous: true;
   };
 }
 /**
- * Anonymous authentication provider.
+ * Create an anonymous sign-in provider.
  *
- * Creates a new anonymous user account without requiring any
- * user-provided information. Useful for guest access or
- * progressive profiling.
+ * @typeParam DataModel - The Convex data model used by the auth context.
+ * @param config - Optional provider id and profile customization.
+ * @returns A configured anonymous provider for `createAuth`.
  *
  * @example
  * ```ts
- * import { Anonymous } from "@robelest/convex-auth/providers";
+ * import { anonymous } from "@robelest/convex-auth/providers";
  *
- * new Anonymous()
+ * anonymous()
  * ```
  */
-declare class Anonymous<DataModel extends GenericDataModel = GenericDataModel> {
-  readonly id: string;
-  readonly type: "credentials";
-  readonly config: AnonymousConfig<DataModel>;
-  constructor(config?: AnonymousConfig<DataModel>);
-}
+declare function anonymous<DataModel extends GenericDataModel = GenericDataModel>(config?: AnonymousConfig<DataModel>): ConvexCredentialsConfig;
 //#endregion
-export { Anonymous, AnonymousConfig };
+export { AnonymousConfig, anonymous };
 //# sourceMappingURL=anonymous.d.ts.map

package/dist/providers/anonymous.js

@@ -1,48 +1,40 @@
-import { Credentials } from "./credentials.js";
+import { credentials } from "./credentials.js";
 
 //#region src/providers/anonymous.ts
+function defaultAnonymousProfile() {
+	return { isAnonymous: true };
+}
 /**
-* Anonymous authentication provider.
+* Create an anonymous sign-in provider.
 *
-* Creates a new anonymous user account without requiring any
-* user-provided information. Useful for guest access or
-* progressive profiling.
+* @typeParam DataModel - The Convex data model used by the auth context.
+* @param config - Optional provider id and profile customization.
+* @returns A configured anonymous provider for `createAuth`.
 *
 * @example
 * ```ts
-* import { Anonymous } from "@robelest/convex-auth/providers";
+* import { anonymous } from "@robelest/convex-auth/providers";
 *
-* new Anonymous()
+* anonymous()
 * ```
 */
-var Anonymous = class {
-	id;
-	type = "credentials";
-	config;
-	constructor(config = {}) {
-		this.id = config.id ?? "anonymous";
-		this.config = config;
-	}
-	/** @internal Convert to the internal materialized config shape. */
-	_toMaterialized() {
-		const config = this.config;
-		const provider = this.id;
-		return new Credentials({
-			id: "anonymous",
-			authorize: async (params, ctx) => {
-				const profile = config.profile?.(params, ctx) ?? { isAnonymous: true };
-				const { user } = await ctx.auth.account.create(ctx, {
-					provider,
-					account: { id: crypto.randomUUID() },
-					profile
-				});
-				return { userId: user._id };
-			},
-			...config
-		})._toMaterialized();
-	}
-};
+function anonymous(config = {}) {
+	const provider = config.id ?? "anonymous";
+	return credentials({
+		id: provider,
+		authorize: async (params, ctx) => {
+			const profile = config.profile?.(params, ctx) ?? defaultAnonymousProfile();
+			const { user } = await ctx.auth.account.create(ctx, {
+				provider,
+				account: { id: crypto.randomUUID() },
+				profile
+			});
+			return { userId: user._id };
+		},
+		...config
+	});
+}
 
 //#endregion
-export { Anonymous };
+export { anonymous };
 //# sourceMappingURL=anonymous.js.map

package/dist/providers/apple.d.ts

@@ -0,0 +1,59 @@
+import { OAuthMaterializedConfig } from "../server/types.js";
+
+//#region src/providers/apple.d.ts
+/**
+ * Apple OAuth provider.
+ *
+ * ```ts
+ * import { apple } from "@robelest/convex-auth/providers/apple";
+ *
+ * apple({
+ *   clientId: process.env.AUTH_APPLE_ID!,
+ *   teamId: process.env.AUTH_APPLE_TEAM_ID!,
+ *   keyId: process.env.AUTH_APPLE_KEY_ID!,
+ *   privateKey: process.env.AUTH_APPLE_PRIVATE_KEY!,
+ * })
+ * ```
+ *
+ * @module
+ */
+/** Configuration for the {@link apple} provider. */
+interface AppleConfig {
+  /** Services ID or app bundle identifier registered with Sign in with Apple. */
+  clientId: string;
+  /** Apple Developer team identifier used to sign client secrets. */
+  teamId: string;
+  /** Apple private key identifier. */
+  keyId: string;
+  /** Apple private key PEM contents or bytes. */
+  privateKey: string | Uint8Array;
+  /** Optional callback URL override. Defaults to `CUSTOM_AUTH_SITE_URL` or `CONVEX_SITE_URL` plus `/api/auth/callback/apple`. */
+  redirectUri?: string;
+  /** Optional OAuth scopes. Defaults to `name email`. */
+  scopes?: string[];
+  /** Account-linking strategy for existing users with matching email addresses. */
+  accountLinking?: "verifiedEmail" | "none";
+}
+/**
+ * Create an Apple OAuth provider.
+ *
+ * @param config - Apple Sign In client settings and signing key material.
+ * @returns A configured Apple OAuth provider for `createAuth`.
+ * @throws {Error} When no callback URL can be derived and `redirectUri` is omitted.
+ *
+ * @example
+ * ```ts
+ * import { apple } from "@robelest/convex-auth/providers/apple";
+ *
+ * apple({
+ *   clientId: process.env.AUTH_APPLE_ID!,
+ *   teamId: process.env.AUTH_APPLE_TEAM_ID!,
+ *   keyId: process.env.AUTH_APPLE_KEY_ID!,
+ *   privateKey: process.env.AUTH_APPLE_PRIVATE_KEY!,
+ * })
+ * ```
+ */
+declare function apple(config: AppleConfig): OAuthMaterializedConfig;
+//#endregion
+export { AppleConfig, apple };
+//# sourceMappingURL=apple.d.ts.map

package/dist/providers/apple.js

@@ -0,0 +1,58 @@
+import { envOptionalString, readConfigSync } from "../server/env.js";
+import { createArcticOAuthClient, createOAuthProvider } from "../server/oauth/factory.js";
+import { Apple } from "arctic";
+
+//#region src/providers/apple.ts
+/**
+* Apple OAuth provider.
+*
+* ```ts
+* import { apple } from "@robelest/convex-auth/providers/apple";
+*
+* apple({
+*   clientId: process.env.AUTH_APPLE_ID!,
+*   teamId: process.env.AUTH_APPLE_TEAM_ID!,
+*   keyId: process.env.AUTH_APPLE_KEY_ID!,
+*   privateKey: process.env.AUTH_APPLE_PRIVATE_KEY!,
+* })
+* ```
+*
+* @module
+*/
+const DEFAULT_SCOPES = ["name", "email"];
+/**
+* Create an Apple OAuth provider.
+*
+* @param config - Apple Sign In client settings and signing key material.
+* @returns A configured Apple OAuth provider for `createAuth`.
+* @throws {Error} When no callback URL can be derived and `redirectUri` is omitted.
+*
+* @example
+* ```ts
+* import { apple } from "@robelest/convex-auth/providers/apple";
+*
+* apple({
+*   clientId: process.env.AUTH_APPLE_ID!,
+*   teamId: process.env.AUTH_APPLE_TEAM_ID!,
+*   keyId: process.env.AUTH_APPLE_KEY_ID!,
+*   privateKey: process.env.AUTH_APPLE_PRIVATE_KEY!,
+* })
+* ```
+*/
+function apple(config) {
+	return createOAuthProvider({
+		id: "apple",
+		provider: createArcticOAuthClient(new Apple(config.clientId, config.teamId, config.keyId, typeof config.privateKey === "string" ? new TextEncoder().encode(config.privateKey) : config.privateKey, config.redirectUri ?? defaultRedirectUri("apple")), { pkce: "never" }),
+		scopes: config.scopes ?? DEFAULT_SCOPES,
+		accountLinking: config.accountLinking
+	});
+}
+function defaultRedirectUri(providerId) {
+	const rootUrl = readConfigSync(envOptionalString("CUSTOM_AUTH_SITE_URL")) ?? readConfigSync(envOptionalString("CONVEX_SITE_URL"));
+	if (!rootUrl) throw new Error(`Missing CONVEX_SITE_URL while configuring ${providerId} OAuth provider. Set CONVEX_SITE_URL or pass redirectUri explicitly.`);
+	return `${rootUrl}/api/auth/callback/${providerId}`;
+}
+
+//#endregion
+export { apple };
+//# sourceMappingURL=apple.js.map

package/dist/providers/credentials.d.ts

@@ -1,64 +1,48 @@
-import { AuthProviderConfig, GenericActionCtxWithAuthConfig } from "../server/types.js";
-import { GenericDataModel } from "convex/server";
+import { AuthProviderConfig, ConvexCredentialsConfig, GenericActionCtxWithAuthConfig } from "../server/types.js";
 import { GenericId, Value } from "convex/values";
+import { GenericDataModel } from "convex/server";
 
 //#region src/providers/credentials.d.ts
-/**
- * Configuration for the Credentials provider.
- *
- * @typeParam DataModel - The Convex data model.
- */
+/** Configuration for the {@link credentials} provider. */
 interface CredentialsConfig<DataModel extends GenericDataModel = GenericDataModel> {
-  /** Uniquely identifies the provider. Defaults to `"credentials"`. */
+  /** Stable provider identifier used in `signIn("<id>")`. */
   id?: string;
   /**
-   * Handle credentials received from the client-side `signIn` call.
-   *
-   * @returns A user ID for successful login, or `null` to reject.
+   * Validate the submitted credentials and return the authenticated user.
+   * Return `null` to reject the sign-in attempt.
    */
   authorize: (credentials: Partial<Record<string, Value | undefined>>, ctx: GenericActionCtxWithAuthConfig<DataModel>) => Promise<{
     userId: GenericId<"User">;
     sessionId?: GenericId<"Session">;
   } | null>;
-  /**
-   * Provide hashing and verification functions for account secrets.
-   */
+  /** Optional hashing helpers for password-style credential verification. */
   crypto?: {
     hashSecret: (secret: string) => Promise<string>;
     verifySecret: (secret: string, hash: string) => Promise<boolean>;
   };
-  /**
-   * Extra providers used internally (e.g. email verification in password flow).
-   * Not exposed to clients.
-   */
+  /** Additional providers to register alongside this credentials provider. */
   extraProviders?: (AuthProviderConfig | undefined)[];
 }
 /**
- * Credentials provider for custom authentication flows.
+ * Create a credentials provider for custom sign-in logic.
  *
- * This is the escape hatch for fully custom auth logic. For email/password
- * flows, use the `Password` class instead.
- *
- * @typeParam DataModel - The Convex data model.
+ * @typeParam DataModel - The Convex data model used by the auth context.
+ * @param config - Custom authorization and hashing hooks.
+ * @returns A configured credentials provider for `createAuth`.
  *
  * @example
  * ```ts
- * import { Credentials } from "@robelest/convex-auth/providers";
+ * import { credentials } from "@robelest/convex-auth/providers";
  *
- * new Credentials({
- *   authorize: async (credentials, ctx) => {
- *     const user = await validateUser(credentials);
+ * credentials({
+ *   authorize: async (params, ctx) => {
+ *     const user = await lookupUser(params.email, params.password, ctx);
  *     return user ? { userId: user._id } : null;
  *   },
  * })
  * ```
  */
-declare class Credentials<DataModel extends GenericDataModel = GenericDataModel> {
-  readonly id: string;
-  readonly type: "credentials";
-  readonly config: CredentialsConfig<DataModel>;
-  constructor(config: CredentialsConfig<DataModel>);
-}
+declare function credentials<DataModel extends GenericDataModel = GenericDataModel>(config: CredentialsConfig<DataModel>): ConvexCredentialsConfig<DataModel>;
 //#endregion
-export { Credentials, CredentialsConfig };
+export { CredentialsConfig, credentials };
 //# sourceMappingURL=credentials.d.ts.map

package/dist/providers/credentials.js

@@ -1,42 +1,31 @@
 //#region src/providers/credentials.ts
 /**
-* Credentials provider for custom authentication flows.
+* Create a credentials provider for custom sign-in logic.
 *
-* This is the escape hatch for fully custom auth logic. For email/password
-* flows, use the `Password` class instead.
-*
-* @typeParam DataModel - The Convex data model.
+* @typeParam DataModel - The Convex data model used by the auth context.
+* @param config - Custom authorization and hashing hooks.
+* @returns A configured credentials provider for `createAuth`.
 *
 * @example
 * ```ts
-* import { Credentials } from "@robelest/convex-auth/providers";
+* import { credentials } from "@robelest/convex-auth/providers";
 *
-* new Credentials({
-*   authorize: async (credentials, ctx) => {
-*     const user = await validateUser(credentials);
+* credentials({
+*   authorize: async (params, ctx) => {
+*     const user = await lookupUser(params.email, params.password, ctx);
 *     return user ? { userId: user._id } : null;
 *   },
 * })
 * ```
 */
-var Credentials = class {
-	id;
-	type = "credentials";
-	config;
-	constructor(config) {
-		this.id = config.id ?? "credentials";
-		this.config = config;
-	}
-	/** @internal Convert to the internal materialized config shape. */
-	_toMaterialized() {
-		return {
-			...this.config,
-			id: this.id,
-			type: "credentials"
-		};
-	}
-};
+function credentials(config) {
+	return {
+		...config,
+		id: config.id ?? "credentials",
+		type: "credentials"
+	};
+}
 
 //#endregion
-export { Credentials };
+export { credentials };
 //# sourceMappingURL=credentials.js.map

package/dist/providers/custom.d.ts

@@ -0,0 +1,94 @@
+import { OAuthMaterializedConfig, OAuthProfile, OAuthTokens } from "../server/types.js";
+
+//#region src/providers/custom.d.ts
+type ScopeSeparator = " " | ",";
+type PkceMode = "required" | "optional" | "never";
+type TokenAuthMethod = "basic" | "body" | "none";
+/** Configuration for the custom provider authorization URL. */
+interface CustomOAuthAuthorizationConfig {
+  /** Authorization endpoint URL. */
+  url: string;
+  /** PKCE requirement for this provider's authorization flow. */
+  pkce?: PkceMode;
+  /** Query parameter name used for the client ID. */
+  clientIdParam?: string;
+  /** Query parameter name used for scopes. */
+  scopeParam?: string;
+  /** Separator used when joining multiple scopes. */
+  scopeSeparator?: ScopeSeparator;
+  /** Additional query parameters appended to the authorization URL. */
+  extraParams?: Record<string, string>;
+}
+/** Configuration for the custom provider token exchange request. */
+interface CustomOAuthTokenConfig {
+  /** Token endpoint URL. */
+  url: string;
+  /** How client credentials are sent to the token endpoint. */
+  authMethod?: TokenAuthMethod;
+  /** Form field name used for the client ID. */
+  clientIdParam?: string;
+  /** Form field name used for the client secret. */
+  clientSecretParam?: string;
+  /** Form field name used for the PKCE code verifier. */
+  codeVerifierParam?: string;
+  /** Form field name used for scopes. */
+  scopeParam?: string;
+  /** Separator used when joining multiple scopes. */
+  scopeSeparator?: ScopeSeparator;
+  /** Whether to include the redirect URI in token requests. */
+  includeRedirectUri?: boolean;
+  /** Whether to include configured scopes in token requests. */
+  includeScopes?: boolean;
+  /** Additional form parameters appended to token requests. */
+  extraParams?: Record<string, string>;
+}
+/** Configuration for the {@link custom} provider. */
+interface CustomOAuthConfig {
+  /** Stable provider identifier used in `signIn("<id>")`. */
+  id: string;
+  /** OAuth client identifier. */
+  clientId: string;
+  /** Optional OAuth client secret. */
+  clientSecret?: string | null;
+  /** Optional callback URL override. Defaults to `CUSTOM_AUTH_SITE_URL` or `CONVEX_SITE_URL` plus `/api/auth/callback/<id>`. */
+  redirectUri?: string;
+  /** Optional default scopes requested during sign-in. */
+  scopes?: string[];
+  /** Account-linking strategy for existing users with matching email addresses. */
+  accountLinking?: "verifiedEmail" | "none";
+  /** Whether the provider requires nonce generation and validation. */
+  nonce?: boolean;
+  /** Authorization endpoint configuration. */
+  authorization: CustomOAuthAuthorizationConfig;
+  /** Token exchange endpoint configuration. */
+  token: CustomOAuthTokenConfig;
+  /** Optional profile loader that converts OAuth tokens into a normalized profile. */
+  profile?: (tokens: OAuthTokens) => Promise<OAuthProfile>;
+  /** Optional token validation hook for provider-specific checks. */
+  validateTokens?: (tokens: OAuthTokens, ctx: {
+    nonce?: string;
+  }) => Promise<void>;
+}
+/**
+ * Create a custom OAuth provider.
+ *
+ * @param config - OAuth endpoints, credentials, and profile callbacks.
+ * @returns A configured OAuth provider for `createAuth`.
+ *
+ * @example
+ * ```ts
+ * import { custom } from "@robelest/convex-auth/providers";
+ *
+ * custom({
+ *   id: "workos",
+ *   clientId: process.env.WORKOS_CLIENT_ID!,
+ *   clientSecret: process.env.WORKOS_CLIENT_SECRET!,
+ *   authorization: { url: "https://api.workos.com/sso/authorize" },
+ *   token: { url: "https://api.workos.com/sso/token", authMethod: "basic" },
+ * })
+ * ```
+ */
+declare function custom(config: CustomOAuthConfig): OAuthMaterializedConfig;
+//#endregion
+export { CustomOAuthAuthorizationConfig, CustomOAuthConfig, CustomOAuthTokenConfig, custom };
+//# sourceMappingURL=custom.d.ts.map