@1claw/openapi-spec 0.8.0 → 0.10.0

package/README.md

@@ -40,7 +40,7 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v2.1.0)
+## What's in the spec (v0.10.0)
 
 - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking
 - **Secrets** — CRUD, versioning, CMEK-encrypted flag

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.3.0",
+    "version": "2.4.0",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.xyz"
@@ -22,6 +22,9 @@
       "description": "Shroud TEE Proxy (Intents API + LLM proxy)"
     }
   ],
+  "x-agentcash-guidance": {
+    "llmsTxtUrl": "https://1claw.xyz/llms.txt"
+  },
   "security": [
     {
       "BearerAuth": []
@@ -1152,6 +1155,16 @@
         ],
         "summary": "Store or update a secret",
         "operationId": "putSecret",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.0075"
+        },
         "parameters": [
           {
             "$ref": "#/components/parameters/VaultId"
@@ -1183,6 +1196,9 @@
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
+          },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
           }
         }
       },
@@ -1192,6 +1208,16 @@
         ],
         "summary": "Retrieve a decrypted secret",
         "operationId": "getSecret",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.0015"
+        },
         "parameters": [
           {
             "$ref": "#/components/parameters/VaultId"
@@ -1637,6 +1663,15 @@
           "Transactions"
         ],
         "summary": "Submit a transaction for signing",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "quote"
+        },
         "description": "Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).\nDuplicate requests with the same key within 24 hours return the cached transaction response\n(no second sign/broadcast). Omit the header for non-idempotent submissions.\n",
         "operationId": "submitTransaction",
         "parameters": [
@@ -1684,6 +1719,9 @@
               }
             }
           },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
+          },
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
@@ -1785,6 +1823,16 @@
         ],
         "summary": "Simulate a transaction via Tenderly",
         "operationId": "simulateTransaction",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.075"
+        },
         "parameters": [
           {
             "$ref": "#/components/parameters/AgentId"
@@ -1814,6 +1862,9 @@
           "400": {
             "$ref": "#/components/responses/BadRequest"
           },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
+          },
           "403": {
             "$ref": "#/components/responses/Forbidden"
           }
@@ -1827,6 +1878,16 @@
         ],
         "summary": "Simulate a bundle of transactions",
         "operationId": "simulateBundle",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.075"
+        },
         "parameters": [
           {
             "$ref": "#/components/parameters/AgentId"
@@ -1855,6 +1916,9 @@
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
+          },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
           }
         }
       }
@@ -2039,6 +2103,16 @@
         ],
         "summary": "Create a share link for a secret",
         "operationId": "createShare",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.003"
+        },
         "parameters": [
           {
             "name": "secret_id",
@@ -2071,6 +2145,9 @@
               }
             }
           },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
+          },
           "404": {
             "$ref": "#/components/responses/NotFound"
           }
@@ -2085,6 +2162,16 @@
         "summary": "Access a shared secret",
         "operationId": "accessShare",
         "security": [],
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.0015"
+        },
         "parameters": [
           {
             "name": "share_id",
@@ -2617,6 +2704,16 @@
         ],
         "summary": "Query audit events",
         "operationId": "queryAuditEvents",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.0008"
+        },
         "parameters": [
           {
             "name": "resource_id",
@@ -2682,6 +2779,9 @@
                 }
               }
             }
+          },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
           }
         }
       }
@@ -4177,6 +4277,14 @@
           "oidc_client_id": {
             "type": "string",
             "description": "OIDC client ID (required for oidc_client_credentials auth)"
+          },
+          "shroud_enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable Shroud LLM Proxy for this agent"
+          },
+          "shroud_config": {
+            "$ref": "#/components/schemas/ShroudConfig"
           }
         }
       },
@@ -4230,6 +4338,13 @@
               "type": "string",
               "format": "uuid"
             }
+          },
+          "shroud_enabled": {
+            "type": "boolean",
+            "description": "Enable/disable Shroud LLM Proxy"
+          },
+          "shroud_config": {
+            "$ref": "#/components/schemas/ShroudConfig"
           }
         }
       },
@@ -4241,6 +4356,7 @@
           "auth_method",
           "is_active",
           "intents_api_enabled",
+          "shroud_enabled",
           "created_at"
         ],
         "properties": {
@@ -4323,6 +4439,13 @@
             "type": "string",
             "description": "P-256 ECDH public key (base64 SEC1 uncompressed point, auto-generated at creation)"
           },
