@oxyhq/core 12.8.0 → 12.10.0

package/src/index.ts

@@ -34,7 +34,13 @@ export type { AuthRefreshReason, AuthRefreshHandler } from './HttpService';
 // ---------------------------------------------------------------------------
 // Authentication
 // ---------------------------------------------------------------------------
-export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
+export {
+  ServiceCredentialMismatchError,
+} from './mixins/OxyServices.auth';
+export {
+  getCommonsApprovalBlockingReason,
+  parseCommonsApprovalExpiresAt,
+} from './utils/commonsApproval';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 // "Sign in with Oxy" — handoff (Workstream C)
 export type {
@@ -245,8 +251,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

@@ -9,6 +9,10 @@ import { loginResultSchema, safeParseContract } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
+export {
+  getCommonsApprovalBlockingReason,
+  parseCommonsApprovalExpiresAt,
+} from '../utils/commonsApproval';
 import { OxyAuthenticationError } from '../OxyServices.errors';
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
@@ -96,7 +100,7 @@ export interface CommonsSignInStatus {
  */
 export interface CommonsApprovalInfo {
   /** Sanitized, display-safe identity of the requesting application. */
-  application: PublicApplication;
+  application: PublicApplication | null;
   /** OAuth scopes the application is requesting. */
   scopes: string[];
   /** The origin the session is bound to (the RP web origin), when applicable. */
@@ -109,8 +113,8 @@ export interface CommonsApprovalInfo {
    * "not verified") by {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
    */
   originVerified: boolean;
-  /** Server-authoritative expiry (epoch milliseconds). */
-  expiresAt: number;
+  /** Server-authoritative expiry (epoch ms or ISO-8601 string from the API). */
+  expiresAt: number | string;
   /** Session lifecycle status. */
   status: string;
 }
@@ -122,11 +126,11 @@ export interface CommonsApprovalInfo {
  * into {@link CommonsApprovalInfo}.
  */
 interface CommonsApprovalInfoResponse {
-  application: PublicApplication;
+  application: PublicApplication | null;
   scopes: string[];
   boundOrigin?: string;
   originVerified?: unknown;
-  expiresAt: number;
+  expiresAt: number | string;
   status: string;
 }
 
@@ -497,14 +501,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 +530,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 +541,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 +552,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 +734,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 +761,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 +772,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.identityBackup.ts

@@ -218,6 +218,19 @@ export function OxyServicesIdentityBackupMixin<T extends typeof OxyServicesBase>
         );
         const payload = JSON.parse(new TextDecoder().decode(plaintext)) as BackupPayload;
 
+        if (!payload.privateKey || !payload.publicKey) {
+          throw new Error('Backup payload is missing key material');
+        }
+
+        const derivedFromPhrase = await RecoveryPhraseService.derivePublicKeyFromPhrase(phrase);
+        const derivedFromPrivate = KeyManager.derivePublicKey(payload.privateKey);
+        const phrasePk = derivedFromPhrase.toLowerCase();
+        const payloadPk = payload.publicKey.toLowerCase();
+        const privatePk = derivedFromPrivate.toLowerCase();
+        if (phrasePk !== payloadPk || privatePk !== payloadPk) {
+          throw new Error('Backup payload does not match the recovery phrase');
+        }
+
         // Persist the recovered key. Native-only; refuses to clobber a different
         // identity unless overwrite — the IdentityAlreadyExistsError propagates.
         return await KeyManager.importKeyPair(payload.privateKey, {

package/src/mixins/OxyServices.user.ts

@@ -606,6 +606,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         const result = await this.makeRequest<PrivacySettings>('PATCH', `/privacy/${id}/privacy`, settings, {
           cache: false,
         });
+        this.clearCacheByPrefix('GET:/session/user/');
+        this.clearCacheByPrefix('GET:/users/me');
+        this.clearCacheByPrefix('GET:/profiles/username/');
+        this.clearCacheEntry(`GET:/users/${id}`);
         this.clearCacheEntry(`GET:/privacy/${id}/privacy`);
         return result;
       } catch (error) {

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__/identityBackup.test.ts

@@ -15,6 +15,7 @@
 import { OxyServices } from '../../OxyServices';
 import { KeyManager, IdentityAlreadyExistsError } from '../../crypto/keyManager';
 import { RecoveryPhraseService } from '../../crypto/recoveryPhrase';
+import { encryptAead, decryptAead } from '../../crypto/aead';
 import type { EncryptedBackupEnvelope, BackupUploadRequest } from '@oxyhq/contracts';
 
 const FIXED_PHRASE =
@@ -192,6 +193,62 @@ describe('encrypted identity backup mixin', () => {
     await expect(oxy.restoreFromEncryptedBackup(FIXED_PHRASE)).rejects.toThrow();
   });
 
+  it('rejects when decrypted payload publicKey does not match the recovery phrase', async () => {
+    fetchMock.mockResolvedValueOnce(plainResponse({ exists: true }));
+    await oxy.createEncryptedBackup(FIXED_PHRASE);
+    const uploaded = uploadBodyFromCall(0);
+
+    const { backupKey } = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+    const aad = new TextEncoder().encode(
+      JSON.stringify({ version: uploaded.version, publicKeyHint: uploaded.publicKeyHint }),
+    );
+    const fromHex = (hex: string): Uint8Array => {
+      const out = new Uint8Array(hex.length / 2);
+      for (let i = 0; i < out.length; i += 1) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+      }
+      return out;
+    };
+    const toHex = (bytes: Uint8Array): string =>
+      Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+
+    const plaintext = decryptAead(
+      backupKey,
+      fromHex(uploaded.nonce),
+      fromHex(uploaded.ciphertext),
+      aad,
+    );
+    const payload = JSON.parse(new TextDecoder().decode(plaintext)) as {
+      privateKey: string;
+      publicKey: string;
+      createdAt: string;
+    };
+    payload.publicKey = `${payload.publicKey.slice(0, -1)}0`;
+
+    const { nonce, ciphertext } = encryptAead(
+      backupKey,
+      new TextEncoder().encode(JSON.stringify(payload)),
+      aad,
+    );
+    const tampered: EncryptedBackupEnvelope = {
+      version: uploaded.version,
+      algorithm: uploaded.algorithm,
+      kdfInfo: uploaded.kdfInfo,
+      nonce: toHex(nonce),
+      ciphertext: toHex(ciphertext),
+      publicKeyHint: uploaded.publicKeyHint,
+      createdAt: uploaded.createdAt,
+    };
+
+    const importSpy = jest.spyOn(KeyManager, 'importKeyPair').mockResolvedValue('x');
+    fetchMock.mockResolvedValueOnce(plainResponse(tampered));
+
+    await expect(oxy.restoreFromEncryptedBackup(FIXED_PHRASE)).rejects.toThrow(
+      /does not match the recovery phrase/,
+    );
+    expect(importSpy).not.toHaveBeenCalled();
+  });
+
   it('propagates IdentityAlreadyExistsError UNCHANGED (so the caller can offer overwrite)', async () => {
     fetchMock.mockResolvedValueOnce(plainResponse({ exists: true }));
     await oxy.createEncryptedBackup(FIXED_PHRASE);

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

@@ -129,6 +129,7 @@ describe('privacy cache invalidation', () => {
 
   it('invalidates the exact logical keys on block/restrict/settings writes', async () => {
     const clearSpy = jest.spyOn(oxy, 'clearCacheEntry');
+    const clearPrefixSpy = jest.spyOn(oxy, 'clearCacheByPrefix');
 
     fetchMock.mockResolvedValueOnce(jsonResponse({ message: 'ok' }));
     await oxy.blockUser('u1');
@@ -141,7 +142,12 @@ describe('privacy cache invalidation', () => {
     fetchMock.mockResolvedValueOnce(jsonResponse({ isPrivateAccount: true }));
     await oxy.updatePrivacySettings({ isPrivateAccount: true }, 'me');
     expect(clearSpy).toHaveBeenCalledWith('GET:/privacy/me/privacy');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/users/me');
+    expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/session/user/');
+    expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/users/me');
+    expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/profiles/username/');
 
     clearSpy.mockRestore();
+    clearPrefixSpy.mockRestore();
   });
 });

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

@@ -0,0 +1,60 @@
+import {
+  getCommonsApprovalBlockingReason,
+  parseCommonsApprovalExpiresAt,
+} from '../commonsApproval';
+
+describe('commonsApproval validation', () => {
+  const application = {
+    id: 'app1',
+    name: 'Mention',
+    type: 'first_party' as const,
+    isOfficial: true,
+    isInternal: false,
+    scopes: ['profile'],
+  };
+
+  it('blocks when the application is missing', () => {
+    expect(
+      getCommonsApprovalBlockingReason({
+        application: null,
+        status: 'pending',
+        expiresAt: Date.now() + 60_000,
+      }),
+    ).toMatch(/could not be resolved/i);
+  });
+
+  it('blocks non-pending sessions', () => {
+    expect(
+      getCommonsApprovalBlockingReason({
+        application,
+        status: 'expired',
+        expiresAt: Date.now() + 60_000,
+      }),
+    ).toMatch(/invalid, already used, or expired/i);
+  });
+
+  it('blocks expired pending sessions (ISO expiresAt)', () => {
+    expect(
+      getCommonsApprovalBlockingReason({
+        application,
+        status: 'pending',
+        expiresAt: new Date(Date.now() - 60_000).toISOString(),
+      }),
+    ).toMatch(/expired/i);
+  });
+
+  it('allows a pending, unexpired session', () => {
+    expect(
+      getCommonsApprovalBlockingReason({
+        application,
+        status: 'pending',
+        expiresAt: Date.now() + 60_000,
+      }),
+    ).toBeNull();
+  });
+
+  it('parses ISO expiresAt strings', () => {
+    const iso = '2026-07-19T12:00:00.000Z';
+    expect(parseCommonsApprovalExpiresAt(iso)).toBe(Date.parse(iso));
+  });
+});

package/src/utils/commonsApproval.ts

@@ -0,0 +1,39 @@
+import type { PublicApplication } from '../mixins/OxyServices.connectedApps';
+
+export interface CommonsApprovalValidationInput {
+  application: PublicApplication | null;
+  status: string;
+  expiresAt: number | string;
+}
+
+/**
+ * Returns a user-facing blocking reason when an approval payload must not be
+ * shown as actionable, or `null` when the request is still pending and valid.
+ */
+export function getCommonsApprovalBlockingReason(
+  info: CommonsApprovalValidationInput,
+): string | null {
+  if (!info.application?.id) {
+    return 'The requesting application could not be resolved.';
+  }
+  if (info.status !== 'pending') {
+    return 'This sign-in request is invalid, already used, or expired.';
+  }
+  const expiresAtMs = parseCommonsApprovalExpiresAt(info.expiresAt);
+  if (expiresAtMs !== null && expiresAtMs < Date.now()) {
+    return 'This sign-in request has expired. Ask for a new QR code.';
+  }
+  return null;
+}
+
+/** Normalize API `expiresAt` (number or ISO string) to epoch ms. */
+export function parseCommonsApprovalExpiresAt(
+  expiresAt: CommonsApprovalValidationInput['expiresAt'],
+): number | null {
+  if (typeof expiresAt === 'number' && Number.isFinite(expiresAt)) return expiresAt;
+  if (typeof expiresAt === 'string') {
+    const ms = Date.parse(expiresAt);
+    return Number.isFinite(ms) ? ms : null;
+  }
+  return null;
+}