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

package/dist/providers/totp.js

@@ -1,39 +1,29 @@
 //#region src/providers/totp.ts
 /**
-* TOTP (Time-based One-Time Password) two-factor authentication provider.
+* Create a TOTP provider.
 *
-* Generates time-based one-time passwords compatible with authenticator
-* apps like Google Authenticator and Authy.
+* @param config - Optional issuer and token generation settings.
+* @returns A configured TOTP provider for `createAuth`.
 *
 * @example
 * ```ts
-* import { Totp } from "@robelest/convex-auth/providers";
+* import { totp } from "@robelest/convex-auth/providers";
 *
-* new Totp({ issuer: "My App" })
+* totp({ issuer: "My App" })
 * ```
 */
-var Totp = class {
-	id;
-	type = "totp";
-	config;
-	constructor(config = {}) {
-		this.id = "totp";
-		this.config = config;
-	}
-	/** @internal Convert to the internal materialized config shape. */
-	_toMaterialized() {
-		return {
-			id: this.id,
-			type: "totp",
-			options: {
-				issuer: this.config.issuer ?? "ConvexAuth",
-				digits: this.config.digits ?? 6,
-				period: this.config.period ?? 30
-			}
-		};
-	}
-};
+function totp(config = {}) {
+	return {
+		id: "totp",
+		type: "totp",
+		options: {
+			issuer: config.issuer ?? "ConvexAuth",
+			digits: config.digits ?? 6,
+			period: config.period ?? 30
+		}
+	};
+}
 
 //#endregion
-export { Totp };
+export { totp };
 //# sourceMappingURL=totp.js.map

package/dist/server/auth-context.d.ts

