🔐 Authentication, RBAC & Feature Limits

Work Clock HQ enforces a multi-tiered security model combining JWT Authentication, Role-Based Access Control (RBAC), and Subscription Feature Limit Gating.

---

🔑 1. Authentication & Session Persistence

Cookies & Session Tokens (services/Cookies.ts)

Authentication state relies on secure HTTP cookies managed via CookiesService:

• token: JWT bearer token used in Authorization headers.
• org_id: Active organization ID context.

import Cookies from "js-cookie";

export const CookiesService = {
  getToken: () => Cookies.get("token"),
  setToken: (token: string) => Cookies.set("token", token, { expires: 7 }),
  getOrgId: () => Cookies.get("org_id"),
  setOrgId: (id: string) => Cookies.set("org_id", id),
  clearAll: () => {
    Cookies.remove("token");
    Cookies.remove("org_id");
  },
};

---

🛡️ 2. Declarative RBAC System (PermissionGuard)

UI components, buttons, and route actions are conditionally rendered based on user permissions.

PermissionGuard Component Structure

The PermissionGuard component (components/auth/permission-guard.tsx) wraps UI elements to ensure unauthorized users cannot view or interact with protected actions:

import { PermissionGuard } from "@/components/auth/permission-guard";
import { PERMISSIONS } from "@/constant/permissions";
import { Button } from "@/components/ui/button";

export function DepartmentHeader() {
  return (
    <div>
      <h1>Departments</h1>
      <PermissionGuard permissions={PERMISSIONS.DEPARTMENTS.CREATE}>
        <Button onClick={handleAddDepartment}>+ Add Department</Button>
      </PermissionGuard>
    </div>
  );
}

---

usePermissions Hook

For imperative permission checks inside logic functions:

import { usePermissions } from "@/components/auth/permission-guard";
import { PERMISSIONS } from "@/constant/permissions";

export function MyComponent() {
  const { hasPermission } = usePermissions();

  const handleExport = () => {
    if (!hasPermission(PERMISSIONS.ATTENDANCE.EXPORT)) {
      showError("Access Denied", "You do not have permission to export logs.");
      return;
    }
    // Perform export...
  };
}

---

🚦 3. Subscription Feature Limits Gating (useFeatureChecker)

Beyond user role permissions, Work Clock HQ enforces Plan Limit Constraints (e.g. max locations, max department limits based on active subscription tier).

useFeatureChecker Implementation

The useFeatureChecker hook (hooks/use-feature-checker.ts) verifies whether an organization has exceeded its subscription plan capacity before allowing new resources to be provisioned:

import { useFeatureChecker, FEATURE_SLUGS } from "@/hooks/use-feature-checker";

export function AddLocationButton() {
  const { checkFeature, isLoading } = useFeatureChecker();

  const handleClick = async () => {
    const { canPerform, message } = await checkFeature(FEATURE_SLUGS.LOCATION, 1);
    if (!canPerform) {
      // Feature check fails (e.g. limit reached) -> shows upgrade modal prompt
      return;
    }
    // Open add location sheet...
  };
}

---

📋 4. Global Permission Constants (constant/permissions.ts)

Domain	Permission Constant	System Action Guarded
Employees	PERMISSIONS.EMPLOYEES.VIEW	Viewing user directory and profiles.
Employees	PERMISSIONS.EMPLOYEES.CREATE	Adding single staff or executing bulk CSV uploads.
Attendance	PERMISSIONS.ATTENDANCE.VIEW	Viewing live attendance logs and GPS maps.
Attendance	PERMISSIONS.ATTENDANCE.EXPORT	Exporting CSV payroll and attendance reports.
Departments	PERMISSIONS.DEPARTMENTS.CREATE	Provisioning new main departments.
Sub-Depts	PERMISSIONS.SUB_DEPARTMENTS.CREATE	Provisioning nested sub-departments.
Billing	PERMISSIONS.BILLING.UPGRADE	Initiating plan upgrades and wallet top-ups.
Admins	PERMISSIONS.ORGANIZATION_ADMINS.CREATE	Adding workspace administrators.