@nxgt/shared-graphql 2.0.1 → 2.1.0

package/docs/troubleshooting.md

@@ -0,0 +1,170 @@
+# 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.
+
+## When the schema is built
+
+### ``@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:
+
+```graphql
+note(noteId: ID!): Note @permission(name: "view", type: "Note", id: "args.noteId")
+```
+
+### ``@permission on <Type.field>: `id` reads "args.<name>", but the field declares <arguments>``
+
+The path reads an argument the field does not have — usually the default
+`args.id` on a field whose argument is named otherwise. graphql-js never puts
+an undeclared argument on `args`, so every request would have failed. Name the
+argument in `id`, or read the parent with `parent.<path>`.
+
+### `@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.
+
+### `@check on <Type.field>: an empty permission requirement admits nobody — remove it, or name a permission`
+
+`@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 on <Type.field>: unknown namespace "<type>" — known: <namespaces>`
+
+You passed `namespaces` to `useKetoChecks` / `applyKetoChecks`, and the field
+names one outside them — most often a typo. Keto would have answered `false`
+for ever, without an error. Fix the name, or add the namespace to the list
+when the OPL document gained it.
+
+### `<Type.field>: @check / @permission on an interface field guards nothing — no resolver runs there. Put it on each implementing type's field`
+
+A resolver runs on an object type's field, never on an interface's. Move the
+directive to every implementing type:
+
+```graphql
+interface Node { id: ID! }
+type Note implements Node {
+	id: ID!
+	body: String @permission(name: "view", type: "Note", id: "parent.id")
+}
+```
+
+### `@nxgt/shared-graphql: no package root`
+
+Thrown when the package is imported, if no `package.json` sits anywhere
+above its files — a bundle copied into an image without one. The more common
+case throws nothing: a bundler inlined the package into your app's bundle, the
+walk finds your app's `package.json`, and `SHARED_SCHEMA_PATH` points at
+`<app>/graphql/**`, which loads no SDL. Either way, mark
+`@nxgt/shared-graphql` external in the bundler so it stays on disk as
+installed.
+
+### `Directive "@permission" argument "name" of type "String!" is required, but it was not provided.`
+
+On graphql 17: `Argument "@permission(name:)" of type "String!" is required, but it was not provided.`
+
+Your schema declares its own `@permission`, and you load this package's
+`graphql/**/*.graphqls` (`SHARED_SCHEMA_PATH`) beside it: `mergeTypeDefs`
+merges the two declarations into one with both sets of arguments, and your
+usages lack `name` and `type`. `@permission` and `PermissionDenial` are
+names this package ships. Load only the folders you need —
+`graphql/scalars`, `graphql/schema` — or rename your directive.
+`useKetoChecks` itself leaves a `@permission` without `name` and `type`
+alone.
+
+### `Cannot use GraphQLSchema "<schema>" from another module or realm.`
+
+Two copies of `graphql` are installed: `graphql` is a peer of this package
+(`^16.4.2 || ^17.0.0`), so your app must declare it once, and every GraphQL
+library must resolve that one. Add `graphql` to your `dependencies` if it was
+only there through this package, and check with `bun pm ls graphql` (or
+`npm ls graphql`) that one version remains. graphql runs this check only
+when `NODE_ENV` is not `production`; in production two copies fail later,
+with less telling errors.
+
+## When a request runs
+
+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`
+
+The path was valid, but at request time it pointed at nothing — a nullable
+argument nobody passed, an empty list, a parent field the parent resolver did
+not load. It is a 500, never an allow. Make the argument required, or make
+sure the parent object carries the field.
+
+### `<Type.field>: no checker on the context — useKetoChecks(ory) is not registered`
+
+The schema was transformed with `applyKetoChecks` but the plugin that puts the
+per-request checker on the context is missing. Register
+`useKetoChecks(ory)` after `useOryAuth(ory)`.
+
+### `can(): no checker on the context — useKetoChecks(ory) is not registered`
+
+The same, from `can`.
+
+### `ory: keto is unavailable` with `SERVICE_UNAVAILABLE` and HTTP 503
+
+Keto (or Kratos, Hydra — the name varies) did not answer. This is on
+purpose: an outage is never turned into a denial or an anonymous caller. The
+client can retry; `extensions.debugMessage` carries what the SDK saw.
+
+### `Unexpected error.` with `INTERNAL_SERVER_ERROR` where a 404 or 403 was expected
+
+`createMaskError` is not registered, so Yoga masks the `CustomException` a
+denial throws as it masks any non-GraphQL error:
+
+```ts
+createYoga({ maskedErrors: { maskError: createMaskError(translate) } });
+```
+
+Under Apollo Server, the counterpart is `formatError: createFormatError(translate)`.
+
+### `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
+message meant for the caller.
+
+## Traps that throw nothing
+
+### 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`.
+
+### `useAuth()` trusts the request body
+
+`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)`.
+
+### `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.

