@1claw/openapi-spec 0.17.0 → 0.19.0

package/README.md

@@ -40,14 +40,14 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.17.x)
+## What's in the spec (v0.19.0)
 
 - **Auth — agent JWT** — `POST /v1/auth/agent-token` documents optional JWT claim **`shroud_config`** when the agent has Shroud enabled (mirrors DB; consumed by Shroud PolicyEngine on LLM requests). Re-exchange after changing agent Shroud settings.
 - **Auth — password reset** — `POST /v1/auth/forgot-password`, `POST /v1/auth/reset-password` (public; anti-enumeration on forgot)
 - **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing` (`LlmTokenBillingStatus`: `enabled`, `subscription_status`, optional `credit_balance`, optional `billing_cycle_usage` with `metered_lines[]`), `POST .../subscribe`, `POST .../disable` (Stripe AI Gateway add-on; optional org feature)
 - **Treasury** — Safe multisig treasuries: `POST/GET /v1/treasury`, `GET/PATCH/DELETE /v1/treasury/{id}`, signers, agent access requests (`requests[]` on list)
-- **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking
-- **Secrets** — CRUD, versioning, CMEK-encrypted flag
+- **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking, MPC enable/disable (`POST /v1/vaults/{id}/mpc`, `DELETE /v1/vaults/{id}/mpc`)
+- **Secrets** — CRUD, versioning, CMEK-encrypted flag, `client_share` in responses (MPC vaults)
 - **Agents** — CRUD with `auth_method` (api_key, mtls, oidc_client_credentials), auto-generated SSH keypairs, `token_ttl_seconds`, `vault_ids`, Intents API, transaction guardrails
 - **Policies** — Glob-based access control
 - **Sharing** — Links, user/agent shares, accept/decline

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.7.0",
+    "version": "2.9.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"
@@ -1221,6 +1221,52 @@
         }
       }
     },
+    "/v1/vaults/{vault_id}/mpc": {
+      "post": {
+        "tags": [
+          "Vaults"
+        ],
+        "summary": "Enable MPC custody on a vault",
+        "operationId": "enableMpc",
+        "description": "Enable MPC custody on an existing vault. Requires Business or Enterprise plan.\nSplits secret encryption keys across multiple providers using the specified\ncustody mode (e.g. 2-of-2, 2-of-3).\n",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/VaultId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EnableMpcRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "MPC custody enabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/VaultResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/vaults/{vault_id}/secrets": {
       "get": {
         "tags": [
@@ -1299,7 +1345,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/SecretMetadataResponse"
+                  "$ref": "#/components/schemas/SecretCreatedResponse"
                 }
               }
             }
@@ -1334,6 +1380,15 @@
           },
           {
             "$ref": "#/components/parameters/SecretPath"
+          },
+          {
+            "name": "x-client-share",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Base64-encoded client key share for MPC 2-of-2 vaults. Required when the vault uses 2-of-2 MPC custody."
           }
         ],
         "responses": {
@@ -1379,6 +1434,160 @@
         }
       }
     },
+    "/v1/vaults/{vault_id}/secret-versions/{path}": {
+      "get": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "List all versions of a secret",
+        "operationId": "listSecretVersions",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/VaultId"
+          },
+          {
+            "$ref": "#/components/parameters/SecretPath"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Version list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecretVersionListResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/vaults/{vault_id}/secret-version/{path}/{version}": {
+      "get": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "Retrieve a specific version of a secret",
+        "operationId": "getSecretVersion",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/VaultId"
+          },
+          {
+            "$ref": "#/components/parameters/SecretPath"
+          },
+          {
+            "name": "version",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Decrypted secret value at the specified version",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecretResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "410": {
+            "description": "Version has been disabled or expired"
+          }
+        }
+      }
+    },
+    "/v1/vaults/{vault_id}/secret-version/{path}/{version}/disable": {
+      "post": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "Disable a specific secret version",
+        "operationId": "disableSecretVersion",
+        "description": "Disables a version so it can no longer be read. The version is\nretained for audit purposes but returns 410 on read attempts.\n",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/VaultId"
+          },
+          {
+            "$ref": "#/components/parameters/SecretPath"
+          },
+          {
+            "name": "version",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Version disabled"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/vaults/{vault_id}/secret-rotate/{path}": {
+      "post": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "Server-side secret rotation",
+        "operationId": "rotateSecret",
+        "description": "Generates a cryptographically random value and stores it as a new\nversion of the secret. The previous version is preserved in history.\nRequires rotate or write permission.\n",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/VaultId"
+          },
+          {
+            "$ref": "#/components/parameters/SecretPath"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RotateSecretRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "New version created with server-generated value",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecretCreatedResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/vaults/{vault_id}/policies": {
       "post": {
         "tags": [
@@ -4133,6 +4342,55 @@
           }
         }
       }
+    },
+    "/v1/shroud/threat-summary": {
+      "get": {
+        "tags": [
+          "Shroud"
+        ],
+        "summary": "Shroud threat analytics summary",
+        "description": "Aggregated threat metrics for the organization from `shroud_activity` (detectors, blocked counts, recent flagged requests). Query `period` selects the window; the previous window of equal length is used for request volume trend.\n",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "period",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "1h",
+                "24h",
+                "7d",
+                "30d"
+              ],
+              "default": "24h"
+            },
+            "description": "Rolling window ending now"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Threat summary",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ShroudThreatSummary"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid period"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -4810,6 +5068,10 @@
           },
           "description": {
             "type": "string"
+          },
+          "mpc_custody": {
+            "type": "string",
+            "description": "MPC custody mode to enable at creation (e.g. \"2-of-2\", \"2-of-3\")"
           }
         }
       },
@@ -4848,6 +5110,21 @@
           "cmek_fingerprint": {
             "type": "string",
             "description": "SHA-256 fingerprint of the CMEK key (64 hex chars)"
+          },
+          "mpc_custody": {
+            "type": "string",
+            "description": "MPC custody mode (e.g. \"2-of-2\", \"2-of-3\"), absent when MPC is not enabled"
+          },
+          "mpc_threshold": {
+            "type": "integer",
+            "description": "Number of shares required to reconstruct the key"
+          },
+          "mpc_providers": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "List of MPC share providers (e.g. [\"server\", \"client\"])"
           }
         }
       },
@@ -4943,6 +5220,18 @@
           }
         }
       },
+      "EnableMpcRequest": {
+        "type": "object",
+        "required": [
+          "mpc_custody"
+        ],
+        "properties": {
+          "mpc_custody": {
+            "type": "string",
+            "description": "MPC custody mode (e.g. \"2-of-2\", \"2-of-3\")"
+          }
+        }
+      },
       "PutSecretRequest": {
         "type": "object",
         "required": [
@@ -5008,6 +5297,52 @@
           "expires_at": {
             "type": "string",
             "format": "date-time"
+          },
+          "is_disabled": {
+            "type": "boolean",
+            "description": "Whether this version has been disabled (retained for audit but unreadable)"
+          }
+        }
+      },
+      "SecretCreatedResponse": {
+        "description": "Returned when a secret is created or updated. Extends SecretMetadataResponse with an optional client_share for MPC vaults.",
+        "type": "object",
+        "required": [
+          "id",
+          "path",
+          "type",
+          "version",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "path": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "version": {
+            "type": "integer"
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "client_share": {
+            "type": "string",
+            "description": "Base64-encoded client key share. Returned only for MPC 2-of-2 vaults. The client must store this share securely — it is not persisted server-side."
           }
         }
       },
@@ -5070,6 +5405,42 @@
           }
         }
       },
+      "SecretVersionListResponse": {
+        "type": "object",
+        "properties": {
+          "versions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SecretMetadataResponse"
+            }
+          }
+        }
+      },
+      "RotateSecretRequest": {
+        "type": "object",
+        "properties": {
+          "length": {
+            "type": "integer",
+            "minimum": 8,
+            "maximum": 1024,
+            "description": "Length of the generated value (default 32)"
+          },
+          "charset": {
+            "type": "string",
+            "enum": [
+              "hex",
+              "base64",
+              "alphanumeric",
+              "ascii"
+            ],
+            "description": "Character set for the generated value (default hex)"
+          },
+          "type": {
+            "type": "string",
+            "description": "Override the secret type (defaults to existing secret's type)"
+          }
+        }
+      },
       "CreatePolicyRequest": {
         "type": "object",
         "required": [
@@ -7934,6 +8305,108 @@
           }
         }
       },
+      "ShroudThreatSummary": {
+        "type": "object",
+        "properties": {
+          "total_requests": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "total_requests_prev": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "blocked_requests": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "detectors_triggered": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "active_agents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "detectors": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ShroudDetectorStats"
+            }
+          },
+          "flagged_requests": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ShroudFlaggedRequest"
+            }
+          }
+        }
+      },
+      "ShroudDetectorStats": {
+        "type": "object",
+        "properties": {
+          "detector": {
+            "type": "string"
+          },
+          "detections": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "blocks": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "actions": {
+            "type": "object",
+            "properties": {
+              "blocked": {
+                "type": "integer",
+                "format": "int64"
+              },
+              "warned": {
+                "type": "integer",
+                "format": "int64"
+              },
+              "logged": {
+                "type": "integer",
+                "format": "int64"
+              }
+            }
+          }
+        }
+      },
+      "ShroudFlaggedRequest": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "agent_id": {
+            "type": "string"
+          },
+          "agent_name": {
+            "type": "string"
+          },
+          "score": {
+            "type": "number"
+          },
+          "reason": {
+            "type": "string"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "blocked",
+              "warned",
+              "logged"
+            ]
+          }
+        }
+      },
       "HealthResponse": {
         "type": "object",
         "properties": {

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.7.0
+    version: 2.9.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -802,6 +802,41 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    # ---------------------------------------------------------------------------
+    # MPC
+    # ---------------------------------------------------------------------------
+
+    /v1/vaults/{vault_id}/mpc:
+        post:
+            tags: [Vaults]
+            summary: Enable MPC custody on a vault
+            operationId: enableMpc
+            description: |
+                Enable MPC custody on an existing vault. Requires Business or Enterprise plan.
+                Splits secret encryption keys across multiple providers using the specified
+                custody mode (e.g. 2-of-2, 2-of-3).
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/EnableMpcRequest"
+            responses:
+                "200":
+                    description: MPC custody enabled
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/VaultResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Secrets
     # ---------------------------------------------------------------------------
@@ -854,7 +889,7 @@ paths:
                     content:
                         application/json:
                             schema:
-                                $ref: "#/components/schemas/SecretMetadataResponse"
+                                $ref: "#/components/schemas/SecretCreatedResponse"
                 "400":
                     $ref: "#/components/responses/BadRequest"
                 "402":
@@ -872,6 +907,12 @@ paths:
             parameters:
                 - $ref: "#/components/parameters/VaultId"
                 - $ref: "#/components/parameters/SecretPath"
+                - name: x-client-share
+                  in: header
+                  required: false
+                  schema:
+                      type: string
+                  description: Base64-encoded client key share for MPC 2-of-2 vaults. Required when the vault uses 2-of-2 MPC custody.
             responses:
                 "200":
                     description: Decrypted secret value
@@ -896,6 +937,100 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/vaults/{vault_id}/secret-versions/{path}:
+        get:
+            tags: [Secrets]
+            summary: List all versions of a secret
+            operationId: listSecretVersions
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - $ref: "#/components/parameters/SecretPath"
+            responses:
+                "200":
+                    description: Version list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SecretVersionListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/vaults/{vault_id}/secret-version/{path}/{version}:
+        get:
+            tags: [Secrets]
+            summary: Retrieve a specific version of a secret
+            operationId: getSecretVersion
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - $ref: "#/components/parameters/SecretPath"
+                - name: version
+                  in: path
+                  required: true
+                  schema:
+                      type: integer
+            responses:
+                "200":
+                    description: Decrypted secret value at the specified version
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SecretResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "410":
+                    description: Version has been disabled or expired
+
+    /v1/vaults/{vault_id}/secret-version/{path}/{version}/disable:
+        post:
+            tags: [Secrets]
+            summary: Disable a specific secret version
+            operationId: disableSecretVersion
+            description: |
+                Disables a version so it can no longer be read. The version is
+                retained for audit purposes but returns 410 on read attempts.
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - $ref: "#/components/parameters/SecretPath"
+                - name: version
+                  in: path
+                  required: true
+                  schema:
+                      type: integer
+            responses:
+                "204":
+                    description: Version disabled
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/vaults/{vault_id}/secret-rotate/{path}:
+        post:
+            tags: [Secrets]
+            summary: Server-side secret rotation
+            operationId: rotateSecret
+            description: |
+                Generates a cryptographically random value and stores it as a new
+                version of the secret. The previous version is preserved in history.
+                Requires rotate or write permission.
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - $ref: "#/components/parameters/SecretPath"
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/RotateSecretRequest"
+            responses:
+                "201":
+                    description: New version created with server-generated value
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SecretCreatedResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Policies
     # ---------------------------------------------------------------------------
@@ -2663,6 +2798,36 @@ paths:
                 "401":
                     description: Unauthorized
 
+    /v1/shroud/threat-summary:
+        get:
+            tags: [Shroud]
+            summary: Shroud threat analytics summary
+            description: >
+                Aggregated threat metrics for the organization from `shroud_activity`
+                (detectors, blocked counts, recent flagged requests). Query `period` selects
+                the window; the previous window of equal length is used for request volume trend.
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: query
+                  name: period
+                  schema:
+                      type: string
+                      enum: [1h, 24h, 7d, 30d]
+                      default: 24h
+                  description: Rolling window ending now
+            responses:
+                "200":
+                    description: Threat summary
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ShroudThreatSummary"
+                "400":
+                    description: Invalid period
+                "401":
+                    description: Unauthorized
+
 # =============================================================================
 # COMPONENTS
 # =============================================================================
@@ -3143,6 +3308,9 @@ components:
                     type: string
                 description:
                     type: string
+                mpc_custody:
+                    type: string
+                    description: MPC custody mode to enable at creation (e.g. "2-of-2", "2-of-3")
 
         VaultResponse:
             type: object
@@ -3168,6 +3336,17 @@ components:
                 cmek_fingerprint:
                     type: string
                     description: SHA-256 fingerprint of the CMEK key (64 hex chars)
+                mpc_custody:
+                    type: string
+                    description: MPC custody mode (e.g. "2-of-2", "2-of-3"), absent when MPC is not enabled
+                mpc_threshold:
+                    type: integer
+                    description: Number of shares required to reconstruct the key
+                mpc_providers:
+                    type: array
+                    items:
+                        type: string
+                    description: List of MPC share providers (e.g. ["server", "client"])
 
         VaultListResponse:
             type: object
@@ -3229,6 +3408,16 @@ components:
                     type: string
                     format: date-time
 
+        # --- MPC ---
+
+        EnableMpcRequest:
+            type: object
+            required: [mpc_custody]
+            properties:
+                mpc_custody:
+                    type: string
+                    description: MPC custody mode (e.g. "2-of-2", "2-of-3")
+
         # --- Secrets ---
 
         PutSecretRequest:
@@ -3275,6 +3464,36 @@ components:
                 expires_at:
                     type: string
                     format: date-time
+                is_disabled:
+                    type: boolean
+                    description: Whether this version has been disabled (retained for audit but unreadable)
+
+        SecretCreatedResponse:
+            description: Returned when a secret is created or updated. Extends SecretMetadataResponse with an optional client_share for MPC vaults.
+            type: object
+            required: [id, path, type, version, created_at]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                path:
+                    type: string
+                type:
+                    type: string
+                version:
+                    type: integer
+                metadata:
+                    type: object
+                    additionalProperties: true
+                created_at:
+                    type: string
+                    format: date-time
+                expires_at:
+                    type: string
+                    format: date-time
+                client_share:
+                    type: string
+                    description: Base64-encoded client key share. Returned only for MPC 2-of-2 vaults. The client must store this share securely — it is not persisted server-side.
 
         SecretResponse:
             type: object
@@ -3314,6 +3533,30 @@ components:
                     items:
                         $ref: "#/components/schemas/SecretMetadataResponse"
 
+        SecretVersionListResponse:
+            type: object
+            properties:
+                versions:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/SecretMetadataResponse"
+
+        RotateSecretRequest:
+            type: object
+            properties:
+                length:
+                    type: integer
+                    minimum: 8
+                    maximum: 1024
+                    description: Length of the generated value (default 32)
+                charset:
+                    type: string
+                    enum: [hex, base64, alphanumeric, ascii]
+                    description: Character set for the generated value (default hex)
+                type:
+                    type: string
+                    description: Override the secret type (defaults to existing secret's type)
+
         # --- Policies ---
 
         CreatePolicyRequest:
@@ -5298,6 +5541,77 @@ components:
                 metadata:
                     type: object
 
+        ShroudThreatSummary:
+            type: object
+            properties:
+                total_requests:
+                    type: integer
+                    format: int64
+                total_requests_prev:
+                    type: integer
+                    format: int64
+                blocked_requests:
+                    type: integer
+                    format: int64
+                detectors_triggered:
+                    type: integer
+                    format: int64
+                active_agents:
+                    type: integer
+                    format: int64
+                detectors:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/ShroudDetectorStats"
+                flagged_requests:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/ShroudFlaggedRequest"
+
+        ShroudDetectorStats:
+            type: object
+            properties:
+                detector:
+                    type: string
+                detections:
+                    type: integer
+                    format: int64
+                blocks:
+                    type: integer
+                    format: int64
+                actions:
+                    type: object
+                    properties:
+                        blocked:
+                            type: integer
+                            format: int64
+                        warned:
+                            type: integer
+                            format: int64
+                        logged:
+                            type: integer
+                            format: int64
+
+        ShroudFlaggedRequest:
+            type: object
+            properties:
+                id:
+                    type: string
+                timestamp:
+                    type: string
+                    format: date-time
+                agent_id:
+                    type: string
+                agent_name:
+                    type: string
+                score:
+                    type: number
+                reason:
+                    type: string
+                action:
+                    type: string
+                    enum: [blocked, warned, logged]
+
         # --- Health ---
 
         HealthResponse:

package/package.json

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