@softistx/janus-graphql 0.0.0-stage → 0.30.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (207) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +716 -2
  3. package/dist/api-keys/index.d.ts +11 -0
  4. package/dist/api-keys/index.d.ts.map +1 -0
  5. package/dist/api-keys/resolvers/deps.d.ts +39 -0
  6. package/dist/api-keys/resolvers/deps.d.ts.map +1 -0
  7. package/dist/api-keys/resolvers/index.d.ts +39 -0
  8. package/dist/api-keys/resolvers/index.d.ts.map +1 -0
  9. package/dist/api-keys/resolvers/list.d.ts +16 -0
  10. package/dist/api-keys/resolvers/list.d.ts.map +1 -0
  11. package/dist/api-keys/resolvers/manage.d.ts +17 -0
  12. package/dist/api-keys/resolvers/manage.d.ts.map +1 -0
  13. package/dist/api-keys/sdl.d.ts +14 -0
  14. package/dist/api-keys/sdl.d.ts.map +1 -0
  15. package/dist/api-keys/shape.d.ts +38 -0
  16. package/dist/api-keys/shape.d.ts.map +1 -0
  17. package/dist/api-keys/types.d.ts +149 -0
  18. package/dist/api-keys/types.d.ts.map +1 -0
  19. package/dist/avatar/index.d.ts +32 -0
  20. package/dist/avatar/index.d.ts.map +1 -0
  21. package/dist/avatar/resolvers.d.ts +41 -0
  22. package/dist/avatar/resolvers.d.ts.map +1 -0
  23. package/dist/avatar/sdl.d.ts +16 -0
  24. package/dist/avatar/sdl.d.ts.map +1 -0
  25. package/dist/bad-input.d.ts +17 -0
  26. package/dist/bad-input.d.ts.map +1 -0
  27. package/dist/connection/connection.d.ts +36 -0
  28. package/dist/connection/connection.d.ts.map +1 -0
  29. package/dist/connection/credential.d.ts +34 -0
  30. package/dist/connection/credential.d.ts.map +1 -0
  31. package/dist/connection/types.d.ts +61 -0
  32. package/dist/connection/types.d.ts.map +1 -0
  33. package/dist/context/create.d.ts +32 -0
  34. package/dist/context/create.d.ts.map +1 -0
  35. package/dist/context/index.d.ts +9 -0
  36. package/dist/context/index.d.ts.map +1 -0
  37. package/dist/context/registry.d.ts +72 -0
  38. package/dist/context/registry.d.ts.map +1 -0
  39. package/dist/context/resolve.d.ts +20 -0
  40. package/dist/context/resolve.d.ts.map +1 -0
  41. package/dist/device.d.ts +28 -0
  42. package/dist/device.d.ts.map +1 -0
  43. package/dist/directives/apply.d.ts +51 -0
  44. package/dist/directives/apply.d.ts.map +1 -0
  45. package/dist/directives/guard.d.ts +22 -0
  46. package/dist/directives/guard.d.ts.map +1 -0
  47. package/dist/directives/permission/enforce.d.ts +24 -0
  48. package/dist/directives/permission/enforce.d.ts.map +1 -0
  49. package/dist/directives/permission/model.d.ts +35 -0
  50. package/dist/directives/permission/model.d.ts.map +1 -0
  51. package/dist/directives/permission/path.d.ts +31 -0
  52. package/dist/directives/permission/path.d.ts.map +1 -0
  53. package/dist/directives/permission/validate.d.ts +42 -0
  54. package/dist/directives/permission/validate.d.ts.map +1 -0
  55. package/dist/directives/read.d.ts +43 -0
  56. package/dist/directives/read.d.ts.map +1 -0
  57. package/dist/directives/validate.d.ts +39 -0
  58. package/dist/directives/validate.d.ts.map +1 -0
  59. package/dist/directives/words.d.ts +7 -0
  60. package/dist/directives/words.d.ts.map +1 -0
  61. package/dist/errors/denial.d.ts +6 -0
  62. package/dist/errors/denial.d.ts.map +1 -0
  63. package/dist/errors/index.d.ts +12 -0
  64. package/dist/errors/index.d.ts.map +1 -0
  65. package/dist/errors/janus-error.d.ts +20 -0
  66. package/dist/errors/janus-error.d.ts.map +1 -0
  67. package/dist/errors/mask.d.ts +69 -0
  68. package/dist/errors/mask.d.ts.map +1 -0
  69. package/dist/fresh.d.ts +44 -0
  70. package/dist/fresh.d.ts.map +1 -0
  71. package/dist/helpers.d.ts +56 -0
  72. package/dist/helpers.d.ts.map +1 -0
  73. package/dist/index.d.ts +86 -0
  74. package/dist/index.d.ts.map +1 -0
  75. package/dist/index.js +3393 -0
  76. package/dist/index.js.map +75 -0
  77. package/dist/invitations/index.d.ts +12 -0
  78. package/dist/invitations/index.d.ts.map +1 -0
  79. package/dist/invitations/resolvers/anonymous.d.ts +11 -0
  80. package/dist/invitations/resolvers/anonymous.d.ts.map +1 -0
  81. package/dist/invitations/resolvers/deps.d.ts +38 -0
  82. package/dist/invitations/resolvers/deps.d.ts.map +1 -0
  83. package/dist/invitations/resolvers/index.d.ts +37 -0
  84. package/dist/invitations/resolvers/index.d.ts.map +1 -0
  85. package/dist/invitations/resolvers/owner.d.ts +17 -0
  86. package/dist/invitations/resolvers/owner.d.ts.map +1 -0
  87. package/dist/invitations/sdl/accept.d.ts +7 -0
  88. package/dist/invitations/sdl/accept.d.ts.map +1 -0
  89. package/dist/invitations/sdl/index.d.ts +14 -0
  90. package/dist/invitations/sdl/index.d.ts.map +1 -0
  91. package/dist/invitations/sdl/owner.d.ts +8 -0
  92. package/dist/invitations/sdl/owner.d.ts.map +1 -0
  93. package/dist/invitations/shape.d.ts +63 -0
  94. package/dist/invitations/shape.d.ts.map +1 -0
  95. package/dist/invitations/types/index.d.ts +5 -0
  96. package/dist/invitations/types/index.d.ts.map +1 -0
  97. package/dist/invitations/types/options.d.ts +104 -0
  98. package/dist/invitations/types/options.d.ts.map +1 -0
  99. package/dist/invitations/types/out.d.ts +136 -0
  100. package/dist/invitations/types/out.d.ts.map +1 -0
  101. package/dist/invitations/types/surface.d.ts +18 -0
  102. package/dist/invitations/types/surface.d.ts.map +1 -0
  103. package/dist/map-code.d.ts +10 -0
  104. package/dist/map-code.d.ts.map +1 -0
  105. package/dist/mask-error.d.ts +18 -0
  106. package/dist/mask-error.d.ts.map +1 -0
  107. package/dist/memo.d.ts +16 -0
  108. package/dist/memo.d.ts.map +1 -0
  109. package/dist/options.d.ts +17 -0
  110. package/dist/options.d.ts.map +1 -0
  111. package/dist/passkeys/deps.d.ts +23 -0
  112. package/dist/passkeys/deps.d.ts.map +1 -0
  113. package/dist/passkeys/first-factor.types.d.ts +38 -0
  114. package/dist/passkeys/first-factor.types.d.ts.map +1 -0
  115. package/dist/passkeys/index.d.ts +14 -0
  116. package/dist/passkeys/index.d.ts.map +1 -0
  117. package/dist/passkeys/resolvers.d.ts +23 -0
  118. package/dist/passkeys/resolvers.d.ts.map +1 -0
  119. package/dist/passkeys/sdl.d.ts +14 -0
  120. package/dist/passkeys/sdl.d.ts.map +1 -0
  121. package/dist/passkeys/shape.d.ts +14 -0
  122. package/dist/passkeys/shape.d.ts.map +1 -0
  123. package/dist/passkeys/sign-in.resolvers.d.ts +19 -0
  124. package/dist/passkeys/sign-in.resolvers.d.ts.map +1 -0
  125. package/dist/passkeys/sign-in.sdl.d.ts +16 -0
  126. package/dist/passkeys/sign-in.sdl.d.ts.map +1 -0
  127. package/dist/passkeys/types.d.ts +193 -0
  128. package/dist/passkeys/types.d.ts.map +1 -0
  129. package/dist/plugin.d.ts +59 -0
  130. package/dist/plugin.d.ts.map +1 -0
  131. package/dist/renewal.d.ts +51 -0
  132. package/dist/renewal.d.ts.map +1 -0
  133. package/dist/report.d.ts +29 -0
  134. package/dist/report.d.ts.map +1 -0
  135. package/dist/sdl.d.ts +12 -0
  136. package/dist/sdl.d.ts.map +1 -0
  137. package/dist/second-factor/index.d.ts +12 -0
  138. package/dist/second-factor/index.d.ts.map +1 -0
  139. package/dist/second-factor/resolvers/deps.d.ts +39 -0
  140. package/dist/second-factor/resolvers/deps.d.ts.map +1 -0
  141. package/dist/second-factor/resolvers/index.d.ts +39 -0
  142. package/dist/second-factor/resolvers/index.d.ts.map +1 -0
  143. package/dist/second-factor/resolvers/sign-in.d.ts +10 -0
  144. package/dist/second-factor/resolvers/sign-in.d.ts.map +1 -0
  145. package/dist/second-factor/resolvers/status.d.ts +10 -0
  146. package/dist/second-factor/resolvers/status.d.ts.map +1 -0
  147. package/dist/second-factor/resolvers/step-up.d.ts +16 -0
  148. package/dist/second-factor/resolvers/step-up.d.ts.map +1 -0
  149. package/dist/second-factor/resolvers/writes.d.ts +19 -0
  150. package/dist/second-factor/resolvers/writes.d.ts.map +1 -0
  151. package/dist/second-factor/sdl.d.ts +14 -0
  152. package/dist/second-factor/sdl.d.ts.map +1 -0
  153. package/dist/second-factor/shape.d.ts +18 -0
  154. package/dist/second-factor/shape.d.ts.map +1 -0
  155. package/dist/second-factor/types/index.d.ts +5 -0
  156. package/dist/second-factor/types/index.d.ts.map +1 -0
  157. package/dist/second-factor/types/options.d.ts +61 -0
  158. package/dist/second-factor/types/options.d.ts.map +1 -0
  159. package/dist/second-factor/types/out.d.ts +84 -0
  160. package/dist/second-factor/types/out.d.ts.map +1 -0
  161. package/dist/second-factor/types/surface.d.ts +89 -0
  162. package/dist/second-factor/types/surface.d.ts.map +1 -0
  163. package/dist/social/index.d.ts +10 -0
  164. package/dist/social/index.d.ts.map +1 -0
  165. package/dist/social/resolvers.d.ts +25 -0
  166. package/dist/social/resolvers.d.ts.map +1 -0
  167. package/dist/social/sdl.d.ts +13 -0
  168. package/dist/social/sdl.d.ts.map +1 -0
  169. package/dist/social/shape.d.ts +11 -0
  170. package/dist/social/shape.d.ts.map +1 -0
  171. package/dist/social/types.d.ts +160 -0
  172. package/dist/social/types.d.ts.map +1 -0
  173. package/dist/surface/api.d.ts +16 -0
  174. package/dist/surface/api.d.ts.map +1 -0
  175. package/dist/surface/request.d.ts +10 -0
  176. package/dist/surface/request.d.ts.map +1 -0
  177. package/dist/surface/signed-in.d.ts +30 -0
  178. package/dist/surface/signed-in.d.ts.map +1 -0
  179. package/dist/types.d.ts +117 -0
  180. package/dist/types.d.ts.map +1 -0
  181. package/dist/wiring.d.ts +56 -0
  182. package/dist/wiring.d.ts.map +1 -0
  183. package/docs/README.md +26 -0
  184. package/docs/guide/api-keys.md +365 -0
  185. package/docs/guide/avatars.md +129 -0
  186. package/docs/guide/context.md +371 -0
  187. package/docs/guide/directives.md +371 -0
  188. package/docs/guide/errors.md +318 -0
  189. package/docs/guide/federation.md +71 -0
  190. package/docs/guide/invitations.md +269 -0
  191. package/docs/guide/passkeys.md +207 -0
  192. package/docs/guide/second-factor.md +238 -0
  193. package/docs/guide/social.md +190 -0
  194. package/docs/guide/step-up.md +208 -0
  195. package/docs/guide/subscriptions.md +255 -0
  196. package/docs/guide/telemetry.md +45 -0
  197. package/docs/roadmap.md +124 -0
  198. package/docs/troubleshooting.md +1265 -0
  199. package/graphql/janus-api-keys.graphqls +237 -0
  200. package/graphql/janus-avatar.graphqls +19 -0
  201. package/graphql/janus-invitations.graphqls +280 -0
  202. package/graphql/janus-passkey-sign-in.graphqls +40 -0
  203. package/graphql/janus-passkeys.graphqls +134 -0
  204. package/graphql/janus-second-factor.graphqls +199 -0
  205. package/graphql/janus-social.graphqls +155 -0
  206. package/graphql/janus.graphqls +44 -0
  207. package/package.json +80 -5
