@aiquants/auth-react-router 0.31.0 → 0.33.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -3
- package/dist/admin.d.mts +35 -1
- package/dist/admin.d.ts +35 -1
- package/dist/admin.js +1 -1
- package/dist/admin.mjs +1 -1
- package/package.json +5 -3
package/README.md
CHANGED
|
@@ -8,7 +8,8 @@ React Router v7 auth adapter for [`@aiquants/auth-core`](../auth-core/): Google
|
|
|
8
8
|
pnpm add @aiquants/auth-core @aiquants/auth-react-router
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
Peers: `react`, `react-router@^7`, `remix-auth@^4`, `remix-auth-oauth2@^3`, `react-icons
|
|
11
|
+
Peers: `react`, `react-router@^7`, `remix-auth@^4`, `remix-auth-oauth2@^3`, `react-icons`, `@aiquants/console-ui@^0.6.0`
|
|
12
|
+
(the admin console reads every colour from it, the values of `@aiquants/console-ui/core`, and needs none of its stylesheets).
|
|
12
13
|
|
|
13
14
|
## User admin shell: the self-permission badge
|
|
14
15
|
|
|
@@ -156,6 +157,7 @@ import { createUserAdminApp, jaUserAdminLabels } from "@aiquants/auth-react-rout
|
|
|
156
157
|
|
|
157
158
|
export const userAdminApp = createUserAdminApp({
|
|
158
159
|
store: myUserAdminStore, // you implement UserAdminStore against your DB
|
|
160
|
+
fieldLimits: myFieldLimits, // REQUIRED — the widths of the columns your store writes; see "Field limits" below
|
|
159
161
|
labels: jaUserAdminLabels, // optional; package default is English
|
|
160
162
|
guards: { // REQUIRED — see below
|
|
161
163
|
requireAccess: async (request, { action }) => {
|
|
@@ -183,7 +185,10 @@ export default () => <AuthUserAdminAppView basePath="/users" />
|
|
|
183
185
|
- **`guards` is mandatory** — this surface lists every user and mutates group membership, so an unguarded mount is an account-enumeration and privilege-escalation path. Allow by returning, deny by throwing (`Response` / `redirect` / `Error`); the return value is `void` by contract, so a predicate-style guard that returns `false` cannot silently fail open.
|
|
184
186
|
- **Per-operation authorization**: the guard receives the CRUD verb each intent actually performs (`read` / `create` / `update` / `delete`), so a principal holding only `update` cannot delete. Membership add/remove map to `create`/`delete` because they add and remove rows.
|
|
185
187
|
- Unknown intents reach neither the guard nor the store (the intent table is a `Map`, so prototype keys such as `constructor` do not resolve).
|
|
186
|
-
- Store errors (e.g. "cannot remove the last administrator") are returned as `{ ok: false, error }` and rendered by the
|
|
188
|
+
- Store errors (e.g. "cannot remove the last administrator") are returned as `{ ok: false, error }` and rendered by the
|
|
189
|
+
views — with their own text only when the store declares them operator-facing (`UserAdminOperatorError`, or
|
|
190
|
+
`operatorFacing: true` on the error). Anything else is logged and answered with `labels.errors.unexpected`; see
|
|
191
|
+
"Upstream group catalog" below for why.
|
|
187
192
|
- **Denials (`status: 403`) never surface as a 500.** A thrown value whose `status` is `403` is a denial, recognised by
|
|
188
193
|
that HTTP vocabulary alone (no authorization library is imported):
|
|
189
194
|
- the **loader** answers a denial that is not a `Response` with a 403 route error response,
|
|
@@ -227,12 +232,56 @@ export default () => <AuthUserAdminAppView basePath="/users" />
|
|
|
227
232
|
deep-link note are rows of the vertical stack outside the wrapping row, so they span the whole width in both
|
|
228
233
|
arrangements. Long addresses wrap inside a member row.
|
|
229
234
|
|
|
235
|
+
### Field limits and duplicate group keys: checked before the store
|
|
236
|
+
|
|
237
|
+
```ts
|
|
238
|
+
createUserAdminApp({
|
|
239
|
+
store, guards,
|
|
240
|
+
// REQUIRED — the longest value each free-text field may hold: the width of the column your store writes it to.
|
|
241
|
+
// `widthOf` stands for your own helper that reads a column's declared length and throws when it has none.
|
|
242
|
+
fieldLimits: {
|
|
243
|
+
user: { displayName: widthOf(users.displayName), email: widthOf(users.email) },
|
|
244
|
+
group: { groupKey: widthOf(groups.groupKey), name: widthOf(groups.name), description: widthOf(groups.description) },
|
|
245
|
+
allowlist: { pattern: widthOf(allowlist.pattern), description: widthOf(allowlist.description) },
|
|
246
|
+
allowlistGroup: { description: widthOf(allowlistGroups.description) },
|
|
247
|
+
link: { externalId: widthOf(groupLinks.externalId), externalKey: widthOf(groupLinks.externalKey) },
|
|
248
|
+
},
|
|
249
|
+
})
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
A value the store cannot hold, or a group key another group already uses, fails inside the store as a driver
|
|
253
|
+
exception. That exception is not operator-facing, so the operator would read only "The operation failed" — without the
|
|
254
|
+
field, the length, or the group in the way. The action therefore checks both before it calls the store.
|
|
255
|
+
|
|
256
|
+
- **There are no default limits.** The package cannot know your columns; a guessed default would let an over-long
|
|
257
|
+
value through on a narrower column, where the store's truncation error (SQL Server's Msg 2628) turns back into the
|
|
258
|
+
generic sentence. The limits are validated once, when the app is built: a missing value or one that is not a
|
|
259
|
+
positive integer throws a `TypeError` naming the field (`fieldLimits.group.name must be a positive integer, …`).
|
|
260
|
+
- **Lengths are UTF-16 code units** (`string.length`), the unit of HTML's `maxlength` and of SQL Server's
|
|
261
|
+
`nvarchar(n)`, measured after trimming. An over-long value is refused with `errors.tooLong`, naming the field, the
|
|
262
|
+
length and the limit. The stable upstream id is measured as resolved from the catalog, since that is the value stored.
|
|
263
|
+
- **The loader returns the limits** (`fieldLimits`), and the views put them on the fields as `maxlength`. `maxlength`
|
|
264
|
+
stops typing, not values the page fills in: the create-group dialog also measures the name and the description it
|
|
265
|
+
filled from an upstream group, and shows the length and the limit under the field instead of truncating silently.
|
|
266
|
+
- **Group keys are compared with `normalizeGroupKey`** (trimmed, NFKC, lower case), the same rule on the server and in
|
|
267
|
+
the dialog, because a typical unique index compares case- and width-insensitively (SQL Server's `_CI_` collations).
|
|
268
|
+
`createGroup` and `createLinkedGroup` name the group holding the key (`errors.groupKeyTaken`); the dialog checks on
|
|
269
|
+
every keystroke and pick and keeps "Create" disabled while a field has a problem.
|
|
270
|
+
- **Creating from an upstream group whose key an unlinked local group holds** offers to link that local group itself
|
|
271
|
+
(`data-testid="link-existing-group"`), with the same confirmation as the directory tab — usually what the operator
|
|
272
|
+
wants, instead of a second group for the same department under another key.
|
|
273
|
+
- **`linkDirectoryGroup` checks its target**: a group the store does not list is refused as an invalid group field,
|
|
274
|
+
and a group already linked with `errors.groupAlreadyLinked`, naming the address it is linked to.
|
|
275
|
+
- The checks do not replace the unique index: a key created between the check and the write still fails, with the
|
|
276
|
+
generic sentence.
|
|
277
|
+
|
|
230
278
|
### Colour scheme
|
|
231
279
|
|
|
232
280
|
Every colour the console draws is a pair of a light value and a dark value written as CSS `light-dark()`, so it follows
|
|
233
281
|
the `color-scheme` the host sets on an ancestor: `color-scheme: dark` (on `html.dark`, for example) shows the dark
|
|
234
282
|
values, and a page that sets none keeps the light ones. The package reads neither a `.dark` class nor
|
|
235
|
-
`prefers-color-scheme`, and it declares no colour property for a host to bind.
|
|
283
|
+
`prefers-color-scheme`, and it declares no colour property for a host to bind. The values are `@aiquants/console-ui`'s
|
|
284
|
+
tokens and tone table, so the console and a console built on console-ui draw the same colours.
|
|
236
285
|
|
|
237
286
|
The shell (`AuthUserAdminAppView`, or `UserAdminShell` around your own views) is the console's colour root: it paints
|
|
238
287
|
the console's surface and text, every button, field and select carries its own palette text and surface, and every link
|
package/dist/admin.d.mts
CHANGED
|
@@ -25,6 +25,9 @@ type UserAdminLabels = {
|
|
|
25
25
|
errors: {
|
|
26
26
|
unknownUpstream: string;
|
|
27
27
|
alreadyLinked: string;
|
|
28
|
+
tooLong: string;
|
|
29
|
+
groupKeyTaken: string;
|
|
30
|
+
groupAlreadyLinked: string;
|
|
28
31
|
directoryDisabled: string;
|
|
29
32
|
invalidField: string;
|
|
30
33
|
unknownIntent: string;
|
|
@@ -98,6 +101,11 @@ type UserAdminLabels = {
|
|
|
98
101
|
unknown: string;
|
|
99
102
|
};
|
|
100
103
|
createUpstreamNotice: string;
|
|
104
|
+
fieldTooLong: string;
|
|
105
|
+
keyTaken: string;
|
|
106
|
+
keyTakenByLocal: string;
|
|
107
|
+
linkExistingGroup: string;
|
|
108
|
+
resolveFieldProblems: string;
|
|
101
109
|
openMembers: string;
|
|
102
110
|
openMembersAria: string;
|
|
103
111
|
title: string;
|
|
@@ -289,6 +297,7 @@ declare function createInMemoryUserAdminStore(initial?: {
|
|
|
289
297
|
allowlist?: AuthAllowlistEntry[];
|
|
290
298
|
}): UserAdminStore;
|
|
291
299
|
declare function normalizeUpstreamKey(key: string): string;
|
|
300
|
+
declare function normalizeGroupKey(key: string): string;
|
|
292
301
|
declare class UserAdminOperatorError extends Error {
|
|
293
302
|
readonly operatorFacing = true;
|
|
294
303
|
constructor(message: string);
|
|
@@ -336,8 +345,31 @@ type UserAdminPermission = {
|
|
|
336
345
|
canWrite: boolean;
|
|
337
346
|
canDelete: boolean;
|
|
338
347
|
};
|
|
348
|
+
type UserAdminFieldLimits = {
|
|
349
|
+
user: {
|
|
350
|
+
displayName: number;
|
|
351
|
+
email: number;
|
|
352
|
+
};
|
|
353
|
+
group: {
|
|
354
|
+
groupKey: number;
|
|
355
|
+
name: number;
|
|
356
|
+
description: number;
|
|
357
|
+
};
|
|
358
|
+
allowlist: {
|
|
359
|
+
pattern: number;
|
|
360
|
+
description: number;
|
|
361
|
+
};
|
|
362
|
+
allowlistGroup: {
|
|
363
|
+
description: number;
|
|
364
|
+
};
|
|
365
|
+
link: {
|
|
366
|
+
externalId: number;
|
|
367
|
+
externalKey: number;
|
|
368
|
+
};
|
|
369
|
+
};
|
|
339
370
|
type UserAdminAppConfig = {
|
|
340
371
|
store: UserAdminStore;
|
|
372
|
+
fieldLimits: UserAdminFieldLimits;
|
|
341
373
|
labels?: PartialUserAdminLabels;
|
|
342
374
|
guards: UserAdminGuards;
|
|
343
375
|
resolveActor?: (request: Request) => Promise<string> | string;
|
|
@@ -358,6 +390,7 @@ declare function createUserAdminApp(config: UserAdminAppConfig): {
|
|
|
358
390
|
directoryStatus: AuthDirectoryStatus;
|
|
359
391
|
myPermissions: Record<string, UserAdminPermission | undefined> | null;
|
|
360
392
|
catalog: UserAdminCatalog;
|
|
393
|
+
fieldLimits: UserAdminFieldLimits;
|
|
361
394
|
labels: UserAdminLabels;
|
|
362
395
|
}>;
|
|
363
396
|
action: ({ request }: RouteArgs) => Promise<react_router.UNSAFE_DataWithResponseInit<{
|
|
@@ -397,6 +430,7 @@ type UserAdminLoaderData = {
|
|
|
397
430
|
allowlist: AuthAllowlistEntry[];
|
|
398
431
|
directoryStatus: AuthDirectoryStatus;
|
|
399
432
|
catalog: UserAdminCatalog;
|
|
433
|
+
fieldLimits: UserAdminFieldLimits;
|
|
400
434
|
labels?: UserAdminLabels;
|
|
401
435
|
};
|
|
402
436
|
declare function UsersView(): React__default.JSX.Element;
|
|
@@ -406,4 +440,4 @@ declare function AllowlistView(): React__default.JSX.Element;
|
|
|
406
440
|
declare function DirectoryView(): React__default.JSX.Element;
|
|
407
441
|
type AuthUserAdminAppViewProps = UserAdminShellProps;
|
|
408
442
|
declare function AuthUserAdminAppView({ renderHeader, pendingSyncPolling, basePath }: AuthUserAdminAppViewProps): React__default.JSX.Element;
|
|
409
|
-
export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DEFAULT_PENDING_SYNC_POLLING, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type PendingSyncPolling, type UserAdminAccess, type UserAdminAppConfig, type UserAdminCatalog, type UserAdminCatalogFailure, type UserAdminCatalogGroup, type UserAdminCatalogSnapshot, type UserAdminGuards, UserAdminInputError, type UserAdminLabels, type UserAdminLinkSyncOutcome, type UserAdminLoaderData, type UserAdminLocale, UserAdminOperatorError, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, type UserAdminSyncRequestOutcome, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, normalizeUpstreamKey, resolveUserAdminLabels, userAdminAccessFor, userAdminIntents };
|
|
443
|
+
export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DEFAULT_PENDING_SYNC_POLLING, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type PendingSyncPolling, type UserAdminAccess, type UserAdminAppConfig, type UserAdminCatalog, type UserAdminCatalogFailure, type UserAdminCatalogGroup, type UserAdminCatalogSnapshot, type UserAdminFieldLimits, type UserAdminGuards, UserAdminInputError, type UserAdminLabels, type UserAdminLinkSyncOutcome, type UserAdminLoaderData, type UserAdminLocale, UserAdminOperatorError, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, type UserAdminSyncRequestOutcome, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, normalizeGroupKey, normalizeUpstreamKey, resolveUserAdminLabels, userAdminAccessFor, userAdminIntents };
|
package/dist/admin.d.ts
CHANGED
|
@@ -25,6 +25,9 @@ type UserAdminLabels = {
|
|
|
25
25
|
errors: {
|
|
26
26
|
unknownUpstream: string;
|
|
27
27
|
alreadyLinked: string;
|
|
28
|
+
tooLong: string;
|
|
29
|
+
groupKeyTaken: string;
|
|
30
|
+
groupAlreadyLinked: string;
|
|
28
31
|
directoryDisabled: string;
|
|
29
32
|
invalidField: string;
|
|
30
33
|
unknownIntent: string;
|
|
@@ -98,6 +101,11 @@ type UserAdminLabels = {
|
|
|
98
101
|
unknown: string;
|
|
99
102
|
};
|
|
100
103
|
createUpstreamNotice: string;
|
|
104
|
+
fieldTooLong: string;
|
|
105
|
+
keyTaken: string;
|
|
106
|
+
keyTakenByLocal: string;
|
|
107
|
+
linkExistingGroup: string;
|
|
108
|
+
resolveFieldProblems: string;
|
|
101
109
|
openMembers: string;
|
|
102
110
|
openMembersAria: string;
|
|
103
111
|
title: string;
|
|
@@ -289,6 +297,7 @@ declare function createInMemoryUserAdminStore(initial?: {
|
|
|
289
297
|
allowlist?: AuthAllowlistEntry[];
|
|
290
298
|
}): UserAdminStore;
|
|
291
299
|
declare function normalizeUpstreamKey(key: string): string;
|
|
300
|
+
declare function normalizeGroupKey(key: string): string;
|
|
292
301
|
declare class UserAdminOperatorError extends Error {
|
|
293
302
|
readonly operatorFacing = true;
|
|
294
303
|
constructor(message: string);
|
|
@@ -336,8 +345,31 @@ type UserAdminPermission = {
|
|
|
336
345
|
canWrite: boolean;
|
|
337
346
|
canDelete: boolean;
|
|
338
347
|
};
|
|
348
|
+
type UserAdminFieldLimits = {
|
|
349
|
+
user: {
|
|
350
|
+
displayName: number;
|
|
351
|
+
email: number;
|
|
352
|
+
};
|
|
353
|
+
group: {
|
|
354
|
+
groupKey: number;
|
|
355
|
+
name: number;
|
|
356
|
+
description: number;
|
|
357
|
+
};
|
|
358
|
+
allowlist: {
|
|
359
|
+
pattern: number;
|
|
360
|
+
description: number;
|
|
361
|
+
};
|
|
362
|
+
allowlistGroup: {
|
|
363
|
+
description: number;
|
|
364
|
+
};
|
|
365
|
+
link: {
|
|
366
|
+
externalId: number;
|
|
367
|
+
externalKey: number;
|
|
368
|
+
};
|
|
369
|
+
};
|
|
339
370
|
type UserAdminAppConfig = {
|
|
340
371
|
store: UserAdminStore;
|
|
372
|
+
fieldLimits: UserAdminFieldLimits;
|
|
341
373
|
labels?: PartialUserAdminLabels;
|
|
342
374
|
guards: UserAdminGuards;
|
|
343
375
|
resolveActor?: (request: Request) => Promise<string> | string;
|
|
@@ -358,6 +390,7 @@ declare function createUserAdminApp(config: UserAdminAppConfig): {
|
|
|
358
390
|
directoryStatus: AuthDirectoryStatus;
|
|
359
391
|
myPermissions: Record<string, UserAdminPermission | undefined> | null;
|
|
360
392
|
catalog: UserAdminCatalog;
|
|
393
|
+
fieldLimits: UserAdminFieldLimits;
|
|
361
394
|
labels: UserAdminLabels;
|
|
362
395
|
}>;
|
|
363
396
|
action: ({ request }: RouteArgs) => Promise<react_router.UNSAFE_DataWithResponseInit<{
|
|
@@ -397,6 +430,7 @@ type UserAdminLoaderData = {
|
|
|
397
430
|
allowlist: AuthAllowlistEntry[];
|
|
398
431
|
directoryStatus: AuthDirectoryStatus;
|
|
399
432
|
catalog: UserAdminCatalog;
|
|
433
|
+
fieldLimits: UserAdminFieldLimits;
|
|
400
434
|
labels?: UserAdminLabels;
|
|
401
435
|
};
|
|
402
436
|
declare function UsersView(): React__default.JSX.Element;
|
|
@@ -406,4 +440,4 @@ declare function AllowlistView(): React__default.JSX.Element;
|
|
|
406
440
|
declare function DirectoryView(): React__default.JSX.Element;
|
|
407
441
|
type AuthUserAdminAppViewProps = UserAdminShellProps;
|
|
408
442
|
declare function AuthUserAdminAppView({ renderHeader, pendingSyncPolling, basePath }: AuthUserAdminAppViewProps): React__default.JSX.Element;
|
|
409
|
-
export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DEFAULT_PENDING_SYNC_POLLING, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type PendingSyncPolling, type UserAdminAccess, type UserAdminAppConfig, type UserAdminCatalog, type UserAdminCatalogFailure, type UserAdminCatalogGroup, type UserAdminCatalogSnapshot, type UserAdminGuards, UserAdminInputError, type UserAdminLabels, type UserAdminLinkSyncOutcome, type UserAdminLoaderData, type UserAdminLocale, UserAdminOperatorError, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, type UserAdminSyncRequestOutcome, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, normalizeUpstreamKey, resolveUserAdminLabels, userAdminAccessFor, userAdminIntents };
|
|
443
|
+
export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DEFAULT_PENDING_SYNC_POLLING, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type PendingSyncPolling, type UserAdminAccess, type UserAdminAppConfig, type UserAdminCatalog, type UserAdminCatalogFailure, type UserAdminCatalogGroup, type UserAdminCatalogSnapshot, type UserAdminFieldLimits, type UserAdminGuards, UserAdminInputError, type UserAdminLabels, type UserAdminLinkSyncOutcome, type UserAdminLoaderData, type UserAdminLocale, UserAdminOperatorError, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, type UserAdminSyncRequestOutcome, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, normalizeGroupKey, normalizeUpstreamKey, resolveUserAdminLabels, userAdminAccessFor, userAdminIntents };
|