@pollar/core 0.9.1-rc.0 → 0.10.0-rc.0

package/dist/index.mjs

@@ -187,7 +187,7 @@ function defaultKeyManager(storage, apiKey) {
 
 // src/lib/base64url.ts
 var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-(() => {
+var REVERSE = (() => {
   const m = /* @__PURE__ */ new Map();
   for (let i = 0; i < ALPHABET.length; i++) m.set(ALPHABET[i], i);
   return m;
@@ -218,6 +218,28 @@ function base64urlEncode(bytes) {
   }
   return result;
 }
+function base64urlDecode(input) {
+  const clean = input.replace(/=+$/, "");
+  const out = new Uint8Array(Math.floor(clean.length * 3 / 4));
+  let byteIdx = 0;
+  for (let i = 0; i < clean.length; i += 4) {
+    const c1 = REVERSE.get(clean[i]);
+    const c2 = REVERSE.get(clean[i + 1]);
+    const c3 = i + 2 < clean.length ? REVERSE.get(clean[i + 2]) : void 0;
+    const c4 = i + 3 < clean.length ? REVERSE.get(clean[i + 3]) : void 0;
+    if (c1 === void 0 || c2 === void 0) {
+      throw new Error("[PollarClient] Invalid base64url input");
+    }
+    out[byteIdx++] = c1 << 2 | c2 >> 4;
+    if (c3 !== void 0) {
+      out[byteIdx++] = (c2 & 15) << 4 | c3 >> 2;
+      if (c4 !== void 0) {
+        out[byteIdx++] = (c3 & 3) << 6 | c4;
+      }
+    }
+  }
+  return out.slice(0, byteIdx);
+}
 function base64urlEncodeString(s) {
   return base64urlEncode(new TextEncoder().encode(s));
 }
@@ -1084,7 +1106,19 @@ function createLogger(level = "info", sink = console) {
 }
 
 // src/lib/logging.ts
-var SENSITIVE_BODY_KEYS = /* @__PURE__ */ new Set(["email", "code", "walletAddress", "dpopJwk", "response", "refreshToken"]);
+var SENSITIVE_BODY_KEYS = /* @__PURE__ */ new Set([
+  "email",
+  "code",
+  "walletAddress",
+  "dpopJwk",
+  "response",
+  "refreshToken",
+  // SEP-10 challenge envelopes: a counter-signed challenge is a live, replayable
+  // auth credential — never log it in the clear.
+  "signedChallengeXdr",
+  "challengeXdr",
+  "signedTxXdr"
+]);
 function redactBody(body) {
   if (!body || typeof body !== "object") return body;
   const out = {};
@@ -1181,8 +1215,36 @@ function defaultStorage(options = {}) {
   return createLocalStorageAdapter(options);
 }
 
+// src/types.ts
+var AUTH_ERROR_CODES = {
+  SESSION_CREATE_FAILED: "SESSION_CREATE_FAILED",
+  SESSION_EXPIRED: "SESSION_EXPIRED",
+  SESSION_INVALID: "SESSION_INVALID",
+  EMAIL_SEND_FAILED: "EMAIL_SEND_FAILED",
+  EMAIL_VERIFY_FAILED: "EMAIL_VERIFY_FAILED",
+  EMAIL_CODE_EXPIRED: "EMAIL_CODE_EXPIRED",
+  EMAIL_CODE_INVALID: "EMAIL_CODE_INVALID",
+  AUTH_FAILED: "AUTH_FAILED",
+  WALLET_CONNECT_FAILED: "WALLET_CONNECT_FAILED",
+  WALLET_AUTH_FAILED: "WALLET_AUTH_FAILED",
+  WALLET_RESOLVER_TIMEOUT: "WALLET_RESOLVER_TIMEOUT",
+  EXTERNAL_AUTH_FAILED: "EXTERNAL_AUTH_FAILED",
+  PASSKEY_FAILED: "PASSKEY_FAILED",
+  // Generic bucket for on-chain transaction failures; the precise reason is the
+  // backend `code` (e.g. TX_FEE_LIMIT_EXCEEDED) carried alongside on the outcome.
+  TX_FAILED: "TX_FAILED",
+  UNEXPECTED_ERROR: "UNEXPECTED_ERROR"
+};
+var PollarFlowError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "INVALID_FLOW";
+    this.name = "PollarFlowError";
+  }
+};
+
 // src/version.ts
-var POLLAR_CORE_VERSION = "0.9.1-rc.0" ;
+var POLLAR_CORE_VERSION = "0.10.0-rc.0" ;
 
 // src/visibility/noop.ts
 function createNoopVisibilityProvider() {
@@ -1235,30 +1297,6 @@ function defaultVisibilityProvider() {
   return createNoopVisibilityProvider();
 }
 
-// src/types.ts
-var AUTH_ERROR_CODES = {
-  SESSION_CREATE_FAILED: "SESSION_CREATE_FAILED",
-  SESSION_EXPIRED: "SESSION_EXPIRED",
-  SESSION_INVALID: "SESSION_INVALID",
-  EMAIL_SEND_FAILED: "EMAIL_SEND_FAILED",
-  EMAIL_VERIFY_FAILED: "EMAIL_VERIFY_FAILED",
-  EMAIL_CODE_EXPIRED: "EMAIL_CODE_EXPIRED",
-  EMAIL_CODE_INVALID: "EMAIL_CODE_INVALID",
-  AUTH_FAILED: "AUTH_FAILED",
-  WALLET_CONNECT_FAILED: "WALLET_CONNECT_FAILED",
-  WALLET_AUTH_FAILED: "WALLET_AUTH_FAILED",
-  WALLET_RESOLVER_TIMEOUT: "WALLET_RESOLVER_TIMEOUT",
-  PASSKEY_FAILED: "PASSKEY_FAILED",
-  UNEXPECTED_ERROR: "UNEXPECTED_ERROR"
-};
-var PollarFlowError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.code = "INVALID_FLOW";
-    this.name = "PollarFlowError";
-  }
-};
-
 // src/wallets/FreighterAdapter.ts
 var import_freighter_api = __toESM(require_index_min());
 
@@ -1514,6 +1552,10 @@ function isValidSession(value, logger = console) {
     logger.debug("[PollarClient:session] Invalid session \u2014 wallet.type must be internal|smart|external");
     return false;
   }
+  if (w["provider"] !== void 0 && typeof w["provider"] !== "string") {
+    logger.debug("[PollarClient:session] Invalid session \u2014 wallet.provider must be a string if present");
+    return false;
+  }
   if (w["address"] !== null && !isBoundedString(w["address"], MAX_WALLET_PUBLIC_KEY)) {
     logger.debug("[PollarClient:session] Invalid session \u2014 wallet.address must be string|null");
     return false;
@@ -1809,14 +1851,91 @@ async function createAuthSession(deps) {
   return data.content.clientSessionId;
 }
 
+// src/client/auth/errorMessages.ts
+var CATALOG = {
+  // ── Smart-account deploy / sponsor wallet ──────────────────────────────────
+  SPONSOR_NOT_FUNDED: {
+    message: "This app can't create your wallet yet \u2014 its sponsor account isn't funded. Please contact the app's developer.",
+    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
+  },
+  APP_WALLET_NOT_FOUND: {
+    message: "This app isn't fully set up to create wallets yet. Please contact the app's developer.",
+    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
+  },
+  WALLET_NOT_FOUND: {
+    message: "This app isn't fully set up to create wallets yet. Please contact the app's developer.",
+    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
+  },
+  PASSKEY_DEPLOY_FAILED: {
+    message: "We couldn't finish creating your wallet. Please try again in a moment.",
+    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
+  },
+  // ── Passkey ceremony ────────────────────────────────────────────────────────
+  PASSKEY_ALREADY_REGISTERED: {
+    message: "A passkey is already registered for this account. Try signing in instead.",
+    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
+  },
+  PASSKEY_UNKNOWN_CREDENTIAL: {
+    message: "We don't recognize this passkey. Try creating a new one.",
+    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
+  },
+  PASSKEY_VERIFICATION_FAILED: {
+    message: "We couldn't verify your passkey. Please try again.",
+    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
+  },
+  PASSKEY_CHALLENGE_MISSING: {
+    message: "Your passkey session expired. Please start again.",
+    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
+  },
+  // ── On-chain transaction failures (surfaced during deploy/transfer) ─────────
+  // These map to the TX_FAILED bucket (not PASSKEY_FAILED) — the precise reason
+  // is the entry key itself, surfaced as the raw `code` on the tx outcome.
+  TX_INSUFFICIENT_BALANCE: {
+    message: "Insufficient balance to complete this transaction.",
+    errorCode: AUTH_ERROR_CODES.TX_FAILED
+  },
+  TX_INSUFFICIENT_FEE: {
+    message: "Not enough XLM to cover the network fee. Add more XLM to your wallet and try again.",
+    errorCode: AUTH_ERROR_CODES.TX_FAILED
+  },
+  TX_FEE_LIMIT_EXCEEDED: {
+    message: "The transaction fee is above the allowed limit. Please try again.",
+    errorCode: AUTH_ERROR_CODES.TX_FAILED
+  },
+  TX_CONTRACT_FAILED: {
+    message: "The contract rejected this operation. Check the operation is allowed right now and try again.",
+    errorCode: AUTH_ERROR_CODES.TX_FAILED
+  },
+  TX_DESTINATION_NOT_FOUND: {
+    message: "The destination account doesn't exist on the network yet.",
+    errorCode: AUTH_ERROR_CODES.TX_FAILED
+  },
+  TX_NO_TRUSTLINE: {
+    message: "The destination can't receive this asset yet (no trustline).",
+    errorCode: AUTH_ERROR_CODES.TX_FAILED
+  },
+  TX_BAD_SEQUENCE: {
+    message: "Something went out of sync. Please try again.",
+    errorCode: AUTH_ERROR_CODES.TX_FAILED
+  }
+};
+function resolveAuthError(code, fallbackMessage) {
+  if (code && CATALOG[code]) return CATALOG[code];
+  return { message: fallbackMessage, errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED };
+}
+function extractErrorCode(error, data) {
+  return error?.code ?? data?.code ?? void 0;
+}
+
 // src/client/auth/emailFlow.ts
-async function initEmailSession(deps) {
-  const clientSessionId = await createAuthSession(deps);
-  if (!clientSessionId) return;
-  deps.setAuthState({ step: "entering_email", clientSessionId });
+async function initEmailSession(ctx) {
+  const clientSessionId = await ctx.createSession();
+  if (!clientSessionId) return null;
+  ctx.setAuthState({ step: "entering_email", clientSessionId });
+  return clientSessionId;
 }
-async function sendEmailCode(email, clientSessionId, deps) {
-  const { api, logger, signal, setAuthState } = deps;
+async function sendEmailCode(email, clientSessionId, ctx) {
+  const { api, logger, signal, setAuthState } = ctx;
   setAuthState({ step: "sending_email", email });
   const body = { clientSessionId, email };
   const { data, error } = await api.POST("/auth/email", { body, signal });
@@ -1832,13 +1951,13 @@ async function sendEmailCode(email, clientSessionId, deps) {
   }
   setAuthState({ step: "entering_code", clientSessionId, email });
 }
-async function verifyAndAuthenticate(code, clientSessionId, email, deps) {
-  const { api, logger, signal, setAuthState } = deps;
+async function verifyAndAuthenticate(code, clientSessionId, email, ctx) {
+  const { api, logger, signal, setAuthState } = ctx;
   setAuthState({ step: "verifying_email_code", clientSessionId, email });
   const body = { clientSessionId, code };
   const { data, error } = await api.POST("/auth/email/verify-code", { body, signal });
   if (data?.code === "SDK_EMAIL_CODE_VERIFIED") {
-    await authenticate(clientSessionId, deps);
+    await ctx.authenticate(clientSessionId);
     return;
   }
   const errCode = error?.error ?? data?.code;
@@ -1916,68 +2035,6 @@ async function loginOAuth(provider, deps) {
   await authenticate(clientSessionId, deps);
 }
 
-// src/client/auth/errorMessages.ts
-var CATALOG = {
-  // ── Smart-account deploy / sponsor wallet ──────────────────────────────────
-  SPONSOR_NOT_FUNDED: {
-    message: "This app can't create your wallet yet \u2014 its sponsor account isn't funded. Please contact the app's developer.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  APP_WALLET_NOT_FOUND: {
-    message: "This app isn't fully set up to create wallets yet. Please contact the app's developer.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  WALLET_NOT_FOUND: {
-    message: "This app isn't fully set up to create wallets yet. Please contact the app's developer.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  PASSKEY_DEPLOY_FAILED: {
-    message: "We couldn't finish creating your wallet. Please try again in a moment.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  // ── Passkey ceremony ────────────────────────────────────────────────────────
-  PASSKEY_ALREADY_REGISTERED: {
-    message: "A passkey is already registered for this account. Try signing in instead.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  PASSKEY_UNKNOWN_CREDENTIAL: {
-    message: "We don't recognize this passkey. Try creating a new one.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  PASSKEY_VERIFICATION_FAILED: {
-    message: "We couldn't verify your passkey. Please try again.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  PASSKEY_CHALLENGE_MISSING: {
-    message: "Your passkey session expired. Please start again.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  // ── On-chain transaction failures (surfaced during deploy/transfer) ─────────
-  TX_INSUFFICIENT_BALANCE: {
-    message: "Insufficient balance to complete this transaction.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  TX_DESTINATION_NOT_FOUND: {
-    message: "The destination account doesn't exist on the network yet.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  TX_NO_TRUSTLINE: {
-    message: "The destination can't receive this asset yet (no trustline).",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  },
-  TX_BAD_SEQUENCE: {
-    message: "Something went out of sync. Please try again.",
-    errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED
-  }
-};
-function resolveAuthError(code, fallbackMessage) {
-  if (code && CATALOG[code]) return CATALOG[code];
-  return { message: fallbackMessage, errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED };
-}
-function extractErrorCode(error, data) {
-  return error?.code ?? data?.code ?? void 0;
-}
-
 // src/client/auth/passkeyFlow.ts
 async function smartWalletFlow(deps, mode) {
   const { api, logger, signal, setAuthState, passkey } = deps;
@@ -2034,6 +2091,71 @@ function failPasskey(setAuthState, code, fallbackMessage) {
   setAuthState({ step: "error", previousStep: "creating_passkey", message, errorCode });
 }
 
+// src/client/auth/providers.ts
+function oauthProvider(provider) {
+  return {
+    id: provider,
+    login: (ctx) => ctx.startHostedOAuth(provider)
+  };
+}
+function emailProvider() {
+  return {
+    id: "email",
+    login: async (ctx, options) => {
+      const email = options.email ?? "";
+      const clientSessionId = await initEmailSession(ctx);
+      if (clientSessionId) await sendEmailCode(email, clientSessionId, ctx);
+    },
+    actions: {
+      begin: async (ctx) => {
+        await initEmailSession(ctx);
+      },
+      sendCode: (ctx, payload) => {
+        const { email, clientSessionId } = payload ?? {};
+        return sendEmailCode(email, clientSessionId, ctx);
+      },
+      verifyCode: (ctx, payload) => {
+        const { code, clientSessionId, email } = payload ?? {};
+        return verifyAndAuthenticate(code, clientSessionId, email, ctx);
+      }
+    }
+  };
+}
+
+// src/client/auth/sep10-challenge.ts
+var ENVELOPE_TYPE_TX_V0 = 0;
+var ENVELOPE_TYPE_TX = 2;
+var KEY_TYPE_ED25519 = 0;
+var SEQ_OFFSET_V1 = 44;
+var SEQ_OFFSET_V0 = 40;
+function base64ToBytes(b64) {
+  return base64urlDecode(b64.replace(/\+/g, "-").replace(/\//g, "_"));
+}
+function isI64Zero(view, offset) {
+  return view.getUint32(offset, false) === 0 && view.getUint32(offset + 4, false) === 0;
+}
+function isValidSep10Challenge(challengeXdr) {
+  try {
+    const bytes = base64ToBytes(challengeXdr.trim());
+    if (bytes.length < 8) return false;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const envelopeType = view.getUint32(0, false);
+    let seqOffset;
+    if (envelopeType === ENVELOPE_TYPE_TX) {
+      if (view.getUint32(4, false) !== KEY_TYPE_ED25519) return false;
+      seqOffset = SEQ_OFFSET_V1;
+    } else if (envelopeType === ENVELOPE_TYPE_TX_V0) {
+      seqOffset = SEQ_OFFSET_V0;
+    } else {
+      return false;
+    }
+    if (bytes.length < seqOffset + 8) return false;
+    return isI64Zero(view, seqOffset);
+  } catch {
+    return false;
+  }
+}
+
 // src/client/auth/walletFlow.ts
 function withSignal(promise, signal) {
   return Promise.race([
@@ -2047,6 +2169,16 @@ function withSignal(promise, signal) {
     })
   ]);
 }
+async function requestWalletChallenge(clientSessionId, walletAddress, deps) {
+  const { api, logger, signal } = deps;
+  const body = { clientSessionId, walletAddress };
+  const { data, error } = await api.POST("/auth/wallet/challenge", { body, signal });
+  if (error || !data?.success) {
+    if (!error) logApiError(logger, "POST /auth/wallet/challenge", { body, data });
+    return null;
+  }
+  return data.content.challengeXdr;
+}
 async function loginWallet(type, deps) {
   const { api, logger, signal, setAuthState } = deps;
   const clientSessionId = await createAuthSession(deps);
@@ -2063,8 +2195,33 @@ async function loginWallet(type, deps) {
     const { address } = await withSignal(adapter.connect(), signal);
     connectedWallet = address;
     deps.storeWalletAdapter(adapter, type);
+    setAuthState({ step: "signing_wallet_challenge", walletType: type });
+    const challengeXdr = await requestWalletChallenge(clientSessionId, address, deps);
+    if (!challengeXdr) {
+      setAuthState({
+        step: "error",
+        previousStep: "signing_wallet_challenge",
+        message: "Failed to obtain wallet challenge",
+        errorCode: AUTH_ERROR_CODES.WALLET_AUTH_FAILED
+      });
+      return;
+    }
+    if (!isValidSep10Challenge(challengeXdr)) {
+      logApiError(logger, "SEP-10 challenge validation", { error: "unexpected challenge structure (sequence != 0?)" });
+      setAuthState({
+        step: "error",
+        previousStep: "signing_wallet_challenge",
+        message: "Invalid wallet challenge",
+        errorCode: AUTH_ERROR_CODES.WALLET_AUTH_FAILED
+      });
+      return;
+    }
+    const { signedTxXdr } = await withSignal(
+      adapter.signTransaction(challengeXdr, { networkPassphrase: deps.networkPassphrase }),
+      signal
+    );
     setAuthState({ step: "authenticating_wallet" });
-    const body = { clientSessionId, walletAddress: address };
+    const body = { clientSessionId, walletAddress: address, signedChallengeXdr: signedTxXdr };
     const { data: walletData, error: walletError } = await api.POST("/auth/wallet", { body, signal });
     if (walletError || !walletData?.success) {
       if (!walletError) logApiError(logger, "POST /auth/wallet", { body, data: walletData });
@@ -2153,6 +2310,13 @@ var PollarClient = class {
     this._loginController = null;
     /** Aborts an in-flight `/auth/session/resume` on destroy() or re-trigger. */
     this._resumeController = null;
+    /**
+     * Registry of pluggable login strategies, keyed by provider id. Seeded with
+     * the built-ins (`google`, `github`, `email`) and then any `config.providers`
+     * (which can override a built-in by reusing its id). `wallet` is deliberately
+     * absent — it keeps its own dedicated flow. See {@link PollarAuthProvider}.
+     */
+    this._providers = /* @__PURE__ */ new Map();
     this.apiKey = config.apiKey;
     this.id = randomUUID();
     this.basePath = `${config.baseUrl || "https://sdk.api.pollar.xyz"}/v1`;
@@ -2174,6 +2338,12 @@ var PollarClient = class {
     this._maxIdleMs = config.maxIdleMs;
     this._openAuthUrl = config.openAuthUrl ?? defaultWebOAuthOpener;
     this._oauthRedirectUri = config.oauthRedirectUri ?? (isBrowser ? window.location?.origin ?? "" : "");
+    for (const provider of [oauthProvider("google"), oauthProvider("github"), emailProvider()]) {
+      this._providers.set(provider.id, provider);
+    }
+    for (const provider of config.providers ?? []) {
+      this._providers.set(provider.id, provider);
+    }
     this._api = createApiClient(this.basePath);
     this._wireMiddlewares();
     this._networkState = { step: "connected", network: config.stellarNetwork ?? "testnet" };
@@ -2580,28 +2750,42 @@ var PollarClient = class {
       warnServerSide("login");
       return;
     }
-    if (options.provider === "google" || options.provider === "github" || options.provider === "email") {
-      const controller = this._newController();
-      const deps = this._flowDeps(controller.signal);
-      if (options.provider === "google" || options.provider === "github") {
-        loginOAuth(options.provider, {
-          ...deps,
-          basePath: this.basePath,
-          apiKey: this.apiKey,
-          openAuthUrl: this._openAuthUrl,
-          redirectUri: this._oauthRedirectUri
-        }).catch((err) => this._handleFlowError(err));
-      } else if (options.provider === "email") {
-        const { email } = options;
-        initEmailSession(deps).then(() => {
-          if (this._authState.step === "entering_email") {
-            return sendEmailCode(email, this._authState.clientSessionId, deps);
-          }
-        }).catch((err) => this._handleFlowError(err));
-      }
-    } else if (options.provider === "wallet") {
+    if (options.provider === "wallet") {
       this.loginWallet(options.type);
+      return;
+    }
+    const provider = this._providers.get(options.provider);
+    if (!provider?.login) {
+      this._setAuthState({
+        step: "error",
+        previousStep: this._authState.step,
+        message: `No auth provider registered for '${options.provider}'`,
+        errorCode: AUTH_ERROR_CODES.AUTH_FAILED
+      });
+      return;
+    }
+    const controller = this._newController();
+    provider.login(this._providerContext(controller.signal), options).catch((err) => this._handleFlowError(err));
+  }
+  /**
+   * Invoke a named secondary step on a registered provider (e.g. email's
+   * `sendCode` / `verifyCode`, or a custom provider's multi-step continuation).
+   * Reuses the in-flight login `AbortController` when one exists so the step
+   * stays cancellable via `cancelLogin()`; otherwise starts a fresh one. The
+   * built-in email steps also have dedicated typed methods
+   * ({@link sendEmailCode} / {@link verifyEmailCode}) — prefer those for email.
+   */
+  providerAction(provider, action, payload) {
+    if (!isClientRuntime) {
+      warnServerSide("providerAction");
+      return;
+    }
+    const fn = this._providers.get(provider)?.actions?.[action];
+    if (!fn) {
+      throw new PollarFlowError(`Auth provider '${provider}' has no action '${action}'`);
     }
+    const signal = this._loginController?.signal ?? this._newController().signal;
+    fn(this._providerContext(signal), payload).catch((err) => this._handleFlowError(err));
   }
   // ─── Email OTP flow (3 steps) ─────────────────────────────────────────────
   beginEmailLogin() {
@@ -2610,7 +2794,7 @@ var PollarClient = class {
       return;
     }
     const controller = this._newController();
-    initEmailSession(this._flowDeps(controller.signal)).catch((err) => this._handleFlowError(err));
+    initEmailSession(this._providerContext(controller.signal)).catch((err) => this._handleFlowError(err));
   }
   sendEmailCode(email) {
     if (!isClientRuntime) {
@@ -2622,7 +2806,7 @@ var PollarClient = class {
     }
     const { clientSessionId } = this._authState;
     const signal = this._loginController.signal;
-    sendEmailCode(email, clientSessionId, this._flowDeps(signal)).catch((err) => this._handleFlowError(err));
+    sendEmailCode(email, clientSessionId, this._providerContext(signal)).catch((err) => this._handleFlowError(err));
   }
   verifyEmailCode(code) {
     if (!isClientRuntime) {
@@ -2637,7 +2821,7 @@ var PollarClient = class {
     const clientSessionId = state.step === "entering_code" ? state.clientSessionId : state.clientSessionId;
     const email = state.step === "entering_code" ? state.email : state.email ?? "";
     const controller = this._newController();
-    verifyAndAuthenticate(code, clientSessionId, email, this._flowDeps(controller.signal)).catch(
+    verifyAndAuthenticate(code, clientSessionId, email, this._providerContext(controller.signal)).catch(
       (err) => this._handleFlowError(err)
     );
   }
@@ -3002,6 +3186,29 @@ var PollarClient = class {
   getWalletType() {
     return this._walletAdapter?.type ?? null;
   }
+  /**
+   * The authenticated user's wallet as a {@link WalletInfo} discriminated union,
+   * or `null` when there's no session (or the session carries no address yet).
+   *
+   * `custody` strictly determines `provider` (the mapping is 1:1 and fixed at
+   * account creation server-side): `external` reports the connected adapter id
+   * (`getWalletType()`), `smart` is always `'passkey'`, and `internal` reports
+   * the login method the backend recorded (`null` for pre-provider sessions).
+   */
+  getWallet() {
+    const w = this._session?.wallet;
+    if (!w || !w.address) return null;
+    switch (w.type) {
+      case "external":
+        return { custody: "external", address: w.address, provider: this._walletAdapter?.type ?? null };
+      case "smart":
+        return { custody: "smart", address: w.address, provider: "passkey" };
+      case "internal":
+        return { custody: "internal", address: w.address, provider: w.provider ?? null };
+      default:
+        return null;
+    }
+  }
   /**
    * Signs the given unsigned XDR and returns the signed XDR.
    *
@@ -3055,14 +3262,16 @@ var PollarClient = class {
         });
         return { status: "signed", signedXdr, submissionToken: idempotencyKey };
       }
-      const details = error?.details;
+      const { details, code, message } = this._resolveTxApiError(error);
       this._setTransactionState({
         step: "error",
         phase: "signing",
         ...buildData && { buildData },
-        ...details && { details }
+        ...details && { details },
+        ...code && { code },
+        ...message && { message }
       });
-      return { status: "error", ...details && { details } };
+      return { status: "error", ...details && { details }, ...code && { code }, ...message && { message } };
     } catch (err) {
       const details = err instanceof Error ? err.message : void 0;
       this._setTransactionState({
@@ -3074,6 +3283,54 @@ var PollarClient = class {
       return { status: "error", ...details && { details } };
     }
   }
+  /**
+   * Sign a single Soroban authorization entry (`SorobanAuthorizationEntry`).
+   *
+   * Use this when a contract is the transaction source (e.g. it sponsors the
+   * gas and swaps the fee out of the user's token) and only needs the user's
+   * address-credentials authorization, not a full signed envelope. The signed
+   * entry is returned as base64 XDR for the caller to compose into its tx.
+   *
+   * - External wallets (Freighter/Albedo) sign the entry via the provider.
+   * - Custodial wallets are signed by the backend, which FIRST validates the
+   *   entry's invocation tree against the app's contract/function allowlist and
+   *   caps the validity window — entries touching a non-allowlisted contract or
+   *   function, or expiring too far ahead, are rejected.
+   *
+   * @param entryXdr base64 XDR of the unsigned `SorobanAuthorizationEntry`.
+   * @param options.validUntilLedger absolute ledger the signature expires at
+   *   (computed from the network's latest ledger). Ignored on the external-wallet
+   *   path, where the provider sets its own expiration.
+   */
+  async signAuthEntry(entryXdr, options) {
+    if (this._walletAdapter) {
+      const accountToSign = this._session?.wallet?.address;
+      try {
+        const { signedAuthEntry } = await this._walletAdapter.signAuthEntry(
+          entryXdr,
+          accountToSign ? { accountToSign } : void 0
+        );
+        return { status: "signed", signedAuthEntry };
+      } catch (err) {
+        const details = err instanceof Error ? err.message : void 0;
+        return { status: "error", ...details && { details } };
+      }
+    }
+    const address = this._session?.wallet?.address ?? "";
+    try {
+      const { data, error } = await this._api.POST("/tx/sign-auth-entry", {
+        body: { network: this.getNetwork(), address, entryXdr, validUntilLedger: options.validUntilLedger }
+      });
+      if (!error && data?.success && data.content?.signedAuthEntry) {
+        return { status: "signed", signedAuthEntry: data.content.signedAuthEntry };
+      }
+      const details = error?.details;
+      return { status: "error", ...details && { details } };
+    } catch (err) {
+      const details = err instanceof Error ? err.message : void 0;
+      return { status: "error", ...details && { details } };
+    }
+  }
   /**
    * Submits a signed XDR via `/tx/submit` regardless of wallet type
    * (custodial or external). Routing through sdk-api gives us:
@@ -3092,6 +3349,21 @@ var PollarClient = class {
    * `submitted` on Horizon ack (pending), `success` on ledger confirmation,
    * or `error[phase: 'submitting']` on failure.
    */
+  /**
+   * Normalize a backend API error into { details, code, message }. `code` is the
+   * precise backend ErrorCode (e.g. `TX_FEE_LIMIT_EXCEEDED`) for programmatic
+   * handling; `message` is a friendly string from the error catalog; `details`
+   * is the raw diagnostic. Lets tx flows surface a typed reason instead of an
+   * opaque details string.
+   */
+  _resolveTxApiError(error) {
+    const e = error;
+    const details = e?.details ?? e?.message;
+    const code = e?.code;
+    if (!code) return details ? { details } : {};
+    const { message } = resolveAuthError(code, details ?? code);
+    return { code, message, ...details && { details } };
+  }
   async submitTx(signedXdr, opts) {
     const buildData = this._currentBuildData();
     const outcomeExtra = buildData ? { buildData } : {};
@@ -3129,14 +3401,22 @@ var PollarClient = class {
           ...resultCode && { details: resultCode, resultCode }
         };
       }
-      const details = error?.details;
+      const { details, code, message } = this._resolveTxApiError(error);
       this._setTransactionState({
         step: "error",
         phase: "submitting",
         ...buildData && { buildData },
-        ...details && { details }
+        ...details && { details },
+        ...code && { code },
+        ...message && { message }
       });
-      return { status: "error", ...outcomeExtra, ...details && { details } };
+      return {
+        status: "error",
+        ...outcomeExtra,
+        ...details && { details },
+        ...code && { code },
+        ...message && { message }
+      };
     } catch (err) {
       const details = err instanceof Error ? err.message : void 0;
       this._setTransactionState({
@@ -3223,14 +3503,22 @@ var PollarClient = class {
           ...resultCode && { details: resultCode, resultCode }
         };
       }
-      const details = error?.details;
+      const { details, code, message } = this._resolveTxApiError(error);
       this._setTransactionState({
         step: "error",
         phase: "signing-submitting",
         ...buildData && { buildData },
-        ...details && { details }
+        ...details && { details },
+        ...code && { code },
+        ...message && { message }
       });
-      return { status: "error", ...outcomeExtra, ...details && { details } };
+      return {
+        status: "error",
+        ...outcomeExtra,
+        ...details && { details },
+        ...code && { code },
+        ...message && { message }
+      };
     } catch (err) {
       const details = err instanceof Error ? err.message : void 0;
       this._setTransactionState({
@@ -3305,13 +3593,15 @@ var PollarClient = class {
         });
         return { status: "error", hash, ...resultCode && { details: resultCode, resultCode } };
       }
-      const details = error?.details;
+      const { details, code, message } = this._resolveTxApiError(error);
       this._setTransactionState({
         step: "error",
         phase: "building-signing-submitting",
-        ...details && { details }
+        ...details && { details },
+        ...code && { code },
+        ...message && { message }
       });
-      return { status: "error", ...details && { details } };
+      return { status: "error", ...details && { details }, ...code && { code }, ...message && { message } };
     } catch (err) {
       const details = err instanceof Error ? err.message : void 0;
       this._setTransactionState({
@@ -3424,9 +3714,22 @@ var PollarClient = class {
         });
         return { status: "error", hash, ...outcomeExtra, ...resultCode && { details: resultCode, resultCode } };
       }
-      const details = error?.details;
-      this._setTransactionState({ step: "error", phase: "submitting", buildData, ...details && { details } });
-      return { status: "error", ...outcomeExtra, ...details && { details } };
+      const { details, code, message } = this._resolveTxApiError(error);
+      this._setTransactionState({
+        step: "error",
+        phase: "submitting",
+        buildData,
+        ...details && { details },
+        ...code && { code },
+        ...message && { message }
+      });
+      return {
+        status: "error",
+        ...outcomeExtra,
+        ...details && { details },
+        ...code && { code },
+        ...message && { message }
+      };
     } catch (err) {
       const details = err instanceof Error ? err.message : void 0;
       this._setTransactionState({ step: "error", phase: "submitting", buildData, ...details && { details } });
@@ -3504,11 +3807,67 @@ var PollarClient = class {
     this._loginController = new AbortController();
     return this._loginController;
   }
+  /**
+   * Build the {@link AuthProviderContext} facade for one login attempt. Wraps
+   * the internal `FlowDeps` so providers get only the curated primitives —
+   * `createSession`, `authenticate`, `exchangeExternalToken`, `startHostedOAuth`
+   * — while storage / wallet-adapter / key-manager internals stay private. All
+   * legs share the same `signal`, so `cancelLogin()` aborts the whole chain.
+   */
+  _providerContext(signal) {
+    const deps = this._flowDeps(signal);
+    return {
+      signal,
+      api: this._api,
+      basePath: this.basePath,
+      apiKey: this.apiKey,
+      logger: this._log,
+      setAuthState: this._setAuthState.bind(this),
+      createSession: () => createAuthSession(deps),
+      authenticate: (clientSessionId) => authenticate(clientSessionId, deps),
+      requestChallenge: (clientSessionId, walletAddress) => requestWalletChallenge(clientSessionId, walletAddress, deps),
+      exchangeExternalToken: (clientSessionId, body) => this._exchangeExternalToken(clientSessionId, body, signal),
+      startHostedOAuth: (provider) => loginOAuth(provider, {
+        ...deps,
+        basePath: this.basePath,
+        apiKey: this.apiKey,
+        openAuthUrl: this._openAuthUrl,
+        redirectUri: this._oauthRedirectUri
+      })
+    };
+  }
+  /**
+   * Generic external-provider exchange leg (`POST /auth/external`). Custom
+   * providers call this (via the context) after their own SDK has authenticated
+   * the user and the wallet has counter-signed the SEP-10 challenge
+   * (`{ provider, walletAddress, signedChallengeXdr }`). On success the session
+   * is marked READY server-side and the provider should then call
+   * `ctx.authenticate(clientSessionId)`. Returns `false` (and sets an error
+   * state) on failure.
+   */
+  async _exchangeExternalToken(clientSessionId, body, signal) {
+    const { data, error } = await this._api.POST("/auth/external", {
+      body: { clientSessionId, ...body },
+      signal
+    });
+    if (error || !data?.success) {
+      this._log.error("[PollarClient] External provider authentication failed", { error });
+      this._setAuthState({
+        step: "error",
+        previousStep: this._authState.step,
+        message: "External provider authentication failed",
+        errorCode: AUTH_ERROR_CODES.EXTERNAL_AUTH_FAILED
+      });
+      return false;
+    }
+    return true;
+  }
   _flowDeps(signal) {
     return {
       api: this._api,
       logger: this._log,
       basePath: this.basePath,
+      networkPassphrase: this._networkPassphrase(),
       // SSE status streaming works on web; React Native's `fetch` has no
       // readable `response.body`, so those clients poll the non-streaming
       // status endpoint instead. `isBrowser` is false in RN and SSR alike.
@@ -3640,6 +3999,7 @@ var PollarClient = class {
   async _storeSession(session) {
     this._log.info("[PollarClient] Session stored");
     const w = session.wallet;
+    const wireProvider = w.provider;
     const persisted = {
       clientSessionId: session.clientSessionId,
       userId: session.userId ?? null,
@@ -3653,6 +4013,7 @@ var PollarClient = class {
       // persisted session speak one vocabulary while the wire stays compatible.
       wallet: {
         type: w.type === "custodial" ? "internal" : w.type,
+        ...wireProvider ? { provider: wireProvider } : {},
         address: w.address ?? w.publicKey ?? null,
         ...w.existsOnStellar !== void 0 ? { existsOnStellar: w.existsOnStellar } : {},
         ...w.createdAt !== void 0 ? { createdAt: w.createdAt } : {},