@1claw/openapi-spec 0.23.0 → 0.23.2

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 (3) hide show
  1. package/openapi.json +263 -2
  2. package/openapi.yaml +187 -2
  3. package/package.json +1 -1
package/openapi.json CHANGED
@@ -2787,6 +2787,89 @@
2787
2787
  }
2788
2788
  }
2789
2789
  },
2790
+ "/v1/agents/{agent_id}/signing-keys/{chain}/export": {
2791
+ "post": {
2792
+ "tags": [
2793
+ "Signing Keys"
2794
+ ],
2795
+ "summary": "Export a signing key (private key included)",
2796
+ "description": "Export the private key for an agent's signing key. Requires re-authentication\nvia the X-Auth-Confirm header containing the user's account password.\nHuman users only — agents cannot export keys.\n",
2797
+ "operationId": "exportSigningKey",
2798
+ "parameters": [
2799
+ {
2800
+ "$ref": "#/components/parameters/AgentId"
2801
+ },
2802
+ {
2803
+ "name": "chain",
2804
+ "in": "path",
2805
+ "required": true,
2806
+ "schema": {
2807
+ "type": "string"
2808
+ }
2809
+ },
2810
+ {
2811
+ "name": "X-Auth-Confirm",
2812
+ "in": "header",
2813
+ "required": true,
2814
+ "description": "Account password for re-authentication",
2815
+ "schema": {
2816
+ "type": "string",
2817
+ "format": "password"
2818
+ }
2819
+ }
2820
+ ],
2821
+ "responses": {
2822
+ "200": {
2823
+ "description": "Signing key exported successfully",
2824
+ "content": {
2825
+ "application/json": {
2826
+ "schema": {
2827
+ "type": "object",
2828
+ "required": [
2829
+ "chain",
2830
+ "curve",
2831
+ "public_key",
2832
+ "private_key",
2833
+ "key_version",
2834
+ "agent_id"
2835
+ ],
2836
+ "properties": {
2837
+ "chain": {
2838
+ "type": "string"
2839
+ },
2840
+ "curve": {
2841
+ "type": "string"
2842
+ },
2843
+ "public_key": {
2844
+ "type": "string"
2845
+ },
2846
+ "address": {
2847
+ "type": "string"
2848
+ },
2849
+ "private_key": {
2850
+ "type": "string"
2851
+ },
2852
+ "key_version": {
2853
+ "type": "integer"
2854
+ },
2855
+ "agent_id": {
2856
+ "type": "string",
2857
+ "format": "uuid"
2858
+ }
2859
+ }
2860
+ }
2861
+ }
2862
+ }
2863
+ },
2864
+ "403": {
2865
+ "$ref": "#/components/responses/Forbidden"
2866
+ },
2867
+ "404": {
2868
+ "$ref": "#/components/responses/NotFound"
2869
+ }
2870
+ }
2871
+ }
2872
+ },
2790
2873
  "/v1/agents/{agent_id}/sign": {
2791
2874
  "post": {
2792
2875
  "tags": [
@@ -4472,7 +4555,7 @@
4472
4555
  "Treasury Wallets"
4473
4556
  ],
4474
4557
  "summary": "Export the private key for a treasury wallet",
4475
- "description": "Returns the raw private key hex for the user's active wallet on\nthe given chain. Audit-logged as `treasury_wallet.export`.\nHuman users only.\n",
4558
+ "description": "Returns the raw private key hex for the user's active wallet on\nthe given chain. Requires re-authentication via the `X-Auth-Confirm`\nheader (account password). Audit-logged as `treasury_wallet.export`.\nHuman users only.\n",
4476
4559
  "operationId": "exportTreasuryWallet",
4477
4560
  "security": [
4478
4561
  {
@@ -4487,6 +4570,16 @@
4487
4570
  "schema": {
4488
4571
  "type": "string"
4489
4572
  }
4573
+ },
4574
+ {
4575
+ "name": "X-Auth-Confirm",
4576
+ "in": "header",
4577
+ "required": true,
4578
+ "description": "Account password for re-authentication",
4579
+ "schema": {
4580
+ "type": "string",
4581
+ "format": "password"
4582
+ }
4490
4583
  }
4491
4584
  ],
4492
4585
  "responses": {
@@ -5656,6 +5749,80 @@
5656
5749
  }
5657
5750
  }
5658
5751
  }
