@nxgt/janus-graphql 0.2.0 → 0.4.0

package/docs/guide/errors.md

@@ -64,7 +64,7 @@ would not.
 | `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?)`
+## `janusMaskError({ report?, 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
@@ -77,7 +77,7 @@ import { createYoga, maskError } from 'graphql-yoga';
 createYoga({
 	schema,
 	plugins: [useJanus({ auth })],
-	maskedErrors: { maskError: janusMaskError(maskError) },
+	maskedErrors: { maskError: janusMaskError({ fallback: maskError }) },
 });
 ```
 
@@ -88,8 +88,51 @@ 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 })`.
+to keep what it shows in development — as `{ fallback }`, or alone:
+`janusMaskError(maskError)`, the form from before `report`, still works. The
+signature is envelop's too, so the same function fits
+`useMaskedErrors({ maskError })`.
+
+## Every outage in your logs: `report`
+
+The client reads a fixed message, and nothing of the store's: which store
+failed, and why, is for your logs. A directive — `@authenticated`, `@fresh`,
+`@permission` — and `requireUser()`, `requireFresh()` and `can()` answer an
+outage 503 themselves, before any resolver of yours runs, so there is no
+`try` of yours to log it in. `report` is where it goes:
+
+```ts
+createYoga({
+	schema,
+	plugins: [useJanus({ auth, access })],
+	maskedErrors: {
+		maskError: janusMaskError({
+			report: (error) => logger.error({ code: error.code, cause: error.cause }, error.message),
+			fallback: maskError,
+		}),
+	},
+});
+```
+
+- **Every 5xx, whichever path it took**: `STORE_FAILED`, `UNSUPPORTED`,
+  `PERMISSION_DEPTH` — from a directive, a helper, a loader, or a resolver
+  that let it through. `report` is given `@nxgt/janus`'s own error: a
+  `StoreFailure` carries the `slot` and `operation` of the call that failed,
+  its message and its `cause`.
+- **Once per failure.** The user is authenticated once per request, so an
+  outage that fails three guarded fields is one error, reported once — and
+  answered three times.
+- **Never a 4xx**: a denial, `CREDENTIALS_INVALID`, `STEP_UP_REQUIRED` are the
+  client's to fix, not yours.
+- **It cannot change the answer.** A `report` that throws, or rejects, is a
+  `process.emitWarning` naming the code, and the 503 is sent all the same.
+  What it answers is ignored.
+
+Yoga's own logger does not cover this: it logs an error only when the mask
+replaced it, and a directive's refusal reaches the mask already a
+`GraphQLError`, kept as it is — so it is never logged. The same `report` is
+`janusErrors({ report })` in `@nxgt/janus-hono`, for the HTTP routes beside
+the GraphQL server.
 
 `janusGraphQLError(error)` is the conversion alone, for a resolver that
 catches a `JanusError` to answer it itself:
