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
| Property | Type |
|---|---|
instance? | string |
publicKey | string |
version | 1 |
wallet | object |
wallet.pipe? | string |
wallet.socket? | string |
WalletOptions
type WalletOptions = object;
Properties
| Property | Type | Description |
|---|---|---|
display? | Display | - |
env? | NodeJS.ProcessEnv | - |
name | string | What 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
| Parameter | Type | Default value |
|---|---|---|
env | ProcessEnv | process.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
| Parameter | Type | Default value |
|---|---|---|
name | string | undefined |
env | ProcessEnv | process.env |
Returns
home()
function home(env?): string;
~/.wellknown.id (or %APPDATA%\wellknown.id), where the discovery file and this installation's key are kept.
Parameters
| Parameter | Type | Default value |
|---|---|---|
env | ProcessEnv | process.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
| Parameter | Type |
|---|---|
p | string |
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
| Parameter | Type |
|---|---|
where | string |
Returns
stderrDisplay()
function stderrDisplay(name, write?): Display;
Says it on stderr, as name: ….
Parameters
| Parameter | Type |
|---|---|
name | string |
write | (s) => void |
Returns
wallet()
function wallet(o): Promise<Wallet>;
The holder's wallet on this machine, found, checked (its hello), and ready to ask.
Parameters
| Parameter | Type |
|---|---|
o | WalletOptions |
Returns
Promise<Wallet>