@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.
Files changed (207) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +716 -2
  3. package/dist/api-keys/index.d.ts +11 -0
  4. package/dist/api-keys/index.d.ts.map +1 -0
  5. package/dist/api-keys/resolvers/deps.d.ts +39 -0
  6. package/dist/api-keys/resolvers/deps.d.ts.map +1 -0
  7. package/dist/api-keys/resolvers/index.d.ts +39 -0
  8. package/dist/api-keys/resolvers/index.d.ts.map +1 -0
  9. package/dist/api-keys/resolvers/list.d.ts +16 -0
  10. package/dist/api-keys/resolvers/list.d.ts.map +1 -0
  11. package/dist/api-keys/resolvers/manage.d.ts +17 -0
  12. package/dist/api-keys/resolvers/manage.d.ts.map +1 -0
  13. package/dist/api-keys/sdl.d.ts +14 -0
  14. package/dist/api-keys/sdl.d.ts.map +1 -0
  15. package/dist/api-keys/shape.d.ts +38 -0
  16. package/dist/api-keys/shape.d.ts.map +1 -0
  17. package/dist/api-keys/types.d.ts +149 -0
  18. package/dist/api-keys/types.d.ts.map +1 -0
  19. package/dist/avatar/index.d.ts +32 -0
  20. package/dist/avatar/index.d.ts.map +1 -0
  21. package/dist/avatar/resolvers.d.ts +41 -0
  22. package/dist/avatar/resolvers.d.ts.map +1 -0
  23. package/dist/avatar/sdl.d.ts +16 -0
  24. package/dist/avatar/sdl.d.ts.map +1 -0
  25. package/dist/bad-input.d.ts +17 -0
  26. package/dist/bad-input.d.ts.map +1 -0
  27. package/dist/connection/connection.d.ts +36 -0
  28. package/dist/connection/connection.d.ts.map +1 -0
  29. package/dist/connection/credential.d.ts +34 -0
  30. package/dist/connection/credential.d.ts.map +1 -0
  31. package/dist/connection/types.d.ts +61 -0
  32. package/dist/connection/types.d.ts.map +1 -0
  33. package/dist/context/create.d.ts +32 -0
  34. package/dist/context/create.d.ts.map +1 -0
  35. package/dist/context/index.d.ts +9 -0
  36. package/dist/context/index.d.ts.map +1 -0
  37. package/dist/context/registry.d.ts +72 -0
  38. package/dist/context/registry.d.ts.map +1 -0
  39. package/dist/context/resolve.d.ts +20 -0
  40. package/dist/context/resolve.d.ts.map +1 -0
  41. package/dist/device.d.ts +28 -0
  42. package/dist/device.d.ts.map +1 -0
  43. package/dist/directives/apply.d.ts +51 -0
  44. package/dist/directives/apply.d.ts.map +1 -0
  45. package/dist/directives/guard.d.ts +22 -0
  46. package/dist/directives/guard.d.ts.map +1 -0
  47. package/dist/directives/permission/enforce.d.ts +24 -0
  48. package/dist/directives/permission/enforce.d.ts.map +1 -0
  49. package/dist/directives/permission/model.d.ts +35 -0
  50. package/dist/directives/permission/model.d.ts.map +1 -0
  51. package/dist/directives/permission/path.d.ts +31 -0
  52. package/dist/directives/permission/path.d.ts.map +1 -0
  53. package/dist/directives/permission/validate.d.ts +42 -0
  54. package/dist/directives/permission/validate.d.ts.map +1 -0
  55. package/dist/directives/read.d.ts +43 -0
  56. package/dist/directives/read.d.ts.map +1 -0
  57. package/dist/directives/validate.d.ts +39 -0
  58. package/dist/directives/validate.d.ts.map +1 -0
  59. package/dist/directives/words.d.ts +7 -0
  60. package/dist/directives/words.d.ts.map +1 -0
  61. package/dist/errors/denial.d.ts +6 -0
  62. package/dist/errors/denial.d.ts.map +1 -0
  63. package/dist/errors/index.d.ts +12 -0
  64. package/dist/errors/index.d.ts.map +1 -0
  65. package/dist/errors/janus-error.d.ts +20 -0
  66. package/dist/errors/janus-error.d.ts.map +1 -0
  67. package/dist/errors/mask.d.ts +69 -0
  68. package/dist/errors/mask.d.ts.map +1 -0
  69. package/dist/fresh.d.ts +44 -0
  70. package/dist/fresh.d.ts.map +1 -0
  71. package/dist/helpers.d.ts +56 -0
  72. package/dist/helpers.d.ts.map +1 -0
  73. package/dist/index.d.ts +86 -0
  74. package/dist/index.d.ts.map +1 -0
  75. package/dist/index.js +3393 -0
  76. package/dist/index.js.map +75 -0
  77. package/dist/invitations/index.d.ts +12 -0
  78. package/dist/invitations/index.d.ts.map +1 -0
  79. package/dist/invitations/resolvers/anonymous.d.ts +11 -0
  80. package/dist/invitations/resolvers/anonymous.d.ts.map +1 -0
  81. package/dist/invitations/resolvers/deps.d.ts +38 -0
  82. package/dist/invitations/resolvers/deps.d.ts.map +1 -0
  83. package/dist/invitations/resolvers/index.d.ts +37 -0
  84. package/dist/invitations/resolvers/index.d.ts.map +1 -0
  85. package/dist/invitations/resolvers/owner.d.ts +17 -0
  86. package/dist/invitations/resolvers/owner.d.ts.map +1 -0
  87. package/dist/invitations/sdl/accept.d.ts +7 -0
  88. package/dist/invitations/sdl/accept.d.ts.map +1 -0
  89. package/dist/invitations/sdl/index.d.ts +14 -0
  90. package/dist/invitations/sdl/index.d.ts.map +1 -0
  91. package/dist/invitations/sdl/owner.d.ts +8 -0
  92. package/dist/invitations/sdl/owner.d.ts.map +1 -0
  93. package/dist/invitations/shape.d.ts +63 -0
  94. package/dist/invitations/shape.d.ts.map +1 -0
  95. package/dist/invitations/types/index.d.ts +5 -0
  96. package/dist/invitations/types/index.d.ts.map +1 -0
  97. package/dist/invitations/types/options.d.ts +104 -0
  98. package/dist/invitations/types/options.d.ts.map +1 -0
  99. package/dist/invitations/types/out.d.ts +136 -0
  100. package/dist/invitations/types/out.d.ts.map +1 -0
  101. package/dist/invitations/types/surface.d.ts +18 -0
  102. package/dist/invitations/types/surface.d.ts.map +1 -0
  103. package/dist/map-code.d.ts +10 -0
  104. package/dist/map-code.d.ts.map +1 -0
  105. package/dist/mask-error.d.ts +18 -0
  106. package/dist/mask-error.d.ts.map +1 -0
  107. package/dist/memo.d.ts +16 -0
  108. package/dist/memo.d.ts.map +1 -0
  109. package/dist/options.d.ts +17 -0
  110. package/dist/options.d.ts.map +1 -0
  111. package/dist/passkeys/deps.d.ts +23 -0
  112. package/dist/passkeys/deps.d.ts.map +1 -0
  113. package/dist/passkeys/first-factor.types.d.ts +38 -0
  114. package/dist/passkeys/first-factor.types.d.ts.map +1 -0
  115. package/dist/passkeys/index.d.ts +14 -0
  116. package/dist/passkeys/index.d.ts.map +1 -0
  117. package/dist/passkeys/resolvers.d.ts +23 -0
  118. package/dist/passkeys/resolvers.d.ts.map +1 -0
  119. package/dist/passkeys/sdl.d.ts +14 -0
  120. package/dist/passkeys/sdl.d.ts.map +1 -0
  121. package/dist/passkeys/shape.d.ts +14 -0
  122. package/dist/passkeys/shape.d.ts.map +1 -0
  123. package/dist/passkeys/sign-in.resolvers.d.ts +19 -0
  124. package/dist/passkeys/sign-in.resolvers.d.ts.map +1 -0
  125. package/dist/passkeys/sign-in.sdl.d.ts +16 -0
  126. package/dist/passkeys/sign-in.sdl.d.ts.map +1 -0
  127. package/dist/passkeys/types.d.ts +193 -0
  128. package/dist/passkeys/types.d.ts.map +1 -0
  129. package/dist/plugin.d.ts +59 -0
  130. package/dist/plugin.d.ts.map +1 -0
  131. package/dist/renewal.d.ts +51 -0
  132. package/dist/renewal.d.ts.map +1 -0
  133. package/dist/report.d.ts +29 -0
  134. package/dist/report.d.ts.map +1 -0
  135. package/dist/sdl.d.ts +12 -0
  136. package/dist/sdl.d.ts.map +1 -0
  137. package/dist/second-factor/index.d.ts +12 -0
  138. package/dist/second-factor/index.d.ts.map +1 -0
  139. package/dist/second-factor/resolvers/deps.d.ts +39 -0
  140. package/dist/second-factor/resolvers/deps.d.ts.map +1 -0
  141. package/dist/second-factor/resolvers/index.d.ts +39 -0
  142. package/dist/second-factor/resolvers/index.d.ts.map +1 -0
  143. package/dist/second-factor/resolvers/sign-in.d.ts +10 -0
  144. package/dist/second-factor/resolvers/sign-in.d.ts.map +1 -0
  145. package/dist/second-factor/resolvers/status.d.ts +10 -0
  146. package/dist/second-factor/resolvers/status.d.ts.map +1 -0
  147. package/dist/second-factor/resolvers/step-up.d.ts +16 -0
  148. package/dist/second-factor/resolvers/step-up.d.ts.map +1 -0
  149. package/dist/second-factor/resolvers/writes.d.ts +19 -0
  150. package/dist/second-factor/resolvers/writes.d.ts.map +1 -0
  151. package/dist/second-factor/sdl.d.ts +14 -0
  152. package/dist/second-factor/sdl.d.ts.map +1 -0
  153. package/dist/second-factor/shape.d.ts +18 -0
  154. package/dist/second-factor/shape.d.ts.map +1 -0
  155. package/dist/second-factor/types/index.d.ts +5 -0
  156. package/dist/second-factor/types/index.d.ts.map +1 -0
  157. package/dist/second-factor/types/options.d.ts +61 -0
  158. package/dist/second-factor/types/options.d.ts.map +1 -0
  159. package/dist/second-factor/types/out.d.ts +84 -0
  160. package/dist/second-factor/types/out.d.ts.map +1 -0
  161. package/dist/second-factor/types/surface.d.ts +89 -0
  162. package/dist/second-factor/types/surface.d.ts.map +1 -0
  163. package/dist/social/index.d.ts +10 -0
  164. package/dist/social/index.d.ts.map +1 -0
  165. package/dist/social/resolvers.d.ts +25 -0
  166. package/dist/social/resolvers.d.ts.map +1 -0
  167. package/dist/social/sdl.d.ts +13 -0
  168. package/dist/social/sdl.d.ts.map +1 -0
  169. package/dist/social/shape.d.ts +11 -0
  170. package/dist/social/shape.d.ts.map +1 -0
  171. package/dist/social/types.d.ts +160 -0
  172. package/dist/social/types.d.ts.map +1 -0
  173. package/dist/surface/api.d.ts +16 -0
  174. package/dist/surface/api.d.ts.map +1 -0
  175. package/dist/surface/request.d.ts +10 -0
  176. package/dist/surface/request.d.ts.map +1 -0
  177. package/dist/surface/signed-in.d.ts +30 -0
  178. package/dist/surface/signed-in.d.ts.map +1 -0
  179. package/dist/types.d.ts +117 -0
  180. package/dist/types.d.ts.map +1 -0
  181. package/dist/wiring.d.ts +56 -0
  182. package/dist/wiring.d.ts.map +1 -0
  183. package/docs/README.md +26 -0
  184. package/docs/guide/api-keys.md +365 -0
  185. package/docs/guide/avatars.md +129 -0
  186. package/docs/guide/context.md +371 -0
  187. package/docs/guide/directives.md +371 -0
  188. package/docs/guide/errors.md +318 -0
  189. package/docs/guide/federation.md +71 -0
  190. package/docs/guide/invitations.md +269 -0
  191. package/docs/guide/passkeys.md +207 -0
  192. package/docs/guide/second-factor.md +238 -0
  193. package/docs/guide/social.md +190 -0
  194. package/docs/guide/step-up.md +208 -0
  195. package/docs/guide/subscriptions.md +255 -0
  196. package/docs/guide/telemetry.md +45 -0
  197. package/docs/roadmap.md +124 -0
  198. package/docs/troubleshooting.md +1265 -0
  199. package/graphql/janus-api-keys.graphqls +237 -0
  200. package/graphql/janus-avatar.graphqls +19 -0
  201. package/graphql/janus-invitations.graphqls +280 -0
  202. package/graphql/janus-passkey-sign-in.graphqls +40 -0
  203. package/graphql/janus-passkeys.graphqls +134 -0
  204. package/graphql/janus-second-factor.graphqls +199 -0
  205. package/graphql/janus-social.graphqls +155 -0
  206. package/graphql/janus.graphqls +44 -0
  207. package/package.json +80 -5
@@ -0,0 +1,371 @@
1
+ # 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 |