@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,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()`.
|