backupKey

client.backupKey creates the tenant’s backup key for a set of custodians and delivers each their share. It proves a share yearly. It replaces a custodian without changing the key’s fingerprint.

registration

registration returns the tenant’s backup key registration.

registration(): Promise<BackupKeyRegistration | undefined>;

func registration() async throws -> BackupKeyRegistration?

suspend fun registration(): BackupKeyRegistration?

Returns: The tenant’s BackupKeyRegistration, or nothing if none exists.

Records: Nothing. Not a decision.

Errors: no-session, unreachable.

mint

mint creates the tenant’s backup key for three to seven custodians, with a quorum from two up to one fewer. The SDK splits the key into shares and delivers one to each custodian. It signs the registration after a fresh multi-factor sign-in.

mint(options: { custodians: Person[]; quorum?: number }): Promise<Decided<BackupKeyRegistration>>;

func mint(custodians: [Person], quorum: Int? = nil) async throws -> Decided<BackupKeyRegistration>

suspend fun mint(custodians: List<Person>, quorum: Int? = null): Decided<BackupKeyRegistration>

Parameter	Type	Description
`custodians`	`Person[]`	Three to seven custodians.
`quorum`	number, optional	From two up to one fewer than the custodian count.

Returns: A Decided<BackupKeyRegistration>.

Records: One decision and one access event.

Who may call it: The Owner role.

Errors: no-session, unreachable, canceled.

abandon

abandon abandons a registration before it completes. No key domain ever relied on that key.

abandon(registrationId: string): Promise<void>;

func abandon(_ registrationId: String) async throws

suspend fun abandon(registrationId: String)

Parameter	Type	Description
`registrationId`	string	The incomplete registration to abandon.

Returns: Nothing.

Records: Nothing. Not a decision.

Errors: no-session, unreachable, not-found.

receiveShare

receiveShare lets a custodian collect their share from the worklist.

receiveShare(registrationId: string): Promise<ShareDelivery>;

func receiveShare(_ registrationId: String) async throws -> ShareDelivery

suspend fun receiveShare(registrationId: String): ShareDelivery

Parameter	Type	Description
`registrationId`	string	The registration this share belongs to.

Returns: A ShareDelivery: the share to save onto the offline medium, then the receipt.

Records: Nothing. Not a decision.

Errors: no-session, unreachable, not-found.

proveShare

proveShare proves that a custodian still holds a valid share. The floor requires this once a year. It reports whether the share matches, then discards the share from memory.

proveShare(share: ShareInput): Promise<{ held: boolean }>;

func proveShare(_ share: ShareInput) async throws -> Bool

suspend fun proveShare(share: ShareInput): Boolean

Parameter	Type	Description
`share`	`ShareInput`	The custodian’s share, from a printed code or the hardware token.

Returns: held: whether the share the custodian holds is still valid. In Swift and Kotlin, the Bool or Boolean itself.

Records: Nothing. Not a decision.

Errors: no-session, unreachable.

replaceCustodian

replaceCustodian runs a ceremony that rebuilds the same key and splits it again for a new set of custodians. The fingerprint and every pin stay the same.

replaceCustodian(change: { leaving: Person; joining: Person }): Promise<Decided<Ceremony>>;

func replaceCustodian(leaving: Person, joining: Person) async throws -> Decided<Ceremony>

suspend fun replaceCustodian(leaving: Person, joining: Person): Decided<Ceremony>

Parameter	Type	Description
`leaving`	`Person`	The custodian being replaced.
`joining`	`Person`	The new custodian.

Returns: A Decided<Ceremony>. recovery describes Ceremony and Participation.

Records: One decision and one access event.

Errors: no-session, unreachable, not-found.

Types

ShareInput

A custodian’s share, presented from their offline medium: a printed code, or the hardware token through the adapter.

type ShareInput = { code: string } | { medium: 'token' };

enum ShareInput {
  case code(String)
  case token
}

sealed interface ShareInput {
  data class Code(val code: String) : ShareInput
  object Token : ShareInput
}

Case	Payload	Description
`code`	`code`	The share as a printed code.
`token`	none	The share read from the hardware token through the offline medium adapter.

BackupKeyRegistration

interface BackupKeyRegistration {
  registrationId: string;
  state: 'pending' | 'complete';
  fingerprint: string;
  custodians: { person: Person; received: boolean; lastProvedAt?: Date }[];
  quorum: number;
  mintedBy: RecipientId;
  mintedAt: Date;
}

struct BackupKeyRegistration {
  let registrationId: String
  let state: State
  let fingerprint: String
  let custodians: [(person: Person, received: Bool, lastProvedAt: Date?)]
  let quorum: Int
  let mintedBy: RecipientId
  let mintedAt: Date

  enum State { case pending, complete }
}

data class BackupKeyRegistration(
  val registrationId: String,
  val state: State,
  val fingerprint: String,
  val custodians: List<Custodian>,
  val quorum: Int,
  val mintedBy: RecipientId,
  val mintedAt: Instant,
) {
  enum class State { PENDING, COMPLETE }
  data class Custodian(val person: Person, val received: Boolean, val lastProvedAt: Instant?)
}

Field	Type	Description
`registrationId`	string	Identifies the registration.
`state`	`"pending"` or `"complete"`	Whether every custodian has received their share.
`fingerprint`	string	The key’s fingerprint, pinned on every device that signs in.
`custodians`	list of person, received and last proved	Each custodian, whether they have received their share, and when they last proved it.
`quorum`	number	How many custodians must agree to rebuild the key.
`mintedBy`	`RecipientId`	Who created the key.
`mintedAt`	date	When it was created.

ShareDelivery

On a custodian’s device: the share to save onto the offline medium, then the receipt.

interface ShareDelivery {
  registrationId: string;
  fingerprint: string;
  code?: string;
  receipt(): Promise<void>;
}

struct ShareDelivery {
  let registrationId: String
  let fingerprint: String
  let code: String?
  func receipt() async throws
}

class ShareDelivery(
  val registrationId: String,
  val fingerprint: String,
  val code: String?,
) {
  suspend fun receipt()
}

Field	Type	Description
`registrationId`	string	The registration this share belongs to.
`fingerprint`	string	The key’s fingerprint, shown beside the code.
`code`	string, optional	The share as a printable code. The SDK discards it from memory once you call `receipt()`. Absent when the offline medium adapter wrote it instead.
`receipt()`	function	This device key signs it. The Seald Healthcare Cloud then deletes its encrypted copy of the share. The SDK keeps only what it needs to verify a share later, not the share itself.