@oxyhq/core 12.7.0 → 12.9.0

package/src/index.ts

@@ -245,8 +245,14 @@ export {
     KeyManager,
     IdentityAlreadyExistsError,
     IdentityPersistError,
+    IdentityUnavailableError,
 } from './crypto/keyManager';
-export type { KeyPair } from './crypto/keyManager';
+export type { KeyPair, IdentityStatus, IdentityRecoveryResult } from './crypto/keyManager';
+export {
+    readIdentityMarker,
+    updateIdentityMarker,
+} from './crypto/identityMarker';
+export type { IdentityMarker } from './crypto/identityMarker';
 export { SignatureService } from './crypto/signatureService';
 export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';

package/src/mixins/OxyServices.auth.ts

@@ -497,14 +497,21 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     /**
      * Request an authentication challenge
      * The client must sign this challenge with their private key
-     * 
+     *
      * @param publicKey - The user's public key
+     * @param requestOptions - Optional per-call transport overrides (`retry`,
+     *   `timeout`). Interactive callers omit it (defaults keep retries); the
+     *   cold-boot `shared-key-signin` step passes `{ retry: false }` so a slow
+     *   network cannot multiply boot latency via the inner retry loop.
      */
-    async requestChallenge(publicKey: string): Promise<ChallengeResponse> {
+    async requestChallenge(
+      publicKey: string,
+      requestOptions?: { retry?: boolean; timeout?: number },
+    ): Promise<ChallengeResponse> {
       try {
         return await this.makeRequest<ChallengeResponse>('POST', '/auth/challenge', {
           publicKey,
-        }, { cache: false });
+        }, { cache: false, ...requestOptions });
       } catch (error) {
         throw this.handleError(error);
       }
@@ -519,6 +526,10 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * @param timestamp - Timestamp when the signature was created
      * @param deviceName - Optional device name
      * @param deviceFingerprint - Optional device fingerprint
+     * @param requestOptions - Optional per-call transport overrides (`retry`,
+     *   `timeout`). Interactive callers omit it (defaults keep retries); the
+     *   cold-boot `shared-key-signin` step passes `{ retry: false }` so a slow
+     *   network cannot multiply boot latency via the inner retry loop.
      */
     async verifyChallenge(
       publicKey: string,
@@ -526,7 +537,8 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       signature: string,
       timestamp: number,
       deviceName?: string,
-      deviceFingerprint?: string
+      deviceFingerprint?: string,
+      requestOptions?: { retry?: boolean; timeout?: number },
     ): Promise<SessionLoginResponse> {
       try {
         const res = await this.makeRequest<SessionLoginResponse>('POST', '/auth/verify', {
@@ -536,7 +548,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           timestamp,
           deviceName,
           deviceFingerprint,
-        }, { cache: false });
+        }, { cache: false, ...requestOptions });
 
         // Plant the freshly-minted tokens, mirroring `claimSessionByToken`.
         // `/auth/verify` returns the first access token (and refresh token) in
@@ -718,9 +730,20 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      *
      * The cold-boot wiring that CALLS this lives in `OxyContext`
      * (`@oxyhq/services`); this method just performs the exchange.
+     *
+     * @param opts.requestOptions - Optional per-call transport overrides
+     *   (`retry`, `timeout`) forwarded to BOTH the `requestChallenge` and
+     *   `verifyChallenge` round-trips. Interactive flows omit it (defaults keep
+     *   retries); the cold-boot `shared-key-signin` step passes `{ retry: false }`
+     *   so this network step cannot multiply boot latency via the inner retry
+     *   loop. The token-refresh scheduler / 401 lane still retry later.
      */
     async signInWithSharedIdentity(
-      opts: { deviceName?: string; deviceFingerprint?: string } = {}
+      opts: {
+        deviceName?: string;
+        deviceFingerprint?: string;
+        requestOptions?: { retry?: boolean; timeout?: number };
+      } = {}
     ): Promise<SessionLoginResponse | null> {
       try {
         // `hasSharedIdentity()` already returns false on web (the shared
@@ -734,7 +757,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           return null;
         }
 
-        const { challenge } = await this.requestChallenge(sharedPublicKey);
+        const { challenge } = await this.requestChallenge(sharedPublicKey, opts.requestOptions);
         const signed = await SignatureService.signChallengeWithSharedKey(challenge);
 
         // `signed.challenge` carries the SIGNATURE (mirrors `signChallenge`).
@@ -745,6 +768,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           signed.timestamp,
           opts.deviceName,
           opts.deviceFingerprint,
+          opts.requestOptions,
         );
       } catch (error) {
         throw this.handleError(error);

package/src/mixins/OxyServices.deviceBoot.ts

@@ -39,6 +39,14 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
      * `no_active_session`) to decide whether to drop the secret and fall back or
      * resolve signed-out.
      *
