@authsome/ui-core 1.6.0 → 1.6.1

package/dist/index.d.ts

@@ -1448,6 +1448,23 @@ type AuthState = {
 } | {
     status: "unauthenticated";
 }
+/**
+ * A session exists in storage but could not be validated because the auth
+ * server was unreachable or errored — as distinct from the server rejecting
+ * it, which yields "unauthenticated".
+ *
+ * This is deliberately NOT "authenticated": nothing has proven the token is
+ * still good, so `isAuthenticated` is false and protected UI must stay
+ * hidden. The session is retained and a refresh is scheduled, so a
+ * transient outage resolves itself without signing the user out.
+ *
+ * Treat it as "signed out, but don't discard their session yet". An app that
+ * wants to render optimistically can branch on it explicitly.
+ */
+ | {
+    status: "unknown";
+    session: Session;
+}
 /**
  * Sign-in returned the MFA gate (HTTP 403 with type:"mfa_required").
  * The user must complete the second factor against the same ticket
@@ -1498,7 +1515,14 @@ interface AuthConfig {
     initialClientConfig?: ClientConfig;
     /** Custom fetch implementation (defaults to global fetch). */
     fetch?: typeof fetch;
-    /** Storage implementation for persisting tokens (defaults to localStorage). */
+    /**
+     * Storage implementation for persisting tokens.
+     *
+     * Defaults to in-memory, so tokens do not survive a reload and no other
+     * script on the page can read them. Pass createLocalStorage() to persist
+     * across reloads, accepting that an XSS can then read the refresh token;
+     * prefer backend-set httpOnly cookies where available.
+     */
     storage?: TokenStorage;
     /** Callback invoked when the auth state changes. */
     onStateChange?: (state: AuthState) => void;
