@oxyhq/core 1.11.13 → 1.11.14

package/dist/types/OxyServices.d.ts

@@ -112,13 +112,23 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
     signUpWithRedirect(options?: RedirectAuthOptions): void;
     auth(options?: {
         debug?: boolean;
-        onError?: (error: any) => any;
+        onError?: (error: unknown) => unknown;
         loadUser?: boolean;
         optional?: boolean;
-    }): (req: any, res: any, next: any) => Promise<void>;
+        jwtSecret?: string;
+        expectedIssuer?: string;
+        expectedAudience?: string;
+    }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
     authSocket(options?: {
         debug?: boolean;
-    }): (socket: any, next: (err?: Error) => void) => Promise<void>;
+    }): (socket: unknown, next: (err?: Error) => void) => Promise<void>;
+    serviceAuth(options?: {
+        debug?: boolean;
+        jwtSecret?: string;
+        expectedIssuer?: string;
+        expectedAudience?: string;
+    }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
+    requireScope(scope: string): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
     assetUpdateVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
 }
 export { OxyAuthenticationError, OxyAuthenticationTimeoutError };
@@ -129,7 +139,7 @@ export declare const OXY_CLOUD_URL = "https://cloud.oxy.so";
 /**
  * Export the default Oxy API URL (for documentation)
  */
-export declare const OXY_API_URL: string;
+export declare const OXY_API_URL: any;
 /**
  * Pre-configured client instance for easy import
  * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL

package/dist/types/index.d.ts

@@ -23,8 +23,9 @@ export type { CrossDomainAuthOptions } from './CrossDomainAuth';
 export type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
 export type { PopupAuthOptions } from './mixins/OxyServices.popup';
 export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
+export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
-export type { ServiceApp } from './mixins/OxyServices.utility';
+export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse } from './mixins/OxyServices.contacts';
 export { KeyManager, SignatureService, RecoveryPhraseService, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto';
@@ -35,7 +36,7 @@ export type { TopicData, TopicTranslation } from './models/Topic';
 export { TopicType, TopicSource } from './models/Topic';
 export { DeviceManager } from './utils/deviceManager';
 export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager';
-export { SUPPORTED_LANGUAGES, getLanguageMetadata, getLanguageName, getNativeLanguageName, normalizeLanguageCode, } from './utils/languageUtils';
+export { SUPPORTED_LANGUAGES, getLanguageMetadata, getLanguageName, getNativeLanguageName, normalizeLanguageCode, isRTLLocale, } from './utils/languageUtils';
 export type { LanguageMetadata } from './utils/languageUtils';
 export { getPlatformOS, setPlatformOS, isWeb, isNative, isIOS, isAndroid, } from './utils/platform';
 export type { PlatformOS } from './utils/platform';

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

@@ -34,33 +34,93 @@ export interface ServiceTokenResponse {
     expiresIn: number;
     appName: string;
 }
+/**
+ * One cache entry per (apiKey hash) → issued token + the secret that produced it.
+ * The secret is kept around in raw Buffer form so we can perform a
+ * constant-time compare against any reused credential pair — this prevents an
+ * attacker who learned a victim's apiKey from receiving the victim's cached
+ * service token by simply guessing the secret.
+ *
+ * @internal
+ */
+interface ServiceTokenCacheEntry {
+    token: string;
+    /** Expiry as ms since epoch */
+    expiresAt: number;
+    /** Raw secret stored as Buffer for constant-time comparison on cache hit */
+    secretBuf: Buffer;
+    /** In-flight refresh promise (deduplicates concurrent callers) */
+    pending: Promise<string> | null;
+}
+/**
+ * Sentinel error raised when getServiceToken() is called with a known apiKey
+ * but a non-matching secret. Indicates either credential drift in the caller
+ * or a cross-tenant cache lookup attempt. Surface as a 401-equivalent.
+ */
+export declare class ServiceCredentialMismatchError extends Error {
+    constructor();
+}
 export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
