@1claw/openapi-spec 0.53.0 → 0.53.2

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 0.53.0
+    version: 0.53.2
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -112,6 +112,12 @@ tags:
       description: Unified balance aggregator
     - name: Environment Variables
       description: Per-vault and org-shared environment variable management
+    - name: Wallet Access
+      description: Role-based wallet access policies for agents and users
+    - name: Credential Recovery
+      description: MFA/passkey/password recovery escape hatch with admin approval
+    - name: Shamir KEK
+      description: Shamir secret-sharing for org-level Key Encryption Keys
 
 # =============================================================================
 # PATHS
@@ -10245,6 +10251,416 @@ paths:
                 "403":
                     $ref: "#/components/responses/Forbidden"
 
+    # ---------------------------------------------------------------------------
+    # Wallet Access Policies
+    # ---------------------------------------------------------------------------
+
+    /v1/treasury/wallets/access-policies:
+        post:
+            tags: [Wallet Access]
+            summary: Create a wallet access policy
+            description: |
+                Create a role-based wallet access policy granting an agent, user, role,
+                or platform app specific permissions on treasury wallets within a scope
+                (org-wide, platform app, or single wallet). Requires Pro+ tier.
+            operationId: createWalletAccessPolicy
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateWalletAccessPolicyRequest"
+            responses:
+                "201":
+                    description: Policy created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/WalletAccessPolicyResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+        get:
+            tags: [Wallet Access]
+            summary: List wallet access policies for the org
+            operationId: listWalletAccessPolicies
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: scope_type
+                  in: query
+                  schema:
+                      type: string
+                      enum: [wallet, platform_app, org]
+                  description: Filter by scope type
+                - name: scope_id
+                  in: query
+                  schema:
+                      type: string
+                      format: uuid
+                  description: Filter by scope ID (wallet or platform app UUID)
+            responses:
+                "200":
+                    description: Policy list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/WalletAccessPolicyListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/treasury/wallets/access-policies/{id}:
+        delete:
+            tags: [Wallet Access]
+            summary: Delete a wallet access policy
+            operationId: deleteWalletAccessPolicy
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Policy deleted
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    # ---------------------------------------------------------------------------
+    # Credential Recovery
+    # ---------------------------------------------------------------------------
+
+    /v1/auth/credential-recovery/request:
+        post:
+            tags: [Credential Recovery]
+            summary: Initiate credential recovery
+            description: |
+                Start a credential recovery request for MFA reset, passkey reset,
+                or password reset. Requires admin approval per org policy.
+            operationId: requestCredentialRecovery
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CredentialRecoveryRequest"
+            responses:
+                "201":
+                    description: Recovery request created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CredentialRecoveryResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/auth/credential-recovery/requests:
+        get:
+            tags: [Credential Recovery]
+            summary: List recovery requests for the org
+            description: Admin/owner only. Returns pending, approved, and rejected recovery requests.
+            operationId: listCredentialRecoveryRequests
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: status
+                  in: query
+                  schema:
+                      type: string
+                      enum: [pending_approval, approved, rejected, expired]
+                  description: Filter by status
+            responses:
+                "200":
+                    description: Recovery request list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CredentialRecoveryListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    /v1/auth/credential-recovery/requests/{id}/approve:
+        post:
+            tags: [Credential Recovery]
+            summary: Approve a recovery request
+            description: Admin/owner approves a pending recovery request. May return a one-time recovery code.
+            operationId: approveCredentialRecovery
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Request approved
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CredentialRecoveryApproveResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/auth/credential-recovery/requests/{id}/execute:
+        post:
+            tags: [Credential Recovery]
+            summary: Execute an approved credential recovery request
+            description: >-
+                Execute an approved credential recovery request after the delay
+                window has elapsed. Only org owners or admins can execute.
+            operationId: executeCredentialRecovery
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Recovery executed
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CredentialRecoveryExecuteResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/auth/credential-recovery/requests/{id}:
+        delete:
+            tags: [Credential Recovery]
+            summary: Cancel or reject a recovery request
+            operationId: cancelCredentialRecovery
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Request cancelled
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    # ---------------------------------------------------------------------------
+    # Org Credential Recovery Policy
+    # ---------------------------------------------------------------------------
+
+    /v1/org/credential-recovery-policy:
+        get:
+            tags: [Credential Recovery]
+            summary: Get org credential recovery policy
+            operationId: getCredentialRecoveryPolicy
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: Recovery policy
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CredentialRecoveryPolicyResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+        patch:
+            tags: [Credential Recovery]
+            summary: Update org credential recovery policy
+            operationId: updateCredentialRecoveryPolicy
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CredentialRecoveryPolicyRequest"
+            responses:
+                "200":
+                    description: Policy updated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CredentialRecoveryPolicyResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    # ---------------------------------------------------------------------------
+    # Shamir KEK
+    # ---------------------------------------------------------------------------
+
+    /v1/org/shamir-kek/setup:
+        post:
+            tags: [Shamir KEK]
+            summary: Set up Shamir KEK for the org
+            description: |
+                Initialize a Shamir secret-sharing KEK for the org. Splits the master
+                key into shares distributed to custodians. Shares are returned one-time
+                only and must be stored securely by each custodian.
+            operationId: setupShamirKek
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ShamirKekSetupRequest"
+            responses:
+                "201":
+                    description: Shamir KEK configured (shares returned one-time)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ShamirKekSetupResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    /v1/org/shamir-kek:
+        get:
+            tags: [Shamir KEK]
+            summary: Get Shamir KEK status
+            description: Returns the current Shamir KEK configuration status for the org.
+            operationId: getShamirKekStatus
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: Shamir KEK status
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ShamirKekStatusResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/org/shamir-kek/reconstruct:
+        post:
+            tags: [Shamir KEK]
+            summary: Reconstruct KEK from shares
+            description: |
+                Submit Shamir shares to reconstruct the org KEK. Requires at least
+                `threshold` valid shares. Used during disaster recovery.
+            operationId: reconstructShamirKek
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ShamirKekReconstructRequest"
+            responses:
+                "200":
+                    description: Reconstruction result
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ShamirKekReconstructResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    /v1/org/shamir-kek/recovery-codes:
+        get:
+            tags: [Shamir KEK]
+            summary: Get Shamir recovery codes (one-time)
+            description: |
+                Returns the one-time recovery codes for the Shamir KEK. These codes
+                can be used as an emergency fallback if custodian shares are lost.
+                Codes are only returned once — subsequent calls return 410.
+            operationId: getShamirKekRecoveryCodes
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: Recovery codes (one-time)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ShamirKekRecoveryCodesResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "410":
+                    description: Codes already retrieved
+
+    /v1/org/shamir-kek/verify-recovery-code:
+        post:
+            tags: [Shamir KEK]
+            summary: Verify a Shamir recovery code
+            description: Check whether a recovery code is valid without consuming it.
+            operationId: verifyShamirKekRecoveryCode
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ShamirKekVerifyCodeRequest"
+            responses:
+                "200":
+                    description: Verification result
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ShamirKekVerifyCodeResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
 # =============================================================================
 # COMPONENTS
 # =============================================================================
