CheckMacaroonPermissions

CheckMacaroonPermissions checks whether the provided macaroon contains all the provided permissions. If the macaroon is valid (e.g. all caveats are satisfied), and all permissions provided in the request are met, then this RPC returns true.

Source: lightning.proto

gRPC

rpc CheckMacaroonPermissions (CheckMacPermRequest) returns (CheckMacPermResponse);

REST

HTTP Method	Path
POST	/v1/macaroon/checkpermissions

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('lightning.proto', loaderOptions);
const lnrpc = grpc.loadPackageDefinition(packageDefinition).lnrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new lnrpc.Lightning(GRPC_HOST, creds);
let request = {
  macaroon: <bytes>,
  permissions: <MacaroonPermission>,
  fullMethod: <string>,
  check_default_perms_from_full_method: <bool>,
};
client.checkMacaroonPermissions(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "valid": <bool>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the lightning.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lightning_pb2 as lnrpc, lightning_pb2_grpc as lightningstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = lightningstub.LightningStub(channel)
request = lnrpc.CheckMacPermRequest(
  macaroon=<bytes>,
  permissions=<MacaroonPermission>,
  fullMethod=<string>,
  check_default_perms_from_full_method=<bool>,
)
response = stub.CheckMacaroonPermissions(request)
print(response)
# {
#    "valid": <bool>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let requestBody = {
  macaroon: <string>, // <bytes> (base64 encoded)
  permissions: <array>, // <MacaroonPermission> 
  fullMethod: <string>, // <string> 
  check_default_perms_from_full_method: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/macaroon/checkpermissions`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "valid": <boolean>, // <bool> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/macaroon/checkpermissions'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'macaroon': base64.b64encode(<bytes>),
  'permissions': <MacaroonPermission>,
  'fullMethod': <string>,
  'check_default_perms_from_full_method': <bool>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "valid": <bool>,
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.CheckMacPermRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
macaroon The macaroon to check permissions for, serialized in binary format. For a macaroon to be valid, it must have been issued by lnd, must succeed all caveat conditions, and must contain all of the permissions specified in the permissions field.	bytes	string	body
permissions The list of permissions the macaroon should be checked against. Only if the macaroon contains all of these permissions, it is considered valid. If the list of permissions given is empty, then the macaroon is considered valid only based on issuance authority and caveat validity. An empty list of permissions is therefore equivalent to saying "skip checking permissions" (unless check_default_perms_from_full_method is specified).	MacaroonPermission[]	array	body
fullMethod The RPC method to check the macaroon against. This is only used if there are custom `uri:<rpcpackage>.<ServiceName>/<MethodName>` permissions in the permission list above. To check a macaroon against the list of permissions of a certain RPC method, query the `ListPermissions` RPC first, extract the permissions for the method, and then pass them in the `permissions` field above.	string	string	body
check_default_perms_from_full_method If this field is set to true, then the permissions list above MUST be empty. The default permissions for the provided fullMethod will be used to check the macaroon. This is equivalent to looking up the permissions for a method in the `ListPermissions` RPC and then calling this RPC with the permission list returned from that call. Without this flag, the list of permissions must be non-empty for the check to actually perform a permission check.	bool	boolean	body

lnrpc.CheckMacPermResponse

Source: lightning.proto

Field	gRPC Type	REST Type
valid	bool	boolean

Nested Messages

lnrpc.MacaroonPermission

Field	gRPC Type	REST Type
entity The entity a permission grants access to.	string	string
action The action that is granted.	string	string