-        /** @internal */ _serviceToken: string | null;
-        /** @internal */ _serviceTokenExp: number;
-        /** @internal */ _serviceApiKey: string | null;
-        /** @internal */ _serviceApiSecret: string | null;
         /**
-         * In-flight promise for service token fetch. Used to deduplicate concurrent
-         * calls to getServiceToken() — pattern mirrors AuthManager.refreshToken().
+         * Per-credential token cache.
+         *
+         * Keyed by SHA-256(apiKey). Each entry carries:
+         *   - the issued service JWT
+         *   - its expiry timestamp
+         *   - the secret that produced it (Buffer for constant-time compare)
+         *   - an optional in-flight promise to deduplicate concurrent refreshes
+         *
+         * The previous implementation kept ONE token/exp pair per OxyServices
+         * instance. That meant calling `getServiceToken(keyA, secretA)` populated
+         * the cache, and a subsequent `getServiceToken(keyB, secretB)` (different
+         * tenant) would receive tenant A's token. This is fixed by routing every
+         * lookup through the Map.
+         *
+         * @internal
+         */
+        _serviceTokenCache: Map<string, ServiceTokenCacheEntry>;
+        /** @internal Raw apiKey stored by configureServiceAuth() for use by getServiceToken() */
+        _serviceApiKey: string | null;
+        /** @internal Raw apiSecret stored by configureServiceAuth() for use by getServiceToken() */
+        _serviceApiSecret: string | null;
+        /**
+         * Hash an apiKey into a stable Map cache key. Uses Node's SHA-256 — service
+         * tokens are only ever issued by a Node host (the SDK on web/RN never has
+         * the apiSecret in the first place), so we can rely on Node crypto here.
+         *
          * @internal
          */
-        _serviceTokenPromise: Promise<string> | null;
+        _hashApiKey(apiKey: string): Promise<string>;
         /**
          * Configure service credentials for internal service-to-service communication.
          * Call this once at startup so that getServiceToken() and makeServiceRequest()
          * can automatically obtain and refresh tokens.
          *
+         * Calling this with credentials that differ from a previously-configured pair
+         * is allowed — each `(apiKey, apiSecret)` pair is cached independently, so
+         * legitimate multi-tenant hosts that need to switch credentials cannot leak
+         * one tenant's token to another tenant on the same instance.
+         *
          * @param apiKey - DeveloperApp API key (oxy_dk_*)
          * @param apiSecret - DeveloperApp API secret
          */
         configureServiceAuth(apiKey: string, apiSecret: string): void;
         /**
          * Get a service token for internal service-to-service communication.
-         * Tokens are short-lived (1h) and automatically cached/refreshed.
+         * Tokens are short-lived (1h) and automatically cached/refreshed per
+         * `(apiKey, apiSecret)` pair.
+         *
+         * Concurrent callers for the same credential pair share a single in-flight
+         * request to avoid hammering `/auth/service-token` when the cache is empty
+         * or expired.
          *
-         * Concurrent callers share a single in-flight request to avoid hammering
-         * `/auth/service-token` when the cache is empty or expired.
+         * **Security guarantee:** if the cache already holds a token for this
+         * apiKey but the supplied apiSecret does not constant-time match the
+         * secret that originally produced that token, this method throws
+         * `ServiceCredentialMismatchError` instead of returning the cached token.
+         * This prevents an attacker who learned a peer's apiKey from extracting
+         * their service token by polling with a wrong secret.
          *
          * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
          * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
@@ -71,7 +131,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * Separated so getServiceToken() can deduplicate concurrent calls.
          * @internal
          */
