@runcitadel/lndconnect

@runcitadel/lndconnect

Generate and parse lndconnect uris https://github.com/runcitadel/lndconnect ⚡️

This package provides utilities for generating and parsing lndconnect uris.

This is a fork of the original node-lndconnect which has been rewritten in TypeScript. It is now also using ES Modules, and less deprecated APIs. In addition, this package works in the browser. However, the legacy URL format (lndconnect:///?host=1.2.3.4&cert=cert&macaroon=macaroon) is no longer supported.

For more information take a look at the specification of the uri format.

Table of Contents

• Install
• Usage
• Maintainers
• Contribute
• License

Install

npm install @runcitadel/lndconnect --save

Usage

format({ host, cert, macaroon }):

Formats a host / cert / macaroon combo into an lndconnect link.

import { format } from '@runcitadel/lndconnect';

const connectionString = format({
  host: '1.2.3.4:10009',
  cert: 'MIICuDCCAl...',
  macaroon: '0201036c6...',
});

expect(connectionString).toEqual('lndconnect://1.2.3.4:10009?cert=MIICuDCCAl...&macaroon=0201036c6...');

encode({ host, cert, macaroon }):

Encodes a host / cert / macaroon combo and formats into an lndconnect link.

import { encode } from '@runcitadel/lndconnect';

const connectionString = encode({
  host: '1.2.3.4:10009',
  cert: '-----BEGIN CERTIFICATE-----\n...',
  macaroon: '0201036c6...',
});

expect(connectionString).toEqual('lndconnect://1.2.3.4:10009?cert=MIICuDCCAl...&macaroon=AgEDbG5kAr...');

decode(lndconnectUri):

Decodes an lndconnect link into it's component parts (host / cert as utf8 / macaroon as hex)

import { decode } from '@runcitadel/lndconnect';

const { host, cert, macaroon } = decode('lndconnect://1.2.3.4:10009?cert=MIICuDCCAl...&macaroon=AgEDbG5kAr...');

expect(host).toEqual('1.2.3.4:10009');
expect(cert).toEqual('MIICuDCCAl...');
expect(macaroon).toEqual('0201036c6...');

Certificate

encodeCert(cert, format):

Encodes a certificate (String or Buffer) to base64url encoded DER format.

import { encodeCert } from '@runcitadel/lndconnect';

// __dirname in ESM
import { dirname } from 'path';
import { fileURLToPath } from 'url';

const __dirname = dirname(fileURLToPath(import.meta.url));

const certPath = path.join(__dirname, 'tls.cert');
const cert = encodeCert(certPath);

// returns base64url encoded DER cert.
expect(cert).toEqual('MIICuDCCAl...');

decodeCert(encodedCert):

Decodes a certificate from base64url encoded DER format to a string.

import { decodeCert } from '@runcitadel/lndconnect';

// __dirname in ESM
import { dirname } from 'path';
import { fileURLToPath } from 'url';

const __dirname = dirname(fileURLToPath(import.meta.url));

// pass a base64url encoded DER cert
const cert = decodeCert(encodedCert);

// returns utf8 encoded PEM cert.
expect(cert).toEqual('-----BEGIN CERTIFICATE-----\n...');

Macaroon

encodeMacaroon(macaroon, format):

Encodes a binary macaroon (String or Buffer) to base64url encoded string.

import { encodeMacaroon } from '@runcitadel/lndconnect';

const macaroonPath = path.join(__dirname, 'admin.macaroon');
const macaroon = encodeMacaroon(macaroonPath);

// returns base64url encoded macaroon.
expect(macaroon).toEqual('AgEDbG5kAr...');

decodeMacaroon(encodedMacaroon):

Decodes a base64url encoded macaroon to a hex encoded macaroon.

import { decodeMacaroon } from '@runcitadel/lndconnect';

// pass a base64url encoded macaroon
const macaroon = decodeMacaroon(encodedMacaroon);

// returns hex encoded macaroon.
expect(macaroon).toEqual('0201036c6...');

Testing

Run the tests suite:

  npm test

Behaviour differences from the version provided by Zeus

• Legacy (lndconnect://?host=...&cert=...) URIs are no longer supported.

Maintainers

@AaronDewes.

Contribute

Feel free to dive in! Open an issue or submit PRs.

lndconnect follows the Contributor Covenant Code of Conduct.

License

MIT © Tom Kirkpatrick