@lego-box/shell 1.0.5 → 1.0.7

package/src/migrations/types.ts

@@ -0,0 +1,207 @@
+/**
+ * Migration System Types and Interfaces
+ * 
+ * This file defines the core types for the RBAC migration system.
+ */
+
+/**
+ * Represents a single database migration
+ */
+export interface Migration {
+  id: string;
+  filename: string;
+  timestamp: number;
+  name: string;
+  status: 'pending' | 'applied' | 'failed' | 'rolled_back';
+  appliedAt: string | null;
+  errorMessage?: string;
+  checksum: string;
+  batch: number;
+}
+
+/**
+ * Migration history entry for audit trail
+ */
+export interface MigrationHistory {
+  id: string;
+  migrationId: string;
+  action: 'apply' | 'rollback' | 'fail';
+  executedAt: string;
+  executedBy: string;
+  errorMessage?: string;
+  duration: number;
+}
+
+/**
+ * Field type for PocketBase collection schema
+ */
+export type FieldType = 
+  | 'text' 
+  | 'number' 
+  | 'bool' 
+  | 'email' 
+  | 'url' 
+  | 'date' 
+  | 'select' 
+  | 'json' 
+  | 'file' 
+  | 'relation';
+
+/**
+ * Field schema definition
+ */
+export interface FieldSchema {
+  name: string;
+  type: FieldType;
+  required?: boolean;
+  unique?: boolean;
+  options?: {
+    min?: number;
+    max?: number;
+    pattern?: string;
+    values?: string[];
+    maxSelect?: number;
+    collectionId?: string;
+    cascadeDelete?: boolean;
+    [key: string]: any;
+  };
+}
+
+/**
+ * Collection schema definition
+ */
+export interface CollectionSchema {
+  name: string;
+  type?: 'base' | 'auth' | 'view';
+  fields: FieldSchema[];
+  indexes?: string[];
+  listRule?: string | null;
+  viewRule?: string | null;
+  createRule?: string | null;
+  updateRule?: string | null;
+  deleteRule?: string | null;
+  options?: {
+    allowEmailAuth?: boolean;
+    allowOAuth2Auth?: boolean;
+    allowUsernameAuth?: boolean;
+    exceptEmailDomains?: string[] | null;
+    onlyEmailDomains?: string[] | null;
+    minPasswordLength?: number;
+    requireEmail?: boolean;
+  };
+}
+
+/**
+ * Permission action types
+ */
+export type PermissionAction = 'create' | 'read' | 'update' | 'delete';
+
+/**
+ * Permission definition
+ */
+export interface Permission {
+  id?: string;
+  name: string;
+  action: PermissionAction;
+  collection: string;
+  description?: string;
+  resourceType: 'collection' | 'field' | 'custom';
+  resourceName?: string;
+}
+
+/**
+ * Role definition
+ */
+export interface Role {
+  id?: string;
+  name: string;
+  description?: string;
+  permissions: string[];
+  organization: string;
+  isDefault?: boolean;
+}
+
+/**
+ * Organization definition
+ */
+export interface Organization {
+  id?: string;
+  name: string;
+  slug: string;
+  description?: string;
+  settings?: Record<string, any>;
+  isActive?: boolean;
+}
+
+/**
+ * Extended User with RBAC fields
+ */
+export interface RBACUser {
+  id?: string;
+  email: string;
+  name: string;
+  avatar?: string;
+  organization: string;
+  role: string;
+  is_superuser?: boolean;
+  isActive?: boolean;
+  permissions?: string[];
+}
+
+/**
+ * Migration context passed to each migration
+ */
+export interface MigrationContext {
+  pb: any; // PocketBase instance
+  log: (message: string, type?: 'info' | 'success' | 'error' | 'warn') => void;
+  createCollection: (schema: CollectionSchema) => Promise<void>;
+  updateCollection: (name: string, schema: Partial<CollectionSchema>) => Promise<void>;
+  deleteCollection: (name: string) => Promise<void>;
+  collectionExists: (name: string) => Promise<boolean>;
+  insert: (collection: string, data: any) => Promise<any>;
+  update: (collection: string, id: string, data: any) => Promise<any>;
+  delete: (collection: string, id: string) => Promise<void>;
+}
+
+/**
+ * Migration function signature
+ */
+export type MigrationFunction = (context: MigrationContext) => Promise<void>;
+
+/**
+ * Migration module interface
+ */
+export interface MigrationModule {
+  up: MigrationFunction;
+  down?: MigrationFunction;
+  id: string;
+  name: string;
+}
+
+/**
+ * Options for migration runner
+ */
+export interface MigrationRunnerOptions {
+  pocketbaseUrl: string;
+  adminEmail?: string;
+  adminPassword?: string;
+  migrationsPath: string;
+  autoMigrate?: boolean;
+  onProgress?: (message: string, type?: 'info' | 'success' | 'error' | 'warn') => void;
+}
+
+/**
+ * API Rule generator function type
+ */
+export type APIRuleGenerator = (collectionName: string, action: PermissionAction) => string;
+
+/**
+ * Migration log entry for console logs
+ */
+export interface MigrationLog {
+  id?: string;
+  message: string;
+  type: 'command' | 'info' | 'success' | 'error';
+  timestamp: string;
+  sessionId?: string;
+}

