@webority-technologies/mobile-core 0.0.1 → 0.0.2

package/README.md

@@ -9,7 +9,28 @@ version checks. **No UI** — components live in
 npm install @webority-technologies/mobile-core
 ```
 
-External runtime dependencies: `axios` and `axios-retry`. Every native peer is optional and lazily
+External runtime dependency: `axios`, and nothing else. `react-native-keychain` is a REQUIRED
+peer, because the HTTP client reads the bearer token. Every other native peer is optional and lazily
 required, so the package installs and runs without any of them.
 
 Full documentation lives in the repository's `docs/` directory.
+
+
+## Import paths
+
+Anything needing a native package lives behind its own path, so an app only bundles what it
+imports:
+
+```ts
+import { Permissions } from '@webority-technologies/mobile-core/permissions';
+import { Geolocation } from '@webority-technologies/mobile-core/geolocation';
+import { openDatabase } from '@webority-technologies/mobile-core/sqlite';
+import { downloadFile } from '@webority-technologies/mobile-core/download';
+import { compressImage } from '@webority-technologies/mobile-core/compressor';
+```
+
+Metro resolves requires statically, so anything reachable from the main barrel is bundled for
+every consumer. Keeping these off it is what makes their peers genuinely optional.
+
+Storage and network status stay on the main barrel but load no package on their own. Wire them at
+startup with `setStorageImplementation` and `setNetworkStatusImplementation` if you want them.

package/lib/commonjs/api/baseUrl.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.applyConfiguredBaseUrl = void 0;
+var _index = require("../config/index.js");
+/**
+ * Resolves `baseURL` PER REQUEST rather than at module evaluation.
+ *
+ * `axios.create({ baseURL: getConfigValue('baseUrl') })` reads the value once,
+ * when the module is first imported — which happens the moment anything touches
+ * the package barrel, long before an app's startup code can call `setConfig`.
+ * The result was a client permanently pinned to `undefined` and a `setConfig`
+ * that appeared to do nothing, with no error anywhere: requests just went to a
+ * relative URL.
+ *
+ * A consumer cannot fix that by ordering its own imports, because the import
+ * that loses the race is usually one it never wrote. So the clients stop
+ * capturing the value and ask for it per request instead.
+ *
+ * An explicit per-request `baseURL` still wins, which is what keeps a one-off
+ * call to a different host possible.
+ */
+const applyConfiguredBaseUrl = client => {
+  client.interceptors.request.use(config => {
+    if (!config.baseURL) {
+      config.baseURL = (0, _index.getConfigValue)('baseUrl') ?? undefined;
+    }
+    return config;
+  });
+};
+exports.applyConfiguredBaseUrl = applyConfiguredBaseUrl;
+//# sourceMappingURL=baseUrl.js.map

package/lib/commonjs/api/curl.js

@@ -0,0 +1,109 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.logCurl = exports.buildCurl = void 0;
+var _index = require("../logger/index.js");
+/**
+ * Header names whose VALUE is a credential. Matched case-insensitively against
+ * the whole name, since `Authorization` and `authorization` are the same header
+ * and axios does not normalise the case of headers a caller sets by hand.
+ */
+const SECRET_HEADERS = new Set(['authorization', 'proxy-authorization', 'cookie', 'set-cookie', 'x-api-key', 'x-auth-token', 'x-access-token', 'x-refresh-token', 'api-key']);
+
+/**
+ * Body fields whose value is a credential. Matched on the key alone, so this
+ * catches `password`, `newPassword` and `password_confirmation` alike.
+ */
+const SECRET_BODY_PATTERN = /pass(word|code)|secret|token|otp|pin|cvv|authoriz/i;
+
+/** The axios per-method header buckets, which are config plumbing, not headers. */
+const AXIOS_METHOD_KEYS = new Set(['common', 'delete', 'get', 'head', 'post', 'put', 'patch']);
+const REDACTED = '<redacted>';
+const redactBody = (value, seen, depth = 0) => {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  // Both guards are needed and they catch different shapes. `seen` breaks a
+  // true cycle, which would otherwise recurse forever AND make the eventual
+  // JSON.stringify throw. The depth bound catches a body that is merely
+  // enormous. A curl line is a debugging aid, and it must never be able to
+  // hang or fail the request it is describing.
+  if (seen.has(value)) {
+    return '<circular>';
+  }
+  if (depth > 6) {
+    return '<truncated>';
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map(entry => redactBody(entry, seen, depth + 1));
+  }
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    out[key] = SECRET_BODY_PATTERN.test(key) ? REDACTED : redactBody(entry, seen, depth + 1);
+  }
+  return out;
+};
+const buildUrl = config => {
+  const url = config.url ?? '';
+  const base = config.baseURL ? config.baseURL.replace(/\/$/, '') : '';
+  let complete = url.startsWith('http') ? url : `${base}/${url.replace(/^\//, '')}`;
+  if (config.params) {
+    const query = new URLSearchParams(config.params).toString();
+    if (query) {
+      complete += (complete.includes('?') ? '&' : '?') + query;
+    }
+  }
+  return complete;
+};
+
+/**
+ * Builds a copy-pasteable curl command for a request, with every credential
+ * replaced by a placeholder.
+ *
+ * The redaction is the point, not a nicety. An unredacted version of this in a
+ * consumer app put `Authorization: Bearer <token>` and the login request's
+ * plaintext password into the device console of a *release* staging build.
+ * A curl line is worth having; a curl line that has to be trusted not to be
+ * enabled in the wrong build is not.
+ */
+const buildCurl = config => {
+  const method = (config.method ?? 'get').toUpperCase();
+  let command = `curl -X ${method} "${buildUrl(config)}"`;
+  const headers = config.headers;
+  if (headers) {
+    for (const [key, value] of Object.entries(headers)) {
+      if (AXIOS_METHOD_KEYS.has(key)) {
+        continue;
+      }
+      if (typeof value !== 'string' && typeof value !== 'number') {
+        continue;
+      }
+      const shown = SECRET_HEADERS.has(key.toLowerCase()) ? REDACTED : value;
+      command += ` -H "${key}: ${shown}"`;
+    }
+  }
+  if (config.data !== undefined && config.data !== null) {
+    const redacted = typeof config.data === 'object' ? redactBody(config.data, new WeakSet()) : config.data;
+    const body = typeof redacted === 'object' ? JSON.stringify(redacted) : String(redacted);
+    command += ` -d '${body.replace(/'/g, "'\\''")}'`;
+  }
+  return command;
+};
+
+/**
+ * Logs the curl equivalent of a request. Never throws: a failure to describe a
+ * request must not be able to fail the request itself.
+ */
+exports.buildCurl = buildCurl;
+const logCurl = config => {
+  try {
+    _index.Logger.info('CURL Command:', buildCurl(config));
+  } catch (error) {
+    _index.Logger.warn('[api] Failed to build a curl command for the request', error);
+  }
+};
+exports.logCurl = logCurl;
+//# sourceMappingURL=curl.js.map

package/lib/commonjs/api/publicClient.js

@@ -5,9 +5,11 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _axios = _interopRequireDefault(require("axios"));
-var _axiosRetry = _interopRequireDefault(require("axios-retry"));
 var _index = require("../config/index.js");
 var _index2 = require("../logger/index.js");
+var _baseUrl = require("./baseUrl.js");
+var _curl = require("./curl.js");
+var _retry = require("./retry.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 // Define timeout for requests
 const REQUEST_TIMEOUT = 30000; // 30 seconds
@@ -20,7 +22,6 @@ const REQUEST_TIMEOUT = 30000; // 30 seconds
  * - Handles specific HTTP status codes.
  */
 const publicClient = _axios.default.create({
-  baseURL: (0, _index.getConfigValue)('baseUrl') ?? undefined,
   headers: {
     'Content-Type': 'application/json',
     Accept: 'application/json',
@@ -28,29 +29,19 @@ const publicClient = _axios.default.create({
   },
   timeout: REQUEST_TIMEOUT
 });
+(0, _baseUrl.applyConfiguredBaseUrl)(publicClient);
 
-// Configure axios-retry with modified exponential backoff
-const retryConfig = {
-  retries: 3,
-  retryDelay: retryCount => retryCount === 0 ? 0 : Math.pow(2, retryCount) * 1000,
-  // Immediate retry for the first attempt
-  retryCondition: error => {
-    // Status-based ONLY, deliberately: a bare network error must never be
-    // retried here. This client carries login and OTP, which are not
-    // idempotent — the request may well have reached the server before the
-    // connection broke, so a retry can create a second session the user never
-    // sees. axios-retry's isNetworkOrIdempotentRequestError does NOT protect
-    // against this: its isNetworkError branch never looks at the HTTP method,
-    // so it retried POSTs too.
-    const status = error.response?.status;
-    return typeof status === 'number' && (status === 429 || status >= 500 && status <= 599);
-  }
-};
-(0, _axiosRetry.default)(publicClient, retryConfig);
+// Registered before the logging interceptors below so they only ever observe
+// the final outcome of a request, not its intermediate retries. The policy
+// itself, and why a bare network error is never retried, lives in ./retry.
+(0, _retry.attachRetry)(publicClient);
 
 // Add request interceptor for logging
 publicClient.interceptors.request.use(config => {
   _index2.Logger.info(`Request: ${config.method?.toUpperCase()} ${config.url}`);
+  if ((0, _index.getConfigValue)('logCurl')) {
+    (0, _curl.logCurl)(config);
+  }
   return config;
 }, error => {
   const message = error instanceof Error ? error.message : String(error);

package/lib/commonjs/api/retry.js

@@ -0,0 +1,75 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isRetryableStatus = exports.attachRetry = void 0;
+/**
+ * Status-based ONLY, deliberately: a bare network error (no `error.response`)
+ * is never retryable. Both clients carry non-idempotent requests, login and OTP
+ * on the public one and every write on the user one, and a broken connection
+ * says nothing about whether the request reached the server. Retrying can
+ * therefore create a second session, or a duplicate record, that the user never
+ * sees. A generic network-error retry rule is not a substitute: it decides on
+ * the transport alone and never looks at the HTTP method, so it retries POSTs
+ * as readily as GETs.
+ */
+const isRetryableStatus = status => typeof status === 'number' && (status === 429 || status >= 500 && status <= 599);
+exports.isRetryableStatus = isRetryableStatus;
+const DEFAULT_POLICY = {
+  retries: 3,
+  retryDelayMs: attempt => attempt <= 1 ? 0 : 2 ** attempt * 1000,
+  shouldRetry: error => isRetryableStatus(error.response?.status),
+  onRetry: () => undefined
+};
+const waitOrAbort = (delay, signal) => new Promise(resolve => {
+  const onAbort = () => {
+    clearTimeout(timer);
+    resolve(false);
+  };
+  const timer = setTimeout(() => {
+    signal?.removeEventListener?.('abort', onAbort);
+    resolve(true);
+  }, delay);
+  signal?.addEventListener?.('abort', onAbort, {
+    once: true
+  });
+});
+const attachRetry = (client, policy = {}) => {
+  client.interceptors.response.use(undefined, async error => {
+    const axiosError = error;
+    const config = axiosError?.config;
+    if (!config || config.retry === false) {
+      return Promise.reject(error);
+    }
+    const perRequest = typeof config.retry === 'object' ? config.retry : {};
+    const effective = {
+      ...DEFAULT_POLICY,
+      ...policy,
+      ...perRequest
+    };
+    const attempt = (config.__retryAttempt ?? 0) + 1;
+    if (attempt > effective.retries || !effective.shouldRetry(axiosError)) {
+      return Promise.reject(error);
+    }
+    if (config.signal?.aborted) {
+      return Promise.reject(error);
+    }
+
+    // The attempt count rides on the config, which axios copies onto the config
+    // of the retried request, so nested attempts continue the same count and
+    // separate requests never share one.
+    config.__retryAttempt = attempt;
+    // The body was serialised by the first pass; transforming it again would
+    // JSON-encode the already-encoded string.
+    config.transformRequest = [data => data];
+    effective.onRetry(attempt, axiosError);
+    const proceed = await waitOrAbort(effective.retryDelayMs(attempt), config.signal);
+    if (!proceed) {
+      return Promise.reject(error);
+    }
+    return client.request(config);
+  });
+};
+exports.attachRetry = attachRetry;
+//# sourceMappingURL=retry.js.map

package/lib/commonjs/api/userClient.js

@@ -3,14 +3,15 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.injectStore = exports.injectAuthActions = exports.default = exports.SESSION_TERMINATION_CODES = exports.SESSION_INVALID_HEADER = exports.RequestOfflineError = void 0;
+exports.resetRefreshState = exports.injectStore = exports.injectAuthActions = exports.default = exports.SESSION_TERMINATION_CODES = exports.SESSION_INVALID_HEADER = exports.RequestOfflineError = void 0;
 var _axios = _interopRequireWildcard(require("axios"));
-var _axiosRetry = _interopRequireDefault(require("axios-retry"));
 var _authStore = require("../auth/authStore.js");
 var _index = require("../config/index.js");
 var _index2 = require("../logger/index.js");
 var _networkStatus = require("../network/networkStatus.js");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _baseUrl = require("./baseUrl.js");
+var _curl = require("./curl.js");
+var _retry = require("./retry.js");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 // Define timeout for requests
 const REQUEST_TIMEOUT = 30000; // 30 seconds
@@ -85,7 +86,6 @@ const getSessionTerminationCode = data => {
  */
 
 const userClient = _axios.default.create({
-  baseURL: (0, _index.getConfigValue)('baseUrl') ?? undefined,
   headers: {
     'Content-Type': 'application/json',
     'Accept-Encoding': 'gzip, deflate, br'
@@ -93,19 +93,10 @@ const userClient = _axios.default.create({
   timeout: REQUEST_TIMEOUT // Set timeout for all requests
 });
 
-// Configure axios-retry with modified exponential backoff
-(0, _axiosRetry.default)(userClient, {
-  retries: 3,
-  retryDelay: retryCount => retryCount === 0 ? 0 : Math.pow(2, retryCount) * 1000,
-  // Immediate retry for the first attempt
-  retryCondition: error => {
-    // Status-based ONLY — see publicClient for the reasoning. A bare network
-    // error carries no response, so it is not retried: the write may already
-    // have landed server-side, and this client issues non-idempotent requests.
-    const status = error.response?.status;
-    return typeof status === 'number' && (status === 429 || status >= 500 && status <= 599);
-  }
-});
+// Registered before the auth interceptors below, so a retryable 5xx is retried
+// before anything else sees it while a 401 still falls through to the refresh
+// flow. Policy and reasoning live in ./retry.
+(0, _retry.attachRetry)(userClient);
 let store;
 let authActions = {
   logout: () => undefined,
@@ -145,6 +136,22 @@ const processQueue = (error, token = null) => {
   });
   failedQueue = [];
 };
+
+/**
+ * Clear any in-flight token refresh and reject everything queued behind it.
+ * Call this on logout.
+ *
+ * Without it, a refresh that was already in flight when the user logged out
+ * resolves afterwards and replays every queued request with a token for a
+ * session that has ended. The queue is module state, so it survives the logout
+ * entirely: nothing else clears it. A consumer app hit this and hand-wrote the
+ * same function locally, which is how it was found.
+ */
+const resetRefreshState = () => {
+  refreshTokenPromise = null;
+  processQueue(new Error('[@webority-technologies/mobile-core] Session ended'));
+};
+exports.resetRefreshState = resetRefreshState;
 const getErrorMessage = error => {
   if (error instanceof Error) {
     return error.message;
@@ -175,6 +182,23 @@ const requireStore = () => {
 /**
  * Attach Authorization Token Before Requests
  */
+// Registered after the curl logger and before the auth interceptor, so that it
+// RUNS between them: axios unshifts its request chain, making the first
+// registered run last. The curl line therefore describes a request that already
+// has both its baseURL and its Authorization header.
+(0, _baseUrl.applyConfiguredBaseUrl)(userClient);
+
+// Registered BEFORE the auth interceptor below deliberately. Axios builds its
+// request chain by unshifting, so the FIRST-registered request interceptor runs
+// LAST — closest to dispatch. This one therefore observes the final config,
+// with the Authorization header already attached, which is the whole point of
+// a curl line. Registering it after would log the request before it is signed.
+userClient.interceptors.request.use(config => {
+  if ((0, _index.getConfigValue)('logCurl')) {
+    (0, _curl.logCurl)(config);
+  }
+  return config;
+});
 userClient.interceptors.request.use(async config => {
   // Reject before any network call when the device is known to be offline.
   // Unknown connectivity (netinfo not installed, or undetermined) is treated
@@ -189,7 +213,7 @@ userClient.interceptors.request.use(async config => {
     if (config.url?.includes('/Account/RefreshToken')) {
       return config;
     }
-    const token = await (0, _authStore.getToken)('accessToken');
+    const token = await (0, _authStore.getToken)(_authStore.ACCESS_TOKEN_KEY);
 
     // Check if token exists
     if (!token?.token) {
@@ -221,7 +245,7 @@ userClient.interceptors.request.use(async config => {
       // Start a new token refresh process
       refreshTokenPromise = (async () => {
         try {
-          const refreshToken = await (0, _authStore.getToken)('refreshToken');
+          const refreshToken = await (0, _authStore.getToken)(_authStore.REFRESH_TOKEN_KEY);
           if (!refreshToken?.token) {
             _index2.Logger.error('No refresh token available');
             throw new Error('No refresh token available');
@@ -239,7 +263,7 @@ userClient.interceptors.request.use(async config => {
           if (refreshResult.error) {
             throw new Error(`Token refresh failed: ${refreshResult.error.message || 'Unknown error'}`);
           }
-          const newAccessToken = await (0, _authStore.getToken)('accessToken');
+          const newAccessToken = await (0, _authStore.getToken)(_authStore.ACCESS_TOKEN_KEY);
           if (!newAccessToken?.token) {
             throw new Error('Failed to retrieve new access token after refresh');
           }
@@ -322,7 +346,7 @@ userClient.interceptors.response.use(response => response, async error => {
     refreshTokenPromise = (async () => {
       try {
         _index2.Logger.info('User Client: Refreshing token...');
-        const refreshToken = await (0, _authStore.getToken)('refreshToken');
+        const refreshToken = await (0, _authStore.getToken)(_authStore.REFRESH_TOKEN_KEY);
         if (!refreshToken || !refreshToken.token) {
           _index2.Logger.error('No refresh token available or token is invalid');
           throw new Error('No refresh token available');
@@ -335,7 +359,7 @@ userClient.interceptors.response.use(response => response, async error => {
           throw new Error(`Token refresh failed: ${refreshResult.error.message || 'Unknown error'}`);
         }
         _index2.Logger.info('Getting new access token after refresh');
-        const newAccessToken = await (0, _authStore.getToken)('accessToken');
+        const newAccessToken = await (0, _authStore.getToken)(_authStore.ACCESS_TOKEN_KEY);
         if (!newAccessToken?.token) {
           throw new Error('Failed to retrieve new access token');
         }

package/lib/commonjs/auth/authStore.js

@@ -3,39 +3,85 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.storeToken = exports.setKeychainImplementation = exports.removeToken = exports.getToken = void 0;
+exports.storeToken = exports.setKeychainImplementation = exports.removeToken = exports.getToken = exports.REFRESH_TOKEN_KEY = exports.ACCESS_TOKEN_KEY = void 0;
+var SecureStore = _interopRequireWildcard(require("expo-secure-store"));
 var _index = require("../logger/index.js");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /**
  * Token data persisted in the keychain.
  */
+/**
+ * The two keys the library itself reads. Everything in the library that needs
+ * the bearer token, the HTTP client, the download module and the authenticated
+ * image cache, resolves it through these rather than repeating the literal, so
+ * one of them cannot silently drift and start reading a key nothing writes.
+ * Apps are free to store their own tokens under any other key.
+ */
+const ACCESS_TOKEN_KEY = exports.ACCESS_TOKEN_KEY = 'accessToken';
+const REFRESH_TOKEN_KEY = exports.REFRESH_TOKEN_KEY = 'refreshToken';
 
 /**
  * Minimal keychain shape we depend on.
  * Lets us avoid a hard import on `react-native-keychain`, so an app that never
  * stores a token does not have to install it.
  */
+/**
+ * The GENERIC password API, not the internet-credentials one.
+ *
+ * `kSecClassInternetPassword` exists for credentials bound to a server, protocol
+ * and port, and it integrates with Safari and AutoFill. A bearer token keyed by
+ * a name like "accessToken" is none of those things, and the library was only
+ * satisfying that API's required `server` argument by passing the key twice,
+ * once as the server and once as the service. That is misuse of the class.
+ *
+ * `kSecClassGenericPassword` is the class for app-local secrets, which is what a
+ * token is. It is what expo-secure-store uses underneath, and what the consumer
+ * app being migrated had already chosen for itself.
+ */
 
+// Only what a test or the showcase injected; null means use expo-secure-store.
 let backend = null;
-let resolved = false;
-const resolveBackend = () => {
-  if (resolved) {
-    return backend;
-  }
-  resolved = true;
-  try {
-    const mod = require('react-native-keychain');
-    // Prefer named exports: the real module and the test mock both expose them
-    // flat, while `default` is a differently-shaped convenience object.
-    backend = typeof mod?.setInternetCredentials === 'function' ? mod : mod?.default;
-  } catch {
-    backend = null;
+
+/**
+ * expo-secure-store, adapted to the generic-password shape this module speaks.
+ *
+ * It is a flat key/value store, so the credential shape is reconstructed around
+ * it. The key is sanitised because expo rejects anything outside
+ * [A-Za-z0-9._-] at runtime, which would otherwise surface as a throw from deep
+ * inside the store rather than as a bad key.
+ */
+const keyFor = service => (service ?? 'default').replace(/[^A-Za-z0-9._-]/g, '_');
+const expoSecureStoreBackend = {
+  setGenericPassword: async (username, password, options) => {
+    await SecureStore.setItemAsync(keyFor(options?.service), JSON.stringify({
+      username,
+      password
+    }));
+    return true;
+  },
+  getGenericPassword: async options => {
+    const service = options?.service;
+    const raw = await SecureStore.getItemAsync(keyFor(service));
+    if (raw === null) {
+      return false;
+    }
+    const parsed = JSON.parse(raw);
+    return {
+      username: parsed.username,
+      password: parsed.password,
+      service: service ?? 'default'
+    };
+  },
+  resetGenericPassword: async options => {
+    await SecureStore.deleteItemAsync(keyFor(options?.service));
+    return true;
   }
-  return backend;
 };
+const resolveBackend = () => backend ?? expoSecureStoreBackend;
 const requireBackend = op => {
   const b = resolveBackend();
   if (!b) {
-    const err = new Error(`[authStore] react-native-keychain is not installed; cannot ${op}. ` + 'Install the peer dep or call setKeychainImplementation() with a custom backend.');
+    const err = new Error(`[authStore] no secure-store backend available; cannot ${op}.`);
     _index.Logger.error(err.message);
     throw err;
   }
@@ -43,12 +89,12 @@ const requireBackend = op => {
 };
 
 /**
- * Inject a custom keychain backend at runtime.
- * Pass `null` to reset to the default react-native-keychain backend.
+ * Replace the secure-store backend. Intended for TESTS and for the showcase,
+ * which injects a failing store to demo the write-failure path; it is not how
+ * an app configures the library. Pass `null` to restore expo-secure-store.
  */
 const setKeychainImplementation = impl => {
   backend = impl;
-  resolved = impl !== null;
 };
 
 /**
@@ -64,9 +110,9 @@ const storeToken = async (key, token, expiry) => {
       token,
       expiry
     });
-    await requireBackend('store a token').setInternetCredentials(key, 'token', data, {
+    await requireBackend('store a token').setGenericPassword('token', data, {
       service: key
-    }); // Ensure service matches
+    });
     _index.Logger.info(`Token stored successfully for key: ${key}`);
   } catch (error) {
     // Log AND rethrow. Swallowing this told the caller the token was persisted
@@ -95,8 +141,10 @@ const parseTokenData = credentials => {
       return parsed;
     }
     return null;
-  } catch (error) {
-    _index.Logger.error('Failed to parse token data', error);
+  } catch {
+    // The single report for "stored, but not a token" belongs to getToken, which
+    // knows whether anything was stored at all. Logging here too made one event
+    // arrive twice, at two different levels.
     return null;
   }
 };
@@ -105,31 +153,43 @@ const parseTokenData = credentials => {
  * Retrieve token and check if expired.
  */
 const getToken = async key => {
-  _index.Logger.info(`Retrieving token for key: ${key}`);
   try {
-    const credentials = await requireBackend('read a token').getInternetCredentials(key, {
+    const credentials = await requireBackend('read a token').getGenericPassword({
       service: key
-    }); // Ensure service matches
+    });
+    // Nothing stored is an ORDINARY state, not a fault: a signed-out user has no
+    // token, and every authenticated request, image and download asks for one.
+    // Warning here put three info lines and a warning into the log, and into the
+    // remote crash sink, on every one of those calls.
+    if (!credentials) {
+      return null;
+    }
     const parsedData = parseTokenData(credentials);
-    _index.Logger.info(`Parsed token data for key: ${key}: ${parsedData ? 'present' : 'absent'}`);
     if (!parsedData) {
-      _index.Logger.warn(`Invalid or no token data found for key: ${key}`);
+      // Something IS stored and it is not a token. That is corruption worth
+      // hearing about, and it is a different event from having no token.
+      _index.Logger.warn(`Stored credentials for key "${key}" are not a valid token; ignoring them.`);
       return null;
     }
     const {
       token,
       expiry
     } = parsedData;
-    _index.Logger.info(`Token retrieved for key: ${key}`);
     return {
       token,
       expiry
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    if (message.includes('Key permanently invalidated')) {
-      _index.Logger.error(`Key permanently invalidated for key: ${key}. Clearing the invalidated key.`);
-      await removeToken(key); // Clear the invalidated key
+    // Both spellings matter. Android throws "Key permanently invalidated" when
+    // the biometric enrolment changes; iOS throws "Secret invalidated" for the
+    // equivalent. Either way the stored value can never be decrypted again, so
+    // clearing it is the only way out: leaving it makes every later read fail
+    // identically, and the user is stuck with no route back to a login. A
+    // consumer app handled the iOS spelling and the library did not.
+    if (message.includes('Key permanently invalidated') || message.includes('Secret invalidated')) {
+      _index.Logger.error(`Stored token for key "${key}" can no longer be decrypted; clearing it.`);
+      await removeToken(key);
       return null;
     }
     _index.Logger.error(`Error retrieving token for key: ${key}`, error);
@@ -143,11 +203,19 @@ const getToken = async key => {
 exports.getToken = getToken;
 const removeToken = async key => {
   try {
-    await requireBackend('remove a token').resetInternetCredentials({
+    await requireBackend('remove a token').resetGenericPassword({
       service: key
     });
     _index.Logger.info(`Token removed successfully for key: ${key}`);
   } catch (error) {
+    // Clearing a key that was never written is the ordinary logout path, not a
+    // failure: only one of the two tokens may ever have been stored. Logging it
+    // as an error puts routine traffic in the channel people watch for real
+    // problems, which is how an error channel stops being watched.
+    if (error instanceof Error && error.message.includes('Item not found')) {
+      _index.Logger.info(`No token found to remove for key: ${key}`);
+      return;
+    }
     _index.Logger.error(`Failed to remove token for key: ${key}`, error);
   }
 };