package/graphql/directives/check.graphqls

@@ -25,8 +25,8 @@ input CheckPermission {
 	permit: String!
 
 	"""
-	Where the object id is read: `args.<path>` or `source.<path>`, dotted paths
-	allowed. A value that turns out to be a LIST requires the permit on every
+	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"
@@ -51,6 +51,10 @@ enum CheckDenial {
 }
 
 """
+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.

package/graphql/directives/permission.graphqls

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

package/package.json

@@ -1,12 +1,13 @@
 {
 	"name": "@nxgt/shared-graphql",
-	"version": "2.0.1",
+	"version": "2.1.0",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"files": [
 		"dist",
+		"docs",
 		"graphql",
 		"README.md",
 		"package.json",
@@ -56,14 +57,13 @@
 		"@graphql-tools/utils": "^12.0.0",
 		"@graphql-yoga/redis-event-target": "^3.0.3",
 		"@hono/zod-validator": "^0.9.0",
-		"@nxgt/i18n": "^1.0.4",
-		"@nxgt/security": "^4.0.0",
-		"@nxgt/shared": "^1.0.4",
+		"@nxgt/i18n": "^1.1.0",
+		"@nxgt/security": "^4.0.1",
+		"@nxgt/shared": "^1.0.5",
 		"@nxgt/shared-exceptions": "^1.0.4",
 		"@nxgt/shared-logging": "^1.0.4",
 		"@nxgt/shared-mongo": "^1.1.4",
 		"dataloader": "^2.2.3",
-		"graphql": "^16.4.2",
 		"graphql-scalars": "^1.26.0",
 		"graphql-subscriptions": "^3.0.0",
 		"graphql-upload": "^18.0.0",
@@ -79,10 +79,12 @@
 		"@types/bun": "^1.4.0",
 		"@types/graphql-upload": "^17.0.0",
 		"@types/lodash": "^4.17.25",
-		"@types/ws": "^8.18.1"
+		"@types/ws": "^8.18.1",
+		"graphql": "^16.4.2"
 	},
 	"peerDependencies": {
 		"@nxgt/ory-sdk": ">=0.1.0",
+		"graphql": "^16.4.2 || ^17.0.0",
 		"stx-sdk": ">=1.1.0",
 		"typescript": "^6.0.3"
 	}

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

@@ -1,23 +0,0 @@
-import type { ApolloServerOptions } from '@apollo/server';
-import { type LocaleKey, type TranslationContext } from '@nxgt/i18n';
-import { GraphQLError, type GraphQLErrorOptions } from 'graphql';
-import type { MaskError } from 'graphql-yoga';
-import type { GraphQLBaseContext } from '../types';
-export declare function createGraphQLError(message: string, options?: GraphQLErrorOptions): GraphQLError;
-export declare function createFormatError<K extends LocaleKey, C extends GraphQLBaseContext = GraphQLBaseContext>(translate?: (message: K, context?: TranslationContext) => string, production?: boolean): ApolloServerOptions<C>['formatError'];
-/**
- * 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; 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 exactly as before.
- *
- *     createYoga({ maskedErrors: { maskError: createMaskError(translate) } })
- */
-export declare function createMaskError<K extends LocaleKey>(translate?: (message: K, context?: TranslationContext) => string): MaskError;
-//# sourceMappingURL=errors.utils.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"errors.utils.d.ts","sourceRoot":"","sources":["../../src/utils/errors.utils.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,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,mBAAmB,GAC3B,YAAY,CAEd;AAED,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,CAoDvC;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EAClD,SAAS,GAAE,CACV,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,kBAAkB,KACxB,MAAsB,GACzB,SAAS,CAkDX"}