evershield 0.0.0-stage → 0.1.0

package/dist/scan/artifact.d.ts

@@ -0,0 +1,18 @@
+import { type Finding, type ScanSummary } from "../index.ts";
+import { type Adapter } from "./adapters.ts";
+export interface ArtifactScanOptions {
+    /** Force an adapter instead of detecting one from the directory. */
+    adapter?: Adapter["name"];
+}
+export interface ArtifactScanResult extends ScanSummary {
+    layer: "artifact";
+    target: string;
+    adapter: Adapter["name"];
+    filesScanned: number;
+    /** Findings removed by config ignore rules; they are not in `findings`. */
+    ignored: number;
+}
+/** Worst first, then surest first, then by location so output is stable. */
+export declare function sortFindings(findings: Finding[]): Finding[];
+/** Layer 1: scan a directory of built files for what should not ship. */
+export declare function scanArtifact(target: string, options?: ArtifactScanOptions): Promise<ArtifactScanResult>;

package/dist/scan/artifact.js

@@ -0,0 +1,68 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { VERSION } from "../index.js";
+import { ARTIFACT_RULES } from "../rules/index.js";
+import { ADAPTERS, detectAdapter } from "./adapters.js";
+import { collectFiles } from "./files.js";
+const SEVERITY_RANK = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    info: 4,
+};
+const CONFIDENCE_RANK = {
+    high: 0,
+    medium: 1,
+    low: 2,
+};
+/** Worst first, then surest first, then by location so output is stable. */
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        const bySeverity = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+        if (bySeverity !== 0)
+            return bySeverity;
+        const byConfidence = CONFIDENCE_RANK[a.confidence] - CONFIDENCE_RANK[b.confidence];
+        if (byConfidence !== 0)
+            return byConfidence;
+        const aPath = a.evidence[0]?.kind === "file" ? a.evidence[0].path : "";
+        const bPath = b.evidence[0]?.kind === "file" ? b.evidence[0].path : "";
+        if (aPath !== bPath)
+            return aPath < bPath ? -1 : 1;
+        const aLine = a.evidence[0]?.kind === "file" ? (a.evidence[0].line ?? 0) : 0;
+        const bLine = b.evidence[0]?.kind === "file" ? (b.evidence[0].line ?? 0) : 0;
+        return aLine - bLine;
+    });
+}
+/** Layer 1: scan a directory of built files for what should not ship. */
+export async function scanArtifact(target, options = {}) {
+    const startedAt = new Date().toISOString();
+    const root = path.resolve(target);
+    const info = await stat(root).catch(() => null);
+    if (info === null || !info.isDirectory()) {
+        throw new Error(`not a directory: ${target}`);
+    }
+    const adapter = options.adapter ? ADAPTERS[options.adapter] : await detectAdapter(root);
+    const files = await collectFiles(root, adapter);
+    const context = {
+        adapter,
+        shippedPaths: new Set(files.map((file) => file.relativePath)),
+    };
+    const findings = [];
+    for (const file of files) {
+        for (const rule of ARTIFACT_RULES) {
+            findings.push(...rule.check(file, context));
+        }
+    }
+    return {
+        version: VERSION,
+        layer: "artifact",
+        target: root,
+        adapter: adapter.name,
+        filesScanned: files.length,
+        ignored: 0,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        findings: sortFindings(findings),
+    };
+}

package/dist/scan/files.d.ts

@@ -0,0 +1,16 @@
+import type { Adapter } from "./adapters.ts";
+/** One text file inside the artifact, as rules see it. */
+export interface ScannedFile {
+    /** Absolute path on disk. */
+    absolutePath: string;
+    /** Path relative to the scan root, with forward slashes. Used in reports. */
+    relativePath: string;
+    text: string;
+}
+export interface CollectOptions {
+    /** Files larger than this are skipped; bundles rarely exceed it and maps can be huge. */
+    maxBytes?: number;
+}
+export declare function toPosix(relative: string): string;
+/** Walk the root, keep what the adapter says the browser receives, read as UTF-8. */
+export declare function collectFiles(root: string, adapter: Adapter, options?: CollectOptions): Promise<ScannedFile[]>;

package/dist/scan/files.js

