@1claw/openapi-spec 0.2.0 → 0.4.0

package/README.md

@@ -44,7 +44,7 @@ import spec from "@1claw/openapi-spec/openapi.json";
 
 - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking
 - **Secrets** — CRUD, versioning, CMEK-encrypted flag
-- **Agents** — CRUD with `token_ttl_seconds`, `vault_ids`, crypto proxy, transaction guardrails
+- **Agents** — CRUD with `auth_method` (api_key, mtls, oidc_client_credentials), auto-generated SSH keypairs, `token_ttl_seconds`, `vault_ids`, crypto proxy, transaction guardrails
 - **Policies** — Glob-based access control
 - **Sharing** — Links, user/agent shares, accept/decline
 - **Billing** — Subscriptions, credits, x402

package/openapi.json

@@ -1478,10 +1478,20 @@
           "Transactions"
         ],
         "summary": "Submit a transaction for signing",
+        "description": "Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).\nDuplicate requests with the same key within 24 hours return the cached transaction response\n(no second sign/broadcast). Omit the header for non-idempotent submissions.\n",
         "operationId": "submitTransaction",
         "parameters": [
           {
             "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "Idempotency-Key",
+            "in": "header",
+            "required": false,
+            "description": "Optional key for replay protection; duplicate requests return cached response.",
+            "schema": {
+              "type": "string"
+            }
           }
         ],
         "requestBody": {
@@ -1495,6 +1505,16 @@
           }
         },
         "responses": {
+          "200": {
+            "description": "Transaction previously created with same Idempotency-Key (replay-safe response)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TransactionResponse"
+                }
+              }
+            }
+          },
           "201": {
             "description": "Transaction signed (and optionally broadcast)",
             "content": {
@@ -1508,6 +1528,16 @@
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
+          "409": {
+            "description": "Idempotency-Key in use by another in-flight request; retry later.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
           "422": {
             "description": "Simulation reverted (when simulate_first is true)",
             "content": {
@@ -1529,6 +1559,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "$ref": "#/components/parameters/IncludeSignedTx"
           }
         ],
         "responses": {
@@ -1564,6 +1597,9 @@
               "type": "string",
               "format": "uuid"
             }
+          },
+          {
+            "$ref": "#/components/parameters/IncludeSignedTx"
           }
         ],
         "responses": {
@@ -2922,6 +2958,16 @@
           "type": "string",
           "format": "uuid"
         }
+      },
+      "IncludeSignedTx": {
+        "name": "include_signed_tx",
+        "in": "query",
+        "required": false,
+        "description": "Set to `true` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk.\n",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
       }
     },
     "responses": {
@@ -3784,7 +3830,14 @@
             "type": "string"
           },
           "auth_method": {
-            "type": "string"
+            "type": "string",
+            "enum": [
+              "api_key",
+              "mtls",
+              "oidc_client_credentials"
+            ],
+            "default": "api_key",
+            "description": "Authentication method. api_key generates a one-time key; mtls requires client_cert_fingerprint; oidc_client_credentials requires oidc_issuer and oidc_client_id."
           },
           "scopes": {
             "type": "array",
@@ -3830,6 +3883,18 @@
               "format": "uuid"
             },
             "description": "Restrict agent to specific vault UUIDs (empty = all vaults in org)"
+          },
+          "client_cert_fingerprint": {
+            "type": "string",
+            "description": "SHA-256 fingerprint of the client certificate (required for mTLS auth)"
+          },
+          "oidc_issuer": {
+            "type": "string",
+            "description": "OIDC issuer URL (required for oidc_client_credentials auth)"
+          },
+          "oidc_client_id": {
+            "type": "string",
+            "description": "OIDC client ID (required for oidc_client_credentials auth)"
           }
         }
       },
@@ -3908,7 +3973,12 @@
             "type": "string"
           },
           "auth_method": {
-            "type": "string"
+            "type": "string",
+            "enum": [
+              "api_key",
+              "mtls",
+              "oidc_client_credentials"
+            ]
           },
           "scopes": {
             "type": "array",
@@ -3951,6 +4021,26 @@
               "format": "uuid"
             }
           },
+          "client_cert_fingerprint": {
+            "type": "string",
+            "description": "SHA-256 fingerprint of the client certificate (mTLS agents)"
+          },
+          "oidc_issuer": {
+            "type": "string",
+            "description": "OIDC issuer URL (oidc_client_credentials agents)"
+          },
+          "oidc_client_id": {
+            "type": "string",
+            "description": "OIDC client ID (oidc_client_credentials agents)"
+          },
+          "ssh_public_key": {
+            "type": "string",
+            "description": "Ed25519 SSH public key (base64-encoded, auto-generated at creation)"
+          },
+          "ecdh_public_key": {
+            "type": "string",
+            "description": "P-256 ECDH public key (base64 SEC1 uncompressed point, auto-generated at creation)"
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"
@@ -4009,14 +4099,21 @@
           "last_active_at": {
             "type": "string",
             "format": "date-time"
+          },
+          "ssh_public_key": {
+            "type": "string",
+            "description": "Ed25519 SSH public key (base64-encoded)"
+          },
+          "ecdh_public_key": {
+            "type": "string",
+            "description": "P-256 ECDH public key (base64 SEC1 uncompressed point)"
           }
         }
       },
       "AgentCreatedResponse": {
         "type": "object",
         "required": [
-          "agent",
-          "api_key"
+          "agent"
         ],
         "properties": {
           "agent": {
@@ -4024,7 +4121,7 @@
           },
           "api_key": {
             "type": "string",
-            "description": "One-time API key (store securely)"
+            "description": "One-time API key (only present for api_key auth method)"
           }
         }
       },
