@mentaproject/signer-react-native 0.0.1

package/README.md

@@ -0,0 +1,343 @@
+# @mentaproject/signer-react-native
+
+React Native Passkey signer for Menta wallet. Implements `SmartAccountSigner` using WebAuthn/Passkeys with P-256 (secp256r1) keys stored in the device's secure enclave.
+
+## Installation
+
+```bash
+npm install @mentaproject/passkey-signer-react-native
+```
+
+### Peer Dependencies
+
+```bash
+npm install react-native-passkey viem @mentaproject/core
+```
+
+### iOS Setup
+
+Add the Associated Domains capability to your app:
+
+1. In Xcode, go to your target's "Signing & Capabilities"
+2. Add "Associated Domains"
+3. Add `webcredentials:yourdomain.com`
+
+Create an `apple-app-site-association` file on your server at `https://yourdomain.com/.well-known/apple-app-site-association`:
+
+```json
+{
+  "webcredentials": {
+    "apps": ["TEAMID.com.yourcompany.yourapp"]
+  }
+}
+```
+
+### Android Setup
+
+Add to your `android/app/build.gradle`:
+
+```gradle
+android {
+    defaultConfig {
+        // ...
+        resValue "string", "host", "yourdomain.com"
+    }
+}
+```
+
+Create a `assetlinks.json` file at `https://yourdomain.com/.well-known/assetlinks.json`:
+
+```json
+[{
+  "relation": ["delegate_permission/common.get_login_creds", "delegate_permission/common.handle_all_urls"],
+  "target": {
+    "namespace": "android_app",
+    "package_name": "com.yourcompany.yourapp",
+    "sha256_cert_fingerprints": ["YOUR_APP_FINGERPRINT"]
+  }
+}]
+```
+
+## Quick Start
+
+### Register a New Passkey
+
+```typescript
+import { ReactNativePasskeySigner } from '@mentaproject/signer-react-native';
+
+// Create a new passkey (triggers biometric prompt)
+const signer = await ReactNativePasskeySigner.register('user@example.com', {
+  rpId: 'yourdomain.com',
+  rpName: 'Your App Name',
+});
+
+// Store the credential for later use
+const credential = signer.getCredential();
+await AsyncStorage.setItem('passkey', JSON.stringify(credential));
+
+// Get the public key for smart account creation
+const publicKeyX = signer.getPublicKeyX(); // 32 bytes hex
+const publicKeyY = signer.getPublicKeyY(); // 32 bytes hex
+```
+
+### Restore from Stored Credential
+
+```typescript
+import { 
+  ReactNativePasskeySigner,
+  deserializeCredential 
+} from '@mentaproject/signer-react-native';
+
+// Load stored credential
+const stored = await AsyncStorage.getItem('passkey');
+const credential = deserializeCredential(JSON.parse(stored));
+
+// Recreate the signer
+const signer = ReactNativePasskeySigner.fromCredential(credential, {
+  rpId: 'yourdomain.com',
+  rpName: 'Your App Name',
+});
+```
+
+### Sign a UserOperation
+
+```typescript
+// Sign a UserOpHash (triggers biometric prompt)
+const signature = await signer.signMessage({
+  message: { raw: userOpHash }, // Hex string
+});
+
+// Use the signature with your smart account
+```
+
+### Sign Typed Data (EIP-712)
+
+```typescript
+const signature = await signer.signTypedData({
+  domain: {
+    name: 'Your App',
+    version: '1',
+    chainId: 1,
+    verifyingContract: '0x...',
+  },
+  types: {
+    Message: [
+      { name: 'content', type: 'string' },
+    ],
+  },
+  primaryType: 'Message',
+  message: {
+    content: 'Hello World',
+  },
+});
+```
+
+## Signature Formats
+
+The signer supports multiple signature encoding formats for different smart contract implementations:
+
+```typescript
+// Default: Kernel/ZeroDev format
+const signer = await ReactNativePasskeySigner.register(username, config);
+
+// Change format for Rhinestone
+const rhineSigner = signer.withSignatureFormat('rhinestone');
+
+// Raw format (r || s only)
+const rawSigner = signer.withSignatureFormat('raw');
+```
+
+### Kernel Format (Default)
+
+```solidity
+abi.encode(
+  bytes authenticatorData,
+  string clientDataJSON,
+  uint256 challengeIndex,
+  uint256 responseTypeIndex,
+  uint256 r,
+  uint256 s
+)
+```
+
+### Rhinestone Format
+
+```solidity
+abi.encode(
+  bytes authenticatorData,
+  bytes clientDataJSON,
+  uint256[2] signature // [r, s]
+)
+```
+
+## API Reference
+
+### ReactNativePasskeySigner
+
+#### Static Methods
+
+| Method | Description |
+|--------|-------------|
+| `register(username, config)` | Creates a new passkey and returns a signer |
+| `fromCredential(credential, config)` | Restores a signer from stored credential data |
+
+#### Instance Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `source` | `"passkey"` | Signer type identifier |
+| `publicKey` | `Hex` | Uncompressed public key (65 bytes) |
+| `credentialId` | `string` | Base64URL credential ID |
+| `credentialIdHex` | `Hex` | Hex credential ID |
+
+#### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `signMessage({ message })` | Signs a message (triggers biometric) |
+| `signTypedData(typedData)` | Signs EIP-712 typed data |
+| `getAddress()` | Returns derived address |
+| `getPublicKeyX()` | Returns X coordinate (32 bytes) |
+| `getPublicKeyY()` | Returns Y coordinate (32 bytes) |
+| `getCredential()` | Returns credential for storage |
+| `withSignatureFormat(format)` | Returns new signer with different format |
+
+### Configuration
+
+```typescript
+interface ReactNativePasskeySignerConfig {
+  // Required
+  rpId: string;          // Relying Party ID (your domain)
+  rpName: string;        // Display name for system UI
+  
+  // Optional
+  timeout?: number;                    // Prompt timeout in ms (default: 60000)
+  userVerification?: 'required' | 'preferred' | 'discouraged';
+  signatureFormat?: 'kernel' | 'rhinestone' | 'raw';
+}
+```
+
+### Credential Storage
+
+```typescript
+import { 
+  serializeCredential, 
+  deserializeCredential,
+  isPasskeyCredential 
+} from '@mentaproject/signer-react-native';
+
+// Serialize for storage
+const data = serializeCredential(signer.getCredential());
+await SecureStorage.set('passkey', JSON.stringify(data));
+
+// Deserialize on restore
+const stored = JSON.parse(await SecureStorage.get('passkey'));
+const credential = deserializeCredential(stored);
+
+// Validate before use
+if (isPasskeyCredential(credential)) {
+  const signer = ReactNativePasskeySigner.fromCredential(credential, config);
+}
+```
+
+## Integration with Smart Accounts
+
+### With Kernel (ZeroDev)
+
+```typescript
+import { createKernelAccount } from '@zerodev/sdk';
+import { ReactNativePasskeySigner } from '@mentaproject/signer-react-native';
+
+const signer = await ReactNativePasskeySigner.register(username, {
+  rpId: 'yourdomain.com',
+  rpName: 'Your App',
+});
+
+// The public key coordinates are needed for the WebAuthn validator
+const webAuthnKey = {
+  pubKeyX: BigInt(signer.getPublicKeyX()),
+  pubKeyY: BigInt(signer.getPublicKeyY()),
+  authenticatorIdHash: keccak256(signer.credentialIdHex),
+};
+
+// Create the kernel account with WebAuthn validator
+const account = await createKernelAccount(publicClient, {
+  plugins: {
+    sudo: await signerToWebAuthnValidator(publicClient, {
+      webAuthnKey,
+      signer, // Pass the signer directly
+    }),
+  },
+});
+```
+
+### With permissionless.js
+
+```typescript
+import { createSmartAccountClient } from 'permissionless';
+
+const smartAccountClient = createSmartAccountClient({
+  account,
+  chain,
+  bundlerTransport: http(bundlerUrl),
+  // The signer's signMessage will be called for UserOp signing
+});
+```
+
+## Utilities
+
+For advanced use cases, low-level utilities are exported:
+
+```typescript
+import {
+  // COSE parsing
+  extractP256PublicKey,
+  extractPublicKeyFromAttestation,
+  
+  // Signature handling
+  parseDERSignature,
+  normalizeSignatureS,
+  encodeWebAuthnSignature,
+  
+  // Encoding
+  base64UrlToHex,
+  hexToBase64Url,
+} from '@mentaproject/signer-react-native';
+```
+
+## Error Handling
+
+```typescript
+import { 
+  PasskeySignerError, 
+  COSEParseError, 
+  SignatureError 
+} from '@mentaproject/signer-react-native';
+
+try {
+  const signer = await ReactNativePasskeySigner.register(username, config);
+} catch (error) {
+  if (error instanceof PasskeySignerError) {
+    // User cancelled, biometric failed, or device not supported
+    console.error('Passkey error:', error.message);
+    console.error('Cause:', error.cause);
+  }
+}
+```
+
+## Security Considerations
+
+1. **Secure Enclave**: Private keys never leave the device's secure enclave
+2. **Biometric Required**: Each signature requires user authentication
+3. **Low-S Normalization**: Signatures are normalized to prevent malleability
+4. **Domain Binding**: Passkeys are bound to your domain (rpId)
+
+## Requirements
+
+- iOS 16+ or Android 9+
+- React Native 0.70+
+- Device with biometric authentication (Face ID, Touch ID, fingerprint)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @mentaproject/signer-react-native
+ *
+ * React Native Passkey signer for Menta wallet.
+ * Implements SmartAccountSigner using WebAuthn/Passkeys with P-256 keys.
+ *
+ * @packageDocumentation
+ */
+export { ReactNativePasskeySigner, PasskeySignerError, isPasskeyCredential, serializeCredential, deserializeCredential, } from "./signer.js";
+export type { SmartAccountSigner, SmartAccountSignerSource, SignableMessage, PasskeyConfig, P256PublicKey, PasskeyCredential, AuthenticatorData, WebAuthnSignature, SignatureEncodingFormat, ReactNativePasskeySignerConfig, } from "./types/index.js";
+export { base64UrlToBytes, bytesToBase64Url, base64UrlToHex, hexToBase64Url, bytesToHex, hexToBytes, padHex, concatHex, extractP256PublicKey, extractPublicKeyFromAttestation, encodeUncompressedPublicKey, isValidP256PublicKey, COSEParseError, parseWebAuthnAssertion, encodeWebAuthnSignature, parseDERSignature, normalizeSignatureS, createChallenge, SignatureError, } from "./utils/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,EACf,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAEL,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,UAAU,EACV,UAAU,EACV,MAAM,EACN,SAAS,EAGT,oBAAoB,EACpB,+BAA+B,EAC/B,2BAA2B,EAC3B,oBAAoB,EACpB,cAAc,EAGd,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @mentaproject/signer-react-native
+ *
+ * React Native Passkey signer for Menta wallet.
+ * Implements SmartAccountSigner using WebAuthn/Passkeys with P-256 keys.
+ *
+ * @packageDocumentation
+ */
+// Main signer class
+export { ReactNativePasskeySigner, PasskeySignerError, isPasskeyCredential, serializeCredential, deserializeCredential, } from "./signer.js";
+// Utilities (for advanced use cases)
+export { 
+// Base64URL utilities
+base64UrlToBytes, bytesToBase64Url, base64UrlToHex, hexToBase64Url, bytesToHex, hexToBytes, padHex, concatHex, 
+// COSE parsing
+extractP256PublicKey, extractPublicKeyFromAttestation, encodeUncompressedPublicKey, isValidP256PublicKey, COSEParseError, 
+// Signature utilities
+parseWebAuthnAssertion, encodeWebAuthnSignature, parseDERSignature, normalizeSignatureS, createChallenge, SignatureError, } from "./utils/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oBAAoB;AACpB,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAgBrB,qCAAqC;AACrC,OAAO;AACL,sBAAsB;AACtB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,UAAU,EACV,UAAU,EACV,MAAM,EACN,SAAS;AAET,eAAe;AACf,oBAAoB,EACpB,+BAA+B,EAC/B,2BAA2B,EAC3B,oBAAoB,EACpB,cAAc;AAEd,sBAAsB;AACtB,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC"}

