@nxgt/janus-graphql 0.3.0 → 0.5.0

package/docs/guide/errors.md

@@ -43,7 +43,8 @@ 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`,
+`attemptsLeft` for `CODE_INVALID`, `retryAfter` for a throttled
+`CREDENTIALS_INVALID` — with its `Retry-After` header. **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
@@ -64,7 +65,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 +78,7 @@ import { createYoga, maskError } from 'graphql-yoga';
 createYoga({
 	schema,
 	plugins: [useJanus({ auth })],
-	maskedErrors: { maskError: janusMaskError(maskError) },
+	maskedErrors: { maskError: janusMaskError({ fallback: maskError }) },
 });
 ```
 
@@ -88,8 +89,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 +150,42 @@ try {
 }
 ```
 
+**Password guessing is throttled per login by `@nxgt/janus`**: past ten
+passwords tried at one login in a 15-minute window, `signIn` refuses every
+one, the right password included, until the window ends — nothing locks. A
+sign-in mutation that lets the refusal through answers it with no code of
+its own:
+
+```json
+{
+	"errors": [{ "message": "Invalid credentials", "path": ["signIn"], "extensions": { "code": "CREDENTIALS_INVALID", "retryAfter": 840 } }]
+}
+```
+
+with a 401 and a `Retry-After: 840` header — `janusGraphQLError()` puts it
+in `extensions.http.headers`, which Yoga answers with and strips from the
+body. `retryAfter` is the seconds until the login's next window.
+`janus({ signIn: { throttle } })` changes the limit
+([passwords](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/passwords.md#password-guessing-is-throttled)).
+
+What the throttle does not see is one password tried against many logins:
+limit a sign-in mutation **per client address** as well, in the resolver,
+with the limiter you already run:
+
+```ts
+import { GraphQLError } from 'graphql';
+
+if (!(await limiter.consume(`sign-in:${clientAddress}`))) {
+	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. Limit a `changePassword`
+mutation per user too: it compares the current password.
+
 ## The status of a response
 
 Yoga answers **the highest status among the errors**. A query whose fields

package/docs/guide/subscriptions.md

@@ -248,4 +248,8 @@ cookie is never read.
   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.
+  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,10 +9,7 @@ Nothing between releases.
 
 ## Next
 
-- **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
 
@@ -43,6 +40,21 @@ Nothing between releases.
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **A throttled sign-in's `retryAfter`, v0.5.0.** `janusGraphQLError()`
+  answers `@nxgt/janus`'s throttled `CREDENTIALS_INVALID` with `retryAfter`
+  in `extensions` and a `Retry-After` header in `extensions.http.headers`,
+  which Yoga answers with. Needs `@nxgt/janus` 0.14.0.
+
+- **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()`

package/docs/troubleshooting.md

@@ -41,6 +41,7 @@ for what causes each.
 
 **In a response**
 - [`UNAUTHENTICATED` for a signed-in user](#unauthenticated-for-a-signed-in-user)
+- [`CREDENTIALS_INVALID` with `retryAfter`, 401, for the right password](#credentials_invalid-with-retryafter-401-for-the-right-password)
 - [`FORBIDDEN` where the user should be allowed](#forbidden-where-the-user-should-be-allowed)
 - [`STEP_UP_REQUIRED`, 403](#step_up_required-403)
 - [`STEP_UP_REQUIRED` for a user who just signed in](#step_up_required-for-a-user-who-just-signed-in)
@@ -59,6 +60,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**
@@ -366,6 +369,20 @@ was revoked; or `useJanus({ type })` treats this user's type as anonymous.
 **Fix:** send `Authorization: Bearer <token>`, `X-Session-Token`, or the
 session cookie; check `useJanus()`'s `type`.
 
+### `CREDENTIALS_INVALID` with `retryAfter`, 401, for the right password
+
+With `extensions.retryAfter` and a `Retry-After` header.
+
+**Why:** `@nxgt/janus` throttles password guessing per login, on by default:
+past ten passwords at one login in a 15-minute window, `signIn` refuses every
+one — the right password included — until the window ends. `retryAfter` is
+the seconds until then. Nothing locks.
+
+**Fix:** show the wait, not "wrong password": read `extensions.retryAfter`
+in the client. To change the limit, `janus({ signIn: { throttle: { attempts,
+window } } })`; in a test over a `fixedClock`, advance the clock past
+`retryAfter`, or wire `signIn: { throttle: false }`.
+
 ### `FORBIDDEN` where the user should be allowed
 
 **Why:** a `type:` that applies does not name the user's type. Every
@@ -410,8 +427,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
 
@@ -580,6 +605,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.3.0",
+	"version": "0.5.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,7 +55,7 @@
 	"devDependencies": {
 		"@envelop/core": "^5.6.1",
 		"@graphql-tools/utils": "^12.0.1",
-		"@nxgt/janus": "^0.12.0",
+		"@nxgt/janus": "^0.14.0",
 		"@types/bun": "^1.4.2",
 		"@types/ws": "^8.18.1",
 		"graphql": "^17.0.2",
@@ -67,7 +67,7 @@
 	"peerDependencies": {
 		"@envelop/core": "^5.0.0",
 		"@graphql-tools/utils": ">=10.0.0 <13",
-		"@nxgt/janus": "^0.12.0",
+		"@nxgt/janus": "^0.14.0",
 		"graphql": "^16.9.0 || ^17.0.0",
 		"graphql-ws": "^6.0.0",
 		"typescript": "^6.0.3"