@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.
- package/README.md +11 -6
- 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/amr.d.ts +2 -2
- 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/auth/types/sign-in.d.ts +1 -1
- package/dist/auth/types/sign-in.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 +428 -100
- package/dist/index.js.map +22 -16
- 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/second-factor.md +1 -1
- package/docs/guide/sessions.md +3 -1
- package/docs/guide/signed-tokens.md +46 -0
- package/docs/roadmap.md +3 -1
- package/docs/troubleshooting.md +17 -5
- 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 |
|
|
@@ -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
|
|
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
|
|
package/docs/guide/sessions.md
CHANGED
|
@@ -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 | `
|
|
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`
|
|
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)
|
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)
|
|
@@ -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 (
|
|
306
|
-
unset or expired) sends every `@softistx` request
|
|
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://
|
|
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
|
-
|
|
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
|
File without changes
|
|
File without changes
|