@1claw/openapi-spec 0.23.1 → 0.24.0

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.12.0
+    version: 2.14.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -62,6 +62,8 @@ tags:
       description: Platform administration
     - name: Health
       description: Service health checks
+    - name: Approvals
+      description: Human-in-the-loop approval workflow for agent actions
     - name: Platform
       description: Platform API for developers building on 1Claw (plt_ keys, user provisioning, bootstrap templates)
 
@@ -871,6 +873,157 @@ paths:
                 "403":
                     $ref: "#/components/responses/Forbidden"
 
+    /v1/auth/devices:
+        post:
+            tags: [Authentication]
+            summary: Register a mobile device
+            description: |
+                Register a new mobile device for the authenticated user. Human-only.
+                The device public key is used for step-up authentication challenges.
+            operationId: registerDevice
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/RegisterDeviceRequest"
+            responses:
+                "201":
+                    description: Device registered
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/RegisterDeviceResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+        get:
+            tags: [Authentication]
+            summary: List devices for current user
+            description: Returns all registered mobile devices for the authenticated user.
+            operationId: listDevices
+            responses:
+                "200":
+                    description: Device list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/DeviceListResponse"
+
+    /v1/auth/devices/{device_id}:
+        delete:
+            tags: [Authentication]
+            summary: Revoke a device
+            description: Removes a registered device, invalidating its keys and push tokens.
+            operationId: revokeDevice
+            parameters:
+                - name: device_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Device revoked
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/auth/devices/{device_id}/challenge:
+        post:
+            tags: [Authentication]
+            summary: Create step-up auth challenge
+            description: |
+                Creates a cryptographic challenge bound to a specific action (e.g. approving
+                a high-risk transaction). The device signs the challenge nonce to prove
+                possession of the private key.
+            operationId: createDeviceChallenge
+            parameters:
+                - name: device_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateDeviceChallengeRequest"
+            responses:
+                "200":
+                    description: Challenge created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/DeviceChallengeResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/auth/devices/{device_id}/attest:
+        post:
+            tags: [Authentication]
+            summary: Attest device challenge
+            description: |
+                Submit a signed challenge nonce to complete step-up authentication.
+                Returns a short-lived step-up token that can be used for the bound action.
+            operationId: attestDeviceChallenge
+            parameters:
+                - name: device_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/AttestDeviceChallengeRequest"
+            responses:
+                "200":
+                    description: Attestation successful
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AttestDeviceChallengeResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/auth/devices/{device_id}/push-token:
+        post:
+            tags: [Authentication]
+            summary: Register push notification token
+            description: |
+                Associates a push notification token (APNs or FCM) with a registered device
+                so the server can send approval requests and alerts.
+            operationId: registerPushToken
+            parameters:
+                - name: device_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/RegisterPushTokenRequest"
+            responses:
+                "204":
+                    description: Push token registered
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Vaults
     # ---------------------------------------------------------------------------
@@ -3730,6 +3883,158 @@ paths:
                 "404":
                     description: Connection not found
 
+    /v1/platform/claim/{token}:
+        get:
+            tags: [Platform]
+            summary: Preview a claim token
+            description: |
+                Verify a claim token and preview what was provisioned (app name, vaults, agents, policies).
+                Public endpoint — the token itself is the authentication.
+            parameters:
+                - in: path
+                  name: token
+                  required: true
+                  schema:
+                      type: string
+                  description: The `ct_` prefixed claim token from the bootstrap response
+            responses:
+                "200":
+                    description: Claim preview
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ClaimPreviewResponse"
+                "404":
+                    description: Invalid or expired claim token
+        post:
+            tags: [Platform]
+            summary: Redeem a claim token
+            description: |
+                Redeem a one-time claim token, marking the connection as claimed.
+                Public endpoint — the token itself is the authentication. Returns 409 if already claimed, 410 if expired.
+            parameters:
+                - in: path
+                  name: token
+                  required: true
+                  schema:
+                      type: string
+                  description: The `ct_` prefixed claim token from the bootstrap response
+            responses:
+                "200":
+                    description: Claim redeemed
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ClaimRedeemResponse"
+                "404":
+                    description: Invalid claim token
+                "409":
+                    description: Claim token already used
+                "410":
+                    description: Claim token has expired
+
+    # --- Approvals ---
+
+    /v1/approvals:
+        get:
+            tags: [Approvals]
+            summary: List pending approvals
+            description: |
+                Returns approvals for the authenticated user's organization.
+                Human-only. Supports filtering by status and pagination.
+            operationId: listApprovals
+            parameters:
+                - name: status
+                  in: query
+                  required: false
+                  schema:
+                      type: string
+                      enum: [pending, approved, rejected, expired]
+                  description: Filter by approval status
+                - name: limit
+                  in: query
+                  required: false
+                  schema:
+                      type: integer
+                      default: 50
+                - name: offset
+                  in: query
+                  required: false
+                  schema:
+                      type: integer
+                      default: 0
+            responses:
+                "200":
+                    description: Approval list
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [approvals]
+                                properties:
+                                    approvals:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/ApprovalResponse"
+
+    /v1/approvals/{approval_id}:
+        get:
+            tags: [Approvals]
+            summary: Get approval details
+            description: Returns details for a single approval by ID.
+            operationId: getApproval
+            parameters:
+                - name: approval_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Approval details
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ApprovalResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/approvals/{approval_id}/decide:
+        post:
+            tags: [Approvals]
+            summary: Approve or reject
+            description: |
+                Submit a decision (approve or reject) for a pending approval.
+                Human-only. The approval must be in `pending` status.
+            operationId: decideApproval
+            parameters:
+                - name: approval_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/DecideApprovalRequest"
+            responses:
+                "200":
+                    description: Decision recorded
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ApprovalResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "409":
+                    $ref: "#/components/responses/Conflict"
+
 # =============================================================================
 # COMPONENTS
 # =============================================================================
