Authorization
Authentication answers “who are you?”. Authorization answers “are you allowed to do this?”: may Bob edit Alice’s post? May a guest see a draft?
In Strutvane, those answers live in policies: one class per model in app/policies/, with one method per action. And the most important rule: anything a policy doesn’t explicitly allow is denied.
The smallest example
Section titled “The smallest example”import type { AuthUser, Policy } from '@strutvane/framework'import type { Post } from '../models/post.ts'
export class PostPolicy implements Policy<Post> { /** Anyone may list posts. */ viewAny(): boolean { return true }
/** Published posts are public; drafts only for their author. */ view(user: AuthUser | null, post: Post): boolean { return post.status === 'published' || user?.id === post.author_id }}Give it to the controller:
export class PostController extends ResourceController<typeof Post> { protected readonly model = Post protected readonly policy = new PostPolicy()}What you’ll see:
| Request | Result | Why |
|---|---|---|
GET /api/posts/hello-world (published), as a guest |
200 |
view allows published posts |
GET /api/posts/alice-draft, as a guest |
404 |
view says no, so it looks missing |
POST /api/posts, as Alice |
403 |
There’s no create method, so it’s denied |
The policy methods
Section titled “The policy methods”| Method | Called for | Arguments |
|---|---|---|
viewAny(user) |
Listing (index) |
the user (or null) |
view(user, record) |
Showing one record, and before any update/delete | the user, the record |
create(user) |
store |
the user |
update(user, record) |
update and custom actions you guard with it |
the user, the record |
delete(user, record) |
destroy |
the user, the record |
before(user, ability) |
First, before any of the above | the user, the action name |
Each method returns true or false (or a Promise of one). Anything other than true means no.
user is null for guests, so write user?.id and decide what guests may do.
A complete policy (typical)
Section titled “A complete policy (typical)”import type { AuthUser, Policy } from '@strutvane/framework'import type { Post } from '../models/post.ts'
/** * Who may do what with posts. A method that is missing denies, so `delete` below is * admin-only through `before()`. */export class PostPolicy implements Policy<Post> { /** Admins may do everything; for everyone else, fall through to the methods below. */ before(user: AuthUser | null): boolean | undefined { return user?.is_admin === true ? true : undefined }
/** Anyone may list posts (the controller narrows the list to what they may see). */ viewAny(): boolean { return true }
/** Published posts are public; drafts only for their author. */ view(user: AuthUser | null, post: Post): boolean { return post.status === 'published' || user?.id === post.author_id }
/** Any signed-in author may write. */ create(user: AuthUser | null): boolean { return user !== null }
/** Only the author may edit. */ update(user: AuthUser | null, post: Post): boolean { return user?.id === post.author_id }}before(): let admins through
Section titled “before(): let admins through”before() runs first. Return:
true: allowed, skip the other methods;false: denied, skip the other methods;undefined: no opinion, carry on to the normal method.
A helper, hasAdminRole(user), is true for a user with is_admin: true or 'admin' in a roles list. Generated policies use it.
Checking a policy yourself: authorize()
Section titled “Checking a policy yourself: authorize()”ResourceController checks the policy in every action. In your own actions, call authorize():
import { authorize } from '@strutvane/framework'
await authorize(this.policy, 'update', ctx.user, post, 'post') // throws 403 if not allowed| Argument | Meaning |
|---|---|
this.policy |
The policy to ask |
'update' |
The action: viewAny, view, create, update or delete |
ctx.user |
Who’s asking (null for guests) |
post |
The record (undefined for viewAny and create) |
'post' |
A label for the message: “You are not allowed to update this post.” |
When you only need a yes/no answer (to show or hide a button), use allows():
import { allows } from '@strutvane/framework'
const canEdit = await allows(this.policy, 'update', ctx.user, post) // true or falsereturn ctx.json({ data: post, meta: { canEdit } })403 or 404?
Section titled “403 or 404?”Imagine Bob tries PATCH /api/posts/alice-draft. If he got 403 Forbidden, he’d learn that a draft called alice-draft exists. So Strutvane checks view first, in every action that targets one record:
Bob may view it? |
Bob may update it? |
Bob gets |
|---|---|---|
| No | (not asked) | 404 No post matches "alice-draft". (same as a missing post) |
| Yes | No | 403 You are not allowed to update this post. (honest) |
| Yes | Yes | 200 |
In your own actions, do the same with visible():
async publish(ctx: HttpContext): Promise<Response> { const post = await this.visible(ctx) // 404 if they can't see it await authorize(this.policy, 'update', ctx.user, post, 'post') // 403 if they can't change it post.fill({ status: 'published' }) await post.save() return ctx.json({ data: post })}Lists: what may each user see?
Section titled “Lists: what may each user see?”viewAny answers “may this user list posts at all?”. It doesn’t filter which posts. Narrow the list in the controller with indexConstraints():
protected override indexConstraints(ctx: HttpContext): Constraint[] { if (ctx.user?.is_admin === true) return [] const visible: Constraint[] = [{ column: 'status', equals: 'published' }] if (ctx.user !== null) visible.push({ column: 'author_id', equals: ctx.user.id }) return [{ anyOf: visible }]}What you’ll see for GET /api/posts: guests get the published posts; Alice also gets her drafts; admins get everything. Totals and pages match.
Developers see why: hints in local mode
Section titled “Developers see why: hints in local mode”In local debug mode (APP_DEBUG=true, APP_ENV=local or testing), every 403 explains itself:
{ "status": 403, "code": "forbidden", "detail": "You are not allowed to delete this post.", "hint": "PostPolicy has no delete() method, so this is denied (Strutvane denies by default). Add delete(user, post) to the policy to allow it."}When the method exists and said no:
{ "detail": "You are not allowed to update this post.", "hint": "PostPolicy.update() returned false for this user." }In production the hint is never sent.
Abilities that aren’t about one record: can
Section titled “Abilities that aren’t about one record: can”Some checks have no record: “may this user see the stats page?”, “may they run an import?”. Laravel calls these gates. In Strutvane they’re named abilities, defined once in bootstrap/app.ts:
import { dirname } from 'node:path'import { Application, hasAdminRole } from '@strutvane/framework'// the rest of the file (config, providers, routing) is unchanged
export function createApp(): Application { return Application.configure({ basePath: dirname(import.meta.dirname) }) .withMiddleware((middleware) => { middleware.defineAbility('view-stats', (user) => user !== null && hasAdminRole(user)) middleware.defineAbility('import-posts', (user) => user?.is_admin === true) }) .create()}Then guard routes with can:<ability>:
import { defineRoutes, Route } from '@strutvane/framework'import { StatsController } from '../app/http/controllers/stats.controller.ts'
export default defineRoutes([ Route.get('/admin/stats', [StatsController, 'show']).name('admin.stats').middleware('auth', 'can:view-stats'),])What you’ll see for a signed-in user who isn’t an admin:
{ "status": 403, "code": "forbidden", "detail": "You are not allowed to do this.", "hint": "The \"view-stats\" ability denied this request." }(The hint appears in local debug mode only.) A guest gets 401 from auth first, before the ability runs.
The same check, in the other styles every protection supports:
| Style | Code |
|---|---|
| On a route | .middleware('auth', 'can:view-stats') |
| On a controller | static readonly middleware = [can({ params: ['view-stats'] })] |
| Around a plain handler | export default withCan(async (ctx) => ctx.json(stats), 'view-stats') |
A typo can’t slip through. Start-up checks every can: reference. A route naming an ability that doesn’t exist stops the app (and node strut route:list, and every test):
✖ GET /admin/stats uses can:view-stat, but no such ability is defined.→ Did you mean "view-stats"?Why abilities about one record stay in the controller: route model binding runs after middleware. If a record check ran as middleware, a guest would learn whether the post exists before being told to sign in. So record checks use the policy and authorize() in the controller, as above.
A role is a name given to a group of users (“admin”, “member”), so policies can say “admins may delete” instead of listing people. The installer asks which roles to start with (question 10):
| Preset | Roles |
|---|---|
admin-member (default) |
admin, member |
admin-manager-member-viewer |
admin, manager, member, viewer |
Role names live in code; only who-has-which-role is stored (the user_roles table, and team roles in team_members when teams are on). New users get no roles. Policies decide what each role means:
import { hasAdminRole, type AuthUser, type Policy } from '@strutvane/framework'import type { Post } from '../models/post.ts'
const rolesOf = (user: AuthUser | null): readonly string[] => user !== null && 'roles' in user && Array.isArray(user.roles) ? user.roles : []
export class PostPolicy implements Policy<Post> { before(user: AuthUser | null): boolean | undefined { return hasAdminRole(user) ? true : undefined }
viewAny(user: AuthUser | null): boolean { return user !== null // every signed-in role may list }
view(user: AuthUser | null, post: Post): boolean { return post.status === 'published' || user?.id === post.author_id || rolesOf(user).includes('manager') }
create(user: AuthUser | null): boolean { return rolesOf(user).some((role) => role === 'manager' || role === 'member') // viewers can't write }
update(user: AuthUser | null, post: Post): boolean { return user?.id === post.author_id || rolesOf(user).includes('manager') }}What you’ll see: viewers read, members write their own posts, managers edit anyone’s, admins pass through before().
API tokens and policies
Section titled “API tokens and policies”A request made with a personal access token must pass both the token’s abilities and your policy. The policy is written once; it doesn’t need to know whether the user came with a cookie or a token. A token can only narrow what the user may do, never widen it.
Row conditions: one rule for one record and for lists
Section titled “Row conditions: one rule for one record and for lists”Today you write the visibility rule twice: in view() for one record, and in indexConstraints() for lists. In 0.2 a policy method may return a row condition instead of true or false. The same condition checks one record in memory and becomes a SQL WHERE for lists, counts, exports, search and charts, so they can never disagree.
The rules the compiler keeps (from 0.1, and they stay):
- NULL never matches by accident.
author_id = <your id>is false for a row whoseauthor_idis NULL, and for a guest. In plain SQL,NULL = NULLis “unknown”, and sloppy code turns that into “allow”. - The negation is exact. “Not mine” includes rows with no author.
- A broken rule denies. A condition that can’t be compiled gives an error, never “all rows”.
In the UI: show only what’s allowed
Section titled “In the UI: show only what’s allowed”The generated screens hide the New button without create, hide Edit and Delete per row, and hide a resource from the sidebar without viewAny. The server still checks every request: hiding a button is a convenience, not a protection.
Where policies live
Section titled “Where policies live”One file per model, app/policies/<model>.policy.ts, exporting <Model>Policy. Policies are discovered by name, like Laravel: model Post → app/policies/post.policy.ts, with no registration. A controller that names a policy explicitly (protected readonly policy = new PostPolicy()) overrides discovery. Discovery is decided and coming in 0.2; the prototype needs the explicit line. node strut make:policy writes a deny-all policy.
See which routes are protected by what:
node strut route:list --securityTesting a policy
Section titled “Testing a policy”Policies are plain classes, so test them directly, without HTTP:
import { allows } from '@strutvane/framework'import { describe, expect, it } from 'vitest'import { PostPolicy } from '../../app/policies/post.policy.ts'import type { Post } from '../../app/models/post.ts'
const policy = new PostPolicy()const alice = { id: 1, is_admin: false }const bob = { id: 2, is_admin: false }const draft = { id: 10, status: 'draft', author_id: 1 } as unknown as Post
describe('PostPolicy', () => { it('lets the author see her draft, and nobody else', async () => { expect(await allows(policy, 'view', alice, draft)).toBe(true) expect(await allows(policy, 'view', bob, draft)).toBe(false) expect(await allows(policy, 'view', null, draft)).toBe(false) })})What you’ll see:
✓ tests/unit/post.policy.test.ts (1 test) 3msFeature tests check the whole route, the 404 included. See HTTP Tests.
With Docker or without Docker
Section titled “With Docker or without Docker”Authorization works the same in both: policies are your own TypeScript, read by the app wherever it runs. The local-mode hint depends only on APP_ENV and APP_DEBUG, so a container started with APP_ENV=production never shows hints, even on your laptop.
Generated policies deny everything
Section titled “Generated policies deny everything”node strut make:controller PostController --api (or --resource, or --model=Post) writes app/policies/post.policy.ts if it doesn’t exist:
import { hasAdminRole, type AuthUser, type Policy } from '@strutvane/framework'import type { Post } from '../models/post.ts'
/** * Who may do what with posts. Generated to deny everyone except admins: open up each * method deliberately. A method you delete also denies. */export class PostPolicy implements Policy<Post> { /** Admins may do everything. */ before(user: AuthUser | null): boolean | undefined { return hasAdminRole(user) ? true : undefined }
/** TODO: who may list posts? */ viewAny(_user: AuthUser | null): boolean { return false }
/** TODO: who may see one post? */ view(_user: AuthUser | null, _post: Post): boolean { return false }
/** TODO: who may create a post? */ create(_user: AuthUser | null): boolean { return false }
/** TODO: who may change this post? */ update(_user: AuthUser | null, _post: Post): boolean { return false }
/** TODO: who may delete this post? */ delete(_user: AuthUser | null, _post: Post): boolean { return false }}Why so strict? A new endpoint should never be open by accident. You open each action deliberately, one method at a time.
And a resource controller without a policy doesn’t start at all (see Common mistakes).
Common mistakes
Section titled “Common mistakes”Everyone gets 403 on create
Section titled “Everyone gets 403 on create”{ "status": 403, "code": "forbidden", "detail": "You are not allowed to create a post.", "hint": "PostPolicy has no create() method, so this is denied (Strutvane denies by default). Add create(user) to the policy to allow it." }Fix: add the method:
create(user: AuthUser | null): boolean { return user !== null}“… serves resource routes but has no policy”
Section titled ““… serves resource routes but has no policy””✖ PostController serves resource routes but has no policy.→ Give it a `protected readonly policy = new PostPolicy()` and call authorize() in every action (node strut make:controller --resource writes this for you).My update returns 404 for a post that exists
Section titled “My update returns 404 for a post that exists”Why: view() returns false for this user, so the post is treated as invisible.
Fix: decide whether they should see it. If yes, allow it in view(); then update() decides about changing it.
My policy returns a truthy value but is still denied
Section titled “My policy returns a truthy value but is still denied”Why: only exactly true allows. 1, 'yes' or an object count as “no”.
Fix: return a real boolean: return user?.id === post.author_id.
A guest gets 401, not the 403 I expected
Section titled “A guest gets 401, not the 403 I expected”{ "status": 401, "code": "unauthenticated", "detail": "Sign in first: send an \"Authorization: Bearer <token>\" header." }Why: the route has the auth middleware, which runs before any policy. Someone who isn’t signed in is asked to sign in first.
Fix: nothing, if the route needs sign-in. If guests should be allowed, remove auth and decide in the policy what null may do.
The app won’t start: “no such ability is defined”
Section titled “The app won’t start: “no such ability is defined””✖ GET /admin/stats uses can:view-stat, but no such ability is defined.→ Did you mean "view-stats"?Why: the name in can: doesn’t match any defineAbility().
Fix: correct the spelling, or define the ability in bootstrap/app.ts.
My can check returns the user and is still denied
Section titled “My can check returns the user and is still denied”Why: only exactly true allows, for abilities as for policies.
Fix: (user) => user !== null && hasAdminRole(user), never (user) => user.
Next steps
Section titled “Next steps”- Controllers:
visible(),indexConstraints()and custom actions. - Middleware:
auth, and route-wide checks likeadmin. - Teams & Tenancy: keeping each customer’s data apart.
- API Tokens: token abilities on top of policies.
- Audit: recording who changed what.