Absorb outline-br, and fix certificate pinning across multiple requests

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
       # node --check only looks at its first argument, so check each file in turn.
       - name: Check syntax
         run: |
-          for file in shadowboxKey.js lib/*.js test/*.js; do
+          for file in index.js shadowboxKey.js lib/*.js test/*.js; do
             node --check "$file"
           done
 
@@ -42,6 +42,15 @@ jobs:
       - name: Check the CLI starts and prints help
         run: node shadowboxKey.js --help
 
+      - name: Check the module exports load
+        run: |
+          node -e '
+            const api = require("./");
+            for (const name of ["listKeys", "getUsage", "getKeys", "OutlineClient"]) {
+              if (!api[name]) throw new Error("missing export: " + name);
+            }
+          '
+
   audit:
     name: Dependency audit
     runs-on: ubuntu-latest

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 rahmanow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -2,9 +2,11 @@
 
 [![CI](https://github.com/rahmanow/ShadowboxKeys/actions/workflows/ci.yml/badge.svg)](https://github.com/rahmanow/ShadowboxKeys/actions/workflows/ci.yml)
 
-A command-line tool for managing access keys on your [Outline VPN](https://getoutline.org/) (Shadowbox) server. It lists, creates, renames and deletes keys, sets per-key data limits, reports how much data each key has used, and prints scannable QR codes so people can onboard with the Outline app instead of copy-pasting `ss://` strings.
+Manage access keys on your [Outline VPN](https://getoutline.org/) (Shadowbox) server, from the terminal or from your own code. It lists, creates, renames and deletes keys, sets per-key data limits, reports how much data each key has used, and prints scannable QR codes so people can onboard with the Outline app instead of copy-pasting `ss://` strings.
 
-It can also rewrite every access URL to use your own domain in place of the server's raw IP address — handy when you have pointed a domain at your Outline server.
+It can also rewrite every access URL to use your own domain in place of the server's raw IP address — handy when you have pointed a domain at your Outline server, or when your provider's IP has been blocked and you have restored the server elsewhere.
+
+This project supersedes [outline-br](https://github.com/rahmanow/outline-br), whose `getKeys()` module lives on here. See [migrating from outline-br](#migrating-from-outline-br).
 
 ## Prerequisites
 
@@ -131,14 +133,83 @@ Export usage for a spreadsheet:
 node shadowboxKey.js usage --csv > usage.csv
 ```
 
+## Using it from code
+
+Everything the CLI does is available as a module. `require` the package and you get three helpers plus the underlying client:
+
+```js
+const { listKeys, getUsage, getKeys, OutlineClient } = require('shadowbox-keys');
+
+const API = 'https://1.2.3.4:16942/AbCdEf123';
+const options = { domain: 'vpn.example.com', certSha256: 'E3823F9B...52F5A584' };
+
+// Structured key data
+const keys = await listKeys(API, options);
+// [{ id: '0', name: 'Alice', port: 443, dataLimitBytes: 10737418240,
+//    accessUrl: 'ss://...@vpn.example.com:443/?outline=1' }, ...]
+
+// Who is using how much
+const usage = await getUsage(API, options);
+// [{ id: '0', name: 'Alice', bytes: 3221225472, dataLimitBytes: 10737418240 }, ...]
+```
+
+`options` is optional throughout: `domain` swaps the host in each access URL, and `certSha256` pins the server's certificate exactly as the CLI does.
+
+For anything the helpers do not cover — creating, renaming and deleting keys, or setting data limits — use the client directly:
+
+```js
+const client = new OutlineClient(API, 'E3823F9B...52F5A584');
+
+const key = await client.createKey('Alice');
+await client.setKeyDataLimit(key.id, 50 * 1024 ** 3);   // 50 GB
+await client.renameKey(key.id, 'Alice B');
+await client.clearKeyDataLimit(key.id);
+await client.removeKey(key.id);
+
+await client.setServerDataLimit(100 * 1024 ** 3);       // server-wide default
+await client.clearServerDataLimit();
+```
+
+Failures caused by bad input or a bad response throw `UserError`, which is also exported, so you can tell them apart from bugs:
+
+```js
+const { UserError } = require('shadowbox-keys');
+
+try {
+    await listKeys(API, { certSha256: expected });
+} catch (err) {
+    if (err instanceof UserError) console.error(err.message);  // e.g. wrong certificate
+    else throw err;
+}
+```
+
+### Migrating from outline-br
+
+This project absorbed [outline-br](https://github.com/rahmanow/outline-br). Its `getKeys(managementApiUrl, newDomain)` is exported here with the same signature, the same `Name -> ss://...` output and the same printing behaviour, so existing code only needs its import changed:
+
+```js
+// before
+const keys = require('outline-br');
+keys('https://1.2.3.4:16942/AbCdEf123', '87.65.43.21');
+
+// after
+const { getKeys } = require('shadowbox-keys');
+await getKeys('https://1.2.3.4:16942/AbCdEf123', '87.65.43.21');
+```
+
+Two differences, both additive: `getKeys` now also returns the lines it printed, and it accepts a third `options` argument for `certSha256`. Nothing that worked before behaves differently.
+
+New code should prefer `listKeys()`, which returns structured data and leaves presentation to you, rather than printing to stdout.
+
 ## Project layout
 
 ```
+index.js           Programmatic API: listKeys, getUsage, getKeys
 shadowboxKey.js    CLI entry point: argument parsing and commands
 lib/outline.js     Outline Management API client
 lib/format.js      Byte formatting, size parsing, table/CSV output
 lib/errors.js      UserError, for messages shown without a stack trace
-test/              Unit tests, run with the built-in Node test runner
+test/              Tests, run with the built-in Node test runner
 ```
 
 ## Development
@@ -192,4 +263,4 @@ The HTTP calls use the built-in `node:https` module because the global `fetch()`
 
 ## License
 
-No license has been specified yet. Until one is added, all rights are reserved by the author.
+[MIT](LICENSE), carried over from outline-br when the two projects merged.

index.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * Programmatic entry point.
+ *
+ * The CLI in shadowboxKey.js is one consumer of this API; the exports below are
+ * the same building blocks it uses, so anything the CLI can do is reachable from
+ * code. getKeys() is kept signature-compatible with the outline-br module this
+ * project absorbed, so existing callers keep working.
+ */
+
+const { OutlineClient } = require('./lib/outline');
+const { formatBytes, parseBytes, rewriteAccessUrl } = require('./lib/format');
+const { UserError } = require('./lib/errors');
+
+/**
+ * Lists every access key on the server.
+ *
+ * @param {string} managementApiUrl  Management API URL from Outline Manager.
+ * @param {object} [options]
+ * @param {string} [options.domain]      Host to use in access URLs instead of the server IP.
+ * @param {string} [options.certSha256]  Pin the server's certificate to this fingerprint.
+ * @returns {Promise<Array<{id: string, name: string, port: number,
+ *                          dataLimitBytes: number|null, accessUrl: string}>>}
+ */
+async function listKeys(managementApiUrl, options = {}) {
+    const client = new OutlineClient(managementApiUrl, options.certSha256);
+    const host = options.domain || client.hostname;
+
+    const keys = await client.listKeys();
+    return keys.map(key => ({
+        id: key.id,
+        name: key.name || '',
+        port: key.port,
+        dataLimitBytes: key.dataLimit ? key.dataLimit.bytes : null,
+        accessUrl: rewriteAccessUrl(key.accessUrl, client.hostname, host),
+    }));
+}
+
+/**
+ * Reports how much data each key has transferred, busiest first.
+ *
+ * @param {string} managementApiUrl
+ * @param {object} [options]  Same options as listKeys.
+ * @returns {Promise<Array<{id: string, name: string, bytes: number,
+ *                          dataLimitBytes: number|null}>>}
+ */
+async function getUsage(managementApiUrl, options = {}) {
+    const client = new OutlineClient(managementApiUrl, options.certSha256);
+    const [keys, transferred] = await Promise.all([
+        client.listKeys(),
+        client.getTransferMetrics(),
+    ]);
+
+    return keys
+        .map(key => ({
+            id: key.id,
+            name: key.name || '',
+            bytes: transferred[key.id] || 0,
+            dataLimitBytes: key.dataLimit ? key.dataLimit.bytes : null,
+        }))
+        .sort((a, b) => b.bytes - a.bytes);
+}
+
+/**
+ * Prints every key as "Name -> ss://..." and returns those lines.
+ *
+ * This is the outline-br entry point, kept for callers migrating from that
+ * module: same two arguments, same output format and same printing behaviour.
+ * It returns the lines as well, which outline-br did not, so existing callers
+ * are unaffected. New code should prefer listKeys(), which returns structured
+ * data and leaves the printing to you.
+ *
+ * @param {string} managementApiUrl
+ * @param {string} [newDomain]  Host to use in access URLs instead of the server IP.
+ * @param {object} [options]    Additionally accepts certSha256.
+ * @returns {Promise<string[]>}
+ */
+async function getKeys(managementApiUrl, newDomain, options = {}) {
+    const keys = await listKeys(managementApiUrl, { ...options, domain: newDomain });
+
+    // outline-br trimmed the /?outline=1 suffix from the printed URL.
+    const lines = keys.map(key => `${key.name || 'Noname'} -> ${key.accessUrl.split('/?')[0]}`);
+    lines.forEach(line => console.log(line));
+    return lines;
+}
+
+module.exports = {
+    // High-level helpers
+    listKeys,
+    getUsage,
+    getKeys,
+    // The full Management API client, for anything the helpers do not cover
+    OutlineClient,
+    // Utilities shared with the CLI
+    formatBytes,
+    parseBytes,
+    rewriteAccessUrl,
+    UserError,
+};

lib/outline.js

@@ -11,7 +11,13 @@ const { UserError } = require('./errors');
 // supported way to relax certificate checks for a single request: it ignores
 // the agent option, and its dispatcher lives in undici, which is not reachable
 // without taking on a dependency.
-const agent = new https.Agent({ rejectUnauthorized: false });
+//
+// maxCachedSessions: 0 disables TLS session resumption. A resumed session skips
+// the certificate exchange, so getPeerCertificate() returns nothing and the
+// pinning check below could not run on any request after the first — which for
+// a command issuing several requests meant rejecting the legitimate server.
+// Forcing a full handshake each time costs a few milliseconds per request.
+const agent = new https.Agent({ rejectUnauthorized: false, maxCachedSessions: 0 });
 
 /**
  * Normalises a SHA-256 certificate fingerprint to bare lowercase hex, accepting