@oxy.so/core 1.0.0

package/dist/cjs/utils/authHelpers.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Authentication helper utilities for common token validation
+ * and authentication error handling patterns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthenticationFailedError = exports.SessionSyncRequiredError = void 0;
+exports.ensureValidToken = ensureValidToken;
+exports.isAuthenticationError = isAuthenticationError;
+exports.withAuthErrorHandling = withAuthErrorHandling;
+exports.authenticatedApiCall = authenticatedApiCall;
+/**
+ * Error thrown when session sync is required
+ */
+class SessionSyncRequiredError extends Error {
+    constructor(message = 'Session needs to be synced. Please try again.') {
+        super(message);
+        this.name = 'SessionSyncRequiredError';
+    }
+}
+exports.SessionSyncRequiredError = SessionSyncRequiredError;
+/**
+ * Error thrown when authentication fails
+ */
+class AuthenticationFailedError extends Error {
+    constructor(message = 'Authentication failed. Please sign in again.') {
+        super(message);
+        this.name = 'AuthenticationFailedError';
+    }
+}
+exports.AuthenticationFailedError = AuthenticationFailedError;
+/**
+ * Ensures a valid token exists before making authenticated API calls.
+ * If no valid token exists, callers may provide a session synchronizer that
+ * uses the platform-appropriate new flow (cookie restore, device claim, or
+ * native secure restore). This helper never exchanges a session id for a token.
+ *
+ * @throws {SessionSyncRequiredError} If the session needs to be synced (offline session)
+ */
+async function ensureValidToken(oxyServices, _activeSessionId, syncSession) {
+    if (oxyServices.hasValidToken()) {
+        return;
+    }
+    if (syncSession) {
+        try {
+            await syncSession();
+            if (oxyServices.hasValidToken()) {
+                return;
+            }
+        }
+        catch (syncError) {
+            const errorMessage = syncError instanceof Error ? syncError.message : String(syncError);
+            if (errorMessage.includes('AUTH_REQUIRED_OFFLINE_SESSION') || errorMessage.includes('offline')) {
+                throw new SessionSyncRequiredError();
+            }
+            throw syncError;
+        }
+    }
+    throw new SessionSyncRequiredError('No active access token is available. Sync the session before calling authenticated APIs.');
+}
+/**
+ * Checks if an error is an authentication error (401 or auth-related message)
+ */
+function isAuthenticationError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const errorObj = error;
+    const errorMessage = errorObj.message || '';
+    const status = errorObj.status || errorObj.response?.status;
+    return (status === 401 ||
+        errorMessage.includes('Authentication required') ||
+        errorMessage.includes('Invalid or missing authorization header'));
+}
+/**
+ * Wraps an API call with authentication error handling.
+ * On auth failure, optionally attempts to sync the session and retry.
+ *
+ * @throws {AuthenticationFailedError} If authentication fails and cannot be recovered
+ */
+async function withAuthErrorHandling(apiCall, options) {
+    try {
+        return await apiCall();
+    }
+    catch (error) {
+        if (!isAuthenticationError(error)) {
+            throw error;
+        }
+        if (options?.syncSession && options?.oxyServices) {
+            try {
+                await options.syncSession();
+                return await apiCall();
+            }
+            catch {
+                throw new AuthenticationFailedError();
+            }
+        }
+        throw new AuthenticationFailedError();
+    }
+}
+/**
+ * Combines token validation and auth error handling for a complete authenticated API call.
+ *
+ * @example
+ * ```ts
+ * return await authenticatedApiCall(
+ *   oxyServices,
+ *   activeSessionId,
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ * ```
+ */
+async function authenticatedApiCall(oxyServices, activeSessionId, apiCall, syncSession) {
+    await ensureValidToken(oxyServices, activeSessionId, syncSession);
+    return withAuthErrorHandling(apiCall, {
+        syncSession,
+        activeSessionId,
+        oxyServices,
+    });
+}

