5.0: enforce the select= validation policy (SEC-21 hard mode) after the 4.x deprecation window

[bpamiri]

Successor to #2952's last open item. 4.x ships the development-mode warning (#3011); 5.0 flips it to enforcement: invalid/unsafe select= expressions throw instead of warn. Scope: the policy definition finalized during the warn window, the throw path, upgrade-guide entry, and removal of the warn-only branch. Blocked until: 5.0 planning. Optional rider: whereParams parameterization (the #2952 'optional' item) if it survives a fresh cost/benefit look.

[wheels-bot]

Wheels Bot — Triage

Classified as framework-design (API/feature design question).
Cross-framework research will follow shortly — Rails, Laravel, Django,
and other modern frameworks will be consulted before any path forward
is proposed.

<!-- wheels-bot:triage:3153 -->
<!-- wheels-bot:triage-class:framework-design -->

[wheels-bot]

Wheels Bot — Cross-Framework Research

Question

Wheels' ORM lets callers pass select= columns/expressions to finders. ORDER BY/GROUP BY already throw on raw SQL, but the SELECT list passes dotted/aliased items through verbatim — only a dev-mode warning ($warnOnUnvalidatedSelectItem) when an item has ;, --, /*, or a (SELECT …) subquery (the 4.x SEC-21 window, #3011). 5.0 wants to flip warn→enforcement (throw). Scope: finalize the safe-vs-unsafe policy, ship the throw path (mirroring $orderByClause), remove the warn-only branch, write the upgrade-guide entry — plus decide the optional whereParams parameterization rider.

How other frameworks handle this

Framework	Naming	Surface	Trade-offs	Edge cases
Rails	Arel.sql(), allow_unsafe_raw_sql, UnknownAttributeReference	Structural whitelist regex on select/order/group/pluck; raw opt-in via the Arel.sql marker (bypass by type, not string)	One greppable, auditable opt-in — but conservative regex rejects legit SQL (multi-arg fns, CASE, casts) → noisy	col / table.col / 1-arg fn / alias / ASC-DESC pass; else throws unless Arel.sql-wrapped
Laravel	select vs selectRaw / DB::raw / Expression	Identifiers quoted/wrapped; raw encoded as the Expression type	Intent carried by type, terse — but zero validation once raw; wrapping isn't injection-proof for column names	fns/aggregates need selectRaw; subqueries via closures, never a raw string
Django	values/only/defer, annotate+F()/Func(), RawSQL(sql, params)	3-tier ladder: validated field names → structured exprs → raw with required params=	Safe path easiest; required params forces parameterization — but two raw hatches (extra vs RawSQL) confuse	bad field → FieldError; quoting the %s is the footgun
Phoenix/Ecto	select, fragment("?"), type/2, selected_as	Query is an AST, not a string; raw only via fragment where ? binds values; interpolation disallowed	Injection structurally impossible — but fragment loses type inference, verbose	? binds values only; identifiers need identifier/1; LIKE still needs %/_ escaping
Spring Data JPA	@Query (JPQL) vs nativeQuery=true, JpaSort.unsafe()	Projections/JPQL validated vs entity metamodel; raw via explicit flag; order-by fns require literal unsafe()	The name unsafe documents risk per call-site, greppable — but legit LENGTH() ordering blocked on common path	Sort.by("LENGTH(x)") throws by default; driven by SQLi CVE-2016-6652
Doctrine (+1)	DQL, addCustomStringFunction, createNativeQuery, QueryException	Parsed language: SELECT items validated vs metadata; unknown fn throws "Expected known function"; raw via separate native-query door	Parser is the boundary — already a throw-enforcer in prod — but every vendor fn needs a registered FunctionNode	unknown field/fn rejected at parse time; values always parameterized

+1 — Doctrine: the one peer whose SELECT clause already throws on disallowed items (the exact 5.0 end-state), pairing a default-deny whitelist with a separate raw escape hatch rather than a passthrough hole. Also the cleanest migration precedent: doctrine/deprecations → deprecate-in-minor, remove-in-major, document in UPGRADE.md.

Dominant pattern

Unanimous: safe-by-default + one explicit, named opt-in escape hatch for deliberate raw SQL — always a distinct greppable signal (a marker type Arel.sql/Expression/fragment, a required params=, or a literal unsafe()/nativeQuery=true). Two divergences: denylist vs whitelist (Wheels alone denylists tokens; Rails/Doctrine whitelist by structure/metadata — more robust, more breaking) and how much to validate the raw path (Laravel trusts fully; Django/Ecto force parameterization). On migration all agree: ship the escape hatch with the warning, flip warn→throw only at the major boundary, gated/documented in the upgrade guide. Rails gates by load_defaults <version> (new apps enforce, upgraders keep warning); Django accelerates straight to a throw for security-class issues — directly relevant since this is an injection concern.

Recommended path for Wheels

