@nxgt/janus-graphql 0.1.0

package/docs/guide/directives.md

@@ -0,0 +1,312 @@
+# Directives
+
+This page is for guarding a schema: `@authenticated`, which asks who the user
+is, and `@permission`, which asks what the user may do to one object. Both
+are declared in `janusTypeDefs`, applied by `useJanus()` when the server
+builds its schema, and checked before the resolver runs — a refused request
+never reaches it.
+
+```ts
+import { janusMaskError, janusTypeDefs, useJanus } from '@nxgt/janus-graphql';
+import { createSchema, createYoga } from 'graphql-yoga';
+
+export const yoga = createYoga({
+	schema: createSchema({ typeDefs: [janusTypeDefs, typeDefs], resolvers }),
+	plugins: [
+		useJanus({
+			auth,
+			access,
+			loaders: { record: (id) => records.find(id) }, // what @permission loads by id
+			conditions: { record: (record, ctx: Context) => ({ onShift: ctx.shift.open }) }, // a when()'s ctx
+		}),
+	],
+	maskedErrors: { maskError: janusMaskError() },
+});
+```
+
+## Where a directive applies
+
+Both directives go on a field, an object type or an interface:
+
+| Written on | Guards |
+| --- | --- |
+| a field | that field |
+| an object type | every field of that type |
+| an interface | every field of every object type implementing it |
+| an interface's field | the field of the same name on every object type implementing it |
+
+GraphQL runs resolvers on object types only, so a directive on an interface
+is applied to each type implementing it, when the schema is built: nothing
+an interface declares is left unguarded, and a type added later that
+implements it is guarded too.
+
+**Every directive that applies must hold** — the field's, its type's, its
+interfaces'. A type's directive guards the type's fields, **not the field that
+returns it**: `Query.ward` below runs for an anonymous request, and the
+refusal lands on `ward.name`. Guard the field too when the lookup itself must
+not run.
+
+## `@authenticated(type: [String!])`
+
+```graphql
+type Query {
+	me: User @authenticated                      # any signed-in user
+	roster: [Staff!]! @authenticated(type: ["staff"])
+	ward(id: ID!): Ward
+}
+
+type Ward @authenticated(type: ["staff"]) {    # every field of Ward
+	name: String
+	chart: String @authenticated(type: ["staff", "patient"])
+}
+
+interface Audited {
+	trail: String @authenticated(type: ["staff"]) # trail, on every type implementing Audited
+}
+```
+
+On `Ward.chart` above, the type's `["staff"]` and the field's
+`["staff", "patient"]` both apply: only staff pass.
+
+| The request | Answered |
+| --- | --- |
+| anonymous | `UNAUTHENTICATED`, 401 |
+| a user of a type no `type:` names | `FORBIDDEN`, 403 |
+| a store that cannot answer | `SERVICE_UNAVAILABLE`, 503 |
+| a user every directive admits | the resolver runs |
+
+Under `useJanus({ type: 'staff' })`, the only user type a directive may name
+is `'staff'`.
+
+## `@permission(name, type, id, onDeny)`
+
+```graphql
+directive @permission(
+	name: String!
+	type: String!
+	id: String
+	onDeny: JanusPermissionDenial! = NOT_FOUND
+) repeatable on OBJECT | INTERFACE | FIELD_DEFINITION
+```
+
+Only a user holding permission `name` on the object of `type` whose id `id`
+reads reaches the field. It is `@nxgt/janus-hono`'s
+`permission(access, permission, type, load)` for a schema, and asks
+`access.can` — the `permissions()` instance given to `useJanus()`.
+
+| Argument | What it is |
+| --- | --- |
+| `name` | A relation or a permission `type` declares in the model — what `access.can` may be asked |
+| `type` | An object type of the model |
+| `id` | Where the object's id is read: `args.<path>` or `parent.<path>`. Absent: `args.id` on a field, `parent.id` on a type or an interface |
+| `onDeny` | What a denial answers: `NOT_FOUND`, 404, by default, or `FORBIDDEN`, 403 |
+
+`@permission` implies `@authenticated`: an anonymous request is answered
+`UNAUTHENTICATED`, 401, before any object is loaded or any check asked.
+
+### Reading the id
+
+```graphql
+type Query {
+	record(id: ID!): Record @permission(name: "view", type: "record")         # args.id
+	transfer(input: TransferInput!): Transfer
+		@permission(name: "manage", type: "ward", id: "args.input.wardId") # a path into an input
+}
+
+type Record @permission(name: "view", type: "record") {                    # parent.id: the record itself
+	title: String
+}
+
+type Visit {
+	notes: String @permission(name: "enter", type: "ward", id: "parent.wardId") # another object, by id
+}
+```
+
+A path is `args` or `parent` followed by one or more names, each read from the
+value before it. Where a step reads a list, the path goes on through every
+element.
+
+What `access.can` is given depends on where the id was read:
+
+| The id | The object `access.can` is given |
+| --- | --- |
+| `parent.id`, or `parent.<path>.id` | **The value that holds it** — the parent, or the value the path reached — with `type` added, read through a proxy: a getter, a class's `#private` state or an ORM document's accessors answer as they do in the resolver |
+| any other `parent.<path>`, or `args.<path>`, on a type with no `fromField` | `{ type, id }` |
+| the same, on a type with a `fromField` | **What `loaders[type](id, ctx)` answers**, with `type` added — the `fromField`s read its fields. `null` is answered `NOT_FOUND` |
+
+A `fromField` relation is read from the object's own data — a record's
+`doctorId` — so the object must carry that field. The parent does when its
+resolver answered the record; an id alone does not, and the loader is what
+turns one into the object. A type with no `fromField` may have a loader too:
+it is then asked for every id `@permission` reads alone — from `args`, or
+from a parent field other than `id` — and its
+`null` answers `NOT_FOUND` for an object that does not exist.
+
+```ts
+useJanus({
+	auth,
+	access,
+	loaders: {
+		record: (id, ctx: Context) => records.find(id), // { id, doctorId, … } or null
+	},
+});
+```
+
+An id that holds `@`, `#`, a parenthesis, a NUL character or a lone
+surrogate, or is empty, names no object: it is answered `NOT_FOUND` without
+asking, and without calling the loader.
+
+### Lists
+
+```graphql
+type Query {
+	records(ids: [ID!]!): [Record!]! @permission(name: "view", type: "record", id: "args.ids")
+}
+
+type Team {
+	wards: [Ward!]!
+	summary: String @permission(name: "enter", type: "ward", id: "parent.wards.id")
+}
+```
+
+**A list requires the permission on every element**: one denial denies the
+field. The checks of a list are asked together. An empty list in `args` asks
+nothing, and the resolver runs: the client asked for nothing. An empty list
+in the parent is answered `NOT_FOUND`: the object's data names nothing to
+check, and its fields are not open to every user for it. This is not a
+filter: to answer only the items a user may see, ask `access.list()` for
+their ids and load those.
+
+### Conditions
+
+A permission whose rules reach a `when()` needs a `ctx`, as `access.can`
+does. `conditions` answers it, per object type, from the object checked and
+the request's context:
+
+```ts
+// model: record.permits.edit = [when('doctors', (ctx: { onShift: boolean }) => ctx.onShift)]
+useJanus({
+	auth,
+	access,
+	loaders: { record: (id) => records.find(id) },
+	conditions: {
+		record: async (record, ctx: Context) => ({ onShift: await shifts.isOpen(ctx) }),
+	},
+});
+```
+
+One entry per type covers every permission of it: it answers every
+condition any of them reaches, typed as the intersection of their `ctx`s.
+
+### Repeated, and in order
+
+```graphql
+type Query {
+	discharge(id: ID!): Discharge
+		@permission(name: "view", type: "record")
+		@permission(name: "discharge", type: "record", onDeny: FORBIDDEN)
+}
+```
+
+**Every one must hold** — an either-or belongs in the model, as a
+permission whose rules name both. They are asked **one at a time, in order**,
+and the first that denies answers: the ones after it are never asked.
+
+The order across locations is outermost first: the interfaces' directives,
+the type's, the interfaces' fields', then the field's own. So a type's
+`NOT_FOUND` answers before a field's `FORBIDDEN` could tell that the object
+exists.
+
+### `NOT_FOUND` or `FORBIDDEN`
+
+`NOT_FOUND` is the default, because a `FORBIDDEN` says *this exists, and not
+for you*: for `record(id: "r42")` that is already an answer to a question the
+user may not ask. Choose `onDeny: FORBIDDEN` where the object is known to
+exist anyway — a field of an object the user may already see:
+
+```graphql
+type Record @permission(name: "view", type: "record") {
+	title: String
+	billing: Billing @permission(name: "manage", type: "record", onDeny: FORBIDDEN)
+}
+```
+
+| The request | Answered |
+| --- | --- |
+| anonymous | `UNAUTHENTICATED`, 401 |
+| a user of a type `@authenticated` does not name | `FORBIDDEN`, 403, before any check |
+| no id at the path, an empty list in the parent, or an id no object can hold | `NOT_FOUND`, 404 |
+| a loader answering `null` | `NOT_FOUND`, 404 |
+| a denial | `onDeny`: `NOT_FOUND`, 404, or `FORBIDDEN`, 403 |
+| a store — or a loader — that cannot answer | `SERVICE_UNAVAILABLE`, 503, never a denial |
+| every permission held | the resolver runs |
+
+A path that reads nothing — an optional argument left out, a `null` field of
+the parent — is answered `NOT_FOUND`, and said once per directive through
+`process.emitWarning`: `@permission on Query.record resolved no object id
+from args.id — answered NOT_FOUND`.
+
+### One check per question, per request
+
+The same question asked twice in one request is asked once: two fields —
+aliased or not — a directive and a resolver's `can()`, or two fields resolved
+at once, which share the one pending answer. The question is the notation
+`record:r1#view@staff:u1`: object, permission and subject. Across requests
+nothing is kept.
+
+Not remembered: a check with a condition's `ctx`, which the question does
+not hold; an anonymous one, which costs no store call; and a failure — the
+next question asks again.
+
+**A subscription's directives skip the memo.** It is one request whose
+fields resolve again on every event, so each event's `@permission` asks
+afresh and a `revoke()` made since the subscription started stops the next
+event. `can(ctx, …)` called in a subscription's resolver still reads the
+memo: call `ctx.janus.access.can` there. **A mutation does not**: a
+mutation that grants or revokes and then asks the same question in the same
+request reads the answer remembered before the change. Ask
+`access.can` directly after such a change, or answer from the mutation's own
+result.
+
+## Refused when the schema is built
+
+What no request could ever pass is a `TypeError` at start-up, naming the
+field, and the location the directive was written on when it is not the
+field — `(read by Ward.name)`:
+
+```
+TypeError: applyJanusDirectives(): @authenticated on Query.me names the user type 'doctor', which is not one of 'patient', 'staff'
+TypeError: applyJanusDirectives(): @authenticated on Query.me names no user type — leave type: out to admit any signed-in user
+TypeError: applyJanusDirectives(): the @authenticated on Ward.chart and on its type or interfaces admit no user type in common
+TypeError: applyJanusDirectives(): @permission on Query.ward needs the permissions() instance — pass useJanus({ auth, access }), with access what permissions() answered
+TypeError: applyJanusDirectives(): @permission on Query.invoice names the object type 'invoice', which is not one of 'record', 'ward'
+TypeError: applyJanusDirectives(): @permission on Query.ward asks 'delete', which ward does not declare — it declares 'nurses', 'visitors', 'enter', 'manage'
+TypeError: applyJanusDirectives(): @permission on Query.ward reads its id from 'ward.id', which is not args.<name> or parent.<name>
+TypeError: applyJanusDirectives(): @permission on Query.ward reads args.wardId, and Query.ward takes no argument wardId
+TypeError: applyJanusDirectives(): @permission on Query.record reads the record's id from args.id, and record reads 'doctorId' of the object itself (fromField) — pass useJanus({ loaders: { record: (id, ctx) => … } })
+TypeError: applyJanusDirectives(): @permission on Query.record asks 'edit' of record, which reaches a when() — pass useJanus({ conditions: { record: (object, ctx) => … } })
+TypeError: applyJanusDirectives(): @permission on Query.ward finds loaders.ward, which is not a function
+```
+
+Each is in [troubleshooting](../troubleshooting.md), with its fix. The
+compiler refuses the wiring's own mistakes before that: a loader for a type
+the model does not declare, a loader answering an object without a field a
+`fromField` reads, a condition for a type no `when()` is reached on, a `ctx`
+of the wrong shape, and `loaders` or `conditions` without `access`.
+
+## The transform alone
+
+`applyJanusDirectives(schema, { auth, type?, access?, loaders?, conditions? })`
+is what `useJanus()` runs on every schema. Call it to check a schema at build
+time — in a test, or in a script that fails a deploy — without starting a
+server:
+
+```ts
+import { applyJanusDirectives } from '@nxgt/janus-graphql';
+
+applyJanusDirectives(schema, { auth, access, loaders, conditions }); // throws the TypeErrors above
+```
+
+The guards it installs read `ctx.janus`, which only `useJanus()` builds: a
+guarded field resolved under any other context throws
+`TypeError: @permission on Query.ward: ctx.janus is not set — add useJanus({ auth }) to the plugins`.

