@1claw/openapi-spec 0.33.0 → 0.34.1

package/README.md

@@ -40,7 +40,21 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.32.1 — API `info.version` 2.18.0)
+## What's in the spec (v0.34.1 — API `info.version` 2.19.0)
+
+### Risk Engine & DPoP (2.19)
+- **Risk events** — `GET /v1/risk/events` (list, filterable by severity/principal_type)
+- **Risk verdicts** — `GET /v1/risk/verdicts` (active verdicts), `GET /v1/risk/verdicts/{type}/{id}` (single principal verdict)
+- **Honeytokens** — `GET/POST/DELETE /v1/risk/honeytokens` (canary secret CRUD with trigger counts)
+- **DPoP** — RFC 9449 Demonstration of Proof-of-Possession token binding (planned spec addition)
+
+### Webhooks (2.19)
+- **Webhook CRUD** — `POST/GET /v1/webhooks`, `GET/PATCH/DELETE /v1/webhooks/{id}`. Events: `wallet.transfer.*`, `proposal.*`, `agent.transaction.*`, `signing_key.rotated`, `policy.*`
+
+### OAuth & Email OTP (2.19)
+- **OAuth2 authorization server** — `GET/POST /v1/oauth/authorize`, `POST /v1/oauth/token`, `GET /v1/oauth/userinfo` ("Sign in with 1Claw")
+- **Email OTP** — `POST /v1/auth/email-otp/send`, `POST /v1/auth/email-otp/verify` (passwordless login)
+- **Spend policies** — `POST/GET/DELETE /v1/platform/apps/{id}/spend-policies`, `PUT /v1/platform/connections/{id}/spend-policy`, `GET /v1/treasury/wallets/spend-policy`
 
 ### Bankr dynamic key vending (2.18)
 - **Bankr keys** — `POST /v1/agents/{id}/bankr-keys/lease`, `GET /v1/agents/{id}/bankr-keys`, `DELETE /v1/agents/{id}/bankr-keys/{lease_id}`. Partner key vending for scoped, TTL-bound `bk_usr_` wallet API keys.

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.18.0",
+    "version": "2.19.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"
@@ -118,6 +118,10 @@
     {
       "name": "OAuth",
       "description": "OAuth 2.0 authorization server (PKCE, consent, token exchange, OIDC UserInfo)"
+    },
+    {
+      "name": "Risk Engine",
+      "description": "Risk events, verdicts, and honeytoken management"
     }
   ],
   "paths": {
@@ -4277,6 +4281,74 @@
         }
       }
     },
