@1claw/openapi-spec 0.49.0 → 0.50.0

package/openapi.json

@@ -921,7 +921,19 @@
           "Authentication"
         ],
         "summary": "Complete passkey registration",
+        "description": "When the account already has a password, passkey, or TOTP,\n`X-Auth-Confirm` is required (purpose `security.passkey.register`).\n",
         "operationId": "passkeyRegisterComplete",
+        "parameters": [
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": false,
+            "description": "Re-auth token (`rat_`) or account password",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -1154,6 +1166,7 @@
           "Authentication"
         ],
         "summary": "Delete a passkey",
+        "description": "Removes a registered passkey. Requires recent re-authentication\n(`X-Auth-Confirm` with a `rat_` token from `POST /v1/auth/reauth`\nusing purpose `security.passkey.delete`). Passkey or TOTP is\nrequired when either is enrolled. Deleting the last passkey is\nrefused while vault passkey unlock is enabled.\n",
         "operationId": "deletePasskey",
         "parameters": [
           {
@@ -1164,11 +1177,23 @@
               "type": "string",
               "format": "uuid"
             }
+          },
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": true,
+            "description": "Re-auth token (`rat_`) or account password",
+            "schema": {
+              "type": "string"
+            }
           }
         ],
         "responses": {
           "200": {
             "description": "Passkey deleted"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           }
         }
       }
@@ -1305,6 +1330,17 @@
         ],
         "summary": "Delete current user account",
         "operationId": "deleteMe",
+        "parameters": [
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": true,
+            "description": "Re-auth token (`rat_`, purpose `account.delete`) or password",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -1334,6 +1370,76 @@
         }
       }
     },
+    "/v1/auth/settings": {
+      "get": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Get user security settings",
+        "operationId": "getSecuritySettings",
+        "responses": {
+          "200": {
+            "description": "Security settings",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "require_passkey_for_vaults": {
+                      "type": "boolean"
+                    },
+                    "passkey_count": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Update user security settings",
+        "description": "Disabling `require_passkey_for_vaults` requires `X-Auth-Confirm`\n(purpose `security.vault_passkey.disable`) with a passkey or TOTP\nwhen either is enrolled.\n",
+        "operationId": "updateSecuritySettings",
+        "parameters": [
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "require_passkey_for_vaults": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated settings"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
     "/v1/auth/mfa/status": {
       "get": {
         "tags": [
@@ -1451,7 +1557,19 @@
           "Authentication"
         ],
         "summary": "Disable MFA",
+        "description": "Requires a valid TOTP or recovery code in the body, or a passkey\nre-auth token in `X-Auth-Confirm` (purpose `security.mfa.disable`).\nAccount password alone is not accepted while TOTP is enabled.\n",
         "operationId": "mfaDisable",
+        "parameters": [
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": false,
+            "description": "Passkey or TOTP re-auth token (`rat_`)",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -1699,8 +1817,18 @@
           "Authentication"
         ],
         "summary": "Export user data (GDPR)",
-        "description": "Returns a full export of the authenticated user's data including\nprofile, vaults, agents, secrets metadata, and policies. Intended\nfor GDPR data-portability requests. Only available to human users\n(not agents).\n",
+        "description": "Returns a full export of the authenticated user's data including\nprofile, vaults, agents, secrets metadata, and policies. Intended\nfor GDPR data-portability requests. Only available to human users\n(not agents). Requires `X-Auth-Confirm` (purpose `account.export`);\npasskey or TOTP when either is enrolled.\n",
         "operationId": "exportUserData",
+        "parameters": [
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "User data export",
@@ -16066,10 +16194,13 @@
         "type": "object",
         "properties": {
           "code": {
-            "type": "string"
+            "type": "string",
+            "description": "TOTP or recovery code"
           },
           "password": {
-            "type": "string"
+            "type": "string",
+            "description": "Deprecated. Password is no longer sufficient to disable MFA.",
+            "deprecated": true
           }
         }
       },
@@ -25967,7 +26098,43 @@
           },
           "value_above": {
             "type": "string",
-            "description": "Native value threshold in gwei"
+            "description": "Native value threshold in wei (arbitrary-precision string)"
+          },
+          "eip712_primary_type_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Match EIP-712 typed_data primaryType (case-sensitive)"
+          },
+          "eip712_verifying_contract_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Match EIP-712 domain.verifyingContract (case-insensitive)"
+          },
+          "eip712_domain_name_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Match EIP-712 domain.name"
+          },
+          "eip712_domain_chain_id_in": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Match EIP-712 domain.chainId"
+          },
+          "eip7702_authorized_addresses_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Match EIP-7702 authorization_list delegate addresses (case-insensitive)"
           },
           "to_address_in": {
             "type": "array",
@@ -26130,8 +26297,7 @@
           {
             "type": "object",
             "required": [
-              "type",
-              "threshold_gwei"
+              "type"
             ],
             "properties": {
               "type": {
@@ -26140,9 +26306,15 @@
                   "value_above"
                 ]
               },
+              "threshold_wei": {
+                "type": "string",
+                "description": "Value threshold in wei (arbitrary-precision string). Preferred over threshold_gwei."
+              },
               "threshold_gwei": {
                 "type": "integer",
-                "format": "int64"
+                "format": "int64",
+                "deprecated": true,
+                "description": "Deprecated — use threshold_wei for arbitrary precision"
               }
             }
           },