5752
+ },
5753
+ "/v1/platform/claim/{token}": {
5754
+ "get": {
5755
+ "tags": [
5756
+ "Platform"
5757
+ ],
5758
+ "summary": "Preview a claim token",
5759
+ "description": "Verify a claim token and preview what was provisioned (app name, vaults, agents, policies).\nPublic endpoint — the token itself is the authentication.\n",
5760
+ "parameters": [
5761
+ {
5762
+ "in": "path",
5763
+ "name": "token",
5764
+ "required": true,
5765
+ "schema": {
5766
+ "type": "string"
5767
+ },
5768
+ "description": "The `ct_` prefixed claim token from the bootstrap response"
5769
+ }
5770
+ ],
5771
+ "responses": {
5772
+ "200": {
5773
+ "description": "Claim preview",
5774
+ "content": {
5775
+ "application/json": {
5776
+ "schema": {
5777
+ "$ref": "#/components/schemas/ClaimPreviewResponse"
5778
+ }
5779
+ }
5780
+ }
5781
+ },
5782
+ "404": {
5783
+ "description": "Invalid or expired claim token"
5784
+ }
5785
+ }
5786
+ },
5787
+ "post": {
5788
+ "tags": [
5789
+ "Platform"
5790
+ ],
5791
+ "summary": "Redeem a claim token",
5792
+ "description": "Redeem a one-time claim token, marking the connection as claimed.\nPublic endpoint — the token itself is the authentication. Returns 409 if already claimed, 410 if expired.\n",
5793
+ "parameters": [
5794
+ {
5795
+ "in": "path",
5796
+ "name": "token",
5797
+ "required": true,
5798
+ "schema": {
5799
+ "type": "string"
5800
+ },
5801
+ "description": "The `ct_` prefixed claim token from the bootstrap response"
5802
+ }
5803
+ ],
5804
+ "responses": {
5805
+ "200": {
5806
+ "description": "Claim redeemed",
5807
+ "content": {
5808
+ "application/json": {
5809
+ "schema": {
5810
+ "$ref": "#/components/schemas/ClaimRedeemResponse"
5811
+ }
5812
+ }
5813
+ }
5814
+ },
5815
+ "404": {
5816
+ "description": "Invalid claim token"
5817
+ },
5818
+ "409": {
5819
+ "description": "Claim token already used"
5820
+ },
5821
+ "410": {
5822
+ "description": "Claim token has expired"
5823
+ }
5824
+ }
5825
+ }
5659
5826
  }
5660
5827
  },
5661
5828
  "components": {
@@ -10196,6 +10363,10 @@
10196
10363
  "type": "string",
10197
10364
  "format": "uri"
10198
10365
  },
10366
+ "oidc_audience": {
10367
+ "type": "string",
10368
+ "description": "Expected audience claim for OIDC token validation"
10369
+ },
10199
10370
  "redirect_uris": {
10200
10371
  "type": "array",
10201
10372
  "items": {
@@ -10245,6 +10416,10 @@
10245
10416
  "oidc_issuer": {
10246
10417
  "type": "string"
10247
10418
  },
10419
+ "oidc_audience": {
10420
+ "type": "string",
10421
+ "description": "Expected audience claim for OIDC token validation"
10422
+ },
10248
10423
  "redirect_uris": {
10249
10424
  "type": "array",
10250
10425
  "items": {
@@ -10310,6 +10485,11 @@
10310
10485
  "type": "string",
10311
10486
  "nullable": true
10312
10487
  },
10488
+ "oidc_audience": {
10489
+ "type": "string",
10490
+ "nullable": true,
10491
+ "description": "Expected audience claim for OIDC token validation"
10492
+ },
10313
10493
  "redirect_uris": {
10314
10494
  "type": "array",
10315
10495
  "items": {
@@ -10380,7 +10560,7 @@
10380
10560
  },
10381
10561
  "spec": {
10382
10562
  "type": "object",
10383
- "description": "Template specification defining vault, agents, and policies to bootstrap."
10563
+ "description": "Template specification defining vault, agents, policies, and signing keys to bootstrap.\nTop-level fields: `vault` (object with name, description), `agents` (array of agent specs\nwith name, description, shroud_enabled, intents, shroud_config), `policies` (array with\nvault_ref, principal_ref, paths, permissions, conditions), and `signing_keys` (array of\n`{ chain }` objects — supported chains: ethereum, bitcoin, solana, xrp, cardano, tron).\nWhen `signing_keys` is present, HSM-backed signing keys are auto-provisioned for the\nbootstrapped agent.\n"
10384
10564
  }
10385
10565
  }
10386
10566
  },
@@ -10594,6 +10774,87 @@
10594
10774
  "format": "date-time"
10595
10775
  }
10596
10776
  }
