@softistx/janus 0.74.0 → 0.76.0
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/README.md +31 -6
- package/dist/auth/config/index.d.ts +1 -1
- package/dist/auth/config/index.d.ts.map +1 -1
- package/dist/auth/config/resolve-social.d.ts.map +1 -1
- package/dist/auth/config/social-config.d.ts +31 -0
- package/dist/auth/config/social-config.d.ts.map +1 -1
- package/dist/auth/index.d.ts +2 -2
- package/dist/auth/index.d.ts.map +1 -1
- package/dist/auth/passkeys/assert.d.ts +2 -0
- package/dist/auth/passkeys/assert.d.ts.map +1 -1
- package/dist/auth/passkeys/assertion-options.d.ts +1 -1
- package/dist/auth/passkeys/assertion-options.d.ts.map +1 -1
- package/dist/auth/passkeys/sign-in.d.ts +5 -2
- package/dist/auth/passkeys/sign-in.d.ts.map +1 -1
- package/dist/auth/second-factor/challenge.d.ts +2 -2
- package/dist/auth/second-factor/challenge.d.ts.map +1 -1
- package/dist/auth/second-factor/flows.d.ts +2 -2
- package/dist/auth/second-factor/flows.d.ts.map +1 -1
- package/dist/auth/second-factor/passkey-confirm.d.ts +2 -2
- package/dist/auth/second-factor/passkey-confirm.d.ts.map +1 -1
- package/dist/auth/second-factor/recovery.d.ts.map +1 -1
- package/dist/auth/sessions/amr.d.ts +1 -1
- package/dist/auth/social/complete.d.ts.map +1 -1
- package/dist/auth/social/federated-amr.d.ts +15 -0
- package/dist/auth/social/federated-amr.d.ts.map +1 -0
- package/dist/auth/social/find-provider.d.ts.map +1 -1
- package/dist/auth/social/finish.d.ts +2 -0
- package/dist/auth/social/finish.d.ts.map +1 -1
- package/dist/auth/step-up/passkey.d.ts.map +1 -1
- package/dist/auth/types/index.d.ts +2 -2
- package/dist/auth/types/index.d.ts.map +1 -1
- package/dist/auth/types/passkeys.d.ts +18 -3
- package/dist/auth/types/passkeys.d.ts.map +1 -1
- package/dist/auth/types/second-factor.d.ts +4 -2
- package/dist/auth/types/second-factor.d.ts.map +1 -1
- package/dist/auth/types/sign-in.d.ts +12 -0
- package/dist/auth/types/sign-in.d.ts.map +1 -1
- package/dist/auth/types/step-up.d.ts +4 -2
- package/dist/auth/types/step-up.d.ts.map +1 -1
- package/dist/index.js +127 -34
- package/dist/index.js.map +16 -15
- package/docs/guide/errors.md +1 -1
- package/docs/guide/passkeys.md +27 -4
- package/docs/guide/second-factor.md +1 -0
- package/docs/guide/sessions.md +1 -1
- package/docs/guide/social.md +41 -0
- package/docs/guide/step-up.md +2 -1
- package/docs/roadmap.md +4 -0
- package/docs/troubleshooting.md +19 -2
- package/package.json +1 -1
package/docs/guide/errors.md
CHANGED
|
@@ -66,7 +66,7 @@ that wired the library, so no handler needs to tell it apart.
|
|
|
66
66
|
| `STEP_UP_REQUIRED` | `StepUpRequiredError` | 403 | `assertFresh`: the session proved who it is `maxAge` ago or more; `apiKeys.create` likewise, past `apiKeys.freshWithin`. Not a denial of the action — ask for a [step-up](step-up.md), then send the request again. With `reason: 'apiKey'`, the caller is an API key: it can never be fresh, so a step-up does not help | `userId`; `reason: 'apiKey'` for a key |
|
|
67
67
|
| `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE` | `TokenError` | 400 | See [e-mail flows](email-flows.md#what-a-token-refusal-means). For a second factor's challenge: sign in again; for a sign-in code's: request a new code — see [sign-in codes](sign-in-code.md#what-confirm-refuses); for a sign-in link: ask for a new link — see [sign-in links](magic-link.md#what-confirm-refuses) | `userId` on `TOKEN_STALE` |
|
|
68
68
|
| `CODE_INVALID` | `TokenError` | 401 | A one-time code that does not match: a second factor's, or one already accepted — or a passkey assertion that does not verify (`confirmPasskey`, with the same `attemptsLeft`; see [passkeys](passkeys.md#signing-in-with-a-passkey)) — see [the second factor](second-factor.md#confirming-the-code-at-sign-in) — a recovery code not the user's, or already used — see [recovery codes](second-factor.md#signing-in-with-one) — or a sign-in code sent by e-mail — see [sign-in codes](sign-in-code.md#attempts) | `attemptsLeft` from either `confirm` and from `recover`: what the challenge has left, `0` once it is spent — or `0` with `reason: 'throttled'` and `retryAfter` when the account's own second-step window (`secondFactor.throttle`, ten codes per 15 minutes across challenges) is full: the challenge is not spent, wait; from `regenerateRecoveryCodes`, `spendRecoveryCode` (and `stepUp.confirm` with an app's code), what the user's 15-minute window has left, `0` past the fifth — then with `reason: 'throttled'` and `retryAfter`, the seconds until the window frees: wait, a new challenge does not help; a spent challenge has neither, request a new one — see [regenerating them](second-factor.md#regenerating-them). None from `activate`. `userId` |
|
|
69
|
-
| `SECOND_FACTOR_NOT_ENROLLED` | `SecondFactorError` | 409 | `activate` before `enroll`; `regenerateRecoveryCodes` or `spendRecoveryCode` without an active factor; `confirm`, `recover` or `confirmPasskey` after the factor was disabled; `stepUp.request(user, { via: 'passkey' })` for a user with no passkey | `userId` |
|
|
69
|
+
| `SECOND_FACTOR_NOT_ENROLLED` | `SecondFactorError` | 409 | `activate` before `enroll`; `regenerateRecoveryCodes` or `spendRecoveryCode` without an active factor; `confirm`, `recover` or `confirmPasskey` after the factor was disabled; `stepUp.request(user, { via: 'passkey' })` for a user with no passkey, or with no active TOTP while `passkeys.firstFactor` is off | `userId` |
|
|
70
70
|
| `SECOND_FACTOR_ACTIVE` | `SecondFactorError` | 409 | `enroll` or `activate` on a factor already active: `disable` it first | `userId` |
|
|
71
71
|
| `INVALID_CURSOR` | `InvalidCursorError` | 400 | A cursor this store did not mint. Never a silent first page | |
|
|
72
72
|
| `CURSOR_FILTER_MISMATCH` | `CursorFilterMismatchError` | 400 | `invitations.list({ after })` with a `nextCursor` issued for another scope, status, role, ref, lapsed or order. Never a page of the other list | |
|
package/docs/guide/passkeys.md
CHANGED
|
@@ -44,7 +44,7 @@ const auth = janus({
|
|
|
44
44
|
| `verifier` | required | A `PasskeyVerifier` |
|
|
45
45
|
| `userVerification` | `'preferred'` | `'required'` asks the authenticator to verify the user (PIN, biometrics) and the core refuses any response, at registration, sign-in or step-up, whose verifier reports `userVerified: false`; at sign-in and step-up the refusal counts as a wrong code (a spent attempt); `'discouraged'` does not |
|
|
46
46
|
| `freshWithin` | `'10m'` | How recently the session must have proved who it is to `register` or `remove` |
|
|
47
|
-
| `firstFactor` | `false` | `true` makes a passkey a first factor: [sign in with one alone](#passkey-as-the-first-factor). `secondFactor` is then optional: configure it
|
|
47
|
+
| `firstFactor` | `false` | `true` makes a passkey a first factor: [sign in with one alone](#passkey-as-the-first-factor), and [step up](#stepping-up-with-a-passkey) without a TOTP. `secondFactor` is then optional: configure it for a TOTP, or for a passkey step-up (its keys derive the challenge) |
|
|
48
48
|
| `maxPerUser` | `10` | The passkeys one user may hold: a positive integer. `register` refuses the next with `PASSKEY_LIMIT` (409, `maxActive` carries the cap) |
|
|
49
49
|
|
|
50
50
|
### Related origins
|
|
@@ -191,7 +191,7 @@ at least one. Existing callers that ignore them keep working. The page hands
|
|
|
191
191
|
result back:
|
|
192
192
|
|
|
193
193
|
```ts
|
|
194
|
-
const signedIn = await auth.secondFactor.confirmPasskey(challenge, assertion, { device });
|
|
194
|
+
const signedIn = await auth.secondFactor.confirmPasskey(challenge, assertion, { device }); // signedIn.method === 'passkey'
|
|
195
195
|
```
|
|
196
196
|
|
|
197
197
|
- **The WebAuthn challenge is derived, not stored**: an HMAC (SHA-256, base64url)
|
|
@@ -273,6 +273,21 @@ const { options, challenge, expiresAt } = await auth.passkeys.signInOptions();
|
|
|
273
273
|
const { user, session, token } = await auth.passkeys.signIn(challenge, response, { device });
|
|
274
274
|
```
|
|
275
275
|
|
|
276
|
+
A policy that must refuse some users (an e-mail domain that signs in through
|
|
277
|
+
SSO) goes in `guard`, which runs once the assertion verified and before the
|
|
278
|
+
passkey's use is recorded or any session opens, so a refusal leaves no token
|
|
279
|
+
and no cookie to revoke:
|
|
280
|
+
|
|
281
|
+
```ts
|
|
282
|
+
await auth.passkeys.signIn(challenge, response, {
|
|
283
|
+
guard: (user) => {
|
|
284
|
+
if (String(user.email).endsWith('@acme-sso.example.com')) {
|
|
285
|
+
throw new Error('Use SSO'); // thrown as it is; nothing was opened
|
|
286
|
+
}
|
|
287
|
+
},
|
|
288
|
+
});
|
|
289
|
+
```
|
|
290
|
+
|
|
276
291
|
```ts
|
|
277
292
|
interface PasskeySignInChallenge {
|
|
278
293
|
options: Record<string, unknown>; // for navigator.credentials.get
|
|
@@ -280,7 +295,7 @@ interface PasskeySignInChallenge {
|
|
|
280
295
|
expiresAt: Date;
|
|
281
296
|
}
|
|
282
297
|
signInOptions(): Promise<PasskeySignInChallenge>;
|
|
283
|
-
signIn(challenge: string, response: unknown, options?:
|
|
298
|
+
signIn(challenge: string, response: unknown, options?: PasskeySignInOptions): Promise<SignedIn<User>>;
|
|
284
299
|
```
|
|
285
300
|
|
|
286
301
|
`signIn` answers like a password sign-in (`session.authenticatedAt` is now, the
|
|
@@ -342,7 +357,15 @@ stamped (`authenticatedAt` moves). Its token is marked as a passkey's: a code
|
|
|
342
357
|
sent to `stepUp.confirm` for it, or an assertion sent to `confirmPasskey` for an
|
|
343
358
|
app's or e-mailed challenge, is `TOKEN_UNKNOWN`. `stepUp.request(user)` without `via` is
|
|
344
359
|
unchanged — the app's code for a user with a second factor, an e-mailed code
|
|
345
|
-
otherwise. A user with no passkey is refused with `SECOND_FACTOR_NOT_ENROLLED
|
|
360
|
+
otherwise. A user with no passkey is refused with `SECOND_FACTOR_NOT_ENROLLED`,
|
|
361
|
+
and so is a user with no active TOTP unless `passkeys.firstFactor` is on: a
|
|
362
|
+
passkey stays a second factor beside a TOTP by default (disabling the TOTP
|
|
363
|
+
removes the passkeys, so they never outlive the recovery path). With
|
|
364
|
+
`firstFactor: true` a passkey-only user steps up, and the assertion must carry
|
|
365
|
+
**user verification** (the options ask for `required`, and an assertion with
|
|
366
|
+
`userVerified: false` is `CODE_INVALID`), since the passkey is then the whole
|
|
367
|
+
proof. `secondFactor` keys must still be configured, as they derive the
|
|
368
|
+
challenge.
|
|
346
369
|
The challenge's five attempts and the counter rule are the sign-in's; the
|
|
347
370
|
per-user window the app's codes share is not applied to assertions, which
|
|
348
371
|
cannot be guessed. Like every step-up it exists on types with an e-mail.
|
|
@@ -29,6 +29,7 @@ if (result.status === 'secondFactor') {
|
|
|
29
29
|
// no session yet: ask for a code, then
|
|
30
30
|
const signedIn = await auth.secondFactor.confirm(result.challenge, '654321');
|
|
31
31
|
// or, with the phone gone: await auth.secondFactor.recover(result.challenge, '7k2mq-x9d4c')
|
|
32
|
+
// signedIn.method is 'totp', 'recovery' or 'passkey': alert on 'recovery'; amr is the same for both codes
|
|
32
33
|
}
|
|
33
34
|
```
|
|
34
35
|
|
package/docs/guide/sessions.md
CHANGED
|
@@ -479,7 +479,7 @@ the field existed reads `amr: []`.
|
|
|
479
479
|
| App code (TOTP) as second factor or step-up | `otp`, `mfa` |
|
|
480
480
|
| Recovery code as second factor | `otp`, `mfa` |
|
|
481
481
|
| Passkey as second factor or step-up | `hwk`, `user`, `mfa` |
|
|
482
|
-
| Social sign-in | `fed` |
|
|
482
|
+
| Social sign-in | `fed`, plus what the provider's `federatedAmr` grants ([social](social.md)) |
|
|
483
483
|
| `signInProven` | nothing: the proof is yours |
|
|
484
484
|
|
|
485
485
|
A second factor adds to its first factor's methods (`['pwd', 'otp', 'mfa']`),
|
package/docs/guide/social.md
CHANGED
|
@@ -145,6 +145,46 @@ it only when `result.stepUp !== null` (and, if it matters, that its `acr` or
|
|
|
145
145
|
Rolling deploys: an instance from before this version reading a six-part cookie
|
|
146
146
|
answers `FLOW_MISMATCH`; the visitor starts again.
|
|
147
147
|
|
|
148
|
+
## Recording the provider's proof in the session (`federatedAmr`)
|
|
149
|
+
|
|
150
|
+
A social sign-in records `fed` in `session.amr`. When the provider's ID token
|
|
151
|
+
also says how the user authenticated upstream (`acr: 'urn:example:mfa'`,
|
|
152
|
+
`amr: ['pwd', 'otp']`), a provider you trust can map those claims into the
|
|
153
|
+
session's methods, so step-up policies (`isMultiFactor`, an OAuth approval's
|
|
154
|
+
`amr`) see the federated proof:
|
|
155
|
+
|
|
156
|
+
```ts
|
|
157
|
+
oidcProvider({
|
|
158
|
+
issuer: 'https://login.acme.example',
|
|
159
|
+
clientId, clientSecret, redirectUri,
|
|
160
|
+
federatedAmr: {
|
|
161
|
+
acr: { 'urn:example:mfa': ['mfa'] }, // upstream acr -> session methods
|
|
162
|
+
amr: { otp: ['otp'], hwk: ['hwk', 'user'] }, // each upstream amr value
|
|
163
|
+
},
|
|
164
|
+
});
|
|
165
|
+
// session.amr after a sign-in with acr 'urn:example:mfa': ['fed', 'mfa']
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
- The mapping is **fixed configuration of a provider you trust**: nothing in a
|
|
169
|
+
request, a flow or a stored tenant record can add to it, and unmapped
|
|
170
|
+
upstream values grant nothing. A resolved provider (`resolveProvider`) that
|
|
171
|
+
sets it is checked too: only map claims of an issuer whose configuration
|
|
172
|
+
your own operators control, never a tenant's.
|
|
173
|
+
- Only RFC 8176 methods can be granted (`pwd`, `otp`, `hwk`, `user`, `mfa`,
|
|
174
|
+
`sms`, `swk`, `pin`, `fpt`, `face`, `iris`, `retina`, `mca`, `sc`, `tel`,
|
|
175
|
+
`vbm`, `geo`, `kba`, `rba`, `wia`); anything else is a `TypeError`, at wiring
|
|
176
|
+
or when `resolveProvider` answers the provider, and the core records only
|
|
177
|
+
those methods whatever the mapping holds.
|
|
178
|
+
`fed` is always recorded.
|
|
179
|
+
- The provider reports the evidence on `SocialIdentity` (`acr`, `amr`); the
|
|
180
|
+
core reads at most 16 `amr` values and ignores one that is not an array of
|
|
181
|
+
strings. `oidcProvider` and `oidcStepUp` read both from the ID
|
|
182
|
+
token; a provider you write sets them itself.
|
|
183
|
+
- It records methods on the sign-in's session only. A user whose type has a
|
|
184
|
+
second factor still answers its challenge: the upstream `mfa` does not
|
|
185
|
+
replace it. The core keeps no separate `acr` on the session; `amr` is the
|
|
186
|
+
record.
|
|
187
|
+
|
|
148
188
|
## Configuration
|
|
149
189
|
|
|
150
190
|
`social` sits on a user type, beside `password`. With several types, each
|
|
@@ -195,6 +235,7 @@ await clinic.social.start({ provider: 'github' }); // only patient has social: `
|
|
|
195
235
|
`social`; its type then requires it.
|
|
196
236
|
- **`signUp` receives a frozen `SocialProfile`**: `provider`, `accountId`,
|
|
197
237
|
`email`, `emailVerified`, and `name` and `picture` when the provider gave them.
|
|
238
|
+
It also carries the provider's raw reported `amr` when there is one; that grants nothing (only `federatedAmr` does).
|
|
198
239
|
Answer the schema's fields. The e-mail field must equal the provider's (else
|
|
199
240
|
`USER_INVALID`, nothing written). A `password` or `active` in the answer is
|
|
200
241
|
ignored: the user is created active, verified, with no password.
|
package/docs/guide/step-up.md
CHANGED
|
@@ -119,6 +119,7 @@ See [passkeys](passkeys.md#stepping-up-with-a-passkey). `request(user)` without
|
|
|
119
119
|
`via` is unchanged. A passkey step-up token confirmed with `stepUp.confirm`
|
|
120
120
|
(a code), or an app or e-mail token confirmed with `confirmPasskey`, is refused
|
|
121
121
|
`TOKEN_UNKNOWN`.
|
|
122
|
+
With `firstFactor: true` a passkey-only user (no active TOTP) steps up too, with user verification required (an assertion without it is `CODE_INVALID`); without it a user with no active TOTP is `SECOND_FACTOR_NOT_ENROLLED`. `secondFactor` must be configured for it (its keys derive the challenge); the types expose the passkey step-up only then.
|
|
122
123
|
|
|
123
124
|
A user whose factor is active **confirms with their app, never by e-mail**:
|
|
124
125
|
a step-up is never weaker than the sign-in their account asks for, so
|
|
@@ -190,7 +191,7 @@ user's is refused as `TOKEN_UNKNOWN`, as a challenge nobody issued is.
|
|
|
190
191
|
| `TOKEN_SPENT`, `TOKEN_EXPIRED` | the challenge was used, replaced by a later request, or lapsed |
|
|
191
192
|
| `TOKEN_STALE` | an e-mailed code, and the user changed their e-mail since |
|
|
192
193
|
| `SECOND_FACTOR_ACTIVE` | an e-mailed code, and the user activated a second factor since: request again, the app confirms now |
|
|
193
|
-
| `SECOND_FACTOR_NOT_ENROLLED` | an app's challenge, and the factor was disabled since |
|
|
194
|
+
| `SECOND_FACTOR_NOT_ENROLLED` | an app's challenge, and the factor was disabled since; or a passkey's, with `passkeys.firstFactor` off |
|
|
194
195
|
| `USER_INACTIVE` | the user was deactivated |
|
|
195
196
|
| `VERSION_CONFLICT` | an app's code sent twice at once: the other confirmation stamped the session |
|
|
196
197
|
|
package/docs/roadmap.md
CHANGED
|
@@ -84,12 +84,16 @@ Nothing yet.
|
|
|
84
84
|
The last ten, newest first, each with the version it came in. Everything
|
|
85
85
|
before is in the [CHANGELOG](../CHANGELOG.md).
|
|
86
86
|
|
|
87
|
+
- **Passkey step-up without a TOTP** — next release. With `passkeys.firstFactor`, `stepUp.request(user, { via: 'passkey' })` works for a passkey-only user, with user verification required. [#951](https://github.com/softistx/nxgt-janus/issues/951)
|
|
88
|
+
- **A guard on `passkeys.signIn`** — next release. `options.guard(user)` runs once the assertion verified, before the passkey's use is recorded and before any session opens, to refuse by policy.
|
|
89
|
+
- **The federated proof in the session** — `federatedAmr` on a social provider maps the upstream `acr` / `amr` into `session.amr` (`mfa` and the like), fixed by configuration and limited to RFC 8176 methods; `oidcProvider` and `oidcStepUp` take it. [#937](https://github.com/softistx/nxgt-janus/issues/937)
|
|
87
90
|
- **Counting a provider's links** — `auth.social.countLinks({ provider })`, backed by the optional `SocialLinkStore.countSocialLinks(provider)` of the memory, MongoDB (per partition) and Drizzle stores, so an app can refuse deleting a provider users are still linked through. [#930](https://github.com/softistx/nxgt-janus/issues/930)
|
|
88
91
|
- **Public on npmjs** — every `@softistx/janus*` package is public on registry.npmjs.org and installs without a token or a scope mapping.
|
|
89
92
|
- **Sealing TOTP secrets again** — `secondFactor.reseal({ batch, after })` seals the secrets of users who do not sign in under the first key, in resumable, idempotent batches, so the old key can be retired. [#915](https://github.com/softistx/nxgt-janus/issues/915)
|
|
90
93
|
- **The methods a session proved** — 0.71.0. `session.amr`, the RFC 8176 methods of the sign-in extended by each step-up, with `authenticatedAt` as the time of the last proof, on `authenticate` and every `SignedIn`; `AMR` and `isMultiFactor` exported. The Mongo, Drizzle (a nullable `amr` column) and Redis stores keep it. [#889](https://github.com/softistx/nxgt-janus/issues/889)
|
|
91
94
|
- **A second factor for a passwordless type** — `secondFactor` on a type whose identifier is an e-mail, with the e-mail as the account name; the sign-in code, magic link, `signInProven` and social completion answer its challenge, and a passkey first-factor sign-in asks for none. [#891](https://github.com/softistx/nxgt-janus/issues/891)
|
|
92
95
|
- **Searching users by display name** — 0.66.0. `list({ namePrefix })` and `count({ namePrefix })` keep the users whose name starts with the prefix, case-insensitively and as plain text, beside `emailPrefix`, from a `(type, nameKey)` index in the Mongo and Drizzle stores; `displayName` names the schema field (`name` by default). A store of your own gains `UserFilter.namePrefix` and `UserRecord.nameKey`. [#842](https://github.com/softistx/nxgt-janus/issues/842)
|
|
96
|
+
- **Which second factor opened the session** — `secondFactor.confirm`, `recover` and `confirmPasskey` answer `method: 'totp' | 'recovery' | 'passkey'`, and `confirmSecondFactor` / `recoverSecondFactor` in `@softistx/janus-graphql` answer `method`, so an application can alert on a recovery-code sign-in or record its own `amr`. The session's `amr` is unchanged and the method is not stored on it. [#950](https://github.com/softistx/nxgt-janus/issues/950)
|
|
93
97
|
- **Spending a recovery code outside a sign-in** — 0.64.0. `secondFactor.spendRecoveryCode(user, code)` spends one recovery code from an existing session (turning the second factor off for a lost phone) and answers `{ user, recoveryCodesLeft }`, with no session, event or notice; its attempts share the five-per-15-minutes count of the step-up. [#770](https://github.com/softistx/nxgt-janus/issues/770)
|
|
94
98
|
- **`apiKeys.get` and a bound filter on `apiKeys.list`** — 0.63.0. `get(id, { owner? })` reads one key by id (`null` when unknown, malformed or, with `owner`, another user's), and `list(user, { bound })` pages one user's keys of an object, or the unbound ones with `null`. A new optional `ApiKeyStore` capability, `userBound` (`listUserBoundApiKeys`), answers it in one read; the memory, Mongo and Drizzle stores have it, and a store without it is read 100 keys at a time. [#736](https://github.com/softistx/nxgt-janus/issues/736)
|
|
95
99
|
- **A background runner** — 0.62.0. `background(log?)` returns `run(name, task)` for fire-and-forget work that must not delay a response (an anti-enumeration mail), which logs its failures and never throws, and `settled()` for specs. [Guide](guide/vocabulary.md#background-work)
|
package/docs/troubleshooting.md
CHANGED
|
@@ -185,6 +185,7 @@ How the messages are shaped:
|
|
|
185
185
|
- [`TypeError: deviceCookie(): …` (a name, prefix or attribute the browser would refuse)](#typeerror-devicecookie--a-name-prefix-or-attribute-the-browser-would-refuse)
|
|
186
186
|
- [`<call>: a device was given, but janus() has no devices — pass devices: { keys }`](#call-a-device-was-given-but-janus-has-no-devices--pass-devices--keys-)
|
|
187
187
|
- [`<call>: options must be { device }, or left out — the token goes under device`](#call-options-must-be--device--or-left-out--the-token-goes-under-device)
|
|
188
|
+
- [`passkeys.signIn: options.guard must be a function`](#passkeyssignin-optionsguard-must-be-a-function)
|
|
188
189
|
- [`<call>: options.device must be the device token the client holds, or null when it holds none`](#call-optionsdevice-must-be-the-device-token-the-client-holds-or-null-when-it-holds-none)
|
|
189
190
|
- [Every sign-in reports a new device](#every-sign-in-reports-a-new-device)
|
|
190
191
|
- [A new device is never reported: `newDevice` is always `false`](#a-new-device-is-never-reported-newdevice-is-always-false)
|
|
@@ -204,6 +205,7 @@ How the messages are shaped:
|
|
|
204
205
|
- [`janus: social.providers must name at least one provider, or social.resolveProvider must be given`](#janus-socialproviders-must-name-at-least-one-provider-or-socialresolveprovider-must-be-given)
|
|
205
206
|
- [`janus: social.resolveProvider must be a function …`](#janus-socialresolveprovider-must-be-a-function-)
|
|
206
207
|
- [`social.resolveProvider("<name>") must answer a provider …`](#socialresolveprovidername-must-answer-a-provider-)
|
|
208
|
+
- [`federatedAmr: …`](#federatedamr-)
|
|
207
209
|
- [`SIGN_UP_DISABLED` — `social.complete: nobody holds this account's e-mail, and the user type does not sign strangers up`](#sign_up_disabled--socialcomplete-nobody-holds-this-accounts-e-mail-and-the-user-type-does-not-sign-strangers-up)
|
|
208
210
|
- [`EMAIL_NOT_VERIFIED_FOR_LINK` — `social.complete: a user holds this e-mail, and the provider or the account does not vouch for it …`](#email_not_verified_for_link--socialcomplete-a-user-holds-this-e-mail-and-the-provider-or-the-account-does-not-vouch-for-it--sign-in-another-way-then-link-the-account)
|
|
209
211
|
- [`SOCIAL_ACCOUNT_TAKEN` — `social.complete: this social account is already linked to another user`](#social_account_taken--socialcomplete-this-social-account-is-already-linked-to-another-user)
|
|
@@ -2464,6 +2466,12 @@ be silently untracked: no token, no notice.
|
|
|
2464
2466
|
await auth.signIn(credentials, { device: token ?? null });
|
|
2465
2467
|
```
|
|
2466
2468
|
|
|
2469
|
+
### `passkeys.signIn: options.guard must be a function`
|
|
2470
|
+
|
|
2471
|
+
**When:** from JavaScript or through a cast, `auth.passkeys.signIn(challenge, response, { guard })` was given something that is not a function.
|
|
2472
|
+
**Why:** it is checked before the challenge is spent, so the visitor loses nothing.
|
|
2473
|
+
**Fix:** pass `guard: (user) => { … }` (it may be async and throws to refuse), or leave it out.
|
|
2474
|
+
|
|
2467
2475
|
### `<call>: options.device must be the device token the client holds, or null when it holds none`
|
|
2468
2476
|
|
|
2469
2477
|
**When:** from JavaScript, or through a cast, a `device` that is neither a
|
|
@@ -2713,6 +2721,13 @@ A `TypeError` at `start`, `link` or `complete`: the resolver answered something
|
|
|
2713
2721
|
**Why:** a bug in the resolver, not a refusal. At `complete` the flow was already spent, so the user starts again.
|
|
2714
2722
|
**Fix:** answer `null` for an unknown name and a built `SocialProvider` otherwise.
|
|
2715
2723
|
|
|
2724
|
+
### `federatedAmr: …`
|
|
2725
|
+
|
|
2726
|
+
A `TypeError` at wiring (`social.providers.<name>`) or when `social.resolveProvider("<name>")` answers a provider: the provider's `federatedAmr` has an unknown key, is not `{ acr?, amr? }`, maps an upstream value to something other than a non-empty array, or lists a method outside RFC 8176.
|
|
2727
|
+
|
|
2728
|
+
**Why:** the mapping decides what the session records, so a bad one is refused rather than guessed. `fed` is always recorded and cannot be listed.
|
|
2729
|
+
**Fix:** keep only `acr` and `amr`, map each upstream value to an array of RFC 8176 methods (`pwd`, `otp`, `hwk`, `user`, `mfa`, `sms`, `swk`, `pin`, `fpt`, `face`, `iris`, `retina`, `mca`, `sc`, `tel`, `vbm`, `geo`, `kba`, `rba`, `wia`), and drop `fed`.
|
|
2730
|
+
|
|
2716
2731
|
### `SIGN_UP_DISABLED` — `social.complete: nobody holds this account's e-mail, and the user type does not sign strangers up`
|
|
2717
2732
|
|
|
2718
2733
|
`SocialError`, 403, carrying `provider`.
|
|
@@ -2858,10 +2873,12 @@ Only with `passkeys.firstFactor` off: with it on, a passkey needs no TOTP.
|
|
|
2858
2873
|
|
|
2859
2874
|
**When:** a user without an **active** TOTP — none, or one enrolled but never activated — asks to register a passkey.
|
|
2860
2875
|
**Why:** a passkey is a second factor beside TOTP, never instead of it.
|
|
2861
|
-
**Fix:** answer 409 and send the user through `secondFactor.enroll` and `activate` first.
|
|
2876
|
+
**Fix:** answer 409 and send the user through `secondFactor.enroll` and `activate` first. A passkey-only user is served by `passkeys: { firstFactor: true }`, which also lets `stepUp.request(user, { via: 'passkey' })` work without a TOTP (user verification then required); `stepUp.request` raises the same code, with `a passkey is only registered beside one`, while it is off.
|
|
2862
2877
|
|
|
2863
2878
|
### `CODE_INVALID` — `secondFactor.confirmPasskey` / `stepUp.confirmPasskey` refused an assertion
|
|
2864
2879
|
|
|
2880
|
+
A passkey step-up of a user with no active TOTP also refuses an assertion without user verification (`userVerified: false`).
|
|
2881
|
+
|
|
2865
2882
|
`TokenError`, 401, carrying `attemptsLeft`, `userId` and `userType`.
|
|
2866
2883
|
|
|
2867
2884
|
**When:** the browser's answer did not verify; named a credential that is not the user's or does not exist; was made for another challenge (another `signIn`, or a step-up's); had a counter that did not move forward (both counters non-zero) — which also emits `user.passkeyCloneSuspected`; or the sealing keys were rotated between `signIn` and the assertion.
|
|
@@ -2878,7 +2895,7 @@ if (result.status === 'secondFactor' && result.methods.includes('passkey')) {
|
|
|
2878
2895
|
|
|
2879
2896
|
`SecondFactorError`, 409, carrying `userId` and `userType`. Also `stepUp.confirmPasskey: the user no longer has a second factor — request a step-up again` (the TOTP was disabled between the request and the confirmation: the challenge is spent), and `secondFactor.confirmPasskey: the user no longer has a second factor — sign in again`.
|
|
2880
2897
|
|
|
2881
|
-
**When:** `stepUp.request(user, { via: 'passkey' })` for a user with no passkey
|
|
2898
|
+
**When:** `stepUp.request(user, { via: 'passkey' })` for a user with no passkey, or without an active TOTP while `passkeys.firstFactor` is off.
|
|
2882
2899
|
**Why:** nothing could answer the challenge, and a code is not silently sent instead.
|
|
2883
2900
|
**Fix:** for the "no longer has a second factor" form, request a new step-up (or sign in again) with what the user has now. Otherwise offer `stepUp.request(user)` (the app's code) to a user with no passkey, or send them to register one. Read `result.methods` / `passkeys.list(user)` to decide which to offer.
|
|
2884
2901
|
|