API reference

@wellknown-id/wallet/view

What a wallet's screens may use besides the service: pure functions over values, with no storage, keys or network. Everything that acts goes through the service (@wellknown-id/wallet/service).

Classes

FieldError

Extends

  • Error

Constructors

Constructor
new FieldError(field, code): FieldError;
Parameters
ParameterType
field| "email" | "given_name" | "family_name" | "nickname" | "phone_number" | "birthdate" | "website" | "address.street_address" | "address.locality" | "address.region" | "address.postal_code" | "address.country"
code"total" | "email" | "phone" | "date" | "url" | "long"
Returns

FieldError

Overrides
Error.constructor

Properties

PropertyModifierType
codereadonly"total" | "email" | "phone" | "date" | "url" | "long"
fieldreadonly| "email" | "given_name" | "family_name" | "nickname" | "phone_number" | "birthdate" | "website" | "address.street_address" | "address.locality" | "address.region" | "address.postal_code" | "address.country"

Variables

BURST_ASKS

const BURST_ASKS: object;

The bounds of a burst's count, for the screens' choices.

Type Declaration

NameTypeDefault value
max2020
min11

FIELD_NAMES

const FIELD_NAMES: (
  | "email"
  | "given_name"
  | "family_name"
  | "nickname"
  | "phone_number"
  | "birthdate"
  | "website"
  | "address.street_address"
  | "address.locality"
  | "address.region"
  | "address.postal_code"
  | "address.country")[];

FIELDS

const FIELDS: object;

The fields a persona may hold, by name (the claim path joined with dots), in the order they're shown.

Type Declaration

NameTypeDefault value
address.countryobject-
address.country.autocomplete"country-name"'country-name'
address.country.kind"text"'text'
address.country.max256256
address.country.path["address", "country"]-
address.localityobject-
address.locality.autocomplete"address-level2"'address-level2'
address.locality.kind"text"'text'
address.locality.max256256
address.locality.path["address", "locality"]-
address.postal_codeobject-
address.postal_code.autocomplete"postal-code"'postal-code'
address.postal_code.kind"text"'text'
address.postal_code.max3232
address.postal_code.path["address", "postal_code"]-
address.regionobject-
address.region.autocomplete"address-level1"'address-level1'
address.region.kind"text"'text'
address.region.max256256
address.region.path["address", "region"]-
address.street_addressobject-
address.street_address.autocomplete"street-address"'street-address'
address.street_address.kind"lines"'lines'
address.street_address.max512512
address.street_address.path["address", "street_address"]-
birthdateobject-
birthdate.autocomplete"bday"'bday'
birthdate.kind"date"'date'
birthdate.max1010
birthdate.path["birthdate"]-
emailobject-
email.autocomplete"email"'email'
email.kind"email"'email'
email.max256256
email.path["email"]-
family_nameobject-
family_name.autocomplete"family-name"'family-name'
family_name.kind"text"'text'
family_name.max256256
family_name.path["family_name"]-
given_nameobject-
given_name.autocomplete"given-name"'given-name'
given_name.kind"text"'text'
given_name.max256256
given_name.path["given_name"]-
nicknameobject-
nickname.autocomplete"nickname"'nickname'
nickname.kind"text"'text'
nickname.max256256
nickname.path["nickname"]-
phone_numberobject-
phone_number.autocomplete"tel"'tel'
phone_number.kind"phone"'phone'
phone_number.max6464
phone_number.path["phone_number"]-
websiteobject-
website.autocomplete"url"'url'
website.kind"url"'url'
website.max256256
website.path["website"]-

MAX_FIELDS_BYTES

const MAX_FIELDS_BYTES: 2048 = 2048;

A persona's fields together: at most this many bytes of UTF-8, so the keyring keeps room for everything else.


MAX_SECRET_BYTES

const MAX_SECRET_BYTES: number;

The largest secret a wallet keeps (40 KB), the same on every device, so any secret travels in one message.


PERSONA_CLAIMS_VCT

const PERSONA_CLAIMS_VCT: "https://kivi.wellknown.id/credentials/persona-claims/1" = 'https://kivi.wellknown.id/credentials/persona-claims/1';

