Identity

Your app works with cryptographic identities — real people and devices, not usernames and passwords.

Listing identities

identity.list (void): Identity[]

List the identities available to your app. Returns own identities and contacts (remote identities you've been introduced to). Own identities have privkey: true — the key itself stays in wish-core.

const identities = await app.identity.list();

for (const id of identities) {
    console.log(id.name, id.privkey ? '(own)' : '(contact)');
}

Each identity has:

Field	Type	Description
uid	Buffer	Identity UID (32 bytes) — stable, never changes
name	string	Display name
privkey	boolean	true for own identities, false for contacts

Getting identity details

identity.get (uid: Uid): Identity

Get full details for an identity — signers, contacts, and hosts.

const identity = await app.identity.get(uid);

for (const host of identity.hosts || []) {
    console.log(`  ${host.name || host.role || 'unnamed'}`);
}

Field	Type	Description
signers	Signer[]	Cryptographic keys that can act as this identity
contacts	Buffer[]	Contact UIDs (own identities only)
hosts	HostInfo[]	Known devices — { hostId, name?, role? }

Signing and verification

Your app can sign data with any identity it has access to, and verify signatures from anyone.

identity.sign (uid: Uid, document: Document, claim: Buffer): Document

Sign a document with an identity's key. The claim is an arbitrary buffer that becomes part of the signed statement.

const signed = await app.identity.sign(uid, document, claim);

identity.verify (document: Document): Document

Verify a signed document. Returns the document with verification result.

const result = await app.identity.verify(signedDocument);

Reacting to changes

The identity signal fires whenever identities change — new identity created, contact added, name updated. Re-fetch app.identity.list() to stay current.

Identity name cache

The SDK automatically caches identity and host names from wish-core. This powers peer.toString() and is also available directly:

app.identityCache.getName(uid)            // "André"
app.identityCache.getHostName(uid, hid)   // "hp"

The cache refreshes automatically when identities change.