@oxyhq/core 12.9.0 → 12.10.0

package/dist/types/crypto/keyManager.d.ts

@@ -396,6 +396,39 @@ export declare class KeyManager {
      * and NEVER cached, so a poisoned "no identity" verdict can no longer stick.
      */
     static getPublicKey(): Promise<string | null>;
+    /**
+     * Persist the recovery mnemonic (the 12-word phrase) into its dedicated,
+     * device-only keychain slot so the user can re-reveal it from Settings after
+     * onboarding.
+     *
+     * Called best-effort at identity creation/import, where the phrase is already
+     * in memory: a failure to persist it must NEVER fail the identity itself, so
+     * callers deliberately swallow the thrown error (logging it). Storage errors
+     * throw {@link IdentityUnavailableError} — same "cannot determine" semantics as
+     * the other getters — so a caller MAY observe/log the failure.
+     *
+     * The mnemonic is stored ONLY here — never in the marker, `getIdentityStatus`,
+     * logs, or any exported bundle.
+     */
+    static storeRecoveryMnemonic(mnemonic: string): Promise<void>;
+    /**
+     * Read the stored recovery mnemonic for re-reveal in Settings.
+     *
+     * Returns the phrase, or `null` when a read SUCCEEDS and finds none — the
+     * expected result for any identity created/imported before this feature
+     * existed, since the phrase was never captured for those. THROWS
+     * {@link IdentityUnavailableError} when storage is unreadable (keychain locked
+     * / module load failure), matching {@link getPublicKey}'s contract — a thrown
+     * read is never flattened to `null`, so a caller distinguishes "phrase was
+     * never stored" from "keychain temporarily locked, retry".
+     */
+    static getRecoveryMnemonic(): Promise<string | null>;
+    /**
+     * Delete the stored recovery mnemonic. Best-effort: a delete failure is logged
+     * and swallowed, never thrown — it runs inside the identity-deletion path where
+     * an unreadable keychain must not abort the wider teardown.
+     */
+    static deleteRecoveryMnemonic(): Promise<void>;
     /**
      * Check if a complete, parseable identity exists on this device.
      *

package/dist/types/index.d.ts

@@ -21,7 +21,8 @@ export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthen
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export type { LinkedHttpClient } from './OxyServices.base';
 export type { AuthRefreshReason, AuthRefreshHandler } from './HttpService';
-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';
 export type { CommonsSignInHandle, CommonsSignInStatus, CommonsApprovalInfo, CommonsSignInActionResult, } from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';

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

@@ -8,6 +8,7 @@ import type { LoginResult, LoginSessionResult } 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';
 export interface ChallengeResponse {
     challenge: string;
     expiresAt: string;
@@ -71,7 +72,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. */
@@ -84,8 +85,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;
 }
@@ -596,4 +597,3 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         }>;
     };
 } & T;
-export {};

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

