@softistx/janus-graphql 0.0.0-stage → 0.30.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (207) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +716 -2
  3. package/dist/api-keys/index.d.ts +11 -0
  4. package/dist/api-keys/index.d.ts.map +1 -0
  5. package/dist/api-keys/resolvers/deps.d.ts +39 -0
  6. package/dist/api-keys/resolvers/deps.d.ts.map +1 -0
  7. package/dist/api-keys/resolvers/index.d.ts +39 -0
  8. package/dist/api-keys/resolvers/index.d.ts.map +1 -0
  9. package/dist/api-keys/resolvers/list.d.ts +16 -0
  10. package/dist/api-keys/resolvers/list.d.ts.map +1 -0
  11. package/dist/api-keys/resolvers/manage.d.ts +17 -0
  12. package/dist/api-keys/resolvers/manage.d.ts.map +1 -0
  13. package/dist/api-keys/sdl.d.ts +14 -0
  14. package/dist/api-keys/sdl.d.ts.map +1 -0
  15. package/dist/api-keys/shape.d.ts +38 -0
  16. package/dist/api-keys/shape.d.ts.map +1 -0
  17. package/dist/api-keys/types.d.ts +149 -0
  18. package/dist/api-keys/types.d.ts.map +1 -0
  19. package/dist/avatar/index.d.ts +32 -0
  20. package/dist/avatar/index.d.ts.map +1 -0
  21. package/dist/avatar/resolvers.d.ts +41 -0
  22. package/dist/avatar/resolvers.d.ts.map +1 -0
  23. package/dist/avatar/sdl.d.ts +16 -0
  24. package/dist/avatar/sdl.d.ts.map +1 -0
  25. package/dist/bad-input.d.ts +17 -0
  26. package/dist/bad-input.d.ts.map +1 -0
  27. package/dist/connection/connection.d.ts +36 -0
  28. package/dist/connection/connection.d.ts.map +1 -0
  29. package/dist/connection/credential.d.ts +34 -0
  30. package/dist/connection/credential.d.ts.map +1 -0
  31. package/dist/connection/types.d.ts +61 -0
  32. package/dist/connection/types.d.ts.map +1 -0
  33. package/dist/context/create.d.ts +32 -0
  34. package/dist/context/create.d.ts.map +1 -0
  35. package/dist/context/index.d.ts +9 -0
  36. package/dist/context/index.d.ts.map +1 -0
  37. package/dist/context/registry.d.ts +72 -0
  38. package/dist/context/registry.d.ts.map +1 -0
  39. package/dist/context/resolve.d.ts +20 -0
  40. package/dist/context/resolve.d.ts.map +1 -0
  41. package/dist/device.d.ts +28 -0
  42. package/dist/device.d.ts.map +1 -0
  43. package/dist/directives/apply.d.ts +51 -0
  44. package/dist/directives/apply.d.ts.map +1 -0
  45. package/dist/directives/guard.d.ts +22 -0
  46. package/dist/directives/guard.d.ts.map +1 -0
  47. package/dist/directives/permission/enforce.d.ts +24 -0
  48. package/dist/directives/permission/enforce.d.ts.map +1 -0
  49. package/dist/directives/permission/model.d.ts +35 -0
  50. package/dist/directives/permission/model.d.ts.map +1 -0
  51. package/dist/directives/permission/path.d.ts +31 -0
  52. package/dist/directives/permission/path.d.ts.map +1 -0
  53. package/dist/directives/permission/validate.d.ts +42 -0
  54. package/dist/directives/permission/validate.d.ts.map +1 -0
  55. package/dist/directives/read.d.ts +43 -0
  56. package/dist/directives/read.d.ts.map +1 -0
  57. package/dist/directives/validate.d.ts +39 -0
  58. package/dist/directives/validate.d.ts.map +1 -0
  59. package/dist/directives/words.d.ts +7 -0
  60. package/dist/directives/words.d.ts.map +1 -0
  61. package/dist/errors/denial.d.ts +6 -0
  62. package/dist/errors/denial.d.ts.map +1 -0
  63. package/dist/errors/index.d.ts +12 -0
  64. package/dist/errors/index.d.ts.map +1 -0
  65. package/dist/errors/janus-error.d.ts +20 -0
  66. package/dist/errors/janus-error.d.ts.map +1 -0
  67. package/dist/errors/mask.d.ts +69 -0
  68. package/dist/errors/mask.d.ts.map +1 -0
  69. package/dist/fresh.d.ts +44 -0
  70. package/dist/fresh.d.ts.map +1 -0
  71. package/dist/helpers.d.ts +56 -0
  72. package/dist/helpers.d.ts.map +1 -0
  73. package/dist/index.d.ts +86 -0
  74. package/dist/index.d.ts.map +1 -0
  75. package/dist/index.js +3393 -0
  76. package/dist/index.js.map +75 -0
  77. package/dist/invitations/index.d.ts +12 -0
  78. package/dist/invitations/index.d.ts.map +1 -0
  79. package/dist/invitations/resolvers/anonymous.d.ts +11 -0
  80. package/dist/invitations/resolvers/anonymous.d.ts.map +1 -0
  81. package/dist/invitations/resolvers/deps.d.ts +38 -0
  82. package/dist/invitations/resolvers/deps.d.ts.map +1 -0
  83. package/dist/invitations/resolvers/index.d.ts +37 -0
  84. package/dist/invitations/resolvers/index.d.ts.map +1 -0
  85. package/dist/invitations/resolvers/owner.d.ts +17 -0
  86. package/dist/invitations/resolvers/owner.d.ts.map +1 -0
  87. package/dist/invitations/sdl/accept.d.ts +7 -0
  88. package/dist/invitations/sdl/accept.d.ts.map +1 -0
  89. package/dist/invitations/sdl/index.d.ts +14 -0
  90. package/dist/invitations/sdl/index.d.ts.map +1 -0
  91. package/dist/invitations/sdl/owner.d.ts +8 -0
  92. package/dist/invitations/sdl/owner.d.ts.map +1 -0
  93. package/dist/invitations/shape.d.ts +63 -0
  94. package/dist/invitations/shape.d.ts.map +1 -0
  95. package/dist/invitations/types/index.d.ts +5 -0
  96. package/dist/invitations/types/index.d.ts.map +1 -0
  97. package/dist/invitations/types/options.d.ts +104 -0
  98. package/dist/invitations/types/options.d.ts.map +1 -0
  99. package/dist/invitations/types/out.d.ts +136 -0
  100. package/dist/invitations/types/out.d.ts.map +1 -0
  101. package/dist/invitations/types/surface.d.ts +18 -0
  102. package/dist/invitations/types/surface.d.ts.map +1 -0
  103. package/dist/map-code.d.ts +10 -0
  104. package/dist/map-code.d.ts.map +1 -0
  105. package/dist/mask-error.d.ts +18 -0
  106. package/dist/mask-error.d.ts.map +1 -0
  107. package/dist/memo.d.ts +16 -0
  108. package/dist/memo.d.ts.map +1 -0
  109. package/dist/options.d.ts +17 -0
  110. package/dist/options.d.ts.map +1 -0
  111. package/dist/passkeys/deps.d.ts +23 -0
  112. package/dist/passkeys/deps.d.ts.map +1 -0
  113. package/dist/passkeys/first-factor.types.d.ts +38 -0
  114. package/dist/passkeys/first-factor.types.d.ts.map +1 -0
  115. package/dist/passkeys/index.d.ts +14 -0
  116. package/dist/passkeys/index.d.ts.map +1 -0
  117. package/dist/passkeys/resolvers.d.ts +23 -0
  118. package/dist/passkeys/resolvers.d.ts.map +1 -0
  119. package/dist/passkeys/sdl.d.ts +14 -0
  120. package/dist/passkeys/sdl.d.ts.map +1 -0
  121. package/dist/passkeys/shape.d.ts +14 -0
  122. package/dist/passkeys/shape.d.ts.map +1 -0
  123. package/dist/passkeys/sign-in.resolvers.d.ts +19 -0
  124. package/dist/passkeys/sign-in.resolvers.d.ts.map +1 -0
  125. package/dist/passkeys/sign-in.sdl.d.ts +16 -0
  126. package/dist/passkeys/sign-in.sdl.d.ts.map +1 -0
  127. package/dist/passkeys/types.d.ts +193 -0
  128. package/dist/passkeys/types.d.ts.map +1 -0
  129. package/dist/plugin.d.ts +59 -0
  130. package/dist/plugin.d.ts.map +1 -0
  131. package/dist/renewal.d.ts +51 -0
  132. package/dist/renewal.d.ts.map +1 -0
  133. package/dist/report.d.ts +29 -0
  134. package/dist/report.d.ts.map +1 -0
  135. package/dist/sdl.d.ts +12 -0
  136. package/dist/sdl.d.ts.map +1 -0
  137. package/dist/second-factor/index.d.ts +12 -0
  138. package/dist/second-factor/index.d.ts.map +1 -0
  139. package/dist/second-factor/resolvers/deps.d.ts +39 -0
  140. package/dist/second-factor/resolvers/deps.d.ts.map +1 -0
  141. package/dist/second-factor/resolvers/index.d.ts +39 -0
  142. package/dist/second-factor/resolvers/index.d.ts.map +1 -0
  143. package/dist/second-factor/resolvers/sign-in.d.ts +10 -0
  144. package/dist/second-factor/resolvers/sign-in.d.ts.map +1 -0
  145. package/dist/second-factor/resolvers/status.d.ts +10 -0
  146. package/dist/second-factor/resolvers/status.d.ts.map +1 -0
  147. package/dist/second-factor/resolvers/step-up.d.ts +16 -0
  148. package/dist/second-factor/resolvers/step-up.d.ts.map +1 -0
  149. package/dist/second-factor/resolvers/writes.d.ts +19 -0
  150. package/dist/second-factor/resolvers/writes.d.ts.map +1 -0
  151. package/dist/second-factor/sdl.d.ts +14 -0
  152. package/dist/second-factor/sdl.d.ts.map +1 -0
  153. package/dist/second-factor/shape.d.ts +18 -0
  154. package/dist/second-factor/shape.d.ts.map +1 -0
  155. package/dist/second-factor/types/index.d.ts +5 -0
  156. package/dist/second-factor/types/index.d.ts.map +1 -0
  157. package/dist/second-factor/types/options.d.ts +61 -0
  158. package/dist/second-factor/types/options.d.ts.map +1 -0
  159. package/dist/second-factor/types/out.d.ts +84 -0
  160. package/dist/second-factor/types/out.d.ts.map +1 -0
  161. package/dist/second-factor/types/surface.d.ts +89 -0
  162. package/dist/second-factor/types/surface.d.ts.map +1 -0
  163. package/dist/social/index.d.ts +10 -0
  164. package/dist/social/index.d.ts.map +1 -0
  165. package/dist/social/resolvers.d.ts +25 -0
  166. package/dist/social/resolvers.d.ts.map +1 -0
  167. package/dist/social/sdl.d.ts +13 -0
  168. package/dist/social/sdl.d.ts.map +1 -0
  169. package/dist/social/shape.d.ts +11 -0
  170. package/dist/social/shape.d.ts.map +1 -0
  171. package/dist/social/types.d.ts +160 -0
  172. package/dist/social/types.d.ts.map +1 -0
  173. package/dist/surface/api.d.ts +16 -0
  174. package/dist/surface/api.d.ts.map +1 -0
  175. package/dist/surface/request.d.ts +10 -0
  176. package/dist/surface/request.d.ts.map +1 -0
  177. package/dist/surface/signed-in.d.ts +30 -0
  178. package/dist/surface/signed-in.d.ts.map +1 -0
  179. package/dist/types.d.ts +117 -0
  180. package/dist/types.d.ts.map +1 -0
  181. package/dist/wiring.d.ts +56 -0
  182. package/dist/wiring.d.ts.map +1 -0
  183. package/docs/README.md +26 -0
  184. package/docs/guide/api-keys.md +365 -0
  185. package/docs/guide/avatars.md +129 -0
  186. package/docs/guide/context.md +371 -0
  187. package/docs/guide/directives.md +371 -0
  188. package/docs/guide/errors.md +318 -0
  189. package/docs/guide/federation.md +71 -0
  190. package/docs/guide/invitations.md +269 -0
  191. package/docs/guide/passkeys.md +207 -0
  192. package/docs/guide/second-factor.md +238 -0
  193. package/docs/guide/social.md +190 -0
  194. package/docs/guide/step-up.md +208 -0
  195. package/docs/guide/subscriptions.md +255 -0
  196. package/docs/guide/telemetry.md +45 -0
  197. package/docs/roadmap.md +124 -0
  198. package/docs/troubleshooting.md +1265 -0
  199. package/graphql/janus-api-keys.graphqls +237 -0
  200. package/graphql/janus-avatar.graphqls +19 -0
  201. package/graphql/janus-invitations.graphqls +280 -0
  202. package/graphql/janus-passkey-sign-in.graphqls +40 -0
  203. package/graphql/janus-passkeys.graphqls +134 -0
  204. package/graphql/janus-second-factor.graphqls +199 -0
  205. package/graphql/janus-social.graphqls +155 -0
  206. package/graphql/janus.graphqls +44 -0
  207. package/package.json +80 -5
