@pollar/core 0.9.0 → 0.10.0-rc.0

package/dist/index.js

@@ -189,7 +189,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;
@@ -220,6 +220,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));
 }
@@ -1085,6 +1107,29 @@ function createLogger(level = "info", sink = console) {
   return { error: gate("error"), warn: gate("warn"), info: gate("info"), debug: gate("debug") };
 }
 
+// src/lib/logging.ts
+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 = {};
+  for (const [key, value] of Object.entries(body)) {
+    out[key] = SENSITIVE_BODY_KEYS.has(key) ? "[redacted]" : value;
+  }
+  return out;
+}
+
 // src/storage/web.ts
 var LOG_PREFIX = "[PollarClient:storage]";
 function createMemoryAdapter() {
@@ -1172,8 +1217,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.0" ;
+var POLLAR_CORE_VERSION = "0.10.0-rc.0" ;
 
 // src/visibility/noop.ts
 function createNoopVisibilityProvider() {
@@ -1226,30 +1299,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());
 
@@ -1345,10 +1394,13 @@ function openAlbedoPopup(url) {
 }
 function waitForAlbedoPopup() {
   return new Promise((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      window.removeEventListener("message", handler);
-      reject(new Error("Albedo response timeout"));
-    }, 2 * 60 * 1e3);
+    const timeout = setTimeout(
+      () => {
+        window.removeEventListener("message", handler);
+        reject(new Error("Albedo response timeout"));
+      },
+      2 * 60 * 1e3
+    );
     function handler(event) {
       if (event.origin !== window.location.origin || event.data?.type !== "ALBEDO_RESULT") return;
       clearTimeout(timeout);
@@ -1502,6 +1554,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;
@@ -1708,6 +1764,16 @@ function waitForSessionReady(args) {
   return useStreaming ? streamUntilFound(api, clientSessionId, check, retryDelayMs ?? 200, signal, logger) : pollUntilFound(baseUrl, clientSessionId, check, retryDelayMs ?? 500, signal, logger);
 }
 
+// src/client/auth/logging.ts
+function logApiError(logger, route, detail = {}, level = "error") {
+  const { body, error, data } = detail;
+  logger[level](`[PollarClient:auth] ${route} failed`, {
+    route,
+    ...body !== void 0 ? { body: redactBody(body) } : {},
+    cause: error ?? data
+  });
+}
+
 // src/client/auth/authenticate.ts
 async function authenticate(clientSessionId, deps, expectedWallet) {
   const { api, logger, basePath, useStreaming, signal, setAuthState, storeSession, clearSession } = deps;
@@ -1725,6 +1791,7 @@ async function authenticate(clientSessionId, deps, expectedWallet) {
   } catch (err) {
     if (err instanceof SessionStatusError) {
       const expired = err.code === "EXPIRED_CLIENT_ID";
+      logApiError(logger, "session status", { data: err });
       setAuthState({
         step: "error",
         previousStep: "authenticating",
@@ -1737,14 +1804,12 @@ async function authenticate(clientSessionId, deps, expectedWallet) {
     throw err;
   }
   const dpopJwk = await deps.getPublicJwk();
-  const { data } = await api.POST("/auth/login", {
-    body: {
-      clientSessionId,
-      dpopJwk,
-      ...deps.deviceLabel ? { deviceLabel: deps.deviceLabel } : {}
-    },
-    signal
-  });
+  const body = {
+    clientSessionId,
+    dpopJwk,
+    ...deps.deviceLabel ? { deviceLabel: deps.deviceLabel } : {}
+  };
+  const { data, error } = await api.POST("/auth/login", { body, signal });
   if (data?.code === "SDK_LOGIN_SUCCESS" && isValidSession(data?.content, logger)) {
     const sessionWallet = data.content.data?.providers?.wallet?.address;
     if (expectedWallet && sessionWallet !== expectedWallet) {
@@ -1759,6 +1824,7 @@ async function authenticate(clientSessionId, deps, expectedWallet) {
     }
     await storeSession(data.content);
   } else {
+    if (!error) logApiError(logger, "POST /auth/login", { body, data });
     setAuthState({
       step: "error",
       previousStep: "authenticating",
@@ -1771,10 +1837,11 @@ async function authenticate(clientSessionId, deps, expectedWallet) {
 
 // src/client/auth/deps.ts
 async function createAuthSession(deps) {
-  const { api, signal, setAuthState } = deps;
+  const { api, logger, signal, setAuthState } = deps;
   setAuthState({ step: "creating_session" });
   const { data, error } = await api.POST("/auth/session", { signal });
   if (error || !data?.success) {
+    if (!error) logApiError(logger, "POST /auth/session", { data });
     setAuthState({
       step: "error",
       previousStep: "creating_session",
@@ -1786,20 +1853,96 @@ 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, signal, setAuthState } = deps;
+async function sendEmailCode(email, clientSessionId, ctx) {
+  const { api, logger, signal, setAuthState } = ctx;
   setAuthState({ step: "sending_email", email });
-  const { data, error } = await api.POST("/auth/email", {
-    body: { clientSessionId, email },
-    signal
-  });
+  const body = { clientSessionId, email };
+  const { data, error } = await api.POST("/auth/email", { body, signal });
   if (error || !data?.success) {
+    if (!error) logApiError(logger, "POST /auth/email", { body, data });
     setAuthState({
       step: "error",
       previousStep: "sending_email",
@@ -1810,19 +1953,18 @@ async function sendEmailCode(email, clientSessionId, deps) {
   }
   setAuthState({ step: "entering_code", clientSessionId, email });
 }
-async function verifyAndAuthenticate(code, clientSessionId, email, deps) {
-  const { api, signal, setAuthState } = deps;
+async function verifyAndAuthenticate(code, clientSessionId, email, ctx) {
+  const { api, logger, signal, setAuthState } = ctx;
   setAuthState({ step: "verifying_email_code", clientSessionId, email });
-  const { data, error } = await api.POST("/auth/email/verify-code", {
-    body: { clientSessionId, code },
-    signal
-  });
+  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;
   if (errCode === "SDK_EMAIL_CODE_EXPIRED") {
+    if (!error) logApiError(logger, "POST /auth/email/verify-code", { body, data });
     setAuthState({
       step: "error",
       previousStep: "verifying_email_code",
@@ -1834,6 +1976,7 @@ async function verifyAndAuthenticate(code, clientSessionId, email, deps) {
     return;
   }
   if (errCode === "INVALID_EMAIL_CODE" || errCode === "SDK_EMAIL_CODE_INVALID") {
+    if (!error) logApiError(logger, "POST /auth/email/verify-code", { body, data });
     setAuthState({
       step: "error",
       previousStep: "verifying_email_code",
@@ -1844,6 +1987,7 @@ async function verifyAndAuthenticate(code, clientSessionId, email, deps) {
     });
     return;
   }
+  if (!error) logApiError(logger, "POST /auth/email/verify-code", { body, data });
   setAuthState({
     step: "error",
     previousStep: "verifying_email_code",
@@ -1895,8 +2039,9 @@ async function loginOAuth(provider, deps) {
 
 // src/client/auth/passkeyFlow.ts
 async function smartWalletFlow(deps, mode) {
-  const { api, signal, setAuthState, passkey } = deps;
+  const { api, logger, signal, setAuthState, passkey } = deps;
   if (!passkey) {
+    logger.error("[PollarClient:auth] passkey ceremony not configured");
     setAuthState({
       step: "error",
       previousStep: "creating_session",
@@ -1908,38 +2053,109 @@ async function smartWalletFlow(deps, mode) {
   const clientSessionId = await createAuthSession(deps);
   if (!clientSessionId) return;
   try {
-    const { data: challengeData } = await api.POST("/auth/passkey/challenge", {
-      body: { clientSessionId },
+    const challengeBody = { clientSessionId };
+    const { data: challengeData, error: challengeError } = await api.POST("/auth/passkey/challenge", {
+      body: challengeBody,
       signal
     });
     const challenge = challengeData?.content?.challenge;
     if (!challengeData?.success || !challenge) {
-      return failPasskey(setAuthState, "Failed to start passkey");
+      if (!challengeError) logApiError(logger, "POST /auth/passkey/challenge", { body: challengeBody, data: challengeData });
+      return failPasskey(setAuthState, extractErrorCode(challengeError, challengeData), "Failed to start passkey");
     }
     setAuthState({ step: "creating_passkey" });
     const ceremony = await passkey({ challenge, mode });
     const response = ceremony.response;
     if (ceremony.kind === "register") {
       setAuthState({ step: "deploying_smart_account" });
-      const { data } = await api.POST("/auth/passkey/register", {
-        body: { clientSessionId, response },
-        signal
-      });
-      if (!data?.success) return failPasskey(setAuthState, "Passkey registration failed");
+      const body = { clientSessionId, response };
+      const { data, error } = await api.POST("/auth/passkey/register", { body, signal });
+      if (!data?.success) {
+        if (!error) logApiError(logger, "POST /auth/passkey/register", { body, data });
+        return failPasskey(setAuthState, extractErrorCode(error, data), "Passkey registration failed");
+      }
     } else {
-      const { data } = await api.POST("/auth/passkey/login", {
-        body: { clientSessionId, response },
-        signal
-      });
-      if (!data?.success) return failPasskey(setAuthState, "Passkey authentication failed");
+      const body = { clientSessionId, response };
+      const { data, error } = await api.POST("/auth/passkey/login", { body, signal });
+      if (!data?.success) {
+        if (!error) logApiError(logger, "POST /auth/passkey/login", { body, data });
+        return failPasskey(setAuthState, extractErrorCode(error, data), "Passkey authentication failed");
+      }
     }
-  } catch {
-    return failPasskey(setAuthState, "Passkey login failed");
+  } catch (err) {
+    logApiError(logger, "passkey ceremony", { error: err });
+    return failPasskey(setAuthState, void 0, "Passkey login failed");
   }
   await authenticate(clientSessionId, deps);
 }
-function failPasskey(setAuthState, message) {
-  setAuthState({ step: "error", previousStep: "creating_passkey", message, errorCode: AUTH_ERROR_CODES.PASSKEY_FAILED });
+function failPasskey(setAuthState, code, fallbackMessage) {
+  const { message, errorCode } = resolveAuthError(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
@@ -1955,8 +2171,18 @@ 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, signal, setAuthState } = deps;
+  const { api, logger, signal, setAuthState } = deps;
   const clientSessionId = await createAuthSession(deps);
   if (!clientSessionId) return;
   let connectedWallet;
@@ -1971,12 +2197,36 @@ async function loginWallet(type, deps) {
     const { address } = await withSignal(adapter.connect(), signal);
     connectedWallet = address;
     deps.storeWalletAdapter(adapter, type);
-    setAuthState({ step: "authenticating_wallet" });
-    const { data: walletData, error: walletError } = await api.POST("/auth/wallet", {
-      body: { clientSessionId, walletAddress: address },
+    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, 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 });
       setAuthState({
         step: "error",
         previousStep: "authenticating_wallet",
@@ -1985,7 +2235,8 @@ async function loginWallet(type, deps) {
       });
       return;
     }
-  } catch {
+  } catch (err) {
+    logApiError(logger, "wallet connect", { error: err });
     setAuthState({
       step: "error",
       previousStep: "connecting_wallet",
@@ -2061,6 +2312,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`;
@@ -2082,6 +2340,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" };
@@ -2191,28 +2455,77 @@ var PollarClient = class {
       onResponse: async ({ request, response }) => {
         const newNonce = response.headers.get("DPoP-Nonce");
         if (newNonce) self._dpopNonce = newNonce;
-        if (response.status !== 401) return response;
+        if (response.status !== 401) return self._logHttp(request, response);
         const wwwAuth = response.headers.get("WWW-Authenticate") ?? "";
         const isNonceChallenge = wwwAuth.includes("use_dpop_nonce");
         if (request.url.includes("/auth/refresh")) {
-          if (isNonceChallenge) return self._retryRequest(request);
-          return response;
+          if (isNonceChallenge) return self._logHttp(request, await self._retryRequest(request));
+          return self._logHttp(request, response);
         }
         if (!isNonceChallenge) {
           try {
             await self.refresh();
           } catch {
-            return response;
+            return self._logHttp(request, response);
           }
           const method = request.method.toUpperCase();
           if (method !== "GET" && method !== "HEAD") {
-            return response;
+            return self._logHttp(request, response);
           }
         }
-        return self._retryRequest(request);
+        return self._logHttp(request, await self._retryRequest(request));
       }
     });
   }
+  /**
+   * Logs the final outcome of an SDK API call exactly once: successes (`2xx`) at
+   * `debug` (method + path + status, no body), failures (`4xx`/`5xx`) at `error`
+   * with the redacted request body and the response error body. Returns the
+   * response so it can be chained at the middleware's return points. The error
+   * body is read off a synchronous `clone()` so it never disturbs the body the
+   * caller consumes.
+   */
+  _logHttp(request, response) {
+    const path = this._httpPath(request.url);
+    const label = `[PollarClient:http] ${request.method.toUpperCase()} ${path} ${response.status}`;
+    if (response.ok) {
+      this._log.debug(label);
+    } else {
+      void this._logHttpError(label, request, response.clone());
+    }
+    return response;
+  }
+  /** Reads the redacted request body + JSON response body and logs at `error`. */
+  async _logHttpError(label, request, response) {
+    let requestBody;
+    const cached = this._requestBodyCache.get(request);
+    if (cached) {
+      try {
+        requestBody = redactBody(JSON.parse(new TextDecoder().decode(cached)));
+      } catch {
+      }
+    }
+    let responseBody;
+    if ((response.headers.get("content-type") ?? "").includes("application/json")) {
+      try {
+        responseBody = await response.json();
+      } catch {
+      }
+    }
+    this._log.error(label, {
+      ...requestBody !== void 0 ? { requestBody } : {},
+      ...responseBody !== void 0 ? { responseBody } : {}
+    });
+  }
+  /** Strips origin + `/v1` version prefix from a request URL for compact logs. */
+  _httpPath(url) {
+    try {
+      const { pathname } = new URL(url);
+      return pathname.startsWith("/v1/") ? pathname.slice(3) : pathname;
+    } catch {
+      return url;
+    }
+  }
   async _buildProofForRequest(request, accessToken) {
     try {
       const htu = request.url.split("?")[0].split("#")[0];
@@ -2439,28 +2752,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() {
@@ -2469,7 +2796,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) {
@@ -2481,7 +2808,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) {
@@ -2496,7 +2823,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)
     );
   }
@@ -2861,6 +3188,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.
    *
@@ -2914,14 +3264,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({
@@ -2933,6 +3285,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:
@@ -2951,6 +3351,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 } : {};
@@ -2988,14 +3403,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({
@@ -3082,14 +3505,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({
@@ -3164,13 +3595,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({
@@ -3283,9 +3716,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 } });
@@ -3363,11 +3809,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.
@@ -3499,6 +4001,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,
@@ -3512,6 +4015,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 } : {},