@1claw/openapi-spec 0.20.0 → 0.20.2

package/README.md

@@ -40,21 +40,22 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.19.x)
+## What's in the spec (v0.20.x — API `info.version` 2.10.x)
 
-- **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.
+- **OIDC Federation (1claw as IdP)** — `GET /.well-known/openid-configuration` (public discovery: issuer, jwks_uri, supported algs `["EdDSA","RS256"]`, supported grant types incl. token-exchange), `GET /.well-known/jwks.json` (public JWKS — every active EdDSA + RS256 key version, keyed by deterministic `kid`), `POST /v1/auth/federated-token` (RFC 8693 token exchange — accepts JSON or `application/x-www-form-urlencoded`; subject token is an agent JWT or `ocv_` API key; returns RS256 JWT scoped to `audience`). Agent fields: `federation_enabled`, `federation_audiences[]`, `federated_token_ttl_seconds`. Designed for Anthropic Workload Identity Federation, GCP STS, AWS STS, etc.
+- **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. Federation tokens use a separate KMS RSA-2048 key and are signed RS256.
 - **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, 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 (`tx_to_allowlist`, `tx_max_value_eth`, `tx_daily_limit_eth`, `tx_allowed_chains`); **`GET /v1/agents/{id}`** includes **`tx_spent_today_eth`** (rolling UTC-day spend from recorded txs) for clients such as **Shroud** that enforce the daily cap alongside per-tx limits
+- **Agents** — CRUD with `auth_method` (api_key, mtls, oidc_client_credentials), auto-generated SSH keypairs, `token_ttl_seconds`, `vault_ids`, Intents API, transaction guardrails (`tx_to_allowlist`, `tx_max_value_eth`, `tx_daily_limit_eth`, `tx_allowed_chains`), **OIDC federation knobs** (`federation_enabled`, `federation_audiences`, `federated_token_ttl_seconds`); **`GET /v1/agents/{id}`** includes **`tx_spent_today_eth`** (rolling UTC-day spend from recorded txs) for clients such as **Shroud** that enforce the daily cap alongside per-tx limits
 - **Policies** — Glob-based access control
 - **Sharing** — Links, user/agent shares, accept/decline
 - **Billing** — Subscriptions, credits, x402, LLM token billing (see above)
 - **Audit** — Hash-chained event log
 - **Chains** — Supported blockchain registry
-- **Auth** — JWT, API keys, agent tokens, MFA, device flow, Google OAuth
+- **Auth** — JWT, API keys, agent tokens, MFA, device flow, Google OAuth, **federated tokens (RFC 8693)**
 - **Org** — List members, invite, update/remove member; `GET /v1/org/agent-keys-vault` (users only, returns __agent-keys vault id or 404)
 
 ## Included files

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.10.0",
+    "version": "2.10.1",
     "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"
@@ -267,7 +267,7 @@
           "Authentication"
         ],
         "summary": "Get JWT verification public key",
-        "description": "Returns the Ed25519 public key used to sign JWTs.\nUse this to verify tokens independently (e.g. in a TEE proxy or\ngateway). No authentication required.\n",
+        "description": "Returns the Ed25519 public key used to sign JWTs.\nUse this to verify tokens independently (e.g. in a TEE proxy or\ngateway). No authentication required.\n\nFor OIDC-compliant relying parties (Anthropic Workload Identity\nFederation, etc.) prefer the JWKS endpoint at\n`/.well-known/jwks.json` together with the discovery document\nat `/.well-known/openid-configuration` — those advertise both\nEd25519 and RS256 keys keyed by `kid` and survive key rotation.\n",
         "operationId": "getJwtPublicKey",
         "security": [],
         "responses": {
@@ -298,6 +298,110 @@
         }
       }
     },