@@ -106,6 +149,27 @@ try {
 }
 ```
 
+**Rate-limit a sign-in mutation per login and per client: `@nxgt/janus`
+counts no failed password**, so without a limit anyone can guess as fast as
+the server hashes. A sign-in code, a second factor and a step-up count their
+guesses; a password does not. Check the limit in the resolver, before
+`signIn`, with the limiter you already run:
+
+```ts
+import { GraphQLError } from 'graphql';
+
+if (!(await limiter.consume(`sign-in:${input.email.trim().toLowerCase()}`))) {
+	throw new GraphQLError('Too many attempts', {
+		extensions: { code: 'TOO_MANY_REQUESTS', http: { status: 429 } },
+	});
+}
+return await auth.patient.signIn(input);
+```
+
+Yoga answers the `http.status` of the extensions. Add a second limit per
+client address, and limit a `changePassword` mutation per user: it compares
+the current password too.
+
 ## The status of a response
 
 Yoga answers **the highest status among the errors**. A query whose fields

package/docs/guide/step-up.md

@@ -140,11 +140,15 @@ seconds.
 
 **A `@fresh` on the subscription field is checked when it subscribes.** A
 stale session is refused before the stream starts; a fresh one keeps
-receiving events past `maxAge`, as it keeps its session. `@authenticated`
-and `@permission` on the field are asked again on every event; its
-`@fresh` is not. To end a stream when the session is no longer fresh, close
+receiving events past `maxAge`, as it keeps its session. `@permission` on
+the field is asked again on every event; `@authenticated` reads the
+operation's one authentication, made when it subscribed; its `@fresh` is
+not asked again. To end a stream when the session is no longer fresh, close
 it from the server.
 
+Over a WebSocket, the same holds once `janusConnection()` authenticates
+the connection: [subscriptions over graphql-ws](subscriptions.md).
+
 **A `@fresh` on the payload's type, or on one of its fields, is checked on
 every event**, as any field is: those fields resolve anew for each event,
 and once the session is past `maxAge` they answer `STEP_UP_REQUIRED` while

package/docs/guide/subscriptions.md

@@ -0,0 +1,255 @@
+# Subscriptions over graphql-ws
+
+A subscription over server-sent events is an HTTP request like any other:
+`useJanus()` authenticates it from its headers, and nothing more is needed.
+Over a WebSocket, every operation travels over one socket, opened once:
+`janusConnection()` authenticates that socket, with
+[graphql-ws](https://github.com/enisdenjo/graphql-ws), the library Yoga
+recommends, so the directives hold on it unchanged.
+
+## Install
+
+`graphql-ws` is an **optional** peer: install it only when you serve
+subscriptions over a WebSocket.
+
+```sh
+bun add graphql-ws ws
+```
+
+Its range, `^6.0.0`, and the `graphql` 17 note are in the
+[README's Install](../../README.md#install).
+
+## Wiring, with Yoga
+
+This is Yoga's recommended graphql-ws setup, with one line added:
+`onConnect`.
+
+```ts
+import { createServer } from 'node:http';
+import { janusConnection, janusMaskError, janusTypeDefs, useJanus } from '@nxgt/janus-graphql';
+import { useServer } from 'graphql-ws/use/ws';
+import { createSchema, createYoga } from 'graphql-yoga';
+import { WebSocketServer } from 'ws';
+import { access } from './access'; // what permissions() answered
+import { auth } from './auth'; // what janus() answered
+
+const yoga = createYoga({
+	schema: createSchema({ typeDefs: [janusTypeDefs, typeDefs], resolvers }),
+	plugins: [useJanus({ auth, access })],
+	maskedErrors: { maskError: janusMaskError() },
+});
+
+const server = createServer(yoga);
+const wsServer = new WebSocketServer({ server, path: yoga.graphqlEndpoint });
+
+useServer(
+	{
+		onConnect: janusConnection({ auth }).onConnect, // refuses a connection with no valid session
+		execute: (args: any) => args.rootValue.execute(args),
+		subscribe: (args: any) => args.rootValue.subscribe(args),
+		onSubscribe: async (ctx, _id, params) => {
+			const { schema, execute, subscribe, contextFactory, parse, validate } = yoga.getEnveloped({
+				...ctx, // carries ctx.extra, where useJanus() finds the connection
+				req: ctx.extra.request,
+				socket: ctx.extra.socket,
+				params,
+			});
+			const args = {
+				schema,
+				operationName: params.operationName,
+				document: parse(params.query),
+				variableValues: params.variables,
+				contextValue: await contextFactory(),
+				rootValue: { execute, subscribe },
+			};
+			const errors = validate(args.schema, args.document);
+			if (errors.length) return errors;
+			return args;
+		},
+	},
+	wsServer,
+);
+
+server.listen(4000);
+```
+
+`useJanus()` needs nothing new. When it builds the context of an operation
+with no `request`, it looks for the connection the operation came from —
+by `ctx.extra`, which the `...ctx` spread carries — and authenticates the
+credential that connection presented. **Keep the spread**: a context built
+without `ctx.extra` has no connection to find, and its first guarded field
+throws [`the GraphQL context has no request to authenticate`](../troubleshooting.md#typeerror--the-graphql-context-has-no-request-to-authenticate).
+
+## How the session travels
+
+`onConnect` reads one credential per connection, in this order:
+
+1. **`connectionParams.authorization`** — for a client that is not a
+   browser, or a browser that holds a bearer token:
+
+   ```ts
+   import { createClient } from 'graphql-ws';
+
+   const client = createClient({
+   	url: 'wss://api.example.com/graphql',
+   	connectionParams: async () => ({ authorization: `Bearer ${await tokens.current()}` }),
+   });
+   ```
+
+   The key is `authorization`, lower-case, and its value a string — the
+   same `Bearer <token>` an HTTP request sends. A value that is not a
+   string refuses the connection; a string of another scheme (`Basic …`)
+   is not a session credential, as in `@nxgt/janus`, and the upgrade
+   request is read instead.
+
+2. **The upgrade request**, read as `auth.authenticate` reads any request:
+   `Authorization: Bearer`, then `X-Session-Token`, then the session
+   cookie. A browser sends its cookies with the upgrade, so a signed-in
+   browser needs no `connectionParams` at all — provided the WebSocket goes
+   to the origin that set the cookie, or to one its `SameSite` admits.
+
+**The first credential present wins, not the first valid one**, as in
+`@nxgt/janus`: a lapsed token in `connectionParams` beside a live cookie is
+refused, rather than rescued in silence. Fix the client's token.
+
+`type` restricts who may connect:
+
+```ts
+janusConnection({ auth, type: 'staff' }); // a patient's session is refused
+```
+
+## What a client sees
+
+| What happened | The client sees |
+| --- | --- |
+| No credential, an unknown or lapsed one, a user gone, inactive or of another `type`, an `authorization` that is not a string | The socket closed **`4403: Forbidden`**, before any operation — graphql-ws's own close for an `onConnect` that answers `false` |
+| The sessions store could not answer at connect | The socket closed **`4500`**, by `graphql-ws/use/ws`, which also logs the error — **never `4403`** |
+| Accepted | `connection_ack`, then operations as over HTTP |
+
+graphql-ws's client treats `4403` as retryable — a `connectionParams`
+function asked again can present a fresh token — and `4500` as fatal. Set
+`retryAttempts` and `shouldRetry` on the client to change that. (`4401` is
+the protocol's answer to an operation sent before the acknowledgement;
+`onConnect` cannot choose it.)
+
+## Each operation
+
+Each operation on an accepted connection gets **a `ctx.janus` of its own**,
+built by `useJanus()` as for an HTTP request, and authenticated again from
+the connection's credential the first time a field asks — once per
+operation, never per event:
+
+- `@authenticated` and `@fresh` on a subscription field are checked **when
+  it subscribes**. A denial answers the operation with its `GraphQLError` —
+  `UNAUTHENTICATED`, `FORBIDDEN`, `STEP_UP_REQUIRED` — and the source stream
+  never starts; the connection stays open.
+- `@permission` on a subscription field is asked **again on every event**,
+  bypassing the request's memo, so a `revoke()` stops the stream at its
+  next event with `NOT_FOUND` (or `FORBIDDEN`).
+- A directive on the payload's type or its fields is checked on every
+  event, as any field.
+- An outage at subscribe, or on an event, answers `SERVICE_UNAVAILABLE` —
+  never a denial.
+
+## A session revoked while connected
+
+`auth.signOut` or `signOutEverywhere` while a socket is open:
+
+- **the stream already running keeps its events coming.** Its user was
+  authenticated once, when it subscribed, and each event's
+  `@authenticated` reads that answer — authenticating on every event would
+  cost a sessions-store read per event per subscriber;
+- **the next operation on the same connection is refused**
+  `UNAUTHENTICATED`, since it authenticates again;
+- **a reconnection is refused `4403`**.
+
+To cut a revoked session's streams at once, close its sockets yourself.
+graphql-ws hands every callback the transport's socket as
+`ctx.extra.socket`: a server that keeps its open sockets by user can close
+them with `4403` when it revokes, and a client that reconnects is then
+refused.
+
+```ts
+const connection = janusConnection({ auth });
+
+useServer({
+	onConnect: async (ctx) => {
+		const accepted = await connection.onConnect(ctx);
+		if (accepted) track(ctx.extra.socket, ctx); // your own bookkeeping, keyed as you revoke
+		return accepted;
+	},
+	onClose: (ctx) => untrack(ctx.extra.socket),
+	// … Yoga's recipe …
+}, wsServer);
+```
+
+A permission revoked while connected needs none of this: `@permission` sees
+it at the next event.
+
+## Without Yoga
+
+A server that runs graphql-ws alone passes `context` as well, and applies
+the directives itself:
+
+```ts
+import { applyJanusDirectives, janusConnection } from '@nxgt/janus-graphql';
+import { useServer } from 'graphql-ws/use/ws';
+import { WebSocketServer } from 'ws';
+import { schema } from './schema'; // your executable schema, with janusTypeDefs
+
+const wsServer = new WebSocketServer({ port: 4000, path: '/graphql' });
+const connection = janusConnection({ auth, access, clock }); // clock: the one given to janus()
+
+useServer(
+	{
+		schema: applyJanusDirectives(schema, { auth, access }),
+		onConnect: connection.onConnect,
+		context: connection.context, // { janus } for each operation
+	},
+	wsServer,
+);
+```
+
+With Yoga, leave `context` out: Yoga's recipe builds the context itself,
+and `useJanus()`'s `access` and `clock` are the ones that apply.
+
+## On Bun, or another transport
+
+`onConnect` reads the upgrade request from `ctx.extra.request`, where
+`graphql-ws/use/ws` and `graphql-ws/use/@fastify/websocket` put it.
+`graphql-ws/use/bun`'s `extra` is `{ socket }` alone: pass the request as
+the socket's `data` when you upgrade, and tell `janusConnection` where it is.
+
+```ts
+import type { ServerWebSocket } from 'bun';
+import { makeHandler } from 'graphql-ws/use/bun';
+
+type Upgraded = ServerWebSocket<{ readonly request: Request }>;
+
+const connection = janusConnection({
+	auth,
+	upgrade: (ctx: { readonly extra: { readonly socket: Upgraded } }) => ctx.extra.socket.data.request,
+});
+
+Bun.serve({
+	fetch: (request, server) =>
+		server.upgrade(request, { data: { request } }) ? undefined : yoga.fetch(request, server),
+	websocket: makeHandler({ onConnect: connection.onConnect, /* … Yoga's recipe … */ }),
+});
+```
+
+Without `upgrade` on Bun, only `connectionParams` authenticates: a browser's
+cookie is never read.
+
+## What is not covered
+
+- **An anonymous connection.** `onConnect` refuses every connection it
+  cannot authenticate; serve anonymous clients over server-sent events. An
+  operation on a connection no `onConnect` accepted has no credential: its
+  first guarded field, or `ctx.janus.user()`, throws a `TypeError`, a 500.
+- **The renewed session cookie.** A WebSocket has no response to set one
+  on. An operation that renews the session renews it in the store, and the
+  browser's cookie keeps its old expiry until the next renewal over HTTP,
+  which `useJanus()` sends — a `renewAfter` later. A browser whose only
+  traffic is the WebSocket should renew through an HTTP route of yours:
+  [the context guide](context.md#ctxjanus) has the detail.

package/docs/roadmap.md

@@ -9,17 +9,16 @@ 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`.
-- **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.
+Nothing yet.
 
 ## Later
 
