Skip to content

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:

crates/features/src/users/http/controller.rs
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)].

crates/features/src/users/entities/user.rs
#[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,
crates/features/src/authz/ability.rs
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.

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 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 500 and one error line, a wire row answered a caller it was not judged for, naming the unit as its mounted line 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: AbilityGuard bound on the field answers as it does bound at /graphql’s request;
  • a push to other connections (WsServer’s broadcast, 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 Model on your event and build the wire row in the stream.
crates/features/src/posts/graphql/resolver.rs
#[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.

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.

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.

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 narrowedone .fields grantconditional on the row
the judged row: build and serialize31.4 µs23.7 µs31.7 µs
no authorization at all24.6 µs24.7 µs24.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.