+    "/v1/org/bankr-config": {
+      "get": {
+        "tags": [
+          "Organization"
+        ],
+        "summary": "Get org Bankr partner configuration",
+        "description": "Returns whether the org has configured Bankr BYOK (partner key prefix and default wallet only — never the secret). Users only.",
+        "operationId": "getOrgBankrConfig",
+        "responses": {
+          "200": {
+            "description": "Bankr configuration status",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OrgBankrConfigResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "tags": [
+          "Organization"
+        ],
+        "summary": "Set org Bankr partner configuration",
+        "description": "Store or replace the org's Bankr partner key (`bk_ptr_...`) and optional default wallet (`wlt_...`). Owner/admin only. Partner key encrypted at rest.",
+        "operationId": "upsertOrgBankrConfig",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertOrgBankrConfigRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Configuration saved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OrgBankrConfigResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Organization"
+        ],
+        "summary": "Remove org Bankr partner configuration",
+        "description": "Delete BYOK credentials for the org. Owner/admin only.",
+        "operationId": "deleteOrgBankrConfig",
+        "responses": {
+          "204": {
+            "description": "Configuration removed"
+          },
+          "404": {
+            "description": "Configuration not found"
+          }
+        }
+      }
+    },
     "/v1/org/invite": {
       "post": {
         "tags": [
@@ -8904,6 +8976,267 @@
           }
         }
       }
+    },
+    "/v1/risk/events": {
+      "get": {
+        "tags": [
+          "Risk Engine"
+        ],
+        "summary": "List risk events",
+        "description": "Returns risk events detected by the risk engine, ordered by most recent first.\nFilter by severity or principal type.\n",
+        "operationId": "listRiskEvents",
+        "parameters": [
+          {
+            "name": "severity",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "low",
+                "medium",
+                "high",
+                "critical"
+              ]
+            },
+            "description": "Filter events by severity level"
+          },
+          {
+            "name": "principal_type",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "user",
+                "agent"
+              ]
+            },
+            "description": "Filter events by principal type"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 50
+            }
+          },
+          {
+            "name": "offset",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Risk event list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RiskEventListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/risk/verdicts": {
+      "get": {
+        "tags": [
+          "Risk Engine"
+        ],
+        "summary": "List risk verdicts",
+        "description": "Returns all active risk verdicts for the caller's organization.",
+        "operationId": "listRiskVerdicts",
+        "responses": {
+          "200": {
+            "description": "Verdict list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RiskVerdictListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/risk/verdicts/{principal_type}/{principal_id}": {
+      "get": {
+        "tags": [
+          "Risk Engine"
+        ],
+        "summary": "Get risk verdict for a principal",
+        "description": "Returns the current risk verdict for a specific user or agent.",
+        "operationId": "getRiskVerdict",
+        "parameters": [
+          {
+            "name": "principal_type",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "user",
+                "agent"
+              ]
+            }
+          },
+          {
+            "name": "principal_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Risk verdict (null if no verdict exists)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "verdict": {
+                      "$ref": "#/components/schemas/RiskVerdict",
+                      "nullable": true
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/risk/honeytokens": {
+      "get": {
+        "tags": [
+          "Risk Engine"
+        ],
+        "summary": "List honeytokens",
+        "description": "Returns all honeytokens (canary secrets) configured for the caller's organization.",
+        "operationId": "listHoneytokens",
+        "responses": {
+          "200": {
+            "description": "Honeytoken list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HoneytokenListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Risk Engine"
+        ],
+        "summary": "Create a honeytoken",
+        "description": "Register a secret path as a honeytoken (canary). Any access to this secret\ntriggers a risk event and increments the trigger counter.\n",
+        "operationId": "createHoneytoken",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateHoneytokenRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Honeytoken created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "honeytoken": {
+                      "$ref": "#/components/schemas/Honeytoken"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/risk/honeytokens/{id}": {
+      "delete": {
+        "tags": [
+          "Risk Engine"
+        ],
+        "summary": "Delete a honeytoken",
+        "description": "Remove a honeytoken registration. The underlying secret is not affected.",
+        "operationId": "deleteHoneytoken",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Honeytoken deleted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "deleted": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -12274,6 +12607,43 @@
           }
         }
       },
+      "OrgBankrConfigResponse": {
+        "type": "object",
+        "properties": {
+          "configured": {
+            "type": "boolean"
+          },
+          "partner_key_prefix": {
+            "type": "string"
+          },
+          "default_wallet_id": {
+            "type": "string"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "using_platform_fallback": {
+            "type": "boolean"
+          }
+        }
+      },
+      "UpsertOrgBankrConfigRequest": {
+        "type": "object",
+        "required": [
+          "partner_key"
+        ],
+        "properties": {
+          "partner_key": {
+            "type": "string",
+            "description": "Bankr partner API key (bk_ptr_...)"
+          },
+          "default_wallet_id": {
+            "type": "string",
+            "description": "Default provisioned wallet (wlt_...)"
+          }
+        }
+      },
       "UsageSummaryResponse": {
         "type": "object",
         "properties": {
@@ -15169,6 +15539,285 @@
             "format": "date-time"
           }
         }
+      },
+      "RiskEvent": {
+        "type": "object",
+        "required": [
+          "id",
+          "occurred_at",
+          "principal_type",
+          "principal_id",
+          "org_id",
+          "event_type",
+          "payload",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "occurred_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "principal_type": {
+            "type": "string",
+            "enum": [
+              "user",
+              "agent"
+            ]
+          },
+          "principal_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "event_type": {
+            "type": "string",
+            "description": "Risk event type (e.g. first_seen, geo_velocity, honeytoken_access)"
+          },
+          "ip": {
+            "type": "string",
+            "nullable": true
+          },
+          "asn": {
+            "type": "integer",
+            "nullable": true
+          },
+          "asn_org": {
+            "type": "string",
+            "nullable": true
+          },
+          "country_code": {
+            "type": "string",
+            "nullable": true
+          },
+          "region": {
+            "type": "string",
+            "nullable": true
+          },
+          "city": {
+            "type": "string",
+            "nullable": true
+          },
+          "latitude": {
+            "type": "number",
+            "nullable": true
+          },
+          "longitude": {
+            "type": "number",
+            "nullable": true
+          },
+          "user_agent": {
+            "type": "string",
+            "nullable": true
+          },
+          "severity": {
+            "type": "string",
+            "nullable": true,
+            "description": "Computed severity at event time (low, medium, high, critical)"
+          },
+          "payload": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "RiskEventListResponse": {
+        "type": "object",
+        "required": [
+          "events"
+        ],
+        "properties": {
+          "events": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RiskEvent"
+            }
+          }
+        }
+      },
+      "RiskVerdictReason": {
+        "type": "object",
+        "required": [
+          "detector",
+          "severity",
+          "description"
+        ],
+        "properties": {
+          "detector": {
+            "type": "string"
+          },
+          "severity": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
+      },
+      "RiskVerdict": {
+        "type": "object",
+        "required": [
+          "principal_type",
+          "principal_id",
+          "org_id",
+          "score",
+          "severity",
+          "reasons",
+          "computed_at",
+          "expires_at"
+        ],
+        "properties": {
+          "principal_type": {
+            "type": "string"
+          },
+          "principal_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "score": {
+            "type": "number",
+            "description": "Composite risk score (0.0 – 100.0)"
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high",
+              "critical"
+            ]
+          },
+          "reasons": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RiskVerdictReason"
+            }
+          },
+          "computed_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "RiskVerdictListResponse": {
+        "type": "object",
+        "required": [
+          "verdicts"
+        ],
+        "properties": {
+          "verdicts": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RiskVerdict"
+            }
+          }
+        }
+      },
+      "Honeytoken": {
+        "type": "object",
+        "required": [
+          "id",
+          "vault_id",
+          "org_id",
+          "secret_path",
+          "created_by",
+          "created_at",
+          "triggered_count"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "vault_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "secret_path": {
+            "type": "string"
+          },
+          "created_by": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "notes": {
+            "type": "string",
+            "nullable": true
+          },
+          "triggered_count": {
+            "type": "integer"
+          },
+          "last_triggered_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          }
+        }
+      },
+      "CreateHoneytokenRequest": {
+        "type": "object",
+        "required": [
+          "vault_id",
+          "secret_path"
+        ],
+        "properties": {
+          "vault_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "secret_path": {
+            "type": "string",
+            "description": "Vault secret path to monitor as a canary"
+          },
+          "notes": {
+            "type": "string",
+            "description": "Optional human-readable notes about this honeytoken"
+          }
+        }
+      },
+      "HoneytokenListResponse": {
+        "type": "object",
+        "required": [
+          "honeytokens"
+        ],
+        "properties": {
+          "honeytokens": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Honeytoken"
+            }
+          }
+        }
       }
     }
   }

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.18.0
+    version: 2.19.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -72,6 +72,8 @@ tags:
       description: Platform API for developers building on 1Claw (plt_ keys, user provisioning, bootstrap templates)
     - name: OAuth
       description: OAuth 2.0 authorization server (PKCE, consent, token exchange, OIDC UserInfo)
