@litusarchieve18/agricore-utils 1.0.3 → 1.0.5

package/README.md

@@ -14,7 +14,7 @@ npm install @litusarchieve18/agricore-utils
 
 For Base44 / Deno Environments
 You do not need a .npmrc or GITHUB_TOKEN to use this library in Base44. Import it directly using the npm: protocol:
-import { AgriLogger, AppError, MOD } from 'npm:@litusarchieve18/agricore-utils@^1.0.2';
+import { AgriLogger, AppError, MOD } from 'npm:@litusarchieve18/agricore-utils@^1.0.4';
 
 🏗️ Core Architecture & Features
 This library is designed with the "Adapter Pattern" in mind. It defines strict contracts (AgriCoreSession) so that your business logic remains completely isolated from the underlying Base44 database infrastructure.
@@ -23,7 +23,7 @@ This library is designed with the "Adapter Pattern" in mind. It defines strict c
 The universal contract for authenticated users. The v2 upgrade includes injected UI-ready navigation data (availableScopes) and tenant configurations to prevent unnecessary frontend API calls.
 
 TypeScript
-import { AgriCoreSession } from 'npm:@litusarchieve18/agricore-utils@^1.0.2';
+import { AgriCoreSession } from 'npm:@litusarchieve18/agricore-utils@^1.0.4';
 
 // Example of the v2 structure:
 const session: AgriCoreSession = {
@@ -62,6 +62,34 @@ ErrorFactory
 4. Domain Enums
 The universal vocabulary of the AgriCore platform, ensuring type-safety across all microservices (e.g., UserRole, UserPrivilege, AccessLevel, FacilityType, NotificationMode, TaskStatus, RESOURCE_PATHS).
 
+🔐 Security & Access Control
+The library now includes a centralized logic layer to enforce granular permissions across all AgriCore services.
+
+evaluateBaseAccess: Automatically determines a user's base permission level (NONE, READ, or WRITE) for a specific resource path (e.g., records.financials). It respects the OWNER role "God Mode" bypass and uses ROLE_SECTIONS_BY_KEY to provide sensible defaults for different app sections.
+
+Access Ranking (resolveEffectiveAccess): Implements an additive permission model. By ranking levels (NONE < READ < WRITE), it allows the system to compare base permissions against specific user overrides and resolve the highest authorized access level.
+
+🛡️ Multi-Tenant Boundary Protection (Backend Only)
+To ensure absolute data isolation in our multi-tenant environment, the library provides a "Boundary Guard."
+
+assertTenantBoundary: A critical security function that prevents "Cross-Tenant" attacks. It validates that any target userId or authScopeId (Facility/Legal Entity) involved in a request belongs specifically to the requester's companyId. This serves as a final, mandatory check before any database write operations.
+
+🌳 Infrastructure & Hierarchy Resolution
+AgriCore data records require a full "Infrastructure Path" (Company ID, Legal Entity ID, and Facility ID). Instead of manual lookups, the library automates tree-walking.
+
+generateInfrastructureFields: This utility takes a user’s activeScope and their availableScopes tree. It recursively walks up the hierarchy—from a specific Facility to the Legal Entity and finally to the Root Company. It resolves all relevant infrastructure IDs and generates a new canonicalId, ensuring that every data record is correctly anchored in the organizational hierarchy.
+
+// Example: Using the new utilities in a Base44 Save Hook
+const infrastructure = generateInfrastructureFields(activeScope, session.availableScopes);
+
+// Ensure the user isn't trying to save data into a company they don't belong to
+await assertTenantBoundary(db, session.companyId, { authScopeId: infrastructure.authScopeId });
+
+const recordToSave = {
+  ...userInput,
+  ...infrastructure, // Injects canonicalId, companyId, legalEntityId, etc.
+};
+
 🛠️ Development & Publishing Guide
 Zero Dependencies
 To keep the package ultra-lightweight (~30KB), this library has zero runtime dependencies. All build tools (tsup, typescript) are strictly kept in devDependencies, and the package.json uses the "files": ["dist"] array to ensure only compiled code is uploaded.
@@ -89,7 +117,12 @@ Run the publish command:
 Bash
 npm publish --access public
 📝 Version History
+v1.0.4 — refactor the code and edit readme
+
+v1.0.4 — add generateInfrastructureFields, security access control and multi tenant boundary
+
 v1.0.3 — add the base44Id
+
 v1.0.2 — Breaking Change: Upgraded AgriCoreSession interface. Added companyConfig and UI-ready availableScopes arrays to support the frontend hierarchy dropdown without secondary API calls.
 
 v1.0.1 — Migrated package from private GitHub Registry to public NPM Registry for Base44/Deno compatibility. Removed baseUrl from tsconfig.json for NodeNext compatibility. Cleaned build artifacts from dependencies.

package/dist/index.d.mts

@@ -67,6 +67,13 @@ interface TaskTypeConfig {
     icon: string;
     approveAction: string;
 }
+interface InfrastructureFields {
+    canonicalId: string;
+    companyId: string;
+    legalEntityId: string | null;
+    facilityId: string | null;
+    authScopeId: string;
+}
 
 declare const AgriLogger: {
     log(level: "INFO" | "WARN" | "ERROR", message: string, meta: any): void;
@@ -201,11 +208,11 @@ declare function generateCanonicalId(): string;
  * This matches the documented rule:
  *   "Set to facilityId if available, else legalEntityId, else companyId."
  */
-declare function resolveAuthScopeId(fields?: AuthScopeFields): string;
-declare function withSaveMiddleware<T extends Record<string, any>>(data: T): T & {
-    canonicalId: any;
-    authScopeId: any;
-};
+/**
+ * generateInfrastructureFields
+ * Standardizes the creation of new entities by walking up the scope tree.
+ */
+declare function generateInfrastructureFields(activeScope: AvailableScope, availableScopes: AvailableScope[]): InfrastructureFields;
 declare function buildRlsFilter(session: AgriCoreSession, extra?: Record<string, any>): {
     authScopeId: {
         $in: string[];
@@ -233,6 +240,7 @@ declare const UserRole: {
     readonly LEADING_HAND: "leadingHand";
     readonly WORKER: "worker";
 };
+type UserRoleType = typeof UserRole[keyof typeof UserRole];
 declare const UserPrivilege: {
     readonly FINANCE: "finance";
     readonly HR: "hr";
@@ -245,6 +253,7 @@ declare const AccessLevel: {
     readonly READ: "READ";
     readonly WRITE: "WRITE";
 };
+type AccessLevelType = keyof typeof AccessLevel;
 declare const EnabledModule: {
     readonly FARM_MANAGEMENT: "farm_management";
     readonly PACKHOUSE: "packhouse";
@@ -478,5 +487,26 @@ declare const RESOURCE_PATHS: {
     teamStaff: string;
     teamTraining: string;
 };
+declare const ACCESS_RANK: Record<AccessLevelType, number>;
+declare const ROLE_SECTIONS_BY_KEY: Record<string, UserRoleType[]>;
+declare function evaluateBaseAccess(resourcePath: string, session: {
+    role?: UserRoleType;
+    privileges?: string[];
+    enabledModules?: string[];
+}, requirements?: {
+    module?: string;
+    allowedRoles?: UserRoleType[];
+    requiredPrivileges?: string[];
+}): AccessLevelType;
+/**
+ * Tenant Boundary Guard (Backend Only)
+ * Note: db is typed as 'any' here because Base44 SDK types vary,
+ * but you can refine this with your internal SDK types.
+ */
+declare function assertTenantBoundary(db: any, requesterCompanyId: string, targets: {
+    targetUserId?: string;
+    authScopeId?: string;
+}): Promise<boolean>;
+declare function resolveEffectiveAccess(base: AccessLevelType, override?: AccessLevelType): AccessLevelType;
 
-export { ACT, AccessLevel, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, ERROR_DICTIONARY, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_PATHS, RelationshipType, type ResolvedError, type ResourceOverrides, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, Validator, VigorRating, WaterSource, assertCanWrite, buildRlsFilter, canRead, canWrite, extractAppCode, generateCanonicalId, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveAuthScopeId, resolveError, resolveMenuVisibility, withAgriLogging, withSaveMiddleware };
+export { ACCESS_RANK, ACT, AccessLevel, type AccessLevelType, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, ERROR_DICTIONARY, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, type InfrastructureFields, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_PATHS, ROLE_SECTIONS_BY_KEY, RelationshipType, type ResolvedError, type ResourceOverrides, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, type UserRoleType, Validator, VigorRating, WaterSource, assertCanWrite, assertTenantBoundary, buildRlsFilter, canRead, canWrite, evaluateBaseAccess, extractAppCode, generateCanonicalId, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolveMenuVisibility, withAgriLogging };

package/dist/index.d.ts

@@ -67,6 +67,13 @@ interface TaskTypeConfig {
     icon: string;
     approveAction: string;
 }
+interface InfrastructureFields {
+    canonicalId: string;
+    companyId: string;
+    legalEntityId: string | null;
+    facilityId: string | null;
+    authScopeId: string;
+}
 
 declare const AgriLogger: {
     log(level: "INFO" | "WARN" | "ERROR", message: string, meta: any): void;
@@ -201,11 +208,11 @@ declare function generateCanonicalId(): string;
  * This matches the documented rule:
  *   "Set to facilityId if available, else legalEntityId, else companyId."
  */
-declare function resolveAuthScopeId(fields?: AuthScopeFields): string;
-declare function withSaveMiddleware<T extends Record<string, any>>(data: T): T & {
-    canonicalId: any;
-    authScopeId: any;
-};
+/**
+ * generateInfrastructureFields
+ * Standardizes the creation of new entities by walking up the scope tree.
+ */
+declare function generateInfrastructureFields(activeScope: AvailableScope, availableScopes: AvailableScope[]): InfrastructureFields;
 declare function buildRlsFilter(session: AgriCoreSession, extra?: Record<string, any>): {
     authScopeId: {
         $in: string[];
@@ -233,6 +240,7 @@ declare const UserRole: {
     readonly LEADING_HAND: "leadingHand";
     readonly WORKER: "worker";
 };
+type UserRoleType = typeof UserRole[keyof typeof UserRole];
 declare const UserPrivilege: {
     readonly FINANCE: "finance";
     readonly HR: "hr";
@@ -245,6 +253,7 @@ declare const AccessLevel: {
     readonly READ: "READ";
     readonly WRITE: "WRITE";
 };
+type AccessLevelType = keyof typeof AccessLevel;
 declare const EnabledModule: {
     readonly FARM_MANAGEMENT: "farm_management";
     readonly PACKHOUSE: "packhouse";
@@ -478,5 +487,26 @@ declare const RESOURCE_PATHS: {
     teamStaff: string;
     teamTraining: string;
 };
+declare const ACCESS_RANK: Record<AccessLevelType, number>;
+declare const ROLE_SECTIONS_BY_KEY: Record<string, UserRoleType[]>;
+declare function evaluateBaseAccess(resourcePath: string, session: {
+    role?: UserRoleType;
+    privileges?: string[];
+    enabledModules?: string[];
+}, requirements?: {
+    module?: string;
+    allowedRoles?: UserRoleType[];
+    requiredPrivileges?: string[];
+}): AccessLevelType;
+/**
+ * Tenant Boundary Guard (Backend Only)
+ * Note: db is typed as 'any' here because Base44 SDK types vary,
+ * but you can refine this with your internal SDK types.
+ */
+declare function assertTenantBoundary(db: any, requesterCompanyId: string, targets: {
+    targetUserId?: string;
+    authScopeId?: string;
+}): Promise<boolean>;
+declare function resolveEffectiveAccess(base: AccessLevelType, override?: AccessLevelType): AccessLevelType;
 
-export { ACT, AccessLevel, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, ERROR_DICTIONARY, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_PATHS, RelationshipType, type ResolvedError, type ResourceOverrides, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, Validator, VigorRating, WaterSource, assertCanWrite, buildRlsFilter, canRead, canWrite, extractAppCode, generateCanonicalId, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveAuthScopeId, resolveError, resolveMenuVisibility, withAgriLogging, withSaveMiddleware };
+export { ACCESS_RANK, ACT, AccessLevel, type AccessLevelType, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, ERROR_DICTIONARY, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, type InfrastructureFields, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_PATHS, ROLE_SECTIONS_BY_KEY, RelationshipType, type ResolvedError, type ResourceOverrides, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, type UserRoleType, Validator, VigorRating, WaterSource, assertCanWrite, assertTenantBoundary, buildRlsFilter, canRead, canWrite, evaluateBaseAccess, extractAppCode, generateCanonicalId, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolveMenuVisibility, withAgriLogging };

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ACCESS_RANK: () => ACCESS_RANK,
   ACT: () => ACT,
   AccessLevel: () => AccessLevel,
   AgriLogger: () => AgriLogger,
@@ -49,6 +50,7 @@ __export(index_exports, {
   PhysicalState: () => PhysicalState,
   PlantingMethod: () => PlantingMethod,
   RESOURCE_PATHS: () => RESOURCE_PATHS,
+  ROLE_SECTIONS_BY_KEY: () => ROLE_SECTIONS_BY_KEY,
   RelationshipType: () => RelationshipType,
   RowOrientation: () => RowOrientation,
   SENTINEL_UUID: () => SENTINEL_UUID,
@@ -65,11 +67,14 @@ __export(index_exports, {
   VigorRating: () => VigorRating,
   WaterSource: () => WaterSource,
   assertCanWrite: () => assertCanWrite,
+  assertTenantBoundary: () => assertTenantBoundary,
   buildRlsFilter: () => buildRlsFilter,
   canRead: () => canRead,
   canWrite: () => canWrite,
+  evaluateBaseAccess: () => evaluateBaseAccess,
   extractAppCode: () => extractAppCode,
   generateCanonicalId: () => generateCanonicalId,
+  generateInfrastructureFields: () => generateInfrastructureFields,
   getAcceptedMimeTypes: () => getAcceptedMimeTypes,
   getApproveAction: () => getApproveAction,
   getFormMeta: () => getFormMeta,
@@ -80,11 +85,10 @@ __export(index_exports, {
   isTabWritable: () => isTabWritable,
   resolveAccess: () => resolveAccess,
   resolveAppError: () => resolveAppError,
-  resolveAuthScopeId: () => resolveAuthScopeId,
+  resolveEffectiveAccess: () => resolveEffectiveAccess,
   resolveError: () => resolveError,
   resolveMenuVisibility: () => resolveMenuVisibility,
-  withAgriLogging: () => withAgriLogging,
-  withSaveMiddleware: () => withSaveMiddleware
+  withAgriLogging: () => withAgriLogging
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -423,15 +427,30 @@ function generateCanonicalId() {
     return (c === "x" ? r : r & 3 | 8).toString(16);
   });
 }
-function resolveAuthScopeId(fields = {}) {
-  return fields.facilityId || fields.legalEntityId || fields.companyId || SENTINEL_UUID;
-}
-function withSaveMiddleware(data) {
-  const canonicalId = data.canonicalId || generateCanonicalId();
+function generateInfrastructureFields(activeScope, availableScopes) {
+  if (!activeScope || !availableScopes?.length) {
+    throw new Error("[generateInfrastructureFields] Missing scope context.");
+  }
+  let companyId = null;
+  let legalEntityId = null;
+  let facilityId = null;
+  let pointer = activeScope;
+  while (pointer) {
+    if (pointer.type === "company") companyId = pointer.base44Id;
+    if (pointer.type === "legalEntity") legalEntityId = pointer.base44Id;
+    if (pointer.type === "facility") facilityId = pointer.base44Id;
+    const parentId = pointer.parentId ?? null;
+    pointer = parentId ? availableScopes.find((s) => s.base44Id === parentId) || null : null;
+  }
+  if (!companyId) {
+    throw new Error("[generateInfrastructureFields] Could not resolve companyId from scope tree.");
+  }
   return {
-    ...data,
-    canonicalId,
-    authScopeId: data.authScopeId || resolveAuthScopeId(data)
+    canonicalId: crypto.randomUUID(),
+    companyId,
+    legalEntityId,
+    facilityId,
+    authScopeId: activeScope.authScopeId
   };
 }
 function buildRlsFilter(session, extra = {}) {
@@ -823,8 +842,72 @@ var RESOURCE_PATHS = {
   teamStaff: "team.staff",
   teamTraining: "team.training"
 };
+var ACCESS_RANK = {
+  NONE: 0,
+  READ: 1,
+  WRITE: 2
+};
+var ROLE_SECTIONS_BY_KEY = {
+  dashboard: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR, UserRole.LEADING_HAND, UserRole.WORKER],
+  operations: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR, UserRole.LEADING_HAND, UserRole.WORKER],
+  equipment: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR, UserRole.LEADING_HAND, UserRole.WORKER],
+  safety: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+  team: [UserRole.OWNER, UserRole.MANAGER],
+  records: [UserRole.OWNER, UserRole.MANAGER],
+  adminSettings: []
+};
+function evaluateBaseAccess(resourcePath, session, requirements = {}) {
+  if (!session?.role) return "NONE";
+  if (session.role === UserRole.OWNER) return "WRITE";
+  const topLevel = resourcePath.split(".")[0];
+  const defaultRoles = ROLE_SECTIONS_BY_KEY[topLevel] || [];
+  if (requirements.module && !session.enabledModules?.includes(requirements.module)) return "NONE";
+  const allowedRoles = requirements.allowedRoles?.length ? requirements.allowedRoles : defaultRoles;
+  if (!allowedRoles.includes(session.role)) return "NONE";
+  if (requirements.requiredPrivileges?.length) {
+    const hasPrivilege = requirements.requiredPrivileges.some((p) => session.privileges?.includes(p));
+    if (!hasPrivilege) return "NONE";
+  }
+  const highRoles = [UserRole.OWNER, UserRole.MANAGER];
+  const isHighRole = highRoles.includes(session.role);
+  return isHighRole ? "WRITE" : "READ";
+}
+async function assertTenantBoundary(db, requesterCompanyId, targets) {
+  if (!requesterCompanyId) {
+    throw ErrorFactory.internal(MOD.ADMIN, "Missing requester company context for boundary check.");
+  }
+  if (targets.targetUserId) {
+    const targetUserAssignments = await db.UserRoleAssignment.filter({
+      userId: targets.targetUserId,
+      companyId: requesterCompanyId
+    });
+    if (targetUserAssignments.length === 0) {
+      console.error(`[SECURITY BREACH ATTEMPT] User tried to modify targetUserId ${targets.targetUserId} outside their company ${requesterCompanyId}`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid target user or tenant boundary violation.");
+    }
+  }
+  if (targets.authScopeId) {
+    const [companyMatch, leMatch, facMatch] = await Promise.all([
+      db.Company.filter({ canonicalId: targets.authScopeId, id: requesterCompanyId }),
+      // Base44 id must match requester
+      db.LegalEntity.filter({ canonicalId: targets.authScopeId, companyId: requesterCompanyId }),
+      db.Facility.filter({ canonicalId: targets.authScopeId, companyId: requesterCompanyId })
+    ]);
+    const isValidScope = companyMatch.length > 0 || leMatch.length > 0 || facMatch.length > 0;
+    if (!isValidScope) {
+      console.error(`[SECURITY BREACH ATTEMPT] User tried to assign scope ${targets.authScopeId} outside company ${requesterCompanyId}`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid authorization scope or tenant boundary violation.");
+    }
+  }
+  return true;
+}
+function resolveEffectiveAccess(base, override) {
+  if (!override) return base;
+  return ACCESS_RANK[override] >= ACCESS_RANK[base] ? override : base;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ACCESS_RANK,
   ACT,
   AccessLevel,
   AgriLogger,
@@ -854,6 +937,7 @@ var RESOURCE_PATHS = {
   PhysicalState,
   PlantingMethod,
   RESOURCE_PATHS,
+  ROLE_SECTIONS_BY_KEY,
   RelationshipType,
   RowOrientation,
   SENTINEL_UUID,
@@ -870,11 +954,14 @@ var RESOURCE_PATHS = {
   VigorRating,
   WaterSource,
   assertCanWrite,
+  assertTenantBoundary,
   buildRlsFilter,
   canRead,
   canWrite,
+  evaluateBaseAccess,
   extractAppCode,
   generateCanonicalId,
+  generateInfrastructureFields,
   getAcceptedMimeTypes,
   getApproveAction,
   getFormMeta,
@@ -885,9 +972,8 @@ var RESOURCE_PATHS = {
   isTabWritable,
   resolveAccess,
   resolveAppError,
-  resolveAuthScopeId,
+  resolveEffectiveAccess,
   resolveError,
   resolveMenuVisibility,
-  withAgriLogging,
-  withSaveMiddleware
+  withAgriLogging
 });

package/dist/index.mjs

@@ -333,15 +333,30 @@ function generateCanonicalId() {
     return (c === "x" ? r : r & 3 | 8).toString(16);
   });
 }
-function resolveAuthScopeId(fields = {}) {
-  return fields.facilityId || fields.legalEntityId || fields.companyId || SENTINEL_UUID;
-}
-function withSaveMiddleware(data) {
-  const canonicalId = data.canonicalId || generateCanonicalId();
+function generateInfrastructureFields(activeScope, availableScopes) {
+  if (!activeScope || !availableScopes?.length) {
+    throw new Error("[generateInfrastructureFields] Missing scope context.");
+  }
+  let companyId = null;
+  let legalEntityId = null;
+  let facilityId = null;
+  let pointer = activeScope;
+  while (pointer) {
+    if (pointer.type === "company") companyId = pointer.base44Id;
+    if (pointer.type === "legalEntity") legalEntityId = pointer.base44Id;
+    if (pointer.type === "facility") facilityId = pointer.base44Id;
+    const parentId = pointer.parentId ?? null;
+    pointer = parentId ? availableScopes.find((s) => s.base44Id === parentId) || null : null;
+  }
+  if (!companyId) {
+    throw new Error("[generateInfrastructureFields] Could not resolve companyId from scope tree.");
+  }
   return {
-    ...data,
-    canonicalId,
-    authScopeId: data.authScopeId || resolveAuthScopeId(data)
+    canonicalId: crypto.randomUUID(),
+    companyId,
+    legalEntityId,
+    facilityId,
+    authScopeId: activeScope.authScopeId
   };
 }
 function buildRlsFilter(session, extra = {}) {
@@ -733,7 +748,71 @@ var RESOURCE_PATHS = {
   teamStaff: "team.staff",
   teamTraining: "team.training"
 };
+var ACCESS_RANK = {
+  NONE: 0,
+  READ: 1,
+  WRITE: 2
+};
+var ROLE_SECTIONS_BY_KEY = {
+  dashboard: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR, UserRole.LEADING_HAND, UserRole.WORKER],
+  operations: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR, UserRole.LEADING_HAND, UserRole.WORKER],
+  equipment: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR, UserRole.LEADING_HAND, UserRole.WORKER],
+  safety: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+  team: [UserRole.OWNER, UserRole.MANAGER],
+  records: [UserRole.OWNER, UserRole.MANAGER],
+  adminSettings: []
+};
+function evaluateBaseAccess(resourcePath, session, requirements = {}) {
+  if (!session?.role) return "NONE";
+  if (session.role === UserRole.OWNER) return "WRITE";
+  const topLevel = resourcePath.split(".")[0];
+  const defaultRoles = ROLE_SECTIONS_BY_KEY[topLevel] || [];
+  if (requirements.module && !session.enabledModules?.includes(requirements.module)) return "NONE";
+  const allowedRoles = requirements.allowedRoles?.length ? requirements.allowedRoles : defaultRoles;
+  if (!allowedRoles.includes(session.role)) return "NONE";
+  if (requirements.requiredPrivileges?.length) {
+    const hasPrivilege = requirements.requiredPrivileges.some((p) => session.privileges?.includes(p));
+    if (!hasPrivilege) return "NONE";
+  }
+  const highRoles = [UserRole.OWNER, UserRole.MANAGER];
+  const isHighRole = highRoles.includes(session.role);
+  return isHighRole ? "WRITE" : "READ";
+}
+async function assertTenantBoundary(db, requesterCompanyId, targets) {
+  if (!requesterCompanyId) {
+    throw ErrorFactory.internal(MOD.ADMIN, "Missing requester company context for boundary check.");
+  }
+  if (targets.targetUserId) {
+    const targetUserAssignments = await db.UserRoleAssignment.filter({
+      userId: targets.targetUserId,
+      companyId: requesterCompanyId
+    });
+    if (targetUserAssignments.length === 0) {
+      console.error(`[SECURITY BREACH ATTEMPT] User tried to modify targetUserId ${targets.targetUserId} outside their company ${requesterCompanyId}`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid target user or tenant boundary violation.");
+    }
+  }
+  if (targets.authScopeId) {
+    const [companyMatch, leMatch, facMatch] = await Promise.all([
+      db.Company.filter({ canonicalId: targets.authScopeId, id: requesterCompanyId }),
+      // Base44 id must match requester
+      db.LegalEntity.filter({ canonicalId: targets.authScopeId, companyId: requesterCompanyId }),
+      db.Facility.filter({ canonicalId: targets.authScopeId, companyId: requesterCompanyId })
+    ]);
+    const isValidScope = companyMatch.length > 0 || leMatch.length > 0 || facMatch.length > 0;
+    if (!isValidScope) {
+      console.error(`[SECURITY BREACH ATTEMPT] User tried to assign scope ${targets.authScopeId} outside company ${requesterCompanyId}`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid authorization scope or tenant boundary violation.");
+    }
+  }
+  return true;
+}
+function resolveEffectiveAccess(base, override) {
+  if (!override) return base;
+  return ACCESS_RANK[override] >= ACCESS_RANK[base] ? override : base;
+}
 export {
+  ACCESS_RANK,
   ACT,
   AccessLevel,
   AgriLogger,
@@ -763,6 +842,7 @@ export {
   PhysicalState,
   PlantingMethod,
   RESOURCE_PATHS,
+  ROLE_SECTIONS_BY_KEY,
   RelationshipType,
   RowOrientation,
   SENTINEL_UUID,
@@ -779,11 +859,14 @@ export {
   VigorRating,
   WaterSource,
   assertCanWrite,
+  assertTenantBoundary,
   buildRlsFilter,
   canRead,
   canWrite,
+  evaluateBaseAccess,
   extractAppCode,
   generateCanonicalId,
+  generateInfrastructureFields,
   getAcceptedMimeTypes,
   getApproveAction,
   getFormMeta,
@@ -794,9 +877,8 @@ export {
   isTabWritable,
   resolveAccess,
   resolveAppError,
-  resolveAuthScopeId,
+  resolveEffectiveAccess,
   resolveError,
   resolveMenuVisibility,
-  withAgriLogging,
-  withSaveMiddleware
+  withAgriLogging
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litusarchieve18/agricore-utils",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Canonical Backend Utility Library for AgriCore",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",