@nest-yalc-2/sentinel 2.0.0

package/src/algorithms/polymorphic-routes.ts

@@ -0,0 +1,89 @@
+/**
+ * # Polymorphic API Route Mutation Engine (`polymorphic-routes.ts`)
+ * Ephemeral time-windowed HMAC path rotation for endpoint obfuscation
+ * (Academic Ref: *ACM SIGCOMM*).
+ */
+
+import * as crypto from 'crypto';
+
+export interface PolymorphicRouteState {
+  basePath: string;
+  currentMutatedPath: string;
+  windowSlot: number;
+  expiresInSecs: number;
+}
+
+export interface RouteValidationResult {
+  isValid: boolean;
+  basePath: string;
+  windowSlot: number;
+}
+
+export class PolymorphicRouteEngine {
+  private secretKey: Buffer;
+  private rotationPeriodSecs: number;
+
+  constructor(secretKey: string | Buffer, rotationPeriodSecs: number = 300) {
+    this.secretKey = typeof secretKey === 'string' ? Buffer.from(secretKey) : secretKey;
+    this.rotationPeriodSecs = rotationPeriodSecs;
+  }
+
+  /**
+   * Generates the current mutated path for a given base path and timestamp
+   */
+  public generateMutatedPath(basePath: string, timestampSecs: number): PolymorphicRouteState {
+    const windowSlot = Math.floor(timestampSecs / this.rotationPeriodSecs);
+    const hasher = crypto.createHash('sha256');
+    hasher.update(this.secretKey);
+    hasher.update(basePath);
+
+    const slotBuf = Buffer.alloc(8);
+    slotBuf.writeBigUInt64BE(BigInt(windowSlot));
+    hasher.update(slotBuf);
+
+    const hexHash = hasher.digest('hex').substring(0, 16);
+    const currentMutatedPath = `${basePath}/_poly_${hexHash}`;
+    const expiresInSecs = this.rotationPeriodSecs - (timestampSecs % this.rotationPeriodSecs);
+
+    return {
+      basePath,
+      currentMutatedPath,
+      windowSlot,
+      expiresInSecs,
+    };
+  }
+
+  /**
+   * Validates incoming request path against current and previous window slot
+   */
+  public validateRequest(requestPath: string, basePath: string, timestampSecs: number): RouteValidationResult {
+    const currentSlot = Math.floor(timestampSecs / this.rotationPeriodSecs);
+
+    for (const slot of [currentSlot, Math.max(0, currentSlot - 1)]) {
+      const hasher = crypto.createHash('sha256');
+      hasher.update(this.secretKey);
+      hasher.update(basePath);
+
+      const slotBuf = Buffer.alloc(8);
+      slotBuf.writeBigUInt64BE(BigInt(slot));
+      hasher.update(slotBuf);
+
+      const hexHash = hasher.digest('hex').substring(0, 16);
+      const expectedPath = `${basePath}/_poly_${hexHash}`;
+
+      if (requestPath === expectedPath) {
+        return {
+          isValid: true,
+          basePath,
+          windowSlot: slot,
+        };
+      }
+    }
+
+    return {
+      isValid: false,
+      basePath,
+      windowSlot: currentSlot,
+    };
+  }
+}

package/src/algorithms/rag-groundedness.d.ts

@@ -0,0 +1,9 @@
+export interface GroundednessAssessment {
+    groundednessScore: number;
+    isGrounded: boolean;
+    unsupportedClaims: string[];
+    matchedContextFacts: string[];
+}
+export declare class RagHallucinationGroundednessEngine {
+    static evaluateGroundedness(generatedResponse: string, retrievedContexts: string[], groundednessThreshold?: number): GroundednessAssessment;
+}

