@softistx/janus-hono 0.0.0-stage → 0.11.34

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 (46) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +547 -2
  3. package/dist/bind.d.ts +104 -0
  4. package/dist/bind.d.ts.map +1 -0
  5. package/dist/device.d.ts +15 -0
  6. package/dist/device.d.ts.map +1 -0
  7. package/dist/errors.d.ts +60 -0
  8. package/dist/errors.d.ts.map +1 -0
  9. package/dist/fresh.d.ts +41 -0
  10. package/dist/fresh.d.ts.map +1 -0
  11. package/dist/index.d.ts +47 -0
  12. package/dist/index.d.ts.map +1 -0
  13. package/dist/index.js +496 -0
  14. package/dist/index.js.map +22 -0
  15. package/dist/no-store.d.ts +8 -0
  16. package/dist/no-store.d.ts.map +1 -0
  17. package/dist/passkeys/body.d.ts +12 -0
  18. package/dist/passkeys/body.d.ts.map +1 -0
  19. package/dist/passkeys/index.d.ts +8 -0
  20. package/dist/passkeys/index.d.ts.map +1 -0
  21. package/dist/passkeys/routes.d.ts +32 -0
  22. package/dist/passkeys/routes.d.ts.map +1 -0
  23. package/dist/passkeys/types.d.ts +105 -0
  24. package/dist/passkeys/types.d.ts.map +1 -0
  25. package/dist/permission.d.ts +80 -0
  26. package/dist/permission.d.ts.map +1 -0
  27. package/dist/provide.d.ts +19 -0
  28. package/dist/provide.d.ts.map +1 -0
  29. package/dist/session.d.ts +156 -0
  30. package/dist/session.d.ts.map +1 -0
  31. package/dist/social/index.d.ts +9 -0
  32. package/dist/social/index.d.ts.map +1 -0
  33. package/dist/social/redirect.d.ts +9 -0
  34. package/dist/social/redirect.d.ts.map +1 -0
  35. package/dist/social/refusals.d.ts +14 -0
  36. package/dist/social/refusals.d.ts.map +1 -0
  37. package/dist/social/routes.d.ts +32 -0
  38. package/dist/social/routes.d.ts.map +1 -0
  39. package/dist/social/types.d.ts +90 -0
  40. package/dist/social/types.d.ts.map +1 -0
  41. package/docs/README.md +15 -0
  42. package/docs/guide/permissions.md +225 -0
  43. package/docs/guide/routes.md +1164 -0
  44. package/docs/roadmap.md +76 -0
  45. package/docs/troubleshooting.md +871 -0
  46. package/package.json +62 -5
