@talex-touch/utils 1.0.42 → 1.0.44

package/permission/index.ts

@@ -1,49 +1,146 @@
-export interface Permission {
-  /**
-   * permission id
-   */
-  id: symbol
-
-  /**
-   * permission name
-   */
-  name: string
-
-  /**
-   * permission description
-   */
-  description: string
+/**
+ * Permission Center
+ *
+ * Plugin permission management system.
+ */
+
+import type { SdkApiVersion } from '../plugin'
+import type {
+  ManifestPermissionReasons,
+  ManifestPermissions,
+  PluginPermissionStatus,
+} from './types'
+import {
+  checkSdkCompatibility,
+  CURRENT_SDK_VERSION,
+} from '../plugin/sdk-version'
+import {
+  DEFAULT_PERMISSIONS,
+  getPermissionIdCandidates,
+  normalizePermissionId,
+  permissionRegistry
+} from './registry'
+
+export * from './legacy'
+export * from './registry'
+export * from './types'
+
+/**
+ * Parse permissions from manifest
+ */
+export function parseManifestPermissions(manifest: {
+  permissions?: ManifestPermissions | string[]
+  permissionReasons?: ManifestPermissionReasons
+}): { required: string[], optional: string[], reasons: ManifestPermissionReasons } {
+  let required: string[] = []
+  let optional: string[] = []
+
+  if (Array.isArray(manifest.permissions)) {
+    // Legacy format: string[]
+    required = manifest.permissions
+  }
+  else if (manifest.permissions) {
+    // New format: { required, optional }
+    required = manifest.permissions.required || []
+    optional = manifest.permissions.optional || []
+  }
+
+  // Validate permission IDs
+  required = required
+    .map(id => normalizePermissionId(id))
+    .filter(id => permissionRegistry.has(id))
+  optional = optional
+    .map(id => normalizePermissionId(id))
+    .filter(id => permissionRegistry.has(id))
+
+  return {
+    required,
+    optional,
+    reasons: manifest.permissionReasons || {},
+  }
+}
+
+/**
+ * Get plugin permission status
+ */
+export function getPluginPermissionStatus(
+  pluginId: string,
+  sdkapi: SdkApiVersion | undefined,
+  declaredPermissions: { required: string[], optional: string[] },
+  grantedPermissions: string[],
+): PluginPermissionStatus {
+  const sdkCompat = checkSdkCompatibility(sdkapi, pluginId)
+  const required = [...new Set(declaredPermissions.required.map(id => normalizePermissionId(id)))]
+  const optional = [...new Set(declaredPermissions.optional.map(id => normalizePermissionId(id)))]
+  const granted = [...new Set(grantedPermissions.map(id => normalizePermissionId(id)))]
+  const defaultPermissions = [...new Set(DEFAULT_PERMISSIONS.map(id => normalizePermissionId(id)))]
+
+  // Calculate missing required permissions
+  const missingRequired = required.filter(
+    p => !granted.includes(p) && !defaultPermissions.includes(p),
+  )
+
+  // Calculate denied (not in granted and not default)
+  const allDeclared = [...required, ...optional]
+  const denied = allDeclared.filter(
+    p => !granted.includes(p) && !defaultPermissions.includes(p),
+  )
+
+  return {
+    pluginId,
+    sdkapi,
+    enforcePermissions: sdkCompat.enforcePermissions,
+    required,
+    optional,
+    granted: [...new Set([...granted, ...defaultPermissions])],
+    denied,
+    missingRequired,
+    warning: sdkCompat.warning,
+  }
+}
+
+/**
+ * Check if plugin has permission
+ */
+export function hasPermission(
+  status: PluginPermissionStatus,
+  permissionId: string,
+): boolean {
+  // If enforcement is disabled, allow all
+  if (!status.enforcePermissions) {
+    return true
+  }
+
+  // Check if granted
+  const candidates = getPermissionIdCandidates(permissionId)
+  return candidates.some(id => status.granted.includes(id))
 }
 
-export interface IPermissionCenter {
-  /**
-   * add a permission
-   * @param pluginScope plugin name
-   * @param permission permission
-   * @throws if permission already exists
-   */
-  addPermission: (pluginScope: string, permission: Permission) => void
-
-  /**
-   * remove a permission
-   * @param pluginScope plugin name
-   * @param permission permission
-   * @throws if permission not exists
-   */
-  delPermission: (pluginScope: string, permission: Permission) => void
-
-  /**
-   * if pluginScope has permission
-   * @param pluginScope plugin name
-   * @param permission permission
-   */
-  hasPermission: (pluginScope: string, permission: Permission) => boolean
-
-  /**
-   * get permission
-   * @param pluginScope plugin name
-   * @param permission permission id
-   * @returns permission
-   */
-  getPermission: (pluginScope: string, permission: symbol) => Permission
+/**
+ * Generate permission issue for plugin
+ */
+export function generatePermissionIssue(
+  status: PluginPermissionStatus,
+): { type: 'error' | 'warning', message: string, code: string, suggestion?: string } | null {
+  // SDK version warning
+  if (status.warning && !status.enforcePermissions) {
+    return {
+      type: 'warning',
+      message: status.warning,
+      code: status.sdkapi === undefined ? 'SDK_VERSION_MISSING' : 'SDK_VERSION_OUTDATED',
+      suggestion: `Add "sdkapi": ${CURRENT_SDK_VERSION} to manifest.json for permission enforcement.`,
+    }
+  }
+
+  // Missing required permissions (warning, not error - plugin can still run)
+  if (status.enforcePermissions && status.missingRequired.length > 0) {
+    return {
+      type: 'warning',
+      message: `Missing required permissions: ${status.missingRequired.join(', ')}`,
+      code: 'PERMISSION_MISSING',
+      suggestion: 'Grant permissions in Plugin Details > Permissions tab.',
+    }
+  }
+
+  return null
 }

package/permission/legacy.ts

@@ -0,0 +1,26 @@
+/**
+ * Legacy Permission Types
+ *
+ * For backward compatibility with old permission-center.ts
+ * @deprecated Use new permission system instead
+ */
+
+/**
+ * Legacy permission interface
+ */
+export interface Permission {
+  id: symbol
+  name: string
+  description?: string
+}
+
+/**
+ * Legacy permission center interface
+ */
+export interface IPermissionCenter {
+  addPermission: (pluginScope: string, permission: Permission) => void
+  delPermission: (pluginScope: string, permission: Permission) => void
+  hasPermission: (pluginScope: string, permission: Permission) => boolean
+  getPermission: (pluginScope: string, permission: symbol) => Permission
+  save: () => Promise<void>
+}

package/permission/registry.ts

@@ -0,0 +1,304 @@
+/**
+ * Permission Registry
+ *
+ * Defines all available permissions in the system.
+ */
+
+import type { PermissionDefinition } from './types'
+import { PermissionCategory, PermissionRiskLevel } from './types'
+
+/**
+ * All permission definitions
+ */
+export const PERMISSIONS: PermissionDefinition[] = [
+  // Filesystem permissions
+  {
+    id: 'fs.read',
+    category: PermissionCategory.FILESYSTEM,
+    risk: PermissionRiskLevel.MEDIUM,
+    nameKey: 'permission.fs.read.name',
+    descKey: 'permission.fs.read.desc',
+    icon: 'FileText',
+  },
+  {
+    id: 'fs.write',
+    category: PermissionCategory.FILESYSTEM,
+    risk: PermissionRiskLevel.HIGH,
+    nameKey: 'permission.fs.write.name',
+    descKey: 'permission.fs.write.desc',
+    icon: 'FilePen',
+  },
+  {
+    id: 'fs.execute',
+    category: PermissionCategory.FILESYSTEM,
+    risk: PermissionRiskLevel.HIGH,
+    nameKey: 'permission.fs.execute.name',
+    descKey: 'permission.fs.execute.desc',
+    icon: 'Terminal',
+  },
+  {
+    id: 'fs.tfile',
+    category: PermissionCategory.FILESYSTEM,
+    risk: PermissionRiskLevel.MEDIUM,
+    nameKey: 'permission.fs.tfile.name',
+    descKey: 'permission.fs.tfile.desc',
+    icon: 'FileText',
+  },
+
+  // Clipboard permissions
+  {
+    id: 'clipboard.read',
+    category: PermissionCategory.CLIPBOARD,
+    risk: PermissionRiskLevel.MEDIUM,
+    nameKey: 'permission.clipboard.read.name',
+    descKey: 'permission.clipboard.read.desc',
+    icon: 'ClipboardCopy',
+  },
+  {
+    id: 'clipboard.write',
+    category: PermissionCategory.CLIPBOARD,
+    risk: PermissionRiskLevel.LOW,
+    nameKey: 'permission.clipboard.write.name',
+    descKey: 'permission.clipboard.write.desc',
+    icon: 'ClipboardPaste',
+  },
+
+  // Network permissions
+  {
+    id: 'network.local',
+    category: PermissionCategory.NETWORK,
+    risk: PermissionRiskLevel.LOW,
+    nameKey: 'permission.network.local.name',
+    descKey: 'permission.network.local.desc',
+    icon: 'Wifi',
+  },
+  {
+    id: 'network.internet',
+    category: PermissionCategory.NETWORK,
+    risk: PermissionRiskLevel.MEDIUM,
+    nameKey: 'permission.network.internet.name',
+    descKey: 'permission.network.internet.desc',
+    icon: 'Globe',
+  },
+  {
+    id: 'network.download',
+    category: PermissionCategory.NETWORK,
+    risk: PermissionRiskLevel.MEDIUM,
+    nameKey: 'permission.network.download.name',
+    descKey: 'permission.network.download.desc',
+    icon: 'Download',
+  },
+
+  // System permissions
+  {
+    id: 'system.shell',
+    category: PermissionCategory.SYSTEM,
+    risk: PermissionRiskLevel.HIGH,
+    nameKey: 'permission.system.shell.name',
+    descKey: 'permission.system.shell.desc',
+    icon: 'Terminal',
+  },
+  {
+    id: 'system.notification',
+    category: PermissionCategory.SYSTEM,
+    risk: PermissionRiskLevel.LOW,
+    nameKey: 'permission.system.notification.name',
+    descKey: 'permission.system.notification.desc',
+    icon: 'Bell',
+  },
+  {
+    id: 'system.tray',
+    category: PermissionCategory.SYSTEM,
+    risk: PermissionRiskLevel.MEDIUM,
+    nameKey: 'permission.system.tray.name',
+    descKey: 'permission.system.tray.desc',
+    icon: 'PanelTop',
+  },
+
+  // Intelligence permissions
+  {
+    id: 'intelligence.basic',
+    category: PermissionCategory.INTELLIGENCE,
+    risk: PermissionRiskLevel.LOW,
+    nameKey: 'permission.intelligence.basic.name',
+    descKey: 'permission.intelligence.basic.desc',
+    icon: 'Bot',
+  },
+  {
+    id: 'intelligence.admin',
+    category: PermissionCategory.INTELLIGENCE,
+    risk: PermissionRiskLevel.HIGH,
+    nameKey: 'permission.intelligence.admin.name',
+    descKey: 'permission.intelligence.admin.desc',
+    icon: 'Shield',
+  },
+  {
+    id: 'intelligence.agents',
+    category: PermissionCategory.INTELLIGENCE,
+    risk: PermissionRiskLevel.HIGH,
+    nameKey: 'permission.intelligence.agents.name',
+    descKey: 'permission.intelligence.agents.desc',
+    icon: 'Users',
+  },
+
+  // Storage permissions
+  {
+    id: 'storage.plugin',
+    category: PermissionCategory.STORAGE,
+    risk: PermissionRiskLevel.LOW,
+    nameKey: 'permission.storage.plugin.name',
+    descKey: 'permission.storage.plugin.desc',
+    icon: 'Database',
+  },
+  {
+    id: 'storage.shared',
+    category: PermissionCategory.STORAGE,
+    risk: PermissionRiskLevel.MEDIUM,
+    nameKey: 'permission.storage.shared.name',
+    descKey: 'permission.storage.shared.desc',
+    icon: 'Share2',
+  },
+  {
+    id: 'storage.sqlite',
+    category: PermissionCategory.STORAGE,
+    risk: PermissionRiskLevel.MEDIUM,
+    nameKey: 'permission.storage.sqlite.name',
+    descKey: 'permission.storage.sqlite.desc',
+    icon: 'Database',
+  },
+
+  // Window permissions
+  {
+    id: 'window.create',
+    category: PermissionCategory.WINDOW,
+    risk: PermissionRiskLevel.LOW,
+    nameKey: 'permission.window.create.name',
+    descKey: 'permission.window.create.desc',
+    icon: 'AppWindow',
+  },
+  {
+    id: 'window.capture',
+    category: PermissionCategory.WINDOW,
+    risk: PermissionRiskLevel.HIGH,
+    nameKey: 'permission.window.capture.name',
+    descKey: 'permission.window.capture.desc',
+    icon: 'Camera',
+  },
+]
+
+export function normalizePermissionId(id: string): string {
+  return id
+}
+
+export function getPermissionIdCandidates(id: string): string[] {
+  return [normalizePermissionId(id)]
+}
+
+/**
+ * Permission registry class
+ */
+export class PermissionRegistry {
+  private permissions: Map<string, PermissionDefinition> = new Map()
+
+  constructor() {
+    // Register all built-in permissions
+    PERMISSIONS.forEach((p) => this.permissions.set(normalizePermissionId(p.id), p))
+  }
+
+  /**
+   * Get permission definition by ID
+   */
+  get(id: string): PermissionDefinition | undefined {
+    return this.permissions.get(normalizePermissionId(id))
+  }
+
+  /**
+   * Get all permissions
+   */
+  all(): PermissionDefinition[] {
+    return Array.from(this.permissions.values())
+  }
+
+  /**
+   * Get permissions by category
+   */
+  byCategory(category: PermissionCategory): PermissionDefinition[] {
+    return this.all().filter(p => p.category === category)
+  }
+
+  /**
+   * Get permissions by risk level
+   */
+  byRisk(risk: PermissionRiskLevel): PermissionDefinition[] {
+    return this.all().filter(p => p.risk === risk)
+  }
+
+  /**
+   * Check if permission exists
+   */
+  has(id: string): boolean {
+    return this.permissions.has(normalizePermissionId(id))
+  }
+
+  /**
+   * Register custom permission
+   */
+  register(permission: PermissionDefinition): void {
+    this.permissions.set(normalizePermissionId(permission.id), permission)
+  }
+}
+
+/**
+ * Singleton permission registry
+ */
+export const permissionRegistry = new PermissionRegistry()
+
+/**
+ * Permission ID constants for type safety
+ */
+export const PermissionIds = {
+  // Filesystem
+  FS_READ: 'fs.read',
+  FS_WRITE: 'fs.write',
+  FS_EXECUTE: 'fs.execute',
+  FS_TFILE: 'fs.tfile',
+
+  // Clipboard
+  CLIPBOARD_READ: 'clipboard.read',
+  CLIPBOARD_WRITE: 'clipboard.write',
+
+  // Network
+  NETWORK_LOCAL: 'network.local',
+  NETWORK_INTERNET: 'network.internet',
+  NETWORK_DOWNLOAD: 'network.download',
+
+  // System
+  SYSTEM_SHELL: 'system.shell',
+  SYSTEM_NOTIFICATION: 'system.notification',
+  SYSTEM_TRAY: 'system.tray',
+
+  // Intelligence
+  INTELLIGENCE_BASIC: 'intelligence.basic',
+  INTELLIGENCE_ADMIN: 'intelligence.admin',
+  INTELLIGENCE_AGENTS: 'intelligence.agents',
+
+  // Storage
+  STORAGE_PLUGIN: 'storage.plugin',
+  STORAGE_SHARED: 'storage.shared',
+  STORAGE_SQLITE: 'storage.sqlite',
+
+  // Window
+  WINDOW_CREATE: 'window.create',
+  WINDOW_CAPTURE: 'window.capture',
+} as const
+
+export type PermissionId = (typeof PermissionIds)[keyof typeof PermissionIds]
+
+/**
+ * Default permissions that are auto-granted
+ */
+export const DEFAULT_PERMISSIONS: string[] = [
+  PermissionIds.STORAGE_PLUGIN,
+  PermissionIds.CLIPBOARD_WRITE,
+  PermissionIds.WINDOW_CREATE,
+]

package/permission/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Permission System Types
+ *
+ * Defines the permission model for plugin security.
+ */
+
+/**
+ * Permission category
+ */
+export enum PermissionCategory {
+  FILESYSTEM = 'fs',
+  CLIPBOARD = 'clipboard',
+  NETWORK = 'network',
+  SYSTEM = 'system',
+  INTELLIGENCE = 'intelligence',
+  STORAGE = 'storage',
+  WINDOW = 'window',
+}
+
+/**
+ * Risk level for permissions
+ */
+export enum PermissionRiskLevel {
+  LOW = 'low',
+  MEDIUM = 'medium',
+  HIGH = 'high',
+}
+
+/**
+ * Permission definition
+ */
+export interface PermissionDefinition {
+  /** Permission ID (e.g., 'fs.read') */
+  id: string
+  /** Category */
+  category: PermissionCategory
+  /** Risk level */
+  risk: PermissionRiskLevel
+  /** i18n key for display name */
+  nameKey: string
+  /** i18n key for description */
+  descKey: string
+  /** Icon name (lucide icon) */
+  icon?: string
+}
+
+/**
+ * Permission grant record
+ */
+export interface PermissionGrant {
+  /** Plugin ID */
+  pluginId: string
+  /** Permission ID */
+  permissionId: string
+  /** Grant timestamp */
+  grantedAt: number
+  /** How it was granted */
+  grantedBy: 'user' | 'auto' | 'trust'
+  /** Expiration timestamp (optional) */
+  expiresAt?: number
+}
+
+/**
+ * Permission denial record
+ */
+export interface PermissionDenial {
+  /** Plugin ID */
+  pluginId: string
+  /** Permission ID */
+  permissionId: string
+  /** Denial timestamp */
+  deniedAt: number
+  /** Reason for denial */
+  reason?: string
+}
+
+/**
+ * Permission check result
+ */
+export interface PermissionCheckResult {
+  /** Permission ID */
+  permissionId: string
+  /** Whether permission is granted */
+  granted: boolean
+  /** Grant details if granted */
+  grant?: PermissionGrant
+  /** Whether enforcement is active (sdkapi check) */
+  enforced: boolean
+  /** Warning message if any */
+  warning?: string
+}
+
+/**
+ * Plugin permission status
+ */
+export interface PluginPermissionStatus {
+  /** Plugin ID */
+  pluginId: string
+  /** SDK API version */
+  sdkapi?: number
+  /** Whether permission enforcement is active */
+  enforcePermissions: boolean
+  /** Required permissions from manifest */
+  required: string[]
+  /** Optional permissions from manifest */
+  optional: string[]
+  /** Granted permissions */
+  granted: string[]
+  /** Denied permissions */
+  denied: string[]
+  /** Missing required permissions */
+  missingRequired: string[]
+  /** Compatibility warning */
+  warning?: string
+}
+
+/**
+ * Permission request for UI prompt
+ */
+export interface PermissionRequest {
+  /** Plugin ID */
+  pluginId: string
+  /** Plugin display name */
+  pluginName: string
+  /** Permission ID */
+  permissionId: string
+  /** Reason from manifest */
+  reason?: string
+  /** Context of the request */
+  context?: Record<string, unknown>
+}
+
+/**
+ * Audit log entry
+ */
+export interface PermissionAuditLog {
+  /** Log ID */
+  id: string
+  /** Timestamp */
+  timestamp: number
+  /** Plugin ID */
+  pluginId: string
+  /** Permission ID */
+  permissionId: string
+  /** Action type */
+  action: 'granted' | 'denied' | 'revoked' | 'used' | 'blocked'
+  /** Additional context */
+  context?: Record<string, unknown>
+}
+
+/**
+ * Manifest permission declaration
+ */
+export interface ManifestPermissions {
+  /** Required permissions - plugin won't work without these */
+  required?: string[]
+  /** Optional permissions - can be granted later */
+  optional?: string[]
+}
+
+/**
+ * Permission reasons in manifest
+ */
+export type ManifestPermissionReasons = Record<string, string>