@aiquants/auth-react-router 0.32.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 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,
@@ -228,6 +232,49 @@ export default () => <AuthUserAdminAppView basePath="/users" />
228
232
  deep-link note are rows of the vertical stack outside the wrapping row, so they span the whole width in both
229
233
  arrangements. Long addresses wrap inside a member row.
230
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
+
231
278
  ### Colour scheme
232
279
 
233
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
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 };