@softistx/janus-graphql 0.0.0-stage → 0.30.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (207) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +716 -2
  3. package/dist/api-keys/index.d.ts +11 -0
  4. package/dist/api-keys/index.d.ts.map +1 -0
  5. package/dist/api-keys/resolvers/deps.d.ts +39 -0
  6. package/dist/api-keys/resolvers/deps.d.ts.map +1 -0
  7. package/dist/api-keys/resolvers/index.d.ts +39 -0
  8. package/dist/api-keys/resolvers/index.d.ts.map +1 -0
  9. package/dist/api-keys/resolvers/list.d.ts +16 -0
  10. package/dist/api-keys/resolvers/list.d.ts.map +1 -0
  11. package/dist/api-keys/resolvers/manage.d.ts +17 -0
  12. package/dist/api-keys/resolvers/manage.d.ts.map +1 -0
  13. package/dist/api-keys/sdl.d.ts +14 -0
  14. package/dist/api-keys/sdl.d.ts.map +1 -0
  15. package/dist/api-keys/shape.d.ts +38 -0
  16. package/dist/api-keys/shape.d.ts.map +1 -0
  17. package/dist/api-keys/types.d.ts +149 -0
  18. package/dist/api-keys/types.d.ts.map +1 -0
  19. package/dist/avatar/index.d.ts +32 -0
  20. package/dist/avatar/index.d.ts.map +1 -0
  21. package/dist/avatar/resolvers.d.ts +41 -0
  22. package/dist/avatar/resolvers.d.ts.map +1 -0
  23. package/dist/avatar/sdl.d.ts +16 -0
  24. package/dist/avatar/sdl.d.ts.map +1 -0
  25. package/dist/bad-input.d.ts +17 -0
  26. package/dist/bad-input.d.ts.map +1 -0
  27. package/dist/connection/connection.d.ts +36 -0
  28. package/dist/connection/connection.d.ts.map +1 -0
  29. package/dist/connection/credential.d.ts +34 -0
  30. package/dist/connection/credential.d.ts.map +1 -0
  31. package/dist/connection/types.d.ts +61 -0
  32. package/dist/connection/types.d.ts.map +1 -0
  33. package/dist/context/create.d.ts +32 -0
  34. package/dist/context/create.d.ts.map +1 -0
  35. package/dist/context/index.d.ts +9 -0
  36. package/dist/context/index.d.ts.map +1 -0
  37. package/dist/context/registry.d.ts +72 -0
  38. package/dist/context/registry.d.ts.map +1 -0
  39. package/dist/context/resolve.d.ts +20 -0
  40. package/dist/context/resolve.d.ts.map +1 -0
  41. package/dist/device.d.ts +28 -0
  42. package/dist/device.d.ts.map +1 -0
  43. package/dist/directives/apply.d.ts +51 -0
  44. package/dist/directives/apply.d.ts.map +1 -0
  45. package/dist/directives/guard.d.ts +22 -0
  46. package/dist/directives/guard.d.ts.map +1 -0
  47. package/dist/directives/permission/enforce.d.ts +24 -0
  48. package/dist/directives/permission/enforce.d.ts.map +1 -0
  49. package/dist/directives/permission/model.d.ts +35 -0
  50. package/dist/directives/permission/model.d.ts.map +1 -0
  51. package/dist/directives/permission/path.d.ts +31 -0
  52. package/dist/directives/permission/path.d.ts.map +1 -0
  53. package/dist/directives/permission/validate.d.ts +42 -0
  54. package/dist/directives/permission/validate.d.ts.map +1 -0
  55. package/dist/directives/read.d.ts +43 -0
  56. package/dist/directives/read.d.ts.map +1 -0
  57. package/dist/directives/validate.d.ts +39 -0
  58. package/dist/directives/validate.d.ts.map +1 -0
  59. package/dist/directives/words.d.ts +7 -0
  60. package/dist/directives/words.d.ts.map +1 -0
  61. package/dist/errors/denial.d.ts +6 -0
  62. package/dist/errors/denial.d.ts.map +1 -0
  63. package/dist/errors/index.d.ts +12 -0
  64. package/dist/errors/index.d.ts.map +1 -0
  65. package/dist/errors/janus-error.d.ts +20 -0
  66. package/dist/errors/janus-error.d.ts.map +1 -0
  67. package/dist/errors/mask.d.ts +69 -0
  68. package/dist/errors/mask.d.ts.map +1 -0
  69. package/dist/fresh.d.ts +44 -0
  70. package/dist/fresh.d.ts.map +1 -0
  71. package/dist/helpers.d.ts +56 -0
  72. package/dist/helpers.d.ts.map +1 -0
  73. package/dist/index.d.ts +86 -0
  74. package/dist/index.d.ts.map +1 -0
  75. package/dist/index.js +3393 -0
  76. package/dist/index.js.map +75 -0
  77. package/dist/invitations/index.d.ts +12 -0
  78. package/dist/invitations/index.d.ts.map +1 -0
  79. package/dist/invitations/resolvers/anonymous.d.ts +11 -0
  80. package/dist/invitations/resolvers/anonymous.d.ts.map +1 -0
  81. package/dist/invitations/resolvers/deps.d.ts +38 -0
  82. package/dist/invitations/resolvers/deps.d.ts.map +1 -0
  83. package/dist/invitations/resolvers/index.d.ts +37 -0
  84. package/dist/invitations/resolvers/index.d.ts.map +1 -0
  85. package/dist/invitations/resolvers/owner.d.ts +17 -0
  86. package/dist/invitations/resolvers/owner.d.ts.map +1 -0
  87. package/dist/invitations/sdl/accept.d.ts +7 -0
  88. package/dist/invitations/sdl/accept.d.ts.map +1 -0
  89. package/dist/invitations/sdl/index.d.ts +14 -0
  90. package/dist/invitations/sdl/index.d.ts.map +1 -0
  91. package/dist/invitations/sdl/owner.d.ts +8 -0
  92. package/dist/invitations/sdl/owner.d.ts.map +1 -0
  93. package/dist/invitations/shape.d.ts +63 -0
  94. package/dist/invitations/shape.d.ts.map +1 -0
  95. package/dist/invitations/types/index.d.ts +5 -0
  96. package/dist/invitations/types/index.d.ts.map +1 -0
  97. package/dist/invitations/types/options.d.ts +104 -0
  98. package/dist/invitations/types/options.d.ts.map +1 -0
  99. package/dist/invitations/types/out.d.ts +136 -0
  100. package/dist/invitations/types/out.d.ts.map +1 -0
  101. package/dist/invitations/types/surface.d.ts +18 -0
  102. package/dist/invitations/types/surface.d.ts.map +1 -0
  103. package/dist/map-code.d.ts +10 -0
  104. package/dist/map-code.d.ts.map +1 -0
  105. package/dist/mask-error.d.ts +18 -0
  106. package/dist/mask-error.d.ts.map +1 -0
  107. package/dist/memo.d.ts +16 -0
  108. package/dist/memo.d.ts.map +1 -0
  109. package/dist/options.d.ts +17 -0
  110. package/dist/options.d.ts.map +1 -0
  111. package/dist/passkeys/deps.d.ts +23 -0
  112. package/dist/passkeys/deps.d.ts.map +1 -0
  113. package/dist/passkeys/first-factor.types.d.ts +38 -0
  114. package/dist/passkeys/first-factor.types.d.ts.map +1 -0
  115. package/dist/passkeys/index.d.ts +14 -0
  116. package/dist/passkeys/index.d.ts.map +1 -0
  117. package/dist/passkeys/resolvers.d.ts +23 -0
  118. package/dist/passkeys/resolvers.d.ts.map +1 -0
  119. package/dist/passkeys/sdl.d.ts +14 -0
  120. package/dist/passkeys/sdl.d.ts.map +1 -0
  121. package/dist/passkeys/shape.d.ts +14 -0
  122. package/dist/passkeys/shape.d.ts.map +1 -0
  123. package/dist/passkeys/sign-in.resolvers.d.ts +19 -0
  124. package/dist/passkeys/sign-in.resolvers.d.ts.map +1 -0
  125. package/dist/passkeys/sign-in.sdl.d.ts +16 -0
  126. package/dist/passkeys/sign-in.sdl.d.ts.map +1 -0
  127. package/dist/passkeys/types.d.ts +193 -0
  128. package/dist/passkeys/types.d.ts.map +1 -0
  129. package/dist/plugin.d.ts +59 -0
  130. package/dist/plugin.d.ts.map +1 -0
  131. package/dist/renewal.d.ts +51 -0
  132. package/dist/renewal.d.ts.map +1 -0
  133. package/dist/report.d.ts +29 -0
  134. package/dist/report.d.ts.map +1 -0
  135. package/dist/sdl.d.ts +12 -0
  136. package/dist/sdl.d.ts.map +1 -0
  137. package/dist/second-factor/index.d.ts +12 -0
  138. package/dist/second-factor/index.d.ts.map +1 -0
  139. package/dist/second-factor/resolvers/deps.d.ts +39 -0
  140. package/dist/second-factor/resolvers/deps.d.ts.map +1 -0
  141. package/dist/second-factor/resolvers/index.d.ts +39 -0
  142. package/dist/second-factor/resolvers/index.d.ts.map +1 -0
  143. package/dist/second-factor/resolvers/sign-in.d.ts +10 -0
  144. package/dist/second-factor/resolvers/sign-in.d.ts.map +1 -0
  145. package/dist/second-factor/resolvers/status.d.ts +10 -0
  146. package/dist/second-factor/resolvers/status.d.ts.map +1 -0
  147. package/dist/second-factor/resolvers/step-up.d.ts +16 -0
  148. package/dist/second-factor/resolvers/step-up.d.ts.map +1 -0
  149. package/dist/second-factor/resolvers/writes.d.ts +19 -0
  150. package/dist/second-factor/resolvers/writes.d.ts.map +1 -0
  151. package/dist/second-factor/sdl.d.ts +14 -0
  152. package/dist/second-factor/sdl.d.ts.map +1 -0
  153. package/dist/second-factor/shape.d.ts +18 -0
  154. package/dist/second-factor/shape.d.ts.map +1 -0
  155. package/dist/second-factor/types/index.d.ts +5 -0
  156. package/dist/second-factor/types/index.d.ts.map +1 -0
  157. package/dist/second-factor/types/options.d.ts +61 -0
  158. package/dist/second-factor/types/options.d.ts.map +1 -0
  159. package/dist/second-factor/types/out.d.ts +84 -0
  160. package/dist/second-factor/types/out.d.ts.map +1 -0
  161. package/dist/second-factor/types/surface.d.ts +89 -0
  162. package/dist/second-factor/types/surface.d.ts.map +1 -0
  163. package/dist/social/index.d.ts +10 -0
  164. package/dist/social/index.d.ts.map +1 -0
  165. package/dist/social/resolvers.d.ts +25 -0
  166. package/dist/social/resolvers.d.ts.map +1 -0
  167. package/dist/social/sdl.d.ts +13 -0
  168. package/dist/social/sdl.d.ts.map +1 -0
  169. package/dist/social/shape.d.ts +11 -0
  170. package/dist/social/shape.d.ts.map +1 -0
  171. package/dist/social/types.d.ts +160 -0
  172. package/dist/social/types.d.ts.map +1 -0
  173. package/dist/surface/api.d.ts +16 -0
  174. package/dist/surface/api.d.ts.map +1 -0
  175. package/dist/surface/request.d.ts +10 -0
  176. package/dist/surface/request.d.ts.map +1 -0
  177. package/dist/surface/signed-in.d.ts +30 -0
  178. package/dist/surface/signed-in.d.ts.map +1 -0
  179. package/dist/types.d.ts +117 -0
  180. package/dist/types.d.ts.map +1 -0
  181. package/dist/wiring.d.ts +56 -0
  182. package/dist/wiring.d.ts.map +1 -0
  183. package/docs/README.md +26 -0
  184. package/docs/guide/api-keys.md +365 -0
  185. package/docs/guide/avatars.md +129 -0
  186. package/docs/guide/context.md +371 -0
  187. package/docs/guide/directives.md +371 -0
  188. package/docs/guide/errors.md +318 -0
  189. package/docs/guide/federation.md +71 -0
  190. package/docs/guide/invitations.md +269 -0
  191. package/docs/guide/passkeys.md +207 -0
  192. package/docs/guide/second-factor.md +238 -0
  193. package/docs/guide/social.md +190 -0
  194. package/docs/guide/step-up.md +208 -0
  195. package/docs/guide/subscriptions.md +255 -0
  196. package/docs/guide/telemetry.md +45 -0
  197. package/docs/roadmap.md +124 -0
  198. package/docs/troubleshooting.md +1265 -0
  199. package/graphql/janus-api-keys.graphqls +237 -0
  200. package/graphql/janus-avatar.graphqls +19 -0
  201. package/graphql/janus-invitations.graphqls +280 -0
  202. package/graphql/janus-passkey-sign-in.graphqls +40 -0
  203. package/graphql/janus-passkeys.graphqls +134 -0
  204. package/graphql/janus-second-factor.graphqls +199 -0
  205. package/graphql/janus-social.graphqls +155 -0
  206. package/graphql/janus.graphqls +44 -0
  207. package/package.json +80 -5
