API reference

@wellknown-id/sdk/node

The wellknown.id SDK on Node (docs/plans/asking-the-wallet.md): finds the holder's wallet on this machine and asks it, with this installation's key kept under ~/.wellknown.id/keys/, the number said on stderr.

Finding the wallet: WELLKNOWN_ID_WALLET, if set, names a discovery file (a container mounts one, with the wallet's socket); else ~/.wellknown.id/config.json on Linux and macOS, %APPDATA%\wellknown.id\config.json on Windows. kivi desktop writes it while it runs, holding no secrets:

{ "version": 1, "wallet": { "socket": "/run/user/1000/kivi/wallet.sock" }, "publicKey": "did:key:z…", "instance": "…" }

The wallet must sign a hello with that publicKey on every connection, naming the file's instance (this run of the wallet: so a socket mounted elsewhere, in a container, still reaches the same one: review R2-14), and every answer (review 2026-10-13, M6), so nothing else listening at that socket can pass for it. And as ssh does with its files, the discovery file, the socket and every folder above them (their real paths, links followed) must be this user's or root's and writable by no one else, group included (wallet_untrusted otherwise: R2-19), so another user can't point a program at a wallet of their own.

Type Aliases

Discovery

type Discovery = object;

What kivi desktop writes, and the SDK reads.

Properties

PropertyType
instance?string
publicKeystring
version1
walletobject
wallet.pipe?string
wallet.socket?string

WalletOptions

type WalletOptions = object;

Properties

PropertyTypeDescription
display?Display-
env?NodeJS.ProcessEnv-
namestringWhat this program calls itself: its key is kept under this name, and the holder sees it (as its word).
now?() => number-
sleep?(ms) => Promise<void>For tests: what waits between polls, and the time it is.
timeoutMs?number-
uri?string-

Functions

discover()

function discover(env?): Promise<{
  file: string;
  found: Discovery;
}>;

The discovery file: where it is, and what it says. Throws, saying how to get one, if there's none.

Parameters

ParameterTypeDefault value
envProcessEnvprocess.env

Returns

Promise<{ file: string; found: Discovery; }>


fileKeyStore()

function fileKeyStore(name, env?): KeyStore;

This installation's key, in ~/.wellknown.id/keys/<name>.key (mode 600, its folder 700).

Parameters

ParameterTypeDefault value
namestringundefined
envProcessEnvprocess.env

Returns

KeyStore


home()

function home(env?): string;

~/.wellknown.id (or %APPDATA%\wellknown.id), where the discovery file and this installation's key are kept.

Parameters

ParameterTypeDefault value
envProcessEnvprocess.env

Returns

string


ours()

function ours(p, kind): Promise<void>;

That p is this user's and writable by no one else, group included, and every folder above its real path (links followed) is this user's or root's and writable by no one else either (Unix; as ssh checks its own files: R2-19), or wallet_untrusted. kind: what it must be.

Parameters

ParameterType
pstring
kind"file" | "dir" | "socket"

Returns

Promise<void>


socketTransport()

function socketTransport(where): Transport;

A transport over a Unix socket (or a Windows named pipe): one line of JSON out, one back, in turn. On every new connection, before anything else goes on it, the SDK's check (onConnect: the wallet's hello) runs on it.

Parameters

ParameterType
wherestring

Returns

Transport


stderrDisplay()

function stderrDisplay(name, write?): Display;

Says it on stderr, as name: ….

Parameters

ParameterType
namestring
write(s) => void

Returns

Display


wallet()

function wallet(o): Promise<Wallet>;

The holder's wallet on this machine, found, checked (its hello), and ready to ask.

Parameters

ParameterType
oWalletOptions

Returns

Promise<Wallet>