Keyvault

The Keyvault broker client and its overview: items, pending requests, grants, rules and audit.

Cua Spaces app export

These APIs are part of the Cua Spaces app export for building Spaces UIs. They are source-available under FSL-1.1-MIT and ship for Swift only (import CuaSpacesFFI); the Rust tab shows the cua-spaces-ffi crate they come from. The open source SDK packages for Python, TypeScript and Kotlin do not include them.

KeyvaultClient talks to the Keyvault broker and returns a KeyvaultOverview. The screens derived from it are on Keyvault screens.

`AppSensitiveOption` record#

Returned by app_picker_sensitive_options.

Field	Type	Description
`group`	`AppSensitiveGroup`	The group.
`label`	`String`	Label.
`detail`	`String`	The line under the label.
`checked`	`bool`	Checked.

`AppSensitiveGroup` enum#

.signIns
.passwords
.history

Variant	Description
`SignIns`	The session cookies: what keeps the app signed in.
`Passwords`	Saved passwords.
`History`	Browsing history.

`app_sensitive_group_sdk`#

The SDK's plan-option group for a picker group.

func appSensitiveGroupSdk(group: AppSensitiveGroup) -> TeleportSensitiveGroup

Parameter	Type	Default
`group`	`AppSensitiveGroup`	required

Returns TeleportSensitiveGroup

`KeyvaultClient`#

The Keyvault broker client: the verified connection to the broker cua daemon hosts on $CUA_HOME/keyvault.sock. The broker checks this process's code signature; approvals, re-enabling and unattended-on make the daemon ask for Touch ID. No call returns a secret value.

Method	Description
`new`	The broker in `cua_home` (`None`: `$CUA_HOME`, else `~/.cua`).
`execute`	Runs one page action (a broker request).
`lock`	Locks the vault.
`overview`	Everything the page shows.
`setup_with_passphrase`	Creates the vault with a passphrase (and a recovery key, returned once).
`unlock_with_passphrase`	Unlocks with the passphrase (sent only to the broker; zeroized here).

`KeyvaultClient.new`#

The broker in cua_home (None: $CUA_HOME, else ~/.cua).

init(cuaHome: String?)

Parameter	Type	Default
`cua_home`	`Option<String>`	required

Returns KeyvaultClient

`KeyvaultClient.execute`#

Runs one page action (a broker request).

func execute(command: KvCommand) async throws -> KvOutcome

Parameter	Type	Default
`command`	`KvCommand`	required

Returns KvOutcome · Async · Raises CuaError

`KeyvaultClient.lock`#

Locks the vault.

func lock() async throws

Async · Raises CuaError

`KeyvaultClient.overview`#

Everything the page shows. Never fails: an unavailable Keyvault is a state (availability).

func overview() async -> KeyvaultOverview

Returns KeyvaultOverview · Async

`KeyvaultClient.setup_with_passphrase`#

Creates the vault with a passphrase (and a recovery key, returned once). The passphrase goes only to the broker over the verified Keyvault socket; it is never logged or kept, and zeroized here.

func setupWithPassphrase(passphrase: String) async throws -> String?

Parameter	Type	Default
`passphrase`	`String`	required

Returns Option<String> · Async · Raises CuaError

`KeyvaultClient.unlock_with_passphrase`#

Unlocks with the passphrase (sent only to the broker; zeroized here).

func unlockWithPassphrase(passphrase: String) async throws

Parameter	Type	Default
`passphrase`	`String`	required

Async · Raises CuaError

`KeyvaultOverview` record#

Returned by KeyvaultClient.overview, kv_overview_from_json.