The type of the credential a persona answers with: what the holder says about themself, as that persona.


PROX_GATT_SERVICE

const PROX_GATT_SERVICE: "776b2d70-726f-7831-6761-747400000001" = '776b2d70-726f-7831-6761-747400000001';

The GATT service kivi offers while it listens for a browser's token (gatt), and its one characteristic, which the page writes the token to (8 bytes, as any channel's). kivi's prefix ("wk-prox1") then "gatt" and a number, so a browser's chooser filters on it (Web Bluetooth's requestDevice({ filters: [{ services: [PROX_GATT_SERVICE] }] })) and finds the same phone again without asking (getDevices).


PROX_GATT_TOKEN

const PROX_GATT_TOKEN: "776b2d70-726f-7831-6761-747400000002" = '776b2d70-726f-7831-6761-747400000002';

PROX_NDEF_TYPE

const PROX_NDEF_TYPE: "wellknown.id:prox" = 'wellknown.id:prox';

The NDEF record a page writes to kivi's emulated tag (ndef): an external type (NFC Forum RTD, "domain:type") whose payload is the 8-byte token. kivi emulates a writable NFC Forum Type 4 tag only while it listens.


PROX_SEND_MS

const PROX_SEND_MS: 5000 = 5000;

How long one send lasts (a Bluetooth advertisement, an NFC card offered).


PROXIMITY_MIN_RSSI

const PROXIMITY_MIN_RSSI: -75 = -75;

The weakest Bluetooth signal that counts as near, in dBm. Measured 2026-10-13: side by side, -39 to -74 (one Pixel reading at -74: to revisit once the iPhone is measured).


USE_POLICY_ALWAYS

const USE_POLICY_ALWAYS: UsePolicySettings;

The number every time; and, for a device that doesn't know always, the closest its rules come.


USE_POLICY_DEFAULTS

const USE_POLICY_DEFAULTS: UsePolicySettings;

The defaults (Ben, 2026-10-10): the number only after a burst of asks, and after a no.


USE_POLICY_PLAIN

const USE_POLICY_PLAIN: UsePolicySettings;

A plain yes or no, always.

Functions

bondingNotice()

function bondingNotice(
   mine, 
   theirs, 
   iShowed
): BondingNotice;

What bonding two devices' personas will do, from the lines each sent (prd.md §4.10, "Before the holder confirms"), as planMerge will do it once the seeds travel: personas on one side only are that side's; a side whose own personas have all gone unused folds them, when the other's have been used, or, neither used, when the other side's were made first; where both have, nothing folds and the holder is told. The default is that of the device that showed the code (iShowed), unless it folds.

Parameters

ParameterType
minereadonly PersonaLine[]
theirsreadonly PersonaLine[]
iShowedboolean

Returns

BondingNotice


copyKey()

function copyKey(s): string;

The key copies of one secret share: the copy id where it has one (copies made from one another), else what it is (name, kind, service, size).

Parameters

ParameterType
sPick<SecretCredential, "copyOf" | "name" | "secretType" | "service" | "size">

Returns

string


devicesThreshold()

function devicesThreshold(n): number | undefined;

The devices way's threshold by how many devices the holder has (decision 3): none with one; 2 of 2; 2 of 3 or 4; 3 of 5 or more.

Parameters

ParameterType
nnumber

Returns

number | undefined


exportConsentRecords()

function exportConsentRecords(
   records, 
   subject, 
   exportedAt
): object;

The records as a JSON-LD document: subject is who they're about (the holder's did:key, say), records any mix of this device's and other devices' (with device). Values shared are never in a record, so never here; single-use key aliases stay behind.

Parameters

ParameterType
recordsExportable[]
subjectstring
exportedAtDate

Returns

object

