@oxy.so/core 1.0.0

package/dist/cjs/utils/officialOrigins.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Official first-party web origin allowlist — shared by OAuth redirect
+ * validation and the server-side trusted-origin checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAllowedDeviceJoinOrigin = void 0;
+exports.isLoopbackOrigin = isLoopbackOrigin;
+exports.isOfficialWebOrigin = isOfficialWebOrigin;
+const authWebUrl_1 = require("./authWebUrl");
+const registrableApex_1 = require("./registrableApex");
+/** Official first-party registrable apexes (mirrors API trusted origins). */
+const OFFICIAL_APEXES = new Set([
+    'oxy.so',
+    'fairco.in',
+    'mention.earth',
+    'homiio.com',
+    'alia.onl',
+    'syra.fm',
+    'allo.you',
+    'tnp.network',
+    'moovo.now',
+    'mercaria.co',
+]);
+/**
+ * Whether an origin is a loopback / local-dev origin (`localhost`, `127.0.0.1`,
+ * or `[::1]` on any port, http or https).
+ */
+function isLoopbackOrigin(origin) {
+    try {
+        const parsed = new URL(origin);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            return false;
+        }
+        const host = parsed.hostname.toLowerCase();
+        return host === 'localhost' || host === '127.0.0.1' || host === '[::1]';
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether an origin belongs to the official Oxy web ecosystem. */
+function isOfficialWebOrigin(origin) {
+    if (isLoopbackOrigin(origin)) {
+        return true;
+    }
+    try {
+        const parsed = new URL(origin);
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+            return false;
+        }
+        const host = parsed.hostname.toLowerCase();
+        if (host === authWebUrl_1.CENTRAL_IDP_APEX || host.endsWith(`.${authWebUrl_1.CENTRAL_IDP_APEX}`)) {
+            return true;
+        }
+        const apex = (0, registrableApex_1.registrableApex)(host);
+        return apex != null && OFFICIAL_APEXES.has(apex);
+    }
+    catch {
+        return false;
+    }
+}
+/** @deprecated Use {@link isOfficialWebOrigin}. */
+exports.isAllowedDeviceJoinOrigin = isOfficialWebOrigin;

package/dist/cjs/utils/oxyServiceEnvironment.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OXY_SERVICE_ENVIRONMENTS = void 0;
+/**
+ * Environment segregation for Oxy service-token JWTs (test/live isolation).
+ * Mirrors `ApplicationCredentialEnvironment` on the API's `ApplicationCredential`
+ * model (`packages/api/src/models/ApplicationCredential.ts`) as an INDEPENDENT
+ * literal union — `@oxy.so/core` has zero dependency on `@oxy.so/api`, so this is
+ * kept in sync by hand, not by import.
+ *
+ * Defined here (not in `server/auth.ts` or `mixins/OxyServices.utility.ts`
+ * directly) because BOTH of those files need it and neither may import from
+ * the other: `server/` types import `express` (Node-only, a peer dependency
+ * `mixins/` deliberately avoids so it stays safe to bundle into RN/browser
+ * consumers — see the "Local request/response/socket typing" comment in
+ * `OxyServices.utility.ts`). This file has zero imports, so both sides can
+ * depend on it without crossing that boundary.
+ */
+exports.OXY_SERVICE_ENVIRONMENTS = ['development', 'staging', 'production'];