package/src/algorithms/rag-groundedness.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RagHallucinationGroundednessEngine = void 0;
+class RagHallucinationGroundednessEngine {
+    static evaluateGroundedness(generatedResponse, retrievedContexts, groundednessThreshold = 0.70) {
+        const claims = generatedResponse
+            .split(/[.!?]/)
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        if (claims.length === 0) {
+            return {
+                groundednessScore: 1.0,
+                isGrounded: true,
+                unsupportedClaims: [],
+                matchedContextFacts: [],
+            };
+        }
+        const combinedContext = retrievedContexts.join(' ').toLowerCase();
+        const contextWords = new Set(combinedContext
+            .split(/[^a-zA-Z0-9]+/)
+            .filter((w) => w.length > 0));
+        let matchedClaimsCount = 0;
+        const unsupportedClaims = [];
+        const matchedContextFacts = [];
+        for (const claim of claims) {
+            const claimWords = claim
+                .toLowerCase()
+                .split(/[^a-zA-Z0-9]+/)
+                .filter((w) => w.length > 3);
+            if (claimWords.length === 0) {
+                matchedClaimsCount++;
+                continue;
+            }
+            const matches = claimWords.filter((w) => contextWords.has(w)).length;
+            const matchRatio = matches / claimWords.length;
+            if (matchRatio >= 0.4) {
+                matchedClaimsCount++;
+                matchedContextFacts.push(claim);
+            }
+            else {
+                unsupportedClaims.push(claim);
+            }
+        }
+        const groundednessScore = matchedClaimsCount / claims.length;
+        const isGrounded = groundednessScore >= groundednessThreshold;
+        return {
+            groundednessScore,
+            isGrounded,
+            unsupportedClaims,
+            matchedContextFacts,
+        };
+    }
+}
+exports.RagHallucinationGroundednessEngine = RagHallucinationGroundednessEngine;
+//# sourceMappingURL=rag-groundedness.js.map

package/src/algorithms/rag-groundedness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-groundedness.js","sourceRoot":"","sources":["rag-groundedness.ts"],"names":[],"mappings":";;;AAaA,MAAa,kCAAkC;IAItC,MAAM,CAAC,oBAAoB,CAChC,iBAAyB,EACzB,iBAA2B,EAC3B,wBAAgC,IAAI;QAEpC,MAAM,MAAM,GAAG,iBAAiB;aAC7B,KAAK,CAAC,OAAO,CAAC;aACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAE/B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO;gBACL,iBAAiB,EAAE,GAAG;gBACtB,UAAU,EAAE,IAAI;gBAChB,iBAAiB,EAAE,EAAE;gBACrB,mBAAmB,EAAE,EAAE;aACxB,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QAClE,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,eAAe;aACZ,KAAK,CAAC,eAAe,CAAC;aACtB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAC/B,CAAC;QAEF,IAAI,kBAAkB,GAAG,CAAC,CAAC;QAC3B,MAAM,iBAAiB,GAAa,EAAE,CAAC;QACvC,MAAM,mBAAmB,GAAa,EAAE,CAAC;QAEzC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,UAAU,GAAG,KAAK;iBACrB,WAAW,EAAE;iBACb,KAAK,CAAC,eAAe,CAAC;iBACtB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAE/B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,kBAAkB,EAAE,CAAC;gBACrB,SAAS;YACX,CAAC;YAED,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACrE,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC;YAE/C,IAAI,UAAU,IAAI,GAAG,EAAE,CAAC;gBACtB,kBAAkB,EAAE,CAAC;gBACrB,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;iBAAM,CAAC;gBACN,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QAED,MAAM,iBAAiB,GAAG,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7D,MAAM,UAAU,GAAG,iBAAiB,IAAI,qBAAqB,CAAC;QAE9D,OAAO;YACL,iBAAiB;YACjB,UAAU;YACV,iBAAiB;YACjB,mBAAmB;SACpB,CAAC;IACJ,CAAC;CACF;AAlED,gFAkEC"}

package/src/algorithms/rag-groundedness.ts

