@oxy.so/core 1.18.0 → 3.0.0

package/src/utils/deviceManager.ts

@@ -27,6 +27,7 @@ export interface StoredDeviceInfo {
  * 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 {
   private static DEVICE_KEY = 'oxy_device_info';
   
@@ -45,7 +46,7 @@ export class DeviceManager {
     setItem: (key: string, value: string) => Promise<void>;
     removeItem: (key: string) => Promise<void>;
   }> {
-    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
@@ -99,24 +100,24 @@ export class DeviceManager {
    */
   static async getDeviceInfo(): Promise<StoredDeviceInfo> {
     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: StoredDeviceInfo = 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();
     }
   }
 
@@ -125,13 +126,13 @@ export class DeviceManager {
    */
   static async createNewDeviceInfo(): Promise<StoredDeviceInfo> {
     const deviceInfo: StoredDeviceInfo = {
-      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;
   }
 
@@ -140,8 +141,8 @@ export class DeviceManager {
    */
   static async saveDeviceInfo(deviceInfo: StoredDeviceInfo): Promise<void> {
     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);
     }
@@ -152,9 +153,9 @@ export class DeviceManager {
    */
   static async updateDeviceName(deviceName: string): Promise<void> {
     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);
     }
@@ -165,8 +166,8 @@ export class DeviceManager {
    */
   static async clearDeviceInfo(): Promise<void> {
     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);
     }
@@ -188,7 +189,7 @@ export class DeviceManager {
    * Get a user-friendly device name based on platform
    */
   static getDefaultDeviceName(): string {
-    const fingerprint = this.getDeviceFingerprint();
+    const fingerprint = DeviceManager.getDeviceFingerprint();
     const platform = (fingerprint.platform || '').toLowerCase();
     
     if (platform.includes('win')) return 'Windows Computer';

package/src/utils/edgeRegion.ts

@@ -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/src/utils/identityCacheSweep.ts

@@ -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.
  */
 
@@ -56,8 +56,7 @@
  * structurally so this module stays free of any client import.
  */
 export interface OxyIdentityCacheEvictor {
-  clearCacheEntry(key: string): void;
-  clearCacheByPrefix(prefix: string): number;
+  invalidateCache(spec: { keys?: readonly string[]; prefixes?: readonly string[] }): number;
 }
 
 /**
@@ -69,8 +68,6 @@ export const OXY_IDENTITY_CACHE_PREFIXES: readonly string[] = [
   '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.
@@ -94,11 +91,9 @@ export function oxyUserByIdCacheKey(userId: string): string {
  *                 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: OxyIdentityCacheEvictor, userId?: string): void {
-  for (const prefix of OXY_IDENTITY_CACHE_PREFIXES) {
-    oxy.clearCacheByPrefix(prefix);
-  }
-  if (userId) {
-    oxy.clearCacheEntry(oxyUserByIdCacheKey(userId));
-  }
+export function evictOxyIdentityCache(http: OxyIdentityCacheEvictor, userId?: string): void {
+  http.invalidateCache({
+    prefixes: OXY_IDENTITY_CACHE_PREFIXES,
+    keys: userId ? [oxyUserByIdCacheKey(userId)] : [],
+  });
 }

package/src/utils/oauthPkce.ts

@@ -89,8 +89,8 @@ export interface BuildOAuthAuthorizeUrlParams {
   responseMode?: 'web_message';
   /**
    * Which of the IdP's screens a person with no session there lands on:
-   * `signin` (sign in with a passkey), `signup` (create an account with its
-   * root), `recover` (recover it from the recovery phrase). Omitted, the IdP
+   * `signin` (sign in), `signup` (create an account), `recover` (get back
+   * into one); each opens its sign-in panel. Omitted, the IdP
    * offers its Commons request first. An Oxy app sends this when it sends the
    * person to auth.oxy.so for what only that origin can do, in the same tab.
    */

package/src/utils/oxyServiceEnvironment.ts

@@ -5,13 +5,9 @@
  * 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'] as const;
 export type OxyServiceEnvironment = (typeof OXY_SERVICE_ENVIRONMENTS)[number];

package/src/utils/requestUtils.ts

@@ -28,69 +28,73 @@ function abortReason(signal: AbortSignal): unknown {
 
 /**
  * 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 {
-  private pendingRequests = new Map<string, Promise<any>>();
+  private pending = new Map<string, { promise: Promise<unknown>; controller: AbortController; waiters: number }>();
 
   /**
    * 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<T>(
     key: string,
-    requestFn: () => Promise<T>,
+    requestFn: (signal: AbortSignal) => Promise<T>,
     signal?: AbortSignal
   ): Promise<T> {
     if (signal?.aborted) {
       throw abortReason(signal);
     }
 
-    let promise = this.pendingRequests.get(key) as Promise<T> | undefined;
-    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);
     }
+    const shared = entry;
+    shared.waiters++;
 
-    // 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.
     if (!signal) {
-      return promise;
+      return shared.promise as Promise<T>;
     }
 
-    // `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(() => { /* ownership stays with the caller(s) awaiting it */ });
-
     return new Promise<T>((resolve, reject) => {
-      const onAbort = (): void => reject(abortReason(signal));
+      const onAbort = (): void => {
+        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(
+      (shared.promise as Promise<T>).then(
         (value) => { signal.removeEventListener('abort', onAbort); resolve(value); },
         (error) => { signal.removeEventListener('abort', onAbort); reject(error); },
       );
@@ -101,14 +105,14 @@ export class RequestDeduplicator {
    * Clear all pending requests
    */
   clear(): void {
-    this.pendingRequests.clear();
+    this.pending.clear();
   }
 
   /**
    * Get number of pending requests
    */
   size(): number {
-    return this.pendingRequests.size;
+    return this.pending.size;
   }
 }
 
@@ -129,7 +133,7 @@ export class RequestDeduplicator {
  * ```
  */
 export class RequestQueue {
-  private queue: Array<() => Promise<any>> = [];
+  private queue: Array<() => Promise<unknown>> = [];
   private running = 0;
   private maxConcurrent: number;
   private maxQueueSize: number;
@@ -297,29 +301,29 @@ export class SimpleLogger {
     return levels.indexOf(level) <= levels.indexOf(this.level);
   }
 
-  private formatMessage(...args: any[]): any[] {
+  private formatMessage(...args: unknown[]): unknown[] {
     return this.prefix ? [`[${this.prefix}]`, ...args] : args;
   }
 
-  error(...args: any[]): void {
+  error(...args: unknown[]): void {
     if (this.shouldLog('error')) {
       console.error(...this.formatMessage(...args));
     }
   }
 
-  warn(...args: any[]): void {
+  warn(...args: unknown[]): void {
     if (this.shouldLog('warn')) {
       console.warn(...this.formatMessage(...args));
     }
   }
 
-  info(...args: any[]): void {
+  info(...args: unknown[]): void {
     if (this.shouldLog('info')) {
       console.info(...this.formatMessage(...args));
     }
   }
 
-  debug(...args: any[]): void {
+  debug(...args: unknown[]): void {
     if (this.shouldLog('debug')) {
       console.log(...this.formatMessage(...args));
     }

package/src/utils/sessionUtils.ts

@@ -94,8 +94,6 @@ export function deduplicateSessionsByUserId(
       if (isCurrentActive && !isExistingActive) {
         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
         const existingTime = new Date(existing.lastActive).getTime();

package/src/utils/tokenClaims.ts

@@ -0,0 +1,38 @@
+/**
+ * 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';
+
+export interface AccessTokenClaims {
+  exp?: number;
+  userId?: string;
+  id?: string;
+  sessionId?: string;
+  [claim: string]: unknown;
+}
+
+const MEMO_SIZE = 4;
+const memo = new Map<string, AccessTokenClaims | null>();
+
+/** The token's claims, or `null` for an opaque/undecodable token. */
+export function decodeTokenClaims(token: string): AccessTokenClaims | null {
+  if (memo.has(token)) return memo.get(token) ?? null;
+  let claims: AccessTokenClaims | null;
+  try {
+    claims = jwtDecode<AccessTokenClaims>(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;
+}