@zukhruf/authentication 0.8.36 → 0.8.37
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -9
- package/dist/react-router.d.ts +7 -1
- package/dist/react-router.d.ts.map +1 -1
- package/dist/react-router.js +8 -1
- package/dist/react-router.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -73,7 +73,7 @@ const target = safeRedirect(searchParams.get(REDIRECT_TO), {
|
|
|
73
73
|
navigate(target, { replace: true });
|
|
74
74
|
```
|
|
75
75
|
|
|
76
|
-
A visitor on `/cases/42?tab=notes` without a session lands on `/sign-in?redirectTo=%2Fcases%2F42%3Ftab%3Dnotes`. When better-auth cannot answer (the network or the server is down), the loader throws `AuthenticationUnavailableError` for the route's error element, instead of sending a signed-in user to sign in ([ADR 0006](./docs/adr/0006-a-failed-session-read-is-authentication-unavailable-never-signed-out.md)).
|
|
76
|
+
A visitor on `/cases/42?tab=notes` without a session lands on `/sign-in?redirectTo=%2Fcases%2F42%3Ftab%3Dnotes`. When better-auth cannot answer (the network or the server is down), the loader throws `AuthenticationUnavailableError` for the route's error element, instead of sending a signed-in user to sign in. A navigation away aborts the loader's request, and with it the session read ([ADR 0006](./docs/adr/0006-a-failed-session-read-is-authentication-unavailable-never-signed-out.md)).
|
|
77
77
|
|
|
78
78
|
## API
|
|
79
79
|
|
|
@@ -98,7 +98,9 @@ class TwoFactorRequiredError extends HTTPException {} // 403, cause { code: 'aut
|
|
|
98
98
|
|
|
99
99
|
// @zukhruf/authentication/react-router
|
|
100
100
|
interface SessionClient<S> {
|
|
101
|
-
getSession(
|
|
101
|
+
getSession(options?: {
|
|
102
|
+
fetchOptions?: { signal?: AbortSignal };
|
|
103
|
+
}): Promise<{ data: S | null; error: { status: number } | null }>;
|
|
102
104
|
} // the member of a better-auth client that the package calls
|
|
103
105
|
|
|
104
106
|
type RequireSessionOptions<S extends { user: object }> = {
|
|
@@ -133,13 +135,13 @@ The guard expects the default client, whose `getSession()` answers `{ data, erro
|
|
|
133
135
|
|
|
134
136
|
## What a call does underneath
|
|
135
137
|
|
|
136
|
-
| Call | What happens
|
|
137
|
-
| ------------------------------------------- |
|
|
138
|
-
| `requireSession(auth)` | `auth.api.getSession({ headers: c.req.raw.headers })` once. `null` throws `UnauthenticatedError`; a session goes on `c.var.session`. An error of `getSession` (the database is down) reaches the app as it is
|
|
139
|
-
| `requireSession(auth, { twoFactor: true })` | as above, then `session.user.twoFactorEnabled !== true` throws `TwoFactorRequiredError`. better-auth gives no session to a user who turned two-factor on and did not enter the code, so a session either passed the second factor or belongs to a user who never turned it on
|
|
140
|
-
| React Router `requireSession` | one `client.getSession()`.
|
|
141
|
-
| the return path | `pathname + search` of `request.url`. On a page in `signIn` or `twoFactorSetup` itself, the page's own safe `redirectTo` goes on, so no page sends a visitor back to sign in. A path longer than 2,048 characters is left out
|
|
142
|
-
| `safeRedirect(to)` | the fallback, unless `to` starts with `/`, not with `//` or `/\`, is at most 2,048 characters, parses on `origin` to the same origin, and its path is not in `exclude`. Then the parsed `pathname + search + hash`, so a tab or newline that the parser drops cannot turn `/\t/evil.example` into `//evil.example`
|
|
138
|
+
| Call | What happens |
|
|
139
|
+
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
140
|
+
| `requireSession(auth)` | `auth.api.getSession({ headers: c.req.raw.headers })` once. `null` throws `UnauthenticatedError`; a session goes on `c.var.session`. An error of `getSession` (the database is down) reaches the app as it is |
|
|
141
|
+
| `requireSession(auth, { twoFactor: true })` | as above, then `session.user.twoFactorEnabled !== true` throws `TwoFactorRequiredError`. better-auth gives no session to a user who turned two-factor on and did not enter the code, so a session either passed the second factor or belongs to a user who never turned it on |
|
|
142
|
+
| React Router `requireSession` | one `client.getSession({ fetchOptions: { signal: request.signal } })`. When React Router aborts the request, the abort is thrown as it is, and the router ignores it. Any other rejection, or an `error`, throws `AuthenticationUnavailableError`. No session throws `replace(signIn + '?redirectTo=' + path)`. A user without two-factor, when `twoFactorSetup` is given, throws `replace(twoFactorSetup + '?redirectTo=' + path)`. On the `twoFactorSetup` page itself the two-factor check passes, so the page never redirects to itself. Otherwise it returns the session |
|
|
143
|
+
| the return path | `pathname + search` of `request.url`. On a page in `signIn` or `twoFactorSetup` itself, the page's own safe `redirectTo` goes on, so no page sends a visitor back to sign in. A path longer than 2,048 characters is left out |
|
|
144
|
+
| `safeRedirect(to)` | the fallback, unless `to` starts with `/`, not with `//` or `/\`, is at most 2,048 characters, parses on `origin` to the same origin, and its path is not in `exclude`. Then the parsed `pathname + search + hash`, so a tab or newline that the parser drops cannot turn `/\t/evil.example` into `//evil.example` |
|
|
143
145
|
|
|
144
146
|
## Errors
|
|
145
147
|
|
package/dist/react-router.d.ts
CHANGED
|
@@ -5,7 +5,11 @@
|
|
|
5
5
|
* session itself and is not one.
|
|
6
6
|
*/
|
|
7
7
|
export interface SessionClient<S> {
|
|
8
|
-
getSession(
|
|
8
|
+
getSession(options?: {
|
|
9
|
+
fetchOptions?: {
|
|
10
|
+
signal?: AbortSignal;
|
|
11
|
+
};
|
|
12
|
+
}): Promise<{
|
|
9
13
|
data: S | null;
|
|
10
14
|
error: {
|
|
11
15
|
status: number;
|
|
@@ -46,6 +50,8 @@ export declare class AuthenticationUnavailableError extends Error {
|
|
|
46
50
|
* `signIn` with the page as the return path, and, with `twoFactorSetup`, a
|
|
47
51
|
* user who never turned two-factor on is sent there. Both throw React
|
|
48
52
|
* Router's `replace()`, so the back button skips the page that redirected.
|
|
53
|
+
* The read follows `request.signal`: when React Router aborts the request,
|
|
54
|
+
* the abort is thrown as it is, neither "no session" nor unavailable.
|
|
49
55
|
*/
|
|
50
56
|
export declare function requireSession<S extends {
|
|
51
57
|
user: object;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"react-router.d.ts","sourceRoot":"","sources":["../src/react-router.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,UAAU,
|
|
1
|
+
{"version":3,"file":"react-router.d.ts","sourceRoot":"","sources":["../src/react-router.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,UAAU,CAAC,OAAO,CAAC,EAAE;QACnB,YAAY,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,WAAW,CAAA;SAAE,CAAC;KACzC,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CACnE;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,IAAI;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,CAAC,kBAAkB,SAAS,MAAM,CAAC,CAAC,MAAM,CAAC,GAC3C;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,wDAAwD;AACxD,eAAO,MAAM,WAAW,eAAe,CAAC;AAIxC;;;GAGG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;gBAC3C,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE;CAIxC;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAC7D,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,CAAC,CAAC,CA8BZ;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC7B,OAAO,EAAE,mBAAmB,GAC3B,MAAM,CAIR"}
|
package/dist/react-router.js
CHANGED
|
@@ -17,13 +17,20 @@ export class AuthenticationUnavailableError extends Error {
|
|
|
17
17
|
* `signIn` with the page as the return path, and, with `twoFactorSetup`, a
|
|
18
18
|
* user who never turned two-factor on is sent there. Both throw React
|
|
19
19
|
* Router's `replace()`, so the back button skips the page that redirected.
|
|
20
|
+
* The read follows `request.signal`: when React Router aborts the request,
|
|
21
|
+
* the abort is thrown as it is, neither "no session" nor unavailable.
|
|
20
22
|
*/
|
|
21
23
|
export async function requireSession(client, request, options) {
|
|
22
24
|
let result;
|
|
23
25
|
try {
|
|
24
|
-
result = await client.getSession(
|
|
26
|
+
result = await client.getSession({
|
|
27
|
+
fetchOptions: { signal: request.signal },
|
|
28
|
+
});
|
|
25
29
|
}
|
|
26
30
|
catch (cause) {
|
|
31
|
+
// React Router ignores what a request it aborted throws.
|
|
32
|
+
if (request.signal.aborted)
|
|
33
|
+
throw cause;
|
|
27
34
|
throw new AuthenticationUnavailableError({ cause });
|
|
28
35
|
}
|
|
29
36
|
if (result.error !== null)
|
package/dist/react-router.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"react-router.js","sourceRoot":"","sources":["../src/react-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;
|
|
1
|
+
{"version":3,"file":"react-router.js","sourceRoot":"","sources":["../src/react-router.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/authentication",
|
|
3
|
-
"version": "0.8.
|
|
3
|
+
"version": "0.8.37",
|
|
4
4
|
"description": "The better-auth session at the edges of an app: a Hono middleware that refuses a request without a session or without two-factor, and a React Router loader guard that sends a visitor to sign in and back on a safe return path.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|