@sentriflow/core 0.2.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentriflow/core",
-  "version": "0.2.1",
+  "version": "0.3.2",
   "description": "SentriFlow core engine for network configuration validation",
   "license": "Apache-2.0",
   "module": "src/index.ts",

package/src/grx2-loader/types.ts

@@ -30,8 +30,8 @@ export interface LicensePayload {
   /** Entitled feed IDs */
   feeds: string[];
 
-  /** API URL for cloud updates */
-  api: string;
+  /** API URL for cloud updates (optional - derived from domain at runtime if not set) */
+  api?: string;
 
   /** Expiration timestamp (Unix seconds) */
   exp: number;
@@ -189,6 +189,9 @@ export interface EncryptedPackInfo {
 
   /** Source: local directory or cloud cache */
   source: 'local' | 'cache';
+
+  /** Pack format (for unified loading) */
+  format?: 'grx2' | 'grpx' | 'unencrypted' | 'unknown';
 }
 
 /**
@@ -226,7 +229,8 @@ export type EncryptedPackErrorCode =
   | 'DECRYPTION_FAILED'
   | 'MACHINE_MISMATCH'
   | 'NETWORK_ERROR'
-  | 'API_ERROR';
+  | 'API_ERROR'
+  | 'ACTIVATION_FAILED';
 
 /**
  * Encrypted pack error

package/src/index.ts

@@ -37,3 +37,6 @@ export * from './helpers/common';
 
 // IP/Subnet extraction module
 export * from './ip';
+
+// Validation utilities (shared with CLI and VS Code)
+export * from './validation';

package/src/ip/classifier.ts

@@ -0,0 +1,416 @@
+// packages/core/src/ip/classifier.ts
+
+import type { IPSummary, IPCounts } from './types';
+
+// ============================================================================
+// IP Classification Types
+// ============================================================================
+
+/**
+ * Classification categories for IP addresses.
+ */
+export type IPClassification =
+  | 'public'      // Globally routable
+  | 'private'     // RFC 1918 private ranges
+  | 'loopback'    // 127.0.0.0/8, ::1
+  | 'link-local'  // 169.254.0.0/16, fe80::/10
+  | 'multicast'   // 224.0.0.0/4, ff00::/8
+  | 'reserved'    // 240.0.0.0/4, other reserved
+  | 'unspecified' // 0.0.0.0, ::
+  | 'broadcast'   // 255.255.255.255
+  | 'documentation' // 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32
+  | 'cgnat';      // 100.64.0.0/10 (Carrier-grade NAT)
+
+/**
+ * Options for filtering IP addresses.
+ */
+export interface IPFilterOptions {
+  /**
+   * Keep public (globally routable) addresses.
+   * @default true
+   */
+  keepPublic?: boolean;
+
+  /**
+   * Keep private (RFC 1918) addresses.
+   * @default true
+   */
+  keepPrivate?: boolean;
+
+  /**
+   * Keep loopback addresses (127.x.x.x, ::1).
+   * @default false
+   */
+  keepLoopback?: boolean;
+
+  /**
+   * Keep link-local addresses (169.254.x.x, fe80::).
+   * @default false
+   */
+  keepLinkLocal?: boolean;
+
+  /**
+   * Keep multicast addresses (224.x.x.x - 239.x.x.x, ff00::).
+   * @default false
+   */
+  keepMulticast?: boolean;
+
+  /**
+   * Keep reserved/future use addresses (240.x.x.x - 255.x.x.x).
+   * @default false
+   */
+  keepReserved?: boolean;
+
+  /**
+   * Keep unspecified addresses (0.0.0.0, ::).
+   * @default false
+   */
+  keepUnspecified?: boolean;
+
+  /**
+   * Keep broadcast address (255.255.255.255).
+   * @default false
+   */
+  keepBroadcast?: boolean;
+
+  /**
+   * Keep documentation addresses (TEST-NET ranges, 2001:db8::).
+   * @default false
+   */
+  keepDocumentation?: boolean;
+
+  /**
+   * Keep CGNAT addresses (100.64.0.0/10).
+   * @default true
+   */
+  keepCgnat?: boolean;
+}
+
+/**
+ * Default filter options - keep only public and private addresses.
+ */
+export const DEFAULT_FILTER_OPTIONS: Required<IPFilterOptions> = {
+  keepPublic: true,
+  keepPrivate: true,
+  keepLoopback: false,
+  keepLinkLocal: false,
+  keepMulticast: false,
+  keepReserved: false,
+  keepUnspecified: false,
+  keepBroadcast: false,
+  keepDocumentation: false,
+  keepCgnat: true,
+};
+
+// ============================================================================
+// IPv4 Classification
+// ============================================================================
+
+/**
+ * Convert IPv4 address string to 32-bit number.
+ */
+function ipv4ToNumber(ip: string): number {
+  const parts = ip.split('.');
+  if (parts.length !== 4) return 0;
+
+  let result = 0;
+  for (let i = 0; i < 4; i++) {
+    const octet = parseInt(parts[i] ?? '0', 10);
+    if (isNaN(octet) || octet < 0 || octet > 255) return 0;
+    result = (result << 8) + octet;
+  }
+  return result >>> 0; // Ensure unsigned
+}
+
+/**
+ * Check if IPv4 address is in a given CIDR range.
+ */
+function isInIPv4Range(ip: string, network: string, prefix: number): boolean {
+  const ipNum = ipv4ToNumber(ip);
+  const netNum = ipv4ToNumber(network);
+  const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+  return (ipNum & mask) === (netNum & mask);
+}
+
+/**
+ * Classify an IPv4 address.
+ */
+export function classifyIPv4(ip: string): IPClassification {
+  // Unspecified
+  if (ip === '0.0.0.0') return 'unspecified';
+
+  // Broadcast
+  if (ip === '255.255.255.255') return 'broadcast';
+
+  // Current network (0.0.0.0/8) - treat as unspecified
+  if (isInIPv4Range(ip, '0.0.0.0', 8)) return 'unspecified';
+
+  // Loopback (127.0.0.0/8)
+  if (isInIPv4Range(ip, '127.0.0.0', 8)) return 'loopback';
+
+  // Link-local (169.254.0.0/16)
+  if (isInIPv4Range(ip, '169.254.0.0', 16)) return 'link-local';
+
+  // Private ranges (RFC 1918)
+  if (isInIPv4Range(ip, '10.0.0.0', 8)) return 'private';
+  if (isInIPv4Range(ip, '172.16.0.0', 12)) return 'private';
+  if (isInIPv4Range(ip, '192.168.0.0', 16)) return 'private';
+
+  // CGNAT (100.64.0.0/10)
+  if (isInIPv4Range(ip, '100.64.0.0', 10)) return 'cgnat';
+
+  // Documentation ranges (TEST-NET)
+  if (isInIPv4Range(ip, '192.0.2.0', 24)) return 'documentation';
+  if (isInIPv4Range(ip, '198.51.100.0', 24)) return 'documentation';
+  if (isInIPv4Range(ip, '203.0.113.0', 24)) return 'documentation';
+
+  // Multicast (224.0.0.0/4)
+  if (isInIPv4Range(ip, '224.0.0.0', 4)) return 'multicast';
+
+  // Reserved for future use (240.0.0.0/4)
+  if (isInIPv4Range(ip, '240.0.0.0', 4)) return 'reserved';
+
+  // Everything else is public
+  return 'public';
+}
+
+/**
+ * Classify an IPv4 subnet (uses network address for classification).
+ */
+export function classifyIPv4Subnet(subnet: string): IPClassification {
+  const slashIndex = subnet.lastIndexOf('/');
+  if (slashIndex === -1) return classifyIPv4(subnet);
+
+  const network = subnet.substring(0, slashIndex);
+  return classifyIPv4(network);
+}
+
+// ============================================================================
+// IPv6 Classification
+// ============================================================================
+
+/**
+ * Expand IPv6 address to full form and return as array of 16-bit values.
+ */
+function expandIPv6(ip: string): number[] {
+  // Strip zone ID if present
+  const zoneIndex = ip.indexOf('%');
+  const addr = zoneIndex !== -1 ? ip.substring(0, zoneIndex) : ip;
+
+  const parts = addr.split(':');
+  const result: number[] = [];
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i] ?? '';
+    if (part === '' && i > 0 && i < parts.length - 1) {
+      // Middle :: - expand
+      const nonEmpty = parts.filter((p) => p !== '').length;
+      const zeros = 8 - nonEmpty;
+      for (let j = 0; j < zeros; j++) {
+        result.push(0);
+      }
+    } else if (part !== '') {
+      result.push(parseInt(part, 16) || 0);
+    } else if (i === 0 && (parts[1] ?? '') === '') {
+      // Leading ::
+      const nonEmpty = parts.filter((p) => p !== '').length;
+      const zeros = 8 - nonEmpty;
+      for (let j = 0; j < zeros; j++) {
+        result.push(0);
+      }
+    }
+  }
+
+  // Pad to 8 if needed
+  while (result.length < 8) {
+    result.push(0);
+  }
+
+  return result.slice(0, 8);
+}
+
+/**
+ * Check if IPv6 starts with a specific prefix.
+ */
+function ipv6StartsWith(ip: string, prefixHex: number, prefixBits: number): boolean {
+  const parts = expandIPv6(ip);
+
+  // Calculate how many 16-bit groups we need to check
+  const fullGroups = Math.floor(prefixBits / 16);
+  const remainingBits = prefixBits % 16;
+
+  // Build the prefix value from parts
+  let value = 0;
+  for (let i = 0; i < fullGroups && i < parts.length; i++) {
+    value = (value << 16) | (parts[i] ?? 0);
+  }
+
+  if (remainingBits > 0 && fullGroups < parts.length) {
+    const mask = (~0 << (16 - remainingBits)) & 0xffff;
+    value = (value << remainingBits) | (((parts[fullGroups] ?? 0) & mask) >> (16 - remainingBits));
+  }
+
+  return value === prefixHex;
+}
+
+/**
+ * Classify an IPv6 address.
+ */
+export function classifyIPv6(ip: string): IPClassification {
+  const parts = expandIPv6(ip);
+
+  // Unspecified (::)
+  if (parts.every((p) => p === 0)) return 'unspecified';
+
+  // Loopback (::1)
+  if (parts.slice(0, 7).every((p) => p === 0) && parts[7] === 1) return 'loopback';
+
+  // Link-local (fe80::/10)
+  if ((parts[0] ?? 0) >= 0xfe80 && (parts[0] ?? 0) <= 0xfebf) return 'link-local';
+
+  // Multicast (ff00::/8)
+  if (((parts[0] ?? 0) & 0xff00) === 0xff00) return 'multicast';
+
+  // Documentation (2001:db8::/32)
+  if (parts[0] === 0x2001 && parts[1] === 0x0db8) return 'documentation';
+
+  // Unique local (fc00::/7) - similar to private
+  if (((parts[0] ?? 0) & 0xfe00) === 0xfc00) return 'private';
+
+  // Everything else is public
+  return 'public';
+}
+
+/**
+ * Classify an IPv6 subnet (uses network address for classification).
+ */
+export function classifyIPv6Subnet(subnet: string): IPClassification {
+  const slashIndex = subnet.lastIndexOf('/');
+  if (slashIndex === -1) return classifyIPv6(subnet);
+
+  const network = subnet.substring(0, slashIndex);
+  return classifyIPv6(network);
+}
+
+// ============================================================================
+// Filtering Functions
+// ============================================================================
+
+/**
+ * Check if a classification should be kept based on filter options.
+ */
+function shouldKeepClassification(
+  classification: IPClassification,
+  options: Required<IPFilterOptions>
+): boolean {
+  switch (classification) {
+    case 'public':
+      return options.keepPublic;
+    case 'private':
+      return options.keepPrivate;
+    case 'loopback':
+      return options.keepLoopback;
+    case 'link-local':
+      return options.keepLinkLocal;
+    case 'multicast':
+      return options.keepMulticast;
+    case 'reserved':
+      return options.keepReserved;
+    case 'unspecified':
+      return options.keepUnspecified;
+    case 'broadcast':
+      return options.keepBroadcast;
+    case 'documentation':
+      return options.keepDocumentation;
+    case 'cgnat':
+      return options.keepCgnat;
+    default:
+      return true;
+  }
+}
+
+/**
+ * Filter an array of IPv4 addresses based on classification.
+ */
+export function filterIPv4Addresses(
+  addresses: string[],
+  options: IPFilterOptions = {}
+): string[] {
+  const opts: Required<IPFilterOptions> = { ...DEFAULT_FILTER_OPTIONS, ...options };
+  return addresses.filter((ip) => {
+    const classification = classifyIPv4(ip);
+    return shouldKeepClassification(classification, opts);
+  });
+}
+
+/**
+ * Filter an array of IPv6 addresses based on classification.
+ */
+export function filterIPv6Addresses(
+  addresses: string[],
+  options: IPFilterOptions = {}
+): string[] {
+  const opts: Required<IPFilterOptions> = { ...DEFAULT_FILTER_OPTIONS, ...options };
+  return addresses.filter((ip) => {
+    const classification = classifyIPv6(ip);
+    return shouldKeepClassification(classification, opts);
+  });
+}
+
+/**
+ * Filter an array of IPv4 subnets based on classification.
+ */
+export function filterIPv4Subnets(
+  subnets: string[],
+  options: IPFilterOptions = {}
+): string[] {
+  const opts: Required<IPFilterOptions> = { ...DEFAULT_FILTER_OPTIONS, ...options };
+  return subnets.filter((subnet) => {
+    const classification = classifyIPv4Subnet(subnet);
+    return shouldKeepClassification(classification, opts);
+  });
+}
+
+/**
+ * Filter an array of IPv6 subnets based on classification.
+ */
+export function filterIPv6Subnets(
+  subnets: string[],
+  options: IPFilterOptions = {}
+): string[] {
+  const opts: Required<IPFilterOptions> = { ...DEFAULT_FILTER_OPTIONS, ...options };
+  return subnets.filter((subnet) => {
+    const classification = classifyIPv6Subnet(subnet);
+    return shouldKeepClassification(classification, opts);
+  });
+}
+
+/**
+ * Filter an entire IPSummary based on classification options.
+ * Returns a new IPSummary with filtered results and updated counts.
+ */
+export function filterIPSummary(
+  summary: IPSummary,
+  options: IPFilterOptions = {}
+): IPSummary {
+  const ipv4Addresses = filterIPv4Addresses(summary.ipv4Addresses, options);
+  const ipv6Addresses = filterIPv6Addresses(summary.ipv6Addresses, options);
+  const ipv4Subnets = filterIPv4Subnets(summary.ipv4Subnets, options);
+  const ipv6Subnets = filterIPv6Subnets(summary.ipv6Subnets, options);
+
+  const counts: IPCounts = {
+    ipv4: ipv4Addresses.length,
+    ipv6: ipv6Addresses.length,
+    ipv4Subnets: ipv4Subnets.length,
+    ipv6Subnets: ipv6Subnets.length,
+    total: ipv4Addresses.length + ipv6Addresses.length + ipv4Subnets.length + ipv6Subnets.length,
+  };
+
+  return {
+    ipv4Addresses,
+    ipv6Addresses,
+    ipv4Subnets,
+    ipv6Subnets,
+    counts,
+  };
+}

