react-native-wallet-keystore 0.1.0

package/package.json

@@ -0,0 +1,210 @@
+{
+  "name": "react-native-wallet-keystore",
+  "version": "0.1.0",
+  "description": "Hardware-protected secp256k1 wallet keys for React Native \u2014 Secure Enclave and Android Keystore, with a viem adapter",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "react-native-wallet-keystore-source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./viem": {
+      "react-native-wallet-keystore-source": "./src/viem.ts",
+      "types": "./lib/typescript/src/viem.d.ts",
+      "default": "./lib/module/viem.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "viem": [
+        "./lib/typescript/src/viem.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-wallet-keystore-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "test": "jest",
+    "release": "release-it --only-version"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "ethereum",
+    "wallet",
+    "secp256k1",
+    "viem",
+    "secure-enclave",
+    "android-keystore",
+    "biometrics",
+    "signing",
+    "keychain",
+    "web3"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miroosama/react-native-wallet-keystore.git"
+  },
+  "author": "Osama Miro <o.miro650@gmail.com> (https://github.com/miroosama)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/miroosama/react-native-wallet-keystore/issues"
+  },
+  "homepage": "https://github.com/miroosama/react-native-wallet-keystore#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^21.2.0",
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.6",
+    "@eslint/js": "^9.39.5",
+    "@jest/globals": "^29.7.0",
+    "@react-native/babel-preset": "0.86.2",
+    "@react-native/eslint-config": "0.86.2",
+    "@react-native/jest-preset": "0.86.2",
+    "@release-it/conventional-changelog": "^12.0.0",
+    "@types/react": "^19.2.0",
+    "commitlint": "^21.2.1",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.6",
+    "jest": "^29.7.0",
+    "lefthook": "^2.1.10",
+    "prettier": "^3.9.6",
+    "react": "19.2.3",
+    "react-native": "0.86.2",
+    "react-native-builder-bob": "^0.43.1",
+    "release-it": "^21.0.1",
+    "turbo": "^2.10.8",
+    "typescript": "^6.0.3",
+    "viem": "^2.56.8"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "viem": ">=2.0.0"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "WalletKeystoreSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.walletkeystore"
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "jest": {
+    "preset": "@react-native/jest-preset",
+    "testEnvironmentOptions": {
+      "customExportConditions": [
+        "require",
+        "react-native",
+        "react-native-wallet-keystore-source"
+      ]
+    },
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "create-react-native-library": {
+    "type": "turbo-module",
+    "languages": "kotlin-objc",
+    "tools": [
+      "eslint",
+      "jest",
+      "lefthook",
+      "release-it"
+    ],
+    "version": "0.63.1"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    }
+  }
+}

package/src/NativeWalletKeystore.ts