package/docs/guide/errors.md

@@ -0,0 +1,138 @@
+# Errors
+
+This page is for what a client receives when a request is refused or a store
+is down, and how that becomes an HTTP status. When you have a message in
+hand and want its cause, see [troubleshooting](../troubleshooting.md).
+
+## No error class of its own
+
+This package throws `GraphQLError` for a denial, and lets `@nxgt/janus`'s own
+errors through. Every error it answers carries a `code` and a status in its
+`extensions`:
+
+```ts
+new GraphQLError('Not signed in', {
+	extensions: { code: 'UNAUTHENTICATED', http: { status: 401 } },
+});
+```
+
+Yoga reads `extensions.http.status` to answer the HTTP response, and strips
+`http` from the body, so the client sees:
+
+```json
+{
+	"data": { "me": null },
+	"errors": [{ "message": "Not signed in", "path": ["me"], "extensions": { "code": "UNAUTHENTICATED" } }]
+}
+```
+
+## The codes
+
+| Code | Status | Message | When |
+| --- | --- | --- | --- |
+| `UNAUTHENTICATED` | 401 | `Not signed in` | An anonymous request reached a field `@authenticated` guards, or `requireUser()` |
+| `FORBIDDEN` | 403 | `Forbidden` | A user of a type the directive or `requireUser({ type })` does not name, or a `@permission(onDeny: FORBIDDEN)` denied |
+| `NOT_FOUND` | 404 | `Not found` | `@permission`'s default denial, a loader answering `null`, an id `@permission` could not read — and `denial('NOT_FOUND')` |
+| `SERVICE_UNAVAILABLE` | 503 | `The service is unavailable, retry later` | A store could not answer: `STORE_FAILED` |
+| any other `JanusErrorCode` | its `statusOf(code)` | fixed per status: `Invalid request` 400, `Invalid credentials` 401 (`CREDENTIALS_INVALID`, `CODE_INVALID`), `Forbidden` 403, `Not found` 404, `Conflict` 409, `Internal server error` 500 and 501 | A `JanusError` a resolver let through — `CREDENTIALS_INVALID` 401, `LOGIN_TAKEN` 409, `TOKEN_EXPIRED` 400, … |
+
+The status of every `JanusErrorCode` is `@nxgt/janus`'s
+[`statusOf`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/errors.md),
+the table `@nxgt/janus-hono` answers with too.
+
+What a refusal carries beyond `code` is only what the client can act on:
+`issues` for `USER_INVALID`, `minLength` for `PASSWORD_TOO_SHORT`,
+`attemptsLeft` for `CODE_INVALID`. **Never** `reason`, `login`, `slot`,
+`operation`, a hash prefix or a cause — those are for your logs. **The
+message is never the core's**: `@nxgt/janus`'s messages name a hash prefix or
+a record's versions, so every `JanusError` gets the fixed message of its
+status, and a client tells refusals apart by `code`.
+
+## An outage is never a denial
+
+**An absence is `null`; a failure throws** — and here a failure is never
+answered `UNAUTHENTICATED`, `FORBIDDEN` or `NOT_FOUND`. A 401 during an
+outage tells every user they are signed out; a 403 tells them they lost their
+rights; a 404 tells them the record is gone. All send them somewhere a retry
+would not.
+
+| Where the store fails | Answered |
+| --- | --- |
+| a field `@authenticated` or `@permission` guards | `SERVICE_UNAVAILABLE`, 503 — with or without `janusMaskError()` |
+| a `loaders` entry throwing `StoreFailure` — or any `JanusError` — for `@permission` | the `JanusError`'s status: `SERVICE_UNAVAILABLE`, 503, for `STORE_FAILED` — with or without `janusMaskError()` |
+| `requireUser(ctx)`, `can(ctx, …)` | `SERVICE_UNAVAILABLE`, 503 — with or without `janusMaskError()` |
+| `ctx.janus.user()` read in a resolver, any `auth.*` or `access.*` call | `SERVICE_UNAVAILABLE`, 503 with `janusMaskError()`; Yoga's masked 500 without it |
+
+## `janusMaskError(fallback?)`
+
+Yoga masks every error that is not a `GraphQLError` into `Unexpected error.`
+with a 500. That is right for a bug and wrong for a `JanusError`: a wrong
+password is a 401 the client must see, and an outage a 503 it must retry.
+
+```ts
+import { janusMaskError } from '@nxgt/janus-graphql';
+import { createYoga, maskError } from 'graphql-yoga';
+
+createYoga({
+	schema,
+	plugins: [useJanus({ auth })],
+	maskedErrors: { maskError: janusMaskError(maskError) },
+});
+```
+
+A `JanusError` — thrown by a resolver, or wrapped by graphql-js with its path —
+is answered as the table above says, at the path it was thrown from. Anything
+else goes to `fallback`.
+
+Without a `fallback`, a `GraphQLError` of your own is kept as it is, and
+anything else becomes the mask's message with the code
+`INTERNAL_SERVER_ERROR` and no detail. Pass Yoga's own `maskError`, as above,
+to keep what it shows in development. The signature is envelop's too, so the
+same function fits `useMaskedErrors({ maskError })`.
+
+`janusGraphQLError(error)` is the conversion alone, for a resolver that
+catches a `JanusError` to answer it itself:
+
+```ts
+import { janusGraphQLError } from '@nxgt/janus-graphql';
+import { JanusError } from '@nxgt/janus';
+
+try {
+	return await auth.patient.signIn(input);
+} catch (error) {
+	if (error instanceof JanusError) throw janusGraphQLError(error); // CREDENTIALS_INVALID → 401
+	throw error;
+}
+```
+
+## The status of a response
+
+Yoga answers **the highest status among the errors**. A query whose fields
+are refused for different reasons is answered with the worst of them, and a
+query where one field is refused and the others answered is still that
+field's status:
+
+| The query, anonymous | Status | `data` |
+| --- | --- | --- |
+| `{ open }` | 200 | `{ open }` |
+| `{ me }` | 401 | `{ me: null }` |
+| `{ open me }` | 401 | `{ open, me: null }` |
+
+A client reads `data` and `errors`, not only the status.
+
+## Your own denials
+
+`denial(code, message?)` is the `GraphQLError` the guards throw, for a
+resolver that refuses on its own terms:
+
+```ts
+import { denial } from '@nxgt/janus-graphql';
+
+if (record.archived) throw denial('NOT_FOUND', 'No such record');
+```
+
+| `code` | Status |
+| --- | --- |
+| `UNAUTHENTICATED` | 401 |
+| `FORBIDDEN` | 403 |
+| `NOT_FOUND` | 404 |

