@oxy.so/core 1.18.0 → 3.0.0

package/dist/esm/utils/deviceManager.js

@@ -5,6 +5,7 @@ const log = createLogger('DeviceManager');
  * Client-side device management utility
  * Handles persistent device identification across app sessions
  */
+// biome-ignore lint/complexity/noStaticOnlyClass: a public, static-only API surface (`X.method()`) that consumers and tests call and spy on by name.
 export class DeviceManager {
     /**
      * Check if we're in React Native environment
@@ -16,7 +17,7 @@ export class DeviceManager {
      * Get appropriate storage for the platform
      */
     static async getStorage() {
-        if (this.isReactNative()) {
+        if (DeviceManager.isReactNative()) {
             try {
                 // `loadAsyncStorage` is per-platform: the RN variant statically imports
                 // @react-native-async-storage/async-storage, the default variant throws
@@ -68,21 +69,21 @@ export class DeviceManager {
      */
     static async getDeviceInfo() {
         try {
-            const storage = await this.getStorage();
-            const stored = await storage.getItem(this.DEVICE_KEY);
+            const storage = await DeviceManager.getStorage();
+            const stored = await storage.getItem(DeviceManager.DEVICE_KEY);
             if (stored) {
                 const deviceInfo = JSON.parse(stored);
                 // Update last used timestamp
                 deviceInfo.lastUsed = new Date().toISOString();
-                await this.saveDeviceInfo(deviceInfo);
+                await DeviceManager.saveDeviceInfo(deviceInfo);
                 return deviceInfo;
             }
             // Create new device info
-            return await this.createNewDeviceInfo();
+            return await DeviceManager.createNewDeviceInfo();
         }
         catch (error) {
             log.error('Error getting device info', error);
-            return await this.createNewDeviceInfo();
+            return await DeviceManager.createNewDeviceInfo();
         }
     }
     /**
@@ -90,12 +91,12 @@ export class DeviceManager {
      */
     static async createNewDeviceInfo() {
         const deviceInfo = {
-            deviceId: this.generateDeviceId(),
-            fingerprint: JSON.stringify(this.getDeviceFingerprint()),
+            deviceId: DeviceManager.generateDeviceId(),
+            fingerprint: JSON.stringify(DeviceManager.getDeviceFingerprint()),
             createdAt: new Date().toISOString(),
             lastUsed: new Date().toISOString()
         };
-        await this.saveDeviceInfo(deviceInfo);
+        await DeviceManager.saveDeviceInfo(deviceInfo);
         return deviceInfo;
     }
     /**
@@ -103,8 +104,8 @@ export class DeviceManager {
      */
     static async saveDeviceInfo(deviceInfo) {
         try {
-            const storage = await this.getStorage();
-            await storage.setItem(this.DEVICE_KEY, JSON.stringify(deviceInfo));
+            const storage = await DeviceManager.getStorage();
+            await storage.setItem(DeviceManager.DEVICE_KEY, JSON.stringify(deviceInfo));
         }
         catch (error) {
             log.error('Error saving device info', error);
@@ -115,9 +116,9 @@ export class DeviceManager {
      */
     static async updateDeviceName(deviceName) {
         try {
-            const deviceInfo = await this.getDeviceInfo();
+            const deviceInfo = await DeviceManager.getDeviceInfo();
             deviceInfo.deviceName = deviceName;
-            await this.saveDeviceInfo(deviceInfo);
+            await DeviceManager.saveDeviceInfo(deviceInfo);
         }
         catch (error) {
             log.error('Error updating device name', error);
@@ -128,8 +129,8 @@ export class DeviceManager {
      */
     static async clearDeviceInfo() {
         try {
-            const storage = await this.getStorage();
-            await storage.removeItem(this.DEVICE_KEY);
+            const storage = await DeviceManager.getStorage();
+            await storage.removeItem(DeviceManager.DEVICE_KEY);
         }
         catch (error) {
             log.error('Error clearing device info', error);
@@ -150,7 +151,7 @@ export class DeviceManager {
      * Get a user-friendly device name based on platform
      */
     static getDefaultDeviceName() {
-        const fingerprint = this.getDeviceFingerprint();
+        const fingerprint = DeviceManager.getDeviceFingerprint();
         const platform = (fingerprint.platform || '').toLowerCase();
         if (platform.includes('win'))
             return 'Windows Computer';

package/dist/esm/utils/edgeRegion.js

@@ -1,2 +1 @@
-/** @deprecated Import from `@oxy.so/telemetry/browser` in new code. */
-export { getBrowserEdgeRegionHeader } from '@oxy.so/telemetry/browser';
+export { peekBrowserEdgeRegionHeader } from '@oxy.so/telemetry/browser';

package/dist/esm/utils/identityCacheSweep.js

@@ -47,7 +47,7 @@
  * refetch; under-eviction serves wrong data.
  *
  * Platform-neutral by construction (no imports, no `OxyServices` reference) so
- * the client mixins and the Node-only `@oxy.so/core/server` invalidation
+ * the client namespaces and the Node-only `@oxy.so/core/server` invalidation
  * subscriber can share it without either pulling in the other.
  */
 /**
@@ -59,8 +59,6 @@ export const OXY_IDENTITY_CACHE_PREFIXES = [
     'GET:/session/user/',
     // `getCurrentUser` (and `GET:/users/me/graph`, harmlessly included).
     'GET:/users/me',
-    // `lookupUsername` — the pre-session login lookup; carries avatar + display name.
-    'GET:/auth/lookup/',
     // `getProfileByUsername` — keyed by handle, including the pre-rename handle.
     'GET:/profiles/username/',
     // `resolveProfile` — keyed by fediverse handle in the query payload.
@@ -82,11 +80,9 @@ export function oxyUserByIdCacheKey(userId) {
  *                 that does not know the id still clears every handle-, session-
  *                 and self-keyed entry, which is the majority of the surface.
  */
-export function evictOxyIdentityCache(oxy, userId) {
-    for (const prefix of OXY_IDENTITY_CACHE_PREFIXES) {
-        oxy.clearCacheByPrefix(prefix);
-    }
-    if (userId) {
-        oxy.clearCacheEntry(oxyUserByIdCacheKey(userId));
-    }
+export function evictOxyIdentityCache(http, userId) {
+    http.invalidateCache({
+        prefixes: OXY_IDENTITY_CACHE_PREFIXES,
+        keys: userId ? [oxyUserByIdCacheKey(userId)] : [],
+    });
 }

package/dist/esm/utils/oxyServiceEnvironment.js

@@ -5,12 +5,8 @@
  * literal union — `@oxy.so/core` has zero dependency on `@oxy.so/api`, so this is
  * kept in sync by hand, not by import.
  *
- * Defined here (not in `server/auth.ts` or `mixins/OxyServices.utility.ts`
- * directly) because BOTH of those files need it and neither may import from
- * the other: `server/` types import `express` (Node-only, a peer dependency
- * `mixins/` deliberately avoids so it stays safe to bundle into RN/browser
- * consumers — see the "Local request/response/socket typing" comment in
- * `OxyServices.utility.ts`). This file has zero imports, so both sides can
- * depend on it without crossing that boundary.
+ * Defined here, with zero imports, so the server middleware and any
+ * client-safe code can both depend on it without the client reaching the
+ * Node-only `server/` modules.
  */
 export const OXY_SERVICE_ENVIRONMENTS = ['development', 'staging', 'production'];

package/dist/esm/utils/requestUtils.js

@@ -26,74 +26,81 @@ function abortReason(signal) {
 /**
  * Request deduplication - prevents duplicate concurrent requests
  *
- * When multiple requests with the same key are made simultaneously,
- * only one request is executed and all callers receive the same result.
+ * When multiple requests with the same key are made simultaneously, only one
+ * request is executed and all callers receive the same result.
+ *
+ * The shared work runs in its OWN abort domain, not the first caller's: each
+ * caller owns its cancellation, and the shared work is aborted only once every
+ * caller waiting on it has cancelled. Binding it to the first caller's signal
+ * meant one cancelled caller failed every other caller on the same key.
  *
  * @example
  * ```typescript
  * const deduplicator = new RequestDeduplicator();
  *
- * // Multiple calls with same key will share the same promise
- * const promise1 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
- * const promise2 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
- * // promise1 === promise2, only one API call is made
+ * // Multiple calls with same key share one in-flight call
+ * const promise1 = deduplicator.deduplicate('user-123', (signal) => fetchUser('123', signal));
+ * const promise2 = deduplicator.deduplicate('user-123', (signal) => fetchUser('123', signal));
  * ```
  */
 export class RequestDeduplicator {
     constructor() {
-        this.pendingRequests = new Map();
+        this.pending = new Map();
     }
     /**
      * Deduplicate a request by key
      * @param key Unique key for the request
-     * @param requestFn Function that returns a promise
-     * @returns Promise that will be shared if key already exists
+     * @param requestFn Runs the work; its signal aborts once every caller has cancelled
+     * @param signal This caller's cancellation
      */
     async deduplicate(key, requestFn, signal) {
         if (signal?.aborted) {
             throw abortReason(signal);
         }
-        let promise = this.pendingRequests.get(key);
-        if (!promise) {
-            promise = requestFn().finally(() => {
-                this.pendingRequests.delete(key);
+        let entry = this.pending.get(key);
+        if (!entry) {
+            const controller = new AbortController();
+            const promise = requestFn(controller.signal).finally(() => {
+                if (this.pending.get(key) === entry)
+                    this.pending.delete(key);
             });
-            this.pendingRequests.set(key, promise);
+            // Ownership stays with the callers awaiting it; this only stops a
+            // rejection nobody is left to observe from surfacing as unhandled.
+            promise.catch(() => { });
+            entry = { promise, controller, waiters: 0 };
+            this.pending.set(key, entry);
         }
-        // Callers SHARE the work but own their cancellation separately.
-        //
-        // Returning the shared promise directly meant one caller's abort rejected
-        // every other caller on the same key — including ones that never cancelled
-        // anything, and which had no way to tell that the failure was not theirs.
-        // Racing each caller's own signal against the shared work keeps the single
-        // in-flight request (the point of deduplication) while making cancellation
-        // per-caller. The shared promise is left running: another caller may still
-        // want it, and if nobody does its own abort domain ends it.
+        const shared = entry;
+        shared.waiters++;
         if (!signal) {
-            return promise;
+            return shared.promise;
         }
-        // `promise` is already owned by the map's `finally`, so attach a no-op
-        // catch to the copy we race: without it, a rejection settled by the race's
-        // loser surfaces as an unhandled rejection.
-        const shared = promise;
-        shared.catch(() => { });
         return new Promise((resolve, reject) => {
-            const onAbort = () => reject(abortReason(signal));
+            const onAbort = () => {
+                shared.waiters--;
+                if (shared.waiters === 0) {
+                    // Nobody wants the result any more: free the key and end the work.
+                    if (this.pending.get(key) === shared)
+                        this.pending.delete(key);
+                    shared.controller.abort();
+                }
+                reject(abortReason(signal));
+            };
             signal.addEventListener('abort', onAbort, { once: true });
-            shared.then((value) => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+            shared.promise.then((value) => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
         });
     }
     /**
      * Clear all pending requests
      */
     clear() {
-        this.pendingRequests.clear();
+        this.pending.clear();
     }
     /**
      * Get number of pending requests
      */
     size() {
-        return this.pendingRequests.size;
+        return this.pending.size;
     }
 }
 /**

package/dist/esm/utils/sessionUtils.js

@@ -83,8 +83,6 @@ export function deduplicateSessionsByUserId(sessions, activeSessionId) {
                 userSessionMap.set(session.userId, session);
             }
             else if (!isCurrentActive && isExistingActive) {
-                // Keep existing (active) session
-                continue;
             }
             else {
                 // Neither is active, keep the one with more recent lastActive

package/dist/esm/utils/tokenClaims.js

@@ -0,0 +1,31 @@
+/**
+ * Decoded access-token claims, memoised per token string.
+ *
+ * Every request used to decode the same JWT several times (the auth preflight,
+ * the cache key, the dedupe key, the expiry checks). A token is immutable, so
+ * its claims are decoded once and reused until a new token replaces it. The
+ * memo holds a handful of recent tokens (a client, its linked clients, a
+ * rotation in flight) and never the payload of a token no longer in use.
+ */
+import { jwtDecode } from 'jwt-decode';
+const MEMO_SIZE = 4;
+const memo = new Map();
+/** The token's claims, or `null` for an opaque/undecodable token. */
+export function decodeTokenClaims(token) {
+    if (memo.has(token))
+        return memo.get(token) ?? null;
+    let claims;
+    try {
+        claims = jwtDecode(token);
+    }
+    catch {
+        claims = null;
+    }
+    memo.set(token, claims);
+    if (memo.size > MEMO_SIZE) {
+        const oldest = memo.keys().next().value;
+        if (oldest !== undefined)
+            memo.delete(oldest);
+    }
+    return claims;
+}

package/dist/types/HttpService.d.ts

@@ -17,6 +17,11 @@ import type { DeviceSecretMintOutcome } from './session/refresh';
 export type AuthRefreshReason = 'preflight' | 'response-401';
 export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
 export type AccessTokenProvider = () => string | null;
+/**
+ * Supplies a bearer for a request made while this client holds NO user session
+ * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
+ */
+export type AnonymousAuthProvider = () => Promise<string | null>;
 /**
  * A low-level authenticated request whose response body remains unread.
  *
@@ -162,6 +167,7 @@ export declare class HttpService {
     private noFresherTokenThan;
     private authRefreshHandler;
     private accessTokenProvider;
+    private anonymousAuthProvider;
     private deviceSecretMintInFlight;
     /**
      * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -324,6 +330,13 @@ export declare class HttpService {
      * Get auth header with automatic token refresh
      */
     private getAuthHeader;
+    /**
+     * The bearer for a request that has no user session behind it, from the
+     * {@link AnonymousAuthProvider} if one is installed. Never throws: a provider
+     * that fails sends the request anonymous, exactly as it went before any
+     * provider existed.
+     */
+    private getAnonymousAuthHeader;
     refreshAccessToken(reason: AuthRefreshReason): Promise<string | null>;
     /**
      * Report that the refresh/mint endpoint answered 429 Too Many Requests, so the
@@ -355,17 +368,18 @@ export declare class HttpService {
      */
     private isAccessTokenExpired;
     /**
-     * PROCESS-WIDE single-flight for the rotating device-secret mint
+     * PROCESS-WIDE single-flight for the device-secret mint
      * (`POST /session/device/token`).
      *
-     * The server rotates the presented `deviceSecret` on every successful mint, so
-     * two concurrent mints would double-rotate and the durable store could end up
-     * holding a superseded secret → a later cold-boot mint 401s → the user is
-     * signed out. Every mint lane (the re-mint handler behind `refreshAccessToken`,
-     * the device-first cold boot, the socket token transport, the tab-focus
-     * reconcile) funnels its `refreshDeviceSecretArm` call through here, so
-     * concurrent callers await the SAME in-flight mint and all receive its result —
-     * exactly one server rotation.
+     * The server does not rotate the presented `deviceSecret` (it echoes it back
+     * as `nextDeviceSecret`; each holder of a shared DeviceSession has its own
+     * stable credential), so this is no longer what keeps the store's secret
+     * valid. It still collapses concurrent callers onto one request and one
+     * persisted write. Every mint lane (the re-mint handler behind
+     * `refreshAccessToken`, the device-first cold boot, the socket token
+     * transport, the tab-focus reconcile) funnels its `refreshDeviceSecretArm`
+     * call through here, so concurrent callers await the SAME in-flight mint and
+     * all receive its result.
      *
      * Distinct from {@link tokenRefreshPromise} (which dedups the FULL re-mint
      * handler incl. the native shared-key arm + the failure cooldown): this inner
@@ -442,6 +456,14 @@ export declare class HttpService {
     hasSessionEnded(): boolean;
     setAuthRefreshHandler(handler: AuthRefreshHandler | null): void;
     setAccessTokenProvider(provider: AccessTokenProvider | null): void;
+    /**
+     * Authenticate requests that carry no user session with the bearer this
+     * provider returns — in practice a backend's own service token (see
+     * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
+     * consulted only when there is no access token, and never for `skipAuth`
+     * requests. `null` removes it.
+     */
+    setAnonymousAuthProvider(provider: AnonymousAuthProvider | null): void;
     clearTokens(): void;
     /**
      * Subscribe to access-token changes on this instance.
@@ -489,6 +511,22 @@ export declare class HttpService {
      * deleted entries (for observability in tests).
      */
     clearCacheByPrefix(prefix: string): number;
+    /**
+     * Invalidate a set of LOGICAL keys (each with every identity-scoped variant,
+     * see `clearCacheEntry`) and key prefixes in ONE pass over the cache. A
+     * mutation touching many resources (a bulk follow) costs one scan, not one
+     * per resource.
+     * @returns Number of entries deleted
+     */
+    invalidateCache({ keys, prefixes }: {
+        keys?: readonly string[];
+        prefixes?: readonly string[];
+    }): number;
+    /**
+     * Release this client: its response cache leaves the global cleanup sweep and
+     * is emptied, pending shared calls are forgotten, and the session ends.
+     */
+    dispose(): void;
     getCacheStats(): {
         size: number;
         hits: number;