+    - name: Risk Engine
+      description: Risk events, verdicts, and honeytoken management
 
 # =============================================================================
 # PATHS
@@ -2806,6 +2808,48 @@ paths:
                 "404":
                     description: Agent-keys vault not found
 
+    /v1/org/bankr-config:
+        get:
+            tags: [Organization]
+            summary: Get org Bankr partner configuration
+            description: Returns whether the org has configured Bankr BYOK (partner key prefix and default wallet only — never the secret). Users only.
+            operationId: getOrgBankrConfig
+            responses:
+                "200":
+                    description: Bankr configuration status
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OrgBankrConfigResponse"
+        put:
+            tags: [Organization]
+            summary: Set org Bankr partner configuration
+            description: Store or replace the org's Bankr partner key (`bk_ptr_...`) and optional default wallet (`wlt_...`). Owner/admin only. Partner key encrypted at rest.
+            operationId: upsertOrgBankrConfig
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/UpsertOrgBankrConfigRequest"
+            responses:
+                "200":
+                    description: Configuration saved
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OrgBankrConfigResponse"
+        delete:
+            tags: [Organization]
+            summary: Remove org Bankr partner configuration
+            description: Delete BYOK credentials for the org. Owner/admin only.
+            operationId: deleteOrgBankrConfig
+            responses:
+                "204":
+                    description: Configuration removed
+                "404":
+                    description: Configuration not found
+
     /v1/org/invite:
         post:
             tags: [Organization]
