@oxyhq/core 12.6.0 → 12.8.0

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

@@ -321,6 +321,26 @@ export declare class KeyManager {
      * "not-hex" pass through as a valid (but compromised, near-zero) key.
      */
     static isValidPrivateKey(privateKey: string): boolean;
+    /**
+     * Derive a 32-byte, domain-separated seed from the on-device Oxy identity
+     * private key via HKDF-SHA256, WITHOUT ever exposing the raw private key.
+     *
+     * The domain separation is carried by `info` (e.g. `"oxypay/faircoin/v1"`),
+     * so distinct apps/purposes get independent seeds from the same identity.
+     * The output is HKDF keying material, never the private key itself — a
+     * consumer (e.g. Oxy Pay's FairCoin HD wallet) can feed it straight into
+     * `HDKey.fromMasterSeed` and never touches the identity key.
+     *
+     * Key source (native only): prefers the shared ecosystem identity written to
+     * `group.so.oxy.shared` (what a Relying Party like Oxy Pay reads), then falls
+     * back to this device's primary identity (Commons/Accounts). Both reproduce
+     * from the user's Oxy recovery phrase, so the derived seed is recoverable.
+     *
+     * @param info Context/domain-binding label (distinct labels → independent seeds).
+     * @returns 32 bytes of derived keying material, or `null` on web / when no
+     *          identity key is available on this device.
+     */
+    static deriveScopedSeed(info: string): Promise<Uint8Array | null>;
     /**
      * Get a shortened version of the public key for display
      * Format: first 8 chars...last 8 chars

package/dist/types/index.d.ts

@@ -26,6 +26,7 @@ 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';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
+export type { InitDeviceTransferResult, DeviceTransferOutcome, } from './mixins/OxyServices.deviceTransfer';
 export type { BulkFollowEntry, BulkFollowResult, BulkUnfollowEntry, BulkUnfollowResult, FollowMutationResult, ViewerGraph, } from './mixins/OxyServices.user';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';

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

@@ -0,0 +1,149 @@
+/**
+ * Device-to-device Identity Transfer Mixin (b3 Feature 2 — "add a device")
+ *
+ * Clones an existing device's secp256k1 identity onto a fresh device over a
+ * short-lived, unauthenticated relay, WITHOUT the server ever holding a
+ * decryption key. Both devices end up holding the SAME private key.
+ *
+ * The two devices agree on a symmetric key via an ephemeral secp256k1 ECDH
+ * handshake (Phase-0 crypto): `deriveSharedSecret` → `hkdfSha256` → a per-pairing
+ * transfer key, used with `encryptAead`/`decryptAead` (XChaCha20-Poly1305) to
+ * seal `{ privateKey, publicKey }`. The relay carries only ephemeral public keys
+ * plus opaque ciphertext — a passive/at-rest-compromised backend cannot decrypt.
+ *
+ * Roles:
+ *  - NEW device (no identity): {@link initDeviceTransfer} (generate ephemeral
+ *    pair, register the pairing, render `pairingId` as a QR) then
+ *    {@link subscribeDeviceTransfer} (await approval over the `/device-pair`
+ *    socket with a poll fallback, decrypt, and import the key).
+ *  - OLD device (has identity): {@link getDeviceTransferInfo} (resolve the
+ *    scanned `pairingId` server-side — the QR is NOT self-contained) then
+ *    {@link approveDeviceTransfer} (biometric-gate in the UI, seal the key
+ *    material, and post it with a fresh signature over the CURRENT identity key).
+ *
+ * SECURITY: E2E against a passive relay only. Explicitly NOT hardened against an
+ * actively-malicious backend MITM'ing the ephemeral keys (same trust boundary as
+ * the existing QR sign-in; SAS compare deferred per owner decision). Approve
+ * requires BOTH a bearer token AND a fresh identity-key signature.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import type { DeviceTransferInfoResponse, DeviceTransferApproveResponse, DeviceTransferDenyResponse } from '@oxyhq/contracts';
+/** Result of {@link OxyServicesDeviceTransferMixin.initDeviceTransfer}. */
+export interface InitDeviceTransferResult {
+    /** 128-bit single-use handle to render in the QR (also the HKDF salt). */
+    pairingId: string;
+    /** ISO-8601 expiry (3 minutes). */
+    expiresAt: string;
+    /** The new device's ephemeral public key registered with the relay. */
+    newEphemeralPublicKey: string;
+}
+/** Terminal outcome delivered to {@link subscribeDeviceTransfer}'s callback. */
+export type DeviceTransferOutcome = {
+    status: 'approved';
+    publicKey: string;
+} | {
+    status: 'denied';
+} | {
+    status: 'expired';
+};
+export declare function OxyServicesDeviceTransferMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * NEW device — begin an "add a device" transfer. Generates a single-use
+         * ephemeral secp256k1 pair, registers the pairing, and returns the
+         * `pairingId` to render as a QR. The ephemeral private key is held in memory
+         * (keyed by `pairingId`) for the subsequent {@link subscribeDeviceTransfer}.
+         *
+         * @param label - Optional human-readable label for this new device.
+         */
+        initDeviceTransfer(label?: string): Promise<InitDeviceTransferResult>;
+        /**
+         * Resolve a pairing server-side (the QR carries only `pairingId`). The OLD
+         * device calls this after scanning to read the new device's ephemeral public
+         * key + label; the NEW device polls it to fetch the sealed material once
+         * approved. Public — no auth required.
+         */
+        getDeviceTransferInfo(pairingId: string): Promise<DeviceTransferInfoResponse>;
+        /**
+         * OLD device — approve a scanned transfer. Reads the new device's ephemeral
+         * public key, derives the shared transfer key, AEAD-seals
+         * `{ privateKey, publicKey }`, and posts it PLUS a fresh signature over
+         * `{ action:'approve_device_transfer', pairingId, timestamp }` made with the
+         * CURRENT identity key (dual-proof alongside the bearer token).
+         *
+         * NATIVE-ONLY: requires a stored identity (throws otherwise). The UI must
+         * biometric-gate before calling this — a key clone leaves the device.
+         */
+        approveDeviceTransfer(pairingId: string): Promise<DeviceTransferApproveResponse>;
+        /**
+         * OLD device — deny (cancel) a scanned transfer so the waiting new device
+         * stops. Public — no auth required.
+         */
+        denyDeviceTransfer(pairingId: string): Promise<DeviceTransferDenyResponse>;
+        /**
+         * NEW device — await approval for a pairing started with
+         * {@link initDeviceTransfer}, then decrypt and import the transferred
+         * identity key. Primary path is an instant `device_pair_update` push over the
+         * `/device-pair` socket; a poll backstops a socket that can't connect.
+         *
+         * On `approved`: re-derives the shared transfer key from the old device's
+         * ephemeral public key, decrypts `{ privateKey, publicKey }`, imports it via
+         * `KeyManager.importKeyPair(privateKey, { overwrite: false })`, and invokes
+         * `onOutcome({ status:'approved', publicKey })`. The caller then runs the
+         * NORMAL challenge/verify sign-in — this method does not mint a session.
+         *
+         * @returns An unsubscribe function; call it to stop waiting (also called
+         *   automatically once the transfer settles).
+         */
+        subscribeDeviceTransfer(pairingId: string, onOutcome: (outcome: DeviceTransferOutcome) => void): () => void;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

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

@@ -1,5 +1,6 @@
 import type { ApiError, User } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
+import { type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 /**
  * Result from the service-acting-as verification endpoint.
  * Confirms that a given service app holds an active delegation grant for
@@ -28,6 +29,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;
 }
 /**
  * Options for oxyClient.auth() middleware

package/dist/types/mixins/index.d.ts

@@ -29,6 +29,7 @@ import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
+import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
  * `composeOxyServices()` produces a class whose instances expose all of
@@ -38,7 +39,7 @@ import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/dist/types/server/auth.d.ts

@@ -1,5 +1,8 @@
 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;
     _id?: string;
@@ -13,6 +16,7 @@ export interface OxyServiceAppContext {
     appName: string;
     scopes: string[];
     credentialId: string;
+    environment: OxyServiceEnvironment;
 }
 export interface OxyServiceActingAsContext {
     userId: string;

package/dist/types/server/index.d.ts

@@ -14,8 +14,8 @@
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * ```
  */
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, } from './auth';
-export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, } from './auth';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
+export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';
 export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch';

