npm - @1claw/openapi-spec - Versions diffs - 0.23.2 → 0.24.0 - Mend

@1claw/openapi-spec 0.23.2 → 0.24.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

package/README.md CHANGED Viewed

@@ -40,7 +40,7 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
-## What's in the spec (v0.23.0 — API `info.version` 2.12.x)
+## What's in the spec (v0.23.2 — API `info.version` 2.13.0)
 - **OIDC Federation (1claw as IdP)** — `GET /.well-known/openid-configuration` (public discovery: issuer, jwks_uri, supported algs `["EdDSA","RS256"]`, supported grant types incl. token-exchange), `GET /.well-known/jwks.json` (public JWKS — every active EdDSA + RS256 key version, keyed by deterministic `kid`), `POST /v1/auth/federated-token` (RFC 8693 token exchange — accepts JSON or `application/x-www-form-urlencoded`; subject token is an agent JWT or `ocv_` API key; returns RS256 JWT scoped to `audience`). Agent fields: `federation_enabled`, `federation_audiences[]`, `federated_token_ttl_seconds`. Designed for Anthropic Workload Identity Federation, GCP STS, AWS STS, etc.
 - **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. Federation tokens use a separate KMS RSA-2048 key and are signed RS256.
@@ -59,7 +59,7 @@ import spec from "@1claw/openapi-spec/openapi.json";
 - **Audit** — Hash-chained event log
 - **Chains** — Supported blockchain registry
 - **Auth** — JWT, API keys, agent tokens, MFA, device flow, Google OAuth, **federated tokens (RFC 8693)**
-- **Platform** — Platform API for building multi-tenant apps on 1Claw: `POST/GET /v1/platform/apps`, `GET/PATCH/DELETE /v1/platform/apps/{id}`, `POST/GET /v1/platform/apps/{id}/templates`, `POST /v1/platform/users/upsert`, `POST /v1/platform/connections/{id}/bootstrap`, `GET /v1/platform/apps/{id}/users`, `GET /v1/platform/apps/{id}/audit`, `GET/DELETE /v1/platform/connected-apps`. Platform apps authenticate with `plt_` prefixed API keys. Supports OIDC user provisioning, bootstrap templates, and billing models (platform_pays, user_pays, hybrid).
+- **Platform** — Platform API for building multi-tenant apps on 1Claw: `POST/GET /v1/platform/apps`, `GET/PATCH/DELETE /v1/platform/apps/{id}`, `POST/GET /v1/platform/apps/{id}/templates`, `POST /v1/platform/users/upsert`, `POST /v1/platform/connections/{id}/bootstrap`, `GET /v1/platform/apps/{id}/users`, `GET /v1/platform/apps/{id}/audit`, `GET/DELETE /v1/platform/connected-apps`, `GET /v1/platform/claim/{token}` (preview), `POST /v1/platform/claim/{token}` (redeem). Platform apps authenticate with `plt_` prefixed API keys. Supports OIDC user provisioning, bootstrap templates, and billing models (platform_pays, user_pays, hybrid).
 - **Org** — List members, invite, update/remove member; `GET /v1/org/agent-keys-vault` (users only, returns __agent-keys vault id or 404)
 ## Included files

package/openapi.json CHANGED Viewed

@@ -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,\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",
     "contact": {
       "email": "ops@1claw.xyz"
@@ -99,6 +99,10 @@
       "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)"
@@ -1263,6 +1267,230 @@
         }
       }
     },
+    "/v1/auth/devices": {
+      "post": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Register a mobile device",
+        "description": "Register a new mobile device for the authenticated user. Human-only.\nThe device public key is used for step-up authentication challenges.\n",
+        "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\na high-risk transaction). The device signs the challenge nonce to prove\npossession of the private key.\n",
+        "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.\nReturns a short-lived step-up token that can be used for the bound action.\n",
+        "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\nso the server can send approval requests and alerts.\n",
+        "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"
+          }
+        }
+      }
+    },
     "/v1/vaults": {
       "post": {
         "tags": [
@@ -5823,27 +6051,183 @@
           }
         }
       }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "BearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      },
-      "ApiKeyAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "description": "1ck_ prefixed API key used as Bearer token"
+    },
+    "/v1/approvals": {
+      "get": {
+        "tags": [
+          "Approvals"
+        ],
+        "summary": "List pending approvals",
+        "description": "Returns approvals for the authenticated user's organization.\nHuman-only. Supports filtering by status and pagination.\n",
+        "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"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
       }
     },
-    "parameters": {
-      "VaultId": {
-        "name": "vault_id",
-        "in": "path",
-        "required": true,
-        "schema": {
+    "/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.\nHuman-only. The approval must be in `pending` status.\n",
+        "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": {
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      },
+      "ApiKeyAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "1ck_ prefixed API key used as Bearer token"
+      }
+    },
+    "parameters": {
+      "VaultId": {
+        "name": "vault_id",
+        "in": "path",
+        "required": true,
+        "schema": {
           "type": "string",
           "format": "uuid"
         }
@@ -10734,6 +11118,39 @@
                   "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"
+                    }
+                  }
+                }
               }
             }
           }
@@ -10855,6 +11272,298 @@
             "type": "string"
           }
         }
+      },
+      "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/openapi.yaml CHANGED Viewed

@@ -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
     # ---------------------------------------------------------------------------
@@ -3780,6 +3933,108 @@ paths:
                 "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
 # =============================================================================
@@ -7222,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
@@ -7306,3 +7584,185 @@ components:
                     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 CHANGED Viewed

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