identity

@xnetjs/identity

DID:key identity, UCAN authorization, and key management for xNet.

Status: Mixed Stable entrypoints: @xnetjs/identity/did, @xnetjs/identity/ucan, @xnetjs/identity/key-bundle, @xnetjs/identity/passkey Deprecated compatibility entrypoint: @xnetjs/identity/legacy

The root barrel remains available for compatibility, but new code should prefer the narrower entrypoints above. See docs/reference/api-lifecycle-matrix.md for the current matrix.

Installation

pnpm add @xnetjs/identity

Features

• DID:key -- Generate and parse did:key:z6Mk... identifiers
• Key bundles -- Derive signing + encryption keys from a single seed
• UCAN tokens -- Create and verify User Controlled Authorization Networks
• Passkey storage -- Browser WebAuthn and in-memory passkey adapters
• Serialization -- Export/import key bundles for persistence

Usage

import { generateIdentity, createDID, parseDID } from '@xnetjs/identity'

// Generate a new identity
const { identity, privateKey } = generateIdentity()
console.log(identity.did) // did:key:z6Mk...

// Parse an existing DID
const parsed = parseDID(identity.did)

import { generateKeyBundle, serializeKeyBundle, deserializeKeyBundle } from '@xnetjs/identity'

// Full key bundle (signing + encryption keys)
const bundle = generateKeyBundle()

// Persist and restore
const serialized = serializeKeyBundle(bundle)
const restored = deserializeKeyBundle(serialized)

import { createUCAN, verifyUCAN, hasCapability } from '@xnetjs/identity'

// Create a UCAN token
const ucan = createUCAN({
  issuer: identity.did,
  issuerKey: privateKey,
  audience: otherDid,
  capabilities: [{ with: 'doc/*', can: 'write' }]
})

// Verify and check capabilities
const verified = verifyUCAN(ucan)
const canWrite = hasCapability(ucan, { with: 'doc/123', can: 'write' })

import { BrowserPasskeyStorage, MemoryPasskeyStorage } from '@xnetjs/identity'

// Browser passkey storage (WebAuthn)
const storage = new BrowserPasskeyStorage()

// In-memory for testing
const memory = new MemoryPasskeyStorage()

Modules

Module	Description
did.ts	DID:key creation and parsing
keys.ts	Key bundle generation, serialization
ucan.ts	UCAN token creation, verification, capabilities
passkey.ts	Browser and memory passkey storage
types.ts	Shared type definitions

Dependencies

• @xnetjs/core -- Core types
• @xnetjs/crypto -- Signing and hashing
• multiformats -- Multicodec encoding

Testing

pnpm --filter @xnetjs/identity test