@nxgt/shared-graphql 2.0.1 → 3.0.0

package/docs/guide/authentication.md

@@ -0,0 +1,187 @@
+# Authentication: who is calling, and `@authenticated`
+
+A resolver reads the caller from `context.user`. This page is where that value
+comes from, which sources are trusted, and how `@authenticated` refuses a
+missing caller or one of the wrong kind.
+
+## The rule: a verified source, never the body alone
+
+The GraphQL request's `extensions` travel in the request body, which any
+client writes. So the caller comes from one of two places:
+
+| Source | Plugin | Verified by |
+| --- | --- | --- |
+| a Kratos session or a Hydra access token | `useOryAuth(ory)` | Ory, server-side, on every request |
+| what a gateway resolved and put in `extensions` | `useAuth()` / `extractJwtPlugin()` | the gateway's proof — `trustedGateway` — on every request |
+
+Anything else leaves the context without a caller.
+
+## `useOryAuth(ory)` — an API that authenticates its own callers
+
+```ts
+import { createOry } from '@nxgt/ory-sdk';
+import { useAuthenticated, useOryAuth } from '@nxgt/shared-graphql';
+
+const ory = createOry({ /* … */ });
+
+createYoga({ plugins: [useOryAuth(ory), useAuthenticated()] });
+```
+
+It reads `Authorization: Bearer`, then `X-Session-Token`, then the Kratos
+cookie, and puts `user`, `claims`, `token` and `ory` on the context. An Ory
+outage throws a 503 `SERVICE_UNAVAILABLE`, never an anonymous caller.
+
+## `useAuth()` and `extractJwtPlugin()` — behind a gateway
+
+A gateway that authenticated the caller can forward it to subgraphs in the
+request's `extensions`: `user` and `token` for `useAuth()` (Yoga),
+`payload` for `extractJwtPlugin()` (Apollo Server). Both read it **only** when
+`trustedGateway` holds for the request:
+
+```ts
+import { extractJwtPlugin, gatewaySecret, useAuth } from '@nxgt/shared-graphql';
+
+const trustedGateway = gatewaySecret({ secret: process.env.GATEWAY_SECRET! });
+
+createYoga({ plugins: [useAuth({ trustedGateway })] });
+new ApolloServer({ plugins: [extractJwtPlugin({ trustedGateway })] });
+```
+
+### `gatewaySecret({ secret, header? })`
+
+Holds for a request whose `header` — `x-gateway-secret` by default — carries
+`secret`, compared in constant time. The gateway adds it to every subgraph
+request; a client that reaches the service directly does not know it, and its
+`extensions` are ignored.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `secret` | — | shared with the gateway only; **at least 16 characters**, or `gatewaySecret` throws when it is built |
+| `header` | `x-gateway-secret` | the header the gateway sends it in |
+
+The length check is there for the day `GATEWAY_SECRET` is unset: the server
+stops at boot instead of trusting an empty header.
+
+### Another proof
+
+`trustedGateway` is any function of the request's headers:
+
+```ts
+type GatewayTrust = (headers: { get(name: string): string | null | undefined }) => boolean | Promise<boolean>;
+
+// Your proxy terminates mTLS and sets this header only for the gateway's certificate.
+useAuth({ trustedGateway: (headers) => headers.get('x-client-cert-subject') === 'CN=gateway' });
+```
+
+It receives a fetch `Headers` under Yoga and Apollo's `HeaderMap` under
+Apollo Server; both answer `get`.
+
+### What is read
+
+- `useAuth()`: `extensions.user` when it is an object with a non-empty string
+  `sub`, and `extensions.token` when it is a string. Otherwise nothing.
+- `extractJwtPlugin()`: `extensions.payload`, under the same `sub` rule, on
+  `context.jwt.payload`.
+- A request that fails the proof leaves `user`, `token` and `jwt` as they
+  were — another plugin's caller is not erased.
+- Over WebSocket, `useAuth()` reads no caller: the proof needs a fetch
+  `Request`, which a graphql-ws context does not hold. Resolve the caller per
+  connection with `resolveWsUser` instead.
+
+Without a `trustedGateway`, both throw a `TypeError` when called — see
+[troubleshooting](../troubleshooting.md).
+
+## `@authenticated(type: [String!])`
+
+```graphql
+directive @authenticated(type: [String!]) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
+```
+
+Declared in `SHARED_TYPE_DEFS` and in `AUTHENTICATED_DIRECTIVE_SDL`; enforced
+by `useAuthenticated()`, or `applyAuthenticated(schema)` on a built schema.
+
+```graphql
+type Query {
+	me: User @authenticated                      # any caller
+	webhooks: [Webhook!]! @authenticated(type: ["token"])  # a machine client, not a session
+}
+
+interface Node @authenticated { id: ID! }
+type Staff implements Node @authenticated(type: ["session"]) { id: ID!, name: String }
+```
+
+| Caller | Answer |
+| --- | --- |
+| none (`context.user` unset) | `UNAUTHENTICATED`, HTTP 401 |
+| of a type no applicable `type:` names | `FORBIDDEN`, HTTP 403 |
+| otherwise | the resolver runs |
+
+- **The caller's type** is `context.ory.kind` — `session` for a Kratos
+  session, `token` for an access token — or `context.user.tokenType` when no
+  Ory principal is on the context.
+- **Every directive that applies is AND-ed**: the field's, its type's, its
+  type's interfaces', and those interfaces' same field. `Staff.name` above
+  needs a caller (`Node`) who is a session (`Staff`).
+- **A scalar's or an enum's directive guards every field returning it** —
+  `scalar Secret @authenticated` refuses `Query.secret: Secret` to an
+  anonymous caller, as federation's router reads it.
+- **A subscription is refused before its stream opens**: the check runs
+  before the field's `subscribe`, and again before each event is resolved.
+- **A type's directive guards its fields, not the field returning it.**
+  `Query.staff` runs for an anonymous caller; the error lands on
+  `staff.name`. Put `@authenticated` on the field too when the lookup must not
+  run.
+
+### Other caller types
+
+```ts
+import { CALLER_TYPES, useAuthenticated } from '@nxgt/shared-graphql';
+
+useAuthenticated({ types: [...CALLER_TYPES, 'service'] });
+```
+
+`types` lists every value a `type:` may name; `CALLER_TYPES` —
+`['session', 'token']` — is the default. Behind a gateway, it is the set
+of `tokenType`s your gateway writes.
+
+### Refused at build
+
+`applyAuthenticated` throws a `TypeError` for a directive no request could
+pass, naming where it sits — `Query.me` on a field, `Staff` on a type,
+`Secret` on a scalar:
+
+| Mistake | Message starts |
+| --- | --- |
+| `type: []` | ``@authenticated on Query.me: `type: []` admits no caller`` |
+| a type outside `types` | `@authenticated on Query.me: unknown type "staff" — known: session, token` |
+| restrictions with no type in common | ``@authenticated on Note.body: the field's, its type's and its interfaces' `type`s have none in common`` |
+
+### Federation's `@authenticated`
+
+Federation defines its own `@authenticated`, with **no argument**, and a
+subgraph imports it:
+
+```graphql
+extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@authenticated"])
+```
+
+`useAuthenticated` accepts that shape: an `@authenticated` whose declaration
+has no `type` means "any caller", and is enforced as such. So in a subgraph,
+keep federation's declaration — `FEDERATION_DIRECTIVES` carries it unchanged
+— and do not load `SHARED_TYPE_DEFS` beside it. `type:` is for a schema that
+declares `@authenticated` through `SHARED_TYPE_DEFS` or
+`AUTHENTICATED_DIRECTIVE_SDL`.
+
+### Beside `useKetoChecks`
+
+Both plugins replace the schema. Each marks the fields it guarded and leaves a
+marked field alone, so the two settle on one schema in either order — and a
+schema merged from a guarded half and an unguarded one gets the second half
+guarded when it is transformed again, as is a field whose resolver was
+replaced since. On a field carrying both,
+`@authenticated` is checked before `@permission` whatever the plugin order,
+so a caller of the wrong type is `FORBIDDEN` before Keto is asked:
+
+```ts
+plugins: [useOryAuth(ory), useAuthenticated(), useKetoChecks(ory)]
+```

