@j3r3mcdev/scoring 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build project
+        run: npm run build

package/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build project
+        run: npm run build
+
+      - name: Publish package
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 j3r3mcdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @j3r3mcdev/auth-service – Scoring & Reporting Engine
+
+Moteur de scoring, corrélation d'événements et génération de rapports (JSON, Markdown, HTML) destiné aux middlewares de sécurité, WAF applicatifs et pipelines DevSecOps.
+
+Ce module fournit :
+
+- un moteur de scoring normalisé
+- un système de corrélation d'événements
+- un format unifié pour les findings
+- trois reporters professionnels (JSON, Markdown, HTML)
+- une factory pour sélectionner dynamiquement un reporter
+- des utilitaires de rendu sécurisés (Markdown/HTML)
+- une suite de tests complète (74 tests)
+
+---
+
+## Installation
+
+```bash
+npm install @j3r3mcdev/auth-service
+```
+
+## Fonctionnalités principales
+
+### Scoring
+
+Score normalisé entre 0 et 100
+
+Conversion automatique en labels (Low, Medium, High, Critical)
+
+Informations enrichies via scoreInfo() (label, couleur, niveau de risque)
+
+Tri automatique des findings par sévérité
+
+### Corrélation
+
+Construction de chaînes d'événements (CorrelationChain)
+
+Calcul de confiance (0–1)
+
+Résumés lisibles via chainSummary()
+
+Tri automatique des chaînes par confiance
+
+### Reporting
+
+JSONReporter : export structuré pour CI/CD, ingestion ou stockage
+
+MarkdownReporter : rapport lisible pour développeurs, compatible GitHub/GitLab/VSCode
+
+HTMLReporter : rapport visuel, thème sombre, sections claires
+
+ReporterFactory : sélection dynamique du reporter (json, markdown, html)
+
+Génération de fichiers avec nom, MIME type et contenu final
+
+### Sécurité
+
+Échappement Markdown (escapeMarkdown)
+
+Échappement HTML (escapeHtml)
+
+Rendu sécurisé des tableaux, listes, sections et paragraphes
+
+Protection contre l’injection dans les rapports
+
+### Utilitaires
+
+renderTable, renderList, renderSection (Markdown)
+
+renderHtmlTable, renderHtmlList, renderHtmlParagraph (HTML)
+
+formatIso() pour les dates
+
+sortFindingsBySeverity() et sortChains() pour un rendu cohérent
+
+### Utilisation
+
+Génération d’un rapport
+
+```ts
+import { createReporter } from "@j3r3mcdev/auth-service";
+
+const reporter = createReporter("markdown");
+
+const findings = [
+  {
+    id: "f1",
+    vulnerability: "xss",
+    severity: "high",
+    score: 80,
+    details: "Reflected XSS detected",
+    evidence: ["<script>alert(1)</script>"],
+    chains: [],
+  },
+];
+
+const chains = [];
+
+const report = reporter.generate(findings, chains);
+
+console.log(report.filename);
+console.log(report.mime);
+console.log(report.content);
+```
+
+## API
+
+createReporter(format)
+
+```ts
+const reporter = createReporter("json" | "markdown" | "html");
+```
+
+Retourne une instance de :
+
+JSONReporter
+MarkdownReporter
+HTMLReporter
+
+ReporterOutput
+
+```ts
+interface ReporterOutput {
+  filename: string;
+  content: string;
+  mime: string;
+}
+```
+
+### Reporters
+
+JSONReporter
+Format structuré
+Idéal pour CI/CD, ingestion, stockage
+
+### MarkdownReporter
+
+Rapport lisible
+Compatible GitHub/GitLab/VSCode
+
+### HTMLReporter
+
+Rapport visuel
+Thème sombre
+Sections claires et structurées
+
+## Tests
+
+La suite de tests couvre :
+
+scoring
+corrélation
+reporters
+factory
+échappements Markdown/HTML
+rapports vides
+intégration complète
+
+Exécution :
+
+```bash
+npm run test
+Résultat attendu :
+```
+
+```bash
+Test Suites: 24 passed, 24 total
+Tests: 74 passed, 74 total
+Structure du projet
+```
+
+Licence
+
+MIT

