# @algorandfoundation/dp256

> Package used to deterministically generate P256 keypairs, using BIP39.

Latest version **1.1.0** (published 2025-12-08) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @algorandfoundation/dp256
pnpm add @algorandfoundation/dp256
yarn add @algorandfoundation/dp256
bun add @algorandfoundation/dp256
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2025-12-08 |
| First published | 2025-09-22 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 43.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | Algorand Foundation |
| Maintainers | bruno.martins.algorand.foundation, dev_algorand.foundation, shane-at-algo, hmd2v, joe-p, bitd13co, krby |
| Keywords | p256, ecdsa, bip39, deterministic, cryptography, webauthn, passkeys |

## Links

- npm: https://www.npmjs.com/package/@algorandfoundation/dp256
- Repository: https://github.com/algorandfoundation/deterministic-p256-ts
- Homepage: https://github.com/algorandfoundation/deterministic-p256-ts#readme
- Issues: https://github.com/algorandfoundation/deterministic-p256-ts/issues
- npm.io page: https://npm.io/package/@algorandfoundation/dp256

## Dependencies (3)

- [@scure/bip39](https://npm.io/package/@scure/bip39.md) 1.6.0
- [@noble/curves](https://npm.io/package/@noble/curves.md) 1.9.6
- [@noble/hashes](https://npm.io/package/@noble/hashes.md) 1.8.0

## Alternatives

- [@gemini-wallet/core](https://npm.io/package/@gemini-wallet/core.md) — 515.6K weekly downloads
- [utility](https://npm.io/package/utility.md) — 416.6K weekly downloads
- [@primno/dpapi](https://npm.io/package/@primno/dpapi.md) — 7.2K weekly downloads
- [pi-readseek](https://npm.io/package/pi-readseek.md) — 3.7K weekly downloads
- [@emilia-protocol/verify](https://npm.io/package/@emilia-protocol/verify.md) — 1.1K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2025-12-08
- 1.0.1 — 2025-09-22
- 1.0.0 — 2025-09-22
- 0.0.1 — 2025-09-22

## README

# Deterministic P256 TypeScript

A TypeScript implementation for generating deterministic P-256 keypairs from BIP39 mnemonic phrases. This library enables the creation of reproducible cryptographic keypairs for WebAuthn/FIDO2 authentication across different devices.

## Features

- 🔐 Generate deterministic P-256 keypairs from BIP39 mnemonic phrases
- 🌐 Domain-specific key generation for WebAuthn/FIDO2 use cases
- 🔄 Cross-platform compatibility (equivalent to Swift and Kotlin implementations)
- 🧪 Comprehensive test coverage
- 📦 Modern TypeScript with full type support

## Installation

```bash
npm install @algorandfoundation/dp256
```

## Usage

### Basic Example

```typescript
import { DeterministicP256 } from '@algorandfoundation/dp256';

const dp256 = new DeterministicP256();

// Step 1: Generate derived main key from BIP39 phrase
const phrase =
  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
const derivedKey = await dp256.genDerivedMainKeyWithBIP39(phrase);

// Step 2: Generate domain-specific keypair
const privateKey = await dp256.genDomainSpecificKeyPair(
  derivedKey,
  'webauthn.example.com', // origin/domain
  'alice@example.com' // user handle
);

// Step 3: Get public key bytes
const publicKeyBytes = dp256.getPurePKBytes(privateKey);

// Step 4: Sign a payload
const payload = new TextEncoder().encode('authenticate user alice');
const signature = dp256.signWithDomainSpecificKeyPair(privateKey, payload);

console.log('Private key length:', privateKey.length); // 32 bytes
console.log('Public key length:', publicKeyBytes.length); // 64 bytes (X + Y coordinates)
console.log('Signature length:', signature.length); // 64 bytes
```

### Advanced Configuration

```typescript
// Custom salt and iteration count
const customDerivedKey = await dp256.genDerivedMainKeyWithBIP39(
  phrase,
  new TextEncoder().encode('custom-salt'), // custom salt
  100_000, // iteration count
  512 // key length in bits
);

// Multiple keypairs for same domain using counter
const keypair1 = await dp256.genDomainSpecificKeyPair(derivedKey, 'example.com', 'user', 0);
const keypair2 = await dp256.genDomainSpecificKeyPair(derivedKey, 'example.com', 'user', 1);
```

## API Reference

### `genDerivedMainKeyWithBIP39(phrase, salt?, iterationCount?, keyLength?)`

Generates a derived main key from a BIP39 mnemonic phrase using PBKDF2-HMAC-SHA512.

- **phrase**: BIP39 mnemonic phrase
- **salt**: Salt for key derivation (default: `"liquid"`)
- **iterationCount**: PBKDF2 iterations (default: `210_000`)
- **keyLength**: Key length in bits (default: `512`)

Returns: `Promise<Uint8Array>`

### `genDomainSpecificKeyPair(derivedMainKey, origin, userHandle, counter?)`

Generates a domain-specific P-256 private key.

- **derivedMainKey**: Output from `genDerivedMainKeyWithBIP39`
- **origin**: Domain/origin identifier
- **userHandle**: User identifier
- **counter**: Optional counter for multiple keys (default: `0`)

Returns: `Promise<Uint8Array>`

### `signWithDomainSpecificKeyPair(privateKey, payload)`

Signs a payload using the private key.

- **privateKey**: Private key from `genDomainSpecificKeyPair`
- **payload**: Data to sign

Returns: `Uint8Array` (64-byte signature)

### `getPurePKBytes(privateKey)`

Extracts the raw public key bytes from a private key.

- **privateKey**: Private key from `genDomainSpecificKeyPair`

Returns: `Uint8Array` (64-byte uncompressed public key coordinates)

## Security Considerations

- The BIP39 mnemonic phrase should be generated with sufficient entropy
- Store the derived main key securely and never expose the original mnemonic
- This library is designed for deterministic key generation across devices
- The PBKDF2 iteration count provides additional security hardening

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch
```

## License

Apache-2.0

## Compatibility

This implementation is equivalent to the Swift and Kotlin versions and produces identical keypairs for the same inputs across all platforms.

---
_Source: https://npm.io/package/@algorandfoundation/dp256 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