-        _doFetchServiceToken(key: string, secret: string): Promise<string>;
+        _doFetchServiceToken(key: string, secret: string, cacheKey: string, secretBuf: Buffer): Promise<string>;
         /**
          * Make an authenticated request on behalf of a user using a service token.
          * Automatically obtains/refreshes the service token.
@@ -240,3 +300,4 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         }>;
     };
 } & T;
+export {};

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

@@ -1,4 +1,4 @@
-import type { ApiError } from '../models/interfaces';
+import type { ApiError, User } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 /**
  * Result from the managed-accounts verification endpoint.
@@ -9,11 +9,31 @@ interface ActingAsVerification {
     role: 'owner' | 'admin' | 'editor';
 }
 /**
- * Service app metadata attached to requests authenticated with service tokens
+ * Result from the service-acting-as verification endpoint.
+ * Confirms that a given service app holds an active delegation grant for
+ * the supplied user, along with the explicit scope list the grant covers.
+ *
+ * The api side persists these via the `ServiceActingAs` model:
+ *   { serviceAppId, userId, scopes: string[], grantedAt, expiresAt }
+ *
+ * The SDK never inspects the grant directly — it round-trips through
+ * `GET /internal/service-acting-as/verify?appId=...&userId=...` so the
+ * authoritative store stays server-side.
+ */
+export interface ServiceActingAsVerification {
+    authorized: boolean;
+    scopes: string[];
+}
+/**
+ * Service app metadata attached to requests authenticated with service tokens.
+ * `scopes` reflects the scopes granted to the app at signup time (from the
+ * `DeveloperApp.scopes` field); route-level checks can require additional
+ * scope-narrowing via `requireScope()`.
  */
 export interface ServiceApp {
     appId: string;
     appName: string;
+    scopes: string[];
 }
 /**
  * Options for oxyClient.auth() middleware
@@ -22,7 +42,7 @@ interface AuthMiddlewareOptions {
     /** Enable debug logging (default: false) */
     debug?: boolean;
     /** Custom error handler - receives error object, can return response */
-    onError?: (error: ApiError) => any;
+    onError?: (error: ApiError) => unknown;
     /** Load full user profile from API (default: false for performance) */
     loadUser?: boolean;
     /** Optional auth - attach user if token present but don't block (default: false) */
@@ -31,8 +51,24 @@ interface AuthMiddlewareOptions {
      * JWT secret for verifying service token signatures locally.
      * When provided, service tokens will be cryptographically verified.
      * When omitted, service tokens will be rejected (secure default).
+     *
+     * **Migration note (>=1.11.14):** the Oxy API now signs service tokens
+     * with a dedicated `SERVICE_TOKEN_SECRET` distinct from `ACCESS_TOKEN_SECRET`.
+     * Pass that value here. If you keep passing the access-token secret you will
+     * still verify ALL signed-by-Oxy tokens (which is the whole class of bug
+     * H4 was supposed to prevent — DO NOT do that in production).
      */
     jwtSecret?: string;
+    /**
+     * Expected JWT issuer. Defaults to `'oxy-auth'`. Override only if you run
+     * a private fork of the Oxy auth server under a different `iss` claim.
+     */
+    expectedIssuer?: string;
+    /**
+     * Expected JWT audience. Defaults to `'oxy-api'`. Override only if your
+     * private fork mints tokens for a different audience.
+     */
+    expectedAudience?: string;
 }
 export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -41,6 +77,17 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
             result: ActingAsVerification | null;
             expiresAt: number;
         }>;
+        /**
+         * In-memory cache for service-acting-as verification.
+         * Negative results are cached for 1min to avoid hammering the verify
+         * endpoint when a service is misconfigured; positive grants are cached
+         * for 5min to amortize the round-trip without holding stale grants too long.
+         * @internal
+         */
+        _serviceActingAsCache: Map<string, {
+            result: ServiceActingAsVerification | null;
+            expiresAt: number;
+        }>;
         /**
          * Verify that a user is authorized to act as a managed account.
          * Results are cached in-memory for 5 minutes to avoid repeated API calls.
@@ -48,6 +95,19 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * @internal Used by the auth() middleware — not part of the public API
          */
         verifyActingAs(userId: string, accountId: string): Promise<ActingAsVerification | null>;
+        /**
+         * Verify that a service app holds an active delegation grant authorising
+         * it to act on behalf of `userId`. Returns the grant (with allowed scopes)
+         * on success or `null` if no valid grant exists. Negative answers are
+         * cached briefly to protect the verify endpoint from misconfigured callers.
+         *
+         * Implemented as a per-instance Map keyed by `appId:userId`. Cached
+         * positive grants live for 5 minutes (acceptable staleness window for an
+         * impersonation grant); revocations propagate within that window.
+         *
+         * @internal Used by the auth() middleware — not part of the public API
+         */
+        verifyServiceActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
         /**
          * Fetch link metadata
          */
