This is the core: the protocol (GNAP, RFC 9635, as @wellknown-id/wallet/gnap sets it out) over ports, so it runs
wherever a transport, a key store and a display can be given. On Node, @wellknown-id/sdk/node gives them all and
finds the wallet on this machine:
import { wallet } from '@wellknown-id/sdk/node';
const w = await wallet({ name: 'ship-a-widget' });
const key = await w.secret('Claude API key', 'Write widget descriptions');
const { signatures } = await w.sign({ key: 'Release key', messages: [digest], purpose: 'Sign release 23' });
Phase 1 (local): a wallet on this machine, over a socket (kivi desktop's); every program shown as not verified. The
bridge (wk.onl) for programs with no wallet beside them comes in phase 2.
A yes that lasts (review R2-1): when the holder says "yes, for 10 minutes" to a signature, the wallet seals a token into the answer. This SDK keeps it in memory only, never on disk, and sends it with this program's next signatures with that key (inside its signed requests), so they're made without asking until it runs out; it goes when the program ends.
The wallet is the one named (its endpoint did:key, from the discovery file): it signs a hello on every new connection, and every answer with the request it answers, which this SDK checks before opening it (review 2026-10-13, M6), so nothing else at the socket can pass for it.
Classes
WalletError
Why the wallet didn't give what was asked: code as GNAP says it (user_denied, request_denied,
invalid_request…), or the SDK's own: no_wallet (none found), connection_lost (the connection went before an
answer: a poll is made again, anything else is said), wallet_untrusted (its discovery file or socket
isn't only this user's), wallet_not_named (what answered isn't the wallet named), wallet_unavailable (it's there
but couldn't take the request: its window not ready, say), timeout, invalid_response.
Extends
Error
Constructors
Constructor
new WalletError(code, message): WalletError;
Parameters
| Parameter | Type |
|---|---|
code | string |
message | string |
Returns
Overrides
Error.constructor
Properties
Interfaces
Display
Says what's happening where the person running the program sees it: the number above all.
Methods
asking()
asking(o): void;
The program's request is with the wallet: match is the number to pick there.
Parameters
| Parameter | Type |
|---|---|
o | { match: number; purpose: string; what: string; } |
o.match | number |
o.purpose | string |
o.what | string |
Returns
void
note()
note(text): void;
Something worth saying while it waits, or when it's done.
Parameters
| Parameter | Type |
|---|---|
text | string |
Returns
void
KeyStore
Keeps this installation's key (one per installation: asking-the-wallet.md, decision 2).
Methods
load()
load(): Promise<Uint8Array<ArrayBufferLike> | undefined>;
Returns
Promise<Uint8Array<ArrayBufferLike> | undefined>
save()
save(secretKey): Promise<void>;
Parameters
| Parameter | Type |
|---|---|
secretKey | Uint8Array |
Returns
Promise<void>
Transport
Carries one message to the wallet and brings back its reply: a local socket today, the bridge later.
Properties
| Property | Type |
|---|---|
send | Send |
Methods
close()
close(): void;
Returns
void
onConnect()?
optional onConnect(check): void;
Run on every new connection, before anything else is sent on it (send: that connection's own): the SDK checks
the wallet's hello there, so a transport that reconnects can't reconnect to something else.
Parameters
| Parameter | Type |
|---|---|
check | (send) => Promise<void> |
Returns
void
Wallet
What a program can ask for.
Methods
close()
close(): void;
Returns
void
secret()
secret(name, purpose): Promise<Uint8Array<ArrayBufferLike>>;
A secret, by its name in the holder's wallet, for this once.
Parameters
| Parameter | Type |
|---|---|
name | string |
purpose | string |
Returns
Promise<Uint8Array<ArrayBufferLike>>
secrets()
secrets(names, purpose): Promise<Uint8Array<ArrayBufferLike>[]>;
Several secrets under one yes (a keystore and its password), in the order named.
Parameters
| Parameter | Type |
|---|---|
names | string[] |
purpose | string |
Returns
Promise<Uint8Array<ArrayBufferLike>[]>
sign()
sign(o): Promise<{
alg: "Ed25519" | "ES256";
publicKey: Uint8Array;
signatures: Uint8Array<ArrayBufferLike>[];
}>;
Messages signed with a key the holder keeps as a secret (key, by name): the key never leaves where it's kept.
Comes back with the key's public half, so the program can check it's the key it expects.
Parameters
| Parameter | Type |
|---|---|
o | { alg?: "Ed25519" | "ES256"; key: string; messages: Uint8Array<ArrayBufferLike>[]; purpose: string; } |
o.alg? | "Ed25519" | "ES256" |
o.key | string |
o.messages | Uint8Array<ArrayBufferLike>[] |
o.purpose | string |
Returns
Promise<{
alg: "Ed25519" | "ES256";
publicKey: Uint8Array;
signatures: Uint8Array<ArrayBufferLike>[];
}>
Type Aliases
ConnectOptions
type ConnectOptions = object;
Properties
| Property | Type | Description |
|---|---|---|
display | Display | - |
keys | KeyStore | - |
name | string | What this program calls itself: shown to the holder as its word, beside what the OS says it is. |
now? | () => number | - |
sleep? | (ms) => Promise<void> | For tests: what waits between polls, and the time it is. |
timeoutMs? | number | How long to wait for the holder, in ms (5 minutes). |
transport | Transport | - |
uri? | string | Where it's from, if it has a home page: shown, not checked (yet). |
wallet | object | The wallet's endpoint did:key, as its discovery file names it, and where it was reached: its hellos and answers must be signed by it. |
wallet.publicKey | string | - |
wallet.where | string | - |
Send
type Send = (message) => Promise<Record<string, unknown>>;
Sends one message and brings back its reply.
Parameters
| Parameter | Type |
|---|---|
message | Record<string, unknown> |
Returns
Promise<Record<string, unknown>>
Functions
checkHello()
function checkHello(send, wallet): Promise<void>;
Checks that the wallet at the other end is the one named: it signs a fresh nonce and where it was reached with its
endpoint did:key. Throws if it doesn't (wallet_not_named), or if it couldn't answer (wallet_unavailable).
Parameters
| Parameter | Type |
|---|---|
send | Send |
wallet | { publicKey: string; where: string; } |
wallet.publicKey | string |
wallet.where | string |
Returns
Promise<void>
connect()
function connect(o): Promise<Wallet>;
Connects to a wallet over the ports given, checking its hello now and on every new connection.
Parameters
| Parameter | Type |
|---|---|
o | ConnectOptions |
Returns
Promise<Wallet>