@adhdev/daemon-core 0.9.82-rc.16 → 0.9.82-rc.161

package/src/providers/sdk/v1/types/common/index.ts

@@ -0,0 +1,210 @@
+/**
+ * Shared types across provider categories.
+ *
+ * Extracted at build time into the Apache 2.0 npm package
+ * `@adhdev/provider-types`. External provider authors import from there;
+ * daemon-core imports from this file directly.
+ */
+
+// ─── Settings ───────────────────────────────────────────────────────────
+
+export interface BooleanSettingDef {
+  type: 'boolean';
+  default: boolean;
+  public?: boolean;
+  label?: string;
+  description?: string;
+}
+
+export interface NumberSettingDef {
+  type: 'number';
+  default: number;
+  public?: boolean;
+  label?: string;
+  description?: string;
+  min?: number;
+  max?: number;
+}
+
+export interface StringSettingDef {
+  type: 'string';
+  default: string;
+  public?: boolean;
+  label?: string;
+  description?: string;
+}
+
+export interface SelectSettingDef {
+  type: 'select';
+  default: string;
+  options: ReadonlyArray<string | { value: string; label?: string }>;
+  public?: boolean;
+  label?: string;
+  description?: string;
+}
+
+export type SettingDef =
+  | BooleanSettingDef
+  | NumberSettingDef
+  | StringSettingDef
+  | SelectSettingDef;
+
+export type SettingsDef = Readonly<Record<string, SettingDef>>;
+
+// ─── Capabilities ───────────────────────────────────────────────────────
+
+export interface CapabilityInputDef {
+  multipart?: boolean;
+  mediaTypes?: ReadonlyArray<'text' | 'image' | 'audio' | string>;
+  strategies?: ReadonlyArray<{
+    mediaType: string;
+    strategies: ReadonlyArray<string>;
+    native?: boolean;
+    degradation?: ReadonlyArray<string>;
+  }>;
+}
+
+export interface CapabilityOutputDef {
+  richContent?: boolean;
+  mediaTypes?: ReadonlyArray<string>;
+}
+
+export interface CapabilityControlsDef {
+  typedResults?: boolean;
+}
+
+export interface CapabilitiesDef {
+  input?: CapabilityInputDef;
+  output?: CapabilityOutputDef;
+  controls?: CapabilityControlsDef;
+}
+
+// ─── Auth ───────────────────────────────────────────────────────────────
+
+export interface EnvVarAuthDef {
+  type: 'env_var';
+  id: string;
+  name: string;
+  vars: ReadonlyArray<{ name: string; description?: string }>;
+  link?: string;
+}
+
+export interface CliCommandAuthDef {
+  type: 'cli_command';
+  id: string;
+  name: string;
+  command: string;
+  link?: string;
+}
+
+export type AuthDef = EnvVarAuthDef | CliCommandAuthDef;
+
+// ─── Spawn ──────────────────────────────────────────────────────────────
+
+export interface SpawnDef {
+  command: string;
+  args?: ReadonlyArray<string>;
+  shell?: boolean;
+  env?: Readonly<Record<string, string>>;
+}
+
+// ─── Timeouts ───────────────────────────────────────────────────────────
+
+export interface TimeoutsDef {
+  /** Gap between writes before considering a chunk settled (ms). */
+  ptyFlush?: number;
+  /** Delay before sending an approval key (ms). */
+  dialogAccept?: number;
+  /** Window during which a freshly resolved modal is suppressed (ms). */
+  approvalCooldown?: number;
+  /** Fallback "still generating" assumption window (ms). */
+  generatingIdle?: number;
+  /** Grace before declaring generating→idle final (ms). */
+  idleFinish?: number;
+  /** Second-pass confirmation window (ms). */
+  idleFinishConfirm?: number;
+  /** PTY-quiet threshold before marking activity ended (ms). */
+  statusActivityHold?: number;
+  /** Hard upper bound on a single generation (ms). */
+  maxResponse?: number;
+  /** SIGTERM→SIGKILL window (ms). */
+  shutdownGrace?: number;
+  /** Post-write debounce (ms). */
+  outputSettle?: number;
+}
+
+// ─── Resume ─────────────────────────────────────────────────────────────
+
+export type StopStrategy = 'command' | 'ctrl_c' | 'signal';
+export type SessionIdFormat = 'uuid' | 'free' | 'string';
+
+export interface ResumeDef {
+  supported: boolean;
+  stopStrategy?: StopStrategy;
+  stopCommand?: string;
+  shutdownGraceMs?: number;
+  sessionIdFormat?: SessionIdFormat;
+  /** Args appended to spawn.args when starting a session under a daemon-issued id. `{{id}}` is replaced at launch. */
+  newSessionArgs?: ReadonlyArray<string>;
+  /** Args appended when resuming a specific session id. */
+  resumeSessionArgs?: ReadonlyArray<string>;
+  /** Args appended when "continue most recent" semantics are wanted. */
+  resumeArgs?: ReadonlyArray<string>;
+}
+
+// ─── Mesh coordinator ───────────────────────────────────────────────────
+
+export interface McpConfigDef {
+  mode: 'manual' | 'auto_import';
+  format?: string;
+  path?: string;
+  configPathCommand?: string;
+  serverName?: string;
+  requiresRestart?: boolean;
+  instructions?: string;
+  /** Template string used by daemon to render the actual config snippet at install time. */
+  template?: string;
+}
+
+export interface MeshCoordinatorDef {
+  supported: boolean;
+  mcpConfig?: McpConfigDef;
+}
+
+// ─── Compatibility ──────────────────────────────────────────────────────
+
+export interface CompatibilityEntryDef {
+  /** SemVer range against the agent's own version. Optional. */
+  ideVersion?: string;
+  /** Script subdirectory to load when this entry matches. e.g. "scripts/1.0". */
+  scriptDir: string;
+}
+
+// ─── Controls (dashboard chips/buttons) ─────────────────────────────────
+
+export type ControlType = 'select' | 'action' | 'toggle';
+
+export interface ControlDef {
+  id: string;
+  type: ControlType;
+  label: string;
+  icon?: string;
+  placement?: string;
+  order?: number;
+  dynamic?: boolean;
+  hidden?: boolean;
+  options?: ReadonlyArray<unknown>;
+  listScript?: string;
+  setScript?: string;
+  invokeScript?: string;
+  readFrom?: string;
+  resultDisplay?: string;
+  defaultValue?: unknown;
+  confirmTitle?: string;
+  confirmMessage?: string;
+  confirmLabel?: string;
+}
+
+// ─── Provider status flag ───────────────────────────────────────────────
+
+export type ProviderLifecycleStatus = 'Stable' | 'Beta' | 'Experimental' | 'Deprecated';

