@oxy.so/core 1.0.0

package/src/utils/officialOrigins.ts

@@ -0,0 +1,62 @@
+/**
+ * Official first-party web origin allowlist — shared by OAuth redirect
+ * validation and the server-side trusted-origin checks.
+ */
+
+import { CENTRAL_IDP_APEX } from './authWebUrl';
+import { registrableApex } from './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).
+ */
+export function isLoopbackOrigin(origin: string): boolean {
+  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. */
+export function isOfficialWebOrigin(origin: string): boolean {
+  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 === CENTRAL_IDP_APEX || host.endsWith(`.${CENTRAL_IDP_APEX}`)) {
+      return true;
+    }
+    const apex = registrableApex(host);
+    return apex != null && OFFICIAL_APEXES.has(apex);
+  } catch {
+    return false;
+  }
+}
+
+/** @deprecated Use {@link isOfficialWebOrigin}. */
+export const isAllowedDeviceJoinOrigin = isOfficialWebOrigin;

package/src/utils/oxyServiceEnvironment.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export const OXY_SERVICE_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
+export type OxyServiceEnvironment = (typeof OXY_SERVICE_ENVIRONMENTS)[number];

package/src/utils/platform.ts

@@ -0,0 +1,139 @@
+/**
+ * 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.
+ */
+
+export type PlatformOS = 'ios' | 'android' | 'web' | 'windows' | 'macos' | 'unknown';
+
+/**
+ * Shape of the RN-platform marker that the React Native entry point registers
+ * on `globalThis` via {@link setPlatformOS}. Declared locally (rather than as a
+ * global type augmentation) so core stays self-contained and does not leak an
+ * ambient global into every consumer's type space.
+ */
+interface RNPlatformGlobal {
+  __REACT_NATIVE_PLATFORM__?: PlatformOS;
+}
+
+/**
+ * Typed view over `globalThis` for the RN-platform marker, avoiding an `any`
+ * cast at each access site.
+ */
+function rnPlatformGlobal(): RNPlatformGlobal {
+  return globalThis as unknown as RNPlatformGlobal;
+}
+
+/**
+ * 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(): PlatformOS {
+  // 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: PlatformOS | null = null;
+
+/**
+ * Get the current platform OS
+ * Safe to call from any environment (web, Node.js, React Native)
+ */
+export function getPlatformOS(): PlatformOS {
+  if (cachedPlatform === null) {
+    cachedPlatform = detectPlatform();
+  }
+  return cachedPlatform;
+}
+
+/**
+ * Check if running on web platform (browser or Node.js)
+ */
+export function isWeb(): boolean {
+  return getPlatformOS() === 'web';
+}
+
+/**
+ * Check if running in a native app (iOS or Android)
+ */
+export function isNative(): boolean {
+  const os = getPlatformOS();
+  return os === 'ios' || os === 'android';
+}
+
+/**
+ * Check if running on iOS
+ */
+export function isIOS(): boolean {
+  return getPlatformOS() === 'ios';
+}
+
+/**
+ * Check if running on Android
+ */
+export function isAndroid(): boolean {
+  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
+ */
+export function setPlatformOS(os: PlatformOS): void {
+  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.
+ */
+export function isWebBrowser(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    typeof document !== 'undefined' &&
+    typeof document.documentElement !== 'undefined'
+  );
+}
+

package/src/utils/profileLinks.ts

@@ -0,0 +1,91 @@
+/**
+ * Normalized profile link shape for display.
+ *
+ * `id` is a stable key for list rendering (the source entry's id when present,
+ * otherwise the source index as a string). `url` is always a non-empty string.
+ * `title`, `description`, and `image` are carried through from `linksMetadata`
+ * only when present; the legacy `links: string[]` path produces just
+ * `{ id, url }`.
+ */
+export interface ProfileLink {
+  id: string;
+  title?: string;
+  url: string;
+  description?: string;
+  image?: string;
+}
+
+/** Source shape of a single `User.linksMetadata` entry. */
+export interface ProfileLinkMetadata {
+  url: string;
+  title?: string;
+  description?: string;
+  image?: string;
+  id?: string;
+}
+
+function cleanUrl(value: unknown): string | null {
+  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.
+ */
+export function normalizeProfileLinks(
+  linksMetadata?: ProfileLinkMetadata[],
+  links?: string[],
+): ProfileLink[] {
+  if (Array.isArray(linksMetadata) && linksMetadata.length > 0) {
+    const result: ProfileLink[] = [];
+    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: ProfileLink[] = [];
+    links.forEach((value, index) => {
+      const url = cleanUrl(value);
+      if (!url) return;
+      result.push({ id: String(index), url });
+    });
+    return result;
+  }
+
+  return [];
+}

package/src/utils/redactUrl.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+export function redactUrlQuery(url: string): string {
+  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/src/utils/registrableApex.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+
+import { getDomain } from '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.
+ */
+export function registrableApex(hostname: string): string | null {
+  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 getDomain(host, { allowPrivateDomains: true });
+}

package/src/utils/requestUtils.ts

@@ -0,0 +1,237 @@
+/**
+ * Request utilities for HTTP clients
+ * 
+ * Provides reusable components for request deduplication, queuing, and logging
+ */
+
+/**
+ * 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
+ * ```
+ */
+export class RequestDeduplicator {
+  private pendingRequests = new Map<string, Promise<any>>();
+
+  /**
+   * 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<T>(
+    key: string,
+    requestFn: () => Promise<T>
+  ): Promise<T> {
+    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(): void {
+    this.pendingRequests.clear();
+  }
+
+  /**
+   * Get number of pending requests
+   */
+  size(): number {
+    return this.pendingRequests.size;
+  }
+}
+
+/**
+ * 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'));
+ * // ...
+ * ```
+ */
+export class RequestQueue {
+  private queue: Array<() => Promise<any>> = [];
+  private running = 0;
+  private maxConcurrent: number;
+  private maxQueueSize: number;
+
+  /**
+   * 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.maxConcurrent = maxConcurrent;
+    this.maxQueueSize = maxQueueSize;
+  }
+
+  /**
+   * Enqueue a request
+   * @param requestFn Function that returns a promise
+   * @returns Promise that resolves when request completes
+   */
+  async enqueue<T>(requestFn: () => Promise<T>): Promise<T> {
+    if (this.queue.length >= this.maxQueueSize) {
+      throw new Error('Request queue is full');
+    }
+
+    return new Promise<T>((resolve, reject) => {
+      this.queue.push(async () => {
+        try {
+          const result = await requestFn();
+          resolve(result);
+        } catch (error) {
+          reject(error);
+        }
+      });
+
+      this.process();
+    });
+  }
+
+  /**
+   * Process queued requests
+   */
+  private async process(): Promise<void> {
+    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(): void {
+    this.queue = [];
+  }
+
+  /**
+   * Get queue size
+   */
+  size(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Get number of currently running requests
+   */
+  runningCount(): number {
+    return this.running;
+  }
+}
+
+/** Log level type for SimpleLogger */
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+
+/**
+ * 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');
+ * ```
+ */
+export class SimpleLogger {
+  private enabled: boolean;
+  private level: LogLevel;
+  private prefix: string;
+
+  /**
+   * 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: LogLevel = 'error',
+    prefix = ''
+  ) {
+    this.enabled = enabled;
+    this.level = level;
+    this.prefix = prefix;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    if (!this.enabled || this.level === 'none') return false;
+    const levels: LogLevel[] = ['none', 'error', 'warn', 'info', 'debug'];
+    return levels.indexOf(level) <= levels.indexOf(this.level);
+  }
+
+  private formatMessage(...args: any[]): any[] {
+    return this.prefix ? [`[${this.prefix}]`, ...args] : args;
+  }
+
+  error(...args: any[]): void {
+    if (this.shouldLog('error')) {
+      console.error(...this.formatMessage(...args));
+    }
+  }
+
+  warn(...args: any[]): void {
+    if (this.shouldLog('warn')) {
+      console.warn(...this.formatMessage(...args));
+    }
+  }
+
+  info(...args: any[]): void {
+    if (this.shouldLog('info')) {
+      console.info(...this.formatMessage(...args));
+    }
+  }
+
+  debug(...args: any[]): void {
+    if (this.shouldLog('debug')) {
+      console.log(...this.formatMessage(...args));
+    }
+  }
+}
+