@gopherium/react-auth 0.9.0 → 0.11.0

package/dist/admin/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { ValidationError } from '../api.js';
 export declare const usersQueryKey: readonly ["users"];
 declare const userSchema: z.ZodObject<{
     id: z.ZodString;
@@ -49,6 +50,21 @@ export declare class SelfRoleError extends Error {
  */
 export declare class LastPrivilegedError extends Error {
 }
+/**
+ * RoleUnknownError is thrown when a write names a role nobody declared.
+ */
+export declare class RoleUnknownError extends ValidationError {
+}
+/**
+ * RoleBeyondReachError is thrown when the actor may not hand out the role or change the account.
+ */
+export declare class RoleBeyondReachError extends Error {
+}
+/**
+ * RoleChangedError is thrown when the account's role changed before the write landed.
+ */
+export declare class RoleChangedError extends Error {
+}
 /**
  * Returns every user account.
  * @param signal - Aborts the in-flight request.

package/dist/admin/index.js

@@ -39,21 +39,79 @@ export class SelfRoleError extends Error {
  */
 export class LastPrivilegedError extends Error {
 }
+/**
+ * RoleUnknownError is thrown when a write names a role nobody declared.
+ */
+export class RoleUnknownError extends ValidationError {
+}
+/**
+ * RoleBeyondReachError is thrown when the actor may not hand out the role or change the account.
+ */
+export class RoleBeyondReachError extends Error {
+}
+/**
+ * RoleChangedError is thrown when the account's role changed before the write landed.
+ */
+export class RoleChangedError extends Error {
+}
 const errorSchema = z.object({ error: z.string(), code: z.string().optional() });
+const roleErrors = new Map([
+    ['role_unknown', RoleUnknownError],
+    ['role_beyond_reach', RoleBeyondReachError],
+]);
+const accountErrors = new Map([
+    ...roleErrors,
+    ['role_changed', RoleChangedError],
+]);
+const roleChangeErrors = new Map([
+    ...accountErrors,
+    ['role_insufficient', RoleRefusedError],
+    ['self_role_refused', SelfRoleError],
+    ['last_privileged_refused', LastPrivilegedError],
+]);
 /**
- * Extracts the backend's explanation from a failed response body.
- * @param response - The failed HTTP response.
+ * Returns the code and message a refused response carries.
+ * @param response - The refused HTTP response.
  * @param fallback - The message to use when the body is unreadable.
- * @returns The message explaining the failure.
+ * @returns The error code, if any, and its message.
  */
-async function errorMessage(response, fallback) {
+async function errorOf(response, fallback) {
     try {
-        return errorSchema.parse(await response.json()).error;
+        const held = errorSchema.parse(await response.json());
+        return { code: held.code, message: held.error };
     }
     catch {
-        return fallback;
+        return { message: fallback };
     }
 }
+/**
+ * Returns the typed error a refused response's code names.
+ * @param refused - The code and message the response carries.
+ * @param errors - The error class each known code maps to.
+ * @returns The typed error, or undefined for any other code.
+ */
+function typedError(refused, errors = roleErrors) {
+    const typed = errors.get(refused.code ?? '');
+    return typed && new typed(refused.message);
+}
+/**
+ * Returns the error a refused account write throws.
+ * @param response - The refused HTTP response.
+ * @param fallback - The message to use when the body is unreadable.
+ * @param write - Names the write in the error for any other status.
+ * @returns The error to throw.
+ */
+async function writeError(response, fallback, write) {
+    const refused = await errorOf(response, fallback);
+    const typed = typedError(refused);
+    if (typed) {
+        return typed;
+    }
+    if (response.status === 422) {
+        return new ValidationError(refused.message);
+    }
+    return new Error(`${write} failed with status ${response.status}`);
+}
 /**
  * Lists the accounts over REST.
  * @param signal - Aborts the in-flight request.
@@ -86,11 +144,8 @@ async function restCreateUser(input) {
     if (response.status === 409) {
         throw new EmailTakenError('email already in use');
     }
-    if (response.status === 422) {
-        throw new ValidationError(await errorMessage(response, __('invalid user details', DOMAIN)));
-    }
     if (!response.ok) {
-        throw new Error(`creating user failed with status ${response.status}`);
+        throw await writeError(response, __('invalid user details', DOMAIN), 'creating user');
     }
     return userSchema.parse(await response.json());
 }
@@ -109,14 +164,11 @@ async function restInvite(input) {
     if (response.status === 401) {
         throw new UnauthorizedError('session expired');
     }
-    if (response.status === 422) {
-        throw new ValidationError(await errorMessage(response, __('invalid invitation details', DOMAIN)));
-    }
     if (response.status === 429) {
         throw new RateLimitedError('too many attempts');
     }
     if (!response.ok) {
-        throw new Error(`inviting failed with status ${response.status}`);
+        throw await writeError(response, __('invalid invitation details', DOMAIN), 'inviting');
     }
     return invitationSchema.parse(await response.json());
 }
@@ -135,7 +187,8 @@ async function restSetUserDisabled(id, disabled) {
         throw new UnauthorizedError('session expired');
     }
     if (!response.ok) {
-        throw new Error(`updating user failed with status ${response.status}`);
+        const refused = await errorOf(response, __('the account could not be updated', DOMAIN));
+        throw typedError(refused, accountErrors) ?? new Error(`updating user failed with status ${response.status}`);
     }
 }
 /**
@@ -155,31 +208,8 @@ async function restSetUserRole(id, role) {
     if (response.status === 401) {
         throw new UnauthorizedError('session expired');
     }
-    const failed = await errorOf(response);
-    if (failed.code === 'role_insufficient') {
-        throw new RoleRefusedError(failed.message);
-    }
-    if (failed.code === 'self_role_refused') {
-        throw new SelfRoleError(failed.message);
-    }
-    if (failed.code === 'last_privileged_refused') {
-        throw new LastPrivilegedError(failed.message);
-    }
-    throw new Error(`updating role failed with status ${response.status}`);
-}
-/**
- * Returns the code and message a refused response carries.
- * @param response - The refused HTTP response.
- * @returns The error code, if any, and its message.
- */
-async function errorOf(response) {
-    try {
-        const held = errorSchema.parse(await response.json());
-        return { code: held.code, message: held.error };
-    }
-    catch {
-        return { message: __('the account could not be updated', DOMAIN) };
-    }
+    const refused = await errorOf(response, __('the account could not be updated', DOMAIN));
+    throw typedError(refused, roleChangeErrors) ?? new Error(`updating role failed with status ${response.status}`);
 }
 /**
  * Returns every user account.

package/dist/api.d.ts

@@ -4,6 +4,8 @@ declare const userSchema: z.ZodObject<{
     email: z.ZodString;
     name: z.ZodString;
     role: z.ZodDefault<z.ZodString>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    grantable: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type User = z.infer<typeof userSchema>;
 /**

package/dist/api.js

@@ -8,6 +8,8 @@ const userSchema = z.object({
     email: z.string(),
     name: z.string(),
     role: z.string().default(''),
+    capabilities: z.array(z.string()).optional(),
+    grantable: z.array(z.string()).optional(),
 });
 /**
  * InvalidCredentialsError is thrown when the backend rejects a login.

package/dist/capabilities.d.ts

@@ -0,0 +1,8 @@
+import type { User } from './api.js';
+/**
+ * Reports whether the user holds the capability, a missing user holding none.
+ * @param user - The signed-in user, if any.
+ * @param capability - The capability asked for.
+ * @returns Whether the user holds the capability.
+ */
+export declare function can(user: User | null | undefined, capability: string): boolean;

package/dist/capabilities.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Reports whether the user holds the capability, a missing user holding none.
+ * @param user - The signed-in user, if any.
+ * @param capability - The capability asked for.
+ * @returns Whether the user holds the capability.
+ */
+export function can(user, capability) {
+    return user?.capabilities?.includes(capability) ?? false;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { InvalidCredentialsError, InvalidTokenError, RateLimitedError, UnauthorizedError, ValidationError, acceptInvite, fetchSession, login, logout, requestPasswordReset, resetPassword, } from './api.js';
 export type { User } from './api.js';
 export { AuthGate } from './AuthGate.js';
+export { can } from './capabilities.js';
 export { DOMAIN } from './domain.js';
 export { catalogFor } from './languages.js';
 export type { Catalog } from './languages.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 export { InvalidCredentialsError, InvalidTokenError, RateLimitedError, UnauthorizedError, ValidationError, acceptInvite, fetchSession, login, logout, requestPasswordReset, resetPassword, } from './api.js';
 export { AuthGate } from './AuthGate.js';
+export { can } from './capabilities.js';
 export { DOMAIN } from './domain.js';
 export { catalogFor } from './languages.js';
 export { isSessionRevoked } from './probe.js';

package/dist/session.d.ts

@@ -13,6 +13,8 @@ export declare function useSession(): import("@tanstack/react-query").UseQueryRe
     email: string;
     name: string;
     role: string;
+    capabilities?: string[] | undefined;
+    grantable?: string[] | undefined;
 } | null>, Error>;
 /**
  * Ends the current session and drops all cached data belonging to the

package/dist/testing/index.d.ts

@@ -17,6 +17,14 @@ export declare const defaultUser: User;
  * @returns The account.
  */
 export declare function userWithRole(role: string): User;
+/**
+ * Returns a canned account holding the role, its capabilities, and the roles it may hand out.
+ * @param role - The role the account holds.
+ * @param capabilities - The capabilities the role carries.
+ * @param grantable - The roles the account may hand out.
+ * @returns The account.
+ */
+export declare function userWithCapabilities(role: string, capabilities: string[], grantable?: string[]): User;
 /**
  * Answers an invitation as mailed.
  * @returns The msw handler.

package/dist/testing/index.js

@@ -46,6 +46,16 @@ export function userWithRole(role) {
         role,
     };
 }
+/**
+ * Returns a canned account holding the role, its capabilities, and the roles it may hand out.
+ * @param role - The role the account holds.
+ * @param capabilities - The capabilities the role carries.
+ * @param grantable - The roles the account may hand out.
+ * @returns The account.
+ */
+export function userWithCapabilities(role, capabilities, grantable = []) {
+    return { ...userWithRole(role), capabilities: [...capabilities], grantable: [...grantable] };
+}
 /**
  * Answers an invitation as mailed.
  * @returns The msw handler.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gopherium/react-auth",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Session authentication for React apps backed by gouncer's authkit.",
   "license": "Apache-2.0",
   "type": "module",
@@ -50,9 +50,9 @@
     "@tanstack/react-query": "^5.101.2",
     "@testing-library/jest-dom": "^6.9.1 || ^7.0.0",
     "@testing-library/react": "^16.3.2",
-    "@wordpress/i18n": ">=6.28.0 <7.0.0",
-    "@wordpress/theme": ">=2.1.0 <3.0.0",
-    "@wordpress/ui": ">=0.22.0 <0.23.0",
+    "@wordpress/i18n": ">=6.29.0 <7.0.0",
+    "@wordpress/theme": ">=2.2.0 <3.0.0",
+    "@wordpress/ui": ">=0.23.0 <0.24.0",
     "msw": "^2.15.0",
     "react": "^19.2.7",
     "vitest": "^4.1.10"
@@ -86,9 +86,9 @@
     "@types/react": "^19.2.17",
     "@vitejs/plugin-react": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
-    "@wordpress/i18n": "6.28.0",
-    "@wordpress/theme": "2.1.0",
-    "@wordpress/ui": "0.22.0",
+    "@wordpress/i18n": "6.29.0",
+    "@wordpress/theme": "2.2.0",
+    "@wordpress/ui": "0.23.0",
     "eslint": "^9.39.1",
     "eslint-plugin-jsdoc": "^63.0.13",
     "eslint-plugin-sonarjs": "^4.2.0",