+    "/v1/auth/federated-token": {
+      "post": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Exchange a 1claw token for an OIDC federation token (RFC 8693)",
+        "description": "Mints a short-lived RS256-signed JWT targeted at an external\nrelying party (e.g. Anthropic Workload Identity Federation).\nThe relying party validates the token via this issuer's JWKS\nURL (`/.well-known/jwks.json`) and exchanges it for its own\nshort-lived service credentials.\n\nRequirements:\n- The agent that owns the `subject_token` must have\n  `federation_enabled = true` and the requested `audience`\n  must appear in `federation_audiences`.\n- The `subject_token` must be a valid 1claw agent JWT or\n  `ocv_` API key.\n- Optional `scope` narrows the agent's existing scopes — it\n  cannot escalate.\n\nReturns 503 when `ONECLAW_JWT_RS256_SIGNING_KEY_ID` is not\nconfigured on the server.\n",
+        "operationId": "exchangeFederatedToken",
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TokenExchangeRequest"
+              }
+            },
+            "application/x-www-form-urlencoded": {
+              "schema": {
+                "$ref": "#/components/schemas/TokenExchangeRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Federation token issued",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TokenExchangeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "503": {
+            "description": "RS256 signing key not configured"
+          }
+        }
+      }
+    },
+    "/.well-known/openid-configuration": {
+      "get": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "OIDC discovery document",
+        "description": "Standard OpenID Connect discovery document advertising the\nissuer URL, JWKS URL, supported algorithms (`EdDSA`, `RS256`),\nand the RFC 8693 token-exchange endpoint. External IdPs\n(Anthropic WIF, Okta, Auth0, etc.) read this URL to learn\nwhere 1claw publishes its JWKS.\n",
+        "operationId": "openidConfiguration",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Discovery document",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/.well-known/jwks.json": {
+      "get": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "JSON Web Key Set",
+        "description": "Public keys for every active version of every JWT signing\nkey (Ed25519 + RSA-2048). Each entry includes a `kid` so\nconsumers can validate tokens issued before the most recent\nkey rotation. Cached for 5 minutes via `Cache-Control` and\nCORS-permissive for browser-based IdP consoles.\n",
+        "operationId": "jwks",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "JWK Set",
+            "content": {
+              "application/jwk-set+json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "keys": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/auth/signup": {
       "post": {
         "tags": [
@@ -1708,7 +1812,7 @@
         }
       }
     },
-    "/v1/vaults/{vault_id}/secret-version/{path}/{version}/disable": {
+    "/v1/vaults/{vault_id}/secret-version-disable/{path}/{version}": {
       "post": {
         "tags": [
           "Secrets"
@@ -1922,7 +2026,7 @@
         ],
         "summary": "Self-enroll an agent",
         "operationId": "enrollAgent",
-        "description": "Public endpoint (no auth required). Creates an agent under the human's org\nand emails the credentials to the specified human email. The API key is NOT\nreturned in the response. Anti-spam: IP rate limiting + per-email cooldown.\n",
+        "description": "Public endpoint (no auth required).\n\n**With `human_email`:** Creates a pending enrollment for that account's org,\nemails Allow/Deny links, and returns `approval_url` in the JSON body (use if email\nis delayed). The API key is NOT returned until the human approves.\n\n**Name only (omit `human_email`):** Creates a link-only pending enrollment.\nThe response includes `approval_url`; the human opens it while signed in to\napprove the agent into their org.\n\nAnti-spam: IP rate limiting, per-email cooldown, caps on pending rows.\n",
         "requestBody": {
           "required": true,
           "content": {
@@ -4868,6 +4972,76 @@
           }
         }
       },
+      "TokenExchangeRequest": {
+        "type": "object",
+        "required": [
+          "grant_type",
+          "subject_token",
+          "subject_token_type",
+          "audience"
+        ],
+        "description": "RFC 8693 token-exchange request body. `subject_token_type`\naccepts the standard JWT URI or 1claw's API-key URI:\n  - `urn:ietf:params:oauth:token-type:jwt`\n  - `urn:1claw:params:oauth:token-type:api-key`\n",
+        "properties": {
+          "grant_type": {
+            "type": "string",
+            "enum": [
+              "urn:ietf:params:oauth:grant-type:token-exchange"
+            ]
+          },
+          "subject_token": {
+            "type": "string",
+            "description": "1claw JWT or `ocv_` API key authorising the exchange."
+          },
+          "subject_token_type": {
+            "type": "string",
+            "enum": [
+              "urn:ietf:params:oauth:token-type:jwt",
+              "urn:1claw:params:oauth:token-type:api-key"
+            ]
+          },
+          "audience": {
+            "type": "string",
+            "format": "uri",
+            "description": "Required `aud` claim for the issued federation token (must be in agent's allowlist).",
+            "example": "https://api.anthropic.com"
+          },
+          "scope": {
+            "type": "string",
+            "description": "Optional space-separated subset of the agent's existing scopes."
+          },
+          "requested_token_type": {
+            "type": "string",
+            "description": "Optional. Defaults to `urn:ietf:params:oauth:token-type:jwt`."
+          }
+        }
+      },
+      "TokenExchangeResponse": {
+        "type": "object",
+        "required": [
+          "access_token",
+          "issued_token_type",
+          "token_type",
+          "expires_in"
+        ],
+        "properties": {
+          "access_token": {
+            "type": "string",
+            "description": "RS256-signed federation JWT."
+          },
+          "issued_token_type": {
+            "type": "string"
+          },
+          "token_type": {
+            "type": "string"
+          },
+          "expires_in": {
+            "type": "integer"
+          },
+          "scope": {
+            "type": "string"
+          }
+        }
+      },
       "SignupRequest": {
         "type": "object",
         "required": [
@@ -5766,8 +5940,7 @@
       "EnrollAgentRequest": {
         "type": "object",
         "required": [
-          "name",
-          "human_email"
+          "name"
         ],
         "properties": {
           "name": {
@@ -5777,7 +5950,7 @@
           "human_email": {
             "type": "string",
             "format": "email",
-            "description": "Email of the human who will receive the agent credentials"
+            "description": "Optional. If set, pending enrollment is bound to that 1Claw account email\nand Allow/Deny links are emailed. If omitted, only `approval_url` is used\n(link-only enrollment; human must open the URL while signed in).\n"
           },
           "description": {
             "type": "string",
@@ -5791,11 +5964,16 @@
           "agent_id": {
             "type": "string",
             "format": "uuid",
-            "description": "UUID of the created agent (nil UUID when email not found — uniform response)"
+            "description": "UUID of the created agent (nil UUID until approved — uniform response)"
           },
           "message": {
             "type": "string",
-            "description": "Status message (always generic to prevent email enumeration)"
+            "description": "Status message (worded to limit email enumeration where applicable)"
+          },
+          "approval_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Present when a pending enrollment was created and the client should show\nthis link (email flow includes it as a fallback; name-only flow requires it).\n"
           }
         }
       },
@@ -5945,6 +6123,25 @@
           },
           "shroud_config": {
             "$ref": "#/components/schemas/ShroudConfig"
+          },
+          "federation_enabled": {
+            "type": "boolean",
+            "description": "Enable OIDC federation (RFC 8693 token-exchange) for this agent.\nWhen true, the agent may call POST /v1/auth/federated-token to mint\nfederation tokens for the audiences listed in `federation_audiences`.\n"
+          },
+          "federation_audiences": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            },
+            "description": "Allowlist of `aud` values the federation token-exchange may issue\ntokens for (e.g. `[\"https://api.anthropic.com\"]`). Empty array\nblocks all federation requests (zero-trust default).\n"
+          },
+          "federated_token_ttl_seconds": {
+            "type": "integer",
+            "minimum": 60,
+            "maximum": 3600,
+            "nullable": true,
+            "description": "Per-agent TTL override for federation tokens (seconds). NULL falls\nback to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).\nHard-capped at 3600 seconds.\n"
           }
         }
       },
@@ -6050,6 +6247,23 @@
           "shroud_config": {
             "$ref": "#/components/schemas/ShroudConfig"
           },
+          "federation_enabled": {
+            "type": "boolean",
+            "description": "Whether this agent may mint OIDC federation tokens via\nPOST /v1/auth/federated-token. False by default.\n"
+          },
+          "federation_audiences": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            },
+            "description": "Allowlist of audience URIs the agent may federate to."
+          },
+          "federated_token_ttl_seconds": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Per-agent TTL override for federation tokens (60..=3600)."
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"
@@ -8446,6 +8660,36 @@
               "type": "string"
             }
           },