Field	Type	Description
`availability`	`String`	`ready`, or why not: `not_running`, `impostor`, `connect`, `no_vault`, `locked`, `not_first_party`, `unsupported`, `error`.
`message`	`Option<String>`	A sentence when not ready.
`status`	`Option<KvStatus>`	The broker's status.
`server_verified` / `serverVerified`	`bool`	The daemon was checked against Cua's signature.
`items`	`Vec<KvItem>`	Items.
`pending`	`Vec<KvPending>`	Pending requests.
`grants`	`Vec<KvGrant>`	Grants.
`rules`	`Vec<KvRule>`	Rules.
`deliveries`	`Vec<KvDelivery>`	Deliveries.
`audit`	`Vec<KvAuditEntry>`	Audit tail, oldest first.
`audit_verification` / `auditVerification`	`Option<KvVerification>`	Chain check.
`partial_errors` / `partialErrors`	`Vec<String>`	Sections that failed while the rest loaded.

`KvAccessRequest` record#

Field	Type	Description
`selectors`	`Vec<KvSelector>`	What.
`targets`	`Vec<String>`	Where.
`actions`	`Vec<String>`	Actions.
`duration_secs` / `durationSecs`	`Option<u64>`	For how long.
`uses`	`Option<u32>`	Uses.
`reason`	`String`	The caller's reason (unverified).
`claimed_name` / `claimedName`	`Option<String>`	The caller's name for itself (unverified).
`agent`	`Option<String>`	The named agent the request is for (unverified).

`KvAuditEntry` record#

Field	Type	Description
`seq`	`u64`	Sequence.
`ts_ms` / `tsMs`	`u64`	Time.
`kind`	`String`	Kind (`consent.allow`, ...).
`actor`	`String`	Actor.
`caller_fp` / `callerFp`	`String`	Caller fingerprint.
`item`	`Option<String>`	Item.
`target`	`Option<String>`	Target.
`decision`	`String`	`ok`, `allow`, `deny`, `error`.
`detail`	`Option<String>`	Detail.
`authless`	`Option<bool>`	Written without the MAC key.

`KvCaller` record#

Field	Type	Description
`pid`	`i32`	Pid.
`uid`	`u32`	Uid.
`path`	`Option<String>`	Executable.
`signing`	`KvSigning`	Signing.
`first_party` / `firstParty`	`bool`	Satisfied the Cua requirement.
`os_verified` / `osVerified`	`bool`	The OS verified the signature.
`launched_by` / `launchedBy`	`Option<String>`	Launched by.
`verified_name` / `verifiedName`	`Option<String>`	OS-verified leaf name.

`KvCookieInfo` record#

Field	Type	Description
`name`	`String`	Name.
`domain`	`String`	Domain.
`session`	`bool`	Session cookie.
`expires_ms` / `expiresMs`	`Option<i64>`	Expiry.

`KvCredentialForm` record#

Returned by kv_credential_form.

Field	Type	Description
`mode`	`KvFormMode`	Setup or unlock.
`method`	`KvMethod`	Touch ID or a passphrase.
`help`	`String`	One line under the form.
`passphrase_label` / `passphraseLabel`	`Option<String>`	The passphrase field's label (passphrase only).
`confirm_label` / `confirmLabel`	`Option<String>`	The second field's label (passphrase setup only).
`submit_label` / `submitLabel`	`String`	The button.

`KvDelivery` record#

Field	Type	Description
`import_id` / `importId`	`String`	Import id.
`target`	`String`	Target.
`provider_id` / `providerId`	`String`	Provider.
`items`	`Vec<String>`	Items.
`caller_fp` / `callerFp`	`String`	Caller fingerprint.
`delivered_ms` / `deliveredMs`	`u64`	Delivered.
`expires_ms` / `expiresMs`	`u64`	Wiped at.
`wiped`	`bool`	Already wiped.

`KvGrant` record#

