@oxy.so/core 1.0.0

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

@@ -0,0 +1,582 @@
+/**
+ * Key Manager - ECDSA secp256k1 Key Generation and Storage
+ *
+ * Handles secure generation, storage, and retrieval of cryptographic keys.
+ * Private keys are stored securely using expo-secure-store and never leave the device.
+ */
+import { type IdentityMarker } from './identityMarker';
+/**
+ * Thrown when an identity-mutating operation (createIdentity / importKeyPair)
+ * is invoked while a valid identity already exists on the device.
+ *
+ * The local private key IS the user's identity — overwriting it without
+ * explicit consent permanently loses access to their account (unless
+ * they previously saved their recovery phrase). This error forces callers
+ * to make an explicit, audited decision instead of silently clobbering.
+ */
+export declare class IdentityAlreadyExistsError extends Error {
+    readonly name = "IdentityAlreadyExistsError";
+    readonly existingPublicKey: string;
+    constructor(existingPublicKey: string);
+}
+/**
+ * Thrown when a freshly written identity cannot be read back, parsed, or
+ * round-tripped through sign/verify. Indicates a storage failure or
+ * corruption that would otherwise silently leave the user with an
+ * unusable account.
+ */
+export declare class IdentityPersistError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "IdentityPersistError";
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Thrown when identity storage cannot be read/written right now — the keychain
+ * is locked, the module failed to load, or a read threw — as opposed to the
+ * identity being genuinely absent.
+ *
+ * This is the crux of the corruption-vs-fresh-install fix: a storage THROW must
+ * NEVER be flattened into "no identity" (the old behavior, which let onboarding
+ * treat a momentarily-locked keystore as a blank device). Callers that used to
+ * tolerate a `false`/`null` from `hasIdentity()`/`getPublicKey()` on error must
+ * now treat this typed error as "cannot determine" — retry, surface a locked
+ * state, or abort a destructive path — never as "safe to create/overwrite".
+ */
+export declare class IdentityUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "IdentityUnavailableError";
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Authoritative tri-state (plus `unavailable`) verdict on the on-device
+ * identity, from {@link KeyManager.getIdentityStatus}.
+ *
+ * - `present`  — a healthy, round-tripping key pair exists.
+ * - `absent`   — storage read succeeded and returned nothing, AND no marker
+ *                records a prior identity → a genuine fresh device. The ONLY
+ *                state that may route to create/onboarding.
+ * - `lost`     — storage read succeeded but the keys are empty/unreadable while
+ *                the independent {@link IdentityMarker} records that an identity
+ *                DID exist here → corruption/keystore death. Route to recovery,
+ *                NEVER to create.
+ * - `unavailable` — a storage read THREW (keychain locked, module load failure).
+ *                Transient by assumption; NEVER cached; callers retry.
+ */
+export type IdentityStatus = {
+    state: 'present';
+    publicKey: string;
+} | {
+    state: 'absent';
+} | {
+    state: 'lost';
+    marker: IdentityMarker;
+} | {
+    state: 'unavailable';
+    cause: unknown;
+};
+/**
+ * Result of {@link KeyManager.attemptIdentityRecovery}. On success it reports
+ * which independent, `key_v1`-surviving source restored the identity. On failure
+ * `reason` distinguishes "wasn't lost", "no surviving source", "a source held a
+ * DIFFERENT account" (never silently switched), and "storage unavailable".
+ */
+export type IdentityRecoveryResult = {
+    recovered: true;
+    source: 'backup' | 'shared';
+    publicKey: string;
+} | {
+    recovered: false;
+    reason: 'not-lost' | 'no-sources' | 'mismatch' | 'unavailable';
+};
+export interface KeyPair {
+    publicKey: string;
+    privateKey: string;
+}
+export declare class KeyManager {
+    private static cachedPublicKey;
+    private static cachedHasIdentity;
+    private static cachedSharedPublicKey;
+    private static cachedHasSharedIdentity;
+    /**
+     * Distinguishes "public key genuinely absent (a successful empty read, safe to
+     * cache)" from "never resolved / storage threw (must NOT be cached)". A `null`
+     * {@link cachedPublicKey} alone is ambiguous — this flag makes the genuine
+     * absence cacheable WITHOUT ever caching a null produced by a thrown read.
+     */
+    private static cachedPublicKeyResolved;
+    /** Listeners notified synchronously whenever the identity verdict may have changed. */
+    private static readonly identityChangeListeners;
+    /**
+     * Memoized one-run-per-process slot migration. `slotMigrationResult` caches a
+     * STABLE outcome (`v2`/`legacy`); a `deferred` outcome is intentionally not
+     * cached (the in-flight promise is cleared) so a later call retries once the
+     * keychain unlocks.
+     */
+    private static slotMigrationPromise;
+    private static slotMigrationResult;
+    /**
+     * Invalidate cached identity state
+     * Called internally when identity is created/deleted/imported
+     */
+    private static invalidateCache;
+    /**
+     * Subscribe to identity-verdict changes (create / import / delete / restore /
+     * cache invalidation). Fires synchronously; the returned function unsubscribes.
+     * Consumed via `useOxyEvent`-style hooks in commons to invalidate the routing
+     * queries the instant the identity state moves, without polling.
+     */
+    static subscribeIdentityChanged(listener: () => void): () => void;
+    /** Synchronous fan-out with per-listener isolation (one throwing listener never blocks the rest). */
+    private static notifyIdentityChanged;
+    /** Build `getItemAsync`/`deleteItemAsync` options for a given keychain service (read/delete). */
+    private static _slotOpts;
+    /** Build private-key write options (device-only accessibility) for a given keychain service. */
+    private static _privateWriteOpts;
+    /** True only when both keys are present, well-formed, AND the public derives from the private. */
+    private static _isHealthyPair;
+    /**
+     * Resolve the AsyncStorage-backed KV store for the advisory migration flag, or
+     * `null` off-RN / when unavailable. Independent of the keychain, so the flag
+     * cannot be taken down by the keystore event this whole subsystem defends
+     * against.
+     */
+    private static _advisoryStorage;
+    private static _readSlotsMigratedFlag;
+    private static _setSlotsMigratedFlag;
+    /**
+     * Ensure the identity has been migrated onto the isolated v2 slots (or that we
+     * know we must read legacy this session). Memoized so concurrent callers share
+     * ONE run; a `deferred` (read-threw) outcome is not cached so a later call
+     * retries after the keychain unlocks. Every identity-slot accessor awaits this
+     * before touching storage.
+     */
+    private static _ensureIdentitySlotsMigrated;
+    /**
+     * One-shot slot migration state machine. All reads are DIRECT and a thrown
+     * read defers everything (zero writes/deletes) so a locked keychain is never
+     * mistaken for an empty one. INVARIANT: at every instant ≥1 readable copy of a
+     * previously-existing identity remains — legacy is deleted ONLY after the v2
+     * copy is verified re-readable in its new (non-aliasable) location.
+     */
+    private static _runSlotMigration;
+    /**
+     * Seed the v2 backup slot during migration. Prefers a healthy legacy backup;
+     * otherwise mirrors the (already-verified) v2 primary material so a v2 backup
+     * always exists on an independent keychain key. Best-effort — a failure just
+     * defers backup population to the next {@link _persistIdentityAtomic}.
+     */
+    private static _migrateBackupSlotToV2;
+    /** Best-effort single delete under an optional keychain service. Cleanup only — never surfaces. */
+    private static _bestEffortDelete;
+    private static _bestEffortDeleteV2Primary;
+    private static _bestEffortDeleteLegacyPrimaryAndBackup;
+    private static _bestEffortDeleteBackupsAllGenerations;
+    /**
+     * Clear the cross-app shared identity slot (force-delete only) so a deleted
+     * identity cannot be resurrected via the recovery ladder's shared rung.
+     * Best-effort — the shared slot is a redundant convenience copy.
+     */
+    private static _clearSharedSlot;
+    /**
+     * Invalidate cached shared identity state
+     * Called internally when shared identity is created/deleted/imported
+     */
+    private static invalidateSharedCache;
+    /**
+     * Lowercase and pad to canonical 64-hex-char form.
+     *
+     * Tolerates legacy leading-zero-stripped keys and externally imported
+     * uppercase hex. Every derivation path canonicalizes first so storage
+     * representation cannot change the resulting identity.
+     *
+     * Private (used only inside KeyManager) — public consumers should not need
+     * to think about hex representation.
+     */
+    private static canonicalPrivateKey;
+    /**
+     * Generate a new ECDSA secp256k1 key pair
+     * Returns the keys in hexadecimal format
+     */
+    static generateKeyPairSync(): KeyPair;
+    /**
+     * Generate a new key pair using secure random bytes
+     */
+    static generateKeyPair(): Promise<KeyPair>;
+    /**
+     * Create a shared identity accessible across all Oxy apps
+     *
+     * iOS: Stores in shared keychain group (requires entitlement configuration)
+     * Android: Stores in Account Manager (requires sharedUserId in manifest)
+     *
+     * This enables true cross-app SSO - when user signs in to one Oxy app,
+     * they're automatically signed in to all other Oxy apps.
+     *
+     * @returns Public key of the shared identity
+     * @throws Error if not on native platform or if sharing is not configured
+     */
+    static createSharedIdentity(): Promise<string>;
+    /**
+     * Get the shared public key (accessible across all Oxy apps)
+     *
+     * @returns Shared public key or null if no shared identity exists
+     */
+    static getSharedPublicKey(): Promise<string | null>;
+    /**
+     * Get the shared private key (for signing operations)
+     *
+     * WARNING: Only use this for signing operations within the app.
+     * The private key should NEVER be transmitted or exposed.
+     *
+     * @returns Shared private key or null if no shared identity exists
+     */
+    static getSharedPrivateKey(): Promise<string | null>;
+    /**
+     * Check if a shared identity exists (accessible across all Oxy apps)
+     *
+     * @returns True if shared identity exists, false otherwise
+     */
+    static hasSharedIdentity(): Promise<boolean>;
+    /**
+     * Import an existing key pair as shared identity
+     *
+     * This is used when:
+     * 1. User signs in to a new Oxy app for the first time
+     * 2. User has existing identity on another Oxy app
+     * 3. We want to sync the identity across apps
+     *
+     * @param privateKey - Private key in hex format
+     * @returns Public key
+     */
+    static importSharedIdentity(privateKey: string): Promise<string>;
+    /**
+     * Store session information in shared storage
+     *
+     * This allows all Oxy apps to access the same session without
+     * re-authenticating. When user signs in to one app, all apps
+     * get the session automatically.
+     *
+     * @param sessionId - Session ID from authentication
+     * @param accessToken - Access token for API calls
+     */
+    static storeSharedSession(sessionId: string, accessToken: string): Promise<void>;
+    /**
+     * Get shared session information
+     *
+     * This allows any Oxy app to check if user is already signed in
+     * via another Oxy app. Enables instant cross-app SSO.
+     *
+     * @returns Session data or null if no shared session exists
+     */
+    static getSharedSession(): Promise<{
+        sessionId: string;
+        accessToken: string;
+    } | null>;
+    /**
+     * Clear shared session (on logout)
+     *
+     * This signs out the user from ALL Oxy apps simultaneously.
+     * Call this when user explicitly logs out.
+     */
+    static clearSharedSession(): Promise<void>;
+    /**
+     * Migrate local identity to shared identity
+     *
+     * Call this when upgrading existing apps to use shared identities.
+     * Copies the device-specific identity to shared storage so it can
+     * be accessed by other Oxy apps.
+     *
+     * @returns True if migration was successful, false if no local identity exists
+     */
+    static migrateToSharedIdentity(): Promise<boolean>;
+    /**
+     * Atomically persist a key pair to secure storage with verification + backup.
+     *
+     * INVARIANT (the reason this method exists): at no instant during the write
+     * may the device be left holding ZERO recoverable copies of a healthy
+     * identity. This matters most on the OVERWRITE / account-switch path: if we
+     * are replacing identity A with B and the write fails halfway, we MUST end
+     * up back on A — never on a half-written B, and never on nothing.
+     *
+     * Algorithm (recoverability-preserving):
+     *   0. Snapshot the existing primary (privA, pubA) so we can roll back to
+     *      EXACTLY what was there.
+     *   1. Write the new primary: public first, then private.
+     *   2. Read back + sign/verify the new primary.
+     *   3. ONLY after the new primary is proven durable, refresh the backup to
+     *      the new key. The backup is NEVER touched before this point, so any
+     *      prior identity's backup remains intact and `restoreIdentityFromBackup`
+     *      can always recover it.
+     *   4. On ANY failure in steps 1–2, restore the snapshotted primary verbatim
+     *      (or delete it if there was none), then surface the error.
+     *
+     * Earlier versions wrote the *incoming* key to the backup FIRST, which
+     * destroyed the previous identity's backup, and rolled back by blindly
+     * deleting the primary — so a failed overwrite silently switched the user
+     * to (or lost them into) the half-written new identity. That is fixed here.
+     *
+     * @internal
+     */
+    private static _persistIdentityAtomic;
+    /**
+     * Write/refresh the identity marker after a successful persist. A same-identity
+     * re-persist (e.g. backup refresh, idempotent re-import) preserves `createdAt`
+     * and the `onboardingComplete` milestone by only updating `origin`; a NEW or
+     * switched identity writes a fresh marker. Best-effort — never throws.
+     *
+     * @internal
+     */
+    private static _syncMarkerAfterPersist;
+    /**
+     * Restore the backup slot to a previously-snapshotted state. Best-effort so
+     * the original persistence error remains the one surfaced to the caller.
+     *
+     * @internal
+     */
+    private static _rollbackBackup;
+    /**
+     * Restore the primary slot to a previously-snapshotted (privA, pubA) pair,
+     * or delete it entirely if there was no prior identity. Best-effort: every
+     * step is wrapped so a rollback failure never masks the original error the
+     * caller is about to throw. Invalidates the in-memory cache so the next read
+     * reflects whatever actually landed on disk.
+     *
+     * @internal
+     */
+    private static _rollbackPrimary;
+    /**
+     * Generate and securely store a new key pair on the device.
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     * Returns the public key. The private key never leaves secure storage.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
+     * @throws IdentityPersistError if the key cannot be durably written
+     */
+    static createIdentity(options?: {
+        overwrite?: boolean;
+    }): Promise<string>;
+    /**
+     * Read the primary key pair DIRECTLY from storage, bypassing the in-memory
+     * cache (which a prior transient failure could have poisoned). Awaits slot
+     * migration first. Throws {@link IdentityUnavailableError} if storage is
+     * deferred/locked or a read throws — so overwrite guards never write blind.
+     *
+     * @internal
+     */
+    private static _readPrimaryDirect;
+    /**
+     * Import an existing key pair (e.g., from recovery phrase).
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
+     * @throws IdentityPersistError if the key cannot be durably written
+     */
+    static importKeyPair(privateKey: string, options?: {
+        overwrite?: boolean;
+    }): Promise<string>;
+    /**
+     * Get the stored private key
+     * WARNING: Only use this for signing operations within the app
+     *
+     * Preserves the "return null on any storage failure" contract signing paths
+     * rely on (a locked keychain simply means "cannot sign now"); unlike
+     * {@link getPublicKey}, it does NOT throw {@link IdentityUnavailableError}.
+     */
+    static getPrivateKey(): Promise<string | null>;
+    /**
+     * Get the stored public key (cached for performance).
+     *
+     * Returns the public key, or `null` when a read SUCCEEDS and finds none.
+     * THROWS {@link IdentityUnavailableError} when storage is unreadable (keychain
+     * locked / module load failure) — a thrown read is NEVER flattened to `null`
+     * 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.
+     *
+     * Returns `true` only when BOTH the private and public keys are present,
+     * both are well-formed, AND the public key derives from the private key.
+     * A partially-written or corrupted identity (read succeeded, bytes empty/bad)
+     * returns `false` so that downstream code can resume the create / restore flow.
+     * THROWS {@link IdentityUnavailableError} when storage is unreadable — a locked
+     * keychain must never be mistaken for "no identity" (the old behavior that let
+     * onboarding treat a transient lock as a blank device).
+     *
+     * Note: this does NOT perform the full sign/verify roundtrip — call
+     * `verifyIdentityIntegrity()` for that.
+     */
+    static hasIdentity(): Promise<boolean>;
+    /**
+     * Authoritative identity verdict — the corruption-vs-fresh-install
+     * disambiguator that routing (commons) keys off of.
+     *
+     * - Healthy pair → `present` (and the marker is backfilled if missing or
+     *   pointing at a different key, `origin: 'backfill'`).
+     * - Read succeeded but no healthy pair, WITH a marker → `lost` (keystore death
+     *   / corruption; route to recovery, NEVER to create).
+     * - Read succeeded, no pair, NO marker → `absent` (a genuine fresh device; the
+     *   only state that may route to onboarding/create).
+     * - A read THREW → `unavailable` (keychain locked); this verdict is NEVER
+     *   cached, so a later call re-reads.
+     *
+     * @param opts.bypassCache When true, never reads OR writes the in-memory cache
+     *   — a pure, fresh storage verdict for the auto-create interlock preflight.
+     */
+    static getIdentityStatus(opts?: {
+        bypassCache?: boolean;
+    }): Promise<IdentityStatus>;
+    /**
+     * Delete the stored identity (both keys)
+     * Use with EXTREME caution - this is irreversible without a recovery phrase
+     * This should ONLY be called when explicitly requested by the user
+     * @param skipBackup - If true, skip backup before deletion (default: false)
+     * @param force - If true, skip confirmation checks (default: false)
+     * @param userConfirmed - If true, user has explicitly confirmed deletion (default: false)
+     */
+    static deleteIdentity(skipBackup?: boolean, force?: boolean, userConfirmed?: boolean): Promise<void>;
+    /**
+     * Backup identity to SecureStore (separate backup storage)
+     * This provides a recovery mechanism if primary storage fails
+     */
+    static backupIdentity(): Promise<boolean>;
+    /**
+     * Verify identity integrity — checks keys are valid, accessible, derive
+     * consistently, AND can sign + verify a probe message.
+     *
+     * Returns true only when the full sign/verify roundtrip succeeds. Use
+     * this on app start to detect silent corruption before the user finds
+     * out by failing to sign in.
+     */
+    static verifyIdentityIntegrity(): Promise<boolean>;
+    /**
+     * Restore identity from backup if primary storage is genuinely missing or
+     * corrupt.
+     *
+     * SAFETY (three independent guards against silently switching accounts):
+     *   1. If the primary passes a full sign/verify probe, do nothing.
+     *   2. If the primary keys CANNOT BE READ (storage threw — e.g. a transient
+     *      keychain lock during a background launch), do nothing. We must NOT
+     *      treat "couldn't read" as "corrupted" and restore a possibly-stale
+     *      backup over an identity that is actually fine but momentarily
+     *      inaccessible.
+     *   3. If a primary private/public key IS present but does not match the
+     *      backup, the backup may belong to a different identity — refuse, so we
+     *      never silently switch the user to another account.
+     *
+     * Only when the primary is provably absent (read succeeded, returned
+     * null/empty) or provably corrupt (read succeeded, bytes malformed AND no
+     * conflicting key material is present) do we rebuild it from the backup.
+     */
+    static restoreIdentityFromBackup(): Promise<boolean>;
+    /**
+     * Recovery ladder — restore a `lost` identity from an independent,
+     * `key_v1`-surviving source WITHOUT the user re-entering their recovery phrase.
+     *
+     * Gated on {@link getIdentityStatus} being `lost` (marker present, keys empty):
+     *   - `present` / `absent` → `not-lost` (nothing to recover / nothing lost)
+     *   - `unavailable`        → `unavailable` (keychain locked; retry later)
+     *
+     * Rungs, tried in order, each fully validated (well-formed + derive-match +
+     * `publicKey === marker.publicKey`, so a source holding a DIFFERENT account is
+     * SKIPPED, never restored):
+     *   1. the v2 backup slot (independent keychain key from the primary), then
+     *   2. the cross-app shared slot (Android bridge `getShared` / iOS keychain
+     *      group) — the copy that survives a primary+backup `key_v1` death.
+     *
+     * On success it re-persists via {@link _persistIdentityAtomic} (origin
+     * `'restore'`) and invalidates the cache so routing re-reads `present`. When no
+     * rung matches, the UI proceeds to recovery-phrase entry.
+     */
+    static attemptIdentityRecovery(): Promise<IdentityRecoveryResult>;
+    /** Read the active-layout backup slot as a healthy candidate, or null. @internal */
+    private static _readBackupCandidate;
+    /** Read the cross-app shared slot as a healthy candidate, or null. @internal */
+    private static _readSharedCandidate;
+    /** Persist a validated recovery candidate + refresh caches/subscribers. @internal */
+    private static _commitRecovery;
+    /**
+     * 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
+     *
+     * Returns false on parse errors (invalid input is the expected fail mode here).
+     * Errors are logged at debug level so they're available when troubleshooting
+     * but don't pollute production logs.
+     */
+    static isValidPublicKey(publicKey: string): boolean;
+    /**
+     * Validate that a string is a valid private key.
+     *
+     * secp256k1 private keys are 256-bit, so 64 hex chars. We require strict
+     * hex-only input so malformed text can never be coerced into a scalar.
+     */
+    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
+     */
+    static shortenPublicKey(publicKey: string): string;
+}
+export default KeyManager;

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