+          "response_injection_score": {
+            "type": "number",
+            "description": "Response-side prompt-injection score (0.0–1.0)."
+          },
+          "response_context_injection_score": {
+            "type": "number",
+            "description": "Response-side context-injection score (0.0–1.0)."
+          },
+          "response_injection_categories": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Category tags emitted by the response-side filters (e.g. `markdown_image_exfil`, `data_uri_blob`, `echoed_instruction`)."
+          },
+          "external_urls_flagged": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "URLs emitted by the model that were flagged as potential exfil / callback targets."
+          },
+          "unexpected_code_blocks": {
+            "type": "integer",
+            "description": "Number of code fences in the response that were not expected for the agent's allowed task set."
+          },
+          "content_filtered": {
+            "type": "boolean",
+            "description": "True when Shroud rewrote or blocked response content before returning it to the agent."
+          },
           "metadata": {
             "type": "object"
           },
@@ -8505,6 +8749,34 @@
           },
           "metadata": {
             "type": "object"
+          },
+          "response_injection_score": {
+            "type": "number",
+            "default": 0
+          },
+          "response_context_injection_score": {
+            "type": "number",
+            "default": 0
+          },
+          "response_injection_categories": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "external_urls_flagged": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "unexpected_code_blocks": {
+            "type": "integer",
+            "default": 0
+          },
+          "content_filtered": {
+            "type": "boolean",
+            "default": false
           }
         }
       },

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.10.0
+    version: 2.10.1
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -192,6 +192,12 @@ paths:
                 Returns the Ed25519 public key used to sign JWTs.
                 Use this to verify tokens independently (e.g. in a TEE proxy or
                 gateway). No authentication required.
