@1claw/openapi-spec 0.51.0 → 0.53.0

package/README.md

@@ -40,7 +40,20 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.48.0)
+## What's in the spec (v0.52.0)
+
+### Environment Variables (v0.51)
+- **Per-key env vars** — `GET/POST /v1/vaults/{id}/env-vars`, `GET/PATCH/DELETE .../{key}`, `GET .../resolve` with three-tier precedence (org shared < vault < branch override)
+- **Vault environments** — `GET/POST /v1/vaults/{id}/environments`, `DELETE .../{slug}` (built-in + tier-gated custom)
+- **Org shared vars** — `GET/POST /v1/org/env-vars`, link/unlink to vaults
+- **Sensitive vars** — write-only after creation; org setting `env.require_sensitive_prod`
+- **Runtime injection** — resolved vars merged into Cloud Runtime container env at start/rebuild
+
+### Agent Environment Tagging (v0.52)
+- **Agent fields** — `environment`, `environment_locked`, `env_auto_resolve`, `per_environment_guardrails` on create/update/response schemas
+- **JWT claim** — Agent tokens include `environment` when the agent has a tag
+- **Policy conditions** — `environment_in` array in built-in policy `conditions` JSON
+- **Env var resolution** — `GET /v1/vaults/{id}/env-vars/resolve` accepts optional `environment`; auto-fills from agent tag when `env_auto_resolve` is true
 
 ### Cedar/OPA Enforcement v2 (v0.48)
 - **Policy backend** — `GET/PATCH /v1/org/settings/policy-backend`, `GET /v1/org/policy-shadow-report`

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.51.0",
+    "version": "0.53.0",
     "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\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.xyz"
@@ -3107,7 +3107,7 @@
           "Environment Variables"
         ],
         "summary": "Resolve environment variables",
-        "description": "Resolve the final KEY=VALUE set for an environment with full precedence (shared < vault < branch override).",
+        "description": "Resolve the final KEY=VALUE set for an environment with full precedence (shared < vault < branch override).\nWhen the caller is an agent with `env_auto_resolve: true`, the `environment` query parameter may be omitted —\nthe server uses the agent's tagged environment from the JWT. Org setting `env.enforce_agent_environment_scope`\nblocks agents from resolving vars outside their tagged environment.\n",
         "operationId": "resolveEnvVars",
         "parameters": [
           {
@@ -3116,17 +3116,19 @@
           {
             "name": "environment",
             "in": "query",
-            "required": true,
+            "required": false,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "Target environment (production, preview, development, or custom). Required for human callers; optional for agents with env_auto_resolve when the agent has an environment tag."
           },
           {
             "name": "git_branch",
             "in": "query",
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "Optional git branch for preview branch overrides"
           }
         ],
         "responses": {
@@ -6353,6 +6355,55 @@
         }
       }
     },
+    "/v1/audit/verify": {
+      "get": {
+        "tags": [
+          "Audit"
+        ],
+        "summary": "Verify audit hash chain integrity",
+        "operationId": "verifyAuditChain",
+        "description": "Verifies the HMAC-SHA256 integrity hash chain for audit events in the\ncalling organization. Returns whether the chain is valid, how many\nevents were verified, and the point of first break (if any).\n",
+        "parameters": [
+          {
+            "name": "from",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          {
+            "name": "to",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 1000,
+              "maximum": 10000
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Chain verification result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuditVerifyResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/security/ip-rules": {
       "get": {
         "tags": [
@@ -8380,6 +8431,34 @@
         }
       }
     },
+    "/v1/shroud/attestation": {
+      "get": {
+        "tags": [
+          "Shroud"
+        ],
+        "summary": "TEE attestation proof (public)",
+        "operationId": "getShroudAttestation",
+        "security": [],
+        "description": "Public endpoint returning the TEE attestation proof for Shroud.\nReturns the GCE Confidential VM identity token and image hash so\ncustomers can verify Shroud is running inside a Confidential VM\nbefore signing contracts. Served from shroud.1claw.xyz.\n",
+        "servers": [
+          {
+            "url": "https://shroud.1claw.xyz"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Attestation proof",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ShroudAttestationResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/shroud/activity": {
       "get": {
         "tags": [
@@ -17419,6 +17498,16 @@
           },
           "tx_conditions": {
             "$ref": "#/components/schemas/TxConditions"
+          },
+          "approval_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Optional completed approval ID for control-plane consensus bypass. When control-plane consensus policies match, resubmit with this field after the approval has been executed.\n"
+          },
+          "policy_schema_version": {
+            "type": "integer",
+            "default": 2,
+            "description": "Policy schema version. Version 1 = legacy field-matching only.\nVersion 2 = expression engine support in tx_conditions.\n"
           }
         }
       },
@@ -17461,6 +17550,11 @@
           },
           "tx_conditions": {
             "$ref": "#/components/schemas/TxConditions"
+          },
+          "approval_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Optional completed approval ID for control-plane consensus bypass.\n"
           }
         }
       },
@@ -17539,6 +17633,10 @@
           },
           "tx_conditions": {
             "$ref": "#/components/schemas/TxConditions"
+          },
+          "policy_schema_version": {
+            "type": "integer",
+            "description": "Policy schema version (1 = legacy, 2 = expression engine)"
           }
         }
       },