@@ -0,0 +1,204 @@
+import { ConvexAuthConfig, Doc } from "./types.js";
+import { GenericId } from "convex/values";
+import { UserIdentity } from "convex/server";
+
+//#region src/server/auth-context.d.ts
+/**
+ * Config for auth setup. Extends the standard auth config
+ * minus `component` (which is passed as the first constructor argument).
+ */
+type AuthConfig = Omit<ConvexAuthConfig, "component">;
+/** Canonical user document type exposed by Convex Auth. */
+type UserDoc = Doc<"User">;
+type AuthIdentityCtx = {
+  auth: {
+    getUserIdentity: () => Promise<UserIdentity | null>;
+  };
+};
+type AuthQueryCtx = {
+  runQuery: (...args: never[]) => Promise<unknown>;
+};
+type CustomFunctionInputResult<TAuth extends Record<string, unknown>> = Promise<{
+  ctx: {
+    auth: TAuth;
+  };
+}>;
+/**
+ * Current request auth context injected into `ctx.auth` by `auth.ctx()`. This
+ * is the authenticated auth shape returned by {@link createAuth().context}.
+ * Optional context builders may still surface nullable fields when
+ * `optional: true` is used.
+ *
+ * - `groupId` is `null` when the user has no active group set.
+ * - `role` is `null` when no active group or no membership is resolved.
+ * - `grants` is `[]` when no active group or no membership is resolved.
+ *
+ * @example
+ * ```ts
+ * import type { AuthContext } from "@robelest/convex-auth/server";
+ *
+ * const mockAuth: AuthContext = {
+ *   userId: "user123" as Id<"User">,
+ *   user: { _id: "user123", email: "test@example.com" },
+ *   groupId: "group456",
+ *   role: "admin",
+ *   grants: ["read", "write"],
+ * };
+ * ```
+ */
+type AuthContext = {
+  /** The authenticated user's document ID. */userId: GenericId<"User">; /** The authenticated user's full document. */
+  user: UserDoc; /** The user's active group ID, or `null` if none set. */
+  groupId: string | null; /** The user's primary role in the active group, or `null`. */
+  role: string | null; /** Resolved grant strings from the user's role definitions. */
+  grants: string[];
+};
+/**
+ * Nullable auth context returned by `auth.context(ctx, { optional: true })`
+ * and injected by `auth.ctx({ optional: true })`.
+ *
+ * Use this when callers may be unauthenticated but you still want a stable
+ * auth-shaped object.
+ *
+ * - `userId` and `user` are `null` when unauthenticated.
+ * - `groupId` and `role` are `null` when no active group is resolved.
+ * - `grants` is `[]` when no membership is resolved.
+ *
+ * @example
+ * ```ts
+ * const authContext = await auth.context(ctx, { optional: true });
+ * if (authContext.userId === null) {
+ *   return null;
+ * }
+ * ```
+ */
+type OptionalAuthContext = {
+  /** The authenticated user's document ID, or `null` when unauthenticated. */userId: GenericId<"User"> | null; /** The authenticated user's full document, or `null` when unauthenticated. */
+  user: UserDoc | null; /** The user's active group ID, or `null` if none is set. */
+  groupId: string | null; /** The user's primary role in the active group, or `null`. */
+  role: string | null; /** Resolved grant strings for the active membership, or `[]`. */
+  grants: string[];
+};
+type AuthContextBase = {
+  getUserIdentity: () => Promise<UserIdentity | null>;
+};
+type RequiredAuthContextState = AuthContextBase & AuthContext;
+type OptionalAuthContextState = AuthContextBase & OptionalAuthContext;
+type ResolvedAuthContext<TResolve> = AuthContext & TResolve;
+type ResolvedOptionalAuthContext<TResolve> = OptionalAuthContext & TResolve;
+type AuthResolverCtx = AuthIdentityCtx & AuthQueryCtx;
+type PublicAuthContextConfig<TResolve extends Record<string, unknown>, TCtx> = AuthContextConfig<TResolve, TCtx & AuthResolverCtx>;
+type AuthContextResolver = {
+  <TCtx, TResolve extends Record<string, unknown> = Record<string, never>>(ctx: TCtx, config: PublicAuthContextConfig<TResolve, TCtx> & {
+    optional: true;
+  }): Promise<ResolvedOptionalAuthContext<TResolve>>;
+  <TCtx, TResolve extends Record<string, unknown> = Record<string, never>>(ctx: TCtx, config?: PublicAuthContextConfig<TResolve, TCtx>): Promise<ResolvedAuthContext<TResolve>>;
+};
+type AuthContextCustomization<TAuth> = {
+  args: {};
+  input: (ctx: AuthResolverCtx, _args: Record<string, never>, _extra?: unknown) => Promise<{
+    ctx: {
+      auth: TAuth;
+    };
+    args: {};
+  }>;
+};
+type AuthContextFactory = {
+  <TResolve extends Record<string, unknown> = Record<string, never>>(config: AuthContextConfig<TResolve> & {
+    optional: true;
+  }): AuthContextCustomization<OptionalAuthContextState & TResolve>;
+  <TResolve extends Record<string, unknown> = Record<string, never>>(config?: AuthContextConfig<TResolve>): AuthContextCustomization<RequiredAuthContextState & TResolve>;
+};
+/**
+ * Minimal auth helper surface required by the context resolvers.
+ *
+ * This stays exported because `auth.ts` re-exports it for compatibility with
+ * existing consumers that reference the low-level context helpers.
+ */
+/**
+ * Configuration for {@link createAuth().ctx} context enrichment.
+ *
+ * The same config shape is also used by {@link createAuth().context}.
+ *
+ * @typeParam TResolve - Extra fields returned from `resolve()` and merged into
+ *   the resulting `ctx.auth` object.
+ *
+ * @example
+ * ```ts
+ * const authContext = await auth.context(ctx, {
+ *   resolve: async (_ctx, user, authState) => ({
+ *     email: user.email,
+ *     canWrite: authState.grants.includes("posts.write"),
+ *   }),
+ * });
+ * ```
+ */
+type AuthContextConfig<TResolve extends Record<string, unknown> = Record<string, never>, TCtx extends AuthIdentityCtx = AuthIdentityCtx> = {
+  /**
+   * Allow unauthenticated callers and return a null-shaped auth object instead
+   * of throwing `NOT_SIGNED_IN`.
+   */
+  optional?: boolean;
+  /**
+   * Attach additional derived fields to the auth context after the base auth
+   * context is resolved.
+   *
+   * This callback runs only when a user is authenticated.
+   */
+  resolve?: (ctx: TCtx, user: UserDoc, auth: AuthContext) => Promise<TResolve> | TResolve;
+  /**
+   * Override or wrap the base auth resolution used by {@link createAuth().ctx}.
+   *
+   * Return `undefined` to fall back to the built-in resolver,
+   * `null` for an explicit unauthenticated state, or an
+   * {@link AuthContext} object to provide a pre-resolved auth state.
+   * This is useful for tests, proxy auth, impersonation flows, or any
+   * environment that needs to inject auth without depending on the standard
+   * Convex auth tables.
+   *
+   * @param ctx - The Convex function context.
+   * @param fallback - The built-in auth resolver used by {@link createAuth().ctx}.
+   * @returns Resolved auth state, `null`, or `undefined` to use the fallback.
+   *
+   * @example
+   * ```ts
+   * const authCtx = auth.ctx({
+   *   authResolve: async (ctx, fallback) => {
+   *     const injected = getInjectedAuth(ctx);
+   *     return injected ?? (await fallback());
+   *   },
+   * });
+   * ```
+   */
+  authResolve?: (ctx: TCtx, fallback: () => Promise<AuthContext | null>) => Promise<AuthContext | null | undefined> | AuthContext | null | undefined;
+};
+/**
+ * Extract the resolved `auth` context type from an `auth.ctx()` customization.
+ *
+ * Use this to type function parameters or variables that receive the
+ * enriched auth context produced by `auth.ctx()`. The inferred type includes
+ * `userId`, `user`, `groupId`, `role`, `grants`, `getUserIdentity`, and any
+ * additional fields added by the `resolve` callback. This is the generic
+ * utility for reusing the enriched auth shape without manually duplicating
+ * conditional auth types.
+ *
+ * @typeParam T - An `auth.ctx()` return value (must have an `input` method
+ *   that returns `{ ctx: { auth: ... } }`).
+ *
+ * @example
+ * ```ts
+ * const authCtx = auth.ctx({
+ *   resolve: async (ctx, user) => ({ orgId: user.orgId }),
+ * });
+ * type Auth = InferAuth<typeof authCtx>;
+ * // Auth = { userId: Id<"User">; user: UserDoc; getUserIdentity: ...; orgId: string }
+ * ```
+ *
+ * @see {@link createAuth}
+ */
+type InferAuth<T extends {
+  input: (...args: never[]) => CustomFunctionInputResult<Record<string, unknown>>;
+}> = Awaited<ReturnType<T["input"]>>["ctx"]["auth"];
+//#endregion
+export { AuthConfig, AuthContext, AuthContextConfig, AuthContextFactory, AuthContextResolver, InferAuth, OptionalAuthContext, UserDoc };
+//# sourceMappingURL=auth-context.d.ts.map

