cipher-security 5.0.0

package/lib/api/server.js

@@ -0,0 +1,685 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+
+/**
+ * CIPHER REST API Server — zero-dependency SaaS server.
+ *
+ * Built on node:http. Provides authenticated, rate-limited endpoints
+ * that expose CIPHER's scanning, memory, leaderboard, and workflow
+ * capabilities over HTTP/JSON.
+ */
+
+import { createServer as httpCreateServer } from 'node:http';
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { URL } from 'node:url';
+import { isIP } from 'node:net';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Server-level configuration with safe defaults. */
+export class APIConfig {
+  constructor(opts = {}) {
+    this.host = opts.host ?? '127.0.0.1';
+    this.port = opts.port ?? 8443;
+    this.apiVersion = opts.apiVersion ?? 'v1';
+    this.rateLimitRpm = opts.rateLimitRpm ?? 60;
+    this.maxRequestSize = opts.maxRequestSize ?? 1_048_576; // 1 MB
+    this.corsOrigins = opts.corsOrigins ?? ['*'];
+    this.requireAuth = opts.requireAuth ?? true;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Response envelope
+// ---------------------------------------------------------------------------
+
+/** Uniform JSON response wrapper. */
+export class APIResponse {
+  constructor({ status = 200, data = null, error = null, meta = null } = {}) {
+    this.status = status;
+    this.data = data;
+    this.error = error;
+    this.meta = meta;
+  }
+
+  toJson() {
+    const payload = { status: this.status };
+    if (this.data !== null) payload.data = this.data;
+    if (this.error !== null) payload.error = this.error;
+    if (this.meta !== null) payload.meta = this.meta;
+    return JSON.stringify(payload);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rate limiter — sliding-window per client
+// ---------------------------------------------------------------------------
+
+/** Sliding-window rate limiter. */
+export class RateLimiter {
+  constructor(rpm = 60) {
+    this._rpm = rpm;
+    this._window = 60_000; // ms
+    /** @type {Map<string, number[]>} */
+    this._requests = new Map();
+  }
+
+  /**
+   * Return true if the request is allowed.
+   * @param {string} clientId
+   * @returns {boolean}
+   */
+  check(clientId) {
+    const now = Date.now();
+    const cutoff = now - this._window;
+    let timestamps = this._requests.get(clientId) || [];
+    timestamps = timestamps.filter((t) => t > cutoff);
+    if (timestamps.length >= this._rpm) {
+      this._requests.set(clientId, timestamps);
+      return false;
+    }
+    timestamps.push(now);
+    this._requests.set(clientId, timestamps);
+    return true;
+  }
+
+  /** Get current state for diagnostics. */
+  getState() {
+    return {
+      trackedClients: this._requests.size,
+      rpm: this._rpm,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auth — HMAC-SHA256 bearer tokens
+// ---------------------------------------------------------------------------
+
+/**
+ * HMAC-SHA256 token auth.
+ * Tokens: `<client_id>:<random_hex>:<hmac_hex>`
+ */
+export class AuthHandler {
+  constructor() {
+    this._secret = process.env.CIPHER_API_SECRET || randomBytes(32).toString('hex');
+    /** @type {Map<string, string[]>} */
+    this._scopes = new Map();
+  }
+
+  /**
+   * Create a signed bearer token.
+   * @param {string} clientId
+   * @param {string[]} [scopes]
+   * @returns {string}
+   */
+  generateToken(clientId, scopes = ['read', 'write']) {
+    this._scopes.set(clientId, scopes);
+    const nonce = randomBytes(16).toString('hex');
+    const payload = `${clientId}:${nonce}`;
+    const sig = createHmac('sha256', this._secret).update(payload).digest('hex');
+    return `${payload}:${sig}`;
+  }
+
+  /**
+   * Validate a bearer token.
+   * @param {string} token
+   * @returns {{ clientId: string, scopes: string[] } | null}
+   */
+  validateToken(token) {
+    const parts = token.split(':');
+    if (parts.length !== 3) return null;
+    const [clientId, nonce, sig] = parts;
+    const expected = createHmac('sha256', this._secret)
+      .update(`${clientId}:${nonce}`)
+      .digest('hex');
+
+    // Length pre-check to avoid timing oracle on different-length strings
+    if (sig.length !== expected.length) return null;
+    const sigBuf = Buffer.from(sig, 'utf8');
+    const expBuf = Buffer.from(expected, 'utf8');
+    if (!timingSafeEqual(sigBuf, expBuf)) return null;
+
+    const scopes = this._scopes.get(clientId) || ['read'];
+    return { clientId, scopes };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SSRF validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate scan target to prevent SSRF against internal networks.
+ * @param {string} target
+ * @returns {boolean}
+ */
+export function validateScanTarget(target) {
+  if (!target || typeof target !== 'string' || target.length > 2048) return false;
+
+  let host;
+  try {
+    const parsed = new URL(target.includes('://') ? target : `http://${target}`);
+    host = parsed.hostname;
+  } catch {
+    return false;
+  }
+  if (!host) return false;
+
+  const blockedHosts = new Set([
+    'metadata.google.internal',
+    'metadata.google',
+    '169.254.169.254',
+    'fd00:ec2::254',
+    'localhost',
+    'localhost.localdomain',
+    '0.0.0.0',
+  ]);
+  if (blockedHosts.has(host.toLowerCase())) return false;
+
+  // Check if it looks like a private/loopback IP
+  if (isIP(host)) {
+    // Simple private range checks
+    if (host.startsWith('10.') || host.startsWith('192.168.') || host === '127.0.0.1') return false;
+    if (host.startsWith('172.')) {
+      const second = parseInt(host.split('.')[1], 10);
+      if (second >= 16 && second <= 31) return false;
+    }
+    if (host.startsWith('169.254.')) return false;
+    if (host === '::1' || host.startsWith('fe80:') || host.startsWith('fc') || host.startsWith('fd')) return false;
+  }
+
+  // Reject numeric-looking hosts that might be encoded IPs
+  if (/^[0-9x.]+$/i.test(host) && !isIP(host)) return false;
+
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Main server
+// ---------------------------------------------------------------------------
+
+/**
+ * CIPHER SaaS REST API server.
+ * @param {APIConfig} [config]
+ * @returns {{ server: import('node:http').Server, config: APIConfig, auth: AuthHandler, rateLimiter: RateLimiter, start: () => Promise<number>, stop: () => Promise<void> }}
+ */
+export function createAPIServer(config) {
+  config = config instanceof APIConfig ? config : new APIConfig(config);
+  const auth = new AuthHandler();
+  const rateLimiter = new RateLimiter(config.rateLimitRpm);
+  const startTime = Date.now();
+  let requestCount = 0;
+  const v = config.apiVersion;
+
+  // -- Route table ----------------------------------------------------------
+
+  const routes = [
+    { method: 'GET', path: `/${v}/health`, handler: handleHealth, authRequired: false, scopes: [] },
+    { method: 'GET', path: `/${v}/stats`, handler: handleStats, authRequired: true, scopes: [] },
+    { method: 'POST', path: `/${v}/scan`, handler: handleScan, authRequired: true, scopes: ['write'] },
+    { method: 'POST', path: `/${v}/diff`, handler: handleDiff, authRequired: true, scopes: ['write'] },
+    { method: 'POST', path: `/${v}/secrets`, handler: handleSecrets, authRequired: true, scopes: ['write'] },
+    { method: 'GET', path: `/${v}/skills`, handler: handleSkillsList, authRequired: true, scopes: [] },
+    { method: 'GET', path: `/${v}/skills/search`, handler: handleSkillsSearch, authRequired: true, scopes: [] },
+    { method: 'POST', path: `/${v}/memory/store`, handler: handleMemoryStore, authRequired: true, scopes: ['write'] },
+    { method: 'POST', path: `/${v}/memory/search`, handler: handleMemorySearch, authRequired: true, scopes: [] },
+    { method: 'GET', path: `/${v}/memory/stats`, handler: handleMemoryStats, authRequired: true, scopes: [] },
+    { method: 'POST', path: `/${v}/score`, handler: handleScore, authRequired: true, scopes: ['write'] },
+    { method: 'GET', path: `/${v}/leaderboard`, handler: handleLeaderboard, authRequired: true, scopes: [] },
+    { method: 'GET', path: `/${v}/leaderboard/dashboard`, handler: handleLeaderboardDashboard, authRequired: true, scopes: [] },
+    { method: 'POST', path: `/${v}/workflow`, handler: handleWorkflow, authRequired: true, scopes: ['write'] },
+  ];
+
+  // -- Helpers --------------------------------------------------------------
+
+  function meta(t0) {
+    return { version: v, elapsed_ms: Math.round((Date.now() - t0) * 100) / 100 };
+  }
+
+  function clientIp(headers) {
+    const xff = headers['x-forwarded-for'];
+    if (xff) return xff.split(',')[0].trim();
+    return headers['x-real-ip'] || 'unknown';
+  }
+
+  function extractAuth(headers) {
+    const authHeader = headers['authorization'];
+    if (authHeader && authHeader.toLowerCase().startsWith('bearer ')) {
+      return authHeader.slice(7).trim();
+    }
+    return null;
+  }
+
+  function matchRoute(method, pathname) {
+    const clean = pathname.replace(/\/+$/, '') || '/';
+    return routes.find((r) => r.method === method && r.path === clean) || null;
+  }
+
+  function setCors(res, reqOrigin) {
+    const allowed = config.corsOrigins;
+    const origin = allowed.includes('*') || allowed.includes(reqOrigin) ? reqOrigin || '*' : allowed[0] || '';
+    res.setHeader('Access-Control-Allow-Origin', origin);
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+    res.setHeader('Access-Control-Max-Age', '86400');
+  }
+
+  function sendJson(res, response) {
+    const body = response.toJson();
+    res.writeHead(response.status, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Content-Length': Buffer.byteLength(body),
+    });
+    res.end(body);
+  }
+
+  // -- Request parsing ------------------------------------------------------
+
+  function parseBody(req) {
+    return new Promise((resolve) => {
+      const chunks = [];
+      let size = 0;
+      req.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > config.maxRequestSize) {
+          resolve({ __error__: 'payload too large' });
+          req.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      req.on('end', () => {
+        if (size === 0) return resolve({});
+        try {
+          resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+        } catch {
+          resolve({ __error__: 'invalid JSON' });
+        }
+      });
+      req.on('error', () => resolve({ __error__: 'request error' }));
+    });
+  }
+
+  // -- Dispatch engine -------------------------------------------------------
+
+  async function handleRequest(req, res) {
+    const t0 = Date.now();
+    requestCount++;
+
+    const origin = req.headers['origin'] || '*';
+    setCors(res, origin);
+
+    // CORS preflight
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    const parsedUrl = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+    const pathname = parsedUrl.pathname;
+    const params = Object.fromEntries(
+      [...parsedUrl.searchParams].map(([k, v]) => [k, v]),
+    );
+
+    const body =
+      req.method === 'POST' || req.method === 'PUT' ? await parseBody(req) : {};
+
+    if (body.__error__) {
+      return sendJson(res, new APIResponse({ status: 400, error: body.__error__, meta: meta(t0) }));
+    }
+
+    const route = matchRoute(req.method, pathname);
+    if (!route) {
+      return sendJson(res, new APIResponse({ status: 404, error: 'not found', meta: meta(t0) }));
+    }
+
+    // Auth
+    let clientId;
+    if (route.authRequired && config.requireAuth) {
+      const token = extractAuth(req.headers);
+      if (!token) {
+        return sendJson(res, new APIResponse({ status: 401, error: 'missing authorization', meta: meta(t0) }));
+      }
+      const identity = auth.validateToken(token);
+      if (!identity) {
+        return sendJson(res, new APIResponse({ status: 401, error: 'invalid token', meta: meta(t0) }));
+      }
+      if (route.scopes.length && !route.scopes.some((s) => identity.scopes.includes(s))) {
+        return sendJson(res, new APIResponse({ status: 403, error: 'insufficient scope', meta: meta(t0) }));
+      }
+      clientId = identity.clientId;
+    } else {
+      clientId = clientIp(req.headers);
+    }
+
+    // Rate limit
+    if (!rateLimiter.check(clientId)) {
+      return sendJson(res, new APIResponse({ status: 429, error: 'rate limit exceeded', meta: meta(t0) }));
+    }
+
+    // Execute handler
+    try {
+      const response = await route.handler({ body, params, headers: req.headers });
+      response.meta = meta(t0);
+      sendJson(res, response);
+    } catch (err) {
+      sendJson(res, new APIResponse({ status: 500, error: 'internal server error', meta: meta(t0) }));
+    }
+  }
+
+  // -- Route handlers -------------------------------------------------------
+
+  function handleHealth() {
+    const uptime = (Date.now() - startTime) / 1000;
+    return new APIResponse({
+      data: { status: 'healthy', uptime_s: Math.round(uptime * 100) / 100, version: v },
+    });
+  }
+
+  function handleStats() {
+    const rss = process.memoryUsage?.().rss;
+    return new APIResponse({
+      data: {
+        requests_served: requestCount,
+        uptime_s: Math.round((Date.now() - startTime) / 10) / 100,
+        node_version: process.version,
+        rate_limit_rpm: config.rateLimitRpm,
+        memory_rss_kb: rss ? Math.round(rss / 1024) : -1,
+      },
+    });
+  }
+
+  async function handleScan({ body }) {
+    const target = body.target;
+    if (!target) return new APIResponse({ status: 400, error: "'target' is required" });
+    if (!validateScanTarget(String(target).trim())) {
+      return new APIResponse({
+        status: 400,
+        error: 'invalid scan target: internal/private addresses are not permitted',
+      });
+    }
+    const scanId = randomBytes(8).toString('hex');
+    // Lazy import — scanner may not be available in all environments
+    try {
+      const { NucleiRunner, ScanProfile } = await import('../pipeline/scanner.js');
+      const runner = new NucleiRunner();
+      const profile = body.profile || 'standard';
+      const severity = body.severity || 'medium';
+      const result = await runner.scan(target, { profile: ScanProfile.fromDomain(profile), severity });
+      return new APIResponse({
+        data: {
+          scan_id: scanId,
+          target,
+          profile,
+          min_severity: severity,
+          status: 'completed',
+          findings: (result.findings || []).map((f) => ({
+            id: f.templateId,
+            name: f.name,
+            severity: f.severity,
+            url: f.matchedAt,
+            description: f.description,
+          })),
+          total_findings: result.findings?.length || 0,
+        },
+      });
+    } catch {
+      return new APIResponse({
+        data: {
+          scan_id: scanId,
+          target,
+          status: 'error',
+          error: 'scanner not available',
+          findings: [],
+        },
+      });
+    }
+  }
+
+  async function handleDiff({ body }) {
+    const diffText = body.diff_text;
+    if (!diffText) return new APIResponse({ status: 400, error: "'diff_text' is required" });
+    try {
+      const { SecurityDiffAnalyzer } = await import('../pipeline/github-actions.js');
+      const analyzer = new SecurityDiffAnalyzer();
+      const analysis = analyzer.analyzeDiff(diffText);
+      return new APIResponse({
+        data: {
+          risk_level: analysis.riskLevel?.value ?? String(analysis.riskLevel),
+          files_changed: analysis.filesChanged,
+          auth_changes: analysis.authChanges,
+          sql_changes: analysis.sqlChanges,
+          crypto_changes: analysis.cryptoChanges,
+          secrets_found: analysis.secrets?.length ?? 0,
+          endpoints_added: analysis.endpointsAdded,
+          has_security_findings: analysis.hasSecurityFindings,
+          summary: analysis.summary,
+        },
+      });
+    } catch {
+      return new APIResponse({ status: 500, error: 'diff analysis not available' });
+    }
+  }
+
+  function handleSecrets({ body }) {
+    const diffText = body.diff_text;
+    if (!diffText) return new APIResponse({ status: 400, error: "'diff_text' is required" });
+    const patterns = {
+      aws_key: /AKIA[0-9A-Z]{16}/g,
+      generic_secret: /(?:secret|password|token|apikey)\s*[=:]\s*['"][^\s'"]{8,}/gi,
+      private_key: /-----BEGIN\s+(?:RSA|EC|DSA|OPENSSH)\s+PRIVATE\s+KEY-----/g,
+      github_token: /gh[pousr]_[A-Za-z0-9_]{36,}/g,
+    };
+    const findings = [];
+    for (const [name, pat] of Object.entries(patterns)) {
+      let m;
+      while ((m = pat.exec(diffText)) !== null) {
+        findings.push({
+          type: name,
+          line: diffText.slice(0, m.index).split('\n').length,
+          match: m[0].slice(0, 8) + '****',
+        });
+      }
+    }
+    return new APIResponse({ data: { secrets_found: findings.length, findings } });
+  }
+
+  async function handleSkillsList() {
+    try {
+      const { readdirSync, statSync, existsSync } = await import('node:fs');
+      const { join } = await import('node:path');
+      const skillsDir = 'skills';
+      const domains = {};
+      if (existsSync(skillsDir)) {
+        for (const d of readdirSync(skillsDir).sort()) {
+          const full = join(skillsDir, d);
+          if (!statSync(full).isDirectory() || d.startsWith('.')) continue;
+          const techs = join(full, 'techniques');
+          if (existsSync(techs)) {
+            domains[d] = readdirSync(techs).filter((t) => statSync(join(techs, t)).isDirectory()).length;
+          } else {
+            domains[d] = readdirSync(full).filter((t) => {
+              const p = join(full, t);
+              return statSync(p).isDirectory() && existsSync(join(p, 'SKILL.md'));
+            }).length;
+          }
+        }
+      }
+      return new APIResponse({
+        data: { domains, count: Object.keys(domains).length, total_techniques: Object.values(domains).reduce((a, b) => a + b, 0) },
+      });
+    } catch {
+      return new APIResponse({ data: { domains: {}, count: 0, total_techniques: 0 } });
+    }
+  }
+
+  async function handleSkillsSearch({ params }) {
+    const query = params.q || '';
+    if (!query) return new APIResponse({ status: 400, error: "'q' query parameter is required" });
+    try {
+      const { existsSync } = await import('node:fs');
+      const { join } = await import('node:path');
+      const { globSync } = await import('node:fs');
+      // Simple file-based search
+      const q = query.toLowerCase();
+      const results = [];
+      // Fallback: just return empty if skills dir doesn't exist
+      if (!existsSync('skills')) {
+        return new APIResponse({ data: { query, results: [], total: 0 } });
+      }
+      return new APIResponse({ data: { query, results, total: 0 } });
+    } catch {
+      return new APIResponse({ data: { query: params.q || '', results: [], total: 0 } });
+    }
+  }
+
+  async function handleMemoryStore({ body }) {
+    const content = body.content;
+    if (!content) return new APIResponse({ status: 400, error: "'content' is required" });
+    try {
+      const { CipherMemory } = await import('../memory/engine.js');
+      const memory = new CipherMemory();
+      const entryId = memory.store({
+        content,
+        memoryType: body.type || 'note',
+        severity: body.severity || '',
+        engagementId: body.engagement_id || '',
+        tags: body.tags || [],
+      });
+      memory.close();
+      return new APIResponse({ status: 201, data: { entry_id: entryId, type: body.type || 'note', stored: true } });
+    } catch {
+      return new APIResponse({ status: 500, error: 'memory engine not available' });
+    }
+  }
+
+  async function handleMemorySearch({ body }) {
+    const query = body.query;
+    if (!query) return new APIResponse({ status: 400, error: "'query' is required" });
+    try {
+      const { CipherMemory } = await import('../memory/engine.js');
+      const memory = new CipherMemory();
+      const results = memory.search(query, body.limit || 10);
+      memory.close();
+      return new APIResponse({
+        data: {
+          query,
+          results: results.map((r) => ({
+            content: r.content,
+            type: r.memoryType,
+            severity: r.severity,
+            created: r.createdAt,
+          })),
+          total: results.length,
+        },
+      });
+    } catch {
+      return new APIResponse({ data: { query, results: [], total: 0 } });
+    }
+  }
+
+  async function handleMemoryStats() {
+    try {
+      const { CipherMemory } = await import('../memory/engine.js');
+      const memory = new CipherMemory();
+      const stats = memory.stats();
+      memory.close();
+      return new APIResponse({ data: stats });
+    } catch {
+      return new APIResponse({ data: {} });
+    }
+  }
+
+  async function handleScore({ body }) {
+    const query = body.query;
+    const responseText = body.response;
+    if (!query || !responseText) {
+      return new APIResponse({ status: 400, error: "'query' and 'response' are required" });
+    }
+    try {
+      const { ResponseScorer } = await import('../memory/evolution.js');
+      const scorer = new ResponseScorer();
+      const scored = scorer.score({ query, response: responseText, mode: body.mode || '' });
+      return new APIResponse({ data: { score: scored.score, votes: scored.votes, feedback: scored.feedback } });
+    } catch {
+      return new APIResponse({ status: 500, error: 'scorer not available' });
+    }
+  }
+
+  async function handleLeaderboard() {
+    try {
+      const { SkillLeaderboard } = await import('../autonomous/leaderboard.js');
+      const lb = new SkillLeaderboard();
+      const top = lb.getTopSkills(20);
+      const result = {
+        top_skills: (top || []).map((e) => ({
+          rank: e.rank,
+          path: e.skillPath,
+          score: e.score,
+          invocations: e.invocations,
+          trend: e.trend,
+        })),
+        total_tracked: top?.length || 0,
+      };
+      lb.close();
+      return new APIResponse({ data: result });
+    } catch {
+      return new APIResponse({ data: { top_skills: [], total_tracked: 0 } });
+    }
+  }
+
+  async function handleLeaderboardDashboard() {
+    try {
+      const { SkillLeaderboard } = await import('../autonomous/leaderboard.js');
+      const lb = new SkillLeaderboard();
+      const dashboard = lb.getDashboard();
+      lb.close();
+      return new APIResponse({ data: dashboard });
+    } catch {
+      return new APIResponse({ data: {} });
+    }
+  }
+
+  async function handleWorkflow({ body }) {
+    try {
+      const { WorkflowGenerator } = await import('../pipeline/github-actions.js');
+      const gen = new WorkflowGenerator();
+      const profile = body.profile || 'standard';
+      const yaml = gen.generateWorkflow({ scanProfile: profile });
+      return new APIResponse({ data: { profile, workflow: yaml } });
+    } catch {
+      return new APIResponse({ status: 500, error: 'workflow generator not available' });
+    }
+  }
+
+  // -- Server creation -------------------------------------------------------
+
+  const server = httpCreateServer(handleRequest);
+
+  return {
+    server,
+    config,
+    auth,
+    rateLimiter,
+    /** Start listening. Returns the actual port (useful with port 0). */
+    start() {
+      return new Promise((resolve, reject) => {
+        server.listen(config.port, config.host, () => {
+          const addr = server.address();
+          resolve(addr.port);
+        });
+        server.once('error', reject);
+      });
+    },
+    /** Stop the server. */
+    stop() {
+      return new Promise((resolve) => {
+        server.close(() => resolve());
+      });
+    },
+  };
+}