@softistx/janus 0.74.0 → 0.75.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 +21 -2
- 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/sign-in.d.ts +5 -2
- package/dist/auth/passkeys/sign-in.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/types/index.d.ts +1 -1
- package/dist/auth/types/index.d.ts.map +1 -1
- package/dist/auth/types/passkeys.d.ts +16 -1
- package/dist/auth/types/passkeys.d.ts.map +1 -1
- package/dist/index.js +105 -22
- package/dist/index.js.map +10 -9
- package/docs/guide/passkeys.md +16 -1
- package/docs/guide/sessions.md +1 -1
- package/docs/guide/social.md +41 -0
- package/docs/roadmap.md +2 -0
- package/docs/troubleshooting.md +15 -0
- package/package.json +1 -1
package/docs/guide/passkeys.md
CHANGED
|
@@ -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
|
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/roadmap.md
CHANGED
|
@@ -84,6 +84,8 @@ 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
|
+
- **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
|
+
- **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
89
|
- **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
90
|
- **Public on npmjs** — every `@softistx/janus*` package is public on registry.npmjs.org and installs without a token or a scope mapping.
|
|
89
91
|
- **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)
|
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`.
|