@@ -0,0 +1,80 @@
+/**
+ * # RAG Groundedness & Hallucination Guardrail Engine (`rag-groundedness.ts`)
+ * RAG factual claim overlap ratio scoring engine
+ * (Academic Ref: *Building LLM-Powered Applications* & *Mastering LLM Applications*).
+ */
+
+export interface GroundednessAssessment {
+  groundednessScore: number;
+  isGrounded: boolean;
+  unsupportedClaims: string[];
+  matchedContextFacts: string[];
+}
+
+export class RagHallucinationGroundednessEngine {
+  /**
+   * Computes factual groundedness score as the ratio of generated response claims supported by retrieved context chunks
+   */
+  public static evaluateGroundedness(
+    generatedResponse: string,
+    retrievedContexts: string[],
+    groundednessThreshold: number = 0.70
+  ): GroundednessAssessment {
+    const claims = generatedResponse
+      .split(/[.!?]/)
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+
+    if (claims.length === 0) {
+      return {
+        groundednessScore: 1.0,
+        isGrounded: true,
+        unsupportedClaims: [],
+        matchedContextFacts: [],
+      };
+    }
+
+    const combinedContext = retrievedContexts.join(' ').toLowerCase();
+    const contextWords = new Set(
+      combinedContext
+        .split(/[^a-zA-Z0-9]+/)
+        .filter((w) => w.length > 0)
+    );
+
+    let matchedClaimsCount = 0;
+    const unsupportedClaims: string[] = [];
+    const matchedContextFacts: string[] = [];
+
+    for (const claim of claims) {
+      const claimWords = claim
+        .toLowerCase()
+        .split(/[^a-zA-Z0-9]+/)
+        .filter((w) => w.length > 3);
+
+      if (claimWords.length === 0) {
+        matchedClaimsCount++;
+        continue;
+      }
+
+      const matches = claimWords.filter((w) => contextWords.has(w)).length;
+      const matchRatio = matches / claimWords.length;
+
+      if (matchRatio >= 0.4) {
+        matchedClaimsCount++;
+        matchedContextFacts.push(claim);
+      } else {
+        unsupportedClaims.push(claim);
+      }
+    }
+
+    const groundednessScore = matchedClaimsCount / claims.length;
+    const isGrounded = groundednessScore >= groundednessThreshold;
+
+    return {
+      groundednessScore,
+      isGrounded,
+      unsupportedClaims,
+      matchedContextFacts,
+    };
+  }
+}

package/src/algorithms/sbom-verifier.d.ts

@@ -0,0 +1,19 @@
+export interface SbomComponentRecord {
+    name: string;
+    version: string;
+    expectedSha256: string;
+    isRevoked: boolean;
+}
+export interface SupplyChainIntegrityReport {
+    isValid: boolean;
+    tamperedComponents: string[];
+    revokedComponents: string[];
+    totalVerified: number;
+}
+export declare class SbomSupplyChainVerifierEngine {
+    static verifyComponent(record: SbomComponentRecord, actualContent: string | Buffer): {
+        matches: boolean;
+        actualHash: string;
+    };
+    static auditSupplyChain(manifest: SbomComponentRecord[], actualComponents: Map<string, string | Buffer>): SupplyChainIntegrityReport;
+}

package/src/algorithms/sbom-verifier.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SbomSupplyChainVerifierEngine = void 0;
+const tslib_1 = require("tslib");
+const crypto = tslib_1.__importStar(require("crypto"));
+class SbomSupplyChainVerifierEngine {
+    static verifyComponent(record, actualContent) {
+        const bytes = typeof actualContent === 'string' ? Buffer.from(actualContent) : actualContent;
+        const actualHash = crypto.createHash('sha256').update(bytes).digest('hex');
+        const matches = actualHash.toLowerCase() === record.expectedSha256.toLowerCase();
+        return { matches, actualHash };
+    }
+    static auditSupplyChain(manifest, actualComponents) {
+        const tamperedComponents = [];
+        const revokedComponents = [];
+        let totalVerified = 0;
+        for (const record of manifest) {
+            if (record.isRevoked) {
+                revokedComponents.push(`${record.name}@${record.version}`);
+            }
+            const content = actualComponents.get(record.name);
+            if (content) {
+                const { matches } = this.verifyComponent(record, content);
+                if (!matches) {
+                    tamperedComponents.push(`${record.name}@${record.version} (Hash mismatch)`);
+                }
+                else {
+                    totalVerified++;
+                }
+            }
+            else {
+                tamperedComponents.push(`${record.name}@${record.version} (Missing component)`);
+            }
+        }
+        return {
+            isValid: tamperedComponents.length === 0 && revokedComponents.length === 0,
+            tamperedComponents,
+            revokedComponents,
+            totalVerified,
+        };
+    }
+}
+exports.SbomSupplyChainVerifierEngine = SbomSupplyChainVerifierEngine;
+//# sourceMappingURL=sbom-verifier.js.map