+
+                For OIDC-compliant relying parties (Anthropic Workload Identity
+                Federation, etc.) prefer the JWKS endpoint at
+                `/.well-known/jwks.json` together with the discovery document
+                at `/.well-known/openid-configuration` — those advertise both
+                Ed25519 and RS256 keys keyed by `kid` and survive key rotation.
             operationId: getJwtPublicKey
             security: []
             responses:
@@ -210,6 +216,100 @@ paths:
                                         type: string
                                         description: Base64-encoded Ed25519 public key
 
+    /v1/auth/federated-token:
+        post:
+            tags: [Authentication]
+            summary: Exchange a 1claw token for an OIDC federation token (RFC 8693)
+            description: |
+                Mints a short-lived RS256-signed JWT targeted at an external
+                relying party (e.g. Anthropic Workload Identity Federation).
+                The relying party validates the token via this issuer's JWKS
+                URL (`/.well-known/jwks.json`) and exchanges it for its own
+                short-lived service credentials.
+
+                Requirements:
+                - The agent that owns the `subject_token` must have
+                  `federation_enabled = true` and the requested `audience`
+                  must appear in `federation_audiences`.
+                - The `subject_token` must be a valid 1claw agent JWT or
+                  `ocv_` API key.
+                - Optional `scope` narrows the agent's existing scopes — it
+                  cannot escalate.
+
+                Returns 503 when `ONECLAW_JWT_RS256_SIGNING_KEY_ID` is not
+                configured on the server.
+            operationId: exchangeFederatedToken
+            security: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/TokenExchangeRequest"
+                    application/x-www-form-urlencoded:
+                        schema:
+                            $ref: "#/components/schemas/TokenExchangeRequest"
+            responses:
+                "200":
+                    description: Federation token issued
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TokenExchangeResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "503":
+                    description: RS256 signing key not configured
+
+    /.well-known/openid-configuration:
+        get:
+            tags: [Authentication]
+            summary: OIDC discovery document
+            description: |
+                Standard OpenID Connect discovery document advertising the
+                issuer URL, JWKS URL, supported algorithms (`EdDSA`, `RS256`),
+                and the RFC 8693 token-exchange endpoint. External IdPs
+                (Anthropic WIF, Okta, Auth0, etc.) read this URL to learn
+                where 1claw publishes its JWKS.
+            operationId: openidConfiguration
+            security: []
+            responses:
+                "200":
+                    description: Discovery document
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+
+    /.well-known/jwks.json:
+        get:
+            tags: [Authentication]
+            summary: JSON Web Key Set
+            description: |
+                Public keys for every active version of every JWT signing
+                key (Ed25519 + RSA-2048). Each entry includes a `kid` so
+                consumers can validate tokens issued before the most recent
+                key rotation. Cached for 5 minutes via `Cache-Control` and
+                CORS-permissive for browser-based IdP consoles.
+            operationId: jwks
+            security: []
+            responses:
+                "200":
+                    description: JWK Set
+                    content:
+                        application/jwk-set+json:
+                            schema:
+                                type: object
+                                properties:
+                                    keys:
+                                        type: array
+                                        items:
+                                            type: object
+
     /v1/auth/signup:
         post:
             tags: [Authentication]
