diff --git a/.cass/playbook.yaml b/.cass/playbook.yaml new file mode 100644 index 0000000..25ebb9a --- /dev/null +++ b/.cass/playbook.yaml @@ -0,0 +1,12 @@ +# Project-specific playbook rules +# These are merged with your global ~/.cass-memory/playbook.yaml +# Project rules take precedence over global rules +schema_version: 2 +name: repo-playbook +description: Project-specific rules for this repository +metadata: + createdAt: 2026-03-09T04:30:43.156Z + totalReflections: 0 + totalSessionsProcessed: 0 +deprecatedPatterns: [] +bullets: [] diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..5f9ad99 --- /dev/null +++ b/.env.example @@ -0,0 +1,44 @@ +# Core control-plane settings +OCTW_DB_URL=postgresql+asyncpg://octw:octw@octw-db:5432/octw +OCTW_REDIS_URL=redis://octw-cache:6379/0 +OCTW_PUBLIC_BASE_URL=https://octw.example.com +OCTW_SERVER_NAME=octw.example.com +OCTW_EDGE_DOMAIN=octw.example.com +OCTW_API_INTERNAL_BASE_URL=http://octw-api:8000 +OCTW_TRUSTED_PROXY_ENABLED=true +OCTW_TRUSTED_PROXY_USER_HEADER=X-Forwarded-Email +OCTW_TRUSTED_PROXY_IPS=172.30.0.0/24 +OCTW_DEFAULT_PROVIDER=zai + +# Secrets +# Generate with: python3 -c "import secrets; print(secrets.token_urlsafe(32))" +OCTW_JWT_SECRET=replace-with-strong-random-token +# Generate with: python3 -c "import os; print(os.urandom(32).hex())" +OCTW_KEK=replace-with-64-hex-character-kek + +# Shared provider API keys (set at least one) +OCTW_ZAI_API_KEY= +OCTW_MOONSHOT_API_KEY= +OCTW_MINIMAX_API_KEY= + +# oauth2-proxy base settings +# Valid providers include: oidc, keycloak-oidc, google +OCTW_OIDC_PROVIDER=oidc +# Config file under configs/oauth2-proxy/ used by the oauth2-proxy container. +OCTW_OIDC_CONFIG_FILE=oauth2-proxy.cfg +# Required for generic OIDC and keycloak-oidc. Leave blank for google. +OCTW_OIDC_ISSUER_URL=https://issuer.example.com/realms/octw +OCTW_OIDC_CLIENT_ID=octw +OCTW_OIDC_CLIENT_SECRET=replace-with-oidc-client-secret +# Generate with: python3 -c "import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode().rstrip('='))" +OCTW_OIDC_COOKIE_SECRET=replace-with-base64-cookie-secret +# Restrict login to your workspace domain. Use * only for isolated test environments. +OCTW_OIDC_EMAIL_DOMAINS=example.com +# Allow oauth2-proxy redirects back to this host. Prefix subdomains with a dot. +OCTW_OIDC_WHITELIST_DOMAINS=.example.com + +# Provider-specific examples live in: +# configs/oauth2-proxy/keycloak.example.cfg +# configs/oauth2-proxy/google-workspace.example.cfg +# For Google Workspace group checks, place the Admin SDK service account JSON at: +# configs/oauth2-proxy/credentials/google-admin-sdk.json diff --git a/README.md b/README.md index c47ab57..34c0bbb 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,128 @@ # OCTW — OpenClaw Tenant Wrapper -OCTW is a multi-tenant abstraction layer that provisions and operates multiple independent [OpenClaw](https://github.com/openclaw/openclaw) installations on a single host. Each tenant gets its own isolated OpenClaw gateway, network, filesystem, credentials, and webchat — using the upstream container image without forking. +OCTW provisions and operates multiple isolated [OpenClaw](https://github.com/openclaw/openclaw) installations on one host. This branch adds a browser-first app flow: reverse-proxy OIDC login, one-click tenant deployment, verified readiness, wake-on-resume, and a minimal OCTW-hosted chat UI. ## Quick Start ### Prerequisites -- Docker (with compose plugin) -- [uv](https://docs.astral.sh/uv/) (for CLI and development) +- Docker Engine with the Compose plugin +- [uv](https://docs.astral.sh/uv/) for local development and tests +- At least one supported model provider API key +- A public DNS name that points to the VM +- OIDC client credentials for your IdP -### 1. Clone and prepare the host +### 1. Prepare the host ```bash -git clone https://github.com/kumanday/OCTW.git && cd OCTW +git clone https://github.com/kumanday/OCTW.git +cd OCTW sudo mkdir -p /var/lib/octw /etc/octw -sudo chown $USER /var/lib/octw +sudo chown "$USER" /var/lib/octw sudo python3 -c "import os; open('/etc/octw/master.key','wb').write(os.urandom(32))" -sudo chown $USER /etc/octw/master.key +sudo chown "$USER" /etc/octw/master.key sudo chmod 600 /etc/octw/master.key ``` -### 2. Configure provider API keys +### 2. Create `.env` -Set one or more LLM provider keys. At least one is required: +```bash +cp .env.example .env +``` + +Fill in these values at minimum: + +- `OCTW_KEK` +- `OCTW_JWT_SECRET` +- `OCTW_PUBLIC_BASE_URL` +- `OCTW_SERVER_NAME` +- `OCTW_TRUSTED_PROXY_ENABLED=true` +- one or more provider API keys such as `OCTW_ZAI_API_KEY` +- `OCTW_OIDC_CLIENT_ID` +- `OCTW_OIDC_CLIENT_SECRET` +- `OCTW_OIDC_COOKIE_SECRET` + +Useful generators: ```bash -export OCTW_ZAI_API_KEY="your-zai-key" # Z.ai GLM Coding Plan -export OCTW_MOONSHOT_API_KEY="your-moonshot-key" # Moonshot AI Kimi Coding Plan -export OCTW_MINIMAX_API_KEY="your-minimax-key" # MiniMax Coding Plan +python3 -c "import os; print(os.urandom(32).hex())" +python3 -c "import secrets; print(secrets.token_urlsafe(32))" +python3 -c "import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode().rstrip('='))" +``` + +### 3. Pick an OIDC provider profile + +The stack now includes both public ingress and OIDC inside Docker: + +- `octw-proxy` terminates HTTPS and routes requests +- `octw-oidc` runs `oauth2-proxy` + +Base oauth2-proxy settings live in [configs/oauth2-proxy/oauth2-proxy.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/oauth2-proxy.cfg). + +Provider examples: + +- Keycloak: [configs/oauth2-proxy/keycloak.example.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/keycloak.example.cfg) +- Google Workspace: [configs/oauth2-proxy/google-workspace.example.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/google-workspace.example.cfg) + +Typical Keycloak settings in `.env`: + +```dotenv +OCTW_OIDC_PROVIDER=keycloak-oidc +OCTW_OIDC_ISSUER_URL=https://keycloak.example.com/realms/octw +OCTW_OIDC_EMAIL_DOMAINS=example.com +OCTW_OIDC_WHITELIST_DOMAINS=.example.com ``` -### 3. Launch the stack +Typical Google Workspace settings in `.env`: + +```dotenv +OCTW_OIDC_PROVIDER=google +OCTW_OIDC_ISSUER_URL= +OCTW_OIDC_EMAIL_DOMAINS=example.com +OCTW_OIDC_WHITELIST_DOMAINS=.example.com +``` + +If you want Google Group checks, place the Admin SDK service account JSON at `configs/oauth2-proxy/credentials/google-admin-sdk.json` and copy the relevant settings from the Google example config. + +### 4. Launch the stack ```bash -export OCTW_KEK=$(python3 -c "print(open('/etc/octw/master.key','rb').read().hex())") -export OCTW_JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))") -docker compose up -d +docker compose up -d --build ``` -This starts four services: +This starts six services: | Service | Port | Purpose | |---|---|---| -| **octw-api** | 8000 | REST API and one-click provisioning | -| **octw-edge** | 8443 | Tenant proxy with wake-on-request | -| **octw-db** | 5432 | PostgreSQL (metadata, secrets, audit) | -| **octw-cache** | 6379 | Redis (sessions, locks) | +| `octw-proxy` | `80`, `443` | Public HTTPS ingress and routing | +| `octw-oidc` | internal | `oauth2-proxy` for OIDC login/session | +| `octw-api` | `127.0.0.1:8000` | API, browser app, provisioning workflow | +| `octw-edge` | `127.0.0.1:8443` | Auth-aware tenant HTTP and WebSocket proxy | +| `octw-db` | `5432` | PostgreSQL metadata store | +| `octw-cache` | `6379` | Redis sessions and locks | + +If `configs/certs/fullchain.pem` and `configs/certs/privkey.pem` do not exist, `octw-proxy` generates an ephemeral self-signed certificate inside the container for bootstrap only. Mount real cert files in `configs/certs/` for production. + +### 5. Open the browser app + +Open: + +```text +https://octw.example.com/app +``` + +The browser flow is: -### 4. Provision a tenant +1. `octw-proxy` sends the request through `octw-oidc` +2. OCTW boots or refreshes the local `octw_session` cookie from the trusted forwarded email header +3. `POST /api/v1/app/deploy-or-resume` creates or resumes the user's single tenant +4. OCTW verifies the OpenClaw tenant before returning success +5. The browser connects to `/t/{slug}/ws` through `octw-edge` and lands in chat + +### 6. Operator / CLI provisioning still works ```bash -# Authenticate TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \ -H 'Content-Type: application/json' \ -d '{"email":"admin@example.com"}' | jq -r .dev_token) @@ -60,35 +131,28 @@ JWT=$(curl -s -X POST http://localhost:8000/api/v1/auth/verify \ -H 'Content-Type: application/json' \ -d "{\"token\":\"$TOKEN\"}" | jq -r .access_token) -# One-click provision curl -s -X POST http://localhost:8000/api/v1/provision \ -H "Authorization: Bearer $JWT" \ -H 'Content-Type: application/json' \ -d '{"slug":"acme", "name":"Acme Corp", "provider":"zai"}' | jq ``` -Response: +The provision response now includes readiness verification: + ```json { "tenant_id": "...", "slug": "acme", "status": "running", "provider": "zai", - "model": "zai-coding/glm-5", - "url": "https://octw.example.com/acme/" + "model": "zai/glm-5", + "url": "https://octw.example.com/acme/", + "verification_status": "verified", + "verification_error": null } ``` -The tenant's OpenClaw webchat is accessible at `https://octw.example.com/acme/`. - -### 5. List available providers - -```bash -curl -s http://localhost:8000/api/v1/provision/providers \ - -H "Authorization: Bearer $JWT" | jq -``` - -## CLI +## Operator CLI ```bash uv sync @@ -97,19 +161,19 @@ uv run octw tenant status uv run octw tenant stop ``` -See [docs/cli.md](docs/cli.md) for the full command reference. +See [docs/cli.md](/Users/magos/dev/kumanday/OCTW/docs/cli.md). ## Documentation | Document | Contents | |---|---| -| [Architecture](docs/architecture.md) | Component overview, isolation model, data flow | -| [API Reference](docs/api.md) | All REST endpoints with request/response examples | -| [Providers](docs/providers.md) | Supported LLM providers, adding new ones | -| [Configuration](docs/configuration.md) | All environment variables and defaults | -| [Security](docs/security.md) | Threat model, secret strategy, container hardening | -| [CLI Reference](docs/cli.md) | Operator command-line tool | -| [Deployment](docs/deployment.md) | Production setup, Docker Compose, development mode | +| [docs/architecture.md](/Users/magos/dev/kumanday/OCTW/docs/architecture.md) | Control-plane and tenant data flow | +| [docs/api.md](/Users/magos/dev/kumanday/OCTW/docs/api.md) | Browser app, operator API, and internal endpoints | +| [docs/configuration.md](/Users/magos/dev/kumanday/OCTW/docs/configuration.md) | Environment variables and proxy config files | +| [docs/deployment.md](/Users/magos/dev/kumanday/OCTW/docs/deployment.md) | Compose deployment, OIDC setup, verification | +| [docs/security.md](/Users/magos/dev/kumanday/OCTW/docs/security.md) | Reverse-proxy auth, trusted-proxy boundaries, secrets | +| [docs/providers.md](/Users/magos/dev/kumanday/OCTW/docs/providers.md) | Supported model providers | +| [docs/cli.md](/Users/magos/dev/kumanday/OCTW/docs/cli.md) | Operator CLI reference | ## Running Tests @@ -119,4 +183,4 @@ uv run pytest tests/ -v ## License -See [LICENSE](LICENSE). +See [LICENSE](/Users/magos/dev/kumanday/OCTW/LICENSE). diff --git a/configs/certs/.gitkeep b/configs/certs/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/configs/nginx/default.conf.template b/configs/nginx/default.conf.template new file mode 100644 index 0000000..aeba890 --- /dev/null +++ b/configs/nginx/default.conf.template @@ -0,0 +1,98 @@ +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} + +server { + listen 8080; + server_name ${OCTW_SERVER_NAME}; + port_in_redirect off; + return 301 https://$host$request_uri; +} + +server { + listen 8443 ssl; + http2 on; + server_name ${OCTW_SERVER_NAME}; + port_in_redirect off; + + ssl_certificate ${OCTW_SSL_CERT_FILE}; + ssl_certificate_key ${OCTW_SSL_KEY_FILE}; + ssl_session_timeout 1d; + ssl_session_cache shared:SSL:10m; + ssl_protocols TLSv1.2 TLSv1.3; + + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Port 443; + + location ^~ /oauth2/ { + proxy_pass http://octw-oidc:4180; + proxy_set_header X-Forwarded-Uri $request_uri; + proxy_set_header X-Scheme https; + } + + location = /oauth2/auth { + internal; + proxy_pass http://octw-oidc:4180/oauth2/auth; + proxy_set_header X-Forwarded-Uri $request_uri; + proxy_set_header Content-Length ""; + proxy_pass_request_body off; + } + + error_page 401 = @oauth2_signin; + + location @oauth2_signin { + return 302 /oauth2/start?rd=$scheme://$http_host$request_uri; + } + + location = /health { + proxy_pass http://octw-api:8000/health; + } + + location = / { + return 302 /app; + } + + location ^~ /app { + auth_request /oauth2/auth; + auth_request_set $user_email $upstream_http_x_auth_request_email; + proxy_set_header X-Forwarded-Email $user_email; + proxy_pass http://octw-api:8000; + } + + location ^~ /api/v1/app/ { + auth_request /oauth2/auth; + auth_request_set $user_email $upstream_http_x_auth_request_email; + proxy_set_header X-Forwarded-Email $user_email; + proxy_read_timeout 300s; + proxy_send_timeout 300s; + proxy_pass http://octw-api:8000; + } + + location /t/ { + auth_request /oauth2/auth; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_pass http://octw-edge:8443; + } + + location /oauth2/sign_out { + proxy_pass http://octw-oidc:4180/oauth2/sign_out; + } + + location ~ ^/[a-z0-9][a-z0-9-]*/? { + auth_request /oauth2/auth; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_pass http://octw-edge:8443; + } + + location / { + return 404; + } +} diff --git a/configs/oauth2-proxy/credentials/.gitkeep b/configs/oauth2-proxy/credentials/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/configs/oauth2-proxy/google-workspace.example.cfg b/configs/oauth2-proxy/google-workspace.example.cfg new file mode 100644 index 0000000..d4bf430 --- /dev/null +++ b/configs/oauth2-proxy/google-workspace.example.cfg @@ -0,0 +1,20 @@ +# Google Workspace example for oauth2-proxy. +# Copy the relevant settings into oauth2-proxy.cfg or keep this file as a +# reference while setting OCTW_OIDC_PROVIDER=google. + +provider = "google" +email_domains = ["example.com"] +whitelist_domains = [".example.com"] + +# Optional: require membership in one or more Google Groups. +# This requires Admin SDK access. Mount the service account JSON at: +# configs/oauth2-proxy/credentials/google-admin-sdk.json +# inside the container as /var/run/oauth2-proxy/google-admin-sdk.json. +# google_admin_email = "admin@example.com" +# google_groups = ["octw-users@example.com"] +# google_service_account_json = "/var/run/oauth2-proxy/google-admin-sdk.json" + +# Optional: if you run on GCP with Workload Identity instead of a JSON key. +# google_use_application_default_credentials = true +# google_target_principal = "oauth2-proxy@example-project.iam.gserviceaccount.com" +# google_use_organization_id = true diff --git a/configs/oauth2-proxy/keycloak.example.cfg b/configs/oauth2-proxy/keycloak.example.cfg new file mode 100644 index 0000000..a36da15 --- /dev/null +++ b/configs/oauth2-proxy/keycloak.example.cfg @@ -0,0 +1,18 @@ +# Keycloak example for oauth2-proxy. +# Copy the relevant settings into oauth2-proxy.cfg or keep this file as a +# reference while setting OCTW_OIDC_PROVIDER=keycloak-oidc. + +provider = "keycloak-oidc" +oidc_issuer_url = "https://keycloak.example.com/realms/octw" +scope = "openid profile email roles groups" +email_domains = ["example.com"] +whitelist_domains = [".example.com"] + +# Optional: require realm or client roles presented by Keycloak. +# allowed_roles = ["octw-user"] + +# Optional: require membership in explicit Keycloak groups. +# keycloak_groups = ["/octw-users"] + +# Optional: trust a private CA when Keycloak uses an internal certificate. +# provider_ca_files = ["/var/run/oauth2-proxy/keycloak-ca.pem"] diff --git a/configs/oauth2-proxy/oauth2-proxy.cfg b/configs/oauth2-proxy/oauth2-proxy.cfg new file mode 100644 index 0000000..e1e51de --- /dev/null +++ b/configs/oauth2-proxy/oauth2-proxy.cfg @@ -0,0 +1,33 @@ +# Base oauth2-proxy configuration used by docker-compose.yml. +# Provider selection and secrets come from environment variables so the same +# file can be used for generic OIDC, Keycloak, or Google Workspace. + +http_address = "0.0.0.0:4180" +upstreams = ["static://202"] + +set_xauthrequest = true +reverse_proxy = true +proxy_websockets = true +skip_provider_button = true +scope = "openid profile email" + +cookie_name = "__Host-octw_oauth2" +cookie_secure = true +cookie_httponly = true +cookie_samesite = "lax" +cookie_path = "/" +cookie_refresh = "1h" +cookie_expire = "8h" + +pass_access_token = false +pass_authorization_header = false +set_authorization_header = false +skip_auth_strip_headers = true + +session_store_type = "redis" +redis_connection_url = "redis://octw-cache:6379/1" + +standard_logging = true +request_logging = true +auth_logging = true +silence_ping_logging = true diff --git a/docker-compose.yml b/docker-compose.yml index 61cf67d..c59364a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -30,6 +30,7 @@ services: - octw_control octw-api: + container_name: octw-api build: context: . dockerfile: Dockerfile @@ -38,7 +39,7 @@ services: # The edge proxy runs as non-root (UID 1000). user: "0:0" ports: - - "8000:8000" + - "127.0.0.1:8000:8000" environment: OCTW_DB_URL: "postgresql+asyncpg://octw:octw@octw-db:5432/octw" OCTW_REDIS_URL: "redis://octw-cache:6379/0" @@ -47,6 +48,10 @@ services: OCTW_ZAI_API_KEY: "${OCTW_ZAI_API_KEY:-}" OCTW_MOONSHOT_API_KEY: "${OCTW_MOONSHOT_API_KEY:-}" OCTW_MINIMAX_API_KEY: "${OCTW_MINIMAX_API_KEY:-}" + OCTW_PUBLIC_BASE_URL: "${OCTW_PUBLIC_BASE_URL:-https://octw.example.com}" + OCTW_TRUSTED_PROXY_ENABLED: "${OCTW_TRUSTED_PROXY_ENABLED:-false}" + OCTW_TRUSTED_PROXY_USER_HEADER: "${OCTW_TRUSTED_PROXY_USER_HEADER:-X-Forwarded-Email}" + OCTW_TRUSTED_PROXY_IPS: "${OCTW_TRUSTED_PROXY_IPS:-172.30.0.0/24}" volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/octw:/var/lib/octw @@ -59,25 +64,74 @@ services: - octw_control octw-edge: + container_name: octw-edge build: context: . dockerfile: Dockerfile command: ["uvicorn", "octw.edge.proxy:edge_app", "--host", "0.0.0.0", "--port", "8443"] ports: - - "8443:8443" + - "127.0.0.1:8443:8443" environment: OCTW_DB_URL: "postgresql+asyncpg://octw:octw@octw-db:5432/octw" OCTW_REDIS_URL: "redis://octw-cache:6379/0" OCTW_JWT_SECRET: "${OCTW_JWT_SECRET:-change-me-in-production}" OCTW_EDGE_DOMAIN: "${OCTW_EDGE_DOMAIN:-octw.example.com}" + OCTW_API_INTERNAL_BASE_URL: "${OCTW_API_INTERNAL_BASE_URL:-http://octw-api:8000}" + OCTW_PUBLIC_BASE_URL: "${OCTW_PUBLIC_BASE_URL:-https://octw.example.com}" depends_on: - octw-api networks: - octw_control + octw-oidc: + image: quay.io/oauth2-proxy/oauth2-proxy:v7.14.3 + container_name: octw-oidc + command: + - --config=/etc/oauth2-proxy/${OCTW_OIDC_CONFIG_FILE:-oauth2-proxy.cfg} + environment: + OAUTH2_PROXY_PROVIDER: "${OCTW_OIDC_PROVIDER:-oidc}" + OAUTH2_PROXY_OIDC_ISSUER_URL: "${OCTW_OIDC_ISSUER_URL:-}" + OAUTH2_PROXY_REDIRECT_URL: "${OCTW_PUBLIC_BASE_URL:-https://octw.example.com}/oauth2/callback" + OAUTH2_PROXY_CLIENT_ID: "${OCTW_OIDC_CLIENT_ID}" + OAUTH2_PROXY_CLIENT_SECRET: "${OCTW_OIDC_CLIENT_SECRET}" + OAUTH2_PROXY_COOKIE_SECRET: "${OCTW_OIDC_COOKIE_SECRET}" + OAUTH2_PROXY_EMAIL_DOMAINS: "${OCTW_OIDC_EMAIL_DOMAINS:-*}" + OAUTH2_PROXY_WHITELIST_DOMAINS: "${OCTW_OIDC_WHITELIST_DOMAINS:-}" + depends_on: + octw-cache: + condition: service_healthy + volumes: + - ./configs/oauth2-proxy:/etc/oauth2-proxy:ro + - ./configs/oauth2-proxy/credentials:/var/run/oauth2-proxy:ro + networks: + - octw_control + + octw-proxy: + container_name: octw-proxy + build: + context: . + dockerfile: docker/proxy/Dockerfile + environment: + OCTW_SERVER_NAME: "${OCTW_SERVER_NAME:-octw.example.com}" + ports: + - "80:8080" + - "443:8443" + depends_on: + - octw-api + - octw-edge + - octw-oidc + volumes: + - ./configs/nginx:/etc/nginx/templates:ro + - ./configs/certs:/etc/nginx/certs:ro + networks: + - octw_control + volumes: octw_pgdata: networks: octw_control: driver: bridge + ipam: + config: + - subnet: 172.30.0.0/24 diff --git a/docker/proxy/Dockerfile b/docker/proxy/Dockerfile new file mode 100644 index 0000000..641ed46 --- /dev/null +++ b/docker/proxy/Dockerfile @@ -0,0 +1,15 @@ +FROM nginxinc/nginx-unprivileged:1.27-alpine + +USER root + +RUN apk add --no-cache bash gettext openssl + +COPY docker/proxy/entrypoint.sh /entrypoint.sh +COPY configs/nginx/default.conf.template /etc/nginx/templates/default.conf.template + +RUN chmod +x /entrypoint.sh + +USER 101:101 + +ENTRYPOINT ["/entrypoint.sh"] +CMD ["nginx", "-g", "daemon off;"] diff --git a/docker/proxy/entrypoint.sh b/docker/proxy/entrypoint.sh new file mode 100644 index 0000000..7fbae15 --- /dev/null +++ b/docker/proxy/entrypoint.sh @@ -0,0 +1,31 @@ +#!/bin/sh +set -eu + +CERT_DIR=/etc/nginx/certs +CERT_FILE="$CERT_DIR/fullchain.pem" +KEY_FILE="$CERT_DIR/privkey.pem" +GENERATED_CERT_DIR=/tmp/nginx-certs +GENERATED_CERT_FILE="$GENERATED_CERT_DIR/fullchain.pem" +GENERATED_KEY_FILE="$GENERATED_CERT_DIR/privkey.pem" + +if [ ! -r "$CERT_FILE" ] || [ ! -r "$KEY_FILE" ]; then + SERVER_NAME="${OCTW_SERVER_NAME:-localhost}" + echo "Using ephemeral self-signed TLS certificate for ${SERVER_NAME}" >&2 + mkdir -p "$GENERATED_CERT_DIR" + openssl req -x509 -nodes -newkey rsa:2048 \ + -keyout "$GENERATED_KEY_FILE" \ + -out "$GENERATED_CERT_FILE" \ + -days 365 \ + -subj "/CN=${SERVER_NAME}" + export OCTW_SSL_CERT_FILE="$GENERATED_CERT_FILE" + export OCTW_SSL_KEY_FILE="$GENERATED_KEY_FILE" +else + export OCTW_SSL_CERT_FILE="$CERT_FILE" + export OCTW_SSL_KEY_FILE="$KEY_FILE" +fi + +envsubst '${OCTW_SERVER_NAME} ${OCTW_SSL_CERT_FILE} ${OCTW_SSL_KEY_FILE}' \ + < /etc/nginx/templates/default.conf.template \ + > /etc/nginx/conf.d/default.conf + +exec "$@" diff --git a/docs/api.md b/docs/api.md index 47bbafe..529114e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,35 +1,107 @@ # API Reference -Base URL: `http://localhost:8000/api/v1` +Base operator API URL: `http://localhost:8000/api/v1` -All endpoints require a Bearer token except auth endpoints. Obtain a token via the login/verify flow. +There are now two auth modes: -## Authentication +- operator and CLI endpoints use OCTW bearer tokens +- browser app endpoints under `/api/v1/app/*` are expected to sit behind `octw-proxy` and OIDC + +## Browser App Routes + +### GET `/app` + +Serves the single-page OCTW browser shell. + +### GET `/app/chat` + +Serves the same shell and resumes the chat view. + +### GET `/api/v1/app/session` + +Bootstrap endpoint for the browser app. + +Behavior: + +- if `octw_session` exists, returns the current user and tenant state +- otherwise, if the request came through the trusted reverse proxy, creates the local user if needed, mints `octw_session`, and returns the same payload +- otherwise returns `401` + +Response: + +```json +{ + "user_id": "550e8400-e29b-41d4-a716-446655440000", + "email": "user@example.com", + "tenant": { + "tenant_id": "44262e00-b7fc-462a-bf2e-8f7b750f4cfe", + "slug": "u-0123456789abcdef0123", + "status": "running", + "verification_status": "verified", + "verification_error": null, + "chat_url": "https://octw.example.com/app/chat" + } +} +``` + +### POST `/api/v1/app/deploy-or-resume` + +Idempotent browser flow entrypoint. + +Behavior: + +- creates the signed-in user's single tenant if it does not exist yet +- otherwise wakes the existing tenant if it is paused or stopped +- re-runs verification if the tenant is not currently marked `verified` + +Response: + +```json +{ + "created": true, + "tenant": { + "tenant_id": "44262e00-b7fc-462a-bf2e-8f7b750f4cfe", + "slug": "u-0123456789abcdef0123", + "status": "running", + "verification_status": "verified", + "verification_error": null, + "chat_url": "https://octw.example.com/app/chat" + } +} +``` + +### WebSocket `/t/{slug}/ws` + +Browser chat connections go through `octw-edge` on this path. + +`octw-edge` validates the OCTW session, checks tenant membership, wakes the tenant if needed, and then proxies the WebSocket to the tenant gateway. + +## Authentication Endpoints ### POST `/auth/login` -Request a magic link token. +Request a development magic-link token. ```json { "email": "user@example.com" } ``` -Response (202): +Response: + ```json { "message": "Check your email for a login link", "dev_token": "..." } ``` -In development, `dev_token` is returned directly. In production, the token would be sent via email. - ### POST `/auth/verify` -Exchange a magic link token for a session JWT. +Exchange a dev token for an OCTW bearer token and `octw_session` cookie. ```json { "token": "" } ``` Response: + ```json { "access_token": "eyJ...", @@ -41,33 +113,20 @@ Response: ### POST `/auth/logout` -Response: 204 No Content - ---- +Placeholder endpoint. Browser logout is currently expected to happen through `/oauth2/sign_out` at the ingress layer. ## Provisioning ### GET `/provision/providers` -List available providers and whether they are configured on the server. - -Response: -```json -[ - { - "key": "zai", - "display_name": "Z.ai GLM Coding Plan", - "model": "zai-coding/glm-5", - "configured": true - } -] -``` +List supported providers and whether their server-side API key is configured. ### POST `/provision` -One-click tenant provisioning. Creates tenant, runs OpenClaw onboarding, configures webchat and model, starts container. +Operator one-click provisioning flow. Request: + ```json { "slug": "acme", @@ -77,232 +136,99 @@ Request: } ``` -- `slug` — DNS-safe identifier (3-50 chars, lowercase alphanumeric and hyphens) -- `name` — display name -- `provider` — one of `zai`, `moonshot`, `minimax` (default: `zai`) -- `secrets` — optional additional per-tenant secrets +Response: -Response (200): ```json { - "tenant_id": "550e8400-...", + "tenant_id": "550e8400-e29b-41d4-a716-446655440000", "slug": "acme", "status": "running", "provider": "zai", - "model": "zai-coding/glm-5", - "url": "https://octw.example.com/acme/" + "model": "zai/glm-5", + "url": "https://octw.example.com/acme/", + "verification_status": "verified", + "verification_error": null } ``` -Error responses: -- 400 — invalid provider or provider not configured on server -- 409 — slug already exists +A successful response implies the config exists, the gateway is healthy, and a server-side WebSocket connection to the tenant succeeded. ---- - -## Tenants +## Tenant Management ### POST `/tenants` -Create a tenant without provisioning OpenClaw (use `/provision` for the full flow). - -```json -{ - "slug": "acme", - "name": "Acme Corp", - "plan": "standard", - "isolation_mode": "standard", - "trusted_proxy_auth": true -} -``` - -Response (201): -```json -{ "tenantId": "...", "slug": "acme", "status": "stopped" } -``` +Create tenant metadata without running the provisioning workflow. ### GET `/tenants` -List tenants the authenticated user belongs to. +List tenants visible to the caller. ### GET `/tenants/{tenantId}` -Get tenant details. Requires membership. +Fetch tenant details. ### PATCH `/tenants/{tenantId}` -Update tenant (currently supports `name`). Requires `tenant_admin` role. +Update mutable tenant fields such as `name`. ### DELETE `/tenants/{tenantId}` -Delete tenant and all resources. Requires `tenant_admin` role. Response: 204. - ---- - -## Members - -### GET `/tenants/{tenantId}/members` - -List tenant members and their roles. - -### POST `/tenants/{tenantId}/members` - -Add a member. Requires `tenant_admin` role. - -```json -{ "email": "user@example.com", "role": "tenant_user" } -``` - -Roles: `tenant_admin`, `tenant_user`, `tenant_viewer`. - -### DELETE `/tenants/{tenantId}/members/{userId}` - -Remove a member. Requires `tenant_admin` role. Response: 204. - ---- +Delete the tenant and its resources. ## Secrets -Secrets are encrypted at rest (AES-256-GCM envelope encryption). The API never returns secret values. - ### GET `/tenants/{tenantId}/secrets` -List secret metadata (names, types, timestamps — never values). +List secret metadata. Values are never returned. ### PUT `/tenants/{tenantId}/secrets/{name}` -Create or update a secret. Requires `tenant_admin` role. - -```json -{ - "value": "sk-...", - "type": "env", - "target_env_var": "OPENAI_API_KEY" -} -``` +Create or replace a secret. ### DELETE `/tenants/{tenantId}/secrets/{name}` -Delete a secret. Requires `tenant_admin` role. Response: 204. +Delete a secret. ### POST `/tenants/{tenantId}/secrets/rotate` -Rotate a secret (provide new value). Requires `tenant_admin` role. - -```json -{ "name": "OPENAI_API_KEY", "value": "sk-new-..." } -``` - ---- +Rotate a secret value. ## Runtime Control ### GET `/tenants/{tenantId}/runtime` -Get tenant runtime state, container ID, last activity, and resource limits. - -```json -{ - "tenant_id": "...", - "state": "running", - "container_id": "abc123...", - "last_activity_at": "2026-02-28T...", - "limits": { "mem_limit": "1536m", "cpu_quota": 100000, "pids_limit": 512 } -} -``` - -States: `running`, `paused`, `stopped`, `error`, `not_found`. +Return runtime state and resource limits. ### POST `/tenants/{tenantId}/runtime/start` -Start the tenant container. Requires `tenant_user` or above. +Start the tenant container. ### POST `/tenants/{tenantId}/runtime/stop` -Stop and remove the tenant container. Requires `tenant_user` or above. +Stop and remove the tenant container. ### POST `/tenants/{tenantId}/runtime/pause` -Pause the container (memory retained, CPU released). Requires `tenant_user` or above. +Pause the tenant container. ### POST `/tenants/{tenantId}/runtime/wake` -Wake a paused or stopped tenant. Requires `tenant_user` or above. +Wake a paused or stopped tenant. ### GET `/tenants/{tenantId}/runtime/logs` -Get container logs. - -Query parameters: -- `since` — Unix timestamp -- `tail` — number of lines (default 200, max 5000) +Return container logs. ---- +## Internal API -## Internal Endpoints +Internal base URL: `http://octw-api:8000/internal/v1/tenants` -These are used by octw-edge and should be restricted to internal access (mTLS in production). +These endpoints are intended for `octw-edge` and internal automation. -Base URL: `http://localhost:8000/internal/v1/tenants` - -All endpoints accept either a UUID or slug as the `{identifier}`. - -| Method | Path | Description | -|---|---|---| -| POST | `/{identifier}/ensure-running` | Wake tenant if not running | -| POST | `/{identifier}/pause-if-idle` | Pause tenant | -| POST | `/{identifier}/stop-if-idle` | Stop tenant | -| GET | `/{identifier}/status` | Get container state and IP | - -### GET `/{identifier}/status` Response - -```json -{ "state": "running", "ip": "172.18.0.5" } -``` - ---- - -## Metrics - -### GET `/metrics` - -Prometheus-format metrics endpoint. No authentication required. - -```bash -curl http://localhost:8000/metrics -``` - -Available metrics: - -| Metric | Type | Description | +| Method | Path | Purpose | |---|---|---| -| `octw_tenant_container_starts_total` | Counter | Tenant container start events (label: `tenant_id`) | -| `octw_tenant_container_stops_total` | Counter | Tenant container stop events (label: `tenant_id`) | -| `octw_tenant_wake_events_total` | Counter | Wake-on-request events (label: `tenant_id`) | -| `octw_tenant_pause_events_total` | Counter | Tenant pause events (label: `tenant_id`) | -| `octw_active_tenants` | Gauge | Currently running tenant containers | -| `octw_proxy_request_duration_seconds` | Histogram | Edge proxy request duration (labels: `tenant_slug`, `method`, `status`) | -| `octw_secret_operations_total` | Counter | Secret lifecycle operations (labels: `tenant_id`, `operation`) | -| `octw_auth_failures_total` | Counter | Authentication failures (label: `reason`) | - -A Prometheus scrape config is provided at `configs/prometheus.yml`. - ---- - -## Health - -### GET `/health` - -Health check endpoint on octw-api. No authentication required. - -```json -{ "status": "ok" } -``` - -### GET `/health` (octw-edge, port 8443) - -Health check endpoint on octw-edge. - -```json -{ "status": "ok", "service": "octw-edge" } -``` +| `POST` | `/{identifier}/ensure-running` | Wake tenant if needed | +| `GET` | `/{identifier}/access/{user_id}` | Confirm membership before proxying | +| `POST` | `/{identifier}/pause-if-idle` | Pause tenant | +| `POST` | `/{identifier}/stop-if-idle` | Stop tenant | +| `GET` | `/{identifier}/status` | Return runtime state and container IP | diff --git a/docs/architecture-1.pdf b/docs/architecture-1.pdf new file mode 100644 index 0000000..b016244 Binary files /dev/null and b/docs/architecture-1.pdf differ diff --git a/docs/architecture-1.png b/docs/architecture-1.png new file mode 100644 index 0000000..c27ab91 Binary files /dev/null and b/docs/architecture-1.png differ diff --git a/docs/architecture.md b/docs/architecture.md index 133e87c..46bc0b0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,120 +2,91 @@ ## Overview -OCTW runs one OpenClaw gateway container per tenant. All tenants share a common control plane (API, database, cache, edge proxy) but are isolated at the container, network, and filesystem levels. - -``` - Internet / VPN / Tailnet - | - v - +-----------------+ - | octw-edge | - | //... | - | Auth + Wake-on | - +--------+--------+ - | - +-------------+--------------+ - | | - v v - +--------------------+ +--------------------+ - | tenant net: T1 | | tenant net: T2 | - | +---------------+ | | +---------------+ | - | | openclaw T1 | | | | openclaw T2 | | - | | port 18789 | | | | port 18789 | | - | +---------------+ | | +---------------+ | - +--------------------+ +--------------------+ - -Control plane (host internal): -+----------+ +---------+ +-------+ -| octw-api |---| octw-db |---| redis | -+----------+ +---------+ +-------+ - | - v -+----------------+ -| orchestrator | -| (Docker API) | -+----------------+ +OCTW runs one OpenClaw gateway container per tenant and keeps all tenant gateways private on Docker networks. A shared control plane handles browser auth, provisioning, verification, runtime control, and proxying. + +```mermaid +flowchart LR + browser["Browser"] --> proxy["octw-proxy
Nginx HTTPS ingress"] + proxy --> oidc["octw-oidc
oauth2-proxy"] + proxy --> api["octw-api
FastAPI"] + proxy --> edge["octw-edge
HTTP + WS proxy"] + api --> db["octw-db
PostgreSQL"] + api --> cache["octw-cache
Redis"] + api --> docker["Docker API"] + edge --> tenant1["Tenant gateway A"] + edge --> tenant2["Tenant gateway B"] ``` ## Components | Component | Technology | Role | |---|---|---| -| **octw-api** | FastAPI (Python) | REST API for provisioning, tenant CRUD, RBAC, secrets, runtime control | -| **octw-edge** | FastAPI + httpx | Reverse proxy: path-based tenant routing (`//`), JWT auth, wake-on-request | -| **octw-db** | PostgreSQL 16 | Metadata, memberships, audit logs, encrypted secret ciphertext, tenant DEKs | -| **octw-cache** | Redis 7 | Sessions, rate limiting, orchestration locks | -| **orchestrator** | Docker SDK for Python | Container lifecycle, network creation, resource limits, init jobs | -| **vault** | cryptography (Python) | AES-256-GCM envelope encryption for secrets at rest | -| **CLI** | Click | Operator tool for tenant and secret management | +| `octw-proxy` | Nginx | Public HTTPS entrypoint, `auth_request`, browser routing | +| `octw-oidc` | oauth2-proxy | OIDC login, secure proxy session cookie, forwarded identity headers | +| `octw-api` | FastAPI | Browser app shell, operator API, provisioning, tenant verification | +| `octw-edge` | FastAPI + httpx + websockets | Membership-aware tenant HTTP and WebSocket proxy | +| `octw-db` | PostgreSQL | Users, tenants, memberships, audit, encrypted secret metadata | +| `octw-cache` | Redis | Sessions, locks, coordination | +| tenant gateway | OpenClaw | Per-tenant runtime with trusted-proxy auth | -## Data Flow +## Browser Flow -### One-Click Provisioning +1. Browser requests `/app` +2. `octw-proxy` delegates auth to `octw-oidc` +3. `octw-api` mints or refreshes `octw_session` from the trusted forwarded email header +4. `/api/v1/app/deploy-or-resume` creates or resumes the user's single tenant +5. `octw-api` waits for tenant verification +6. Browser connects to `/t/{slug}/ws` +7. `octw-edge` validates membership, wakes the tenant if needed, and proxies the WebSocket to the tenant gateway -``` -Web App - │ - ├─► POST /api/v1/provision { slug, name, provider } - │ - ▼ -octw-api - ├─ 1. Create tenant row in DB - ├─ 2. Create filesystem dirs (/var/lib/octw/tenants//) - ├─ 3. Create isolated Docker network - ├─ 4. Run init container (openclaw onboard --non-interactive) - │ └─ Provider API key + model injected via env vars - ├─ 5. Patch openclaw.json (webchat, gateway bind, model config) - ├─ 6. Start tenant container with secrets injected - └─ 7. Return { tenant_id, slug, url, provider, model } -``` +## Provisioning Flow -### Request Routing +When OCTW provisions a tenant, it performs: -``` -User request: https://octw.example.com/acme/chat - │ - ▼ -octw-edge - ├─ Extract slug "acme" from path - ├─ Authenticate (JWT Bearer or session cookie) - ├─ Resolve slug → tenant_id → container IP - │ └─ If stopped/paused: call ensure-running, wait for container - ├─ Proxy to http://:18789/chat - └─ Return response -``` +1. create tenant rows and ownership membership +2. create tenant directories and a dedicated Docker network +3. connect `octw-edge` to that tenant network +4. run non-interactive OpenClaw onboarding +5. rewrite `openclaw.json` for trusted-proxy auth and explicit allowed origins +6. start the tenant container +7. verify the tenant by checking config presence, gateway health, and a WebSocket handshake -## Isolation Model +Only after step 7 does OCTW report the tenant as ready. -Each tenant container runs with: +## Request Routing -- **Dedicated Docker network** — per-tenant bridge network, `internal=true`. No inter-tenant connectivity. -- **Dedicated volumes** — separate state and workspace directories at `/var/lib/octw/tenants//`, permissions `0700`. -- **Non-root execution** — UID 1000:1000, all Linux capabilities dropped, `no-new-privileges`. -- **Resource limits** — configurable memory (default 1.5 GB), CPU quota, PID limit (512). -- **No host port publishing** — tenant containers are not reachable from the host network; only octw-edge connects. -- **Optional hardened runtime** — gVisor (`runsc`) per tenant via `isolation_mode: hardened`. +### Browser app -## Idle Hibernation +- `/app` and `/api/v1/app/*` terminate at `octw-api` +- `/oauth2/*` terminates at `octw-oidc` +- `/t/{slug}/ws` terminates at `octw-edge` -To conserve host resources when running many tenants: +### Legacy tenant path -| Trigger | Action | Effect | -|---|---|---| -| 30 min idle | Pause container | Memory retained, CPU released | -| 8 hours idle | Stop container | Memory and CPU fully reclaimed | -| First request after stop/pause | Wake-on-request | Edge proxy triggers ensure-running, waits, then proxies | +- `https://octw.example.com//...` still proxies through `octw-edge` +- this remains useful for compatibility and debugging +- the preferred v1 UX is `/app` and `/app/chat` + +## Isolation Model + +Each tenant still gets: + +- a dedicated Docker bridge network +- its own state and workspace directories +- no public host ports +- non-root execution with dropped capabilities +- independent runtime lifecycle and idle hibernation + +`octw-edge` is the only shared service attached to tenant networks. -Activity is defined as HTTP/WS traffic through octw-edge to the tenant. +## Persistent State -## Database Schema +Important persisted records now include: -Key tables: +- tenant owner membership +- provider selection +- verification status +- verification error message +- verification timestamp -- **tenants** — id, slug, name, plan, status, provider, resource_limits, container_id, network_id -- **users** — id, email -- **memberships** — tenant_id, user_id, role (tenant_admin / tenant_user / tenant_viewer) -- **secrets** — tenant_id, name, ciphertext, nonce, algorithm, key_version, target_env_var -- **tenant_deks** — tenant_id, encrypted_dek, dek_nonce, kek_version -- **audit_events** — tenant_id, user_id, action, detail, timestamp -- **image_pins** — image_ref, version, digest, is_default +That state lets OCTW resume a tenant later and distinguish a running container from a verified, usable deployment. diff --git a/docs/architecture.md-1.svg b/docs/architecture.md-1.svg new file mode 100644 index 0000000..a49d9fd --- /dev/null +++ b/docs/architecture.md-1.svg @@ -0,0 +1 @@ +

