Skip to content

CONFIGURATION.md

Latest commit

 

History

History
216 lines (156 loc) · 8.59 KB

CONFIGURATION.md

File metadata and controls

216 lines (156 loc) · 8.59 KB

Configuration Reference

This file documents environment variables that are actually read by server.mjs today.

For public paste-and-verify receipt verification, use VerifyAgent: https://github.com/commandlayer/verifyagent

This runtime repository is focused on execution + signed receipt production, not hosting a public verifier UI/demo.

Core listen and service metadata

Variable Default Notes
HOST 0.0.0.0 HTTP bind host.
PORT 8080 HTTP listen port.
SERVICE_NAME commandlayer-runtime Returned by GET / and GET /health.
SERVICE_VERSION 1.1.0 Returned by GET / and GET /health.
API_VERSION 1.1.0 Version segment used when mounting verb routes.
CANONICAL_BASE_URL https://runtime.commandlayer.org Returned by GET / and GET /health.
RAILWAY_SERVICE_NAME unset Used only in runtime trace/debug metadata; does not rename the service fields above.

Enabled verbs

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

The server mounts POST /<verb>/v1.1.0 only for verbs in this list. If a listed verb has no handler implementation, requests still return 404.

Signing identity and key material

Canonical/current names

These are the current names shown in .env.example and accepted directly by the server:

Variable Default Behavior
RECEIPT_SIGNER_ID unset Signer identifier written into receipt.metadata.proof.signer_id. Required unless a supported alias is set.
RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64 unset Base64-encoded PKCS#8 Ed25519 private key PEM. Required unless a supported alias is set or DEV_AUTO_KEYS=1.
RECEIPT_SIGNING_PUBLIC_KEY_B64 unset Base64-encoded raw 32-byte Ed25519 public key. Current preferred public-key input.

Accepted aliases and precedence

The server reads the first non-empty value from these lists.

Signer identifier

  1. CL_RECEIPT_SIGNER_ID
  2. RECEIPT_SIGNER_ID
  3. CL_RECEIPT_SIGNER

CL_RECEIPT_SIGNER is still accepted, including by scripts/dev.sh, but it is not the primary name in .env.example.

Private key

  1. CL_RECEIPT_SIGNING_PRIVATE_KEY_PEM
  2. RECEIPT_SIGNING_PRIVATE_KEY_PEM
  3. CL_RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64
  4. RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64
  5. CL_RECEIPT_SIGNING_PRIVATE_KEY_B64
  6. RECEIPT_SIGNING_PRIVATE_KEY_B64
  7. CL_RECEIPT_SIGNING_PRIVATE_KEY_PEM_FILE
  8. CL_PRIVATE_KEY_PEM
  9. CL_PRIVATE_KEY_PEM_B64

Behavior:

  • *_PEM values are parsed as PEM text.
  • *_PEM_FILE is read from disk.
  • the remaining *_B64 forms are base64-decoded and then parsed as PEM text.
  • the private key must be PKCS#8 Ed25519 PEM.

Public key

  1. CL_RECEIPT_SIGNING_PUBLIC_KEY_B64
  2. RECEIPT_SIGNING_PUBLIC_KEY_B64
  3. CL_RECEIPT_SIGNING_PUBLIC_KEY_PEM
  4. RECEIPT_SIGNING_PUBLIC_KEY_PEM
  5. CL_RECEIPT_SIGNING_PUBLIC_KEY_PEM_B64
  6. RECEIPT_SIGNING_PUBLIC_KEY_PEM_B64
  7. CL_RECEIPT_SIGNING_PUBLIC_KEY_PEM_FILE
  8. CL_PUBLIC_KEY_B64
  9. RECEIPT_SIGNING_PUBLIC_KEY_RAW32_B64

Behavior:

  • *_PUBLIC_KEY_B64 and *_RAW32_B64 are treated as raw 32-byte Ed25519 public keys.
  • *_PEM, *_PEM_FILE, and *_PEM_B64 are treated as PEM public keys.
  • the server converts accepted public-key inputs to SPKI PEM internally for verification.

If a commons verb request omits execution, the runtime fabricates default receipt execution values with the live API version:

  • entry: "https://runtime.commandlayer.org/execute"
  • verb: "<verb>"
  • version: "1.1.0"
  • class: "commons"

Commercial/payment-aware behavior belongs in the separate commercial runtime and is intentionally out of scope here.

Startup behavior

  • If signing configuration is missing or invalid and DEV_AUTO_KEYS is not enabled, the process exits at boot.
  • If DEV_AUTO_KEYS=1 and valid key material is not supplied, the server generates an in-memory Ed25519 keypair and logs the generated material to stderr/stdout.
  • kid is derived from the active public key fingerprint. It is not read from environment variables.
  • canonical_id is fixed to json.sorted_keys.v1 from @commandlayer/runtime-core and is not overridden by environment variables.

Legacy names that are present but not used for production signing behavior

