@matware/e2e-runner 1.2.1 → 1.3.0

package/src/runner.js

@@ -7,11 +7,15 @@
 
 import fs from 'fs';
 import path from 'path';
-import { connectToPool, waitForPool, getPoolStatus } from './pool.js';
+import http from 'http';
+import https from 'https';
+import { connectToPool } from './pool.js';
+import { getPoolUrls, selectPool, releasePending } from './pool-manager.js';
 import { executeAction } from './actions.js';
 import { narrateAction } from './narrate.js';
 import { log, colors as C } from './logger.js';
-import { resolveTestData } from './module-resolver.js';
+import { resolveTestData, validateActionTypes } from './module-resolver.js';
+import { ensureProject, getVariables } from './db.js';
 
 function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
@@ -44,6 +48,46 @@ function mergeHooks(configHooks, suiteHooks) {
   };
 }
 
+/** Replaces {{var.KEY}} and {{env.KEY}} in all string fields of an action object.
+ *  Skips {{param}} patterns (no dot) — those are module params handled by module-resolver. */
+function resolveVarsInAction(action, vars) {
+  const resolved = { ...action };
+  for (const key of Object.keys(resolved)) {
+    if (typeof resolved[key] !== 'string') continue;
+    resolved[key] = resolved[key].replace(/\{\{(var|env)\.([^}]+)\}\}/g, (match, ns, name) => {
+      if (ns === 'env') {
+        if (process.env[name] !== undefined) return process.env[name];
+        throw new Error(`Unresolved variable: {{env.${name}}} — environment variable not set`);
+      }
+      // ns === 'var'
+      if (vars[name] !== undefined) return vars[name];
+      throw new Error(`Unresolved variable: {{var.${name}}} — not found in project or suite variables`);
+    });
+  }
+  return resolved;
+}
+
+/** Loads merged variables for a test (project scope + suite scope overlay). */
+function loadVarsForTest(config, suiteName) {
+  try {
+    const cwd = config._cwd || process.cwd();
+    const projectName = config.projectName || cwd.split('/').pop() || 'default';
+    const projectId = ensureProject(cwd, projectName, config.screenshotsDir, config.testsDir);
+    const projectVars = getVariables(projectId, 'project');
+    if (!suiteName) return projectVars;
+    const suiteVars = getVariables(projectId, suiteName);
+    return { ...projectVars, ...suiteVars };
+  } catch {
+    return {};
+  }
+}
+
+/** Resolves variables in an array of actions. */
+function resolveVarsInActions(actions, vars) {
+  if (!actions || !actions.length) return actions;
+  return actions.map(a => resolveVarsInAction(a, vars));
+}
+
 /** Executes an array of hook actions on a page */
 async function executeHookActions(page, actions, config) {
   for (const action of actions) {
@@ -65,24 +109,45 @@ function normalizeTestData(data) {
   return { tests: data.tests || [], hooks };
 }
 
-/** Waits until the pool has capacity before connecting */
-async function waitForSlot(poolUrl, pollIntervalMs = 2000, maxWaitMs = 60000) {
-  const start = Date.now();
-  while (Date.now() - start < maxWaitMs) {
-    try {
-      const status = await getPoolStatus(poolUrl);
-      if (status.available && status.running < status.maxConcurrent) {
-        return;
-      }
-      log('⏳', `${C.dim}Pool at capacity (${status.running}/${status.maxConcurrent}, ${status.queued} queued), waiting for slot...${C.reset}`);
-    } catch {
-      // Pool unreachable, let connectToPool handle the error
-      return;
-    }
-    await sleep(pollIntervalMs);
-  }
-  // Timeout — proceed anyway and let connectToPool deal with it
-  log('⚠️', `${C.yellow}Waited ${maxWaitMs / 1000}s for pool slot, proceeding anyway${C.reset}`);
+/** Extracts a value from an object using a dot-path (e.g. "data.token"). */
+function getByPath(obj, dotPath) {
+  return dotPath.split('.').reduce((o, key) => o?.[key], obj);
+}
+
+/** Fetches an auth token by POSTing credentials to a login endpoint. */
+function fetchAuthToken(endpoint, credentials, tokenPath) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(endpoint);
+    const transport = url.protocol === 'https:' ? https : http;
+    const body = JSON.stringify(credentials);
+
+    const req = transport.request(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+      timeout: 15000,
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          return reject(new Error(`Auth login failed: HTTP ${res.statusCode} from ${endpoint}`));
+        }
+        try {
+          const json = JSON.parse(data);
+          const token = getByPath(json, tokenPath);
+          if (!token) {
+            return reject(new Error(`Auth login: token not found at path "${tokenPath}" in response`));
+          }
+          resolve(token);
+        } catch (e) {
+          reject(new Error(`Auth login: failed to parse response from ${endpoint}: ${e.message}`));
+        }
+      });
+    });
+    req.on('error', (e) => reject(new Error(`Auth login request failed: ${e.message}`)));
+    req.on('timeout', () => { req.destroy(); reject(new Error(`Auth login request timed out: ${endpoint}`)); });
+    req.end(body);
+  });
 }
 
 /** Runs a single test end-to-end */
