Public control API for starting, rejoining, and observing sessions.
The Proxy Control Plane validates incoming requests with the Security Token Service (STS), creates sessions in the Session Manager, and returns the assigned Proxy Dataplane WebSocket URL for the browser.
Session endpoints expect AWS ALB Cognito authentication. The control plane
cryptographically verifies the ES256 x-amzn-oidc-data JWT against the AWS
regional ALB public key endpoint. It rejects an unexpected signer ALB ARN,
issuer, client ID, algorithm, key ID, signature, expiry, or a mismatch between
the signed sub and x-amzn-oidc-identity.
The Cognito access token in x-amzn-oidc-accesstoken is also verified against
the configured issuer's cached JWKS. Verification requires RS256, valid expiry,
access-token purpose, the configured client ID, and subject equality with the
verified ALB identity. Only verified cognito:groups populate internal
actorGroups; browser identity/group fields cannot override them. JWKS reads
have bounded timeouts, response sizes, key counts, and unknown-key refreshes.
The verified sub becomes userId; clients must not send userId in the
request body. GET /healthz remains unauthenticated.
The service layer acts as a Facade over STS and Session Manager. Public handlers call one control-plane operation, while the service coordinates authorization, session assignment or lookup, and scoped token issuance without exposing those internal calls to clients.
PORT=8080 \
STS_URL=http://localhost:8082 \
SESSION_MANAGER_URL=http://localhost:8081 \
AWS_REGION=ap-southeast-1 \
ALB_ARN=arn:aws:elasticloadbalancing:ap-southeast-1:123456789012:loadbalancer/app/example/id \
COGNITO_USER_POOL_ID=ap-southeast-1_XXXXXXXXX \
COGNITO_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx \
go run ./cmd/serverCOGNITO_ISSUER may be set directly. Otherwise it is derived from
AWS_REGION and COGNITO_USER_POOL_ID. Production startup fails when verifier
configuration is incomplete.
Optional lifecycle event publication:
EVENT_PUBLISHER_ENABLED=true
EVENTS_TOPIC_ARN=arn:aws:sns:ap-southeast-1:123456789012:dendenmushi-events-dev
AWS_REGION=ap-southeast-1When enabled, the control plane publishes sanitized SessionStarted,
UserRejoined, ObserverJoined, and user-requested SessionClosed metadata
events to SNS after the synchronous control operation succeeds. Publish
failures are logged and do not fail the session path. Event payloads never
include session tokens, WebSocket URLs, terminal data, command bodies, or
secrets.
GET /healthz
POST /sessions/start
GET /sessions?status=ACTIVE&mine=false
GET /sessions/rejoin-candidates?hostId={hostId}&crId={crId}
POST /sessions/{sessionId}/rejoin
POST /sessions/{sessionId}/observe
POST /sessions/{sessionId}/closeBounded Agentic AI and automation run endpoints are owned by
agent-controlplane. Proxy Control Plane remains focused on authenticated
session start, rejoin, observe, list, and close flows. It never carries
terminal traffic.
Start request body:
{
"hostId": "host-123",
"crId": "cr-123",
"connectionType": "ssh"
}connectionType is ssh, which is also the default.
Rejoin and observe requests use an empty JSON object:
{}Close requests also use an empty JSON object. The session owner may close their
own session. Users in the Cognito SecurityAnalyst or Admin groups may close
another user's active session.
Rejoin is limited to the original session owner. Observe requires current CR authorization and returns an observer token; the signed token, rather than a URL parameter, makes the dataplane connection read-only.
To discover sessions eligible for owner rejoin, call
GET /sessions/rejoin-candidates?hostId={hostId}&crId={crId}. The control plane
derives userId from verified Cognito identity, validates rejoin access with
STS, and returns active sessions owned by that user for the requested server and
change request. The response intentionally excludes session tokens, WebSocket
URLs, and dataplane ownership fields. Use the selected sessionId with
POST /sessions/{sessionId}/rejoin to receive a fresh scoped session token.
For webapp session tables, call GET /sessions. Optional filters are hostId,
crId, status, and mine=true. The response contains safe session metadata
only and never includes session tokens, WebSocket URLs, or dataplane ownership
fields. Token issuance still happens only through start, rejoin, and observe.
Business endpoints require x-api-version: 1. GET /healthz and
GET /openapi.yaml are exempt so probes and spec reads do not need custom
headers.
Successful probe request logs are suppressed; failed probe responses still emit
request logs.
All HTTP responses use Cache-Control: no-store, disable MIME sniffing and
framing, and apply Referrer-Policy: no-referrer. The service does not emit
CORS allow headers: browser access is intentionally same-origin through the
public ALB.
Start, rejoin, observe, and rejoin discovery require STS to approve the current
CR window, explicit host scope, and actor-group entitlement. Admin bypasses
role matching only; it cannot bypass approval, time, or host scope. Rejoin and
observe use Session Manager's trusted host/CR metadata rather than browser
fields. STS rechecks the policy before issuing each session token.
STS denials return HTTP 403 with a sanitized error. If token issuance fails after
a new assignment, the control plane attempts a bounded close using both
ownerPodId and ownerInstanceId, even if the original request was cancelled.
Existing sessions are not closed by a denied rejoin or observe request. Close
remains available after CR expiry and privileged close uses verified groups.
Role names are matched case-insensitively, consistent with the web application's
Cognito role mapping: admin has the same role as Admin, and
securityanalyst as SecurityAnalyst. Browser-supplied roles remain ignored;
whitespace-padded groups are invalid, and host/CR identifiers retain exact matching.
Cross-repository verification, from this repository:
(cd ../sts && go build -o /tmp/ddm-sts-contract-test ./cmd/server)
DDM_STS_INTEGRATION_BINARY=/tmp/ddm-sts-contract-test \
DDM_NEST_CONTRACT_FIXTURE="$(cd ../nest-backend && pwd)/test/fixtures/sts-change-request.json" \
go test -race ./...The integration test runs a real STS process with local signed ALB/Cognito fixtures, a Nest-tested wire-contract fixture, and controlled Session Manager responses. It covers valid access, expired/future CRs, actor denials, missing or empty scope, out-of-scope hosts, and assignment cleanup after expiry.
OpenAPI contract, served byte-for-byte at GET /openapi.yaml.
CI validates it with openapi-spec-validator==0.9.0; handler tests check success,
error and API-version responses. Update the specification alongside handler changes.
After successful main CI, the Image workflow builds the tested source SHA
and opens a Kubernetes promotion PR with its immutable image digest. Argo CD
deploys after that PR is merged; the commit tag provides source traceability.