OPS_NOTES.md

OPS_NOTES.md — a11oy operational notes

Authored for SZL Holdings. Signed-off per repository DCO. Doctrine v7 compliant — no fake-green labels, no marketing superlatives.

---

Base image disclosure — Iron Bank gap

Current base images are vanilla (not Iron Bank-approved):

Stage	Image	Notes
builder	node:22-alpine	Official Docker Hub Node.js Alpine image
runtime	node:22-alpine	Same — minimal Alpine; not hardened

Iron Bank-approved base images (e.g., registry1.dso.mil/ironbank/opensource/nodejs/nodejs22) are not currently used. This is an honest gap, not a configuration oversight.

Iron Bank hardening is a Warhacker hardening item tracked in: szl-holdings/a11oy#164 — chore(hardening): migrate to Iron Bank-approved base images

Until that issue is resolved and the Dockerfile updated, do not label this image as Iron Bank-compliant or DoD IL-approved. Claims of IL-5/IL-6 suitability require the Iron Bank base plus a Platform One Continuous Authority to Operate (cATO) review.

---

Serve mode (HTTP API)

The serve subcommand starts an HTTP API on A11OY_PORT (default 8080). It is implemented by packages/receipt-substrate/src/server.ts (serve-BE PR, pending merge). Until that PR lands, the entrypoint exits with a clear error if serve is invoked and the server module is absent — no silent hang, no fake-green probe response.

Probes:

• GET /healthz — liveness: returns {"status":"ok"} once the process is up.
• GET /readyz — readiness: returns {"status":"ready"} after full initialisation.

---

Container image registry

Production images: ghcr.io/szl-holdings/a11oy

Tagging strategy:

• sha-<7-hex> — every push to main (continuous delivery tag).
• <semver> + latest — published GitHub Releases only.
• pr-<7-hex> — pull-request builds (local daemon only; not pushed to GHCR).

---

SLSA posture

Current level: SLSA L1 (honest) — source + build provenance documented via slsa-provenance.yml. L2/L3 require Sigstore + isolated builders (roadmap item).

---

Known gaps (tracked)

Gap	Tracking
Iron Bank base images	#164
serve subcommand server module	serve-BE PR (pending)
SPA routes wired to real data	SPA-repair PR (pending)
SLSA L2/L3 isolated builder	ROADMAP.md