@@ -2704,6 +2728,25 @@ declare class AuthClient extends AuthClient$1 {
  * class and expose reactive state.
  */
 
+/**
+ * Storage key under which the whole Session (tokens + expiry) is persisted.
+ *
+ * Exported because a cookie-backed TokenStorage writes it as a cookie name,
+ * and server-side readers have to know what to look for. See
+ * @authsome/ui-nextjs readSessionToken.
+ */
+declare const SESSION_STORAGE_KEY = "authsome:session";
+/**
+ * Token storage backed by window.localStorage, falling back to memory where
+ * localStorage is unavailable (SSR, restricted contexts).
+ *
+ * Opt in only if you understand the exposure: everything written here,
+ * including the refresh token, is readable by any script running on the page.
+ * Prefer backend-set httpOnly cookies where you can.
+ *
+ *     new AuthManager({ baseURL, storage: createLocalStorage() })
+ */
+declare function createLocalStorage(): TokenStorage;
 /**
  * AuthManager is the core state machine that drives authentication.
  *
@@ -2739,6 +2782,22 @@ declare class AuthManager {
      * Call this once on app start.
      */
     initialize(): Promise<void>;
+    /**
+     * Resolves the state when hydrating a stored session failed.
+     *
+     * The two failure modes must not be conflated. A rejected credential means
+     * the user is signed out. An unreachable server means we simply do not know,
+     * and signing them out over a transient blip is its own bug — which is what
+     * the previous behaviour tried to avoid, by reporting "authenticated" with a
+     * null user. That kept people signed in through an outage but told every
+     * consumer gating on `isAuthenticated` to render protected UI for a session
+     * nothing had validated, and made `user.email` a crash.
+     *
+     * So: rejection signs out; unavailability yields "unknown", which is not
+     * authenticated but retains the session and keeps a refresh scheduled so the
+     * app recovers on its own.
+     */
+    private handleInitFailure;
     /** Sign in with email & password. */
     signIn(credentials: SignInRequest): Promise<void>;
     /** Sign up with email & password. */
@@ -2812,6 +2871,18 @@ declare class AuthManager {
     /** Tear down: clear timers and listeners. */
     destroy(): void;
     private handleAuthResponse;
+    /**
+     * Exchanges the refresh token for a new session.
+     *
+     * On failure the two cases are separated, as they are in initialize: a
+     * rejected token means signed out, anything else means no verdict and is
+     * worth retrying.
+     *
+     * `attempt` was previously accepted and never read, and the retry path
+     * called back in without it — so a permanently-invalid token retried every
+     * 30s for as long as the tab stayed open, and the user was never signed out.
+     * It now bounds the retries and backs off between them.
+     */
     private refreshSession;
     private scheduleRefresh;
     private clearRefreshTimer;
@@ -2822,6 +2893,59 @@ declare class AuthManager {
     private handleError;
 }
 
+/**
+ * Redirect-target validation.
+ *
+ * Sign-in and sign-up flows accept a `?redirect=` parameter so a user who was
+ * bounced to the auth page lands back where they started. That parameter is
+ * attacker-controlled: without validation, `?redirect=https://evil.com` sends
+ * the user to a hostile page *immediately after they authenticate*, which is
+ * the most convincing possible moment to present a fake "confirm your
+ * password" screen. It can also carry `javascript:` payloads.
+ *
+ * The check here resolves the candidate against the current origin and
+ * compares origins, rather than inspecting the string. String checks are the
+ * usual approach and they leak: `startsWith("/")` accepts `//evil.com` and
+ * `/\evil.com`, both of which browsers resolve to a different host.
+ */
+/** Options controlling which redirect targets are acceptable. */
+interface SafeRedirectOptions {
+    /**
+     * Origin the app is currently served from — `window.location.origin` in a
+     * browser. Redirects to this origin are always allowed.
+     */
+    currentOrigin: string;
+    /**
+     * Extra origins accepted as redirect targets, for deployments where the auth
+     * UI and the app live on different hosts. Empty by default: same-origin only.
+     *
+     * Entries are matched **exactly**, by origin. Wildcards and subdomain
+     * patterns are deliberately unsupported — every tenant host must be listed
+     * in full. Pattern matching here is a well-known source of account-takeover
+     * bugs, and an explicit list is worth the verbosity.
+     *
+     * Each entry must be an absolute URL ("https://portal.example.com"); it is
+     * reduced to its origin, so a trailing slash, a path, or a capitalized host
+     * are all tolerated. Entries that cannot be parsed are ignored and will
+     * never match.
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * Reports whether `candidate` is safe to navigate to after authentication.
+ *
+ * Accepts relative paths ("/dashboard", "/a/b?x=1#f") and absolute URLs whose
+ * origin is the current origin or an allowed one. Refuses everything else,
+ * including a malformed candidate.
+ */
+declare function isSafeRedirect(candidate: string | null | undefined, options: SafeRedirectOptions): boolean;
+/**
+ * Returns `candidate` when it passes {@link isSafeRedirect}, otherwise
+ * `fallback`. Use this at navigation sites so an unsafe value degrades to a
+ * known-good destination instead of blocking the user.
+ */
+declare function safeRedirectTarget(candidate: string | null | undefined, fallback: string, options: SafeRedirectOptions): string;
+
 /**
  * WebAuthn encoding helpers.
  *
@@ -2862,4 +2986,4 @@ declare function prepareRequestOptions(options: Record<string, unknown>): Public
  */
 declare function serializeCredential(credential: Credential): Record<string, unknown>;
 
-export { type APIError, type KeyListItem as APIKey, type AddMemberRequest, type AdminBanUserRequest, AuthClient, type AuthClientConfig, AuthClientError, type AuthConfig, AuthManager, type AuthResponse, type AuthState, type ChallengeMFARequest, type ChangePasswordRequest, type ClientConfig, type CreateAPIKeyRequest, type CreateInvitationRequest, type CreateOrganizationRequest as CreateOrgRequest, type CreateOrganizationRequest, type Device, type EnrollMFARequest, type EnrollResponse, type ForgotPasswordRequest, type Invitation, type KeyListItem, type ListOptions, type ListResponse, type EnrollResponse as MFAEnrollment, type SendMagicLinkRequest as MagicLinkSendRequest, type VerifyMagicLinkRequest as MagicLinkVerifyRequest, type Member, type ChallengeMFARequest as MfaChallengeRequest, type EnrollMFARequest as MfaEnrollRequest, type SendSMSCodeRequest as MfaSMSSendRequest, type VerifySMSCodeRequest as MfaSMSVerifyRequest, type VerifyMFARequest as MfaVerifyRequest, type Organization, type RefreshRequest, type ResetPasswordRequest, type SSOConnectionConfig, type SendMagicLinkRequest, type SendSMSCodeRequest, type Session, type SignInRequest, type SignUpRequest, type SignupFieldConfig, type SignupFieldOption, type SignupFieldValidation, type SocialProviderConfig, type SsoACSRequest, type SsoCallbackRequest, type TokenResponse, type TokenStorage, type UpdateMeRequest, type UpdateOrganizationRequest as UpdateOrgRequest, type UpdateOrganizationRequest, type User, type VerifyEmailRequest, type VerifyMFARequest, type VerifyMagicLinkRequest, type VerifyRecoveryCodeRequest, type VerifySMSCodeRequest, base64urlToBuffer, bufferToBase64url, prepareCreationOptions, prepareRequestOptions, serializeCredential };
+export { type APIError, type KeyListItem as APIKey, type AddMemberRequest, type AdminBanUserRequest, AuthClient, type AuthClientConfig, AuthClientError, type AuthConfig, AuthManager, type AuthResponse, type AuthState, type ChallengeMFARequest, type ChangePasswordRequest, type ClientConfig, type CreateAPIKeyRequest, type CreateInvitationRequest, type CreateOrganizationRequest as CreateOrgRequest, type CreateOrganizationRequest, type Device, type EnrollMFARequest, type EnrollResponse, type ForgotPasswordRequest, type Invitation, type KeyListItem, type ListOptions, type ListResponse, type EnrollResponse as MFAEnrollment, type SendMagicLinkRequest as MagicLinkSendRequest, type VerifyMagicLinkRequest as MagicLinkVerifyRequest, type Member, type ChallengeMFARequest as MfaChallengeRequest, type EnrollMFARequest as MfaEnrollRequest, type SendSMSCodeRequest as MfaSMSSendRequest, type VerifySMSCodeRequest as MfaSMSVerifyRequest, type VerifyMFARequest as MfaVerifyRequest, type Organization, type RefreshRequest, type ResetPasswordRequest, SESSION_STORAGE_KEY, type SSOConnectionConfig, type SafeRedirectOptions, type SendMagicLinkRequest, type SendSMSCodeRequest, type Session, type SignInRequest, type SignUpRequest, type SignupFieldConfig, type SignupFieldOption, type SignupFieldValidation, type SocialProviderConfig, type SsoACSRequest, type SsoCallbackRequest, type TokenResponse, type TokenStorage, type UpdateMeRequest, type UpdateOrganizationRequest as UpdateOrgRequest, type UpdateOrganizationRequest, type User, type VerifyEmailRequest, type VerifyMFARequest, type VerifyMagicLinkRequest, type VerifyRecoveryCodeRequest, type VerifySMSCodeRequest, base64urlToBuffer, bufferToBase64url, createLocalStorage, isSafeRedirect, prepareCreationOptions, prepareRequestOptions, safeRedirectTarget, serializeCredential };

package/dist/index.js

@@ -2661,11 +2661,15 @@ var AuthClient2 = class extends AuthClient {
 };
 
 // src/auth.ts
-var SESSION_KEY = "authsome:session";
+var SESSION_STORAGE_KEY = "authsome:session";
+var SESSION_KEY = SESSION_STORAGE_KEY;
 var CONFIG_KEY = "authsome:client_config";
 var REFRESH_BEFORE_MS = 6e4;
 var CONFIG_TTL_MS = 5 * 6e4;
-var memoryStorage = /* @__PURE__ */ (() => {
+var DEFAULT_SESSION_TTL_MS = 36e5;
+var MAX_REFRESH_ATTEMPTS = 5;
+var REFRESH_RETRY_BASE_MS = 3e4;
+function createMemoryStorage() {
   const store = /* @__PURE__ */ new Map();
   return {
     getItem: (key) => store.get(key) ?? null,
@@ -2676,15 +2680,28 @@ var memoryStorage = /* @__PURE__ */ (() => {
       store.delete(key);
     }
   };
-})();
-function defaultStorage() {
+}
+function createLocalStorage() {
   try {
     if (typeof window !== "undefined" && window.localStorage) {
       return window.localStorage;
     }
   } catch {
   }
-  return memoryStorage;
+  return createMemoryStorage();
+}
+function toSession(res) {
+  return {
+    session_token: res.session_token,
+    refresh_token: res.refresh_token,
+    expires_at: res.expires_at ?? new Date(Date.now() + DEFAULT_SESSION_TTL_MS).toISOString()
+  };
+}
+function isAuthRejection(err) {
+  if (err instanceof AuthClientError) {
+    return err.code === 401 || err.code === 403;
+  }
+  return false;
 }
 var AuthManager = class {
   client;
@@ -2699,7 +2716,7 @@ var AuthManager = class {
   configFetchPromise = null;
   constructor(config) {
     this.client = new AuthClient2(config);
-    this.storage = config.storage ?? defaultStorage();
+    this.storage = config.storage ?? createMemoryStorage();
     this.onError = config.onError;
     this.publishableKey = config.publishableKey;
     if (config.initialClientConfig) {
@@ -2750,27 +2767,50 @@ var AuthManager = class {
       const user = await this.client.getMe(session.session_token);
       this.setState({ status: "authenticated", user, session });
       this.scheduleRefresh(session);
+    } catch (err) {
+      await this.handleInitFailure(err);
+    }
+  }
+  /**
+   * Resolves the state when hydrating a stored session failed.
+   *
+   * The two failure modes must not be conflated. A rejected credential means
+   * the user is signed out. An unreachable server means we simply do not know,
+   * and signing them out over a transient blip is its own bug — which is what
+   * the previous behaviour tried to avoid, by reporting "authenticated" with a
+   * null user. That kept people signed in through an outage but told every
+   * consumer gating on `isAuthenticated` to render protected UI for a session
+   * nothing had validated, and made `user.email` a crash.
+   *
+   * So: rejection signs out; unavailability yields "unknown", which is not
+   * authenticated but retains the session and keeps a refresh scheduled so the
+   * app recovers on its own.
+   */
+  async handleInitFailure(err) {
+    const stored = await this.storage.getItem(SESSION_KEY);
+    if (!stored) {
+      this.setState({ status: "unauthenticated" });
+      return;
+    }
+    let session;
+    try {
+      session = JSON.parse(stored);
     } catch {
-      const stored = await this.storage.getItem(SESSION_KEY);
-      if (stored) {
-        const session = JSON.parse(stored);
-        this.setState({ status: "authenticated", user: null, session });
-        this.scheduleRefresh(session);
-      } else {
-        this.setState({ status: "unauthenticated" });
-      }
+      this.setState({ status: "unauthenticated" });
+      return;
+    }
+    if (isAuthRejection(err)) {
+      this.setState({ status: "unauthenticated" });
+      return;
     }
+    this.setState({ status: "unknown", session });
+    this.scheduleRefresh(session);
   }
   /** Sign in with email & password. */
   async signIn(credentials) {
     try {
       const res = await this.client.signIn(credentials);
-      const session = {
-        session_token: res.session_token,
-        refresh_token: res.refresh_token,
-        expires_at: new Date(Date.now() + 36e5).toISOString()
-        // fallback
-      };
+      const session = toSession(res);
       await this.handleAuthResponse(res.user, session);
     } catch (err) {
       if (err instanceof AuthClientError && err.type === "mfa_required" && err.details) {
@@ -2862,11 +2902,7 @@ var AuthManager = class {
         mfa_ticket: state.mfaTicket,
         code
       });
-      const session = {
-        session_token: res.session_token,
-        refresh_token: res.refresh_token,
-        expires_at: res.expires_at ?? new Date(Date.now() + 36e5).toISOString()
-      };
+      const session = toSession(res);
       await this.handleAuthResponse(res.user, session);
     } catch (err) {
       this.onError?.({
@@ -2889,11 +2925,7 @@ var AuthManager = class {
     this.setState({ status: "loading" });
     try {
       const res = await this.client.verifyRecoveryCode(code);
-      const session = {
-        session_token: res.session_token,
-        refresh_token: res.refresh_token,
-        expires_at: new Date(Date.now() + 36e5).toISOString()
-      };
+      const session = toSession(res);
       await this.handleAuthResponse(res.user, session);
     } catch (err) {
       this.handleError(err);
@@ -2912,11 +2944,7 @@ var AuthManager = class {
       const token = this.getSessionToken();
       if (!token) throw new Error("No session token available");
       const res = await this.client.verifySMSCodeForMFA(code, token);
-      const session = {
-        session_token: res.session_token,
-        refresh_token: res.refresh_token,
-        expires_at: new Date(Date.now() + 36e5).toISOString()
-      };
+      const session = toSession(res);
       await this.handleAuthResponse(res.user, session);
     } catch (err) {
       this.handleError(err);
@@ -3013,6 +3041,18 @@ var AuthManager = class {
     this.setState({ status: "authenticated", user, session });
     this.scheduleRefresh(session);
   }
+  /**
+   * Exchanges the refresh token for a new session.
+   *
+   * On failure the two cases are separated, as they are in initialize: a
+   * rejected token means signed out, anything else means no verdict and is
+   * worth retrying.
+   *
+   * `attempt` was previously accepted and never read, and the retry path
+   * called back in without it — so a permanently-invalid token retried every
+   * 30s for as long as the tab stayed open, and the user was never signed out.
+   * It now bounds the retries and backs off between them.
+   */
   async refreshSession(refreshToken, attempt = 0) {
     try {
       const newSession = await this.client.refresh(refreshToken);
@@ -3020,11 +3060,30 @@ var AuthManager = class {
       await this.persistSession(newSession);
       this.setState({ status: "authenticated", user, session: newSession });
       this.scheduleRefresh(newSession);
-    } catch {
+    } catch (err) {
+      if (isAuthRejection(err)) {
+        this.setState({ status: "unauthenticated" });
+        return;
+      }
+      if (attempt >= MAX_REFRESH_ATTEMPTS) {
+        const stored = await this.storage.getItem(SESSION_KEY);
+        if (stored) {
+          try {
+            this.setState({ status: "unknown", session: JSON.parse(stored) });
+            return;
+          } catch {
+          }
+        }
+        this.setState({ status: "unauthenticated" });
+        return;
+      }
       this.clearRefreshTimer();
-      this.refreshTimer = setTimeout(() => {
-        void this.refreshSession(refreshToken);
-      }, 3e4);
+      this.refreshTimer = setTimeout(
+        () => {
+          void this.refreshSession(refreshToken, attempt + 1);
+        },
+        REFRESH_RETRY_BASE_MS * 2 ** attempt
+      );
     }
   }
   scheduleRefresh(session) {
@@ -3078,6 +3137,40 @@ var AuthManager = class {
   }
 };
 
+// src/redirect.ts
+var ALLOWED_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
+function isSafeRedirect(candidate, options) {
+  if (typeof candidate !== "string" || candidate.trim() === "") {
+    return false;
+  }
+  let resolved;
+  try {
+    resolved = new URL(candidate, options.currentOrigin);
+  } catch {
+    return false;
+  }
+  if (!ALLOWED_PROTOCOLS.has(resolved.protocol)) {
+    return false;
+  }
+  if (resolved.origin === options.currentOrigin) {
+    return true;
+  }
+  return (options.allowedOrigins ?? []).some(
+    (allowed) => toOrigin(allowed) === resolved.origin
+  );
+}
+function toOrigin(value) {
+  try {
+    const { origin } = new URL(value);
+    return origin === "null" ? null : origin;
+  } catch {
+    return null;
+  }
+}
+function safeRedirectTarget(candidate, fallback, options) {
+  return isSafeRedirect(candidate, options) ? candidate : fallback;
+}
+
 // src/webauthn.ts
 function base64urlToBuffer(base64url) {
   const base64 = base64url.replace(/-/g, "+").replace(/_/g, "/");
@@ -3174,10 +3267,14 @@ export {
   AuthClient2 as AuthClient,
   AuthClientError,
   AuthManager,
+  SESSION_STORAGE_KEY,
   base64urlToBuffer,
   bufferToBase64url,
+  createLocalStorage,
+  isSafeRedirect,
   prepareCreationOptions,
   prepareRequestOptions,
+  safeRedirectTarget,
   serializeCredential
 };
 //# sourceMappingURL=index.js.map