package/jest.config.js

@@ -0,0 +1,11 @@
+const { createDefaultPreset } = require("ts-jest");
+
+const tsJestTransformCfg = createDefaultPreset().transform;
+
+/** @type {import("jest").Config} **/
+module.exports = {
+  testEnvironment: "node",
+  transform: {
+    ...tsJestTransformCfg,
+  },
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@j3r3mcdev/scoring",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "directories": {
+    "test": "tests"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "clean": "rimraf dist"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.60.1",
+    "@typescript-eslint/parser": "^8.60.1",
+    "eslint": "^10.4.1",
+    "jest": "^30.4.2",
+    "rimraf": "^6.1.3",
+    "ts-jest": "^29.4.11",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3"
+  }
+}

package/src/core/__tests__/scoring-context.test.ts

@@ -0,0 +1,47 @@
+import { ContextBuilder } from "../scoring-context";
+
+describe("ScoringContext", () => {
+  test("builds an empty context", () => {
+    const ctx = new ContextBuilder().build();
+
+    expect(ctx.events).toEqual([]);
+    expect(ctx.chains).toEqual([]);
+    expect(ctx.metadata).toEqual({});
+  });
+
+  test("adds events", () => {
+    const event = {
+      id: "1",
+      source: "waf" as const,
+      timestamp: Date.now(),
+      metadata: {},
+    };
+
+    const ctx = new ContextBuilder().addEvent(event).build();
+
+    expect(ctx.events).toHaveLength(1);
+    expect(ctx.events[0]).toBe(event);
+  });
+
+  test("adds chains", () => {
+    const chain = {
+      id: "c1",
+      type: "ssrf" as const,
+      events: [],
+      confidence: 0.9,
+    };
+
+    const ctx = new ContextBuilder().addChain(chain).build();
+
+    expect(ctx.chains).toHaveLength(1);
+    expect(ctx.chains[0]).toBe(chain);
+  });
+
+  test("sets metadata", () => {
+    const ctx = new ContextBuilder()
+      .setMetadata("target", "https://example.com")
+      .build();
+
+    expect(ctx.metadata?.target).toBe("https://example.com");
+  });
+});

package/src/core/__tests__/scoring-engine.test.ts

@@ -0,0 +1,110 @@
+import { ScoringEngine } from "../scoring-engine";
+import { RuleRegistry } from "../../rules/rule-registry";
+import { ContextBuilder } from "../scoring-context";
+
+describe("ScoringEngine", () => {
+  beforeEach(() => RuleRegistry.clear());
+
+  test("returns empty result when no rules apply", () => {
+    const engine = new ScoringEngine();
+    const ctx = new ContextBuilder().build();
+
+    const result = engine.run(ctx);
+
+    expect(result.score).toBe(0);
+    expect(result.findings).toHaveLength(0);
+  });
+
+  test("executes a rule and returns findings", () => {
+    const fakeRule = {
+      id: "r1",
+      name: "Fake",
+      applies: () => true,
+      execute: () => [
+        {
+          ruleId: "r1",
+          vulnerability: "xss" as const,
+          score: 0.8,
+          severity: "high" as const,
+          details: "test",
+        },
+      ],
+    };
+
+    RuleRegistry.register(fakeRule);
+
+    const engine = new ScoringEngine();
+    const ctx = new ContextBuilder().build();
+
+    const result = engine.run(ctx);
+
+    expect(result.findings).toHaveLength(1);
+    expect(result.findings[0].vulnerability).toBe("xss");
+    expect(result.score).toBe(80);
+    expect(result.severity).toBe("high");
+  });
+
+  test("merges multiple findings of same vulnerability", () => {
+    const rule = {
+      id: "r1",
+      name: "MergeTest",
+      applies: () => true,
+      execute: () => [
+        {
+          ruleId: "r1",
+          vulnerability: "sqli" as const,
+          score: 0.4,
+          severity: "medium" as const,
+        },
+        {
+          ruleId: "r1",
+          vulnerability: "sqli" as const,
+          score: 0.9,
+          severity: "critical" as const,
+        },
+      ],
+    };
+
+    RuleRegistry.register(rule);
+
+    const engine = new ScoringEngine();
+    const ctx = new ContextBuilder().build();
+
+    const result = engine.run(ctx);
+
+    expect(result.findings).toHaveLength(1);
+    expect(result.findings[0].score).toBe(0.9);
+    expect(result.findings[0].severity).toBe("critical");
+  });
+
+  test("computes global severity as highest", () => {
+    const rule = {
+      id: "r1",
+      name: "MergeTest",
+      applies: () => true,
+      execute: () => [
+        {
+          ruleId: "r1",
+          vulnerability: "sqli" as const,
+          score: 0.4,
+          severity: "medium" as const,
+        },
+        {
+          ruleId: "r1",
+          vulnerability: "sqli" as const,
+          score: 0.9,
+          severity: "critical" as const,
+        },
+      ],
+    };
+
+    RuleRegistry.register(rule);
+
+    const engine = new ScoringEngine();
+    const ctx = new ContextBuilder().build();
+
+    const result = engine.run(ctx);
+
+    expect(result.severity).toBe("critical");
+  });
+});

