@litusarchieve18/agricore-utils 1.0.7 → 1.0.9

package/README.md

@@ -90,6 +90,18 @@ const recordToSave = {
   ...infrastructure, // Injects canonicalId, companyId, legalEntityId, etc.
 };
 
+To completely eliminate database bottlenecks and solve serverless rate-limiting, AgriCore has migrated to a state-of-the-art, "Zero-DB" authorization architecture. By decoupling our security rules from the database SDK, our backend API endpoints now resolve complex multi-tenant boundaries and granular role-based access controls in roughly 1 millisecond.
+
+Key Features of the New Security Engine:
+
+One-Time Session Generation: On login, the backend dynamically aggregates a user's full hierarchical profile—including role assignments, availableScopes (Company > Legal Entity > Facility), and granular resourceOverrides—into a single, cryptographically signed JSON Web Token (JWT).
+
+Zero-DB Library Validations: The @litusarchieve18/agricore-utils library has been upgraded to utilize pure, synchronous functions. Deep hierarchical access checks (findSpecificOverride) and tenant isolation (assertTenantBoundary) are now resolved directly against the JWT payload in-memory, completely bypassing the database for routine requests.
+
+Smart Frontend Interceptor: A centralized React hook (useApiClient) acts as an automated API wrapper. It seamlessly injects the user's customJWT and the globally selected activeScopeId into every outbound request. This keeps UI forms completely decoupled from authentication logic.
+
+Instant Context Switching: Because the JWT securely holds the user's entire "VIP List" of permitted scopes, users can instantly switch between farms, legal entities, and facilities in the frontend global dropdown without triggering a new authentication handshake or database query.
+
 🛠️ 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.
@@ -117,7 +129,11 @@ Run the publish command:
 Bash
 npm publish --access public
 📝 Version History
-v1.0.5 — add RESOURCE_MODULE_MAP
+V1.0.9 — added jwt function
+
+v1.0.8 — added temporary RESOURCE_REQUIREMENTS
+
+v1.0.7 — add RESOURCE_MODULE_MAP
 
 v1.0.6 — adding more logic
 

package/dist/index.d.mts

