@1claw/openapi-spec 0.61.31 → 0.61.34

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.31",
+    "version": "0.61.34",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging. Automations (workflow_spec,\nwebhook tokens, event triggers, Assist), cloud runtimes with\ninteractive shell sessions, agent memory, and discovery.\n\n## Domains\n\n`api.1claw.co` is canonical: it is the OIDC issuer, the `aud` the API\nmints, and the first entry in `servers` — a generated client takes its\nbase URL from there, and the previous ordering pointed every SDK at the\ndomain the issuer had already left. `api.1claw.xyz` still answers and is\nstill accepted on token validation, because tokens minted before the\nmove carry it; it is never minted now.\n\nOne deliberate exception: the Shroud attestation identity token is\nrequested from GCP with `audience: https://api.1claw.xyz`, so\n`/v1/shroud/attestation` reports that as its `expected_audience`. That\nis accurate rather than stale — the audience is a verification contract\nwith anyone already checking the token, and moving it is a breaking\nchange for them, not a rename.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.co"
@@ -17221,6 +17221,75 @@
         }
       }
     },
+    "/v1/x402/topup": {
+      "post": {
+        "tags": [
+          "Billing"
+        ],
+        "summary": "x402 ledger top-up (agent door)",
+        "description": "The wallet rail for Shroud (Shroud AI plan). Without `X-PAYMENT` the response is a\n**402** quote (`x402Version`, `accepts[]` with `payTo`, `maxAmountRequired`, `resource`)\nfor `amount_usd` (default $1) of USDC on Base. With a signed EIP-3009 `X-PAYMENT`\nthe facilitator verifies it, the proof is claimed once, the payer wallet's org\nledger is credited in micro-USD, and the facilitator settles.\n\n**Payment is the account.** An unknown wallet's first settled top-up provisions a\nshadow org, one Shroud-enabled agent and one `sk-shroud-v1` router key keyed on the\nwallet (returned once as `router_key`), after screening the wallet against the OFAC\nSDN list (fails closed when the list is missing or stale) and the caller's region\nagainst the custody geofence. Same wallet = same org on every later top-up. The\nresponse always carries a ≤60 s `access_token` for the wallet's agent so the\ngateway can serve the paid request immediately. The Shroud gateway drives this for\n`Authorization: Bearer x402` requests and relays the quote or the result.\n",
+        "operationId": "x402Topup",
+        "security": [],
+        "parameters": [
+          {
+            "name": "X-PAYMENT",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Base64 x402 payment payload (EIP-3009 USDC authorization on Base)"
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "amount_usd": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "description": "Whole dollars to add to the ledger (default 1)"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Credited",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/X402TopupResponse"
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Payment required — the quote to sign, or why the payment was refused",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PaymentRequirement"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "The wallet is sanctioned or the region is fenced; no account is opened"
+          },
+          "503": {
+            "description": "The sanctions list is unavailable (fails closed)"
+          }
+        }
+      }
+    },
     "/v1/oauth/token": {
       "post": {
         "tags": [
@@ -23871,6 +23940,130 @@
         }
       }
     },
