@ebowwa/sandbox 0.1.1

package/src/core/permissions.ts

@@ -0,0 +1,409 @@
+/**
+ * Permissions Primitive
+ *
+ * Composable permission enforcement for sandbox execution.
+ * Each permission can be independently granted or denied.
+ */
+
+import type {
+  Permissions,
+  PermissionLevel,
+  FileSystemPermission,
+  NetworkPermission,
+  EnvironmentPermission,
+  ProcessPermission,
+} from "./types.js";
+
+/**
+ * Permission Checker
+ *
+ * Validates permissions against allowed operations.
+ */
+export class PermissionChecker {
+  constructor(private permissions: Permissions) {}
+
+  /**
+   * Check if filesystem read is allowed
+   */
+  canReadFile(path?: string): boolean {
+    const fs = this.permissions.fs;
+    if (!fs?.read) return false;
+
+    if (path) {
+      return this.isPathAllowed(path, fs);
+    }
+    return true;
+  }
+
+  /**
+   * Check if filesystem write is allowed
+   */
+  canWriteFile(path?: string): boolean {
+    const fs = this.permissions.fs;
+    if (!fs?.write) return false;
+
+    if (path) {
+      return this.isPathAllowed(path, fs);
+    }
+    return true;
+  }
+
+  /**
+   * Check if filesystem delete is allowed
+   */
+  canDeleteFile(path?: string): boolean {
+    const fs = this.permissions.fs;
+    if (!fs?.delete) return false;
+
+    if (path) {
+      return this.isPathAllowed(path, fs);
+    }
+    return true;
+  }
+
+  /**
+   * Check if network outbound is allowed
+   */
+  canConnect(host?: string): boolean {
+    const net = this.permissions.network;
+    if (!net?.outbound) return false;
+
+    if (host) {
+      return this.isHostAllowed(host, net);
+    }
+    return true;
+  }
+
+  /**
+   * Check if network inbound is allowed
+   */
+  canListen(port?: number): boolean {
+    const net = this.permissions.network;
+    if (!net?.inbound) return false;
+
+    // Could add port-based restrictions here
+    return true;
+  }
+
+  /**
+   * Check if environment read is allowed
+   */
+  canReadEnv(key?: string): boolean {
+    const env = this.permissions.env;
+    if (!env?.read) return false;
+
+    if (key && env.allowedKeys) {
+      return env.allowedKeys.includes(key);
+    }
+    return true;
+  }
+
+  /**
+   * Check if environment write is allowed
+   */
+  canWriteEnv(key?: string): boolean {
+    const env = this.permissions.env;
+    if (!env?.write) return false;
+
+    if (key && env.allowedKeys) {
+      return env.allowedKeys.includes(key);
+    }
+    return true;
+  }
+
+  /**
+   * Check if process spawn is allowed
+   */
+  canSpawnProcess(command?: string): boolean {
+    const proc = this.permissions.process;
+    if (!proc?.spawn) return false;
+
+    if (command && proc.allowedCommands) {
+      return proc.allowedCommands.some(cmd =>
+        command.startsWith(cmd) || command === cmd
+      );
+    }
+    return true;
+  }
+
+  /**
+   * Get memory limit
+   */
+  getMemoryLimit(): number | undefined {
+    return this.permissions.memory?.maxBytes;
+  }
+
+  /**
+   * Get CPU limits
+   */
+  getCpuLimits(): { maxPercent?: number; maxTimeMs?: number } {
+    const cpu = this.permissions.cpu;
+    return {
+      maxPercent: cpu?.maxPercent,
+      maxTimeMs: cpu?.maxTimeMs,
+    };
+  }
+
+  /**
+   * Check if path is allowed
+   */
+  private isPathAllowed(path: string, fs: FileSystemPermission): boolean {
+    // Check denied paths first
+    if (fs.deniedPaths) {
+      for (const denied of fs.deniedPaths) {
+        if (path.startsWith(denied)) {
+          return false;
+        }
+      }
+    }
+
+    // Check allowed paths
+    if (fs.allowedPaths) {
+      for (const allowed of fs.allowedPaths) {
+        if (path.startsWith(allowed)) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Check if host is allowed
+   */
+  private isHostAllowed(host: string, net: NetworkPermission): boolean {
+    // Check denied hosts first
+    if (net.deniedHosts) {
+      for (const denied of net.deniedHosts) {
+        if (host === denied || host.endsWith(`.${denied}`)) {
+          return false;
+        }
+      }
+    }
+
+    // Check allowed hosts
+    if (net.allowedHosts) {
+      for (const allowed of net.allowedHosts) {
+        if (host === allowed || host.endsWith(`.${allowed}`)) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    return true;
+  }
+}
+
+/**
+ * Permission Builder
+ *
+ * Fluent API for building permission sets.
+ */
+export class PermissionBuilder {
+  private permissions: Permissions = {};
+
+  filesystem(options: Partial<FileSystemPermission>): this {
+    this.permissions.fs = {
+      ...this.permissions.fs,
+      ...options,
+    };
+    return this;
+  }
+
+  network(options: Partial<NetworkPermission>): this {
+    this.permissions.network = {
+      ...this.permissions.network,
+      ...options,
+    };
+    return this;
+  }
+
+  environment(options: Partial<EnvironmentPermission>): this {
+    this.permissions.env = {
+      ...this.permissions.env,
+      ...options,
+    };
+    return this;
+  }
+
+  process(options: Partial<ProcessPermission>): this {
+    this.permissions.process = {
+      ...this.permissions.process,
+      ...options,
+    };
+    return this;
+  }
+
+  memory(maxBytes: number): this {
+    this.permissions.memory = { maxBytes };
+    return this;
+  }
+
+  cpu(options: { maxPercent?: number; maxTimeMs?: number }): this {
+    this.permissions.cpu = options;
+    return this;
+  }
+
+  build(): Permissions {
+    return this.permissions;
+  }
+}
+
+/**
+ * Create permission set from level
+ */
+export function createPermissions(level: PermissionLevel): Permissions {
+  switch (level) {
+    case "isolated":
+      return {};
+
+    case "readonly":
+      return {
+        fs: { read: true },
+      };
+
+    case "network":
+      return {
+        fs: { read: true },
+        network: { outbound: true },
+      };
+
+    case "filesystem":
+      return {
+        fs: { read: true, write: true, delete: true },
+        network: { outbound: true, inbound: true },
+      };
+
+    case "admin":
+      return {
+        fs: { read: true, write: true, delete: true },
+        network: { outbound: true, inbound: true },
+        env: { read: true, write: true },
+        process: { spawn: true },
+      };
+
+    case "sudo":
+      return {
+        fs: { read: true, write: true, delete: true },
+        network: { outbound: true, inbound: true },
+        env: { read: true, write: true },
+        process: { spawn: true },
+      };
+  }
+}
+
+/**
+ * Merge permissions (intersection - most restrictive)
+ */
+export function mergePermissions(...perms: Permissions[]): Permissions {
+  const result: Permissions = {};
+
+  // Filesystem
+  const fsPerms = perms.filter(p => p.fs);
+  if (fsPerms.length === perms.length) {
+    result.fs = {
+      read: fsPerms.every(p => p.fs?.read),
+      write: fsPerms.every(p => p.fs?.write),
+      delete: fsPerms.every(p => p.fs?.delete),
+      allowedPaths: intersectArrays(
+        ...fsPerms.map(p => p.fs?.allowedPaths).filter(Boolean) as string[][]
+      ),
+      deniedPaths: unionArrays(
+        ...fsPerms.map(p => p.fs?.deniedPaths).filter(Boolean) as string[][]
+      ),
+    };
+  }
+
+  // Network
+  const netPerms = perms.filter(p => p.network);
+  if (netPerms.length === perms.length) {
+    result.network = {
+      outbound: netPerms.every(p => p.network?.outbound),
+      inbound: netPerms.every(p => p.network?.inbound),
+      allowedHosts: intersectArrays(
+        ...netPerms.map(p => p.network?.allowedHosts).filter(Boolean) as string[][]
+      ),
+      deniedHosts: unionArrays(
+        ...netPerms.map(p => p.network?.deniedHosts).filter(Boolean) as string[][]
+      ),
+    };
+  }
+
+  // Memory (take minimum)
+  const memoryLimits = perms
+    .map(p => p.memory?.maxBytes)
+    .filter(Boolean) as number[];
+  if (memoryLimits.length > 0) {
+    result.memory = { maxBytes: Math.min(...memoryLimits) };
+  }
+
+  // CPU (take minimums)
+  const cpuPerms = perms.filter(p => p.cpu);
+  if (cpuPerms.length > 0) {
+    result.cpu = {
+      maxPercent: Math.min(
+        ...cpuPerms.map(p => p.cpu?.maxPercent ?? 100)
+      ),
+      maxTimeMs: Math.min(
+        ...cpuPerms.map(p => p.cpu?.maxTimeMs ?? Infinity)
+      ),
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Check if permission level implies another
+ */
+export function impliesPermission(
+  level: PermissionLevel,
+  required: PermissionLevel
+): boolean {
+  const levels: PermissionLevel[] = [
+    "isolated",
+    "readonly",
+    "network",
+    "filesystem",
+    "admin",
+    "sudo",
+  ];
+  return levels.indexOf(level) >= levels.indexOf(required);
+}
+
+/**
+ * Upgrade permissions to higher level
+ */
+export function upgradePermissions(
+  current: Permissions,
+  newLevel: PermissionLevel
+): Permissions {
+  const newPerms = createPermissions(newLevel);
+  return mergePermissions(current, newPerms);
+}
+
+// Helper functions
+function intersectArrays<T>(...arrays: T[][]): T[] {
+  if (arrays.length === 0) return [];
+  if (arrays.length === 1) return arrays[0];
+
+  return arrays[0].filter(item =>
+    arrays.every(arr => arr.includes(item))
+  );
+}
+
+function unionArrays<T>(...arrays: T[][]): T[] {
+  const set = new Set<T>();
+  for (const arr of arrays) {
+    for (const item of arr) {
+      set.add(item);
+    }
+  }
+  return Array.from(set);
+}
+
+// Re-export from types
+export { permissionsFromLevel } from "./types.js";