@@ -490,24 +490,33 @@ declare const RESOURCE_PATHS: {
 declare const RESOURCE_MODULE_MAP: Record<string, string[]>;
 declare const ACCESS_RANK: Record<AccessLevelType, number>;
 declare const ROLE_SECTIONS_BY_KEY: Record<string, UserRoleType[]>;
+interface ResourceRequirement {
+    allowedRoles?: UserRoleType[];
+    requiredPrivileges?: string[];
+}
+declare const EVERYONE: ("owner" | "manager" | "supervisor" | "leadingHand" | "worker")[];
+declare const RESOURCE_REQUIREMENTS: Record<string, ResourceRequirement>;
 declare function evaluateBaseAccess(resourcePath: string, session: {
     role?: UserRoleType;
     privileges?: string[];
     enabledModules?: string[];
-}, requirements?: {
-    allowedRoles?: UserRoleType[];
-    requiredPrivileges?: string[];
-}): AccessLevelType;
+}, requirements?: ResourceRequirement): AccessLevelType;
+/**
+ * The Judge: Overrides win over base access (Specificity principle).
+ */
+declare function resolveEffectiveAccess(base: AccessLevelType, override?: AccessLevelType | null): AccessLevelType;
+declare function findSpecificOverride(session: AgriCoreSession, activeScopeId: string, resourcePath: string): AccessLevelType | null;
 /**
  * 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: {
+declare function assertTenantBoundary(db: any, session: AgriCoreSession, // Pass the JWT session instead of just requesterCompanyId
+targets: {
     targetUserId?: string;
     authScopeId?: string;
     expectedScopeType?: 'company' | 'legalEntity' | 'facility';
 }): Promise<boolean>;
-declare function resolveEffectiveAccess(base: AccessLevelType, override?: AccessLevelType | null): AccessLevelType;
+declare function verifyAndExtractSession(token: string, secret: string): Promise<AgriCoreSession>;
 
-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_MODULE_MAP, 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 };
+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, EVERYONE, 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_MODULE_MAP, RESOURCE_PATHS, RESOURCE_REQUIREMENTS, ROLE_SECTIONS_BY_KEY, RelationshipType, type ResolvedError, type ResourceOverrides, type ResourceRequirement, 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, findSpecificOverride, generateCanonicalId, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolveMenuVisibility, verifyAndExtractSession, withAgriLogging };

package/dist/index.d.ts

@@ -490,24 +490,33 @@ declare const RESOURCE_PATHS: {
 declare const RESOURCE_MODULE_MAP: Record<string, string[]>;
 declare const ACCESS_RANK: Record<AccessLevelType, number>;
 declare const ROLE_SECTIONS_BY_KEY: Record<string, UserRoleType[]>;
+interface ResourceRequirement {
+    allowedRoles?: UserRoleType[];
+    requiredPrivileges?: string[];
+}
+declare const EVERYONE: ("owner" | "manager" | "supervisor" | "leadingHand" | "worker")[];
+declare const RESOURCE_REQUIREMENTS: Record<string, ResourceRequirement>;
 declare function evaluateBaseAccess(resourcePath: string, session: {
     role?: UserRoleType;
     privileges?: string[];
     enabledModules?: string[];
-}, requirements?: {
-    allowedRoles?: UserRoleType[];
-    requiredPrivileges?: string[];
-}): AccessLevelType;
+}, requirements?: ResourceRequirement): AccessLevelType;
+/**
+ * The Judge: Overrides win over base access (Specificity principle).
+ */
+declare function resolveEffectiveAccess(base: AccessLevelType, override?: AccessLevelType | null): AccessLevelType;
+declare function findSpecificOverride(session: AgriCoreSession, activeScopeId: string, resourcePath: string): AccessLevelType | null;
 /**
  * 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: {
+declare function assertTenantBoundary(db: any, session: AgriCoreSession, // Pass the JWT session instead of just requesterCompanyId
+targets: {
     targetUserId?: string;
     authScopeId?: string;
     expectedScopeType?: 'company' | 'legalEntity' | 'facility';
 }): Promise<boolean>;
-declare function resolveEffectiveAccess(base: AccessLevelType, override?: AccessLevelType | null): AccessLevelType;
+declare function verifyAndExtractSession(token: string, secret: string): Promise<AgriCoreSession>;
 
-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_MODULE_MAP, 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 };
+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, EVERYONE, 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_MODULE_MAP, RESOURCE_PATHS, RESOURCE_REQUIREMENTS, ROLE_SECTIONS_BY_KEY, RelationshipType, type ResolvedError, type ResourceOverrides, type ResourceRequirement, 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, findSpecificOverride, generateCanonicalId, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolveMenuVisibility, verifyAndExtractSession, withAgriLogging };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   Converter: () => Converter,
   CropCycleStatus: () => CropCycleStatus,
   ERROR_DICTIONARY: () => ERROR_DICTIONARY,
+  EVERYONE: () => EVERYONE,
   EmitterType: () => EmitterType,
   EnabledModule: () => EnabledModule,
   ErrorFactory: () => ErrorFactory,
@@ -51,6 +52,7 @@ __export(index_exports, {
   PlantingMethod: () => PlantingMethod,
   RESOURCE_MODULE_MAP: () => RESOURCE_MODULE_MAP,
   RESOURCE_PATHS: () => RESOURCE_PATHS,
+  RESOURCE_REQUIREMENTS: () => RESOURCE_REQUIREMENTS,
   ROLE_SECTIONS_BY_KEY: () => ROLE_SECTIONS_BY_KEY,
   RelationshipType: () => RelationshipType,
   RowOrientation: () => RowOrientation,
@@ -74,6 +76,7 @@ __export(index_exports, {
   canWrite: () => canWrite,
   evaluateBaseAccess: () => evaluateBaseAccess,
   extractAppCode: () => extractAppCode,
+  findSpecificOverride: () => findSpecificOverride,
   generateCanonicalId: () => generateCanonicalId,
   generateInfrastructureFields: () => generateInfrastructureFields,
   getAcceptedMimeTypes: () => getAcceptedMimeTypes,
@@ -89,9 +92,11 @@ __export(index_exports, {
   resolveEffectiveAccess: () => resolveEffectiveAccess,
   resolveError: () => resolveError,
   resolveMenuVisibility: () => resolveMenuVisibility,
+  verifyAndExtractSession: () => verifyAndExtractSession,
   withAgriLogging: () => withAgriLogging
 });
 module.exports = __toCommonJS(index_exports);
+var import_jose = require("jose");
 
 // src/logger.ts
 var SENSITIVE_KEYS = ["password", "token", "secret", "apiKey", "creditCard", "authorization"];
@@ -430,7 +435,7 @@ function generateCanonicalId() {
 }
 function generateInfrastructureFields(activeScope, availableScopes) {
   if (!activeScope || !availableScopes?.length) {
-    throw new Error("[generateInfrastructureFields] Missing scope context.");
+    throw ErrorFactory.unauthorized("[generateInfrastructureFields] Missing scope context.");
   }
   let companyId = null;
   let legalEntityId = null;
@@ -444,7 +449,7 @@ function generateInfrastructureFields(activeScope, availableScopes) {
     pointer = parentId ? availableScopes.find((s) => s.base44Id === parentId) || null : null;
   }
   if (!companyId) {
-    throw new Error("[generateInfrastructureFields] Could not resolve companyId from scope tree.");
+    throw ErrorFactory.unauthorized("[generateInfrastructureFields] Could not resolve companyId from scope tree.");
   }
   return {
     canonicalId: crypto.randomUUID(),
@@ -907,6 +912,76 @@ var ROLE_SECTIONS_BY_KEY = {
   records: [UserRole.OWNER, UserRole.MANAGER],
   adminSettings: []
 };
+var EVERYONE = Object.values(UserRole);
+var RESOURCE_REQUIREMENTS = {
+  [RESOURCE_PATHS.dashboard]: {
+    allowedRoles: EVERYONE
+  },
+  [RESOURCE_PATHS.operations]: {
+    allowedRoles: EVERYONE
+  },
+  // [RESOURCE_PATHS.equipment]: EVERYONE, 
+  // [RESOURCE_PATHS.safety]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.team]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.records]: ALL_OPERATIONS, 
+  // [RESOURCE_PATHS.adminSettings]: ALL_OPERATIONS,
+  // ── Records & Reports ──────────────────────────────────────────────────────
+  [RESOURCE_PATHS.documentHub]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  [RESOURCE_PATHS.documentHubTemplates]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  [RESOURCE_PATHS.documentHubFolder]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  [RESOURCE_PATHS.documentHubExtraction]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  [RESOURCE_PATHS.documentHubQueue]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  // [RESOURCE_PATHS.analytics]: ALL_OPERATIONS,
+  // ── Admin Settings ─────────────────────────────────────────────────────────
+  [RESOURCE_PATHS.adminUserRoster]: {
+    allowedRoles: [UserRole.OWNER],
+    requiredPrivileges: [UserPrivilege.ADMIN]
+  },
+  [RESOURCE_PATHS.adminBlueprintsSites]: {
+    allowedRoles: [UserRole.OWNER],
+    requiredPrivileges: [UserPrivilege.ADMIN]
+  },
+  [RESOURCE_PATHS.adminRolesPermissions]: {
+    allowedRoles: [UserRole.OWNER],
+    requiredPrivileges: [UserPrivilege.ADMIN]
+  },
+  [RESOURCE_PATHS.adminCompanySettings]: {
+    allowedRoles: [UserRole.OWNER]
+  }
+  //  // ── Operations ────────────────────────────────────────────────────────────
+  // [RESOURCE_PATHS.farmManagement]: [EnabledModule.FARM_MANAGEMENT],
+  // [RESOURCE_PATHS.packhouse]: [EnabledModule.PACKHOUSE],
+  // [RESOURCE_PATHS.accommodation]: [EnabledModule.ACCOMMODATION],
+  //  // ── Equipment & Fleet ──────────────────────────────────────────────────────
+  // [RESOURCE_PATHS.equipPreStart]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.equipMaintenance]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.equipFuelRegister]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.equipCalibration]: AGRI_ONLY,
+  // [RESOURCE_PATHS.equipFleet]: ALL_OPERATIONS,
+  //  // ── Safety, Quality & Compliance ──────────────────────────────────────────
+  // [RESOURCE_PATHS.safetyAuditing]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.safetyFood]: AGRI_ONLY,
+  // [RESOURCE_PATHS.safetyWhs]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.safetyCleaning]: ALL_OPERATIONS,
+  //  // ── Team & HR ──────────────────────────────────────────────────────────────
+  // [RESOURCE_PATHS.teamStaff]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.teamTraining]: ALL_OPERATIONS,
+};
 function evaluateBaseAccess(resourcePath, session, requirements = {}) {
   if (!session?.role) return "NONE";
   if (session.role === UserRole.OWNER) return "WRITE";
@@ -925,44 +1000,63 @@ function evaluateBaseAccess(resourcePath, session, requirements = {}) {
   }
   return session.role === UserRole.MANAGER ? "WRITE" : "READ";
 }
-async function assertTenantBoundary(db, requesterCompanyId, targets) {
-  if (!requesterCompanyId) {
-    throw ErrorFactory.internal(MOD.ADMIN, "Missing requester company context for boundary check.");
+function resolveEffectiveAccess(base, override) {
+  return override === void 0 || override === null ? base : override;
+}
+function findSpecificOverride(session, activeScopeId, resourcePath) {
+  const scopeOverrides = session.resourceOverrides?.[activeScopeId];
+  if (!scopeOverrides) return null;
+  const parts = resourcePath.split(".");
+  let currentPath = "";
+  let bestOverride = null;
+  for (const part of parts) {
+    currentPath = currentPath ? `${currentPath}.${part}` : part;
+    if (scopeOverrides[currentPath] !== void 0) {
+      bestOverride = scopeOverrides[currentPath];
+    }
+  }
+  return bestOverride;
+}
+async function assertTenantBoundary(db, session, targets) {
+  if (!session.companyId) {
+    throw ErrorFactory.internal(MOD.ADMIN, "Missing requester company context.");
   }
   if (targets.targetUserId) {
     const targetUserAssignments = await db.UserRoleAssignment.filter({
       userId: targets.targetUserId,
-      companyId: requesterCompanyId
+      companyId: session.companyId
     });
     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.");
+      console.error(`[SECURITY BREACH] User tried to modify targetUserId ${targets.targetUserId}`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid target user.");
     }
   }
   if (targets.authScopeId) {
-    let matchFound = false;
-    if (targets.expectedScopeType === "company" || !targets.expectedScopeType) {
-      const c = await db.Company.filter({ canonicalId: targets.authScopeId, id: requesterCompanyId });
-      if (c.length > 0) matchFound = true;
-    }
-    if (!matchFound && (targets.expectedScopeType === "legalEntity" || !targets.expectedScopeType)) {
-      const le = await db.LegalEntity.filter({ canonicalId: targets.authScopeId, companyId: requesterCompanyId });
-      if (le.length > 0) matchFound = true;
-    }
-    if (!matchFound && (targets.expectedScopeType === "facility" || !targets.expectedScopeType)) {
-      const fac = await db.Facility.filter({ canonicalId: targets.authScopeId, companyId: requesterCompanyId });
-      if (fac.length > 0) matchFound = true;
+    const matchedScope = session.availableScopes?.find(
+      (scope) => scope.authScopeId === targets.authScopeId
+    );
+    if (!matchedScope) {
+      console.error(`[SECURITY BREACH] Scope ${targets.authScopeId} not found in user's permitted list.`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Tenant boundary violation.");
     }
-    if (!matchFound) {
-      console.error(`[SECURITY BREACH/VALIDATION ERROR] Scope ${targets.authScopeId} not found for type ${targets.expectedScopeType} in company ${requesterCompanyId}`);
-      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid authorization scope level or tenant boundary violation.");
+    if (targets.expectedScopeType && matchedScope.type !== targets.expectedScopeType) {
+      console.error(`[VALIDATION ERROR] Expected type ${targets.expectedScopeType} but got ${matchedScope.type}`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid authorization scope level.");
     }
   }
   return true;
 }
-function resolveEffectiveAccess(base, override) {
-  if (override === void 0 || override === null) return base;
-  return override;
+async function verifyAndExtractSession(token, secret) {
+  if (!token) {
+    throw ErrorFactory.unauthorized(MOD.SESSION, "UNAUTHORIZED: No secure session token provided.");
+  }
+  try {
+    const secretKey = new TextEncoder().encode(secret);
+    const { payload } = await (0, import_jose.jwtVerify)(token, secretKey);
+    return payload;
+  } catch (error) {
+    throw ErrorFactory.unauthorized(MOD.SESSION, "UNAUTHORIZED: No secure session token provided.");
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -979,6 +1073,7 @@ function resolveEffectiveAccess(base, override) {
   Converter,
   CropCycleStatus,
   ERROR_DICTIONARY,
+  EVERYONE,
   EmitterType,
   EnabledModule,
   ErrorFactory,
@@ -997,6 +1092,7 @@ function resolveEffectiveAccess(base, override) {
   PlantingMethod,
   RESOURCE_MODULE_MAP,
   RESOURCE_PATHS,
+  RESOURCE_REQUIREMENTS,
   ROLE_SECTIONS_BY_KEY,
   RelationshipType,
   RowOrientation,
@@ -1020,6 +1116,7 @@ function resolveEffectiveAccess(base, override) {
   canWrite,
   evaluateBaseAccess,
   extractAppCode,
+  findSpecificOverride,
   generateCanonicalId,
   generateInfrastructureFields,
   getAcceptedMimeTypes,
@@ -1035,5 +1132,6 @@ function resolveEffectiveAccess(base, override) {
   resolveEffectiveAccess,
   resolveError,
   resolveMenuVisibility,
+  verifyAndExtractSession,
   withAgriLogging
 });

package/dist/index.mjs

@@ -1,3 +1,6 @@
+// src/index.ts
+import { jwtVerify } from "jose";
+
 // src/logger.ts
 var SENSITIVE_KEYS = ["password", "token", "secret", "apiKey", "creditCard", "authorization"];
 function redact(obj) {
@@ -335,7 +338,7 @@ function generateCanonicalId() {
 }
 function generateInfrastructureFields(activeScope, availableScopes) {
   if (!activeScope || !availableScopes?.length) {
-    throw new Error("[generateInfrastructureFields] Missing scope context.");
+    throw ErrorFactory.unauthorized("[generateInfrastructureFields] Missing scope context.");
   }
   let companyId = null;
   let legalEntityId = null;
@@ -349,7 +352,7 @@ function generateInfrastructureFields(activeScope, availableScopes) {
     pointer = parentId ? availableScopes.find((s) => s.base44Id === parentId) || null : null;
   }
   if (!companyId) {
-    throw new Error("[generateInfrastructureFields] Could not resolve companyId from scope tree.");
+    throw ErrorFactory.unauthorized("[generateInfrastructureFields] Could not resolve companyId from scope tree.");
   }
   return {
     canonicalId: crypto.randomUUID(),
@@ -812,6 +815,76 @@ var ROLE_SECTIONS_BY_KEY = {
   records: [UserRole.OWNER, UserRole.MANAGER],
   adminSettings: []
 };
+var EVERYONE = Object.values(UserRole);
+var RESOURCE_REQUIREMENTS = {
+  [RESOURCE_PATHS.dashboard]: {
+    allowedRoles: EVERYONE
+  },
+  [RESOURCE_PATHS.operations]: {
+    allowedRoles: EVERYONE
+  },
+  // [RESOURCE_PATHS.equipment]: EVERYONE, 
+  // [RESOURCE_PATHS.safety]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.team]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.records]: ALL_OPERATIONS, 
+  // [RESOURCE_PATHS.adminSettings]: ALL_OPERATIONS,
+  // ── Records & Reports ──────────────────────────────────────────────────────
+  [RESOURCE_PATHS.documentHub]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  [RESOURCE_PATHS.documentHubTemplates]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  [RESOURCE_PATHS.documentHubFolder]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  [RESOURCE_PATHS.documentHubExtraction]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  [RESOURCE_PATHS.documentHubQueue]: {
+    allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
+    requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
+  },
+  // [RESOURCE_PATHS.analytics]: ALL_OPERATIONS,
+  // ── Admin Settings ─────────────────────────────────────────────────────────
+  [RESOURCE_PATHS.adminUserRoster]: {
+    allowedRoles: [UserRole.OWNER],
+    requiredPrivileges: [UserPrivilege.ADMIN]
+  },
+  [RESOURCE_PATHS.adminBlueprintsSites]: {
+    allowedRoles: [UserRole.OWNER],
+    requiredPrivileges: [UserPrivilege.ADMIN]
+  },
+  [RESOURCE_PATHS.adminRolesPermissions]: {
+    allowedRoles: [UserRole.OWNER],
+    requiredPrivileges: [UserPrivilege.ADMIN]
+  },
+  [RESOURCE_PATHS.adminCompanySettings]: {
+    allowedRoles: [UserRole.OWNER]
+  }
+  //  // ── Operations ────────────────────────────────────────────────────────────
+  // [RESOURCE_PATHS.farmManagement]: [EnabledModule.FARM_MANAGEMENT],
+  // [RESOURCE_PATHS.packhouse]: [EnabledModule.PACKHOUSE],
+  // [RESOURCE_PATHS.accommodation]: [EnabledModule.ACCOMMODATION],
+  //  // ── Equipment & Fleet ──────────────────────────────────────────────────────
+  // [RESOURCE_PATHS.equipPreStart]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.equipMaintenance]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.equipFuelRegister]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.equipCalibration]: AGRI_ONLY,
+  // [RESOURCE_PATHS.equipFleet]: ALL_OPERATIONS,
+  //  // ── Safety, Quality & Compliance ──────────────────────────────────────────
+  // [RESOURCE_PATHS.safetyAuditing]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.safetyFood]: AGRI_ONLY,
+  // [RESOURCE_PATHS.safetyWhs]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.safetyCleaning]: ALL_OPERATIONS,
+  //  // ── Team & HR ──────────────────────────────────────────────────────────────
+  // [RESOURCE_PATHS.teamStaff]: ALL_OPERATIONS,
+  // [RESOURCE_PATHS.teamTraining]: ALL_OPERATIONS,
+};
 function evaluateBaseAccess(resourcePath, session, requirements = {}) {
   if (!session?.role) return "NONE";
   if (session.role === UserRole.OWNER) return "WRITE";
@@ -830,44 +903,63 @@ function evaluateBaseAccess(resourcePath, session, requirements = {}) {
   }
   return session.role === UserRole.MANAGER ? "WRITE" : "READ";
 }
-async function assertTenantBoundary(db, requesterCompanyId, targets) {
-  if (!requesterCompanyId) {
-    throw ErrorFactory.internal(MOD.ADMIN, "Missing requester company context for boundary check.");
+function resolveEffectiveAccess(base, override) {
+  return override === void 0 || override === null ? base : override;
+}
+function findSpecificOverride(session, activeScopeId, resourcePath) {
+  const scopeOverrides = session.resourceOverrides?.[activeScopeId];
+  if (!scopeOverrides) return null;
+  const parts = resourcePath.split(".");
+  let currentPath = "";
+  let bestOverride = null;
+  for (const part of parts) {
+    currentPath = currentPath ? `${currentPath}.${part}` : part;
+    if (scopeOverrides[currentPath] !== void 0) {
+      bestOverride = scopeOverrides[currentPath];
+    }
+  }
+  return bestOverride;
+}
+async function assertTenantBoundary(db, session, targets) {
+  if (!session.companyId) {
+    throw ErrorFactory.internal(MOD.ADMIN, "Missing requester company context.");
   }
   if (targets.targetUserId) {
     const targetUserAssignments = await db.UserRoleAssignment.filter({
       userId: targets.targetUserId,
-      companyId: requesterCompanyId
+      companyId: session.companyId
     });
     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.");
+      console.error(`[SECURITY BREACH] User tried to modify targetUserId ${targets.targetUserId}`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid target user.");
     }
   }
   if (targets.authScopeId) {
-    let matchFound = false;
-    if (targets.expectedScopeType === "company" || !targets.expectedScopeType) {
-      const c = await db.Company.filter({ canonicalId: targets.authScopeId, id: requesterCompanyId });
-      if (c.length > 0) matchFound = true;
-    }
-    if (!matchFound && (targets.expectedScopeType === "legalEntity" || !targets.expectedScopeType)) {
-      const le = await db.LegalEntity.filter({ canonicalId: targets.authScopeId, companyId: requesterCompanyId });
-      if (le.length > 0) matchFound = true;
-    }
-    if (!matchFound && (targets.expectedScopeType === "facility" || !targets.expectedScopeType)) {
-      const fac = await db.Facility.filter({ canonicalId: targets.authScopeId, companyId: requesterCompanyId });
-      if (fac.length > 0) matchFound = true;
+    const matchedScope = session.availableScopes?.find(
+      (scope) => scope.authScopeId === targets.authScopeId
+    );
+    if (!matchedScope) {
+      console.error(`[SECURITY BREACH] Scope ${targets.authScopeId} not found in user's permitted list.`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Tenant boundary violation.");
     }
-    if (!matchFound) {
-      console.error(`[SECURITY BREACH/VALIDATION ERROR] Scope ${targets.authScopeId} not found for type ${targets.expectedScopeType} in company ${requesterCompanyId}`);
-      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid authorization scope level or tenant boundary violation.");
+    if (targets.expectedScopeType && matchedScope.type !== targets.expectedScopeType) {
+      console.error(`[VALIDATION ERROR] Expected type ${targets.expectedScopeType} but got ${matchedScope.type}`);
+      throw ErrorFactory.forbidden(MOD.ADMIN, ACT.EDIT, "Invalid authorization scope level.");
     }
   }
   return true;
 }
-function resolveEffectiveAccess(base, override) {
-  if (override === void 0 || override === null) return base;
-  return override;
+async function verifyAndExtractSession(token, secret) {
+  if (!token) {
+    throw ErrorFactory.unauthorized(MOD.SESSION, "UNAUTHORIZED: No secure session token provided.");
+  }
+  try {
+    const secretKey = new TextEncoder().encode(secret);
+    const { payload } = await jwtVerify(token, secretKey);
+    return payload;
+  } catch (error) {
+    throw ErrorFactory.unauthorized(MOD.SESSION, "UNAUTHORIZED: No secure session token provided.");
+  }
 }
 export {
   ACCESS_RANK,
@@ -883,6 +975,7 @@ export {
   Converter,
   CropCycleStatus,
   ERROR_DICTIONARY,
+  EVERYONE,
   EmitterType,
   EnabledModule,
   ErrorFactory,
@@ -901,6 +994,7 @@ export {
   PlantingMethod,
   RESOURCE_MODULE_MAP,
   RESOURCE_PATHS,
+  RESOURCE_REQUIREMENTS,
   ROLE_SECTIONS_BY_KEY,
   RelationshipType,
   RowOrientation,
@@ -924,6 +1018,7 @@ export {
   canWrite,
   evaluateBaseAccess,
   extractAppCode,
+  findSpecificOverride,
   generateCanonicalId,
   generateInfrastructureFields,
   getAcceptedMimeTypes,
@@ -939,5 +1034,6 @@ export {
   resolveEffectiveAccess,
   resolveError,
   resolveMenuVisibility,
+  verifyAndExtractSession,
   withAgriLogging
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litusarchieve18/agricore-utils",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Canonical Backend Utility Library for AgriCore",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -23,5 +23,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"
   },
-  "dependencies": {}
-}
+  "dependencies": {
+    "jose": "^6.2.2"
+  }
+}