@softistx/janus 0.78.0 → 0.79.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.
Files changed (44) hide show
  1. package/README.md +35 -13
  2. package/dist/auth/config/index.d.ts +1 -1
  3. package/dist/auth/config/index.d.ts.map +1 -1
  4. package/dist/auth/config/resolve-social.d.ts +1 -1
  5. package/dist/auth/config/resolve-social.d.ts.map +1 -1
  6. package/dist/auth/config/resolved-config.d.ts +3 -1
  7. package/dist/auth/config/resolved-config.d.ts.map +1 -1
  8. package/dist/auth/config/social-config.d.ts +31 -0
  9. package/dist/auth/config/social-config.d.ts.map +1 -1
  10. package/dist/auth/events.d.ts +3 -2
  11. package/dist/auth/events.d.ts.map +1 -1
  12. package/dist/auth/first-proof.d.ts +10 -2
  13. package/dist/auth/first-proof.d.ts.map +1 -1
  14. package/dist/auth/index.d.ts +1 -1
  15. package/dist/auth/index.d.ts.map +1 -1
  16. package/dist/auth/shared-api.d.ts.map +1 -1
  17. package/dist/auth/social/complete-link.d.ts +9 -1
  18. package/dist/auth/social/complete-link.d.ts.map +1 -1
  19. package/dist/auth/social/complete.d.ts +1 -0
  20. package/dist/auth/social/complete.d.ts.map +1 -1
  21. package/dist/auth/social/finish.d.ts +3 -0
  22. package/dist/auth/social/finish.d.ts.map +1 -1
  23. package/dist/auth/social/link-holder.d.ts +10 -1
  24. package/dist/auth/social/link-holder.d.ts.map +1 -1
  25. package/dist/auth/social/redeem.d.ts +2 -0
  26. package/dist/auth/social/redeem.d.ts.map +1 -1
  27. package/dist/auth/social/replace-holder.d.ts +37 -0
  28. package/dist/auth/social/replace-holder.d.ts.map +1 -0
  29. package/dist/auth/social/sign-in.d.ts +4 -1
  30. package/dist/auth/social/sign-in.d.ts.map +1 -1
  31. package/dist/auth/social/sign-up.d.ts +1 -0
  32. package/dist/auth/social/sign-up.d.ts.map +1 -1
  33. package/dist/auth/types/social.d.ts +4 -1
  34. package/dist/auth/types/social.d.ts.map +1 -1
  35. package/dist/index.js +91 -19
  36. package/dist/index.js.map +14 -13
  37. package/docs/guide/email-flows.md +6 -1
  38. package/docs/guide/errors.md +3 -3
  39. package/docs/guide/events.md +7 -7
  40. package/docs/guide/magic-link.md +1 -1
  41. package/docs/guide/social.md +102 -5
  42. package/docs/roadmap.md +1 -0
  43. package/docs/troubleshooting.md +21 -0
  44. package/package.json +1 -1
@@ -178,7 +178,7 @@ const user = await auth.verifyEmail.confirm(token, { firstProof: true });
178
178
 
179
179
  One write marks the e-mail verified and drops the password and the second
180
180
  factor (active or waiting, with its recovery codes); every session and API key
181
- is revoked and the reset links and second-factor challenges are spent, before and after
181
+ is revoked and the reset links, second-factor challenges and what a session left waiting (an e-mail change, a link flow, a passkey registration, a step-up) are spent, before and after
182
182
  the write. Events: `user.emailVerified`, then `user.passwordChanged` and
183
183
  `user.secondFactorDisabled` when something was dropped. An address **already
184
184
  proved** is confirmed exactly as without the option, and a stale token is still
@@ -315,6 +315,11 @@ readonly changeEmail: {
315
315
  };
