@nxgt/janus-graphql 0.5.1 → 0.5.3

package/README.md

@@ -257,6 +257,13 @@ createYoga({
   browser keeps the cookie with its old expiry until the next renewal over
   HTTP, a `renewAfter` later: a browser whose only traffic is the WebSocket
   should renew through an HTTP route of yours.
+- **A sign-in mutation passes the device itself.** `@nxgt/janus-graphql`
+  signs nobody in, and ships no device helper: with `janus({ devices })`,
+  read the device cookie from `ctx.request` — `useCookies()`'s
+  `cookieStore`, or the `Cookie` header — call
+  `auth.signIn(input, { device: token ?? null })`, and set `deviceToken`
+  back as a long-lived `HttpOnly` cookie. See
+  [the context](docs/guide/context.md#a-sign-in-mutation-and-the-device-cookie).
 - **An `auth` of your own needs `cookie` for the renewal.** A wrapper that
   passes on only `authenticate` and `types` sends no renewed cookie; pass
   `cookie: auth.cookie` along.

package/docs/README.md

@@ -8,7 +8,7 @@ give the detail.
 | [Directives](guide/directives.md) | You are guarding fields, types or interfaces with `@authenticated`, `@fresh` or `@permission`: where the id is read, loaders and conditions, lists, the order, the denials, one check per question, and what is refused at start-up |
 | [The step-up over GraphQL](guide/step-up.md) | A mutation must run only on a session that proved who it is recently: `@fresh`, `STEP_UP_REQUIRED`, `stepUp.request` and `confirm` as mutations, `requireFresh()`, subscriptions, and testing with a clock |
 | [Subscriptions over graphql-ws](guide/subscriptions.md) | You serve subscriptions over a WebSocket: `janusConnection()`, the cookie or `connectionParams`, the close codes, a session revoked mid-stream, Bun, and a server without Yoga |
-| [The context](guide/context.md) | You are reading the user in a resolver, narrowing it to a user type, checking a permission or freshness yourself with `requireUser()`, `requireFresh()` and `can()`, or wondering when the renewed session cookie is sent |
+| [The context](guide/context.md) | You are reading the user in a resolver, narrowing it to a user type, checking a permission or freshness yourself with `requireUser()`, `requireFresh()` and `can()`, wondering when the renewed session cookie is sent, or passing the device cookie from a sign-in mutation |
 | [Errors](guide/errors.md) | You want to know what a client receives for a denial or an outage, what the status of the response is, how `janusMaskError()` fits Yoga's masking, and how `report` logs every outage |
 | [Telemetry](guide/telemetry.md) | You want a span per authentication and per permission check, with `@nxgt/janus-telemetry` |
 | [Federation](guide/federation.md) | The server is a subgraph: where the directives are checked, what the router must forward, and `@composeDirective` |

package/docs/guide/context.md

@@ -123,6 +123,79 @@ type StaffContext = YogaInitialContext & JanusContext<typeof auth, typeof access
 Without `access`, write `JanusContext<typeof auth>`: `ctx.janus.access` is
 then absent from the type, as it is from the context.
 
+## A sign-in mutation and the device cookie
+
+`@nxgt/janus-graphql` runs no sign-in: a mutation of yours calls
+`auth.signIn`. With `janus({ devices })`, that call takes the **device
+token** the browser holds, as `device`, and answers a `deviceToken` to keep
+in a long-lived cookie of its own — so a sign-in from a device the user had
+not signed in from is told apart
+([`@nxgt/janus`'s devices guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/devices.md)).
+No helper is shipped for it: read the cookie from `ctx.request`, and set it
+back on the response.
+
+With Yoga, [`useCookies()`](https://the-guild.dev/graphql/yoga-server/docs/features/cookies)
+from `@whatwg-node/server-plugin-cookies` — a separate install, not a peer
+of this package: `bun add @whatwg-node/server-plugin-cookies` — gives the
+request a `cookieStore` to read and write through:
+
+```ts
+import { janusMaskError, janusTypeDefs, useJanus } from '@nxgt/janus-graphql';
+import { useCookies } from '@whatwg-node/server-plugin-cookies';
+import { createSchema, createYoga } from 'graphql-yoga';
+
+const DEVICE = 'janus-device';
+const FOUR_HUNDRED_DAYS = 400 * 24 * 60 * 60 * 1000; // the longest a browser keeps a cookie
+
+const resolvers = {
+	Mutation: {
+		signIn: async (_: unknown, args: { email: string; password: string }, ctx: Context) => {
+			const token = (await ctx.request.cookieStore?.get(DEVICE))?.value;
+			const result = await auth.signIn(args, { device: token ?? null });
+			if (result.status === 'secondFactor') return { challenge: result.challenge };
+			// …set the session cookie from result.token, as your sign-in already does
+			if (result.deviceToken !== null) {
+				await ctx.request.cookieStore?.set({
+					name: DEVICE,
+					value: result.deviceToken,
+					expires: Date.now() + FOUR_HUNDRED_DAYS,
+					httpOnly: true,
+					secure: true,
+					sameSite: 'lax',
+					path: '/',
+				});
+			}
+			return { userId: result.user.id, newDevice: result.newDevice };
+		},
+	},
+};
+
+export const yoga = createYoga({
+	schema: createSchema({ typeDefs: [janusTypeDefs, typeDefs], resolvers }),
+	plugins: [useCookies(), useJanus({ auth, access })],
+	maskedErrors: { maskError: janusMaskError() },
+});
+```
+
+Without the plugin, read the device token from the `Cookie` header —
+`ctx.request.headers.get('cookie')` — and set the cookie with a plugin of
+your own that appends a `Set-Cookie` in Yoga's `onResponse`.
+
+- **`token ?? null`, never `token` alone.** A missing cookie is
+  `undefined`, and `undefined` means *not tracked*: that browser would never
+  be given a token, nor reported.
+- **Give the device again to the second factor's mutation.** With an active
+  second factor, `signIn` answers a challenge that carries no device:
+  `auth.secondFactor.confirm(challenge, code, { device: token ?? null })`, and
+  the same for `recover`, `signInCode.confirm` and `magicLink.confirm`.
+- **A cookie of its own, apart from the session's**, `HttpOnly` and
+  `Secure`, and left in place by a sign-out: the device stays known. It
+  holds one user's token — see
+  [devices](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/devices.md#keeping-the-token-the-cookie).
+
+A bearer client has no cookie jar: answer it the `deviceToken` in the
+mutation's result, and take it back as an argument of the next sign-in.
+
 ## Directives
 
 `@authenticated`, `@fresh` and `@permission` guard a field, a type or an interface

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus-graphql",
-	"version": "0.5.1",
+	"version": "0.5.3",
 	"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.15.0",
+		"@nxgt/janus": "^0.17.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.15.0",
+		"@nxgt/janus": "^0.17.0",
 		"graphql": "^16.9.0 || ^17.0.0",
 		"graphql-ws": "^6.0.0",
 		"typescript": "^6.0.3"