@softistx/janus-graphql 0.0.0-stage → 0.30.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +716 -2
- package/dist/api-keys/index.d.ts +11 -0
- package/dist/api-keys/index.d.ts.map +1 -0
- package/dist/api-keys/resolvers/deps.d.ts +39 -0
- package/dist/api-keys/resolvers/deps.d.ts.map +1 -0
- package/dist/api-keys/resolvers/index.d.ts +39 -0
- package/dist/api-keys/resolvers/index.d.ts.map +1 -0
- package/dist/api-keys/resolvers/list.d.ts +16 -0
- package/dist/api-keys/resolvers/list.d.ts.map +1 -0
- package/dist/api-keys/resolvers/manage.d.ts +17 -0
- package/dist/api-keys/resolvers/manage.d.ts.map +1 -0
- package/dist/api-keys/sdl.d.ts +14 -0
- package/dist/api-keys/sdl.d.ts.map +1 -0
- package/dist/api-keys/shape.d.ts +38 -0
- package/dist/api-keys/shape.d.ts.map +1 -0
- package/dist/api-keys/types.d.ts +149 -0
- package/dist/api-keys/types.d.ts.map +1 -0
- package/dist/avatar/index.d.ts +32 -0
- package/dist/avatar/index.d.ts.map +1 -0
- package/dist/avatar/resolvers.d.ts +41 -0
- package/dist/avatar/resolvers.d.ts.map +1 -0
- package/dist/avatar/sdl.d.ts +16 -0
- package/dist/avatar/sdl.d.ts.map +1 -0
- package/dist/bad-input.d.ts +17 -0
- package/dist/bad-input.d.ts.map +1 -0
- package/dist/connection/connection.d.ts +36 -0
- package/dist/connection/connection.d.ts.map +1 -0
- package/dist/connection/credential.d.ts +34 -0
- package/dist/connection/credential.d.ts.map +1 -0
- package/dist/connection/types.d.ts +61 -0
- package/dist/connection/types.d.ts.map +1 -0
- package/dist/context/create.d.ts +32 -0
- package/dist/context/create.d.ts.map +1 -0
- package/dist/context/index.d.ts +9 -0
- package/dist/context/index.d.ts.map +1 -0
- package/dist/context/registry.d.ts +72 -0
- package/dist/context/registry.d.ts.map +1 -0
- package/dist/context/resolve.d.ts +20 -0
- package/dist/context/resolve.d.ts.map +1 -0
- package/dist/device.d.ts +28 -0
- package/dist/device.d.ts.map +1 -0
- package/dist/directives/apply.d.ts +51 -0
- package/dist/directives/apply.d.ts.map +1 -0
- package/dist/directives/guard.d.ts +22 -0
- package/dist/directives/guard.d.ts.map +1 -0
- package/dist/directives/permission/enforce.d.ts +24 -0
- package/dist/directives/permission/enforce.d.ts.map +1 -0
- package/dist/directives/permission/model.d.ts +35 -0
- package/dist/directives/permission/model.d.ts.map +1 -0
- package/dist/directives/permission/path.d.ts +31 -0
- package/dist/directives/permission/path.d.ts.map +1 -0
- package/dist/directives/permission/validate.d.ts +42 -0
- package/dist/directives/permission/validate.d.ts.map +1 -0
- package/dist/directives/read.d.ts +43 -0
- package/dist/directives/read.d.ts.map +1 -0
- package/dist/directives/validate.d.ts +39 -0
- package/dist/directives/validate.d.ts.map +1 -0
- package/dist/directives/words.d.ts +7 -0
- package/dist/directives/words.d.ts.map +1 -0
- package/dist/errors/denial.d.ts +6 -0
- package/dist/errors/denial.d.ts.map +1 -0
- package/dist/errors/index.d.ts +12 -0
- package/dist/errors/index.d.ts.map +1 -0
- package/dist/errors/janus-error.d.ts +20 -0
- package/dist/errors/janus-error.d.ts.map +1 -0
- package/dist/errors/mask.d.ts +69 -0
- package/dist/errors/mask.d.ts.map +1 -0
- package/dist/fresh.d.ts +44 -0
- package/dist/fresh.d.ts.map +1 -0
- package/dist/helpers.d.ts +56 -0
- package/dist/helpers.d.ts.map +1 -0
- package/dist/index.d.ts +86 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3393 -0
- package/dist/index.js.map +75 -0
- package/dist/invitations/index.d.ts +12 -0
- package/dist/invitations/index.d.ts.map +1 -0
- package/dist/invitations/resolvers/anonymous.d.ts +11 -0
- package/dist/invitations/resolvers/anonymous.d.ts.map +1 -0
- package/dist/invitations/resolvers/deps.d.ts +38 -0
- package/dist/invitations/resolvers/deps.d.ts.map +1 -0
- package/dist/invitations/resolvers/index.d.ts +37 -0
- package/dist/invitations/resolvers/index.d.ts.map +1 -0
- package/dist/invitations/resolvers/owner.d.ts +17 -0
- package/dist/invitations/resolvers/owner.d.ts.map +1 -0
- package/dist/invitations/sdl/accept.d.ts +7 -0
- package/dist/invitations/sdl/accept.d.ts.map +1 -0
- package/dist/invitations/sdl/index.d.ts +14 -0
- package/dist/invitations/sdl/index.d.ts.map +1 -0
- package/dist/invitations/sdl/owner.d.ts +8 -0
- package/dist/invitations/sdl/owner.d.ts.map +1 -0
- package/dist/invitations/shape.d.ts +63 -0
- package/dist/invitations/shape.d.ts.map +1 -0
- package/dist/invitations/types/index.d.ts +5 -0
- package/dist/invitations/types/index.d.ts.map +1 -0
- package/dist/invitations/types/options.d.ts +104 -0
- package/dist/invitations/types/options.d.ts.map +1 -0
- package/dist/invitations/types/out.d.ts +136 -0
- package/dist/invitations/types/out.d.ts.map +1 -0
- package/dist/invitations/types/surface.d.ts +18 -0
- package/dist/invitations/types/surface.d.ts.map +1 -0
- package/dist/map-code.d.ts +10 -0
- package/dist/map-code.d.ts.map +1 -0
- package/dist/mask-error.d.ts +18 -0
- package/dist/mask-error.d.ts.map +1 -0
- package/dist/memo.d.ts +16 -0
- package/dist/memo.d.ts.map +1 -0
- package/dist/options.d.ts +17 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/passkeys/deps.d.ts +23 -0
- package/dist/passkeys/deps.d.ts.map +1 -0
- package/dist/passkeys/first-factor.types.d.ts +38 -0
- package/dist/passkeys/first-factor.types.d.ts.map +1 -0
- package/dist/passkeys/index.d.ts +14 -0
- package/dist/passkeys/index.d.ts.map +1 -0
- package/dist/passkeys/resolvers.d.ts +23 -0
- package/dist/passkeys/resolvers.d.ts.map +1 -0
- package/dist/passkeys/sdl.d.ts +14 -0
- package/dist/passkeys/sdl.d.ts.map +1 -0
- package/dist/passkeys/shape.d.ts +14 -0
- package/dist/passkeys/shape.d.ts.map +1 -0
- package/dist/passkeys/sign-in.resolvers.d.ts +19 -0
- package/dist/passkeys/sign-in.resolvers.d.ts.map +1 -0
- package/dist/passkeys/sign-in.sdl.d.ts +16 -0
- package/dist/passkeys/sign-in.sdl.d.ts.map +1 -0
- package/dist/passkeys/types.d.ts +193 -0
- package/dist/passkeys/types.d.ts.map +1 -0
- package/dist/plugin.d.ts +59 -0
- package/dist/plugin.d.ts.map +1 -0
- package/dist/renewal.d.ts +51 -0
- package/dist/renewal.d.ts.map +1 -0
- package/dist/report.d.ts +29 -0
- package/dist/report.d.ts.map +1 -0
- package/dist/sdl.d.ts +12 -0
- package/dist/sdl.d.ts.map +1 -0
- package/dist/second-factor/index.d.ts +12 -0
- package/dist/second-factor/index.d.ts.map +1 -0
- package/dist/second-factor/resolvers/deps.d.ts +39 -0
- package/dist/second-factor/resolvers/deps.d.ts.map +1 -0
- package/dist/second-factor/resolvers/index.d.ts +39 -0
- package/dist/second-factor/resolvers/index.d.ts.map +1 -0
- package/dist/second-factor/resolvers/sign-in.d.ts +10 -0
- package/dist/second-factor/resolvers/sign-in.d.ts.map +1 -0
- package/dist/second-factor/resolvers/status.d.ts +10 -0
- package/dist/second-factor/resolvers/status.d.ts.map +1 -0
- package/dist/second-factor/resolvers/step-up.d.ts +16 -0
- package/dist/second-factor/resolvers/step-up.d.ts.map +1 -0
- package/dist/second-factor/resolvers/writes.d.ts +19 -0
- package/dist/second-factor/resolvers/writes.d.ts.map +1 -0
- package/dist/second-factor/sdl.d.ts +14 -0
- package/dist/second-factor/sdl.d.ts.map +1 -0
- package/dist/second-factor/shape.d.ts +18 -0
- package/dist/second-factor/shape.d.ts.map +1 -0
- package/dist/second-factor/types/index.d.ts +5 -0
- package/dist/second-factor/types/index.d.ts.map +1 -0
- package/dist/second-factor/types/options.d.ts +61 -0
- package/dist/second-factor/types/options.d.ts.map +1 -0
- package/dist/second-factor/types/out.d.ts +84 -0
- package/dist/second-factor/types/out.d.ts.map +1 -0
- package/dist/second-factor/types/surface.d.ts +89 -0
- package/dist/second-factor/types/surface.d.ts.map +1 -0
- package/dist/social/index.d.ts +10 -0
- package/dist/social/index.d.ts.map +1 -0
- package/dist/social/resolvers.d.ts +25 -0
- package/dist/social/resolvers.d.ts.map +1 -0
- package/dist/social/sdl.d.ts +13 -0
- package/dist/social/sdl.d.ts.map +1 -0
- package/dist/social/shape.d.ts +11 -0
- package/dist/social/shape.d.ts.map +1 -0
- package/dist/social/types.d.ts +160 -0
- package/dist/social/types.d.ts.map +1 -0
- package/dist/surface/api.d.ts +16 -0
- package/dist/surface/api.d.ts.map +1 -0
- package/dist/surface/request.d.ts +10 -0
- package/dist/surface/request.d.ts.map +1 -0
- package/dist/surface/signed-in.d.ts +30 -0
- package/dist/surface/signed-in.d.ts.map +1 -0
- package/dist/types.d.ts +117 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/wiring.d.ts +56 -0
- package/dist/wiring.d.ts.map +1 -0
- package/docs/README.md +26 -0
- package/docs/guide/api-keys.md +365 -0
- package/docs/guide/avatars.md +129 -0
- package/docs/guide/context.md +371 -0
- package/docs/guide/directives.md +371 -0
- package/docs/guide/errors.md +318 -0
- package/docs/guide/federation.md +71 -0
- package/docs/guide/invitations.md +269 -0
- package/docs/guide/passkeys.md +207 -0
- package/docs/guide/second-factor.md +238 -0
- package/docs/guide/social.md +190 -0
- package/docs/guide/step-up.md +208 -0
- package/docs/guide/subscriptions.md +255 -0
- package/docs/guide/telemetry.md +45 -0
- package/docs/roadmap.md +124 -0
- package/docs/troubleshooting.md +1265 -0
- package/graphql/janus-api-keys.graphqls +237 -0
- package/graphql/janus-avatar.graphqls +19 -0
- package/graphql/janus-invitations.graphqls +280 -0
- package/graphql/janus-passkey-sign-in.graphqls +40 -0
- package/graphql/janus-passkeys.graphqls +134 -0
- package/graphql/janus-second-factor.graphqls +199 -0
- package/graphql/janus-social.graphqls +155 -0
- package/graphql/janus.graphqls +44 -0
- package/package.json +80 -5
|
@@ -0,0 +1,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
|
+
```
|