Field	Type	Description
`id`	`String`	Id.
`request_id` / `requestId`	`String`	Request.
`caller_fp` / `callerFp`	`String`	Caller fingerprint.
`caller_display` / `callerDisplay`	`String`	Caller.
`items`	`Vec<String>`	Items.
`targets`	`Vec<String>`	Targets.
`actions`	`Vec<String>`	Actions.
`created_ms` / `createdMs`	`u64`	Created.
`not_after_ms` / `notAfterMs`	`u64`	Expires.
`uses_left` / `usesLeft`	`Option<u32>`	Uses left (none: unlimited until expiry).
`revoked`	`bool`	Revoked.
`agent`	`Option<String>`	The named agent it was approved for.

`KvItem` record#

Field	Type	Description
`id`	`String`	Id.
`kind`	`String`	`browser_site`, `site_passwords`, `app_session`.
`label`	`String`	Label.
`provider_id` / `providerId`	`String`	Provider.
`app_display` / `appDisplay`	`String`	App.
`site`	`Option<String>`	Site.
`account`	`Option<String>`	Account.
`source`	`String`	Profile.
`summary`	`KvItemSummary`	Summary.
`warnings`	`Vec<String>`	Warnings.
`identity_provider` / `identityProvider`	`bool`	Identity providers always ask.
`policy`	`KvItemPolicy`	Policy.
`created_ms` / `createdMs`	`u64`	Created.
`updated_ms` / `updatedMs`	`u64`	Updated.
`rev`	`u64`	Revision.
`record_digest` / `recordDigest`	`String`	Digest.

`KvItemPolicy` record#

Field	Type	Description
`allowed_targets` / `allowedTargets`	`Vec<String>`	Allowed targets (empty: any).
`ttl_secs` / `ttlSecs`	`u64`	Delivery lifetime.
`unattended`	`bool`	Unattended rules may use it.

`KvItemSummary` record#

Field	Type	Description
`cookies`	`Vec<KvCookieInfo>`	Cookies.
`storage_origins` / `storageOrigins`	`Vec<String>`	Storage origins.
`passwords`	`u32`	Saved passwords.
`files`	`Vec<String>`	Files.
`keychain_services` / `keychainServices`	`Vec<String>`	Keychain services.
`bytes`	`u64`	Bytes.

`KvLabels` record#

Returned by kv_labels.

Field	Type	Description
`deny`	`String`	"Deny".
`review`	`String`	"Review…" (opens the approval sheet).
`cancel`	`String`	"Cancel".
`set_up` / `setUp`	`String`	"Set up Keyvault".
`unlock`	`String`	"Unlock".
`revoke_all` / `revokeAll`	`String`	"Revoke all".
`confirm_note` / `confirmNote`	`String`	Under the approval sheet.
`protection_title` / `protectionTitle`	`String`	"Protection".
`accounts_title` / `accountsTitle`	`String`	A site's accounts section.
`app_label` / `appLabel`	`String`	A site's app fact.
`every_account` / `everyAccount`	`String`	A site's switch.

`KvPassphraseCheck` record#

Returned by kv_passphrase_check.

Field	Type	Description
`can_submit` / `canSubmit`	`bool`	The button is enabled.
`strength`	`Option<KvStrength>`	Setup only, once something is typed.
`hint`	`Option<String>`	One short line under the fields.

`KvPending` record#

Field	Type	Description
`id`	`String`	Id.
`caller`	`KvCaller`	Verified caller.
`caller_fp` / `callerFp`	`String`	Fingerprint.
`caller_display` / `callerDisplay`	`String`	One-line verified identity.
`request`	`KvAccessRequest`	The request.
`items`	`Vec<KvItem>`	Existing items it resolves to.
`needs_import` / `needsImport`	`Vec<KvSelector>`	Selectors approval would import.
`created_ms` / `createdMs`	`u64`	Created.

`KvRule` record#

Field	Type	Description
`id`	`String`	Id.
`items`	`Vec<String>`	Items.
`targets`	`Vec<String>`	Targets (`*`: any Space).
`callers`	`Vec<KvRuleCaller>`	Callers.
`created_ms` / `createdMs`	`u64`	Created.
`not_after_ms` / `notAfterMs`	`u64`	Expires.
`enabled`	`bool`	Enabled.
`note`	`String`	Note.

