@1claw/openapi-spec 0.16.3 → 0.18.0

package/openapi.yaml

@@ -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,
         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
@@ -2597,6 +2638,102 @@ paths:
                                         type: string
                                         enum: [ok, degraded, unavailable]
 
+    # --- Shroud Activity ---
+
+    /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.
+            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
 # =============================================================================
@@ -3077,6 +3214,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
@@ -3102,6 +3242,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
@@ -3163,6 +3314,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:
@@ -3210,6 +3371,33 @@ components:
                     type: string
                     format: date-time
 
+        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: [id, path, type, value, version, created_at]
@@ -3715,6 +3903,21 @@ components:
                     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
 
         UnicodeNormalizationConfig:
             type: object
@@ -3850,6 +4053,150 @@ components:
                         type: string
                     description: Path patterns to block (e.g., /etc/passwd, ~/.ssh)
 
+        ToolCallPolicy:
+            type: object
+            description: Tool/function call inspection settings
+            properties:
+                enabled:
+                    type: boolean
+                    default: false
+                    description: Enable tool call inspection
+                allowed_tool_names:
+                    type: array
+                    items:
+                        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]
@@ -4995,6 +5342,155 @@ components:
                 description:
                     type: string
 
+        # --- Shroud Activity ---
+
+        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]
+
         # --- Health ---
 
         HealthResponse:

package/package.json

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