feature: authorization/policy layer (wheels.Policy + authorize()/can()/policyScope())

[bpamiri]

Child of #2962, sequenced AFTER the auth generator (policies need a currentUser to authorize). Framework-core: wheels.Policy base + authorize()/can()/policyScope() controller+view mixins. Cross-engine constraint: mixin helpers must be public with $-prefixed internals (Invariant 7). Key design call: default-deny vs default-allow when no policy exists — Pundit denies, Laravel's before() foot-gun allows; recommendation on the parent: default-deny.

[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:3156 -->
<!-- wheels-bot:triage-class:framework-design -->

[wheels-bot]

Wheels Bot — Cross-Framework Research

Question

Wheels wants a first-class authorization/policy layer that answers "may this currentUser perform this action on this record?" — layered on top of the authentication system from the parent roadmap (#2962, which answers "who are you?"). The proposed surface is a wheels.Policy base class plus controller+view mixin helpers authorize() (enforce, throws on deny), can() (boolean, for views), and policyScope() (narrow a collection for index). The load-bearing open design call is default-deny vs default-allow when no policy exists — the parent issue already leans default-deny (Pundit-style), and this research tests that against the field.

How other frameworks handle this

Framework	Naming	Surface	Trade-offs	Edge cases
Rails (Pundit)	<Model>Policy, update?, authorize, policy_scope, base ApplicationPolicy	Method-per-action policy class + nested Scope; opt-in verify_authorized guard	Plain-OO, unit-testable; same policy(record).update? object gates view and controller (no drift); ceremony per action	Missing policy class → loud NotDefinedError; default-deny lives in scaffolded ApplicationPolicy whose methods return false
Laravel	Gates + <Model>Policy, update, authorize(), @can, before()	Auto-discovered policies + closure Gates; can() in controller/view/route	Zero-config policy discovery; current user implicit everywhere; two parallel systems (gates vs policies)	Default-deny on undefined ability and guest user; before() foot-gun — must return null to defer, a bare boolean silently allows/denies everything
Django (+ django-rules)	app.action_model perm strings, has_perm, PermissionRequiredMixin, perms template tag	Model-level perms in core; object-level + predicate composition via django-rules	One string works in view/decorator/template; predicates compose (is_author OR is_editor)	Default-deny everywhere; superuser short-circuits to allow; core has_perm(obj) ignores the record arg (looks object-level, isn't); no core collection scoping
Phoenix (Bodyguard / LetMe)	authorize(action,user,params), permit?, scope; LetMe object/action/allow/deny	Behaviour/DSL policy on the context module + scope query narrowing	Tiny surface; same policy reused across web/API/LiveView; LetMe is introspectable (filter_allowed_actions drives UI)	Bodyguard needs a hand-written deny catch-all or it crashes (FunctionClauseError); LetMe bakes default-deny into the compiled rule
Spring Security	@PreAuthorize, hasPermission(), @PostFilter, PermissionEvaluator	SpEL annotations + pluggable per-object PermissionEvaluator; URL matcher to rule	Declarative one-liners on the action; object-level decision is pluggable	Default-deny only if you install the anyRequest().denyAll() terminal — unmatched/unannotated = open otherwise; SpEL is stringly-typed
Symfony Voters (+1)	*Voter, supports() + voteOnAttribute(), isGranted(), is_granted()	Composable voters per attribute+subject-type + access-decision strategy	abstain is not deny, letting many small focused voters compose with zero coordination; two-method indirection is boilerplate	All-abstain → deny by default (allow_if_all_abstain=false); no collection-scope primitive

Why Symfony for the "+1": its Voter pattern is the cleanest articulation in the field of the abstain-vs-deny distinction that directly answers Wheels' open question, and it offers a genuine structural alternative to the method-per-action policy class — composable predicates rather than one class per model (the same shape django-rules reaches for).

Dominant pattern

Two findings converge hard and one forks. (1) Default-deny is unanimous. Every framework denies when no rule matches — Laravel/Django/LetMe bake it in, Symfony resolves all-abstain to deny, Spring forces an explicit denyAll terminal, and Pundit denies via a base class whose methods return false. Not one framework defaults to allow; the only "allow" escape hatches (Laravel's before(), Gate overrides) are explicitly flagged as foot-guns. This fully validates the parent issue's default-deny call. (2) The proposed authorize() / can() / policyScope() trio maps almost 1:1 onto Pundit (authorize / policy(r).action? / policy_scope) and Phoenix (permit! / permit? / scope) — so the issue's chosen names are idiomatic. The fork: structure of the policy itself — method-per-action class (Pundit, Laravel — recommended, matches the issue) vs composable voter/predicate (Symfony, django-rules). The one real divergence: collection scoping (policyScope) exists in Pundit/Phoenix/Spring (@PostFilter) but not in Laravel or Symfony — so shipping it is a deliberate Pundit-lean.

A subtle but important nuance the field splits on: missing policy method vs missing policy class. Pundit denies a missing method (inherited false) but raises a loud error on a missing class — treating a forgotten policy as a programmer bug, not a silent deny. Django/Laravel silently deny both. The loud-on-missing-class behaviour is the single most portable idea for catching typos.

Recommended path for Wheels

Adopt the Pundit-shaped, method-per-action policy class with default-deny baked into the base. A wheels.Policy base denies every standard action; app policies extend it and override to grant. authorize() throws Wheels.NotAuthorized (HTTP 403); can() is the non-throwing boolean for views; policyScope() narrows an index collection by returning a chainable finder. The authenticated identity flows in through a single configurable seam (the currentUser resolver the auth generator in #2962 will provide).

// vendor/wheels/Policy.cfc — base class; app policies extend "Policy".
// Default-DENY: every standard action denies unless a subclass overrides.
component {
    function init(required any user, required any record) {
        variables.user   = arguments.user;    // authenticated identity, or "" when signed out
        variables.record = arguments.record;  // model instance, model class, or "" for headless
        return this;
    }
    public boolean function index()  { return false; }
    public boolean function show()   { return false; }
    public boolean function create() { return false; }
    public boolean function update() { return false; }
    public boolean function delete() { return false; }

    // Collection narrowing for index — defaults to "no rows"; override to widen.
    public any function scope(required any collection) {
        return arguments.collection.where("1 = 0");
    }
}

// app/policies/PostPolicy.cfc — override to grant; compose with enums/scopes/builder
component extends="Policy" {
    public boolean function update() {
        return Len(variables.user) && variables.user.id == variables.record.userId;
    }
    public any function scope(required any collection) {
        return variables.user.isAdmin ? arguments.collection : arguments.collection.where(published = true);
    }
}

// Controller usage (mixin auto-integrated). Views run in the controller's
// variables scope, so can() is available in templates too.
function update() {
    post = model("Post").findByKey(params.key);
    authorize(post);                 // throws Wheels.NotAuthorized (403) on deny; returns post
    post.update(params.post);
}
function index() {
    posts = policyScope(model("Post")).active().findAll(page = params.page, perPage = 25);
}
// view:  <cfif can("update", post)>#linkTo(text="Edit", route="editPost", key=post.id)#</cfif>

Public mixin signatures (all-named when options are passed — no mixed argument styles):

• public any function authorize(required any record, string action = variables.params.action) — resolves <Model>Policy, instantiates with the resolved user + record, dispatches the action method, throws Wheels.NotAuthorized on false, returns the record so it inlines.
• public boolean function can(required string action, any record = "") — non-throwing boolean for views/conditionals.
• public any function policyScope(required any collection) — resolves <Model>Policy, calls its scope(), returns the narrowed finder chain.
• Internals must be public + $-prefixed (Invariant 7): $policyFor(), $policyClassName(), $currentUserForPolicy() (the configurable resolver).

Lives in: vendor/wheels/Policy.cfc (base class, sibling to Model.cfc / Controller.cfc / Job.cfc) + a new mixin vendor/wheels/controller/authorization.cfc (sibling to filters.cfc / verifies.cfc).
Composes with: the chainable query builder & scopes (policyScope() returns a finder you keep chaining — .active().findAll(page=...)); the DI container (currentUser as a request-scoped resolver from the auth layer); enum checkers inside policy methods (variables.record.isPublished()). An optional Pundit-style verifyAuthorized filter (dev/testing only) can flag actions that never called authorize()/policyScope().

Cross-engine notes

Manageable, but three traps to honour. (1) Invariant 7 — authorize/can/policyScope are mixed onto controllers via $integrateComponents(), which copies only public methods, and views execute in the controller's variables scope; so every helper is public and every internal is public + $-prefixed (private mixins fail on Lucee/Adobe). (2) Dynamic method dispatch — the policy action method is invoked by name. Use a single-expression bracket call policyObj[local.action]() so BoxLang binds the receiver (extracting the method into a local var first drops it), and keep that call out of any closure (Adobe CF 2021/2023 crash on bracket-notation calls inside closures). (3) Policy class resolution should use CreateObject/component lookup, and init() takes positional args (no inline-closure-as-named-arg). No Lucee-only or Adobe-only APIs are required. Net: clean if the mixin discipline and single-expression dispatch are followed.

Open questions

• Missing policy class: silently deny, or throw a loud Wheels.Policy.NotDefined to catch typos? Pundit's loud-on-missing-class is its best safety idea. Suggest mirroring Wheels' existing dev-vs-prod posture (cf. tableName() docs+model: guides and CLAUDE.md use non-existent tableName("x") setter — silent no-op, models fall back to the convention table (real setter is table()) #3079): throw in development/testing, deny in production.
• currentUser seam: this feature is sequenced after the auth generator (roadmap: high-impact application feature gaps — auth scaffold/generator, authorization policy layer, file attachments (Active Storage), channels docs + WebSocket parity #2962), which doesn't exist yet — so the canonical resolver is undecided. DI service("currentUser"), a controller currentUser() helper, or read from the Authenticator? This is a hard dependency that should land first.
• Structural choice: confirm method-per-action policy class (Pundit/Laravel — recommended, matches the issue) over the composable voter/predicate model (Symfony/django-rules). Both are viable; the issue's named API presupposes the former.
• policyScope() as a first-class helper: Laravel and Symfony ship no scope primitive — confirm we want the Pundit/Phoenix collection-narrowing helper rather than leaving index filtering to plain scopes.
• Global override hook: ship a Laravel-style before()/admin-override or not? It's a documented foot-gun (must return "no opinion", never a bare boolean). Recommend omitting it initially; if added later, make "defer" structurally distinct from "deny."

Confidence: low

Low because the proposal introduces new framework infrastructure — a wheels.Policy base class, a new controller/view mixin, and a policy-resolution convention — and hard-depends on the not-yet-built auth generator (#2962) for the currentUser seam; the "new infrastructure / new mixin warrants a human discussion before code" auto-downgrade rule fires. The default-deny call is settled (unanimous across all six frameworks), but the missing-policy-class semantics, the currentUser resolver, and the method-per-action-vs-voter structural fork are decisions a human should confirm before propose-fix writes code.

Sources

• Rails / Pundit: https://github.com/varvet/pundit and https://github.com/CanCanCommunity/cancancan
• Laravel: https://laravel.com/docs/12.x/authorization and [5.3] Auth Gate : Throwing an error when no ability match laravel/framework#16496 (undefined ability returns false, does not throw)
• Django: https://docs.djangoproject.com/en/stable/topics/auth/default/ and https://github.com/dfunckt/django-rules
• Phoenix: https://bodyguard.hexdocs.pm/readme.html and https://let-me.hexdocs.pm/readme.html
• Spring Security: https://docs.spring.io/spring-security/reference/servlet/authorization/method-security.html and https://docs.spring.io/spring-security/reference/servlet/authorization/architecture.html
• Symfony: https://symfony.com/doc/current/security/voters.html and https://symfony.com/doc/current/security.html