@@ -70,9 +130,17 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * - Security comes from API-based session validation (`validateSession()`)
          *   which checks the session server-side on every request
          * - Service tokens (type: 'service') DO use cryptographic HMAC verification
-         *   via the `jwtSecret` option, since they are stateless
+         *   via the `jwtSecret` option, since they are stateless. Service tokens
+         *   are additionally checked for `aud`, `iss`, and `type` claims to prevent
+         *   cross-token-type confusion attacks.
          * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
-         *   direct access to `ACCESS_TOKEN_SECRET`
+         *   direct access to `SERVICE_TOKEN_SECRET` / `ACCESS_TOKEN_SECRET`.
+         *
+         * **Service-token delegation (X-Oxy-User-Id):**
+         * When a service token is accompanied by `X-Oxy-User-Id`, the SDK calls
+         * `verifyServiceActingAs(appId, userId)` to confirm an explicit delegation
+         * grant exists before attaching `req.userId`. A missing/expired grant
+         * results in a 403 — there is no fail-open path.
          *
          * @example
          * ```typescript
@@ -81,7 +149,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
          *
          * // Protect all routes under /protected
-         * app.use('/protected', oxy.auth());
+         * app.use('/protected', oxy.auth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
          *
          * // Access user in route handler
          * app.get('/protected/me', (req, res) => {
@@ -93,12 +161,15 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          *
          * // Optional auth - attach user if present, don't block if absent
          * app.use('/public', oxy.auth({ optional: true }));
+         *
+         * // Require a specific scope on a service-token-protected route
+         * app.use('/internal/files', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }), oxy.requireScope('files:write'));
          * ```
          *
          * @param options Optional configuration
          * @returns Express middleware function
          */
-        auth(options?: AuthMiddlewareOptions): (req: any, res: any, next: any) => Promise<any>;
+        auth(options?: AuthMiddlewareOptions): (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<unknown>;
         /**
          * Socket.IO authentication middleware factory
          *
@@ -125,7 +196,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          */
         authSocket(options?: {
             debug?: boolean;
-        }): (socket: any, next: (err?: Error) => void) => Promise<void>;
+        }): (socket: SocketLike, next: (err?: Error) => void) => Promise<void>;
         /**
          * Express.js middleware that only allows service tokens.
          * Use this for internal-only endpoints that should not be accessible
@@ -134,7 +205,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * @example
          * ```typescript
          * // Protect internal endpoints
-         * app.use('/internal', oxy.serviceAuth());
+         * app.use('/internal', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
          *
          * app.post('/internal/trigger', (req, res) => {
          *   console.log('Service app:', req.serviceApp);
@@ -145,7 +216,30 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
         serviceAuth(options?: {
             debug?: boolean;
             jwtSecret?: string;
-        }): (req: any, res: any, next: any) => Promise<void>;
+            expectedIssuer?: string;
+            expectedAudience?: string;
+        }): (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<void>;
+        /**
+         * Express.js middleware that enforces a specific service-token scope.
+         *
+         * Mount AFTER `auth()` / `serviceAuth()` — relies on `req.serviceApp` and
+         * (when delegation is in effect) `req.serviceActingAs.scopes`. The scope
+         * is granted if EITHER list contains it, mirroring the OAuth2 model where
+         * the app's app-level scopes and the per-user delegated scopes both count.
+         *
+         * Requests authenticated as a regular user (no service token) are rejected
+         * with 403 — scope-protected endpoints are service-to-service by design.
+         *
+         * @example
+         * ```typescript
+         * app.use(
+         *   '/internal/files',
+         *   oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }),
+         *   oxy.requireScope('files:write'),
+         * );
+         * ```
+         */
+        requireScope(scope: string): (req: AuthReq, res: AuthRes, next: AuthNext) => void;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
@@ -196,4 +290,44 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
         }>;
     };
 } & T;
