@checkstack/auth-frontend 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @checkstack/auth-frontend
 
+## 0.2.0
+
+### Minor Changes
+
+- 9faec1f: # Unified AccessRule Terminology Refactoring
+
+  This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
+
+  ## Changes
+
+  ### Core Infrastructure (`@checkstack/common`)
+
+  - Introduced `AccessRule` interface as the primary access control type
+  - Added `accessPair()` helper for creating read/manage access rule pairs
+  - Added `access()` builder for individual access rules
+  - Replaced `Permission` type with `AccessRule` throughout
+
+  ### API Changes
+
+  - `env.registerPermissions()` → `env.registerAccessRules()`
+  - `meta.permissions` → `meta.access` in RPC contracts
+  - `usePermission()` → `useAccess()` in frontend hooks
+  - Route `permission:` field → `accessRule:` field
+
+  ### UI Changes
+
+  - "Roles & Permissions" tab → "Roles & Access Rules"
+  - "You don't have permission..." → "You don't have access..."
+  - All permission-related UI text updated
+
+  ### Documentation & Templates
+
+  - Updated 18 documentation files with AccessRule terminology
+  - Updated 7 scaffolding templates with `accessPair()` pattern
+  - All code examples use new AccessRule API
+
+  ## Migration Guide
+
+  ### Backend Plugins
+
+  ```diff
+  - import { permissionList } from "./permissions";
+  - env.registerPermissions(permissionList);
+  + import { accessRules } from "./access";
+  + env.registerAccessRules(accessRules);
+  ```
+
+  ### RPC Contracts
+
+  ```diff
+  - .meta({ userType: "user", permissions: [permissions.read.id] })
+  + .meta({ userType: "user", access: [access.read] })
+  ```
+
+  ### Frontend Hooks
+
+  ```diff
+  - const canRead = accessApi.usePermission(permissions.read.id);
+  + const canRead = accessApi.useAccess(access.read);
+  ```
+
+  ### Routes
+
+  ```diff
+  - permission: permissions.entityRead.id,
+  + accessRule: access.read,
+  ```
+
+### Patch Changes
+
+- 95eeec7: # Auto-login after credential registration
+
+  Users are now automatically logged in after successful registration when using the credential (email & password) authentication strategy.
+
+  ## Changes
+
+  ### Backend (`@checkstack/auth-backend`)
+
+  - Added `autoSignIn: true` to the `emailAndPassword` configuration in better-auth
+  - Users no longer need to manually log in after registration; a session is created immediately upon successful sign-up
+
+  ### Frontend (`@checkstack/auth-frontend`)
+
+  - Updated `RegisterPage` to use full page navigation after registration to ensure the session state refreshes correctly
+  - Updated `LoginPage` to use full page navigation after login to ensure fresh permissions state when switching between users
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [f533141]
+  - @checkstack/auth-common@0.2.0
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/ui@0.2.0
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/auth-frontend",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.tsx",
   "exports": {

package/src/api.ts

@@ -25,10 +25,10 @@ export interface Role {
   description?: string | null;
   isSystem?: boolean;
   isAssignable?: boolean; // False for anonymous role - not assignable to users
-  permissions?: string[];
+  accessRules?: string[];
 }
 
-export interface Permission {
+export interface AccessRuleEntry {
   id: string;
   description?: string;
 }

package/src/components/ApplicationsTab.tsx

@@ -303,7 +303,7 @@ export const ApplicationsTab: React.FC<ApplicationsTabProps> = ({
 
           {!canManageApplications && (
             <p className="text-xs text-muted-foreground mt-4">
-              You don't have permission to manage applications.
+              You don't have access to manage applications.
             </p>
           )}
         </CardContent>

package/src/components/AuthSettingsPage.tsx

@@ -1,12 +1,15 @@
 import React, { useEffect, useState, useMemo } from "react";
 import { useSearchParams } from "react-router-dom";
-import { useApi, permissionApiRef, rpcApiRef } from "@checkstack/frontend-api";
+import { useApi, accessApiRef, rpcApiRef } from "@checkstack/frontend-api";
 import { PageLayout, useToast, Tabs, TabPanel } from "@checkstack/ui";
-import { authApiRef, AuthUser, Role, AuthStrategy, Permission } from "../api";
 import {
-  permissions as authPermissions,
-  AuthApi,
-} from "@checkstack/auth-common";
+  authApiRef,
+  AuthUser,
+  Role,
+  AuthStrategy,
+  AccessRuleEntry,
+} from "../api";
+import { authAccess, AuthApi } from "@checkstack/auth-common";
 import { Shield, Settings2, Users, Key, Users2 } from "lucide-react";
 import { UsersTab } from "./UsersTab";
 import { RolesTab } from "./RolesTab";
@@ -18,7 +21,7 @@ export const AuthSettingsPage: React.FC = () => {
   const authApi = useApi(authApiRef);
   const rpcApi = useApi(rpcApiRef);
   const authClient = rpcApi.forPlugin(AuthApi);
-  const permissionApi = useApi(permissionApiRef);
+  const accessApi = useApi(accessApiRef);
   const toast = useToast();
   const [searchParams, setSearchParams] = useSearchParams();
 
@@ -29,13 +32,11 @@ export const AuthSettingsPage: React.FC = () => {
   >("users");
   const [users, setUsers] = useState<(AuthUser & { roles: string[] })[]>([]);
   const [roles, setRoles] = useState<Role[]>([]);
-  const [permissions, setPermissions] = useState<Permission[]>([]);
+  const [accessRuleEntries, setAccessRuleEntries] = useState<AccessRuleEntry[]>([]);
   const [strategies, setStrategies] = useState<AuthStrategy[]>([]);
   const [loading, setLoading] = useState(true);
 
-  const canReadUsers = permissionApi.usePermission(
-    authPermissions.usersRead.id
-  );
+  const canReadUsers = accessApi.useAccess(authAccess.users.read);
 
   // Handle ?tab= URL parameters (from command palette)
   useEffect(() => {
@@ -58,44 +59,20 @@ export const AuthSettingsPage: React.FC = () => {
     }
   }, [searchParams, setSearchParams]);
 
-  const canManageUsers = permissionApi.usePermission(
-    authPermissions.usersManage.id
-  );
-  const canCreateUsers = permissionApi.usePermission(
-    authPermissions.usersCreate.id
-  );
-  const canReadRoles = permissionApi.usePermission(
-    authPermissions.rolesRead.id
-  );
-  const canCreateRoles = permissionApi.usePermission(
-    authPermissions.rolesCreate.id
-  );
-  const canUpdateRoles = permissionApi.usePermission(
-    authPermissions.rolesUpdate.id
-  );
-  const canDeleteRoles = permissionApi.usePermission(
-    authPermissions.rolesDelete.id
-  );
-  const canManageRoles = permissionApi.usePermission(
-    authPermissions.rolesManage.id
-  );
-  const canManageStrategies = permissionApi.usePermission(
-    authPermissions.strategiesManage.id
-  );
-  const canManageRegistration = permissionApi.usePermission(
-    authPermissions.registrationManage.id
-  );
-  const canManageApplications = permissionApi.usePermission(
-    authPermissions.applicationsManage.id
-  );
-  const canReadTeams = permissionApi.usePermission(
-    authPermissions.teamsRead.id
-  );
-  const canManageTeams = permissionApi.usePermission(
-    authPermissions.teamsManage.id
-  );
-
-  const permissionsLoading =
+  const canManageUsers = accessApi.useAccess(authAccess.users.manage);
+  const canCreateUsers = accessApi.useAccess(authAccess.users.create);
+  const canReadRoles = accessApi.useAccess(authAccess.roles.read);
+  const canCreateRoles = accessApi.useAccess(authAccess.roles.create);
+  const canUpdateRoles = accessApi.useAccess(authAccess.roles.update);
+  const canDeleteRoles = accessApi.useAccess(authAccess.roles.delete);
+  const canManageRoles = accessApi.useAccess(authAccess.roles.manage);
+  const canManageStrategies = accessApi.useAccess(authAccess.strategies);
+  const canManageRegistration = accessApi.useAccess(authAccess.registration);
+  const canManageApplications = accessApi.useAccess(authAccess.applications);
+  const canReadTeams = accessApi.useAccess(authAccess.teams.read);
+  const canManageTeams = accessApi.useAccess(authAccess.teams.manage);
+
+  const accessRulesLoading =
     loading ||
     canReadUsers.loading ||
     canReadRoles.loading ||
@@ -103,17 +80,17 @@ export const AuthSettingsPage: React.FC = () => {
     canManageApplications.loading ||
     canReadTeams.loading;
 
-  const hasAnyPermission =
+  const hasAnyAccess =
     canReadUsers.allowed ||
     canReadRoles.allowed ||
     canManageStrategies.allowed ||
     canManageApplications.allowed ||
     canReadTeams.allowed;
 
-  // Special case: if user is not logged in, show permission denied
-  const isAllowed = session.data?.user ? hasAnyPermission : false;
+  // Special case: if user is not logged in, show access denied
+  const isAllowed = session.data?.user ? hasAnyAccess : false;
 
-  // Compute visible tabs based on permissions
+  // Compute visible tabs based on access rules
   const visibleTabs = useMemo(() => {
     const tabs: Array<{
       id: "users" | "roles" | "teams" | "strategies" | "applications";
@@ -129,7 +106,7 @@ export const AuthSettingsPage: React.FC = () => {
     if (canReadRoles.allowed)
       tabs.push({
         id: "roles",
-        label: "Roles & Permissions",
+        label: "Roles & Access Rules",
         icon: <Shield size={18} />,
       });
     if (canReadTeams.allowed)
@@ -176,11 +153,11 @@ export const AuthSettingsPage: React.FC = () => {
         roles: string[];
       })[];
       const rolesData = await authClient.getRoles();
-      const permissionsData = await authClient.getPermissions();
+      const accessRulesData = await authClient.getAccessRules();
       const strategiesData = await authClient.getStrategies();
       setUsers(usersData);
       setRoles(rolesData);
-      setPermissions(permissionsData);
+      setAccessRuleEntries(accessRulesData);
       setStrategies(strategiesData);
     } catch (error: unknown) {
       const message =
@@ -204,7 +181,7 @@ export const AuthSettingsPage: React.FC = () => {
   return (
     <PageLayout
       title="Authentication Settings"
-      loading={permissionsLoading}
+      loading={accessRulesLoading}
       allowed={isAllowed}
     >
       <Tabs
@@ -235,7 +212,7 @@ export const AuthSettingsPage: React.FC = () => {
       <TabPanel id="roles" activeTab={activeTab}>
         <RolesTab
           roles={roles}
-          permissions={permissions}
+          accessRulesList={accessRuleEntries}
           userRoleIds={currentUserRoleIds}
           canReadRoles={canReadRoles.allowed}
           canCreateRoles={canCreateRoles.allowed}

package/src/components/LoginPage.tsx

@@ -1,5 +1,5 @@
 import React, { useState } from "react";
-import { Link, useNavigate } from "react-router-dom";
+import { Link } from "react-router-dom";
 import { LogIn, LogOut, AlertCircle } from "lucide-react";
 import {
   useApi,
@@ -38,7 +38,7 @@ import {
 } from "@checkstack/ui";
 import { authApiRef } from "../api";
 import { useEnabledStrategies } from "../hooks/useEnabledStrategies";
-import { usePermissions } from "../hooks/usePermissions";
+import { useAccessRules } from "../hooks/useAccessRules";
 import { useAuthClient } from "../lib/auth-client";
 import { SocialProviderButton } from "./SocialProviderButton";
 import { useEffect } from "react";
@@ -47,7 +47,7 @@ export const LoginPage = () => {
   const [email, setEmail] = useState("");
   const [password, setPassword] = useState("");
   const [loading, setLoading] = useState(false);
-  const navigate = useNavigate();
+
   const authApi = useApi(authApiRef);
   const rpcApi = useApi(rpcApiRef);
   const authRpcClient = rpcApi.forPlugin(AuthApi);
@@ -74,7 +74,8 @@ export const LoginPage = () => {
       if (error) {
         console.error("Login failed:", error);
       } else {
-        navigate("/");
+        // Use full page navigation to ensure session/permissions state refreshes
+        globalThis.location.href = "/";
       }
     } finally {
       setLoading(false);
@@ -273,7 +274,7 @@ export const LogoutMenuItem = (_props: UserMenuItemsContext) => {
 export const LoginNavbarAction = () => {
   const authApi = useApi(authApiRef);
   const { data: session, isPending } = authApi.useSession();
-  const { permissions, loading: permissionsLoading } = usePermissions();
+  const { accessRules, loading: accessRulesLoading } = useAccessRules();
   const authClient = useAuthClient();
   const [hasCredentialAccount, setHasCredentialAccount] =
     useState<boolean>(false);
@@ -295,7 +296,7 @@ export const LoginNavbarAction = () => {
     });
   }, [session?.user, authClient]);
 
-  if (isPending || permissionsLoading || credentialLoading) {
+  if (isPending || accessRulesLoading || credentialLoading) {
     return <div className="w-20 h-9 bg-muted animate-pulse rounded-full" />;
   }
 
@@ -306,7 +307,7 @@ export const LoginNavbarAction = () => {
     );
     const hasBottomItems = bottomExtensions.length > 0;
     const menuContext: UserMenuItemsContext = {
-      permissions,
+      accessRules,
       hasCredentialAccount,
     };
 

package/src/components/RegisterPage.tsx

@@ -1,13 +1,9 @@
 import React, { useState, useEffect } from "react";
-import { Link, useNavigate } from "react-router-dom";
+import { Link } from "react-router-dom";
 import { AlertCircle } from "lucide-react";
 import { useApi, rpcApiRef } from "@checkstack/frontend-api";
 import { authApiRef } from "../api";
-import {
-  AuthApi,
-  authRoutes,
-  passwordSchema,
-} from "@checkstack/auth-common";
+import { AuthApi, authRoutes, passwordSchema } from "@checkstack/auth-common";
 import { resolveRoute } from "@checkstack/common";
 import {
   Button,
@@ -35,7 +31,7 @@ export const RegisterPage = () => {
   const [password, setPassword] = useState("");
   const [loading, setLoading] = useState(false);
   const [validationErrors, setValidationErrors] = useState<string[]>([]);
-  const navigate = useNavigate();
+
   const authApi = useApi(authApiRef);
   const rpcApi = useApi(rpcApiRef);
   const authRpcClient = rpcApi.forPlugin(AuthApi);
@@ -87,7 +83,8 @@ export const RegisterPage = () => {
       if (res.error) {
         console.error("Registration failed:", res.error);
       } else {
-        navigate("/");
+        // Use full page navigation to ensure session state refreshes in navbar
+        globalThis.location.href = "/";
       }
     } catch (error) {
       console.error("Registration failed:", error);

package/src/components/RoleDialog.tsx

@@ -19,20 +19,20 @@ import {
   AlertDescription,
 } from "@checkstack/ui";
 import { Check } from "lucide-react";
-import type { Role, Permission } from "../api";
+import type { Role, AccessRuleEntry } from "../api";
 
 interface RoleDialogProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   role?: Role;
-  permissions: Permission[];
-  /** Whether current user has this role (prevents permission elevation) */
+  accessRulesList: AccessRuleEntry[];
+  /** Whether current user has this role (prevents access elevation) */
   isUserRole?: boolean;
   onSave: (params: {
     id?: string;
     name: string;
     description?: string;
-    permissions: string[];
+    accessRules: string[];
   }) => Promise<void>;
 }
 
@@ -40,14 +40,14 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
   open,
   onOpenChange,
   role,
-  permissions,
+  accessRulesList,
   isUserRole = false,
   onSave,
 }) => {
   const [name, setName] = useState(role?.name || "");
   const [description, setDescription] = useState(role?.description || "");
-  const [selectedPermissions, setSelectedPermissions] = useState<Set<string>>(
-    new Set(role?.permissions || [])
+  const [selectedAccessRules, setSelectedAccessRules] = useState<Set<string>>(
+    new Set(role?.accessRules || [])
   );
   const [saving, setSaving] = useState(false);
 
@@ -55,32 +55,32 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
   React.useEffect(() => {
     setName(role?.name || "");
     setDescription(role?.description || "");
-    setSelectedPermissions(new Set(role?.permissions || []));
+    setSelectedAccessRules(new Set(role?.accessRules || []));
   }, [role]);
 
   const isEditing = !!role;
   const isAdminRole = role?.id === "admin";
-  // Disable permissions for admin (wildcard) or user's own roles (prevent elevation)
-  const permissionsDisabled = isAdminRole || isUserRole;
+  // Disable access rules for admin (wildcard) or user's own roles (prevent elevation)
+  const accessRulesDisabled = isAdminRole || isUserRole;
 
-  // Group permissions by plugin
-  const permissionsByPlugin: Record<string, Permission[]> = {};
-  for (const perm of permissions) {
+  // Group access rules by plugin
+  const accessRulesByPlugin: Record<string, AccessRuleEntry[]> = {};
+  for (const perm of accessRulesList) {
     const [plugin] = perm.id.split(".");
-    if (!permissionsByPlugin[plugin]) {
-      permissionsByPlugin[plugin] = [];
+    if (!accessRulesByPlugin[plugin]) {
+      accessRulesByPlugin[plugin] = [];
     }
-    permissionsByPlugin[plugin].push(perm);
+    accessRulesByPlugin[plugin].push(perm);
   }
 
-  const handleTogglePermission = (permissionId: string) => {
-    const newSelected = new Set(selectedPermissions);
-    if (newSelected.has(permissionId)) {
-      newSelected.delete(permissionId);
+  const handleToggleAccessRule = (accessRuleId: string) => {
+    const newSelected = new Set(selectedAccessRules);
+    if (newSelected.has(accessRuleId)) {
+      newSelected.delete(accessRuleId);
     } else {
-      newSelected.add(permissionId);
+      newSelected.add(accessRuleId);
     }
-    setSelectedPermissions(newSelected);
+    setSelectedAccessRules(newSelected);
   };
 
   const handleSave = async () => {
@@ -90,7 +90,7 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
         ...(isEditing && { id: role.id }),
         name,
         description: description || undefined,
-        permissions: [...selectedPermissions],
+        accessRules: [...selectedAccessRules],
       });
       onOpenChange(false);
     } catch (error) {
@@ -114,8 +114,8 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
           <DialogTitle>{isEditing ? "Edit Role" : "Create Role"}</DialogTitle>
           <DialogDescription className="sr-only">
             {isEditing
-              ? "Modify the settings and permissions for this role"
-              : "Create a new role with specific permissions"}
+              ? "Modify the settings and access rules for this role"
+              : "Create a new role with specific access rules"}
           </DialogDescription>
         </DialogHeader>
 
@@ -141,15 +141,15 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
           </div>
 
           <div>
-            <Label className="text-base">Permissions</Label>
+            <Label className="text-base">Access Rules</Label>
             <p className="text-sm text-muted-foreground mt-1 mb-3">
-              Select permissions to grant to this role. Permissions are
+              Select access rules to grant to this role. Access rules are
               organized by plugin.
             </p>
             {isAdminRole && (
               <Alert variant="info" className="mb-3">
                 <AlertDescription>
-                  The administrator role has wildcard access to all permissions.
+                  The administrator role has wildcard access to all access rules.
                   These cannot be modified.
                 </AlertDescription>
               </Alert>
@@ -157,7 +157,7 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
             {!isAdminRole && isUserRole && (
               <Alert variant="info" className="mb-3">
                 <AlertDescription>
-                  You cannot modify permissions for a role you currently have.
+                  You cannot modify access rules for a role you currently have.
                   This prevents accidental self-lockout from the system.
                 </AlertDescription>
               </Alert>
@@ -165,10 +165,10 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
             <div className="border rounded-lg">
               <Accordion
                 type="multiple"
-                defaultValue={Object.keys(permissionsByPlugin)}
+                defaultValue={Object.keys(accessRulesByPlugin)}
                 className="w-full"
               >
-                {Object.entries(permissionsByPlugin).map(([plugin, perms]) => (
+                {Object.entries(accessRulesByPlugin).map(([plugin, perms]) => (
                   <AccordionItem key={plugin} value={plugin}>
                     <AccordionTrigger className="px-4 hover:no-underline">
                       <div className="flex items-center justify-between flex-1 pr-2">
@@ -177,7 +177,7 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
                         </span>
                         <span className="text-xs text-muted-foreground">
                           {
-                            perms.filter((p) => selectedPermissions.has(p.id))
+                            perms.filter((p) => selectedAccessRules.has(p.id))
                               .length
                           }{" "}
                           / {perms.length} selected
@@ -187,15 +187,15 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
                     <AccordionContent className="px-4">
                       <div
                         className={`space-y-${
-                          permissionsDisabled ? "2" : "3"
+                          accessRulesDisabled ? "2" : "3"
                         } pt-2`}
                       >
                         {perms.map((perm) => {
                           const isAssigned =
-                            isAdminRole || selectedPermissions.has(perm.id);
+                            isAdminRole || selectedAccessRules.has(perm.id);
 
-                          // Use view-style design when permissions are disabled
-                          if (permissionsDisabled) {
+                          // Use view-style design when access rules are disabled
+                          if (accessRulesDisabled) {
                             return (
                               <div
                                 key={perm.id}
@@ -239,7 +239,7 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
                             );
                           }
 
-                          // Use editable checkbox design when permissions are editable
+                          // Use editable checkbox design when access rules are editable
                           return (
                             <div
                               key={perm.id}
@@ -247,9 +247,9 @@ export const RoleDialog: React.FC<RoleDialogProps> = ({
                             >
                               <Checkbox
                                 id={`perm-${perm.id}`}
-                                checked={selectedPermissions.has(perm.id)}
+                                checked={selectedAccessRules.has(perm.id)}
                                 onCheckedChange={() =>
-                                  handleTogglePermission(perm.id)
+                                  handleToggleAccessRule(perm.id)
                                 }
                                 className="mt-0.5"
                               />

package/src/components/RolesTab.tsx

@@ -19,12 +19,12 @@ import { Plus, Edit, Trash2 } from "lucide-react";
 import { useApi } from "@checkstack/frontend-api";
 import { rpcApiRef } from "@checkstack/frontend-api";
 import { AuthApi } from "@checkstack/auth-common";
-import type { Role, Permission } from "../api";
+import type { Role, AccessRuleEntry } from "../api";
 import { RoleDialog } from "./RoleDialog";
 
 export interface RolesTabProps {
   roles: Role[];
-  permissions: Permission[];
+  accessRulesList: AccessRuleEntry[];
   userRoleIds: string[];
   canReadRoles: boolean;
   canCreateRoles: boolean;
@@ -35,7 +35,7 @@ export interface RolesTabProps {
 
 export const RolesTab: React.FC<RolesTabProps> = ({
   roles,
-  permissions,
+  accessRulesList,
   userRoleIds,
   canReadRoles,
   canCreateRoles,
@@ -65,7 +65,7 @@ export const RolesTab: React.FC<RolesTabProps> = ({
     id?: string;
     name: string;
     description?: string;
-    permissions: string[];
+    accessRules: string[];
   }) => {
     try {
       if (params.id) {
@@ -73,14 +73,14 @@ export const RolesTab: React.FC<RolesTabProps> = ({
           id: params.id,
           name: params.name,
           description: params.description,
-          permissions: params.permissions,
+          accessRules: params.accessRules,
         });
         toast.success("Role updated successfully");
       } else {
         await authClient.createRole({
           name: params.name,
           description: params.description,
-          permissions: params.permissions,
+          accessRules: params.accessRules,
         });
         toast.success("Role created successfully");
       }
@@ -128,7 +128,7 @@ export const RolesTab: React.FC<RolesTabProps> = ({
                 <TableHeader>
                   <TableRow>
                     <TableHead>Role</TableHead>
-                    <TableHead>Permissions</TableHead>
+                    <TableHead>Access Rules</TableHead>
                     <TableHead className="text-right">Actions</TableHead>
                   </TableRow>
                 </TableHeader>
@@ -159,7 +159,7 @@ export const RolesTab: React.FC<RolesTabProps> = ({
                         </TableCell>
                         <TableCell>
                           <span className="text-sm text-muted-foreground">
-                            {role.permissions?.length || 0} permissions
+                            {role.accessRules?.length || 0} access rules
                           </span>
                         </TableCell>
                         <TableCell className="text-right">
@@ -192,7 +192,7 @@ export const RolesTab: React.FC<RolesTabProps> = ({
             )
           ) : (
             <p className="text-muted-foreground">
-              You don't have permission to view roles.
+              You don't have access to view roles.
             </p>
           )}
         </CardContent>
@@ -202,7 +202,7 @@ export const RolesTab: React.FC<RolesTabProps> = ({
         open={roleDialogOpen}
         onOpenChange={setRoleDialogOpen}
         role={editingRole}
-        permissions={permissions}
+        accessRulesList={accessRulesList}
         isUserRole={editingRole ? userRoleIds.includes(editingRole.id) : false}
         onSave={handleSaveRole}
       />

package/src/components/StrategiesTab.tsx

@@ -64,7 +64,7 @@ export const StrategiesTab: React.FC<StrategiesTabProps> = ({
     setStrategyConfigs(configs);
   }, [strategies]);
 
-  // Fetch registration data when we have permission
+  // Fetch registration data when we have access
   useEffect(() => {
     if (!canManageRegistration) {
       setLoadingRegistration(false);
@@ -206,7 +206,7 @@ export const StrategiesTab: React.FC<StrategiesTabProps> = ({
             )
           ) : (
             <p className="text-sm text-muted-foreground">
-              You don't have permission to manage registration settings.
+              You don't have access to manage registration settings.
             </p>
           )}
         </CardContent>
@@ -268,7 +268,7 @@ export const StrategiesTab: React.FC<StrategiesTabProps> = ({
 
       {!canManageStrategies && (
         <p className="text-xs text-muted-foreground mt-4">
-          You don't have permission to manage strategies.
+          You don't have access to manage strategies.
         </p>
       )}
     </div>

package/src/components/TeamAccessEditor.tsx

@@ -26,11 +26,8 @@ import {
   Settings,
   Lock,
 } from "lucide-react";
-import { useApi, rpcApiRef, permissionApiRef } from "@checkstack/frontend-api";
-import {
-  AuthApi,
-  permissions as authPermissions,
-} from "@checkstack/auth-common";
+import { useApi, rpcApiRef, accessApiRef } from "@checkstack/frontend-api";
+import { AuthApi, authAccess } from "@checkstack/auth-common";
 
 interface TeamAccess {
   teamId: string;
@@ -72,12 +69,12 @@ export const TeamAccessEditor: React.FC<TeamAccessEditorProps> = ({
   onChange,
 }) => {
   const rpcApi = useApi(rpcApiRef);
-  const permissionApi = useApi(permissionApiRef);
+  const accessApi = useApi(accessApiRef);
   const authClient = rpcApi.forPlugin(AuthApi);
   const toast = useToast();
 
-  const { allowed: canManageTeams } = permissionApi.usePermission(
-    authPermissions.teamsManage.id
+  const { allowed: canManageTeams } = accessApi.useAccess(
+    authAccess.teams.manage
   );
 
   const [expanded, setExpanded] = useState(initialExpanded);
@@ -270,7 +267,7 @@ export const TeamAccessEditor: React.FC<TeamAccessEditorProps> = ({
                     Team Only
                   </Label>
                   <span className="text-xs text-muted-foreground">
-                    (Bypass global permissions)
+                    (Bypass global accesss)
                   </span>
                 </div>
                 <Toggle
@@ -320,7 +317,7 @@ export const TeamAccessEditor: React.FC<TeamAccessEditorProps> = ({
             <div className="space-y-2">
               {accessList.length === 0 ? (
                 <p className="text-sm text-muted-foreground text-center py-2">
-                  No team restrictions. All users with permission can access.
+                  No team restrictions. All users with access can access.
                 </p>
               ) : (
                 accessList.map((access) => (
@@ -472,7 +469,7 @@ export const TeamAccessEditor: React.FC<TeamAccessEditorProps> = ({
                     </Label>
                     <p className="text-xs text-muted-foreground">
                       When enabled, only team members can access (global
-                      permissions bypassed)
+                      access bypassed)
                     </p>
                   </div>
                 </div>
@@ -488,7 +485,7 @@ export const TeamAccessEditor: React.FC<TeamAccessEditorProps> = ({
             {accessList.length === 0 ? (
               <p className="text-sm text-muted-foreground text-center py-4 bg-muted/30 rounded-lg">
                 No team restrictions configured. All users with appropriate
-                permissions can access this resource.
+                access can view this resource.
               </p>
             ) : (
               <div className="border rounded-lg divide-y">

package/src/components/TeamsTab.tsx

@@ -370,7 +370,7 @@ export const TeamsTab: React.FC<TeamsTabProps> = ({
             )
           ) : (
             <p className="text-muted-foreground">
-              You don't have permission to view teams.
+              You don't have access to view teams.
             </p>
           )}
         </CardContent>

package/src/components/UsersTab.tsx

@@ -130,7 +130,7 @@ export const UsersTab: React.FC<UsersTabProps> = ({
             <AlertDescription>
               You cannot modify roles for your own account. This security
               measure prevents accidental self-lockout from the system and
-              permission elevation.
+              access elevation.
             </AlertDescription>
           </Alert>
           {canReadUsers ? (
@@ -210,7 +210,7 @@ export const UsersTab: React.FC<UsersTabProps> = ({
             )
           ) : (
             <p className="text-muted-foreground">
-              You don't have permission to list users.
+              You don't have access to list users.
             </p>
           )}
         </CardContent>

package/src/hooks/{usePermissions.ts → useAccessRules.ts}

@@ -3,10 +3,10 @@ import { useAuthClient } from "../lib/auth-client";
 import { rpcApiRef, useApi } from "@checkstack/frontend-api";
 import { AuthApi } from "@checkstack/auth-common";
 
-export const usePermissions = () => {
+export const useAccessRules = () => {
   const authClient = useAuthClient();
   const { data: session, isPending: sessionPending } = authClient.useSession();
-  const [permissions, setPermissions] = useState<string[]>([]);
+  const [accessRules, setAccessRules] = useState<string[]>([]);
   const [loading, setLoading] = useState(true);
   const rpcApi = useApi(rpcApiRef);
 
@@ -18,26 +18,26 @@ export const usePermissions = () => {
     }
 
     if (!session?.user) {
-      setPermissions([]);
+      setAccessRules([]);
       setLoading(false);
       return;
     }
 
-    const fetchPermissions = async () => {
+    const fetchAccessRules = async () => {
       try {
         const authRpc = rpcApi.forPlugin(AuthApi);
-        const data = await authRpc.permissions();
-        if (Array.isArray(data.permissions)) {
-          setPermissions(data.permissions);
+        const data = await authRpc.accessRules();
+        if (Array.isArray(data.accessRules)) {
+          setAccessRules(data.accessRules);
         }
       } catch (error) {
-        console.error("Failed to fetch permissions", error);
+        console.error("Failed to fetch access rules", error);
       } finally {
         setLoading(false);
       }
     };
-    fetchPermissions();
+    fetchAccessRules();
   }, [session?.user?.id, sessionPending, rpcApi]);
 
-  return { permissions, loading };
+  return { accessRules, loading };
 };

package/src/index.test.tsx

@@ -1,95 +1,141 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
 import { authPlugin } from "./index";
-import { permissionApiRef } from "@checkstack/frontend-api";
-import { usePermissions } from "./hooks/usePermissions";
+import { accessApiRef } from "@checkstack/frontend-api";
+import type { AccessRule } from "@checkstack/common";
+import { useAccessRules } from "./hooks/useAccessRules";
 
-// Mock the usePermissions hook
-mock.module("./hooks/usePermissions", () => ({
-  usePermissions: mock(),
+// Mock the useAccessRules hook
+mock.module("./hooks/useAccessRules", () => ({
+  useAccessRules: mock(),
 }));
 
-describe("AuthPermissionApi", () => {
-  let permissionApi: {
-    usePermission: (p: string) => { loading: boolean; allowed: boolean };
+// Test access rule objects
+const testReadAccess: AccessRule = {
+  id: "test.read",
+  resource: "test",
+  level: "read",
+  description: "Test read access",
+};
+
+const testManageAccess: AccessRule = {
+  id: "test.manage",
+  resource: "test",
+  level: "manage",
+  description: "Test manage access",
+};
+
+const otherAccess: AccessRule = {
+  id: "other.read",
+  resource: "other",
+  level: "read",
+  description: "Other read access",
+};
+
+describe("AuthAccessApi", () => {
+  let accessApi: {
+    useAccess: (p: AccessRule) => { loading: boolean; allowed: boolean };
   };
 
   beforeEach(() => {
-    const apiDef = authPlugin.apis?.find(
-      (a) => a.ref.id === permissionApiRef.id
-    );
-    if (!apiDef) throw new Error("Permission API not found in plugin");
-    permissionApi = apiDef.factory({ get: () => ({}) } as any) as any;
+    const apiDef = authPlugin.apis?.find((a) => a.ref.id === accessApiRef.id);
+    if (!apiDef) throw new Error("Access API not found in plugin");
+    accessApi = apiDef.factory({ get: () => ({}) } as any) as any;
   });
 
-  it("should return true if user has the permission", () => {
-    (usePermissions as ReturnType<typeof mock>).mockReturnValue({
-      permissions: ["test.permission"],
+  it("should return true if user has the access rule", () => {
+    (useAccessRules as ReturnType<typeof mock>).mockReturnValue({
+      accessRules: ["test.read"],
       loading: false,
     });
 
-    expect(permissionApi.usePermission("test.permission")).toEqual({
+    expect(accessApi.useAccess(testReadAccess)).toEqual({
       loading: false,
       allowed: true,
     });
   });
 
-  it("should return false if user is missing the permission", () => {
-    (usePermissions as ReturnType<typeof mock>).mockReturnValue({
-      permissions: ["other.permission"],
+  it("should return false if user is missing the access rule", () => {
+    (useAccessRules as ReturnType<typeof mock>).mockReturnValue({
+      accessRules: ["other.read"],
       loading: false,
     });
 
-    expect(permissionApi.usePermission("test.permission")).toEqual({
+    expect(accessApi.useAccess(testReadAccess)).toEqual({
       loading: false,
       allowed: false,
     });
   });
 
-  it("should return false if no session data (no permissions)", () => {
-    (usePermissions as ReturnType<typeof mock>).mockReturnValue({
-      permissions: [],
+  it("should return false if no session data (no access rules)", () => {
+    (useAccessRules as ReturnType<typeof mock>).mockReturnValue({
+      accessRules: [],
       loading: false,
     });
 
-    expect(permissionApi.usePermission("test.permission")).toEqual({
+    expect(accessApi.useAccess(testReadAccess)).toEqual({
       loading: false,
       allowed: false,
     });
   });
 
-  it("should return false if no user permissions (empty array)", () => {
-    (usePermissions as ReturnType<typeof mock>).mockReturnValue({
-      permissions: [],
+  it("should return false if no user access rules (empty array)", () => {
+    (useAccessRules as ReturnType<typeof mock>).mockReturnValue({
+      accessRules: [],
       loading: false,
     });
 
-    expect(permissionApi.usePermission("test.permission")).toEqual({
+    expect(accessApi.useAccess(testReadAccess)).toEqual({
       loading: false,
       allowed: false,
     });
   });
 
-  it("should return true if user has the wildcard permission", () => {
-    (usePermissions as ReturnType<typeof mock>).mockReturnValue({
-      permissions: ["*"],
+  it("should return true if user has the wildcard access rule", () => {
+    (useAccessRules as ReturnType<typeof mock>).mockReturnValue({
+      accessRules: ["*"],
       loading: false,
     });
 
-    expect(permissionApi.usePermission("any.permission")).toEqual({
+    expect(accessApi.useAccess(otherAccess)).toEqual({
       loading: false,
       allowed: true,
     });
   });
 
-  it("should return loading state if permissions are loading", () => {
-    (usePermissions as ReturnType<typeof mock>).mockReturnValue({
-      permissions: [],
+  it("should return true if user has manage access for a manage check", () => {
+    (useAccessRules as ReturnType<typeof mock>).mockReturnValue({
+      accessRules: ["test.manage"],
+      loading: false,
+    });
+
+    expect(accessApi.useAccess(testManageAccess)).toEqual({
+      loading: false,
+      allowed: true,
+    });
+  });
+
+  it("should return loading state if access rules are loading", () => {
+    (useAccessRules as ReturnType<typeof mock>).mockReturnValue({
+      accessRules: [],
       loading: true,
     });
 
-    expect(permissionApi.usePermission("test.permission")).toEqual({
+    expect(accessApi.useAccess(testReadAccess)).toEqual({
       loading: true,
       allowed: false,
     });
   });
+
+  it("should return true if user has manage access for a read check", () => {
+    (useAccessRules as ReturnType<typeof mock>).mockReturnValue({
+      accessRules: ["test.manage"],
+      loading: false,
+    });
+
+    // User has test.manage, which implies test.read
+    expect(accessApi.useAccess(testReadAccess)).toEqual({
+      loading: false,
+      allowed: true,
+    });
+  });
 });

package/src/index.tsx

@@ -1,8 +1,8 @@
 import React from "react";
 import {
   ApiRef,
-  permissionApiRef,
-  PermissionApi,
+  accessApiRef,
+  AccessApi,
   createFrontendPlugin,
   createSlotExtension,
   NavbarRightSlot,
@@ -22,71 +22,52 @@ import { ChangePasswordPage } from "./components/ChangePasswordPage";
 import { authApiRef, AuthApi, AuthSession } from "./api";
 import { getAuthClientLazy } from "./lib/auth-client";
 
-import { usePermissions } from "./hooks/usePermissions";
+import { useAccessRules } from "./hooks/useAccessRules";
 
-import { PermissionAction, qualifyPermissionId } from "@checkstack/common";
+import type { AccessRule } from "@checkstack/common";
 import { useNavigate } from "react-router-dom";
 import { Settings2, Key } from "lucide-react";
 import { DropdownMenuItem } from "@checkstack/ui";
 import { UserMenuItemsContext } from "@checkstack/frontend-api";
 import { AuthSettingsPage } from "./components/AuthSettingsPage";
 import {
-  permissions as authPermissions,
+  authAccess,
   authRoutes,
   pluginMetadata,
 } from "@checkstack/auth-common";
 import { resolveRoute } from "@checkstack/common";
 
-class AuthPermissionApi implements PermissionApi {
-  usePermission(permission: string): { loading: boolean; allowed: boolean } {
-    const { permissions, loading } = usePermissions();
-
-    if (loading) {
-      return { loading: true, allowed: false };
-    }
-
-    // If no user, or user has no permissions, return false
-    if (!permissions || permissions.length === 0) {
-      return { loading: false, allowed: false };
-    }
-    const allowed =
-      permissions.includes("*") || permissions.includes(permission);
-    return { loading: false, allowed };
-  }
-
-  useResourcePermission(
-    resource: string,
-    action: PermissionAction
-  ): { loading: boolean; allowed: boolean } {
-    const { permissions, loading } = usePermissions();
+/**
+ * Unified access API implementation.
+ * Uses AccessRule objects for access checks.
+ */
+class AuthAccessApi implements AccessApi {
+  useAccess(accessRule: AccessRule): { loading: boolean; allowed: boolean } {
+    const { accessRules, loading } = useAccessRules();
 
     if (loading) {
       return { loading: true, allowed: false };
     }
 
-    if (!permissions || permissions.length === 0) {
+    // If no user, or user has no access rules, return false
+    if (!accessRules || accessRules.length === 0) {
       return { loading: false, allowed: false };
     }
 
-    const isWildcard = permissions.includes("*");
-    const hasResourceManage = permissions.includes(`${resource}.manage`);
-    const hasSpecificPermission = permissions.includes(`${resource}.${action}`);
+    const accessRuleId = accessRule.id;
 
-    // manage implies read
-    const isAllowed =
-      isWildcard ||
-      hasResourceManage ||
-      (action === "read" && hasResourceManage) ||
-      hasSpecificPermission;
+    // Check wildcard, exact match, or manage implies read
+    const isWildcard = accessRules.includes("*");
+    const hasExact = accessRules.includes(accessRuleId);
 
-    return { loading: false, allowed: isAllowed };
-  }
+    // For read actions, also check if user has manage access for the same resource
+    const hasManage =
+      accessRule.level === "read"
+        ? accessRules.includes(`${accessRule.resource}.manage`)
+        : false;
 
-  useManagePermission(resource: string): {
-    loading: boolean;
-    allowed: boolean;
-  } {
-    return this.useResourcePermission(resource, "manage");
+    const allowed = isWildcard || hasExact || hasManage;
+    return { loading: false, allowed };
   }
 }
 
@@ -180,8 +161,8 @@ export const authPlugin = createFrontendPlugin({
       factory: () => new BetterAuthApi(),
     },
     {
-      ref: permissionApiRef as ApiRef<unknown>,
-      factory: () => new AuthPermissionApi(),
+      ref: accessApiRef as ApiRef<unknown>,
+      factory: () => new AuthAccessApi(),
     },
   ],
   routes: [
@@ -222,12 +203,9 @@ export const authPlugin = createFrontendPlugin({
     },
     createSlotExtension(UserMenuItemsSlot, {
       id: "auth.user-menu.settings",
-      component: ({ permissions: userPerms }: UserMenuItemsContext) => {
+      component: ({ accessRules: userPerms }: UserMenuItemsContext) => {
         const navigate = useNavigate();
-        const qualifiedId = qualifyPermissionId(
-          pluginMetadata,
-          authPermissions.strategiesManage
-        );
+        const qualifiedId = `${pluginMetadata.pluginId}.${authAccess.strategies.id}`;
         const canManage =
           userPerms.includes("*") || userPerms.includes(qualifiedId);