package/dist/cjs/utils/authWebUrl.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Central IdP apex constant.
+ *
+ * The client SSO/FedCM resolvers (`resolveCentralAuthUrl`, `CENTRAL_AUTH_URL`)
+ * were removed in the device-first / legacy-final cutovers. The lone survivor is
+ * `CENTRAL_IDP_APEX`, kept because it has a LIVE consumer —
+ * `@oxy.so/core/server`'s CORS helper (`server/cors.ts`'s `createOxyCors`)
+ * auto-allows `*.oxy.so` from it. That CORS use is permanent, so this stays
+ * past the SSO/FedCM teardown.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CENTRAL_IDP_APEX = void 0;
+/**
+ * The registrable apex (eTLD+1) of the Oxy ecosystem's central Identity
+ * Provider, reachable at `auth.${CENTRAL_IDP_APEX}`. Single source of truth so
+ * the CORS helper (and anything else that needs the central apex) never drifts.
+ */
+exports.CENTRAL_IDP_APEX = 'oxy.so';

package/dist/cjs/utils/avatarUtils.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateAvatarVisibility = updateAvatarVisibility;
+const logger_1 = require("../logger");
+/**
+ * Updates file visibility to public for avatar use.
+ * 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 contextName - Context name for error logging
+ */
+async function updateAvatarVisibility(fileId, oxyServices, contextName = 'AvatarUtils') {
+    if (!fileId || fileId.startsWith('temp-')) {
+        return;
+    }
+    try {
+        await oxyServices.assetUpdateVisibility(fileId, 'public');
+    }
+    catch (visError) {
+        // 404 is expected when asset doesn't exist yet — skip logging
+        const status = (visError instanceof Error && 'status' in visError)
+            ? visError.status
+            : undefined;
+        if (status !== 404) {
+            logger_1.logger.error(`[${contextName}] Failed to update avatar visibility for ${fileId}`, visError, { component: contextName });
+        }
+    }
+}

package/dist/cjs/utils/cache.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * Centralized cache utility with TTL support
+ *
+ * This is a production-ready cache implementation used across the codebase
+ * for consistent caching behavior and performance optimization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTLCache = void 0;
+exports.createCache = createCache;
+exports.registerCacheForCleanup = registerCacheForCleanup;
+exports.unregisterCacheFromCleanup = unregisterCacheFromCleanup;
+exports.stopAllCleanupIntervals = stopAllCleanupIntervals;
+/**
+ * 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();
+ * ```
+ */
+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;
+    }
+}
+exports.TTLCache = TTLCache;
+/**
+ * Create a TTL cache instance (convenience function)
+ *
+ * @example
+ * ```typescript
+ * const cache = createCache<string>(5 * 60 * 1000);
+ * ```
+ */
+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
+ */
+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
+ */
+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
+ */
+function stopAllCleanupIntervals() {
+    if (cleanupInterval) {
+        clearInterval(cleanupInterval);
+        cleanupInterval = null;
+    }
+    activeCaches.clear();
+}

package/dist/cjs/utils/cacheKey.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANON_IDENTITY = void 0;
+exports.fnv1a32 = fnv1a32;
+exports.computeIdentityTag = computeIdentityTag;
+const jwt_decode_1 = require("jwt-decode");
+/**
+ * Discriminator used when there is no access token at all. Anonymous responses
+ * must never collide with any authenticated identity.
+ */
+exports.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.
+ */
+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.
+ */
+function computeIdentityTag(accessToken) {
+    if (!accessToken) {
+        return exports.ANON_IDENTITY;
+    }
+    try {
+        const decoded = (0, jwt_decode_1.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/cjs/utils/coldBoot.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runColdBoot = runColdBoot;
+/**
+ * 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' }`.
+ */
+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/cjs/utils/commonsApproval.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommonsApprovalBlockingReason = getCommonsApprovalBlockingReason;
+exports.parseCommonsApprovalExpiresAt = parseCommonsApprovalExpiresAt;
+/**
+ * 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.
+ */
+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. */
+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;
+}