@@ -4171,7 +4268,9 @@
             ]
           },
           "signed_tx": {
-            "type": "string"
+            "type": "string",
+            "nullable": true,
+            "description": "Raw signed transaction hex. Omitted (null) by default to reduce exfiltration risk. Pass `include_signed_tx=true` query param on GET endpoints to include it. Always returned on the initial POST submission response.\n"
           },
           "tx_hash": {
             "type": "string"

package/openapi.yaml

@@ -941,9 +941,19 @@ paths:
     post:
       tags: [Transactions]
       summary: Submit a transaction for signing
+      description: |
+        Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).
+        Duplicate requests with the same key within 24 hours return the cached transaction response
+        (no second sign/broadcast). Omit the header for non-idempotent submissions.
       operationId: submitTransaction
       parameters:
         - $ref: "#/components/parameters/AgentId"
+        - name: Idempotency-Key
+          in: header
+          required: false
+          description: Optional key for replay protection; duplicate requests return cached response.
+          schema:
+            type: string
       requestBody:
         required: true
         content:
@@ -957,8 +967,20 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/TransactionResponse"
+        "200":
+          description: Transaction previously created with same Idempotency-Key (replay-safe response)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TransactionResponse"
         "403":
           $ref: "#/components/responses/Forbidden"
+        "409":
+          description: Idempotency-Key in use by another in-flight request; retry later.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
         "422":
           description: Simulation reverted (when simulate_first is true)
           content:
@@ -971,6 +993,7 @@ paths:
       operationId: listTransactions
       parameters:
         - $ref: "#/components/parameters/AgentId"
+        - $ref: "#/components/parameters/IncludeSignedTx"
       responses:
         "200":
           description: Transaction list
@@ -992,6 +1015,7 @@ paths:
           schema:
             type: string
             format: uuid
+        - $ref: "#/components/parameters/IncludeSignedTx"
       responses:
         "200":
           description: Transaction details
@@ -1871,6 +1895,16 @@ components:
       schema:
         type: string
         format: uuid
+    IncludeSignedTx:
+      name: include_signed_tx
+      in: query
+      required: false
+      description: >
+        Set to `true` to include the raw signed transaction hex in the response.
+        Omitted by default to reduce key exfiltration risk.
+      schema:
+        type: boolean
+        default: false
 
   responses:
     BadRequest:
@@ -2456,6 +2490,9 @@ components:
           type: string
         auth_method:
           type: string
+          enum: [api_key, mtls, oidc_client_credentials]
+          default: api_key
+          description: Authentication method. api_key generates a one-time key; mtls requires client_cert_fingerprint; oidc_client_credentials requires oidc_issuer and oidc_client_id.
         scopes:
           type: array
           items:
@@ -2488,6 +2525,15 @@ components:
             type: string
             format: uuid
           description: Restrict agent to specific vault UUIDs (empty = all vaults in org)
+        client_cert_fingerprint:
+          type: string
+          description: SHA-256 fingerprint of the client certificate (required for mTLS auth)
+        oidc_issuer:
+          type: string
+          description: OIDC issuer URL (required for oidc_client_credentials auth)
+        oidc_client_id:
+          type: string
+          description: OIDC client ID (required for oidc_client_credentials auth)
 
     UpdateAgentRequest:
       type: object
@@ -2539,6 +2585,7 @@ components:
           type: string
         auth_method:
           type: string
+          enum: [api_key, mtls, oidc_client_credentials]
         scopes:
           type: array
           items:
@@ -2567,6 +2614,21 @@ components:
           items:
             type: string
             format: uuid
+        client_cert_fingerprint:
+          type: string
+          description: SHA-256 fingerprint of the client certificate (mTLS agents)
+        oidc_issuer:
+          type: string
+          description: OIDC issuer URL (oidc_client_credentials agents)
+        oidc_client_id:
+          type: string
+          description: OIDC client ID (oidc_client_credentials agents)
+        ssh_public_key:
+          type: string
+          description: Ed25519 SSH public key (base64-encoded, auto-generated at creation)
+        ecdh_public_key:
+          type: string
+          description: P-256 ECDH public key (base64 SEC1 uncompressed point, auto-generated at creation)
         created_at:
           type: string
           format: date-time
@@ -2610,16 +2672,22 @@ components:
         last_active_at:
           type: string
           format: date-time
+        ssh_public_key:
+          type: string
+          description: Ed25519 SSH public key (base64-encoded)
+        ecdh_public_key:
+          type: string
+          description: P-256 ECDH public key (base64 SEC1 uncompressed point)
 
     AgentCreatedResponse:
       type: object
-      required: [agent, api_key]
+      required: [agent]
       properties:
         agent:
           $ref: "#/components/schemas/AgentResponse"
         api_key:
           type: string
-          description: One-time API key (store securely)
+          description: One-time API key (only present for api_key auth method)
 
     AgentListResponse:
       type: object
@@ -2717,6 +2785,11 @@ components:
           enum: [pending, signed, broadcast, failed, simulation_failed]
         signed_tx:
           type: string
+          nullable: true
+          description: >
+            Raw signed transaction hex. Omitted (null) by default to reduce exfiltration risk.
+            Pass `include_signed_tx=true` query param on GET endpoints to include it.
+            Always returned on the initial POST submission response.
         tx_hash:
           type: string
         error_message:

package/package.json

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