@1claw/openapi-spec 0.61.17 → 0.61.18

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.17",
+    "version": "0.61.18",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging. Automations (workflow_spec,\nwebhook tokens, event triggers, Assist), cloud runtimes with\ninteractive shell sessions, agent memory, and discovery.\n\n## Domains\n\n`api.1claw.co` is canonical: it is the OIDC issuer, the `aud` the API\nmints, and the first entry in `servers` — a generated client takes its\nbase URL from there, and the previous ordering pointed every SDK at the\ndomain the issuer had already left. `api.1claw.xyz` still answers and is\nstill accepted on token validation, because tokens minted before the\nmove carry it; it is never minted now.\n\nOne deliberate exception: the Shroud attestation identity token is\nrequested from GCP with `audience: https://api.1claw.xyz`, so\n`/v1/shroud/attestation` reports that as its `expected_audience`. That\nis accurate rather than stale — the audience is a verification contract\nwith anyone already checking the token, and moving it is a breaking\nchange for them, not a rename.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.co"
@@ -99,6 +99,10 @@
       "name": "Treasury Wallets",
       "description": "Multi-chain wallet generation for human users (replaces CDP embedded wallets)"
     },
+    {
+      "name": "Key Custody",
+      "description": "Customer-held key shares for non-custodial (threshold) signing keys"
+    },
     {
       "name": "Admin",
       "description": "Platform administration"
@@ -1172,6 +1176,11 @@
                           },
                           "created_at": {
                             "type": "string"
+                          },
+                          "prf_supported": {
+                            "type": "boolean",
+                            "nullable": true,
+                            "description": "`true` — can hold a wallet share (WebAuthn PRF).\n`false` — cannot. `null` — registered before this\nwas captured.\n"
                           }
                         }
                       }
@@ -8413,6 +8422,213 @@
         }
       }
     },
+    "/v1/keys/{key_id}/client-share": {
+      "parameters": [
+        {
+          "name": "key_id",
+          "in": "path",
+          "required": true,
+          "description": "A treasury wallet id or an agent signing key id owned by the caller's org",
+          "schema": {
+            "type": "string",
+            "format": "uuid"
+          }
+        }
+      ],
+      "put": {
+        "tags": [
+          "Key Custody"
+        ],
+        "summary": "Store the customer's wrapped share of a threshold key",
+        "description": "Stores ciphertext the vault cannot open: the customer's share of a\n2-party threshold signing key, wrapped in the browser under the\npasskey's WebAuthn PRF output (`passkey_prf`, one wrap per credential)\nor under a recovery code (`recovery_code`, one per key). The vault\nkeeps the blob and its salt and returns them only to the owning user.\nHuman users only; the passkey must have reported PRF support at\nregistration. Idempotent per (key, credential).\n",
+        "operationId": "putClientKeyShare",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutClientShareRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Share stored",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ClientShareResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Key Custody"
+        ],
+        "summary": "List the caller's wrapped shares for a key",
+        "description": "Returns every wrap on file for this key, unopened, to the user who\nstored them. `custody` tells you whether the key is `server` (1claw\nholds the whole private key) or `client_tss` (threshold; neither party\ncan sign alone). Funding a `client_tss` wallet needs at least two wraps.\n",
+        "operationId": "listClientKeyShares",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Wraps on file",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ClientShareListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/keys/{key_id}/client-share/rewrap": {
+      "parameters": [
+        {
+          "name": "key_id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "format": "uuid"
+          }
+        }
+      ],
+      "post": {
+        "tags": [
+          "Key Custody"
+        ],
+        "summary": "Add a wrap for another credential or the recovery code",
+        "description": "Same write as `PUT …/client-share`, for a key that already has at\nleast one wrap: the browser, holding the share in memory during a\npasskey session, re-wraps it under a newly added passkey's PRF\noutput or under the recovery code. 409 if no wrap exists yet.\n",
+        "operationId": "rewrapClientKeyShare",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutClientShareRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Wrap added",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ClientShareResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          }
+        }
+      }
+    },
+    "/v1/keys/{key_id}/client-share/{share_id}": {
+      "parameters": [
+        {
+          "name": "key_id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "format": "uuid"
+          }
+        },
+        {
+          "name": "share_id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "format": "uuid"
+          }
+        }
+      ],
+      "delete": {
+        "tags": [
+          "Key Custody"
+        ],
+        "summary": "Remove one wrap",
+        "description": "Deletes a single wrap. Wraps tied to a passkey are also removed when\nthat passkey is deleted. Removing the last wrap of a `client_tss` key\nmakes the key unrecoverable — the vault holds only its own share.\n",
+        "operationId": "deleteClientKeyShare",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Wrap removed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/treasury/wallets/generate": {
       "post": {
         "tags": [
@@ -31957,6 +32173,14 @@
             "type": "string",
             "format": "date-time",
             "nullable": true
+          },
+          "custody": {
+            "type": "string",
+            "enum": [
+              "server",
+              "client_tss"
+            ],
+            "description": "`server` — 1claw holds the whole private key and can sign alone.\n`client_tss` — 2-party threshold key; the customer's passkey share is required.\n"
           }
         }
       },
