@usehenri/graphql 0.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# @usehenri/graphql
+
+## 1.2.0
+
+### Minor Changes
+
+- [#404](https://github.com/usehenri/henri/pull/404) [`ab5a8e4`](https://github.com/usehenri/henri/commit/ab5a8e4a88c80cca070a2b8ad398c80babdaff11) Thanks [@reel](https://github.com/reel)! - A model's GraphQL definition is derived from the schema it already declares.
+  
+  A model that wanted GraphQL wrote its types out by hand, in SDL, immediately below the henri schema that had just said the same thing — the field names again, the types again, and the resolvers to go with them ([#68](https://github.com/usehenri/henri/issues/68), open since 2019). `graphql: true` is now the whole key:
+  
+  ```js
+  module.exports = {
+    graphql: true,
+    schema: {
+      title: { type: 'string', required: true },
+      year: { type: 'integer' },
+    },
+  };
+  ```
+  
+  which serves `type Artwork { id: ID! title: String! year: Int ... }`, `artwork(id: ID!)` and `artworks(page:, perPage:, where:)` — an `ArtworkPage`, so no derived query is unbounded.
+  
+  **It is derived at boot, not written into the file, and that is the decision worth stating.** A generator would have handed over an honest copy that stops being true the first time a column, a `personal` mark, an `encrypted` mark or `config.externalIds` changes; the definition depends on all four. henri already refuses that trade for the OpenAPI document, for the HAL `_links` and for what a foreign key publishes as. `henri graphql` prints the derived SDL without booting — paste it into a model's own `types` when you want to own it — and `henri graphql --summary` says what was left out of each model and why.
+  
+  **`id` is the `externalId`.** The primary key is not a field, it is not an argument, and `artwork(id:)` resolves through `findById()`, which takes the public identifier and nothing else. A declared foreign key is an `ID` carrying the target row's `externalId`, and a mutation writing one takes an `externalId` back and looks the row up: the identifier rule, in both directions.
+  
+  **What is never derived is read off the model, not off a list of names.** A field marked `personal: { expose: false }` is not a field — which is what leaves the user's `password` out, since `base/privacy.js` marks it that way on every application with a user model. A field marked `personal: true` is a field and never an argument: a value you may read on a record you are allowed to see is not one anybody may search by. A randomised `encrypted` field is never an argument either, because henri refuses that query with `HENRI_ENCRYPTION_NOT_QUERYABLE` and a field the framework will not query has no business being a queryable one. A `json` column has no shape GraphQL could state, so it is left for a scalar of your own.
+  
+  **Queries by default, mutations on request.** `graphql: { generate: true, mutations: true }` adds `createArtwork`, `updateArtwork` and `deleteArtwork`; nothing writes unless a model asks, because a delete mutation on the endpoint of an application that never wanted one is a hole. The block also takes `name`, `queries`, `filters`, `except`, and the `types` and `resolvers` you write yourself, which are merged on top of the derived ones and win.
+  
+  **Every derived resolver goes through `app/policies`, and there is no setting that turns that off.** One record asks `show`; a refusal and a row that is not there both answer `null`, the same non-oracle `findById()` follows. A list asks `index` and then asks the policy what the list _is_ — `scope(user)` is the condition it filters by, and a `where` argument narrows that and never widens it. Mutations ask `create`, `update` and `destroy`. Policies fail closed, so a model with `graphql: true` and no `app/policies/<model>.js` serves an empty page and a null record: opting a model into GraphQL is not opting it out of authorization. Everything answered is published and stripped by the same two functions every other answer goes through.
+  
+  `henri doctor` reports the three things that are otherwise invisible: a `graphql` key that would fail the boot (`graphql.declaration`), a derived model with no policy behind it or a policy with no `scope(user)` behind its list query (`graphql.policy`), and a hand-written definition naming a field marked `personal: { expose: false }` (`graphql.exposed`) — the drift a derived definition cannot have.
+  
+  A model that writes `graphql: { types, resolvers }` is untouched: nothing is derived unless `generate` asks for it. Four codes are new: `HENRI_API_GRAPHQL_INVALID_DECLARATION`, `HENRI_API_GRAPHQL_SCOPE_REQUIRED`, `HENRI_API_GRAPHQL_DENIED` and `HENRI_API_GRAPHQL_UNKNOWN_REFERENCE`. The [GraphQL guide](https://usehenri.io/guides/graphql/) has the whole table.
+
+- [#351](https://github.com/usehenri/henri/pull/351) [`fda9366`](https://github.com/usehenri/henri/commit/fda9366e9ed2b072764a995c5aa60205ca7a4725) Thanks [@reel](https://github.com/reel)! - GraphQL moves out of core into `@usehenri/graphql`
+  
+  The GraphQL layer is now a package of its own. `@usehenri/core` no longer
+  depends on `@apollo/server`, `@as-integrations/express5`,
+  `@graphql-tools/merge`, `@graphql-tools/schema` or `graphql`, so an
+  application that never mounts a schema stops installing them.
+  
+  An application that uses GraphQL adds one dependency,
+  `npm install @usehenri/graphql`, and nothing else changes: the package ships
+  the henri module itself, so depending on it is what puts `henri.graphql` in
+  the boot, with the same `run()`, `endpoint`, `active`, error classes and
+  `toApolloError()`. The endpoint is still `/_henri/gql` (still configurable
+  with the `graphql` key) and the schema is still built from the models'
+  `graphql` keys.
+  
+  `@usehenri/core/module` is the base class a module package extends, and this
+  is the first package to use it: it is the supported path, so a module of your
+  own no longer reaches into `@usehenri/core/src/base/module`.
+  
+  Without the package henri says so instead of going quiet: a model declaring a
+  `graphql` key fails the boot with the install line, `res.render(view, { graphql })`
+  fails the request with it, and `henri doctor` reports it as a missing
+  dependency. `henri.graphql` is `undefined` rather than an object that does
+  nothing, which the type declarations say too, and a page has no `graphql` key
+  among its view options.
+
+### Patch Changes
+
+- Updated dependencies [[`792a15a`](https://github.com/usehenri/henri/commit/792a15ade614cf8b920d9197586f9866700d458e), [`1e23664`](https://github.com/usehenri/henri/commit/1e23664829bd1a356de28f404cfb21c9ae211388), [`5b627ad`](https://github.com/usehenri/henri/commit/5b627adfa37e9f16bc75af96cc8ff5308a91f688), [`4dff51e`](https://github.com/usehenri/henri/commit/4dff51edc050e29398c793a5aedb48776b7b7119), [`60dbf33`](https://github.com/usehenri/henri/commit/60dbf33c2a4f14e328a0df1cb44be061e15431e5), [`1b316c6`](https://github.com/usehenri/henri/commit/1b316c6f3c5d5eb5752c70b534092d1052956cc6), [`d074e8b`](https://github.com/usehenri/henri/commit/d074e8b482582e25f80d8a14b4735e69a2b7821e), [`7fd13f6`](https://github.com/usehenri/henri/commit/7fd13f631b75f7aa152b73046b50c6902ae3ca93), [`b559fb7`](https://github.com/usehenri/henri/commit/b559fb72b391eeb21a3f6a0cda1515e01ecbfafc), [`1c0dfe8`](https://github.com/usehenri/henri/commit/1c0dfe84a98eff2122512256c4f42ec7ccde4212), [`93060a8`](https://github.com/usehenri/henri/commit/93060a86df795dbbd99bf1895beb0cf14c4b86de), [`e031900`](https://github.com/usehenri/henri/commit/e031900082f28aec72af4cda9cd959f932e2ebc7), [`9173000`](https://github.com/usehenri/henri/commit/91730005efa88f073bfaaf67078c3ec0e137b459), [`62fac46`](https://github.com/usehenri/henri/commit/62fac46fd6cae5581979b73daf99700fd246e0ea), [`b7f33e2`](https://github.com/usehenri/henri/commit/b7f33e28a5e4844391befd75d08e42c4cf6212ed), [`3d6f3fc`](https://github.com/usehenri/henri/commit/3d6f3fc048d05db41be86069608d342e437408cb), [`b278119`](https://github.com/usehenri/henri/commit/b2781190de436eb5838e866446c9a0c8210bb6ca), [`b161e1b`](https://github.com/usehenri/henri/commit/b161e1b8fad94af2d2afc351dc1bc07dabbb1379), [`7cb0b04`](https://github.com/usehenri/henri/commit/7cb0b04b29b61dedaa82fcd1972646fb3765acfc), [`1616e34`](https://github.com/usehenri/henri/commit/1616e343a612be2bffffcfa5b23bfa8ad191bbe3), [`c8f5367`](https://github.com/usehenri/henri/commit/c8f53678b33341d086b467f801e959314afc7860), [`bcf4ce2`](https://github.com/usehenri/henri/commit/bcf4ce22bcd294844504164fac1fa4aef1ffec41), [`ab5a8e4`](https://github.com/usehenri/henri/commit/ab5a8e4a88c80cca070a2b8ad398c80babdaff11), [`43d267f`](https://github.com/usehenri/henri/commit/43d267f0f9d192b2c01e89c3925b7daf5000041b), [`9f868f3`](https://github.com/usehenri/henri/commit/9f868f3d9162fa218e34304110210e6949f97d5c), [`d88bf7f`](https://github.com/usehenri/henri/commit/d88bf7fe038a6b58e7bed02ff4c90755f6c0e65e), [`49398a6`](https://github.com/usehenri/henri/commit/49398a6308f0760f01c6ff2ec98aaa35f484474d), [`89dda62`](https://github.com/usehenri/henri/commit/89dda62da456a0a55600e79cfb65ce89f11258e2), [`62fac46`](https://github.com/usehenri/henri/commit/62fac46fd6cae5581979b73daf99700fd246e0ea), [`a93d6cc`](https://github.com/usehenri/henri/commit/a93d6cc39b33b261089e91f3e757b54fefc9fe15), [`d9f3be4`](https://github.com/usehenri/henri/commit/d9f3be49c5929d929a220220bf6e72fdcb135595), [`c44f025`](https://github.com/usehenri/henri/commit/c44f025acec3d5bbbb57e2310d02184a1053a10d), [`67cfb20`](https://github.com/usehenri/henri/commit/67cfb200ea0e0b31bacf2af183db6467b0fa011d), [`e661f98`](https://github.com/usehenri/henri/commit/e661f98fe8f8acce15aa10ce2dc320c5a2cb006f), [`43a0e1a`](https://github.com/usehenri/henri/commit/43a0e1a6a320baa43298391e1c1e0334d6cd28d5), [`cee57b9`](https://github.com/usehenri/henri/commit/cee57b9d3521a4a70c715222eae1f18ff4a6c128), [`61bf75c`](https://github.com/usehenri/henri/commit/61bf75cbaccda1aecff34408a175b2d85447d7a8), [`2c8a826`](https://github.com/usehenri/henri/commit/2c8a8265262dbf6ea5c3e73e8e7892a230d4d0f0), [`46d5dbc`](https://github.com/usehenri/henri/commit/46d5dbcc983c03e96ae5a87d7288c5d8a5adbc24), [`ba97ea9`](https://github.com/usehenri/henri/commit/ba97ea968f0b34cd67b7a3e803ecd34543b8aaaf), [`5ccd537`](https://github.com/usehenri/henri/commit/5ccd537b3621b54d11e7f24ccca39643ae7d5cf7), [`d88bf7f`](https://github.com/usehenri/henri/commit/d88bf7fe038a6b58e7bed02ff4c90755f6c0e65e), [`9895cbf`](https://github.com/usehenri/henri/commit/9895cbf4be85b476e341a5be915e3049e5a027de), [`61bf75c`](https://github.com/usehenri/henri/commit/61bf75cbaccda1aecff34408a175b2d85447d7a8), [`5a150d5`](https://github.com/usehenri/henri/commit/5a150d576208571c32b9cd12827d035e31ed4313), [`3c1c5b8`](https://github.com/usehenri/henri/commit/3c1c5b83ea135b000ddd6ffbfd05457b000f2f7c), [`2625067`](https://github.com/usehenri/henri/commit/26250673d91ab70ad024739d02b647754f75267d), [`aa3f90b`](https://github.com/usehenri/henri/commit/aa3f90bd6f42bb05431c33f3e4bf2202cb6bb7c6), [`a1c6769`](https://github.com/usehenri/henri/commit/a1c6769099e3dc28b22b5338a2a57b13bdf69f7a), [`0a8bb41`](https://github.com/usehenri/henri/commit/0a8bb415d352cd75b12d07e591c8ec7c16774a99), [`ec1c8c4`](https://github.com/usehenri/henri/commit/ec1c8c419f4d9063a7617472b2970fdb8a929fa1), [`dd2731d`](https://github.com/usehenri/henri/commit/dd2731d6a20fd96aa1be1aeb5e6ec0155001326b), [`ab52e18`](https://github.com/usehenri/henri/commit/ab52e187c420dfe381f03ed51c5c141fda525acb), [`b7b56e1`](https://github.com/usehenri/henri/commit/b7b56e190ae774abc0096fe2aebaf91f823115af), [`b7038ce`](https://github.com/usehenri/henri/commit/b7038ceaa430f4a0b9eaf7e983fc2844421bf636), [`1ea0f85`](https://github.com/usehenri/henri/commit/1ea0f85066b86fba31f58937cc10abb6359e6a26), [`762062a`](https://github.com/usehenri/henri/commit/762062aadc450d49b1a2d15524f9d579ab4f60e7), [`01a561a`](https://github.com/usehenri/henri/commit/01a561aa58650ec15df1c2659795a5e4c5bbfd53), [`bd1b630`](https://github.com/usehenri/henri/commit/bd1b63083b3817b8c47b8a187de76027458a1b32), [`27b5513`](https://github.com/usehenri/henri/commit/27b5513d1cae8aba734fe27da0ace2a82423e2f4), [`e31a3f7`](https://github.com/usehenri/henri/commit/e31a3f73e7e8facf3cedf7460f115e57995f32c3), [`2689779`](https://github.com/usehenri/henri/commit/26897798b840fd28a4bc091c050a83457b36905d), [`72cd1d3`](https://github.com/usehenri/henri/commit/72cd1d35ffb99311bbca815c1f6ab41ee3682f64), [`a2e1ec2`](https://github.com/usehenri/henri/commit/a2e1ec29df52462f12ebaae9bfbc1ad4f427b27f), [`afead74`](https://github.com/usehenri/henri/commit/afead7489498ed42e1893a25123ea772cac2ca09), [`a4ecba5`](https://github.com/usehenri/henri/commit/a4ecba50c663f4d5c741adbb6cd9bc0eefe0e5cc), [`baec3fd`](https://github.com/usehenri/henri/commit/baec3fd22be92bf8ffbaeb251b0b6c2771f8347a), [`1103628`](https://github.com/usehenri/henri/commit/110362808f8ec6d73a75ff7fc89a77f3e943d773), [`e865d94`](https://github.com/usehenri/henri/commit/e865d945d65419ac676f5a2fe3ba3b6114a1e53d), [`4274567`](https://github.com/usehenri/henri/commit/4274567e20a980657f07df9ec7db25296c7d55f5), [`aea429c`](https://github.com/usehenri/henri/commit/aea429ca99338a62370ab3e3d94bdc6b8c227601), [`8a8e3b3`](https://github.com/usehenri/henri/commit/8a8e3b33d7967b81f66633aa25c3075318f01d60), [`18715f9`](https://github.com/usehenri/henri/commit/18715f90ea8958dc57da1bb029b8209c36b84cc6), [`0d2ebc3`](https://github.com/usehenri/henri/commit/0d2ebc344bfcd80533ef900638083e4c105407bb), [`49398a6`](https://github.com/usehenri/henri/commit/49398a6308f0760f01c6ff2ec98aaa35f484474d), [`ec64e44`](https://github.com/usehenri/henri/commit/ec64e44e7b79a02da5fc587a72a9a6c900836982), [`831aa5c`](https://github.com/usehenri/henri/commit/831aa5c011f3432630c68b8d26755d2582f82f74), [`16824e8`](https://github.com/usehenri/henri/commit/16824e8fe9ccc6a04dab5d9b2481c29ff4f6b64b), [`fda9366`](https://github.com/usehenri/henri/commit/fda9366e9ed2b072764a995c5aa60205ca7a4725), [`1a86acb`](https://github.com/usehenri/henri/commit/1a86acbf15e4a43e5fb81277bb22e101c06e77a4), [`808d824`](https://github.com/usehenri/henri/commit/808d82471d59e64ccc735f617bab293eb572c46b), [`0b32fbd`](https://github.com/usehenri/henri/commit/0b32fbde19c95da8fe07fab76933840a4242c71c), [`c0c16e8`](https://github.com/usehenri/henri/commit/c0c16e873ba440aee9832160553cbb12ab81bd2c), [`41470bf`](https://github.com/usehenri/henri/commit/41470bf378d83ca3d35d00e8c31796fea5eb15e0), [`8e44e7e`](https://github.com/usehenri/henri/commit/8e44e7e882dd8741b3ac632651b453389d76bf2c), [`de1c1e0`](https://github.com/usehenri/henri/commit/de1c1e02ed83d13dcfeb8e44012f309eb663f03e), [`4b4677d`](https://github.com/usehenri/henri/commit/4b4677d4a09d39fe50b1fa4af577600342578daf)]:
+  - @usehenri/core@1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016-present, Félix-Antoine Paradis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
+<!-- generated by scripts/prepublish.js -->
+
 # @usehenri/graphql
 
-Placeholder release. Install a real version: see https://usehenri.io.
+Henri GraphQL: the types and resolvers of the models, merged and served by Apollo Server.
+
+Part of [henri](https://usehenri.io), the Rails-like React framework for
+Node.js: [documentation](https://usehenri.io),
+[source and issues](https://github.com/usehenri/henri),
+[changelog](https://github.com/usehenri/henri/blob/master/packages/graphql/CHANGELOG.md).

package/index.js

@@ -0,0 +1,18 @@
+const Graphql = require('./src/graphql');
+
+/**
+ * GraphQL for henri.
+ *
+ * `@usehenri/core` resolves this package from the application directory the
+ * way it resolves a store adapter, and exposes what it builds as
+ * `henri.graphql`. An application that does not install it never loads
+ * Apollo Server, and core says so the moment something asks for a query.
+ *
+ * @param {object} henri A henri instance
+ * @returns {Graphql} The engine
+ */
+const create = (henri) => new Graphql(henri);
+
+module.exports = create;
+module.exports.Graphql = Graphql;
+module.exports.create = create;

package/module.js

@@ -0,0 +1,8 @@
+/**
+ * The henri module this package ships.
+ *
+ * `package.json` points at this file with `"henri": { "module": "./module.js" }`,
+ * which is all core reads: an application depending on `@usehenri/graphql`
+ * has the module in its boot, as `henri.graphql`.
+ */
+module.exports = require('./src/graphql');

package/package.json

@@ -1,15 +1,56 @@
 {
-  "description": "Placeholder creating @usehenri/graphql on npm; the first real version is published by the henri release workflow",
-  "homepage": "https://usehenri.io",
-  "license": "MIT",
   "name": "@usehenri/graphql",
-  "publishConfig": {
-    "access": "public"
-  },
+  "version": "1.2.0",
+  "description": "henri GraphQL: the types and resolvers of the models, merged and served by Apollo Server",
+  "license": "MIT",
+  "author": "Felix-Antoine Paradis",
+  "homepage": "https://usehenri.io",
   "repository": {
-    "directory": "packages/graphql",
     "type": "git",
-    "url": "git+https://github.com/usehenri/henri.git"
+    "url": "git+https://github.com/usehenri/henri.git",
+    "directory": "packages/graphql"
+  },
+  "bugs": {
+    "url": "https://github.com/usehenri/henri/issues"
+  },
+  "keywords": [
+    "henri",
+    "graphql",
+    "apollo",
+    "schema",
+    "resolvers"
+  ],
+  "main": "index.js",
+  "henri": {
+    "module": "./module.js"
+  },
+  "files": [
+    "index.js",
+    "module.js",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@apollo/server": "^5.2.0",
+    "@as-integrations/express5": "^1.1.2",
+    "@graphql-tools/merge": "^9.2.3",
+    "@graphql-tools/schema": "^10.1.0",
+    "debug": "^4.4.3",
+    "graphql": "^16.11.0"
+  },
+  "peerDependencies": {
+    "@usehenri/core": "^1.2.0"
   },
-  "version": "0.0.0"
-}
+  "devDependencies": {
+    "@usehenri/core": "^1.2.0",
+    "express": "^5.2.1",
+    "supertest": "^7.2.2"
+  }
+}

package/src/graphql-guard.js

@@ -0,0 +1,404 @@
+/**
+ * Bounds on the GraphQL endpoint.
+ *
+ * A rate limiter caps how many requests arrive. It says nothing about what
+ * one request costs, and one GraphQL request can cost arbitrarily much: a
+ * hundred aliases of the same expensive field, a fragment spread a thousand
+ * times, or a walk down a cycle the schema happens to contain. This module
+ * refuses those before a single resolver runs.
+ *
+ * Three bounds, all schema-independent, so they protect an application whose
+ * schema its author has never audited:
+ *
+ * - `maxAliases`: the universal one. Aliasing does not need a cycle or a deep
+ *   schema, it works against anything, so this is the strict default.
+ * - `maxComplexity`: how many fields the query selects in total, fragments
+ *   expanded, which is what a fragment bomb inflates.
+ * - `maxDepth`: nesting, which needs the schema to offer somewhere deep to
+ *   go, so it is the loosest of the three.
+ *
+ * `maxTokens` bounds the document before it is even parsed, and is passed to
+ * graphql's own parser rather than implemented here.
+ */
+const { GraphQLError, Kind } = require('graphql');
+
+/**
+ * Defaults.
+ *
+ * Roomy enough that a page's own query never meets them (a handful of
+ * aliases, a dozen fields, four or five levels) and tight enough that
+ * amplification stops being free.
+ */
+const DEFAULTS = Object.freeze({
+  maxAliases: 15,
+  maxComplexity: 1000,
+  maxDepth: 10,
+  maxTokens: 5000,
+});
+
+/**
+ * Normalizes `config.graphql`.
+ *
+ * A string stays what it always was: the endpoint. An object takes the
+ * endpoint, the limits and the access rules.
+ *
+ * @param {*} raw the configured value
+ * @param {string} fallback the default endpoint
+ * @returns {{endpoint: string, authenticated: boolean, roles: Array<string>, loopbackOnly: boolean, introspection: ?boolean, maxAliases: number, maxComplexity: number, maxDepth: number, maxTokens: number}} the settings
+ * @throws {TypeError} when it is neither a string nor an object
+ */
+function graphqlConfig(raw, fallback) {
+  const settings = Object.assign({}, DEFAULTS, {
+    authenticated: false,
+    endpoint: fallback,
+    introspection: null,
+    loopbackOnly: false,
+    roles: [],
+  });
+
+  if (typeof raw === 'undefined' || raw === null) {
+    return settings;
+  }
+
+  if (typeof raw === 'string') {
+    settings.endpoint = raw;
+
+    return settings;
+  }
+
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new TypeError(
+      'config.graphql must be a string (the endpoint) or an object ({ endpoint, authenticated, roles, loopbackOnly, introspection, maxDepth, maxAliases, maxComplexity, maxTokens })'
+    );
+  }
+
+  if (typeof raw.endpoint === 'string' && raw.endpoint.length > 0) {
+    settings.endpoint = raw.endpoint;
+  }
+  if (typeof raw.introspection === 'boolean') {
+    settings.introspection = raw.introspection;
+  }
+  settings.authenticated = Boolean(raw.authenticated);
+  settings.loopbackOnly = Boolean(raw.loopbackOnly);
+  settings.roles = []
+    .concat(raw.roles || [])
+    .filter((role) => typeof role === 'string' && role.length > 0);
+
+  if (settings.roles.length > 0) {
+    settings.authenticated = true;
+  }
+
+  for (const key of ['maxAliases', 'maxComplexity', 'maxDepth', 'maxTokens']) {
+    if (raw[key] === false) {
+      settings[key] = Infinity;
+    } else if (Number.isInteger(raw[key]) && raw[key] > 0) {
+      settings[key] = raw[key];
+    }
+  }
+
+  return settings;
+}
+
+/**
+ * Measures one operation: its depth, how many aliases it uses and how many
+ * fields it selects in total, with fragments expanded.
+ *
+ * The walk stops as soon as a limit is passed, so a document built to blow
+ * up the analyzer cannot: the analyzer is bounded by the same numbers it
+ * enforces. Fragment cycles (which graphql's own `NoFragmentCycles` refuses
+ * separately) are cut by the visited set.
+ *
+ * @param {object} node an operation or fragment definition
+ * @param {Map<string, object>} fragments the document's fragments, by name
+ * @param {{maxAliases: number, maxComplexity: number, maxDepth: number}} limits the limits
+ * @returns {{aliases: number, complexity: number, depth: number}} the measurements
+ */
+function measure(node, fragments, limits) {
+  const totals = { aliases: 0, complexity: 0, depth: 0 };
+
+  /**
+   * Whether one of the limits has been passed already
+   *
+   * @returns {boolean} stop or not
+   */
+  const done = () =>
+    totals.aliases > limits.maxAliases ||
+    totals.complexity > limits.maxComplexity ||
+    totals.depth > limits.maxDepth;
+
+  /**
+   * Walks a selection set
+   *
+   * @param {object} selectionSet the selection set
+   * @param {number} depth its depth
+   * @param {Set<string>} seen fragments already spread on this path
+   * @returns {void}
+   */
+  const walk = (selectionSet, depth, seen) => {
+    if (!selectionSet || done()) {
+      return;
+    }
+
+    totals.depth = Math.max(totals.depth, depth);
+
+    for (const selection of selectionSet.selections) {
+      if (done()) {
+        return;
+      }
+
+      if (selection.kind === Kind.FIELD) {
+        totals.complexity += 1;
+        if (selection.alias) {
+          totals.aliases += 1;
+        }
+        if (selection.selectionSet) {
+          walk(selection.selectionSet, depth + 1, seen);
+        }
+        continue;
+      }
+
+      if (selection.kind === Kind.INLINE_FRAGMENT) {
+        // An inline fragment is not a level of its own
+        walk(selection.selectionSet, depth, seen);
+        continue;
+      }
+
+      if (selection.kind === Kind.FRAGMENT_SPREAD) {
+        const name = selection.name.value;
+        const fragment = fragments.get(name);
+
+        if (!fragment || seen.has(name)) {
+          continue;
+        }
+
+        const nested = new Set(seen);
+
+        nested.add(name);
+        walk(fragment.selectionSet, depth, nested);
+      }
+    }
+  };
+
+  walk(node.selectionSet, 1, new Set());
+
+  return totals;
+}
+
+/**
+ * A graphql validation rule refusing queries past the limits.
+ *
+ * It runs before execution, so a refused query costs a parse and a walk and
+ * nothing else.
+ *
+ * @param {{maxAliases: number, maxComplexity: number, maxDepth: number}} limits the limits
+ * @returns {function} a graphql ValidationRule
+ */
+function queryLimits(limits) {
+  return (context) => ({
+    /**
+     * @param {object} node an OperationDefinition
+     * @returns {false} never descend: the walk below did it already
+     */
+    OperationDefinition(node) {
+      const fragments = new Map();
+
+      for (const definition of context.getDocument().definitions) {
+        if (definition.kind === Kind.FRAGMENT_DEFINITION) {
+          fragments.set(definition.name.value, definition);
+        }
+      }
+
+      const { aliases, complexity, depth } = measure(node, fragments, limits);
+
+      if (depth > limits.maxDepth) {
+        context.reportError(
+          new GraphQLError(
+            `Query is too deep: ${depth} levels, the limit is ${limits.maxDepth}`,
+            { extensions: { code: 'GRAPHQL_VALIDATION_FAILED' }, nodes: [node] }
+          )
+        );
+      }
+
+      if (aliases > limits.maxAliases) {
+        context.reportError(
+          new GraphQLError(
+            `Query uses too many aliases: more than ${limits.maxAliases}`,
+            { extensions: { code: 'GRAPHQL_VALIDATION_FAILED' }, nodes: [node] }
+          )
+        );
+      }
+
+      if (complexity > limits.maxComplexity) {
+        context.reportError(
+          new GraphQLError(
+            `Query is too complex: it selects more than ${limits.maxComplexity} fields`,
+            { extensions: { code: 'GRAPHQL_VALIDATION_FAILED' }, nodes: [node] }
+          )
+        );
+      }
+
+      return false;
+    },
+  });
+}
+
+/**
+ * An Apollo plugin that stops resolving once the client is gone.
+ *
+ * graphql-js 16 cannot cancel an execution that has started, so this is done
+ * where it can be: every field asks first, and a query whose client
+ * disconnected or whose request already timed out (`base/timeout.js` answered
+ * a 503) stops at the next field instead of running to completion against
+ * nobody.
+ *
+ * @returns {object} an ApolloServerPlugin
+ */
+function cancellation() {
+  return {
+    /**
+     * @param {object} params the request
+     * @param {object} params.contextValue henri's context (`{ req, res }`)
+     * @returns {Promise<object>} the request listener
+     */
+    async requestDidStart({ contextValue }) {
+      const req = contextValue && contextValue.req;
+      const res = contextValue && contextValue.res;
+      let disconnected = false;
+
+      if (res && typeof res.once === 'function') {
+        res.once('close', () => {
+          disconnected = !res.writableEnded;
+        });
+      }
+
+      /**
+       * Whether nobody is waiting for this answer any more: the client hung
+       * up, or `base/timeout.js` already answered a 503
+       *
+       * @returns {boolean} gone or not
+       */
+      const gone = () =>
+        disconnected ||
+        Boolean(req && req.timedout) ||
+        Boolean(req && req.socket && req.socket.destroyed);
+
+      return {
+        /**
+         * @returns {Promise<object>} the execution listener
+         */
+        async executionDidStart() {
+          return {
+            /**
+             * @returns {void}
+             * @throws {GraphQLError} when the client is gone
+             */
+            willResolveField() {
+              if (gone()) {
+                throw new GraphQLError('Request cancelled', {
+                  extensions: { code: 'REQUEST_CANCELLED' },
+                });
+              }
+            },
+          };
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Whether a user owns every one of the given roles.
+ *
+ * Deliberately a local copy rather than an import from core: this module is
+ * meant to travel with the GraphQL layer wherever it lives.
+ *
+ * @param {object} user a user instance
+ * @param {Array<string>} roles the roles it must have
+ * @returns {Promise<boolean>} allowed or not
+ */
+async function hasRoles(user, roles) {
+  if (!user) {
+    return false;
+  }
+
+  if (typeof user.hasRole === 'function') {
+    return Boolean(await user.hasRole(roles));
+  }
+
+  const owned = Array.isArray(user.roles)
+    ? user.roles
+    : [user.roles].filter(Boolean);
+
+  return roles.every((role) => owned.includes(role));
+}
+
+/**
+ * The middleware guarding the endpoint: loopback only, signed in, or holding
+ * the roles the application asked for.
+ *
+ * Answers 404 off the loopback interface (the endpoint should not even look
+ * like it exists) and 401/403 otherwise.
+ *
+ * @param {object} settings the settings built by graphqlConfig()
+ * @returns {function} middleware
+ */
+/**
+ * Refuses the request: through `res.boom` when core's middleware is in front
+ * of this one, and with the body it would have sent when it is not
+ *
+ * The guard used to reach for `res.boom` unguarded. Inside a henri boot that
+ * is always there, but this package is no longer the same package as the
+ * middleware that puts it there, and nothing declares the dependency. The
+ * fallback is byte-identical to `base/boom.js` (same status, same body, same
+ * key order), so it only ever fires where the alternative was a TypeError.
+ * `base/csrf.js` in core does the same thing for the same reason.
+ *
+ * @param {object} res the response
+ * @param {number} statusCode 401 or 403
+ * @param {string} error the status text
+ * @param {string} message why
+ * @returns {*} the response
+ */
+function refuse(res, statusCode, error, message) {
+  const method = statusCode === 401 ? 'unauthorized' : 'forbidden';
+
+  if (res.boom && typeof res.boom[method] === 'function') {
+    return res.boom[method](message);
+  }
+
+  return res.status(statusCode).json({ error, message, statusCode });
+}
+
+function accessGuard(settings) {
+  const { authenticated, roles } = settings;
+
+  return async (req, res, next) => {
+    if (!authenticated && roles.length === 0) {
+      return next();
+    }
+
+    const signedIn =
+      typeof req.isAuthenticated === 'function'
+        ? req.isAuthenticated()
+        : Boolean(req.user);
+
+    if (!signedIn || !req.user) {
+      return refuse(res, 401, 'Unauthorized', 'Authentication required');
+    }
+
+    if (roles.length > 0 && !(await hasRoles(req.user, roles))) {
+      return refuse(res, 403, 'Forbidden', 'Insufficient roles');
+    }
+
+    return next();
+  };
+}
+
+module.exports = {
+  DEFAULTS,
+  accessGuard,
+  cancellation,
+  graphqlConfig,
+  measure,
+  queryLimits,
+};

package/src/graphql.js

@@ -0,0 +1,377 @@
+const BaseModule = require('@usehenri/core/module');
+const { mergeTypeDefs, mergeResolvers } = require('@graphql-tools/merge');
+const { makeExecutableSchema } = require('@graphql-tools/schema');
+const { ApolloServer } = require('@apollo/server');
+const { expressMiddleware } = require('@as-integrations/express5');
+const { GraphQLError } = require('graphql');
+const debug = require('debug')('henri:graphql');
+
+const {
+  accessGuard,
+  cancellation,
+  graphqlConfig,
+  queryLimits,
+} = require('./graphql-guard');
+const { loopbackOnly } = require('./loopback');
+
+/**
+ * Build a GraphQLError subclass carrying an `extensions.code`
+ *
+ * @param {string} code the extension code (ex: UNAUTHENTICATED)
+ * @returns {typeof GraphQLError} the error class
+ */
+const errorWithCode = (code) =>
+  class extends GraphQLError {
+    /**
+     * @param {string} message error message
+     * @param {object} [options={}] GraphQLError options
+     */
+    constructor(message, options = {}) {
+      super(message, {
+        ...options,
+        extensions: { code, ...(options.extensions || {}) },
+      });
+    }
+  };
+
+const AuthenticationError = errorWithCode('UNAUTHENTICATED');
+const ForbiddenError = errorWithCode('FORBIDDEN');
+const UserInputError = errorWithCode('BAD_USER_INPUT');
+const ValidationError = errorWithCode('GRAPHQL_VALIDATION_FAILED');
+const SyntaxError = errorWithCode('GRAPHQL_PARSE_FAILED');
+
+/**
+ * The GraphQL module of henri
+ *
+ * This package ships it (`"henri": { "module": "./module.js" }` in its
+ * package.json), so an application that depends on the package has it in the
+ * boot as `henri.graphql`, with nothing else to write. An application that
+ * does not never loads Apollo Server, and `henri.graphql` is undefined.
+ *
+ * It only needs the configuration: the schema is built from the models,
+ * which extract into it at their own level.
+ *
+ * @class Graphql
+ * @extends {BaseModule}
+ */
+class Graphql extends BaseModule {
+  /**
+   * Creates an instance of Graphql.
+   *
+   * @param {object} [henri=null] A henri instance
+   * @memberof Graphql
+   */
+  constructor(henri = null) {
+    super();
+
+    this.reloadable = true;
+    this.needs = ['config'];
+    this.runlevel = 1;
+    this.name = 'graphql';
+    this.henri = henri;
+
+    this.typesList = [];
+    this.resolversList = [];
+
+    this.types = null;
+    this.resolvers = null;
+    this.schema = null;
+    this.endpoint = '/_henri/gql';
+    /** Normalized `config.graphql`: the endpoint, the limits, the access rules */
+    this.settings = graphqlConfig(null, this.endpoint);
+    this.active = false;
+
+    this.graphqlServer = null;
+    this.ready = null;
+
+    this._handler = null;
+    this._middlewareRegistered = false;
+
+    this.init = this.init.bind(this);
+    this.extract = this.extract.bind(this);
+    this.merge = this.merge.bind(this);
+    this.run = this.run.bind(this);
+    this.reload = this.reload.bind(this);
+    this.createServer = this.createServer.bind(this);
+
+    this.GraphQLError = GraphQLError;
+    this.ApolloError = GraphQLError;
+    this.toApolloError = (error, code = 'INTERNAL_SERVER_ERROR') =>
+      error instanceof GraphQLError
+        ? error
+        : new GraphQLError(error.message, {
+            extensions: { code },
+            originalError: error,
+          });
+    this.SyntaxError = SyntaxError;
+    this.ValidationError = ValidationError;
+    this.AuthenticationError = AuthenticationError;
+    this.ForbiddenError = ForbiddenError;
+    this.UserInputError = UserInputError;
+  }
+
+  /**
+   * Module initialization
+   * Called after being loaded by Modules
+   *
+   * @async
+   * @returns {!string} The name of the module
+   * @memberof Graphql
+   */
+  async init() {
+    const { config } = this.henri;
+
+    this.settings = graphqlConfig(
+      config.has('graphql') ? config.get('graphql') : null,
+      this.endpoint
+    );
+    this.endpoint = this.settings.endpoint;
+
+    if (this.schema !== null && !this.graphqlServer) {
+      await this.createServer();
+    }
+
+    if (!this.henri.isProduction && this.active) {
+      this.henri.pen.info('graphql', 'endpoint', this.endpoint);
+    }
+
+    return this.name;
+  }
+
+  /**
+   * Create (and start) the Apollo server for the current schema
+   * The express middleware is registered once and always delegates to the
+   * latest server instance, so reloads do not stack handlers.
+   *
+   * @returns {Promise<void>} resolves once the server has started
+   * @memberof Graphql
+   */
+  createServer() {
+    const { introspection, maxTokens } = this.settings;
+    const server = new ApolloServer({
+      // Apollo's own simple-request protection: a POST must be
+      // `application/json` or carry `apollo-require-preflight`, so a form on
+      // another site cannot reach the endpoint. On by default; named here so
+      // it stays that way.
+      csrfPrevention: true,
+      introspection:
+        introspection === null ? !this.henri.isProduction : introspection,
+      parseOptions: Number.isFinite(maxTokens) ? { maxTokens } : {},
+      plugins: [cancellation()],
+      schema: this.schema,
+      validationRules: [queryLimits(this.settings)],
+    });
+
+    this.graphqlServer = server;
+    this.ready = server
+      .start()
+      .then(() => {
+        this._handler = expressMiddleware(server, {
+          context: async ({ req, res }) => ({ req, res }),
+        });
+        debug('apollo server started');
+      })
+      .catch((error) => {
+        this.henri.pen.error('graphql', 'unable to start apollo server');
+        this.henri.pen.error('graphql', error);
+        this.active = false;
+      });
+
+    if (!this._middlewareRegistered) {
+      this._middlewareRegistered = true;
+      this.henri.addMiddleware('graphql', (app) => {
+        const guards = [];
+
+        if (this.settings.loopbackOnly) {
+          guards.push(loopbackOnly(this.henri));
+        }
+
+        guards.push(accessGuard(this.settings));
+
+        app.use(this.endpoint, ...guards, (req, res, next) => {
+          if (!this.active || !this._handler) {
+            return next();
+          }
+
+          return this._handler(req, res, next);
+        });
+      });
+    }
+
+    return this.ready;
+  }
+
+  /**
+   * Extract graphql items from a model (if any)
+   *
+   * @param {object} model a model
+   * @returns {boolean} status
+   * @memberof Graphql
+   */
+  extract(model) {
+    if (typeof model.graphql === 'undefined') {
+      return false;
+    }
+
+    const { types = null, resolvers = {} } = model.graphql;
+
+    if (typeof types === 'string') {
+      this.typesList.push(types);
+    }
+
+    if (typeof resolvers === 'object') {
+      this.resolversList.push(resolvers);
+    }
+
+    return true;
+  }
+
+  /**
+   * Merge the graphql types and resolver
+   * After extracting from all the models, we merge and compile them
+   *
+   * @return {boolean} success?
+   * @memberof Graphql
+   */
+  merge() {
+    let should = false;
+
+    if (this.typesList.length > 0) {
+      should = true;
+      this.types = mergeTypeDefs(this.typesList);
+    }
+
+    if (this.resolversList.length > 0) {
+      should = true;
+      this.resolvers = mergeResolvers(this.resolversList);
+    }
+
+    if (should) {
+      this.active = true;
+      try {
+        this.schema = makeExecutableSchema({
+          resolvers: this.resolvers || {},
+          typeDefs: this.types,
+        });
+        this.henri.pen.info('graphql', 'schema', 'valid');
+        this.createServer();
+      } catch (error) {
+        this.henri.pen.error('graphql', error);
+        this.henri.pen.error(
+          'graphql',
+          `THE GRAPHQL SERVICE WON'T BE AVAILABLE`
+        );
+        this.henri.pen.error('graphql', `UNTIL YOU FIX THIS ERROR`);
+        this.active = false;
+      }
+    } else {
+      this.active = false;
+
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Run a Graphql query against compiled graphql
+   *
+   * @async
+   * @param {Graphql} [query=`{ No query }`]  the graphql query
+   * @param {object} [variables] query variables
+   * @param {object} [contextValue={}] the resolvers' context (ex: { req, res })
+   * @returns {(Promise<{data: object, errors: Array}> | "No graphql schema found.")} value
+   * @memberof Graphql
+   */
+  async run(query = `{ No query }`, variables = undefined, contextValue = {}) {
+    if (!this.schema || !this.graphqlServer) {
+      return 'No graphql schema found.';
+    }
+
+    await this.ready;
+
+    const response = await this.graphqlServer.executeOperation(
+      {
+        query,
+        variables,
+      },
+      { contextValue: contextValue || {} }
+    );
+
+    if (response.body.kind === 'single') {
+      const { data, errors } = response.body.singleResult;
+
+      return { data, errors };
+    }
+
+    return {
+      data: null,
+      errors: [new GraphQLError('incremental delivery is not supported')],
+    };
+  }
+
+  /**
+   * Reloads the module
+   * State is cleared synchronously; the previous Apollo server is stopped in
+   * the background.
+   *
+   * @async
+   * @returns {string} Module name
+   * @memberof Graphql
+   */
+  async reload() {
+    const previous = this.graphqlServer;
+
+    this.typesList = [];
+    this.resolversList = [];
+
+    this.active = false;
+    this.types = null;
+    this.resolvers = null;
+    this.schema = null;
+    this.graphqlServer = null;
+    this.ready = null;
+    this._handler = null;
+
+    if (previous) {
+      try {
+        await previous.stop();
+      } catch (error) {
+        // The previous server is gone either way; the new one is what matters
+        this.henri.pen.warn(
+          'graphql',
+          'unable to stop the previous apollo server',
+          error.message
+        );
+        debug('error while stopping previous apollo server %O', error);
+      }
+    }
+
+    return this.name;
+  }
+
+  /**
+   * Stops the module
+   *
+   * @async
+   * @returns {(string|boolean)} Module name or false
+   * @memberof Graphql
+   */
+  async stop() {
+    if (this.graphqlServer) {
+      const server = this.graphqlServer;
+
+      this.graphqlServer = null;
+      this._handler = null;
+      this.ready = null;
+
+      await server.stop();
+
+      return this.name;
+    }
+
+    return false;
+  }
+}
+
+module.exports = Graphql;

package/src/loopback.js

@@ -0,0 +1,32 @@
+/**
+ * The `loopbackOnly: true` option of `config.graphql`.
+ *
+ * Core has one of these in `base/http.js`, but this package reaches into
+ * core for exactly one thing -- `BaseModule`, which the module system
+ * documents -- and that is worth keeping to one. The predicate itself is not
+ * copied: `isLoopback` is public API on the instance
+ * (`henri.utils.isLoopback`, see the API reference), so `::1`,
+ * `::ffff:127.0.0.1` and the whole `127.0.0.0/8` block are handled by core's
+ * definition and cannot drift from it.
+ *
+ * Core's version content-negotiates its 404. A GraphQL endpoint answers JSON
+ * either way, so this one always does.
+ *
+ * @param {object} henri A henri instance
+ * @returns {function} express middleware
+ */
+const loopbackOnly = (henri) => (req, res, next) => {
+  const address = req.socket && req.socket.remoteAddress;
+
+  if (henri.utils.isLoopback(address)) {
+    return next();
+  }
+
+  return res.status(404).json({
+    error: 'Not Found',
+    message: 'Not Found',
+    statusCode: 404,
+  });
+};
+
+module.exports = { loopbackOnly };