access-control · git:20261029.b929ced · 2026-10-29 · sha256 7f99630f1911f03b
access-control git:20261029.b929cedA
Immutable. This exact content never changes and is served at /api/v1/blob/7f99630f1911f03b.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_t5tnzehh3wae3rgc/7f99630f1911f03b0277c62c4e3bc6c6fa8bccca15f2939d1c1db0c9ad708454.json
Then /plugin install access-control@markdownregistry-t5tnzehh3wae3rgc in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: access-control
description: >-
Use when adding a permission, a role or an ownership rule, when code needs the connected
user or the tenant, when filtering a list by rights, or on an authz/* rule.
Authentication, authorization, access scopes, policies, RBAC, ABAC, ReBAC.
allowed-tools:
- Read
- Bash(npx ddd-ts-kit generate *)
- Bash(npx ddd-ts-kit check *)
- Bash(npx ddd-ts-kit list *)
- Bash(npx ddd-ts-kit describe *)
---
# Access control
Three questions, three places. API and examples: README of `@ddd-ts-kit/auth`.
| Question | Where | How |
|---|---|---|
| Who is calling? (authentication) | `src/platform/auth/authentication/`, at the boundary | an adapter of the `Authenticator` port turns the credential into a `Session` holding the `Actor`; a route hands `actorOf(...)` to the use case and declares its `security` |
| May this actor do this, on this? (authorization) | `application/authorization/` of the context | permissions as data, required by each use case, decided by the `Authorizer` port in a bus middleware before the handler runs |
| Is this valid at all? (invariant) | `domain/` | "an invoice cannot be paid twice" is not a permission and knows no actor |
The platform side lives in `<platformDir>/auth/`, one folder per question: `authentication/`
(the authenticator, the session of a request, the HTTP boundary), `authorization/` (the
authorizer behind the port, the guard of the buses, the access policies, the `Role` vocabulary,
the registry of permissions, the grants of every signed-in person), then the folder of the
model: `roles/`, `attributes/`, `relationships/` or `custom/`. A project generated before the
folders keeps them flat: read and write them there, or run `npx ddd-ts-kit platform-folders`
when the team asks for the move (it moves the whole platform: `composition/`, `observability/`,
`jobs/`, `audit/search-audit-entries/` too).
## A permission is mandatory
Nothing is reachable by default (`authz/declared`): the generator refuses a command or a
query without one of the two.
```bash
npx ddd-ts-kit generate command <ctx> <UseCase> --permission <aggregate>.<action> --grant <role> --json
npx ddd-ts-kit generate query <ctx> <UseCase> --public --json
```
- A permission is held by somebody: decide who when you declare it. With roles
(`stack.authz` `rbac`), `--grant <role>` writes `[Role.<Role>]: [<context>Permissions['<p>']]`
in `<platformDir>/auth/roles/roles.ts` and adds the role to `authorization/role.ts` when it is new. The
super-admin `*` alone does not count: a permission no role names is refused to everybody
else, and `check` warns (`authz/granted`). One meant for administrators only is granted to
`Role.Admin` by name. A grant to every signed-in person goes in `authorization/signed-in-grants.ts`.
Under attributes or relationships, `--grant` is refused: give the right in that model. Under
relationships a permission left on the context is held by its operators, and `check` warns
(`authz/granted`) until some source writes an `operator` relationship on that context (a provisioning
step, a bootstrap, the grant of a system actor) or every signed-in person holds it. A job or a handler that
sends a protected command acts as a system actor, which needs its own relationship in
`relationships/relate-system-actors.ts` (`generate job` writes it for a job, a handler by hand
needs it): `authz/system-actor-granted` is an error without it.
- The permission is named in the ubiquitous language (`invoice.issue`, not `admin.write`),
joins `<context>.permissions.ts`, and its words are checked
against the glossary.
- Declared style: `@Requires(permissions['invoice.issue'])` or `@Public()` on the message
class. Explicit style: `.requires(...)` or `.public()` where the handler is registered, which is
`<context>.module.ts`, or `<module>/<module>.module.ts` with `--module <module>` (the module
file keeps the context file short). Never a hand-written `application/authorization/*.policy.ts`
that returns declarations: a policy decides on one element.
- Nothing else for a plain permission: no check in the controller, none in the handler. The
generated handler spec already proves that an actor without it is refused.
- A guard is another thing: a control at the edge over a set of routes, named in `guards` of
a `@RouteGroup` or of a controller (`Authenticated`, `HasRole(Role.Auditor)`, `HasScope('invoices:read')`, `TenantMember`, `Public`, or a
guard of the project in `presentation/http/guards/*.guard.ts`). It reads the caller and the
request, answers 401 or 403 before the controller runs (before the request is read when it
decides on the caller alone, through `admit`), and never loads an element
(`presentation/guard-at-the-edge`). It never replaces the permission: a job or an event
handler sends the same command without passing any guard. Use a guard for what is true of
the whole set of routes (signed in, a role, the tenant of the path), a permission or a policy
for everything that depends on the element.
- A role is never a string in code: it is a key of the vocabulary `Role` of the platform
(`<platformDir>/auth/authorization/role.ts`), and `generate route-group <ctx> <Name> --role <role>` adds
the role there. A grant names the permission through its set,
`billingPermissions['invoice.issue']`, never by its id `'billing:invoice.issue'`.
- `npx ddd-ts-kit describe <ctx>` shows what each use case and route requires; the
permissions of a context are listed in its `CONTEXT.md`.
## A rule on one element
"Only the author may edit" depends on loaded state:
```bash
npx ddd-ts-kit generate policy <ctx> <Name> --permission <aggregate>.<action> --json
```
A policy is a named, pure, unit-tested class in `application/authorization/*.policy.ts`
(`@Policy(permission, { name: '<context>.<name>' })`); the handler loads the aggregate and
asks `Access.authorize(command.actor, permission, appointment)`, the loaded aggregate named after its concept. Every
handler of a use case requiring that permission must ask it: `authz/policy-asked` reports one that
does not, and at run time its result is refused with `PolicyNotAskedError` and rolled back. The
generators write the question about the message; replace the message by the loaded aggregate. A rule that holds whoever asks ("not after publication") is an invariant: it goes in
the aggregate.
## The resource of a use case under relationships
Under `stack.authz` `rebac`, `generate command` and `generate query` (not a search) write the
context as the resource, `{ resource: () => ({ type: 'context', id: '<context>' }) }`, and a
`// TODO(domain): name the <element> this command is about` next to it, which `todo` and `status`
list. The context is the right resource only for a use case on no element: declaring a service,
running a search (its scope narrows the ids). A use case about one element (change the
dependencies of a service, add a member to a team) names that element, once its message carries
the id:
```ts
@Requires(cataloguePermissions['service.change'], {
resource: (command) => ({ type: 'service', id: command.serviceId }),
})
```
and the schema derives the permission on that type (`service: { derived: { [cataloguePermissions['service.change'].id]: 'owning-member' } }`
in `elements` of `relationships/relationship-schema.ts`). The schema written by `init` derives on
`context` only the permissions no element derives: modelling a right on an element takes it away
from the operators of the context. A right left on the context is held by every operator of it,
and the project's bridge from roles to permissions (a member holds it) widens it to every
member: any member then acts on any element, and every spec written as a member of the owning
team stays green. When a search runs under the permission of its element, give the gate its own
permission (`service.search`, on the context) and keep the scope on the element's
(`service.view`), since the first is no longer held on the context once derived on the element.
`authz/resource-modelled` (an error under relationships) reports a requirement on the context for
a permission the schema derives on an element, and a search whose gate and scope share such a
permission; a schema or a resource it cannot read is reported too.
## Searches
Never load then filter in memory. `generate query ... --search` writes a handler that asks the
access scope of the actor (`all`, `none`, a set of ids, or a filter) and hands it to the read
port; the adapter turns it into the query.
A search across many elements asks two questions, under two permissions:
- **May the actor run it?** The requirement of the query. Under relationships it always names a
resource (`RESOURCE_REQUIRED` otherwise): the enclosing one the generator writes,
`{ resource: () => ({ type: 'context', id: '<context>' }) }` (see "The resource of a use case
under relationships" below for the use cases that are about one element). When an actor who reaches no
element must get 403 rather than an empty page, name the tenant of the actor instead,
`{ type: 'tenant', id: <its tenant> }`, with, on the type `tenant`, the derived relation
`[<ctx>Permissions['folder.search'].id]: via('folder', <ctx>Permissions['folder.view'].id)` and a
tuple `tenant:<id>#folder@folder:<id>` written with each element. That check reads the elements of the tenant one by one for an actor who holds none.
- **Which elements?** `Access.scope(query.actor, <context>Permissions['folder.view'], 'folder')`,
the permission of one element, mapped on its type: the relationships answer `ids`. An empty
page for an actor who reaches nothing is the right answer, not a leak.
Never put the permission the scope asks in `signed-in-grants.ts` to let the query past the bus:
what those grants cover lists `all` before the model is asked, so every signed-in person reads
every element. When anybody may run the search, grant there its own permission
(`folder.search`) and keep the scope on the permission of the element.
Prove it with the real authorizer (the schema, the mapping and an `InMemoryRelationTupleStore`
in `authorizationModule`), never `AllowAll` nor an answer written by hand: an element is absent
for an actor with no relation to it, absent for the actor of another element, and absent from
the page asked without any criterion.
## A field only some callers see
"The patient does not see the internal note" is a right on a field, not a role test in a
serializer or a query (`authz/fields-by-schema`, `authz/in-application`). Mark it on the schema of
the answer, and of the body when the caller sets it:
`withFieldAccess(schema, { internalNote: { read: { permission }, write: { permission }, subject } })`
of `@ddd-ts-kit/http`, decided through `Access` (`fieldDeciderOf`, which `presentation-of.ts`
of the platform wires). It is left out of JSON, XML and CSV alike for a caller who may not read
it, refused with 403 in a body from one who may not set it, absent or read-only in the form of
the route. The handler still authorizes the write itself, for the callers that are not HTTP. A
field shown or hidden is decided without being recorded; a field set is recorded.
The form of a route (`defineForm`) names the permission of its use case, asked as its
`@Requires` asks it: `requires: { permission, subject: (values) => ..., context: (values, actor)
=> ... }`. A caller who may not run the use case gets 403 instead of the form.
## The current actor
- **Use cases**: explicit, the first field of the command or query (`command.actor`).
Integration event handlers and jobs act as `systemActor('<context>.<name>')`.
- **Infrastructure** that needs it without being handed it (audit columns, tenant scoping,
log fields): the `ExecutionScope`, opened at the boundary for every request, consumed event
and job; `ActorContext` is a view of it. Neither is named nor read in `domain/` or
`application/` (`authz/actor-explicit`).
- **Domain**: never. Pass an identifier named for its role: `approve(approverId)`.
## Choosing the model
The owner's choice (`stack.authz`); all sit behind the one `Authorizer` port, so changing
later replaces an adapter and the permission mapping, not the handlers. Ask, in order, and
stop at the first answer that changes the model (the guide
`docs/guides/choosing-access-control.md` of the kit has a worked preset for each):
1. Does a right depend on **which element**? No: roles.
2. Do users **share** elements, **delegate**, or inherit along a **hierarchy**, and must a list
show what each one reaches? Yes: relationships (Zanzibar), in the PostgreSQL tuple store of
the project, or OpenFGA once it outgrows it.
3. Do rights follow **properties** or need **explicit refusals**? Yes: attribute policies over
roles. No: roles plus a policy per element rule.
4. Do **third parties** act with a limited credential? Add scopes: `HasScope` on the routes,
the vocabulary in `SessionScopes`.
5. Do **several customers** share the deployment? Add a tenancy strategy (skill
`ddd-ts-kit:persistence`), roles per tenant, `TenantMember` on the routes of tenant data.
| Model | Fits when | Costs |
|---|---|---|
| roles (`rbac`) | rights follow job functions | role explosion once rights depend on the element |
| attributes (`abac`) | rights depend on attributes of actor, resource, moment | rules spread out; needs tests |
| relationships (`rebac`) | rights follow relations: owner, member of, shared with | tuples to keep in sync; lists need care |
**Why was it refused.** Every authorizer of the kit answers `explain(request)` with the same
decision as `check` and a trace in words; `traceText(trace)` lays it out, `x` before what did
not hold. Use it in a spec or a console when a decision surprises, never in an answer or a log.
## Refuse these shortcuts
| Shortcut | Instead |
|---|---|
| `if (user.role === 'admin')` in a controller or a handler | a permission required by the use case; `HasRole(Role.Admin)` on the route group when the whole set of routes is for admins |
| a guard that loads the appointment to see who owns it | a policy on the permission of the use case |
| a policy declared and a handler that never asks it | `Access.authorize` in every handler of that permission |
| reading the user from a global or the request in a handler | `command.actor` |
| passing the request or the token inward | an `Actor`, mapped at the boundary |
| an `isAdmin` flag on an entity deciding access | roles or relations in the authorizer |
| `if (actor.roles.includes('staff'))` removing a field from an answer | `withFieldAccess` on the response schema |
| authorization in a repository | tenant scoping only there; rights in the application |
| a search permission given to every signed-in person to get it past the bus | a requirement on an enclosing resource; the signed-in grant would make the scope `all` (`authz/scope-narrows`) |
Finish with
`npx ddd-ts-kit check --rule authz/declared --rule authz/in-application --rule authz/actor-explicit --rule authz/fields-by-schema --rule authz/policy-asked --rule authz/granted --rule authz/scope-narrows --rule authz/resource-modelled --rule authz/system-actor-granted`.
Every decision, denials included, is recorded by the audit trail (skill
`ddd-ts-kit:cross-cutting`), the refusals of the guards at the edge too (`onGuardRefusal` of the
HTTP boundary, wired to `auditGuardRefusals`).