@@ -0,0 +1,25 @@
+/**
+ * Crypto Polyfills
+ *
+ * Ensures Buffer and crypto.getRandomValues are available
+ * across all platforms (Node.js, Browser, React Native).
+ *
+ * Guard order when installing a `getRandomValues` shim (see bottom of file and
+ * {@link cryptoPolyfill}):
+ *
+ *   1. A REAL `globalThis.crypto.getRandomValues` — used as-is (browser, Node
+ *      >= 20, modern Hermes). The shim below is only installed when the host is
+ *      missing it, so this branch is the install-time gate.
+ *   2. Node — backed by the built-in `node:crypto` module (`webcrypto`, else
+ *      `randomFillSync`). This is what a Node runtime WITHOUT a global WebCrypto
+ *      (Node 18 script entrypoints, some embedded hosts) falls back to.
+ *   3. React Native — `expo-crypto.getRandomBytes` (statically imported via the
+ *      per-platform `platform/crypto` module in `@oxy.so/protocol`).
+ *
+ * Historically step (2) delegated to `@oxy.so/protocol`'s RN-only
+ * `getRandomBytesRN`, which THROWS on Node — so any Node host lacking a global
+ * WebCrypto crashed here instead of getting randomness. It is now a proper
+ * Node-backed implementation.
+ */
+import { Buffer } from 'buffer';
+export { Buffer };