{ "schema": "cluster-onboarding-guide/v1", "entrypoint": "/v1/onboarding", "representations": { "html": "/v1/onboarding", "markdown": "/v1/onboarding?format=markdown", "json": "/v1/onboarding?format=json" }, "authentication": { "scheme": "Bearer", "source": "request access here; host approves owner and verification code", "request": { "path": "/v1/seed-access-requests", "proof": "SHA-256 of a locally generated random 32-byte hex key", "status": "/v1/seed-access-requests/{request_id}", "claim": "/v1/seed-access-requests/{request_id}/claim", "proof_header": "X-Access-Request-Key", "request_expires_minutes": 30, "browser_delivery": "Secure HttpOnly SameSite=Strict session cookie", "agent_delivery": "raw limited bearer returned once by claim" }, "participant_scopes": [ "fleet:read", "seed:write" ], "operator_issuer": "/v1/seed-access", "participant_can_issue_access": false }, "limits": { "archive_bytes": 536870912, "expanded_archive_bytes": 5368709120, "json_body_bytes_exclusive": 65536, "pending_slots_per_owner": 8, "upload_framing": "Content-Length; no chunked transfer" }, "preservation_tools_commit": "3a4ab6cdc5cb29712e44eabc063b1a53e8528db2", "portable_tools": "/downloads/being-seed-tools-3a4ab6c.tgz", "exporter_status": { "source_reference_false_positive": "corrected", "blank_jpeg_false_positive": "corrected", "credential_bearing_history": "recipient-bound-protected-transfer", "already_received_context": "reuse; no new export required" }, "completion": { "prepared": "originals preserved; separate working context prepared", "active": false, "automatic_runtime_activation": false, "remaining": [ "native context and HMK acceptance", "canonical signed body enrollment", "dedicated SSH", "provider login", "single Telegram consumer acceptance", "first bot welcome" ] }, "requests": { "transfer_recipient": { "method": "POST", "path": "/v1/seeds/{name}/transfer", "body": {}, "result": "durable public recipient and exact canonical recipient_sha256; private key is never returned", "read": "GET the same path; retry preserves the recipient and accepted archive", "producer": "Save only recipient as a private JSON file. Use the exact portable toolkit with cryptography==50.0.0: export --recipient FILE --recipient-sha256 DIGEST --output ARCHIVE.dm-protected --writers-stopped. Review source inventory and quiesce its writers before exporting.", "meaning": "Full selected historical credentials stay inside protected history, not live configuration. Native Matrix identity remains independently required." }, "hosted_checks": { "method": "GET", "path": "/v1/seeds/{name}/onboarding/checks", "result": "worker-owned native metadata and technical checks, remaining owner checks and preserved witness; null until the hosted collector is ready" }, "hosted_witness": { "method": "POST", "path": "/v1/seeds/{name}/onboarding/checks", "body": { "schema": "cluster-onboarding-hosted-witness/v1", "request_id": "UUID from hosted request", "plan_digest": "exact digest from hosted request", "checked_at_ms": "current Unix milliseconds", "checks": "all checks from the hosted request, each passed, missing, failed or not-checked" }, "meaning": "owner witness only; independent native observations remain required; never grants custody or activates a job" }, "local_body_requests": { "method": "GET", "path": "/v1/onboarding/local-body", "result": "owner-scoped requests even before archive intake; received inputs, fixed local checks and expected existing being" }, "local_body_report": { "method": "POST", "path": "/v1/onboarding/local-body/{name}", "body": { "schema": "cluster-onboarding-local-body-report/v1", "request_id": "UUID from the request", "checked_at_ms": "current Unix milliseconds", "checks": { "identity_context": "passed, missing, failed or not-checked", "memory": "passed, missing, failed or not-checked", "cli_resume": "passed, missing, failed or not-checked", "matrix_owner_client": "passed, missing, failed or not-checked" }, "matrix_state": "signed-identity, not-found or unavailable", "matrix_identity": "native public signed identity object for signed-identity; null otherwise" }, "meaning": "preserved local report; public identity is independently verified, local checks are self-reported; never creates custody or hosted acceptance" }, "local_body_diagnostic": { "method": "POST", "path": "/v1/onboarding/local-body/{name}/diagnostic", "body": { "schema": "cluster-onboarding-local-body-diagnostic/v1", "request_id": "UUID from the request", "reported_at_ms": "current Unix milliseconds", "component": "context-exporter, local-codex or matrix-identity", "no_credentials": true, "report": "existing nonsecret reproducible JSON object, maximum envelope 60000 bytes" }, "meaning": "owner-private evidence only; no execution, identity change or hosted acceptance; same-report retries preserve originals" }, "ssh_access": { "method": "GET", "path": "/v1/seeds/{name}/onboarding/access", "result": "owner-private dedicated SSH coordinates and pinned host key; readiness is not real owner login acceptance" }, "account_action": { "method": "GET", "path": "/v1/seeds/{name}/onboarding/action", "result": "private native OpenAI device approval; never credentials in public progress" }, "activation_review": { "method": "GET", "path": "/v1/seeds/{name}/onboarding/review", "result": "owner-private exact plan, Source context and decision state" }, "activation_consent": { "method": "POST", "path": "/v1/seeds/{name}/onboarding/review", "body": { "review_digest": "digest returned by activation_review", "inheritance_approved": true, "matrix_identity_mode": "existing or first" }, "meaning": "pair acknowledgement; host grant and native identity evidence remain required" }, "create": { "method": "POST", "path": "/v1/seeds", "required_headers": { "Idempotency-Key": "UUID" }, "body": { "name": "lowercase environment ID", "label": "daimon name", "mode": "import or new", "browser": "optional boolean", "soul": "required initial SOUL only for new" } }, "upload": { "method": "POST", "path": "/v1/seeds/{name}/archive", "body": "raw ZIP/TGZ or recipient-bound .dm-protected bytes", "required_headers": { "Content-Length": "archive byte size", "X-Archive-SHA256": "64 lowercase hex characters" }, "recommended_total_timeout_seconds": 1800 }, "selection": { "method": "GET", "path": "/v1/seeds/{name}/selection", "result": "private verified candidates" }, "prepare": { "method": "POST", "path": "/v1/seeds/{name}/prepare", "body": { "selection": "reviewed selection object; null for new" } }, "connections": { "method": "POST", "path": "/v1/seeds/{name}/connections", "body_fields": { "telegram_bot_token": "private bot token", "telegram_chat_id": "nonzero integer", "telegram_topic_id": "optional nonzero integer", "ssh_public_key": "public key only" } }, "progress": { "method": "GET", "path": "/v1/seeds", "result": "owner-scoped paginated progress" } }, "retry_rules": [ "Reuse the same creation UUID and exact specification.", "If uploaded, discover the existing archive instead of uploading again.", "An exact preparation retry preserves later receiving memory writes.", "If upload_retryable is true, resend the same archive/checksum with a 30-minute total timeout; earlier partial bytes stay preserved.", "Published archives and preparation attempts are never overwritten." ], "api": { "openapi": "3.0.3", "info": { "title": "clusterd", "version": "0.1.0", "description": "HTTP API over clusterctl (issue #17; design: docs/design/clusterd.md). Mutations adapt clusterctl; read models add owner scoping, redaction, explicit observation boundaries and bounded snapshot pagination. Errors mirror clusterctl exit codes: 0->200, 2->400, 3->404, 6->409, 10->500." }, "servers": [ { "url": "/", "description": "This HTTPS origin" } ], "paths": { "/v1/seed-access-requests": { "post": { "operationId": "requestSeedAccess", "summary": "Request human-approved private intake access", "description": "Create a pending access request. This grants no authority. The host must approve the exact owner and verification code.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "owner", "proof_sha256" ], "properties": { "owner": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,30}$" }, "proof_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } } } }, "/v1/seed-access-requests/{request_id}": { "get": { "operationId": "seedAccessRequestStatus", "summary": "Read own request with private proof header", "description": "Only the requester possessing the private proof key can access this request. Claims require host approval, expire after 30 minutes and succeed once.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Access-Request-Key", "in": "header", "required": true, "description": "Private random hex key retained by the requester; never put it in a URL.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "security": [], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/seed-access-requests/{request_id}/claim": { "post": { "operationId": "claimSeedAccess", "summary": "Claim human-approved access with private proof header", "description": "Only the requester possessing the private proof key can access this request. Claims require host approval, expire after 30 minutes and succeed once.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Access-Request-Key", "in": "header", "required": true, "description": "Private random hex key retained by the requester; never put it in a URL.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "X-Access-Delivery", "in": "header", "required": false, "description": "Browser delivery sets an HttpOnly cookie instead of returning a bearer.", "schema": { "type": "string", "enum": [ "browser" ] } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/seed-session": { "get": { "operationId": "seedSession", "summary": "Read own private intake session", "description": "Uses `n/a` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `fleet:read` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "seedSessionLogout", "summary": "Revoke own intake session", "description": "Uses `n/a` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `fleet:read` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/onboarding": { "get": { "operationId": "seedOnboarding", "summary": "Human interface or public Markdown/JSON agent guide", "description": "Uses `n/a` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `None` (route is public)", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "html", "markdown", "json" ] } } ], "security": [], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/seeds": { "get": { "operationId": "listSeeds", "summary": "Owner-scoped seed preparation progress", "description": "Uses `clusterctl seed list --json` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `fleet:read` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 512 } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "Bounded immutable snapshot page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotPage" } } } }, "400": { "description": "invalid limit/cursor or cursor scope mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "cursor snapshot expired or was evicted; restart pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createSeed", "summary": "Create an import slot or a new being context", "description": "Uses `clusterctl seed create` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "uuid. Retry with the same key replays the cached clusterctl result (idempotent-replay: true); reuse for a different operation/target is a 409 conflict. Dedupe is clusterctl's own idempotency store.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "400": { "description": "missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/seed-access": { "post": { "operationId": "createSeedAccess", "summary": "Operator issues a short-lived owner-scoped access token once", "description": "Uses `clusterd --token-create` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/seeds/{seed}/archive": { "post": { "operationId": "uploadSeed", "summary": "Stream a bounded private archive with SHA-256", "description": "Uses `clusterctl seed upload` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Archive-SHA256", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/v1/seeds/{seed}/transfer": { "get": { "operationId": "seedTransfer", "summary": "Read the durable public recipient for private complete history", "description": "Uses `clusterctl seed recipient` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "seedTransferRequest", "summary": "Create or reuse an owner-bound private transfer recipient", "description": "Uses `clusterctl seed recipient` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/seeds/{seed}/selection": { "get": { "operationId": "discoverSeed", "summary": "Verify and discover private receiving candidates", "description": "Uses `clusterctl seed discover` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/seeds/{seed}/prepare": { "post": { "operationId": "prepareSeed", "summary": "Preserve originals and prepare receiving context", "description": "Uses `clusterctl seed prepare` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/seeds/{seed}/connections": { "post": { "operationId": "seedConnections", "summary": "Store private bot data and a public SSH key", "description": "Uses `clusterctl seed connections` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/seeds/{seed}/onboarding": { "get": { "operationId": "seedOnboardingStatus", "summary": "Read owner-scoped receiving activation progress", "description": "Uses `onboarding worker read model` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `fleet:read` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/seeds/{seed}/onboarding/action": { "get": { "operationId": "seedOnboardingAction", "summary": "Read private account authorization action", "description": "Uses `native Codex device login` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/seeds/{seed}/onboarding/access": { "get": { "operationId": "seedOnboardingAccess", "summary": "Read private dedicated SSH coordinates", "description": "Uses `clusterctl seed ssh` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/seeds/{seed}/onboarding/checks": { "get": { "operationId": "seedHostedChecks", "summary": "Read independent hosted evidence and remaining owner checks", "description": "Uses `clusterctl seed checks` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "seedHostedWitness", "summary": "Preserve owner witnesses without granting hosted acceptance", "description": "Uses `clusterctl seed witness` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/seeds/{seed}/onboarding/review": { "get": { "operationId": "seedOnboardingReview", "summary": "Review the exact plan and proposed Source context", "description": "Uses `clusterctl seed review` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "seedOnboardingConsent", "summary": "Record the pair's exact plan acknowledgement", "description": "Uses `clusterctl seed consent` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner. Browser-cookie mutations require an Origin header matching this HTTPS host; explicit API bearer requests are unchanged.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] }, { "intakeCookie": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/onboarding/local-body": { "get": { "operationId": "localBodyRequests", "summary": "Read pending local Codex checks in this private workspace", "description": "Uses `owner-scoped local body requests` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/onboarding/local-body/tools/{tool}": { "get": { "operationId": "localBodyTool", "summary": "Download the existing-body public identity exporter", "description": "Uses `maintained native public identity tools` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "tool", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/onboarding/local-body/{seed}": { "get": { "operationId": "localBodyRequest", "summary": "Read one local Codex check and received inputs", "description": "Uses `owner-scoped local body request` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "localBodyReport", "summary": "Submit local checks and an existing public signed Matrix identity", "description": "Uses `preserved local body report` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/onboarding/local-body/{seed}/diagnostic": { "post": { "operationId": "localBodyDiagnostic", "summary": "Preserve an owner-private nonsecret reproducible blocker report", "description": "Uses `participant diagnostic; never executable instructions` as its source; mutations retain the same clusterctl business-logic boundary while reads may add owner scoping, redaction, observation envelopes, and bounded snapshot pagination.\n\nRequired bearer scope: `seed:write` \u2014 enforced (issue #18). Owner-scoped tokens may only touch daimons whose spec created_by matches the owner.", "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "description": "Echoed back; a uuid4 is generated when absent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Actor", "in": "header", "required": false, "description": "Advisory only. Authenticated routes use the bearer token actor as the authoritative actor.", "schema": { "type": "string", "default": "anonymous" } }, { "name": "seed", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Human-Approval", "in": "header", "required": false, "description": "Base64url clusterd-human-approval/v1 artifact. Required for steward@* execution and signed by a separately provisioned human authority over the exact 409 intent. Caller attendance headers carry no authority.", "schema": { "type": "string", "maxLength": 16384 } }, { "name": "X-Confirm", "in": "header", "required": false, "description": "'none' executes non-destructive mutations (start/stop/restart) directly. Destructive-class routes ALWAYS require a confirmation token regardless.", "schema": { "type": "string", "enum": [ "none" ] } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "clusterctl result JSON (exit 0)" }, "401": { "description": "missing/unknown/expired/revoked bearer token ({error: unauthorized})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "authenticated but denied: insufficient scope, not your daimon (owner mismatch), or unattended-steward-denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "not found (CLI exit 3)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "conflict (CLI exit 6: idempotency-key reuse, lock held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "mutation rate limit: 60 mutations/minute per token (sliding window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "internal error (CLI exit 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error", "action", "target", "request_id" ], "properties": { "error": { "type": "string" }, "action": { "type": "string" }, "target": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } } }, "SnapshotPage": { "type": "object", "required": [ "schema", "items", "page" ], "properties": { "schema": { "type": "string", "enum": [ "clusterd-page/v1" ] }, "items": { "type": "array", "items": { "type": "object" } }, "page": { "type": "object", "required": [ "limit", "count", "has_more", "next_cursor", "snapshot_id", "observed_at_ms", "expires_in_s", "truncated" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "count": { "type": "integer", "minimum": 0, "maximum": 200 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "snapshot_id": { "type": "string" }, "observed_at_ms": { "type": "integer" }, "expires_in_s": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean" } } } } }, "ConfirmationChallenge": { "type": "object", "required": [ "schema", "token", "operation", "target", "actor", "action_digest", "created_ms", "ttl_s" ], "properties": { "schema": { "type": "string", "enum": [ "confirmation/v1" ] }, "token": { "type": "string", "description": "single-use; send back as X-Confirm-Token" }, "operation": { "type": "string" }, "target": { "type": "string" }, "actor": { "type": "string" }, "action_digest": { "type": "string", "description": "sha256 of canonical JSON {operation,target,actor,args} \u2014 binds the confirmation to exactly that action" }, "created_ms": { "type": "integer" }, "ttl_s": { "type": "integer", "default": 900 } } } }, "securitySchemes": { "intakeCookie": { "type": "apiKey", "in": "cookie", "name": "dm_seed_access", "description": "Three-day Secure HttpOnly SameSite=Strict browser access; accepted only by seed and seed-session routes." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Scoped bearer token, format dcd_ (issue #18, design \u00a72/\u00a73). ENFORCED: tokens are sha256-hashed at rest in state_dir/auth/tokens.json (auth-token/v1); manage via `scripts/clusterd --token-create | --token-revoke | --token-list`. Scopes are exact operation classes (fleet:read, lifecycle:write, backup:write, etc.). Owner-scoped tokens may only touch their own daimons. Revocation takes effect without restart. Intake metadata and access requests are public; participant data and fleet routes require authorized access." } } } } }