package/dist/signer.d.ts

@@ -0,0 +1,161 @@
+import { type Address, type Hex, type TypedData, type TypedDataDefinition } from "viem";
+import type { SmartAccountSigner, PasskeyCredential, P256PublicKey, ReactNativePasskeySignerConfig, SignableMessage, SignatureEncodingFormat } from "./types/index.js";
+/**
+ * Error thrown when passkey operations fail.
+ */
+export declare class PasskeySignerError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * ReactNativePasskeySigner implements SmartAccountSigner using WebAuthn/Passkeys.
+ *
+ * This signer uses the device's biometric authentication (Face ID, Touch ID, fingerprint)
+ * to sign messages and transactions for ERC-4337 smart accounts.
+ *
+ * The public key is a P-256 (secp256r1) key stored in the device's secure enclave.
+ *
+ * @example
+ * ```typescript
+ * // Register a new passkey
+ * const signer = await ReactNativePasskeySigner.register("user@example.com", {
+ *   rpId: "example.com",
+ *   rpName: "Example App",
+ * });
+ *
+ * // Sign a message (triggers biometric prompt)
+ * const signature = await signer.signMessage({
+ *   message: { raw: userOpHash },
+ * });
+ * ```
+ */
+export declare class ReactNativePasskeySigner implements SmartAccountSigner<"passkey"> {
+    readonly source: "passkey";
+    /**
+     * The credential ID in Base64URL format.
+     */
+    readonly credentialId: string;
+    /**
+     * The credential ID as hex.
+     */
+    readonly credentialIdHex: Hex;
+    /**
+     * The P-256 public key coordinates (x, y).
+     */
+    readonly publicKeyCoordinates: P256PublicKey;
+    /**
+     * The encoded public key (uncompressed SEC1 format: 0x04 || x || y).
+     */
+    readonly publicKey: Hex;
+    /**
+     * Configuration for passkey operations.
+     */
+    private readonly config;
+    /**
+     * Creates a new ReactNativePasskeySigner instance.
+     * Use the static `register` or `fromCredential` methods instead of calling this directly.
+     *
+     * @param credential - The passkey credential data
+     * @param config - Configuration for passkey operations
+     */
+    private constructor();
+    /**
+     * Registers a new passkey and returns a signer instance.
+     *
+     * This triggers the device's WebAuthn registration flow:
+     * 1. Shows a system prompt to create a new passkey
+     * 2. User authenticates with biometrics
+     * 3. Device generates a new P-256 key pair in the secure enclave
+     * 4. Returns the public key and credential ID
+     *
+     * @param username - The username for the passkey (displayed in system UI)
+     * @param config - Configuration for the passkey
+     * @returns A new ReactNativePasskeySigner instance
+     * @throws PasskeySignerError if registration fails
+     */
+    static register(username: string, config: ReactNativePasskeySignerConfig): Promise<ReactNativePasskeySigner>;
+    /**
+     * Creates a signer from an existing credential.
+     *
+     * Use this when you have previously registered a passkey and stored the credential data.
+     *
+     * @param credential - The stored credential data
+     * @param config - Configuration for passkey operations
+     * @returns A new ReactNativePasskeySigner instance
+     */
+    static fromCredential(credential: PasskeyCredential, config: ReactNativePasskeySignerConfig): ReactNativePasskeySigner;
+    /**
+     * Signs a message using the passkey.
+     *
+     * This triggers the device's biometric authentication prompt.
+     * The message can be a string or raw bytes (typically a UserOpHash).
+     *
+     * @param params - The message to sign
+     * @returns The encoded signature
+     * @throws PasskeySignerError if signing fails
+     */
+    signMessage({ message, }: {
+        message: SignableMessage;
+    }): Promise<Hex>;
+    /**
+     * Signs typed data according to EIP-712.
+     *
+     * @param typedData - The typed data to sign
+     * @returns The encoded signature
+     * @throws PasskeySignerError if signing fails
+     */
+    signTypedData<const TTypedData extends TypedData | Record<string, unknown>, TPrimaryType extends keyof TTypedData | "EIP712Domain" = keyof TTypedData>(typedData: TypedDataDefinition<TTypedData, TPrimaryType>): Promise<Hex>;
+    /**
+     * Returns the address derived from the public key.
+     *
+     * Note: P-256 keys don't directly map to Ethereum addresses.
+     * This returns a pseudo-address derived from the public key hash.
+     * The actual smart account address is determined by the account implementation.
+     *
+     * @returns A derived address (not a real EOA address)
+     */
+    getAddress(): Promise<Address>;
+    /**
+     * Returns the X coordinate of the public key.
+     */
+    getPublicKeyX(): Hex;
+    /**
+     * Returns the Y coordinate of the public key.
+     */
+    getPublicKeyY(): Hex;
+    /**
+     * Returns the full credential data for storage/restoration.
+     */
+    getCredential(): PasskeyCredential;
+    /**
+     * Sets the signature encoding format.
+     *
+     * @param format - The format to use for encoding signatures
+     * @returns A new signer instance with the updated format
+     */
+    withSignatureFormat(format: SignatureEncodingFormat): ReactNativePasskeySigner;
+    /**
+     * Internal method to sign a challenge with the passkey.
+     *
+     * @param challenge - The Base64URL-encoded challenge
+     * @returns The encoded signature
+     */
+    private signWithPasskey;
+    /**
+     * Converts a hex string to Uint8Array.
+     */
+    private hexToBytes;
+}
+/**
+ * Type guard to check if a value is a valid PasskeyCredential.
+ */
+export declare function isPasskeyCredential(value: unknown): value is PasskeyCredential;
+/**
+ * Serializes a PasskeyCredential to a JSON-safe object.
+ */
+export declare function serializeCredential(credential: PasskeyCredential): Record<string, string>;
+/**
+ * Deserializes a PasskeyCredential from a JSON object.
+ */
+export declare function deserializeCredential(data: Record<string, string>): PasskeyCredential;
+//# sourceMappingURL=signer.d.ts.map

