@softistx/janus 0.76.0 → 0.78.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +11 -6
  2. package/dist/auth/api-keys/authenticate-key.d.ts +3 -2
  3. package/dist/auth/api-keys/authenticate-key.d.ts.map +1 -1
  4. package/dist/auth/api-keys/count.d.ts.map +1 -1
  5. package/dist/auth/api-keys/create/after-insert.d.ts +11 -0
  6. package/dist/auth/api-keys/create/after-insert.d.ts.map +1 -0
  7. package/dist/auth/api-keys/create/checks.d.ts +17 -0
  8. package/dist/auth/api-keys/create/checks.d.ts.map +1 -1
  9. package/dist/auth/api-keys/create/index.d.ts.map +1 -1
  10. package/dist/auth/api-keys/create/service-checks.d.ts +25 -0
  11. package/dist/auth/api-keys/create/service-checks.d.ts.map +1 -0
  12. package/dist/auth/api-keys/create/service.d.ts +12 -0
  13. package/dist/auth/api-keys/create/service.d.ts.map +1 -0
  14. package/dist/auth/api-keys/expiry.d.ts.map +1 -1
  15. package/dist/auth/api-keys/flows.d.ts +6 -2
  16. package/dist/auth/api-keys/flows.d.ts.map +1 -1
  17. package/dist/auth/api-keys/owned.d.ts +12 -0
  18. package/dist/auth/api-keys/owned.d.ts.map +1 -0
  19. package/dist/auth/api-keys/read.d.ts.map +1 -1
  20. package/dist/auth/api-keys/service-flows.d.ts +13 -0
  21. package/dist/auth/api-keys/service-flows.d.ts.map +1 -0
  22. package/dist/auth/api-keys/to-api-key.d.ts.map +1 -1
  23. package/dist/auth/config/api-keys-config.d.ts +29 -2
  24. package/dist/auth/config/api-keys-config.d.ts.map +1 -1
  25. package/dist/auth/config/index.d.ts +1 -1
  26. package/dist/auth/config/index.d.ts.map +1 -1
  27. package/dist/auth/config/resolve-api-keys.d.ts.map +1 -1
  28. package/dist/auth/config/resolved-config.d.ts +8 -0
  29. package/dist/auth/config/resolved-config.d.ts.map +1 -1
  30. package/dist/auth/index.d.ts +3 -2
  31. package/dist/auth/index.d.ts.map +1 -1
  32. package/dist/auth/port/memory/api-keys/capabilities.d.ts.map +1 -1
  33. package/dist/auth/port/memory/api-keys/index.d.ts.map +1 -1
  34. package/dist/auth/port/types/api-keys.d.ts +25 -5
  35. package/dist/auth/port/types/api-keys.d.ts.map +1 -1
  36. package/dist/auth/sessions/amr.d.ts +2 -2
  37. package/dist/auth/sessions/authenticate.d.ts +3 -2
  38. package/dist/auth/sessions/authenticate.d.ts.map +1 -1
  39. package/dist/auth/sessions/fresh.d.ts +2 -2
  40. package/dist/auth/sessions/fresh.d.ts.map +1 -1
  41. package/dist/auth/sessions/shared-api.d.ts +3 -2
  42. package/dist/auth/sessions/shared-api.d.ts.map +1 -1
  43. package/dist/auth/shared-api.d.ts +11 -3
  44. package/dist/auth/shared-api.d.ts.map +1 -1
  45. package/dist/auth/signed-token.d.ts +41 -0
  46. package/dist/auth/signed-token.d.ts.map +1 -0
  47. package/dist/auth/types/api-keys-of.d.ts +6 -1
  48. package/dist/auth/types/api-keys-of.d.ts.map +1 -1
  49. package/dist/auth/types/api-keys.d.ts +18 -6
  50. package/dist/auth/types/api-keys.d.ts.map +1 -1
  51. package/dist/auth/types/checks.d.ts +17 -1
  52. package/dist/auth/types/checks.d.ts.map +1 -1
  53. package/dist/auth/types/index.d.ts +3 -2
  54. package/dist/auth/types/index.d.ts.map +1 -1
  55. package/dist/auth/types/service-keys.d.ts +58 -0
  56. package/dist/auth/types/service-keys.d.ts.map +1 -0
  57. package/dist/auth/types/session.d.ts +21 -2
  58. package/dist/auth/types/session.d.ts.map +1 -1
  59. package/dist/auth/types/shared-api.d.ts +15 -1
  60. package/dist/auth/types/shared-api.d.ts.map +1 -1
  61. package/dist/auth/types/sign-in.d.ts +1 -1
  62. package/dist/auth/types/sign-in.d.ts.map +1 -1
  63. package/dist/chunks/{index-7h34nqrm.js → index-5hcajrrx.js} +5 -5
  64. package/dist/chunks/{index-7h34nqrm.js.map → index-5hcajrrx.js.map} +4 -4
  65. package/dist/chunks/{index-n8jxmxeg.js → index-gzc472ar.js} +2 -2
  66. package/dist/chunks/{index-ftz0ne6j.js → index-r8fcessc.js} +2 -2
  67. package/dist/chunks/{index-2ttdcz7n.js → index-vx9a5cpy.js} +9 -3
  68. package/dist/chunks/{index-2ttdcz7n.js.map → index-vx9a5cpy.js.map} +4 -4
  69. package/dist/conformance/api-keys/cases/index.d.ts.map +1 -1
  70. package/dist/conformance/api-keys/cases/outage.d.ts.map +1 -1
  71. package/dist/conformance/api-keys/cases/service.d.ts +3 -0
  72. package/dist/conformance/api-keys/cases/service.d.ts.map +1 -0
  73. package/dist/conformance/index.js +407 -302
  74. package/dist/conformance/index.js.map +6 -5
  75. package/dist/errors/janus-error/codes.invitations.d.ts +6 -0
  76. package/dist/errors/janus-error/codes.invitations.d.ts.map +1 -1
  77. package/dist/errors/janus-error/index.d.ts +1 -1
  78. package/dist/errors/janus-error/index.d.ts.map +1 -1
  79. package/dist/errors/janus-error/options.d.ts +1 -1
  80. package/dist/errors/janus-error/options.d.ts.map +1 -1
  81. package/dist/errors/janus-error/refusals.d.ts +5 -0
  82. package/dist/errors/janus-error/refusals.d.ts.map +1 -1
  83. package/dist/errors/janus-error/status.d.ts.map +1 -1
  84. package/dist/index.d.ts +1 -1
  85. package/dist/index.d.ts.map +1 -1
  86. package/dist/index.js +428 -100
  87. package/dist/index.js.map +22 -16
  88. package/dist/permissions/index.js +3 -3
  89. package/docs/README.md +1 -0
  90. package/docs/guide/api-keys.md +78 -1
  91. package/docs/guide/errors.md +1 -0
  92. package/docs/guide/second-factor.md +1 -1
  93. package/docs/guide/sessions.md +3 -1
  94. package/docs/guide/signed-tokens.md +46 -0
  95. package/docs/roadmap.md +3 -1
  96. package/docs/troubleshooting.md +17 -5
  97. package/package.json +1 -1
  98. /package/dist/chunks/{index-n8jxmxeg.js.map → index-gzc472ar.js.map} +0 -0
  99. /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-n8jxmxeg.js";
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-2ttdcz7n.js";
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-ftz0ne6j.js";
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 |
@@ -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`
@@ -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 |
@@ -29,7 +29,7 @@ if (result.status === 'secondFactor') {
29
29
  // no session yet: ask for a code, then
30
30
  const signedIn = await auth.secondFactor.confirm(result.challenge, '654321');
31
31
  // or, with the phone gone: await auth.secondFactor.recover(result.challenge, '7k2mq-x9d4c')
32
- // signedIn.method is 'totp', 'recovery' or 'passkey': alert on 'recovery'; amr is the same for both codes
32
+ // signedIn.method is 'totp', 'recovery' or 'passkey': alert on 'recovery'; the session's amr holds 'rec' instead of 'otp'
33
33
  }
34
34
  ```