@@ -1121,7 +1221,7 @@ paths:
                 "410":
                     description: Version has been disabled or expired
 
-    /v1/vaults/{vault_id}/secret-version/{path}/{version}/disable:
+    /v1/vaults/{vault_id}/secret-version-disable/{path}/{version}:
         post:
             tags: [Secrets]
             summary: Disable a specific secret version
@@ -1258,9 +1358,17 @@ paths:
             summary: Self-enroll an agent
             operationId: enrollAgent
             description: |
-                Public endpoint (no auth required). Creates an agent under the human's org
-                and emails the credentials to the specified human email. The API key is NOT
-                returned in the response. Anti-spam: IP rate limiting + per-email cooldown.
+                Public endpoint (no auth required).
+
+                **With `human_email`:** Creates a pending enrollment for that account's org,
+                emails Allow/Deny links, and returns `approval_url` in the JSON body (use if email
+                is delayed). The API key is NOT returned until the human approves.
+
+                **Name only (omit `human_email`):** Creates a link-only pending enrollment.
+                The response includes `approval_url`; the human opens it while signed in to
+                approve the agent into their org.
+
+                Anti-spam: IP rate limiting, per-email cooldown, caps on pending rows.
             requestBody:
                 required: true
                 content:
@@ -3168,6 +3276,55 @@ components:
                 api_key:
                     type: string
 
+        TokenExchangeRequest:
+            type: object
+            required: [grant_type, subject_token, subject_token_type, audience]
+            description: |
+                RFC 8693 token-exchange request body. `subject_token_type`
+                accepts the standard JWT URI or 1claw's API-key URI:
+                  - `urn:ietf:params:oauth:token-type:jwt`
+                  - `urn:1claw:params:oauth:token-type:api-key`
+            properties:
+                grant_type:
+                    type: string
+                    enum:
+                        - "urn:ietf:params:oauth:grant-type:token-exchange"
+                subject_token:
+                    type: string
+                    description: 1claw JWT or `ocv_` API key authorising the exchange.
+                subject_token_type:
+                    type: string
+                    enum:
+                        - "urn:ietf:params:oauth:token-type:jwt"
+                        - "urn:1claw:params:oauth:token-type:api-key"
+                audience:
+                    type: string
+                    format: uri
+                    description: Required `aud` claim for the issued federation token (must be in agent's allowlist).
+                    example: "https://api.anthropic.com"
+                scope:
+                    type: string
+                    description: Optional space-separated subset of the agent's existing scopes.
+                requested_token_type:
+                    type: string
+                    description: Optional. Defaults to `urn:ietf:params:oauth:token-type:jwt`.
+
+        TokenExchangeResponse:
+            type: object
+            required: [access_token, issued_token_type, token_type, expires_in]
+            properties:
+                access_token:
+                    type: string
+                    description: RS256-signed federation JWT.
+                issued_token_type:
+                    type: string
+                token_type:
+                    type: string
+                expires_in:
+                    type: integer
+                scope:
+                    type: string
+
         SignupRequest:
             type: object
             required: [email, password]
@@ -3792,7 +3949,7 @@ components:
 
         EnrollAgentRequest:
             type: object
-            required: [name, human_email]
+            required: [name]
             properties:
                 name:
                     type: string
@@ -3800,7 +3957,10 @@ components:
                 human_email:
                     type: string
                     format: email
-                    description: Email of the human who will receive the agent credentials
+                    description: |
+                        Optional. If set, pending enrollment is bound to that 1Claw account email
+                        and Allow/Deny links are emailed. If omitted, only `approval_url` is used
+                        (link-only enrollment; human must open the URL while signed in).
                 description:
                     type: string
                     description: Optional agent description
@@ -3811,10 +3971,16 @@ components:
                 agent_id:
                     type: string
                     format: uuid
-                    description: UUID of the created agent (nil UUID when email not found — uniform response)
+                    description: UUID of the created agent (nil UUID until approved — uniform response)
                 message:
                     type: string
-                    description: Status message (always generic to prevent email enumeration)
+                    description: Status message (worded to limit email enumeration where applicable)
+                approval_url:
+                    type: string
+                    format: uri
+                    description: |
+                        Present when a pending enrollment was created and the client should show
+                        this link (email flow includes it as a fallback; name-only flow requires it).
 
         # --- Agents ---
 
@@ -3920,6 +4086,30 @@ components:
                     description: Enable/disable Shroud LLM Proxy
                 shroud_config:
                     $ref: "#/components/schemas/ShroudConfig"
+                federation_enabled:
+                    type: boolean
+                    description: |
+                        Enable OIDC federation (RFC 8693 token-exchange) for this agent.
+                        When true, the agent may call POST /v1/auth/federated-token to mint
+                        federation tokens for the audiences listed in `federation_audiences`.
+                federation_audiences:
+                    type: array
+                    items:
+                        type: string
+                        format: uri
+                    description: |
+                        Allowlist of `aud` values the federation token-exchange may issue
+                        tokens for (e.g. `["https://api.anthropic.com"]`). Empty array
+                        blocks all federation requests (zero-trust default).
+                federated_token_ttl_seconds:
+                    type: integer
+                    minimum: 60
+                    maximum: 3600
+                    nullable: true
+                    description: |
+                        Per-agent TTL override for federation tokens (seconds). NULL falls
+                        back to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).
+                        Hard-capped at 3600 seconds.
 
         AgentResponse:
             type: object