Keep the already-finalized denylist (;, --, /*, subquery) as the 5.0 trigger — matches issue scope, minimizes breakage; a Rails-style whitelist is a larger separate hardening for later. Convert $warnOnUnvalidatedSelectItem into a throwing $validateSelectItem raising Wheels.InvalidSelectClause, mirroring Wheels.InvalidOrderClause in $orderByClause. Per every framework, enforcement must ship with an escape hatch or audited-raw-SQL users are stranded. Wheels already has the structured hatch (calculated properties = Django annotate/F(); the warning already points there). Add one per-call opt-in allowRawSelect= (Spring JpaSort.unsafe / Laravel selectRaw analog — a plain named boolean, greppable), threaded findAll → $selectClause → $createSQLFieldList.

// vendor/wheels/model/sql.cfc — replaces the 4.x warn-only branch
// 5.0 SEC-21 enforcement: throw on raw-SQL select items unless explicitly opted-in.
public void function $validateSelectItem(required string item, boolean allowRawSelect = false) {
    if (arguments.allowRawSelect || !$isSuspiciousSelectItem(arguments.item)) {
        return;
    }
    Throw(
        type = "Wheels.InvalidSelectClause",
        message = "Raw SQL is not allowed in the select clause.",
        extendedInfo = "The select item contains a statement separator, comment marker, or subquery. Define a calculated property with property() in config() and reference it by name, or pass allowRawSelect=true if you have audited the expression and it contains no request input."
    );
}
// in $createSQLFieldList where $warnOnUnvalidatedSelectItem was called:
if (arguments.clause == "select") {
    $validateSelectItem(item = local.iItem, allowRawSelect = arguments.allowRawSelect);
}

// SAFE — calculated property (preferred structured path)
//   config(): property(name="fullName", sql="first_name || ' ' || last_name");
model("User").findAll(select="id,fullName");
// SAFE — plain columns / table.column / 1-arg fn / alias still pass
model("User").findAll(select="users.id, COUNT(orders.id) AS orderCount", include="orders", group="users.id");
// 5.0 — now THROWS Wheels.InvalidSelectClause (was a dev warning in 4.x)
model("User").findAll(select="(SELECT secret FROM admins) AS x");
// Deliberate, audited raw SQL — explicit opt-in escape hatch
model("User").findAll(select="(SELECT MAX(total) FROM orders WHERE orders.user_id = users.id) AS maxOrder", allowRawSelect=true);

Lives in: vendor/wheels/model/sql.cfc (replace $warnOnUnvalidatedSelectItem; thread allowRawSelect through vendor/wheels/model/read.cfc::findAll + $selectClause). Composes with calculated properties, the chainable query builder, include/group, and the whereParams rider.

whereParams rider — strong endorse. Everyone converges on parameterized placeholders for values (Django params=, Ecto/Rails ?, Doctrine :name, Spring @Param). where="status = ?" + whereParams=["active"] is the value-side complement to this select-side hardening; worth surviving the fresh cost/benefit look.

Cross-engine notes

Clean. Throw() is used identically in $orderByClause/$groupByClause, so the throw path is proven on Lucee 5/6/7, Adobe 2018–2025, BoxLang. allowRawSelect is a plain named boolean — no mixed positional+named args, no struct.map(), no obj["key"](), no closures, no array-by-value. $validateSelectItem must be public + $-prefixed to mix into model objects (Invariant #7). No bare cfabort, no attributeCollection=arguments. Update SelectClauseWarningSpec.cfc (the "passes through unchanged" test now asserts a throw).

Open questions

• Escape hatch shape: allowRawSelect= boolean (recommended) or rely only on calculated properties? A new public finder arg warrants a human nod.
• Enforcement gating: hard unconditional throw in 5.0 (issue says so; Django accelerates security flips), or a softer set(enforceSelectPolicy="warn|throw") tri-state à la Rails load_defaults?
• Denylist vs whitelist: confirm 5.0 keeps the denylist rather than adopting a Rails/Doctrine structural whitelist (recommended; track whitelist separately).
• whereParams scope: same 5.0 PR or a sibling issue?

Confidence: medium

The core flip (warn→throw, mirroring the in-repo $orderByClause precedent, policy already finalized) is clear and concrete. Downgraded from high because the dominant pattern (typed raw-SQL marker + structural whitelist) had to be adapted to Wheels' string-based select= and existing denylist, the +1 (Doctrine) and Rails validate via metadata/whitelist with a non-trivial trade-off, and the escape-hatch API (allowRawSelect) is a genuine new public-surface choice a human should ratify.

Sources

• Rails: https://api.rubyonrails.org/classes/ActiveRecord/Sanitization/ClassMethods.html · Disallow raw SQL in dangerous AR methods rails/rails#27947
• Laravel: https://laravel.com/docs/12.x/queries
• Django: https://docs.djangoproject.com/en/5.2/ref/models/expressions/ · https://docs.djangoproject.com/en/dev/internals/deprecation/
• Phoenix/Ecto: https://ecto.hexdocs.pm/Ecto.Query.API.html
• Spring Data JPA: https://docs.spring.io/spring-data/jpa/reference/jpa/query-methods.html · https://spring.io/security/cve-2016-6652/
• Doctrine: https://www.doctrine-project.org/projects/doctrine-orm/en/3.6/reference/dql-doctrine-query-language.html · https://www.doctrine-project.org/policies/deprecation.html

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3164

Spec: vendor/wheels/tests/specs/model/SelectClauseEnforcementSpec.cfc — failing → passing (11/11), supersedes the deleted SelectClauseWarningSpec.cfc
Implementation: vendor/wheels/model/sql.cfc ($warnOnUnvalidatedSelectItem → throwing $validateSelectItem), vendor/wheels/model/read.cfc + vendor/wheels/interfaces/model/ModelFinderInterface.cfc (allowRawSelect threaded through findAll / findOne → $selectClause → $createSQLFieldList)

This implements the cross-framework research's recommended path: keep the finalized denylist as the 5.0 trigger, convert warn→throw mirroring the in-repo $orderByClause precedent, and ship the throw with one greppable allowRawSelect=true opt-in. The upgrade-guide entry and the optional whereParams rider are deferred (hence Refs, not Closes), and three research open questions — escape-hatch shape, hard-throw vs tri-state gating, denylist vs whitelist — are flagged in the PR for human ratification.

A human review is required before merge. The Reviewer will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.