Keyvault screens
The Keyvault page, sidebar, the vault list (apps, sites and items with their locks), the unlock prompt and the approval prompt.
The Keyvault page, sidebar, the vault list (apps, sites and items with their locks), the unlock prompt and the approval prompt.
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.
The kv_* functions derive each Keyvault screen from a KeyvaultOverview. kv_vault_view groups the vault by source app and site, with a lock on each row; kv_vault_reduce applies search, selection and open groups; kv_unlock_prompt is the "Allow unattended access?" prompt. kv_approval_open, kv_approval_reduce and kv_approval_view drive the approval prompt; the *_command functions return the KvCommand to send.
KvAccessRow record#| Field | Type | Default | Description |
|---|---|---|---|
kind | KvAccessKind | Kind. | |
key | String | Stable key. | |
text | String | Main text. | |
detail | String | Muted detail. | |
action_label / actionLabel | String | "Revoke", "Remove", "Wipe". | |
command | KvCommand | What the button sends. | |
imports | Vec<String> | A Space's copies: their import ids, which Dismiss hides from the notch (empty for grants and rules). |
KvAccessKind enum#.grant
.rule
.delivery| Variant | Description |
|---|---|
Grant | A grant. |
Rule | An unattended rule. |
Delivery | Copies in a Space. |
KvRecentRow record#| Field | Type | Default | Description |
|---|---|---|---|
decision | KvDecision | The decision. | |
age | String | "now", "5 min ago". |
KvDecision record#| Field | Type | Default | Description |
|---|---|---|---|
entry | KvAuditEntry | The entry. | |
verb | String | "Approved". | |
tone | KvDecisionTone | Tone. | |
what | String | Item and target, or the actor. |
KvDecisionTone enum#.ok
.deny
.info| Variant | Description |
|---|---|
Ok | Allowed or delivered. |
Deny | Denied, refused, failed. |
Info | Everything else. |
KvTri enum#.on
.off
.mixed| Variant | Description |
|---|---|
On | All on. |
Off | All off. |
Mixed | Some. |
KvSelection enum#.category(category: KvCategory)
.app(key: String)| Variant | Description |
|---|---|
Category | A category. Fields: category: KvCategory |
App | One app's items. Fields: key: String |
KvSigningBadge record#| Field | Type | Default | Description |
|---|---|---|---|
text | String | "signed, team X". | |
tone | KvTone | Tone. |
KvTone enum#.ok
.warn
.danger| Variant | Description |
|---|---|
Ok | Verified. |
Warn | Caution. |
Danger | Untrusted. |
KvAppRow record#| Field | Type | Default | Description |
|---|---|---|---|
key | String | The provider id (chrome): the key, and what the icon is looked up by. | |
title | String | "Google Chrome". | |
items | u32 | Items. | |
waiting | bool | Something waits for this app. |
KvApprovalRow record#| Field | Type | Default | Description |
|---|---|---|---|
key | String | Row key: <app>|<site>, <app>|files, or import:<n>. | |
title | String | The site, or the app for files and imports. | |
account | String | "3 cookies, 1 password", or "Not saved yet". | |
provider_id / providerId | String | The app's provider id (its icon), when known. | |
items | u32 | Items the row stands for. | |
item_ids / itemIds | Vec<String> | The items' ids. | |
selected | bool | Ticked. | |
is_import / isImport | bool | A new item the approval imports. |
KvApprovalState record#Returned by kv_approval_open, kv_approval_reduce.
| Field | Type | Default | Description |
|---|---|---|---|
request_id / requestId | String | The request. | |
selected | Vec<String> | Ticked row keys (<app>|<site>, or import:<n> for new items). |
KvApprovalView record#Returned by kv_approval_view.
| Field | Type | Default | Description |
|---|---|---|---|
request_id / requestId | String | The request. | |
title | String | "Allow com.example.koalabot?" | |
caller | String | Verified caller (short). | |
badge | KvSigningBadge | Signing badge. | |
targets | String | Where to ("dev-1"). | |
wants | String | For how long. | |
summary | String | One-line summary. | |
claims | Vec<String> | Unverified claims. | |
rows | Vec<KvApprovalRow> | Rows. | |
can_approve / canApprove | bool | Approve is enabled. | |
blocked_reason / blockedReason | Option<String> | Why not, in one line (none when it can, or nothing is ticked yet). | |
approve_label / approveLabel | String | "Approve 2 items". | |
gone | bool | The request is gone (answered elsewhere). |
KvCategoryRow record#| Field | Type | Default | Description |
|---|---|---|---|
category | KvCategory | Category. | |
title | String | Title. | |
symbol | String | SF Symbol. | |
count | Option<u32> | Count (none for Recent). | |
badge | Option<u32> | The sidebar badge: Waiting's count while something waits. |
KvDeleteConfirm record#Returned by kv_delete_confirm.
| Field | Type | Default | Description |
|---|---|---|---|
title | String | "Delete 3 items?" | |
message | String | What deleting does. | |
confirm | String | "Delete". | |
cancel | String | "Cancel". |
KvListView record#Returned by kv_list.
| Field | Type | Default | Description |
|---|---|---|---|
title | String | Title. | |
vault | bool | The vault list shows (All Items, or one app). | |
pending | Vec<KvPendingRow> | Waiting. | |
access | Vec<KvAccessRow> | Access. | |
recent | Vec<KvRecentRow> | Recent. | |
empty_text / emptyText | Option<String> | "Nothing is waiting." and friends. |
KvPage record#Returned by kv_page.
| Field | Type | Default | Description |
|---|---|---|---|
ready | bool | Items can be shown. | |
unavailable_title / unavailableTitle | Option<String> | The unavailable heading. | |
message | Option<String> | The broker's sentence. | |
can_setup / canSetup | bool | "Set up Keyvault" shows. | |
can_unlock / canUnlock | bool | "Unlock" shows. | |
kill_switch_visible / killSwitchVisible | bool | The Disable switch shows (this app is first party, a vault exists). | |
kill_switch_enabled / killSwitchEnabled | bool | The switch can be flipped (unlocked). | |
disabled | bool | The kill switch is on. | |
disabled_banner / disabledBanner | Option<String> | "Keyvault is off. Nothing can be teleported." | |
partial_errors / partialErrors | Vec<String> | Sections that failed to load. | |
log_status / logStatus | Option<String> | "Log verified" / "Log tampered at #n". | |
log_tampered / logTampered | bool | The log check failed. | |
protection | Vec<AppFact> | Protection facts. | |
revoke_all / revokeAll | bool | "Revoke all" shows (more than one live grant). | |
has_items / hasItems | bool | Items exist. | |
search_visible / searchVisible | bool | Search shows (any item exists). | |
skip_unlock_prompt / skipUnlockPrompt | bool | "Never ask again" on the unlock prompt is on (Settings turns it off). | |
reset_notice / resetNotice | Option<String> | An earlier preview's vault was set aside: one line to show. | |
pending_count / pendingCount | u32 | Pending requests (the sidebar badge). | |
kill_switch_help / killSwitchHelp | String | The switch's tooltip (it reads "on" while the Keyvault works). | |
labels | KvLabels | The page's fixed words. | |
form | Option<KvCredentialForm> | The setup or unlock form, when one applies. |
KvPendingRow record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | Request id. | |
caller | String | Short caller. | |
badge | KvSigningBadge | Signing badge. | |
summary | String | What and where. | |
wants | String | For how long. | |
claims | Vec<String> | Unverified claims (tooltip). |
KvSidebar record#Returned by kv_sidebar.
| Field | Type | Default | Description |
|---|---|---|---|
categories | Vec<KvCategoryRow> | All Items, Waiting, Access, Recent. | |
apps | Vec<KvAppRow> | One row per app, by name. |
KvUnlockPrompt record#Returned by kv_unlock_prompt, kv_unlock_prompt_always.
| Field | Type | Default | Description |
|---|---|---|---|
title | String | "Allow unattended access?" | |
message | String | What it allows. | |
subject | String | "3 items" (a batch), or the one item's name. | |
deny | String | "Deny". | |
allow | String | "Allow". | |
never_ask / neverAsk | String | "Never ask again". |
KvVaultApp record#| Field | Type | Default | Description |
|---|---|---|---|
key | String | Group key: the provider id (chrome). | |
provider_id / providerId | String | The provider id, for the app's icon. | |
name | String | "Google Chrome". | |
count | u32 | Items. | |
summary | String | "212 items, 14 unlocked". | |
updated | String | Grey time of the newest save. | |
selected | KvTri | Selection of its items. | |
lock | KvLock | Lock of its items. | |
unlock_ids / unlockIds | Vec<String> | Items a click on the lock unlocks (locked, not identity providers). | |
lock_ids / lockIds | Vec<String> | Items a click on the lock locks (unlocked). | |
open | bool | Open. | |
sites | Vec<KvVaultSite> | Sites with their items, by name. | |
files | Option<KvVaultFiles> | Files, when it has any. |
KvVaultFiles record#| Field | Type | Default | Description |
|---|---|---|---|
key | String | Group key. | |
count | u32 | Files. | |
selected | KvTri | Selection of its items. | |
lock | KvLock | Lock of its items. | |
unlock_ids / unlockIds | Vec<String> | Items a click on the lock unlocks (locked, not identity providers). | |
lock_ids / lockIds | Vec<String> | Items a click on the lock locks (unlocked). | |
open | bool | Open. | |
rows | Vec<KvVaultRow> | Its rows (empty while closed, unless searching). |
KvVaultRow record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | Item id. | |
kind | KvKind | Type. | |
kind_label / kindLabel | String | "Cookie". | |
symbol | String | The type's SF Symbol. | |
title | String | The key: a cookie name, storage key, username or file name. | |
subtitle | String | Grey line: the domain, or the file's folder. | |
updated | String | Grey time: "2 min ago". | |
locked | bool | Locked (needs approval for every use). | |
lock_symbol / lockSymbol | String | The lock icon: lock.fill or lock.open. | |
lock_help / lockHelp | String | The lock's tooltip and accessibility label. | |
identity_provider / identityProvider | bool | Identity provider: always asks, cannot be unlocked. | |
selected | bool | Selected. |
KvVaultSelection record#| Field | Type | Default | Description |
|---|---|---|---|
count | u32 | Selected items. | |
ids | Vec<String> | Their ids, in list order. | |
title | String | "3 selected". | |
can_unlock / canUnlock | bool | Some selected item is locked and may be unlocked. | |
can_lock / canLock | bool | Some selected item is unlocked. | |
always_ask / alwaysAsk | u32 | Selected items that always ask (identity providers). | |
unlock_ids / unlockIds | Vec<String> | The ids to send when unlocking (locked, not identity providers). | |
lock_ids / lockIds | Vec<String> | The ids to send when locking (unlocked). |
KvVaultSite record#| Field | Type | Default | Description |
|---|---|---|---|
key | String | Group key. | |
site | String | "github.com". | |
count | u32 | Items (all of them, even while closed). | |
counts | String | "12 cookies, 2 storage values". | |
updated | String | Grey time of the newest save. | |
selected | KvTri | Selection of its items. | |
lock | KvLock | Lock of its items. | |
unlock_ids / unlockIds | Vec<String> | Items a click on the lock unlocks (locked, not identity providers). | |
lock_ids / lockIds | Vec<String> | Items a click on the lock locks (unlocked). | |
open | bool | Open. | |
rows | Vec<KvVaultRow> | Its rows (empty while closed, unless searching). |
KvVaultSource record#Returned by kv_vault_source.
| Field | Type | Default | Description |
|---|---|---|---|
count | u32 | Items that can be sent. | |
newest_ms / newestMs | i64 | When the newest was saved, Unix ms (0: none). | |
ids | Vec<String> | Their ids, in list order. | |
password_ids / passwordIds | Vec<String> | The app's saved passwords (ids), never part of ids: they are sent only when ticked in the review. |
KvVaultState record#Returned by kv_vault_prune, kv_vault_reduce.
| Field | Type | Default | Description |
|---|---|---|---|
query | String | The search text. | |
selected | Vec<String> | Selected item ids. | |
expanded | Vec<String> | Open groups (their keys); the rest are closed. | |
app | Option<String> | Narrowed to one app (its provider id), as the sidebar picks it. |
KvVaultView record#Returned by kv_vault_view.
| Field | Type | Default | Description |
|---|---|---|---|
apps | Vec<KvVaultApp> | Apps, by name. | |
shown | u32 | Items shown (after search). | |
total | u32 | Items in the vault. | |
empty_text / emptyText | Option<String> | "No items yet." and friends. | |
names_hidden / namesHidden | bool | Domains and keys are hidden until the user confirms with Touch ID. | |
hidden_note / hiddenNote | Option<String> | What to say about it. | |
show_names_label / showNamesLabel | String | The button that opens the names. | |
search_prompt / searchPrompt | String | The search field's prompt. | |
selection | KvVaultSelection | The selection. | |
can_select_all / canSelectAll | bool | Select all is offered. |
KvApprovalAction enum#.toggle(key: String)
.selectAll
.clear| Variant | Description |
|---|---|
Toggle | Tick or untick a row. Fields: key: String |
SelectAll | Tick every row. |
Clear | Untick every row. |
KvCategory enum#.all
.waiting
.access
.recent| Variant | Description |
|---|---|
All | Every item, grouped by app. |
Waiting | Requests waiting for approval. |
Access | Live grants, rules and copies. |
Recent | Recent decisions. |
KvKind enum#.cookie
.localStorage
.password
.file| Variant | Description |
|---|---|
Cookie | A cookie. |
LocalStorage | A localStorage value. |
Password | A saved password. |
File | A file. |
KvLock enum#.locked
.unlocked
.mixed| Variant | Description |
|---|---|
Locked | Every item needs approval for each use. |
Unlocked | Every item allows unattended access. |
Mixed | Some of each. |
KvVaultAction enum#.query(text: String)
.toggle(id: String)
.toggleGroup(key: String)
.selectAll
.clear
.toggleOpen(key: String)| Variant | Description |
|---|---|
Query | The search text changed. Fields: text: String |
Toggle | Select or deselect one item. Fields: id: String |
ToggleGroup | Select or deselect every shown item of an app, a site or the files of an app (all of them when any is unselected, none when all are). Fields: key: String |
SelectAll | Select every shown item. |
Clear | Deselect everything. |
ToggleOpen | Open or close a group. Fields: key: String |
kv_approval_approve_command#What Approve sends (none while it cannot).
func kvApprovalApproveCommand(overview: KeyvaultOverview, state: KvApprovalState) -> KvCommand?| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
state | KvApprovalState | required |
Returns Option<KvCommand>
kv_approval_deny_command#What Deny sends.
func kvApprovalDenyCommand(state: KvApprovalState) -> KvCommand| Parameter | Type | Default |
|---|---|---|
state | KvApprovalState | required |
Returns KvCommand
kv_approval_open#Opens the approval sheet with nothing selected.
func kvApprovalOpen(requestId: String) -> KvApprovalState| Parameter | Type | Default |
|---|---|---|
request_id | String | required |
Returns KvApprovalState
kv_approval_reduce#Advances the approval sheet.
func kvApprovalReduce(overview: KeyvaultOverview, state: KvApprovalState, action: KvApprovalAction) -> KvApprovalState| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
state | KvApprovalState | required |
action | KvApprovalAction | required |
Returns KvApprovalState
kv_approval_view#The approval sheet as drawn.
func kvApprovalView(overview: KeyvaultOverview, state: KvApprovalState) -> KvApprovalView| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
state | KvApprovalState | required |
Returns KvApprovalView
kv_delete_command#The command that deletes items and wipes their copies in Spaces.
func kvDeleteCommand(ids: [String]) -> KvCommand| Parameter | Type | Default |
|---|---|---|
ids | Vec<String> | required |
Returns KvCommand
kv_delete_confirm#The delete confirmation.
func kvDeleteConfirm(count: UInt32, liveCopies: UInt32) -> KvDeleteConfirm| Parameter | Type | Default |
|---|---|---|
count | u32 | required |
live_copies | u32 | required |
Returns KvDeleteConfirm
kv_list#The pane for a sidebar selection (the vault list is kv_vault_view).
func kvList(overview: KeyvaultOverview, selection: KvSelection, nowMs: Int64) -> KvListView| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
selection | KvSelection | required |
now_ms | i64 | required |
Returns KvListView
kv_live_copy_spaces#How many Spaces hold a live copy of any of ids.
func kvLiveCopySpaces(overview: KeyvaultOverview, ids: [String], nowMs: Int64) -> UInt32| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
ids | Vec<String> | required |
now_ms | i64 | required |
Returns u32
kv_lock_command#The command that locks items.
func kvLockCommand(ids: [String]) -> KvCommand| Parameter | Type | Default |
|---|---|---|
ids | Vec<String> | required |
Returns KvCommand
kv_page#The page chrome.
func kvPage(overview: KeyvaultOverview, nowMs: Int64) -> KvPage| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
now_ms | i64 | required |
Returns KvPage
kv_sidebar#The sidebar: All Items, Waiting, Access, Recent, and one row per app.
func kvSidebar(overview: KeyvaultOverview, nowMs: Int64) -> KvSidebar| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
now_ms | i64 | required |
Returns KvSidebar
kv_unlock_command#The command that unlocks items (the daemon asks for Touch ID once).
func kvUnlockCommand(ids: [String]) -> KvCommand| Parameter | Type | Default |
|---|---|---|
ids | Vec<String> | required |
Returns KvCommand
kv_unlock_prompt#The unlock prompt for count items (name: the one item's name). None
when the user chose "Never ask again".
func kvUnlockPrompt(overview: KeyvaultOverview, count: UInt32, name: String?) -> KvUnlockPrompt?| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
count | u32 | required |
name | Option<String> | required |
Returns Option<KvUnlockPrompt>
kv_unlock_prompt_always#The unlock prompt whatever the setting says.
func kvUnlockPromptAlways(count: UInt32, name: String?) -> KvUnlockPrompt| Parameter | Type | Default |
|---|---|---|
count | u32 | required |
name | Option<String> | required |
Returns KvUnlockPrompt
kv_vault_prune#The selection without what the vault no longer holds.
func kvVaultPrune(overview: KeyvaultOverview, state: KvVaultState) -> KvVaultState| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
state | KvVaultState | required |
Returns KvVaultState
kv_vault_reduce#The vault list's next state (search, selection, open groups).
func kvVaultReduce(overview: KeyvaultOverview, state: KvVaultState, action: KvVaultAction) -> KvVaultState| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
state | KvVaultState | required |
action | KvVaultAction | required |
Returns KvVaultState
kv_vault_source#What the Keyvault holds for provider_id that a teleport can send.
func kvVaultSource(overview: KeyvaultOverview, providerId: String) -> KvVaultSource| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
provider_id | String | required |
Returns KvVaultSource
kv_vault_view#The vault list: apps, sites and items with their locks, the selection and the batch bar.
func kvVaultView(overview: KeyvaultOverview, state: KvVaultState, nowMs: Int64) -> KvVaultView| Parameter | Type | Default |
|---|---|---|
overview | KeyvaultOverview | required |
state | KvVaultState | required |
now_ms | i64 | required |
Returns KvVaultView