@nxgt/shared-graphql 2.0.1 → 2.1.0

package/dist/plugins/ory-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ory-auth.d.ts","sourceRoot":"","sources":["../../src/plugins/ory-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,GAAG,EACR,KAAK,YAAY,EACjB,cAAc,EACd,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACxB,GAAG,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,cAAc,CAc7D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAQvE;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACxC,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,UAAU,GAAG;IAAE,IAAI,CAAC,EAAE,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAejE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,kBAAkB,GAAG,UAAU,CAAC,CAM5E"}
+{"version":3,"file":"ory-auth.d.ts","sourceRoot":"","sources":["../../src/plugins/ory-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,GAAG,EACR,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAMnD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACxB,GAAG,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,cAAc,CAc7D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAEvE;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACxC,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,UAAU,GAAG;IAAE,IAAI,CAAC,EAAE,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAejE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,kBAAkB,GAAG,UAAU,CAAC,CAM5E"}

package/dist/scalars/custom/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/scalars/custom/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EACpC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC/B,EACC,IAAI,EACJ,WAAW,EACX,YAAY,GACZ,EAAE;IACF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CAClC,2BA2CD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/scalars/custom/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EACpC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC/B,EACC,IAAI,EACJ,WAAW,EACX,YAAY,GACZ,EAAE;IACF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CAClC,2BA4CD"}

package/dist/utils/errors/create-error.d.ts

@@ -0,0 +1,3 @@
+import { GraphQLError, type GraphQLErrorOptions } from 'graphql';
+export declare function createGraphQLError(message: string, options?: GraphQLErrorOptions): GraphQLError;
+//# sourceMappingURL=create-error.d.ts.map

package/dist/utils/errors/create-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-error.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/create-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEjE,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,mBAAmB,GAC3B,YAAY,CAEd"}

package/dist/utils/errors/format-error.d.ts

@@ -0,0 +1,11 @@
+import type { ApolloServerOptions } from '@apollo/server';
+import { type LocaleKey, type TranslationContext } from '@nxgt/i18n';
+import type { GraphQLBaseContext } from '../../types';
+/**
+ * Apollo Server's `formatError`, taught this repo's exceptions — the Apollo
+ * counterpart of `createMaskError`. `OryUnavailable` answers
+ * `SERVICE_UNAVAILABLE`, never a denial and never an opaque
+ * `INTERNAL_SERVER_ERROR`.
+ */
+export declare function createFormatError<K extends LocaleKey, C extends GraphQLBaseContext = GraphQLBaseContext>(translate?: (message: K, context?: TranslationContext) => string, production?: boolean): ApolloServerOptions<C>['formatError'];
+//# sourceMappingURL=format-error.d.ts.map

package/dist/utils/errors/format-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-error.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/format-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAK1D,OAAO,EACN,KAAK,SAAS,EACd,KAAK,kBAAkB,EAEvB,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAChC,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,EAEjD,SAAS,GAAE,CACV,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,kBAAkB,KACxB,MAAsB,EAC3B,UAAU,CAAC,EAAE,OAAO,GAClB,mBAAmB,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CA4DvC"}

package/dist/utils/errors/index.d.ts

@@ -0,0 +1,5 @@
+export * from './create-error';
+export * from './format-error';
+export * from './mask-error';
+export * from './ory-unavailable';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC"}

package/dist/utils/errors/mask-error.d.ts

@@ -0,0 +1,24 @@
+import { type LocaleKey, type TranslationContext } from '@nxgt/i18n';
+import type { MaskError } from 'graphql-yoga';
+type Translate<K extends LocaleKey> = (message: K, context?: TranslationContext) => string;
+/**
+ * Yoga's `maskedErrors.maskError`, taught this repo's exceptions.
+ *
+ * Yoga masks anything that is not a `GraphQLError` as "Unexpected error." —
+ * and `CustomException` extends `Error`, so out of the box a service's
+ * `notFound()` or `forbidden()` reaches the client as an opaque 500. This
+ * turns one into a `GraphQLError` with the translated message, the
+ * exception's `code` in `extensions`, and a matching HTTP status
+ * (`UNAUTHENTICATED` 401, `FORBIDDEN` 403, `NOT_FOUND` 404); a Mongoose error
+ * goes through `castError` first, as `createFormatError` does for Apollo.
+ * `OryUnavailable` (@nxgt/ory-sdk) becomes a 503 `SERVICE_UNAVAILABLE`, never
+ * a denial. Everything else is masked as Yoga's default masks it: a
+ * `GraphQLError` thrown on purpose — or raised by validation — passes, and one
+ * that only wraps a plain `Error` a resolver threw is replaced by `message`,
+ * so an internal message never reaches the client.
+ *
+ *     createYoga({ maskedErrors: { maskError: createMaskError(translate) } })
+ */
+export declare function createMaskError<K extends LocaleKey>(translate?: Translate<K>): MaskError;
+export {};
+//# sourceMappingURL=mask-error.d.ts.map

package/dist/utils/errors/mask-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask-error.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/mask-error.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,SAAS,EACd,KAAK,kBAAkB,EAEvB,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,KAAK,SAAS,CAAC,CAAC,SAAS,SAAS,IAAI,CACrC,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,kBAAkB,KACxB,MAAM,CAAC;AAEZ;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EAClD,SAAS,GAAE,SAAS,CAAC,CAAC,CAAiB,GACrC,SAAS,CA2BX"}

package/dist/utils/errors/ory-unavailable.d.ts

@@ -0,0 +1,19 @@
+import type { OryUnavailable } from '@nxgt/ory-sdk';
+import { GraphQLError } from 'graphql';
+/**
+ * Whether an error is `@nxgt/ory-sdk`'s `OryUnavailable` — Kratos, Hydra or
+ * Keto could not answer.
+ *
+ * By name and shape as well as by class: an install that resolves two copies
+ * of `@nxgt/ory-sdk` (one under this package, one under the app) throws an
+ * `OryUnavailable` this module's `instanceof` does not recognise, and an
+ * outage that slips past here is masked as a 500 instead of answered as a 503.
+ */
+export declare function isOryUnavailable(error: unknown): error is OryUnavailable;
+/**
+ * A 503 the client can read as one — a real `GraphQLError` so Yoga's masking
+ * leaves it alone, `extensions.http.status` so the transport says 503 too.
+ * Never a denial: an outage must not read as "not signed in" or "not allowed".
+ */
+export declare function serviceUnavailableError(error: OryUnavailable): GraphQLError;
+//# sourceMappingURL=ory-unavailable.d.ts.map

package/dist/utils/errors/ory-unavailable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ory-unavailable.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/ory-unavailable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAIxE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAQ3E"}

package/dist/utils/index.d.ts

@@ -1,7 +1,7 @@
 export * from './change-resolvers.utils';
 export * from './codegen.utils';
 export * from './data-loader.utils';
-export * from './errors.utils';
+export * from './errors';
 export * from './publish';
 export * from './sandbox';
 export * from './schema.utils';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/docs/README.md

@@ -0,0 +1,11 @@
+# `@nxgt/shared-graphql` docs
+
+The package's [README](../README.md) is the short version, with one example
+per section. These pages are the long one.
+
+- [Guide: permissions](./guide/permissions.md) — `@permission`, `@check`,
+  `useKetoChecks`, build-time validation, `requireUser` and `can`
+- [Guide: errors](./guide/errors.md) — `createMaskError`, `createFormatError`,
+  the codes and statuses, and why an outage is a 503
+- [Troubleshooting](./troubleshooting.md) — each error by the message you see
+- [Roadmap](./roadmap.md) — what is next, including the planned major

package/docs/guide/errors.md

@@ -0,0 +1,104 @@
+# 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.
+
+## 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 |
+| --- | --- | --- | --- |
+| `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 `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/permissions.md

@@ -0,0 +1,231 @@
+# Permissions: `@permission`, `@check`, `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) },
+});
+```
+
+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.
+
+A schema assembled in code, with no `SHARED_SCHEMA_PATH`, takes the
+declarations as a string:
+
+```ts
+import { KETO_DIRECTIVES_SDL } from '@nxgt/shared-graphql';
+
+createSchema({ typeDefs: [KETO_DIRECTIVES_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.
+
+## `@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` — 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 |
+| `view` and `edit` | the resolver runs |
+
+### 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` — 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:
+
+```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.
+
+## Refused at build
+
+`applyKetoChecks` — which `useKetoChecks` runs on every schema change — reads
+every requirement 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 …` |
+| 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.
+
+`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.
+
+## From a resolver
+
+```ts
+import { can, type OryGraphQLContext, requireUser } from '@nxgt/shared-graphql';
+
+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' });
+			}
+			return notes.archive(id, user.sub);
+		},
+	},
+};
+```
+
+- `requireUser(ctx)` returns `ctx.user`, or throws `UNAUTHENTICATED` (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,70 @@
+# 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` and `useKetoChecks` for an
+Ory-native API, `createMaskError` / `createFormatError`, dataloaders,
+subscriptions over Redis, uploads and the Hono integration.
+
+## Next — a planned major
+
+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.
+
+## 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
+
+- **`@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`.