package/docs/guide/errors.md

@@ -0,0 +1,136 @@
+# Errors: `createMaskError` and `createFormatError`
+
+The directives, `requireUser` and `can` throw a **denial**: a `GraphQLError`
+that carries its own code and HTTP status, so any server answers it right.
+Services throw `CustomException` (from `@nxgt/shared-exceptions`), and
+`@nxgt/ory-sdk` throws `OryUnavailable` when Ory cannot answer. Neither of
+those is a `GraphQLError`, so a server has to be told how to answer them —
+and how to translate a denial's message with your resources. These two
+functions do it — one for Yoga, one for Apollo Server.
+
+## Denials
+
+```ts
+import { denial } from '@nxgt/shared-graphql';
+import { ErrorCode } from '@nxgt/shared-exceptions';
+
+throw denial(ErrorCode.NotFound, 'notes.errors.not-found');
+```
+
+| Code | `extensions.http.status` | Thrown by |
+| --- | --- | --- |
+| `UNAUTHENTICATED` | 401 | `@permission`, `@authenticated`, `requireUser`, `can`, with no caller |
+| `FORBIDDEN` | 403 | `@permission(onDeny: FORBIDDEN)`; `@authenticated(type:)` for a caller of another type |
+| `NOT_FOUND` | 404 | `@permission`, by default |
+
+The second argument is an i18n key — `errors.unauthenticated`,
+`errors.insufficient-permissions` or `errors.not-found` when omitted. The
+message is that key translated with `@nxgt/i18n`'s own resources, in the
+request's language when one is known; a key those resources do not hold stays
+as it is. `createMaskError(translate)` and `createFormatError(translate)`
+translate it again with yours, and keep its code and status.
+
+`denialMessageKey(error)` returns that key, for a mask of your own; the key is
+never serialised to the client.
+
+**Without `createMaskError`**, Yoga answers a denial with its status — it is
+a `GraphQLError` thrown on purpose, which Yoga's default mask lets through.
+
+## Yoga
+
+```ts
+import { createMaskError } from '@nxgt/shared-graphql';
+import { translate } from './i18n';
+
+createYoga({ maskedErrors: { maskError: createMaskError(translate) } });
+```
+
+## Apollo Server
+
+```ts
+import { createFormatError } from '@nxgt/shared-graphql';
+
+new ApolloServer({ formatError: createFormatError(translate, isProduction) });
+```
+
+## What a client receives — Yoga, through `createMaskError`
+
+| Thrown | `extensions.code` | `extensions.http.status` | message |
+| --- | --- | --- | --- |
+| a `denial()` | its code | 401, 403 or 404 | its key, translated with your `translate` |
+| `CustomException.unauthenticated()` | `UNAUTHENTICATED` | 401 | translated key |
+| `CustomException.forbidden()` | `FORBIDDEN` | 403 | translated key |
+| `CustomException.notFound()` | `NOT_FOUND` | 404 | translated key |
+| any other `CustomException` | its `errorCode` | its status | translated key |
+| a Mongoose error | through `castError` | its status | translated key |
+| `OryUnavailable` | `SERVICE_UNAVAILABLE` | 503 | `ory: keto is unavailable` |
+| a `GraphQLError` thrown on purpose | its own | its own | its own |
+| a plain `Error` a resolver threw | `INTERNAL_SERVER_ERROR` | — | the mask message |
+
+```json
+{
+	"errors": [
+		{
+			"message": "Could not find the requested resource.",
+			"path": ["note"],
+			"extensions": { "code": "NOT_FOUND", "http": { "status": 404 } }
+		}
+	]
+}
+```
+
+The HTTP status applies when it is the only error of the response, as Yoga
+decides it.
+
+## What a client receives — Apollo, through `createFormatError`
+
+| Thrown | `extensions.code` | message |
+| --- | --- | --- |
+| a `denial()` | its code (`http.status` answers the transport) | its key, translated with your `translate` |
+| a `CustomException` or a Mongoose error | its `errorCode` (plus `debugMessage`) | translated key |
+| `OryUnavailable` | `SERVICE_UNAVAILABLE`, `http: { status: 503 }` in `extensions` | `ory: keto is unavailable` |
+| an Apollo validation or parse error | its own | translated `errors.<code>` |
+| anything else | as Apollo formats it | as Apollo formats it — not masked here |
+
+`formatError` shapes the error body; it does not set the response's status,
+so `http.status` is information for the client, not the transport's answer.
+The stack trace is removed when the second argument, `production`, is true.
+
+## An outage is a 503, never a denial
+
+Kratos, Hydra or Keto failing to answer is not "anonymous" and not "denied".
+Answering it as either would lock every caller out in silence — or, for a
+check that defaulted open, let everyone in. So `OryUnavailable` is never caught
+as a refusal anywhere in this package, and both functions answer it
+`SERVICE_UNAVAILABLE` — with HTTP 503 under Yoga — which a client can retry.
+
+It is recognised by class, and also by its name and shape: an install that
+ends up with two copies of `@nxgt/ory-sdk` throws an `OryUnavailable` whose
+class is not the one this package imported, and that must still be a 503
+rather than a masked 500. `isOryUnavailable(error)` is the test, and
+`serviceUnavailableError(error)` builds the 503 `GraphQLError` both use —
+exported for a server that writes its own `maskError`:
+
+```ts
+import { isOryUnavailable, serviceUnavailableError } from '@nxgt/shared-graphql';
+import { GraphQLError } from 'graphql';
+import type { MaskError } from 'graphql-yoga';
+
+const maskError: MaskError = (error, message) => {
+	const original = error instanceof GraphQLError ? error.originalError : error;
+	if (isOryUnavailable(original)) return serviceUnavailableError(original);
+	// …
+};
+```
+
+`oryUnavailableError`, which `useOryAuth` throws when it cannot resolve the
+caller, is the same function under its older name.
+
+## Internal messages stay internal
+
+graphql-js wraps every error a resolver throws in a `GraphQLError`. A wrapper
+around a plain `Error` — a driver's `connect ECONNREFUSED 10.0.0.5:27017` — is
+replaced by the mask message, as Yoga's default mask does; its `path` is kept.
+In development (`isDev`) the original is in `extensions.debugMessage`.
+
+A `GraphQLError` you throw yourself, and every validation error, passes as is.

