@nxgt/shared-graphql 2.1.0 → 3.0.0

package/docs/troubleshooting.md

@@ -1,17 +1,80 @@
 # Troubleshooting `@nxgt/shared-graphql`
 
 Each entry is headed by the message you see; the parts in `<angle brackets>`
-vary. Messages thrown when the schema is built are `TypeError`s naming
-`Type.field`, and stop the server from booting. They start `@permission on`
-or `@check on`, after the directive that carries the mistake; the entries show
-one of the two. The last section holds the
-traps that throw nothing.
+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 (or a `@check` term's `id`) names no root. Prefix it:
+The `id` argument names no root. Prefix it:
 
 ```graphql
 note(noteId: ID!): Note @permission(name: "view", type: "Note", id: "args.noteId")
@@ -24,28 +87,12 @@ The path reads an argument the field does not have — usually the default
 an undeclared argument on `args`, so every request would have failed. Name the
 argument in `id`, or read the parent with `parent.<path>`.
 
-### `@check on <Type.field>: an empty group admits EVERYONE — a conjunction over no terms is true`
-
-`@check(permissions: [[]])`. An AND over nothing is true, so the field would
-be open to every signed-in caller while looking guarded. Name a permission,
-or remove the directive.
+In 2.x a `@check` booted with this and logged a warning; a `@permission`
+refuses it.
 
-### `@check on <Type.field>: an empty permission requirement admits nobody — remove it, or name a permission`
+### ``@permission on <Type.field>: every term needs `namespace`, `permit` and `id`, got <term>``
 
-`@check(permissions: [])`: an OR over nothing refuses everyone.
-
-### ``<…> — @check still boots with this; the next major refuses it, as @permission does``
-
-A warning, not an error: one of the two mistakes above — an argument the
-field does not declare, or a guard on an interface field — on a `@check`. The
-server boots as it did in 2.x, but the field answers 500 on every request, or
-is not guarded at all. Fix it as the entry for the same message describes; the
-next major refuses it at build.
-
-### ``@check on <Type.field>: every term needs `namespace`, `permit` and `id`, got <term>``
-
-A term, or a `@permission`, has an empty `namespace`/`type` or
-`permit`/`name` — `@permission(name: "", type: "Note")`. Name both.
+`@permission(name: "", type: "Note")`: an empty `name` or `type`. Name both.
 
 ### `@permission on <Type.field>: unknown namespace "<type>" — known: <namespaces>`
 
@@ -54,7 +101,7 @@ 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>: @check / @permission on an interface field guards nothing — no resolver runs there. Put it on each implementing type's field`
+### `<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:
@@ -67,6 +114,39 @@ type Note implements Node {
 }
 ```
 
+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
@@ -93,7 +173,7 @@ alone.
 ### `Cannot use GraphQLSchema "<schema>" from another module or realm.`
 
 Two copies of `graphql` are installed: `graphql` is a peer of this package
-(`^16.4.2 || ^17.0.0`), so your app must declare it once, and every GraphQL
+(`^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
@@ -102,13 +182,12 @@ with less telling errors.
 
 ## When a request runs
 
-The three messages below are plain `Error`s 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.
-
 ### `<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
@@ -118,7 +197,7 @@ sure the parent object carries the field.
 
 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)`.
+`useKetoChecks(ory)` after `useOryAuth(ory)`. Answered as the previous entry.
 
 ### `can(): no checker on the context — useKetoChecks(ory) is not registered`
 
@@ -130,10 +209,12 @@ 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.
 
-### `Unexpected error.` with `INTERNAL_SERVER_ERROR` where a 404 or 403 was expected
+### A denial's message reads `notes.errors.not-found`
 
-`createMaskError` is not registered, so Yoga masks the `CustomException` a
-denial throws as it masks any non-GraphQL error:
+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) } });
@@ -141,30 +222,52 @@ 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
 
-Since this release `createMaskError` masks a plain `Error` a resolver threw,
-as Yoga's default does — before, its message (a driver error, a host name)
-reached the client. Throw a `CustomException` or a `GraphQLError` for a
+`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 `"@check"` if used) and
-import the directive in the subgraph's `@link`.
+Add `@composeDirective(name: "@permission")` and import the directive in the
+subgraph's `@link`.
 
-### `useAuth()` trusts the request body
+### `@authenticated(type:)` in a subgraph
 
