@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,255 @@
1
+ # Subscriptions over graphql-ws
2
+
3
+ A subscription over server-sent events is an HTTP request like any other:
4
+ `useJanus()` authenticates it from its headers, and nothing more is needed.
5
+ Over a WebSocket, every operation travels over one socket, opened once:
6
+ `janusConnection()` authenticates that socket, with
7
+ [graphql-ws](https://github.com/enisdenjo/graphql-ws), the library Yoga
8
+ recommends, so the directives hold on it unchanged.
9
+
10
+ ## Install
11
+
12
+ `graphql-ws` is an **optional** peer: install it only when you serve
13
+ subscriptions over a WebSocket.
14
+
15
+ ```sh
16
+ bun add graphql-ws ws
17
+ ```
18
+
19
+ Its range, `^6.0.0`, and the `graphql` 17 note are in the
20
+ [README's Install](../../README.md#install).
21
+
22
+ ## Wiring, with Yoga
23
+
24
+ This is Yoga's recommended graphql-ws setup, with one line added:
25
+ `onConnect`.
26
+
27
+ ```ts
28
+ import { createServer } from 'node:http';
29
+ import { janusConnection, janusMaskError, janusTypeDefs, useJanus } from '@softistx/janus-graphql';
30
+ import { useServer } from 'graphql-ws/use/ws';
31
+ import { createSchema, createYoga } from 'graphql-yoga';
32
+ import { WebSocketServer } from 'ws';
33
+ import { access } from './access'; // what permissions() answered
34
+ import { auth } from './auth'; // what janus() answered
35
+
36
+ const yoga = createYoga({
37
+ schema: createSchema({ typeDefs: [janusTypeDefs, typeDefs], resolvers }),
38
+ plugins: [useJanus({ auth, access })],
39
+ maskedErrors: { maskError: janusMaskError() },
40
+ });
41
+
42
+ const server = createServer(yoga);
43
+ const wsServer = new WebSocketServer({ server, path: yoga.graphqlEndpoint });
44
+
45
+ useServer(
46
+ {
47
+ onConnect: janusConnection({ auth }).onConnect, // refuses a connection with no valid session
48
+ execute: (args: any) => args.rootValue.execute(args),
49
+ subscribe: (args: any) => args.rootValue.subscribe(args),
50
+ onSubscribe: async (ctx, _id, params) => {
51
+ const { schema, execute, subscribe, contextFactory, parse, validate } = yoga.getEnveloped({
52
+ ...ctx, // carries ctx.extra, where useJanus() finds the connection
53
+ req: ctx.extra.request,
54
+ socket: ctx.extra.socket,
55
+ params,
56
+ });
57
+ const args = {
58
+ schema,
59
+ operationName: params.operationName,
60
+ document: parse(params.query),
61
+ variableValues: params.variables,
62
+ contextValue: await contextFactory(),
63
+ rootValue: { execute, subscribe },
64
+ };
65
+ const errors = validate(args.schema, args.document);
66
+ if (errors.length) return errors;
67
+ return args;
68
+ },
69
+ },
70
+ wsServer,
71
+ );
72
+
73
+ server.listen(4000);
74
+ ```
75
+
76
+ `useJanus()` needs nothing new. When it builds the context of an operation
77
+ with no `request`, it looks for the connection the operation came from —
78
+ by `ctx.extra`, which the `...ctx` spread carries — and authenticates the
79
+ credential that connection presented. **Keep the spread**: a context built
80
+ without `ctx.extra` has no connection to find, and its first guarded field
81
+ throws [`the GraphQL context has no request to authenticate`](../troubleshooting.md#typeerror--the-graphql-context-has-no-request-to-authenticate).
82
+
83
+ ## How the session travels
84
+
85
+ `onConnect` reads one credential per connection, in this order:
86
+
87
+ 1. **`connectionParams.authorization`** — for a client that is not a
88
+ browser, or a browser that holds a bearer token:
89
+
90
+ ```ts
91
+ import { createClient } from 'graphql-ws';
92
+
93
+ const client = createClient({
94
+ url: 'wss://api.example.com/graphql',
95
+ connectionParams: async () => ({ authorization: `Bearer ${await tokens.current()}` }),
96
+ });
97
+ ```
98
+
99
+ The key is `authorization`, lower-case, and its value a string — the
100
+ same `Bearer <token>` an HTTP request sends. A value that is not a
101
+ string refuses the connection; a string of another scheme (`Basic …`)
102
+ is not a session credential, as in `@softistx/janus`, and the upgrade
103
+ request is read instead.
104
+
105
+ 2. **The upgrade request**, read as `auth.authenticate` reads any request:
106
+ `Authorization: Bearer`, then `X-Session-Token`, then the session
107
+ cookie. A browser sends its cookies with the upgrade, so a signed-in
108
+ browser needs no `connectionParams` at all — provided the WebSocket goes
109
+ to the origin that set the cookie, or to one its `SameSite` admits.
110
+
111
+ **The first credential present wins, not the first valid one**, as in
112
+ `@softistx/janus`: a lapsed token in `connectionParams` beside a live cookie is
113
+ refused, rather than rescued in silence. Fix the client's token.
114
+
115
+ `type` restricts who may connect:
116
+
117
+ ```ts
118
+ janusConnection({ auth, type: 'staff' }); // a patient's session is refused
119
+ ```
120
+
121
+ ## What a client sees
122
+
123
+ | What happened | The client sees |
124
+ | --- | --- |
125
+ | 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` |
126
+ | The sessions store could not answer at connect | The socket closed **`4500`**, by `graphql-ws/use/ws`, which also logs the error — **never `4403`** |
127
+ | Accepted | `connection_ack`, then operations as over HTTP |
128
+
129
+ graphql-ws's client treats `4403` as retryable — a `connectionParams`
130
+ function asked again can present a fresh token — and `4500` as fatal. Set
131
+ `retryAttempts` and `shouldRetry` on the client to change that. (`4401` is
132
+ the protocol's answer to an operation sent before the acknowledgement;
133
+ `onConnect` cannot choose it.)
134
+
135
+ ## Each operation
136
+
137
+ Each operation on an accepted connection gets **a `ctx.janus` of its own**,
138
+ built by `useJanus()` as for an HTTP request, and authenticated again from
139
+ the connection's credential the first time a field asks — once per
140
+ operation, never per event:
141
+
142
+ - `@authenticated` and `@fresh` on a subscription field are checked **when
143
+ it subscribes**. A denial answers the operation with its `GraphQLError` —
144
+ `UNAUTHENTICATED`, `FORBIDDEN`, `STEP_UP_REQUIRED` — and the source stream
145
+ never starts; the connection stays open.
146
+ - `@permission` on a subscription field is asked **again on every event**,
147
+ bypassing the request's memo, so a `revoke()` stops the stream at its
148
+ next event with `NOT_FOUND` (or `FORBIDDEN`).
149
+ - A directive on the payload's type or its fields is checked on every
150
+ event, as any field.
151
+ - An outage at subscribe, or on an event, answers `SERVICE_UNAVAILABLE` —
152
+ never a denial.
153
+
154
+ ## A session revoked while connected
155
+
156
+ `auth.signOut` or `signOutEverywhere` while a socket is open:
157
+
158
+ - **the stream already running keeps its events coming.** Its user was
159
+ authenticated once, when it subscribed, and each event's
160
+ `@authenticated` reads that answer — authenticating on every event would
161
+ cost a sessions-store read per event per subscriber;
162
+ - **the next operation on the same connection is refused**
163
+ `UNAUTHENTICATED`, since it authenticates again;
164
+ - **a reconnection is refused `4403`**.
165
+
166
+ To cut a revoked session's streams at once, close its sockets yourself.
167
+ graphql-ws hands every callback the transport's socket as
168
+ `ctx.extra.socket`: a server that keeps its open sockets by user can close
169
+ them with `4403` when it revokes, and a client that reconnects is then
170
+ refused.
171
+
172
+ ```ts
173
+ const connection = janusConnection({ auth });
174
+
175
+ useServer({
176
+ onConnect: async (ctx) => {
177
+ const accepted = await connection.onConnect(ctx);
178
+ if (accepted) track(ctx.extra.socket, ctx); // your own bookkeeping, keyed as you revoke
179
+ return accepted;
180
+ },
181
+ onClose: (ctx) => untrack(ctx.extra.socket),
182
+ // … Yoga's recipe …
183
+ }, wsServer);
184
+ ```
185
+
186
+ A permission revoked while connected needs none of this: `@permission` sees
187
+ it at the next event.
188
+
189
+ ## Without Yoga
190
+
191
+ A server that runs graphql-ws alone passes `context` as well, and applies
192
+ the directives itself:
193
+
194
+ ```ts
195
+ import { applyJanusDirectives, janusConnection } from '@softistx/janus-graphql';
196
+ import { useServer } from 'graphql-ws/use/ws';
197
+ import { WebSocketServer } from 'ws';
198
+ import { schema } from './schema'; // your executable schema, with janusTypeDefs
199
+
200
+ const wsServer = new WebSocketServer({ port: 4000, path: '/graphql' });
201
+ const connection = janusConnection({ auth, access, clock }); // clock: the one given to janus()
202
+
203
+ useServer(
204
+ {
205
+ schema: applyJanusDirectives(schema, { auth, access }),
206
+ onConnect: connection.onConnect,
207
+ context: connection.context, // { janus } for each operation
208
+ },
209
+ wsServer,
210
+ );
211
+ ```
212
+
213
+ With Yoga, leave `context` out: Yoga's recipe builds the context itself,
214
+ and `useJanus()`'s `access` and `clock` are the ones that apply.
215
+
216
+ ## On Bun, or another transport
217
+
218
+ `onConnect` reads the upgrade request from `ctx.extra.request`, where
219
+ `graphql-ws/use/ws` and `graphql-ws/use/@fastify/websocket` put it.
220
+ `graphql-ws/use/bun`'s `extra` is `{ socket }` alone: pass the request as
221
+ the socket's `data` when you upgrade, and tell `janusConnection` where it is.
222
+
223
+ ```ts
224
+ import type { ServerWebSocket } from 'bun';
225
+ import { makeHandler } from 'graphql-ws/use/bun';
226
+
227
+ type Upgraded = ServerWebSocket<{ readonly request: Request }>;
228
+
229
+ const connection = janusConnection({
230
+ auth,
231
+ upgrade: (ctx: { readonly extra: { readonly socket: Upgraded } }) => ctx.extra.socket.data.request,
232
+ });
233
+
234
+ Bun.serve({
235
+ fetch: (request, server) =>
236
+ server.upgrade(request, { data: { request } }) ? undefined : yoga.fetch(request, server),
237
+ websocket: makeHandler({ onConnect: connection.onConnect, /* … Yoga's recipe … */ }),
238
+ });
239
+ ```
240
+
241
+ Without `upgrade` on Bun, only `connectionParams` authenticates: a browser's
242
+ cookie is never read.
243
+
244
+ ## What is not covered
245
+
246
+ - **An anonymous connection.** `onConnect` refuses every connection it
247
+ cannot authenticate; serve anonymous clients over server-sent events. An
248
+ operation on a connection no `onConnect` accepted has no credential: its
249
+ first guarded field, or `ctx.janus.user()`, throws a `TypeError`, a 500.
250
+ - **The renewed session cookie.** A WebSocket has no response to set one
251
+ on. An operation that renews the session renews it in the store, and the
252
+ browser's cookie keeps its old expiry until the next renewal over HTTP,
253
+ which `useJanus()` sends — a `renewAfter` later. A browser whose only
254
+ traffic is the WebSocket should renew through an HTTP route of yours:
255
+ [the context guide](context.md#ctxjanus) has the detail.
@@ -0,0 +1,45 @@
1
+ # Telemetry
2
+
3
+ This page is for tracing what the GraphQL server asks of `@softistx/janus`: a span
4
+ per authentication and per permission check, with
5
+ [`@softistx/janus-telemetry`](https://github.com/softistx/nxgt-janus/tree/develop/packages/janus-telemetry).
6
+
7
+ `@softistx/janus-graphql` does not depend on it, and has nothing to configure for
8
+ it: `useJanus()` takes the instances you give it, and an instrumented
9
+ instance answers exactly as the plain one does, with the same types.
10
+
11
+ ```ts
12
+ import { janus } from '@softistx/janus';
13
+ import { permissions } from '@softistx/janus/permissions';
14
+ import { useJanus } from '@softistx/janus-graphql';
15
+ import { instrumentJanus, instrumentPermissions } from '@softistx/janus-telemetry';
16
+
17
+ export const auth = instrumentJanus(janus({ users, hasher, ...stores }));
18
+ export const access = instrumentPermissions(permissions({ model, store }));
19
+
20
+ useJanus({ auth, access, loaders, conditions });
21
+ ```
22
+
23
+ `instrumentPermissions(access)` answers a frozen copy that keeps `model`, so
24
+ `@permission` reads the model from it when the schema is built, and every
25
+ check — a directive's or `can()`'s — goes through the traced `can`.
26
+
27
+ ## What shows up
28
+
29
+ | Span | Written for |
30
+ | --- | --- |
31
+ | `janus.authenticate` | The first `ctx.janus.user()` or `ctx.janus.session()` of a request — a guarded field asks it — and never when neither is asked. Once per request |
32
+ | `janus.can` | Each **distinct** permission check of a request: `@permission`'s and `can()`'s |
33
+
34
+ The spans nest under the server span of whatever opened one — an
35
+ OpenTelemetry instrumentation of your server, or `@softistx/telemetry`'s own.
36
+
37
+ **A question answered from the request's memo writes no span.** The memo sits
38
+ between `ctx.janus` and `access.can`, so the same object, permission and user
39
+ asked twice in one request — two fields, or a directive and `can()` — is one
40
+ `janus.can`. A check with a condition's `ctx` is never remembered, and
41
+ writes one span each time.
42
+
43
+ **A loader is yours to trace.** `loaders[type](id, ctx)` runs your code; what
44
+ it asks of your database shows up as your database's instrumentation writes
45
+ it, not as a `janus.*` span.
@@ -0,0 +1,124 @@
1
+ # Roadmap
2
+
3
+ Where `@softistx/janus-graphql` is heading. A direction, not a commitment: there
4
+ are no dates here, and the version something shipped in is the only number.
5
+
6
+ ## Now
7
+
8
+ Nothing yet.
9
+
10
+ ## Next
11
+
12
+ Nothing yet.
13
+
14
+ ## Later
15
+
16
+ - **Anonymous graphql-ws connections** — `janusConnection({ anonymous:
17
+ true })`, accepting a connection with no credential so its public fields
18
+ answer and its guarded ones deny, as over HTTP.
19
+ - **Re-authenticating a subscription on each event** — an opt-in for
20
+ streams that must end the moment their session is revoked, at the cost
21
+ of a sessions-store read per event.
22
+
23
+ ## Not planned
24
+
25
+ - **Filtering a list by permission** — no directive drops the items of a list
26
+ the user may not see. Loading every item and checking each is a query that
27
+ grows with the table; ask the question the other way round with
28
+ `access.list()`, which answers the ids the user holds a permission on, and
29
+ load only those.
30
+ - **Introspection control and rate limiting** — neither is about who the user
31
+ is. Envelop and Yoga have plugins for both; this package stays out of their
32
+ way.
33
+ - **Error classes of its own** — a denial is a `GraphQLError`, and anything
34
+ else is `@softistx/janus`'s, which is why `@softistx/janus` is a required peer and
35
+ never a dependency.
36
+ - **`moduleResolution: "nodenext"`** — like `@softistx/janus`, the package
37
+ imports without extensions. Use `"moduleResolution": "bundler"`.
38
+
39
+ ## Shipped
40
+
41
+ Newest first; from the first release on, the package's CHANGELOG holds every one.
42
+
43
+ - **Second factor, per-request auth** — next release. `secondFactorResolvers({ auth })` and `secondFactorViewerFields({ auth })` accept a function of the context answering the instance that serves the request (`SecondFactorAuthSource`), as `passkeyResolvers()` and `socialResolvers()` do; no instance is `UNAUTHENTICATED`. [#914](https://github.com/softistx/nxgt-janus/issues/914)
44
+ - **Bound API key pages in one core call** — 0.28.0. `apiKeys(boundTo:)` and `revokeApiKey` use the core's `apiKeys.list(user, { bound })` and `apiKeys.get(id)` instead of reading the key history; an `auth` given to `apiKeysResolvers` needs `apiKeys.get`. [#736](https://github.com/softistx/nxgt-janus/issues/736)
45
+ - **API keys over GraphQL** — 0.27.0. The opt-in SDL `apiKeysTypeDefs` and `apiKeysResolvers({ auth, lifetimes, authorize: { create, list, revoke }, bound? })`: list a user's own keys or every key bound to an object, create one (the secret answered once, behind the step-up) and revoke one. Who may do what is `authorize`; `bound` names the object a key acts in, a workspace say. Needs `@softistx/janus` with bound API keys. [#732](https://github.com/softistx/nxgt-janus/issues/732)
46
+ - **Social sign-in, per-request auth** — 0.26.0. `socialResolvers({ auth })` accepts a function of the context answering the instance that serves the request (`SocialAuthSource`), as `passkeyResolvers()` does; no instance, or one with no `social`, is `UNAUTHENTICATED`. [#713](https://github.com/softistx/nxgt-janus/issues/713)
47
+ - **Passkey as the first factor, per-request auth** — 0.24.0. The opt-in SDL `janusPasskeySignInTypeDefs` and `passkeyResolvers({ auth, firstFactor: true })` sign a visitor in with a passkey alone (`passkeySignInOptions`, `passkeySignIn`); `passkeyResolvers({ auth })` accepts a function of the context answering the instance that serves the request. [#667](https://github.com/softistx/nxgt-janus/issues/667)
48
+ - **One server, several issuers** — 0.23.0. `useJanus({ auth })` and `janusConnection({ auth })` accept a function of the request's context answering the `janus()` instance that serves it, beside a fixed instance; `useJanus({ types })` names the user types the directives may use meanwhile. [#651](https://github.com/softistx/nxgt-janus/issues/651)
49
+ - **Invitation ref, type, order and count** — 0.18.0. `JanusInvitation` answers `ref` and `type`, `issueInvitation` takes both, `invitations` filters by `role` and `ref` and orders with `JanusInvitationOrder`, and `JanusInvitationPage.totalCount` counts the matches when selected. [#572](https://github.com/softistx/nxgt-janus/issues/572)
50
+ - **Who revoked, who resent** — 0.17.0. `JanusInvitation` gains nullable `revokedBy` and `resentBy`, and `resendInvitation` and `revokeInvitation` pass the signed-in user as `by`. [#566](https://github.com/softistx/nxgt-janus/issues/566)
51
+ - **Invitation read by id** — 0.17.0. `resendInvitation` and `revokeInvitation` read the stored invitation with the core's `invitations.get({ id, scope })` instead of paging the scope's list. [#577](https://github.com/softistx/nxgt-janus/issues/577)
52
+ - **Invitations** — 0.15.0. The opt-in SDL `janusInvitationTypeDefs` and `invitationResolvers({ auth, authorize })`: list, issue, resend and revoke a scope's invitations, preview a code, and accept it — a new invitee is signed in. Who may invite is `authorize`; where the code goes is `sendInvitation` or `answerCode`. [#547](https://github.com/softistx/nxgt-janus/issues/547)
53
+ - **Second factor (TOTP)** — 0.14.0. The opt-in SDL `janusSecondFactorTypeDefs` and `secondFactorResolvers({ auth })`: the sign-in challenge, confirm and recover, enroll, activate, regenerate the recovery codes, disable, `Viewer.secondFactor`, and the step-up with `sessionConfirmedUntil`. The freshness window, a guard before each write and the step-up mail are options. [#517](https://github.com/softistx/nxgt-janus/issues/517)
54
+ - **Passkeys** — 0.13.0. The opt-in SDL `janusPasskeyTypeDefs` and `passkeyResolvers({ auth })`: register, list, rename and remove passkeys, and answer a sign-in's second factor and a step-up with one.
55
+ - **Device cookie helpers** (0.12.0) — `deviceOf(ctx.request)` and `sendDevice(ctx.request, token)` read and set the `janus-device` cookie of a sign-in mutation, with the names, defaults and options of `@softistx/janus-hono`, and no cookie plugin to install. HTTP through Yoga only: nothing is sent over graphql-ws (they throw over graphql-ws). [#410](https://github.com/softistx/nxgt-janus/issues/410)
56
+ - **Social login** — 0.10.0. The opt-in SDL `janusSocialTypeDefs` and `socialResolvers({ auth })`: start a provider sign-in, complete it from the callback URL, and list, link or unlink accounts. A provider failure answers a fixed "Bad gateway" message. [#359](https://github.com/softistx/nxgt-janus/issues/359)
57
+ - **Moved to `@softistx` on GitHub Packages** (0.9.0) — formerly
58
+ the `@nxgt` scope on npm; same names under the new scope, published privately.
59
+
60
+ - **Account avatars, v0.7.0.** An opt-in `JanusAvatar` type
61
+ (`janusAvatarTypeDefs`, also `graphql/janus-avatar.graphqls`) for the
62
+ avatar `@softistx/janus` 0.29.0 records: `toJanusAvatar(user)` is the parent of
63
+ an `avatar: JanusAvatar` field of yours, and `avatarResolvers({ url })`
64
+ answers `updatedAt` as an ISO-8601 string and `url(size:)` as the path of
65
+ your own authenticated route — never a public URL. A `size` below 1 is
66
+ `BAD_USER_INPUT`, 400. Guard the field with `@permission` or `can()`.
67
+
68
+ - **A throttled e-mail request's `retryAfter`, v0.6.0.**
69
+ `janusGraphQLError()` answers `@softistx/janus`'s `MAIL_THROTTLED` with 429,
70
+ `retryAfter` in `extensions`, a `Retry-After` header in
71
+ `extensions.http.headers` and the message `Too many requests, retry later`.
72
+ Needs `@softistx/janus` 0.18.0.
73
+
74
+ - **A throttled sign-in's `retryAfter`, v0.5.0.** `janusGraphQLError()`
75
+ answers `@softistx/janus`'s throttled `CREDENTIALS_INVALID` with `retryAfter`
76
+ in `extensions` and a `Retry-After` header in `extensions.http.headers`,
77
+ which Yoga answers with. Needs `@softistx/janus` 0.14.0.
78
+
79
+ - **The renewed session cookie, and `report` for every outage, v0.4.0.**
80
+ Under Yoga, `useJanus()` sends a session `authenticate` renewed back as
81
+ `Set-Cookie`, so a browser keeps the new expiry without an HTTP route of
82
+ its own — only to a request that presented the session cookie, never to a
83
+ bearer token or `X-Session-Token`, and never when nothing authenticated.
84
+ `janusMaskError({ report, fallback })` hands every `JanusError` answered
85
+ 5xx to your logger, once, including the outages a directive or a helper
86
+ answers 503 on its own; a `report` that throws never changes the answer.
87
+ `janusMaskError(fallback)` still works.
88
+
89
+ - **Subscriptions over graphql-ws, `janusConnection()`, v0.3.0.** The same
90
+ `@authenticated`, `@fresh` and `@permission` on subscriptions served over
91
+ a WebSocket with graphql-ws: `onConnect` for its `useServer()`
92
+ authenticates the connection from `connectionParams.authorization` — else
93
+ from the upgrade request's headers and the browser's session cookie —
94
+ and refuses it `4403`, or rejects on an outage, closed `4500`. Each
95
+ operation's `ctx.janus` is built by `useJanus()` from that credential, in
96
+ Yoga's recommended setup, and authenticated again when it subscribes, so
97
+ a session revoked since the connection opened is refused at the next
98
+ subscribe. `context` for a server without Yoga, `upgrade` for Bun.
99
+ `graphql-ws` is an optional peer, `^6.0.0`, whose floor runs in CI.
100
+
101
+ - **`@fresh(maxAge)` and `requireFresh()`, v0.2.0.** A field, a type or an
102
+ interface only a session that proved who it is less than `maxAge` seconds
103
+ ago may resolve — signed in, or confirmed since by `auth.stepUp.confirm`:
104
+ a new e-mail or a payment method, asked again of a session that is days
105
+ old. An older session is `STEP_UP_REQUIRED`, 403, which tells the client
106
+ to ask for a step-up; checked after `@authenticated` and before any
107
+ `@permission`, and for a subscription when it subscribes.
108
+ `requireFresh(ctx, '10m')` is the same check in a resolver, and
109
+ `useJanus({ clock })` the clock both read. `@softistx/janus` 0.12's
110
+ `assertFresh` is the check.
111
+
112
+ - **The first release, v0.1.0.** GraphQL for `@softistx/janus`, as an envelop
113
+ plugin: `useJanus()` with a lazy `ctx.janus`, authenticated only when a
114
+ field asks; `@authenticated` on fields, types and interfaces, for any user
115
+ or some user types; `@permission(name, type, id, onDeny)`, reading the id
116
+ from `args.<path>` or `parent.<path>`, loading an object by id through
117
+ `loaders` and a condition's `ctx` through `conditions`, one check per
118
+ question per request, and a denial answered `NOT_FOUND` unless
119
+ `onDeny: FORBIDDEN`; `requireUser()` and `can()` for a resolver;
120
+ `janusMaskError()`, an outage as 503; and the SDL as `janusTypeDefs` and
121
+ `graphql/janus.graphqls`. What no request could pass is refused at
122
+ start-up, naming the field. The specs and the typecheck also run on the
123
+ peer floors — `graphql` 16.9.0, `@graphql-tools/utils` 10.0.0 and
124
+ `@envelop/core` 5.0.0 — in CI.