@@ -104,8 +169,15 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
   const pendingBodies = [];
 
   try {
-    await waitForSlot(config.poolUrl);
-    browser = await connectToPool(config.poolUrl, config.connectRetries, config.connectRetryDelay);
+    const chosenPool = await selectPool(getPoolUrls(config));
+    result.poolUrl = chosenPool;
+    const poolLabel = chosenPool.replace('ws://', '').replace('wss://', '');
+    const isMultiPool = getPoolUrls(config).length > 1;
+    if (isMultiPool) {
+      log('🔗', `${C.cyan}${test.name}${C.reset} ${C.dim}→ ${poolLabel}${C.reset}`);
+    }
+    progressFn({ event: 'test:pool', name: test.name, poolUrl: chosenPool });
+    browser = await connectToPool(chosenPool, config.connectRetries, config.connectRetryDelay);
     // Use incognito context for cookie isolation between concurrent tests
     context = await browser.createBrowserContext();
     page = await context.newPage();
@@ -115,7 +187,10 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
       result.consoleLogs.push({ type: msg.type(), text: msg.text() });
     });
     page.on('requestfailed', (req) => {
-      result.networkErrors.push({ url: req.url(), error: req.failure()?.errorText });
+      const url = req.url();
+      const ignoreDomains = config.networkIgnoreDomains || [];
+      if (ignoreDomains.length > 0 && ignoreDomains.some(d => url.includes(d))) return;
+      result.networkErrors.push({ url, error: req.failure()?.errorText });
     });
 
     const requestTimings = new Map();
@@ -149,11 +224,38 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
       }
     });
 