package/dist/cjs/utils/platform.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Platform Detection Utility
+ *
+ * Provides platform detection WITHOUT importing from 'react-native'.
+ * This allows core modules to be used in web/Node.js environments
+ * without bundlers failing on react-native imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPlatformOS = getPlatformOS;
+exports.isWeb = isWeb;
+exports.isNative = isNative;
+exports.isIOS = isIOS;
+exports.isAndroid = isAndroid;
+exports.setPlatformOS = setPlatformOS;
+exports.isWebBrowser = isWebBrowser;
+/**
+ * Typed view over `globalThis` for the RN-platform marker, avoiding an `any`
+ * cast at each access site.
+ */
+function rnPlatformGlobal() {
+    return globalThis;
+}
+/**
+ * Detect the current platform without importing react-native
+ *
+ * Detection order:
+ * 1. Check for React Native's Platform object on globalThis (set by RN runtime)
+ * 2. Check for Node.js environment
+ * 3. Check for browser environment
+ * 4. Fall back to 'unknown'
+ */
+function detectPlatform() {
+    // Check if React Native Platform is available globally (set by RN runtime)
+    // This avoids static imports while still detecting RN environment
+    const rnPlatform = rnPlatformGlobal().__REACT_NATIVE_PLATFORM__;
+    if (rnPlatform) {
+        return rnPlatform;
+    }
+    // Check navigator.product for React Native
+    if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+        // We're in React Native but Platform wasn't set globally
+        // Try to get OS from userAgent or default to 'unknown'
+        return 'unknown';
+    }
+    // Check for Node.js environment
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        return 'web'; // Treat Node.js as 'web' for compatibility (no native features)
+    }
+    // Check for browser/web environment
+    if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+        return 'web';
+    }
+    return 'unknown';
+}
+// Cache the platform detection result
+let cachedPlatform = null;
+/**
+ * Get the current platform OS
+ * Safe to call from any environment (web, Node.js, React Native)
+ */
+function getPlatformOS() {
+    if (cachedPlatform === null) {
+        cachedPlatform = detectPlatform();
+    }
+    return cachedPlatform;
+}
+/**
+ * Check if running on web platform (browser or Node.js)
+ */
+function isWeb() {
+    return getPlatformOS() === 'web';
+}
+/**
+ * Check if running in a native app (iOS or Android)
+ */
+function isNative() {
+    const os = getPlatformOS();
+    return os === 'ios' || os === 'android';
+}
+/**
+ * Check if running on iOS
+ */
+function isIOS() {
+    return getPlatformOS() === 'ios';
+}
+/**
+ * Check if running on Android
+ */
+function isAndroid() {
+    return getPlatformOS() === 'android';
+}
+/**
+ * Set the platform OS explicitly
+ * Called by React Native entry point to register the platform
+ * This allows lazy detection in environments where react-native is available
+ */
+function setPlatformOS(os) {
+    cachedPlatform = os;
+    rnPlatformGlobal().__REACT_NATIVE_PLATFORM__ = os;
+}
+/**
+ * True only in a real web browser (a DOM is present), false on React Native
+ * and Node/SSR.
+ *
+ * Native defines a global `window` but no `document`, so the DOM probe — not a
+ * bare `window` check — is the reliable discriminator. This is the single
+ * source of truth consumed by `@oxy.so/services` (which dropped
+ * their local copies), so every consumer shares the exact same predicate.
+ *
+ * NOTE: this is a live runtime probe (not the cached `getPlatformOS()` verdict)
+ * because it must reflect the actual DOM availability at call time in the
+ * consumer's bundle.
+ */
+function isWebBrowser() {
+    return (typeof window !== 'undefined' &&
+        typeof document !== 'undefined' &&
+        typeof document.documentElement !== 'undefined');
+}

package/dist/cjs/utils/profileLinks.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeProfileLinks = normalizeProfileLinks;
+function cleanUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Normalizes a user's profile links into a clean display shape.
+ *
+ * Pure, no side effects, no I/O.
+ *
+ * - Prefers `linksMetadata` when it is a non-empty array: maps each entry to
+ *   `{ id, title, url, description, image }`, using `entry.id` when present and
+ *   falling back to the entry index. `title`, `description`, and `image` are
+ *   carried through only when they are present strings. Entries without a
+ *   non-empty string `url` are dropped.
+ * - Otherwise falls back to the legacy `links` string array: maps each string to
+ *   `{ id: <index>, url }` (no title/description/image). Empty/non-string values
+ *   are dropped.
+ * - Returns `[]` when both are absent or empty (including when `linksMetadata`
+ *   is present but every entry is dropped — it does NOT fall back to `links`).
+ *
+ * URLs are trimmed and blanks are filtered out. This does NOT add a scheme such
+ * as `https://`; prefixing is a display concern left to the caller.
+ */
+function normalizeProfileLinks(linksMetadata, links) {
+    if (Array.isArray(linksMetadata) && linksMetadata.length > 0) {
+        const result = [];
+        linksMetadata.forEach((entry, index) => {
+            const url = cleanUrl(entry?.url);
+            if (!url)
+                return;
+            const id = typeof entry?.id === 'string' && entry.id.trim().length > 0
+                ? entry.id
+                : String(index);
+            const title = typeof entry?.title === 'string' ? entry.title : undefined;
+            const description = typeof entry?.description === 'string' ? entry.description : undefined;
+            const image = typeof entry?.image === 'string' ? entry.image : undefined;
+            result.push({
+                id,
+                url,
+                ...(title !== undefined ? { title } : {}),
+                ...(description !== undefined ? { description } : {}),
+                ...(image !== undefined ? { image } : {}),
+            });
+        });
+        return result;
+    }
+    if (Array.isArray(links) && links.length > 0) {
+        const result = [];
+        links.forEach((value, index) => {
+            const url = cleanUrl(value);
+            if (!url)
+                return;
+            result.push({ id: String(index), url });
+        });
+        return result;
+    }
+    return [];
+}

