@sentriflow/core 0.1.2 → 0.1.4

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "@sentriflow/core",
-  "version": "0.1.2",
-  "description": "SentriFlow core engine for network configuration validation",
-  "license": "Apache-2.0",
-  "module": "src/index.ts",
-  "type": "module",
-  "exports": {
-    ".": "./src/index.ts",
-    "./helpers": "./src/helpers/index.ts",
-    "./helpers/common": "./src/helpers/common/index.ts",
-    "./helpers/arista": "./src/helpers/arista/index.ts",
-    "./helpers/aruba": "./src/helpers/aruba/index.ts",
-    "./helpers/cisco": "./src/helpers/cisco/index.ts",
-    "./helpers/cumulus": "./src/helpers/cumulus/index.ts",
-    "./helpers/extreme": "./src/helpers/extreme/index.ts",
-    "./helpers/fortinet": "./src/helpers/fortinet/index.ts",
-    "./helpers/huawei": "./src/helpers/huawei/index.ts",
-    "./helpers/juniper": "./src/helpers/juniper/index.ts",
-    "./helpers/mikrotik": "./src/helpers/mikrotik/index.ts",
-    "./helpers/nokia": "./src/helpers/nokia/index.ts",
-    "./helpers/paloalto": "./src/helpers/paloalto/index.ts",
-    "./helpers/vyos": "./src/helpers/vyos/index.ts"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sentriflow/sentriflow.git",
-    "directory": "packages/core"
-  },
-  "homepage": "https://github.com/sentriflow/sentriflow#readme",
-  "bugs": {
-    "url": "https://github.com/sentriflow/sentriflow/issues"
-  },
-  "keywords": [
-    "network",
-    "configuration",
-    "validation",
-    "security",
-    "cisco",
-    "juniper",
-    "arista",
-    "firewall",
-    "linter",
-    "helpers"
-  ],
-  "files": [
-    "src",
-    "LICENSE",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "bun-types": "latest"
-  },
-  "peerDependencies": {
-    "typescript": "^5.0.0"
-  }
-}
+{
+  "name": "@sentriflow/core",
+  "version": "0.1.4",
+  "description": "SentriFlow core engine for network configuration validation",
+  "license": "Apache-2.0",
+  "module": "src/index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./helpers": "./src/helpers/index.ts",
+    "./helpers/common": "./src/helpers/common/index.ts",
+    "./helpers/arista": "./src/helpers/arista/index.ts",
+    "./helpers/aruba": "./src/helpers/aruba/index.ts",
+    "./helpers/cisco": "./src/helpers/cisco/index.ts",
+    "./helpers/cumulus": "./src/helpers/cumulus/index.ts",
+    "./helpers/extreme": "./src/helpers/extreme/index.ts",
+    "./helpers/fortinet": "./src/helpers/fortinet/index.ts",
+    "./helpers/huawei": "./src/helpers/huawei/index.ts",
+    "./helpers/juniper": "./src/helpers/juniper/index.ts",
+    "./helpers/mikrotik": "./src/helpers/mikrotik/index.ts",
+    "./helpers/nokia": "./src/helpers/nokia/index.ts",
+    "./helpers/paloalto": "./src/helpers/paloalto/index.ts",
+    "./helpers/vyos": "./src/helpers/vyos/index.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sentriflow/sentriflow.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/sentriflow/sentriflow#readme",
+  "bugs": {
+    "url": "https://github.com/sentriflow/sentriflow/issues"
+  },
+  "keywords": [
+    "network",
+    "configuration",
+    "validation",
+    "security",
+    "cisco",
+    "juniper",
+    "arista",
+    "firewall",
+    "linter",
+    "helpers"
+  ],
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "bun-types": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -15,6 +15,9 @@ export * from './errors';
 // SEC-012: Encrypted rule pack loader
 export * from './pack-loader';
 
+// Pack Provider abstraction for cloud licensing extension
+export * from './pack-provider';
+
 // SEC-001: Declarative rules and sandboxed execution
 export * from './types/DeclarativeRule';
 export * from './engine/SandboxedExecutor';

package/src/pack-provider/LocalPackProvider.ts

@@ -0,0 +1,194 @@
+/**
+ * Local Pack Provider
+ *
+ * Default IPackProvider implementation for local file-based pack loading.
+ * Uses the existing loadEncryptedPack function for .grpx files.
+ *
+ * @module pack-provider/LocalPackProvider
+ */
+
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve, basename } from 'path';
+import type {
+  IPackProvider,
+  PackUpdateInfo,
+  PackProviderLicenseStatus,
+  LocalPackProviderOptions,
+} from './PackProvider';
+import type { RulePack } from '../types/IRule';
+import { loadEncryptedPack, validatePackFormat, PackLoadError } from '../pack-loader';
+
+/**
+ * Local file-based pack provider
+ *
+ * Loads encrypted rule packs (.grpx) from the local filesystem
+ * using a license key for decryption.
+ *
+ * @example
+ * ```typescript
+ * const provider = new LocalPackProvider({
+ *   licenseKey: 'XXXX-XXXX-XXXX-XXXX',
+ *   packPaths: ['./rules/security.grpx', './rules/compliance.grpx'],
+ * });
+ *
+ * const packs = await provider.loadPacks();
+ * ```
+ */
+export class LocalPackProvider implements IPackProvider {
+  private readonly licenseKey: string;
+  private readonly packPaths: string[];
+  private readonly machineId?: string;
+  private readonly strict: boolean;
+
+  private loadedPacks: RulePack[] = [];
+  private lastLoadError: string | null = null;
+
+  constructor(options: LocalPackProviderOptions) {
+    this.licenseKey = options.licenseKey;
+    this.packPaths = options.packPaths.map((p) => resolve(p));
+    this.machineId = options.machineId;
+    this.strict = options.strict ?? false;
+  }
+
+  /**
+   * Load all configured pack files
+   *
+   * @returns Promise resolving to array of loaded RulePacks
+   * @throws Error if strict mode and any pack fails to load
+   */
+  async loadPacks(): Promise<RulePack[]> {
+    const packs: RulePack[] = [];
+    const errors: string[] = [];
+
+    for (const packPath of this.packPaths) {
+      try {
+        const pack = await this.loadSinglePack(packPath);
+        packs.push(pack);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const fileName = basename(packPath);
+
+        if (this.strict) {
+          throw new Error(`Failed to load pack ${fileName}: ${message}`);
+        }
+
+        errors.push(`${fileName}: ${message}`);
+        console.warn(`Warning: Failed to load pack ${fileName}: ${message}`);
+      }
+    }
+
+    this.loadedPacks = packs;
+    this.lastLoadError = errors.length > 0 ? errors.join('; ') : null;
+
+    return packs;
+  }
+
+  /**
+   * Check for updates (not supported for local files)
+   *
+   * @returns Empty array - local files don't support updates
+   */
+  async checkForUpdates(): Promise<PackUpdateInfo[]> {
+    // Local file provider doesn't support update checking
+    return [];
+  }
+
+  /**
+   * Apply updates (not supported for local files)
+   *
+   * @returns 0 - local files don't support updates
+   */
+  async applyUpdates(_feedIds?: string[]): Promise<number> {
+    // Local file provider doesn't support updates
+    return 0;
+  }
+
+  /**
+   * Get license status
+   *
+   * Returns basic status based on loaded packs.
+   */
+  async getLicenseStatus(): Promise<PackProviderLicenseStatus> {
+    return {
+      isValid: this.loadedPacks.length > 0,
+      tier: 'community', // Local packs don't have tier info
+      entitledFeeds: this.loadedPacks.map((p) => p.name),
+      isOffline: true, // Local is always "offline"
+      cachedPackCount: this.loadedPacks.length,
+      totalRuleCount: this.loadedPacks.reduce((sum, p) => sum + p.rules.length, 0),
+      hasUpdates: false,
+    };
+  }
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void {
+    // Clear loaded packs
+    this.loadedPacks = [];
+  }
+
+  /**
+   * Load a single pack file
+   *
+   * @param packPath - Path to the .grpx file
+   * @returns Loaded RulePack
+   */
+  private async loadSinglePack(packPath: string): Promise<RulePack> {
+    // Check file exists
+    if (!existsSync(packPath)) {
+      throw new Error(`Pack file not found: ${packPath}`);
+    }
+
+    // Read binary data
+    const packData = await readFile(packPath);
+
+    // Validate format
+    if (!validatePackFormat(packData)) {
+      throw new Error('Invalid pack format');
+    }
+
+    // Load and decrypt
+    const loadedPack = await loadEncryptedPack(packData, {
+      licenseKey: this.licenseKey,
+      machineId: this.machineId,
+      timeout: 10000,
+    });
+
+    // Convert LoadedPack to RulePack
+    return {
+      ...loadedPack.metadata,
+      priority: 200, // High priority for licensed packs
+      rules: loadedPack.rules,
+    };
+  }
+
+  /**
+   * Get the last load error message (if any)
+   */
+  getLastError(): string | null {
+    return this.lastLoadError;
+  }
+
+  /**
+   * Get list of configured pack paths
+   */
+  getPackPaths(): readonly string[] {
+    return this.packPaths;
+  }
+}
+
+/**
+ * Create a local pack provider
+ *
+ * Factory function for creating LocalPackProvider instances.
+ *
+ * @param options - Provider configuration
+ * @returns Configured LocalPackProvider
+ */
+export function createLocalPackProvider(
+  options: LocalPackProviderOptions
+): LocalPackProvider {
+  return new LocalPackProvider(options);
+}

