Add route middleware: Authenticated, Authorized, JwtAuth, BasicAuth by lmajano · Pull Request #74 · coldbox-modules/cbsecurity

lmajano · 2026-10-05T12:12:17Z

Description

Adds ready-made ColdBox route middleware so a route or a group can be secured where it is declared, without firewall rules.

route( "/account" ).middleware( "Authenticated@cbsecurity" ).to( "account.index" )

route( "/admin" )
    .middleware( "Authorized@cbsecurity" )
    .meta( { permissions : "ADMIN" } )
    .to( "admin.index" )

Authenticated@cbsecurity: logged in (ignores meta)
Authorized@cbsecurity: logged in and satisfying route meta permissions, roles and mode (any, all, none)
JwtAuth@cbsecurity / BasicAuth@cbsecurity: like Authorized, through those validators
Guard: base class for custom middleware

Denied requests go through the firewall's invalid access flow, so redirect, override and block actions, module overrides, interception points (annotationType is middleware) and logging behave like a rule or annotation. Security gains public validateAccess() and processInvalidAccess(), and the annotation path now shares processInvalidAccess() with no behavior change. The firewall interceptor must stay loaded (autoLoadFirewall, default true), otherwise a clear cbsecurity.MiddlewareRequiresFirewall is thrown.

Design note: a router file loads before modules, so getInstance( "SomeFactory@cbsecurity" ) cannot run inside Router.configure(). That is why parameters travel in the route meta() and not as middleware arguments.

Requirements

Route middleware: ColdBox 8.2+.
Group-level meta and middleware inside execute(): ColdBox 8.3+, see ColdBox/coldbox-platform PR on branch claude/funny-mendel-eeim2l.

Issues

No issue is linked yet, please link or create one.

Type of change

Checklist

My code follows the style guidelines of this project (cfformat applied to my files)
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes

Testing

BoxLang 1.18, TestBox 7.1, against the companion ColdBox changes: 138 passed, 31 of them new (MiddlewareSpec).

Against unmodified ColdBox development (8.2 behavior): the route specs skip themselves via feature detection (16 passed, 15 skipped, 0 failed), so CI on released ColdBox stays green. The harness Router.cfc only registers middleware routes when the router supports them, so ColdBox 7 still loads (I could not run ColdBox 7 here).
The 1 failure and 15 errors are pre-existing and all say "No default datasource", this sandbox has no MySQL (JWT DB storage specs).
format:check still flags SecuritySpec.cfc, which I did not touch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E8yy4oK5vnaVucmYLg4UtY

Generated by Claude Code

Secure a route or a group where it is declared, with no firewall rules: - Authenticated@cbsecurity: the user must be logged in - Authorized@cbsecurity: logged in and satisfying the `permissions`, `roles` and `mode` (any|all|none) declared in the route `meta()` - JwtAuth@cbsecurity and BasicAuth@cbsecurity: Authorized, authenticating through the JWT or Basic validators - Guard: the base class for custom middleware Denied requests go through the firewall's invalid access flow, so redirect, override and block actions, module overrides, interception points and logging behave exactly like a firewall rule or annotation. The Security interceptor gains public validateAccess() and processInvalidAccess() methods for this; the annotation path now shares processInvalidAccess() with no behavior change. The route specs run only when the installed ColdBox can run route middleware in execute() and group meta (8.3+); the Guard specs run everywhere. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E8yy4oK5vnaVucmYLg4UtY

github-actions · 2026-10-05T12:13:25Z

lucee@5 ColdBox ^8.0.0 Test Results

1 files ± 0 8 suites +1 8s ⏱️ -1s
139 tests +16 139 ✅ +16 0 💤 ± 0 0 ❌ ±0
154 runs +31 139 ✅ +16 15 💤 +15 0 ❌ ±0

Results for commit 13d48b5. ± Comparison against base commit a890b0c.