package/dist/cjs/utils/redactUrl.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactUrlQuery = redactUrlQuery;
+/**
+ * URL redaction for logging.
+ *
+ * Asset URLs the API hands back for private assets carry a scoped, short-lived
+ * media token (`mt=…`) in their query string. That token is a bearer credential
+ * for the underlying object, so it must never land in a log line, breadcrumb,
+ * or metric — a captured log would otherwise grant read access until the token
+ * expires. Query strings on API URLs can also carry other sensitive params, so
+ * we redact the whole query rather than allow-listing one key.
+ *
+ * `redactUrlQuery` returns the URL's path portion with a `?<redacted>` marker
+ * when a query string is present, and the input unchanged otherwise. It is
+ * defensive: any input that does not parse as a URL is passed through as-is,
+ * except that a bare `?query` tail is still stripped so a relative path with a
+ * query never leaks.
+ */
+function redactUrlQuery(url) {
+    if (typeof url !== 'string' || url.length === 0) {
+        return url;
+    }
+    const queryIndex = url.indexOf('?');
+    if (queryIndex === -1) {
+        return url;
+    }
+    return `${url.slice(0, queryIndex)}?<redacted>`;
+}

package/dist/cjs/utils/registrableApex.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Registrable-apex (eTLD+1) host kernel.
+ *
+ * The client FAPI auto-detection helper was removed in the device-first cutover
+ * (which is why this file is now named for what it actually is, not the old
+ * `fapiAutoDetect`). What survives is the pure registrable-domain kernel, still
+ * used by the `@oxy.so/core/server` CORS layer (the `*.oxy.so` same-apex trust
+ * check) and its re-export surface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registrableApex = registrableApex;
+const tldts_1 = require("tldts");
+/**
+ * Compute the bare registrable apex (eTLD+1) of a hostname using the Public
+ * Suffix List, including private hosted suffixes.
+ *
+ * Performs NO protocol handling and builds NO URL — it only answers "what is
+ * the registrable domain of this host, or is that undefinable?".
+ *
+ * Returns `null` (apex undefinable) for:
+ *   - empty input;
+ *   - IPv4 literals (`192.168.1.10`);
+ *   - IPv6 literals or any host carrying a port (`[::1]`, anything with `:`);
+ *   - single-label hosts (`intranet`, `localhost`);
+ *   - public suffixes without a registrable label (e.g. `co.uk`, `github.io`).
+ *
+ * @param hostname - A bare hostname (no scheme), e.g. `www.mention.earth`.
+ * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.
+ */
+function registrableApex(hostname) {
+    if (!hostname)
+        return null;
+    const host = hostname.toLowerCase();
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(host))
+        return null;
+    // IPv6 literals are bracketed; any remaining ':' implies a port — neither
+    // yields a registrable apex.
+    if (host.startsWith('[') || host.includes(':'))
+        return null;
+    // The Public Suffix List (private suffixes included) is the source of truth
+    // for what an attacker can register. A multi-part public suffix like `co.uk`
+    // or a hosted suffix like `github.io` returns no registrable domain.
+    return (0, tldts_1.getDomain)(host, { allowPrivateDomains: true });
+}

