@oxyhq/core 12.2.1 → 12.4.0

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

@@ -0,0 +1,56 @@
+/**
+ * Authenticated Encryption with Associated Data (XChaCha20-Poly1305)
+ *
+ * Pure-JS/TS AEAD via `@noble/ciphers` — identical behaviour on web, Node, and
+ * React Native with zero WebCrypto / native-module dependency. This replaces
+ * the `crypto.subtle`-based path (unreliable on React Native) for the Commons
+ * encrypted backup and device-to-device transfer flows.
+ *
+ * XChaCha20-Poly1305 is chosen over AES-GCM specifically for its 24-byte
+ * (192-bit) random nonce: the nonce space is large enough that random nonces
+ * never collide in practice, so callers do not need to maintain a per-key
+ * counter. The 16-byte Poly1305 tag is appended to the ciphertext by the
+ * underlying library and validated on decrypt.
+ *
+ * The optional Associated Data (AAD) is authenticated but NOT encrypted: it
+ * binds the ciphertext to its context (e.g. a backup version, a device id, a
+ * DID). Decryption fails if the key, nonce, ciphertext, OR aad differ from
+ * those used at encryption time.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+import './polyfill';
+/** Key length for XChaCha20-Poly1305, in bytes (256-bit). */
+export declare const AEAD_KEY_LENGTH = 32;
+/** Nonce length for XChaCha20-Poly1305, in bytes (192-bit). */
+export declare const AEAD_NONCE_LENGTH = 24;
+/** Ciphertext (Poly1305 tag appended) plus the random nonce used to produce it. */
+export interface AeadResult {
+    /** The 24-byte random nonce. Store/transmit alongside the ciphertext. */
+    nonce: Uint8Array;
+    /** Ciphertext with the 16-byte Poly1305 authentication tag appended. */
+    ciphertext: Uint8Array;
+}
+/**
+ * Encrypt `plaintext` under `key` with a fresh random nonce, authenticating the
+ * optional `aad`.
+ *
+ * @param key       32-byte symmetric key (e.g. from `hkdfSha256`).
+ * @param plaintext Bytes to encrypt.
+ * @param aad       Optional associated data authenticated but not encrypted.
+ * @returns         `{ nonce, ciphertext }` — both are required to decrypt.
+ */
+export declare function encryptAead(key: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): AeadResult;
+/**
+ * Decrypt and authenticate `ciphertext` produced by {@link encryptAead}.
+ *
+ * Throws if the key, nonce, ciphertext, or aad differ from those used at
+ * encryption time (tamper detection), or if the tag is invalid.
+ *
+ * @param key        32-byte symmetric key.
+ * @param nonce      The 24-byte nonce returned by `encryptAead`.
+ * @param ciphertext Ciphertext with the appended Poly1305 tag.
+ * @param aad        The same associated data supplied at encryption time.
+ * @returns          The recovered plaintext bytes.
+ */
+export declare function decryptAead(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;

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

@@ -0,0 +1,29 @@
+/**
+ * ECDH shared-secret derivation (secp256k1)
+ *
+ * Derives a raw 32-byte ECDH shared secret from a local private key and a
+ * remote public key, using the SAME `elliptic` `EC('secp256k1')` primitive the
+ * rest of core's identity layer uses (`keyManager.ts`). This is the key-exchange
+ * step for the Commons device-to-device transfer flow: each side computes the
+ * same shared secret, which is then run through `hkdfSha256` to derive the
+ * symmetric key handed to `encryptAead` / `decryptAead`.
+ *
+ * The returned value is the raw x-coordinate of the ECDH point, big-endian,
+ * zero-padded to 32 bytes. It is NOT itself a symmetric key — always pass it
+ * through a KDF (HKDF) with a context-binding `info` before use.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+/**
+ * Compute the ECDH shared secret between a local private key and a remote
+ * public key on secp256k1.
+ *
+ * Symmetric by construction:
+ * `deriveSharedSecret(privA, pubB) === deriveSharedSecret(privB, pubA)`.
+ *
+ * @param privateKeyHex     Local private key, hex (up to 64 chars; canonicalized).
+ * @param otherPublicKeyHex Remote public key, hex — compressed (`02`/`03` + 32
+ *                          bytes) or uncompressed (`04` + 64 bytes).
+ * @returns                 The 32-byte big-endian shared secret.
+ */
+export declare function deriveSharedSecret(privateKeyHex: string, otherPublicKeyHex: string): Uint8Array;

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

@@ -0,0 +1,25 @@
+/**
+ * Key Derivation Function (HKDF-SHA256)
+ *
+ * Pure-JS/TS HKDF via `@noble/hashes` — identical behaviour on web, Node, and
+ * React Native with zero WebCrypto / native-module dependency. Used to derive
+ * fixed-length symmetric keys from higher-entropy input keying material (an
+ * ECDH shared secret, a recovery-phrase seed, etc.) for the Commons encrypted
+ * backup and device-to-device transfer flows.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+/**
+ * Derive `length` bytes of keying material from `ikm` using HKDF-SHA256
+ * (RFC 5869 — extract-then-expand).
+ *
+ * @param ikm    Input keying material (the raw secret; NOT necessarily uniform).
+ * @param salt   Non-secret random salt. An empty array is treated by HKDF as a
+ *               zero-filled salt of the hash length — pass a real salt whenever
+ *               one is available so derivations for different contexts diverge.
+ * @param info   Context/application-binding string ("what is this key for").
+ *               Distinct `info` values yield independent keys from the same ikm.
+ * @param length Number of output bytes. Must be in (0, 255 * 32].
+ * @returns      Exactly `length` bytes of derived keying material.
+ */
+export declare function hkdfSha256(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array, length: number): Uint8Array;

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

@@ -299,6 +299,11 @@ export declare class KeyManager {
      * Derive public key from a private key (without storing)
      */
     static derivePublicKey(privateKey: string): string;
+    /**
+     * Normalize a public key to uncompressed, lowercased hex. Used when building
+     * signed rotation payloads so legacy compressed/cased encodings still verify.
+     */
+    static canonicalPublicKey(publicKey: string): string;
     /**
      * Validate that a string is a valid public key
      *

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

@@ -6,11 +6,55 @@
  *
  * Note: This module requires the polyfill to be loaded first (done via crypto/index.ts)
  */
+/**
+ * HKDF context tag for the encrypted-backup key schedule (b3 Feature 1). Used as
+ * the HKDF `salt`; distinct from any other Oxy key-derivation salt so the backup
+ * key schedule is independent. Versioned so a future scheme change is a new tag.
+ */
+export declare const BACKUP_KDF_SALT = "oxy-identity-backup-v1";
+/** HKDF `info` label that derives the symmetric AEAD key from the seed. */
+export declare const BACKUP_KDF_ENCRYPTION_INFO = "oxy-backup-encryption-key";
+/** HKDF `info` label that derives the (server-hashed) backup locator from the seed. */
+export declare const BACKUP_KDF_LOOKUP_INFO = "oxy-backup-lookup-id";
+/** Byte length of both the derived backup key and the derived lookup id (256-bit). */
+export declare const BACKUP_MATERIAL_LENGTH = 32;
+/**
+ * The two pieces of key material derived from a recovery phrase for the
+ * encrypted off-device backup, kept strictly separate by HKDF domain separation.
+ */
+export interface BackupMaterial {
+    /**
+     * The 32-byte symmetric key handed to `encryptAead`/`decryptAead`. NEVER
+     * leaves the device — the server sees only ciphertext produced with it.
+     */
+    backupKey: Uint8Array;
+    /**
+     * The 256-bit backup locator, hex. Sent to the server, which stores ONLY
+     * `sha256(lookupId)` — so possession of this value (which itself requires the
+     * full seed to compute) is what locates a backup, and the server can never
+     * recompute it from what it stores.
+     */
+    lookupId: string;
+}
 export interface RecoveryPhraseResult {
     phrase: string;
     words: string[];
     publicKey: string;
 }
+/**
+ * A freshly-derived identity that has NOT been persisted to secure storage.
+ *
+ * Unlike {@link RecoveryPhraseResult} this also exposes the `privateKey`, because
+ * the caller must be able to sign with (or later persist) the material itself —
+ * the whole point of a "pending" identity is that nothing is committed until an
+ * external step (e.g. a server-confirmed key rotation) succeeds.
+ */
+export interface PendingIdentityResult {
+    phrase: string;
+    words: string[];
+    privateKey: string;
+    publicKey: string;
+}
 export interface GenerateIdentityOptions {
     /**
      * Pass `true` to allow overwriting an existing on-device identity.
@@ -40,6 +84,47 @@ export declare class RecoveryPhraseService {
      * Same overwrite-protection semantics as `generateIdentityWithRecovery`.
      */
     static generateIdentityWithRecovery24(options?: GenerateIdentityOptions): Promise<RecoveryPhraseResult>;
+    /**
+     * Derive a brand-new identity + recovery phrase WITHOUT persisting anything.
+     *
+     * Pure: same derivation as {@link generateIdentityWithRecovery} (128-bit
+     * mnemonic → seed → first 32 bytes as the secp256k1 private key) but it stops
+     * BEFORE `KeyManager.importKeyPair`, so no on-device identity is touched. The
+     * caller decides if/when to commit the material (e.g. only after a server
+     * confirms a key rotation). Works on web too — it never reads or writes secure
+     * storage.
+     *
+     * The 12-word `phrase` MUST be shown to the user before the identity is
+     * committed anywhere — if it is lost the account becomes unrecoverable.
+     */
+    static derivePendingIdentity(): Promise<PendingIdentityResult>;
+    /**
+     * Derive the private key from a recovery phrase WITHOUT storing it.
+     *
+     * The private-key counterpart of {@link derivePublicKeyFromPhrase}. Used to
+     * re-derive a key in memory (e.g. to sign a rotation proof with the current
+     * key when the device has no SecureStore copy). Never persists — the returned
+     * material lives only in the caller's memory.
+     */
+    static derivePrivateKeyFromPhrase(phrase: string): Promise<string>;
+    /**
+     * Derive the encrypted-backup key material from a recovery phrase (b3 Feature
+     * 1). PURE and additive — it does NOT touch the frozen phrase→privateKey
+     * derivation ({@link derivePrivateKeyFromPhrase} slices the first 32 seed
+     * bytes) and never reads or writes secure storage.
+     *
+     * Both outputs are derived from the FULL 64-byte BIP-39 seed via HKDF-SHA256
+     * with domain-separated `info` labels, so the domain separation is real: a
+     * device compromise that leaks only the raw 32-byte private key can compute
+     * NEITHER the backup key nor the lookup id (both need the whole seed). Locating
+     * AND decrypting a backup therefore requires the recovery phrase.
+     *
+     * @param phrase - The BIP-39 recovery phrase (validated + normalized here).
+     * @returns `{ backupKey, lookupId }` — the AEAD key (kept local) and the hex
+     *   locator (uploaded; server stores only its hash).
+     * @throws if the phrase is not a valid BIP-39 mnemonic.
+     */
+    static deriveBackupMaterial(phrase: string): Promise<BackupMaterial>;
     /**
      * Restore an identity from a recovery phrase.
      *

package/dist/types/index.d.ts

@@ -26,7 +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 { BulkFollowEntry, BulkFollowResult, BulkUnfollowEntry, BulkUnfollowResult, ViewerGraph, } from './mixins/OxyServices.user';
+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';
 export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHandle';
@@ -38,7 +38,7 @@ export type { AccountKind, OrganizationCategory, AccountRelationship, AccountRol
 export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
 export type { ReputationCategory, TrustTier, ReputationTransactionStatus, ReputationTargetEntityType, ReputationDisputeStatus, ReputationInfluenceContext, ReputationTransaction, ReputationBalanceBreakdown, ReputationInfluence, ReputationReliability, ReputationBalance, ReputationDispute, ReputationRule, ReputationLeaderboardEntry, ReputationInfluenceResult, ReverseReputationTransactionResult, AwardReputationInput, CreateReputationDisputeInput, ResolveReputationDisputeInput, UpsertReputationRuleInput, ReverseReputationTransactionInput, } from './mixins/OxyServices.reputation';
 export { buildUserDid } from './mixins/OxyServices.identity';
-export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, } from './mixins/OxyServices.identity';
+export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './mixins/OxyServices.identity';
 export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation, } from './mixins/OxyServices.civic';
 export type { CivicCardResult, IdCardRef, AttestQrPayload, ParsedAttestPayload, SubmitRealLifeAttestationInput, DenyValidationResult, VouchForPersonInput, WithdrawVouchResult, IssueCredentialInput, RevokeCredentialResult, } from './mixins/OxyServices.civic';
 export type { UserNodeStatus, UserNodeMode, UserNodeController, UserNodeLivenessStatus, RegisterNodeInput, RemoveNodeResult } from './mixins/OxyServices.nodes';
@@ -51,7 +51,11 @@ export type { KeyPair } from './crypto/keyManager';
 export { SignatureService } from './crypto/signatureService';
 export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';
-export type { RecoveryPhraseResult } from './crypto/recoveryPhrase';
+export type { RecoveryPhraseResult, PendingIdentityResult, BackupMaterial } from './crypto/recoveryPhrase';
+export { hkdfSha256 } from './crypto/kdf';
+export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH, } from './crypto/aead';
+export type { AeadResult } from './crypto/aead';
+export { deriveSharedSecret } from './crypto/ecdh';
 export { DeviceManager } from './utils/deviceManager';
 export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager';
 export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceLinkedSession, DeviceLinkedSessionsResponse, DeviceLinkedSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
@@ -73,7 +77,7 @@ export { buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } fr
 export type { PaginationParams, ApiResponse, ErrorResponse, } from './utils/apiUtils';
 export { ErrorCodes, createApiError, handleHttpError, validateRequiredFields, } from './utils/errorUtils';
 export { retryAsync } from './utils/asyncUtils';
-export { EMAIL_REGEX, USERNAME_REGEX, PASSWORD_REGEX, isValidEmail, isValidUsername, isValidPassword, isValidDisplayName, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils';
+export { EMAIL_REGEX, USERNAME_REGEX, PASSWORD_REGEX, isValidEmail, isValidUsername, isValidPassword, isValidDisplayName, DISPLAY_NAME_ALLOWED_SCRIPTS, DISPLAY_NAME_DISALLOWED_SOURCE, DISPLAY_NAME_ORPHANED_MARK_SOURCE, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils';
 export { normalizeInlineText, normalizeMultilineText, } from './utils/textNormalization';
 export { logger, createLogger, configureLogger, getLoggerConfig, resetLoggerConfig, consoleSink, isDev, } from './logger';
 export type { Logger, LogLevel, EmittableLogLevel, LogContext, LogEntry, LogSink, LoggerConfig, } from './logger';

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

@@ -25,6 +25,7 @@
  */
 import type { AuthMethodsResponse, DidDocument, DomainVerificationInstructions, ExportBundle, OxySignedRecordType, SignedRecordEnvelope, VerifiedDomain } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
+import { type PendingIdentityResult } from '../crypto/recoveryPhrase';
 /**
  * Record categories a client may sign and publish to the Oxy store. The base
  * envelope `type` is now an open string (any app may define its own records on
@@ -67,6 +68,54 @@ export interface VerifyDomainResult {
 export interface RemoveDomainResult {
     success: boolean;
 }
+/** How the caller proves control of the CURRENT key during a key rotation. */
+export type RotateKeyProof = 'device' | 'phrase';
+/** Options for {@link OxyServicesIdentityMixin.rotateKey}. */
+export interface RotateKeyOptions {
+    /**
+     * How to prove control of the CURRENT key:
+     *  - `'device'`: sign with the on-device SecureStore key (native-only).
+     *  - `'phrase'`: re-derive the current key from the entered recovery `phrase`
+     *    and sign with it. This works even when the device holds NO SecureStore
+     *    copy of the key — it is how the LAST remaining credential is replaced.
+     */
+    proof: RotateKeyProof;
+    /** The CURRENT identity's recovery phrase. Required when `proof: 'phrase'`. */
+    phrase?: string;
+    /**
+     * When true, all OTHER active sessions are revoked after a successful
+     * rotation (the rotating device stays signed in). Use it when the old key is
+     * presumed compromised.
+     */
+    signOutEverywhere?: boolean;
+    /**
+     * A pre-derived NEW identity to rotate to (from
+     * {@link RecoveryPhraseService.derivePendingIdentity}). Pass it when the UI
+     * derived + SHOWED the new phrase to the user BEFORE committing, so the SAME
+     * identity is the one rotated in. When omitted, a fresh identity is derived
+     * internally and its phrase is returned in the result.
+     */
+    pendingIdentity?: PendingIdentityResult;
+}
+/** Result of a successful key rotation. */
+export interface RotateKeyResult {
+    /** The account's new (rotated) public key. */
+    newPublicKey: string;
+    /**
+     * The NEW identity's recovery phrase. It MUST be surfaced to the user so they
+     * can back up the rotated key — if lost, the new identity is unrecoverable.
+     */
+    newPhrase: string;
+    /** The recovery phrase split into its individual words. */
+    words: string[];
+    /**
+     * Present (and `true`) only when the server rotated successfully but the new
+     * key could NOT be persisted on-device. The account key IS the new one
+     * server-side, so the user must re-import it from `newPhrase`; the caller
+     * should surface a recovery prompt. Omitted on full success.
+     */
+    localPersistFailed?: true;
+}
 /**
  * Derive a user's Oxy DID from their stable account id.
  * `did:web:oxy.so:u:<userId>`.
@@ -126,6 +175,52 @@ export declare function OxyServicesIdentityMixin<T extends typeof OxyServicesBas
          *   (`AuthMethodEntry.credentialId`).
          */
         removePasskey(credentialId: string): Promise<LinkAuthMethodResult>;
+        /**
+         * Rotate the account's identity key: derive a brand-new keypair, prove
+         * control of the CURRENT key, and have the server ATOMICALLY replace the old
+         * key with the new one.
+         *
+         * The rotation is an atomic REPLACE on the server (never remove-then-add), so
+         * it never passes through a zero-auth-method state and is independent of the
+         * unlink guards. Because control of the current key is PROVEN (from
+         * SecureStore in `'device'` mode, or a recovery-phrase re-derivation in
+         * `'phrase'` mode), even the LAST remaining credential can be replaced.
+         *
+         * Ordering (safety-critical): the new key is persisted on-device ONLY AFTER
+         * the server confirms the swap. Persisting earlier would clobber the local
+         * key while the server still trusts the old one, locking the device out.
+         *
+         * Ambiguous-network-failure guard: if the `complete` response is lost
+         * (request sent, no reply), the swap may already have applied server-side.
+         * Before surfacing the error we reconcile against the derived DID document —
+         * if it already advertises the new key, the rotation is treated as done.
+         *
+         * NOTE: the UI is responsible for showing `newPhrase` to the user. For a
+         * "show-phrase-first" flow, derive the identity up front via
+         * {@link RecoveryPhraseService.derivePendingIdentity}, display it, then pass
+         * it back as `options.pendingIdentity` so the SAME identity is committed.
+         *
+         * @throws when no user is authenticated, when `proof: 'phrase'` is given
+         *   without a `phrase`, when `proof: 'device'` runs with no on-device key,
+         *   or when the rotation does not complete.
+         */
+        rotateKey(options: RotateKeyOptions): Promise<RotateKeyResult>;
+        /**
+         * Reconciliation probe for the rotation ambiguous-failure guard: fetch the
+         * account's derived DID document (uncached) and report whether it already
+         * advertises `newPublicKey` as a verification method — i.e. whether the swap
+         * already landed server-side. A failed probe returns `false` (unconfirmed),
+         * so the caller surfaces the original network error.
+         *
+         * Uses the DID document rather than `GET /auth/methods` because the latter
+         * intentionally does NOT expose raw public keys, whereas the DID's
+         * `verificationMethod[].publicKeyHex` is derived live from the account's
+         * current key — so it reflects a completed rotation immediately.
+         *
+         * Internal helper (leading underscore); public rather than `private` for the
+         * same TS4094 reason as {@link _invalidateIdentityCaches}.
+         */
+        _rotationAlreadyApplied(userId: string, newPublicKey: string): Promise<boolean>;
         /**
          * Sign a record with the on-device identity key, WITHOUT publishing it.
          * The subject is the current user's DID. NATIVE-ONLY (requires a stored

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

@@ -0,0 +1,129 @@
+/**
+ * Encrypted off-device identity backup mixin (b3 Feature 1).
+ *
+ * Lets a self-custody identity store an ENCRYPTED copy of its key off-device so
+ * a lost/wiped device can be recovered from the recovery phrase alone — while the
+ * platform never sees the phrase, the derived key, or the plaintext private key.
+ *
+ * Key schedule (from the recovery phrase; see
+ * {@link RecoveryPhraseService.deriveBackupMaterial}):
+ *   seed      = bip39.mnemonicToSeed(phrase)                    // 64 bytes, UNCHANGED
+ *   backupKey = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-encryption-key')
+ *   lookupId  = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-lookup-id')   // hex
+ *
+ * The two derivations require the FULL seed, so a device compromise that leaks
+ * only the raw 32-byte private key can neither locate nor decrypt the backup.
+ *
+ * Wire shapes come from `@oxyhq/contracts` (`EncryptedBackupEnvelope`,
+ * `BackupUploadRequest`, `BackupStatusResponse`) — the API validates its
+ * request/response against the same schemas, so producer and consumer cannot
+ * drift.
+ *
+ * Encryption/derivation are cross-platform (pure `@noble/*`), but persisting a
+ * restored key is NATIVE-ONLY: `restoreFromEncryptedBackup` ends in
+ * `KeyManager.importKeyPair`, which throws on web (SecureStore does not exist
+ * there) — decryption still succeeds, only the local write is native-only.
+ */
+import type { BackupStatusResponse } from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesIdentityBackupMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Derive the backup key material from the recovery phrase, encrypt the
+         * identity's `{privateKey, publicKey, createdAt}` with it, and upload the
+         * ciphertext + raw `lookupId` (`POST /identity/backup`, bearer). The server
+         * stores only `sha256(lookupId)` + the ciphertext. Idempotent per user: a
+         * re-upload REPLACES the prior backup (upsert by user id).
+         *
+         * The identity is derived from the PHRASE (not read from SecureStore), so
+         * this works cross-platform and does not require an on-device key.
+         *
+         * @param phrase - The identity's BIP-39 recovery phrase.
+         * @returns The post-write backup status (`{ exists: true, publicKeyHint, createdAt }`).
+         */
+        createEncryptedBackup(phrase: string): Promise<BackupStatusResponse>;
+        /**
+         * Whether the authenticated user has a stored encrypted backup, plus the
+         * non-sensitive hint + timestamp when one exists (`GET /identity/backup/status`,
+         * bearer). Returns no ciphertext and no locator.
+         */
+        getBackupStatus(): Promise<BackupStatusResponse>;
+        /**
+         * Delete the authenticated user's stored backup (`DELETE /identity/backup`,
+         * bearer). Idempotent — deleting a non-existent backup still succeeds.
+         */
+        deleteBackup(): Promise<{
+            success: boolean;
+        }>;
+        /**
+         * Restore an identity from its encrypted off-device backup using ONLY the
+         * recovery phrase: re-derive `{backupKey, lookupId}`, fetch the envelope by
+         * `lookupId` (`GET /identity/backup/:lookupId`, PUBLIC — the 256-bit locator
+         * is the protection), decrypt + authenticate locally, then persist the key.
+         *
+         * NATIVE-ONLY persistence: `KeyManager.importKeyPair` throws on web. It also
+         * refuses to clobber a DIFFERENT existing on-device identity unless
+         * `overwrite: true` — the {@link import('../crypto/keyManager').IdentityAlreadyExistsError}
+         * propagates to the caller (never swallowed) so the UI can confirm before
+         * overwriting.
+         *
+         * @param phrase - The identity's BIP-39 recovery phrase.
+         * @param options.overwrite - Replace a different existing on-device identity.
+         * @returns The restored identity's public key.
+         * @throws if the phrase is invalid, no backup exists (404), the ciphertext
+         *   fails authentication (tamper), or an existing identity blocks the import.
+         */
+        restoreFromEncryptedBackup(phrase: string, options?: {
+            overwrite?: boolean;
+        }): Promise<string>;
+        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.user.d.ts

@@ -5,6 +5,25 @@ import type { User, Notification, NotificationPreferences, UserPreferences, Sear
 import type { UserNameResponse, UserProfileUpdate, RecommendationRequest, RecommendationItem } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PaginationParams } from '../utils/apiUtils';
+/**
+ * Response of the single follow/unfollow toggle route
+ * (`POST /users/:id/follow` and `DELETE /users/:id/follow`). The route reports a
+ * status message, which side of the toggle was applied, and the post-write
+ * follower/following counts for the affected users.
+ */
+export interface FollowMutationResult {
+    /** Human-readable status message. */
+    message: string;
+    /** Which side of the toggle was applied, when reported by the route. */
+    action?: 'follow' | 'unfollow';
+    /** Post-write counts, when reported by the route. */
+    counts?: {
+        /** The target user's follower count after the write. */
+        followers: number;
+        /** The viewer's following count after the write. */
+        following: number;
+    };
+}
 /** Per-user outcome returned by `POST /users/follow/bulk`. */
 export interface BulkFollowEntry {
     /** The user ID that was processed. */
@@ -309,10 +328,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * UI (the "follow resets after navigating away and back" bug).
          * `clearCacheEntry` deletes every identity-scoped variant of the key.
          */
-        followUser(userId: string): Promise<{
-            success: boolean;
-            message: string;
-        }>;
+        followUser(userId: string): Promise<FollowMutationResult>;
         /**
          * Follow multiple users in a single request.
          *
@@ -334,16 +350,30 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         /**
          * Unfollow a user
          */
-        unfollowUser(userId: string): Promise<{
-            success: boolean;
-            message: string;
-        }>;
+        unfollowUser(userId: string): Promise<FollowMutationResult>;
         /**
          * Get follow status
          */
         getFollowStatus(userId: string): Promise<{
             isFollowing: boolean;
         }>;
+        /**
+         * Resolve the viewer's follow status for MANY users in one round-trip per
+         * chunk. Built for list UIs (a page of `FollowButton`s) that would otherwise
+         * fire one `getFollowStatus` per button (the classic N+1).
+         *
+         * Ids are deduplicated and validated (empty/blank ids dropped), split into
+         * chunks of {@link FOLLOW_STATUS_CHUNK_SIZE} (the server's bulk cap), and
+         * POSTed to `/users/follow-status/bulk` as `{ userIds }`. The per-chunk
+         * `{ statuses }` maps are merged into one `Record<string, boolean>` covering
+         * every requested id — ids the viewer does not follow come back `false`.
+         *
+         * Uncached (`{ cache: false }`): the UI store owns follow-status freshness
+         * and writes optimistically on every mutation, so an SDK cache here would
+         * serve a stale status right after a follow/unfollow. An empty/whitespace-
+         * only input resolves immediately with `{}` and performs no network call.
+         */
+        getFollowStatuses(userIds: string[]): Promise<Record<string, boolean>>;
         /**
          * Get user followers
          */

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

@@ -8,6 +8,7 @@ import { OxyServicesBase } from '../OxyServices.base';
 import { OxyServicesAuthMixin } from './OxyServices.auth';
 import { OxyServicesUserMixin } from './OxyServices.user';
 import { OxyServicesIdentityMixin } from './OxyServices.identity';
+import { OxyServicesIdentityBackupMixin } from './OxyServices.identityBackup';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
 import { OxyServicesLanguageMixin } from './OxyServices.language';
 import { OxyServicesPaymentMixin } from './OxyServices.payment';
@@ -37,7 +38,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 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 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