package/src/migrations/utils.ts

@@ -0,0 +1,264 @@
+/**
+ * RBAC Utilities
+ * 
+ * Helper functions for managing permissions, roles, and API rules dynamically.
+ */
+
+import type { PermissionAction, Permission, Role, Organization } from './types';
+
+/**
+ * Generate a permission name from action and collection
+ */
+export function generatePermissionName(action: PermissionAction, collection: string): string {
+  return `${action}:${collection}`;
+}
+
+/**
+ * Parse a permission name into action and collection
+ */
+export function parsePermissionName(name: string): { action: PermissionAction; collection: string } | null {
+  const parts = name.split(':');
+  if (parts.length !== 2) return null;
+  
+  const action = parts[0] as PermissionAction;
+  if (!['create', 'read', 'update', 'delete'].includes(action)) return null;
+  
+  return { action, collection: parts[1] };
+}
+
+/**
+ * Generate all CRUD permissions for a collection
+ */
+export function generateCollectionPermissions(collection: string): string[] {
+  const actions: PermissionAction[] = ['create', 'read', 'update', 'delete'];
+  return actions.map(action => generatePermissionName(action, collection));
+}
+
+/**
+ * Generate API rule for a collection and action
+ */
+export function generateAPIRule(collection: string, action: PermissionAction): string {
+  const actionMap: Record<PermissionAction, string> = {
+    create: 'create',
+    read: 'read',
+    update: 'update',
+    delete: 'delete',
+  };
+
+  // Superusers can do everything
+  // Users with the specific permission in their role can access if in same organization
+  return `(@request.auth.is_superuser = true) || (@request.auth.role.permissions ?~ "${collection}:${actionMap[action]}" && @request.auth.organization = organization)`;
+}
+
+/**
+ * Generate all API rules for a collection
+ */
+export function generateAllAPIRules(collection: string): {
+  listRule: string;
+  viewRule: string;
+  createRule: string;
+  updateRule: string;
+  deleteRule: string;
+} {
+  return {
+    listRule: generateAPIRule(collection, 'read'),
+    viewRule: generateAPIRule(collection, 'read'),
+    createRule: generateAPIRule(collection, 'create'),
+    updateRule: generateAPIRule(collection, 'update'),
+    deleteRule: generateAPIRule(collection, 'delete'),
+  };
+}
+
+/**
+ * Check if user has a specific permission
+ */
+export function hasPermission(
+  userPermissions: string[],
+  rolePermissions: string[],
+  requiredPermission: string
+): boolean {
+  // Direct user permissions take precedence
+  if (userPermissions.includes(requiredPermission)) return true;
+  
+  // Check role permissions
+  if (rolePermissions.includes(requiredPermission)) return true;
+  
+  // Check wildcard permissions (e.g., "read:*" grants read access to all)
+  const [action] = requiredPermission.split(':');
+  if (userPermissions.includes(`${action}:*`)) return true;
+  if (rolePermissions.includes(`${action}:*`)) return true;
+  
+  return false;
+}
+
+/**
+ * Check if user has permission for a specific action on a collection
+ */
+export function hasCollectionPermission(
+  userPermissions: string[],
+  rolePermissions: string[],
+  collection: string,
+  action: PermissionAction
+): boolean {
+  const permissionName = generatePermissionName(action, collection);
+  return hasPermission(userPermissions, rolePermissions, permissionName);
+}
+
+/**
+ * Get all permissions for a user combining role and direct permissions
+ */
+export function getAllPermissions(
+  userPermissions: string[] = [],
+  rolePermissions: string[] = []
+): string[] {
+  return Array.from(new Set([...rolePermissions, ...userPermissions]));
+}
+
+/**
+ * Role permission builder
+ * Fluent API for building role permissions
+ */
+export class RolePermissionBuilder {
+  private permissions: string[] = [];
+
+  /**
+   * Grant permission for an action on a collection
+   */
+  can(action: PermissionAction, collection: string): this {
+    this.permissions.push(generatePermissionName(action, collection));
+    return this;
+  }
+
+  /**
+   * Grant all CRUD permissions for a collection
+   */
+  canManage(collection: string): this {
+    this.permissions.push(...generateCollectionPermissions(collection));
+    return this;
+  }
+
+  /**
+   * Grant read permission for a collection
+   */
+  canRead(collection: string): this {
+    this.permissions.push(generatePermissionName('read', collection));
+    return this;
+  }
+
+  /**
+   * Grant create permission for a collection
+   */
+  canCreate(collection: string): this {
+    this.permissions.push(generatePermissionName('create', collection));
+    return this;
+  }
+
+  /**
+   * Grant update permission for a collection
+   */
+  canUpdate(collection: string): this {
+    this.permissions.push(generatePermissionName('update', collection));
+    return this;
+  }
+
+  /**
+   * Grant delete permission for a collection
+   */
+  canDelete(collection: string): this {
+    this.permissions.push(generatePermissionName('delete', collection));
+    return this;
+  }
+
+  /**
+   * Build and return the permissions array
+   */
+  build(): string[] {
+    return Array.from(new Set(this.permissions));
+  }
+}
+
+/**
+ * Create a new permission builder
+ */
+export function definePermissions(): RolePermissionBuilder {
+  return new RolePermissionBuilder();
+}
+
+/**
+ * Default role definitions
+ */
+export const DEFAULT_ROLES = {
+  superuser: (orgId: string) => ({
+    name: 'Superuser',
+    description: 'Full system access with all permissions',
+    organization: orgId,
+    isDefault: false,
+  }),
+  
+  admin: (orgId: string) => ({
+    name: 'Admin',
+    description: 'Organization administrator',
+    organization: orgId,
+    isDefault: false,
+  }),
+  
+  user: (orgId: string) => ({
+    name: 'User',
+    description: 'Standard user',
+    organization: orgId,
+    isDefault: true,
+  }),
+};
+
+/**
+ * Default permissions for standard user role
+ */
+export function getDefaultUserPermissions(): string[] {
+  return [
+    'read:rbac_users',
+    'update:rbac_users',
+    'read:organizations',
+    'read:roles',
+    'read:permissions',
+  ];
+}
+
+/**
+ * Validate permission name format
+ */
+export function isValidPermissionName(name: string): boolean {
+  return parsePermissionName(name) !== null;
+}
+
+/**
+ * Extract collection names from permissions
+ */
+export function extractCollections(permissions: string[]): string[] {
+  const collections = new Set<string>();
+  for (const perm of permissions) {
+    const parsed = parsePermissionName(perm);
+    if (parsed) {
+      collections.add(parsed.collection);
+    }
+  }
+  return Array.from(collections);
+}
+
+/**
+ * Group permissions by collection
+ */
+export function groupPermissionsByCollection(permissions: string[]): Record<string, PermissionAction[]> {
+  const grouped: Record<string, PermissionAction[]> = {};
+  
+  for (const perm of permissions) {
+    const parsed = parsePermissionName(perm);
+    if (parsed) {
+      if (!grouped[parsed.collection]) {
+        grouped[parsed.collection] = [];
+      }
+      grouped[parsed.collection].push(parsed.action);
+    }
+  }
+  
+  return grouped;
+}