package/dist/signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,GAAG,EACR,KAAK,SAAS,EACd,KAAK,mBAAmB,EAGzB,MAAM,MAAM,CAAC;AAEd,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,8BAA8B,EAC9B,eAAe,EACf,uBAAuB,EACxB,MAAM,kBAAkB,CAAC;AAe1B;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,KAAK,CAAC,EAAE,OAAO;gBAD/B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,wBAAyB,YAAW,kBAAkB,CAAC,SAAS,CAAC;IAC5E,SAAgB,MAAM,EAAG,SAAS,CAAU;IAE5C;;OAEG;IACH,SAAgB,YAAY,EAAE,MAAM,CAAC;IAErC;;OAEG;IACH,SAAgB,eAAe,EAAE,GAAG,CAAC;IAErC;;OAEG;IACH,SAAgB,oBAAoB,EAAE,aAAa,CAAC;IAEpD;;OAEG;IACH,SAAgB,SAAS,EAAE,GAAG,CAAC;IAE/B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IAExD;;;;;;OAMG;IACH,OAAO;IAgBP;;;;;;;;;;;;;OAaG;WACiB,QAAQ,CAC1B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,8BAA8B,GACrC,OAAO,CAAC,wBAAwB,CAAC;IA2FpC;;;;;;;;OAQG;WACW,cAAc,CAC1B,UAAU,EAAE,iBAAiB,EAC7B,MAAM,EAAE,8BAA8B,GACrC,wBAAwB;IAQ3B;;;;;;;;;OASG;IACU,WAAW,CAAC,EACvB,OAAO,GACR,EAAE;QACD,OAAO,EAAE,eAAe,CAAC;KAC1B,GAAG,OAAO,CAAC,GAAG,CAAC;IAmChB;;;;;;OAMG;IACU,aAAa,CACxB,KAAK,CAAC,UAAU,SAAS,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,YAAY,SAAS,MAAM,UAAU,GAAG,cAAc,GAAG,MAAM,UAAU,EACzE,SAAS,EAAE,mBAAmB,CAAC,UAAU,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAWzE;;;;;;;;OAQG;IACU,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAQ3C;;OAEG;IACI,aAAa,IAAI,GAAG;IAI3B;;OAEG;IACI,aAAa,IAAI,GAAG;IAI3B;;OAEG;IACI,aAAa,IAAI,iBAAiB;IASzC;;;;;OAKG;IACI,mBAAmB,CACxB,MAAM,EAAE,uBAAuB,GAC9B,wBAAwB;IAO3B;;;;;OAKG;YACW,eAAe;IAwC7B;;OAEG;IACH,OAAO,CAAC,UAAU;CAQnB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAkB5B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,iBAAiB,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3B,iBAAiB,CAoBnB"}