316
316
  ```
317
317
 
318
+ A change asked for before the **first proof** of the user's e-mail (a sign-in
319
+ code or link, `verifyEmail.proveFirst`, a social sign-in that replaces an
320
+ unverified holder) is spent by that proof: its link no longer confirms, so
321
+ whoever held the account before cannot move it to their address afterwards.
322
+
318
323
  `send` issues a token for the **new** address and changes nothing. The
319
324
  address is validated as `update` validates it (`USER_INVALID`), the user must
320
325
  be active (`USER_INACTIVE`), and an address equal to the user's current one
@@ -52,7 +52,7 @@ that wired the library, so no handler needs to tell it apart.
52
52
  | `NOT_FOUND` | `NotFoundError` | 404 | `get`, `getUser`, `signInProven`, `verifyEmail.proveFirst`, or a write to a user who is gone. `find*` answers `null` instead | `userId` |
53
53
  | `EMAIL_CHANGE_NEEDS_PROOF` | `EmailChangeNeedsProofError` | 409 | `update` would move the e-mail of a user who holds a second factor (active or waiting) or a passkey: the new address is unproved and its first proof would drop them. Nothing was written. Use [`changeEmail`](email-flows.md#changeemail), which proves the new address and keeps them | `userId`, `userType` |
54
54
  | `LOGIN_TAKEN` | `StoreConflict` (`on: 'login'`) | 409 | Another user of the same type holds the login — on `changeEmail.confirm`, the new address | `login`, `userType` |
55
- | `VERSION_CONFLICT` | `StoreConflict` (`on: 'version'`) | 409 | `ifVersion` no longer matches; nothing was written. From `verifyEmail.confirm(token, { firstProof: true })`, a user written between the read and the proof. From `secondFactor.confirm` or `recover`, the same code used by two sign-ins at once: the other opened the session. From `verifyEmail.proveFirst`, which already retried once: the user was written again during the retry, or the write changed the e-mail address; nothing was proved | `expectedVersion`, `actualVersion` |
55
+ | `VERSION_CONFLICT` | `StoreConflict` (`on: 'version'`) | 409 | `ifVersion` no longer matches; nothing was written. From `verifyEmail.confirm(token, { firstProof: true })`, a user written between the read and the proof. From `secondFactor.confirm` or `recover`, the same code used by two sign-ins at once: the other opened the session. From `verifyEmail.proveFirst`, which already retried once: the user was written again during the retry, or the write changed the e-mail address; nothing was proved. From `social.complete` replacing an unverified holder (`social.unverifiedHolder`), a user written between the read and the proof: start the flow again | `expectedVersion`, `actualVersion` |
56
56
  | `INVITATION_PENDING` | `StoreConflict` (`on: 'pending'`) | 409 | An invitation store refused a write that would make an invitation pending while another pending one holds its scope and address. `invitations.issue` revokes the invitation that was pending when it began and retries; it surfaces when a concurrent issue won the place first (the loser never revokes that winner), or from a store called directly | |
57
57
  | `USER_INVALID` | `UserInvalidError` | 400 | The fields failed the schema | `issues`, field by field |
58
58
  | `AVATAR_ID_INVALID` | `AvatarIdInvalidError` | 400 | The id given to `avatar.set` is not a non-empty string of at most 512 characters that every store can keep. Nothing was read or written | `operation` — never the id |
@@ -84,14 +84,14 @@ that wired the library, so no handler needs to tell it apart.
84
84
  | `PASSKEY_TAKEN` | `PasskeyError` | 409 | `passkeys.register`: the credential is already registered, by this user or another. Nothing was stored | `userId`, `userType` |
85
85
  | `PASSKEY_LIMIT` | `PasskeyLimitError` | 409 | `passkeys.register` for a user who already holds `passkeys.maxPerUser` passkeys (10 by default). Refused before the challenge is spent; remove one, then register | `maxActive`, `userId` |
86
86
  | `FLOW_EXPIRED` | `SocialError` | 400 | `social.complete`: the flow the cookie names is unknown, already used or lapsed (`tokens.socialFlow`, ten minutes). Start again — see [social sign-in](social.md#what-complete-decides) | |
87
- | `FLOW_MISMATCH` | `SocialError` | 400 | `social.complete`: no cookie, a malformed one, a `state` that is not the flow's, a cookie whose contents were changed, or a link flow completed by somebody other than its user | |
87
+ | `FLOW_MISMATCH` | `SocialError` | 400 | `social.complete`: no cookie, a malformed one, a `state` that is not the flow's, a cookie whose contents were changed, a link flow completed by somebody other than its user, or a link flow started before the user's e-mail was proved | |
88
88
  | `FLOW_PURPOSE_MISMATCH` | `SocialError` | 400 | `social.complete` was given a `purpose` (`'signIn'` or `'link'`) and the flow is of the other kind. The flow is spent; nothing was exchanged, linked or signed in — see [social sign-in](social.md#what-complete-decides) | `flowSpent: true` |
89
89
  | `RETURN_TO_INVALID` | `SocialError` | 400 | `social.start` or `social.link`: `returnTo` is not a path of this site — see [`returnTo`](social.md#returnto). Nothing was started | |
90
90
  | `PROVIDER_ERROR` | `SocialError` | 502 | The social provider failed or refused: an error at its authorization endpoint, a failed exchange, a token that did not verify, an unreachable provider, an identity the core cannot keep | `reason`: `'denied'`, `'refused'` or `'unreachable'`, for your logs only; `cause`; `provider` |
91
91
  | `SOCIAL_PROVIDER_UNKNOWN` | `SocialError` | 404 | `social.start` or `social.link` for a provider the user type does not configure | `provider` |
92
92
  | `SOCIAL_STEP_UP_UNMET` | `SocialError` | 403 | `social.complete`: the flow asked for a `stepUp` and the identity does not prove it — no `acr` or one not asked for, no `authTime` or one too old — or the provider no longer supports it. The flow is spent; nobody signed in or linked. See [step-up per request](social.md#step-up-per-request) | `provider`, `returnTo`, `flowSpent`, `reason` (`'acr'` or `'authTime'`, for logs only) |
93
93
  | `SIGN_UP_DISABLED` | `SocialError` | 403 | `social.complete`: nobody holds the account's e-mail and the type has no `social.signUp`. **Reveals that no account exists** | `provider` |
94
- | `EMAIL_NOT_VERIFIED_FOR_LINK` | `SocialError` | 409 | `social.complete`: a user holds the provider's e-mail, but the provider or the user's account does not vouch for it. Nothing was linked. **Reveals that an account exists** | `provider` |
94
+ | `EMAIL_NOT_VERIFIED_FOR_LINK` | `SocialError` | 409 | `social.complete`: a user holds the provider's e-mail, but the provider or the user's account does not vouch for it. Nothing was linked. An unverified account refuses by default; [`social.unverifiedHolder`](social.md#an-unverified-user-holds-the-e-mail) lets a provider that vouches replace it. **Reveals that an account exists** | `provider` |
95
95
  | `SOCIAL_ACCOUNT_TAKEN` | `SocialError` | 409 | The provider account is already linked to another user, or to a user of another type: one account links to one user | `provider` |
96
96
  | `LAST_SIGN_IN_METHOD` | `SocialError` | 409 | `social.unlink` would leave the user no password, no other link and, on a type with no password, no verified e-mail. Nothing was deleted | `provider` |
97
97
 
@@ -44,19 +44,19 @@ The words — **user event**, **listener** — are defined in
44
44
  | `type` | Sent by | Not sent |
45
45
  | --- | --- | --- |
46
46
  | `user.created` | `create`, `signUp` — once the user is inserted, even if `signUp`'s session then fails to open | for a sign-up refused (`LOGIN_TAKEN`, `USER_INVALID`, `PASSWORD_TOO_SHORT`) |
47
- | `user.emailVerified` | `verifyEmail.confirm`, `verifyEmail.proveFirst` and `setEmailVerified` (turning the flag on; clearing it sends no event); `changeEmail.confirm`, whose link reached the new address; `resetPassword.confirm` and `magicLink.confirm`, whose link proves the e-mail; `signInCode.confirm`, whose code does | for an e-mail already verified — `changeEmail.confirm` to the same address in another case included — or a refused confirm |
47
+ | `user.emailVerified` | `verifyEmail.confirm`, `verifyEmail.proveFirst` and `setEmailVerified` (turning the flag on; clearing it sends no event); `changeEmail.confirm`, whose link reached the new address; `resetPassword.confirm` and `magicLink.confirm`, whose link proves the e-mail; `signInCode.confirm`, whose code does; `social.complete` replacing an unverified holder ([`social.unverifiedHolder`](social.md#an-unverified-user-holds-the-e-mail)), with the other events of a first proof | for an e-mail already verified — `changeEmail.confirm` to the same address in another case included — or a refused confirm |
48
48
  | `user.passwordReset` | `resetPassword.confirm` | for `setPassword` or `changePassword` — they are not resets |
49
- | `user.passwordChanged` | `changePassword` and `setPassword` — a first password set on a user created without one included, which carries `first: true` — once the password is written — even if spending the reset links and second-factor challenges it ends then fails; `signInCode.confirm`, `magicLink.confirm`, `verifyEmail.proveFirst` and `verifyEmail.confirm(token, { firstProof: true })` when their first proof of the e-mail dropped a password, after `user.emailVerified` | for a reset, which is `user.passwordReset` alone; for a `changePassword` refused (`CREDENTIALS_INVALID`) |
49
+ | `user.passwordChanged` | `changePassword` and `setPassword` — a first password set on a user created without one included, which carries `first: true` — once the password is written — even if spending the reset links and second-factor challenges it ends then fails; `signInCode.confirm`, `magicLink.confirm`, `verifyEmail.proveFirst`, `verifyEmail.confirm(token, { firstProof: true })` and `social.complete` replacing an unverified holder ([`social.unverifiedHolder`](social.md#an-unverified-user-holds-the-e-mail)) when their first proof of the e-mail dropped a password, after `user.emailVerified` | for a reset, which is `user.passwordReset` alone; for a `changePassword` refused (`CREDENTIALS_INVALID`) |
50
50
  | `user.emailChanged` | `update` and `changeEmail.confirm`, when they changed the e-mail — added, replaced or removed. It carries `formerEmail`, the address before | for an update that leaves the e-mail alone, or changes only its case (`Ada@…` for `ada@…`): compared normalised, the same test that makes the new address unverified; for a type with no e-mail; for an update refused |
51
51
  | `user.secondFactorEnabled` | `secondFactor.activate`, once the first code made the factor active | for `enroll`, which leaves the factor waiting and asked for nowhere; for a code refused |
52
- | `user.secondFactorDisabled` | `secondFactor.disable`, when it removed an **active** factor; `signInCode.confirm`, `magicLink.confirm`, `verifyEmail.proveFirst` and `verifyEmail.confirm(token, { firstProof: true })` when their first proof of the e-mail removed one, after `user.emailVerified` and any `user.passwordChanged` — even if an outage interrupts the sign-outs | for a user who had no factor, a factor still waiting for its first code — it was never asked for — or a second `disable` |
52
+ | `user.secondFactorDisabled` | `secondFactor.disable`, when it removed an **active** factor; `signInCode.confirm`, `magicLink.confirm`, `verifyEmail.proveFirst`, `verifyEmail.confirm(token, { firstProof: true })` and `social.complete` replacing an unverified holder ([`social.unverifiedHolder`](social.md#an-unverified-user-holds-the-e-mail)) when their first proof of the e-mail removed one, after `user.emailVerified` and any `user.passwordChanged` — even if an outage interrupts the sign-outs | for a user who had no factor, a factor still waiting for its first code — it was never asked for — or a second `disable` |
53
53
  | `user.recoveryCodesRegenerated` | `secondFactor.regenerateRecoveryCodes`: the codes the user held stopped working | for `activate`, whose first codes come with `user.secondFactorEnabled`; for a code refused |
54
54
  | `user.recoveryCodeUsed` (not `spendRecoveryCode`, which sends nothing) | `secondFactor.recover`, once the recovery code is spent — even if opening the session then fails | for a recovery code refused. How many are left is not in the event: `secondFactor.recoveryCodesLeft(event.userId)` reads it |
55
55
  | `user.newDeviceSignedIn` | `signIn`, `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm`, `magicLink.confirm` and `signInProven`, given a `device` whose token did not prove this user signed in there — once the sign-in is complete. It carries `sessionId`, the new session's. See [devices](devices.md) | for `signUp`, which mints the first token; for a call given no `device`; for a known device; for a challenge, which opens no session; for a sign-in refused — a wrong password, or a `signIn` refused after its session opened because a password was written meanwhile |
56
56
  | `user.avatarChanged` | `avatar.set`, when it wrote an id different from the user's current one. It carries `formerAvatarId`, the id replaced, `null` for a first avatar | for the same id set again; for a refused id (`AVATAR_ID_INVALID`) |
57
- | `user.avatarRemoved` | `avatar.remove`, or the first proof of an e-mail (`verifyEmail.proveFirst`, a code, a link), when the user had an avatar. It carries `formerAvatarId`, the id it had | for a user with no avatar |
57
+ | `user.avatarRemoved` | `avatar.remove`, or the first proof of an e-mail (`verifyEmail.proveFirst`, a code, a link, `social.complete` replacing an unverified holder), when the user had an avatar. It carries `formerAvatarId`, the id it had | for a user with no avatar |
58
58
  | `user.socialLinked` | `social.complete`, when it linked an account: a link flow, an existing user matched by a verified e-mail, or the user a social sign-up created (after `user.created`). It carries `provider`, never the account's id. See [social sign-in](social.md) | for an account already linked to that user; for a refused link (`SOCIAL_ACCOUNT_TAKEN`, `EMAIL_NOT_VERIFIED_FOR_LINK`) |
59
- | `user.socialUnlinked` | `social.unlink`, when it deleted a link. It carries `provider` | for a link that is not the user's or not there (`false`); for a refused unlink (`LAST_SIGN_IN_METHOD`) |
59
+ | `user.socialUnlinked` | `social.unlink`, when it deleted a link; `social.complete` replacing an unverified holder ([`social.unverifiedHolder`](social.md#an-unverified-user-holds-the-e-mail)), once per link it deleted. It carries `provider` | for a link that is not the user's or not there (`false`); for a refused unlink (`LAST_SIGN_IN_METHOD`) |
60
60
  | `user.passkeyAdded` | `passkeys.register`, once the passkey is stored. It carries `passkey: { credentialId, name }` | for `registrationOptions`, which stores nothing; for a registration refused (`PASSKEY_INVALID`, `PASSKEY_TAKEN`, a spent challenge) |
61
61
  | `user.passkeyRemoved` | `passkeys.remove`, when it deleted a passkey; `secondFactor.disable` (and a first proof that removed an active TOTP), once for each passkey it took with the factor. It carries `passkey: { credentialId, name }` | for a passkey that is not the user's or not there (`false`) |
62
62
  | `user.passkeyCloneSuspected` | `secondFactor.confirmPasskey` and `stepUp.confirmPasskey`, when an assertion's counter did not move forward (both counters non-zero). It carries `passkey: { credentialId, name }` | for a counter of `0`, stored or received, which is always accepted; for any other refusal. The call is refused, the passkey stays active |
@@ -295,7 +295,7 @@ Where the listener runs within a flow, and what an outage does to it:
295
295
  | `update` | after the write — and, when it moved the e-mail, after the user's pending change links are spent | fails the call with `STORE_FAILED`, the write landed; the event is sent all the same, from a `finally` |
296
296
  | `changeEmail.confirm` | after the write — the flow's last step: `user.emailChanged`, then `user.emailVerified` | — (a `VERSION_CONFLICT` or `LOGIN_TAKEN` leaves nothing written and sends nothing; the token is already spent) |
297
297
  | `changePassword`, `setPassword` | **after** the reset links and the second-factor challenges left open are spent | fails the call; the event is sent all the same, from a `finally` |
298
- | `signInCode.confirm`, `magicLink.confirm`, `verifyEmail.proveFirst`, `verifyEmail.confirm` with `{ firstProof: true }` | on an e-mail never verified: **after** every session and API key is revoked and the reset links and second-factor challenges left open are spent — before the write and again after it — and **before** the new session or second-factor challenge is opened. `user.passwordChanged` follows `user.emailVerified` when a password was dropped, then `user.secondFactorDisabled` when an active second factor was removed, then `user.avatarRemoved` when an avatar was cleared. An e-mail already verified sends nothing | fails the call; the events are sent all the same, from a `finally`. An outage in the sign-outs before the write fails the call with nothing written and nothing sent: the next code, link or `proveFirst` proves the e-mail again |
298
+ | `signInCode.confirm`, `magicLink.confirm`, `verifyEmail.proveFirst`, `verifyEmail.confirm` with `{ firstProof: true }`, `social.complete` replacing an unverified holder (which sends `user.socialUnlinked` for each link it deletes before these, and `user.socialLinked` after them) | on an e-mail never verified: **after** every session and API key is revoked and the reset links, second-factor challenges and what a session left waiting (an e-mail change, a link flow, a passkey registration, a step-up) are spent — before the write and again after it — and **before** the new session or second-factor challenge is opened. `user.passwordChanged` follows `user.emailVerified` when a password was dropped, then `user.secondFactorDisabled` when an active second factor was removed, then `user.avatarRemoved` when an avatar was cleared. An e-mail already verified sends nothing | fails the call; the events are sent all the same, from a `finally`. An outage in the sign-outs before the write fails the call with nothing written and nothing sent: the next code, link or `proveFirst` proves the e-mail again |
299
299
  | `secondFactor.activate`, `secondFactor.regenerateRecoveryCodes`, `secondFactor.disable` | after the write — the flow's last step | — |
300
300
  | `avatar.set`, `avatar.remove` | after the write — the flow's last step | — |
301
301
  | `social.complete` (a link), `social.unlink` | after the write — the flow's last step; for a sign-in that links, before the session is opened | fails the call; the event is already sent |
@@ -457,7 +457,7 @@ kept. See [Invitations](invitations.md).
457
457
  ## See also
458
458
 
459
459
  - [E-mail verification, password reset and changing an e-mail](email-flows.md) — the flows that send `user.emailVerified`, `user.passwordReset` and, with `changeEmail`, `user.emailChanged`
460
- - [The second factor](second-factor.md) — `activate` and `disable`, which send `user.secondFactorEnabled` and `user.secondFactorDisabled` — sent too by the first proof of an e-mail by a [code](sign-in-code.md) or a [link](magic-link.md#an-account-someone-else-registered); [recovery codes](second-factor.md#recovery-codes), which send `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`
460
+ - [The second factor](second-factor.md) — `activate` and `disable`, which send `user.secondFactorEnabled` and `user.secondFactorDisabled` — sent too by the first proof of an e-mail by a [code](sign-in-code.md), a [link](magic-link.md#an-account-someone-else-registered) or a [provider replacing an unverified holder](social.md#an-unverified-user-holds-the-e-mail); [recovery codes](second-factor.md#recovery-codes), which send `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`
461
461
  - [Devices](devices.md) — the sign-ins that send `user.newDeviceSignedIn`, the device token and the cookie
462
462
  - [Account avatars](avatars.md) — what to do with `formerAvatarId`, step by step
463
463
  - [Social sign-in](social.md) — what links and unlinks an account
@@ -320,7 +320,7 @@ which applies this proof when the proof is your own — an invitation.
320
320
  (`hasSecondFactor` turns `false`), and so is the avatar (`avatar` turns
321
321
  `null`, `user.avatarRemoved` carries the former id to delete): Ada's sign-in asks for no factor she
322
322
  never set. Every session of the user is revoked, and
323
- the reset links and second-factor challenges still waiting are spent,
323
+ the reset links, second-factor challenges and what a session left waiting (an e-mail change, a link flow, a passkey registration, a step-up) are spent,
324
324
  before that write and again after it: an outage before it leaves the
325
325
  e-mail unproved, so the next link or code runs all of it again.
326
326
  - [`user.emailVerified`](events.md) is sent, then `user.passwordChanged`
@@ -195,6 +195,13 @@ interface SocialConfig {
195
195
  readonly providers?: { readonly [name: string]: SocialProvider };
196
196
  readonly resolveProvider?: SocialProviderResolver;
197
197
  readonly signUp?: false | ((profile: SocialProfile) => unknown);
198
+ readonly unverifiedHolder?:
199
+ | 'refuse'
200
+ | 'replace'
201
+ | ((
202
+ holder: { readonly id: string; readonly type: string },
203
+ profile: SocialProfile,
204
+ ) => 'refuse' | 'replace' | Promise<'refuse' | 'replace'>);
198
205
  readonly freshWithin?: Duration;
199
206
  }
200
207
  ```