@@ -0,0 +1,41 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+const ALWAYS_SKIP_DIRS = new Set(["node_modules", ".git"]);
+/** Cheap binary check: a NUL byte in the first 8 KiB means not text. */
+function isProbablyBinary(buffer) {
+    const end = Math.min(buffer.length, 8192);
+    for (let i = 0; i < end; i += 1) {
+        if (buffer[i] === 0)
+            return true;
+    }
+    return false;
+}
+export function toPosix(relative) {
+    return relative.split(path.sep).join("/");
+}
+/** Walk the root, keep what the adapter says the browser receives, read as UTF-8. */
+export async function collectFiles(root, adapter, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const absolutePath = path.join(entry.parentPath, entry.name);
+        const relativePath = toPosix(path.relative(root, absolutePath));
+        if (relativePath.split("/").some((segment) => ALWAYS_SKIP_DIRS.has(segment)))
+            continue;
+        if (!adapter.includes(relativePath))
+            continue;
+        const info = await stat(absolutePath);
+        if (info.size === 0 || info.size > maxBytes)
+            continue;
+        const buffer = await readFile(absolutePath);
+        if (isProbablyBinary(buffer))
+            continue;
+        files.push({ absolutePath, relativePath, text: buffer.toString("utf8") });
+    }
+    files.sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1));
+    return files;
+}

package/dist/scan/text.d.ts

@@ -0,0 +1,18 @@
+/** Text helpers shared by rules: positions, redaction and entropy. */
+export interface LineColumn {
+    line: number;
+    column: number;
+}
+/** 1-based line and column for a character offset. */
+export declare function lineColumn(text: string, offset: number): LineColumn;
+/**
+ * Redact a matched value so reports never reproduce the secret they found.
+ * Keeps enough of each end to recognise the value in the source.
+ */
+export declare function redact(value: string, keep?: number): string;
+/** Shannon entropy in bits per character. ~4.5 is random base64, ~3 is prose. */
+export declare function shannonEntropy(value: string): number;
+/** Values humans type as stand-ins; never worth a finding on their own. */
+export declare function looksLikePlaceholder(value: string): boolean;
+/** Decode a JWT payload without verifying it. Returns null when it is not a JWT. */
+export declare function decodeJwtPayload(token: string): Record<string, unknown> | null;

package/dist/scan/text.js

@@ -0,0 +1,58 @@
+/** Text helpers shared by rules: positions, redaction and entropy. */
+/** 1-based line and column for a character offset. */
+export function lineColumn(text, offset) {
+    let line = 1;
+    let lastBreak = -1;
+    for (let i = 0; i < offset && i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10) {
+            line += 1;
+            lastBreak = i;
+        }
+    }
+    return { line, column: offset - lastBreak };
+}
+/**
+ * Redact a matched value so reports never reproduce the secret they found.
+ * Keeps enough of each end to recognise the value in the source.
+ */
+export function redact(value, keep = 4) {
+    if (value.length <= keep * 2 + 1)
+        return "*".repeat(value.length);
+    return `${value.slice(0, keep)}…${value.slice(-keep)} (${value.length} chars)`;
+}
+/** Shannon entropy in bits per character. ~4.5 is random base64, ~3 is prose. */
+export function shannonEntropy(value) {
+    if (value.length === 0)
+        return 0;
+    const counts = new Map();
+    for (const ch of value)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const p = count / value.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+const PLACEHOLDER = /^(x+|0+|\*+|your[_-]|changeme|placeholder|example|dummy|test|sample|<)/i;
+/** Values humans type as stand-ins; never worth a finding on their own. */
+export function looksLikePlaceholder(value) {
+    return PLACEHOLDER.test(value) || /^(.)\1+$/.test(value);
+}
+/** Decode a JWT payload without verifying it. Returns null when it is not a JWT. */
+export function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    const payload = parts[1];
+    if (payload === undefined)
+        return null;
+    try {
+        const json = Buffer.from(payload, "base64url").toString("utf8");
+        const parsed = JSON.parse(json);
+        return typeof parsed === "object" && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "evershield",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Shield everything, everywhere: find what your web app exposes to the browser before attackers do",
+  "license": "MIT",
+  "author": "Lee Dongwook (@inviy)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inviy/evershield.git"
+  },
+  "homepage": "https://github.com/inviy/evershield#readme",
+  "bugs": {
+    "url": "https://github.com/inviy/evershield/issues"
+  },
+  "keywords": [
+    "security",
+    "exposure",
+    "client-side",
+    "bundle",
+    "sourcemap",
+    "secrets",
+    "authorization",
+    "paywall",
+    "static-analysis",
+    "sarif",
+    "ci",
+    "devsecops"
+  ],
+  "type": "module",
+  "bin": {
+    "evershield": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "packageManager": "pnpm@10.28.0",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-strip-types --test \"src/**/*.test.ts\"",
+    "check": "pnpm typecheck && pnpm test && pnpm build",
+    "prepublishOnly": "pnpm check"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.0"
+  }
+}