package/src/providers/sdk/v1/validators/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Validators — public surface.
+ */
+
+export {
+  analyzeOverrideTaint,
+  formatTaintResult,
+  type TaintLevel,
+  type TaintCategory,
+  type TaintFinding,
+  type TaintResult,
+} from './taint.js';
+
+export {
+  validateCliProviderManifest,
+  formatManifestValidationIssues,
+  type ManifestValidationIssue,
+  type ManifestValidationResult,
+} from './manifest.js';

package/src/providers/sdk/v1/validators/manifest.ts

@@ -0,0 +1,110 @@
+/**
+ * Manifest validators — runtime JSON Schema check for v1 provider manifests.
+ *
+ * The schemas live under `schemas/{category}/provider.schema.json` and are
+ * the authoritative contract for what a v1 manifest may contain. Daemon
+ * code that loads a manifest at install or boot time runs it through
+ * `validateCliProviderManifest()` first; failures are reported back to
+ * the caller with structured paths so manifest authors can locate the
+ * offending field without guessing.
+ *
+ * Validation lives in the SDK layer (not in provider-loader) so dashboards,
+ * registry workers, and the marketplace publish flow can all reuse the
+ * same code path and produce identical error messages.
+ */
+
+import Ajv2020, { type ErrorObject, type ValidateFunction } from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import cliProviderSchema from '../schemas/cli/provider.schema.json';
+
+export interface ManifestValidationIssue {
+    /** JSON Pointer-style path into the manifest. Empty string for the root. */
+    path: string;
+    /** Schema-keyword that failed. */
+    keyword: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Allowed values when the failure is an `enum` / `const` / `additionalProperties`. */
+    allowed?: unknown;
+}
+
+export interface ManifestValidationResult {
+    ok: boolean;
+    issues: ManifestValidationIssue[];
+}
+
+let _ajv: Ajv2020 | null = null;
+let _cliValidator: ValidateFunction | null = null;
+
+function getAjv(): Ajv2020 {
+    if (_ajv) return _ajv;
+    // strict=false because the schema authors freely use schema-level
+    // `description`/`examples` fields that ajv would otherwise warn about.
+    // allErrors=true so a single validation run reports every problem at
+    // once instead of bailing on the first — that's what makes the
+    // structured-error output usable for manifest authors.
+    _ajv = new Ajv2020({
+        strict: false,
+        allErrors: true,
+        allowUnionTypes: true,
+    });
+    addFormats(_ajv);
+    return _ajv;
+}
+
+function getCliValidator(): ValidateFunction {
+    if (_cliValidator) return _cliValidator;
+    _cliValidator = getAjv().compile(cliProviderSchema as unknown as object);
+    return _cliValidator;
+}
+
+function formatIssue(err: ErrorObject): ManifestValidationIssue {
+    const path = err.instancePath || '';
+    const params = err.params as Record<string, unknown>;
+    let message = err.message || 'validation failed';
+    let allowed: unknown;
+
+    if (err.keyword === 'additionalProperties') {
+        const extra = params.additionalProperty;
+        message = `unexpected property "${extra}"`;
+    } else if (err.keyword === 'required') {
+        message = `missing required property "${params.missingProperty}"`;
+    } else if (err.keyword === 'enum') {
+        allowed = params.allowedValues;
+        message = `must be one of ${JSON.stringify(allowed)}`;
+    } else if (err.keyword === 'const') {
+        allowed = params.allowedValue;
+        message = `must equal ${JSON.stringify(allowed)}`;
+    } else if (err.keyword === 'type') {
+        message = `must be ${params.type}`;
+    }
+
+    return { path, keyword: err.keyword, message, ...(allowed !== undefined ? { allowed } : {}) };
+}
+
+/**
+ * Validate a CLI provider.v1.json manifest. Returns `{ ok: true, issues: [] }`
+ * on success and `{ ok: false, issues: [...] }` on failure with each issue
+ * pointing at the offending field. Never throws — manifest parse errors
+ * should be caught by the caller before this is called.
+ */
+export function validateCliProviderManifest(manifest: unknown): ManifestValidationResult {
+    const validator = getCliValidator();
+    const ok = validator(manifest) as boolean;
+    if (ok) return { ok: true, issues: [] };
+    const issues = (validator.errors || []).map(formatIssue);
+    return { ok: false, issues };
+}
+
+/**
+ * Render a list of validation issues as a single multi-line string,
+ * suitable for log lines or daemon command error fields.
+ */
+export function formatManifestValidationIssues(issues: ManifestValidationIssue[]): string {
+    return issues
+        .map((issue) => {
+            const where = issue.path || '<root>';
+            return `  - ${where}: ${issue.message} (${issue.keyword})`;
+        })
+        .join('\n');
+}

