@pollar/core 0.5.3 → 0.7.0

package/README.md

@@ -2,6 +2,11 @@
 
 Core SDK for [Pollar](https://pollar.xyz) — authentication and transaction utilities for Stellar-based applications.
 
+> **0.7.0 ships sender-constrained tokens via DPoP (RFC 9449), pluggable storage and key managers, automatic
+refresh-on-401, and removes PII from persisted storage.** This is a breaking change — read
+> the [CHANGELOG](../../CHANGELOG.md) before upgrading. Requires HTTPS and
+`sdk-api` ≥ Phase 5.
+
 ## Installation
 
 ```bash
@@ -12,43 +17,130 @@ pnpm add @pollar/core
 yarn add @pollar/core
 ```
 
+For React Native / Expo, also install one of the storage adapter peer deps:
+
+```bash
+# Expo
+npx expo install expo-secure-store react-native-get-random-values
+
+# Bare React Native
+npm i react-native-keychain react-native-get-random-values
+```
+
 ## Overview
 
 `@pollar/core` provides the `PollarClient` class and utilities to:
 
 - Authenticate users via **Google**, **GitHub**, **Email (OTP)**, or **Stellar wallets** (Freighter, Albedo)
+- Sign every authenticated request with **DPoP** (RFC 9449), making stolen tokens useless to an attacker without the
+  per-session keypair
 - Build and submit Stellar transactions
 - Fetch Stellar account balances
 - React to real-time authentication state changes
 
-## Quick Start
+## Quick Start (web)
+
+```ts
+import { PollarClient } from '@pollar/core';
+
+const client = new PollarClient({ apiKey: 'your-api-key' });
+// Storage and KeyManager autodetect:
+//   storage  → localStorage with in-memory fallback
+//   keypair  → WebCrypto ECDSA P-256, non-extractable, persisted in IndexedDB
+```
+
+## React Native (Expo)
+
+```ts
+// At your app entry — `crypto.getRandomValues` polyfill
+import 'react-native-get-random-values';
+
+import { PollarClient } from '@pollar/core';
+import { createSecureStoreAdapter } from '@pollar/core/adapters/expo';
+
+// `await`: SecureStore is loaded via dynamic import.
+const storage = await createSecureStoreAdapter({
+  // Default: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY
+  // Prevents iCloud Keychain from carrying the key to another device.
+});
+
+const client = new PollarClient({ apiKey: 'your-api-key', storage });
+// KeyManager autodetects → NobleKeyManager (pure-JS @noble/curves p256).
+```
+
+## React Native (`react-native-keychain`)
+
+```ts
+import 'react-native-get-random-values';
+import { PollarClient } from '@pollar/core';
+import { createKeychainAdapter } from '@pollar/core/adapters/react-native-keychain';
+
+const storage = await createKeychainAdapter();
+const client = new PollarClient({ apiKey: 'your-api-key', storage });
+```
+
+## Preserved-on-disk storage shape
+
+0.7.0 persists exactly:
+
+```
+clientSessionId, userId, status,
+token { accessToken, refreshToken, expiresAt },
+user { id?, ready },
+wallet { publicKey, existsOnStellar?, createdAt? }
+```
+
+PII (`mail`, `first_name`, `last_name`, `avatar`, `providers.*`) lives **in memory only** on the `PollarClient` instance
+and is fetched after auth. Reach it via:
+
+```ts
+const profile = client.getUserProfile();
+// { mail, first_name, last_name, avatar, providers } | null
+```
+
+Storage keys are namespaced by `apiKeyHash` (first 8 hex chars of SHA-256 of your API key) so multiple SDK instances on
+the same origin don't cross-contaminate.
+
+## End-to-end example
 
 ```ts
 import { PollarClient } from '@pollar/core';
 
 const client = new PollarClient({ apiKey: 'your-api-key' });
 
-// Listen to state changes
-client.onStateChange((entry) => {
-  console.log(entry.var, entry.code, entry.status);
+// React to auth state
+const unsubscribe = client.onAuthStateChange((state) => {
+  console.log(state.step, state.errorCode ?? '');
 });
 
-// Login with email
-const { cancelLogin } = client.login({ provider: 'email', email: 'user@example.com' });
+// Wait until the keypair is ready and any persisted session has been restored
+await client.ready();
+
+// Start an email login
+client.login({ provider: 'email', email: 'user@example.com' });
+
+// Submit the OTP — clientSessionId is tracked internally
+client.verifyEmailCode('123456');
 
-// Verify the OTP code sent to the user
-await client.verifyEmailCode(clientSessionId, '123456');
+// After success
+const profile = client.getUserProfile();   // PII (memory-only)
+const sessions = await client.listSessions();
 ```
 
 ## API Reference
 
 ### `new PollarClient(config)`
 
-| Option          | Type     | Required | Description                                        |
-| --------------- | -------- | -------- | -------------------------------------------------- |
-| `apiKey`        | `string` | Yes      | Your Pollar API key                                |
-| `baseUrl`       | `string` | No       | Override the default API endpoint                  |
-| `stellarNetwork`| `'mainnet' \| 'testnet'` | No | Target Stellar network (default: `testnet`) |
+| Option             | Type                     | Required | Description                                                                                              |
+|--------------------|--------------------------|----------|----------------------------------------------------------------------------------------------------------|
+| `apiKey`           | `string`                 | Yes      | Your Pollar API key                                                                                      |
+| `baseUrl`          | `string`                 | No       | Override the default API endpoint                                                                        |
+| `stellarNetwork`   | `'mainnet' \| 'testnet'` | No       | Target Stellar network (default: `testnet`)                                                              |
+| `storage`          | `Storage`                | No       | Pluggable storage adapter. Web autodetects `localStorage` with in-memory fallback; RN must inject one    |
+| `keyManager`       | `KeyManager`             | No       | Pluggable DPoP key manager. Web picks `WebCryptoKeyManager`; otherwise `NobleKeyManager`                  |
+| `walletAdapter`    | `WalletAdapterResolver`  | No       | External wallet stack (e.g. Stellar Wallets Kit). Falls back to built-in `FreighterAdapter`/`AlbedoAdapter` |
+| `deviceLabel`      | `string`                 | No       | UI-friendly device label sent at `/auth/login` time and shown in `listSessions()` rows                   |
+| `onStorageDegrade` | `OnStorageDegrade`       | No       | Notified the first time `localStorage` falls back to in-memory mode (SSR, private browsing, quota, …)    |
 
 ---
 
@@ -72,18 +164,87 @@ client.login({ provider: 'wallet', type: WalletType.FREIGHTER });
 client.login({ provider: 'wallet', type: WalletType.ALBEDO });
 ```
 
-#### `client.verifyEmailCode(clientSessionId, code)`
+#### `client.verifyEmailCode(code)`
+
+Submits the OTP code for email authentication. The active `clientSessionId` is tracked internally — no need to pass it.
 
-Submits the OTP code for email authentication. Use `clientSessionId` received from the `EMAIL_AUTH_START_SUCCESS` state event.
+#### `client.loginWallet(walletId)`
 
-#### `client.logout()`
+Lower-level entry point for wallet flows. Accepts any `WalletId` (`WalletType.FREIGHTER`, `WalletType.ALBEDO`, or an
+opaque string id like `'xbull'` / `'lobstr'` resolved by `walletAdapter`).
 
-Clears the current session from memory and storage.
+#### `client.cancelLogin()`
+
+Aborts any in-flight login flow and resets `authState` to `idle`. Safe to call from any step (including `error`).
+
+#### `client.logout(options?): Promise<void>`
+
+Server-side revokes the refresh-token family via `POST /v1/auth/logout`, then clears local storage and resets the
+keypair. Server revocation is best-effort: a failed POST still clears local state.
+
+```ts
+await client.logout();                       // sign out this device
+await client.logout({ everywhere: true });   // revoke every active session for this user
+```
+
+> Returns `Promise<void>` (was `void` pre-0.7.0). Existing fire-and-forget call sites keep working, but `await` it if
+> you want to observe server-side revocation.
+
+#### `client.logoutEverywhere(): Promise<void>`
+
+Shorthand for `logout({ everywhere: true })`.
 
 #### `client.isAuthenticated()`
 
 Returns `true` if a valid session with a wallet public key is present.
 
+#### `client.getUserProfile(): PollarUserProfile | null`
+
+Returns the in-memory profile (`mail`, `first_name`, `last_name`, `avatar`, `providers`). `null` until `/auth/login`
+completes. **This is the only way to read PII as of 0.7.0** — PII is no longer persisted to storage.
+
+#### `client.ready(): Promise<void>`
+
+Resolves once the keypair is initialized and any persisted session has been restored. Useful in tests and
+server-side rendering.
+
+#### `client.destroy(): void`
+
+Detaches the cross-tab `storage` listener, aborts in-flight logins, and releases the keypair. Call this on unmount in
+environments that re-instantiate `PollarClient`.
+
+#### `client.refresh(): Promise<void>`
+
+Forces an access-token refresh. Race-safe: concurrent calls coalesce into a single `/v1/auth/refresh` request.
+Request middleware also calls this automatically on 401 with `DPoP-Nonce` rotation.
+
+---
+
+### Sessions
+
+#### `client.listSessions(): Promise<SessionInfo[]>`
+
+Returns one row per active refresh-token family for the authenticated user:
+
+```ts
+interface SessionInfo {
+  familyId: string;
+  createdAt: string;
+  lastUsedAt: string;
+  userAgent: string;
+  ipHash: string;
+  deviceLabel?: string;
+  expiresAt: string;
+  current: boolean; // true for the family backing this client
+}
+```
+
+#### `client.revokeSession(familyId): Promise<void>`
+
+Revokes a specific refresh-token family. Revoking the **current** family does not immediately clear local state — the
+next 401 triggers an auto-refresh, which fails (family revoked) and clears the session. Call `logout()` for an
+immediate teardown.
+
 ---
 
 ### Transactions
@@ -112,32 +273,36 @@ await client.submitTx(signedXdr);
 
 ### State
 
-#### `client.onStateChange(callback)`
-
-Subscribe to state changes. Returns an unsubscribe function.
+Each state domain has its own typed subscriber. All `on*StateChange` methods return an unsubscribe function.
 
 ```ts
-const unsubscribe = client.onStateChange((entry) => {
-  // entry.var    — 'authentication' | 'transaction' | 'network'
-  // entry.code   — granular event code (see STATE_VAR_CODES)
-  // entry.status — 'NONE' | 'LOADING' | 'SUCCESS' | 'ERROR'
-  // entry.data   — optional payload
-  // entry.level  — 'info' | 'warn' | 'error'
-  // entry.ts     — timestamp (ms)
+const unsubAuth = client.onAuthStateChange((state) => {
+  // state.step    — 'idle' | 'oauth' | 'email' | 'wallet' | 'success' | 'error'
+  // state.session — PollarPersistedSession (when step === 'success')
+  // state.errorCode — AuthErrorCode (when step === 'error')
 });
 
-// Unsubscribe
-unsubscribe();
+const unsubTx       = client.onTransactionStateChange((s) => { /* build → sign → submit */ });
+const unsubHistory  = client.onTxHistoryStateChange((s) => { /* paginated rows */ });
+const unsubBalance  = client.onWalletBalanceStateChange((s) => { /* balances */ });
+const unsubNetwork  = client.onNetworkStateChange((s) => { /* mainnet / testnet */ });
+
+unsubAuth();
 ```
 
-All state codes are available via `STATE_VAR_CODES`:
+Snapshot getters are also available: `getAuthState()`, `getTransactionState()`, `getTxHistoryState()`,
+`getWalletBalanceState()`, `getNetworkState()`.
+
+Error codes for the auth flow are surfaced via `AUTH_ERROR_CODES` / `AuthErrorCode`:
 
 ```ts
-import { STATE_VAR_CODES } from '@pollar/core';
+import { AUTH_ERROR_CODES, type AuthErrorCode } from '@pollar/core';
 
-// STATE_VAR_CODES.authentication.EMAIL_AUTH_START_SUCCESS
-// STATE_VAR_CODES.transaction.BUILD_TRANSACTION_SUCCESS
-// STATE_VAR_CODES.network.NETWORK_UPDATED
+// AUTH_ERROR_CODES.EMAIL_CODE_INVALID
+// AUTH_ERROR_CODES.EMAIL_CODE_EXPIRED
+// AUTH_ERROR_CODES.SESSION_CREATE_FAILED
+// AUTH_ERROR_CODES.WALLET_CONNECT_FAILED
+// …see types.ts for the full list
 ```
 
 ---
@@ -178,6 +343,50 @@ if (available) {
 }
 ```
 
+To plug in external wallet stacks (e.g. Stellar Wallets Kit) without `@pollar/core` having to depend on them, pass a
+`WalletAdapterResolver` to the client:
+
+```ts
+import { PollarClient, WalletType } from '@pollar/core';
+import { stellarWalletsKit } from '@pollar/stellar-wallets-kit-adapter';
+import { Networks } from '@creit.tech/stellar-wallets-kit';
+
+const client = new PollarClient({
+  apiKey: 'pk_...',
+  walletAdapter: stellarWalletsKit({ network: Networks.PUBLIC }),
+});
+
+client.loginWallet('xbull'); // any string id the kit understands
+```
+
+The resolver signature is:
+
+```ts
+type WalletAdapterResolver = (id: WalletId) => WalletAdapter | Promise<WalletAdapter>;
+type WalletId = WalletType | (string & {});
+```
+
+---
+
+### Custom adapters (`AdapterFn` / `PollarAdapter`)
+
+Generic adapter contract for wrapping external signing flows (e.g. Trustless Work SDK). Adapter functions receive
+params and return an unsigned XDR; the client handles signing and submission.
+
+```ts
+import type { AdapterFn, PollarAdapter, PollarAdapters } from '@pollar/core';
+
+const trustlessWork: PollarAdapter = {
+  initialize: (async (params) => ({ unsignedTransaction: '...' })) satisfies AdapterFn,
+  release:    (async (params) => ({ unsignedTransaction: '...' })) satisfies AdapterFn,
+};
+
+const adapters: PollarAdapters = { trustlessWork };
+```
+
+> **Renamed in 0.7.0** — `EscrowFn` → `AdapterFn` and `EscrowAdapter` → `PollarAdapter`. Runtime contract is unchanged;
+> rename your imports.
+
 ## TypeScript
 
 `@pollar/core` is written in TypeScript and ships full type declarations.
@@ -186,20 +395,45 @@ Key exported types:
 
 ```ts
 import type {
+  // Client
   PollarClientConfig,
   PollarLoginOptions,
-  PollarState,
-  PollarStateEntry,
-  StateAuthenticationCodes,
-  StateTransactionCodes,
-  StateNetworkCodes,
-  StateVarCodes,
+  PollarPersistedSession,
+  PollarUserProfile,
+  AuthState,
+  AuthErrorCode,
+
+  // Storage / keys / DPoP
+  Storage,
+  OnStorageDegrade,
+  StorageDegradeReason,
+  KeyManager,
+  PublicEcJwk,
+  BuildProofArgs,
+
+  // Sessions
+  SessionInfo,
+
+  // Wallets
+  WalletType,
+  WalletId,
+  WalletAdapter,
+  WalletAdapterResolver,
+
+  // Adapters (renamed from Escrow*)
+  AdapterFn,
+  PollarAdapter,
+  PollarAdapters,
+
+  // Stellar
   StellarNetwork,
+  StellarClientConfig,
   StellarBalance,
-  GetBalancesResult,
 } from '@pollar/core';
+
+import { AUTH_ERROR_CODES } from '@pollar/core';
 ```
 
 ## License
 
-MIT
+MIT

package/dist/adapters/expo-secure-store.d.mts

@@ -0,0 +1,26 @@
+import { S as Storage } from '../types-DqgJIJBl.mjs';
+
+/**
+ * Hard cap per stored value. Generously above what the SDK actually writes
+ * (sessions ≈ 600–800 bytes, private scalars ≈ 43 chars), and well within
+ * iOS Keychain's practical limit. Refuses oversized writes loudly rather
+ * than letting the platform truncate or silently fail.
+ */
+declare const SECURE_STORE_MAX_VALUE_BYTES = 4096;
+interface SecureStoreAdapterOptions {
+    /**
+     * Override the iOS Keychain accessibility class. Defaults to
+     * `WHEN_UNLOCKED_THIS_DEVICE_ONLY` when available on the loaded module.
+     * On Android this is a no-op (the platform manages access via Keystore).
+     */
+    keychainAccessible?: number;
+}
+/**
+ * Create a `Storage` adapter backed by Expo SecureStore.
+ *
+ * Throws synchronously (via the returned Promise) at construction time if
+ * `expo-secure-store` cannot be loaded.
+ */
+declare function createSecureStoreAdapter(options?: SecureStoreAdapterOptions): Promise<Storage>;
+
+export { SECURE_STORE_MAX_VALUE_BYTES, type SecureStoreAdapterOptions, createSecureStoreAdapter };

package/dist/adapters/expo-secure-store.d.ts

@@ -0,0 +1,26 @@
+import { S as Storage } from '../types-DqgJIJBl.js';
+
+/**
+ * Hard cap per stored value. Generously above what the SDK actually writes
+ * (sessions ≈ 600–800 bytes, private scalars ≈ 43 chars), and well within
+ * iOS Keychain's practical limit. Refuses oversized writes loudly rather
+ * than letting the platform truncate or silently fail.
+ */
+declare const SECURE_STORE_MAX_VALUE_BYTES = 4096;
+interface SecureStoreAdapterOptions {
+    /**
+     * Override the iOS Keychain accessibility class. Defaults to
+     * `WHEN_UNLOCKED_THIS_DEVICE_ONLY` when available on the loaded module.
+     * On Android this is a no-op (the platform manages access via Keystore).
+     */
+    keychainAccessible?: number;
+}
+/**
+ * Create a `Storage` adapter backed by Expo SecureStore.
+ *
+ * Throws synchronously (via the returned Promise) at construction time if
+ * `expo-secure-store` cannot be loaded.
+ */
+declare function createSecureStoreAdapter(options?: SecureStoreAdapterOptions): Promise<Storage>;
+
+export { SECURE_STORE_MAX_VALUE_BYTES, type SecureStoreAdapterOptions, createSecureStoreAdapter };

package/dist/adapters/expo-secure-store.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// src/adapters/expo-secure-store.ts
+var SECURE_STORE_MAX_VALUE_BYTES = 4096;
+async function loadSecureStore() {
+  try {
+    const mod = await import('expo-secure-store');
+    return mod;
+  } catch (error) {
+    const message = `[PollarClient:storage] Failed to load 'expo-secure-store'. Install it in your Expo app: \`npx expo install expo-secure-store\`. Original error: ${error instanceof Error ? error.message : String(error)}`;
+    throw new Error(message);
+  }
+}
+function utf8ByteLength(value) {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(value).length;
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < 128) bytes += 1;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 55296 && code <= 56319) {
+      bytes += 4;
+      i++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+async function createSecureStoreAdapter(options = {}) {
+  const SecureStore = await loadSecureStore();
+  const accessible = options.keychainAccessible !== void 0 ? options.keychainAccessible : SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY;
+  return {
+    async get(key) {
+      return SecureStore.getItemAsync(key);
+    },
+    async set(key, value) {
+      const size = utf8ByteLength(value);
+      if (size > SECURE_STORE_MAX_VALUE_BYTES) {
+        throw new Error(
+          `[PollarClient:storage] Value for "${key}" is ${size} bytes, exceeds SecureStore limit ${SECURE_STORE_MAX_VALUE_BYTES}`
+        );
+      }
+      await SecureStore.setItemAsync(key, value, accessible !== void 0 ? { keychainAccessible: accessible } : void 0);
+    },
+    async remove(key) {
+      await SecureStore.deleteItemAsync(key);
+    }
+  };
+}
+
+exports.SECURE_STORE_MAX_VALUE_BYTES = SECURE_STORE_MAX_VALUE_BYTES;
+exports.createSecureStoreAdapter = createSecureStoreAdapter;
+//# sourceMappingURL=expo-secure-store.js.map
+//# sourceMappingURL=expo-secure-store.js.map

package/dist/adapters/expo-secure-store.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/expo-secure-store.ts"],"names":[],"mappings":";;;AAqCO,IAAM,4BAAA,GAA+B;AAW5C,eAAe,eAAA,GAA2C;AACxD,EAAA,IAAI;AAGF,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,mBAAmB,CAAA;AAC5C,IAAA,OAAO,GAAA;AAAA,EACT,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,OAAA,GACJ,mJAEmB,KAAA,YAAiB,KAAA,GAAQ,MAAM,OAAA,GAAU,MAAA,CAAO,KAAK,CAAC,CAAA,CAAA;AAC3E,IAAA,MAAM,IAAI,MAAM,OAAO,CAAA;AAAA,EACzB;AACF;AAEA,SAAS,eAAe,KAAA,EAAuB;AAC7C,EAAA,IAAI,OAAO,gBAAgB,WAAA,EAAa,OAAO,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,KAAK,CAAA,CAAE,MAAA;AAE/E,EAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,QAAQ,CAAA,EAAA,EAAK;AACrC,IAAA,MAAM,IAAA,GAAO,KAAA,CAAM,UAAA,CAAW,CAAC,CAAA;AAC/B,IAAA,IAAI,IAAA,GAAO,KAAM,KAAA,IAAS,CAAA;AAAA,SAAA,IACjB,IAAA,GAAO,MAAO,KAAA,IAAS,CAAA;AAAA,SAAA,IACvB,IAAA,IAAQ,KAAA,IAAU,IAAA,IAAQ,KAAA,EAAQ;AAEzC,MAAA,KAAA,IAAS,CAAA;AACT,MAAA,CAAA,EAAA;AAAA,IACF,OAAO,KAAA,IAAS,CAAA;AAAA,EAClB;AACA,EAAA,OAAO,KAAA;AACT;AAQA,eAAsB,wBAAA,CAAyB,OAAA,GAAqC,EAAC,EAAqB;AACxG,EAAA,MAAM,WAAA,GAAc,MAAM,eAAA,EAAgB;AAE1C,EAAA,MAAM,aACJ,OAAA,CAAQ,kBAAA,KAAuB,MAAA,GAAY,OAAA,CAAQ,qBAAqB,WAAA,CAAY,8BAAA;AAEtF,EAAA,OAAO;AAAA,IACL,MAAM,IAAI,GAAA,EAAK;AACb,MAAA,OAAO,WAAA,CAAY,aAAa,GAAG,CAAA;AAAA,IACrC,CAAA;AAAA,IACA,MAAM,GAAA,CAAI,GAAA,EAAK,KAAA,EAAO;AACpB,MAAA,MAAM,IAAA,GAAO,eAAe,KAAK,CAAA;AACjC,MAAA,IAAI,OAAO,4BAAA,EAA8B;AACvC,QAAA,MAAM,IAAI,KAAA;AAAA,UACR,CAAA,kCAAA,EAAqC,GAAG,CAAA,KAAA,EAAQ,IAAI,qCAAqC,4BAA4B,CAAA;AAAA,SACvH;AAAA,MACF;AACA,MAAA,MAAM,WAAA,CAAY,YAAA,CAAa,GAAA,EAAK,KAAA,EAAO,UAAA,KAAe,SAAY,EAAE,kBAAA,EAAoB,UAAA,EAAW,GAAI,MAAS,CAAA;AAAA,IACtH,CAAA;AAAA,IACA,MAAM,OAAO,GAAA,EAAK;AAChB,MAAA,MAAM,WAAA,CAAY,gBAAgB,GAAG,CAAA;AAAA,IACvC;AAAA,GACF;AACF","file":"expo-secure-store.js","sourcesContent":["import type { Storage } from '../storage/types';\n\n/**\n * Adapter that persists session and key material in the iOS Keychain / Android\n * Keystore via [`expo-secure-store`](https://docs.expo.dev/versions/latest/sdk/securestore/).\n *\n * `expo-secure-store` is an optional peer dependency; install it in your Expo\n * project with `npx expo install expo-secure-store`.\n *\n * The module is loaded lazily via dynamic `import('expo-secure-store')` so web\n * bundlers strip the dependency from web builds entirely.\n */\n\n/**\n * Minimal structural type for the parts of `expo-secure-store` we use. We\n * type the surface here instead of importing the package's types because the\n * package is an optional peer dependency and may not be installed when this\n * SDK is type-checked (e.g. web-only consumers).\n */\ntype SecureStoreApi = {\n  getItemAsync: (key: string) => Promise<string | null>;\n  setItemAsync: (key: string, value: string, options?: { keychainAccessible?: number }) => Promise<void>;\n  deleteItemAsync: (key: string) => Promise<void>;\n  /**\n   * Default we use: requires the device to be unlocked and disables iCloud\n   * Keychain backup of the value (so a stolen iCloud backup cannot exfiltrate\n   * the SDK's private key material to another device).\n   */\n  WHEN_UNLOCKED_THIS_DEVICE_ONLY?: number;\n};\n\n/**\n * Hard cap per stored value. Generously above what the SDK actually writes\n * (sessions ≈ 600–800 bytes, private scalars ≈ 43 chars), and well within\n * iOS Keychain's practical limit. Refuses oversized writes loudly rather\n * than letting the platform truncate or silently fail.\n */\nexport const SECURE_STORE_MAX_VALUE_BYTES = 4096;\n\nexport interface SecureStoreAdapterOptions {\n  /**\n   * Override the iOS Keychain accessibility class. Defaults to\n   * `WHEN_UNLOCKED_THIS_DEVICE_ONLY` when available on the loaded module.\n   * On Android this is a no-op (the platform manages access via Keystore).\n   */\n  keychainAccessible?: number;\n}\n\nasync function loadSecureStore(): Promise<SecureStoreApi> {\n  try {\n    // @ts-ignore -- optional peer dep; not present when the SDK is built or\n    // when the SDK runs on web. Resolved at runtime in Expo / RN apps.\n    const mod = await import('expo-secure-store');\n    return mod as unknown as SecureStoreApi;\n  } catch (error) {\n    const message =\n      `[PollarClient:storage] Failed to load 'expo-secure-store'. ` +\n      `Install it in your Expo app: \\`npx expo install expo-secure-store\\`. ` +\n      `Original error: ${error instanceof Error ? error.message : String(error)}`;\n    throw new Error(message);\n  }\n}\n\nfunction utf8ByteLength(value: string): number {\n  if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(value).length;\n  // Fallback: count UTF-8 bytes manually for environments without TextEncoder.\n  let bytes = 0;\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i);\n    if (code < 0x80) bytes += 1;\n    else if (code < 0x800) bytes += 2;\n    else if (code >= 0xd800 && code <= 0xdbff) {\n      // Surrogate pair → 4 bytes; advance the index.\n      bytes += 4;\n      i++;\n    } else bytes += 3;\n  }\n  return bytes;\n}\n\n/**\n * Create a `Storage` adapter backed by Expo SecureStore.\n *\n * Throws synchronously (via the returned Promise) at construction time if\n * `expo-secure-store` cannot be loaded.\n */\nexport async function createSecureStoreAdapter(options: SecureStoreAdapterOptions = {}): Promise<Storage> {\n  const SecureStore = await loadSecureStore();\n\n  const accessible =\n    options.keychainAccessible !== undefined ? options.keychainAccessible : SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY;\n\n  return {\n    async get(key) {\n      return SecureStore.getItemAsync(key);\n    },\n    async set(key, value) {\n      const size = utf8ByteLength(value);\n      if (size > SECURE_STORE_MAX_VALUE_BYTES) {\n        throw new Error(\n          `[PollarClient:storage] Value for \"${key}\" is ${size} bytes, exceeds SecureStore limit ${SECURE_STORE_MAX_VALUE_BYTES}`,\n        );\n      }\n      await SecureStore.setItemAsync(key, value, accessible !== undefined ? { keychainAccessible: accessible } : undefined);\n    },\n    async remove(key) {\n      await SecureStore.deleteItemAsync(key);\n    },\n  };\n}\n"]}

package/dist/adapters/expo-secure-store.mjs

@@ -0,0 +1,50 @@
+// src/adapters/expo-secure-store.ts
+var SECURE_STORE_MAX_VALUE_BYTES = 4096;
+async function loadSecureStore() {
+  try {
+    const mod = await import('expo-secure-store');
+    return mod;
+  } catch (error) {
+    const message = `[PollarClient:storage] Failed to load 'expo-secure-store'. Install it in your Expo app: \`npx expo install expo-secure-store\`. Original error: ${error instanceof Error ? error.message : String(error)}`;
+    throw new Error(message);
+  }
+}
+function utf8ByteLength(value) {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(value).length;
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < 128) bytes += 1;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 55296 && code <= 56319) {
+      bytes += 4;
+      i++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+async function createSecureStoreAdapter(options = {}) {
+  const SecureStore = await loadSecureStore();
+  const accessible = options.keychainAccessible !== void 0 ? options.keychainAccessible : SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY;
+  return {
+    async get(key) {
+      return SecureStore.getItemAsync(key);
+    },
+    async set(key, value) {
+      const size = utf8ByteLength(value);
+      if (size > SECURE_STORE_MAX_VALUE_BYTES) {
+        throw new Error(
+          `[PollarClient:storage] Value for "${key}" is ${size} bytes, exceeds SecureStore limit ${SECURE_STORE_MAX_VALUE_BYTES}`
+        );
+      }
+      await SecureStore.setItemAsync(key, value, accessible !== void 0 ? { keychainAccessible: accessible } : void 0);
+    },
+    async remove(key) {
+      await SecureStore.deleteItemAsync(key);
+    }
+  };
+}
+
+export { SECURE_STORE_MAX_VALUE_BYTES, createSecureStoreAdapter };
+//# sourceMappingURL=expo-secure-store.mjs.map
+//# sourceMappingURL=expo-secure-store.mjs.map

package/dist/adapters/expo-secure-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/expo-secure-store.ts"],"names":[],"mappings":";AAqCO,IAAM,4BAAA,GAA+B;AAW5C,eAAe,eAAA,GAA2C;AACxD,EAAA,IAAI;AAGF,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,mBAAmB,CAAA;AAC5C,IAAA,OAAO,GAAA;AAAA,EACT,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,OAAA,GACJ,mJAEmB,KAAA,YAAiB,KAAA,GAAQ,MAAM,OAAA,GAAU,MAAA,CAAO,KAAK,CAAC,CAAA,CAAA;AAC3E,IAAA,MAAM,IAAI,MAAM,OAAO,CAAA;AAAA,EACzB;AACF;AAEA,SAAS,eAAe,KAAA,EAAuB;AAC7C,EAAA,IAAI,OAAO,gBAAgB,WAAA,EAAa,OAAO,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,KAAK,CAAA,CAAE,MAAA;AAE/E,EAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,QAAQ,CAAA,EAAA,EAAK;AACrC,IAAA,MAAM,IAAA,GAAO,KAAA,CAAM,UAAA,CAAW,CAAC,CAAA;AAC/B,IAAA,IAAI,IAAA,GAAO,KAAM,KAAA,IAAS,CAAA;AAAA,SAAA,IACjB,IAAA,GAAO,MAAO,KAAA,IAAS,CAAA;AAAA,SAAA,IACvB,IAAA,IAAQ,KAAA,IAAU,IAAA,IAAQ,KAAA,EAAQ;AAEzC,MAAA,KAAA,IAAS,CAAA;AACT,MAAA,CAAA,EAAA;AAAA,IACF,OAAO,KAAA,IAAS,CAAA;AAAA,EAClB;AACA,EAAA,OAAO,KAAA;AACT;AAQA,eAAsB,wBAAA,CAAyB,OAAA,GAAqC,EAAC,EAAqB;AACxG,EAAA,MAAM,WAAA,GAAc,MAAM,eAAA,EAAgB;AAE1C,EAAA,MAAM,aACJ,OAAA,CAAQ,kBAAA,KAAuB,MAAA,GAAY,OAAA,CAAQ,qBAAqB,WAAA,CAAY,8BAAA;AAEtF,EAAA,OAAO;AAAA,IACL,MAAM,IAAI,GAAA,EAAK;AACb,MAAA,OAAO,WAAA,CAAY,aAAa,GAAG,CAAA;AAAA,IACrC,CAAA;AAAA,IACA,MAAM,GAAA,CAAI,GAAA,EAAK,KAAA,EAAO;AACpB,MAAA,MAAM,IAAA,GAAO,eAAe,KAAK,CAAA;AACjC,MAAA,IAAI,OAAO,4BAAA,EAA8B;AACvC,QAAA,MAAM,IAAI,KAAA;AAAA,UACR,CAAA,kCAAA,EAAqC,GAAG,CAAA,KAAA,EAAQ,IAAI,qCAAqC,4BAA4B,CAAA;AAAA,SACvH;AAAA,MACF;AACA,MAAA,MAAM,WAAA,CAAY,YAAA,CAAa,GAAA,EAAK,KAAA,EAAO,UAAA,KAAe,SAAY,EAAE,kBAAA,EAAoB,UAAA,EAAW,GAAI,MAAS,CAAA;AAAA,IACtH,CAAA;AAAA,IACA,MAAM,OAAO,GAAA,EAAK;AAChB,MAAA,MAAM,WAAA,CAAY,gBAAgB,GAAG,CAAA;AAAA,IACvC;AAAA,GACF;AACF","file":"expo-secure-store.mjs","sourcesContent":["import type { Storage } from '../storage/types';\n\n/**\n * Adapter that persists session and key material in the iOS Keychain / Android\n * Keystore via [`expo-secure-store`](https://docs.expo.dev/versions/latest/sdk/securestore/).\n *\n * `expo-secure-store` is an optional peer dependency; install it in your Expo\n * project with `npx expo install expo-secure-store`.\n *\n * The module is loaded lazily via dynamic `import('expo-secure-store')` so web\n * bundlers strip the dependency from web builds entirely.\n */\n\n/**\n * Minimal structural type for the parts of `expo-secure-store` we use. We\n * type the surface here instead of importing the package's types because the\n * package is an optional peer dependency and may not be installed when this\n * SDK is type-checked (e.g. web-only consumers).\n */\ntype SecureStoreApi = {\n  getItemAsync: (key: string) => Promise<string | null>;\n  setItemAsync: (key: string, value: string, options?: { keychainAccessible?: number }) => Promise<void>;\n  deleteItemAsync: (key: string) => Promise<void>;\n  /**\n   * Default we use: requires the device to be unlocked and disables iCloud\n   * Keychain backup of the value (so a stolen iCloud backup cannot exfiltrate\n   * the SDK's private key material to another device).\n   */\n  WHEN_UNLOCKED_THIS_DEVICE_ONLY?: number;\n};\n\n/**\n * Hard cap per stored value. Generously above what the SDK actually writes\n * (sessions ≈ 600–800 bytes, private scalars ≈ 43 chars), and well within\n * iOS Keychain's practical limit. Refuses oversized writes loudly rather\n * than letting the platform truncate or silently fail.\n */\nexport const SECURE_STORE_MAX_VALUE_BYTES = 4096;\n\nexport interface SecureStoreAdapterOptions {\n  /**\n   * Override the iOS Keychain accessibility class. Defaults to\n   * `WHEN_UNLOCKED_THIS_DEVICE_ONLY` when available on the loaded module.\n   * On Android this is a no-op (the platform manages access via Keystore).\n   */\n  keychainAccessible?: number;\n}\n\nasync function loadSecureStore(): Promise<SecureStoreApi> {\n  try {\n    // @ts-ignore -- optional peer dep; not present when the SDK is built or\n    // when the SDK runs on web. Resolved at runtime in Expo / RN apps.\n    const mod = await import('expo-secure-store');\n    return mod as unknown as SecureStoreApi;\n  } catch (error) {\n    const message =\n      `[PollarClient:storage] Failed to load 'expo-secure-store'. ` +\n      `Install it in your Expo app: \\`npx expo install expo-secure-store\\`. ` +\n      `Original error: ${error instanceof Error ? error.message : String(error)}`;\n    throw new Error(message);\n  }\n}\n\nfunction utf8ByteLength(value: string): number {\n  if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(value).length;\n  // Fallback: count UTF-8 bytes manually for environments without TextEncoder.\n  let bytes = 0;\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i);\n    if (code < 0x80) bytes += 1;\n    else if (code < 0x800) bytes += 2;\n    else if (code >= 0xd800 && code <= 0xdbff) {\n      // Surrogate pair → 4 bytes; advance the index.\n      bytes += 4;\n      i++;\n    } else bytes += 3;\n  }\n  return bytes;\n}\n\n/**\n * Create a `Storage` adapter backed by Expo SecureStore.\n *\n * Throws synchronously (via the returned Promise) at construction time if\n * `expo-secure-store` cannot be loaded.\n */\nexport async function createSecureStoreAdapter(options: SecureStoreAdapterOptions = {}): Promise<Storage> {\n  const SecureStore = await loadSecureStore();\n\n  const accessible =\n    options.keychainAccessible !== undefined ? options.keychainAccessible : SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY;\n\n  return {\n    async get(key) {\n      return SecureStore.getItemAsync(key);\n    },\n    async set(key, value) {\n      const size = utf8ByteLength(value);\n      if (size > SECURE_STORE_MAX_VALUE_BYTES) {\n        throw new Error(\n          `[PollarClient:storage] Value for \"${key}\" is ${size} bytes, exceeds SecureStore limit ${SECURE_STORE_MAX_VALUE_BYTES}`,\n        );\n      }\n      await SecureStore.setItemAsync(key, value, accessible !== undefined ? { keychainAccessible: accessible } : undefined);\n    },\n    async remove(key) {\n      await SecureStore.deleteItemAsync(key);\n    },\n  };\n}\n"]}

package/dist/adapters/react-native-keychain.d.mts

@@ -0,0 +1,25 @@
+import { S as Storage } from '../types-DqgJIJBl.mjs';
+
+/**
+ * Hard cap per stored value. iOS Keychain has no formal byte limit but
+ * practical limits sit a few KB; we refuse oversized writes loudly.
+ */
+declare const KEYCHAIN_MAX_VALUE_BYTES = 4096;
+interface KeychainAdapterOptions {
+    /**
+     * Override the iOS Keychain accessibility class. Defaults to
+     * `ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY` when available on the loaded
+     * module — that prevents iCloud Keychain backup from carrying the SDK's
+     * private key material to another device.
+     */
+    accessible?: string;
+}
+/**
+ * Create a `Storage` adapter backed by `react-native-keychain`.
+ *
+ * Throws (via the returned Promise) at construction time if the package
+ * cannot be loaded.
+ */
+declare function createKeychainAdapter(options?: KeychainAdapterOptions): Promise<Storage>;
+
+export { KEYCHAIN_MAX_VALUE_BYTES, type KeychainAdapterOptions, createKeychainAdapter };

package/dist/adapters/react-native-keychain.d.ts

@@ -0,0 +1,25 @@
+import { S as Storage } from '../types-DqgJIJBl.js';
+
+/**
+ * Hard cap per stored value. iOS Keychain has no formal byte limit but
+ * practical limits sit a few KB; we refuse oversized writes loudly.
+ */
+declare const KEYCHAIN_MAX_VALUE_BYTES = 4096;
+interface KeychainAdapterOptions {
+    /**
+     * Override the iOS Keychain accessibility class. Defaults to
+     * `ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY` when available on the loaded
+     * module — that prevents iCloud Keychain backup from carrying the SDK's
+     * private key material to another device.
+     */
+    accessible?: string;
+}
+/**
+ * Create a `Storage` adapter backed by `react-native-keychain`.
+ *
+ * Throws (via the returned Promise) at construction time if the package
+ * cannot be loaded.
+ */
+declare function createKeychainAdapter(options?: KeychainAdapterOptions): Promise<Storage>;
+
+export { KEYCHAIN_MAX_VALUE_BYTES, type KeychainAdapterOptions, createKeychainAdapter };