@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,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`.
|