@1claw/openapi-spec 0.20.0 → 0.21.0

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.10.0
+    version: 2.11.0
     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:
@@ -1651,6 +1759,117 @@ paths:
                 "402":
                     $ref: "#/components/responses/PaymentRequired"
 
+    # ---------------------------------------------------------------------------
+    # Agent Signing Keys (Multi-Chain)
+    # ---------------------------------------------------------------------------
+
+    /v1/agents/{agent_id}/signing-keys:
+        post:
+            tags: [Signing Keys]
+            summary: Provision a signing key for a chain
+            operationId: createSigningKey
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateSigningKeyRequest"
+            responses:
+                "201":
+                    description: Signing key created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SigningKeyResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "409":
+                    $ref: "#/components/responses/Conflict"
+        get:
+            tags: [Signing Keys]
+            summary: List signing keys for an agent
+            operationId: listSigningKeys
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Signing keys list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SigningKeyListResponse"
+
+    /v1/agents/{agent_id}/signing-keys/{chain}/rotate:
+        post:
+            tags: [Signing Keys]
+            summary: Rotate a signing key for a chain
+            operationId: rotateSigningKey
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            responses:
+                "200":
+                    description: Rotated signing key
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SigningKeyResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/signing-keys/{chain}:
+        delete:
+            tags: [Signing Keys]
+            summary: Deactivate a signing key for a chain
+            operationId: deactivateSigningKey
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            responses:
+                "204":
+                    description: Key deactivated
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    # ---------------------------------------------------------------------------
+    # Unified Signing Intent
+    # ---------------------------------------------------------------------------
+
+    /v1/agents/{agent_id}/sign:
+        post:
+            tags: [Signing]
+            summary: Unified signing intent (EIP-191, EIP-712, EIP-2718 types 0-4)
+            operationId: signIntent
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/SignIntentRequest"
+            responses:
+                "200":
+                    description: Signed result
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SignIntentResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
     # ---------------------------------------------------------------------------
     # Chains
     # ---------------------------------------------------------------------------
@@ -3057,6 +3276,12 @@ components:
                 application/json:
                     schema:
                         $ref: "#/components/schemas/PaymentRequirement"
+        Conflict:
+            description: Resource already exists or conflict
+            content:
+                application/json:
+                    schema:
+                        $ref: "#/components/schemas/ProblemDetails"
 
     schemas:
         ProblemDetails:
@@ -3168,6 +3393,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 +4066,7 @@ components:
 
         EnrollAgentRequest:
             type: object
-            required: [name, human_email]
+            required: [name]
             properties:
                 name:
                     type: string
@@ -3800,7 +4074,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 +4088,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 +4203,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 +4302,38 @@ 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).
+                signing_chains:
+                    type: array
+                    items:
+                        type: string
+                    description: Chains for which this agent has provisioned signing keys.
+                eip712_domain_allowlist:
+                    type: array
+                    items:
+                        type: object
+                    description: JSON array of allowed EIP-712 domain entries.
+                eip712_default_policy:
+                    type: string
+                    enum: [deny, allow]
+                    description: Default EIP-712 policy (deny blocks all unless allowlisted).
+                message_signing_enabled:
+                    type: boolean
+                    description: Whether EIP-191 personal_sign is enabled.
                 created_at:
                     type: string
                     format: date-time
@@ -4616,6 +4955,133 @@ components:
                     items:
                         $ref: "#/components/schemas/SimulateTransactionRequest"
 
+        # Signing Keys (Multi-Chain)
+        CreateSigningKeyRequest:
+            type: object
+            required: [chain]
+            properties:
+                chain:
+                    type: string
+                    enum: [ethereum, bitcoin, solana, xrp, cardano, tron]
+
+        SigningKeyResponse:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                agent_id:
+                    type: string
+                    format: uuid
+                chain:
+                    type: string
+                curve:
+                    type: string
+                public_key:
+                    type: string
+                address:
+                    type: string
+                    nullable: true
+                key_version:
+                    type: integer
+                is_active:
+                    type: boolean
+                created_at:
+                    type: string
+                    format: date-time
+                rotated_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+
+        SigningKeyListResponse:
+            type: object
+            properties:
+                keys:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/SigningKeyResponse"
+
+        # Unified Signing Intent
+        SignIntentRequest:
+            type: object
+            required: [intent_type, chain]
+            properties:
+                intent_type:
+                    type: string
+                    enum: [personal_sign, typed_data, transaction]
+                chain:
+                    type: string
+                signing_key_path:
+                    type: string
+                message:
+                    type: string
+                    description: Hex-encoded message bytes (for personal_sign)
+                typed_data:
+                    type: object
+                    description: EIP-712 typed data JSON (for typed_data)
+                tx_type:
+                    type: integer
+                    description: "EIP-2718 type: 0=legacy, 1=2930, 2=1559, 3=4844, 4=7702"
+                to:
+                    type: string
+                value:
+                    type: string
+                data:
+                    type: string
+                nonce:
+                    type: integer
+                gas_limit:
+                    type: integer
+                gas_price:
+                    type: string
+                max_fee_per_gas:
+                    type: string
+                max_priority_fee_per_gas:
+                    type: string
+                access_list:
+                    type: array
+                    items:
+                        type: object
+                max_fee_per_blob_gas:
+                    type: string
+                blob_versioned_hashes:
+                    type: array
+                    items:
+                        type: string
+                authorization_list:
+                    type: array
+                    items:
+                        type: object
+
+        SignIntentResponse:
+            type: object
+            properties:
+                intent_type:
+                    type: string
+                chain:
+                    type: string
+                from:
+                    type: string
+                signature:
+                    type: string
+                    nullable: true
+                signed_tx:
+                    type: string
+                    nullable: true
+                tx_hash:
+                    type: string
+                    nullable: true
+                message_hash:
+                    type: string
+                    nullable: true
+                typed_data_hash:
+                    type: string
+                    nullable: true
+                tx_type:
+                    type: integer
+                    nullable: true
+
         TransactionResponse:
             type: object
             properties:
@@ -5643,6 +6109,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 +6175,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.21.0",
     "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
     "license": "MIT",
     "repository": {