roles

src/api/companies/[id]/fetch.ts

@@ -4,6 +4,7 @@ import { companies } from "../../../managers/companies";
 import { apiResponse } from "../../../modules/api-utils/apiResponse";
 import { ContentfulStatusCode } from "hono/utils/http-status";
 import { authMiddleware } from "../../middleware/authorization";
+import GenericError from "../../../Errors/GenericError";
 
 /* /v1/company/companies/[id] */
 export default createRoute(
@@ -12,10 +13,23 @@ export default createRoute(
 
   async (c) => {
     const company = await companies.fetch(c.req.param("identifier"));
+    const includeAddress = c.req.query("includeAddress") === "true";
+
+    // Check for address-specific permission if includeAddress is requested
+    if (includeAddress) {
+      const user = c.get("user");
+      if (!user || !(await user.hasPermission("company.fetch.address"))) {
+        throw new GenericError({
+          name: "InsufficientPermission",
+          message: "You do not have permission to view company addresses.",
+          status: 403,
+        });
+      }
+    }
 
     const response = apiResponse.successful(
       "Company Fetched Successfully!",
-      company,
+      company.toJson({ includeAddress }),
     );
     return c.json(response, response.status as ContentfulStatusCode);
   },

src/api/companies/count.ts

@@ -0,0 +1,25 @@
+import { Hono } from "hono/tiny";
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { companies } from "../../managers/companies";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+
+/* /v1/company/count */
+export default createRoute(
+  "get",
+  ["/count"],
+  async (c) => {
+    const count = await companies.count();
+
+    const response = apiResponse.successful(
+      "Company count fetched successfully!",
+      {
+        count,
+      },
+    );
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["company.fetch.many"] }),
+);

src/api/companies/index.ts

@@ -1,5 +1,6 @@
 import { default as fetchAll } from "./fetchAll";
 import { default as fetch } from "./[id]/fetch";
 import { default as configurations } from "./[id]/configurations";
+import { default as count } from "./count";
 
-export { configurations, fetch, fetchAll };
+export { configurations, count, fetch, fetchAll };

src/api/permissions/fetchAll.ts

@@ -0,0 +1,20 @@
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+import { PERMISSION_NODES } from "../../types/PermissionNodes";
+
+/* /v1/permissions */
+export default createRoute(
+  "get",
+  ["/"],
+
+  async (c) => {
+    const response = apiResponse.successful(
+      "Permission Nodes Fetched Successfully!",
+      PERMISSION_NODES,
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.read"] }),
+);

src/api/permissions/fetchByCategory.ts

@@ -0,0 +1,34 @@
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+import { PERMISSION_NODES } from "../../types/PermissionNodes";
+import GenericError from "../../Errors/GenericError";
+
+/* /v1/permissions/:category */
+export default createRoute(
+  "get",
+  ["/:category"],
+
+  async (c) => {
+    const categoryKey = c.req.param(
+      "category",
+    ) as keyof typeof PERMISSION_NODES;
+
+    if (!(categoryKey in PERMISSION_NODES)) {
+      throw new GenericError({
+        name: "NotFound",
+        message: `Permission category "${categoryKey}" not found`,
+        status: 404,
+        cause: `Valid categories: ${Object.keys(PERMISSION_NODES).join(", ")}`,
+      });
+    }
+
+    const response = apiResponse.successful(
+      "Permission Category Fetched Successfully!",
+      PERMISSION_NODES[categoryKey],
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.read"] }),
+);

src/api/permissions/fetchNodes.ts

@@ -0,0 +1,22 @@
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+import { getAllPermissionNodes } from "../../types/PermissionNodes";
+
+/* /v1/permissions/nodes */
+export default createRoute(
+  "get",
+  ["/nodes"],
+
+  async (c) => {
+    const allNodes = getAllPermissionNodes();
+
+    const response = apiResponse.successful(
+      "All Permission Nodes Fetched Successfully!",
+      allNodes,
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.read"] }),
+);

src/api/permissions/index.ts

@@ -0,0 +1,5 @@
+import { default as fetchAll } from "./fetchAll";
+import { default as fetchByCategory } from "./fetchByCategory";
+import { default as fetchNodes } from "./fetchNodes";
+
+export { fetchAll, fetchByCategory, fetchNodes };

src/api/roles/addPermissions.ts

@@ -0,0 +1,36 @@
+import { Hono } from "hono/tiny";
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { roles } from "../../managers/roles";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+import { z } from "zod";
+
+/* POST /v1/role/:identifier/permissions */
+export default createRoute(
+  "post",
+  ["/:identifier/permissions"],
+
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const body = await c.req.json();
+
+    const schema = z.object({
+      permissions: z
+        .array(z.string().min(1, "Permission node cannot be empty"))
+        .min(1, "At least one permission is required"),
+    });
+
+    const data = schema.parse(body);
+
+    const role = await roles.fetch(identifier);
+    await role.addPermissions(...data.permissions);
+
+    const response = apiResponse.successful(
+      "Permissions Added Successfully!",
+      role.toJson({ viewPermissions: true }),
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.update"] }),
+);

src/api/roles/create.ts

@@ -0,0 +1,36 @@
+import { Hono } from "hono/tiny";
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { roles } from "../../managers/roles";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+import { z } from "zod";
+
+/* POST /v1/role */
+export default createRoute(
+  "post",
+  ["/"],
+
+  async (c) => {
+    const body = await c.req.json();
+
+    const schema = z.object({
+      title: z.string().min(1, "Title is required"),
+      moniker: z.string().min(1, "Moniker is required"),
+      permissions: z
+        .array(z.string().min(1, "Permission node cannot be empty"))
+        .optional(),
+    });
+
+    const data = schema.parse(body);
+
+    const role = await roles.create(data);
+
+    const response = apiResponse.created(
+      "Role Created Successfully!",
+      role.toJson({ viewPermissions: true }),
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.create"] }),
+);

src/api/roles/delete.ts

@@ -0,0 +1,26 @@
+import { Hono } from "hono/tiny";
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { roles } from "../../managers/roles";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+
+/* DELETE /v1/role/:identifier */
+export default createRoute(
+  "delete",
+  ["/:identifier"],
+
+  async (c) => {
+    const identifier = c.req.param("identifier");
+
+    const role = await roles.fetch(identifier);
+    await role.delete();
+
+    const response = apiResponse.successful(
+      "Role Deleted Successfully!",
+      role.toJson(),
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.delete"] }),
+);

src/api/roles/fetch.ts

@@ -0,0 +1,25 @@
+import { Hono } from "hono/tiny";
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { roles } from "../../managers/roles";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+
+/* GET /v1/role/:identifier */
+export default createRoute(
+  "get",
+  ["/:identifier"],
+
+  async (c) => {
+    const identifier = c.req.param("identifier");
+
+    const role = await roles.fetch(identifier);
+
+    const response = apiResponse.successful(
+      "Role Fetched Successfully!",
+      role.toJson({ viewPermissions: true }),
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.read"] }),
+);

src/api/roles/fetchAll.ts

@@ -0,0 +1,27 @@
+import { Hono } from "hono/tiny";
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { roles } from "../../managers/roles";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+
+/* GET /v1/role */
+export default createRoute(
+  "get",
+  ["/"],
+
+  async (c) => {
+    const allRoles = await roles.fetchAllRoles();
+
+    const rolesArray = allRoles.map((role) =>
+      role.toJson({ viewPermissions: true }),
+    );
+
+    const response = apiResponse.successful(
+      "Roles Fetched Successfully!",
+      rolesArray,
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.read", "role.list"] }),
+);

src/api/roles/getUsers.ts

@@ -0,0 +1,28 @@
+import { Hono } from "hono/tiny";
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { roles } from "../../managers/roles";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+
+/* GET /v1/role/:identifier/users */
+export default createRoute(
+  "get",
+  ["/:identifier/users"],
+
+  async (c) => {
+    const identifier = c.req.param("identifier");
+
+    const role = await roles.fetch(identifier);
+    const users = role.getUsers();
+
+    const usersArray = users.map((user) => user.toJson());
+
+    const response = apiResponse.successful(
+      "Users Fetched Successfully!",
+      usersArray,
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.read", "user.read"] }),
+);

src/api/roles/index.ts

@@ -0,0 +1,8 @@
+export { default as create } from "./create";
+export { default as fetch } from "./fetch";
+export { default as fetchAll } from "./fetchAll";
+export { default as update } from "./update";
+export { default as deleteRole } from "./delete";
+export { default as addPermissions } from "./addPermissions";
+export { default as removePermissions } from "./removePermissions";
+export { default as getUsers } from "./getUsers";

src/api/roles/removePermissions.ts

@@ -0,0 +1,36 @@
+import { Hono } from "hono/tiny";
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { roles } from "../../managers/roles";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+import { z } from "zod";
+
+/* DELETE /v1/role/:identifier/permissions */
+export default createRoute(
+  "delete",
+  ["/:identifier/permissions"],
+
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const body = await c.req.json();
+
+    const schema = z.object({
+      permissions: z
+        .array(z.string().min(1, "Permission node cannot be empty"))
+        .min(1, "At least one permission is required"),
+    });
+
+    const data = schema.parse(body);
+
+    const role = await roles.fetch(identifier);
+    await role.removePermissions(...data.permissions);
+
+    const response = apiResponse.successful(
+      "Permissions Removed Successfully!",
+      role.toJson({ viewPermissions: true }),
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.update"] }),
+);

src/api/roles/update.ts

@@ -0,0 +1,41 @@
+import { Hono } from "hono/tiny";
+import { createRoute } from "../../modules/api-utils/createRoute";
+import { roles } from "../../managers/roles";
+import { apiResponse } from "../../modules/api-utils/apiResponse";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { authMiddleware } from "../middleware/authorization";
+import { z } from "zod";
+
+/* PATCH /v1/role/:identifier */
+export default createRoute(
+  "patch",
+  ["/:identifier"],
+
+  async (c) => {
+    const identifier = c.req.param("identifier");
+    const body = await c.req.json();
+
+    const schema = z
+      .object({
+        title: z.string().min(1, "Title cannot be empty"),
+        moniker: z.string().min(1, "Moniker cannot be empty"),
+        permissions: z.array(
+          z.string().min(1, "Permission node cannot be empty"),
+        ),
+      })
+      .partial()
+      .strict();
+
+    const data = schema.parse(body);
+
+    const role = await roles.fetch(identifier);
+    await role.update(data);
+
+    const response = apiResponse.successful(
+      "Role Updated Successfully!",
+      role.toJson({ viewPermissions: true }),
+    );
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ permissions: ["role.update"] }),
+);

src/api/routers/permissionRouter.ts

@@ -0,0 +1,7 @@
+import { Hono } from "hono";
+import * as permissionRoutes from "../permissions";
+
+const permissionRouter = new Hono();
+Object.values(permissionRoutes).map((r) => permissionRouter.route("/", r));
+
+export default permissionRouter;

src/api/routers/roleRouter.ts

@@ -0,0 +1,7 @@
+import { Hono } from "hono";
+import * as roleRoutes from "../roles";
+
+const roleRouter = new Hono();
+Object.values(roleRoutes).map((r) => roleRouter.route("/", r));
+
+export default roleRouter;

src/api/server.ts

@@ -52,6 +52,8 @@ v1.route("/user", require("./routers/user").default);
 v1.route("/company", require("./routers/companyRouter").default);
 v1.route("/credential", require("./routers/credentialRouter").default);
 v1.route("/credential-type", require("./routers/credentialTypeRouter").default);
+v1.route("/role", require("./routers/roleRouter").default);
+v1.route("/permissions", require("./routers/permissionRouter").default);
 app.route("/v1", v1);
 
 export default app;

src/api/user/@me/checkPermission.ts

@@ -0,0 +1,37 @@
+import { ContentfulStatusCode } from "hono/utils/http-status";
+import { z } from "zod";
+import { apiResponse } from "../../../modules/api-utils/apiResponse";
+import { createRoute } from "../../../modules/api-utils/createRoute";
+import { authMiddleware } from "../../middleware/authorization";
+
+const checkPermissionSchema = z.object({
+  permissions: z
+    .array(z.string().min(1, "Permission node cannot be empty"))
+    .min(1, "At least one permission is required"),
+});
+
+// /v1/user/@me/check-permission
+export default createRoute(
+  "post",
+  ["/@me/check-permission"],
+  async (c) => {
+    const user = c.get("user");
+
+    const body = await c.req.json();
+    const { permissions } = checkPermissionSchema.parse(body);
+
+    const results = await Promise.all(
+      permissions.map(async (permission) => ({
+        permission,
+        hasPermission: await user.hasPermission(permission),
+      })),
+    );
+
+    const response = apiResponse.successful("Permission check completed.", {
+      results,
+    });
+
+    return c.json(response, response.status as ContentfulStatusCode);
+  },
+  authMiddleware({ scopes: ["user.read"] }),
+);

src/api/user/@me/index.ts

@@ -1,2 +1,3 @@
 export { default as fetch } from "./fetch";
 export { default as update } from "./update";
+export { default as checkPermission } from "./checkPermission";

src/controllers/CompanyController.ts

@@ -1,6 +1,6 @@
 import { Company } from "../../generated/prisma/client";
 import { fetchCwCompanyById } from "../modules/cw-utils/fetchCompany";
-import { fetchCompanyConfigurations } from "../modules/cw-utils/fetchCompanyConfigurations";
+import { fetchCompanyConfigurations } from "../modules/cw-utils/configurations/fetchCompanyConfigurations";
 import { updateCwInternalCompany } from "../modules/cw-utils/updateCompany";
 import { Company as CWCompany } from "../types/ConnectWiseTypes";
 
@@ -16,12 +16,14 @@ export class CompanyController {
   public name: string;
   public readonly cw_Identifier: string;
   public readonly cw_CompanyId: number;
+  public readonly cw_Data?: CWCompany;
 
-  constructor(companyData: Company) {
+  constructor(companyData: Company, cwData?: CWCompany) {
     this.id = companyData.id;
     this.name = companyData.name;
     this.cw_Identifier = companyData.cw_Identifier;
     this.cw_CompanyId = companyData.cw_CompanyId;
+    this.cw_Data = cwData;
   }
 
   /**
@@ -65,12 +67,22 @@ export class CompanyController {
     return data;
   }
 
-  public toJson() {
+  public toJson(opts?: { includeAddress: boolean }) {
     return {
       id: this.id,
       name: this.name,
       cw_Identifier: this.cw_Identifier,
       cw_CompanyId: this.cw_CompanyId,
+      cw_Data: {
+        address: {
+          line1: this.cw_Data?.addressLine1,
+          line2: this.cw_Data?.addressLine2 ?? null,
+          city: this.cw_Data?.city,
+          state: this.cw_Data?.state,
+          zip: this.cw_Data?.zip,
+          country: this.cw_Data?.country.name,
+        },
+      },
     };
   }
 }

src/controllers/RoleController.ts

@@ -265,7 +265,7 @@ export class RoleController {
         where: { moniker: data.moniker },
       });
 
-      if (checkMoniker)
+      if (checkMoniker && checkMoniker.moniker !== this.moniker)
         throw new RoleError(
           "Moniker is already taken.",
           "Another role with this moniker already exists in the databse.",

src/managers/companies.ts

@@ -1,5 +1,6 @@
-import { prisma } from "../constants";
+import { connectWiseApi, prisma } from "../constants";
 import { CompanyController } from "../controllers/CompanyController";
+import { Company } from "../types/ConnectWiseTypes";
 
 export const companies = {
   async fetch(identifier: string | number): Promise<CompanyController> {
@@ -11,7 +12,10 @@ export const companies = {
 
     if (!search) throw new Error("Unknown company.");
 
-    return new CompanyController(search);
+    const freshCwData = await connectWiseApi.get(
+      `/company/companies/${search.cw_CompanyId}`,
+    );
+    return new CompanyController(search, freshCwData.data);
   },
 
   async count() {

src/modules/cw-utils/configurations/fetchCompanyConfigurations.ts

@@ -1,10 +1,10 @@
-import { connectWiseApi } from "../../constants";
-import { ConfigurationResponse } from "../../types/ConnectWiseTypes";
+import { connectWiseApi } from "../../../constants";
+import { ConfigurationResponse } from "../../../types/ConnectWiseTypes";
 import {
   processConfigurationResponse,
   ProcessedConfiguration,
 } from "./processConfigurationResponse";
-import GenericError from "../../Errors/GenericError";
+import GenericError from "../../../Errors/GenericError";
 
 export const fetchCompanyConfigurations = async (
   cwCompanyId: number,

src/modules/cw-utils/configurations/processConfigurationResponse.ts

@@ -0,0 +1,29 @@
+import { ConfigurationResponse } from "../../../types/ConnectWiseTypes";
+
+export type ProcessedConfiguration = ReturnType<
+  typeof processConfigurationResponse
+>;
+
+export const processConfigurationResponse = (c: ConfigurationResponse) => {
+  return c.map((item) => ({
+    id: item.id,
+    name: item.name,
+    active: item.activeFlag,
+    serialNumber: item.serialNumber,
+    type: item.type,
+    notes: item.notes,
+    status: {
+      id: item.status.id,
+      name: item.status.name,
+    },
+    questions: !item.questions
+      ? null
+      : item.questions.map((q) => ({
+          id: q.questionId,
+          question: q.question,
+          answer: q.answer,
+          fieldType: q.fieldType,
+        })),
+    info: item._info,
+  }));
+};

src/modules/cw-utils/processConfigurationResponse.ts

@@ -1,22 +0,0 @@
-import { ConfigurationResponse } from "../../types/ConnectWiseTypes";
-
-export type ProcessedConfiguration = ReturnType<
-  typeof processConfigurationResponse
->;
-
-export const processConfigurationResponse = (c: ConfigurationResponse) => {
-  return c.map((item) => ({
-    id: item.id,
-    name: item.name,
-    active: item.activeFlag,
-    serialNumber: item.serialNumber,
-    type: item.type,
-    questions: item.questions.map((q) => ({
-      id: q.questionId,
-      question: q.question,
-      answer: q.answer,
-      fieldType: q.fieldType,
-    })),
-    info: item._info,
-  }));
-};

src/types/ConnectWiseTypes.ts

@@ -4,9 +4,11 @@ export interface Company {
   name: string;
   status: CompanyStatus;
   addressLine1: string;
+  addressLine2?: string;
   city: string;
   state: string;
   zip: string;
+  country: BasicEntity;
   phoneNumber: string;
   faxNumber: string;
   website: string;

src/types/PermissionNodes.ts

@@ -0,0 +1,304 @@
+/**
+ * Permission Nodes - Centralized definition of all permission nodes
+ * organized by category with descriptions and usage information.
+ *
+ * Format: resource.action[.modifier]
+ * Special tokens: * (matches all), ? (single char wildcard), [a,b,c] (inclusive), <a,b,c> (exclusive)
+ */
+
+export interface PermissionNode {
+  /** The permission node identifier (e.g., "company.fetch") */
+  node: string;
+  /** Description of what this permission allows */
+  description: string;
+  /** File paths where this permission is used */
+  usedIn: string[];
+  /** Dependencies - other permissions that must be granted alongside this one */
+  dependencies?: string[];
+}
+
+export interface PermissionCategory {
+  /** Category name */
+  name: string;
+  /** Category description */
+  description: string;
+  /** Permission nodes in this category */
+  permissions: PermissionNode[];
+}
+
+export const PERMISSION_NODES = {
+  global: {
+    name: "Global Permissions",
+    description:
+      "Global wildcard permissions that grant access to all resources",
+    permissions: [
+      {
+        node: "*",
+        description:
+          "Full access to all resources and actions (administrator role)",
+        usedIn: [],
+      },
+    ],
+  },
+
+  company: {
+    name: "Company Permissions",
+    description: "Permissions for accessing and managing company resources",
+    permissions: [
+      {
+        node: "company.fetch",
+        description: "Fetch a single company",
+        usedIn: ["src/api/companies/[id]/fetch.ts"],
+      },
+      {
+        node: "company.fetch.address",
+        description: "View company address information",
+        usedIn: ["src/api/companies/[id]/fetch.ts"],
+        dependencies: ["company.fetch"],
+      },
+      {
+        node: "company.fetch.many",
+        description: "Fetch multiple companies",
+        usedIn: ["src/api/companies/fetchAll.ts"],
+      },
+      {
+        node: "company.fetch.configurations",
+        description: "Fetch company configurations",
+        usedIn: ["src/api/companies/[id]/configurations.ts"],
+        dependencies: ["company.fetch"],
+      },
+    ],
+  },
+
+  credential: {
+    name: "Credential Permissions",
+    description: "Permissions for managing credentials and their fields",
+    permissions: [
+      {
+        node: "credential.create",
+        description: "Create a new credential",
+        usedIn: ["src/api/credentials/create.ts"],
+      },
+      {
+        node: "credential.fetch",
+        description: "Fetch a single credential",
+        usedIn: ["src/api/credentials/fetch.ts"],
+      },
+      {
+        node: "credential.fetch.many",
+        description: "Fetch multiple credentials",
+        usedIn: ["src/api/credentials/fetchByCompany.ts"],
+      },
+      {
+        node: "credential.update",
+        description: "Update a credential",
+        usedIn: ["src/api/credentials/update.ts"],
+      },
+      {
+        node: "credential.delete",
+        description: "Delete a credential",
+        usedIn: ["src/api/credentials/delete.ts"],
+      },
+      {
+        node: "credential.fields.fetch",
+        description: "Fetch credential fields",
+        usedIn: ["src/api/credentials/fetchFields.ts"],
+        dependencies: ["credential.fetch"],
+      },
+      {
+        node: "credential.fields.update",
+        description: "Update credential fields",
+        usedIn: ["src/api/credentials/updateFields.ts"],
+        dependencies: ["credential.update"],
+      },
+      {
+        node: "credential.secure_values.read",
+        description: "Read secure values of a credential",
+        usedIn: ["src/api/credentials/readSecureValues.ts"],
+        dependencies: ["credential.fetch"],
+      },
+    ],
+  },
+
+  credentialType: {
+    name: "Credential Type Permissions",
+    description: "Permissions for managing credential types and definitions",
+    permissions: [
+      {
+        node: "credential_type.create",
+        description: "Create a new credential type",
+        usedIn: ["src/api/credential-types/create.ts"],
+      },
+      {
+        node: "credential_type.fetch",
+        description: "Fetch a single credential type",
+        usedIn: ["src/api/credential-types/fetch.ts"],
+      },
+      {
+        node: "credential_type.fetch.many",
+        description: "Fetch multiple credential types",
+        usedIn: ["src/api/credential-types/fetchAll.ts"],
+      },
+      {
+        node: "credential_type.update",
+        description: "Update a credential type",
+        usedIn: ["src/api/credential-types/update.ts"],
+      },
+      {
+        node: "credential_type.delete",
+        description: "Delete a credential type",
+        usedIn: ["src/api/credential-types/delete.ts"],
+      },
+    ],
+  },
+
+  permission: {
+    name: "Permission Permissions",
+    description: "Permissions for viewing permission node definitions",
+    permissions: [
+      {
+        node: "role.read",
+        description: "Fetch all permission nodes organized by category",
+        usedIn: ["src/api/permissions/fetchAll.ts"],
+      },
+      {
+        node: "role.read",
+        description: "Fetch a flat list of all permission nodes",
+        usedIn: ["src/api/permissions/fetchNodes.ts"],
+      },
+      {
+        node: "role.read",
+        description: "Fetch permission nodes by category",
+        usedIn: ["src/api/permissions/fetchByCategory.ts"],
+      },
+    ],
+  },
+
+  role: {
+    name: "Role Permissions",
+    description: "Permissions for managing roles and role assignments",
+    permissions: [
+      {
+        node: "role.create",
+        description: "Create a new role",
+        usedIn: ["src/api/roles/create.ts"],
+      },
+      {
+        node: "role.read",
+        description: "Fetch a single role or view role information",
+        usedIn: ["src/api/roles/fetch.ts"],
+      },
+      {
+        node: "role.list",
+        description: "Fetch all roles",
+        usedIn: ["src/api/roles/fetchAll.ts"],
+        dependencies: ["role.read"],
+      },
+      {
+        node: "role.update",
+        description: "Update role properties or manage role permissions",
+        usedIn: [
+          "src/api/roles/update.ts",
+          "src/api/roles/addPermissions.ts",
+          "src/api/roles/removePermissions.ts",
+        ],
+      },
+      {
+        node: "role.delete",
+        description: "Delete a role",
+        usedIn: ["src/api/roles/delete.ts"],
+      },
+      {
+        node: "user.read",
+        description: "View users assigned to a role",
+        usedIn: ["src/api/roles/getUsers.ts"],
+        dependencies: ["role.read"],
+      },
+    ],
+  },
+
+  user: {
+    name: "User Permissions",
+    description: "Permissions for user profile and information management",
+    permissions: [
+      {
+        node: "user.read",
+        description: "Read user information",
+        usedIn: ["src/api/user/@me/fetch.ts"],
+      },
+      {
+        node: "user.write",
+        description: "Update user information",
+        usedIn: ["src/api/user/@me/update.ts"],
+      },
+    ],
+  },
+
+  uiNavigation: {
+    name: "UI Navigation Permissions",
+    description: "Permissions for controlling navigation visibility",
+    permissions: [
+      {
+        node: "ui.navigation.*.view",
+        description:
+          "View specific navigation sections (e.g., ui.navigation.admin.view)",
+        usedIn: [],
+      },
+    ],
+  },
+
+  adminUI: {
+    name: "Admin UI Permissions",
+    description:
+      "Admin-specific UI permissions that control visibility of admin sub-tabs",
+    permissions: [
+      {
+        node: "admin.users.view",
+        description: "Show the Users tab and load user data",
+        usedIn: [],
+      },
+      {
+        node: "admin.roles.view",
+        description: "Show the Roles tab and load role data",
+        usedIn: [],
+      },
+      {
+        node: "admin.credential-types.view",
+        description: "Show the Credential Types tab and load type data",
+        usedIn: [],
+      },
+    ],
+  },
+} as const satisfies Record<string, PermissionCategory>;
+
+/**
+ * Utility function to get all permission nodes flattened into a single array
+ */
+export function getAllPermissionNodes(): PermissionNode[] {
+  return Object.values(PERMISSION_NODES).flatMap(
+    (category) => category.permissions as PermissionNode[],
+  );
+}
+
+/**
+ * Utility function to get all permission node strings
+ */
+export function getAllPermissionStrings(): string[] {
+  return getAllPermissionNodes().map((p) => p.node);
+}
+
+/**
+ * Utility function to get a specific permission node by its identifier
+ */
+export function getPermissionNode(nodeId: string): PermissionNode | undefined {
+  return getAllPermissionNodes().find((p) => p.node === nodeId);
+}
+
+/**
+ * Utility function to get all permissions in a specific category
+ */
+export function getPermissionsByCategory(
+  categoryKey: keyof typeof PERMISSION_NODES,
+): PermissionNode[] {
+  return PERMISSION_NODES[categoryKey].permissions;
+}