ns-auth-sdk 1.12.6 → 1.13.0

package/README.md

@@ -55,7 +55,7 @@ import { EventStore } from 'ns-auth-sdk';
 const authService = new AuthService({
   rpId: 'your-domain.com',
   rpName: 'Your App Name',
-  storageKey: 'nsauth_keyinfo',
+  storageKey: 'identity',
   cacheOnCreation: true, // Enable early caching (default: true)
 });
 
@@ -124,9 +124,15 @@ const signedEvent = await authService.signEvent(event);
 - `addPasswordRecovery(password: string): Promise<KeyInfo>` - Add password recovery to an existing PRF key
 - `activateWithPassword(password: string, newCredentialId: Uint8Array): Promise<KeyInfo>` - Recover using password with a new passkey credential ID from a new device
 - `getRecoveryForKind0(): RecoveryData | null` - Get recovery data for publishing to kind-0
+- `publishRecoveryToKind0(relayService: RelayService, content?: string): Promise<boolean>` - Publish recovery data to a kind-0 event, preserving existing content and tags
 - `parseRecoveryTag(tags: string[][]): KeyRecovery | null` - Parse recovery tag from event
 - `verifyRecoverySignature(kind0: Event): Promise<boolean>` - Verify recovery signature (async)
 
+#### RelayService Methods
+
+- `fetchKind0Event(pubkey: string): Promise<{ content: string; tags: string[][] } | null>` - Fetch the full kind-0 event (content + tags)
+- `publishRecoveryToKind0(pubkey: string, recoveryData: RecoveryData, signEvent: (event: Event) => Promise<Event>, content?: string): Promise<boolean>` - Publish or update kind-0 with recovery data, preserving existing content and tags
+
 #### KeyOptions
 
 ```typescript
@@ -191,6 +197,29 @@ const keyInfo = await authService.createKey(credentialId, undefined, {
 // ["r", recoveryPubkey, recoverySalt, createdAt, signature]
 ```
 
+**Publishing recovery data to relays:**
+
+The recovery data must be published to a kind-0 event so it can be fetched on a new device. The SDK preserves all existing profile content and tags, only amending the recovery "r" tag:
+
+```typescript
+import { RelayService } from 'ns-auth-sdk';
+
+const relayService = new RelayService({
+  relayUrls: ['wss://relay.io'],
+});
+relayService.initialize(eventStore);
+
+// Publish recovery data — existing kind-0 content and tags are preserved
+await authService.publishRecoveryToKind0(relayService);
+
+// Or provide custom content instead of fetching the existing kind-0
+await authService.publishRecoveryToKind0(relayService, JSON.stringify({
+  name: 'My Name',
+  about: 'My bio',
+  picture: 'https://example.com/avatar.jpg',
+}));
+```
+
 **Recovery on a new device:**
 
 ```typescript
@@ -218,6 +247,41 @@ if (isValid) {
 }
 ```
 