+          "shroud_enabled": {
+            "type": "boolean",
+            "description": "Whether this agent routes LLM traffic through the Shroud TEE proxy"
+          },
+          "shroud_config": {
+            "$ref": "#/components/schemas/ShroudConfig"
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"
@@ -4389,6 +4512,91 @@
           "ecdh_public_key": {
             "type": "string",
             "description": "P-256 ECDH public key (base64 SEC1 uncompressed point)"
+          },
+          "shroud_enabled": {
+            "type": "boolean",
+            "description": "Whether this agent routes LLM traffic through the Shroud TEE proxy"
+          },
+          "shroud_config": {
+            "$ref": "#/components/schemas/ShroudConfig"
+          }
+        }
+      },
+      "ShroudConfig": {
+        "type": "object",
+        "description": "Per-agent Shroud LLM Proxy configuration",
+        "properties": {
+          "pii_policy": {
+            "type": "string",
+            "enum": [
+              "block",
+              "redact",
+              "warn",
+              "allow"
+            ],
+            "default": "redact",
+            "description": "How PII detections are handled"
+          },
+          "injection_threshold": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "default": 0.7,
+            "description": "Prompt injection score threshold (0.0–1.0). Requests above are blocked"
+          },
+          "context_injection_threshold": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "default": 0.7,
+            "description": "Context injection score threshold (0.0–1.0)"
+          },
+          "allowed_providers": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "LLM providers this agent may use (empty = all)"
+          },
+          "allowed_models": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Specific models allowed (empty = all)"
+          },
+          "denied_models": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Models explicitly blocked"
+          },
+          "max_tokens_per_request": {
+            "type": "integer",
+            "description": "Maximum input tokens per request"
+          },
+          "max_requests_per_minute": {
+            "type": "integer",
+            "description": "Rate limit (requests per minute)"
+          },
+          "max_requests_per_day": {
+            "type": "integer",
+            "description": "Rate limit (requests per day)"
+          },
+          "daily_budget_usd": {
+            "type": "number",
+            "description": "Daily LLM spend cap in USD (0 = unlimited)"
+          },
+          "enable_secret_redaction": {
+            "type": "boolean",
+            "default": true,
+            "description": "Whether vault secrets are redacted from prompts/responses"
+          },
+          "enable_response_filtering": {
+            "type": "boolean",
+            "default": true,
+            "description": "Whether response credential scanning is active"
           }
         }
       },

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: 1Claw API
-  version: 2.3.0
+  version: 2.4.0
   description: |
     Secure secret management for AI agents. Provides vaults, secrets,
     policy-based access control, agent identity, Intents API,
@@ -21,6 +21,9 @@ servers:
   - url: https://shroud.1claw.xyz
     description: Shroud TEE Proxy (Intents API + LLM proxy)
 
+x-agentcash-guidance:
+  llmsTxtUrl: https://1claw.xyz/llms.txt
+
 security:
   - BearerAuth: []
 
@@ -745,6 +748,12 @@ paths:
       tags: [Secrets]
       summary: Store or update a secret
       operationId: putSecret
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.0075"
       parameters:
         - $ref: "#/components/parameters/VaultId"
         - $ref: "#/components/parameters/SecretPath"
@@ -763,10 +772,18 @@ paths:
                 $ref: "#/components/schemas/SecretMetadataResponse"
         "400":
           $ref: "#/components/responses/BadRequest"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
     get:
       tags: [Secrets]
       summary: Retrieve a decrypted secret
       operationId: getSecret
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.0015"
       parameters:
         - $ref: "#/components/parameters/VaultId"
         - $ref: "#/components/parameters/SecretPath"
@@ -1047,6 +1064,11 @@ paths:
     post:
       tags: [Transactions]
       summary: Submit a transaction for signing
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: quote
       description: |
         Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).
         Duplicate requests with the same key within 24 hours return the cached transaction response
@@ -1079,6 +1101,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/TransactionResponse"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
         "403":
           $ref: "#/components/responses/Forbidden"
         "409":
@@ -1137,6 +1161,12 @@ paths:
       tags: [Transactions]
       summary: Simulate a transaction via Tenderly
       operationId: simulateTransaction
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.075"
       parameters:
         - $ref: "#/components/parameters/AgentId"
       requestBody:
@@ -1156,12 +1186,20 @@ paths:
           $ref: "#/components/responses/BadRequest"
         "403":
           $ref: "#/components/responses/Forbidden"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
 
   /v1/agents/{agent_id}/transactions/simulate-bundle:
     post:
       tags: [Transactions]
       summary: Simulate a bundle of transactions
       operationId: simulateBundle
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.075"
       parameters:
         - $ref: "#/components/parameters/AgentId"
       requestBody:
@@ -1179,6 +1217,8 @@ paths:
                 $ref: "#/components/schemas/BundleSimulationResponse"
         "400":
           $ref: "#/components/responses/BadRequest"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
 
   # ---------------------------------------------------------------------------
   # Chains
@@ -1300,6 +1340,12 @@ paths:
       tags: [Sharing]
       summary: Create a share link for a secret
       operationId: createShare
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.003"
       parameters:
         - name: secret_id
           in: path
@@ -1320,6 +1366,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ShareResponse"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
         "404":
           $ref: "#/components/responses/NotFound"
 
@@ -1329,6 +1377,12 @@ paths:
       summary: Access a shared secret
       operationId: accessShare
       security: []
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.0015"
       parameters:
         - name: share_id
           in: path
@@ -1671,6 +1725,12 @@ paths:
       tags: [Audit]
       summary: Query audit events
       operationId: queryAuditEvents
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.0008"
       parameters:
         - name: resource_id
           in: query
@@ -1711,6 +1771,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/AuditEventsResponse"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
 
   # ---------------------------------------------------------------------------
   # Security (IP Rules)
@@ -2731,6 +2793,12 @@ components:
         oidc_client_id:
           type: string
           description: OIDC client ID (required for oidc_client_credentials auth)
+        shroud_enabled:
+          type: boolean
+          default: false
+          description: Enable Shroud LLM Proxy for this agent
+        shroud_config:
+          $ref: '#/components/schemas/ShroudConfig'
 
     UpdateAgentRequest:
       type: object
@@ -2768,10 +2836,15 @@ components:
           items:
             type: string
             format: uuid
+        shroud_enabled:
+          type: boolean
+          description: Enable/disable Shroud LLM Proxy
+        shroud_config:
+          $ref: '#/components/schemas/ShroudConfig'
 
     AgentResponse:
       type: object
-      required: [id, name, auth_method, is_active, intents_api_enabled, created_at]
+      required: [id, name, auth_method, is_active, intents_api_enabled, shroud_enabled, created_at]
       properties:
         id:
           type: string
@@ -2826,6 +2899,11 @@ components:
         ecdh_public_key:
           type: string
           description: P-256 ECDH public key (base64 SEC1 uncompressed point, auto-generated at creation)
+        shroud_enabled:
+          type: boolean
+          description: Whether this agent routes LLM traffic through the Shroud TEE proxy
+        shroud_config:
+          $ref: '#/components/schemas/ShroudConfig'
         created_at:
           type: string
           format: date-time
@@ -2875,6 +2953,68 @@ components:
         ecdh_public_key:
           type: string
           description: P-256 ECDH public key (base64 SEC1 uncompressed point)
+        shroud_enabled:
+          type: boolean
+          description: Whether this agent routes LLM traffic through the Shroud TEE proxy
+        shroud_config:
+          $ref: '#/components/schemas/ShroudConfig'
+
+    ShroudConfig:
+      type: object
+      description: Per-agent Shroud LLM Proxy configuration
+      properties:
+        pii_policy:
+          type: string
+          enum: [block, redact, warn, allow]
+          default: redact
+          description: How PII detections are handled
+        injection_threshold:
+          type: number
+          minimum: 0
+          maximum: 1
+          default: 0.7
+          description: Prompt injection score threshold (0.0–1.0). Requests above are blocked
+        context_injection_threshold:
+          type: number
+          minimum: 0
+          maximum: 1
+          default: 0.7
+          description: Context injection score threshold (0.0–1.0)
+        allowed_providers:
+          type: array
+          items:
+            type: string
+          description: LLM providers this agent may use (empty = all)
+        allowed_models:
+          type: array
+          items:
+            type: string
+          description: Specific models allowed (empty = all)
+        denied_models:
+          type: array
+          items:
+            type: string
+          description: Models explicitly blocked
+        max_tokens_per_request:
+          type: integer
+          description: Maximum input tokens per request
+        max_requests_per_minute:
+          type: integer
+          description: Rate limit (requests per minute)
+        max_requests_per_day:
+          type: integer
+          description: Rate limit (requests per day)
+        daily_budget_usd:
+          type: number
+          description: Daily LLM spend cap in USD (0 = unlimited)
+        enable_secret_redaction:
+          type: boolean
+          default: true
+          description: Whether vault secrets are redacted from prompts/responses
+        enable_response_filtering:
+          type: boolean
+          default: true
+          description: Whether response credential scanning is active
 
     AgentCreatedResponse:
       type: object

package/package.json

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