NameTypeDefault value
@contextobjectCONTEXT
@context.dctstring'http://purl.org/dc/terms/'
@context.dpvstring'https://w3id.org/dpv#'
@context.kivistring'https://kivi.wellknown.id/ns#'
@context.xsdstring'http://www.w3.org/2001/XMLSchema#'
@graph( | { @id: string; @type: string; dct:conformsTo: string; dct:created: { @type: string; @value: string; }; dct:identifier: string; dpv:hasDataController: { @id: string; dct:title: string | undefined; }; dpv:hasDataSubject: { @id: string; }; dpv:hasRight: { @id: string; }; dpv:hasStatus: { @id: string; }; kivi:device?: string; kivi:organisationSaid: | { reason?: string; status?: "open" | "in_progress" | "fulfilled" | "denied"; } | undefined; } | { @id: string; @type: string; dct:conformsTo: string; dct:identifier: string; dpv:hasConsentStatus: { @type: string; dpv:isIndicatedAtTime: { @type: string; @value: string; }; dpv:isIndicatedBy: { @id: string; }; }; dpv:hasDataController: { @id: string; dct:title: string | undefined; }; dpv:hasDataSubject: { @id: string; }; dpv:hasNotice: | { @id: string; dct:hasVersion: string; kivi:sha256: string; } | undefined; dpv:hasPersonalData: object[] | undefined; dpv:hasPurpose: { @type: string; dct:description: string; }; dpv:hasStorageCondition: | { @type: string; dpv:hasDuration: string; } | undefined; kivi:askedBy: string | undefined; kivi:device?: string; kivi:how: | "rotation" | "digital-credentials-api" | "bonded-device" | "in-app" | "fedcm" | "redirect" | "for-another-device" | undefined; })[]graph
dct:createdstring-

holdersOwn()

function holdersOwn(b): boolean;

Whether a bond is with one of the holder's own devices, as removing it treats it (prd.md §7.10): a "mine" bond (held or not) that isn't this device's owner's (this device limited to it). Removing one takes it out of the holder's group, and asks why (lost or stolen freezes); removing any other bond ends it here only.

Parameters

ParameterType
bPick<Bond, "kind" | "as">

Returns

boolean


normaliseField()

function normaliseField(name, typed): string;

A value as it's kept: NFC, controls gone, white space tidied (lines kept for a street address), trimmed. "" clears it.

Parameters

ParameterType
name| "email" | "given_name" | "family_name" | "nickname" | "phone_number" | "birthdate" | "website" | "address.street_address" | "address.locality" | "address.region" | "address.postal_code" | "address.country"
typedstring

Returns

string


offerNameAmong()

function offerNameAmong(typed, taken): object;

A name as the holder typed it, against the names of their other personas (taken): name normalised, offered the one it would take ("Work 2" if "Work" is taken, ignoring case), taken if they differ. Throws NameError if it can't be a name.

Parameters

ParameterType
typedstring
takenIterable<string>

Returns

object

NameType
namestring
offeredstring
takenboolean

otherPersons()

function otherPersons(b): boolean;

Whether a bond is with another person's device (prd.md §7.10), whichever side showed the code: who a custodian can be (§7.11).

Parameters

ParameterType
bPick<Bond, "kind" | "as">

Returns

boolean


pairingMailbox()

function pairingMailbox(secret): string;

The relay mailbox two devices meet at to pair, named by a hash of the pairing secret (the secret never leaves the link).

Parameters

ParameterType
secretUint8Array

Returns

string


parseHandoverUrl()

function parseHandoverUrl(url): Uint8Array<ArrayBufferLike> | undefined;

The secret in a link handing the holder's wellknown.id to a browser (…/take#1.<secret>), or undefined if url isn't one.

Parameters

ParameterType
urlstring

Returns

Uint8Array<ArrayBufferLike> | undefined


parsePairingUrl()

function parsePairingUrl(url): Uint8Array<ArrayBufferLike> | undefined;