+    "/v1/agents/{agent_id}/tool-bindings": {
+      "post": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "Create a secret → tool binding (rehydration policy)",
+        "description": "Authorises the enclave to rehydrate the `⟦sk:…⟧` placeholder for `secret_path`\ninto `tool_name` at `arg_path` — and only when the call's destination host is one\nof `destination_hosts`. Redaction replaces vault secrets in prompts with\ndeterministic placeholders the model can place but never read; a placeholder is\nsubstituted back only inside an authorised tool-call argument, at the moment the\nenclave performs the call (`execution_mode: \"tee\"`). No binding, wrong argument,\nwrong host, bad checksum or an unknown tag is a 403 at execution time. Human users\nonly; up to 200 per agent.\n",
+        "operationId": "createToolBinding",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateToolBindingRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecretToolBinding"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "description": "A binding for this secret, tool and argument already exists"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "List secret → tool bindings",
+        "operationId": "listToolBindings",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Bindings",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "bindings"
+                  ],
+                  "properties": {
+                    "bindings": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/SecretToolBinding"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/tool-bindings/{binding_id}": {
+      "delete": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "Delete a secret → tool binding",
+        "operationId": "deleteToolBinding",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "binding_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Deleted"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/oauth/connections": {
       "get": {
         "tags": [
@@ -36090,7 +36283,13 @@
             "type": "string"
           },
           "credit_balance_cents": {
-            "type": "integer"
+            "type": "integer",
+            "description": "Derived (rounded down); the ledger unit is micro-USD"
+          },
+          "credit_balance_micro_usd": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The ledger value. One inspected Shroud request costs 5,000 micro-USD ($0.005)."
           },
           "credit_balance_usd": {
             "type": "string"
@@ -36313,10 +36512,17 @@
         "type": "object",
         "properties": {
           "balance_cents": {
-            "type": "integer"
+            "type": "integer",
+            "description": "Derived (rounded down); the ledger unit is micro-USD"
+          },
+          "balance_micro_usd": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The ledger value (1 = $0.000001)"
           },
           "balance_usd": {
-            "type": "string"
+            "type": "string",
+            "description": "Dollars at the ledger's precision (e.g. \"4.995\"), never fewer than two decimals"
           },
           "expiring_within_90_days": {
             "type": "object",
@@ -40035,6 +40241,148 @@
           }
         ]
       },
+      "CreateToolBindingRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "secret_path",
+          "tool_name",
+          "destination_hosts"
+        ],
+        "properties": {
+          "secret_path": {
+            "type": "string",
+            "description": "Vault path of the secret the placeholder stands for"
+          },
+          "tool_name": {
+            "type": "string",
+            "description": "Tool the binding applies to (`http_request`, `run_sql`, …) or `*`"
+          },
+          "arg_path": {
+            "type": "string",
+            "description": "JSON pointer into the tool's arguments (`/headers/Authorization`, `/body/*`) or `*` (default)"
+          },
+          "destination_hosts": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 32,
+            "items": {
+              "type": "string"
+            },
+            "description": "Hosts the rehydrated call may reach (`api.stripe.com`, `*.googleapis.com`); required"
+          }
+        }
+      },
+      "SecretToolBinding": {
+        "type": "object",
+        "required": [
+          "id",
+          "org_id",
+          "agent_id",
+          "secret_path",
+          "tool_name",
+          "arg_path",
+          "destination_hosts",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "secret_path": {
+            "type": "string"
+          },
+          "tool_name": {
+            "type": "string"
+          },
+          "arg_path": {
+            "type": "string"
+          },
+          "destination_hosts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "created_by": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "X402TopupResponse": {
+        "type": "object",
+        "required": [
+          "wallet",
+          "org_id",
+          "agent_id",
+          "credited_micro_usd",
+          "balance_micro_usd",
+          "balance_usd",
+          "access_token",
+          "expires_in",
+          "base_url",
+          "provisioned"
+        ],
+        "properties": {
+          "wallet": {
+            "type": "string",
+            "description": "Payer address (lower-case)"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "credited_micro_usd": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "balance_micro_usd": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "balance_usd": {
+            "type": "string"
+          },
+          "router_key": {
+            "type": "string",
+            "description": "Present only on the top-up that provisioned the account (or re-minted a lost key). Shown once."
+          },
+          "access_token": {
+            "type": "string",
+            "description": "A ≤60 s agent token for the wallet's agent (carries the `router_key` claim)"
+          },
+          "expires_in": {
+            "type": "integer"
+          },
+          "base_url": {
+            "type": "string",
+            "description": "The Shroud gateway"
+          },
+          "provisioned": {
+            "type": "boolean",
+            "description": "True when this top-up created the account"
+          }
+        }
+      },
       "EventSubscription": {
         "type": "object",
         "required": [

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.31"
+    version: "0.61.34"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -10956,6 +10956,64 @@ paths:
                 "400":
                     description: Invalid request
 
+    /v1/x402/topup:
+        post:
+            tags: [Billing]
+            summary: x402 ledger top-up (agent door)
+            description: |
+                The wallet rail for Shroud (Shroud AI plan). Without `X-PAYMENT` the response is a
+                **402** quote (`x402Version`, `accepts[]` with `payTo`, `maxAmountRequired`, `resource`)
+                for `amount_usd` (default $1) of USDC on Base. With a signed EIP-3009 `X-PAYMENT`
+                the facilitator verifies it, the proof is claimed once, the payer wallet's org
+                ledger is credited in micro-USD, and the facilitator settles.
+
+                **Payment is the account.** An unknown wallet's first settled top-up provisions a
+                shadow org, one Shroud-enabled agent and one `sk-shroud-v1` router key keyed on the
+                wallet (returned once as `router_key`), after screening the wallet against the OFAC
+                SDN list (fails closed when the list is missing or stale) and the caller's region
+                against the custody geofence. Same wallet = same org on every later top-up. The
+                response always carries a ≤60 s `access_token` for the wallet's agent so the
+                gateway can serve the paid request immediately. The Shroud gateway drives this for
+                `Authorization: Bearer x402` requests and relays the quote or the result.
+            operationId: x402Topup
+            security: []
+            parameters:
+                - name: X-PAYMENT
+                  in: header
+                  required: false
+                  schema: { type: string }
+                  description: Base64 x402 payment payload (EIP-3009 USDC authorization on Base)
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            additionalProperties: false
+                            properties:
+                                amount_usd:
+                                    type: integer
+                                    minimum: 1
+                                    maximum: 100
+                                    description: Whole dollars to add to the ledger (default 1)
+            responses:
+                "200":
+                    description: Credited
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/X402TopupResponse"
+                "402":
+                    description: Payment required — the quote to sign, or why the payment was refused
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PaymentRequirement"
+                "403":
+                    description: The wallet is sanctioned or the region is fenced; no account is opened
+                "503":
+                    description: The sanctions list is unavailable (fails closed)
+
     /v1/oauth/token:
         post:
             tags: [OAuth]
@@ -15270,6 +15328,86 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/agents/{agent_id}/tool-bindings:
+        post:
+            tags: [Agents]
+            summary: Create a secret → tool binding (rehydration policy)
+            description: |
+                Authorises the enclave to rehydrate the `⟦sk:…⟧` placeholder for `secret_path`
+                into `tool_name` at `arg_path` — and only when the call's destination host is one
+                of `destination_hosts`. Redaction replaces vault secrets in prompts with
+                deterministic placeholders the model can place but never read; a placeholder is
+                substituted back only inside an authorised tool-call argument, at the moment the
+                enclave performs the call (`execution_mode: "tee"`). No binding, wrong argument,
+                wrong host, bad checksum or an unknown tag is a 403 at execution time. Human users
+                only; up to 200 per agent.
+            operationId: createToolBinding
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateToolBindingRequest"
+            responses:
+                "201":
+                    description: Created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SecretToolBinding"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "409":
+                    description: A binding for this secret, tool and argument already exists
+        get:
+            tags: [Agents]
+            summary: List secret → tool bindings
+            operationId: listToolBindings
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Bindings
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [bindings]
+                                properties:
+                                    bindings:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/SecretToolBinding"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/tool-bindings/{binding_id}:
+        delete:
+            tags: [Agents]
+            summary: Delete a secret → tool binding
+            operationId: deleteToolBinding
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: binding_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                "204":
+                    description: Deleted
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/agents/{agent_id}/oauth/connections:
         get:
             tags: [OAuth Connect]
@@ -23430,6 +23568,11 @@ components:
                     type: string
                 credit_balance_cents:
                     type: integer
+                    description: Derived (rounded down); the ledger unit is micro-USD
+                credit_balance_micro_usd:
+                    type: integer
+                    format: int64
+                    description: The ledger value. One inspected Shroud request costs 5,000 micro-USD ($0.005).
                 credit_balance_usd:
                     type: string
                 overage_method:
@@ -23586,8 +23729,14 @@ components:
             properties:
                 balance_cents:
                     type: integer
+                    description: Derived (rounded down); the ledger unit is micro-USD
+                balance_micro_usd:
+                    type: integer
+                    format: int64
+                    description: The ledger value (1 = $0.000001)
                 balance_usd:
                     type: string
+                    description: Dollars at the ledger's precision (e.g. "4.995"), never fewer than two decimals
                 expiring_within_90_days:
                     type: object
                     properties:
@@ -25982,6 +26131,63 @@ components:
                           description: The Shroud gateway to point the SDK at
                           example: https://shroud.1claw.co
 
+        CreateToolBindingRequest:
+            type: object
+            additionalProperties: false
+            required: [secret_path, tool_name, destination_hosts]
+            properties:
+                secret_path:
+                    type: string
+                    description: Vault path of the secret the placeholder stands for
+                tool_name:
+                    type: string
+                    description: Tool the binding applies to (`http_request`, `run_sql`, …) or `*`
+                arg_path:
+                    type: string
+                    description: JSON pointer into the tool's arguments (`/headers/Authorization`, `/body/*`) or `*` (default)
+                destination_hosts:
+                    type: array
+                    minItems: 1
+                    maxItems: 32
+                    items: { type: string }
+                    description: Hosts the rehydrated call may reach (`api.stripe.com`, `*.googleapis.com`); required
+
+        SecretToolBinding:
+            type: object
+            required: [id, org_id, agent_id, secret_path, tool_name, arg_path, destination_hosts, created_at]
+            properties:
+                id: { type: string, format: uuid }
+                org_id: { type: string, format: uuid }
+                agent_id: { type: string, format: uuid }
+                secret_path: { type: string }
+                tool_name: { type: string }
+                arg_path: { type: string }
+                destination_hosts:
+                    type: array
+                    items: { type: string }
+                created_by: { type: string, format: uuid, nullable: true }
+                created_at: { type: string, format: date-time }
+
+        X402TopupResponse:
+            type: object
+            required: [wallet, org_id, agent_id, credited_micro_usd, balance_micro_usd, balance_usd, access_token, expires_in, base_url, provisioned]
+            properties:
+                wallet: { type: string, description: Payer address (lower-case) }
+                org_id: { type: string, format: uuid }
+                agent_id: { type: string, format: uuid }
+                credited_micro_usd: { type: integer, format: int64 }
+                balance_micro_usd: { type: integer, format: int64 }
+                balance_usd: { type: string }
+                router_key:
+                    type: string
+                    description: Present only on the top-up that provisioned the account (or re-minted a lost key). Shown once.
+                access_token:
+                    type: string
+                    description: A ≤60 s agent token for the wallet's agent (carries the `router_key` claim)
+                expires_in: { type: integer }
+                base_url: { type: string, description: The Shroud gateway }
+                provisioned: { type: boolean, description: True when this top-up created the account }
+
         EventSubscription:
             type: object
             required: [id, agent_id, binding_id, event_type, interval_secs, is_active, primed, next_poll_at, consecutive_errors, events_emitted, created_at]

package/package.json

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