package/docs/guide/federation.md

@@ -0,0 +1,70 @@
+# Federation
+
+This page is for a subgraph of a federated graph: where the directives are
+checked, how the router must forward the request, and how to keep them in
+the supergraph with `@composeDirective`.
+
+## Checked in the subgraph
+
+`useJanus()` guards the schema of the server it is plugged into. In a
+federated graph that is the subgraph: each subgraph that serves a guarded
+field runs its own `useJanus({ auth, access })`, and checks the directive
+when the router asks it for the field. Nothing is checked by the router.
+
+So **the router must forward what `authenticate` reads**: the
+`Authorization` header, `X-Session-Token`, or the session cookie. A router
+that forwards none of them turns every signed-in user into an anonymous one,
+answered `UNAUTHENTICATED` by the subgraph. Configure header propagation in
+the router for the subgraphs that use this package.
+
+An entity's fields are guarded as any object type's: a type-level
+`@permission` reads `parent.id`, and the parent is what your
+`__resolveReference` answered, so it carries the fields its `fromField`s
+read when your reference resolver loads them.
+
+```graphql
+type Record @key(fields: "id") @permission(name: "view", type: "record") {
+	id: ID!
+	title: String
+}
+```
+
+## The shipped SDL
+
+The directives and the `JanusPermissionDenial` enum ship twice, as the same text:
+`janusTypeDefs`, and `graphql/janus.graphqls` in the package —
+`node_modules/@nxgt/janus-graphql/graphql/janus.graphqls`. Composition
+requires a directive to be declared identically in every subgraph that
+composes it, and reading it from the package, rather than copying it, keeps
+every subgraph on the definition of the version it installed.
+
+A subgraph built with `@apollo/subgraph` or `@graphql-tools/federation`
+takes `janusTypeDefs` among its type definitions, like any server; a
+schema-first toolchain reads the file.
+
+## Keeping the directives in the supergraph
+
+Composition drops a subgraph's own directives from the supergraph unless
+they are composed. The checks do not need them there — they run in the
+subgraph — but a client generator or a schema registry reading the
+supergraph does, to show which fields are guarded. Link them under a
+specification URL of your own and compose them:
+
+```graphql
+extend schema
+	@link(url: "https://specs.apollo.dev/federation/v2.1", import: ["@key", "@composeDirective"])
+	@link(url: "https://example.com/janus/v1.0", import: ["@authenticated", "@permission"])
+	@composeDirective(name: "@authenticated")
+	@composeDirective(name: "@permission")
+```
+
+Every subgraph that composes a directive must declare it identically, which
+the shipped SDL does, and link it under the same URL, with the same major
+version.
+
+**Do not import federation's own `@authenticated`.** Federation 2.5 declares
+a directive of that name, read by the router, and a subgraph that imports it
+from the federation `@link` while declaring `janusTypeDefs` has two
+definitions of one name. Import only what you use from the federation
+specification — `@key`, `@composeDirective` — and let this package's
+`@authenticated` be the one the subgraph checks.