35
35
 
@@ -477,11 +477,13 @@ the field existed reads `amr: []`.
477
477
  | E-mailed code, magic link | `otp` |
478
478
  | Passkey sign-in (user verified) | `hwk`, `user` |
479
479
  | App code (TOTP) as second factor or step-up | `otp`, `mfa` |
480
- | Recovery code as second factor | `otp`, `mfa` |
480
+ | Recovery code as second factor | `rec`, `mfa` (not grantable through `federatedAmr`) |
481
481
  | Passkey as second factor or step-up | `hwk`, `user`, `mfa` |
482
482
  | Social sign-in | `fed`, plus what the provider's `federatedAmr` grants ([social](social.md)) |
483
483
  | `signInProven` | nothing: the proof is yours |
484
484
 
485
+ Sessions stored before this change keep `otp` for a recovery code; test for `rec` to spot one.
486
+
485
487
  A second factor adds to its first factor's methods (`['pwd', 'otp', 'mfa']`),
486
488
  and a step-up adds to the session's (an e-mailed step-up after a password:
487
489
  `['pwd', 'otp']`). Each value once, in the order proved. The table is
@@ -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/roadmap.md CHANGED
@@ -84,6 +84,8 @@ Nothing yet.
84
84
  The last ten, newest first, each with the version it came in. Everything