package/src/core/__tests__/scoring-result.test.ts

@@ -0,0 +1,14 @@
+import { createEmptyResult } from "../scoring-result";
+
+describe("createEmptyResult", () => {
+  test("returns a valid empty scoring result", () => {
+    const result = createEmptyResult();
+
+    expect(result.score).toBe(0);
+    expect(result.severity).toBe("low");
+    expect(result.findings).toEqual([]);
+    expect(result.chains).toEqual([]);
+    expect(result.metadata).toEqual({});
+    expect(typeof result.timestamp).toBe("number");
+  });
+});

package/src/core/index.ts

@@ -0,0 +1,8 @@
+// ─────────────────────────────────────────────────────────────
+//  CORE — Scoring complet
+// ─────────────────────────────────────────────────────────────
+
+export * from "./scoring-types";
+export * from "./scoring-context";
+export * from "./scoring-result";
+export * from "./scoring-engine";

package/src/core/scoring-context.ts

@@ -0,0 +1,80 @@
+import {
+  NormalizedEvent,
+  CorrelationChain,
+  ScoringContext,
+} from "./scoring-types";
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  SCORING CONTEXT — Version avancée
+ *  Construit un contexte propre, stable et extensible.
+ * ─────────────────────────────────────────────────────────────
+ */
+
+export class ContextBuilder {
+  private events: NormalizedEvent[] = [];
+  private chains: CorrelationChain[] = [];
+  private metadata: Record<string, any> = {};
+
+  /**
+   * Ajoute un événement normalisé au contexte.
+   */
+  addEvent(event: NormalizedEvent): this {
+    this.events.push(event);
+    return this;
+  }
+
+  /**
+   * Ajoute plusieurs événements d'un coup.
+   */
+  addEvents(events: NormalizedEvent[]): this {
+    this.events.push(...events);
+    return this;
+  }
+
+  /**
+   * Ajoute une chaîne de corrélation.
+   */
+  addChain(chain: CorrelationChain): this {
+    this.chains.push(chain);
+    return this;
+  }
+
+  /**
+   * Ajoute plusieurs chaînes.
+   */
+  addChains(chains: CorrelationChain[]): this {
+    this.chains.push(...chains);
+    return this;
+  }
+
+  /**
+   * Ajoute des métadonnées arbitraires (ex: URL cible, IP, user-agent…)
+   */
+  setMetadata(key: string, value: any): this {
+    this.metadata[key] = value;
+    return this;
+  }
+
+  /**
+   * Construit le contexte final.
+   */
+  build(): ScoringContext {
+    return {
+      events: [...this.events],
+      chains: [...this.chains],
+      metadata: { ...this.metadata },
+    };
+  }
+}
+
+/**
+ * Helper simple pour créer un contexte vide.
+ */
+export function createEmptyContext(): ScoringContext {
+  return {
+    events: [],
+    chains: [],
+    metadata: {},
+  };
+}