package/docs/guide/telemetry.md

@@ -0,0 +1,45 @@
+# Telemetry
+
+This page is for tracing what the GraphQL server asks of `@nxgt/janus`: a span
+per authentication and per permission check, with
+[`@nxgt/janus-telemetry`](https://www.npmjs.com/package/@nxgt/janus-telemetry).
+
+`@nxgt/janus-graphql` does not depend on it, and has nothing to configure for
+it: `useJanus()` takes the instances you give it, and an instrumented
+instance answers exactly as the plain one does, with the same types.
+
+```ts
+import { janus } from '@nxgt/janus';
+import { permissions } from '@nxgt/janus/permissions';
+import { useJanus } from '@nxgt/janus-graphql';
+import { instrumentJanus, instrumentPermissions } from '@nxgt/janus-telemetry';
+
+export const auth = instrumentJanus(janus({ users, hasher, ...stores }));
+export const access = instrumentPermissions(permissions({ model, store }));
+
+useJanus({ auth, access, loaders, conditions });
+```
+
+`instrumentPermissions(access)` answers a frozen copy that keeps `model`, so
+`@permission` reads the model from it when the schema is built, and every
+check — a directive's or `can()`'s — goes through the traced `can`.
+
+## What shows up
+
+| Span | Written for |
+| --- | --- |
+| `janus.authenticate` | The first `ctx.janus.user()` or `ctx.janus.session()` of a request — a guarded field asks it — and never when neither is asked. Once per request |
+| `janus.can` | Each **distinct** permission check of a request: `@permission`'s and `can()`'s |
+
+The spans nest under the server span of whatever opened one — an
+OpenTelemetry instrumentation of your server, or `@nxgt/telemetry`'s own.
+
+**A question answered from the request's memo writes no span.** The memo sits
+between `ctx.janus` and `access.can`, so the same object, permission and user
+asked twice in one request — two fields, or a directive and `can()` — is one
+`janus.can`. A check with a condition's `ctx` is never remembered, and
+writes one span each time.
+
+**A loader is yours to trace.** `loaders[type](id, ctx)` runs your code; what
+it asks of your database shows up as your database's instrumentation writes
+it, not as a `janus.*` span.

package/docs/roadmap.md

@@ -0,0 +1,59 @@
+# Roadmap
+
+Where `@nxgt/janus-graphql` is heading. A direction, not a commitment: there
+are no dates here, and the version something shipped in is the only number.
+
+## Now
+
+Nothing between releases.
+
+## Next
+
+- **Subscriptions over graphql-ws** — `janusConnection`, which authenticates
+  a WebSocket connection once, from its `connectionParams` or its upgrade
+  request, and gives every operation on it the same `ctx.janus`.
+- **`@fresh(maxAge)`** — a field only a session signed in less than `maxAge`
+  ago may resolve: a password change, a new e-mail, a payment method, asked
+  again of a session that is days old.
+- **The renewed session cookie on GraphQL responses** — `authenticate`
+  renews a sliding session in passing; the response would then carry its
+  `Set-Cookie`, so a browser keeps the new expiry without an HTTP route of
+  its own.
+
+## Later
+
+Nothing yet.
+
+## Not planned
+
+- **Filtering a list by permission** — no directive drops the items of a list
+  the user may not see. Loading every item and checking each is a query that
+  grows with the table; ask the question the other way round with
+  `access.list()`, which answers the ids the user holds a permission on, and
+  load only those.
+- **Introspection control and rate limiting** — neither is about who the user
+  is. Envelop and Yoga have plugins for both; this package stays out of their
+  way.
+- **Error classes of its own** — a denial is a `GraphQLError`, and anything
+  else is `@nxgt/janus`'s, which is why `@nxgt/janus` is a required peer and
+  never a dependency.
+- **`moduleResolution: "nodenext"`** — like `@nxgt/janus`, the package
+  imports without extensions. Use `"moduleResolution": "bundler"`.
+
+## Shipped
+
+Newest first; from the first release on, the package's CHANGELOG holds every one.
+
+- **The first release, v0.1.0.** GraphQL for `@nxgt/janus`, as an envelop
+  plugin: `useJanus()` with a lazy `ctx.janus`, authenticated only when a
+  field asks; `@authenticated` on fields, types and interfaces, for any user
+  or some user types; `@permission(name, type, id, onDeny)`, reading the id
+  from `args.<path>` or `parent.<path>`, loading an object by id through
+  `loaders` and a condition's `ctx` through `conditions`, one check per
+  question per request, and a denial answered `NOT_FOUND` unless
+  `onDeny: FORBIDDEN`; `requireUser()` and `can()` for a resolver;
+  `janusMaskError()`, an outage as 503; and the SDL as `janusTypeDefs` and
+  `graphql/janus.graphqls`. What no request could pass is refused at
+  start-up, naming the field. The specs and the typecheck also run on the
+  peer floors — `graphql` 16.9.0, `@graphql-tools/utils` 10.0.0 and
+  `@envelop/core` 5.0.0 — in CI.