@@ -17789,6 +17887,25 @@
             "format": "date-time",
             "nullable": true,
             "description": "Optional expiration time for the agent's API key."
+          },
+          "environment": {
+            "type": "string",
+            "description": "Named environment for this agent (production, preview, development, or custom)."
+          },
+          "environment_locked": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, the environment tag cannot be changed after creation."
+          },
+          "env_auto_resolve": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, env var resolve endpoints auto-fill environment from this agent's tag."
+          },
+          "approval_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Optional completed approval ID for control-plane consensus bypass when creating an agent under a control-plane governance policy.\n"
           }
         }
       },
@@ -17976,6 +18093,24 @@
             "format": "date-time",
             "nullable": true,
             "description": "Optional expiration time for the agent's API key. Set to null to clear."
+          },
+          "environment": {
+            "type": "string",
+            "nullable": true,
+            "description": "Named environment for this agent (production, preview, development, or custom)."
+          },
+          "environment_locked": {
+            "type": "boolean",
+            "description": "When true, the environment tag cannot be changed after creation."
+          },
+          "env_auto_resolve": {
+            "type": "boolean",
+            "description": "When true, env var resolve endpoints auto-fill environment from this agent's tag."
+          },
+          "per_environment_guardrails": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Per-environment guardrail overrides keyed by environment slug."
           }
         }
       },
@@ -18279,6 +18414,24 @@
             "items": {
               "$ref": "#/components/schemas/AgentSmartAccountResponse"
             }
+          },
+          "environment": {
+            "type": "string",
+            "nullable": true,
+            "description": "Named environment this agent belongs to (production, preview, development, or custom)."
+          },
+          "environment_locked": {
+            "type": "boolean",
+            "description": "When true, the environment tag is locked and cannot be changed."
+          },
+          "env_auto_resolve": {
+            "type": "boolean",
+            "description": "When true, env var resolve endpoints auto-fill environment from this agent's tag."
+          },
+          "per_environment_guardrails": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Per-environment guardrail overrides keyed by environment slug."
           }
         }
       },
@@ -20887,6 +21040,99 @@
           }
         }
       },
