@oxyhq/core 3.4.0 → 3.4.2

package/src/mixins/index.ts

@@ -8,7 +8,7 @@
 import { OxyServicesBase } from '../OxyServices.base';
 import { OxyServicesAuthMixin } from './OxyServices.auth';
 import { OxyServicesFedCMMixin } from './OxyServices.fedcm';
-import { OxyServicesPopupAuthMixin } from './OxyServices.popup';
+import { OxyServicesSilentAuthMixin } from './OxyServices.silent';
 import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect';
 import { OxyServicesSsoMixin } from './OxyServices.sso';
 import { OxyServicesUserMixin } from './OxyServices.user';
@@ -42,7 +42,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
 type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>>
-  & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>>
@@ -84,7 +84,7 @@ type MixinFunction = (Base: new (...args: unknown[]) => OxyServicesBase) => new
  *
  * Order matters for dependencies:
  * 1. Base auth mixin first (required by all others)
- * 2. Cross-domain auth mixins (FedCM, Popup, Redirect)
+ * 2. Cross-domain auth mixins (FedCM, silent iframe, Redirect)
  * 3. User mixin (requires auth)
  * 4. Feature mixins (can depend on user)
  * 5. Utility mixin last (augments all)
@@ -97,14 +97,13 @@ const MIXIN_PIPELINE: MixinFunction[] = [
 
     // Cross-domain authentication (web-only)
     // - FedCM: Modern browser-native identity federation (Google-style)
-    // - Popup: OAuth2-style popup authentication
+    // - Silent: iframe-based restore for first-party IdP hosts
     // - Redirect: Traditional redirect-based authentication
     OxyServicesFedCMMixin,
-    OxyServicesPopupAuthMixin,
+    OxyServicesSilentAuthMixin,
     OxyServicesRedirectAuthMixin,
 
-    // Central cross-domain SSO (opaque-code exchange). After Popup so it can
-    // reuse the popup mixin's secure-random `generateState()`.
+    // Central cross-domain SSO (opaque-code exchange).
     OxyServicesSsoMixin,
 
     // User management (requires auth)
@@ -155,4 +154,3 @@ export function composeOxyServices(): ComposedOxyServicesConstructor {
 
 // Export the pipeline for testing/debugging
 export { MIXIN_PIPELINE };
-

package/src/models/interfaces.ts

@@ -174,8 +174,6 @@ export interface UserPreferences {
 
 export interface LoginResponse {
   accessToken?: string;
-  refreshToken?: string;
-  token?: string; // For backwards compatibility
   user: User;
   message?: string;
 }
@@ -661,15 +659,7 @@ export interface RefreshAllAccountUser {
 
 /**
  * One rotated account entry returned by `POST /auth/refresh-all`. `authuser` is
- * the device-local slot index (0..N-1) the cookie was bound to. The legacy
- * un-suffixed `oxy_rt` cookie yields `authuser: null` server-side, but the SDK
- * normalises that to `0` before exposing it (the chooser always operates on
- * numeric indices).
- *
- * `user` is `null` only on the SDK-side synthesised legacy fallback (when the
- * server is too old to support `/auth/refresh-all` and we wrap a
- * `/auth/refresh` response — that endpoint does not project a user shape).
- * On the modern path every accepted entry carries a non-null user.
+ * the device-local slot index (0..N-1) the cookie was bound to.
  */
 export interface RefreshAllAccount {
   authuser: number;
@@ -689,13 +679,12 @@ export interface RefreshAllResponse {
 }
 
 /**
- * Wire shape of `POST /auth/refresh` (single-account refresh, optionally
- * targeting a specific `?authuser=N` slot). The server includes `authuser` in
- * the response when an indexed slot was rotated; the legacy slot yields
- * `authuser: null`.
+ * Wire shape of `POST /auth/refresh` (single-slot refresh, optionally targeting
+ * a specific `?authuser=N` slot). The server always includes the numeric slot in
+ * the response.
  */
 export interface RefreshCookieResponse {
   accessToken: string;
   expiresAt: string;
-  authuser: number | null;
+  authuser: number;
 }

package/src/models/session.ts

@@ -33,6 +33,4 @@ export interface SessionLoginResponse {
   user: MinimalUserData;
   /** JWT access token for API authentication */
   accessToken?: string;
-  /** Refresh token for obtaining new access tokens */
-  refreshToken?: string;
-} 
+}

package/src/server/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @oxyhq/core/server — Server-only utilities for Oxy backends
+ *
+ * This subpath export provides Express middleware and Node.js-specific
+ * utilities that are not available in React Native or browser environments.
+ *
+ * @example
+ * ```ts
+ * import { createOxyRateLimit } from '@oxyhq/core/server';
+ * import { oxyClient } from '@oxyhq/core';
+ *
+ * const oxy = oxyClient({ apiUrl: 'https://api.oxy.so' });
+ * 
+ * app.use(createOxyRateLimit(oxy, { store: redisStore }));
+ * ```
+ */
+
+export { createOxyRateLimit } from './rateLimit';
+export type { OxyRateLimitOptions } from './rateLimit';

package/src/server/rateLimit.ts

@@ -0,0 +1,170 @@
+import type { Request, RequestHandler } from 'express';
+import rateLimit, { type Store } from 'express-rate-limit';
+import type { OxyServices } from '../OxyServices';
+
+/**
+ * Server-only rate limiting for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every Oxy backend previously shipped its own copy-pasted `security.ts`
+ * implementing the same per-user/per-IP rate limiter — and every copy carried
+ * the same latent bug: the limiter ran BEFORE the session was resolved, so
+ * `req.user` was always undefined inside it. Consequences:
+ *   1. Authenticated users got the low ANONYMOUS limit.
+ *   2. Requests were keyed by IP. Behind a shared load balancer (e.g. the AWS
+ *      ALB) many users share one egress IP, so a single bucket was split across
+ *      all of them → frequent, spurious HTTP 429s.
+ *
+ * `@oxyhq/core` already owns the session: `oxy.auth()` resolves `req.user` /
+ * `req.userId`. Per-user rate limiting is the same concern (session identity),
+ * so it belongs here — once — instead of being re-implemented per app.
+ *
+ * WHAT IT PROVIDES
+ * ----------------
+ * `createOxyRateLimit(oxy, options)` returns a SINGLE composed middleware that:
+ *   1. Resolves the user via `oxy.auth({ optional: true })` (idempotent — it
+ *      skips re-verification if a prior middleware already set `req.user`).
+ *   2. Applies an `express-rate-limit` limiter keyed PER USER when
+ *      authenticated, falling back to the (IPv6-safe) IP otherwise, with
+ *      generous, media-app-realistic defaults and sensible exemptions.
+ *
+ * Mount it after CORS and before your routers:
+ * ```ts
+ * app.use(cors(...));
+ * app.use(oxy.rateLimit({ store }));   // resolves session + limits per user
+ * app.use('/api', apiRouter);
+ * ```
+ */
+
+/** Minimal shape of the request after Oxy session resolution. */
+interface OxyAuthedRequest extends Request {
+  userId?: string | null;
+  user?: { id?: string; _id?: string } | null;
+}
+
+export interface OxyRateLimitOptions {
+  /**
+   * Max requests per window for AUTHENTICATED users (keyed per user).
+   * Default 5000 — ~5.5 req/s sustained, comfortable for a media client that
+   * fans out into many small requests per screen.
+   */
+  authenticatedMax?: number;
+  /**
+   * Max requests per window for ANONYMOUS callers (keyed per IP).
+   * Default 600 — enough to browse public pages while bounding abuse.
+   */
+  anonymousMax?: number;
+  /** Rate-limit window in milliseconds. Default 15 minutes. */
+  windowMs?: number;
+  /**
+   * Optional `express-rate-limit` store (e.g. a Redis store) for distributed
+   * limiting across instances. Defaults to the library's in-memory store.
+   */
+  store?: Store;
+  /**
+   * Extra path predicates to exempt from limiting, in addition to the built-in
+   * exemptions (uploads, image proxy, streaming sub-requests, health probes,
+   * CORS preflight). Return `true` to skip limiting for the request.
+   */
+  exempt?: (req: Request) => boolean;
+  /** Response message body sent with a 429. */
+  message?: string;
+  /**
+   * Options forwarded to the internal `oxy.auth({ optional: true })` resolver
+   * (e.g. `{ jwtSecret }` to verify service tokens). `optional` is forced true.
+   */
+  auth?: Parameters<OxyServices['auth']>[0];
+}
+
+/**
+ * Built-in exemptions. A media app's cover-art/avatar fan-out and HLS
+ * sub-requests must not consume the coarse global budget; health probes from
+ * the load balancer must never be limited; CORS preflight is not a real call.
+ */
+function isBuiltInExempt(req: Request): boolean {
+  const path = req.path;
+  return (
+    req.method === 'OPTIONS' ||
+    path.startsWith('/files/upload') ||
+    path.includes('/images/') ||
+    path.includes('/media/') ||
+    path.startsWith('/api/stream/') ||
+    path.includes('/stream/') ||
+    path === '/health' ||
+    path.endsWith('/health')
+  );
+}
+
+/** IPv6-safe IP key generator (replaces colons to avoid Redis namespace issues). */
+function ipKeyGenerator(ip: string): string {
+  return ip.replace(/:/g, '_');
+}
+
+/** Resolve the rate-limit key: per authenticated user, else per (IPv6-safe) IP. */
+function resolveKey(req: OxyAuthedRequest): string {
+  const userId = req.userId ?? req.user?.id ?? req.user?._id;
+  if (userId) {
+    return `user:${userId}`;
+  }
+  const ip = req.ip || (req.socket as any)?.remoteAddress || 'unknown';
+  return ipKeyGenerator(ip);
+}
+
+/**
+ * Build the composed Oxy rate-limit middleware. See module docs for rationale.
+ */
+export function createOxyRateLimit(
+  oxy: OxyServices,
+  options: OxyRateLimitOptions = {},
+): RequestHandler {
+  const {
+    authenticatedMax = 5000,
+    anonymousMax = 600,
+    windowMs = 15 * 60 * 1000,
+    store,
+    exempt,
+    message = 'Too many requests, please try again later.',
+    auth,
+  } = options;
+
+  // Idempotent optional-auth resolver. Reuses the SAME session resolution as
+  // every protected route, so the limiter keys by the real user identity.
+  const resolveSession = oxy.auth({ ...auth, optional: true });
+
+  const skip = (req: Request): boolean =>
+    isBuiltInExempt(req) || (exempt ? exempt(req) : false);
+
+  const limiter = rateLimit({
+    windowMs,
+    ...(store ? { store } : {}),
+    max: ((req: Request): number => {
+      const authed = req as OxyAuthedRequest;
+      const userId = authed.userId ?? authed.user?.id ?? authed.user?._id;
+      return userId ? authenticatedMax : anonymousMax;
+    }) as any,
+    keyGenerator: ((req: Request): string => resolveKey(req as OxyAuthedRequest)) as any,
+    message,
+    standardHeaders: true,
+    legacyHeaders: false,
+    skip: skip as any,
+  } as any);
+
+  return ((req: any, res: any, next: any) => {
+    // Skipped paths bypass BOTH session resolution and limiting — cheap and
+    // safe for static/streaming/health traffic.
+    if (skip(req)) {
+      next();
+      return;
+    }
+    resolveSession(req, res, (err?: unknown) => {
+      if (err) {
+        // Optional auth never rejects; a token error just means "anonymous".
+        // Swallow the error and continue to limit as anonymous.
+        next();
+        return;
+      }
+      limiter(req, res, next);
+    });
+  }) as RequestHandler;
+}

package/src/shared/utils/debugUtils.ts

@@ -57,7 +57,7 @@ export const debugError = (prefix: string, ...args: unknown[]): void => {
 
 /**
  * Create a namespaced debug logger
- * @param namespace - Logger namespace (e.g., 'FedCM', 'PopupAuth')
+ * @param namespace - Logger namespace (e.g., 'FedCM', 'SilentAuth')
  * @returns Object with log, warn, error methods
  *
  * @example

package/src/utils/accountUtils.ts

@@ -204,10 +204,10 @@ export const mergeAccountsFromRefreshAll = (
 
     const merged: QuickAccount[] = fresh.map((entry) => {
         const previous = storedByAuthuser.get(entry.authuser);
-        // `entry.user` is null on the SDK legacy-fallback path; preserve any
-        // previously cached identity for that slot rather than overwriting
-        // it with blanks, and let the AuthManager's getCurrentUser() hydration
-        // refresh it on the next snapshot.
+        // Preserve any previously cached identity for a slot that arrives
+        // without a user shape rather than overwriting it with blanks, and let
+        // AuthManager's getCurrentUser() hydration refresh it on the next
+        // snapshot.
         const wireUser = entry.user;
         const username = wireUser?.username ?? previous?.username ?? '';
         const displayName = getAccountDisplayName({

package/src/utils/authHelpers.ts

@@ -27,30 +27,39 @@ export class AuthenticationFailedError extends Error {
 
 /**
  * Ensures a valid token exists before making authenticated API calls.
- * If no valid token exists and an active session ID is available,
- * attempts to refresh the token using the session.
+ * 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)
  */
 export async function ensureValidToken(
   oxyServices: OxyServices,
-  activeSessionId: string | null | undefined
+  _activeSessionId: string | null | undefined,
+  syncSession?: () => Promise<unknown>
 ): Promise<void> {
-  if (oxyServices.hasValidToken() || !activeSessionId) {
+  if (oxyServices.hasValidToken()) {
     return;
   }
 
-  try {
-    await oxyServices.getTokenBySession(activeSessionId);
-  } catch (tokenError) {
-    const errorMessage = tokenError instanceof Error ? tokenError.message : String(tokenError);
+  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();
-    }
+      if (errorMessage.includes('AUTH_REQUIRED_OFFLINE_SESSION') || errorMessage.includes('offline')) {
+        throw new SessionSyncRequiredError();
+      }
 
-    throw tokenError;
+      throw syncError;
+    }
   }
+
+  throw new SessionSyncRequiredError('No active access token is available. Sync the session before calling authenticated APIs.');
 }
 
 /**
@@ -98,10 +107,9 @@ export async function withAuthErrorHandling<T>(
       throw error;
     }
 
-    if (options?.syncSession && options?.activeSessionId && options?.oxyServices) {
+    if (options?.syncSession && options?.oxyServices) {
       try {
         await options.syncSession();
-        await options.oxyServices.getTokenBySession(options.activeSessionId);
         return await apiCall();
       } catch {
         throw new AuthenticationFailedError();
@@ -130,7 +138,7 @@ export async function authenticatedApiCall<T>(
   apiCall: () => Promise<T>,
   syncSession?: () => Promise<unknown>
 ): Promise<T> {
-  await ensureValidToken(oxyServices, activeSessionId);
+  await ensureValidToken(oxyServices, activeSessionId, syncSession);
 
   return withAuthErrorHandling(apiCall, {
     syncSession,

package/src/utils/coldBoot.ts

@@ -4,7 +4,7 @@
  *
  * On a fresh page load / app launch the SDK may have several ways to recover an
  * existing session (silent FedCM, a persisted refresh token, a cross-domain
- * claim, an explicit popup flow, …). They must be attempted in a *deterministic
+ * claim, a redirect SSO 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.
  *
@@ -112,7 +112,7 @@ export interface RunColdBootOptions<S> {
    * Per-step timeouts inside `run()` remain the first line of defense and
    * should keep every step well under this budget on a healthy load; this only
    * trips when one of them regresses (the production FedCM-silent hang). When
-   * omitted there is NO overall deadline (unchanged legacy behaviour).
+   * omitted there is no overall deadline.
    */
   readonly overallDeadlineMs?: number;
   /**
@@ -178,8 +178,8 @@ export async function runColdBoot<S>(
 
       let result: ColdBootStepResult<S> | typeof DEADLINE_EXPIRED;
       try {
-        // Without a deadline: legacy behaviour — await the step directly.
-        // With a deadline: race the step against the shared deadline. The
+        // 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 —

package/src/utils/fapiAutoDetect.ts

@@ -8,7 +8,7 @@
  * Clerk-style multi-domain SSO depends on the IdP being reachable on a
  * subdomain of the RP's own apex (e.g. `auth.mention.earth` CNAMEd to the
  * central Oxy IdP). That way every FedCM endpoint, the session cookie,
- * and any popup/redirect target are same-site with the RP — the only way
+ * and any redirect target are same-site with the RP — the only way
  * to get first-party cookies in Safari ITP and Firefox Total Cookie
  * Protection.
  *