@base44-preview/sdk 0.8.52-pr.297.7590c31 → 0.8.52-pr.298.d08e0ba

package/README.md

@@ -151,3 +151,5 @@ npm run create-docs
 cd docs
 mintlify dev
 ```
+
+See [experimental app-user MFA](MFA.md) for challenge handling and managed continuation.

package/dist/index.d.ts

@@ -18,3 +18,4 @@ export { Actor, type Conn } from "./actor.js";
 export type { ConnectorsModule, UserConnectorsModule, ConnectorApiRequest, ConnectorApiResponse, ConnectorApiResponsePhase, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";
 export type { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions, } from "./utils/auth-utils.types.js";
+export type { MfaChallenge, MfaModule, MfaProof, LoginResult, MfaEnrollmentResult } from "./modules/mfa.js";

package/dist/modules/ai-gateway.types.d.ts

@@ -51,13 +51,15 @@ export interface AiGatewayModuleConfig {
  * against the provider directly, no separate account, API key, or billing
  * setup with the underlying model provider required.
  *
- * By default, `connection()` uses the OpenAI-compatible provider, which serves
- * chat and images. Pass `{ provider: "typesafe" }` for structured evaluations.
+ * By default, `connection()` uses the OpenAI-compatible provider. Pass
+ * `{ provider: "typesafe" }` to connect to TypeSafe for structured evaluations
+ * with `@ai-sdk/typesafe-ai`.
  *
  * Call `connection()` from a backend function rather than the browser. This
  * keeps your instructions, tools, and business logic server-side, and lets
- * you enforce your own auth, rate, and spend limits around the call. Which
- * token it returns depends on the authentication mode, described below.
+ * you enforce your own auth, rate, and spend limits around the call. The
+ * `token` it returns is the caller's regular session token, the same one
+ * used for every other SDK call.
  *
  * ## OpenAI-compatible models
  *
@@ -74,23 +76,13 @@ export interface AiGatewayModuleConfig {
  * `'gemini_3_1_flash_image'` or `'gpt_image_2'`. For request options, the
  * full model list, and limits, see [Generate images with the AI Gateway](/developers/references/sdk/getting-started/ai-gateway-images).
  *
- * ## Structured evaluations
- *
- * The `typesafe` provider runs the `jev` evaluation model through
- * `@ai-sdk/typesafe-ai` and `experimental_evaluate` from the `ai` package,
- * version 7.0.105 or later. Pass `evaluationModel("jev")`; the gateway rejects
- * other model IDs, such as `"jev-latest"`. Give it some app state and a set of
- * questions, each a `choice`, `score`, or `boolean`. Choice and score answers
- * come back with `probabilities` per option; boolean answers with a single
- * `probability` of `true`. Use it to classify, score, or route records, then
- * apply your own thresholds and actions in code.
- *
  * ## Authentication Modes
  *
- * The mode determines which token `connection()` returns:
+ * There's no permission difference between modes. Both just determine which
+ * token `connection()` returns:
  *
- * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the service-role token. Use this from backend functions, including scheduled automations with no signed-in user. Every call spends the app's credits, so check the caller with `base44.auth.me()` first when a user triggers the function.
- * - **User authentication** (`base44.aiGateway`): Returns the signed-in app user's token. When an app restricts Core integrations, which is the default for new apps, public apps reject gateway calls made with a user token unless the AI Gateway is allowed.
+ * - **User authentication** (`base44.aiGateway`): Returns the signed-in app user's token.
+ * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the service-role token instead, for calling the gateway when there's no signed-in user, such as from a scheduled automation.
  *
  * ## Billing and limits
  *
@@ -119,7 +111,7 @@ export interface AiGatewayModule {
      *
      * // Runs inside a backend function
      * const base44 = createClientFromRequest(request);
-     * const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
+     * const { baseURL, token, headers } = base44.aiGateway.connection();
      * const openai = new OpenAI({ baseURL, apiKey: token, defaultHeaders: headers });
      *
      * const response = await openai.chat.completions.create({
@@ -141,7 +133,7 @@ export interface AiGatewayModule {
      * // Runs inside a backend function, reviewing a return request
      * const base44 = createClientFromRequest(request);
      * const returnRequest = await base44.entities.ReturnRequest.get(returnId);
-     * const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
+     * const { baseURL, token, headers } = base44.aiGateway.connection();
      * // Point any OpenAI-compatible client at `baseURL` with `apiKey: token` and `headers`.
      * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token, headers });
      *
@@ -182,7 +174,7 @@ export interface AiGatewayModule {
      *
      * // Runs inside a backend function
      * const base44 = createClientFromRequest(request);
-     * const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
+     * const { baseURL, token, headers } = base44.aiGateway.connection();
      * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token, headers });
      *
      * const { image } = await generateImage({
@@ -195,45 +187,6 @@ export interface AiGatewayModule {
      * const file = new File([image.uint8Array], "lighthouse.png", { type: image.mediaType });
      * const { file_url } = await base44.integrations.Core.UploadFile({ file });
      * ```