10777
+ },
10778
+ "ClaimPreviewResponse": {
10779
+ "type": "object",
10780
+ "properties": {
10781
+ "app_name": {
10782
+ "type": "string"
10783
+ },
10784
+ "app_slug": {
10785
+ "type": "string"
10786
+ },
10787
+ "app_logo_url": {
10788
+ "type": "string",
10789
+ "nullable": true
10790
+ },
10791
+ "auth_mode": {
10792
+ "type": "string"
10793
+ },
10794
+ "vault_ids": {
10795
+ "type": "array",
10796
+ "items": {
10797
+ "type": "string",
10798
+ "format": "uuid"
10799
+ }
10800
+ },
10801
+ "agent_ids": {
10802
+ "type": "array",
10803
+ "items": {
10804
+ "type": "string",
10805
+ "format": "uuid"
10806
+ }
10807
+ },
10808
+ "policy_count": {
10809
+ "type": "integer"
10810
+ },
10811
+ "status": {
10812
+ "type": "string"
10813
+ },
10814
+ "already_claimed": {
10815
+ "type": "boolean"
10816
+ },
10817
+ "expired": {
10818
+ "type": "boolean"
10819
+ },
10820
+ "return_to": {
10821
+ "type": "string",
10822
+ "nullable": true
10823
+ }
10824
+ }
10825
+ },
10826
+ "ClaimRedeemResponse": {
10827
+ "type": "object",
10828
+ "properties": {
10829
+ "status": {
10830
+ "type": "string"
10831
+ },
10832
+ "connection_id": {
10833
+ "type": "string",
10834
+ "format": "uuid"
10835
+ },
10836
+ "vault_ids": {
10837
+ "type": "array",
10838
+ "items": {
10839
+ "type": "string",
10840
+ "format": "uuid"
10841
+ }
10842
+ },
10843
+ "agent_ids": {
10844
+ "type": "array",
10845
+ "items": {
10846
+ "type": "string",
10847
+ "format": "uuid"
10848
+ }
10849
+ },
10850
+ "return_to": {
10851
+ "type": "string",
10852
+ "nullable": true
10853
+ },
10854
+ "dashboard_url": {
10855
+ "type": "string"
10856
+ }
10857
+ }
10597
10858
  }
10598
10859
  }
10599
10860
  }
package/openapi.yaml CHANGED
@@ -1845,6 +1845,58 @@ paths:
1845
1845
  "404":
1846
1846
  $ref: "#/components/responses/NotFound"
1847
1847
 