@@ -0,0 +1,13 @@
+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 declare function getCommonsApprovalBlockingReason(info: CommonsApprovalValidationInput): string | null;
+/** Normalize API `expiresAt` (number or ISO string) to epoch ms. */
+export declare function parseCommonsApprovalExpiresAt(expiresAt: CommonsApprovalValidationInput['expiresAt']): number | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.9.0",
+  "version": "12.10.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/crypto/__tests__/keyManager.recoveryMnemonic.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Recovery-mnemonic storage: a dedicated, device-only keychain slot that lets a
+ * user re-reveal their 12-word phrase from Settings. Isolated from the identity
+ * primary/backup slots (its own keychain service), null-on-absent, typed-throw
+ * on a locked keychain, and wiped when the identity is deleted.
+ */
+
+import { setPlatformOS } from '../../utils/platform';
+
+jest.mock(
+  'expo-secure-store',
+  () => {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { createSecureStoreMock } = require('./identityMocks');
+    return createSecureStoreMock();
+  },
+  { virtual: true },
+);
+
+jest.mock(
+  'expo-crypto',
+  () => ({
+    __esModule: true,
+    getRandomBytes: (length: number) => {
+      const out = new Uint8Array(length);
+      for (let i = 0; i < length; i++) out[i] = (Math.random() * 256) & 0xff;
+      return out;
+    },
+    digestStringAsync: async () => '0'.repeat(64),
+    CryptoDigestAlgorithm: { SHA256: 'SHA-256' },
+  }),
+  { virtual: true },
+);
+
+jest.mock('@oxyhq/protocol', () => {
+  const actual = jest.requireActual('@oxyhq/protocol');
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { createAsyncStorageMock } = require('./identityMocks');
+  const asyncStorage = createAsyncStorageMock();
+  return {
+    __esModule: true,
+    ...actual,
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    loadExpoCrypto: async () => require('expo-crypto'),
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    loadSecureStore: async () => require('expo-secure-store'),
+    loadAsyncStorage: async () => ({ default: asyncStorage }),
+    loadSharedIdentityBridge: async () => null,
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    loadNodeCrypto: async () => require('crypto'),
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    getRandomBytesRN: (n: number) => require('expo-crypto').getRandomBytes(n),
+  };
+});
+
+const MNEMONIC_SVC = 'oxy_identity_mnemonic';
+const MNEMONIC_KEY = 'oxy_identity_mnemonic_v1';
+const PRIMARY_SVC = 'oxy_identity';
+const PHRASE = 'legal winner thank year wave sausage worth useful legal winner thank yellow';
+
+interface SecureStoreTestHandle {
+  __resetStore__: () => void;
+  __getRaw__: (key: string, service?: string) => string | null;
+  __simulateKeystoreDeath__: (service: string) => void;
+  __failPlan__: { failKey?: string; failOp?: 'set' | 'get'; failTimes?: number; failService?: string };
+}
+
+describe('KeyManager recovery mnemonic storage', () => {
+  let KeyManager: typeof import('../keyManager').KeyManager;
+  let IdentityUnavailableError: typeof import('../keyManager').IdentityUnavailableError;
+  let ss: SecureStoreTestHandle;
+
+  beforeAll(() => {
+    setPlatformOS('ios');
+    (globalThis as unknown as { navigator: unknown }).navigator = { product: 'ReactNative' };
+  });
+
+  beforeEach(async () => {
+    jest.resetModules();
+    setPlatformOS('ios');
+    ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    ss.__resetStore__();
+    const km = await import('../keyManager');
+    KeyManager = km.KeyManager;
+    IdentityUnavailableError = km.IdentityUnavailableError;
+  });
+
+  it('round-trips a stored mnemonic', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    expect(await KeyManager.getRecoveryMnemonic()).toBe(PHRASE);
+  });
+
+  it('persists under its OWN keychain service, isolated from the identity slots', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    // Present under the mnemonic service, invisible under the primary service.
+    expect(ss.__getRaw__(MNEMONIC_KEY, MNEMONIC_SVC)).toBe(PHRASE);
+    expect(ss.__getRaw__(MNEMONIC_KEY, PRIMARY_SVC)).toBeNull();
+  });
+
+  it('returns null when no mnemonic was ever stored (pre-feature identity)', async () => {
+    expect(await KeyManager.getRecoveryMnemonic()).toBeNull();
+  });
+
+  it('survives a keystore death of the identity primary service', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    // The identity primary slot dies; the mnemonic lives in a distinct service.
+    ss.__simulateKeystoreDeath__(PRIMARY_SVC);
+    expect(await KeyManager.getRecoveryMnemonic()).toBe(PHRASE);
+  });
+
+  it('throws IdentityUnavailableError (never null) when the read throws', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    ss.__failPlan__.failOp = 'get';
+    ss.__failPlan__.failKey = MNEMONIC_KEY;
+    ss.__failPlan__.failService = MNEMONIC_SVC;
+    await expect(KeyManager.getRecoveryMnemonic()).rejects.toBeInstanceOf(IdentityUnavailableError);
+  });
+
+  it('throws IdentityUnavailableError when the write throws', async () => {
+    ss.__failPlan__.failOp = 'set';
+    ss.__failPlan__.failKey = MNEMONIC_KEY;
+    ss.__failPlan__.failService = MNEMONIC_SVC;
+    await expect(KeyManager.storeRecoveryMnemonic(PHRASE)).rejects.toBeInstanceOf(IdentityUnavailableError);
+  });
+
+  it('deleteRecoveryMnemonic removes the stored phrase', async () => {
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    await KeyManager.deleteRecoveryMnemonic();
+    expect(await KeyManager.getRecoveryMnemonic()).toBeNull();
+  });
+
+  it('deleteIdentity(force) wipes the stored mnemonic', async () => {
+    await KeyManager.createIdentity();
+    await KeyManager.storeRecoveryMnemonic(PHRASE);
+    await KeyManager.deleteIdentity(true, true, true);
+    expect(await KeyManager.getRecoveryMnemonic()).toBeNull();
+  });
+});

package/src/crypto/keyManager.ts

@@ -198,6 +198,25 @@ const V2_STORAGE_KEYS = {
   BACKUP_TIMESTAMP: 'oxy_identity_backup_timestamp_v2',
 } as const;
 
