forward: no way to express "forward everything" or "everything except", and the absent-block default silently rewrites the request

[OliverWolffGIP]

Summary

The forward model can express only one of the three postures a proxy needs, and it has picked the
rarest one as the default. There is no way to say "forward everything", and no way to say "forward
everything except X". The only expressible posture is an exhaustive allowlist — and omitting the
block means nothing crosses.

The result is that a route which does not enumerate every header and every query parameter its
backend uses will silently produce a different upstream request than the client sent. No error, no
log, no metric.

Expected

Three postures, resolved independently for headers and for query parameters:

Declaration	Behaviour
no list declared	everything is forwarded
allowlist declared	only the listed elements are forwarded
denylist declared	everything is forwarded except the listed elements

headers_allow / query_allow keep their current meaning. The two gaps are the absent case and the
denylist.

Actual

ForwardPolicyStage.copyAllowedQuery / copyAllowedHeaders iterate the allowlist and look each
name up, so anything unnamed is simply never read. ForwardConfig's canonical constructor
normalises an absent list to an empty one:

headersAllow = headersAllow == null ? List.of() : List.copyOf(headersAllow);
queryAllow   = queryAllow   == null ? List.of() : List.copyOf(queryAllow);

so "not declared" and "declared empty" are already indistinguishable downstream. The schema is a
plain array of string with no reserved value, and the lookup is literal, so "*" would match a
parameter named * rather than acting as a wildcard.

Why the current default is the wrong way round

The failure mode is a silent rewrite, not a refusal. The upstream receives a request the client
did not send, the client receives a plausible answer computed from the wrong input, and nothing
anywhere records that an input was discarded — there is no logging, event or metric in the entire
forward package.

That is also inconsistent with how the rest of the gateway behaves. An unknown configuration key
refuses the boot; an unrecognised security_defaults.profile refuses the boot; overlapping anchors
refuse the boot; an over-cap body is a 413; a path outside the allowlist is a 400. Everywhere
else this project fails loudly and on purpose. The forward stage is the one place that degrades
quietly, and it does so on the input path where a wrong answer is hardest to notice.

Four things the change has to settle

These are not objections — they are the places where a naive "absent means forward everything" would
break something that currently works.

1. Hop-by-hop headers need an unconditional carve-out

ResponseStage strips hop-by-hop headers on the way back, but the request path has no equivalent:
copyAllowedHeaders skips only FORWARDING_HEADERS (x-forwarded-*, forwarded). Today that is
harmless, because nothing crosses unless it is named and nobody names Connection.

Under a forward-everything default, Connection, Keep-Alive, TE, Trailer, Upgrade,
Transfer-Encoding and Proxy-Authorization would start crossing to the upstream. That is a
protocol violation and a request-smuggling surface, and it must not be reachable by omitting
configuration. These belong on an unconditional deny that no configuration can lift — the same way
the regenerated forwarding headers already work.

2. Forwarding-header regeneration must survive

Inbound X-Forwarded-* / Forwarded are deliberately never propagated and are regenerated instead.
A forward-everything default must not become a route around that.

3. Cookie on session routes would break the BFF's own mediation property

This is the one I would flag hardest. The BFF guarantees that the browser's session cookie never
reaches the upstream — the integration test asserts exactly that:

Cookie is deliberately NOT allow-listed, so the browser session cookie is stripped and never
reaches the upstream — the two halves of the mediation proof.

That guarantee currently holds because the default is deny. Flip the default and it holds only for
deployments that remember to write a denylist. A documented security property of the product would
then depend on an operator not forgetting something.

So Cookie (and arguably Authorization, which is already overwritten by the mediated bearer)
needs a carve-out on require: session routes specifically — deny by default there, regardless of
the route's declaration.

4. Allowlist and denylist on the same dimension must be a boot error

If both headers_allow and headers_deny are declared, precedence becomes something a reader has
to guess. Refusing at boot, naming the route and the dimension, is consistent with how every other
contradiction in this configuration surface is handled.

Two smaller specification points:

• Header names match case-insensitively (HTTP), query-parameter names match exactly. A denylist has
  to state which rule it follows, and they differ per dimension.
• Whether a denylist entry may be a prefix or pattern (X-Internal-*) or must be an exact name.
  Exact-only is a fine answer; it just needs to be the stated one.

Note on the upgrade