@@ -34460,6 +34684,14 @@
           "created_at": {
             "type": "string",
             "format": "date-time"
+          },
+          "custody": {
+            "type": "string",
+            "enum": [
+              "server",
+              "client_tss"
+            ],
+            "description": "`server` — 1claw holds the whole private key and can sign alone.\n`client_tss` — 2-party threshold key; the customer's passkey share is required.\n"
           }
         }
       },
@@ -38161,6 +38393,120 @@
           },
           "name": {
             "type": "string"
+          },
+          "prf_supported": {
+            "type": "boolean",
+            "nullable": true,
+            "description": "`prf.enabled` from `credential.getClientExtensionResults()` —\nwhether this authenticator can derive the secret that wraps a\nwallet share. Omit if the client did not request the extension.\n"
+          }
+        }
+      },
+      "PutClientShareRequest": {
+        "type": "object",
+        "required": [
+          "wrap_kind",
+          "wrapped_share",
+          "salt"
+        ],
+        "properties": {
+          "wrap_kind": {
+            "type": "string",
+            "enum": [
+              "passkey_prf",
+              "recovery_code"
+            ]
+          },
+          "credential_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true,
+            "description": "Required for `passkey_prf`; the passkey id from `GET /v1/auth/passkeys`."
+          },
+          "wrapped_share": {
+            "type": "string",
+            "description": "Base64 ciphertext (≤ 4 KiB). Opaque to the vault."
+          },
+          "salt": {
+            "type": "string",
+            "description": "Base64 PRF salt, 16–64 random bytes, one per key."
+          }
+        }
+      },
+      "ClientShareResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "key_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "key_kind": {
+            "type": "string",
+            "enum": [
+              "agent_signing_key",
+              "treasury_wallet"
+            ]
+          },
+          "wrap_kind": {
+            "type": "string",
+            "enum": [
+              "passkey_prf",
+              "recovery_code"
+            ]
+          },
+          "credential_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "wrapped_share": {
+            "type": "string",
+            "description": "Base64, exactly as stored."
+          },
+          "salt": {
+            "type": "string",
+            "description": "Base64."
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ClientShareListResponse": {
+        "type": "object",
+        "properties": {
+          "key_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "key_kind": {
+            "type": "string",
+            "enum": [
+              "agent_signing_key",
+              "treasury_wallet"
+            ]
+          },
+          "custody": {
+            "type": "string",
+            "enum": [
+              "server",
+              "client_tss"
+            ],
+            "description": "`server` — 1claw holds the whole private key and can sign alone.\n`client_tss` — 2-party threshold key; the customer's share is required.\n"
+          },
+          "shares": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ClientShareResponse"
+            }
           }
         }
       },

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.17"
+    version: "0.61.18"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -80,6 +80,8 @@ tags:
       description: Multi-sig treasury wallets (Safe) and agent access requests
     - name: Treasury Wallets
       description: Multi-chain wallet generation for human users (replaces CDP embedded wallets)
+    - name: Key Custody
+      description: Customer-held key shares for non-custodial (threshold) signing keys
     - name: Admin
       description: Platform administration
     - name: Health
@@ -801,6 +803,13 @@ paths:
                                                     type: string
                                                 created_at:
                                                     type: string
+                                                prf_supported:
+                                                    type: boolean
+                                                    nullable: true
+                                                    description: |
+                                                        `true` — can hold a wallet share (WebAuthn PRF).
+                                                        `false` — cannot. `null` — registered before this
+                                                        was captured.
 
     /v1/auth/passkeys/{passkey_id}:
         delete:
@@ -5442,6 +5451,152 @@ paths:
     # Treasury Wallets (multi-chain key generation for human users)
     # ---------------------------------------------------------------------------
 