+     * `retry: false`: the mint is a single logical attempt. The proactive
+     * token-refresh scheduler and the reactive 401 lane already own backoff and
+     * re-arm, so `HttpService`'s inner retry loop here would only multiply the
+     * mint's latency on a slow/black-hole network (3 retries × 5s timeout ≈ 20s
+     * per lane) with no correctness benefit — it is the dominant term in the cold
+     * boot's worst-case time-to-route. A transient failure surfaces once and the
+     * scheduler/401 path retries it later.
+     *
      * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
      */
     async mintFromDeviceSecret(
@@ -50,7 +58,7 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
           'POST',
           '/session/device/token',
           { deviceId, deviceSecret },
-          { cache: false, skipAuth: true },
+          { cache: false, skipAuth: true, retry: false },
         );
         const parsed = safeParseContract(deviceTokenMintResponseSchema, res);
         if (!parsed) {

package/src/mixins/OxyServices.utility.ts

@@ -12,6 +12,7 @@ import { loadNodeCrypto } from '@oxyhq/protocol';
 import { buildUrl } from '../utils/apiUtils';
 import { logger } from '../logger';
 import { CACHE_TIMES } from './mixinHelpers';
+import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 
 interface JwtPayload {
   exp?: number;
@@ -25,6 +26,7 @@ interface JwtPayload {
   scopes?: string[];
   aud?: string | string[];
   iss?: string;
+  environment?: string;
   [key: string]: unknown;
 }
 
@@ -57,6 +59,8 @@ export interface ServiceApp {
   scopes: string[];
   /** The credentialId of the specific service credential that minted this token. */
   credentialId: string;
+  /** Test/live isolation (F2.0): which `ApplicationCredential.environment` minted this token. */
+  environment: OxyServiceEnvironment;
 }
 
 /**
@@ -94,6 +98,13 @@ class ServiceTokenClaimError extends Error {
   }
 }
 
+function isOxyServiceEnvironment(value: unknown): value is OxyServiceEnvironment {
+  return (
+    typeof value === 'string' &&
+    (OXY_SERVICE_ENVIRONMENTS as readonly string[]).includes(value)
+  );
+}
+
 /**
  * Options for oxyClient.auth() middleware
  */
@@ -459,7 +470,13 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             // Validate required service token fields
             const appId = decoded.appId;
             const credentialId = decoded.credentialId;
-            if (!appId || typeof credentialId !== 'string' || credentialId.length === 0) {
+            const environment = decoded.environment;
+            if (
+              !appId ||
+              typeof credentialId !== 'string' ||
+              credentialId.length === 0 ||
+              !isOxyServiceEnvironment(environment)
+            ) {
               if (optional) {
                 req.userId = null;
                 req.user = null;
@@ -513,6 +530,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               appName: decoded.appName || 'unknown',
               credentialId,
               scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
+              environment,
             };
 
             if (debug) {

package/src/mixins/__tests__/OxyServices.deviceBoot.test.ts

@@ -31,15 +31,17 @@ describe('OxyServices.deviceBoot', () => {
       },
     };
 
-    it('POSTs deviceId + deviceSecret with skipAuth (no bearer, no cache) and returns the validated mint', async () => {
+    it('POSTs deviceId + deviceSecret with skipAuth + retry:false (no bearer, no cache, single attempt) and returns the validated mint', async () => {
       makeRequest.mockResolvedValueOnce(MINT);
       const result = await oxy.mintFromDeviceSecret('dev-1', 'ds-current-secret');
       expect(result).toEqual(MINT);
+      // `retry: false` — the scheduler/401 lane own backoff; HttpService's inner
+      // retry here would only multiply cold-boot latency on a slow network.
       expect(makeRequest).toHaveBeenCalledWith(
         'POST',
         '/session/device/token',
         { deviceId: 'dev-1', deviceSecret: 'ds-current-secret' },
-        { cache: false, skipAuth: true },
+        { cache: false, skipAuth: true, retry: false },
       );
     });
 

package/src/mixins/__tests__/commonsSignIn.test.ts

@@ -242,6 +242,51 @@ describe('OxyServices — "Sign in with Oxy" handoff', () => {
     });
   });
 
+  describe('requestChallenge / verifyChallenge — requestOptions spread into makeRequest', () => {
+    it('requestChallenge omits transport overrides by default (retries ON) and spreads them when given', async () => {
+      makeRequestSpy.mockResolvedValue(challengeFixture);
+
+      await oxy.requestChallenge('pub-x');
+      expect(makeRequestSpy).toHaveBeenLastCalledWith(
+        'POST',
+        '/auth/challenge',
+        { publicKey: 'pub-x' },
+        { cache: false },
+      );
+
+      await oxy.requestChallenge('pub-x', { retry: false });
+      expect(makeRequestSpy).toHaveBeenLastCalledWith(
+        'POST',
+        '/auth/challenge',
+        { publicKey: 'pub-x' },
+        { cache: false, retry: false },
+      );
+    });
+
+    it('verifyChallenge spreads requestOptions (retry + timeout) into makeRequest', async () => {
+      makeRequestSpy.mockResolvedValue(sessionFixture);
+
+      await oxy.verifyChallenge('pub-x', 'chal', 'sig', 123, 'dev', 'fp', {
+        retry: false,
+        timeout: 9000,
+      });
+
+      expect(makeRequestSpy).toHaveBeenLastCalledWith(
+        'POST',
+        '/auth/verify',
+        {
+          publicKey: 'pub-x',
+          challenge: 'chal',
+          signature: 'sig',
+          timestamp: 123,
+          deviceName: 'dev',
+          deviceFingerprint: 'fp',
+        },
+        { cache: false, retry: false, timeout: 9000 },
+      );
+    });
+  });
+
   describe('signInWithSharedIdentity (Mechanism A — same-device SSO)', () => {
     it('mints a session from the shared key when one exists (native)', async () => {
       jest.spyOn(KeyManager, 'hasSharedIdentity').mockResolvedValue(true);
@@ -263,7 +308,9 @@ describe('OxyServices — "Sign in with Oxy" handoff', () => {
         deviceFingerprint: 'fp-1',
       });
 
-      expect(requestChallengeSpy).toHaveBeenCalledWith('shared-pub');
+      // No requestOptions passed → both round-trips get `undefined` (defaults:
+      // retries ON), preserving interactive behaviour.
+      expect(requestChallengeSpy).toHaveBeenCalledWith('shared-pub', undefined);
       expect(verifyChallengeSpy).toHaveBeenCalledWith(
         'shared-pub',
         'chal-shared',
@@ -271,6 +318,42 @@ describe('OxyServices — "Sign in with Oxy" handoff', () => {
         1700000000456,
         'iPad',
         'fp-1',
+        undefined,
+      );
+      expect(result).toEqual(sessionFixture);
+    });
+
+    it('threads requestOptions into BOTH the challenge and verify round-trips (cold-boot retry:false)', async () => {
+      jest.spyOn(KeyManager, 'hasSharedIdentity').mockResolvedValue(true);
+      jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue('shared-pub');
+      const requestChallengeSpy = jest
+        .spyOn(oxy, 'requestChallenge')
+        .mockResolvedValue({ challenge: 'chal-shared', expiresAt: '2026-06-26T00:05:00.000Z' });
+      jest.spyOn(SignatureService, 'signChallengeWithSharedKey').mockResolvedValue({
+        challenge: 'sig-shared',
+        publicKey: 'shared-pub',
+        timestamp: 1700000000456,
+      });
+      const verifyChallengeSpy = jest
+        .spyOn(oxy, 'verifyChallenge')
+        .mockResolvedValue(sessionFixture);
+
+      const result = await oxy.signInWithSharedIdentity({
+        requestOptions: { retry: false },
+      });
+
+      // The SAME requestOptions object is forwarded to both calls — this is how
+      // the cold-boot `shared-key-signin` step keeps its two round-trips as
+      // single attempts without changing interactive defaults.
+      expect(requestChallengeSpy).toHaveBeenCalledWith('shared-pub', { retry: false });
+      expect(verifyChallengeSpy).toHaveBeenCalledWith(
+        'shared-pub',
+        'chal-shared',
+        'sig-shared',
+        1700000000456,
+        undefined,
+        undefined,
+        { retry: false },
       );
       expect(result).toEqual(sessionFixture);
     });

package/src/mixins/__tests__/serviceAuth.test.ts

@@ -30,6 +30,7 @@ interface ServiceTokenClaims {
   scopes?: string[];
   aud?: string | string[];
   iss?: string;
+  environment?: string;
   exp?: number;
   iat?: number;
   [key: string]: unknown;
@@ -49,6 +50,7 @@ const signServiceToken = (claims: ServiceTokenClaims, secret: string): string =>
     aud: 'oxy-api',
     iss: 'oxy-auth',
     credentialId: 'cred-1',
+    environment: 'production',
     ...claims,
   };
   const headerB64 = b64url(JSON.stringify(header));
@@ -183,6 +185,7 @@ describe('C3: service-token acting-as enforcement', () => {
       appName: 'trusted-service',
       credentialId: 'cred-1',
       scopes: ['user:read'],
+      environment: 'production',
     });
   });
 
@@ -762,3 +765,65 @@ describe('requireScope() middleware', () => {
     expect(() => oxy.requireScope(undefined as unknown as string)).toThrow('requireScope');
   });
 });
+
+// ---------------------------------------------------------------------------
+// service-token environment claim (F2.0 task 1b) — test/live isolation.
+// ---------------------------------------------------------------------------
+
+describe('service-token environment claim (F2.0 task 1b)', () => {
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+  });
+
+  it('populates req.serviceApp.environment from the token claim', async () => {
+    const token = signServiceToken(
+      { appId: 'app-1', appName: 'svc', environment: 'development' },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
+    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(req.serviceApp).toMatchObject({ appId: 'app-1', environment: 'development' });
+  });
+
+  it('rejects a service token missing the environment claim (401)', async () => {
+    const token = signServiceToken(
+      { appId: 'app-1', appName: 'svc', environment: undefined },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
+    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+  });
+
+  it('rejects a service token with an environment value outside the known set (401)', async () => {
+    const token = signServiceToken(
+      { appId: 'app-1', appName: 'svc', environment: 'bogus' },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
+    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+  });
+});

package/src/server/auth.ts

@@ -1,5 +1,9 @@
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import type { OxyServices } from '../OxyServices';
+import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
+
+export { OXY_SERVICE_ENVIRONMENTS };
+export type { OxyServiceEnvironment };
 
 export interface OxyRequestUser {
   id: string;
@@ -15,6 +19,7 @@ export interface OxyServiceAppContext {
   appName: string;
   scopes: string[];
   credentialId: string;
+  environment: OxyServiceEnvironment;
 }
 
 export interface OxyServiceActingAsContext {

package/src/server/index.ts

@@ -22,6 +22,7 @@ export {
   getRequiredOxyUserId,
   isOxyAuthenticated,
   requireOxyAuth,
+  OXY_SERVICE_ENVIRONMENTS,
 } from './auth';
 export type {
   OxyAuthenticatedRequest,
@@ -30,6 +31,7 @@ export type {
   OxyRequestUser,
   OxyServiceActingAsContext,
   OxyServiceAppContext,
+  OxyServiceEnvironment,
 } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';

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

@@ -0,0 +1,7 @@
+import { OXY_SERVICE_ENVIRONMENTS } from '../oxyServiceEnvironment';
+
+describe('OXY_SERVICE_ENVIRONMENTS', () => {
+  it('lists exactly development, staging, production, in that order', () => {
+    expect(OXY_SERVICE_ENVIRONMENTS).toEqual(['development', 'staging', 'production']);
+  });
+});

package/src/utils/oxyServiceEnvironment.ts

@@ -0,0 +1,17 @@
+/**
+ * Environment segregation for Oxy service-token JWTs (test/live isolation).
+ * Mirrors `ApplicationCredentialEnvironment` on the API's `ApplicationCredential`
+ * model (`packages/api/src/models/ApplicationCredential.ts`) as an INDEPENDENT
+ * literal union — `@oxyhq/core` has zero dependency on `@oxyhq/api`, so this is
+ * kept in sync by hand, not by import.
+ *
+ * Defined here (not in `server/auth.ts` or `mixins/OxyServices.utility.ts`
+ * directly) because BOTH of those files need it and neither may import from
+ * the other: `server/` types import `express` (Node-only, a peer dependency
+ * `mixins/` deliberately avoids so it stays safe to bundle into RN/browser
+ * consumers — see the "Local request/response/socket typing" comment in
+ * `OxyServices.utility.ts`). This file has zero imports, so both sides can
+ * depend on it without crossing that boundary.
+ */
+export const OXY_SERVICE_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
+export type OxyServiceEnvironment = (typeof OXY_SERVICE_ENVIRONMENTS)[number];