killm 1.0.0 → 1.0.3

package/README.md

@@ -39,6 +39,36 @@ Editing the hosts file needs elevated privileges:
 - **macOS / Linux:** prefix with `sudo` → `sudo npx killm for 1h --agents`
 - **Windows:** run from an **Administrator** terminal
 
+### WSL users — read this
+
+WSL and Windows have **separate hosts files**. Running `sudo npx killm` inside
+WSL edits WSL's `/etc/hosts`, which only blocks processes running _inside_ WSL
+(curl, node, coding agents in your WSL shell). Your browser is a Windows app —
+it reads `C:\Windows\System32\drivers\etc\hosts` and is **not affected**.
+
+To block Windows apps (the browser, Windows-side editors), run killm **on
+Windows** from an Administrator PowerShell:
+
+```powershell
+npx killm for 1h --web
+```
+
+killm detects WSL and prints a warning when this applies. If you want both
+sides blocked, run it in both places.
+
+### Browser caveats
+
+Two browser behaviors can make a block look like it isn't working:
+
+- **Secure DNS (DNS-over-HTTPS):** when enabled, the browser resolves names
+  through an encrypted remote resolver and **bypasses the hosts file
+  entirely**. Disable it (Chrome/Edge: Settings → Privacy → Security → "Use
+  secure DNS"; Firefox: Settings → Privacy → DNS over HTTPS) for the block to
+  apply.
+- **Browser DNS caching:** already-open tabs and cached lookups keep working
+  for a while. Restart the browser, or clear its DNS cache
+  (`chrome://net-internals/#dns` in Chrome/Edge).
+
 ## The key idea: agents vs. web
 
 The whole point of `killm` is that an agentic coding tool and a chat website
@@ -95,6 +125,7 @@ You can combine `--agents` and `--web`; that's the same as `--all`.
 
 | Option            | Effect                                           |
 | ----------------- | ------------------------------------------------ |
+| `--firewall`      | Also block current IPs at the OS firewall        |
 | `--restore`       | Lift any active block right now and exit         |
 | `--status`        | Report whether a block is currently active       |
 | `--list`          | Print the hostnames a given scope would block    |
@@ -132,12 +163,55 @@ target hostname at `0.0.0.0` (and `::1` for IPv6):
 ```
 
 It then flushes the OS DNS cache so the change takes effect immediately. When
-the timer expires, or on `Ctrl+C`, `SIGTERM`, or process exit, it strips that
-block back out and flushes again. The markers mean it only ever touches its own
-lines — your existing hosts entries are left alone.
+the timer expires — or on `Ctrl+C`, `SIGTERM`, or closing the terminal
+(`SIGHUP`) — it strips that block back out and flushes again. The markers mean
+it only ever touches its own lines — your existing hosts entries are left
+alone.
+
+### If the killm process dies, the block stays — until killm heals it
+
+The timer lives in the killm process, so **keep it running** for the duration.
+Ctrl+C and closing the terminal both lift the block cleanly, but a `kill -9`,
+a crash, or a machine shutdown can strand the block in your hosts file.
+
+killm writes the expiry time into the block itself, so it self-heals: **any
+later killm command** (`--status`, `--restore`, or starting a new block)
+notices an expired stranded block and removes it. To lift one immediately:
+
+```bash
+sudo npx killm --restore
+```
+
+`killm --status` also tells you when an active block is scheduled to lift.
+
+## Firewall mode (`--firewall`)
+
+The hosts file only intercepts name resolution, so a browser with **Secure DNS
+(DoH)** enabled bypasses it. `--firewall` closes that hole: in addition to the
+hosts entries, killm resolves each target hostname to its **current IPs** and
+blocks those at the OS firewall:
+
+```bash
+sudo npx killm for 1h --web --firewall
+```
+
+- **Linux:** `iptables` / `ip6tables` OUTPUT rules, tagged with a `killm`
+  comment
+- **Windows:** one outbound Windows Firewall rule named `killm` (via `netsh`)
+- **macOS:** a `pf` anchor named `killm`
+
+Rules are removed together with the hosts block (timer, `Ctrl+C`, or
+`killm --restore` — which also sweeps up rules left behind by a crash, since
+they're all tagged).
+
+Caveats, honestly stated:
 
-If something goes wrong and a block is left behind, `sudo npx killm --restore`
-(or the Administrator equivalent) cleans it up.
+- IPs are captured **at block time**; if a provider rotates addresses
+  mid-block, new IPs aren't covered.
+- Big providers sit behind shared CDNs — blocking their current IPs _may_
+  affect unrelated sites served from the same edge.
+- Inside WSL, iptables rules (like the hosts file) only affect WSL traffic,
+  not Windows apps.
 
 ## Limitations & honesty
 

package/dist/src/cli.js

@@ -23,6 +23,9 @@ SCOPE  (pick one or more; default is --all)
   --all      Block both of the above. This is the default if no scope is given.
 
 OPTIONS
+  --firewall       Also block the targets' current IPs at the OS firewall
+                   (iptables/ip6tables, Windows Firewall, or pf). Catches
+                   browsers that bypass the hosts file via Secure DNS (DoH).
   --restore        Remove any active killm block right now and exit.
   --status         Show whether a block is currently active and exit.
   --list           Print the hostnames that would be blocked and exit.
@@ -50,6 +53,7 @@ export function parseArgs(argv) {
         scope: { agents: false, web: false, all: false },
         dryRun: false,
         yes: false,
+        firewall: false,
     };
     let explicit;
     let durationInput;
@@ -74,6 +78,9 @@ export function parseArgs(argv) {
             case '--dry-run':
                 result.dryRun = true;
                 break;
+            case '--firewall':
+                result.firewall = true;
+                break;
             case '-y':
             case '--yes':
                 result.yes = true;

package/dist/src/firewall.js

@@ -0,0 +1,175 @@
+import { execFile } from 'node:child_process';
+import dns from 'node:dns/promises';
+/**
+ * Firewall-level blocking, layered on top of the hosts-file block.
+ *
+ * The hosts file only intercepts name resolution, so a browser with Secure
+ * DNS (DoH) enabled sails right past it. Firewall mode resolves each target
+ * hostname to its current IPs and blocks those at the OS firewall:
+ *
+ *   - Linux:   iptables / ip6tables OUTPUT rules tagged with a "killm" comment
+ *   - Windows: a single "killm" outbound netsh advfirewall rule
+ *   - macOS:   a pf anchor named "killm"
+ *
+ * All rules are identifiable without local state, so `killm --restore` can
+ * always clean up, even after a crash.
+ */
+export const RULE_TAG = 'killm';
+/** Maximum IPs per netsh rule; Windows accepts a comma list but not unbounded. */
+const WINDOWS_CHUNK = 100;
+export const defaultRunner = (cmd, args, stdin) => new Promise((resolve) => {
+    const child = execFile(cmd, args, (error, stdout) => resolve({ ok: !error, stdout: stdout ?? '' }));
+    if (stdin != null && child.stdin) {
+        child.stdin.write(stdin);
+        child.stdin.end();
+    }
+});
+/**
+ * Resolve every hostname to its current A/AAAA records. Failures are
+ * collected, not thrown — an unresolvable host simply can't be blocked by IP.
+ */
+export async function resolveTargetIPs(hosts, resolver = dns) {
+    const v4 = new Set();
+    const v6 = new Set();
+    const unresolved = [];
+    await Promise.all(hosts.map(async (host) => {
+        const [a, aaaa] = await Promise.all([
+            resolver.resolve4(host).catch(() => []),
+            resolver.resolve6(host).catch(() => []),
+        ]);
+        if (a.length === 0 && aaaa.length === 0) {
+            unresolved.push(host);
+            return;
+        }
+        for (const ip of a)
+            v4.add(ip);
+        for (const ip of aaaa)
+            v6.add(ip);
+    }));
+    return { v4: Array.from(v4).sort(), v6: Array.from(v6).sort(), unresolved: unresolved.sort() };
+}
+// ---- pure command builders (unit-tested per platform) --------------------
+/** iptables/ip6tables arguments to add one REJECT rule tagged with killm. */
+export function linuxAddArgs(ip) {
+    return ['-I', 'OUTPUT', '-d', ip, '-j', 'REJECT', '-m', 'comment', '--comment', RULE_TAG];
+}
+/**
+ * Convert `iptables -S OUTPUT` output into the `-D` argument lists needed to
+ * delete every killm-tagged rule. Our rules never contain quoted spaces, so
+ * whitespace splitting is safe.
+ */
+export function linuxDeleteArgsFromListing(listing) {
+    const out = [];
+    for (const line of listing.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('-A OUTPUT'))
+            continue;
+        if (!trimmed.includes(`--comment ${RULE_TAG}`))
+            continue;
+        out.push(['-D', ...trimmed.slice('-A '.length).split(/\s+/)]);
+    }
+    return out;
+}
+/** netsh argument lists to add the killm outbound block rule(s). */
+export function windowsAddArgs(ips) {
+    const out = [];
+    for (let i = 0; i < ips.length; i += WINDOWS_CHUNK) {
+        const chunk = ips.slice(i, i + WINDOWS_CHUNK);
+        out.push([
+            'advfirewall',
+            'firewall',
+            'add',
+            'rule',
+            `name=${RULE_TAG}`,
+            'dir=out',
+            'action=block',
+            `remoteip=${chunk.join(',')}`,
+        ]);
+    }
+    return out;
+}
+/** netsh argument list that deletes every rule named killm. */
+export function windowsDeleteArgs() {
+    return ['advfirewall', 'firewall', 'delete', 'rule', `name=${RULE_TAG}`];
+}
+/** pf rule text for the killm anchor on macOS. */
+export function darwinAnchorRules(v4, v6) {
+    const all = [...v4, ...v6];
+    if (all.length === 0)
+        return '';
+    return `block drop out quick to { ${all.join(', ')} }\n`;
+}
+/**
+ * Resolve the hostnames and install firewall rules for their current IPs.
+ * Throws on unsupported platforms; individual rule failures are tolerated.
+ */
+export async function applyFirewall(hosts, opts = {}) {
+    const runner = opts.runner ?? defaultRunner;
+    const platform = opts.platform ?? process.platform;
+    const { v4, v6, unresolved } = await resolveTargetIPs(hosts, opts.resolver);
+    const blocked = v4.length + v6.length;
+    // Individual rule failures are tolerated, but if not a single command
+    // succeeded the firewall tool itself is missing/unusable — surface that
+    // instead of pretending the IPs are blocked.
+    let applied = 0;
+    const failIfNothingApplied = () => {
+        if (blocked > 0 && applied === 0) {
+            throw new Error('no firewall rules could be applied (is the firewall tool available?)');
+        }
+        return { blocked, unresolved };
+    };
+    if (platform === 'linux') {
+        for (const ip of v4)
+            if ((await runner('iptables', linuxAddArgs(ip))).ok)
+                applied++;
+        for (const ip of v6)
+            if ((await runner('ip6tables', linuxAddArgs(ip))).ok)
+                applied++;
+        return failIfNothingApplied();
+    }
+    if (platform === 'win32') {
+        for (const args of windowsAddArgs([...v4, ...v6])) {
+            if ((await runner('netsh', args)).ok)
+                applied++;
+        }
+        return failIfNothingApplied();
+    }
+    if (platform === 'darwin') {
+        const rules = darwinAnchorRules(v4, v6);
+        if (rules) {
+            await runner('pfctl', ['-e']); // best effort: enable pf if it isn't
+            if ((await runner('pfctl', ['-a', RULE_TAG, '-f', '-'], rules)).ok)
+                applied++;
+        }
+        return failIfNothingApplied();
+    }
+    throw new Error(`--firewall is not supported on platform "${platform}"`);
+}
+/**
+ * Remove every killm firewall rule. Needs no stored state, so it also cleans
+ * up rules left behind by a crashed run. Failures are tolerated — rules that
+ * don't exist can't be removed.
+ */
+export async function removeFirewall(opts = {}) {
+    const runner = opts.runner ?? defaultRunner;
+    const platform = opts.platform ?? process.platform;
+    if (platform === 'linux') {
+        for (const tool of ['iptables', 'ip6tables']) {
+            const listing = await runner(tool, ['-S', 'OUTPUT']);
+            if (!listing.ok)
+                continue;
+            for (const args of linuxDeleteArgsFromListing(listing.stdout)) {
+                await runner(tool, args);
+            }
+        }
+        return;
+    }
+    if (platform === 'win32') {
+        await runner('netsh', windowsDeleteArgs());
+        return;
+    }
+    if (platform === 'darwin') {
+        await runner('pfctl', ['-a', RULE_TAG, '-F', 'rules']);
+        return;
+    }
+}

package/dist/src/hosts.js

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { execFile } from 'node:child_process';
 export const BEGIN = '# >>> killm block (do not edit between markers) >>>';
 export const END = '# <<< killm block <<<';
+/** Machine-parseable expiry marker inside the block. */
+export const EXPIRES_PREFIX = '# killm-expires: ';
 const SINK4 = '0.0.0.0';
 const SINK6 = '::1';
 function errnoCode(err) {
@@ -59,6 +61,7 @@ export function buildBlock(hosts, opts = {}) {
     lines.push(`# added by killm at ${new Date().toISOString()}`);
     if (opts.until) {
         lines.push(`# auto-removed at ${opts.until.toISOString()} (or when killm exits)`);
+        lines.push(`${EXPIRES_PREFIX}${opts.until.toISOString()}`);
     }
     for (const h of hosts) {
         lines.push(`${SINK4}\t${h}`);
@@ -125,6 +128,36 @@ export function removeBlock() {
 export function isBlocked() {
     return readHosts().includes(BEGIN);
 }
+/**
+ * When the current block is scheduled to expire, or null when no block is
+ * present or it carries no (valid) expiry marker — e.g. blocks written by
+ * killm <= 1.0.2.
+ */
+export function blockExpiry(text = readHosts()) {
+    const begin = text.indexOf(BEGIN);
+    if (begin === -1)
+        return null;
+    const idx = text.indexOf(EXPIRES_PREFIX, begin);
+    if (idx === -1)
+        return null;
+    const start = idx + EXPIRES_PREFIX.length;
+    const lineEnd = text.indexOf('\n', start);
+    const stamp = text.slice(start, lineEnd === -1 ? undefined : lineEnd).trim();
+    const date = new Date(stamp);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/**
+ * Remove the block if its expiry has passed — heals hosts files stranded by
+ * a killed process (terminal closed, kill -9, crash, machine shutdown).
+ *
+ * @returns true when an expired block was found and removed
+ */
+export function clearExpiredBlock(now = new Date()) {
+    const expiry = blockExpiry();
+    if (expiry === null || expiry.getTime() > now.getTime())
+        return false;
+    return removeBlock();
+}
 /**
  * Best-effort DNS cache flush so the new hosts entries take effect immediately.
  * Silently ignores failures — the block still works, it may just take a moment.
@@ -159,3 +192,18 @@ export function hasPrivileges() {
         return true;
     return typeof process.getuid === 'function' && process.getuid() === 0;
 }
+/**
+ * Whether we are running inside Windows Subsystem for Linux. A block applied
+ * here edits WSL's /etc/hosts only — Windows browsers read the Windows hosts
+ * file and are NOT affected.
+ */
+export function isWsl(procVersionPath = '/proc/version') {
+    if (process.platform !== 'linux')
+        return false;
+    try {
+        return /microsoft/i.test(fs.readFileSync(procVersionPath, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/index.js

@@ -3,6 +3,7 @@ import { parseArgs, HELP, VERSION } from './cli.js';
 import { resolveTargets } from './targets.js';
 import { formatDuration } from './duration.js';
 import * as hosts from './hosts.js';
+import * as firewall from './firewall.js';
 // Minimal ANSI styling that degrades to plain text when not a TTY.
 const tty = process.stdout.isTTY === true;
 const c = {
@@ -93,6 +94,15 @@ async function runBlock(parsed) {
             return 0;
         }
     }
+    // Heal any expired block stranded by a killed process before applying ours.
+    try {
+        if (hosts.clearExpiredBlock()) {
+            out(c.dim('  (cleaned up an expired block left behind by a previous run)'));
+        }
+    }
+    catch {
+        /* no privileges; the apply below will surface the real error */
+    }
     const endTime = Date.now() + durationMs;
     const until = new Date(endTime);
     try {
@@ -110,6 +120,37 @@ async function runBlock(parsed) {
     }
     await hosts.flushDns();
     out(c.green(`  ✓ block active until ${until.toLocaleTimeString()}`));
+    let firewallActive = false;
+    if (parsed.firewall) {
+        try {
+            const result = await firewall.applyFirewall(targets);
+            firewallActive = true;
+            out(c.green(`  ✓ firewall: blocked ${result.blocked} IPs at the OS firewall`));
+            if (result.unresolved.length > 0) {
+                out(c.dim(`    (${result.unresolved.length} hostnames did not resolve and were skipped)`));
+            }
+        }
+        catch (e) {
+            err(c.yellow(`  ⚠ firewall rules could not be applied: ${e.message}`));
+            err(c.yellow('    Continuing with the hosts-file block only.'));
+        }
+    }
+    if (hosts.isWsl()) {
+        out();
+        out(c.yellow('  ⚠ WSL detected: this only blocks processes running inside WSL.'));
+        out(c.yellow('    Windows apps (your browser!) read the Windows hosts file and are'));
+        out(c.yellow('    NOT affected. To block them, run killm from an Administrator'));
+        out(c.yellow('    PowerShell/terminal on Windows:  npx killm for 1h --web'));
+    }
+    out();
+    out(c.dim('  note: browsers cache DNS and "Secure DNS" (DoH) bypasses the hosts') +
+        '\n' +
+        c.dim('  file entirely — restart the browser / disable Secure DNS if needed.'));
+    out();
+    out(c.yellow('  ⚠ keep this process running — killm lifts the block when the timer'));
+    out(c.yellow('    ends or you press Ctrl+C / close the terminal. If it dies harder'));
+    out(c.yellow('    than that (kill -9, crash, shutdown), the block stays in place'));
+    out(c.yellow('    until you run any killm command again, e.g.  killm --restore'));
     out();
     let timer = null;
     let ticker = null;
@@ -123,6 +164,11 @@ async function runBlock(parsed) {
             clearTimeout(timer);
         if (ticker)
             clearInterval(ticker);
+        if (firewallActive) {
+            // Fire and forget: rules are tagged, so a missed removal here is still
+            // recoverable via "killm --restore".
+            void firewall.removeFirewall().catch(() => { });
+        }
         try {
             const removed = hosts.removeBlock();
             void hosts.flushDns(); // fire and forget on the way out
@@ -167,6 +213,9 @@ async function runBlock(parsed) {
         };
         process.once('SIGINT', () => onSignal('interrupted'));
         process.once('SIGTERM', () => onSignal('terminated'));
+        // Closing the terminal window sends SIGHUP; without this handler Node
+        // dies without cleanup and the block is stranded in the hosts file.
+        process.once('SIGHUP', () => onSignal('terminal closed'));
     });
     return 0;
 }
@@ -192,9 +241,31 @@ export async function main(argv) {
             out(VERSION);
             return 0;
         case 'status': {
+            const expiry = hosts.blockExpiry();
+            const expired = expiry !== null && expiry.getTime() <= Date.now();
+            if (expired) {
+                // A previous run was killed before it could clean up. Heal it now.
+                try {
+                    hosts.clearExpiredBlock();
+                    await hosts.flushDns();
+                    out(c.green('killm: no block active.'));
+                    out(c.dim('(cleaned up an expired block left behind by a previous run)'));
+                    return 0;
+                }
+                catch {
+                    err(c.yellow('killm: an EXPIRED block is still stuck in the hosts file.'));
+                    err('  Clean it up with elevated privileges:  sudo npx killm --restore');
+                    return 1;
+                }
+            }
             if (hosts.isBlocked()) {
                 out(c.yellow('killm: a block is currently ACTIVE.'));
-                out(c.dim('Run "killm --restore" to lift it.'));
+                if (expiry) {
+                    out(c.dim(`Scheduled to lift at ${expiry.toLocaleString()}.`));
+                    out(c.dim('If the killm process that created it is no longer running, it will not\n' +
+                        'lift itself on time — but any later killm command cleans it up once expired.'));
+                }
+                out(c.dim('Run "killm --restore" to lift it now.'));
             }
             else {
                 out(c.green('killm: no block active.'));
@@ -217,6 +288,13 @@ export async function main(argv) {
             try {
                 const removed = hosts.removeBlock();
                 await hosts.flushDns();
+                // Always sweep firewall rules too: they are tagged "killm", so this
+                // also cleans up after a crashed --firewall run. Harmless when none
+                // exist or the platform is unsupported. Skipped under the test
+                // override so tests never touch the real firewall.
+                if (!process.env.KILLM_HOSTS_PATH) {
+                    await firewall.removeFirewall().catch(() => { });
+                }
                 out(removed
                     ? c.green('killm: block lifted. Access restored.')
                     : c.dim('killm: no block was active.'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killm",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Temporarily block your machine from reaching LLM services to curb AI dependency. npx killm for 1h --agents",
   "bin": {
     "killm": "dist/src/bin.js"
@@ -15,7 +15,7 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "pretest": "npm run build",
-    "test": "node --test dist/test/duration.test.js dist/test/targets.test.js dist/test/cli.test.js dist/test/hosts.test.js dist/test/e2e.test.js",
+    "test": "node --test dist/test/duration.test.js dist/test/targets.test.js dist/test/cli.test.js dist/test/hosts.test.js dist/test/firewall.test.js dist/test/e2e.test.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",