@@ -204,6 +211,7 @@ interface SocialConfig {
204
211
  | `social.providers` | `{ [name]: SocialProvider }` | required unless `resolveProvider` is given | The providers, by the application's name for each: lowercase letters, digits and `-`, starting with a letter, at most 32 characters. At least one, unless `resolveProvider` names the rest |
205
212
  | `social.resolveProvider` | `SocialProviderResolver` (`(name) => Promise<SocialProvider \| null>`) | absent | Looks a provider up at request time, [below](#providers-resolved-at-request-time) |
206
213
  | `social.signUp` | `false \| (profile: SocialProfile) => fields` | absent: a stranger is refused | Answers the fields of a new user from the profile. Only on a type whose login is its e-mail |
214
+ | `social.unverifiedHolder` | `'refuse' \| 'replace' \| (holder, profile) => 'refuse' \| 'replace'` | `'refuse'` | What a provider-verified sign-in does with a user who holds the e-mail and never proved it, [below](#an-unverified-user-holds-the-e-mail) |
207
215
  | `social.freshWithin` | `Duration` | `'10m'` | How recently the session must have proved who it is for `social.link` |
208
216
  | `tokens.socialFlow` | `Duration` | `'10m'` | How long a flow waits for its callback |
209
217
 
@@ -314,17 +322,19 @@ await auth.social.start({ provider: 'acme' }); // any name, known at request tim
314
322
 
315
323
  ```ts
316
324
  type SocialCompleted<U, Challenge extends SecondFactorRequired = SecondFactorRequired> =
317
- | (SignedIn<U> & { provider: string; created: boolean; linked: boolean; returnTo: string | null })
318
- | (Challenge & { provider: string; returnTo: string | null })
325
+ | (SignedIn<U> & { provider: string; created: boolean; linked: boolean; replaced: boolean; returnTo: string | null; stepUp: SocialStepUpProof | null })
326
+ | (Challenge & { provider: string; returnTo: string | null; stepUp: SocialStepUpProof | null })
319
327
  | SocialLinked<U>;
320
328
 
321
- interface SocialLinked<U> { status: 'linked'; user: U; link: SocialLink; returnTo: string | null }
329
+ interface SocialLinked<U> { status: 'linked'; user: U; link: SocialLink; returnTo: string | null; stepUp: SocialStepUpProof | null }
322
330
  interface SocialLink { provider: string; accountId: string; email: string | null; linkedAt: Date }
323
331
  ```
324
332
 
325
333
  Switch on `status`: `signedIn` has a `session` and a `token` like `signIn`,
326
334
  `created` (a user was made for this account) and `linked` (this call linked the
327
- account: a sign-up or an e-mail match; `false` for one linked already);
335
+ account: a sign-up or an e-mail match; `false` for one linked already) and
336
+ `replaced` (this call took over an unverified user who held the e-mail,
337
+ [below](#an-unverified-user-holds-the-e-mail); `false` otherwise);
328
338
  Both sign-in variants carry `provider`, the name you gave the provider that vouched.
329
339
  `secondFactor` is a challenge; `linked` answers a link flow. `returnTo` is the
330
340
  path the flow was started with, or `null`.
@@ -338,6 +348,7 @@ For a sign-in flow, the provider's identity decides, in this order:
338
348
  | Linked user is inactive | `USER_INACTIVE` (403) | none |
339
349
  | Not linked; a user of the type holds its e-mail, the provider vouches for it **and** the user verified it | the account is linked, `signedIn`, `linked: true` | `user.socialLinked` |
340
350
  | Not linked; a user holds the e-mail, but the provider or the user does not vouch for it | `EMAIL_NOT_VERIFIED_FOR_LINK` (409) | none |
351
+ | …as above, the provider vouches, the user never verified, and `social.unverifiedHolder` answers `'replace'` | the user is taken over, `signedIn`, `linked: true`, `replaced: true` | `user.socialUnlinked` per link deleted, the events of a first proof (`user.emailVerified`, …), then `user.socialLinked` |
341
352
  | Not linked; nobody holds the e-mail; `social.signUp` is set; the provider vouches for the e-mail | a user is created, verified, no password; `signedIn`, `created: true`, `linked: true` | `user.created`, then `user.socialLinked` |
342
353
  | …as above, but the provider does not vouch for the e-mail, or gave none | `EMAIL_UNVERIFIED` (403); nobody is created | none |
343
354
  | …as above, with `social.signUp` absent or `false` | `SIGN_UP_DISABLED` (403) | none |
@@ -349,6 +360,91 @@ written (the account taken meanwhile, a store outage) is rolled back: the user
349
360
  is deleted again, so the application sees `user.created` then `user.deleted`,
350
361
  and the original failure is the one thrown.
351
362
 
363
+ ### An unverified user holds the e-mail
364
+
365
+ By default a user who holds the provider's e-mail and never proved it blocks
366
+ the sign-in: `EMAIL_NOT_VERIFIED_FOR_LINK`, every time. That is the safe
367
+ answer when somebody may have registered the address with a password of their
368
+ own: linking would leave them a way in. But where anyone can create an
369
+ unverified account for an address (open sign-up, a sign-in code or link that
370
+ creates the user), it also lets them lock the real owner out of the provider
371
+ sign-in, one address at a time, until the account is verified or deleted.
372
+
373
+ `social.unverifiedHolder` chooses:
374
+
375
+ ```ts
376
+ const auth = janus({
377
+ user: z.strictObject({ email: z.email(), name: z.string() }),
378
+ store: createMemoryStores(),
379
+ social: {
380
+ providers: { google },
381
+ // 'refuse' (default) | 'replace' | a function, to decide per provider or address
382
+ unverifiedHolder: (holder, profile) =>
383
+ profile.provider === 'google' && profile.email?.endsWith('@example.com')
384
+ ? 'replace'
385
+ : 'refuse',
386
+ },
387
+ });
388
+
389
+ const done = await auth.social.complete({ callback, flow });
390
+ if (done.status === 'signedIn' && done.replaced) {
391
+ // audit: the unverified account done.user.id was taken over through done.provider
392
+ }
393
+ ```
394
+
395
+ With `'replace'`, the provider's proof counts as the **first proof of the
396
+ e-mail**, with the ending a first sign-in code or `verifyEmail.proveFirst`
397
+ gives it, and more:
398
+
399
+ 1. the user is read again; an inactive one is `USER_INACTIVE`, nothing touched;
400
+ 2. every social account linked to the user is deleted (`user.socialUnlinked`
401
+ each): whoever held the account could have linked their own;
402
+ 3. the first proof runs: the e-mail is verified, the password, the avatar, the
403
+ second factor and its recovery codes, the passkeys and the API keys go,
404
+ every session is revoked, and what the password opened and what a session
405
+ left waiting are spent (reset links, second-factor challenges, an e-mail
406
+ change, a link flow, a passkey registration, a step-up), with the events
407
+ of a first proof;
408
+ 4. links are deleted once more (one linked meanwhile), the provider's account
409
+ is linked (`user.socialLinked`), and the session opens: `linked: true`,
410
+ `replaced: true`.
411
+
412
+ - **Only when the provider vouches.** `emailVerified: false` is
413
+ `EMAIL_NOT_VERIFIED_FOR_LINK` whatever the option says, and the function is
414
+ not asked. A verified user is never replaced: they are linked as before,
415
+ `replaced: false`, and keep everything.
416
+ - **The function** (type `SocialUnverifiedHolder`) **is asked with** the holder (`id`, `type`) and the frozen
417
+ `SocialProfile` (`provider`, `accountId`, `email`, …). Anything it answers
418
+ other than `'replace'` refuses; a throw propagates, nothing touched. Answer
419
+ from your own configuration (which provider owns which domain), never from
420
+ the request.
421
+ - **Trust is yours to place.** `'replace'` trusts every configured provider's
422
+ `emailVerified` for every address. A provider that vouches for addresses it
423
+ does not control (a self-hosted one, a tenant's own) could take over any
424
+ unverified account: allow those only for the domains they own, with the
425
+ function.
426
+ - **What the user's fields held stays**: the name and the other schema fields
427
+ written at sign-up are not reset. Overwrite them from `done.user` and the
428
+ provider's profile if they matter.
429
+ - **What other packages issued stays too**: the core revokes sessions and API
430
+ keys, not the OAuth grants and refresh tokens `@softistx/janus-oauth` issued
431
+ for the user. Revoke them when `replaced` is `true` if an unverified user
432
+ could approve a client.
433
+ - **A link the holder left at the provider is refused.** A link flow started
434
+ before the proof and completed after it is `FLOW_MISMATCH`, spent; one not
435
+ yet at the provider is `FLOW_EXPIRED`. This holds for every first proof of
436
+ an e-mail, and for a user who verifies their e-mail, or confirms an e-mail
437
+ change, between `social.link` and its callback: they start the link again.
438
+ - **An outage midway is safe to retry.** Until the e-mail is verified, the
439
+ next sign-in runs the same steps again; a write landing between the read
440
+ and the proof is `VERSION_CONFLICT`, and the visitor starts the flow again.
441
+ An outage after the proof's write still deletes the links, and leaves the
442
+ account verified with no credential: the next sign-in links it as a
443
+ verified user's and answers `replaced: false`, so record the takeover from
444
+ `user.emailVerified` as well if you audit it.
445
+ - A value that is not `'refuse'`, `'replace'` or a function is a `TypeError`
446
+ at wiring.
447
+
352
448
  **Two of these answers reveal that an account exists**:
353
449
  `EMAIL_NOT_VERIFIED_FOR_LINK` and `SIGN_UP_DISABLED` — as `findByEmail` does.
354
450
  Neither is told to a stranger by any other flow, so answer them to the visitor
@@ -468,7 +564,8 @@ export async function link(request: Request): Promise<Response> {
468
564
  `FLOW_MISMATCH` and is spent. Use `lax` for the session cookie.
469
565
  - **A link flow is for the user who started it.** Completed with no `current`,
470
566
  or another user's, it is `FLOW_MISMATCH`, and the flow is spent; a link flow
471
- cannot be completed as a sign-in.
567
+ cannot be completed as a sign-in. So is one started before the user's
568
+ e-mail was proved and completed after: the user starts the link again.
472
569
  - **An account already linked to this user** answers `linked` with no write
473
570
  and no event. **One linked to another user**, or to a user of another type,
474
571
  is `SOCIAL_ACCOUNT_TAKEN`: one provider account links to one user per
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
+ - **A policy for an unverified account that holds a social sign-in's e-mail** — next release. `social.unverifiedHolder` (`'refuse'` by default, `'replace'`, or a function per provider and address) lets a provider that vouches for the e-mail take over a user who never proved it: their password, factors, passkeys, API keys, links and sessions go first, and the answer carries `replaced: true`. [#978](https://github.com/softistx/nxgt-janus/issues/978)
87
88
  - **Service keys** — next release. `apiKeys.createService` makes a key that belongs to an object, has no user, survives its creator and may never expire (`lifetimes: ['…', 'never']`), with scopes, `details`, `listOwned` and `revokeOwned`; `authenticate(request, { apiKey: true, service: true })` answers it as `via: 'serviceKey'`, and `bearerCaller` as `kind: 'service-key'`. [#964](https://github.com/softistx/nxgt-janus/issues/964)
88
89
  - **Signed tokens** — next release. `signToken` and `verifyToken`: HMAC-signed, expiring links (download, unsubscribe) with a rotatable key list and a derived key per purpose. [#967](https://github.com/softistx/nxgt-janus/issues/967)
89
90
  - **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)
@@ -205,6 +205,7 @@ How the messages are shaped:
205
205
  - [`SOCIAL_PROVIDER_UNKNOWN` — `social.start: the user type configures no such social provider`](#social_provider_unknown--socialstart-the-user-type-configures-no-such-social-provider)
206
206
  - [`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)
207
207
  - [`janus: social.resolveProvider must be a function …`](#janus-socialresolveprovider-must-be-a-function-)
208
+ - [`janus: social.unverifiedHolder must be 'refuse', 'replace' or a function …`](#janus-socialunverifiedholder-must-be-refuse-replace-or-a-function-)
208
209
  - [`social.resolveProvider("<name>") must answer a provider …`](#socialresolveprovidername-must-answer-a-provider-)
209
210
  - [`federatedAmr: …`](#federatedamr-)
210
211
  - [`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)
@@ -2654,6 +2655,8 @@ null) …` — or give every sign-in a `device`.
2654
2655
 
2655
2656
  **A link flow also ends here when your session cookie is `sameSite: 'strict'`.** The provider's callback is a cross-site navigation, so the browser leaves a Strict cookie out, `authenticate` finds no session, the callback has no `current`, and the flow is spent. Use `sameSite: 'lax'` for the session cookie when users link accounts.
2656
2657
 
2658
+ **A link flow started before the user's e-mail was proved ends here too** (`the user's e-mail was proved after this link was started — start it again`): a first proof of the address (a sign-in code or link, `verifyEmail`, `social.unverifiedHolder: 'replace'`) ends what was opened before it, a link waiting at the provider included. Call `social.link` again.
2659
+
2657
2660
  **Fix:** send the cookie with the callback request and give `complete` its value unchanged:
2658
2661
 
2659
2662
  ```ts
@@ -2759,6 +2762,7 @@ social: { providers: { google }, signUp: (profile) => ({ email: profile.email ??
2759
2762
  **When:** the provider's account is not linked, and a user of the type holds its e-mail, but the provider reports `emailVerified: false` or the local account never verified its address.
2760
2763
  **Why:** linking on an address one side has not proved would hand the account to whoever controls the unproven side. Nothing was linked. The answer tells the visitor an account exists for that address.
2761
2764
  **Fix:** the user signs in the way they have, and links from `social.link`, which needs no e-mail match. If the local address is unverified, have them prove it first (`verifyEmail.confirm`). If the account was registered by somebody else, they recover it: `resetPassword`, or `verifyEmail` with `{ firstProof: true }`, which prove the address and drop the squatter's password.
2765
+ **Also:** where anyone can create an unverified account for an address, this refusal locks its real owner out of the provider sign-in. `social.unverifiedHolder: 'replace'` (or a function, per provider and address) lets a provider that vouches for the e-mail take the unverified account over: its credentials, links and sessions go first, and the answer carries `replaced: true`. See [social sign-in](guide/social.md#an-unverified-user-holds-the-e-mail).
2762
2766
 
2763
2767
  ### `SOCIAL_ACCOUNT_TAKEN` — `social.complete: this social account is already linked to another user`
2764
2768
 
@@ -2821,6 +2825,23 @@ An `UnsupportedError` (`UNSUPPORTED`, 501) when `auth.social.countLinks(...)` is
2821
2825
  const socialLinks = { ...mine, countSocialLinks: (provider) => countRows({ provider }) };
2822
2826
  ```
2823
2827
 
2828
+ ### `janus: social.unverifiedHolder must be 'refuse', 'replace' or a function …`
2829
+
2830
+ A `TypeError` at wiring: `<at>: social.unverifiedHolder must be 'refuse', 'replace' or a function that takes the holder and the profile and answers one of them`.
2831
+
2832
+ **When:** `social: { unverifiedHolder }` is something else: `true`, another word, an object.
2833
+ **Why:** the option decides whether a provider may take over an unverified account, so a value that is not understood is refused, not read as a default.
2834
+ **Fix:** leave it out (`'refuse'`), or pass `'replace'` or a function:
2835
+
2836
+ ```ts
2837
+ social: {
2838
+ providers: { google },
2839
+ unverifiedHolder: (holder, profile) => (profile.provider === 'google' ? 'replace' : 'refuse'),
2840
+ },
2841
+ ```
2842
+
2843
+ See [social sign-in](guide/social.md#an-unverified-user-holds-the-e-mail).
2844
+
2824
2845
  ### `janus: social.signUp needs a type whose login is its e-mail …`
2825
2846
 
2826
2847
  A `TypeError` at wiring, and a compile error: `<at>: social.signUp needs a type whose login is its e-mail — password.login is "<field>", not "<email field>"`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softistx/janus",
3
- "version": "0.78.0",
3
+ "version": "0.79.0",
4
4
  "description": "Embeddable, type-safe identities and permissions: bring your own database",
5
5
  "license": "MIT",
6
6
  "type": "module",