@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.
- package/README.md +35 -13
- 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 +1 -1
- package/dist/auth/config/resolve-social.d.ts.map +1 -1
- package/dist/auth/config/resolved-config.d.ts +3 -1
- package/dist/auth/config/resolved-config.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/events.d.ts +3 -2
- package/dist/auth/events.d.ts.map +1 -1
- package/dist/auth/first-proof.d.ts +10 -2
- package/dist/auth/first-proof.d.ts.map +1 -1
- package/dist/auth/index.d.ts +1 -1
- package/dist/auth/index.d.ts.map +1 -1
- package/dist/auth/shared-api.d.ts.map +1 -1
- package/dist/auth/social/complete-link.d.ts +9 -1
- package/dist/auth/social/complete-link.d.ts.map +1 -1
- package/dist/auth/social/complete.d.ts +1 -0
- package/dist/auth/social/complete.d.ts.map +1 -1
- package/dist/auth/social/finish.d.ts +3 -0
- package/dist/auth/social/finish.d.ts.map +1 -1
- package/dist/auth/social/link-holder.d.ts +10 -1
- package/dist/auth/social/link-holder.d.ts.map +1 -1
- package/dist/auth/social/redeem.d.ts +2 -0
- package/dist/auth/social/redeem.d.ts.map +1 -1
- package/dist/auth/social/replace-holder.d.ts +37 -0
- package/dist/auth/social/replace-holder.d.ts.map +1 -0
- package/dist/auth/social/sign-in.d.ts +4 -1
- package/dist/auth/social/sign-in.d.ts.map +1 -1
- package/dist/auth/social/sign-up.d.ts +1 -0
- package/dist/auth/social/sign-up.d.ts.map +1 -1
- package/dist/auth/types/social.d.ts +4 -1
- package/dist/auth/types/social.d.ts.map +1 -1
- package/dist/index.js +91 -19
- package/dist/index.js.map +14 -13
- package/docs/guide/email-flows.md +6 -1
- package/docs/guide/errors.md +3 -3
- package/docs/guide/events.md +7 -7
- package/docs/guide/magic-link.md +1 -1
- package/docs/guide/social.md +102 -5
- package/docs/roadmap.md +1 -0
- package/docs/troubleshooting.md +21 -0
- 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
|
|
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
|
package/docs/guide/errors.md
CHANGED
|
@@ -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,
|
|
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
|
|
package/docs/guide/events.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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)
|
|
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
|
package/docs/guide/magic-link.md
CHANGED
|
@@ -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
|
|
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`
|
package/docs/guide/social.md
CHANGED
|
@@ -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)
|
package/docs/troubleshooting.md
CHANGED
|
@@ -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>"`.
|