Skip to content

Improve MacaroonWhitelist Structure and Permission Granularity #1841

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 13, 2025
Merged

Improve MacaroonWhitelist Structure and Permission Granularity #1841

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4094e8f
taprpc: simplify MacaroonWhitelist func code
ffranr Sep 29, 2025
cea2725
taprpc: separate universe proof courier permissions in MacaroonWhitelist
ffranr Oct 8, 2025
a7d6ebd
proof+taprpc: inline default macaroon whitelist logic
ffranr Oct 8, 2025
fe70d4f
proof: update stale universe proof courier comment
ffranr Oct 8, 2025
99c30a5
taprpc: add default permissions for MailboxInfo and Universe/Info
ffranr Oct 8, 2025
9b16515
docs: add release note
ffranr Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions docs/release-notes/release-notes-0.8.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Release Notes
- [Bug Fixes](#bug-fixes)
- [New Features](#new-features)
- [Functional Enhancements](#functional-enhancements)
- [RPC Additions](#rpc-additions)
- [tapcli Additions](#tapcli-additions)
- [Improvements](#improvements)
- [Functional Updates](#functional-updates)
- [RPC Updates](#rpc-updates)
- [tapcli Updates](#tapcli-updates)
- [Breaking Changes](#breaking-changes)
- [Performance Improvements](#performance-improvements)
- [Deprecations](#deprecations)
- [Technical and Architectural Updates](#technical-and-architectural-updates)
- [BIP/bLIP Spec Updates](#bipblip-spec-updates)
- [Testing](#testing)
- [Database](#database)
- [Code Health](#code-health)
- [Tooling and Documentation](#tooling-and-documentation)

# Bug Fixes

# New Features

## Functional Enhancements

## RPC Additions

## tapcli Additions

# Improvements

## Functional Updates

## RPC Updates

- [PR#1841](https://github.com/lightninglabs/taproot-assets/pull/1841): Remove
the defaultMacaroonWhitelist map and inline its entries directly
into the conditional logic within MacaroonWhitelist. This ensures that
access to previously always-available endpoints is now governed by
explicit user configuration (read/write/courier), improving permission
control and aligning with expected access restrictions.

- [PR#1841](https://github.com/lightninglabs/taproot-assets/pull/1841): Add
default RPC permissions for RPC endpoints universerpc.Universe/Info and
/authmailboxrpc.Mailbox/MailboxInfo.

## tapcli Updates

## Code Health

## Breaking Changes

## Performance Improvements

## Deprecations

# Technical and Architectural Updates

## BIP/bLIP Spec Updates

## Testing

## Database

## Code Health

## Tooling and Documentation

# Contributors (Alphabetical Order)
6 changes: 3 additions & 3 deletions proof/courier.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1316,9 +1316,9 @@ func (c *UniverseRpcCourier) ensureConnect(ctx context.Context) error {
c.mboxClient = mboxrpc.NewMailboxClient(conn)
c.rawConn = conn

// Make sure we initiate the connection. The GetInfo RPC method is in
// the base macaroon white list, so it doesn't require any
// authentication, independent of the universe's configuration.
// Ensure the connection is established by calling the `Info` RPC
// endpoint. This endpoint does not require authentication when the
// universe server is configured to act as a proof courier.
_, err = c.client.Info(ctx, &unirpc.InfoRequest{})
if err != nil {
// If we fail to connect, we'll close the connection and return
Expand Down
87 changes: 54 additions & 33 deletions taprpc/perms.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,10 @@ var (
Entity: "mint",
Action: "read",
}},
"/universerpc.Universe/Info": {{
Entity: "universe",
Action: "read",
}},
"/universerpc.Universe/MultiverseRoot": {{
Entity: "universe",
Action: "read",
Expand Down Expand Up @@ -339,22 +343,10 @@ var (
Entity: "mailbox",
Action: "read",
}},
"/authmailboxrpc.Mailbox/MailboxInfo": {{}},
}

// defaultMacaroonWhitelist defines a default set of RPC endpoints that
// don't require macaroons authentication.
//
// For now, these are the Universe related read/write methods. We permit
// InsertProof as a valid proof requires an on-chain transaction, so we
// gain a layer of DoS defense.
defaultMacaroonWhitelist = map[string]struct{}{
"/universerpc.Universe/AssetRoots": {},
"/universerpc.Universe/QueryAssetRoots": {},
"/universerpc.Universe/AssetLeafKeys": {},
"/universerpc.Universe/AssetLeaves": {},
"/universerpc.Universe/Info": {},
"/authmailboxrpc.Mailbox/MailboxInfo": {},
"/authmailboxrpc.Mailbox/MailboxInfo": {{
Entity: "mailbox",
Action: "read",
}},
}
)

Expand All @@ -364,34 +356,63 @@ func MacaroonWhitelist(allowUniPublicAccessRead bool,
allowUniPublicAccessWrite bool, allowPublicUniProofCourier bool,
allowPublicStats bool) map[string]struct{} {

// Make a copy of the default whitelist.
whitelist := make(map[string]struct{})
for k, v := range defaultMacaroonWhitelist {
whitelist[k] = v

// addEndpoints adds the given endpoints to the whitelist map.
addEndpoints := func(endpoints ...string) {
for _, endpoint := range endpoints {
whitelist[endpoint] = struct{}{}
}
}

// Conditionally whitelist universe server read methods.
// nolint: lll
if allowUniPublicAccessRead || allowPublicUniProofCourier {
whitelist["/universerpc.Universe/QueryProof"] = struct{}{}
whitelist["/universerpc.Universe/FetchSupplyCommit"] = struct{}{}
whitelist["/universerpc.Universe/FetchSupplyLeaves"] = struct{}{}
whitelist["/authmailboxrpc.Mailbox/ReceiveMessages"] = struct{}{}
if allowUniPublicAccessRead {
addEndpoints(
"/universerpc.Universe/Info",

"/universerpc.Universe/AssetRoots",
"/universerpc.Universe/QueryAssetRoots",
"/universerpc.Universe/AssetLeafKeys",
"/universerpc.Universe/AssetLeaves",
"/universerpc.Universe/QueryProof",

"/universerpc.Universe/FetchSupplyCommit",
"/universerpc.Universe/FetchSupplyLeaves",

"/authmailboxrpc.Mailbox/MailboxInfo",
"/authmailboxrpc.Mailbox/ReceiveMessages",
)
Comment on lines +370 to +384
Copy link

@gemini-code-assist gemini-code-assist bot Oct 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To improve maintainability and prevent typos, it's a good practice to define these RPC endpoint paths as constants instead of using string literals directly. This is especially useful as these paths are used in multiple places in this function and potentially elsewhere in the codebase.

You could define them in a const block at the package level, for example:

const (
	// Universe RPC methods.
	UniverseInfoPath            = "/universerpc.Universe/Info"
	UniverseAssetRootsPath      = "/universerpc.Universe/AssetRoots"
	UniverseQueryAssetRootsPath = "/universerpc.Universe/QueryAssetRoots"
	UniverseAssetLeafKeysPath   = "/universerpc.Universe/AssetLeafKeys"
	UniverseAssetLeavesPath     = "/universerpc.Universe/AssetLeaves"
	UniverseQueryProofPath      = "/universerpc.Universe/QueryProof"
	UniverseFetchSupplyCommitPath = "/universerpc.Universe/FetchSupplyCommit"
	UniverseFetchSupplyLeavesPath = "/universerpc.Universe/FetchSupplyLeaves"

	// Mailbox RPC methods.
	MailboxInfoPath           = "/authmailboxrpc.Mailbox/MailboxInfo"
	MailboxReceiveMessagesPath = "/authmailboxrpc.Mailbox/ReceiveMessages"
	// ... and so on for other paths.
)

Then you can use these constants throughout the function, which makes the code more robust and easier to read.

Suggested change
addEndpoints(
"/universerpc.Universe/Info",
"/universerpc.Universe/AssetRoots",
"/universerpc.Universe/QueryAssetRoots",
"/universerpc.Universe/AssetLeafKeys",
"/universerpc.Universe/AssetLeaves",
"/universerpc.Universe/QueryProof",
"/universerpc.Universe/FetchSupplyCommit",
"/universerpc.Universe/FetchSupplyLeaves",
"/authmailboxrpc.Mailbox/MailboxInfo",
"/authmailboxrpc.Mailbox/ReceiveMessages",
)
addEndpoints(
UniverseInfoPath,
UniverseAssetRootsPath,
UniverseQueryAssetRootsPath,
UniverseAssetLeafKeysPath,
UniverseAssetLeavesPath,
UniverseQueryProofPath,
UniverseFetchSupplyCommitPath,
UniverseFetchSupplyLeavesPath,
MailboxInfoPath,
MailboxReceiveMessagesPath,
)

}

// Conditionally whitelist universe server write methods.
// nolint: lll
if allowUniPublicAccessWrite || allowPublicUniProofCourier {
whitelist["/universerpc.Universe/InsertProof"] = struct{}{}
whitelist["/universerpc.Universe/InsertSupplyCommit"] = struct{}{}
whitelist["/authmailboxrpc.Mailbox/SendMessage"] = struct{}{}
if allowUniPublicAccessWrite {
addEndpoints(
"/universerpc.Universe/InsertProof",
"/universerpc.Universe/InsertSupplyCommit",
"/authmailboxrpc.Mailbox/SendMessage",
)
}

// Conditionally add public stats RPC endpoints to the whitelist.
if allowPublicStats {
whitelist["/universerpc.Universe/QueryAssetStats"] = struct{}{}
whitelist["/universerpc.Universe/UniverseStats"] = struct{}{}
whitelist["/universerpc.Universe/QueryEvents"] = struct{}{}
addEndpoints(
"/universerpc.Universe/QueryAssetStats",
"/universerpc.Universe/UniverseStats",
"/universerpc.Universe/QueryEvents",
)
}

// Conditionally whitelist public universe server proof courier methods.
if allowPublicUniProofCourier {
addEndpoints(
"/universerpc.Universe/Info",
"/universerpc.Universe/InsertProof",
"/universerpc.Universe/QueryProof",

"/authmailboxrpc.Mailbox/MailboxInfo",
"/authmailboxrpc.Mailbox/SendMessage",
"/authmailboxrpc.Mailbox/ReceiveMessages",
)
}

return whitelist
Expand Down