@oxy.so/core 1.0.0

package/src/utils/cache.ts

@@ -0,0 +1,273 @@
+/**
+ * Centralized cache utility with TTL support
+ * 
+ * This is a production-ready cache implementation used across the codebase
+ * for consistent caching behavior and performance optimization.
+ */
+
+/**
+ * Cache entry with expiration tracking
+ */
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  expiresAt: number;
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  size: number;
+  hits: number;
+  misses: number;
+  hitRate: number;
+}
+
+/**
+ * TTL-based cache implementation
+ * 
+ * Features:
+ * - Automatic expiration based on TTL
+ * - Manual cleanup of expired entries
+ * - Statistics tracking (hits, misses, hit rate)
+ * - Type-safe generic interface
+ * 
+ * @example
+ * ```typescript
+ * const cache = new TTLCache<string>(5 * 60 * 1000); // 5 minutes
+ * 
+ * // Set with default TTL
+ * cache.set('key', 'value');
+ * 
+ * // Set with custom TTL
+ * cache.set('key', 'value', 10 * 60 * 1000); // 10 minutes
+ * 
+ * // Get value
+ * const value = cache.get('key');
+ * 
+ * // Get statistics
+ * const stats = cache.getStats();
+ * ```
+ */
+export class TTLCache<T> {
+  private cache = new Map<string, CacheEntry<T>>();
+  private defaultTTL: number;
+  private hits = 0;
+  private misses = 0;
+
+  /**
+   * Create a new TTL cache
+   * @param defaultTTL Default TTL in milliseconds (default: 5 minutes)
+   */
+  constructor(defaultTTL: number = 5 * 60 * 1000) {
+    this.defaultTTL = defaultTTL;
+  }
+
+  /**
+   * Get a value from cache
+   * @param key Cache key
+   * @returns Cached value or null if not found or expired
+   */
+  get(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+
+    const now = Date.now();
+    if (now > entry.expiresAt) {
+      this.cache.delete(key);
+      this.misses++;
+      return null;
+    }
+
+    this.hits++;
+    return entry.data;
+  }
+
+  /**
+   * Set a value in cache
+   * @param key Cache key
+   * @param data Data to cache
+   * @param ttl Optional TTL override (uses default if not provided). An
+   *   explicit `0` or negative value is honored as "already expired" — the
+   *   entry is stored with `expiresAt <= now`, so the next `get`/`has` treats
+   *   it as a miss — rather than silently falling back to the default TTL.
+   */
+  set(key: string, data: T, ttl?: number): void {
+    const now = Date.now();
+    // Distinguish "no override provided" (undefined → use default) from an
+    // explicit `0`/negative (do not cache). `ttl || this.defaultTTL` collapsed
+    // both into the default, making `cacheTTL:0` impossible to honor.
+    const effectiveTTL = ttl === undefined ? this.defaultTTL : ttl;
+    const expiresAt = now + effectiveTTL;
+    this.cache.set(key, { data, timestamp: now, expiresAt });
+  }
+
+  /**
+   * Delete a specific cache entry
+   * @param key Cache key
+   * @returns true if entry was deleted, false if not found
+   */
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear(): void {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  /**
+   * Check if a key exists and is not expired
+   * @param key Cache key
+   * @returns true if key exists and is valid
+   */
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get all valid cache keys
+   * @returns Array of valid cache keys
+   */
+  keys(): string[] {
+    const now = Date.now();
+    const validKeys: string[] = [];
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (now <= entry.expiresAt) {
+        validKeys.push(key);
+      } else {
+        this.cache.delete(key);
+      }
+    }
+
+    return validKeys;
+  }
+
+  /**
+   * Clean up expired entries
+   * @returns Number of entries removed
+   */
+  cleanup(): number {
+    const now = Date.now();
+    let removed = 0;
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiresAt) {
+        this.cache.delete(key);
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+
+  /**
+   * Get cache size (number of entries)
+   */
+  size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): CacheStats {
+    const total = this.hits + this.misses;
+    return {
+      size: this.cache.size,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? this.hits / total : 0,
+    };
+  }
+
+  /**
+   * Reset statistics (keeps cache entries)
+   */
+  resetStats(): void {
+    this.hits = 0;
+    this.misses = 0;
+  }
+}
+
+/**
+ * Create a TTL cache instance (convenience function)
+ * 
+ * @example
+ * ```typescript
+ * const cache = createCache<string>(5 * 60 * 1000);
+ * ```
+ */
+export function createCache<T>(ttl: number = 5 * 60 * 1000): TTLCache<T> {
+  return new TTLCache<T>(ttl);
+}
+
+/**
+ * Global cache cleanup interval (runs every minute)
+ * This helps prevent memory leaks from expired cache entries
+ */
+let cleanupInterval: ReturnType<typeof setInterval> | null = null;
+const activeCaches = new Set<TTLCache<any>>();
+
+/**
+ * Register a cache for automatic cleanup
+ * @param cache Cache instance to register
+ */
+export function registerCacheForCleanup(cache: TTLCache<any>): void {
+  activeCaches.add(cache);
+
+  // Start cleanup interval if not already running
+  if (!cleanupInterval) {
+    cleanupInterval = setInterval(() => {
+      for (const cache of activeCaches) {
+        cache.cleanup();
+      }
+    }, 60000); // Every minute
+    // Never block process/worker exit on a housekeeping timer.
+    cleanupInterval.unref?.();
+  }
+}
+
+/**
+ * Unregister a cache from automatic cleanup
+ * @param cache Cache instance to unregister
+ */
+export function unregisterCacheFromCleanup(cache: TTLCache<any>): void {
+  activeCaches.delete(cache);
+
+  // Stop cleanup interval if no caches are registered
+  if (activeCaches.size === 0 && cleanupInterval) {
+    clearInterval(cleanupInterval);
+    cleanupInterval = null;
+  }
+}
+
+/**
+ * Stop all cleanup intervals (useful for testing)
+ * This will clear the interval and unregister all caches
+ */
+export function stopAllCleanupIntervals(): void {
+  if (cleanupInterval) {
+    clearInterval(cleanupInterval);
+    cleanupInterval = null;
+  }
+  activeCaches.clear();
+}
+