+interface AuthReq {
+    method?: string;
+    path?: string;
+    headers: Record<string, string | string[] | undefined>;
+    query?: Record<string, unknown>;
+    userId?: string | null;
+    user?: User | null;
+    accessToken?: string;
+    sessionId?: string | null;
+    serviceApp?: ServiceApp;
+    serviceActingAs?: {
+        userId: string;
+        scopes: string[];
+    };
+    actingAs?: {
+        userId: string;
+        role: string;
+    };
+    originalUser?: {
+        id: string;
+    } & Partial<User>;
+}
+interface AuthRes {
+    status(code: number): AuthRes;
+    json(body: unknown): unknown;
+}
+type AuthNext = (err?: unknown) => void;
+interface SocketLike {
+    handshake?: {
+        auth?: {
+            token?: string;
+        };
+    };
+    data?: Record<string, unknown>;
+    user?: {
+        id: string;
+        userId: string;
+        sessionId?: string | null;
+    };
+}
 export {};

package/dist/types/utils/languageUtils.d.ts

@@ -35,3 +35,4 @@ export declare function getNativeLanguageName(languageCode: string | null | unde
  * @returns Normalized BCP-47 language code
  */
 export declare function normalizeLanguageCode(lang?: string | null): string;
+export declare function isRTLLocale(locale?: string | null): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "1.11.13",
+  "version": "1.11.14",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -70,7 +70,22 @@
     "clean": "rm -rf dist",
     "typescript": "tsc --noEmit",
     "test": "jest --passWithNoTests",
-    "lint": "biome lint --error-on-warnings ./src"
+    "lint": "biome lint --error-on-warnings ./src",
+    "release": "rm -rf dist && bun run build && release-it"
+  },
+  "release-it": {
+    "git": {
+      "tagName": "@oxyhq/core@${version}",
+      "tagAnnotation": "Release @oxyhq/core@${version}",
+      "commitMessage": "chore(core): release @oxyhq/core@${version}"
+    },
+    "github": {
+      "release": true,
+      "releaseName": "@oxyhq/core@${version}"
+    },
+    "npm": {
+      "publish": true
+    }
   },
   "dependencies": {
     "bip39": "^3.1.0",
@@ -105,6 +120,7 @@
     "@types/node": "^20.19.9",
     "expo-crypto": "~56.0.3",
     "expo-secure-store": "~56.0.4",
+    "release-it": "^19.0.6",
     "typescript": "^5.9.2"
   }
 }

package/src/OxyServices.ts

@@ -137,15 +137,29 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
   // Express.js middleware
   auth(options?: {
     debug?: boolean;
-    onError?: (error: any) => any;
+    onError?: (error: unknown) => unknown;
     loadUser?: boolean;
     optional?: boolean;
-  }): (req: any, res: any, next: any) => Promise<void>;
+    jwtSecret?: string;
+    expectedIssuer?: string;
+    expectedAudience?: string;
+  }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
 
   // Socket.IO middleware
   authSocket(options?: {
     debug?: boolean;
-  }): (socket: any, next: (err?: Error) => void) => Promise<void>;
+  }): (socket: unknown, next: (err?: Error) => void) => Promise<void>;
+
+  // Service-token-only middleware (delegates to auth() internally)
+  serviceAuth(options?: {
+    debug?: boolean;
+    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>;

package/src/index.ts

@@ -30,8 +30,9 @@ export type { CrossDomainAuthOptions } from './CrossDomainAuth';
 export type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
 export type { PopupAuthOptions } from './mixins/OxyServices.popup';
 export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
+export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
-export type { ServiceApp } from './mixins/OxyServices.utility';
+export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse } from './mixins/OxyServices.contacts';
 
@@ -62,6 +63,7 @@ export {
   getLanguageName,
   getNativeLanguageName,
   normalizeLanguageCode,
+  isRTLLocale,
 } from './utils/languageUtils';
 export type { LanguageMetadata } from './utils/languageUtils';