guardrail-core 1.0.0

package/dist/rbac/permissions.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * RBAC Permission Checker
+ *
+ * Core permission checking logic for role-based access control.
+ * Provides functions to verify user permissions against required permissions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.roleHasPermission = roleHasPermission;
+exports.hasPermission = hasPermission;
+exports.hasAllPermissions = hasAllPermissions;
+exports.hasAnyPermission = hasAnyPermission;
+exports.compareRoles = compareRoles;
+exports.isRoleAtLeast = isRoleAtLeast;
+exports.getMinimumRoleForPermission = getMinimumRoleForPermission;
+exports.getEffectivePermissions = getEffectivePermissions;
+exports.checkTierAndPermission = checkTierAndPermission;
+exports.generatePermissionMatrix = generatePermissionMatrix;
+exports.canAssignRole = canAssignRole;
+exports.canRemoveMember = canRemoveMember;
+exports.isValidRole = isValidRole;
+exports.isValidPermission = isValidPermission;
+exports.parseRole = parseRole;
+const tier_config_1 = require("../tier-config");
+const types_1 = require("./types");
+// ============================================================================
+// PERMISSION CHECKING
+// ============================================================================
+/**
+ * Check if a role has a specific permission
+ */
+function roleHasPermission(role, permission) {
+    const permissions = types_1.ROLE_PERMISSIONS[role];
+    return permissions.includes(permission);
+}
+/**
+ * Check if a user has a specific permission based on their role
+ */
+function hasPermission(context, permission) {
+    if (!context.role || !types_1.ROLES.includes(context.role)) {
+        return {
+            allowed: false,
+            reason: 'Invalid or missing role',
+        };
+    }
+    const hasAccess = roleHasPermission(context.role, permission);
+    if (!hasAccess) {
+        const requiredRole = getMinimumRoleForPermission(permission);
+        return {
+            allowed: false,
+            reason: `Permission '${permission}' requires at least '${requiredRole}' role`,
+            requiredRole,
+            requiredPermissions: [permission],
+        };
+    }
+    return { allowed: true };
+}
+/**
+ * Check if a user has ALL of the specified permissions
+ */
+function hasAllPermissions(context, permissions) {
+    const missingPermissions = [];
+    for (const permission of permissions) {
+        if (!roleHasPermission(context.role, permission)) {
+            missingPermissions.push(permission);
+        }
+    }
+    if (missingPermissions.length > 0) {
+        return {
+            allowed: false,
+            reason: `Missing required permissions: ${missingPermissions.join(', ')}`,
+            requiredPermissions: missingPermissions,
+        };
+    }
+    return { allowed: true };
+}
+/**
+ * Check if a user has ANY of the specified permissions
+ */
+function hasAnyPermission(context, permissions) {
+    for (const permission of permissions) {
+        if (roleHasPermission(context.role, permission)) {
+            return { allowed: true };
+        }
+    }
+    return {
+        allowed: false,
+        reason: `Requires at least one of: ${permissions.join(', ')}`,
+        requiredPermissions: permissions,
+    };
+}
+// ============================================================================
+// ROLE COMPARISON
+// ============================================================================
+/**
+ * Compare two roles and return their relative hierarchy
+ * Returns positive if role1 > role2, negative if role1 < role2, 0 if equal
+ */
+function compareRoles(role1, role2) {
+    return types_1.ROLE_HIERARCHY[role1] - types_1.ROLE_HIERARCHY[role2];
+}
+/**
+ * Check if role1 is higher than or equal to role2 in the hierarchy
+ */
+function isRoleAtLeast(role, minimumRole) {
+    return types_1.ROLE_HIERARCHY[role] >= types_1.ROLE_HIERARCHY[minimumRole];
+}
+/**
+ * Get the minimum role required for a specific permission
+ */
+function getMinimumRoleForPermission(permission) {
+    // Check roles from lowest to highest
+    const orderedRoles = ['viewer', 'compliance-auditor', 'dev', 'admin', 'owner'];
+    for (const role of orderedRoles) {
+        if (roleHasPermission(role, permission)) {
+            return role;
+        }
+    }
+    // Default to owner if permission not found
+    return 'owner';
+}
+/**
+ * Get all permissions for a role (including inherited)
+ */
+function getEffectivePermissions(role) {
+    return [...types_1.ROLE_PERMISSIONS[role]];
+}
+// ============================================================================
+// TIER-BASED RESTRICTIONS
+// ============================================================================
+/**
+ * Check if a tier allows a specific operation with RBAC
+ */
+function checkTierAndPermission(context, permission, requiredTier) {
+    // First check permission
+    const permissionCheck = hasPermission(context, permission);
+    if (!permissionCheck.allowed) {
+        return permissionCheck;
+    }
+    // Then check tier if provided
+    if (context.tier) {
+        const userTierIndex = tier_config_1.TIER_ORDER.indexOf(context.tier);
+        const requiredTierIndex = tier_config_1.TIER_ORDER.indexOf(requiredTier);
+        if (userTierIndex < requiredTierIndex) {
+            return {
+                allowed: false,
+                reason: `This feature requires ${requiredTier} tier or higher`,
+            };
+        }
+    }
+    return { allowed: true };
+}
+// ============================================================================
+// PERMISSION MATRIX
+// ============================================================================
+/**
+ * Generate a permission matrix for UI display
+ */
+function generatePermissionMatrix() {
+    const matrix = {};
+    for (const role of types_1.ROLES) {
+        matrix[role] = {};
+        for (const permission of types_1.PERMISSIONS) {
+            matrix[role][permission] = roleHasPermission(role, permission);
+        }
+    }
+    return {
+        roles: [...types_1.ROLES],
+        permissions: [...types_1.PERMISSIONS],
+        matrix,
+    };
+}
+// ============================================================================
+// ROLE ASSIGNMENT VALIDATION
+// ============================================================================
+/**
+ * Check if a user can assign a specific role to another user
+ * Users can only assign roles lower than their own
+ */
+function canAssignRole(assignerRole, targetRole) {
+    // Must have assign_roles permission
+    if (!roleHasPermission(assignerRole, 'assign_roles')) {
+        return {
+            allowed: false,
+            reason: 'You do not have permission to assign roles',
+        };
+    }
+    // Cannot assign a role equal to or higher than your own (except owner can assign admin)
+    if (assignerRole === 'owner') {
+        return { allowed: true };
+    }
+    if (types_1.ROLE_HIERARCHY[targetRole] >= types_1.ROLE_HIERARCHY[assignerRole]) {
+        return {
+            allowed: false,
+            reason: `Cannot assign role '${targetRole}' - must be lower than your role '${assignerRole}'`,
+        };
+    }
+    return { allowed: true };
+}
+/**
+ * Check if a user can remove another user from the team
+ */
+function canRemoveMember(removerRole, targetRole) {
+    // Must have remove_members permission
+    if (!roleHasPermission(removerRole, 'remove_members')) {
+        return {
+            allowed: false,
+            reason: 'You do not have permission to remove members',
+        };
+    }
+    // Cannot remove owner
+    if (targetRole === 'owner') {
+        return {
+            allowed: false,
+            reason: 'Cannot remove the team owner',
+        };
+    }
+    // Cannot remove someone with equal or higher role (unless owner)
+    if (removerRole !== 'owner' && types_1.ROLE_HIERARCHY[targetRole] >= types_1.ROLE_HIERARCHY[removerRole]) {
+        return {
+            allowed: false,
+            reason: `Cannot remove a member with role '${targetRole}' - must have a lower role than yours`,
+        };
+    }
+    return { allowed: true };
+}
+// ============================================================================
+// VALIDATION UTILITIES
+// ============================================================================
+/**
+ * Validate if a string is a valid role
+ */
+function isValidRole(role) {
+    return types_1.ROLES.includes(role);
+}
+/**
+ * Validate if a string is a valid permission
+ */
+function isValidPermission(permission) {
+    return types_1.PERMISSIONS.includes(permission);
+}
+/**
+ * Get role from string with validation
+ */
+function parseRole(role) {
+    return isValidRole(role) ? role : null;
+}