package/src/core/scoring-engine.ts

@@ -0,0 +1,126 @@
+import {
+  RuleFinding,
+  Finding,
+  Severity,
+  ScoringContext,
+  ScoringResult,
+} from "./scoring-types";
+
+import { RuleRegistry } from "../rules/rule-registry";
+import { createEmptyResult } from "./scoring-result";
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  SCORING ENGINE — Version avancée
+ * ─────────────────────────────────────────────────────────────
+ */
+export class ScoringEngine {
+  run(context: ScoringContext): ScoringResult {
+    const rules = RuleRegistry.getAll();
+    const rawFindings: RuleFinding[] = [];
+
+    // 1. Exécution des règles
+    for (const rule of rules) {
+      if (rule.applies(context)) {
+        const results = rule.execute(context);
+        rawFindings.push(...results);
+      }
+    }
+
+    // 2. Aucun finding → résultat vide propre
+    if (rawFindings.length === 0) {
+      return {
+        ...createEmptyResult(),
+        chains: context.chains,
+        metadata: context.metadata,
+      };
+    }
+
+    // 3. Fusion des findings
+    const consolidated = this.consolidateFindings(rawFindings, context);
+
+    // 4. Score global
+    const score = this.computeGlobalScore(consolidated);
+
+    // 5. Sévérité globale
+    const severity = this.computeGlobalSeverity(consolidated);
+
+    // 6. Résultat final
+    return {
+      score,
+      severity,
+      findings: consolidated,
+      chains: context.chains,
+      timestamp: Date.now(),
+      metadata: context.metadata,
+    };
+  }
+
+  private consolidateFindings(
+    raw: RuleFinding[],
+    context: ScoringContext,
+  ): Finding[] {
+    const map = new Map<string, Finding>();
+
+    for (const f of raw) {
+      if (!map.has(f.vulnerability)) {
+        map.set(f.vulnerability, {
+          id: f.vulnerability,
+          vulnerability: f.vulnerability,
+          severity: f.severity,
+          score: f.score,
+          evidence: [],
+          chains: [],
+          details: f.details,
+        });
+      } else {
+        const existing = map.get(f.vulnerability)!;
+
+        existing.score = Math.max(existing.score, f.score);
+        existing.severity = this.maxSeverity(existing.severity, f.severity);
+
+        if (f.details) {
+          existing.details = (existing.details ?? "") + "\n" + f.details;
+        }
+      }
+    }
+
+    // Ajout des events + chains filtrées
+    for (const finding of map.values()) {
+      finding.evidence = context.events;
+      finding.chains = context.chains.filter(
+        (c) => c.type === finding.vulnerability,
+      );
+    }
+
+    return [...map.values()];
+  }
+
+  private computeGlobalScore(findings: Finding[]): number {
+    const total = findings.reduce((acc, f) => acc + f.score, 0);
+    return Math.round((total / findings.length) * 100);
+  }
+
+  private computeGlobalSeverity(findings: Finding[]): Severity {
+    return findings
+      .map((f) => f.severity)
+      .sort((a, b) => this.severityWeight(b) - this.severityWeight(a))[0];
+  }
+
+  private maxSeverity(a: Severity, b: Severity): Severity {
+    return this.severityWeight(a) >= this.severityWeight(b) ? a : b;
+  }
+
+  private severityWeight(s: Severity): number {
+    switch (s) {
+      case "low":
+        return 1;
+      case "medium":
+        return 2;
+      case "high":
+        return 3;
+      case "critical":
+        return 4;
+    }
+  }
+}