-     *
-     * @example
-     * ```typescript
-     * // Route a support ticket with a structured evaluation
-     * import { createClientFromRequest } from "@base44/sdk";
-     * import { experimental_evaluate as evaluate } from "ai";
-     * import { createTypeSafeAi } from "@ai-sdk/typesafe-ai";
-     *
-     * // Runs inside a backend function
-     * const base44 = createClientFromRequest(request);
-     * const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection({ provider: "typesafe" });
-     * const typesafe = createTypeSafeAi({ baseURL, apiKey: token, headers });
-     *
-     * const { answers, providerMetadata } = await evaluate({
-     *   model: typesafe.evaluationModel("jev"),
-     *   maxRetries: 0, // Avoid automatic replays of billed requests
-     *   state: { message: "Please refund today's duplicate charge." },
-     *   questions: {
-     *     department: {
-     *       type: "choice",
-     *       instructions: "Which team should handle this?",
-     *       criteria: { billing: "Payments and refunds", support: "Other requests" },
-     *     },
-     *     urgency: {
-     *       type: "score",
-     *       instructions: "How urgent is this?",
-     *       criteria: ["No deadline", "Requested today", "Immediate emergency"],
-     *     },
-     *     refund: { type: "boolean", instructions: "Is a refund explicitly requested?" },
-     *   },
-     * });
-     *
-     * // answers.department → { type: "choice", choice: "billing", probabilities: { billing: 0.97, support: 0.03 } }
-     * // answers.urgency    → { type: "score", score: 1.2, probabilities: { 0: 0.1, 1: 0.6, 2: 0.3 } }
-     * // answers.refund     → { type: "boolean", probability: 0.99 }
-     * // Choice and score confidence is in providerMetadata.typesafe.confidence
-     * // Pick your own thresholds and act on them in code
-     * const autoRefund = answers.department.choice === "billing" && answers.refund.probability > 0.9;
-     * ```
      */
     connection(options?: AiGatewayConnectionOptions): AiGatewayConnection;
 }

package/dist/modules/auth.js

@@ -1,3 +1,4 @@
+import { createMfaModule, prepareMfaPkce } from "./mfa.js";
 import { resetAnalyticsSessionContext } from "./analytics.js";
 function isInsideIframe() {
     if (typeof window === "undefined")
@@ -19,9 +20,9 @@ function loginViaPopup(url, redirectUrl, expectedOrigin) {
     const height = 600;
     const left = Math.round(window.screenX + (window.outerWidth - width) / 2);
     const top = Math.round(window.screenY + (window.outerHeight - height) / 2);
-    const popup = window.open(url, "base44_auth", `width=${width},height=${height},left=${left},top=${top},resizable=yes,scrollbars=yes`);
+    const popup = window.open("about:blank", "base44_auth", `width=${width},height=${height},left=${left},top=${top},resizable=yes,scrollbars=yes`);
     if (!popup) {
-        return;
+        return Promise.resolve();
     }
     const cleanup = () => {
         window.removeEventListener("message", onMessage);
@@ -52,6 +53,7 @@ function loginViaPopup(url, redirectUrl, expectedOrigin) {
             cleanup();
     }, 500);
     window.addEventListener("message", onMessage);
+    return url.then(value => { popup.location.href = value; }, error => { cleanup(); throw error; });
 }
 /**
  * Creates the auth module for the Base44 SDK.
@@ -82,7 +84,8 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
     // to the identity transitions below (`setToken`, `logout`) instead of to the
     // header a caller may have set on the instance directly.
     let hasAccessToken = Boolean(options.token);
-    return {
+    const module = {
+        mfa: createMfaModule(axios, appId, token => module.setToken(token)),
         hasToken() {
             return hasAccessToken;
         },
@@ -119,9 +122,10 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             window.location.href = loginUrl;
         },
         // Redirects the user to a provider's login page
-        loginWithProvider(provider, fromUrl = "/") {
+        async loginWithProvider(provider, fromUrl = "/") {
             // Build the full redirect URL
             const redirectUrl = new URL(fromUrl, window.location.origin).toString();
+            const mfaPkce = provider === "sso" ? Promise.resolve("") : prepareMfaPkce(appId).then(value => `&app_mfa_code_challenge=${value}`);
             const queryParams = `app_id=${appId}&from_url=${encodeURIComponent(redirectUrl)}`;
             // SSO uses a different URL structure with appId in the path
             let authPath;
@@ -137,11 +141,11 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             // When running inside an iframe, use a popup to avoid OAuth providers
             // blocking iframe navigation.
             if (isInsideIframe()) {
-                const popupLoginUrl = `${loginUrl}&popup_origin=${encodeURIComponent(window.location.origin)}`;
+                const popupLoginUrl = mfaPkce.then(pkce => `${loginUrl}${pkce}&popup_origin=${encodeURIComponent(window.location.origin)}`);
                 return loginViaPopup(popupLoginUrl, redirectUrl, window.location.origin);
             }
             // Default: full-page redirect
-            window.location.href = loginUrl;
+            window.location.href = loginUrl + await mfaPkce;
         },
         // Logout the current user
         logout(redirectUrl) {
@@ -207,6 +211,8 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                     password,
                     ...(turnstileToken && { turnstile_token: turnstileToken }),
                 });
+                if (response.mfa_required)
+                    return response;
                 const { access_token, user } = response;
                 if (access_token) {
                     this.setToken(access_token);
@@ -278,4 +284,5 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             });
         },
     };
+    return module;
 }

package/dist/modules/auth.types.d.ts

@@ -1,3 +1,4 @@
+import type { LoginResult, MfaModule } from "./mfa.js";
 /**
  * An authenticated user.
  */
@@ -37,6 +38,7 @@ export interface User {
  * Response from login endpoints containing user information and access token.
  */
 export interface LoginResponse {
+    mfa_required?: false;
     /** JWT access token for authentication. */
     access_token: string;
     /** User information. */
@@ -117,6 +119,8 @@ export interface AuthModuleOptions {
  * The auth module is only available in user authentication mode (`base44.auth`).
  */
 export interface AuthModule {
+    /** Multi-factor enrollment and login for this app. */
+    mfa: MfaModule;
     /**
      * Gets the current authenticated user's information.
      *
@@ -219,7 +223,7 @@ export interface AuthModule {
      * ```
      *
      */
-    loginWithProvider(provider: string, fromUrl?: string): void;
+    loginWithProvider(provider: string, fromUrl?: string): Promise<void>;
     /**
      * Logs out the current user.
      *
@@ -302,7 +306,7 @@ export interface AuthModule {
      * );
      * ```
      */
-    loginViaEmailPassword(email: string, password: string, turnstileToken?: string): Promise<LoginResponse>;
+    loginViaEmailPassword(email: string, password: string, turnstileToken?: string): Promise<LoginResult>;
     /**
      * Checks if the current user is authenticated.
      *
@@ -427,7 +431,7 @@ export interface AuthModule {
      * );
      * ```
      */
-    verifyOtp(params: VerifyOtpParams): Promise<any>;
+    verifyOtp(params: VerifyOtpParams): Promise<LoginResult>;
     /**
      * Resends an OTP code to the user's email address.
      *

package/dist/modules/mfa.d.ts

@@ -0,0 +1,52 @@
+import type { AxiosInstance } from 'axios';
+import type { LoginResponse } from './auth.types.js';
+/** A restricted, short-lived login outcome. It is never an access token. */
+export interface MfaChallenge {
+    mfa_required: true;
+    next_step: 'enroll' | 'verify';
+    mfa_methods: ('totp' | 'sms')[];
+    mfa_session_token: string;
+    expires_in_seconds: number;
+    phone_hint?: string;
+    access_token?: never;
+    user?: never;
+}
+export type LoginResult = LoginResponse | MfaChallenge;
+export interface MfaEnrollmentResult extends LoginResponse {
+    backup_codes?: string[];
+}
+export interface MfaProof {
+    code: string;
+    method: 'totp' | 'sms';
+    remember_device?: boolean;
+}
+/** App-scoped MFA. Pass the challenge credential explicitly; do not set it as the SDK token. */
+export interface MfaModule {
+    getStatus(): Promise<{
+        mfa_enabled: boolean;
+        methods: ('totp' | 'sms')[];
+        backup_codes_remaining: number;
+        policy: 'off' | 'required';
+    }>;
+    /** Requires an app admin session; resets a user in this app only. */
+    resetForUser(appUserId: string): Promise<{
+        success: true;
+    }>;
+    /** Open managed settings with fresh primary authentication and factor verification. */
+    openSecurity(returnTo?: string): void;
+    setupTotp(challenge: MfaChallenge): Promise<{
+        secret: string;
+        secret_formatted: string;
+        qr_code: string;
+    }>;
+    sendSms(challenge: MfaChallenge, phoneNumber: string): Promise<unknown>;
+    enrollTotp(challenge: MfaChallenge, code: string, rememberDevice?: boolean): Promise<MfaEnrollmentResult>;
+    enrollSms(challenge: MfaChallenge, code: string, rememberDevice?: boolean): Promise<MfaEnrollmentResult>;
+    verify(challenge: MfaChallenge, proof: MfaProof): Promise<LoginResponse>;
+    verifyRecoveryCode(challenge: MfaChallenge, code: string, rememberDevice?: boolean): Promise<LoginResponse>;
+    resendSms(challenge: MfaChallenge): Promise<unknown>;
+    /** Open Base44's managed MFA flow on this app's origin. */
+    continueLogin(challenge: MfaChallenge, returnTo?: string): Promise<void>;
+}
+export declare function prepareMfaPkce(appId: string): Promise<string>;
+export declare function createMfaModule(axios: AxiosInstance, appId: string, setToken: (token: string) => void): MfaModule;

package/dist/modules/mfa.js

@@ -0,0 +1,43 @@
+export async function prepareMfaPkce(appId) {
+    const encode = (value) => btoa(String.fromCharCode(...value)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    const verifier = encode(crypto.getRandomValues(new Uint8Array(32)));
+    sessionStorage.setItem(`app-mfa-pkce:${appId}`, verifier);
+    return encode(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))));
+}
+export function createMfaModule(axios, appId, setToken) {
+    const post = async (challenge, path, payload = {}) => {
+        const response = await axios.post(`/apps/${appId}/auth/mfa${path}`, payload, {
+            headers: { Authorization: `Bearer ${challenge.mfa_session_token}` }, withCredentials: true,
+        });
+        const token = response.access_token;
+        if (token)
+            setToken(token);
+        return response;
+    };
+    return {
+        getStatus: () => axios.get(`/apps/${appId}/auth/mfa/status`),
+        resetForUser: appUserId => axios.post(`/apps/${appId}/auth/mfa/reset`, { app_user_id: appUserId }),
+        openSecurity(returnTo = '/') {
+            const target = new URL(returnTo, window.location.origin);
+            if (target.origin !== window.location.origin)
+                throw new Error('MFA must return to this app.');
+            window.location.href = `/auth/mfa?${new URLSearchParams({ security: '1', from_url: target.pathname + target.search + target.hash })}`;
+        },
+        setupTotp: challenge => post(challenge, '/totp/setup'),
+        sendSms: (challenge, phoneNumber) => post(challenge, '/sms/send-code', { phone_number: phoneNumber }),
+        enrollTotp: (challenge, code, rememberDevice = false) => post(challenge, '/totp/verify', { code, remember_device: rememberDevice }),
+        enrollSms: (challenge, code, rememberDevice = false) => post(challenge, '/sms/verify', { code, remember_device: rememberDevice }),
+        verify: (challenge, proof) => post(challenge, '/verify', proof),
+        verifyRecoveryCode: (challenge, code, rememberDevice = false) => post(challenge, '/verify-backup', { backup_code: code, remember_device: rememberDevice }),
+        resendSms: challenge => post(challenge, '/resend'),
+        async continueLogin(challenge, returnTo = '/') {
+            const target = new URL(returnTo, window.location.origin);
+            if (target.origin !== window.location.origin)
+                throw new Error('MFA must return to this app.');
+            const codeChallenge = await prepareMfaPkce(appId);
+            const handoff = await post(challenge, '/handoff', { code_challenge: codeChallenge });
+            const query = new URLSearchParams({ app_id: appId, mfa_code: handoff.code, from_url: target.pathname + target.search + target.hash });
+            window.location.href = `/auth/mfa?${query}`;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.52-pr.297.7590c31",
+  "version": "0.8.52-pr.298.d08e0ba",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",