@nxgt/shared-graphql 2.0.1 → 3.0.0

package/docs/guide/permissions.md

@@ -0,0 +1,220 @@
+# Permissions: `@permission`, `useKetoChecks`
+
+An Ory-native API asks Keto one question per object: **may this caller
+`view` `Note:n1`**. This page is how a schema asks it, what answers it, and
+what happens when the answer cannot be had.
+
+## Wiring
+
+```ts
+import { createOry } from '@nxgt/ory-sdk';
+import {
+	createMaskError,
+	type OryGraphQLContext,
+	SHARED_SCHEMA_PATH,
+	loadTypeDefs,
+	useKetoChecks,
+	useOryAuth,
+} from '@nxgt/shared-graphql';
+import { createSchema, createYoga } from 'graphql-yoga';
+
+const ory = createOry({ /* … */ });
+
+const yoga = createYoga<{}, OryGraphQLContext>({
+	schema: createSchema({
+		typeDefs: loadTypeDefs(SHARED_SCHEMA_PATH, './src/**/*.graphqls'),
+		resolvers,
+	}),
+	plugins: [
+		useOryAuth(ory), // puts `ory`, `user`, `claims`, `token` on the context
+		useKetoChecks(ory, { namespaces: ['Note', 'Folder'] }),
+	],
+	maskedErrors: { maskError: createMaskError(translate) },
+});
+```
+
+`useOryAuth` is needed: a guarded field reads `ory.subject`, which it puts on
+the context — without it every guarded field answers `UNAUTHENTICATED`.
+`createMaskError` is optional for the denials, which carry their own status,
+and is what translates their message with your `translate` and turns an
+outage into a 503 — see [errors](./errors.md).
+
+A schema assembled in code, with no `SHARED_SCHEMA_PATH`, takes the
+declaration as a string:
+
+```ts
+import { PERMISSION_DIRECTIVE_SDL } from '@nxgt/shared-graphql';
+
+createSchema({ typeDefs: [PERMISSION_DIRECTIVE_SDL, typeDefs], resolvers });
+```
+
+It equals `graphql/directives/permission.graphqls` — a spec parses and prints
+both. `KETO_DIRECTIVES_SDL` is the same string.
+
+## `@permission`
+
+```graphql
+directive @permission(
+	name: String!
+	type: String!
+	id: String
+	onDeny: PermissionDenial! = NOT_FOUND
+	message: String
+) repeatable on FIELD_DEFINITION
+```
+
+| Argument | Meaning |
+| --- | --- |
+| `name` | the permit asked of Keto — `view`, `edit`; a plain relation works too |
+| `type` | the Keto namespace — `Note` |
+| `id` | where the object id is read: `args.<path>` or `parent.<path>`; `args.id` when omitted |
+| `onDeny` | `NOT_FOUND` (default) or `FORBIDDEN` |
+| `message` | the i18n key the denial carries |
+
+### The 404-then-403 ladder
+
+Repeated `@permission`s are AND, evaluated **in declaration order**, and each
+answers its own `onDeny`:
+
+```graphql
+updateNote(id: ID!, input: UpdateNoteInput!): Note!
+	@permission(name: "view", type: "Note")
+	@permission(name: "edit", type: "Note", onDeny: FORBIDDEN)
+```
+
+| Caller holds | Answer |
+| --- | --- |
+| nothing | `NOT_FOUND` (404) — the same as an id that never existed, so ids cannot be probed |
+| `view` | `FORBIDDEN` (403) — they can already see it, so "you may not change it" is honest |
+| `view` and `edit` | the resolver runs |
+
+An anonymous caller is `UNAUTHENTICATED` (401) before Keto is asked anything.
+
+### Where the id comes from
+
+```graphql
+note(id: ID!): Note @permission(name: "view", type: "Note")
+noteByKey(key: ID!): Note @permission(name: "view", type: "Note", id: "args.key")
+deleteNotes(ids: [ID!]!): Boolean @permission(name: "delete", type: "Note", id: "args.ids")
+
+type Note {
+	ownerId: ID!
+	owner: Person @permission(name: "view", type: "Person", id: "parent.ownerId")
+}
+```
+
+A **list** requires the permit on every element, and stops at the first
+refusal. `source.<path>` is accepted as the same root as `parent.<path>`.
+
+A path that resolves no id at request time — a nullable argument nobody
+passed, a parent field that was not loaded — is a wiring error (500), never an
+allow.
+
+### Or, in the model
+
+There is no OR between `@permission`s. When a field is open to owners *or*
+editors, say so in the Keto model — a permit that unions the two relations —
+and ask that permit.
+
+### Wording a refusal
+
+`message` defaults to the shared `errors.not-found` /
+`errors.insufficient-permissions`. Set it whenever the service behind the field
+refuses the same object with a domain message:
+
+```graphql
+note(id: ID!): Note
+	@permission(name: "view", type: "Note", message: "notes.errors.not-found")
+```
+
+Two layers guard these fields — the directive and the service's own access
+check — and if they word the same 404 differently, the wording tells a caller
+which one refused: a generic message means "you may not", a domain one "it is
+gone". That is the distinction `NOT_FOUND` exists to hide.
+
+## `@check` — removed in 3.0
+
+The list-of-lists form is gone. Rewrite each term as a `@permission`, and move
+an OR into the Keto model — [the migration guide](./migrating-to-3.md#2-check-is-removed)
+has the before and after. A `@check` left in a schema does not boot: see
+[troubleshooting](../troubleshooting.md).
+
+## Refused at build
+
+`applyKetoChecks` — which `useKetoChecks` runs on every schema change — reads
+every `@permission` when the schema is built, and throws a `TypeError` naming
+`Type.field` for:
+
+| Mistake | Message starts |
+| --- | --- |
+| a path naming no root | ``@permission on Query.note: `id` must be "args.<path>", …`` |
+| an argument the field does not declare | ``… `id` reads "args.id", but the field declares noteId`` |
+| an empty `name` or `type` | ``… every term needs `namespace`, `permit` and `id` …`` |
+| a namespace outside `namespaces` | `… unknown namespace "Noet" — known: Note, Folder` |
+| a guard on an interface field | `Node.id: @permission on an interface field guards nothing …` |
+| a `@check` of 2.x's shape | `@check on Query.note: @check was removed in @nxgt/shared-graphql 3.0 …` |
+
+`namespaces` is optional. Without it a namespace is taken on trust, and a
+misspelt one answers `false` for ever — Keto does not error on a namespace it
+does not know. Pass the namespaces of your OPL document to make that a boot
+failure.
+
+`applyKetoChecks` leaves a field it already guarded alone, so a field is never
+wrapped twice, and a field it has not — the other half of a merged schema —
+is guarded when it runs again — as is a field whose resolver was replaced
+since (`addResolversToSchema`, a merge with resolvers).
+
+On a subscription, a `@permission` whose `id` reads `args.*` is asked before
+`subscribe`, so a refused subscription opens no stream. One that reads
+`parent.*` has no event to read yet: it is asked of each event instead, and a
+refused event answers its denial while the stream stays open.
+
+## From a resolver
+
+```ts
+import { can, denial, type OryGraphQLContext, requireUser } from '@nxgt/shared-graphql';
+import { ErrorCode } from '@nxgt/shared-exceptions';
+
+const resolvers = {
+	Mutation: {
+		archive: async (_: unknown, { id }: { id: string }, ctx: OryGraphQLContext) => {
+			const user = requireUser(ctx);
+			if (!(await can(ctx, { name: 'edit', type: 'Note', id }))) {
+				throw denial(ErrorCode.Forbidden, 'notes.errors.read-only');
+			}
+			return notes.archive(id, user.sub);
+		},
+	},
+};
+```
+
+- `requireUser(ctx)` returns `ctx.user`, or throws an `UNAUTHENTICATED`
+  denial (401).
+- `can(ctx, { name, type, id })` returns Keto's answer. It throws
+  `UNAUTHENTICATED` with no caller, names the missing plugin without
+  `useKetoChecks`, and lets `OryUnavailable` through on an outage — it never
+  answers `false` for a question it could not ask.
+
+## The per-request memo
+
+`useKetoChecks` puts one `ketoChecks` function on each request's context. It
+**batches** the distinct questions of one tick into a single
+`POST /relation-tuples/batch/check` and **memoises** answers for the request.
+A field guarded by `@permission(view)` and a service that asks the same
+question through `can` pay for one round trip between them.
+
+A batch that failed is not remembered: every question in it rejects with the
+outage, and the next ask goes back to Keto.
+
+## An outage is not a no
+
+`@nxgt/ory-sdk` throws `OryUnavailable` when Keto cannot answer. Nothing in
+this package catches it as a denial: the directive, `can` and the memo all
+let it through, and `createMaskError` / `createFormatError` answer it
+`SERVICE_UNAVAILABLE` with HTTP 503. See [errors](./errors.md).
+
+## Not a check: lists
+
+"Which notes may I see" is a Keto query folded into the database filter before
+the read, not a directive. A directive on a list field would have to fetch
+everything and filter after, which makes `totalCount` and the cursors lie.

package/docs/roadmap.md

@@ -0,0 +1,71 @@
+# Roadmap
+
+What `@nxgt/shared-graphql` does now, what is planned, and what it will not do.
+
+## Now
+
+The GraphQL layer for Yoga and Apollo services: shared SDL, scalars and
+directives shipped in `graphql/`, `useOryAuth`, `useAuthenticated` and
+`useKetoChecks` for an Ory-native API, `useAuth` behind a trusted gateway,
+denials that carry their status, `createMaskError` / `createFormatError`,
+dataloaders, subscriptions over Redis, uploads and the Hono integration.
+
+## Next
+
+Nothing planned that changes what a consumer gets. See Later.
+
+## Later
+
+- **Batching a list argument's ids** into one Keto batch rather than one
+  question per id in order.
+
+## Not planned
+
+- **A directive on a list field** that filters after the read. "Which objects
+  may I see" is a Keto query folded into the database filter.
+- **OR between directives.** It belongs in the Keto model.
+- **Turning an Ory outage into a denial or an anonymous caller**, under any
+  option. It is a 503.
+
+## Shipped
+
+### 3.0 — [migration guide](./guide/migrating-to-3.md)
+
+- **The caller comes from a verified source only**: `useAuth()` and
+  `extractJwtPlugin()` read `extensions` only for a request
+  `trustedGateway` vouches for — `gatewaySecret({ secret })` by default — and
+  refuse to start without one.
+- **`@check` removed**, leaving `@permission`; a `@check` left in a schema is
+  refused at build, and the mistakes 2.x only warned about on it are
+  `TypeError`s.
+- **`@authenticated(type: [String!])`**, enforced by `useAuthenticated()`:
+  401 for no caller, 403 for a caller of another type. Federation's
+  argument-less declaration is read as "any caller".
+- **Denials are `GraphQLError`s** with `extensions { code, http { status } }`
+  — `denial(code, message?)` — so a server without `createMaskError` answers
+  401/403/404 rather than a masked 500.
+- **Five unused dependencies dropped**: `@graphql-hive/gateway`,
+  `@envelop/generic-auth`, `@envelop/extended-validation`,
+  `@hono/zod-validator`, `zod`.
+- **Peers bounded**: `@nxgt/ory-sdk` `>=0.1.0 <1`, `graphql` `^16.9.0 ||
+  ^17.0.0`.
+- **`sandboxExplorer`**, the sandbox helper's corrected name.
+
+### 2.1
+
+- **`@permission(name, type, id, onDeny, message)`**, the flat form, answered
+  with `@check` in declaration order; `@check` deprecated in its favour.
+- **More refused at build**: an argument the field does not declare, a
+  namespace outside the model (`namespaces`), a guard on an interface field —
+  each a `TypeError` naming the field for `@permission`, and a warning for
+  `@check`, which booted with the first and last before.
+- **`requireUser`, `can` and `OryGraphQLContext`** for resolvers, through the
+  same per-request memo.
+- **The directive SDL as strings** — `PERMISSION_DIRECTIVE_SDL`,
+  `CHECK_DIRECTIVE_SDL`, `KETO_DIRECTIVES_SDL` — held equal to the files.
+- **graphql 17**: `graphql` is a peer, `^16.4.2 || ^17.0.0`, and the suite
+  runs on both.
+- **An outage under Apollo is a 503 too**, and one from a second copy of
+  `@nxgt/ory-sdk` is still recognised.
+- **Internal messages masked**: a plain `Error` a resolver threw no longer
+  reaches the client through `createMaskError`.

package/docs/troubleshooting.md

@@ -0,0 +1,273 @@
+# Troubleshooting `@nxgt/shared-graphql`
+
+Each entry is headed by the message you see; the parts in `<angle brackets>`
+vary. Messages thrown when the server starts or the schema is built are
+`TypeError`s, and stop the server from booting; the schema ones name
+`Type.field` after the directive that carries the mistake. The last section
+holds the traps that throw nothing.
+
+Upgrading from 2.x, most of these come from [the
+migration](./guide/migrating-to-3.md).
+
+## When the server starts
+
+### ``useAuth(): name the gateway allowed to set the caller — useAuth({ trustedGateway: gatewaySecret({ secret }) }). …``
+
+Also `extractJwtPlugin(): name the gateway allowed to set the caller — …`.
+
+Since 3.0 both need to know which gateway may put the caller in the request's
+`extensions`, which a client can otherwise write. Pass one:
+
+```ts
+const trustedGateway = gatewaySecret({ secret: process.env.GATEWAY_SECRET! });
+createYoga({ plugins: [useAuth({ trustedGateway })] });
+new ApolloServer({ plugins: [extractJwtPlugin({ trustedGateway })] });
+```
+
+`extractJwtPlugin` is a function now: `plugins: [extractJwtPlugin]` passes
+the function itself, not a plugin. An API that authenticates its own callers
+uses `useOryAuth(ory)` and needs neither.
+
+### ``gatewaySecret(): `secret` must be a string of at least 16 characters — is its environment variable set?``
+
+The secret is missing or shorter than 16 characters — most often an
+environment variable that is not set where the server runs. Set it, to the
+same value the gateway sends.
+
+### `Cannot find module '@envelop/generic-auth'`
+
+Or `@graphql-hive/gateway`, `@envelop/extended-validation`,
+`@hono/zod-validator`, `zod`. 3.0 dropped them from its dependencies — nothing
+here imported them — and your app was using the copy this package brought.
+Declare it yourself:
+
+```sh
+bun add @envelop/generic-auth
+```
+
+### ``Module '"@nxgt/shared-graphql"' has no exported member 'sandboxExpolorer'. Did you mean 'sandboxExplorer'?``
+
+The typo was corrected in 3.0, with no alias. Import `sandboxExplorer`.
+
+## When the schema is built
+
+### ``@check on <Type.field>: @check was removed in @nxgt/shared-graphql 3.0 — write one @permission(name: "<permit>", type: "<namespace>") per term, and move an OR into the Keto model``
+
+The schema declares 2.x's `@check` itself and a field still uses it. This
+package no longer answers it, so the field would boot unguarded; it is refused
+instead. Rewrite it:
+
+```graphql
+# before
+note(id: ID!): Note @check(permissions: [[{ namespace: "Note", permit: "view" }]])
+# after
+note(id: ID!): Note @permission(name: "view", type: "Note")
+```
+
+Then drop your `@check` declaration. [The migration guide](./guide/migrating-to-3.md#2-check-is-removed)
+covers an AND and an OR.
+
+### `Unknown directive "@check".`
+
+The same, in a schema that loads this package's `graphql/` and nothing else:
+3.0 no longer ships `@check`'s declaration. Rewrite the field as above.
+
+### ``@permission on <Type.field>: `id` must be "args.<path>", "parent.<path>" or "source.<path>", got "<id>"``
+
+The `id` argument names no root. Prefix it:
+
+```graphql
+note(noteId: ID!): Note @permission(name: "view", type: "Note", id: "args.noteId")
+```
+
+### ``@permission on <Type.field>: `id` reads "args.<name>", but the field declares <arguments>``
+
+The path reads an argument the field does not have — usually the default
+`args.id` on a field whose argument is named otherwise. graphql-js never puts
+an undeclared argument on `args`, so every request would have failed. Name the
+argument in `id`, or read the parent with `parent.<path>`.
+
+In 2.x a `@check` booted with this and logged a warning; a `@permission`
+refuses it.
+
+### ``@permission on <Type.field>: every term needs `namespace`, `permit` and `id`, got <term>``
+
+`@permission(name: "", type: "Note")`: an empty `name` or `type`. Name both.
+
+### `@permission on <Type.field>: unknown namespace "<type>" — known: <namespaces>`
+
+You passed `namespaces` to `useKetoChecks` / `applyKetoChecks`, and the field
+names one outside them — most often a typo. Keto would have answered `false`
+for ever, without an error. Fix the name, or add the namespace to the list
+when the OPL document gained it.
+
+### `<Type.field>: @permission on an interface field guards nothing — no resolver runs there. Put it on each implementing type's field`
+
+A resolver runs on an object type's field, never on an interface's. Move the
+directive to every implementing type:
+
+```graphql
+interface Node { id: ID! }
+type Note implements Node {
+	id: ID!
+	body: String @permission(name: "view", type: "Note", id: "parent.id")
+}
+```
+
+In 2.x a `@check` there booted with a warning; a `@permission` is refused.
+
+### ``@authenticated on <where>: `type: []` admits no caller — name a type, or drop `type` ``
+
+`<where>` is where the directive sits: `Type.field`, or a type, interface,
+scalar or enum name.
+
+An empty list admits nobody. Name the kinds of caller, or drop `type` to
+admit any caller.
+
+### `@authenticated on <where>: unknown type "<type>" — known: <types>`
+
+`type:` names a value outside the caller types `useAuthenticated` knows —
+`session` and `token` by default. Fix the name, or list your own:
+
+```ts
+useAuthenticated({ types: [...CALLER_TYPES, 'service'] });
+```
+
+### ``@authenticated on <Type.field>: the field's, its type's and its interfaces' `type`s have none in common — no caller could pass``
+
+Every `@authenticated` that applies to a field must hold — the field's, its
+type's, its interfaces'. Two of them name disjoint types, so no caller could
+reach the field. Drop or widen one.
+
+### `Unknown argument "type" on directive "@authenticated".`
+
+The schema declares `@authenticated` without an argument — federation's
+declaration, imported through `@link`, or your own — and a field writes
+`type:`. In a subgraph keep federation's form and drop `type:`; in a schema
+of your own, load `SHARED_TYPE_DEFS` or `AUTHENTICATED_DIRECTIVE_SDL` in place
+of your declaration.
+
+### `@nxgt/shared-graphql: no package root`
+
+Thrown when the package is imported, if no `package.json` sits anywhere
+above its files — a bundle copied into an image without one. The more common
+case throws nothing: a bundler inlined the package into your app's bundle, the
+walk finds your app's `package.json`, and `SHARED_SCHEMA_PATH` points at
+`<app>/graphql/**`, which loads no SDL. Either way, mark
+`@nxgt/shared-graphql` external in the bundler so it stays on disk as
+installed.
+
+### `Directive "@permission" argument "name" of type "String!" is required, but it was not provided.`
+
+On graphql 17: `Argument "@permission(name:)" of type "String!" is required, but it was not provided.`
+
+Your schema declares its own `@permission`, and you load this package's
+`graphql/**/*.graphqls` (`SHARED_SCHEMA_PATH`) beside it: `mergeTypeDefs`
+merges the two declarations into one with both sets of arguments, and your
+usages lack `name` and `type`. `@permission` and `PermissionDenial` are
+names this package ships. Load only the folders you need —
+`graphql/scalars`, `graphql/schema` — or rename your directive.
+`useKetoChecks` itself leaves a `@permission` without `name` and `type`
+alone.
+
+### `Cannot use GraphQLSchema "<schema>" from another module or realm.`
+
+Two copies of `graphql` are installed: `graphql` is a peer of this package
+(`^16.9.0 || ^17.0.0`), so your app must declare it once, and every GraphQL
+library must resolve that one. Add `graphql` to your `dependencies` if it was
+only there through this package, and check with `bun pm ls graphql` (or
+`npm ls graphql`) that one version remains. graphql runs this check only
+when `NODE_ENV` is not `production`; in production two copies fail later,
+with less telling errors.
+
+## When a request runs
+
+### `<Type.field>: "<path>" resolved no object id`
+
+A plain `Error` thrown inside a resolver: `createMaskError` answers the client
+`Unexpected error.` (`INTERNAL_SERVER_ERROR`); the text is in the server log,
+and in `extensions.debugMessage` when `isDev` is on.
+
+The path was valid, but at request time it pointed at nothing — a nullable
+argument nobody passed, an empty list, a parent field the parent resolver did
+not load. It is a 500, never an allow. Make the argument required, or make
+sure the parent object carries the field.
+
+### `<Type.field>: no checker on the context — useKetoChecks(ory) is not registered`
+
+The schema was transformed with `applyKetoChecks` but the plugin that puts the
+per-request checker on the context is missing. Register
+`useKetoChecks(ory)` after `useOryAuth(ory)`. Answered as the previous entry.
+
+### `can(): no checker on the context — useKetoChecks(ory) is not registered`
+
+The same, from `can`.
+
+### `ory: keto is unavailable` with `SERVICE_UNAVAILABLE` and HTTP 503
+
+Keto (or Kratos, Hydra — the name varies) did not answer. This is on
+purpose: an outage is never turned into a denial or an anonymous caller. The
+client can retry; `extensions.debugMessage` carries what the SDK saw.
+
+### A denial's message reads `notes.errors.not-found`
+
+A `@permission(message: "notes.errors.not-found")`, or your own
+`denial(code, key)`, reached the client untranslated. A denial translates its
+key with `@nxgt/i18n`'s own resources, which do not hold your app's keys.
+Register the mask with your translator:
+
+```ts
+createYoga({ maskedErrors: { maskError: createMaskError(translate) } });
+```
+
+Under Apollo Server, the counterpart is `formatError: createFormatError(translate)`.
+
+### `Unexpected error.` with `INTERNAL_SERVER_ERROR` where a service's 404 or 403 was expected
+
+A service threw a `CustomException` and `createMaskError` is not registered,
+so Yoga masks it as any non-GraphQL error. The directives and `requireUser` /
+`can` are not concerned — their denials carry their own status — but a
+service's `CustomException.notFound()` is. Register `createMaskError`, as
+above, or throw `denial(code, message)` from the resolver.
+
+### `Unexpected error.` where a resolver's own message used to reach the client
+
+`createMaskError` masks a plain `Error` a resolver threw, as Yoga's default
+does. Throw a `CustomException`, a `denial()` or a `GraphQLError` for a
+message meant for the caller.
+
+## Traps that throw nothing
+
+### Every caller is anonymous behind the gateway
+
+`useAuth({ trustedGateway })` reads no caller from a request that does not
+carry the gateway's proof. The gateway is not sending the header — or sends
+another secret — on its subgraph requests. Make it add
+`x-gateway-secret: <secret>` (or your `header`) to every one, with the same
+value the subgraph was given.
+
+### `FORBIDDEN` from `@authenticated(type:)` for a caller who should pass
+
+The caller's type is `context.ory.kind`, or `context.user.tokenType` without
+Ory. Behind a gateway that writes no `tokenType` in the `user` it forwards,
+every caller has no type, and every `type:` refuses them. Make the gateway
+write it, or drop `type:` on those fields.
+
+### A guarded field answers unguarded in the supergraph
+
+A subgraph composed by federation drops a directive it was not told to keep.
+Add `@composeDirective(name: "@permission")` and import the directive in the
+subgraph's `@link`.
+
+### `@authenticated(type:)` in a subgraph
+
+Federation declares `@authenticated` without an argument, and a subgraph
+imports that declaration. Keep it: `useAuthenticated` enforces it as "any
+caller". A `type:` restriction is for a schema that declares `@authenticated`
+through `SHARED_TYPE_DEFS` or `AUTHENTICATED_DIRECTIVE_SDL`.
+
+### `OryForbidden` from `ory.requireAllowed` is a 500
+
+`createMaskError` does not map `OryForbidden`: whether a refusal is a 404 or a
+403 is the caller's decision. In a resolver, use `can` and throw the
+`denial` you mean.

package/graphql/directives/permission.graphqls

@@ -0,0 +1,73 @@
+# The flat form of @check, and the name to write in a new schema.
+#
+# One @permission is one Keto question — "may the caller `name` this `type`" —
+# the same vocabulary as @nxgt/janus-graphql's @permission. Repeated, they are
+# AND, evaluated in declaration order with @check, each with its own onDeny.
+# An OR belongs in the Keto model (a permit that unions two relations), not in
+# the schema; @check keeps the list-of-lists form for the schemas that still
+# write one, and is deprecated in its favour.
+#
+# `useKetoChecks(ory)` answers both. The string export PERMISSION_DIRECTIVE_SDL
+# carries the same declaration, and a spec holds the two equal.
+
+"""
+What a refused @permission looks like from outside.
+"""
+enum PermissionDenial {
+	"""
+	The same answer as for an id that never existed, so ids cannot be probed.
+	The default.
+	"""
+	NOT_FOUND
+
+	"""
+	For a permission asked of an object the caller can already see: a viewer
+	asked to edit already knows it exists, and "you may not change it" is
+	honest.
+	"""
+	FORBIDDEN
+}
+
+"""
+The permission a field requires: the caller must hold the permit `name` on the
+`type` object whose id `id` points at.
+
+Repeatable, and repeated ones are AND, evaluated in declaration order — the
+404-then-403 ladder:
+
+    updateNote(id: ID!, input: UpdateNoteInput!): Note!
+      @permission(name: "view", type: "Note")
+      @permission(name: "edit", type: "Note", onDeny: FORBIDDEN)
+
+NOT for a field that answers a LIST the caller is entitled to: fold a Keto
+query into the database filter before the read instead.
+"""
+directive @permission(
+	"""
+	The permit asked of Keto, e.g. "view". A plain relation works too; Keto
+	answers `false`, not an error, for a name it does not know.
+	"""
+	name: String!
+
+	"""
+	The Keto namespace, e.g. "Note" — from the stack's OPL document.
+	"""
+	type: String!
+
+	"""
+	Where the object id is read: `args.<path>` or `parent.<path>`, dotted
+	paths allowed, `args.id` when omitted. A value that turns out to be a LIST
+	requires the permit on every element.
+	"""
+	id: String
+
+	onDeny: PermissionDenial! = NOT_FOUND
+
+	"""
+	The i18n key the denial carries, e.g. "notes.errors.not-found". Defaults to
+	`errors.not-found` / `errors.insufficient-permissions`, the shared keys.
+	Set it when the service layer words the same refusal with a domain message,
+	so the wording does not tell a caller which layer refused.
+	"""
+	message: String
+) repeatable on FIELD_DEFINITION