@oxyhq/core 3.4.0 → 3.4.2

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -34,13 +34,8 @@ export interface ServiceApp {
     appId: string;
     appName: string;
     scopes: string[];
-    /**
-     * The credentialId of the specific service credential that minted this token.
-     * Carried by newer service-token JWTs alongside `appId`; absent on tokens
-     * issued before credential-level audit linking. Use for per-credential audit
-     * trails and rotation alignment (GitHub #215).
-     */
-    credentialId?: string;
+    /** The credentialId of the specific service credential that minted this token. */
+    credentialId: string;
 }
 /**
  * Options for oxyClient.auth() middleware
@@ -273,7 +268,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
             hitRate: number;
         };
         getCloudURL(): string;
-        setTokens(accessToken: string, refreshToken?: string): void;
+        setTokens(accessToken: string): void;
         clearTokens(): void;
         onTokensChanged(listener: (accessToken: string | null) => void): () => void;
         _cachedUserId: string | null | undefined;

package/dist/types/mixins/OxyServices.workspaces.d.ts

@@ -177,7 +177,7 @@ export declare function OxyServicesWorkspacesMixin<T extends typeof OxyServicesB
             hitRate: number;
         };
         getCloudURL(): string;
-        setTokens(accessToken: string, refreshToken?: string): void;
+        setTokens(accessToken: string): void;
         clearTokens(): void;
         onTokensChanged(listener: (accessToken: string | null) => void): () => void;
         _cachedUserId: string | null | undefined;

package/dist/types/mixins/index.d.ts

@@ -7,7 +7,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';
@@ -37,7 +37,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<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>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline
@@ -56,7 +56,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)

package/dist/types/models/interfaces.d.ts

@@ -155,8 +155,6 @@ export interface UserPreferences {
 }
 export interface LoginResponse {
     accessToken?: string;
-    refreshToken?: string;
-    token?: string;
     user: User;
     message?: string;
 }
@@ -548,15 +546,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;
@@ -574,13 +564,12 @@ export interface RefreshAllResponse {
     accounts: RefreshAllAccount[];
 }
 /**
- * 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/dist/types/models/session.d.ts

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

package/dist/types/server/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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/dist/types/server/rateLimit.d.ts

@@ -0,0 +1,40 @@
+import type { Request, RequestHandler } from 'express';
+import { type Store } from 'express-rate-limit';
+import type { OxyServices } from '../OxyServices';
+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];
+}
+/**
+ * Build the composed Oxy rate-limit middleware. See module docs for rationale.
+ */
+export declare function createOxyRateLimit(oxy: OxyServices, options?: OxyRateLimitOptions): RequestHandler;

package/dist/types/shared/utils/debugUtils.d.ts

@@ -30,7 +30,7 @@ export declare const debugWarn: (prefix: string, ...args: unknown[]) => void;
 export declare 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/dist/types/utils/authHelpers.d.ts

@@ -17,12 +17,13 @@ export declare 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 declare function ensureValidToken(oxyServices: OxyServices, activeSessionId: string | null | undefined): Promise<void>;
+export declare function ensureValidToken(oxyServices: OxyServices, _activeSessionId: string | null | undefined, syncSession?: () => Promise<unknown>): Promise<void>;
 /**
  * Options for handling API authentication errors
  */

package/dist/types/utils/coldBoot.d.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.
  *
@@ -100,7 +100,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;
     /**

package/dist/types/utils/fapiAutoDetect.d.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.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -23,6 +23,17 @@
       },
       "default": "./dist/esm/index.js"
     },
+    "./server": {
+      "import": {
+        "types": "./dist/types/server/index.d.ts",
+        "default": "./dist/esm/server/index.js"
+      },
+      "require": {
+        "types": "./dist/types/server/index.d.ts",
+        "default": "./dist/cjs/server/index.js"
+      },
+      "default": "./dist/esm/server/index.js"
+    },
     "./package.json": "./package.json"
   },
   "react-native": {
@@ -79,7 +90,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "workspace:*",
+    "@oxyhq/contracts": "^0.1.0",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",
@@ -91,7 +102,9 @@
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "*",
     "expo-crypto": "*",
-    "expo-secure-store": "*"
+    "expo-secure-store": "*",
+    "express": "^4.0.0",
+    "express-rate-limit": "^7.0.0"
   },
   "peerDependenciesMeta": {
     "@react-native-async-storage/async-storage": {
@@ -102,16 +115,25 @@
     },
     "expo-secure-store": {
       "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "express-rate-limit": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@react-native-async-storage/async-storage": "^2.2.0",
     "@types/elliptic": "^6.4.18",
+    "@types/express": "^5.0.0",
     "@types/invariant": "^2.2.34",
     "@types/node": "^20.19.9",
     "expo-crypto": "~56.0.3",
     "expo-secure-store": "~56.0.4",
+    "express": "^4.21.2",
+    "express-rate-limit": "^7.5.0",
     "release-it": "^19.0.6",
     "typescript": "^5.9.2"
   }