package/src/pack-provider/PackProvider.ts

@@ -0,0 +1,160 @@
+/**
+ * Pack Provider Interface
+ *
+ * Provides an abstraction layer for loading rule packs from different sources:
+ * - Local file-based packs (OSS default)
+ * - Cloud licensing (via @sentriflow/licensing)
+ * - Offline bundles
+ *
+ * This enables the commercial licensing package to provide cloud-based
+ * pack loading without modifying the core engine.
+ *
+ * @module pack-provider
+ */
+
+import type { IRule, RulePack, RulePackMetadata } from '../types/IRule';
+
+/**
+ * Information about available pack updates
+ */
+export interface PackUpdateInfo {
+  /** Feed/pack identifier */
+  feedId: string;
+
+  /** Currently cached version */
+  currentVersion: string;
+
+  /** Available version on server */
+  availableVersion: string;
+
+  /** Download size in bytes (if known) */
+  downloadSize?: number;
+}
+
+/**
+ * License status information
+ */
+export interface PackProviderLicenseStatus {
+  /** Whether the license is currently valid */
+  isValid: boolean;
+
+  /** License tier */
+  tier: 'community' | 'professional' | 'enterprise' | string;
+
+  /** List of entitled feed/pack IDs */
+  entitledFeeds: string[];
+
+  /** Whether currently operating in offline mode */
+  isOffline?: boolean;
+
+  /** ISO timestamp when cached license expires */
+  cacheExpiresAt?: string;
+
+  /** Number of packs available in cache */
+  cachedPackCount?: number;
+
+  /** Total number of rules available */
+  totalRuleCount?: number;
+
+  /** Whether updates are available */
+  hasUpdates?: boolean;
+}
+
+/**
+ * Pack Provider Interface
+ *
+ * Abstracts rule pack loading to support different sources:
+ * - Default: Local file loading with license key
+ * - Cloud: Network-based activation and downloads
+ * - Offline: Air-gapped bundle loading
+ *
+ * Usage:
+ * ```typescript
+ * import { setPackProvider, getPackProvider } from '@sentriflow/core';
+ *
+ * // Use cloud provider (requires @sentriflow/licensing)
+ * const cloudProvider = new CloudPackProvider({ apiUrl, licenseKey });
+ * setPackProvider(cloudProvider);
+ *
+ * // Load packs using the registered provider
+ * const packs = await getPackProvider().loadPacks();
+ * ```
+ */
+export interface IPackProvider {
+  /**
+   * Load all available rule packs
+   *
+   * @returns Promise resolving to array of rule packs
+   * @throws Error if loading fails
+   */
+  loadPacks(): Promise<RulePack[]>;
+
+  /**
+   * Check for available updates
+   *
+   * Optional - only implemented by cloud/network providers.
+   * Local providers can return empty array.
+   *
+   * @returns Promise resolving to array of update info
+   */
+  checkForUpdates?(): Promise<PackUpdateInfo[]>;
+
+  /**
+   * Download and apply available updates
+   *
+   * Optional - only implemented by cloud/network providers.
+   *
+   * @param feedIds - Specific feeds to update (all if undefined)
+   * @returns Promise resolving to number of packs updated
+   */
+  applyUpdates?(feedIds?: string[]): Promise<number>;
+
+  /**
+   * Get current license status
+   *
+   * Optional - only implemented by licensed providers.
+   * OSS providers can return a default community status.
+   *
+   * @returns Promise resolving to license status
+   */
+  getLicenseStatus?(): Promise<PackProviderLicenseStatus>;
+
+  /**
+   * Clean up resources
+   *
+   * Optional - called when provider is being replaced or application exits.
+   * Should clear sensitive data from memory.
+   */
+  destroy?(): void;
+}
+
+/**
+ * Result of loading a single pack
+ */
+export interface PackLoadResult {
+  /** The loaded rule pack */
+  pack: RulePack;
+
+  /** Source of the pack (file path, feed ID, etc.) */
+  source: string;
+
+  /** ISO timestamp when the pack expires (if applicable) */
+  validUntil?: string;
+}
+
+/**
+ * Options for the default local pack provider
+ */
+export interface LocalPackProviderOptions {
+  /** License key for decryption */
+  licenseKey: string;
+
+  /** Paths to .grpx pack files */
+  packPaths: string[];
+
+  /** Optional machine ID for node-locked licenses */
+  machineId?: string;
+
+  /** Fail on first error (default: false, continue loading other packs) */
+  strict?: boolean;
+}