`KvRuleCaller` record#

Field	Type	Default	Description
`fp`	`String`		Fingerprint.
`display`	`String`		Display.

`KvStatus` record#

Field	Type	Description
`version`	`String`	Version.
`initialized`	`bool`	A vault exists.
`unlocked`	`bool`	Unlocked.
`disabled`	`bool`	The kill switch is on.
`caller_first_party` / `callerFirstParty`	`bool`	This app is first party.
`caller_display` / `callerDisplay`	`String`	How the broker sees this app.
`items`	`u32`	Items.
`pending`	`u32`	Pending requests.
`unlock_policy` / `unlockPolicy`	`Option<String>`	`auto` or `presence`.
`os_protector_available` / `osProtectorAvailable`	`bool`	The daemon can create the OS key store protector (setup offers Touch ID); false for a development daemon, which is passphrase-only.
`passphrase_available` / `passphraseAvailable`	`bool`	A passphrase can always be chosen.
`unlock_protectors` / `unlockProtectors`	`Vec<String>`	Protector kinds that can unlock this vault now (`macos-keychain`, `windows-credential`, `passphrase`, `recovery`).

`KvVerification` record#

Field	Type	Description
`ok`	`bool`	Intact.
`entries`	`u64`	Entries.
`unauthenticated`	`u64`	Entries without a MAC.
`tampered_line` / `tamperedLine`	`Option<u64>`	First tampered line.
`reason`	`Option<String>`	Why.

`KvCommand` enum#

.setup
.unlock
.setDisabled(disabled: Bool)
.setUnattended(itemIds: [String], unattended: Bool)
.revokeGrant(id: String)
.removeRule(id: String)
.release(target: String)
.approve(requestId: String, items: [String]?)
.deny(requestId: String)

Variant	Description
`Setup`	Create the vault with the OS key store (the daemon asks for presence). A passphrase never travels in a command: the shells pass it to `KeyvaultCommands::setup_with_passphrase` directly.
`Unlock`	Unlock with the OS key store (a passphrase goes to `KeyvaultCommands::unlock_with_passphrase`).
`SetDisabled`	The kill switch (turning it off asks for Touch ID). Fields: `disabled: bool`
`SetUnattended`	Per-item unattended (turning on asks for Touch ID). Fields: `item_ids: Vec<String>`, `unattended: bool`
`RevokeGrant`	Revoke a grant (`*`: all). Fields: `id: String`
`RemoveRule`	Remove a rule. Fields: `id: String`
`Release`	Wipe a Space's copies. Fields: `target: String`
`Approve`	Approve a request for exactly these items (the daemon asks for presence). `None` keeps everything the request asked for, which the approval sheet only sends when the user ticked every row. Fields: `request_id: String`, `items: Option<Vec<String>>`
`Deny`	Deny a request. Fields: `request_id: String`

`KvFormMode` enum#

.setup
.unlock

Variant	Description
`Setup`	No vault yet.
`Unlock`	The vault is locked.

`KvMethod` enum#

.touchId
.passphrase

Variant	Description
`TouchId`	The OS key store (the login keychain), confirmed with Touch ID.
`Passphrase`	A passphrase.

`KvOutcome` enum#

.done
.recoveryKey(key: String?)
.items(items: [KvItem])
.revoked(count: UInt32)
.wiped(imports: [String])
.granted(grant: KvGrant)

Variant	Description
`Done`	Nothing to show.
`RecoveryKey`	The recovery key, shown once and never stored. Fields: `key: Option<String>`
`Items`	Items after a policy change. Fields: `items: Vec<KvItem>`
`Revoked`	Grants revoked. Fields: `count: u32`
`Wiped`	Imports wiped. Fields: `imports: Vec<String>`
`Granted`	The grant an approval minted. Fields: `grant: KvGrant`