1848
+ /v1/agents/{agent_id}/signing-keys/{chain}/export:
1849
+ post:
1850
+ tags: [Signing Keys]
1851
+ summary: Export a signing key (private key included)
1852
+ description: |
1853
+ Export the private key for an agent's signing key. Requires re-authentication
1854
+ via the X-Auth-Confirm header containing the user's account password.
1855
+ Human users only — agents cannot export keys.
1856
+ operationId: exportSigningKey
1857
+ parameters:
1858
+ - $ref: "#/components/parameters/AgentId"
1859
+ - name: chain
1860
+ in: path
1861
+ required: true
1862
+ schema:
1863
+ type: string
1864
+ - name: X-Auth-Confirm
1865
+ in: header
1866
+ required: true
1867
+ description: Account password for re-authentication
1868
+ schema:
1869
+ type: string
1870
+ format: password
1871
+ responses:
1872
+ "200":
1873
+ description: Signing key exported successfully
1874
+ content:
1875
+ application/json:
1876
+ schema:
1877
+ type: object
1878
+ required: [chain, curve, public_key, private_key, key_version, agent_id]
1879
+ properties:
1880
+ chain:
1881
+ type: string
1882
+ curve:
1883
+ type: string
1884
+ public_key:
1885
+ type: string
1886
+ address:
1887
+ type: string
1888
+ private_key:
1889
+ type: string
1890
+ key_version:
1891
+ type: integer
1892
+ agent_id:
1893
+ type: string
1894
+ format: uuid
1895
+ "403":
1896
+ $ref: "#/components/responses/Forbidden"
1897
+ "404":
1898
+ $ref: "#/components/responses/NotFound"
1899
+
1848
1900
  # ---------------------------------------------------------------------------
1849
1901
  # Unified Signing Intent
1850
1902
  # ---------------------------------------------------------------------------
@@ -2931,7 +2983,8 @@ paths:
2931
2983
  summary: Export the private key for a treasury wallet
2932
2984
  description: |
2933
2985
  Returns the raw private key hex for the user's active wallet on
2934
- the given chain. Audit-logged as `treasury_wallet.export`.
2986
+ the given chain. Requires re-authentication via the `X-Auth-Confirm`
2987
+ header (account password). Audit-logged as `treasury_wallet.export`.
2935
2988
  Human users only.
2936
2989
  operationId: exportTreasuryWallet
2937
2990
  security:
@@ -2942,6 +2995,13 @@ paths:
2942
2995
  required: true
2943
2996
  schema:
2944
2997
  type: string
2998
+ - name: X-Auth-Confirm
2999
+ in: header
3000
+ required: true
3001
+ description: Account password for re-authentication
3002
+ schema:
3003
+ type: string
3004
+ format: password
2945
3005
  responses:
2946
3006
  "200":
2947
3007
  description: Private key exported
@@ -3670,6 +3730,56 @@ paths:
3670
3730
  "404":
3671
3731
  description: Connection not found
3672
3732
 
3733
+ /v1/platform/claim/{token}:
3734
+ get:
3735
+ tags: [Platform]
3736
+ summary: Preview a claim token
3737
+ description: |
3738
+ Verify a claim token and preview what was provisioned (app name, vaults, agents, policies).
3739
+ Public endpoint — the token itself is the authentication.
3740
+ parameters:
3741
+ - in: path
3742
+ name: token
3743
+ required: true
3744
+ schema:
3745
+ type: string
3746
+ description: The `ct_` prefixed claim token from the bootstrap response
3747
+ responses:
3748
+ "200":
3749
+ description: Claim preview
3750
+ content:
3751
+ application/json:
3752
+ schema:
3753
+ $ref: "#/components/schemas/ClaimPreviewResponse"
3754
+ "404":
3755
+ description: Invalid or expired claim token
3756
+ post:
3757
+ tags: [Platform]
3758
+ summary: Redeem a claim token
3759
+ description: |
3760
+ Redeem a one-time claim token, marking the connection as claimed.
3761
+ Public endpoint — the token itself is the authentication. Returns 409 if already claimed, 410 if expired.
3762
+ parameters:
3763
+ - in: path
3764
+ name: token
3765
+ required: true
3766
+ schema:
3767
+ type: string
3768
+ description: The `ct_` prefixed claim token from the bootstrap response
3769
+ responses:
3770
+ "200":
3771
+ description: Claim redeemed
3772
+ content:
3773
+ application/json:
3774
+ schema:
3775
+ $ref: "#/components/schemas/ClaimRedeemResponse"
3776
+ "404":
3777
+ description: Invalid claim token
3778
+ "409":
3779
+ description: Claim token already used
3780
+ "410":
3781
+ description: Claim token has expired
3782
+
3673
3783
  # =============================================================================