Flipping a default from "nothing crosses" to "everything crosses" widens what reaches every backend
in every existing deployment that omitted the block. The alpha policy permits breaking changes
without a migration path, but this one widens a security posture rather than narrowing it, and it
does so for configurations that do not change. It is worth an explicit release note rather than
being left to the diff.

Suggested shape

forward:
  headers_allow: [...]   # allowlist        — mutually exclusive with headers_deny
  headers_deny:  [...]   # denylist         — mutually exclusive with headers_allow
  # neither declared     → all headers forwarded, minus the unconditional carve-outs
  query_allow:   [...]
  query_deny:    [...]
  # neither declared     → all query parameters forwarded

Resolved independently per dimension, so a route may allowlist headers while forwarding all query
parameters, or the reverse.

Whatever is decided, making a discarded input visible — a counter, or a log line naming what was
dropped — would remove the whole class of "the backend answered plausibly and wrongly" debugging
this currently produces.

[OliverWolffGIP]

Companion design proposal filed as #183: separating the headers the gateway understands (Accept, Content-Type, Accept-Encoding, the conditional validators, Range) from the ones only the backend understands, so operators stop enumerating HTTP mechanics in every route.

The two interlock, and the interaction should be settled together rather than twice:

• no list declared — the set is redundant, everything crosses anyway
• allowlist — the set is added; this is where it earns its keep
• denylist — an explicitly denied entry wins

#183 also generalises not_modified, which is already this idea applied to one header set.

[cuioss-oliver]

Implemented by #185, squash-merged to main as ce644d7, and shipped in 0.1.1 (be5c4bd).

GitHub never linked this issue automatically — #185's body says "Implements #182 and #183" in prose but used no closing keyword — so recording the link here explicitly.

The three postures, per dimension

Declared	Effect
*_allow	only the enumerated names cross
*_deny	everything crosses except the enumerated names
neither	everything crosses

Resolved independently for headers and for query parameters, exactly as the suggested shape asked.

The absent-vs-declared-empty conflation is gone at the root: ForwardConfig's four list components became @Nullable and the canonical constructor stopped normalising null to List.of(), so absent and declared empty are finally distinguishable downstream.

The four things the change had to settle

1. Hop-by-hop carve-out — ConnectionHeaders.REQUEST_STRIP (16 names) sits beside the untouched RESPONSE_STRIP, applied under every mode and liftable by no configuration. TE is the one carve-out: only the exact trailers token crosses, which is what gRPC-over-HTTP/2 requires.
2. Forwarding-header regeneration survives — the regeneration skip now tests the separator-folded name, so it is not routed around by a spelling.
3. Cookie — shipped stronger than requested. Rather than a carve-out scoped to require: session routes, Cookie is withheld from client input absolutely, under every mode, on every route. The BFF mediation property therefore no longer depends on the route's declaration at all. Authorization is the single re-admittable member (naming it in a positive list re-admits it), with the mediated bearer still winning because applyMediatedBearer runs last.
4. Both lists on one dimension is a boot error — ConfigValidator.checkForwardDimension, naming the route and the dimension.

Both smaller specification points are settled and stated in-code: header names match case-insensitively (the outbound map is keyed case-insensitively per RFC 9110), query-parameter names match exactly, and entries are exact names — no prefixes or patterns.

Beyond the ask

The never-forward set closes each of its names across the whole -/_ equivalence class by rule rather than by enumeration (separatorFolded). The finalize security audit found the vendor provenance aliases carried in their hyphenated spelling only, so under forward-all 22 further spellings (X_Real_IP, CF_Connecting_IP, …) would have crossed untouched, each folding onto the same variable as the canonical name for any CGI/FastCGI/WSGI/Rack backend. Closed by the folding rule, so a name added later is covered across every spelling with no second edit.

A latent precedence bug was also fixed: applyConditionalHeaders previously ran after putAll(setHeaders()) and overrode set_headers. The pinned order is now mode copy → strip → protocol set → set_headers → regenerated forwarding → mediated bearer.

Upgrade note

Carried in the root README.adoc, as this issue asked: every 0.1.0 route with no forward block — or one declaring no *_allow — begins forwarding everything on 0.1.1. It changes what crosses within routes the operator already chose to expose, never which routes are reachable, and credentials are withheld regardless.

Not shipped, recorded rather than dropped

The closing suggestion — a counter or log line making a discarded input visible — is not in 0.1.1. It is tracked for a later cut; nothing in the forward package emits a log or metric today, and that is unchanged by this issue.

Closing as implemented.