@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.
@@ -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?: SignInOptions): Promise<SignedIn<User>>;
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
@@ -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']`),
@@ -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)
@@ -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`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softistx/janus",
3
- "version": "0.74.0",
3
+ "version": "0.75.0",
4
4
  "description": "Embeddable, type-safe identities and permissions: bring your own database",
5
5
  "license": "MIT",
6
6
  "type": "module",