@@ -0,0 +1,238 @@
1
+ # The second factor over GraphQL
2
+
3
+ This page is for letting users hold a TOTP second factor — the six-digit codes
4
+ of an authenticator app — and answer its challenge at sign-in, from a GraphQL
5
+ API: the schema, the resolvers, the cookies, the step-up and the policy you
6
+ keep. It is opt-in: nothing here is declared by `janusTypeDefs`, and a server
7
+ without a second factor imports none of it.
8
+
9
+ What the factor is in Janus, the sealing keys, the states of a factor and
10
+ the recovery codes are
11
+ [`@softistx/janus`'s second-factor guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/second-factor.md).
12
+ This package only puts `auth.secondFactor` and `auth.stepUp` in the schema.
13
+
14
+ ## The schema
15
+
16
+ ```ts
17
+ import {
18
+ janusMaskError,
19
+ janusSecondFactorTypeDefs,
20
+ janusTypeDefs,
21
+ secondFactorChallengeOut,
22
+ secondFactorResolvers,
23
+ secondFactorViewerFields,
24
+ useJanus,
25
+ } from '@softistx/janus-graphql';
26
+ import { createSchema, createYoga } from 'graphql-yoga';
27
+
28
+ const typeDefs = /* GraphQL */ `
29
+ type Query { viewer: Viewer @authenticated }
30
+ type Mutation { signIn(email: String!, password: String!): SignInResult! }
31
+ type Viewer {
32
+ email: String!
33
+ secondFactor: JanusSecondFactorStatus!
34
+ sessionConfirmedUntil: String
35
+ }
36
+ extend type SecondFactorSignedIn { user: Viewer! }
37
+ union SignInResult = SecondFactorSignedIn | JanusSecondFactorChallenge
38
+ `;
39
+
40
+ const options = { auth, freshWithin: '10m' } as const;
41
+
42
+ const yoga = createYoga({
43
+ schema: createSchema({
44
+ typeDefs: [janusTypeDefs, janusSecondFactorTypeDefs, typeDefs],
45
+ resolvers: {
46
+ ...secondFactorResolvers(options),
47
+ Viewer: secondFactorViewerFields(options),
48
+ SecondFactorSignedIn: { user: (signedIn: { user: unknown }) => signedIn.user },
49
+ },
50
+ }),
51
+ plugins: [useJanus({ auth })],
52
+ maskedErrors: { maskError: janusMaskError() },
53
+ });
54
+ ```
55
+
56
+ `secondFactorResolvers` returns `Query` and `Mutation` keys: merge the map with
57
+ yours (`mergeResolvers`) rather than spreading it beside resolvers that have
58
+ the same keys. It throws a `TypeError` when `auth` has no `secondFactor` surface;
59
+ with several user types name the one with `type`. The SDL
60
+ `extend`s `Query` and `Mutation`, so your `typeDefs` declare them.
61
+
62
+ | Operation | What it does |
63
+ | --- | --- |
64
+ | `secondFactor` (`Query`) | `{ enabled, recoveryCodesLeft }` for the signed-in user: `enabled` once the factor is active, `recoveryCodesLeft` null without one |
65
+ | `sessionConfirmedUntil` (`Query`) | When the session's last proof plus `freshWithin` ends; null without `freshWithin` |
66
+ | `enrollSecondFactor` | `{ secret, uri }`: show `uri` as a QR code, `secret` beside it. `SECOND_FACTOR_ACTIVE` when a factor is active |
67
+ | `activateSecondFactor(code)` | The first code of the app: the factor is active, ten recovery codes answered once |
68
+ | `regenerateRecoveryCodes(code)` | Ten new codes on a current code of the app; the old ones stop working |
69
+ | `disableSecondFactor(code)` | Removes the factor on a current code: a step-up of the request's session checks it |
70
+ | `confirmSecondFactor(challenge, code)` | Redeems a sign-in's challenge; sets the session cookie |
71
+ | `recoverSecondFactor(challenge, recoveryCode)` | The same with a recovery code; `recoveryCodesLeft` answers what remains |
72
+ | `requestStepUp` / `confirmStepUp` | See [the step-up](#the-step-up) |
73
+
74
+ `Viewer.secondFactor` and `Viewer.sessionConfirmedUntil` are the same
75
+ resolvers as the two `Query` fields, for your own `Viewer`:
76
+ `secondFactorViewerFields(options)` returns both.
77
+
78
+ ## Signing in
79
+
80
+ The password sign-in is yours: `auth.signIn` answers `status: 'secondFactor'`
81
+ for a user whose factor is active. Answer it as `JanusSecondFactorChallenge`:
82
+
83
+ ```ts
84
+ signIn: async (_: unknown, args: { email: string; password: string }, ctx: { request: Request }) => {
85
+ const result = await auth.signIn(args);
86
+ if (result.status === 'secondFactor') {
87
+ return { __typename: 'JanusSecondFactorChallenge', ...secondFactorChallengeOut(result, ctx.request) };
88
+ }
89
+ // set the session cookie as your sign-in does, then answer a SecondFactorSignedIn
90
+ },
91
+ ```
92
+
93
+ Pass `ctx.request` to `secondFactorChallengeOut`: the challenge is single-use,
94
+ and the response then carries `Cache-Control: no-store` (through `useJanus()`'s
95
+ `onResponse`, over HTTP). Without it nothing is sent, and no cache is told not
96
+ to keep the challenge.
97
+
98
+ `requestStepUp` also answers a single-use `challenge`, and its response carries `Cache-Control: no-store` too.
99
+
100
+ The client then asks for a code and calls `confirmSecondFactor(challenge,
101
+ code)`, or `recoverSecondFactor(challenge, recoveryCode)` for a lost phone.
102
+ Either sets the session cookie through `useJanus()` and answers
103
+ `SecondFactorSignedIn`: `userId`, `expiresAt`, `newDevice` and, after a
104
+ recovery, `recoveryCodesLeft`. `methods` lists `totp` and, for a user with a
105
+ passkey, `passkey` with its `passkeyOptions` (a JSON string); a passkey
106
+ answer goes to `confirmSecondFactorPasskey` of
107
+ [the passkeys guide](passkeys.md).
108
+
109
+ - **`answerToken: true`** answers the session token in `token` and sets no
110
+ cookie, for a backend-for-frontend that keeps it in its own cookie. A
111
+ response that answers the token carries `Cache-Control: no-store` (through
112
+ `useJanus()`'s `onResponse`, over HTTP), so no cache keeps it.
113
+ - **`device: true`** (or the device cookie's options) tracks the device as a
114
+ sign-in mutation does; it needs `janus({ devices })`.
115
+ - A wrong code is `CODE_INVALID` with `attemptsLeft`; the fifth wrong code
116
+ spends the challenge (`TOKEN_SPENT`).
117
+
118
+ ## The step-up
119
+
120
+ `requestStepUp` issues a challenge for the signed-in user; `confirmStepUp`
121
+ checks the code and stamps the request's session as freshly confirmed.
122
+
123
+ - **A user with an active factor** confirms with the code of their app
124
+ (`via: 'secondFactor'`); nothing is sent.
125
+ - **Any other user** gets a code by e-mail (`via: 'email'`), which you send:
126
+ give `sendStepUpCode`, called with `issued.email`, `issued.code` and the
127
+ context. Without it, such a step-up is a `TypeError` (a 500): the package
128
+ has no mailer of its own.
129
+
130
+ ```ts
131
+ const options = {
132
+ auth,
133
+ freshWithin: '10m',
134
+ sendStepUpCode: (issued) => mail.stepUp(issued, { name: issued.user.name }),
135
+ };
136
+ ```
137
+
138
+ The answer never carries the code. `confirmStepUp` answers `{ confirmedAt,
139
+ confirmedUntil }`; `confirmedUntil` is null without `freshWithin`.
140
+
141
+ ## Your policy
142
+
143
+ The core asks for no fresh session before it enrolls, activates, regenerates
144
+ or disables a factor: that is your decision, as options.
145
+
146
+ | Option | Effect |
147
+ | --- | --- |
148
+ | `freshWithin: '10m'` | The four writes call `requireFresh(ctx, '10m')` first: an older session is `STEP_UP_REQUIRED`, 403. `sessionConfirmedUntil` and `confirmStepUp` answer when the proof ends |
149
+ | `guard(action, user, ctx)` | Runs before each write, after the freshness check, with `action` one of `enroll`, `activate`, `regenerateRecoveryCodes`, `disable`. Throw to refuse: an admin who must keep the factor, an e-mail the account must have proved |
150
+ | `sendStepUpCode(issued, ctx)` | Sends the e-mailed step-up code |
151
+
152
+ ```ts
153
+ secondFactorResolvers({
154
+ auth,
155
+ freshWithin: '10m',
156
+ guard: (action, user) => {
157
+ if (action === 'disable' && roleOf(user) === 'admin') {
158
+ throw new GraphQLError('the factor is required of an admin', {
159
+ extensions: { code: 'FORBIDDEN', http: { status: 403 } },
160
+ });
161
+ }
162
+ },
163
+ });
164
+ ```
165
+
166
+ `janus-graphql` counts no attempts of its own: the core counts five per
167
+ challenge, and five app codes per user per 15 minutes across
168
+ `regenerateRecoveryCodes`, `disableSecondFactor` and `confirmStepUp`.
169
+ `activateSecondFactor` is not counted by the core: rate-limit it as any
170
+ authenticated form. Activating does not sign the user's other sessions out;
171
+ do it in your own resolver wrapper when your policy asks for it.
172
+
173
+ ## One auth instance per request
174
+
175
+ `auth` may be a function of the GraphQL context, as `useJanus({ auth })` and
176
+ `passkeyResolvers({ auth })` allow, for a server that builds one `janus()`
177
+ instance per tenant:
178
+
179
+ ```ts
180
+ const authFor = (ctx: { host: string }) => instances.get(ctx.host);
181
+
182
+ const options = { auth: authFor, freshWithin: '10m' } as const;
183
+
184
+ createYoga({
185
+ schema: createSchema({
186
+ typeDefs,
187
+ resolvers: mergeResolvers([secondFactorResolvers(options), mine]),
188
+ }),
189
+ plugins: [useJanus({ auth: authFor, types: ['user'] })],
190
+ context: ({ request }) => ({ host: new URL(request.url).host }),
191
+ });
192
+ ```
193
+
194
+ - The function runs on every second-factor field (and on each `Viewer` field of
195
+ `secondFactorViewerFields()`), may return a promise, and its answer is bound
196
+ once per instance. `null` or `undefined` (no tenant for this host) is
197
+ `UNAUTHENTICATED`, 401.
198
+ - An instance is checked when it is chosen: one with no `secondFactor` is a
199
+ `TypeError` on that request, not at wiring.
200
+ - Give `useJanus()` the same function, so `@authenticated`, `ctx.janus` and the
201
+ field resolvers agree on the instance. Challenges, the factor and the
202
+ step-ups live in the chosen instance's store.
203
+ - `type`, `answerToken`, `device`, `freshWithin`, `guard` and `sendStepUpCode`
204
+ apply to every instance the function answers.
205
+
206
+ ## Traps
207
+
208
+ - **The writes need a session, not an API key.** Under `useJanus({ apiKey:
209
+ true })` a key authenticates as its owner; `enrollSecondFactor`,
210
+ `activateSecondFactor`, `regenerateRecoveryCodes`, `disableSecondFactor`,
211
+ `requestStepUp` and `confirmStepUp` answer it `UNAUTHENTICATED`, so a key
212
+ can neither change its owner's factor nor cancel their step-ups.
213
+ - **No cache.** `enrollSecondFactor`, `activateSecondFactor` and
214
+ `regenerateRecoveryCodes` answer a secret or the recovery codes, once, with
215
+ `Cache-Control: no-store` (through `useJanus()`'s `onResponse`, over HTTP).
216
+ - **`disableSecondFactor` also removes every passkey** of the user: in
217
+ Janus a passkey is a second factor beside TOTP, never instead of it.
218
+ - **A user type with no e-mail has no `stepUp`**, so `disableSecondFactor`,
219
+ `requestStepUp` and `confirmStepUp` throw a `TypeError` naming themselves
220
+ for it; the other fields work. Limit the resolvers to a type with an e-mail
221
+ with `type`.
222
+ - **Your own `requestStepUp` and `confirmStepUp`** collide with the shipped
223
+ fields: see [the step-up guide](step-up.md#the-resolvers).
224
+
225
+ ## Errors
226
+
227
+ A refusal of the core is rethrown as its `GraphQLError`, which
228
+ `janusMaskError()` answers with its code and status:
229
+
230
+ | Code | When |
231
+ | --- | --- |
232
+ | `CODE_INVALID` | a wrong or reused code; `attemptsLeft`, and `reason: 'throttled'` with `retryAfter` once the window is spent |
233
+ | `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED` | an unknown, spent or lapsed challenge: sign in or step up again |
234
+ | `SECOND_FACTOR_ACTIVE` | `enrollSecondFactor` over an active factor |
235
+ | `EMAIL_UNVERIFIED` | `enrollSecondFactor` or `activateSecondFactor` while the account's e-mail is not proved |
236
+ | `SECOND_FACTOR_NOT_ENROLLED` | `activateSecondFactor` before an enrolment; a write that needs an active factor without one |
237
+ | `STEP_UP_REQUIRED` | a stale session, with `freshWithin` |
238
+ | `UNAUTHENTICATED` | no session, on a signed-in operation |
@@ -0,0 +1,190 @@
1
+ # Social sign-in
2
+
3
+ This page is for letting users sign in, sign up and link accounts through an
4
+ external provider (Google, GitHub, …) from a GraphQL API: the schema, the
5
+ resolvers, who keeps the flow, the cookie, the errors and the guards. It is
6
+ opt-in: nothing here is declared by `janusTypeDefs`, and a server without
7
+ social sign-in imports none of it.
8
+
9
+ The flow, the configuration, what `complete` decides and the providers are
10
+ [`@softistx/janus`'s social guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/social.md).
11
+ This package only puts the five calls of `auth.social` in the schema.
12
+
13
+ ## The schema
14
+
15
+ ```ts
16
+ import {
17
+ janusMaskError,
18
+ janusSocialTypeDefs,
19
+ janusTypeDefs,
20
+ socialResolvers,
21
+ useJanus,
22
+ } from '@softistx/janus-graphql';
23
+ import { createSchema, createYoga } from 'graphql-yoga';
24
+
25
+ const typeDefs = /* GraphQL */ `
26
+ type Query { me: Viewer @authenticated }
27
+ type Mutation { noop: Boolean }
28
+ type Viewer { email: String! }
29
+ extend type SocialSignedIn { user: Viewer! }
30
+ `;
31
+
32
+ export const yoga = createYoga({
33
+ schema: createSchema({
34
+ typeDefs: [janusTypeDefs, janusSocialTypeDefs, typeDefs],
35
+ resolvers: {
36
+ ...socialResolvers({ auth }),
37
+ SocialSignedIn: { user: (signedIn) => signedIn.user },
38
+ },
39
+ }),
40
+ plugins: [useJanus({ auth })],
41
+ maskedErrors: { maskError: janusMaskError() },
42
+ });
43
+ ```
44
+
45
+ `janusSocialTypeDefs` (also `graphql/janus-social.graphqls`) `extend`s your
46
+ `Query` and `Mutation`, so both must exist, and it uses `@authenticated` and
47
+ `@fresh`, so `janusTypeDefs` goes beside it. `socialResolvers` returns the
48
+ keys `Query`, `Mutation` and `SocialSignInResult`: with resolvers of your own
49
+ on `Query` or `Mutation`, merge the maps (`mergeResolvers` from
50
+ `@graphql-tools/merge`) instead of spreading over them.
51
+
52
+ | Field | Guard | Answers |
53
+ | --- | --- | --- |
54
+ | `socialSignInStart(provider: String!, returnTo: String)` | none | `SocialFlowStart!`: `url`, `flow`, `expiresAt` |
55
+ | `socialSignInComplete(callbackUrl: String!, flow: String!)` | none | `SocialSignInResult!`: `SocialSignedIn`, `SocialSecondFactor` or `SocialLinked` |
56
+ | `linkSocial(provider: String!, returnTo: String)` | `@authenticated @fresh(maxAge: 600)` | `SocialFlowStart!` |
57
+ | `unlinkSocial(provider: String!, accountId: ID!)` | `@authenticated @fresh(maxAge: 600)` | `Boolean!`: whether this call removed the link |
58
+ | `socialLinks` (on `Query`) | `@authenticated` | `[JanusSocialLink!]!`: `provider`, `accountId`, `email`, `linkedAt` (ISO-8601) |
59
+
60
+ `socialResolvers({ auth, type? })` takes `type` when several user types
61
+ configure `social` (it is passed to `start`, and `socialLinks`, `linkSocial`
62
+ and `unlinkSocial` answer `FORBIDDEN` to a user of another type).
63
+
64
+ ### One auth instance per request
65
+
66
+ `auth` may be a function of the GraphQL context, as `passkeyResolvers()` and
67
+ `useJanus({ auth })` allow, for a server that builds one `janus()` instance
68
+ per issuer, each with its own `social` providers:
69
+
70
+ ```ts
71
+ const authFor = (ctx: { request?: Request }) =>
72
+ instances.get(new URL(ctx.request?.url ?? '').host); // none: UNAUTHENTICATED
73
+
74
+ createYoga({
75
+ schema: createSchema({
76
+ typeDefs,
77
+ resolvers: { ...socialResolvers({ auth: authFor }), ...mine },
78
+ }),
79
+ plugins: [useJanus({ auth: authFor, types: ['user'] })],
80
+ });
81
+ ```
82
+
83
+ - The function runs on every social field and may return a promise. `null` or
84
+ `undefined` (no issuer for this host), or an instance whose `janus()` has no
85
+ `social`, is `UNAUTHENTICATED`, 401.
86
+ - A flow belongs to the instance that started it: completing it on another
87
+ issuer's instance is refused by that instance (`FLOW_MISMATCH` or
88
+ `FLOW_EXPIRED`), as its store does not know the flow.
89
+ - Give `useJanus()` the same function, so `@authenticated`, `ctx.janus` and the
90
+ resolvers agree on the instance. `type` and `answerToken` apply to every
91
+ instance the function answers. The type is `SocialAuthSource`.
92
+
93
+ `SocialSignedIn` has no `user` field: your `Viewer` is yours. Extend the type
94
+ as above; its parent carries the signed-in user. It also has `userId`,
95
+ `expiresAt`, `created`, `linked`, `newDevice` and `returnTo`.
96
+
97
+ ## Who keeps the flow
98
+
99
+ The flow is a secret like a session token. **Yoga sets no flow cookie**:
100
+ `socialSignInStart` hands `flow` to the backend-for-frontend that called it,
101
+ which keeps it in its own `HttpOnly`, `SameSite=Lax` cookie, redirects the
102
+ visitor to `url`, and on the callback route calls
103
+ `socialSignInComplete(callbackUrl:, flow:)` with the cookie's value and the
104
+ full callback URL (only its query is read). Never put `flow` in a URL, a log
105
+ or a page. The responses that answer it (`socialSignInStart` and `linkSocial`)
106
+ carry `Cache-Control: no-store` (through `useJanus()`'s `onResponse`, over
107
+ HTTP), and so does a `SocialSecondFactor` answer with its `challenge`.
108
+
109
+ 1. The BFF calls `socialSignInStart(provider: "google", returnTo: "/home")`,
110
+ stores `flow` in its cookie and redirects to `url`.
111
+ 2. The provider redirects to the BFF's callback route.
112
+ 3. The BFF calls `socialSignInComplete` with the cookie and the callback URL,
113
+ forwarding the visitor's session cookie when there is one (a link flow
114
+ needs it), and passes the response's `Set-Cookie` on to the browser.
115
+ 4. It sends the visitor to `returnTo`.
116
+
117
+ ## The session cookie
118
+
119
+ A completed sign-in sets the session cookie, `auth.cookie.serialize(token,
120
+ session)`, on the GraphQL HTTP response, through `useJanus()`'s `onResponse`
121
+ as a renewed session is. So `useJanus()` is required, the server must be
122
+ Yoga (envelop alone never calls `onResponse`), and the BFF must forward the
123
+ response's `Set-Cookie`. A `SocialLinked` answer is not a sign-in and sets
124
+ none. The device cookie is not handled here, as for the other sign-in
125
+ mutations (see [the context](context.md#a-sign-in-mutation-and-the-device-cookie)).
126
+
127
+ ### A token instead of the cookie
128
+
129
+ A backend-for-frontend that keeps the API session in its own cookie and
130
+ forwards it as `Authorization: Bearer` cannot use the janus cookie. Pass
131
+ `answerToken: true`: a completed sign-in then answers the session token in
132
+ `SocialSignedIn.token` and **sets no cookie** (`token` is `null` otherwise).
133
+
134
+ ```ts
135
+ const resolvers = socialResolvers({ auth, answerToken: true });
136
+ ```
137
+
138
+ ```graphql
139
+ mutation($u: String!, $f: String!) {
140
+ socialSignInComplete(callbackUrl: $u, flow: $f) {
141
+ ... on SocialSignedIn { token expiresAt returnTo }
142
+ ... on SocialSecondFactor { challenge expiresAt methods passkeyOptions returnTo }
143
+ }
144
+ }
145
+ ```
146
+
147
+ The BFF stores `token` in its own `HttpOnly` cookie until `expiresAt` and
148
+ sends it on later calls as `Authorization: Bearer <token>`. It is a secret
149
+ like the session cookie: never in a URL, a log or a page. The response that
150
+ answers it carries `Cache-Control: no-store` (through `useJanus()`'s
151
+ `onResponse`, over HTTP), so no cache keeps it. `SocialSecondFactor`
152
+ and `SocialLinked` carry no token, as before.
153
+
154
+ ## Errors
155
+
156
+ Every refusal is a `JanusError` answered through `janusMaskError()` with its
157
+ code and status, and the fixed message of that status:
158
+
159
+ | Code | Status | When |
160
+ | --- | --- | --- |
161
+ | `PROVIDER_ERROR` | 502 | The provider could not be reached, or refused the exchange. Its `cause` and `reason` stay in your logs |
162
+ | `FLOW_MISMATCH`, `FLOW_PURPOSE_MISMATCH`, `FLOW_EXPIRED` | 400 | No flow, a foreign `state`, a changed flow, a flow of the other kind than the `purpose` expected, a lapsed flow |
163
+ | `RETURN_TO_INVALID` | 400 | `returnTo` is not a path of this site |
164
+ | `SOCIAL_PROVIDER_UNKNOWN` | 404 | A provider the user type does not configure |
165
+ | `SOCIAL_ACCOUNT_TAKEN` | 409 | The account is linked to another user |
166
+ | `LAST_SIGN_IN_METHOD` | 409 | `unlinkSocial` of the user's only way to sign in |
167
+ | `SIGN_UP_DISABLED`, `EMAIL_UNVERIFIED`, `EMAIL_NOT_VERIFIED_FOR_LINK`, `USER_INACTIVE` | per `statusOf` | `complete` refused the identity |
168
+ | `STEP_UP_REQUIRED` | 403 | `linkSocial` or `unlinkSocial` on a session older than ten minutes |
169
+ | `BAD_USER_INPUT` | 400 | `callbackUrl` is not a URL |
170
+ | `UNAUTHENTICATED` | 401 | `auth` is a function (one instance per request) and answered no instance, or one with no `social` |
171
+
172
+ A refusal of `complete` also carries, in `extensions`, what the BFF needs to
173
+ answer the visitor: `flowSpent` (`false` means the flow was not spent: keep
174
+ the cookie, the real callback may still come; anything else, clear it) and
175
+ `returnTo`, the path the flow was started with, present only after the flow
176
+ was authenticated, so a redirect to `returnTo?socialError=<code>` is safe.
177
+ `returnTo` is never in the message and not for logs. The account id, the
178
+ e-mail and the provider's error never reach the response.
179
+
180
+ ```json
181
+ { "errors": [{ "message": "Bad gateway", "extensions": { "code": "PROVIDER_ERROR", "returnTo": "/home", "flowSpent": true } }] }
182
+ ```
183
+
184
+ ## Guards
185
+
186
+ `linkSocial` and `unlinkSocial` are `@fresh(maxAge: 600)`, ten minutes, the
187
+ default `social.freshWithin` of the core, which `social.link` enforces
188
+ itself. The SDL's directive is fixed text: if you set another
189
+ `freshWithin`, or want `unlinkSocial` stricter, guard the field yourself
190
+ (`requireFresh()`) or ship the SDL with another `maxAge`.
@@ -0,0 +1,208 @@
1
+ # A step-up over GraphQL
2
+
3
+ This page is for a mutation a stolen session should not run alone: changing
4
+ the e-mail, a payment method, deleting the account. `@fresh(maxAge)` lets it
5
+ run only for a session that proved who it is less than `maxAge` seconds ago;
6
+ older, it answers `STEP_UP_REQUIRED`, and the client proves it again with a
7
+ step-up. `@softistx/janus` issues and checks the code, and stamps the session.
8
+ This page shows the whole flow as GraphQL. For the directive alone, see
9
+ [directives](directives.md#freshmaxage-int); for the step-up itself, every
10
+ error and the codes an app confirms, see
11
+ [`@softistx/janus`'s step-up guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/step-up.md).
12
+
13
+ The two step-up mutations and the second factor around them are also shipped
14
+ as an opt-in schema: [second factor](second-factor.md#the-step-up).
15
+
16
+ ## The schema
17
+
18
+ ```graphql
19
+ type Mutation {
20
+ changeEmail(email: String!): User @fresh(maxAge: 600) # ten minutes
21
+ deleteAccount: Boolean! @fresh(maxAge: 300) # five
22
+
23
+ requestStepUp: StepUpChallenge! @authenticated
24
+ confirmStepUp(challenge: String!, code: String!): Boolean! @authenticated
25
+ }
26
+
27
+ type StepUpChallenge {
28
+ challenge: String!
29
+ via: String! # "email", or "secondFactor": the code is in the user's app
30
+ }
31
+ ```
32
+
33
+ `@fresh` implies a signed-in user: an anonymous request is `UNAUTHENTICATED`,
34
+ 401, before freshness is read. The two step-up mutations need a signed-in
35
+ user and no fresh one: they are how a session becomes fresh.
36
+
37
+ ## The resolvers
38
+
39
+ ```ts
40
+ import { requireUser, type JanusContext } from '@softistx/janus-graphql';
41
+ import type { YogaInitialContext } from 'graphql-yoga';
42
+
43
+ type Context = YogaInitialContext & JanusContext<typeof auth>;
44
+
45
+ const resolvers = {
46
+ Mutation: {
47
+ changeEmail: (_: unknown, { email }: { email: string }, ctx: Context) =>
48
+ users.changeEmail(ctx, email), // runs only on a fresh session
49
+
50
+ requestStepUp: async (_: unknown, __: unknown, ctx: Context) => {
51
+ const user = await requireUser(ctx); // the session's user — never an id the client sent
52
+ const issued = await auth.stepUp.request(user);
53
+ if (issued.via === 'email') {
54
+ await sendMail(issued.email, 'Confirm it is you', `${issued.code} confirms the action.`);
55
+ }
56
+ return { challenge: issued.challenge, via: issued.via }; // never the code
57
+ },
58
+
59
+ confirmStepUp: async (
60
+ _: unknown,
61
+ { challenge, code }: { challenge: string; code: string },
62
+ ctx: Context,
63
+ ) => {
64
+ await auth.stepUp.confirm(ctx.request, challenge, code); // stamps this request's session
65
+ return true;
66
+ },
67
+ },
68
+ };
69
+ ```
70
+
71
+ `stepUp.confirm` takes the **request**, not a user: it stamps the session
72
+ that request presents, and only a standing session of the challenge's user.
73
+ `ctx.request` is the `Request` Yoga puts on the context, and carries the same
74
+ token or cookie as the mutation that was refused. With several user types,
75
+ `stepUp` is on each type that has an e-mail — `auth.patient.stepUp` — and
76
+ `requireUser(ctx, { type: 'patient' })` narrows the user to it.
77
+
78
+ **Wire `janusMaskError()`.** A wrong code is a `JanusError` the resolver lets
79
+ through — `CODE_INVALID`, 401, with `attemptsLeft`, and `retryAfter` once the user's app-code window is spent — and without the mask
80
+ Yoga answers it as a 500.
81
+
82
+ **A schema that already has these two mutations.** `janusSecondFactorTypeDefs`
83
+ declares `requestStepUp: JanusStepUpChallenge!` and `confirmStepUp:
84
+ JanusStepUpConfirmed!`, with the type names of the shipped schema. An app
85
+ that wrote its own `requestStepUp` and `confirmStepUp` (as above, with
86
+ `StepUpChallenge` and `Boolean!`) and adds `janusSecondFactorTypeDefs` gets
87
+ a schema-merge error on the two fields: remove yours and use the shipped
88
+ ones, or leave `janusSecondFactorTypeDefs` out and keep yours.
89
+
90
+ ## What the client does
91
+
92
+ 1. It sends `changeEmail`. The session is older than ten minutes:
93
+
94
+ ```json
95
+ { "data": { "changeEmail": null },
96
+ "errors": [{ "message": "Forbidden", "path": ["changeEmail"], "extensions": { "code": "STEP_UP_REQUIRED" } }] }
97
+ ```
98
+
99
+ The response is a 403. The client reads `extensions.code`, never the
100
+ message, which is the fixed one of the status.
101
+
102
+ 2. It sends `requestStepUp`, and keeps `challenge`. The user reads the code
103
+ in the e-mail — or in their app, when `via` is `"secondFactor"`.
104
+
105
+ 3. It sends `confirmStepUp(challenge, code)`. From now on, the session is
106
+ fresh for `maxAge` seconds.
107
+
108
+ 4. It sends `changeEmail` again, which runs.
109
+
110
+ | `confirmStepUp` answers | Status | The client |
111
+ | --- | --- | --- |
112
+ | `true` | 200 | sends the refused mutation again |
113
+ | `CODE_INVALID`, with `attemptsLeft` | 401 | asks for the code again; at `0`, starts over at `requestStepUp` |
114
+ | `CODE_INVALID`, with `attemptsLeft: 0` and `retryAfter` | 401 | the user's app-code window is spent: shows the wait, `extensions.retryAfter` seconds; a new `requestStepUp` does not help |
115
+ | `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_UNKNOWN`, `TOKEN_STALE` | 400 | starts over at `requestStepUp` |
116
+ | `SECOND_FACTOR_ACTIVE` | 409 | starts over: the user's app confirms now |
117
+ | `SECOND_FACTOR_NOT_ENROLLED` | 409 | starts over: the factor was disabled, an e-mailed code confirms now |
118
+ | `USER_INACTIVE` | 403 | stops: the account was deactivated |
119
+ | `SERVICE_UNAVAILABLE` | 503 | retries later |
120
+
121
+ `requestStepUp` itself answers `USER_INACTIVE`, 403, for a deactivated
122
+ user, and `NOT_FOUND`, 404, for a user with no e-mail to send a code to
123
+ — an optional e-mail left empty.
124
+
125
+ **`@softistx/janus` throttles an e-mailed `stepUp.request` per user** (five in 10
126
+ minutes by default): past that it throws `MAIL_THROTTLED`, answered 429 with a
127
+ `Retry-After` header, and sends nothing; the code last sent still works, so tell
128
+ the user to use the last e-mail they received, or to wait. Limiting per client
129
+ address stays yours (`@softistx/redis` rate limits fit).
130
+
131
+ ## API keys are never fresh
132
+
133
+ With `useJanus({ apiKey: true })`, `@fresh` and `requireFresh()` refuse a
134
+ request authenticated by an API key with `STEP_UP_REQUIRED`, 403, like a stale
135
+ session. Confirming a step-up cannot help: a key has no session, so the client
136
+ must call with a signed-in session instead.
137
+
138
+ ## In a resolver: `requireFresh(ctx, maxAge)`
139
+
140
+ Where the rule depends on the arguments, ask in the resolver:
141
+
142
+ ```ts
143
+ import { requireFresh } from '@softistx/janus-graphql';
144
+
145
+ const resolvers = {
146
+ Mutation: {
147
+ transfer: async (_: unknown, { amount }: { amount: number }, ctx: Context) => {
148
+ if (amount > 1_000) await requireFresh(ctx, '5m'); // STEP_UP_REQUIRED past five minutes
149
+ return payments.transfer(ctx, amount);
150
+ },
151
+ },
152
+ };
153
+ ```
154
+
155
+ It answers the session, and refuses as `@fresh` does. `maxAge` is a
156
+ duration with its unit — `'5m'`, `'300s'` — never a bare number: the
157
+ compiler refuses one, and so does the call at run time, because
158
+ `@softistx/janus` reads a bare number as milliseconds where `@fresh` reads
159
+ seconds.
160
+
161
+ ## Subscriptions
162
+
163
+ **A `@fresh` on the subscription field is checked when it subscribes.** A
164
+ stale session is refused before the stream starts; a fresh one keeps
165
+ receiving events past `maxAge`, as it keeps its session. `@permission` on
166
+ the field is asked again on every event; `@authenticated` reads the
167
+ operation's one authentication, made when it subscribed; its `@fresh` is
168
+ not asked again. To end a stream when the session is no longer fresh, close
169
+ it from the server.
170
+
171
+ Over a WebSocket, the same holds once `janusConnection()` authenticates
172
+ the connection: [subscriptions over graphql-ws](subscriptions.md).
173
+
174
+ **A `@fresh` on the payload's type, or on one of its fields, is checked on
175
+ every event**, as any field is: those fields resolve anew for each event,
176
+ and once the session is past `maxAge` they answer `STEP_UP_REQUIRED` while
177
+ the stream goes on.
178
+
179
+ ```graphql
180
+ type Subscription {
181
+ receipts: Receipt @fresh(maxAge: 600) # checked once, when it subscribes
182
+ }
183
+ type Receipt @fresh(maxAge: 600) { # checked on every event that carries one
184
+ amount: Int
185
+ }
186
+ ```
187
+
188
+ ## Testing it
189
+
190
+ `useJanus({ clock })` is the clock `@fresh` and `requireFresh()` read. Give
191
+ it the one given to `janus()`, and a spec moves both at once:
192
+
193
+ ```ts
194
+ import { fixedClock, janus } from '@softistx/janus';
195
+
196
+ const clock = fixedClock(Date.UTC(2026, 0, 1));
197
+ const auth = janus({ /* … */ clock });
198
+ const yoga = createYoga({ schema, plugins: [useJanus({ auth, clock })] });
199
+
200
+ const { token } = await auth.signUp({ email, password }); // signed in now
201
+ clock.advance(10 * 60_000); // ten minutes later
202
+ // changeEmail now answers STEP_UP_REQUIRED
203
+ ```
204
+
205
+ Without `clock`, both read the system's. A `janus()` on a fixed clock and a
206
+ `useJanus()` without one disagree on the time: a session signed in on
207
+ the fixed clock looks days old, and every `@fresh` field answers
208
+ `STEP_UP_REQUIRED`.