package/dist/types/utils/oxyServiceEnvironment.d.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 declare const OXY_SERVICE_ENVIRONMENTS: readonly ["development", "staging", "production"];
+export type OxyServiceEnvironment = (typeof OXY_SERVICE_ENVIRONMENTS)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.6.0",
+  "version": "12.8.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__/scopedSeed.test.ts

@@ -0,0 +1,126 @@
+import { setPlatformOS } from '../../utils/platform';
+
+jest.mock(
+  'expo-secure-store',
+  () => {
+    const store = new Map<string, string>();
+    return {
+      __esModule: true,
+      WHEN_UNLOCKED_THIS_DEVICE_ONLY: 'WHEN_UNLOCKED_THIS_DEVICE_ONLY',
+      WHEN_UNLOCKED: 'WHEN_UNLOCKED',
+      setItemAsync: jest.fn(async (k: string, v: string) => { store.set(k, v); }),
+      getItemAsync: jest.fn(async (k: string) => store.get(k) ?? null),
+      deleteItemAsync: jest.fn(async (k: string) => { store.delete(k); }),
+      __resetStore__: () => store.clear(),
+    };
+  },
+  { 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', () => ({
+  __esModule: true,
+  ...jest.requireActual('@oxyhq/protocol'),
+  loadExpoCrypto: async () => require('expo-crypto'),
+  loadSecureStore: async () => require('expo-secure-store'),
+  loadNodeCrypto: async () => require('crypto'),
+  loadSharedIdentityBridge: async () => null,
+}));
+
+const FIXED_PRIV = 'aa'.repeat(32);
+const EXPECTED_FAIR = '4b90d900a11b0a1737ed643db3446e5f28035d86f1a4fda92474ea8ab152adf5';
+const EXPECTED_OTHER = 'cdedf1f076b0f4766c769e55bc1e90c5bf44d8630f6e5fb147615ee7c330c905';
+const toHex = (b: Uint8Array): string => Buffer.from(b).toString('hex');
+
+describe('KeyManager.deriveScopedSeed', () => {
+  let KeyManager: typeof import('../keyManager').KeyManager;
+
+  beforeEach(async () => {
+    jest.resetModules();
+    setPlatformOS('ios');
+    const secureStore = (await import('expo-secure-store' as string)) as unknown as {
+      __resetStore__: () => void;
+    };
+    secureStore.__resetStore__();
+    const km = await import('../keyManager');
+    KeyManager = km.KeyManager;
+    // Store a known shared identity key so derivation is deterministic.
+    await KeyManager.importSharedIdentity(FIXED_PRIV);
+  });
+
+  it('derives the pinned 32-byte seed for a fixed identity + info', async () => {
+    const seed = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    if (!seed) throw new Error('expected a seed');
+    expect(seed).toHaveLength(32);
+    expect(toHex(seed)).toBe(EXPECTED_FAIR);
+  });
+
+  it('is deterministic (same identity + info → identical seed)', async () => {
+    const a = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    const b = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    if (!a || !b) throw new Error('expected seeds');
+    expect(toHex(a)).toBe(toHex(b));
+  });
+
+  it('domain-separates by info (different info → different seed)', async () => {
+    const fair = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    const other = await KeyManager.deriveScopedSeed('oxypay/other/v1');
+    if (!fair || !other) throw new Error('expected seeds');
+    expect(toHex(other)).toBe(EXPECTED_OTHER);
+    expect(toHex(fair)).not.toBe(toHex(other));
+  });
+
+  it('never returns the raw private key (no leak)', async () => {
+    const seed = await KeyManager.deriveScopedSeed('oxypay/faircoin/v1');
+    if (!seed) throw new Error('expected a seed');
+    expect(toHex(seed)).not.toBe(FIXED_PRIV);
+  });
+
+  it('returns null on web (no identity key available)', async () => {
+    // `jest.resetModules()` gives KeyManager its own bound instance of
+    // `utils/platform` (its cached OS locks in as soon as `beforeEach`'s
+    // `importSharedIdentity` first checks it). The file-level `setPlatformOS`
+    // import above is bound to a different, earlier instance, so mutating it
+    // here would not be observed by the already-imported `KeyManager`. Reset
+    // again and re-import both from the same fresh module graph so the
+    // platform flip actually reaches the KeyManager instance under test.
+    //
+    // `jest.resetModules()` also re-runs the virtual `expo-secure-store`
+    // mock factory, handing this fresh KeyManager a brand-new empty
+    // in-memory store — the identity `beforeEach` imported lives only in the
+    // pre-reset store instance. Without re-storing an identity here, a
+    // `null` result would be ambiguous between the web gate and the
+    // no-identity fallback. Re-import the identity on THIS fresh instance
+    // (while still native — `importSharedIdentity` itself is native-gated
+    // and throws on web) BEFORE flipping to web, so the later `null` can
+    // only be explained by the web gate, not a missing identity.
+    jest.resetModules();
+    const platform = await import('../../utils/platform');
+    const km = await import('../keyManager');
+    await km.KeyManager.importSharedIdentity(FIXED_PRIV);
+    platform.setPlatformOS('web');
+    expect(await km.KeyManager.deriveScopedSeed('oxypay/faircoin/v1')).toBeNull();
+  });
+
+  it('returns null when no identity exists on the device', async () => {
+    const secureStore = (await import('expo-secure-store' as string)) as unknown as {
+      __resetStore__: () => void;
+    };
+    secureStore.__resetStore__();
+    expect(await KeyManager.deriveScopedSeed('oxypay/faircoin/v1')).toBeNull();
+  });
+});