package/docs/guide/migrating-to-3.md

@@ -0,0 +1,276 @@
+# Migrating to 3.0
+
+`@nxgt/shared-graphql` 3.0 is a major release. Most of it is the removals and
+renames 2.x announced, plus one security fix that changes how the caller is
+read. Each section below is one break: what changed, why, and the code before
+and after.
+
+| # | Break | You are affected if you… |
+| --- | --- | --- |
+| 1 | [`useAuth()` and `extractJwtPlugin` need a trusted gateway](#1-useauth-and-extractjwtplugin-need-a-trusted-gateway) | use either |
+| 2 | [`@check` is removed](#2-check-is-removed) | write `@check`, or import `CHECK_DIRECTIVE_SDL` / `readChecks` / `readRequirements` |
+| 3 | [`@authenticated` takes `type:`, and this package enforces it](#3-authenticated-takes-type) | declare `@authenticated` yourself, or load `SHARED_TYPE_DEFS` |
+| 4 | [Five dependencies are gone](#4-five-dependencies-are-gone) | import one of them without declaring it |
+| 5 | [`@nxgt/ory-sdk` is peered `>=0.1.0 <1`](#5-nxgtory-sdk-is-peered-010-1) | are on an `@nxgt/ory-sdk` 1.x (none is published) |
+| 6 | [`graphql` is peered `^16.9.0 \|\| ^17.0.0`](#6-graphql-is-peered-1690--1700) | are on graphql 16.4 to 16.8 |
+| 7 | [`sandboxExpolorer` is `sandboxExplorer`](#7-sandboxexpolorer-is-sandboxexplorer) | import it |
+| 8 | [A denial is a `GraphQLError`](#8-a-denial-is-a-graphqlerror) | catch a denial as a `CustomException`, or read its `errorCode` |
+
+## 1. `useAuth()` and `extractJwtPlugin` need a trusted gateway
+
+**Why.** Both copied the caller from the GraphQL request's `extensions` —
+`user` and `token` for `useAuth()`, `payload` for `extractJwtPlugin`. That is
+part of the request body, and any client that reaches the service writes it:
+
+```json
+{ "query": "{ me { id } }", "extensions": { "user": { "sub": "someone-else" } } }
+```
+
+In 2.x that request was answered as `someone-else`. In 3.0 the caller is read
+from `extensions` only for a request that proves it came from your gateway.
+
+**Before**
+
+```ts
+createYoga({ plugins: [useAuth()] });
+new ApolloServer({ plugins: [extractJwtPlugin] });
+```
+
+**After**
+
+```ts
+import { extractJwtPlugin, gatewaySecret, useAuth } from '@nxgt/shared-graphql';
+
+const trustedGateway = gatewaySecret({ secret: process.env.GATEWAY_SECRET! });
+
+createYoga({ plugins: [useAuth({ trustedGateway })] });
+new ApolloServer({ plugins: [extractJwtPlugin({ trustedGateway })] });
+```
+
+Then make the gateway send the secret on every subgraph request, in the
+`x-gateway-secret` header (or the one you name with `header`). A Hive Gateway,
+for example:
+
+```ts
+defineConfig({
+	propagateHeaders: {
+		fromClientToSubgraphs: () => ({ 'x-gateway-secret': process.env.GATEWAY_SECRET }),
+	},
+});
+```
+
+- A request without the header, or with a wrong one, keeps the context
+  without a caller: `user`, `token` and `jwt` are left as they were.
+- `gatewaySecret` refuses, when it is built, a secret shorter than 16
+  characters — an unset variable stops the server instead of trusting an
+  empty header. It compares in constant time.
+- `trustedGateway` can be any `(headers) => boolean | Promise<boolean>`, for a
+  proof other than a shared secret (an mTLS header your proxy sets, say).
+- Called without a `trustedGateway`, both throw a `TypeError` when the server
+  starts:
+  ``useAuth(): name the gateway allowed to set the caller — …``.
+- `extractJwtPlugin` is now a function, and no longer logs the payload.
+- A `user` (or `payload`) without a non-empty string `sub` is ignored, even
+  from a trusted gateway.
+- Over WebSocket, `useAuth()` reads no caller: a graphql-ws context holds no
+  fetch `Request` to carry the proof. Resolve the caller per connection with
+  `resolveWsUser`.
+
+An API that authenticates its own callers — a Kratos session, a Hydra token —
+does not need a gateway at all: use `useOryAuth(ory)`, which verifies the
+credential server-side.
+
+## 2. `@check` is removed
+
+**Why.** `@permission` replaced it in 2.1, and 3.0 drops the list-of-lists
+form: one Keto question per directive, AND when repeated, and OR in the Keto
+model.
+
+**Before**
+
+```graphql
+note(id: ID!): Note @check(permissions: [[{ namespace: "Note", permit: "view" }]])
+
+updateNote(id: ID!): Note
+	@check(permissions: [[{ namespace: "Note", permit: "view" }]])
+	@check(permissions: [[{ namespace: "Note", permit: "edit" }]], onDeny: FORBIDDEN)
+
+owner: Person @check(permissions: [[{ namespace: "Person", permit: "view", id: "parent.ownerId" }]])
+```
+
+**After**
+
+```graphql
+note(id: ID!): Note @permission(name: "view", type: "Note")
+
+updateNote(id: ID!): Note
+	@permission(name: "view", type: "Note")
+	@permission(name: "edit", type: "Note", onDeny: FORBIDDEN)
+
+owner: Person @permission(name: "view", type: "Person", id: "parent.ownerId")
+```
+
+`namespace` is `type`, `permit` is `name`; `id`, `onDeny` and `message` keep
+their meaning. A term group with two terms (`[[A, B]]`, an AND) becomes two
+`@permission`s. A requirement with two groups (`[[A], [B]]`, an OR) has no
+`@permission` spelling: add a permit to the Keto model that unions the two
+relations, and ask that one.
+
+**In code:**
+
+| 2.x | 3.0 |
+| --- | --- |
+| `CHECK_DIRECTIVE_SDL` | gone — `PERMISSION_DIRECTIVE_SDL` |
+| `KETO_DIRECTIVES_SDL` | still exported, now `@permission` alone |
+| `readChecks`, `readRequirements` | gone — `readPermissions` |
+| `CheckArgs`, `CheckDenial` | `FieldPermission`, `PermissionDenial` |
+| `graphql/directives/check.graphqls` | no longer shipped |
+
+**What 2.x only warned about now stops the server.** An `args.<name>` the
+field does not declare, and a guard on an interface field, were logged as
+warnings on a `@check`. As `@permission`s they are `TypeError`s naming the
+field, when the schema is built.
+
+**A `@check` left behind does not boot.** Without its declaration, graphql
+refuses it (`Unknown directive "@check"`). With a declaration of 2.x's shape
+copied into your schema, `useKetoChecks` refuses it:
+
+```
+@check on Query.note: @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
+```
+
+A `@check` directive of another shape (without `permissions`) is yours, and is
+left alone.
+
+## 3. `@authenticated` takes `type:`
+
+**Why.** A field meant for a machine client could not refuse a person's
+session. `@authenticated(type: [String!])` names the kinds of caller a field
+admits, and `useAuthenticated()` enforces it.
+
+**Before** — `@authenticated` was declared, and enforced by an app's own
+`useGenericAuth`:
+
+```ts
+createYoga({ plugins: [useOryAuth(ory), useGenericAuth({ mode: 'protect-granular', resolveUserFn })] });
+```
+
+**After**
+
+```graphql
+me: User @authenticated
+webhooks: [Webhook!]! @authenticated(type: ["token"])
+```
+
+```ts
+import { useAuthenticated, useOryAuth } from '@nxgt/shared-graphql';
+
+createYoga({ plugins: [useOryAuth(ory), useAuthenticated()] });
+```
+
+- The type is Ory's `kind` — `session` or `token` — or `user.tokenType` when
+  no Ory principal is on the context. `useAuthenticated({ types: [...] })`
+  names other values; a `type` outside them is refused at build.
+- An anonymous caller is `UNAUTHENTICATED` (401), a caller of another type
+  `FORBIDDEN` (403). An `@authenticated` scalar or enum guards every field
+  returning it, and a subscription is refused before its stream opens.
+- `SHARED_TYPE_DEFS` now declares `@authenticated(type: [String!])`. If you
+  declare `@authenticated` yourself, add the argument or drop your
+  declaration; `AUTHENTICATED_DIRECTIVE_SDL` is the declaration as a string.
+- **In a federation subgraph**, keep federation's own `@authenticated`, which
+  takes no argument: import it in `@link` as before. `useAuthenticated()`
+  reads that shape as "any caller", so the directive is enforced there too.
+  `FEDERATION_DIRECTIVES` keeps federation's shape for the same reason.
+
+`useGenericAuth` keeps working beside it if you still need its other modes.
+Declare `@envelop/generic-auth` yourself — see the next section.
+
+## 4. Five dependencies are gone
+
+**Why.** Nothing in this package imported them:
+`@graphql-hive/gateway`, `@envelop/generic-auth`,
+`@envelop/extended-validation`, `@hono/zod-validator`, `zod`.
+
+An app that imported one of them without declaring it got it through this
+package, and now gets `Cannot find module`. Declare what you use:
+
+```diff
+ "dependencies": {
++	"@envelop/generic-auth": "^11.1.1",
+ 	"@nxgt/shared-graphql": "^3.0.0"
+ }
+```
+
+## 5. `@nxgt/ory-sdk` is peered `>=0.1.0 <1`
+
+**Why.** An open range admitted a breaking SDK major the day it was
+published, untested. Every published version (0.1.x) is still admitted;
+nothing changes for an install today. `@nxgt/security` and
+`@nxgt/shared-hono` take the same ceiling.
+
+## 6. `graphql` is peered `^16.9.0 || ^17.0.0`
+
+**Why.** The floor was 16.4.2, which nothing tested. The suite runs on a
+graphql 16 above 16.9 and on graphql 17. On graphql 16.4 to 16.8, upgrade:
+
+```sh
+bun add graphql@^16.9.0
+```
+
+## 7. `sandboxExpolorer` is `sandboxExplorer`
+
+**Before**
+
+```ts
+import { sandboxExpolorer } from '@nxgt/shared-graphql';
+app.get('/sandbox', sandboxExpolorer({ port: 4000 }));
+```
+
+**After**
+
+```ts
+import { sandboxExplorer } from '@nxgt/shared-graphql';
+app.get('/sandbox', sandboxExplorer({ port: 4000 }));
+```
+
+No alias is kept. `createYogaHono` uses the new name for you.
+
+## 8. A denial is a `GraphQLError`
+
+**Why.** `@permission`, `requireUser` and `can` threw a `CustomException`,
+which Yoga masks as a 500 unless `createMaskError` is registered. They now
+throw `denial(code, message?)`: a `GraphQLError` carrying
+`extensions { code, http { status } }`, so any server answers 401, 403 or 404.
+`@authenticated` throws the same.
+
+What a client receives through `createMaskError` or `createFormatError` does
+not change: the same code, status and translated message.
+
+**Before** — code that caught a refusal:
+
+```ts
+try {
+	requireUser(ctx);
+} catch (error) {
+	if (error instanceof CustomException && error.errorCode === ErrorCode.Unauthenticated) { … }
+}
+```
+
+**After**
+
+```ts
+import { GraphQLError } from 'graphql';
+
+try {
+	requireUser(ctx);
+} catch (error) {
+	if (error instanceof GraphQLError && error.extensions.code === 'UNAUTHENTICATED') { … }
+}
+```
+
+Without `createMaskError`, the message is the shared key translated with
+`@nxgt/i18n`'s own resources (`Could not find the requested resource.`), in
+the request's language when one is known. A custom `message:` key those
+resources do not hold reaches the client as the key: register
+`createMaskError(translate)` to translate it with yours. `denial` and
+`denialMessageKey` are exported for a resolver or a mask of your own.