package/src/providers/sdk/v1/validators/taint.ts

@@ -0,0 +1,309 @@
+/**
+ * Static taint analyzer for extended-tier override JS.
+ *
+ * Goal: classify the override JS shipped with an extended-tier provider into
+ * one of three risk tiers, so the marketplace + daemon trust prompt can
+ * surface accurate language to the operator instead of a single generic
+ * "this provider contains JS" warning.
+ *
+ *   - clean    : no flagged APIs at all. The override looks like pure string
+ *                manipulation. Still extended-tier, but the warning copy is
+ *                "this provider contains JS; nothing dangerous was detected".
+ *   - elevated : touches process / dynamic codegen / dynamic require / eval
+ *                / Function constructor / child_process. The warning copy is
+ *                explicit ("this provider can run shell commands / dynamically
+ *                load code").
+ *   - hostile  : combines elevated APIs with network egress, AND uses obvious
+ *                obfuscation (base64-decoded strings fed into Function / eval).
+ *                The publish endpoint should reject these.
+ *
+ * Implementation note: this is a *static* analyzer — string + light AST scan
+ * via Node's built-in parser. It is intentionally fail-loud: anything that
+ * looks suspicious is flagged. False positives are fine; this exists to gate
+ * the trust prompt, not to be a real sandbox. The real sandbox lives in
+ * Phase 5 (isolated-vm).
+ *
+ * Used by:
+ *   - `adhdev provider validate` (CLI tier classification)
+ *   - registry publish endpoint static-check
+ *   - daemon at provider-load time, to size the warning
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+
+// ─── Findings ──────────────────────────────────────────────────────────
+
+export type TaintLevel = 'clean' | 'elevated' | 'hostile';
+
+export interface TaintFinding {
+  /** What was found, e.g. "child_process.exec". */
+  api: string;
+  /** Coarse category. */
+  category: TaintCategory;
+  /** File the finding came from. */
+  file: string;
+  /** Line number (1-indexed) of the first character of the matched token. */
+  line: number;
+  /** The surrounding source excerpt, trimmed. */
+  excerpt: string;
+}
+
+export type TaintCategory =
+  | 'process-control'   // process.exit, process.kill
+  | 'shell-exec'        // child_process.{exec,execSync,spawn,spawnSync,fork}
+  | 'fs-write'          // fs.writeFile / writeFileSync outside override dir
+  | 'fs-read'           // fs.readFile / readFileSync
+  | 'network'           // http(s).request, fetch, net.connect, dgram
+  | 'dynamic-codegen'   // eval, new Function(), Function('...')
+  | 'dynamic-require'   // require(variable), import(variable)
+  | 'obfuscation'       // Buffer.from(...,'base64').toString + (eval|Function)
+  | 'global-mutation';  // mutating Object.prototype, process.env
+
+export interface TaintResult {
+  level: TaintLevel;
+  findings: TaintFinding[];
+  files: string[];
+}
+
+// ─── Patterns ──────────────────────────────────────────────────────────
+
+interface PatternRule {
+  category: TaintCategory;
+  /** Display label. */
+  label: string;
+  /** Regex applied per-line. */
+  pattern: RegExp;
+}
+
+const PATTERNS: PatternRule[] = [
+  {
+    category: 'shell-exec',
+    label: 'child_process.exec',
+    pattern: /\bchild_process\b[\s\S]{0,40}?\b(exec|execSync|spawn|spawnSync|fork|execFile)\b/,
+  },
+  {
+    category: 'shell-exec',
+    label: 'require("child_process")',
+    pattern: /\brequire\s*\(\s*['"]child_process['"]\s*\)/,
+  },
+  {
+    category: 'shell-exec',
+    label: 'import child_process',
+    pattern: /\bfrom\s+['"](?:node:)?child_process['"]/,
+  },
+  {
+    category: 'process-control',
+    label: 'process.exit / kill',
+    pattern: /\bprocess\.(exit|kill|abort)\s*\(/,
+  },
+  {
+    category: 'global-mutation',
+    label: 'process.env mutation',
+    pattern: /\bprocess\.env\.[A-Z_][A-Z0-9_]*\s*=/,
+  },
+  {
+    category: 'global-mutation',
+    label: 'prototype pollution',
+    pattern: /\bObject\.prototype\b.*=/,
+  },
+  {
+    category: 'dynamic-codegen',
+    label: 'eval()',
+    pattern: /(?<![A-Za-z0-9_$])eval\s*\(/,
+  },
+  {
+    category: 'dynamic-codegen',
+    label: 'new Function()',
+    pattern: /\bnew\s+Function\s*\(/,
+  },
+  {
+    category: 'dynamic-require',
+    label: 'require(variable)',
+    pattern: /\brequire\s*\(\s*(?!['"`])/,
+  },
+  {
+    category: 'dynamic-require',
+    label: 'import(variable)',
+    pattern: /(?<![.\w])import\s*\(\s*(?!['"`])/,
+  },
+  {
+    category: 'network',
+    label: 'fetch()',
+    pattern: /(?<![A-Za-z0-9_$])fetch\s*\(/,
+  },
+  {
+    category: 'network',
+    label: 'http(s).request',
+    pattern: /\b(https?)\.(request|get)\s*\(/,
+  },
+  {
+    category: 'network',
+    label: 'net.connect / Socket',
+    pattern: /\b(net\.connect|tls\.connect|new\s+net\.Socket)\b/,
+  },
+  {
+    category: 'network',
+    label: 'dgram',
+    pattern: /\brequire\s*\(\s*['"](?:node:)?dgram['"]/,
+  },
+  {
+    category: 'fs-write',
+    label: 'fs.writeFile / writeFileSync',
+    pattern: /\bfs\.(writeFile|writeFileSync|appendFile|appendFileSync|unlink|unlinkSync|rm|rmSync)\b/,
+  },
+  {
+    category: 'fs-read',
+    label: 'fs.readFile / readFileSync',
+    pattern: /\bfs\.(readFile|readFileSync|readdir|readdirSync|stat|statSync)\b/,
+  },
+];
+
+// Obfuscation heuristic: base64 / hex decode feeding into eval or Function.
+const OBFUSCATION_PATTERN =
+  /Buffer\.from\s*\([^)]*['"](?:base64|hex)['"]\s*\)\s*\.toString\s*\([^)]*\)[\s\S]{0,80}?(eval|Function)\s*\(/;
+
+// ─── File walker — picks up everything reachable from overrides ────────
+
+function listOverrideJsFiles(manifestPath: string): string[] {
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8')) as { overrides?: Record<string, unknown> };
+  if (!manifest.overrides) return [];
+  const base = dirname(manifestPath);
+  const out = new Set<string>();
+  for (const value of Object.values(manifest.overrides)) {
+    let rel: string | null = null;
+    if (typeof value === 'string') rel = value;
+    else if (value && typeof value === 'object' && 'path' in value && typeof (value as { path: unknown }).path === 'string') {
+      rel = (value as { path: string }).path;
+    }
+    if (!rel) continue;
+    const abs = resolve(base, rel);
+    if (existsSync(abs)) out.add(abs);
+  }
+  // Best-effort: also scan sibling scripts/ tree, since overrides commonly
+  // require() helpers from there.
+  for (const candidate of ['scripts']) {
+    const dir = join(base, candidate);
+    if (existsSync(dir)) {
+      try {
+        walk(dir, out);
+      } catch {
+        // Ignore individual unreadable files.
+      }
+    }
+  }
+  return [...out];
+}
+
+function walk(dir: string, into: Set<string>): void {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { readdirSync, statSync } = require('node:fs') as typeof import('node:fs');
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    let st;
+    try { st = statSync(abs); } catch { continue; }
+    if (st.isDirectory()) walk(abs, into);
+    else if (st.isFile() && /\.(?:m|c)?js$/.test(entry)) into.add(abs);
+  }
+}
+
+// ─── Scanner ───────────────────────────────────────────────────────────
+
+function scanFile(file: string): TaintFinding[] {
+  const source = readFileSync(file, 'utf-8');
+  const findings: TaintFinding[] = [];
+  // Per-line scan keeps line numbers honest.
+  const lines = source.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    for (const rule of PATTERNS) {
+      if (rule.pattern.test(line)) {
+        findings.push({
+          api: rule.label,
+          category: rule.category,
+          file,
+          line: i + 1,
+          excerpt: line.trim().slice(0, 200),
+        });
+      }
+    }
+  }
+  // Whole-file scan for obfuscation pattern (may span lines).
+  if (OBFUSCATION_PATTERN.test(source)) {
+    findings.push({
+      api: 'base64/hex → eval|Function',
+      category: 'obfuscation',
+      file,
+      line: 1,
+      excerpt: '<obfuscation pattern across multiple lines>',
+    });
+  }
+  return findings;
+}
+
+// ─── Classification ────────────────────────────────────────────────────
+
+const ELEVATED_CATEGORIES = new Set<TaintCategory>([
+  'shell-exec',
+  'process-control',
+  'dynamic-codegen',
+  'dynamic-require',
+  'fs-write',
+  'global-mutation',
+]);
+
+const HOSTILE_REQUIRES = new Set<TaintCategory>([
+  'obfuscation',
+]);
+
+function classify(findings: TaintFinding[]): TaintLevel {
+  if (findings.length === 0) return 'clean';
+  const cats = new Set(findings.map((f) => f.category));
+  if ([...cats].some((c) => HOSTILE_REQUIRES.has(c))) return 'hostile';
+  // Hostile also: elevated + network combined.
+  const hasElevated = [...cats].some((c) => ELEVATED_CATEGORIES.has(c));
+  const hasNetwork = cats.has('network');
+  if (hasElevated && hasNetwork) return 'hostile';
+  if (hasElevated || hasNetwork) return 'elevated';
+  return 'clean'; // only fs-read on its own is fine.
+}
+
+// ─── Public API ────────────────────────────────────────────────────────
+
+export function analyzeOverrideTaint(manifestPath: string): TaintResult {
+  const files = listOverrideJsFiles(manifestPath);
+  const findings: TaintFinding[] = [];
+  for (const f of files) findings.push(...scanFile(f));
+  return {
+    level: classify(findings),
+    findings,
+    files,
+  };
+}
+
+/** Format a result as a single CLI-friendly block. */
+export function formatTaintResult(result: TaintResult): string {
+  const lines: string[] = [];
+  lines.push(`Tier: extended (override JS present)`);
+  lines.push(`Risk level: ${result.level}`);
+  lines.push(`Files scanned: ${result.files.length}`);
+  if (result.findings.length === 0) {
+    lines.push('No flagged APIs detected.');
+    return lines.join('\n');
+  }
+  // Group by category for a tighter report.
+  const byCat = new Map<TaintCategory, TaintFinding[]>();
+  for (const f of result.findings) {
+    const arr = byCat.get(f.category) ?? [];
+    arr.push(f);
+    byCat.set(f.category, arr);
+  }
+  for (const [cat, items] of byCat) {
+    lines.push(`  ${cat}: ${items.length} occurrence(s)`);
+    for (const f of items.slice(0, 5)) {
+      lines.push(`    ${f.file}:${f.line}  ${f.api}`);
+    }
+    if (items.length > 5) lines.push(`    …and ${items.length - 5} more`);
+  }
+  return lines.join('\n');
+}