selfguard 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 selfguard contributors
+
+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

@@ -1,6 +1,136 @@
 # selfguard
 
-This version only reserves the package name. It contains no code.
+[![npm](https://img.shields.io/npm/v/selfguard)](https://www.npmjs.com/package/selfguard)
+[![CI](https://github.com/josseed/selfguard/actions/workflows/ci.yml/badge.svg)](https://github.com/josseed/selfguard/actions/workflows/ci.yml)
+[![provenance](https://img.shields.io/badge/npm-provenance-blue)](https://www.npmjs.com/package/selfguard#provenance)
+[![license](https://img.shields.io/npm/l/selfguard)](LICENSE)
 
-The first real release (published from GitHub Actions with provenance) will be available soon:
-https://github.com/josseed/selfguard
+**A local-first guard for the dependencies of every JavaScript repo on your machine.**
+
+Most dependency scanners only check a project when you remember to run them, or only for repos
+hosted on a platform. selfguard tracks every project on your machine and checks their lockfiles
+against [OSV.dev](https://osv.dev). It tells you when one of them is affected by a new
+vulnerability or a malicious package, including repos you haven't opened in months.
+
+```text
+$ selfguard status
+CRITICAL acme/storefront  31 vulnerable pkg(s) on main · 82 on feat/checkout  3 checkouts
+   ├ main  31 vulnerable  ~/code/storefront
+   ├ fix/query-perf worktree  30 vulnerable  ~/code/storefront-query-perf
+   └ feat/checkout worktree  82 vulnerable  ~/code/storefront-feat-checkout
+HIGH     acme/payments-api  3 vulnerable pkg(s)  ~/code/payments-api
+✓        acme/docs-site  clean  ~/code/docs-site
+```
+
+## Features
+
+- **It tells you on its own.** A background watcher re-checks a repo seconds after its lockfile
+  changes (`git pull`, installs, merges), a scheduled sync catches newly published advisories,
+  and a daily reminder lists what is still open and serious. When you fix something, you get a
+  "✓ fixed" notification too.
+- **A dashboard, not just a terminal.** `selfguard ui` opens a local page with every repo, what
+  needs attention, how to fix it, and a feed of what changed.
+- **Signal over noise.** Only checkouts with recent git activity alert you. Old clones and
+  abandoned worktrees stay listed but quiet (except for malicious packages), and a new worktree
+  of a known repo isn't reported as news.
+- **Hands-off.** `cd` into a project and it is registered and scanned in the background. New
+  clones in your code folders are picked up automatically.
+- **Malicious packages first.** OSV includes the OpenSSF malicious-packages feed (`MAL-*`).
+  Compromised releases, like the Shai-Hulud npm worm, outrank any CVE and open a dialog that
+  stays on screen until you dismiss it.
+- **Actionable output.** One upgrade target per vulnerable package ("upgrade lodash to 4.18.0"),
+  not a wall of advisories.
+- **Every package manager.** npm, pnpm, yarn (classic and berry) and bun lockfiles.
+- **Repo-aware.** Git worktrees and clones of the same repo are grouped, each with its branch.
+- **Incident response.** `selfguard where <package>` answers "do I use this anywhere?" in one
+  command.
+- **AI-ready.** A built-in MCP server, `--json` output on every command, and a guide for agents.
+- **Safe by design.** It never executes code from your projects, has zero runtime dependencies,
+  and only sends package names and versions over the network.
+
+## Quick start
+
+Requires **Node.js 20.10+**. Works on **macOS** and **Linux**. Native notifications and
+scheduling are macOS-only for now.
+
+```sh
+npm install -g selfguard
+selfguard setup
+```
+
+`setup` is a small terminal UI. Pick the folders where you keep your code, and selfguard scans
+them. It then offers to install the shell hook and background watching with notifications.
+Then open the dashboard:
+
+```sh
+selfguard ui
+```
+
+```text
+Where do you keep your code?
+selfguard only looks inside the folders you pick, nothing else on your disk.
+
+  [x] ~/code                          42 projects    depth 5
+› [ ] ~/work                          17 projects    depth 5
+  + add another folder…
+
+↑/↓ move · space select · ←/→ depth · a add folder · enter continue · q quit
+```
+
+Or scan a single project without setting anything up:
+
+```text
+$ selfguard scan
+~/code/payments-api  412 packages
+  3 vulnerable package(s), 9 advisories: 1 critical, 4 high, 4 moderate
+
+  CRITICAL minimist@1.2.5 (transitive)
+    → upgrade to 1.2.6 or later
+    • GHSA-xvch-5gv4-984h critical Prototype Pollution in minimist
+
+  HIGH axios@0.21.0 (direct)
+    → upgrade to 0.33.0 or later
+    • GHSA-cph5-m8f7-6c5x high axios Inefficient Regular Expression Complexity vulnerability
+    …
+```
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, setup, dashboard, alerts, uninstall |
+| [CLI reference](docs/cli.md) | Every command and flag, exit codes, environment variables |
+| [How it works](docs/how-it-works.md) | Discovery, lockfile parsing, repo grouping, OSV, caching, alerts |
+| [AI and automation](docs/ai-and-automation.md) | MCP server setup, tools, JSON output, scripting and CI |
+| [Security model](docs/security-model.md) | What selfguard trusts, what it sends, how it is released |
+| [Troubleshooting](docs/troubleshooting.md) | Notifications, hook, scheduling, unsupported lockfiles |
+
+## How it compares
+
+| | selfguard | `npm audit` | osv-scanner | Dependabot |
+|---|---|---|---|---|
+| Watches every project on your machine | ✅ | ❌ one project, on demand | ❌ on demand | ❌ hosted repos only |
+| Alerts when a new advisory hits an old project | ✅ | ❌ | ❌ | ✅ |
+| Local-only (no repo hosting required) | ✅ | ✅ | ✅ | ❌ |
+| npm, pnpm, yarn, bun | ✅ | npm only | ✅ | ✅ |
+| Malicious package feed | ✅ via OSV | ❌ | ✅ via OSV | partial |
+| Opens PRs with fixes | ❌ | ❌ (`npm audit fix` locally) | guided remediation | ✅ |
+| Ecosystems | JavaScript | JavaScript | many | many |
+
+selfguard complements these tools rather than replacing them. Keep Dependabot or Renovate for
+automated fix PRs, and use selfguard to know what is vulnerable on your machine right now.
+
+## Privacy
+
+selfguard sends only `name` and `version` pairs of your locked dependencies to the OSV.dev API.
+No file paths, repo names or source code ever leave your machine. All state lives in
+`~/.selfguard`, readable only by your user. See the [security model](docs/security-model.md).
+
+## Contributing
+
+Bug reports, ideas and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+Please report security issues privately as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/activity.js

@@ -0,0 +1,12 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function activityOf(repo, activeDays, now = Date.now()) {
+    // Not a git checkout: we can't tell, so it counts (you added it on purpose).
+    if (!repo)
+        return { active: true, lastActivity: null };
+    if (repo.orphaned)
+        return { active: false, lastActivity: null };
+    if (!repo.lastActivity)
+        return { active: true, lastActivity: null };
+    const age = now - Date.parse(repo.lastActivity);
+    return { active: age <= activeDays * DAY_MS, lastActivity: repo.lastActivity };
+}

package/dist/alerts.js

@@ -0,0 +1,189 @@
+/** Decide what to tell the user (and how) after a scan or sync. Pure: easy to test. */
+import { basename } from "node:path";
+import { criticalDialog, notify } from "./notify.js";
+import { groupByPackage, worstSeverity } from "./report.js";
+const LABEL = {
+    malicious: "MALICIOUS",
+    critical: "CRITICAL",
+    high: "HIGH",
+    moderate: "MODERATE",
+    low: "LOW",
+    unknown: "UNKNOWN",
+};
+const name = (path) => basename(path) || path;
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+function listFixes(findings, max = 3) {
+    const groups = groupByPackage(findings);
+    const parts = groups.slice(0, max).map((g) => (g.upgradeTo ? `${g.name} → ${g.upgradeTo}` : `${g.name} (no fix yet)`));
+    if (groups.length > max)
+        parts.push(`+${groups.length - max} more`);
+    return parts.join(", ");
+}
+/** Merge checkouts of the same repo into one entry, de-duplicating findings. */
+function byRepo(news) {
+    const groups = new Map();
+    for (const n of news) {
+        if (n.newFindings.length === 0)
+            continue;
+        const key = n.repo?.key ?? `path:${n.path}`;
+        let g = groups.get(key);
+        if (!g) {
+            g = { path: n.path, newFindings: [], label: n.repo?.label ?? name(n.path), checkouts: 0, seen: new Set() };
+            groups.set(key, g);
+        }
+        g.checkouts++;
+        for (const f of n.newFindings) {
+            const k = `${f.id}|${f.name}@${f.version}`;
+            if (g.seen.has(k))
+                continue;
+            g.seen.add(k);
+            g.newFindings.push(f);
+        }
+    }
+    return [...groups.values()].map(({ seen: _s, ...g }) => g);
+}
+export function buildAlert(news) {
+    const relevant = news.map((n) => n.active === false ? { ...n, newFindings: n.newFindings.filter((f) => f.severity === "malicious") } : n);
+    const affected = byRepo(relevant);
+    if (affected.length === 0)
+        return { kind: "none" };
+    const all = affected.flatMap((n) => n.newFindings);
+    const malicious = affected.flatMap((n) => n.newFindings.filter((f) => f.severity === "malicious").map((f) => ({ f, path: n.path })));
+    if (malicious.length > 0) {
+        const { f, path } = malicious[0];
+        const group = affected.find((n) => n.path === path);
+        const where = affected.length === 1 ? group.label : `${affected.length} projects`;
+        const others = malicious.length > 1 ? ` (+${malicious.length - 1} more malicious)` : "";
+        return {
+            kind: "critical",
+            title: `⛔ Malicious package in ${where}`,
+            subtitle: `${f.name}@${f.version} · ${f.id}`,
+            body: "Remove it now and rotate credentials on this machine.",
+            dialogTitle: `selfguard: malicious package in ${where}`,
+            dialogMessage: `${f.name}@${f.version} is a known malicious package${others}.\n\n` +
+                `Project: ${path}${group.checkouts > 1 ? ` (and ${group.checkouts - 1} other checkout(s) of ${group.label})` : ""}\n\n` +
+                "1. Remove it (or pin a safe version) and reinstall.\n" +
+                "2. Rotate credentials this machine or CI could reach: npm tokens, cloud keys, SSH keys, .env secrets.\n" +
+                "3. Check the advisory for what the payload does.",
+            url: `https://osv.dev/vulnerability/${encodeURIComponent(f.id)}`,
+        };
+    }
+    const worst = LABEL[worstSeverity(all) ?? "unknown"];
+    if (affected.length === 1) {
+        const n = affected[0];
+        const pkgs = groupByPackage(n.newFindings).length;
+        return {
+            kind: "banner",
+            title: `selfguard: ${n.label}${n.checkouts > 1 ? ` (${n.checkouts} checkouts)` : ""}`,
+            subtitle: `${plural(pkgs, "vulnerable package")} · worst: ${worst}`,
+            body: listFixes(n.newFindings),
+        };
+    }
+    const pkgs = affected.reduce((sum, n) => sum + groupByPackage(n.newFindings).length, 0);
+    const names = affected.map((n) => n.label);
+    return {
+        kind: "banner",
+        title: `selfguard: ${affected.length} projects affected`,
+        subtitle: `${plural(pkgs, "vulnerable package")} · worst: ${worst}`,
+        body: `${names.slice(0, 3).join(", ")}${names.length > 3 ? ` +${names.length - 3} more` : ""}. Run: selfguard status`,
+    };
+}
+const pkgKey = (f) => `${f.name}@${f.version}`;
+/** "datahub ✓ 17 vulnerable packages fixed": only for active checkouts, grouped by repo. */
+export function buildResolvedAlert(news) {
+    const groups = new Map();
+    for (const n of news) {
+        if (n.active === false || !n.resolvedFindings?.length)
+            continue;
+        const still = new Set((n.findings ?? []).map(pkgKey));
+        const fixed = n.resolvedFindings.map(pkgKey).filter((k) => !still.has(k));
+        if (fixed.length === 0)
+            continue;
+        const key = n.repo?.key ?? `path:${n.path}`;
+        let g = groups.get(key);
+        if (!g) {
+            g = { label: n.repo?.label ?? name(n.path), fixed: new Set(), left: new Map() };
+            groups.set(key, g);
+        }
+        for (const k of fixed)
+            g.fixed.add(k);
+        for (const f of n.findings ?? [])
+            g.left.set(`${f.id}|${pkgKey(f)}`, f);
+    }
+    if (groups.size === 0)
+        return { kind: "none" };
+    const list = [...groups.values()];
+    const total = list.reduce((sum, g) => sum + g.fixed.size, 0);
+    if (list.length === 1) {
+        const g = list[0];
+        const left = [...g.left.values()];
+        const leftPkgs = groupByPackage(left).length;
+        return {
+            kind: "banner",
+            title: `selfguard: ${g.label} ✓`,
+            subtitle: `${plural(g.fixed.size, "vulnerable package")} fixed`,
+            body: leftPkgs
+                ? `${leftPkgs} still vulnerable · worst: ${LABEL[worstSeverity(left) ?? "unknown"]}`
+                : "No known vulnerabilities left.",
+        };
+    }
+    const names = list.map((g) => g.label);
+    return {
+        kind: "banner",
+        title: `selfguard: fixes in ${list.length} repos`,
+        subtitle: `${plural(total, "vulnerable package")} fixed`,
+        body: `${names.slice(0, 3).join(", ")}${names.length > 3 ? ` +${names.length - 3} more` : ""}`,
+    };
+}
+/**
+ * What a reminder nags about: any malicious package; critical vulnerabilities outside dev
+ * dependencies; high ones in direct (non-dev) dependencies. The rest stays in the dashboard,
+ * so the reminder remains rare enough to be read.
+ */
+export const needsAttention = (f) => f.severity === "malicious" || (!f.dev && (f.severity === "critical" || (f.severity === "high" && f.direct)));
+function severityCounts(findings) {
+    const counts = new Map();
+    for (const g of groupByPackage(findings))
+        counts.set(g.worst, (counts.get(g.worst) ?? 0) + 1);
+    return ["malicious", "critical", "high"]
+        .filter((s) => counts.get(s))
+        .map((s) => `${counts.get(s)} ${s}`)
+        .join(", ");
+}
+/** Periodic reminder of unresolved serious findings in the repos you work on. */
+export function buildReminder(repos) {
+    const rank = (s) => ["malicious", "critical", "high"].indexOf(s ?? "");
+    const serious = repos
+        .map((r) => ({ label: r.label, findings: r.findings.filter(needsAttention) }))
+        .filter((r) => r.findings.length > 0)
+        .sort((a, b) => rank(worstSeverity(a.findings)) - rank(worstSeverity(b.findings)) ||
+        groupByPackage(b.findings).length - groupByPackage(a.findings).length);
+    if (serious.length === 0)
+        return { kind: "none" };
+    const all = serious.flatMap((r) => r.findings);
+    if (serious.length === 1) {
+        const r = serious[0];
+        return {
+            kind: "banner",
+            title: `selfguard: ${r.label} needs attention`,
+            subtitle: `${severityCounts(r.findings)} · open: selfguard ui`,
+            body: listFixes(r.findings),
+        };
+    }
+    const parts = serious.slice(0, 3).map((r) => `${r.label} (${severityCounts(r.findings)})`);
+    if (serious.length > 3)
+        parts.push(`+${serious.length - 3} more`);
+    return {
+        kind: "banner",
+        title: `selfguard: ${serious.length} repos need attention`,
+        subtitle: `worst: ${LABEL[worstSeverity(all) ?? "unknown"]} · open: selfguard ui`,
+        body: parts.join(", "),
+    };
+}
+export async function deliver(alert) {
+    if (alert.kind === "none")
+        return;
+    await notify(alert.title, alert.body, alert.subtitle);
+    if (alert.kind === "critical")
+        await criticalDialog(alert.dialogTitle, alert.dialogMessage, alert.url);
+}

package/dist/announce.js

@@ -0,0 +1,136 @@
+/**
+ * Side effects after a scan: record what changed in the activity log and tell the user
+ * (new advisories, fixes, periodic reminders). Decisions live in alerts.ts.
+ */
+import { activityOf } from "./activity.js";
+import { buildAlert, buildReminder, buildResolvedAlert, deliver, needsAttention } from "./alerts.js";
+import { loadConfig } from "./config.js";
+import { appendEvents, eventPackages } from "./events.js";
+import { repoIdentity } from "./repoid.js";
+import { loadState, updateState } from "./state.js";
+import { findingKey, listRepos } from "./store.js";
+const HOUR_MS = 60 * 60 * 1000;
+/**
+ * Findings already known in other checkouts of the same repo (current or recently seen).
+ * A new worktree or clone of a repo isn't news: only what no checkout had before is.
+ */
+function knownElsewhere(outcomes) {
+    const scanned = new Set(outcomes.map((o) => o.record.path));
+    let byRepo = null;
+    return (key, path) => {
+        if (!byRepo) {
+            byRepo = new Map();
+            for (const rec of listRepos()) {
+                const k = repoIdentity(rec.path)?.key ?? `path:${rec.path}`;
+                const keys = new Set([...Object.keys(rec.seen ?? {}), ...rec.findings.map(findingKey)]);
+                const list = byRepo.get(k) ?? [];
+                list.push({ path: rec.path, keys });
+                byRepo.set(k, list);
+            }
+        }
+        const out = new Set();
+        for (const other of byRepo.get(key) ?? []) {
+            // Other checkouts scanned in this same run don't count: they're news too.
+            if (other.path === path || scanned.has(other.path))
+                continue;
+            for (const k of other.keys)
+                out.add(k);
+        }
+        return out;
+    };
+}
+function toNews(outcomes, activeDays) {
+    const known = knownElsewhere(outcomes);
+    return outcomes.map((o) => {
+        const repo = repoIdentity(o.record.path);
+        const key = repo?.key ?? `path:${o.record.path}`;
+        const elsewhere = o.newFindings.length ? known(key, o.record.path) : new Set();
+        return {
+            path: o.record.path,
+            newFindings: o.newFindings.filter((f) => !elsewhere.has(findingKey(f))),
+            resolvedFindings: o.resolvedFindings,
+            findings: o.record.findings,
+            repo,
+            active: activityOf(repo, activeDays).active,
+            branch: repo?.branch ?? null,
+            firstScan: o.firstScan,
+        };
+    });
+}
+/** Log and notify what changed. Returns true if something was notified. */
+export async function announce(outcomes, opts = {}) {
+    const news = toNews(outcomes, loadConfig().activeDays);
+    const at = new Date().toISOString();
+    const events = [];
+    for (const n of news) {
+        const base = {
+            at,
+            repo: n.repo?.label ?? n.path.split("/").pop() ?? n.path,
+            repoKey: n.repo?.key ?? `path:${n.path}`,
+            path: n.path,
+            branch: n.branch,
+            active: n.active !== false,
+        };
+        if (n.newFindings.length)
+            events.push({ ...base, kind: "new", ...(n.firstScan ? { firstScan: true } : {}), ...eventPackages(n.newFindings) });
+        const still = new Set((n.findings ?? []).map((f) => `${f.name}@${f.version}`));
+        const fixed = (n.resolvedFindings ?? []).filter((f) => !still.has(`${f.name}@${f.version}`));
+        if (fixed.length)
+            events.push({ ...base, kind: "resolved", ...eventPackages(fixed) });
+    }
+    try {
+        appendEvents(events);
+    }
+    catch {
+        /* the log is a convenience; never fail a scan because of it */
+    }
+    if (opts.notify === false)
+        return false;
+    const alerts = [buildAlert(news), buildResolvedAlert(news)].filter((a) => a.kind !== "none");
+    for (const a of alerts)
+        await deliver(a);
+    return alerts.length > 0;
+}
+/** Is a reminder due? Daytime only (9:00–21:00 local), at most once per period. */
+export function reminderDue(every, last, now = new Date()) {
+    if (every === "off")
+        return false;
+    const hour = now.getHours();
+    if (hour < 9 || hour >= 21)
+        return false;
+    if (!last)
+        return true;
+    const gap = every === "daily" ? 20 * HOUR_MS : 6.5 * 24 * HOUR_MS;
+    return now.getTime() - Date.parse(last) >= gap;
+}
+/**
+ * Send the periodic reminder if it is due (or `force`). The input comes from api.getAttention().
+ * Returns whether a notification was sent.
+ */
+export async function maybeRemind(source, opts = {}) {
+    const cfg = loadConfig();
+    if (!opts.force && !reminderDue(cfg.remind, loadState().lastReminder))
+        return false;
+    // Computed only when due: the watcher calls this often.
+    const repos = typeof source === "function" ? source() : source;
+    const alert = buildReminder(repos);
+    // Mark the period as handled even when everything is fine, so a later finding waits its turn.
+    updateState({ lastReminder: new Date().toISOString() });
+    if (alert.kind === "none")
+        return false;
+    await deliver(alert);
+    appendEvents([
+        {
+            at: new Date().toISOString(),
+            kind: "reminder",
+            repo: alert.title.replace(/^selfguard: /, ""),
+            repoKey: "reminder",
+            path: null,
+            branch: null,
+            active: true,
+            total: repos.filter((r) => r.findings.some(needsAttention)).length,
+            packages: [],
+        },
+    ]);
+    return true;
+}