Keyvault
The Keyvault broker client and its overview: items, pending requests, grants, rules and audit.
The Keyvault broker client and its overview: items, pending requests, grants, rules and audit.
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 | Default | 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). |
favicons | Site icons the vault holds (not secret; empty while names are hidden). |
inventory | What app holds, per domain with counts (the daemon asks for Touch ID when the browse window is closed). |
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.favicons#Site icons the vault holds (not secret; empty while names are hidden).
func favicons() async -> [KvFavicon]Returns Vec<KvFavicon> ยท Async
KeyvaultClient.inventory#What app holds, per domain with counts (the daemon asks for Touch ID
when the browse window is closed). Never a value.
func inventory(app: String, profile: String?) async throws -> KvInventory| Parameter | Type | Default |
|---|---|---|
app | String | required |
profile | Option<String> | required |
Returns KvInventory ยท Async ยท Raises CuaError
KeyvaultClient.lock#Locks the vault.
func lock() async throwsAsync ยท Raises CuaError
KeyvaultClient.overview#Everything the page shows. Never fails: an unavailable Keyvault is a
state (availability).
func overview() async -> KeyvaultOverviewReturns 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 | Default | 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> | The vault's secret items, in order (app, domain, key). | |
names_visible / namesVisible | bool | Domains and keys are present in items (the browse window is open). | |
items_total / itemsTotal | u32 | Items in the vault. | |
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 | Default | 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 | Default | 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 | Default | 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. |
KvCredentialForm record#Returned by kv_credential_form.
| Field | Type | Default | 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 | Default | 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 (KV_NO_EXPIRY: only when wiped). | |
wiped | bool | Already wiped. |
KvDomainCount record#| Field | Type | Default | Description |
|---|---|---|---|
domain | String | Registrable domain. | |
cookies | u32 | Cookies. | |
session_cookies / sessionCookies | u32 | Cookies without an expiry. | |
local_storage / localStorage | u32 | localStorage values. | |
passwords | u32 | Saved passwords. | |
signin | bool | Looks like it keeps a sign-in. | |
identity_provider / identityProvider | bool | An identity provider. | |
unavailable | u32 | Cookies that cannot be read (Chrome's app-bound encryption). | |
unavailable_reason / unavailableReason | String | Why they cannot be read. |
KvFavicon record#Returned by KeyvaultClient.favicons.
| Field | Type | Default | Description |
|---|---|---|---|
site | String | The site (registrable domain). | |
png | String | PNG, base64. |
KvGrant record#| Field | Type | Default | 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. |
KvInventory record#Returned by KeyvaultClient.inventory.
| Field | Type | Default | Description |
|---|---|---|---|
provider_id / providerId | String | Provider id. | |
app_display / appDisplay | String | App name. | |
domains | Vec<KvDomainCount> | Domains with counts. | |
notes | Vec<String> | Notes. |
KvItem record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | Id. | |
kind | String | cookie, local_storage, password or file. | |
provider_id / providerId | String | The source app (chrome, slack). | |
app_display / appDisplay | String | The app's name. | |
domain | Option<String> | A cookie's host, a storage value's or password's origin; none for a file or when the names are hidden. | |
key | String | A cookie name, storage key, username or file path; empty when the names are hidden. | |
path | Option<String> | A cookie's path. | |
source | String | Profile. | |
session | bool | A cookie without an expiry. | |
expires_ms / expiresMs | Option<i64> | A cookie's expiry, Unix ms. | |
bytes | u64 | Bytes. | |
blob | Option<String> | The blob a big file's bytes live in. | |
identity_provider / identityProvider | bool | Identity providers always ask: they cannot be unlocked. | |
policy | KvItemPolicy | Policy: unattended is the unlock. | |
created_ms / createdMs | u64 | Created. | |
updated_ms / updatedMs | u64 | Last saved. | |
rev | u64 | Revision. | |
record_digest / recordDigest | String | Digest. |
KvItemPolicy record#| Field | Type | Default | Description |
|---|---|---|---|
allowed_targets / allowedTargets | Vec<String> | Allowed targets (empty: any). | |
ttl_secs / ttlSecs | u64 | Delivery lifetime. | |
unattended | bool | Unattended rules may use it. |
KvLabels record#Returned by kv_labels.
| Field | Type | Default | 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". |
KvPassphraseCheck record#Returned by kv_passphrase_check.
| Field | Type | Default | 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 | Default | 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 | Default | 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 | Default | 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. | |
auto_wipe / autoWipe | Option<bool> | Delivered copies wipe themselves after their TTL (off by default; none: not told, a broker before the setting or a third party). | |
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, linux-secret-service, passphrase, recovery). | |
browse_until_ms / browseUntilMs | Option<u64> | The browse window is open until this time, Unix ms: item names are visible until then. | |
skip_unlock_prompt / skipUnlockPrompt | Option<bool> | "Never ask again" on the unlock prompt is on. | |
reset_notice / resetNotice | Option<String> | An earlier preview's vault was found and set aside. |
KvVerification record#| Field | Type | Default | 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)
.setLocked(itemIds: [String], locked: Bool)
.deleteItems(itemIds: [String])
.setSkipUnlockPrompt(on: Bool)
.browse
.endBrowse
.revokeGrant(id: String)
.removeRule(id: String)
.setAutoWipe(on: Bool)
.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): the same as KvCommand.SetLocked with locked the other way round. Fields: item_ids: Vec<String>, unattended: bool |
SetLocked | Lock or unlock items together. Unlocking allows unattended access and asks for Touch ID once for the whole batch; locking does not. Fields: item_ids: Vec<String>, locked: bool |
DeleteItems | Delete items, wiping every live copy of them in Spaces. Fields: item_ids: Vec<String> |
SetSkipUnlockPrompt | "Never ask again" on the unlock prompt (Settings turns it back on). Fields: on: bool |
Browse | Show item names for a few minutes (the daemon asks for Touch ID). |
EndBrowse | Hide item names again. |
RevokeGrant | Revoke a grant (*: all). Fields: id: String |
RemoveRule | Remove a rule. Fields: id: String |
SetAutoWipe | Auto-wipe of delivered copies (turning it off asks for Touch ID). Fields: on: bool |
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?)
.locked(changed: [String], skipped: [String])
.deleted(count: UInt32, wiped: [String])
.browsing(untilMs: UInt64)
.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> |
Locked | Items locked or unlocked. Identity providers always ask: they are in skipped, never changed. Fields: changed: Vec<String>, skipped: Vec<String> |
Deleted | Items deleted. Fields: count: u32, wiped: Vec<String> |
Browsing | The browse window is open until then, Unix ms. Fields: until_ms: u64 |
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)
.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 |
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() -> KvLabelsReturns 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_prune_dismissed#The dismissed copies still live.
func kvPruneDismissed(overview: KeyvaultOverview, nowMs: Int64, dismissed: [String]) -> [String]| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
now_ms | i64 | required |
dismissed | Vec<String> | required |
Returns Vec<String>
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>
kv_signed_in_spaces#The ids of spaces signed in through the Keyvault (a live copy is in
them), less the dismissed copies: "Signed in" in the Spaces list
(nothing dismissed), the key on notch tiles.
func kvSignedInSpaces(overview: KeyvaultOverview, nowMs: Int64, dismissed: [String], spaces: [AppSpace]) -> [String]| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
now_ms | i64 | required |
dismissed | Vec<String> | required |
spaces | Vec<AppSpace> | required |
Returns Vec<String>
kv_space_access_key#The Access row of space's copies, to focus from its "Signed in" badge.
func kvSpaceAccessKey(overview: KeyvaultOverview, nowMs: Int64, space: AppSpace) -> String?| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
now_ms | i64 | required |
space | AppSpace | required |
Returns Option<String>
kv_visible_sharing_label#kv_sharing_label without the copies the user dismissed (import ids):
the notch indicator.
func kvVisibleSharingLabel(overview: KeyvaultOverview, nowMs: Int64, dismissed: [String]) -> String?| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
now_ms | i64 | required |
dismissed | Vec<String> | required |
Returns Option<String>