prepia 1.0.0

package/src/rate/shield.mjs

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview Rate limit monitoring and protection.
+ * @module rate/shield
+ */
+
+import { EventEmitter } from 'node:events';
+import { TokenBucket, SlidingWindow } from './limiter.mjs';
+
+/**
+ * @typedef {Object} ProviderLimits
+ * @property {number} [requestsPerMinute] - RPM limit
+ * @property {number} [tokensPerMinute] - TPM limit
+ * @property {number} [requestsPerDay] - Daily request limit
+ */
+
+export class RateShield extends EventEmitter {
+  /**
+   * @param {Object} [options]
+   * @param {Object<string, ProviderLimits>} [options.providers] - Per-provider limits
+   * @param {number} [options.warningThreshold=0.8] - Warn at this % of limit
+   */
+  constructor(options = {}) {
+    super();
+    this._warningThreshold = options.warningThreshold ?? 0.8;
+    /** @type {Map<string, { bucket: TokenBucket, window: SlidingWindow, limits: ProviderLimits, usage: Object }>} */
+    this._providers = new Map();
+
+    if (options.providers) {
+      for (const [name, limits] of Object.entries(options.providers)) {
+        this.addProvider(name, limits);
+      }
+    }
+  }
+
+  /**
+   * Add a provider with rate limits.
+   * @param {string} name - Provider name
+   * @param {ProviderLimits} limits
+   */
+  addProvider(name, limits) {
+    const rpm = limits.requestsPerMinute ?? 60;
+    const bucket = new TokenBucket({ capacity: rpm, refillRate: rpm / 60 });
+    const window = new SlidingWindow({ maxRequests: rpm, windowMs: 60000 });
+    this._providers.set(name, {
+      bucket,
+      window,
+      limits,
+      usage: { requests: 0, tokens: 0, rejected: 0, lastReset: Date.now() },
+    });
+  }
+
+  /**
+   * Check if a request is allowed for a provider.
+   * @param {string} provider - Provider name
+   * @param {number} [tokens=0] - Token count for this request
+   * @returns {Object} { allowed: boolean, reason?: string, waitMs?: number }
+   */
+  check(provider, tokens = 0) {
+    const entry = this._providers.get(provider);
+    if (!entry) {
+      return { allowed: true };
+    }
+
+    // Check sliding window
+    if (!entry.window.consume()) {
+      entry.usage.rejected++;
+      const waitMs = entry.window.waitFor();
+      this.emit('rate:rejected', { provider, waitMs });
+      return { allowed: false, reason: 'Rate limit exceeded', waitMs };
+    }
+
+    // Check token bucket
+    if (!entry.bucket.consume()) {
+      entry.usage.rejected++;
+      const waitMs = entry.bucket.waitFor();
+      this.emit('rate:rejected', { provider, waitMs });
+      return { allowed: false, reason: 'Token bucket empty', waitMs };
+    }
+
+    entry.usage.requests++;
+    entry.usage.tokens += tokens;
+
+    // Check warning threshold
+    const usageRatio = entry.usage.requests / (entry.limits.requestsPerMinute ?? 60);
+    if (usageRatio >= this._warningThreshold) {
+      this.emit('rate:warning', { provider, usageRatio });
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * Record token usage for a provider.
+   * @param {string} provider
+   * @param {number} tokens
+   */
+  recordUsage(provider, tokens) {
+    const entry = this._providers.get(provider);
+    if (entry) {
+      entry.usage.tokens += tokens;
+    }
+  }
+
+  /**
+   * Get usage stats for a provider.
+   * @param {string} provider
+   * @returns {Object|null}
+   */
+  getUsage(provider) {
+    const entry = this._providers.get(provider);
+    if (!entry) return null;
+    return { ...entry.usage };
+  }
+
+  /**
+   * Get all provider stats.
+   * @returns {Object}
+   */
+  getAllUsage() {
+    const result = {};
+    for (const [name, entry] of this._providers) {
+      result[name] = { ...entry.usage };
+    }
+    return result;
+  }
+
+  /**
+   * Reset usage counters for a provider.
+   * @param {string} provider
+   */
+  reset(provider) {
+    const entry = this._providers.get(provider);
+    if (entry) {
+      entry.usage = { requests: 0, tokens: 0, rejected: 0, lastReset: Date.now() };
+      entry.bucket.reset();
+      entry.window.reset();
+    }
+  }
+
+  /**
+   * Reset all providers.
+   */
+  resetAll() {
+    for (const name of this._providers.keys()) {
+      this.reset(name);
+    }
+  }
+}
+
+export default RateShield;

package/src/script/executor.mjs

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview PrepiScript executor - runs parsed scripts.
+ * @module script/executor
+ */
+
+import { EventEmitter } from 'node:events';
+
+export class ScriptExecutor extends EventEmitter {
+  /**
+   * @param {Object} [options]
+   * @param {Object} [options.tools] - Tool instances for execution
+   */
+  constructor(options = {}) {
+    super();
+    this._tools = options.tools || {};
+    this._results = new Map();
+  }
+
+  /**
+   * Execute a parsed PrepiScript.
+   * @param {import('./parser.mjs').ParsedScript} script - Parsed script
+   * @param {Object} [context] - Execution context
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(script, context = {}) {
+    const variables = { ...script.variables, ...context };
+    const stepResults = [];
+    let lastResult = null;
+
+    for (const step of script.steps) {
+      this.emit('step:start', { keyword: step.keyword, line: step.line });
+
+      try {
+        const result = await this._executeStep(step, variables, lastResult);
+        stepResults.push({ step, result, success: true });
+        lastResult = result;
+
+        // Store in variables if argument looks like a variable assignment
+        if (step.argument?.includes('->')) {
+          const [_, varName] = step.argument.split('->').map(s => s.trim());
+          if (varName) variables[varName] = result;
+        }
+
+        this.emit('step:complete', { keyword: step.keyword, line: step.line, result });
+      } catch (err) {
+        stepResults.push({ step, error: err.message, success: false });
+        this.emit('step:error', { keyword: step.keyword, line: step.line, error: err.message });
+
+        // Stop on error unless it's a non-critical step
+        if (step.keyword !== 'CACHE' && step.keyword !== 'FILTER') {
+          break;
+        }
+      }
+    }
+
+    return {
+      scriptName: script.name,
+      steps: stepResults,
+      variables,
+      success: stepResults.every(r => r.success),
+      output: lastResult,
+    };
+  }
+
+  /**
+   * Execute a single step.
+   * @param {Object} step
+   * @param {Object} variables
+   * @param {*} lastResult
+   * @returns {Promise<*>}
+   * @private
+   */
+  async _executeStep(step, variables, lastResult) {
+    const arg = this._resolveVariables(step.argument, variables);
+
+    switch (step.keyword) {
+      case 'SEARCH':
+        return this._executeSearch(arg, step.options);
+      case 'EXTRACT':
+        return this._executeExtract(arg, lastResult, step.options);
+      case 'FORMAT':
+        return this._executeFormat(arg, lastResult, step.options);
+      case 'DELIVER':
+        return this._executeDeliver(arg, lastResult, step.options);
+      case 'CACHE':
+        return { cached: true, key: arg };
+      case 'FILTER':
+        return this._executeFilter(arg, lastResult, step.options);
+      case 'MERGE':
+        return this._executeMerge(lastResult, step.options);
+      case 'IF':
+        return this._executeIf(arg, lastResult, step.options);
+      case 'OUTPUT':
+        return lastResult;
+      default:
+        throw new Error(`Unknown step keyword: ${step.keyword}`);
+    }
+  }
+
+  /**
+   * Resolve variable references in a string.
+   * @param {string} str
+   * @param {Object} variables
+   * @returns {string}
+   * @private
+   */
+  _resolveVariables(str, variables) {
+    if (!str) return str;
+    return str.replace(/\$\{(\w+)\}/g, (_, name) => {
+      return variables[name] !== undefined ? String(variables[name]) : `\${${name}}`;
+    });
+  }
+
+  async _executeSearch(query, options) {
+    if (this._tools.search) {
+      return this._tools.search(query, options);
+    }
+    return { query, results: [], source: 'no-search-tool' };
+  }
+
+  async _executeExtract(target, source, options) {
+    if (this._tools.extract && source) {
+      return this._tools.extract(target, source, options);
+    }
+    return { target, extracted: source };
+  }
+
+  async _executeFormat(format, data, options) {
+    if (format === 'json') return JSON.stringify(data, null, 2);
+    if (format === 'text') return typeof data === 'string' ? data : JSON.stringify(data);
+    if (format === 'markdown') return typeof data === 'object' ? JSON.stringify(data, null, 2) : String(data);
+    return data;
+  }
+
+  async _executeDeliver(target, data, options) {
+    return { target, data, delivered: true };
+  }
+
+  async _executeFilter(filter, data, options) {
+    if (!data || !Array.isArray(data)) return data;
+    return data; // In a real implementation, apply filter criteria
+  }
+
+  async _executeMerge(data, options) {
+    return { merged: true, data };
+  }
+
+  async _executeIf(condition, data, options) {
+    // Simple condition evaluation
+    if (condition && data) return data;
+    return null;
+  }
+
+  /**
+   * Register a tool for script execution.
+   * @param {string} name
+   * @param {Function} fn
+   */
+  registerTool(name, fn) {
+    this._tools[name] = fn;
+  }
+}
+
+export default ScriptExecutor;

package/src/script/parser.mjs

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview PrepiScript parser - custom task definition language.
+ * @module script/parser
+ */
+
+/**
+ * @typedef {Object} ParsedScript
+ * @property {string} name - Script name
+ * @property {Object[]} steps - Parsed steps
+ * @property {Object} variables - Variable declarations
+ * @property {Object[]} errors - Parse errors
+ */
+
+/**
+ * @typedef {Object} ScriptStep
+ * @property {string} keyword - Step keyword (SEARCH, EXTRACT, FORMAT, DELIVER, etc.)
+ * @property {string} argument - Step argument
+ * @property {Object} options - Step options
+ * @property {number} line - Source line number
+ */
+
+/** Valid keywords */
+const KEYWORDS = ['TASK', 'SEARCH', 'EXTRACT', 'FORMAT', 'DELIVER', 'CACHE', 'FILTER', 'MERGE', 'IF', 'SET', 'OUTPUT'];
+
+/**
+ * Parse a PrepiScript string.
+ * @param {string} script - Script source
+ * @returns {ParsedScript}
+ */
+export function parse(script) {
+  if (!script || typeof script !== 'string') {
+    return { name: '', steps: [], variables: {}, errors: [{ line: 0, message: 'Empty script' }] };
+  }
+
+  const lines = script.split('\n');
+  const steps = [];
+  const variables = {};
+  const errors = [];
+  let name = '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const line = lines[i].trim();
+
+    // Skip empty lines and comments
+    if (!line || line.startsWith('#') || line.startsWith('//')) continue;
+
+    // Parse keyword and argument
+    const match = line.match(/^(\w+)\s*(?:["']([^"']*)["']|\s+(.+))?$/);
+    if (!match) {
+      if (line.length > 0) {
+        errors.push({ line: lineNum, message: `Invalid syntax: ${line.substring(0, 50)}` });
+      }
+      continue;
+    }
+
+    const keyword = match[1].toUpperCase();
+    const argument = (match[2] || match[3] || '').trim();
+
+    if (!KEYWORDS.includes(keyword)) {
+      errors.push({ line: lineNum, message: `Unknown keyword: ${keyword}` });
+      continue;
+    }
+
+    if (keyword === 'TASK') {
+      name = argument;
+      continue;
+    }
+
+    // Parse options (key=value pairs)
+    const options = {};
+    const optPattern = /(\w+)=["']?([^"'\s]+)["']?/g;
+    let optMatch;
+    const remaining = line.substring(match[0].indexOf(argument || '') + (argument || '').length);
+    while ((optMatch = optPattern.exec(remaining)) !== null) {
+      options[optMatch[1]] = optMatch[2];
+    }
+
+    if (keyword === 'SET') {
+      const varMatch = argument.match(/^(\w+)\s*=\s*(.+)$/);
+      if (varMatch) {
+        variables[varMatch[1]] = varMatch[2];
+      } else {
+        errors.push({ line: lineNum, message: `Invalid SET syntax: ${argument}` });
+      }
+      continue;
+    }
+
+    steps.push({
+      keyword,
+      argument,
+      options,
+      line: lineNum,
+    });
+  }
+
+  if (!name && steps.length > 0) {
+    errors.unshift({ line: 0, message: 'Missing TASK declaration' });
+  }
+
+  return { name, steps, variables, errors };
+}
+
+/**
+ * Validate a parsed script.
+ * @param {ParsedScript} parsed
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validate(parsed) {
+  const errors = [];
+
+  if (parsed.errors.length > 0) {
+    errors.push(...parsed.errors.map(e => `Line ${e.line}: ${e.message}`));
+  }
+
+  if (!parsed.name) {
+    errors.push('Script must have a TASK name');
+  }
+
+  if (parsed.steps.length === 0) {
+    errors.push('Script must have at least one step');
+  }
+
+  // Check that DELIVER has a target
+  for (const step of parsed.steps) {
+    if (step.keyword === 'DELIVER' && !step.argument) {
+      errors.push(`Line ${step.line}: DELIVER requires a target`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export default { parse, validate };

package/src/security/privacy.mjs

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview PII detection and redaction.
+ * @module security/privacy
+ */
+
+/**
+ * @typedef {Object} PIIMatch
+ * @property {string} type - PII type
+ * @property {string} value - Matched value
+ * @property {number} start - Start index
+ * @property {number} end - End index
+ */
+
+/** PII detection patterns */
+const PII_PATTERNS = {
+  email: {
+    pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+    replacement: '[EMAIL]',
+  },
+  phone: {
+    pattern: /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+    replacement: '[PHONE]',
+  },
+  ssn: {
+    pattern: /\b\d{3}[-.\s]?\d{2}[-.\s]?\d{4}\b/g,
+    replacement: '[SSN]',
+  },
+  creditCard: {
+    pattern: /\b(?:\d{4}[-.\s]?){3}\d{4}\b/g,
+    replacement: '[CREDIT_CARD]',
+  },
+  ipAddress: {
+    pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+    replacement: '[IP]',
+  },
+  // US addresses (simplified)
+  address: {
+    pattern: /\b\d{1,5}\s+[\w\s]+(?:street|st|avenue|ave|road|rd|boulevard|blvd|drive|dr|lane|ln|way|court|ct)\b/gi,
+    replacement: '[ADDRESS]',
+  },
+};
+
+/**
+ * Detect PII in text.
+ * @param {string} text
+ * @returns {PIIMatch[]}
+ */
+export function detectPII(text) {
+  if (!text || typeof text !== 'string') return [];
+
+  const matches = [];
+  for (const [type, { pattern }] of Object.entries(PII_PATTERNS)) {
+    const regex = new RegExp(pattern.source, pattern.flags);
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+      matches.push({
+        type,
+        value: match[0],
+        start: match.index,
+        end: match.index + match[0].length,
+      });
+    }
+  }
+
+  return matches.sort((a, b) => a.start - b.start);
+}
+
+/**
+ * Redact PII from text.
+ * @param {string} text
+ * @param {Object} [options]
+ * @param {string[]} [options.types] - PII types to redact (default: all)
+ * @param {string} [options.replacement] - Custom replacement marker
+ * @returns {{ text: string, redacted: number }}
+ */
+export function redactPII(text, options = {}) {
+  if (!text || typeof text !== 'string') {
+    return { text: '', redacted: 0 };
+  }
+
+  const types = options.types || Object.keys(PII_PATTERNS);
+  let result = text;
+  let redacted = 0;
+
+  for (const type of types) {
+    const config = PII_PATTERNS[type];
+    if (!config) continue;
+    const replacement = options.replacement || config.replacement;
+    const regex = new RegExp(config.pattern.source, config.pattern.flags);
+    const before = result;
+    result = result.replace(regex, replacement);
+    const matches = before.match(regex);
+    if (matches) redacted += matches.length;
+  }
+
+  return { text: result, redacted };
+}
+
+/**
+ * Check if text contains PII.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function containsPII(text) {
+  return detectPII(text).length > 0;
+}
+
+export default { detectPII, redactPII, containsPII };

package/src/security/sanitizer.mjs

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Input/output sanitization.
+ * @module security/sanitizer
+ */
+
+/**
+ * @typedef {Object} SanitizeResult
+ * @property {string} text - Sanitized text
+ * @property {boolean} modified - Whether text was modified
+ * @property {string[]} issues - Issues found
+ */
+
+/** Injection patterns to detect and strip */
+const INJECTION_PATTERNS = [
+  // Prompt injection attempts
+  /ignore\s+(?:all\s+)?(?:previous|prior|above)\s+(?:instructions?|prompts?|rules?)/gi,
+  /you\s+are\s+now\s+(?:a|an|the)/gi,
+  /system\s*:\s*/gi,
+  /assistant\s*:\s*/gi,
+  /user\s*:\s*/gi,
+  /\[INST\]/gi,
+  /\[\/INST\]/gi,
+  /<\|im_start\|>/gi,
+  /<\|im_end\|>/gi,
+  /###\s*(?:system|instruction)/gi,
+  // Code injection
+  /```(?:bash|sh|shell)\s*\n[\s\S]*?rm\s+-rf/gi,
+  /```(?:bash|sh|shell)\s*\n[\s\S]*?curl\s+.*\|\s*sh/gi,
+];
+
+/**
+ * Sanitize user input.
+ * @param {string} input - Raw user input
+ * @param {Object} [options]
+ * @param {boolean} [options.stripInjection=true] - Strip injection patterns
+ * @param {number} [options.maxLength=100000] - Max input length
+ * @returns {SanitizeResult}
+ */
+export function sanitize(input, options = {}) {
+  if (!input || typeof input !== 'string') {
+    return { text: '', modified: false, issues: ['Empty or invalid input'] };
+  }
+
+  const { stripInjection = true, maxLength = 100000 } = options;
+  let text = input;
+  let modified = false;
+  const issues = [];
+
+  // Truncate if too long
+  if (text.length > maxLength) {
+    text = text.substring(0, maxLength);
+    modified = true;
+    issues.push(`Input truncated to ${maxLength} characters`);
+  }
+
+  // Strip null bytes
+  if (text.includes('\0')) {
+    text = text.replace(/\0/g, '');
+    modified = true;
+    issues.push('Null bytes removed');
+  }
+
+  // Strip injection patterns
+  if (stripInjection) {
+    for (const pattern of INJECTION_PATTERNS) {
+      if (pattern.test(text)) {
+        text = text.replace(pattern, '[REDACTED]');
+        modified = true;
+        issues.push(`Injection pattern detected and redacted: ${pattern.source.substring(0, 40)}`);
+      }
+    }
+  }
+
+  return { text, modified, issues };
+}
+
+/**
+ * Validate task parameters.
+ * @param {Object} params - Task parameters
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateParams(params) {
+  const errors = [];
+
+  if (!params || typeof params !== 'object') {
+    return { valid: false, errors: ['Parameters must be an object'] };
+  }
+
+  if (params.query && typeof params.query !== 'string') {
+    errors.push('Query must be a string');
+  }
+  if (params.query && params.query.length > 100000) {
+    errors.push('Query exceeds maximum length');
+  }
+  if (params.type && typeof params.type !== 'string') {
+    errors.push('Type must be a string');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Sanitize output before returning to user.
+ * @param {string} output
+ * @returns {SanitizeResult}
+ */
+export function sanitizeOutput(output) {
+  if (!output || typeof output !== 'string') {
+    return { text: '', modified: false, issues: ['Empty output'] };
+  }
+
+  let text = output;
+  let modified = false;
+  const issues = [];
+
+  // Remove any system-level markers that might have leaked
+  const leakPatterns = [
+    /system\s*:\s*.*$/gim,
+    /\[INST\][\s\S]*?\[\/INST\]/gi,
+  ];
+
+  for (const pattern of leakPatterns) {
+    if (pattern.test(text)) {
+      text = text.replace(pattern, '');
+      modified = true;
+      issues.push('System-level content leaked in output');
+    }
+  }
+
+  return { text: text.trim(), modified, issues };
+}
+
+export default { sanitize, validateParams, sanitizeOutput };