Identity Kit

About Nuwa Identity Kit

Overview

@nuwa-ai/identity-kit provides DID creation, resolution, key management, and DIDAuth v1 signing/verification. It supports multiple DID methods (e.g., did:rooch, did:key) and follows NIP-1 (single DID, multi-key) and NIP-2 (DIDAuth v1).

Install

pnpm add @nuwa-ai/identity-kit @roochnetwork/rooch-sdk

CLI for agent environments

If you need a zero-code DIDAuth flow for agent environments, use the nuwa-id CLI:

npm i -g @nuwa-ai/identity-kit
nuwa-id help

See DIDAuth Integration Guides for both agent flow and backend verification middleware.

Quick Start

import { IdentityKit, DIDAuth, KeyType } from '@nuwa-ai/identity-kit';

const env = await IdentityKit.bootstrap({ method: 'rooch', vdrOptions: { rpcUrl: 'https://test-seed.rooch.network' } });
const kit = await env.loadDid('did:rooch:0xYourDid');
await kit.addVerificationMethod({ keyType: KeyType.ECDSA_SECP256K1 }, ['authentication']);
const sig = await DIDAuth.v1.createSignature({ operation: 'call', params: { ts: Date.now() } }, env.keyManager, kit.getDIDDocument().verificationMethod![0].id);
const authz = DIDAuth.v1.toAuthorizationHeader(sig);

IdentityKit (Static)

bootstrap

Prepare VDR(s) and a KeyManager without creating a DID.

Inputs

Bootstrap options

options · object

Show options

method · string · default: "rooch"

DID method to register with VDR

vdrOptions · object

VDR-specific options (e.g., rpcUrl, network)

keyStore · KeyStore?

Custom key store implementation

Returns

env · IdentityEnv

Environment with VDRRegistry and KeyManager

fromExistingDID

Resolve a DID and bind an IdentityKit instance to it.

Inputs

did · string · required

DID to resolve (e.g., did:rooch:0x…)

signer · SignerInterface · required

Used for publishing changes and signing

Returns

kit · IdentityKit

Instance bound to the DID

fromDIDDocument

Create an instance using a known DID Document.

Inputs

didDocument · DIDDocument · required

Pre-resolved DID Document

signer · SignerInterface · required

Signer for publishing

Returns

kit · IdentityKit

Instance bound to the doc

createNewDID

Create and publish a new DID via registered VDR.

Inputs

method · string · required

DID method (e.g., rooch)

creationRequest · DIDCreationRequest · required

VDR-specific creation payload

signer · SignerInterface · required

Signer for publishing

options · object?

Optional VDR params

Returns

kit · IdentityKit

Instance bound to new DID

IdentityEnv

loadDid

Load an existing DID using the environment.

Inputs

did · string · required

DID to load

signer · SignerInterface?

Defaults to env.keyManager

Returns

kit · IdentityKit

Instance bound to DID

fromDocument

Bind a known DID Document.

Inputs

doc · DIDDocument · required

Known DID Document

signer · SignerInterface?

Defaults to env.keyManager

Returns

kit · IdentityKit

Instance bound to doc

createDid

Create a DID via the underlying VDR.

Inputs

method · string · required

DID method name

request · DIDCreationRequest · required

Creation payload

signer · SignerInterface?

Override signer

options · object?

VDR-specific options

Returns

kit · IdentityKit

Instance bound to new DID

IdentityKit (Instance)

addVerificationMethod

Add a verification method to the DID Document and publish.

Inputs Key material and metadata

keyInfo · OperationalKeyInfo · required

Show keyInfo

idFragment · string?

Defaults to key-<timestamp>

type · string · required

e.g., EcdsaSecp256k1VerificationKey2019

controller · string?

Defaults to DID

publicKeyMaterial · Uint8Array | JsonWebKey · required

Public key

relationships · string[] · required

One or more of authentication/assertionMethod/keyAgreement/capabilityInvocation/capabilityDelegation

Optional signing controls

options · object?

Show options

keyId · string?

Signing key with capabilityDelegation

scopes · string[]?

Optional scopes

Returns

keyId · string

New verification method id

removeVerificationMethod

Remove a verification method and update relationships.

Inputs

keyId · string · required

Verification method id to remove

signerKeyId · string?

Signing key (capabilityDelegation)

Returns

success · boolean

True if removal published

updateVerificationMethodRelationships

Add/remove relationships for an existing key.

Inputs

keyId · string · required

Verification method id

add · string[] · required

Relationships to add

remove · string[] · required

Relationships to remove

signer · SignerInterface?

Override signer

Returns

success · boolean

True if update published

addService

Publish a new service entry to the DID Document.

Inputs Service definition

serviceInfo · object · required

Show serviceInfo

idFragment · string · required

type · string · required

serviceEndpoint · string | object · required

additionalProperties · object?

Arbitrary fields

keyId · string?

Signing key (capabilityInvocation)

Returns

serviceId · string

Fully qualified service id

removeService

Delete a service by id and publish.

Inputs

serviceId · string · required

Service id to remove

keyId · string?

Signing key (capabilityInvocation)

Returns

success · boolean

True if removal published

getDIDDocument

Return the current DID Document.

Inputs

(none) · void

No input parameters

Returns

didDocument · DIDDocument

Latest resolved DID Document

findServiceByType

Find a service by its type.

Inputs

serviceType · string · required

Service type string

Returns

service · ServiceEndpoint | undefined

Matching service (if any)

findVerificationMethodsByRelationship

List verification methods for a given relationship.

Inputs

relationship · string · required

Relationship key

Returns

methods · VerificationMethod[]

Matching verification methods

canSignWithKey

Check if the signer has the private key for keyId.

Inputs

keyId · string · required

Verification method id

Returns

canSign · boolean

True if signer can sign

getAvailableKeyIds

List available key ids by relationship present in both DID doc and signer.

Inputs

(none) · void

No input parameters

Returns

byRelationship · record

Map of relationships to key ids

DIDAuth.v1

createSignature

Create a signed object suitable for DIDAuth v1.

Inputs

Operation payload

payload · object · required

Show payload

operation · string · required

params · any · required

signer · SignerInterface · required

Signing interface

keyId · string · required

Verification method id

Optional signing controls

options · object?

didDocument · DIDDocument?

nonce · string?

timestamp · number?

domainSeparator · string? · default: "DIDAuthV1:"

Returns

signed · NIP1SignedObject

Signed object

toAuthorizationHeader

Serialize a signed object into an Authorization header value.

Inputs

signed · NIP1SignedObject · required

Signed object

Returns

header · string

DIDAuthV1 <base64url(payload)>

verifyAuthHeader

Verify a DIDAuth header string.

Inputs

header · string · required

Authorization header value

resolver · DIDResolver · required

DID resolver

Verification options

options · object?

maxClockSkew · number? · default: "300"

Seconds

nonceStore · NonceStore?

Replay protection

Returns

result · object

Detailed verification result (ok, error?, errorCode?, signedObject?)

verifySignatureDetailed

Verify a signed object using a resolver or a DID Document.

Inputs

signed · NIP1SignedObject · required

Signed object

resolverOrDoc · DIDResolver | DIDDocument · required

Source for public key

Verification options

options · object?

maxClockSkew · number? · default: "300"

Returns

result · object

Detailed verification result (ok, error?, errorCode?, signedObject?)

verifySignature

Backward compatible boolean verification.

Inputs

signed · NIP1SignedObject · required

Signed object

resolverOrDoc · DIDResolver | DIDDocument · required

Source for public key

Verification options

options · object?

maxClockSkew · number? · default: "300"

Returns

ok · boolean

True if signature is valid