`KvSelector` enum#

.item(id: String)
.site(app: String, site: String, account: String?)
.app(app: String)
.login(site: String)

Variant	Description
`Item`	An existing item. Fields: `id: String`
`Site`	A site of an app. Fields: `app: String`, `site: String`, `account: Option<String>`
`App`	A whole app. Fields: `app: String`
`Login`	A site's saved password, used to sign in (never delivered). Fields: `site: String`

`KvSigning` enum#

.signed(teamId: String, identifier: String, cdhash: String)
.adHoc(identifier: String, cdhash: String)
.unsigned
.unknown

Variant	Description
`Signed`	Team-signed. Fields: `team_id: String`, `identifier: String`, `cdhash: String`
`AdHoc`	Ad hoc. Fields: `identifier: String`, `cdhash: String`
`Unsigned`	Unsigned.
`Unknown`	Unknown platform.

`KvStrength` enum#

.weak
.fair
.strong

Variant	Description
`Weak`	Too short, or easy to guess.
`Fair`	Acceptable.
`Strong`	Long and varied.

`kv_credential_form`#

The setup or unlock form for an overview (also KvPage.form): Touch ID when the daemon can use the OS key store, else a passphrase.

func kvCredentialForm(overview: KeyvaultOverview) -> KvCredentialForm?

Parameter	Type	Default
`overview`	`KeyvaultOverview`	required

Returns Option<KvCredentialForm>

`kv_duration`#

A duration in words ("5 min").

func kvDuration(ms: Int64) -> String

Parameter	Type	Default
`ms`	`i64`	required

Returns String

`kv_labels`#

The Keyvault's fixed words.

func kvLabels() -> KvLabels

Returns KvLabels

`kv_overview_from_json`#

A Keyvault overview from JSON (fixtures, parity flows). Fixture data only: it carries metadata, never a secret value.

func kvOverviewFromJson(json: String) throws -> KeyvaultOverview

Parameter	Type	Default
`json`	`String`	required

Returns KeyvaultOverview · Raises CuaError

`kv_passphrase_check`#

The passphrase fields' hint and whether the form can be sent. Pure: the passphrase is only measured, never kept.

func kvPassphraseCheck(mode: KvFormMode, passphrase: String, confirm: String) -> KvPassphraseCheck

Parameter	Type	Default
`mode`	`KvFormMode`	required
`passphrase`	`String`	required
`confirm`	`String`	required

Returns KvPassphraseCheck

`kv_recovery_key_text`#

The banner after setup: the recovery key, shown once.

func kvRecoveryKeyText(key: String) -> String

Parameter	Type	Default
`key`	`String`	required

Returns String

`kv_sharing_label`#

The always-visible signal while Keyvault sign-ins are live in a Space (the notch indicator and the menu bar line); none when nothing is live.

func kvSharingLabel(overview: KeyvaultOverview, nowMs: Int64) -> String?

Parameter	Type	Default
`overview`	`KeyvaultOverview`	required
`now_ms`	`i64`	required

Returns Option<String>

Keyvault

AppSensitiveOption record#

AppSensitiveGroup enum#

app_sensitive_group_sdk#

KeyvaultClient#

KeyvaultClient.new#

KeyvaultClient.execute#

KeyvaultClient.lock#

KeyvaultClient.overview#

KeyvaultClient.setup_with_passphrase#

KeyvaultClient.unlock_with_passphrase#

KeyvaultOverview record#

KvAccessRequest record#

KvAuditEntry record#

KvCaller record#

KvCookieInfo record#

KvCredentialForm record#

KvDelivery record#

KvGrant record#

KvItem record#

KvItemPolicy record#

KvItemSummary record#

KvLabels record#

KvPassphraseCheck record#

KvPending record#

KvRule record#

KvRuleCaller record#

KvStatus record#

