domains

client.domains lets a domain owner share and unshare a key domain, hand off domain ownership, create a sub-domain and manage the recycle bin.

share

share gives a person or group access to the key domain. Only a domain owner can share. A share costs one decision and one access event for the whole key domain. It changes only the key domain’s key material, not any stored object.

TypeScript

share(root: Locator, to: ShareTarget): Promise<Decided<{ escrowVersion: number }>>

Swift

func share(_ root: Locator, to: ShareTarget) async throws -> Decided<Int>

Kotlin

suspend fun share(root: Locator, to: ShareTarget): Decided<Int>

Parameters

Name	Type	Description
root	Locator	The key domain’s root.
to	ShareTarget	A person or a group to share with.

Returns: Decided, and on allow the new escrowVersion.

Records: Share Record.

Who may call it: A domain owner only.

Errors: locked, no-session, trust-failed.

unshare

unshare removes access at once and starts a new epoch. The Owner role may unshare any key domain.

TypeScript

unshare(root: Locator, from: ShareTarget): Promise<Decided<{ epoch: number }>>

Swift

func unshare(_ root: Locator, from: ShareTarget) async throws -> Decided<Int>

Kotlin

suspend fun unshare(root: Locator, from: ShareTarget): Decided<Int>

Parameters

Name	Type	Description
root	Locator	The key domain’s root.
from	ShareTarget	The person or group to remove.

Returns: Decided, and on allow the new epoch.

Records: One decision and one access event.

Who may call it: A domain owner, or the Owner role for any key domain.

Errors: locked, no-session.

shareRecord

shareRecord shares one record’s versions with a person outside the key domain, as a record recipient. Each version needs its own share. The key domain, not the record, is the unit of sharing.

TypeScript

shareRecord(locator: Locator, to: Person): Promise<Decided<{ versions: number }>>

Swift

func shareRecord(_ locator: Locator, to: Person) async throws -> Decided<Int>

Kotlin

suspend fun shareRecord(locator: Locator, to: Person): Decided<Int>

Parameters

Name	Type	Description
locator	Locator	The record to share.
to	Person	The person to add as a record recipient.

Returns: Decided, and on allow how many versions were shared.

Records: Share Record.

Errors: locked, no-session.

unshareRecord

unshareRecord removes a record recipient’s access to one record.

TypeScript

unshareRecord(locator: Locator, from: Person): Promise<Decided<{}>>

Swift

func unshareRecord(_ locator: Locator, from: Person) async throws -> Decided<Void>

Kotlin

suspend fun unshareRecord(locator: Locator, from: Person): Decided<Unit>

Parameters

Name	Type	Description
locator	Locator	The record to stop sharing.
from	Person	The record recipient to remove.

Returns: Decided<{}>.

Records: One decision and one access event.

Errors: locked, no-session.

makeOwner

makeOwner makes a member a domain owner. A key domain always keeps at least one domain owner with a device.

TypeScript

makeOwner(root: Locator, person: Person): Promise<Decided<{}>>

Swift

func makeOwner(_ root: Locator, person: Person) async throws -> Decided<Void>

Kotlin

suspend fun makeOwner(root: Locator, person: Person): Decided<Unit>

Parameters

Name	Type	Description
root	Locator	The key domain.
person	Person	The member to make a domain owner.

Returns: Decided<{}>.

Records: Share Record.

Who may call it: A domain owner.

Errors: locked, no-session.

giveUpOwnership

giveUpOwnership gives up domain ownership while another domain owner remains.

TypeScript

giveUpOwnership(root: Locator): Promise<Decided<{}>>

Swift

func giveUpOwnership(_ root: Locator) async throws -> Decided<Void>

Kotlin

suspend fun giveUpOwnership(root: Locator): Decided<Unit>

Parameters

Name	Type	Description
root	Locator	The key domain.

Returns: Decided<{}>.

Records: One decision and one access event.

Who may call it: A domain owner. The SDK refuses it for the last domain owner.

Errors: locked, no-session.

members

members returns who can see a key domain.

TypeScript

members(root: Locator): Promise<Membership>

Swift

func members(_ root: Locator) async throws -> Membership

Kotlin

suspend fun members(root: Locator): Membership

Parameters

Name	Type	Description
root	Locator	The key domain.

Returns: The key domain’s Membership.

Records: Nothing. Not a decision.

Errors: locked, no-session.

create

create turns an empty folder below a dataset’s root into a key domain. A domain owner of the enclosing key domain calls it and becomes the first domain owner.

TypeScript