@@ -7172,6 +7477,29 @@ components:
                             items:
                                 type: string
                                 format: uuid
+                        signing_key_chains:
+                            type: array
+                            items:
+                                type: string
+                            description: Chains with provisioned signing keys
+                        agent_api_key:
+                            type: string
+                            nullable: true
+                            description: One-time agent API key (ocv_ prefix). Store securely — not retrievable later.
+                        signing_keys:
+                            type: array
+                            description: Provisioned signing key details (chain, address, public key)
+                            items:
+                                type: object
+                                properties:
+                                    chain:
+                                        type: string
+                                    curve:
+                                        type: string
+                                    public_key:
+                                        type: string
+                                    address:
+                                        type: string
 
         ConnectedAppResponse:
             type: object
@@ -7198,3 +7526,243 @@ components:
                 created_at:
                     type: string
                     format: date-time
+
+        ClaimPreviewResponse:
+            type: object
+            properties:
+                app_name:
+                    type: string
+                app_slug:
+                    type: string
+                app_logo_url:
+                    type: string
+                    nullable: true
+                auth_mode:
+                    type: string
+                vault_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                agent_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                policy_count:
+                    type: integer
+                status:
+                    type: string
+                already_claimed:
+                    type: boolean
+                expired:
+                    type: boolean
+                return_to:
+                    type: string
+                    nullable: true
+
+        ClaimRedeemResponse:
+            type: object
+            properties:
+                status:
+                    type: string
+                connection_id:
+                    type: string
+                    format: uuid
+                vault_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                agent_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                return_to:
+                    type: string
+                    nullable: true
+                dashboard_url:
+                    type: string
+
+        # --- Mobile Companion App schemas ---
+
+        RegisterDeviceRequest:
+            type: object
+            required: [name, platform, public_key_pem]
+            properties:
+                name:
+                    type: string
+                    description: Human-readable device name (e.g. "Kevin's iPhone")
+                    example: My iPhone
+                platform:
+                    type: string
+                    enum: [ios, android]
+                public_key_pem:
+                    type: string
+                    description: PEM-encoded public key for step-up challenge signing
+                attestation_blob:
+                    type: string
+                    description: Optional platform attestation (Apple DeviceCheck / Android SafetyNet)
+
+        RegisterDeviceResponse:
+            type: object
+            required: [device_id, attestation_verified]
+            properties:
+                device_id:
+                    type: string
+                    format: uuid
+                attestation_verified:
+                    type: boolean
+
+        DeviceListResponse:
+            type: object
+            required: [devices]
+            properties:
+                devices:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/DeviceResponse"
+
+        DeviceResponse:
+            type: object
+            required: [id, name, platform, attestation_verified, created_at]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                name:
+                    type: string
+                platform:
+                    type: string
+                attestation_verified:
+                    type: boolean
+                last_used_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+                created_at:
+                    type: string
+                    format: date-time
+
+        CreateDeviceChallengeRequest:
+            type: object
+            required: [action, target_id]
+            properties:
+                action:
+                    type: string
+                    description: The action this challenge authorizes (e.g. "approve_transaction")
+                target_id:
+                    type: string
+                    description: ID of the resource the action targets
+
+        DeviceChallengeResponse:
+            type: object
+            required: [challenge_nonce, expires_at, action_bound_hash]
+            properties:
+                challenge_nonce:
+                    type: string
+                expires_at:
+                    type: string
+                    format: date-time
+                action_bound_hash:
+                    type: string
+                    description: SHA-256 binding the challenge to the requested action and target
+
+        AttestDeviceChallengeRequest:
+            type: object
+            required: [challenge_nonce, signature]
+            properties:
+                challenge_nonce:
+                    type: string
+                signature:
+                    type: string
+                    description: Signature over the challenge nonce using the device's private key
+
+        AttestDeviceChallengeResponse:
+            type: object
+            required: [step_up_token, expires_at]
+            properties:
+                step_up_token:
+                    type: string
+                    description: Short-lived token authorizing the bound action
+                expires_at:
+                    type: string
+                    format: date-time
+
+        RegisterPushTokenRequest:
+            type: object
+            required: [token, platform]
+            properties:
+                token:
+                    type: string
+                    description: Push notification token from APNs or FCM
+                platform:
+                    type: string
+                    enum: [apns, fcm]
+
+        DecideApprovalRequest:
+            type: object
+            required: [decision]
+            properties:
+                decision:
+                    type: string
+                    enum: [approve, reject]
+                reason:
+                    type: string
+                    description: Optional human-readable reason for the decision
+
+        ApprovalResponse:
+            type: object
+            required: [id, org_id, user_id, action, target_type, target_id, risk_tier, status, summary, created_at]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                user_id:
+                    type: string
+                    format: uuid
+                agent_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                action:
+                    type: string
+                target_type:
+                    type: string
+                target_id:
+                    type: string
+                risk_tier:
+                    type: integer
+                    minimum: 1
+                    maximum: 3
+                status:
+                    type: string
+                    enum: [pending, approved, rejected, expired]
+                summary:
+                    type: object
+                    description: Structured summary of the action requiring approval
+                reason:
+                    type: string
+                    nullable: true
+                decision_reason:
+                    type: string
+                    nullable: true
+                decided_by:
+                    type: string
+                    format: uuid
+                    nullable: true
+                decided_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+                expires_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+                created_at:
+                    type: string
+                    format: date-time

package/package.json

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