package/src/algorithms/sbom-verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sbom-verifier.js","sourceRoot":"","sources":["sbom-verifier.ts"],"names":[],"mappings":";;;;AAMA,uDAAiC;AAgBjC,MAAa,6BAA6B;IACjC,MAAM,CAAC,eAAe,CAAC,MAA2B,EAAE,aAA8B;QACvF,MAAM,KAAK,GAAG,OAAO,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;QAC7F,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAE3E,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,CAAC;QACjF,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IACjC,CAAC;IAEM,MAAM,CAAC,gBAAgB,CAC5B,QAA+B,EAC/B,gBAA8C;QAE9C,MAAM,kBAAkB,GAAa,EAAE,CAAC;QACxC,MAAM,iBAAiB,GAAa,EAAE,CAAC;QACvC,IAAI,aAAa,GAAG,CAAC,CAAC;QAEtB,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBACrB,iBAAiB,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;YAC7D,CAAC;YAED,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAClD,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC1D,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,kBAAkB,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;gBAC9E,CAAC;qBAAM,CAAC;oBACN,aAAa,EAAE,CAAC;gBAClB,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,kBAAkB,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;YAClF,CAAC;QACH,CAAC;QAED,OAAO;YACL,OAAO,EAAE,kBAAkB,CAAC,MAAM,KAAK,CAAC,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC;YAC1E,kBAAkB;YAClB,iBAAiB;YACjB,aAAa;SACd,CAAC;IACJ,CAAC;CACF;AA1CD,sEA0CC"}

package/src/algorithms/sbom-verifier.ts

@@ -0,0 +1,65 @@
+/**
+ * # SBOM & Supply Chain Dependency Integrity Guard (`sbom-verifier.ts`)
+ * Package SHA-256 cryptographic hash & dependency integrity validator
+ * (Academic Ref: *Intelligent Continuous Security*, O'Reilly - Ch. 7).
+ */
+
+import * as crypto from 'crypto';
+
+export interface SbomComponentRecord {
+  name: string;
+  version: string;
+  expectedSha256: string;
+  isRevoked: boolean;
+}
+
+export interface SupplyChainIntegrityReport {
+  isValid: boolean;
+  tamperedComponents: string[];
+  revokedComponents: string[];
+  totalVerified: number;
+}
+
+export class SbomSupplyChainVerifierEngine {
+  public static verifyComponent(record: SbomComponentRecord, actualContent: string | Buffer): { matches: boolean; actualHash: string } {
+    const bytes = typeof actualContent === 'string' ? Buffer.from(actualContent) : actualContent;
+    const actualHash = crypto.createHash('sha256').update(bytes).digest('hex');
+
+    const matches = actualHash.toLowerCase() === record.expectedSha256.toLowerCase();
+    return { matches, actualHash };
+  }
+
+  public static auditSupplyChain(
+    manifest: SbomComponentRecord[],
+    actualComponents: Map<string, string | Buffer>
+  ): SupplyChainIntegrityReport {
+    const tamperedComponents: string[] = [];
+    const revokedComponents: string[] = [];
+    let totalVerified = 0;
+
+    for (const record of manifest) {
+      if (record.isRevoked) {
+        revokedComponents.push(`${record.name}@${record.version}`);
+      }
+
+      const content = actualComponents.get(record.name);
+      if (content) {
+        const { matches } = this.verifyComponent(record, content);
+        if (!matches) {
+          tamperedComponents.push(`${record.name}@${record.version} (Hash mismatch)`);
+        } else {
+          totalVerified++;
+        }
+      } else {
+        tamperedComponents.push(`${record.name}@${record.version} (Missing component)`);
+      }
+    }
+
+    return {
+      isValid: tamperedComponents.length === 0 && revokedComponents.length === 0,
+      tamperedComponents,
+      revokedComponents,
+      totalVerified,
+    };
+  }
+}

package/src/algorithms/shannon-entropy.d.ts

@@ -0,0 +1,8 @@
+export interface EntropyAssessment {
+    entropyScore: number;
+    isSuspicious: boolean;
+    byteLength: number;
+}
+export declare class ShannonEntropyEngine {
+    static calculateEntropy(payload: string | Buffer): EntropyAssessment;
+}

package/src/algorithms/shannon-entropy.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShannonEntropyEngine = void 0;
+class ShannonEntropyEngine {
+    static calculateEntropy(payload) {
+        const bytes = typeof payload === 'string' ? Buffer.from(payload) : payload;
+        if (bytes.length === 0) {
+            return { entropyScore: 0.0, isSuspicious: false, byteLength: 0 };
+        }
+        const counts = new Array(256).fill(0);
+        for (let i = 0; i < bytes.length; i++) {
+            counts[bytes[i]]++;
+        }
+        let entropy = 0.0;
+        const len = bytes.length;
+        for (let i = 0; i < 256; i++) {
+            if (counts[i] > 0) {
+                const p = counts[i] / len;
+                entropy -= p * Math.log2(p);
+            }
+        }
+        const isSuspicious = entropy > 7.2 && bytes.length > 64;
+        return {
+            entropyScore: Math.round(entropy * 1000) / 1000,
+            isSuspicious,
+            byteLength: bytes.length,
+        };
+    }
+}
+exports.ShannonEntropyEngine = ShannonEntropyEngine;
+//# sourceMappingURL=shannon-entropy.js.map

