@1claw/openapi-spec 0.48.2 → 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
           }
         }
       },
@@ -25938,9 +26069,18 @@
       },
       "TxConditions": {
         "type": "object",
-        "description": "Signing-time AND conditions on access policies (all tiers).\nIgnored on secret reads. Evaluated when a TransactionContext is present.\n",
+        "description": "Signing-time conditions on access policies (all tiers).\nIgnored on secret reads. Evaluated when a TransactionContext is present.\nFields are combined according to `match_mode` (default AND).\n",
         "additionalProperties": true,
         "properties": {
+          "match_mode": {
+            "type": "string",
+            "enum": [
+              "all",
+              "any"
+            ],
+            "default": "all",
+            "description": "How individual condition fields are combined.\n\"all\" (default): every present field must match (AND).\n\"any\": at least one present field must match (OR).\n"
+          },
           "function_name_in": {
             "type": "array",
             "items": {
@@ -25958,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",
@@ -25986,6 +26162,11 @@
             "items": {
               "type": "string"
             }
+          },
+          "deep_inspect": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, conditions are also evaluated against inner calls\nextracted from wrapper transactions (multicall, Safe execTransaction,\nERC-4337 handleOps). A match on any inner call counts as an overall match.\n"
           }
         }
       },
@@ -26013,6 +26194,101 @@
           "self_approval_allowed": {
             "type": "boolean",
             "default": false
+          },
+          "skip_when": {
+            "type": "array",
+            "description": "When ALL conditions in ANY entry match, consensus is bypassed.\nUseful for exempting known-safe recipients or low-value transfers.\n",
+            "items": {
+              "$ref": "#/components/schemas/FlatConditionSet"
+            }
+          },
+          "require_when": {
+            "type": "array",
+            "description": "Consensus is ONLY required when at least one entry matches.\nIf set and none match, consensus is skipped entirely.\n",
+            "items": {
+              "$ref": "#/components/schemas/FlatConditionSet"
+            }
+          },
+          "deep_inspect": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, also evaluate conditions against inner calls extracted\nfrom wrapper transactions (multicall, Safe execTransaction,\nERC-4337 handleOps).\n"
+          }
+        }
+      },
+      "FlatConditionSet": {
+        "type": "object",
+        "description": "Flat condition set used by consensus composability. Each present field\nis AND-combined within the set. At least one field must be specified\n(unless `always` is true).\n",
+        "additionalProperties": false,
+        "properties": {
+          "value_above": {
+            "type": "string",
+            "description": "Native value threshold in gwei (numeric string)"
+          },
+          "chain_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "to_address_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "function_selector_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "erc20_amount_above": {
+            "type": "string",
+            "description": "ERC-20 raw token amount threshold (numeric string)"
+          },
+          "intent_type_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "always": {
+            "type": "boolean",
+            "description": "When true, this entry always matches regardless of other fields"
+          }
+        }
+      },
+      "TimeWindow": {
+        "type": "object",
+        "description": "Time window condition for policy evaluation. Used inside the policy\n`conditions` JSON to restrict when the policy is active.\n",
+        "properties": {
+          "start_hour": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 23
+          },
+          "end_hour": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 24
+          },
+          "days_of_week": {
+            "type": "array",
+            "description": "Days when policy is active (0=Sunday, 6=Saturday)",
+            "items": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 6
+            }
+          },
+          "timezone": {
+            "type": "string",
+            "description": "IANA timezone identifier (e.g. \"America/New_York\"). Defaults to UTC."
+          },
+          "cron_expr": {
+            "type": "string",
+            "description": "Cron expression (6-field with seconds) for fine-grained scheduling."
           }
         }
       },
@@ -26021,8 +26297,7 @@
           {
             "type": "object",
             "required": [
-              "type",
-              "threshold_gwei"
+              "type"
             ],
             "properties": {
               "type": {
@@ -26031,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"
               }
             }
           },
@@ -26152,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"
+              }
+            }
           }
         ]
       },