@@ -5682,6 +5726,173 @@ paths:
                 "401":
                     $ref: "#/components/responses/Unauthorized"
 
+    # ---------------------------------------------------------------------------
+    # Risk Engine
+    # ---------------------------------------------------------------------------
+
+    /v1/risk/events:
+        get:
+            tags: [Risk Engine]
+            summary: List risk events
+            description: |
+                Returns risk events detected by the risk engine, ordered by most recent first.
+                Filter by severity or principal type.
+            operationId: listRiskEvents
+            parameters:
+                - name: severity
+                  in: query
+                  schema:
+                      type: string
+                      enum: [low, medium, high, critical]
+                  description: Filter events by severity level
+                - name: principal_type
+                  in: query
+                  schema:
+                      type: string
+                      enum: [user, agent]
+                  description: Filter events by principal type
+                - name: limit
+                  in: query
+                  schema:
+                      type: integer
+                      default: 50
+                - name: offset
+                  in: query
+                  schema:
+                      type: integer
+                      default: 0
+            responses:
+                "200":
+                    description: Risk event list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/RiskEventListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/risk/verdicts:
+        get:
+            tags: [Risk Engine]
+            summary: List risk verdicts
+            description: Returns all active risk verdicts for the caller's organization.
+            operationId: listRiskVerdicts
+            responses:
+                "200":
+                    description: Verdict list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/RiskVerdictListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/risk/verdicts/{principal_type}/{principal_id}:
+        get:
+            tags: [Risk Engine]
+            summary: Get risk verdict for a principal
+            description: Returns the current risk verdict for a specific user or agent.
+            operationId: getRiskVerdict
+            parameters:
+                - name: principal_type
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      enum: [user, agent]
+                - name: principal_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Risk verdict (null if no verdict exists)
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    verdict:
+                                        $ref: "#/components/schemas/RiskVerdict"
+                                        nullable: true
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/risk/honeytokens:
+        get:
+            tags: [Risk Engine]
+            summary: List honeytokens
+            description: Returns all honeytokens (canary secrets) configured for the caller's organization.
+            operationId: listHoneytokens
+            responses:
+                "200":
+                    description: Honeytoken list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/HoneytokenListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+        post:
+            tags: [Risk Engine]
+            summary: Create a honeytoken
+            description: |
+                Register a secret path as a honeytoken (canary). Any access to this secret
+                triggers a risk event and increments the trigger counter.
+            operationId: createHoneytoken
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateHoneytokenRequest"
+            responses:
+                "201":
+                    description: Honeytoken created
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    honeytoken:
+                                        $ref: "#/components/schemas/Honeytoken"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/risk/honeytokens/{id}:
+        delete:
+            tags: [Risk Engine]
+            summary: Delete a honeytoken
+            description: Remove a honeytoken registration. The underlying secret is not affected.
+            operationId: deleteHoneytoken
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Honeytoken deleted
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    deleted:
+                                        type: boolean
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
 # =============================================================================
 # COMPONENTS
 # =============================================================================
@@ -8043,6 +8254,32 @@ components:
                     type: string
                     format: uuid
 
