@seedid/core

Core cryptographic SDK for SeedID identity management.

Installation

npm install @seedid/core

Features

• Idea-based Seed Generation: Generate deterministic seeds from memorable phrases using Argon2id KDF
• Multi-curve Key Derivation: Support for Ed25519 and secp256k1 key generation
• W3C DID Documents: Generate and serialize W3C-compliant Decentralized Identifiers
• Shamir Secret Sharing: 3-of-5 threshold secret sharing for Friend Scatter recovery
• Cloud Backup: AES-256-GCM encrypted backup with PIN-based key derivation
• HTTP Message Signatures: RFC 9421-compliant signatures for Mastodon integration
• Diceware Seeds: Generate cryptographically secure Diceware seed phrases

Quick Start

Provision an Agent Identity (canonical v1 contract)

The canonical agent-identity API for multi-machine brain identity (AgentBootup / AgentDispatch / PeerWeight consume this). See docs/AGENT-IDENTITY-CONTRACT.md.

import { provisionAgentIdentity, publicIdentityRecord } from '@seedid/core';

// master is the brain's master secret (caller-owned; store via Mech Vault, never in git)
const id = await provisionAgentIdentity(master, { tenantId: 'mech-dna', agentId: 'agent-5ad2f6d4' });
console.log(id.did);              // did:seed:<sha256(pubkey)[0:8] hex>
console.log(id.publicKeyMultibase);// base64 public key — safe for manifests/registry
// id.privateKey is CALLER-OWNED — route to Mech Vault, never write to git/bundles/logs

const record = publicIdentityRecord(id); // PUBLIC-ONLY: did + publicKey + derivation meta
// `record` is what you write to tracked manifests + register with AgentDispatch

Deterministic: the same (master, tenantId, agentId, version) always yields the same identity — a fresh brain with the same master seed obtains the same current identity (privacy-safe multi-machine identity). Rotate by bumping version; old signatures still verify cryptographically (revocation is a registry assertion).

Generate Seed from Idea

import { generateSeedFromIdea } from '@seedid/core';

// Generate master seed from memorable idea
const seed = await generateSeedFromIdea('my secret memorable phrase');
console.log(seed); // Hex-encoded master seed

Derive Identity Keys

import { deriveIdentityKey } from '@seedid/core';

// Derive Ed25519 keypair for email domain
const emailKey = await deriveIdentityKey(
  seed, 
  'seedid:email:example.com:ed25519',
  'ed25519'
);

console.log(emailKey.publicKey); // Uint8Array(32)
console.log(emailKey.privateKey); // Uint8Array(32)

Generate DID Document

import { generateDID } from '@seedid/core';

const did = await generateDID(emailKey.publicKey);
console.log(did); // did:seed:a1b2c3d4...

Friend Scatter (Shamir Secret Sharing)

import { splitSecret, combineShares, generateQRCode } from '@seedid/core';

// Split seed into 5 shares (need any 3 to recover)
const shares = splitSecret(seed, 5, 3);

// Generate QR codes for sharing
for (const share of shares) {
  const qrCode = await generateQRCode(share);
  console.log(qrCode); // Data URL for QR code image
}

// Recover seed from any 3 shares
const recovered = combineShares([shares[0], shares[2], shares[4]]);
console.log(recovered === seed); // true

Cloud Scramble (Encrypted Backup)

import { encryptSeed, decryptSeed } from '@seedid/core';

// Encrypt seed with PIN
const backup = await encryptSeed(seed, '123456');
console.log(backup.ciphertext); // Base64-encoded encrypted data

// Decrypt with correct PIN
const decrypted = await decryptSeed(backup, '123456');
console.log(decrypted === seed); // true

Diceware Seed Phrase

import { generateSeed, validateSeed } from '@seedid/core';

// Generate 12-word Diceware seed
const seedPhrase = generateSeed(12);
console.log(seedPhrase); // "correct horse battery staple..."

// Validate seed phrase
const isValid = validateSeed(seedPhrase);
console.log(isValid); // true

Security Considerations

Argon2id Parameters

The SDK uses Argon2id for key derivation with the following parameters:

• Memory Cost: 256 MiB (262144 KiB)
• Time Cost: 5 iterations
• Parallelism: 2 threads
• Output Length: 32 bytes