package/src/ip/index.ts

@@ -25,3 +25,19 @@ export type {
 } from './types';
 
 export { InputValidationError, DEFAULT_MAX_CONTENT_SIZE } from './types';
+
+// IP Classification and Filtering
+export {
+  classifyIPv4,
+  classifyIPv6,
+  classifyIPv4Subnet,
+  classifyIPv6Subnet,
+  filterIPv4Addresses,
+  filterIPv6Addresses,
+  filterIPv4Subnets,
+  filterIPv6Subnets,
+  filterIPSummary,
+  DEFAULT_FILTER_OPTIONS,
+} from './classifier';
+
+export type { IPClassification, IPFilterOptions } from './classifier';

package/src/json-rules/schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://sentriflow.io/schemas/json-rules/v1.0.json",
+  "$id": "https://sentriflow.com.au/schemas/json-rules/v1.0.json",
   "title": "SentriFlow JSON Rules",
   "description": "Schema for SentriFlow JSON rule files",
   "type": "object",

package/src/pack-loader/format-detector.ts

@@ -0,0 +1,113 @@
+/**
+ * Pack Format Detection
+ *
+ * Detects pack format from magic bytes.
+ * Shared between CLI and VS Code extension.
+ *
+ * @module format-detector
+ */
+
+import { open } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+/**
+ * Detected pack format
+ */
+export type PackFormat = 'grx2' | 'grpx' | 'unencrypted' | 'unknown';
+
+/**
+ * Priority tiers by format.
+ * Higher priority packs override lower priority packs for the same rule.
+ *
+ * - unknown: 0 (fallback, should not occur in normal operation)
+ * - unencrypted: 100 (plain JS/TS modules)
+ * - grpx: 200 (legacy encrypted format)
+ * - grx2: 300 (extended encrypted format)
+ */
+export const FORMAT_PRIORITIES: Record<PackFormat, number> = {
+  unknown: 0,
+  unencrypted: 100,
+  grpx: 200,
+  grx2: 300,
+};
+
+/**
+ * Magic bytes for format detection
+ */
+const MAGIC_BYTES = {
+  GRX2: Buffer.from('GRX2', 'ascii'),
+  GRPX: Buffer.from('GRPX', 'ascii'),
+} as const;
+
+const MAGIC_BYTES_LENGTH = 4;
+
+/**
+ * Detect the format of a pack file by reading magic bytes.
+ *
+ * @param filePath - Path to the pack file
+ * @returns Promise resolving to the detected format
+ *
+ * @example
+ * ```typescript
+ * import { detectPackFormat } from '@sentriflow/core';
+ *
+ * const format = await detectPackFormat('/path/to/pack.grx2');
+ * // Returns: 'grx2'
+ *
+ * const format2 = await detectPackFormat('/path/to/rules.js');
+ * // Returns: 'unencrypted'
+ * ```
+ */
+export async function detectPackFormat(filePath: string): Promise<PackFormat> {
+  const absolutePath = resolve(filePath);
+  let fileHandle;
+
+  try {
+    fileHandle = await open(absolutePath, 'r');
+    const stats = await fileHandle.stat();
+
+    // Files smaller than magic bytes length are treated as unencrypted
+    if (stats.size < MAGIC_BYTES_LENGTH) {
+      return 'unencrypted';
+    }
+
+    const buffer = Buffer.alloc(MAGIC_BYTES_LENGTH);
+    const { bytesRead } = await fileHandle.read(
+      buffer,
+      0,
+      MAGIC_BYTES_LENGTH,
+      0
+    );
+
+    if (bytesRead < MAGIC_BYTES_LENGTH) {
+      return 'unencrypted';
+    }
+
+    // Check for GRX2 magic bytes
+    if (buffer.equals(MAGIC_BYTES.GRX2)) {
+      return 'grx2';
+    }
+
+    // Check for GRPX magic bytes
+    if (buffer.equals(MAGIC_BYTES.GRPX)) {
+      return 'grpx';
+    }
+
+    // No magic bytes match - treat as unencrypted module
+    return 'unencrypted';
+  } catch (error) {
+    // Re-throw file access errors with context
+    if (error instanceof Error) {
+      const nodeError = error as NodeJS.ErrnoException;
+      if (nodeError.code === 'ENOENT') {
+        throw new Error(`Pack file not found: ${absolutePath}`);
+      }
+      if (nodeError.code === 'EACCES') {
+        throw new Error(`Permission denied reading pack file: ${absolutePath}`);
+      }
+    }
+    throw error;
+  } finally {
+    await fileHandle?.close();
+  }
+}