+      "AuditVerifyResponse": {
+        "type": "object",
+        "required": [
+          "chain_valid",
+          "events_verified",
+          "events_checked",
+          "scheme"
+        ],
+        "properties": {
+          "chain_valid": {
+            "type": "boolean",
+            "description": "Whether the integrity hash chain is unbroken"
+          },
+          "events_verified": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Number of events with valid integrity hashes"
+          },
+          "events_checked": {
+            "type": "integer",
+            "description": "Total events examined"
+          },
+          "broken_at_event_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true,
+            "description": "First event where chain integrity broke (null if valid)"
+          },
+          "scheme": {
+            "type": "object",
+            "properties": {
+              "algorithm": {
+                "type": "string",
+                "example": "HMAC-SHA256"
+              },
+              "chain_structure": {
+                "type": "string"
+              },
+              "hash_field": {
+                "type": "string"
+              },
+              "link_field": {
+                "type": "string"
+              },
+              "documentation": {
+                "type": "string",
+                "format": "uri"
+              }
+            }
+          }
+        }
+      },
+      "ShroudAttestationResponse": {
+        "type": "object",
+        "required": [
+          "attested",
+          "image_hash",
+          "identity_token",
+          "verification"
+        ],
+        "properties": {
+          "attested": {
+            "type": "boolean",
+            "description": "Whether TEE attestation was successfully fetched"
+          },
+          "image_hash": {
+            "type": "string",
+            "description": "Confidential VM image hash (compare against published Docker digest)"
+          },
+          "identity_token": {
+            "type": "string",
+            "description": "GCE metadata identity JWT (verify against Google public keys)"
+          },
+          "verification": {
+            "type": "object",
+            "properties": {
+              "steps": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "google_certs_url": {
+                "type": "string",
+                "format": "uri"
+              },
+              "expected_audience": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
       "AuditEvent": {
         "type": "object",
         "properties": {
@@ -26738,6 +26984,11 @@
             "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"
+          },
+          "expression": {
+            "type": "string",
+            "maxLength": 1024,
+            "description": "Mini expression DSL for policy conditions (schema version 2+).\nReferences transaction context fields (chain, value_wei, to_address,\nfunction_selector, etc.) with boolean operators. Fail-closed on parse\nor evaluation errors. Example: `chain == 'ethereum' && value_wei > 1000000000000000000`\n"
           }
         }
       },
@@ -26827,6 +27078,20 @@
           "always": {
             "type": "boolean",
             "description": "When true, this entry always matches regardless of other fields"
+          },
+          "action_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Control-plane actions to match (e.g. policy.create, signing_key.export)"
+          },
+          "action_kind_in": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Version-agnostic action kind groups (e.g. signing_key.*, policy.*, member.*)\n"
           }
         }
       },
@@ -27026,6 +27291,28 @@
                 "description": "Control-plane actions to match, e.g. policy.create, policy.update,\npolicy.delete, signing_key.export, member.role_change, member.remove\n"
               }
             }
+          },
+          {
+            "type": "object",
+            "required": [
+              "type",
+              "action_kinds"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "action_kind_in"
+                ]
+              },
+              "action_kinds": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Version-agnostic action kind groups, e.g. signing_key.*, policy.*, member.*\n"
+              }
+            }
           }
         ]
       },

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 0.51.0
+    version: 0.53.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -2041,19 +2041,25 @@ paths:
         get:
             tags: [Environment Variables]
             summary: Resolve environment variables
-            description: Resolve the final KEY=VALUE set for an environment with full precedence (shared < vault < branch override).
+            description: |
+                Resolve the final KEY=VALUE set for an environment with full precedence (shared < vault < branch override).
+                When the caller is an agent with `env_auto_resolve: true`, the `environment` query parameter may be omitted —
+                the server uses the agent's tagged environment from the JWT. Org setting `env.enforce_agent_environment_scope`
+                blocks agents from resolving vars outside their tagged environment.
             operationId: resolveEnvVars
             parameters:
                 - $ref: "#/components/parameters/VaultId"
                 - name: environment
                   in: query
-                  required: true
+                  required: false
                   schema:
                       type: string
+                  description: Target environment (production, preview, development, or custom). Required for human callers; optional for agents with env_auto_resolve when the agent has an environment tag.
                 - name: git_branch
                   in: query
                   schema:
                       type: string
+                  description: Optional git branch for preview branch overrides
             responses:
                 "200":
                     description: Resolved environment variables
@@ -4123,6 +4129,40 @@ paths:
                 "402":
                     $ref: "#/components/responses/PaymentRequired"
 