-Nothing yet.
+- **Anonymous graphql-ws connections** — `janusConnection({ anonymous:
+  true })`, accepting a connection with no credential so its public fields
+  answer and its guarded ones deny, as over HTTP.
+- **Re-authenticating a subscription on each event** — an opt-in for
+  streams that must end the moment their session is revoked, at the cost
+  of a sessions-store read per event.
 
 ## Not planned
 
@@ -41,6 +40,28 @@ Nothing yet.
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **The renewed session cookie, and `report` for every outage, v0.4.0.**
+  Under Yoga, `useJanus()` sends a session `authenticate` renewed back as
+  `Set-Cookie`, so a browser keeps the new expiry without an HTTP route of
+  its own — only to a request that presented the session cookie, never to a
+  bearer token or `X-Session-Token`, and never when nothing authenticated.
+  `janusMaskError({ report, fallback })` hands every `JanusError` answered
+  5xx to your logger, once, including the outages a directive or a helper
+  answers 503 on its own; a `report` that throws never changes the answer.
+  `janusMaskError(fallback)` still works.
+
+- **Subscriptions over graphql-ws, `janusConnection()`, v0.3.0.** The same
+  `@authenticated`, `@fresh` and `@permission` on subscriptions served over
+  a WebSocket with graphql-ws: `onConnect` for its `useServer()`
+  authenticates the connection from `connectionParams.authorization` — else
+  from the upgrade request's headers and the browser's session cookie —
+  and refuses it `4403`, or rejects on an outage, closed `4500`. Each
+  operation's `ctx.janus` is built by `useJanus()` from that credential, in
+  Yoga's recommended setup, and authenticated again when it subscribes, so
+  a session revoked since the connection opened is refused at the next
+  subscribe. `context` for a server without Yoga, `upgrade` for Bun.
+  `graphql-ws` is an optional peer, `^6.0.0`, whose floor runs in CI.
+
 - **`@fresh(maxAge)` and `requireFresh()`, v0.2.0.** A field, a type or an
   interface only a session that proved who it is less than `maxAge` seconds
   ago may resolve — signed in, or confirmed since by `auth.stepUp.confirm`:

package/docs/troubleshooting.md

@@ -30,6 +30,14 @@ for what causes each.
 - [`TypeError: useJanus(): auth is not what janus() answered`](#typeerror-usejanus-auth-is-not-what-janus-answered)
 - [`TypeError: useJanus(): access is not what permissions() answered`](#typeerror-usejanus-access-is-not-what-permissions-answered)
 - [`TypeError: useJanus(): clock is not a Clock`](#typeerror-usejanus-clock-is-not-a-clock)
+- [`TypeError: janusConnection(): auth is not what janus() answered`, `access …`, `clock …`](#typeerror-janusconnection-auth-is-not-what-janus-answered-access--clock-)
+- [`TypeError: janusConnection(): upgrade is not a function`](#typeerror-janusconnection-upgrade-is-not-a-function)
+
+**Over graphql-ws**
+- [The socket closed `4403: Forbidden` right after connecting](#the-socket-closed-4403-forbidden-right-after-connecting)
+- [The socket closed `4500`](#the-socket-closed-4500)
+- [A stream keeps its events after its session was revoked](#a-stream-keeps-its-events-after-its-session-was-revoked)
+- [`TypeError: janusConnection(): the connection's extra is not an object`](#typeerror-janusconnection-the-connections-extra-is-not-an-object)
 
 **In a response**
 - [`UNAUTHENTICATED` for a signed-in user](#unauthenticated-for-a-signed-in-user)
@@ -39,7 +47,7 @@ for what causes each.
 - [`SERVICE_UNAVAILABLE`, 503, on every guarded field](#service_unavailable-503-on-every-guarded-field)
 - [`Unexpected error.`, 500, where a `JanusError` was thrown](#unexpected-error-500-where-a-januserror-was-thrown)
 - [`TypeError: … ctx.janus is not set`](#typeerror--ctxjanus-is-not-set)
-- [`TypeError: useJanus(): the GraphQL context has no request to authenticate`](#typeerror-usejanus-the-graphql-context-has-no-request-to-authenticate)
+- [`TypeError: …: the GraphQL context has no request to authenticate`](#typeerror--the-graphql-context-has-no-request-to-authenticate)
 - [`TypeError: can(): ctx.janus.access is not set`](#typeerror-can-ctxjanusaccess-is-not-set)
 - [`TypeError: requireUser(): type is an empty list, which no user could pass`](#typeerror-requireuser-type-is-an-empty-list-which-no-user-could-pass)
 - [`TypeError: requireFresh(): maxAge is a duration with its unit`](#typeerror-requirefresh-maxage-is-a-duration-with-its-unit)
@@ -51,6 +59,8 @@ for what causes each.
 - [`Unexpected error.`, 500, on a field `@permission` guards](#unexpected-error-500-on-a-field-permission-guards)
 - [`TypeError: @permission on …: ctx.janus.access is not set`](#typeerror-permission-on--ctxjanusaccess-is-not-set)
 - [`TypeError: @permission on …: loaders.… answered …`](#typeerror-permission-on--loaders-answered-)
+- [The session cookie expires while the user is active](#the-session-cookie-expires-while-the-user-is-active)
+- [`Warning: janusMaskError: report failed on …`](#warning-janusmaskerror-report-failed-on-)
 - [A 401 whose `data` still holds the other fields](#a-401-whose-data-still-holds-the-other-fields)
 
 **Types**
@@ -278,6 +288,74 @@ answered — or leave `access` out when no field uses `@permission` or `can()`.
 `@nxgt/janus` in a spec — or leave `clock` out for the system's:
 `useJanus({ auth, clock })`.
 
+### `TypeError: janusConnection(): auth is not what janus() answered`, `access …`, `clock …`
+
+**Why:** the same checks as `useJanus()`'s, named for `janusConnection()`:
+`auth` is not what `janus()` answered, `access` not what `permissions()`
+answered, `clock` not a `Clock`.
+
+**Fix:** `janusConnection({ auth })`, with the `access` and `clock` given to
+`useJanus()` when you pass them at all.
+
+### `TypeError: janusConnection(): upgrade is not a function`
+
+**Why:** `upgrade` is how `onConnect` finds the upgrade request on a
+transport whose `extra` does not carry it, and it was given something else.
+
+**Fix:** a function of graphql-ws's context, or nothing — `ctx.extra.request`
+is then read, as `graphql-ws/use/ws` sets it:
+
+```ts
+janusConnection({ auth, upgrade: (ctx: { readonly extra: { readonly socket: Upgraded } }) => ctx.extra.socket.data.request });
+```
+
+## Over graphql-ws
+
+### The socket closed `4403: Forbidden` right after connecting
+
+**Why:** `onConnect` found no credential that authenticates: none at all,
+an unknown or lapsed token, a user gone or inactive, a user of another
+type than `janusConnection({ type })`, or a `connectionParams.authorization`
+that is not a string. A `Bearer` `connectionParams.authorization` is
+read before the upgrade request, and **the first present wins**: a lapsed
+token there refuses the connection even beside a live cookie. One of
+another scheme (`Basic …`) does not count, and the cookie is read.
+
+**Fix:** send `connectionParams: { authorization: 'Bearer <token>' }` —
+the key lower-case — or connect from a browser holding the session cookie,
+to the origin that set it. On Bun, pass `upgrade`, or the cookie is never
+read. graphql-ws's client retries a `4403`; a `connectionParams` function
+is asked again each time.
+
+### The socket closed `4500`
+
+**Why:** the sessions store could not answer while `onConnect`
+authenticated — `STORE_FAILED`. `graphql-ws/use/ws` closes the socket
+`4500` and logs the error with `console.error`. It is an outage, **never a
+refusal**: `4403` would tell the client its session is bad.
+
+**Fix:** the store. graphql-ws's client does not retry a `4500` by default;
+set `shouldRetry` to retry an outage.
+
+### A stream keeps its events after its session was revoked
+
+**Why:** an operation is authenticated once, when it subscribes, and
+each event's `@authenticated` reads that answer. The next operation on
+the connection is refused `UNAUTHENTICATED`, and a reconnection `4403`.
+
+**Fix:** close the session's sockets when you revoke it
+([the subscriptions guide](guide/subscriptions.md#a-session-revoked-while-connected)).
+A permission revoked needs nothing: `@permission` asks again on every event.
+
+### `TypeError: janusConnection(): the connection's extra is not an object`
+
+**Why:** `onConnect` was called with a context whose `extra` is not an
+object — by hand, or by a transport of your own. It remembers the
+connection by that object.
+
+**Fix:** pass `onConnect` to graphql-ws's `useServer()` or `makeHandler()`,
+which give it the context they made.
+
 ## In a response
 
 ### `UNAUTHENTICATED` for a signed-in user
@@ -334,8 +412,16 @@ for `can()` and `@permission` — and a loader of yours that threw
 `StoreFailure`. It is never answered `UNAUTHENTICATED`, `FORBIDDEN` or `STEP_UP_REQUIRED`.
 
 **Fix:** the store: its connection, its credentials, its availability. The
-message carries nothing of the store's; log the error where you call
-`auth` — `@nxgt/janus`'s `slot` and `operation` name the call that failed.
+message carries nothing of the store's, and a directive or a helper answers
+the outage before any resolver of yours could catch it: pass `report` to
+the mask, which is given `@nxgt/janus`'s error — its `slot` and `operation`
+name the call that failed, its `cause` the driver's error:
+
+```ts
+maskedErrors: {
+	maskError: janusMaskError({ report: (error) => logger.error(error), fallback: maskError }),
+},
+```
 
 ### `Unexpected error.`, 500, where a `JanusError` was thrown
 
@@ -353,14 +439,21 @@ transformed with `applyJanusDirectives()` and served by something else.
 
 **Fix:** `plugins: [useJanus({ auth })]`.
 
-### `TypeError: useJanus(): the GraphQL context has no request to authenticate`
+### `TypeError: …: the GraphQL context has no request to authenticate`
 
-**Why:** the context was built without `request` — a transport that is not
-HTTP, such as a WebSocket subscription.
+**Why:** the context was built without `request`, and for no connection
+`janusConnection().onConnect` accepted: a transport that is not HTTP; a
+graphql-ws server without `onConnect`; or Yoga's recipe with the context
+built from something other than `{ ...ctx, … }`, which drops `ctx.extra`,
+where `useJanus()` finds the connection. The message opens with
+`useJanus():` under Yoga, and with `janusConnection().context:` without
+it — the `context` of a server whose `onConnect` is not
+`janusConnection()`'s.
 
-**Fix:** for now, authenticate subscriptions over HTTP (Yoga's server-sent
-events carry the request). A connection-level wiring for graphql-ws is on
-the [roadmap](roadmap.md).
+**Fix:** over graphql-ws, pass `onConnect: janusConnection({ auth }).onConnect`
+to `useServer()`, and keep the `...ctx` spread in `yoga.getEnveloped()`
+([the subscriptions guide](guide/subscriptions.md)). Without Yoga, pass
+`context: connection.context` too.
 
 ### `TypeError: can(): ctx.janus.access is not set`
 
@@ -497,6 +590,34 @@ from the same options.
 
 **Fix:** answer the object, or `null` when there is none.
 
+### The session cookie expires while the user is active
+
+**Why:** `authenticate` renewed the session in the store, and no
+`Set-Cookie` carried the new expiry back, so the browser drops the cookie at
+the expiry it was given at sign-in. `useJanus()` sends it only on Yoga's
+HTTP response (`onResponse`), and not when:
+
+- the server runs on envelop without Yoga, which never calls `onResponse`;
+- the `auth` given to `useJanus()` is a wrapper of yours without `cookie`;
+- the only traffic is over graphql-ws, which has no response to carry it;
+- the client sent `Authorization: Bearer` or `X-Session-Token`, which is
+  never answered with a cookie.
+
+**Fix:** under Yoga, pass `janus()`'s own instance, or a wrapper with
+`cookie: auth.cookie`. Elsewhere — and for a browser that talks only over
+the WebSocket — renew through an HTTP route of yours that sends
+`auth.cookie.serialize(token, session)`, as `@nxgt/janus-hono`'s
+`session()` does.
+
+### `Warning: janusMaskError: report failed on …`
+
+**Why:** the `report` given to `janusMaskError()` threw, or rejected — a
+logger that is down, a serializer that meets a circular `cause`. The name
+after the code is the class of what it threw.
+
+**Fix:** your `report`. The response was sent all the same: a `report`
+never changes the answer, so an outage is still a 503 and never a 500.
+
 ### A 401 whose `data` still holds the other fields
 
 **Why:** Yoga answers the highest status among the errors. One refused field

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus-graphql",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "GraphQL for @nxgt/janus: an envelop plugin with the signed-in user on the context, fields guarded by @authenticated, @fresh and @permission, and every error with the status it deserves",
 	"license": "MIT",
 	"type": "module",
@@ -55,17 +55,26 @@
 	"devDependencies": {
 		"@envelop/core": "^5.6.1",
 		"@graphql-tools/utils": "^12.0.1",
-		"@nxgt/janus": "^0.12.0",
+		"@nxgt/janus": "^0.13.0",
 		"@types/bun": "^1.4.2",
+		"@types/ws": "^8.18.1",
 		"graphql": "^17.0.2",
+		"graphql-ws": "^6.3.0",
 		"graphql-yoga": "^5.24.1",
+		"ws": "^8.22.0",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
 		"@envelop/core": "^5.0.0",
 		"@graphql-tools/utils": ">=10.0.0 <13",
-		"@nxgt/janus": "^0.12.0",
+		"@nxgt/janus": "^0.13.0",
 		"graphql": "^16.9.0 || ^17.0.0",
+		"graphql-ws": "^6.0.0",
 		"typescript": "^6.0.3"
+	},
+	"peerDependenciesMeta": {
+		"graphql-ws": {
+			"optional": true
+		}
 	}
 }