@robelest/convex-auth 0.0.4-preview.18 → 0.0.4-preview.19

package/dist/component/server/signin.js.map

@@ -1 +1 @@
-{"version":3,"file":"signin.js","names":[],"sources":["../../../src/server/signin.ts"],"sourcesContent":["import type { Fx as FxType } from \"@robelest/fx\";\nimport { GenericId } from \"convex/values\";\n\nimport { handleDevice } from \"./device\";\nimport { AuthError, Fx } from \"./fx\";\nimport {\n  callCreateVerificationCode,\n  callRefreshSession,\n  callSignIn,\n  callVerifier,\n  callVerifierSignature,\n  callVerifyCodeAndSignIn,\n} from \"./mutations/index\";\nimport { handlePasskeyFx } from \"./passkey\";\nimport { redirectAbsoluteUrl, setURLSearchParam } from \"./redirects\";\nimport { handleTotp } from \"./totp\";\nimport {\n  AuthProviderMaterializedConfig,\n  ConvexCredentialsConfig,\n  EmailConfig,\n  GenericActionCtxWithAuthConfig,\n  PhoneConfig,\n} from \"./types\";\nimport {\n  AuthDataModel,\n  SessionInfo,\n  SessionInfoWithTokens,\n  Tokens,\n  queryTotpVerifiedByUserId,\n} from \"./types\";\nimport type { OAuthMaterializedConfig } from \"./types\";\nimport { generateRandomString } from \"./utils\";\nimport { requireEnv } from \"./utils\";\n\nconst DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S = 60 * 60 * 24; // 24 hours\n\ntype EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;\n\ntype SignInResult =\n  | { kind: \"signedIn\"; signedIn: SessionInfo | null }\n  | { kind: \"refreshTokens\"; signedIn: { tokens: Tokens } }\n  | { kind: \"started\"; started: true }\n  | { kind: \"redirect\"; redirect: string; verifier: string }\n  | { kind: \"passkeyOptions\"; options: Record<string, any>; verifier: string }\n  | { kind: \"totpRequired\"; verifier: string }\n  | {\n      kind: \"totpSetup\";\n      uri: string;\n      secret: string;\n      verifier: string;\n      totpId: string;\n    }\n  | {\n      kind: \"deviceCode\";\n      deviceCode: string;\n      userCode: string;\n      verificationUri: string;\n      verificationUriComplete: string;\n      expiresIn: number;\n      interval: number;\n    };\n\n/** @internal */\nexport async function signInImpl(\n  ctx: EnrichedActionCtx,\n  provider: AuthProviderMaterializedConfig | null,\n  args: {\n    accountId?: GenericId<\"Account\">;\n    params?: Record<string, any>;\n    verifier?: string;\n    refreshToken?: string;\n    calledBy?: string;\n  },\n  options: {\n    generateTokens: boolean;\n    allowExtraProviders: boolean;\n  },\n): Promise<SignInResult> {\n  const fx = signInFx(ctx, provider, args, options);\n  return Fx.run(\n    fx.pipe(Fx.recover((e) => Fx.fatal((e as AuthError).toConvexError()))),\n  );\n}\n\n/**\n * Core sign-in pipeline as an Fx generator.\n *\n * Handles: refresh tokens, verification codes, then dispatches by\n * provider type using a dispatch map (no if-chain).\n */\nfunction signInFx(\n  ctx: EnrichedActionCtx,\n  provider: AuthProviderMaterializedConfig | null,\n  args: {\n    accountId?: GenericId<\"Account\">;\n    params?: Record<string, any>;\n    verifier?: string;\n    refreshToken?: string;\n    calledBy?: string;\n  },\n  options: {\n    generateTokens: boolean;\n    allowExtraProviders: boolean;\n  },\n): FxType<SignInResult, AuthError> {\n  return Fx.gen(function* () {\n    // --- Refresh token (no provider) ---\n    if (provider === null && args.refreshToken) {\n      const tokens = yield* Fx.promise(() =>\n        callRefreshSession(ctx, { refreshToken: args.refreshToken! }),\n      );\n      if (tokens === null) {\n        return { kind: \"signedIn\" as const, signedIn: null };\n      }\n      return { kind: \"refreshTokens\" as const, signedIn: { tokens } };\n    }\n\n    // --- Verify code (no provider, code present) ---\n    if (provider === null && args.params?.code !== undefined) {\n      const result = yield* Fx.promise(() =>\n        callVerifyCodeAndSignIn(ctx, {\n          params: args.params,\n          verifier: args.verifier,\n          generateTokens: true,\n          allowExtraProviders: options.allowExtraProviders,\n        }),\n      );\n      return { kind: \"signedIn\" as const, signedIn: result };\n    }\n\n    // --- Provider is required past this point ---\n    const resolvedProvider = yield* provider != null\n      ? Fx.succeed(provider)\n      : Fx.fail(new AuthError(\"SIGN_IN_MISSING_PARAMS\"));\n\n    // --- Dispatch by provider type ---\n    return yield* Fx.match(resolvedProvider).on(\"type\", {\n      email: (p) => handleEmailAndPhoneProviderFx(ctx, p, args, options),\n      phone: (p) => handleEmailAndPhoneProviderFx(ctx, p, args, options),\n      credentials: (p) => handleCredentialsFx(ctx, p, args, options),\n      oauth: (p) => handleOAuthProviderFx(ctx, p, args, options),\n      passkey: (p) => handlePasskeyFx(ctx, p, args),\n      totp: (p) => handleTotp(ctx, p, args),\n      device: (p) => handleDevice(ctx, p, args),\n      sso: (_p) => handleSsoProviderFx(ctx, args),\n    });\n  });\n}\n\n// ============================================================================\n// Email / Phone\n// ============================================================================\n\nfunction handleEmailAndPhoneProviderFx(\n  ctx: EnrichedActionCtx,\n  provider: EmailConfig | PhoneConfig,\n  args: {\n    params?: Record<string, any>;\n    accountId?: GenericId<\"Account\">;\n  },\n  options: {\n    generateTokens: boolean;\n    allowExtraProviders: boolean;\n  },\n): FxType<\n  | { kind: \"started\"; started: true }\n  | { kind: \"signedIn\"; signedIn: SessionInfoWithTokens },\n  AuthError\n> {\n  return Fx.gen(function* () {\n    // --- Code verification path ---\n    if (args.params?.code !== undefined) {\n      const result = yield* Fx.promise(() =>\n        callVerifyCodeAndSignIn(ctx, {\n          params: args.params,\n          provider: provider.id,\n          generateTokens: options.generateTokens,\n          allowExtraProviders: options.allowExtraProviders,\n        }),\n      );\n      const verified = yield* result != null\n        ? Fx.succeed(result)\n        : Fx.fail(new AuthError(\"INVALID_VERIFICATION_CODE\"));\n      return {\n        kind: \"signedIn\" as const,\n        signedIn: verified as SessionInfoWithTokens,\n      };\n    }\n\n    // --- Send verification code path ---\n    const alphabet =\n      \"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz\";\n    const code = provider.generateVerificationToken\n      ? yield* Fx.from({\n          ok: async () => provider.generateVerificationToken!(),\n          err: () =>\n            new AuthError(\n              \"INTERNAL_ERROR\",\n              \"Failed to generate verification token\",\n            ),\n        })\n      : generateRandomString(32, alphabet);\n    const expirationTime =\n      Date.now() +\n      (provider.maxAge ?? DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S) * 1000;\n\n    const identifier = yield* Fx.promise(() =>\n      callCreateVerificationCode(ctx, {\n        provider: provider.id,\n        accountId: args.accountId,\n        email: args.params?.email,\n        phone: args.params?.phone,\n        code,\n        expirationTime,\n        allowExtraProviders: options.allowExtraProviders,\n      }),\n    );\n    const destination = yield* Fx.promise(() =>\n      redirectAbsoluteUrl(\n        ctx.auth.config,\n        (args.params ?? {}) as { redirectTo: unknown },\n      ),\n    );\n    const verificationArgs = {\n      identifier,\n      url: setURLSearchParam(destination, \"code\", code),\n      token: code,\n      expires: new Date(expirationTime),\n    };\n    yield* Fx.match(provider).on(\"type\", {\n      email: (p) =>\n        Fx.from({\n          ok: async () =>\n            p.sendVerificationRequest(\n              {\n                ...verificationArgs,\n                provider: p,\n                request: new Request(\"http://localhost\"),\n              },\n              ctx,\n            ),\n          err: () =>\n            new AuthError(\"INTERNAL_ERROR\", \"Failed to send email code\"),\n        }),\n      phone: (p) =>\n        Fx.from({\n          ok: async () =>\n            p.sendVerificationRequest(\n              { ...verificationArgs, provider: p },\n              ctx,\n            ),\n          err: () =>\n            new AuthError(\"INTERNAL_ERROR\", \"Failed to send phone code\"),\n        }),\n    });\n    return { kind: \"started\" as const, started: true as const };\n  });\n}\n\n// ============================================================================\n// Credentials\n// ============================================================================\n\nfunction handleCredentialsFx(\n  ctx: EnrichedActionCtx,\n  provider: ConvexCredentialsConfig,\n  args: {\n    params?: Record<string, any>;\n  },\n  options: {\n    generateTokens: boolean;\n  },\n): FxType<\n  | { kind: \"signedIn\"; signedIn: SessionInfo | null }\n  | { kind: \"totpRequired\"; verifier: string },\n  AuthError\n> {\n  return Fx.gen(function* () {\n    const result = yield* Fx.promise(() =>\n      provider.authorize(args.params ?? {}, ctx),\n    );\n    if (result === null) {\n      return { kind: \"signedIn\" as const, signedIn: null };\n    }\n\n    // Check if user has TOTP 2FA enrolled before issuing tokens\n    const hasTotpEnrolled = yield* Fx.promise(async () => {\n      const totpDoc = await queryTotpVerifiedByUserId(ctx, result.userId);\n      return totpDoc !== null;\n    });\n    if (hasTotpEnrolled) {\n      // Create session but withhold tokens — TOTP verification needed\n      yield* Fx.promise(() =>\n        callSignIn(ctx, {\n          userId: result.userId,\n          sessionId: result.sessionId,\n          generateTokens: false,\n        }),\n      );\n      // Store userId in verifier so the TOTP verify flow can complete sign-in\n      const verifier = yield* Fx.promise(() => callVerifier(ctx));\n      yield* Fx.promise(() =>\n        callVerifierSignature(ctx, {\n          verifier,\n          signature: JSON.stringify({ userId: result.userId }),\n        }),\n      );\n      return { kind: \"totpRequired\" as const, verifier };\n    }\n\n    const idsAndTokens = yield* Fx.promise(() =>\n      callSignIn(ctx, {\n        userId: result.userId,\n        sessionId: result.sessionId,\n        generateTokens: options.generateTokens,\n      }),\n    );\n    return { kind: \"signedIn\" as const, signedIn: idsAndTokens };\n  });\n}\n\n// ============================================================================\n// OAuth\n// ============================================================================\n\nfunction handleOAuthProviderFx(\n  ctx: EnrichedActionCtx,\n  provider: OAuthMaterializedConfig,\n  args: {\n    params?: Record<string, any>;\n    verifier?: string;\n  },\n  options: {\n    allowExtraProviders: boolean;\n  },\n): FxType<\n  | { kind: \"signedIn\"; signedIn: SessionInfoWithTokens | null }\n  | { kind: \"redirect\"; redirect: string; verifier: string },\n  AuthError\n> {\n  return Fx.gen(function* () {\n    // --- Code verification path ---\n    if (args.params?.code !== undefined) {\n      const result = yield* Fx.promise(() =>\n        callVerifyCodeAndSignIn(ctx, {\n          params: args.params,\n          verifier: args.verifier,\n          generateTokens: true,\n          allowExtraProviders: options.allowExtraProviders,\n        }),\n      );\n      return {\n        kind: \"signedIn\" as const,\n        signedIn: result as SessionInfoWithTokens | null,\n      };\n    }\n\n    // --- Build redirect URL ---\n    const redirect = new URL(\n      (process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv(\"CONVEX_SITE_URL\")) +\n        `/api/auth/signin/${provider.id}`,\n    );\n    const verifier = yield* Fx.promise(() => callVerifier(ctx));\n    redirect.searchParams.set(\"code\", verifier);\n\n    if (args.params?.redirectTo !== undefined) {\n      yield* Fx.guard(\n        typeof args.params.redirectTo !== \"string\",\n        Fx.fail(\n          new AuthError(\n            \"INVALID_REDIRECT\",\n            `Expected \\`redirectTo\\` to be a string, got ${args.params.redirectTo}`,\n          ),\n        ),\n      );\n      redirect.searchParams.set(\"redirectTo\", args.params.redirectTo);\n    }\n\n    return {\n      kind: \"redirect\" as const,\n      redirect: redirect.toString(),\n      verifier,\n    };\n  });\n}\n\n// ============================================================================\n// SSO (Enterprise OIDC / SAML)\n// ============================================================================\n\nfunction handleSsoProviderFx(\n  ctx: EnrichedActionCtx,\n  args: {\n    params?: Record<string, any>;\n  },\n): FxType<{ kind: \"redirect\"; redirect: string; verifier: string }, AuthError> {\n  return Fx.gen(function* () {\n    const enterpriseId = args.params?.enterpriseId;\n    if (!enterpriseId || typeof enterpriseId !== \"string\") {\n      return yield* Fx.fail(\n        new AuthError(\n          \"SIGN_IN_MISSING_PARAMS\",\n          \"enterpriseId is required for SSO sign-in.\",\n        ),\n      );\n    }\n\n    const protocol: \"oidc\" | \"saml\" = args.params?.protocol ?? \"oidc\";\n    if (protocol !== \"oidc\" && protocol !== \"saml\") {\n      return yield* Fx.fail(\n        new AuthError(\n          \"SIGN_IN_MISSING_PARAMS\",\n          `Invalid SSO protocol: ${protocol as string}. Expected \"oidc\" or \"saml\".`,\n        ),\n      );\n    }\n\n    const verifier = yield* Fx.promise(() => callVerifier(ctx));\n    const siteUrl =\n      process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv(\"CONVEX_SITE_URL\");\n    const redirect = new URL(\n      `${siteUrl}/api/auth/sso/${enterpriseId}/${protocol}/signin`,\n    );\n    redirect.searchParams.set(\"code\", verifier);\n\n    if (typeof args.params?.redirectTo === \"string\") {\n      redirect.searchParams.set(\"redirectTo\", args.params.redirectTo);\n    }\n\n    return {\n      kind: \"redirect\" as const,\n      redirect: redirect.toString(),\n      verifier,\n    };\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"signin.js","names":[],"sources":["../../../src/server/signin.ts"],"sourcesContent":["import type { Fx as FxType } from \"@robelest/fx\";\nimport { GenericId } from \"convex/values\";\n\nimport { handleDevice } from \"./device\";\nimport { Fx } from \"@robelest/fx\";\n\nimport { AuthError } from \"./authError\";\nimport {\n  callCreateVerificationCode,\n  callRefreshSession,\n  callSignIn,\n  callVerifier,\n  callVerifierSignature,\n  callVerifyCodeAndSignIn,\n} from \"./mutations/index\";\nimport { handlePasskeyFx } from \"./passkey\";\nimport { redirectAbsoluteUrl, setURLSearchParam } from \"./redirects\";\nimport { handleTotp } from \"./totp\";\nimport {\n  AuthProviderMaterializedConfig,\n  ConvexCredentialsConfig,\n  EmailConfig,\n  GenericActionCtxWithAuthConfig,\n  PhoneConfig,\n} from \"./types\";\nimport {\n  AuthDataModel,\n  SessionInfo,\n  SessionInfoWithTokens,\n  Tokens,\n  queryTotpVerifiedByUserId,\n} from \"./types\";\nimport type { OAuthMaterializedConfig } from \"./types\";\nimport { generateRandomString } from \"./utils\";\nimport { requireEnv } from \"./utils\";\n\nconst DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S = 60 * 60 * 24; // 24 hours\n\ntype EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;\n\ntype SignInResult =\n  | { kind: \"signedIn\"; signedIn: SessionInfo | null }\n  | { kind: \"refreshTokens\"; signedIn: { tokens: Tokens } }\n  | { kind: \"started\"; started: true }\n  | { kind: \"redirect\"; redirect: string; verifier: string }\n  | { kind: \"passkeyOptions\"; options: Record<string, any>; verifier: string }\n  | { kind: \"totpRequired\"; verifier: string }\n  | {\n      kind: \"totpSetup\";\n      uri: string;\n      secret: string;\n      verifier: string;\n      totpId: string;\n    }\n  | {\n      kind: \"deviceCode\";\n      deviceCode: string;\n      userCode: string;\n      verificationUri: string;\n      verificationUriComplete: string;\n      expiresIn: number;\n      interval: number;\n    };\n\n/** @internal */\nexport async function signInImpl(\n  ctx: EnrichedActionCtx,\n  provider: AuthProviderMaterializedConfig | null,\n  args: {\n    accountId?: GenericId<\"Account\">;\n    params?: Record<string, any>;\n    verifier?: string;\n    refreshToken?: string;\n    calledBy?: string;\n  },\n  options: {\n    generateTokens: boolean;\n    allowExtraProviders: boolean;\n  },\n): Promise<SignInResult> {\n  const fx = signInFx(ctx, provider, args, options);\n  return Fx.run(\n    fx.pipe(Fx.recover((e) => Fx.fatal((e as AuthError).toConvexError()))),\n  );\n}\n\n/**\n * Core sign-in pipeline as an Fx generator.\n *\n * Handles: refresh tokens, verification codes, then dispatches by\n * provider type using a dispatch map (no if-chain).\n */\nfunction signInFx(\n  ctx: EnrichedActionCtx,\n  provider: AuthProviderMaterializedConfig | null,\n  args: {\n    accountId?: GenericId<\"Account\">;\n    params?: Record<string, any>;\n    verifier?: string;\n    refreshToken?: string;\n    calledBy?: string;\n  },\n  options: {\n    generateTokens: boolean;\n    allowExtraProviders: boolean;\n  },\n): FxType<SignInResult, AuthError> {\n  return Fx.gen(function* () {\n    // --- Refresh token (no provider) ---\n    if (provider === null && args.refreshToken) {\n      const tokens = yield* Fx.promise(() =>\n        callRefreshSession(ctx, { refreshToken: args.refreshToken! }),\n      );\n      if (tokens === null) {\n        return { kind: \"signedIn\" as const, signedIn: null };\n      }\n      return { kind: \"refreshTokens\" as const, signedIn: { tokens } };\n    }\n\n    // --- Verify code (no provider, code present) ---\n    if (provider === null && args.params?.code !== undefined) {\n      const result = yield* Fx.promise(() =>\n        callVerifyCodeAndSignIn(ctx, {\n          params: args.params,\n          verifier: args.verifier,\n          generateTokens: true,\n          allowExtraProviders: options.allowExtraProviders,\n        }),\n      );\n      return { kind: \"signedIn\" as const, signedIn: result };\n    }\n\n    // --- Provider is required past this point ---\n    const resolvedProvider = yield* provider != null\n      ? Fx.succeed(provider)\n      : Fx.fail(new AuthError(\"SIGN_IN_MISSING_PARAMS\"));\n\n    // --- Dispatch by provider type ---\n    return yield* Fx.match(resolvedProvider).on(\"type\", {\n      email: (p) => handleEmailAndPhoneProviderFx(ctx, p, args, options),\n      phone: (p) => handleEmailAndPhoneProviderFx(ctx, p, args, options),\n      credentials: (p) => handleCredentialsFx(ctx, p, args, options),\n      oauth: (p) => handleOAuthProviderFx(ctx, p, args, options),\n      passkey: (p) => handlePasskeyFx(ctx, p, args),\n      totp: (p) => handleTotp(ctx, p, args),\n      device: (p) => handleDevice(ctx, p, args),\n      sso: (_p) => handleSsoProviderFx(ctx, args),\n    });\n  });\n}\n\n// ============================================================================\n// Email / Phone\n// ============================================================================\n\nfunction handleEmailAndPhoneProviderFx(\n  ctx: EnrichedActionCtx,\n  provider: EmailConfig | PhoneConfig,\n  args: {\n    params?: Record<string, any>;\n    accountId?: GenericId<\"Account\">;\n  },\n  options: {\n    generateTokens: boolean;\n    allowExtraProviders: boolean;\n  },\n): FxType<\n  | { kind: \"started\"; started: true }\n  | { kind: \"signedIn\"; signedIn: SessionInfoWithTokens },\n  AuthError\n> {\n  return Fx.gen(function* () {\n    // --- Code verification path ---\n    if (args.params?.code !== undefined) {\n      const result = yield* Fx.promise(() =>\n        callVerifyCodeAndSignIn(ctx, {\n          params: args.params,\n          provider: provider.id,\n          generateTokens: options.generateTokens,\n          allowExtraProviders: options.allowExtraProviders,\n        }),\n      );\n      const verified = yield* result != null\n        ? Fx.succeed(result)\n        : Fx.fail(new AuthError(\"INVALID_VERIFICATION_CODE\"));\n      return {\n        kind: \"signedIn\" as const,\n        signedIn: verified as SessionInfoWithTokens,\n      };\n    }\n\n    // --- Send verification code path ---\n    const alphabet =\n      \"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz\";\n    const code = provider.generateVerificationToken\n      ? yield* Fx.from({\n          ok: async () => provider.generateVerificationToken!(),\n          err: () =>\n            new AuthError(\n              \"INTERNAL_ERROR\",\n              \"Failed to generate verification token\",\n            ),\n        })\n      : generateRandomString(32, alphabet);\n    const expirationTime =\n      Date.now() +\n      (provider.maxAge ?? DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S) * 1000;\n\n    const identifier = yield* Fx.promise(() =>\n      callCreateVerificationCode(ctx, {\n        provider: provider.id,\n        accountId: args.accountId,\n        email: args.params?.email,\n        phone: args.params?.phone,\n        code,\n        expirationTime,\n        allowExtraProviders: options.allowExtraProviders,\n      }),\n    );\n    const destination = yield* Fx.promise(() =>\n      redirectAbsoluteUrl(\n        ctx.auth.config,\n        (args.params ?? {}) as { redirectTo: unknown },\n      ),\n    );\n    const verificationArgs = {\n      identifier,\n      url: setURLSearchParam(destination, \"code\", code),\n      token: code,\n      expires: new Date(expirationTime),\n    };\n    yield* Fx.match(provider).on(\"type\", {\n      email: (p) =>\n        Fx.from({\n          ok: async () =>\n            p.sendVerificationRequest(\n              {\n                ...verificationArgs,\n                provider: p,\n                request: new Request(\"http://localhost\"),\n              },\n              ctx,\n            ),\n          err: () =>\n            new AuthError(\"INTERNAL_ERROR\", \"Failed to send email code\"),\n        }),\n      phone: (p) =>\n        Fx.from({\n          ok: async () =>\n            p.sendVerificationRequest(\n              { ...verificationArgs, provider: p },\n              ctx,\n            ),\n          err: () =>\n            new AuthError(\"INTERNAL_ERROR\", \"Failed to send phone code\"),\n        }),\n    });\n    return { kind: \"started\" as const, started: true as const };\n  });\n}\n\n// ============================================================================\n// Credentials\n// ============================================================================\n\nfunction handleCredentialsFx(\n  ctx: EnrichedActionCtx,\n  provider: ConvexCredentialsConfig,\n  args: {\n    params?: Record<string, any>;\n  },\n  options: {\n    generateTokens: boolean;\n  },\n): FxType<\n  | { kind: \"signedIn\"; signedIn: SessionInfo | null }\n  | { kind: \"totpRequired\"; verifier: string },\n  AuthError\n> {\n  return Fx.gen(function* () {\n    const result = yield* Fx.promise(() =>\n      provider.authorize(args.params ?? {}, ctx),\n    );\n    if (result === null) {\n      return { kind: \"signedIn\" as const, signedIn: null };\n    }\n\n    // Check if user has TOTP 2FA enrolled before issuing tokens\n    const hasTotpEnrolled = yield* Fx.promise(async () => {\n      const totpDoc = await queryTotpVerifiedByUserId(ctx, result.userId);\n      return totpDoc !== null;\n    });\n    if (hasTotpEnrolled) {\n      // Create session but withhold tokens — TOTP verification needed\n      yield* Fx.promise(() =>\n        callSignIn(ctx, {\n          userId: result.userId,\n          sessionId: result.sessionId,\n          generateTokens: false,\n        }),\n      );\n      // Store userId in verifier so the TOTP verify flow can complete sign-in\n      const verifier = yield* Fx.promise(() => callVerifier(ctx));\n      yield* Fx.promise(() =>\n        callVerifierSignature(ctx, {\n          verifier,\n          signature: JSON.stringify({ userId: result.userId }),\n        }),\n      );\n      return { kind: \"totpRequired\" as const, verifier };\n    }\n\n    const idsAndTokens = yield* Fx.promise(() =>\n      callSignIn(ctx, {\n        userId: result.userId,\n        sessionId: result.sessionId,\n        generateTokens: options.generateTokens,\n      }),\n    );\n    return { kind: \"signedIn\" as const, signedIn: idsAndTokens };\n  });\n}\n\n// ============================================================================\n// OAuth\n// ============================================================================\n\nfunction handleOAuthProviderFx(\n  ctx: EnrichedActionCtx,\n  provider: OAuthMaterializedConfig,\n  args: {\n    params?: Record<string, any>;\n    verifier?: string;\n  },\n  options: {\n    allowExtraProviders: boolean;\n  },\n): FxType<\n  | { kind: \"signedIn\"; signedIn: SessionInfoWithTokens | null }\n  | { kind: \"redirect\"; redirect: string; verifier: string },\n  AuthError\n> {\n  return Fx.gen(function* () {\n    // --- Code verification path ---\n    if (args.params?.code !== undefined) {\n      const result = yield* Fx.promise(() =>\n        callVerifyCodeAndSignIn(ctx, {\n          params: args.params,\n          verifier: args.verifier,\n          generateTokens: true,\n          allowExtraProviders: options.allowExtraProviders,\n        }),\n      );\n      return {\n        kind: \"signedIn\" as const,\n        signedIn: result as SessionInfoWithTokens | null,\n      };\n    }\n\n    // --- Build redirect URL ---\n    const redirect = new URL(\n      (process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv(\"CONVEX_SITE_URL\")) +\n        `/api/auth/signin/${provider.id}`,\n    );\n    const verifier = yield* Fx.promise(() => callVerifier(ctx));\n    redirect.searchParams.set(\"code\", verifier);\n\n    if (args.params?.redirectTo !== undefined) {\n      yield* Fx.guard(\n        typeof args.params.redirectTo !== \"string\",\n        Fx.fail(\n          new AuthError(\n            \"INVALID_REDIRECT\",\n            `Expected \\`redirectTo\\` to be a string, got ${args.params.redirectTo}`,\n          ),\n        ),\n      );\n      redirect.searchParams.set(\"redirectTo\", args.params.redirectTo);\n    }\n\n    return {\n      kind: \"redirect\" as const,\n      redirect: redirect.toString(),\n      verifier,\n    };\n  });\n}\n\n// ============================================================================\n// SSO (Enterprise OIDC / SAML)\n// ============================================================================\n\nfunction handleSsoProviderFx(\n  ctx: EnrichedActionCtx,\n  args: {\n    params?: Record<string, any>;\n  },\n): FxType<{ kind: \"redirect\"; redirect: string; verifier: string }, AuthError> {\n  return Fx.gen(function* () {\n    const enterpriseId = args.params?.enterpriseId;\n    if (!enterpriseId || typeof enterpriseId !== \"string\") {\n      return yield* Fx.fail(\n        new AuthError(\n          \"SIGN_IN_MISSING_PARAMS\",\n          \"enterpriseId is required for SSO sign-in.\",\n        ),\n      );\n    }\n\n    const protocol: \"oidc\" | \"saml\" = args.params?.protocol ?? \"oidc\";\n    if (protocol !== \"oidc\" && protocol !== \"saml\") {\n      return yield* Fx.fail(\n        new AuthError(\n          \"SIGN_IN_MISSING_PARAMS\",\n          `Invalid SSO protocol: ${protocol as string}. Expected \"oidc\" or \"saml\".`,\n        ),\n      );\n    }\n\n    const verifier = yield* Fx.promise(() => callVerifier(ctx));\n    const siteUrl =\n      process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv(\"CONVEX_SITE_URL\");\n    const redirect = new URL(\n      `${siteUrl}/api/auth/sso/${enterpriseId}/${protocol}/signin`,\n    );\n    redirect.searchParams.set(\"code\", verifier);\n\n    if (typeof args.params?.redirectTo === \"string\") {\n      redirect.searchParams.set(\"redirectTo\", args.params.redirectTo);\n    }\n\n    return {\n      kind: \"redirect\" as const,\n      redirect: redirect.toString(),\n      verifier,\n    };\n  });\n}\n"],"mappings":"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"}

