npm package: @ident-agency/core
Description: Core Ident Agency SDK for secure, privacy-preserving access to user-controlled identity and data fragments
Author: Lorem Labs
Latest version: 0.0.10

# @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

```bash
npm install @ident-agency/core
```

## Quick Start

```typescript
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

```typescript
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

```typescript
// 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

```typescript
// 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](https://github.com/loremlabs/ident-agency-sdk/issues)
- Documentation: [Ident.Agency Docs](https://www.ident.agency)