@1claw/openapi-spec 0.16.3 → 0.18.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.6.0",
+    "version": "2.8.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": {
@@ -4027,6 +4082,161 @@
           }
         }
       }
+    },
+    "/v1/shroud/activity": {
+      "get": {
+        "tags": [
+          "Shroud"
+        ],
+        "summary": "List Shroud activity events",
+        "description": "Returns recent Shroud proxy activity for the organization (LLM requests, inspections, policy actions).",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "agent_id",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by agent ID"
+          },
+          {
+            "in": "query",
+            "name": "action",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by action (allowed, blocked, warned)"
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "schema": {
+              "type": "integer",
+              "default": 50
+            },
+            "description": "Maximum events to return"
+          },
+          {
+            "in": "query",
+            "name": "offset",
+            "schema": {
+              "type": "integer",
+              "default": 0
+            },
+            "description": "Pagination offset"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Activity events",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "events": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/ShroudActivityEvent"
+                      }
+                    },
+                    "total": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Shroud"
+        ],
+        "summary": "Ingest Shroud activity event (internal)",
+        "description": "Called by the Shroud proxy to record activity events. Not intended for external use.",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/IngestShroudActivityRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Event recorded"
+          },
+          "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.\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": {
@@ -4704,6 +4914,10 @@
           },
           "description": {
             "type": "string"
+          },
+          "mpc_custody": {
+            "type": "string",
+            "description": "MPC custody mode to enable at creation (e.g. \"2-of-2\", \"2-of-3\")"
           }
         }
       },
@@ -4742,6 +4956,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\"])"
           }
         }
       },
@@ -4837,6 +5066,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": [
@@ -4905,6 +5146,48 @@
           }
         }
       },
+      "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",
         "required": [
@@ -5615,6 +5898,27 @@
             "type": "boolean",
             "default": true,
             "description": "Whether to log all detected threats to audit (even when action is allow/warn)"
+          },
+          "tool_call_inspection": {
+            "$ref": "#/components/schemas/ToolCallPolicy"
+          },
+          "output_policy": {
+            "$ref": "#/components/schemas/OutputPolicy"
+          },
+          "secret_injection_detection": {
+            "$ref": "#/components/schemas/SecretInjectionConfig"
+          },
+          "advanced_redaction": {
+            "$ref": "#/components/schemas/AdvancedRedactionConfig"
+          },
+          "semantic_policy": {
+            "$ref": "#/components/schemas/SemanticPolicy"
+          },
+          "flagged_request_retention_days": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 365,
+            "description": "Number of days to retain flagged request bodies for replay/investigation"
           }
         }
       },
@@ -5821,35 +6125,250 @@
           }
         }
       },
