@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.
- package/LICENSE +21 -0
- package/README.md +547 -2
- package/dist/bind.d.ts +104 -0
- package/dist/bind.d.ts.map +1 -0
- package/dist/device.d.ts +15 -0
- package/dist/device.d.ts.map +1 -0
- package/dist/errors.d.ts +60 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/fresh.d.ts +41 -0
- package/dist/fresh.d.ts.map +1 -0
- package/dist/index.d.ts +47 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +496 -0
- package/dist/index.js.map +22 -0
- package/dist/no-store.d.ts +8 -0
- package/dist/no-store.d.ts.map +1 -0
- package/dist/passkeys/body.d.ts +12 -0
- package/dist/passkeys/body.d.ts.map +1 -0
- package/dist/passkeys/index.d.ts +8 -0
- package/dist/passkeys/index.d.ts.map +1 -0
- package/dist/passkeys/routes.d.ts +32 -0
- package/dist/passkeys/routes.d.ts.map +1 -0
- package/dist/passkeys/types.d.ts +105 -0
- package/dist/passkeys/types.d.ts.map +1 -0
- package/dist/permission.d.ts +80 -0
- package/dist/permission.d.ts.map +1 -0
- package/dist/provide.d.ts +19 -0
- package/dist/provide.d.ts.map +1 -0
- package/dist/session.d.ts +156 -0
- package/dist/session.d.ts.map +1 -0
- package/dist/social/index.d.ts +9 -0
- package/dist/social/index.d.ts.map +1 -0
- package/dist/social/redirect.d.ts +9 -0
- package/dist/social/redirect.d.ts.map +1 -0
- package/dist/social/refusals.d.ts +14 -0
- package/dist/social/refusals.d.ts.map +1 -0
- package/dist/social/routes.d.ts +32 -0
- package/dist/social/routes.d.ts.map +1 -0
- package/dist/social/types.d.ts +90 -0
- package/dist/social/types.d.ts.map +1 -0
- package/docs/README.md +15 -0
- package/docs/guide/permissions.md +225 -0
- package/docs/guide/routes.md +1164 -0
- package/docs/roadmap.md +76 -0
- package/docs/troubleshooting.md +871 -0
- 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).
|