+/**
+ * Dedicated keychain slot for the recovery mnemonic (the 12-word phrase).
+ *
+ * Stored under its OWN keychain service — distinct from the v2 primary, backup,
+ * and shared slots — so it shares an AndroidKeyStore key with none of them
+ * (blast-radius isolation, same rationale as the v2 primary/backup split).
+ * Written `WHEN_UNLOCKED_THIS_DEVICE_ONLY` and NEVER exported off-device: it
+ * exists solely so the user can RE-READ their phrase from Settings on the SAME
+ * device that generated/imported it.
+ *
+ * This is convenience persistence, NOT a recovery mechanism — a keystore death
+ * wipes it alongside the keys, exactly like the private key itself. The user's
+ * written-down phrase remains the sole out-of-band recovery path. The mnemonic
+ * lives ONLY in this slot: it is never mirrored into the identity marker,
+ * {@link KeyManager.getIdentityStatus}, logs, or any exported bundle.
+ */
+const RECOVERY_MNEMONIC_KEYCHAIN_SERVICE = 'oxy_identity_mnemonic';
+const RECOVERY_MNEMONIC_STORAGE_KEY = 'oxy_identity_mnemonic_v1';
+
 /**
  * Advisory AsyncStorage fast-path flag: set once the v2 slots own the identity.
  * Re-derivable (its loss just re-runs the cheap slot check), so it lives in
@@ -1773,6 +1792,81 @@ export class KeyManager {
     }
   }
 
+  /**
+   * Persist the recovery mnemonic (the 12-word phrase) into its dedicated,
+   * device-only keychain slot so the user can re-reveal it from Settings after
+   * onboarding.
+   *
+   * Called best-effort at identity creation/import, where the phrase is already
+   * in memory: a failure to persist it must NEVER fail the identity itself, so
+   * callers deliberately swallow the thrown error (logging it). Storage errors
+   * throw {@link IdentityUnavailableError} — same "cannot determine" semantics as
+   * the other getters — so a caller MAY observe/log the failure.
+   *
+   * The mnemonic is stored ONLY here — never in the marker, `getIdentityStatus`,
+   * logs, or any exported bundle.
+   */
+  static async storeRecoveryMnemonic(mnemonic: string): Promise<void> {
+    if (isWebPlatform()) {
+      return; // Identity storage is only available on native platforms
+    }
+    try {
+      const store = await initSecureStore();
+      await store.setItemAsync(
+        RECOVERY_MNEMONIC_STORAGE_KEY,
+        mnemonic,
+        KeyManager._privateWriteOpts(store, RECOVERY_MNEMONIC_KEYCHAIN_SERVICE),
+      );
+    } catch (error) {
+      if (isDev()) {
+        logger.warn('Failed to persist recovery mnemonic', { component: 'KeyManager' }, error);
+      }
+      throw new IdentityUnavailableError('Failed to persist recovery mnemonic.', error);
+    }
+  }
+
+  /**
+   * Read the stored recovery mnemonic for re-reveal in Settings.
+   *
+   * Returns the phrase, or `null` when a read SUCCEEDS and finds none — the
+   * expected result for any identity created/imported before this feature
+   * existed, since the phrase was never captured for those. THROWS
+   * {@link IdentityUnavailableError} when storage is unreadable (keychain locked
+   * / module load failure), matching {@link getPublicKey}'s contract — a thrown
+   * read is never flattened to `null`, so a caller distinguishes "phrase was
+   * never stored" from "keychain temporarily locked, retry".
+   */
+  static async getRecoveryMnemonic(): Promise<string | null> {
+    if (isWebPlatform()) {
+      return null; // Identity storage is only available on native platforms
+    }
+    try {
+      const store = await initSecureStore();
+      return await store.getItemAsync(
+        RECOVERY_MNEMONIC_STORAGE_KEY,
+        KeyManager._slotOpts(RECOVERY_MNEMONIC_KEYCHAIN_SERVICE),
+      );
+    } catch (error) {
+      if (isDev()) {
+        logger.warn('Failed to read recovery mnemonic', { component: 'KeyManager' }, error);
+      }
+      throw new IdentityUnavailableError('Failed to read recovery mnemonic from secure storage.', error);
+    }
+  }
+
+  /**
+   * Delete the stored recovery mnemonic. Best-effort: a delete failure is logged
+   * and swallowed, never thrown — it runs inside the identity-deletion path where
+   * an unreadable keychain must not abort the wider teardown.
+   */
+  static async deleteRecoveryMnemonic(): Promise<void> {
+    if (isWebPlatform()) {
+      return; // Identity storage is only available on native platforms
+    }
+    const store = await initSecureStore();
+    await KeyManager._bestEffortDelete(store, RECOVERY_MNEMONIC_STORAGE_KEY, RECOVERY_MNEMONIC_KEYCHAIN_SERVICE);
+  }
+
   /**
    * Check if a complete, parseable identity exists on this device.
    *
@@ -2016,6 +2110,11 @@ export class KeyManager {
     await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PRIVATE_KEY);
     await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PUBLIC_KEY);
 
+    // Always drop the stored recovery mnemonic — it is scoped to the identity
+    // being deleted, so a leftover would let Settings reveal a stale phrase for
+    // an identity that no longer exists (or a DIFFERENT one after re-onboarding).
+    await KeyManager.deleteRecoveryMnemonic();
+
     // Also clear backups + the shared slot on force deletion, so a deleted
     // identity cannot be resurrected from any recovery source.
     if (force) {

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 {

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;
 }
 

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__/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;
+}