@oxyhq/core 12.8.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/__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);
     });