@ident-agency/core

Core SDK for Ident.Agency - a user-controlled identity and metadata vault where individuals own and control their encrypted data fragments.

What is Ident.Agency?

Ident.Agency is a privacy-preserving identity vault that enables users to:

• Store personal data ("fragments") at path-based locations
• Keep data encrypted with keys that never leave the client
• Share specific data with applications through granular consent
• Maintain a single identity across multiple applications

Key Features

• 🔐 Client-side encryption - All encryption/decryption happens locally
• 🔑 Multiple unlock methods - Passkeys (WebAuthn), passwords, recovery phrases
• 🌐 OAuth2/PKCE authentication - Standards-based secure authentication
• 📁 Fragment storage - Path-based data storage (e.g., /identity/name, /wallet/xrpl)
• 🎯 Two-tier encryption - User KEK wraps per-fragment DEKs for efficient key rotation
• 🚫 Zero-knowledge server - Server never sees plaintext data or keys

Installation

npm install @ident-agency/core

Quick Start

import { IdentClient, PasswordProvider, DeviceKeyProvider } from '@ident-agency/core';

// Initialize providers for authentication
const passwordProvider = new PasswordProvider('my-secure-password');
const deviceKeyProvider = new DeviceKeyProvider();

// Initialize the client
const client = await IdentClient.create({
	clientId: 'your-app-id',
	redirectUri: window.location.origin,
	apiBaseUrl: 'https://www.ident.agency',
	scopes: ['read', 'write'],
	passwordProvider,
	deviceKeyProvider,
	debug: true
});

// Authenticate and ensure we have a subject
await client.ensureSubject();

// Write an encrypted fragment
await client.put('/identity/bio', { text: 'Software developer' });

// Read and auto-decrypt a fragment
const bio = await client.get('/identity/bio');
console.log(bio); // { text: 'Software developer' }

// List fragments at a path
const identityItems = await client.list('/identity/');
console.log(identityItems); // Array of fragments under /identity/

// Delete a fragment
await client.del('/identity/bio');

API Reference

Core Methods

Client Initialization

import { IdentClient, PasswordProvider, DeviceKeyProvider } from '@ident-agency/core';

const passwordProvider = new PasswordProvider('secure-password');
const deviceKeyProvider = new DeviceKeyProvider();

const client = await IdentClient.create({
	clientId: 'your-app-id',
	redirectUri: window.location.origin,
	apiBaseUrl: 'https://www.ident.agency',
	scopes: ['read', 'write'],
	passwordProvider,
	deviceKeyProvider
});

Authentication & Unlock

// Authenticate and get current subject
const subject = await client.ensureSubject();

// Check if vault is locked
if (client.isLocked()) {
	// Unlock with passkey
	await client.unlockWithPasskey();

	// Or unlock with password
	await client.unlockWithPassword('my-password');

	// Or unlock with recovery phrase
	await client.unlockWithRecoveryPhrase('word1 word2 ...');
}

// Check authentication status
const context = client.getContext();
console.log(context.authenticated); // true/false

Fragment Operations

// Write a fragment (automatically encrypted)
await client.put('/identity/name', { first: 'Alice', last: 'Smith' });

// Read a fragment (automatically decrypted)
const name = await client.get('/identity/name');

// List fragments at a path
const items = await client.list('/identity/', { limit: 10 });

// Delete a fragment
await client.del('/identity/name');

Architecture

The SDK operates on a two-tier encryption model:

1. User KEK (Key Encryption Key): Derived from the user's root seed, used to wrap fragment DEKs
2. Fragment DEKs (Data Encryption Keys): Unique per fragment, used for actual data encryption

This design allows efficient key rotation and selective data access without re-encrypting all fragments.

Security Considerations

• All cryptographic operations happen client-side using WebCrypto API
• The server stores only encrypted data and metadata
• Private keys and plaintext never leave the client
• OAuth2 PKCE flow prevents authorization code interception
• Per-fragment encryption allows granular access control

Browser Requirements

• WebCrypto API
• localStorage
• fetch API
• ES2020+ JavaScript features

Browser Compatibility

The @ident-agency/core package is designed to work in both browser and Node.js environments:

Browser Usage

• SSH key operations are not available in browser environments
• The package will automatically exclude Node-only dependencies when bundled for the browser
• All other functionality (OAuth, encryption, fragment operations) works normally

Node.js Usage

• Full functionality including SSH key operations
• SSH key support requires the optional sshpk dependency

Bundler Configuration

The package uses conditional imports that are handled automatically by modern bundlers like Vite, webpack, and Rollup. No special configuration is required.

License

MIT

Support

• Issues: GitHub Issues
• Documentation: Ident.Agency Docs