Repository navigation
fix(Middleware): validate allowedQueryParameters entries; #262 review follow-ups - #274
Merged
Merged
Conversation
… names (#148) `allowedQueryParameters` lists family base names made only of a-z, the only names the reserved-parameter check rejects. An entry such as `lang[region]`, `Lang`, ` lang` or `""` could never match one, so it silently admitted nothing and left the parameter it meant to admit rejected. `schemaErrorsLayer` and `layerWith` now throw the new `Middleware.InvalidAllowedQueryParameter` when the layer is built, and `checkQueryParameters` when it is called; a bracketed entry's message names the base name to list instead. Also tests the declared-name walk through a suspended query schema, and names in the pending changeset the common lowercase parameters (`q`, `lang`, `limit`, `fbclid`, ...) that now answer 400. Follow-up to #262. Part of #148. Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc Co-Authored-By: Claude <noreply@anthropic.com>
3 tasks
…ages (#148) Review follow-ups to the allow-list entry validation: - schemaErrorsLayer validates allowedQueryParameters when it is built and then hands the checked list to an internal rejectQueryParameters, rather than through checkQueryParameters, which re-validated on every request. checkQueryParameters still validates its own options. - An empty entry now says "An empty entry names no parameter; remove it." instead of the any-other-character hint. - layerWith's JSDoc says it throws InvalidAllowedQueryParameter, as the other three do. - Tests pin the "needs no entry" message (not the base-name hint) and the empty-entry message. Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc Co-Authored-By: Claude <noreply@anthropic.com>
This was referenced Oct 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #262. Part of #148.
Review follow-ups to #262 (the reserved query-parameter 400), each checked against
trunkat b1d774b, after #264.Allow-list entries are now validated (should-fix).
allowedQueryParametersdocuments its entries as "family base names made only of a-z", the only names the check ever rejects. An entry likelang[region],Lang,langor""could never match one, so before this change it admitted nothing, and the parameter it was meant to admit was still rejected. Such an entry now throws the new exportedMiddleware.InvalidAllowedQueryParameter(Schema.TaggedError, fieldsparameterandmessage,@since 0.17.0):schemaErrorsLayerandlayerWiththrow it when the layer is built, so a typo fails at startup.checkQueryParametersthrows it when called.List its base name "lang")."", the message saysAn empty entry names no parameter; remove it.page, …) stay valid entries. They match^[a-z]+$and are harmless.Validation runs once per layer.
schemaErrorsLayervalidates the list when it is built. It then passes the checked list to an internal (non-exported)rejectQueryParameters, so the list isn't re-validated on every request. The publiccheckQueryParametersis nowallowedBaseNames+rejectQueryParameters, and it still validates its own options when called.rejectQueryParametersreturns anOption, so the move adds noprefer-option-over-nullwarn-tier site. The publiccheckQueryParameterssignature is unchanged (Option.getOrUndefined).title: BadRequest.title(nit): already true, skipped. The check already spreadsBadRequest.title, asschemaErrorDocumentdoes. Nothing is hard-coded.SchemaAST.isSuspendbranch (nit). Added a test,what an endpoint's query schema declares › reads through a suspended schema. Its endpoint's query isSchema.suspend(() => Schema.Struct({ a })).?a=1answers 200, and?a=1&unknown=1answers the 400.Changeset (nit).
.changeset/reject-reserved-query-parameters.mdfrom fix(Middleware): reject reserved all-lowercase query parameters with 400 #262 is still pending: the package is at 0.16.3, and the feature is@since 0.17.0. So I amended it rather than adding a changeset. It now names the lowercase parameters users are likely to hit:q,search,lang,localelimit,offsetformat,callbacktoken,reft,vfbclid,gclidIt also notes that
utm_source,_andx-traceare unaffected, and adds the entry validation."An allowed name never reaches
query" docs: already fixed by fix(Query): drop undeclared query parameters when the query declares nothing (#260) #264, skipped. fix(Query): drop undeclared query parameters when the query declares nothing (#260) #264 (6311818, 30e8530) made the claim true: an endpoint whose query declares nothing now drops undeclared parameters, and a test pins it. TheQueryParameterOptions.allowedQueryParametersJSDoc and the README sentence also now say "which keeps only what itsqueryschema declares — also when that schema declares nothing (bug: an endpoint whose query declares nothing passes every parameter to its handler, and?x=1&x[y]=2is a 500 #260)". No change needed.Docs. All four entry points that can throw now say so in their JSDoc:
QueryParameterOptions.allowedQueryParameters,schemaErrorsLayer,layerWith(added in the second commit) andcheckQueryParameters.README: one paragraph added in the Middleware "Reserved query parameters" section, describing the entry rule. Nothing else in the README is touched.
Mutation checks
allowedBaseNames(options)replaced by the raw list (options?.allowedQueryParameters ?? []), 21 tests fail: 9schemaErrorsLayer, 9layerWith, the base-name hint, "needs no entry" and the empty-entry message.checkQueryParametersstill validates: with itsallowedBaseNames(options)replaced by the raw list, 9 tests fail (eachrefuses … in a checkQueryParameters call).Option.isSome(rejected)short-circuited tofalse, 12 tests fail.true(always "List its base name …"),says a name with any other character needs no entryfails. This test asserts thatschemaErrorsLayer({ allowedQueryParameters: ["Lang"] })throws a message containing "needs no entry" and not "List its base name".parameter === ""branch disabled,says an empty entry names no parameterfails.parametermutated to"x", 9 tests fail. This confirms thetoThrow(expect.objectContaining(…))assertions bite.isSuspendbranch: with the branch deleted,reads through a suspended schemafails (expected 200 to be 400). The test passes with it restored.Verification
All run locally on the head commit, in order:
pnpm install --frozen-lockfile: passvp run build: passvp check: pass (0 errors). The 4353 warnings match the base: no new warn-tier site. The two flagged sites in changed hunks were there before: thetitleconditional spread moved intorejectQueryParameters, and theallowedQueryParameters?: … | undefined/checkQueryParametersreturn-type declarations.vp run check(sources, type-level tests, examples, emitted declarations): passvp run -r test:unit: pass. Root: 2286 tests. Examples: 42 / 39 / 53.vp run docgen: pass. docgen does not run the newInvalidAllowedQueryParameter@example. @effect/docgen 0.5.2'sgetExampleFilesnever collects examples from a class's own doc comment, so athrowin that example still passes docgen. (An earlier version of this body wrongly said docgen ran it.) I checked that example by hand instead, aftervp run build:tsx: it printslang[region]and exits 0.tsc6(TypeScript 6.0.3) under docgen'sexamplesCompilerOptions(--ignoreConfig --noEmit --strict --skipLibCheck --module esnext --moduleResolution bundler --target es2022 --lib es2022 --exactOptionalPropertyTypes false --types node): exit 0.tsc6invocation on a copy that reads.nopefails withTS2339: Property 'nope' does not exist on type 'InvalidAllowedQueryParameter'.@examplein a class's own doc comment (10 examples never run) #276 and isn't fixed here.fallow audit --base origin/trunk: pass ("No issues in 4 changed files"; one inheritedsourceOfCRAP finding, excluded by the gate). The agent gate (fallow audit --format json --quiet --explain --gate-marker agent) verdict ispass.Changeset
.changeset/reject-reserved-query-parameters.md(minor, from fix(Middleware): reject reserved all-lowercase query parameters with 400 #262). It names the common lowercase parameters and the new entry validation. This PR changes only unreleased 0.17.0 behaviour, so no new changeset is needed. The second commit changes only an error message and internal plumbing, and the changeset's text still holds.Notes
Middleware.InvalidAllowedQueryParameter. Existing signatures are unchanged.schemaErrorsLayer/layerWith/checkQueryParameterscan now throw on a misconfigured allow-list. That follows theRegistry.layer/Registry.checkFamilyprecedent of throwing a tagged error for a construction-time misconfiguration.rejectQueryParametersis module-private.lang[region]to the wholelangfamily.Lang,langor""have no meaningful normalisation: member names are case-sensitive, and trimming would guess.schemaErrorsLayer/checkQueryParameters.🤖 Generated with Claude Code
Generated by Claude Code