package/dist/component/server/totp.js

@@ -1,10 +1,11 @@
-import { AuthError, Fx } from "./fx.js";
+import { AuthError } from "./authError.js";
 import { userIdFromIdentitySubject } from "./identity.js";
 import { callVerifierSignature } from "./mutations/signature.js";
 import { callSignIn } from "./mutations/signin.js";
 import { callVerifier } from "./mutations/verifier.js";
 import { mutateTotpInsert, mutateTotpMarkVerified, mutateTotpUpdateLastUsed, mutateVerifierDelete, queryTotpById, queryTotpVerifiedByUserId, queryUserById, queryVerifierById } from "./types.js";
 import { encodeBase32LowerCaseNoPadding } from "@oslojs/encoding";
+import { Fx } from "@robelest/fx";
 import { createTOTPKeyURI, verifyTOTPWithGracePeriod } from "@oslojs/otp";
 
 //#region src/server/totp.ts

package/dist/component/server/totp.js.map

@@ -1 +1 @@
-{"version":3,"file":"totp.js","names":["code","verifier"],"sources":["../../../src/server/totp.ts"],"sourcesContent":["/**\n * Server-side TOTP ceremony logic for two-factor authentication.\n *\n * Handles the three phases of the TOTP flow:\n * 1. setup   — generate a TOTP secret and `otpauth://` URI for enrollment\n * 2. confirm — verify the first code from the authenticator app\n * 3. verify  — verify a TOTP code during sign-in (2FA challenge)\n */\n\nimport { encodeBase32LowerCaseNoPadding } from \"@oslojs/encoding\";\nimport { verifyTOTPWithGracePeriod, createTOTPKeyURI } from \"@oslojs/otp\";\nimport type { Fx as FxType } from \"@robelest/fx\";\n\nimport { AuthError, Fx } from \"./fx\";\nimport { userIdFromIdentitySubject } from \"./identity\";\nimport { callSignIn, callVerifier } from \"./mutations/index\";\nimport { callVerifierSignature } from \"./mutations/signature\";\nimport { TotpProviderConfig, GenericActionCtxWithAuthConfig } from \"./types\";\nimport {\n  AuthDataModel,\n  SessionInfo,\n  queryUserById,\n  queryTotpById,\n  queryTotpVerifiedByUserId,\n  queryVerifierById,\n  mutateTotpInsert,\n  mutateTotpMarkVerified,\n  mutateTotpUpdateLastUsed,\n  mutateVerifierDelete,\n} from \"./types\";\n\ntype EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;\n\n// ============================================================================\n// Setup flow\n// ============================================================================\n\n// ============================================================================\n// Confirm flow\n// ============================================================================\n\n// ============================================================================\n// Verify flow (2FA during sign-in)\n// ============================================================================\n\n// ============================================================================\n// Main dispatch\n// ============================================================================\n\ntype TotpResult =\n  | { kind: \"signedIn\"; signedIn: SessionInfo | null }\n  | {\n      kind: \"totpSetup\";\n      uri: string;\n      secret: string;\n      verifier: string;\n      totpId: string;\n    };\n\nconst TOTP_FLOWS = [\"setup\", \"confirm\", \"verify\"] as const;\n\ntype TotpFlow = (typeof TOTP_FLOWS)[number];\n\ntype TotpDispatch =\n  | { flow: \"setup\"; params: Record<string, unknown> }\n  | { flow: \"confirm\"; code: string; totpId: string; verifier: string }\n  | { flow: \"verify\"; code: string; verifier: string };\n\nconst resolveTotpFlowFx = (\n  params: Record<string, unknown>,\n): FxType<TotpFlow, AuthError> => {\n  const flow = params.flow;\n  return typeof flow === \"string\" && TOTP_FLOWS.includes(flow as never)\n    ? Fx.succeed(flow as TotpFlow)\n    : Fx.fail(\n        new AuthError(\n          \"TOTP_MISSING_FLOW\",\n          \"Missing `flow` parameter. Expected one of: setup, confirm, verify\",\n        ),\n      );\n};\n\nconst requireTotpVerifierFx = (\n  verifier: string | undefined,\n): FxType<string, AuthError> =>\n  verifier != null\n    ? Fx.succeed(verifier)\n    : Fx.fail(new AuthError(\"TOTP_MISSING_VERIFIER\"));\n\nconst requireTotpCodeFx = (\n  params: Record<string, unknown>,\n): FxType<string, AuthError> =>\n  typeof params.code === \"string\"\n    ? Fx.succeed(params.code)\n    : Fx.fail(new AuthError(\"TOTP_MISSING_CODE\"));\n\nconst requireTotpIdFx = (\n  params: Record<string, unknown>,\n): FxType<string, AuthError> =>\n  typeof params.totpId === \"string\"\n    ? Fx.succeed(params.totpId)\n    : Fx.fail(new AuthError(\"TOTP_MISSING_ID\"));\n\nconst resolveTotpDispatchFx = (\n  params: Record<string, unknown>,\n  verifier: string | undefined,\n): FxType<TotpDispatch, AuthError> =>\n  resolveTotpFlowFx(params).pipe(\n    Fx.chain((flow) =>\n      Fx.match({ flow }).on(\"flow\", {\n        setup: () => Fx.succeed({ flow: \"setup\" as const, params }),\n        confirm: () =>\n          Fx.gen(function* () {\n            const resolvedVerifier = yield* requireTotpVerifierFx(verifier);\n            const code = yield* requireTotpCodeFx(params);\n            const totpId = yield* requireTotpIdFx(params);\n            return {\n              flow: \"confirm\" as const,\n              code,\n              totpId,\n              verifier: resolvedVerifier,\n            };\n          }),\n        verify: () =>\n          Fx.gen(function* () {\n            const resolvedVerifier = yield* requireTotpVerifierFx(verifier);\n            const code = yield* requireTotpCodeFx(params);\n            return {\n              flow: \"verify\" as const,\n              code,\n              verifier: resolvedVerifier,\n            };\n          }),\n      }),\n    ),\n  );\n\n/** @internal */\nexport const handleTotp = (\n  ctx: EnrichedActionCtx,\n  provider: TotpProviderConfig,\n  args: { params?: Record<string, any>; verifier?: string },\n): FxType<TotpResult, AuthError> => {\n  const params = (args.params ?? {}) as Record<string, unknown>;\n\n  return resolveTotpDispatchFx(params, args.verifier).pipe(\n    Fx.chain((dispatch) =>\n      Fx.match(dispatch).on(\"flow\", {\n        setup: ({ params }) =>\n          Fx.from({\n            ok: () => ctx.auth.getUserIdentity(),\n            err: (e) => new AuthError(\"INTERNAL_ERROR\", String(e)),\n          }).pipe(\n            Fx.chain((identity) =>\n              identity === null\n                ? Fx.fail(new AuthError(\"TOTP_AUTH_REQUIRED\"))\n                : Fx.succeed(userIdFromIdentitySubject(identity.subject)),\n            ),\n            Fx.chain((userId) =>\n              Fx.from({\n                ok: async () => {\n                  const secret = new Uint8Array(20);\n                  crypto.getRandomValues(secret);\n\n                  let accountName: string = params.accountName as string;\n                  if (!accountName) {\n                    const user = await queryUserById(ctx, userId);\n                    accountName = user?.email ?? \"user\";\n                  }\n\n                  const uri = createTOTPKeyURI(\n                    provider.options.issuer,\n                    accountName,\n                    secret,\n                    provider.options.period,\n                    provider.options.digits,\n                  );\n                  const base32Secret = encodeBase32LowerCaseNoPadding(secret);\n\n                  const verifier = await callVerifier(ctx);\n                  await callVerifierSignature(ctx, {\n                    verifier,\n                    signature: JSON.stringify({\n                      secret: Array.from(secret),\n                      userId,\n                      digits: provider.options.digits,\n                      period: provider.options.period,\n                    }),\n                  });\n\n                  const totpId = await mutateTotpInsert(ctx, {\n                    userId,\n                    secret: secret.buffer.slice(\n                      secret.byteOffset,\n                      secret.byteOffset + secret.byteLength,\n                    ),\n                    digits: provider.options.digits,\n                    period: provider.options.period,\n                    verified: false,\n                    name:\n                      typeof params.name === \"string\" ? params.name : undefined,\n                    createdAt: Date.now(),\n                  });\n\n                  return {\n                    kind: \"totpSetup\" as const,\n                    uri,\n                    secret: base32Secret,\n                    verifier,\n                    totpId,\n                  };\n                },\n                err: (e) =>\n                  new AuthError(\n                    \"INTERNAL_ERROR\",\n                    `TOTP setup failed: ${String(e)}`,\n                  ),\n              }),\n            ),\n          ),\n        confirm: ({ code, totpId, verifier }) =>\n          Fx.from({\n            ok: () => ctx.auth.getUserIdentity(),\n            err: (e) => new AuthError(\"INTERNAL_ERROR\", String(e)),\n          }).pipe(\n            Fx.chain((identity) =>\n              identity === null\n                ? Fx.fail(new AuthError(\"TOTP_AUTH_REQUIRED\"))\n                : Fx.succeed(userIdFromIdentitySubject(identity.subject)),\n            ),\n            Fx.chain((userId) =>\n              Fx.from({\n                ok: () => queryTotpById(ctx, totpId),\n                err: () => new AuthError(\"TOTP_NOT_FOUND\"),\n              })\n                .pipe(\n                  Fx.chain((doc) =>\n                    doc === null\n                      ? Fx.fail(new AuthError(\"TOTP_NOT_FOUND\"))\n                      : Fx.succeed(doc),\n                  ),\n                  Fx.chain((totpDoc) =>\n                    totpDoc.verified\n                      ? Fx.fail(new AuthError(\"TOTP_ALREADY_VERIFIED\"))\n                      : Fx.succeed(totpDoc),\n                  ),\n                )\n                .pipe(\n                  Fx.chain((totpDoc) =>\n                    verifyTOTPWithGracePeriod(\n                      new Uint8Array(totpDoc.secret),\n                      provider.options.period,\n                      provider.options.digits,\n                      code,\n                      30,\n                    )\n                      ? Fx.succeed(totpDoc)\n                      : Fx.fail(new AuthError(\"TOTP_INVALID_CODE\")),\n                  ),\n                )\n                .pipe(\n                  Fx.chain((_totpDoc) =>\n                    Fx.from({\n                      ok: async () => {\n                        await mutateTotpMarkVerified(ctx, totpId, Date.now());\n                        await mutateVerifierDelete(ctx, verifier);\n                        return callSignIn(ctx, {\n                          userId,\n                          generateTokens: true,\n                        });\n                      },\n                      err: (e) => new AuthError(\"INTERNAL_ERROR\", String(e)),\n                    }),\n                  ),\n                )\n                .pipe(\n                  Fx.map((signInResult) => ({\n                    kind: \"signedIn\" as const,\n                    signedIn: signInResult,\n                  })),\n                ),\n            ),\n          ),\n        verify: ({ code, verifier }) =>\n          Fx.from({\n            ok: () => queryVerifierById(ctx, verifier),\n            err: () => new AuthError(\"TOTP_INVALID_VERIFIER\"),\n          }).pipe(\n            Fx.chain((doc) =>\n              doc === null\n                ? Fx.fail(new AuthError(\"TOTP_INVALID_VERIFIER\"))\n                : Fx.succeed(doc),\n            ),\n            Fx.map((doc) => {\n              const data = JSON.parse(doc.signature!);\n              return { userId: data.userId as string, code, verifier };\n            }),\n            Fx.chain(({ userId, code, verifier }) =>\n              Fx.from({\n                ok: () => queryTotpVerifiedByUserId(ctx, userId),\n                err: () => new AuthError(\"TOTP_NO_ENROLLMENT\"),\n              }).pipe(\n                Fx.chain((totpDoc) =>\n                  totpDoc === null\n                    ? Fx.fail(new AuthError(\"TOTP_NO_ENROLLMENT\"))\n                    : Fx.succeed(totpDoc),\n                ),\n                Fx.chain((totpDoc) =>\n                  verifyTOTPWithGracePeriod(\n                    new Uint8Array(totpDoc.secret),\n                    totpDoc.period,\n                    totpDoc.digits,\n                    code,\n                    30,\n                  )\n                    ? Fx.succeed(totpDoc)\n                    : Fx.fail(new AuthError(\"TOTP_INVALID_CODE\")),\n                ),\n                Fx.chain((totpDoc) =>\n                  Fx.from({\n                    ok: async () => {\n                      await mutateTotpUpdateLastUsed(\n                        ctx,\n                        totpDoc._id,\n                        Date.now(),\n                      );\n                      await mutateVerifierDelete(ctx, verifier);\n                      return callSignIn(ctx, { userId, generateTokens: true });\n                    },\n                    err: (e) => new AuthError(\"INTERNAL_ERROR\", String(e)),\n                  }),\n                ),\n                Fx.map((signInResult) => ({\n                  kind: \"signedIn\" as const,\n                  signedIn: signInResult,\n                })),\n              ),\n            ),\n          ),\n      }),\n    ),\n  );\n};\n\n// ============================================================================\n// Helpers\n// ============================================================================\n"],"mappings":"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"}
+{"version":3,"file":"totp.js","names":["code","verifier"],"sources":["../../../src/server/totp.ts"],"sourcesContent":["/**\n * Server-side TOTP ceremony logic for two-factor authentication.\n *\n * Handles the three phases of the TOTP flow:\n * 1. setup   — generate a TOTP secret and `otpauth://` URI for enrollment\n * 2. confirm — verify the first code from the authenticator app\n * 3. verify  — verify a TOTP code during sign-in (2FA challenge)\n */\n\nimport { encodeBase32LowerCaseNoPadding } from \"@oslojs/encoding\";\nimport { verifyTOTPWithGracePeriod, createTOTPKeyURI } from \"@oslojs/otp\";\nimport type { Fx as FxType } from \"@robelest/fx\";\n\nimport { Fx } from \"@robelest/fx\";\n\nimport { AuthError } from \"./authError\";\nimport { userIdFromIdentitySubject } from \"./identity\";\nimport { callSignIn, callVerifier } from \"./mutations/index\";\nimport { callVerifierSignature } from \"./mutations/signature\";\nimport { TotpProviderConfig, GenericActionCtxWithAuthConfig } from \"./types\";\nimport {\n  AuthDataModel,\n  SessionInfo,\n  queryUserById,\n  queryTotpById,\n  queryTotpVerifiedByUserId,\n  queryVerifierById,\n  mutateTotpInsert,\n  mutateTotpMarkVerified,\n  mutateTotpUpdateLastUsed,\n  mutateVerifierDelete,\n} from \"./types\";\n\ntype EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;\n\n// ============================================================================\n// Setup flow\n// ============================================================================\n\n// ============================================================================\n// Confirm flow\n// ============================================================================\n\n// ============================================================================\n// Verify flow (2FA during sign-in)\n// ============================================================================\n\n// ============================================================================\n// Main dispatch\n// ============================================================================\n\ntype TotpResult =\n  | { kind: \"signedIn\"; signedIn: SessionInfo | null }\n  | {\n      kind: \"totpSetup\";\n      uri: string;\n      secret: string;\n      verifier: string;\n      totpId: string;\n    };\n\nconst TOTP_FLOWS = [\"setup\", \"confirm\", \"verify\"] as const;\n\ntype TotpFlow = (typeof TOTP_FLOWS)[number];\n\ntype TotpDispatch =\n  | { flow: \"setup\"; params: Record<string, unknown> }\n  | { flow: \"confirm\"; code: string; totpId: string; verifier: string }\n  | { flow: \"verify\"; code: string; verifier: string };\n\nconst resolveTotpFlowFx = (\n  params: Record<string, unknown>,\n): FxType<TotpFlow, AuthError> => {\n  const flow = params.flow;\n  return typeof flow === \"string\" && TOTP_FLOWS.includes(flow as never)\n    ? Fx.succeed(flow as TotpFlow)\n    : Fx.fail(\n        new AuthError(\n          \"TOTP_MISSING_FLOW\",\n          \"Missing `flow` parameter. Expected one of: setup, confirm, verify\",\n        ),\n      );\n};\n\nconst requireTotpVerifierFx = (\n  verifier: string | undefined,\n): FxType<string, AuthError> =>\n  verifier != null\n    ? Fx.succeed(verifier)\n    : Fx.fail(new AuthError(\"TOTP_MISSING_VERIFIER\"));\n\nconst requireTotpCodeFx = (\n  params: Record<string, unknown>,\n): FxType<string, AuthError> =>\n  typeof params.code === \"string\"\n    ? Fx.succeed(params.code)\n    : Fx.fail(new AuthError(\"TOTP_MISSING_CODE\"));\n\nconst requireTotpIdFx = (\n  params: Record<string, unknown>,\n): FxType<string, AuthError> =>\n  typeof params.totpId === \"string\"\n    ? Fx.succeed(params.totpId)\n    : Fx.fail(new AuthError(\"TOTP_MISSING_ID\"));\n\nconst resolveTotpDispatchFx = (\n  params: Record<string, unknown>,\n  verifier: string | undefined,\n): FxType<TotpDispatch, AuthError> =>\n  resolveTotpFlowFx(params).pipe(\n    Fx.chain((flow) =>\n      Fx.match({ flow }).on(\"flow\", {\n        setup: () => Fx.succeed({ flow: \"setup\" as const, params }),\n        confirm: () =>\n          Fx.gen(function* () {\n            const resolvedVerifier = yield* requireTotpVerifierFx(verifier);\n            const code = yield* requireTotpCodeFx(params);\n            const totpId = yield* requireTotpIdFx(params);\n            return {\n              flow: \"confirm\" as const,\n              code,\n              totpId,\n              verifier: resolvedVerifier,\n            };\n          }),\n        verify: () =>\n          Fx.gen(function* () {\n            const resolvedVerifier = yield* requireTotpVerifierFx(verifier);\n            const code = yield* requireTotpCodeFx(params);\n            return {\n              flow: \"verify\" as const,\n              code,\n              verifier: resolvedVerifier,\n            };\n          }),\n      }),\n    ),\n  );\n\n/** @internal */\nexport const handleTotp = (\n  ctx: EnrichedActionCtx,\n  provider: TotpProviderConfig,\n  args: { params?: Record<string, any>; verifier?: string },\n): FxType<TotpResult, AuthError> => {\n  const params = (args.params ?? {}) as Record<string, unknown>;\n\n  return resolveTotpDispatchFx(params, args.verifier).pipe(\n    Fx.chain((dispatch) =>\n      Fx.match(dispatch).on(\"flow\", {\n        setup: ({ params }) =>\n          Fx.from({\n            ok: () => ctx.auth.getUserIdentity(),\n            err: (e) => new AuthError(\"INTERNAL_ERROR\", String(e)),\n          }).pipe(\n            Fx.chain((identity) =>\n              identity === null\n                ? Fx.fail(new AuthError(\"TOTP_AUTH_REQUIRED\"))\n                : Fx.succeed(userIdFromIdentitySubject(identity.subject)),\n            ),\n            Fx.chain((userId) =>\n              Fx.from({\n                ok: async () => {\n                  const secret = new Uint8Array(20);\n                  crypto.getRandomValues(secret);\n\n                  let accountName: string = params.accountName as string;\n                  if (!accountName) {\n                    const user = await queryUserById(ctx, userId);\n                    accountName = user?.email ?? \"user\";\n                  }\n\n                  const uri = createTOTPKeyURI(\n                    provider.options.issuer,\n                    accountName,\n                    secret,\n                    provider.options.period,\n                    provider.options.digits,\n                  );\n                  const base32Secret = encodeBase32LowerCaseNoPadding(secret);\n\n                  const verifier = await callVerifier(ctx);\n                  await callVerifierSignature(ctx, {\n                    verifier,\n                    signature: JSON.stringify({\n                      secret: Array.from(secret),\n                      userId,\n                      digits: provider.options.digits,\n                      period: provider.options.period,\n                    }),\n                  });\n\n                  const totpId = await mutateTotpInsert(ctx, {\n                    userId,\n                    secret: secret.buffer.slice(\n                      secret.byteOffset,\n                      secret.byteOffset + secret.byteLength,\n                    ),\n                    digits: provider.options.digits,\n                    period: provider.options.period,\n                    verified: false,\n                    name:\n                      typeof params.name === \"string\" ? params.name : undefined,\n                    createdAt: Date.now(),\n                  });\n\n                  return {\n                    kind: \"totpSetup\" as const,\n                    uri,\n                    secret: base32Secret,\n                    verifier,\n                    totpId,\n                  };\n                },\n                err: (e) =>\n                  new AuthError(\n                    \"INTERNAL_ERROR\",\n                    `TOTP setup failed: ${String(e)}`,\n                  ),\n              }),\n            ),\n          ),\n        confirm: ({ code, totpId, verifier }) =>\n          Fx.from({\n            ok: () => ctx.auth.getUserIdentity(),\n            err: (e) => new AuthError(\"INTERNAL_ERROR\", String(e)),\n          }).pipe(\n            Fx.chain((identity) =>\n              identity === null\n                ? Fx.fail(new AuthError(\"TOTP_AUTH_REQUIRED\"))\n                : Fx.succeed(userIdFromIdentitySubject(identity.subject)),\n            ),\n            Fx.chain((userId) =>\n              Fx.from({\n                ok: () => queryTotpById(ctx, totpId),\n                err: () => new AuthError(\"TOTP_NOT_FOUND\"),\n              })\n                .pipe(\n                  Fx.chain((doc) =>\n                    doc === null\n                      ? Fx.fail(new AuthError(\"TOTP_NOT_FOUND\"))\n                      : Fx.succeed(doc),\n                  ),\n                  Fx.chain((totpDoc) =>\n                    totpDoc.verified\n                      ? Fx.fail(new AuthError(\"TOTP_ALREADY_VERIFIED\"))\n                      : Fx.succeed(totpDoc),\n                  ),\n                )\n                .pipe(\n                  Fx.chain((totpDoc) =>\n                    verifyTOTPWithGracePeriod(\n                      new Uint8Array(totpDoc.secret),\n                      provider.options.period,\n                      provider.options.digits,\n                      code,\n                      30,\n                    )\n                      ? Fx.succeed(totpDoc)\n                      : Fx.fail(new AuthError(\"TOTP_INVALID_CODE\")),\n                  ),\n                )\n                .pipe(\n                  Fx.chain((_totpDoc) =>\n                    Fx.from({\n                      ok: async () => {\n                        await mutateTotpMarkVerified(ctx, totpId, Date.now());\n                        await mutateVerifierDelete(ctx, verifier);\n                        return callSignIn(ctx, {\n                          userId,\n                          generateTokens: true,\n                        });\n                      },\n                      err: (e) => new AuthError(\"INTERNAL_ERROR\", String(e)),\n                    }),\n                  ),\n                )\n                .pipe(\n                  Fx.map((signInResult) => ({\n                    kind: \"signedIn\" as const,\n                    signedIn: signInResult,\n                  })),\n                ),\n            ),\n          ),\n        verify: ({ code, verifier }) =>\n          Fx.from({\n            ok: () => queryVerifierById(ctx, verifier),\n            err: () => new AuthError(\"TOTP_INVALID_VERIFIER\"),\n          }).pipe(\n            Fx.chain((doc) =>\n              doc === null\n                ? Fx.fail(new AuthError(\"TOTP_INVALID_VERIFIER\"))\n                : Fx.succeed(doc),\n            ),\n            Fx.map((doc) => {\n              const data = JSON.parse(doc.signature!);\n              return { userId: data.userId as string, code, verifier };\n            }),\n            Fx.chain(({ userId, code, verifier }) =>\n              Fx.from({\n                ok: () => queryTotpVerifiedByUserId(ctx, userId),\n                err: () => new AuthError(\"TOTP_NO_ENROLLMENT\"),\n              }).pipe(\n                Fx.chain((totpDoc) =>\n                  totpDoc === null\n                    ? Fx.fail(new AuthError(\"TOTP_NO_ENROLLMENT\"))\n                    : Fx.succeed(totpDoc),\n                ),\n                Fx.chain((totpDoc) =>\n                  verifyTOTPWithGracePeriod(\n                    new Uint8Array(totpDoc.secret),\n                    totpDoc.period,\n                    totpDoc.digits,\n                    code,\n                    30,\n                  )\n                    ? Fx.succeed(totpDoc)\n                    : Fx.fail(new AuthError(\"TOTP_INVALID_CODE\")),\n                ),\n                Fx.chain((totpDoc) =>\n                  Fx.from({\n                    ok: async () => {\n                      await mutateTotpUpdateLastUsed(\n                        ctx,\n                        totpDoc._id,\n                        Date.now(),\n                      );\n                      await mutateVerifierDelete(ctx, verifier);\n                      return callSignIn(ctx, { userId, generateTokens: true });\n                    },\n                    err: (e) => new AuthError(\"INTERNAL_ERROR\", String(e)),\n                  }),\n                ),\n                Fx.map((signInResult) => ({\n                  kind: \"signedIn\" as const,\n                  signedIn: signInResult,\n                })),\n              ),\n            ),\n          ),\n      }),\n    ),\n  );\n};\n\n// ============================================================================\n// Helpers\n// ============================================================================\n"],"mappings":"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"}