@@ -0,0 +1,371 @@
1
+ # The context
2
+
3
+ This page is for everything a resolver reads from `@softistx/janus`: the user and
4
+ the session on `ctx.janus`, the two helpers, and the types that make `ctx`
5
+ precise. For the directives that guard a field or a type, see
6
+ [directives](directives.md); for what a client receives when a request is
7
+ refused, see [errors](errors.md).
8
+
9
+ ## Wiring
10
+
11
+ ```ts
12
+ import { janusMaskError, janusTypeDefs, useJanus } from '@softistx/janus-graphql';
13
+ import { createSchema, createYoga } from 'graphql-yoga';
14
+
15
+ export const yoga = createYoga({
16
+ schema: createSchema({ typeDefs: [janusTypeDefs, typeDefs], resolvers }),
17
+ plugins: [useJanus({ auth, access })],
18
+ maskedErrors: { maskError: janusMaskError() },
19
+ });
20
+ ```
21
+
22
+ `useJanus()` does two things, and nothing else:
23
+
24
+ - **Every request's context gets `ctx.janus`**, built from `context.request`,
25
+ the `Request` Yoga puts there — or, for an operation over graphql-ws,
26
+ from the credential of the connection `janusConnection().onConnect`
27
+ accepted, found through `ctx.extra`
28
+ ([subscriptions over graphql-ws](subscriptions.md)).
29
+ - **Every schema the server is given has its directives applied**, once, by
30
+ `applyJanusDirectives()`. A schema set later — a gateway reloading its
31
+ supergraph — is applied too. The schema it made is remembered, so envelop
32
+ calling the hook again with it does not loop.
33
+
34
+ `janusTypeDefs` must be among the type definitions: without it, the schema
35
+ does not build, since `@authenticated`, `@fresh` and `@permission` are not
36
+ declared.
37
+
38
+ | Option | What it does |
39
+ | --- | --- |
40
+ | `auth` | What `janus()` answered. Required |
41
+ | `access` | What `permissions()` answered: `ctx.janus.access`, what `can()` and `@permission` ask. Optional — and required once the schema uses `@permission` |
42
+ | `type` | A user type: a user of any other type is anonymous on this server, as `auth.authenticate(request, { type })` answers |
43
+ | `clock` | What `@fresh` and `requireFresh()` read the time from: the clock given to `janus()`, when it is not the system's — `fixedClock` in a spec. Absent, the system's |
44
+ | `loaders` | Per object type, `(id, ctx) => object \| null`: the object `@permission` checks when it reads an id alone — from `args`, or a parent field other than `id`. Required for a type with a `fromField` — see [directives](directives.md#reading-the-id) |
45
+ | `conditions` | Per object type, `(object, ctx) => its when()s' ctx`: what `@permission` passes as `{ ctx }` — see [directives](directives.md#conditions) |
46
+
47
+ ## `ctx.janus`
48
+
49
+ ```ts
50
+ import type { JanusContext } from '@softistx/janus-graphql';
51
+ import type { YogaInitialContext } from 'graphql-yoga';
52
+
53
+ type Context = YogaInitialContext & JanusContext<typeof auth, typeof access>;
54
+
55
+ const resolvers = {
56
+ Query: {
57
+ greeting: async (_: unknown, __: unknown, ctx: Context) => {
58
+ const user = await ctx.janus.user(); // User<'patient', …> | User<'staff', …> | null
59
+ return user === null ? 'Hello' : `Hello, ${user.type}`;
60
+ },
61
+ expires: async (_: unknown, __: unknown, ctx: Context) =>
62
+ (await ctx.janus.session())?.expiresAt.toISOString() ?? null,
63
+ },
64
+ };
65
+ ```
66
+
67
+ | Member | What it answers |
68
+ | --- | --- |
69
+ | `user()` | The user the request belongs to, as a union narrowed by `user.type`, or `null` for an anonymous request |
70
+ | `session()` | The session it presented, or `null` |
71
+ | `access` | The `permissions()` instance, when `useJanus()` was given one |
72
+
73
+ **Lazy, and once per request.** `auth.authenticate(request)` runs the first
74
+ time `user()` or `session()` is asked, and both share its answer: a query
75
+ whose fields ask ten times costs one store call, and a query that asks
76
+ nothing — an introspection, a field no directive guards — costs none.
77
+
78
+ **An outage is not anonymous.** When a store cannot answer, `user()` rejects
79
+ with `STORE_FAILED` rather than answering `null`, and the client receives
80
+ `SERVICE_UNAVAILABLE`, 503 — see [errors](errors.md).
81
+
82
+ `authenticate` reads the request as it does anywhere: `Authorization:
83
+ Bearer`, then `X-Session-Token`, then the cookie. It renews a sliding session
84
+ in passing, and **`useJanus()` sends the renewed cookie back**, as
85
+ `@softistx/janus-hono`'s `session()` does:
86
+
87
+ | The request | The response |
88
+ | --- | --- |
89
+ | Presented the session cookie, and `authenticate` renewed it | `Set-Cookie` with the session's new `Expires` — once, for a batch of operations too |
90
+ | Presented the cookie, not yet due for renewal | No `Set-Cookie` |
91
+ | `Authorization: Bearer` or `X-Session-Token` | No `Set-Cookie`, renewed or not: the client never asked for a cookie, and reads the new expiry from `session().expiresAt` |
92
+ | Anonymous, or no field asked `user()` or `session()` | No `Set-Cookie`, and no store call |
93
+ | The store failed | No `Set-Cookie`: the response is the 503 |
94
+ | A mutation of yours already set the session cookie — a sign-in, a sign-out | Yours: the renewal never overwrites it |
95
+
96
+ The cookie is `auth.cookie.serialize(token, session)`, under the attributes
97
+ `janus({ cookie })` resolved. It is set in Yoga's `onResponse` hook:
98
+
99
+ - **A server on envelop alone** never calls it, and sends no renewed cookie.
100
+ - **An operation over graphql-ws** has no response per operation, so none is
101
+ sent: the store holds the renewed session, but the browser keeps its
102
+ cookie's old expiry. That renewal is spent — an HTTP query right after
103
+ finds the session not yet due, and sends nothing — so the cookie is sent
104
+ again by the next renewal over HTTP, a `renewAfter` later. A client whose
105
+ only traffic is the WebSocket for longer than the lifespan minus
106
+ `renewAfter` should renew through an HTTP route of yours. See
107
+ [subscriptions](subscriptions.md).
108
+ - **A session first read after the response started** — by a field under
109
+ `@defer`, when no field of the initial payload read it — is not sent: the
110
+ headers had already gone.
111
+ - **An `auth` of your own** — a wrapper that counts or caches — must pass on
112
+ `cookie: auth.cookie` beside `authenticate` and `types`; without it, no
113
+ renewed cookie is sent.
114
+
115
+ `JanusContext<typeof auth, typeof access, Type>` takes the third argument
116
+ when `useJanus({ type })` narrows the server:
117
+
118
+ ```ts
119
+ type StaffContext = YogaInitialContext & JanusContext<typeof auth, typeof access, 'staff'>;
120
+ // (await ctx.janus.user())?.username — a staff member's field, typed
121
+ ```
122
+
123
+ Without `access`, write `JanusContext<typeof auth>`: `ctx.janus.access` is
124
+ then absent from the type, as it is from the context.
125
+
126
+ ## Several issuers, one server
127
+
128
+ `useJanus({ auth })` and `janusConnection({ auth })` take, besides a
129
+ `janus()` instance, a function of the request's context answering the
130
+ instance that serves it. The context is the one the request's `ctx` is built
131
+ from: `ctx.request` over HTTP; over graphql-ws, `ctx.extra` (with the upgrade
132
+ request in `ctx.extra.request` on `ws`) and `ctx.connectionParams`.
133
+
134
+ ```ts
135
+ import { createYoga } from 'graphql-yoga';
136
+ import { useJanus } from '@softistx/janus-graphql';
137
+
138
+ const issuers = { 'a.example': authA, 'b.example': authB };
139
+
140
+ const yoga = createYoga({
141
+ schema,
142
+ plugins: [
143
+ useJanus({
144
+ auth: (ctx) => issuers[new URL(ctx.request?.url ?? 'http://x').host],
145
+ types: ['patient', 'staff'],
146
+ access,
147
+ }),
148
+ ],
149
+ });
150
+ ```
151
+
152
+ - **Lazy and once.** The function runs the first time `user()` or
153
+ `session()` is asked, once per context (one per operation of a batch), and
154
+ its instance is the one that authenticates. A request that asks neither
155
+ never calls it.
156
+ - **Isolated.** Each instance has its own store: a session token issued by A
157
+ is unknown to B, so through B the request is anonymous (`@authenticated`
158
+ answers `UNAUTHENTICATED`).
159
+ - **`types`.** Directives are checked when the schema is built, before any
160
+ request, so there is no instance to read `auth.types` from. `types` names
161
+ the user types `@authenticated(type: [...])` may use and is checked like
162
+ `auth.types`; left out, no `type:` is checked, and a name no instance knows
163
+ simply admits nobody. It is read only when `auth` is a function.
164
+ - **Renewal.** A renewed session cookie is sent again with the cookie
165
+ definition of the instance that renewed it.
166
+ - **One answer or an error.** Answering `null`/`undefined` is a `TypeError`
167
+ (`the auth resolver answered no janus() instance for this request`), and
168
+ so is something that is not what `janus()` answered. A function that
169
+ throws or rejects keeps its own error: throw a `GraphQLError` or a
170
+ `JanusError` to refuse a request with the status you want.
171
+ - **Over graphql-ws,** `janusConnection({ auth })` calls the function in
172
+ `onConnect` (a `null` answer rejects: the socket closes `4500`) and
173
+ `context()` again for each operation; both get the same connection, so
174
+ they must pick the same instance. `useJanus()`'s function also runs for
175
+ those operations, with the context Yoga built from the connection.
176
+ - **Still fixed.** `access` (and its `loaders` and `conditions`) and the
177
+ opt-in resolvers (`socialResolvers`, `passkeyResolvers`, …) take one
178
+ instance: a permissions model per issuer is not served by this option.
179
+
180
+ ## API keys: `useJanus({ apiKey: true })`
181
+
182
+ Opt-in, and off by default. A key is read from `Authorization: Bearer` only, never from the cookie or `X-Session-Token`. With `janus({ apiKeys })` wired on `auth`, pass
183
+ `apiKey: true` and a request that presents a key (`Authorization: Bearer
184
+ sl_…`) is accepted as its owner:
185
+
186
+ ```ts
187
+ useJanus({ auth, access, apiKey: true });
188
+
189
+ type Context = YogaInitialContext &
190
+ JanusContext<typeof auth, typeof access, UserType, true>; // the 4th argument
191
+
192
+ const principal = await ctx.janus.principal(); // Principal<User> | null — narrow on `via`
193
+ if (principal?.via === 'apiKey') principal.apiKey.id;
194
+ await ctx.janus.apiKey(); // the ApiKey, or null for a session or no one
195
+ ```
196
+
197
+ | With `apiKey: true` | |
198
+ | --- | --- |
199
+ | `user()` | The key's user, as for a session: `@authenticated` and `@permission` hold for a key |
200
+ | `session()` | `null` for a key — it has no session. A resolver that reads `session()` must expect it |
201
+ | `principal()`, `apiKey()` | Added; share `user()`'s one lazy `authenticate` |
202
+ | `@fresh`, `requireFresh()` | Refuse a key with `STEP_UP_REQUIRED`, 403 (`reason: 'apiKey'` in your logs): a step-up cannot make a key fresh, so the client needs a signed-in session |
203
+
204
+ Without the option nothing changes: a key-shaped bearer is anonymous,
205
+ `session()` is never `null` for a signed-in user, and `principal()` and
206
+ `apiKey()` are absent from the context and the type. A key is not renewed,
207
+ so it never sends a cookie. Over graphql-ws, `janusConnection().onConnect`
208
+ still accepts a session only; keys are an HTTP matter.
209
+
210
+ ## A sign-in mutation and the device cookie
211
+
212
+ `@softistx/janus-graphql` runs no sign-in: a mutation of yours calls
213
+ `auth.signIn`. With `janus({ devices })`, that call takes the **device
214
+ token** the browser holds, as `device`, and answers a `deviceToken` to keep
215
+ in a long-lived cookie of its own — so a sign-in from a device the user had
216
+ not signed in from is told apart
217
+ ([`@softistx/janus`'s devices guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/devices.md)).
218
+ `deviceOf(ctx.request)` reads that cookie and `sendDevice(ctx.request, token)`
219
+ sets it back, on the response Yoga sends, through `useJanus()` — the same way
220
+ the session cookie of [`socialResolvers`](../../README.md#api) is set, so it
221
+ works in any resolver and needs no cookie plugin. They are the names, defaults
222
+ and options of `@softistx/janus-hono`'s `deviceOf` and `sendDevice`.
223
+
224
+ ```ts
225
+ import {
226
+ deviceOf,
227
+ janusMaskError,
228
+ janusTypeDefs,
229
+ sendDevice,
230
+ useJanus,
231
+ } from '@softistx/janus-graphql';
232
+ import { createSchema, createYoga } from 'graphql-yoga';
233
+
234
+ const resolvers = {
235
+ Mutation: {
236
+ signIn: async (_: unknown, args: { email: string; password: string }, ctx: Context) => {
237
+ const result = await auth.signIn(args, { device: deviceOf(ctx.request) });
238
+ if (result.status === 'secondFactor') return { challenge: result.challenge };
239
+ // …set the session cookie from result.token, as your sign-in already does
240
+ if (result.deviceToken !== null) sendDevice(ctx.request, result.deviceToken);
241
+ return { userId: result.user.id, newDevice: result.newDevice };
242
+ },
243
+ },
244
+ };
245
+
246
+ export const yoga = createYoga({
247
+ schema: createSchema({ typeDefs: [janusTypeDefs, typeDefs], resolvers }),
248
+ plugins: [useJanus({ auth, access })],
249
+ maskedErrors: { maskError: janusMaskError() },
250
+ });
251
+ ```
252
+
253
+ `DeviceCookieOptions` — `name` (`'janus-device'`), `domain`, `path` (`'/'`),
254
+ `sameSite` (`'Lax'`), `secure` (`true`) and `maxAge` in seconds (four hundred
255
+ days, the longest a browser keeps a cookie) — is the same object for both
256
+ helpers: give `deviceOf` and `sendDevice` the same one. The cookie is always
257
+ `HttpOnly`. `deviceOf` answers `null` for a missing or empty cookie. `sendDevice` throws a `RangeError` for a `maxAge` outside 0 to 34560000, and a `TypeError` for a name, `__Host-`/`__Secure-` prefix or attribute a browser would refuse ([troubleshooting](../troubleshooting.md#rangeerror-devicecookie-maxage-must-be-a-number-of-seconds-from-0-to-34560000-400-days-got-)).
258
+
259
+ `sendDevice` needs `useJanus()`'s `onResponse` to run, so it sets the cookie
260
+ over HTTP through Yoga only. Over graphql-ws the context has no `request`,
261
+ and both helpers throw a `TypeError` saying so — see
262
+ [troubleshooting](../troubleshooting.md#typeerror-deviceof-the-graphql-context-has-no-request--).
263
+
264
+ - **`null`, never `undefined`.** `deviceOf` answers `null` for a missing
265
+ cookie; `undefined` means *not tracked*, and that browser would never be
266
+ given a token, nor reported. If you read the cookie yourself, write
267
+ `token ?? null`.
268
+ - **Give the device again to the second factor's mutation.** With an active
269
+ second factor, `signIn` answers a challenge that carries no device:
270
+ `auth.secondFactor.confirm(challenge, code, { device: deviceOf(ctx.request) })`, and
271
+ the same for `recover`, `signInCode.confirm` and `magicLink.confirm`.
272
+ - **A cookie of its own, apart from the session's**, `HttpOnly` and
273
+ `Secure`, and left in place by a sign-out: the device stays known. It
274
+ holds one user's token — see
275
+ [devices](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/devices.md#keeping-the-token-the-cookie).
276
+
277
+ A bearer client has no cookie jar: answer it the `deviceToken` in the
278
+ mutation's result, and take it back as an argument of the next sign-in.
279
+
280
+ ## Directives
281
+
282
+ `@authenticated`, `@fresh` and `@permission` guard a field, a type or an interface
283
+ before its resolver runs: see [directives](directives.md). This page covers
284
+ what a resolver checks itself, where a directive does not fit.
285
+
286
+ ## `requireUser(ctx, { type? })`
287
+
288
+ ```ts
289
+ import { requireUser } from '@softistx/janus-graphql';
290
+
291
+ const resolvers = {
292
+ Mutation: {
293
+ admitPatient: async (_: unknown, args: { id: string }, ctx: Context) => {
294
+ const staff = await requireUser(ctx, { type: 'staff' });
295
+ return wards.admit(args.id, { by: staff.username }); // typed: a staff member
296
+ },
297
+ },
298
+ };
299
+ ```
300
+
301
+ The signed-in user, narrowed to `type` — or a denial: `UNAUTHENTICATED` for
302
+ an anonymous request, `FORBIDDEN` for a user of another type. `type` takes
303
+ one user type or a list, `{ type: ['staff', 'patient'] }`, and the answer is
304
+ typed as the union of them. Without `type`, any signed-in user. An empty list
305
+ is refused — by the compiler, and with a `TypeError` for a list built at run
306
+ time — since no user could pass it.
307
+
308
+ Use it where a directive does not fit: a mutation that must know the user
309
+ anyway, or a type that depends on the arguments.
310
+
311
+ ## `requireFresh(ctx, maxAge)`
312
+
313
+ ```ts
314
+ import { requireFresh } from '@softistx/janus-graphql';
315
+
316
+ const resolvers = {
317
+ Mutation: {
318
+ transfer: async (_: unknown, { amount }: { amount: number }, ctx: Context) => {
319
+ if (amount > 1_000) await requireFresh(ctx, '5m');
320
+ return payments.transfer(ctx, amount);
321
+ },
322
+ },
323
+ };
324
+ ```
325
+
326
+ The request's session, once it proved who it is less than `maxAge` ago —
327
+ signed in, or confirmed since by `auth.stepUp.confirm` — or a denial:
328
+ `UNAUTHENTICATED` for an anonymous request, `STEP_UP_REQUIRED`, 403, for an
329
+ older session or, under `apiKey: true`, for an API key. A store that cannot answer is `SERVICE_UNAVAILABLE`. It is
330
+ `@fresh` in a resolver, for a rule that depends on the arguments, on
331
+ `useJanus({ clock })`'s clock.
332
+
333
+ `maxAge` is a duration **with its unit** — `'5m'`, `'300s'`, `'1h'` — and
334
+ never a bare number: `@softistx/janus` reads a number as milliseconds, where
335
+ `@fresh(maxAge: 300)` reads seconds, so the compiler refuses one and the call
336
+ throws a `TypeError` for one built at run time. What the client does next is
337
+ in [the step-up over GraphQL](step-up.md).
338
+
339
+ ## `can(ctx, permission, object, options?)`
340
+
341
+ ```ts
342
+ import { can } from '@softistx/janus-graphql';
343
+
344
+ const resolvers = {
345
+ Query: {
346
+ record: async (_: unknown, { id }: { id: string }, ctx: Context) => {
347
+ const record = await records.find(id);
348
+ if (record === null) return null;
349
+ return (await can(ctx, 'view', { type: 'record', ...record })) ? record : null;
350
+ },
351
+ },
352
+ };
353
+ ```
354
+
355
+ `access.can` for the request's user, **typed as `access.can` is**: the
356
+ permission must be one the object's type declares, the object must carry
357
+ every field its `fromField`s read, and `{ ctx }` is required exactly when the
358
+ permission reaches a condition. An anonymous request answers `false`, with no
359
+ store call. A store that cannot answer is `SERVICE_UNAVAILABLE`, never
360
+ `false`.
361
+
362
+ **It shares the request's checks with `@permission`.** A question a directive
363
+ already asked in this request — the same object, permission and user — is
364
+ answered from that check, and two asked at once share one; a check with
365
+ `{ ctx }` is always asked. In a subscription, whose one request lasts the
366
+ whole stream, call `ctx.janus.access.can` instead, so a `revoke()` is seen. See
367
+ [one check per question](directives.md#one-check-per-question-per-request).
368
+
369
+ It needs `useJanus({ access })`: without it, `can(ctx, …)` does not compile,
370
+ and a context built by hand without `access` throws
371
+ `TypeError: can(): ctx.janus.access is not set — pass { access } to useJanus()`.