+### Cross-Origin Identity
+
+The SDK stores KeyInfo in `localStorage` by default. For cross-origin scenarios (e.g., multiple websites sharing the same identity), use the [Storage Access API](https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API):
+
+```typescript
+// Identity provider hosted at identity.example.com
+// All sites embed: <iframe src="https://identity.example.com/auth">
+
+// Inside the iframe, request storage access:
+if (document.hasStorageAccess) {
+  await document.requestStorageAccess();
+}
+
+// Now localStorage is shared across all sites embedding the iframe
+const authService = new AuthService({
+  rpId: 'identity.org.com',  // Shared rpId for all sites
+  rpName: 'org',
+});
+
+// Create or load identity — same keyInfo across all embedding sites
+const keyInfo = authService.getCurrentKeyInfo();
+```
+
+**How it works:**
+
+1. Host the identity provider on a single origin (e.g., `identity.org.com`)
+2. All sites embed it as an iframe: `<iframe src="https://identity.org.com/auth">`
+3. The iframe calls `document.requestStorageAccess()` to access its first-party storage
+4. The passkey uses the shared `rpId` (`identity.org.com`), so all sites derive the same key
+5. KeyInfo in `localStorage` is shared across all embedding sites
+
+**Browser support:** Storage Access API is supported in all major browsers (Chrome, Firefox, Safari, Edge).
+
+**Security note:** The user will see a permission prompt the first time a site requests storage access. After granting, access is remembered for that site.
+
 #### Configuration Options
 
 ```typescript
@@ -309,3 +373,1027 @@ const event = finalizeEvent({
 - Add rate limiting or debouncing around profile queries and event publishing in the host app or API layer.
 - Avoid surfacing raw error details to end users; log detailed errors in secure logs.
 
+## Multisig (Threshold Signing)
+
+The SDK supports M-of-N threshold signing via [FROST](https://eprint.iacr.org/2020/852) (Flexible Round-Optimized Schnorr Threshold signatures). This enables organizations to require multiple members to collaborate on signing — no single person can act alone.
+
+The resulting signatures are standard BIP-340 Schnorr signatures, indistinguishable from single-signer signatures. Your `pubkey` never changes.
+
+### How It Works
+
+1. **Admin** creates an identity and enables multisig — the passkey-derived secret is split into N shares
+2. **Admin distributes** share credentials to members (via QR code, encrypted message, etc.)
+3. **Members** import their share into their own identity
+4. **Signing** requires M-of-N members to coordinate via Nostr relays
+
+Share credentials are encrypted with the identity's secret (PRF or password-derived) before storage in localStorage. The plaintext share is never persisted.
+
+### Installation
+
+Multisig requires peer dependencies:
+
+```bash
+npm install ns-auth-sdk @frostr/bifrost @frostr/igloo-core
+```
+
+### Setup Flow (Org Admin)
+
+```typescript
+import { AuthService } from 'ns-auth-sdk';
+
+const adminAuth = new AuthService({
+  rpId: 'org.com',
+  rpName: 'org',
+});
+
+// 1. Create the org identity
+const credentialId = await adminAuth.createPasskey('alice@org.com');
+const keyInfo = await adminAuth.createKey(credentialId);
+adminAuth.setCurrentKeyInfo(keyInfo);
+
+// 2. Enable multisig: 2-of-3 threshold
+const { groupCredential, shareCredential } = await adminAuth.enableMultisig({
+  threshold: 2,
+  totalMembers: 3,
+  relays: ['wss://relay.io'],
+});
+
+// 3. Distribute shares to members
+// allShareCredentials[0] → admin (stored encrypted in their localStorage)
+// allShareCredentials[1] → member B
+// allShareCredentials[2] → member C
+```
+
+### Import Flow (Members)
+
+```typescript
+const memberAuth = new AuthService({
+  rpId: 'org.com',
+  rpName: 'org',
+});
+
+// Member creates their own passkey (for local auth)
+const credentialId = await memberAuth.createPasskey('member@org.com');
+const keyInfo = await memberAuth.createKey(credentialId);
+memberAuth.setCurrentKeyInfo(keyInfo);
+
+// Member imports their MultiSig share (received from admin)
+await memberAuth.importMultisigShare({
+  groupCredential: 'bfgroup1...',
+  shareCredential: 'bfshare1...',
+  relays: ['wss://relay.io'],
+});
+
+// The share is encrypted with the member's passkey-derived secret and stored
+```
+
+### Signing
+
+```typescript
+// Default: auto-detects mode (multisig if configured, individual otherwise)
+const signed = await memberAuth.signEvent(event);
+
+// Force individual signing (personal actions, no peer coordination needed)
+const personal = await memberAuth.signEvent(event, { mode: 'individual' });
+
+// Force multisig (org actions, requires threshold approval)
+const org = await memberAuth.signEvent(event, { mode: 'multisig' });
+
+// Password-protected identity: provide password to decrypt the share
+const signed = await memberAuth.signEvent(event, {
+  mode: 'multisig',
+  password: 'my-password',
+});
+```
+
+### Multisig API Reference
+
+#### AuthService Methods
+
+- `enableMultisig(options: MultisigSetupOptions): Promise<MultisigSetupResult>` — Split the identity's secret into shares, encrypt the local share, and store config
+- `isMultisig(): boolean` — Check if multisig is enabled on the current identity
+- `getMultisigConfig(): MultisigConfig | null` — Get the public multisig configuration
+- `getPeerStatus(): Promise<PeerInfo[]>` — Check which group members are online
+- `rotateShares(newThreshold?: number, newTotal?: number): Promise<string[]>` — Generate a new keyset, invalidating old shares
+- `importMultisigShare(options: MultisigImportOptions): Promise<KeyInfo>` — Import a share credential into an existing identity
+
+#### Types
+
+```typescript
+interface MultisigSetupOptions {
+  threshold: number;      // M: minimum signers required
+  totalMembers: number;   // N: total shares
+  relays: string[];       // Nostr relays for coordination
+  members?: MultisigMember[];    // Optional: members to invite via Welcome messages
+  groupManager?: GroupManager;   // Optional: required if members are provided
+}
+
+interface MultisigMember {
+  pubkey: string;                    // Member's Nostr pubkey
+  keyPackageEvent?: any;            // Member's key package event (kind 443)
+}
+
+interface MultisigSetupResult {
+  keyInfo: KeyInfo;
+  groupCredential: string;       // bfgroup1...
+  shareCredential: string;        // bfshare1... (this member's share)
+  membersInvited: number;         // number of members invited via Welcome messages
+}
+
+interface MultisigImportOptions {
+  groupCredential: string;
+  shareCredential: string;
+  relays: string[];
+}
+
+interface MultisigConfig {
+  threshold: number;
+  totalMembers: number;
+  relays: string[];
+  groupCredential: string;
+  shareCredential: string;
+  shareIndex: number;
+}
+
+interface PeerInfo {
+  pubkey: string;
+  status: 'online' | 'offline' | 'unknown';
+  latency?: number;
+}
+
+type SigningMode = 'individual' | 'multisig';
+
+interface SignOptions {
+  mode?: SigningMode;
+  clearMemory?: boolean;
+  tags?: string[][];
+  password?: string;
+}
+```
+
+### Share Rotation
+
+If a share is compromised or a member leaves, rotate the shares:
+
+```typescript
+// Generate new shares (same threshold and member count)
+const newShares = await adminAuth.rotateShares();
+
+// Or change the threshold
+const newShares = await adminAuth.rotateShares(3, 5); // 3-of-5
+
+// Distribute new shares to members — old shares are now invalid
+```
+
+## Group Messaging
+
+The SDK integrates an end-to-end encrypted group messaging protocol. This provides the coordination layer for multisig groups and general encrypted communication.
+
+### Architecture
+
+```
+Organization
+
+MultiSig (2-of-3 directors)           Group (all employees)
+├── Alice (director) ◄──────────────► ├── Alice (director)
+├── Bob (director)   ◄──────────────► ├── Bob (director)
+└── Carol (director) ◄──────────────► ├── Carol (director)
+                                      ├── Dave (engineer)
+                                      └── Eve (designer)
+```
+
+- **MultiSig** = signing authority (directors only, threshold-based)
+- **Group** = encrypted communication (everyone, read/write)
+
+### Installation
+
+```bash
+npm install ns-auth-sdk @internet-privacy/marmot-ts
+```
+
+### Quick Start
+
+```typescript
+import { AuthService, GroupManager, RelayService, EventStore } from 'ns-auth-sdk';
+
+// 1. Initialize services
+const authService = new AuthService({ rpId: 'org.com', rpName: 'org' });
+const relayService = new RelayService({ relayUrls: ['wss://relay.io'] });
+const eventStore = new EventStore(/* config */);
+relayService.initialize(eventStore);
+
+// 2. Create identity
+const credentialId = await authService.createPasskey('alice@org.com');
+await authService.createKey(credentialId);
+
+// 3. Initialize group manager (relays are required)
+const groupManager = new GroupManager({
+  signer: authService,
+  network: relayService,
+  relays: ['wss://relay.io'],
+});
+await groupManager.initialize();
+
+// 4. Start the event ingestion pipeline (required for receiving messages)
+await groupManager.start();
+
+// 5. Subscribe to incoming messages
+groupManager.onMessage((message) => {
+  console.log(`${message.senderPubkey}: ${message.content}`);
+});
+
+// 6. Create a group
+const group = await groupManager.createGroup('org', {
+  description: 'Company-wide encrypted communication',
+  adminPubkeys: ['alice-pubkey-hex'],
+  relays: ['wss://relay.io'],
+});
+
+// 7. Invite a member
+await groupManager.inviteMember(group, 'bob-pubkey-hex');
+
+// 8. Send a message
+await groupManager.sendMessage(group, 'Hello team!');
+```
+
+### Share Distribution via Welcome Messages
+
+Share credentials are sent as part of the group's encrypted Welcome message — **only the recipient can decrypt them**, even if other employees are in the same group:
+
+You can use the `members` and `groupManager` options to automatically distribute shares via Welcome messages:
+
+```typescript
+// Admin enables multisig with Welcome-based share distribution
+const { groupCredential, membersInvited } = await adminAuth.enableMultisig({
+  threshold: 2,
+  totalMembers: 3,
+  relays: ['wss://relay.io'],
+  members: [
+    { pubkey: 'bob-pubkey-hex', keyPackageEvent: bobKeyPackage },
+    { pubkey: 'carol-pubkey-hex', keyPackageEvent: carolKeyPackage },
+  ],
+  groupManager,
+});
+
+// Members automatically receive their shares via Welcome messages
+// membersInvited = 2
+```
+
+Or manually send shares after creating a group:
+
+```typescript
+// Admin creates a group
+const group = await groupManager.createGroup('org Directors', {
+  adminPubkeys: [adminPubkey],
+  relays: ['wss://relay.io'],
+});
+
+// Manually invite member and send their share via encrypted Welcome
+await groupManager.inviteMember(group, 'bob-pubkey-hex');
+await groupManager.sendShareToMember(
+  group,
+  'bob-pubkey-hex',
+  shareCredential,  // Use shareCredential from enableMultisig result
+  groupCredential,
+  ['wss://relay.io']
+);
+
+// Bob receives the Welcome message, decrypts it, and imports the share
+const welcomeRumor = /* decrypted NIP-59 gift wrap */;
+const joinedGroup = await groupManager.joinGroupFromWelcome(welcomeRumor);
+
+// Parse the share message from the group
+groupManager.onMessage((message) => {
+  const share = groupManager.parseGroupMessage(message);
+  if (share?.type === 'share-credential') {
+    memberAuth.importMultisigShare({
+      groupCredential: share.groupCredential,
+      shareCredential: share.shareCredential,
+      relays: share.relays,
+    });
+  }
+});
+```
+
+### Coordination Helpers
+
+The SDK provides utilities for structured group messages:
+
+```typescript
+import { createSigningRequest, parseSigningRequest, createShareMessage, parseShareMessage } from 'ns-auth-sdk';
+
+// Send a signing request to the group
+const request = createSigningRequest('doc-42', 'Update Document');
+await groupManager.sendMessage(group, request);
+
+// Parse incoming messages
+groupManager.onMessage((message) => {
+  const signingRequest = groupManager.parseGroupMessage(message);
+  if (signingRequest?.type === 'signing-request') {
+    console.log(`Signing requested: ${signingRequest.description}`);
+    // Trigger MultiSig signing flow
+  }
+
+  if (signingRequest?.type === 'share-credential') {
+    console.log('Share credential received');
+    // Import the share
+  }
+});
+```
+
+### Invite Processing
+
+When a member is invited to a group, they receive a GiftWrap (kind 1059) containing a Welcome message. The `GroupManager` automatically syncs invites from relays. After the user interacts (triggering decryption), call `processInvites()`:
+
+```typescript
+// Start begins automatic invite sync from relays
+await groupManager.start();
+
+// After user interaction (e.g., clicking "Check Invites"), decrypt and process
+await groupManager.processInvites();
+// This auto-joins groups from Welcome messages
+```
+
+### Unread Management
+
+The `GroupManager` tracks unread state per group, persisted to IndexedDB:
+
+```typescript
+// React to unread changes
+groupManager.unreadGroupIds$.subscribe((unreadIds) => {
+  console.log('Unread groups:', unreadIds);
+});
+
+// Mark a group as read when user opens it
+await groupManager.markGroupSeen(groupIdHex);
+```
+
+### Group Messaging API Reference
+
+#### GroupManager Methods
+
+- `constructor(options: { signer: any; network: any; relays: string[]; dbName?: string })` — Create a GroupManager (relays are required, no fallback)
+- `initialize(): Promise<void>` — Initialize with IndexedDB storage backends
+- `start(): Promise<void>` — Start the full pipeline: ingestion, invite sync, key package tracking (required for receiving messages)
+- `stop(): void` — Stop all pipelines and clean up subscriptions
+- `createGroup(name: string, options?: CreateGroupOptions): Promise<Group>` — Create a new MLS group (auto-calls selfUpdate for forward secrecy)
+- `joinGroupFromWelcome(welcomeRumor: Event): Promise<Group>` — Join a group from a Welcome message (auto-calls selfUpdate)
+- `inviteMember(group: Group, memberPubkey: string): Promise<void>` — Invite a member via key package
+- `sendMessage(group: Group, content: string, kind?: number): Promise<void>` — Send an encrypted message
+- `sendShareToMember(group: Group, memberPubkey: string, shareCredential: string, groupCredential: string, relays: string[]): Promise<void>` — Send a share credential to a member
+- `onMessage(handler: (msg: GroupMessage) => void): () => void` — Subscribe to all group messages (returns unsubscribe function)
+- `parseGroupMessage(message: GroupMessage): ShareCredentialMessage | SigningRequest | null` — Parse structured messages
+- `getGroups(): Promise<Group[]>` — List all loaded groups
+- `leaveGroup(groupId: Uint8Array | string): Promise<void>` — Leave a group
+- `destroyGroup(groupId: Uint8Array | string): Promise<void>` — Destroy a group and purge local data
+- `close(): void` — Alias for stop()
+- `markGroupSeen(groupIdHex: string, seenAt?: number): Promise<void>` — Mark a group as read
+- `processInvites(): Promise<void>` — Decrypt pending gift wraps and auto-join groups from Welcome messages
+- `getInviteReader(): InviteReader` — Get the underlying InviteReader for advanced invite handling
+- `unreadGroupIds$: BehaviorSubject<string[]>` — Observable of unread group IDs (persisted across page reloads)
+
+#### Default Storage Backends
+
+- `IndexedDBGroupStateBackend` — Default IndexedDB backend for group state (stores MLS group bytes)
+- `IndexedDBKeyPackageStore` — Default IndexedDB backend for key packages (stores kind-443 key material)
+- `IndexedDBKeyValueBackend` — Generic key-value store backend for InviteStore and other needs
+
+All use a unified IndexedDB database (default: `group`) with no external dependencies. Custom backends can be provided via the `GroupManager` constructor.
+
+#### Coordination Helpers
+
+- `createSigningRequest(eventId: string, description: string): string` — Create a signing request message
+- `parseSigningRequest(message: GroupMessage): SigningRequest | null` — Parse a signing request
+- `createShareMessage(shareCredential: string, groupCredential: string, relays: string[]): string` — Create a share credential message
+- `parseShareMessage(message: GroupMessage): ShareCredentialMessage | null` — Parse a share credential message
+
+## Root of Trust
+
+The SDK supports optional "root of trust" verification through multiple credential types. This enables cryptographic verification of identity - both individual and organizational.
+
+### Architecture
+
+```
+VerificationStatus
+├── verified: boolean        // true = any trust established
+├── individual: {
+│   ├── eudi?: EUDIClaims    // EUDI Wallet PID
+│   └── zkp?: ZKPClaims      // ZKPassport (zero-knowledge)
+└── organization: {
+    ├── vlei?: RootOfTrustInfo     // vLEI credentials
+    └── eudiLegal?: EUDILegalClaims // EUDI Legal PID
+}
+```
+
+Two separate services handle verification:
+- `IndividualTrustService` - EUDI PID + ZKPassport
+- `OrganizationTrustService` - vLEI + EUDI Legal PID
+
+### Installation
+
+Root of trust is optional. Install only what you need:
+
+```bash
+# Individual verification
+npm install ns-auth-sdk jose           # EUDI
+npm install ns-auth-sdk @zkpassport/sdk # ZKPassport
+
+# Organization verification
+npm install ns-auth-sdk @global-vlei/signify-ts # vLEI
+```
+
+### Quick Start
+
+```typescript
+import { 
+  IndividualTrustService, 
+  OrganizationTrustService,
+  RelayService 
+} from 'ns-auth-sdk';
+
+// Create services
+const individualTrust = new IndividualTrustService();
+const organizationTrust = new OrganizationTrustService();
+const relayService = new RelayService({ relayUrls: ['wss://relay.io'] });
+```
+
+## Individual Trust (EUDI + ZKPassport)
+
+### EUDI Wallet (PID)
+
+EUDI provides cryptographic verification of individual identity through the European Digital Identity Wallet.
+
+```typescript
+import { IndividualTrustService } from 'ns-auth-sdk';
+
+const individualTrust = new IndividualTrustService();
+
+// Connect to EUDI verifier (e.g., walt.id)
+await individualTrust.connectEUDI({
+  url: 'https://verifier.example.com',
+  clientId: 'your-client-id',
+});
+
+// Verify EUDI credentials
+const claims = await individualTrust.verifyEUDI();
+// { holderDID, givenName, familyName, dateOfBirth, nationality, verifiedAt, expiresAt? }
+```
+
+### ZKPassport (Zero-Knowledge)
+
+ZKPassport provides zero-knowledge proofs without revealing underlying data.
+
+```typescript
+// Connect to ZKPassport
+await individualTrust.connectZKP({ appId: 'your-app-id' });
+
+// Verify with zero-knowledge (supports ALL countries)
+const claims = await individualTrust.verifyZKP({
+  scope: 'global-adult',
+  purpose: 'Age verification',
+});
+// Returns: { uniqueIdentifier, proofSaid?, firstName?, nationality?, verifiedAt, expiresAt? }
+```
+
+### Storing Individual Trust
+
+```typescript
+import { AuthService } from 'ns-auth-sdk';
+
+const authService = new AuthService();
+
+// Store EUDI
+await authService.setIndividualTrust({ eudi: eudiClaims });
+
+// Store ZKP
+await authService.setIndividualTrust({ zkp: zkpClaims });
+
+// Store both
+await authService.setIndividualTrust({ eudi: eudiClaims, zkp: zkpClaims });
+
+// Check verification status
+const status = authService.getTrustStatus();
+// { verified: true, individual: { eudi?, zkp? }, organization? }
+```
+
+### Publishing to Profile
+
+```typescript
+// Publish EUDI to your kind-0
+await authService.publishEUDIToProfile(relayService);
+
+// Publish ZKP to your kind-0
+await authService.publishZKPToProfile(relayService);
+
+// Fetch from any pubkey
+const eudiTags = await relayService.fetchEUDITags(pubkey);
+const zkpTags = await relayService.fetchZKPTags(pubkey);
+```
+
+## Organization Trust (vLEI + EUDI Legal PID)
+
+### vLEI
+
+vLEI provides cryptographic verification of organizational identity through ACDC credentials.
+
+```typescript
+import { OrganizationTrustService } from 'ns-auth-sdk';
+
+const orgTrust = new OrganizationTrustService();
+
+// Connect to KERIA agent
+await orgTrust.connectKERIA('https://keria.example.com', 'yourbran');
+
+// Verify vLEI credentials
+const vleiClaims = await orgTrust.verifyVLEI();
+// { aidPrefix, lei, legalName, role, roleCredentialSaid, entityCredentialSaid, verifiedAt, expiresAt? }
+```
+
+### EUDI Legal PID
+
+EUDI also supports Legal Person Identification Data (LPID) for organizations via OpenID4VCI.
+
+```typescript
+// Connect to EUDI verifier for Legal PID
+await orgTrust.connectEUDI({
+  url: 'https://verifier.example.com',
+  clientId: 'your-client-id',
+});
+
+// Verify Legal PID
+const legalClaims = await orgTrust.verifyEUDILegal();
+// { holderDID, legalName, lei, legalForm?, registeredAddress?, vatNumber?, taxReference?, verifiedAt, expiresAt? }
+```
+
+### Storing Organization Trust
+
+```typescript
+import { AuthService } from 'ns-auth-sdk';
+
+const authService = new AuthService();
+
+// Store vLEI
+await authService.setOrganizationTrust(vleiClaims);
+
+// Store EUDI Legal PID
+await authService.setOrganizationTrust(legalClaims);
+
+// Check verification status
+const status = authService.getTrustStatus();
+// { verified: true, individual?, organization: { vlei?, eudiLegal? } }
+```
+
+### Publishing to Profile
+
+```typescript
+// Publish vLEI to organization's kind-0
+await authService.publishVLEIToProfile(relayService);
+
+// Publish EUDI Legal to organization's kind-0
+await authService.publishEUDILegalToProfile(relayService);
+
+// Fetch from any org pubkey
+const vleiTags = await relayService.fetchVLEITags(pubkey);
+const eudiLegalTags = await relayService.fetchEUDILegalTags(pubkey);
+```
+
+### FROST Multisig + Organization Trust
+
+Organization trust integrates with FROST multisig for organizational authority:
+
+```typescript
+// Enable multisig requiring organization verification
+const result = await authService.enableMultisig({
+  threshold: 2,
+  totalMembers: 3,
+  relays: ['wss://relay.io'],
+  organization: {
+    lei: '549300TLMP5S...',
+    legalName: 'org',
+  },
+  requireVLEI: true,  // All signers must have valid org trust
+});
+```
+
+## Kind-0 Tag Formats
+
+All tags use generic list format (not JSON):
+
+```typescript
+// EUDI (individual)
+['eudi', holderDID, givenName, familyName, dateOfBirth, nationality, verifiedAt, expiresAt?]
+
+// ZKPassport (individual)
+['zkp', uniqueIdentifier, proofSaid?, firstName?, nationality?, expiresAt?]
+
+// vLEI (organization)
+['vlei', aidPrefix, lei, legalName, role, roleCredentialSaid, entityCredentialSaid, verifiedAt, expiresAt?]
+
+// EUDI Legal PID (organization)
+['eudil', holderDID, legalName, lei, legalForm?, registeredAddress?, vatNumber?, taxReference?, verifiedAt, expiresAt?]
+
+// ZK Membership
+['zkm', groupId, root, createdAt, expiresAt?]
+```
+
+## ZK Membership
+
+Anonymous group membership where only the group root (Merkle tree root) is published to kind-0, not individual members.
+
+### How It Works
+
+1. **Identity Creation**: Generate a private key + commitment (Poseidon hash)
+2. **Group Creation**: Admin creates group with their commitment as initial root
+3. **Add Members**: New members' commitments update the Merkle tree root
+4. **Publish Root**: Only the root is published to kind-0 (not members)
+5. **Proof Generation**: Members generate ZK proofs proving membership without revealing identity
+6. **Nullifiers**: Each proof includes a nullifier to prevent double-signing
+
+### Quick Start
+
+```typescript
+import { ZKMService } from 'ns-auth-sdk';
+
+const zkmService = new ZKMService();
+
+// Generate your identity (private key + commitment)
+const identity = await zkmService.generateIdentity();
+// { privateKey: '...', commitment: '0xabc123...' }
+
+// Create a group (admin is first member)
+const group = await zkmService.createGroup('my-group');
+// { id: 'my-group', root: '0xdef456...', members: [...] }
+
+// Add members (updates root)
+const newMember = await zkmService.generateIdentity();
+const updatedGroup = await zkmService.addMember(group, newMember);
+
+// Publish group root to kind-0 (only root, no members!)
+await relayService.publishZKMGroupToKind0(pubkey, { 
+  groupId: group.id, 
+  root: updatedGroup.root 
+}, signEvent);
+
+// Generate anonymous membership proof
+const proof = await zkmService.generateProof(group, 'scope-1');
+// { groupId, root, proof, nullifier, scope, issuedAt }
+
+// Verify proof against known root
+const isValid = await zkmService.verifyProof(proof, knownRoot);
+```
+
+### Tag Format
+
+```
+['zkm', groupId, root, createdAt, expiresAt?]
+```
+
+Only the group root is published - members remain private.
+
+### Verification
+
+```typescript
+import { verifyZKMTag, verifyAllRootOfTrusts } from 'ns-auth-sdk';
+
+const result = verifyZKMTag(kind0Event);
+// Only verifies root exists and is valid
+// Does NOT reveal which member you are
+```
+
+## Root of Trust Verification
+
+Anyone can verify root of trust credentials from a user's kind-0 profile without needing to query the original issuer. The SDK provides unified verification utilities.
+
+### Quick Start
+
+```typescript
+import { 
+  verifyAllRootOfTrusts, 
+  hasAnyVerifiedRootOfTrust,
+  getVerificationSummary 
+} from 'ns-auth-sdk';
+
+// Fetch kind-0 from relay
+const kind0 = await relayService.fetchKind0Event(pubkey);
+
+// Verify all root of trust credentials
+const results = await verifyAllRootOfTrusts(kind0);
+
+// Check if any trust exists
+const hasTrust = await hasAnyVerifiedRootOfTrust(kind0);
+
+// Get human-readable summary
+const summary = await getVerificationSummary(kind0);
+console.log(summary);
+// {
+//   hasAnyTrust: true,
+//   individualVerified: true,
+//   organizationVerified: false,
+//   membershipVerified: true,
+//   details: ['EUDI verified', 'ZKPassport verified', 'ZK Membership verified']
+// }
+```
+
+### Individual Verification
+
+#### EUDI (with Nostr key linkage)
+
+EUDI verification includes signature verification to prove the EUDI holder also controls this Nostr key:
+
+```typescript
+import { verifyEUDITag } from 'ns-auth-sdk';
+
+const result = await verifyEUDITag(kind0Event);
+
+if (result.valid) {
+  console.log('EUDI verified!', result.claims);
+  // { uniqueIdentifier, signature, isOver18, nationality?, verifiedAt, expiresAt? }
+}
+```
+
+**Verification steps:**
+1. Extract `uniqueIdentifier` (SHA256 of holderDID) and `signature` from tag
+2. Reconstruct message: `EUDI:${uniqueIdentifier}:${verifiedAt}`
+3. Verify signature matches the pubkey in the kind-0 event
+
+#### ZKPassport (zero-knowledge)
+
+```typescript
+import { verifyZKPTag } from 'ns-auth-sdk';
+
+const result = verifyZKPTag(kind0Event);
+
+if (result.valid) {
+  console.log('ZKPassport verified!', result.claims);
+  // { uniqueIdentifier, proofSaid?, firstName?, nationality?, verifiedAt, expiresAt? }
+}
+```
+
+### Organization Verification
+
+#### vLEI
+
+```typescript
+import { verifyVLEITag } from 'ns-auth-sdk';
+
+const result = verifyVLEITag(kind0Event);
+
+if (result.valid) {
+  console.log('vLEI verified!', result.claims);
+  // { aidPrefix, lei, legalName, role, roleCredentialSaid, entityCredentialSaid, verifiedAt, expiresAt? }
+}
+```
+
+#### EUDI Legal PID
+
+```typescript
+import { verifyEUDILegalTag } from 'ns-auth-sdk';
+
+const result = await verifyEUDILegalTag(kind0Event);
+
+if (result.valid) {
+  console.log('EUDI Legal verified!', result.claims);
+  // { holderDID, legalName, lei, legalForm?, registeredAddress?, vatNumber?, taxReference?, verifiedAt, expiresAt? }
+}
+```
+
+### Group Membership Verification
+
+#### ZK Membership (Semaphore-style)
+
+```typescript
+import { verifyZKMTag } from 'ns-auth-sdk';
+
+const result = verifyZKMTag(kind0Event);
+
+if (result.valid) {
+  console.log('ZK Membership verified!', result.claims);
+  // { groupId, root, createdAt, expiresAt? }
+  // Note: Only root is verified, member identity is NOT revealed
+}
+```
+
+### API Reference
+
+```typescript
+// Verify individual root of trust types
+verifyVLEITag(kind0Event): RootOfTrustVerificationResult
+verifyEUDITag(kind0Event): Promise<RootOfTrustVerificationResult>
+verifyEUDILegalTag(kind0Event): Promise<RootOfTrustVerificationResult>
+verifyZKPTag(kind0Event): RootOfTrustVerificationResult
+verifyZKMTag(kind0Event): RootOfTrustVerificationResult
+
+// Verify all at once
+verifyAllRootOfTrusts(kind0Event): Promise<AllVerificationResults>
+
+// Quick checks
+hasAnyVerifiedRootOfTrust(kind0Event): Promise<boolean>
+getVerificationSummary(kind0Event): Promise<VerificationSummary>
+
+// Types
+interface RootOfTrustVerificationResult {
+  type: 'vlei' | 'eudi' | 'eudil' | 'zkp' | 'zkm';
+  valid: boolean;
+  claims?: any;
+  error?: string;
+}
+
+interface AllVerificationResults {
+  vlei?: RootOfTrustVerificationResult;
+  eudi?: RootOfTrustVerificationResult;
+  eudil?: RootOfTrustVerificationResult;
+  zkp?: RootOfTrustVerificationResult;
+  zkm?: RootOfTrustVerificationResult;
+}
+
+interface VerificationSummary {
+  hasAnyTrust: boolean;
+  individualVerified: boolean;
+  organizationVerified: boolean;
+  membershipVerified: boolean;
+  details: string[];
+}
+```
+
+### IndividualTrustService
+
+```typescript
+class IndividualTrustService {
+  eudi: EUDIService;
+  zkp: ZKPService;
+
+  connectEUDI(config: EUDIVerifierConfig): Promise<void>;
+  connectZKP(config: ZKPVerifierConfig): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  verifyEUDI(): Promise<EUDIClaims>;
+  verifyZKP(options?: Partial<ZKPVerificationRequest>): Promise<ZKPClaims>;
+  getVerificationStatus(): { eudi: boolean; zkp: boolean };
+}
+```
+
+### OrganizationTrustService
+
+```typescript
+class OrganizationTrustService {
+  keria: KERIAService;
+  eudi: EUDIService;
+
+  connectKERIA(url: string, bran: string): Promise<KERIAConnection>;
+  connectEUDI(config: EUDIVerifierConfig): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  verifyVLEI(): Promise<RootOfTrustInfo>;
+  verifyEUDILegal(): Promise<EUDILegalClaims>;
+  getVerificationStatus(): { vlei: boolean; eudiLegal: boolean };
+}
+```
+
+### VerificationStatus
+
+```typescript
+interface VerificationStatus {
+  verified: boolean;
+  individual?: {
+    eudi?: EUDIClaims & { expired?: boolean };
+    zkp?: ZKPClaims & { expired?: boolean };
+  };
+  organization?: {
+    vlei?: RootOfTrustInfo & { expired?: boolean };
+    eudiLegal?: EUDILegalClaims & { expired?: boolean };
+  };
+}
+```
+
+### Trust Methods (via AuthService)
+
+- `setOrganizationTrust(claims): Promise<void>` - Store org trust in KeyInfo
+- `clearOrganizationTrust(): Promise<void>` - Remove org trust
+- `setIndividualTrust(claims): Promise<void>` - Store individual trust in KeyInfo
+- `clearIndividualTrust(): Promise<void>` - Remove individual trust
+- `getTrustStatus(): VerificationStatus` - Get current verification status
+- `publishVLEIToProfile(relayService, orgPubkey?): Promise<boolean>`
+- `publishEUDIToProfile(relayService): Promise<boolean>`
+- `publishZKPToProfile(relayService): Promise<boolean>`
+- `publishEUDILegalToProfile(relayService): Promise<boolean>`
+
+vLEI integrates with FROST multisig for organizational authority:
+
+```typescript
+// Enable multisig with vLEI requirement
+const result = await authService.enableMultisig({
+  threshold: 2,
+  totalMembers: 3,
+  relays: ['wss://relay.io'],
+  organization: {
+    lei: '549300TLMP5S...',
+    legalName: 'org',
+  },
+  requireVLEI: true,  // All signers must have valid vLEI
+});
+
+// Signers in 'multisig' mode can be verified against vLEI
+const signedEvent = await authService.signEvent(event, { mode: 'multisig' });
+```
+
+## API Reference
+
+### IndividualTrustService
+
+```typescript
+class IndividualTrustService {
+  eudi: EUDIService;
+  zkp: ZKPService;
+
+  connectEUDI(config: EUDIVerifierConfig): Promise<void>;
+  connectZKP(config: ZKPVerifierConfig): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  verifyEUDI(): Promise<EUDIClaims>;
+  verifyZKP(options?: Partial<ZKPVerificationRequest>): Promise<ZKPClaims>;
+  getVerificationStatus(): { eudi: boolean; zkp: boolean };
+}
+```
+
+### OrganizationTrustService
+
+```typescript
+class OrganizationTrustService {
+  keria: KERIAService;
+  eudi: EUDIService;
+
+  connectKERIA(url: string, bran: string): Promise<KERIAConnection>;
+  connectEUDI(config: EUDIVerifierConfig): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  verifyVLEI(): Promise<RootOfTrustInfo>;
+  verifyEUDILegal(): Promise<EUDILegalClaims>;
+  getVerificationStatus(): { vlei: boolean; eudiLegal: boolean };
+}
+```
+
+### VerificationStatus
+
+```typescript
+interface VerificationStatus {
+  verified: boolean;
+  individual?: {
+    eudi?: EUDIClaims & { expired?: boolean };
+    zkp?: ZKPClaims & { expired?: boolean };
+  };
+  organization?: {
+    vlei?: RootOfTrustInfo & { expired?: boolean };
+    eudiLegal?: EUDILegalClaims & { expired?: boolean };
+  };
+}
+```
+
+### Root of Trust Types
+
+```typescript
+// EUDI Claims
+interface EUDIClaims {
+  uniqueIdentifier: string;     // SHA256 hash of holderDID
+  signature?: string;           // Signature linking
+  isOver18?: boolean;
+  nationality?: string;
+  verifiedAt: string;  // ISO 8601
+  expiresAt?: string;
+}
+
+interface ZKPClaims {
+  uniqueIdentifier: string;
+  proofSaid?: string;
+  firstName?: string;
+  nationality?: string;
+  isOver18?: boolean;
+  isEUCitizen?: boolean;
+  documentType?: string;
+  verifiedAt: string;  // ISO 8601
+  expiresAt?: string;
+}
+
+interface RootOfTrustInfo {
+  aidPrefix: string;
+  lei: string;
+  legalName: string;
+  role: string;
+  roleCredentialSaid: string;
+  entityCredentialSaid: string;
+  verifiedAt: string;  // ISO 8601
+  expiresAt?: string;
+}
+
+interface EUDILegalClaims {
+  holderDID: string;
+  legalName: string;
+  lei: string;
+  legalForm?: string;
+  registeredAddress?: string;
+  vatNumber?: string;
+  taxReference?: string;
+  verifiedAt: string;  // ISO 8601
+  expiresAt?: string;
+}
+```
+