Most apps start with roles. A user is an admin or a member, and a route checks which. That works until the questions stop being about who someone is and start being about the thing they are touching: can this person edit this project, today, on this plan?
This post walks through the shape I use instead, with a made-up product called Fieldnote: a SaaS where organizations have teams, and teams own projects.
Where roles run out
Here are four rules Fieldnote needs, none of them unusual:
- Anyone on a project's team can view it.
- Editors on the team can change it, unless the project is archived.
- Only an organization owner can archive a project.
- A contractor's access ends on the date their contract does.
Rule 1 depends on the resource (which team owns the project). Rule 2 depends on the resource's state. Rule 4 depends on the time. A role is one fact about the person, and none of these rules is only about the person.
The usual fix is to keep the roles and add special cases next to them, one route at a time. Six months later nobody can say what a viewer is allowed to do without reading every handler.
Four inputs, one answer
Every access question has the same four parts:
- Subject: who is asking, with what they are (their team memberships, their role in each, when their contract ends).
- Action: what they want to do.
- Resource: the thing, with what it is (its team, its organization, whether it is archived).
- Context: the circumstances (the current time, the request's channel).
So the whole system is one function:
type Decision = { allow: true } | { allow: false; reason: string };
function authorize(
subject: Subject,
action: Action,
resource: Project,
context: Context,
): Decision;A role is still there. It is just one attribute of the subject, read by the rules that care about it.
Deny by default
The function starts from no, and each rule can only turn it into a yes for the action it covers. Anything nobody wrote a rule for is refused.
type Action = "view" | "edit" | "archive";
type Membership = { teamId: string; role: "viewer" | "editor" };
type Subject = {
id: string;
orgOwnerOf: string[];
memberships: Membership[];
accessEndsAt?: Date;
};
type Project = { id: string; orgId: string; teamId: string; archived: boolean };
type Context = { now: Date };
const deny = (reason: string): Decision => ({ allow: false, reason });
export function authorize(
subject: Subject,
action: Action,
project: Project,
context: Context,
): Decision {
if (subject.accessEndsAt && context.now >= subject.accessEndsAt) {
return deny("access has ended");
}
const membership = subject.memberships.find(
(m) => m.teamId === project.teamId,
);
switch (action) {
case "view":
return membership ? { allow: true } : deny("not on the project's team");
case "edit":
if (project.archived) return deny("project is archived");
return membership?.role === "editor"
? { allow: true }
: deny("not an editor on the project's team");
case "archive":
return subject.orgOwnerOf.includes(project.orgId)
? { allow: true }
: deny("not an owner of the organization");
default:
return deny(`no rule for ${action satisfies never}`);
}
}The satisfies never line is the type system's version of deny by default: add a new action to the union and forget its rule, and the build fails before a request ever reaches the fallback.
Every refusal says why
A bare false is useless at the moment you need it most, when someone reports that they cannot do something they should be able to. The reason string is cheap to write and turns that conversation from guesswork into a log search.
const decision = authorize(user, "edit", project, { now: new Date() });
if (!decision.allow) {
log.info("access denied", {
userId: user.id,
projectId: project.id,
action: "edit",
reason: decision.reason,
});
return res.status(403).json({ error: "You can't edit this project." });
}The user sees a plain message. The log sees which rule said no.
Every route asks the same question
The value of one function is that there is nowhere else to put an access rule. A route handler loads the resource, builds the subject and context, and asks:
app.patch("/projects/:id", async (req, res) => {
const project = await projects.find(req.params.id);
if (!project) return res.sendStatus(404);
const decision = authorize(req.user, "edit", project, { now: new Date() });
if (!decision.allow)
return res.status(403).json({ error: "You can't edit this project." });
await projects.update(project.id, req.body);
res.sendStatus(204);
});A test per allow and per deny
Because the rules are plain code with no framework in sight, they are trivial to test, and every rule gets at least two tests: one that proves it allows what it should, one that proves it refuses what it should.
const now = new Date("2026-06-01T12:00:00Z");
const project = { id: "p1", orgId: "o1", teamId: "t1", archived: false };
const editor = {
id: "u1",
orgOwnerOf: [],
memberships: [{ teamId: "t1", role: "editor" as const }],
};
it("lets an editor on the team edit", () => {
expect(authorize(editor, "edit", project, { now })).toEqual({ allow: true });
});
it("refuses an edit to an archived project, even for an editor", () => {
expect(
authorize(editor, "edit", { ...project, archived: true }, { now }),
).toEqual({
allow: false,
reason: "project is archived",
});
});
it("refuses everything once a contractor's access has ended", () => {
const contractor = {
...editor,
accessEndsAt: new Date("2026-05-31T00:00:00Z"),
};
expect(authorize(contractor, "view", project, { now }).allow).toBe(false);
});Passing now in as context, instead of reading the clock inside the function, is what makes the contract rule testable at all.
What it costs
The honest trade-off: you load the resource before you can decide, so a refused request still costs a read. In practice you were loading it anyway to return a 404 for a missing project, and one read is a small price for rules you can find in one place.
The other cost is discipline. One function only stays one function if nobody adds a quick role check in a route "just this once". The tests help there, because a rule that is not in authorize has no test to prove it, and that gap is easy to spot in review.