@nxgt/janus-graphql 0.1.1 → 0.3.0

package/docs/guide/directives.md

@@ -1,7 +1,8 @@
 # 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
+is, `@fresh`, which asks how recently their session proved it, and
+`@permission`, which asks what the user may do to one object. All three
 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.
@@ -26,7 +27,7 @@ export const yoga = createYoga({
 
 ## Where a directive applies
 
-Both directives go on a field, an object type or an interface:
+Every directive goes on a field, an object type or an interface:
 
 | Written on | Guards |
 | --- | --- |
@@ -78,6 +79,57 @@ On `Ward.chart` above, the type's `["staff"]` and the field's
 Under `useJanus({ type: 'staff' })`, the only user type a directive may name
 is `'staff'`.
 
+## `@fresh(maxAge: Int!)`
+
+```graphql
+type Mutation {
+	changeEmail(email: String!): User @fresh(maxAge: 600) # signed in, or confirmed, in the last ten minutes
+}
+
+type PaymentMethods @fresh(maxAge: 600) {              # every field of PaymentMethods
+	cards: [Card!]!
+	add(token: String!): Card @fresh(maxAge: 60)       # the smallest maxAge holds: one minute
+}
+```
+
+Only a session that proved who it is **less than `maxAge` seconds ago**
+reaches the field: signed in, or confirmed since by `auth.stepUp.confirm`,
+which moves the session's `authenticatedAt` to now. Renewing a sliding
+session does not. It is `@nxgt/janus`'s `assertFresh`, and
+`@nxgt/janus-hono`'s `fresh()`, for a schema.
+
+**`maxAge` is in seconds**, an `Int`: `600` is ten minutes. Seconds because
+a GraphQL `Int` is 32 bits — about 24 days in milliseconds — and because a
+freshness limit is written in seconds elsewhere, such as OpenID Connect's
+`max_age`. `@nxgt/janus`'s durations read a bare number as milliseconds;
+here there is no unit to write, so it is seconds, always.
+
+| The request | Answered |
+| --- | --- |
+| anonymous | `UNAUTHENTICATED`, 401 |
+| a user of a type `@authenticated` does not name | `FORBIDDEN`, 403, before freshness is read |
+| a session that proved who it is `maxAge` seconds ago or more | `STEP_UP_REQUIRED`, 403 — the client asks for a step-up |
+| a store that cannot answer | `SERVICE_UNAVAILABLE`, 503, never a denial |
+| a fresh session | every `@permission`, then the resolver |
+
+`@fresh` implies a signed-in user, as `@permission` does. **It is checked
+after `@authenticated` and before any `@permission`**, so a stale session
+asks no permission check and loads no object. Where several apply — the
+field's, its type's, its interfaces' — **the smallest `maxAge` holds**. The
+refusal is at `maxAge` exactly: a session `maxAge` seconds old is refused,
+as `assertFresh` refuses it.
+
+**A `@fresh` on a subscription field is checked when it subscribes**: a
+fresh one keeps receiving events past `maxAge`. A `@fresh` on the payload's
+type or its fields is checked on every event, as any field. See
+[the step-up over GraphQL](step-up.md#subscriptions).
+
+The time is `useJanus({ clock })`'s — give it the clock given to `janus()`
+when that is not the system's, such as `fixedClock` in a spec. The flow a
+client follows on `STEP_UP_REQUIRED`, with `stepUp.request` and `confirm` as
+mutations, is in [the step-up over GraphQL](step-up.md); `requireFresh(ctx,
+maxAge)` is the same check in a resolver.
+
 ## `@permission(name, type, id, onDeny)`
 
 ```graphql
@@ -102,7 +154,8 @@ reads reaches the field. It is `@nxgt/janus-hono`'s
 | `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.
+`UNAUTHENTICATED`, 401, before any object is loaded or any check asked. A
+`@fresh` that applies is checked before it, too.
 
 ### Reading the id
 
@@ -213,7 +266,9 @@ 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
+the type's, the interfaces' fields', then the field's own. Across
+directives, every `@authenticated` comes first, then `@fresh`, then the
+`@permission`s. So a type's
 `NOT_FOUND` answers before a field's `FORBIDDEN` could tell that the object
 exists.
 
@@ -235,6 +290,7 @@ type Record @permission(name: "view", type: "record") {
 | --- | --- |
 | anonymous | `UNAUTHENTICATED`, 401 |
 | a user of a type `@authenticated` does not name | `FORBIDDEN`, 403, before any check |
+| a session older than a `@fresh` that applies allows | `STEP_UP_REQUIRED`, 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 |
@@ -278,6 +334,7 @@ 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(): @fresh on Mutation.changeEmail asks maxAge: 0 — write a number of seconds above zero, such as maxAge: 600 for ten minutes
 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'
@@ -292,7 +349,9 @@ 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`.
+of the wrong shape, `loaders` or `conditions` without `access`, and a
+`clock` that is not a `Clock`. A `maxAge` that is not an `Int`, or is
+missing, is refused by graphql-js itself, at start-up too.
 
 ## The transform alone
 

package/docs/guide/errors.md

@@ -30,8 +30,9 @@ Yoga reads `extensions.http.status` to answer the HTTP response, and strips
 
 | Code | Status | Message | When |
 | --- | --- | --- | --- |
-| `UNAUTHENTICATED` | 401 | `Not signed in` | An anonymous request reached a field `@authenticated` guards, or `requireUser()` |
+| `UNAUTHENTICATED` | 401 | `Not signed in` | An anonymous request reached a guarded field, `requireUser()` or `requireFresh()` |
 | `FORBIDDEN` | 403 | `Forbidden` | A user of a type the directive or `requireUser({ type })` does not name, or a `@permission(onDeny: FORBIDDEN)` denied |
+| `STEP_UP_REQUIRED` | 403 | `Forbidden` | A session older than `@fresh(maxAge)` or `requireFresh(ctx, maxAge)` allows: the client asks for a step-up — see [the step-up over GraphQL](step-up.md) |
 | `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, … |

package/docs/guide/federation.md

@@ -53,8 +53,9 @@ 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"])
+	@link(url: "https://example.com/janus/v1.0", import: ["@authenticated", "@fresh", "@permission"])
 	@composeDirective(name: "@authenticated")
+	@composeDirective(name: "@fresh")
 	@composeDirective(name: "@permission")
 ```
 

package/docs/guide/step-up.md

@@ -0,0 +1,186 @@
+# A step-up over GraphQL
+
+This page is for a mutation a stolen session should not run alone: changing
+the e-mail, a payment method, deleting the account. `@fresh(maxAge)` lets it
+run only for a session that proved who it is less than `maxAge` seconds ago;
+older, it answers `STEP_UP_REQUIRED`, and the client proves it again with a
+step-up. `@nxgt/janus` issues and checks the code, and stamps the session.
+This page shows the whole flow as GraphQL. For the directive alone, see
+[directives](directives.md#freshmaxage-int); for the step-up itself, every
+error and the codes an app confirms, see
+[`@nxgt/janus`'s step-up guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/step-up.md).
+
+## The schema
+
+```graphql
+type Mutation {
+	changeEmail(email: String!): User @fresh(maxAge: 600)   # ten minutes
+	deleteAccount: Boolean! @fresh(maxAge: 300)              # five
+
+	requestStepUp: StepUpChallenge! @authenticated
+	confirmStepUp(challenge: String!, code: String!): Boolean! @authenticated
+}
+
+type StepUpChallenge {
+	challenge: String!
+	via: String!   # "email", or "secondFactor": the code is in the user's app
+}
+```
+
+`@fresh` implies a signed-in user: an anonymous request is `UNAUTHENTICATED`,
+401, before freshness is read. The two step-up mutations need a signed-in
+user and no fresh one: they are how a session becomes fresh.
+
+## The resolvers
+
+```ts
+import { requireUser, type JanusContext } from '@nxgt/janus-graphql';
+import type { YogaInitialContext } from 'graphql-yoga';
+
+type Context = YogaInitialContext & JanusContext<typeof auth>;
+
+const resolvers = {
+	Mutation: {
+		changeEmail: (_: unknown, { email }: { email: string }, ctx: Context) =>
+			users.changeEmail(ctx, email), // runs only on a fresh session
+
+		requestStepUp: async (_: unknown, __: unknown, ctx: Context) => {
+			const user = await requireUser(ctx); // the session's user — never an id the client sent
+			const issued = await auth.stepUp.request(user);
+			if (issued.via === 'email') {
+				await sendMail(issued.email, 'Confirm it is you', `${issued.code} confirms the action.`);
+			}
+			return { challenge: issued.challenge, via: issued.via }; // never the code
+		},
+
+		confirmStepUp: async (
+			_: unknown,
+			{ challenge, code }: { challenge: string; code: string },
+			ctx: Context,
+		) => {
+			await auth.stepUp.confirm(ctx.request, challenge, code); // stamps this request's session
+			return true;
+		},
+	},
+};
+```
+
+`stepUp.confirm` takes the **request**, not a user: it stamps the session
+that request presents, and only a standing session of the challenge's user.
+`ctx.request` is the `Request` Yoga puts on the context, and carries the same
+token or cookie as the mutation that was refused. With several user types,
+`stepUp` is on each type that has an e-mail — `auth.patient.stepUp` — and
+`requireUser(ctx, { type: 'patient' })` narrows the user to it.
+
+**Wire `janusMaskError()`.** A wrong code is a `JanusError` the resolver lets
+through — `CODE_INVALID`, 401, with `attemptsLeft` — and without the mask
+Yoga answers it as a 500.
+
+## What the client does
+
+1. It sends `changeEmail`. The session is older than ten minutes:
+
+   ```json
+   { "data": { "changeEmail": null },
+     "errors": [{ "message": "Forbidden", "path": ["changeEmail"], "extensions": { "code": "STEP_UP_REQUIRED" } }] }
+   ```
+
+   The response is a 403. The client reads `extensions.code`, never the
+   message, which is the fixed one of the status.
+
+2. It sends `requestStepUp`, and keeps `challenge`. The user reads the code
+   in the e-mail — or in their app, when `via` is `"secondFactor"`.
+
+3. It sends `confirmStepUp(challenge, code)`. From now on, the session is
+   fresh for `maxAge` seconds.
+
+4. It sends `changeEmail` again, which runs.
+
+| `confirmStepUp` answers | Status | The client |
+| --- | --- | --- |
+| `true` | 200 | sends the refused mutation again |
+| `CODE_INVALID`, with `attemptsLeft` | 401 | asks for the code again; at `0`, starts over at `requestStepUp` |
+| `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_UNKNOWN`, `TOKEN_STALE` | 400 | starts over at `requestStepUp` |
+| `SECOND_FACTOR_ACTIVE` | 409 | starts over: the user's app confirms now |
+| `SECOND_FACTOR_NOT_ENROLLED` | 409 | starts over: the factor was disabled, an e-mailed code confirms now |
+| `USER_INACTIVE` | 403 | stops: the account was deactivated |
+| `SERVICE_UNAVAILABLE` | 503 | retries later |
+
+`requestStepUp` itself answers `USER_INACTIVE`, 403, for a deactivated
+user, and `NOT_FOUND`, 404, for a user with no e-mail to send a code to
+— an optional e-mail left empty.
+
+**Rate-limit `requestStepUp` per user.** A new challenge takes only a new
+request, and each one sends an e-mail: a few an hour is plenty for a person.
+
+## In a resolver: `requireFresh(ctx, maxAge)`
+
+Where the rule depends on the arguments, ask in the resolver:
+
+```ts
+import { requireFresh } from '@nxgt/janus-graphql';
+
+const resolvers = {
+	Mutation: {
+		transfer: async (_: unknown, { amount }: { amount: number }, ctx: Context) => {
+			if (amount > 1_000) await requireFresh(ctx, '5m'); // STEP_UP_REQUIRED past five minutes
+			return payments.transfer(ctx, amount);
+		},
+	},
+};
+```
+
+It answers the session, and refuses as `@fresh` does. `maxAge` is a
+duration with its unit — `'5m'`, `'300s'` — never a bare number: the
+compiler refuses one, and so does the call at run time, because
+`@nxgt/janus` reads a bare number as milliseconds where `@fresh` reads
+seconds.
+
+## Subscriptions
+
+**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. `@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
+the stream goes on.
+
+```graphql
+type Subscription {
+	receipts: Receipt @fresh(maxAge: 600) # checked once, when it subscribes
+}
+type Receipt @fresh(maxAge: 600) {       # checked on every event that carries one
+	amount: Int
+}
+```
+
+## Testing it
+
+`useJanus({ clock })` is the clock `@fresh` and `requireFresh()` read. Give
+it the one given to `janus()`, and a spec moves both at once:
+
+```ts
+import { fixedClock, janus } from '@nxgt/janus';
+
+const clock = fixedClock(Date.UTC(2026, 0, 1));
+const auth = janus({ /* … */ clock });
+const yoga = createYoga({ schema, plugins: [useJanus({ auth, clock })] });
+
+const { token } = await auth.signUp({ email, password }); // signed in now
+clock.advance(10 * 60_000); // ten minutes later
+// changeEmail now answers STEP_UP_REQUIRED
+```
+
+Without `clock`, both read the system's. A `janus()` on a fixed clock and a
+`useJanus()` without one disagree on the time: a session signed in on
+the fixed clock looks days old, and every `@fresh` field answers
+`STEP_UP_REQUIRED`.

package/docs/guide/subscriptions.md

@@ -0,0 +1,251 @@
+# 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: renew through your HTTP routes.

package/docs/roadmap.md

@@ -9,14 +9,6 @@ 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 that proved who it is less
-  than `maxAge` ago may resolve — signed in, or confirmed since by
-  `auth.stepUp.confirm`: a password change, a new e-mail, a payment method,
-  asked again of a session that is days old. `@nxgt/janus` 0.12's
-  `assertFresh` is the check, and `STEP_UP_REQUIRED` the error it answers.
 - **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
@@ -24,7 +16,12 @@ Nothing between releases.
 
 ## 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
 
@@ -46,6 +43,29 @@ Nothing yet.
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **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`:
+  a new e-mail or a payment method, asked again of a session that is days
+  old. An older session is `STEP_UP_REQUIRED`, 403, which tells the client
+  to ask for a step-up; checked after `@authenticated` and before any
+  `@permission`, and for a subscription when it subscribes.
+  `requireFresh(ctx, '10m')` is the same check in a resolver, and
+  `useJanus({ clock })` the clock both read. `@nxgt/janus` 0.12's
+  `assertFresh` is the check.
+
 - **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