package/src/crypto/keyManager.ts

@@ -10,6 +10,7 @@ import type { ECKeyPair } from 'elliptic';
 import { isWeb, isIOS, isAndroid } from '../utils/platform';
 import { type ExpoCryptoLike, type ExpoSecureStoreLike, isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore, loadSharedIdentityBridge } from '@oxyhq/protocol';
 import { isDev, logger } from '../logger';
+import { hkdfSha256 } from './kdf';
 
 /**
  * Options for expo-secure-store calls made by KeyManager.
@@ -79,6 +80,28 @@ export class IdentityPersistError extends Error {
 
 const ec = new EC('secp256k1');
 
+/**
+ * HKDF salt that domain-separates every identity-scoped seed produced by
+ * {@link KeyManager.deriveScopedSeed}. Versioned so a future scheme change is a
+ * new, non-colliding tag. The per-app domain (e.g. Oxy Pay's FairCoin wallet)
+ * is carried by the caller's `info` string, not this salt.
+ */
+const SCOPED_SEED_KDF_SALT = 'oxy-identity-scoped-seed-v1';
+
+/** UTF-8 encode an ASCII label to bytes (HKDF salt/info). */
+function utf8ToBytes(label: string): Uint8Array {
+  return new TextEncoder().encode(label);
+}
+
+/** Decode a hex string to bytes. Inverse of {@link uint8ArrayToHex}. */
+function hexToBytes(hex: string): Uint8Array {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
 const STORAGE_KEYS = {
   PRIVATE_KEY: 'oxy_identity_private_key',
   PUBLIC_KEY: 'oxy_identity_public_key',
@@ -1559,6 +1582,38 @@ export class KeyManager {
     }
   }
 
+  /**
+   * Derive a 32-byte, domain-separated seed from the on-device Oxy identity
+   * private key via HKDF-SHA256, WITHOUT ever exposing the raw private key.
+   *
+   * The domain separation is carried by `info` (e.g. `"oxypay/faircoin/v1"`),
+   * so distinct apps/purposes get independent seeds from the same identity.
+   * The output is HKDF keying material, never the private key itself — a
+   * consumer (e.g. Oxy Pay's FairCoin HD wallet) can feed it straight into
+   * `HDKey.fromMasterSeed` and never touches the identity key.
+   *
+   * Key source (native only): prefers the shared ecosystem identity written to
+   * `group.so.oxy.shared` (what a Relying Party like Oxy Pay reads), then falls
+   * back to this device's primary identity (Commons/Accounts). Both reproduce
+   * from the user's Oxy recovery phrase, so the derived seed is recoverable.
+   *
+   * @param info Context/domain-binding label (distinct labels → independent seeds).
+   * @returns 32 bytes of derived keying material, or `null` on web / when no
+   *          identity key is available on this device.
+   */
+  static async deriveScopedSeed(info: string): Promise<Uint8Array | null> {
+    if (isWebPlatform()) {
+      return null;
+    }
+    const privateKey =
+      (await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey());
+    if (!privateKey) {
+      return null;
+    }
+    const ikm = hexToBytes(KeyManager.canonicalPrivateKey(privateKey));
+    return hkdfSha256(ikm, utf8ToBytes(SCOPED_SEED_KDF_SALT), utf8ToBytes(info), 32);
+  }
+
   /**
    * Get a shortened version of the public key for display
    * Format: first 8 chars...last 8 chars

package/src/i18n/locales/en-US.json

@@ -1449,6 +1449,13 @@
       "emptyTitle": "No photos yet",
       "emptySubtitle": "Upload from your device to get started"
     },
+    "details": {
+      "title": "File Details",
+      "download": "Download",
+      "type": "Type",
+      "uploaded": "Uploaded",
+      "description": "Description"
+    },
     "a11y": {
       "viewAll": "Show all files",
       "viewPhotos": "Show photos only",

package/src/i18n/locales/es-ES.json

@@ -1449,6 +1449,13 @@
       "emptyTitle": "Aún no hay fotos",
       "emptySubtitle": "Sube desde tu dispositivo para empezar"
     },
+    "details": {
+      "title": "Detalles del archivo",
+      "download": "Descargar",
+      "type": "Tipo",
+      "uploaded": "Subido",
+      "description": "Descripción"
+    },
     "a11y": {
       "viewAll": "Mostrar todos los archivos",
       "viewPhotos": "Mostrar solo fotos",

package/src/index.ts

@@ -48,6 +48,10 @@ export type {
     ContactDiscoveryMatch,
     ContactDiscoveryResponse,
 } from './mixins/OxyServices.contacts';
+export type {
+    InitDeviceTransferResult,
+    DeviceTransferOutcome,
+} from './mixins/OxyServices.deviceTransfer';
 export type {
     BulkFollowEntry,
     BulkFollowResult,