package/dist/component/server/types.d.ts

@@ -1,6 +1,6 @@
 import _default from "../schema.js";
 import { OAuthProviderInstance } from "../providers/oauth.js";
-import { CredentialsUserConfig } from "../providers/credentials.js";
+import { CredentialsConfig } from "../providers/credentials.js";
 import { Password } from "../providers/password.js";
 import { Passkey } from "../providers/passkey.js";
 import { Totp } from "../providers/totp.js";
@@ -15,19 +15,59 @@ import { GenericId, Infer, Value } from "convex/values";
 import * as arctic0 from "arctic";
 
 //#region src/server/types.d.ts
-/** A value that is either `T` or a `PromiseLike<T>`. */
+/**
+ * A value that is either `T` or a `PromiseLike<T>`.
+ *
+ * @typeParam T - The underlying value type.
+ */
 type Awaitable<T> = T | PromiseLike<T>;
+/**
+ * A single role definition within the authorization config.
+ *
+ * Each role has an optional human-readable label and a list of grant strings
+ * that members with this role receive.
+ *
+ * @see {@link AuthAuthorizationConfig}
+ */
 type AuthRoleDefinition = {
-  id?: string;
-  label?: string;
+  /** Optional stable identifier (defaults to the record key). */id?: string; /** Human-readable label for admin UIs. */
+  label?: string; /** Permission grant strings conferred by this role. */
   grants: string[];
 };