@@ -12587,6 +13003,22 @@ components:
                         Optional pending approval ID. When consensus policies match,
                         clients resubmit with this field set to bypass the 202 gate
                         after the approval has been executed.
+                raw_transaction:
+                    type: string
+                    description: >
+                        Pre-built raw transaction as a base64-encoded byte string.
+                        When provided, the handler decodes and deep-inspects the
+                        transaction for policy evaluation before signing. Supported
+                        for non-EVM chains where the client constructs the
+                        transaction payload.
+                tron_transaction:
+                    type: object
+                    additionalProperties: true
+                    description: >
+                        Pre-built Tron transaction JSON object. When provided,
+                        the handler signs the transaction as-is using the Tron
+                        protobuf format. Enables full Tron transaction type
+                        coverage beyond simple TRX/TRC-20 transfers.
 
         SignTransactionRequest:
             type: object
@@ -13058,9 +13490,25 @@ components:
                     type: string
                     format: uuid
                     description: >
-                        Optional pending approval ID. When consensus policies match,
-                        clients resubmit with this field set to bypass the 202 gate
-                        after the approval has been executed.
+                        Optional pending approval ID. When consensus policies match,
+                        clients resubmit with this field set to bypass the 202 gate
+                        after the approval has been executed.
+                raw_transaction:
+                    type: string
+                    description: >
+                        Pre-built raw transaction as a base64-encoded byte string.
+                        When provided, the handler decodes and deep-inspects the
+                        transaction for policy evaluation before signing. Supported
+                        for non-EVM chains where the client constructs the
+                        transaction payload.
+                tron_transaction:
+                    type: object
+                    additionalProperties: true
+                    description: >
+                        Pre-built Tron transaction JSON object. When provided,
+                        the handler signs the transaction as-is using the Tron
+                        protobuf format. Enables full Tron transaction type
+                        coverage beyond simple TRX/TRC-20 transfers.
 
         SignIntentResponse:
             type: object
@@ -13824,17 +14272,31 @@ components:
 
         ShroudAttestationResponse:
             type: object