-`useAuth()` copies `user` and `token` from the GraphQL request's
-`extensions`, which a client writes. It is safe only behind a gateway that
-sets them and a network that stops callers from reaching the service
-directly. An API that resolves its own callers uses `useOryAuth(ory)`.
+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
-`CustomException` you mean.
+`denial` you mean.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/shared-graphql",
-	"version": "2.1.0",
+	"version": "3.0.0",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -49,16 +49,12 @@
 	"dependencies": {
 		"@apollo/server": "^5.5.1",
 		"@apollo/subgraph": "^2.14.3",
-		"@envelop/extended-validation": "^7.1.1",
-		"@envelop/generic-auth": "^11.1.1",
-		"@graphql-hive/gateway": "^2.11.2",
 		"@graphql-tools/load-files": "^7.0.1",
 		"@graphql-tools/merge": "^9.2.3",
 		"@graphql-tools/utils": "^12.0.0",
 		"@graphql-yoga/redis-event-target": "^3.0.3",
-		"@hono/zod-validator": "^0.9.0",
 		"@nxgt/i18n": "^1.1.0",
-		"@nxgt/security": "^4.0.1",
+		"@nxgt/security": "^4.1.0",
 		"@nxgt/shared": "^1.0.5",
 		"@nxgt/shared-exceptions": "^1.0.4",
 		"@nxgt/shared-logging": "^1.0.4",
@@ -72,19 +68,19 @@
 		"hono": "^4.13.4",
 		"ioredis": "^6.0.0",
 		"lodash": "^4.18.1",
-		"ws": "^8.21.3",
-		"zod": "^4.4.3"
+		"ws": "^8.21.3"
 	},
 	"devDependencies": {
+		"@graphql-tools/schema": "^10.1.0",
 		"@types/bun": "^1.4.0",
 		"@types/graphql-upload": "^17.0.0",
 		"@types/lodash": "^4.17.25",
 		"@types/ws": "^8.18.1",
-		"graphql": "^16.4.2"
+		"graphql": "^16.9.0"
 	},
 	"peerDependencies": {
-		"@nxgt/ory-sdk": ">=0.1.0",
-		"graphql": "^16.4.2 || ^17.0.0",
+		"@nxgt/ory-sdk": ">=0.1.0 <1",
+		"graphql": "^16.9.0 || ^17.0.0",
 		"stx-sdk": ">=1.1.0",
 		"typescript": "^6.0.3"
 	}

package/dist/directives/check.d.ts

@@ -1,32 +0,0 @@
-import type { PermissionRequirement } from '@nxgt/ory-sdk';
-import type { GraphQLSchema } from 'graphql';
-import { type FieldNode, type ReadOptions } from './scope';
-/**
- * `@check` — the list-of-lists form of `@permission`, deprecated in its
- * favour and kept working.
- *
- * The declaration itself is SDL, in `graphql/directives/check.graphqls`, so it
- * reaches every consumer of `SHARED_SCHEMA_PATH`; `CHECK_DIRECTIVE_SDL` is the
- * same text as a string, held equal by a spec. This module only reads it.
- */
-export declare const CHECK_DIRECTIVE_NAME = "check";
-export type CheckDenial = 'NOT_FOUND' | 'FORBIDDEN';
-export type CheckArgs = {
-    permissions: PermissionRequirement;
-    onDeny: CheckDenial;
-    /** i18n key; the shared `errors.*` one when the field does not say. */
-    message?: string;
-};
-/**
- * Every `@check` on a field, in declaration order, validated.
- *
- * `@check` is repeatable, so this is a list and the order is load-bearing:
- * `view` then `edit` is what turns a denial into 404 for a stranger and 403
- * for a viewer.
- *
- * The `id` and `onDeny` defaults are applied here as well as in the SDL:
- * graphql 17 no longer hands an input field's default to `getDirective`, and a
- * term without an id would otherwise refuse the whole schema.
- */
-export declare function readChecks(schema: GraphQLSchema, node: FieldNode, where: string, options?: ReadOptions): CheckArgs[];
-//# sourceMappingURL=check.d.ts.map

package/dist/directives/check.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/directives/check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAkB,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAW,MAAM,SAAS,CAAC;AAGpE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAEpD,MAAM,MAAM,SAAS,GAAG;IACvB,WAAW,EAAE,qBAAqB,CAAC;IACnC,MAAM,EAAE,WAAW,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACzB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACvB,SAAS,EAAE,CAgBb"}

package/dist/directives/deprecation.d.ts

@@ -1,7 +0,0 @@
-/**
- * How a `@check` mistake that 2.x let boot is reported: a warning at build,
- * naming the field, that says it becomes a refusal in the next major.
- * `@permission` is new, so the same mistake there throws.
- */
-export declare function warnCheckMistake(message: string): void;
-//# sourceMappingURL=deprecation.d.ts.map

