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
| Parameter | Type |
|---|---|
message? | string |
Returns
Inherited from
Error.constructor
Constructor
new PagesDifferError(message?, options?): PagesDifferError;
Parameters
| Parameter | Type |
|---|---|
message? | string |
options? | ErrorOptions |
Returns
Inherited from
Error.constructor
Properties
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
| Parameter | Type |
|---|---|
credentials | SdJwtVcCredential[] |
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
| Parameter | Type |
|---|---|
state | HolderState | 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
| Parameter | Type |
|---|---|
user | PasskeyUser |
exclude | string[] |
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
| Parameter | Type |
|---|---|
k | Keyring |
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
| Parameter | Type |
|---|---|
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
| Parameter | Type |
|---|---|
sealed | Uint8Array |
Returns
Promise<Uint8Array<ArrayBufferLike>>
seal()
seal(data): Promise<Uint8Array<ArrayBufferLike>>;
Parameters
| Parameter | Type |
|---|---|
data | Uint8Array |
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
| Parameter | Type |
|---|---|
message | string |
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
| Parameter | Type |
|---|---|
prompt | string |
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
| Parameter | Type |
|---|---|
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
Answerer
type Answerer = object;
A persona as the holder may answer as it: its id and name.
Properties
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
| Name | Type |
|---|---|
credential | object |
credential.subtitle | string |
credential.title | string |
paths | string[][] |
persona? | object |
persona.id | string |
persona.name | string |
witness? | string |
Bequest
type Bequest = object;
What a beneficiary's device shows of a legacy: only once told, or once received.
Properties
| Property | Type |
|---|---|
error? | string |
from | object |
from.contact? | string |
from.name | string |
note? | string |
received? | string |
secrets? | string[] |
series | string |
told | boolean |
Bringing
type Bringing = object;
A passkey the holder brought in that opens a second keyring (findWithPasskey): what merging does, and doing it.
Properties
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
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
| Name | Type |
|---|---|
devices | ContactDeviceHere[] |
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
| Name | Type |
|---|---|
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
| Property | Type |
|---|---|
contacts | Contact[] |
disputed? | object[] |
toTell? | object[] |
unsorted | Bond[] |
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
| Name | Type |
|---|---|
custodians | number |
DealingView
type DealingView = object;
A dealing as the dealer sees it: each custodian by contact.
Properties
| Property | Type |
|---|---|
byThisDevice | boolean |
count | number |
custodians | object[] |
dealt | string |
epoch | string |
replicas | boolean |
threshold | number |
waitMs | number |
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
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
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
| Property | Type | Description |
|---|---|---|
code | string | - |
needsProof | true | - |
network? | Network | - |
place | Promise<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 | - |
proving | Promise<Proximity> | - |
unoffered? | true | - |
yesAt | number | - |
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
| Parameter | Type |
|---|---|
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
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
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
| Property | Type |
|---|---|
signal | GiveSignal |
why | GiveUnusableWhy |
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
| Property | Type |
|---|---|
actor? | string |
change? | object |
change.added | number |
change.members | number |
change.removed | number |
change.threshold | number |
group | string |
label | string |
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
HeldShare
type HeldShare = object;
A custodian's view of a share held for someone: whose, by contact (prd.md §7.12).
Properties
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.
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.
A program on this device asks for a secret kept here, or a signature with one (programs.ts).
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
| Property | Type | Description |
|---|---|---|
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? | number | When the recovery-code copies were last checked against the keyring here (ms; keyring-holder.ts checkCodes). |
credentialId? | string | The 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? | string | On a phone: the dealing's quiet part (service/holder.ts CustodyQuiet), sealed by the quiet sealer, so notices are read without the gate. |
frozen? | FrozenHere | The 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? | string | The keyring as this device last had it (base64: keyring.ts sealKeyringHere under the seed). |
later? | string[] | - |
laterKey? | string | On 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? | string | On 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? | number | When 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? | number | The notice box, as far as this device has read it (the item sequence), and the recoveries it has heard of. |
openRoot? | string | A 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? | string | The keyring last written to its recovery copy (a hash), so it's written again only when it changes (root.ts). |
recoveredBy? | string | The recovery this device got back in by (its id): its notices are this device's own, not one to stop. |
recoveryPasskeys? | string | The 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? | string | Back 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? | number | Since 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? | string | The 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? | number | Since 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? | object | The 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.id | string | - |
root.xpub | string | - |
rootFailed? | object | What 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.at | number | - |
rootFailed.failures | object[] | - |
rootHere? | string | The 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? | number | Which 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? | object | An 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.id | string | - |
rootWaits.since | number | - |
rootWaits.xpub? | string | - |
sealedSeed | string | The 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? | boolean | Whether the holder has more than one persona in use: all a sign-in page knows of them before the keyring opens. |
shareHere? | object | This 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.root | string | - |
shareHere.sealed | string | - |
shareHere.taken? | boolean | - |
since | string | - |
successors? | SuccessorTrusts | Which 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? | string | On a phone: the list of personas (PersonaList: names, states, fingerprints, no seeds or keys), sealed the same way. |
told? | string | What the passkey providers were last told (passkeys.ts signalled), so they're told again only when it changes. |
until? | number | - |
unwritten? | string | Since 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? | string | The 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? | string | On a phone, sealed quietly: the store copies to watch for a freeze or a recovery elsewhere, each id and key (service/freeze.ts). |
writer? | string | This 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
| Name | Type | Description |
|---|---|---|
needsProof | boolean | For 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? | ProximityKind | The channel the proof uses (hearing the other, else being heard), so the screen can say how: undefined, none. |
proving | Promise<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. |
yesAt | number | When 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
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
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
OfferAsk
type OfferAsk = object;
An offer held here, put to the holder: keep it (behind the gate) or decline.
Properties
| Property | Type | Description |
|---|---|---|
bond | Bond | - |
contact? | string | From someone else's device (a copy given, prd.md §7.14): their name as this holder knows them, where they're a contact. |
offer | Offer | - |
Methods
decline()
decline(reason): void;
Parameters
| Parameter | Type |
|---|---|
reason | string |
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
| Property | Type | Description |
|---|---|---|
checking | boolean | A check is running. |
origins | string[] | 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? | boolean | Pointed at a test stack (a development build). |
unchecked? | object | The latest try got no answer: when, and why. |
unchecked.at | number | - |
unchecked.reason | string | - |
web | boolean | Where 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
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
| Property | Type |
|---|---|
at | number |
by | string |
byName? | string |
byStatic? | string |
did | string |
here? | true |
key | string |
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
| Property | Type |
|---|---|
contacts? | ContactView[] |
custody? | CustodyPublic |
grants? | GrantView[] |
groups? | GroupView[] |
legacy? | Record<string, LegacyPublic> |
names? | boolean |
onlyWayIn | boolean |
passkeys | object[] |
personas | PersonaView[] |
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
| Property | Type |
|---|---|
choices | number[] |
claimed? | string |
count | number |
how | "sign" | "share" |
id | string |
key | string |
lasts? | number |
mismatch | boolean |
missing | boolean |
names | string[] |
os? | ProgramRequester |
purpose | string |
readyAt? | number |
twoStep | boolean |
type | "program" |
urgent | true |
verified | false |
withdrawn | Promise<string> |
Methods
approve()
approve(chosen, lasting?): Promise<void>;
Parameters
| Parameter | Type |
|---|---|
chosen | number |
lasting? | boolean |
Returns
Promise<void>
confirm()
confirm(): void;
Returns
void
decline()
decline(reason?): void;
Parameters
| Parameter | Type |
|---|---|
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
Recognising
type Recognising = object;
A recovery a custodian is taking part in, before confirming: the code to compare.
Properties
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
| Name | Type |
|---|---|
custody | "none" | "dealt" | "ended" |
grants | number |
legacies | object |
legacies.dealt | string[] |
legacies.ended | string[] |
legacies.ending | string[] |
owed | RenewalView[] |
Recovery
type Recovery = object;
A recovery begun on this device: the link to give custodians, the code, and how far it has got.
Properties
| Property | Type |
|---|---|
code | string |
done? | boolean |
error? | string |
id | string |
shares | number |
since | string |
threshold? | number |
url | string |
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
| Name | Type | Description |
|---|---|---|
remove? | readonly string[] | - |
removeLost? | boolean | The 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
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
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
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
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
| Property | Type | Description |
|---|---|---|
custodians | boolean | - |
items | RecoveryItem[] | 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? | object | The 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.did | string | - |
lost.name | string | - |
lost.static? | string | - |
personas | object[] | - |
policy? | Policy | The 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
| Name | Type |
|---|---|
devices | object[] |
ReleasePorts
type ReleasePorts = object;
What the release watch needs from the platform: what to check, a fetch, and somewhere to keep its state.
Properties
Methods
load()
load(): Promise<unknown>;
What the watch keeps between checks, on this device only.
Returns
Promise<unknown>
save()
save(state): Promise<void>;
Parameters
| Parameter | Type |
|---|---|
state | unknown |
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
| Property | Type |
|---|---|
id | string |
kind | RenewalKind |
last? | string |
name? | string |
sealed? | string |
since | number |
tries | number |
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
| Name | Type |
|---|---|
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
RingProgress
type RingProgress = object;
Properties
| Property | Type |
|---|---|
at? | number |
of? | number |
step | RingStep |
words | string |
RingSecret
type RingSecret = object;
What a copy on a ring holds, sealed: enough to bring the secret back on a new device.
Properties
| Property | Type |
|---|---|
copy | string |
fileName? | string |
name | string |
secretType | SecretCredential["secretType"] |
service? | string |
slot? | number |
value | Uint8Array |
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
| Property | Type |
|---|---|
added | string |
by | string |
id | string |
name | string |
securityKey? | RingRecord["securityKey"] |
slots | RingSlot[] |
tapCopies | boolean |
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
| Name | Type | Description |
|---|---|---|
gathered | number | Shares gathered here in person, for the next root act (gather), and how many the devices way needs. |
joinable | object[] | The holder's own devices bonded here that the devices way doesn't name (kivi offers to add them: decision 5). |
needed? | number | - |
suggested | Policy | The 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
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
| Property | Type |
|---|---|
at? | number |
reason? | string |
site | string |
status | SiteStatus |
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
| Property | Type |
|---|---|
id | string |
kind | "rotation" | "burn" |
next? | string |
persona | string |
sites | RotationSite[] |
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
| Parameter | Type |
|---|---|
key | SayKey |
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
| Property | Type |
|---|---|
copyOf? | string |
fileName? | string |
name | string |
secretType | SecretCredential["secretType"] |
service? | string |
value | Uint8Array |
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
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
| Property | Type |
|---|---|
copies | SecretListing[] |
rings | object[] |
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
| Property | Type |
|---|---|
on? | SecretElsewhere |
ring? | object |
ring.copy | string |
ring.name | string |
ring.needsPin | boolean |
ring.ring | string |
s | SecretCredential |
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
| Property | Type | Description |
|---|---|---|
bondingLimits? | () => object | Bonding'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). |
bonds | BondStore & LogStore & OfferStore | Bonds (with update), the sync log, offers held. |
clock? | Clock | The time; tests move it. |
credentials | CredentialStore | Documents, secrets' notes, consents. |
custodyLimits? | () => object | The wait a dealing may be made with, at least (prd.md §7.11: 72 hours); a development build's tests shorten it. |
device | Device | What this device calls itself, and its platform. |
directory? | DirectoryClient | wellknown.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. |
drops | DropStore | Drop boxes at the relay: what bonded devices leave for this one while it's away. |
fetch | typeof fetch | Fetch, 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. |
gate | Sealer | The biometric gate (a browser: a non-extractable key, no prompt). Seals secrets and the holder's seed. |
holderState | HolderStore | The holder's state on this device (the default persona's sealed seed, this device's keyring copy). |
keys | KeyStore | The device's identity key and credential keys. |
location? | LocationPort | This 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? | boolean | A 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). |
passkeys | Passkeys | The platform's passkeys, with PRF: the holder's unlock. |
policy? | object | karu, 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.explain | Promise<{ allow: string[]; decision: "ALLOW" | "DENY"; deny: string[]; }> | - |
proximity? | ProximityPort | Ways 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? | object | This device's push token as last fetched, straight away (for answering pings). |
push.known | PushHandle | undefined | - |
quiet? | QuietSealer | On a phone: what's read without the gate. None in a browser. |
registry? | CredentialRegistry | Where sites find this wallet's credentials (Android's Credential Manager); none in a browser. |
relay | Relay | The relay's mailboxes. |
release? | ReleasePorts | The release watch: kivi's check of the pages wellknown.id serves against the signed release log. |
ring? | RingPort | Keeper rings, where this device can reach one (NFC). |
say | Say | The service's words, in the holder's language. |
screen? | object | When 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 | - |
store | EncryptedStore | The encrypted store (keyrings, recovery-code copies, the personas' mailboxes) and drop boxes, at the relay. |
syncLimits? | () => object | Syncing'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? | TrustStore | Document signers' trust anchors (CSCA certificates), for checking passports and ID cards. |
witness? | object | A witness's connection (its protocol's WebSocket); by default the platform's WebSocket (witness.ts connectWitness). |
witness.connect | Promise<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
| Parameter | Type |
|---|---|
bond | Bond |
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
Methods
accept()
accept(o?): Promise<void>;
Parameters
| Parameter | Type |
|---|---|
o? | { keepOn?: readonly string[]; name?: string; } |
o.keepOn? | readonly string[] |
o.name? | string |
Returns
Promise<void>
decline()
decline(reason): void;
Parameters
| Parameter | Type |
|---|---|
reason | string |
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
| Name | Type |
|---|---|
yesAt | Promise<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
Methods
decline()
decline(reason?): void;
Parameters
| Parameter | Type |
|---|---|
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
| Parameter | Type |
|---|---|
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
| Name | Type |
|---|---|
site | string |
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
| Property | Type |
|---|---|
forwarded | boolean |
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
| Property | Type |
|---|---|
bound? | SshBound |
id | string |
name | string |
readyAt? | number |
requester? | UseRequester |
signing | SshSigning |
type | "ssh-ring" |
urgent | true |
withdrawn | Promise<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
| Property | Type |
|---|---|
at | number |
checked | number |
commit? | string |
differences? | Difference[] |
release? | number |
rollingOut? | string[] |
scope | Scope |
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
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
| Property | Type |
|---|---|
alg? | SignAlg |
by | string |
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
| Property | Type |
|---|---|
asked? | string[] |
declined? | object |
declined.device | string |
declined.reason | string |
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
| Property | Type |
|---|---|
alg? | SignAlg | "SK-ES256" |
also? | string[] |
copy? | string |
how | "sign" | "share" |
match? | number |
message? | Uint8Array |
messages? | Uint8Array[] |
name? | string |
purpose | string |
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
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
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
| Parameter | Type |
|---|---|
given | ServicePorts |
Returns
| Name | Type | Default value | Description |
|---|---|---|---|
addresses | object | - | 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. |
bonds | object | - | - |
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.deviceNames | The 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.personasToGive | The 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. |
contacts | object | - | 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.choose | Which 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.list | The 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.remove | Removes 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.tell | The 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). |
custodians | object | - | 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.afterRecovery | Back in through custodians, and not dealt again yet: the dealing to retire, and whom this device reaches. |
custodians.callOff() | (shareId) => Promise<void> | custodians.callOff | A recovery under way through this custodian, called off here (before its release). |
custodians.cancelRecovery() | () => Promise<void> | custodians.cancelRecovery | - |
custodians.checkNotices() | () => Promise<boolean> | custodians.checkNotices | Reads 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.view | The 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.dropHeld | A share this custodian wants to delete: told to the holder (as no longer held) the next time they ask. |
custodians.held() | () => Promise<HeldShare[]> | custodians.held | The shares this device holds for others (accepted), newest first. |
custodians.markRecoverable() | (secretId, on) => Promise<void> | custodians.markRecoverable | Marks 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.nextAsk | The share waiting longest for this device's holder, if any, to put to them. |
custodians.notices() | () => Promise<RecoveryNotice & object[]> | custodians.notices | The 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.pollRecovery | Reads 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.recognise | The 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.recovery | The recovery begun here, if any, and how far it has got. |
custodians.releaseDue() | () => Promise<number> | custodians.releaseDue | For 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.startRecovery | Begins 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.stop | Stops 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). |
debug | object | - | 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). |
device | Device | ports.device | What this device calls itself (the device port). |
freeze | object | - | 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.check | The 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.recovery | object | freeze.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.removed | This 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.upgrade | object | freeze.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). |
give | object | - | - |
give.connect() | (...a) => Promise<GiveAsk | undefined> | - | - |
grants | object | - | 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.drop | Stops 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.give | Lets 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.list | The grants as the keyring has them (without asking: from the list the holder already sees). |
grants.takeBack() | (id) => Promise<void> | delegation.takeBack | Takes 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.terms | The site's terms for delegation, from its wellknown.id config. Throws if it has none, or doesn't accept it. |
groups | object | - | 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.act | Asks 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.changeMembers | Changes 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.found | Founds 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.list | The 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.takeBack | Takes 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). |
holder | object | - | - |
holder.addPasskeyHere() | () => Promise<void> | holder.addPasskeyHere | Adds 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.addPersona | Adds a persona named name (made unique). Resolves its id. |
holder.addPersonaWithCode() | (code) => Promise<CodeOutcome> | holder.addPersonaWithCode | A 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.begin | Rotation 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) => void | holder.rotation.cancel | The next sheet put away unconfirmed: the rotation isn't begun, and S and the proofs are wiped. |
holder.cancelSuccessor() | (persona) => void | holder.cancelSuccessor | The successor sheet just made is put away unconfirmed: nothing goes into the keyring. |
holder.cancelSuccessorChange() | (persona) => Promise<void> | holder.cancelSuccessorChange | Cancels 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.defaultPersona | The 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.defaultPersonaId | The default persona's id alone (defaultPersona). |
holder.findWithPasskey() | (elsewhere) => Promise<Bringing | undefined> | holder.findWithPasskey | - |
holder.forget() | (...args) => Promise<void> | holder.forget | Forgets the holder's wellknown.id on this device (their personas stay reachable through their unlocks). |
holder.forgetPersona() | (id) => Promise<undefined> | holder.forgetPersona | - |
holder.hide() | () => void | holder.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.makeSuccessor | A 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.noticeAlarms | Sites 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.openRecords | On 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.personaFields | A 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.recordsWaiting | Whether 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.refresh | The 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.rename | Renames 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.resend | Sends 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.reveal | Shows 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.view | Where 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.settleConflict | The 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>>> | undefined | holder.shown | What's been revealed, by persona id; undefined while hidden. |
holder.signInChoice() | (site) => Promise<Choice | undefined> | holder.signInChoice | Which 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.startNew | For 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.state | What 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.successorSites | The 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.trustWithCode | A 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.unlockWithPasskey | With 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.unlockWithRecoveryCode | With 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> | - | - |
legacy | object | - | 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.agree | This 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.bequests | What 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.checkNotices | Reads 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.deal | Deals 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.end | Ends 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.held | The 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.leave | Leaves 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.views | The legacies the keyring notes, each with its terms and what's left to the beneficiary from here. |
legacy.notices() | () => Promise<LegacyNotice & object[]> | legacy.notices | The custodians' agreements this device has heard of, newest first, each with who it's left to, by name. |
legacy.releaseDue() | () => Promise<number> | legacy.releaseDue | For 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.signOfLife | A 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.withoutContact | Removing 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. |
offers | object | - | - |
offers.askBack() | (...a) => Promise<Uint8Array<ArrayBufferLike>> | - | - |
offers.keepSecret() | (...a) => Promise<{ deliveries: Delivery[]; record: SecretCredential; }> | - | - |
offers.nextAsk() | () => Promise<OfferAsk | undefined> | offers.nextAsk | The 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. |
pages | object | - | - |
pages.check() | (o) => Promise<PagesCheck> | pages.check | Checks 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() | () => PagesCheck | pages.now | - |
programs | object | - | 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.endpoint | The 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.handle | One 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() | () => number | programs.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). |
rings | object | - | 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.add | Adds 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() | () => void | rings.cancel | - |
rings.drop() | (secretId, ringId, pin, o) => Promise<void> | rings.drop | Removes 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.forget | Forgets 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.keep | Keeps 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.keepOnlyOnRing | Keeps 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.lockCopies | Puts 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.look | Reads 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.open | A 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.rename | Gives a ring another name, on every device of the holder's. |
rings.restore() | (name, pin?, o) => Promise<{ onRing: number; restored: number; unreadable: number; }> | rings.restore | Brings 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() | () => boolean | rings.supported | - |
root | object | - | 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.addDevice | Adds a device bonded here to the devices way (a root act, decision 5): it holds a share from the new root on. |
root.clearGathered() | () => void | root.clearGathered | - |
root.gather() | (origin?) => Promise<{ code: Promise<string>; done: Promise<{ gathered: number; name: string; }>; url: string; cancel: void; }> | root.gather | Gathering 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.give | The 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.renew | Makes 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.setPolicy | Changes 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.vouchFor | Shows 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). |
secrets | object | - | 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.list | The 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. |
shares | object | - | 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.give | Gives 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.lend | Lends 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.of | What's lent and given, by contact, for a secret kept here (its card). |
shares.present() | (o) => Promise<void> | shares.present | Shows 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.presentable | What 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.stopLending | Stops 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.takeBack | Takes 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. |
signIn | object | - | - |
signIn.connect() | (...a) => Promise<SignInAsk | undefined> | - | - |
ssh | object | - | 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) => void | ssh.gone | An agent connection closed (ssh gave up): its asks still open are withdrawn, and won't sign (R2-24). |
ssh.keys() | () => Promise<object[]> | ssh.keys | The holder's SSH keys, as SSH names them (blob) with their secrets' names as comments: no one asked. |
ssh.newKey() | (o) => object | ssh.newKey | A 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>> | - | - |
sync | object | - | - |
sync.otherDevices() | () => Promise<CatalogueDevice[]> | sync.otherDevices | - |
sync.pendingRemovals() | () => Promise<PendingRemoval[]> | sync.pendingRemovals | - |
sync.refresh() | () => Promise<boolean> | - | - |
sync.removeStranded() | (did) => Promise<void> | sync.removeStranded | Removes 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.settleRemoval | The 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> | - | - |
usePolicy | object | - | 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> | - | - |
uses | object | - | 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). |
wallet | Omit<{ 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 | - | - |
witnesses | object | - | - |
witnesses.connect() | (endpoint) => Promise<WitnessConn> | - | - |
witnesses.discover() | (domain) => Promise<DiscoveredWitness> | - | A witness's config, from its domain's wellknown.id config. |