Browser

octw-proxy
Nginx HTTPS ingress

octw-oidc
oauth2-proxy

octw-api
FastAPI

octw-edge
HTTP + WS proxy

octw-db
PostgreSQL

octw-cache
Redis

Docker API

Tenant gateway A

Tenant gateway B

\ No newline at end of file diff --git a/docs/configuration.md b/docs/configuration.md index ef34e98..67d2826 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,66 +1,93 @@ # Configuration -All settings are controlled via environment variables with the `OCTW_` prefix. +OCTW reads settings from environment variables with the `OCTW_` prefix. Start with [`.env.example`](/Users/magos/dev/kumanday/OCTW/.env.example) and adjust only what you need. -## Core Settings +## Core Control Plane | Variable | Default | Description | |---|---|---| -| `OCTW_DB_URL` | `postgresql+asyncpg://octw:octw@localhost:5432/octw` | Database connection string | +| `OCTW_DB_URL` | `postgresql+asyncpg://octw:octw@localhost:5432/octw` | PostgreSQL connection string | | `OCTW_REDIS_URL` | `redis://localhost:6379/0` | Redis connection string | -| `OCTW_JWT_SECRET` | `CHANGE-ME-IN-PRODUCTION` | JWT signing secret (use a strong random value) | -| `OCTW_JWT_ALGORITHM` | `HS256` | JWT algorithm | -| `OCTW_JWT_EXPIRE_MINUTES` | `60` | JWT token expiry | -| `OCTW_LOG_LEVEL` | `INFO` | Log level | +| `OCTW_LOG_LEVEL` | `INFO` | API and edge log level | +| `OCTW_PUBLIC_BASE_URL` | `https://octw.example.com` | Public HTTPS origin used by the browser app and Control UI origin checks | +| `OCTW_EDGE_DOMAIN` | `octw.example.com` | Hostname used when building legacy tenant URLs | +| `OCTW_EDGE_LISTEN_HOST` | `0.0.0.0` | Bind host for the standalone edge server | +| `OCTW_EDGE_LISTEN_PORT` | `8443` | Bind port for the standalone edge server | +| `OCTW_API_INTERNAL_BASE_URL` | `http://octw-api:8000` | Internal API base URL used by `octw-edge` | +| `OCTW_EDGE_CONTAINER_NAME` | `octw-edge` | Docker container name trusted by tenant networks | -## Encryption +## Secrets and Session Signing | Variable | Default | Description | |---|---|---| -| `OCTW_KEK` | — | Master encryption key as hex string (32 bytes = 64 hex chars) | -| `OCTW_KEK_PATH` | `/etc/octw/master.key` | Path to 32-byte KEK file (used if `OCTW_KEK` is not set) | +| `OCTW_KEK` | none | Hex-encoded 32-byte master key for envelope encryption | +| `OCTW_KEK_PATH` | `/etc/octw/master.key` | Fallback path for the KEK if `OCTW_KEK` is unset | +| `OCTW_JWT_SECRET` | `CHANGE-ME-IN-PRODUCTION` | Signing key for API bearer tokens and the `octw_session` cookie | +| `OCTW_JWT_ALGORITHM` | `HS256` | JWT algorithm | +| `OCTW_JWT_EXPIRE_MINUTES` | `60` | Expiry for OCTW bearer tokens and `octw_session` | -The KEK encrypts per-tenant Data Encryption Keys (DEKs), which in turn encrypt individual secret values. See [security.md](security.md) for details. +## Shared Provider API Keys -## Provider API Keys +At least one provider key must be present for one-click provisioning. | Variable | Provider | Model | |---|---|---| -| `OCTW_ZAI_API_KEY` | Z.ai GLM Coding Plan | `zai-coding/glm-5` | -| `OCTW_MOONSHOT_API_KEY` | Moonshot AI Kimi Coding Plan | `kimi-coding/k2p5` | -| `OCTW_MINIMAX_API_KEY` | MiniMax Coding Plan | `minimax-coding/MiniMax-M2.5` | +| `OCTW_ZAI_API_KEY` | Z.ai | `zai/glm-5` | +| `OCTW_MOONSHOT_API_KEY` | Moonshot AI | `kimi-coding/k2p5` | +| `OCTW_MINIMAX_API_KEY` | MiniMax | `minimax-coding/MiniMax-M2.5` | +| `OCTW_DEFAULT_PROVIDER` | `zai` | Provider key used by `/api/v1/app/deploy-or-resume` | -At least one provider key is required for provisioning. See [providers.md](providers.md) for details. - -## OpenClaw Image +## OpenClaw Runtime | Variable | Default | Description | |---|---|---| -| `OCTW_OPENCLAW_IMAGE` | `ghcr.io/openclaw/openclaw:latest` | OpenClaw container image | -| `OCTW_OPENCLAW_DIGEST` | — | Pin image by digest (recommended for production) | +| `OCTW_OPENCLAW_IMAGE` | `ghcr.io/openclaw/openclaw:latest` | OpenClaw image used for tenants | +| `OCTW_OPENCLAW_DIGEST` | none | Optional image digest pin | +| `OCTW_WEBCHAT_PORT` | `18790` | WebChat port enabled during onboarding | +| `OCTW_TENANT_BASE_DIR` | `/var/lib/octw/tenants` | Base directory for tenant state and workspace data | -## Networking +## Resource Limits and Idle Control | Variable | Default | Description | |---|---|---| -| `OCTW_EDGE_LISTEN_HOST` | `0.0.0.0` | Edge proxy listen address | -| `OCTW_EDGE_LISTEN_PORT` | `8443` | Edge proxy listen port | -| `OCTW_EDGE_DOMAIN` | `octw.example.com` | Domain used for building tenant URLs | -| `OCTW_WEBCHAT_PORT` | `18790` | Port for OpenClaw webchat inside tenant containers | +| `OCTW_DEFAULT_MEM_LIMIT` | `1536m` | Default container memory limit | +| `OCTW_DEFAULT_CPU_QUOTA` | `100000` | Default CPU quota in microseconds | +| `OCTW_DEFAULT_CPU_PERIOD` | `100000` | CPU period in microseconds | +| `OCTW_DEFAULT_PIDS_LIMIT` | `512` | Default PID limit per tenant | +| `OCTW_IDLE_PAUSE_SECONDS` | `1800` | Idle pause threshold | +| `OCTW_IDLE_STOP_SECONDS` | `28800` | Idle stop threshold | -## Tenant Defaults +## Browser Auth and Trusted Proxy + +These settings control the browser-first `/app` flow. | Variable | Default | Description | |---|---|---| -| `OCTW_TENANT_BASE_DIR` | `/var/lib/octw/tenants` | Base directory for tenant state and workspace volumes | -| `OCTW_DEFAULT_MEM_LIMIT` | `1536m` | Default memory limit per tenant container | -| `OCTW_DEFAULT_CPU_QUOTA` | `100000` | CPU quota in microseconds per period | -| `OCTW_DEFAULT_CPU_PERIOD` | `100000` | CPU period in microseconds | -| `OCTW_DEFAULT_PIDS_LIMIT` | `512` | Maximum PIDs per tenant container | +| `OCTW_TRUSTED_PROXY_ENABLED` | `false` | Allow the API to bootstrap browser sessions from a forwarded identity header | +| `OCTW_TRUSTED_PROXY_USER_HEADER` | `X-Forwarded-Email` | Header that carries the authenticated user email from Nginx/oauth2-proxy | +| `OCTW_TRUSTED_PROXY_IPS` | empty | Comma-separated list of IPs or CIDRs allowed to send that header | + +`OCTW_TRUSTED_PROXY_ENABLED` should only be enabled when the API is behind `octw-proxy` or another trusted reverse proxy that injects the configured header. + +## Containerized OIDC Ingress -## Hibernation +`docker-compose.yml` now runs `oauth2-proxy` inside the `octw-oidc` service. The service loads [configs/oauth2-proxy/oauth2-proxy.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/oauth2-proxy.cfg) and accepts provider-specific overrides from the environment. | Variable | Default | Description | |---|---|---| -| `OCTW_IDLE_PAUSE_SECONDS` | `1800` | Pause container after 30 minutes of inactivity | -| `OCTW_IDLE_STOP_SECONDS` | `28800` | Stop container after 8 hours of inactivity | +| `OCTW_SERVER_NAME` | `octw.example.com` | Nginx `server_name` and certificate CN fallback | +| `OCTW_OIDC_CONFIG_FILE` | `oauth2-proxy.cfg` | Config file under `configs/oauth2-proxy/` loaded by `octw-oidc` | +| `OCTW_OIDC_PROVIDER` | `oidc` | `oauth2-proxy` provider, typically `oidc`, `keycloak-oidc`, or `google` | +| `OCTW_OIDC_ISSUER_URL` | empty | Required for generic OIDC and Keycloak providers | +| `OCTW_OIDC_CLIENT_ID` | none | OIDC client ID | +| `OCTW_OIDC_CLIENT_SECRET` | none | OIDC client secret | +| `OCTW_OIDC_COOKIE_SECRET` | none | 16/24/32-byte `oauth2-proxy` cookie secret, raw or base64-encoded | +| `OCTW_OIDC_EMAIL_DOMAINS` | `*` | Allowed email domains passed to `oauth2-proxy` | +| `OCTW_OIDC_WHITELIST_DOMAINS` | empty | Redirect domains allowed by `oauth2-proxy` | + +Provider-specific references: + +- Keycloak: [configs/oauth2-proxy/keycloak.example.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/keycloak.example.cfg) +- Google Workspace: [configs/oauth2-proxy/google-workspace.example.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/google-workspace.example.cfg) + +For Google Group enforcement, mount an Admin SDK service-account JSON at `configs/oauth2-proxy/credentials/google-admin-sdk.json`. diff --git a/docs/deployment.md b/docs/deployment.md index fea9633..e92a91f 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,145 +1,147 @@ # Deployment -## Docker Compose (Recommended) +## Compose Topology -### Prerequisites +The recommended deployment is the provided Docker Compose stack: -- Docker Engine with compose plugin -- At least one LLM provider API key +| Service | Exposure | Role | +|---|---|---| +| `octw-proxy` | public `80/443` | HTTPS termination, `auth_request`, browser routing | +| `octw-oidc` | internal | `oauth2-proxy` for OIDC login/session | +| `octw-api` | `127.0.0.1:8000` | REST API and browser app | +| `octw-edge` | `127.0.0.1:8443` | Tenant HTTP and WebSocket proxy | +| `octw-db` | internal plus `5432` | PostgreSQL metadata store | +| `octw-cache` | internal plus `6379` | Redis sessions and orchestration locks | + +The API and edge stay on localhost for operator access. End users only hit `octw-proxy` over HTTPS. -### Host Setup +## Host Preparation ```bash -# Create directories sudo mkdir -p /var/lib/octw /etc/octw -sudo chown $USER /var/lib/octw - -# Generate master encryption key +sudo chown "$USER" /var/lib/octw sudo python3 -c "import os; open('/etc/octw/master.key','wb').write(os.urandom(32))" -sudo chown $USER /etc/octw/master.key +sudo chown "$USER" /etc/octw/master.key sudo chmod 600 /etc/octw/master.key ``` -### Environment Variables +## Environment Setup ```bash -# Required -export OCTW_KEK=$(python3 -c "print(open('/etc/octw/master.key','rb').read().hex())") -export OCTW_JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))") - -# Provider keys (at least one required) -export OCTW_ZAI_API_KEY="your-key" -export OCTW_MOONSHOT_API_KEY="your-key" -export OCTW_MINIMAX_API_KEY="your-key" +cp .env.example .env ``` -### Launch +Set at least: -```bash -docker compose up -d -``` +- `OCTW_KEK` +- `OCTW_JWT_SECRET` +- `OCTW_PUBLIC_BASE_URL` +- `OCTW_SERVER_NAME` +- `OCTW_TRUSTED_PROXY_ENABLED=true` +- `OCTW_OIDC_CLIENT_ID` +- `OCTW_OIDC_CLIENT_SECRET` +- `OCTW_OIDC_COOKIE_SECRET` +- one provider API key such as `OCTW_ZAI_API_KEY` -### Verify +## OIDC Provider Profiles -```bash -docker compose ps # all 4 services should be Up/Healthy -curl http://localhost:8000/health # {"status":"ok"} -curl http://localhost:8443/health # {"status":"ok","service":"octw-edge"} +### Keycloak + +In `.env`: + +```dotenv +OCTW_OIDC_PROVIDER=keycloak-oidc +OCTW_OIDC_ISSUER_URL=https://keycloak.example.com/realms/octw +OCTW_OIDC_EMAIL_DOMAINS=example.com +OCTW_OIDC_WHITELIST_DOMAINS=.example.com ``` -### Services +Use [configs/oauth2-proxy/keycloak.example.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/keycloak.example.cfg) as the reference for optional Keycloak group or role gates. -| Service | Port | Image | -|---|---|---| -| octw-api | 8000 | Built from Dockerfile | -| octw-edge | 8443 | Built from Dockerfile | -| octw-db | 5432 | postgres:16-alpine | -| octw-cache | 6379 | redis:7-alpine | +### Google Workspace -### Rebuild After Code Changes +In `.env`: -```bash -docker compose up -d --build +```dotenv +OCTW_OIDC_PROVIDER=google +OCTW_OIDC_ISSUER_URL= +OCTW_OIDC_EMAIL_DOMAINS=example.com +OCTW_OIDC_WHITELIST_DOMAINS=.example.com ``` -### View Logs +If you need Google Group enforcement: -```bash -docker compose logs -f octw-api -docker compose logs -f octw-edge -``` +1. Put the Admin SDK service account JSON at `configs/oauth2-proxy/credentials/google-admin-sdk.json` +2. Copy the relevant settings from [configs/oauth2-proxy/google-workspace.example.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/google-workspace.example.cfg) into your active oauth2-proxy config +3. Delegate domain-wide authority and grant the Admin SDK read scopes in Google Workspace -### Reset Everything +## Launch ```bash -docker compose down -v # removes containers and volumes -sudo rm -rf /var/lib/octw/tenants/* # removes tenant data +docker compose up -d --build ``` -## Development Setup - -For running services outside Docker Compose (e.g. for debugging with breakpoints): - -```bash -uv sync +`octw-proxy` will generate an ephemeral self-signed certificate inside the container if `configs/certs/fullchain.pem` and `configs/certs/privkey.pem` are missing. -# Start only infrastructure -docker compose up -d octw-db octw-cache +## Verification -# Run API in one terminal -uv run octw server api +### Container health -# Run edge proxy in another terminal -uv run octw server edge +```bash +docker compose ps +curl http://localhost:8000/health +curl http://localhost:8443/health +curl -k https://localhost/health ``` -Both connect to the same Postgres and Redis instances from Docker Compose. - -## Production Considerations - -### TLS Termination +### Browser flow -The edge proxy (octw-edge) does not terminate TLS itself. In production, place a reverse proxy in front: +Open `https:///app`. -- **nginx** or **Caddy** with automatic ACME certificates -- Cloud load balancer with TLS termination -- Tailscale / WireGuard for private access +The first successful visit should: -### Database +1. redirect through your OIDC provider +2. return to OCTW with a valid `oauth2-proxy` session +3. mint an `octw_session` cookie from the trusted forwarded email header +4. create or resume the single user-owned tenant +5. land on `/app/chat` -The included Postgres is suitable for development. For production: +### Provision verification -- Use a managed Postgres instance (RDS, Cloud SQL, etc.) -- Enable SSL connections -- Set strong passwords -- Configure backups +A successful `POST /api/v1/provision` or `POST /api/v1/app/deploy-or-resume` now implies: -Update `OCTW_DB_URL` to point to your production database. +- `openclaw.json` exists after onboarding +- the tenant container started +- the gateway health check succeeded +- a server-side WebSocket handshake to the tenant gateway succeeded -### Secrets +If verification fails, OCTW stores the failure and returns an error instead of pretending the tenant is ready. -- Use a strong, unique `OCTW_JWT_SECRET` (at least 32 bytes) -- Protect `/etc/octw/master.key` with file permissions (`chmod 600`) -- Consider backing the KEK with cloud KMS for production -- Rotate the JWT secret periodically +## Logs -### Resource Limits +```bash +docker compose logs -f octw-proxy +docker compose logs -f octw-oidc +docker compose logs -f octw-api +docker compose logs -f octw-edge +``` -Default tenant limits (1.5 GB RAM, 1 vCPU, 512 PIDs) are suitable for development. Adjust per deployment: +## Rebuild After Code Changes ```bash -export OCTW_DEFAULT_MEM_LIMIT=2g -export OCTW_DEFAULT_PIDS_LIMIT=1024 +docker compose up -d --build ``` -### Monitoring +## Reset -Prometheus metrics are available at `http://localhost:8000/metrics`. Key metrics: +```bash +docker compose down -v +sudo rm -rf /var/lib/octw/tenants/* +``` -- `octw_tenant_container_starts_total` -- `octw_tenant_wake_events_total` -- `octw_active_tenants` -- `octw_proxy_request_duration_seconds` -- `octw_auth_failures_total` +## Production Notes -A Prometheus scrape config is provided at `configs/prometheus.yml`. +- Mount a real certificate at `configs/certs/fullchain.pem` and `configs/certs/privkey.pem` before exposing the stack broadly. +- Keep `octw-api` and `octw-edge` bound to localhost. The public entrypoint should stay `octw-proxy` only. +- The default Postgres and Redis containers are adequate for development and small-scale testing. For production, move them to managed services and update `OCTW_DB_URL` and `OCTW_REDIS_URL`. +- Pin `OCTW_OPENCLAW_DIGEST` if you need deterministic tenant image rollouts. diff --git a/docs/providers.md b/docs/providers.md index 287b1f8..4077273 100644 --- a/docs/providers.md +++ b/docs/providers.md @@ -6,7 +6,7 @@ OCTW supports multiple LLM providers. Provider API keys are configured once on t | Key | Display Name | Model ID | Env Var | |---|---|---|---| -| `zai` | Z.ai GLM Coding Plan | `zai-coding/glm-5` | `OCTW_ZAI_API_KEY` | +| `zai` | Z.ai GLM Coding Plan | `zai/glm-5` | `OCTW_ZAI_API_KEY` | | `moonshot` | Moonshot AI Kimi Coding Plan | `kimi-coding/k2p5` | `OCTW_MOONSHOT_API_KEY` | | `minimax` | MiniMax Coding Plan | `minimax-coding/MiniMax-M2.5` | `OCTW_MINIMAX_API_KEY` | @@ -34,7 +34,7 @@ Response: { "key": "zai", "display_name": "Z.ai GLM Coding Plan", - "model": "zai-coding/glm-5", + "model": "zai/glm-5", "configured": true }, { @@ -57,7 +57,7 @@ Response: When a tenant is provisioned with a provider: 1. **Init job** — the provider's API key is injected as an env var (e.g. `ZAI_API_KEY`) and `OPENCLAW_DEFAULT_MODEL` is set to the model ID. -2. **OpenClaw config** — `openclaw.json` is patched to set `models.default` to the model ID and configure the provider with a SecretRef (`{"$ref": "env:ZAI_API_KEY"}`), avoiding plaintext keys in config files. +2. **OpenClaw config** — `openclaw.json` is patched to set `env.ZAI_API_KEY` to `"${ZAI_API_KEY}"`, set the default model to the chosen model ID, and register the Z.ai provider against `https://api.z.ai/api/coding/paas/v4` using the OpenAI-compatible completions API. 3. **Runtime** — the container is started with the provider's API key injected as an env var. This happens on every start, including wake-on-request after hibernation. The provider choice is stored on the tenant row, so it persists across restarts. diff --git a/docs/security.md b/docs/security.md index 13f9f7d..61ec4fa 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,111 +1,84 @@ # Security -## Threat Model +## Trust Boundaries -OCTW assumes tenants are mutually untrusted. Tenants may be adversarial through prompt injection, may install compromised skills or MCP servers, and should never be able to access another tenant's data or network. +OCTW now has three distinct auth boundaries: -### Primary Threats +1. `octw-proxy` plus `octw-oidc` authenticate the browser user with OIDC +2. `octw-api` trusts the forwarded user header only from configured proxy IPs and converts it into the local `octw_session` cookie +3. each tenant OpenClaw gateway trusts only `octw-edge` via OpenClaw `trusted-proxy` mode -| Threat | Mitigation | -|---|---| -| Cross-tenant data access | Per-tenant volumes with `0700` permissions, separate Docker networks | -| Cross-tenant network movement | Dedicated bridge network per tenant (`internal=true`), no inter-tenant connectivity | -| Host compromise via container breakout | Non-root execution, all capabilities dropped, `no-new-privileges`, optional gVisor | -| Secret leakage to disk | AES-256-GCM encryption at rest, env var injection at runtime, SecretRef in OpenClaw config | -| Ingress auth bypass | JWT validation at edge proxy, forwarded header sanitization | +That split avoids device pairing, Tailscale login, and dangerous gateway auth bypasses for end users. -## Secret Strategy +## Public Ingress -### Envelope Encryption +Public browser traffic terminates at `octw-proxy` over HTTPS. -``` -Master KEK (file at /etc/octw/master.key or OCTW_KEK env var) - │ - └─► encrypts per-tenant DEK (stored in DB as ciphertext) - │ - └─► encrypts each secret value (AES-256-GCM, unique nonce per value) -``` +- `octw-proxy` uses Nginx `auth_request` against `octw-oidc` +- `octw-oidc` stores its own login session in a secure cookie +- Nginx forwards the authenticated email as `X-Forwarded-Email` to OCTW app endpoints +- `octw-api` accepts that header only when `OCTW_TRUSTED_PROXY_ENABLED=true` and the caller IP matches `OCTW_TRUSTED_PROXY_IPS` -- **KEK** — 32-byte AES key, stored outside the database (file or env var). Single point of trust. -- **DEK** — one random 32-byte key per tenant, encrypted by KEK and stored in `tenant_deks` table. -- **Secret values** — encrypted by the tenant's DEK using AES-256-GCM with a unique 12-byte nonce. +The browser never receives raw tenant credentials and never connects directly to tenant container IPs. -### Runtime Secret Delivery +## OCTW Browser Session -1. Secrets are decrypted **only** when starting or waking a tenant container. -2. Decrypted values are injected as **environment variables** into the container process. -3. Secrets are **never written** to the tenant's state volume or config files by OCTW. -4. OpenClaw config uses **SecretRef** (`{"$ref": "env:ZAI_API_KEY"}`) to reference env vars without embedding values. +After a successful OIDC-authenticated request, `octw-api` creates `octw_session`: -### Secret Categories +- signed with `OCTW_JWT_SECRET` +- `HttpOnly` +- `SameSite=Lax` +- `Secure` when `OCTW_PUBLIC_BASE_URL` is HTTPS -| Category | Example | Storage | -|---|---|---| -| Provider API keys (shared) | `ZAI_API_KEY` | Server config (`OCTW_ZAI_API_KEY`), injected at runtime | -| Per-tenant secrets | Channel tokens, custom keys | Encrypted in DB, injected at runtime | -| Platform secrets | JWT secret, DB password | Server environment only | -| Infrastructure secrets | KEK, TLS keys | File or env, never in DB | +`octw-edge` uses that cookie for both HTTP proxying and the `/t/{slug}/ws` WebSocket path. -## Container Hardening +## Tenant Gateway Auth -Every tenant container runs with: +When OCTW configures a tenant, it rewrites the OpenClaw gateway auth section to: -```yaml -user: "1000:1000" -cap_drop: ["ALL"] -security_opt: ["no-new-privileges:true"] -pids_limit: 512 -mem_limit: "1536m" -cpu_quota: 100000 -``` +- `gateway.auth.mode = "trusted-proxy"` +- `gateway.auth.trustedProxy.userHeader = "x-octw-user-email"` +- `gateway.trustedProxies = []` +- `gateway.controlUi.allowedOrigins = [OCTW_PUBLIC_BASE_URL]` -Additionally: -- No Docker socket mount -- No host port publishing -- No privileged mode -- Restart policy: `unless-stopped` -- Health check: `curl -sf http://localhost:18789/health` every 30s +OCTW also removes dangerous fallback controls such as insecure auth and device-auth disable flags. -### Isolation Modes +## Edge Proxy Controls -| Mode | Runtime | Description | -|---|---|---| -| `standard` | Default Docker (runc) | seccomp + AppArmor profiles | -| `hardened` | gVisor (runsc) | User-space kernel, stronger syscall isolation | +`octw-edge` now enforces all of the following before proxying to a tenant: -Set per tenant at creation: `"isolation_mode": "hardened"`. +- validates the OCTW bearer token or `octw_session` cookie +- checks tenant membership via the internal API +- wakes paused or stopped tenants on demand +- strips user-supplied forwarded identity headers and injects its own `x-octw-user-id` and `x-octw-user-email` +- proxies both HTTP and WebSocket traffic over private Docker networks only -## Network Isolation +## Secret Handling -- Each tenant gets a dedicated Docker bridge network (`octw_tenant_`). -- Networks are created with `internal=true` — no outbound internet access by default. -- Only the edge proxy (octw-edge) is connected to tenant networks. -- Tenant containers never join the default bridge network. -- No ports are published to the host. +Secrets still use envelope encryption: -## Authentication and Authorization +- KEK from `OCTW_KEK` or `OCTW_KEK_PATH` +- one DEK per tenant in the database +- AES-256-GCM for stored ciphertext +- runtime injection into container environment variables only -### Edge Proxy (octw-edge) +Provider API keys remain host-level shared secrets. Per-tenant secrets remain encrypted in the database and are never returned by the API. -- Authenticates every request via JWT Bearer token or `octw_session` cookie. -- Sanitizes forwarded headers (`X-Forwarded-For` is overwritten with client IP). -- Injects `x-octw-tenant-slug`, `x-octw-user-id`, `x-octw-user-email` headers. +## Container Isolation -### API (octw-api) +Each tenant still gets: -- JWT-based auth on all endpoints (except `/auth/login` and `/auth/verify`). -- RBAC: every tenant operation checks membership and role. -- Roles: `tenant_admin` > `tenant_user` > `tenant_viewer`. +- a dedicated Docker bridge network +- dedicated tenant directories under `/var/lib/octw/tenants//` +- no published host ports +- non-root execution and dropped Linux capabilities +- resource limits and idle pause/stop enforcement -## Audit Logging +`octw-edge` is the only control-plane container attached to tenant networks. -All sensitive actions emit audit events stored in the `audit_events` table: +## Operational Guidance -- Tenant create / delete -- Secret set / rotate / delete -- Container start / stop / pause / wake -- Member add / remove -- Route mapping changes -- Backup / restore - -Each event includes `tenant_id`, `user_id`, action type, and detail metadata. +- Keep `octw-api` and `octw-edge` on localhost-only bindings. +- Use a real TLS certificate in `configs/certs/` for production. +- Do not enable OpenClaw insecure auth fallbacks to make browser login easier. The trusted-proxy path replaces that need. +- If you use Google Group checks in `oauth2-proxy`, treat the Admin SDK service-account JSON under `configs/oauth2-proxy/credentials/` as a production secret. diff --git a/pyproject.toml b/pyproject.toml index 7c031c4..d50a70a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,6 +17,7 @@ dependencies = [ "pyjwt[crypto]>=2.10.0", "cryptography>=44.0.0", "httpx>=0.28.0", + "websockets>=16.0", "python-multipart>=0.0.18", "structlog>=24.4.0", "prometheus-client>=0.21.0", diff --git a/src/octw/api/app.py b/src/octw/api/app.py index f156bbb..60b759e 100644 --- a/src/octw/api/app.py +++ b/src/octw/api/app.py @@ -1,11 +1,15 @@ from __future__ import annotations from contextlib import asynccontextmanager +from pathlib import Path from fastapi import FastAPI +from fastapi.responses import FileResponse +from fastapi.staticfiles import StaticFiles from prometheus_client import make_asgi_app from octw.api.routers import ( + app_router, auth_router, internal_router, provision_router, @@ -13,14 +17,14 @@ secrets_router, tenants_router, ) -from octw.db.engine import engine -from octw.db.tables import Base +from octw.db.engine import engine, ensure_schema + +WEB_ROOT = Path(__file__).resolve().parent.parent / "web" / "static" @asynccontextmanager async def lifespan(app: FastAPI): - async with engine.begin() as conn: - await conn.run_sync(Base.metadata.create_all) + await ensure_schema(engine) yield await engine.dispose() @@ -32,12 +36,22 @@ async def lifespan(app: FastAPI): app.include_router(secrets_router.router, prefix="/api/v1") app.include_router(runtime_router.router, prefix="/api/v1") app.include_router(provision_router.router, prefix="/api/v1") +app.include_router(app_router.router) app.include_router(internal_router.router) +app.mount("/app/static", StaticFiles(directory=WEB_ROOT), name="app-static") + metrics_app = make_asgi_app() app.mount("/metrics", metrics_app) +@app.get("/app") +@app.get("/app/") +@app.get("/app/chat") +async def app_shell(): + return FileResponse(WEB_ROOT / "index.html") + + @app.get("/health") async def health(): return {"status": "ok"} diff --git a/src/octw/api/app_logic.py b/src/octw/api/app_logic.py new file mode 100644 index 0000000..ee92162 --- /dev/null +++ b/src/octw/api/app_logic.py @@ -0,0 +1,128 @@ +from __future__ import annotations + +import re +import uuid +from dataclasses import dataclass + +from sqlalchemy import update +from sqlalchemy.ext.asyncio import AsyncSession + +from octw.api.auth import TokenPayload +from octw.common.config import settings +from octw.common.logging import get_logger +from octw.db.tables import TenantRow +from octw.models.provider import get_provider +from octw.models.tenant import TenantCreate, TenantPlan +from octw.orchestrator.docker_orch import DockerOrchestrator +from octw.orchestrator.tenant_service import TenantService +from octw.vault.service import VaultService + +log = get_logger(__name__) + +_SLUG_SAFE = re.compile(r"[^a-z0-9]+") + + +@dataclass(slots=True) +class ProvisionedTenant: + tenant_id: str + slug: str + status: str + provider: str + model: str + url: str + verification_status: str + verification_error: str | None + + +def build_user_tenant_slug(user_id: uuid.UUID) -> str: + return f"u-{user_id.hex[:20]}" + + +def build_user_tenant_name(email: str) -> str: + local = email.split("@", 1)[0].strip().lower() or "user" + safe = _SLUG_SAFE.sub(" ", local).strip() + label = safe.title() if safe else "User" + return f"{label} Workspace" + + +def tenant_chat_url(slug: str) -> str: + return f"{settings.public_base_url.rstrip('/')}/app/chat" + + +async def provision_tenant( + *, + session: AsyncSession, + svc: TenantService, + orch: DockerOrchestrator, + vault_svc: VaultService, + user: TokenPayload, + slug: str, + name: str, + provider_key: str, + secrets: dict[str, str] | None = None, +) -> ProvisionedTenant: + provider_spec = get_provider(provider_key) + api_key = settings.get_provider_api_key(provider_spec.env_var) + if not api_key: + raise RuntimeError( + "Provider " + f"'{provider_spec.display_name}' is not configured. " + f"Set OCTW_{provider_spec.env_var}." + ) + + existing = await svc.get_tenant_by_slug(session, slug) + if existing: + raise RuntimeError(f"Tenant with slug '{slug}' already exists") + + tenant_req = TenantCreate( + slug=slug, + name=name, + plan=TenantPlan.STANDARD, + trusted_proxy_auth=True, + ) + tenant = await svc.create_tenant(session, tenant_req, creator_user_id=user.user_id) + await session.flush() + + await session.execute( + update(TenantRow) + .where(TenantRow.tenant_id == tenant.tenant_id) + .values(provider=provider_spec.key.value) + ) + await session.flush() + + if secrets: + for secret_name, secret_value in secrets.items(): + await vault_svc.store_secret( + session, tenant.tenant_id, secret_name, secret_value, + target_env_var=secret_name, + ) + await session.flush() + + env_secrets = await vault_svc.get_decrypted_secrets(session, tenant.tenant_id) + orch.run_init_job( + tenant, + provider_env_var=provider_spec.env_var, + provider_model=provider_spec.model_id, + env_secrets=env_secrets, + ) + + orch.configure_tenant(tenant.tenant_id, provider_spec=provider_spec) + await svc.start_tenant(session, tenant.tenant_id) + try: + verified = await svc.verify_tenant(session, tenant.tenant_id) + except Exception as exc: + await svc.mark_verification_failed(session, tenant.tenant_id, str(exc)) + log.error("tenant_verification_failed", tenant_id=str(tenant.tenant_id), error=str(exc)) + raise + + await session.commit() + return ProvisionedTenant( + tenant_id=str(verified.tenant_id), + slug=verified.slug, + status=verified.status.value, + provider=provider_spec.key.value, + model=provider_spec.model_id, + url=f"https://{settings.edge_domain.rstrip('/')}/{verified.slug}/", + verification_status=verified.verification_status.value, + verification_error=verified.verification_error, + ) diff --git a/src/octw/api/auth.py b/src/octw/api/auth.py index ffb7ac8..75f52cc 100644 --- a/src/octw/api/auth.py +++ b/src/octw/api/auth.py @@ -1,10 +1,12 @@ from __future__ import annotations +import ipaddress import uuid from datetime import datetime, timedelta +from typing import Any import jwt -from fastapi import Depends, HTTPException +from fastapi import Depends, HTTPException, Request, Response from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer from sqlalchemy import select from sqlalchemy.ext.asyncio import AsyncSession @@ -13,6 +15,7 @@ from octw.db.tables import UserRow security = HTTPBearer(auto_error=False) +SESSION_COOKIE_NAME = "octw_session" class TokenPayload: @@ -29,7 +32,7 @@ def create_access_token( expires_minutes: int | None = None, ) -> str: exp = datetime.utcnow() + timedelta(minutes=expires_minutes or settings.jwt_expire_minutes) - payload: dict = { + payload: dict[str, Any] = { "sub": str(user_id), "email": email, "exp": exp, @@ -48,12 +51,76 @@ def decode_token(token: str) -> TokenPayload: return TokenPayload(user_id=uuid.UUID(data["sub"]), email=data["email"], tid=tid) +def _extract_cookie_token(request: Request) -> str | None: + token = request.cookies.get(SESSION_COOKIE_NAME) + return token.strip() if token else None + + +def _client_host(request: Request) -> str: + if request.client and request.client.host: + return request.client.host + return "" + + +def _ip_in_networks(host: str, configured: list[str]) -> bool: + if not host: + return False + try: + addr = ipaddress.ip_address(host) + except ValueError: + return False + for raw in configured: + try: + network = ipaddress.ip_network(raw, strict=False) + except ValueError: + continue + if addr in network: + return True + return False + + +def get_trusted_proxy_email(request: Request) -> str | None: + if not settings.trusted_proxy_enabled: + return None + host = _client_host(request) + if settings.trusted_proxy_ips and not _ip_in_networks(host, settings.trusted_proxy_ips): + return None + header = settings.trusted_proxy_user_header + email = request.headers.get(header, "").strip() + return email or None + + async def get_current_user( + request: Request, credentials: HTTPAuthorizationCredentials | None = Depends(security), ) -> TokenPayload: - if not credentials: + token: str | None = None + if credentials: + token = credentials.credentials + if not token: + token = _extract_cookie_token(request) + if not token: + raise HTTPException(status_code=401, detail="Not authenticated") + return decode_token(token) + + +async def get_browser_user( + request: Request, + session: AsyncSession, +) -> tuple[TokenPayload, bool]: + token = _extract_cookie_token(request) + if token: + payload = decode_token(token) + row = await session.get(UserRow, payload.user_id) + if row: + return TokenPayload(row.user_id, row.email, payload.tid), False + + forwarded_email = get_trusted_proxy_email(request) + if not forwarded_email: raise HTTPException(status_code=401, detail="Not authenticated") - return decode_token(credentials.credentials) + + user = await get_or_create_user(session, forwarded_email) + return TokenPayload(user.user_id, user.email), True async def get_or_create_user( @@ -68,3 +135,15 @@ async def get_or_create_user( session.add(row) await session.flush() return row + + +def set_session_cookie(response: Response, token: str) -> None: + response.set_cookie( + key=SESSION_COOKIE_NAME, + value=token, + httponly=True, + secure=settings.public_base_url.startswith("https://"), + samesite="lax", + path="/", + max_age=settings.jwt_expire_minutes * 60, + ) diff --git a/src/octw/api/routers/app_router.py b/src/octw/api/routers/app_router.py new file mode 100644 index 0000000..fad80c2 --- /dev/null +++ b/src/octw/api/routers/app_router.py @@ -0,0 +1,142 @@ +from __future__ import annotations + +from fastapi import APIRouter, Depends, HTTPException, Request, Response +from pydantic import BaseModel +from sqlalchemy.ext.asyncio import AsyncSession + +from octw.api.app_logic import ( + build_user_tenant_name, + build_user_tenant_slug, + provision_tenant, + tenant_chat_url, +) +from octw.api.auth import create_access_token, get_browser_user, set_session_cookie +from octw.api.deps import get_orchestrator, get_tenant_service, get_vault_service +from octw.common.config import settings +from octw.db.engine import get_session +from octw.models.tenant import VerificationStatus +from octw.orchestrator.docker_orch import DockerOrchestrator +from octw.orchestrator.tenant_service import TenantService +from octw.vault.service import VaultService + +router = APIRouter(prefix="/api/v1/app", tags=["app"]) + + +class AppTenantInfo(BaseModel): + tenant_id: str + slug: str + status: str + verification_status: str + verification_error: str | None = None + chat_url: str + + +class AppSessionResponse(BaseModel): + user_id: str + email: str + tenant: AppTenantInfo | None = None + + +class DeployOrResumeResponse(BaseModel): + created: bool + tenant: AppTenantInfo + + +async def _browser_auth( + request: Request, + response: Response, + session: AsyncSession, +): + user, issued = await get_browser_user(request, session) + if issued: + await session.commit() + set_session_cookie(response, create_access_token(user.user_id, user.email)) + return user + + +async def _tenant_info(session: AsyncSession, svc: TenantService, user_id): + tenant = await svc.get_owner_tenant(session, user_id) + if not tenant: + return None + return AppTenantInfo( + tenant_id=str(tenant.tenant_id), + slug=tenant.slug, + status=tenant.status.value, + verification_status=tenant.verification_status.value, + verification_error=tenant.verification_error, + chat_url=tenant_chat_url(tenant.slug), + ) + + +@router.get("/session", response_model=AppSessionResponse) +async def get_app_session( + request: Request, + response: Response, + session: AsyncSession = Depends(get_session), + svc: TenantService = Depends(get_tenant_service), +): + user = await _browser_auth(request, response, session) + tenant = await _tenant_info(session, svc, user.user_id) + return AppSessionResponse(user_id=str(user.user_id), email=user.email, tenant=tenant) + + +@router.post("/deploy-or-resume", response_model=DeployOrResumeResponse) +async def deploy_or_resume( + request: Request, + response: Response, + session: AsyncSession = Depends(get_session), + svc: TenantService = Depends(get_tenant_service), + orch: DockerOrchestrator = Depends(get_orchestrator), + vault_svc: VaultService = Depends(get_vault_service), +): + user = await _browser_auth(request, response, session) + tenant = await svc.get_owner_tenant(session, user.user_id) + created = False + + if tenant is None: + try: + provisioned = await provision_tenant( + session=session, + svc=svc, + orch=orch, + vault_svc=vault_svc, + user=user, + slug=build_user_tenant_slug(user.user_id), + name=build_user_tenant_name(user.email), + provider_key=settings.default_provider, + ) + except Exception as exc: + await session.rollback() + raise HTTPException(status_code=500, detail=str(exc)) from exc + created = True + tenant_info = AppTenantInfo( + tenant_id=provisioned.tenant_id, + slug=provisioned.slug, + status=provisioned.status, + verification_status=provisioned.verification_status, + verification_error=provisioned.verification_error, + chat_url=tenant_chat_url(provisioned.slug), + ) + return DeployOrResumeResponse(created=created, tenant=tenant_info) + + try: + await svc.wake_tenant(session, tenant.tenant_id) + if tenant.verification_status != VerificationStatus.VERIFIED: + await svc.verify_tenant(session, tenant.tenant_id) + await session.commit() + except Exception as exc: + await session.rollback() + raise HTTPException(status_code=500, detail=str(exc)) from exc + + refreshed = await svc.get_tenant(session, tenant.tenant_id) + if not refreshed: + raise HTTPException(status_code=404, detail="Tenant disappeared") + tenant_info = AppTenantInfo( + tenant_id=str(refreshed.tenant_id), + slug=refreshed.slug, + status=refreshed.status.value, + verification_status=refreshed.verification_status.value, + verification_error=refreshed.verification_error, + chat_url=tenant_chat_url(refreshed.slug), + ) + return DeployOrResumeResponse(created=created, tenant=tenant_info) diff --git a/src/octw/api/routers/auth_router.py b/src/octw/api/routers/auth_router.py index 1fd525b..8889af5 100644 --- a/src/octw/api/routers/auth_router.py +++ b/src/octw/api/routers/auth_router.py @@ -3,11 +3,11 @@ import secrets from datetime import datetime, timedelta -from fastapi import APIRouter, Depends, HTTPException +from fastapi import APIRouter, Depends, HTTPException, Response from pydantic import BaseModel from sqlalchemy.ext.asyncio import AsyncSession -from octw.api.auth import create_access_token, get_or_create_user +from octw.api.auth import create_access_token, get_or_create_user, set_session_cookie from octw.db.engine import get_session router = APIRouter(prefix="/auth", tags=["auth"]) @@ -42,7 +42,11 @@ async def login(req: LoginRequest, session: AsyncSession = Depends(get_session)) @router.post("/verify") -async def verify(req: VerifyRequest, session: AsyncSession = Depends(get_session)): +async def verify( + req: VerifyRequest, + response: Response, + session: AsyncSession = Depends(get_session), +): pending = _pending_tokens.pop(req.token, None) if not pending or pending["expires"] < datetime.utcnow(): raise HTTPException(status_code=401, detail="Invalid or expired token") @@ -50,6 +54,7 @@ async def verify(req: VerifyRequest, session: AsyncSession = Depends(get_session user = await get_or_create_user(session, pending["email"]) await session.commit() access_token = create_access_token(user.user_id, user.email) + set_session_cookie(response, access_token) return SessionResponse( access_token=access_token, user_id=str(user.user_id), diff --git a/src/octw/api/routers/internal_router.py b/src/octw/api/routers/internal_router.py index cca8f2a..1d7017d 100644 --- a/src/octw/api/routers/internal_router.py +++ b/src/octw/api/routers/internal_router.py @@ -19,7 +19,6 @@ async def _resolve_tenant_id( session: AsyncSession, svc: TenantService, ) -> uuid.UUID: - """Resolve a tenant identifier that may be a UUID or a slug.""" try: return uuid.UUID(identifier) except ValueError: @@ -42,6 +41,20 @@ async def ensure_running( return {"status": "running", "containerId": container_id} +@router.get("/{identifier}/access/{user_id}") +async def check_access( + identifier: str, + user_id: uuid.UUID, + session: AsyncSession = Depends(get_session), + svc: TenantService = Depends(get_tenant_service), +): + tenant_id = await _resolve_tenant_id(identifier, session, svc) + role = await svc.check_membership(session, tenant_id, user_id) + if role is None: + raise HTTPException(status_code=403, detail="Forbidden") + return {"allowed": True, "role": role.value, "tenant_id": str(tenant_id)} + + @router.post("/{identifier}/pause-if-idle") async def pause_if_idle( identifier: str, diff --git a/src/octw/api/routers/provision_router.py b/src/octw/api/routers/provision_router.py index 1a5906a..1cede1b 100644 --- a/src/octw/api/routers/provision_router.py +++ b/src/octw/api/routers/provision_router.py @@ -3,17 +3,15 @@ from fastapi import APIRouter, Depends, HTTPException from pydantic import BaseModel, Field -from sqlalchemy import update from sqlalchemy.ext.asyncio import AsyncSession +from octw.api.app_logic import provision_tenant as provision_tenant_impl from octw.api.auth import TokenPayload, get_current_user from octw.api.deps import get_orchestrator, get_tenant_service, get_vault_service from octw.common.config import settings from octw.common.logging import get_logger from octw.db.engine import get_session -from octw.db.tables import TenantRow from octw.models.provider import PROVIDERS, get_provider -from octw.models.tenant import TenantCreate, TenantPlan from octw.orchestrator.docker_orch import DockerOrchestrator from octw.orchestrator.tenant_service import TenantService from octw.vault.service import VaultService @@ -40,6 +38,8 @@ class ProvisionResponse(BaseModel): provider: str model: str url: str + verification_status: str + verification_error: str | None = None @router.get("/providers") @@ -77,10 +77,11 @@ async def provision_tenant( """ # 0. Validate provider try: - provider_spec = get_provider(req.provider) + get_provider(req.provider) except ValueError as e: raise HTTPException(status_code=400, detail=str(e)) from e + provider_spec = get_provider(req.provider) api_key = settings.get_provider_api_key(provider_spec.env_var) if not api_key: raise HTTPException( @@ -91,82 +92,42 @@ async def provision_tenant( ), ) - existing = await svc.get_tenant_by_slug(session, req.slug) - if existing: - raise HTTPException( - status_code=409, - detail=f"Tenant with slug '{req.slug}' already exists", - ) - - # 1. Create tenant - tenant_req = TenantCreate( - slug=req.slug, - name=req.name, - plan=TenantPlan.STANDARD, - trusted_proxy_auth=True, - ) - tenant = await svc.create_tenant(session, tenant_req, creator_user_id=user.user_id) - await session.flush() - - # Store the provider choice on the tenant row - await session.execute( - update(TenantRow) - .where(TenantRow.tenant_id == tenant.tenant_id) - .values(provider=provider_spec.key.value) - ) - await session.flush() - - # 2. Store per-tenant secrets (if any beyond the shared provider key) - if req.secrets: - for secret_name, secret_value in req.secrets.items(): - await vault_svc.store_secret( - session, tenant.tenant_id, secret_name, secret_value, - target_env_var=secret_name, - ) - await session.flush() - - # 3. Run OpenClaw onboarding init job try: - env_secrets = await vault_svc.get_decrypted_secrets(session, tenant.tenant_id) - orch.run_init_job( - tenant, - provider_env_var=provider_spec.env_var, - provider_model=provider_spec.model_id, - env_secrets=env_secrets, + provisioned = await provision_tenant_impl( + session=session, + svc=svc, + orch=orch, + vault_svc=vault_svc, + user=user, + slug=req.slug, + name=req.name, + provider_key=req.provider, + secrets=req.secrets, ) except RuntimeError as e: log.error( "provision_init_failed", - tenant_id=str(tenant.tenant_id), + slug=req.slug, error=str(e), ) raise HTTPException(status_code=500, detail=f"Onboarding failed: {e}") from e - # 4. Configure gateway + model provider in openclaw.json - orch.configure_tenant(tenant.tenant_id, provider_spec=provider_spec) - - # 5. Start the tenant container - await svc.start_tenant(session, tenant.tenant_id) - await session.commit() - - # 6. Build access URL - base_url = settings.edge_domain.rstrip("/") - url = f"https://{base_url}/{req.slug}/" - log.info( "tenant_provisioned", - tenant_id=str(tenant.tenant_id), - slug=req.slug, - provider=provider_spec.key.value, - model=provider_spec.model_id, - url=url, + tenant_id=provisioned.tenant_id, + slug=provisioned.slug, + provider=provisioned.provider, + model=provisioned.model, + url=provisioned.url, ) return ProvisionResponse( - tenant_id=str(tenant.tenant_id), - slug=req.slug, - status="running", - provider=provider_spec.key.value, - model=provider_spec.model_id, - url=url, + tenant_id=provisioned.tenant_id, + slug=provisioned.slug, + status=provisioned.status, + provider=provisioned.provider, + model=provisioned.model, + url=provisioned.url, + verification_status=provisioned.verification_status, + verification_error=provisioned.verification_error, ) diff --git a/src/octw/common/config.py b/src/octw/common/config.py index 6315fe8..c71997c 100644 --- a/src/octw/common/config.py +++ b/src/octw/common/config.py @@ -1,6 +1,9 @@ from __future__ import annotations -from pydantic_settings import BaseSettings +from typing import Annotated + +from pydantic import Field, field_validator +from pydantic_settings import BaseSettings, NoDecode class OCTWSettings(BaseSettings): @@ -16,6 +19,9 @@ class OCTWSettings(BaseSettings): edge_listen_host: str = "0.0.0.0" edge_listen_port: int = 8443 edge_domain: str = "octw.example.com" + edge_container_name: str = "octw-edge" + api_internal_base_url: str = "http://octw-api:8000" + public_base_url: str = "https://octw.example.com" jwt_secret: str = "CHANGE-ME-IN-PRODUCTION" jwt_algorithm: str = "HS256" @@ -27,6 +33,7 @@ class OCTWSettings(BaseSettings): default_cpu_quota: int = 100000 # microseconds per period default_cpu_period: int = 100000 default_pids_limit: int = 512 + default_provider: str = "zai" idle_pause_seconds: int = 1800 # 30 min idle_stop_seconds: int = 28800 # 8 hours @@ -36,11 +43,25 @@ class OCTWSettings(BaseSettings): moonshot_api_key: str | None = None minimax_api_key: str | None = None + # Browser auth via reverse proxy. + trusted_proxy_enabled: bool = False + trusted_proxy_user_header: str = "X-Forwarded-Email" + trusted_proxy_ips: Annotated[list[str], NoDecode] = Field(default_factory=list) + # WebChat is enabled by default during onboarding. webchat_port: int = 18790 log_level: str = "INFO" + @field_validator("trusted_proxy_ips", mode="before") + @classmethod + def _parse_proxy_ips(cls, value): + if value in (None, "", []): + return [] + if isinstance(value, str): + return [item.strip() for item in value.split(",") if item.strip()] + return value + def get_provider_api_key(self, env_var: str) -> str | None: mapping = { "ZAI_API_KEY": self.zai_api_key, diff --git a/src/octw/db/engine.py b/src/octw/db/engine.py index 8f5096d..44362e0 100644 --- a/src/octw/db/engine.py +++ b/src/octw/db/engine.py @@ -1,13 +1,50 @@ from __future__ import annotations -from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine +from sqlalchemy import text +from sqlalchemy.ext.asyncio import ( + AsyncEngine, + AsyncSession, + async_sessionmaker, + create_async_engine, +) from octw.common.config import settings +from octw.db.tables import Base engine = create_async_engine(settings.db_url, echo=False, pool_size=10, max_overflow=20) async_session = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False) +async def ensure_schema(db_engine: AsyncEngine | None = None) -> None: + target = db_engine or engine + async with target.begin() as conn: + await conn.run_sync(Base.metadata.create_all) + dialect = conn.dialect.name + if dialect == "postgresql": + await conn.execute( + text("ALTER TABLE tenants ADD COLUMN IF NOT EXISTS owner_user_id UUID") + ) + await conn.execute( + text( + "ALTER TABLE tenants " + "ADD COLUMN IF NOT EXISTS verification_status " + "VARCHAR(20) DEFAULT 'pending'" + ) + ) + await conn.execute( + text("ALTER TABLE tenants ADD COLUMN IF NOT EXISTS verification_error TEXT") + ) + await conn.execute( + text("ALTER TABLE tenants ADD COLUMN IF NOT EXISTS verified_at TIMESTAMP") + ) + await conn.execute( + text( + "UPDATE tenants SET verification_status = " + "COALESCE(verification_status, 'pending')" + ) + ) + + async def get_session() -> AsyncSession: # type: ignore[misc] async with async_session() as session: yield session # type: ignore[misc] diff --git a/src/octw/db/tables.py b/src/octw/db/tables.py index 9c15778..4b147a4 100644 --- a/src/octw/db/tables.py +++ b/src/octw/db/tables.py @@ -9,6 +9,7 @@ Index, LargeBinary, String, + Text, UniqueConstraint, func, ) @@ -28,8 +29,12 @@ class TenantRow(Base): ) slug: Mapped[str] = mapped_column(String(50), unique=True, nullable=False) name: Mapped[str] = mapped_column(String(200), nullable=False) + owner_user_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) plan: Mapped[str] = mapped_column(String(20), default="standard") status: Mapped[str] = mapped_column(String(20), default="provisioning") + verification_status: Mapped[str] = mapped_column(String(20), default="pending") + verification_error: Mapped[str | None] = mapped_column(Text, nullable=True) + verified_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True) isolation_mode: Mapped[str] = mapped_column(String(20), default="standard") resource_limits: Mapped[dict | None] = mapped_column(JSON, nullable=True) trusted_proxy_auth: Mapped[bool] = mapped_column(default=True) diff --git a/src/octw/edge/proxy.py b/src/octw/edge/proxy.py index ed95391..a9e9308 100644 --- a/src/octw/edge/proxy.py +++ b/src/octw/edge/proxy.py @@ -6,12 +6,17 @@ """ from __future__ import annotations +import asyncio import re +from collections.abc import AsyncIterator import httpx -from fastapi import FastAPI, HTTPException, Request, Response +import websockets +from fastapi import FastAPI, HTTPException, Request, Response, WebSocket, WebSocketDisconnect +from websockets.exceptions import ConnectionClosed from octw.api.auth import TokenPayload, decode_token +from octw.common.config import settings from octw.common.logging import get_logger from octw.orchestrator.docker_orch import OPENCLAW_GATEWAY_PORT @@ -20,10 +25,10 @@ edge_app = FastAPI(title="OCTW Edge Proxy") _http_client: httpx.AsyncClient | None = None -_INTERNAL_API = "http://127.0.0.1:8000" +_INTERNAL_API = settings.api_internal_base_url.rstrip("/") _SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9\-]*[a-z0-9]$") -_RESERVED_PATHS = {"api", "internal", "health", "metrics"} +_RESERVED_PATHS = {"api", "internal", "health", "metrics", "app", "t"} async def _get_client() -> httpx.AsyncClient: @@ -33,7 +38,7 @@ async def _get_client() -> httpx.AsyncClient: return _http_client -def _authenticate(request: Request) -> TokenPayload | None: +def _authenticate_request(request: Request) -> TokenPayload | None: auth = request.headers.get("authorization", "") if auth.startswith("Bearer "): try: @@ -49,17 +54,38 @@ def _authenticate(request: Request) -> TokenPayload | None: return None -async def _resolve_and_ensure(slug: str) -> str: - """Resolve tenant slug to container IP, waking if necessary.""" +def _authenticate_websocket(websocket: WebSocket) -> TokenPayload | None: + auth = websocket.headers.get("authorization", "") + if auth.startswith("Bearer "): + try: + return decode_token(auth[7:]) + except Exception: + pass + cookie_header = websocket.headers.get("cookie", "") + for chunk in cookie_header.split(";"): + name, _, value = chunk.strip().partition("=") + if name == "octw_session" and value: + try: + return decode_token(value) + except Exception: + pass + return None + + +async def _check_access(slug: str, user: TokenPayload) -> None: client = await _get_client() + resp = await client.get(f"{_INTERNAL_API}/internal/v1/tenants/{slug}/access/{user.user_id}") + if resp.status_code == 403: + raise HTTPException(status_code=403, detail="Forbidden") + if resp.status_code != 200: + raise HTTPException(status_code=404, detail=f"Tenant '{slug}' not found") - # Look up tenant by slug to get tenant_id - await client.get(f"{_INTERNAL_API}/api/v1/tenants", params={"slug": slug}) - # Check current status - status_resp = await client.get( - f"{_INTERNAL_API}/internal/v1/tenants/{slug}/status" - ) +async def _resolve_and_ensure(slug: str, user: TokenPayload) -> str: + client = await _get_client() + await _check_access(slug, user) + + status_resp = await client.get(f"{_INTERNAL_API}/internal/v1/tenants/{slug}/status") if status_resp.status_code != 200: raise HTTPException(status_code=404, detail=f"Tenant '{slug}' not found") @@ -71,14 +97,9 @@ async def _resolve_and_ensure(slug: str) -> str: return ip if state in ("paused", "stopped", "not_found"): - ensure = await client.post( - f"{_INTERNAL_API}/internal/v1/tenants/{slug}/ensure-running" - ) + ensure = await client.post(f"{_INTERNAL_API}/internal/v1/tenants/{slug}/ensure-running") if ensure.status_code == 200: - # Re-fetch IP after wake - status_resp = await client.get( - f"{_INTERNAL_API}/internal/v1/tenants/{slug}/status" - ) + status_resp = await client.get(f"{_INTERNAL_API}/internal/v1/tenants/{slug}/status") data = status_resp.json() ip = data.get("ip") if ip: @@ -87,6 +108,108 @@ async def _resolve_and_ensure(slug: str) -> str: raise HTTPException(status_code=503, detail="Tenant is not available") +def _proxy_headers_from_request(request: Request, slug: str, user: TokenPayload) -> dict[str, str]: + headers = dict(request.headers) + headers.pop("host", None) + headers.pop("origin", None) + headers.pop("x-octw-user-email", None) + headers.pop("x-forwarded-for", None) + headers["x-octw-tenant-slug"] = slug + headers["x-octw-user-id"] = str(user.user_id) + headers["x-octw-user-email"] = user.email + headers["x-forwarded-for"] = request.client.host if request.client else "unknown" + headers["x-forwarded-proto"] = "https" + headers["x-forwarded-host"] = request.headers.get("host", settings.edge_domain) + origin = request.headers.get("origin") + if origin: + headers["origin"] = origin + return headers + + +@edge_app.websocket("/t/{slug}/ws") +async def tenant_websocket(slug: str, websocket: WebSocket): + if slug in _RESERVED_PATHS or not _SLUG_RE.match(slug): + await websocket.close(code=4404) + return + + user = _authenticate_websocket(websocket) + if not user: + await websocket.close(code=4401) + return + + try: + ip = await _resolve_and_ensure(slug, user) + except HTTPException as exc: + await websocket.close(code=4403 if exc.status_code == 403 else 4404) + return + + await websocket.accept() + upstream_headers = { + "origin": settings.public_base_url.rstrip("/"), + "x-octw-user-id": str(user.user_id), + "x-octw-user-email": user.email, + "x-forwarded-for": websocket.client.host if websocket.client else "unknown", + "x-forwarded-proto": "https", + "x-forwarded-host": websocket.headers.get("host", settings.edge_domain), + } + upstream_url = f"ws://{ip}:{OPENCLAW_GATEWAY_PORT}" + + try: + async with websockets.connect( + upstream_url, additional_headers=upstream_headers + ) as upstream: + async def client_to_upstream() -> None: + while True: + message = await websocket.receive() + if message.get("type") == "websocket.disconnect": + break + if message.get("text") is not None: + await upstream.send(message["text"]) + elif message.get("bytes") is not None: + await upstream.send(message["bytes"]) + + async def upstream_to_client() -> None: + async for message in _iter_upstream_messages(upstream): + if isinstance(message, bytes): + await websocket.send_bytes(message) + else: + await websocket.send_text(message) + + done, pending = await asyncio.wait( + [ + asyncio.create_task(client_to_upstream()), + asyncio.create_task(upstream_to_client()), + ], + return_when=asyncio.FIRST_COMPLETED, + ) + for task in pending: + task.cancel() + for task in done: + exc = task.exception() + if exc and not isinstance(exc, WebSocketDisconnect): + raise exc + except ConnectionClosed: + pass + except WebSocketDisconnect: + pass + except Exception as exc: + log.warning("tenant_ws_proxy_failed", slug=slug, error=str(exc)) + await websocket.close(code=1011) + + +async def _iter_upstream_messages(upstream) -> AsyncIterator[str | bytes]: + while True: + try: + yield await upstream.recv() + except ConnectionClosed: + break + + +@edge_app.get("/health") +async def health(): + return {"status": "ok", "service": "octw-edge"} + + @edge_app.api_route( "/{slug}/{path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"], @@ -95,24 +218,17 @@ async def proxy_path(slug: str, path: str, request: Request): if slug in _RESERVED_PATHS or not _SLUG_RE.match(slug): raise HTTPException(status_code=404, detail="Not found") - user = _authenticate(request) + user = _authenticate_request(request) if not user: raise HTTPException(status_code=401, detail="Authentication required") - ip = await _resolve_and_ensure(slug) + ip = await _resolve_and_ensure(slug, user) upstream_url = f"http://{ip}:{OPENCLAW_GATEWAY_PORT}/{path}" if request.url.query: upstream_url += f"?{request.url.query}" client = await _get_client() - headers = dict(request.headers) - headers.pop("host", None) - headers["x-octw-tenant-slug"] = slug - headers["x-octw-user-id"] = str(user.user_id) - headers["x-octw-user-email"] = user.email - headers.pop("x-forwarded-for", None) - headers["x-forwarded-for"] = request.client.host if request.client else "unknown" - headers["x-forwarded-proto"] = "https" + headers = _proxy_headers_from_request(request, slug, user) body = await request.body() resp = await client.request( @@ -122,10 +238,14 @@ async def proxy_path(slug: str, path: str, request: Request): content=body, ) + response_headers = { + key: value for key, value in resp.headers.items() + if key.lower() not in {"content-encoding", "transfer-encoding", "connection"} + } return Response( content=resp.content, status_code=resp.status_code, - headers=dict(resp.headers), + headers=response_headers, ) @@ -134,12 +254,6 @@ async def proxy_path(slug: str, path: str, request: Request): methods=["GET"], ) async def proxy_slug_root(slug: str, request: Request): - """Handle / without trailing slash.""" if slug in _RESERVED_PATHS or not _SLUG_RE.match(slug): raise HTTPException(status_code=404, detail="Not found") return await proxy_path(slug, "", request) - - -@edge_app.get("/health") -async def health(): - return {"status": "ok", "service": "octw-edge"} diff --git a/src/octw/models/provider.py b/src/octw/models/provider.py index e4df7d3..cafddec 100644 --- a/src/octw/models/provider.py +++ b/src/octw/models/provider.py @@ -27,13 +27,13 @@ class ProviderSpec: ProviderKey.ZAI: ProviderSpec( key=ProviderKey.ZAI, env_var="ZAI_API_KEY", - provider_name="zai-coding", - model_id="zai-coding/glm-5", + provider_name="zai", + model_id="zai/glm-5", model_name="glm-5", display_name="Z.ai GLM Coding Plan", - base_url=None, - api_type=None, - builtin=True, + base_url="https://api.z.ai/api/coding/paas/v4", + api_type="openai-completions", + builtin=False, ), ProviderKey.MOONSHOT: ProviderSpec( key=ProviderKey.MOONSHOT, diff --git a/src/octw/models/tenant.py b/src/octw/models/tenant.py index efc0cab..60d86f1 100644 --- a/src/octw/models/tenant.py +++ b/src/octw/models/tenant.py @@ -16,6 +16,12 @@ class TenantStatus(enum.StrEnum): DELETING = "deleting" +class VerificationStatus(enum.StrEnum): + PENDING = "pending" + VERIFIED = "verified" + FAILED = "failed" + + class ContainerState(enum.StrEnum): RUNNING = "running" PAUSED = "paused" @@ -56,6 +62,10 @@ class Tenant(BaseModel): name: str plan: TenantPlan = TenantPlan.STANDARD status: TenantStatus = TenantStatus.PROVISIONING + verification_status: VerificationStatus = VerificationStatus.PENDING + verification_error: str | None = None + verified_at: datetime | None = None + owner_user_id: uuid.UUID | None = None isolation_mode: IsolationMode = IsolationMode.STANDARD resource_limits: ResourceLimits = Field(default_factory=ResourceLimits) trusted_proxy_auth: bool = True diff --git a/src/octw/orchestrator/docker_orch.py b/src/octw/orchestrator/docker_orch.py index 4f6e11d..f435320 100644 --- a/src/octw/orchestrator/docker_orch.py +++ b/src/octw/orchestrator/docker_orch.py @@ -2,13 +2,16 @@ import os import stat +import subprocess +import textwrap +import time import uuid from pathlib import Path -import docker from docker.errors import NotFound from docker.types import Mount +import docker from octw.common.config import settings from octw.common.logging import get_logger from octw.models.tenant import ContainerState, IsolationMode, Tenant @@ -21,6 +24,85 @@ CONTAINER_STATE_DIR = f"{CONTAINER_HOME}/.openclaw" CONTAINER_WORKSPACE_DIR = f"{CONTAINER_HOME}/.openclaw/workspace" +WS_PROBE_SCRIPT = textwrap.dedent( + """ + import asyncio + import json + import sys + import websockets + + async def main() -> int: + uri, origin, email = sys.argv[1:4] + async with websockets.connect( + uri, + additional_headers={ + "Origin": origin, + "x-octw-user-email": email, + "x-forwarded-for": "127.0.0.1", + "x-forwarded-proto": "https", + "x-forwarded-host": origin.replace("https://", "").replace("http://", ""), + }, + open_timeout=10, + close_timeout=5, + max_size=1_000_000, + ) as ws: + req = { + "type": "req", + "id": "octw-probe", + "method": "connect", + "params": { + "minProtocol": 3, + "maxProtocol": 3, + "client": { + "id": "openclaw-control-ui", + "version": "control-ui", + "platform": "linux", + "mode": "webchat", + }, + "role": "operator", + "scopes": ["operator.admin", "operator.approvals", "operator.pairing"], + "caps": ["tool-events"], + "locale": "en-US", + "userAgent": "octw-probe", + }, + } + await ws.send(json.dumps(req)) + while True: + response = json.loads(await ws.recv()) + if response.get("type") == "event": + continue + if response.get("type") != "res" or response.get("id") != "octw-probe": + continue + if not response.get("ok"): + raise RuntimeError(json.dumps(response)) + break + payload = response.get("payload") or {} + if payload.get("type") != "hello-ok": + raise RuntimeError(json.dumps(response)) + await ws.send(json.dumps({ + "type": "req", + "id": "octw-status", + "method": "health", + "params": {}, + })) + while True: + health = json.loads(await ws.recv()) + if health.get("type") == "event" and health.get("event") == "health": + payload = health.get("payload") or {} + if not payload.get("ok"): + raise RuntimeError(json.dumps(health)) + break + if health.get("type") != "res" or health.get("id") != "octw-status": + continue + if not health.get("ok"): + raise RuntimeError(json.dumps(health)) + break + return 0 + + raise SystemExit(asyncio.run(main())) + """ +).strip() + class DockerOrchestrator: def __init__(self) -> None: @@ -42,6 +124,9 @@ def _image_ref(self, tenant: Tenant) -> str: return f"{ref}@{tenant.openclaw_digest}" return tenant.openclaw_image or settings.openclaw_image + def _edge_container(self): + return self._client.containers.get(settings.edge_container_name) + # --- Filesystem --- def create_tenant_dirs(self, tenant_id: uuid.UUID) -> dict[str, str]: @@ -61,17 +146,16 @@ def create_tenant_dirs(self, tenant_id: uuid.UUID) -> dict[str, str]: f"sudo chown $USER {settings.tenant_base_dir}" ) from None try: - os.chmod(d, stat.S_IRWXU) # 0700 + os.chmod(d, stat.S_IRWXU) if os.getuid() == 0: os.chown(d, 1000, 1000) except OSError: - pass # already exists with correct permissions + pass log.info("tenant_dirs_created", tenant_id=str(tenant_id), dirs=dirs) return dirs def remove_tenant_dirs(self, tenant_id: uuid.UUID) -> None: import shutil - import subprocess base = self._tenant_dir(tenant_id) if not base.exists(): @@ -79,12 +163,7 @@ def remove_tenant_dirs(self, tenant_id: uuid.UUID) -> None: try: shutil.rmtree(base) except PermissionError: - # Dirs may be owned by UID 1000; use sudo if available - subprocess.run( - ["sudo", "rm", "-rf", str(base)], - check=True, - capture_output=True, - ) + subprocess.run(["sudo", "rm", "-rf", str(base)], check=True, capture_output=True) log.info("tenant_dirs_removed", tenant_id=str(tenant_id)) # --- Network --- @@ -99,7 +178,6 @@ def create_network(self, tenant_id: uuid.UUID) -> str: net = self._client.networks.create( name=name, driver="bridge", - internal=True, labels={"octw.tenant_id": str(tenant_id)}, ) log.info("network_created", tenant_id=str(tenant_id), network_id=net.id) @@ -114,13 +192,34 @@ def remove_network(self, tenant_id: uuid.UUID) -> None: except NotFound: pass - def connect_edge_to_network(self, tenant_id: uuid.UUID, edge_container: str) -> None: + def connect_edge_to_network( + self, tenant_id: uuid.UUID, edge_container: str | None = None + ) -> str | None: name = self._network_name(tenant_id) + target = edge_container or settings.edge_container_name try: net = self._client.networks.get(name) - net.connect(edge_container) + net.reload() + connected = net.attrs.get("Containers", {}) or {} + edge = self._client.containers.get(target) + if edge.id not in connected: + net.connect(edge) + log.info("edge_connected", tenant_id=str(tenant_id), edge_container=edge.name) + return self.get_named_container_ip(target, name) except Exception as e: log.warning("edge_connect_failed", tenant_id=str(tenant_id), error=str(e)) + return None + + def get_named_container_ip(self, container_name: str, network_name: str) -> str | None: + try: + container = self._client.containers.get(container_name) + except NotFound: + return None + nets = container.attrs.get("NetworkSettings", {}).get("Networks", {}) + info = nets.get(network_name) + if info: + return info.get("IPAddress") + return None # --- Init / Onboarding --- @@ -132,7 +231,6 @@ def run_init_job( env_secrets: dict[str, str] | None = None, timeout: int = 120, ) -> str: - """Run a one-shot container to onboard OpenClaw for this tenant.""" init_name = f"octw_init_{tenant.tenant_id}" image = self._image_ref(tenant) dirs = self.create_tenant_dirs(tenant.tenant_id) @@ -186,10 +284,6 @@ def run_init_job( exit_code = result.get("StatusCode", -1) container.remove() - # The onboard command writes config/workspace then tries to start the - # gateway and connect via WebSocket. In a one-shot init container the - # gateway isn't running, so it exits 1 with a WS close error. This is - # expected -- check that the config file was actually created. config_created = "Updated" in output and "openclaw.json" in output if exit_code != 0 and not config_created: log.error( @@ -212,12 +306,15 @@ def run_init_job( log.info("init_job_completed", tenant_id=str(tenant.tenant_id)) return output + def tenant_config_exists(self, tenant_id: uuid.UUID) -> bool: + state_dir = Path(settings.tenant_base_dir) / str(tenant_id) / "state" + return (state_dir / "openclaw.json").exists() + def configure_tenant( self, tenant_id: uuid.UUID, provider_spec: object | None = None, ) -> None: - """Configure gateway and model provider in OpenClaw config.""" state_dir = Path(settings.tenant_base_dir) / str(tenant_id) / "state" config_path = state_dir / "openclaw.json" if not config_path.exists(): @@ -232,45 +329,44 @@ def configure_tenant( config = json.loads(config_path.read_text()) - # Gateway: bind to LAN so edge proxy can reach it config["gateway"] = config.get("gateway", {}) config["gateway"]["bind"] = "lan" config["gateway"]["port"] = OPENCLAW_GATEWAY_PORT - config["gateway"]["controlUi"] = config["gateway"].get("controlUi", {}) - config["gateway"]["controlUi"][ - "dangerouslyAllowHostHeaderOriginFallback" - ] = True + edge_ip = self.connect_edge_to_network(tenant_id) + config["gateway"]["trustedProxies"] = [ip for ip in [edge_ip] if ip] + config["gateway"]["auth"] = config["gateway"].get("auth", {}) + config["gateway"]["auth"]["mode"] = "trusted-proxy" + config["gateway"]["auth"]["trustedProxy"] = { + "userHeader": "x-octw-user-email", + "requiredHeaders": ["x-forwarded-proto", "x-forwarded-host"], + } + control_ui = config["gateway"].get("controlUi", {}) + control_ui["allowedOrigins"] = [settings.public_base_url.rstrip("/")] + control_ui.pop("dangerouslyAllowHostHeaderOriginFallback", None) + control_ui.pop("allowInsecureAuth", None) + control_ui.pop("dangerouslyDisableDeviceAuth", None) + config["gateway"]["controlUi"] = control_ui - # Model provider if spec: - # Set primary model in agents.defaults.model + config["env"] = config.get("env", {}) + config["env"][spec.env_var] = f"${{{spec.env_var}}}" config["agents"] = config.get("agents", {}) config["agents"]["defaults"] = config["agents"].get("defaults", {}) - config["agents"]["defaults"]["model"] = { - "primary": spec.model_id, - } + config["agents"]["defaults"]["model"] = {"primary": spec.model_id} if spec.builtin: - # Built-in providers only need the env var set (done at - # container start) and the model selection above. - # Remove any stale custom providers entry for this provider. providers = config.get("models", {}).get("providers", {}) providers.pop(spec.provider_name, None) else: - # Custom provider: write full models.providers entry config["models"] = config.get("models", {}) config["models"]["mode"] = "merge" providers = config["models"].get("providers", {}) - provider_entry: dict = { - "apiKey": f"${{{spec.env_var}}}", - } + provider_entry: dict[str, object] = {"apiKey": f"${{{spec.env_var}}}"} if spec.base_url: provider_entry["baseUrl"] = spec.base_url if spec.api_type: provider_entry["api"] = spec.api_type - provider_entry["models"] = [ - {"id": spec.model_name, "name": spec.display_name}, - ] + provider_entry["models"] = [{"id": spec.model_name, "name": spec.display_name}] providers[spec.provider_name] = provider_entry config["models"]["providers"] = providers @@ -299,7 +395,6 @@ def start_container( "OPENCLAW_GATEWAY_PORT": str(OPENCLAW_GATEWAY_PORT), "OPENCLAW_CANVAS_PORT": str(OPENCLAW_CANVAS_PORT), } - # Inject the selected provider's API key from server config if provider_env_var: api_key = settings.get_provider_api_key(provider_env_var) if api_key: @@ -308,32 +403,23 @@ def start_container( env.update(env_secrets) mounts = [ - Mount( - target=CONTAINER_STATE_DIR, - source=dirs["state"], - type="bind", - ), - Mount( - target=CONTAINER_WORKSPACE_DIR, - source=dirs["workspace"], - type="bind", - ), + Mount(target=CONTAINER_STATE_DIR, source=dirs["state"], type="bind"), + Mount(target=CONTAINER_WORKSPACE_DIR, source=dirs["workspace"], type="bind"), ] - runtime = None - if tenant.isolation_mode == IsolationMode.HARDENED: - runtime = "runsc" - + runtime = "runsc" if tenant.isolation_mode == IsolationMode.HARDENED else None security_opt = ["no-new-privileges:true"] try: existing = self._client.containers.get(name) if existing.status == "paused": existing.unpause() + self.connect_edge_to_network(tenant.tenant_id) log.info("container_unpaused", tenant_id=str(tenant.tenant_id)) return existing.id if existing.status == "exited": existing.remove() elif existing.status == "running": + self.connect_edge_to_network(tenant.tenant_id) return existing.id else: existing.remove(force=True) @@ -342,6 +428,7 @@ def start_container( network_name = self._network_name(tenant.tenant_id) self.create_network(tenant.tenant_id) + self.connect_edge_to_network(tenant.tenant_id) container = self._client.containers.run( image=image, @@ -365,17 +452,13 @@ def start_container( restart_policy={"Name": "unless-stopped"}, healthcheck={ "test": ["CMD", "curl", "-sf", f"http://localhost:{OPENCLAW_GATEWAY_PORT}/health"], - "interval": 30_000_000_000, # 30s in ns + "interval": 30_000_000_000, "timeout": 5_000_000_000, "retries": 3, "start_period": 10_000_000_000, }, ) - log.info( - "container_started", - tenant_id=str(tenant.tenant_id), - container_id=container.id, - ) + log.info("container_started", tenant_id=str(tenant.tenant_id), container_id=container.id) return container.id def stop_container(self, tenant_id: uuid.UUID, timeout: int = 30) -> None: @@ -404,6 +487,7 @@ def unpause_container(self, tenant_id: uuid.UUID) -> None: container = self._client.containers.get(name) if container.status == "paused": container.unpause() + self.connect_edge_to_network(tenant_id) log.info("container_unpaused", tenant_id=str(tenant_id)) except NotFound: pass @@ -429,7 +513,7 @@ def get_container_logs( name = self._container_name(tenant_id) try: container = self._client.containers.get(name) - kwargs: dict = {"tail": tail, "timestamps": True} + kwargs: dict[str, object] = {"tail": tail, "timestamps": True} if since: kwargs["since"] = since return container.logs(**kwargs).decode(errors="replace") @@ -437,17 +521,55 @@ def get_container_logs( return "" def get_container_ip(self, tenant_id: uuid.UUID) -> str | None: - name = self._container_name(tenant_id) - network_name = self._network_name(tenant_id) - try: - container = self._client.containers.get(name) - nets = container.attrs.get("NetworkSettings", {}).get("Networks", {}) - net_info = nets.get(network_name) - if net_info: - return net_info.get("IPAddress") - except NotFound: - pass - return None + return self.get_named_container_ip( + self._container_name(tenant_id), self._network_name(tenant_id) + ) + + def wait_for_gateway_health(self, tenant_id: uuid.UUID, timeout: int = 45) -> None: + deadline = time.time() + timeout + ip: str | None = None + while time.time() < deadline: + ip = self.get_container_ip(tenant_id) + if not ip: + time.sleep(1) + continue + result = self._edge_container().exec_run([ + "curl", "-fsS", f"http://{ip}:{OPENCLAW_GATEWAY_PORT}/health" + ]) + if result.exit_code == 0: + return + time.sleep(1) + raise RuntimeError(f"Gateway health check failed for tenant {tenant_id} (last ip={ip})") + + def verify_gateway_ws(self, tenant_id: uuid.UUID, email: str, timeout: int = 45) -> None: + deadline = time.time() + timeout + ip: str | None = None + last_output = "" + while time.time() < deadline: + ip = self.get_container_ip(tenant_id) + if not ip: + time.sleep(1) + continue + result = self._edge_container().exec_run([ + "/app/.venv/bin/python", + "-c", + WS_PROBE_SCRIPT, + f"ws://{ip}:{OPENCLAW_GATEWAY_PORT}", + settings.public_base_url.rstrip("/"), + email, + ]) + if isinstance(result.output, (bytes, bytearray)): + output = result.output.decode(errors="replace") + else: + output = str(result.output) + last_output = output.strip() + if result.exit_code == 0: + return + time.sleep(1) + raise RuntimeError( + "Gateway websocket verification failed for tenant " + f"{tenant_id}: {last_output or 'unknown error'}" + ) def cleanup_tenant(self, tenant_id: uuid.UUID) -> None: self.stop_container(tenant_id) diff --git a/src/octw/orchestrator/tenant_service.py b/src/octw/orchestrator/tenant_service.py index d52ae25..c9726b7 100644 --- a/src/octw/orchestrator/tenant_service.py +++ b/src/octw/orchestrator/tenant_service.py @@ -19,6 +19,7 @@ TenantCreate, TenantRuntimeInfo, TenantStatus, + VerificationStatus, ) from octw.orchestrator.docker_orch import DockerOrchestrator from octw.vault.service import VaultService @@ -59,8 +60,10 @@ async def create_tenant( row = TenantRow( slug=req.slug, name=req.name, + owner_user_id=creator_user_id, plan=req.plan.value, status=TenantStatus.PROVISIONING.value, + verification_status=VerificationStatus.PENDING.value, isolation_mode=req.isolation_mode.value, resource_limits=limits.model_dump(), trusted_proxy_auth=req.trusted_proxy_auth, @@ -74,6 +77,7 @@ async def create_tenant( self._orch.create_tenant_dirs(tenant.tenant_id) network_id = self._orch.create_network(tenant.tenant_id) + self._orch.connect_edge_to_network(tenant.tenant_id) row.network_id = network_id row.status = TenantStatus.STOPPED.value await session.flush() @@ -92,6 +96,7 @@ async def create_tenant( tenant.status = TenantStatus.STOPPED tenant.network_id = network_id + tenant.owner_user_id = creator_user_id log.info("tenant_created", tenant_id=str(tenant.tenant_id), slug=req.slug) return tenant @@ -110,6 +115,15 @@ async def get_tenant_by_slug( row = result.scalar_one_or_none() return self._row_to_tenant(row) if row else None + async def get_owner_tenant( + self, session: AsyncSession, owner_user_id: uuid.UUID + ) -> Tenant | None: + result = await session.execute( + select(TenantRow).where(TenantRow.owner_user_id == owner_user_id) + ) + row = result.scalar_one_or_none() + return self._row_to_tenant(row) if row else None + async def list_tenants( self, session: AsyncSession, user_id: uuid.UUID | None = None ) -> list[Tenant]: @@ -155,11 +169,15 @@ async def start_tenant( secrets = await self._vault.get_decrypted_secrets(session, tenant_id) + provider_spec = None provider_env_var: str | None = None if tenant.provider: from octw.models.provider import get_provider - spec = get_provider(tenant.provider) - provider_env_var = spec.env_var + provider_spec = get_provider(tenant.provider) + provider_env_var = provider_spec.env_var + + if self._orch.tenant_config_exists(tenant_id): + self._orch.configure_tenant(tenant_id, provider_spec=provider_spec) container_id = self._orch.start_container( tenant, env_secrets=secrets, provider_env_var=provider_env_var, @@ -208,6 +226,7 @@ async def wake_tenant( ) -> str: state = self._orch.get_container_state(tenant_id) if state == ContainerState.RUNNING: + self._orch.connect_edge_to_network(tenant_id) await self._touch_activity(session, tenant_id) tenant = await self.get_tenant(session, tenant_id) return tenant.container_id or "" @@ -224,6 +243,50 @@ async def wake_tenant( return tenant.container_id or "" return await self.start_tenant(session, tenant_id) + async def verify_tenant(self, session: AsyncSession, tenant_id: uuid.UUID) -> Tenant: + tenant = await self.get_tenant(session, tenant_id) + if not tenant: + raise ValueError(f"Tenant {tenant_id} not found") + if not tenant.owner_user_id: + raise ValueError(f"Tenant {tenant_id} has no owner for verification") + + owner = await session.get(UserRow, tenant.owner_user_id) + if not owner: + raise ValueError(f"Tenant {tenant_id} owner not found") + if not self._orch.tenant_config_exists(tenant_id): + raise RuntimeError(f"Tenant {tenant.slug} is missing openclaw.json") + + self._orch.wait_for_gateway_health(tenant_id) + self._orch.verify_gateway_ws(tenant_id, owner.email) + + await session.execute( + update(TenantRow) + .where(TenantRow.tenant_id == tenant_id) + .values( + verification_status=VerificationStatus.VERIFIED.value, + verification_error=None, + verified_at=datetime.utcnow(), + ) + ) + await session.flush() + refreshed = await self.get_tenant(session, tenant_id) + if not refreshed: + raise ValueError(f"Tenant {tenant_id} disappeared after verification") + return refreshed + + async def mark_verification_failed( + self, session: AsyncSession, tenant_id: uuid.UUID, error: str + ) -> None: + await session.execute( + update(TenantRow) + .where(TenantRow.tenant_id == tenant_id) + .values( + verification_status=VerificationStatus.FAILED.value, + verification_error=error, + ) + ) + await session.flush() + async def get_runtime_info( self, session: AsyncSession, tenant_id: uuid.UUID ) -> TenantRuntimeInfo: @@ -254,8 +317,6 @@ async def _touch_activity( ) await session.flush() - # --- Membership --- - async def _ensure_membership( self, session: AsyncSession, @@ -367,8 +428,12 @@ def _row_to_tenant(row: TenantRow) -> Tenant: tenant_id=row.tenant_id, slug=row.slug, name=row.name, + owner_user_id=row.owner_user_id, plan=row.plan, status=row.status, + verification_status=row.verification_status, + verification_error=row.verification_error, + verified_at=row.verified_at, isolation_mode=row.isolation_mode, resource_limits=limits, trusted_proxy_auth=row.trusted_proxy_auth, diff --git a/src/octw/web/static/app.css b/src/octw/web/static/app.css new file mode 100644 index 0000000..dc06016 --- /dev/null +++ b/src/octw/web/static/app.css @@ -0,0 +1,200 @@ +:root { + color-scheme: light; + --bg: #f3efe6; + --panel: rgba(255, 252, 246, 0.92); + --line: rgba(38, 34, 28, 0.12); + --text: #1f1a15; + --muted: #6d6255; + --accent: #0b7a75; + --accent-2: #f08a24; +} +* { box-sizing: border-box; } +body { + margin: 0; + min-height: 100vh; + font-family: Georgia, "Iowan Old Style", serif; + background: radial-gradient(circle at top left, #fff7df, transparent 30%), linear-gradient(160deg, #efe4d0, #f5f1ea 50%, #e7efe8); + color: var(--text); +} +.shell { + max-width: 1180px; + margin: 0 auto; + padding: 32px 20px 48px; +} +.toolbar { + display: flex; + justify-content: flex-end; + margin-bottom: 14px; +} +.language-picker { + display: inline-flex; + align-items: center; + gap: 10px; + padding: 10px 14px; + border-radius: 999px; + background: rgba(255, 252, 246, 0.78); + border: 1px solid var(--line); + color: var(--muted); + backdrop-filter: blur(16px); +} +.language-label { + font-size: 0.92rem; +} +.language-picker select { + border: 0; + background: transparent; + color: var(--text); + font: inherit; + cursor: pointer; +} +.language-picker select:focus { + outline: none; +} +.panel { + background: var(--panel); + border: 1px solid var(--line); + border-radius: 24px; + backdrop-filter: blur(16px); + box-shadow: 0 16px 40px rgba(31, 26, 21, 0.08); +} +.hero { + padding: 48px; + min-height: 280px; +} +.hero h1 { + font-size: clamp(2.4rem, 4vw, 4.5rem); + line-height: 0.95; + max-width: 10ch; + margin: 0 0 16px; +} +.eyebrow { + text-transform: uppercase; + letter-spacing: 0.18em; + color: var(--accent); + font-size: 0.76rem; + margin-bottom: 12px; +} +.lede, .muted, .status { + color: var(--muted); +} +.status[hidden] { + display: none; +} +.button { + border: 0; + border-radius: 999px; + padding: 12px 20px; + font: inherit; + cursor: pointer; + background: rgba(31, 26, 21, 0.07); + color: var(--text); +} +.button.primary { + background: linear-gradient(135deg, var(--accent), #05504c); + color: #fff; +} +.button:disabled { + cursor: wait; + opacity: 0.7; +} +.activity { + display: inline-flex; + align-items: center; + gap: 12px; + margin-top: 18px; + padding: 12px 16px; + border-radius: 999px; + background: rgba(11, 122, 117, 0.08); + color: var(--accent); + border: 1px solid rgba(11, 122, 117, 0.16); +} +.spinner { + width: 18px; + height: 18px; + border-radius: 50%; + border: 2px solid rgba(11, 122, 117, 0.2); + border-top-color: var(--accent); + animation: spin 0.9s linear infinite; +} +.activity[hidden] { + display: none; +} +.chat-shell { + display: grid; + grid-template-columns: minmax(320px, 360px) 1fr; + gap: 18px; +} +.sidebar, .chat-panel { + padding: 24px; +} +.sidebar h4 { + margin: 0 0 10px; + font-size: clamp(1.05rem, 1.4vw, 1.25rem); + line-height: 1.3; + overflow-wrap: anywhere; + word-break: break-word; +} +#tenant-meta { + margin-top: 0; + font-size: 0.98rem; + line-height: 1.45; + overflow-wrap: anywhere; + word-break: break-word; +} +.messages { + height: min(65vh, 720px); + overflow: auto; + display: flex; + flex-direction: column; + gap: 12px; + margin-bottom: 18px; +} +.message { + padding: 14px 16px; + border-radius: 18px; + max-width: min(82%, 780px); + white-space: pre-wrap; +} +.message.user { + background: #f4d5b5; + margin-left: auto; +} +.message.assistant { + background: #fff; + border: 1px solid var(--line); +} +.message.system { + background: #edf5f4; + border: 1px dashed rgba(11, 122, 117, 0.28); + max-width: 100%; +} +.composer { + display: flex; + flex-direction: column; + gap: 12px; +} +textarea { + width: 100%; + resize: vertical; + border-radius: 18px; + border: 1px solid var(--line); + padding: 16px; + font: inherit; + background: rgba(255,255,255,0.76); +} +.composer-actions { + display: flex; + align-items: center; + justify-content: space-between; +} +@keyframes spin { + to { transform: rotate(360deg); } +} +@media (max-width: 900px) { + .toolbar { + justify-content: flex-start; + } + .hero { padding: 28px; } + .chat-shell { grid-template-columns: 1fr; } + .messages { height: 56vh; } +} diff --git a/src/octw/web/static/app.js b/src/octw/web/static/app.js new file mode 100644 index 0000000..9403fa8 --- /dev/null +++ b/src/octw/web/static/app.js @@ -0,0 +1,520 @@ +const state = { + session: null, + socket: null, + requestId: 0, + pending: new Map(), + sessionKey: "main", + locale: "en", + localeForced: false, +}; + +const el = { + heroEyebrow: document.getElementById("hero-eyebrow"), + heroTitle: document.getElementById("hero-title"), + languageLabel: document.getElementById("language-label"), + languageSelect: document.getElementById("language-select"), + landing: document.getElementById("landing"), + summary: document.getElementById("summary"), + status: document.getElementById("status"), + deployButton: document.getElementById("deploy-button"), + activity: document.getElementById("activity"), + activityLabel: document.getElementById("activity-label"), + chatShell: document.getElementById("chat-shell"), + workspaceEyebrow: document.getElementById("workspace-eyebrow"), + messages: document.getElementById("messages"), + prompt: document.getElementById("prompt"), + composer: document.getElementById("composer"), + sendButton: document.getElementById("send-button"), + resumeButton: document.getElementById("resume-button"), + connection: document.getElementById("connection"), + tenantName: document.getElementById("tenant-name"), + tenantMeta: document.getElementById("tenant-meta"), +}; + +const STRINGS = { + en: { + appTitle: "OCTW Chat", + language: "Language", + heroEyebrow: "OpenClaw Tenant Wrapper", + heroTitle: "Deploy once. Resume straight into chat.", + checkingWorkspace: "Checking your workspace.", + deployWorkspace: "Deploy Workspace", + working: "Working", + workspace: "Workspace", + chat: "Chat", + resumeWake: "Resume / Wake", + promptPlaceholder: "Ask OpenClaw to do something useful.", + disconnected: "Disconnected", + connecting: "Connecting", + authorizing: "Authorizing", + connected: "Connected", + send: "Send", + signedInSummary: "Signed in as {email}. Create your dedicated OpenClaw workspace.", + tenantMeta: "{status} · {verification}", + status_running: "running", + status_paused: "paused", + status_stopped: "stopped", + status_error: "error", + status_provisioning: "provisioning", + verification_verified: "verified", + verification_pending: "pending", + verification_failed: "failed", + authFailed: "Authentication failed: {message}", + provisioningActivity: "Provisioning your workspace. This can take a minute or two.", + workspaceReady: "Workspace ready.", + workspaceResumed: "Workspace resumed.", + provisioningFailed: "Provisioning failed: {message}", + wakingWorkspace: "Waking your workspace.", + workspaceConnected: "Workspace connected.", + resumeFailed: "Resume failed: {message}", + running: "Running...", + assistantError: "Agent failed: {message}", + sendFailed: "Send failed: {message}", + timedOutWaiting: "Timed out waiting for {method}", + websocketNotConnected: "WebSocket not connected", + gatewayError: "Gateway error", + }, + es: { + appTitle: "Chat de OCTW", + language: "Idioma", + heroEyebrow: "OpenClaw Tenant Wrapper", + heroTitle: "Despliega una vez. Retoma directo en el chat.", + checkingWorkspace: "Revisando tu espacio de trabajo.", + deployWorkspace: "Desplegar espacio", + working: "Procesando", + workspace: "Espacio de trabajo", + chat: "Chat", + resumeWake: "Reanudar / Activar", + promptPlaceholder: "Pídele a OpenClaw que haga algo útil.", + disconnected: "Desconectado", + connecting: "Conectando", + authorizing: "Autorizando", + connected: "Conectado", + send: "Enviar", + signedInSummary: "Sesión iniciada como {email}. Crea tu espacio dedicado de OpenClaw.", + tenantMeta: "{status} · {verification}", + status_running: "activo", + status_paused: "pausado", + status_stopped: "detenido", + status_error: "error", + status_provisioning: "provisionando", + verification_verified: "verificado", + verification_pending: "pendiente", + verification_failed: "fallido", + authFailed: "Error de autenticación: {message}", + provisioningActivity: "Provisionando tu espacio. Esto puede tardar uno o dos minutos.", + workspaceReady: "Espacio listo.", + workspaceResumed: "Espacio reanudado.", + provisioningFailed: "Falló el provisionamiento: {message}", + wakingWorkspace: "Activando tu espacio.", + workspaceConnected: "Espacio conectado.", + resumeFailed: "Falló la reanudación: {message}", + running: "Ejecutando...", + assistantError: "El agente falló: {message}", + sendFailed: "Falló el envío: {message}", + timedOutWaiting: "Tiempo de espera agotado para {method}", + websocketNotConnected: "WebSocket no conectado", + gatewayError: "Error del gateway", + }, +}; + +function resolveLocale() { + const query = new URLSearchParams(window.location.search).get("lang"); + if (query) { + const normalized = query.toLowerCase(); + if (normalized.startsWith("es")) { + state.localeForced = true; + return "es"; + } + if (normalized.startsWith("en")) { + state.localeForced = true; + return "en"; + } + } + state.localeForced = false; + const raw = (navigator.language || "en").toLowerCase(); + if (raw.startsWith("es")) return "es"; + return "en"; +} + +function getLocaleStrings() { + return state.locale === "es" ? STRINGS.es : STRINGS.en; +} + +function getTemplate(key) { + const strings = getLocaleStrings(); + switch (key) { + case "appTitle": return strings.appTitle; + case "language": return strings.language; + case "heroEyebrow": return strings.heroEyebrow; + case "heroTitle": return strings.heroTitle; + case "checkingWorkspace": return strings.checkingWorkspace; + case "deployWorkspace": return strings.deployWorkspace; + case "working": return strings.working; + case "workspace": return strings.workspace; + case "chat": return strings.chat; + case "resumeWake": return strings.resumeWake; + case "promptPlaceholder": return strings.promptPlaceholder; + case "disconnected": return strings.disconnected; + case "connecting": return strings.connecting; + case "authorizing": return strings.authorizing; + case "connected": return strings.connected; + case "send": return strings.send; + case "signedInSummary": return strings.signedInSummary; + case "tenantMeta": return strings.tenantMeta; + case "status_running": return strings.status_running; + case "status_paused": return strings.status_paused; + case "status_stopped": return strings.status_stopped; + case "status_error": return strings.status_error; + case "status_provisioning": return strings.status_provisioning; + case "verification_verified": return strings.verification_verified; + case "verification_pending": return strings.verification_pending; + case "verification_failed": return strings.verification_failed; + case "authFailed": return strings.authFailed; + case "provisioningActivity": return strings.provisioningActivity; + case "workspaceReady": return strings.workspaceReady; + case "workspaceResumed": return strings.workspaceResumed; + case "provisioningFailed": return strings.provisioningFailed; + case "wakingWorkspace": return strings.wakingWorkspace; + case "workspaceConnected": return strings.workspaceConnected; + case "resumeFailed": return strings.resumeFailed; + case "running": return strings.running; + case "assistantError": return strings.assistantError; + case "sendFailed": return strings.sendFailed; + case "timedOutWaiting": return strings.timedOutWaiting; + case "websocketNotConnected": return strings.websocketNotConnected; + case "gatewayError": return strings.gatewayError; + default: return key; + } +} + +function getVar(vars, name) { + switch (name) { + case "email": + return vars.email ?? ""; + case "status": + return vars.status ?? ""; + case "verification": + return vars.verification ?? ""; + case "message": + return vars.message ?? ""; + case "method": + return vars.method ?? ""; + default: + return ""; + } +} + +function t(key, vars = {}) { + const template = getTemplate(key); + return template.replace(/\{(\w+)\}/g, (_, name) => `${getVar(vars, name)}`); +} + +function applyLocale() { + state.locale = resolveLocale(); + document.documentElement.lang = state.locale; + document.title = t("appTitle"); + el.languageLabel.textContent = t("language"); + el.languageSelect.value = state.locale; + el.heroEyebrow.textContent = t("heroEyebrow"); + el.heroTitle.textContent = t("heroTitle"); + el.summary.textContent = t("checkingWorkspace"); + el.deployButton.textContent = t("deployWorkspace"); + el.activityLabel.textContent = t("working"); + el.workspaceEyebrow.textContent = t("workspace"); + el.tenantName.textContent = t("chat"); + el.resumeButton.textContent = t("resumeWake"); + el.prompt.placeholder = t("promptPlaceholder"); + el.connection.textContent = t("disconnected"); + el.sendButton.textContent = t("send"); +} + +function localizeTenantState(value, prefix) { + const normalized = String(value || "").toLowerCase(); + if (prefix === "status") { + switch (normalized) { + case "running": return t("status_running"); + case "paused": return t("status_paused"); + case "stopped": return t("status_stopped"); + case "error": return t("status_error"); + case "provisioning": return t("status_provisioning"); + default: return value; + } + } + if (prefix === "verification") { + switch (normalized) { + case "verified": return t("verification_verified"); + case "pending": return t("verification_pending"); + case "failed": return t("verification_failed"); + default: return value; + } + } + return value; +} + +function toSameOriginPath(path) { + if (typeof path !== "string" || !path.startsWith("/")) { + throw new Error("Expected a same-origin absolute path"); + } + const url = new URL(path, window.location.origin); + if (url.origin !== window.location.origin) { + throw new Error("Cross-origin requests are not allowed"); + } + return `${url.pathname}${url.search}`; +} + +async function fetchJson(path, init) { + const response = await fetch(toSameOriginPath(path), { + credentials: "include", + headers: { "Content-Type": "application/json", ...(init?.headers || {}) }, + ...init, + }); + if (!response.ok) { + const body = await response.text(); + throw new Error(body || `${response.status} ${response.statusText}`); + } + return response.json(); +} + +function setStatus(message) { + const visible = Boolean(message); + el.status.hidden = !visible; + el.status.textContent = message; +} + +function setActivity(message = "") { + const active = Boolean(message); + el.activity.hidden = !active; + el.activityLabel.textContent = message || t("working"); + el.deployButton.disabled = active; + el.resumeButton.disabled = active; +} + +function addMessage(role, text) { + const node = document.createElement("div"); + node.className = `message ${role}`; + node.textContent = text; + el.messages.appendChild(node); + el.messages.scrollTop = el.messages.scrollHeight; +} + +function normalizeText(entry) { + if (!entry || typeof entry !== "object") return ""; + if (typeof entry.errorMessage === "string" && entry.errorMessage) { + return t("assistantError", { message: entry.errorMessage }); + } + if (typeof entry.text === "string") return entry.text; + if (Array.isArray(entry.content)) { + return entry.content + .map((part) => (part && typeof part.text === "string" ? part.text : "")) + .filter(Boolean) + .join("\n\n"); + } + return ""; +} + +function renderHistory(messages) { + el.messages.innerHTML = ""; + for (const message of messages || []) { + addMessage(message.role === "user" ? "user" : "assistant", normalizeText(message)); + } +} + +function nextRequestId() { + state.requestId += 1; + return `octw-${state.requestId}`; +} + +function sendRpc(method, params = {}) { + if (!state.socket || state.socket.readyState !== WebSocket.OPEN) { + throw new Error(t("websocketNotConnected")); + } + const id = nextRequestId(); + const payload = { type: "req", id, method, params }; + state.socket.send(JSON.stringify(payload)); + return new Promise((resolve, reject) => { + state.pending.set(id, { resolve, reject }); + window.setTimeout(() => { + if (state.pending.has(id)) { + state.pending.delete(id); + reject(new Error(t("timedOutWaiting", { method }))); + } + }, 15000); + }); +} + +async function loadHistory() { + const response = await sendRpc("chat.history", { sessionKey: state.sessionKey, limit: 100 }); + renderHistory(response.messages || []); +} + +async function connectChat() { + if (!state.session?.tenant) return; + if (state.socket && (state.socket.readyState === WebSocket.OPEN || state.socket.readyState === WebSocket.CONNECTING)) { + return; + } + const url = `${window.location.protocol === "https:" ? "wss" : "ws"}://${window.location.host}/t/${state.session.tenant.slug}/ws`; + const socket = new WebSocket(url); + state.socket = socket; + el.connection.textContent = t("connecting"); + let connectSent = false; + + const sendConnect = () => { + if (connectSent || socket.readyState !== WebSocket.OPEN) return; + connectSent = true; + socket.send(JSON.stringify({ + type: "req", + id: nextRequestId(), + method: "connect", + params: { + minProtocol: 3, + maxProtocol: 3, + client: { + id: "openclaw-control-ui", + version: "control-ui", + platform: navigator.platform || "web", + mode: "webchat", + }, + role: "operator", + scopes: ["operator.admin", "operator.approvals", "operator.pairing"], + caps: ["tool-events"], + locale: navigator.language, + userAgent: navigator.userAgent, + }, + })); + }; + + socket.addEventListener("open", () => { + el.connection.textContent = t("authorizing"); + window.setTimeout(sendConnect, 700); + }); + + socket.addEventListener("message", async (event) => { + const frame = JSON.parse(event.data); + if (frame.type === "event" && frame.event === "connect.challenge") { + sendConnect(); + return; + } + if (frame.type === "res") { + const pending = state.pending.get(frame.id); + if (pending) { + state.pending.delete(frame.id); + if (frame.ok) pending.resolve(frame.payload || {}); + else pending.reject(new Error(frame.error?.message || t("gatewayError"))); + } + if (frame.ok && frame.payload?.type === "hello-ok") { + el.connection.textContent = t("connected"); + await loadHistory(); + } + return; + } + if (frame.type === "event" && frame.event === "chat") { + await loadHistory(); + } + }); + + socket.addEventListener("close", () => { + el.connection.textContent = t("disconnected"); + state.socket = null; + }); +} + +async function bootstrap() { + try { + state.session = await fetchJson("/api/v1/app/session"); + } catch (error) { + setStatus(t("authFailed", { message: error.message })); + return; + } + + if (!state.session.tenant) { + el.summary.textContent = t("signedInSummary", { email: state.session.email }); + el.deployButton.hidden = false; + setActivity(""); + return; + } + + el.landing.hidden = true; + el.chatShell.hidden = false; + el.tenantName.textContent = state.session.email; + el.tenantMeta.textContent = t("tenantMeta", { + status: localizeTenantState(state.session.tenant.status, "status"), + verification: localizeTenantState(state.session.tenant.verification_status, "verification"), + }); + setActivity(""); + await connectChat(); +} + +el.deployButton.addEventListener("click", async () => { + setActivity(t("provisioningActivity")); + setStatus(""); + try { + const response = await fetchJson("/api/v1/app/deploy-or-resume", { method: "POST", body: "{}" }); + state.session = { ...state.session, tenant: response.tenant }; + await bootstrap(); + setStatus(response.created ? t("workspaceReady") : t("workspaceResumed")); + } catch (error) { + setStatus(t("provisioningFailed", { message: error.message })); + } finally { + setActivity(""); + } +}); + +el.resumeButton.addEventListener("click", async () => { + setActivity(t("wakingWorkspace")); + setStatus(""); + try { + const response = await fetchJson("/api/v1/app/deploy-or-resume", { method: "POST", body: "{}" }); + state.session = { ...state.session, tenant: response.tenant }; + await connectChat(); + await loadHistory(); + setStatus(t("workspaceConnected")); + } catch (error) { + setStatus(t("resumeFailed", { message: error.message })); + } finally { + setActivity(""); + } +}); + +el.composer.addEventListener("submit", async (event) => { + event.preventDefault(); + const message = el.prompt.value.trim(); + if (!message) return; + el.prompt.value = ""; + addMessage("user", message); + addMessage("system", t("running")); + try { + await sendRpc("chat.send", { + sessionKey: state.sessionKey, + message, + deliver: false, + idempotencyKey: nextRequestId(), + }); + } catch (error) { + addMessage("system", t("sendFailed", { message: error.message })); + } +}); + +el.prompt.addEventListener("keydown", (event) => { + if (event.key !== "Enter" || event.shiftKey) { + return; + } + event.preventDefault(); + el.composer.requestSubmit(); +}); + +el.languageSelect.addEventListener("change", (event) => { + const value = event.target.value; + const url = new URL(window.location.href); + if (value === "en") { + url.searchParams.set("lang", "en"); + } else if (value === "es") { + url.searchParams.set("lang", "es"); + } else { + url.searchParams.delete("lang"); + } + window.location.assign(url.toString()); +}); + +applyLocale(); +bootstrap(); diff --git a/src/octw/web/static/index.html b/src/octw/web/static/index.html new file mode 100644 index 0000000..1de27ba --- /dev/null +++ b/src/octw/web/static/index.html @@ -0,0 +1,53 @@ + + + + + + OCTW Chat + + + +
+
+ +
+
+

