Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

46 Commits

Folders and files

Repository files navigation

Proxy Control Plane

Public control API for starting, rejoining, and observing sessions.

Overview

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.

Design Patterns

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.

Run

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/server

COGNITO_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-1

When 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.

Endpoints

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}/close

Bounded 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.

Change-request policy

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.

API contract and CI

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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages