Unforgettable SDK

Secure, seedless wallet recovery for modern applications

Documentation • Website • Examples • Changelog

📖 Overview

The Unforgettable SDK is a comprehensive, multi-platform toolkit for implementing secure, seedless wallet recovery in your applications. It enables users to recover their private keys using biometric factors (face recognition, physical objects) and traditional methods (passwords) without storing sensitive data on servers.

Key Features

✨ Seedless Recovery - No mnemonics or seed phrases to manage
🔐 End-to-End Encryption - Client-side cryptography, zero-knowledge architecture
🎯 Multi-Factor Authentication - Combine face recognition, images, and passwords
📱 Cross-Platform - TypeScript/JavaScript, iOS (Swift), Android (Kotlin), React Native
🚀 Easy Integration - Simple APIs, React hooks, and native SDKs
🌐 Self-Sovereign - Users control their own recovery process

📦 Packages

The SDK is organized into platform-specific packages:

Package	Platform	Documentation
`@rarimo/unforgettable-sdk`	TypeScript/JavaScript (Core)	Docs
`@rarimo/unforgettable-sdk-react`	React Components	Docs
`com.github.rarimo.unforgettable-sdk:android`	Android (Kotlin)	Docs
`UnforgettableSDK`	iOS (Swift)	Docs

Package Features

Core SDK (TypeScript/JavaScript)

Works in browsers and Node.js environments
Cryptographic key generation and encryption
Recovery URL generation with embedded and custom parameters
Polling mechanism for recovery completion
TypeScript type definitions

React SDK

Pre-built QR code component (UnforgettableQrCode)
React hooks for recovery flow management
Automatic polling and state management
Customizable styling and error handling

Android SDK

Native Kotlin implementation
Coroutines support for async operations
WebView integration helpers
Comprehensive error types

iOS SDK

Native Swift implementation with Swift Package Manager
Async/await support
Combine framework integration
iOS 13+ support

🚀 Quick Start

Web/React

npm install @rarimo/unforgettable-sdk @rarimo/unforgettable-sdk-react
# or
yarn add @rarimo/unforgettable-sdk @rarimo/unforgettable-sdk-react

import UnforgettableQrCode from '@rarimo/unforgettable-sdk-react'
import { RecoveryFactor } from '@rarimo/unforgettable-sdk'

function App() {
  return (
    <UnforgettableQrCode
      mode="create"
      factors={[RecoveryFactor.Face, RecoveryFactor.Password]}
      onSuccess={(privateKey) => {
        console.log('Recovery key:', privateKey)
      }}
    />
  )
}

Android

repositories {
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.rarimo.unforgettable-sdk:android:1.0.0")
}

import com.rarimo.unforgettable.*

val sdk = UnforgettableSDK(
    UnforgettableSdkOptions(
        mode = UnforgettableMode.CREATE,
        factors = listOf(RecoveryFactor.FACE, RecoveryFactor.PASSWORD)
    )
)

val recoveryUrl = sdk.getRecoveryUrl()
val recoveredKey = sdk.getRecoveredKey() // suspending function

iOS

dependencies: [
    .package(url: "https://github.com/rarimo/unforgettable-sdk.git", from: "1.0.0")
]

import UnforgettableSDK

let sdk = try UnforgettableSDK(
    mode: .create,
    factors: [.face, .image, .password]
)

let recoveryUrl = try sdk.getRecoveryUrl()
let recoveredKey = try await sdk.getRecoveredKey()

💡 Examples

The repository includes comprehensive examples for each platform:

Web & Mobile

Platform	Description	Location	Live Demo
React	Web app with QR code component	`examples/react`
React Native	iOS & Android mobile app	`examples/react-native`	-
Android	Native Kotlin app with WebView	`examples/android`	-
iOS	Native Swift app	`examples/ios`	-

Each example demonstrates:

Creating new recovery setups
Restoring existing accounts
Factor selection and configuration
WebView/QR code integration
Automatic polling for recovery completion
Key display and management

🏗️ Architecture

The SDK follows a zero-knowledge architecture:

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│ Your App    │────────▶│ Unforgettable│◀────────│ User Device │
│ (SDK)       │         │ App (WebView)│         │ (Camera)    │
└─────────────┘         └──────────────┘         └─────────────┘
      │                        │
      │                        │
      ▼                        ▼
┌─────────────────────────────────────┐
│  Unforgettable API (Encrypted Data) │
│  • No private keys stored           │
│  • Only encrypted shards            │
│  • Cannot decrypt without factors   │
└─────────────────────────────────────┘

Key Generation: Client generates ephemeral key pairs
Encryption: Recovery data encrypted client-side
Storage: Only encrypted shards stored on API
Recovery: User provides only factors → decryption happens client-side
Zero-Knowledge: Server never sees private keys or decrypted data

🛠️ Development

Prerequisites

Node.js 18+ and Yarn 4.x
Java 17 (for Android development)
Xcode 14+ (for iOS development)
Gradle 8.1+ (for Android builds)

Setup

Clone the repository:

git clone https://github.com/rarimo/unforgettable-sdk.git
cd unforgettable-sdk

Install dependencies:
```
yarn install
```
Build all packages:
```
yarn build
```

Run tests:

yarn test              # All tests
yarn test:ts           # TypeScript/JavaScript tests
yarn test:swift        # iOS Swift tests
yarn test:kotlin       # Android Kotlin tests

Monorepo Structure

unforgettable-sdk/
├── packages/
│   ├── core/          # TypeScript/JavaScript SDK
│   ├── react/         # React components and hooks
│   ├── android/       # Android SDK (Kotlin)
│   └── ios/           # iOS SDK (Swift)
├── examples/
│   ├── react/         # React web example
│   ├── react-native/  # React Native mobile example
│   ├── android/       # Android example app
│   └── ios/           # iOS example app
└── scripts/           # Build and release scripts

Available Scripts

yarn build             # Build all packages
yarn lint              # Lint TypeScript code
yarn test              # Run all tests
yarn publish:stable    # Publish packages to NPM

🔧 Troubleshooting

Android: Java 17 Not Found

If you encounter this error:

Cannot find a Java installation on your machine matching: {languageVersion=17}

Solution (macOS):

# Install Java 17
brew install openjdk@17

# Link it
sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

# Verify
/usr/libexec/java_home -V

TypeScript Build Errors

# Clean and rebuild
yarn clean
yarn install
yarn build

iOS CocoaPods Issues

cd packages/ios
rm -rf Pods Podfile.lock
pod install

📚 Documentation

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow existing code style (ESLint for TypeScript, Ktlint for Kotlin, SwiftLint for Swift)
Add tests for new features
Update documentation
Ensure all tests pass (yarn test)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

🙏 Acknowledgments

Built with ❤️ by the Rarimo team and contributors.

Powered by:

@noble/curves - Cryptographic curves
@noble/ciphers - Encryption
@noble/hashes - Hash functions

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github/workflows		.github/workflows
.yarn/releases		.yarn/releases
examples		examples
images		images
packages		packages
scripts		scripts
.editorconfig		.editorconfig
.eslintrc.js		.eslintrc.js
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierrc		.prettierrc
.yarnrc.yml		.yarnrc.yml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
jest.config.base.js		jest.config.base.js
jest.config.js		jest.config.js
jitpack.yml		jitpack.yml
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

License

rarimo/unforgettable-sdk

Folders and files

Latest commit

History

Repository files navigation