@softistx/janus 0.77.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.
- package/README.md +8 -3
- 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 +1 -1
- 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/resolved-config.d.ts +8 -0
- package/dist/auth/config/resolved-config.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/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/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 +427 -99
- package/dist/index.js.map +21 -15
- package/dist/permissions/index.js +3 -3
- package/docs/README.md +1 -0
- package/docs/guide/api-keys.md +78 -1
- package/docs/guide/errors.md +1 -0
- package/docs/guide/signed-tokens.md +46 -0
- package/docs/roadmap.md +2 -0
- package/docs/troubleshooting.md +12 -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`
|
package/docs/guide/errors.md
CHANGED
|
@@ -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 |
|
|
@@ -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)
|
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)
|
|
@@ -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
|
File without changes
|
|
File without changes
|