@naughtbot/e2ee-payloads 0.3.1 → 0.5.0

package/src/schema.ts

@@ -43,7 +43,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";
+        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";
         /**
          * 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.
@@ -181,6 +181,7 @@ export interface components {
         /**
          * DisplayField
          * @description A single label/value row rendered on the approval surface.
+         *     Superseded by the declarative `ApprovalUiV1` schema in `approval_ui.yaml` (`ApprovalUiKeyValueRow` is the direct replacement). Retained only for producers that have not yet migrated to the `ui` field; scheduled for removal in a follow-up once every producer and approver sends and renders `ApprovalUiV1`.
          */
         DisplayField: {
             /**
@@ -219,6 +220,7 @@ export interface components {
         /**
          * DisplaySchema
          * @description Optional approval-UI metadata. Producers populate this on a best-effort basis; approvers MUST render the wire payload regardless of presence.
+         *     Superseded by the declarative `ApprovalUiV1` schema in `approval_ui.yaml`, exposed as the `ui` field on every request payload. Retained only for producers that have not yet migrated; scheduled for removal in a follow-up once every producer and approver sends and renders `ApprovalUiV1`.
          */
         DisplaySchema: {
             /**
@@ -265,6 +267,264 @@ export interface components {
             /** @description Full process tree from the current process up to init. */
             process_chain?: components["schemas"]["ProcessEntry"][];
         };
+        /**
+         * ApprovalUiV1
+         * @description Declarative approval-UI container. `blocks` is a flat, ordered list rendered top to bottom. The approver renders this content above its own mandatory security chrome and signing controls; nothing here can suppress, reorder, or replace that chrome. Renderers MUST skip (not reject) any block whose `type` is not recognised so that newer producers stay forward-compatible with older approvers. Producers populate this on a best-effort basis; approvers MUST still render a safe default screen when it is absent or empty.
+         */
+        ApprovalUiV1: {
+            /**
+             * @description Canonical declarative approval-UI format version. Renderers reject unknown values.
+             * @enum {string}
+             */
+            schema: "approval-ui/v1";
+            /** @description Ordered list of content blocks. An empty list is valid and renders as no requester-supplied content. */
+            blocks: components["schemas"]["ApprovalUiBlock"][];
+        };
+        /**
+         * ApprovalUiBlock
+         * @description One content block in an `ApprovalUiV1.blocks` list. Discriminated on `type`. Renderers MUST skip blocks whose `type` is not recognised rather than rejecting the whole payload.
+         */
+        ApprovalUiBlock: components["schemas"]["ApprovalUiHeadingBlock"] | components["schemas"]["ApprovalUiTextBlock"] | components["schemas"]["ApprovalUiKeyValuesBlock"] | components["schemas"]["ApprovalUiCalloutBlock"] | components["schemas"]["ApprovalUiBadgeBlock"] | components["schemas"]["ApprovalUiDividerBlock"] | components["schemas"]["ApprovalUiImageBlock"] | components["schemas"]["ApprovalUiSignedDataBlock"];
+        /**
+         * ApprovalUiProvenance
+         * @description Trust origin of a block's content. Renderers MAY group or badge blocks by provenance so the approver can tell requester-asserted content from device-derived content. `requester` is content the relying party / CLI asserted, `relay` is content the relay added, `device` is content the approving device derived locally, and `backend` is content a first-party NaughtBot backend asserted.
+         * @example requester
+         * @enum {string}
+         */
+        ApprovalUiProvenance: "requester" | "relay" | "device" | "backend";
+        /**
+         * ApprovalUiHeadingBlock
+         * @description A short heading rendered as a section title. `level` is visual weight only and carries no document-outline semantics.
+         */
+        ApprovalUiHeadingBlock: {
+            /**
+             * @description Block discriminator (`heading`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            type: "heading";
+            provenance: components["schemas"]["ApprovalUiProvenance"];
+            /**
+             * @description Heading text.
+             * @example Sign Git Commit
+             */
+            text: string;
+            /**
+             * @description Visual weight of the heading (`1` strongest). Not a document outline level; renderers map it to a font size only.
+             * @default 1
+             * @enum {integer}
+             */
+            level?: 1 | 2;
+        };
+        /**
+         * ApprovalUiTextBlock
+         * @description A paragraph of plain, non-interactive body text.
+         */
+        ApprovalUiTextBlock: {
+            /**
+             * @description Block discriminator (`text`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            type: "text";
+            provenance: components["schemas"]["ApprovalUiProvenance"];
+            /**
+             * @description Body text. Rendered as plain text; no markup is interpreted.
+             * @example This will create a signed commit on the main branch.
+             */
+            text: string;
+            /**
+             * @description Visual emphasis. `secondary` renders as de-emphasised supporting text.
+             * @default normal
+             * @enum {string}
+             */
+            style?: "normal" | "secondary";
+        };
+        /**
+         * ApprovalUiKeyValuesBlock
+         * @description A labelled table of label/value rows, e.g. request metadata the approver should review before approving.
+         */
+        ApprovalUiKeyValuesBlock: {
+            /**
+             * @description Block discriminator (`key_values`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            type: "key_values";
+            provenance: components["schemas"]["ApprovalUiProvenance"];
+            /**
+             * @description Optional title rendered above the rows.
+             * @example Request details
+             */
+            title?: string;
+            /** @description Ordered label/value rows. */
+            rows: components["schemas"]["ApprovalUiKeyValueRow"][];
+        };
+        /**
+         * ApprovalUiKeyValueRow
+         * @description A single label/value row inside an `ApprovalUiKeyValuesBlock`.
+         */
+        ApprovalUiKeyValueRow: {
+            /**
+             * @description Short row label.
+             * @example Repository
+             */
+            label: string;
+            /**
+             * @description Row value. Rendered as plain text; no markup is interpreted.
+             * @example github.com/user/repo
+             */
+            value: string;
+            /**
+             * @description Render the value in a monospace font.
+             * @default false
+             */
+            monospace?: boolean;
+            /**
+             * @description Value may be collapsed by default and expanded on demand.
+             * @default false
+             */
+            expandable?: boolean;
+            /**
+             * @description Render the value across multiple lines.
+             * @default false
+             */
+            multiline?: boolean;
+            /**
+             * @description Value is sensitive; the renderer MAY mask it until revealed.
+             * @default false
+             */
+            sensitive?: boolean;
+            /**
+             * @description Optional lookup name into the approver's curated icon set. MUST NOT be a URL or file path; renderers ignore unknown names.
+             * @example lock
+             */
+            icon?: string;
+        };
+        /**
+         * ApprovalUiCalloutBlock
+         * @description A highlighted callout box used to draw attention to a single message, e.g. a warning about the request.
+         */
+        ApprovalUiCalloutBlock: {
+            /**
+             * @description Block discriminator (`callout`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            type: "callout";
+            provenance: components["schemas"]["ApprovalUiProvenance"];
+            /**
+             * @description Visual severity of the callout. The renderer maps this to a fixed colour treatment; it carries no executable meaning.
+             * @enum {string}
+             */
+            severity: "info" | "success" | "warning" | "danger";
+            /**
+             * @description Optional callout title.
+             * @example Unrecognised host
+             */
+            title?: string;
+            /**
+             * @description Callout body text. Rendered as plain text.
+             * @example This request came from a host you have not approved before.
+             */
+            text: string;
+        };
+        /**
+         * ApprovalUiBadgeBlock
+         * @description A small inline pill / tag used to label a status or category.
+         */
+        ApprovalUiBadgeBlock: {
+            /**
+             * @description Block discriminator (`badge`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            type: "badge";
+            provenance: components["schemas"]["ApprovalUiProvenance"];
+            /**
+             * @description Badge label.
+             * @example Production
+             */
+            text: string;
+            /**
+             * @description Visual tone of the badge. The renderer maps this to a fixed colour treatment.
+             * @default neutral
+             * @enum {string}
+             */
+            tone?: "neutral" | "info" | "success" | "warning" | "danger";
+        };
+        /**
+         * ApprovalUiDividerBlock
+         * @description A horizontal rule used to visually separate groups of blocks.
+         */
+        ApprovalUiDividerBlock: {
+            /**
+             * @description Block discriminator (`divider`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            type: "divider";
+            provenance: components["schemas"]["ApprovalUiProvenance"];
+        };
+        /**
+         * ApprovalUiImageBlock
+         * @description An embedded raster image rendered inline. The image bytes are carried in `data`; the schema never references an external URL or file path so the approver never makes a network request to render the screen. Deferred: the schema is published now, but the mobile renderer adds image support in a later phase. Renderers that do not yet support images MUST skip this block per the `ApprovalUiBlock` skip-unknown rule.
+         */
+        ApprovalUiImageBlock: {
+            /**
+             * @description Block discriminator (`image`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            type: "image";
+            provenance: components["schemas"]["ApprovalUiProvenance"];
+            /**
+             * @description Pixel format of the embedded image bytes.
+             * @enum {string}
+             */
+            format: "png";
+            /**
+             * Format: byte
+             * @description RFC 4648 standard base64 with `=` padding for the raw image bytes. Embedded inline only; never a URL or file path.
+             */
+            data: string;
+            /**
+             * @description Optional accessibility description of the image.
+             * @example Repository avatar
+             */
+            alt_text?: string;
+            /**
+             * @description Maximum rendered height in layout points. The renderer scales the image down to fit and never scales it up past its native size.
+             * @default 120
+             */
+            max_height_points?: number;
+        };
+        /**
+         * ApprovalUiSignedDataBlock
+         * @description A read-only presentation of the exact bytes the approver is about to sign. This block carries NO content field of its own: the renderer derives the displayed bytes from the request payload's own preimage field (e.g. `signed_payload` / `raw_data`) and renders them in the selected `encoding`. This keeps the signed bytes single-sourced — a requester cannot show the approver one thing here and sign another. Because the content is device-derived, `provenance` MUST be `device`.
+         */
+        ApprovalUiSignedDataBlock: {
+            /**
+             * @description Block discriminator (`signed_data`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            type: "signed_data";
+            /**
+             * @description Always `device`: the displayed bytes are derived locally from the request preimage, never asserted by the requester. Constrained to the single `device` value in-schema (rather than the shared `ApprovalUiProvenance` enum) so a requester cannot mislabel the trust origin of signed bytes.
+             * @enum {string}
+             */
+            provenance: "device";
+            encoding: components["schemas"]["ApprovalUiSignedDataEncoding"];
+            /**
+             * @description Label rendered above the signed-data presentation.
+             * @default To be signed
+             */
+            label?: string;
+            /** @description Encodings the renderer MAY offer the approver to switch between. When present it SHOULD include `encoding`. */
+            available_encodings?: components["schemas"]["ApprovalUiSignedDataEncoding"][];
+            /** @description Optional caption rendered below the signed-data presentation. */
+            caption?: string;
+        };
+        /**
+         * ApprovalUiSignedDataEncoding
+         * @description How the signed bytes are rendered for review. `hex` and `base64` render the raw bytes, `utf8` decodes them as text, and `sha256` renders the lowercase hex SHA-256 digest of the bytes.
+         * @example hex
+         * @enum {string}
+         */
+        ApprovalUiSignedDataEncoding: "hex" | "base64" | "utf8" | "sha256";
         /**
          * MailboxSshAuthRequestPayloadV1
          * @description Request payload for the `ssh_auth` envelope type. The approver signs an SSH user-authentication challenge constructed from `raw_data`, using the on-device key selected by `device_key_id`.
@@ -297,6 +557,7 @@ export interface components {
             device_key_id: string;
             approval_challenge?: components["schemas"]["ApprovalChallenge"];
             display?: components["schemas"]["DisplaySchema"];
+            ui?: components["schemas"]["ApprovalUiV1"];
             source_info?: components["schemas"]["SourceInfo"];
         };
         /**
@@ -371,6 +632,7 @@ export interface components {
             device_key_id: string;
             approval_challenge?: components["schemas"]["ApprovalChallenge"];
             display?: components["schemas"]["DisplaySchema"];
+            ui?: components["schemas"]["ApprovalUiV1"];
             source_info?: components["schemas"]["SourceInfo"];
         };
         /**
@@ -431,6 +693,7 @@ export interface components {
             device_key_id: string;
             approval_challenge?: components["schemas"]["ApprovalChallenge"];
             display?: components["schemas"]["DisplaySchema"];
+            ui?: components["schemas"]["ApprovalUiV1"];
             source_info?: components["schemas"]["SourceInfo"];
         };
         /**
@@ -481,6 +744,7 @@ export interface components {
             device_key_id: string;
             approval_challenge?: components["schemas"]["ApprovalChallenge"];
             display?: components["schemas"]["DisplaySchema"];
+            ui?: components["schemas"]["ApprovalUiV1"];
             source_info?: components["schemas"]["SourceInfo"];
         };
         /**
@@ -578,6 +842,7 @@ export interface components {
             recipient_public_hex: string;
             approval_challenge?: components["schemas"]["ApprovalChallenge"];
             display?: components["schemas"]["DisplaySchema"];
+            ui?: components["schemas"]["ApprovalUiV1"];
             source_info?: components["schemas"]["SourceInfo"];
         };
         /**
@@ -624,6 +889,7 @@ export interface components {
             /** @description Hex-encoded public key selecting which on-device key the approver should use for signing. */
             device_key_id: string;
             display?: components["schemas"]["DisplaySchema"];
+            ui?: components["schemas"]["ApprovalUiV1"];
             approval_challenge?: components["schemas"]["ApprovalChallenge"];
             source_info?: components["schemas"]["SourceInfo"];
         };
@@ -671,6 +937,7 @@ export interface components {
             kdf?: components["schemas"]["Pkcs11DeriveKdfParams"];
             approval_challenge?: components["schemas"]["ApprovalChallenge"];
             display?: components["schemas"]["DisplaySchema"];
+            ui?: components["schemas"]["ApprovalUiV1"];
             source_info?: components["schemas"]["SourceInfo"];
         };
         /**
@@ -748,6 +1015,7 @@ export interface components {
             include_certification?: boolean;
             approval_challenge?: components["schemas"]["ApprovalChallenge"];
             display?: components["schemas"]["DisplaySchema"];
+            ui?: components["schemas"]["ApprovalUiV1"];
             source_info?: components["schemas"]["SourceInfo"];
         };
         /**
@@ -826,6 +1094,86 @@ export interface components {
              */
             error_message?: string;
         };
