@softistx/janus 0.75.0 → 0.77.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 +10 -4
- package/dist/auth/index.d.ts +1 -1
- 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/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 +2 -2
- package/dist/auth/step-up/passkey.d.ts.map +1 -1
- package/dist/auth/types/index.d.ts +1 -1
- package/dist/auth/types/index.d.ts.map +1 -1
- package/dist/auth/types/passkeys.d.ts +2 -2
- 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 +24 -14
- package/dist/index.js.map +9 -9
- package/docs/guide/errors.md +1 -1
- package/docs/guide/passkeys.md +11 -3
- package/docs/guide/second-factor.md +1 -0
- package/docs/guide/sessions.md +3 -1
- package/docs/guide/step-up.md +2 -1
- package/docs/roadmap.md +2 -0
- package/docs/troubleshooting.md +9 -7
- 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)
|
|
@@ -357,7 +357,15 @@ stamped (`authenticatedAt` moves). Its token is marked as a passkey's: a code
|
|
|
357
357
|
sent to `stepUp.confirm` for it, or an assertion sent to `confirmPasskey` for an
|
|
358
358
|
app's or e-mailed challenge, is `TOKEN_UNKNOWN`. `stepUp.request(user)` without `via` is
|
|
359
359
|
unchanged — the app's code for a user with a second factor, an e-mailed code
|
|
360
|
-
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.
|
|
361
369
|
The challenge's five attempts and the counter rule are the sign-in's; the
|
|
362
370
|
per-user window the app's codes share is not applied to assertions, which
|
|
363
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'; the session's amr holds 'rec' instead of 'otp'
|
|
32
33
|
}
|
|
33
34
|
```
|
|
34
35
|
|
package/docs/guide/sessions.md
CHANGED
|
@@ -477,11 +477,13 @@ the field existed reads `amr: []`.
|
|
|
477
477
|
| E-mailed code, magic link | `otp` |
|
|
478
478
|
| Passkey sign-in (user verified) | `hwk`, `user` |
|
|
479
479
|
| App code (TOTP) as second factor or step-up | `otp`, `mfa` |
|
|
480
|
-
| Recovery code as second factor | `
|
|
480
|
+
| Recovery code as second factor | `rec`, `mfa` (not grantable through `federatedAmr`) |
|
|
481
481
|
| Passkey as second factor or step-up | `hwk`, `user`, `mfa` |
|
|
482
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
|
+
Sessions stored before this change keep `otp` for a recovery code; test for `rec` to spot one.
|
|
486
|
+
|
|
485
487
|
A second factor adds to its first factor's methods (`['pwd', 'otp', 'mfa']`),
|
|
486
488
|
and a step-up adds to the session's (an e-mailed step-up after a password:
|
|
487
489
|
`['pwd', 'otp']`). Each value once, in the order proved. The table is
|
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,6 +84,7 @@ 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)
|
|
87
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.
|
|
88
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)
|
|
89
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)
|
|
@@ -92,6 +93,7 @@ before is in the [CHANGELOG](../CHANGELOG.md).
|
|
|
92
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)
|
|
93
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)
|
|
94
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` holds `rec` (not `otp`) for a recovery code, with `mfa`. [#950](https://github.com/softistx/nxgt-janus/issues/950), [#960](https://github.com/softistx/nxgt-janus/issues/960)
|
|
95
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)
|
|
96
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)
|
|
97
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
|
@@ -302,19 +302,19 @@ them needs no token and no scope mapping. A 401 or 404 means something still
|
|
|
302
302
|
sends the request elsewhere. The causes, in the order to check them:
|
|
303
303
|
|
|
304
304
|
- **A stale `@softistx` scope.** A `bunfig.toml` `[install.scopes]` entry or an
|
|
305
|
-
`.npmrc` line mapping `@softistx` to another registry (
|
|
306
|
-
unset or expired) sends every `@softistx` request
|
|
307
|
-
and the packages resolve from registry.npmjs.org:
|
|
305
|
+
`.npmrc` line mapping `@softistx` to another registry (a retired private
|
|
306
|
+
one, with a token that is unset or expired) sends every `@softistx` request
|
|
307
|
+
there. Remove the entry and the packages resolve from registry.npmjs.org:
|
|
308
308
|
|
|
309
309
|
```toml
|
|
310
310
|
# delete this from bunfig.toml
|
|
311
311
|
[install.scopes]
|
|
312
|
-
"@softistx" = { url = "https://
|
|
312
|
+
"@softistx" = { url = "https://registry.example.test/", token = "$REGISTRY_TOKEN" }
|
|
313
313
|
```
|
|
314
314
|
|
|
315
315
|
- **The lockfile still names another registry.** A `bun.lock` entry whose
|
|
316
316
|
tarball URL is `https://npm.pkg.github.com/download/…` or
|
|
317
|
-
|
|
317
|
+
a private registry's URL keeps installing from there. Check
|
|
318
318
|
`grep -c "npm.pkg.github.com\|npm.softistx.com" bun.lock`; when it is not 0,
|
|
319
319
|
delete those entries (or the lockfile) and run `bun install` again so they
|
|
320
320
|
re-resolve from registry.npmjs.org.
|
|
@@ -2873,10 +2873,12 @@ Only with `passkeys.firstFactor` off: with it on, a passkey needs no TOTP.
|
|
|
2873
2873
|
|
|
2874
2874
|
**When:** a user without an **active** TOTP — none, or one enrolled but never activated — asks to register a passkey.
|
|
2875
2875
|
**Why:** a passkey is a second factor beside TOTP, never instead of it.
|
|
2876
|
-
**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.
|
|
2877
2877
|
|
|
2878
2878
|
### `CODE_INVALID` — `secondFactor.confirmPasskey` / `stepUp.confirmPasskey` refused an assertion
|
|
2879
2879
|
|
|
2880
|
+
A passkey step-up of a user with no active TOTP also refuses an assertion without user verification (`userVerified: false`).
|
|
2881
|
+
|
|
2880
2882
|
`TokenError`, 401, carrying `attemptsLeft`, `userId` and `userType`.
|
|
2881
2883
|
|
|
2882
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.
|
|
@@ -2893,7 +2895,7 @@ if (result.status === 'secondFactor' && result.methods.includes('passkey')) {
|
|
|
2893
2895
|
|
|
2894
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`.
|
|
2895
2897
|
|
|
2896
|
-
**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.
|
|
2897
2899
|
**Why:** nothing could answer the challenge, and a code is not silently sent instead.
|
|
2898
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.
|
|
2899
2901
|
|