An OPA ext_authz rule matched a URL path exactly; adding ?page=2 now returns 403. Why?

## What the developer actually sees A service call that worked all week starts returning `403` with an empty body the moment a query parameter is added. Nothing in the response says which rule refused it or why, because a denial from external authorization is just Envoy's default rejection: status 403, no body, unless the policy went out of its way to shape one. The service logs show no request at all, because the request never reached the service — it was stopped at the proxy. ## The mechanism The policy is queried once per request with an `input` built from the proxy's check request. `input.attributes.request.http.path` is the **raw request target**: the path *and* the query string, still percent-encoded, exactly as the client sent it. So for `GET /api/v1/orders?page=2` that field is the string `"/api/v1/orders?page=2"`. An equality test against `"/api/v1/orders"` is simply false. In Rego a failed expression makes the rule body fail; the rule produces nothing; with a `default allow := false` in the document, the answer is a deny. This is why the OPA Envoy plugin adds `input.parsed_path`. It takes the target, discards everything from the `?` onward, splits the remaining path on `/`, and percent-decodes each segment, producing `["api", "v1", "orders"]`. Comparing that array to a list of segments is stable against query strings, against encoding, and against a caller who appends a fragment or an extra parameter. ## The dangerous direction On an allow rule this bug is merely annoying: a legitimate request is refused, someone gets paged, the rule is fixed. On a **deny** rule the same mismatch is a security hole, and it is the version an interviewer will push you toward. Suppose a rule denies anything whose raw path starts with `/admin`. A caller requests `/adm%69n/reset`. As a string, that does not start with `/admin`, so the deny does not fire. But the proxy and the upstream service will normalise and decode that target on the way to routing and handling it, and the request lands on the admin handler. The rule and the thing it was protecting disagreed about what the path was. Matching `input.parsed_path[0] == "admin"` closes that gap, because the decoding happens before your comparison rather than after it. The mirror-image mistake is a prefix test: `startswith(path, "/admin")` also matches `/administrators/export`, quietly widening the rule to a route nobody intended to gate. Segment comparison does not have that failure mode either — `parsed_path[0] == "admin"` is true for `/admin/reset` and false for `/administrators/export`. ## Fixing it, and confirming the fix The corrected rule matches on segments and, where the request may legitimately carry parameters, reads them from `input.parsed_query`, which maps each parameter name to an array of values (a name can repeat). Note also that indexing a segment that does not exist — `input.parsed_path[2]` on a two-segment path — makes the expression undefined, so the whole rule body fails. That is the correct behaviour for an allow rule and a trap for a deny rule, which is another argument for expressing gates as positive allows over an explicit default deny. To confirm what the policy actually saw rather than what you assume it saw, read OPA's decision log for the refused request: it records the `input` document and the result together. That single habit turns "the gate is broken" into "the gate compared `/api/v1/orders?page=2` to `/api/v1/orders`" in about a minute, and it is the difference between debugging a policy and arguing about one. ## The lesson to state out loud A policy decides on a *representation* of the request. Every place where the representation the rule reads differs from the representation the upstream acts on is a bug: query strings, percent-encoding, case, trailing slashes, duplicate parameters. Prefer the fields the plugin has already normalised, and write matches that are exact about structure rather than clever about strings.