API reference

@wellknown-id/wallet/service

The wallet service: everything a wallet does, made once from the platform's ports. An app builds it with createWalletService(ports), calls its commands, listens for what changed (on), opens and closes it as the app comes to the front and goes, and puts to the holder what only they can answer (open's asks). The app itself keeps no state and makes no decisions: kivi is such an app, over its platform adapters.

Classes

PagesDifferError

Refused while the pages differ from the log: bonding, handing over the holder's wellknown.id, signing in for another device.

Extends

  • Error

Constructors

Constructor
new PagesDifferError(message?): PagesDifferError;
Parameters
ParameterType
message?string
Returns

PagesDifferError

Inherited from
Error.constructor
Constructor
new PagesDifferError(message?, options?): PagesDifferError;
Parameters
ParameterType
message?string
options?ErrorOptions
Returns

PagesDifferError

Inherited from
Error.constructor

Properties

PropertyModifierTypeDefault value
codereadonly"E_PAGES_DIFFER"'E_PAGES_DIFFER'

Interfaces

CredentialRegistry

Where the platform lets sites find this wallet's credentials (the Digital Credentials API: Android's Credential Manager). None in a browser.

Methods

register()
register(credentials, personas?): Promise<string[]>;

Registers these presentable credentials (a batch as one, under its batch id), and the personas that can answer for the holder (persona-fields.ts: each under its entry id, with the names of the fields it has, never their values), in place of what was there. Resolves the ids registered.

Parameters
ParameterType
credentialsSdJwtVcCredential[]
personas?object[]
Returns

Promise<string[]>

supported()
supported(): boolean;
Returns

boolean


HolderStore

Where the device keeps its HolderState: a file on a phone, localStorage in a browser.

Methods

load()
load(): Promise<HolderState | undefined>;
Returns

Promise<HolderState | undefined>

save()
save(state): Promise<void>;
Parameters
ParameterType
stateHolderState | undefined
Returns

Promise<void>


Passkeys

The holder's wellknown.id passkeys (prd.md §4.7, §4.10): the system's prompts, through the platform.

Methods

create()
create(user, exclude): Promise<{
  aaguid?: string;
  credentialId: string;
  prfEnabled: boolean;
  unlock?: Uint8Array<ArrayBufferLike>;
}>;

Makes a passkey for a keyring: exclude, the credential IDs it mustn't duplicate (E_EXCLUDED). Resolves its credential ID, whether it does PRF, and the unlock secret if the provider computed it at registration.

Parameters
ParameterType
userPasskeyUser
excludestring[]
Returns

Promise<{ aaguid?: string; credentialId: string; prfEnabled: boolean; unlock?: Uint8Array<ArrayBufferLike>; }>

here()?
optional here(): boolean;

Whether this device can make a passkey with PRF now (an Android phone, an iPhone on iOS 18 or later, a browser that offers PRF). Not given: taken as yes. The service decides from it (a recovery makes a new passkey only where one can be).

Returns

boolean

tell()
tell(k): Promise<void>;

Tells the providers (the WebAuthn Signal API, where there is one) which passkeys open the keyring. Never throws.

Parameters
ParameterType
kKeyring
Returns

Promise<void>

unlock()
unlock(elsewhere?, credentialId?): Promise<{
  credentialId: string;
  secret: Uint8Array;
  user?: string;
}>;

The passkey's unlock secret (its PRF output), its credential ID (base64url) and its user handle where the system gives it, after the system's prompt. Any wellknown.id passkey, or credentialId's only; elsewhere lets the system offer one from another device (a QR code). Rejects with code E_CANCELLED, E_NO_PASSKEY or E_NO_PRF.

Parameters
ParameterType
elsewhere?boolean
credentialId?string
Returns

Promise<{ credentialId: string; secret: Uint8Array; user?: string; }>


QuietSealer

Seals a persona's records keys and the list of personas with a key bound to this device, without a prompt (prd.md §4.10): the Keystore on Android, a Secure Enclave key on iOS. None in a browser, where they're never kept: they come from the seed, which opens there without a prompt.

Methods

open()
open(sealed): Promise<Uint8Array<ArrayBufferLike>>;
Parameters
ParameterType
sealedUint8Array
Returns

Promise<Uint8Array<ArrayBufferLike>>

seal()
seal(data): Promise<Uint8Array<ArrayBufferLike>>;
Parameters
ParameterType
dataUint8Array
Returns

Promise<Uint8Array<ArrayBufferLike>>


RingPort

Keeper rings (ring.ts) over NFC: a tap at a time. None where there's no NFC that sends APDUs (a browser; kivi on iPhone until its build declares the ring's AID).

Methods

cancel()?
optional cancel(): void;

Gives up a tap still waiting for the ring (the holder's Cancel: Android shows nothing of its own to cancel with).

Returns

void

say()?
optional say(message): void;

How a tap is going, in the holder's words, where they're looking while the ring is held (iOS's NFC sheet covers the app).

Parameters
ParameterType
messagestring
Returns

void

supported()
supported(): boolean;
Returns

boolean

tap()
tap<T>(prompt, run): Promise<T>;

One tap: asks the holder to hold their ring to the device (prompt) and runs run while it's there; the session ends when run settles. Rejects (E_CANCELLED) if the holder gives up.

Type Parameters
Type Parameter
T
Parameters
ParameterType
promptstring
run(link) => Promise<T>
Returns

Promise<T>

tapNow()?
optional tapNow<T>(run): Promise<T | undefined>;

A tap with a ring that's already there, without asking for one: run with it if a ring is on the reader now (a computer's: kivi desktop), else undefined at once. Where a ring is only ever held for a moment (a phone), absent.

Type Parameters
Type Parameter
T
Parameters
ParameterType
run(link) => Promise<T>
Returns

Promise<T | undefined>

Type Aliases

AfterRecovery

type AfterRecovery = object;

Back in through custodians (prd.md §7.11, after a recovery): the dealing whose shares travelled, its policy, and its custodians by contact, each with whether this device can reach them yet. Until it deals again, those shares still open the keyring as it was; it deals again by itself once it reaches every one (upkeep).

Properties

PropertyType
contactsobject[]
epochstring
replicasboolean
thresholdnumber
waitMsnumber

Answerer

type Answerer = object;

A persona as the holder may answer as it: its id and name.

Properties

PropertyType
idstring
namestring

Asked

type Asked = object[];

What a site asked for, as the screens show it before the holder decides: from a document, or (persona) stated by the holder as a persona.

Type Declaration

NameType
credentialobject
credential.subtitlestring
credential.titlestring
pathsstring[][]
persona?object
persona.idstring
persona.namestring
witness?string

Bequest

type Bequest = object;

What a beneficiary's device shows of a legacy: only once told, or once received.

Properties

PropertyType
error?string
fromobject
from.contact?string
from.namestring
note?string
received?string
secrets?string[]
seriesstring
toldboolean

Bringing

type Bringing = object;

A passkey the holder brought in that opens a second keyring (findWithPasskey): what merging does, and doing it.

Properties

PropertyType
planMergePlan

Methods

apply()
apply(): Promise<void>;
Returns

Promise<void>

cancel()
cancel(): void;
Returns

void


CheckSetup

type CheckSetup = object;

What the release watch checks (service/pages.ts): the release keys pinned (the key that signs now, then its successor) and the origins checked (by the manifest's names, with where to fetch each).

Properties

PropertyType
keysreadonly ReleaseKey[]
test?boolean
whereRecord<string, string>

CodeOutcome

type CodeOutcome = 
  | {
  id: string;
  kind: "added" | "restored" | "here";
  name: string;
}
  | {
  code: string;
  here: string;
  id: string;
  kind: "conflict";
};

What a recovery code entered here did, once the holder is reached.


Contact

type Contact = Omit<ContactView, "devices" | "out"> & object;

A contact, as the screens show it. waiting: chosen here, not in the keyring yet. out: their devices that no longer stand here (their root said so, or known only through one that no longer stands), each with its bond if it's kept. rootBeside: their devices bonded here that tell a root other than the one kept for them (prd.md §7.12): a ceremony with one of theirs settles which is theirs.

Type Declaration

NameType
devicesContactDeviceHere[]
out?ContactDeviceOut & object[]
rootBeside?string[]
waiting?boolean

ContactDeviceHere

type ContactDeviceHere = ContactView["devices"][number] & object;

A contact's device, as the screens show it: with this device's bond with it, if there is one.

Type Declaration

NameType
bondId?string

ContactList

type ContactList = object;

The holder's contacts, the bonds with someone else's devices that belong to none yet, and untold: contacts none of the holder's devices is bonded with now that a device was removed or left stranded, who couldn't be told it's no longer theirs; untoldUnknown: this device couldn't work out its group, so it can't tell who was told (every contact with a device is in untold then: review R8-31). disputed: contacts whose devices disagree about one of theirs (review R8-37: a device one of theirs lists and another no longer does). toTell: the holder's devices removed or left stranded that their root hasn't yet told their contacts are no longer theirs (prd.md §7.12: "Tell your contacts", a root act: service/root.ts tellContacts), where they have a contact with a device.

Properties

PropertyType
contactsContact[]
disputed?object[]
toTell?object[]
unsortedBond[]
untold?object[]
untoldUnknown?true

CustodyPublic

type CustodyPublic = Pick<CustodyNote, 
  | "epoch"
  | "threshold"
  | "count"
  | "waitMs"
  | "dealt"
  | "by"
  | "replicas"
  | "contacts"
  | "root"> & object;

The dealing to custodians, less its secrets (prd.md §7.11): what's read without the gate.

Type Declaration

NameType
custodiansnumber

DealingView

type DealingView = object;

A dealing as the dealer sees it: each custodian by contact.

Properties

PropertyType
byThisDeviceboolean
countnumber
custodiansobject[]
dealtstring
epochstring
replicasboolean
thresholdnumber
waitMsnumber

Froze

type Froze = object;

What a freeze did (prd.md §7.10): how many store copies it froze, and how many the store didn't answer for (owed: each owed until it's frozen, tried again at every refresh and on a push, even while frozen: service/renewals.ts; review R7-8), and how many were gone from the store already (gone: deleted, perhaps by someone holding one of the holder's devices; every device takes that as frozen: review R8-40). This device is frozen either way.

Properties

PropertyType
copiesnumber
gone?number
owednumber

FrozenHere

type FrozenHere = object;

A freeze as this device keeps it (HolderState.frozen): the freezes in force (ids), the first one's when (ms), why, where and the device reported, if any; the roots this device trusted at the time (a recovery made elsewhere ends the freeze here only if signed by one of them: freeze.ts); and, once it's seen its copies retired, where and when the holder recovered.

Properties

PropertyTypeDescription
atnumber-
codes?string[]Code copies (their store ids) this device knew before the freeze: where it trusted no root yet, a recovery is taken at a ceremony, in person.
idsstring[]-
late?objectA bonding whose keyring exchange landed here after its ceremony's time (holder.ts CEREMONY_MS): it ended nothing, so the holder is told to bond again (review R9-18), never left frozen unsaid. The device's name, and when.
late.atnumber-
late.namestring-
lost?string-
lostInstall?objectThe device reported lost, by its install (review R8-11): recovery marks it by install, never by a name.
lostInstall.didstring-
lostInstall.static?string-
on?string-
recovered?object-
recovered.atnumber-
recovered.onstring-
shut?string[]The bonds (ids) with the holder's own devices when this device froze: none carries anything, ever, until a ceremony replaces it.
trusted?TrustedRoots-
why"lost" | "not-me" | "holder" | "seen"-

GateStatus

type GateStatus = "ready" | "no-lock" | "unavailable" | "browser";

Whether secrets can be gated here: 'ready' (a phone with a lock), 'no-lock', 'unavailable', or 'browser' (sealed, no prompt).


GiveAsk

type GiveAsk = object;

A browser's hand-over code, connected: the six digits, what the relay said of the browser's network, when the holder may say yes (E_TOO_SOON before), the check that the browser is near (always needed: needsProof; Web Bluetooth or Web NFC, proofKind; none possible, unoffered: only give({ without: true }) gives), and the holder's answer; "This wasn't me" cancels and notes it (give-reported).

Properties

PropertyTypeDescription
codestring-
needsProoftrue-
network?Network-
placePromise<GivePlace | undefined>The browser's place beside this phone's, where the browser sent one (its toggle on) and this phone read its own (read only then, in the foreground); undefined otherwise. Information only: never the check.
proofKind?ProximityKind-
provingPromise<Proximity>-
unoffered?true-
yesAtnumber-

Methods

cancel()
cancel(): void;
Returns

void

give()
give(o?): Promise<void>;

Gives, behind the gate. Rejects E_TOO_SOON before yesAt; E_PROXIMITY where the browser wasn't heard, unless without.

Parameters
ParameterType
o?{ without?: boolean; }
o.without?boolean
Returns

Promise<void>

notMe()
notMe(): Promise<void>;
Returns

Promise<void>

prove()
prove(): Promise<Proximity>;
Returns

Promise<Proximity>

unusable()
unusable(): GiveUnusable[];

Each signal that couldn't be used, as things stand (the proof's last answer, the place once read): for the warning before "without".

Returns

GiveUnusable[]


GivePlace

type GivePlace = object;

The browser's place beside this phone's (both coarse): roughly together or not, and how far apart (km). Shown, never kept.

Properties

PropertyType
kmnumber
nearboolean

GiveSignal

type GiveSignal = "bluetooth" | "nfc" | "location" | "network";

A signal on the hand-over, as the holder knows it: the browser's Bluetooth (gatt), NFC (ndef), place, and the relay's word on its network.


GiveUnusable

type GiveUnusable = object;

Properties

PropertyType
signalGiveSignal
whyGiveUnusableWhy

GiveUnusableWhy

type GiveUnusableWhy = 
  | "browser"
  | "off"
  | "refused"
  | "phone"
  | "phone-off"
  | "not-heard"
  | "different"
  | "unknown";

Why a signal couldn't be used: 'browser', the browser hasn't it (or didn't say); 'off', its toggle left off on the page; 'refused', the browser's permission refused or nothing read there; 'phone', this phone hasn't it (or couldn't read its place); 'phone-off', location off on this phone or not allowed to kivi; 'not-heard', tried and not heard; 'different', another network; 'unknown', the relay didn't say.


GroupSignAsk

type GroupSignAsk = object;

What a member is asked to agree to, as their screen shows it before they decide.

Properties

PropertyType
actor?string
change?object
change.addednumber
change.membersnumber
change.removednumber
change.thresholdnumber
groupstring
labelstring
scope?string[]
site?string
until?number

HeldLegacy

type HeldLegacy = object;

A legacy share held here for someone, as its custodian sees it: whose (their contact), the terms, and where it stands. quiet: they've been active within the period (nothing to do). may-agree: the period has passed. agreed: this custodian agreed, and waits for enough others. window: enough agree; the release goes at ends unless they show a sign of life. released. unreadable: what's needed couldn't be read just now, so nothing moves.

Properties

PropertyType
addedAtstring
contact?object
contact.idstring
contact.namestring
countnumber
ends?number
idstring
quietMsnumber
state"quiet" | "may-agree" | "agreed" | "window" | "released" | "unreadable"
thresholdnumber
windowMsnumber

HeldShare

type HeldShare = object;

A custodian's view of a share held for someone: whose, by contact (prd.md §7.12).

Properties

PropertyType
addedAtstring
contact?object
contact.idstring
contact.namestring
copy?boolean
countnumber
dropped?string
epochstring
holderShareCredential["holder"]
idstring
indexnumber
pending?ShareCredential["pending"]
thresholdnumber
waitMsnumber

HolderAsk

type HolderAsk = 
  | {
  asked: Asked;
  bond: Bond;
  personas: Answerer[];
  request: Extract<BondRequest, {
     kind: "openid4vp";
  }>;
  type: "proof";
  approve: Promise<void>;
  decline: void;
  reveal: Promise<Revealed>;
}
  | {
  bond: Bond;
  request: Extract<BondRequest, {
     kind: "return";
  }>;
  type: "return";
  approve: Promise<void>;
  decline: void;
}
  | {
  bond: Bond;
  site: string;
  type: "grant-key";
  approve: Promise<void>;
  decline: void;
}
  | {
  bond: Bond;
  by?: string;
  count: number;
  name: string;
  threshold: number;
  type: "group-invite";
  approve: Promise<void>;
  decline: void;
}
  | {
  bond: Bond;
  by?: string;
  group: string;
  label: string;
  site: string;
  type: "group-site-key";
  approve: Promise<void>;
  decline: void;
}
  | {
  asked: GroupSignAsk;
  bond: Bond;
  by?: string;
  type: "group-sign";
  approve: Promise<void>;
  decline: void;
}
  | UseHolderAsk
  | ProgramAsk
  | SshRingAsk
  | {
  bond: Bond;
  choices?: number[];
  id: string;
  name: string;
  network?: Network;
  platform?: string;
  readyAt?: number;
  type: "bond-held";
  via: string;
  decline: void;
  mine: void;
  notMine: void;
  shown: number;
};

A bonded device's request that only the holder can answer, put to them by the app's screens. Each is answered once: approve (which may ask the gate, and rejects, E_CANCELLED and the like, leaving it still asked) or decline.

Union Members

Type Literal
{
  asked: Asked;
  bond: Bond;
  personas: Answerer[];
  request: Extract<BondRequest, {
     kind: "openid4vp";
  }>;
  type: "proof";
  approve: Promise<void>;
  decline: void;
  reveal: Promise<Revealed>;
}

A site's request from a bonded computer: what it asks (asked), the other personas the holder may answer as (approve's persona), and what a persona would answer with (reveal, through the gate).


