@aiquants/auth-react-router 0.40.0 → 0.41.1

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 CHANGED
@@ -71,16 +71,18 @@ createAuthServer({
71
71
  ```
72
72
 
73
73
  A page loader hands its guard the page's path and query, so an unauthenticated reader is sent to the sign-in page that
74
- returns here (an action passes `{ failureRedirect: null }` instead and answers 401 data):
74
+ returns here (an action passes `{ failureRedirect: null }` instead and answers 401 data). Build the return-to from the
75
+ loader's `url` argument, React Router's normalized address of the page, never from `request.url`: a client-side
76
+ navigation runs the loader through a single-fetch data request, whose `request.url` ends in `.data` and carries
77
+ `_routes`, and a return-to built from it sends the reader back to that data address after the sign-in:
75
78
 
76
79
  ```ts
77
- export const loader = async ({ request }: LoaderFunctionArgs) => {
78
- const url = new URL(request.url)
79
- const returnTo = url.pathname + url.search
80
+ export const loader = async ({ request, url }: LoaderFunctionArgs) => {
81
+ const returnTo = url.pathname + url.search // the page's address; a data request's request.url ends in .data
80
82
  const { user, cookie } = await authServer.authenticateInLoader(request, { failureRedirect: "/auth/login", returnTo }) // failureRedirect must be loginPath; GET and HEAD only
81
83
  ...
82
84
  }
83
- // requireUser(request, returnTo) and requireAdminUser(request, returnTo) take the same return-to
85
+ // requireUser(request, returnTo) and requireAdminUser(request, returnTo) take the same return-to, built from the loader's url
84
86
  ```
85
87
 
86
88
  ```ts
@@ -179,6 +181,7 @@ assistive technology, so the button's name is its label.
179
181
  A splat-mounted admin UI for users, groups, group members, and the sign-in allowlist — the identity-side counterpart to `@aiquants/authz-react-router`.
180
182
 
181
183
  ```ts
184
+ import { accessFailureResponse } from "@aiquants/auth-core"
182
185
  import { createUserAdminApp, jaUserAdminLabels } from "@aiquants/auth-react-router/admin"
183
186
 
184
187
  export const userAdminApp = createUserAdminApp({
@@ -186,9 +189,10 @@ export const userAdminApp = createUserAdminApp({
186
189
  fieldLimits: myFieldLimits, // REQUIRED — the widths of the columns your store writes; see "Field limits" below
187
190
  labels: jaUserAdminLabels, // optional; package default is English
188
191
  guards: { // REQUIRED — see below
192
+ // Serves the loader and the action alike and receives only the request: it checks without redirecting, and
193
+ // the route below has already sent an unauthenticated reader of the page to the sign-in page
189
194
  requireAccess: async (request, { action }) => {
190
- const url = new URL(request.url)
191
- await requireUser(request, url.pathname + url.search)
195
+ if ((await getSessionUser(request)) === undefined) throw accessFailureResponse("unauthenticated")
192
196
  await requirePermission(request, { resourceKey: "user_admin", action })
193
197
  },
194
198
  },
@@ -196,13 +200,29 @@ export const userAdminApp = createUserAdminApp({
196
200
  ```
197
201
 
198
202
  ```tsx
203
+ import { accessFailureBody } from "@aiquants/auth-core"
199
204
  import { AuthUserAdminAppView } from "@aiquants/auth-react-router/admin"
200
- export const loader = userAdminApp.loader
201
- export const action = userAdminApp.action
205
+ import { type ActionFunctionArgs, data, type LoaderFunctionArgs } from "react-router"
206
+
202
207
  // mounted as the splat route "/users/*"
208
+ export const loader = async (args: LoaderFunctionArgs) => {
209
+ // the page's address (args.url), so the sign-in returns here; a data request's request.url ends in .data
210
+ await authenticateInLoader(args.request, { failureRedirect: "/auth/login", returnTo: args.url.pathname + args.url.search })
211
+ return await userAdminApp.loader(args)
212
+ }
213
+ export const action = async (args: ActionFunctionArgs) => {
214
+ const { user, cookie } = await authenticateInLoader(args.request, { failureRedirect: null })
215
+ // a write is answered in place: the view draws the 401 body through the presenter (place write)
216
+ if (user === undefined) return data(accessFailureBody("unauthenticated"), { status: 401, headers: cookie === undefined ? undefined : { "Set-Cookie": cookie } })
217
+ return await userAdminApp.action(args)
218
+ }
203
219
  export default () => <AuthUserAdminAppView basePath="/users" accessFailure={accessFailurePresenter} />
204
220
  ```
205
221
 
222
+ The guard receives only the request, and a client-side navigation reaches the loader through a single-fetch data request
223
+ whose `request.url` ends in `.data`, so the guard cannot build the page's return-to; the route authenticates the page
224
+ first from the loader's `url`. The guard's own check is reached only by a session that ends between the two checks.
225
+
206
226
  - **`basePath` is required** (`AuthUserAdminAppView` / `UserAdminShell`): the absolute path the console is mounted at,
207
227
  without a trailing slash (`"/users"` for a `/users/*` route). The five tabs and the per-row "members" links of the
208
228
  groups tab are built from it. There is no default: the host decides where the console lives, and a built-in default
@@ -210,8 +230,9 @@ export default () => <AuthUserAdminAppView basePath="/users" accessFailure={acce
210
230
  passes, only the links point at a place that is not served.
211
231
  - **`accessFailure` is required** (`AuthUserAdminAppView` / `UserAdminShell`): the host's access-failure presenter
212
232
  (`AccessFailurePresenter` of `@aiquants/auth-core`), the same one its other screens use, so a denial reads the same
213
- everywhere. The shell's root (`ConsoleUiRoot`) holds it, and the views draw every denied write through it (place
214
- `write`, with `labels.errors.forbidden` as the denied sentence). `ConsoleUiRoot` throws `TypeError` when it is not a
233
+ everywhere. The shell's root (`ConsoleUiRoot`) holds it, and the views draw through it every write the action answers
234
+ with an access-failure body (place `write`): a denied one (403, with `labels.errors.forbidden` as the denied sentence)
235
+ and one from a reader who is not signed in (401). `ConsoleUiRoot` throws `TypeError` when it is not a
215
236
  function.
216
237
  - **Serve the view with `userAdminApp.loader`**: `AuthUserAdminAppView` draws the tab its loader's `segment` names
217
238
  (`users`, `groups`, `group_members`, `allowlist` or `directory`; the package's loader reads any other path below the
@@ -251,15 +272,21 @@ export default () => <AuthUserAdminAppView basePath="/users" accessFailure={acce
251
272
  rendered outside the shell (`UsersView` and the others) sits inside a `ConsoleUiRoot` of the host's: the parts throw
252
273
  outside a root, and a root inside a root throws too. The shell draws no `<main>`: the host decides the page's
253
274
  landmarks and wraps the console in its own.
275
+ - **Header placement**: a header the host draws through `renderHeader` comes first in the shell's root, before and
276
+ outside the page box of formula 1. The shell adds no inset around it, so the band spans the root's full width and
277
+ meets its top, as the host's other screens draw theirs, and the page box's 24 px block padding separates it from the
278
+ tabs. The band stays inside the root because the annotation the shell hands it is built from console parts. Without
279
+ `renderHeader` the shell draws its own heading (`user-admin-header`: an `h1` and the annotation) inside the page box,
280
+ above the tabs.
254
281
  - **Layout by formula, down to a 320 px viewport** (WCAG 2.2 SC 1.4.10): no part of the console scrolls sideways.
255
282
 
256
283
  | Formula | What it decides |
257
284
  | --- | --- |
258
- | 1 content width | The page box (`PAGE_STYLE`, `data-testid="user-admin-page"`) pads `clamp(16px, 4vw, 24px)` on each inline side and has no maximum width, so the content is `C(v) = v − 2·clamp(16, 0.04v, 24)` px wide at a viewport `v`: 288 at 320, 358 at 390, 1392 at 1440. Lines of text keep the console's reading measure. |
285
+ | 1 content width | The page box (`PAGE_STYLE`, `data-testid="user-admin-page"`) holds the tabs and everything below them (and the shell's own heading when the host draws no header), pads `clamp(16px, 4vw, 24px)` on each inline side and has no maximum width, so the content is `C(v) = v − 2·clamp(16, 0.04v, 24)` px wide at a viewport `v`: 288 at 320, 358 at 390, 1392 at 1440. Lines of text keep the console's reading measure. |
259
286
  | 2 tables | Every table (`DataTable`) is one flexible row-header column plus at most one fixed column sized from its closed vocabulary (`fixedColumnPx`: a status pill, an operation's button), so its frame's minimum fits `C(320)` in both catalogs. |
260
287
  | 3 row height | A table whose rows hold a button draws the console's `row-control` rows (52 px); a table of text alone (the members of a group owned upstream) draws `row` rows (44 px). |
261
288
  | 4 tabs | The tabs are links (`Tabs`, collapsible): in a content box narrower than 48rem they fold into one button naming the current tab, whose popup lists every tab. The directory tab is listed while the directory is wired, a group is linked, or it is the current tab. |
262
- | 5 header annotation | Each unit of the annotation the shell hands the header (the permissions lead, each permission pill, the heading badge) fits 180 px on one line in both catalogs; host data (a resource's name) wraps inside its pill. |
289
+ | 5 header annotation | Each unit of the annotation the shell hands the header (the permissions lead, each permission pill, the heading badge) fits 212 px on one line in both catalogs: a host's header band, outside the page box, is 320 px wide at a 320 px viewport and keeps 212 px for the annotation after 108 px of its own chrome (an 8 px inset, 8 px of margins, a 20 px icon and a 72 px reserve for a switch of its own). Host data (a resource's name) wraps inside its pill. |
263
290
  | 6 dialogs | The create and edit dialogs are console-ui's `Dialog`: `calc(40ic + 48px)` wide, never wider than the viewport less 48 px. |
264
291
  | 9 group cards | The groups' cards sit in `repeat(auto-fill, minmax(min(100%, 17.5rem), 1fr))` with a 16 px gap (`GROUP_GRID_STYLE`): a grid `W` px wide holds `⌊(W + 16) / 296⌋` columns (1 at 288, 4 at 1392), and a card shrinks to a grid narrower than 280 px. |
265
292
  | 10 group members | The group-members tab is a `MasterDetail` with 240 px minimums and a 24 px gap: the group list and the member panel sit side by side from a 504 px content box (a 548 px viewport) and stack, each at the full width, below it. The heading, the action error and the deep-link note sit above it at the full width. |