ohdear-npm-audit 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# ohdear-npm-audit
+
+[Oh Dear Application Health](https://ohdear.app/docs/features/application-health-monitoring) check for critical npm vulnerabilities.
+
+Designed for serverless platforms (Vercel, Netlify...) where you can't run `npm audit` at runtime. Instead, a dependency manifest is generated at build time and checked against the npm advisory API on each health check request.
+
+> **Disclaimer:** This package is not affiliated with or endorsed by [Oh Dear](https://ohdear.app/). It is a community-built integration that implements the [Oh Dear application health check protocol](https://ohdear.app/docs/features/application-health-monitoring).
+
+## Install
+
+```bash
+npm install ohdear-npm-audit
+```
+
+## Setup
+
+### 1. Generate the dependency manifest at build time
+
+**Option A — CLI (works with any framework)**
+
+```json
+"build": "ohdear-deps-manifest --output src/app/api/health/deps-manifest.json && next build"
+```
+
+**Option B — Next.js config wrapper**
+
+```js
+// next.config.mjs
+import { withOhDearHealth } from "ohdear-npm-audit/next";
+
+export default withOhDearHealth({
+  // your Next.js config
+});
+```
+
+The wrapper generates the manifest automatically when the config is evaluated (before the build starts). You can customize the output path:
+
+```js
+withOhDearHealth(nextConfig, {
+  output: "src/app/api/health/deps-manifest.json", // default
+});
+```
+
+### 2. Create the health check route
+
+```ts
+// src/app/api/health/route.ts (Next.js App Router)
+import { createHealthHandler } from "ohdear-npm-audit";
+import manifest from "./deps-manifest.json" with { type: "json" };
+
+export const GET = createHealthHandler(manifest);
+```
+
+### 3. Set the environment variable
+
+```
+OHDEAR_HEALTH_SECRET=your-secret-here
+```
+
+This must match the secret configured in Oh Dear for your application health check.
+
+### 4. Add to .gitignore
+
+```gitignore
+**/deps-manifest.json
+```
+
+## How it works
+
+1. **Build time** — The CLI or Next.js wrapper runs `pnpm list` / `npm ls` to extract all production dependencies (including transitive) and writes them to a JSON manifest
+2. **Runtime** — On each GET request, the handler verifies the Oh Dear secret header, POSTs the manifest to the [npm bulk advisory API](https://docs.npmjs.com/about-audit-reports), filters for critical severity, and returns the result in the [Oh Dear health check format](https://ohdear.app/docs/features/application-health-monitoring)
+
+### Response format
+
+```json
+{
+  "finishedAt": 1708300000,
+  "checkResults": [
+    {
+      "name": "npm_vulnerabilities",
+      "label": "NPM Critical Vulnerabilities",
+      "status": "ok",
+      "notificationMessage": "No critical npm vulnerabilities found.",
+      "shortSummary": "0 critical",
+      "meta": {}
+    }
+  ]
+}
+```
+
+`status` is `"ok"` when there are no critical vulnerabilities, `"warning"` when the npm advisory API is unreachable, `"failed"` otherwise.
+
+## API
+
+### `createHealthHandler(manifest, options?)`
+
+Returns a `(request: Request) => Promise<Response>` handler compatible with any framework that uses the Web Request/Response API (Next.js, Hono, SvelteKit...).
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `secretEnvVar` | `"OHDEAR_HEALTH_SECRET"` | Environment variable name for the secret |
+| `secretHeader` | `"oh-dear-health-check-secret"` | Request header name for the secret |
+
+### `withOhDearHealth(nextConfig, options?)`
+
+Next.js config wrapper that generates the manifest before the build.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `output` | `"src/app/api/health/deps-manifest.json"` | Output path for the manifest |
+
+### CLI `ohdear-deps-manifest`
+
+```bash
+ohdear-deps-manifest --output path/to/deps-manifest.json
+```
+
+Defaults to `deps-manifest.json` in the current directory. Detects the package manager (pnpm or npm) from the lockfile.
+
+> **Note:** Yarn is not supported. Use pnpm or npm.
+
+## Contributing
+
+### Architecture
+
+```
+src/
+├── types.ts      # Shared types (DepsManifest, Vulnerability, HealthCheckResponse)
+├── generate.ts   # Manifest generation logic (build-time, execSync)
+├── handler.ts    # createHealthHandler factory — main export "."
+├── next.ts       # withOhDearHealth wrapper — export "./next"
+└── bin.ts        # CLI entry point — bin "ohdear-deps-manifest"
+```
+
+### Package manager detection
+
+The manifest generator detects the package manager from the lockfile in the project root:
+
+- `pnpm-lock.yaml` → `pnpm list --json --prod --depth Infinity`
+- Otherwise → `npm ls --json --omit=dev --all`
+- `yarn.lock` → error (not supported)
+
+### Building
+
+```bash
+pnpm install
+pnpm build
+```
+
+ESM only. TypeScript compiled with `tsc`, output in `dist/`.
+
+## Credits
+
+Made by [Breaking Web](https://www.breakingweb.com?utm_source=github&utm_medium=readme&utm_campaign=ohdear-npm-audit).
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { writeManifest } from "./generate.js";
+const args = process.argv.slice(2);
+let output = "deps-manifest.json";
+const outputIdx = args.indexOf("--output");
+if (outputIdx !== -1 && args[outputIdx + 1]) {
+    output = args[outputIdx + 1];
+}
+const cwd = process.cwd();
+const outputPath = resolve(cwd, output);
+const manifest = writeManifest(outputPath, cwd);
+console.log(`deps-manifest.json: ${Object.keys(manifest).length} packages written`);

package/dist/generate.d.ts

@@ -0,0 +1,3 @@
+import type { DepsManifest } from "./types.js";
+export declare function generateManifest(cwd: string): DepsManifest;
+export declare function writeManifest(outputPath: string, cwd: string): DepsManifest;

package/dist/generate.js

@@ -0,0 +1,63 @@
+import { execSync } from "node:child_process";
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+function detectPackageManager(cwd) {
+    if (existsSync(resolve(cwd, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(resolve(cwd, "yarn.lock"))) {
+        throw new Error("ohdear-npm-audit: yarn is not supported. Use pnpm or npm.");
+    }
+    return "npm";
+}
+function walkDeps(deps, acc) {
+    if (!deps)
+        return;
+    for (const [name, info] of Object.entries(deps)) {
+        if (!info.version)
+            continue;
+        if (!acc[name])
+            acc[name] = new Set();
+        acc[name].add(info.version);
+        walkDeps(info.dependencies, acc);
+    }
+}
+// execSync throws on non-zero exit codes, but npm ls exits with code 1
+// on missing/extraneous packages while still writing valid JSON to stdout.
+function execCommand(command, cwd) {
+    try {
+        return execSync(command, { cwd, encoding: "utf-8" });
+    }
+    catch (err) {
+        const stdout = err.stdout;
+        if (stdout)
+            return stdout;
+        throw err;
+    }
+}
+export function generateManifest(cwd) {
+    const pm = detectPackageManager(cwd);
+    let raw;
+    switch (pm) {
+        case "pnpm":
+            raw = execCommand("pnpm list --json --prod --depth Infinity", cwd);
+            break;
+        case "npm":
+            raw = execCommand("npm ls --json --omit=dev --all", cwd);
+            break;
+    }
+    const parsed = JSON.parse(raw);
+    const tree = Array.isArray(parsed) ? parsed[0] : parsed;
+    const acc = {};
+    walkDeps(tree.dependencies, acc);
+    const manifest = {};
+    for (const [name, versions] of Object.entries(acc)) {
+        manifest[name] = [...versions];
+    }
+    return manifest;
+}
+export function writeManifest(outputPath, cwd) {
+    const manifest = generateManifest(cwd);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, JSON.stringify(manifest, null, 2) + "\n");
+    return manifest;
+}

package/dist/handler.d.ts

@@ -0,0 +1,9 @@
+import type { DepsManifest } from "./types.js";
+export type { DepsManifest, HealthCheckResponse, Vulnerability, } from "./types.js";
+export interface CreateHealthHandlerOptions {
+    /** Environment variable name for the secret. Default: "OHDEAR_HEALTH_SECRET" */
+    secretEnvVar?: string;
+    /** Header name for the secret. Default: "oh-dear-health-check-secret" */
+    secretHeader?: string;
+}
+export declare function createHealthHandler(manifest: DepsManifest, options?: CreateHealthHandlerOptions): (request: Request) => Promise<Response>;

package/dist/handler.js

@@ -0,0 +1,82 @@
+const NPM_BULK_ADVISORY_URL = "https://registry.npmjs.org/-/npm/v1/security/advisories/bulk";
+const FETCH_TIMEOUT_MS = 8_000;
+function makeWarningResponse(message) {
+    return {
+        finishedAt: Math.floor(Date.now() / 1000),
+        checkResults: [
+            {
+                name: "npm_vulnerabilities",
+                label: "NPM Critical Vulnerabilities",
+                status: "warning",
+                notificationMessage: message,
+                shortSummary: "check error",
+                meta: {},
+            },
+        ],
+    };
+}
+export function createHealthHandler(manifest, options) {
+    const envVar = options?.secretEnvVar ?? "OHDEAR_HEALTH_SECRET";
+    const headerName = options?.secretHeader ?? "oh-dear-health-check-secret";
+    if (!process.env[envVar]) {
+        console.warn(`ohdear-npm-audit: env var ${envVar} is not set — all health check requests will be rejected with 401.`);
+    }
+    return async (request) => {
+        const secret = request.headers.get(headerName);
+        if (!secret || secret !== process.env[envVar]) {
+            return Response.json({ error: "Unauthorized" }, { status: 401 });
+        }
+        let res;
+        try {
+            res = await fetch(NPM_BULK_ADVISORY_URL, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(manifest),
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            const message = err instanceof DOMException && err.name === "TimeoutError"
+                ? "npm advisory API timed out"
+                : "npm advisory API request failed";
+            return Response.json(makeWarningResponse(message));
+        }
+        if (!res.ok) {
+            return Response.json(makeWarningResponse(`npm advisory API returned HTTP ${res.status}`));
+        }
+        let advisories;
+        try {
+            advisories = await res.json();
+        }
+        catch {
+            return Response.json(makeWarningResponse("Failed to parse npm advisory response"));
+        }
+        const critical = [];
+        for (const [pkg, entries] of Object.entries(advisories)) {
+            for (const entry of entries) {
+                if (entry.severity === "critical") {
+                    critical.push({ package: pkg, title: entry.title, url: entry.url });
+                }
+            }
+        }
+        const status = critical.length === 0 ? "ok" : "failed";
+        const shortSummary = `${critical.length} critical`;
+        const notificationMessage = critical.length === 0
+            ? "No critical npm vulnerabilities found."
+            : `Critical vulnerabilities in: ${critical.map((v) => v.package).join(", ")}`;
+        const body = {
+            finishedAt: Math.floor(Date.now() / 1000),
+            checkResults: [
+                {
+                    name: "npm_vulnerabilities",
+                    label: "NPM Critical Vulnerabilities",
+                    status,
+                    notificationMessage,
+                    shortSummary,
+                    meta: critical.length > 0 ? { vulnerabilities: critical } : {},
+                },
+            ],
+        };
+        return Response.json(body);
+    };
+}

package/dist/next.d.ts

@@ -0,0 +1,6 @@
+export interface WithOhDearHealthOptions {
+    /** Output path for the manifest, relative to project root.
+     *  Default: "src/app/api/health/deps-manifest.json" */
+    output?: string;
+}
+export declare function withOhDearHealth<T extends Record<string, unknown>>(nextConfig: T, options?: WithOhDearHealthOptions): T;

package/dist/next.js

@@ -0,0 +1,15 @@
+import { resolve } from "node:path";
+import { writeManifest } from "./generate.js";
+export function withOhDearHealth(nextConfig, options) {
+    const cwd = process.cwd();
+    const output = resolve(cwd, options?.output ?? "src/app/api/health/deps-manifest.json");
+    try {
+        const manifest = writeManifest(output, cwd);
+        console.log(`ohdear-npm-audit: ${Object.keys(manifest).length} packages written → ${output}`);
+    }
+    catch (err) {
+        console.error("ohdear-npm-audit: failed to generate dependency manifest.");
+        throw err;
+    }
+    return nextConfig;
+}

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+export type DepsManifest = Record<string, string[]>;
+export interface Vulnerability {
+    package: string;
+    title: string;
+    url: string;
+}
+export interface HealthCheckResult {
+    name: string;
+    label: string;
+    status: "ok" | "warning" | "failed" | "crashed";
+    notificationMessage: string;
+    shortSummary: string;
+    meta: Record<string, unknown>;
+}
+export interface HealthCheckResponse {
+    finishedAt: number;
+    checkResults: HealthCheckResult[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "ohdear-npm-audit",
+  "version": "0.1.0",
+  "description": "Oh Dear Application Health check for npm audit critical vulnerabilities",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/handler.d.ts",
+      "import": "./dist/handler.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
+    }
+  },
+  "bin": {
+    "ohdear-deps-manifest": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "ohdear",
+    "health-check",
+    "npm",
+    "vulnerabilities",
+    "security",
+    "nextjs"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}