macwarden 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## 1.0.1 (2026-10-08)
+
+Fixes found in the live field check against LND 0.20.0 (Polar, regtest):
+
+- `watch` fails with exit 4 and names the gRPC endpoint it tried (and how it was chosen) when no session ever registers. Before, an unreachable endpoint was retried quietly and the run ended with exit 0 and "watched 0 calls". Reconnecting with backoff now applies only after a session has registered once.
+- `inventory` shows macwarden's own credential as itself instead of "unknown", in the text output, the JSON flags and the access-review report (where it still appears under periodic access review).
+- `inventory --verify` reports a canary as "canary: verifiable only while watch runs" instead of "error", without asking LND.
+- `respond` aligns its text table columns.
+- A triggered canary is unmistakable. `watch` records the canary guard's denied uses apart from ordinary usage (`canaryUses` in the usage file); `inventory` starts that row's status with "CANARY TRIGGERED <n> times, last <time>: assume this credential's location is compromised", adds the `canary-triggered` flag to the JSON row (with `canary: {uses, firstUse, lastUse}`), and ends the text output with a line naming every triggered canary. `inventory --report` flags it and opens its control observations with "Incident response". Before, a used canary read "active; last used <time> (1 calls)", the same as normal use.
+- `recommend` says how long usage was observed. `watch` now records its registered time per node (`coverage` in the usage file), and `recommend` prints `observed for <duration>`. Under 7 days, it warns `short-observation` (rarely used methods such as payments may be missing) and withholds the narrowing command unless `--accept-short-observation` is given. Before, a one-minute watch was enough to print a bake command that would have dropped a payment credential's payment methods. Usage files from 1.0.0 have no coverage record and count as short.
+- GitHub Actions: `actions/checkout` and `actions/setup-node` moved to v5 (Node 24 runtime); GitHub has deprecated Node 20 for actions.
+
+## 1.0.0 (2026-10-08)
+
+First production release. It adds runtime visibility (`watch`, canaries, `recommend`), incident response (`respond`), access-review evidence and CI-native scanning to the 1.0.0-rc.1 command set, and closes every finding of the 2026-10-08 deep audit ([report](docs/reviews/2026-10-08-deep-audit.md)). Validated with complete Windows and unprivileged Linux suites, every pinned-regtest LND reference, leak checks and independent reviews. The real-node field check is in [docs/field-check.md](docs/field-check.md).
+
+
+Audit fixes and hardening (2026-10-08):
+
+- Output is rendered in bounded chunks and written with stdout backpressure, so a very large scan no longer builds one string that can exceed V8's limit. A closed stdout or stderr pipe (`| head`) stops output quietly and keeps the computed exit status instead of reporting an internal error.
+- A BakeMacaroon or DeleteMacaroonID request that gets no complete response (timeout, reset, cancellation) is treated as an unknown outcome: exit 7 with the pending record kept and an exact recovery command, never "nothing changed". Recovery commands print absolute paths.
+- Registry: a failed lock acquisition no longer leaves a stale lock; saves sync the directory on POSIX; validation is linear in the number of entries; leftover temporary files from killed saves are removed under the lock.
+- Windows `--out`: the credential is written only through an exclusive handle opened after the owner-only ACL is applied, so a handle opened before the restriction cannot read it.
+- `scan --git-history` refuses repository locations off the local file system (gitfile, commondir, alternates and config includes pointing to network or device paths) before git runs; a shallow clone fails with exit 3 unless `--allow-shallow`; history memory is bounded; SIGINT/SIGTERM stop a scan (exit 6) and kill git.
+- Credential recognition finds grouped base64 runs in linear time: a crafted 200 KB caveat took 52 s to `inspect` and now takes 0.15 s.
+- `scan` scales: known NWC secret redaction, ignore-file matching, read buffers and per-line work are linear; a 200,000-file tree scans in about 15 s instead of 384 s.
+- `--help` lists the commands and `<command> --help` prints its synopsis; refusals name the flag and the rule; `--fail-on` accepts any case.
+- `rules/gitleaks.toml` extends gitleaks' default rules (it replaced them before) and adds keyword prefilters; a pre-commit hook definition ships in `.pre-commit-hooks.yaml`.
+- `inventory` shows an EXPIRES column with expired and expiring flags; `--expiring-within <n>(m|h|d)` exits 1 for a cron reminder. `scan` text marks expired credentials.
+- JSON schemas for every command's `--json` output in `schemas/output/`, shipped in the package and checked against real outputs in the tests.
+- The Windows process-domain query passes an explicit temp directory, defaulting to the system Temp folder in service environments without TEMP or TMP.
+- Package metadata and the (disabled) release workflow are ready for npm trusted publishing; prereleases publish with the `next` tag.
+
+Features (2026-10-07 and 2026-10-08):
+
+- `scan --format sarif|github` for CI: a SARIF 2.1.0 log for GitHub code scanning and GitHub Actions annotations, both without matched text. `--format json` equals `--json`.
+- `scan --agent-configs` scans the configuration locations of AI agents and MCP clients and marks credentials found inside MCP server entries (`context: "mcp-config"`).
+- `rules/trufflehog.yaml`: the four detectors as TruffleHog custom detectors, with the same regexes as SPEC and the gitleaks pack.
+- `scan --git-history` scans every blob committed on any ref, so a credential that was committed and later deleted is still found. Local git only, offline and read-only.
+- `inspect` decodes Nostr Wallet Connect URIs offline: wallet and client public keys, relays, lud16 and fingerprint, counted as SPEND. The secret is never shown; a relay, lud16 or wallet key that embeds it is refused. Legacy `nostrwalletconnect:` schemes are decoded by `inspect` and detected by `scan` and the gitleaks rule.
+- New offline `attenuate` command adds expiry or IP caveats to a copy of a macaroon. The copy shares the original root key ID, and the command says so.
+- New `watch` command: a read-only LND RPC middleware (gRPC) that attributes every authenticated call to a credential ID, root key ID and registry label, records last use for `inventory`, and guards canary macaroons.
+- `bake --canary` bakes a decoy that LND refuses unless `watch` runs; with `watch` running, every use its permissions allow is denied and alerted in the same call.
+- `inventory` text output lines its columns up under the headers.
+- `watch` canary alerting is rate-limited: every use is still denied, but each canary raises at most one alert per 10 seconds plus a counted summary, and at most one `--alert-command` runs at a time. Previously a flood of canary uses spawned one alert process per use and could exhaust the host.
+- Red-team hardening before release, each item reproduced with a probe and covered by a test:
+  - `watch`: canary alerts cannot be suppressed by bursts or invented conditions; every bound on the middleware stream (unread feedback, frame size, registration and stall deadlines, method and macaroon field sizes, reconnect backoff) is enforced over real HTTP/2; feedback stays under 100 ms p99 at 100,000 calls/s; output survives a slow or stalled reader on Linux; alert commands and their children are always reaped; the lock survives crashes, container restarts and start races.
+  - `recommend` refuses to print a narrowing command when usage may be incomplete or broader than the credential.
+  - `respond` leaves canaries alone, lists root key IDs the registry marks revoked but LND still holds, scopes every proof to its own credential, flags credentials that can bake, and refuses tampered replacement links, chains and cycles.
+  - `scan` and `inspect` bound macaroon decoding (a crafted 61 KB file took two minutes and 1.3 GB; now milliseconds and refused), report a credential added at many history paths once with a count, enforce a findings limit, and never print a line that GitHub Actions or a terminal could read as a command or reordered text.
+  - Printed commands quote safely for POSIX shells and PowerShell, including curly quotes.
+- New `recommend` command: least-privilege permissions and exact methods from observed usage, with the narrowing commands.
+- `scan` reads files concurrently with a fixed bound and unchanged output order.
+- New `respond` command: after a suspected leak, stage replacements for every registered credential in one confirmed batch, then `--finish` revokes the old root key IDs with per-credential proof (old rejected, new accepted). Resumable; unknown IDs and root key ID 0 are reported with guidance, never touched.
+- `inventory --report markdown|csv|json [--out <file>]` exports access-review evidence with control observations, last use from `watch` and a reviewer sign-off.
+- On Windows, owner-only output files are granted to the current user SID, with the account name as fallback.
+
+## 1.0.0-rc.1 (prerelease candidate, superseded by 1.0.0)
+
+- Prepare candidate metadata and the operator guide for replacing default macaroons.
+- Final local validation and readiness approval are pending: fresh complete Windows and unprivileged Linux suites, tarball and installed-command checks, all affected live regtest references, leak checks, independent reviews and a checkpoint-specific delegated decision must cover the exact candidate. Historical composite summaries do not establish final proof.
+- Production release remains pending the engineer's successful real-node field report for this version, resolution of any surprises, and publication. Hosted Actions remain disabled; no macOS, hosted CI, publication, npm provenance or real-node validation is claimed.
+
+## 0.2.0 (local candidate; validation and approval pending)
+
+- Add the registry and online `inventory`, verified `bake`, individual `revoke`, and two-step `rotate` commands, including dry-run and recovery paths.
+- Document dedicated session credentials and the admin-equivalent `macaroon:generate` permission.
+- Prepare an actual local package for Windows and unprivileged Linux validation and independent review. Readiness approval is pending; hosted Actions remain disabled. No publication, macOS, hosted CI, npm provenance or real-node validation is claimed.
+
+## 0.1.0
+
+- Prepare the offline `inspect` and `scan` commands and the gitleaks rule pack for a local release artifact.
+- Validate the package contents, fresh build, installed commands and credential leak checks locally on Windows and unprivileged Linux before a release decision. GitHub Actions remain disabled; this record does not establish macOS, hosted CI, publication or npm provenance.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 macwarden 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,3 +1,186 @@
-# Temporary Holding Version
+# macwarden
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Credential control for LND: see every macaroon, find the leaked ones, revoke and rotate without locking yourself out.**
+
+macwarden is a command-line tool for teams that run LND behind BTCPay Server, LNbits, RTL, ThunderHub, their own backend or an AI agent. It keeps a record of every macaroon you issue, gives each one its own revocable root key, finds credentials that leaked into code, CI or agent configs, and walks you through an incident with proof that the old credentials are dead.
+
+It is a single Node.js CLI. It talks only to your own LND node, sends no telemetry, and never prints a credential: a credential only ever appears as a short SHA-256 fingerprint.
+
+```text
+$ macwarden inventory --verify
+node 03f2a1c97b5e4d0e8a6b9f31c2d47e5a0b8c6d2e9f1a3b5c7d9e0f2a4b6c8d0e1f (shop-node) mainnet
+ROOT KEY ID  LABEL      GRADE    AGE  EXPIRES     STATUS
+0            —          —        —    —           default root key: cannot be individually revoked
+4294967341   btcpay     RECEIVE  41d  —           active; accepted; last used 2026-10-08T09:12:44Z (18324 calls)
+4294967342   lnbits     SPEND    12d  2026-10-26  active; accepted; expires in 17d; rotate with: macwarden rotate lnbits
+4294967355   ci-reader  READ     3d   2026-10-07  active; expired; revoke with: macwarden revoke ci-reader
+9187201950   —          —        —    —           unknown — not in this registry (another tool or operator may own it)
+```
+
+
+## Why it exists
+
+In August 2026 an unauthenticated flaw in BTCPay Server let attackers download LND `.macaroon` files, and funds were stolen ([advisory](https://blog.btcpayserver.org/security-advisory-btcpay-server-2-4-2/)). The fix closed the hole, but it could not invalidate the stolen files. Operators had to work out by hand which credentials existed, which apps used them, and how to replace them without breaking payments.
+
+That is hard with LND alone:
+
+- **LND keeps no record of what it issued.** `listmacaroonids` returns bare numbers. Who holds which macaroon is up to you ([lnd#10594](https://github.com/lightningnetwork/lnd/issues/10594)).
+- **Most macaroons cannot be revoked one at a time.** Anything baked without `--root_key_id`, including `admin.macaroon`, shares root key 0, which LND will not delete.
+- **Rotation is easy to get wrong.** Operators have locked themselves out by deleting `macaroons.db` or renaming files ([btcpayserver-docker#1112](https://github.com/btcpayserver/btcpayserver-docker/issues/1112), [lnd#11049](https://github.com/lightningnetwork/lnd/issues/11049)).
+- **Secret scanners ignore Lightning credentials.** gitleaks, TruffleHog and GitHub secret scanning have no rule for macaroons, `lndconnect://` URIs or NWC connection strings.
+
+## What it does
+
+### Know what you have
+
+- `inventory` lists every root key ID on the node, matched against macwarden's registry: owner label, permission grade, age, expiry, last use, and flags for anything unknown, expired or still on root key 0. `--verify` asks LND whether each recorded macaroon is still accepted. `--expiring-within 14d` exits 1 for a cron reminder.
+- `inspect` decodes a macaroon, `lndconnect://` URI or Nostr Wallet Connect string offline and grades it `ADMIN`, `SPEND`, `OPERATE`, `RECEIVE` or `READ`.
+- `watch` registers a read-only LND RPC middleware and attributes every call to the credential that made it, without storing macaroon bytes. `inventory` then shows when each credential was last used.
+
+### Find leaks before someone else does
+
+- `scan` finds macaroons, `lndconnect://` URIs and NWC strings in files and directories, and `--fail-on <grade>` fails a build.
+- `--git-history` also scans every blob ever committed on any branch, so a credential that was committed and later deleted is still found.
+- `--agent-configs` checks the files where AI agents and MCP clients keep credentials: Claude, Cursor, VS Code, Windsurf, Continue, Gemini CLI, Codex, Zed, lnget.
+- `--format sarif` feeds GitHub code scanning; `--format github` gives inline annotations on any plan. Rule packs for gitleaks and TruffleHog are included.
+
+### Issue only what each app needs
+
+- `bake` creates one macaroon per app, each on its own fresh root key ID so it can be revoked alone, from presets (`read-only`, `invoice-only`, `pay-only`, `btcpay`) or explicit permissions, with an optional expiry. LND verifies it before it is written.
+- `recommend` reads what `watch` observed and prints the smallest permission set a credential actually needs, with the commands to narrow it. It says how long usage was observed; under 7 days it warns that rarely used methods (such as payments) may be missing and withholds the narrowing command unless you pass `--accept-short-observation`.
+- `attenuate` adds an expiry or IP lock to a copy of a macaroon offline.
+
+### Change credentials safely
+
+- `rotate` works in two steps. It bakes and verifies a replacement first and changes nothing else; you switch the app; `rotate --finish` revokes the old credential and confirms LND rejects it. Until you finish, the old one keeps working.
+- `revoke` deletes a credential's root key ID and proves LND now rejects it.
+- Every command that changes the node has `--dry-run`. `revoke`, `rotate --finish` and `respond` ask you to type a confirmation. An interrupted run prints the exact command that completes or undoes it.
+
+### Respond to an incident
+
+- `respond --out-dir <dir>` stages a replacement for every registered credential in one confirmed batch. After the apps are switched, `respond --finish` revokes the old root key IDs and reports, for each credential, proof that the old one is rejected and the new one accepted. It explains what to do about root key 0, which LND cannot revoke on its own. Canaries are never rotated into ordinary credentials, IDs the registry calls revoked but LND still holds are flagged, and if a credential that can bake may have leaked it says so plainly: only regenerating all root keys removes what such a credential could have created.
+- `bake --canary` creates a decoy credential. While `watch` runs, every use its permissions allow is denied and raises an alert within the same call. Put it where a thief would look.
+- `inventory --report markdown|csv|json` writes an access-review record (every credential, its owner, permissions, expiry, last use and review flags, with a sign-off section) for SOC 2, ISO 27001 or internal reviews. It is evidence for a reviewer, not a compliance claim.
+
+## Quick start
+
+macwarden needs Node.js 22.12 or later.
+
+```sh
+npm i -g macwarden@1.0.1
+```
+
+On production hosts, pin the exact version as above rather than installing the latest, and run `npm audit signatures` in a project that depends on macwarden to check the registry signatures of what you installed.
+
+### Offline: check a repository
+
+No node and no credentials needed:
+
+```sh
+macwarden scan . --git-history --fail-on READ
+```
+
+It exits 1 if it finds a credential at or above the grade you set, 0 if it finds none. To accept a known test fixture, add its fingerprint to `.macwardenignore`.
+
+### In CI
+
+```yaml
+- uses: actions/checkout@v5
+  with:
+    fetch-depth: 0
+- run: npx --yes macwarden@1.0.1 scan . --git-history --fail-on READ --format github
+```
+
+[docs/ci-integration.md](docs/ci-integration.md) has a SARIF workflow for GitHub code scanning, the pre-commit hook and the gitleaks and TruffleHog rule packs.
+
+### Online: take control of a node
+
+macwarden runs with a macaroon of its own. Because it can bake macaroons, that credential is admin-equivalent, so make it short-lived and keep it out of application configs:
+
+```sh
+lncli bakemacaroon --root_key_id 123456789 --timeout 3600 \
+  --save_to ./macwarden-session.macaroon \
+  macaroon:generate macaroon:read macaroon:write info:read
+
+export MACWARDEN_LND_REST=127.0.0.1:8080
+export MACWARDEN_TLS_CERT=~/.lnd/tls.cert
+export MACWARDEN_MACAROON=./macwarden-session.macaroon
+
+macwarden inventory --verify
+macwarden bake --label btcpay --preset btcpay --out ./btcpay.macaroon
+macwarden rotate btcpay --out ./btcpay-next.macaroon
+# switch BTCPay to btcpay-next.macaroon, then:
+macwarden rotate btcpay --finish
+```
+
+Pick an unused root key ID (check `lncli listmacaroonids`), and run `lncli deletemacaroonid 123456789` when the session is over. To move existing apps off `admin.macaroon` and root key 0, follow [Replacing the default macaroons](docs/replacing-default-macaroons.md). It covers the maintenance window, the one step only you can do, and how to confirm nothing is left behind.
+
+`macwarden --help` lists every command; `macwarden <command> --help` shows its options. Every command accepts `--json` and prints one document whose shape is published as a JSON Schema in `schemas/output/`.
+
+## Safety guarantees
+
+These are enforced in code and covered by tests. [SECURITY.md](SECURITY.md) lists them as rules SAFE-01 to SAFE-11:
+
+- It never prints, logs or stores credential bytes. The only file that ever holds a credential is one you asked it to write with `--out`, created owner-only and never overwritten.
+- It never calls `changepassword`, never deletes root key ID 0, and never reads or writes `macaroons.db`, wallet passwords, seeds or TLS keys.
+- A rotation leaves the old credential valid until you confirm the switch. A failure at any step before that changes nothing you depend on.
+- When the outcome of a change is uncertain (a timeout, a dropped connection), it says so, exits 7 and prints the command to reconcile. It never reports "nothing changed" without proof.
+- `inspect` and `scan` are offline. The only network peer is your LND node, with TLS pinned to its certificate. There is no telemetry.
+
+## Compatibility
+
+| | |
+| --- | --- |
+| LND | 0.21.x. Every online command is tested against a pinned LND v0.21.4-beta regtest node. |
+| Platforms | Linux and Windows, tested on every change. macOS should work but is not tested. |
+| Node.js | 22.12 or later. No runtime dependencies. |
+| Transport | REST over HTTPS; `watch` uses gRPC. For a Tor-only node, tunnel to localhost over SSH. |
+
+LND only: Core Lightning runes, LNbits keys, Eclair and LDK are not supported. Nostr Wallet Connect strings are decoded and found by `scan`, but NWC connections are revoked in the wallet service.
+
+## How it compares
+
+| | `lncli` | Lightning Labs macaroon-bakery | macwarden |
+| --- | --- | --- | --- |
+| Decode and grade permissions offline | `printmacaroon` | `--inspect` | `inspect`, with a risk grade |
+| Bake least-privilege macaroons | `bakemacaroon` | role presets | presets, each on its own root key |
+| Record who got what | no | no | registry and `inventory` |
+| Revoke one macaroon | if you tracked its root key ID | no | `revoke`, verified |
+| Rotate without lockout | by hand | no | `rotate`, verified at both steps |
+| Know when a credential was last used | no | no | `watch` |
+| Find leaked credentials | no | no | `scan`, git history, agent configs, SARIF |
+| Incident response with proof | no | no | `respond` |
+
+Everything macwarden does online can be done by hand with `lncli`. What it adds is the record-keeping, the verification after every change, and an order of operations that cannot leave you locked out. For a single agent that needs one scoped macaroon, Lightning Labs' script is a good fit. Spending limits per app belong in Lightning Terminal accounts. NWC budgets belong in your wallet service, such as Alby Hub.
+
+## Limits
+
+- A clean `scan` is not proof that nothing leaked. Encrypted, archived or unusually encoded credentials can be missed, and git history covers only what is present in your local clone.
+- Revoking a credential blocks new requests. Streams opened before the revoke, such as an invoice subscription, stay open until they disconnect; restart LND if a compromised credential may hold one.
+- While `watch` is registered, LND waits for it on every RPC. Run it as a supervised service and never enable `rpcmiddleware.addmandatory`. Its own work is bounded whatever callers do: canary alerts are rate-limited, at most one alert command runs (killed after 12 s), and usage data keeps at most 20,000 records.
+- On nodes run with `--no-macaroons`, stateless init or a remote signer, macwarden sees only part of the picture.
+
+## Documentation
+
+- [Replacing the default macaroons](docs/replacing-default-macaroons.md): the operator procedure for moving every app onto its own macaroon
+- [CI integration](docs/ci-integration.md): GitHub Actions, SARIF, pre-commit, gitleaks and TruffleHog
+- [Field check](docs/field-check.md): a short, safe procedure to confirm a release against your own node
+- [SPEC.md](SPEC.md): every command, flag, grade, exit code and output format
+- [SECURITY.md](SECURITY.md): the SAFE rules and threat model
+- [ARCHITECTURE.md](ARCHITECTURE.md): how it is built
+- [CHANGELOG.md](CHANGELOG.md): release notes
+
+## Development
+
+```sh
+npm ci
+npm run build
+npm test            # product tests
+npm run test:harness
+```
+
+Online behaviour is tested against a pinned regtest LND in Docker: `npm run fixture:up`, `npm run test:oracle`, `npm run fixture:down`. `npm run test:full` runs everything on the current platform. Changes go through the checkpoint process in [HELIX.md](HELIX.md), with roles in [AGENTS.md](AGENTS.md), milestones in [PLAN.md](PLAN.md) and operating notes in [RUNBOOK.md](RUNBOOK.md). Checkpoint contracts and validation tooling live in [tools/validation/](tools/validation/).
+
+## Security and licence
+
+Source and issues: https://github.com/ZilverZtream/macwarden. Report vulnerabilities through GitHub private vulnerability reporting rather than a public issue; see [SECURITY.md](SECURITY.md). macwarden is released under the MIT licence.

package/SECURITY.md

@@ -0,0 +1,104 @@
+# Security
+
+This file defines the security requirements for macwarden.
+
+## What macwarden handles
+
+macwarden works with LND macaroons. A macaroon is a bearer credential: whoever holds the bytes has its permissions, with no further check. An `admin.macaroon` (or any macaroon that can spend or bake) is enough to move a node's funds.
+
+Why this matters now:
+
+- The [BTCPay Server 2.4.2 advisory](https://blog.btcpayserver.org/security-advisory-btcpay-server-2-4-2/) (2026-08-07) describes an issue that "could allow an unauthenticated remote attacker to obtain `.macaroon` credential files for LND", which "could be used to take control of an LND node and move funds". It states "attackers exploited this vulnerability. Users were affected and funds were stolen", and advises: "If you use LND, treat its credentials as potentially exposed".
+- Rotation itself has locked operators out. In [btcpayserver-docker#1112](https://github.com/btcpayserver/btcpayserver-docker/issues/1112) rotation deleted `macaroons.db` and a later `changepassword` left a wallet permanently locked ("LND changes the wallet passphrase before touching the macaroon root key, so a failure on the second step leaves the passphrase already changed"). In [lnd#11049](https://github.com/lightningnetwork/lnd/issues/11049) renaming `admin.macaroon` and `macaroons.db` left LND stuck in `WAITING_TO_START`.
+
+So macwarden must never become a new leak path, and must never take the risky rotation path that caused those lock-outs.
+
+## Safety rules
+
+These IDs are referenced from SPEC.md. Do not renumber.
+
+| ID | Rule | How it is tested or enforced |
+|---|---|---|
+| SAFE-01 | Never print, log, or store macaroon bytes, hex or base64. Fingerprints only. Applies to errors, warnings, crashes and `--json` output too. (The single exception is the macaroon file that `bake`, `rotate` or the offline `attenuate` writes to `--out`, which is the product. The `attenuate --out` file is created through the same exclusive, owner-only writer.) | All rendering goes through the `output` module; process-level handlers route crashes through it. A leak test plants a sentinel macaroon and asserts its raw bytes (as UTF-8 and latin1), hex (both cases), base64 and base64url (padded and unpadded) appear in no stdout, stderr, log, registry, error output or other written file across every command, including a crash forced mid-request; it excludes exactly the `--out` file, including the `attenuate --out` copy. |
+| SAFE-02 | Never call `changepassword`; never read or write `macaroons.db`, wallet password files, seeds, TLS keys. | The `lnd` adapter exposes no `changepassword` call; a test asserts the adapter's endpoint list. `scan` never opens these names (case-insensitive, also as directory names); a test asserts it with an fs spy. |
+| SAFE-03 | Never delete root key ID 0. | `revoke` and `rotate` refuse ID 0 (as an argument or as a `--target-file`'s ID) before any network call; the adapter refuses it again. Unit and integration tests for both layers. |
+| SAFE-04 | Rotation is two invocations: **stage** (bake → verify new) → operator switches the app → **finish** (confirm → revoke old → verify old rejected). A failure anywhere before the revoke leaves the old credential valid. | Failure-injection cases 1–8 in PLAN.md M5 (faulty adapter in unit tests, real faults against the fixture in integration tests) assert with the `lncli` acceptance probe that the old macaroon is still accepted unless the finish's DeleteMacaroonID had completed. |
+| SAFE-05 | Every mutating command (`bake`, `revoke`, `rotate`) supports `--dry-run`; `revoke` and `rotate --finish` require typed confirmation unless `--yes`. Rotation stage relying on permissions unproven by the old credential requires typed informed approval showing the exact grade and permissions before lock, reservation or issue; stage --yes does not authorize this fallback. | Integration tests: `--dry-run` leaves LND's root key IDs, the registry and the `--out` path unchanged; without `--yes`, a declined, wrong or missing (non-TTY) confirmation changes nothing. |
+| SAFE-06 | Registry and all outputs are free of secrets. The registry is `0600` in a `0700` directory; macaroon files are written owner-only. Stale-lock recovery requires same-host dead-owner and pathname identity proof; competing owners are preserved. Failed owned lock/output cleanup is visible and reports exit 7 after possible mutation while retaining any primary error. On Windows `--out` is restricted to the current user with `icacls`; if that fails the command warns that the file inherits the folder's permissions. Bytes are written only through an exclusive (share mode 0) handle opened after the restriction, so no handle opened before it can read them; if another handle exists the command fails without writing. | Leak test covers the registry file. Tests check modes `0600`/`0700` on Linux/macOS; on Windows (CI) the `icacls` call is asserted and its failure produces warning `acl-best-effort`; a real-Windows test opens a handle before the restriction and proves the command fails with no bytes readable through it. |
+| SAFE-07 | `inspect` and `scan` are offline and read-only. | Tests run them with networking stubbed to throw and on read-only fixture directories; file mtimes and contents are unchanged afterwards. |
+| SAFE-08 | No telemetry; the only network peer is the configured LND node; TLS certificate verification is on by default. | Code review rule: the `lnd` adapter is the only module that opens network connections (it uses `node:https`). Integration test: a wrong TLS cert is rejected. |
+| SAFE-09 | macwarden's own credential should be a dedicated macaroon; the docs must state plainly that the ability to bake is admin-equivalent, so that macaroon must be protected like `admin.macaroon`. | Documented below and in the README; a unit test asserts `inspect` grades any macaroon holding `macaroon:generate` as `ADMIN`; online commands warn `own-root-key-0`. |
+| SAFE-11 | `watch` is read-only toward the caller's data: the read-only middleware always accepts, the canary guard always denies, and nothing replaces an RPC response. Intercepted macaroons are decoded in memory to a credential ID and root key ID and dropped; payloads and gRPC metadata are never read; only credential IDs, root key IDs, method names, counts and times are written (`<registry>.usage.json`, owner-only). The own macaroon needs `macaroon:write`, which is admin-equivalent like `macaroon:generate` (SAFE-09). A stalled watcher delays and then fails node RPCs (SPEC Commands > 8), so event output never blocks the answers (bounded queue written off the event loop); never recommend `rpcmiddleware.addmandatory`. Zeroed after use: each received gRPC frame and the copied raw macaroon bytes. Not zeroed: the `Secret` wrapper's own copy and derived identifier bytes, which are unreferenced at once and left to garbage collection. The canary guard fails closed (unknown intercept types and internal errors deny); canaries carry only READ or RECEIVE permissions. Every resource an attacker can drive is bounded: alerts are rate-limited per registered canary (one per 10-second window plus a counted summary) and invented caveat conditions share one bucket; at most one alert command runs, killed (process group) 12 s after it starts; event output is a bounded queue that treats EAGAIN as backpressure; usage holds at most 20,000 records with least-recently-seen eviction, is written at most at 64 KiB/s on average, and the summary counts at most 10,000 credentials; shutdown persists usage and releases the lock before waiting at most 13 s for an alert command. Attribution runs behind a bounded queue that drops and counts work it cannot keep up with, so LND feedback latency is independent of the call rate; stream fields are capped (macaroon 64 KiB, method name and caveat condition 256 bytes) before they are copied; a session ends on a missing registration confirmation (30 s), a stalled message (60 s) or more than 16 MiB of unread feedback. Processes an alert command leaves behind are killed (POSIX process groups, 1 s after it exits and when watch stops; on Windows the tree is killed on timeout only). Output that cannot be delivered never keeps watch running: queued lines are dropped and counted and the process exits within a bounded time, non-zero when it had to be terminated. | Unit tests decide every intercept kind; leak tests assert caller macaroons never appear in events, alerts or the usage file; the regtest oracle proves attribution, canary denial, and unregistration on exit. |
+| SAFE-10 | Development and CI integration tests run against regtest only. (The released tool works on any network — it moves no funds.) | The test fixture starts its own regtest LND + bitcoind and aborts if `getinfo` reports any other network or a version not starting with `0.21.4-beta`. |
+
+## Threat model
+
+macwarden helps against:
+
+- **Over-privileged apps.** `inspect` and `inventory` show what each credential can do; `bake` issues least-privilege macaroons instead of handing out `admin.macaroon`.
+- **Unknown credentials.** `inventory` flags root key IDs LND has that the registry does not know; `inventory --verify` flags registered macaroons LND no longer accepts.
+- **Leaked credentials in repos, configs and backups.** `scan` finds macaroon files, embedded hex/base64 macaroons, `lndconnect://` URIs and NWC connection strings, and can fail a CI job.
+- **Unknown usage and silent leaks.** `watch` attributes every authenticated RPC to a credential and records last use; `recommend` narrows a credential to what it actually calls; a canary macaroon (`bake --canary`) is refused by LND unless `watch` runs, and while it runs every use is denied and alerted within the same call.
+- **Botched rotation.** `rotate` follows SAFE-04 and only ever revokes per-app root key IDs, never root key 0.
+- **Leaked credentials after an incident.** `respond` rotates every registered credential in one confirmed batch through `rotate` (SAFE-04 and SAFE-05 apply to each), then proves each old credential rejected and each replacement accepted. It never touches root key IDs it does not own and never calls `changepassword` (SAFE-02); for root key 0 it prints the manual LND procedure.
+- **A leaked credential that can bake, and a tampered registry, during an incident.** A holder of `macaroon:generate` can create credentials on any root key ID, including the replacements `respond` stages, so every `respond` proof is scoped to its own credential, credentials that can bake are listed and finished first, and the guidance says that only regenerating all root keys removes everything such a holder could have baked. `respond` and `rotate` treat a replacement link macwarden could not have written as tampering (exit 3), never rotate a canary into an ordinary credential, and list root key IDs the registry calls revoked but LND still holds. Registry evidence values are validated, and printed commands are quoted for POSIX shells and PowerShell, including PowerShell's curly single quotes.
+- **Missing review evidence.** `inventory --report` writes an access-review record from registry facts and LND root key IDs only, never credential bytes.
+- **Leaks reaching CI logs and code-scanning tools.** `scan --format sarif|github` reports only paths, kinds, grades and fingerprints, never matched text, so uploading the SARIF log or printing annotations exposes no credential.
+
+macwarden does not protect against:
+
+- **A compromised host.** An attacker on the machine running LND or macwarden can read the macaroons directly.
+- **Theft of the admin macaroon itself**, or of macwarden's own macaroon (see below).
+- **Streams that are already open.** Deleting a root key ID blocks new requests only. Streams opened earlier (e.g. `HtlcInterceptor`, `SubscribeInvoices`, REST WebSockets) keep running until they disconnect. New requests with this macaroon are now rejected. Streams opened before the revoke stay open until they disconnect; if the credential may be compromised, restart LND.
+- **Anything on root key ID 0.** `admin.macaroon`, `readonly.macaroon`, `invoice.macaroon` and anything else baked on ID 0 cannot be revoked individually. They stay valid until the operator rotates the root keys by hand. `changepassword --new_mac_root_key` regenerates **every** root key, not just ID 0: every macaroon ever baked becomes invalid, including macwarden-baked ones and macwarden's own. LND's docs also describe deleting `macaroons.db`. So the order is always: rotate the root keys first (in a maintenance window), then bake fresh per-app macaroons (PLAN.md M6). Moving apps first and rotating afterwards breaks every app.
+- **Nodes where macwarden's view is incomplete.** With `--no-macaroons` LND checks no macaroons, so macwarden's verification means nothing. With `--mac_root_key` (stateless init) macaroons can be baked offline and never appear in `inventory`. With a remote signer, the signer has its own macaroon store and must be inventoried separately. Other tools and operators can store root keys in the same LND store (Lightning Terminal is reported to; ARCHITECTURE.md assumption 12), which is why `revoke` needs `--unregistered` for IDs it did not issue.
+- **IP-restricted macaroons.** `bake` has no `--ip`: LND is reported to see REST clients as its REST proxy's address (ARCHITECTURE.md assumption 5), so an IP lock either breaks the app or accepts everyone.
+- **Other implementations.** CLN runes, Eclair and LDK are out of scope for v1.
+- **Secrets `scan` does not recognise.** Scanning is pattern-based. Text detectors only match macaroons with location `lnd`; line-wrapped, split, encrypted, archived or oddly encoded credentials can be missed or only flagged as `undecodable-candidate`; UTF-16 without a BOM is treated as binary; files over 5 MiB are skipped; git history is scanned only with `scan --git-history`, and only for history that still exists in the local repository (rewritten history, other clones and objects missing from a partial clone are not covered; a missing object fails the scan). A clean scan is not proof of no leak.
+
+Two facts to keep in mind:
+
+- **`macaroon:read` is a validity oracle.** It includes CheckMacaroonPermissions, so even an inventory-only macaroon can test whether a stolen macaroon is still valid.
+- **Fingerprints are linkable.** A fingerprint reveals nothing usable about the credential (no feasible preimage), but the same credential has the same fingerprint in every report, so reports can be correlated. A fingerprint changes when a caveat is added.
+
+## The credential macwarden runs with
+
+- Online commands need a macaroon. Use a **dedicated** one for macwarden, not `admin.macaroon`, so it can be revoked on its own. First-time setup may use `admin.macaroon`; every online command then warns `own-root-key-0`.
+- `bake` needs `macaroon:generate`. **Holding `macaroon:generate` is admin-equivalent**: it can bake a macaroon with any permission, including spending. Protect macwarden's macaroon exactly like `admin.macaroon`.
+- `revoke` and `rotate` also need `macaroon:write`, which can revoke any non-zero root key ID. macwarden refuses to revoke or rotate the root key ID it is itself using.
+- For `inventory` only, `info:read` and `macaroon:read` are enough. Do not give a read-only workflow a baking macaroon.
+- Do not store macwarden's macaroon in the repo or CI variables of the apps it manages. Run it from an operator machine or a locked-down admin host.
+
+Recommended: bake, use and revoke a short-lived session macaroon per session, on its own root key ID, with only `macaroon:generate macaroon:read macaroon:write info:read` and a one-hour `time-before`. `lncli bakemacaroon` defaults to root key ID 0, so pass an explicit `--root_key_id`:
+
+```sh
+ID=$(( (RANDOM << 30) | (RANDOM << 15) | RANDOM ))    # check it is not in `lncli listmacaroonids`
+lncli bakemacaroon --root_key_id "$ID" --timeout 3600 \
+  --save_to ./macwarden-session.macaroon \
+  macaroon:generate macaroon:read macaroon:write info:read
+macwarden inventory --macaroon ./macwarden-session.macaroon    # … this session's commands
+lncli deletemacaroonid "$ID"
+rm ./macwarden-session.macaroon
+```
+
+Check the flag names with `lncli bakemacaroon --help` on your LND version.
+
+## Installing
+
+- Version `1.0.0` is released (Owner decision 2026-10-08) after complete Windows and unprivileged Linux validation, pinned-regtest references, leak checks and independent review. A real-node field check ([docs/field-check.md](docs/field-check.md)) follows release. Hosted Actions remain disabled, and macOS is not tested. When the package is published through npm trusted publishing, it carries npm provenance that `npm audit signatures` can verify.
+- For online commands install a pinned version and check signatures: `npm i -g macwarden@<exact version>`, then `npm audit signatures`.
+- For the offline commands, `npx macwarden@<exact version> inspect …` is fine.
+
+## Development rules
+
+- No real credentials in issues, prompts, logs, commits or test snapshots. Never paste a real macaroon, `lndconnect://` URI or NWC string into an AI agent. Fixtures use throwaway regtest credentials generated by the test suite (SAFE-10).
+- Test vectors committed to the repo come from a disposable regtest node and are labelled as such. Read vectors by path and use fingerprints in reports, logs and commit messages. The repo's own `.macwardenignore` lists their fingerprints so `scan` of the repo stays clean.
+- Run gitleaks only with `--redact`; without it gitleaks prints and stores the matched credential.
+- A real credential that is ever exposed is treated as compromised: revoke it on the node and remove it from history; deleting the text is not enough.
+- The development process (checkpoints, gates, reviews) is in HELIX.md.
+
+## Reporting a vulnerability
+
+Use GitHub private vulnerability reporting: the repository's **Security** tab → **Report a vulnerability**. Do not open a public issue for a vulnerability.
+
+Please include the macwarden version, the command and flags used, and what you observed. Do not send real macaroons; a fingerprint or a regtest reproduction is enough.

package/dist/bin.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { main, completionStatus } from './cli.js';
+// watch runs unattended (systemd, CI). If its output can no longer be delivered (a pipe
+// that is never read), a write already handed to the operating system cannot be
+// cancelled: on Windows every write to an inherited pipe is synchronous, and a normal exit
+// waits for the blocked writer. So once watch has finished, a short unref'd deadline
+// terminates the process if it is still alive. With a reader that reads, the process exits
+// on its own before the deadline with its real status; when the deadline fires, the
+// non-zero exit (1 on Windows, SIGKILL on POSIX) reports that output was not delivered.
+// Other commands are not affected: their output is waited for in full.
+const WATCH_EXIT_GRACE_MS = 3_000;
+const status = await main(process.argv.slice(2));
+process.exitCode = completionStatus(status);
+if (process.argv[2] === 'watch')
+    setTimeout(() => process.kill(process.pid, 'SIGKILL'), WATCH_EXIT_GRACE_MS).unref();

package/dist/cancellation.js

@@ -0,0 +1 @@
+export {api0_withCancellation as withCancellation, api0_checkCancellation as checkCancellation, api0_cancellable as cancellable, api0_cancellationSignal as cancellationSignal, api0_cleanup as cleanup, api0_cleanupOutcome as cleanupOutcome, api0_Cancelled as Cancelled} from "./runtime.js";

package/dist/caveat-address.js

@@ -0,0 +1 @@
+export {api1_canonicalIp as canonicalIp, api1_canonicalCidr as canonicalCidr} from "./runtime.js";

package/dist/cli.js

@@ -0,0 +1 @@
+export {api2_writeChunks as writeChunks, api2_main as main, api2_completionStatus as completionStatus, api2_WATCH_SUMMARY_WRITE_MS as WATCH_SUMMARY_WRITE_MS} from "./runtime.js";

package/dist/command-result.js

@@ -0,0 +1 @@
+export {} from "./runtime.js";

package/dist/commands/attenuate.js

@@ -0,0 +1 @@
+export {api4_run as run, api4_attenuate as attenuate} from "../runtime.js";

package/dist/commands/bake/allocate.js

@@ -0,0 +1 @@
+export {api5_allocateRootKeyId as allocateRootKeyId} from "../../runtime.js";

package/dist/commands/bake/index.js

@@ -0,0 +1 @@
+export {api6_run as run, api6_bake as bake} from "../../runtime.js";

package/dist/commands/bake/write-out.js

@@ -0,0 +1 @@
+export {api7_reserveOut as reserveOut} from "../../runtime.js";

package/dist/commands/handlers.js

@@ -0,0 +1 @@
+export {api8_handlers as handlers} from "../runtime.js";

package/dist/commands/inspect.js

@@ -0,0 +1 @@
+export {api9_run as run, api9_inspect as inspect} from "../runtime.js";

package/dist/commands/inventory.js

@@ -0,0 +1 @@
+export {api10_run as run, api10_inventory as inventory} from "../runtime.js";

package/dist/commands/recommend.js

@@ -0,0 +1 @@
+export {api11_narrowLabel as narrowLabel, api11_run as run, api11_recommend as recommend, api11_SHORT_OBSERVATION_SECONDS as SHORT_OBSERVATION_SECONDS} from "../runtime.js";

package/dist/commands/respond.js

@@ -0,0 +1 @@
+export {api12_aggregateExit as aggregateExit, api12_run as run, api12_respond as respond, api12_ROOT_KEY_0_GUIDANCE as ROOT_KEY_0_GUIDANCE, api12_OWN_ON_ROOT_KEY_0 as OWN_ON_ROOT_KEY_0, api12_REVOKED_BUT_PRESENT_GUIDANCE as REVOKED_BUT_PRESENT_GUIDANCE, api12_BAKING_RISK_GUIDANCE as BAKING_RISK_GUIDANCE, api12_CUSTOM_CAVEAT_NOTE as CUSTOM_CAVEAT_NOTE, api12_UNKNOWN_GUIDANCE as UNKNOWN_GUIDANCE} from "../runtime.js";

package/dist/commands/revoke.js

@@ -0,0 +1 @@
+export {api13_run as run, api13_revoke as revoke} from "../runtime.js";

package/dist/commands/rotate.js

@@ -0,0 +1 @@
+export {api14_run as run, api14_rotate as rotate} from "../runtime.js";

package/dist/commands/scan.js

@@ -0,0 +1 @@
+export {api15_run as run} from "../runtime.js";

package/dist/commands/watch.js

@@ -0,0 +1 @@
+export {api16_lockOwnerGone as lockOwnerGone, api16_acquireLock as acquireLock, api16_run as run, api16_stdoutEvents as stdoutEvents, api16_watch as watch, api16_CANARY_RELOAD_MS as CANARY_RELOAD_MS} from "../runtime.js";

package/dist/credential-recognition.js

@@ -0,0 +1 @@
+export {api17_redactEncodedCredentials as redactEncodedCredentials} from "./runtime.js";

package/dist/decode/index.js

@@ -0,0 +1 @@
+export {api18_macaroonPacketRange as macaroonPacketRange, api18_macaroonSectionRange as macaroonSectionRange, api18_parseTimeBefore as parseTimeBefore, api18_canonicalMacaroonLength as canonicalMacaroonLength, api18_decodeMacaroon as decodeMacaroon, api18_macaroonId as macaroonId, api18_encodeMacaroon as encodeMacaroon, api18_addFirstPartyCaveat as addFirstPartyCaveat, api18_timeBeforeCondition as timeBeforeCondition, api18_validMacaroonIdentifier as validMacaroonIdentifier, api18_isNwcContainer as isNwcContainer, api18_decodeNwc as decodeNwc, api18_DecodeError as DecodeError} from "../runtime.js";

package/dist/decode/recognition.js

@@ -0,0 +1 @@
+export {api19_macaroonEnds as macaroonEnds} from "../runtime.js";

package/dist/environment.js

@@ -0,0 +1 @@
+export {api20_unsafeNodeDiagnostics as unsafeNodeDiagnostics} from "./runtime.js";

package/dist/errors.js

@@ -0,0 +1 @@
+export {api21_UsageError as UsageError, api21_InputError as InputError, api21_DecodeError as DecodeError, api21_LndError as LndError, api21_LndUncertainError as LndUncertainError} from "./runtime.js";

package/dist/grade/index.js

@@ -0,0 +1 @@
+export {api22_grade as grade, api22_describe as describe} from "../runtime.js";