auramaxx 1.0.0-alpha.4

package/server/lib/strategy/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Strategy Engine — Public API
+ * ============================
+ * Re-exports the main engine functions for use by routes and server startup.
+ */
+
+export {
+  startEngine,
+  stopEngine,
+  enableStrategy,
+  disableStrategy,
+  reloadStrategies,
+  getStrategies,
+  getRuntime,
+  resolveApproval,
+  getPendingApprovals,
+  isEngineStarted,
+  emitStrategyEvent,
+  runExternalTickCycle,
+  reconcileWorkspaceStrategies,
+  persistEngineStateSnapshot,
+  enqueueAppMessage,
+  waitForQueuedAppMessage,
+  processPendingAppMessages,
+  STRATEGY_ENABLED_STORAGE_KEY,
+} from './engine';
+export { getState, updateState, getConfigOverrides, setConfigOverrides } from './state';
+export type { StrategyManifest, StrategyRuntime, StrategyStatus, TickTier, Intent, Action, ActionOutcome, HookResult } from './types';

package/server/lib/strategy/installer.ts

@@ -0,0 +1,305 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { createHash } from 'crypto';
+import { execFileSync } from 'child_process';
+import { parse as parseYaml } from 'yaml';
+
+import { validateExternalUrl } from '../network';
+import { orderSources, validateManifest } from './loader';
+import type { StrategyManifest, SourceDef } from './types';
+
+type StrategySourceType = 'git' | 'tarball' | 'zip' | 'local' | 'inline';
+
+interface ParsedSource {
+  type: 'git' | 'tarball' | 'zip' | 'local';
+  url: string;
+  subdir: string | null;
+}
+
+export interface StrategyInstallProvenance {
+  sourceType: StrategySourceType;
+  sourceUrl: string;
+  ref: string | null;
+  subdir: string | null;
+  hash: string;
+  signaturePresent: boolean;
+  installedAt: string;
+}
+
+export interface PreparedThirdPartyStrategy {
+  manifest: StrategyManifest;
+  provenance: StrategyInstallProvenance;
+}
+
+function parseSource(source: string): ParsedSource {
+  let subdir: string | null = null;
+  const hashIdx = source.indexOf('#path=');
+  let cleanSource = source;
+  if (hashIdx !== -1) {
+    subdir = source.slice(hashIdx + 6);
+    cleanSource = source.slice(0, hashIdx);
+  }
+
+  if (cleanSource.startsWith('.') || cleanSource.startsWith('/')) {
+    return { type: 'local', url: cleanSource, subdir };
+  }
+
+  if (cleanSource.endsWith('.tar.gz') || cleanSource.endsWith('.tgz')) {
+    return { type: 'tarball', url: cleanSource, subdir };
+  }
+
+  if (cleanSource.endsWith('.zip')) {
+    return { type: 'zip', url: cleanSource, subdir };
+  }
+
+  let gitUrl = cleanSource;
+  if (gitUrl.startsWith('git@') || gitUrl.startsWith('ext::')) {
+    throw new Error('Only HTTPS git URLs are allowed for strategy install');
+  }
+  if (!gitUrl.startsWith('http://') && !gitUrl.startsWith('https://')) {
+    gitUrl = `https://${gitUrl}`;
+  }
+  if (gitUrl.startsWith('http://')) {
+    throw new Error('Only HTTPS sources are allowed for strategy install');
+  }
+  if (!gitUrl.endsWith('.git')) {
+    gitUrl = `${gitUrl}.git`;
+  }
+
+  return { type: 'git', url: gitUrl, subdir };
+}
+
+function hashContent(input: string): string {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+function copyDirSync(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isSymbolicLink()) {
+      const target = fs.readlinkSync(srcPath);
+      fs.symlinkSync(target, destPath);
+    } else if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function downloadFile(url: string, dest: string): void {
+  execFileSync('curl', ['-fsSL', '--proto', '=https', '-o', dest, url], {
+    stdio: 'pipe',
+    timeout: 60_000,
+  });
+}
+
+function findArchiveRoot(dir: string): string {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const dirs = entries.filter((entry) => entry.isDirectory());
+  if (dirs.length === 1 && !fs.existsSync(path.join(dir, 'app.md'))) {
+    return path.join(dir, dirs[0].name);
+  }
+  return dir;
+}
+
+function deriveAllowedHosts(explicit: string[] | undefined, sources: SourceDef[]): string[] {
+  const hosts = new Set(explicit || []);
+  for (const source of sources) {
+    if (source.url.startsWith('/') || source.url.includes('${')) continue;
+    try {
+      hosts.add(new URL(source.url).hostname);
+    } catch {
+      // Ignore unparseable URLs here; validated elsewhere.
+    }
+  }
+  return hosts.size > 0 ? Array.from(hosts) : [];
+}
+
+function resolveAllowedHosts(explicit: string[] | undefined, sources: SourceDef[]): string[] {
+  const normalizedExplicit = Array.isArray(explicit)
+    ? explicit.map((host) => host.trim()).filter((host) => host.length > 0)
+    : undefined;
+  if (normalizedExplicit && normalizedExplicit.length > 0) {
+    return deriveAllowedHosts(normalizedExplicit, sources);
+  }
+  return deriveAllowedHosts(undefined, sources);
+}
+
+function parseAppMarkdownManifest(appRoot: string, strategyId: string): { manifest: StrategyManifest; signaturePresent: boolean } {
+  const mdPath = path.join(appRoot, 'app.md');
+  if (!fs.existsSync(mdPath)) {
+    throw new Error('Source package missing app.md');
+  }
+
+  const raw = fs.readFileSync(mdPath, 'utf8');
+  const match = raw.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    throw new Error('app.md missing YAML frontmatter');
+  }
+
+  const parsed = parseYaml(match[1]) as Record<string, unknown>;
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('app.md frontmatter is invalid');
+  }
+
+  const sources = (parsed.sources as SourceDef[]) || [];
+  const manifest: StrategyManifest = {
+    id: strategyId,
+    name: (parsed.name as string) || strategyId,
+    icon: parsed.icon as string | undefined,
+    category: parsed.category as string | undefined,
+    size: parsed.size as string | undefined,
+    autoStart: parsed.autoStart === true,
+    ticker: parsed.ticker as StrategyManifest['ticker'],
+    jobs: parsed.jobs as StrategyManifest['jobs'],
+    sources,
+    keys: parsed.keys as StrategyManifest['keys'],
+    hooks: (parsed.hooks as StrategyManifest['hooks']) || {},
+    config: (parsed.config as StrategyManifest['config']) || {},
+    permissions: (parsed.permissions as string[]) || [],
+    limits: parsed.limits as StrategyManifest['limits'],
+    allowedHosts: resolveAllowedHosts(parsed.allowedHosts as string[] | undefined, sources),
+  };
+
+  manifest.sources = orderSources(manifest.sources);
+
+  const errors = validateManifest(manifest);
+  if (errors.length > 0) {
+    throw new Error(`Invalid strategy manifest: ${errors.join('; ')}`);
+  }
+
+  const signaturePresent = Boolean(parsed.signature)
+    || fs.existsSync(path.join(appRoot, 'SIGNATURE'))
+    || fs.existsSync(path.join(appRoot, 'app.md.sig'))
+    || fs.existsSync(path.join(appRoot, 'manifest.sig'));
+
+  return { manifest, signaturePresent };
+}
+
+async function fetchSourceToTemp(parsed: ParsedSource, tempDir: string): Promise<{ rootDir: string; ref: string | null }> {
+  if (parsed.type === 'local') {
+    const absPath = path.resolve(parsed.url);
+    if (!fs.existsSync(absPath)) throw new Error(`Local path not found: ${absPath}`);
+    copyDirSync(absPath, tempDir);
+    return { rootDir: tempDir, ref: null };
+  }
+
+  if (parsed.type === 'git') {
+    await validateExternalUrl(parsed.url);
+    execFileSync('git', ['clone', '--depth', '1', parsed.url, tempDir], {
+      stdio: 'pipe',
+      timeout: 60_000,
+    });
+    const ref = execFileSync('git', ['-C', tempDir, 'rev-parse', 'HEAD'], {
+      stdio: 'pipe',
+      timeout: 10_000,
+    }).toString().trim() || null;
+    return { rootDir: tempDir, ref };
+  }
+
+  if (parsed.type === 'tarball') {
+    const archivePath = path.join(tempDir, 'archive.tar.gz');
+    await validateExternalUrl(parsed.url);
+    downloadFile(parsed.url, archivePath);
+    const extractDir = path.join(tempDir, 'extracted');
+    fs.mkdirSync(extractDir, { recursive: true });
+    execFileSync('tar', ['xzf', archivePath, '-C', extractDir], {
+      stdio: 'pipe',
+      timeout: 30_000,
+    });
+    return { rootDir: findArchiveRoot(extractDir), ref: null };
+  }
+
+  const archivePath = path.join(tempDir, 'archive.zip');
+  await validateExternalUrl(parsed.url);
+  downloadFile(parsed.url, archivePath);
+  const extractDir = path.join(tempDir, 'extracted');
+  fs.mkdirSync(extractDir, { recursive: true });
+  execFileSync('unzip', ['-o', archivePath, '-d', extractDir], {
+    stdio: 'pipe',
+    timeout: 30_000,
+  });
+  return { rootDir: findArchiveRoot(extractDir), ref: null };
+}
+
+function applySubdir(rootDir: string, subdir: string | null): string {
+  if (!subdir) return rootDir;
+  const subPath = path.join(rootDir, subdir);
+  if (!fs.existsSync(subPath)) {
+    throw new Error(`Subdirectory not found: ${subdir}`);
+  }
+  return subPath;
+}
+
+export async function prepareThirdPartyStrategyFromSource(input: {
+  source: string;
+  strategyId: string;
+  strategyName?: string;
+}): Promise<PreparedThirdPartyStrategy> {
+  const parsed = parseSource(input.source);
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'aura-strategy-'));
+
+  try {
+    const { rootDir, ref } = await fetchSourceToTemp(parsed, tempDir);
+    const strategyRoot = applySubdir(rootDir, parsed.subdir);
+    const { manifest, signaturePresent } = parseAppMarkdownManifest(strategyRoot, input.strategyId);
+    if (input.strategyName && input.strategyName.trim()) {
+      manifest.name = input.strategyName.trim();
+    }
+
+    const normalizedUrl = parsed.type === 'local' ? path.resolve(parsed.url) : parsed.url;
+    const hash = hashContent(JSON.stringify(manifest));
+    const provenance: StrategyInstallProvenance = {
+      sourceType: parsed.type,
+      sourceUrl: normalizedUrl,
+      ref,
+      subdir: parsed.subdir,
+      hash,
+      signaturePresent,
+      installedAt: new Date().toISOString(),
+    };
+
+    return { manifest, provenance };
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+export function prepareThirdPartyStrategyFromManifest(input: {
+  manifest: StrategyManifest;
+  strategyId: string;
+  sourceLabel?: string;
+}): PreparedThirdPartyStrategy {
+  const manifest = {
+    ...input.manifest,
+    id: input.strategyId,
+    name: input.manifest.name || input.strategyId,
+    hooks: input.manifest.hooks || {},
+    sources: orderSources(input.manifest.sources || []),
+    config: input.manifest.config || {},
+    permissions: input.manifest.permissions || [],
+    allowedHosts: resolveAllowedHosts(input.manifest.allowedHosts, input.manifest.sources || []),
+  } as StrategyManifest;
+
+  const errors = validateManifest(manifest);
+  if (errors.length > 0) {
+    throw new Error(`Invalid strategy manifest: ${errors.join('; ')}`);
+  }
+
+  const hash = hashContent(JSON.stringify(manifest));
+  const provenance: StrategyInstallProvenance = {
+    sourceType: 'inline',
+    sourceUrl: input.sourceLabel || 'inline-manifest',
+    ref: null,
+    subdir: null,
+    hash,
+    signaturePresent: false,
+    installedAt: new Date().toISOString(),
+  };
+
+  return { manifest, provenance };
+}

package/server/lib/strategy/loader.ts

@@ -0,0 +1,256 @@
+/**
+ * Strategy Manifest Loader
+ *
+ * Scans apps directory for strategy manifests (those with ticker or jobs field).
+ * Uses the 'yaml' package for full YAML parsing (nested objects, multi-line strings).
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { StrategyManifest, SourceDef, TickTier, TICK_INTERVALS } from './types';
+import { isIPv4, isIPv6 } from 'net';
+import { isPrivateIp } from '../network';
+
+const VALID_TICKERS = Object.keys(TICK_INTERVALS) as TickTier[];
+
+/**
+ * Load all strategy manifests from apps/ directory.
+ * Only returns manifests with a ticker or jobs field (skips regular apps).
+ */
+export function loadStrategyManifests(): StrategyManifest[] {
+  const appsDir = path.join(process.cwd(), 'apps');
+  if (!fs.existsSync(appsDir)) return [];
+
+  const strategies: StrategyManifest[] = [];
+
+  for (const entry of fs.readdirSync(appsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const mdPath = path.join(appsDir, entry.name, 'app.md');
+    if (!fs.existsSync(mdPath)) continue;
+
+    const raw = fs.readFileSync(mdPath, 'utf-8');
+    const match = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) continue;
+
+    let manifest: Record<string, unknown>;
+    try {
+      manifest = parseYaml(match[1]);
+    } catch (err) {
+      console.error(`[strategy] Failed to parse ${mdPath}:`, err);
+      continue;
+    }
+
+    const hooks = manifest.hooks as StrategyManifest['hooks'] | undefined;
+    if (!manifest || (!manifest.ticker && !manifest.jobs && !hooks?.message)) continue;
+
+    const strategy: StrategyManifest = {
+      id: entry.name,
+      name: (manifest.name as string) || entry.name,
+      icon: manifest.icon as string | undefined,
+      category: manifest.category as string | undefined,
+      size: manifest.size as string | undefined,
+      autoStart: manifest.autoStart === true,
+      ticker: manifest.ticker as TickTier | undefined,
+      jobs: manifest.jobs as StrategyManifest['jobs'],
+      sources: (manifest.sources as SourceDef[]) || [],
+      keys: manifest.keys as StrategyManifest['keys'],
+      hooks: manifest.hooks as StrategyManifest['hooks'] || { tick: '', execute: '' },
+      config: (manifest.config as StrategyManifest['config']) || {},
+      permissions: (manifest.permissions as string[]) || [],
+      limits: manifest.limits as StrategyManifest['limits'],
+      allowedHosts: deriveAllowedHosts(
+        manifest.allowedHosts as string[] | undefined,
+        (manifest.sources as SourceDef[]) || [],
+      ),
+    };
+
+    const errors = validateManifest(strategy);
+    if (errors.length > 0) {
+      console.error(`[strategy] Invalid manifest ${entry.name}:`, errors);
+      continue;
+    }
+
+    // Sort sources by dependency order
+    strategy.sources = orderSources(strategy.sources);
+
+    strategies.push(strategy);
+  }
+
+  return strategies;
+}
+
+/**
+ * Validate a strategy manifest. Returns array of error strings (empty = valid).
+ */
+export function validateManifest(manifest: StrategyManifest): string[] {
+  const errors: string[] = [];
+
+  const hasTicker = !!manifest.ticker || !!manifest.jobs;
+  const hasMessage = !!manifest.hooks?.message;
+
+  // hooks.tick is required only when ticker or jobs is set
+  if (hasTicker && !manifest.hooks?.tick) {
+    errors.push('Missing hooks.tick (required when ticker or jobs is set)');
+  }
+
+  if (manifest.ticker && !VALID_TICKERS.includes(manifest.ticker)) {
+    errors.push(`Invalid ticker "${manifest.ticker}". Must be one of: ${VALID_TICKERS.join(', ')}`);
+  }
+
+  if (manifest.jobs) {
+    for (const job of manifest.jobs) {
+      if (!job.id) errors.push('Job missing id');
+      if (!job.ticker || !VALID_TICKERS.includes(job.ticker)) {
+        errors.push(`Job "${job.id}" has invalid ticker "${job.ticker}"`);
+      }
+    }
+  }
+
+  if (!hasTicker && !hasMessage) {
+    errors.push('Must have either ticker, jobs, or hooks.message');
+  }
+
+  // Validate allowedHosts — reject private IPs/hosts
+  if (manifest.allowedHosts) {
+    for (const host of manifest.allowedHosts) {
+      if (isPrivateHost(host)) {
+        errors.push(`allowedHosts contains private/reserved host: "${host}"`);
+      }
+    }
+  }
+
+  // Validate source URLs — reject private IPs/hosts at load time
+  for (const source of manifest.sources) {
+    if (!source.url.startsWith('/') && !source.url.includes('${')) {
+      try {
+        const parsed = new URL(source.url);
+        if (isPrivateHost(parsed.hostname)) {
+          errors.push(`Source "${source.id}" has private/reserved host in URL: "${parsed.hostname}"`);
+        }
+        if (manifest.allowedHosts && manifest.allowedHosts.length > 0 && !manifest.allowedHosts.includes(parsed.hostname)) {
+          errors.push(`Source "${source.id}" host "${parsed.hostname}" is not listed in allowedHosts`);
+        }
+      } catch {
+        // URL with template vars or invalid — validated at fetch time
+      }
+    }
+    if (!source.url.startsWith('/') && source.url.includes('${') && (!manifest.allowedHosts || manifest.allowedHosts.length === 0)) {
+      errors.push(`Source "${source.id}" uses a templated external URL and requires explicit allowedHosts`);
+    }
+  }
+
+  // Validate source dependencies exist
+  const sourceIds = new Set(manifest.sources.map(s => s.id));
+  for (const source of manifest.sources) {
+    if (source.depends && !sourceIds.has(source.depends)) {
+      errors.push(`Source "${source.id}" depends on unknown source "${source.depends}"`);
+    }
+  }
+
+  // Check for circular dependencies
+  if (hasCircularDeps(manifest.sources)) {
+    errors.push('Circular source dependencies detected');
+  }
+
+  return errors;
+}
+
+/**
+ * Topological sort of sources by dependency order.
+ * Independent sources come first, dependent sources come after their parents.
+ */
+export function orderSources(sources: SourceDef[]): SourceDef[] {
+  if (sources.length === 0) return [];
+
+  const byId = new Map(sources.map(s => [s.id, s]));
+  const ordered: SourceDef[] = [];
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  function visit(id: string) {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) return; // circular — already caught by validation
+    visiting.add(id);
+
+    const source = byId.get(id);
+    if (!source) return;
+
+    if (source.depends) {
+      visit(source.depends);
+    }
+
+    visiting.delete(id);
+    visited.add(id);
+    ordered.push(source);
+  }
+
+  for (const source of sources) {
+    visit(source.id);
+  }
+
+  return ordered;
+}
+
+/**
+ * Derive the combined allowedHosts list from explicit YAML declaration
+ * and auto-extracted hostnames from source URLs.
+ */
+function deriveAllowedHosts(
+  explicit: string[] | undefined,
+  sources: SourceDef[],
+): string[] {
+  const hosts = new Set(explicit || []);
+
+  for (const source of sources) {
+    // Skip internal URLs (start with /) and URLs with template vars
+    if (source.url.startsWith('/') || source.url.includes('${')) continue;
+    try {
+      const parsed = new URL(source.url);
+      hosts.add(parsed.hostname);
+    } catch {
+      // Skip unparseable URLs
+    }
+  }
+
+  return hosts.size > 0 ? Array.from(hosts) : [];
+}
+
+/**
+ * Check if a hostname string is obviously private (pre-DNS, for manifest validation).
+ */
+function isPrivateHost(hostname: string): boolean {
+  if (['localhost', '127.0.0.1', '0.0.0.0', '::1', '[::1]', ''].includes(hostname)) return true;
+  if (isIPv4(hostname) || isIPv6(hostname)) return isPrivateIp(hostname);
+  return false;
+}
+
+/**
+ * Check for circular dependencies in sources.
+ */
+function hasCircularDeps(sources: SourceDef[]): boolean {
+  const byId = new Map(sources.map(s => [s.id, s]));
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  function hasCycle(id: string): boolean {
+    if (visiting.has(id)) return true;
+    if (visited.has(id)) return false;
+    visiting.add(id);
+
+    const source = byId.get(id);
+    if (source?.depends) {
+      if (hasCycle(source.depends)) return true;
+    }
+
+    visiting.delete(id);
+    visited.add(id);
+    return false;
+  }
+
+  for (const source of sources) {
+    if (hasCycle(source.id)) return true;
+  }
+
+  return false;
+}