@nxgt/shared-graphql 2.1.0 → 3.0.0

package/docs/guide/errors.md

@@ -1,10 +1,40 @@
 # Errors: `createMaskError` and `createFormatError`
 
-Services throw `CustomException` (from `@nxgt/shared-exceptions`), the
-directives throw it for a refusal, and `@nxgt/ory-sdk` throws `OryUnavailable`
-when Ory cannot answer. Neither is a `GraphQLError`, so a server has to be told
-how to answer them. These two functions do it — one for Yoga, one for Apollo
-Server.
+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
 
@@ -27,6 +57,7 @@ new ApolloServer({ formatError: createFormatError(translate, isProduction) });
 
 | 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 |
@@ -55,6 +86,7 @@ decides it.
 
 | 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>` |

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.

package/docs/guide/permissions.md

@@ -1,4 +1,4 @@
-# Permissions: `@permission`, `@check`, `useKetoChecks`
+# 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
@@ -33,21 +33,23 @@ const yoga = createYoga<{}, OryGraphQLContext>({
 });
 ```
 
-Both are needed: a guarded field reads `ory.subject`, which `useOryAuth` puts
-on the context — without it every guarded field answers `UNAUTHENTICATED`. `createMaskError` is what turns a denial into a 404/403 and an outage
-into a 503 — without it Yoga answers every one of them as an opaque 500.
+`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
-declarations as a string:
+declaration as a string:
 
 ```ts
-import { KETO_DIRECTIVES_SDL } from '@nxgt/shared-graphql';
+import { PERMISSION_DIRECTIVE_SDL } from '@nxgt/shared-graphql';
 
-createSchema({ typeDefs: [KETO_DIRECTIVES_SDL, typeDefs], resolvers });
+createSchema({ typeDefs: [PERMISSION_DIRECTIVE_SDL, typeDefs], resolvers });
 ```
 
-`PERMISSION_DIRECTIVE_SDL` and `CHECK_DIRECTIVE_SDL` are the two halves. Each
-equals its file in `graphql/directives/` — a spec parses and prints both.
+It equals `graphql/directives/permission.graphqls` — a spec parses and prints
+both. `KETO_DIRECTIVES_SDL` is the same string.
 
 ## `@permission`
 
@@ -82,10 +84,12 @@ updateNote(id: ID!, input: UpdateNoteInput!): Note!
 
 | Caller holds | Answer |
 | --- | --- |
-| nothing | `NOT_FOUND` — the same as an id that never existed, so ids cannot be probed |
-| `view` | `FORBIDDEN` — they can already see it, so "you may not change it" is honest |
+| 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
@@ -128,71 +132,55 @@ 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` — deprecated
-
-The list-of-lists form. It keeps working, and is validated and evaluated
-exactly like `@permission` — in declaration order with it, on the same field:
-
-```graphql
-note(id: ID!): Note
-	@check(permissions: [[{ namespace: "Note", permit: "view" }]])
-
-either(id: ID!): Note
-	@check(permissions: [
-		[{ namespace: "Note", permit: "a" }, { namespace: "Note", permit: "b" }],
-		[{ namespace: "Note", permit: "c" }]
-	])
-```
-
-The outer list is OR, the inner list AND: `[[A, B], [C]]` reads
-"(A and B) or C". Moving a field to `@permission` one directive at a time
-keeps its ladder, since the order is read across both names:
+## `@check` — removed in 3.0
 
-```graphql
-updateNote(id: ID!, input: UpdateNoteInput!): Note!
-	@check(permissions: [[{ namespace: "Note", permit: "view" }]])
-	@permission(name: "edit", type: "Note", onDeny: FORBIDDEN)
-```
-
-A field whose `@check` really needs an OR is the one to move into the Keto
-model first.
+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 requirement when the schema is built, and throws a `TypeError` naming
+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 requirement or group (`@check`) | `… an empty group admits EVERYONE …` |
+| 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: @check / @permission on an interface field guards nothing …` |
-
-On a `@check` — which 2.x booted with them — the undeclared argument and the
-interface field are logged (`logger.warn` from `@nxgt/shared-logging`) instead
-of thrown, ending `— @check still boots with this; the next major refuses it,
-as @permission does`. Fix them now: the field they name answers 500 on every
-request, or is not guarded at all.
+| 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, type OryGraphQLContext, requireUser } from '@nxgt/shared-graphql';
+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 CustomException.forbidden({ message: 'notes.errors.read-only' });
+				throw denial(ErrorCode.Forbidden, 'notes.errors.read-only');
 			}
 			return notes.archive(id, user.sub);
 		},
@@ -200,7 +188,8 @@ const resolvers = {
 };
 ```
 
-- `requireUser(ctx)` returns `ctx.user`, or throws `UNAUTHENTICATED` (401).
+- `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

package/docs/roadmap.md

@@ -5,37 +5,14 @@ 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` and `useKetoChecks` for an
-Ory-native API, `createMaskError` / `createFormatError`, dataloaders,
-subscriptions over Redis, uploads and the Hono integration.
+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 — a planned major
+## Next
 
-Each of these changes what an existing consumer gets, so they wait for a major
-release, together:
-
-- **`@check`'s mistakes refused at build**, as `@permission`'s are: an
-  argument the field does not declare, and a guard on an interface field —
-  today a warning.
-- **`@check` removed**, leaving `@permission`. A field whose `@check` holds an
-  OR moves that OR into the Keto model first.
-- **`@authenticated(type: [String!])`** — refusing a caller of the wrong kind
-  (a session where a client token is expected) at the directive. It changes
-  the declaration that federation's own `@authenticated` shares, so it cannot
-  be added in place.
-- **Dependencies this package does not import are dropped** —
-  `@graphql-hive/gateway`, `@envelop/generic-auth`,
-  `@envelop/extended-validation`, `@hono/zod-validator`, `zod`. An app that
-  imports one of them without declaring it would stop installing it.
-- **`useAuth()` and `extractJwtPlugin` stop reading the caller from the request
-  body's `extensions`** unless told which gateway may set them.
-- **`@nxgt/ory-sdk` peered with a ceiling** (`>=0.1.0 <1`), so a breaking SDK
-  major is not admitted untested.
-- **The peer floors raised to what is tested** — `graphql` `^16.9.0 ||
-  ^17.0.0`.
-- **The sandbox helper renamed** from `sandboxExpolorer` to `sandboxExplorer`.
-- **A denial thrown as a `GraphQLError`** with its `code` and HTTP status, so a
-  server without `createMaskError` answers 404/403 rather than a masked 500.
+Nothing planned that changes what a consumer gets. See Later.
 
 ## Later
 
@@ -52,6 +29,30 @@ release, together:
 
 ## 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