amadan
docs: record the #277 cert-gate ruling in the spec (2026-08-24)
Part 2 described the challenge read-through and the order gate as bounded by this box's registry (Allowed). A dated amendment, appended rather than rewriting the sentence, records the widening: all three cert-adjacent gates now admit exact home-map names alongside Allowed, with the mechanism of #277 traced from DNS through the backhaul to the burned LE budget, the one-label wildcard rule stated as still excluded (PR #180's bound, with the three refusal tests named), the fail-closed residual (DNS at neither home nor issuer stays certless at zero LE spend) and the roll-every-edge-before-arming ordering. Also corrects the status block's name for the ALPN bound test, which the widening renamed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 file changed,
+64
−1
docs/superpowers/specs/2026-08-20-multi-region-ingress-design.md+64 −1
diff --git a/docs/superpowers/specs/2026-08-20-multi-region-ingress-design.md b/docs/superpowers/specs/2026-08-20-multi-region-ingress-design.md| index f44461f39..4d3425d0b 100644 |
| --- a/docs/superpowers/specs/2026-08-20-multi-region-ingress-design.md |
| +++ b/docs/superpowers/specs/2026-08-20-multi-region-ingress-design.md |
| @@ -126,7 +126,7 @@ the one box always holds the housekeeper lease, so behaviour is identical |
| to today. Residual: tls-alpn-01 (autocert's PREFERRED challenge type) is |
| NOT end-to-end proven — only http-01 is; tls-alpn-01 has real unit |
| coverage (`TestMirrorAnswersAnotherEdgesALPNValidation`, |
| -`TestMirrorALPNReadThroughOnlyForServedHosts`, |
| +`TestMirrorALPNReadThroughOnlyForServedOrRemoteHomedHosts`, |
| `TestMirrorNeverServesATokenCertToAnOrdinaryHello`, |
| `TestALPNTokenCertIsReadLiveNotFromTheSnapshot` in |
| `internal/edge/certsync_test.go`) but not the e2e proof — tracked as a |
| @@ -168,6 +168,69 @@ prefix already listed and read on every mirror poll — and is left for a |
| later sweep rather than solved here; tracked as issue #243 (filed). The |
| issuer remains the only box that talks to the CA. |
| +**Amendment (2026-08-24, #277): the three cert-adjacent host gates admit |
| +exact home-map names, not only this box's own routes.** As shipped, the |
| +HTTP-01 challenge read-through, the tls-alpn-01 read-through and |
| +`issuerHostPolicy`'s order gate all bounded on `Edge.Allowed` — this |
| +box's registry. That was the right anti-stranger bound for a world where |
| +every box's registry named every host it could be validated for, and |
| +home-boxed routes falsified it the moment a second edge armed: DNS for |
| +such a route may point at ANY edge, that edge backhauls to the home box |
| +with the real SNI, the home box (as issuer) orders — and the CA then |
| +validates against the box DNS names, whose registry has never heard of |
| +the host. Every authorization failed, each client retry re-triggered |
| +another through the backhaul, and five failures burned the name's LE |
| +per-hostname budget in minutes while the route was down (#277, observed |
| +in the dev topology). |
| + |
| +All three gates now admit a host when it is in this box's registry |
| +(`Allowed`, unchanged) **or** is an **EXACT** key of the mirrored home |
| +map (`homeMap.KnownHost`, folded from the same `control/edges/**` objects |
| +Part 3 already mirrors on the same 30s cadence) — bridged in one place, |
| +`Edge.deploymentHost`. Both halves stay registry-backed and |
| +deployment-controlled: edges files are written by each box's own loop |
| +from its own registry, so a stranger cannot add a name without a control- |
| +bucket write, which Part 2's trust statement already treats as |
| +game-over. |
| + |
| +**The one-label wildcard rule stays excluded, and that is load-bearing.** |
| +The home map carries `*.<parent>` catch-all rows verbatim, and `Home()`'s |
| +one-label fallback makes labels under them dialable. Admitting the |
| +fallback here would let a stranger's SNI or Host of |
| +`<anything>.<remote-parent>` drive fresh per-host ACME orders against the |
| +deployment's single shared account and rate-limit bucket, and spend the |
| +read-through budgets on invented names — exactly what PR #180's |
| +exact-registry `Allowed` rule exists to refuse. That rule therefore |
| +survives verbatim, merely widened from "this box's routes" to "this |
| +deployment's exactly-named routes"; coverage for labels under a catch-all |
| +remains the wildcard cert's job, as on a single box. Exact-only loses |
| +nothing: an order only ever exists for a name that passed the exact gate, |
| +so a challenge only ever needs answering for an exact name. Refusals are |
| +pinned by test on all three surfaces |
| +(`TestHostPolicyRefusesWildcardLabelUnderRemoteCatchAll`, |
| +`TestALPNReadThroughRefusesWildcardLabelUnderRemoteCatchAll`, |
| +`TestChallengeReadThroughStillRefusesStrangers`). |
| + |
| +*Residual, filed rather than fixed.* An order still only ever STARTS on |
| +the issuer, because autocert orders lazily out of `GetCertificate`. In a |
| +3-plus-edge deployment where DNS points at neither the home box nor the |
| +issuer, no hello ever reaches the issuer and the name simply stays |
| +certless — **failing closed, with zero LE spend** (a non-issuer answers |
| +`errNotIssuer` before autocert's cache lookup, so backhauled hellos there |
| +order nothing). Steering heals the steered case (its latency records |
| +include the issuer edge) and the custom-domain CNAME guidance covers the |
| +rest; a proactive issuer-side order nudge for exact home-map names is the |
| +natural fix and is a follow-up, not an overnight change. Issue #277 |
| +carries this ruling and the residual. |
| + |
| +*Rollout.* Read-side only — no wire or storage shape, no new writer, no |
| +knob — and dormant on single-box deployments, where the fold is empty and |
| +every gate reduces to `Allowed`. Must be rolled to EVERY edge of a |
| +deployment before its second edge arms: a not-yet-rolled edge is exactly |
| +the refusing validator #277 describes. Until then, do not point real DNS |
| +at a non-home edge for a home-boxed name; that hour-long rate-limit has |
| +already been paid once. |
| + |
| **Issuer death**: the lease expires and the next box's housekeeper takes |
| over with identical machinery. Distributed certs keep every edge serving |
| through the gap; a dead issuer costs nothing until the earliest renewal |