@algorandfoundation/keystore

Core types and reactive state management for the Algorand Wallet Provider Keystore.

This package provides the base interfaces and reactive store for managing cryptographic keys. It does not contain a concrete implementation of key storage or cryptographic operations.

Why This Exists

By separating the store and types from the implementation, we enable:

• Environment Specific Implementations: Use specialized extensions for different contexts (e.g., React Native, Browser Extension, Cloud KMS) that all fulfill the same contract.
• Type Safety: Unified interfaces for all keystore-related operations, including arbitrary data signing and HD derivation.
• Reactive State: Built-in state management using @tanstack/store for UI-safe key metadata.

Core Components

• KeyStoreAPI: The main interface that all backends must implement.
• keyStore: A reactive store for managing key metadata and operation status.
• KeyStoreExtension: The interface exposed when added to a Wallet Provider.

Implementation Examples

If you are looking for a concrete implementation, please refer to:

• @algorandfoundation/keystore-react-native - React Native implementation using secure hardware.

Quick Start

1. Define a Backend

To use the store, you typically use a concrete implementation that implements the KeyStoreAPI:

import { KeyStoreAPI } from "@algorandfoundation/keystore/types";

class MyBackend implements KeyStoreAPI {
  // Implement required methods: generate, import, sign, etc.
}

2. Subscribe to State Changes

The store provides a reactive way to track available keys and the current operation status:

import { keyStore } from "@algorandfoundation/keystore";

keyStore.subscribe((state) => {
  console.log("Current keys:", state.keys);
  console.log("Status:", state.status);
});

API Documentation

For detailed information on types and methods, see the TypeDocs.

Key Interfaces

• KeyStoreAPI: Main interface for cryptographic operations.
• KeyStoreState: Reactive state structure.
• Key: Metadata for a single key.

Security

The store is designed to be UI-safe. It only holds metadata and public identifiers. Private key material should never be stored in the reactive keyStore and should remain isolated within the backend implementation.

License

Apache-2.0