create(folder: Locator, options?: { members?: ShareTarget[] }): Promise<Decided<{ root: Locator }>>

Swift

func create(_ folder: Locator, members: [ShareTarget] = []) async throws -> Decided<Locator>

Kotlin

suspend fun create(folder: Locator, members: List<ShareTarget> = emptyList()): Decided<Locator>

Parameters

Name	Type	Description
folder	Locator	The empty folder to turn into a key domain’s root.
options	{ members?: ShareTarget[] }, optional	Members to share the new key domain with at once.

Returns: Decided, and on allow the new key domain’s root locator.

Records: Share Record.

Who may call it: A domain owner of the enclosing key domain.

Errors: locked, no-session.

delete

delete retires a whole key domain into the recycle bin.

TypeScript

delete(root: Locator): Promise<Decided<{}>>

Swift

func delete(_ root: Locator) async throws -> Decided<Void>

Kotlin

suspend fun delete(root: Locator): Decided<Unit>

Parameters

Name	Type	Description
root	Locator	The key domain to retire.

Returns: Decided<{}>.

Records: Delete.

Who may call it: A domain owner. The SDK refuses it under a legal hold or the retention floor.

Errors: locked, no-session.

recycleBin

recycleBin lists what a key domain’s domain owners see of its retired versions, objects and key domains. Nothing leaves the recycle bin on its own.

TypeScript

recycleBin(root?: Locator): Promise<RecycleBinItem[]>

Swift

func recycleBin(_ root: Locator? = nil) async throws -> [RecycleBinItem]

Kotlin

suspend fun recycleBin(root: Locator? = null): List<RecycleBinItem>

Parameters

Name	Type	Description
root	Locator, optional	Restricts the listing to this key domain. Otherwise lists every key domain the person owns.

Returns: The matching RecycleBinItem list.

Records: Nothing. Not a decision.

Who may call it: A domain owner.

Errors: locked, no-session.

restore

restore returns a retired item from the recycle bin.

TypeScript

restore(item: RecycleBinItem): Promise<Decided<{}>>

Swift

func restore(_ item: RecycleBinItem) async throws -> Decided<Void>

Kotlin

suspend fun restore(item: RecycleBinItem): Decided<Unit>

Parameters

Name	Type	Description
item	RecycleBinItem	The item to restore, from recycleBin().

Returns: Decided<{}>.

Records: Restore.

Who may call it: A domain owner.

Errors: locked, no-session.

shred

shred destroys items for good. Break-glass recovery cannot reverse it. The tombstone keeps the locator, the version and their access events.

TypeScript

shred(items: RecycleBinItem[]): Promise<Decided<{}>>

Swift

func shred(_ items: [RecycleBinItem]) async throws -> Decided<Void>

Kotlin

suspend fun shred(items: List<RecycleBinItem>): Decided<Unit>

Parameters

Name	Type	Description
items	RecycleBinItem[]	The items to shred. The SDK refuses any item under a legal hold.

Returns: Decided<{}>.

Records: Delete.

Who may call it: A domain owner.

Errors: locked, no-session.

Types

ShareTarget

TypeScript

type ShareTarget = { person: Person } | { group: Group };

Swift

enum ShareTarget {
  case person(Person)
  case group(Group)
}

Kotlin

sealed interface ShareTarget {
  data class ToPerson(val person: Person) : ShareTarget
  data class ToGroup(val group: Group) : ShareTarget
}

Who a share, unshare or new key domain membership names: a Person, or a group by name. In Swift: ShareTarget.person(p) or .group("x"). In Kotlin: ShareTarget.ToPerson(p) or ShareTarget.ToGroup("x").

Membership

TypeScript

interface Membership {
  root: Locator;
  dataset: string;
  owners: Person[];
  members: { person: Person; through?: Group[] }[];
  groups: Group[];
  recordRecipients: { locator: Locator; person: Person }[];
  epoch: number;
  escrowVersion: number;
}

Swift

struct Membership {
  let root: Locator
  let dataset: String
  let owners: [Person]
  let members: [(person: Person, through: [Group]?)]
  let groups: [Group]
  let recordRecipients: [(locator: Locator, person: Person)]
  let epoch: Int
  let escrowVersion: Int
}

Kotlin

data class Membership(
  val root: Locator,
  val dataset: String,
  val owners: List<Person>,
  val members: List<Member>,
  val groups: List<Group>,
  val recordRecipients: List<RecordRecipient>,
  val epoch: Int,
  val escrowVersion: Int,
)

