diff --git a/.dockerignore b/.dockerignore index 32881c66..84a06964 100644 --- a/.dockerignore +++ b/.dockerignore @@ -19,6 +19,9 @@ docs # other repos checked out for reference reference/ +# Local agent state (Claude Code settings and worktrees) +.claude/ + # Web app artifacts web/node_modules/ web/dist diff --git a/cmd/mock-convox/handlers_apps.go b/cmd/mock-convox/handlers_apps.go index 76a44339..b6626edf 100644 --- a/cmd/mock-convox/handlers_apps.go +++ b/cmd/mock-convox/handlers_apps.go @@ -99,7 +99,13 @@ func updateService(w http.ResponseWriter, r *http.Request) { app := vars["app"] service := vars["service"] - updated, err := updateServiceState(app, service, r.URL.Query()) + // Like the real rack, read options from the form body (where the SDK sends them) as well as the query. + r.Body = http.MaxBytesReader(w, r.Body, 1<<20) + if err := r.ParseForm(); err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) + return + } + updated, err := updateServiceState(app, service, r.Form) if err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return diff --git a/docs/src/content/docs/configuration/environment-variables.mdx b/docs/src/content/docs/configuration/environment-variables.mdx index 9ce44902..b3ef0d86 100644 --- a/docs/src/content/docs/configuration/environment-variables.mdx +++ b/docs/src/content/docs/configuration/environment-variables.mdx @@ -6,6 +6,22 @@ description: Complete reference of all environment variables for Rack Gateway. This page provides a complete reference of Rack Gateway environment variables. For a shorter overview, see [Configuration](/configuration/). +## Production Safety Check + +The first time a gateway starts against a database, it marks the database as `production` (or `development` when `DEV_MODE=true`). A gateway refuses to start against a production database while any development or test-only setting is present, because each one weakens a security control: + +| Variable | Why it's refused in production | +|----------|--------------------------------| +| `DEV_MODE=true` | Relaxes cookies, CSP and secret requirements | +| `E2E_TEST_MODE=true` | Skips WebAuthn assertion checks | +| `AWS_ENDPOINT_URL` | Sends every AWS call (S3 audit anchors, STS, KMS) to another endpoint | +| `AWS_ENDPOINT_URL_S3` | Sends audit anchors to another S3 endpoint | +| `AWS_ENDPOINT_URL_STS`, `AWS_ENDPOINT_URL_KMS` | Sends AWS credential exchange or key operations to another endpoint | +| `POSTMARK_API_BASE` | Sends the Postmark token to another server | +| `GOOGLE_OAUTH_BASE_URL` without `https://` | Accepts identity tokens over plain HTTP | + +The error names every offending variable. Remove them from the production environment and restart. `GOOGLE_ALLOWED_DOMAIN` is required whenever `DEV_MODE` is off. + ## Core Server | Variable | Default | Description | diff --git a/docs/src/content/docs/development/api-reference.mdx b/docs/src/content/docs/development/api-reference.mdx index 399a7129..3b9c6a1e 100644 --- a/docs/src/content/docs/development/api-reference.mdx +++ b/docs/src/content/docs/development/api-reference.mdx @@ -17,7 +17,9 @@ The OpenAPI spec is the source of truth, but this page summarizes the current su ## Authentication -Most endpoints require either a session cookie (browser/CLI login) or an API token (automation). +Gateway endpoints require a session (browser cookie or CLI login). API tokens (automation) can use the rack proxy (`/api/v1/rack-proxy/*`) and only four gateway endpoints: `GET /info`, `GET /rack`, `POST /deploy-approval-requests` and `GET /deploy-approval-requests/{id}`. Every other gateway endpoint returns `403 API tokens cannot use this endpoint`. + +Each gateway endpoint declares the permission it needs; callers without it get `403 insufficient permissions: requires `. Endpoints under `/users/{email}` that read or sign out a user's own sessions, profile or audit log also accept that user themselves. ### Session Authentication diff --git a/docs/src/content/docs/getting-started/architecture.mdx b/docs/src/content/docs/getting-started/architecture.mdx index e488d4dd..d5639b34 100644 --- a/docs/src/content/docs/getting-started/architecture.mdx +++ b/docs/src/content/docs/getting-started/architecture.mdx @@ -71,7 +71,7 @@ rack-gateway apps 4. Gateway validates session token 5. Gateway checks MFA requirements (if enabled) 6. Gateway checks RBAC permissions for `convox:app:list` -7. If authorized, gateway forwards to real Convox rack +7. If authorized, gateway forwards to real Convox rack. Only the request headers the Convox API uses (an allowlist) are forwarded; cookies, CSRF and MFA headers and any client-supplied identity headers are dropped. The gateway authenticates to the rack with its own credential and sets `X-Convox-Actor` to the signed-in user (or `token:`), so the rack's own logs name the real caller. Query parameters are limited to the ones the Convox SDK sends; a request with any other is refused, because the rack would read options such as an exec command or release env from the query string without the gateway checking them. 8. Gateway logs the action to audit log 9. Response returned to user diff --git a/docs/src/content/docs/security/authentication/api-tokens.mdx b/docs/src/content/docs/security/authentication/api-tokens.mdx index e34d97bc..298bd5ff 100644 --- a/docs/src/content/docs/security/authentication/api-tokens.mdx +++ b/docs/src/content/docs/security/authentication/api-tokens.mdx @@ -12,8 +12,8 @@ API tokens provide authentication for automated systems like CI/CD pipelines, sc | Aspect | API Tokens | Sessions | |--------|-----------|----------| | **Use Case** | Automation, CI/CD | Human users | -| **Creation** | Admin/user creates | OAuth flow | -| **Lifetime** | Until deleted | Idle timeout | +| **Creation** | Deployers (for themselves) or admins | OAuth flow | +| **Lifetime** | Until deleted or the optional `expires_at` | Idle timeout | | **MFA** | Not applicable | Supported | | **CSRF** | Not required | Required | | **Revocation** | Manual delete | Logout/admin | @@ -58,7 +58,7 @@ API tokens store explicit permissions. Roles are a shortcut at creation time: | `ops` | Emergency scripts | Restart, exec, view env | | `deployer` | Deploy automation | Full deploy capabilities | | `cicd` | CI/CD pipelines | Minimal deploy + approval | -| `admin` | Full automation | All operations | +| `admin` | Rack automation | All Convox operations, capped by the owner's role |