@aiquants/auth-react-router 0.32.0 → 0.34.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 CHANGED
@@ -157,6 +157,7 @@ import { createUserAdminApp, jaUserAdminLabels } from "@aiquants/auth-react-rout
157
157
 
158
158
  export const userAdminApp = createUserAdminApp({
159
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
160
161
  labels: jaUserAdminLabels, // optional; package default is English
161
162
  guards: { // REQUIRED — see below
162
163
  requireAccess: async (request, { action }) => {
@@ -184,7 +185,10 @@ export default () => <AuthUserAdminAppView basePath="/users" />
184
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.
185
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.
186
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).
187
- - Store errors (e.g. "cannot remove the last administrator") are returned as `{ ok: false, error }` and rendered by the views.
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.
188
192
  - **Denials (`status: 403`) never surface as a 500.** A thrown value whose `status` is `403` is a denial, recognised by
189
193
  that HTTP vocabulary alone (no authorization library is imported):
190
194
  - the **loader** answers a denial that is not a `Response` with a 403 route error response,
@@ -208,7 +212,8 @@ export default () => <AuthUserAdminAppView basePath="/users" />
208
212
  never scrolls sideways, even at 400 % zoom (a viewport 320 to 360 CSS px wide).
209
213
  - **Text size**: the names of the row actions, of the links to a group's members and of the pressable "create from"
210
214
  and "members only" labels are set in the `body` step (13 px on a 20 px line), and the permission badge of the header
211
- and its pills in the `caption` step (11 px on a 20 px line); no text of the package is smaller than `caption`. A
215
+ and its pills, and the lead and lines of the upstream members not in a group, in the `caption` step (11 px on a
216
+ 20 px line); no text of the package is smaller than `caption`. A
212
217
  size is always read together with its line height. A one-line name sits inside its 44 px target without changing
213
218
  it; a name that wraps takes 20 px per line (the longer "create from" label wraps to two lines, a 54.8 px box). The
214
219
  sizes are in rem, so they follow the browser's zoom and its root font-size setting. They are read from custom
@@ -219,15 +224,81 @@ export default () => <AuthUserAdminAppView basePath="/users" />
219
224
  | --- | --- | --- |
220
225
  | `--aqau-font-size-body` | `0.8125rem` (13 px) | the names of the controls above |
221
226
  | `--aqau-line-height-body` | `1.25rem` (20 px) | the same controls, together with the size |
222
- | `--aqau-font-size-caption` | `0.6875rem` (11 px) | the permission badge of the header and its pills |
223
- | `--aqau-line-height-caption` | `1.25rem` (20 px) | the same badge and pills, together with the size |
224
-
227
+ | `--aqau-font-size-caption` | `0.6875rem` (11 px) | the permission badge of the header and its pills, the upstream members not in a group |
228
+ | `--aqau-line-height-caption` | `1.25rem` (20 px) | the same badge, pills and members, together with the size |
229
+
230
+ - **Upstream members not in a group are listed by reason**, never as one count under one label: someone who matches
231
+ more than one user, someone whose address belongs to a user linked to another upstream account, someone the next
232
+ synchronization adds, someone deactivated and someone not registered yet are different facts, cleared in different
233
+ ways, and one label is false for some of them. The counts come from the host, in the link's
234
+ `AuthGroupExternalLink.unresolved` (`AuthDirectoryUnresolvedCounts` of `@aiquants/auth-core`; a host on
235
+ `@aiquants/auth-directory-drizzle` reads them from `listLinks` / `unresolvedByGroup`, which count with the
236
+ synchronization's own resolver). The block sits on the group's card in the groups tab and in the group's cell of the
237
+ directory tab — not beside the last sync time, since who is missing is a fact of the group, not of the run:
238
+
239
+ | Reason | Label (`directoryView.*`) | Colour | What the operator does |
240
+ | --- | --- | --- | --- |
241
+ | `ambiguous` | `unresolvedAmbiguousTemplate` | amber | Tidy the users (check) |
242
+ | `claimedByAnother` | `unresolvedClaimedByAnotherTemplate` | amber | Confirm who the person is (check) |
243
+ | `pendingSync` | `unresolvedPendingSyncTemplate` | sky | Wait for the next synchronization |
244
+ | `deactivated` | `unresolvedDeactivatedTemplate` | neutral (muted text) | Nothing, when the deactivation is deliberate |
245
+ | `unregistered` | `unresolvedUnregisteredTemplate` | neutral (muted text) | Nothing: the person joins at their first sign-in |
246
+
247
+ One line per reason that has anyone, in the order of `AUTH_DIRECTORY_UNRESOLVED_REASONS` (the reasons to check
248
+ first); a count that is zero, negative or not a number draws no line, and a group with no line draws no block. The
249
+ lead `directoryView.unresolvedLead` names the list (`<ul role="list" aria-labelledby>`; the role is explicit
250
+ because WebKit drops it from a list drawn without markers). The colour only repeats the text: each reason is a
251
+ sentence of its own, and the ones to check say so. Test hooks: the block is `group-unresolved-<id>` /
252
+ `directory-unresolved-<id>`, each line `<block>-<reason>` with `data-reason="<reason>"`.
225
253
  - **The group-members tab reflows without a media query** (WCAG 2.2 SC 1.4.10): the group list keeps a 240 px basis
226
254
  and the member panel never takes less than half the row, so the two sit side by side from about 518 px
227
255
  (`2 × (240 px + 1.2rem)`) and stack, each at the full width, below it. The heading, the action error and the
228
256
  deep-link note are rows of the vertical stack outside the wrapping row, so they span the whole width in both
229
257
  arrangements. Long addresses wrap inside a member row.
230
258
 
259
+ ### Field limits and duplicate group keys: checked before the store
260
+
261
+ ```ts
262
+ createUserAdminApp({
263
+ store, guards,
264
+ // REQUIRED — the longest value each free-text field may hold: the width of the column your store writes it to.
265
+ // `widthOf` stands for your own helper that reads a column's declared length and throws when it has none.
266
+ fieldLimits: {
267
+ user: { displayName: widthOf(users.displayName), email: widthOf(users.email) },
268
+ group: { groupKey: widthOf(groups.groupKey), name: widthOf(groups.name), description: widthOf(groups.description) },
269
+ allowlist: { pattern: widthOf(allowlist.pattern), description: widthOf(allowlist.description) },
270
+ allowlistGroup: { description: widthOf(allowlistGroups.description) },
271
+ link: { externalId: widthOf(groupLinks.externalId), externalKey: widthOf(groupLinks.externalKey) },
272
+ },
273
+ })
274
+ ```
275
+
276
+ A value the store cannot hold, or a group key another group already uses, fails inside the store as a driver
277
+ exception. That exception is not operator-facing, so the operator would read only "The operation failed" — without the
278
+ field, the length, or the group in the way. The action therefore checks both before it calls the store.
279
+
280
+ - **There are no default limits.** The package cannot know your columns; a guessed default would let an over-long
281
+ value through on a narrower column, where the store's truncation error (SQL Server's Msg 2628) turns back into the
282
+ generic sentence. The limits are validated once, when the app is built: a missing value or one that is not a
283
+ positive integer throws a `TypeError` naming the field (`fieldLimits.group.name must be a positive integer, …`).
284
+ - **Lengths are UTF-16 code units** (`string.length`), the unit of HTML's `maxlength` and of SQL Server's
285
+ `nvarchar(n)`, measured after trimming. An over-long value is refused with `errors.tooLong`, naming the field, the
286
+ length and the limit. The stable upstream id is measured as resolved from the catalog, since that is the value stored.
287
+ - **The loader returns the limits** (`fieldLimits`), and the views put them on the fields as `maxlength`. `maxlength`
288
+ stops typing, not values the page fills in: the create-group dialog also measures the name and the description it
289
+ filled from an upstream group, and shows the length and the limit under the field instead of truncating silently.
290
+ - **Group keys are compared with `normalizeGroupKey`** (trimmed, NFKC, lower case), the same rule on the server and in
291
+ the dialog, because a typical unique index compares case- and width-insensitively (SQL Server's `_CI_` collations).
292
+ `createGroup` and `createLinkedGroup` name the group holding the key (`errors.groupKeyTaken`); the dialog checks on
293
+ every keystroke and pick and keeps "Create" disabled while a field has a problem.
294
+ - **Creating from an upstream group whose key an unlinked local group holds** offers to link that local group itself
295
+ (`data-testid="link-existing-group"`), with the same confirmation as the directory tab — usually what the operator
296
+ wants, instead of a second group for the same department under another key.
297
+ - **`linkDirectoryGroup` checks its target**: a group the store does not list is refused as an invalid group field,
298
+ and a group already linked with `errors.groupAlreadyLinked`, naming the address it is linked to.
299
+ - The checks do not replace the unique index: a key created between the check and the write still fails, with the
300
+ generic sentence.
301
+
231
302
  ### Colour scheme
232
303
 
233
304
  Every colour the console draws is a pair of a light value and a dark value written as CSS `light-dark()`, so it follows
@@ -248,13 +319,13 @@ colours; the annotation the shell hands it carries the palette's.
248
319
  | Tone | Used for |
249
320
  | --- | --- |
250
321
  | emerald | an active user and the activate button, an enabled sync, a member's row, an exact match, an editable permission |
251
- | amber | warnings and notes (the directory sync banner, a queued sync request, an unset provider, a stale or unavailable catalog, unresolved members), a fuzzy match, a domain entry, an unknown permission |
322
+ | amber | warnings and notes (the directory sync banner, a queued sync request, an unset provider, a stale or unavailable catalog, the upstream members not in a group whom someone has to check), a fuzzy match, a domain entry, an unknown permission |
252
323
  | blue | the active tab, the links to a group's members, a read-only permission |
253
324
  | red | errors, the deactivate and remove buttons, an inactive user, a paused sync, a delete-only permission |
254
325
  | indigo | the group key, the chosen "create from" mode, the selected group of the members tab |
255
326
  | violet | a group owned upstream (its badge, marker and notes), a group entry |
256
- | sky | an e-mail entry, the header annotation |
257
- | neutral | text, surfaces, lines, a control's outline, the primary button, no permission |
327
+ | sky | an e-mail entry, the header annotation, the upstream members the next synchronization adds to a group |
328
+ | neutral | text, surfaces, lines, a control's outline, the primary button, no permission, the upstream members not in a group with nothing to do (deactivated, not registered yet) |
258
329
 
259
330
  Each text colour reaches 7:1 and each non-text mark (a control's outline, a tone's accent) 3:1 against every surface
260
331
  the console draws (the neutral surfaces and every tone's tint), in both schemes (WCAG 2.2 AAA, SC 1.4.6 and 1.4.11);
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;
@@ -163,7 +171,12 @@ type UserAdminLabels = {
163
171
  transitiveMode: string;
164
172
  lastSynced: string;
165
173
  neverSynced: string;
166
- unresolvedTemplate: string;
174
+ unresolvedLead: string;
175
+ unresolvedAmbiguousTemplate: string;
176
+ unresolvedClaimedByAnotherTemplate: string;
177
+ unresolvedPendingSyncTemplate: string;
178
+ unresolvedDeactivatedTemplate: string;
179
+ unresolvedUnregisteredTemplate: string;
167
180
  syncPaused: string;
168
181
  syncEnabled: string;
169
182
  syncNow: string;
@@ -289,6 +302,7 @@ declare function createInMemoryUserAdminStore(initial?: {
289
302
  allowlist?: AuthAllowlistEntry[];
290
303
  }): UserAdminStore;
291
304
  declare function normalizeUpstreamKey(key: string): string;
305
+ declare function normalizeGroupKey(key: string): string;
292
306
  declare class UserAdminOperatorError extends Error {
293
307
  readonly operatorFacing = true;
294
308
  constructor(message: string);
@@ -336,8 +350,31 @@ type UserAdminPermission = {
336
350
  canWrite: boolean;
337
351
  canDelete: boolean;
338
352
  };
353
+ type UserAdminFieldLimits = {
354
+ user: {
355
+ displayName: number;
356
+ email: number;
357
+ };
358
+ group: {
359
+ groupKey: number;
360
+ name: number;
361
+ description: number;
362
+ };
363
+ allowlist: {
364
+ pattern: number;
365
+ description: number;
366
+ };
367
+ allowlistGroup: {
368
+ description: number;
369
+ };
370
+ link: {
371
+ externalId: number;
372
+ externalKey: number;
373
+ };
374
+ };
339
375
  type UserAdminAppConfig = {
340
376
  store: UserAdminStore;
377
+ fieldLimits: UserAdminFieldLimits;
341
378
  labels?: PartialUserAdminLabels;
342
379
  guards: UserAdminGuards;
343
380
  resolveActor?: (request: Request) => Promise<string> | string;
@@ -358,6 +395,7 @@ declare function createUserAdminApp(config: UserAdminAppConfig): {
358
395
  directoryStatus: AuthDirectoryStatus;
359
396
  myPermissions: Record<string, UserAdminPermission | undefined> | null;
360
397
  catalog: UserAdminCatalog;
398
+ fieldLimits: UserAdminFieldLimits;
361
399
  labels: UserAdminLabels;
362
400
  }>;
363
401
  action: ({ request }: RouteArgs) => Promise<react_router.UNSAFE_DataWithResponseInit<{
@@ -397,6 +435,7 @@ type UserAdminLoaderData = {
397
435
  allowlist: AuthAllowlistEntry[];
398
436
  directoryStatus: AuthDirectoryStatus;
399
437
  catalog: UserAdminCatalog;
438
+ fieldLimits: UserAdminFieldLimits;
400
439
  labels?: UserAdminLabels;
401
440
  };
402
441
  declare function UsersView(): React__default.JSX.Element;
@@ -406,4 +445,4 @@ declare function AllowlistView(): React__default.JSX.Element;
406
445
  declare function DirectoryView(): React__default.JSX.Element;
407
446
  type AuthUserAdminAppViewProps = UserAdminShellProps;
408
447
  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 };
448
+ 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;
@@ -163,7 +171,12 @@ type UserAdminLabels = {
163
171
  transitiveMode: string;
164
172
  lastSynced: string;
165
173
  neverSynced: string;
166
- unresolvedTemplate: string;
174
+ unresolvedLead: string;
175
+ unresolvedAmbiguousTemplate: string;
176
+ unresolvedClaimedByAnotherTemplate: string;
177
+ unresolvedPendingSyncTemplate: string;
178
+ unresolvedDeactivatedTemplate: string;
179
+ unresolvedUnregisteredTemplate: string;
167
180
  syncPaused: string;
168
181
  syncEnabled: string;
169
182
  syncNow: string;
@@ -289,6 +302,7 @@ declare function createInMemoryUserAdminStore(initial?: {
289
302
  allowlist?: AuthAllowlistEntry[];
290
303
  }): UserAdminStore;
291
304
  declare function normalizeUpstreamKey(key: string): string;
305
+ declare function normalizeGroupKey(key: string): string;
292
306
  declare class UserAdminOperatorError extends Error {
293
307
  readonly operatorFacing = true;
294
308
  constructor(message: string);
@@ -336,8 +350,31 @@ type UserAdminPermission = {
336
350
  canWrite: boolean;
337
351
  canDelete: boolean;
338
352
  };
353
+ type UserAdminFieldLimits = {
354
+ user: {
355
+ displayName: number;
356
+ email: number;
357
+ };
358
+ group: {
359
+ groupKey: number;
360
+ name: number;
361
+ description: number;
362
+ };
363
+ allowlist: {
364
+ pattern: number;
365
+ description: number;
366
+ };
367
+ allowlistGroup: {
368
+ description: number;
369
+ };
370
+ link: {
371
+ externalId: number;
372
+ externalKey: number;
373
+ };
374
+ };
339
375
  type UserAdminAppConfig = {
340
376
  store: UserAdminStore;
377
+ fieldLimits: UserAdminFieldLimits;
341
378
  labels?: PartialUserAdminLabels;
342
379
  guards: UserAdminGuards;
343
380
  resolveActor?: (request: Request) => Promise<string> | string;
@@ -358,6 +395,7 @@ declare function createUserAdminApp(config: UserAdminAppConfig): {
358
395
  directoryStatus: AuthDirectoryStatus;
359
396
  myPermissions: Record<string, UserAdminPermission | undefined> | null;
360
397
  catalog: UserAdminCatalog;
398
+ fieldLimits: UserAdminFieldLimits;
361
399
  labels: UserAdminLabels;
362
400
  }>;
363
401
  action: ({ request }: RouteArgs) => Promise<react_router.UNSAFE_DataWithResponseInit<{
@@ -397,6 +435,7 @@ type UserAdminLoaderData = {
397
435
  allowlist: AuthAllowlistEntry[];
398
436
  directoryStatus: AuthDirectoryStatus;
399
437
  catalog: UserAdminCatalog;
438
+ fieldLimits: UserAdminFieldLimits;
400
439
  labels?: UserAdminLabels;
401
440
  };
402
441
  declare function UsersView(): React__default.JSX.Element;
@@ -406,4 +445,4 @@ declare function AllowlistView(): React__default.JSX.Element;
406
445
  declare function DirectoryView(): React__default.JSX.Element;
407
446
  type AuthUserAdminAppViewProps = UserAdminShellProps;
408
447
  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 };
448
+ 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 };