package/src/pack-provider/index.ts

@@ -0,0 +1,116 @@
+/**
+ * Pack Provider System
+ *
+ * Provides registration and access to pack providers:
+ * - Default: Local file-based pack loading
+ * - Custom: Cloud licensing via @sentriflow/licensing
+ *
+ * @module pack-provider
+ */
+
+export * from './PackProvider';
+export { LocalPackProvider, createLocalPackProvider } from './LocalPackProvider';
+
+import type { IPackProvider } from './PackProvider';
+import { LocalPackProvider } from './LocalPackProvider';
+
+/**
+ * Currently registered pack provider
+ * Default: null (uses legacy local loading)
+ */
+let currentProvider: IPackProvider | null = null;
+
+/**
+ * Set the global pack provider
+ *
+ * This allows replacing the default local pack loading with
+ * cloud-based providers from @sentriflow/licensing.
+ *
+ * @param provider - The pack provider to use
+ *
+ * @example
+ * ```typescript
+ * import { setPackProvider } from '@sentriflow/core';
+ * import { CloudPackProvider } from '@sentriflow/licensing';
+ *
+ * // Enable cloud licensing
+ * const cloudProvider = new CloudPackProvider({
+ *   licenseKey: 'XXXX-XXXX-XXXX-XXXX',
+ *   apiUrl: 'https://api.sentriflow.dev',
+ * });
+ * setPackProvider(cloudProvider);
+ * ```
+ */
+export function setPackProvider(provider: IPackProvider): void {
+  // Clean up previous provider if it has a destroy method
+  if (currentProvider?.destroy) {
+    currentProvider.destroy();
+  }
+
+  currentProvider = provider;
+}
+
+/**
+ * Get the current pack provider
+ *
+ * Returns the registered provider, or null if using legacy loading.
+ *
+ * @returns The current pack provider or null
+ */
+export function getPackProvider(): IPackProvider | null {
+  return currentProvider;
+}
+
+/**
+ * Check if a custom pack provider is registered
+ *
+ * @returns true if a custom provider is set
+ */
+export function hasPackProvider(): boolean {
+  return currentProvider !== null;
+}
+
+/**
+ * Clear the current pack provider
+ *
+ * Resets to using legacy local pack loading.
+ * Calls destroy() on the current provider if available.
+ */
+export function clearPackProvider(): void {
+  if (currentProvider?.destroy) {
+    currentProvider.destroy();
+  }
+  currentProvider = null;
+}
+
+/**
+ * Create and set a local pack provider
+ *
+ * Convenience function to create a LocalPackProvider and set it
+ * as the current provider.
+ *
+ * @param options - Provider options
+ * @returns The created LocalPackProvider
+ *
+ * @example
+ * ```typescript
+ * import { createAndSetLocalProvider } from '@sentriflow/core';
+ *
+ * const provider = createAndSetLocalProvider({
+ *   licenseKey: 'XXXX-XXXX-XXXX-XXXX',
+ *   packPaths: ['./rules/custom.grpx'],
+ * });
+ *
+ * const packs = await provider.loadPacks();
+ * ```
+ */
+export function createAndSetLocalProvider(options: {
+  licenseKey: string;
+  packPaths: string[];
+  machineId?: string;
+  strict?: boolean;
+}): LocalPackProvider {
+  const provider = new LocalPackProvider(options);
+  setPackProvider(provider);
+  return provider;
+}