Type Literal
{
  bond: Bond;
  request: Extract<BondRequest, {
     kind: "return";
  }>;
  type: "return";
  approve: Promise<void>;
  decline: void;
}

Type Literal
{
  bond: Bond;
  site: string;
  type: "grant-key";
  approve: Promise<void>;
  decline: void;
}

A contact asks for this holder's key at a site, to let them act for the contact there (prd.md §7.13).


Type Literal
{
  bond: Bond;
  by?: string;
  count: number;
  name: string;
  threshold: number;
  type: "group-invite";
  approve: Promise<void>;
  decline: void;
}

A contact (by, as the holder knows them) invites this holder into a shared identity (prd.md §7.14): its name, and how many of how many must agree.


Type Literal
{
  bond: Bond;
  by?: string;
  group: string;
  label: string;
  site: string;
  type: "group-site-key";
  approve: Promise<void>;
  decline: void;
}

A member of a shared identity asks for this holder's key at a site, for the group: it says who they are there to the other members.


Type Literal
{
  asked: GroupSignAsk;
  bond: Bond;
  by?: string;
  type: "group-sign";
  approve: Promise<void>;
  decline: void;
}

A member asks this holder to agree: a grant for the group at a site, or a change of its members.


UseHolderAsk

Another of the holder's devices asks to use a secret kept here (uses.ts), or tells of one asked for that this device doesn't keep.


ProgramAsk

A program on this device asks for a secret kept here, or a signature with one (programs.ts).


SshRingAsk


Type Literal
{
  bond: Bond;
  choices?: number[];
  id: string;
  name: string;
  network?: Network;
  platform?: string;
  readyAt?: number;
  type: "bond-held";
  via: string;
  decline: void;
  mine: void;
  notMine: void;
  shown: number;
}

Another of the holder's devices (bond) says a device joined it without proving it's near, and is held for an hour (service/bonds.ts): name and platform, the network it was on as the relay said, and three numbers, one of them the one via shows. mine(chosen): it's the holder's, released there if the number's right; notMine(): "This wasn't me", removed there; decline(): no answer now, the hour runs. shown(): the screen says it's in front of the holder (review R2-2), and readyAt (ms, the service's clock) is a moment from then: mine refuses before it (E_TOO_SOON), the holder reads first (review M9).


HolderState

type HolderState = object;

What a device keeps of the holder's wellknown.id: the default persona's seed, sealed by this device's gate; this device's own merged keyring (prd.md §4.10), sealed under a key from that seed, so it opens only once the gate has opened the seed; and, on a phone, each persona's records keys and the list of personas, sealed by a hardware key without a prompt (never in the clear). Private to the device.

Properties