@@ -26175,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"
           }
         }
       },
@@ -26242,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 ---
 
@@ -17084,10 +17182,19 @@ components:
         TxConditions:
             type: object
             description: |
-                Signing-time AND conditions on access policies (all tiers).
+                Signing-time conditions on access policies (all tiers).
                 Ignored on secret reads. Evaluated when a TransactionContext is present.
+                Fields are combined according to `match_mode` (default AND).
             additionalProperties: true
             properties:
+                match_mode:
+                    type: string
+                    enum: [all, any]
+                    default: all
+                    description: |
+                        How individual condition fields are combined.
+                        "all" (default): every present field must match (AND).
+                        "any": at least one present field must match (OR).
                 function_name_in:
                     type: array
                     items:
@@ -17100,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:
@@ -17119,6 +17252,13 @@ components:
                     type: array
                     items:
                         type: string
+                deep_inspect:
+                    type: boolean
+                    default: false
+                    description: |
+                        When true, conditions are also evaluated against inner calls
+                        extracted from wrapper transactions (multicall, Safe execTransaction,
+                        ERC-4337 handleOps). A match on any inner call counts as an overall match.
 
         ConsensusTrigger:
             type: object
@@ -17137,18 +17277,106 @@ components:
                 self_approval_allowed:
                     type: boolean
                     default: false
+                skip_when:
+                    type: array
+                    description: |
+                        When ALL conditions in ANY entry match, consensus is bypassed.
+                        Useful for exempting known-safe recipients or low-value transfers.
+                    items:
+                        $ref: "#/components/schemas/FlatConditionSet"
+                require_when:
+                    type: array
+                    description: |
+                        Consensus is ONLY required when at least one entry matches.
+                        If set and none match, consensus is skipped entirely.
+                    items:
+                        $ref: "#/components/schemas/FlatConditionSet"
+                deep_inspect:
+                    type: boolean
+                    default: false
+                    description: |
+                        When true, also evaluate conditions against inner calls extracted
+                        from wrapper transactions (multicall, Safe execTransaction,
+                        ERC-4337 handleOps).
+
+        FlatConditionSet:
+            type: object
+            description: |
+                Flat condition set used by consensus composability. Each present field
+                is AND-combined within the set. At least one field must be specified
+                (unless `always` is true).
+            additionalProperties: false
+            properties:
+                value_above:
+                    type: string
+                    description: Native value threshold in gwei (numeric string)
+                chain_in:
+                    type: array
+                    items:
+                        type: string
+                to_address_in:
+                    type: array
+                    items:
+                        type: string
+                function_selector_in:
+                    type: array
+                    items:
+                        type: string
+                erc20_amount_above:
+                    type: string
+                    description: ERC-20 raw token amount threshold (numeric string)
+                intent_type_in:
+                    type: array
+                    items:
+                        type: string
+                always:
+                    type: boolean
+                    description: When true, this entry always matches regardless of other fields
+
+        TimeWindow:
+            type: object
+            description: |
+                Time window condition for policy evaluation. Used inside the policy
+                `conditions` JSON to restrict when the policy is active.
+            properties:
+                start_hour:
+                    type: integer
+                    minimum: 0
+                    maximum: 23
+                end_hour:
+                    type: integer
+                    minimum: 0
+                    maximum: 24
+                days_of_week:
+                    type: array
+                    description: Days when policy is active (0=Sunday, 6=Saturday)
+                    items:
+                        type: integer
+                        minimum: 0
+                        maximum: 6
+                timezone:
+                    type: string
+                    description: IANA timezone identifier (e.g. "America/New_York"). Defaults to UTC.
+                cron_expr:
+                    type: string
+                    description: Cron expression (6-field with seconds) for fine-grained scheduling.
 
         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:
@@ -17203,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
@@ -17218,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
@@ -17260,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.48.2",
+    "version": "0.50.0",
   "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
   "license": "MIT",
   "repository": {