+    /v1/keys/{key_id}/client-share:
+        parameters:
+            - name: key_id
+              in: path
+              required: true
+              description: A treasury wallet id or an agent signing key id owned by the caller's org
+              schema:
+                  type: string
+                  format: uuid
+        put:
+            tags: [Key Custody]
+            summary: Store the customer's wrapped share of a threshold key
+            description: |
+                Stores ciphertext the vault cannot open: the customer's share of a
+                2-party threshold signing key, wrapped in the browser under the
+                passkey's WebAuthn PRF output (`passkey_prf`, one wrap per credential)
+                or under a recovery code (`recovery_code`, one per key). The vault
+                keeps the blob and its salt and returns them only to the owning user.
+                Human users only; the passkey must have reported PRF support at
+                registration. Idempotent per (key, credential).
+            operationId: putClientKeyShare
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/PutClientShareRequest"
+            responses:
+                "201":
+                    description: Share stored
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ClientShareResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        get:
+            tags: [Key Custody]
+            summary: List the caller's wrapped shares for a key
+            description: |
+                Returns every wrap on file for this key, unopened, to the user who
+                stored them. `custody` tells you whether the key is `server` (1claw
+                holds the whole private key) or `client_tss` (threshold; neither party
+                can sign alone). Funding a `client_tss` wallet needs at least two wraps.
+            operationId: listClientKeyShares
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: Wraps on file
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ClientShareListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/keys/{key_id}/client-share/rewrap:
+        parameters:
+            - name: key_id
+              in: path
+              required: true
+              schema:
+                  type: string
+                  format: uuid
+        post:
+            tags: [Key Custody]
+            summary: Add a wrap for another credential or the recovery code
+            description: |
+                Same write as `PUT …/client-share`, for a key that already has at
+                least one wrap: the browser, holding the share in memory during a
+                passkey session, re-wraps it under a newly added passkey's PRF
+                output or under the recovery code. 409 if no wrap exists yet.
+            operationId: rewrapClientKeyShare
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/PutClientShareRequest"
+            responses:
+                "201":
+                    description: Wrap added
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ClientShareResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "409":
+                    $ref: "#/components/responses/Conflict"
+
+    /v1/keys/{key_id}/client-share/{share_id}:
+        parameters:
+            - name: key_id
+              in: path
+              required: true
+              schema:
+                  type: string
+                  format: uuid
+            - name: share_id
+              in: path
+              required: true
+              schema:
+                  type: string
+                  format: uuid
+        delete:
+            tags: [Key Custody]
+            summary: Remove one wrap
+            description: |
+                Deletes a single wrap. Wraps tied to a passkey are also removed when
+                that passkey is deleted. Removing the last wrap of a `client_tss` key
+                makes the key unrecoverable — the vault holds only its own share.
+            operationId: deleteClientKeyShare
+            security:
+                - BearerAuth: []
+            responses:
+                "204":
+                    description: Wrap removed
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/treasury/wallets/generate:
         post:
             tags: [Treasury Wallets]
@@ -20764,6 +20919,12 @@ components:
                     type: string
                     format: date-time
                     nullable: true
+                custody:
+                    type: string
+                    enum: [server, client_tss]
+                    description: |
+                        `server` — 1claw holds the whole private key and can sign alone.
+                        `client_tss` — 2-party threshold key; the customer's passkey share is required.
 
         SigningKeyListResponse:
             type: object
@@ -22537,6 +22698,12 @@ components:
                 created_at:
                     type: string
                     format: date-time
+                custody:
+                    type: string
+                    enum: [server, client_tss]
+                    description: |
+                        `server` — 1claw holds the whole private key and can sign alone.
+                        `client_tss` — 2-party threshold key; the customer's passkey share is required.
 
         TreasuryWalletListResponse:
             type: object
@@ -24912,6 +25079,84 @@ components:
                         type: string
                 name:
                     type: string
+                prf_supported:
+                    type: boolean
+                    nullable: true
+                    description: |
+                        `prf.enabled` from `credential.getClientExtensionResults()` —
+                        whether this authenticator can derive the secret that wraps a
+                        wallet share. Omit if the client did not request the extension.
+
+        PutClientShareRequest:
+            type: object
+            required: [wrap_kind, wrapped_share, salt]
+            properties:
+                wrap_kind:
+                    type: string
+                    enum: [passkey_prf, recovery_code]
+                credential_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                    description: Required for `passkey_prf`; the passkey id from `GET /v1/auth/passkeys`.
+                wrapped_share:
+                    type: string
+                    description: Base64 ciphertext (≤ 4 KiB). Opaque to the vault.
+                salt:
+                    type: string
+                    description: Base64 PRF salt, 16–64 random bytes, one per key.
+
+        ClientShareResponse:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                key_id:
+                    type: string
+                    format: uuid
+                key_kind:
+                    type: string
+                    enum: [agent_signing_key, treasury_wallet]
+                wrap_kind:
+                    type: string
+                    enum: [passkey_prf, recovery_code]
+                credential_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                wrapped_share:
+                    type: string
+                    description: Base64, exactly as stored.
+                salt:
+                    type: string
+                    description: Base64.
+                created_at:
+                    type: string
+                    format: date-time
+                updated_at:
+                    type: string
+                    format: date-time
+
+        ClientShareListResponse:
+            type: object
+            properties:
+                key_id:
+                    type: string
+                    format: uuid
+                key_kind:
+                    type: string
+                    enum: [agent_signing_key, treasury_wallet]
+                custody:
+                    type: string
+                    enum: [server, client_tss]
+                    description: |
+                        `server` — 1claw holds the whole private key and can sign alone.
+                        `client_tss` — 2-party threshold key; the customer's share is required.
+                shares:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/ClientShareResponse"
 
         PasskeyRegisterCompleteResponse:
             type: object

package/package.json

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