package/src/utils/cacheKey.ts

@@ -0,0 +1,93 @@
+/**
+ * Cache-key primitives for the identity-scoped HTTP GET response cache.
+ *
+ * Extracted from {@link HttpService} so the identity-tag derivation is a pure,
+ * independently testable function with no dependency on instance/token state.
+ * The HTTP service injects the live access token; everything here is
+ * referentially transparent given that input.
+ */
+
+import { jwtDecode } from 'jwt-decode';
+
+/**
+ * Minimal JWT payload shape we read for cache scoping. The identity discriminator
+ * comes from `userId` (preferred) or `id`; nothing else is consulted here.
+ */
+export interface CacheIdentityJwtPayload {
+  userId?: string;
+  id?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Discriminator used when there is no access token at all. Anonymous responses
+ * must never collide with any authenticated identity.
+ */
+export const ANON_IDENTITY = 'anon';
+
+/**
+ * FNV-1a 32-bit non-cryptographic hash.
+ *
+ * Used by the cache-key generator for large payloads where full JSON inclusion
+ * would balloon the cache map keys, and as the fallback discriminator for an
+ * undecodable access token. Content-addressed: every byte of the input
+ * contributes to the digest, so two inputs with the same top-level shape but
+ * different field values produce different keys (the previous `keys + length`
+ * heuristic collided on these).
+ *
+ * Trade-offs:
+ *  - 32 bits is ample for an in-process cache (collision risk negligible at our
+ *    key counts; we also prefix with method + url which further partitions the
+ *    keyspace).
+ *  - Not cryptographically secure — never use for security decisions.
+ *  - Zero dependencies, branch-free hot loop, ~1 GiB/s on V8.
+ */
+export function fnv1a32(str: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    // h * 16777619 mod 2^32, written as shift-and-add for portability and
+    // to avoid 53-bit JS number truncation in the intermediate multiply.
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/**
+ * Derive a stable, non-sensitive identity discriminator for cache scoping.
+ *
+ * The GET-response cache MUST be partitioned by caller identity: endpoints with
+ * optional auth (e.g. `GET /profiles/recommendations`) return different content
+ * for an anonymous vs an authenticated caller, and per-user content for
+ * different authenticated users. Keying solely on `method:url:data` let an
+ * anonymous response be served to an authenticated caller — surfacing as
+ * "Who to follow" recommending accounts the user already follows after a
+ * cold-boot session restore.
+ *
+ * Resolution order:
+ *  - no token            → {@link ANON_IDENTITY} (`'anon'`).
+ *  - decodable token     → the token's `userId || id`.
+ *  - undecodable token   → a short FNV-1a hash of the token, prefixed `t` so it
+ *                          can never collide with `'anon'` or a real user id.
+ *
+ * We use the decoded user id rather than the raw JWT so the token never lands
+ * in a cache key (no token leakage through any cache-key logging, no key bloat).
+ * Switching into a managed account mints a REAL new session whose access token
+ * carries the target account's id, so the identity tag changes naturally on a
+ * switch — there is no separate acting-as discriminator to fold in.
+ *
+ * @param accessToken The current bearer access token, or `null` when anonymous.
+ */
+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)}`;
+  }
+}

package/src/utils/coldBoot.ts

@@ -0,0 +1,218 @@
+/**
+ * coldBoot — a pure, ordered, short-circuit runner for "cold boot"
+ * authentication resolution.
+ *
+ * On a fresh page load / app launch the SDK may have several ways to recover an
+ * existing session (a persisted refresh-token family, a shared-keychain
+ * identity, a cross-domain boot-fragment return, ...). They must be attempted
+ * in a deterministic order, and the FIRST one that yields a session wins —
+ * every later step is skipped. This module encodes exactly that contract and
+ * nothing else.
+ *
+ * Design constraints (all enforced):
+ *   - PURE: no DOM, no `navigator`, no `window`, no React, no platform globals.
+ *   - NO module-level mutable state. Every call to {@link runColdBoot} is fully
+ *     self-contained, so it is safe under bundler re-evaluation (e.g. the Metro
+ *     web bundle — the reason any run-once guard for a step must live in the
+ *     calling consumer, never in a core module-level singleton).
+ *   - Architecture-agnostic: it knows nothing about HOW a step resolves a
+ *     session; `runSessionColdBoot` (`boot/sessionColdBoot.ts`) is the current
+ *     device-first consumer.
+ *
+ * A step is skipped (without running) when its `enabled` predicate returns
+ * false. Any thrown error — from either `enabled` or `run` — is reported via
+ * `onStepError` and treated as a non-fatal skip, so one broken recovery path
+ * can never prevent a later, healthy one from succeeding.
+ */
+
+/**
+ * A successful step result carrying the recovered session.
+ */
+export interface ColdBootSession<S> {
+  readonly kind: 'session';
+  readonly session: S;
+}
+
+/**
+ * A step result indicating this step has nothing to contribute; the runner
+ * should fall through to the next step.
+ */
+export interface ColdBootSkip {
+  readonly kind: 'skip';
+}
+
+/**
+ * The result of running a single cold-boot step.
+ */
+export type ColdBootStepResult<S> = ColdBootSession<S> | ColdBootSkip;
+
+/**
+ * A single ordered cold-boot recovery step.
+ */
+export interface ColdBootStep<S> {
+  /** Stable identifier; surfaced as {@link ColdBootOutcome.via} on success. */
+  readonly id: string;
+  /**
+   * Optional gate. When provided and it returns `false`, `run` is NOT called
+   * and the runner moves to the next step. A throw is treated as disabled
+   * (and reported via `onStepError`).
+   */
+  readonly enabled?: () => boolean;
+  /**
+   * Attempts to recover a session. Resolve with `{ kind: 'session' }` to win
+   * the cold boot, or `{ kind: 'skip' }` to defer to the next step. A throw is
+   * treated as a skip (and reported via `onStepError`).
+   */
+  readonly run: () => Promise<ColdBootStepResult<S>>;
+}
+
+/**
+ * The terminal outcome of a cold boot: either the winning step's session
+ * (with the step `id` it came from), or `unauthenticated` if every step
+ * skipped, was disabled, or errored.
+ */
+export type ColdBootOutcome<S> =
+  | { readonly kind: 'session'; readonly via: string; readonly session: S }
+  | { readonly kind: 'unauthenticated' };
+
+/**
+ * The unique sentinel a step's `run()` resolves to (via the internal race)
+ * when the overall cold-boot deadline expires before that step settled. It is
+ * NOT a {@link ColdBootStepResult} — the runner detects it by identity and
+ * treats it as "this step did not settle in time; move on".
+ *
+ * @internal
+ */
+const DEADLINE_EXPIRED: unique symbol = Symbol('coldBoot.deadlineExpired');
+
+/**
+ * Options for {@link runColdBoot}.
+ */
+export interface RunColdBootOptions<S> {
+  /** Ordered steps; evaluated front to back, first session wins. */
+  readonly steps: ReadonlyArray<ColdBootStep<S>>;
+  /**
+   * Optional observer invoked whenever a step's `enabled` or `run` throws.
+   * Receives the offending step `id` and the thrown value. Must not throw;
+   * the runner does not guard against an observer that itself throws.
+   */
+  readonly onStepError?: (id: string, error: unknown) => void;
+  /**
+   * Optional HARD overall deadline (ms) for the entire ordered step loop —
+   * defense-in-depth so a single non-settling step can NEVER hang the whole
+   * cold boot forever.
+   *
+   * Each step's `run()` is raced against the SHARED remaining time. If a step
+   * fails to settle before the deadline, the runner abandons the await for that
+   * step (reporting it via `onStepDeadline`) and CONTINUES to the next step,
+   * each now racing against an already-expired deadline. This is deliberate:
+   * the runner keeps iterating so the TERMINAL step (e.g. `sessionColdBoot`'s
+   * `bootstrap-hop`, whose `run()` performs its navigation side effect
+   * synchronously before its first `await`) still gets to fire. A step that
+   * has nothing to contribute after the deadline simply doesn't settle and is
+   * skipped in turn.
+   *
+   * Per-step timeouts inside `run()` remain the first line of defense and
+   * should keep every step well under this budget on a healthy load; this only
+   * trips when one of them regresses (a step hanging past its own timeout).
+   * When omitted there is no overall deadline.
+   */
+  readonly overallDeadlineMs?: number;
+  /**
+   * Optional observer invoked once per step that was abandoned because the
+   * overall deadline expired before it settled. Receives the step `id`. Must
+   * not throw.
+   */
+  readonly onStepDeadline?: (id: string) => void;
+}
+
+/**
+ * Run the ordered cold-boot steps and resolve to the first recovered session,
+ * or `unauthenticated` if none recovers one.
+ *
+ * Semantics:
+ *   1. Iterate `steps` in order.
+ *   2. If a step has an `enabled` predicate, call it inside try/catch:
+ *      - throw → report via `onStepError(id, err)` → treat as disabled → continue.
+ *      - returns false → continue (skip, `run` not called).
+ *   3. Otherwise await `step.run()` inside try/catch:
+ *      - throw → report via `onStepError(id, err)` → continue.
+ *      - `{ kind: 'session' }` → return `{ kind: 'session', via: step.id, session }`.
+ *      - `{ kind: 'skip' }` → continue.
+ *   4. After the loop with no winner → `{ kind: 'unauthenticated' }`.
+ */
+export async function runColdBoot<S>(
+  options: RunColdBootOptions<S>
+): Promise<ColdBootOutcome<S>> {
+  const { steps, onStepError, overallDeadlineMs, onStepDeadline } = options;
+
+  // Arm the optional overall deadline. The budget is SHARED across the whole
+  // loop (not reset per step): a single timer resolves a reusable
+  // `DEADLINE_EXPIRED` sentinel that every per-step race can observe. Once it
+  // fires, later steps race against an already-resolved promise and so never
+  // block, yet the loop keeps iterating so the terminal step still fires.
+  const deadlineMs =
+    typeof overallDeadlineMs === 'number' &&
+    Number.isFinite(overallDeadlineMs) &&
+    overallDeadlineMs > 0
+      ? overallDeadlineMs
+      : null;
+
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  let deadlinePromise: Promise<typeof DEADLINE_EXPIRED> | undefined;
+  if (deadlineMs !== null) {
+    deadlinePromise = new Promise<typeof DEADLINE_EXPIRED>((resolve) => {
+      deadlineTimer = setTimeout(() => resolve(DEADLINE_EXPIRED), deadlineMs);
+    });
+  }
+
+  try {
+    for (const step of steps) {
+      if (step.enabled) {
+        let isEnabled: boolean;
+        try {
+          isEnabled = step.enabled();
+        } catch (error) {
+          onStepError?.(step.id, error);
+          continue;
+        }
+        if (!isEnabled) continue;
+      }
+
+      let result: ColdBootStepResult<S> | typeof DEADLINE_EXPIRED;
+      try {
+        // Without a deadline, await the step directly. With a deadline, race
+        // the step against the shared deadline. The
+        // step's `run()` still STARTS synchronously up to its first `await`
+        // (so a terminal step's synchronous navigation side effect always
+        // executes), but a non-settling step can no longer block the loop —
+        // the race resolves with the sentinel and we move on.
+        result = deadlinePromise
+          ? await Promise.race([step.run(), deadlinePromise])
+          : await step.run();
+      } catch (error) {
+        onStepError?.(step.id, error);
+        continue;
+      }
+
+      if (result === DEADLINE_EXPIRED) {
+        // The deadline tripped before this step settled. Abandon the await and
+        // continue: subsequent steps race against the already-resolved deadline
+        // (so they cannot block), which lets a terminal side-effect step still
+        // run while guaranteeing the loop terminates promptly.
+        onStepDeadline?.(step.id);
+        continue;
+      }
+
+      if (result.kind === 'session') {
+        return { kind: 'session', via: step.id, session: result.session };
+      }
+    }
+
+    return { kind: 'unauthenticated' };
+  } finally {
+    if (deadlineTimer !== undefined) {
+      clearTimeout(deadlineTimer);
+    }
+  }
+}

package/src/utils/commonsApproval.ts

@@ -0,0 +1,39 @@
+import type { PublicApplication } from '../mixins/OxyServices.connectedApps';
+
+export interface CommonsApprovalValidationInput {
+  application: PublicApplication | null;
+  status: string;
+  expiresAt: number | string;
+}
+
+/**
+ * Returns a user-facing blocking reason when an approval payload must not be
+ * shown as actionable, or `null` when the request is still pending and valid.
+ */
+export function getCommonsApprovalBlockingReason(
+  info: CommonsApprovalValidationInput,
+): string | null {
+  if (!info.application?.id) {
+    return 'The requesting application could not be resolved.';
+  }
+  if (info.status !== 'pending') {
+    return 'This sign-in request is invalid, already used, or expired.';
+  }
+  const expiresAtMs = parseCommonsApprovalExpiresAt(info.expiresAt);
+  if (expiresAtMs !== null && expiresAtMs < Date.now()) {
+    return 'This sign-in request has expired. Ask for a new QR code.';
+  }
+  return null;
+}
+
+/** Normalize API `expiresAt` (number or ISO string) to epoch ms. */
+export function parseCommonsApprovalExpiresAt(
+  expiresAt: CommonsApprovalValidationInput['expiresAt'],
+): number | null {
+  if (typeof expiresAt === 'number' && Number.isFinite(expiresAt)) return expiresAt;
+  if (typeof expiresAt === 'string') {
+    const ms = Date.parse(expiresAt);
+    return Number.isFinite(ms) ? ms : null;
+  }
+  return null;
+}