@@ -0,0 +1,871 @@
1
+ # Troubleshooting `@softistx/janus-hono`
2
+
3
+ Installing `@softistx/janus*` fails with a 401 or 404? See
4
+ [the install entry](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#installing-softistx-packages).
5
+
6
+ Each entry is headed by what you see: a compiler error, a thrown `TypeError`,
7
+ or a status and its body. Search this page for its words.
8
+
9
+ This package **defines no error class**. What reaches `app.onError` is one of
10
+ `@softistx/janus`'s errors, and the codes are those of the core — see
11
+ [`@softistx/janus`'s troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md)
12
+ for what causes each.
13
+
14
+ ## Index
15
+
16
+ **Types**
17
+ - [`'c.var.user' is possibly 'null'`](#cvaruser-is-possibly-null)
18
+ - [`Property 'user' does not exist on type 'Readonly<ContextVariableMap>'`](#property-user-does-not-exist-on-type-readonlycontextvariablemap)
19
+ - [`Property 'email' does not exist on type 'User<"patient", …> | User<"staff", …>'`](#property-email-does-not-exist-on-type-userpatient---userstaff-)
20
+ - [`Type '"doctor"' is not assignable to type '"patient" | "staff"'`](#type-doctor-is-not-assignable-to-type-patient--staff)
21
+ - [`Argument of type 'string | undefined' is not assignable to parameter of type 'string'`, in `load`](#argument-of-type-string--undefined-is-not-assignable-to-parameter-of-type-string-in-load)
22
+ - [`Expected 5 arguments, but got 4`, on `permission()`](#expected-5-arguments-but-got-4-on-permission)
23
+ - [`Type '{ id: string; }' is not assignable to type 'Awaitable<ObjectData<…> | null>'`](#type--id-string--is-not-assignable-to-type-awaitableobjectdata--null)
24
+ - [`Property 'access' does not exist on type 'Readonly<ContextVariableMap & …>'`](#property-access-does-not-exist-on-type-readonlycontextvariablemap--)
25
+ - [`Type '"lax"' is not assignable to type '"Lax" | "Strict" | "None" | undefined'. Did you mean '"Lax"'?`](#type-lax-is-not-assignable-to-type-lax--strict--none--undefined-did-you-mean-lax), on `deviceOf` or `sendSession`
26
+ - [`Object literal may only specify known properties, and 'name' does not exist in type 'SendSessionOptions'.`](#object-literal-may-only-specify-known-properties-and-name-does-not-exist-in-type-sendsessionoptions)
27
+ - [`Argument of type 'SignInResult<…>' is not assignable to parameter of type …`, on `sendSession`](#argument-of-type-signinresult-is-not-assignable-to-parameter-of-type--readonly-token-string-readonly-session-session-readonly-user--)
28
+
29
+ **Runtime**
30
+ - [`500 Internal Server Error` for every refusal](#500-internal-server-error-for-every-refusal)
31
+ - [`TypeError: permission(): c.var.object is already set`](#typeerror-permission-cvarobject-is-already-set)
32
+ - [`TypeError: permission(): c.var.user is not set`](#typeerror-permission-cvaruser-is-not-set)
33
+ - [`TypeError: fresh(): c.var.session is not set — put session(auth) before it`](#typeerror-fresh-cvarsession-is-not-set--put-sessionauth-before-it)
34
+ - [`TypeError: fresh: maxAge: "<value>" is not a duration …`](#typeerror-fresh-maxage-value-is-not-a-duration-)
35
+ - [`403 {"code":"STEP_UP_REQUIRED"}` for a signed-in user](#403-codestep_up_required-for-a-signed-in-user)
36
+ - [`403 {"code":"STEP_UP_REQUIRED"}` for an API key](#403-codestep_up_required-for-an-api-key)
37
+ - [`401` for a valid API key](#401-for-a-valid-api-key)
38
+ - [`403` where the user should be allowed](#403-where-the-user-should-be-allowed)
39
+ - [`401` with an empty body, for a signed-in user](#401-with-an-empty-body-for-a-signed-in-user)
40
+ - [`503 {"code":"STORE_FAILED"}` on every route](#503-codestore_failed-on-every-route)
41
+ - [`Warning: janusErrors: report failed on …`](#warning-januserrors-report-failed-on-)
42
+ - [`400 {"code":"HASH_UNSUPPORTED"}` on sign-in](#400-codehash_unsupported-on-sign-in)
43
+ - [`401 {"code":"CODE_INVALID","attemptsLeft":<n>}` on the code form](#401-codecode_invalidattemptsleftn-on-the-code-form) — a second factor's, or the code sent by e-mail
44
+ - [`401 {"code":"CREDENTIALS_INVALID","retryAfter":<n>}` with the right password](#401-codecredentials_invalidretryaftern-with-the-right-password)
45
+ - [`404 {"code":"MAGIC_LINK_DISABLED"}` on a magic-link route](#404-codemagic_link_disabled-on-a-magic-link-route)
46
+ - [`429 {"code":"MAIL_THROTTLED","retryAfter":<n>}` on a request for an e-mail](#429-codemail_throttledretryaftern-on-a-request-for-an-e-mail)
47
+ - [`403 Forbidden` on `POST /sign-in/link`](#403-forbidden-on-post-sign-inlink) — Hono's `csrf()`, not `janusErrors()`
48
+ - [`409 {"code":"SECOND_FACTOR_ACTIVE"}` or `409 {"code":"SECOND_FACTOR_NOT_ENROLLED"}`](#409-codesecond_factor_active-or-409-codesecond_factor_not_enrolled)
49
+ - [`409 {"code":"PASSKEY_TAKEN"}` or `409 {"code":"PASSKEY_LIMIT"}` on `POST /auth/passkeys`](#409-codepasskey_taken-or-409-codepasskey_limit-on-post-authpasskeys)
50
+ - [A response that answers a challenge or a session token is cached](#a-response-that-answers-a-challenge-or-a-session-token-is-cached)
51
+ - [`?socialError=<code>` on the landing page](#socialerrorcode-on-the-landing-page)
52
+ - [Every social callback is `FLOW_MISMATCH`](#every-social-callback-is-flow_mismatch)
53
+ - [The browser never sends the cookie back](#the-browser-never-sends-the-cookie-back)
54
+ - [A bearer client holds an expiry earlier than the session's](#a-bearer-client-holds-an-expiry-earlier-than-the-sessions)
55
+ - [Every sign-in reports a new device](#every-sign-in-reports-a-new-device)
56
+ - [No device cookie is set](#no-device-cookie-is-set)
57
+ - [`RangeError: deviceCookie(): maxAge must be a number of seconds from 0 to 34560000 (400 days), got …`](#rangeerror-devicecookie-maxage-must-be-a-number-of-seconds-from-0-to-34560000-400-days-got-)
58
+ - [`TypeError: deviceCookie(): …` (a name, prefix or attribute the browser would refuse)](#typeerror-devicecookie--a-name-prefix-or-attribute-the-browser-would-refuse)
59
+ - [`TypeError: signIn: a device was given, but janus() has no devices — pass devices: { keys }`](#typeerror-signin-a-device-was-given-but-janus-has-no-devices--pass-devices--keys-)
60
+
61
+ ## Types
62
+
63
+ ### `'c.var.user' is possibly 'null'`
64
+
65
+ **When:** reading `c.var.user` in a route behind `session(auth)`.
66
+
67
+ **Why:** the route does not require a user, so an anonymous request reaches
68
+ it. The same holds for `required` given a computed `boolean`: only a literal
69
+ `true` removes the `null`.
70
+
71
+ **Fix:** require a user, or answer the anonymous request yourself.
72
+
73
+ ```ts
74
+ app.get('/me', session(auth, { required: true }), (c) => c.json(c.var.user));
75
+ ```
76
+
77
+ ### `Property 'user' does not exist on type 'Readonly<ContextVariableMap>'`
78
+
79
+ **When:** `app.use(session(auth))` on its own line, then `c.var.user` in a
80
+ route declared after it.
81
+
82
+ **Why:** Hono types a chain of calls, not separate statements.
83
+
84
+ **Fix:** declare the app with the `Env`, or pass `session(auth)` to the route.
85
+
86
+ ```ts
87
+ const app = new Hono<SessionEnv<typeof auth>>();
88
+ app.use(session(auth));
89
+ ```
90
+
91
+ ### `Property 'email' does not exist on type 'User<"patient", …> | User<"staff", …>'`
92
+
93
+ **When:** several user types, and `session(auth)` without `type`.
94
+
95
+ **Why:** the route admits every user type, so `c.var.user` is their union, and
96
+ a field only one type has is not on it.
97
+
98
+ **Fix:** name the type the route admits, or narrow on `user.type`.
99
+
100
+ ```ts
101
+ app.get('/me', session(auth, { type: 'patient', required: true }), (c) =>
102
+ c.json({ email: c.var.user.email }),
103
+ );
104
+ ```
105
+
106
+ ### `Type '"doctor"' is not assignable to type '"patient" | "staff"'`
107
+
108
+ **When:** `session(auth, { type: 'doctor' })`, or `SessionEnv<typeof auth, 'doctor'>`.
109
+
110
+ **Why:** `type` names a user type of the instance you pass, and `doctor` is
111
+ not one of them — a misspelling, or a type from another `janus()`.
112
+
113
+ **Fix:** use one of the names in the message, the keys of `users` in
114
+ `janus({ users })`.
115
+
116
+ ### `Argument of type 'string | undefined' is not assignable to parameter of type 'string'`, in `load`
117
+
118
+ **When:** `permission(access, 'view', 'record', (c) => records.find(c.req.param('id')))`.
119
+
120
+ **Why:** `load` takes a plain `Context`: `permission()` is built before Hono
121
+ attaches it to a route, so `c.req.param('id')` is `string | undefined` there.
122
+
123
+ **Fix:** a missing id is nothing to load: answer `null`, which is a 404 —
124
+ what `byParam` does.
125
+
126
+ ```ts
127
+ permission(access, 'view', 'record', byParam('id', (id) => records.find(id)));
128
+ ```
129
+
130
+ ### `Expected 5 arguments, but got 4`, on `permission()`
131
+
132
+ **When:** the permission reaches a `when()` condition, and no options were
133
+ passed.
134
+
135
+ **Why:** a condition needs its `ctx`, and `permission()` requires it exactly
136
+ then — as `can()` does.
137
+
138
+ **Fix:** pass `ctx`, read from the request and the loaded object.
139
+
140
+ ```ts
141
+ permission(access, 'edit', 'record', load, {
142
+ ctx: (c, record) => ({ locked: record.locked }),
143
+ });
144
+ ```
145
+
146
+ ### `Type '{ id: string; }' is not assignable to type 'Awaitable<ObjectData<…> | null>'`
147
+
148
+ Also: `Property 'doctorId' is missing in type '{ id: string; }'`.
149
+
150
+ **When:** `load` answers an object without a field a `fromField` of its type
151
+ reads — `doctorId` for `fromField('doctorId', 'staff')`.
152
+
153
+ **Why:** `can()` reads that relation from the object. At run time a missing
154
+ field is a `TypeError` — `can: record.doctors reads doctorId, which the object
155
+ does not carry …` — never a denial, so the type refuses it first.
156
+
157
+ **Fix:** load the field — `null` when it holds nobody.
158
+
159
+ ### `Property 'access' does not exist on type 'Readonly<ContextVariableMap & …>'`
160
+
161
+ **When:** `c.var.access` or `c.var.auth` in a route. With nothing before the
162
+ route that sets a variable, the type is `'Readonly<ContextVariableMap>'`, with
163
+ no `&`.
164
+
165
+ **Why:** `provide()` was not in the chain before the route, or was not given
166
+ that instance: it sets, and types, only what it is given.
167
+
168
+ **Fix:**
169
+
170
+ ```ts
171
+ const app = new Hono().use(session(auth), provide({ auth, access }));
172
+ ```
173
+
174
+ ### `Type '"lax"' is not assignable to type '"Lax" | "Strict" | "None" | undefined'. Did you mean '"Lax"'?`
175
+
176
+ **When:** `tsc`, on `deviceOf(c, { sameSite: 'lax' })` or
177
+ `sendSession(c, auth, signedIn, { device: { sameSite: 'lax' } })` — the
178
+ session cookie's option copied over.
179
+ **Why:** the device cookie is set by Hono's `setCookie`, whose `sameSite` is
180
+ capitalised; `janus({ cookie })`'s is lowercase.
181
+ **Fix:** `{ sameSite: 'Lax' }` — or leave it out: `'Lax'` is the default.
182
+
183
+ ### `Object literal may only specify known properties, and 'name' does not exist in type 'SendSessionOptions'.`
184
+
185
+ **When:** `tsc`, on `sendSession(c, auth, signedIn, { name: 'device' })`.
186
+ **Why:** `sendSession`'s options hold the device cookie's under `device`.
187
+ **Fix:** `sendSession(c, auth, signedIn, { device: { name: 'device' } })`,
188
+ and the same object to `deviceOf(c, { name: 'device' })`.
189
+
190
+ ### `Argument of type 'SignInResult<…>' is not assignable to parameter of type '{ readonly token: string; readonly session: Session; readonly user: … }'`
191
+
192
+ Also: `Type 'SecondFactorRequired' is missing the following properties …: token, session, user`.
193
+
194
+ **When:** `sendSession(c, auth, await auth.signIn(...))`,
195
+ `sendSession(c, auth, await auth.magicLink.confirm(token))` or
196
+ `sendSession(c, auth, await auth.signInCode.confirm(challenge, code))`, once
197
+ `janus()` is given a `secondFactor`, for a user type with a password.
198
+
199
+ **Why:** each of the three then answers a session, or `{ status: 'secondFactor',
200
+ challenge, expiresAt, userId }` for a user whose second factor is active — and a
201
+ challenge is no session to send. A link or a code sent by e-mail proves the
202
+ e-mail, not the factor. A user type with no password has no second factor, so
203
+ its `confirm` answers a session and compiles as it is.
204
+
205
+ **Fix:** switch on `status`, and send the session `secondFactor.confirm`
206
+ answers on the next request. For the password form:
207
+
208
+ ```ts
209
+ app.post('/sign-in', async (c) => {
210
+ const result = await auth.signIn(await c.req.json());
211
+ if (result.status === 'secondFactor') {
212
+ // never in a URL: the body of the code form, or a short-lived cookie
213
+ return c.json({ challenge: result.challenge, expiresAt: result.expiresAt });
214
+ }
215
+ return c.json(sendSession(c, auth, result));
216
+ });
217
+
218
+ app.post('/sign-in/code', async (c) => {
219
+ const { challenge, code } = await c.req.json();
220
+ return c.json(sendSession(c, auth, await auth.secondFactor.confirm(challenge, code)));
221
+ });
222
+ ```
223
+
224
+ `magicLink.confirm` and `signInCode.confirm` narrow the same way. They hand
225
+ the challenge on in a cookie, which the guide's `/sign-in/code` reads instead of
226
+ the body. `CHALLENGE`, `scope` and that route are under
227
+ [A second factor](guide/routes.md#a-second-factor). The link route redirects, as below. The code route answers
228
+ `c.json({ next: 'secondFactor' })` instead. See "With a second factor" under
229
+ [a code sent by e-mail](guide/routes.md#with-a-second-factor) and under
230
+ [a link sent by e-mail](guide/routes.md#with-a-second-factor-1).
231
+
232
+ ```ts
233
+ const result = await auth.magicLink.confirm(token);
234
+ if (result.status === 'secondFactor') {
235
+ setCookie(c, CHALLENGE, result.challenge, { ...scope, expires: result.expiresAt });
236
+ return c.redirect('/sign-in/second-factor', 303); // a page whose form posts the code to /sign-in/code
237
+ }
238
+ sendSession(c, auth, result);
239
+ ```
240
+
241
+ ## Runtime
242
+
243
+ ### `TypeError: permission(): c.var.object is already set`
244
+
245
+ **When:** the first request to a route with two `permission()` guards, or one
246
+ behind a middleware of yours that sets `c.var.object`.
247
+
248
+ **Why:** `permission()` hands the route its object as `c.var.object`. Two
249
+ would claim the one variable, and the route would be typed as if it held both.
250
+
251
+ **Fix:** one `permission()` per route. Check a parent through an arrow in the
252
+ model, so the one check covers it.
253
+
254
+ ```ts
255
+ record: {
256
+ related: { owners: ['patient'], folders: ['folder'] },
257
+ permits: { view: ['owners', 'folders->view'] },
258
+ },
259
+ ```
260
+
261
+ ### `TypeError: permission(): c.var.user is not set`
262
+
263
+ **When:** the first request to a route guarded by `permission()`.
264
+
265
+ **Why:** nothing set `c.var.user`: no `session()` before `permission()` in that
266
+ route's chain, and no `subject` option. It is a wiring error, so it is thrown
267
+ rather than answered 401.
268
+
269
+ **Fix:** put `session(auth)` before it — on the route or with `app.use` — or
270
+ say who the subject is.
271
+
272
+ ```ts
273
+ app.get('/records/:id', session(auth), permission(access, 'view', 'record', load), handler);
274
+ ```
275
+
276
+ ### `TypeError: fresh(): c.var.session is not set — put session(auth) before it`
277
+
278
+ **When:** the first request to a route guarded by `fresh()`.
279
+
280
+ **Why:** nothing set `c.var.session`: no `session()` before `fresh()` in
281
+ that route's chain. It is a wiring error, so it is thrown rather than
282
+ answered 401.
283
+
284
+ **Fix:** put `session(auth)` before it — on the route or with `app.use`:
285
+
286
+ ```ts
287
+ app.delete('/account', session(auth, { required: true }), fresh('10m'), handler);
288
+ ```
289
+
290
+ ### `TypeError: fresh: maxAge: "<value>" is not a duration …`
291
+
292
+ **When:** when the app is wired: the line that calls `fresh('10 m')`, or
293
+ `fresh()` with a `maxAge` computed as a string, throws before any request.
294
+
295
+ **Why:** a `maxAge` is a number of milliseconds, or a number followed by
296
+ one unit — `ms`, `s`, `m`, `h` or `d`. The type refuses most mistakes;
297
+ a computed string or a space (`'10 m'`) reaches here.
298
+
299
+ **Fix:**
300
+
301
+ ```ts
302
+ fresh('10m'); // or fresh(600_000)
303
+ ```
304
+
305
+ ### `403 {"code":"STEP_UP_REQUIRED"}` for a signed-in user
306
+
307
+ **When:** a route guarded by `fresh(maxAge)`, for a session that signed in
308
+ — or was last confirmed by a step-up — `maxAge` ago or more.
309
+
310
+ **Why:** the route asks for a recent proof of who the user is. A session
311
+ renewed yesterday is still as old as its sign-in: renewal never moves
312
+ `authenticatedAt`. In a spec, a `fresh()` without `janus()`'s clock reads
313
+ the system time, not `clock.advance()`'s.
314
+
315
+ **Fix:** it is not a denial. Have the client run a step-up —
316
+ `auth.stepUp.request`, then `auth.stepUp.confirm(c.req.raw, challenge,
317
+ code)` — and send the same request again; see
318
+ [the routes guide](guide/routes.md#a-step-up). In a spec, pass the clock:
319
+ `fresh('10m', { clock })`.
320
+
321
+ ### `403 {"code":"STEP_UP_REQUIRED"}` for an API key
322
+
323
+ **When:** a request presenting an API key reaches a route guarded by
324
+ `fresh(maxAge)`.
325
+
326
+ **Why:** a key proves nothing recent: it is never fresh, and a step-up cannot
327
+ change that. `fresh()` throws `STEP_UP_REQUIRED` with `reason: 'apiKey'`.
328
+
329
+ **Fix:** keep that route for a signed-in session — put it behind
330
+ `session(auth)` without `apiKey: true`, or have the client sign in. Do not
331
+ loosen `fresh()` for keys.
332
+
333
+ ### `401` for a valid API key
334
+
335
+ **When:** a request with `Authorization: Bearer sl_…` is answered 401 (or
336
+ `c.var.user` is `null`).
337
+
338
+ **Why:** the route's `session()` was not given `{ apiKey: true }`, so the
339
+ key-shaped bearer is anonymous there; or the key was sent in the session
340
+ cookie or in `X-Session-Token` (a key is read from `Authorization: Bearer`
341
+ and nowhere else); or the key is revoked or lapsed; or the
342
+ user is inactive or of another `type` than the route's.
343
+
344
+ **Fix:** add `apiKey: true` to the `session()` of the routes meant for keys
345
+ (`janus()` must be wired with `apiKeys`, or the first request is a
346
+ `TypeError`). Check the key with `auth.apiKeys.list`.
347
+
348
+ ### `403` where the user should be allowed
349
+
350
+ **When:** a user who holds the relation is refused.
351
+
352
+ **Why**, in the order to check:
353
+
354
+ 1. The user holds a relation, and the route asks a permission that does not
355
+ include it — `edit` is not `view`.
356
+ 2. A condition answered `false`: check what `ctx` computes.
357
+ 3. A `fromField`'s field holds another id, or `null`, in what `load` answered.
358
+ 4. The tuple names another user type than the one signed in — granted to
359
+ `patient:u1`, checked for `staff:u1`: the same id under another type is
360
+ somebody else.
361
+
362
+ **Fix:** ask `can()` directly with the same arguments; it answers the same.
363
+
364
+ ```ts
365
+ await access.can(user, 'view', { ...record, type: 'record' }); // the check permission() makes
366
+ ```
367
+
368
+ ### `500 Internal Server Error` for every refusal
369
+
370
+ **When:** a sign-in with a wrong password, a taken login or an outage answers
371
+ 500 instead of 401, 409 or 503.
372
+
373
+ **Why:** no `janusErrors()` on the app that ran the throwing code. A sub-app's
374
+ own `onError` is captured when `app.route()` mounts it; one with none uses the
375
+ parent's. An error from a middleware on the parent — `app.use(session(auth))`
376
+ — always uses the parent's.
377
+
378
+ **Fix:** set it on the app you serve, and on a sub-app before mounting it if
379
+ that sub-app has a handler of its own.
380
+
381
+ ```ts
382
+ app.onError(janusErrors());
383
+ sub.onError(janusErrors());
384
+ app.route('/staff', sub);
385
+ ```
386
+
387
+ ### `401` with an empty body, for a signed-in user
388
+
389
+ **When:** a route with `required: true` answers 401 although the user signed
390
+ in.
391
+
392
+ **Why**, in the order to check:
393
+
394
+ 1. The route passes `type`, and the user is of another type. The session
395
+ stands; it does not authenticate that user on this route.
396
+ 2. The request presents two session credentials, and the first one is stale.
397
+ **The first present wins, not the first valid one**: a lapsed
398
+ `Authorization: Bearer` beside a live cookie is anonymous.
399
+ 3. The session lapsed or was revoked — `signOut`, `signOutEverywhere`, a
400
+ password reset — or the user was deactivated.
401
+ 4. The browser did not send the cookie: see
402
+ [The browser never sends the cookie back](#the-browser-never-sends-the-cookie-back).
403
+
404
+ **Fix:** for 2, stop sending the stale header. For 1 and 3, it is the answer
405
+ you asked for.
406
+
407
+ ```ts
408
+ fetch(url, { credentials: 'include' }); // the cookie, and no stale Authorization header
409
+ ```
410
+
411
+ ### `503 {"code":"STORE_FAILED"}` on every route
412
+
413
+ **When:** every request that presents a session credential answers 503.
414
+
415
+ **Why:** a store cannot answer. `session()` calls the sessions store on every
416
+ request that presents a session token, and **an outage is never anonymous**: it
417
+ is `STORE_FAILED`, answered 503, so that nobody is told they are signed out
418
+ while the database is down. A request that presents nothing never reaches the
419
+ store, and stays anonymous.
420
+
421
+ **Fix:** the database. `janusErrors()` answers without logging: pass `report`
422
+ to see which store failed and why.
423
+
424
+ ```ts
425
+ app.onError(
426
+ janusErrors({
427
+ report: (error) =>
428
+ logger.error({ slot: error.slot, operation: error.operation }, error.cause),
429
+ }),
430
+ );
431
+ ```
432
+
433
+ ### `Warning: janusErrors: report failed on …`
434
+
435
+ **Why:** the `report` given to `janusErrors()` threw, or rejected — a logger
436
+ that is down, a serializer that meets a circular `cause`. The name after the
437
+ code is the class of what it threw.
438
+
439
+ **Fix:** your `report`. The response was sent all the same: a `report` never
440
+ changes the answer, so an outage is still a 503 and never a 500.
441
+
442
+ ### `400 {"code":"HASH_UNSUPPORTED"}` on sign-in
443
+
444
+ **When:** users imported from another system, or after a change of hasher.
445
+
446
+ **Why:** the stored password hash has a prefix no wired hasher reads. It is a
447
+ wiring fault, not the user's: they cannot act on the 400.
448
+
449
+ **Fix:** wire the hasher that wrote those hashes back as a verifier — see
450
+ [`@softistx/janus`'s passwords guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/passwords.md).
451
+
452
+ ```ts
453
+ janus({ …, hasher: bunHasher(), verifiers: [scryptHasher()] }); // old hashes still verify
454
+ ```
455
+
456
+ ### `401 {"code":"CODE_INVALID","attemptsLeft":<n>}` on the code form
457
+
458
+ Also `401 {"code":"CODE_INVALID"}`, with no `attemptsLeft`, from
459
+ `secondFactor.activate`: it has no challenge to count attempts against.
460
+
461
+ **When:** a route calling `secondFactor.confirm(challenge, code)`,
462
+ `secondFactor.recover(challenge, code)` with a recovery code,
463
+ `secondFactor.activate(user, code)` or
464
+ `secondFactor.regenerateRecoveryCodes(user, code)`, with a code that does not match or was
465
+ already used — or a route calling `signInCode.confirm(challenge, code)`, the
466
+ code sent by e-mail, with a code that does not match or is not six digits.
467
+
468
+ **Why:** `janusErrors()` answers a wrong code 401, like a wrong password. On
469
+ `confirm`, `attemptsLeft` is what the challenge has left of its five attempts;
470
+ at `0` it is spent, and the next call with it answers
471
+ `400 {"code":"TOKEN_SPENT"}`. If the code is the one the app shows, the cause
472
+ is a clock off by more than about 30 seconds, or a code used already — see
473
+ [`@softistx/janus`'s troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#the-code-the-authenticator-app-shows-is-refused-with-code_invalid).
474
+
475
+ On `signInCode.confirm`, `attemptsLeft` counts the same five attempts, and
476
+ at `0` the challenge is spent too: the right code no longer works with it.
477
+
478
+ On `secondFactor.regenerateRecoveryCodes`, `attemptsLeft` is what the user
479
+ has left of five attempts in the current 15-minute window. At `0`, every
480
+ call answers `401 {"code":"CODE_INVALID","attemptsLeft":0,"retryAfter":<n>}`
481
+ with a `Retry-After` header — the right code included, compared by nobody —
482
+ until the next window: tell the user to wait `retryAfter` seconds, at most 15
483
+ minutes. `stepUp.confirm` with an app's code shares that window, and a new
484
+ challenge does not help; a challenge spent alone answers `attemptsLeft: 0`
485
+ with no `retryAfter`. The message, in your logs, is
486
+ `secondFactor.regenerateRecoveryCodes: too many codes tried — wait for the next 15-minute window`.
487
+
488
+ The same window answers `stepUp.confirm` with an app's code, with the message
489
+ `stepUp.confirm: too many codes tried — wait for the next 15-minute window`
490
+ and the same body: wait `retryAfter` seconds. A new `stepUp.request` does not
491
+ help; a challenge whose own tries are spent, with the window free, answers
492
+ `attemptsLeft: 0` and no `retryAfter` — request a new one.
493
+
494
+ **Fix:** read `attemptsLeft` in the client: ask again while it is above `0`.
495
+ Once it is `0`, a sign-in goes back to the sign-in form. With `retryAfter` in
496
+ the body, the regenerate or step-up form tells the signed-in user to wait that
497
+ many seconds; a new challenge does not help.
498
+
499
+ ```ts
500
+ const response = await fetch('/sign-in/code', { method: 'POST', body: JSON.stringify({ challenge, code }) });
501
+ if (response.status === 401) {
502
+ const { attemptsLeft } = await response.json();
503
+ if (attemptsLeft === 0) showSignInForm();
504
+ else showCodeForm(`Wrong code — ${attemptsLeft} attempts left`);
505
+ }
506
+ ```
507
+
508
+ For the code sent by e-mail, request a new code once it is `0` — a new
509
+ challenge, with five attempts of its own:
510
+
511
+ ```ts
512
+ const response = await fetch('/sign-in/email/code', { method: 'POST', body: JSON.stringify({ code }) });
513
+ if (response.status === 401) {
514
+ const { attemptsLeft } = await response.json();
515
+ if (attemptsLeft === 0) showEmailForm(); // POST /sign-in/email again: a new code
516
+ else showCodeForm(`Wrong code — ${attemptsLeft} attempts left`);
517
+ }
518
+ ```
519
+
520
+ ### `401 {"code":"CREDENTIALS_INVALID","retryAfter":<n>}` with the right password
521
+
522
+ With a `Retry-After: <n>` header.
523
+
524
+ **When:** the sign-in route, after ten passwords were tried at the login in
525
+ the current 15-minute window — the right one is refused too until the window
526
+ ends.
527
+
528
+ **Why:** `@softistx/janus` throttles password guessing per login, on by default;
529
+ `retryAfter` is the seconds until the next window. Nothing locks: the next
530
+ window signs in. An end-to-end test that signs one login in with more than
531
+ ten wrong passwords over a `fixedClock` meets it at once.
532
+
533
+ **Fix:** show the visitor the wait, not "wrong password":
534
+
535
+ ```ts
536
+ const response = await fetch('/sign-in', { method: 'POST', body });
537
+ if (response.status === 401) {
538
+ const { retryAfter } = await response.json();
539
+ if (retryAfter !== undefined) showWait(`Too many attempts — try again in ${Math.ceil(retryAfter / 60)} min`);
540
+ else showError('Wrong e-mail or password');
541
+ }
542
+ ```
543
+
544
+ To change the limit, `janus({ signIn: { throttle: { attempts, window } } })`;
545
+ in a test, advance the clock past `retryAfter`, or wire
546
+ `signIn: { throttle: false }`.
547
+
548
+ ### `404 {"code":"MAGIC_LINK_DISABLED"}` on a magic-link route
549
+
550
+ **When:** your route calls `auth.magicLink.request`, `prepare` or `confirm` and
551
+ the instance was built with `janus({ magicLink: { enabled: false } })`.
552
+ **Why:** the core refuses before any store access, and `janusErrors()` answers
553
+ the code's status, 404. **Fix:** enable it, or do not offer the route and hide
554
+ the button with `auth.magicLink.enabled`.
555
+
556
+ ### `429 {"code":"MAIL_THROTTLED","retryAfter":<n>}` on a request for an e-mail
557
+
558
+ With a `Retry-After: <n>` header.
559
+
560
+ **When:** a route that asks for an e-mail — a sign-in link or code, a
561
+ password reset, an address check, an e-mailed step-up — after five requests
562
+ for the same address (the same user, for the last two) in the current
563
+ 10-minute window.
564
+
565
+ **Why:** `@softistx/janus` throttles the requests that hand out something to
566
+ e-mail, on by default, each flow on its own; an unknown address is counted
567
+ and refused alike, so nothing is revealed. `retryAfter` is the seconds until
568
+ the window ends. **A refused request spends and rotates nothing**: nothing was
569
+ sent or issued, and the last link or code sent, by anyone's request, still
570
+ works until it expires.
571
+
572
+ **Fix:** tell the visitor to use the last e-mail they received, or to wait:
573
+
574
+ ```ts
575
+ const response = await fetch('/sign-in/email', { method: 'POST', body });
576
+ if (response.status === 429) {
577
+ const { retryAfter } = await response.json();
578
+ showWait(`Check your inbox: the last e-mail we sent still works. You can ask for a new one in ${Math.ceil(retryAfter / 60)} min.`);
579
+ }
580
+ ```
581
+
582
+ To change the limit, `janus({ mail: { throttle: { attempts, window } } })`
583
+ (keep `window` no longer than the shortest `tokens.*` lifetime you use, or the
584
+ last code can expire first); `@softistx/janus` never sees IP addresses, so add a
585
+ per-IP ceiling with `@softistx/redis` rate limits. In a test, advance the clock past `retryAfter`, or wire
586
+ `mail: { throttle: false }`.
587
+
588
+ ### `403 Forbidden` on `POST /sign-in/link`
589
+
590
+ The body is the text `Forbidden`, not a `{ code }`. It is not a `JanusError`:
591
+ `csrf()` threw it, and `janusErrors()` hands it to Hono's default response, or
592
+ to your `fallback`.
593
+
594
+ **When:** the button of the page the e-mailed link opens, on the route
595
+ guarded by `csrf({ origin: ORIGIN })` — see
596
+ [a link sent by e-mail](guide/routes.md#a-link-sent-by-e-mail).
597
+
598
+ **Why:** Hono's `csrf()` lets a form post through when the browser sends
599
+ `Sec-Fetch-Site: same-origin`, or else an `Origin` header equal to `origin`,
600
+ character for character. Neither held:
601
+
602
+ - **The page and the route are on two origins.** The page may be served by a
603
+ development server on another port, or on `www.` while the route is on the
604
+ bare host. The browser then sends `same-site` or `cross-site`, and the
605
+ `Origin` decides.
606
+ - **The browser sends no `Sec-Fetch-Site`.** It sends none to plain `http://`
607
+ on a host other than `localhost` or a loopback address, and an older browser
608
+ sends none at all. The `Origin` decides here too.
609
+ - **The `Origin` is `null`.** A page sent with `Referrer-Policy: no-referrer`
610
+ makes the browser send `Origin: null` for every form it posts. So whenever
611
+ the `Origin` decides, the answer is 403, whatever `ORIGIN` holds.
612
+ - **`ORIGIN` is not what the browser shows.** Check for `http` against
613
+ `https`, a missing or extra port, or a trailing `/`. Leaving `origin` out does
614
+ not help behind a proxy: `csrf()` then compares with the URL the app sees,
615
+ which is the proxy's `http://` upstream, not the public one.
616
+
617
+ **Fix:** serve the page and the route on one origin, over HTTPS or on
618
+ `localhost` in development. Redirect `www.` to the bare host, and post the form
619
+ to a relative `action`. Set `ORIGIN` to the scheme, host and port the address
620
+ bar shows. Send the page with `strict-origin`, as
621
+ [the guide](guide/routes.md#a-link-sent-by-e-mail) does, never
622
+ `no-referrer`. A `Referer` then holds the origin only, never the path and its
623
+ token, and the form carries its real `Origin`.
624
+
625
+ ```ts
626
+ const ORIGIN = process.env.ORIGIN ?? 'https://app.example'; // what the address bar shows, no trailing slash
627
+
628
+ // on the GET page: the token's URL still reaches nobody, and Origin is no longer null
629
+ c.header('Referrer-Policy', 'strict-origin');
630
+
631
+ app.post('/sign-in/link', csrf({ origin: ORIGIN }), handler);
632
+ ```
633
+
634
+ ### `409 {"code":"SECOND_FACTOR_ACTIVE"}` or `409 {"code":"SECOND_FACTOR_NOT_ENROLLED"}`
635
+
636
+ **When:** a route calling `secondFactor.enroll` or `secondFactor.activate`
637
+ answers `SECOND_FACTOR_ACTIVE` for a user whose factor is already on;
638
+ `secondFactor.activate` with no `enroll` before it,
639
+ `secondFactor.regenerateRecoveryCodes` for a user with no active factor, or
640
+ `secondFactor.confirm` or `secondFactor.recover` after the factor was
641
+ disabled, answers `SECOND_FACTOR_NOT_ENROLLED`.
642
+
643
+ **Why:** both say the factor is not in the state the call needs — a conflict
644
+ with the user's state, so 409, not 400. A `409 {"code":"VERSION_CONFLICT"}`
645
+ from the code form, or from the recovery code route (`/sign-in/recovery`), is
646
+ the other 409: the same code submitted twice at once, where the first call
647
+ already opened the session.
648
+
649
+ **Fix:** read `c.var.user.hasSecondFactor` before offering "set up" or
650
+ "turn off"; after `SECOND_FACTOR_NOT_ENROLLED` on the code form or the recovery code
651
+ route, send the
652
+ visitor back to sign in. The causes of each are in
653
+ [`@softistx/janus`'s troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#second-factor).
654
+
655
+ ```ts
656
+ app.post('/me/second-factor', session(auth, { required: true }), async (c) => {
657
+ if (c.var.user.hasSecondFactor) return c.json({ active: true });
658
+ return c.json(await auth.secondFactor.enroll(c.var.user)); // { secret, uri }
659
+ });
660
+ ```
661
+
662
+ ### `409 {"code":"PASSKEY_TAKEN"}` or `409 {"code":"PASSKEY_LIMIT"}` on `POST /auth/passkeys`
663
+
664
+ Also `400 {"code":"PASSKEY_INVALID"}` and `403 {"code":"STEP_UP_REQUIRED"}`
665
+ on the same route, and `401 {"code":"CODE_INVALID","attemptsLeft":<n>}` on
666
+ `POST /auth/passkeys/sign-in`.
667
+
668
+ **When:** a page registers a passkey with `passkeyRoutes()`.
669
+
670
+ **Why:** `PASSKEY_TAKEN` — the authenticator's credential is already
671
+ registered, by this user or another (the options exclude the user's own, so
672
+ this is usually a retry after a lost answer). `PASSKEY_LIMIT` — the user holds
673
+ `maxPerUser` passkeys (`maxActive` in the body): remove one first.
674
+ `PASSKEY_INVALID` carries `field: 'name'` for a name that is not 1 to 100
675
+ characters (the challenge is still good), and no field for a response that did
676
+ not verify — the challenge is spent, so ask `registration-options` again;
677
+ `reason` is in the error for your logs, never in the body. `STEP_UP_REQUIRED`
678
+ — the session proved who it is longer ago than `passkeys.freshWithin`.
679
+
680
+ **Fix:** show the message for the code; for `STEP_UP_REQUIRED`, run `POST
681
+ /auth/passkeys/step-up` and `/step-up/confirm`, then send the request again.
682
+ A `CODE_INVALID` on `/sign-in` is a wrong, foreign or replayed assertion:
683
+ `attemptsLeft` is what the challenge has left, and at `0` the visitor signs in
684
+ again.
685
+
686
+ ### A response that answers a challenge or a session token is cached
687
+
688
+ **When:** a response that carries a single-use challenge or a session token, in its body or in a `Set-Cookie` (a session or a social flow cookie), has no `Cache-Control: no-store`, and a proxy or a CDN may keep it.
689
+
690
+ **Why:** the built-in routes send the header themselves: `passkeyRoutes()` (`POST /registration-options`, `POST /step-up`, and `POST /sign-in`, which sets the session cookie), `socialRoutes()` (the start and link redirects, which set the flow cookie, and the callback once the flow is spent), and `session()` when it re-sends a renewed session, on that response only. A route of your own does not, unless it calls `sendSession`: your password sign-in that answers a `challenge` or a bearer `token` in its body, or a handler (`onSignedIn`, `onSecondFactor`) that returns its own `Response`, which loses the headers set on `c`.
691
+
692
+ **Fix:** set `Cache-Control: no-store` on every response of yours that carries a `challenge` or a `token`:
693
+
694
+ ```ts
695
+ app.post('/sign-in', async (c) => {
696
+ const result = await auth.signIn(await c.req.json());
697
+ if (result.status === 'secondFactor') {
698
+ c.header('Cache-Control', 'no-store');
699
+ return c.json({ challenge: result.challenge });
700
+ }
701
+ const user = sendSession(c, auth, result); // sets no-store itself
702
+ return c.json({ id: user.id });
703
+ });
704
+ ```
705
+
706
+ ### `?socialError=<code>` on the landing page
707
+
708
+ **When:** the visitor comes back from the provider to `/path?socialError=SIGN_UP_DISABLED`
709
+ (or `EMAIL_UNVERIFIED`, `EMAIL_NOT_VERIFIED_FOR_LINK`, `SOCIAL_ACCOUNT_TAKEN`,
710
+ `USER_INACTIVE`, `PROVIDER_ERROR`, `FLOW_EXPIRED`, `FLOW_MISMATCH`, `FLOW_PURPOSE_MISMATCH`).
711
+
712
+ **Why:** the callback was refused. It redirects instead of answering JSON
713
+ because the browser is mid-navigation; the code is all it carries. The reason
714
+ of a `PROVIDER_ERROR` (`denied`, `refused`, `unreachable`) and its `cause`
715
+ are for your logs, in `onRefusal`, never in the page. `FLOW_EXPIRED` is a
716
+ replayed or late callback (ten minutes by default), `FLOW_MISMATCH` a missing
717
+ or foreign cookie, `FLOW_PURPOSE_MISMATCH` a flow of the other kind than the
718
+ `purpose` the application passed to `social.complete`.
719
+
720
+ **Fix:** show a message per code on the landing page, and let the visitor start
721
+ again. To log or answer differently, give `onRefusal`:
722
+
723
+ ```ts
724
+ socialRoutes(auth, {
725
+ onSecondFactor,
726
+ onRefusal: (c, error, location) => {
727
+ logger.warn({ code: error.code }); // never error.message, error.cause or location's returnTo
728
+ return c.redirect(location, 302);
729
+ },
730
+ });
731
+ ```
732
+
733
+ ### Every social callback is `FLOW_MISMATCH`
734
+
735
+ **When:** the round trip always ends in `?socialError=FLOW_MISMATCH`.
736
+
737
+ **Why:** the flow cookie does not come back with the callback. The usual
738
+ causes: the app is served on `http` while the cookie is `Secure` (a
739
+ `__Host-` cookie needs `https` and no `Domain`); the callback is on another
740
+ host than the start (the cookie is per host); a proxy strips cookies; or the
741
+ route that read the cookie was not under the same `Path`.
742
+
743
+ **Fix:** start and finish on one origin, over `https` in production, and read
744
+ the name from `auth.social.cookie.name`, never a literal:
745
+
746
+ ```ts
747
+ auth.social.cookie.name; // '__Host-janus-social-flow' or 'janus-social-flow'
748
+ ```
749
+
750
+ ### The browser never sends the cookie back
751
+
752
+ **When:** `sendSession` answered a `Set-Cookie`, and the next request presents
753
+ no cookie.
754
+
755
+ **Why:** one of three.
756
+
757
+ - The cookie is `Secure` by default, and the page is served over plain
758
+ `http://` on a host other than `localhost`.
759
+ - The front end is on another origin: the browser sends a cookie cross-origin
760
+ only with `credentials: 'include'`, to a server that allows credentials, and
761
+ `SameSite=Lax` (the default) drops it from a cross-site `POST`.
762
+ - `sameSite: 'none'` without `secure` is refused when `janus()` is called —
763
+ `cookie.sameSite "none" requires cookie.secure` — so it never gets that far.
764
+
765
+ **Fix:** serve over HTTPS; for a development server off `localhost`,
766
+ `cookie: { secure: false }` in `janus()`, never in production. For a front end
767
+ on another origin:
768
+
769
+ ```ts
770
+ import { cors } from 'hono/cors';
771
+
772
+ // janus({ …, cookie: { sameSite: 'none' } }) — secure stays true
773
+ app.use(cors({ origin: 'https://front.example', credentials: true }));
774
+ // in the front end: fetch(url, { credentials: 'include' })
775
+ ```
776
+
777
+ ### A bearer client holds an expiry earlier than the session's
778
+
779
+ **When:** a bearer client caches `session.expiresAt` from its sign-in, and
780
+ treats the session as over at that date.
781
+
782
+ **Why:** the session was renewed in passing, and its expiry moved in the store.
783
+ A bearer client is never sent a cookie saying so, and its session token does
784
+ not change.
785
+
786
+ **Fix:** nothing to fix unless the client caches the expiry. If it does, answer
787
+ `c.var.session.expiresAt` from a route it calls.
788
+
789
+ ```ts
790
+ app.get('/session', session(auth, { required: true }), (c) =>
791
+ c.json({ expiresAt: c.var.session.expiresAt }),
792
+ );
793
+ ```
794
+
795
+ ### Every sign-in reports a new device
796
+
797
+ **When:** `signedIn.newDevice` is `true` — and a notice sent — at every
798
+ sign-in, from a browser the user always uses.
799
+ **Why:** the token `deviceOf` reads does not prove this user signed in
800
+ there. With this package, most often:
801
+
802
+ - `deviceOf` and `sendSession` were given different options — another
803
+ `name`, or a `path` the sign-in route is outside of — so the cookie written
804
+ is never the one read;
805
+ - the device cookie is `Secure`, and the page is served over plain `http://`
806
+ on a host other than `localhost`: see
807
+ [The browser never sends the cookie back](#the-browser-never-sends-the-cookie-back);
808
+ - a confirmation route passes `{ device: null }` rather than
809
+ `{ device: deviceOf(c) }`.
810
+
811
+ `@softistx/janus`'s [troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#every-sign-in-reports-a-new-device)
812
+ has the other causes: a device key removed, two people sharing a browser.
813
+ **Fix:** one `DeviceCookieOptions`, passed to both:
814
+
815
+ ```ts
816
+ const device = { name: 'device' } as const;
817
+ const signedIn = await auth.signIn(input, { device: deviceOf(c, device) });
818
+ sendSession(c, auth, signedIn, { device });
819
+ ```
820
+
821
+ ### No device cookie is set
822
+
823
+ **When:** `sendSession` appends the session cookie and no `janus-device`.
824
+ **Why:** the answer carries no `deviceToken`: the sign-in was given no
825
+ `device` — `{ device: deviceOf(c) }` left out, or a second factor's
826
+ `confirm` called without it, since the challenge carries none. The session
827
+ renewal of `session()` never sets it either.
828
+ **Fix:** give every call that opens a session `{ device: deviceOf(c) }`.
829
+
830
+ ### `RangeError: deviceCookie(): maxAge must be a number of seconds from 0 to 34560000 (400 days), got …`
831
+
832
+ **When:** `sendSession` or `sendDevice` is called
833
+ with a `maxAge` that is not a finite number from 0 to 34560000 — `NaN`,
834
+ `Infinity`, a negative value, or above 400 days — most often milliseconds
835
+ given where seconds belong. It throws after the sign-in completed: the
836
+ session exists, the response is not sent.
837
+ **Why:** a browser keeps a cookie 400 days at most, and `deviceCookie` refuses
838
+ a `maxAge` it would not keep rather than write it.
839
+ **Fix:** give seconds within 0 to 34560000 — or leave `maxAge` out, which is
840
+ 400 days.
841
+
842
+ ```ts
843
+ sendSession(c, auth, signedIn, { device: { maxAge: 60 * 60 * 24 * 180 } }); // 180 days
844
+ ```
845
+
846
+ ### `TypeError: deviceCookie(): …` (a name, prefix or attribute the browser would refuse)
847
+
848
+ **When:** `sendSession` or `sendDevice` is called
849
+ with a `name` that is not a valid cookie name, a `__Secure-` name without
850
+ `secure: true`, a `__Host-` name without `secure: true`, with a `path` other
851
+ than `'/'` or with a `domain`, or a `domain`, `path` or `sameSite` holding
852
+ `;`, a carriage return or a line feed. The message names the option.
853
+ **Why:** `deviceCookie` refuses what Hono's `setCookie` refuses: a browser
854
+ would drop the cookie, and a `;` or line break in an attribute could inject
855
+ another one.
856
+ **Fix:** meet the prefix's terms, or drop the prefix — `__Host-` asks `Secure`,
857
+ `Path=/` and no `Domain`; [the core entry](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#typeerror-devicecookie--a-name-prefix-or-attribute-the-browser-would-refuse) has the list.
858
+
859
+ ```ts
860
+ sendSession(c, auth, signedIn, { device: { name: '__Host-device' } }); // Secure, Path=/, no Domain
861
+ ```
862
+
863
+ ### `TypeError: signIn: a device was given, but janus() has no devices — pass devices: { keys }`
864
+
865
+ **When:** a route passes `{ device: deviceOf(c) }` — even when it answers
866
+ `null` — to a `janus()` wired without `devices`. It reaches
867
+ `janusErrors()`'s `fallback`, or Hono's 500: a `TypeError` is a wiring
868
+ mistake, not a refusal.
869
+ **Fix:** give that `janus()` `devices: { keys }` — every instance that signs
870
+ users in needs the same — or stop passing `device`. See
871
+ [`@softistx/janus`'s devices guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/devices.md#wiring).