@nxgt/janus-graphql 0.1.1 → 0.2.0

package/docs/guide/step-up.md

@@ -0,0 +1,182 @@
+# 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. `@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
+it from the server.
+
+**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/roadmap.md

@@ -12,11 +12,6 @@ Nothing between releases.
 - **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
@@ -46,6 +41,17 @@ Nothing yet.
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **`@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

package/docs/troubleshooting.md

@@ -15,6 +15,7 @@ for what causes each.
 - [`TypeError: applyJanusDirectives(): @authenticated on … names the user type '…', which is not one of …`](#typeerror-applyjanusdirectives-authenticated-on--names-the-user-type--which-is-not-one-of-)
 - [`TypeError: applyJanusDirectives(): @authenticated on … names no user type`](#typeerror-applyjanusdirectives-authenticated-on--names-no-user-type)
 - [`TypeError: applyJanusDirectives(): the @authenticated on … admit no user type in common`](#typeerror-applyjanusdirectives-the-authenticated-on--admit-no-user-type-in-common)
+- [`TypeError: applyJanusDirectives(): @fresh on … asks maxAge: …`](#typeerror-applyjanusdirectives-fresh-on--asks-maxage-)
 - [`TypeError: applyJanusDirectives(): @permission on … needs the permissions() instance`](#typeerror-applyjanusdirectives-permission-on--needs-the-permissions-instance)
 - [`TypeError: applyJanusDirectives(): @permission on … names the object type '…', which is not one of …`](#typeerror-applyjanusdirectives-permission-on--names-the-object-type--which-is-not-one-of-)
 - [`TypeError: applyJanusDirectives(): @permission on … asks '…', which … does not declare`](#typeerror-applyjanusdirectives-permission-on--asks--which--does-not-declare)
@@ -23,20 +24,27 @@ for what causes each.
 - [`TypeError: applyJanusDirectives(): @permission on … reads the …'s id from …, and … reads '…' of the object itself (fromField)`](#typeerror-applyjanusdirectives-permission-on--reads-the-s-id-from--and--reads--of-the-object-itself-fromfield)
 - [`TypeError: applyJanusDirectives(): @permission on … asks '…' of …, which reaches a when()`](#typeerror-applyjanusdirectives-permission-on--asks--of--which-reaches-a-when)
 - [`TypeError: applyJanusDirectives(): @permission on … finds loaders.…, which is not a function`](#typeerror-applyjanusdirectives-permission-on--finds-loaders-which-is-not-a-function)
-- [`Unknown directive "@authenticated"`, or `"@permission"`](#unknown-directive-authenticated-or-permission)
+- [`Unknown directive "@authenticated"`, `"@fresh"` or `"@permission"`](#unknown-directive-authenticated-fresh-or-permission)
+- [`Argument "@fresh(maxAge:)" of type "Int!" is required`, or `Argument "maxAge" has invalid value …`](#argument-freshmaxage-of-type-int-is-required-or-argument-maxage-has-invalid-value-)
 - [`TypeError: applyJanusDirectives(): type '…' is not a user type of auth`](#typeerror-applyjanusdirectives-type--is-not-a-user-type-of-auth)
 - [`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)
 
 **In a response**
 - [`UNAUTHENTICATED` for a signed-in user](#unauthenticated-for-a-signed-in-user)
 - [`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)
 - [`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: 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)
+- [`TypeError: requireFresh(): maxAge: "…" is not a duration`](#typeerror-requirefresh-maxage--is-not-a-duration)
+- [`TypeError: requireFresh(): maxAge: a duration must be above zero`](#typeerror-requirefresh-maxage-a-duration-must-be-above-zero)
 - [`@permission on … resolved no object id from … — answered NOT_FOUND`](#permission-on--resolved-no-object-id-from---answered-not_found)
 - [`NOT_FOUND` where the user should be allowed](#not_found-where-the-user-should-be-allowed)
 - [A 403 that tells a user the object exists](#a-403-that-tells-a-user-the-object-exists)
@@ -52,6 +60,9 @@ for what causes each.
 - [`'…' does not exist in type 'Loaders<…>'`, or `'Conditions<…>'`](#-does-not-exist-in-type-loaders-or-conditions)
 - [`Type '{ …: … }' is not assignable to type 'never'`, on `loaders`](#type-----is-not-assignable-to-type-never-on-loaders)
 - [`Source has 0 element(s) but target requires 1`, on `requireUser()`](#source-has-0-elements-but-target-requires-1-on-requireuser)
+- [`Argument of type '600' is not assignable to parameter of type '`${number}ms` | …'`, on `requireFresh()`](#argument-of-type-600-is-not-assignable-to-parameter-of-type-numberms---on-requirefresh)
+- [`Expected 2 arguments, but got 1`, on `requireFresh()`](#expected-2-arguments-but-got-1-on-requirefresh)
+- [`Type 'number' is not assignable to type 'Clock'`](#type-number-is-not-assignable-to-type-clock)
 
 ## At start-up
 
@@ -95,6 +106,24 @@ type Ward @authenticated(type: ["staff"]) {
 **Fix:** widen one of them, or move the field to a type whose directive
 admits the users it is for.
 
+### `TypeError: applyJanusDirectives(): @fresh on … asks maxAge: …`
+
+**When:** at start-up, for a schema that uses `@fresh`.
+
+**Why:** `maxAge` is not above zero — `@fresh(maxAge: 0)` or a negative
+number — so no session could ever be fresh enough, and every request would
+be refused. The message names the field, and the location the directive was
+written on when it is not the field: `@fresh on Account (read by
+Account.email)`.
+
+**Fix:** write a number of **seconds** above zero:
+
+```graphql
+type Mutation {
+	changeEmail(email: String!): User @fresh(maxAge: 600) # ten minutes
+}
+```
+
 ### `TypeError: applyJanusDirectives(): @permission on … needs the permissions() instance`
 
 **When:** at start-up, for a schema that uses `@permission`.
@@ -192,7 +221,7 @@ than a function of it, from JavaScript or past a cast.
 
 **Fix:** `loaders: { record: (id) => records.find(id) }`.
 
-### `Unknown directive "@authenticated"`, or `"@permission"`
+### `Unknown directive "@authenticated"`, `"@fresh"` or `"@permission"`
 
 **Why:** graphql-js builds the schema before `useJanus()` sees it, and the
 directive is not declared.
@@ -202,6 +231,18 @@ directive is not declared.
 generator reading files takes
 `node_modules/@nxgt/janus-graphql/graphql/janus.graphqls`.
 
+### `Argument "@fresh(maxAge:)" of type "Int!" is required`, or `Argument "maxAge" has invalid value …`
+
+graphql 16 words the first `Directive "@fresh" argument "maxAge" of type
+"Int!" is required, but it was not provided.`
+
+**Why:** graphql-js refuses the directive at start-up: `@fresh` without
+`maxAge`, when the schema is built; or with a value that is not an `Int` —
+a fraction, a string such as `"10m"` — when `useJanus()` reads it.
+
+**Fix:** a whole number of seconds: `@fresh(maxAge: 600)`. A duration with a
+unit belongs to `requireFresh(ctx, '10m')`, in a resolver.
+
 ### `TypeError: applyJanusDirectives(): type '…' is not a user type of auth`
 
 **When:** at start-up, with `useJanus({ auth, type })` or
@@ -228,6 +269,15 @@ its place, or the module that exports `auth` not loaded yet.
 **Fix:** `useJanus({ auth, access })`, with `access` what `permissions()`
 answered — or leave `access` out when no field uses `@permission` or `can()`.
 
+### `TypeError: useJanus(): clock is not a Clock`
+
+**Why:** `clock` has no `now()` — a timestamp such as `Date.now()`, or a
+`Date`, passed from JavaScript or cast past the compiler.
+
+**Fix:** pass the clock given to `janus()` — `fixedClock(…)` from
+`@nxgt/janus` in a spec — or leave `clock` out for the system's:
+`useJanus({ auth, clock })`.
+
 ## In a response
 
 ### `UNAUTHENTICATED` for a signed-in user
@@ -251,12 +301,37 @@ says applies to it too.
 **Fix:** read the directives on the field, on its type, and on every
 interface the type implements.
 
+### `STEP_UP_REQUIRED`, 403
+
+**Why:** a field `@fresh(maxAge)` guards, or a `requireFresh(ctx, maxAge)`,
+was reached by a session that proved who it is `maxAge` ago or more — at
+its sign-in, or at its last `auth.stepUp.confirm`. Renewing a sliding
+session does not count. This is the answer working: it tells the client to
+ask for a step-up.
+
+**Fix:** in the client, on `extensions.code === 'STEP_UP_REQUIRED'`, run the
+step-up — `requestStepUp`, then `confirmStepUp(challenge, code)` — and send
+the request again. The mutations are in
+[the step-up over GraphQL](guide/step-up.md).
+
+### `STEP_UP_REQUIRED` for a user who just signed in
+
+**Why:** `@fresh` reads the time from `useJanus({ clock })`, and the session
+was stamped with `janus()`'s. Two different clocks: `janus({ clock:
+fixedClock(…) })` with `useJanus()` given none, in a spec — the session looks
+days old. Or `maxAge` written as minutes: `@fresh(maxAge: 10)` is ten
+seconds, not ten minutes.
+
+**Fix:** give both the same clock — `useJanus({ auth, clock })` — and write
+`maxAge` in seconds: `@fresh(maxAge: 600)` for ten minutes.
+
 ### `SERVICE_UNAVAILABLE`, 503, on every guarded field
 
 **Why:** a store could not answer — `STORE_FAILED`. The sessions store for
-`@authenticated`, `requireUser()` and `ctx.janus.user()`; the relation store
+`@authenticated`, `@fresh`, `requireUser()`, `requireFresh()` and
+`ctx.janus.user()`; the relation store
 for `can()` and `@permission` — and a loader of yours that threw
-`StoreFailure`. It is never answered `UNAUTHENTICATED` or `FORBIDDEN`.
+`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
@@ -307,6 +382,30 @@ signed-in user:
 const user = await requireUser(ctx, allowed.length > 0 ? { type: allowed } : {});
 ```
 
+### `TypeError: requireFresh(): maxAge is a duration with its unit`
+
+**Why:** `requireFresh(ctx, 600)` — a bare number, from JavaScript or built
+at run time. `@nxgt/janus` would read it as 600 milliseconds, where
+`@fresh(maxAge: 600)` reads ten minutes, so it is refused rather than
+guessed. The compiler refuses a literal number.
+
+**Fix:** write the unit: `requireFresh(ctx, '10m')`, or `'600s'`.
+
+### `TypeError: requireFresh(): maxAge: "…" is not a duration`
+
+**Why:** the string is not a number followed by `ms`, `s`, `m`, `h` or `d`
+— `'10 minutes'`, `'10 m'`.
+
+**Fix:** `requireFresh(ctx, '10m')`.
+
+### `TypeError: requireFresh(): maxAge: a duration must be above zero`
+
+**Why:** `requireFresh(ctx, '0m')` — no session is ever fresh within no
+time, so every request would be refused. The compiler lets it through: the
+type reads a number and a unit, not their value.
+
+**Fix:** a duration above zero, `requireFresh(ctx, '10m')`.
+
 ### `@permission on … resolved no object id from … — answered NOT_FOUND`
 
 **Where:** a warning, through `process.emitWarning` with the code
@@ -469,3 +568,28 @@ throws
 
 **Fix:** name at least one user type, `{ type: ['staff'] }`, or leave `type`
 out to admit any signed-in user.
+
+### `Argument of type '600' is not assignable to parameter of type '`${number}ms` | …'`, on `requireFresh()`
+
+The full message ends `` '`${number}ms` | `${number}s` | `${number}m` |
+`${number}h` | `${number}d`' ``; the same for `'10 minutes'`.
+
+**Why:** `requireFresh(ctx, maxAge)` takes a duration with its unit. A bare
+number would be milliseconds to `@nxgt/janus` and seconds to `@fresh`, so
+neither is guessed.
+
+**Fix:** `requireFresh(ctx, '10m')`.
+
+### `Expected 2 arguments, but got 1`, on `requireFresh()`
+
+**Why:** `requireFresh(ctx)` — how recent the proof must be has no default.
+
+**Fix:** `requireFresh(ctx, '10m')`.
+
+### `Type 'number' is not assignable to type 'Clock'`
+
+**Why:** `useJanus({ auth, clock: Date.now() })` — a timestamp, where a
+clock answers `now()`.
+
+**Fix:** pass the clock given to `janus()`, `fixedClock(…)` in a spec, or
+leave `clock` out.

package/graphql/janus.graphqls

@@ -7,6 +7,14 @@ directive @authenticated(
 	type: [String!]
 ) on OBJECT | INTERFACE | FIELD_DEFINITION
 
+"""
+Only a session that proved who it is less than `maxAge` seconds ago reaches
+this field, or every field of this type or interface: signed in, or confirmed
+since by a step-up. Anonymous is answered UNAUTHENTICATED, an older session
+STEP_UP_REQUIRED. Where several apply, the smallest `maxAge` holds.
+"""
+directive @fresh(maxAge: Int!) on OBJECT | INTERFACE | FIELD_DEFINITION
+
 """
 What a denied `@permission` answers.
 """

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@nxgt/janus-graphql",
-	"version": "0.1.1",
-	"description": "GraphQL for @nxgt/janus: an envelop plugin with the signed-in user on the context, fields guarded by @authenticated and @permission, and every error with the status it deserves",
+	"version": "0.2.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",
 	"main": "./dist/index.js",