container lifecycle management

2026-03-12 15:13:38 -04:00
parent e99ef5d2dd
commit b9cc397e05
61 changed files with 6880 additions and 31 deletions
--- a/doc/m_c_p_client_authentication_modes.md
+++ b/doc/m_c_p_client_authentication_modes.md
@@ -0,0 +1,80 @@
+Mode A: Platform Harness → Hosted Container (internal)
+   Auth: mTLS + platform-signed user claim
+   Network: k8s internal, never hits the internet
+
+Mode B: Platform Harness → External User Container (remote)
+   Auth: OAuth2 token issued by your platform
+   Network: public internet, TLS required
+
+Mode C: Third-party MCP Client → External User Container (standalone)
+   Auth: User-managed API key or local-only (no network)
+   Network: localhost or user's own network
+
+┌──────────────────────────────────────────────────────────┐
+│                     Platform (Postgres)                    │
+│                                                            │
+│  users                                                     │
+│  ├── id, email, password_hash, plan_tier                   │
+│  │                                                         │
+│  containers                                                │
+│  ├── user_id                                               │
+│  ├── type: "hosted" | "external"                           │
+│  ├── mcp_endpoint: "internal-svc:3100" | "https://..."     │
+│  ├── auth_method: "mtls" | "platform_token" | "api_key"    │
+│  └── public_key_fingerprint (for pinning external certs)   │
+│                                                            │
+│  api_tokens                                                │
+│  ├── user_id                                               │
+│  ├── token_hash                                            │
+│  ├── scopes: ["mcp:tools", "mcp:resources", "data:read"]  │
+│  ├── expires_at                                            │
+│  └── issued_for: "platform_harness" | "user_direct"        │
+│                                                            │
+└──────────────────────────────────────────────────────────┘
+
+## Mode A
+
+Harness ──mTLS──▶ k8s Service ──▶ User Container MCP
+Validates: source is platform namespace
+Extracts: user_id from forwarded header
+
+## Mode B
+
+Registration flow (one-time):
+1. User provides their MCP endpoint URL in platform settings
+2. Platform generates a scoped token (JWT, short-lived, auto-refreshed)
+3. User configures their MCP server to accept tokens signed by your platform
+4. Platform stores the endpoint + auth method
+
+Runtime:
+┌──────────┐   HTTPS + Bearer token    ┌────────────────────┐
+│ Harness  │ ─────────────────────────▶ │ External MCP Server│
+│          │   Authorization:           │                    │
+│          │   Bearer <platform_jwt>    │ Validates:         │
+│          │                            │  - JWT signature   │
+│          │                            │    (your public    │
+│          │                            │     key, JWKS)     │
+│          │                            │  - user_id claim   │
+│          │                            │    matches self    │
+│          │                            │  - not expired     │
+└──────────┘                            └────────────────────┘
+
+## Mode C
+
+```yaml
+# openclaw/config.yaml
+auth:
+  # For local-only use (Claude Desktop, Cursor, etc via stdio)
+  mode: "local"          # no network auth needed
+
+  # OR for remote access
+  mode: "token"
+  tokens:
+    - name: "my-laptop"
+      hash: "sha256:..."  # generated by `openclaw token create`
+
+  # OR for platform integration
+  mode: "platform"
+  platform_jwks_url: "https://api.openclaw.io/.well-known/jwks.json"
+  expected_user_id: "user_abc123"
+```