NestJS APIs for change requests, inventory, access policy, memberships, and Cognito user administration.
This backend owns authenticated web application data APIs, STS inventory/change-request lookups, Cognito administration, readiness, and CloudWatch monitoring views. It does not proxy terminal streams or issue session tokens.
All application APIs use the /ddm prefix. Kubernetes probes are intentionally
outside that prefix:
GET /healthz
GET /readyzBusiness endpoints require x-api-version: 1. GET /healthz, GET /readyz,
GET /openapi.yaml, /, /ddm/auth/login, /ddm/auth/logout, and
/ddm/monitoring/alerts/webhook are exempt so probes, browser redirects, and
SNS delivery do not need custom headers.
Successful probe request logs are suppressed; failed probe responses still emit
request logs.
/healthz only reports that the process is running. /readyz executes
SELECT 1 and returns 503 while PostgreSQL is unavailable.
AUTH_MODE=dev enables the local JWT login flow for development.
Production requires AUTH_MODE=alb. The backend verifies both AWS ALB
authentication headers:
x-amzn-oidc-data: signature, expiry, signer ALB ARN, issuer, and client ID.x-amzn-oidc-accesstoken: signature, expiry, issuer, client ID, and token use.
The verified sub values must match. Cognito groups are taken from the access
token and mapped to application roles. Requester, approver, and audit actor
fields are always derived from this authenticated identity.
GET /ddm/auth/login
GET /ddm/auth/logoutLogin is an ALB authentication entry point. Logout expires the ALB session
cookie and all four possible cookie shards, disables caching of the response,
and redirects through the Cognito logout endpoint. APP_LOGOUT_URI must point
to an unauthenticated landing page that is registered as an allowed Cognito
sign-out URL.
All responses disable caching and include MIME-sniffing, framing, and referrer
protections. The Express X-Powered-By banner is disabled. Production uses
same-origin browser APIs and leaves CORS disabled. Local development may set
CORS_ENABLED=true and a comma-separated CORS_ORIGINS list of exact
http:// or https:// origins. Wildcards and credentialed cross-origin
requests are intentionally unsupported.
npm ci
npm run start:dev
npm test -- --runInBand
npm run buildUse .env.example as the configuration reference. Local development may use
the individual DB_* settings. Production must use DATABASE_URL and set
DB_SSL=true; application startup and migrations reject production
configuration that does not enable database TLS.
npm run audit:prod checks production dependencies against the reviewed
audit policy and retains the native findings in
npm-audit.json. npm run test:audit-policy verifies enforcement, including
the expiry of reviewed exceptions. High and critical findings fail CI.
Sequelize model synchronization is disabled. Apply versioned migrations before rolling out a new backend image:
npm run migratepremigrate runs npm run build automatically so compiled migration files exist.
Versioned migrations create all domain tables. The initial migration seeds the six default access policies and creates alert event history tables. Apply migrations before starting the app in any shared or production environment.
The Docker image uses Node.js 22, compiles the application and migrations in a
builder stage, installs production dependencies only, and runs as a non-root
user on port 3000.
The container entrypoint runs database migrations before starting the API.
Set SKIP_MIGRATIONS=true to bypass migration on startup when a separate
migration job already ran.
Terminal session control is handled by Proxy Control Plane and Session Manager,
not by this backend. The Angular client calls the public /sessions gateway
routes directly after ALB authentication.
The backend also exposes the STS server-inventory contract:
GET /servers/{hostId}
GET /sts/change-requests/{crId}STS should configure SERVER_INVENTORY_URL=http://nest-backend:3000.
The endpoint resolves {hostId} by VM UUID or hostname, returns address data
from virtual_machines, and enriches SSH-only metadata from
SERVER_INVENTORY_STATIC_JSON or the SERVER_INVENTORY_DEFAULT_* env vars.
STS should configure CHANGE_REQUEST_URL=http://nest-backend:3000/sts.
The trusted response includes crId, status, resolved gateway hostIds,
implementationStartAt, implementationEndAt, and allowedRoles. Dates are
serialized as UTC ISO 8601 strings. These values come from the stored CR;
no browser-provided authorization metadata is substituted. An empty VM scope
returns hostIds: [], which STS denies. STS requires an explicit role match for
ordinary actors; Admin bypasses role matching only. Access-tab visibility is
not authorization: STS independently checks approval, window, groups, and scope.
The wire contract is tested in
src/change-request/sts-change-request.controller.spec.ts and consumed by the
Proxy Control Plane cross-repository integration test.
Managers, auditors, security analysts, and admins can read retained SSH command/output audit through:
GET /ddm/session-audit/sessions
GET /ddm/session-audit/records
GET /ddm/session-audit/sessions/{sessionId}/records
GET /ddm/audit/eventsThe backend is only an authenticated facade. It does not proxy terminal traffic, capture command output, store audit bodies, or persist lifecycle events in the webapp database. Configure it with:
SESSION_AUDIT_URL=http://audit-service:8085GET /ddm/audit/events forwards metadata timeline filters to Audit Service
GET /events, including eventType, source, userId, sessionId, hostId,
crId, incidentId, runId, from, to, limit, and cursor. The response
contains sanitized metadata only.
The session-audit.view permission is granted to Manager, Auditor,
SecurityAnalyst, and Admin by default.
The monitoring API reads CloudWatch metrics, alarms, and log groups using the nest-backend pod IAM role (IRSA). Set these env vars on the deployment:
CLOUDWATCH_REGION=ap-southeast-1
CLOUDWATCH_LOG_GROUP=/aws/containerinsights/dendenmushi-cluster-dev/application
CLOUDWATCH_SESSION_LOG_GROUP=/aws/containerinsights/dendenmushi-cluster-dev/application
CLOUDWATCH_NAMESPACE=DenDenMushiAttach a read-only policy to the nest-backend role (for example
dendenmushi-nest-backend-dev):
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "CloudWatchReadMetricsAndAlarms",
"Effect": "Allow",
"Action": [
"cloudwatch:DescribeAlarms",
"cloudwatch:GetMetricStatistics",
"cloudwatch:ListMetrics"
],
"Resource": "*"
},
{
"Sid": "CloudWatchLogsRead",
"Effect": "Allow",
"Action": [
"logs:FilterLogEvents",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams"
],
"Resource": [
"arn:aws:logs:ap-southeast-1:891377133321:log-group:/aws/containerinsights/dendenmushi-cluster-dev/application",
"arn:aws:logs:ap-southeast-1:891377133321:log-group:/aws/containerinsights/dendenmushi-cluster-dev/application:*"
]
}
]
}Adjust the account ID, region, and log group ARNs to match your cluster. Without
these permissions the monitoring page loads but metrics/logs/alarms stay empty
and the API reports awsAuthorized: false.
Successful CloudWatch alarm and metric queries can be cached in Redis to reduce repeated AWS API calls. The cache is disabled by default and is never used for authentication, authorization, logs, alert records, session state, audit data, or terminal traffic.
REDIS_CACHE_ENABLED=false
REDIS_URL=redis://localhost:6379
MONITORING_CACHE_TTL_SECONDS=60When enabled, REDIS_URL is required and the TTL must be a positive integer
number of seconds. Redis connects asynchronously and is not part of readiness. Cache
connection, read, or write failures fall back to CloudWatch, and unsuccessful
CloudWatch responses are not cached. Values larger than 256 KiB are also
skipped.
For a local container demo, start the optional Compose profile:
REDIS_CACHE_ENABLED=true docker compose --profile cache up --buildGET /ddm/monitoring/status reports the cache provider, enabled state,
availability, and TTL. The Kubernetes development environment enables this
cache against its internal, non-persistent Redis service:
REDIS_CACHE_ENABLED=true
REDIS_URL=redis://redis.dendenmushi-webapp.svc.cluster.local:6379
MONITORING_CACHE_TTL_SECONDS=60That Redis pod is a disposable optimization. NetworkPolicy restricts access to Nest Backend, and a restart, suspension, or reschedule may discard all cached values without affecting durable application state.
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.