package/dist/rbac/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * RBAC Type Definitions
+ *
+ * Core types for Role-Based Access Control system.
+ * Defines roles, permissions, and related interfaces.
+ */
+export declare const ROLES: readonly ["owner", "admin", "dev", "viewer", "compliance-auditor"];
+export type Role = typeof ROLES[number];
+/** Role hierarchy for permission inheritance (higher index = more permissions) */
+export declare const ROLE_HIERARCHY: Record<Role, number>;
+export declare const PERMISSIONS: readonly ["manage_team", "invite_members", "remove_members", "assign_roles", "view_audit", "export_audit", "manage_compliance", "view_compliance", "view_reports", "export_reports", "create_reports", "run_scan", "run_reality", "run_autopilot", "run_fix", "run_gate", "view_policies", "manage_policies", "create_policies", "view_projects", "create_projects", "delete_projects", "manage_project_settings", "manage_api_keys", "view_api_keys", "manage_webhooks", "manage_integrations", "view_billing", "manage_billing", "view_dashboard", "admin_settings"];
+export type Permission = typeof PERMISSIONS[number];
+/**
+ * Default permissions for each role.
+ * Roles inherit permissions from lower roles in the hierarchy.
+ */
+export declare const ROLE_PERMISSIONS: Record<Role, Permission[]>;
+export interface RoleAssignment {
+    userId: string;
+    teamId: string;
+    role: Role;
+    assignedBy: string;
+    assignedAt: Date;
+}
+export interface PermissionCheck {
+    allowed: boolean;
+    reason?: string;
+    requiredRole?: Role;
+    requiredPermissions?: Permission[];
+}
+export interface TeamMemberWithRole {
+    id: string;
+    userId: string;
+    email: string;
+    name: string;
+    role: Role;
+    joinedAt: Date;
+    lastActive?: Date;
+}
+export interface TeamInvitation {
+    id: string;
+    teamId: string;
+    email: string;
+    role: Role;
+    invitedBy: string;
+    expiresAt: Date;
+    status: 'pending' | 'accepted' | 'expired' | 'revoked';
+}
+export interface RBACContext {
+    userId: string;
+    teamId: string;
+    role: Role;
+    permissions: Permission[];
+    tier?: string;
+}
+export interface PermissionMatrix {
+    roles: Role[];
+    permissions: Permission[];
+    matrix: Record<Role, Record<Permission, boolean>>;
+}
+export interface RoleMetadata {
+    name: Role;
+    displayName: string;
+    description: string;
+    color: string;
+    icon: string;
+}
+export declare const ROLE_METADATA: Record<Role, RoleMetadata>;
+//# sourceMappingURL=types.d.ts.map