OpenClaw Tenant Wrapper

+

Deploy once. Resume straight into chat.

+

Checking your workspace.

+ + + +
+ + +
+ + + diff --git a/tests/unit/test_app_v1.py b/tests/unit/test_app_v1.py new file mode 100644 index 0000000..dfde31d --- /dev/null +++ b/tests/unit/test_app_v1.py @@ -0,0 +1,201 @@ +from __future__ import annotations + +import uuid +from types import SimpleNamespace + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient +from starlette.requests import Request + +from octw.api import auth +from octw.api.app_logic import build_user_tenant_name, build_user_tenant_slug +from octw.api.auth import TokenPayload +from octw.api.routers import app_router +from octw.api.routers.app_router import router as app_api_router +from octw.common.config import settings +from octw.models.tenant import Tenant, TenantStatus, VerificationStatus +from octw.orchestrator.docker_orch import DockerOrchestrator + + +@pytest.mark.asyncio +async def test_get_browser_user_bootstraps_from_trusted_proxy(monkeypatch): + user_id = uuid.uuid4() + + async def fake_get_or_create_user(session, email: str): + return SimpleNamespace(user_id=user_id, email=email) + + monkeypatch.setattr(settings, "trusted_proxy_enabled", True) + monkeypatch.setattr(settings, "trusted_proxy_user_header", "X-Forwarded-Email") + monkeypatch.setattr(settings, "trusted_proxy_ips", ["127.0.0.1/32"]) + monkeypatch.setattr(auth, "get_or_create_user", fake_get_or_create_user) + + request = Request( + { + "type": "http", + "headers": [(b"x-forwarded-email", b"person@example.com")], + "client": ("127.0.0.1", 1234), + } + ) + + payload, issued = await auth.get_browser_user(request, session=object()) + assert issued is True + assert payload.user_id == user_id + assert payload.email == "person@example.com" + + +@pytest.mark.asyncio +async def test_get_browser_user_rehydrates_when_cookie_user_missing(monkeypatch): + stale_user_id = uuid.uuid4() + fresh_user_id = uuid.uuid4() + stale_token = auth.create_access_token(stale_user_id, "person@example.com") + + async def fake_get_or_create_user(session, email: str): + return SimpleNamespace(user_id=fresh_user_id, email=email) + + class FakeSession: + async def get(self, model, user_id): + assert user_id == stale_user_id + return None + + monkeypatch.setattr(settings, "trusted_proxy_enabled", True) + monkeypatch.setattr(settings, "trusted_proxy_user_header", "X-Forwarded-Email") + monkeypatch.setattr(settings, "trusted_proxy_ips", ["127.0.0.1/32"]) + monkeypatch.setattr(auth, "get_or_create_user", fake_get_or_create_user) + + request = Request( + { + "type": "http", + "headers": [ + (b"x-forwarded-email", b"person@example.com"), + (b"cookie", f"octw_session={stale_token}".encode()), + ], + "client": ("127.0.0.1", 1234), + } + ) + + payload, issued = await auth.get_browser_user(request, session=FakeSession()) + assert issued is True + assert payload.user_id == fresh_user_id + assert payload.email == "person@example.com" + + +def test_build_user_tenant_slug_is_deterministic(): + user_id = uuid.UUID("11111111-2222-3333-4444-555555555555") + assert build_user_tenant_slug(user_id) == "u-11111111222233334444" + assert build_user_tenant_name("alice.smith@example.com") == "Alice Smith Workspace" + + +def test_app_session_sets_cookie(monkeypatch): + app = FastAPI() + app.include_router(app_api_router) + + class FakeTenantService: + async def get_owner_tenant(self, session, user_id): + return None + + class FakeSession: + async def commit(self): + return None + + async def fake_session_dep(): + yield FakeSession() + + async def fake_browser_user(request, session): + return TokenPayload(uuid.uuid4(), "oidc@example.com"), True + + monkeypatch.setattr(app_router, "get_browser_user", fake_browser_user) + monkeypatch.setattr(app_router, "create_access_token", lambda user_id, email: "session-token") + app.dependency_overrides[app_router.get_session] = fake_session_dep + app.dependency_overrides[app_router.get_tenant_service] = lambda: FakeTenantService() + + client = TestClient(app) + response = client.get("/api/v1/app/session") + + assert response.status_code == 200 + assert response.json()["email"] == "oidc@example.com" + assert response.cookies.get("octw_session") == "session-token" + + +def test_configure_tenant_sets_trusted_proxy(monkeypatch, tmp_path): + tenant_id = uuid.uuid4() + state_dir = tmp_path / str(tenant_id) / "state" + state_dir.mkdir(parents=True) + config_path = state_dir / "openclaw.json" + config_path.write_text( + '{"gateway": {"controlUi": {"dangerouslyAllowHostHeaderOriginFallback": true}}}' + ) + + monkeypatch.setattr(settings, "tenant_base_dir", str(tmp_path)) + monkeypatch.setattr(settings, "public_base_url", "https://chat.example.com") + + orch = DockerOrchestrator.__new__(DockerOrchestrator) + orch.connect_edge_to_network = lambda tenant_id: "172.18.0.9" + + orch.configure_tenant(tenant_id, provider_spec=None) + + data = config_path.read_text() + assert '"mode": "trusted-proxy"' in data + assert '"trustedProxies": [' in data + assert '"172.18.0.9"' in data + assert '"allowedOrigins": [' in data + assert 'dangerouslyAllowHostHeaderOriginFallback' not in data + + +def test_deploy_or_resume_reuses_existing_tenant(monkeypatch): + app = FastAPI() + app.include_router(app_api_router) + + tenant = Tenant( + tenant_id=uuid.uuid4(), + slug="u-tenant", + name="Workspace", + owner_user_id=uuid.uuid4(), + status=TenantStatus.STOPPED, + verification_status=VerificationStatus.VERIFIED, + ) + + class FakeTenantService: + def __init__(self): + self.wake_calls = 0 + + async def get_owner_tenant(self, session, user_id): + return tenant + + async def wake_tenant(self, session, tenant_id): + self.wake_calls += 1 + return "container-id" + + async def verify_tenant(self, session, tenant_id): + raise AssertionError("verified tenant should not be re-verified") + + async def get_tenant(self, session, tenant_id): + return tenant.model_copy(update={"status": TenantStatus.RUNNING}) + + fake_service = FakeTenantService() + + class FakeSession: + async def commit(self): + return None + + async def rollback(self): + return None + + async def fake_session_dep(): + yield FakeSession() + + async def fake_browser_user(request, session): + return TokenPayload(tenant.owner_user_id, "oidc@example.com"), False + + monkeypatch.setattr(app_router, "get_browser_user", fake_browser_user) + app.dependency_overrides[app_router.get_session] = fake_session_dep + app.dependency_overrides[app_router.get_tenant_service] = lambda: fake_service + app.dependency_overrides[app_router.get_orchestrator] = lambda: object() + app.dependency_overrides[app_router.get_vault_service] = lambda: object() + + client = TestClient(app) + response = client.post("/api/v1/app/deploy-or-resume") + + assert response.status_code == 200 + assert response.json()["created"] is False + assert fake_service.wake_calls == 1 diff --git a/tests/unit/test_provider.py b/tests/unit/test_provider.py index 816c63d..8d38151 100644 --- a/tests/unit/test_provider.py +++ b/tests/unit/test_provider.py @@ -15,10 +15,12 @@ def test_all_providers_defined(self): def test_get_provider_by_key(self): spec = get_provider("zai") assert spec.env_var == "ZAI_API_KEY" - assert spec.model_id == "zai-coding/glm-5" - assert spec.provider_name == "zai-coding" + assert spec.model_id == "zai/glm-5" + assert spec.provider_name == "zai" assert spec.model_name == "glm-5" - assert spec.builtin is True + assert spec.base_url == "https://api.z.ai/api/coding/paas/v4" + assert spec.api_type == "openai-completions" + assert spec.builtin is False def test_get_provider_moonshot(self): spec = get_provider("moonshot") diff --git a/uv.lock b/uv.lock index a14da8d..128948a 100644 --- a/uv.lock +++ b/uv.lock @@ -723,6 +723,7 @@ dependencies = [ { name = "sqlalchemy", extra = ["asyncio"] }, { name = "structlog" }, { name = "uvicorn", extra = ["standard"] }, + { name = "websockets" }, ] [package.dev-dependencies] @@ -753,6 +754,7 @@ requires-dist = [ { name = "sqlalchemy", extras = ["asyncio"], specifier = ">=2.0.36" }, { name = "structlog", specifier = ">=24.4.0" }, { name = "uvicorn", extras = ["standard"], specifier = ">=0.34.0" }, + { name = "websockets", specifier = ">=16.0" }, ] [package.metadata.requires-dev]