These names appear in tests or debug output, but server.mjs does not consume them to control live signing behavior:

  • CL_KEY_ID
  • CL_CANONICAL_ID

ENS verification

Variable Default Behavior
ETH_RPC_URL empty Ethereum RPC endpoint used for live ENS lookups. Required for real ens=1 verification unless ENS_MOCK_TXT_JSON is set for tests.
ENS_SIG_PUB_KEY cl.sig.pub TXT key used to fetch the Ed25519 public key on the signer ENS name.
ENS_SIG_KID_KEY cl.sig.kid TXT key used to fetch the optional kid value on the signer ENS name.
ENS_SIG_CANONICAL_KEY cl.sig.canonical TXT key used to fetch canonical mode on the signer ENS name.
ENS_MOCK_TXT_JSON unset Test/debug shortcut that bypasses live RPC lookups and returns mock TXT values.

Important current behavior:

  • /verify?ens=1 resolves TXT records directly on the signer ENS name from the receipt proof, or runtimeConfig.signerId if the proof is missing a signer id.
  • VERIFIER_ENS_NAME is not read.
  • ENS_SIG_PUB_TEXT_KEY and ENS_SIG_KID_TEXT_KEY are not read; the implemented names are ENS_SIG_PUB_KEY and ENS_SIG_KID_KEY.
  • ENS_SIGNER_TEXT_KEY is not read.
  • ENS_SIG_KID_KEY is optional for normal ens=1 verification and is only enforced when strict_kid=1 is used and the TXT value exists.

Schema fetch and verification controls

Variable Default Behavior
SCHEMA_HOST https://www.commandlayer.org Base URL used to compute receipt schema URLs.
SCHEMA_FETCH_TIMEOUT_MS 15000 Timeout for schema document fetches.
SCHEMA_VALIDATE_BUDGET_MS 15000 Timeout budget for async AJV schema compilation.
VERIFY_SCHEMA_CACHED_ONLY 1 If 1, /verify?schema=1 uses only precompiled validators and returns 202 on a cold cache.
VERIFY_MAX_MS 30000 Overall timeout budget for /verify.

SCHEMA_HOST is used to construct v1.1.0 receipt schema URLs during /verify?schema=1.

REQUEST_SCHEMA_VALIDATION is not implemented by server.mjs.

Schema and validator caches

Variable Default
MAX_JSON_CACHE_ENTRIES 256
JSON_CACHE_TTL_MS 600000
MAX_VALIDATOR_CACHE_ENTRIES 128
VALIDATOR_CACHE_TTL_MS 1800000
PREWARM_MAX_VERBS 25
PREWARM_TOTAL_BUDGET_MS 12000
PREWARM_PER_VERB_BUDGET_MS 5000

These settings control the in-memory schema JSON cache, compiled validator cache, and the debug prewarm worker.

Request execution and fetch hardening

Variable Default Behavior
SERVER_MAX_HANDLER_MS 12000 Server-side cap on verb execution time.
FETCH_TIMEOUT_MS 8000 Timeout for outbound fetch requests made by the fetch verb.
FETCH_MAX_BYTES 262144 Maximum response bytes read by the fetch verb.
ENABLE_SSRF_GUARD 1 Enables the built-in SSRF guard for the fetch verb.
ALLOW_FETCH_HOSTS empty Optional comma-separated allowlist for fetch hosts.

Current SSRF guard behavior blocks:

  • non-HTTP(S) schemes
  • localhost and *.localhost
  • 169.254.169.254
  • IPv4 private/local ranges
  • all IPv6 literals
  • hostnames whose A records resolve to blocked IPv4 addresses

Debug route gating

Variable Default Behavior
ENABLE_DEBUG 0 Enables debug routes only when set to 1.
DEBUG_TOKEN empty Required token for debug routes. If missing, debug routes still return 404.

DEBUG_ROUTES_ENABLED and DEBUG_BEARER_TOKEN are not read by the current server.

CORS

The current server does not expose environment-based CORS configuration.

It always returns:

  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Headers: Content-Type, Authorization, X-Debug-Token
  • Access-Control-Allow-Methods: GET,POST,OPTIONS

CORS_ALLOW_ORIGINS, CORS_ALLOW_HEADERS, and CORS_ALLOW_METHODS are not implemented.

Not implemented in server.mjs

These names appear in older docs or conventions but are not read by the live server:

  • VERIFIER_ENS_NAME
  • ENS_SIGNER_TEXT_KEY
  • ENS_SIG_PUB_TEXT_KEY
  • ENS_SIG_KID_TEXT_KEY
  • CORS_ALLOW_ORIGINS
  • CORS_ALLOW_HEADERS
  • CORS_ALLOW_METHODS
  • RATE_LIMIT_ENABLED
  • RATE_LIMIT_MAX
  • RATE_LIMIT_WINDOW_MS
  • REQUEST_SCHEMA_VALIDATION
  • LOG_REQUESTS
  • RECEIPT_SIGNING_PUBLIC_KEY