@softistx/janus-graphql 0.0.0-stage → 0.30.2
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
|
+
# Directives
|
|
2
|
+
|
|
3
|
+
This page is for guarding a schema: `@authenticated`, which asks who the user
|
|
4
|
+
is, `@fresh`, which asks how recently their session proved it, and
|
|
5
|
+
`@permission`, which asks what the user may do to one object. All three
|
|
6
|
+
are declared in `janusTypeDefs`, applied by `useJanus()` when the server
|
|
7
|
+
builds its schema, and checked before the resolver runs — a refused request
|
|
8
|
+
never reaches it.
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
import { janusMaskError, janusTypeDefs, useJanus } from '@softistx/janus-graphql';
|
|
12
|
+
import { createSchema, createYoga } from 'graphql-yoga';
|
|
13
|
+
|
|
14
|
+
export const yoga = createYoga({
|
|
15
|
+
schema: createSchema({ typeDefs: [janusTypeDefs, typeDefs], resolvers }),
|
|
16
|
+
plugins: [
|
|
17
|
+
useJanus({
|
|
18
|
+
auth,
|
|
19
|
+
access,
|
|
20
|
+
loaders: { record: (id) => records.find(id) }, // what @permission loads by id
|
|
21
|
+
conditions: { record: (record, ctx: Context) => ({ onShift: ctx.shift.open }) }, // a when()'s ctx
|
|
22
|
+
}),
|
|
23
|
+
],
|
|
24
|
+
maskedErrors: { maskError: janusMaskError() },
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Where a directive applies
|
|
29
|
+
|
|
30
|
+
Every directive goes on a field, an object type or an interface:
|
|
31
|
+
|
|
32
|
+
| Written on | Guards |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| a field | that field |
|
|
35
|
+
| an object type | every field of that type |
|
|
36
|
+
| an interface | every field of every object type implementing it |
|
|
37
|
+
| an interface's field | the field of the same name on every object type implementing it |
|
|
38
|
+
|
|
39
|
+
GraphQL runs resolvers on object types only, so a directive on an interface
|
|
40
|
+
is applied to each type implementing it, when the schema is built: nothing
|
|
41
|
+
an interface declares is left unguarded, and a type added later that
|
|
42
|
+
implements it is guarded too.
|
|
43
|
+
|
|
44
|
+
**Every directive that applies must hold** — the field's, its type's, its
|
|
45
|
+
interfaces'. A type's directive guards the type's fields, **not the field that
|
|
46
|
+
returns it**: `Query.ward` below runs for an anonymous request, and the
|
|
47
|
+
refusal lands on `ward.name`. Guard the field too when the lookup itself must
|
|
48
|
+
not run.
|
|
49
|
+
|
|
50
|
+
## `@authenticated(type: [String!])`
|
|
51
|
+
|
|
52
|
+
```graphql
|
|
53
|
+
type Query {
|
|
54
|
+
me: User @authenticated # any signed-in user
|
|
55
|
+
roster: [Staff!]! @authenticated(type: ["staff"])
|
|
56
|
+
ward(id: ID!): Ward
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
type Ward @authenticated(type: ["staff"]) { # every field of Ward
|
|
60
|
+
name: String
|
|
61
|
+
chart: String @authenticated(type: ["staff", "patient"])
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
interface Audited {
|
|
65
|
+
trail: String @authenticated(type: ["staff"]) # trail, on every type implementing Audited
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
On `Ward.chart` above, the type's `["staff"]` and the field's
|
|
70
|
+
`["staff", "patient"]` both apply: only staff pass.
|
|
71
|
+
|
|
72
|
+
| The request | Answered |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| anonymous | `UNAUTHENTICATED`, 401 |
|
|
75
|
+
| a user of a type no `type:` names | `FORBIDDEN`, 403 |
|
|
76
|
+
| a store that cannot answer | `SERVICE_UNAVAILABLE`, 503 |
|
|
77
|
+
| a user every directive admits | the resolver runs |
|
|
78
|
+
|
|
79
|
+
Under `useJanus({ type: 'staff' })`, the only user type a directive may name
|
|
80
|
+
is `'staff'`.
|
|
81
|
+
|
|
82
|
+
## `@fresh(maxAge: Int!)`
|
|
83
|
+
|
|
84
|
+
```graphql
|
|
85
|
+
type Mutation {
|
|
86
|
+
changeEmail(email: String!): User @fresh(maxAge: 600) # signed in, or confirmed, in the last ten minutes
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
type PaymentMethods @fresh(maxAge: 600) { # every field of PaymentMethods
|
|
90
|
+
cards: [Card!]!
|
|
91
|
+
add(token: String!): Card @fresh(maxAge: 60) # the smallest maxAge holds: one minute
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Only a session that proved who it is **less than `maxAge` seconds ago**
|
|
96
|
+
reaches the field: signed in, or confirmed since by `auth.stepUp.confirm`,
|
|
97
|
+
which moves the session's `authenticatedAt` to now. Renewing a sliding
|
|
98
|
+
session does not. It is `@softistx/janus`'s `assertFresh`, and
|
|
99
|
+
`@softistx/janus-hono`'s `fresh()`, for a schema.
|
|
100
|
+
|
|
101
|
+
**`maxAge` is in seconds**, an `Int`: `600` is ten minutes. Seconds because
|
|
102
|
+
a GraphQL `Int` is 32 bits — about 24 days in milliseconds — and because a
|
|
103
|
+
freshness limit is written in seconds elsewhere, such as OpenID Connect's
|
|
104
|
+
`max_age`. `@softistx/janus`'s durations read a bare number as milliseconds;
|
|
105
|
+
here there is no unit to write, so it is seconds, always.
|
|
106
|
+
|
|
107
|
+
| The request | Answered |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| anonymous | `UNAUTHENTICATED`, 401 |
|
|
110
|
+
| a user of a type `@authenticated` does not name | `FORBIDDEN`, 403, before freshness is read |
|
|
111
|
+
| a session that proved who it is `maxAge` seconds ago or more | `STEP_UP_REQUIRED`, 403 — the client asks for a step-up |
|
|
112
|
+
| a store that cannot answer | `SERVICE_UNAVAILABLE`, 503, never a denial |
|
|
113
|
+
| a fresh session | every `@permission`, then the resolver |
|
|
114
|
+
|
|
115
|
+
`@fresh` implies a signed-in user, as `@permission` does. **It is checked
|
|
116
|
+
after `@authenticated` and before any `@permission`**, so a stale session
|
|
117
|
+
asks no permission check and loads no object. Where several apply — the
|
|
118
|
+
field's, its type's, its interfaces' — **the smallest `maxAge` holds**. The
|
|
119
|
+
refusal is at `maxAge` exactly: a session `maxAge` seconds old is refused,
|
|
120
|
+
as `assertFresh` refuses it.
|
|
121
|
+
|
|
122
|
+
**A `@fresh` on a subscription field is checked when it subscribes**: a
|
|
123
|
+
fresh one keeps receiving events past `maxAge`. A `@fresh` on the payload's
|
|
124
|
+
type or its fields is checked on every event, as any field. See
|
|
125
|
+
[the step-up over GraphQL](step-up.md#subscriptions).
|
|
126
|
+
|
|
127
|
+
The time is `useJanus({ clock })`'s — give it the clock given to `janus()`
|
|
128
|
+
when that is not the system's, such as `fixedClock` in a spec. The flow a
|
|
129
|
+
client follows on `STEP_UP_REQUIRED`, with `stepUp.request` and `confirm` as
|
|
130
|
+
mutations, is in [the step-up over GraphQL](step-up.md); `requireFresh(ctx,
|
|
131
|
+
maxAge)` is the same check in a resolver.
|
|
132
|
+
|
|
133
|
+
## `@permission(name, type, id, onDeny)`
|
|
134
|
+
|
|
135
|
+
```graphql
|
|
136
|
+
directive @permission(
|
|
137
|
+
name: String!
|
|
138
|
+
type: String!
|
|
139
|
+
id: String
|
|
140
|
+
onDeny: JanusPermissionDenial! = NOT_FOUND
|
|
141
|
+
) repeatable on OBJECT | INTERFACE | FIELD_DEFINITION
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Only a user holding permission `name` on the object of `type` whose id `id`
|
|
145
|
+
reads reaches the field. It is `@softistx/janus-hono`'s
|
|
146
|
+
`permission(access, permission, type, load)` for a schema, and asks
|
|
147
|
+
`access.can` — the `permissions()` instance given to `useJanus()`.
|
|
148
|
+
|
|
149
|
+
| Argument | What it is |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| `name` | A relation or a permission `type` declares in the model — what `access.can` may be asked |
|
|
152
|
+
| `type` | An object type of the model |
|
|
153
|
+
| `id` | Where the object's id is read: `args.<path>` or `parent.<path>`. Absent: `args.id` on a field, `parent.id` on a type or an interface |
|
|
154
|
+
| `onDeny` | What a denial answers: `NOT_FOUND`, 404, by default, or `FORBIDDEN`, 403 |
|
|
155
|
+
|
|
156
|
+
`@permission` implies `@authenticated`: an anonymous request is answered
|
|
157
|
+
`UNAUTHENTICATED`, 401, before any object is loaded or any check asked. A
|
|
158
|
+
`@fresh` that applies is checked before it, too.
|
|
159
|
+
|
|
160
|
+
### Reading the id
|
|
161
|
+
|
|
162
|
+
```graphql
|
|
163
|
+
type Query {
|
|
164
|
+
record(id: ID!): Record @permission(name: "view", type: "record") # args.id
|
|
165
|
+
transfer(input: TransferInput!): Transfer
|
|
166
|
+
@permission(name: "manage", type: "ward", id: "args.input.wardId") # a path into an input
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
type Record @permission(name: "view", type: "record") { # parent.id: the record itself
|
|
170
|
+
title: String
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
type Visit {
|
|
174
|
+
notes: String @permission(name: "enter", type: "ward", id: "parent.wardId") # another object, by id
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
A path is `args` or `parent` followed by one or more names, each read from the
|
|
179
|
+
value before it. Where a step reads a list, the path goes on through every
|
|
180
|
+
element.
|
|
181
|
+
|
|
182
|
+
What `access.can` is given depends on where the id was read:
|
|
183
|
+
|
|
184
|
+
| The id | The object `access.can` is given |
|
|
185
|
+
| --- | --- |
|
|
186
|
+
| `parent.id`, or `parent.<path>.id` | **The value that holds it** — the parent, or the value the path reached — with `type` added, read through a proxy: a getter, a class's `#private` state or an ORM document's accessors answer as they do in the resolver |
|
|
187
|
+
| any other `parent.<path>`, or `args.<path>`, on a type with no `fromField` | `{ type, id }` |
|
|
188
|
+
| the same, on a type with a `fromField` | **What `loaders[type](id, ctx)` answers**, with `type` added — the `fromField`s read its fields. `null` is answered `NOT_FOUND` |
|
|
189
|
+
|
|
190
|
+
A `fromField` relation is read from the object's own data — a record's
|
|
191
|
+
`doctorId` — so the object must carry that field. The parent does when its
|
|
192
|
+
resolver answered the record; an id alone does not, and the loader is what
|
|
193
|
+
turns one into the object. A type with no `fromField` may have a loader too:
|
|
194
|
+
it is then asked for every id `@permission` reads alone — from `args`, or
|
|
195
|
+
from a parent field other than `id` — and its
|
|
196
|
+
`null` answers `NOT_FOUND` for an object that does not exist.
|
|
197
|
+
|
|
198
|
+
```ts
|
|
199
|
+
useJanus({
|
|
200
|
+
auth,
|
|
201
|
+
access,
|
|
202
|
+
loaders: {
|
|
203
|
+
record: (id, ctx: Context) => records.find(id), // { id, doctorId, … } or null
|
|
204
|
+
},
|
|
205
|
+
});
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
An id that holds `@`, `#`, a parenthesis, a NUL character or a lone
|
|
209
|
+
surrogate, or is empty, names no object: it is answered `NOT_FOUND` without
|
|
210
|
+
asking, and without calling the loader.
|
|
211
|
+
|
|
212
|
+
### Lists
|
|
213
|
+
|
|
214
|
+
```graphql
|
|
215
|
+
type Query {
|
|
216
|
+
records(ids: [ID!]!): [Record!]! @permission(name: "view", type: "record", id: "args.ids")
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
type Team {
|
|
220
|
+
wards: [Ward!]!
|
|
221
|
+
summary: String @permission(name: "enter", type: "ward", id: "parent.wards.id")
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**A list requires the permission on every element**: one denial denies the
|
|
226
|
+
field. The checks of a list are asked together. An empty list in `args` asks
|
|
227
|
+
nothing, and the resolver runs: the client asked for nothing. An empty list
|
|
228
|
+
in the parent is answered `NOT_FOUND`: the object's data names nothing to
|
|
229
|
+
check, and its fields are not open to every user for it. This is not a
|
|
230
|
+
filter: to answer only the items a user may see, ask `access.list()` for
|
|
231
|
+
their ids and load those.
|
|
232
|
+
|
|
233
|
+
### Conditions
|
|
234
|
+
|
|
235
|
+
A permission whose rules reach a `when()` needs a `ctx`, as `access.can`
|
|
236
|
+
does. `conditions` answers it, per object type, from the object checked and
|
|
237
|
+
the request's context:
|
|
238
|
+
|
|
239
|
+
```ts
|
|
240
|
+
// model: record.permits.edit = [when('doctors', (ctx: { onShift: boolean }) => ctx.onShift)]
|
|
241
|
+
useJanus({
|
|
242
|
+
auth,
|
|
243
|
+
access,
|
|
244
|
+
loaders: { record: (id) => records.find(id) },
|
|
245
|
+
conditions: {
|
|
246
|
+
record: async (record, ctx: Context) => ({ onShift: await shifts.isOpen(ctx) }),
|
|
247
|
+
},
|
|
248
|
+
});
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
One entry per type covers every permission of it: it answers every
|
|
252
|
+
condition any of them reaches, typed as the intersection of their `ctx`s.
|
|
253
|
+
|
|
254
|
+
### Repeated, and in order
|
|
255
|
+
|
|
256
|
+
```graphql
|
|
257
|
+
type Query {
|
|
258
|
+
discharge(id: ID!): Discharge
|
|
259
|
+
@permission(name: "view", type: "record")
|
|
260
|
+
@permission(name: "discharge", type: "record", onDeny: FORBIDDEN)
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
**Every one must hold** — an either-or belongs in the model, as a
|
|
265
|
+
permission whose rules name both. They are asked **one at a time, in order**,
|
|
266
|
+
and the first that denies answers: the ones after it are never asked.
|
|
267
|
+
|
|
268
|
+
The order across locations is outermost first: the interfaces' directives,
|
|
269
|
+
the type's, the interfaces' fields', then the field's own. Across
|
|
270
|
+
directives, every `@authenticated` comes first, then `@fresh`, then the
|
|
271
|
+
`@permission`s. So a type's
|
|
272
|
+
`NOT_FOUND` answers before a field's `FORBIDDEN` could tell that the object
|
|
273
|
+
exists.
|
|
274
|
+
|
|
275
|
+
### `NOT_FOUND` or `FORBIDDEN`
|
|
276
|
+
|
|
277
|
+
`NOT_FOUND` is the default, because a `FORBIDDEN` says *this exists, and not
|
|
278
|
+
for you*: for `record(id: "r42")` that is already an answer to a question the
|
|
279
|
+
user may not ask. Choose `onDeny: FORBIDDEN` where the object is known to
|
|
280
|
+
exist anyway — a field of an object the user may already see:
|
|
281
|
+
|
|
282
|
+
```graphql
|
|
283
|
+
type Record @permission(name: "view", type: "record") {
|
|
284
|
+
title: String
|
|
285
|
+
billing: Billing @permission(name: "manage", type: "record", onDeny: FORBIDDEN)
|
|
286
|
+
}
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
| The request | Answered |
|
|
290
|
+
| --- | --- |
|
|
291
|
+
| anonymous | `UNAUTHENTICATED`, 401 |
|
|
292
|
+
| a user of a type `@authenticated` does not name | `FORBIDDEN`, 403, before any check |
|
|
293
|
+
| a session older than a `@fresh` that applies allows | `STEP_UP_REQUIRED`, 403, before any check |
|
|
294
|
+
| no id at the path, an empty list in the parent, or an id no object can hold | `NOT_FOUND`, 404 |
|
|
295
|
+
| a loader answering `null` | `NOT_FOUND`, 404 |
|
|
296
|
+
| a denial | `onDeny`: `NOT_FOUND`, 404, or `FORBIDDEN`, 403 |
|
|
297
|
+
| a store — or a loader — that cannot answer | `SERVICE_UNAVAILABLE`, 503, never a denial |
|
|
298
|
+
| every permission held | the resolver runs |
|
|
299
|
+
|
|
300
|
+
A path that reads nothing — an optional argument left out, a `null` field of
|
|
301
|
+
the parent — is answered `NOT_FOUND`, and said once per directive through
|
|
302
|
+
`process.emitWarning`: `@permission on Query.record resolved no object id
|
|
303
|
+
from args.id — answered NOT_FOUND`.
|
|
304
|
+
|
|
305
|
+
### One check per question, per request
|
|
306
|
+
|
|
307
|
+
The same question asked twice in one request is asked once: two fields —
|
|
308
|
+
aliased or not — a directive and a resolver's `can()`, or two fields resolved
|
|
309
|
+
at once, which share the one pending answer. The question is the notation
|
|
310
|
+
`record:r1#view@staff:u1`: object, permission and subject. Across requests
|
|
311
|
+
nothing is kept.
|
|
312
|
+
|
|
313
|
+
Not remembered: a check with a condition's `ctx`, which the question does
|
|
314
|
+
not hold; an anonymous one, which costs no store call; and a failure — the
|
|
315
|
+
next question asks again.
|
|
316
|
+
|
|
317
|
+
**A subscription's directives skip the memo.** It is one request whose
|
|
318
|
+
fields resolve again on every event, so each event's `@permission` asks
|
|
319
|
+
afresh and a `revoke()` made since the subscription started stops the next
|
|
320
|
+
event. `can(ctx, …)` called in a subscription's resolver still reads the
|
|
321
|
+
memo: call `ctx.janus.access.can` there. **A mutation does not**: a
|
|
322
|
+
mutation that grants or revokes and then asks the same question in the same
|
|
323
|
+
request reads the answer remembered before the change. Ask
|
|
324
|
+
`access.can` directly after such a change, or answer from the mutation's own
|
|
325
|
+
result.
|
|
326
|
+
|
|
327
|
+
## Refused when the schema is built
|
|
328
|
+
|
|
329
|
+
What no request could ever pass is a `TypeError` at start-up, naming the
|
|
330
|
+
field, and the location the directive was written on when it is not the
|
|
331
|
+
field — `(read by Ward.name)`:
|
|
332
|
+
|
|
333
|
+
```
|
|
334
|
+
TypeError: applyJanusDirectives(): @authenticated on Query.me names the user type 'doctor', which is not one of 'patient', 'staff'
|
|
335
|
+
TypeError: applyJanusDirectives(): @authenticated on Query.me names no user type — leave type: out to admit any signed-in user
|
|
336
|
+
TypeError: applyJanusDirectives(): the @authenticated on Ward.chart and on its type or interfaces admit no user type in common
|
|
337
|
+
TypeError: applyJanusDirectives(): @fresh on Mutation.changeEmail asks maxAge: 0 — write a number of seconds above zero, such as maxAge: 600 for ten minutes
|
|
338
|
+
TypeError: applyJanusDirectives(): @permission on Query.ward needs the permissions() instance — pass useJanus({ auth, access }), with access what permissions() answered
|
|
339
|
+
TypeError: applyJanusDirectives(): @permission on Query.invoice names the object type 'invoice', which is not one of 'record', 'ward'
|
|
340
|
+
TypeError: applyJanusDirectives(): @permission on Query.ward asks 'delete', which ward does not declare — it declares 'nurses', 'visitors', 'enter', 'manage'
|
|
341
|
+
TypeError: applyJanusDirectives(): @permission on Query.ward reads its id from 'ward.id', which is not args.<name> or parent.<name>
|
|
342
|
+
TypeError: applyJanusDirectives(): @permission on Query.ward reads args.wardId, and Query.ward takes no argument wardId
|
|
343
|
+
TypeError: applyJanusDirectives(): @permission on Query.record reads the record's id from args.id, and record reads 'doctorId' of the object itself (fromField) — pass useJanus({ loaders: { record: (id, ctx) => … } })
|
|
344
|
+
TypeError: applyJanusDirectives(): @permission on Query.record asks 'edit' of record, which reaches a when() — pass useJanus({ conditions: { record: (object, ctx) => … } })
|
|
345
|
+
TypeError: applyJanusDirectives(): @permission on Query.ward finds loaders.ward, which is not a function
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
Each is in [troubleshooting](../troubleshooting.md), with its fix. The
|
|
349
|
+
compiler refuses the wiring's own mistakes before that: a loader for a type
|
|
350
|
+
the model does not declare, a loader answering an object without a field a
|
|
351
|
+
`fromField` reads, a condition for a type no `when()` is reached on, a `ctx`
|
|
352
|
+
of the wrong shape, `loaders` or `conditions` without `access`, and a
|
|
353
|
+
`clock` that is not a `Clock`. A `maxAge` that is not an `Int`, or is
|
|
354
|
+
missing, is refused by graphql-js itself, at start-up too.
|
|
355
|
+
|
|
356
|
+
## The transform alone
|
|
357
|
+
|
|
358
|
+
`applyJanusDirectives(schema, { auth, type?, access?, loaders?, conditions? })`
|
|
359
|
+
is what `useJanus()` runs on every schema. Call it to check a schema at build
|
|
360
|
+
time — in a test, or in a script that fails a deploy — without starting a
|
|
361
|
+
server:
|
|
362
|
+
|
|
363
|
+
```ts
|
|
364
|
+
import { applyJanusDirectives } from '@softistx/janus-graphql';
|
|
365
|
+
|
|
366
|
+
applyJanusDirectives(schema, { auth, access, loaders, conditions }); // throws the TypeErrors above
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
The guards it installs read `ctx.janus`, which only `useJanus()` builds: a
|
|
370
|
+
guarded field resolved under any other context throws
|
|
371
|
+
`TypeError: @permission on Query.ward: ctx.janus is not set — add useJanus({ auth }) to the plugins`.
|
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
# Errors
|
|
2
|
+
|
|
3
|
+
This page is for what a client receives when a request is refused or a store
|
|
4
|
+
is down, and how that becomes an HTTP status. When you have a message in
|
|
5
|
+
hand and want its cause, see [troubleshooting](../troubleshooting.md).
|
|
6
|
+
|
|
7
|
+
## No error class of its own
|
|
8
|
+
|
|
9
|
+
This package throws `GraphQLError` for a denial, and lets `@softistx/janus`'s own
|
|
10
|
+
errors through. Every error it answers carries a `code` and a status in its
|
|
11
|
+
`extensions`:
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
new GraphQLError('Not signed in', {
|
|
15
|
+
extensions: { code: 'UNAUTHENTICATED', http: { status: 401 } },
|
|
16
|
+
});
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Yoga reads `extensions.http.status` to answer the HTTP response, and strips
|
|
20
|
+
`http` from the body, so the client sees:
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"data": { "me": null },
|
|
25
|
+
"errors": [{ "message": "Not signed in", "path": ["me"], "extensions": { "code": "UNAUTHENTICATED" } }]
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## The codes
|
|
30
|
+
|
|
31
|
+
| Code | Status | Message | When |
|
|
32
|
+
| --- | --- | --- | --- |
|
|
33
|
+
| `UNAUTHENTICATED` | 401 | `Not signed in` | An anonymous request reached a guarded field, `requireUser()` or `requireFresh()` |
|
|
34
|
+
| `FORBIDDEN` | 403 | `Forbidden` | A user of a type the directive or `requireUser({ type })` does not name, or a `@permission(onDeny: FORBIDDEN)` denied |
|
|
35
|
+
| `STEP_UP_REQUIRED` | 403 | `Forbidden` | A session older than `@fresh(maxAge)` or `requireFresh(ctx, maxAge)` allows: the client asks for a step-up — see [the step-up over GraphQL](step-up.md) |
|
|
36
|
+
| `NOT_FOUND` | 404 | `Not found` | `@permission`'s default denial, a loader answering `null`, an id `@permission` could not read — and `denial('NOT_FOUND')` |
|
|
37
|
+
| `SERVICE_UNAVAILABLE` | 503 | `The service is unavailable, retry later` | A store could not answer: `STORE_FAILED` |
|
|
38
|
+
| `BAD_USER_INPUT` | 400 | `size must be a positive integer` | `JanusAvatar.url(size:)` asked with a size below 1 — see [account avatars](avatars.md) |
|
|
39
|
+
| `BAD_USER_INPUT` | 400 | `Invalid request` | `invitations(after:)` with a cursor issued for another scope, status, role, ref, lapsed or order: the core's `CURSOR_FILTER_MISMATCH`, remapped |
|
|
40
|
+
| `SECOND_FACTOR_ACTIVE` | 409 | `Conflict` | `enrollSecondFactor` over an active factor — see [the second factor](second-factor.md#errors) |
|
|
41
|
+
| `SECOND_FACTOR_NOT_ENROLLED` | 409 | `Conflict` | `activateSecondFactor` before an enrolment, `disableSecondFactor` or a recovery-code write without an active factor — see [the second factor](second-factor.md#errors) |
|
|
42
|
+
| `EMAIL_UNVERIFIED` | 403 | `Forbidden` | `enrollSecondFactor`, `activateSecondFactor`, passkey registration (options or register) or a sign-in with `password.requireVerifiedEmail` while the account's e-mail is not proved — see [the second factor](second-factor.md#errors) |
|
|
43
|
+
| `EMAIL_CHANGE_NEEDS_PROOF` | 409 | `Conflict` | `update` of the e-mail of a user holding a second factor or a passkey (through your own resolver): nothing was written; move it with `changeEmail` |
|
|
44
|
+
| `INVITATION_INVALID` | 400 | `Invalid request` | An invitation input that cannot be kept (`field`), or a code that names no pending invitation — see [invitations](invitations.md#errors) |
|
|
45
|
+
| `INVITATION_LIMIT` | 409 | `Conflict` | `issueInvitation` into a scope that holds `maxPending` (`maxActive`) |
|
|
46
|
+
| `INVITATION_NOT_PENDING` | 409 | `Conflict` | `resendInvitation` or `revokeInvitation` of an accepted or revoked invitation |
|
|
47
|
+
| `INVITATION_REFUSED` | 403 | `Forbidden` | `acceptInvitation` refused by the application's `beforeAccept`; nothing was written, the invitation is still pending |
|
|
48
|
+
| `PASSWORD_REQUIRED` | 400 | `Invalid request` | `acceptInvitation` by a new invitee with no password |
|
|
49
|
+
| `PROVIDER_ERROR` | 502 | `Bad gateway` | The social provider failed — see [social sign-in](social.md) |
|
|
50
|
+
| any other `JanusErrorCode` | its `statusOf(code)` | fixed per status: `Invalid request` 400, `Invalid credentials` 401 (`CREDENTIALS_INVALID`, `CODE_INVALID`), `Forbidden` 403, `Not found` 404, `Conflict` 409, `Internal server error` 500 and 501 | A `JanusError` a resolver let through — `CREDENTIALS_INVALID` 401, `LOGIN_TAKEN` 409, `TOKEN_EXPIRED` 400, … |
|
|
51
|
+
|
|
52
|
+
The status of every `JanusErrorCode` is `@softistx/janus`'s
|
|
53
|
+
[`statusOf`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/errors.md),
|
|
54
|
+
the table `@softistx/janus-hono` answers with too.
|
|
55
|
+
|
|
56
|
+
What a refusal carries beyond `code` is only what the client can act on:
|
|
57
|
+
`issues` for `USER_INVALID`, `minLength` for `PASSWORD_TOO_SHORT`,
|
|
58
|
+
`attemptsLeft` for `CODE_INVALID`, `retryAfter` for a throttled
|
|
59
|
+
`CREDENTIALS_INVALID`, `MAIL_THROTTLED` or `CODE_INVALID` past the user's app-code window (with `attemptsLeft: 0`) — with its `Retry-After` header —
|
|
60
|
+
`maxActive` for `API_KEY_LIMIT` (409, the standing keys a user may hold) and
|
|
61
|
+
`INVITATION_LIMIT` (409, the pending invitations a scope may hold) and
|
|
62
|
+
`field` (`'name'` or `'lifetime'`) for `API_KEY_INVALID` (400), `field` and, for a code, `reason` (`'unknown'`, `'expired'`, `'accepted'` or `'revoked'`) for `INVITATION_INVALID` (400), and `returnTo` and `flowSpent` for a social flow's refusal (see [social sign-in](social.md#errors)). **Never** any other `reason`, `login`, `slot`,
|
|
63
|
+
`operation`, a hash prefix or a cause — those are for your logs. **The
|
|
64
|
+
message is never the core's**: `@softistx/janus`'s messages name a hash prefix or
|
|
65
|
+
a record's versions, so every `JanusError` gets the fixed message of its
|
|
66
|
+
status, and a client tells refusals apart by `code`.
|
|
67
|
+
|
|
68
|
+
## An outage is never a denial
|
|
69
|
+
|
|
70
|
+
**An absence is `null`; a failure throws** — and here a failure is never
|
|
71
|
+
answered `UNAUTHENTICATED`, `FORBIDDEN` or `NOT_FOUND`. A 401 during an
|
|
72
|
+
outage tells every user they are signed out; a 403 tells them they lost their
|
|
73
|
+
rights; a 404 tells them the record is gone. All send them somewhere a retry
|
|
74
|
+
would not.
|
|
75
|
+
|
|
76
|
+
| Where the store fails | Answered |
|
|
77
|
+
| --- | --- |
|
|
78
|
+
| a field `@authenticated` or `@permission` guards | `SERVICE_UNAVAILABLE`, 503 — with or without `janusMaskError()` |
|
|
79
|
+
| a `loaders` entry throwing `StoreFailure` — or any `JanusError` — for `@permission` | the `JanusError`'s status: `SERVICE_UNAVAILABLE`, 503, for `STORE_FAILED` — with or without `janusMaskError()` |
|
|
80
|
+
| `requireUser(ctx)`, `can(ctx, …)` | `SERVICE_UNAVAILABLE`, 503 — with or without `janusMaskError()` |
|
|
81
|
+
| `ctx.janus.user()` read in a resolver, any `auth.*` or `access.*` call | `SERVICE_UNAVAILABLE`, 503 with `janusMaskError()`; Yoga's masked 500 without it |
|
|
82
|
+
|
|
83
|
+
## `janusMaskError({ report?, fallback?, mapCode? })`
|
|
84
|
+
|
|
85
|
+
Yoga masks every error that is not a `GraphQLError` into `Unexpected error.`
|
|
86
|
+
with a 500. That is right for a bug and wrong for a `JanusError`: a wrong
|
|
87
|
+
password is a 401 the client must see, and an outage a 503 it must retry.
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
import { janusMaskError } from '@softistx/janus-graphql';
|
|
91
|
+
import { createYoga } from 'graphql-yoga';
|
|
92
|
+
|
|
93
|
+
createYoga({
|
|
94
|
+
schema,
|
|
95
|
+
plugins: [useJanus({ auth })],
|
|
96
|
+
maskedErrors: { maskError: janusMaskError() },
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
A `JanusError` — thrown by a resolver, or wrapped by graphql-js with its path —
|
|
101
|
+
is answered as the table above says, at the path it was thrown from. Anything
|
|
102
|
+
else goes to `fallback`.
|
|
103
|
+
|
|
104
|
+
Without a `fallback`, every other error is masked the way Yoga's own
|
|
105
|
+
`maskError` does: a `GraphQLError` of your own is kept, anything else becomes
|
|
106
|
+
the mask's message with `INTERNAL_SERVER_ERROR` and `unexpected: true` (so a
|
|
107
|
+
failure with no `data`, such as a context factory that throws, is still HTTP
|
|
108
|
+
500), `extensions.http` is carried over, and the original error is shown only
|
|
109
|
+
in development (`isDev`). Passing Yoga's `maskError` is no longer needed; any
|
|
110
|
+
other function passed as `{ fallback }`, or alone, `janusMaskError(fn)`,
|
|
111
|
+
replaces the default. The result (typed `JanusMaskError`) fits Yoga's
|
|
112
|
+
`maskError` and `useMaskedErrors({ maskError })` of envelop 5 (`isDev` third)
|
|
113
|
+
and of envelop 6 (`context` third).
|
|
114
|
+
|
|
115
|
+
## Your own codes: `mapCode`
|
|
116
|
+
|
|
117
|
+
An API with its own error codes maps the package's onto them in one place.
|
|
118
|
+
`mapCode(code, error)` is called with the `extensions.code` of every
|
|
119
|
+
`GraphQLError` the mask returns (`UNAUTHENTICATED`, `FORBIDDEN`,
|
|
120
|
+
`STEP_UP_REQUIRED`, `SERVICE_UNAVAILABLE`, `NOT_FOUND`…) and answers
|
|
121
|
+
`{ code, message?, status? }`, or `undefined` to keep the error as it is. The
|
|
122
|
+
error is rebuilt with that code (and message, and `extensions.http.status`),
|
|
123
|
+
keeping its other extensions, nodes, path and `originalError`.
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
const codes: Record<string, { code: string; status: number }> = {
|
|
127
|
+
UNAUTHENTICATED: { code: 'auth.errors.unauthenticated', status: 401 },
|
|
128
|
+
FORBIDDEN: { code: 'auth.errors.forbidden', status: 403 },
|
|
129
|
+
SERVICE_UNAVAILABLE: { code: 'auth.errors.unavailable', status: 503 },
|
|
130
|
+
};
|
|
131
|
+
|
|
132
|
+
createYoga({
|
|
133
|
+
schema,
|
|
134
|
+
maskedErrors: { maskError: janusMaskError({ mapCode: (code) => codes[code] }) },
|
|
135
|
+
});
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## The `JanusError` under a resolver's error: `janusErrorOf`
|
|
139
|
+
|
|
140
|
+
The package's resolvers throw a `GraphQLError` whose `originalError` chain
|
|
141
|
+
holds the `JanusError`. `janusErrorOf(error)` returns it (or `undefined`), so
|
|
142
|
+
a wrapper can map a refusal per operation:
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
import { janusErrorOf } from '@softistx/janus-graphql';
|
|
146
|
+
|
|
147
|
+
try {
|
|
148
|
+
return await call();
|
|
149
|
+
} catch (raised) {
|
|
150
|
+
if (janusErrorOf(raised)?.code === 'INVITATION_NOT_PENDING') throw notPending();
|
|
151
|
+
throw raised;
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Every outage in your logs: `report`
|
|
156
|
+
|
|
157
|
+
The client reads a fixed message, and nothing of the store's: which store
|
|
158
|
+
failed, and why, is for your logs. A directive — `@authenticated`, `@fresh`,
|
|
159
|
+
`@permission` — and `requireUser()`, `requireFresh()` and `can()` answer an
|
|
160
|
+
outage 503 themselves, before any resolver of yours runs, so there is no
|
|
161
|
+
`try` of yours to log it in. `report` is where it goes:
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
createYoga({
|
|
165
|
+
schema,
|
|
166
|
+
plugins: [useJanus({ auth, access })],
|
|
167
|
+
maskedErrors: {
|
|
168
|
+
maskError: janusMaskError({
|
|
169
|
+
report: (error) => logger.error({ code: error.code, cause: error.cause }, error.message),
|
|
170
|
+
}),
|
|
171
|
+
},
|
|
172
|
+
});
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
- **Every 5xx, whichever path it took**: `STORE_FAILED`, `UNSUPPORTED`,
|
|
176
|
+
`PERMISSION_DEPTH` — from a directive, a helper, a loader, or a resolver
|
|
177
|
+
that let it through. `report` is given `@softistx/janus`'s own error: a
|
|
178
|
+
`StoreFailure` carries the `slot` and `operation` of the call that failed,
|
|
179
|
+
its message and its `cause`.
|
|
180
|
+
- **Once per failure.** The user is authenticated once per request, so an
|
|
181
|
+
outage that fails three guarded fields is one error, reported once — and
|
|
182
|
+
answered three times.
|
|
183
|
+
- **Never a 4xx**: a denial, `CREDENTIALS_INVALID`, `STEP_UP_REQUIRED` are the
|
|
184
|
+
client's to fix, not yours.
|
|
185
|
+
- **It cannot change the answer.** A `report` that throws, or rejects, is a
|
|
186
|
+
`process.emitWarning` naming the code, and the 503 is sent all the same.
|
|
187
|
+
What it answers is ignored.
|
|
188
|
+
|
|
189
|
+
Yoga's own logger does not cover this: it logs an error only when the mask
|
|
190
|
+
replaced it, and a directive's refusal reaches the mask already a
|
|
191
|
+
`GraphQLError`, kept as it is — so it is never logged. The same `report` is
|
|
192
|
+
`janusErrors({ report })` in `@softistx/janus-hono`, for the HTTP routes beside
|
|
193
|
+
the GraphQL server.
|
|
194
|
+
|
|
195
|
+
`janusGraphQLError(error)` is the conversion alone, for a resolver that
|
|
196
|
+
catches a `JanusError` to answer it itself:
|
|
197
|
+
|
|
198
|
+
```ts
|
|
199
|
+
import { janusGraphQLError } from '@softistx/janus-graphql';
|
|
200
|
+
import { JanusError } from '@softistx/janus';
|
|
201
|
+
|
|
202
|
+
try {
|
|
203
|
+
return await auth.patient.signIn(input);
|
|
204
|
+
} catch (error) {
|
|
205
|
+
if (error instanceof JanusError) throw janusGraphQLError(error); // CREDENTIALS_INVALID → 401
|
|
206
|
+
throw error;
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
**Password guessing is throttled per login by `@softistx/janus`**: past ten
|
|
211
|
+
passwords tried at one login in a 15-minute window, `signIn` refuses every
|
|
212
|
+
one, the right password included, until the window ends — nothing locks. A
|
|
213
|
+
sign-in mutation that lets the refusal through answers it with no code of
|
|
214
|
+
its own:
|
|
215
|
+
|
|
216
|
+
```json
|
|
217
|
+
{
|
|
218
|
+
"errors": [{ "message": "Invalid credentials", "path": ["signIn"], "extensions": { "code": "CREDENTIALS_INVALID", "retryAfter": 840 } }]
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
with a 401 and a `Retry-After: 840` header — `janusGraphQLError()` puts it
|
|
223
|
+
in `extensions.http.headers`, which Yoga answers with and strips from the
|
|
224
|
+
body. `retryAfter` is the seconds until the login's next window.
|
|
225
|
+
`janus({ signIn: { throttle } })` changes the limit
|
|
226
|
+
([passwords](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/passwords.md#password-guessing-is-throttled)).
|
|
227
|
+
|
|
228
|
+
**The requests that send an e-mail are throttled too.** Past five requests
|
|
229
|
+
for one address (one user, for `verifyEmail.send`, `changeEmail.send` — also
|
|
230
|
+
counted per new address — and an e-mailed `stepUp.request`) in a 10-minute
|
|
231
|
+
window, `@softistx/janus` throws `MAIL_THROTTLED` and sends nothing; a refused request spends and rotates nothing, so the last
|
|
232
|
+
link or code sent still works. Tell the visitor to use the last e-mail they
|
|
233
|
+
received, or to wait `retryAfter` seconds. `janusGraphQLError()` answers it
|
|
234
|
+
with the fixed message `Too many requests, retry later`:
|
|
235
|
+
|
|
236
|
+
```json
|
|
237
|
+
{
|
|
238
|
+
"errors": [{ "message": "Too many requests, retry later", "extensions": { "code": "MAIL_THROTTLED", "retryAfter": 840 } }]
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
with a 429 and a `Retry-After: 840` header, as above. `janus({ mail: { throttle } })`
|
|
243
|
+
changes the limit; keep its `window` no longer than the shortest `tokens.*`
|
|
244
|
+
lifetime you use. `@softistx/janus` never sees IP addresses: add a per-IP ceiling
|
|
245
|
+
with `@softistx/redis` rate limits.
|
|
246
|
+
|
|
247
|
+
A mutation that sends the e-mail off the request — so its time does not tell
|
|
248
|
+
whether the address has an account — calls `prepare` in the resolver and the
|
|
249
|
+
`send()` of its answer after it, so `MAIL_THROTTLED` still reaches the client
|
|
250
|
+
(`@softistx/janus` 0.20):
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
const resolvers = {
|
|
254
|
+
Mutation: {
|
|
255
|
+
async requestSignInLink(_: unknown, { email }: { email: string }) {
|
|
256
|
+
const pending = await auth.magicLink.prepare(email); // counted, nobody looked up: MAIL_THROTTLED → 429
|
|
257
|
+
void pending
|
|
258
|
+
.send() // looked up and issued after the answer; once — a second send() is a TypeError
|
|
259
|
+
.then((issued) => issued && mailer.send(issued.email, linkTo(issued.token)))
|
|
260
|
+
.catch(reportError);
|
|
261
|
+
return true; // the same answer for every address
|
|
262
|
+
},
|
|
263
|
+
},
|
|
264
|
+
};
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
`signInCode.prepare` and `resetPassword.prepare` work the same way; see
|
|
268
|
+
[requests in two steps](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/email-flows.md#requests-in-two-steps).
|
|
269
|
+
|
|
270
|
+
What the throttle does not see is one password tried against many logins:
|
|
271
|
+
limit a sign-in mutation **per client address** as well, in the resolver,
|
|
272
|
+
with the limiter you already run:
|
|
273
|
+
|
|
274
|
+
```ts
|
|
275
|
+
import { GraphQLError } from 'graphql';
|
|
276
|
+
|
|
277
|
+
if (!(await limiter.consume(`sign-in:${clientAddress}`))) {
|
|
278
|
+
throw new GraphQLError('Too many attempts', {
|
|
279
|
+
extensions: { code: 'TOO_MANY_REQUESTS', http: { status: 429 } },
|
|
280
|
+
});
|
|
281
|
+
}
|
|
282
|
+
return await auth.patient.signIn(input);
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Yoga answers the `http.status` of the extensions. Limit a `changePassword`
|
|
286
|
+
mutation per user too: it compares the current password.
|
|
287
|
+
|
|
288
|
+
## The status of a response
|
|
289
|
+
|
|
290
|
+
Yoga answers **the highest status among the errors**. A query whose fields
|
|
291
|
+
are refused for different reasons is answered with the worst of them, and a
|
|
292
|
+
query where one field is refused and the others answered is still that
|
|
293
|
+
field's status:
|
|
294
|
+
|
|
295
|
+
| The query, anonymous | Status | `data` |
|
|
296
|
+
| --- | --- | --- |
|
|
297
|
+
| `{ open }` | 200 | `{ open }` |
|
|
298
|
+
| `{ me }` | 401 | `{ me: null }` |
|
|
299
|
+
| `{ open me }` | 401 | `{ open, me: null }` |
|
|
300
|
+
|
|
301
|
+
A client reads `data` and `errors`, not only the status.
|
|
302
|
+
|
|
303
|
+
## Your own denials
|
|
304
|
+
|
|
305
|
+
`denial(code, message?)` is the `GraphQLError` the guards throw, for a
|
|
306
|
+
resolver that refuses on its own terms:
|
|
307
|
+
|
|
308
|
+
```ts
|
|
309
|
+
import { denial } from '@softistx/janus-graphql';
|
|
310
|
+
|
|
311
|
+
if (record.archived) throw denial('NOT_FOUND', 'No such record');
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
| `code` | Status |
|
|
315
|
+
| --- | --- |
|
|
316
|
+
| `UNAUTHENTICATED` | 401 |
|
|
317
|
+
| `FORBIDDEN` | 403 |
|
|
318
|
+
| `NOT_FOUND` | 404 |
|