@1claw/openapi-spec 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +3 -3
  2. package/openapi.json +281 -2
  3. package/openapi.yaml +195 -2
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -40,14 +40,14 @@ openapi-generator generate \
40
40
  import spec from "@1claw/openapi-spec/openapi.json";
41
41
  ```
42
42
 
43
- ## What's in the spec (v0.17.x)
43
+ ## What's in the spec (v0.18.0)
44
44
 
45
45
  - **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.
46
46
  - **Auth — password reset** — `POST /v1/auth/forgot-password`, `POST /v1/auth/reset-password` (public; anti-enumeration on forgot)
47
47
  - **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)
48
48
  - **Treasury** — Safe multisig treasuries: `POST/GET /v1/treasury`, `GET/PATCH/DELETE /v1/treasury/{id}`, signers, agent access requests (`requests[]` on list)
49
- - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking
50
- - **Secrets** — CRUD, versioning, CMEK-encrypted flag
49
+ - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking, MPC enable/disable (`POST /v1/vaults/{id}/mpc`, `DELETE /v1/vaults/{id}/mpc`)
50
+ - **Secrets** — CRUD, versioning, CMEK-encrypted flag, `client_share` in responses (MPC vaults)
51
51
  - **Agents** — CRUD with `auth_method` (api_key, mtls, oidc_client_credentials), auto-generated SSH keypairs, `token_ttl_seconds`, `vault_ids`, Intents API, transaction guardrails
52
52
  - **Policies** — Glob-based access control
53
53
  - **Sharing** — Links, user/agent shares, accept/decline
package/openapi.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "openapi": "3.1.0",
3
3
  "info": {
4
4
  "title": "1Claw API",
5
- "version": "2.7.0",
5
+ "version": "2.8.0",
6
6
  "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",
7
7
  "contact": {
8
8
  "email": "ops@1claw.xyz"
@@ -1221,6 +1221,52 @@
1221
1221
  }
1222
1222
  }
1223
1223
  },
1224
+ "/v1/vaults/{vault_id}/mpc": {
1225
+ "post": {
1226
+ "tags": [
1227
+ "Vaults"
1228
+ ],
1229
+ "summary": "Enable MPC custody on a vault",
1230
+ "operationId": "enableMpc",
1231
+ "description": "Enable MPC custody on an existing vault. Requires Business or Enterprise plan.\nSplits secret encryption keys across multiple providers using the specified\ncustody mode (e.g. 2-of-2, 2-of-3).\n",
1232
+ "parameters": [
1233
+ {
1234
+ "$ref": "#/components/parameters/VaultId"
1235
+ }
1236
+ ],
1237
+ "requestBody": {
1238
+ "required": true,
1239
+ "content": {
1240
+ "application/json": {
1241
+ "schema": {
1242
+ "$ref": "#/components/schemas/EnableMpcRequest"
1243
+ }
1244
+ }
1245
+ }
1246
+ },
1247
+ "responses": {
1248
+ "200": {
1249
+ "description": "MPC custody enabled",
1250
+ "content": {
1251
+ "application/json": {
1252
+ "schema": {
1253
+ "$ref": "#/components/schemas/VaultResponse"
1254
+ }
1255
+ }
1256
+ }
1257
+ },
1258
+ "400": {
1259
+ "$ref": "#/components/responses/BadRequest"
1260
+ },
1261
+ "403": {
1262
+ "$ref": "#/components/responses/Forbidden"
1263
+ },
1264
+ "404": {
1265
+ "$ref": "#/components/responses/NotFound"
1266
+ }
1267
+ }
1268
+ }
1269
+ },
1224
1270
  "/v1/vaults/{vault_id}/secrets": {
1225
1271
  "get": {
1226
1272
  "tags": [
@@ -1299,7 +1345,7 @@
1299
1345
  "content": {
1300
1346
  "application/json": {
1301
1347
  "schema": {
1302
- "$ref": "#/components/schemas/SecretMetadataResponse"
1348
+ "$ref": "#/components/schemas/SecretCreatedResponse"
1303
1349
  }
1304
1350
  }
1305
1351
  }
@@ -1334,6 +1380,15 @@
1334
1380
  },
1335
1381
  {
1336
1382
  "$ref": "#/components/parameters/SecretPath"
1383
+ },
1384
+ {
1385
+ "name": "x-client-share",
1386
+ "in": "header",
1387
+ "required": false,
1388
+ "schema": {
1389
+ "type": "string"
1390
+ },
1391
+ "description": "Base64-encoded client key share for MPC 2-of-2 vaults. Required when the vault uses 2-of-2 MPC custody."
1337
1392
  }
1338
1393
  ],
1339
1394
  "responses": {
@@ -4133,6 +4188,55 @@
4133
4188
  }
4134
4189
  }
4135
4190
  }
4191
+ },
4192
+ "/v1/shroud/threat-summary": {
4193
+ "get": {
4194
+ "tags": [
4195
+ "Shroud"
4196
+ ],
4197
+ "summary": "Shroud threat analytics summary",
4198
+ "description": "Aggregated threat metrics for the organization from `shroud_activity` (detectors, blocked counts, recent flagged requests). Query `period` selects the window; the previous window of equal length is used for request volume trend.\n",
4199
+ "security": [
4200
+ {
4201
+ "BearerAuth": []
4202
+ }
4203
+ ],
4204
+ "parameters": [
4205
+ {
4206
+ "in": "query",
4207
+ "name": "period",
4208
+ "schema": {
4209
+ "type": "string",
4210
+ "enum": [
4211
+ "1h",
4212
+ "24h",
4213
+ "7d",
4214
+ "30d"
4215
+ ],
4216
+ "default": "24h"
4217
+ },
4218
+ "description": "Rolling window ending now"
4219
+ }
4220
+ ],
4221
+ "responses": {
4222
+ "200": {
4223
+ "description": "Threat summary",
4224
+ "content": {
4225
+ "application/json": {
4226
+ "schema": {
4227
+ "$ref": "#/components/schemas/ShroudThreatSummary"
4228
+ }
4229
+ }
4230
+ }
4231
+ },
4232
+ "400": {
4233
+ "description": "Invalid period"
4234
+ },
4235
+ "401": {
4236
+ "description": "Unauthorized"
4237
+ }
4238
+ }
4239
+ }
4136
4240
  }
4137
4241
  },
4138
4242
  "components": {
@@ -4810,6 +4914,10 @@
4810
4914
  },
4811
4915
  "description": {
4812
4916
  "type": "string"
4917
+ },
4918
+ "mpc_custody": {
4919
+ "type": "string",
4920
+ "description": "MPC custody mode to enable at creation (e.g. \"2-of-2\", \"2-of-3\")"
4813
4921
  }
4814
4922
  }
4815
4923
  },
@@ -4848,6 +4956,21 @@
4848
4956
  "cmek_fingerprint": {
4849
4957
  "type": "string",
4850
4958
  "description": "SHA-256 fingerprint of the CMEK key (64 hex chars)"
4959
+ },
4960
+ "mpc_custody": {
4961
+ "type": "string",
4962
+ "description": "MPC custody mode (e.g. \"2-of-2\", \"2-of-3\"), absent when MPC is not enabled"
4963
+ },
4964
+ "mpc_threshold": {
4965
+ "type": "integer",
4966
+ "description": "Number of shares required to reconstruct the key"
4967
+ },
4968
+ "mpc_providers": {
4969
+ "type": "array",
4970
+ "items": {
4971
+ "type": "string"
4972
+ },
4973
+ "description": "List of MPC share providers (e.g. [\"server\", \"client\"])"
4851
4974
  }
4852
4975
  }
4853
4976
  },
@@ -4943,6 +5066,18 @@
4943
5066
  }
4944
5067
  }
4945
5068
  },
5069
+ "EnableMpcRequest": {
5070
+ "type": "object",
5071
+ "required": [
5072
+ "mpc_custody"
5073
+ ],
5074
+ "properties": {
5075
+ "mpc_custody": {
5076
+ "type": "string",
5077
+ "description": "MPC custody mode (e.g. \"2-of-2\", \"2-of-3\")"
5078
+ }
5079
+ }
5080
+ },
4946
5081
  "PutSecretRequest": {
4947
5082
  "type": "object",
4948
5083
  "required": [
@@ -5011,6 +5146,48 @@
5011
5146
  }
5012
5147
  }
5013
5148
  },
5149
+ "SecretCreatedResponse": {
5150
+ "description": "Returned when a secret is created or updated. Extends SecretMetadataResponse with an optional client_share for MPC vaults.",
5151
+ "type": "object",
5152
+ "required": [
5153
+ "id",
5154
+ "path",
5155
+ "type",
5156
+ "version",
5157
+ "created_at"
5158
+ ],
5159
+ "properties": {
5160
+ "id": {
5161
+ "type": "string",
5162
+ "format": "uuid"
5163
+ },
5164
+ "path": {
5165
+ "type": "string"
5166
+ },
5167
+ "type": {
5168
+ "type": "string"
5169
+ },
5170
+ "version": {
5171
+ "type": "integer"
5172
+ },
5173
+ "metadata": {
5174
+ "type": "object",
5175
+ "additionalProperties": true
5176
+ },
5177
+ "created_at": {
5178
+ "type": "string",
5179
+ "format": "date-time"
5180
+ },
5181
+ "expires_at": {
5182
+ "type": "string",
5183
+ "format": "date-time"
5184
+ },
5185
+ "client_share": {
5186
+ "type": "string",
5187
+ "description": "Base64-encoded client key share. Returned only for MPC 2-of-2 vaults. The client must store this share securely — it is not persisted server-side."
5188
+ }
5189
+ }
5190
+ },
5014
5191
  "SecretResponse": {
5015
5192
  "type": "object",
5016
5193
  "required": [
@@ -7934,6 +8111,108 @@
7934
8111
  }
7935
8112
  }
7936
8113
  },
8114
+ "ShroudThreatSummary": {
8115
+ "type": "object",
8116
+ "properties": {
8117
+ "total_requests": {
8118
+ "type": "integer",
8119
+ "format": "int64"
8120
+ },
8121
+ "total_requests_prev": {
8122
+ "type": "integer",
8123
+ "format": "int64"
8124
+ },
8125
+ "blocked_requests": {
8126
+ "type": "integer",
8127
+ "format": "int64"
8128
+ },
8129
+ "detectors_triggered": {
8130
+ "type": "integer",
8131
+ "format": "int64"
8132
+ },
8133
+ "active_agents": {
8134
+ "type": "integer",
8135
+ "format": "int64"
8136
+ },
8137
+ "detectors": {
8138
+ "type": "array",
8139
+ "items": {
8140
+ "$ref": "#/components/schemas/ShroudDetectorStats"
8141
+ }
8142
+ },
8143
+ "flagged_requests": {
8144
+ "type": "array",
8145
+ "items": {
8146
+ "$ref": "#/components/schemas/ShroudFlaggedRequest"
8147
+ }
8148
+ }
8149
+ }
8150
+ },
8151
+ "ShroudDetectorStats": {
8152
+ "type": "object",
8153
+ "properties": {
8154
+ "detector": {
8155
+ "type": "string"
8156
+ },
8157
+ "detections": {
8158
+ "type": "integer",
8159
+ "format": "int64"
8160
+ },
8161
+ "blocks": {
8162
+ "type": "integer",
8163
+ "format": "int64"
8164
+ },
8165
+ "actions": {
8166
+ "type": "object",
8167
+ "properties": {
8168
+ "blocked": {
8169
+ "type": "integer",
8170
+ "format": "int64"
8171
+ },
8172
+ "warned": {
8173
+ "type": "integer",
8174
+ "format": "int64"
8175
+ },
8176
+ "logged": {
8177
+ "type": "integer",
8178
+ "format": "int64"
8179
+ }
8180
+ }
8181
+ }
8182
+ }
8183
+ },
8184
+ "ShroudFlaggedRequest": {
8185
+ "type": "object",
8186
+ "properties": {
8187
+ "id": {
8188
+ "type": "string"
8189
+ },
8190
+ "timestamp": {
8191
+ "type": "string",
8192
+ "format": "date-time"
8193
+ },
8194
+ "agent_id": {
8195
+ "type": "string"
8196
+ },
8197
+ "agent_name": {
8198
+ "type": "string"
8199
+ },
8200
+ "score": {
8201
+ "type": "number"
8202
+ },
8203
+ "reason": {
8204
+ "type": "string"
8205
+ },
8206
+ "action": {
8207
+ "type": "string",
8208
+ "enum": [
8209
+ "blocked",
8210
+ "warned",
8211
+ "logged"
8212
+ ]
8213
+ }
8214
+ }
8215
+ },
7937
8216
  "HealthResponse": {
7938
8217
  "type": "object",
7939
8218
  "properties": {
package/openapi.yaml CHANGED
@@ -2,7 +2,7 @@ openapi: 3.1.0
2
2
 
3
3
  info:
4
4
  title: 1Claw API
5
- version: 2.7.0
5
+ version: 2.8.0
6
6
  description: |
7
7
  Secure secret management for AI agents. Provides vaults, secrets,
8
8
  policy-based access control, agent identity, Intents API,
@@ -802,6 +802,41 @@ paths:
802
802
  "404":
803
803
  $ref: "#/components/responses/NotFound"
804
804
 
805
+ # ---------------------------------------------------------------------------
806
+ # MPC
807
+ # ---------------------------------------------------------------------------
808
+
809
+ /v1/vaults/{vault_id}/mpc:
810
+ post:
811
+ tags: [Vaults]
812
+ summary: Enable MPC custody on a vault
813
+ operationId: enableMpc
814
+ description: |
815
+ Enable MPC custody on an existing vault. Requires Business or Enterprise plan.
816
+ Splits secret encryption keys across multiple providers using the specified
817
+ custody mode (e.g. 2-of-2, 2-of-3).
818
+ parameters:
819
+ - $ref: "#/components/parameters/VaultId"
820
+ requestBody:
821
+ required: true
822
+ content:
823
+ application/json:
824
+ schema:
825
+ $ref: "#/components/schemas/EnableMpcRequest"
826
+ responses:
827
+ "200":
828
+ description: MPC custody enabled
829
+ content:
830
+ application/json:
831
+ schema:
832
+ $ref: "#/components/schemas/VaultResponse"
833
+ "400":
834
+ $ref: "#/components/responses/BadRequest"
835
+ "403":
836
+ $ref: "#/components/responses/Forbidden"
837
+ "404":
838
+ $ref: "#/components/responses/NotFound"
839
+
805
840
  # ---------------------------------------------------------------------------
806
841
  # Secrets
807
842
  # ---------------------------------------------------------------------------
@@ -854,7 +889,7 @@ paths:
854
889
  content:
855
890
  application/json:
856
891
  schema:
857
- $ref: "#/components/schemas/SecretMetadataResponse"
892
+ $ref: "#/components/schemas/SecretCreatedResponse"
858
893
  "400":
859
894
  $ref: "#/components/responses/BadRequest"
860
895
  "402":
@@ -872,6 +907,12 @@ paths:
872
907
  parameters:
873
908
  - $ref: "#/components/parameters/VaultId"
874
909
  - $ref: "#/components/parameters/SecretPath"
910
+ - name: x-client-share
911
+ in: header
912
+ required: false
913
+ schema:
914
+ type: string
915
+ description: Base64-encoded client key share for MPC 2-of-2 vaults. Required when the vault uses 2-of-2 MPC custody.
875
916
  responses:
876
917
  "200":
877
918
  description: Decrypted secret value
@@ -2663,6 +2704,36 @@ paths:
2663
2704
  "401":
2664
2705
  description: Unauthorized
2665
2706
 
2707
+ /v1/shroud/threat-summary:
2708
+ get:
2709
+ tags: [Shroud]
2710
+ summary: Shroud threat analytics summary
2711
+ description: >
2712
+ Aggregated threat metrics for the organization from `shroud_activity`
2713
+ (detectors, blocked counts, recent flagged requests). Query `period` selects
2714
+ the window; the previous window of equal length is used for request volume trend.
2715
+ security:
2716
+ - BearerAuth: []
2717
+ parameters:
2718
+ - in: query
2719
+ name: period
2720
+ schema:
2721
+ type: string
2722
+ enum: [1h, 24h, 7d, 30d]
2723
+ default: 24h
2724
+ description: Rolling window ending now
2725
+ responses:
2726
+ "200":
2727
+ description: Threat summary
2728
+ content:
2729
+ application/json:
2730
+ schema:
2731
+ $ref: "#/components/schemas/ShroudThreatSummary"
2732
+ "400":
2733
+ description: Invalid period
2734
+ "401":
2735
+ description: Unauthorized
2736
+
2666
2737
  # =============================================================================
2667
2738
  # COMPONENTS
2668
2739
  # =============================================================================
@@ -3143,6 +3214,9 @@ components:
3143
3214
  type: string
3144
3215
  description:
3145
3216
  type: string
3217
+ mpc_custody:
3218
+ type: string
3219
+ description: MPC custody mode to enable at creation (e.g. "2-of-2", "2-of-3")
3146
3220
 
3147
3221
  VaultResponse:
3148
3222
  type: object
@@ -3168,6 +3242,17 @@ components:
3168
3242
  cmek_fingerprint:
3169
3243
  type: string
3170
3244
  description: SHA-256 fingerprint of the CMEK key (64 hex chars)
3245
+ mpc_custody:
3246
+ type: string
3247
+ description: MPC custody mode (e.g. "2-of-2", "2-of-3"), absent when MPC is not enabled
3248
+ mpc_threshold:
3249
+ type: integer
3250
+ description: Number of shares required to reconstruct the key
3251
+ mpc_providers:
3252
+ type: array
3253
+ items:
3254
+ type: string
3255
+ description: List of MPC share providers (e.g. ["server", "client"])
3171
3256
 
3172
3257
  VaultListResponse:
3173
3258
  type: object
@@ -3229,6 +3314,16 @@ components:
3229
3314
  type: string
3230
3315
  format: date-time
3231
3316
 
3317
+ # --- MPC ---
3318
+
3319
+ EnableMpcRequest:
3320
+ type: object
3321
+ required: [mpc_custody]
3322
+ properties:
3323
+ mpc_custody:
3324
+ type: string
3325
+ description: MPC custody mode (e.g. "2-of-2", "2-of-3")
3326
+
3232
3327
  # --- Secrets ---
3233
3328
 
3234
3329
  PutSecretRequest:
@@ -3276,6 +3371,33 @@ components:
3276
3371
  type: string
3277
3372
  format: date-time
3278
3373
 
3374
+ SecretCreatedResponse:
3375
+ description: Returned when a secret is created or updated. Extends SecretMetadataResponse with an optional client_share for MPC vaults.
3376
+ type: object
3377
+ required: [id, path, type, version, created_at]
3378
+ properties:
3379
+ id:
3380
+ type: string
3381
+ format: uuid
3382
+ path:
3383
+ type: string
3384
+ type:
3385
+ type: string
3386
+ version:
3387
+ type: integer
3388
+ metadata:
3389
+ type: object
3390
+ additionalProperties: true
3391
+ created_at:
3392
+ type: string
3393
+ format: date-time
3394
+ expires_at:
3395
+ type: string
3396
+ format: date-time
3397
+ client_share:
3398
+ type: string
3399
+ description: Base64-encoded client key share. Returned only for MPC 2-of-2 vaults. The client must store this share securely — it is not persisted server-side.
3400
+
3279
3401
  SecretResponse:
3280
3402
  type: object
3281
3403
  required: [id, path, type, value, version, created_at]
@@ -5298,6 +5420,77 @@ components:
5298
5420
  metadata:
5299
5421
  type: object
5300
5422
 
5423
+ ShroudThreatSummary:
5424
+ type: object
5425
+ properties:
5426
+ total_requests:
5427
+ type: integer
5428
+ format: int64
5429
+ total_requests_prev:
5430
+ type: integer
5431
+ format: int64
5432
+ blocked_requests:
5433
+ type: integer
5434
+ format: int64
5435
+ detectors_triggered:
5436
+ type: integer
5437
+ format: int64
5438
+ active_agents:
5439
+ type: integer
5440
+ format: int64
5441
+ detectors:
5442
+ type: array
5443
+ items:
5444
+ $ref: "#/components/schemas/ShroudDetectorStats"
5445
+ flagged_requests:
5446
+ type: array
5447
+ items:
5448
+ $ref: "#/components/schemas/ShroudFlaggedRequest"
5449
+
5450
+ ShroudDetectorStats:
5451
+ type: object
5452
+ properties:
5453
+ detector:
5454
+ type: string
5455
+ detections:
5456
+ type: integer
5457
+ format: int64
5458
+ blocks:
5459
+ type: integer
5460
+ format: int64
5461
+ actions:
5462
+ type: object
5463
+ properties:
5464
+ blocked:
5465
+ type: integer
5466
+ format: int64
5467
+ warned:
5468
+ type: integer
5469
+ format: int64
5470
+ logged:
5471
+ type: integer
5472
+ format: int64
5473
+
5474
+ ShroudFlaggedRequest:
5475
+ type: object
5476
+ properties:
5477
+ id:
5478
+ type: string
5479
+ timestamp:
5480
+ type: string
5481
+ format: date-time
5482
+ agent_id:
5483
+ type: string
5484
+ agent_name:
5485
+ type: string
5486
+ score:
5487
+ type: number
5488
+ reason:
5489
+ type: string
5490
+ action:
5491
+ type: string
5492
+ enum: [blocked, warned, logged]
5493
+
5301
5494
  # --- Health ---
5302
5495
 
5303
5496
  HealthResponse:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1claw/openapi-spec",
3
- "version": "0.17.0",
3
+ "version": "0.18.0",
4
4
  "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
5
5
  "license": "MIT",
6
6
  "repository": {