Classes
FieldError
Extends
Error
Constructors
Constructor
new FieldError(field, code): FieldError;
Parameters
| Parameter | Type |
|---|---|
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
Overrides
Error.constructor
Properties
Variables
BURST_ASKS
const BURST_ASKS: object;
The bounds of a burst's count, for the screens' choices.
Type Declaration
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
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
| Parameter | Type |
|---|---|
mine | readonly PersonaLine[] |
theirs | readonly PersonaLine[] |
iShowed | boolean |
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
| Parameter | Type |
|---|---|
s | Pick<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
| Parameter | Type |
|---|---|
n | number |
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
| Parameter | Type |
|---|---|
records | Exportable[] |
subject | string |
exportedAt | Date |
Returns
object
| Name | Type | Default value |
|---|---|---|
@context | object | CONTEXT |
@context.dct | string | 'http://purl.org/dc/terms/' |
@context.dpv | string | 'https://w3id.org/dpv#' |
@context.kivi | string | 'https://kivi.wellknown.id/ns#' |
@context.xsd | string | '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:created | string | - |
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
| Parameter | Type |
|---|---|
b | Pick<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
| Parameter | Type |
|---|---|
name | | "email" | "given_name" | "family_name" | "nickname" | "phone_number" | "birthdate" | "website" | "address.street_address" | "address.locality" | "address.region" | "address.postal_code" | "address.country" |
typed | string |
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
| Parameter | Type |
|---|---|
typed | string |
taken | Iterable<string> |
Returns
object
| Name | Type |
|---|---|
name | string |
offered | string |
taken | boolean |
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
| Parameter | Type |
|---|---|
b | Pick<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
| Parameter | Type |
|---|---|
secret | Uint8Array |
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
| Parameter | Type |
|---|---|
url | string |
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
| Parameter | Type |
|---|---|
url | string |
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
| Parameter | Type |
|---|---|
typed | string |
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
| Parameter | Type |
|---|---|
url | string |
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
| Parameter | Type |
|---|---|
url | string |
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
| Parameter | Type |
|---|---|
url | string |
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
| Parameter | Type |
|---|---|
s | UsePolicySettings |
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
| Parameter | Type | Default value |
|---|---|---|
signs | { alg: SignAlg; publicKey: string; } | undefined |
signs.alg | SignAlg | undefined |
signs.publicKey | string | undefined |
comment | string | '' |
Returns
string
sshSkPublicLine()
function sshSkPublicLine(k, comment?): string;
A security key credential's line for authorized_keys.
Parameters
| Parameter | Type | Default value |
|---|---|---|
k | Pick<SecurityKeyCredential, "publicKey" | "application"> | undefined |
comment | string | '' |
Returns
string
toBase64()
function toBase64(bytes): string;
Standard base64 (RFC 4648 §4, padded), with no dependency on Buffer or btoa.
Parameters
| Parameter | Type |
|---|---|
bytes | Uint8Array |
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
| Parameter | Type |
|---|---|
did | string |
data | Uint8Array |
signature | Uint8Array |
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
| Parameter | Type |
|---|---|
p | Policy | undefined |
kind | K |
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
| Parameter | Type |
|---|---|
entry | { signer?: string; } |
entry.signer? | string |
here | string |
known | ReadonlyMap<string, string> |
Returns
| {
kind: "here";
}
| {
kind: "device";
name: string;
}
| {
kind: "unknown";
}
| {
kind: "page";
}