javascript // SERVER ONLY. The embed backend tool (EMBED_CONTRACT.md, "Backend tools"). It
// extends the JavaScript integration allocator (../../integration/server) with
// the same settings, map format, key pattern, lock and response checks, and
// adds per-user data caps and removal. Your authenticated backend supplies the
// key internally, user:<service-user-id>:<installation-id> (or
// user:<service-user-id> for a service whose users run one installation);
// never pass an untrusted request field or a URnetwork client ID as the key.
//
// provision <key> <client-jwt-file> reissue or provision the key's client
// cap <key> [--monthly <bytes>|--monthly null] [--total <bytes>|--total null] [--reset-total]
// usage <key> the key's cap object
// usage-all every capped client's cap object, one per line
// remove <key> remove the key's client and its mapping
// acl <key> default|isolated set the ACL group of the key's client
// status the network's Embed state
// --self-test credential-free, no network
//
// Settings: URNETWORK_ROOT_JWT (an API key or a network JWT; never in an app),
// URNETWORK_CLIENT_MAP (absolute path in an existing private, service-owned
// directory), optional URNETWORK_API_URL and optional
// URNETWORK_DEFAULT_ACL_GROUP (the ACL group of each new client: isolated, the
// default, or default). A crash may leave <map>.lock; remove it only after
// confirming that no tool still owns it.
//
// Exit codes: 0 success, 78 configuration or credential problem (missing
// settings, an invalid key or map, the root credential refused, the client
// limit), 1 any other failure, with one stderr line that never holds a secret.
import assert from "node:assert/strict";
import {randomUUID} from "node:crypto";
import * as fs from "node:fs";
import {createServer} from "node:http";
import * as os from "node:os";
import * as path from "node:path";
import {fileURLToPath} from "node:url";
const exitSuccess = 0;
const exitFailure = 1;
// sysexits EX_CONFIG
const exitConfig = 78;
// the largest map or API answer the tool reads
const limit = 1 << 20;
const keyPattern = /^user:[A-Za-z0-9][A-Za-z0-9_.:@-]{0,122}(?![\s\S])/;
const idPattern = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}(?![\s\S])/;
// a byte count: a decimal integer from 0 to 2^63 - 1, without units
const byteCountPattern = /^(?:0|[1-9][0-9]{0,18})(?![\s\S])/;
const byteCountMax = 9223372036854775807n;
const description = "embed client";
const deviceSpec = "urnetwork-examples/javascript-embed-server";
const clientLimitMessage = "client limit reached: your network is at its client limit; see https://ur.io/services";
const clientDoesNotExist = "Client does not exist.";
const unmappedMessage = "no client is mapped for that key; run provision first";
const aclUnsupportedMessage = "/network/client-acl-group answered 404: the server predates ACL groups";
// The server refuses the data-cap and ACL-group routes with this message while
// the team has not enabled Embed for the network (EMBED_CONTRACT.md, "Embed
// enablement"); caps and groups set earlier stay enforced.
const embedNotEnabledMessage = "Embed isn't enabled for this network.";
// cap, usage, usage-all and acl print this for the refusal and exit 78
const embedNotEnabledLine = "embed not enabled: Embed isn't enabled for this network; see https://ur.io/services";
// provision prints this on stderr when the client's default ACL group stays
// pending because Embed isn't enabled, and exits 0
const embedPendingLine = "embed not enabled: the client's defaults stay pending until Embed is enabled; see https://ur.io/services";
const embedUnsupportedMessage = "/network/embed answered 404: the server predates Embed enablement";
const aclPath = "/network/client-acl-group";
const embedPath = "/network/embed";
const capPath = "/network/client-data-cap";
const capsPath = "/network/client-data-caps";
const aclGroupDefault = "default";
const aclGroupIsolated = "isolated";
const aclGroups = [aclGroupDefault, aclGroupIsolated];
// A configuration or credential problem: exit code 78.
class ConfigError extends Error {}
// An error whose message is one of the contract's exact lines, printed
// without the tool's prefix.
function exactError(message, ErrorClass = Error) {
const error = new ErrorClass(message);
error.exact = true;
return error;
}
// The error for a route that answered 404: a server that predates it
// (EMBED_CONTRACT.md, "Backend tools").
function notFoundError(apiPath) {
const route = apiPath.split("?")[0];
if (route === aclPath) return exactError(aclUnsupportedMessage);
if (route === capPath || route === capsPath) return exactError(`${route} answered 404: the server predates the data-cap routes`);
if (route === embedPath) return exactError(embedUnsupportedMessage);
return new Error(`${route} answered 404`);
}
// Whether an answer is the Embed-not-enabled refusal.
function isEmbedNotEnabled(answer) {
return answer?.error?.message === embedNotEnabledMessage;
}
// The Embed-not-enabled refusal is a configuration error with the exact line.
function checkEmbedEnabled(answer) {
if (isEmbedNotEnabled(answer)) throw exactError(embedNotEnabledLine, ConfigError);
}
// The key, checked against the allocator's pattern.
function checkKey(key) {
if (typeof key !== "string" || !keyPattern.test(key)) {
throw new ConfigError("expected a key user:<service-user-id>[:<installation-id>]");
}
return key;
}
// The API origin: HTTPS, or explicit loopback HTTP for local mocks.
function apiOrigin(base) {
let u;
try {
u = new URL(base);
} catch {
throw new ConfigError("URNETWORK_API_URL is not a URL");
}
if (u.username || u.password || u.pathname !== "/" || u.search || u.hash ||
(u.protocol !== "https:" && !(u.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname))))
throw new ConfigError("URNETWORK_API_URL must be an HTTPS origin (explicit loopback HTTP mocks are allowed)");
return u.origin;
}
// JSON with exact int64 byte counts: integers beyond 2^53 parse as BigInt and
// print back unchanged.
function parseJson(text) {
return JSON.parse(text, (key, value, context) =>
typeof value === "number" && Number.isInteger(value) && !Number.isSafeInteger(value) ? BigInt(context.source) : value);
}
function printJson(value) {
return JSON.stringify(value, (key, member) => typeof member === "bigint" ? JSON.rawJSON(String(member)) : member);
}
// Loads the map: version, clients and an optional pending_acl (the keys whose
// new clients still owe their default ACL group), so that two tools (or the
// token server, whose map adds pending_caps) never rewrite each other's map.
function loadMap(file) {
if (!fs.existsSync(file)) return {version: 1, clients: {}, pending_acl: []};
const stat = fs.lstatSync(file);
if (!stat.isFile() || stat.isSymbolicLink() || stat.size > limit ||
(process.platform !== "win32" && (stat.mode & 0o077))) throw new ConfigError("the client map must be a private regular file (0600)");
let map;
try {
map = JSON.parse(fs.readFileSync(file, "utf8"));
} catch {
throw new ConfigError("the client map is not JSON");
}
if (!map || typeof map !== "object" || Array.isArray(map) || map.version !== 1 || !map.clients ||
Array.isArray(map.clients) || typeof map.clients !== "object") throw new ConfigError("invalid client map");
const unknown = Object.keys(map).filter(name => name !== "version" && name !== "clients" && name !== "pending_acl");
if (unknown.length) throw new ConfigError(`the client map has fields this tool does not own (${unknown.join(", ")}); use a map of its own`);
const seen = new Set();
for (const [key, client] of Object.entries(map.clients)) {
if (!keyPattern.test(key) || typeof client !== "string" || !idPattern.test(client) || seen.has(client)) throw new ConfigError("invalid client map entry");
seen.add(client);
}
map.pending_acl ??= [];
if (!Array.isArray(map.pending_acl) || new Set(map.pending_acl).size !== map.pending_acl.length ||
map.pending_acl.some(key => typeof key !== "string" || !Object.hasOwn(map.clients, key)))
throw new ConfigError("the client map's pending_acl is not a list of mapped keys");
return map;
}
// Saves the map atomically: pending_acl only while it is not empty.
function saveMap(file, map) {
const saved = {version: map.version, clients: map.clients};
if (map.pending_acl.length) saved.pending_acl = map.pending_acl;
writePrivate(file, JSON.stringify(saved));
}
// Records that key's new client owes its default ACL group, or drops the
// record.
function setAclPending(map, key, pending) {
map.pending_acl = map.pending_acl.filter(entry => entry !== key);
if (pending) map.pending_acl.push(key);
}
// Writes a file atomically with owner-only permissions.
function writePrivate(file, data) {
const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomUUID()}`);
const fd = fs.openSync(temporary, "wx", 0o600);
try {
fs.writeFileSync(fd, data);
fs.fsyncSync(fd);
} finally { fs.closeSync(fd); }
try { fs.renameSync(temporary, file); }
finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
}
// Runs work with the map's exclusive lock, held through the remote calls and
// the atomic map update.
async function withLock(file, work) {
if (!path.isAbsolute(file) || !fs.statSync(path.dirname(file), {throwIfNoEntry: false})?.isDirectory())
throw new ConfigError("URNETWORK_CLIENT_MAP needs an absolute path in an existing directory");
try {
fs.mkdirSync(file + ".lock", {mode: 0o700});
} catch (error) {
if (error.code === "EEXIST") throw new Error("the client map is locked by another tool; retry");
throw error;
}
try { return await work(); }
finally { fs.rmdirSync(file + ".lock"); }
}
// The JWT's client_id claim; this checks consistency, not the signature.
function claimedClientId(jwt) {
const parts = typeof jwt === "string" ? jwt.split(".") : [];
if (parts.length !== 3 || parts.some(part => !part) || !/^[A-Za-z0-9_-]+(?![\s\S])/.test(parts[1])) throw new Error("invalid client JWT");
let claims;
try {
claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
} catch {
throw new Error("invalid client JWT");
}
return typeof claims?.client_id === "string" ? claims.client_id.toLowerCase() : "";
}
// The auth-client request for a key: a reissue sends the mapped client_id,
// a new client sends neither client_id nor source_client_id.
function authClientBody(client) {
const body = {description, device_spec: deviceSpec};
if (client !== undefined) {
if (!idPattern.test(client)) throw new ConfigError("invalid mapped client ID");
body.client_id = client;
}
return JSON.stringify(body);
}
// Checks an auth-client answer: a refusal throws (the client limit flags as a
// configuration error), a success must carry a client JWT whose claim matches.
function checkAuthClient(answer, expected) {
if (!answer || typeof answer !== "object" || Array.isArray(answer)) throw new Error("invalid API response");
if (answer.error != null) {
if (answer.error.client_limit_exceeded || answer.error.upgrade_required) throw exactError(clientLimitMessage, ConfigError);
const refusal = new Error(typeof answer.error.message === "string" ? `provisioning refused: ${answer.error.message}` : "provisioning refused");
refusal.apiMessage = answer.error.message;
throw refusal;
}
if (typeof answer.client_id !== "string" || !idPattern.test(answer.client_id) || typeof answer.by_client_jwt !== "string") throw new Error("invalid API response");
if (claimedClientId(answer.by_client_jwt) !== answer.client_id || (expected !== undefined && expected !== answer.client_id))
throw new Error("scoped client identity mismatch");
return {client_id: answer.client_id, by_client_jwt: answer.by_client_jwt};
}
// The cap request body: only the given fields, byte counts exact.
function capBody(client, {monthly, total, resetTotal}) {
let body = `{"client_id":${JSON.stringify(client)}`;
if (monthly !== undefined) body += `,"monthly_byte_limit":${monthly}`;
if (total !== undefined) body += `,"total_byte_limit":${total}`;
if (resetTotal) body += `,"reset_total":true`;
return body + "}";
}
// The cap command's options: at least one, each once.
function capOptions(args) {
const options = {};
const byteCount = value => {
if (value === "null") return "null";
if (typeof value !== "string" || !byteCountPattern.test(value) || BigInt(value) > byteCountMax)
throw new ConfigError("a byte count is a decimal integer from 0 to 9223372036854775807, or null");
return value;
};
for (let i = 0; i < args.length; i += 1) {
const option = args[i];
if ((option === "--monthly" || option === "--total") && i + 1 < args.length) {
const name = option === "--monthly" ? "monthly" : "total";
if (options[name] !== undefined) throw new ConfigError(`${option} given twice`);
options[name] = byteCount(args[i += 1]);
} else if (option === "--reset-total" && !options.resetTotal) {
options.resetTotal = true;
} else {
throw new ConfigError(`unexpected argument ${JSON.stringify(option)}`);
}
}
if (options.monthly === undefined && options.total === undefined && !options.resetTotal)
throw new ConfigError("cap needs at least one of --monthly, --total, --reset-total");
return options;
}
// Checks a cap object answer for the client.
function checkCapObject(answer, client) {
if (!answer || typeof answer !== "object" || Array.isArray(answer)) throw new Error("invalid cap answer");
checkEmbedEnabled(answer);
if (answer.error != null) throw new Error(typeof answer.error.message === "string" ? `the cap request was refused: ${answer.error.message}` : "the cap request was refused");
if (client !== undefined && answer.client_id !== client) throw new Error("the cap answer is for another client");
for (const field of ["monthly_byte_limit", "total_byte_limit"]) {
const value = answer[field];
if (!(value === undefined || value === null || typeof value === "bigint" || (Number.isInteger(value) && 0 <= value))) throw new Error("invalid cap answer");
}
return answer;
}
// The mapped client of a key, or a configuration error.
function mappedClient(map, key) {
const client = map.clients[key];
if (client === undefined) throw exactError(unmappedMessage, ConfigError);
return client;
}
// An API call with the root credential: call(method, path, body) resolves
// with the parsed answer. A 401 is the root credential refused (78).
function apiCaller(origin, root) {
if (!root || /\s/.test(root)) throw new ConfigError("set URNETWORK_ROOT_JWT to the backend's root credential");
return async (method, apiPath, body) => {
const response = await fetch(origin + apiPath, {
method,
headers: {authorization: "Bearer " + root, ...(body === undefined ? {} : {"content-type": "application/json"})},
body, redirect: "error", signal: AbortSignal.timeout(15000),
});
if (response.status === 401) throw new ConfigError("the URnetwork API refused the root credential");
const text = await response.text();
if (response.status === 404) throw notFoundError(apiPath);
if (text.length > limit) throw new Error("API response too large");
if (!response.ok) throw new Error(`the URnetwork API answered HTTP ${response.status}`);
return parseJson(text);
};
}
// provision: reissue the key's client, or provision a new one; on "Client does
// not exist." drop the mapping and provision a new client. A new client goes
// into aclGroup, with a pending_acl record until the group is applied, before
// any client JWT is written. Writes the client JWT to the file, never to the
// output. While Embed isn't enabled the record stays, with a line on err, and
// a provision after the team enables Embed applies it.
async function provision(key, clientJwtFile, {file, call, out, err, aclGroup}) {
checkKey(key);
if (typeof clientJwtFile !== "string" || clientJwtFile === "") throw new ConfigError("expected provision <key> <client-jwt-file>");
const target = path.resolve(clientJwtFile);
await withLock(file, async () => {
const map = loadMap(file);
let old = map.clients[key];
let result;
try {
result = checkAuthClient(await call("POST", "/network/auth-client", authClientBody(old)), old);
} catch (error) {
if (old === undefined || error.apiMessage !== clientDoesNotExist) throw error;
// deactivated after 30 days without connecting: provision a new client
delete map.clients[key];
setAclPending(map, key, false);
saveMap(file, map);
old = undefined;
result = checkAuthClient(await call("POST", "/network/auth-client", authClientBody(undefined)), undefined);
}
if (old === undefined) {
if (Object.values(map.clients).includes(result.client_id)) throw new Error("client assigned to another key");
map.clients[key] = result.client_id;
// the mapping and the record that the client owes its group, in one save
setAclPending(map, key, aclGroup === aclGroupIsolated);
saveMap(file, map);
}
let embedEnabled = true;
if (map.pending_acl.includes(key)) {
// a new client is "default": only an isolated default needs the request.
// A failure throws with the record kept, before any client JWT is written.
if (aclGroup === aclGroupIsolated) embedEnabled = await postAclGroup(call, result.client_id, aclGroupIsolated, true);
// while Embed isn't enabled the record stays and the client works
if (embedEnabled) {
setAclPending(map, key, false);
saveMap(file, map);
}
}
writePrivate(target, result.by_client_jwt + "\n");
out(printJson({client_id: result.client_id}));
if (!embedEnabled) err(embedPendingLine);
});
}
// Sets the client's ACL group; the answer must name the client and the group.
// The Embed-not-enabled refusal exits 78, or resolves false when
// allowNotEnabled is set.
async function postAclGroup(call, client, group, allowNotEnabled = false) {
const answer = await call("POST", aclPath, JSON.stringify({client_id: client, acl_group: group}));
if (!answer || typeof answer !== "object" || Array.isArray(answer)) throw new Error("invalid ACL group answer");
if (allowNotEnabled && isEmbedNotEnabled(answer)) return false;
checkEmbedEnabled(answer);
if (answer.error != null)
throw new Error(typeof answer.error.message === "string" ? `the ACL group request was refused: ${answer.error.message}` : "the ACL group request was refused");
if (answer.client_id !== client || answer.acl_group !== group) throw new Error("the API answered another client or ACL group");
return true;
}
// acl: set the ACL group of the key's client; prints {"client_id": ...,
// "acl_group": ...}. An explicit group settles a pending default group, so
// the record is dropped.
async function acl(key, group, {file, call, out}) {
checkKey(key);
if (!aclGroups.includes(group)) throw new ConfigError("expected acl <key> default|isolated");
await withLock(file, async () => {
const map = loadMap(file);
const client = mappedClient(map, key);
await postAclGroup(call, client, group);
if (map.pending_acl.includes(key)) {
setAclPending(map, key, false);
saveMap(file, map);
}
out(printJson({client_id: client, acl_group: group}));
});
}
// cap: post only the given fields; prints the cap object.
async function cap(key, args, {file, call, out}) {
checkKey(key);
const options = capOptions(args);
const client = mappedClient(loadMap(file), key);
out(printJson(checkCapObject(await call("POST", "/network/client-data-cap", capBody(client, options)), client)));
}
// usage: the key's cap object, read with the root credential.
async function usage(key, {file, call, out}) {
checkKey(key);
const client = mappedClient(loadMap(file), key);
out(printJson(checkCapObject(await call("GET", `/network/client-data-cap?client_id=${client}`), client)));
}
// usage-all: every capped client's cap object, one per line, paging with
// limit=1000 until a null cursor or a repeated one.
async function usageAll({call, out}) {
const seen = new Set();
let cursor = null;
while (true) {
const page = await call("GET", `/network/client-data-caps?limit=1000${cursor === null ? "" : `&cursor=${encodeURIComponent(cursor)}`}`);
checkEmbedEnabled(page);
if (!page || typeof page !== "object" || page.error != null || !Array.isArray(page.clients) ||
!(page.next_cursor === null || page.next_cursor === undefined || typeof page.next_cursor === "string")) throw new Error("invalid cap list answer");
for (const item of page.clients) out(printJson(checkCapObject(item)));
cursor = page.next_cursor ?? null;
if (cursor === null || seen.has(cursor)) return;
seen.add(cursor);
}
}
// status: the network's Embed state from GET /network/embed as one line,
// "embed enabled: yes | client limit: 5000 | active clients: 1234". A refusal,
// such as for a client JWT, is a configuration error.
async function status({call, out}) {
const answer = await call("GET", embedPath);
if (!answer || typeof answer !== "object" || Array.isArray(answer)) throw new Error("invalid Embed state answer");
if (answer.error != null)
throw new ConfigError(typeof answer.error.message === "string" ? `the Embed state request was refused: ${answer.error.message}` : "the Embed state request was refused");
const isCount = value => (Number.isSafeInteger(value) && 0 <= value) || (typeof value === "bigint" && 0n <= value);
if (typeof answer.enabled !== "boolean" || !isCount(answer.client_limit) || !isCount(answer.active_client_count))
throw new Error("invalid Embed state answer");
out(`embed enabled: ${answer.enabled ? "yes" : "no"} | client limit: ${answer.client_limit} | active clients: ${answer.active_client_count}`);
}
// remove: remove the key's client, then its mapping (also when the client is
// already gone).
async function remove(key, {file, call, out}) {
checkKey(key);
await withLock(file, async () => {
const map = loadMap(file);
const client = mappedClient(map, key);
const answer = await call("POST", "/network/remove-client", JSON.stringify({client_id: client}));
if (!answer || typeof answer !== "object") throw new Error("invalid remove answer");
if (answer.error != null && answer.error.message !== clientDoesNotExist)
throw new Error(typeof answer.error.message === "string" ? `removal refused: ${answer.error.message}` : "removal refused");
delete map.clients[key];
setAclPending(map, key, false);
saveMap(file, map);
out(printJson({removed: client}));
});
}
// Runs one command; resolves with the exit code. The options replace the
// environment, the API caller and the output, for the self-test.
export async function runCommand(args, {environment = process.env, call = undefined, out = line => console.log(line), err = line => console.error(line)} = {}) {
try {
const [command, ...rest] = args;
if (command === "--self-test" && rest.length === 0) {
await selfTest();
out("embed server self-test passed");
return exitSuccess;
}
const handlers = {
provision: rest.length === 2 ? context => provision(rest[0], rest[1], context) : null,
cap: rest.length >= 1 ? context => cap(rest[0], rest.slice(1), context) : null,
usage: rest.length === 1 ? context => usage(rest[0], context) : null,
"usage-all": rest.length === 0 ? context => usageAll(context) : null,
remove: rest.length === 1 ? context => remove(rest[0], context) : null,
acl: rest.length === 2 && aclGroups.includes(rest[1]) ? context => acl(rest[0], rest[1], context) : null,
status: rest.length === 0 ? context => status(context) : null,
};
const handler = Object.hasOwn(handlers, command) ? handlers[command] : null;
if (!handler) throw new ConfigError("usage: embed-server provision <key> <client-jwt-file> | cap <key> [--monthly <bytes>|null] [--total <bytes>|null] [--reset-total] | usage <key> | usage-all | remove <key> | acl <key> default|isolated | status | --self-test");
const file = environment.URNETWORK_CLIENT_MAP;
if (!file) throw new ConfigError("set URNETWORK_CLIENT_MAP to the absolute path of this tool's private client map");
const aclGroup = environment.URNETWORK_DEFAULT_ACL_GROUP || aclGroupIsolated;
if (!aclGroups.includes(aclGroup)) throw new ConfigError("URNETWORK_DEFAULT_ACL_GROUP must be default or isolated");
call ??= apiCaller(apiOrigin(environment.URNETWORK_API_URL || "https://api.bringyour.com"), environment.URNETWORK_ROOT_JWT);
await handler({file, call, out, err, aclGroup});
return exitSuccess;
} catch (error) {
// one line, never a token: messages here never include the root credential or a JWT
// the contract's exact lines (the client limit, an unmapped key, an older server) print as they are
err(error?.exact ? error.message : error?.message ? `embed server: ${error.message}` : "embed server failed");
return error instanceof ConfigError ? exitConfig : exitFailure;
}
}
// The credential-free self-test: a mock API, no network.
async function selfTest() {
const client = "11111111-1111-1111-1111-111111111111";
const other = "22222222-2222-2222-2222-222222222222";
const jwt = id => "e30." + Buffer.from(JSON.stringify({client_id: id})).toString("base64url") + ".test";
const root = "urn_" + "r".repeat(40);
const directory = fs.mkdtempSync(path.join(os.tmpdir(), "ur-embed-server-"));
fs.chmodSync(directory, 0o700);
const file = path.join(directory, "clients.json");
const jwtFile = path.join(directory, "client.jwt");
const key = "user:alice:33333333-3333-3333-3333-333333333333";
const capAnswer = id => `{"client_id":"${id}","monthly_byte_limit":9223372036854775807,"monthly_used_byte_count":12,"total_byte_limit":null,"total_used_byte_count":12,"capped":false,"capped_reason":""}`;
try {
// a scripted API: answers[i] answers the i-th call; calls records them
const calls = [];
let answers = [];
const call = async (method, apiPath, body) => {
calls.push({method, apiPath, body: body === undefined ? undefined : body});
const next = answers.shift();
if (next instanceof Error) throw next;
return parseJson(next);
};
const outputs = [];
const command = async args => {
outputs.length = 0;
// these checks keep new clients in "default", which sends no ACL request
return runCommand(args, {environment: {URNETWORK_CLIENT_MAP: file, URNETWORK_ROOT_JWT: root, URNETWORK_DEFAULT_ACL_GROUP: aclGroupDefault}, call, out: line => outputs.push(line), err: line => outputs.push(line)});
};
// the same with the default group unset, so isolated, and its own map
const aclFile = path.join(directory, "acl.json");
const isolated = async args => {
outputs.length = 0;
return runCommand(args, {environment: {URNETWORK_CLIENT_MAP: aclFile, URNETWORK_ROOT_JWT: root}, call, out: line => outputs.push(line), err: line => outputs.push(line)});
};
// new, then reissue: client_id only on the reissue, never source_client_id
answers = [JSON.stringify({client_id: client, by_client_jwt: jwt(client)})];
assert.equal(await command(["provision", key, jwtFile]), exitSuccess);
assert.deepEqual(outputs, [`{"client_id":"${client}"}`]);
assert.deepEqual(JSON.parse(calls[0].body), {description, device_spec: deviceSpec});
assert.equal(fs.readFileSync(jwtFile, "utf8").trim(), jwt(client));
if (process.platform !== "win32") {
assert.equal(fs.statSync(jwtFile).mode & 0o077, 0);
assert.equal(fs.statSync(file).mode & 0o077, 0);
}
answers = [JSON.stringify({client_id: client, by_client_jwt: jwt(client)})];
assert.equal(await command(["provision", key, jwtFile]), exitSuccess);
assert.deepEqual(JSON.parse(calls[1].body), {description, device_spec: deviceSpec, client_id: client});
assert.equal(JSON.parse(calls[1].body).source_client_id, undefined);
assert.deepEqual(loadMap(file).clients, {[key]: client});
// the token never reaches the output
assert.ok(outputs.every(line => !line.includes(jwt(client))));
// a deactivated client: the reissue answers "Client does not exist.", a new client is provisioned
answers = [JSON.stringify({error: {message: clientDoesNotExist}}), JSON.stringify({client_id: other, by_client_jwt: jwt(other)})];
assert.equal(await command(["provision", key, jwtFile]), exitSuccess);
assert.equal(calls[3].body, authClientBody(undefined));
assert.deepEqual(loadMap(file).clients, {[key]: other});
// response and claim checks, the client limit (78), a refusal (1), the root credential refused (78)
for (const [answer, code] of [
[JSON.stringify({client_id: other, by_client_jwt: jwt(client)}), exitFailure],
[JSON.stringify({error: {client_limit_exceeded: true, message: "Client limit exceeded."}}), exitConfig],
[JSON.stringify({error: {upgrade_required: true, message: "Upgrade required."}}), exitConfig],
[JSON.stringify({error: {message: "Invalid location"}}), exitFailure],
[new ConfigError("the URnetwork API refused the root credential"), exitConfig],
]) {
answers = [answer];
assert.equal(await command(["provision", key, jwtFile]), code);
assert.equal(outputs.length, 1);
}
answers = [JSON.stringify({error: {client_limit_exceeded: true}})];
assert.equal(await command(["provision", "user:bob", path.join(directory, "bob.jwt")]), exitConfig);
assert.deepEqual(outputs, [clientLimitMessage]);
// key and argument rejection
for (const args of [["provision", other, jwtFile], ["provision", "user:../a", jwtFile], ["provision", "user:alice\n", jwtFile],
["provision", key], ["usage", key, "--client-id", other], ["cap", key], ["cap", key, "--monthly", "10GB"], ["cap", key, "--monthly", "-1"],
["cap", key, "--monthly", "9223372036854775808"], ["cap", key, "--monthly", "1", "--monthly", "2"], ["remove", "user:nobody"], ["unknown"]]) {
assert.equal(await command(args), exitConfig, args.join(" "));
}
// merge bodies: omitted absent, null is null, exact integers, reset_total only when given
for (const [args, body] of [
[["--monthly", "10000000000"], `{"client_id":"${other}","monthly_byte_limit":10000000000}`],
[["--total", "null"], `{"client_id":"${other}","total_byte_limit":null}`],
[["--monthly", "0", "--reset-total"], `{"client_id":"${other}","monthly_byte_limit":0,"reset_total":true}`],
[["--reset-total"], `{"client_id":"${other}","reset_total":true}`],
[["--monthly", "9223372036854775807", "--total", "5"], `{"client_id":"${other}","monthly_byte_limit":9223372036854775807,"total_byte_limit":5}`],
]) {
answers = [capAnswer(other)];
assert.equal(await command(["cap", key, ...args]), exitSuccess);
assert.equal(calls.at(-1).body, body);
// the cap object prints with the exact byte counts
assert.equal(outputs[0], capAnswer(other));
}
answers = [capAnswer(client)];
assert.equal(await command(["cap", key, "--monthly", "1"]), exitFailure);
answers = [capAnswer(other)];
assert.equal(await command(["usage", key]), exitSuccess);
assert.equal(calls.at(-1).apiPath, `/network/client-data-cap?client_id=${other}`);
// usage-all pages until a null cursor, and stops on a repeated cursor
answers = [JSON.stringify({clients: [JSON.parse(capAnswer(client))], next_cursor: "a"}), JSON.stringify({clients: [JSON.parse(capAnswer(other))], next_cursor: null})];
assert.equal(await command(["usage-all"]), exitSuccess);
assert.equal(outputs.length, 2);
assert.equal(calls.at(-2).apiPath, "/network/client-data-caps?limit=1000");
assert.equal(calls.at(-1).apiPath, "/network/client-data-caps?limit=1000&cursor=a");
answers = [JSON.stringify({clients: [], next_cursor: "b"}), JSON.stringify({clients: [], next_cursor: "b"}), JSON.stringify({clients: [], next_cursor: "c"})];
assert.equal(await command(["usage-all"]), exitSuccess);
assert.equal(answers.length, 1, "usage-all did not stop on the repeated cursor");
// remove drops the mapping for both answers
answers = [JSON.stringify({})];
assert.equal(await command(["remove", key]), exitSuccess);
assert.deepEqual(outputs, [`{"removed":"${other}"}`]);
assert.deepEqual(JSON.parse(calls.at(-1).body), {client_id: other});
assert.deepEqual(loadMap(file).clients, {});
writePrivate(file, JSON.stringify({version: 1, clients: {[key]: client}}));
answers = [JSON.stringify({error: {message: clientDoesNotExist}})];
assert.equal(await command(["remove", key]), exitSuccess);
assert.deepEqual(loadMap(file).clients, {});
// a map with fields this tool does not own, such as the token server's pending_caps
writePrivate(file, JSON.stringify({version: 1, clients: {}, pending_caps: []}));
answers = [JSON.stringify({clients: [], next_cursor: null})];
assert.equal(await command(["usage-all"]), exitSuccess, "usage-all needs no map");
assert.equal(await command(["provision", key, jwtFile]), exitConfig);
assert.match(outputs[0], /pending_caps/);
// the default ACL group: one request after a new client, then no record; none on a reissue
const ivanJwt = path.join(directory, "ivan.jwt");
answers = [JSON.stringify({client_id: client, by_client_jwt: jwt(client)}), JSON.stringify({client_id: client, acl_group: aclGroupIsolated})];
assert.equal(await isolated(["provision", "user:ivan", ivanJwt]), exitSuccess);
assert.deepEqual(calls.slice(-2).map(c => c.apiPath), ["/network/auth-client", aclPath]);
assert.deepEqual(JSON.parse(calls.at(-1).body), {client_id: client, acl_group: aclGroupIsolated});
assert.deepEqual(loadMap(aclFile).pending_acl, []);
assert.ok(!fs.readFileSync(aclFile, "utf8").includes("pending_acl"));
assert.equal(fs.readFileSync(ivanJwt, "utf8").trim(), jwt(client));
answers = [JSON.stringify({client_id: client, by_client_jwt: jwt(client)})];
const callCount = calls.length;
assert.equal(await isolated(["provision", "user:ivan", ivanJwt]), exitSuccess);
assert.equal(calls.length, callCount + 1, "a reissue sent an ACL request");
// a failed request keeps the record and writes no client JWT; the next issue retries
const judyJwt = path.join(directory, "judy.jwt");
answers = [JSON.stringify({client_id: other, by_client_jwt: jwt(other)}), new Error("the URnetwork API answered HTTP 500")];
assert.equal(await isolated(["provision", "user:judy", judyJwt]), exitFailure);
assert.ok(!fs.existsSync(judyJwt));
assert.deepEqual(loadMap(aclFile).pending_acl, ["user:judy"]);
assert.equal(loadMap(aclFile).clients["user:judy"], other);
answers = [JSON.stringify({client_id: other, by_client_jwt: jwt(other)}), JSON.stringify({client_id: other, acl_group: aclGroupIsolated})];
assert.equal(await isolated(["provision", "user:judy", judyJwt]), exitSuccess);
assert.equal(calls.at(-1).apiPath, aclPath);
assert.deepEqual(loadMap(aclFile).pending_acl, []);
assert.ok(fs.existsSync(judyJwt));
// a server without ACL groups: exit 1 with the exact line and the record kept
const kim = "55555555-5555-5555-5555-555555555555";
answers = [JSON.stringify({client_id: kim, by_client_jwt: jwt(kim)}), notFoundError(aclPath)];
assert.equal(await isolated(["provision", "user:kim", path.join(directory, "kim.jwt")]), exitFailure);
assert.deepEqual(outputs, [aclUnsupportedMessage]);
assert.deepEqual(loadMap(aclFile).pending_acl, ["user:kim"]);
assert.ok(!fs.existsSync(path.join(directory, "kim.jwt")));
// a default of default settles the record without a request
answers = [JSON.stringify({client_id: kim, by_client_jwt: jwt(kim)})];
const beforeDefault = calls.length;
assert.equal(await runCommand(["provision", "user:kim", path.join(directory, "kim.jwt")],
{environment: {URNETWORK_CLIENT_MAP: aclFile, URNETWORK_ROOT_JWT: root, URNETWORK_DEFAULT_ACL_GROUP: aclGroupDefault}, call, out: () => {}, err: () => {}}), exitSuccess);
assert.equal(calls.length, beforeDefault + 1);
assert.deepEqual(loadMap(aclFile).pending_acl, []);
// the acl command: the request, the printed answer, refusals
answers = [JSON.stringify({client_id: client, acl_group: aclGroupDefault})];
assert.equal(await isolated(["acl", "user:ivan", aclGroupDefault]), exitSuccess);
assert.deepEqual(outputs, [`{"client_id":"${client}","acl_group":"default"}`]);
assert.deepEqual(calls.at(-1), {method: "POST", apiPath: aclPath, body: JSON.stringify({client_id: client, acl_group: aclGroupDefault})});
for (const args of [["acl"], ["acl", "user:ivan"], ["acl", "user:ivan", "public"], ["acl", "user:ivan", "Default"], ["acl", "user:ivan", "default", "extra"], ["acl", "alice", "default"]]) {
assert.equal(await isolated(args), exitConfig, args.join(" "));
}
answers = [JSON.stringify({client_id: client, acl_group: aclGroupDefault})];
assert.equal(await isolated(["acl", "user:ivan", aclGroupIsolated]), exitFailure, "an answer for another group was accepted");
answers = [JSON.stringify({error: {message: clientDoesNotExist}})];
assert.equal(await isolated(["acl", "user:ivan", aclGroupIsolated]), exitFailure);
answers = [notFoundError(aclPath)];
assert.equal(await isolated(["acl", "user:ivan", aclGroupIsolated]), exitFailure);
assert.deepEqual(outputs, [aclUnsupportedMessage]);
// an explicit group settles a pending record, so a later issue keeps it
const mia = "66666666-6666-6666-6666-666666666666";
answers = [JSON.stringify({client_id: mia, by_client_jwt: jwt(mia)}), new Error("the URnetwork API answered HTTP 500")];
await isolated(["provision", "user:mia", path.join(directory, "mia.jwt")]);
assert.deepEqual(loadMap(aclFile).pending_acl, ["user:mia"]);
answers = [JSON.stringify({client_id: mia, acl_group: aclGroupDefault})];
assert.equal(await isolated(["acl", "user:mia", aclGroupDefault]), exitSuccess);
assert.deepEqual(loadMap(aclFile).pending_acl, []);
answers = [JSON.stringify({client_id: mia, by_client_jwt: jwt(mia)})];
const beforeSettled = calls.length;
assert.equal(await isolated(["provision", "user:mia", path.join(directory, "mia.jwt")]), exitSuccess);
assert.equal(calls.length, beforeSettled + 1, "a settled group was overridden");
// remove drops a pending record with its mapping
const noor = "77777777-7777-7777-7777-777777777777";
answers = [JSON.stringify({client_id: noor, by_client_jwt: jwt(noor)}), new Error("the URnetwork API answered HTTP 500")];
await isolated(["provision", "user:noor", path.join(directory, "noor.jwt")]);
answers = [JSON.stringify({})];
assert.equal(await isolated(["remove", "user:noor"]), exitSuccess);
assert.deepEqual(loadMap(aclFile).pending_acl, []);
// Embed not enabled: cap, usage, usage-all and acl exit 78 with the exact
// line; provision still provisions and writes the client JWT, keeps the
// default group pending with the exact stderr line, and a provision after
// the team enables Embed applies it
const embedFile = path.join(directory, "embed.json");
const embedRun = async args => {
const lines = {out: [], err: []};
const code = await runCommand(args, {environment: {URNETWORK_CLIENT_MAP: embedFile, URNETWORK_ROOT_JWT: root}, call,
out: line => lines.out.push(line), err: line => lines.err.push(line)});
return {code, ...lines};
};
const refusal = JSON.stringify({error: {message: embedNotEnabledMessage}});
const pia = "88888888-8888-8888-8888-888888888888";
answers = [JSON.stringify({client_id: pia, by_client_jwt: jwt(pia)}), JSON.stringify({client_id: pia, acl_group: aclGroupIsolated})];
assert.equal((await embedRun(["provision", "user:pia", path.join(directory, "pia.jwt")])).code, exitSuccess);
for (const args of [["cap", "user:pia", "--monthly", "1"], ["usage", "user:pia"], ["usage-all"], ["acl", "user:pia", aclGroupIsolated]]) {
answers = [refusal];
assert.deepEqual(await embedRun(args), {code: exitConfig, out: [], err: [embedNotEnabledLine]}, args.join(" "));
}
const quinn = "99999999-9999-9999-9999-999999999999";
const quinnJwt = path.join(directory, "quinn.jwt");
answers = [JSON.stringify({client_id: quinn, by_client_jwt: jwt(quinn)}), refusal];
assert.deepEqual(await embedRun(["provision", "user:quinn", quinnJwt]), {code: exitSuccess, out: [`{"client_id":"${quinn}"}`], err: [embedPendingLine]});
assert.equal(calls.at(-1).apiPath, aclPath);
assert.equal(fs.readFileSync(quinnJwt, "utf8"), jwt(quinn) + "\n");
assert.deepEqual(loadMap(embedFile).pending_acl, ["user:quinn"]);
answers = [JSON.stringify({client_id: quinn, by_client_jwt: jwt(quinn)}), JSON.stringify({client_id: quinn, acl_group: aclGroupIsolated})];
assert.deepEqual(await embedRun(["provision", "user:quinn", quinnJwt]), {code: exitSuccess, out: [`{"client_id":"${quinn}"}`], err: []});
assert.deepEqual(JSON.parse(calls.at(-1).body), {client_id: quinn, acl_group: aclGroupIsolated});
assert.deepEqual(loadMap(embedFile).pending_acl, []);
// status: GET /network/embed printed as one line for an enabled and a not
// enabled network; a refusal is 78; a server without the route and an
// invalid answer are 1
for (const [answer, line] of [
[{enabled: true, client_limit: 5000, active_client_count: 1234}, "embed enabled: yes | client limit: 5000 | active clients: 1234"],
[{enabled: false, client_limit: 100, active_client_count: 0}, "embed enabled: no | client limit: 100 | active clients: 0"],
]) {
answers = [JSON.stringify(answer)];
assert.deepEqual(await embedRun(["status"]), {code: exitSuccess, out: [line], err: []});
assert.deepEqual(calls.at(-1), {method: "GET", apiPath: embedPath, body: undefined});
}
answers = [JSON.stringify({error: {message: "Invalid credential."}})];
const refusedStatus = await embedRun(["status"]);
assert.ok(refusedStatus.code === exitConfig && refusedStatus.out.length === 0 && refusedStatus.err.length === 1 &&
refusedStatus.err[0].includes("Invalid credential."), JSON.stringify(refusedStatus));
answers = [new ConfigError("the URnetwork API refused the root credential")];
assert.equal((await embedRun(["status"])).code, exitConfig);
answers = [notFoundError(embedPath)];
assert.deepEqual(await embedRun(["status"]), {code: exitFailure, out: [], err: [embedUnsupportedMessage]});
for (const answer of [{enabled: true}, {enabled: "yes", client_limit: 1, active_client_count: 1}, {enabled: true, client_limit: -1, active_client_count: 0},
{enabled: true, client_limit: 1.5, active_client_count: 0}, {enabled: 1, client_limit: 1, active_client_count: 1}, {enabled: true, client_limit: "1", active_client_count: 1}]) {
answers = [JSON.stringify(answer)];
const result = await embedRun(["status"]);
assert.ok(result.code === exitFailure && result.out.length === 0, JSON.stringify(answer));
}
assert.equal((await embedRun(["status", "extra"])).code, exitConfig);
// a pending_acl that is not a list of distinct mapped keys is refused untouched
const pendingFile = path.join(directory, "pending.json");
for (const map of [
{version: 1, clients: {}, pending_acl: ["user:x"]},
{version: 1, clients: {"user:x": client}, pending_acl: ["user:x", "user:x"]},
{version: 1, clients: {"user:x": client}, pending_acl: "user:x"},
{version: 1, clients: {"user:x": client}, pending_acl: [1]},
]) {
writePrivate(pendingFile, JSON.stringify(map));
const before = calls.length;
assert.equal(await runCommand(["provision", "user:x", jwtFile], {environment: {URNETWORK_CLIENT_MAP: pendingFile, URNETWORK_ROOT_JWT: root}, call, out: () => {}, err: () => {}}), exitConfig);
assert.equal(fs.readFileSync(pendingFile, "utf8"), JSON.stringify(map));
assert.equal(calls.length, before);
}
// the unmapped-key line, exactly, for each command that needs a mapping
for (const args of [["cap", "user:nobody", "--monthly", "1"], ["usage", "user:nobody"], ["remove", "user:nobody"], ["acl", "user:nobody", "default"]]) {
assert.equal(await isolated(args), exitConfig, args.join(" "));
assert.deepEqual(outputs, [unmappedMessage]);
}
// an invalid default ACL group
assert.equal(await runCommand(["provision", "user:x", jwtFile], {environment: {URNETWORK_CLIENT_MAP: aclFile, URNETWORK_ROOT_JWT: root, URNETWORK_DEFAULT_ACL_GROUP: "private"}, call, out: () => {}, err: line => outputs.push(line)}), exitConfig);
// missing settings
assert.equal(await runCommand(["usage-all"], {environment: {}, out: () => {}, err: () => {}}), exitConfig);
assert.equal(await runCommand(["usage-all"], {environment: {URNETWORK_CLIENT_MAP: file}, out: () => {}, err: () => {}}), exitConfig);
// the root credential never reaches the output
assert.ok(outputs.every(line => !line.includes(root)));
assert.throws(() => apiOrigin("http://example.com"));
assert.throws(() => apiOrigin("https://example.com/path"));
assert.equal(apiOrigin("http://127.0.0.1:1234"), "http://127.0.0.1:1234");
// the HTTP layer against a loopback stand-in: the root credential as the
// bearer, the exact body, int64 answers kept, a 401 as a credential error
const seen = [];
let olderServer = false;
const standIn = createServer((request, response) => {
const chunks = [];
request.on("data", chunk => chunks.push(chunk));
request.on("end", () => {
seen.push({authorization: request.headers.authorization, body: Buffer.concat(chunks).toString("utf8")});
if (olderServer) {
// a server that predates the data-cap and ACL routes
response.statusCode = 404;
response.end("404 page not found");
return;
}
response.statusCode = request.url === "/refused" ? 401 : 200;
response.end(request.url === "/refused" ? "{}" : capAnswer(client));
});
});
await new Promise(resolve => standIn.listen(0, "127.0.0.1", resolve));
try {
const httpCall = apiCaller(`http://127.0.0.1:${standIn.address().port}`, root);
const body = capBody(client, {monthly: "9223372036854775807"});
const answer = await httpCall("POST", "/network/client-data-cap", body);
assert.equal(answer.monthly_byte_limit, 9223372036854775807n);
assert.deepEqual(seen[0], {authorization: `Bearer ${root}`, body});
await assert.rejects(httpCall("GET", "/refused"), error => error instanceof ConfigError);
// an older server's 404s print the contract's lines, over HTTP
olderServer = true;
const olderEnvironment = {URNETWORK_CLIENT_MAP: aclFile, URNETWORK_ROOT_JWT: root, URNETWORK_API_URL: `http://127.0.0.1:${standIn.address().port}`};
for (const [args, line] of [
[["cap", "user:ivan", "--monthly", "1"], `${capPath} answered 404: the server predates the data-cap routes`],
[["usage", "user:ivan"], `${capPath} answered 404: the server predates the data-cap routes`],
[["usage-all"], `${capsPath} answered 404: the server predates the data-cap routes`],
[["acl", "user:ivan", "isolated"], aclUnsupportedMessage],
[["status"], embedUnsupportedMessage],
]) {
const lines = [];
assert.equal(await runCommand(args, {environment: olderEnvironment, out: () => {}, err: message => lines.push(message)}), exitFailure, args.join(" "));
assert.deepEqual(lines, [line]);
}
} finally {
await new Promise(resolve => standIn.close(resolve));
}
} finally {
fs.rmSync(directory, {recursive: true, force: true});
}
}
// Whether this module is the program's entry point.
function isEntryPoint() {
return typeof import.meta.main === "boolean"
? import.meta.main
: process.argv[1] !== undefined && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
}
if (isEntryPoint()) {
process.exitCode = await runCommand(process.argv.slice(2));
}