+    /v1/audit/verify:
+        get:
+            tags: [Audit]
+            summary: Verify audit hash chain integrity
+            operationId: verifyAuditChain
+            description: |
+                Verifies the HMAC-SHA256 integrity hash chain for audit events in the
+                calling organization. Returns whether the chain is valid, how many
+                events were verified, and the point of first break (if any).
+            parameters:
+                - name: from
+                  in: query
+                  schema:
+                      type: string
+                      format: date-time
+                - name: to
+                  in: query
+                  schema:
+                      type: string
+                      format: date-time
+                - name: limit
+                  in: query
+                  schema:
+                      type: integer
+                      default: 1000
+                      maximum: 10000
+            responses:
+                "200":
+                    description: Chain verification result
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AuditVerifyResponse"
+
     # ---------------------------------------------------------------------------
     # Security (IP Rules)
     # ---------------------------------------------------------------------------
@@ -5422,6 +5462,27 @@ paths:
 
     # --- Shroud Activity ---
 
+    /v1/shroud/attestation:
+        get:
+            tags: [Shroud]
+            summary: TEE attestation proof (public)
+            operationId: getShroudAttestation
+            security: []
+            description: |
+                Public endpoint returning the TEE attestation proof for Shroud.
+                Returns the GCE Confidential VM identity token and image hash so
+                customers can verify Shroud is running inside a Confidential VM
+                before signing contracts. Served from shroud.1claw.xyz.
+            servers:
+                - url: https://shroud.1claw.xyz
+            responses:
+                "200":
+                    description: Attestation proof
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ShroudAttestationResponse"
+
     /v1/shroud/activity:
         get:
             tags: [Shroud]
@@ -11174,6 +11235,19 @@ components:
                     $ref: "#/components/schemas/ConsensusTrigger"
                 tx_conditions:
                     $ref: "#/components/schemas/TxConditions"
+                approval_id:
+                    type: string
+                    format: uuid
+                    description: >
+                        Optional completed approval ID for control-plane consensus bypass.
+                        When control-plane consensus policies match, resubmit with this
+                        field after the approval has been executed.
+                policy_schema_version:
+                    type: integer
+                    default: 2
+                    description: |
+                        Policy schema version. Version 1 = legacy field-matching only.
+                        Version 2 = expression engine support in tx_conditions.
 
         UpdatePolicyRequest:
             type: object
@@ -11203,6 +11277,11 @@ components:
                     $ref: "#/components/schemas/ConsensusTrigger"
                 tx_conditions:
                     $ref: "#/components/schemas/TxConditions"
+                approval_id:
+                    type: string
+                    format: uuid
+                    description: >
+                        Optional completed approval ID for control-plane consensus bypass.
 
         PolicyResponse:
             type: object
@@ -11261,6 +11340,9 @@ components:
                     $ref: "#/components/schemas/ConsensusTrigger"
                 tx_conditions:
                     $ref: "#/components/schemas/TxConditions"
+                policy_schema_version:
+                    type: integer
+                    description: Policy schema version (1 = legacy, 2 = expression engine)
 
         PolicyListResponse:
             type: object
@@ -11457,6 +11539,23 @@ components:
                     format: date-time
                     nullable: true
                     description: Optional expiration time for the agent's API key.
+                environment:
+                    type: string
+                    description: Named environment for this agent (production, preview, development, or custom).
+                environment_locked:
+                    type: boolean
+                    default: false
+                    description: When true, the environment tag cannot be changed after creation.
+                env_auto_resolve:
+                    type: boolean
+                    default: false
+                    description: When true, env var resolve endpoints auto-fill environment from this agent's tag.
+                approval_id:
+                    type: string
+                    format: uuid
+                    description: >
+                        Optional completed approval ID for control-plane consensus bypass
+                        when creating an agent under a control-plane governance policy.
 
         UpdateAgentRequest:
             type: object
@@ -11609,6 +11708,20 @@ components:
                     format: date-time
                     nullable: true
                     description: Optional expiration time for the agent's API key. Set to null to clear.
+                environment:
+                    type: string
+                    nullable: true
+                    description: Named environment for this agent (production, preview, development, or custom).
+                environment_locked:
+                    type: boolean
+                    description: When true, the environment tag cannot be changed after creation.
+                env_auto_resolve:
+                    type: boolean
+                    description: When true, env var resolve endpoints auto-fill environment from this agent's tag.
+                per_environment_guardrails:
+                    type: object
+                    additionalProperties: true
+                    description: Per-environment guardrail overrides keyed by environment slug.
 
         AgentResponse:
             type: object