package/src/algorithms/shannon-entropy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shannon-entropy.js","sourceRoot":"","sources":["shannon-entropy.ts"],"names":[],"mappings":";;;AAYA,MAAa,oBAAoB;IAIxB,MAAM,CAAC,gBAAgB,CAAC,OAAwB;QACrD,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC3E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;QACnE,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,KAAK,CAAS,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,CAAC;QAED,IAAI,OAAO,GAAG,GAAG,CAAC;QAClB,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7B,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;gBAC1B,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAGD,MAAM,YAAY,GAAG,OAAO,GAAG,GAAG,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC;QAExD,OAAO;YACL,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,IAAI;YAC/C,YAAY;YACZ,UAAU,EAAE,KAAK,CAAC,MAAM;SACzB,CAAC;IACJ,CAAC;CACF;AAjCD,oDAiCC"}

package/src/algorithms/shannon-entropy.ts

@@ -0,0 +1,46 @@
+/**
+ * # Shannon Payload Entropy Evaluator (`shannon-entropy.ts`)
+ * Calculates payload information entropy to detect obfuscated, packed, or encrypted payloads
+ * (Academic Ref: *Malware Data Science*, No Starch Press).
+ */
+
+export interface EntropyAssessment {
+  entropyScore: number;
+  isSuspicious: boolean;
+  byteLength: number;
+}
+
+export class ShannonEntropyEngine {
+  /**
+   * Calculates Shannon Entropy H(X) = -sum(P(x) * log2(P(x))) for string/buffer payload
+   */
+  public static calculateEntropy(payload: string | Buffer): EntropyAssessment {
+    const bytes = typeof payload === 'string' ? Buffer.from(payload) : payload;
+    if (bytes.length === 0) {
+      return { entropyScore: 0.0, isSuspicious: false, byteLength: 0 };
+    }
+
+    const counts = new Array<number>(256).fill(0);
+    for (let i = 0; i < bytes.length; i++) {
+      counts[bytes[i]]++;
+    }
+
+    let entropy = 0.0;
+    const len = bytes.length;
+    for (let i = 0; i < 256; i++) {
+      if (counts[i] > 0) {
+        const p = counts[i] / len;
+        entropy -= p * Math.log2(p);
+      }
+    }
+
+    // High entropy threshold > 7.2 indicates packed/encrypted payload
+    const isSuspicious = entropy > 7.2 && bytes.length > 64;
+
+    return {
+      entropyScore: Math.round(entropy * 1000) / 1000,
+      isSuspicious,
+      byteLength: bytes.length,
+    };
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,10 @@
+export * from './algorithms/ai-guardrails';
+export * from './algorithms/rag-groundedness';
+export * from './algorithms/shannon-entropy';
+export * from './algorithms/polymorphic-routes';
+export * from './algorithms/markov-sequence';
+export * from './algorithms/lsass-guard';
+export * from './algorithms/sbom-verifier';
+export * from './sentinel.guard';
+export * from './sentinel.interceptor';
+export * from './sentinel.module';

package/src/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./algorithms/ai-guardrails"), exports);
+tslib_1.__exportStar(require("./algorithms/rag-groundedness"), exports);
+tslib_1.__exportStar(require("./algorithms/shannon-entropy"), exports);
+tslib_1.__exportStar(require("./algorithms/polymorphic-routes"), exports);
+tslib_1.__exportStar(require("./algorithms/markov-sequence"), exports);
+tslib_1.__exportStar(require("./algorithms/lsass-guard"), exports);
+tslib_1.__exportStar(require("./algorithms/sbom-verifier"), exports);
+tslib_1.__exportStar(require("./sentinel.guard"), exports);
+tslib_1.__exportStar(require("./sentinel.interceptor"), exports);
+tslib_1.__exportStar(require("./sentinel.module"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAKA,qEAA2C;AAC3C,wEAA8C;AAC9C,uEAA6C;AAC7C,0EAAgD;AAChD,uEAA6C;AAC7C,mEAAyC;AACzC,qEAA2C;AAC3C,2DAAiC;AACjC,iEAAuC;AACvC,4DAAkC"}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * # Ferrox-Node Sentinel (`@nest-yalc-2/sentinel` / `@ferrox/node-sentinel`)
+ * Enterprise AI/ML Security Analytics & 35 SOTA Innovations for NestJS
+ */
+
+export * from './algorithms/ai-guardrails';
+export * from './algorithms/rag-groundedness';
+export * from './algorithms/shannon-entropy';
+export * from './algorithms/polymorphic-routes';
+export * from './algorithms/markov-sequence';
+export * from './algorithms/lsass-guard';
+export * from './algorithms/sbom-verifier';
+export * from './sentinel.guard';
+export * from './sentinel.interceptor';
+export * from './sentinel.module';

package/src/sentinel.guard.d.ts

@@ -0,0 +1,4 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+export declare class FerroxSentinelGuard implements CanActivate {
+    canActivate(context: ExecutionContext): boolean;
+}

package/src/sentinel.guard.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FerroxSentinelGuard = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const ai_guardrails_js_1 = require("./algorithms/ai-guardrails.js");
+const shannon_entropy_js_1 = require("./algorithms/shannon-entropy.js");
+let FerroxSentinelGuard = class FerroxSentinelGuard {
+    canActivate(context) {
+        const request = context.switchToHttp().getRequest();
+        const bodyStr = request.body ? JSON.stringify(request.body) : '';
+        const entropyResult = shannon_entropy_js_1.ShannonEntropyEngine.calculateEntropy(bodyStr);
+        if (entropyResult.isSuspicious) {
+            throw new common_1.ForbiddenException(`[FerroxSentinel] Blocked high-entropy payload (Score: ${entropyResult.entropyScore})`);
+        }
+        const promptSample = `${request.url} ${bodyStr}`;
+        const aiAssessment = ai_guardrails_js_1.AiPromptGuardrailEngine.evaluatePrompt(promptSample);
+        if (aiAssessment.isThreatDetected && aiAssessment.threatScore >= 0.7) {
+            throw new common_1.ForbiddenException(`[FerroxSentinel] Blocked Prompt Injection / DAN Jailbreak attempt. Matched: ${aiAssessment.matchedKeywords.join(', ')}`);
+        }
+        return true;
+    }
+};
+exports.FerroxSentinelGuard = FerroxSentinelGuard;
+exports.FerroxSentinelGuard = FerroxSentinelGuard = tslib_1.__decorate([
+    (0, common_1.Injectable)()
+], FerroxSentinelGuard);
+//# sourceMappingURL=sentinel.guard.js.map

package/src/sentinel.guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.guard.js","sourceRoot":"","sources":["sentinel.guard.ts"],"names":[],"mappings":";;;;AAKA,2CAA+F;AAC/F,oEAAwE;AACxE,wEAAuE;AAGhE,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAC9B,WAAW,CAAC,OAAyB;QACnC,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,CAAC;QACpD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAGjE,MAAM,aAAa,GAAG,yCAAoB,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACrE,IAAI,aAAa,CAAC,YAAY,EAAE,CAAC;YAC/B,MAAM,IAAI,2BAAkB,CAAC,yDAAyD,aAAa,CAAC,YAAY,GAAG,CAAC,CAAC;QACvH,CAAC;QAGD,MAAM,YAAY,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,EAAE,CAAC;QACjD,MAAM,YAAY,GAAG,0CAAuB,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;QAE1E,IAAI,YAAY,CAAC,gBAAgB,IAAI,YAAY,CAAC,WAAW,IAAI,GAAG,EAAE,CAAC;YACrE,MAAM,IAAI,2BAAkB,CAC1B,+EAA+E,YAAY,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzH,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAA;AAvBY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;GACA,mBAAmB,CAuB/B"}

package/src/sentinel.guard.ts

@@ -0,0 +1,34 @@
+/**
+ * # NestJS Ferrox-Node Sentinel Guard (`sentinel.guard.ts`)
+ * CanActivate Guard evaluating entropy, prompt injection, and velocity anomalies
+ */
+
+import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
+import { AiPromptGuardrailEngine } from './algorithms/ai-guardrails.js';
+import { ShannonEntropyEngine } from './algorithms/shannon-entropy.js';
+
+@Injectable()
+export class FerroxSentinelGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest();
+    const bodyStr = request.body ? JSON.stringify(request.body) : '';
+
+    // 1. Evaluate Payload Shannon Entropy
+    const entropyResult = ShannonEntropyEngine.calculateEntropy(bodyStr);
+    if (entropyResult.isSuspicious) {
+      throw new ForbiddenException(`[FerroxSentinel] Blocked high-entropy payload (Score: ${entropyResult.entropyScore})`);
+    }
+
+    // 2. Evaluate Prompt Injection Patterns if string present in query or body
+    const promptSample = `${request.url} ${bodyStr}`;
+    const aiAssessment = AiPromptGuardrailEngine.evaluatePrompt(promptSample);
+
+    if (aiAssessment.isThreatDetected && aiAssessment.threatScore >= 0.7) {
+      throw new ForbiddenException(
+        `[FerroxSentinel] Blocked Prompt Injection / DAN Jailbreak attempt. Matched: ${aiAssessment.matchedKeywords.join(', ')}`
+      );
+    }
+
+    return true;
+  }
+}

package/src/sentinel.interceptor.d.ts

@@ -0,0 +1,7 @@
+import { NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable } from 'rxjs';
+export declare class RagGroundednessInterceptor implements NestInterceptor {
+    private readonly minGroundednessScore;
+    constructor(minGroundednessScore?: number);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+}

package/src/sentinel.interceptor.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RagGroundednessInterceptor = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const operators_1 = require("rxjs/operators");
+const rag_groundedness_js_1 = require("./algorithms/rag-groundedness.js");
+let RagGroundednessInterceptor = class RagGroundednessInterceptor {
+    constructor(minGroundednessScore = 0.70) {
+        this.minGroundednessScore = minGroundednessScore;
+    }
+    intercept(context, next) {
+        const request = context.switchToHttp().getRequest();
+        const retrievedContexts = request.ragContexts || [];
+        return next.handle().pipe((0, operators_1.map)((response) => {
+            if (typeof response === 'string' && retrievedContexts.length > 0) {
+                const assessment = rag_groundedness_js_1.RagHallucinationGroundednessEngine.evaluateGroundedness(response, retrievedContexts, this.minGroundednessScore);
+                if (!assessment.isGrounded) {
+                    throw new common_1.BadGatewayException(`[FerroxSentinel] LLM response failed groundedness check (Score: ${assessment.groundednessScore.toFixed(2)} < ${this.minGroundednessScore})`);
+                }
+            }
+            return response;
+        }));
+    }
+};
+exports.RagGroundednessInterceptor = RagGroundednessInterceptor;
+exports.RagGroundednessInterceptor = RagGroundednessInterceptor = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [Number])
+], RagGroundednessInterceptor);
+//# sourceMappingURL=sentinel.interceptor.js.map