The bonding secret in a pairing link (…/bond#1.<secret>), or undefined if url isn't one.

Parameters

ParameterType
urlstring

Returns

Uint8Array<ArrayBufferLike> | undefined


parseRecoveryCode()

function parseRecoveryCode(typed): Uint8Array;

A recovery code as typed (any case, with or without dashes or spaces; O for 0, I and L for 1). A code printed with its persona's name (Persona Work · 7K3P-…, prd.md §4.10) is read after the last ·: the name is a label, not part of the code.

Parameters

ParameterType
typedstring

Returns

Uint8Array


parseRecoveryUrl()

function parseRecoveryUrl(url): Uint8Array<ArrayBufferLike> | undefined;

The secret in a recovery link (…/recover#1.<S>), or undefined if url isn't one.

Parameters

ParameterType
urlstring

Returns

Uint8Array<ArrayBufferLike> | undefined


parseRootCeremonyUrl()

function parseRootCeremonyUrl(url): Uint8Array<ArrayBufferLike> | undefined;

The secret in a root ceremony's code, or undefined if url isn't one.

Parameters

ParameterType
urlstring

Returns

Uint8Array<ArrayBufferLike> | undefined


parseSignInUrl()

function parseSignInUrl(url): Uint8Array<ArrayBufferLike> | undefined;

The secret in a link asking a wallet to sign in for another device (…/signin#1.<secret>), or undefined if url isn't one.

Parameters

ParameterType
urlstring

Returns

Uint8Array<ArrayBufferLike> | undefined


policyPresetOf()

function policyPresetOf(s): "own" | "plain" | "odd" | "always";

Which of the three ways of being asked the settings are, or 'own' (the holder's own mix).

Parameters

ParameterType
sUsePolicySettings

Returns

"own" | "plain" | "odd" | "always"


sshPublicLineOf()

function sshPublicLineOf(signs, comment?): string;

A secret's SSH public line, from its record's public half (signs): what a server's authorized_keys takes.

Parameters

ParameterTypeDefault value
signs{ alg: SignAlg; publicKey: string; }undefined
signs.algSignAlgundefined
signs.publicKeystringundefined
commentstring''

Returns

string


sshSkPublicLine()

function sshSkPublicLine(k, comment?): string;

A security key credential's line for authorized_keys.

Parameters

ParameterTypeDefault value
kPick<SecurityKeyCredential, "publicKey" | "application">undefined
commentstring''

Returns

string


toBase64()

function toBase64(bytes): string;

Standard base64 (RFC 4648 §4, padded), with no dependency on Buffer or btoa.

Parameters

ParameterType
bytesUint8Array

Returns

string


verifyDidKeySignature()

function verifyDidKeySignature(
   did, 
   data, 
   signature
): boolean;

Verifies a signature by a did:key, as the IdP does (apps/idp/lib/did-key.ts): Ed25519, or P-256 ECDSA with SHA-256 as raw r||s. Never throws.

Parameters

ParameterType
didstring
dataUint8Array
signatureUint8Array

Returns

boolean


wayOf()

function wayOf<K>(p, kind): 
  | Extract<{
  codes: CodeFactor[];
  kind: "code";
}, {
  kind: K;
}>
  | Extract<{
  installs: RootInstall[];
  k: number;
  kind: "devices";
}, {
  kind: K;
}>
  | Extract<{
  contacts: string[];
  k: number;
  kind: "custodians";
  n: number;
}, {
  kind: K;
}>
  | undefined;

The ways of a kind in a policy.

Type Parameters

Type Parameter
K extends "code" | "devices" | "custodians"

Parameters

ParameterType
pPolicy | undefined
kindK

Returns

| Extract<{ codes: CodeFactor[]; kind: "code"; }, { kind: K; }> | Extract<{ installs: RootInstall[]; k: number; kind: "devices"; }, { kind: K; }> | Extract<{ contacts: string[]; k: number; kind: "custodians"; n: number; }, { kind: K; }> | undefined


whoSigned()

function whoSigned(
   entry, 
   here, 
   known
): 
  | {
  kind: "here";
}
  | {
  kind: "device";
  name: string;
}
  | {
  kind: "unknown";
}
  | {
  kind: "page";
};

Who made a record, for people: this device (here, its did:key), one of the devices known by name (did:key to name), a device this one doesn't know, or (unsigned) one of the holder's browsers.

Parameters

ParameterType
entry{ signer?: string; }
entry.signer?string
herestring
knownReadonlyMap<string, string>

Returns

| { kind: "here"; } | { kind: "device"; name: string; } | { kind: "unknown"; } | { kind: "page"; }