Your program needs something the person keeps in their wallet: an API key, a signing key's signature. With the SDK for programs it asks their wallet directly. The person sees who's asking and why, picks the number your program shows, and says yes, and what they agreed to comes back to your program alone. Nothing is stored for next time.
import { wallet } from '@wellknown-id/sdk/node';
const w = await wallet({ name: 'ship-a-widget' });
const apiKey = await w.secret('Claude API key', 'Write widget descriptions');
const { publicKey, signatures } = await w.sign({ key: 'Release key', messages: [digest], purpose: 'Sign release 23', alg: 'Ed25519' });
w.close();
What the person sees
Your program prints the number on stderr: ship-a-widget: asking your wallet for “Claude API key”: when it asks, choose 42. Their wallet shows:
- who's asking: the name your program gives (marked not verified: it's your word), and what their computer says the program is (its command line, and the shell it was run from). If the two don't match, the wallet warns them.
- what, and why: the secret's name, or how many signatures with which key, and your purpose, in your words.
- three numbers, one of them yours, which they can pick only after a moment to read the request. A wrong pick is a no.
A secret's value comes to your program for this once. A key that signs never leaves where it's kept: your program gets the signatures and the key's public half, to check it's the key you expect.
When the holder says yes to a signature, they may choose "for 10 minutes". The wallet then gives your program a token, sealed to it, that the SDK keeps in memory (never on disk) and sends with your next signatures with that key, which are made without asking until it runs out, your program ends, the holder takes it back (in kivi's Consents, on the device that keeps the key), or that device locks (a phone's lock; kivi desktop's session lock on Linux, or its window hidden five minutes). Nothing to do in your code: sign() uses it when it has one. A secret's value is never covered: each is asked for.
Finding the wallet
The SDK looks for the wallet on this machine:
WELLKNOWN_ID_WALLET, if it's set, names a discovery file (mount one into a container with the wallet's socket).- Otherwise
~/.wellknown.id/config.json(%APPDATA%\wellknown.id\config.jsonon Windows), which kivi desktop writes while it runs:
{ "version": 1, "wallet": { "socket": "/run/user/1000/kivi/wallet.sock" }, "publicKey": "did:key:z…" }
The file holds no secrets; publicKey is the wallet's own endpoint key. On every connection the SDK checks the wallet signs a fresh hello with it, naming the socket it was reached on, and every answer comes signed by it too, so nothing else listening at the socket can pass for the wallet. As ssh does with its files, the discovery file, its folder and the socket must be yours and writable by no one else. With no wallet found, wallet() throws a WalletError with the code no_wallet.
Your program's own key (one per installation) is made on first use and kept in ~/.wellknown.id/keys/<name>.key, readable only by the user. Every request is signed with it, and the answer is sealed to a key made for that request alone.
Errors
Every refusal is a WalletError with a code, as GNAP names them:
code | |
|---|---|
no_wallet | No wallet on this machine, or it didn't answer |
wallet_not_named | Something answered that isn't the wallet the discovery file names |
wallet_untrusted | The discovery file, its folder or the socket isn't only yours (its owner, or others can write it) |
wallet_unavailable | The wallet is there but couldn't take the request (its window not ready, say) |
connection_lost | The connection went before an answer (the SDK polls again by itself; this reaches you only if it keeps happening) |
user_denied | The person said no, or picked another number |
request_denied | The wallet couldn't give it: no such secret, or a key that doesn't sign that way |
invalid_request | The request wasn't one the wallet takes |
timeout | No answer in time (5 minutes, or timeoutMs): the SDK tells the wallet it gave up, and the request goes from the wallet's screen |
Under the hood
The SDK speaks GNAP (RFC 9635), the IETF's protocol for a program obtaining a grant from a person, with a few extensions at its registered extension points: the number your program shows, signed inside the request; and the answer, sealed with HPKE (RFC 9180) to your request's own key. Each request is one JWS signed by your program's key (GNAP's attached-JWS proofing), so it holds together over a socket today and through a relay later.
Today the SDK finds wallets on the same machine. Asking from another machine (a server, a remote shell), through a short link and a QR code, comes next. Its types are in the API reference: @wellknown-id/sdk and @wellknown-id/sdk/node.