PropertyTypeDescription
browsersNear?object[]Browsers paired with this phone (Ben's decision of 2026-10-16; service/sign-in.ts): each a browser's id (as its pages said it, pages/proximity.ts) whose Web Bluetooth or Web NFC check this phone heard, on the hand-over or after it. A sign-in page from one of these is checked that way again (it can without a prompt); from any other, by the network word. Kept on this device only, never sent; the newest 32.
codesChecked?numberWhen the recovery-code copies were last checked against the keyring here (ms; keyring-holder.ts checkCodes).
credentialId?stringThe passkey that reached the seed, where one did; with until, the end of its session where the app keeps the seed only for a while (the sign-in pages' unlock session, keyring-holder.ts sessionMs).
custodyQuiet?stringOn a phone: the dealing's quiet part (service/holder.ts CustodyQuiet), sealed by the quiet sealer, so notices are read without the gate.
frozen?FrozenHereThe holder's wellknown.id is frozen, as this device knows (prd.md §7.10, the freeze; freeze.ts): until recovery ends it here, or a ceremony brings a recovery made elsewhere, this device writes, signs, shares and sends nothing.
how"passkey" | "recovery-code" | "new" | "bond" | "custodians" | "browser"-
keyring?stringThe keyring as this device last had it (base64: keyring.ts sealKeyringHere under the seed).
later?string[]-
laterKey?stringOn a phone: the public key what bonded devices send about personas while the gate is closed is sealed to (persona-bonds.ts laterKeys, from the default's seed; base64), and what's waiting, sealed (sealForLater), merged the next time the gate opens the seed.
legacyNotices?LegacyNotice[]-
legacyQuiet?stringOn a phone: the legacy dealings' quiet parts (service/holder.ts LegacyQuiet), sealed by the quiet sealer.
legacySeq?Record<string, number>Each legacy notice box, as far as this device has read it (by series), and what custodians said there.
lifeAt?numberWhen this device last wrote a sign of life (prd.md §7.11, legacy; ms).
mailboxes?object[]On a phone: each held persona's records keys (seed.ts recordsKeys), the default's first, sealed by the quiet sealer (base64), with the persona's id. Absent in a browser, where they come from the seeds.
notices?RecoveryNotice[]-
noticeSeq?numberThe notice box, as far as this device has read it (the item sequence), and the recoveries it has heard of.
openRoot?stringA new holder's root, before it has any way in (no recovery code, no devices together, no custodians yet), sealed by the gate: there's nothing yet to rebuild it from, so it's kept here until the first way is dealt (service/root.ts).
rcHash?stringThe keyring last written to its recovery copy (a hash), so it's written again only when it changes (root.ts).
recoveredBy?stringThe recovery this device got back in by (its id): its notices are this device's own, not one to stop.
recoveryPasskeys?stringThe passkeys a recovery here made before it stopped (keyring-holder.ts recover; review R9-17), sealed under the default's seed as a keyring holding only them: the next recovery retires their copies with the old ones (each held the keyring, outside every keyring after). Let go once a recovery finishes.
redeal?stringBack in through custodians (prd.md §7.11): the dealing whose shares travelled, until one is dealt again (here or on another of the holder's devices). Until then those shares still open the keyring as it was.
regroup?numberSince when (ms) the holder's own devices count again only by a ceremony (after a recovery: prd.md §7.10): a "mine" or limited bond made before, or made from the log at all, carries nothing either way until a ceremony makes it again.
regroupShut?string[]The bonds (ids) with the holder's own devices that a recovery shut (regroup): each carries nothing until a ceremony replaces it.
removals?KeyringRemoval[]The keyring's removal list (keyring.ts Keyring.removed), kept beside it unsealed (dids and static keys only, which the log holds too), so who's out is known without the gate (service/removals.ts): a phone whose gate is shut acts on what it last knew. The list in force only (removalsAfter); grows only, until a recovery starts it again; what's here and not yet in the keyring goes into it at its next keep.
removalsAfter?stringThe recovery whose removal list removals is (freeze.ts removalEpoch); none: the list from before any recovery.
removalsPending?KeyringRemoval[]Removals heard on the list in force that this device can't judge yet (holder.ts judge, review R9-22: a mutual pair, or a maker that counts here only through a device in question): shown, both sides shut at the gate, judged again at every read until taken or dropped, or the holder settles them here.
removalsUnjudged?numberSince when (ms) removals heard here couldn't be judged (the logs unreadable): the gate refuses until they are (review R9-36).
renewals?Renewal[]What's left to finish after a recovery (service/renewals.ts; reviews R6-14, R6-41): each step tried again until it's done, and shown to the holder meanwhile. Kept across a keep anew; gone with the holder.
root?objectThe recovery root this device trusts (prd.md §7.8; root.ts): its id and extended public key. It judges a new root, a policy, a recovery by it: only one it signed for (root.ts trustedFrom) is taken. Public: an xpub makes public keys.
root.idstring-
root.xpubstring-
rootFailed?objectWhat the last root act here couldn't do (root-holder.ts RootFailure: a share not filed, a copy not re-keyed, a code removed whose copy isn't retired yet, the custodians not dealt), when: shown (RootView failed) until a root act here finishes with nothing left (review R8-23: every root act's failures said, never dropped).
rootFailed.atnumber-
rootFailed.failuresobject[]-
rootHere?stringThe holder's recovery root, rebuilt through their custodians while frozen (prd.md §7.11; root.ts), sealed by the gate (the quiet sealer on a phone): what ends the freeze there (service/freeze.ts), kept only until it has.
rootsFrom?numberWhich build kept this state (keyring-holder.ts ROOTS_FROM): one that takes no root by waiting. A state without it was kept by an earlier build, whose root the sign-in pages let go (review R8-21).
rootWaits?objectAn earlier build's wait for a root no root this device trusted signed for (since, ms). No root is taken by waiting any more (reviews R7-9, R7-31: the week and ROOT_WAIT_MS are gone): a wait kept here is let go at the next keep (keyring-holder.ts, root-holder.ts beside), and nothing takes the root it names.
rootWaits.idstring-
rootWaits.sincenumber-
rootWaits.xpub?string-
sealedSeedstringThe default persona's seed, sealed by the gate; how it was reached (bond: given by a bonded device, prd.md §4.10: one of the holder's own, or the device a limited one is limited to; browser: a seed made in a browser that can't do passkeys with PRF, kept there, the sign-in pages); since when.
several?booleanWhether the holder has more than one persona in use: all a sign-in page knows of them before the keyring opens.
shareHere?objectThis device's share of the recovery root it trusts (its devices way: root.ts), taken from where it waited in the store and kept sealed by the gate (the phone's hardware key, behind the biometric), never by the static key the dealing named (review: the recovery root's "Still open"). taken: the copy it waited in is removed (else tried again).
shareHere.rootstring-
shareHere.sealedstring-
shareHere.taken?boolean-
sincestring-
successors?SuccessorTrustsWhich successor (prd.md §4.12) this device trusts for each persona, by persona id, and one seen but not yet taken, since when (successor-trust.ts): hashes only. No device takes a new successor on the keyring's word alone.
summary?stringOn a phone: the list of personas (PersonaList: names, states, fingerprints, no seeds or keys), sealed the same way.
told?stringWhat the passkey providers were last told (passkeys.ts signalled), so they're told again only when it changes.
until?number-
unwritten?stringSince when (ISO) the last keyring change kept here couldn't be written to every passkey's copy: written with the next (review R5-15).
vaultKeys?stringThe vault keys (prd.md §7.11; custodians.ts): the recovery key and the secrets key, with the dealing's epoch, sealed under the default persona's seed as keyring is (never in the keyring, which a passkey opens). Only on the holder's own devices, brought by their bonds.
watch?stringOn a phone, sealed quietly: the store copies to watch for a freeze or a recovery elsewhere, each id and key (service/freeze.ts).
writer?stringThis device's writer id for keyring edits (keyring.ts newWriter).

Joining

type Joining = Omit<Joined, "confirm"> & object;

The side that joins, once connected: the six digits to compare, what the other side said, the proximity proof it can lead (bond.ts Joined), and the holder's answer. Bonding as someone else's, confirm takes the contact the other device belongs to (prd.md §7.12). confirm refuses before the bonding wait (YES_AFTER_MS) has passed since joining.

Type Declaration

NameTypeDescription
needsProofbooleanFor one of the holder's own devices: whether proximity must be proved before saying yes (a channel both sides share), and whether the proof failed (then only confirm({ without: true }) goes on, held for an hour).
proofKind?ProximityKindThe channel the proof uses (hearing the other, else being heard), so the screen can say how: undefined, none.
provingPromise<Proximity>The proof, started by the service as soon as the ceremony connects where one is needed (the devices check, not the holder: review D/M9); prove() tries again ("Check again"). Resolves 'none' when there's nothing to prove.
yesAtnumberWhen the holder may say yes (ms, the service's clock): three seconds after the screen first showed.
confirm()(o?) => Promise<Bond>-

LegacyNotice

type LegacyNotice = object;

A legacy custodian's agreement to a release, as the holder's notice box told this device (prd.md §7.11).

Properties

PropertyType
atnumber
bystring
contactstring
epochstring
seriesstring

LegacyPublic

type LegacyPublic = Pick<LegacyNote, 
  | "series"
  | "epoch"
  | "threshold"
  | "count"
  | "quietMs"
  | "windowMs"
  | "dealt"
  | "by"
  | "contacts"
  | "told"
| "replicas">;

A legacy dealing, less its secrets (prd.md §7.11): what's read without the gate, by the beneficiary's contact.


LegacyView

type LegacyView = object;

A legacy dealing, as the holder's devices show it: for whom, to whom, on what terms, and what's left to them.

Properties

PropertyTypeDescription
beneficiaryobject-
beneficiary.idstring-
beneficiary.namestring-
countnumber-
custodians?object[]Only on the device that dealt: each custodian's answer, as recovery's dealing view says it.
dealtstring-
epochstring-
quietMsnumber-
secretsobject[]The secrets kept here that are left to them, by name.
seriesstring-
thresholdnumber-
toldboolean-
windowMsnumber-

NoticeAlarm

type NoticeAlarm = object;

An alarm shown on every device (review R13-4): a site whose notice for persona persona's key there is someone else's; since at.

Properties

PropertyType
atstring
namestring
personastring
sitestring

OfferAsk

type OfferAsk = object;

An offer held here, put to the holder: keep it (behind the gate) or decline.

Properties

PropertyTypeDescription
bondBond-
contact?stringFrom someone else's device (a copy given, prd.md §7.14): their name as this holder knows them, where they're a contact.
offerOffer-

Methods

decline()
decline(reason): void;
Parameters
ParameterType
reasonstring
Returns

void

keep()
keep(): Promise<void>;

Keeps it here (the gate asks now, to seal it) and says so to the device that offered it. Rejects (E_CANCELLED…) and stays asked if it can't.

Returns

Promise<void>


OpenProgress

type OpenProgress = 
  | {
  notThere: {
     bond: Bond;
     device: string;
  };
}
  | {
  woken: {
     device: string;
     sent: boolean;
  };
}
  | {
  asking: string;
}
  | {
  waitingOn: string;
}
  | {
  tapRing: string;
}
  | {
  ring: RingProgress;
};

How opening a copy is going: a device not open (woken with a notification, or not), asking it, waiting on its holder; or a ring to tap, then how the tap is going once it's found.


PagesCheck

type PagesCheck = object;

Where the release watch stands, for the screens.

Properties

PropertyTypeDescription
checkingbooleanA check is running.
originsstring[]The origins it checks.
standing?Standing-
status"off" | "never" | "ok" | "differs"off: nothing to check here; never: no check has got an answer yet.
test?booleanPointed at a test stack (a development build).
unchecked?objectThe latest try got no answer: when, and why.
unchecked.atnumber-
unchecked.reasonstring-
webbooleanWhere this wallet runs, for what the screens say about the check's limits.

PasskeyUser

type PasskeyUser = object;

The WebAuthn user entity of a passkey made for a keyring (passkeys.ts passkeyUser): its ring as the handle, base64url.

Properties

PropertyType
displayNamestring
idstring
namestring

PendingRemoval

type PendingRemoval = object;

A removal this device can't judge yet (holder.ts judge; prd.md §7.10; review R9-22): its maker counts here, but a removal heard names it (a mutual pair), or it counts only through a device that's in question. Shown on every device that holds it, both sides shut at the gate, until the holder settles it (sync.ts settleRemoval). key: which entry; said: from the maker's log, not the keyring's list; here: it names this device.

Properties

PropertyType
atnumber
bystring
byName?string
byStatic?string
didstring
here?true
keystring
name?string
said?true
static?string

PersonaList

type PersonaList = object;

The personas as the screens show them, the passkeys that open the keyring, whether their names carry the default's name, the dealing, and the contacts (prd.md §7.12).

Properties

PropertyType
contacts?ContactView[]
custody?CustodyPublic
grants?GrantView[]
groups?GroupView[]
legacy?Record<string, LegacyPublic>
names?boolean
onlyWayInboolean
passkeysobject[]
personasPersonaView[]
root?RootView
rootTold?RootTold
tombs?ContactTombs

PolicyChange

type PolicyChange = 
  | {
  devicesK: number;
}
  | {
  addDevices: true;
}
  | {
  suggested: true;
};

A change to the recovery policy, as the holder asks for it: the devices way at k of its devices; the suggested devices way added; the suggestion taken whole.


ProgramAsk

type ProgramAsk = object;

What the holder's asked when a program on this device asks: what the program calls itself (claimed, its word: "not verified") and what the operating system says it is (os), and whether the two disagree (mismatch: a warning, not a refusal, decision 5); its key's thumbprint (key); what's asked, why, for once; the three numbers, one of which the program shows. shown(): the screen says when it's shown, and Accept works a moment after (readyAt, from then); twoStep: a secret leaving for an unverified program takes confirm() first (the holder reads what will happen); missing: asked for something kept nowhere (the holder sees it, the program learns only "no", as for any no: nothing tells it whether the name exists). notMe(): "This wasn't me": declined, noted in the holder's consents, and where to find the program (the ask is then withdrawn as 'reported', so the screen keeps it until the holder's read it: R2-12). lasts: a signature's yes may last this long (approve(n, true): a token for this program, R2-1). urgent: kivi desktop brings its window forward for it.

Properties

PropertyType
choicesnumber[]
claimed?string
countnumber
how"sign" | "share"
idstring
keystring
lasts?number
mismatchboolean
missingboolean
namesstring[]
os?ProgramRequester
purposestring
readyAt?number
twoStepboolean
type"program"
urgenttrue
verifiedfalse
withdrawnPromise<string>

Methods

approve()
approve(chosen, lasting?): Promise<void>;
Parameters
ParameterType
chosennumber
lasting?boolean
Returns

Promise<void>

confirm()
confirm(): void;
Returns

void

decline()
decline(reason?): void;
Parameters
ParameterType
reason?string
Returns

void

notMe()
notMe(): Promise<ProgramRequester | undefined>;
Returns

Promise<ProgramRequester | undefined>

shown()
shown(): number;
Returns

number


ProgramRequester

type ProgramRequester = object;

The program asking, as this device's operating system says (kivi desktop's peer.rs): path, the file it runs from, read when it connected (the one thing it can't say otherwise of itself); program, its command line, which a program can rewrite (process.title), so shown as its own words; from, the shell and folder it was run from; its pid, so the holder can find it.

Properties

PropertyType
from?string
path?string
pid?number
programstring
terminal?boolean

Recognising

type Recognising = object;

A recovery a custodian is taking part in, before confirming: the code to compare.

Properties

PropertyType
codestring
recoverystring

Methods

cancel()
cancel(): void;
Returns

void

confirm()
confirm(): Promise<void>;
Returns

Promise<void>


Recovered

type Recovered = RecoveryDone & object;

What a recovery made (RecoveryDone), and what followed in the wallet: the custodians dealt again (or not reached), the legacies renewed (ending: one that couldn't be dealt again, whose end is still owed), the grants given posted again under new write keys; and what's still owed (owed: service/renewals.ts), tried again until it's done.

Type Declaration

NameType
custody"none" | "dealt" | "ended"
grantsnumber
legaciesobject
legacies.dealtstring[]
legacies.endedstring[]
legacies.endingstring[]
owedRenewalView[]

Recovery

type Recovery = object;

A recovery begun on this device: the link to give custodians, the code, and how far it has got.

Properties

PropertyType
codestring
done?boolean
error?string
idstring
sharesnumber
sincestring
threshold?number
urlstring

RecoveryAnswers

type RecoveryAnswers = RecoveryPick & object;

A recovery's answers, as the screens give them (reviews R7-11, R7-23): the ids of the plan's items to drop (drop), a version of the keyring's recovery copy to go back to (version: every change since it undone, and drop besides), and the other devices bonded here the holder says may be in someone else's hands (remove, by bond id). The service works out what each does (recovery-choices.ts recoveryDrops): an id it didn't show, or a version it didn't offer, is refused.

Type Declaration

NameTypeDescription
remove?readonly string[]-
removeLost?booleanThe device the freeze reported lost (the plan's lost), bonded here or not: put out with the recovery (review R8-11) unless the holder says it's in their hands (false). The service's default, one for every screen (review R9-38: it was set three ways).

RecoveryFailure

type RecoveryFailure = object;

A step a recovery couldn't finish, for the screens to show (never swallowed: review R7-20): what, whose, why. One type, for the service and the pages (review R8-34).

Properties

PropertyType
errorstring
name?string
stepstring

RecoveryItem

type RecoveryItem = object;

One thing recovery shows: its id (what the holder's answer names), what it is, its name, when (ms, the writer's word), whether it's recent (since the freeze's window), and whether it may be dropped here (kept: why not). of: whose (a grant's or a device's contact); site: a grant's; what: a version's change to a persona (forgotten, renamed…).

Properties

PropertyTypeDescription
at?number-
idstring-
install?objectA way-device's install (its did:key and static key): what dropping it takes out of the devices way, read here, never parsed back from the id (review R8-34).
install.didstring-
install.staticstring-
kept?KeptWhy-
kindRecoveryItemKind-
namestring-
of?string-
recentboolean-
site?string-
was?string-
what?string[]-

RecoveryNotice

type RecoveryNotice = object;

A recovery under way, as a custodian's notice told this device (prd.md §7.11), and whether the holder stopped it.

Properties

PropertyType
atnumber
bystring
codestring
epochstring
recoverystring
stopped?number

RecoveryPick

type RecoveryPick = object;

The holder's answer: a version of the recovery copy to go back to (by when the store wrote it), and the ids of the items to drop. With a version, every change since it is undone (the version as it was), and drop names what else the holder drops of what's still to ask beside it (review R9-38: the union is the service's, never a screen's to restate; drop once replaced the version's own).

Properties

PropertyType
drop?readonly string[]
version?number

RecoveryPlan

type RecoveryPlan = object;

What recovery will show before it's made: what changed lately, the personas (for choosing the default), and, once the root is rebuilt (openRecovery), the keyring's recovery copy's versions, each with what changed since it.

Properties

PropertyTypeDescription
custodiansboolean-
itemsRecoveryItem[]Everything a thief could have planted, each kept unless the holder's answer drops it by id (recovery-choices.ts; reviews R7-11, R7-23).
lost?objectThe device a freeze reported lost or stolen, by its install (review R8-11): for the screens to offer marked, on any device or the sign-in pages; the holder's mark (recover's lost) puts it on the new removal list. The reporter's word: a thief may name the holder's own phone (review R6-44), so it's the holder's to keep or mark.
lost.didstring-
lost.namestring-
lost.static?string-
personasobject[]-
policy?PolicyThe recovery policy the root this device trusts holds: what the new root is made with (its devices among items).
versions?VersionOffered & object[]The recovery copy's versions to offer, once the root is rebuilt (review R8-25: the service decides, the screens draw): each with what going back to it undoes (items) and what's still to ask beside it (ask: review R8-26). Only those with something to undo; never capped.

RecoveryView

type RecoveryView = RecoveryPlan & object;

A recovery's plan, as the screens draw it: what changed, everything a thief could have planted (items), the versions, and the holder's own devices bonded here.

Type Declaration

NameType
devicesobject[]

ReleasePorts

type ReleasePorts = object;

What the release watch needs from the platform: what to check, a fetch, and somewhere to keep its state.

Properties

PropertyTypeDescription
fetchReleaseFetchA fetch for the check: fresh (no cache), no credentials, a timeout; rejects when there's no answer.
webbooleanThis wallet is the web app (what the screens say about the check's limits).

Methods

load()
load(): Promise<unknown>;

What the watch keeps between checks, on this device only.

Returns

Promise<unknown>

save()
save(state): Promise<void>;
Parameters
ParameterType
stateunknown
Returns

Promise<void>

setup()
setup(): CheckSetup | undefined;

What this device checks; undefined: nothing here.

Returns

CheckSetup | undefined


Renewal

type Renewal = object;

A step still owed after a recovery (service/renewals.ts): its kind and key (id: one per thing, so owing it twice owes it once), whose it is for the screens (name: a beneficiary, a site, a group), since when (ms), how many times it was tried and why it last failed; what it needs (sealed: a key, ids), sealed by the quiet sealer (the gate's, in a browser), never in the clear.

Properties

PropertyType
idstring
kindRenewalKind
last?string
name?string
sealed?string
sincenumber
triesnumber

RenewalKind

type RenewalKind = 
  | "retire"
  | "remove"
  | "renew"
  | "legacy-end"
  | "grant"
  | "freeze"
  | "passkey-copy"
  | "removal"
  | "after-keep"
  | "sign-in-record";

retire: old copies taken out of the store under a key a lost device knew (the secrets vault's, a legacy's content); remove: an old copy removed by its write key (a dealing's vault, a legacy's head); renew: a part's renewal after a recovery that failed before it began (the secrets vault or the legacies, re-keyed); legacy-end: a legacy that couldn't be dealt again, ended; grant: a grant given, posted again under a write key the lost device never held; freeze: a store copy a freeze couldn't reach, frozen (the one step that runs while frozen: review R7-8); passkey-copy: a recovery's new passkey's copy of the keyring, written again until it's there (review R7-20). A freeze owed carries the freeze's note where its copy's keyring didn't take it either: written first, then the copy frozen (R8-3). removal: a removal of one of the holder's devices whose write into the keyring's store copies didn't land (the gate declined, a copy unwritten: holder.ts writeRemovals E_UNWRITTEN; review R8-28: noted beside the keyring here, it goes with the next change; owed, so it's said and tried until it's there), or, with a bond's id, a removal a recovery couldn't make at all (removed then written). sign-in-record: a sign-in's record (or a promotion's) the store didn't take, filed again at every refresh (review R13-6: a rotation isn't begun while one is owed).


RenewalView

type RenewalView = Omit<Renewal, "sealed"> & object;

A step as the screens show it: what, whose, since when, tried how often, why it last failed; holder: it waits for the holder (the gate) to run.

Type Declaration

NameType
needs"nothing" | "holder"

Revealed

type Revealed = Record<string, string>;

What a persona would answer with, by claim path joined with "/" (prepareAnswer's reveal).


RingOptions

type RingOptions = object;

What each ring operation takes besides its own: how the tap is going.

Properties

PropertyType
progress?(p) => void

RingProgress

type RingProgress = object;

Properties

PropertyType
at?number
of?number
stepRingStep
wordsstring

RingSecret

type RingSecret = object;

What a copy on a ring holds, sealed: enough to bring the secret back on a new device.

Properties

PropertyType
copystring
fileName?string
namestring
secretTypeSecretCredential["secretType"]
service?string
slot?number
valueUint8Array

RingStep

type RingStep = "found" | "pin" | "key" | "write" | "check" | "open" | "sign";

How a tap is going, once the ring is found (before then, the platform asks the holder to hold it): what the ring is doing now, in the holder's words (words, said on iOS's NFC sheet too), and for opening several copies, which of how many. Ring work is slow (a key made on the ring takes seconds), so the holder hears each step.


RingView

type RingView = object;

A ring the holder added, as their devices' logs say: by, the device that last said it ('' for this one); tapCopies, whether it may keep copies a tap alone opens (no PIN key on it, nothing noted here as on it, or a copy here noted under another key): "Put its copies behind the PIN" (lockCopies) is for those.

Properties

PropertyType
addedstring
bystring
idstring
namestring
securityKey?RingRecord["securityKey"]
slotsRingSlot[]
tapCopiesboolean

RootPublic

type RootPublic = RootView & object;

The root as the screens show it (root-holder.ts RootView), with what the holder's group says of the devices way, and the policy suggested.

Type Declaration

NameTypeDescription
gatherednumberShares gathered here in person, for the next root act (gather), and how many the devices way needs.
joinableobject[]The holder's own devices bonded here that the devices way doesn't name (kivi offers to add them: decision 5).
needed?number-
suggestedPolicyThe policy suggested from what the holder has (decision 3).

RootView

type RootView = object;

A root as this device has it: trusted, one it could take, or open (a new holder's, before any way in).

Properties

PropertyTypeDescription
adopt?trueTrusting none, the keyring holds the holder's root made with a code from before it (blockingRoot): this device takes it by a code typed here (or in person), and makes no first root of its own without one (E_ADOPT). A first root nothing vouched for (waiting alone) is no reason to: a root act here makes the holder's own beside it (review R9-28).
beside?RootSeen[]The alarm: unreached but for those fork says (a fork on this device's own chain is said as such, rejoined by a code), newest first. The service's word for both apps (review R9-38: the IdP hid every one where there was a fork).
clash?trueTwo different entries were seen for the root this device trusts, both signed by it: someone else has rebuilt it (keyring.ts rootClash: the other entry kept as evidence, checked; review R8-8). Making the root anew clears it.
failed?RootFailure[]What the last root act here couldn't do (HolderState.rootFailed; review R8-23), until one finishes with nothing left.
fork?RootSeen[]The roots past a fork on this device's chain (a root that signed for two: review R8-5, R8-7): followed by none here; each taken only in person, or by a code of its way typed here. Among unreached too.
kept?trueThe root is kept on this device, sealed behind its gate, since custodians released it (HolderState.rootHere; review R7-15): until the custodians are dealt again, which makes the root anew and lets it go.
open?boolean-
owed"custodians"[]A way the policy names that this root hasn't dealt yet: the custodians (dealt again from kivi, a root act).
staleobject[]The devices way's installs the keyring's removal list now names: each still holds a share of this root (worthless alone) until it's made anew.
trusted?RootSeen & object-
unreached?RootSeen[]Trusting one: roots in the keyring its chain doesn't reach (review R7-9): made beside the holder's root, by someone holding one of their devices, or by one of their own devices alone. An alarm: never taken, by any device, but in person.
waiting?RootSeenTrusting none: the newest first root the keyring holds whose entry verifies, which this device takes only in person (shown by a device that trusts it) or with a code of its way typed here; never by waiting (reviews R7-9, R7-31).

RotationSite

type RotationSite = object;

A site in a rotation, as kivi shows it: reason for refused and unreachable; at when that was last noted.

Properties

PropertyType
at?number
reason?string
sitestring
statusSiteStatus
via?"receiver" | "mailbox" | "notice"

RotationView

type RotationView = object;

A persona's rotation (or burn) as it stands: its sites. A rotation's persona is the one it promoted to (the successor, at once), and next the successor after it (S′'s xpub).

Properties

PropertyType
idstring
kind"rotation" | "burn"
next?string
personastring
sitesRotationSite[]

Say

type Say = (key, values?) => string;

Puts one of the service's words (SayKey) in the holder's language, with its values filled in.

Parameters

ParameterType
keySayKey
values?Record<string, string | number>

Returns

string


SayKey

type SayKey = 
  | "reason.fields"
  | "reason.shareFields"
  | "reason.reveal"
  | "error.noFields"
  | "reason.keep"
  | "reason.default"
  | "reason.records"
  | "reason.personas"
  | "reason.recoveryCode"
  | "reason.give"
  | "reason.rootShare"
  | "reason.freeze"
  | "reason.recover"
  | "error.frozen"
  | "material.bond"
  | "material.remove"
  | "material.recover"
  | "material.upgrade"
  | "material.makeCode"
  | "material.removeCode"
  | "material.sheet"
  | "material.policy"
  | "material.renew"
  | "material.deal"
  | "material.addDevice"
  | "material.share"
  | "material.vouch"
  | "material.tellContacts"
  | "material.addPasskey"
  | "material.legacy"
  | "material.grant"
  | "material.ring"
  | "material.give"
  | "material.givePersonas"
  | "material.addRing"
  | "root.none"
  | "root.notOpened"
  | "root.wrong"
  | "root.wayNeeded"
  | "root.noVersion"
  | "root.inPerson"
  | "root.notInWay"
  | "root.older"
  | "root.codesLeft"
  | "root.otherInUse"
  | "reason.signIn"
  | "reason.bond"
  | "reason.givePersonas"
  | "reason.deal"
  | "reason.keepShare"
  | "reason.stop"
  | "reason.recoverable"
  | "reason.contacts"
  | "reason.keepLegacyShare"
  | "reason.legacy"
  | "reason.releaseLegacy"
  | "error.notBeneficiary"
  | "error.shortQuiet"
  | "error.noHolder"
  | "error.badRecoveryCode"
  | "error.notReached"
  | "error.noPersona"
  | "error.badRecoveryLink"
  | "error.noRequest"
  | "error.notCustodians"
  | "error.shortWait"
  | "error.noContact"
  | "pages.refused"
  | "custody.noScreenLock"
  | "custody.notShared"
  | "reason.grant"
  | "reason.grantBack"
  | "reason.grantDrop"
  | "reason.grantKeep"
  | "reason.grantForget"
  | "reason.grantKey"
  | "grants.noConfig"
  | "grants.notAccepted"
  | "grants.noContact"
  | "grants.unknownScope"
  | "grants.tooLong"
  | "grants.noDevice"
  | "grants.noAnswer"
  | "grants.unknown"
  | "grants.notAContact"
  | "grants.notForMe"
  | "shares.noContact"
  | "shares.noSecret"
  | "shares.noDevice"
  | "reason.groupFound"
  | "reason.groupJoin"
  | "reason.groupNews"
  | "reason.groupSite"
  | "reason.groupAgree"
  | "reason.groupGrant"
  | "reason.groupChange"
  | "groups.unknown"
  | "groups.noDevice"
  | "groups.noAnswer"
  | "groups.noName"
  | "groups.badThreshold"
  | "groups.notEnough"
  | "groups.notSigned"
  | "groups.notAContact"
  | "groups.notAgreed"
  | "groups.notFounded"
  | "groups.notMember"
  | "uses.shareReason"
  | "uses.tooOld"
  | "uses.nowhere"
  | "uses.notAKey"
  | "uses.wrongAlg"
  | "uses.tooLong"
  | "ring.restoreReason"
  | "ring.hold"
  | "ring.step.found"
  | "ring.step.pin"
  | "ring.step.key"
  | "ring.step.write"
  | "ring.step.check"
  | "ring.step.open"
  | "ring.step.openOf"
  | "ring.step.sign"
  | "ring.noNfc"
  | "ring.notKeeper"
  | "ring.notThisRing"
  | "ring.noCopy"
  | "ring.needsPin"
  | "ring.unknown"
  | "ring.blocked"
  | "secrets.notBonded"
  | "successor.oldSheetNeeded"
  | "successor.wrongSheet"
  | "successor.checkWrong"
  | "successor.notMade"
  | "successor.restoreInstead"
  | "successor.noRoot"
  | "successor.unread"
  | "successor.changeWaiting"
  | "freeze.notOwed"
  | "material.rotate"
  | "material.burn"
  | "rotation.unfiled"
  | "rotation.none"
  | "notice.unread"
  | "notice.unfiled"
  | "notice.planted"
  | "rotation.recordsOwed"
  | "ssh.noKey"
  | "ssh.purpose"
  | "ssh.purposeAny"
  | "ssh.declined"
  | "ssh.ringGone"
  | "ssh.hostMismatch"
  | "ssh.hostRevoked"
  | "uses.noMatch"
  | "uses.refusedByRules"
  | "bonds.wait"
  | "bonds.proximity.needed"
  | "signin.proximity.needed"
  | "give.proximity.needed"
  | "bonds.limited.alreadyOwn"
  | "bonds.alreadyLimited"
  | "bonds.limitedElsewhere"
  | "bonds.removedPeer"
  | "bonds.removedHere"
  | "reason.removeDevice"
  | "programs.readFirst"
  | "programs.noMatch"
  | "programs.shareReason"
  | "programs.declined"
  | "programs.nothingBack"
  | "programs.tooMany"
  | "programs.gone"
  | "programs.confirmFirst"
  | "programs.needsNumber"
  | "reason.addresses"
  | "addresses.unavailable"
  | "addresses.notAnAddress"
  | "addresses.noCode"
  | "addresses.badLink"
  | "addresses.gone"
  | "addresses.badCode"
  | "addresses.notFound"
  | "addresses.tooMany";

The words the service puts in front of the holder: the gate's prompts, and errors. In the holder's language.


Secret

type Secret = object;

A secret as the holder enters it: its name, kind and value, and where it's for.

Properties

PropertyType
copyOf?string
fileName?string
namestring
secretTypeSecretCredential["secretType"]
service?string
valueUint8Array

SecretElsewhere

type SecretElsewhere = object;

Where a copy kept on another of the holder's devices is: that device, when it last said, and whether it's bonded with this one.

Properties

PropertyType
bondedboolean
devicestring
updatedstring

SecretGroup

type SecretGroup = object;

A secret's copies (the one here first), and the rings keeping one: mine where this device put it there.

Properties

PropertyType
copiesSecretListing[]
ringsobject[]

SecretListing

type SecretListing = object;

One copy of a secret, as listed: its record (a catalogue entry is shaped like one), where it is if not here, and, for the copy a group opens from a keeper ring, which ring copy and whether its key takes the ring's PIN.

Properties

PropertyType
on?SecretElsewhere
ring?object
ring.copystring
ring.namestring
ring.needsPinboolean
ring.ringstring
sSecretCredential

ServiceEvent

type ServiceEvent = 
  | "log"
  | "bonds"
  | "offers"
  | "pages"
  | "holder"
  | "records"
  | "custody"
  | "contacts"
  | "legacy"
  | "grants"
  | "groups"
  | "reveal"
  | "heard";

What changed, for screens to read again: the log (and so the secrets catalogue), bonds, offers held, the release watch, the holder's state here, the personas' records (this device's consents filed in them), the custodians (shares offered, held or released, a dealing, a recovery under way, prd.md §7.11), the contacts (§7.12).


ServicePorts

type ServicePorts = object;

Everything the service needs from the platform, and nothing else: an app supplies these adapters (a browser's, a phone's, an in-memory set for tests) and the service does the rest.

Properties

PropertyTypeDescription
bondingLimits?() => objectBonding's waits, for tests and the browser tests' build: how long a bonding's yes waits after its screen shows (bonds.ts YES_AFTER_MS by default), and how long a "mine" bond without proximity is held (HOLD_MS by default).
bondsBondStore & LogStore & OfferStoreBonds (with update), the sync log, offers held.
clock?ClockThe time; tests move it.
credentialsCredentialStoreDocuments, secrets' notes, consents.
custodyLimits?() => objectThe wait a dealing may be made with, at least (prd.md §7.11: 72 hours); a development build's tests shorten it.
deviceDeviceWhat this device calls itself, and its platform.
directory?DirectoryClientwellknown.id's blinded directory, the addresses' inboxes and parcels at the relay (borrowed.ts directoryClient; docs/plans/borrowed-device.md). None: addresses can't be linked here, and nothing is collected.
dropsDropStoreDrop boxes at the relay: what bonded devices leave for this one while it's away.
fetchtypeof fetchFetch, for sites' privacy declarations, witnesses' discovery, grants' mailboxes and issuers' keys. Required (review R2-8): the app passes its platform's (kivi: platformFetch), so the service never falls back to a global itself.
gateSealerThe biometric gate (a browser: a non-extractable key, no prompt). Seals secrets and the holder's seed.
holderStateHolderStoreThe holder's state on this device (the default persona's sealed seed, this device's keyring copy).
keysKeyStoreThe device's identity key and credential keys.
location?LocationPortThis device's place, coarse (proximity/place.ts), read in the foreground only, and only on the hand-over to a browser that sent its own (its toggle on): compared here, never sent or kept. None: no comparison (kivi on the web).
loopback?booleanA development build (kivi: __DEV__): a site's config may name a mailbox on this machine (http://localhost, 127.0.0.1, [::1]) for its notices and events. Never in a release (review R13-9: a site's config naming one would have kivi post the holder's notices to whatever listens on the phone's loopback).
passkeysPasskeysThe platform's passkeys, with PRF: the holder's unlock.
policy?objectkaru, run where the holder is (prd.md §6; use-policy.ts): every rule of policy that matches request. On phones, karu's native library (kivi's modules/kivi-karu); absent where it can't run (then asks take the number).
policy.explainPromise<{ allow: string[]; decision: "ALLOW" | "DENY"; deny: string[]; }>-
proximity?ProximityPortWays this device can prove it's near another (Bluetooth LE, NFC; UWB when an adapter offers it: proximity/index.ts), for "mine" bonds (bonds.ts). None: bonding goes on without proximity, and a "mine" bond waits out its cooling-off.
push?objectThis device's push token as last fetched, straight away (for answering pings).
push.knownPushHandle | undefined-
quiet?QuietSealerOn a phone: what's read without the gate. None in a browser.
registry?CredentialRegistryWhere sites find this wallet's credentials (Android's Credential Manager); none in a browser.
relayRelayThe relay's mailboxes.
release?ReleasePortsThe release watch: kivi's check of the pages wellknown.id serves against the signed release log.
ring?RingPortKeeper rings, where this device can reach one (NFC).
saySayThe service's words, in the holder's language.
screen?objectWhen the phone locks or its screen turns off (not when the holder switches apps): what's revealed of the holder's details is hidden again. None in a browser; the app may say so in its own way there.
screen.onLocked() => void-
storeEncryptedStoreThe encrypted store (keyrings, recovery-code copies, the personas' mailboxes) and drop boxes, at the relay.
syncLimits?() => objectSyncing's wait, for tests: how long a refresh waits for each bonded device's answer before it leaves that device the news in its drop box instead (syncMs; sync.ts SYNC_MS, 6 s, by default). The whole-service tests shorten it, so a device that's away isn't waited out at every refresh (review R8-33).
trust?TrustStoreDocument signers' trust anchors (CSCA certificates), for checking passports and ID cards.
witness?objectA witness's connection (its protocol's WebSocket); by default the platform's WebSocket (witness.ts connectWitness).
witness.connectPromise<WitnessConn>-

Methods

gateStatus()
gateStatus(): Promise<GateStatus>;

Whether secrets can be gated here, and how.

Returns

Promise<GateStatus>

reset()?
optional reset(): Promise<void>;

Makes this device a new install (prd.md §7.10, "That was me"): a new Noise static key, and the sync log the bond store keeps begun again, so the holder can bond it again by a ceremony (a removal is permanent for an install). None: the holder reinstalls the app instead.

Returns

Promise<void>

wake()
wake(bond): Promise<boolean>;

Asks the relay to wake a bonded phone (a content-free push). False if it can't.

Parameters
ParameterType
bondBond
Returns

Promise<boolean>


ShareAsk

type ShareAsk = object;

A share offered to this device, put to its holder. contact: whose, as this holder knows them (none yet: accepting takes a name, and makes them a contact). copy: sent by another of this holder's own devices, which kept it there. devices: this holder's other devices it could be kept on too. Accept (with a name, if there's no contact; and the other devices chosen), or decline.

Properties

PropertyTypeDescription
bond?Bond-
contact?object-
contact.idstring-
contact.namestring-
copy?boolean-
devicesobject[]-
fromstring-
legacy?objectA share of a legacy key (prd.md §7.11): the period of quiet and the veto window it's held on. Absent for the recovery key.
legacy.quietMsnumber-
legacy.windowMsnumber-
sharePick<ShareOffer, "threshold" | "count" | "waitMs">-

Methods

accept()
accept(o?): Promise<void>;
Parameters
ParameterType
o?{ keepOn?: readonly string[]; name?: string; }
o.keepOn?readonly string[]
o.name?string
Returns

Promise<void>

decline()
decline(reason): void;
Parameters
ParameterType
reasonstring
Returns

void


Showing

type Showing = Omit<Pairing, "confirm"> & object;

The side that shows the code, as the service hands it out (bond.ts Pairing): yesAt (ms, the service's clock) resolves once the digits show, three seconds on; confirm refuses before it (E_TOO_SOON: review M9).

Type Declaration

NameType
yesAtPromise<number>
confirm()() => Promise<void>

SignInAsk

type SignInAsk = object;

A sign-in page's request, connected: the site, which persona would sign (the chooser), and the holder's answer.

Properties

PropertyTypeDescription
actingobject[]Contacts who've let this holder act for them at the site (prd.md §7.13), by grants held here, and shared identities whose members agreed to let this holder act for them there (§7.14): each a choice beside signing in as themselves, never made for them.
choice?Choice-
name?string-
needsProofbooleanWhether a plain yes needs the page proven near: a radio channel both share (as bonding's), or, where none is, the page on another network than this phone's (or one the relay didn't say); a browser paired with this phone and not heard, likewise only off this network. Where it isn't proven, only sign(…, { without: true }) signs.
network?NetworkWhat the relay said of the page's network beside this device's: shown ('same' signs a page that can't check with a plain yes).
paired?trueThe page is a browser paired with this phone (its Web Bluetooth or Web NFC heard here before).
proofKind?ProximityKindThe channel the proof listens on, so the screen can say how ("hold the two together"); undefined: none.
provingPromise<Proximity>The proof, started by the service as the request came; prove() tries again. 'none' where there's nothing to prove.
sitestring-
unoffered?trueNo check can be made with this page (it offered no channel this device listens on): only the network decides.
yesAtnumberWhen the holder may say yes (ms, the service's clock): "Decline" first, the yes three seconds after the request came.

Methods

decline()
decline(reason?): void;
Parameters
ParameterType
reason?string
Returns

void

notMe()
notMe(): Promise<void>;

"This wasn't me": declined (the page hears no), and noted in the holder's consents (sign-in-reported).

Returns

Promise<void>

prove()
prove(): Promise<Proximity>;
Returns

Promise<Proximity>

sign()
sign(
   persona?, 
   grant?, 
   o?
): Promise<void>;

Signs as persona (the chooser's, if none is named), behind the gate, and sends only the self-issued token; then files the sign-in in that persona's mailbox. With grant (one of acting's ids), acts for that contact: the persona the grant names signs, and the grant goes with the token. Rejects E_CANCELLED (still asking) if the holder closes the prompt; E_TOO_SOON before yesAt; E_PROXIMITY where a proof is needed and wasn't made, unless without.

Parameters
ParameterType
persona?string
grant?string
o?{ without?: boolean; }
o.without?boolean
Returns

Promise<void>


SiteStatus

type SiteStatus = 
  | "rotated"
  | "burned"
  | "pending"
  | "noticed"
  | "refused"
  | "unreachable"
  | "unsent";

Where a site stands in a rotation or burn. unsent: its proof kept, nothing sent yet; noticed: the site names no receiver or inbox, so the proof was left at its notice slot alone (it moves the account at the holder's next sign-in there, where the site reads notices).


SiteTerms

type SiteTerms = Delegation & object;

What a site says about delegation, as the screens show it before a grant is made.

Type Declaration

NameType
sitestring

SshBound

type SshBound = object;

Where an agent's request came through, from OpenSSH's session-bind@openssh.com messages on that connection (PROTOCOL.agent §1; review R2-22), which kivi desktop's agent passes on and this service checks. The destination is the LAST bind, as OpenSSH's agent takes it (R3-1): its host key's fingerprint and name (from the holder's known_hosts, looked up by kivi desktop, read-only) only where the host's signature over the session checks, never an earlier hop's in its place; sessionId, that bind's session, which a sign-in must carry. forwarded: ssh said a bind was forwarded (ssh -A); via: where that forwarding happens, the first forwarded bind's host (the jump host: the program asking runs there: R3-2), named only where its signature checks. revoked: kivi desktop found the destination's host key marked @revoked in known_hosts (R3-6).

Properties

PropertyType
forwardedboolean
host?string
hostKey?string
revoked?boolean
sessionId?string
via?object
via.host?string
via.hostKey?string

SshRingAsk

type SshRingAsk = object;

What the holder's asked, on this computer, before a ring on its reader signs (review M1; Ben's decision (b)): the key's name, what's being signed (signing: a sign-in as user, with the server's host key where ssh sent it; an SSHSIG signature and its namespace; or something else), who asked (the OS's word: phase 0, cleaned here: R2-4), where the request came through (bound, R2-22), and when Approve may be pressed: shown() says the ask is in front of the holder, and readyAt is three seconds from then (R2-2). Decline is the default. approve refuses before readyAt (E_TOO_SOON) or once withdrawn; withdrawn resolves when the ask goes: the holder declined, it timed out, or ssh gave up (its agent connection closed: gone). A ring lifted after a yes fails the signature (E_RING_GONE). Each signature asks: no yes lasts for a ring. urgent: the app brings its window forward for it (R2-9).

Properties

PropertyType
bound?SshBound
idstring
namestring
readyAt?number
requester?UseRequester
signingSshSigning
type"ssh-ring"
urgenttrue
withdrawnPromise<string>

Methods

approve()
approve(): void;
Returns

void

decline()
decline(): void;
Returns

void

shown()
shown(): number;
Returns

number


Standing

type Standing = object;

The result of the latest check that got an answer: the pages served as the signed release lists them, or not.

Properties

PropertyType
atnumber
checkednumber
commit?string
differences?Difference[]
release?number
rollingOut?string[]
scopeScope
status"ok" | "differs"

UpgradeView

type UpgradeView = object;

The upgrade (prd.md §7.8): whether this holder has no recovery root yet, and the copies the keyring names that carry no recovery key.

Properties

PropertyType
copiesnumber
neededboolean
rootboolean

UseAnswer

type UseAnswer = object;

What came back, and from which device: the signature, or signatures for messages (with the algorithm and public key, each checked here), or the value.

Properties

PropertyType
alg?SignAlg
bystring
lasting?Lasting
publicKey?Uint8Array
securityKey?SecurityKeySignature
signature?Uint8Array
signatures?Uint8Array[]
value?Uint8Array
values?Uint8Array[]

UseHolderAsk

type UseHolderAsk = 
  | {
  alg?: SignAlg;
  also?: string[];
  application?: string;
  bond: Bond;
  choices?: number[];
  count: number;
  how: "sign" | "share";
  keptHere?: boolean;
  lasts?: number;
  name: string;
  purpose: string;
  readyAt?: number;
  requester?: UseRequester;
  ring?: true;
  signing?: SshSigning;
  type: "use";
  why?: string[];
  withdrawn: Promise<string>;
  approve: Promise<void>;
  decline: void;
  shown: number;
}
  | {
  bond: Bond;
  keptOn: string[];
  name: string;
  purpose: string;
  type: "use-elsewhere";
  withdrawn: Promise<string>;
  decline: void;
};

What the holder's asked: to use a secret kept here for another device (approve opens it behind the gate), or told that another device asked for one this device doesn't keep (keptOn: where it can be answered). withdrawn resolves (with the device that answered, or '') once it's answered elsewhere or given up.

Union Members

Type Literal
{
  alg?: SignAlg;
  also?: string[];
  application?: string;
  bond: Bond;
  choices?: number[];
  count: number;
  how: "sign" | "share";
  keptHere?: boolean;
  lasts?: number;
  name: string;
  purpose: string;
  readyAt?: number;
  requester?: UseRequester;
  ring?: true;
  signing?: SshSigning;
  type: "use";
  why?: string[];
  withdrawn: Promise<string>;
  approve: Promise<void>;
  decline: void;
  shown: number;
}

count: how many things a yes signs (0 to share). lasts: a sign ask's yes may last this long (ms), approve(true): that device's next asks with this key sign at once until then, or the phone locks. choices: three numbers, one of them the asking device's (number matching, where the holder's rules ask for it: why, the rules' names): approve's chosen must be it. ring: a key on the holder's ring's security key, signed by the ring held to this device after the yes; application (ssh:…) says which, signing what's signed (read from the data: an SSH sign-in's account and the server's host key, SSHSIG's namespace, or neither), and keptHere false: this device doesn't keep the key's file, the asking device sent it (always with the number). shown(): the screen says when the holder can see it; readyAt: when a yes works (ms, the service's clock: a moment to read it first, from then).


Type Literal
{
  bond: Bond;
  keptOn: string[];
  name: string;
  purpose: string;
  type: "use-elsewhere";
  withdrawn: Promise<string>;
  decline: void;
}

UseProgress

type UseProgress = object;

How an ask is going, for the asker's screen: whom it's asked; a device not open, woken with a notification (waking) or not (unwoken: none could be sent); a no; the number to show (match).

Properties

PropertyType
asked?string[]
declined?object
declined.devicestring
declined.reasonstring
match?number
unwoken?string
waking?string

UseRequest

type UseRequest = object;

What's asked for: a secret (by its copy id, or its name), signed with or shared, and why, in the asker's words. To sign: one message, or several (messages: a release's manifest and its scripts), under one yes.

Properties

PropertyType
alg?SignAlg | "SK-ES256"
also?string[]
copy?string
how"sign" | "share"
match?number
message?Uint8Array
messages?Uint8Array[]
name?string
purposestring
requester?UseRequester
securityKey?SecurityKeyCredential
token?string

UseRequester

type UseRequester = object;

Which program asked, as the asking device's operating system says (docs/plans/asking-the-wallet.md, phase 0: kivi desktop reads its socket's peer): program ("ssh deploy@77.68.55.217": its command line, which a program can rewrite, so its own words), path (the file it runs from, which it can't), from ("bash in /home/ben/src"), and how it reached the device (via). Through the SDK (via: 'sdk'), also what the program calls itself (claimed, not verified) and its key's thumbprint (key). For ssh (bound, from OpenSSH's session-bind, its host key's signature checked by service/ssh.ts: review R2-22): the server the sign-in is for, and whether it came through a forwarded connection (ssh -A). Shown to the holder beside the number, as the asking device's word, never acted on: a yes that lasts is a token only a program through the SDK holds (R2-1), never keyed by what a requester says or runs from.

Properties

PropertyType
bound?object
bound.forwardedboolean
bound.host?string
bound.hostKey?string
bound.via?object
bound.via.host?string
bound.via.hostKey?string
claimed?string
from?string
key?string
path?string
programstring
via?"ssh-agent" | "kivi-command" | "sdk"

WalletService

type WalletService = ReturnType<typeof createWalletService>;

The wallet service: its commands, grouped by what they're about (holder, bonds, contacts, custodians…).


WayIn

type WayIn = 
  | {
  code: string;
}
  | {
  devices: true;
}
  | {
  custodians: true;
};

How the screens name a way to rebuild the root: a recovery code typed; the devices gathered in person (gather); the custodians (the root kept here after getting back in through them).


YesThatLasts

type YesThatLasts = object;

A yes that lasts, still running, as the holder sees it (review R3-8): which program (its own word), its key (the start of its thumbprint), which secret, until when, and for a token given on a phone, which device asked. id names it to take back (the start of the token's hash, never the token).

Properties

PropertyType
device?string
idstring
keystring
programstring
secretstring
untilnumber

Variables

CHECK_STANDS_MS

const CHECK_STANDS_MS: number;

How long a check's result stands before the next bonding or sign-in checks again.


DAILY_MS

const DAILY_MS: number;

How often the app checks while open, and checks fonts and images too.

Functions

createWalletService()

function createWalletService(given): object;

Makes the wallet service from the platform's ports: once per app, as a second one over the same storage would answer the same bonds twice. Two services over the same storage behave like the same device restarted.

Parameters

ParameterType
givenServicePorts

Returns

NameTypeDefault valueDescription
addressesobject-Addresses linked so a device that doesn't know the holder can send them a single-site persona (prd.md §4.10; docs/plans/borrowed-device.md): link sends a code, confirm takes it back (one prompt), unlink; waiting lists what was left in their inboxes (gate: through the gate, on a phone), openLink an email's link with the code the borrowed device showed (case 2); each parcel is the holder's to take (one prompt) or discard.
addresses.confirm()(code) => Promise<{ address: string; entry: string; }>-The code typed back, in one keyring edit (one prompt, before anything is filed): a new inbox for the address named at the relay, its card filed in the directory, the address kept. Rejects (the directory's words) where the code is wrong or ran out: nothing kept then.
addresses.discard()(ref) => Promise<void>-Throws a waiting thing away (ref): a parcel cleared from its inbox or the store, never joined; a notice cleared.
addresses.openLink()(url, code) => Promise<Waiting>-An email's link opened here (case 2), with the code the borrowed device showed: the parcel found and opened by both (scrypt: seconds on a phone), and listed as waiting, never joined. Rejects where the link isn't one, the code isn't one, or nothing opens with the two (a wrong code, or the parcel's gone: taken, thrown away, or 30 days).
addresses.pending()() => string | undefined-The address a code was sent to, while it can still be typed back.
addresses.take()(ref) => Promise<Collected>-Takes a waiting parcel (ref, from waiting or openLink): its persona joined as a single-site persona, in one keyring edit (one prompt), then cleared from its inbox or the store. Rejects where it's no longer waiting, or the keyring holds SINGLE_SITE_MAX single-site personas already.
addresses.unlink()(entry) => Promise<void>-Unlinks an address (by its entry): the directory's entry removed by its write key, the address marked removed (one prompt).
addresses.waiting()(o) => Promise< | { items: Waiting[]; more: number; } | undefined>-What's waiting in the addresses' inboxes (case 1), and any parcel opened by a link here (case 2): listed, never joined. gate: open the keyring through the gate where it doesn't open without (the holder is there: kivi's addresses screen); without it (a refresh), a phone whose gate is shut lists nothing. more: how many beyond those shown. Undefined where the keyring couldn't be read.
link()(address, lang?) => Promise<string>-Asks wellknown.id to send a code to address. Resolves the address as it'll be linked.
list()() => Promise<object[] | undefined>-The addresses linked, oldest first; undefined where the keyring doesn't open without a prompt.
bondsobject--
bonds.asksWhy()(bond) => boolean-Whether removing bond asks the holder why (remove's lost): one of the holder's own devices (persona-bonds.ts holdersOwn), which leaves their group, and whose loss freezes everything. Any other bond just ends here.
bonds.deviceNames()() => Promise<Map<string, string>>sync.deviceNamesThe devices this one knows by name, by did:key: those its bonds name, and those the logs held here describe. Who signed a record (records.ts whoSigned) is named from it.
bonds.gaps()() => Promise<Gap[]>sync.gaps-
bonds.give()(bond, ids) => Promise<void>-Gives a limited bond's device personas; takes them back (a request to forget).
bonds.list()() => Promise<Bond[]>--
bonds.notMine()(id) => Promise<void>-"This wasn't me", on this device: the held device is removed. "This wasn't me": the held device is removed, before anything of the holder's went to it.
bonds.personasToGive()() => Promise<PersonaView[]>holder.personasToGiveThe personas this device could give a limited device. The personas this device could give a limited device: those in use, by name.
bonds.reachable()(bond, timeoutMs?) => Promise<boolean>-Whether bond's device is there to answer now (its answer brings its current push token, kept on the bond).
bonds.releaseDue()(o) => Promise<void>-Every held bond whose hour is up, released (on opening, and by the timers); the rest timed, and, on opening (not on the minute's tick: review R2-3), asked about.
bonds.takeBack()(bond, ids) => Promise<void>--
bonds.untilReachable()(bond, timeoutMs?, cancelled?) => Promise<boolean>-Waits for bond's device to be there, pinging every couple of seconds; stops early if cancelled().
bonds.wake()(bond) => Promise<boolean>-Asks the relay to wake bond's device (with its push token as last heard). False if it can't.
closed()() => void--
held()() => Promise<HeldBond[]>-Held bonds (no proximity: docs/cross-device-risk-assessment.md), for the screens: who, until when, and this device's number.
join()(url) => Promise<Joining>-The side that joins: from a scanned code (or its link), connects, and says what the other side asks. Refused while the pages differ.
opened()() => void-On opening: held bonds whose hour is up are released, the rest timed.
pair()( kind, given?, origin?, contact? ) => Promise<Showing>-The side that starts: the QR code to show (and its link), then the six digits, then the bond. kind: what the other device will be; given: the personas a limited device is given; contact: someone else's device's contact, chosen before the code is shown (prd.md §7.12). Refused while wellknown.id's served pages differ from its release log. origin: the web app that opens the link on a device without the app.
reach()(bond, o?) => Promise<void>-Makes sure the app is open on bond's device before asking it anything. If it isn't (notThere), wakes it (a notification that only says a request is waiting) where it can be (woken: whether it could), and waits up to the notification's two minutes for the holder to open it. Rejects if it never comes.
remove()(bond, o?) => Promise<{ alone: object[]; froze?: Froze; notRemoved?: string; }>-Removes a bonded device. Where it's the device this one is limited to, what it gave goes too: a limited device holds only the personas its owner gave it, and kept, they'd be merged into a later holder's keyring once this device is someone's own (review R4-5: an employer's persona in the holder's keyring, out of the employer's reach). lost: the holder says it's lost or stolen, or someone else may be using it: the holder's wellknown.id is frozen (prd.md §7.10, the freeze: service/freeze.ts), every device and the store, until recovery under the holder's policy; the word of the device reporting it settles nothing (review R6-44: a thief would report the holder's device first; a recovery carries on no removal made by a device it removes, nor one of the recovering device). Otherwise (wiped, or theirs and safe) the removed device is woken to read that it was (the keyring's removal list), so it can ask the holder whether that was them ("That wasn't me" freezes). Resolves alone: the devices the holder's group counted only through the removed one's ceremonies, which are no longer the holder's (only a ceremony vouches: review R6-1). No screen reads it (review R8-34): kivi shows the same devices, on every device and for as long as it lasts, from gaps' stranded (review R7-38); it's kept for the group's tests, which check the log's word. Lost or stolen fails closed (review R7-7): the freeze first, then the removal. A freeze that can't be made throws, and nothing is removed (the screen says so, and offers "Freeze my wellknown.id"); once frozen, a removal that fails is said (notRemoved), not thrown: the freeze stands, and recovery asks which devices are out. froze: what the freeze reached (a copy the store didn't answer for is owed until it's frozen: review R7-8).
watchThere()(list, changed) => object-Watches which of list's devices are there (kivi open on them): changed with each one's state as it's learnt, each away one checked again, at 3 seconds, then 10, 30 and every 60 while it stays away, so opening kivi on one shows soon, and an old device that's never there costs little. hold pauses the checks (waiting for any running) while the app asks a device itself, so they don't queue behind it; stop ends it.
close()() => void-The app has gone to the background.
contactsobject-Contacts (prd.md §7.12): the people the holder knows, each a name only the holder's devices see, over the bonds with their devices. Chosen at bonding (bonds.pair, Joining.confirm); choose gives one to a bond that has none.
contacts.choose()(bond, pick) => Promise<string>contacts.chooseWhich contact bond's device is (prd.md §7.12): one the holder has, or a new one by the name they typed (never the device's). Kept on the bond now, and taken into the keyring as soon as it can be.
contacts.list()() => Promise<ContactList>contacts.listThe holder's contacts, without asking (see above).
contacts.merge()(from, into) => Promise<void>contacts.merge-
contacts.move()(did, into) => Promise<void>contacts.move-
contacts.remove()(id, opts) => Promise<void>contacts.removeRemoves a contact: what they told forgotten, the bonds made from contacts with their devices ended; with bonds (the default), the bonds with their devices made by a ceremony too, on each of the holder's devices.
contacts.rename()(id, name) => Promise<void>contacts.rename-
contacts.tell()(id, on) => Promise<void>contacts.tellThe holder's answer to "tell them about my other devices?" (asked once per contact). Yes sends them now; no after a yes asks their devices to forget what they were told, and ends the bonds made from it (settle).
custodiansobject-Custodians (prd.md §7.11): dealing shares of a recovery key to people the holder chooses, holding theirs, and getting back in through them.
custodians.afterRecovery()() => Promise<AfterRecovery | undefined>custodians.afterRecoveryBack in through custodians, and not dealt again yet: the dealing to retire, and whom this device reaches.
custodians.callOff()(shareId) => Promise<void>custodians.callOffA recovery under way through this custodian, called off here (before its release).
custodians.cancelRecovery()() => Promise<void>custodians.cancelRecovery-
custodians.checkNotices()() => Promise<boolean>custodians.checkNoticesReads the notice box (from where this device left off) and the veto box: recoveries under way, and stops.
custodians.confirmHeld()() => Promise<void>custodians.confirmHeld-
custodians.deal()(o) => Promise<DealingView & object>-Dealing to custodians: a root act (prd.md §7.8): the biometric, the root rebuilt by way, the custodians' way set, the root made anew and dealt to them.
custodians.dealing()() => Promise<DealingView | undefined>custodians.viewThe current dealing, as the dealer sees it: each custodian's answer and last confirmation (stale after 60 days).
custodians.dealWithout()(id, way?) => Promise<DealingView>--
custodians.dropHeld()(id) => Promise<void>custodians.dropHeldA share this custodian wants to delete: told to the holder (as no longer held) the next time they ask.
custodians.held()() => Promise<HeldShare[]>custodians.heldThe shares this device holds for others (accepted), newest first.
custodians.markRecoverable()(secretId, on) => Promise<void>custodians.markRecoverableMarks a secret kept here recoverable (prd.md §7.11): its value goes into the secrets vault under the secrets key (made now if there's none yet; a dealing carries it in the vault). Or takes it out again. The gate asks.
custodians.nextAsk()() => Promise<ShareAsk | undefined>custodians.nextAskThe share waiting longest for this device's holder, if any, to put to them.
custodians.notices()() => Promise<RecoveryNotice & object[]>custodians.noticesThe recoveries this device has heard of, newest first, each custodian named as the holder knows them (prd.md §7.12).
custodians.pollRecovery()() => Promise<boolean>custodians.pollRecoveryReads the release box: each release that opens and verifies is kept, by index; with the threshold of one dealing, the key is rebuilt, the newest vault that opens found (the store's, the replicas'), the keyring and the vault keys kept, and the recoverable secrets brought back. Resolves true once the holder is reached.
custodians.recognise()(contactId, link) => Promise<Recognising>custodians.recogniseThe holder has lost everything and shows this custodian a recovery link (prd.md §7.11): whose it is, by contact (§7.12), picks the share held for them; the new device's key is read from the request box, and the code both screens show is returned to compare, in person or on a call. confirm posts the notice to the holder's devices and starts the wait; nothing is released before it ends.
custodians.recovery()(origin?) => Promise<Recovery | undefined>custodians.recoveryThe recovery begun here, if any, and how far it has got.
custodians.releaseDue()() => Promise<number>custodians.releaseDueFor each recovery waiting here: the veto box read (a stop by the veto key withholds the share); past the wait, with the veto box read successfully just now, the share released to the new device's key alone, with a signed statement. The gate opens the share for that. Returns how many were released.
custodians.startRecovery()(origin?) => Promise<Recovery>custodians.startRecoveryBegins getting back in through custodians (prd.md §7.11), on a device that hasn't reached the holder: a fresh key pair for the recovery, its public key in the request box, the link to give each custodian, and the code every screen will show. The release box is polled while the service is open.
custodians.stop()(recovery) => Promise<void>custodians.stopStops a recovery (prd.md §7.11): a veto signed with the keyring's veto key (the gate asks), for every custodian to read. Even while frozen (§7.10): a recovery through custodians the holder doesn't recognise is one to stop, and a stop gives nothing away (the drop box as it came: guard.ts).
debugobject-For development tools: this device's latest asks, and what each listener is doing.
debug.asked()() => object[]--
debug.bondingSeeds()() => number--
debug.legacyPointers()() => Promise<object[]>--
debug.listening()() => Map<string, { at: number; state: string; }>--
declared()(origin) => Promise<Privacy | null>-What a site says it does with what it asks for: its config's privacy block (null: it publishes none).
deviceDeviceports.deviceWhat this device calls itself (the device port).
freezeobject-The freeze (prd.md §7.10; service/freeze.ts): a loss stops everything until recovery. view says whether the holder's wellknown.id is frozen here (when, why, where; once seen, where the holder recovered); check reads the store's word; freezeMine is "Freeze my wellknown.id"; recovery ends it (the holder's recovery root rebuilt by a way of their policy: a code, the devices in person, the custodians; the keyring's versions and what changed shown first); upgrade makes a holder from before the root their root; removed says this device was removed elsewhere, notMe ("That wasn't me") freezes, reset ("That was me") makes this device a new install. owed: what a recovery left to finish here (renewals.ts: old copies to retire or remove, a legacy to end, a grant to post again), each tried again until it's done; finish tries them all now, with the holder there (those that open the keyring too).
freeze.check()() => Promise<FreezeView | undefined>freeze.checkThe store's word (keyring-holder.ts checkStore): a copy frozen freezes this device; every copy retired by a recovery says where the holder recovered. On opening, at each refresh, and on a push. A store that can't be read says nothing (the freeze kept here stands); it throws only where this device's own state can't be read (E_UNREADABLE: fails closed, review R7-18, never "not frozen"; the guard refuses everything then too). Frozen here: every yes that lasts forgotten (review R7-6), and a freeze still owed to a copy tried again (review R7-8).
freeze.finish()() => Promise<RenewalView[]>--
freeze.freezeForLoss()(bondId) => Promise<Froze>freeze.freezeForLoss"Freeze my wellknown.id" where removing bond bondId's device as lost or stolen failed before anything froze (review R8-29): frozen as a loss of that device, so recovery marks it at first, as the removal's own freeze does (bonds.ts remove). A bond that isn't one of the holder's own devices here: a plain freeze.
freeze.freezeMine()() => Promise<Froze>freeze.freezeMine-
freeze.notMe()() => Promise<Froze>freeze.notMe-
freeze.owed()() => Promise<RenewalView[]>--
freeze.recoveryobjectfreeze.recovery-
freeze.recovery.cancel()() => void-Gives up a recovery opened: the root rebuilt for it wiped.
freeze.recovery.finish()(answers, o) => Promise<Recovered>-Ends the freeze, with the recovery opened (open), and the holder's answers.
freeze.recovery.makesPasskey()() => boolean-Whether recovering here makes a new passkey: where this device can make one (else the screens say it won't). Whether a recovery here makes a new passkey (the passkeys port says this device can make one): else it ends the freeze without one, and the screens say so.
freeze.recovery.withCode()(code, answers, o) => Promise<Recovered>-Ends the freeze with one of the holder's recovery codes (typed as printed), in one step.
freeze.recovery.withCustodians()(answers, o) => Promise<Recovered>-Ends the freeze with the root rebuilt through custodians (byCustodians), in one step.
freeze.recovery.withDevices()(answers, o) => Promise<Recovered>-Ends the freeze with the root rebuilt from the holder's devices, their shares gathered in person (service/root.ts gather), in one step.
byCustodians()() => Promise<boolean>-Whether this device got back in through custodians while frozen, and can end the freeze with them (no code needed).
open()(way) => Promise<RecoveryPlan & object>-Opens the recovery (prd.md §7.8): the biometric, then the holder's recovery root rebuilt by way (a code; the devices gathered in person; the custodians). Resolves the plan with the keyring's recovery copy's versions, each with what changed since it, to choose from; finish ends it. Ten minutes, in memory only.
plan()() => Promise<RecoveryPlan & object>-What changed lately that a thief could have planted, for the holder to keep or drop; and the holder's own devices bonded here, each lost if a freeze reported it so, for the holder to say which may be in someone else's hands (remove, by bond id: removed as the recovery ends; the rest come back by a ceremony). The gate asks.
freeze.removed()() => Promise<RemovedHere | undefined>freeze.removedThis device was removed by another of the holder's own (prd.md §7.10): by which, and when, as the keyring's removal list says (removals.ts removedHere: read from the store's copies, on a phone through the copies it watches); undefined if it wasn't. "That was me" resets kivi here (reset); "That wasn't me" freezes (notMe). Where this device's state or the list can't be read, it rejects (E_UNREADABLE: review R7-18), never "not removed": the screens say they can't tell, and the gate refuses meanwhile.
freeze.reset()() => Promise<void>freeze.reset"That was me": kivi reset here. The holder's wellknown.id is forgotten on this device, its bonds and log go, and the platform makes it a new install (a new static key: ports.reset); bonded again by a ceremony, it's a new device. Documents and secrets kept here stay; the holder removes them as any other.
freeze.upgradeobjectfreeze.upgrade-
freeze.upgrade.withCodes()(codes, policy?) => Promise<{ failures: RootFailure[]; frozen: number; others: number; root: string; }>-The upgrade (prd.md §7.8; Ben): one or more of the holder's recovery codes, typed (the first vouches for the root), and the biometric: the root made, the policy suggested from what they have (or policy), its shares dealt, its key on every copy, the codes' persona copies made the root's alone. Nothing else changes.
needed()() => Promise<UpgradeView>-Whether this holder has a root yet, and how many copies the keyring names carry no recovery key. Opens the keyring (the gate asks, on a phone).
pending()() => Promise<boolean>-Whether to ask the holder for the upgrade (prd.md §7.8: a holder from before the recovery root), without opening anything: no root trusted here, none waiting, none kept open; not while frozen; and not a new holder (whose first recovery code makes their root: service/root.ts).
freeze.view()() => Promise<FreezeView | undefined>freeze.view-
gateStatus()() => Promise<GateStatus>-Whether secrets can be gated here (the gate port's status).
giveobject--
give.connect()(...a) => Promise<GiveAsk | undefined>--
grantsobject-Delegation (prd.md §7.13): letting a contact act for the holder at one site, under a grant the site looks up in its mailbox at every use, so it can be taken back at once; and acting for a contact who's let this holder.
grants.drop()(id) => Promise<void>delegation.dropStops acting for a contact under a grant held here: ended in the keyring (the giver isn't asked anything).
grants.give()(o) => Promise<string>delegation.giveLets the contact act for this holder at site for days, doing what scopes (the site's names) say. Asks the contact's device for their key there first (their kivi asks them, up to waitMs). Resolves the grant's id.
grants.list()() => Promise<GrantView[]>delegation.listThe grants as the keyring has them (without asking: from the list the holder already sees).
grants.takeBack()(id) => Promise<void>delegation.takeBackTakes a grant back: gone from its mailbox at once, ended in the keyring, and the contact's devices asked to forget it.
grants.terms()(site) => Promise<SiteTerms>delegation.termsThe site's terms for delegation, from its wellknown.id config. Throws if it has none, or doesn't accept it.
groupsobject-Shared identities (prd.md §7.14): founded with contacts, acting at a site through a grant to one member that k members sign, members changed by k of them. Built, and not offered until delegation's legal review (the app decides).
groups.act()(o) => Promise<string>groups.actAsks to act for the group at site for days, doing what scopes (the site's names) say: the members' keys there, then their agreement, until k agree (each member's kivi asks them, up to waitMs). Resolves the grant's id.
groups.changeMembers()(o) => Promise<void>groups.changeMembersChanges the group: remove (members' keys), add (contacts, invited first), threshold. Signed by k members of the statement before (each asked). Resolves when it's agreed and the members are told.
groups.found()(o) => Promise<string>groups.foundFounds a shared identity with contactIds, threshold of all its members (the holder too) to agree. Each contact's kivi asks them; those who say yes are its founding members (it needs two members and threshold). Resolves its id here.
groups.leave()(group) => Promise<undefined>groups.leave-
groups.list()() => Promise<GroupView[]>groups.listThe groups as the screens show them (without asking: from the list the holder already sees).
groups.rename()(group, label) => Promise<undefined>groups.rename-
groups.takeBack()(group, id) => Promise<void>groups.takeBackTakes one of the group's grants back (any member may): gone from its mailbox at once, ended, the members told, with this holder's word for it, signed with its key for the group (the other members end it only on a member's word).
holderobject--
holder.addPasskeyHere()() => Promise<void>holder.addPasskeyHereAdds a passkey to the holder's keyring, deliberately (another provider, say): made with the keyring's user handle and names, and excludeCredentials listing its passkeys, so a provider that already keeps one refuses (E_EXCLUDED). Its PRF output files a copy of the keyring. A lock an earlier lock change left (Keyring.locks) keeps it, and it's dated by the service's clock, so it counts however soon after that change it's added (review R6-39: it was held out for good).
holder.addPersona()(name) => Promise<string>holder.addPersonaAdds a persona named name (made unique). Resolves its id.
holder.addPersonaWithCode()(code) => Promise<CodeOutcome>holder.addPersonaWithCodeA recovery code entered once the holder is reached: its persona joins the keyring, in use. A forgotten persona comes back (its code is the deliberate act that may). One already here under another name is the rename conflict, settled by settleConflict.
holder.beginRotation()(persona, sheet) => Promise<{ group: number; seed: Uint8Array; sheet: string; sites: number; }>holder.rotation.beginRotation at sites after a loss (prd.md §4.12; service/rotation.ts): begun with the successor sheet (the biometric: every site's proof signed by both keys then), the next sheet shown once and confirmed (a root act), which promotes the successor at once (the old seed wiped), then every site sent its rotation in the background; receipts looked for and sites sent again (refreshRotation; resendRotation, the biometric, at once). The view is of the persona the rotation promoted to (confirmRotation resolves it). Without a sheet, burnKeys (a root act) disables the persona's key at each site, which holds the account. Begins rotating persona (the material step: the biometric): sheet its successor sheet, the one this device trusts. Makes the next successor S′ and, with the persona's seed and S both in hand, each site's proof (both keys) and its SET; returns S′'s sheet once, with the group to type back (confirm). Nothing is sent or kept yet.
holder.burnKeys()(persona, way?) => Promise<RotationView>--
holder.cancelRotation()(persona) => voidholder.rotation.cancelThe next sheet put away unconfirmed: the rotation isn't begun, and S and the proofs are wiped.
holder.cancelSuccessor()(persona) => voidholder.cancelSuccessorThe successor sheet just made is put away unconfirmed: nothing goes into the keyring.
holder.cancelSuccessorChange()(persona) => Promise<void>holder.cancelSuccessorChangeCancels a change to persona's successor this device hasn't taken (keyring-holder.ts cancelSuccessorChange).
holder.confirmRotation()(persona, typed, way?) => Promise<RotationView>--
holder.confirmSuccessor()(persona, typed, way?) => Promise<{ persona?: string; unfiled: string[]; }>-The sheet just made, confirmed (a root act: the biometric, the root rebuilt by way, made anew): into the keyring.
holder.defaultPersona()() => Promise< | { fields: ( | "email" | "given_name" | "family_name" | "nickname" | "phone_number" | "birthdate" | "website" | "address.street_address" | "address.locality" | "address.region" | "address.postal_code" | "address.country")[]; id: string; name: string; } | undefined>holder.defaultPersonaThe default persona's id (its fingerprint, in full), which a home seal is drawn from (prd.md §4.10), and its name, which the home card shows. Read without asking: on a phone from the quietly sealed list of personas, in a browser from the default's seed and the keyring kept here. Undefined while no persona is held here (or, on a phone, before that list has been sealed).
holder.defaultPersonaId()() => Promise<string | undefined>holder.defaultPersonaIdThe default persona's id alone (defaultPersona).
holder.findWithPasskey()(elsewhere) => Promise<Bringing | undefined>holder.findWithPasskey-
holder.forget()(...args) => Promise<void>holder.forgetForgets the holder's wellknown.id on this device (their personas stay reachable through their unlocks).
holder.forgetPersona()(id) => Promise<undefined>holder.forgetPersona-
holder.hide()() => voidholder.hide-
holder.makeDefault()(id) => Promise<undefined>holder.makeDefault-
holder.makeRecoveryCode()(way?) => Promise<{ code: string; copy: string; failures: RootFailure[]; }>-Recovery codes (prd.md §7.8, decision 8: the holder's, not a persona's): each a root act, the biometric and the root rebuilt by way (a code; the devices gathered in person; a new holder's first code needs none), then made anew. removeRecoveryCode: a code of the root's (its copy's id), or a persona's code from before the root (persona).
holder.makeSuccessor()(persona, o) => Promise<{ group: number; seed: Uint8Array; sheet: string; }>holder.makeSuccessorA persona's successor (prd.md §4.12): made, its seed returned once as a sheet and kept nowhere here; its extended public key into the keyring only once a group of the sheet is typed back (or nothing, cancelled), named by the recovery root (a root act), so every one of the holder's devices takes it at once; replaced with the old sheet (a rotation: the old sheet becomes the persona), or said lost; restored from its sheet (a root act too). A change written without the root waits a week on each device, shown, and any can cancel it. Makes persona's successor (prd.md §4.12, successor.ts): a fresh successor seed, returned once, as a sheet for the holder to write down or keep on a ring, and never stored on any device. Nothing goes into the keyring until the holder types back group number group (1-based) of the sheet (confirmSuccessor, a root act); cancelled, nothing changes. Replacing the successor this device trusts with its sheet in hand (old) is a rotation (Ben, 2026-10-16: the re-commit retired; service/rotation.ts begin, confirmed by confirmSuccessor): the old sheet becomes the persona, this new one its successor, and every site is sent a proof signed by both keys. Without it (lost), sites holding the old one keep it. Either way, the root names the new one when it's kept, so the holder's devices take it at once. Refused on a device that commits to no successor while the keyring names one (review R9-14: it can't tell whether that one is the holder's, so a "first" made here would overwrite it with no link and no re-commits): trusting no root, E_NO_ROOT (a code typed here first); trusting one that doesn't name it (a change shown here), E_CHANGE_WAITING: restore it from its sheet if it's the holder's (restoreSuccessor), or say the one there is lost (lost), which replaces it as lost, as for any. Where the sign-in records can't be read, E_UNREAD (review R9-15).
holder.noticeAlarms()() => Promise<NoticeAlarm[]>holder.noticeAlarmsSites whose notice for a persona's key is someone else's (review R13-4): an alarm, on every device, offering the freeze (freeze.freezeMine). The alarms in the records of the personas held here (review R13-4; service/notices.ts): sites whose notice for a persona's key is someone else's. Shown on every device until the persona is rotated, with the freeze offered. Rejects where a persona's records can't be read (never "none").
holder.openRecords()() => Promise<void>holder.openRecordsOn a phone whose personas aren't sealed for quiet reading yet: opens the seed once, through the gate, to seal them.
holder.personaFields()(persona) => Promise<Partial<Record< | "email" | "given_name" | "family_name" | "nickname" | "phone_number" | "birthdate" | "website" | "address.street_address" | "address.locality" | "address.region" | "address.postal_code" | "address.country", string>>>holder.personaFieldsA persona's fields (persona-fields.ts), through the gate; and setting them ("" clears one), then what sites can ask for is registered again. A persona's fields: from what's revealed, or else read through the gate (the values are never in the list read without it).
holder.personaList()() => Promise<PersonaList | undefined>holder.personaList-
holder.personaSites()() => Promise<Map<string, number>>holder.personaSites-
holder.records()() => Promise<MailboxEntry[]>holder.records-
holder.recordsWaiting()() => Promise<boolean>holder.recordsWaitingWhether the records and the personas wait for the gate (a phone where they aren't sealed for quiet reading yet).
holder.recoveryCodeVersions()(code) => Promise<CodeVersion[] | undefined>holder.recoveryCodeVersions-
holder.refreshRotation()(persona) => Promise<RotationView | undefined>holder.rotation.refreshThe rotation kept going (no gate): receipts looked for, and, where the keyring opens without asking, the sites unsent, unreachable, refused or pending a day sent their rotation again (its notices filed where they weren't). kivi calls it whenever it shows the rotation, and in the background. Resolves where it stands.
holder.removeRecoveryCode()(copy, way?, persona?) => Promise<{ failures: RootFailure[]; }>--
holder.rename()(id, name) => Promise<void>holder.renameRenames a persona; every recovery-code copy of it the keyring knows is rewritten with the new name.
holder.resendRotation()(persona) => Promise<RotationView | undefined>holder.rotation.resendSends the rotation again now (the biometric: its steps signed by the persona's seed's step key) to every site not rotated.
holder.restoreSuccessor()(persona, sheet, way?) => Promise<void>-A sheet the holder still has, put back (a root act, as confirmSuccessor).
holder.reuse()(id) => Promise<undefined>holder.reuse-
holder.reveal()() => Promise<void>holder.revealShows what the holder's personas say (their names, details): read once through the gate and kept in memory until hide, or the phone locks (the screen port); shown is it, by persona id, or undefined while hidden. The 'reveal' event says it changed.
holder.rotation()(persona) => Promise<RotationView | undefined>holder.rotation.viewWhere persona's rotation (or burn) stands, from its records; undefined where there's none. No gate.
holder.setAside()(id) => Promise<undefined>holder.setAside-
holder.setNames()(on) => Promise<undefined>holder.setNames-
holder.settleConflict()(keepThisName) => Promise<void>holder.settleConflictThe rename conflict's answers: keep the name here (the code's copy rewritten with it), or rename back to the code's.
holder.shown()() => | Record<string, Partial<Record< | "email" | "given_name" | "family_name" | "nickname" | "phone_number" | "birthdate" | "website" | "address.street_address" | "address.locality" | "address.region" | "address.postal_code" | "address.country", string>>> | undefinedholder.shownWhat's been revealed, by persona id; undefined while hidden.
holder.signInChoice()(site) => Promise<Choice | undefined>holder.signInChoiceWhich persona signs at site, by the chooser's rules (prd.md §4.10), read without the gate: a single-site persona collected (addresses) is offered at its site. Which persona signs at site for another device's page (prd.md §4.8, §4.10), by the chooser's rules: the personas held here, and where each has signed in, from its mailbox. Read without the gate. Undefined where they can't be read yet: the default signs.
holder.startNew()() => Promise<void>holder.startNewFor someone new to wellknown.id: makes their passkey, and their first persona with it. The unlock comes with the passkey when its provider computes PRF at registration, so they're asked once; else the passkey is asked for it.
holder.state()() => Promise<HolderState | undefined>holder.stateWhat this device knows of the holder. What an older version kept that this one doesn't read (records keys in the clear; one persona's sealed records keys) is let go of at once (a clean break); in the sign-in pages, so is a recovery root an earlier build kept, with the successor records it judged (dropEarlierRoots: review R8-21).
holder.successorSites()(persona) => Promise<"none" | "unknown" | SiteOnOlder[] | "no-root">holder.successorSitesThe sites still keeping an older sheet's commitment than the one this device uses (review R6-6): keep that sheet until none do. The sites where persona still keeps an older successor sheet's commitment than the one this device uses (review R6-6; successor-holder.ts sites): the holder keeps that sheet until none does. 'unknown' where the sign-in records or its re-commit box can't be read now (reviews R7-19, R8-31: never an empty list, which would say no site needs the old sheet); 'no-root' where this device trusts no recovery root and so commits to no successor (review R8-17: a code typed here, trustWithCode, or a ceremony gives it the root); 'none' where it trusts a root but commits to no successor for the persona (review R9-4: none made, or a change shown here that it doesn't take; never an empty list). The gate asks.
holder.trustWithCode()(code) => Promise<void>holder.trustWithCodeA recovery code typed on a device that trusts no recovery root (review R8-17): the root trusted here, the successors it names taken at once. One of the holder's recovery codes typed on this device, which trusts no recovery root (a kivi install brought in by passkey: review R8-17): the root it opens trusted here, so the successor sheets it names count at once, as the sign-in pages do with "Type a recovery code to let this browser use your successor sheet". Nothing is made anew.
holder.unlockWithPasskey()(elsewhere) => Promise<void>holder.unlockWithPasskeyWith the holder's passkey (from this phone, or elsewhere through the system's QR code), finds their keyring. Rejects with code E_NO_HOLDER if the passkey opens none (they're new: see startNew).
holder.unlockWithRecoveryCode()(code, version?) => Promise<void>holder.unlockWithRecoveryCodeWith a recovery code, on a device that hasn't reached the holder yet: the persona it's for, kept here as its own; a code of the recovery root's code way, the whole keyring, as version had it (one of recoveryCodeVersions', from before a theft: review R7-4), else the newest.
setFields()(...args) => Promise<void>--
legacyobject-Legacy (prd.md §7.11): chosen secrets left to a beneficiary, released by custodians on a long absence they agree on, after a veto window; never the identity. Built, and not offered until the legal review (the app decides whether to show it).
legacy.agree()(shareId) => Promise<void>legacy.agreeThis custodian agrees to a release (prd.md §7.11): only once the period of quiet has passed. Signed with its agreement key, left in the agreement box (the other custodians read it) and the holder's notice box (their devices hear of it, and any sign of life voids it).
legacy.bequests()() => Promise<Bequest[]>legacy.bequestsWhat this device shows of legacies left to its holder: those the holder chose to tell them of, and those received.
legacy.checkNotices()() => Promise<boolean>legacy.checkNoticesReads each legacy's notice box from where this device left off: the custodians' agreements, by who they're left to.
legacy.checkReleases()() => Promise<number>legacy.checkReleases-
legacy.deal()(o) => Promise<LegacyView>legacy.dealDeals a legacy (deal, above), a material act (review R7-17): the biometric first, its seed used for the dealing, so the gate isn't asked twice. Dealing again without a contact (withoutContact) and after a recovery (renewAfterLoss) is part of those acts, so asks nothing more.
legacy.end()(beneficiary) => Promise<void>legacy.endEnds the legacy for beneficiary: the keyring's note gone, the head removed, its custodians told to drop their shares, the beneficiary's devices told to forget the box secret (a compliant kivi does when it hears; it could have kept a copy, which opens nothing without the custodians). The secrets stay where they're kept. The gate asks.
legacy.held()() => Promise<HeldLegacy[]>legacy.heldThe legacy shares this device holds for others, each with where it stands (read now).
legacy.imHere()() => Promise<number>legacy.imHere-
legacy.leave()(secretId, beneficiary, on) => Promise<void>legacy.leaveLeaves a secret kept here to beneficiary (prd.md §7.11), or takes it back: its value into their content (under the content key, made now if there's none yet), or out of it. The gate asks.
legacy.list()() => Promise<LegacyView[]>legacy.viewsThe legacies the keyring notes, each with its terms and what's left to the beneficiary from here.
legacy.notices()() => Promise<LegacyNotice & object[]>legacy.noticesThe custodians' agreements this device has heard of, newest first, each with who it's left to, by name.
legacy.releaseDue()() => Promise<number>legacy.releaseDueFor each legacy share this custodian agreed to release: past the veto window, with the life entry, the veto box and the agreement box read in this same run and still enough agreements since the latest sign of life, the share sealed to the release key alone, with a statement. The gate opens the share. Resolves how many were released.
legacy.signOfLife()(force) => Promise<number>legacy.signOfLifeA sign of life (prd.md §7.11): written to each legacy's life entry at most daily (or now, force: "I'm here", also into the veto box), from any of the holder's devices that holds the keyring, without the gate. The dealing device also sends one over its bonds with the custodians, at most monthly. Resolves how many legacies it was written for.
legacy.withoutContact()(id, o) => Promise<{ dealtAgain: string[]; ended: string[]; tooFew: string[]; }>legacy.withoutContactRemoving a contact (prd.md §7.12): a legacy left to them ends; one they hold a share of is dealt again without them (dealAgain), where enough custodians are left (else it stays as it is, their share with them until it's dealt again, and tooFew names it). Only the device that dealt it knows its custodians: elsewhere those are left alone.
offersobject--
offers.askBack()(...a) => Promise<Uint8Array<ArrayBufferLike>>--
offers.keepSecret()(...a) => Promise<{ deliveries: Delivery[]; record: SecretCredential; }>--
offers.nextAsk()() => Promise<OfferAsk | undefined>offers.nextAskThe offer waiting longest for the holder here, if any, to put to them. Where this device can't gate secrets (a phone without a screen lock), it's declined at once, and the next is looked at.
on()(event, fn) => () => void--
open()(asks) => void-The app is open and in front (requests.ts): it listens for its bonded devices; asks puts to the holder what only they can answer.
pagesobject--
pages.check()(o) => Promise<PagesCheck>pages.checkChecks the served pages now, or (unless force) takes a result less than 10 minutes old. Resolves the check as it stands: a difference found earlier stands through a check that got no answer.
pages.now()() => PagesCheckpages.now-
programsobject-Programs asking this wallet (programs.ts; docs/plans/asking-the-wallet.md, phase 1): a program on this device, through the wellknown.id SDK over a local socket (kivi desktop's), asks in GNAP for a secret for once, or a signature. handle answers each message; what's kept here is put to the holder through open's asks (type: 'program'), what isn't is asked of their devices; endpoint is what the discovery file names.
programs.endpoint()() => Promise<{ instance: string; publicKey: string; }>programs.endpointThe discovery file's publicKey: this wallet's endpoint key as a did:key (M6; not the device's identity key), which signs each hello and each answer, so a program knows it reached the wallet the file names.
programs.handle()(message, osSaid?, at) => Promise<Record<string, unknown>>programs.handleOne message from a program, over the local socket: hello (this wallet's signed hello, for its nonce and the socket it was reached on), grant (a GNAP grant request as a JWS), continue (polling one, by its id, with its continuation token, no sooner than wait says), or cancel (the program gave up: §5.4). os: the asking program as this device's operating system says (kivi desktop reads the socket's peer); socket: where it was reached, which a hello must name.
programs.waiting()() => numberprograms.waiting-
registerCredentials()() => Promise<{ registered: string[]; supported: boolean; }>-Makes this wallet's credentials available to sites through the platform (the registry port): every verified document gets its presentable credentials first (documents read before credentials existed get theirs now). Makes this wallet's credentials available to sites through the platform (the registry port): every verified document gets its presentable credentials first (documents read before credentials existed get theirs now), and each persona that says anything is offered too (persona-fields.ts).
ringsobject-Keeper rings (prd.md §7.9; ring.ts): added as one of the holder's devices, keeping copies of secrets sealed to the ring's own key, opened with a tap on any of the holder's devices with NFC, and restored from on a new one.
rings.add()(name, pin, o) => Promise<RingView>rings.addAdds the ring held to the device as one of the holder's (a tap): its PIN, set now on a new ring (4 to 16 characters) or asked for on one that has it; its keys made on it, if it hasn't them (a tap's, and the PIN's that copies are sealed to); proved to be the ring holding the first; then said in this device's log, so every device of the holder's knows it.
rings.cancel()() => voidrings.cancel-
rings.drop()(secretId, ringId, pin, o) => Promise<void>rings.dropRemoves a secret's copy from a ring (a tap, its PIN), and notes it gone; a secret then kept nowhere at all is removed here too.
rings.forget()(id) => Promise<void>rings.forgetForgets a ring, on every device of the holder's. What it keeps stays on it (a tap reads it again: restore); copies noted here as kept on it are noted as gone.
rings.keep()(secretId, ringId, pin, o) => Promise<void>rings.keepKeeps a copy of a secret kept here on a ring (a tap, after the gate opens it): sealed to the ring's PIN key (made now on a ring added before it had one), written behind its PIN in place of any older copy of the same secret (one sealed to the tap's key included), read back, then noted and listed. A material act (review R7-17: a secret put where a tap and a PIN open it): the biometric first, then the gate opens the secret itself (on a phone, a second prompt: the secret's own gate is a key of its own).
rings.keepOnlyOnRing()(secretId, pin?, o) => Promise<void>rings.keepOnlyOnRingKeeps a secret only on its rings: the copy here is dropped, once a ring this device put it on is known to hold it (a tap reads it back first, and opens it, so it's there and opens: pin where the ring's key asks for it). Opening it again here takes the ring.
rings.list()() => Promise<RingView[]>rings.list-
rings.lockCopies()(ringId, pin, o) => Promise<number>rings.lockCopiesPuts what a ring keeps behind its PIN (a tap, its PIN): every copy sealed to the tap's key opened on the ring and sealed again to the PIN key (made now if the ring hasn't one), written in their place and read back. Nothing is opened through this device's gate. Answers how many were moved.
rings.look()(id, o) => Promise<RingView>rings.lookReads what a ring says of itself again (a tap, no PIN): its security key's report (how many times it has signed, how many keys it has made), said in the log if it changed, so every device of the holder's shows it.
rings.open()(copy, pin?, o) => Promise<RingSecret>rings.openA secret's copy on a ring, opened (a tap): the ring's half of the key agreement, blinded, so nothing useful crosses the air. pin only where the ring's key asks for it. Any of the holder's devices with NFC can.
rings.rename()(id, name) => Promise<void>rings.renameGives a ring another name, on every device of the holder's.
rings.restore()(name, pin?, o) => Promise<{ onRing: number; restored: number; unreadable: number; }>rings.restoreBrings back what a ring keeps, on this device (a tap): every copy opened, and each secret not kept here already (by its copy id) kept here behind the gate, noted as on the ring too. A ring the holder's devices don't know yet is added under name. A record that won't open (another wallet's, an older format, a ring's key since deleted) is passed over, not the end of it. Answers how many were brought back, of how many on the ring, and how many couldn't be read.
rings.supported()() => booleanrings.supported-
rootobject-The recovery root (prd.md §7.8; service/root.ts): who may do the dangerous things. view what this device trusts, the policy and what's suggested; gather (this device rebuilding the root) and give (another of the holder's devices, from the code it scans) the in-person ceremony for a device's share; vouchFor and give a root taken in person (the only way, but a code typed there, a device that trusts no root takes one: never by waiting); root acts: setPolicy, renew (made anew, a removed device's share worthless), addDevice (to the devices way), tellContacts (the root's word to contacts: prd.md §7.12).
root.addDevice()(bondId, way?) => Promise<{ failures: RootFailure[]; root: string; }>root.addDeviceAdds a device bonded here to the devices way (a root act, decision 5): it holds a share from the new root on.
root.clearGathered()() => voidroot.clearGathered-
root.gather()(origin?) => Promise<{ code: Promise<string>; done: Promise<{ gathered: number; name: string; }>; url: string; cancel: void; }>root.gatherGathering a share in person (decision 4): this device, rebuilding the root, shows the root ceremony's code for one of the holder's other devices to scan. Resolves its name, and how many shares are gathered now (this device's own comes from its keyring at the act).
root.give()(url) => Promise<{ code: string; peer: string; proving: Promise<boolean>; purpose: "share" | "vouch"; confirm: Promise<void>; decline: void; }>root.giveThe other side of the root ceremony, from its scanned code: a share asked for (share), or a root shown to take in person (vouch). The proof that the other device is near starts at once (radio only: no going on without it). The holder sees who asks and the six digits; confirm (the biometric, the material step) releases this device's share of the root it trusts, or takes the root shown, to the other device alone. Refused for a device that isn't the holder's own (bonded here as theirs, or named in the devices way).
root.renew()(way?, o) => Promise<{ failures: RootFailure[]; root: string; }>root.renewMakes the root anew (a root act, decision 6): the same policy, a new secret and shares; the old shares, a removed device's among them, worthless.
root.setPolicy()(policy, way?) => Promise<{ failures: RootFailure[]; root: string; }>root.setPolicyChanges the holder's policy (a root act, decision 2): the ways in, as given. A code way names codes already made (new ones come by makeRecoveryCode); the custodians' way is custodians.deal's. Each root act here resolves the new root and what it couldn't do (failures, review R8-23: returned and shown, never dropped).
root.tellContacts()(way?) => Promise<{ failures: RootFailure[]; root: string; told: string[]; }>root.tellContacts"Tell your contacts" (prd.md §7.12; Ben, 2026-10-16: only the holder's root takes a device away at a contact): a root act whose new root signs that the devices still to tell (contacts.ts toTell: removed, or left stranded) are no longer the holder's, beside every one it said so before, and that the holder's devices now are; then every contact's device bonded here is sent it (service/contacts.ts sendRootNotes), and the holder's other devices send it over theirs as the keyring reaches them. Resolves the devices told of, the new root and what it couldn't do.
root.vouchFor()(origin?) => Promise<{ code: Promise<string>; done: Promise<{ name: string; }>; url: string; cancel: void; }>root.vouchForShows the root this device trusts, for another of the holder's devices to take in person (give, purpose vouch).
changePolicy()(change, way?) => Promise<{ failures: RootFailure[]; root: string; }>-A change to the policy as the holder asks for it (ways-in.ts policyWith), composed here and set by a root act (setPolicy).
view()() => Promise< | { adopt?: true; beside?: RootSeen[]; clash?: true; differs: boolean; failed?: RootFailure[]; fork?: RootSeen[]; gathered: number; joinable: object[]; kept?: true; needed?: number; needsWay: boolean; open?: boolean; owed: "custodians"[]; stale: object[]; suggested: Policy; trusted?: RootSeen & object; unreached?: RootSeen[]; waiting?: RootSeen; } | undefined>-The root as the screens show it, with what they'd otherwise work out themselves (review R7-23): whether a root act needs a way given (needsWay), and whether the policy differs from what kivi suggests (differs).
secretsobject-Secrets as the holder sees them (service/secrets.ts): here and on their other devices, copies of one as one group, each with where it is; and opening one wherever it is (here, from a ring, or asked of the device keeping it).
secrets.list()() => Promise<{ groups: SecretGroup[]; sharers: Bond[]; }>secrets.listThe secrets kivi knows of, here and as the holder's other devices list theirs, grouped by copyKey (the copy here first, then those kept, then notes), and those this device's secrets may be shared with (bonds that aren't the holder's own). A note of a secret sent to another device shows once: as that device lists it, when it does.
secrets.open()(...a) => Promise<Uint8Array<ArrayBufferLike>>--
setListed()(id, listed) => Promise<void>-Lists a secret kept here on the holder's other devices, or stops: said in this device's catalogue, and spread.
settled()() => Promise<void>-Resolves once nothing this device began on opening (a refresh, an upkeep) is still under way: a test moving its clock waits for it.
sharesobject-Sharing with a contact (prd.md §7.14): a secret lent (it stays here; their devices ask, and the holder's asked each time) or given (a copy that's theirs; taking it back is a request to forget). Never a persona, records or documents.
shares.give()(secretId, contactId) => Promise<number>shares.giveGives a contact a copy of a secret kept here, as theirs: opened behind this device's gate, then offered to each of their devices to keep (their kivi asks them). Resolves how many devices it was handed to.
shares.lend()(secretId, contactId) => Promise<void>shares.lendLends a secret kept here to a contact: listed for every device of theirs; they ask, and this holder's asked each time.
shares.news()() => ShareNews[]shares.news-
shares.of()(secretId) => Promise<{ given: object[]; lent: object[]; }>shares.ofWhat's lent and given, by contact, for a secret kept here (its card).
shares.present()(o) => Promise<void>shares.presentShows a contact what a credential says, bound to them: they can check it, not use it as their own. Shows a contact what a credential says: only paths, key-bound to their device (its did:key) and a nonce it gave, so they can check it but not use it as their own. Needs their kivi open (it gives the nonce). Resolves once their kivi has checked it.
shares.presentable()() => Promise<object[]>shares.presentableWhat can be shown to a contact: each credential, by title, with the claims it can disclose one by one (their paths).
shares.stopLending()(secretId, contactId) => Promise<void>shares.stopLendingStops lending a secret to a contact: their devices are taken off its list, so nothing more reaches them.
shares.takeBack()(secretId, contactId) => Promise<void>shares.takeBackTakes back a copy given: each of the contact's devices is asked to forget it (a compliant kivi deletes it when it hears). They could have copied it first: the screens say so, and that a password given should be changed.
signInobject--
signIn.connect()(...a) => Promise<SignInAsk | undefined>--
sshobject-SSH through kivi (service/ssh.ts): the holder's SSH keys, a sign-in signed where the key is kept (kivi desktop's agent answers ssh with these), and a new key made here.
ssh.gone()(conn) => voidssh.goneAn agent connection closed (ssh gave up): its asks still open are withdrawn, and won't sign (R2-24).
ssh.keys()() => Promise<object[]>ssh.keysThe holder's SSH keys, as SSH names them (blob) with their secrets' names as comments: no one asked.
ssh.newKey()(o) => objectssh.newKeyA new SSH key, made here (Ed25519 unless asked for P-256): its private key as ssh-keygen writes it, to be kept as an SSH key secret like one pasted in (so it goes to the holder's other devices and rings, and can be copied out), and its line for authorized_keys. Nothing is kept until it's kept.
ssh.sign()(...a) => Promise<Uint8Array<ArrayBufferLike>>--
syncobject--
sync.otherDevices()() => Promise<CatalogueDevice[]>sync.otherDevices-
sync.pendingRemovals()() => Promise<PendingRemoval[]>sync.pendingRemovals-
sync.refresh()() => Promise<boolean>--
sync.removeStranded()(did) => Promise<void>sync.removeStrandedRemoves a stranded device (group.ts strandedIn: once in a group with this one, counted by nothing now) that the holder doesn't keep: for good, as removing a bonded device is (removeDevice), with the material step (the gate first). It has no bond here, so nothing is ended, and it isn't woken. Never one of the rest where this device is the one cut off (strandedIn cutOff; review R8-14): those are the holder's other devices, and a ceremony mends it.
sync.settleRemoval()(key, o) => Promise<void>sync.settleRemovalThe holder settles a removal pending here (pendingRemovals), with the biometric (the material step): take, this device removes the install it names too; else this device removes the one that named it ("not so"). Either is this device's own removal (always taken here; on the holder's other devices judged as any, so one that counts this device takes it), written into the keyring as any removal is (owed where it doesn't land). A removal of this device itself can't be taken here (reset it instead): only "not so".
sync.upkeep()() => Promise<void>--
usePolicyobject-The holder's rules for being asked (use-policy.ts): when a device asking to use a secret is answered with the number to pick, or plainly. Set on one device, followed by all of the holder's (the log).
usePolicy.get()() => Promise<UsePolicySettings>--
here()() => Promise<{ error?: string; runs: boolean; way: "own" | "plain" | "odd" | "always"; }>-Whether this device judges asks by the holder's rules (karu runs here: tried now on a made-up ask), and which way they're set. Where it doesn't, an ask of a secret kept here takes the number.
set()(settings) => Promise<void>--
usesobject-Using a secret another of the holder's devices keeps (docs/plans/kivi-desktop.md): signed with there, the key never leaving it, or shared for one use. Every device keeping it is asked at once; the first answer wins. forgetYeses: every yes that lasts given on this device stops working now (the holder takes them back; the phone locking does the same): each program's token (review R2-1).
uses.forgetYes()(id) => void-Takes back one, by its id: its token stops working now.
uses.forgetYeses()() => void--
uses.use()(...a) => Promise<UseAnswer>--
uses.yeses()() => YesThatLasts[]-Every yes that lasts given on this device and still running, for the holder to see and take back (review R3-8).
walletOmit<{ agreedTo: (party, purpose, noticeSha256) => Promise<boolean>; claims: (credential) => Claims; clearUnanswered: (id) => Promise<SecretCredential>; consents: () => Promise<ConsentRecord[]>; credentials: () => Promise<SdJwtVcCredential & object[]>; deriveCredential: (doc) => Promise<SdJwtVcCredential>; document: (id) => Promise<DocumentCredential | undefined>; documents: () => Promise<DocumentCredential[]>; forgetHere: (id) => Promise<SecretCredential>; identity: () => Promise<IdentityKey>; keptAlsoOn: (id, where) => Promise<SecretCredential>; keptOnRing: (id, where) => Promise<SecretCredential>; markLeftTo: (id, contact, at) => Promise<SecretCredential>; markRecoverable: (id, at) => Promise<SecretCredential>; offersDelivered: (id, deliveries) => Promise<SecretCredential>; offRing: (id, ring) => Promise<SecretCredential>; recordConsent: (party, purpose, notice?, detail) => Promise<ConsentRecord>; removeSecret: (id) => Promise<void>; requestErasure: (party, fetchImpl) => Promise<{ outcome: "refused" | "unreachable" | "accepted" | "no-endpoint"; record: ConsentRecord; sent: number; }>; secrets: () => Promise<SecretCredential[]>; setListed: (id, listed) => Promise<SecretCredential>; withdrawConsent: (party, purpose?, detail) => Promise<ConsentRecord>; addDocument: Promise<DocumentCredential>; addSecret: Promise<SecretCredential>; addSecrets: Promise<SecretCredential[]>; mayAsk: Promise<boolean>; offerAnswered: Promise<SecretCredential | undefined>; openSecret: Promise<Uint8Array<ArrayBufferLike>>; openSecrets: Promise<Uint8Array<ArrayBufferLike>[]>; prepareAnswer: Promise<{ asked: object[]; protocol: string; share: (declared?) => Promise<{ vp_token: Record<string, ...[]>; }>; }>; presentTo: Promise<string>; remove: Promise<void>; shareSecret: Promise<void>; witnessDocument: Promise<{ count: number; witness: string; }>; }, "prepareAnswer"> & object--
witnessesobject--
witnesses.connect()(endpoint) => Promise<WitnessConn>--
witnesses.discover()(domain) => Promise<DiscoveredWitness>-A witness's config, from its domain's wellknown.id config.