package/dist/server/auth-context.js

@@ -0,0 +1,76 @@
+import { createUnauthenticatedAuthContext, getAuthContext } from "./context.js";
+import { ConvexError } from "convex/values";
+
+//#region src/server/auth-context.ts
+async function resolveConfiguredAuthContext(auth, ctx, config) {
+	const fallback = () => getAuthContext(auth, ctx);
+	const authOverride = config?.authResolve ? await config.authResolve(ctx, fallback) : void 0;
+	return authOverride === void 0 ? await fallback() : authOverride;
+}
+function createNotSignedInError() {
+	return new ConvexError({
+		code: "NOT_SIGNED_IN",
+		message: "Authentication required."
+	});
+}
+function assertAuthResolverContext(ctx) {
+	const candidate = ctx;
+	if (candidate === null || typeof candidate !== "object" || candidate.auth === void 0 || candidate.auth === null || typeof candidate.auth !== "object" || typeof candidate.auth.getUserIdentity !== "function" || typeof candidate.runQuery !== "function") throw new TypeError("auth.context(ctx) requires a Convex function context with auth.getUserIdentity() and runQuery().");
+}
+/**
+* Resolve the public auth context for a Convex handler context.
+*
+* This low-level helper underpins `auth.context(...)` and remains exported for
+* compatibility with existing consumers using the server entrypoint.
+*/
+async function createPublicAuthContext(auth, ctx, config) {
+	const resolved = await resolveConfiguredAuthContext(auth, ctx, config);
+	if (resolved === null) {
+		if (config?.optional !== true) throw createNotSignedInError();
+		return createUnauthenticatedAuthContext();
+	}
+	const extra = config?.resolve ? await config.resolve(ctx, resolved.user, resolved) : {};
+	return {
+		...resolved,
+		...extra
+	};
+}
+/**
+* Create a convex-helpers customization that injects `ctx.auth`.
+*
+* This low-level helper underpins `auth.ctx(...)` and remains exported for
+* compatibility with existing consumers using the server entrypoint.
+*/
+function createAuthContextCustomization(auth, config) {
+	return {
+		args: {},
+		input: async (ctx, _args, _extra) => {
+			const nativeAuth = ctx.auth;
+			const getUserIdentity = nativeAuth.getUserIdentity.bind(nativeAuth);
+			const resolved = await resolveConfiguredAuthContext(auth, ctx, config);
+			if (resolved === null) {
+				if (config?.optional !== true) throw createNotSignedInError();
+				return {
+					ctx: { auth: {
+						getUserIdentity,
+						...createUnauthenticatedAuthContext()
+					} },
+					args: {}
+				};
+			}
+			const extra = config?.resolve ? await config.resolve(ctx, resolved.user, resolved) : {};
+			return {
+				ctx: { auth: {
+					getUserIdentity,
+					...resolved,
+					...extra
+				} },
+				args: {}
+			};
+		}
+	};
+}
+
+//#endregion
+export { assertAuthResolverContext, createAuthContextCustomization, createPublicAuthContext };
+//# sourceMappingURL=auth-context.js.map