Security Token Service. It validates well-formed access requests and issues short-lived session tokens.
PORT=8082 \
JWT_SIGNING_KEY='replace-with-at-least-32-random-bytes' \
CHANGE_REQUEST_URL=http://localhost:8085 \
SERVER_INVENTORY_URL=http://localhost:8086 \
go run ./cmd/serverFor local development without a server-inventory service, configure a trusted static inventory:
SERVER_INVENTORY_STATIC_JSON='{
"host-123": {
"address": "server.example:22",
"username": "ubuntu",
"connectionType": "ssh",
"credentialSecretId": "dendenmushi/host-123",
"hostPublicKey": "ssh-ed25519 AAAA..."
}
}'JWT_SIGNING_KEY is required and must contain at least 32 bytes. All STS
instances and token-verifying services must use the same secret. Generate one
for local development with openssl rand -base64 32.
Optional token settings:
SESSION_TOKEN_TTL_SECONDS=300
AUTOMATION_TOKEN_TTL_SECONDS=600
AUTOMATION_WORKLOAD_AUDIENCE=dendenmushi-incident-agent
AUTOMATION_WORKLOAD_NAMESPACE=dendenmushi-agentic
AUTOMATION_TOKEN_SERVICE_ACCOUNTS=agent-tool-gateway
WORKLOAD_IDENTITY_SERVICE_ACCOUNTS=incident-agent,agent-controlplane
JWT_ISSUER=dendenmushi-sts
JWT_AUDIENCE=dendenmushi-session
JWT_CLOCK_SKEW_SECONDS=5Optional lifecycle event publication:
EVENT_PUBLISHER_ENABLED=false
EVENTS_TOPIC_ARN=
AWS_REGION=ap-southeast-1When enabled, /validate publishes sanitized AccessAllowed and
AccessDenied metadata events to SNS. Events never include session tokens,
automation capability tokens, secrets, command bodies, prompts, or terminal
streams. Publish failures are logged and do not change the authorization
response.
CHANGE_REQUEST_URL is required for interactive access. STS fails closed when
it is absent or its lookup fails. In EKS it points to
http://nest-backend.dendenmushi-webapp.svc.cluster.local:3000/sts.
The trusted backend returns:
GET /change-requests/{crId}{
"crId": "cr-123",
"status": "Approved",
"hostIds": ["host-123"],
"implementationStartAt": "2026-10-07T08:00:00.000Z",
"implementationEndAt": "2026-10-07T10:00:00.000Z",
"allowedRoles": ["Employee"]
}Start, rejoin, observe, rejoin discovery, and /tokens/session issuance require:
- The returned CR ID matches the requested ID and its status is approved.
- Both timestamps are valid, start precedes end, and
start <= now < end. CR windows have no clock-skew grace period. hostIdsis explicitly present, non-empty, contains no blank entries, and includes the exact requested gateway host ID.actorGroupscomes from Proxy Control Plane's cryptographically verified Cognito access token. Group names matchallowedRolescase-insensitively, consistent with the web application's role mapping (for example,adminandAdmin). Whitespace-padded role names remain invalid; host and CR IDs remain case-sensitive.Adminbypasses role matching only, including an explicitly empty role list. Missing/null/malformed role metadata is denied even for Admin.
The STS API is internal: caller assertions are trusted only within the existing
service/network boundary. Do not expose /validate or /tokens/session to
browsers or accept browser-supplied actor groups. Missing actor context, malformed
metadata, and unavailable upstreams deny access with sanitized errors. Role/group
checks refer to Cognito groups, not implementer-group OS usernames.
For rejoin and observe, Proxy Control Plane resolves hostId and crId from
Session Manager. Rejoin remains owner-only; observe remains read-only. These checks require the trusted session host and CR metadata.
Closing a session remains available after CR expiry. Existing attachments and
issued-token TTLs retain their lifecycle behavior; this policy does not terminate
an already attached terminal at the CR end time.
A configured inventory URL still uses GET /servers/{hostId}. EKS continues to
use trusted static SSH inventory. CR metadata never supplies SSH credentials.
STS models access checks as policy strategies behind the /validate endpoint.
Common validation runs first, then the action-specific policy for start,
rejoin, observe, or stop. The start policy composes the trusted
change-request and optional server-inventory clients using the internal actor-group contract.
GET /healthz
POST /validate
POST /tokens/session
POST /tokens/validate
POST /tokens/automation
POST /tokens/automation/validate
POST /workloads/validateBusiness 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.
/validate accepts start requests scoped by hostId and crId, session
operations scoped by sessionId, and owner rejoin discovery requests scoped by
hostId and crId.
/tokens/validate is used by token-consuming services. A successful response
returns the verified claims. Callers may provide expected userId, hostId,
crId, connectionType, action, and mode values; STS rejects the request
if any provided expected value does not match the signed token. Tokens bind the
session action (start, rejoin, or observe), mode, host, change request,
connection type, and trusted SSH target metadata. Observer tokens cannot become
writable owner connections.
Session tokens are RFC 7519 JWTs signed with JWS HS256. They include the
registered iss, sub, aud, exp, nbf, iat, and jti claims plus the
private session and SSH target claims. Verification only accepts HS256 and
requires the configured issuer, audience, expiration, and issued-at values.
Automation capability tokens are a separate JWT type and cannot be used as
interactive session tokens. Issuance requires a projected Kubernetes
service-account token that passes TokenReview for the configured namespace,
audience, and AUTOMATION_TOKEN_SERVICE_ACCOUNTS; production narrows this to
agent-tool-gateway. Capabilities bind the run, incident, host, phase,
operation allowlist, assigned pod instance, and remediation plan hash.
POST /workloads/validate validates projected tokens against
WORKLOAD_IDENTITY_SERVICE_ACCOUNTS and returns only normalized subject,
namespace, and serviceAccount fields. A2A and MCP services use this endpoint
for authentication. It never returns or logs the submitted token. The existing
audience is intentionally retained so identity and capability callers can use
the same projected-token configuration while their service-account allowlists
remain separate.
The Kubernetes reviewer credential is read from its mounted service-account token file for every TokenReview. Kubernetes rotates this file while the STS pod is running; STS fails closed if the current credential is missing or empty and never logs either the reviewer credential or submitted workload token.
For Phase 2 AI-agent integrations, STS remains the authority boundary. Model output never grants capability by itself; callers must present workload identity for issuance and consumers must validate the signed run, incident, host, operation allowlist, assigned pod instance, and plan hash before executing any automation step.
Trusted inventory entries may include:
{
"automation": {
"catalogVersion": "v1",
"serviceName": "myapp",
"healthUrl": "http://127.0.0.1:8080/healthz",
"helperPath": "/usr/local/sbin/ddm-ops",
"allowedOperations": [
"service_status",
"health_check",
"restart_service",
"recover_demo_app",
"reload_service"
]
}
}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.