@oxy.so/core 1.0.0

package/dist/esm/utils/cache.js

@@ -0,0 +1,227 @@
+/**
+ * Centralized cache utility with TTL support
+ *
+ * This is a production-ready cache implementation used across the codebase
+ * for consistent caching behavior and performance optimization.
+ */
+/**
+ * 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 {
+    /**
+     * Create a new TTL cache
+     * @param defaultTTL Default TTL in milliseconds (default: 5 minutes)
+     */
+    constructor(defaultTTL = 5 * 60 * 1000) {
+        this.cache = new Map();
+        this.hits = 0;
+        this.misses = 0;
+        this.defaultTTL = defaultTTL;
+    }
+    /**
+     * Get a value from cache
+     * @param key Cache key
+     * @returns Cached value or null if not found or expired
+     */
+    get(key) {
+        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, data, ttl) {
+        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) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all cache entries
+     */
+    clear() {
+        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) {
+        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() {
+        const now = Date.now();
+        const validKeys = [];
+        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() {
+        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() {
+        return this.cache.size;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        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() {
+        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(ttl = 5 * 60 * 1000) {
+    return new TTLCache(ttl);
+}
+/**
+ * Global cache cleanup interval (runs every minute)
+ * This helps prevent memory leaks from expired cache entries
+ */
+let cleanupInterval = null;
+const activeCaches = new Set();
+/**
+ * Register a cache for automatic cleanup
+ * @param cache Cache instance to register
+ */
+export function registerCacheForCleanup(cache) {
+    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) {
+    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() {
+    if (cleanupInterval) {
+        clearInterval(cleanupInterval);
+        cleanupInterval = null;
+    }
+    activeCaches.clear();
+}

package/dist/esm/utils/cacheKey.js

@@ -0,0 +1,80 @@
+/**
+ * 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';
+/**
+ * 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) {
+    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) {
+    if (!accessToken) {
+        return ANON_IDENTITY;
+    }
+    try {
+        const decoded = jwtDecode(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/dist/esm/utils/coldBoot.js

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+/**
+ * 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 = Symbol('coldBoot.deadlineExpired');
+/**
+ * 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(options) {
+    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;
+    let deadlinePromise;
+    if (deadlineMs !== null) {
+        deadlinePromise = new Promise((resolve) => {
+            deadlineTimer = setTimeout(() => resolve(DEADLINE_EXPIRED), deadlineMs);
+        });
+    }
+    try {
+        for (const step of steps) {
+            if (step.enabled) {
+                let isEnabled;
+                try {
+                    isEnabled = step.enabled();
+                }
+                catch (error) {
+                    onStepError?.(step.id, error);
+                    continue;
+                }
+                if (!isEnabled)
+                    continue;
+            }
+            let result;
+            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/dist/esm/utils/commonsApproval.js

@@ -0,0 +1,27 @@
+/**
+ * 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) {
+    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) {
+    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;
+}

package/dist/esm/utils/commonsDelivery.js

@@ -0,0 +1,54 @@
+import { getPlatformOS } from './platform.js';
+/**
+ * Choose the ONE primary delivery route for a "Sign in with Oxy" request.
+ *
+ * Decision order (issue #691, "Automatic delivery selection"):
+ *
+ *  1. Mobile with a verified Commons link available → open Commons directly.
+ *     No push is needed when the identity is already reachable on this device.
+ *  2. At least one eligible Commons installation was pushed to → await the push.
+ *  3. Otherwise → QR.
+ *
+ * A caller that already knows it is on step 1 does not need to call
+ * `deliverCommonsSignIn` at all; every other caller runs the delivery
+ * round-trip first and passes its `targets` in here.
+ *
+ * `pushTargets` is server-derived, so it is validated rather than trusted: a
+ * negative, fractional, non-finite, or otherwise malformed count is treated as
+ * "no targets" and degrades to QR instead of parking the user on a "check your
+ * phone" screen that nothing will ever wake.
+ */
+export function selectCommonsDelivery(facts) {
+    if (facts.platform === 'mobile' && facts.commonsAvailable) {
+        return 'open-commons';
+    }
+    if (Number.isInteger(facts.pushTargets) && facts.pushTargets >= 1) {
+        return 'await-push';
+    }
+    return 'qr';
+}
+/**
+ * Map a `deliverCommonsSignIn` result onto the `pushTargets` fact for
+ * {@link selectCommonsDelivery}. The server reports eligible install *count*
+ * separately from whether any push was accepted — a transport failure can leave
+ * `delivered: false` with `targets > 0`, which must NOT park the user on
+ * "check your phone".
+ */
+export function pushTargetsFromDelivery(result) {
+    return result.delivered ? result.targets : 0;
+}
+/**
+ * Classify the current runtime surface for delivery selection. Callers that
+ * cannot confidently detect the platform should not use this — pass
+ * `'unknown'` explicitly instead.
+ */
+export function commonsDeliveryPlatform() {
+    const os = getPlatformOS();
+    if (os === 'ios' || os === 'android') {
+        return 'mobile';
+    }
+    if (os === 'web') {
+        return 'desktop';
+    }
+    return 'unknown';
+}

package/dist/esm/utils/deviceManager.js

@@ -0,0 +1,170 @@
+import { loadAsyncStorage } from '@oxy.so/protocol';
+import { createLogger } from '../logger/index.js';
+const log = createLogger('DeviceManager');
+/**
+ * Client-side device management utility
+ * Handles persistent device identification across app sessions
+ */
+export class DeviceManager {
+    /**
+     * Check if we're in React Native environment
+     */
+    static isReactNative() {
+        return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+    }
+    /**
+     * Get appropriate storage for the platform
+     */
+    static async getStorage() {
+        if (this.isReactNative()) {
+            try {
+                // `loadAsyncStorage` is per-platform: the RN variant statically imports
+                // @react-native-async-storage/async-storage, the default variant throws
+                // (never called outside RN because of the `isReactNative()` gate above).
+                const asyncStorageModule = await loadAsyncStorage();
+                const storage = asyncStorageModule.default;
+                return {
+                    getItem: storage.getItem.bind(storage),
+                    setItem: storage.setItem.bind(storage),
+                    removeItem: storage.removeItem.bind(storage),
+                };
+            }
+            catch (error) {
+                log.error('AsyncStorage not available in React Native', error);
+                throw new Error('AsyncStorage is required in React Native environment');
+            }
+        }
+        else {
+            // Use localStorage for web
+            return {
+                getItem: async (key) => localStorage.getItem(key),
+                setItem: async (key, value) => localStorage.setItem(key, value),
+                removeItem: async (key) => localStorage.removeItem(key)
+            };
+        }
+    }
+    /**
+     * Get or create device fingerprint for current device
+     */
+    static getDeviceFingerprint() {
+        const fingerprint = {
+            userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'unknown',
+            platform: typeof navigator !== 'undefined' ? navigator.platform : 'unknown',
+            language: typeof navigator !== 'undefined' ? navigator.language : undefined,
+            timezone: typeof Intl !== 'undefined' ? Intl.DateTimeFormat().resolvedOptions().timeZone : undefined,
+        };
+        // Add screen info if available
+        if (typeof screen !== 'undefined') {
+            fingerprint.screen = {
+                width: screen.width,
+                height: screen.height,
+                colorDepth: screen.colorDepth
+            };
+        }
+        return fingerprint;
+    }
+    /**
+     * Get stored device info or create new one
+     */
+    static async getDeviceInfo() {
+        try {
+            const storage = await this.getStorage();
+            const stored = await storage.getItem(this.DEVICE_KEY);
+            if (stored) {
+                const deviceInfo = JSON.parse(stored);
+                // Update last used timestamp
+                deviceInfo.lastUsed = new Date().toISOString();
+                await this.saveDeviceInfo(deviceInfo);
+                return deviceInfo;
+            }
+            // Create new device info
+            return await this.createNewDeviceInfo();
+        }
+        catch (error) {
+            log.error('Error getting device info', error);
+            return await this.createNewDeviceInfo();
+        }
+    }
+    /**
+     * Create new device info and store it
+     */
+    static async createNewDeviceInfo() {
+        const deviceInfo = {
+            deviceId: this.generateDeviceId(),
+            fingerprint: JSON.stringify(this.getDeviceFingerprint()),
+            createdAt: new Date().toISOString(),
+            lastUsed: new Date().toISOString()
+        };
+        await this.saveDeviceInfo(deviceInfo);
+        return deviceInfo;
+    }
+    /**
+     * Save device info to storage
+     */
+    static async saveDeviceInfo(deviceInfo) {
+        try {
+            const storage = await this.getStorage();
+            await storage.setItem(this.DEVICE_KEY, JSON.stringify(deviceInfo));
+        }
+        catch (error) {
+            log.error('Error saving device info', error);
+        }
+    }
+    /**
+     * Update device name
+     */
+    static async updateDeviceName(deviceName) {
+        try {
+            const deviceInfo = await this.getDeviceInfo();
+            deviceInfo.deviceName = deviceName;
+            await this.saveDeviceInfo(deviceInfo);
+        }
+        catch (error) {
+            log.error('Error updating device name', error);
+        }
+    }
+    /**
+     * Clear stored device info (useful for testing or reset)
+     */
+    static async clearDeviceInfo() {
+        try {
+            const storage = await this.getStorage();
+            await storage.removeItem(this.DEVICE_KEY);
+        }
+        catch (error) {
+            log.error('Error clearing device info', error);
+        }
+    }
+    /**
+     * Generate a unique device ID
+     */
+    static generateDeviceId() {
+        if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+            const array = new Uint8Array(32);
+            crypto.getRandomValues(array);
+            return Array.from(array, byte => byte.toString(16).padStart(2, '0')).join('');
+        }
+        throw new Error('No secure random source available for device ID generation');
+    }
+    /**
+     * Get a user-friendly device name based on platform
+     */
+    static getDefaultDeviceName() {
+        const fingerprint = this.getDeviceFingerprint();
+        const platform = (fingerprint.platform || '').toLowerCase();
+        if (platform.includes('win'))
+            return 'Windows Computer';
+        if (platform.includes('mac'))
+            return 'Mac Computer';
+        if (platform.includes('linux'))
+            return 'Linux Computer';
+        if (platform.includes('iphone'))
+            return 'iPhone';
+        if (platform.includes('ipad'))
+            return 'iPad';
+        if (platform.includes('android'))
+            return 'Android Device';
+        return 'Unknown Device';
+    }
+}
+DeviceManager.DEVICE_KEY = 'oxy_device_info';