# ol.trixnity.key

Encryption-key state, backup state, and trust-level queries.

## Upstream Mapping

This namespace maps to Trixnity’s `KeyService` and `KeyBackupService`.

The public wrappers here cover:

* current and flow-based backup bootstrap state
* cross-signing bootstrap
* current and flow-based backup-version observation
* trust-level queries for users, devices, and timeline events
* device-key and cross-signing-key lookup

Use [`ol.trixnity.verification`](api/ol-trixnity-verification.adoc) for active verification workflows and
[`ol.trixnity.room`](api/ol-trixnity-room.adoc) when you need room timeline events to pair with
trust-level checks.

## current-bootstrap-running

```clojure
(current-bootstrap-running client)
```

Returns whether cross-signing bootstrap is currently running.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/key.clj#L28-L31)

---

## bootstrap-running

```clojure
(bootstrap-running client)
```

Returns a Missionary flow of cross-signing bootstrap state.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/key.clj#L33-L37)

---

## bootstrap-cross-signing!

```clojure
(bootstrap-cross-signing! client)
(bootstrap-cross-signing! client opts)
```

Bootstraps cross-signing for the current Matrix account.

Returns a Missionary task. The task resolves to a normalized map with:

* `::mx/kind` — `"success"`, `"uia-required"`, or `"uia-error"`
* `::mx/recovery-key` — the recovery key generated by Trixnity
* `::mx/uia` — a UIA snapshot with completed stages, flows, session, and error details

By default this calls Trixnity’s `KeyService.bootstrapCrossSigning()`. If
`opts` includes `::mx/password`, the bridge attempts to complete a password
UIA step before returning. `::mx/user-id` can override the password UIA user
identifier; otherwise the current client’s Matrix user id is used.

`"uia-required"` and `"uia-error"` results do not expose Trixnity UIA
objects. Inspect `::mx/uia` to decide which public UIA flow or error remains.

Persist or display `::mx/recovery-key` securely; it is the user’s recovery
key material for the new bootstrap.

Be aware that upstream cross-signing bootstrap can replace existing
cross-signing and key-backup state for the account.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/key.clj#L39-L65)

---

## bootstrap-cross-signing-from-passphrase!

```clojure
(bootstrap-cross-signing-from-passphrase! client passphrase)
(bootstrap-cross-signing-from-passphrase! client passphrase opts)
```

Bootstraps cross-signing with a secret-storage passphrase.

Returns the same normalized Missionary task result as
[`bootstrap-cross-signing!`](#bootstrap-cross-signing!), but calls Trixnity’s
`KeyService.bootstrapCrossSigningFromPassphrase(passphrase)`.
`passphrase` configures the generated secret storage; use `::mx/password` in
`opts` for password-based UIA completion.

Be aware that upstream cross-signing bootstrap can replace existing
cross-signing and key-backup state for the account.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/key.clj#L67-L87)

---

## current-backup-version

```clojure
(current-backup-version client)
```

Returns the current active room-key-backup version, or nil when unavailable.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/key.clj#L89-L92)

---

## backup-version

```clojure
(backup-version client)
```

Returns a Missionary flow of the active room-key-backup version.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/key.clj#L94-L98)

---

## get-trust-level

```clojure
(get-trust-level client user-id)
(get-trust-level client user-id-or-room-id device-id-or-event-id)
```

Returns a Missionary flow of trust information.

With two arguments, `user-id` resolves to the trust level of that user.

With three arguments, the meaning depends on the first id:

* a `@user:server` value resolves device trust for `device-id`
* a `!room:server` value resolves the trust level for the device that sent
  the timeline `event-id`

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/key.clj#L100-L122)

---

## get-device-keys

```clojure
(get-device-keys client user-id)
```

Returns a Missionary flow of device keys for `user-id`.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/key.clj#L124-L128)

---

## get-cross-signing-keys

```clojure
(get-cross-signing-keys client user-id)
```

Returns a Missionary flow of cross-signing keys for `user-id`.

[source,window=_blank](https://github.com/outskirtslabs/trixnity-clj/blob/main/src/clj/ol/trixnity/key.clj#L130-L134)