@softistx/janus 0.77.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 +42 -15
- package/dist/auth/api-keys/authenticate-key.d.ts +3 -2
- package/dist/auth/api-keys/authenticate-key.d.ts.map +1 -1
- package/dist/auth/api-keys/count.d.ts.map +1 -1
- package/dist/auth/api-keys/create/after-insert.d.ts +11 -0
- package/dist/auth/api-keys/create/after-insert.d.ts.map +1 -0
- package/dist/auth/api-keys/create/checks.d.ts +17 -0
- package/dist/auth/api-keys/create/checks.d.ts.map +1 -1
- package/dist/auth/api-keys/create/index.d.ts.map +1 -1
- package/dist/auth/api-keys/create/service-checks.d.ts +25 -0
- package/dist/auth/api-keys/create/service-checks.d.ts.map +1 -0
- package/dist/auth/api-keys/create/service.d.ts +12 -0
- package/dist/auth/api-keys/create/service.d.ts.map +1 -0
- package/dist/auth/api-keys/expiry.d.ts.map +1 -1
- package/dist/auth/api-keys/flows.d.ts +6 -2
- package/dist/auth/api-keys/flows.d.ts.map +1 -1
- package/dist/auth/api-keys/owned.d.ts +12 -0
- package/dist/auth/api-keys/owned.d.ts.map +1 -0
- package/dist/auth/api-keys/read.d.ts.map +1 -1
- package/dist/auth/api-keys/service-flows.d.ts +13 -0
- package/dist/auth/api-keys/service-flows.d.ts.map +1 -0
- package/dist/auth/api-keys/to-api-key.d.ts.map +1 -1
- package/dist/auth/config/api-keys-config.d.ts +29 -2
- package/dist/auth/config/api-keys-config.d.ts.map +1 -1
- package/dist/auth/config/index.d.ts +2 -2
- package/dist/auth/config/index.d.ts.map +1 -1
- package/dist/auth/config/resolve-api-keys.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 +11 -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 +3 -2
- package/dist/auth/index.d.ts.map +1 -1
- package/dist/auth/port/memory/api-keys/capabilities.d.ts.map +1 -1
- package/dist/auth/port/memory/api-keys/index.d.ts.map +1 -1
- package/dist/auth/port/types/api-keys.d.ts +25 -5
- package/dist/auth/port/types/api-keys.d.ts.map +1 -1
- package/dist/auth/sessions/authenticate.d.ts +3 -2
- package/dist/auth/sessions/authenticate.d.ts.map +1 -1
- package/dist/auth/sessions/fresh.d.ts +2 -2
- package/dist/auth/sessions/fresh.d.ts.map +1 -1
- package/dist/auth/sessions/shared-api.d.ts +3 -2
- package/dist/auth/sessions/shared-api.d.ts.map +1 -1
- package/dist/auth/shared-api.d.ts +11 -3
- package/dist/auth/shared-api.d.ts.map +1 -1
- package/dist/auth/signed-token.d.ts +41 -0
- package/dist/auth/signed-token.d.ts.map +1 -0
- 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/api-keys-of.d.ts +6 -1
- package/dist/auth/types/api-keys-of.d.ts.map +1 -1
- package/dist/auth/types/api-keys.d.ts +18 -6
- package/dist/auth/types/api-keys.d.ts.map +1 -1
- package/dist/auth/types/checks.d.ts +17 -1
- package/dist/auth/types/checks.d.ts.map +1 -1
- package/dist/auth/types/index.d.ts +3 -2
- package/dist/auth/types/index.d.ts.map +1 -1
- package/dist/auth/types/service-keys.d.ts +58 -0
- package/dist/auth/types/service-keys.d.ts.map +1 -0
- package/dist/auth/types/session.d.ts +21 -2
- package/dist/auth/types/session.d.ts.map +1 -1
- package/dist/auth/types/shared-api.d.ts +15 -1
- package/dist/auth/types/shared-api.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/chunks/{index-7h34nqrm.js → index-5hcajrrx.js} +5 -5
- package/dist/chunks/{index-7h34nqrm.js.map → index-5hcajrrx.js.map} +4 -4
- package/dist/chunks/{index-n8jxmxeg.js → index-gzc472ar.js} +2 -2
- package/dist/chunks/{index-ftz0ne6j.js → index-r8fcessc.js} +2 -2
- package/dist/chunks/{index-2ttdcz7n.js → index-vx9a5cpy.js} +9 -3
- package/dist/chunks/{index-2ttdcz7n.js.map → index-vx9a5cpy.js.map} +4 -4
- package/dist/conformance/api-keys/cases/index.d.ts.map +1 -1
- package/dist/conformance/api-keys/cases/outage.d.ts.map +1 -1
- package/dist/conformance/api-keys/cases/service.d.ts +3 -0
- package/dist/conformance/api-keys/cases/service.d.ts.map +1 -0
- package/dist/conformance/index.js +407 -302
- package/dist/conformance/index.js.map +6 -5
- package/dist/errors/janus-error/codes.invitations.d.ts +6 -0
- package/dist/errors/janus-error/codes.invitations.d.ts.map +1 -1
- package/dist/errors/janus-error/index.d.ts +1 -1
- package/dist/errors/janus-error/index.d.ts.map +1 -1
- package/dist/errors/janus-error/options.d.ts +1 -1
- package/dist/errors/janus-error/options.d.ts.map +1 -1
- package/dist/errors/janus-error/refusals.d.ts +5 -0
- package/dist/errors/janus-error/refusals.d.ts.map +1 -1
- package/dist/errors/janus-error/status.d.ts.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +517 -117
- package/dist/index.js.map +32 -25
- package/dist/permissions/index.js +3 -3
- package/docs/README.md +1 -0
- package/docs/guide/api-keys.md +78 -1
- package/docs/guide/email-flows.md +6 -1
- package/docs/guide/errors.md +4 -3
- package/docs/guide/events.md +7 -7
- package/docs/guide/magic-link.md +1 -1
- package/docs/guide/signed-tokens.md +46 -0
- package/docs/guide/social.md +102 -5
- package/docs/roadmap.md +3 -0
- package/docs/troubleshooting.md +33 -0
- package/package.json +1 -1
- /package/dist/chunks/{index-n8jxmxeg.js.map → index-gzc472ar.js.map} +0 -0
- /package/dist/chunks/{index-ftz0ne6j.js.map → index-r8fcessc.js.map} +0 -0
|
@@ -2,7 +2,7 @@ import {
|
|
|
2
2
|
guardRelations,
|
|
3
3
|
isStorable,
|
|
4
4
|
UNSTORABLE
|
|
5
|
-
} from "../chunks/index-
|
|
5
|
+
} from "../chunks/index-gzc472ar.js";
|
|
6
6
|
import {
|
|
7
7
|
PermissionDepthError2,
|
|
8
8
|
MAX_PAGE_SIZE2,
|
|
@@ -11,14 +11,14 @@ import {
|
|
|
11
11
|
isSubjectSet2,
|
|
12
12
|
isSetOf2,
|
|
13
13
|
formatEntity2
|
|
14
|
-
} from "../chunks/index-
|
|
14
|
+
} from "../chunks/index-vx9a5cpy.js";
|
|
15
15
|
import {
|
|
16
16
|
holderCursor2,
|
|
17
17
|
readHolderCursor2,
|
|
18
18
|
idMatches2,
|
|
19
19
|
pageOfHolders2,
|
|
20
20
|
createMemoryRelations2
|
|
21
|
-
} from "../chunks/index-
|
|
21
|
+
} from "../chunks/index-r8fcessc.js";
|
|
22
22
|
|
|
23
23
|
// src/permissions/resolve/resolved.ts
|
|
24
24
|
function admits(holders, subject) {
|
package/docs/README.md
CHANGED
|
@@ -17,6 +17,7 @@ below are defined once, in [Words](guide/vocabulary.md#words).
|
|
|
17
17
|
| [Signing in with an e-mailed link](guide/magic-link.md) | You are signing users in with a link sent by e-mail — a magic link: the page that confirms it from a `POST` so mail scanners spend nothing, the lifetime, the errors, and what ends a link |
|
|
18
18
|
| [Signing in with an e-mailed code](guide/sign-in-code.md) | You are signing users in with a six-digit code sent by e-mail — with no password, or beside one: requesting it without telling who exists, keeping the challenge, the attempts and the errors |
|
|
19
19
|
| [The second factor](guide/second-factor.md) | You are turning on TOTP codes: making and rotating the sealing keys, the QR code, `signIn`'s `status`, confirming a challenge, recovery codes for a lost phone, disabling — and sealing your own secrets at rest with `sealerFor` |
|
|
20
|
+
| [Signed tokens](guide/signed-tokens.md) | You hand out a link that must expire and cannot be forged, and want to check it without a store: `signToken`, `verifyToken`, purposes, key rotation, what the token does not hide |
|
|
20
21
|
| [Passkeys](guide/passkeys.md) | A user registers a passkey and answers with it, as a second factor beside TOTP or, with `firstFactor`, to sign in with no password (`signInOptions`, `signIn`): wiring `passkeys` (`rpId`, `origins`, the verifier), the two-step registration, `list`, `rename` and `remove`, freshness, `methods` and `passkeyOptions` on the sign-in challenge, `confirmPasskey`, a step-up `via: 'passkey'`, the counter rule, the errors, and a test with a fake verifier |
|
|
21
22
|
| [Step-up](guide/step-up.md) | A sensitive action — changing the e-mail, disabling the second factor, deleting the account — should ask a signed-in user to prove again who they are: `assertFresh`, `stepUp.request` and `confirm`, by e-mailed code, by their app or by a passkey |
|
|
22
23
|
| [Invitations](guide/invitations.md) | Inviting somebody into an organization: wiring `invitations`, `issue`, `resend`, `revoke`, `list`, `preview` and `accept`, the e-mail link, what `accept` does for a new, an unproved and a proved address, and the traps |
|
package/docs/guide/api-keys.md
CHANGED
|
@@ -232,6 +232,83 @@ const unbound = await auth.apiKeys.list(user, { bound: null }); // the user's un
|
|
|
232
232
|
A store with `listUserBoundApiKeys` answers in one read; without it the core
|
|
233
233
|
reads the user's keys 100 at a time and keeps those that match.
|
|
234
234
|
|
|
235
|
+
## Service keys
|
|
236
|
+
|
|
237
|
+
A **service key** belongs to an object (an account, a tenant), not to the user
|
|
238
|
+
who made it: it has no user, it survives its creator, and it may never expire.
|
|
239
|
+
It is for a server calling your API on the object's behalf.
|
|
240
|
+
|
|
241
|
+
```ts
|
|
242
|
+
const auth = janus({
|
|
243
|
+
// …
|
|
244
|
+
apiKeys: {
|
|
245
|
+
store: createMongoApiKeys(db),
|
|
246
|
+
prefix: 'sl_',
|
|
247
|
+
lifetimes: ['30d', '90d', 'never'], // 'never' is the opt-in
|
|
248
|
+
service: {
|
|
249
|
+
// who may make one: asked after the step-up, before anything is written
|
|
250
|
+
authorize: ({ user, owner, scopes }) => isManagerOf(user, owner),
|
|
251
|
+
maxActive: 5, // standing service keys one owner may hold; 10 when absent
|
|
252
|
+
},
|
|
253
|
+
},
|
|
254
|
+
});
|
|
255
|
+
|
|
256
|
+
const { apiKey, token } = await auth.apiKeys.createService(current, {
|
|
257
|
+
name: 'Mailer',
|
|
258
|
+
owner: { type: 'account', id: account.id },
|
|
259
|
+
scopes: ['mail:send'],
|
|
260
|
+
lifetime: 'never', // or one of the configured lifetimes, e.g. '90d'
|
|
261
|
+
details: { domains: ['example.org'] }, // optional, yours, never read by janus
|
|
262
|
+
});
|
|
263
|
+
|
|
264
|
+
const principal = await auth.authenticate(request, { apiKey: true, service: true });
|
|
265
|
+
if (principal?.via === 'serviceKey') {
|
|
266
|
+
principal.user; // null: no one
|
|
267
|
+
principal.bound; // { type: 'account', id: '…' }: the owner
|
|
268
|
+
principal.scopes; // ['mail:send']
|
|
269
|
+
principal.apiKey.lastUsedAt; // when it last called
|
|
270
|
+
principal.apiKey.details; // { domains: ['example.org'] }
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
await auth.apiKeys.listOwned({ type: 'account', id }); // the owner's service keys, oldest first
|
|
274
|
+
await auth.apiKeys.revokeOwned({ type: 'account', id }, apiKey.id);
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
- **Opt-in at both ends.** `createService`, `listOwned` and `revokeOwned` exist
|
|
278
|
+
only when `apiKeys.service` is configured. A service key authenticates only
|
|
279
|
+
to `authenticate(request, { apiKey: true, service: true })`; without
|
|
280
|
+
`service: true` it is anonymous, so a consumer written for user keys never
|
|
281
|
+
meets a principal with no user. `'never'` in `lifetimes` is taken by
|
|
282
|
+
`createService` only: a user's `create` refuses it (`API_KEY_INVALID`,
|
|
283
|
+
`field: 'lifetime'`), as does `createService` when `'never'` is not listed.
|
|
284
|
+
- **Who may make one.** The same fresh proof as `create` (`STEP_UP_REQUIRED`,
|
|
285
|
+
never from a key principal), for an active user with a verified e-mail, then
|
|
286
|
+
`service.authorize({ user: { id, type }, owner, scopes })`. Answering `false`
|
|
287
|
+
is `API_KEY_REFUSED` (403) and nothing is written. Janus decides nothing
|
|
288
|
+
about owners: your hook checks the user may act for `owner`.
|
|
289
|
+
- **It survives its creator.** The key stores `userId: null`: deleting,
|
|
290
|
+
deactivating or removing the creator from the owner changes nothing, and
|
|
291
|
+
`delete(user)`, `revokeAll(user)` and `list(user)` never see it. Revoke it
|
|
292
|
+
with `revokeOwned` (idempotent; `NOT_FOUND` for a key that is another
|
|
293
|
+
owner's, a user's, or unknown).
|
|
294
|
+
- **Scopes are required** (1 to 32 tokens, as for `create`), and janus never
|
|
295
|
+
enforces them: your route checks `principal.scopes` and that
|
|
296
|
+
`principal.bound` is the object the request touches.
|
|
297
|
+
- `maxActive` counts the owner's standing service keys; past it,
|
|
298
|
+
`API_KEY_LIMIT` (409). User keys bound to the same owner are not counted
|
|
299
|
+
and not listed by `listOwned` (`listBound` lists both).
|
|
300
|
+
- No `user.apiKeyCreated` event, since no user holds the key; a service key,
|
|
301
|
+
never-expiring or dated, is never in `expiring` and gets no expiry notice. `details` is a plain
|
|
302
|
+
JSON object of at most 4000 characters once serialised.
|
|
303
|
+
- **Stores.** Needs the `bound` capability, and a store that keeps `userId` and
|
|
304
|
+
`expiresAt` as `null` and `details`. `createMemoryApiKeys()`,
|
|
305
|
+
`createMongoApiKeys(db)` and `createDrizzleApiKeys()` do; Drizzle needs
|
|
306
|
+
`user_id` and `expires_at` nullable and a `details` `jsonb` column on
|
|
307
|
+
`api_keys` (see its README). A custom store passes the `service` cases of the
|
|
308
|
+
exported conformance specs.
|
|
309
|
+
|
|
310
|
+
- **Pages can come back short.** `listBound`, `listOwned` and `expiring` may answer fewer items than `limit`, even none, with a `nextCursor`: follow `nextCursor` until it is `null`.
|
|
311
|
+
|
|
235
312
|
## Expiry notices
|
|
236
313
|
|
|
237
314
|
To warn a user before a key lapses, sweep the keys that expire soon and claim
|
|
@@ -309,7 +386,7 @@ There is no e-mail notice when a key is created: listen to `user.apiKeyCreated`
|
|
|
309
386
|
`expiryNotifiedAt`, each `null` when unset), `CreatedApiKey`
|
|
310
387
|
(`{ apiKey, token }`), `CreateApiKeyInput`, `ApiKeyBound` (`{ type, id }`),
|
|
311
388
|
`ApiKeyPage` (`{ limit?, after? }`; `expiring` takes `{ within } & ApiKeyPage`),
|
|
312
|
-
`ApiKeyListOptions` (`ApiKeyPage & { bound? }`, what `list` takes), `ApiKeysApi`, `ApiKeysConfig`, and for
|
|
389
|
+
`ApiKeyListOptions` (`ApiKeyPage & { bound? }`, what `list` takes), `CreateServiceKeyInput`, `ServiceKeysApi`, `ServiceKeyAuthenticated` (what `authenticate` answers to `{ service: true }` for a service key: `via: 'serviceKey'`, `user: null`, `scopes`, `bound`), `ApiKeysApi`, `ApiKeysConfig`, and for
|
|
313
390
|
the principal of a request, `Principal<U> = Authenticated<U> | KeyAuthenticated<U>`,
|
|
314
391
|
told apart by `via` (`'session'` or `'apiKey'`; a key's has `session: null`,
|
|
315
392
|
and `scopes` and `bound`). `apiKeys`
|
|
@@ -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 |
|
|
@@ -72,6 +72,7 @@ that wired the library, so no handler needs to tell it apart.
|
|
|
72
72
|
| `CURSOR_FILTER_MISMATCH` | `CursorFilterMismatchError` | 400 | `invitations.list({ after })` with a `nextCursor` issued for another scope, status, role, ref, lapsed or order. Never a page of the other list | |
|
|
73
73
|
| `UNSUPPORTED` | `UnsupportedError` | 501 | The wired store lacks an optional capability — `collectExpired` with neither `deleteExpiredSessions` nor `deleteExpiredTokens`, `sessions.list` / `sessions.revoke` without `listUserSessions`, or `social.countLinks` without `countSocialLinks` | `slot`, `operation` |
|
|
74
74
|
| `PERMISSION_DEPTH` | `PermissionDepthError` | 500 | A check or list walked past `maxDepth`. **Not a denial** | `permission`, `maxDepth` |
|
|
75
|
+
| `API_KEY_REFUSED` | `ApiKeyRefusedError` | 403 | `apiKeys.createService` when `apiKeys.service.authorize` answered `false` for this user, owner and scopes; nothing is written. See [Service keys](api-keys.md#service-keys) | `userId` |
|
|
75
76
|
| `API_KEY_LIMIT` | `ApiKeyLimitError` | 409 | `apiKeys.create` for a user who already holds `maxActive` standing keys (refused before anything is written); the key a race inserted is revoked again. Revoke one, then create — see [API keys](api-keys.md#creating-a-key) | `maxActive`, `userId` |
|
|
76
77
|
| `API_KEY_INVALID` | `ApiKeyInvalidError` | 400 | `apiKeys.create` with a name empty, over 100 characters once trimmed, or holding a NUL or a lone surrogate, or a lifetime not among `apiKeys.lifetimes`, or `scopes` that are not 1 to 32 scope tokens, or a `bound` that is not `{ type, id }`. Nothing was written | `field`: `'name'`, `'lifetime'`, `'scopes'` or `'bound'` |
|
|
77
78
|
| `INVITATION_INVALID` | `InvitationInvalidError` | 400 | `invitations.preview` or `accept` given a code that names no pending, unlapsed invitation (unknown, malformed, accepted, revoked or lapsed: **one code for all**, told apart by `reason`: `'unknown'`, `'expired'`, `'accepted'` or `'revoked'`, the code being its holder's own secret; a deactivated user, a taken login and a lost race stay `'unknown'`; of two concurrent accepts the loser gets it too, and `accept` for a deactivated user answers it as well, so a code cannot tell whether an account exists; so do a taken login on the new user and a version that moved); `invitations.issue` given an email, name, role, locale or scope it cannot keep. Nothing was written — see [Invitations](invitations.md#errors) | `field`: `'code'` for a code, the input's name for `issue`; `reason` (`InvitationRefusal`) for a code |
|
|
@@ -83,14 +84,14 @@ that wired the library, so no handler needs to tell it apart.
|
|
|
83
84
|
| `PASSKEY_TAKEN` | `PasskeyError` | 409 | `passkeys.register`: the credential is already registered, by this user or another. Nothing was stored | `userId`, `userType` |
|
|
84
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` |
|
|
85
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) | |
|
|
86
|
-
| `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 | |
|
|
87
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` |
|
|
88
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 | |
|
|
89
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` |
|
|
90
91
|
| `SOCIAL_PROVIDER_UNKNOWN` | `SocialError` | 404 | `social.start` or `social.link` for a provider the user type does not configure | `provider` |
|
|
91
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) |
|
|
92
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` |
|
|
93
|
-
| `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` |
|
|
94
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` |
|
|
95
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` |
|
|
96
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`
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Signed tokens
|
|
2
|
+
|
|
3
|
+
A signed, expiring token carries a small payload and an expiry under an HMAC.
|
|
4
|
+
Use it for a link the application hands out and checks later without a store:
|
|
5
|
+
a download URL, an unsubscribe link, a confirmation step. Nothing is stored,
|
|
6
|
+
and **nothing is hidden**: the payload is readable by whoever holds the token;
|
|
7
|
+
it only cannot be changed or extended. For a secret, use `sealerFor`; for a
|
|
8
|
+
single-use proof, use a stored one-time token (magic links and sign-in codes
|
|
9
|
+
store a hashed secret, so they do not use this helper).
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { parseSealingKeys, signToken, verifyToken } from '@softistx/janus';
|
|
13
|
+
|
|
14
|
+
const keys = parseSealingKeys(process.env.LINK_KEYS ?? '');
|
|
15
|
+
|
|
16
|
+
const token = signToken(keys, 'download', { file: 'invoice-42.pdf' }, { expiresIn: '15m' });
|
|
17
|
+
// v1.<key id>.<base64url payload>.<base64url HMAC-SHA-256>
|
|
18
|
+
|
|
19
|
+
const verified = verifyToken<{ file: string }>(keys, 'download', token);
|
|
20
|
+
if (verified === null) {
|
|
21
|
+
// expired, changed, another purpose, or a key no longer held: answer 404
|
|
22
|
+
}
|
|
23
|
+
verified?.payload.file; // 'invoice-42.pdf'
|
|
24
|
+
verified?.expiresAt; // Date
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- `keys` is the `{ id, key }` list of `sealerFor` (32 random bytes in base64,
|
|
28
|
+
`openssl rand -base64 32`). The first key signs, every key verifies.
|
|
29
|
+
- `purpose` names what the token is for. Each key is derived for it
|
|
30
|
+
(HKDF-SHA-256), so a `download` token never verifies as an `unsubscribe`
|
|
31
|
+
one, nor under the second factor's keys. Keep a purpose stable.
|
|
32
|
+
- `expiresIn` is a duration (`'15m'`, `'7d'`, or milliseconds). A token stops
|
|
33
|
+
verifying at its expiry instant. `clock` (`{ now() }`, e.g. `fixedClock`)
|
|
34
|
+
replaces the system clock in specs.
|
|
35
|
+
- The payload is any JSON value; it comes back as a JSON round trip.
|
|
36
|
+
- `verifyToken` answers `null` for any bad token and never throws for one;
|
|
37
|
+
the signature is compared in constant time.
|
|
38
|
+
- **Rotation**: put the new key first and keep the old ones until their
|
|
39
|
+
tokens have expired. `needsResign` is `true` for a token signed under
|
|
40
|
+
another key than the first.
|
|
41
|
+
- Keep tokens short: `verifyToken` answers `null` above 8 KiB.
|
|
42
|
+
|
|
43
|
+
`TypeError`s (wiring, never a request): an empty or badly formed key list, an
|
|
44
|
+
empty or over 256 characters purpose, a duration that is not above zero, a
|
|
45
|
+
payload JSON cannot carry (`undefined`, a function), and a payload that makes
|
|
46
|
+
the token longer than 8 KiB (`signToken: the token is over 8 KiB; keep the payload small`).
|
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,9 @@ 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)
|
|
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)
|
|
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)
|
|
87
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)
|
|
88
91
|
- **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.
|
|
89
92
|
- **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)
|
package/docs/troubleshooting.md
CHANGED
|
@@ -65,6 +65,7 @@ How the messages are shaped:
|
|
|
65
65
|
**API keys**
|
|
66
66
|
- [`API_KEY_LIMIT` — `apiKeys.create: the user already holds <n> API keys — revoke one first`](#api_key_limit--apikeyscreate-the-user-already-holds-n-api-keys--revoke-one-first)
|
|
67
67
|
- [`API_KEY_INVALID` — `apiKeys.create: name must be 1 to 100 characters once trimmed` / `lifetime is not one of the configured lifetimes`](#api_key_invalid--apikeyscreate-name-must-be-1-to-100-characters-once-trimmed--lifetime-is-not-one-of-the-configured-lifetimes)
|
|
68
|
+
- [`API_KEY_REFUSED` — `apiKeys.createService: the application refused this service key`](#api_key_refused--apikeyscreateservice-the-application-refused-this-service-key)
|
|
68
69
|
- [`STEP_UP_REQUIRED` with `reason: 'apiKey'`](#step_up_required-with-reason-apikey)
|
|
69
70
|
- [`TS2769: No overload matches this call` on `authenticate(request, { apiKey })`](#ts2769-no-overload-matches-this-call-on-authenticaterequest--apikey-)
|
|
70
71
|
- [A valid API key answers `null` (anonymous)](#a-valid-api-key-answers-null-anonymous)
|
|
@@ -204,6 +205,7 @@ How the messages are shaped:
|
|
|
204
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)
|
|
205
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)
|
|
206
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-)
|
|
207
209
|
- [`social.resolveProvider("<name>") must answer a provider …`](#socialresolveprovidername-must-answer-a-provider-)
|
|
208
210
|
- [`federatedAmr: …`](#federatedamr-)
|
|
209
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)
|
|
@@ -588,6 +590,9 @@ Also:
|
|
|
588
590
|
- `sealerFor: purpose must be a well-formed string of 1 to 256 characters`: an empty, longer or badly formed (NUL, lone surrogate) purpose
|
|
589
591
|
- `sealerFor: seal(id, plaintext) takes two strings`: `seal` was called with a non-string
|
|
590
592
|
- `sealerFor: seal(id, plaintext) takes a well-formed id and a non-empty, well-formed plaintext`
|
|
593
|
+
- `signToken: …` / `verifyToken: …`: the same key-list messages, prefixed with the function's name; `signToken: purpose must be a well-formed string of 1 to 256 characters`; `signToken: expiresIn: …` for a duration that is not above zero or not written like `"15m"`
|
|
594
|
+
- `signToken: the payload must be a JSON value`: the payload is `undefined`, a function or a symbol
|
|
595
|
+
- `signToken: the token is over 8 KiB; keep the payload small`: put an id in the payload and look the rest up
|
|
591
596
|
- Warning `JANUS_SEALER_UNKNOWN_KEY` (not an error): `unseal` was given a value sealed with a key id the sealer no longer holds, and answered `null`. Put the key back until every value is sealed again (`needsReseal`). For TOTP secrets, `secondFactor.reseal` seals them again in batches (see Rotating the keys in the second-factor guide).
|
|
592
597
|
|
|
593
598
|
**When:** `janus({ ..., secondFactor })`, or `sealerFor(keys, purpose)`.
|
|
@@ -803,6 +808,14 @@ A runtime without `process.emitWarning` stays silent. Silence it with
|
|
|
803
808
|
**Why:** the user's standing keys were counted before anything was written and already reached the limit. (Two creations racing at the limit are both refused too: each key is inserted, the keys are counted again, and the new one is revoked.)
|
|
804
809
|
**Fix:** answer 409 with `maxActive`; the user revokes a key (`apiKeys.revoke(id, { owner })`) or waits for one to lapse, or raise `apiKeys.maxActive` (at most 100).
|
|
805
810
|
|
|
811
|
+
### `API_KEY_REFUSED` — `apiKeys.createService: the application refused this service key`
|
|
812
|
+
|
|
813
|
+
`ApiKeyRefusedError`, 403, carrying `userId`.
|
|
814
|
+
|
|
815
|
+
**When:** `apiKeys.createService` when `apiKeys.service.authorize` answered `false`.
|
|
816
|
+
**Why:** the application's hook decided that this user may not make a service key for this owner with these scopes. The check runs after the step-up and before anything is written.
|
|
817
|
+
**Fix:** answer 403 and show nothing more; if the user should have been allowed, fix the hook (it gets `{ user: { id, type }, owner, scopes }`). A missing `lifetime: 'never'` entry in `apiKeys.lifetimes`, a missing `apiKeys.service` block, or a store without the `bound` capability are not this error: they are `API_KEY_INVALID` (`field: 'lifetime'`) and `TypeError`s at the call. A service key authenticates only to `authenticate(request, { apiKey: true, service: true })`; without `service: true` it answers `null` (anonymous). See [Service keys](guide/api-keys.md#service-keys).
|
|
818
|
+
|
|
806
819
|
### `API_KEY_INVALID` — `apiKeys.create: name must be 1 to 100 characters once trimmed` / `lifetime is not one of the configured lifetimes`
|
|
807
820
|
|
|
808
821
|
`ApiKeyInvalidError`, 400, carrying `field`: `'name'` or `'lifetime'` (and `'scopes'` or `'bound'`, [below](#api_key_invalid-with-field-scopes-or-bound)).
|
|
@@ -2642,6 +2655,8 @@ null) …` — or give every sign-in a `device`.
|
|
|
2642
2655
|
|
|
2643
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.
|
|
2644
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
|
+
|
|
2645
2660
|
**Fix:** send the cookie with the callback request and give `complete` its value unchanged:
|
|
2646
2661
|
|
|
2647
2662
|
```ts
|
|
@@ -2747,6 +2762,7 @@ social: { providers: { google }, signUp: (profile) => ({ email: profile.email ??
|
|
|
2747
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.
|
|
2748
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.
|
|
2749
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).
|
|
2750
2766
|
|
|
2751
2767
|
### `SOCIAL_ACCOUNT_TAKEN` — `social.complete: this social account is already linked to another user`
|
|
2752
2768
|
|
|
@@ -2809,6 +2825,23 @@ An `UnsupportedError` (`UNSUPPORTED`, 501) when `auth.social.countLinks(...)` is
|
|
|
2809
2825
|
const socialLinks = { ...mine, countSocialLinks: (provider) => countRows({ provider }) };
|
|
2810
2826
|
```
|
|
2811
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
|
+
|
|
2812
2845
|
### `janus: social.signUp needs a type whose login is its e-mail …`
|
|
2813
2846
|
|
|
2814
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
|
File without changes
|
|
File without changes
|