@oxy.so/core 1.0.0

package/src/utils/__tests__/webauthnOrigin.test.ts

@@ -0,0 +1,83 @@
+/**
+ * `isOxyRpOrigin()` — client-side WebAuthn relying-party origin guard.
+ *
+ * Runs under the `node` test environment, where `globalThis.location` is
+ * genuinely absent by default (mirroring native/SSR). Each case defines a fake
+ * `location` with the host under test and restores the original afterwards.
+ */
+import { isOxyRpOrigin } from '../webauthnOrigin';
+
+describe('isOxyRpOrigin', () => {
+  const originalLocation = globalThis.location;
+
+  const setHostname = (hostname: unknown): void => {
+    Object.defineProperty(globalThis, 'location', {
+      configurable: true,
+      value: hostname === undefined ? undefined : { hostname },
+    });
+  };
+
+  afterEach(() => {
+    Object.defineProperty(globalThis, 'location', {
+      configurable: true,
+      value: originalLocation,
+    });
+  });
+
+  it('returns true on the apex oxy.so', () => {
+    setHostname('oxy.so');
+    expect(isOxyRpOrigin()).toBe(true);
+  });
+
+  it('returns true on an oxy.so subdomain', () => {
+    setHostname('accounts.oxy.so');
+    expect(isOxyRpOrigin()).toBe(true);
+  });
+
+  it('returns true on a deep oxy.so subdomain', () => {
+    setHostname('sub.accounts.oxy.so');
+    expect(isOxyRpOrigin()).toBe(true);
+  });
+
+  it('returns true on loopback hosts', () => {
+    for (const host of ['localhost', '127.0.0.1', '[::1]']) {
+      setHostname(host);
+      expect(isOxyRpOrigin()).toBe(true);
+    }
+  });
+
+  it('is case-insensitive on the host', () => {
+    setHostname('Accounts.OXY.So');
+    expect(isOxyRpOrigin()).toBe(true);
+  });
+
+  it('returns false on an unrelated origin', () => {
+    setHostname('evil.com');
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false on a look-alike suffix without the dot boundary', () => {
+    setHostname('evil-oxy.so');
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false when oxy.so is only a subdomain label of an attacker apex', () => {
+    setHostname('oxy.so.evil.com');
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false when there is no location (native / SSR)', () => {
+    setHostname(undefined);
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false when the hostname is not a string', () => {
+    setHostname(123);
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false when the hostname is empty', () => {
+    setHostname('');
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+});

package/src/utils/accountCacheSweep.ts

@@ -0,0 +1,93 @@
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that serve the ACCOUNT FOREST
+ * — the caller's accessible accounts, as lists and as individual detail rows —
+ * and the one sweep that clears them.
+ *
+ * WHY THIS IS NOT A METHOD ON THE ACCOUNTS MIXIN
+ * ---------------------------------------------
+ * `AccountNode.account` is a whole `User`, so a forest read embeds the very
+ * profile the identity reads serve. That makes an IDENTITY write a writer of
+ * these keys too: `updateProfile` edits the caller's own personal account,
+ * which is a row in `GET /accounts` and is its own `GET /accounts/<id>`. Leave
+ * those cached and the account switcher keeps drawing the pre-edit name and
+ * picture for the full TTL, against a perfectly healthy server.
+ *
+ * The mixins compose into one class at runtime but are typed one at a time, so
+ * the user mixin cannot call a method the accounts mixin owns. The key list
+ * therefore lives here, once, and every writer calls {@link
+ * evictOxyAccountForestCache} — exactly like the identity key list in
+ * `identityCacheSweep`, which the accounts mixin already calls for the
+ * mirror-image case (an account write staling the identity reads). The
+ * alternative — a second hand-written copy of these keys in the other mixin —
+ * is the drift that shipped the two stale-profile bugs `identityCacheSweep`
+ * documents.
+ *
+ * WHY THE LIST NEEDS A PREFIX AND THE DETAIL DOES NOT
+ * --------------------------------------------------
+ * `listAccounts({tree?})` keys the flat list as `GET:/accounts` and every
+ * option variant as `GET:/accounts?<query>` (the query string is part of the
+ * URL, hence of the key), and a writer cannot enumerate which variants a caller
+ * has read. The detail key, by contrast, is derivable from the account id the
+ * writer already holds.
+ *
+ * The `GET:/accounts?` prefix matches ONLY the query-string list variants —
+ * never `GET:/accounts/<id>` or its `…/members`, `…/credentials`, `…/children`
+ * sub-resources, which are the accounts mixin's own business and stay there.
+ */
+
+import type { OxyIdentityCacheEvictor } from './identityCacheSweep';
+
+/**
+ * The cache-eviction surface of an `OxyServices` instance. Reused from
+ * `identityCacheSweep` rather than re-declared: it is the SDK's one published
+ * name for these two methods, and a second identical interface would be one
+ * more shape to keep in step.
+ */
+export type OxyAccountCacheEvictor = OxyIdentityCacheEvictor;
+
+/** The cache key `listAccounts()` reads under with no options. */
+export const OXY_ACCOUNT_LIST_CACHE_KEY = 'GET:/accounts';
+
+/**
+ * The prefix covering every option-carrying `listAccounts(opts)` variant
+ * (`?tree=true`, …), none of which a writer can enumerate.
+ */
+export const OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX = 'GET:/accounts?';
+
+/**
+ * Prefix covering every per-account sub-resource cache key
+ * (`GET:/accounts/<id>`, `…/members`, `…/credentials`, `…/children`). A
+ * membership mutation on an ancestor must sweep ALL of these, not only the
+ * account named in the path: descendant member rosters embed inherited rows
+ * resolved from that ancestor, and the writer cannot enumerate which descendant
+ * ids a caller has already read. The trailing slash deliberately excludes the
+ * forest list keys (`GET:/accounts`, `GET:/accounts?…`) documented above.
+ */
+export const OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX = 'GET:/accounts/';
+
+/**
+ * Build the exact cache key `getAccount(accountId)` reads under.
+ */
+export function oxyAccountDetailCacheKey(accountId: string): string {
+  return `GET:/accounts/${encodeURIComponent(accountId)}`;
+}
+
+/**
+ * Sweep an `OxyServices` GET response cache of the account forest.
+ *
+ * @param oxy       - Anything exposing the SDK's two eviction methods.
+ * @param accountId - The account whose detail row to drop as well. Optional: a
+ *                    writer that changed the SHAPE of the forest rather than one
+ *                    account in it (create, archive, ownership transfer) has no
+ *                    detail row to name, and clears only the lists.
+ */
+export function evictOxyAccountForestCache(
+  oxy: OxyAccountCacheEvictor,
+  accountId?: string,
+): void {
+  oxy.clearCacheEntry(OXY_ACCOUNT_LIST_CACHE_KEY);
+  oxy.clearCacheByPrefix(OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX);
+  if (accountId) {
+    oxy.clearCacheEntry(oxyAccountDetailCacheKey(accountId));
+  }
+}

package/src/utils/accountUtils.ts

@@ -0,0 +1,194 @@
+/**
+ * Shared account types and pure helper functions.
+ * Used by the @oxy.so/services account stores (Expo/RN and RN-Web).
+ */
+
+import { translate } from '../i18n';
+import { getNormalizedUserHandle } from './userHandle';
+
+export interface QuickAccount {
+    sessionId: string;
+    userId?: string;
+    username: string;
+    displayName: string;
+    avatar?: string;
+    avatarUrl?: string;
+    /**
+     * Device-local account slot index, 0..N-1 (Google-style multi-account).
+     * Optional so that pre-multi-account QuickAccounts (sessionId-only) remain
+     * valid; the device session set populates it where available.
+     */
+    authuser?: number;
+    /**
+     * Account's preferred Bloom color preset (e.g. `"blue"`, `"oxy"`). Drives
+     * per-account theming in the account chooser. `null` / `undefined` means
+     * the account has no preference and the base theme should be used.
+     */
+    color?: string | null;
+}
+
+/** Minimal user shape accepted by display-name helpers. Avoids importing the full User type. */
+export interface DisplayNameUserShape {
+    name?: string | {
+        displayName?: string;
+        first?: string;
+        last?: string;
+        full?: string;
+        [key: string]: unknown;
+    };
+    /** Pre-normalized account-row display name, not the API User DTO field. */
+    displayName?: string;
+    username?: string;
+    publicKey?: string;
+}
+
+/**
+ * Truncate a long public key for display, e.g. `0x12345678…`.
+ * Falls back to the raw key if it's too short to truncate.
+ */
+export const formatPublicKeyHandle = (publicKey: string): string => {
+    const cleaned = publicKey.startsWith('0x') ? publicKey.slice(2) : publicKey;
+    if (cleaned.length <= 8) return `0x${cleaned}`;
+    return `0x${cleaned.slice(0, 8)}…`;
+};
+
+/**
+ * Resolve a friendly display name for a user.
+ *
+ * Order of preference:
+ *  1. `name.displayName` from the API user contract.
+ *  2. `name.full`, or composed `name.first name.last` for local unsaved shapes.
+ *  3. `name` when passed as a plain string by local non-DTO call sites.
+ *  4. pre-normalized account-row `displayName`.
+ *  5. `username`
+ *  6. `Account 0x12345678…` (derived from publicKey, when present)
+ *  7. Translated fallback (e.g. "Unnamed")
+ *
+ * The translation key `common.unnamed` is used for the final fallback. If the
+ * caller does not pass a locale, the default English translation is used.
+ */
+export const getAccountDisplayName = (
+    user: DisplayNameUserShape | null | undefined,
+    locale?: string,
+): string => {
+    if (!user) return translate(locale, 'common.unnamed');
+
+    const { name, displayName, username, publicKey } = user;
+
+    if (name && typeof name === 'object') {
+        if (typeof name.displayName === 'string' && name.displayName.trim()) {
+            return name.displayName.trim();
+        }
+        if (typeof name.full === 'string' && name.full.trim()) return name.full.trim();
+        const first = typeof name.first === 'string' ? name.first.trim() : '';
+        const last = typeof name.last === 'string' ? name.last.trim() : '';
+        const composed = [first, last].filter(Boolean).join(' ').trim();
+        if (composed) return composed;
+    } else if (typeof name === 'string' && name.trim()) {
+        return name.trim();
+    }
+
+    if (typeof displayName === 'string' && displayName.trim()) return displayName.trim();
+
+    if (typeof username === 'string' && username.trim()) return username.trim();
+
+    if (typeof publicKey === 'string' && publicKey.length > 0) {
+        return translate(locale, 'common.accountFallback', {
+            handle: formatPublicKeyHandle(publicKey),
+        });
+    }
+
+    return translate(locale, 'common.unnamed');
+};
+
+/**
+ * Resolve a `@handle` style identifier for a user.
+ *
+ * Returns the bare username when present (without the `@`), otherwise a
+ * truncated public-key handle (`0x12345678…`), or `undefined` when neither is
+ * available — callers can decide whether to hide the line entirely.
+ */
+export const getAccountFallbackHandle = (
+    user: DisplayNameUserShape | null | undefined,
+): string | undefined => {
+    if (!user) return undefined;
+    if (typeof user.username === 'string' && user.username.trim()) return user.username.trim();
+    if (typeof user.publicKey === 'string' && user.publicKey.length > 0) {
+        return formatPublicKeyHandle(user.publicKey);
+    }
+    return undefined;
+};
+
+/**
+ * Build an ordered array of QuickAccounts from a map and order list.
+ */
+export const buildAccountsArray = (
+    accounts: Record<string, QuickAccount>,
+    order: string[]
+): QuickAccount[] => {
+    const result: QuickAccount[] = [];
+    for (const id of order) {
+        const account = accounts[id];
+        if (account) result.push(account);
+    }
+    return result;
+};
+
+/**
+ * Create a QuickAccount from user data returned by the API.
+ *
+ * @param sessionId - Session identifier
+ * @param userData - Raw user object from the API
+ * @param existingAccount - Previously cached account (to preserve avatarUrl if unchanged)
+ * @param getFileDownloadUrl - Function to generate avatar download URL from file ID
+ */
+export const createQuickAccount = (
+    sessionId: string,
+    userData: {
+        name?: string | { displayName?: string; full?: string; first?: string; last?: string };
+        username?: string;
+        publicKey?: string;
+        id?: string;
+        _id?: { toString(): string } | string;
+        avatar?: string | null;
+    },
+    existingAccount?: QuickAccount,
+    getFileDownloadUrl?: (fileId: string, variant: string) => string
+): QuickAccount => {
+    const nameObj =
+        userData.name && typeof userData.name === 'object' ? userData.name : undefined;
+    const apiDisplayName =
+        typeof nameObj?.displayName === 'string' ? nameObj.displayName.trim() : '';
+    const displayName =
+        apiDisplayName ||
+        getNormalizedUserHandle(userData) ||
+        getAccountDisplayName(null);
+    const userId = userData.id || (typeof userData._id === 'string' ? userData._id : userData._id?.toString());
+
+    // Preserve existing avatarUrl if avatar hasn't changed (prevents image reload)
+    let avatarUrl: string | undefined;
+    const avatar = userData.avatar ?? undefined;
+    if (existingAccount && existingAccount.avatar === avatar && existingAccount.avatarUrl) {
+        avatarUrl = existingAccount.avatarUrl;
+    } else if (avatar && getFileDownloadUrl) {
+        avatarUrl = getFileDownloadUrl(avatar, 'thumb');
+    }
+
+    return {
+        sessionId,
+        userId,
+        username: userData.username || '',
+        displayName,
+        avatar,
+        avatarUrl,
+    };
+};
+
+/**
+ * Return the account's preferred Bloom color preset, or `null` if it has no
+ * preference. Centralises the `color ?? null` normalisation so consumers can
+ * drive per-account theming without duplicating the nullish-handling.
+ */
+export const getAccountColor = (account: QuickAccount): string | null => {
+    return account.color ?? null;
+};

package/src/utils/activityId.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from `@oxy.so/telemetry/browser` in new code. */
+export { getBrowserActivityIdHeader } from '@oxy.so/telemetry/browser';

package/src/utils/apiUtils.ts

@@ -0,0 +1,137 @@
+/**
+ * Utility functions for common API patterns
+ */
+
+/**
+ * Build a plain query-parameter record from an object, stringifying values and
+ * dropping `undefined`/`null` entries.
+ *
+ * This is the shape `OxyServices.makeRequest` expects for a GET's `params`:
+ * `HttpService` inspects it with `Object.keys(...)` (both to decide whether to
+ * append a query string and to build the request's cache key), and
+ * `Object.keys(new URLSearchParams({ limit: '20' }))` is `[]` — a
+ * `URLSearchParams` exposes its entries through iterator methods, never as own
+ * enumerable properties. Passing one to `makeRequest` therefore silently drops
+ * the whole query string. Always hand `makeRequest` a plain record.
+ *
+ * Generic over the input object rather than taking `Record<string, unknown>`,
+ * because a TypeScript `interface` (`PaginationParams`, `FollowGraphParams`, …)
+ * has no implicit index signature and so is not assignable to that type.
+ */
+export function buildQueryParams<T extends object>(params: T): Record<string, string> {
+  const query: Record<string, string> = {};
+
+  // Widening the value to `unknown` is always sound; the default overload of
+  // `Object.entries` would otherwise infer `any` here.
+  for (const [key, value] of Object.entries(params) as [string, unknown][]) {
+    if (value !== undefined && value !== null) {
+      query[key] = String(value);
+    }
+  }
+
+  return query;
+}
+
+/**
+ * Build URL search parameters from an object.
+ *
+ * For building a URL string only — see {@link buildQueryParams} for the shape
+ * `makeRequest` needs.
+ *
+ * @param params Object with parameter key-value pairs
+ * @returns URLSearchParams instance
+ */
+export function buildSearchParams<T extends object>(params: T): URLSearchParams {
+  return new URLSearchParams(buildQueryParams(params));
+}
+
+/**
+ * Build URL with search parameters
+ * @param baseUrl Base URL
+ * @param params Object with parameter key-value pairs
+ * @returns Complete URL with search parameters
+ */
+export function buildUrl<T extends object>(baseUrl: string, params?: T): string {
+  if (!params) return baseUrl;
+  
+  const searchParams = buildSearchParams(params);
+  const queryString = searchParams.toString();
+  
+  return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+}
+
+/**
+ * Common pagination parameters
+ */
+export interface PaginationParams {
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Ordering for the follow-graph list endpoints (`/users/:id/followers`,
+ * `/users/:id/following`, `/users/:id/mutuals`).
+ *
+ * - `recent` — newest follow edge first (the server default).
+ * - `oldest` — oldest follow edge first.
+ */
+export type FollowGraphSort = 'recent' | 'oldest';
+
+/**
+ * Pagination plus the follow-graph ordering.
+ *
+ * Kept separate from {@link PaginationParams}, which is shared by endpoints
+ * that have no `sort` at all.
+ */
+export interface FollowGraphParams extends PaginationParams {
+  sort?: FollowGraphSort;
+}
+
+/**
+ * Build pagination query parameters.
+ *
+ * Returns a plain record — NOT a `URLSearchParams` — because that is the only
+ * shape `makeRequest`/`HttpService` can read. See {@link buildQueryParams}.
+ *
+ * @param params Pagination parameters
+ * @returns Query record with pagination
+ */
+export function buildPaginationParams(params: PaginationParams): Record<string, string> {
+  return buildQueryParams(params);
+}
+
+/**
+ * Common API response wrapper
+ */
+export interface ApiResponse<T = any> {
+  data: T;
+  message?: string;
+  success?: boolean;
+}
+
+/**
+ * Common error response wrapper
+ */
+export interface ErrorResponse {
+  message: string;
+  code: string;
+  status: number;
+  details?: any;
+}
+
+/**
+ * Safe JSON parsing with error handling
+ * @param data Data to parse
+ * @param fallback Fallback value if parsing fails
+ * @returns Parsed data or fallback
+ */
+export function safeJsonParse<T>(data: any, fallback: T): T {
+  if (typeof data === 'string') {
+    try {
+      return JSON.parse(data);
+    } catch {
+      return fallback;
+    }
+  }
+  return data as T;
+}