[MPins]

Change Description

Depends on #11117. The ProtectorConstraint bullet below documents the constraint that PR adds, so this one should be merged after it.

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. Five sub servers also bake one of their own on first startup when they are compiled in (router, signer, walletkit, chainnotifier, invoices), and four of those files can be pointed elsewhere with a command line option. They are now listed with the permissions they carry, along with what --stateless_init means for them: no file is written, and only the admin macaroon comes back over RPC.

• 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 every one of them with the caveat condition it 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).

• Protector constraint. Documents ProtectorConstraint from macaroons+rpcperms: add protector caveats to restrict RPC request fields #11117 alongside the other four constraints, including that only the profile name travels in the macaroon while the rules are compiled into lnd, and points at docs/macaroons.md for the available profiles.

• 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.

The ProtectorConstraint bullet can only be checked against the #11117 branch, where the constraint lives in macaroons/protector.go and its checker is registered in config_builder.go next to the other three.

[MPins]

@Lrifton92 thanks for checking the claims against the code rather than just the prose.

You are right that the sentence read too broadly, and looking into it turned up a mistake of my own, so both are fixed in the latest push:

• The list now says that five sub servers bake a macaroon of their own when they are compiled in, and that the others write no file. Those five are the ones with a macaroon filename of their own: router, signer, walletkit, chainnotifier and invoices.
• invoices.macaroon has no path option at all. Only --routermacaroonpath, --signermacaroonpath, --walletkitmacaroonpath and --notifiermacaroonpath exist; the invoices one is always read from the network directory (NetworkDir in lnrpc/invoicesrpc/config_active.go). The old sentence claimed each file could be overridden "with its own command line option", which was wrong.

[github-actions]

🟢 PR Severity: LOW

file-based classification | 1 file | 98 lines changed

🟢 Low (1 file)

• macaroons/README.md - documentation-only change (*.md file), no code touched

Analysis

The only file changed is macaroons/README.md. Although the macaroons/* package is normally classified as HIGH severity (auth/security), this PR only edits prose in the README, not any Go source. Per the classification rules, *.md files are explicitly LOW severity regardless of the package they document. No other files were touched, and the change is well under the thresholds for a severity bump (>20 files or >500 lines).

---

_{To override, add a severity-override-{critical,high,medium,low} label.}

[litbot-9000]

@Lrifton92: review reminder

[litbot-9000]

@Lrifton92: review reminder

[litbot-9000]

@Lrifton92: review reminder

[litbot-9000]

@Lrifton92: review reminder