@mitralab.io/platform-sdk 1.1.2 → 1.2.0-beta.1

package/dist/index.cjs

@@ -434,16 +434,37 @@ async function resolveApiKeySession(publicClient, appId, apiKey) {
   );
 }
 
-// src/modules/google-auth.ts
+// src/modules/auth-page-flow.ts
 var import_sdk_core2 = require("@mitralab.io/sdk-core");
 var RESULT_TYPE = "mitra-oauth-result";
-var PROVIDER_LABELS = {
-  google: "Google",
-  microsoft: "Microsoft"
+var FIVE_MINUTES_MS = 5 * 60 * 1e3;
+var TEN_MINUTES_MS = 10 * 60 * 1e3;
+var PROVIDERS = {
+  google: {
+    label: "Google",
+    exchangePath: "/api/v1/auth/google",
+    sendsRedirectUri: true,
+    redirectStorage: "sessionStorage",
+    popupTimeoutMs: FIVE_MINUTES_MS
+  },
+  microsoft: {
+    label: "Microsoft",
+    exchangePath: "/api/v1/auth/microsoft",
+    sendsRedirectUri: true,
+    redirectStorage: "sessionStorage",
+    popupTimeoutMs: FIVE_MINUTES_MS
+  },
+  email: {
+    label: "Email",
+    exchangePath: "/api/v1/auth/magic-link/exchange",
+    sendsRedirectUri: false,
+    redirectStorage: "localStorage",
+    pendingRequestTtlMs: TEN_MINUTES_MS,
+    popupTimeoutMs: TEN_MINUTES_MS
+  }
 };
 var POPUP_WIDTH = 480;
 var POPUP_HEIGHT = 600;
-var POPUP_TIMEOUT_MS = 5 * 60 * 1e3;
 var POPUP_CLOSED_POLL_MS = 500;
 function expectAuthTokenResponse(value) {
   const response = (0, import_sdk_core2.expectObject)(
@@ -464,12 +485,13 @@ function expectAuthTokenResponse(value) {
     tokenType: response.tokenType
   };
 }
-var GoogleAuthFlow = class {
+var AuthPageFlow = class {
   appId;
   apiUrl;
   configuredAuthPageUrl;
   client;
   provider;
+  profile;
   providerLabel;
   redirectStorageKey;
   popupPromise = null;
@@ -479,7 +501,8 @@ var GoogleAuthFlow = class {
     this.configuredAuthPageUrl = config.authPageUrl;
     this.client = config.client;
     this.provider = config.provider ?? "google";
-    this.providerLabel = PROVIDER_LABELS[this.provider];
+    this.profile = PROVIDERS[this.provider];
+    this.providerLabel = this.profile.label;
     this.redirectStorageKey = `mitra_${this.provider}_redirect_${config.appId}`;
   }
   signIn(options = {}) {
@@ -496,6 +519,19 @@ var GoogleAuthFlow = class {
     });
     return this.popupPromise;
   }
+  /**
+   * Finishes a redirect this provider started, or returns `null` when the URL
+   * carries no result or carries one that belongs to another provider's flow.
+   *
+   * The state generated at the start of every flow is prefixed with the provider
+   * name, and the auth page echoes it verbatim, so a fragment identifies its own
+   * flow. An application that offers several methods can call every completion
+   * at startup, in any order, even while other methods have requests pending.
+   *
+   * A fragment of this flow is always consumed, including when it cannot be
+   * completed, so a failure is reported once instead of on every reload. A
+   * fragment of another flow is left exactly as it was found.
+   */
   async completeRedirect() {
     const browserWindow = this.requireBrowser();
     const params = new URLSearchParams(browserWindow.location.hash.replace(/^#/, ""));
@@ -504,17 +540,36 @@ var GoogleAuthFlow = class {
     const error = params.get("errorMitra");
     if (code === null && state === null && error === null) return null;
     const context = this.readRedirectContext(browserWindow);
-    if (!state?.trim()) {
-      throw new Error(`${this.providerLabel} sign-in redirect is missing state.`);
+    const hasState = state !== null && state.trim() !== "";
+    if (hasState && !this.ownsState(state)) return null;
+    if (!hasState && !context) return null;
+    if (!hasState) {
+      throw this.discardOwnRedirect(
+        browserWindow,
+        `${this.providerLabel} sign-in redirect is missing state.`
+      );
+    }
+    if (context && this.hasExpired(context)) {
+      this.clearRedirectContext(browserWindow);
+      throw this.discardOwnRedirect(
+        browserWindow,
+        `${this.providerLabel} sign-in request expired before it was completed.`
+      );
     }
     if (context?.state !== state) {
-      throw new Error(`Invalid ${this.providerLabel} sign-in state (possible CSRF).`);
+      throw this.discardOwnRedirect(
+        browserWindow,
+        `Invalid ${this.providerLabel} sign-in state (possible CSRF).`
+      );
     }
     const expectedRedirectUri = this.getRedirectUri(
       resolveAuthPageUrl(this.apiUrl, this.configuredAuthPageUrl, browserWindow)
     );
     if (context.redirectUri !== expectedRedirectUri) {
-      throw new Error(`${this.providerLabel} sign-in redirect context is invalid.`);
+      throw this.discardOwnRedirect(
+        browserWindow,
+        `${this.providerLabel} sign-in redirect context is invalid.`
+      );
     }
     this.cleanRedirectFragment(browserWindow);
     this.clearRedirectContext(browserWindow);
@@ -533,8 +588,13 @@ var GoogleAuthFlow = class {
       this.configuredAuthPageUrl,
       browserWindow
     );
+    const completedInAnotherTab = this.profile.pendingRequestTtlMs !== void 0;
+    if (completedInAnotherTab) {
+      this.writeRedirectContext(browserWindow, this.newRedirectContext(state, authPageUrl));
+    }
     const popup = this.openPopup(browserWindow, this.buildStartUrl(browserWindow, authPageUrl, state));
     const result = await this.waitForPopupResult(browserWindow, popup, authPageUrl.origin, state);
+    if (completedInAnotherTab) this.clearRedirectContext(browserWindow);
     if (result.code) return this.exchangeCode(result.code, this.getRedirectUri(authPageUrl));
     return expectAuthTokenResponse(result.token);
   }
@@ -545,20 +605,20 @@ var GoogleAuthFlow = class {
       this.configuredAuthPageUrl,
       browserWindow
     );
-    const context = {
-      state,
-      redirectUri: this.getRedirectUri(authPageUrl)
-    };
-    this.persistRedirectContext(browserWindow, context);
+    if (!this.writeRedirectContext(browserWindow, this.newRedirectContext(state, authPageUrl))) {
+      throw new Error(
+        `${this.providerLabel} sign-in redirect requires ${this.profile.redirectStorage}.`
+      );
+    }
     const startUrl = this.buildStartUrl(browserWindow, authPageUrl, state);
     browserWindow.location.assign(startUrl.toString());
     return new Promise(() => void 0);
   }
   async exchangeCode(code, redirectUri) {
-    const response = await this.client.post(`/api/v1/auth/${this.provider}`, {
+    const response = await this.client.post(this.profile.exchangePath, {
       appId: this.appId,
       code,
-      redirectUri
+      ...this.profile.sendsRedirectUri ? { redirectUri } : {}
     });
     return expectAuthTokenResponse(response);
   }
@@ -575,13 +635,41 @@ var GoogleAuthFlow = class {
   getRedirectUri(authPageUrl) {
     return `${authPageUrl.origin}${authPageUrl.pathname}`;
   }
+  newRedirectContext(state, authPageUrl) {
+    return {
+      state,
+      redirectUri: this.getRedirectUri(authPageUrl),
+      createdAt: Date.now()
+    };
+  }
+  /**
+   * Reports a fragment of this flow that cannot be completed, dropping it from the
+   * URL first. Nobody else claims a fragment that names this flow, so leaving it
+   * there would make the application fail again on every reload.
+   */
+  discardOwnRedirect(browserWindow, message) {
+    this.cleanRedirectFragment(browserWindow);
+    return new Error(message);
+  }
+  /** Whether a state echoed by the auth page was generated by this provider's flow. */
+  ownsState(state) {
+    return state.startsWith(`${this.provider}.`);
+  }
+  hasExpired(context) {
+    const ttlMs = this.profile.pendingRequestTtlMs;
+    if (ttlMs === void 0) return false;
+    if (!Number.isFinite(context.createdAt)) return true;
+    return Date.now() - context.createdAt > ttlMs;
+  }
+  /** A one-time state that names the flow that created it, so its fragment is recognizable. */
   generateState() {
     if (!globalThis.crypto?.getRandomValues) {
       throw new Error(`${this.providerLabel} sign-in requires crypto.getRandomValues.`);
     }
     const bytes = new Uint8Array(16);
     globalThis.crypto.getRandomValues(bytes);
-    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    const random = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${this.provider}.${random}`;
   }
   openPopup(browserWindow, url) {
     const outerWidth = browserWindow.outerWidth || browserWindow.screen.width;
@@ -590,7 +678,7 @@ var GoogleAuthFlow = class {
     const top = Math.max(0, (browserWindow.screenY || 0) + (outerHeight - POPUP_HEIGHT) / 2);
     const popup = browserWindow.open(
       url.toString(),
-      "mitra-google-oauth",
+      `mitra-${this.provider}-auth`,
       `width=${POPUP_WIDTH},height=${POPUP_HEIGHT},left=${left},top=${top},menubar=no,toolbar=no,status=no`
     );
     if (!popup) {
@@ -603,7 +691,7 @@ var GoogleAuthFlow = class {
       const timeout = globalThis.setTimeout(() => {
         cleanup();
         reject(new Error(`${this.providerLabel} sign-in timed out.`));
-      }, POPUP_TIMEOUT_MS);
+      }, this.profile.popupTimeoutMs);
       const closedPoll = globalThis.setInterval(() => {
         if (popup.closed) {
           cleanup();
@@ -628,7 +716,7 @@ var GoogleAuthFlow = class {
         const code = typeof data.code === "string" && data.code.trim() ? data.code : void 0;
         if (!code && data.token === void 0) {
           cleanup();
-          reject(new Error("Google auth page returned neither code nor token."));
+          reject(new Error(`${this.providerLabel} auth page returned neither code nor token.`));
           return;
         }
         cleanup();
@@ -643,22 +731,28 @@ var GoogleAuthFlow = class {
       browserWindow.addEventListener("message", onMessage);
     });
   }
-  persistRedirectContext(browserWindow, context) {
+  /** Writes the pending request, reporting whether storage accepted it. */
+  writeRedirectContext(browserWindow, context) {
     try {
-      browserWindow.sessionStorage.setItem(this.redirectStorageKey, JSON.stringify(context));
+      browserWindow[this.profile.redirectStorage].setItem(
+        this.redirectStorageKey,
+        JSON.stringify(context)
+      );
+      return true;
     } catch {
-      throw new Error(`${this.providerLabel} sign-in redirect requires sessionStorage.`);
+      return false;
     }
   }
   readRedirectContext(browserWindow) {
     try {
-      const raw = browserWindow.sessionStorage.getItem(this.redirectStorageKey);
+      const raw = browserWindow[this.profile.redirectStorage].getItem(this.redirectStorageKey);
       if (!raw) return null;
       const value = JSON.parse(raw);
       if (typeof value.state !== "string" || typeof value.redirectUri !== "string") return null;
       return {
         state: value.state,
-        redirectUri: value.redirectUri
+        redirectUri: value.redirectUri,
+        createdAt: typeof value.createdAt === "number" ? value.createdAt : Number.NaN
       };
     } catch {
       return null;
@@ -666,7 +760,7 @@ var GoogleAuthFlow = class {
   }
   clearRedirectContext(browserWindow) {
     try {
-      browserWindow.sessionStorage.removeItem(this.redirectStorageKey);
+      browserWindow[this.profile.redirectStorage].removeItem(this.redirectStorageKey);
     } catch {
     }
   }
@@ -736,6 +830,7 @@ var AuthModule = class {
   currentUserApi;
   googleAuth;
   microsoftAuth;
+  emailAuth;
   constructor(appId, iamBaseUrl, options = {}) {
     this.appId = appId;
     const trimmedIamBaseUrl = stripTrailingSlashes(iamBaseUrl);
@@ -752,19 +847,26 @@ var AuthModule = class {
       onUnauthorized: (requestToken) => this.handleUnauthorized(requestToken)
     });
     this.currentUserApi = (0, import_sdk_core3.createAuthModule)(this.authedClient, coreErrors);
-    this.googleAuth = new GoogleAuthFlow({
+    this.googleAuth = new AuthPageFlow({
       appId,
       apiUrl,
       authPageUrl: options.authPageUrl,
       client: this.publicClient
     });
-    this.microsoftAuth = new GoogleAuthFlow({
+    this.microsoftAuth = new AuthPageFlow({
       appId,
       apiUrl,
       authPageUrl: options.authPageUrl,
       client: this.publicClient,
       provider: "microsoft"
     });
+    this.emailAuth = new AuthPageFlow({
+      appId,
+      apiUrl,
+      authPageUrl: options.authPageUrl,
+      client: this.publicClient,
+      provider: "email"
+    });
     this.loadFromStorage();
     const readAccessToken = () => this.#accessToken;
     sessionPorts.set(this, {
@@ -790,10 +892,10 @@ var AuthModule = class {
   get isAuthenticated() {
     return this._currentUser !== null && this.#accessToken !== null;
   }
-  /** @deprecated Email/password authentication is not implemented by IAM. Use Google or Microsoft SSO. */
+  /** @deprecated Email/password authentication is not implemented by IAM. Use signInWithEmail() or SSO. */
   async signIn(_credentials) {
     throw new MitraApiError(
-      "Email/password authentication is not available. Use signInWithGoogle() or signInWithMicrosoft().",
+      "Email/password authentication is not available. Use signInWithEmail(), signInWithGoogle() or signInWithMicrosoft().",
       0,
       "UNSUPPORTED_AUTH_METHOD"
     );
@@ -879,8 +981,10 @@ var AuthModule = class {
    *
    * The method consumes and clears the fragment and stored CSRF context, sends
    * the single-use code directly to IAM, persists both tokens, calls `auth.me()`,
-   * and notifies auth-state listeners. It returns `null` when the current URL is
-   * not a Google SSO redirect. Redirect errors must carry the same `stateMitra`
+   * and notifies auth-state listeners. It returns `null` when the current URL
+   * carries no redirect result, and also when it carries one this flow never
+   * started, so an application that offers several methods can call every
+   * completion at startup. Redirect errors must carry the same `stateMitra`
    * stored at the start of the flow before their message is exposed or consumed.
    *
    * @returns The authenticated user, or `null` when no redirect result is present.
@@ -916,10 +1020,54 @@ var AuthModule = class {
     const tokenResponse = await this.microsoftAuth.completeRedirect();
     return tokenResponse ? this.establishSession(tokenResponse) : null;
   }
-  /** @deprecated Email/password registration is not implemented by IAM. Use Google or Microsoft SSO. */
+  /**
+   * Signs in with a one-time code sent by email: the same auth-page handshake as
+   * SSO, where the platform page collects the address and the code, and IAM
+   * hands back a single-use exchange code redeemed at `/auth/magic-link/exchange`.
+   * Popup by default; redirect mode navigates away.
+   *
+   * The message also carries a link. Because that link opens a new tab, the
+   * pending request is kept in `localStorage` for 10 minutes - the one-time state
+   * and the auth page URL, never a token - so
+   * {@link completeEmailSignInRedirect} can finish the flow in that tab.
+   *
+   * @param options - Popup or redirect mode.
+   * @returns The authenticated and hydrated user in popup mode.
+   * @throws {MitraApiError} When IAM rejects the exchange code.
+   * @throws {Error} When the browser blocks or cancels the popup, the flow times
+   * out, or the response fails origin, source, state, or shape validation. A
+   * person who finishes through the link instead of the popup leaves this call
+   * to time out, which the application should treat as a cancelled popup.
+   *
+   * @example
+   * ```typescript
+   * const user = await mitra.auth.signInWithEmail();
+   * ```
+   */
+  async signInWithEmail(options = {}) {
+    return this.establishSession(await this.emailAuth.signIn(options));
+  }
+  /**
+   * Completes an email sign-in from `#codeMitra` and `#stateMitra`, during
+   * application startup like {@link completeGoogleSignInRedirect}.
+   *
+   * It covers both ways the flow comes back, and they are the same check: a
+   * redirect in the tab that started it, and the tab the link in the message
+   * opened. Both carry the one-time state this SDK generated, which the second
+   * tab matches against the pending request kept in `localStorage`. A request
+   * older than 10 minutes is discarded instead of completed.
+   *
+   * @returns The authenticated user, or `null` when the URL carries no result or
+   * carries one that belongs to another sign-in method's flow.
+   */
+  async completeEmailSignInRedirect() {
+    const tokenResponse = await this.emailAuth.completeRedirect();
+    return tokenResponse ? this.establishSession(tokenResponse) : null;
+  }
+  /** @deprecated Email/password registration is not implemented by IAM. Use signInWithEmail() or SSO. */
   async signUp(_data) {
     throw new MitraApiError(
-      "Email/password registration is not available. Use signInWithGoogle() or signInWithMicrosoft().",
+      "Email/password registration is not available. Use signInWithEmail(), signInWithGoogle() or signInWithMicrosoft().",
       0,
       "UNSUPPORTED_AUTH_METHOD"
     );
@@ -1660,8 +1808,6 @@ function holdSendsWhileOffline(session, outbox) {
 
 // src/modules/agent-session.ts
 var CONNECT_TIMEOUT_MS = 15e3;
-var CHANNEL_BOOT_TIMEOUT_MS = 9e4;
-var CHANNEL_BOOT_RETRY_MS = 2e3;
 var SILENCE_TIMEOUT_MS = 6e4;
 var RECONNECT_DELAYS_MS = [1e3, 2e3, 4e3, 8e3, 16e3];
 var SUPERSEDED_CLOSE_CODE = 4409;
@@ -1827,28 +1973,28 @@ var BrowserAgentTaskEventSource = class {
   requestDirectChannel(taskId, token, signal) {
     return this.askDirectChannel(taskId, token, signal).catch(() => null);
   }
-  /** Like `requestDirectChannel`, but a request the network lost is thrown, not a refusal. */
+  /**
+   * Like `requestDirectChannel`, but a request the network lost is thrown, not a refusal.
+   *
+   * One request. The copilot holds it while the box boots and answers 200 with the channel, or
+   * an error status once the box cannot be had. A 202 comes only from a copilot older than that
+   * contract, which used to mean "still booting, ask again": there is no channel to open, and
+   * the conversation follows the copilot socket. Polling here again would put the wait back on
+   * the client that the server now owns.
+   */
   async askDirectChannel(taskId, token, signal) {
+    if (signal?.aborted) return null;
     const url = `${this.apiUrl}/copilot/api/v1/tasks/${encodeURIComponent(taskId)}/channel`;
-    const deadline = Date.now() + CHANNEL_BOOT_TIMEOUT_MS;
-    for (; ; ) {
-      if (signal?.aborted) return null;
-      const response = await globalThis.fetch(url, {
-        method: "POST",
-        headers: { Authorization: `Bearer ${stripBearer2(token)}` },
-        ...signal ? { signal } : {}
-      });
-      if (response.status === 202) {
-        if (Date.now() >= deadline) return null;
-        await sleep(CHANNEL_BOOT_RETRY_MS, signal);
-        continue;
-      }
-      if (!response.ok) return null;
-      try {
-        return toDirectChannel(await response.json(), this.apiUrl);
-      } catch {
-        return null;
-      }
+    const response = await globalThis.fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${stripBearer2(token)}` },
+      ...signal ? { signal } : {}
+    });
+    if (response.status === 202 || !response.ok) return null;
+    try {
+      return toDirectChannel(await response.json(), this.apiUrl);
+    } catch {
+      return null;
     }
   }
   async openWebSocket(taskId, observer, signal) {
@@ -2136,6 +2282,10 @@ var BrowserAgentTaskEventSource = class {
 };
 
 // src/modules/agent-tasks.ts
+function bornOnBox(options) {
+  if (!("create" in options) || options.runtime || options.transport === "http") return options;
+  return { ...options, runtime: "T3" };
+}
 function createBrowserAgentTasksModule(httpClient, auth, apiUrl) {
   const tasks = (0, import_sdk_core8.createAgentTasksModule)(httpClient, coreErrors);
   const source = new BrowserAgentTaskEventSource(auth, apiUrl);
@@ -2165,7 +2315,7 @@ function createBrowserAgentTasksModule(httpClient, auth, apiUrl) {
     eventSource
   });
   return (0, import_sdk_core8.withAgentTaskSessions)(tasks, {
-    session: (options) => holdSendsWhileOffline(manager.session(options), outbox)
+    session: (options) => holdSendsWhileOffline(manager.session(bornOnBox(options)), outbox)
   });
 }
 
@@ -2227,7 +2377,12 @@ function expectAppInfoResponse(value) {
   }
   return {
     dataSourceId: response.dataSourceId,
-    allowSignup: response.allowSignup
+    allowSignup: response.allowSignup,
+    // Unlike the fields above, a missing or non-boolean value is read as `false`
+    // instead of failing `init()`: a Code Studio older than the email login gate
+    // answers without this field, and an app that cannot prove it is enabled
+    // should stop offering the option, not stop starting.
+    emailLoginEnabled: response.emailLoginEnabled === true
   };
 }
 function createClient(config) {
@@ -2295,6 +2450,7 @@ function createClient(config) {
   legacyBridge.connect();
   let initialized = false;
   let allowSignup = true;
+  let emailLoginEnabled = false;
   async function init() {
     if (initialized) return;
     const publicClient = new HttpClient({
@@ -2310,6 +2466,7 @@ function createClient(config) {
       entitiesModule.setDataSourceId(appInfo.dataSourceId);
     }
     allowSignup = appInfo.allowSignup;
+    emailLoginEnabled = appInfo.emailLoginEnabled;
     initialized = true;
   }
   return {
@@ -2325,6 +2482,9 @@ function createClient(config) {
     get allowSignup() {
       return allowSignup;
     },
+    get emailLoginEnabled() {
+      return emailLoginEnabled;
+    },
     config
   };
 }