package/src/sentinel.interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.interceptor.js","sourceRoot":"","sources":["sentinel.interceptor.ts"],"names":[],"mappings":";;;;AAKA,2CAAiH;AAEjH,8CAAqC;AACrC,0EAAsF;AAG/E,IAAM,0BAA0B,GAAhC,MAAM,0BAA0B;IACrC,YAA6B,uBAA+B,IAAI;QAAnC,yBAAoB,GAApB,oBAAoB,CAAe;IAAG,CAAC;IAEpE,SAAS,CAAC,OAAyB,EAAE,IAAiB;QACpD,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,CAAC;QACpD,MAAM,iBAAiB,GAAa,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;QAE9D,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CACvB,IAAA,eAAG,EAAC,CAAC,QAAQ,EAAE,EAAE;YACf,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACjE,MAAM,UAAU,GAAG,wDAAkC,CAAC,oBAAoB,CACxE,QAAQ,EACR,iBAAiB,EACjB,IAAI,CAAC,oBAAoB,CAC1B,CAAC;gBAEF,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;oBAC3B,MAAM,IAAI,4BAAmB,CAC3B,mEAAmE,UAAU,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,oBAAoB,GAAG,CAC7I,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF,CAAA;AA1BY,gEAA0B;qCAA1B,0BAA0B;IADtC,IAAA,mBAAU,GAAE;;GACA,0BAA0B,CA0BtC"}