package/dist/cjs/utils/requestUtils.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * Request utilities for HTTP clients
+ *
+ * Provides reusable components for request deduplication, queuing, and logging
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleLogger = exports.RequestQueue = exports.RequestDeduplicator = void 0;
+/**
+ * Request deduplication - prevents duplicate concurrent requests
+ *
+ * When multiple requests with the same key are made simultaneously,
+ * only one request is executed and all callers receive the same result.
+ *
+ * @example
+ * ```typescript
+ * const deduplicator = new RequestDeduplicator();
+ *
+ * // Multiple calls with same key will share the same promise
+ * const promise1 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * const promise2 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * // promise1 === promise2, only one API call is made
+ * ```
+ */
+class RequestDeduplicator {
+    constructor() {
+        this.pendingRequests = new Map();
+    }
+    /**
+     * Deduplicate a request by key
+     * @param key Unique key for the request
+     * @param requestFn Function that returns a promise
+     * @returns Promise that will be shared if key already exists
+     */
+    async deduplicate(key, requestFn) {
+        const existing = this.pendingRequests.get(key);
+        if (existing) {
+            return existing;
+        }
+        const promise = requestFn()
+            .finally(() => {
+            this.pendingRequests.delete(key);
+        });
+        this.pendingRequests.set(key, promise);
+        return promise;
+    }
+    /**
+     * Clear all pending requests
+     */
+    clear() {
+        this.pendingRequests.clear();
+    }
+    /**
+     * Get number of pending requests
+     */
+    size() {
+        return this.pendingRequests.size;
+    }
+}
+exports.RequestDeduplicator = RequestDeduplicator;
+/**
+ * Request queue with concurrency control
+ *
+ * Limits the number of concurrent requests and queues excess requests.
+ * Useful for rate limiting and preventing request flooding.
+ *
+ * @example
+ * ```typescript
+ * const queue = new RequestQueue(5, 100); // Max 5 concurrent, queue up to 100
+ *
+ * // All requests will be queued and processed with max 5 concurrent
+ * await queue.enqueue(() => fetchUser('1'));
+ * await queue.enqueue(() => fetchUser('2'));
+ * // ...
+ * ```
+ */
+class RequestQueue {
+    /**
+     * Create a new request queue
+     * @param maxConcurrent Maximum number of concurrent requests (default: 10)
+     * @param maxQueueSize Maximum queue size (default: 100)
+     */
+    constructor(maxConcurrent = 10, maxQueueSize = 100) {
+        this.queue = [];
+        this.running = 0;
+        this.maxConcurrent = maxConcurrent;
+        this.maxQueueSize = maxQueueSize;
+    }
+    /**
+     * Enqueue a request
+     * @param requestFn Function that returns a promise
+     * @returns Promise that resolves when request completes
+     */
+    async enqueue(requestFn) {
+        if (this.queue.length >= this.maxQueueSize) {
+            throw new Error('Request queue is full');
+        }
+        return new Promise((resolve, reject) => {
+            this.queue.push(async () => {
+                try {
+                    const result = await requestFn();
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            this.process();
+        });
+    }
+    /**
+     * Process queued requests
+     */
+    async process() {
+        if (this.running >= this.maxConcurrent || this.queue.length === 0) {
+            return;
+        }
+        this.running++;
+        const requestFn = this.queue.shift();
+        if (requestFn) {
+            try {
+                await requestFn();
+            }
+            finally {
+                this.running--;
+                this.process();
+            }
+        }
+        else {
+            this.running--;
+        }
+    }
+    /**
+     * Clear all queued requests
+     */
+    clear() {
+        this.queue = [];
+    }
+    /**
+     * Get queue size
+     */
+    size() {
+        return this.queue.length;
+    }
+    /**
+     * Get number of currently running requests
+     */
+    runningCount() {
+        return this.running;
+    }
+}
+exports.RequestQueue = RequestQueue;
+/**
+ * Simple logger with level support
+ *
+ * Lightweight logger for HTTP clients and utilities.
+ * For structured, namespaced, level-gated logging, use `@oxy.so/core/logger`.
+ *
+ * @example
+ * ```typescript
+ * const logger = new SimpleLogger(true, 'debug');
+ * logger.debug('Debug message');
+ * logger.info('Info message');
+ * logger.error('Error message');
+ * ```
+ */
+class SimpleLogger {
+    /**
+     * Create a new simple logger
+     * @param enabled Whether logging is enabled
+     * @param level Minimum log level
+     * @param prefix Prefix for log messages (default: '')
+     */
+    constructor(enabled = false, level = 'error', prefix = '') {
+        this.enabled = enabled;
+        this.level = level;
+        this.prefix = prefix;
+    }
+    shouldLog(level) {
+        if (!this.enabled || this.level === 'none')
+            return false;
+        const levels = ['none', 'error', 'warn', 'info', 'debug'];
+        return levels.indexOf(level) <= levels.indexOf(this.level);
+    }
+    formatMessage(...args) {
+        return this.prefix ? [`[${this.prefix}]`, ...args] : args;
+    }
+    error(...args) {
+        if (this.shouldLog('error')) {
+            console.error(...this.formatMessage(...args));
+        }
+    }
+    warn(...args) {
+        if (this.shouldLog('warn')) {
+            console.warn(...this.formatMessage(...args));
+        }
+    }
+    info(...args) {
+        if (this.shouldLog('info')) {
+            console.info(...this.formatMessage(...args));
+        }
+    }
+    debug(...args) {
+        if (this.shouldLog('debug')) {
+            console.log(...this.formatMessage(...args));
+        }
+    }
+}
+exports.SimpleLogger = SimpleLogger;