+    // Auto-inject auth token into localStorage (runs BEFORE beforeEach hooks)
+    if (config.authToken) {
+      const storageKey = config.authStorageKey || 'accessToken';
+      await page.goto(config.baseUrl, { waitUntil: 'domcontentloaded', timeout: 15000 });
+      await page.evaluate((key, token) => {
+        localStorage.setItem(key, token);
+      }, storageKey, config.authToken);
+    }
+
+    // Resolve {{var.X}} and {{env.X}} in test actions and hooks
+    const vars = loadVarsForTest(config, config._suiteName);
+    if (Object.keys(vars).length > 0 || /\{\{(var|env)\./.test(JSON.stringify(test.actions))) {
+      test = { ...test, actions: resolveVarsInActions(test.actions, vars) };
+      if (hooks.beforeEach?.length) hooks = { ...hooks, beforeEach: resolveVarsInActions(hooks.beforeEach, vars) };
+      if (hooks.afterEach?.length) hooks = { ...hooks, afterEach: resolveVarsInActions(hooks.afterEach, vars) };
+    }
+
     // Run beforeEach hook
     if (hooks.beforeEach?.length) {
       await executeHookActions(page, hooks.beforeEach, config);
     }
 
+    // Auto-capture baseline screenshot if test has "expect" (BEFORE actions)
+    if (test.expect && page) {
+      try {
+        const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
+        const baselinePath = path.join(config.screenshotsDir, `baseline-${safeName}-${Date.now()}.png`);
+        await page.screenshot({ path: baselinePath, fullPage: true });
+        result.baselineScreenshot = baselinePath;
+      } catch { /* page may not be ready */ }
+    }
+
     for (let i = 0; i < test.actions.length; i++) {
       const action = test.actions[i];
       const maxActionRetries = action.retries ?? config.actionRetries ?? 0;
@@ -263,6 +365,10 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
     if (browser) {
       try { browser.disconnect(); } catch { /* */ }
     }
+    // Release local pending counter so selectPool() knows this slot is free
+    if (result.poolUrl) {
+      releasePending(result.poolUrl);
+    }
   }
 
   return result;
@@ -283,7 +389,8 @@ export async function runTestsParallel(tests, config, suiteHooks = {}) {
     log('🪝', `${C.dim}Running beforeAll hook...${C.reset}`);
     let browser = null;
     try {
-      browser = await connectToPool(config.poolUrl, config.connectRetries, config.connectRetryDelay);
+      const hookPool = await selectPool(getPoolUrls(config));
+      browser = await connectToPool(hookPool, config.connectRetries, config.connectRetryDelay);
       const page = await browser.newPage();
       await page.setViewport(config.viewport);
       await executeHookActions(page, hooks.beforeAll, config);
@@ -296,6 +403,22 @@ export async function runTestsParallel(tests, config, suiteHooks = {}) {
     }
   }
 
+  // Auto-login: fetch auth token via API if configured and not already provided
+  if (config.authLoginEndpoint && !config.authToken && config.authCredentials) {
+    log('🔑', `${C.dim}Fetching auth token from ${config.authLoginEndpoint}...${C.reset}`);
+    try {
+      config.authToken = await fetchAuthToken(
+        config.authLoginEndpoint,
+        config.authCredentials,
+        config.authTokenPath || 'token'
+      );
+      log('✅', `${C.dim}Auth token acquired (${config.authToken.length} chars)${C.reset}`);
+    } catch (error) {
+      log('❌', `${C.red}Auth auto-login failed: ${error.message}${C.reset}`);
+      throw error;
+    }
+  }
+
   const concurrency = config.concurrency || 3;
   const _runId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
   const _proj = config.projectName || null;
@@ -363,7 +486,7 @@ export async function runTestsParallel(tests, config, suiteHooks = {}) {
       activeCount--;
 
       const screenshots = result.actions.filter(a => a.result?.screenshot).map(a => a.result.screenshot);
-      _progress({ event: 'test:complete', name: test.name, success: result.success, duration: timeDiff(result.startTime, result.endTime), error: result.error, consoleLogs: result.consoleLogs, networkErrors: result.networkErrors, networkLogs: result.networkLogs, errorScreenshot: result.errorScreenshot, screenshots });
+      _progress({ event: 'test:complete', name: test.name, success: result.success, duration: timeDiff(result.startTime, result.endTime), error: result.error, consoleLogs: result.consoleLogs, networkErrors: result.networkErrors, networkLogs: result.networkLogs, errorScreenshot: result.errorScreenshot, screenshots, poolUrl: result.poolUrl || null });
 
       if (result.success) {
         const flaky = result.attempt > 1 ? ` ${C.yellow}(flaky, passed on attempt ${result.attempt}/${result.maxAttempts})${C.reset}` : '';
@@ -401,7 +524,8 @@ export async function runTestsParallel(tests, config, suiteHooks = {}) {
     log('🪝', `${C.dim}Running afterAll hook...${C.reset}`);
     let browser = null;
     try {
-      browser = await connectToPool(config.poolUrl, config.connectRetries, config.connectRetryDelay);
+      const hookPool = await selectPool(getPoolUrls(config));
+      browser = await connectToPool(hookPool, config.connectRetries, config.connectRetryDelay);
       const page = await browser.newPage();
       await page.setViewport(config.viewport);
       await executeHookActions(page, hooks.afterAll, config);
@@ -429,7 +553,9 @@ export function loadTestFile(filePath, modulesDir) {
   }
   const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
   const normalized = normalizeTestData(data);
-  return modulesDir ? resolveTestData(normalized, modulesDir) : normalized;
+  const resolved = modulesDir ? resolveTestData(normalized, modulesDir) : normalized;
+  validateActionTypes(resolved, path.basename(filePath));
+  return resolved;
 }
 
 /** Loads a test suite by name — returns { tests, hooks } */
@@ -446,7 +572,9 @@ export function loadTestSuite(suiteName, testsDir, modulesDir) {
 
   const data = JSON.parse(fs.readFileSync(path.join(testsDir, match), 'utf-8'));
   const normalized = normalizeTestData(data);
-  return modulesDir ? resolveTestData(normalized, modulesDir) : normalized;
+  const resolved = modulesDir ? resolveTestData(normalized, modulesDir) : normalized;
+  validateActionTypes(resolved, match);
+  return resolved;
 }
 
 /** Loads all test suites from the tests directory — returns { tests, hooks } */
@@ -466,6 +594,7 @@ export function loadAllSuites(testsDir, modulesDir, exclude = []) {
     if (modulesDir) {
       ({ tests, hooks } = resolveTestData({ tests, hooks }, modulesDir));
     }
+    validateActionTypes({ tests, hooks }, file);
     // Tag each test with its own suite's hooks so they're preserved
     for (const t of tests) {
       t._suiteHooks = hooks;

package/src/sync/auth.js

@@ -0,0 +1,354 @@
+/**
+ * Sync Authentication Module
+ * 
+ * Provides cryptographic utilities for multi-instance sync:
+ * - API Key generation and validation
+ * - TOTP (Time-based One-Time Password) RFC 6238
+ * - JWT token signing and verification
+ * - Request signature generation
+ * 
+ * Zero external dependencies - uses Node.js crypto only.
+ */
+
+import crypto from 'crypto';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// API KEY MANAGEMENT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a secure API key (256-bit random).
+ * Format: sk_<base64url encoded 32 bytes>
+ */
+export function generateApiKey() {
+  const bytes = crypto.randomBytes(32);
+  return 'sk_' + bytes.toString('base64url');
+}
+
+/**
+ * Hash an API key for storage (never store plaintext).
+ */
+export function hashApiKey(apiKey) {
+  return crypto.createHash('sha256').update(apiKey).digest('hex');
+}
+
+/**
+ * Verify an API key against its stored hash.
+ */
+export function verifyApiKey(apiKey, storedHash) {
+  const hash = hashApiKey(apiKey);
+  return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(storedHash));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TOTP (TIME-BASED ONE-TIME PASSWORD)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a TOTP secret (20 bytes = 160 bits, per RFC 6238).
+ * Returns base32-encoded string for compatibility with authenticator apps.
+ */
+export function generateTotpSecret() {
+  const bytes = crypto.randomBytes(20);
+  return base32Encode(bytes);
+}
+
+/**
+ * Generate TOTP code for a given secret and time step.
+ * @param {string} secret - Base32-encoded secret
+ * @param {number} timeStep - Time step (default: current)
+ * @returns {string} 6-digit TOTP code
+ */
+export function generateTotpCode(secret, timeStep = null) {
+  if (timeStep === null) {
+    timeStep = Math.floor(Date.now() / 1000 / 30);
+  }
+  
+  const secretBytes = base32Decode(secret);
+  const timeBuffer = Buffer.alloc(8);
+  timeBuffer.writeBigInt64BE(BigInt(timeStep));
+  
+  const hmac = crypto.createHmac('sha1', secretBytes);
+  hmac.update(timeBuffer);
+  const hash = hmac.digest();
+  
+  const offset = hash[hash.length - 1] & 0x0f;
+  const code = (
+    ((hash[offset] & 0x7f) << 24) |
+    ((hash[offset + 1] & 0xff) << 16) |
+    ((hash[offset + 2] & 0xff) << 8) |
+    (hash[offset + 3] & 0xff)
+  ) % 1000000;
+  
+  return code.toString().padStart(6, '0');
+}
+
+/**
+ * Validate a TOTP code with a tolerance window of ±1 step (±30 seconds).
+ * @param {string} secret - Base32-encoded secret
+ * @param {string} code - 6-digit code to validate
+ * @returns {boolean}
+ */
+export function validateTotp(secret, code) {
+  const now = Math.floor(Date.now() / 1000 / 30);
+  
+  for (const offset of [0, -1, 1]) {
+    const expected = generateTotpCode(secret, now + offset);
+    if (crypto.timingSafeEqual(Buffer.from(code), Buffer.from(expected))) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Generate TOTP URI for authenticator apps (Google Authenticator, etc.).
+ */
+export function generateTotpUri(secret, instanceId, issuer = 'e2e-runner') {
+  const encodedIssuer = encodeURIComponent(issuer);
+  const encodedLabel = encodeURIComponent(`${issuer}:${instanceId}`);
+  return `otpauth://totp/${encodedLabel}?secret=${secret}&issuer=${encodedIssuer}&algorithm=SHA1&digits=6&period=30`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// JWT (JSON WEB TOKENS)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Sign a JWT token (HS256).
+ * @param {object} payload - Claims to include
+ * @param {string} secret - Signing secret (256-bit recommended)
+ * @param {number} expiresIn - Expiration in seconds (default: 1 hour)
+ * @returns {string} JWT token
+ */
+export function signJwt(payload, secret, expiresIn = 3600) {
+  const header = { alg: 'HS256', typ: 'JWT' };
+  const now = Math.floor(Date.now() / 1000);
+  
+  const claims = {
+    ...payload,
+    iat: now,
+    exp: now + expiresIn,
+    jti: crypto.randomBytes(16).toString('hex'),
+  };
+  
+  const b64url = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const unsigned = `${b64url(header)}.${b64url(claims)}`;
+  const signature = crypto.createHmac('sha256', secret).update(unsigned).digest('base64url');
+  
+  return `${unsigned}.${signature}`;
+}
+
+/**
+ * Verify and decode a JWT token.
+ * @param {string} token - JWT token
+ * @param {string} secret - Signing secret
+ * @returns {object} Decoded payload
+ * @throws {Error} If token is invalid or expired
+ */
+export function verifyJwt(token, secret) {
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    throw new Error('Invalid token format');
+  }
+  
+  const [headerB64, payloadB64, signature] = parts;
+  const unsigned = `${headerB64}.${payloadB64}`;
+  const expectedSig = crypto.createHmac('sha256', secret).update(unsigned).digest('base64url');
+  
+  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSig))) {
+    throw new Error('Invalid signature');
+  }
+  
+  const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
+  
+  if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
+    throw new Error('Token expired');
+  }
+  
+  return payload;
+}
+
+/**
+ * Decode JWT without verification (for debugging only).
+ */
+export function decodeJwt(token) {
+  const parts = token.split('.');
+  if (parts.length !== 3) return null;
+  
+  try {
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+  } catch {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// REQUEST SIGNING
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a signature for a request payload.
+ * Used for additional integrity verification on sensitive operations.
+ */
+export function signRequest(payload, secret) {
+  const canonical = JSON.stringify(payload, Object.keys(payload).sort());
+  return crypto.createHmac('sha512', secret).update(canonical).digest('hex');
+}
+
+/**
+ * Verify a request signature.
+ */
+export function verifyRequestSignature(payload, signature, secret) {
+  const expected = signRequest(payload, secret);
+  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ENCRYPTION (for storing secrets in DB)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Encrypt a value using AES-256-GCM.
+ * @param {string} plaintext - Value to encrypt
+ * @param {string} masterKey - 32-byte hex-encoded master key
+ * @returns {string} Encrypted value (iv:ciphertext:tag in hex)
+ */
+export function encrypt(plaintext, masterKey) {
+  const key = Buffer.from(masterKey, 'hex');
+  if (key.length !== 32) {
+    throw new Error('Master key must be 32 bytes (64 hex chars)');
+  }
+  
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, 'utf8'),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+  
+  return `${iv.toString('hex')}:${encrypted.toString('hex')}:${tag.toString('hex')}`;
+}
+
+/**
+ * Decrypt a value encrypted with encrypt().
+ * @param {string} ciphertext - Encrypted value (iv:ciphertext:tag)
+ * @param {string} masterKey - 32-byte hex-encoded master key
+ * @returns {string} Decrypted plaintext
+ */
+export function decrypt(ciphertext, masterKey) {
+  const key = Buffer.from(masterKey, 'hex');
+  if (key.length !== 32) {
+    throw new Error('Master key must be 32 bytes (64 hex chars)');
+  }
+  
+  const [ivHex, encryptedHex, tagHex] = ciphertext.split(':');
+  const iv = Buffer.from(ivHex, 'hex');
+  const encrypted = Buffer.from(encryptedHex, 'hex');
+  const tag = Buffer.from(tagHex, 'hex');
+  
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+  
+  return decipher.update(encrypted) + decipher.final('utf8');
+}
+
+/**
+ * Generate a master key for encryption.
+ * Store this securely (env var, secrets manager).
+ */
+export function generateMasterKey() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// NONCE & TIMESTAMP VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a nonce for request freshness.
+ */
+export function generateNonce() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+/**
+ * Check if a timestamp is within acceptable range (±30 seconds).
+ */
+export function isTimestampValid(timestamp, toleranceMs = 30000) {
+  const now = Date.now();
+  return Math.abs(now - timestamp) <= toleranceMs;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BASE32 ENCODING (for TOTP compatibility)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+function base32Encode(buffer) {
+  let result = '';
+  let bits = 0;
+  let value = 0;
+  
+  for (const byte of buffer) {
+    value = (value << 8) | byte;
+    bits += 8;
+    
+    while (bits >= 5) {
+      bits -= 5;
+      result += BASE32_ALPHABET[(value >>> bits) & 0x1f];
+    }
+  }
+  
+  if (bits > 0) {
+    result += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f];
+  }
+  
+  return result;
+}
+
+function base32Decode(str) {
+  str = str.toUpperCase().replace(/=+$/, '');
+  const bytes = [];
+  let bits = 0;
+  let value = 0;
+  
+  for (const char of str) {
+    const idx = BASE32_ALPHABET.indexOf(char);
+    if (idx === -1) continue;
+    
+    value = (value << 5) | idx;
+    bits += 5;
+    
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((value >>> bits) & 0xff);
+    }
+  }
+  
+  return Buffer.from(bytes);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// INSTANCE ID GENERATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a unique instance ID.
+ * Format: <prefix>-<random 4 chars>
+ */
+export function generateInstanceId(prefix = 'instance') {
+  const suffix = crypto.randomBytes(2).toString('hex');
+  return `${prefix}-${suffix}`;
+}
+
+/**
+ * Validate instance ID format.
+ */
+export function isValidInstanceId(id) {
+  return /^[a-z0-9][a-z0-9-]{2,48}[a-z0-9]$/i.test(id);
+}