fix(trust): enforce §3 invariant 3 — BoJ ignores X-Trust-Level from non-loopback (standards#98) (#106)

## Summary

Phase A contract §3 invariant 3 mandates: *"Any `X-Trust-Level`
arriving from any other source MUST be ignored and treated as
`untrusted`."*

`BojRest.TrustPolicy.satisfies?/3` previously accepted
`X-Trust-Level: authenticated|internal` from any caller — the third
clause matched regardless of `is_local`. A non-loopback caller reaching
BoJ's back-side bind (a §4 violation) could therefore claim any trust
class by setting a header. This is the **BoJ-side half of the §3
defence-in-depth pair**; the gateway-side strip + re-emit landed as
http-capability-gateway#11.

## The fix

One new clause between the existing `:public` and `:authenticated`
arms:

```elixir
def satisfies?(_required, _trust, false), do: false
```

Plus the surrounding bookkeeping:

- `trust_policy_test.exs` — 2 existing assertions inverted (they
  codified the buggy behaviour) + 2 new tests explicitly pinning §3
- `router_test.exs` — 2 existing tests inverted (used to assert that
  a non-loopback caller with `X-Trust-Level: authenticated|internal`
  passed; now assert they get 403)
- `phase_c_seam_test.exs` — 5 `@tag skip:` annotations removed; module
  moduledoc updated (was a "documented finding" module; now a live
  enforcement test module)
- `docs/integration/http-capability-gateway-boj-contract.md` — new
  "Implementation status (Phase C)" subsection naming the three
  controls (gateway-side / BoJ-side / operational §4) and where each
  landed
- `lib/boj_rest/trust_policy.ex` — moduledoc updated with a "Phase A §3
  invariant 3" subsection explaining the new clause

## Test plan

- [x] `mix test test/{trust_policy,router,phase_c_seam}_test.exs` —
**64/64 green**
- [x] full `mix test` — 2 failures, both pre-existing baseline rot in
`catalog_test.exs:85` + `catalog_properties_test.exs:73` (cartridge
`auth.method` values), unrelated to this PR
- [ ] reviewer: confirm §3 enforcement is correct — non-loopback caller
cannot promote trust class via header
- [ ] reviewer: confirm the inversion of the 2 router-tests + 2
trust_policy_tests is the right call (they were testing the buggy
behaviour)

## Refs

Refs hyperpolymath/standards#98
Refs hyperpolymath/standards#91

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

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

Author: hyperpolymath

docs/integration/http-capability-gateway-boj-contract.md

@@ -123,6 +123,20 @@ router. This invariant is tested in Phase C (plan §Phase C, "Trust header
 forwarding security invariant") and hardened in Phase B (mTLS becomes the
 trust source so the resolved value cannot be header-forged at all).
 
+**Implementation status (Phase C):**
+
+- Gateway-side (1)+(2): `http-capability-gateway/lib/http_capability_gateway/proxy.ex`
+  `build_backend_headers/1` strips client-supplied `X-Trust-Level` + `X-Request-ID`
+  and re-emits the gateway-resolved values. Landed in http-capability-gateway#11.
+- BoJ-side (3): `boj_rest/lib/boj_rest/trust_policy.ex` `satisfies?/3` ignores
+  the header for any non-loopback caller via the
+  `satisfies?(_required, _trust, false), do: false` clause — defence in depth
+  against (4) being violated by a misconfiguration. Verified by
+  `elixir/test/phase_c_seam_test.exs` (9 tests, all live).
+- (4) is an operational/configuration invariant, not a code change; verified
+  during Phase E rollout (production deployments MUST front BoJ with a
+  loopback-only socket per the §Phase E runbook).
+
 ---
 
 ## 4. Headers BoJ MUST NOT forward to cartridges unchanged

elixir/lib/boj_rest/trust_policy.ex

@@ -14,6 +14,19 @@ defmodule BojRest.TrustPolicy do
   Loopback callers (127.x.x.x, ::1) bypass trust enforcement — they are
   implicitly trusted as local processes (mcp-bridge, developer curl, etc.).
 
+  ## Phase A §3 invariant 3 — non-loopback ignores `X-Trust-Level`
+
+  Per the http-capability-gateway BoJ contract §3 invariant 3, a
+  non-loopback caller presenting an `X-Trust-Level` header has the
+  header **ignored** — the caller is treated as if it presented no
+  header at all. The gateway is the only source authorised to assert a
+  trust class, and reaches BoJ on the loopback bind; any other source
+  is by definition not the gateway. This is BoJ-side defence in depth;
+  the gateway-side strip is the primary control. Without this clause an
+  attacker who reaches BoJ's back-side bind directly (a §4 violation —
+  back-side bind not network-isolated) could claim `internal` trust by
+  setting a header.
+
   ## Exposure inference from auth.method
 
   | auth.method          | Required caller exposure |
@@ -49,10 +62,15 @@ defmodule BojRest.TrustPolicy do
   True when the given `X-Trust-Level` header value satisfies `required`.
 
   Loopback callers (`is_local: true`) always satisfy any exposure level.