-            required: [attested, image_hash, identity_token, verification]
+            required: [attested, attestation_level, image_hash, identity_token, verification]
             properties:
                 attested:
                     type: boolean
-                    description: Whether TEE attestation was successfully fetched
+                    description: |
+                        Whether at least an identity token was obtained (true for identity,
+                        confidential, or sev_snp levels). Backward-compatible boolean; prefer
+                        attestation_level for granularity.
+                attestation_level:
+                    type: string
+                    enum: [none, identity, confidential, sev_snp]
+                    description: |
+                        Granularity of TEE attestation achieved. `none` = dev/non-GCE;
+                        `identity` = GCE metadata JWT only; `confidential` = CC claims present;
+                        `sev_snp` = full SEV-SNP measurement verified against image digest.
                 image_hash:
                     type: string
                     description: Confidential VM image hash (compare against published Docker digest)
                 identity_token:
                     type: string
                     description: GCE metadata identity JWT (verify against Google public keys)
+                confidential_claims:
+                    nullable: true
+                    description: Confidential Computing claims extracted from the identity JWT
+                    $ref: "#/components/schemas/ConfidentialClaims"
                 verification:
                     type: object
                     properties:
@@ -13848,6 +14310,23 @@ components:
                         expected_audience:
                             type: string
 
+        ConfidentialClaims:
+            type: object
+            nullable: true
+            properties:
+                secboot:
+                    type: boolean
+                    description: Whether secure boot was enabled
+                hwmodel:
+                    type: string
+                    description: Hardware model string (e.g. GCP_AMD_SEV)
+                instance_confidentiality:
+                    type: string
+                    description: Instance confidentiality level from google.compute_engine
+                sw_name:
+                    type: string
+                    description: Software name claim (swname or sw_name)
+
         AuditEvent:
             type: object
             properties:
@@ -18544,3 +19023,355 @@ components:
                         type: string
                 comment:
                     type: string
