@oxy.so/core 1.18.0 → 3.0.0

package/src/session/sharedDeviceCredential.ts

@@ -242,8 +242,9 @@ export function decideSharedDevicePublish(
       if (shared.credential.deviceSecret === proven.deviceSecret) {
         return { action: 'skip', reason: 'already-current' };
       }
-      // Same device, newer secret. Sign-in rotates the secret (the mint does
-      // not), so the just-proven one is the credential a fresh install should
+      // Same device, newer secret. Each sign-in issues a new holder credential
+      // (the older one stays valid until the device ends with nobody signed
+      // in), so the just-proven one is the credential a fresh install should
       // join with.
       return { action: 'publish' };
     }

package/src/shared/utils/networkUtils.ts

@@ -98,7 +98,7 @@ export const calculateBackoffInterval = (state: CircuitBreakerState): number =>
   if (consecutiveFailures === 0) return baseInterval;
 
   const backoffMultiplier = Math.min(
-    Math.pow(2, consecutiveFailures - 1),
+    2 ** (consecutiveFailures - 1),
     maxInterval / baseInterval
   );
 
@@ -238,7 +238,7 @@ export const withRetry = async <T>(
         throw error;
       }
 
-      const delayMs = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+      const delayMs = Math.min(baseDelay * 2 ** attempt, maxDelay);
       onRetry?.(error, attempt + 1);
       await delay(delayMs);
     }

package/src/utils/accountCacheSweep.ts

@@ -12,15 +12,12 @@
  * those cached and the account switcher keeps drawing the pre-edit name and
  * picture for the full TTL, against a perfectly healthy server.
  *
- * The mixins compose into one class at runtime but are typed one at a time, so
- * the user mixin cannot call a method the accounts mixin owns. The key list
- * therefore lives here, once, and every writer calls {@link
- * evictOxyAccountForestCache} — exactly like the identity key list in
- * `identityCacheSweep`, which the accounts mixin already calls for the
- * mirror-image case (an account write staling the identity reads). The
- * alternative — a second hand-written copy of these keys in the other mixin —
- * is the drift that shipped the two stale-profile bugs `identityCacheSweep`
- * documents.
+ * The key list lives here, once, and every writer (`users.updateMe`, the
+ * `accounts` namespace) reads it — exactly like the identity key list in
+ * `identityCacheSweep`, which account writes use for the mirror-image case (an
+ * account write staling the identity reads). A second hand-written copy of
+ * these keys in another namespace is the drift that shipped the two
+ * stale-profile bugs `identityCacheSweep` documents.
  *
  * WHY THE LIST NEEDS A PREFIX AND THE DETAIL DOES NOT
  * --------------------------------------------------
