2026-06-01 16:09:01 +00:00
2 changed files with 2109 additions and 0 deletions
@@ -0,0 +1,114 @@
+# Molecule Platform OpenAPI specs
+
+This directory holds the machine-readable API contracts for the Molecule
+platform.
+
+| File | Spec | Scope | Status |
+|------|------|-------|--------|
+| `management.yaml` | OpenAPI **3.1** | The **management surface** across both services (orgs, billing, admin, provisioning, workspaces, secrets, templates, org-tokens, bundles). | **SSOT** — hand-authored. |
+| `swagger.yaml` / `swagger.json` | OpenAPI 2.0 | swaggo-generated stub, `/schedules` only (the per-workspace **runtime** surface). | Legacy stub; superseded for management by `management.yaml`. |
+
+`management.yaml` is the **single source of truth** the management tooling
+derives from — the management MCP server, the management CLI (`molecule-cli`),
+and the human-facing API docs (RFC #1706, the gap closed by
+`PLATFORM-MANAGEMENT-API.md` §5c). Do not hand-edit those clients' route maps;
+change them here and regenerate/derive.
+
+## The two-service split
+
+One structural fact drives the whole spec: there are **two services with two
+auth stacks**, and the management surface spans both.
+
+```
+                         ┌─────────────────────────────────────────┐
+   browser / CLI / MCP   │  Control plane (CP)                      │
+        │                │  molecule-controlplane @ api.moleculesai │
+        │  session       │  /api/v1/* (stable) [+ /cp/* sunset]      │
+        ├───────────────▶│  orgs · members · billing · provisioning │
+        │  admin bearer  │  · fleet/admin ops · pins                 │
+        │  provision sec │                                          │
+        └────────────────┴──────────────┬───────────────────────────┘
+                                         │ edge reverse-proxy
+                                         │ (subdomain / X-Molecule-Org-Slug)
+                                         ▼
+                         ┌─────────────────────────────────────────┐
+   Org API Key / ws tok  │  Tenant workspace-server                 │
+        │                │  molecule-core/workspace-server          │
+        └───────────────▶│  ONE EC2 per org @ <slug>.moleculesai.app│
+                         │  workspaces · secrets · templates ·      │
+                         │  org-tokens · bundles                    │
+                         └─────────────────────────────────────────┘
+```
+
+- **Control plane (CP)** — `api.moleculesai.app`, routes modelled under
+  `/api/v1/*` (the `/cp/*` mirror is identical but sunset-headed per RFC #61 and
+  is not duplicated in the spec). Owns **orgs, members, billing, provisioning,
+  fleet/admin ops**.
+- **Tenant workspace-server** — one EC2 per org at `<slug>.moleculesai.app`.
+  Owns **workspaces, agents, secrets, templates, org-tokens, bundles**. Requests
+  may also be sent to the CP host with an `X-Molecule-Org-Slug` header; the CP
+  edge reverse-proxies them to the tenant host (the `Authorization`,
+  `X-Molecule-Org-*`, and cookie headers pass through unchanged and the tenant's
+  own middleware validates them).
+
+The key consequence, called out in `PLATFORM-MANAGEMENT-API.md`: **the Org API
+Key is a TENANT credential, not a CP one.** It is full tenant-admin over its own
+org's workspace-server surface and reaches **nothing** on the CP (org
+create/delete, billing, members, provisioning all 401/403 it). That is why
+member/billing tools belong in a separate CP-admin MCP, not the org-key-authed
+management MCP.
+
+## Security scheme → surface map (the tier matrix)
+
+`management.yaml` defines these `securitySchemes`; each operation declares the
+one(s) it accepts. Mirror of `PLATFORM-MANAGEMENT-API.md` §1:
+
+| Scheme | What it is | Where it applies |
+|--------|-----------|------------------|
+| `workosSession` | WorkOS AuthKit session cookie `mcp_session` (+ org membership/ownership checks) | CP `/api/v1/orgs/*`, `/api/v1/billing/*`. Also accepted on the tenant surface via the CP-session path. |
+| `cpAdminBearer` | CP `CP_ADMIN_API_TOKEN` operator bearer (AdminGate, constant-time) | CP `/api/v1/admin/*` — admin-create-org, tenant teardown, workspace env, ListOrgWorkspaces, redeploy, pins. |
+| `provisionSecret` | CP `PROVISION_SHARED_SECRET` bearer | CP `/api/v1/workspaces/provision`, `…/status`. Routes unmounted when the secret is unset. |
+| `tenantAdminToken` | Per-tenant admin_token (+ `X-Molecule-Org-Id`) | CP `DELETE /api/v1/workspaces/:id` (deprovision) — **in addition to** `provisionSecret` (issue #118). |
+| `orgApiKey` | Tenant Org API Key — `Authorization: Bearer <key>` + routing header; full tenant-admin, self-minting | **All** tenant routes: `/workspaces[/:id]`, `/workspaces/:id/secrets`, budget, billing-mode, `/settings/secrets`, `/org/import`, `/org/templates`, `/org/tokens`, `/templates`, `/bundles`. |
+| `workspaceToken` | Per-workspace bearer, bound to one workspace id (+ routing header) | Read/lifecycle/secrets on a single `/workspaces/:id/*`. **Rejected** on admin list/create/delete when ADMIN_TOKEN is set — use `orgApiKey`. |
+| `orgRoutingHeaderId` / `orgRoutingHeaderSlug` | `X-Molecule-Org-Id` / `X-Molecule-Org-Slug` | Required on every tenant-host request so the edge / TenantGuard route + authorize against the correct org. Send one of them alongside the bearer. |
+
+### Guards worth knowing (modelled per-operation)
+
+- **Dry-run:** `POST /api/v1/admin/orgs?dry_run=true` — validate + echo, no org
+  created. (The only dry-run on the whole management API.)
+- **Confirm token:** `DELETE /api/v1/admin/tenants/:slug` and
+  `…/scrub-artifacts` — body `confirm` MUST equal the URL slug, else `400`
+  before any teardown.
+- **Force flag:** `POST /api/v1/admin/workspaces/:id/env` — keys matching the
+  secret-keyword guard (`TOKEN`/`SECRET`/`KEY`/`PASSWORD`) require `force=true`.
+- **Runtime-pin gate:** `POST /api/v1/workspaces/provision` returns `422
+  RUNTIME_PIN_MISSING` when no runtime image pin exists.
+- **Auto-restart side-effects:** writing a workspace or global secret
+  auto-restarts the affected workspace(s).
+
+## Security note (carried from the synthesis spec)
+
+The Org API Key is **full tenant-admin and self-minting** — a management MCP
+holding one holds tenant root. There is no scope-down today (TODO in
+`orgtoken`). Per-role / per-workspace scoping should ship alongside the
+management MCP.
+
+## Validate
+
+```bash
+cd workspace-server/docs/openapi
+npx @redocly/cli lint management.yaml   # must be clean (0 errors, 0 warnings)
+```
+
+## Scope notes / best-effort flags
+
+- The per-workspace **runtime** surface (schedules, agent, registry, a2a,
+  memory, approvals, channels, terminal, files) is intentionally **out of
+  scope** here — that's the runtime contract, not management.
+- A handful of bodies are **best-effort** from the handlers (org-import inline
+  template, bundle import, list responses with open shapes) and are marked with
+  `additionalProperties: true` in the schema. Tighten as the handler structs
+  stabilise.
+- `/cp/*` deprecated mirrors are omitted (identical shapes; RFC #61
+  Deprecation/Sunset). Build against `/api/v1/*`.