package/src/pack-loader/index.ts

@@ -14,4 +14,11 @@
  */
 
 export * from './types';
-export { loadEncryptedPack, validatePackFormat } from './PackLoader';
+export { loadEncryptedPack, validatePackFormat, compileNativeCheckFunction } from './PackLoader';
+
+// Pack format detection (shared with CLI and VS Code)
+export {
+  detectPackFormat,
+  FORMAT_PRIORITIES,
+  type PackFormat,
+} from './format-detector';

package/src/validation/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Validation utilities for rules and rule packs.
+ * Shared between CLI and VS Code extension.
+ */
+
+export {
+  validateRule,
+  isValidRule,
+  validateRulePack,
+  isValidRulePack,
+  ruleAppliesToVendor,
+} from './rule-validation';

package/src/validation/rule-validation.ts

@@ -0,0 +1,209 @@
+/**
+ * Rule and RulePack validation utilities
+ * Shared between CLI and VS Code extension for DRY compliance.
+ */
+
+import { RULE_ID_PATTERN } from '../constants';
+import { isValidVendorId } from '../types/IRule';
+import type { IRule, RulePack, RuleVendor } from '../types/IRule';
+
+/**
+ * Validates that an object has the basic structure of an IRule.
+ * Returns error message if invalid, null if valid.
+ *
+ * Security: Prevents malicious extensions from registering invalid rules.
+ */
+export function validateRule(rule: unknown): string | null {
+  if (typeof rule !== 'object' || rule === null) {
+    return 'Rule is not an object';
+  }
+
+  const obj = rule as Record<string, unknown>;
+
+  // Required: id (string matching pattern)
+  if (typeof obj.id !== 'string') {
+    return 'Rule id is not a string';
+  }
+  if (!RULE_ID_PATTERN.test(obj.id)) {
+    return `Rule id "${obj.id}" does not match pattern ${RULE_ID_PATTERN}`;
+  }
+
+  // Required: check (function)
+  if (typeof obj.check !== 'function') {
+    return `Rule ${obj.id}: check is not a function (got ${typeof obj.check})`;
+  }
+
+  // Optional but recommended: selector (string)
+  if (obj.selector !== undefined && typeof obj.selector !== 'string') {
+    return `Rule ${obj.id}: selector is not a string`;
+  }
+
+  // Optional: vendor (string or array of valid vendors)
+  if (obj.vendor !== undefined) {
+    if (Array.isArray(obj.vendor)) {
+      for (const v of obj.vendor) {
+        if (typeof v !== 'string') {
+          return `Rule ${obj.id}: vendor array contains non-string`;
+        }
+        if (!isValidVendorId(v)) {
+          return `Rule ${obj.id}: invalid vendor "${v}"`;
+        }
+      }
+    } else if (typeof obj.vendor !== 'string') {
+      return `Rule ${obj.id}: vendor is not a string`;
+    } else if (!isValidVendorId(obj.vendor)) {
+      return `Rule ${obj.id}: invalid vendor "${obj.vendor}"`;
+    }
+  }
+
+  // Required: metadata (object with level)
+  if (typeof obj.metadata !== 'object' || obj.metadata === null) {
+    return `Rule ${obj.id}: metadata is not an object`;
+  }
+
+  const metadata = obj.metadata as Record<string, unknown>;
+  if (!['error', 'warning', 'info'].includes(metadata.level as string)) {
+    return `Rule ${obj.id}: invalid metadata.level "${metadata.level}"`;
+  }
+
+  return null;
+}
+
+/**
+ * Type guard to check if an object is a valid IRule.
+ */
+export function isValidRule(rule: unknown): rule is IRule {
+  return validateRule(rule) === null;
+}
+
+/**
+ * Validates that an object has the basic structure of a RulePack.
+ * Returns error message if invalid, null if valid.
+ *
+ * @param pack - The object to validate
+ * @param reservedPackName - Optional pack name that is reserved (e.g., "Default Rules")
+ */
+export function validateRulePack(
+  pack: unknown,
+  reservedPackName?: string
+): string | null {
+  if (typeof pack !== 'object' || pack === null) {
+    return 'Pack is not an object';
+  }
+
+  const obj = pack as Record<string, unknown>;
+
+  // Required: name (non-empty string)
+  if (typeof obj.name !== 'string' || obj.name.length === 0) {
+    return 'Pack name is missing or empty';
+  }
+
+  // Check reserved name if provided
+  if (reservedPackName && obj.name === reservedPackName) {
+    return `Pack name "${obj.name}" is reserved`;
+  }
+
+  // Required: version (string)
+  if (typeof obj.version !== 'string' || obj.version.length === 0) {
+    return 'Pack version is missing or empty';
+  }
+
+  // Required: publisher (string)
+  if (typeof obj.publisher !== 'string' || obj.publisher.length === 0) {
+    return 'Pack publisher is missing or empty';
+  }
+
+  // Required: priority (number >= 0)
+  if (typeof obj.priority !== 'number' || obj.priority < 0) {
+    return `Pack priority is invalid (got ${obj.priority})`;
+  }
+
+  // Required: rules (array)
+  if (!Array.isArray(obj.rules)) {
+    return 'Pack rules is not an array';
+  }
+
+  // Validate each rule in the pack
+  for (let i = 0; i < obj.rules.length; i++) {
+    const ruleError = validateRule(obj.rules[i]);
+    if (ruleError) {
+      return `Rule[${i}]: ${ruleError}`;
+    }
+  }
+
+  // Optional: disables (object with specific structure)
+  if (obj.disables !== undefined) {
+    if (typeof obj.disables !== 'object' || obj.disables === null) {
+      return 'Pack disables is not an object';
+    }
+
+    const disables = obj.disables as Record<string, unknown>;
+
+    // Optional: all (boolean)
+    if (disables.all !== undefined && typeof disables.all !== 'boolean') {
+      return 'Pack disables.all is not a boolean';
+    }
+
+    // Optional: vendors (array of valid vendor strings)
+    if (disables.vendors !== undefined) {
+      if (!Array.isArray(disables.vendors)) {
+        return 'Pack disables.vendors is not an array';
+      }
+      for (const v of disables.vendors) {
+        if (typeof v !== 'string' || !isValidVendorId(v)) {
+          return `Pack disables.vendors contains invalid vendor "${v}"`;
+        }
+      }
+    }
+
+    // Optional: rules (array of strings)
+    if (disables.rules !== undefined) {
+      if (!Array.isArray(disables.rules)) {
+        return 'Pack disables.rules is not an array';
+      }
+      for (const r of disables.rules) {
+        if (typeof r !== 'string') {
+          return 'Pack disables.rules contains non-string';
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Type guard to check if an object is a valid RulePack.
+ *
+ * @param pack - The object to validate
+ * @param reservedPackName - Optional pack name that is reserved
+ */
+export function isValidRulePack(
+  pack: unknown,
+  reservedPackName?: string
+): pack is RulePack {
+  return validateRulePack(pack, reservedPackName) === null;
+}
+
+/**
+ * Check if a rule applies to the given vendor.
+ * Rules without a vendor property are considered vendor-agnostic (apply to all).
+ * Rules with vendor: 'common' also apply to all vendors.
+ */
+export function ruleAppliesToVendor(rule: IRule, vendorId: string): boolean {
+  // No vendor specified = vendor-agnostic, applies to all
+  if (!rule.vendor) {
+    return true;
+  }
+
+  // Handle array of vendors
+  if (Array.isArray(rule.vendor)) {
+    return (
+      rule.vendor.includes('common') ||
+      rule.vendor.includes(vendorId as RuleVendor)
+    );
+  }
+
+  // Single vendor
+  return rule.vendor === 'common' || rule.vendor === vendorId;
+}