+        /**
+         * MailboxSigningRequestPayloadV1
+         * @description Request payload for the `signing_request` envelope type. The approver signs `signed_payload` exactly as supplied with the on-device key selected by `device_key_id`; there is no protocol-specific preimage wrapping. When `approval_challenge` is present its `plaintext_hash` MUST equal `sha256:<lowercase hex of signed_payload after base64 decoding>` so the approval proof is bound to the exact signed bytes.
+         */
+        MailboxSigningRequestPayloadV1: {
+            /**
+             * Format: byte
+             * @description RFC 4648 standard base64 with `=` padding for the exact preimage bytes the approver signs. The decoded payload is capped at 1 MiB (1048576 bytes); `maxLength` is the matching base64-string ceiling.
+             * @example ZGF0YSB0byBzaWdu
+             */
+            signed_payload: string;
+            /**
+             * @description Signature algorithm the approver MUST use. `ecdsa-p256-sha256` signs the SHA-256 digest of `signed_payload`; `ed25519` signs the payload bytes directly.
+             * @example ed25519
+             * @enum {string}
+             */
+            signing_algorithm: "ed25519" | "ecdsa-p256-sha256";
+            /** @description Device-side key identifier (e.g. iOS Secure Enclave handle) used to select among enrolled signing keys on the approver. */
+            device_key_id: string;
+            /**
+             * @description When true, `signed_payload` is already the digest to sign and the approver MUST NOT hash it again. Only meaningful for algorithms that sign a digest (e.g. `ecdsa-p256-sha256`); ignored for `ed25519`.
+             * @default false
+             */
+            digest_prehashed?: boolean;
+            /**
+             * @description Optional short human-readable label describing what the signature is for. Display only; not bound into the signature.
+             * @example Release manifest
+             */
+            purpose_label?: string;
+            ui?: components["schemas"]["ApprovalUiV1"];
+            approval_challenge?: components["schemas"]["ApprovalChallenge"];
+            source_info?: components["schemas"]["SourceInfo"];
+        };
+        /**
+         * MailboxSigningResponsePayloadV1
+         * @description Response payload for the `signing_response` envelope type. Discriminated on `result`: `signed` carries the signature; `failed` carries a signing error code.
+         */
+        MailboxSigningResponsePayloadV1: components["schemas"]["MailboxSigningResponseSignedV1"] | components["schemas"]["MailboxSigningResponseFailedV1"];
+        /**
+         * MailboxSigningResponseSignedV1
+         * @description Signed branch of `MailboxSigningResponsePayloadV1`. Carries the raw signature over the request `signed_payload` and echoes the algorithm the approver actually used.
+         */
+        MailboxSigningResponseSignedV1: {
+            /**
+             * @description Signing outcome discriminator (`signed`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            result: "signed";
+            /**
+             * Format: byte
+             * @description RFC 4648 standard base64 with `=` padding for the raw signature bytes (no protocol framing).
+             */
+            signature: string;
+            /**
+             * @description Signature algorithm the approver used. Echoes the request `signing_algorithm`.
+             * @example ed25519
+             * @enum {string}
+             */
+            signing_algorithm: "ed25519" | "ecdsa-p256-sha256";
+            /** @description Optional lowercase hex-encoded public key the signature verifies against (64 hex chars for an Ed25519 32-byte key, or 66 hex chars for a P-256 33-byte compressed key). */
+            public_key_hex?: string;
+            approval_proof?: components["schemas"]["ApprovalAttestedKeyProof"];
+        };
+        /**
+         * MailboxSigningResponseFailedV1
+         * @description Failed branch of `MailboxSigningResponsePayloadV1`. Carries the signing error code and an optional human-readable message.
+         */
+        MailboxSigningResponseFailedV1: {
+            /**
+             * @description Signing outcome discriminator (`failed`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            result: "failed";
+            error_code: components["schemas"]["SigningErrorCode"];
+            /**
+             * @description Human-readable error message.
+             * @example User rejected the request
+             */
+            error_message?: string;
+        };
         /**
          * MailboxBrowserApprovalDecision
          * @description Mobile user's signed approval decision.
@@ -1031,6 +1379,374 @@ export interface components {
             request_envelope_id: string;
             status: components["schemas"]["MailboxBrowserApprovalResponseStatus"];
         };
+        /**
+         * MailboxFirstPartyRequestKind
+         * @description First-party request category delivered to a user's devices.
+         * @example privileged_action_approval
+         * @enum {string}
+         */
+        MailboxFirstPartyRequestKind: "privileged_action_approval";
+        /**
+         * MailboxFirstPartyPrivilegedActionType
+         * @description Privileged server-side action that requires mobile approval.
+         * @example relying_party.register
+         * @enum {string}
+         */
+        MailboxFirstPartyPrivilegedActionType: "relying_party.register" | "relying_party.rotate_secret" | "device.revoke_other";
+        /**
+         * MailboxFirstPartyApprovalDecision
+         * @description Mobile user's signed decision for a first-party request.
+         * @example approved
+         * @enum {string}
+         */
+        MailboxFirstPartyApprovalDecision: "approved" | "denied";
+        /**
+         * MailboxFirstPartyResponseStatus
+         * @description Response lifecycle status. The signed `decision` carries the approval outcome.
+         * @example decided
+         * @enum {string}
+         */
+        MailboxFirstPartyResponseStatus: "decided";
+        /**
+         * MailboxFirstPartyApprovalBindingFormat
+         * @description Canonical byte format signed by the approving device key.
+         * @example first-party-privileged-action-decision-binding/v1+json
+         * @enum {string}
+         */
+        MailboxFirstPartyApprovalBindingFormat: "first-party-privileged-action-decision-binding/v1+json";
+        /**
+         * MailboxFirstPartyRelyingPartyRegisterActionV1
+         * @description Canonical action details for `relying_party.register`. Mobile displays these exact fields before approving creation of the relying party and its paired public/confidential clients.
+         */
+        MailboxFirstPartyRelyingPartyRegisterActionV1: {
+            /**
+             * @description Discriminator for this privileged action payload.
+             * @enum {string}
+             */
+            action_type: "relying_party.register";
+            /**
+             * @description Whether approval returns a one-time plaintext client secret to the initiating console flow.
+             * @example true
+             */
+            client_secret_returned_once: boolean;
+            /**
+             * @description OAuth resource audience requested for confidential client credentials.
+             * @example verify.api
+             */
+            confidential_client_audience: string;
+            /**
+             * @description Requested scopes for the confidential backend client.
+             * @example [
+             *       "verify:proof"
+             *     ]
+             */
+            confidential_client_scopes: string[];
+            /**
+             * @description Human-readable relying-party label shown to the user.
+             * @example Customer Portal
+             */
+            display_name: string;
+            /**
+             * Format: uri
+             * @description Browser origin that will host the public relying-party client.
+             * @example https://customer.example
+             */
+            origin: string;
+            /**
+             * @description Requested scopes for the public browser Sign in client.
+             * @example [
+             *       "openid",
+             *       "offline_access",
+             *       "mailbox:pairing:start"
+             *     ]
+             */
+            public_client_scopes: string[];
+            /**
+             * @description Exact browser callback URIs for the public authorization-code client.
+             * @example [
+             *       "https://customer.example/oauth/callback"
+             *     ]
+             */
+            redirect_uris: string[];
+        };
+        /**
+         * MailboxFirstPartyRelyingPartyRotateSecretActionV1
+         * @description Canonical action details for `relying_party.rotate_secret`. Approval authorizes replacing the confidential client's stored secret hash and returning the new secret once to the initiating console flow.
+         */
+        MailboxFirstPartyRelyingPartyRotateSecretActionV1: {
+            /**
+             * @description Discriminator for this privileged action payload.
+             * @enum {string}
+             */
+            action_type: "relying_party.rotate_secret";
+            /**
+             * @description Whether approval returns a one-time plaintext client secret to the initiating console flow.
+             * @example true
+             */
+            client_secret_returned_once: boolean;
+            /**
+             * @description Confidential backend client id whose secret will rotate.
+             * @example rp_conf_9d58fb4c6ff84f46
+             */
+            confidential_client_id: string;
+            /**
+             * @description Human-readable relying-party label shown to the user.
+             * @example Customer Portal
+             */
+            display_name: string;
+            /**
+             * Format: uri
+             * @description Browser origin attached to the relying party.
+             * @example https://customer.example
+             */
+            origin: string;
+            /**
+             * @description Relying-party record id whose confidential secret will rotate.
+             * @example rp_2af7b1fb2b5b4b5b8
+             */
+            relying_party_id: string;
+        };
+        /**
+         * MailboxFirstPartyDeviceRevokeOtherActionV1
+         * @description Canonical action details for `device.revoke_other`. Approval authorizes revoking another active device on the same user account.
+         */
+        MailboxFirstPartyDeviceRevokeOtherActionV1: {
+            /**
+             * @description Discriminator for this privileged action payload.
+             * @enum {string}
+             */
+            action_type: "device.revoke_other";
+            /**
+             * @description Whether approval cascades revocation to pairings involving the target device.
+             * @example true
+             */
+            revoke_pairings: boolean;
+            /**
+             * @description Whether approval revokes refresh-token families bound to the target device.
+             * @example true
+             */
+            revoke_refresh_tokens: boolean;
+            /**
+             * @description RFC 3339 UTC creation timestamp for the target device.
+             * @example 2026-05-01T12:00:00Z
+             */
+            target_device_created_at: string;
+            /**
+             * Format: uuid
+             * @description Device id that will be revoked.
+             * @example 22222222-3333-4444-8555-666666666666
+             */
+            target_device_id: string;
+            /**
+             * @description Optional human-readable device name shown to the user.
+             * @example Taylor's iPhone
+             */
+            target_device_name?: string | null;
+            /**
+             * @description Registered platform type for the target device.
+             * @example ios
+             * @enum {string}
+             */
+            target_device_type: "ios" | "android";
+        };
+        /**
+         * MailboxFirstPartyPrivilegedAction
+         * @description Typed canonical privileged action details shown on mobile.
+         */
+        MailboxFirstPartyPrivilegedAction: components["schemas"]["MailboxFirstPartyRelyingPartyRegisterActionV1"] | components["schemas"]["MailboxFirstPartyRelyingPartyRotateSecretActionV1"] | components["schemas"]["MailboxFirstPartyDeviceRevokeOtherActionV1"];
+        /**
+         * MailboxFirstPartyPrivilegedActionRequestV1
+         * @description Privileged console action approval request. `canonical_action_bytes` are the UTF-8 JSON bytes of the typed `action` object encoded with lexicographic property order and no insignificant whitespace; the hash pins the exact action details auth will execute after approval.
+         */
+        MailboxFirstPartyPrivilegedActionRequestV1: {
+            action: components["schemas"]["MailboxFirstPartyPrivilegedAction"];
+            action_type: components["schemas"]["MailboxFirstPartyPrivilegedActionType"];
+            /**
+             * Format: byte
+             * @description RFC 4648 standard base64 with `=` padding for the canonical privileged action JSON bytes.
+             */
+            canonical_action_bytes: string;
+            /**
+             * @description SHA-256 hash of `canonical_action_bytes` after base64 decoding.
+             * @example sha256:70f1e52bd01429bc2f405b182a3abc72751bda213dba41684a12db5116698c3c
+             */
+            canonical_action_hash: string;
+            /**
+             * @description RFC 3339 UTC timestamp when auth created the privileged-action intent.
+             * @example 2026-05-16T20:40:00Z
+             */
+            created_at: string;
+            /**
+             * @description OAuth client id for the console flow that initiated the intent.
+             * @example naughtbot-console
+             */
+            initiating_client_id: string;
+            /**
+             * @description Base64url SHA-256 thumbprint of the initiating browser DPoP key.
+             * @example 2oNQXcW2Upi5b1xHZQW1Yf3N0aYVnX_Jf7mRiS7Jm8A
+             */
+            initiating_dpop_jkt: string;
+            /**
+             * @description Opaque privileged-action intent id.
+             * @example pai_2af7b1fb2b5b4b5b8
+             */
+            intent_id: string;
+        };
+        /**
+         * MailboxFirstPartyRequestPayloadV1
+         * @description Request payload for the `first_party_request` envelope type.
+         */
+        MailboxFirstPartyRequestPayloadV1: {
+            /**
+             * @description RFC 3339 UTC timestamp after which the request is invalid.
+             * @example 2026-05-16T20:45:00Z
+             */
+            expires_at: string;
+            /**
+             * @description RFC 3339 UTC timestamp with canonical `Z` suffix.
+             * @example 2026-05-16T20:40:00Z
+             */
+            issued_at: string;
+            /**
+             * @description Opaque nonce bound into the mobile-signed decision.
+             * @example first-party-nonce-fixture
+             */
+            nonce: string;
+            privileged_action: components["schemas"]["MailboxFirstPartyPrivilegedActionRequestV1"];
+            /**
+             * @description Opaque auth/mailbox-scoped first-party request id.
+             * @example fpr_2af7b1fb2b5b4b5b8
+             */
+            request_id: string;
+            request_kind: components["schemas"]["MailboxFirstPartyRequestKind"];
+        };
+        /**
+         * MailboxFirstPartyPrivilegedActionDecisionBindingV1
+         * @description Canonical JSON object whose UTF-8 bytes are signed by the approving device key. Producers encode these fields in lexicographic property order with no insignificant whitespace and place the resulting bytes in `MailboxFirstPartyResponsePayloadV1.approval_binding_bytes`.
+         */
+        MailboxFirstPartyPrivilegedActionDecisionBindingV1: {
+            action_type: components["schemas"]["MailboxFirstPartyPrivilegedActionType"];
+            /**
+             * Format: uuid
+             * @description Device id whose signing key created `approval_signature`.
+             * @example 33333333-4444-4555-8666-777777777777
+             */
+            approving_device_id: string;
+            /**
+             * @description Base64url SHA-256 thumbprint of the approving device signing key.
+             * @example uJx87scLEhI5vT1YdtXx5ERw2IW0aP2mMNJ1lUu1Dx4
+             */
+            approving_device_signing_key_jkt: string;
+            /**
+             * @description Hash copied from the request payload.
+             * @example sha256:70f1e52bd01429bc2f405b182a3abc72751bda213dba41684a12db5116698c3c
+             */
+            canonical_action_hash: string;
+            /**
+             * @description RFC 3339 UTC timestamp of the mobile decision.
+             * @example 2026-05-16T20:41:00Z
+             */
+            decided_at: string;
+            decision: components["schemas"]["MailboxFirstPartyApprovalDecision"];
+            /**
+             * @description Request expiry copied from the request payload.
+             * @example 2026-05-16T20:45:00Z
+             */
+            expires_at: string;
+            /**
+             * @description Privileged-action intent id copied from the request payload.
+             * @example pai_2af7b1fb2b5b4b5b8
+             */
+            intent_id: string;
+            /**
+             * @description Nonce copied from the request payload.
+             * @example first-party-nonce-fixture
+             */
+            nonce: string;
+            /**
+             * Format: uuid
+             * @description Envelope id of the first-party request being answered.
+             * @example 11111111-2222-4333-8444-555555555555
+             */
+            request_envelope_id: string;
+            /**
+             * @description Envelope `issued_at` timestamp of the request being answered.
+             * @example 2026-05-16T20:40:00Z
+             */
+            request_envelope_issued_at: string;
+            /**
+             * @description Envelope type of the request being answered.
+             * @example first_party_request
+             * @enum {string}
+             */
+            request_envelope_type: "first_party_request";
+            /**
+             * @description First-party request id copied from the request payload.
+             * @example fpr_2af7b1fb2b5b4b5b8
+             */
+            request_id: string;
+            /**
+             * @description Canonical decision binding schema version.
+             * @enum {string}
+             */
+            version: "first-party-privileged-action-decision-binding/v1";
+        };
+        /**
+         * MailboxFirstPartyResponsePayloadV1
+         * @description Response payload for the `first_party_response` envelope type. The response carries the mobile decision, the exact canonical bytes signed by the approving device, and the raw device signature over those bytes.
+         */
+        MailboxFirstPartyResponsePayloadV1: {
+            /**
+             * Format: byte
+             * @description RFC 4648 standard base64 with `=` padding for the canonical `MailboxFirstPartyPrivilegedActionDecisionBindingV1` UTF-8 JSON bytes.
+             */
+            approval_binding_bytes: string;
+            approval_binding_format: components["schemas"]["MailboxFirstPartyApprovalBindingFormat"];
+            /**
+             * Format: byte
+             * @description RFC 4648 standard base64 with `=` padding for the raw signature over `approval_binding_bytes` after base64 decoding.
+             */
+            approval_signature: string;
+            /**
+             * @description Device signing-key algorithm identifier.
+             * @example ES256
+             */
+            approval_signature_algorithm: string;
+            /**
+             * Format: uuid
+             * @description Device id whose signing key created `approval_signature`.
+             * @example 33333333-4444-4555-8666-777777777777
+             */
+            approving_device_id: string;
+            /**
+             * @description Base64url SHA-256 thumbprint of the approving device signing key.
+             * @example uJx87scLEhI5vT1YdtXx5ERw2IW0aP2mMNJ1lUu1Dx4
+             */
+            approving_device_signing_key_jkt: string;
+            /**
+             * @description RFC 3339 UTC timestamp of the mobile decision.
+             * @example 2026-05-16T20:41:00Z
+             */
+            decided_at: string;
+            decision: components["schemas"]["MailboxFirstPartyApprovalDecision"];
+            /**
+             * @description Privileged-action intent id copied from the request payload.
+             * @example pai_2af7b1fb2b5b4b5b8
+             */
+            intent_id: string;
+            /**
+             * Format: uuid
+             * @description Envelope id of the first-party request being answered.
+             * @example 11111111-2222-4333-8444-555555555555
+             */
+            request_envelope_id: string;
+            /**
+             * @description First-party request id copied from the request payload.
+             * @example fpr_2af7b1fb2b5b4b5b8
+             */
+            request_id: string;
+            status: components["schemas"]["MailboxFirstPartyResponseStatus"];
+        };
     };
     responses: never;
     parameters: never;