-      "AgentCreatedResponse": {
+      "ToolCallPolicy": {
         "type": "object",
-        "required": [
-          "agent"
-        ],
+        "description": "Tool/function call inspection settings",
         "properties": {
-          "agent": {
-            "$ref": "#/components/schemas/AgentResponse"
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable tool call inspection"
           },
-          "api_key": {
-            "type": "string",
-            "description": "One-time API key (only present for api_key auth method)"
-          }
-        }
-      },
-      "AgentListResponse": {
-        "type": "object",
-        "properties": {
-          "agents": {
+          "allowed_tool_names": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/AgentResponse"
-            }
-          }
-        }
-      },
-      "AgentKeyRotatedResponse": {
-        "type": "object",
-        "properties": {
+              "type": "string"
+            },
+            "description": "Allowed tool/function names (empty = all allowed)"
+          },
+          "denied_tool_names": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Denied tool/function names"
+          },
+          "scan_arguments": {
+            "type": "boolean",
+            "default": true,
+            "description": "Scan tool call arguments for credential exfiltration"
+          },
+          "block_credential_exfil": {
+            "type": "boolean",
+            "default": true,
+            "description": "Block tool calls that appear to exfiltrate credentials"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "block",
+              "sanitize",
+              "warn",
+              "log"
+            ],
+            "default": "block",
+            "description": "Action when a tool call violation is detected"
+          }
+        }
+      },
+      "OutputPolicy": {
+        "type": "object",
+        "description": "Output content policy settings for LLM responses",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable output content policies"
+          },
+          "blocked_patterns": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Custom regex patterns to block in responses"
+          },
+          "blocked_entities": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Named entities to block (e.g., competitor names)"
+          },
+          "block_harmful_content": {
+            "type": "boolean",
+            "default": false,
+            "description": "Block responses containing harmful content categories"
+          },
+          "harmful_categories": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "violence",
+                "self_harm",
+                "illegal",
+                "hate",
+                "sexual",
+                "malware"
+              ]
+            },
+            "description": "Harm categories to block"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "block",
+              "sanitize",
+              "warn",
+              "log"
+            ],
+            "default": "warn",
+            "description": "Action when output policy is violated"
+          }
+        }
+      },
+      "SecretInjectionConfig": {
+        "type": "object",
+        "description": "Detects credentials injected into prompts that are not from the vault",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable secret injection detection"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "block",
+              "sanitize",
+              "warn",
+              "log"
+            ],
+            "default": "block",
+            "description": "Action when injected credentials are detected"
+          },
+          "sensitivity": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high"
+            ],
+            "default": "medium",
+            "description": "Detection sensitivity level"
+          }
+        }
+      },
+      "AdvancedRedactionConfig": {
+        "type": "object",
+        "description": "Advanced secret redaction settings (base64-encoded, split, prefix leaks)",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable advanced redaction checks"
+          },
+          "detect_base64_encoded": {
+            "type": "boolean",
+            "default": false,
+            "description": "Detect base64-encoded vault secrets"
+          },
+          "detect_split_secrets": {
+            "type": "boolean",
+            "default": false,
+            "description": "Detect secrets split across tokens or messages"
+          },
+          "detect_prefix_leak": {
+            "type": "boolean",
+            "default": false,
+            "description": "Detect partial/prefix leaks of vault secrets"
+          },
+          "min_secret_length": {
+            "type": "integer",
+            "default": 16,
+            "description": "Minimum secret length to consider for advanced matching"
+          }
+        }
+      },
+      "SemanticPolicy": {
+        "type": "object",
+        "description": "Semantic/intent-level policy enforcement",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable semantic policy enforcement"
+          },
+          "allowed_topics": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Topics the agent is allowed to discuss (empty = all)"
+          },
+          "denied_topics": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Topics to block"
+          },
+          "allowed_tasks": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Tasks the agent is allowed to perform (empty = all)"
+          },
+          "denied_tasks": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Tasks to block (e.g., code_generation, data_export)"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "block",
+              "sanitize",
+              "warn",
+              "log"
+            ],
+            "default": "warn",
+            "description": "Action when semantic policy is violated"
+          }
+        }
+      },
+      "AgentCreatedResponse": {
+        "type": "object",
+        "required": [
+          "agent"
+        ],
+        "properties": {
+          "agent": {
+            "$ref": "#/components/schemas/AgentResponse"
+          },
+          "api_key": {
+            "type": "string",
+            "description": "One-time API key (only present for api_key auth method)"
+          }
+        }
+      },
+      "AgentListResponse": {
+        "type": "object",
+        "properties": {
+          "agents": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AgentResponse"
+            }
+          }
+        }
+      },
+      "AgentKeyRotatedResponse": {
+        "type": "object",
+        "properties": {
           "api_key": {
             "type": "string"
           }
@@ -7482,6 +8001,218 @@
           }
         }
       },
+      "ShroudActivityEvent": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "action": {
+            "type": "string",
+            "description": "Action taken (allowed, blocked, warned)"
+          },
+          "request_tokens": {
+            "type": "integer"
+          },
+          "response_tokens": {
+            "type": "integer"
+          },
+          "latency_ms": {
+            "type": "integer"
+          },
+          "had_secrets_redacted": {
+            "type": "boolean"
+          },
+          "had_pii_detected": {
+            "type": "boolean"
+          },
+          "injection_score": {
+            "type": "number"
+          },
+          "policy_violations": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "metadata": {
+            "type": "object"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "IngestShroudActivityRequest": {
+        "type": "object",
+        "required": [
+          "agent_id",
+          "action"
+        ],
+        "properties": {
+          "agent_id": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "action": {
+            "type": "string"
+          },
+          "request_tokens": {
+            "type": "integer",
+            "default": 0
+          },
+          "response_tokens": {
+            "type": "integer",
+            "default": 0
+          },
+          "latency_ms": {
+            "type": "integer"
+          },
+          "had_secrets_redacted": {
+            "type": "boolean",
+            "default": false
+          },
+          "had_pii_detected": {
+            "type": "boolean",
+            "default": false
+          },
+          "injection_score": {
+            "type": "number",
+            "default": 0
+          },
+          "policy_violations": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "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"
+            ]
+          }
+        }
+      },
       "HealthResponse": {
         "type": "object",
         "properties": {