@naughtbot/e2ee-payloads 0.9.0 → 0.11.0

package/src/schema.ts

@@ -45,7 +45,7 @@ export interface components {
          * @example ssh_sign
          * @enum {string}
          */
-        MailboxEnvelopeType: "link_request" | "link_approval" | "link_rejection" | "captcha_request" | "captcha_response" | "ssh_auth" | "ssh_sign" | "gpg_sign" | "gpg_decrypt" | "age_unwrap" | "pkcs11_sign" | "pkcs11_derive" | "enroll" | "browser_approval_request" | "browser_approval_response" | "first_party_request" | "first_party_response" | "signing_request" | "signing_response";
+        MailboxEnvelopeType: "link_request" | "link_approval" | "link_rejection" | "captcha_request" | "captcha_response" | "ssh_auth" | "ssh_sign" | "gpg_sign" | "gpg_decrypt" | "age_unwrap" | "pkcs11_sign" | "pkcs11_derive" | "enroll" | "browser_approval_request" | "browser_approval_response" | "first_party_request" | "first_party_response" | "signing_request" | "signing_response" | "key_inventory_request" | "key_inventory_response";
         /**
          * ApprovalChallenge
          * @description Canonical Longfellow / attested-key-zk approval challenge. Producer sends this inside the request payload; the approver binds it into the approval proof returned in the response payload.
@@ -180,6 +180,40 @@ export interface components {
          * @enum {string}
          */
         KeyPurpose: "ssh" | "gpg" | "age" | "pkcs11";
+        /**
+         * PublicKeyAlgorithm
+         * @description Closed set of public-key algorithms whose canonical byte layout is pinned by this contract. `ecdsa_p256` is a NIST P-256 (secp256r1) key, `ed25519` is an Edwards-curve Ed25519 signing key, and `x25519` is a Curve25519 Diffie-Hellman key. This enum is deliberately closed: receivers MUST reject any algorithm not listed here rather than guessing a byte layout.
+         *     This DIVERGES from `MailboxEnrollResponseApprovedV1.algorithm`, which is an open free-form string (the `enroll` flow predates the closed canonical-transport contract and stays permissive for forward compatibility). Schemas that need a verifiable canonical public key — notably the `key_inventory` surface — MUST use this closed enum so the producer and the approver cannot disagree on how to interpret `public_key_hex`. New algorithms (e.g. `rsa`) are added here only when there is a concrete implementation that needs them.
+         * @example ed25519
+         * @enum {string}
+         */
+        PublicKeyAlgorithm: "ecdsa_p256" | "ed25519" | "x25519";
+        /**
+         * PublicKeyFormat
+         * @description Closed set of byte layouts a `public_key_hex` value can carry. `sec1_compressed` is the SEC1 compressed-point encoding for P-256 (33 bytes: a `0x02`/`0x03` parity prefix followed by the 32-byte X coordinate). `raw_32` is a bare 32-byte public key, used for Ed25519 signing keys and X25519 Diffie-Hellman keys.
+         *     The format MUST be consistent with `PublicKeyAlgorithm`: `ecdsa_p256` pairs with `sec1_compressed`; `ed25519` and `x25519` pair with `raw_32`. Receivers MUST reject any other pairing. A `spki_der` layout is intentionally NOT defined yet — add it only when a future PKCS#11 RSA or generic public key actually needs it.
+         * @example raw_32
+         * @enum {string}
+         */
+        PublicKeyFormat: "sec1_compressed" | "raw_32";
+        /**
+         * Sec1CompressedPublicKeyHex
+         * @description Lowercase hex of a SEC1 compressed P-256 public key: 66 hex chars (33 bytes) whose first byte is the `0x02` or `0x03` parity prefix followed by the 32-byte X coordinate. Use this with `PublicKeyAlgorithm.ecdsa_p256` / `PublicKeyFormat.sec1_compressed`. Receivers MUST reject values whose length or prefix does not match.
+         * @example 02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
+         */
+        Sec1CompressedPublicKeyHex: string;
+        /**
+         * Raw32PublicKeyHex
+         * @description Lowercase hex of a bare 32-byte public key: exactly 64 hex chars. Use this with `PublicKeyAlgorithm.ed25519` or `PublicKeyAlgorithm.x25519` and `PublicKeyFormat.raw_32`. Receivers MUST reject values whose length does not match.
+         * @example a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
+         */
+        Raw32PublicKeyHex: string;
+        /**
+         * CanonicalPublicKeyHex
+         * @description Lowercase hex of the canonical public-key bytes. The exact layout is described by the sibling `PublicKeyAlgorithm` / `PublicKeyFormat` fields: a `sec1_compressed` P-256 key is 66 hex chars with a `02`/`03` prefix; a `raw_32` Ed25519 or X25519 key is 64 hex chars. The relaxed `^(02|03)?[0-9a-f]{64}$` pattern accepts both lengths; receivers MUST additionally reject any value whose length and prefix do not match the declared `algorithm` and `public_key_format`. Hex — never OpenAPI `format: byte` — is the canonical transport for key material; `format: byte` is reserved for opaque bytes (signatures, proofs, ciphertexts, wrapped keys, packet blobs).
+         * @example a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
+         */
+        CanonicalPublicKeyHex: string;
         /**
          * DisplayField
          * @description A single label/value row rendered on the approval surface.
@@ -1981,6 +2015,348 @@ export interface components {
             request_id: string;
             status: components["schemas"]["MailboxFirstPartyResponseStatus"];
         };
+        /**
+         * MailboxKeyInventoryRequestPayloadV1
+         * @description Request payload for the `key_inventory_request` envelope type. The paired CLI sends this to the mobile device to ask for the public-key inventory covering one or more `purposes`. The approver returns a `MailboxKeyInventoryResponsePayloadV1`.
+         */
+        MailboxKeyInventoryRequestPayloadV1: {
+            /**
+             * @description Non-empty, unique set of key purposes the requester wants the inventory for. Any subset of `ssh`, `gpg`, `age`, and `pkcs11` is valid. The approver MUST only return keys whose `purpose` is in this set, and MUST commit the exact requested set into `MailboxKeyInventoryApprovalBindingV1.requested_purposes`.
+             * @example [
+             *       "ssh",
+             *       "gpg"
+             *     ]
+             */
+            purposes: components["schemas"]["KeyPurpose"][];
+            approval_challenge?: components["schemas"]["ApprovalChallenge"];
+            display?: components["schemas"]["DisplaySchema"];
+            ui?: components["schemas"]["ApprovalUiV1"];
+            source_info?: components["schemas"]["SourceInfo"];
+        };
+        /**
+         * MailboxKeyInventoryApprovalBindingFormat
+         * @description Canonical byte format of the `MailboxKeyInventoryApprovalBindingV1` carried by a `key_inventory_response`. The `+json` suffix marks the binding as the UTF-8 JSON encoding of `MailboxKeyInventoryApprovalBindingV1` with lexicographically ordered properties and no insignificant whitespace. These bytes are the proof input the `approval_proof` statement commits to (the statement signs `SHA256(approval_binding bytes)`); they are never a signature input.
+         * @example key-inventory-approval-binding/v1+json
+         * @enum {string}
+         */
+        MailboxKeyInventoryApprovalBindingFormat: "key-inventory-approval-binding/v1+json";
+        /**
+         * MailboxKeyInventoryEntryV1
+         * @description One public key in a shared inventory response. The canonical identity of the key is the triple (`algorithm`, `public_key_format`, `public_key_hex`); every protocol-specific field below is derived export/display metadata, never the identity of the key.
+         *     This entry DIVERGES from `MailboxEnrollResponseApprovedV1`: that schema carries `algorithm` as a free-form open string and accepts both 64- and 66-hex public keys under a single relaxed pattern. This entry instead pins `algorithm` and `public_key_format` to the closed `PublicKeyAlgorithm` / `PublicKeyFormat` enums in `common.yaml` so the CLI and mobile cannot disagree on how to interpret `public_key_hex`. Receivers MUST reject an entry whose `public_key_hex` length/prefix is inconsistent with `algorithm` + `public_key_format` (a `sec1_compressed` `ecdsa_p256` key is 66 hex chars with a `02`/`03` prefix; a `raw_32` `ed25519`/`x25519` key is 64 hex chars).
+         *     Canonical key material is always lowercase hex. OpenAPI `format: byte` is used only for opaque byte blobs (GPG signature/armor packet bytes), never for key material.
+         */
+        MailboxKeyInventoryEntryV1: {
+            purpose: components["schemas"]["KeyPurpose"];
+            /**
+             * @description Stable inventory identifier for this key. UUID for GPG keys; algorithm- or provider-defined for other purposes. The CLI uses this to refer to the key in later signing/decryption requests.
+             * @example 550e8400-e29b-41d4-a716-446655440000
+             */
+            id: string;
+            /** @description Device-side key handle (e.g. iOS Secure Enclave handle) the CLI passes back as `device_key_id` on subsequent `ssh_*`, `gpg_*`, `age_unwrap`, or `pkcs11_*` requests. */
+            device_key_id: string;
+            /**
+             * @description Human-readable label for the key shown to the user.
+             * @example Work Laptop SSH Key
+             */
+            label?: string;
+            algorithm: components["schemas"]["PublicKeyAlgorithm"];
+            public_key_format: components["schemas"]["PublicKeyFormat"];
+            /**
+             * @description Lowercase hex of the canonical public-key bytes for this key. The byte layout MUST match `algorithm` + `public_key_format`: `ecdsa_p256` + `sec1_compressed` is 66 hex chars (`02`/`03` prefix); `ed25519` / `x25519` + `raw_32` is 64 hex chars. Receivers MUST reject a value whose length/prefix is inconsistent with the declared `algorithm` and `public_key_format`.
+             * @example 02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
+             */
+            public_key_hex: string;
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds when the key was created on the device. Required input for GPG V4 fingerprint reproduction; optional for other purposes.
+             * @example 1705320000
+             */
+            key_creation_timestamp?: number;
+            attestation?: components["schemas"]["KeyMetadataAttestation"];
+            ssh?: components["schemas"]["KeyInventorySshMetadataV1"];
+            gpg?: components["schemas"]["KeyInventoryGpgMetadataV1"];
+            age?: components["schemas"]["KeyInventoryAgeMetadataV1"];
+            pkcs11?: components["schemas"]["KeyInventoryPkcs11MetadataV1"];
+        };
+        /**
+         * KeyInventorySshMetadataV1
+         * @description Derived SSH export metadata for an inventory entry whose `purpose` is `ssh`. Every field is reproducible from `public_key_hex`, `algorithm`, the SSH SK key type, and the application string, so the CLI MAY recompute and cross-check it; the approver SHOULD still populate it so the CLI can write the `.pub` file without re-deriving.
+         */
+        KeyInventorySshMetadataV1: {
+            /**
+             * @description OpenSSH security-key type string. `sk-ecdsa-sha2-nistp256@openssh.com` for `ecdsa_p256` keys; `sk-ssh-ed25519@openssh.com` for `ed25519` keys.
+             * @example sk-ecdsa-sha2-nistp256@openssh.com
+             */
+            ssh_key_type?: string;
+            /**
+             * @description SSH application string baked into the public-key blob. Defaults to `ssh:` when the credential was enrolled with the default application.
+             * @default ssh:
+             * @example ssh:
+             */
+            application?: string;
+            /**
+             * @description Single-line OpenSSH authorized-keys / `.pub` representation: `<ssh_key_type> <base64(blob)> <comment>`. The blob is the SSH wire encoding of the public key (uncompressed EC point for `ecdsa_p256`) plus the application string.
+             * @example sk-ecdsa-sha2-nistp256@openssh.com AAAAInNrLWVjZHNhLXNoYTItbmlzdHAyNTZAb3BlbnNzaC5jb20= work-laptop
+             */
+            authorized_key?: string;
+            /**
+             * @description OpenSSH public-key fingerprint as `SHA256:<base64-no-padding>` of `SHA256(public-key-blob)`. The base64 uses the standard alphabet with trailing `=` padding stripped.
+             * @example SHA256:cccccccccccccccccccccccccccccccccccccccccCC
+             */
+            ssh_fingerprint?: string;
+            /**
+             * @description Per-credential SSH-SK flags byte (UP=0x01, UV=0x04) the credential was enrolled with. The CLI persists this and uses it as the request `flags` input on later `ssh_auth` / `ssh_sign` calls.
+             * @example 1
+             */
+            ssh_sk_flags?: number;
+        };
+        /**
+         * KeyInventoryGpgMetadataV1
+         * @description Derived GPG export metadata for an inventory entry whose `purpose` is `gpg`. The primary-key fingerprint is the OpenPGP V4 fingerprint (`SHA1` over the V4 public-key packet) and depends on `key_creation_timestamp`, so that field MUST be present on GPG entries. `armored_public_key` lets the CLI import the key into system GPG without rebuilding the packet stream.
+         */
+        KeyInventoryGpgMetadataV1: {
+            /**
+             * @description Uppercase hex of the 20-byte OpenPGP V4 primary-key fingerprint (40 hex chars), no spaces.
+             * @example A1D597197F5C1DACB3E3BB7862BF2FC536D562FF
+             */
+            fingerprint_hex?: string;
+            /**
+             * @description Display-formatted primary-key fingerprint: the 40 hex chars in uppercase, grouped into ten 4-character blocks separated by single spaces. Display only — `fingerprint_hex` is canonical.
+             * @example A1D5 9719 7F5C 1DAC B3E3 BB78 62BF 2FC5 36D5 62FF
+             */
+            formatted_fingerprint?: string;
+            /**
+             * @description Uppercase hex of the 8-byte OpenPGP key id (16 hex chars), the low 64 bits of `fingerprint_hex`.
+             * @example 62BF2FC536D562FF
+             */
+            key_id?: string;
+            /**
+             * @description ASCII-armored OpenPGP public key block (`-----BEGIN PGP PUBLIC KEY BLOCK-----` … `-----END …-----`), including the primary key, user id, self-certification signature, and — when present — the encryption subkey and its binding signature.
+             * @example -----BEGIN PGP PUBLIC KEY BLOCK-----
+             *
+             *     mDMEY...
+             *     -----END PGP PUBLIC KEY BLOCK-----
+             */
+            armored_public_key?: string;
+            /**
+             * Format: byte
+             * @description RFC 4648 standard base64 with `=` padding for the raw OpenPGP self-certification (user-id) signature packet bytes.
+             */
+            user_id_signature?: string;
+            /**
+             * Format: byte
+             * @description RFC 4648 standard base64 with `=` padding for the raw OpenPGP subkey binding signature packet bytes, when an encryption subkey is present.
+             */
+            subkey_signature?: string;
+            /**
+             * @description Lowercase hex of the ECDH encryption subkey public key, SEC1 compressed P-256 (66 hex chars). Present only when the GPG key has an encryption subkey.
+             * @example 03b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3
+             */
+            encryption_public_key_hex?: string;
+            /**
+             * @description Uppercase hex of the 20-byte OpenPGP V4 fingerprint of the ECDH encryption subkey (40 hex chars).
+             * @example B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0C1
+             */
+            encryption_fingerprint_hex?: string;
+            /**
+             * @description Uppercase hex of the 8-byte OpenPGP key id of the ECDH encryption subkey (16 hex chars).
+             * @example B4C5D6E7F8A9B0C1
+             */
+            encryption_key_id?: string;
+        };
+        /**
+         * KeyInventoryAgeMetadataV1
+         * @description Derived age export metadata for an inventory entry whose `purpose` is `age`. The underlying key is an X25519 key (`algorithm: x25519`, `public_key_format: raw_32`).
+         */
+        KeyInventoryAgeMetadataV1: {
+            /**
+             * @description Canonical age recipient string. It is the Bech32 encoding (per the age spec, lowercase, with the standard age Bech32 checksum) of the 32 raw X25519 public-key bytes — the same bytes as `public_key_hex` — under the human-readable prefix `age1nb`. Producers MUST emit the recipient with this exact prefix and Bech32 checksum; the CLI MUST reject a recipient that does not Bech32-decode to the entry's `public_key_hex` bytes. (The legacy CLI shipped two divergent helpers — a Go Bech32 encoder and a Swift `age1ackagent` + raw-hex concatenation; neither is the contract here. This schema field and the cross-language vectors are authoritative.)
+             * @example age1nb1qqqsyqcyq5rqwzqfpg9scrgwpugpzysnzs23v9ccrydpk8qarc0pz5
+             */
+            age_recipient?: string;
+            /**
+             * @description Short display fingerprint for the age key. Display only — not a cryptographic identifier; the canonical identity is `public_key_hex`.
+             * @example age:YWdlLXJlY2lwaWVu
+             */
+            age_fingerprint?: string;
+        };
+        /**
+         * KeyInventoryPkcs11MetadataV1
+         * @description Derived PKCS#11 public-object metadata for an inventory entry whose `purpose` is `pkcs11`. These are the attributes a PKCS#11 provider needs to expose the public key as a `CKO_PUBLIC_KEY` object deterministically. The canonical identity of the key remains `public_key_hex`; `cka_ec_point_hex` is the DER-wrapped restatement of the same key for the `CKA_EC_POINT` attribute.
+         */
+        KeyInventoryPkcs11MetadataV1: {
+            /**
+             * @description Lowercase hex of the `CKA_ID` attribute bytes used to correlate the public object with its private counterpart.
+             * @example a1b2c3d4
+             */
+            cka_id_hex?: string;
+            /**
+             * @description UTF-8 `CKA_LABEL` attribute string for the public object.
+             * @example NaughtBot PKCS#11 Key
+             */
+            cka_label?: string;
+            /**
+             * @description PKCS#11 `CKA_KEY_TYPE` name for the key. `CKK_EC` for P-256 keys; `CKK_EC_EDWARDS` for Ed25519 keys.
+             * @example CKK_EC
+             */
+            cka_key_type?: string;
+            /**
+             * @description Lowercase hex of the DER-encoded `CKA_EC_PARAMS` attribute (the named-curve OID, e.g. `prime256v1` for P-256).
+             * @example 06082a8648ce3d030107
+             */
+            cka_ec_params_hex?: string;
+            /**
+             * @description Lowercase hex of the DER-encoded `CKA_EC_POINT` attribute (an ASN.1 `OCTET STRING` wrapping the EC point). This is the same public key as `public_key_hex`, re-encoded for the PKCS#11 attribute; receivers MUST treat `public_key_hex` as canonical if the two ever disagree.
+             * @example 0441a1b2c3d4
+             */
+            cka_ec_point_hex?: string;
+            /**
+             * @description Whether the key's PKCS#11 object exposes the `CKA_SIGN` / `CKA_VERIFY` capability (signing keys).
+             * @example true
+             */
+            can_sign?: boolean;
+            /**
+             * @description Whether the key's PKCS#11 object exposes the `CKA_DERIVE` capability (ECDH key-agreement keys).
+             * @example false
+             */
+            can_derive?: boolean;
+        };
+        /**
+         * MailboxKeyInventoryResponseSharedV1
+         * @description `shared` branch of `MailboxKeyInventoryResponsePayloadV1`. The mobile user approved the request; this branch carries the approved key list plus the attested-key-zk proof the CLI uses to verify it.
+         *     Integrity is carried entirely by `approval_proof`. The device approval signing key is NEVER transmitted: no signing-key identity and no raw signature appears on the wire. Verification is by the `attested-key-zk` proof alone, which verifies the approval WITHOUT revealing the device signing key — exactly as the `captcha` flow does.
+         *     Verification rule the CLI MUST apply:
+         *       1. Recompute `key_list_digest` over `keys` exactly as
+         *          `MailboxKeyInventoryApprovalBindingV1.key_list_digest` documents
+         *          and confirm it matches `approval_binding.key_list_digest`.
+         *       2. Re-encode `approval_binding` to its canonical JSON bytes (see
+         *          `MailboxKeyInventoryApprovalBindingV1`) and confirm those bytes
+         *          equal `approval_binding_bytes` after base64-decoding.
+         *       3. Verify `approval_proof` (attested-key-zk) over
+         *          `SHA256(approval_binding bytes)`: confirm
+         *          `approval_proof.statement.approval_hash_hex` is the lowercase hex
+         *          SHA-256 of the canonical `approval_binding` bytes, then verify the
+         *          zero-knowledge proof against current issuer keys. Because the
+         *          binding commits to the request id/type, requested purposes,
+         *          response status, requester source info, response timestamp, and
+         *          `key_list_digest`, a valid proof binds this exact request and key
+         *          list to an attested NaughtBot install that approved it.
+         *     There is no signature-verification step. A response that fails any step MUST be treated as not approved.
+         */
+        MailboxKeyInventoryResponseSharedV1: {
+            /**
+             * @description Outcome discriminator (`shared`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            status: "shared";
+            /**
+             * Format: uuid
+             * @description Envelope id of the `key_inventory_request` being answered. MUST equal `approval_binding.request_envelope_id`.
+             * @example 11111111-2222-4333-8444-555555555555
+             */
+            request_envelope_id: string;
+            /** @description Approved public-key inventory. MAY be empty when the device holds no keys for the requested purposes. Every entry's `purpose` MUST be in the request's `purposes` set. */
+            keys: components["schemas"]["MailboxKeyInventoryEntryV1"][];
+            approval_binding: components["schemas"]["MailboxKeyInventoryApprovalBindingV1"];
+            /**
+             * Format: byte
+             * @description RFC 4648 standard base64 with `=` padding for the canonical `MailboxKeyInventoryApprovalBindingV1` UTF-8 JSON bytes. These are the proof input: `approval_proof.statement.approval_hash_hex` is `SHA256` of these bytes (after base64 decoding). They are never a signature input.
+             */
+            approval_binding_bytes: string;
+            approval_binding_format: components["schemas"]["MailboxKeyInventoryApprovalBindingFormat"];
+            approval_proof: components["schemas"]["ApprovalAttestedKeyProof"];
+        };
+        /**
+         * MailboxKeyInventoryResponseRejectedV1
+         * @description `rejected` branch of `MailboxKeyInventoryResponsePayloadV1`. The request was declined by the user or could not be satisfied. Carries the signing error code and an optional human-readable message; it never carries key material or an approval binding.
+         */
+        MailboxKeyInventoryResponseRejectedV1: {
+            /**
+             * @description Outcome discriminator (`rejected`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            status: "rejected";
+            /**
+             * Format: uuid
+             * @description Envelope id of the `key_inventory_request` being answered.
+             * @example 11111111-2222-4333-8444-555555555555
+             */
+            request_envelope_id: string;
+            error_code: components["schemas"]["SigningErrorCode"];
+            /**
+             * @description Human-readable error message.
+             * @example User rejected the key inventory request
+             */
+            error_message?: string;
+        };
+        /**
+         * MailboxKeyInventoryResponsePayloadV1
+         * @description Response payload for the `key_inventory_response` envelope type. Discriminated on `status`: `shared` carries the approved key list, approval binding, and attested-key-zk approval proof; `rejected` carries only an error code.
+         *     Go generator caveat (see repo `AGENTS.md`): the generated `AsMailboxKeyInventoryResponseSharedV1()` helper is permissive and will not error on a `rejected`-shaped JSON. Routing call-sites MUST inspect the union with `Discriminator()` before treating the result as `shared`.
+         */
+        MailboxKeyInventoryResponsePayloadV1: components["schemas"]["MailboxKeyInventoryResponseSharedV1"] | components["schemas"]["MailboxKeyInventoryResponseRejectedV1"];
+        /**
+         * MailboxKeyInventoryApprovalBindingV1
+         * @description Canonical JSON object whose UTF-8 bytes are the input to the attested-key-zk `approval_proof` for a shared key-inventory response. Producers encode these fields with lexicographically ordered properties and no insignificant whitespace and place the resulting bytes in `MailboxKeyInventoryResponseSharedV1.approval_binding_bytes`.
+         *     Integrity mechanism: `MailboxKeyInventoryResponseSharedV1.approval_proof` is an attested-key-zk proof whose statement signs `SHA256(approval_binding bytes)` — exactly as the `captcha` flow signs `SHA256(NaughtBotApprovalBindingV1 bytes)`. The proof verifies that the approval decision (this exact request, answered `shared`, returning this exact key list) was made by an attested NaughtBot install, WITHOUT revealing the device signing key. The device approval signing key is never transmitted and never named here: it is seen only by the core auth service, which uses it to issue the ZK attestation credential. There is no signature over these bytes.
+         *     `key_list_digest` commits to the full shared key list — canonical key material AND every protocol export field the CLI persists or displays — so the mobile user cannot approve one set of keys while the CLI stores a different exported representation. It is `sha256:<hex>` where `<hex>` is the lowercase hex SHA-256 of the UTF-8 JSON array `MailboxKeyInventoryResponseSharedV1.keys` encoded in the same canonical form (each `MailboxKeyInventoryEntryV1` object with lexicographically ordered properties, omitted optional fields absent, no insignificant whitespace). Recomputing the digest over the delivered `keys` array MUST reproduce this value.
+         */
+        MailboxKeyInventoryApprovalBindingV1: {
+            /**
+             * @description Canonical approval binding schema version.
+             * @enum {string}
+             */
+            version: "key-inventory-approval-binding/v1";
+            /**
+             * Format: uuid
+             * @description Envelope id of the `key_inventory_request` being answered. Copied from `MailboxEnvelopeV1.id` of the request.
+             * @example 11111111-2222-4333-8444-555555555555
+             */
+            request_envelope_id: string;
+            /**
+             * @description `MailboxEnvelopeV1.issued_at` of the request being answered, preserved as the literal RFC 3339 UTC string.
+             * @example 2026-05-21T17:30:00Z
+             */
+            request_envelope_issued_at: string;
+            /**
+             * @description Envelope type of the request being answered.
+             * @example key_inventory_request
+             * @enum {string}
+             */
+            request_envelope_type: "key_inventory_request";
+            /**
+             * @description Exact `purposes` set copied from the request payload. Pins which purposes the mobile user agreed to share so the CLI can reject a response whose scope drifted from the request.
+             * @example [
+             *       "ssh",
+             *       "gpg"
+             *     ]
+             */
+            requested_purposes: components["schemas"]["KeyPurpose"][];
+            /**
+             * @description Response outcome committed by this binding. Always `shared`: this binding only exists on the shared response branch.
+             * @example shared
+             * @enum {string}
+             */
+            response_status: "shared";
+            /**
+             * @description `sha256:<hex>` digest committing to the full shared key list, including canonical key material and protocol export metadata. See the schema description for the exact canonicalization. An approved response with no keys (the device holds none for the requested purposes) commits to the digest of the empty JSON array `[]`, `sha256:4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945`.
+             * @example sha256:70f1e52bd01429bc2f405b182a3abc72751bda213dba41684a12db5116698c3c
+             */
+            key_list_digest: string;
+            /**
+             * Format: uuid
+             * @description Opaque identifier of the device that approved this request, for display and audit. It is NOT key material — no device signing-key identity travels on the wire. The cryptographic binding of the approval to an attested device is carried solely by `MailboxKeyInventoryResponseSharedV1.approval_proof`.
+             * @example 33333333-4444-4555-8666-777777777777
+             */
+            approving_device_id: string;
+            /**
+             * @description RFC 3339 UTC timestamp when mobile produced the response.
+             * @example 2026-05-21T17:31:00Z
+             */
+            responded_at: string;
+            requester_source_info?: components["schemas"]["SourceInfo"];
+        };
     };
     responses: never;
     parameters: never;