@wellknown-id/wallet/service

#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

#Returns

PagesDifferError

#Inherited from

Error.constructor

#Constructor

new PagesDifferError(message?, options?): PagesDifferError;

#Parameters

#Returns

PagesDifferError

#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): Promise<string[]>;

Registers these presentable credentials (a batch as one, under its batch id) in place of what was there. Resolves the ids registered.

#Parameters

#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

#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<{
  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

#Returns

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

#tell()

tell(k): Promise<void>;

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

#Parameters

#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

#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

#Returns

Promise<Uint8Array<ArrayBufferLike>>

#seal()

seal(data): Promise<Uint8Array<ArrayBufferLike>>;

#Parameters

#Returns

Promise<Uint8Array<ArrayBufferLike>>

#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

#Asked

type Asked = object[];

What a site asked for, as the screens show it before the holder decides (wallet.ts prepareAnswer).

#Type Declaration

#Bequest

type Bequest = object;

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

#Properties

#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"> & object;

A contact, as the screens show it. waiting: chosen here, not in the keyring yet.

#Type Declaration

#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

#ContactList

type ContactList = object;

The holder's contacts, and the bonds with someone else's devices that belong to none yet.

#Properties

#CustodyPublic

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

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

#Type Declaration

#DealingView

type DealingView = object;

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

#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, and the holder's answer.

#Properties

#Methods

#cancel()

cancel(): void;

#Returns

void

#give()

give(): Promise<void>;

#Returns

Promise<void>

#GroupSignAsk

type GroupSignAsk = object;

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

#Properties

#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;
  request: Extract<BondRequest, {
     kind: "openid4vp";
  }>;
  type: "proof";
  approve: Promise<void>;
  decline: void;
}
  | {
  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;
};

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;
  request: Extract<BondRequest, {
     kind: "openid4vp";
  }>;
  type: "proof";
  approve: Promise<void>;
  decline: void;
}

#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.

#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

#Joining

type Joining = object;

The side that joins, once connected: the six digits to compare, what the other side said, and the holder's answer. Bonding as someone else's, confirm takes the contact the other device belongs to (prd.md §7.12).

#Properties

#Methods

#cancel()

cancel(): void;

#Returns

void

#confirm()

confirm(contact?): Promise<Bond>;

#Parameters

#Returns

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

#OfferAsk

type OfferAsk = object;

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

#Properties

#Methods

#decline()

decline(reason): void;

#Parameters

#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>

#PagesCheck

type PagesCheck = object;

Where the release watch stands, for the screens.

#Properties

#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

#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

#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>

#Recovery

type Recovery = object;

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

#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

#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

#Returns

Promise<void>

#setup()

setup(): CheckSetup | undefined;

What this device checks; undefined: nothing here.

#Returns

CheckSetup | undefined

#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

#Returns

string

#SayKey

type SayKey = 
  | "reason.keep"
  | "reason.default"
  | "reason.records"
  | "reason.personas"
  | "reason.recoveryCode"
  | "reason.give"
  | "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";

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

#ServiceEvent

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

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

#Methods

#gateStatus()

gateStatus(): Promise<GateStatus>;

Whether secrets can be gated here, and how.

#Returns

Promise<GateStatus>

#wake()

wake(bond): Promise<boolean>;

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

#Parameters

#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

#Returns

Promise<void>

#decline()

decline(reason): void;

#Parameters

#Returns

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

#Returns

void

#sign()

sign(persona?, grant?): 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.

#Parameters

#Returns

Promise<void>

#SiteTerms

type SiteTerms = Delegation & object;

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

#Type Declaration

#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

#WalletService

type WalletService = ReturnType<typeof createWalletService>;

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

#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(ports): 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

#Returns