3674
3784
  # COMPONENTS
3675
3785
  # =============================================================================
@@ -6848,6 +6958,9 @@ components:
6848
6958
  oidc_issuer:
6849
6959
  type: string
6850
6960
  format: uri
6961
+ oidc_audience:
6962
+ type: string
6963
+ description: Expected audience claim for OIDC token validation
6851
6964
  redirect_uris:
6852
6965
  type: array
6853
6966
  items:
@@ -6878,6 +6991,9 @@ components:
6878
6991
  type: string
6879
6992
  oidc_issuer:
6880
6993
  type: string
6994
+ oidc_audience:
6995
+ type: string
6996
+ description: Expected audience claim for OIDC token validation
6881
6997
  redirect_uris:
6882
6998
  type: array
6883
6999
  items:
@@ -6919,6 +7035,10 @@ components:
6919
7035
  oidc_issuer:
6920
7036
  type: string
6921
7037
  nullable: true
7038
+ oidc_audience:
7039
+ type: string
7040
+ nullable: true
7041
+ description: Expected audience claim for OIDC token validation
6922
7042
  redirect_uris:
6923
7043
  type: array
6924
7044
  items:
@@ -6964,7 +7084,14 @@ components:
6964
7084
  type: string
6965
7085
  spec:
6966
7086
  type: object
6967
- description: Template specification defining vault, agents, and policies to bootstrap.
7087
+ description: |
7088
+ Template specification defining vault, agents, policies, and signing keys to bootstrap.
7089
+ Top-level fields: `vault` (object with name, description), `agents` (array of agent specs
7090
+ with name, description, shroud_enabled, intents, shroud_config), `policies` (array with
7091
+ vault_ref, principal_ref, paths, permissions, conditions), and `signing_keys` (array of
7092
+ `{ chain }` objects — supported chains: ethereum, bitcoin, solana, xrp, cardano, tron).
7093
+ When `signing_keys` is present, HSM-backed signing keys are auto-provisioned for the
7094
+ bootstrapped agent.
6968
7095
 
6969
7096
  PlatformTemplateResponse:
6970
7097
  type: object
@@ -7121,3 +7248,61 @@ components:
7121
7248
  created_at:
7122
7249
  type: string
7123
7250
  format: date-time
7251
+
7252
+ ClaimPreviewResponse:
7253
+ type: object
7254
+ properties:
7255
+ app_name:
7256
+ type: string
7257
+ app_slug:
7258
+ type: string
7259
+ app_logo_url:
7260
+ type: string
7261
+ nullable: true
7262
+ auth_mode:
7263
+ type: string
7264
+ vault_ids:
7265
+ type: array
7266
+ items:
7267
+ type: string
7268
+ format: uuid
7269
+ agent_ids:
7270
+ type: array
7271
+ items:
7272
+ type: string
7273
+ format: uuid
7274
+ policy_count:
7275
+ type: integer
7276
+ status:
7277
+ type: string
7278
+ already_claimed:
7279
+ type: boolean
7280
+ expired:
7281
+ type: boolean
7282
+ return_to:
7283
+ type: string
7284
+ nullable: true
7285
+
7286
+ ClaimRedeemResponse:
7287
+ type: object
7288
+ properties:
7289
+ status:
7290
+ type: string
7291
+ connection_id:
7292
+ type: string
7293
+ format: uuid
7294
+ vault_ids:
7295
+ type: array
7296
+ items:
7297
+ type: string
7298
+ format: uuid
7299
+ agent_ids:
7300
+ type: array
7301
+ items:
7302
+ type: string
7303
+ format: uuid
7304
+ return_to:
7305
+ type: string
7306
+ nullable: true
7307
+ dashboard_url:
7308
+ type: string
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1claw/openapi-spec",
3
- "version": "0.23.0",
3
+ "version": "0.23.2",
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": {