fix(container): APP_HOST defaults to 127.0.0.1 (HCG tier-2 E1 prereq) (#132)

## Summary

Tightens three sites that feed the Zig adapter binary's `--host` flag in
production deployments, materialising the ADR-0004 §1 invariant that
BoJ's back-side bind is not externally routable when fronted by
`http-capability-gateway` (HCG tier-2).

This is **action item #7** from the [Phase E consumer-side
audit](hyperpolymath/standards#100 (comment)).
The scope expanded during implementation from one site (the audit named
`stapeln.toml`) to three sites — `entrypoint.sh` and `compose.prod.yaml`
had the same `[::]` default that the audit missed. All three sites feed
into the same Zig-adapter `--host` flag, so they need to flip together
for the change to actually take effect at runtime.

Companion PR to **#130** (Cowboy bind tightening in the Elixir path) and
**#131** (k8s Service ClusterIP). Together the three give defence in
depth: Elixir Cowboy binds loopback **AND** Zig adapter binds loopback
**AND** k8s Service is internal-only.

`Refs hyperpolymath/standards#100` (NOT Closes — joint-close is
owner-only).
`Refs hyperpolymath/standards#91`.

## What's in

| File | Change |
|---|---|
| `stapeln.toml` `[targets.production]` | `APP_HOST = "[::]"` →
`APP_HOST = "127.0.0.1"` + comment block. |
| `container/entrypoint.sh` line 40 (log) + line 140 (`exec` invocation)
| `${APP_HOST:-[::]}` → `${APP_HOST:-127.0.0.1}` + comment at exec line.
|
| `container/compose.prod.yaml` `services.boj-rest.environment` |
`APP_HOST: "[::]"` → `APP_HOST: "127.0.0.1"` + comment block. |
| `CHANGELOG.md` | New `### Changed` entry under `[Unreleased]`. |

## Override path for legacy/standalone use

Deployments without HCG in front: set `APP_HOST=0.0.0.0` (IPv4
all-interfaces) or `APP_HOST=::` (IPv6 all-interfaces) in your
deployment config. The in-repo defaults remain loopback.

## Audit-residue follow-ups deliberately NOT in this PR

- `container/Containerfile` line 125: `ENV PHX_HOST=0.0.0.0` is
**vestigial**. Nothing in the codebase reads `PHX_HOST` (verified by
`grep -rn "PHX_HOST\|phx_host" --include="*.ex" ...` returning empty).
Leftover from a former Phoenix incarnation. Safe to leave alone; can be
removed in a hygiene PR if desired.
- Unifying `APP_HOST` (Zig adapter) and `BOJ_BIND_IP` (Elixir Cowboy
from #130) into one envelope is broader scope. The divergence exists
because they feed different binaries built by different toolchains. If
it proves annoying in operation, file a separate issue.

## Why DRAFT

Same reason as #131 — this is a behaviour change for anyone running the
stapeln-built production container or `compose.prod.yaml` as-is and
relying on the default `[::]` for external access. Owner gates merge on
confirming no such reliance, or on coordinating with anyone who needs
the migration path (HCG-in-front, or explicit `APP_HOST=0.0.0.0`
override).

## Test plan

- [x] `stapeln.toml` parses as valid TOML (syntax preserved).
- [x] `container/entrypoint.sh` runs through `sh -n` without syntax
error (no syntax change, just literal substitution).
- [x] `container/compose.prod.yaml` parses as valid YAML.
- [ ] CI green — governance / hypatia / a2ml / k9 / dogfooding all pass.
- [ ] Owner: confirm no live deployment depends on `[::]` default; flip
from DRAFT to ready.
- [ ] Post-merge manual: a stapeln-built production container, with no
env override, refuses connections from non-loopback peers.

## Risk

**Low for the codebase, medium for ops.** No Elixir / Zig / Idris2 /
cartridge logic touched; CI should not show any regressions. Ops risk:
anyone whose runbook assumes the container exposes BoJ on all interfaces
by default will need to set `APP_HOST=0.0.0.0` explicitly. Reasonable
default for the Phase E posture; documented override path.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

CHANGELOG.md

@@ -56,6 +56,19 @@ All notable changes to Bundle of Joy Server are documented here.
   [`hyperpolymath/standards#100`](https://github.com/hyperpolymath/standards/issues/100),
   [`#91`](https://github.com/hyperpolymath/standards/issues/91).
 
+- **Container `APP_HOST` default is now `127.0.0.1`** (was: `"[::]"`
+  IPv6 all-interfaces). Tightens three sites that feed the Zig adapter
+  binary's `--host` flag: `stapeln.toml [targets.production]`,
+  `container/entrypoint.sh`, and `container/compose.prod.yaml`. Same
+  Phase E posture as the Cowboy bind change in the Elixir path: BoJ
+  binds loopback by default when fronted by `http-capability-gateway`
+  (HCG tier-2). Legacy/standalone deployments without HCG in front
+  should override `APP_HOST=0.0.0.0` (IPv4 all-interfaces) or
+  `APP_HOST=::` (IPv6 all-interfaces) in their deployment config.
+  Phase E rollout-runbook §1.4 prereq #7. Refs
+  [`hyperpolymath/standards#100`](https://github.com/hyperpolymath/standards/issues/100),
+  [`#91`](https://github.com/hyperpolymath/standards/issues/91).
+
 ### Added
 
 - **ADR-0014 — cross-cartridge composition safety (RFC)** — frames the

container/compose.prod.yaml

@@ -40,8 +40,12 @@ services:
     volumes:
       - boj-node-data:/data:Z
     environment:
-      # Server binding
-      APP_HOST: "[::]"
+      # Server binding — loopback by default per ADR-0004 §1 (BoJ is
+      # fronted by http-capability-gateway tier-2 and not externally
+      # routable). Override APP_HOST=0.0.0.0 or APP_HOST=:: for
+      # legacy/standalone deployments without HCG in front.
+      # See docs/integration/hcg-tier2-rollout-runbook.md §1.4 prereq #7.
+      APP_HOST: "127.0.0.1"
       APP_PORT: "7700"
       APP_DATA_DIR: "/data"
       APP_LOG_FORMAT: "json"

container/entrypoint.sh

@@ -37,7 +37,7 @@ done
 export LD_LIBRARY_PATH="${LD_LIBRARY_PATH:+${LD_LIBRARY_PATH}:}${CART_LIBS}"
 
 echo "Starting boj-server..."
-echo "  Host: ${APP_HOST:-[::]}"
+echo "  Host: ${APP_HOST:-127.0.0.1}"
 echo "  Port: ${APP_PORT:-7700}"
 echo "  Data: ${APP_DATA_DIR:-/data}"
 echo "  Log:  ${APP_LOG_FORMAT:-json}"
@@ -137,4 +137,8 @@ bootstrap_federation &
 # Replace the entrypoint shell with the application process so that
 # signals are delivered directly and PID 1 is the application.
 
-exec /app/boj-server serve --host "${APP_HOST:-[::]}" --port "${REST_PORT}"
+# Default to 127.0.0.1 (loopback) per ADR-0004 §1 — BoJ is fronted by
+# http-capability-gateway (HCG tier-2) and is not externally routable
+# in canonical deployments. Override APP_HOST for legacy/standalone use.
+# See docs/integration/hcg-tier2-rollout-runbook.md §1.4 prereq #7.
+exec /app/boj-server serve --host "${APP_HOST:-127.0.0.1}" --port "${REST_PORT}"

stapeln.toml

@@ -97,7 +97,14 @@ env = { LOG_LEVEL = "debug", BOJ_DEV_MODE = "true" }
 
 [targets.production]
 layers = ["runtime"]
-env = { LOG_LEVEL = "info", APP_HOST = "[::]", APP_PORT = "7700" }
+# APP_HOST = "127.0.0.1" (was "[::]") — code-enforces the ADR-0004 §1
+# invariant that BoJ's back-side bind is not externally routable in
+# deployments fronted by http-capability-gateway (HCG tier-2). See
+# docs/integration/hcg-tier2-rollout-runbook.md §1.4 prereq #7.
+# Legacy/standalone deployments without HCG in front should override
+# APP_HOST=0.0.0.0 (IPv4 all-interfaces) or APP_HOST=:: (IPv6
+# all-interfaces) in their deployment configuration.
+env = { LOG_LEVEL = "info", APP_HOST = "127.0.0.1", APP_PORT = "7700" }
 
 [targets.test]
 layers = ["base", "zig-toolchain", "ffi-build", "adapter-build"]