Every route on zanabler.com says who may reach it

Four layers from Zana 2.21 to 2.23: every route declares who may reach it, the tests attack every route, an unsafe release cannot be built, and a reviewed list records who may reach what. Applied to this site’s 150 routes, with real outputs.

A list of routes marked with padlocks, people and open rings; a new route highlighted in gold awaits a person’s approval.

The most common serious flaw in web applications is not an exotic attack. It is a page that forgot to check who is asking. An admin screen added on a Friday without its permission check, an export with no sign-in, a draft preview that anyone can open. Each one is a single missing line, and each one looks fine in a code review because there is nothing there to see.

Zana 2.21 to 2.23 tackle that problem from four directions. Every route must say who may reach it. Every route is attacked by the test suite. A release cannot be built while a rule fails. And a committed list records who may reach each route, so that every change to it is reviewed by a person.

This website runs on all four. Its 150 routes are checked on every build: 86 need a permission, 62 are public with a written reason, and 2 need any signed-in editor. Here is how each layer works, with real outputs from this site and from a small demo project where we made the mistakes on purpose.

Layer 1: every route says who may reach it

In Zana 2.21, a route that says nothing is an error. Each route, or the class or group it belongs to, declares one of three things:

  • #[RequiresPermission('articles.edit')]: only users who hold that permission;
  • #[RequiresAuthentication]: any signed-in user;
  • #[PublicRoute(reason: '…')]: anyone, and the reason why.

The reason is not decoration. It is what a reviewer reads, and it forces the author to state the intent. Here is how this site's sign-in pages declare it:

#[PublicRoute(reason: 'Signing in and out: the sign-in form is for people without a session yet, and signing out without one only leads back to it')]
final readonly class LoginController

In our demo, we added two pages the way people often do. One is a search page that declares nothing. The other is a reports page that requires a permission, but without the middleware that enforces it. php bin/console check stops both:

  ✘ GET /search does not say who may reach it. (modules/Site/Presentation/Web/SearchController.php:17)
      → Add #[RequiresAuthentication] or #[RequiresPermission('…')] with AuthorizationMiddleware on the route, or #[PublicRoute(reason: '…')] if anyone may reach it.
  ✘ GET /reports requires a user, but AuthorizationMiddleware is not on the route, so anyone reaches it. (modules/Site/Presentation/Web/ReportsController.php:18)
      → Add AuthorizationMiddleware to the route or its group. Authentication middleware alone lets anonymous requests through.

The second finding is the subtle one. The code looks protected: the attribute is right there. But an attribute is only a declaration. Without AuthorizationMiddleware on the route, nothing reads it, and the page is open to everyone. Zana catches the gap between what the code says and what it does.

Layer 2: every route is attacked

Declarations can be wrong, so in Zana 2.22 the test suite attacks every route, in memory, on every run. One line in tests/SecurityTest.php does it:

$this->assertRoutesWithstandAttacks();

The attacks depend on what each route declares:

  • a route that needs a user gets an anonymous request and an expired session, which must never reach its handler;
  • a form gets no CSRF token, a forged one, and a post from another site;
  • a rate-limited route gets one request more than it allows;
  • every route anyone may reach gets hostile input: a script, SQL, template syntax, ../ paths, NUL bytes, very long values, a list where a value is expected, a body that is not JSON and a 2 MB body.

It catches what declarations cannot. In the demo, the search page was now correctly declared public, but it printed the visitor's query as it came:

return $this->responses->html("<h1>Results for {$q}</h1>");

The attack test found it, and something else besides:

7 route(s) attacked with 55 request(s): 2 failure(s).
  ✘ GET /search — a script in the query: the page prints the script as it was sent: a visitor could be made to run it.
  ✘ GET /search — a list where a value is expected: caused a PHP warning in the application: Array to string conversion (SearchController.php:21). Check the type of what the request sends before using it.

The first is cross-site scripting: a link could make a visitor's browser run someone else's script on our site. The second is the kind of crack attackers probe for. After checking the type and escaping the output, all 55 requests pass.

The attacks also run as a signed-in user. This site's test signs in as an editor and declares what an editor holds. The attacks then check that the account-management screens, which need editors.manage, refuse an editor, and that every screen an editor may use withstands forged forms and hostile input:

$this->assertRoutesWithstandAttacks(
    signIn: static fn (ServerRequestInterface $request): ServerRequestInterface => $request->withHeader('Cookie', $cookie),
    holding: self::EDITOR,
);

On this site, the two runs, anonymous and as an editor, make 2,554 assertions in about 19 seconds. A new route is attacked the moment it exists, with no test to write for it.

Layer 3: an unsafe release cannot be built

Checks only help if they stop something. With security.strict set to true, which both Zana skeletons and this site do, the security rules of check are errors rather than warnings. The skeletons' continuous integration pipeline runs the tests, check and composer audit on every push, so a failing rule stops a merge.

The release command enforces the same rules on the code it packages. In the demo, after committing the two new routes without reviewing them:

 [ERROR] Nothing was built: the security rules of check report 2 error(s) (security.strict).

         [security.exposure] GET /reports is new, and not in the reviewed baseline security/exposure.json: users with reports.read may reach it.

No archive is written, so there is nothing to upload.

Layer 4: a reviewed list of who may reach what

The first three layers make sure every route is declared and behaves as declared. They cannot tell whether the declaration is right. Should the reports page really be open to anyone holding reports.read? Should drafts be previewable by link? Those are decisions, and decisions belong to people.

Zana 2.23 records them in a file committed with the code, security/exposure.json, with one line per route. Here are a few of this site's:

"GET /admin/account": {"access": "user"},
"GET /admin/editors": {"access": "permission", "permissions": ["editors.manage"]},
"GET /en/insights/{slug}": {"access": "public", "reason": "The public blog: published articles and their feeds"},
"POST /en/start-a-project": {"access": "public", "reason": "The \"Start a project\" form, for any visitor"},
"GET /preview/articles/{token}": {"access": "public", "reason": "A draft preview: the signed link an editor shares is the access, for an hour"},

When anything changes, such as a new route, a route made public, or a permission swapped for another, check reports it. php bin/console security:exposure shows exactly what differs, and writes nothing:

2 route(s) differ from the reviewed baseline security/exposure.json:
  + GET /reports: users with reports.read
  + GET /search: anyone (public: "Searching the public pages")
Nothing was written. Review each change; once reviewed, record them with security:exposure --update, and commit the file.

Showing and approving are deliberately separate. Running the command again never approves anything. Only --update records a change, and the file it writes is the only one accepted: a hand edit fails the check. In a pull request, the change to exposure.json sits next to the code that caused it, so the reviewer sees "this route is now public, because…" in one line rather than hunting for it.

The same rule applies to AI coding agents. The AGENTS.md that Zana writes into every project tells them to show the changes and name each one in their summary, and never to record them: recording a change approves it, and that is a person's decision.

What this does not do

Zana's documentation is explicit about the limits:

  • One user reading another's data is not tested. Whether invoice 42 belongs to the person asking for it is your application's knowledge. Test it with two users of your own.
  • A declared reason is trusted, not judged. A poor reason passes check; that is why it is written down for a reviewer.
  • The signed-in attacks are only as good as the sign-in you give them, and CSRF is attacked with a session, not with a bearer token.
  • The hostile-input attacks run your handlers, as a visitor could, so they run against the test database.

These layers do not replace thinking about access. They make sure the thinking happens on every route, every time, and that its result is written down where the next person can see it.

Bringing an existing application up to this standard

  1. Upgrade with composer update and run php bin/console check. Each security.* warning names a route or a setting to fix.
  2. Give every route its declaration. For a website's pages, one line covers a whole group: $router->group('', $routes, public: 'The public website').
  3. Add tests/SecurityTest.php, as in the skeletons, and fix what it finds. Expect findings on the first run; each names the route and the attack.
  4. When check is clean, set security.strict to true, and add composer audit to your CI.
  5. Run php bin/console security:exposure, review who may reach each route, record the baseline with --init, and commit security/exposure.json.

On this site, that took one upgrade commit and one review. Since then, no route can appear, open up or change its permission without someone saying so.

If you would like help applying this to your own application, Zana-based or not, tell us about your project.

Get new articles by email

One email a month. You confirm your address before anything is sent.