@oxy.so/core 1.6.1 → 1.7.1

package/dist/esm/HttpService.js

@@ -15,7 +15,7 @@
 import { TTLCache, registerCacheForCleanup } from './utils/cache.js';
 import { RequestDeduplicator, RequestQueue, SimpleLogger } from './utils/requestUtils.js';
 import { retryAsync } from './utils/asyncUtils.js';
-import { handleHttpError, parseHttpErrorBody } from './utils/errorUtils.js';
+import { createCancelledError, ErrorCodes, handleHttpError, parseHttpErrorBody } from './utils/errorUtils.js';
 import { jwtDecode } from 'jwt-decode';
 import { isNative, getPlatformOS } from './utils/platform.js';
 import { isReactNative } from '@oxy.so/protocol';
@@ -170,6 +170,41 @@ class TokenStore {
         this.csrfTokenFetchPromise = null;
     }
 }
+/**
+ * Propagate `parent`'s abort to `child`, returning a disposer.
+ *
+ * Three things a bare `parent.addEventListener('abort', ...)` gets wrong, all
+ * of which this exists to stop repeating:
+ *
+ * 1. **An already-aborted parent never fires again.** `abort` is a once-only
+ *    event, so linking to a signal that has already fired silently links to
+ *    nothing — which is how a cancelled request got re-issued on every retry.
+ *    The `aborted` pre-check is the whole point.
+ * 2. **The listener outlives the request.** A long-lived caller signal (one
+ *    React Query owns for a query's lifetime, say) accumulates one listener per
+ *    attempt per request with nothing ever removing them.
+ * 3. **The reason is dropped**, so the child cannot tell WHY it was aborted.
+ *
+ * `AbortSignal.any` does all this natively and is not used: Hermes support is
+ * not safe to assume, and this SDK ships to React Native. The pattern is the
+ * one `uploadViaXHR` already had right; this is that code, shared.
+ */
+function isAbortLike(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.name === 'AbortError');
+}
+function linkAbort(parent, child) {
+    if (parent.aborted) {
+        child.abort(parent.reason);
+        return () => { };
+    }
+    const onAbort = () => {
+        child.abort(parent.reason);
+    };
+    parent.addEventListener('abort', onAbort, { once: true });
+    return () => parent.removeEventListener('abort', onAbort);
+}
 /**
  * Unified HTTP Service
  *
@@ -365,21 +400,59 @@ export class HttpService {
         const csrfToken = isStateChangingMethod && !authHeader ? await this.fetchCsrfToken() : null;
         const edgeRegionHeader = await getBrowserEdgeRegionHeader();
         const activityIdHeader = getBrowserActivityIdHeader();
+        // A request the caller has ALREADY abandoned takes no queue slot and makes
+        // no network call. Checked here, before enqueue, because a slot is the
+        // scarce resource: ten of them, and a dead request holding one is a live
+        // request waiting for nothing.
+        if (signal?.aborted) {
+            throw createCancelledError('Request cancelled before it was sent');
+        }
+        // ONE abort domain for the whole call, linked to the caller's signal ONCE.
+        //
+        // The bug this replaces: the controller used to be built INSIDE `requestFn`
+        // — the function `retryAsync` re-invokes — and the caller's signal was
+        // linked to each new controller with a bare `addEventListener`. An `abort`
+        // event fires once, so on attempt 2 the caller's already-fired signal could
+        // not abort the freshly built controller, and the request the caller had
+        // cancelled went out for real. Hoisting the linkage means a cancellation
+        // arrives once and is then true for every attempt, including ones not yet
+        // started.
+        const callController = new AbortController();
+        const disposeCallerLink = signal ? linkAbort(signal, callController) : undefined;
+        /**
+         * Which of our own timers fired, so a timeout can be told apart from a
+         * cancellation. Both reach us from `fetch` as an indistinguishable
+         * `AbortError`, and collapsing them (as this used to) is what let the retry
+         * predicate treat an abandoned request as a transient failure.
+         */
+        let timedOut = false;
         // Request function
         const requestFn = async () => {
             const startTime = Date.now();
+            // Re-checked per attempt so no retry can issue a network call after the
+            // caller gave up — belt to `retryAsync`'s braces, and the one that holds
+            // if a custom `shouldRetry` ever says yes to a cancellation.
+            if (callController.signal.aborted) {
+                throw createCancelledError('Request cancelled');
+            }
+            // This attempt's controller carries its own timeout and inherits the
+            // call-wide abort domain. Declared OUTSIDE the `try` so the `finally`
+            // that releases them can see them — the timer and the listener are
+            // exactly what leaked when they lived inside it.
+            const controller = new AbortController();
+            const disposeCallLink = linkAbort(callController.signal, controller);
+            const timeoutId = timeout
+                ? setTimeout(() => {
+                    timedOut = true;
+                    controller.abort();
+                }, timeout)
+                : null;
             try {
                 // Build URL with params
                 const fullUrl = this.buildURL(url, params);
                 // Determine if data is FormData using robust detection
                 const isFormData = this.isFormData(data);
                 const isUrlEncoded = this.isUrlSearchParams(data);
-                // Make fetch request
-                const controller = new AbortController();
-                const timeoutId = timeout ? setTimeout(() => controller.abort(), timeout) : null;
-                if (signal) {
-                    signal.addEventListener('abort', () => controller.abort());
-                }
                 // Build headers - start with defaults
                 const headers = {
                     'Accept': 'application/json',
@@ -457,6 +530,8 @@ export class HttpService {
                         signal: controller.signal,
                         credentials: this.getCredentialsMode(fullUrl),
                     });
+                // Cleared as early as possible; the `finally` below is what GUARANTEES
+                // it, including on every throw between here and there.
                 if (timeoutId)
                     clearTimeout(timeoutId);
                 // Handle response
@@ -582,34 +657,82 @@ export class HttpService {
                 this.updateMetrics(false, duration);
                 this.config.onRequestEnd?.(url, method, duration, false);
                 this.config.onRequestError?.(url, method, error instanceof Error ? error : new Error(String(error)));
-                // Handle AbortError specifically for better error messages
-                if (error instanceof Error && error.name === 'AbortError') {
-                    throw handleHttpError(error);
+                // An abort is the one failure whose CAUSE the error cannot carry on its
+                // own: `fetch` reports a caller cancellation and our own timeout as the
+                // same `AbortError`. `timedOut` is set by the timer callback, so it is
+                // the only thing here that knows which happened — and getting this
+                // wrong is not cosmetic. Both used to collapse to `TIMEOUT` with
+                // `status: 0`, and because `status: 0` is not 4xx the retry predicate
+                // read every cancellation as a transient failure worth another try.
+                // Tested by NAME, not `instanceof Error`. `fetch` rejects an abort with a
+                // `DOMException`, and `instanceof` is realm-bound: the exception can be
+                // constructed in a different realm from the `Error` this module closes
+                // over (a Jest VM context, a worker, an iframe), in which case the check
+                // silently fails and the abort is misreported as a generic 500. That was
+                // happening; a structural check cannot be fooled that way.
+                if (isAbortLike(error)) {
+                    if (timedOut) {
+                        const timeoutError = new Error(`Request timed out after ${timeout}ms`);
+                        timeoutError.status = 0;
+                        timeoutError.code = ErrorCodes.TIMEOUT;
+                        timeoutError.timeout = true;
+                        throw timeoutError;
+                    }
+                    throw createCancelledError('Request cancelled');
                 }
                 throw handleHttpError(error);
             }
+            finally {
+                // Both of these leaked before: `clearTimeout` sat on the success path
+                // only, so any throw between the fetch and the return (a 404, a parse
+                // failure) left the timer armed; and nothing ever removed the abort
+                // listener, so a long-lived caller signal collected one per attempt.
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                disposeCallLink();
+            }
         };
-        // Wrap with retry if enabled
+        // Wrap with retry if enabled.
+        //
+        // `retryOnTimeout` defaults to false in `retryAsync`, which is what makes
+        // the pathological total unreachable: a timeout now costs ONE attempt
+        // instead of four-plus-backoff (~28s at the 5s default), and a cancellation
+        // costs none. `deadline` bounds whatever retries do happen by wall clock
+        // rather than by attempts x timeout + backoff.
         const requestWithRetry = retry
-            ? () => retryAsync(requestFn, maxRetries, this.config.retryDelay || 1000)
+            ? () => retryAsync(requestFn, {
+                maxRetries,
+                baseDelay: this.config.retryDelay || 1000,
+                retryOnTimeout: config.retryOnTimeout ?? false,
+                deadline: config.deadline !== undefined ? Date.now() + config.deadline : undefined,
+            })
             : requestFn;
         // Wrap with deduplication if enabled (use optimized key generation)
         const dedupeKey = deduplicate ? this.generateCacheKey(method, url, data || params) : null;
         const finalRequest = dedupeKey
-            ? () => this.deduplicator.deduplicate(dedupeKey, requestWithRetry)
+            ? () => this.deduplicator.deduplicate(dedupeKey, requestWithRetry, callController.signal)
             : requestWithRetry;
-        // Execute the request. Control-plane calls the auth lane depends on
-        // (`bypassQueue`, e.g. the device-secret mint) run DIRECTLY — a queued mint
-        // could never acquire a slot when every slot is parked awaiting it.
-        const result = config.bypassQueue
-            ? await finalRequest()
-            : await this.requestQueue.enqueue(finalRequest);
-        // Cache the result if caching is enabled
-        if (cache && cacheKey && result) {
-            this.cache.set(cacheKey, result, cacheTTL);
-            this.warnIfCacheOversized();
+        try {
+            // Execute the request. Control-plane calls the auth lane depends on
+            // (`bypassQueue`, e.g. the device-secret mint) run DIRECTLY — a queued mint
+            // could never acquire a slot when every slot is parked awaiting it.
+            const result = config.bypassQueue
+                ? await finalRequest()
+                : await this.requestQueue.enqueue(finalRequest, callController.signal);
+            // Cache the result if caching is enabled
+            if (cache && cacheKey && result) {
+                this.cache.set(cacheKey, result, cacheTTL);
+                this.warnIfCacheOversized();
+            }
+            return result;
+        }
+        finally {
+            // The call-wide link to the CALLER's signal, released once the call is
+            // over however it ended. Without this a caller signal that outlives the
+            // request — the normal case for a React Query query signal — accrues one
+            // listener per request for its whole lifetime.
+            disposeCallerLink?.();
         }
-        return result;
     }
     /**
      * Soft cache-size guard. Emits a single throttled telemetry warning when the

package/dist/esm/crypto/registrationPow.js

@@ -0,0 +1,50 @@
+/**
+ * Registration proof-of-work — the CLIENT half of the anti-automation nonce
+ * `register()` (`mixins/OxyServices.auth.ts`) submits alongside the
+ * registration signature. The message format, difficulty and the full design
+ * rationale (why 16 bits, why sequential nonces are fine, what this is and
+ * isn't a defense against) live in `@oxy.so/protocol`'s
+ * `auth/registrationPow.ts` — this file is only the solve loop.
+ */
+import './polyfill.js';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils';
+import { meetsRegistrationPowDifficulty, registrationPowMessage, REGISTRATION_POW_DIFFICULTY_BITS, } from '@oxy.so/protocol';
+/**
+ * How many attempts the grind loop runs before yielding to the event loop.
+ *
+ * A synchronous hot loop long enough to matter (an average solve at 16 bits
+ * is 65,536 attempts) would otherwise block the JS thread for its entire
+ * duration — on a mobile app that means no touch response, no animation, for
+ * up to roughly a second. Yielding periodically keeps the UI responsive
+ * during the grind at the cost of a handful of event-loop round trips, which
+ * is imperceptible next to the grind itself.
+ */
+const YIELD_EVERY_N_ATTEMPTS = 2000;
+function yieldToEventLoop() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+/**
+ * Grind a nonce for `publicKey`/`timestamp` that clears
+ * {@link REGISTRATION_POW_DIFFICULTY_BITS}, returned as a decimal counter.
+ *
+ * Hashes with `@noble/hashes/sha256` — pure JS, synchronous, identical output
+ * on web/Node/React Native with no native module and no per-attempt bridge
+ * crossing (see the difficulty constant's own doc for why that distinction is
+ * the whole point). Nonces are sequential (0, 1, 2, …) rather than random: the
+ * candidate space a hash function spreads solutions across is dense either
+ * way, so a counter finds one exactly as reliably as randomness would, without
+ * needing a randomness source at all.
+ */
+export async function solveRegistrationPow(publicKey, timestamp) {
+    for (let nonce = 0;; nonce += 1) {
+        const candidate = String(nonce);
+        const digest = bytesToHex(sha256(utf8ToBytes(registrationPowMessage(publicKey, timestamp, candidate))));
+        if (meetsRegistrationPowDifficulty(digest, REGISTRATION_POW_DIFFICULTY_BITS)) {
+            return candidate;
+        }
+        if (nonce % YIELD_EVERY_N_ATTEMPTS === YIELD_EVERY_N_ATTEMPTS - 1) {
+            await yieldToEventLoop();
+        }
+    }
+}

package/dist/esm/mixins/OxyServices.auth.js

@@ -2,6 +2,7 @@ import { loginResultSchema, safeParseContract } from '@oxy.so/contracts';
 export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from '../utils/commonsApproval.js';
 import { OxyAuthenticationError } from '../OxyServices.errors.js';
 import { KeyManager } from '../crypto/keyManager.js';
+import { solveRegistrationPow } from '../crypto/registrationPow.js';
 import { SignatureService } from '../crypto/signatureService.js';
 import { loadNodeCrypto } from '@oxy.so/protocol';
 import { logger } from '../logger/index.js';
@@ -269,7 +270,7 @@ export function OxyServicesAuthMixin(Base) {
             if (typeof process === 'undefined' || !process.versions?.node)
                 return false;
             try {
-                const { canAttestWorkloadIdentity } = await import('../server/workloadIdentity');
+                const { canAttestWorkloadIdentity } = await import('../server/workloadIdentity.js');
                 return canAttestWorkloadIdentity();
             }
             catch {
@@ -297,7 +298,7 @@ export function OxyServicesAuthMixin(Base) {
                 return entry.token;
             if (entry?.pending)
                 return entry.pending;
-            const { requestWorkloadServiceToken } = await import('../server/workloadIdentity');
+            const { requestWorkloadServiceToken } = await import('../server/workloadIdentity.js');
             const seeded = entry ?? {
                 token: '',
                 expiresAt: 0,
@@ -432,10 +433,15 @@ export function OxyServicesAuthMixin(Base) {
          */
         async register(publicKey, signature, timestamp) {
             try {
+                // Advisory for now (server soft-enforces — see
+                // `SessionController.register`), but solved unconditionally so every
+                // client is already sending it once the server starts requiring it.
+                const powNonce = await solveRegistrationPow(publicKey, timestamp);
                 const res = await this.makeRequest('POST', '/auth/register', {
                     publicKey,
                     signature,
                     timestamp,
+                    powNonce,
                 }, { cache: false, skipAuth: true });
                 if (!res || (typeof res === 'object' && Object.keys(res).length === 0)) {
                     throw new OxyAuthenticationError('Registration failed', 'REGISTER_FAILED', 400);

package/dist/esm/mixins/OxyServices.identityBackup.js

@@ -118,7 +118,7 @@ export function OxyServicesIdentityBackupMixin(Base) {
          *
          * NATIVE-ONLY persistence: `KeyManager.importKeyPair` throws on web. It also
          * refuses to clobber a DIFFERENT existing on-device identity unless
-         * `overwrite: true` — the {@link import('../crypto/keyManager').IdentityAlreadyExistsError}
+         * `overwrite: true` — the {@link import('../crypto/keyManager.js').IdentityAlreadyExistsError}
          * propagates to the caller (never swallowed) so the UI can confirm before
          * overwriting.
          *

package/dist/esm/mixins/OxyServices.user.js

@@ -64,12 +64,19 @@ export function OxyServicesUserMixin(Base) {
         }
         /**
          * Search user profiles
+         *
+         * Takes an `AbortSignal` because people search is typed into: without one
+         * every keystroke started a search that ran to completion and had its
+         * result discarded, while holding one of the request queue's slots. It was
+         * the only search lane in Mention that could not be cancelled, purely
+         * because this signature had no way to say so.
          */
-        async searchProfiles(query, pagination) {
+        async searchProfiles(query, pagination, options) {
             try {
                 const response = await this.makeRequest('GET', '/profiles/search', buildQueryParams({ query, ...pagination }), {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+                    signal: options?.signal,
                 });
                 if (typeof response !== 'object' ||
                     response === null ||

package/dist/esm/utils/asyncUtils.js

@@ -2,6 +2,7 @@
  * Async utilities for common asynchronous patterns and error handling
  */
 import { logger } from '../logger/index.js';
+import { ErrorCodes, isCancelledError } from './errorUtils.js';
 /**
  * Wrapper for async operations with automatic error handling
  * Returns null on error instead of throwing
@@ -53,29 +54,55 @@ function extractHttpStatus(error) {
     return undefined;
 }
 /**
- * Retry an async operation with exponential backoff
+ * Whether an error came from a request hitting its own timeout.
  *
- * By default, does not retry on 4xx errors (client errors). The default
- * predicate accepts both the axios-style `error.response.status` and the
- * flat `error.status` shape produced by {@link handleHttpError}, so callers
- * never accidentally retry a deterministic client failure.
- *
- * Use the `shouldRetry` callback to customize retry behavior.
+ * A timeout and a caller cancellation both surface from `fetch` as an
+ * `AbortError`, so this only recognises one that has already been CLASSIFIED
+ * (by `HttpService`, which knows which of its own timers fired). An
+ * unclassified abort is treated as a cancellation, which is the safe
+ * direction: refusing to retry something that was abandoned costs nothing,
+ * while retrying it is the defect this whole option exists to fix.
  */
-export async function retryAsync(operation, maxRetries = 3, baseDelay = 1000, shouldRetry) {
+function isTimeoutError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    return candidate.timeout === true || candidate.code === ErrorCodes.TIMEOUT;
+}
+export async function retryAsync(operation, maxRetriesOrOptions = 3, baseDelayArg = 1000, shouldRetryArg) {
+    // An options-object overload rather than a fifth positional parameter:
+    // `retryOnError` below and other in-tree callers pass positionally, and a
+    // boolean wedged between `baseDelay` and `shouldRetry` is the kind of
+    // signature that gets called wrong exactly once and then silently.
+    const options = typeof maxRetriesOrOptions === 'object' && maxRetriesOrOptions !== null
+        ? maxRetriesOrOptions
+        : { maxRetries: maxRetriesOrOptions, baseDelay: baseDelayArg, shouldRetry: shouldRetryArg };
+    const maxRetries = options.maxRetries ?? 3;
+    const baseDelay = options.baseDelay ?? 1000;
+    const retryOnTimeout = options.retryOnTimeout ?? false;
+    const deadline = options.deadline;
     let lastError;
     // Default shouldRetry: don't retry on 4xx errors (client errors).
     // Checks BOTH `error.status` (flat shape from handleHttpError / fetch
     // clients) AND `error.response.status` (axios-style shape) so neither
     // representation can leak a client error into the retry loop.
     const defaultShouldRetry = (error) => {
+        // A cancellation is an INSTRUCTION, not a transient failure, and is
+        // refused here rather than only in HttpService so that every `retryAsync`
+        // consumer inherits it. This was the defect: an `AbortError` carries no
+        // HTTP status, `status: 0` is not 4xx, so the status check below passed it
+        // straight into the retry loop and the SDK re-issued requests their
+        // callers had already abandoned.
+        if (isCancelledError(error)) {
+            return false;
+        }
         const status = extractHttpStatus(error);
         if (status !== undefined && status >= 400 && status < 500) {
             return false;
         }
         return true;
     };
-    const retryCheck = shouldRetry || defaultShouldRetry;
+    const retryCheck = options.shouldRetry || defaultShouldRetry;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             return await operation();
@@ -85,11 +112,25 @@ export async function retryAsync(operation, maxRetries = 3, baseDelay = 1000, sh
             if (attempt === maxRetries) {
                 break;
             }
+            // A cancellation is never retryable, whatever `shouldRetry` says: a
+            // custom predicate is for deciding which FAILURES are worth another
+            // attempt, and it has no business overriding an explicit abort.
+            if (isCancelledError(error)) {
+                break;
+            }
+            if (!retryOnTimeout && isTimeoutError(error)) {
+                break;
+            }
             if (!retryCheck(error)) {
                 break;
             }
             // Calculate delay with exponential backoff and jitter
             const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
+            // Nothing may start, or even sleep, past the deadline — otherwise the
+            // budget bounds the attempts but not the wall clock the caller feels.
+            if (deadline !== undefined && Date.now() + delay >= deadline) {
+                break;
+            }
             await new Promise(resolve => setTimeout(resolve, delay));
         }
     }

package/dist/esm/utils/errorUtils.js

@@ -26,7 +26,20 @@ export const ErrorCodes = {
     TIMEOUT: 'TIMEOUT',
     // Network errors
     NETWORK_ERROR: 'NETWORK_ERROR',
-    CONNECTION_FAILED: 'CONNECTION_FAILED'
+    CONNECTION_FAILED: 'CONNECTION_FAILED',
+    /**
+     * The CALLER cancelled this request — it did not fail.
+     *
+     * Distinct from {@link ErrorCodes.TIMEOUT} on purpose, and the distinction is
+     * load-bearing rather than cosmetic. Both arrive from `fetch` as an
+     * `AbortError` carrying no status, so for a long time both collapsed to
+     * `TIMEOUT` with `status: 0` — and since `status: 0` is not 4xx, the retry
+     * predicate treated a cancellation as a transient failure and re-issued the
+     * request the caller had just abandoned. A cancellation is an INSTRUCTION;
+     * nothing may retry it. See `retryAsync`'s default predicate, which refuses
+     * this code specifically.
+     */
+    CANCELLED: 'CANCELLED'
 };
 /**
  * Narrow a caught value to {@link HttpRequestError}.
@@ -96,6 +109,33 @@ export function createApiError(message, code = ErrorCodes.INTERNAL_ERROR, status
         details
     };
 }
+export function createCancelledError(message = 'Request cancelled') {
+    const error = new Error(message);
+    error.name = 'AbortError';
+    error.code = ErrorCodes.CANCELLED;
+    error.status = 0;
+    error.cancelled = true;
+    return error;
+}
+/**
+ * Whether an error represents a CALLER cancellation rather than a failure.
+ *
+ * Structural, never message-based: a message is localizable and rewordable,
+ * and a retry predicate that keys off one is a bug waiting for a copy edit.
+ */
+function isAbortLike(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.name === 'AbortError');
+}
+export function isCancelledError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    return (candidate.cancelled === true ||
+        candidate.code === ErrorCodes.CANCELLED ||
+        candidate.name === 'AbortError');
+}
 /**
  * Handle common HTTP errors and convert to ApiError
  */
@@ -112,8 +152,16 @@ export function handleHttpError(error) {
         }
         return apiError;
     }
-    // Handle AbortError (timeout or cancelled requests)
-    if (error instanceof Error && error.name === 'AbortError') {
+    // Handle AbortError (timeout or cancelled requests).
+    //
+    // Matched by NAME rather than `instanceof Error`, because `fetch` rejects an
+    // abort with a `DOMException` and `instanceof` is realm-bound — an exception
+    // built in another realm (a test VM, a worker, an iframe) fails the check and
+    // falls through to the generic 500 branch below. `HttpService` classifies its
+    // own aborts before reaching here, so this is the fallback for aborts raised
+    // anywhere else, and it stays TIMEOUT: a caller that never passed a signal
+    // cannot have cancelled anything.
+    if (isAbortLike(error)) {
         return createApiError('Request timeout or cancelled', ErrorCodes.TIMEOUT, 0);
     }
     // Handle TypeError (network failures, CORS, etc.)