+/**
+ * Authorization configuration mapping role IDs to {@link AuthRoleDefinition}s.
+ *
+ * Passed as `authorization.roles` in {@link ConvexAuthConfig}.
+ *
+ * @see {@link AuthRoleDefinition}
+ * @see {@link ConvexAuthConfig}
+ */
 type AuthAuthorizationConfig = {
   roles: Record<string, AuthRoleDefinition>;
 };
+/**
+ * Extracts the union of role ID strings from an authorization config.
+ *
+ * When `TAuthorization` is defined, this resolves to the literal key union
+ * of the `roles` record. Otherwise falls back to `string`.
+ *
+ * @typeParam TAuthorization - The authorization config type, or `undefined`.
+ *
+ * @see {@link AuthGrant}
+ */
 type AuthRoleId<TAuthorization extends AuthAuthorizationConfig | undefined> = TAuthorization extends {
   roles: infer TRoles extends Record<string, any>;
 } ? keyof TRoles & string : string;
+/**
+ * Extracts the union of grant strings from all roles in an authorization config.
+ *
+ * When `TAuthorization` is defined, this resolves to the literal union
+ * of all `grants` array elements across every role. Otherwise falls back to `string`.
+ *
+ * @typeParam TAuthorization - The authorization config type, or `undefined`.
+ *
+ * @see {@link AuthRoleId}
+ */
 type AuthGrant<TAuthorization extends AuthAuthorizationConfig | undefined> = TAuthorization extends {
   roles: infer TRoles extends Record<string, {
     grants: readonly any[];
@@ -59,12 +99,16 @@ type ConvexAuthConfig = {
      * How long can a user session last without the user reauthenticating.
      *
      * Defaults to 30 days.
+     *
+     * @defaultValue 2_592_000_000
      */
     totalDurationMs?: number;
     /**
      * How long can a user session last without the user being active.
      *
      * Defaults to 30 days.
+     *
+     * @defaultValue 2_592_000_000
      */
     inactiveDurationMs?: number;
   };
@@ -76,6 +120,8 @@ type ConvexAuthConfig = {
      * How long is the JWT valid for after it is signed initially.
      *
      * Defaults to 1 hour.
+     *
+     * @defaultValue 3_600_000
      */
     durationMs?: number;
   };
@@ -89,6 +135,8 @@ type ConvexAuthConfig = {
      *
      * Defaults to 10 times per hour (that is 10 failed attempts, and then
      * allow another one every 6 minutes).
+     *
+     * @defaultValue 10
      */
     maxFailedAttemptsPerHour?: number;
   };
@@ -268,10 +316,43 @@ interface SSOProviderConfig {
   id: string;
   type: "sso";
 }
+/**
+ * Account linking strategy for enterprise SSO sign-in.
+ *
+ * - `"verifiedEmail"` — link accounts when the IdP-provided email matches a verified email on an existing user.
+ * - `"none"` — never auto-link; always create a new account.
+ */
 type EnterpriseAccountLinkingPolicy = "verifiedEmail" | "none";
+/**
+ * Policy for reusing existing users during SCIM provisioning.
+ *
+ * - `"externalId"` — match by the SCIM `externalId` to reuse a previously provisioned user.
+ * - `"none"` — always create a new user for each SCIM provision request.
+ */
 type EnterpriseScimReuseUserPolicy = "externalId" | "none";
+/**
+ * Just-in-time provisioning mode for enterprise SSO.
+ *
+ * - `"off"` — no JIT provisioning; users must be pre-provisioned.
+ * - `"createUser"` — create a user record on first SSO sign-in.
+ * - `"createUserAndMembership"` — create a user and add them to the enterprise group on first SSO sign-in.
+ */
 type EnterpriseJitProvisioningMode = "off" | "createUser" | "createUserAndMembership";
+/**
+ * Deprovisioning strategy when a SCIM user is deleted.
+ *
+ * - `"soft"` — mark the user as inactive but preserve the record.
+ * - `"hard"` — permanently delete the user and associated data.
+ */
 type EnterpriseDeprovisionMode = "soft" | "hard";
+/**
+ * Effective enterprise policy document stored for an SSO/SCIM tenant.
+ *
+ * Controls account linking, JIT provisioning, SCIM reuse behavior,
+ * deprovisioning, and any app-defined extension metadata.
+ *
+ * @see {@link EnterprisePolicyPatch}
+ */
 interface EnterprisePolicy {
   version: 1;
   identity: {
@@ -294,6 +375,12 @@ interface EnterprisePolicy {
   };
   extend?: Record<string, unknown>;
 }
+/**
+ * Partial update payload for {@link EnterprisePolicy}.
+ *
+ * Use this when patching only selected enterprise policy sections without
+ * replacing the entire stored policy document.
+ */
 interface EnterprisePolicyPatch {
   identity?: {
     accountLinking?: {
@@ -317,6 +404,8 @@ interface EnterprisePolicyPatch {
 }
 /**
  * Email provider config for magic link / OTP sign-in.
+ *
+ * @typeParam DataModel - The Convex data model for typed action contexts.
  */
 interface EmailConfig<DataModel extends GenericDataModel = GenericDataModel> {
   /** Provider identifier (e.g. `"email"`, `"resend"`). */
@@ -327,7 +416,11 @@ interface EmailConfig<DataModel extends GenericDataModel = GenericDataModel> {
   name?: string;
   /** Sender address (e.g. `"My App <noreply@example.com>"`). */
   from?: string;
-  /** Token expiration in seconds. Defaults to 86 400 (24 hours). */
+  /**
+   * Token expiration in seconds. Defaults to 86 400 (24 hours).
+   *
+   * @defaultValue 86400
+   */
   maxAge?: number;
   /**
    * Send the verification token to the user.
@@ -365,18 +458,23 @@ interface EmailConfig<DataModel extends GenericDataModel = GenericDataModel> {
   /**
    * The values passed to the `signIn` function.
    */
-
   params: Record<string, Value | undefined>, account: GenericDoc<DataModel, "Account">) => Promise<void>;
   /** Raw user options before merging with defaults. */
   options: EmailUserConfig<DataModel>;
 }
 /**
- * Configurable options for an email provider config.
+ * User-facing configuration shape accepted by the email provider.
+ *
+ * Equivalent to `Partial<EmailConfig>` without internal runtime-only fields.
+ *
+ * @typeParam DataModel - The Convex data model.
  */
 type EmailUserConfig<DataModel extends GenericDataModel = GenericDataModel> = Omit<Partial<EmailConfig<DataModel>>, "options" | "type">;
 /**
  * Same as email provider config, but verifies
  * phone number instead of the email address.
+ *
+ * @typeParam DataModel - The Convex data model for typed action contexts.
  */
 interface PhoneConfig<DataModel extends GenericDataModel = GenericDataModel> {
   id: string;
@@ -425,18 +523,21 @@ interface PhoneConfig<DataModel extends GenericDataModel = GenericDataModel> {
   /**
    * The values passed to the `signIn` function.
    */
-
   params: Record<string, Value | undefined>, account: GenericDoc<DataModel, "Account">) => Promise<void>;
   options: PhoneUserConfig<DataModel>;
 }
 /**
- * Configurable options for a phone provider config.
+ * User-facing configuration shape accepted by the phone provider.
+ *
+ * Equivalent to `Partial<PhoneConfig>` without internal runtime-only fields.
+ *
+ * @typeParam DataModel - The Convex data model.
  */
 type PhoneUserConfig<DataModel extends GenericDataModel = GenericDataModel> = Omit<Partial<PhoneConfig<DataModel>>, "options" | "type">;
 /**
  * Credentials provider config used by Convex Auth.
  */
-type ConvexCredentialsConfig = CredentialsUserConfig<any> & {
+type ConvexCredentialsConfig = CredentialsConfig<any> & {
   type: "credentials";
   id: string;
 };
@@ -449,12 +550,37 @@ interface PasskeyProviderConfig {
   options: {
     /** Relying Party display name. Defaults to SITE_URL hostname. */rpName?: string; /** Relying Party ID (hostname). Defaults to SITE_URL hostname. */
     rpId?: string; /** Allowed origins for credential verification. Defaults to SITE_URL. */
-    origin?: string | string[]; /** Attestation conveyance preference. Defaults to "none". */
-    attestation?: "none" | "direct"; /** User verification requirement. Defaults to "required". */
-    userVerification?: "required" | "preferred" | "discouraged"; /** Resident key (discoverable credential) preference. Defaults to "preferred". */
+    origin?: string | string[];
+    /**
+     * Attestation conveyance preference. Defaults to "none".
+     *
+     * @defaultValue "none"
+     */
+    attestation?: "none" | "direct";
+    /**
+     * User verification requirement. Defaults to "required".
+     *
+     * @defaultValue "required"
+     */
+    userVerification?: "required" | "preferred" | "discouraged";
+    /**
+     * Resident key (discoverable credential) preference. Defaults to "preferred".
+     *
+     * @defaultValue "preferred"
+     */
     residentKey?: "required" | "preferred" | "discouraged"; /** Restrict to platform or cross-platform authenticators. */
-    authenticatorAttachment?: "platform" | "cross-platform"; /** Supported COSE algorithms. Defaults to [-7 (ES256), -257 (RS256)]. */
-    algorithms?: number[]; /** Challenge expiration in ms. Defaults to 300_000 (5 minutes). */
+    authenticatorAttachment?: "platform" | "cross-platform";
+    /**
+     * Supported COSE algorithms. Defaults to [-7 (ES256), -257 (RS256)].
+     *
+     * @defaultValue [-7, -257]
+     */
+    algorithms?: number[];
+    /**
+     * Challenge expiration in ms. Defaults to 300_000 (5 minutes).
+     *
+     * @defaultValue 300_000
+     */
     challengeExpirationMs?: number;
   };
 }
@@ -465,8 +591,18 @@ interface TotpProviderConfig {
   id: string;
   type: "totp";
   options: {
-    /** Issuer name shown in authenticator apps (e.g. "My App"). */issuer: string; /** Number of digits in each code (default: 6). */
-    digits: number; /** Time period in seconds for code rotation (default: 30). */
+    /** Issuer name shown in authenticator apps (e.g. "My App"). */issuer: string;
+    /**
+     * Number of digits in each code (default: 6).
+     *
+     * @defaultValue 6
+     */
+    digits: number;
+    /**
+     * Time period in seconds for code rotation (default: 30).
+     *
+     * @defaultValue 30
+     */
     period: number;
   };
 }
@@ -529,9 +665,50 @@ type AuthProviderSignInResult = {
   userId: GenericId<"User">;
   sessionId: GenericId<"Session">;
 } | null;
-/** Server-side auth helpers available on enriched action contexts. */
+/** Arguments for `auth.member.resolve()`. */
+type AuthMemberResolveArgs = {
+  userId: GenericId<"User">;
+  groupId: GenericId<"Group">;
+  ancestry?: boolean;
+  roleIds?: string[];
+  grants?: string[];
+  maxDepth?: number;
+};
+/** Result of `auth.member.resolve()` — membership check with role and grant details. */
+type AuthMemberResolveResult = {
+  ok: boolean;
+  membership: GenericDoc<GenericDataModel, "GroupMember"> | null;
+  matchedGroupId: GenericId<"Group"> | null;
+  roleIds: string[];
+  grants: string[];
+  missingGrants: string[];
+  depth: number | null;
+  isDirect: boolean;
+  isInherited: boolean;
+  traversedGroupIds: GenericId<"Group">[];
+  code?: "INVALID_ROLE_IDS";
+  invalidRoleIds?: string[];
+};
+/**
+ * Server-side auth helper methods injected into `ctx.auth` within provider actions.
+ *
+ * Provides programmatic access to account management, session lifecycle,
+ * membership resolution, and provider sign-in from within Convex actions
+ * that use {@link GenericActionCtxWithAuthConfig}.
+ *
+ * @see {@link GenericActionCtxWithAuthConfig}
+ *
+ * @example
+ * ```ts
+ * // Inside a credentials provider's authorize callback:
+ * const { account, user } = await ctx.auth.account.get(ctx, {
+ *   provider: "password",
+ *   account: { id: email },
+ * });
+ * ```
+ */
 type AuthServerHelpers = {
-  account: {
+  /** Account management: create, retrieve, and update provider-linked accounts. */account: {
     create: (ctx: GenericActionCtx<any>, args: AuthCreateAccountArgs) => Promise<{
       ok: true;
       account: GenericDoc<GenericDataModel, "Account">;
@@ -556,23 +733,8 @@ type AuthServerHelpers = {
       except: GenericId<"Session">[];
     }>;
   };
-  access: {
-    check: (ctx: GenericActionCtx<any>, args: {
-      userId: GenericId<"User">;
-      groupId: GenericId<"Group">;
-      grants: string[];
-      maxDepth?: number;
-    }) => Promise<{
-      ok: boolean;
-      grants: string[];
-      missingGrants: string[];
-      roleIds: string[];
-      matchedGroupId: GenericId<"Group"> | null;
-      membership: GenericDoc<GenericDataModel, "GroupMember"> | null;
-      isDirect: boolean;
-      isInherited: boolean;
-      depth: number | null;
-    }>;
+  member: {
+    resolve: (ctx: GenericActionCtx<any>, args: AuthMemberResolveArgs) => Promise<AuthMemberResolveResult>;
   };
   provider: {
     signIn: (ctx: GenericActionCtx<any>, provider: AuthProviderConfig, args: AuthProviderSignInArgs) => Promise<AuthProviderSignInResult>;
@@ -581,6 +743,8 @@ type AuthServerHelpers = {
 /**
  * Your `ActionCtx` enriched with `ctx.auth.config` field with
  * the config passed to `createAuth`.
+ *
+ * @typeParam DataModel - The Convex data model.
  */
 type GenericActionCtxWithAuthConfig<DataModel extends GenericDataModel> = GenericActionCtx<DataModel> & {
   auth: GenericActionCtx<DataModel>["auth"] & {
@@ -600,18 +764,38 @@ type ConvexAuthMaterializedConfig = {
  * Materialized OAuth provider config (Arctic-based).
  *
  * Carries the Arctic provider instance along with scopes and profile config.
- * Produced by materializing an `OAuthProviderInstance` during `configDefaults`.
+  * Produced by materializing an `OAuthProviderInstance` during `configDefaults`.
  */
 interface OAuthMaterializedConfig {
+  /**
+   * Provider identifier (e.g. `"google"`, `"github"`).
+   * @readonly
+   */
   readonly id: string;
+  /**
+   * Discriminant for provider type routing.
+   * @readonly
+   */
   readonly type: "oauth";
-  /** The Arctic provider instance. */
+  /**
+   * The Arctic provider instance.
+   * @readonly
+   */
   readonly provider: any;
-  /** OAuth scopes to request. */
+  /**
+   * OAuth scopes to request.
+   * @readonly
+   */
   readonly scopes: string[];
-  /** User-provided profile extraction callback. */
+  /**
+   * User-provided profile extraction callback.
+   * @readonly
+   */
   readonly profile?: (tokens: arctic0.OAuth2Tokens) => Promise<OAuthProfile>;
-  /** Account-linking policy for OAuth identities. Defaults to verified email linking. */
+  /**
+   * Account-linking policy for OAuth identities. Defaults to verified email linking.
+   * @readonly
+   */
   readonly accountLinking?: "verifiedEmail" | "none";
 }
 /**