@birdapi/velinstyle 1.2.1 → 1.3.0

package/core/security/checks/fs.js

@@ -0,0 +1,92 @@
+/**
+ * Shared FS helpers for Security Engine rules.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+
+const SKIP = new Set(['node_modules', '.git', 'dist', 'vendor', 'coverage', '.velin']);
+
+/**
+ * @param {string} root
+ * @param {(name: string, abs: string) => boolean} [filter]
+ * @param {number} [max=400]
+ */
+export function walkFiles(root, filter, max = 400) {
+  const out = [];
+  const walk = (dir) => {
+    if (out.length >= max) return;
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (SKIP.has(name)) continue;
+      const abs = join(dir, name);
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) walk(abs);
+      else if (!filter || filter(name, abs)) out.push(abs);
+      if (out.length >= max) return;
+    }
+  };
+  if (existsSync(root)) walk(root);
+  return out;
+}
+
+export function readText(path) {
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+export function readJson(path) {
+  const t = readText(path);
+  if (!t) return null;
+  try {
+    return JSON.parse(t);
+  } catch {
+    return null;
+  }
+}
+
+export function rel(root, abs) {
+  return relative(root, abs).replace(/\\/g, '/');
+}
+
+export function fileExists(path) {
+  return existsSync(path);
+}
+
+/**
+ * Lightweight YAML-ish peek for GitHub Actions (no full parser).
+ * @param {string} text
+ */
+export function workflowHints(text) {
+  const lines = text.split(/\r?\n/);
+  const uses = [];
+  let hasPullRequestTarget = /pull_request_target\s*:/.test(text);
+  let hasPermissions = /^\s*permissions\s*:/m.test(text);
+  let hasIdToken = /id-token\s*:\s*write/.test(text);
+  let mentionsNpmToken = /NPM_TOKEN|NODE_AUTH_TOKEN/.test(text);
+  for (const line of lines) {
+    const m = line.match(/^\s*-\s*uses:\s*(.+)\s*$/);
+    if (m) uses.push(m[1].trim().replace(/['"]/g, ''));
+  }
+  return { uses, hasPullRequestTarget, hasPermissions, hasIdToken, mentionsNpmToken };
+}
+
+/** Pin check: owner/action@sha40 vs @v1 */
+export function isShaPinned(usesRef) {
+  const at = usesRef.lastIndexOf('@');
+  if (at < 0) return false;
+  const ref = usesRef.slice(at + 1);
+  return /^[0-9a-f]{40}$/i.test(ref);
+}

package/core/security/detect.js

@@ -0,0 +1,35 @@
+/**
+ * Detect repo vs consumer vs both for Security Engine.
+ */
+import { join } from 'path';
+import { fileExists, readJson } from './checks/fs.js';
+
+/**
+ * @param {string} root
+ * @returns {'repo'|'consumer'|'both'}
+ */
+export function detectSecurityMode(root) {
+  const pkg = readJson(join(root, 'package.json'));
+  const isFramework =
+    pkg?.name === '@birdapi/velinstyle'
+    || fileExists(join(root, '.github', 'workflows', 'publish-npm.yml'))
+    || (fileExists(join(root, 'SECURITY.md')) && fileExists(join(root, 'cli', 'index.js')));
+
+  const hasVelinDep =
+    Boolean(pkg?.dependencies?.['@birdapi/velinstyle'] || pkg?.devDependencies?.['@birdapi/velinstyle'])
+    || fileExists(join(root, 'vendor', 'velinstyle'))
+    || fileExists(join(root, 'vendor', 'velinstyle.min.css'));
+
+  const consumerMarkers =
+    fileExists(join(root, 'artisan'))
+    || fileExists(join(root, 'composer.json'))
+    || hasVelinDep
+    || Boolean(pkg && pkg.name !== '@birdapi/velinstyle');
+
+  if (isFramework && consumerMarkers && hasVelinDep && pkg?.name !== '@birdapi/velinstyle') {
+    return 'both';
+  }
+  if (isFramework) return 'repo';
+  if (consumerMarkers || pkg) return 'consumer';
+  return 'consumer';
+}

package/core/security/engine.js

@@ -0,0 +1,116 @@
+/**
+ * Velin Security Engine — run registered rules.
+ */
+import { selectSecurityRules } from './registry.js';
+import { loadBuiltinSecurityRules } from './rules/index.js';
+import { detectSecurityMode } from './detect.js';
+import { scoreFindings } from './score/score.js';
+import { computeDependencyHealth } from './score/dependency-health.js';
+import { computeReleaseHealth } from './score/release-health.js';
+import { loadTimeline, touchTimeline } from './timeline/timeline.js';
+import { resolve } from 'path';
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.root]
+ * @param {string} [opts.mode] — doctor|repo|consumer|ci|publish|deps|secrets|scan|audit
+ * @param {string[]} [opts.categories]
+ * @param {boolean} [opts.updateTimeline=true]
+ * @param {boolean} [opts.includeReleaseHealth]
+ * @param {boolean} [opts.includeDependencyHealth]
+ */
+export async function runSecurityEngine(opts = {}) {
+  loadBuiltinSecurityRules();
+  const root = resolve(opts.root || '.');
+  let mode = opts.mode || 'doctor';
+
+  let detected = detectSecurityMode(root);
+  if (mode === 'doctor') {
+    mode = detected === 'both' ? 'audit' : detected;
+  }
+
+  const categoryMap = {
+    deps: ['deps', 'malware'],
+    secrets: ['secrets'],
+    ci: ['ci'],
+    publish: ['publish', 'repo', 'secrets', 'deps', 'malware'],
+    scan: ['consumer', 'secrets', 'repo', 'malware'],
+    repo: ['repo', 'ci', 'secrets', 'deps', 'publish', 'malware'],
+    consumer: ['consumer', 'secrets', 'deps', 'malware'],
+    audit: null,
+  };
+
+  const categories = opts.categories || categoryMap[mode] || null;
+  const rules = selectSecurityRules({
+    mode: mode === 'audit' ? 'audit' : mode,
+    categories: categories || undefined,
+  });
+
+  const ctx = { root, mode, categories: categories || undefined, meta: { detected } };
+  /** @type {import('./registry.js').SecurityFinding[]} */
+  const findings = [];
+
+  for (const rule of rules) {
+    try {
+      const out = await rule.run(ctx);
+      for (const f of out || []) {
+        findings.push({
+          category: rule.category,
+          ...f,
+          ruleId: f.ruleId || rule.id,
+        });
+      }
+    } catch (err) {
+      findings.push({
+        ruleId: rule.id,
+        category: rule.category,
+        severity: 'warning',
+        message: `Rule failed: ${err?.message || err}`,
+      });
+    }
+  }
+
+  const scored = scoreFindings(findings);
+  const includeDep = opts.includeDependencyHealth !== false;
+  const includeRel =
+    opts.includeReleaseHealth === true
+    || mode === 'publish'
+    || (mode === 'audit' && detected === 'repo');
+
+  const dependencyHealth = includeDep ? computeDependencyHealth(root, findings) : null;
+  const releaseHealth = includeRel ? computeReleaseHealth(root, findings) : null;
+
+  const touched = [];
+  if (mode === 'ci' || categories?.includes('ci')) touched.push('ci');
+  if (mode === 'deps' || categories?.includes('deps')) touched.push('dependencies');
+  if (mode === 'secrets' || categories?.includes('secrets')) touched.push('secrets');
+  if (mode === 'publish') touched.push('publish');
+  if (mode === 'repo' || detected === 'repo') touched.push('repository');
+  if (mode === 'consumer' || detected === 'consumer') touched.push('consumer');
+  if (mode === 'audit' || mode === 'scan') touched.push('audit');
+
+  let timeline = loadTimeline(root);
+  if (opts.updateTimeline !== false && touched.length) {
+    timeline = touchTimeline(root, touched);
+  }
+
+  return {
+    ...scored,
+    root,
+    mode,
+    detected,
+    rulesRun: rules.length,
+    dependencyHealth,
+    releaseHealth,
+    timeline,
+    ok: scored.overallGate !== 'fail',
+  };
+}
+
+export function createSecurityEngine(options = {}) {
+  loadBuiltinSecurityRules();
+  return {
+    detect: (root) => detectSecurityMode(resolve(root || options.root || '.')),
+    run: (opts = {}) => runSecurityEngine({ ...options, ...opts }),
+  };
+}

package/core/security/index.js

@@ -0,0 +1,18 @@
+/**
+ * Velin Security Engine — public API.
+ */
+export {
+  registerSecurityRule,
+  clearSecurityRules,
+  listSecurityRules,
+  getSecurityRule,
+  selectSecurityRules,
+} from './registry.js';
+export { detectSecurityMode } from './detect.js';
+export { runSecurityEngine, createSecurityEngine } from './engine.js';
+export { scoreFindings, gateLabel } from './score/score.js';
+export { computeDependencyHealth } from './score/dependency-health.js';
+export { computeReleaseHealth } from './score/release-health.js';
+export { loadTimeline, touchTimeline, timelineRows, timelinePath } from './timeline/timeline.js';
+export { toExperiencePayload, toMarkdownReport } from './report/report.js';
+export { loadBuiltinSecurityRules } from './rules/index.js';

package/core/security/registry.js

@@ -0,0 +1,85 @@
+/**
+ * Velin Security Engine — rule registry (Studio-/CLI-ready).
+ */
+
+/** @typedef {'ci'|'secrets'|'deps'|'publish'|'repo'|'consumer'|'malware'} SecurityCategory */
+/** @typedef {'info'|'warning'|'error'} SecuritySeverity */
+/** @typedef {'repo'|'consumer'|'ci'|'publish'|'deps'|'secrets'|'scan'|'audit'} SecurityMode */
+
+/**
+ * @typedef {object} SecurityFinding
+ * @property {string} ruleId
+ * @property {SecuritySeverity} severity
+ * @property {string} message
+ * @property {string} [path]
+ * @property {string} [fix]
+ * @property {string} [code]
+ */
+
+/**
+ * @typedef {object} SecurityRule
+ * @property {string} id
+ * @property {SecurityCategory} category
+ * @property {SecuritySeverity} severity
+ * @property {SecurityMode[]} [modes]
+ * @property {string} [title]
+ * @property {string} [description]
+ * @property {(ctx: SecurityContext) => Promise<SecurityFinding[]>|SecurityFinding[]} run
+ */
+
+/**
+ * @typedef {object} SecurityContext
+ * @property {string} root
+ * @property {SecurityMode} mode
+ * @property {string[]} [categories]
+ * @property {import('fs').PathLike} [fs]
+ * @property {Record<string, unknown>} [meta]
+ */
+
+/** @type {Map<string, SecurityRule>} */
+const RULES = new Map();
+
+/**
+ * @param {SecurityRule} rule
+ */
+export function registerSecurityRule(rule) {
+  if (!rule?.id || typeof rule.run !== 'function') {
+    throw new Error('registerSecurityRule: id and run() required');
+  }
+  RULES.set(rule.id, {
+    severity: 'warning',
+    modes: ['repo', 'consumer', 'audit'],
+    title: rule.id,
+    description: '',
+    ...rule,
+  });
+  return rule.id;
+}
+
+export function clearSecurityRules() {
+  RULES.clear();
+}
+
+export function listSecurityRules() {
+  return [...RULES.values()];
+}
+
+export function getSecurityRule(id) {
+  return RULES.get(id) || null;
+}
+
+/**
+ * @param {{ mode?: SecurityMode, categories?: string[] }} [filter]
+ */
+export function selectSecurityRules(filter = {}) {
+  const mode = filter.mode;
+  const cats = filter.categories?.length ? new Set(filter.categories) : null;
+  return listSecurityRules().filter((r) => {
+    if (cats && !cats.has(r.category)) return false;
+    if (!mode) return true;
+    const modes = r.modes || [];
+    if (mode === 'audit' || mode === 'doctor') return true;
+    if (mode === 'scan') return modes.includes('scan') || modes.includes('consumer') || modes.includes('secrets');
+    return modes.includes(mode) || modes.includes('audit');
+  });
+}

package/core/security/report/report.js

@@ -0,0 +1,113 @@
+/**
+ * Security report builders (JSON / Markdown / Experience payload).
+ */
+import { gateLabel } from '../score/score.js';
+import { timelineRows } from '../timeline/timeline.js';
+
+/**
+ * @param {object} result — engine result
+ */
+export function toExperiencePayload(result) {
+  const { securityScore, scores, overall, dependencyHealth, releaseHealth, timeline, mode, findings } = result;
+  const items = [
+    { label: 'Security Score', value: String(securityScore) },
+    { label: 'Overall', value: overall },
+    { label: 'Mode', value: mode },
+  ];
+  if (dependencyHealth) {
+    items.push({ label: 'Dependency Health', value: `${dependencyHealth.score} %` });
+  }
+  if (releaseHealth) {
+    items.push({ label: 'Release Health', value: releaseHealth.status });
+  }
+
+  const tableRows = Object.entries(scores || {}).map(([k, v]) => [
+    v.label || k,
+    gateLabel(v.gate),
+    v.na ? 'n/a' : String(v.score),
+  ]);
+
+  const notifications = [];
+  if (overall === 'BLOCKED') {
+    notifications.push({ tone: 'danger', message: 'Security gate BLOCKED — fix errors before publish' });
+  } else if (overall === 'READY_WITH_WARNINGS') {
+    notifications.push({ tone: 'warning', message: 'Ready with warnings — review WARNING findings' });
+  } else {
+    notifications.push({ tone: 'success', message: 'Security Overall READY' });
+  }
+
+  const tl = timelineRows(timeline || { entries: {} });
+  if (tl.length) {
+    notifications.push({
+      tone: 'info',
+      message: `Timeline: ${tl.map((r) => `${r.title} ${r.date}`).join(' · ')}`,
+    });
+  }
+
+  return {
+    message: `Security Score ${securityScore} / 100 · ${overall}`,
+    items,
+    table: {
+      columns: ['Area', 'Gate', 'Score'],
+      rows: tableRows,
+    },
+    score: { value: securityScore, label: 'Security' },
+    findings: (findings || []).slice(0, 40).map((f) => ({
+      severity: f.severity,
+      message: f.message,
+      path: f.path,
+      rule: f.ruleId,
+    })),
+    notifications,
+    meta: {
+      dependencyHealth,
+      releaseHealth,
+      timeline: tl,
+      mode,
+    },
+  };
+}
+
+/**
+ * @param {object} result
+ */
+export function toMarkdownReport(result) {
+  const lines = [
+    '# Velin Security Report',
+    '',
+    `**Score:** ${result.securityScore} / 100`,
+    `**Overall:** ${result.overall}`,
+    `**Mode:** ${result.mode}`,
+    '',
+    '## Categories',
+    '',
+  ];
+  for (const [k, v] of Object.entries(result.scores || {})) {
+    const scorePart = v.na ? 'n/a' : String(v.score);
+    const note = v.note ? ` — ${v.note}` : '';
+    lines.push(`- **${v.label || k}:** ${gateLabel(v.gate)} (${scorePart})${note}`);
+  }
+  if (result.dependencyHealth) {
+    lines.push('', '## Dependency Health', '');
+    const dh = result.dependencyHealth;
+    lines.push(
+      `Score ${dh.score}% · deprecated ${dh.deprecated} · no-lockfile ${dh.noLockfile ?? 0} · outdated (heuristic) ${dh.outdated} · critical ${dh.critical}`,
+    );
+    if (dh.note) lines.push(`_${dh.note}_`);
+  }
+  if (result.releaseHealth) {
+    lines.push('', '## Release Health', '');
+    lines.push(`**${result.releaseHealth.status}** (score ${result.releaseHealth.score})`);
+  }
+  const tl = timelineRows(result.timeline || { entries: {} });
+  if (tl.length) {
+    lines.push('', '## Security Timeline', '');
+    for (const r of tl) lines.push(`- ${r.title}: ${r.date}`);
+  }
+  lines.push('', '## Findings', '');
+  for (const f of result.findings || []) {
+    lines.push(`- **${f.severity}** \`${f.ruleId}\`: ${f.message}${f.path ? ` (${f.path})` : ''}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/core/security/rules/ci/index.js

@@ -0,0 +1,146 @@
+import { registerSecurityRule } from '../../registry.js';
+import { fileExists, readText, walkFiles, rel, workflowHints, isShaPinned } from '../../checks/fs.js';
+import { join } from 'path';
+
+export function registerCiRules() {
+  registerSecurityRule({
+    id: 'workflow.present',
+    category: 'ci',
+    severity: 'info',
+    modes: ['repo', 'ci', 'audit'],
+    title: 'Workflows directory',
+    run(ctx) {
+      if (fileExists(join(ctx.root, '.github', 'workflows'))) return [];
+      return [{
+        ruleId: 'workflow.present',
+        category: 'ci',
+        severity: 'info',
+        message: 'No .github/workflows directory',
+        path: '.github/workflows',
+      }];
+    },
+  });
+
+  registerSecurityRule({
+    id: 'workflow.sha-pinning',
+    category: 'ci',
+    severity: 'warning',
+    modes: ['repo', 'ci', 'audit', 'publish'],
+    title: 'SHA pinning',
+    description: 'GitHub Actions should pin actions by commit SHA.',
+    run(ctx) {
+      const dir = join(ctx.root, '.github', 'workflows');
+      if (!fileExists(dir)) return [];
+      const files = walkFiles(dir, (n) => /\.ya?ml$/i.test(n), 40);
+      const findings = [];
+      for (const abs of files) {
+        const hints = workflowHints(readText(abs) || '');
+        for (const u of hints.uses) {
+          if (!isShaPinned(u) && /@(v?\d|main|master|latest)/i.test(u)) {
+            findings.push({
+              ruleId: 'workflow.sha-pinning',
+              category: 'ci',
+              severity: 'warning',
+              message: `Action not SHA-pinned: ${u}`,
+              path: rel(ctx.root, abs),
+              fix: 'Pin uses: owner/action@<40-char-sha>',
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  });
+
+  registerSecurityRule({
+    id: 'workflow.pull-request-target',
+    category: 'ci',
+    severity: 'error',
+    modes: ['repo', 'ci', 'audit'],
+    title: 'pull_request_target',
+    run(ctx) {
+      const dir = join(ctx.root, '.github', 'workflows');
+      if (!fileExists(dir)) return [];
+      const files = walkFiles(dir, (n) => /\.ya?ml$/i.test(n), 40);
+      const findings = [];
+      for (const abs of files) {
+        const hints = workflowHints(readText(abs) || '');
+        if (hints.hasPullRequestTarget) {
+          findings.push({
+            ruleId: 'workflow.pull-request-target',
+            category: 'ci',
+            severity: 'error',
+            message: 'Workflow uses pull_request_target — high risk if checkout PR code',
+            path: rel(ctx.root, abs),
+            fix: 'Avoid untrusted code execution on pull_request_target',
+          });
+        }
+      }
+      return findings;
+    },
+  });
+
+  registerSecurityRule({
+    id: 'workflow.permissions',
+    category: 'ci',
+    severity: 'warning',
+    modes: ['repo', 'ci', 'audit'],
+    title: 'Explicit permissions',
+    run(ctx) {
+      const dir = join(ctx.root, '.github', 'workflows');
+      if (!fileExists(dir)) return [];
+      const files = walkFiles(dir, (n) => /\.ya?ml$/i.test(n), 40);
+      const findings = [];
+      for (const abs of files) {
+        const hints = workflowHints(readText(abs) || '');
+        if (!hints.hasPermissions) {
+          findings.push({
+            ruleId: 'workflow.permissions',
+            category: 'ci',
+            severity: 'warning',
+            message: 'Workflow missing top-level permissions: block',
+            path: rel(ctx.root, abs),
+            fix: 'Set least-privilege permissions',
+          });
+        }
+      }
+      return findings;
+    },
+  });
+
+  registerSecurityRule({
+    id: 'workflow.publish-token',
+    category: 'ci',
+    severity: 'info',
+    modes: ['repo', 'ci', 'audit', 'publish'],
+    title: 'Publish token / EOTP',
+    run(ctx) {
+      const pub = join(ctx.root, '.github', 'workflows', 'publish-npm.yml');
+      if (!fileExists(pub)) return [];
+      const text = readText(pub) || '';
+      const findings = [];
+      if (/NPM_TOKEN|NODE_AUTH_TOKEN/.test(text)) {
+        findings.push({
+          ruleId: 'workflow.publish-token',
+          category: 'ci',
+          severity: 'info',
+          message: 'Publish workflow uses NPM_TOKEN — use npm Automation token (no OTP/EOTP)',
+          path: '.github/workflows/publish-npm.yml',
+          fix: 'Granular Automation token with publish access; avoid classic 2FA tokens in CI',
+        });
+      }
+      const hints = workflowHints(text);
+      if (!hints.hasIdToken) {
+        findings.push({
+          ruleId: 'workflow.publish-provenance',
+          category: 'ci',
+          severity: 'warning',
+          message: 'Publish workflow may lack id-token: write for npm provenance',
+          path: '.github/workflows/publish-npm.yml',
+          fix: 'Add permissions.id-token: write for provenance',
+        });
+      }
+      return findings;
+    },
+  });
+}