@@ -3995,6 +4185,21 @@ components:
                     description: Whether this agent routes LLM traffic through the Shroud TEE proxy
                 shroud_config:
                     $ref: "#/components/schemas/ShroudConfig"
+                federation_enabled:
+                    type: boolean
+                    description: |
+                        Whether this agent may mint OIDC federation tokens via
+                        POST /v1/auth/federated-token. False by default.
+                federation_audiences:
+                    type: array
+                    items:
+                        type: string
+                        format: uri
+                    description: Allowlist of audience URIs the agent may federate to.
+                federated_token_ttl_seconds:
+                    type: integer
+                    nullable: true
+                    description: Per-agent TTL override for federation tokens (60..=3600).
                 created_at:
                     type: string
                     format: date-time
@@ -5643,6 +5848,31 @@ components:
                     type: array
                     items:
                         type: string
+                # Response-side inspection signals (Shroud v0.5.0+,
+                # H-RESP-INSPECT). Optional — pre-v0.5.0 events have them
+                # unset; treat as zero / empty.
+                response_injection_score:
+                    type: number
+                    description: Response-side prompt-injection score (0.0–1.0).
+                response_context_injection_score:
+                    type: number
+                    description: Response-side context-injection score (0.0–1.0).
+                response_injection_categories:
+                    type: array
+                    items:
+                        type: string
+                    description: Category tags emitted by the response-side filters (e.g. `markdown_image_exfil`, `data_uri_blob`, `echoed_instruction`).
+                external_urls_flagged:
+                    type: array
+                    items:
+                        type: string
+                    description: URLs emitted by the model that were flagged as potential exfil / callback targets.
+                unexpected_code_blocks:
+                    type: integer
+                    description: Number of code fences in the response that were not expected for the agent's allowed task set.
+                content_filtered:
+                    type: boolean
+                    description: True when Shroud rewrote or blocked response content before returning it to the agent.
                 metadata:
                     type: object
                 timestamp:
@@ -5684,6 +5914,28 @@ components:
                         type: string
                 metadata:
                     type: object
+                # Response-side inspection signals (Shroud v0.5.0+,
+                # H-RESP-INSPECT). Optional for backward compatibility.
+                response_injection_score:
+                    type: number
+                    default: 0
+                response_context_injection_score:
+                    type: number
+                    default: 0
+                response_injection_categories:
+                    type: array
+                    items:
+                        type: string
+                external_urls_flagged:
+                    type: array
+                    items:
+                        type: string
+                unexpected_code_blocks:
+                    type: integer
+                    default: 0
+                content_filtered:
+                    type: boolean
+                    default: false
 
         ShroudThreatSummary:
             type: object

package/package.json

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