Skip to main content
This page covers security beyond input validation: network security, authentication enforcement, logging hygiene, container security, and deployment architecture.

​
Authentication

Auth is per-tool — there is no global middleware that applies automatically. You must opt in for every tool that handles sensitive data.

​
Enforce auth on every sensitive tool

Auth is per-tool. There is no global middleware. Every tool accessing sensitive data must have an auth block: 
auth:
  plugin: api_key
  policy:
    value: '{{ env.ROUTE_API_KEY }}'
Audit checklist:
  • Review all app/tools/*/config.terse files for missing auth blocks.
  • allow_all should only appear on health checks and intentionally public tools.
  • hyperterse validate confirms structural correctness; manually verify auth presence.

​
Rotate credentials

API keys and tokens are resolved at startup. Rotation requires a restart. For zero-downtime rotation:
  1. Update the secret in your secrets manager.
  2. Trigger a rolling restart.
  3. Verify the old key is rejected after all instances restart.

​
Network security

Hyperterse listens on plain HTTP. Encryption and access control belong to the infrastructure layer in front of it.

​
TLS termination

Hyperterse does not terminate TLS natively. Deploy behind a reverse proxy:
  • Nginx — proxy_pass to http://localhost:8080.
  • Caddy — Automatic HTTPS with Let’s Encrypt.
  • AWS ALB / GCP LB — Managed TLS.
  • Kubernetes Ingress — cert-manager or cloud provider integration.

​
CORS

The runtime applies permissive CORS by default. For production:
  1. Deploy behind a reverse proxy.
  2. Configure restrictive CORS at the proxy.
  3. Restrict the runtime’s built-in CORS to your domain.

​
Network segmentation

  • Place the runtime in a private network segment.
  • Restrict inbound traffic to the reverse proxy only.
  • Restrict outbound to database hosts and external APIs used by handlers.
  • Block direct internet access to the runtime port.

​
Logging hygiene

Logs are the first place an attacker looks after a breach. Keep them clean.

​
Log level

Set production to 2 (warn) or 3 (info): 
server:
  log_level: 2
Debug-level logging may include substituted statements, input values, and execution details.

​
Log routing

Use --log-file for file-based collection by aggregation systems. Review handler scripts for accidental credential logging via console.log.

​
Container security

A smaller container means fewer CVEs and a faster patch cycle.

​
Minimal base image

FROM scratch
COPY dist/hyperterse /hyperterse
COPY dist/model.bin /model.bin
COPY dist/build/ /build/
ENTRYPOINT ["/hyperterse", "serve"]
Or alpine for shell access: 
FROM alpine:3.19
RUN apk add --no-cache ca-certificates
RUN adduser -D -u 1001 hyperterse
COPY dist/ /app/
WORKDIR /app
USER hyperterse
EXPOSE 8080
ENTRYPOINT ["./hyperterse", "serve"]

​
Non-root execution

RUN adduser -D -u 1001 hyperterse
USER hyperterse

​
Read-only filesystem

Hyperterse does not write to disk at runtime (cache is in-memory): 
securityContext:
  readOnlyRootFilesystem: true

​
Secrets management

Credentials must never appear in configuration files, logs, or version control.

​
Environment variables

All credentials must come from environment variables: 
connection_string: '{{ env.DATABASE_URL }}'

​
Kubernetes secrets

env:
  - name: DATABASE_URL
    valueFrom:
      secretKeyRef:
        name: db-credentials
        key: url

​
External secrets managers

Use a sidecar or init container to fetch from AWS Secrets Manager, Vault, etc. Signal restarts on rotation. Do not mount secrets as files — Hyperterse reads environment variables.

​
Rate limiting

No built-in rate limiting. Implement at the infrastructure layer:
  • Reverse proxy — Nginx limit_req, Caddy rate_limit, Envoy rate limit filter.
  • API gateway — AWS API Gateway, Kong, Traefik.
  • Cloud provider — Cloud Armor, AWS WAF, Azure Front Door.
Apply to /mcp, which handles all tool invocations.

​
Health checks

Expose lightweight probes so your orchestrator can detect and restart unhealthy instances.

​
Liveness

curl http://localhost:8080/heartbeat
Confirms the HTTP server is accepting connections. Does not check connector health.

​
Readiness

For full-system readiness, create a tool that queries each adapter: 
# app/tools/readiness/config.terse
description: 'Readiness check'
use: primary-db
statement: 'SELECT 1'
auth:
  plugin: allow_all

​
Deployment checklist

  • All sensitive tools have auth blocks.
  • No allow_all on tools accessing sensitive data.
  • Credentials via environment variables, not plaintext.
  • .env excluded from version control.
  • TLS at reverse proxy or load balancer.
  • CORS restricted to application domain.
  • Log level at 2 or 3.
  • Container runs as non-root.
  • Runtime port not exposed to public internet.
  • Rate limiting at infrastructure layer.
  • Health and readiness probes configured.
  • Observability enabled.