@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.
- package/LICENSE +21 -0
- package/README.md +716 -2
- package/dist/api-keys/index.d.ts +11 -0
- package/dist/api-keys/index.d.ts.map +1 -0
- package/dist/api-keys/resolvers/deps.d.ts +39 -0
- package/dist/api-keys/resolvers/deps.d.ts.map +1 -0
- package/dist/api-keys/resolvers/index.d.ts +39 -0
- package/dist/api-keys/resolvers/index.d.ts.map +1 -0
- package/dist/api-keys/resolvers/list.d.ts +16 -0
- package/dist/api-keys/resolvers/list.d.ts.map +1 -0
- package/dist/api-keys/resolvers/manage.d.ts +17 -0
- package/dist/api-keys/resolvers/manage.d.ts.map +1 -0
- package/dist/api-keys/sdl.d.ts +14 -0
- package/dist/api-keys/sdl.d.ts.map +1 -0
- package/dist/api-keys/shape.d.ts +38 -0
- package/dist/api-keys/shape.d.ts.map +1 -0
- package/dist/api-keys/types.d.ts +149 -0
- package/dist/api-keys/types.d.ts.map +1 -0
- package/dist/avatar/index.d.ts +32 -0
- package/dist/avatar/index.d.ts.map +1 -0
- package/dist/avatar/resolvers.d.ts +41 -0
- package/dist/avatar/resolvers.d.ts.map +1 -0
- package/dist/avatar/sdl.d.ts +16 -0
- package/dist/avatar/sdl.d.ts.map +1 -0
- package/dist/bad-input.d.ts +17 -0
- package/dist/bad-input.d.ts.map +1 -0
- package/dist/connection/connection.d.ts +36 -0
- package/dist/connection/connection.d.ts.map +1 -0
- package/dist/connection/credential.d.ts +34 -0
- package/dist/connection/credential.d.ts.map +1 -0
- package/dist/connection/types.d.ts +61 -0
- package/dist/connection/types.d.ts.map +1 -0
- package/dist/context/create.d.ts +32 -0
- package/dist/context/create.d.ts.map +1 -0
- package/dist/context/index.d.ts +9 -0
- package/dist/context/index.d.ts.map +1 -0
- package/dist/context/registry.d.ts +72 -0
- package/dist/context/registry.d.ts.map +1 -0
- package/dist/context/resolve.d.ts +20 -0
- package/dist/context/resolve.d.ts.map +1 -0
- package/dist/device.d.ts +28 -0
- package/dist/device.d.ts.map +1 -0
- package/dist/directives/apply.d.ts +51 -0
- package/dist/directives/apply.d.ts.map +1 -0
- package/dist/directives/guard.d.ts +22 -0
- package/dist/directives/guard.d.ts.map +1 -0
- package/dist/directives/permission/enforce.d.ts +24 -0
- package/dist/directives/permission/enforce.d.ts.map +1 -0
- package/dist/directives/permission/model.d.ts +35 -0
- package/dist/directives/permission/model.d.ts.map +1 -0
- package/dist/directives/permission/path.d.ts +31 -0
- package/dist/directives/permission/path.d.ts.map +1 -0
- package/dist/directives/permission/validate.d.ts +42 -0
- package/dist/directives/permission/validate.d.ts.map +1 -0
- package/dist/directives/read.d.ts +43 -0
- package/dist/directives/read.d.ts.map +1 -0
- package/dist/directives/validate.d.ts +39 -0
- package/dist/directives/validate.d.ts.map +1 -0
- package/dist/directives/words.d.ts +7 -0
- package/dist/directives/words.d.ts.map +1 -0
- package/dist/errors/denial.d.ts +6 -0
- package/dist/errors/denial.d.ts.map +1 -0
- package/dist/errors/index.d.ts +12 -0
- package/dist/errors/index.d.ts.map +1 -0
- package/dist/errors/janus-error.d.ts +20 -0
- package/dist/errors/janus-error.d.ts.map +1 -0
- package/dist/errors/mask.d.ts +69 -0
- package/dist/errors/mask.d.ts.map +1 -0
- package/dist/fresh.d.ts +44 -0
- package/dist/fresh.d.ts.map +1 -0
- package/dist/helpers.d.ts +56 -0
- package/dist/helpers.d.ts.map +1 -0
- package/dist/index.d.ts +86 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3393 -0
- package/dist/index.js.map +75 -0
- package/dist/invitations/index.d.ts +12 -0
- package/dist/invitations/index.d.ts.map +1 -0
- package/dist/invitations/resolvers/anonymous.d.ts +11 -0
- package/dist/invitations/resolvers/anonymous.d.ts.map +1 -0
- package/dist/invitations/resolvers/deps.d.ts +38 -0
- package/dist/invitations/resolvers/deps.d.ts.map +1 -0
- package/dist/invitations/resolvers/index.d.ts +37 -0
- package/dist/invitations/resolvers/index.d.ts.map +1 -0
- package/dist/invitations/resolvers/owner.d.ts +17 -0
- package/dist/invitations/resolvers/owner.d.ts.map +1 -0
- package/dist/invitations/sdl/accept.d.ts +7 -0
- package/dist/invitations/sdl/accept.d.ts.map +1 -0
- package/dist/invitations/sdl/index.d.ts +14 -0
- package/dist/invitations/sdl/index.d.ts.map +1 -0
- package/dist/invitations/sdl/owner.d.ts +8 -0
- package/dist/invitations/sdl/owner.d.ts.map +1 -0
- package/dist/invitations/shape.d.ts +63 -0
- package/dist/invitations/shape.d.ts.map +1 -0
- package/dist/invitations/types/index.d.ts +5 -0
- package/dist/invitations/types/index.d.ts.map +1 -0
- package/dist/invitations/types/options.d.ts +104 -0
- package/dist/invitations/types/options.d.ts.map +1 -0
- package/dist/invitations/types/out.d.ts +136 -0
- package/dist/invitations/types/out.d.ts.map +1 -0
- package/dist/invitations/types/surface.d.ts +18 -0
- package/dist/invitations/types/surface.d.ts.map +1 -0
- package/dist/map-code.d.ts +10 -0
- package/dist/map-code.d.ts.map +1 -0
- package/dist/mask-error.d.ts +18 -0
- package/dist/mask-error.d.ts.map +1 -0
- package/dist/memo.d.ts +16 -0
- package/dist/memo.d.ts.map +1 -0
- package/dist/options.d.ts +17 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/passkeys/deps.d.ts +23 -0
- package/dist/passkeys/deps.d.ts.map +1 -0
- package/dist/passkeys/first-factor.types.d.ts +38 -0
- package/dist/passkeys/first-factor.types.d.ts.map +1 -0
- package/dist/passkeys/index.d.ts +14 -0
- package/dist/passkeys/index.d.ts.map +1 -0
- package/dist/passkeys/resolvers.d.ts +23 -0
- package/dist/passkeys/resolvers.d.ts.map +1 -0
- package/dist/passkeys/sdl.d.ts +14 -0
- package/dist/passkeys/sdl.d.ts.map +1 -0
- package/dist/passkeys/shape.d.ts +14 -0
- package/dist/passkeys/shape.d.ts.map +1 -0
- package/dist/passkeys/sign-in.resolvers.d.ts +19 -0
- package/dist/passkeys/sign-in.resolvers.d.ts.map +1 -0
- package/dist/passkeys/sign-in.sdl.d.ts +16 -0
- package/dist/passkeys/sign-in.sdl.d.ts.map +1 -0
- package/dist/passkeys/types.d.ts +193 -0
- package/dist/passkeys/types.d.ts.map +1 -0
- package/dist/plugin.d.ts +59 -0
- package/dist/plugin.d.ts.map +1 -0
- package/dist/renewal.d.ts +51 -0
- package/dist/renewal.d.ts.map +1 -0
- package/dist/report.d.ts +29 -0
- package/dist/report.d.ts.map +1 -0
- package/dist/sdl.d.ts +12 -0
- package/dist/sdl.d.ts.map +1 -0
- package/dist/second-factor/index.d.ts +12 -0
- package/dist/second-factor/index.d.ts.map +1 -0
- package/dist/second-factor/resolvers/deps.d.ts +39 -0
- package/dist/second-factor/resolvers/deps.d.ts.map +1 -0
- package/dist/second-factor/resolvers/index.d.ts +39 -0
- package/dist/second-factor/resolvers/index.d.ts.map +1 -0
- package/dist/second-factor/resolvers/sign-in.d.ts +10 -0
- package/dist/second-factor/resolvers/sign-in.d.ts.map +1 -0
- package/dist/second-factor/resolvers/status.d.ts +10 -0
- package/dist/second-factor/resolvers/status.d.ts.map +1 -0
- package/dist/second-factor/resolvers/step-up.d.ts +16 -0
- package/dist/second-factor/resolvers/step-up.d.ts.map +1 -0
- package/dist/second-factor/resolvers/writes.d.ts +19 -0
- package/dist/second-factor/resolvers/writes.d.ts.map +1 -0
- package/dist/second-factor/sdl.d.ts +14 -0
- package/dist/second-factor/sdl.d.ts.map +1 -0
- package/dist/second-factor/shape.d.ts +18 -0
- package/dist/second-factor/shape.d.ts.map +1 -0
- package/dist/second-factor/types/index.d.ts +5 -0
- package/dist/second-factor/types/index.d.ts.map +1 -0
- package/dist/second-factor/types/options.d.ts +61 -0
- package/dist/second-factor/types/options.d.ts.map +1 -0
- package/dist/second-factor/types/out.d.ts +84 -0
- package/dist/second-factor/types/out.d.ts.map +1 -0
- package/dist/second-factor/types/surface.d.ts +89 -0
- package/dist/second-factor/types/surface.d.ts.map +1 -0
- package/dist/social/index.d.ts +10 -0
- package/dist/social/index.d.ts.map +1 -0
- package/dist/social/resolvers.d.ts +25 -0
- package/dist/social/resolvers.d.ts.map +1 -0
- package/dist/social/sdl.d.ts +13 -0
- package/dist/social/sdl.d.ts.map +1 -0
- package/dist/social/shape.d.ts +11 -0
- package/dist/social/shape.d.ts.map +1 -0
- package/dist/social/types.d.ts +160 -0
- package/dist/social/types.d.ts.map +1 -0
- package/dist/surface/api.d.ts +16 -0
- package/dist/surface/api.d.ts.map +1 -0
- package/dist/surface/request.d.ts +10 -0
- package/dist/surface/request.d.ts.map +1 -0
- package/dist/surface/signed-in.d.ts +30 -0
- package/dist/surface/signed-in.d.ts.map +1 -0
- package/dist/types.d.ts +117 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/wiring.d.ts +56 -0
- package/dist/wiring.d.ts.map +1 -0
- package/docs/README.md +26 -0
- package/docs/guide/api-keys.md +365 -0
- package/docs/guide/avatars.md +129 -0
- package/docs/guide/context.md +371 -0
- package/docs/guide/directives.md +371 -0
- package/docs/guide/errors.md +318 -0
- package/docs/guide/federation.md +71 -0
- package/docs/guide/invitations.md +269 -0
- package/docs/guide/passkeys.md +207 -0
- package/docs/guide/second-factor.md +238 -0
- package/docs/guide/social.md +190 -0
- package/docs/guide/step-up.md +208 -0
- package/docs/guide/subscriptions.md +255 -0
- package/docs/guide/telemetry.md +45 -0
- package/docs/roadmap.md +124 -0
- package/docs/troubleshooting.md +1265 -0
- package/graphql/janus-api-keys.graphqls +237 -0
- package/graphql/janus-avatar.graphqls +19 -0
- package/graphql/janus-invitations.graphqls +280 -0
- package/graphql/janus-passkey-sign-in.graphqls +40 -0
- package/graphql/janus-passkeys.graphqls +134 -0
- package/graphql/janus-second-factor.graphqls +199 -0
- package/graphql/janus-social.graphqls +155 -0
- package/graphql/janus.graphqls +44 -0
- 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.
|
package/docs/roadmap.md
ADDED
|
@@ -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.
|