@@ -82,12 +79,11 @@ export function oxyAccountDetailCacheKey(accountId: string): string {
  *                    detail row to name, and clears only the lists.
  */
 export function evictOxyAccountForestCache(
-  oxy: OxyAccountCacheEvictor,
+  http: OxyAccountCacheEvictor,
   accountId?: string,
 ): void {
-  oxy.clearCacheEntry(OXY_ACCOUNT_LIST_CACHE_KEY);
-  oxy.clearCacheByPrefix(OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX);
-  if (accountId) {
-    oxy.clearCacheEntry(oxyAccountDetailCacheKey(accountId));
-  }
+  http.invalidateCache({
+    keys: accountId ? [OXY_ACCOUNT_LIST_CACHE_KEY, oxyAccountDetailCacheKey(accountId)] : [OXY_ACCOUNT_LIST_CACHE_KEY],
+    prefixes: [OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX],
+  });
 }

package/src/utils/apiUtils.ts

@@ -103,7 +103,7 @@ export function buildPaginationParams(params: PaginationParams): Record<string,
 /**
  * Common API response wrapper
  */
-export interface ApiResponse<T = any> {
+export interface ApiResponse<T = unknown> {
   data: T;
   message?: string;
   success?: boolean;
@@ -116,7 +116,7 @@ export interface ErrorResponse {
   message: string;
   code: string;
   status: number;
-  details?: any;
+  details?: unknown;
 }
 
 /**
@@ -125,7 +125,7 @@ export interface ErrorResponse {
  * @param fallback Fallback value if parsing fails
  * @returns Parsed data or fallback
  */
-export function safeJsonParse<T>(data: any, fallback: T): T {
+export function safeJsonParse<T>(data: unknown, fallback: T): T {
   if (typeof data === 'string') {
     try {
       return JSON.parse(data);

package/src/utils/asyncUtils.ts

@@ -1,85 +1,10 @@
 /**
- * Async utilities for common asynchronous patterns and error handling
+ * Retry with exponential backoff and jitter — the policy `HttpService` uses.
  */
 
-import { logger } from '../logger';
 import { ErrorCodes, isCancelledError } from './errorUtils';
 
-/**
- * Wrapper for async operations with automatic error handling
- * Returns null on error instead of throwing
- */
-export async function withErrorHandling<T>(
-  operation: () => Promise<T>,
-  errorHandler?: (error: any) => void,
-  context?: string
-): Promise<T | null> {
-  try {
-    return await operation();
-  } catch (error) {
-    if (errorHandler) {
-      errorHandler(error);
-    } else {
-      logger.error(`Error in ${context || 'operation'}`, error instanceof Error ? error : new Error(String(error)), {
-        component: 'asyncUtils',
-        method: 'withErrorHandling',
-      });
-    }
-    return null;
-  }
-}
-
-/**
- * Execute multiple async operations in parallel with error handling
- */
-export async function parallelWithErrorHandling<T>(
-  operations: (() => Promise<T>)[],
-  errorHandler?: (error: any, index: number) => void
-): Promise<(T | null)[]> {
-  const results = await Promise.allSettled(
-    operations.map((op, index) => 
-      withErrorHandling(op, error => errorHandler?.(error, index))
-    )
-  );
-  
-  return results.map(result => 
-    result.status === 'fulfilled' ? result.value : null
-  );
-}
-
-/**
- * Extract an HTTP status code from an error value, tolerating both the
- * axios-style nested shape (`error.response.status`) and the flat shape
- * produced by {@link handleHttpError} / fetch-based clients (`error.status`).
- *
- * Centralising this lookup prevents retry predicates from silently falling
- * through when one of the two shapes is missing, which previously caused
- * @oxy.so/core to retry 4xx responses and turn sub-10ms failures into
- * multi-second stalls for every missing-resource lookup.
- */
-function extractHttpStatus(error: unknown): number | undefined {
-  if (!error || typeof error !== 'object') return undefined;
-  const candidate = error as {
-    status?: unknown;
-    response?: { status?: unknown } | null;
-  };
-  const flat = candidate.status;
-  if (typeof flat === 'number' && Number.isFinite(flat)) return flat;
-  const nested = candidate.response?.status;
-  if (typeof nested === 'number' && Number.isFinite(nested)) return nested;
-  return undefined;
-}
-
-/**
- * Retry an async operation with exponential backoff
- *
- * 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.
- */
+/** Options for {@link retryAsync}. */
 export interface RetryOptions {
   maxRetries?: number;
   baseDelay?: number;
@@ -126,11 +51,44 @@ function isTimeoutError(error: unknown): boolean {
   return candidate.timeout === true || candidate.code === ErrorCodes.TIMEOUT;
 }
 
+/**
+ * Extract an HTTP status code from an error value, tolerating both the
+ * axios-style nested shape (`error.response.status`) and the flat shape
+ * produced by {@link handleHttpError} / fetch-based clients (`error.status`).
+ *
+ * Centralising this lookup prevents retry predicates from silently falling
+ * through when one of the two shapes is missing, which previously caused
+ * @oxy.so/core to retry 4xx responses and turn sub-10ms failures into
+ * multi-second stalls for every missing-resource lookup.
+ */
+function extractHttpStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') return undefined;
+  const candidate = error as {
+    status?: unknown;
+    response?: { status?: unknown } | null;
+  };
+  const flat = candidate.status;
+  if (typeof flat === 'number' && Number.isFinite(flat)) return flat;
+  const nested = candidate.response?.status;
+  if (typeof nested === 'number' && Number.isFinite(nested)) return nested;
+  return undefined;
+}
+
+/**
+ * Retry an async operation with exponential backoff
+ *
+ * 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.
+ */
 export async function retryAsync<T>(
   operation: () => Promise<T>,
   maxRetriesOrOptions: number | RetryOptions = 3,
   baseDelayArg = 1000,
-  shouldRetryArg?: (error: any) => boolean
+  shouldRetryArg?: (error: unknown) => boolean
 ): Promise<T> {
   // An options-object overload rather than a fifth positional parameter:
   // `retryOnError` below and other in-tree callers pass positionally, and a
@@ -146,7 +104,7 @@ export async function retryAsync<T>(
   const retryOnTimeout = options.retryOnTimeout ?? false;
   const deadline = options.deadline;
 
-  let lastError: any;
+  let lastError: unknown;
 
   // Default shouldRetry: don't retry on 4xx errors (client errors).
   // Checks BOTH `error.status` (flat shape from handleHttpError / fetch
@@ -197,7 +155,7 @@ export async function retryAsync<T>(
       }
 
       // Calculate delay with exponential backoff and jitter
-      const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
+      const delay = baseDelay * 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.
@@ -211,158 +169,3 @@ export async function retryAsync<T>(
 
   throw lastError;
 }
-
-/**
- * Debounce async function calls
- */
-export function debounceAsync<T extends (...args: any[]) => Promise<any>>(
-  func: T,
-  delay: number
-): (...args: Parameters<T>) => Promise<ReturnType<T>> {
-  let timeoutId: ReturnType<typeof setTimeout>;
-
-  return (...args: Parameters<T>): Promise<ReturnType<T>> => {
-    return new Promise((resolve, reject) => {
-      clearTimeout(timeoutId);
-      
-      timeoutId = setTimeout(async () => {
-        try {
-          const result = await func(...args);
-          resolve(result);
-        } catch (error) {
-          reject(error);
-        }
-      }, delay);
-    });
-  };
-}
-
-/**
- * Throttle async function calls
- */
-export function throttleAsync<T extends (...args: any[]) => Promise<any>>(
-  func: T,
-  limit: number,
-  interval: number
-): (...args: Parameters<T>) => Promise<ReturnType<T>> {
-  let inThrottle = false;
-  let lastPromise: Promise<ReturnType<T>> | null = null;
-  
-  return (...args: Parameters<T>): Promise<ReturnType<T>> => {
-    if (inThrottle) {
-      return lastPromise!;
-    }
-    
-    inThrottle = true;
-    lastPromise = func(...args);
-    
-    setTimeout(() => {
-      inThrottle = false;
-    }, interval);
-    
-    return lastPromise;
-  };
-}
-
-/**
- * Execute async operations sequentially with progress tracking
- */
-export async function sequentialWithProgress<T>(
-  operations: (() => Promise<T>)[],
-  onProgress?: (completed: number, total: number) => void
-): Promise<T[]> {
-  const results: T[] = [];
-  
-  for (let i = 0; i < operations.length; i++) {
-    const result = await operations[i]();
-    results.push(result);
-    onProgress?.(i + 1, operations.length);
-  }
-  
-  return results;
-}
-
-/**
- * Batch async operations
- */
-export async function batchAsync<T>(
-  items: T[],
-  batchSize: number,
-  processor: (batch: T[]) => Promise<void>
-): Promise<void> {
-  for (let i = 0; i < items.length; i += batchSize) {
-    const batch = items.slice(i, i + batchSize);
-    await processor(batch);
-  }
-}
-
-/**
- * Create a cancellable async operation
- */
-export function createCancellableAsync<T>(
-  operation: (signal: AbortSignal) => Promise<T>
-): { execute: () => Promise<T>; cancel: () => void } {
-  let abortController: AbortController | null = null;
-  
-  return {
-    execute: async () => {
-      abortController = new AbortController();
-      return await operation(abortController.signal);
-    },
-    cancel: () => {
-      abortController?.abort();
-    }
-  };
-}
-
-/**
- * Timeout wrapper for async operations
- */
-export async function withTimeout<T>(
-  operation: Promise<T>,
-  timeoutMs: number,
-  timeoutMessage?: string
-): Promise<T> {
-  const timeoutPromise = new Promise<never>((_, reject) => {
-    setTimeout(() => {
-      reject(new Error(timeoutMessage || `Operation timed out after ${timeoutMs}ms`));
-    }, timeoutMs);
-  });
-  
-  return Promise.race([operation, timeoutPromise]);
-}
-
-/**
- * Execute async operation with loading state
- */
-export async function withLoadingState<T>(
-  operation: () => Promise<T>,
-  setLoading: (loading: boolean) => void
-): Promise<T> {
-  setLoading(true);
-  try {
-    return await operation();
-  } finally {
-    setLoading(false);
-  }
-}
-
-/**
- * Create a promise that resolves after a delay
- */
-export const delay = (ms: number): Promise<void> => 
-  new Promise(resolve => setTimeout(resolve, ms));
-
-/**
- * Execute async operation with retry on specific errors
- */
-export async function retryOnError<T>(
-  operation: () => Promise<T>,
-  retryableErrors: (string | number)[],
-  maxRetries = 3
-): Promise<T> {
-  return retryAsync(operation, maxRetries, 1000, (error) => {
-    const errorCode = error?.code || error?.status || error?.message;
-    return retryableErrors.includes(errorCode);
-  });
-}

package/src/utils/authHelpers.ts

@@ -38,14 +38,14 @@ export async function ensureValidToken(
   _activeSessionId: string | null | undefined,
   syncSession?: () => Promise<unknown>
 ): Promise<void> {
-  if (oxyServices.hasValidToken()) {
+  if (oxyServices.session.isAuthenticated) {
     return;
   }
 
   if (syncSession) {
     try {
       await syncSession();
-      if (oxyServices.hasValidToken()) {
+      if (oxyServices.session.isAuthenticated) {
         return;
       }
     } catch (syncError) {

package/src/utils/authWebUrl.ts

@@ -17,9 +17,8 @@
 export const CENTRAL_IDP_APEX = 'oxy.so';
 
 /**
- * The IdP's origin, `auth.oxy.so` — the OAuth authorize/consent surface and the
- * one origin that asserts Oxy passkeys: where a person signs in, creates,
- * recovers or deletes a web account, in the window an app opens (ADR 0029).
- * Apps open it; they never run the passkey themselves.
+ * The IdP's origin, `auth.oxy.so` — the OAuth authorize/consent surface for
+ * third parties, the browser bridge (ADR 0029 D2) and the page an email
+ * sign-in link opens. Official apps sign in inside their own dialog (ADR 0030).
  */
 export const AUTH_WEB_ORIGIN = `https://auth.${CENTRAL_IDP_APEX}`;

package/src/utils/avatarUtils.ts

@@ -1,11 +1,8 @@
 import { logger } from '../logger';
 
-/**
- * Minimal interface for services that can update asset visibility.
- * Kept loose to avoid mixin type-inference issues with the OxyServices class.
- */
+/** What `updateAvatarVisibility` needs of a client: `oxy.assets.setVisibility`. */
 export interface AssetVisibilityService {
-  assetUpdateVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
+  assets: { setVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown> };
 }
 
 /**
@@ -13,7 +10,7 @@ export interface AssetVisibilityService {
  * Logs non-404 errors to help debug upload issues.
  *
  * @param fileId - The file ID to update visibility for
- * @param oxyServices - OxyServices instance (or any object with assetUpdateVisibility)
+ * @param oxyServices - An OxyServices client
  * @param contextName - Context name for error logging
  */
 export async function updateAvatarVisibility(
@@ -26,7 +23,7 @@ export async function updateAvatarVisibility(
   }
 
   try {
-    await oxyServices.assetUpdateVisibility(fileId, 'public');
+    await oxyServices.assets.setVisibility(fileId, 'public');
   } catch (visError: unknown) {
     // 404 is expected when asset doesn't exist yet — skip logging
     const status = (visError instanceof Error && 'status' in visError)

package/src/utils/cache.ts

@@ -56,12 +56,17 @@ export class TTLCache<T> {
   private hits = 0;
   private misses = 0;
 
+  private maxEntries: number;
+
   /**
    * Create a new TTL cache
    * @param defaultTTL Default TTL in milliseconds (default: 5 minutes)
+   * @param maxEntries Bound on live entries; the least recently used is evicted
+   *   past it (default: 1000)
    */
-  constructor(defaultTTL: number = 5 * 60 * 1000) {
+  constructor(defaultTTL: number = 5 * 60 * 1000, maxEntries = 1000) {
     this.defaultTTL = defaultTTL;
+    this.maxEntries = maxEntries;
   }
 
   /**
@@ -83,6 +88,9 @@ export class TTLCache<T> {
       return null;
     }
 
+    // Re-insert so Map order is recency order and eviction drops the LRU.
+    this.cache.delete(key);
+    this.cache.set(key, entry);
     this.hits++;
     return entry.data;
   }
@@ -103,7 +111,12 @@ export class TTLCache<T> {
     // both into the default, making `cacheTTL:0` impossible to honor.
     const effectiveTTL = ttl === undefined ? this.defaultTTL : ttl;
     const expiresAt = now + effectiveTTL;
+    this.cache.delete(key);
     this.cache.set(key, { data, timestamp: now, expiresAt });
+    if (this.cache.size > this.maxEntries) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) this.cache.delete(oldest);
+    }
     if (!cleanupInterval && activeCaches.has(this)) updateCleanupInterval();
   }
 
@@ -114,7 +127,9 @@ export class TTLCache<T> {
    */
   delete(key: string): boolean {
     const deleted = this.cache.delete(key);
-    if (activeCaches.has(this)) updateCleanupInterval();
+    // Only the delete that EMPTIES this cache can let the timer stop; checking
+    // on every delete made bulk invalidation O(deletes x caches).
+    if (deleted && this.cache.size === 0 && activeCaches.has(this)) updateCleanupInterval();
     return deleted;
   }
 
@@ -128,6 +143,22 @@ export class TTLCache<T> {
     if (activeCaches.has(this)) updateCleanupInterval();
   }
 
+  /**
+   * Delete every entry whose key matches, in ONE pass.
+   * @returns Number of entries deleted
+   */
+  deleteWhere(match: (key: string) => boolean): number {
+    let removed = 0;
+    for (const key of this.cache.keys()) {
+      if (match(key)) {
+        this.cache.delete(key);
+        removed++;
+      }
+    }
+    if (removed > 0 && this.cache.size === 0 && activeCaches.has(this)) updateCleanupInterval();
+    return removed;
+  }
+
   /**
    * Check if a key exists and is not expired
    * @param key Cache key
@@ -228,13 +259,13 @@ export function createCache<T>(ttl: number = 5 * 60 * 1000): TTLCache<T> {
  * This helps prevent memory leaks from expired cache entries
  */
 let cleanupInterval: ReturnType<typeof setInterval> | null = null;
-const activeCaches = new Set<TTLCache<any>>();
+const activeCaches = new Set<TTLCache<unknown>>();
 
 /**
  * Register a cache for automatic cleanup
  * @param cache Cache instance to register
  */
-export function registerCacheForCleanup(cache: TTLCache<any>): void {
+export function registerCacheForCleanup(cache: TTLCache<unknown>): void {
   activeCaches.add(cache);
   updateCleanupInterval();
 }
@@ -256,7 +287,7 @@ function updateCleanupInterval(): void {
 }
 
 /** Unregister a cache without changing its entries or TTL behavior. */
-export function unregisterCacheFromCleanup(cache: TTLCache<any>): void {
+export function unregisterCacheFromCleanup(cache: TTLCache<unknown>): void {
   activeCaches.delete(cache);
   updateCleanupInterval();
 }

package/src/utils/cacheKey.ts

@@ -7,7 +7,7 @@
  * referentially transparent given that input.
  */
 
-import { jwtDecode } from 'jwt-decode';
+import { decodeTokenClaims } from './tokenClaims';
 
 /**
  * Minimal JWT payload shape we read for cache scoping. The identity discriminator
@@ -82,12 +82,8 @@ export function computeIdentityTag(accessToken: string | null): string {
   if (!accessToken) {
     return ANON_IDENTITY;
   }
-  try {
-    const decoded = jwtDecode<CacheIdentityJwtPayload>(accessToken);
-    return decoded.userId || decoded.id || `t${fnv1a32(accessToken)}`;
-  } catch {
-    // Undecodable token — still partition it away from anon and from other
-    // tokens via a hash. Never silently fall back to ANON_IDENTITY.
-    return `t${fnv1a32(accessToken)}`;
-  }
+  const decoded = decodeTokenClaims(accessToken);
+  // An undecodable token is still partitioned away from anon and from other
+  // tokens via a hash — never silently ANON_IDENTITY.
+  return (decoded?.userId as string | undefined) || (decoded?.id as string | undefined) || `t${fnv1a32(accessToken)}`;
 }

package/src/utils/commonsApproval.ts

@@ -1,4 +1,4 @@
-import type { PublicApplication } from '../mixins/OxyServices.connectedApps';
+import type { PublicApplication } from '../api/apps';
 
 export interface CommonsApprovalValidationInput {
   application: PublicApplication | null;