Skip to content

CONFIGURATION.md

Latest commit

 

History

History
138 lines (103 loc) · 6.54 KB

CONFIGURATION.md

File metadata and controls

138 lines (103 loc) · 6.54 KB

Configuration Reference

This runtime is configured via environment variables.

Core service identity

Variable Default Purpose
PORT 8080 HTTP listen port.
SERVICE_NAME commandlayer-runtime Name exposed in index/health metadata.
SERVICE_VERSION 1.0.0 Service version exposed in responses.
API_VERSION 1.0.0 Version segment used in verb route shape.
CANONICAL_BASE_URL https://runtime.commandlayer.org Base URL metadata in index/health payloads.

Enabled verbs

Variable Default
ENABLED_VERBS fetch,describe,format,clean,parse,summarize,convert,explain,analyze,classify

Comma-separated list of enabled handlers. Disabled verbs return 404.

Signing + verifier identity

Variable Default Purpose
RECEIPT_SIGNER_ID runtime (or ENS_NAME when set) Receipt proof signer identifier.
RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64 empty Required for signing receipts. Base64 of PEM private key.
RECEIPT_SIGNING_PUBLIC_KEY_B64 empty Preferred verifier key input: base64 of raw 32-byte Ed25519 public key.
RECEIPT_SIGNING_PUBLIC_KEY_PEM empty Legacy verifier key input (plain PEM text).
RECEIPT_SIGNING_PUBLIC_KEY_PEM_B64 empty Legacy verifier key input (base64-encoded PEM); lower priority than RECEIPT_SIGNING_PUBLIC_KEY_B64.
ENS_NAME empty Optional identity alias fallback.

Env precedence and normalization

The runtime resolves the first non-empty value from each list:

  • Private key: CL_RECEIPT_SIGNING_PRIVATE_KEY_PEM → RECEIPT_SIGNING_PRIVATE_KEY_PEM → CL_RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64 → RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64 → CL_RECEIPT_SIGNING_PRIVATE_KEY_B64 → RECEIPT_SIGNING_PRIVATE_KEY_B64 → CL_RECEIPT_SIGNING_PRIVATE_KEY_PEM_FILE.
  • Public key: CL_RECEIPT_SIGNING_PUBLIC_KEY_B64 → RECEIPT_SIGNING_PUBLIC_KEY_B64 → CL_RECEIPT_SIGNING_PUBLIC_KEY_PEM → RECEIPT_SIGNING_PUBLIC_KEY_PEM → CL_RECEIPT_SIGNING_PUBLIC_KEY_PEM_B64 → RECEIPT_SIGNING_PUBLIC_KEY_PEM_B64 → CL_RECEIPT_SIGNING_PUBLIC_KEY_PEM_FILE.
  • Signer id: CL_RECEIPT_SIGNER_ID → RECEIPT_SIGNER_ID.

RECEIPT_SIGNING_PUBLIC_KEY_B64 must decode to exactly 32 bytes.

ENS-based verification

Variable Default Purpose
ETH_RPC_URL empty Ethereum RPC endpoint for ENS resolver lookups.
VERIFIER_ENS_NAME ENS_NAME / RECEIPT_SIGNER_ID fallback ENS name queried for TXT pubkey value.
ENS_SIGNER_TEXT_KEY cl.receipt.signer ENS TXT key on verifier name that delegates to signer ENS name.
ENS_SIG_PUB_TEXT_KEY cl.sig.pub ENS TXT key on signer name containing ed25519:<base64> public key.
ENS_SIG_KID_TEXT_KEY cl.sig.kid ENS TXT key on signer name containing key identifier.
ENS_SIG_CANONICAL_KEY cl.sig.canonical ENS TXT key on signer name containing canonical mode (e.g. json.sorted_keys.v1).

/verify?ens=1 verifies using ENS cl.sig.pub key material. /verify?ens=1&strict_kid=1 additionally enforces cl.sig.kid equality when present.

Schema fetching + validation budgets

Variable Default Purpose
SCHEMA_HOST https://www.commandlayer.org Schema host prefix used to compute receipt schema URLs.
SCHEMA_FETCH_TIMEOUT_MS 15000 Timeout per schema document fetch.
SCHEMA_VALIDATE_BUDGET_MS 15000 Budget for async schema compilation.
VERIFY_SCHEMA_CACHED_ONLY 1 If 1, /verify?schema=1 only uses warm validators and returns 202 on cold cache.
REQUEST_SCHEMA_VALIDATION 0 If 1, validate verb request payloads against published request schemas. Returns 503 if schemas are unavailable.

Cache controls

Variable Default
MAX_JSON_CACHE_ENTRIES 256
JSON_CACHE_TTL_MS 600000
MAX_VALIDATOR_CACHE_ENTRIES 128
VALIDATOR_CACHE_TTL_MS 1800000

Request safety limits

Variable Default Purpose
SERVER_MAX_HANDLER_MS 12000 Hard upper bound for verb execution timeout.
VERIFY_MAX_MS 30000 Upper bound for /verify request processing.

fetch hardening

Variable Default Purpose
FETCH_TIMEOUT_MS 8000 Timeout for outbound fetch HTTP request.
FETCH_MAX_BYTES 262144 Max bytes read from outbound response body.
ENABLE_SSRF_GUARD 1 Enables DNS/IP/local-network SSRF checks.
ALLOW_FETCH_HOSTS empty Optional CSV domain allowlist (example.com,api.example.com).

CORS

Variable Default Purpose
CORS_ALLOW_ORIGINS empty Comma-separated list of allowed origins. Empty = deny browser-origin requests. Use * to allow all (not recommended in production).
CORS_ALLOW_HEADERS Content-Type, Authorization Allowed request headers.
CORS_ALLOW_METHODS GET,POST,OPTIONS Allowed HTTP methods.

Debug routes

Variable Default Purpose
DEBUG_ROUTES_ENABLED 0 If 1, enables /debug/* endpoints. Disabled by default in production.
DEBUG_BEARER_TOKEN empty If set, requires Authorization: Bearer <token> on all debug routes.

Request logging

Variable Default Purpose
LOG_REQUESTS 1 If 1, emits structured JSON log lines to stdout for every request.

Rate limiting

Variable Default Purpose
RATE_LIMIT_ENABLED 0 If 1, enables per-IP rate limiting.
RATE_LIMIT_MAX 120 Max requests per window per IP.
RATE_LIMIT_WINDOW_MS 60000 Sliding window duration in milliseconds.

Schema prewarm behavior

Variable Default Purpose
PREWARM_MAX_VERBS 25 Max verbs accepted in one /debug/prewarm call.
PREWARM_TOTAL_BUDGET_MS 12000 Total worker runtime budget.
PREWARM_PER_VERB_BUDGET_MS 5000 Max warm budget per verb.

Recommended production baseline

  • Set explicit signing keys and verify signer_ok=true and verifier_ok=true on /health.
  • Keep VERIFY_SCHEMA_CACHED_ONLY=1 for edge stability.
  • Set CORS_ALLOW_ORIGINS to specific origins (never * in production).
  • Set DEBUG_ROUTES_ENABLED=0 (default) or protect with DEBUG_BEARER_TOKEN.
  • Set RATE_LIMIT_ENABLED=1 with appropriate limits for your traffic profile.
  • Restrict egress using both network policy and ALLOW_FETCH_HOSTS where possible.
  • Tune FETCH_MAX_BYTES and timeout budgets based on expected payload sizes.
  • Poll /debug/validators after deploy and prewarm critical verbs.