@@ -26261,6 +26433,28 @@
                 ]
               }
             }
+          },
+          {
+            "type": "object",
+            "required": [
+              "type",
+              "actions"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "action_in"
+                ]
+              },
+              "actions": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Control-plane actions to match, e.g. policy.create, policy.update,\npolicy.delete, signing_key.export, member.role_change, member.remove\n"
+              }
+            }
           }
         ]
       },
@@ -26284,6 +26478,20 @@
             "additionalProperties": {
               "type": "integer"
             }
+          },
+          "require_credential_types": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "password",
+                "passkey",
+                "totp",
+                "biometric",
+                "api_key"
+              ]
+            },
+            "description": "At least one approval must use one of these credential types"
           }
         }
       },
@@ -26351,6 +26559,17 @@
           },
           "reason": {
             "type": "string"
+          },
+          "credential_type": {
+            "type": "string",
+            "enum": [
+              "password",
+              "passkey",
+              "totp",
+              "biometric",
+              "api_key"
+            ],
+            "description": "Authentication method used for this approval vote"
           }
         }
       },

package/openapi.yaml

@@ -625,7 +625,17 @@ paths:
         post:
             tags: [Authentication]
             summary: Complete passkey registration
+            description: |
+                When the account already has a password, passkey, or TOTP,
+                `X-Auth-Confirm` is required (purpose `security.passkey.register`).
             operationId: passkeyRegisterComplete
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: false
+                  description: Re-auth token (`rat_`) or account password
+                  schema:
+                      type: string
             requestBody:
                 required: true
                 content:
@@ -768,6 +778,12 @@ paths:
         delete:
             tags: [Authentication]
             summary: Delete a passkey
+            description: |
+                Removes a registered passkey. Requires recent re-authentication
+                (`X-Auth-Confirm` with a `rat_` token from `POST /v1/auth/reauth`
+                using purpose `security.passkey.delete`). Passkey or TOTP is
+                required when either is enrolled. Deleting the last passkey is
+                refused while vault passkey unlock is enabled.
             operationId: deletePasskey
             parameters:
                 - name: passkey_id
@@ -776,9 +792,17 @@ paths:
                   schema:
                       type: string
                       format: uuid
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  description: Re-auth token (`rat_`) or account password
+                  schema:
+                      type: string
             responses:
                 "200":
                     description: Passkey deleted
+                "403":
+                    $ref: "#/components/responses/Forbidden"
 
     /v1/approvals/request:
         post:
@@ -861,6 +885,13 @@ paths:
             tags: [Authentication]
             summary: Delete current user account
             operationId: deleteMe
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  description: Re-auth token (`rat_`, purpose `account.delete`) or password
+                  schema:
+                      type: string
             requestBody:
                 required: true
                 content:
@@ -878,6 +909,52 @@ paths:
                 "400":
                     $ref: "#/components/responses/BadRequest"
 
+    /v1/auth/settings:
+        get:
+            tags: [Authentication]
+            summary: Get user security settings
+            operationId: getSecuritySettings
+            responses:
+                "200":
+                    description: Security settings
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    require_passkey_for_vaults:
+                                        type: boolean
+                                    passkey_count:
+                                        type: integer
+        patch:
+            tags: [Authentication]
+            summary: Update user security settings
+            description: |
+                Disabling `require_passkey_for_vaults` requires `X-Auth-Confirm`
+                (purpose `security.vault_passkey.disable`) with a passkey or TOTP
+                when either is enrolled.
+            operationId: updateSecuritySettings
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: false
+                  schema:
+                      type: string
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                require_passkey_for_vaults:
+                                    type: boolean
+            responses:
+                "200":
+                    description: Updated settings
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
     # MFA
 
     /v1/auth/mfa/status:
@@ -953,7 +1030,18 @@ paths:
         delete:
             tags: [Authentication]
             summary: Disable MFA
+            description: |
+                Requires a valid TOTP or recovery code in the body, or a passkey
+                re-auth token in `X-Auth-Confirm` (purpose `security.mfa.disable`).
+                Account password alone is not accepted while TOTP is enabled.
             operationId: mfaDisable
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: false
+                  description: Passkey or TOTP re-auth token (`rat_`)
+                  schema:
+                      type: string
             requestBody:
                 required: true
                 content:
@@ -1118,8 +1206,15 @@ paths:
                 Returns a full export of the authenticated user's data including
                 profile, vaults, agents, secrets metadata, and policies. Intended
                 for GDPR data-portability requests. Only available to human users
-                (not agents).
+                (not agents). Requires `X-Auth-Confirm` (purpose `account.export`);
+                passkey or TOTP when either is enrolled.
             operationId: exportUserData
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  schema:
+                      type: string
             responses:
                 "200":
                     description: User data export
@@ -10278,8 +10373,11 @@ components:
             properties:
                 code:
                     type: string
+                    description: TOTP or recovery code
                 password:
                     type: string
+                    description: Deprecated. Password is no longer sufficient to disable MFA.
+                    deprecated: true
 
         # --- Device Auth ---
 
@@ -17109,7 +17207,33 @@ components:
                     type: string
                 value_above:
                     type: string
-                    description: Native value threshold in gwei
+                    description: Native value threshold in wei (arbitrary-precision string)
+                eip712_primary_type_in:
+                    type: array
+                    items:
+                        type: string
+                    description: Match EIP-712 typed_data primaryType (case-sensitive)
+                eip712_verifying_contract_in:
+                    type: array
+                    items:
+                        type: string
+                    description: Match EIP-712 domain.verifyingContract (case-insensitive)
+                eip712_domain_name_in:
+                    type: array
+                    items:
+                        type: string
+                    description: Match EIP-712 domain.name
+                eip712_domain_chain_id_in:
+                    type: array
+                    items:
+                        type: integer
+                        format: int64
+                    description: Match EIP-712 domain.chainId
+                eip7702_authorized_addresses_in:
+                    type: array
+                    items:
+                        type: string
+                    description: Match EIP-7702 authorization_list delegate addresses (case-insensitive)
                 to_address_in:
                     type: array
                     items:
@@ -17240,14 +17364,19 @@ components:
         ConsensusCondition:
             oneOf:
                 - type: object
-                  required: [type, threshold_gwei]
+                  required: [type]
                   properties:
                       type:
                           type: string
                           enum: [value_above]
+                      threshold_wei:
+                          type: string
+                          description: Value threshold in wei (arbitrary-precision string). Preferred over threshold_gwei.
                       threshold_gwei:
                           type: integer
                           format: int64
+                          deprecated: true
+                          description: Deprecated — use threshold_wei for arbitrary precision
                 - type: object
                   required: [type, chains]
                   properties:
@@ -17302,6 +17431,19 @@ components:
                       type:
                           type: string
                           enum: [always]
+                - type: object
+                  required: [type, actions]
+                  properties:
+                      type:
+                          type: string
+                          enum: [action_in]
+                      actions:
+                          type: array
+                          items:
+                              type: string
+                          description: |
+                              Control-plane actions to match, e.g. policy.create, policy.update,
+                              policy.delete, signing_key.export, member.role_change, member.remove
 
         ApprovalRequirement:
             type: object
@@ -17317,6 +17459,12 @@ components:
                     type: object
                     additionalProperties:
                         type: integer
+                require_credential_types:
+                    type: array
+                    items:
+                        type: string
+                        enum: [password, passkey, totp, biometric, api_key]
+                    description: At least one approval must use one of these credential types
 
         SubmitPendingApprovalRequest:
             type: object
@@ -17359,6 +17507,10 @@ components:
                     type: string
                 reason:
                     type: string
+                credential_type:
+                    type: string
+                    enum: [password, passkey, totp, biometric, api_key]
+                    description: Authentication method used for this approval vote
 
         PendingApprovalResponse:
             type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1claw/openapi-spec",
-    "version": "0.49.0",
+    "version": "0.50.0",
   "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
   "license": "MIT",
   "repository": {