@@ -0,0 +1,1265 @@
1
+ # Troubleshooting `@softistx/janus-graphql`
2
+
3
+ Installing `@softistx/janus*` fails with a 401 or 404? See
4
+ [the install entry](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#installing-softistx-packages).
5
+
6
+ Each entry is headed by what you see: a compiler error, a `TypeError` at
7
+ start-up or in a response, a warning, or a code and its status. Search this page for its
8
+ words.
9
+
10
+ This package **defines no error class**. A denial is a `GraphQLError`; any
11
+ other code is one of `@softistx/janus`'s — see
12
+ [`@softistx/janus`'s troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md)
13
+ for what causes each.
14
+
15
+ ## Index
16
+
17
+ **Install**
18
+ - [Optional peers are installed as required](#optional-peers-are-installed-as-required)
19
+
20
+ **At start-up**
21
+ - [`TypeError: applyJanusDirectives(): @authenticated on … names the user type '…', which is not one of …`](#typeerror-applyjanusdirectives-authenticated-on--names-the-user-type--which-is-not-one-of-)
22
+ - [`TypeError: applyJanusDirectives(): @authenticated on … names no user type`](#typeerror-applyjanusdirectives-authenticated-on--names-no-user-type)
23
+ - [`TypeError: applyJanusDirectives(): the @authenticated on … admit no user type in common`](#typeerror-applyjanusdirectives-the-authenticated-on--admit-no-user-type-in-common)
24
+ - [`TypeError: applyJanusDirectives(): @fresh on … asks maxAge: …`](#typeerror-applyjanusdirectives-fresh-on--asks-maxage-)
25
+ - [`TypeError: applyJanusDirectives(): @permission on … needs the permissions() instance`](#typeerror-applyjanusdirectives-permission-on--needs-the-permissions-instance)
26
+ - [`TypeError: applyJanusDirectives(): @permission on … names the object type '…', which is not one of …`](#typeerror-applyjanusdirectives-permission-on--names-the-object-type--which-is-not-one-of-)
27
+ - [`TypeError: applyJanusDirectives(): @permission on … asks '…', which … does not declare`](#typeerror-applyjanusdirectives-permission-on--asks--which--does-not-declare)
28
+ - [`TypeError: applyJanusDirectives(): @permission on … reads its id from '…', which is not args.<name> or parent.<name>`](#typeerror-applyjanusdirectives-permission-on--reads-its-id-from--which-is-not-argsname-or-parentname)
29
+ - [`TypeError: applyJanusDirectives(): @permission on … reads args.…, and … takes no argument …`](#typeerror-applyjanusdirectives-permission-on--reads-args-and--takes-no-argument-)
30
+ - [`TypeError: applyJanusDirectives(): @permission on … reads the …'s id from …, and … reads '…' of the object itself (fromField)`](#typeerror-applyjanusdirectives-permission-on--reads-the-s-id-from--and--reads--of-the-object-itself-fromfield)
31
+ - [`TypeError: applyJanusDirectives(): @permission on … asks '…' of …, which reaches a when()`](#typeerror-applyjanusdirectives-permission-on--asks--of--which-reaches-a-when)
32
+ - [`TypeError: applyJanusDirectives(): @permission on … finds loaders.…, which is not a function`](#typeerror-applyjanusdirectives-permission-on--finds-loaders-which-is-not-a-function)
33
+ - [`Unknown directive "@authenticated"`, `"@fresh"` or `"@permission"`](#unknown-directive-authenticated-fresh-or-permission)
34
+ - [`Argument "@fresh(maxAge:)" of type "Int!" is required`, or `Argument "maxAge" has invalid value …`](#argument-freshmaxage-of-type-int-is-required-or-argument-maxage-has-invalid-value-)
35
+ - [`TypeError: applyJanusDirectives(): type '…' is not a user type of auth`](#typeerror-applyjanusdirectives-type--is-not-a-user-type-of-auth)
36
+ - [`TypeError: useJanus(): auth is not what janus() answered`](#typeerror-usejanus-auth-is-not-what-janus-answered)
37
+ - [`TypeError: useJanus(): the auth resolver answered no janus() instance for this request`](#typeerror-usejanus-the-auth-resolver-answered-no-janus-instance-for-this-request)
38
+ - [`TypeError: useJanus(): the auth resolver answered something that is not what janus() answered`](#typeerror-usejanus-the-auth-resolver-answered-something-that-is-not-what-janus-answered)
39
+ - [`TypeError: useJanus(): access is not what permissions() answered`](#typeerror-usejanus-access-is-not-what-permissions-answered)
40
+ - [`TypeError: useJanus(): clock is not a Clock`](#typeerror-usejanus-clock-is-not-a-clock)
41
+ - [`TypeError: janusConnection(): auth is not what janus() answered`, `access …`, `clock …`](#typeerror-janusconnection-auth-is-not-what-janus-answered-access--clock-)
42
+ - [`TypeError: janusConnection(): upgrade is not a function`](#typeerror-janusconnection-upgrade-is-not-a-function)
43
+
44
+ **Over graphql-ws**
45
+ - [The socket closed `4403: Forbidden` right after connecting](#the-socket-closed-4403-forbidden-right-after-connecting)
46
+ - [The socket closed `4500`](#the-socket-closed-4500)
47
+ - [A stream keeps its events after its session was revoked](#a-stream-keeps-its-events-after-its-session-was-revoked)
48
+ - [`TypeError: janusConnection(): the connection's extra is not an object`](#typeerror-janusconnection-the-connections-extra-is-not-an-object)
49
+ - [`TypeError: deviceOf(): the GraphQL context has no request — …`](#typeerror-deviceof-the-graphql-context-has-no-request--)
50
+
51
+ **In a response**
52
+ - [`UNAUTHENTICATED` for a signed-in user](#unauthenticated-for-a-signed-in-user)
53
+ - [`MAGIC_LINK_DISABLED`, 404, `Not found`](#magic_link_disabled-404-not-found)
54
+ - [`MAIL_THROTTLED`, 429, `Too many requests, retry later`](#mail_throttled-429-too-many-requests-retry-later)
55
+ - [`BAD_USER_INPUT`, 400, `size must be a positive integer`](#bad_user_input-400-size-must-be-a-positive-integer)
56
+ - [A completed social sign-in sets no session cookie](#a-completed-social-sign-in-sets-no-session-cookie)
57
+ - [A response that answers the session token is cached](#a-response-that-answers-the-session-token-is-cached)
58
+ - [A response that answers a challenge or a flow is cached](#a-response-that-answers-a-challenge-or-a-flow-is-cached)
59
+ - [`FLOW_MISMATCH` on the callback, though the visitor did nothing wrong](#flow_mismatch-on-the-callback-though-the-visitor-did-nothing-wrong)
60
+ - [`PROVIDER_ERROR`, 502, `Bad gateway`](#provider_error-502-bad-gateway)
61
+ - [`TypeError: socialResolvers(): the GraphQL context has no request`](#typeerror-socialresolvers-the-graphql-context-has-no-request)
62
+ - [`UNAUTHENTICATED`, 401, on every social field](#unauthenticated-401-on-every-social-field)
63
+ - [`BAD_USER_INPUT`, 400, on `socialSignInComplete`](#bad_user_input-400-on-socialsignincomplete)
64
+ - [`TypeError: secondFactorResolvers(): auth has no secondFactor surface — …`, `… auth.<type> has no secondFactor — …`](#typeerror-secondfactorresolvers-auth-has-no-secondfactor-surface--)
65
+ - [`UNAUTHENTICATED`, 401, on every second-factor field](#unauthenticated-401-on-every-second-factor-field)
66
+ - [`TypeError: secondFactorResolvers(): freshWithin is a duration with its unit`](#typeerror-secondfactorresolvers-freshwithin-is-a-duration-with-its-unit)
67
+ - [`TypeError: secondFactorResolvers(): the GraphQL context has no request`](#typeerror-secondfactorresolvers-the-graphql-context-has-no-request)
68
+ - [`TypeError: secondFactorResolvers(): a step-up by e-mail needs sendStepUpCode`](#typeerror-secondfactorresolvers-a-step-up-by-e-mail-needs-sendstepupcode)
69
+ - [`TypeError: secondFactorResolvers(): <caller> needs a step-up`](#typeerror-secondfactorresolvers-caller-needs-a-step-up)
70
+ - [`UNAUTHENTICATED` on a second-factor write with an API key](#unauthenticated-on-a-second-factor-write-with-an-api-key)
71
+ - [`TypeError: passkeyResolvers(): auth has no passkeys — …`](#typeerror-passkeyresolvers-auth-has-no-passkeys--)
72
+ - [`TypeError: passkeyResolvers(): the GraphQL context has no request`](#typeerror-passkeyresolvers-the-graphql-context-has-no-request)
73
+ - [`CREDENTIALS_INVALID` or `TOKEN_*` on `passkeySignIn`](#credentials_invalid-or-token_-on-passkeysignin)
74
+ - [`TypeError: … passkeys.firstFactor` on `passkeySignInOptions`](#typeerror--passkeysfirstfactor-on-passkeysigninoptions)
75
+ - [`BAD_USER_INPUT`, 400, on a passkey field](#bad_user_input-400-on-a-passkey-field)
76
+ - [`PASSKEY_INVALID`, `PASSKEY_TAKEN` or `STEP_UP_REQUIRED` on `registerPasskey`](#passkey_invalid-passkey_taken-or-step_up_required-on-registerpasskey)
77
+ - [A passkey sign-in sets no session cookie](#a-passkey-sign-in-sets-no-session-cookie)
78
+ - [`TypeError: invitationResolvers(): auth has no invitations — …`](#typeerror-invitationresolvers-auth-has-no-invitations--)
79
+ - [`` TypeError: invitationResolvers(): `authorize` is required … ``](#typeerror-invitationresolvers-authorize-is-required-)
80
+ - [`TypeError: invitationResolvers(): … the code would reach nobody`](#typeerror-invitationresolvers--the-code-would-reach-nobody)
81
+ - [`NOT_FOUND` on `issueInvitation` for an owner](#not_found-on-issueinvitation-for-an-owner)
82
+ - [`INVITATION_INVALID` on `acceptInvitation` after the preview worked](#invitation_invalid-on-acceptinvitation-after-the-preview-worked)
83
+ - [`BAD_USER_INPUT`, 400, on `invitations(after:)`](#bad_user_input-400-on-invitationsafter)
84
+ - [`BAD_USER_INPUT`, 400, with a `field`, on an invitation argument](#bad_user_input-400-with-a-field-on-an-invitation-argument)
85
+ - [`invitations.issue: type must be one of …`](#invitationsissue-type-must-be-one-of-)
86
+ - [A response that answers the invitation code is cached](#a-response-that-answers-the-invitation-code-is-cached)
87
+ - [`TypeError: apiKeysResolvers(): auth has no apiKeys — …`](#typeerror-apikeysresolvers-auth-has-no-apikeys--)
88
+ - [`` TypeError: apiKeysResolvers(): `authorize` needs `create`, `list` and `revoke` … ``](#typeerror-apikeysresolvers-authorize-needs-create-list-and-revoke--)
89
+ - [`TypeError: apiKeysResolvers(): lifetimes …`](#typeerror-apikeysresolvers-lifetimes-)
90
+ - [`BAD_USER_INPUT`, 400, on `createApiKey(lifetimeDays:)`](#bad_user_input-400-on-createapikeylifetimedays)
91
+ - [`NOT_FOUND` on an API key field with `boundTo`](#not_found-on-an-api-key-field-with-boundto)
92
+ - [`STEP_UP_REQUIRED` on `createApiKey` from a request signed by a key](#step_up_required-on-createapikey-from-a-request-signed-by-a-key)
93
+ - [`CREDENTIALS_INVALID` with `retryAfter`, 401, for the right password](#credentials_invalid-with-retryafter-401-for-the-right-password)
94
+ - [`CODE_INVALID` with `retryAfter`, 401, `too many codes tried`](#code_invalid-with-retryafter-401-too-many-codes-tried)
95
+ - [`FORBIDDEN` where the user should be allowed](#forbidden-where-the-user-should-be-allowed)
96
+ - [`STEP_UP_REQUIRED`, 403](#step_up_required-403)
97
+ - [`STEP_UP_REQUIRED` for a user who just signed in](#step_up_required-for-a-user-who-just-signed-in)
98
+ - [`SERVICE_UNAVAILABLE`, 503, on every guarded field](#service_unavailable-503-on-every-guarded-field)
99
+ - [`Unexpected error.`, 500, where a `JanusError` was thrown](#unexpected-error-500-where-a-januserror-was-thrown)
100
+ - [`TypeError: … ctx.janus is not set`](#typeerror--ctxjanus-is-not-set)
101
+ - [`TypeError: …: the GraphQL context has no request to authenticate`](#typeerror--the-graphql-context-has-no-request-to-authenticate)
102
+ - [`TypeError: can(): ctx.janus.access is not set`](#typeerror-can-ctxjanusaccess-is-not-set)
103
+ - [`TypeError: requireUser(): type is an empty list, which no user could pass`](#typeerror-requireuser-type-is-an-empty-list-which-no-user-could-pass)
104
+ - [`TypeError: requireFresh(): maxAge is a duration with its unit`](#typeerror-requirefresh-maxage-is-a-duration-with-its-unit)
105
+ - [`TypeError: requireFresh(): maxAge: "…" is not a duration`](#typeerror-requirefresh-maxage--is-not-a-duration)
106
+ - [`TypeError: requireFresh(): maxAge: a duration must be above zero`](#typeerror-requirefresh-maxage-a-duration-must-be-above-zero)
107
+ - [`@permission on … resolved no object id from … — answered NOT_FOUND`](#permission-on--resolved-no-object-id-from---answered-not_found)
108
+ - [`NOT_FOUND` where the user should be allowed](#not_found-where-the-user-should-be-allowed)
109
+ - [A 403 that tells a user the object exists](#a-403-that-tells-a-user-the-object-exists)
110
+ - [`Unexpected error.`, 500, on a field `@permission` guards](#unexpected-error-500-on-a-field-permission-guards)
111
+ - [`TypeError: @permission on …: ctx.janus.access is not set`](#typeerror-permission-on--ctxjanusaccess-is-not-set)
112
+ - [`TypeError: @permission on …: loaders.… answered …`](#typeerror-permission-on--loaders-answered-)
113
+ - [The session cookie expires while the user is active](#the-session-cookie-expires-while-the-user-is-active)
114
+ - [`Warning: janusMaskError: report failed on …`](#warning-janusmaskerror-report-failed-on-)
115
+ - [A 401 whose `data` still holds the other fields](#a-401-whose-data-still-holds-the-other-fields)
116
+ - [`RangeError: deviceCookie(): maxAge must be a number of seconds from 0 to 34560000 (400 days), got …`](#rangeerror-devicecookie-maxage-must-be-a-number-of-seconds-from-0-to-34560000-400-days-got-)
117
+ - [`TypeError: deviceCookie(): …` (a name, prefix or attribute the browser would refuse)](#typeerror-devicecookie--a-name-prefix-or-attribute-the-browser-would-refuse)
118
+
119
+ **Types**
120
+ - [`'user' is possibly 'null'`](#user-is-possibly-null)
121
+ - [`Property 'access' does not exist on type …`](#property-access-does-not-exist-on-type-)
122
+ - [`Expected 4 arguments, but got 3`, on `can()`](#expected-4-arguments-but-got-3-on-can)
123
+ - [`'…' does not exist in type 'Loaders<…>'`, or `'Conditions<…>'`](#-does-not-exist-in-type-loaders-or-conditions)
124
+ - [`Type '{ …: … }' is not assignable to type 'never'`, on `loaders`](#type-----is-not-assignable-to-type-never-on-loaders)
125
+ - [`Source has 0 element(s) but target requires 1`, on `requireUser()`](#source-has-0-elements-but-target-requires-1-on-requireuser)
126
+ - [`Argument of type '600' is not assignable to parameter of type '`${number}ms` | …'`, on `requireFresh()`](#argument-of-type-600-is-not-assignable-to-parameter-of-type-numberms---on-requirefresh)
127
+ - [`Expected 2 arguments, but got 1`, on `requireFresh()`](#expected-2-arguments-but-got-1-on-requirefresh)
128
+ - [`Type 'number' is not assignable to type 'Clock'`](#type-number-is-not-assignable-to-type-clock)
129
+
130
+ ## At start-up
131
+
132
+ ### `TypeError: applyJanusDirectives(): @authenticated on … names the user type '…', which is not one of …`
133
+
134
+ **When:** the server builds its schema — `createYoga()` with `useJanus()`, or
135
+ `applyJanusDirectives()` called yourself.
136
+
137
+ **Why:** a `type:` names a user type `janus()` does not declare — a typo, or a
138
+ type of another instance. Under `useJanus({ type: 'staff' })`, `'staff'` is
139
+ the only one a directive may name. `(read by Ward.name)` says the directive is
140
+ on the type `Ward`, read for its field `name`.
141
+
142
+ **Fix:** name a user type of `auth.types`.
143
+
144
+ ```graphql
145
+ type Query {
146
+ roster: [Staff!]! @authenticated(type: ["staff"]) # not "doctor"
147
+ }
148
+ ```
149
+
150
+ ### `TypeError: applyJanusDirectives(): @authenticated on … names no user type`
151
+
152
+ **Why:** `@authenticated(type: [])` admits nobody, so every request would be
153
+ refused.
154
+
155
+ **Fix:** leave `type:` out to admit any signed-in user —
156
+ `@authenticated` — or name the user types.
157
+
158
+ ### `TypeError: applyJanusDirectives(): the @authenticated on … admit no user type in common`
159
+
160
+ **Why:** every `@authenticated` that applies must hold — the field's, its
161
+ type's, its interfaces' — and their `type:` lists share no user type.
162
+
163
+ ```graphql
164
+ type Ward @authenticated(type: ["staff"]) {
165
+ chart: String @authenticated(type: ["patient"]) # staff AND patient: nobody
166
+ }
167
+ ```
168
+
169
+ **Fix:** widen one of them, or move the field to a type whose directive
170
+ admits the users it is for.
171
+
172
+ ### `TypeError: applyJanusDirectives(): @fresh on … asks maxAge: …`
173
+
174
+ **When:** at start-up, for a schema that uses `@fresh`.
175
+
176
+ **Why:** `maxAge` is not above zero — `@fresh(maxAge: 0)` or a negative
177
+ number — so no session could ever be fresh enough, and every request would
178
+ be refused. The message names the field, and the location the directive was
179
+ written on when it is not the field: `@fresh on Account (read by
180
+ Account.email)`.
181
+
182
+ **Fix:** write a number of **seconds** above zero:
183
+
184
+ ```graphql
185
+ type Mutation {
186
+ changeEmail(email: String!): User @fresh(maxAge: 600) # ten minutes
187
+ }
188
+ ```
189
+
190
+ ### `TypeError: applyJanusDirectives(): @permission on … needs the permissions() instance`
191
+
192
+ **When:** at start-up, for a schema that uses `@permission`.
193
+
194
+ **Why:** `useJanus()` — or `applyJanusDirectives()` — was given no `access`,
195
+ or, through `applyJanusDirectives()`, an object with no `model`: the
196
+ directive reads the object types and permissions from `access.model`.
197
+ (`useJanus()` refuses an `access` without `can` earlier — see
198
+ [`access is not what permissions() answered`](#typeerror-usejanus-access-is-not-what-permissions-answered).)
199
+
200
+ **Fix:** `useJanus({ auth, access })`. An instance wrapped by
201
+ `instrumentPermissions()` keeps its `model`, and works as the plain one.
202
+
203
+ ### `TypeError: applyJanusDirectives(): @permission on … names the object type '…', which is not one of …`
204
+
205
+ **Why:** `type:` names an object type the model does not declare — a typo, a
206
+ user type, or a type of another model. The message lists the model's.
207
+
208
+ **Fix:** name one of them: `@permission(name: "view", type: "record")`.
209
+
210
+ ### `TypeError: applyJanusDirectives(): @permission on … asks '…', which … does not declare`
211
+
212
+ **Why:** `name:` is neither a relation nor a permission of that type — what
213
+ `access.can` would refuse too. The message lists what the type declares.
214
+
215
+ **Fix:** name one of them, or add the permission to the model:
216
+
217
+ ```ts
218
+ record: { related: { owners: ['patient'] }, permits: { view: ['owners'], delete: ['owners'] } },
219
+ ```
220
+
221
+ ### `TypeError: applyJanusDirectives(): @permission on … reads its id from '…', which is not args.<name> or parent.<name>`
222
+
223
+ **Why:** `id:` is not a path: it must start with `args.` or `parent.`,
224
+ followed by one or more names — letters, numbers and `_`, not starting with a
225
+ number — separated by dots. `"id"`, `"args"`, `"record.id"` and
226
+ `"parent..id"` are not.
227
+
228
+ **Fix:** `id: "args.recordId"`, `id: "args.input.recordId"`,
229
+ `id: "parent.recordId"`.
230
+
231
+ ### `TypeError: applyJanusDirectives(): @permission on … reads args.…, and … takes no argument …`
232
+
233
+ **Why:** the path's first name is not an argument of the field it guards.
234
+ Two common causes:
235
+
236
+ - the field names its argument otherwise — `record(recordId: ID!)` read
237
+ through the default, `args.id`;
238
+ - the default is not what you meant: on a **field**, the default is
239
+ `args.id` even when the field belongs to the object, and the message then
240
+ ends with `— name the id with id: "parent.<field>" or id: "args.<name>"`;
241
+ on a **type**, `id: "args.…"` must be an argument of every field of the
242
+ type.
243
+
244
+ **Fix:** name the path: `@permission(name: "view", type: "record", id: "args.recordId")`,
245
+ or `id: "parent.id"` for the object a field belongs to.
246
+
247
+ ### `TypeError: applyJanusDirectives(): @permission on … reads the …'s id from …, and … reads '…' of the object itself (fromField)`
248
+
249
+ **Why:** the type has a `fromField` relation, read from the object's own
250
+ data, and the directive has only an id — from `args`, or from a field of the
251
+ parent other than its `id`. `access.can` would have nothing to read the field
252
+ from.
253
+
254
+ **Fix:** give the type a loader, which answers the object for an id:
255
+
256
+ ```ts
257
+ useJanus({ auth, access, loaders: { record: (id, ctx) => records.find(id) } });
258
+ ```
259
+
260
+ Where the parent *is* the object — a type-level `@permission`, or
261
+ `id: "parent.id"` — no loader is needed: the parent is checked itself, and
262
+ must carry the field.
263
+
264
+ ### `TypeError: applyJanusDirectives(): @permission on … asks '…' of …, which reaches a when()`
265
+
266
+ **Why:** the permission's rules reach a condition, whose `ctx` `access.can`
267
+ requires, and `useJanus()` has no `conditions` entry for the type to answer
268
+ it.
269
+
270
+ **Fix:**
271
+
272
+ ```ts
273
+ useJanus({
274
+ auth,
275
+ access,
276
+ conditions: { record: (record, ctx: Context) => ({ onShift: ctx.shift.open }) },
277
+ });
278
+ ```
279
+
280
+ ### `TypeError: applyJanusDirectives(): @permission on … finds loaders.…, which is not a function`
281
+
282
+ **Why:** a `loaders` entry is something else — the repository object rather
283
+ than a function of it, from JavaScript or past a cast.
284
+
285
+ **Fix:** `loaders: { record: (id) => records.find(id) }`.
286
+
287
+ ### `Unknown directive "@authenticated"`, `"@fresh"` or `"@permission"`
288
+
289
+ **Why:** graphql-js builds the schema before `useJanus()` sees it, and the
290
+ directive is not declared.
291
+
292
+ **Fix:** put `janusTypeDefs` among the type definitions:
293
+ `createSchema({ typeDefs: [janusTypeDefs, typeDefs], resolvers })`. A code
294
+ generator reading files takes
295
+ `node_modules/@softistx/janus-graphql/graphql/janus.graphqls`.
296
+
297
+ ### `Argument "@fresh(maxAge:)" of type "Int!" is required`, or `Argument "maxAge" has invalid value …`
298
+
299
+ graphql 16 words the first `Directive "@fresh" argument "maxAge" of type
300
+ "Int!" is required, but it was not provided.`
301
+
302
+ **Why:** graphql-js refuses the directive at start-up: `@fresh` without
303
+ `maxAge`, when the schema is built; or with a value that is not an `Int` —
304
+ a fraction, a string such as `"10m"` — when `useJanus()` reads it.
305
+
306
+ **Fix:** a whole number of seconds: `@fresh(maxAge: 600)`. A duration with a
307
+ unit belongs to `requireFresh(ctx, '10m')`, in a resolver.
308
+
309
+ ### `TypeError: applyJanusDirectives(): type '…' is not a user type of auth`
310
+
311
+ **When:** at start-up, with `useJanus({ auth, type })` or
312
+ `applyJanusDirectives(schema, { auth, type })` — from JavaScript, or with a
313
+ `type` cast past the compiler, which otherwise refuses it.
314
+
315
+ **Why:** `type` names a user type `janus()` does not declare. The message
316
+ lists the ones it does: `— it knows 'patient', 'staff'`.
317
+
318
+ **Fix:** name one of `auth.types`: `useJanus({ auth, type: 'staff' })`.
319
+
320
+ ### `TypeError: useJanus(): auth is not what janus() answered`
321
+
322
+ **Why:** `auth` has no `authenticate` — the `permissions()` instance passed in
323
+ its place, or the module that exports `auth` not loaded yet.
324
+
325
+ **Fix:** `useJanus({ auth, access })`, with `auth` what `janus()` answered —
326
+ or a function answering it per request.
327
+
328
+ ### `TypeError: useJanus(): the auth resolver answered no janus() instance for this request`
329
+
330
+ **Why:** `auth` is a function (one server, several issuers) and it answered
331
+ `null` or `undefined` for this request — a host or header no issuer owns. The
332
+ same text reads `janusConnection(): … for this connection` over graphql-ws,
333
+ where the socket closes `4500`. It is raised when `ctx.janus.user()` or
334
+ `session()` is first asked, not at start-up.
335
+
336
+ **Fix:** answer the instance for every request you serve, or throw the error
337
+ you want the client to read:
338
+
339
+ ```ts
340
+ useJanus({
341
+ auth: (ctx) => {
342
+ const instance = issuers[new URL(ctx.request?.url ?? 'http://x').host];
343
+ if (instance === undefined) throw denial('FORBIDDEN', 'unknown issuer');
344
+ return instance;
345
+ },
346
+ });
347
+ ```
348
+
349
+ ### `TypeError: useJanus(): the auth resolver answered something that is not what janus() answered`
350
+
351
+ **Why:** the function returned a value without `authenticate` — the
352
+ `permissions()` instance, a plain object, or a lookup that found the wrong
353
+ entry.
354
+
355
+ **Fix:** return what `janus()` answered for that issuer.
356
+
357
+ ### `TypeError: useJanus(): access is not what permissions() answered`
358
+
359
+ **Why:** `access` has no `can` — `janus()`'s instance passed in its place,
360
+ `null`, or the module that exports `access` not loaded yet.
361
+
362
+ **Fix:** `useJanus({ auth, access })`, with `access` what `permissions()`
363
+ answered — or leave `access` out when no field uses `@permission` or `can()`.
364
+
365
+ ### `TypeError: useJanus(): clock is not a Clock`
366
+
367
+ **Why:** `clock` has no `now()` — a timestamp such as `Date.now()`, or a
368
+ `Date`, passed from JavaScript or cast past the compiler.
369
+
370
+ **Fix:** pass the clock given to `janus()` — `fixedClock(…)` from
371
+ `@softistx/janus` in a spec — or leave `clock` out for the system's:
372
+ `useJanus({ auth, clock })`.
373
+
374
+ ### `TypeError: janusConnection(): auth is not what janus() answered`, `access …`, `clock …`
375
+
376
+ **Why:** the same checks as `useJanus()`'s, named for `janusConnection()`:
377
+ `auth` is not what `janus()` answered, `access` not what `permissions()`
378
+ answered, `clock` not a `Clock`.
379
+
380
+ **Fix:** `janusConnection({ auth })`, with the `access` and `clock` given to
381
+ `useJanus()` when you pass them at all.
382
+
383
+ ### `TypeError: janusConnection(): upgrade is not a function`
384
+
385
+ **Why:** `upgrade` is how `onConnect` finds the upgrade request on a
386
+ transport whose `extra` does not carry it, and it was given something else.
387
+
388
+ **Fix:** a function of graphql-ws's context, or nothing — `ctx.extra.request`
389
+ is then read, as `graphql-ws/use/ws` sets it:
390
+
391
+ ```ts
392
+ janusConnection({ auth, upgrade: (ctx: { readonly extra: { readonly socket: Upgraded } }) => ctx.extra.socket.data.request });
393
+ ```
394
+
395
+ ## Over graphql-ws
396
+
397
+ ### The socket closed `4403: Forbidden` right after connecting
398
+
399
+ **Why:** `onConnect` found no credential that authenticates: none at all,
400
+ an unknown or lapsed token, a user gone or inactive, a user of another
401
+ type than `janusConnection({ type })`, or a `connectionParams.authorization`
402
+ that is not a string. A `Bearer` `connectionParams.authorization` is
403
+ read before the upgrade request, and **the first present wins**: a lapsed
404
+ token there refuses the connection even beside a live cookie. One of
405
+ another scheme (`Basic …`) does not count, and the cookie is read.
406
+
407
+ **Fix:** send `connectionParams: { authorization: 'Bearer <token>' }` —
408
+ the key lower-case — or connect from a browser holding the session cookie,
409
+ to the origin that set it. On Bun, pass `upgrade`, or the cookie is never
410
+ read. graphql-ws's client retries a `4403`; a `connectionParams` function
411
+ is asked again each time.
412
+
413
+ ### The socket closed `4500`
414
+
415
+ **Why:** the sessions store could not answer while `onConnect`
416
+ authenticated — `STORE_FAILED`. `graphql-ws/use/ws` closes the socket
417
+ `4500` and logs the error with `console.error`. It is an outage, **never a
418
+ refusal**: `4403` would tell the client its session is bad.
419
+
420
+ **Fix:** the store. graphql-ws's client does not retry a `4500` by default;
421
+ set `shouldRetry` to retry an outage.
422
+
423
+ ### A stream keeps its events after its session was revoked
424
+
425
+ **Why:** an operation is authenticated once, when it subscribes, and
426
+ each event's `@authenticated` reads that answer. The next operation on
427
+ the connection is refused `UNAUTHENTICATED`, and a reconnection `4403`.
428
+
429
+ **Fix:** close the session's sockets when you revoke it
430
+ ([the subscriptions guide](guide/subscriptions.md#a-session-revoked-while-connected)).
431
+ A permission revoked needs nothing: `@permission` asks again on every event.
432
+
433
+ ### `TypeError: janusConnection(): the connection's extra is not an object`
434
+
435
+ **Why:** `onConnect` was called with a context whose `extra` is not an
436
+ object — by hand, or by a transport of your own. It remembers the
437
+ connection by that object.
438
+
439
+ **Fix:** pass `onConnect` to graphql-ws's `useServer()` or `makeHandler()`,
440
+ which give it the context they made.
441
+
442
+ ### `TypeError: deviceOf(): the GraphQL context has no request — …`
443
+
444
+ The same holds for `sendDevice()`, which throws `TypeError: sendDevice(): the
445
+ GraphQL context has no request — …`.
446
+
447
+ **When:** a resolver called `deviceOf(ctx.request)` or `sendDevice(ctx.request, …)`
448
+ in an operation served over graphql-ws. There `ctx.request` is `undefined`.
449
+
450
+ **Why:** the device cookie is read from the request's `Cookie` header and set
451
+ through `useJanus()`'s `onResponse`, and a graphql-ws operation has neither a
452
+ request of its own nor an HTTP response to carry a `Set-Cookie`.
453
+
454
+ **Fix:** read and set the device in a sign-in mutation served over HTTP
455
+ through Yoga, as in
456
+ [the context guide](guide/context.md#a-sign-in-mutation-and-the-device-cookie).
457
+ A bearer client has no cookie jar: answer it the `deviceToken` in the
458
+ mutation's result and take it back as an argument of the next sign-in.
459
+
460
+ ### `RangeError: deviceCookie(): maxAge must be a number of seconds from 0 to 34560000 (400 days), got …`
461
+
462
+ **When:** `sendDevice(ctx.request, …)` is called
463
+ with a `maxAge` that is not a finite number from 0 to 34560000 — `NaN`,
464
+ `Infinity`, a negative value, or above 400 days — most often milliseconds
465
+ given where seconds belong. It throws after the sign-in completed: the
466
+ session exists, the response is not sent.
467
+ **Why:** a browser keeps a cookie 400 days at most, and `deviceCookie` refuses
468
+ a `maxAge` it would not keep rather than write it.
469
+ **Fix:** give seconds within 0 to 34560000 — or leave `maxAge` out, which is
470
+ 400 days.
471
+
472
+ ```ts
473
+ sendDevice(ctx.request, token, { maxAge: 60 * 60 * 24 * 180 }); // 180 days
474
+ ```
475
+
476
+ ### `TypeError: deviceCookie(): …` (a name, prefix or attribute the browser would refuse)
477
+
478
+ **When:** `sendDevice(ctx.request, …)` is called
479
+ with a `name` that is not a valid cookie name, a `__Secure-` name without
480
+ `secure: true`, a `__Host-` name without `secure: true`, with a `path` other
481
+ than `'/'` or with a `domain`, or a `domain`, `path` or `sameSite` holding
482
+ `;`, a carriage return or a line feed. The message names the option.
483
+ **Why:** `deviceCookie` refuses what Hono's `setCookie` refuses: a browser
484
+ would drop the cookie, and a `;` or line break in an attribute could inject
485
+ another one.
486
+ **Fix:** meet the prefix's terms, or drop the prefix — `__Host-` asks `Secure`,
487
+ `Path=/` and no `Domain`; [the core entry](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#typeerror-devicecookie--a-name-prefix-or-attribute-the-browser-would-refuse) has the list.
488
+
489
+ ```ts
490
+ sendDevice(ctx.request, token, { name: '__Host-device' }); // Secure, Path=/, no Domain
491
+ ```
492
+
493
+ ## In a response
494
+
495
+ ### `UNAUTHENTICATED` for a signed-in user
496
+
497
+ **Why:** `authenticate` found no session in the request. The usual causes: the
498
+ client sends the cookie to another origin without `credentials: 'include'`;
499
+ the token is in a header `authenticate` does not read; the session lapsed or
500
+ was revoked; or `useJanus({ type })` treats this user's type as anonymous.
501
+
502
+ **Fix:** send `Authorization: Bearer <token>`, `X-Session-Token`, or the
503
+ session cookie; check `useJanus()`'s `type`.
504
+
505
+ ### `MAGIC_LINK_DISABLED`, 404, `Not found`
506
+
507
+ **When:** a resolver of yours calls `auth.magicLink.request`, `prepare` or
508
+ `confirm` on an instance built with `janus({ magicLink: { enabled: false } })`.
509
+ **Why:** the core refuses before any store access; `janusMaskError()` answers
510
+ the code with the status of `statusOf`. **Fix:** enable it, or drop the field
511
+ and hide the button with `auth.magicLink.enabled`.
512
+
513
+ ### `MAIL_THROTTLED`, 429, `Too many requests, retry later`
514
+
515
+ With `extensions.retryAfter` and a `Retry-After` header.
516
+
517
+ **Why:** `@softistx/janus` throttles the requests that hand out something to
518
+ e-mail, on by default: past five for one address (one user, for
519
+ `verifyEmail.send` and an e-mailed `stepUp.request`) in a 10-minute window it
520
+ throws `MAIL_THROTTLED` and issues nothing: a refused request spends and
521
+ rotates nothing, and the last link or code sent still works. An unknown address is counted and
522
+ refused alike. `retryAfter` is the seconds until the window ends.
523
+
524
+ **Fix:** read `extensions.retryAfter` in the client and tell the visitor to use
525
+ the last e-mail they received (it still works), or to wait that many seconds.
526
+ `@softistx/janus` never sees IP addresses: add a per-IP ceiling with `@softistx/redis`
527
+ rate limits. To change
528
+ the limit, `janus({ mail: { throttle: { attempts, window } } })`; in a test
529
+ over a `fixedClock`, advance the clock past `retryAfter`, or wire
530
+ `mail: { throttle: false }`.
531
+
532
+ ### `BAD_USER_INPUT`, 400, `size must be a positive integer`
533
+
534
+ `JanusAvatar.url(size:)` was asked with `0` or a negative number. `avatarResolvers()`
535
+ refuses it before your `url` function runs, with `extensions.code`
536
+ `BAD_USER_INPUT` and `http.status` 400 — the one error of this package that is
537
+ neither a denial nor a `JanusError`.
538
+
539
+ Ask for a size your route stores:
540
+
541
+ ```graphql
542
+ { viewer { avatar { url(size: 64) } } }
543
+ ```
544
+
545
+ A positive size your route does not store is not this error: the URL is built,
546
+ and the route answers 404.
547
+
548
+ ### `TypeError: invitationResolvers(): auth has no invitations — …`
549
+
550
+ **Why:** `auth.invitations` is absent: `janus()` was not given `invitations`, or `auth` is not what `janus()` answered.
551
+
552
+ **Fix:**
553
+
554
+ ```ts
555
+ const auth = janus({ …, invitations: { store: createMemoryInvitations(), create, onAccepted } });
556
+ invitationResolvers({ auth, authorize, sendInvitation });
557
+ ```
558
+
559
+ ### `` TypeError: invitationResolvers(): `authorize` is required … ``
560
+
561
+ **Why:** the core authorises nobody, so the resolvers will not guess who may invite into a scope.
562
+
563
+ **Fix:** pass `authorize(action, { user, scope }, ctx)`, answering `true` for who may do `action` (`'issue'`, `'resend'`, `'revoke'`, `'list'`) in `scope`:
564
+
565
+ ```ts
566
+ // Context: YogaInitialContext & JanusContext<typeof auth, typeof access>; the hooks are methods, so `ctx` takes it.
567
+ authorize: (action, { scope }, ctx: Context) => can(ctx, 'invite', { type: 'organization', id: scope }),
568
+ ```
569
+
570
+ `subject` also carries `input`, `invitation` and `page`: see the table in the [invitations guide](guide/invitations.md#who-may-invite-authorize).
571
+
572
+ ### `TypeError: invitationResolvers(): … the code would reach nobody`
573
+
574
+ **Why:** neither `sendInvitation` nor `answerCode: true` was given, so the code `issueInvitation` makes would be dropped at once and nobody could accept.
575
+
576
+ **Fix:** deliver it with `sendInvitation({ invitation, code }, ctx)` (your e-mail), or answer it with `answerCode: true`.
577
+
578
+ ### `NOT_FOUND` on `issueInvitation` for an owner
579
+
580
+ **Why:** `authorize` answered `false` (or a scope other than the one it allows). A refusal is `NOT_FOUND`, as `@permission`'s default, so a scope's existence is not revealed. It is also the answer for an invitation id of another scope, and for an unknown invitation id on `resendInvitation` and `revokeInvitation`, which answers `NOT_FOUND` whatever `authorize` answers (it is asked without an `invitation`, and its answer is ignored, as is any error but a `GraphQLError` such as a step-up, so a known and an unknown id look alike).
581
+
582
+ **Fix:** log what `authorize` receives (`action`, `scope`, `user`, and `input`, `invitation` or `page`) and check the permission it reads; make sure the `scope` argument is the one your permission model names.
583
+
584
+ ### `INVITATION_INVALID` on `acceptInvitation` after the preview worked
585
+
586
+ **Why:** the code was spent or replaced in between: another accept won (of two concurrent accepts exactly one does), the owner called `resendInvitation` (the old code stops working) or `revokeInvitation`, or the invitation lapsed. `extensions.reason` tells them apart: `accepted`, `revoked` or `expired`; a replaced code or a lost race reads `unknown`.
587
+
588
+ **Fix:** ask the owner to `resendInvitation`. An accept that failed before `onAccepted` returned released the claim and can be retried with the same code.
589
+
590
+ ### `invitations.issue: type must be one of "staff", "guardian"`
591
+
592
+ **When:** `issueInvitation` is refused with `INVITATION_INVALID` and `field: 'type'`.
593
+
594
+ **Why:** the instance lists several invitation user types and `type` was absent, or it names a type that is not listed.
595
+
596
+ **Fix:** pass one of the listed types, as in the message:
597
+
598
+ ```graphql
599
+ mutation {
600
+ issueInvitation(scope: "acme", email: "a@example.test", name: "Ada", role: "member", type: "staff") {
601
+ invitation { id type }
602
+ }
603
+ }
604
+ ```
605
+
606
+ ### A response that answers the invitation code is cached
607
+
608
+ **When:** `issueInvitation` or `resendInvitation` with `answerCode: true`, or `invitationPreview` and `acceptInvitation`, answer without `Cache-Control: no-store`.
609
+
610
+ **Why:** the header is sent through `useJanus()`'s `onResponse`, which only Yoga's HTTP response runs (not graphql-ws, nor an envelop server without `useJanus()`); `invitationPreview` called with a context that carries no request answers without it.
611
+
612
+ **Fix:** serve these operations over HTTP through Yoga with `useJanus({ auth })`, or set `Cache-Control: no-store` yourself on every response that carries a code, a token or a challenge.
613
+
614
+ ### `TypeError: apiKeysResolvers(): auth has no apiKeys — …`
615
+
616
+ **When:** `apiKeysResolvers()` is called, before the server starts.
617
+ **Why:** `auth.apiKeys` is absent: `janus()` was not given `apiKeys`, or `auth` is not what `janus()` answered.
618
+
619
+ **Fix:**
620
+
621
+ ```ts
622
+ const auth = janus({ …, apiKeys: { store: createMemoryApiKeys(), prefix: 'sl_', lifetimes: ['30d', '90d', '365d'], maxActive: 3 } });
623
+ apiKeysResolvers({ auth, lifetimes: { days: [30, 90, 365], default: 90 }, authorize });
624
+ ```
625
+
626
+ ### `` TypeError: apiKeysResolvers(): `authorize` needs `create`, `list` and `revoke` … ``
627
+
628
+ **When:** `apiKeysResolvers()` is called, before the server starts.
629
+ **Why:** the core authorises nobody, so `authorize` is required, with its three hooks; one is missing, or `authorize` is absent.
630
+
631
+ **Fix:**
632
+
633
+ ```ts
634
+ apiKeysResolvers({
635
+ auth,
636
+ lifetimes,
637
+ authorize: {
638
+ create: ({ bound }, ctx: Context) => bound !== null && can(ctx, 'member', bound),
639
+ list: ({ bound }, ctx: Context) => bound !== null && can(ctx, 'member', bound),
640
+ revoke: ({ own }) => own === true,
641
+ },
642
+ });
643
+ // Context: YogaInitialContext & JanusContext<typeof auth, typeof access>; the hooks are methods, so `ctx` takes it.
644
+ ```
645
+
646
+ `bound` is the other wiring check: `` TypeError: apiKeysResolvers(): `bound` must be a function of the asked id and the context `` when it is given and is not a function. See the [API keys guide](guide/api-keys.md#who-may-do-what-authorize).
647
+
648
+ ### `TypeError: apiKeysResolvers(): lifetimes …`
649
+
650
+ **When:** `apiKeysResolvers()` is called, before the server starts. The messages: `lifetimes must list at least one lifetime in days — for example { days: [30, 90, 365], default: 90 }`, `lifetimes.days must be positive whole numbers of days`, `lifetimes.default must be one of lifetimes.days`.
651
+ **Why:** `lifetimes` is absent or `days` is empty, a day count is zero, negative or fractional, or the default is not one of the choices.
652
+
653
+ **Fix:** list the choices in whole days, each also configured in `janus({ apiKeys: { lifetimes } })` (`30` is `'30d'`), and pick the default among them:
654
+
655
+ ```ts
656
+ apiKeysResolvers({ auth, lifetimes: { days: [30, 90, 365], default: 90 }, authorize });
657
+ ```
658
+
659
+ ### `BAD_USER_INPUT`, 400, on `createApiKey(lifetimeDays:)`
660
+
661
+ **When:** `createApiKey(name: "CI", lifetimeDays: 7)` answers `lifetimeDays must be one of 30, 90, 365`, with `extensions.field: "lifetimeDays"`.
662
+ **Why:** `lifetimeDays` is checked against `lifetimes.days` before `authorize` or a store is asked; any other value is refused. The same code answers a `name` over 100 characters, more than 32 `scopes`, a scope over 100 characters, or a `boundTo` empty or over 200 (`extensions.field` names the argument).
663
+
664
+ **Fix:** offer the client `apiKeyLifetimes { days default }` and send one of `days`, or omit `lifetimeDays` for the default:
665
+
666
+ ```graphql
667
+ query { apiKeyLifetimes { days default } }
668
+ mutation { createApiKey(name: "CI", lifetimeDays: 90) { secret } }
669
+ ```
670
+
671
+ ### `NOT_FOUND` on an API key field with `boundTo`
672
+
673
+ **When:** `apiKeys`, `boundApiKeys`, `createApiKey` or `revokeApiKey` answers `NOT_FOUND`, 404, for a user who may do it.
674
+ **Why:** `NOT_FOUND` has four causes, deliberately alike so an object's existence is not revealed: an `authorize` hook answered `false`; a `boundTo` was sent and `apiKeysResolvers()` has no `bound` hook; `bound(boundTo, ctx)` answered `null` for it; or `revokeApiKey` named an id that is neither the user's own key nor one bound to the call's object. `boundApiKeys` with no object is `NOT_FOUND` too.
675
+
676
+ **Fix:** pass `bound` and make it answer `{ type, id }` for the ids you accept; log what `authorize` receives (`user`, `bound`, and `input`, `every` or `key`):
677
+
678
+ ```ts
679
+ bound: (asked) => (asked === null ? null : { type: 'workspace', id: asked }),
680
+ ```
681
+
682
+ ### `STEP_UP_REQUIRED` on `createApiKey` from a request signed by a key
683
+
684
+ **When:** `createApiKey` answers `STEP_UP_REQUIRED`, 403, to a request that carries `Authorization: Bearer <key>`, however fresh.
685
+ **Why:** a key never creates a key. The core refuses a principal that is an API key, whatever its age; only a session that proved who it is within `apiKeys.freshWithin` may create one. (A stale session is the same code, and is cured by a step-up.)
686
+
687
+ **Fix:** create keys from the browser session, not from a script that holds a key; for a stale session, confirm a step-up and send the request again (see [the step-up guide](guide/step-up.md)).
688
+
689
+ ### `CREDENTIALS_INVALID` with `retryAfter`, 401, for the right password
690
+
691
+ With `extensions.retryAfter` and a `Retry-After` header.
692
+
693
+ **Why:** `@softistx/janus` throttles password guessing per login, on by default:
694
+ past ten passwords at one login in a 15-minute window, `signIn` refuses every
695
+ one — the right password included — until the window ends. `retryAfter` is
696
+ the seconds until then. Nothing locks.
697
+
698
+ **Fix:** show the wait, not "wrong password": read `extensions.retryAfter`
699
+ in the client. To change the limit, `janus({ signIn: { throttle: { attempts,
700
+ window } } })`; in a test over a `fixedClock`, advance the clock past
701
+ `retryAfter`, or wire `signIn: { throttle: false }`.
702
+
703
+ ### `CODE_INVALID` with `retryAfter`, 401, `too many codes tried`
704
+
705
+ The messages are `secondFactor.regenerateRecoveryCodes: too many codes tried — wait for the next 15-minute window` and `stepUp.confirm: too many codes tried — wait for the next 15-minute window`; the error carries `extensions.attemptsLeft: 0`, `extensions.retryAfter` and a `Retry-After` header.
706
+
707
+ **Why:** `@softistx/janus` counts an authenticator code's tries per user — five per 15-minute window, shared by `regenerateRecoveryCodes` and a step-up confirmed with the app. Past the fifth every code is refused, the right one included, until the window frees; `retryAfter` is the seconds until then.
708
+
709
+ **Fix:** read `extensions.retryAfter` in the client and show the wait: **a new `requestStepUp` does not help**. A `CODE_INVALID` with `attemptsLeft: 0` and no `retryAfter` is a challenge whose own tries are spent, with the window free: start over at `requestStepUp`.
710
+
711
+ ### `FORBIDDEN` where the user should be allowed
712
+
713
+ **Why:** a `type:` that applies does not name the user's type. Every
714
+ `@authenticated` that applies must hold — a type's or an interface's too, not
715
+ only the field's. Or a `@permission(onDeny: FORBIDDEN)` denied: what
716
+ [`NOT_FOUND` where the user should be allowed](#not_found-where-the-user-should-be-allowed)
717
+ says applies to it too.
718
+
719
+ **Fix:** read the directives on the field, on its type, and on every
720
+ interface the type implements.
721
+
722
+ ### `STEP_UP_REQUIRED`, 403
723
+
724
+ **Why:** a field `@fresh(maxAge)` guards, or a `requireFresh(ctx, maxAge)`,
725
+ was reached by a session that proved who it is `maxAge` ago or more — at
726
+ its sign-in, or at its last `auth.stepUp.confirm`. Renewing a sliding
727
+ session does not count. This is the answer working: it tells the client to
728
+ ask for a step-up.
729
+
730
+ It is also the answer to a request authenticated by an **API key**
731
+ (`useJanus({ apiKey: true })`): a key is never fresh, and a step-up cannot
732
+ change that. **Fix:** send a signed-in session instead of the key.
733
+ A key is read from `Authorization: Bearer` only: one sent in the cookie or
734
+ `X-Session-Token` is anonymous, not a key.
735
+
736
+ **Fix:** in the client, on `extensions.code === 'STEP_UP_REQUIRED'`, run the
737
+ step-up — `requestStepUp`, then `confirmStepUp(challenge, code)` — and send
738
+ the request again. The mutations are in
739
+ [the step-up over GraphQL](guide/step-up.md).
740
+
741
+ ### `Property 'principal' does not exist on type …`
742
+
743
+ **Why:** `ctx.janus.principal()` and `apiKey()` are typed only when the
744
+ context type says so, though `useJanus({ apiKey: true })` adds them at run
745
+ time.
746
+
747
+ **Fix:** pass `true` as the fourth argument:
748
+ `JanusContext<typeof auth, typeof access, UserType, true>`.
749
+
750
+ ### `STEP_UP_REQUIRED` for a user who just signed in
751
+
752
+ **Why:** `@fresh` reads the time from `useJanus({ clock })`, and the session
753
+ was stamped with `janus()`'s. Two different clocks: `janus({ clock:
754
+ fixedClock(…) })` with `useJanus()` given none, in a spec — the session looks
755
+ days old. Or `maxAge` written as minutes: `@fresh(maxAge: 10)` is ten
756
+ seconds, not ten minutes.
757
+
758
+ **Fix:** give both the same clock — `useJanus({ auth, clock })` — and write
759
+ `maxAge` in seconds: `@fresh(maxAge: 600)` for ten minutes.
760
+
761
+ ### `SERVICE_UNAVAILABLE`, 503, on every guarded field
762
+
763
+ **Why:** a store could not answer — `STORE_FAILED`. The sessions store for
764
+ `@authenticated`, `@fresh`, `requireUser()`, `requireFresh()` and
765
+ `ctx.janus.user()`; the relation store
766
+ for `can()` and `@permission` — and a loader of yours that threw
767
+ `StoreFailure`. It is never answered `UNAUTHENTICATED`, `FORBIDDEN` or `STEP_UP_REQUIRED`.
768
+
769
+ **Fix:** the store: its connection, its credentials, its availability. The
770
+ message carries nothing of the store's, and a directive or a helper answers
771
+ the outage before any resolver of yours could catch it: pass `report` to
772
+ the mask, which is given `@softistx/janus`'s error — its `slot` and `operation`
773
+ name the call that failed, its `cause` the driver's error:
774
+
775
+ ```ts
776
+ maskedErrors: {
777
+ maskError: janusMaskError({ report: (error) => logger.error(error) }),
778
+ },
779
+ ```
780
+
781
+ ### `Unexpected error.`, 500, where a `JanusError` was thrown
782
+
783
+ **Why:** Yoga masks every error that is not a `GraphQLError`, and nothing
784
+ told it a `JanusError` is one a client should see.
785
+
786
+ **Fix:** `maskedErrors: { maskError: janusMaskError() }`. `CREDENTIALS_INVALID`
787
+ is then 401, `STORE_FAILED` 503, and so on.
788
+
789
+ ### `TypeError: … ctx.janus is not set`
790
+
791
+ **Why:** a guarded field, `requireUser()` or `can()` ran under a context
792
+ `useJanus()` did not build: the plugin is missing, or the schema was
793
+ transformed with `applyJanusDirectives()` and served by something else.
794
+
795
+ **Fix:** `plugins: [useJanus({ auth })]`.
796
+
797
+ ### `TypeError: …: the GraphQL context has no request to authenticate`
798
+
799
+ **Why:** the context was built without `request`, and for no connection
800
+ `janusConnection().onConnect` accepted: a transport that is not HTTP; a
801
+ graphql-ws server without `onConnect`; or Yoga's recipe with the context
802
+ built from something other than `{ ...ctx, … }`, which drops `ctx.extra`,
803
+ where `useJanus()` finds the connection. The message opens with
804
+ `useJanus():` under Yoga, and with `janusConnection().context:` without
805
+ it — the `context` of a server whose `onConnect` is not
806
+ `janusConnection()`'s.
807
+
808
+ **Fix:** over graphql-ws, pass `onConnect: janusConnection({ auth }).onConnect`
809
+ to `useServer()`, and keep the `...ctx` spread in `yoga.getEnveloped()`
810
+ ([the subscriptions guide](guide/subscriptions.md)). Without Yoga, pass
811
+ `context: connection.context` too.
812
+
813
+ ### `TypeError: can(): ctx.janus.access is not set`
814
+
815
+ **Why:** `useJanus()` was given no `access`.
816
+
817
+ **Fix:** `useJanus({ auth, access })`, with `access` what `permissions()`
818
+ answered.
819
+
820
+ ### `TypeError: requireUser(): type is an empty list, which no user could pass`
821
+
822
+ **Why:** `requireUser(ctx, { type })` was given `[]` — a list of user types
823
+ built at run time that came out empty. The compiler refuses a literal `[]`;
824
+ a `string[]` built elsewhere gets through, and no user could pass it.
825
+
826
+ **Fix:** name at least one user type, or leave `type` out to admit any
827
+ signed-in user:
828
+
829
+ ```ts
830
+ const user = await requireUser(ctx, allowed.length > 0 ? { type: allowed } : {});
831
+ ```
832
+
833
+ ### `TypeError: requireFresh(): maxAge is a duration with its unit`
834
+
835
+ **Why:** `requireFresh(ctx, 600)` — a bare number, from JavaScript or built
836
+ at run time. `@softistx/janus` would read it as 600 milliseconds, where
837
+ `@fresh(maxAge: 600)` reads ten minutes, so it is refused rather than
838
+ guessed. The compiler refuses a literal number.
839
+
840
+ **Fix:** write the unit: `requireFresh(ctx, '10m')`, or `'600s'`.
841
+
842
+ ### `TypeError: requireFresh(): maxAge: "…" is not a duration`
843
+
844
+ **Why:** the string is not a number followed by `ms`, `s`, `m`, `h` or `d`
845
+ — `'10 minutes'`, `'10 m'`.
846
+
847
+ **Fix:** `requireFresh(ctx, '10m')`.
848
+
849
+ ### `TypeError: requireFresh(): maxAge: a duration must be above zero`
850
+
851
+ **Why:** `requireFresh(ctx, '0m')` — no session is ever fresh within no
852
+ time, so every request would be refused. The compiler lets it through: the
853
+ type reads a number and a unit, not their value.
854
+
855
+ **Fix:** a duration above zero, `requireFresh(ctx, '10m')`.
856
+
857
+ ### `@permission on … resolved no object id from … — answered NOT_FOUND`
858
+
859
+ **Where:** a warning, through `process.emitWarning` with the code
860
+ `JANUS_GRAPHQL_NO_OBJECT_ID`, once per directive; the client receives
861
+ `NOT_FOUND`, 404.
862
+
863
+ **Why:** the path read nothing it could check: an optional argument the
864
+ client left out (`record(id: ID)`), a `null` in the parent
865
+ (`parent.wardId` on a visit with no ward), an empty list in the parent, a
866
+ list holding a `null`, or a value that is neither a string nor an integer.
867
+ There is no object to ask about, so there is nothing to allow.
868
+
869
+ **Fix:** make the argument required — `record(id: ID!)` — or point `id:` at a
870
+ field that always holds an id. When a `null` is a valid answer, move the
871
+ directive to a field that is only reached when there is an object.
872
+
873
+ ### `NOT_FOUND` where the user should be allowed
874
+
875
+ **Why:** one of the directives that apply denied — `NOT_FOUND` is
876
+ `@permission`'s default denial — or there was nothing to check:
877
+
878
+ - a `@permission` on the **type** or an **interface** it implements applies
879
+ too, and is asked first;
880
+ - the `id:` path reads another object than you think — `args.id` is the
881
+ default on a field, even a field of the object;
882
+ - a loader answered `null`;
883
+ - a `fromField` field is missing from the parent, so the relation it reads
884
+ holds for nobody: the parent's resolver must answer the field;
885
+ - the user holds the relation on another object type than `type:` names.
886
+
887
+ **Fix:** ask `access.can` yourself with the same subject, permission and
888
+ object to see what the model answers, and read every directive on the field,
889
+ its type and its interfaces.
890
+
891
+ ### A 403 that tells a user the object exists
892
+
893
+ **Why:** `onDeny: FORBIDDEN` answers *this exists, and not for you*. On
894
+ `record(id: "r42")`, that tells a user who may not know `r42` that it exists.
895
+
896
+ **Fix:** keep `NOT_FOUND`, the default, on anything reached by an id the
897
+ client chose. `FORBIDDEN` fits a field of an object the user may already
898
+ see — guard the type with a `NOT_FOUND` `@permission` and the field with the
899
+ `FORBIDDEN` one; the type's is asked first:
900
+
901
+ ```graphql
902
+ type Record @permission(name: "view", type: "record") {
903
+ billing: Billing @permission(name: "manage", type: "record", onDeny: FORBIDDEN)
904
+ }
905
+ ```
906
+
907
+ ### `Unexpected error.`, 500, on a field `@permission` guards
908
+
909
+ **Why:** `@permission` answers a `JanusError` — a relation store's
910
+ `STORE_FAILED`, or one a loader threw — with its status, 503 for an outage.
911
+ An error that is not a `JanusError` is masked by Yoga like any other: a
912
+ database driver's own error thrown by a loader or a condition, or anything
913
+ the resolver throws after the check. And without `janusMaskError()`, a
914
+ `JanusError` the **resolver** lets through is masked too.
915
+
916
+ **Fix:** throw `StoreFailure` from a loader whose database cannot answer, so
917
+ the outage is a 503 rather than a 500, and wire
918
+ `maskedErrors: { maskError: janusMaskError() }`:
919
+
920
+ ```ts
921
+ import { StoreFailure } from '@softistx/janus';
922
+
923
+ loaders: {
924
+ record: (id) =>
925
+ records.find(id).catch((cause: unknown) => {
926
+ throw new StoreFailure('records.find could not answer', { cause });
927
+ }),
928
+ },
929
+ ```
930
+
931
+ ### `TypeError: @permission on …: ctx.janus.access is not set`
932
+
933
+ **Why:** the schema was transformed with `access` — by
934
+ `applyJanusDirectives(schema, { auth, access })` — and is served with a
935
+ context built without it.
936
+
937
+ **Fix:** serve it through `useJanus({ auth, access })`, which builds both
938
+ from the same options.
939
+
940
+ ### `TypeError: @permission on …: loaders.… answered …`
941
+
942
+ **Why:** a loader answered `undefined`, or something that is not an object.
943
+ **An absence is `null`**: a loader that forgets to `return` answers
944
+ `undefined`, and that is refused rather than read as "not found".
945
+
946
+ **Fix:** answer the object, or `null` when there is none.
947
+
948
+ ### The session cookie expires while the user is active
949
+
950
+ **Why:** `authenticate` renewed the session in the store, and no
951
+ `Set-Cookie` carried the new expiry back, so the browser drops the cookie at
952
+ the expiry it was given at sign-in. `useJanus()` sends it only on Yoga's
953
+ HTTP response (`onResponse`), and not when:
954
+
955
+ - the server runs on envelop without Yoga, which never calls `onResponse`;
956
+ - the `auth` given to `useJanus()` is a wrapper of yours without `cookie`;
957
+ - the only traffic is over graphql-ws, which has no response to carry it;
958
+ - the client sent `Authorization: Bearer` or `X-Session-Token`, which is
959
+ never answered with a cookie.
960
+
961
+ **Fix:** under Yoga, pass `janus()`'s own instance, or a wrapper with
962
+ `cookie: auth.cookie`. Elsewhere — and for a browser that talks only over
963
+ the WebSocket — renew through an HTTP route of yours that sends
964
+ `auth.cookie.serialize(token, session)`, as `@softistx/janus-hono`'s
965
+ `session()` does.
966
+
967
+ ### A completed social sign-in sets no session cookie
968
+
969
+ **Why:** `socialSignInComplete` hands the cookie to `useJanus()`'s
970
+ `onResponse`, which only Yoga's HTTP response runs. It is missing when
971
+ `useJanus()` is not among the plugins, when the server is envelop alone, or
972
+ when the BFF did not forward the response's `Set-Cookie` to the browser. A
973
+ `SocialLinked` answer sets none: it is not a sign-in. `socialResolvers({ answerToken: true })` sets none on purpose and answers the session
974
+ token in `SocialSignedIn.token` instead.
975
+
976
+ **Fix:** add `useJanus({ auth })` under Yoga and forward `Set-Cookie`, or read `token` when `answerToken` is on. The response that answers `token` must also say `Cache-Control: no-store`: [see below](#a-response-that-answers-the-session-token-is-cached).
977
+
978
+ ### A response that answers the session token is cached
979
+
980
+ **When:** a sign-in with `answerToken: true` (`confirmSecondFactor`, `recoverSecondFactor`, `confirmSecondFactorPasskey`, `socialSignInComplete`) answers `token`, but the response has no `Cache-Control: no-store`.
981
+
982
+ **Why:** the header is sent through `useJanus()`'s `onResponse`, which only Yoga's HTTP response runs. It is missing over graphql-ws, and on an envelop server without `useJanus()`.
983
+
984
+ **Fix:** serve these operations over HTTP through Yoga with `useJanus({ auth })`, or set `Cache-Control: no-store` yourself on every response that carries `token`.
985
+
986
+ ### A response that answers a challenge or a flow is cached
987
+
988
+ **When:** `socialSignInStart`, `linkSocial`, `passkeyRegistrationOptions`, `requestStepUp`, a `SocialSecondFactor` answer or your sign-in's `JanusSecondFactorChallenge` answers a `flow` or a `challenge`, but the response has no `Cache-Control: no-store`.
989
+
990
+ **Why:** the header is sent through `useJanus()`'s `onResponse`, which only Yoga's HTTP response runs (not graphql-ws, nor an envelop server without `useJanus()`); a context with no request answers without it. For `JanusSecondFactorChallenge` your own sign-in resolver builds the answer: it sends the header only when it calls `secondFactorChallengeOut(result, ctx.request)` with the request.
991
+
992
+ **Fix:** serve these operations over HTTP through Yoga with `useJanus({ auth })`, pass `ctx.request` to `secondFactorChallengeOut`, or set `Cache-Control: no-store` yourself on every response that carries a `flow` or a `challenge`.
993
+
994
+ ### `FLOW_MISMATCH` on the callback, though the visitor did nothing wrong
995
+
996
+ **Why:** the BFF did not hand back the `flow` that `socialSignInStart` answered
997
+ (its cookie is missing, `SameSite=Strict`, on another host, or lapsed), the
998
+ `state` in `callbackUrl` is another flow's, or a link flow is completed with no
999
+ session cookie. `extensions.flowSpent` is `false` when nothing was spent: keep
1000
+ the cookie, the genuine callback may still come.
1001
+
1002
+ **Fix:** keep `flow` in an `HttpOnly`, `SameSite=Lax` cookie of the BFF, send
1003
+ it with the callback, and forward the visitor's session cookie on a link.
1004
+
1005
+ ### `PROVIDER_ERROR`, 502, `Bad gateway`
1006
+
1007
+ **Why:** the provider was unreachable or refused the code exchange. The
1008
+ response says nothing more on purpose; the provider's error is the
1009
+ `JanusError`'s `cause`, for `janusMaskError({ report })`.
1010
+
1011
+ **Fix:** read the cause in your logs. The flow is spent (`flowSpent: true`):
1012
+ clear the cookie and start again.
1013
+
1014
+ ### `TypeError: socialResolvers(): the GraphQL context has no request`
1015
+
1016
+ **Why:** a social field ran on a context built without an HTTP request (a
1017
+ graphql-ws operation, or a hand-built context).
1018
+
1019
+ **Fix:** serve social fields over HTTP through Yoga, which puts `request` on the context.
1020
+
1021
+ ### `BAD_USER_INPUT`, 400, on `invitations(after:)`
1022
+
1023
+ **When:** the `after` cursor came from a page of another scope, status, role, ref, lapsed or order.
1024
+ **Why:** the cursor is bound to the list that issued it; it is refused rather than paging through the other list. The error carries `extensions.field: "after"`, as does `INVALID_CURSOR`; a bad `status`, `role`, `ref` or `limit` carries its own argument's name, so a form can flag the right input.
1025
+ **Fix:** pass `nextCursor` back with the same arguments, and drop `after` when an argument changes. A cursor from before the upgrade that bound cursors to their list is refused as `INVALID_CURSOR`; restart from the first page.
1026
+
1027
+ ### `BAD_USER_INPUT`, 400, with a `field`, on an invitation argument
1028
+
1029
+ **When:** `acceptInvitation`, `invitationPreview` or `issueInvitation` is sent a string over its maximum: `password` 1024 characters, `code` 43, `scope` 512, `email` 254, `name`, `role` and `ref` 100, `locale` 35. `extensions.field` names the argument; the message never echoes the value.
1030
+ **Why:** the arguments are bounded before `authorize`, a hash or a store is asked, so a holder of a code cannot make the server hash a megabyte. `name` and `email` are measured once trimmed, as the core does. The refusal spends nothing: an invitation code stays pending.
1031
+ **Fix:** cap the form's inputs at those lengths. A `password` over 1024 characters is not a password the form should accept; a `code` is the 43 characters the link carries, so a longer one was mangled on the way.
1032
+
1033
+ ### `UNAUTHENTICATED`, 401, on every social field
1034
+
1035
+ **Why:** `socialResolvers({ auth })` was given a function (one instance per request) and it answered `null` or `undefined` for this request, or an instance whose `janus()` has no `social`. No field is run.
1036
+
1037
+ **Fix:** make the function answer the issuer's instance for every request that reaches the social fields, and give that instance `janus({ social })`. [One auth instance per request](guide/social.md#one-auth-instance-per-request).
1038
+
1039
+ ### `BAD_USER_INPUT`, 400, on `socialSignInComplete`
1040
+
1041
+ **Why:** `callbackUrl` is not a URL. Pass the full callback URL the provider redirected to.
1042
+
1043
+ **Fix:** forward the request URL as received; only its query is read.
1044
+
1045
+ ### `TypeError: secondFactorResolvers(): auth has no secondFactor surface — …`, `… auth.<type> has no secondFactor — …`
1046
+
1047
+ **When:** `secondFactorResolvers()` or `secondFactorViewerFields()` is called at start-up; with `auth` a function of the context, on the request that chose the instance.
1048
+
1049
+ **Why:** `auth` carries no `secondFactor`: it is not what `janus()` answered, or, with several user types, the named `type` is not one of them (the surface is `auth.<type>.secondFactor`). A `janus()` without `secondFactor` is refused by the compiler first.
1050
+
1051
+ **Fix:** pass what `janus({ secondFactor })` answered, and with several user types name the one that holds the factor: `secondFactorResolvers({ auth, type: 'staff' })`. With `auth` a function of the context, the error comes on the request that chose that instance: make the function answer only instances built with `janus({ secondFactor })`.
1052
+
1053
+ ### `UNAUTHENTICATED`, 401, on every second-factor field
1054
+
1055
+ **Why:** `secondFactorResolvers({ auth })` was given a function (one instance per request) and it answered `null` or `undefined` for this request. No field is run.
1056
+
1057
+ **Fix:** make the function answer the tenant's instance for every request that reaches the second-factor fields. [One auth instance per request](guide/second-factor.md#one-auth-instance-per-request).
1058
+
1059
+ ### `TypeError: secondFactorResolvers(): freshWithin is a duration with its unit`
1060
+
1061
+ **When:** at start-up, `freshWithin` is not a string.
1062
+
1063
+ **Why:** a bare number would be milliseconds here and seconds in `@fresh`; the option takes a duration with its unit.
1064
+
1065
+ **Fix:** `freshWithin: '10m'`.
1066
+
1067
+ ### `TypeError: secondFactorResolvers(): the GraphQL context has no request`
1068
+
1069
+ **When:** a second-factor resolver ran over graphql-ws, or a context was built without an HTTP request.
1070
+
1071
+ **Why:** the session cookie, the device cookie and `Cache-Control` travel on the HTTP request and response; a graphql-ws operation has neither.
1072
+
1073
+ **Fix:** serve these operations over HTTP through Yoga, as for [passkeys](#typeerror-passkeyresolvers-the-graphql-context-has-no-request).
1074
+
1075
+ ### `TypeError: secondFactorResolvers(): a step-up by e-mail needs sendStepUpCode`
1076
+
1077
+ **When:** `requestStepUp` for a user with no active second factor.
1078
+
1079
+ **Why:** that user confirms with a code sent to their address, and this package has no mailer. Nothing was issued: the check comes before the core is called.
1080
+
1081
+ **Fix:** give `sendStepUpCode: (issued) => mail.stepUp(issued, …)`, or require a second factor of every user.
1082
+
1083
+ ### `TypeError: secondFactorResolvers(): <caller> needs a step-up`
1084
+
1085
+ **When:** `requestStepUp`, `confirmStepUp` or `disableSecondFactor` for a user type that has no e-mail.
1086
+
1087
+ **Why:** `stepUp` exists on a user type with an e-mail only, and `disableSecondFactor` checks its code through a step-up.
1088
+
1089
+ **Fix:** none in this package: give the type an e-mail, or do not offer those three fields for it (`type` limits the resolvers to one user type).
1090
+
1091
+ ### `UNAUTHENTICATED` on a second-factor write with an API key
1092
+
1093
+ **When:** a request authenticated by an API key (`useJanus({ apiKey: true })`) calls `enrollSecondFactor`, `activateSecondFactor`, `regenerateRecoveryCodes`, `disableSecondFactor`, `requestStepUp` or `confirmStepUp`.
1094
+
1095
+ **Why:** a key is no session. It must not enroll, change or disable its owner's factor, or cancel their live step-ups, so these fields need a session.
1096
+
1097
+ **Fix:** call them with the session cookie or token.
1098
+
1099
+ ### `TypeError: passkeyResolvers(): auth has no passkeys — …`
1100
+
1101
+ **Why:** `janus()` was given no `passkeys` (or no `secondFactor`), or, with several
1102
+ user types, `type` is missing or names a type that does not exist: the
1103
+ surface is `auth.<type>.passkeys`.
1104
+
1105
+ **Fix:** configure `janus({ secondFactor, passkeys })` and pass `passkeyResolvers({ auth, type })` with the user type's name. With `auth` a function of the context, the error comes on the request that chose that instance.
1106
+
1107
+ ### `TypeError: passkeyResolvers(): the GraphQL context has no request`
1108
+
1109
+ **Why:** `confirmSecondFactorPasskey` ran on a context built without an HTTP
1110
+ request (a graphql-ws operation, or a hand-built context): the session and
1111
+ device cookies are HTTP.
1112
+
1113
+ **Fix:** serve it over HTTP through Yoga, which puts `request` on the context.
1114
+
1115
+ ### `CREDENTIALS_INVALID` or `TOKEN_*` on `passkeySignIn`
1116
+
1117
+ **Why:** `passkeySignIn` allows one attempt per challenge. `CREDENTIALS_INVALID`, 401, is an assertion the core refused (an unknown credential, a response that did not verify or did not verify the user, a counter that went backwards); `TOKEN_UNKNOWN`, `TOKEN_SPENT` or `TOKEN_EXPIRED` is a challenge that is unknown, already used or lapsed. With a per-request `auth` function, the challenge also belongs to the instance that made it: another tenant's is `TOKEN_UNKNOWN`.
1118
+
1119
+ **Fix:** ask for new `passkeySignInOptions` after any refusal, from the same tenant, and run the ceremony again.
1120
+
1121
+ ### `TypeError: … passkeys.firstFactor` on `passkeySignInOptions`
1122
+
1123
+ **Why:** `passkeyResolvers({ firstFactor: true })` is wired over an instance whose `janus({ passkeys })` has no `firstFactor: true`. TypeScript refuses it at compile time; a cast or a per-request `auth` function answering such an instance reaches the core, which refuses.
1124
+
1125
+ **Fix:** give that instance `passkeys: { firstFactor: true }`, or leave `firstFactor` off.
1126
+
1127
+ ### `BAD_USER_INPUT`, 400, on a passkey field
1128
+
1129
+ **Why:** `response` (`registerPasskey`) or `assertion`
1130
+ (`confirmSecondFactorPasskey`) is not JSON. Nothing was spent.
1131
+
1132
+ **Fix:** send the credential as `JSON.stringify(credential.toJSON())`, the string as received from the browser's API, never a hand-built object.
1133
+
1134
+ ### `PASSKEY_INVALID`, `PASSKEY_TAKEN` or `STEP_UP_REQUIRED` on `registerPasskey`
1135
+
1136
+ **Why:** `PASSKEY_INVALID` is a response that did not verify (the challenge is
1137
+ now spent) or a name outside 1 to 100 characters (`extensions.field` is
1138
+ `name`, nothing spent); `PASSKEY_TAKEN` is a credential already registered;
1139
+ `STEP_UP_REQUIRED` is a session that proved who it is longer ago than
1140
+ `passkeys.freshWithin`.
1141
+
1142
+ **Fix:** ask for new `passkeyRegistrationOptions` after a failed verification; run the step-up and retry on `STEP_UP_REQUIRED`; let the user keep the passkey they have on `PASSKEY_TAKEN`.
1143
+
1144
+ ### A passkey sign-in sets no session cookie
1145
+
1146
+ **Why:** as for [social sign-in](#a-completed-social-sign-in-sets-no-session-cookie): `useJanus()` is not among the plugins, the BFF did not forward `Set-Cookie`, or `passkeyResolvers({ answerToken: true })` sets none on purpose and answers `token`, which must not be cached: [see the entry](#a-response-that-answers-the-session-token-is-cached).
1147
+
1148
+ **Fix:** add `useJanus({ auth })` under Yoga and forward `Set-Cookie`, or read `token`.
1149
+
1150
+ ### `Warning: janusMaskError: report failed on …`
1151
+
1152
+ **Why:** the `report` given to `janusMaskError()` threw, or rejected — a
1153
+ logger that is down, a serializer that meets a circular `cause`. The name
1154
+ after the code is the class of what it threw.
1155
+
1156
+ **Fix:** your `report`. The response was sent all the same: a `report`
1157
+ never changes the answer, so an outage is still a 503 and never a 500.
1158
+
1159
+ ### A 401 whose `data` still holds the other fields
1160
+
1161
+ **Why:** Yoga answers the highest status among the errors. One refused field
1162
+ in a query makes the response a 401, while the fields that were allowed are
1163
+ answered in `data`.
1164
+
1165
+ **Fix:** nothing to fix: read `data` and `errors` rather than the status
1166
+ alone, or split the query.
1167
+
1168
+ ## Types
1169
+
1170
+ ### `'user' is possibly 'null'`
1171
+
1172
+ **When:** `const user = await ctx.janus.user(); user.id;` — or, read without
1173
+ binding it, `(await ctx.janus.user()).id`, where the message is
1174
+ `Object is possibly 'null'`.
1175
+
1176
+ **Why:** `ctx.janus.user()` answers `null` for an anonymous request, and the
1177
+ type does not know a directive guards the field.
1178
+
1179
+ **Fix:** `requireUser(ctx)`, which answers a user or refuses the request.
1180
+
1181
+ ```ts
1182
+ const user = await requireUser(ctx);
1183
+ user.id;
1184
+ ```
1185
+
1186
+ ### `Property 'access' does not exist on type …`
1187
+
1188
+ **Why:** the context was typed `JanusContext<typeof auth>`, without `access`
1189
+ — as it is when `useJanus()` is given none.
1190
+
1191
+ **Fix:** `JanusContext<typeof auth, typeof access>`, and `useJanus({ auth, access })`.
1192
+
1193
+ ### `Expected 4 arguments, but got 3`, on `can()`
1194
+
1195
+ **Why:** the permission reaches a condition, a `when()` in the model, and its
1196
+ `ctx` is required — as it is for `access.can`.
1197
+
1198
+ **Fix:** pass it: `can(ctx, 'edit', record, { ctx: { locked: record.locked } })`.
1199
+
1200
+ ### `'…' does not exist in type 'Loaders<…>'`, or `'Conditions<…>'`
1201
+
1202
+ **Why:** a `loaders` key is not an object type of the model; or a
1203
+ `conditions` key is a type none of whose permissions reaches a `when()`, so
1204
+ there is no `ctx` to answer.
1205
+
1206
+ **Fix:** name an object type of the model; drop the `conditions` entry of a
1207
+ type with no condition.
1208
+
1209
+ ### `Type '{ …: … }' is not assignable to type 'never'`, on `loaders`
1210
+
1211
+ **Why:** `useJanus()` was given `loaders` or `conditions` and no `access`:
1212
+ without the permissions instance, `@permission` cannot be used, and has
1213
+ nothing to load for.
1214
+
1215
+ **Fix:** `useJanus({ auth, access, loaders })`.
1216
+
1217
+ ### `Source has 0 element(s) but target requires 1`, on `requireUser()`
1218
+
1219
+ The full message reads `Type '[]' is not assignable to type '"patient" |
1220
+ "staff" | readonly ["patient" | "staff", ...("patient" | "staff")[]] |
1221
+ undefined'`.
1222
+
1223
+ **Why:** `requireUser(ctx, { type: [] })` — an empty list admits no user.
1224
+ The compiler refuses it here; a list built at run time that comes out empty
1225
+ throws
1226
+ [`TypeError: requireUser(): type is an empty list, which no user could pass`](#typeerror-requireuser-type-is-an-empty-list-which-no-user-could-pass).
1227
+
1228
+ **Fix:** name at least one user type, `{ type: ['staff'] }`, or leave `type`
1229
+ out to admit any signed-in user.
1230
+
1231
+ ### `Argument of type '600' is not assignable to parameter of type '`${number}ms` | …'`, on `requireFresh()`
1232
+
1233
+ The full message ends `` '`${number}ms` | `${number}s` | `${number}m` |
1234
+ `${number}h` | `${number}d`' ``; the same for `'10 minutes'`.
1235
+
1236
+ **Why:** `requireFresh(ctx, maxAge)` takes a duration with its unit. A bare
1237
+ number would be milliseconds to `@softistx/janus` and seconds to `@fresh`, so
1238
+ neither is guessed.
1239
+
1240
+ **Fix:** `requireFresh(ctx, '10m')`.
1241
+
1242
+ ### `Expected 2 arguments, but got 1`, on `requireFresh()`
1243
+
1244
+ **Why:** `requireFresh(ctx)` — how recent the proof must be has no default.
1245
+
1246
+ **Fix:** `requireFresh(ctx, '10m')`.
1247
+
1248
+ ### `Type 'number' is not assignable to type 'Clock'`
1249
+
1250
+ **Why:** `useJanus({ auth, clock: Date.now() })` — a timestamp, where a
1251
+ clock answers `now()`.
1252
+
1253
+ **Fix:** pass the clock given to `janus()`, `fixedClock(…)` in a spec, or
1254
+ leave `clock` out.
1255
+
1256
+ ## Optional peers are installed as required
1257
+
1258
+ **When:** after `bun add @softistx/janus-graphql` of version 0.30.0 or older, or from a lock that resolved one, `node_modules` holds `graphql-ws`, or a second copy of a library sits beside yours.
1259
+ **Why:** the package document of versions up to 0.30.0 lacks `peerDependenciesMeta`, so Bun, which installs peers, treats every optional peer as required. The published `package.json` is right; only the package document lacks the field. The first version published on npmjs, and every later one, keeps it. Where you do not use subscriptions, `graphql-ws` still arrives, and a range that differs from yours can add a duplicate copy.
1260
+ **Fix:** install with `--omit=peer`, which skips every peer, **the required ones too** (verified with Bun 1.4.4), then add the required peers back as direct dependencies, plus `graphql-ws` only for subscriptions.
1261
+
1262
+ ```bash
1263
+ bun add @softistx/janus @envelop/core @graphql-tools/utils graphql typescript
1264
+ bun install --omit=peer
1265
+ ```