85
85
  before is in the [CHANGELOG](../CHANGELOG.md).
86
86
 
87
+ - **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
+ - **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
89
  - **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
90
  - **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
91
  - **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)
@@ -93,7 +95,7 @@ before is in the [CHANGELOG](../CHANGELOG.md).
93
95
  - **The methods a session proved** — 0.71.0. `session.amr`, the RFC 8176 methods of the sign-in extended by each step-up, with `authenticatedAt` as the time of the last proof, on `authenticate` and every `SignedIn`; `AMR` and `isMultiFactor` exported. The Mongo, Drizzle (a nullable `amr` column) and Redis stores keep it. [#889](https://github.com/softistx/nxgt-janus/issues/889)
94
96
  - **A second factor for a passwordless type** — `secondFactor` on a type whose identifier is an e-mail, with the e-mail as the account name; the sign-in code, magic link, `signInProven` and social completion answer its challenge, and a passkey first-factor sign-in asks for none. [#891](https://github.com/softistx/nxgt-janus/issues/891)
95
97
  - **Searching users by display name** — 0.66.0. `list({ namePrefix })` and `count({ namePrefix })` keep the users whose name starts with the prefix, case-insensitively and as plain text, beside `emailPrefix`, from a `(type, nameKey)` index in the Mongo and Drizzle stores; `displayName` names the schema field (`name` by default). A store of your own gains `UserFilter.namePrefix` and `UserRecord.nameKey`. [#842](https://github.com/softistx/nxgt-janus/issues/842)
96
- - **Which second factor opened the session** — `secondFactor.confirm`, `recover` and `confirmPasskey` answer `method: 'totp' | 'recovery' | 'passkey'`, and `confirmSecondFactor` / `recoverSecondFactor` in `@softistx/janus-graphql` answer `method`, so an application can alert on a recovery-code sign-in or record its own `amr`. The session's `amr` is unchanged and the method is not stored on it. [#950](https://github.com/softistx/nxgt-janus/issues/950)
98
+ - **Which second factor opened the session** — `secondFactor.confirm`, `recover` and `confirmPasskey` answer `method: 'totp' | 'recovery' | 'passkey'`, and `confirmSecondFactor` / `recoverSecondFactor` in `@softistx/janus-graphql` answer `method`, so an application can alert on a recovery-code sign-in or record its own `amr`. The session's `amr` holds `rec` (not `otp`) for a recovery code, with `mfa`. [#950](https://github.com/softistx/nxgt-janus/issues/950), [#960](https://github.com/softistx/nxgt-janus/issues/960)
97
99
  - **Spending a recovery code outside a sign-in** — 0.64.0. `secondFactor.spendRecoveryCode(user, code)` spends one recovery code from an existing session (turning the second factor off for a lost phone) and answers `{ user, recoveryCodesLeft }`, with no session, event or notice; its attempts share the five-per-15-minutes count of the step-up. [#770](https://github.com/softistx/nxgt-janus/issues/770)
98
100
  - **`apiKeys.get` and a bound filter on `apiKeys.list`** — 0.63.0. `get(id, { owner? })` reads one key by id (`null` when unknown, malformed or, with `owner`, another user's), and `list(user, { bound })` pages one user's keys of an object, or the unbound ones with `null`. A new optional `ApiKeyStore` capability, `userBound` (`listUserBoundApiKeys`), answers it in one read; the memory, Mongo and Drizzle stores have it, and a store without it is read 100 keys at a time. [#736](https://github.com/softistx/nxgt-janus/issues/736)
99
101
  - **A background runner** — 0.62.0. `background(log?)` returns `run(name, task)` for fire-and-forget work that must not delay a response (an anti-enumeration mail), which logs its failures and never throws, and `settled()` for specs. [Guide](guide/vocabulary.md#background-work)
@@ -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)
@@ -302,19 +303,19 @@ them needs no token and no scope mapping. A 401 or 404 means something still
302
303
  sends the request elsewhere. The causes, in the order to check them:
303
304
 
304
305
  - **A stale `@softistx` scope.** A `bunfig.toml` `[install.scopes]` entry or an
305
- `.npmrc` line mapping `@softistx` to another registry (with a token that is
306
- unset or expired) sends every `@softistx` request there. Remove the entry
307
- and the packages resolve from registry.npmjs.org:
306
+ `.npmrc` line mapping `@softistx` to another registry (a retired private
307
+ one, with a token that is unset or expired) sends every `@softistx` request
308
+ there. Remove the entry and the packages resolve from registry.npmjs.org:
308
309
 
309
310
  ```toml
310
311
  # delete this from bunfig.toml
311
312
  [install.scopes]
312
- "@softistx" = { url = "https://npm.softistx.com/", token = "$NPM_REGISTRY_TOKEN" }
313
+ "@softistx" = { url = "https://registry.example.test/", token = "$REGISTRY_TOKEN" }
313
314
  ```
314
315
 
315
316
  - **The lockfile still names another registry.** A `bun.lock` entry whose
316
317
  tarball URL is `https://npm.pkg.github.com/download/…` or
317
- `https://npm.softistx.com/…` keeps installing from there. Check
318
+ a private registry's URL keeps installing from there. Check
318
319
  `grep -c "npm.pkg.github.com\|npm.softistx.com" bun.lock`; when it is not 0,
319
320
  delete those entries (or the lockfile) and run `bun install` again so they
320
321
  re-resolve from registry.npmjs.org.
@@ -588,6 +589,9 @@ Also:
588
589
  - `sealerFor: purpose must be a well-formed string of 1 to 256 characters`: an empty, longer or badly formed (NUL, lone surrogate) purpose
589
590
  - `sealerFor: seal(id, plaintext) takes two strings`: `seal` was called with a non-string
590
591
  - `sealerFor: seal(id, plaintext) takes a well-formed id and a non-empty, well-formed plaintext`
592
+ - `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"`
593
+ - `signToken: the payload must be a JSON value`: the payload is `undefined`, a function or a symbol
594
+ - `signToken: the token is over 8 KiB; keep the payload small`: put an id in the payload and look the rest up
591
595
  - 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
596
 
593
597
  **When:** `janus({ ..., secondFactor })`, or `sealerFor(keys, purpose)`.
@@ -803,6 +807,14 @@ A runtime without `process.emitWarning` stays silent. Silence it with
803
807
  **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
808
  **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
809
 
810
+ ### `API_KEY_REFUSED` — `apiKeys.createService: the application refused this service key`
811
+
812
+ `ApiKeyRefusedError`, 403, carrying `userId`.
813
+
814
+ **When:** `apiKeys.createService` when `apiKeys.service.authorize` answered `false`.
815
+ **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.
816
+ **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).
817
+
806
818
  ### `API_KEY_INVALID` — `apiKeys.create: name must be 1 to 100 characters once trimmed` / `lifetime is not one of the configured lifetimes`
807
819
 
808
820
  `ApiKeyInvalidError`, 400, carrying `field`: `'name'` or `'lifetime'` (and `'scopes'` or `'bound'`, [below](#api_key_invalid-with-field-scopes-or-bound)).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softistx/janus",
3
- "version": "0.76.0",
3
+ "version": "0.78.0",
4
4
  "description": "Embeddable, type-safe identities and permissions: bring your own database",
5
5
  "license": "MIT",
6
6
  "type": "module",