@@ -0,0 +1,43 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+/**
+ * Codegen contract.
+ *
+ * Everything crossing the bridge is a plain `string` on purpose: codegen
+ * supports a narrow set of types, and string-literal unions are handled
+ * inconsistently across React Native versions. The typed surface lives in
+ * `keystore.ts`, which narrows these values.
+ */
+export interface Spec extends TurboModule {
+  getBiometryType(): Promise<string>;
+  authenticate(reason: string, policy: string): Promise<boolean>;
+
+  storeSecret(
+    keyId: string,
+    secretHex: string,
+    policy: string,
+    invalidation: string
+  ): Promise<void>;
+  getSecret(keyId: string, reason: string): Promise<string>;
+  hasSecret(keyId: string): Promise<boolean>;
+  deleteSecret(keyId: string): Promise<void>;
+
+  generateKey(
+    keyId: string,
+    policy: string,
+    invalidation: string
+  ): Promise<string>;
+  importPrivateKey(
+    keyId: string,
+    privateKeyHex: string,
+    policy: string,
+    invalidation: string
+  ): Promise<string>;
+  getPublicKey(keyId: string): Promise<string>;
+
+  /** Returns 65 bytes of hex: `r || s || v`, low-s normalized, `v` of 27/28. */
+  signDigest(keyId: string, digestHex: string, reason: string): Promise<string>;
+  exportPrivateKey(keyId: string, reason: string): Promise<string>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('WalletKeystore');

package/src/errors.ts

@@ -0,0 +1,94 @@
+/**
+ * Stable, cross-platform error codes.
+ *
+ * The distinctions are load-bearing: `USER_CANCELED` means re-prompt,
+ * `NOT_ENROLLED` means send the user to Settings, and `KEY_INVALIDATED` means
+ * the secret is gone and recovery must start. Collapsing them makes callers
+ * guess.
+ */
+const CODES = [
+  'NOT_AVAILABLE',
+  'NOT_ENROLLED',
+  'USER_CANCELED',
+  'USER_FALLBACK',
+  'LOCKOUT',
+  'LOCKOUT_PERMANENT',
+  'SYSTEM_CANCEL',
+  'KEY_NOT_FOUND',
+  'KEY_ALREADY_EXISTS',
+  'KEY_INVALIDATED',
+  'STORAGE_ERROR',
+  'INVALID_KEY',
+  'UNKNOWN',
+] as const;
+
+export type KeystoreErrorCode = (typeof CODES)[number];
+
+const KNOWN_CODES: ReadonlySet<string> = new Set(CODES);
+
+export class KeystoreError extends Error {
+  readonly code: KeystoreErrorCode;
+
+  /** The raw native code, kept even when `code` has fallen back to `UNKNOWN`. */
+  readonly nativeCode?: string;
+
+  constructor(
+    code: KeystoreErrorCode,
+    message: string,
+    options?: { nativeCode?: string; cause?: unknown }
+  ) {
+    super(message);
+    this.name = 'KeystoreError';
+    this.code = code;
+    this.nativeCode = options?.nativeCode;
+
+    if (options && 'cause' in options) {
+      // Assigned rather than passed to super() to support pre-ES2022 targets.
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+
+    // Without this, extending a built-in breaks `instanceof` once compiled to
+    // ES5 — silently, and only for consumers.
+    Object.setPrototypeOf(this, KeystoreError.prototype);
+
+    const capture = (
+      Error as unknown as {
+        captureStackTrace?: (t: object, c?: unknown) => void;
+      }
+    ).captureStackTrace;
+    if (typeof capture === 'function') {
+      capture(this, KeystoreError);
+    }
+  }
+}
+
+function isKeystoreErrorCode(value: unknown): value is KeystoreErrorCode {
+  return typeof value === 'string' && KNOWN_CODES.has(value);
+}
+
+/**
+ * Normalizes any rejection into a `KeystoreError`.
+ *
+ * React Native surfaces `reject(code, message)` as an `Error` carrying `code`,
+ * but a JS-side failure can produce any shape at all, so everything degrades to
+ * `UNKNOWN` rather than throwing while building the error.
+ */
+export function toKeystoreError(value: unknown): KeystoreError {
+  if (value instanceof KeystoreError) {
+    return value;
+  }
+
+  const raw = (value as { code?: unknown } | null | undefined)?.code;
+  const message =
+    (value as { message?: unknown } | null | undefined)?.message ??
+    'The keystore operation failed.';
+
+  return new KeystoreError(
+    isKeystoreErrorCode(raw) ? raw : 'UNKNOWN',
+    typeof message === 'string' ? message : String(message),
+    {
+      nativeCode: typeof raw === 'string' ? raw : undefined,
+      cause: value,
+    }
+  );
+}

package/src/index.tsx

@@ -0,0 +1,6 @@
+export * from './keystore';
+export { KeystoreError, type KeystoreErrorCode } from './errors';
+
+// The viem adapter is intentionally not re-exported. It ships as the
+// `react-native-wallet-keystore/viem` subpath with viem as an optional peer, so
+// importing the core API never requires viem to be installed.

package/src/keystore.ts

@@ -0,0 +1,317 @@
+import NativeWalletKeystore from './NativeWalletKeystore';
+import { KeystoreError, toKeystoreError } from './errors';
+
+/**
+ * Android reports which biometric *hardware* exists, not which modality is
+ * enrolled, so it returns `'biometric'` when more than one is present.
+ */
+export type BiometryType =
+  | 'faceId'
+  | 'touchId'
+  | 'opticId'
+  | 'fingerprint'
+  | 'face'
+  | 'iris'
+  | 'biometric'
+  | 'none';
+
+export type AuthPolicy = 'biometricOnly' | 'biometricOrPasscode';
+
+/**
+ * Whether the wrapping key is destroyed when biometric enrollment changes.
+ *
+ * Orthogonal to {@link AuthPolicy} on purpose: `'biometricOnly'` must never
+ * imply invalidation, or a user adding a fingerprint silently destroys their
+ * wallet. Opting in is explicit.
+ */
+export type InvalidationPolicy = 'onEnrollmentChange' | 'never';
+
+export const DEFAULT_AUTH_POLICY: AuthPolicy = 'biometricOrPasscode';
+export const DEFAULT_INVALIDATION_POLICY: InvalidationPolicy = 'never';
+
+/** Uncompressed SEC1 public key: `0x04` followed by 64 bytes. */
+export type PublicKeyHex = `0x${string}`;
+
+/** 65-byte Ethereum signature: `r || s || v`, with `v` 27 or 28. */
+export type SignatureHex = `0x${string}`;
+
+type KeyOptions = {
+  policy?: AuthPolicy;
+  invalidation?: InvalidationPolicy;
+};
+
+const BIOMETRY_TYPES: ReadonlySet<string> = new Set<BiometryType>([
+  'faceId',
+  'touchId',
+  'opticId',
+  'fingerprint',
+  'face',
+  'iris',
+  'biometric',
+  'none',
+]);
+
+const HEX_PATTERN = /^(?:[0-9a-fA-F]{2})+$/;
+const HEX_32_BYTES = /^(?:0x)?[0-9a-fA-F]{64}$/;
+
+function strip0x(value: string): string {
+  return value.startsWith('0x') || value.startsWith('0X')
+    ? value.slice(2)
+    : value;
+}
+
+function prefix0x(value: string): `0x${string}` {
+  return (value.startsWith('0x') ? value : `0x${value}`) as `0x${string}`;
+}
+
+function assertKeyId(keyId: string): void {
+  if (typeof keyId !== 'string' || keyId.trim() === '') {
+    throw new KeystoreError('UNKNOWN', 'A non-empty `keyId` is required.');
+  }
+}
+
+function assertReason(reason: string, action: string): void {
+  // iOS raises on an empty localizedReason rather than failing gracefully, so
+  // this is checked before the bridge to keep both platforms consistent.
+  if (typeof reason !== 'string' || reason.trim() === '') {
+    throw new KeystoreError(
+      'UNKNOWN',
+      `A non-empty \`reason\` is required to ${action}.`
+    );
+  }
+}
+
+/**
+ * Which biometric modality the hardware supports, whether or not anything is
+ * enrolled. Resolves `'none'` when there is no hardware; never rejects.
+ *
+ * Enrollment state comes from {@link authenticate} via `NOT_ENROLLED`.
+ */
+export async function getBiometryType(): Promise<BiometryType> {
+  const type = await NativeWalletKeystore.getBiometryType();
+  // A native layer newer than this JS could return a modality we don't know.
+  return (BIOMETRY_TYPES.has(type) ? type : 'biometric') as BiometryType;
+}
+
+/**
+ * Prompts for device-owner authentication.
+ *
+ * A UX gate, not a security boundary — the boolean can be faked by a
+ * compromised bundle. Use {@link signDigest} where it actually matters.
+ *
+ * Never resolves `false`; every failure rejects.
+ *
+ * @throws {KeystoreError}
+ */
+export async function authenticate(
+  reason: string,
+  policy: AuthPolicy = DEFAULT_AUTH_POLICY
+): Promise<boolean> {
+  try {
+    assertReason(reason, 'authenticate');
+    return await NativeWalletKeystore.authenticate(reason, policy);
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}
+
+/**
+ * Stores a secret encrypted under a hardware-bound wrapping key.
+ *
+ * @throws {KeystoreError} `KEY_ALREADY_EXISTS` if `keyId` is taken; overwriting
+ *   is always deliberate.
+ */
+export async function storeSecret(
+  keyId: string,
+  secretHex: string,
+  options: KeyOptions = {}
+): Promise<void> {
+  try {
+    assertKeyId(keyId);
+
+    if (typeof secretHex !== 'string' || !HEX_PATTERN.test(secretHex)) {
+      throw new KeystoreError(
+        'UNKNOWN',
+        '`secretHex` must be a non-empty, even-length hex string.'
+      );
+    }
+
+    await NativeWalletKeystore.storeSecret(
+      keyId,
+      secretHex,
+      options.policy ?? DEFAULT_AUTH_POLICY,
+      options.invalidation ?? DEFAULT_INVALIDATION_POLICY
+    );
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}
+
+/**
+ * Authenticates and returns the stored secret as hex.
+ *
+ * The prompt is raised by the keystore as a precondition of using the wrapping
+ * key, so it cannot be bypassed from JS.
+ *
+ * @throws {KeystoreError} `KEY_NOT_FOUND`, `KEY_INVALIDATED`, or any auth code.
+ */
+export async function getSecret(
+  keyId: string,
+  reason: string
+): Promise<string> {
+  try {
+    assertKeyId(keyId);
+    assertReason(reason, 'read a secret');
+    return await NativeWalletKeystore.getSecret(keyId, reason);
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}
+
+/** Whether a secret is stored under `keyId`. Does not authenticate. */
+export async function hasSecret(keyId: string): Promise<boolean> {
+  try {
+    assertKeyId(keyId);
+    return await NativeWalletKeystore.hasSecret(keyId);
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}
+
+/** Removes the secret and its wrapping key. Idempotent. */
+export async function deleteSecret(keyId: string): Promise<void> {
+  try {
+    assertKeyId(keyId);
+    await NativeWalletKeystore.deleteSecret(keyId);
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}
+
+/**
+ * Generates a secp256k1 keypair in hardware-wrapped storage.
+ *
+ * Entropy comes from the platform CSPRNG, never from JavaScript, and the
+ * private key never crosses the bridge.
+ *
+ * @returns The uncompressed public key.
+ */
+export async function generateKey(
+  keyId: string,
+  options: KeyOptions = {}
+): Promise<PublicKeyHex> {
+  try {
+    assertKeyId(keyId);
+    return prefix0x(
+      await NativeWalletKeystore.generateKey(
+        keyId,
+        options.policy ?? DEFAULT_AUTH_POLICY,
+        options.invalidation ?? DEFAULT_INVALIDATION_POLICY
+      )
+    );
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}
+
+/**
+ * Imports an existing secp256k1 private key.
+ *
+ * @throws {KeystoreError} `INVALID_KEY` unless the key is in [1, n-1]. Keys
+ *   outside that range are rejected rather than clamped.
+ */
+export async function importPrivateKey(
+  keyId: string,
+  privateKeyHex: string,
+  options: KeyOptions = {}
+): Promise<PublicKeyHex> {
+  try {
+    assertKeyId(keyId);
+
+    if (
+      typeof privateKeyHex !== 'string' ||
+      !HEX_32_BYTES.test(privateKeyHex)
+    ) {
+      throw new KeystoreError(
+        'INVALID_KEY',
+        'A private key must be exactly 32 bytes of hex.'
+      );
+    }
+
+    // The range check stays native, where the curve order is already at hand.
+    return prefix0x(
+      await NativeWalletKeystore.importPrivateKey(
+        keyId,
+        strip0x(privateKeyHex),
+        options.policy ?? DEFAULT_AUTH_POLICY,
+        options.invalidation ?? DEFAULT_INVALIDATION_POLICY
+      )
+    );
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}
+
+/** The uncompressed public key. Does not authenticate. */
+export async function getPublicKey(keyId: string): Promise<PublicKeyHex> {
+  try {
+    assertKeyId(keyId);
+    return prefix0x(await NativeWalletKeystore.getPublicKey(keyId));
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}
+
+/**
+ * Authenticates, then signs a 32-byte digest.
+ *
+ * Only a digest crosses the boundary — never a message or a transaction.
+ * Keccak and EIP-191/712/155 encoding stay in JS, which keeps this module
+ * curve-specific but chain-agnostic.
+ *
+ * @returns 65 bytes, `r || s || v`, low-s normalized per EIP-2 with `v` of
+ *   27/28 — byte-identical to viem.
+ */
+export async function signDigest(
+  keyId: string,
+  digestHex: string,
+  reason: string
+): Promise<SignatureHex> {
+  try {
+    assertKeyId(keyId);
+
+    if (typeof digestHex !== 'string' || !HEX_32_BYTES.test(digestHex)) {
+      throw new KeystoreError(
+        'INVALID_KEY',
+        'A digest must be exactly 32 bytes of hex. Hash the message in JS first.'
+      );
+    }
+
+    assertReason(reason, 'sign');
+
+    return prefix0x(
+      await NativeWalletKeystore.signDigest(keyId, strip0x(digestHex), reason)
+    );
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}
+
+/**
+ * Authenticates, then returns the raw private key.
+ *
+ * For user-initiated backup only. The result lands in the JS heap where it
+ * cannot be zeroed, so prefer {@link signDigest} for everyday use.
+ */
+export async function exportPrivateKey(
+  keyId: string,
+  reason: string
+): Promise<string> {
+  try {
+    assertKeyId(keyId);
+    assertReason(reason, 'export a private key');
+    return prefix0x(await NativeWalletKeystore.exportPrivateKey(keyId, reason));
+  } catch (error) {
+    throw toKeystoreError(error);
+  }
+}