These parameters provide strong resistance against brute-force and side-channel attacks while remaining performant on modern hardware.

Deterministic Derivation

All cryptographic operations are deterministic from the master seed. Given the same seed and context, you will always derive the same keys. This enables:

• Backup-free recovery: Recover all identities from a single seed
• Cross-device sync: Same identity on multiple devices
• Predictable testing: Reproducible results for test vectors

Memory Zeroing

Sensitive data (private keys, intermediate key material) is zeroed from memory after use to prevent:

• Memory dumps from exposing secrets
• Swap file leakage
• Cold boot attacks
• Process inspection

Offline Operation

The SDK operates entirely offline with no external API calls. All cryptographic operations use:

• Web Crypto API (browser and Node.js 18+)
• WASM-based hash-wasm for Argon2id
• Pure JavaScript implementations from @noble/* libraries

API Reference

Seed Generation

• generateSeed(wordCount?: number): string - Generate Diceware seed phrase
• validateSeed(seed: string): boolean - Validate Diceware seed
• generateSeedFromIdea(idea: string, opts?): Promise<string> - Generate seed from idea

Key Derivation

• deriveIdentityKey(seed, context, curve): Promise<KeyPair> - Derive identity keypair
• generateEd25519KeyPair(privateKey): KeyPair - Generate Ed25519 keypair
• generateSecp256k1KeyPair(privateKey): Secp256k1KeyPair - Generate secp256k1 keypair

DID Management

• generateDID(publicKey): Promise<string> - Generate DID from public key
• createDidDocument(did, publicKey): DidDocument - Create W3C DID document

Recovery Mechanisms

• splitSecret(secret, n?, k?): string[] - Split secret with Shamir (default 3-of-5)
• combineShares(shares): string - Recover secret from shares
• generateQRCode(data): Promise<string> - Generate QR code for sharing

Backup & Encryption

• encryptSeed(seed, pin): Promise<BackupPayload> - Encrypt seed with PIN
• decryptSeed(backup, pin): Promise<string> - Decrypt seed with PIN
• deriveBackupKey(pin, salt?): Promise<Uint8Array> - Derive encryption key from PIN

HTTP Signatures (Mastodon)

• signRequest(privateKey, request): Promise<string> - Sign HTTP request
• verifySignature(publicKey, request, signature): Promise<boolean> - Verify signature

TypeScript Support

The SDK is written in TypeScript and provides full type definitions.

import type { KeyPair, Secp256k1KeyPair, DidDocument, BackupPayload } from '@seedid/core';

Platform Support

• Node.js: 18.0.0 or higher (requires Web Crypto API)
• Browsers: Modern browsers with Web Crypto API support. Import from @seedid/core/web for the dedicated browser barrel — the full browser-safe surface (includes idea-seed, keys, DID, signatures, KDF + forAgentDispatch, cloud-backup, storage abstractions + MockSecureStorage, pipeline, mastodon); excludes only Shamir (which needs Node's createRequire). A Buffer polyfill is required (encoding.ts uses Buffer for base64 — Vite: vite-plugin-node-polyfills; webpack: node polyfill plugins). forAgentDispatch is HKDF-only (no Argon2id) and main-thread-safe; deriveMasterKey/deriveIdentityKey use Argon2id (256 MiB) and should run in a Web Worker. TypeScript note: prefer @seedid/core/web over the bare @seedid/core — the bare package's browser export condition resolves correctly at runtime, but TypeScript does not auto-select the browser condition for type resolution, so importing the bare package in a browser app can type-check Node-only APIs (e.g. splitSecret) that then fail at bundle time. /web resolves unconditionally, so types and runtime stay in sync.
• React Native: Requires react-native-quick-crypto polyfill (see docs)
• Electron: Supported out of the box

Performance

Typical performance on modern hardware (2023+ laptop):

• Seed generation (Argon2id): ~2-5 seconds
• Key derivation (HKDF): <1ms
• Ed25519 keypair generation: <1ms
• secp256k1 keypair generation: ~2-5ms
• Shamir split/combine: ~10-50ms
• Cloud backup encryption: <10ms

Note: Argon2id is intentionally slow to resist brute-force attacks. Performance varies based on available CPU cores and memory.

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Lint
npm run lint

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

MIT

Security

For security issues, please email [email protected] instead of using the public issue tracker.