package/dist/rbac/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rbac/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,eAAO,MAAM,KAAK,oEAAqE,CAAC;AACxF,MAAM,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC;AAExC,kFAAkF;AAClF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAM/C,CAAC;AAMF,eAAO,MAAM,WAAW,wiBAiDd,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;AAMpD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,CA0GvD,CAAC;AAMF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,IAAI,CAAC;IACpB,mBAAmB,CAAC,EAAE,UAAU,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,IAAI,CAAC;IACf,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;CACxD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAMD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,YAAY,CAoCpD,CAAC"}

package/dist/rbac/types.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * RBAC Type Definitions
+ *
+ * Core types for Role-Based Access Control system.
+ * Defines roles, permissions, and related interfaces.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_METADATA = exports.ROLE_PERMISSIONS = exports.PERMISSIONS = exports.ROLE_HIERARCHY = exports.ROLES = void 0;
+// ============================================================================
+// ROLES
+// ============================================================================
+exports.ROLES = ['owner', 'admin', 'dev', 'viewer', 'compliance-auditor'];
+/** Role hierarchy for permission inheritance (higher index = more permissions) */
+exports.ROLE_HIERARCHY = {
+    'viewer': 0,
+    'compliance-auditor': 1,
+    'dev': 2,
+    'admin': 3,
+    'owner': 4,
+};
+// ============================================================================
+// PERMISSIONS
+// ============================================================================
+exports.PERMISSIONS = [
+    // Team Management
+    'manage_team',
+    'invite_members',
+    'remove_members',
+    'assign_roles',
+    // Audit & Compliance
+    'view_audit',
+    'export_audit',
+    'manage_compliance',
+    'view_compliance',
+    // Reports
+    'view_reports',
+    'export_reports',
+    'create_reports',
+    // Operations
+    'run_scan',
+    'run_reality',
+    'run_autopilot',
+    'run_fix',
+    'run_gate',
+    // Policies
+    'view_policies',
+    'manage_policies',
+    'create_policies',
+    // Projects
+    'view_projects',
+    'create_projects',
+    'delete_projects',
+    'manage_project_settings',
+    // API & Integrations
+    'manage_api_keys',
+    'view_api_keys',
+    'manage_webhooks',
+    'manage_integrations',
+    // Billing
+    'view_billing',
+    'manage_billing',
+    // Admin
+    'view_dashboard',
+    'admin_settings',
+];
+// ============================================================================
+// ROLE-PERMISSION MAPPING
+// ============================================================================
+/**
+ * Default permissions for each role.
+ * Roles inherit permissions from lower roles in the hierarchy.
+ */
+exports.ROLE_PERMISSIONS = {
+    'viewer': [
+        'view_dashboard',
+        'view_projects',
+        'view_reports',
+        'view_compliance',
+        'view_policies',
+    ],
+    'compliance-auditor': [
+        // Inherits viewer permissions
+        'view_dashboard',
+        'view_projects',
+        'view_reports',
+        'view_compliance',
+        'view_policies',
+        // Additional audit permissions
+        'view_audit',
+        'export_audit',
+        'export_reports',
+    ],
+    'dev': [
+        // Inherits viewer permissions
+        'view_dashboard',
+        'view_projects',
+        'view_reports',
+        'view_compliance',
+        'view_policies',
+        // Dev operations
+        'run_scan',
+        'run_reality',
+        'run_fix',
+        'run_gate',
+        'create_projects',
+        'view_api_keys',
+    ],
+    'admin': [
+        // Inherits dev permissions
+        'view_dashboard',
+        'view_projects',
+        'view_reports',
+        'view_compliance',
+        'view_policies',
+        'run_scan',
+        'run_reality',
+        'run_fix',
+        'run_gate',
+        'create_projects',
+        'view_api_keys',
+        // Admin permissions
+        'manage_team',
+        'invite_members',
+        'remove_members',
+        'assign_roles',
+        'run_autopilot',
+        'manage_policies',
+        'create_policies',
+        'delete_projects',
+        'manage_project_settings',
+        'manage_api_keys',
+        'manage_webhooks',
+        'manage_integrations',
+        'view_audit',
+        'export_audit',
+        'export_reports',
+        'create_reports',
+        'manage_compliance',
+        'view_billing',
+    ],
+    'owner': [
+        // All permissions
+        'manage_team',
+        'invite_members',
+        'remove_members',
+        'assign_roles',
+        'view_audit',
+        'export_audit',
+        'manage_compliance',
+        'view_compliance',
+        'view_reports',
+        'export_reports',
+        'create_reports',
+        'run_scan',
+        'run_reality',
+        'run_autopilot',
+        'run_fix',
+        'run_gate',
+        'view_policies',
+        'manage_policies',
+        'create_policies',
+        'view_projects',
+        'create_projects',
+        'delete_projects',
+        'manage_project_settings',
+        'manage_api_keys',
+        'view_api_keys',
+        'manage_webhooks',
+        'manage_integrations',
+        'view_billing',
+        'manage_billing',
+        'view_dashboard',
+        'admin_settings',
+    ],
+};
+exports.ROLE_METADATA = {
+    'owner': {
+        name: 'owner',
+        displayName: 'Owner',
+        description: 'Full access to all features including billing and team deletion',
+        color: '#8B5CF6', // purple
+        icon: 'crown',
+    },
+    'admin': {
+        name: 'admin',
+        displayName: 'Admin',
+        description: 'Manage team members, settings, and run all operations',
+        color: '#3B82F6', // blue
+        icon: 'shield',
+    },
+    'dev': {
+        name: 'dev',
+        displayName: 'Developer',
+        description: 'Run scans, fixes, and manage projects',
+        color: '#10B981', // green
+        icon: 'code',
+    },
+    'viewer': {
+        name: 'viewer',
+        displayName: 'Viewer',
+        description: 'View-only access to dashboards and reports',
+        color: '#6B7280', // gray
+        icon: 'eye',
+    },
+    'compliance-auditor': {
+        name: 'compliance-auditor',
+        displayName: 'Compliance Auditor',
+        description: 'View and export audit logs and compliance reports',
+        color: '#F59E0B', // amber
+        icon: 'clipboard-check',
+    },
+};