macaroons: refresh the package README

[MPins]

Change Description

macaroons/README.md has drifted from the code. This refreshes it. No code changes, documentation only.

• Macaroons baked at startup. The README described only admin.macaroon, invoice.macaroon and readonly.macaroon. Every sub server compiled into the binary also bakes one of its own on first startup (router, signer, walletkit, chainnotifier, invoices), each with its own path flag. They are now listed with the permissions they carry, along with the note that no macaroon file is written to disk under --stateless_init.

• Permission example. The invoice.macaroon example was missing onchain:read. It now matches invoicePermissions in rpcserver.go.

• Constraints. The section stated that "there are currently two constraints implemented" and covered TimeoutConstraint and IPLockConstraint only. IPRangeLockConstraint and CustomConstraint have been around for several releases. The section now says what a constraint is (a first party caveat, which anyone holding the macaroon can append offline and which can only narrow what the macaroon allows), lists all four with the caveat condition each one encodes, and points at config_builder.go, where the checkers for the lnd specific conditions are registered.

• How constraints are applied. Adds examples for both bakemacaroon and constrainmacaroon, notes that --macaroontimeout is applied to every lncli call with a 60 second default as a basic anti-replay measure, and records that IPRangeLockConstraint is currently reachable only from Go code, since neither command registers a flag for it ([bug]: lncli --ip_range is unreachable and its implementation calls the wrong constraint #11127).

• Obsolete section. Drops "Upgrading from v0.8.0-beta or earlier", which is about upgrades to a release that is now many years old.

• Fixes gPRC in passing.

Steps to Test

Documentation only, so there is nothing to run. The claims can be checked against the code:

• grep -rn "MacPath\|MacFilename" --include=*.go lnrpc/ | grep -v _test for the sub server macaroon files and their path flags.
• grep -n -A 25 "invoicePermissions = " rpcserver.go for the permission example.
• ls macaroons/constraints.go and grep -n "func.*Constraint" macaroons/*.go for the four constraints.
• grep -n "Checker" config_builder.go for where the checkers are registered.

Pull Request Checklist

The change is documentation only: no tests, no logging, no new lncli commands. Lines wrap at 80, and the commit carries [skip ci] instead of a release notes entry, as the template allows for small changes.

[Lrifton92]

Nice cleanup — this fills a real gap, the old README only described the three default macaroons. I cross-checked the factual claims against the code and they hold up:

• Sub-server permissions all match: routerrpc → offchain:read/offchain:write (router_server.go), signrpc → signer:generate/signer:read, walletrpc → address + onchain read/write, chainrpc → onchain:read only (chain_server.go), invoicesrpc → invoices:read/invoices:write.
• The --macaroontimeout default of 60s and the "applied to every call" anti-replay note match cmd/commands/main.go (flag at :406, the 60s default is documented at :176-185).
• The IPRangeLockConstraint note is accurate: only --macaroonip is wired up (main.go:413), there's no CLI flag for the range variant.

One optional nit: in the sub-server list, the phrase "every sub server that is compiled into the binary bakes a macaroon of its own on first startup" is true for the ones that declare macaroon permissions, but it may read as if every registered sub-server writes a file. Might be worth a half-sentence clarifying it's the sub-servers with their own permission set. Non-blocking — the content itself is correct.