+
+        # -----------------------------------------------------------------
+        # Wallet Access Policy schemas
+        # -----------------------------------------------------------------
+
+        CreateWalletAccessPolicyRequest:
+            type: object
+            required: [scope_type, principal_type, principal_id]
+            properties:
+                scope_type:
+                    type: string
+                    enum: [wallet, platform_app, org]
+                    description: Policy scope — org-wide, platform app, or single wallet
+                scope_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                    description: Wallet or platform app UUID when scope_type is not org
+                principal_type:
+                    type: string
+                    enum: [user, agent, role, platform_app]
+                    description: Who receives the grant
+                principal_id:
+                    type: string
+                    description: User/agent UUID, role name, or platform app UUID
+                can_sign:
+                    type: boolean
+                    default: false
+                can_view_balance:
+                    type: boolean
+                    default: true
+                can_export:
+                    type: boolean
+                    default: false
+                can_send:
+                    type: boolean
+                    default: false
+                can_swap:
+                    type: boolean
+                    default: false
+                allowed_chains:
+                    type: array
+                    items:
+                        type: string
+                    description: Chains this policy applies to (empty = all)
+                max_value_per_tx_eth:
+                    type: string
+                    description: Max value per transaction in ETH
+                daily_limit_eth:
+                    type: string
+                    description: Daily spend limit in ETH
+                conditions:
+                    type: object
+                    description: Additional JSON conditions (reserved for future enforcement)
+                expires_at:
+                    type: string
+                    format: date-time
+
+        WalletAccessPolicyResponse:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                scope_type:
+                    type: string
+                scope_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                principal_type:
+                    type: string
+                principal_id:
+                    type: string
+                can_sign:
+                    type: boolean
+                can_view_balance:
+                    type: boolean
+                can_export:
+                    type: boolean
+                can_send:
+                    type: boolean
+                can_swap:
+                    type: boolean
+                allowed_chains:
+                    type: array
+                    items:
+                        type: string
+                max_value_per_tx_eth:
+                    type: string
+                    nullable: true
+                daily_limit_eth:
+                    type: string
+                    nullable: true
+                conditions:
+                    type: object
+                is_active:
+                    type: boolean
+                expires_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+                created_by:
+                    type: string
+                    format: uuid
+                created_at:
+                    type: string
+                    format: date-time
+                updated_at:
+                    type: string
+                    format: date-time
+
+        WalletAccessPolicyListResponse:
+            type: object
+            properties:
+                policies:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/WalletAccessPolicyResponse"
+
+        # -----------------------------------------------------------------
+        # Credential Recovery schemas
+        # -----------------------------------------------------------------
+
+        CredentialRecoveryRequest:
+            type: object
+            required: [recovery_type]
+            properties:
+                recovery_type:
+                    type: string
+                    enum: [mfa_reset, passkey_reset, password_reset]
+                reason:
+                    type: string
+                    description: Optional justification for the recovery request
+
+        CredentialRecoveryResponse:
+            type: object
+            properties:
+                request_id:
+                    type: string
+                    format: uuid
+                status:
+                    type: string
+                    enum: [pending_approval, approved, rejected, expired]
+                recovery_type:
+                    type: string
+                    enum: [mfa_reset, passkey_reset, password_reset]
+                created_at:
+                    type: string
+                    format: date-time
+
+        CredentialRecoveryListResponse:
+            type: object
+            properties:
+                requests:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/CredentialRecoveryResponse"
+
+        CredentialRecoveryApproveResponse:
+            type: object
+            properties:
+                request_id:
+                    type: string
+                    format: uuid
+                status:
+                    type: string
+                    enum: [approved]
+                recovery_code:
+                    type: string
+                    nullable: true
+                    description: One-time recovery code (only present for certain recovery types)
+
+        CredentialRecoveryExecuteResponse:
+            type: object
+            properties:
+                request_id:
+                    type: string
+                    format: uuid
+                status:
+                    type: string
+                    enum: [executed]
+                recovery_type:
+                    type: string
+                executed_at:
+                    type: string
+                    format: date-time
+
+        CredentialRecoveryPolicyResponse:
+            type: object
+            properties:
+                enabled:
+                    type: boolean
+                require_admin_approval:
+                    type: boolean
+                delay_hours:
+                    type: integer
+                    description: Waiting period before recovery takes effect
+                allowed_types:
+                    type: array
+                    items:
+                        type: string
+                        enum: [mfa_reset, passkey_reset, password_reset]
+
+        CredentialRecoveryPolicyRequest:
+            type: object
+            properties:
+                enabled:
+                    type: boolean
+                require_admin_approval:
+                    type: boolean
+                delay_hours:
+                    type: integer
+                allowed_types:
+                    type: array
+                    items:
+                        type: string
+                        enum: [mfa_reset, passkey_reset, password_reset]
+
+        # -----------------------------------------------------------------
+        # Shamir KEK schemas
+        # -----------------------------------------------------------------
+
+        ShamirKekSetupRequest:
+            type: object
+            required: [threshold, total_shares, custodian_emails]
+            properties:
+                threshold:
+                    type: integer
+                    enum: [2, 3]
+                    description: Minimum shares required to reconstruct the KEK
+                total_shares:
+                    type: integer
+                    enum: [3, 5]
+                    description: Total number of shares to generate
+                custodian_emails:
+                    type: array
+                    items:
+                        type: string
+                        format: email
+                    description: Email addresses of share custodians
+
+        ShamirKekSetupResponse:
+            type: object
+            properties:
+                kek_id:
+                    type: string
+                threshold:
+                    type: integer
+                total_shares:
+                    type: integer
+                shares:
+                    type: array
+                    description: One-time share distribution (never returned again)
+                    items:
+                        type: object
+                        properties:
+                            index:
+                                type: integer
+                            custodian_email:
+                                type: string
+                                format: email
+                            share_b64:
+                                type: string
+                                description: Base64-encoded share
+                custody_mode:
+                    type: string
+                created_at:
+                    type: string
+                    format: date-time
+
+        ShamirKekStatusResponse:
+            type: object
+            properties:
+                configured:
+                    type: boolean
+                kek_id:
+                    type: string
+                    nullable: true
+                threshold:
+                    type: integer
+                    nullable: true
+                total_shares:
+                    type: integer
+                    nullable: true
+                custody_mode:
+                    type: string
+                    nullable: true
+                custodians:
+                    type: array
+                    nullable: true
+                    items:
+                        type: object
+                        properties:
+                            email:
+                                type: string
+                                format: email
+                            share_provided:
+                                type: boolean
+                created_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+
+        ShamirKekReconstructRequest:
+            type: object
+            required: [shares]
+            properties:
+                shares:
+                    type: array
+                    items:
+                        type: object
+                        required: [index, share_b64]
+                        properties:
+                            index:
+                                type: integer
+                            share_b64:
+                                type: string
+                                description: Base64-encoded share
+
+        ShamirKekReconstructResponse:
+            type: object
+            properties:
+                status:
+                    type: string
+                    enum: [accepted, reconstructed]
+                message:
+                    type: string
+
+        ShamirKekRecoveryCodesResponse:
+            type: object
+            properties:
+                codes:
+                    type: array
+                    items:
+                        type: string
+
+        ShamirKekVerifyCodeRequest:
+            type: object
+            required: [code]
+            properties:
+                code:
+                    type: string
+
+        ShamirKekVerifyCodeResponse:
+            type: object
+            properties:
+                valid:
+                    type: boolean