From cce635789ce4e508456351f182d6aaa3f02366cc Mon Sep 17 00:00:00 2001 From: rookiestar28 Date: Thu, 5 Mar 2026 03:57:18 +0800 Subject: [PATCH] docs: align security and API docs with connector/planner contracts --- README.md | 12 ++++++ docs/SECURITY.md | 13 ++++++ docs/openapi.yaml | 82 ++++++++++++++++++++++++++++++++++-- docs/release/api_contract.md | 19 ++++++++- 4 files changed, 121 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bd31631..817df3d 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,18 @@ Deployment profiles and hardening checklists:
+Today’s implementation roundup across frontend quality, planner contracts, and connector security baselines + +- Completed the frontend quality bundle by stabilizing canonical style ownership, adding baseline frontend unit coverage, and expanding regression coverage for Library/Approvals/admin-console parity. +- Completed SSRF pinning regression hardening with dedicated no-skip coverage for pinned connect paths, multi-IP failover ordering, and TLS wrap degradation branches. +- Completed planner profile/system-prompt externalization with validated file-backed registry loading, runtime-safe fallback/reload behavior, and synchronized profile sourcing across API, node, and Planner tab. +- Completed connector contract baseline with multi-workspace installation lifecycle registry, encrypted token references, fail-closed workspace resolution, and reusable interactive callback security decisions (signature/timestamp/hash/replay/idempotency/policy mapping) plus admin diagnostics APIs. +- Completed full verification gate pass on `dev` (detect-secrets, pre-commit, backend unit suites, adversarial/retry/real-backend lanes, and frontend Playwright E2E). + +
+ +
+ Connector multi-workspace installation and interactive callback contract baseline - Added a persistent connector installation registry with normalized installation identity (`platform`, `workspace_id`, `installation_id`, `token_refs`, `status`, `updated_at`) and explicit lifecycle transitions (`created`, `active`, `rotating`, `revoked`, `deactivated`, `uninstalled`). diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 28d31d1..10666f6 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -109,6 +109,19 @@ Operational requirement: - never enable connector platform tokens/enable flags in public or hardened posture without platform allowlist coverage. +### 4.1 Interactive Callback Contract Baseline (Connector) + +For interactive connector callbacks (actions/modals/workflow style payloads), the shared callback contract is fail-closed by default: + +- signed envelope is required (`signature`, `timestamp`, `request_id`, `workspace_id`, `action_type`, `payload_hash`) +- stale timestamp, replay/duplicate request ID, payload-hash mismatch, or unknown action type are rejected +- workspace-to-installation resolution is fail-closed on missing/ambiguous/inactive/stale-token-ref binding +- policy mapping is explicit (`public`/`run`/`admin`) and untrusted `run` callbacks degrade to approval instead of direct privileged execution + +Operational note: + +- treat callback decision codes/audit trails as security evidence and investigate repeated reject patterns before enabling higher-risk interactive flows. + ### 5. Startup Gate Behavior (R136 + S56) Startup security gates are fail-closed. Fatal startup gate/bootstrap failures abort route/worker registration and do not continue in a partial state. diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 147f0cc..fc6df87 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -201,6 +201,20 @@ paths: security: - OpenClawAdminToken: [] + /assist/planner/profiles: + get: + operationId: "get_assist_planner_profiles" + summary: "List active planner profiles from registry for UI/node alignment." + responses: + 200: + description: "OK" + x-openclaw-auth: "Admin/Local" + x-openclaw-section: "1.3 Assist, LLM & Chat" + x-openclaw-legacy-path: "/moltbot/assist/planner/profiles" + x-openclaw-auth-tier: "admin" + security: + - OpenClawAdminToken: + [] /assist/planner: post: operationId: "post_assist_planner" @@ -259,6 +273,68 @@ paths: - OpenClawAdminToken: [] x-openclaw-streaming: true + /connector/installations: + get: + operationId: "get_connector_installations" + summary: "List redacted connector installations with lifecycle diagnostics." + responses: + 200: + description: "OK" + x-openclaw-auth: "Admin" + x-openclaw-section: "1.3B Connector Installation Diagnostics" + x-openclaw-legacy-path: "/moltbot/connector/installations" + x-openclaw-auth-tier: "admin" + security: + - OpenClawAdminToken: + [] + /connector/installations/{installation_id}: + get: + operationId: "get_connector_installations_installation_id" + summary: "Get one redacted connector installation record." + responses: + 200: + description: "OK" + x-openclaw-auth: "Admin" + x-openclaw-section: "1.3B Connector Installation Diagnostics" + x-openclaw-legacy-path: "/moltbot/connector/installations/{installation_id}" + x-openclaw-auth-tier: "admin" + security: + - OpenClawAdminToken: + [] + parameters: + - name: "installation_id" + in: "path" + required: true + schema: + type: "string" + /connector/installations/resolve: + get: + operationId: "get_connector_installations_resolve" + summary: "Run fail-closed workspace resolution diagnostics (`platform`, `workspace_id`)." + responses: + 200: + description: "OK" + x-openclaw-auth: "Admin" + x-openclaw-section: "1.3B Connector Installation Diagnostics" + x-openclaw-legacy-path: "/moltbot/connector/installations/resolve" + x-openclaw-auth-tier: "admin" + security: + - OpenClawAdminToken: + [] + /connector/installations/audit: + get: + operationId: "get_connector_installations_audit" + summary: "List installation lifecycle audit evidence (redacted)." + responses: + 200: + description: "OK" + x-openclaw-auth: "Admin" + x-openclaw-section: "1.3B Connector Installation Diagnostics" + x-openclaw-legacy-path: "/moltbot/connector/installations/audit" + x-openclaw-auth-tier: "admin" + security: + - OpenClawAdminToken: + [] /chat: post: operationId: "post_chat" @@ -267,7 +343,7 @@ paths: 200: description: "OK" x-openclaw-auth: "Admin/Local" - x-openclaw-section: "1.3 Assist, LLM & Chat" + x-openclaw-section: "1.3C LLM Management & Chat" x-openclaw-legacy-path: "/moltbot/llm/chat" x-openclaw-auth-tier: "admin" security: @@ -281,7 +357,7 @@ paths: 200: description: "OK" x-openclaw-auth: "Admin" - x-openclaw-section: "1.3 Assist, LLM & Chat" + x-openclaw-section: "1.3C LLM Management & Chat" x-openclaw-legacy-path: "/moltbot/llm/test" x-openclaw-auth-tier: "admin" security: @@ -295,7 +371,7 @@ paths: 200: description: "OK" x-openclaw-auth: "Admin" - x-openclaw-section: "1.3 Assist, LLM & Chat" + x-openclaw-section: "1.3C LLM Management & Chat" x-openclaw-legacy-path: "/moltbot/llm/models" x-openclaw-auth-tier: "admin" security: diff --git a/docs/release/api_contract.md b/docs/release/api_contract.md index 9afd7f2..cff6959 100644 --- a/docs/release/api_contract.md +++ b/docs/release/api_contract.md @@ -1,8 +1,8 @@ # OpenClaw API Contract (v1) > **Status**: normative -> **Version**: 1.0.2 -> **Date**: 2026-02-28 +> **Version**: 1.0.3 +> **Date**: 2026-03-05 This document defines the public API contract for OpenClaw. It serves as the authoritative baseline for client compatibility and breaking change policies. @@ -53,11 +53,26 @@ All new integrations should use the `/openclaw/` prefix. Use of `/moltbot/` is d | Method | Path | Legacy Path | Auth | Description | | :--- | :--- | :--- | :--- | :--- | +| `GET` | `/assist/planner/profiles` | `/moltbot/assist/planner/profiles` | Admin/Local | List active planner profiles from registry for UI/node alignment. | | `POST` | `/assist/planner` | `/moltbot/assist/planner` | Admin/Local | Planner structured prompt generation. | | `POST` | `/assist/refiner` | `/moltbot/assist/refiner` | Admin/Local | Prompt refinement with optional image context. | | `POST` | `/assist/planner/stream` | `/moltbot/assist/planner/stream` | Admin/Local | Optional SSE-style planner streaming response (`text/event-stream`) with staged progress + final payload. | | `POST` | `/assist/refiner/stream` | `/moltbot/assist/refiner/stream` | Admin/Local | Optional SSE-style refiner streaming response (`text/event-stream`) with staged progress + final payload. | +### 1.3B Connector Installation Diagnostics + +**Base Path**: `/openclaw/connector/` +**Auth**: Admin Token Required + +| Method | Path | Legacy Path | Auth | Description | +| :--- | :--- | :--- | :--- | :--- | +| `GET` | `/connector/installations` | `/moltbot/connector/installations` | Admin | List redacted connector installations with lifecycle diagnostics. | +| `GET` | `/connector/installations/{installation_id}` | `/moltbot/connector/installations/{installation_id}` | Admin | Get one redacted connector installation record. | +| `GET` | `/connector/installations/resolve` | `/moltbot/connector/installations/resolve` | Admin | Run fail-closed workspace resolution diagnostics (`platform`, `workspace_id`). | +| `GET` | `/connector/installations/audit` | `/moltbot/connector/installations/audit` | Admin | List installation lifecycle audit evidence (redacted). | + +### 1.3C LLM Management & Chat + **LLM Base Path**: `/openclaw/llm/` | Method | Path | Legacy Path | Auth | Description |