KvVerification record#

KvCommand enum#

KvFormMode enum#

KvMethod enum#

KvOutcome enum#

KvSelector enum#

KvSigning enum#

KvStrength enum#

kv_credential_form#

kv_duration#

kv_labels#

kv_overview_from_json#

kv_passphrase_check#

kv_recovery_key_text#

kv_sharing_label#

AppSensitiveOption record#

AppSensitiveGroup enum#

app_sensitive_group_sdk#

KeyvaultClient#

KeyvaultClient.new#

KeyvaultClient.execute#

KeyvaultClient.lock#

KeyvaultClient.overview#

KeyvaultClient.setup_with_passphrase#

KeyvaultClient.unlock_with_passphrase#

KeyvaultOverview record#

KvAccessRequest record#

KvAuditEntry record#

KvCaller record#

KvCookieInfo record#

KvCredentialForm record#

KvDelivery record#

KvGrant record#

KvItem record#

KvItemPolicy record#

KvItemSummary record#

KvLabels record#

KvPassphraseCheck record#

KvPending record#

KvRule record#

KvRuleCaller record#

KvStatus record#

KvVerification record#

KvCommand enum#

KvFormMode enum#

KvMethod enum#

KvOutcome enum#

KvSelector enum#

KvSigning enum#

KvStrength enum#

kv_credential_form#

kv_duration#

`AppSensitiveOption` record#

`AppSensitiveGroup` enum#

`app_sensitive_group_sdk`#

`KeyvaultClient`#

`KeyvaultClient.new`#

`KeyvaultClient.execute`#

`KeyvaultClient.lock`#

`KeyvaultClient.overview`#

`KeyvaultClient.setup_with_passphrase`#

`KeyvaultClient.unlock_with_passphrase`#

`KeyvaultOverview` record#

`KvAccessRequest` record#

`KvAuditEntry` record#

`KvCaller` record#

`KvCookieInfo` record#

`KvCredentialForm` record#

`KvDelivery` record#

`KvGrant` record#

`KvItem` record#

`KvItemPolicy` record#

`KvItemSummary` record#

`KvLabels` record#

`KvPassphraseCheck` record#

`KvPending` record#

`KvRule` record#

`KvRuleCaller` record#

`KvStatus` record#

`KvVerification` record#

`KvCommand` enum#

`KvFormMode` enum#

`KvMethod` enum#

`KvOutcome` enum#

`KvSelector` enum#

`KvSigning` enum#

`KvStrength` enum#

`kv_credential_form`#

`kv_duration`#

`kv_labels`#

`kv_overview_from_json`#

`kv_passphrase_check`#

`kv_recovery_key_text`#

`kv_sharing_label`#

`AppSensitiveOption` record#

`AppSensitiveGroup` enum#

`app_sensitive_group_sdk`#

`KeyvaultClient`#

`KeyvaultClient.new`#

`KeyvaultClient.execute`#

`KeyvaultClient.lock`#

`KeyvaultClient.overview`#

`KeyvaultClient.setup_with_passphrase`#

`KeyvaultClient.unlock_with_passphrase`#

`KeyvaultOverview` record#

`KvAccessRequest` record#

`KvAuditEntry` record#

`KvCaller` record#

`KvCookieInfo` record#

`KvCredentialForm` record#

`KvDelivery` record#

`KvGrant` record#

`KvItem` record#

`KvItemPolicy` record#

`KvItemSummary` record#

`KvLabels` record#

`KvPassphraseCheck` record#

`KvPending` record#

`KvRule` record#

`KvRuleCaller` record#

`KvStatus` record#

`KvVerification` record#

`KvCommand` enum#

`KvFormMode` enum#

`KvMethod` enum#

`KvOutcome` enum#

`KvSelector` enum#

`KvSigning` enum#

`KvStrength` enum#

`kv_credential_form`#

`kv_duration`#

`kv_labels`#