Field	Type	Description
root	Locator	The key domain’s root.
dataset	string	The dataset this key domain belongs to.
owners	Person[]	The key domain’s current domain owners.
members	{ person, through? }[]	Every member, and the group they joined through, where they joined through one.
groups	Group[]	The groups mapped into this key domain.
recordRecipients	{ locator, person }[]	The one-record shares made with shareRecord.
epoch	number	The key domain’s current epoch.
escrowVersion	number	The current version of the key domain’s key material.

RecycleBinItem

TypeScript

interface RecycleBinItem {
  kind: 'version' | 'object' | 'domain';
  locator: Locator;
  version?: number;
  retiredAt: Date;
  retiredBy: RecipientId;
  held: boolean;
}

Swift

struct RecycleBinItem {
  let kind: RecycleBinItem.Kind
  let locator: Locator
  let version: Int?
  let retiredAt: Date
  let retiredBy: RecipientId
  let held: Bool
}

Kotlin

data class RecycleBinItem(
  val kind: RecycleBinItemKind,
  val locator: Locator,
  val version: Int? = null,
  val retiredAt: Instant,
  val retiredBy: RecipientId,
  val held: Boolean,
)

Field	Type	Description
kind	'version' | 'object' | 'domain'	What was retired.
locator	Locator	The retired item’s locator.
version	number, optional	The retired version, for kind: 'version'.
retiredAt	Date	When it was retired.
retiredBy	RecipientId	The device that retired it.
held	boolean	True while a legal hold keeps it in the bin.

Domains

TypeScript

interface Domains {
  share(root: Locator, to: ShareTarget): Promise<Decided<{ escrowVersion: number }>>;
  unshare(root: Locator, from: ShareTarget): Promise<Decided<{ epoch: number }>>;
  shareRecord(locator: Locator, to: Person): Promise<Decided<{ versions: number }>>;
  unshareRecord(locator: Locator, from: Person): Promise<Decided<{}>>;
  makeOwner(root: Locator, person: Person): Promise<Decided<{}>>;
  giveUpOwnership(root: Locator): Promise<Decided<{}>>;
  members(root: Locator): Promise<Membership>;
  create(folder: Locator, options?: { members?: ShareTarget[] }): Promise<Decided<{ root: Locator }>>;
  delete(root: Locator): Promise<Decided<{}>>;
  recycleBin(root?: Locator): Promise<RecycleBinItem[]>;
  restore(item: RecycleBinItem): Promise<Decided<{}>>;
  shred(items: RecycleBinItem[]): Promise<Decided<{}>>;
}

Swift

class Domains {
  func share(_ root: Locator, to: ShareTarget) async throws -> Decided<Int>
  func unshare(_ root: Locator, from: ShareTarget) async throws -> Decided<Int>
  func shareRecord(_ locator: Locator, to: Person) async throws -> Decided<Int>
  func unshareRecord(_ locator: Locator, from: Person) async throws -> Decided<Void>
  func makeOwner(_ root: Locator, person: Person) async throws -> Decided<Void>
  func giveUpOwnership(_ root: Locator) async throws -> Decided<Void>
  func members(_ root: Locator) async throws -> Membership
  func create(_ folder: Locator, members: [ShareTarget] = []) async throws -> Decided<Locator>
  func delete(_ root: Locator) async throws -> Decided<Void>
  func recycleBin(_ root: Locator? = nil) async throws -> [RecycleBinItem]
  func restore(_ item: RecycleBinItem) async throws -> Decided<Void>
  func shred(_ items: [RecycleBinItem]) async throws -> Decided<Void>
}

Kotlin

class Domains {
  suspend fun share(root: Locator, to: ShareTarget): Decided<Int>
  suspend fun unshare(root: Locator, from: ShareTarget): Decided<Int>
  suspend fun shareRecord(locator: Locator, to: Person): Decided<Int>
  suspend fun unshareRecord(locator: Locator, from: Person): Decided<Unit>
  suspend fun makeOwner(root: Locator, person: Person): Decided<Unit>
  suspend fun giveUpOwnership(root: Locator): Decided<Unit>
  suspend fun members(root: Locator): Membership
  suspend fun create(folder: Locator, members: List<ShareTarget> = emptyList()): Decided<Locator>
  suspend fun delete(root: Locator): Decided<Unit>
  suspend fun recycleBin(root: Locator? = null): List<RecycleBinItem>
  suspend fun restore(item: RecycleBinItem): Decided<Unit>
  suspend fun shred(items: List<RecycleBinItem>): Decided<Unit>
}

Domains groups the twelve methods above into the namespace client.domains.