API reference

@wellknown-id/sdk

The wellknown.id SDK for programs (docs/plans/asking-the-wallet.md): a command-line tool, a desktop app, a script asks the holder's wallet for a secret, for this once, or for messages signed with a key the holder keeps, which never leaves where it's kept. The program shows a number; the holder's wallet shows who's asking and what for, and asks them to pick that number; the answer comes back sealed to this program's key.

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
ParameterType
codestring
messagestring
Returns

WalletError

Overrides
Error.constructor

Properties

PropertyModifierType
codereadonlystring

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
ParameterType
o{ match: number; purpose: string; what: string; }
o.matchnumber
o.purposestring
o.whatstring
Returns

void

note()
note(text): void;

Something worth saying while it waits, or when it's done.

Parameters
ParameterType
textstring
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
ParameterType
secretKeyUint8Array
Returns

Promise<void>


Transport

Carries one message to the wallet and brings back its reply: a local socket today, the bridge later.

Properties

PropertyType
sendSend

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
ParameterType
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
ParameterType
namestring
purposestring
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
ParameterType
namesstring[]
purposestring
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
ParameterType
o{ alg?: "Ed25519" | "ES256"; key: string; messages: Uint8Array<ArrayBufferLike>[]; purpose: string; }
o.alg?"Ed25519" | "ES256"
o.keystring
o.messagesUint8Array<ArrayBufferLike>[]
o.purposestring
Returns

Promise<{ alg: "Ed25519" | "ES256"; publicKey: Uint8Array; signatures: Uint8Array<ArrayBufferLike>[]; }>

Type Aliases

ConnectOptions

type ConnectOptions = object;

Properties

PropertyTypeDescription
displayDisplay-
keysKeyStore-
namestringWhat 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?numberHow long to wait for the holder, in ms (5 minutes).
transportTransport-
uri?stringWhere it's from, if it has a home page: shown, not checked (yet).
walletobjectThe 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.publicKeystring-
wallet.wherestring-

Send

type Send = (message) => Promise<Record<string, unknown>>;

Sends one message and brings back its reply.

Parameters

ParameterType
messageRecord<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

ParameterType
sendSend
wallet{ publicKey: string; where: string; }
wallet.publicKeystring
wallet.wherestring

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

ParameterType
oConnectOptions

Returns

Promise<Wallet>