@oxy.so/core 1.0.0

package/src/OxyServices.ts

@@ -0,0 +1,172 @@
+/**
+ * OxyServices - Unified client for Oxy API and Oxy Cloud
+ *
+ * # Usage Examples
+ *
+ * ## Browser (ESM/TypeScript)
+ *
+ * ```typescript
+ * import { OxyServices } from './core/OxyServices';
+ *
+ * const oxy = new OxyServices({
+ *   baseURL: 'https://api.oxy.so',
+ *   cloudURL: 'https://cloud.oxy.so',
+ * });
+ *
+ * // Authenticate and fetch user
+ * await oxy.setTokens('ACCESS_TOKEN');
+ * const user = await oxy.getCurrentUser();
+ *
+ * // Upload a file (browser File API)
+ * const fileInput = document.querySelector('input[type=file]');
+ * const file = fileInput.files[0];
+ * await oxy.uploadRawFile(file);
+ *
+ * // Get a file download URL for <img src>
+ * const url = oxy.getFileDownloadUrl('fileId', 'thumb');
+ * ```
+ *
+ * ## Node.js (CommonJS/TypeScript)
+ *
+ * ```typescript
+ * import { OxyServices } from './core/OxyServices';
+ * import fs from 'fs';
+ *
+ * const oxy = new OxyServices({
+ *   baseURL: 'https://api.oxy.so',
+ *   cloudURL: 'https://cloud.oxy.so',
+ * });
+ *
+ * // Authenticate and fetch user
+ * await oxy.setTokens('ACCESS_TOKEN');
+ * const user = await oxy.getCurrentUser();
+ *
+ * // Upload a file (Node.js Buffer)
+ * const buffer = fs.readFileSync('myfile.png');
+ * const blob = new Blob([buffer]);
+ * await oxy.uploadRawFile(blob, { filename: 'myfile.png' });
+ *
+ * // Get a file download URL
+ * const url = oxy.getFileDownloadUrl('fileId');
+ * ```
+ *
+ * ## Configuration
+ * - `baseURL`: Oxy API endpoint (e.g., https://api.oxy.so)
+ * - `cloudURL`: Oxy Cloud/CDN endpoint (e.g., https://cloud.oxy.so)
+ *
+ * See method JSDoc for more details and options.
+ */
+import { OxyServicesBase, type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
+import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.errors';
+
+// Import mixin composition helper
+import { composeOxyServices } from './mixins';
+
+/**
+ * OxyServices - Unified client library for interacting with the Oxy API
+ * 
+ * This class provides all API functionality in one simple, easy-to-use interface.
+ * 
+ * ## Architecture
+ * - **HttpService**: Unified HTTP service handling authentication, caching, deduplication, queuing, and retry
+ * - **OxyServices**: Provides high-level API methods
+ * 
+ * ## Mixin Composition
+ * The class is composed using TypeScript mixins for better code organization:
+ * - **Base**: Core infrastructure (HTTP client, request management, error handling)
+ * - **Auth**: Authentication and session management
+ * - **User**: User profiles, follow, notifications
+ * - **Privacy**: Blocked and restricted users
+ * - **Language**: Language detection and metadata
+ * - **Payment**: Payment processing
+ * - **Reputation**: Reputation system (Oxy Trust)
+ * - **Assets**: File upload and asset management
+ * - **Accounts**: Unified account graph (tree, members, roles, bot credentials)
+ *   and the applications owned within it (Application = OAuth client)
+ * - **Connected apps**: OAuth-consent surface (public app identity, grants)
+ * - **Location**: Location-based features
+ * - **Analytics**: Analytics tracking
+ * - **Devices**: Device management
+ * - **Utility**: Utility methods and Express middleware
+ * 
+ * @example
+ * ```typescript
+ * const oxy = new OxyServices({
+ *   baseURL: 'https://api.oxy.so',
+ *   cloudURL: 'https://cloud.oxy.so'
+ * });
+ * ```
+ */
+// Compose all mixins into the final OxyServices class. The composed runtime
+// class augments OxyServicesBase with every mixin's methods (see mixins/index.ts).
+// Statically, TypeScript sees this as a constructor producing OxyServicesBase;
+// the additional methods are exposed via interface merging on `OxyServices` below.
+const OxyServicesComposed = composeOxyServices();
+
+// Export as a named class to avoid TypeScript issues with anonymous class types.
+// We extend the composed constructor directly — its public surface is broadened
+// to the full mixin set via the interface declaration that follows.
+export class OxyServices extends OxyServicesComposed {
+  constructor(config: OxyConfig) {
+    super(config);
+  }
+}
+
+// Type augmentation to expose mixin methods to TypeScript
+// This allows proper type checking while avoiding complex mixin type inference.
+// Explicit declarations are added for cross-domain auth methods that downstream
+// packages (auth-sdk, services) need without casting to `any`.
+export interface OxyServices extends InstanceType<ReturnType<typeof composeOxyServices>> {
+  createLinkedClient(config: OxyConfig): LinkedHttpClient;
+
+  // Express.js middleware
+  auth(options?: {
+    debug?: boolean;
+    onError?: (error: unknown) => unknown;
+    loadUser?: boolean;
+    optional?: boolean;
+    serviceTokenJwksUrl?: string;
+    jwtSecret?: string;
+    expectedIssuer?: string;
+    expectedAudience?: string;
+  }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
+
+  // Socket.IO middleware
+  authSocket(options?: {
+    debug?: boolean;
+  }): (socket: unknown, next: (err?: Error) => void) => Promise<void>;
+
+  // Service-token-only middleware (delegates to auth() internally)
+  serviceAuth(options?: {
+    debug?: boolean;
+    serviceTokenJwksUrl?: string;
+    jwtSecret?: string;
+    expectedIssuer?: string;
+    expectedAudience?: string;
+  }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
+
+  // Scope enforcement for service-token-protected routes
+  requireScope(scope: string): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+
+  // Asset management
+  assetUpdateVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
+}
+
+// Re-export error classes for convenience
+export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError };
+
+/**
+ * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.
+ */
+export const OXY_CLOUD_URL = 'https://cloud.oxy.so';
+
+/**
+ * Export the default Oxy API URL (for documentation)
+ */
+export const OXY_API_URL = (typeof process !== 'undefined' && process.env && process.env.OXY_API_URL) || 'https://api.oxy.so';
+
+/**
+ * Pre-configured client instance for easy import
+ * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL
+ */
+export const oxyClient = new OxyServices({ baseURL: OXY_API_URL, cloudURL: OXY_CLOUD_URL });

package/src/__tests__/authSocket.test.ts

@@ -0,0 +1,96 @@
+import { OxyServices } from '../OxyServices';
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.forged-signature`;
+}
+
+async function runAuthSocket(oxy: OxyServices, token: string) {
+  const socket: {
+    handshake: { auth: { token: string } };
+    data?: Record<string, unknown>;
+    user?: { id: string; userId: string; sessionId?: string | null };
+  } = { handshake: { auth: { token } } };
+  let nextError: Error | undefined;
+
+  await oxy.authSocket()(socket, (err?: Error) => {
+    nextError = err;
+  });
+
+  return { socket, nextError };
+}
+
+describe('authSocket', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('rejects decoded JWT payloads that do not include a server-validated session', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const fetchMock = jest.fn();
+    globalThis.fetch = fetchMock;
+
+    const { socket, nextError } = await runAuthSocket(oxy, createJwt({
+      userId: 'victimUserId',
+      exp: 4102444800,
+    }));
+
+    expect(nextError?.message).toBe('Session required');
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(socket.data?.userId).toBeUndefined();
+    expect(socket.user).toBeUndefined();
+  });
+
+  it('rejects tokens whose decoded user does not match the validated session user', async () => {
+    globalThis.fetch = async () =>
+      jsonResponse({
+        valid: true,
+        expiresAt: '2099-01-01T00:00:00.000Z',
+        lastActivity: '2026-06-24T00:00:00.000Z',
+        user: { id: 'realUserId', username: 'real', publicKey: 'pub_1' },
+      });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const { socket, nextError } = await runAuthSocket(oxy, createJwt({
+      userId: 'victimUserId',
+      sessionId: 'session_1',
+      exp: 4102444800,
+    }));
+
+    expect(nextError?.message).toBe('Session user mismatch');
+    expect(socket.data?.userId).toBeUndefined();
+    expect(socket.user).toBeUndefined();
+  });
+
+  it('attaches the validated session user when the decoded user matches', async () => {
+    globalThis.fetch = async () =>
+      jsonResponse({
+        valid: true,
+        expiresAt: '2099-01-01T00:00:00.000Z',
+        lastActivity: '2026-06-24T00:00:00.000Z',
+        user: { id: 'user_1', username: 'nate', publicKey: 'pub_1' },
+      });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const { socket, nextError } = await runAuthSocket(oxy, createJwt({
+      userId: 'user_1',
+      sessionId: 'session_1',
+      exp: 4102444800,
+    }));
+
+    expect(nextError).toBeUndefined();
+    expect(socket.data?.userId).toBe('user_1');
+    expect(socket.data?.sessionId).toBe('session_1');
+    expect(socket.user).toEqual({ id: 'user_1', userId: 'user_1', sessionId: 'session_1' });
+  });
+});

package/src/__tests__/httpServiceActivityId.test.ts

@@ -0,0 +1,49 @@
+import { HttpService } from '../HttpService';
+
+describe('HttpService browser activity identifier', () => {
+  const originalFetch = globalThis.fetch;
+  const originalWindowDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'window');
+  const originalDocumentDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'document');
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    if (originalWindowDescriptor) {
+      Object.defineProperty(globalThis, 'window', originalWindowDescriptor);
+    } else {
+      Reflect.deleteProperty(globalThis, 'window');
+    }
+    if (originalDocumentDescriptor) {
+      Object.defineProperty(globalThis, 'document', originalDocumentDescriptor);
+    } else {
+      Reflect.deleteProperty(globalThis, 'document');
+    }
+    jest.restoreAllMocks();
+  });
+
+  it('adds the runtime identifier after caller headers', async () => {
+    Object.defineProperty(globalThis, 'window', {
+      configurable: true,
+      value: {},
+    });
+    Object.defineProperty(globalThis, 'document', {
+      configurable: true,
+      value: {},
+    });
+    const fetchMock = jest.fn(async () => new Response(JSON.stringify({ data: { ok: true } }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    }));
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+    await http.get('/session/status', {
+      headers: { 'X-Oxy-Activity-Id': 'caller-controlled' },
+    });
+
+    const requestHeaders = fetchMock.mock.calls[0]?.[1]?.headers as Record<string, string>;
+    expect(requestHeaders['X-Oxy-Activity-Id']).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    );
+    expect(requestHeaders['X-Oxy-Activity-Id']).not.toBe('caller-controlled');
+  });
+});

package/src/__tests__/httpServiceAuthSelfAwait.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Auth self-await regression.
+ *
+ * The refresh handler (arm 2 shared-key sign-in) calls PRE-SESSION public
+ * endpoints (`/auth/challenge`, `/auth/verify`, the commons-signin surface, …)
+ * from INSIDE the single-flight `tokenRefreshPromise`. If any of those carried
+ * an auth preflight (no `skipAuth`), its `getAuthHeader` would call
+ * `refreshAccessToken`, find the handler's own promise already in flight, and
+ * await it — the handler awaiting itself → permanent hang (no deadline on the
+ * auto-connect lane makes it visible). `skipAuth` on every pre-session public
+ * endpoint is what prevents this; these tests lock the invariant.
+ */
+import { HttpService } from '../HttpService';
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const nowSec = (): number => Math.floor(Date.now() / 1000);
+
+/** Resolve to `true` if `promise` settles within `ms`, else `false`. Always
+ *  clears its timer so no pending timeout leaks into jest's teardown. */
+async function settlesWithin(promise: Promise<unknown>, ms: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  try {
+    return await Promise.race([promise.then(() => true), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+describe('HttpService auth self-await', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('a skipAuth request issued from INSIDE the refresh handler resolves (no self-await)', async () => {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/auth/challenge')) return jsonResponse({ challenge: 'c' });
+      return jsonResponse({ ok: true });
+    }) as typeof fetch;
+
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+    // Near-expiry → the data request's preflight starts the refresh.
+    http.setTokens(createJwt({ userId: 'u', exp: nowSec() + 30 }));
+
+    http.setAuthRefreshHandler(async () => {
+      // Mirror arm 2: from inside the handler, hit a pre-session public endpoint.
+      // With skipAuth it does NOT re-enter refreshAccessToken; without it, its
+      // preflight would await THIS handler's own pending promise → self-await.
+      await http.post('/auth/challenge', { publicKey: 'p' }, { skipAuth: true, retry: false });
+      const fresh = createJwt({ userId: 'u', exp: nowSec() + 3600, jti: 'fresh' });
+      http.setTokens(fresh);
+      return fresh;
+    });
+
+    expect(await settlesWithin(http.get('/data'), 500)).toBe(true);
+  });
+
+  it('a skipAuth public request does NOT await a pending refresh', async () => {
+    let releaseRefresh: (() => void) | undefined;
+    const refreshGate = new Promise<void>((resolve) => {
+      releaseRefresh = resolve;
+    });
+
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/auth/challenge')) return jsonResponse({ challenge: 'c' });
+      return jsonResponse({ ok: true });
+    }) as typeof fetch;
+
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+    http.setTokens(createJwt({ userId: 'u', exp: nowSec() + 30 }));
+
+    http.setAuthRefreshHandler(async () => {
+      await refreshGate; // hold the refresh open
+      const fresh = createJwt({ userId: 'u', exp: nowSec() + 3600, jti: 'fresh' });
+      http.setTokens(fresh);
+      return fresh;
+    });
+
+    // A data request whose preflight starts (and blocks on) the held refresh.
+    const data = http.get('/data');
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    // A skipAuth public request must settle WITHOUT waiting for the held refresh.
+    const pub = http.post('/auth/challenge', { publicKey: 'p' }, { skipAuth: true, retry: false });
+    expect(await settlesWithin(pub, 300)).toBe(true);
+
+    releaseRefresh?.();
+    await data;
+  });
+});