+  Non-loopback callers (`is_local: false`) have their `X-Trust-Level`
+  header **ignored** per Phase A §3 invariant 3 — they can therefore
+  only satisfy `:public` exposure. The header alone cannot promote a
+  non-loopback caller's trust class.
   """
   @spec satisfies?(exposure(), trust_header(), boolean()) :: boolean()
   def satisfies?(_required, _trust, true), do: true
   def satisfies?(:public, _trust, _local), do: true
+  def satisfies?(_required, _trust, false), do: false
   def satisfies?(:authenticated, trust, _local) when trust in ["authenticated", "internal"], do: true
   def satisfies?(_required, _trust, _local), do: false
 end

elixir/test/phase_c_seam_test.exs

@@ -1,34 +1,22 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# Phase C seam tests — BoJ-side documentation of the http-capability-gateway
+# Phase C seam tests — BoJ-side enforcement of the http-capability-gateway
 # contract §3 (trust-header security invariant).
 #
-# *** Finding ***
-# Phase A contract §3 invariant 3 is currently **UNENFORCED** at the BoJ
-# side. `BojRest.TrustPolicy.satisfies?/3` accepts an `X-Trust-Level:
-# authenticated|internal` header from any caller — its third clause does
-# not branch on `is_local`. The contract states (boj-contract.md §3.3):
+# Companion to http-capability-gateway#11 (gateway-side X-Trust-Level
+# strip + re-emit) — together they form the §3 defence-in-depth pair:
 #
-#     BoJ's gnosis handler / BojRest.Router MUST treat X-Trust-Level as
-#     authoritative only when the connection originates from the gateway
-#     ... Any X-Trust-Level arriving from any other source MUST be ignored
-#     and treated as untrusted.
+#   gateway-side:  strips client-supplied X-Trust-Level, re-emits from
+#                  the gateway's resolved trust decision (mTLS-derived
+#                  from Phase B onward)
+#   BoJ-side:      ignores X-Trust-Level from any non-loopback caller
+#                  (enforced by BojRest.TrustPolicy.satisfies?/3)
 #
-# Mitigation in practice today: §4 (back-side bind isolation) keeps the
-# non-loopback path unreachable in well-configured deployments. But the §3
-# enforcement is "mandatory, not advisory" per the contract, and is the
-# BoJ-side half of the defence-in-depth pair whose gateway-side half landed
-# in http-capability-gateway#11.
-#
-# This module:
-#   * **Tests that currently pass** — positive controls (loopback HONOURS
-#     the gateway-forwarded header; non-loopback to :public cartridge still
-#     OK) and `is_local=true` function-level parity. Live now.
-#   * **Tests that demonstrate the defect** — marked `@tag skip:` with a
-#     reason. They will start passing as-is when the §3 fix lands in
-#     `BojRest.TrustPolicy.satisfies?/3` (add clause: any non-loopback +
-#     non-:public exposure → false).
+# All 9 tests here are live. The 4 non-loopback negative tests
+# previously documented an unfixed defect (with `@tag skip:`); the
+# defect was fixed by adding a `satisfies?(_, _, false), do: false`
+# clause and those tests are now enforced.
 #
 # Refs hyperpolymath/standards#98 (Phase C).
 # Refs hyperpolymath/standards#91 (HCG tier-2 channel).
@@ -42,11 +30,9 @@ defmodule BojRest.PhaseCSeamTest do
   @keyed_cart "airtable-mcp"
   @public_cart "boj-health"
 
-  @skip_finding "Phase A §3 invariant 3 unenforced in TrustPolicy.satisfies?/3 — see module doc + standards#98"
-
   # ── §3 invariant 3 (positive control) — loopback HONOURS X-Trust-Level ────
 
-  describe "loopback callers (gateway-equivalent path) — live tests" do
+  describe "loopback callers (gateway-equivalent path)" do
     test "X-Trust-Level: internal from 127.0.0.1 → allowed on :authenticated cartridge" do
       conn = invoke(@keyed_cart, "airtable_list_bases",
         remote_ip: {127, 0, 0, 1},
@@ -83,11 +69,8 @@ defmodule BojRest.PhaseCSeamTest do
   end
 
   # ── §3 invariant 3 — non-loopback X-Trust-Level MUST be IGNORED ───────────
-  # The 4 tests below DEMONSTRATE THE FINDING. They are skipped today; they
-  # will pass unchanged once the §3 fix lands in TrustPolicy.satisfies?/3.
 
-  describe "non-loopback callers (header MUST be ignored per §3) — finding, skipped" do
-    @tag skip: @skip_finding
+  describe "non-loopback callers (header ignored per §3)" do
     test "X-Trust-Level: internal from 1.2.3.4 → 403 on :authenticated cartridge" do
       conn = invoke(@keyed_cart, "airtable_list_bases",
         remote_ip: {1, 2, 3, 4},
@@ -100,7 +83,6 @@ defmodule BojRest.PhaseCSeamTest do
       assert body(conn)["required"] == "authenticated"
     end
 
-    @tag skip: @skip_finding
     test "X-Trust-Level: authenticated from 1.2.3.4 → 403 on :authenticated cartridge" do
       conn = invoke(@keyed_cart, "airtable_list_bases",
         remote_ip: {1, 2, 3, 4},
@@ -111,7 +93,6 @@ defmodule BojRest.PhaseCSeamTest do
       assert body(conn)["error"] == "forbidden"
     end
 
-    @tag skip: @skip_finding
     test "X-Trust-Level: internal from IPv6 non-loopback → 403" do
       # IPv6 documentation prefix 2001:db8::/32 — never routable, never loopback.
       conn = invoke(@keyed_cart, "airtable_list_bases",
@@ -122,7 +103,6 @@ defmodule BojRest.PhaseCSeamTest do
       assert conn.status == 403
     end
 
-    @tag skip: @skip_finding
     test "SSE: X-Trust-Level: internal from 1.2.3.4 → 403 on :authenticated cartridge" do
       conn = invoke_sse(@keyed_cart, "airtable_list_bases",
         remote_ip: {1, 2, 3, 4},
@@ -143,7 +123,6 @@ defmodule BojRest.PhaseCSeamTest do
       end
     end
 
-    @tag skip: @skip_finding
     test "is_local=false rejects every non-:public exposure regardless of header" do
       for trust <- [nil, "public", "authenticated", "internal", "garbage"] do
         refute BojRest.TrustPolicy.satisfies?(:authenticated, trust, false),

elixir/test/router_test.exs

@@ -401,30 +401,36 @@ defmodule BojRest.RouterTest do
     assert body["required"] == "authenticated"
   end
 
-  test "POST /invoke on keyed cartridge with X-Trust-Level: authenticated → allowed" do
+  # Phase A §3 invariant 3: non-loopback X-Trust-Level is IGNORED. These two
+  # used to assert the header was honoured for non-loopback callers; that was
+  # the §3 hole the gateway was supposed to plug at the front and BoJ at the
+  # back. BoJ-side enforcement now lives in TrustPolicy.satisfies?/3.
+  test "POST /invoke on keyed cartridge with X-Trust-Level: authenticated from non-loopback → 403 (header ignored, §3)" do
     conn =
       conn(:post, "/cartridge/#{@keyed_cart}/invoke", Jason.encode!(%{tool: "airtable_list_bases"}))
       |> put_req_header("content-type", "application/json")
       |> put_req_header("x-trust-level", "authenticated")
       |> Map.put(:remote_ip, {1, 2, 3, 4})
       |> BojRest.Router.call(@opts)
 
-    assert conn.status in [200, 500]
+    assert conn.status == 403
     body = Jason.decode!(conn.resp_body)
-    refute body["error"] == "forbidden"
+    assert body["error"] == "forbidden"
+    assert body["detail"] == "insufficient-trust"
   end
 
-  test "POST /invoke on keyed cartridge with X-Trust-Level: internal → allowed" do
+  test "POST /invoke on keyed cartridge with X-Trust-Level: internal from non-loopback → 403 (header ignored, §3)" do
     conn =
       conn(:post, "/cartridge/#{@keyed_cart}/invoke", Jason.encode!(%{tool: "airtable_list_bases"}))
       |> put_req_header("content-type", "application/json")
       |> put_req_header("x-trust-level", "internal")
       |> Map.put(:remote_ip, {1, 2, 3, 4})
       |> BojRest.Router.call(@opts)
 
-    assert conn.status in [200, 500]
+    assert conn.status == 403
     body = Jason.decode!(conn.resp_body)
-    refute body["error"] == "forbidden"
+    assert body["error"] == "forbidden"
+    assert body["detail"] == "insufficient-trust"
   end
 
   test "POST /invoke on keyed cartridge with X-Trust-Level: public → 403 forbidden" do

elixir/test/trust_policy_test.exs

@@ -49,14 +49,24 @@ defmodule BojRest.TrustPolicyTest do
     assert TrustPolicy.satisfies?(:public, "internal", false)
   end
 
-  test "satisfies?: :authenticated requires authenticated or internal" do
-    assert TrustPolicy.satisfies?(:authenticated, "authenticated", false)
-    assert TrustPolicy.satisfies?(:authenticated, "internal", false)
+  test "satisfies?: :authenticated requires authenticated or internal when loopback" do
+    assert TrustPolicy.satisfies?(:authenticated, "authenticated", true)
+    assert TrustPolicy.satisfies?(:authenticated, "internal", true)
   end
 
   test "satisfies?: :authenticated rejects public or nil" do
     refute TrustPolicy.satisfies?(:authenticated, "public", false)
     refute TrustPolicy.satisfies?(:authenticated, nil, false)
     refute TrustPolicy.satisfies?(:authenticated, "garbage", false)
   end
+
+  # ── Phase A §3 invariant 3 — non-loopback `X-Trust-Level` is ignored ─────
+
+  test "satisfies?: :authenticated rejects non-loopback authenticated (header ignored, §3)" do
+    refute TrustPolicy.satisfies?(:authenticated, "authenticated", false)
+  end
+
+  test "satisfies?: :authenticated rejects non-loopback internal (header ignored, §3)" do
+    refute TrustPolicy.satisfies?(:authenticated, "internal", false)
+  end
 end