package/dist/directives/deprecation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"deprecation.d.ts","sourceRoot":"","sources":["../../src/directives/deprecation.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,QAI/C"}

package/dist/directives/requirements.d.ts

@@ -1,14 +0,0 @@
-import type { GraphQLSchema } from 'graphql';
-import { type CheckArgs } from './check';
-import type { FieldNode, ReadOptions } from './scope';
-/**
- * Every `@check` and `@permission` on a field, validated, in the order they
- * are written — across the two names, so a field migrating one directive at a
- * time keeps its 404-then-403 ladder.
- *
- * `getDirective` answers per name, so the interleaving is read back off the
- * field's AST. A field built without one (a schema made in code) has no order
- * to keep across names, and gets its `@check`s first.
- */
-export declare function readRequirements(schema: GraphQLSchema, node: FieldNode, where: string, options?: ReadOptions): CheckArgs[];
-//# sourceMappingURL=requirements.d.ts.map

package/dist/directives/requirements.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../../src/directives/requirements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAwB,KAAK,SAAS,EAAc,MAAM,SAAS,CAAC;AAE3E,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACvB,SAAS,EAAE,CAeb"}

package/graphql/directives/check.graphqls

@@ -1,90 +0,0 @@
-# The Ory-native counterpart to @policy.
-#
-# @policy asks whether the caller CARRIES an authority. An Ory principal
-# carries none — `toPrincipal` sets `authorities: []` on purpose — because
-# Keto answers per OBJECT: "may this subject `view` `Note:<id>`". @check is how
-# a schema asks that, and `useKetoChecks(ory)` is what answers it.
-#
-# It lives here, in the shipped SDL, rather than in SHARED_TYPE_DEFS, so that
-# every consumer of SHARED_SCHEMA_PATH sees it — the subgraphs built with
-# `buildSubgraphSchema` included, which never load SHARED_TYPE_DEFS.
-
-"""
-One question, with the object left as a path instead of a value.
-"""
-input CheckPermission {
-	"""
-	The Keto namespace, e.g. "Note" — from the stack's OPL document.
-	"""
-	namespace: String!
-
-	"""
-	The permit asked of it, e.g. "view". A plain relation works too; Keto
-	answers `false`, not an error, for a name it does not know.
-	"""
-	permit: String!
-
-	"""
-	Where the object id is read: `args.<path>`, or `parent.<path>` /
-	`source.<path>` (the same root under two names), dotted paths allowed. A value that turns out to be a LIST requires the permit on every
-	element — that is what a mutation taking `ids: [ID!]!` means.
-	"""
-	id: String = "args.id"
-}
-
-"""
-What a denial looks like from outside.
-"""
-enum CheckDenial {
-	"""
-	The same answer as for an id that never existed, so ids cannot be probed.
-	The default, and the one to keep unless the caller already knows the object
-	is there.
-	"""
-	NOT_FOUND
-
-	"""
-	For a second check on 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
-}
-
-"""
-Deprecated: write `@permission(name:, type:)` in a new schema — one Keto
-question per directive, repeated for AND, with OR kept in the Keto model. This
-form keeps working and is evaluated in declaration order with @permission.
-
-The permission a field requires, in disjunctive normal form: the OUTER list is
-OR, the INNER list is AND. `[[A, B], [C]]` reads "(A and B) or C" — the same
-shape `@policy(policies: [["ADMIN"]])` uses.
-
-Repeatable, and evaluated in declaration order, each with its own `onDeny`.
-That is how the 404-then-403 ladder is written:
-
-    updateNote(id: ID!, input: UpdateNoteInput!): Note!
-      @check(permissions: [[{ namespace: "Note", permit: "view" }]])
-      @check(permissions: [[{ namespace: "Note", permit: "edit" }]], onDeny: FORBIDDEN)
-
-NOT for a field that answers a LIST the caller is entitled to. "Which notes may
-I see" is not a check, it is a Keto query folded into the database filter
-before the read. A directive there would have to fetch everything and filter
-after, which makes `totalCount` and the cursors lie.
-"""
-directive @check(
-	permissions: [[CheckPermission!]!]!
-	onDeny: CheckDenial! = 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 whenever the API's own service layer answers the same refusal with a
-	domain message. Two layers guard these fields — the directive, and the
-	`require<M>Access` the service calls — 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 means "it is gone". That is precisely the
-	distinction NOT_FOUND exists to hide.
-	"""
-	message: String
-) repeatable on FIELD_DEFINITION