Response masking
Each wire row is judged whole where #[expose]'s conversion builds it: a column the caller's grant withholds holds no value, on every edge and in every shape.
The third layer of authorization happens where you build the answer, not after
it: User::from(&row) judges the row for the caller whose ability is
installed there. A column their grant withholds is not in the wire row at all —
it reads null — a row their grants refuse answers nobody, and the row
remembers who judged it, so it answers that caller and no one else. Nothing reads
your reply back, and nothing in your handler calls a mask.
Declare it — #[authorize], then build the rows
Section titled “Declare it — #[authorize], then build the rows”#[authorize(Read, user::Entity)] declares the route’s posture: the class gate
runs with the route’s guards, and the handler reads under the caller’s ability.
Build the exposed type from the rows the service read, as you always have:
use nest_rs::authz::Read;use nest_rs::http::Json;
#[get("/")]#[authorize(Read, user::Entity)]async fn list(&self) -> Result<Json<Vec<User>>> { Ok(Json(self.svc.directory().await?))}directory is a service method returning Result<Vec<User>, ServiceError> —
the Model → User conversion lives there, and that conversion is where each
row is judged. The same declaration and the same conversion serve GraphQL
(#[query], #[mutation], #[subscription]), WebSocket messages and MCP tools
and resources.
What a grant may withhold — #[expose(nullable)]
Section titled “What a grant may withhold — #[expose(nullable)]”A grant’s .fields on Read names the columns a caller may read. Every other
column reads null in their rows, so the column has to be one the wire can
answer null for: an Option column, or one you declare with
#[expose(nullable)].
#[expose]pub id: Uuid,#[expose(nullable)]pub org_id: Uuid,#[expose(input(create, update), validate(length(min = 1)))]pub name: String,#[expose(input(create, update), validate(email), nullable)]pub email: String,ab.can(Action::Read, user::Entity) .when(|p| p.eq(user::Column::OrgId, actor.org_id)) .fields([user::Column::Id, user::Column::Name]);A member then reads {"id": "…", "org_id": null, "name": "Ada", "email": null, …}
on HTTP and WebSocket, email: null on GraphQL and in MCP’s structured content.
The schema says so on every edge: the field is nullable, its description says the
caller’s ability may withhold it, and its key is still required, since a reply always
writes it — OpenAPI’s and MCP’s required and GraphQL’s ! stay true. A
belongs_to field says the same on GraphQL, where it reads null for a key or a row
the caller may not read. A column you do not declare is never withheld: a grant on Read or
Manage leaving one out fails when the ability builds, naming the column and the
key:
malformed authorization rule: the grant for `Read` on `users::Entity` withholds `email` in `.fields`, which a reply cannot answer null — declare the column `#[expose(nullable)]` on `email`, or name it in `.fields`The primary key names its row and takes no nullable: every reply’s grant reads
it. A reply reads Read’s grants whatever its posture’s action — .fields on
Update or Create names what a write may set, never what a reply shows.
Each row is judged on its whole row
Section titled “Each row is judged on its whole row”The judgement runs on the Model the service read, every column of it, so a
condition on any column is decided in memory: with a grant of every column on the
caller’s own row and of id and name on the others, the caller’s own email ships
and the others’ read null. A rule the row cannot decide — a relation, two value
types only the database compares — counts as the Repo read that admitted the row
counted it: a row out of Repo::scoped(Read) passed (OR grants) AND NOT (OR denials), so when no decided grant matches, an undecided one did, and the row
keeps the columns every such grant permits.
A row the caller’s grants refuse never ships as an empty object: in a GraphQL
mutation’s reply it answers its key alone, which names the row the write wrote, and
refuses every other column FORBIDDEN; on any other operation it refuses every
column, its key included; and elsewhere the reply is refused 403 — a write-only
caller’s write answers its key on GraphQL and nothing on HTTP. A list a body built
by hand holding such a row fails the whole reply closed; a Repo read never hands
it one.
A row answers the caller who judged it
Section titled “A row answers the caller who judged it”A wire row carries the id of the ability that judged it, and a private proof no
struct literal can supply — Thing { … } outside the decorator does not compile —
and it has no Deserialize. Its Serialize and each of its GraphQL columns check
that the ability installed where it answers is that one, so:
- a row kept in a cache, or carried into another request, answers no one: the
reply fails with
500and oneerrorline,a wire row answered a caller it was not judged for, naming the unit as itsmountedline does; - a
#[field_resolver]whose parent is such a row, or one the caller may not read, refuses before it runs, as the parent’s own columns refuse, so nothing it derives from the parent ships; - a GraphQL root field’s answer resolves under the ability its own unit judged its
rows by — the one its request carried, or the one the field’s own guards attached
where the request carried none — and so do the field resolvers below it, the
batches its relations read and a subscription’s items:
AbilityGuardbound on the field answers as it does bound at/graphql’s request; - a push to other connections (
WsServer’sbroadcast,emit_to,emit) refuses a row judged for the caller pushing it — no recipient’s ability judged it — and takes a row a job built, which holds every exposed column for no caller and answers nowhere else outside a job: kept in a cache and answered by a route, it fails as another caller’s; - a subscription builds its rows where the socket polls its stream, so each is
judged for its subscriber: carry the
Modelon your event and build the wire row in the stream.
#[subscription]#[authorize(Read, PostEntity)]async fn post_published(&self) -> impl Stream<Item = Post> { self.bus .stream::<PostPublishedEvent>() .map(|event| Post::from(&event.post))}A subscription’s item is a push no read filtered, so a rule only a read could
decide grants nothing there, and an item a refusal makes leaves the stream — a row,
a list’s rows, a row inside an Option or a Result — so a subscriber learns
nothing of a push they may not read. An object of your own holding the row arrives,
its row answering no column, the key included: stream the row itself where a
subscriber must not learn a push happened.
Every shape holds only what the row holds
Section titled “Every shape holds only what the row holds”Since a withheld column is no value in the row, there is nothing for any shape to
leak: a scalar a body builds (Json<Vec<User>> in GraphQL), an object holding a
row or copying its columns (#[graphql(flatten)]), a map column, a column renamed
onto a field resolver’s name — each holds the row as it was judged. A row a
scalar holds that refuses its caller — one judged for another, kept in a Json —
fails its root field with the refusal’s code rather than the null async-graphql
writes for a value it cannot serialize, its line naming that field. A generated
loader answers wire rows too, judged for the caller whose request runs the batch,
so a body reading writers.load_one(id).await?.and_then(|row| row.email) reads
None where the grant withholds the email.
A belongs_to relation reads its link off the judged row, so a key the grant
withholds is no link to follow and the relation reads null. A has_many groups
its children by their key inside the batch, each child judged on its own; the
relation’s #[expose] is its visible opening.
What stays the body’s own line
Section titled “What stays the body’s own line”No type tells a column a body copies into a value of its own from a column it
derives: initials(row.name) and row.email in a DTO read alike. A body reading a
column off a whole Model and answering it as its own value is that body’s
visible line, read in review — as is a body serializing a row by hand. A method
answering a Model itself, whatever wraps it and whatever it derives, does not
compile: return the exposed type, built from the row, and the judgement is the
framework’s.
What it costs
Section titled “What it costs”Measured in release on a 100-row list of a user-shaped entity (6 exposed columns,
3 hidden), Vec<Model> to bytes under an ability eight ambient values deep:
| no column narrowed | one .fields grant | conditional on the row | |
|---|---|---|---|
| the judged row: build and serialize | 31.4 µs | 23.7 µs | 31.7 µs |
| no authorization at all | 24.6 µs | 24.7 µs | 24.6 µs |
On GraphQL each resolved column checks who judged its row: 600 checks cost about 4.3 µs. An app with no field grant pays the judgement of an unconditional grant and nothing else.