preact-missing-hooks 4.4.0 → 4.5.0

package/src/useRBAC.ts

@@ -0,0 +1,380 @@
+import { useCallback, useEffect, useRef, useState } from "preact/hooks";
+
+/** Flexible user object; your app can use any shape. */
+export type RBACUser = Record<string, unknown>;
+
+/** Get auth state (user + optional roles/capabilities). Used by custom source. */
+export interface RBACAuthState {
+  user?: RBACUser | null;
+  roles?: string[];
+  capabilities?: string[];
+}
+
+/** Pluggable source for current user (and optionally roles/capabilities). */
+export type RBACUserSource =
+  | { type: "localStorage"; key: string }
+  | { type: "sessionStorage"; key: string }
+  | { type: "api"; fetch: () => Promise<RBACUser> }
+  | { type: "memory"; getUser: () => RBACUser | null }
+  | { type: "custom"; getAuth: () => RBACAuthState | Promise<RBACAuthState> };
+
+/** Role definition: name + condition to grant this role based on user. */
+export interface RBACRoleDefinition {
+  role: string;
+  condition: (user: RBACUser | null) => boolean;
+}
+
+/** Role name -> list of capability strings. Use '*' for full access. */
+export type RBACRoleCapabilities = Record<string, string[]>;
+
+/** Optional override: get capabilities directly (e.g. from API) instead of deriving from roles. */
+export type RBACCapabilitiesOverride =
+  | { type: "localStorage"; key: string }
+  | { type: "sessionStorage"; key: string }
+  | { type: "api"; fetch: () => Promise<string[]> };
+
+export interface UseRBACOptions {
+  /** Where to get the current user (and optionally roles/capabilities if type is 'custom'). */
+  userSource: RBACUserSource;
+  /** Role definitions: each role has a condition(user) to determine if the user has that role. */
+  roleDefinitions: RBACRoleDefinition[];
+  /** Capabilities per role. User gets union of capabilities for all their roles. Use '*' for admin. */
+  roleCapabilities: RBACRoleCapabilities;
+  /** Optional: fetch capabilities directly (overrides role-derived capabilities when provided). */
+  capabilitiesOverride?: RBACCapabilitiesOverride;
+}
+
+export interface UseRBACReturn {
+  /** Current user from source, or null. */
+  user: RBACUser | null;
+  /** Resolved roles for the current user. */
+  roles: string[];
+  /** Resolved capabilities (union of role capabilities, or from override). */
+  capabilities: string[];
+  /** True when user/roles/capabilities have been resolved (or failed). */
+  isReady: boolean;
+  /** Error from source (e.g. API or parse). */
+  error: Error | null;
+  /** Check if the user has the given role. */
+  hasRole: (role: string) => boolean;
+  /** Check if the user has the given capability (or '*' ). */
+  hasCapability: (capability: string) => boolean;
+  /** Alias for hasCapability. */
+  can: (capability: string) => boolean;
+  /** Re-fetch user/roles/capabilities from source. */
+  refetch: () => Promise<void>;
+  /** Helpers to persist auth to storage (for frontend-only flows). */
+  setUserInStorage: (
+    user: RBACUser | null,
+    storage: "localStorage" | "sessionStorage",
+    key: string
+  ) => void;
+  setRolesInStorage: (
+    roles: string[],
+    storage: "localStorage" | "sessionStorage",
+    key: string
+  ) => void;
+  setCapabilitiesInStorage: (
+    capabilities: string[],
+    storage: "localStorage" | "sessionStorage",
+    key: string
+  ) => void;
+}
+
+const WILDCARD = "*";
+
+function parseUserFromStorage(
+  type: "localStorage" | "sessionStorage",
+  key: string
+): RBACUser | null {
+  if (typeof window === "undefined") return null;
+  const storage =
+    type === "localStorage" ? window.localStorage : window.sessionStorage;
+  try {
+    const raw = storage.getItem(key);
+    if (raw == null) return null;
+    const data = JSON.parse(raw) as unknown;
+    return data && typeof data === "object" ? (data as RBACUser) : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseCapabilitiesFromStorage(
+  type: "localStorage" | "sessionStorage",
+  key: string
+): string[] {
+  if (typeof window === "undefined") return [];
+  const storage =
+    type === "localStorage" ? window.localStorage : window.sessionStorage;
+  try {
+    const raw = storage.getItem(key);
+    if (raw == null) return [];
+    const data = JSON.parse(raw) as unknown;
+    return Array.isArray(data)
+      ? data.filter((x): x is string => typeof x === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+function computeRoles(
+  user: RBACUser | null,
+  roleDefinitions: RBACRoleDefinition[]
+): string[] {
+  return roleDefinitions
+    .filter((def) => def.condition(user))
+    .map((def) => def.role);
+}
+
+function computeCapabilitiesFromRoles(
+  roles: string[],
+  roleCapabilities: RBACRoleCapabilities
+): string[] {
+  const set = new Set<string>();
+  for (const role of roles) {
+    const caps = roleCapabilities[role];
+    if (Array.isArray(caps)) {
+      for (const c of caps) set.add(c);
+    }
+  }
+  return Array.from(set);
+}
+
+function hasCapabilityImpl(
+  capabilities: string[],
+  capability: string
+): boolean {
+  if (capabilities.includes(WILDCARD)) return true;
+  return capabilities.includes(capability);
+}
+
+/**
+ * Frontend-only role-based access control hook. Define roles with conditions,
+ * assign capabilities per role, and plug in user source (localStorage, sessionStorage, API, or custom).
+ * Supports full flexibility: frontend-only with storage or pluggable API.
+ *
+ * @param options - userSource, roleDefinitions, roleCapabilities, optional capabilitiesOverride
+ * @returns user, roles, capabilities, hasRole, hasCapability, can, isReady, error, refetch, and storage helpers
+ *
+ * @example
+ * ```tsx
+ * const { hasRole, can, roles, setUserInStorage } = useRBAC({
+ *   userSource: { type: 'localStorage', key: 'user' },
+ *   roleDefinitions: [
+ *     { role: 'admin', condition: (u) => u?.role === 'admin' },
+ *     { role: 'editor', condition: (u) => u?.role === 'editor' || u?.role === 'admin' },
+ *   ],
+ *   roleCapabilities: {
+ *     admin: ['*'],
+ *     editor: ['posts:edit', 'posts:create'],
+ *   },
+ * });
+ * if (can('posts:edit')) { ... }
+ * ```
+ */
+export function useRBAC(options: UseRBACOptions): UseRBACReturn {
+  const { userSource } = options;
+
+  const optsRef = useRef(options);
+  optsRef.current = options;
+
+  const [user, setUser] = useState<RBACUser | null>(null);
+  const [roles, setRoles] = useState<string[]>([]);
+  const [capabilities, setCapabilities] = useState<string[]>([]);
+  const [isReady, setIsReady] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const resolveAuth = useCallback(async () => {
+    const {
+      userSource: us,
+      roleDefinitions: rdefs,
+      roleCapabilities: rcaps,
+      capabilitiesOverride: capOver,
+    } = optsRef.current;
+    setError(null);
+    let resolvedUser: RBACUser | null = null;
+    let resolvedRoles: string[] = [];
+    let resolvedCapabilities: string[] = [];
+
+    try {
+      if (us.type === "localStorage") {
+        resolvedUser = parseUserFromStorage("localStorage", us.key);
+        resolvedRoles = computeRoles(resolvedUser, rdefs);
+        resolvedCapabilities = computeCapabilitiesFromRoles(
+          resolvedRoles,
+          rcaps
+        );
+      } else if (us.type === "sessionStorage") {
+        resolvedUser = parseUserFromStorage("sessionStorage", us.key);
+        resolvedRoles = computeRoles(resolvedUser, rdefs);
+        resolvedCapabilities = computeCapabilitiesFromRoles(
+          resolvedRoles,
+          rcaps
+        );
+      } else if (us.type === "api") {
+        resolvedUser = await us.fetch();
+        resolvedRoles = computeRoles(resolvedUser, rdefs);
+        resolvedCapabilities = computeCapabilitiesFromRoles(
+          resolvedRoles,
+          rcaps
+        );
+      } else if (us.type === "memory") {
+        resolvedUser = us.getUser();
+        resolvedRoles = computeRoles(resolvedUser, rdefs);
+        resolvedCapabilities = computeCapabilitiesFromRoles(
+          resolvedRoles,
+          rcaps
+        );
+      } else if (us.type === "custom") {
+        const auth = await Promise.resolve(us.getAuth());
+        resolvedUser = auth.user ?? null;
+        resolvedRoles = auth.roles ?? computeRoles(resolvedUser, rdefs);
+        resolvedCapabilities =
+          auth.capabilities ??
+          computeCapabilitiesFromRoles(resolvedRoles, rcaps);
+      }
+
+      if (capOver) {
+        if (capOver.type === "localStorage") {
+          const override = parseCapabilitiesFromStorage(
+            "localStorage",
+            capOver.key
+          );
+          if (override.length > 0) resolvedCapabilities = override;
+        } else if (capOver.type === "sessionStorage") {
+          const override = parseCapabilitiesFromStorage(
+            "sessionStorage",
+            capOver.key
+          );
+          if (override.length > 0) resolvedCapabilities = override;
+        } else if (capOver.type === "api") {
+          const override = await capOver.fetch();
+          resolvedCapabilities = override;
+        }
+      }
+
+      setUser(resolvedUser);
+      setRoles(resolvedRoles);
+      setCapabilities(resolvedCapabilities);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setUser(null);
+      setRoles([]);
+      setCapabilities([]);
+    } finally {
+      setIsReady(true);
+    }
+  }, []);
+
+  useEffect(() => {
+    resolveAuth();
+  }, [resolveAuth]);
+
+  // Listen to storage events when using localStorage/sessionStorage so we refetch when another tab changes data
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const key =
+      userSource.type === "localStorage" || userSource.type === "sessionStorage"
+        ? userSource.key
+        : null;
+    if (!key) return;
+    const handler = (e: StorageEvent) => {
+      if (e.key === key) void resolveAuth();
+    };
+    window.addEventListener("storage", handler);
+    return () => window.removeEventListener("storage", handler);
+  }, [
+    userSource.type,
+    userSource.type === "localStorage" || userSource.type === "sessionStorage"
+      ? (userSource as { key: string }).key
+      : "",
+    resolveAuth,
+  ]);
+
+  const hasRole = useCallback((role: string) => roles.includes(role), [roles]);
+
+  const hasCapability = useCallback(
+    (capability: string) => hasCapabilityImpl(capabilities, capability),
+    [capabilities]
+  );
+
+  const can = hasCapability;
+
+  const refetch = useCallback(() => resolveAuth(), [resolveAuth]);
+
+  const setUserInStorage = useCallback(
+    (
+      newUser: RBACUser | null,
+      storage: "localStorage" | "sessionStorage",
+      key: string
+    ) => {
+      if (typeof window === "undefined") return;
+      const s =
+        storage === "localStorage"
+          ? window.localStorage
+          : window.sessionStorage;
+      if (newUser == null) s.removeItem(key);
+      else s.setItem(key, JSON.stringify(newUser));
+      if (
+        (userSource.type === "localStorage" &&
+          storage === "localStorage" &&
+          userSource.key === key) ||
+        (userSource.type === "sessionStorage" &&
+          storage === "sessionStorage" &&
+          userSource.key === key)
+      ) {
+        void resolveAuth();
+      }
+    },
+    [userSource, resolveAuth]
+  );
+
+  const setRolesInStorage = useCallback(
+    (
+      newRoles: string[],
+      storage: "localStorage" | "sessionStorage",
+      key: string
+    ) => {
+      if (typeof window === "undefined") return;
+      const s =
+        storage === "localStorage"
+          ? window.localStorage
+          : window.sessionStorage;
+      s.setItem(key, JSON.stringify(newRoles));
+    },
+    []
+  );
+
+  const setCapabilitiesInStorage = useCallback(
+    (
+      newCaps: string[],
+      storage: "localStorage" | "sessionStorage",
+      key: string
+    ) => {
+      if (typeof window === "undefined") return;
+      const s =
+        storage === "localStorage"
+          ? window.localStorage
+          : window.sessionStorage;
+      s.setItem(key, JSON.stringify(newCaps));
+    },
+    []
+  );
+
+  return {
+    user,
+    roles,
+    capabilities,
+    isReady,
+    error,
+    hasRole,
+    hasCapability,
+    can,
+    refetch,
+    setUserInStorage,
+    setRolesInStorage,
+    setCapabilitiesInStorage,
+  };
+}

package/tests/useRBAC.test.tsx

@@ -0,0 +1,212 @@
+/** @jsx h */
+import { h } from "preact";
+import { useRef } from "preact/hooks";
+import { render, fireEvent, waitFor } from "@testing-library/preact";
+import { useRBAC } from "../src/useRBAC";
+import { vi } from "vitest";
+
+const STORAGE_KEY = "rbac-test-user";
+const ROLE_DEFS = [
+  { role: "admin", condition: (u: Record<string, unknown> | null) => u?.role === "admin" },
+  { role: "editor", condition: (u: Record<string, unknown> | null) => u?.role === "editor" || u?.role === "admin" },
+  { role: "viewer", condition: (u: Record<string, unknown> | null) => !!u?.id },
+];
+const ROLE_CAPS: Record<string, string[]> = {
+  admin: ["*"],
+  editor: ["posts:edit", "posts:create", "posts:read"],
+  viewer: ["posts:read"],
+};
+
+describe("useRBAC", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    sessionStorage.clear();
+  });
+
+  it("returns isReady, user, roles, capabilities, hasRole, can, refetch", async () => {
+    function TestComponent() {
+      const rbac = useRBAC({
+        userSource: { type: "localStorage", key: STORAGE_KEY },
+        roleDefinitions: ROLE_DEFS,
+        roleCapabilities: ROLE_CAPS,
+      });
+      return h("div", {},
+        h("span", { "data-testid": "ready" }, String(rbac.isReady)),
+        h("span", { "data-testid": "roles" }, rbac.roles.join(",")),
+        h("span", { "data-testid": "caps" }, rbac.capabilities.join(",")),
+        h("button", { onClick: rbac.refetch }, "Refetch"),
+      );
+    }
+    const { getByTestId, getByText } = render(h(TestComponent));
+    await waitFor(() => expect(getByTestId("ready").textContent).toBe("true"));
+    expect(getByTestId("roles").textContent).toBe("");
+    expect(getByTestId("caps").textContent).toBe("");
+    fireEvent.click(getByText("Refetch"));
+    await waitFor(() => expect(getByTestId("ready").textContent).toBe("true"));
+  });
+
+  it("derives roles and capabilities from localStorage user", async () => {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ id: 1, role: "editor" }));
+    function TestComponent() {
+      const rbac = useRBAC({
+        userSource: { type: "localStorage", key: STORAGE_KEY },
+        roleDefinitions: ROLE_DEFS,
+        roleCapabilities: ROLE_CAPS,
+      });
+      return h("div", {},
+        h("span", { "data-testid": "roles" }, rbac.roles.join(",")),
+        h("span", { "data-testid": "caps" }, rbac.capabilities.sort().join(",")),
+        h("span", { "data-testid": "has-editor" }, String(rbac.hasRole("editor"))),
+        h("span", { "data-testid": "can-edit" }, String(rbac.can("posts:edit"))),
+      );
+    }
+    const { getByTestId } = render(h(TestComponent));
+    await waitFor(() => expect(getByTestId("roles").textContent).toContain("editor"));
+    expect(getByTestId("roles").textContent).toContain("viewer");
+    expect(getByTestId("caps").textContent).toContain("posts:edit");
+    expect(getByTestId("has-editor").textContent).toBe("true");
+    expect(getByTestId("can-edit").textContent).toBe("true");
+  });
+
+  it("admin gets wildcard capability", async () => {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ id: 1, role: "admin" }));
+    function TestComponent() {
+      const rbac = useRBAC({
+        userSource: { type: "localStorage", key: STORAGE_KEY },
+        roleDefinitions: ROLE_DEFS,
+        roleCapabilities: ROLE_CAPS,
+      });
+      return h("div", {},
+        h("span", { "data-testid": "can-any" }, String(rbac.can("anything:foo"))),
+        h("span", { "data-testid": "has-admin" }, String(rbac.hasRole("admin"))),
+      );
+    }
+    const { getByTestId } = render(h(TestComponent));
+    await waitFor(() => expect(getByTestId("has-admin").textContent).toBe("true"));
+    expect(getByTestId("can-any").textContent).toBe("true");
+  });
+
+  it("sessionStorage source works", async () => {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify({ id: 2, role: "viewer" }));
+    function TestComponent() {
+      const rbac = useRBAC({
+        userSource: { type: "sessionStorage", key: STORAGE_KEY },
+        roleDefinitions: ROLE_DEFS,
+        roleCapabilities: ROLE_CAPS,
+      });
+      return h("div", {},
+        h("span", { "data-testid": "roles" }, rbac.roles.join(",")),
+        h("span", { "data-testid": "can-read" }, String(rbac.can("posts:read"))),
+      );
+    }
+    const { getByTestId } = render(h(TestComponent));
+    await waitFor(() => expect(getByTestId("roles").textContent).toContain("viewer"));
+    expect(getByTestId("can-read").textContent).toBe("true");
+  });
+
+  it("memory source works", async () => {
+    const user = { id: 3, role: "editor" };
+    function TestComponent() {
+      const rbac = useRBAC({
+        userSource: { type: "memory", getUser: () => user },
+        roleDefinitions: ROLE_DEFS,
+        roleCapabilities: ROLE_CAPS,
+      });
+      return h("div", {},
+        h("span", { "data-testid": "roles" }, rbac.roles.join(",")),
+        h("span", { "data-testid": "can-create" }, String(rbac.can("posts:create"))),
+      );
+    }
+    const { getByTestId } = render(h(TestComponent));
+    await waitFor(() => expect(getByTestId("roles").textContent).toContain("editor"));
+    expect(getByTestId("can-create").textContent).toBe("true");
+  });
+
+  it("custom source with explicit roles and capabilities", async () => {
+    function TestComponent() {
+      const rbac = useRBAC({
+        userSource: {
+          type: "custom",
+          getAuth: () => ({
+            user: { id: 1 },
+            roles: ["custom-role"],
+            capabilities: ["custom:read", "custom:write"],
+          }),
+        },
+        roleDefinitions: ROLE_DEFS,
+        roleCapabilities: ROLE_CAPS,
+      });
+      return h("div", {},
+        h("span", { "data-testid": "roles" }, rbac.roles.join(",")),
+        h("span", { "data-testid": "caps" }, rbac.capabilities.join(",")),
+        h("span", { "data-testid": "can-write" }, String(rbac.can("custom:write"))),
+      );
+    }
+    const { getByTestId } = render(h(TestComponent));
+    await waitFor(() => expect(getByTestId("roles").textContent).toBe("custom-role"));
+    expect(getByTestId("caps").textContent).toContain("custom:write");
+    expect(getByTestId("can-write").textContent).toBe("true");
+  });
+
+  it("setUserInStorage updates localStorage and refetches when key matches", async () => {
+    function TestComponent() {
+      const rbac = useRBAC({
+        userSource: { type: "localStorage", key: STORAGE_KEY },
+        roleDefinitions: ROLE_DEFS,
+        roleCapabilities: ROLE_CAPS,
+      });
+      return h("div", {},
+        h("span", { "data-testid": "roles" }, rbac.roles.join(",")),
+        h("button", {
+          onClick: () => rbac.setUserInStorage({ id: 1, role: "editor" }, "localStorage", STORAGE_KEY),
+        }, "Login as editor"),
+        h("button", { onClick: () => rbac.setUserInStorage(null, "localStorage", STORAGE_KEY) }, "Logout"),
+      );
+    }
+    const { getByTestId, getByText } = render(h(TestComponent));
+    await waitFor(() => expect(getByTestId("roles").textContent).toBe(""));
+    fireEvent.click(getByText("Login as editor"));
+    await waitFor(() => expect(getByTestId("roles").textContent).toContain("editor"));
+    fireEvent.click(getByText("Logout"));
+    await waitFor(() => expect(getByTestId("roles").textContent).toBe(""));
+  });
+
+  it("api source and error handling", async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new Error("Network error"));
+    function TestComponent() {
+      const rbac = useRBAC({
+        userSource: { type: "api", fetch: fetchMock },
+        roleDefinitions: ROLE_DEFS,
+        roleCapabilities: ROLE_CAPS,
+      });
+      return h("div", {},
+        h("span", { "data-testid": "ready" }, String(rbac.isReady)),
+        h("span", { "data-testid": "error" }, rbac.error?.message ?? ""),
+        h("span", { "data-testid": "roles" }, rbac.roles.join(",")),
+      );
+    }
+    const { getByTestId } = render(h(TestComponent));
+    await waitFor(() => expect(getByTestId("ready").textContent).toBe("true"));
+    expect(getByTestId("error").textContent).toBe("Network error");
+    expect(getByTestId("roles").textContent).toBe("");
+  });
+
+  it("capabilitiesOverride from localStorage overrides role-derived capabilities", async () => {
+    const capsKey = "rbac-caps";
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ id: 1, role: "viewer" }));
+    localStorage.setItem(capsKey, JSON.stringify(["posts:read", "posts:edit"]));
+    function TestComponent() {
+      const rbac = useRBAC({
+        userSource: { type: "localStorage", key: STORAGE_KEY },
+        roleDefinitions: ROLE_DEFS,
+        roleCapabilities: ROLE_CAPS,
+        capabilitiesOverride: { type: "localStorage", key: capsKey },
+      });
+      return h("div", {},
+        h("span", { "data-testid": "can-edit" }, String(rbac.can("posts:edit"))),
+      );
+    }
+    const { getByTestId } = render(h(TestComponent));
+    await waitFor(() => expect(getByTestId("can-edit").textContent).toBe("true"));
+  });
+});