+        OrgBankrConfigResponse:
+            type: object
+            properties:
+                configured:
+                    type: boolean
+                partner_key_prefix:
+                    type: string
+                default_wallet_id:
+                    type: string
+                updated_at:
+                    type: string
+                    format: date-time
+                using_platform_fallback:
+                    type: boolean
+
+        UpsertOrgBankrConfigRequest:
+            type: object
+            required: [partner_key]
+            properties:
+                partner_key:
+                    type: string
+                    description: Bankr partner API key (bk_ptr_...)
+                default_wallet_id:
+                    type: string
+                    description: Default provisioned wallet (wlt_...)
+
         # --- Billing ---
 
         UsageSummaryResponse:
@@ -10016,3 +10253,180 @@ components:
                 created_at:
                     type: string
                     format: date-time
+
+        # --- Risk Engine ---
+
+        RiskEvent:
+            type: object
+            required: [id, occurred_at, principal_type, principal_id, org_id, event_type, payload, created_at]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                occurred_at:
+                    type: string
+                    format: date-time
+                principal_type:
+                    type: string
+                    enum: [user, agent]
+                principal_id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                event_type:
+                    type: string
+                    description: "Risk event type (e.g. first_seen, geo_velocity, honeytoken_access)"
+                ip:
+                    type: string
+                    nullable: true
+                asn:
+                    type: integer
+                    nullable: true
+                asn_org:
+                    type: string
+                    nullable: true
+                country_code:
+                    type: string
+                    nullable: true
+                region:
+                    type: string
+                    nullable: true
+                city:
+                    type: string
+                    nullable: true
+                latitude:
+                    type: number
+                    nullable: true
+                longitude:
+                    type: number
+                    nullable: true
+                user_agent:
+                    type: string
+                    nullable: true
+                severity:
+                    type: string
+                    nullable: true
+                    description: "Computed severity at event time (low, medium, high, critical)"
+                payload:
+                    type: object
+                    additionalProperties: true
+                created_at:
+                    type: string
+                    format: date-time
+
+        RiskEventListResponse:
+            type: object
+            required: [events]
+            properties:
+                events:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/RiskEvent"
+
+        RiskVerdictReason:
+            type: object
+            required: [detector, severity, description]
+            properties:
+                detector:
+                    type: string
+                severity:
+                    type: string
+                description:
+                    type: string
+                metadata:
+                    type: object
+                    additionalProperties: true
+
+        RiskVerdict:
+            type: object
+            required: [principal_type, principal_id, org_id, score, severity, reasons, computed_at, expires_at]
+            properties:
+                principal_type:
+                    type: string
+                principal_id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                score:
+                    type: number
+                    description: Composite risk score (0.0 – 100.0)
+                severity:
+                    type: string
+                    enum: [low, medium, high, critical]
+                reasons:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/RiskVerdictReason"
+                computed_at:
+                    type: string
+                    format: date-time
+                expires_at:
+                    type: string
+                    format: date-time
+
+        RiskVerdictListResponse:
+            type: object
+            required: [verdicts]
+            properties:
+                verdicts:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/RiskVerdict"
+
+        Honeytoken:
+            type: object
+            required: [id, vault_id, org_id, secret_path, created_by, created_at, triggered_count]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                vault_id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                secret_path:
+                    type: string
+                created_by:
+                    type: string
+                    format: uuid
+                created_at:
+                    type: string
+                    format: date-time
+                notes:
+                    type: string
+                    nullable: true
+                triggered_count:
+                    type: integer
+                last_triggered_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+
+        CreateHoneytokenRequest:
+            type: object
+            required: [vault_id, secret_path]
+            properties:
+                vault_id:
+                    type: string
+                    format: uuid
+                secret_path:
+                    type: string
+                    description: Vault secret path to monitor as a canary
+                notes:
+                    type: string
+                    description: Optional human-readable notes about this honeytoken
+
+        HoneytokenListResponse:
+            type: object
+            required: [honeytokens]
+            properties:
+                honeytokens:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/Honeytoken"

package/package.json

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