Skip to main content

Configuration

jhf-lantern Configuration

Lantern configuration is intentionally narrow on the current route-aware mixed shell. Local preview keeps fixture mode as the default, while the deployed public Lantern host must prefer live owner-backed readbacks.

Local UI Mode​

  • VITE_LANTERN_DATA_MODE=fixture is the default posture.
  • Fixture mode must remain visibly marked so sample data is not treated as production readback.

Deployed UI Mode​

  • https://<internal-runtime-redacted> must default to live owner-backed readbacks.
  • Fixture/demo content may remain available only as an explicit development fallback and must never be the default deployed experience.
  • the deployed UI image is built with VITE_LANTERN_DATA_MODE=live
  • the deployed UI uses same-origin /api proxying to reach lantern-bff instead of requiring browser-local mode switches

Live UI Mode​

Use live mode only for contract-backed local verification:

VITE_LANTERN_DATA_MODE=live
VITE_LANTERN_API_BASE_URL=`api/v`1/lantern

BFF Browser Origin Allowlist​

  • LANTERN_ALLOWED_ORIGINS may override the browser-origin allowlist for the repo-owned BFF CORS posture.
  • The value is a comma-separated list of absolute origins.
  • The default allowlist keeps the documented Lantern surfaces working without wildcarding browser access:
    • https://<internal-runtime-redacted>
    • http://<owner-runtime-host>:18120
    • http://<internal-runtime-redacted>:4173
    • http://<internal-runtime-redacted>:5173
  • Unknown origins remain fail-closed for browser preflight requests.

Live Materialization Auth Input​

  • scripts/materialize_live_runtime.sh is the repo-owned live materializer for the owner-supplied runtime host.
  • It must resolve runtime auth from exactly one of:
    • LANTERN_RUNTIME_AUTH_ENV
    • repo-root .env
    • ~/.config/helpifyr/runtime-secrets/lantern-runtime-auth.env
  • When LANTERN_RUNTIME_AUTH_ENV is not set, an incomplete candidate is skipped and the next candidate is tried. An explicitly selected file is never silently replaced; missing or empty required names fail closed.
  • The materializer must fail closed before docker compose up -d --build if any of these auth-bound upstream tokens are missing or empty:
    • FABRIC_API_TOKEN
    • WARP_API_TOKEN
    • PATTERN_API_TOKEN
  • This prevents clean worktrees from silently materializing a runtime that can only return restricted / future_contract for guarded owner-backed readbacks.

Host172 BFF Service Discovery​

  • In the Host172 DEV Compose project, lantern-bff reaches Fabric through the attached jhf-fabric_net network at http://jhf-fabric-api:8080.
  • Fabric-backed runtime, access-context, Universal Connections, skill-pack, and Plan Studio routes must use that service name; the host-published Fabric port 28080 is not an in-container default.
  • Shuttle mailbox health is read through the attached Shuttle owner network at http://jhf-shuttle-mailbox-adapter:8080/healthz; a loopback URL and a host-published fallback are invalid from inside the BFF container.
  • These are non-secret routing values. Auth tokens remain in the operator-managed runtime secret file and are never committed to Compose or documentation.
  • The operator-managed runtime secret file must also contain the Dev-only LANTERN_UNIVERSAL_CONNECTIONS_ATTESTATION_CONSUMER_TOKEN; the materializer fails closed before rebuilding if it is absent. Resolve it only from the exact Heddle Dev bootstrap item, never from a browser or human credential.

BFF Request Guard​

  • LANTERN_RATE_LIMIT_WINDOW_MS configures the in-memory request window for /api/v1/lantern/* readback and admitted write-through routes.
  • LANTERN_RATE_LIMIT_MAX_REQUESTS caps per-client requests per route inside that window.
  • LANTERN_MAX_QUERY_CHARS bounds query-string length before the BFF reaches upstream readback handlers.
  • The default posture is intentionally conservative:
    • LANTERN_RATE_LIMIT_WINDOW_MS=10000
    • LANTERN_RATE_LIMIT_MAX_REQUESTS=20
    • LANTERN_MAX_QUERY_CHARS=512
  • Exceeding the rate window returns 429 with Retry-After.
  • Oversized query strings fail closed with 414 and do not hit upstream readback code.

Safety Rules​

  • no secrets in committed files
  • no write-capable Phase-0 endpoints
  • missing upstream truth must render as restricted, future, stale, or unavailable instead of green
  • Fabric and owner repos remain the source of truth for policy and domain state

Verify​

python scripts/verify_module_features.py
python scripts/verify_route_aware_runtime.py

License: AGPLv3 Project: https://helpifyr.com

Host172 queue owner readbacks​

The BFF queue surface resolves owner services over their Docker networks. FABRIC_METRICS_URL uses jhf-fabric-api:8080, while SHUTTLE_MAILBOX_HEALTH_URL uses jhf-shuttle-mailbox-adapter:8080 on the external jhf-shuttle-self-stack_default network. Host-published loopback ports are intentionally not valid from the BFF container and are rejected by the route-aware runtime verifier.