@@ -11837,6 +11950,20 @@ components:
                     description: Multi-chain; one Safe per chain
                     items:
                         $ref: "#/components/schemas/AgentSmartAccountResponse"
+                environment:
+                    type: string
+                    nullable: true
+                    description: Named environment this agent belongs to (production, preview, development, or custom).
+                environment_locked:
+                    type: boolean
+                    description: When true, the environment tag is locked and cannot be changed.
+                env_auto_resolve:
+                    type: boolean
+                    description: When true, env var resolve endpoints auto-fill environment from this agent's tag.
+                per_environment_guardrails:
+                    type: object
+                    additionalProperties: true
+                    description: Per-environment guardrail overrides keyed by environment slug.
 
         KnownToken:
             type: object
@@ -13660,6 +13787,67 @@ components:
                 count:
                     type: integer
 
+        AuditVerifyResponse:
+            type: object
+            required: [chain_valid, events_verified, events_checked, scheme]
+            properties:
+                chain_valid:
+                    type: boolean
+                    description: Whether the integrity hash chain is unbroken
+                events_verified:
+                    type: integer
+                    format: int64
+                    description: Number of events with valid integrity hashes
+                events_checked:
+                    type: integer
+                    description: Total events examined
+                broken_at_event_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                    description: First event where chain integrity broke (null if valid)
+                scheme:
+                    type: object
+                    properties:
+                        algorithm:
+                            type: string
+                            example: HMAC-SHA256
+                        chain_structure:
+                            type: string
+                        hash_field:
+                            type: string
+                        link_field:
+                            type: string
+                        documentation:
+                            type: string
+                            format: uri
+
+        ShroudAttestationResponse:
+            type: object
+            required: [attested, image_hash, identity_token, verification]
+            properties:
+                attested:
+                    type: boolean
+                    description: Whether TEE attestation was successfully fetched
+                image_hash:
+                    type: string
+                    description: Confidential VM image hash (compare against published Docker digest)
+                identity_token:
+                    type: string
+                    description: GCE metadata identity JWT (verify against Google public keys)
+                verification:
+                    type: object
+                    properties:
+                        steps:
+                            type: array
+                            items:
+                                type: string
+                        google_certs_url:
+                            type: string
+                            format: uri
+                        expected_audience:
+                            type: string
+
         AuditEvent:
             type: object
             properties:
@@ -17613,6 +17801,14 @@ components:
                         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.
+                expression:
+                    type: string
+                    maxLength: 1024
+                    description: |
+                        Mini expression DSL for policy conditions (schema version 2+).
+                        References transaction context fields (chain, value_wei, to_address,
+                        function_selector, etc.) with boolean operators. Fail-closed on parse
+                        or evaluation errors. Example: `chain == 'ethereum' && value_wei > 1000000000000000000`
 
         ConsensusTrigger:
             type: object
@@ -17686,6 +17882,17 @@ components:
                 always:
                     type: boolean
                     description: When true, this entry always matches regardless of other fields
+                action_in:
+                    type: array
+                    items:
+                        type: string
+                    description: Control-plane actions to match (e.g. policy.create, signing_key.export)
+                action_kind_in:
+                    type: array
+                    items:
+                        type: string
+                    description: |
+                        Version-agnostic action kind groups (e.g. signing_key.*, policy.*, member.*)
 
         TimeWindow:
             type: object
@@ -17798,6 +18005,18 @@ components:
                           description: |
                               Control-plane actions to match, e.g. policy.create, policy.update,
                               policy.delete, signing_key.export, member.role_change, member.remove
+                - type: object
+                  required: [type, action_kinds]
+                  properties:
+                      type:
+                          type: string
+                          enum: [action_kind_in]
+                      action_kinds:
+                          type: array
+                          items:
+                              type: string
+                          description: |
+                              Version-agnostic action kind groups, e.g. signing_key.*, policy.*, member.*
 
         ApprovalRequirement:
             type: object

package/package.json

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