// SERVER ONLY. The C# embed backend tool (EMBED_CONTRACT.md, "Backend tools"):
// the integration allocator (../../integration/server) extended with what a
// backend needs to embed URnetwork. It provisions one client per user
// installation, sets and reads that client's data caps, reads every capped
// client of the network, removes a client, sets a client's ACL group, and
// reads the network's Embed state.
// Your service authenticates its user first and supplies the key internally:
// never take a key, a client ID or a cap from a raw request field.
//
// dotnet run -- provision <key> <client-jwt-file>
// dotnet run -- cap <key> [--monthly <bytes>|--monthly null] [--total <bytes>|--total null] [--reset-total]
// dotnet run -- usage <key>
// dotnet run -- usage-all
// dotnet run -- remove <key>
// dotnet run -- acl <key> default|isolated
// dotnet run -- status
// dotnet run -- --self-test
//
// <key> is user:<service-user-id> or user:<service-user-id>:<installation-id>.
// Settings: URNETWORK_ROOT_JWT (an API key or a network JWT, from the
// backend's secret store), URNETWORK_CLIENT_MAP (absolute path of this tool's
// private map, in an existing service-owned directory; never the token
// server's map), optional URNETWORK_API_URL and optional
// URNETWORK_DEFAULT_ACL_GROUP (the ACL group of each new client: "isolated",
// the default, or "default"). The map lock is an exclusively created
// <map>.lock file; a crash may leave it, so remove it only after confirming
// that no tool still runs.
//
// Exit codes: 0 success; 78 a 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.
using System.Globalization;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Text.RegularExpressions;
/// A failure with the exit code it maps to.
internal sealed class ToolException : Exception {
public int ExitCode { get; }
/// A failure with its exit code and its one stderr line.
public ToolException(int exitCode, string message) : base(message) {
ExitCode = exitCode;
}
}
/// One request to the URnetwork API, as the transport sees it.
internal sealed record ApiRequest(string Method, string PathAndQuery, string? Body);
/// The answer to one request: the HTTP status and the body.
internal sealed record ApiResponse(int Status, string Body);
/// The options of the cap command. A limit that is given with a null value
/// clears that cap; one that is not given is not sent, so the cap keeps its
/// value.
internal sealed class CapOptions {
public bool MonthlyGiven { get; set; }
public long? Monthly { get; set; }
public bool TotalGiven { get; set; }
public long? Total { get; set; }
public bool ResetTotal { get; set; }
}
/// The URnetwork API with the root credential.
internal sealed class Api {
private readonly Func<ApiRequest, Task<ApiResponse>> transport;
/// The API over a transport: HTTPS in production, a stand-in in the
/// self-test.
public Api(Func<ApiRequest, Task<ApiResponse>> transport) {
this.transport = transport;
}
/// The JSON object of a 2xx answer. HTTP 401 or 403 is the root credential
/// refused (78); another status, an unreachable API or a body that is not a
/// JSON object is a failure (1). A refusal inside the object (an "error"
/// member) is for the caller.
public JsonObject Call(string method, string pathAndQuery, JsonObject? body) {
ApiResponse response;
try {
response = transport(new ApiRequest(method, pathAndQuery, body?.ToJsonString()))
.GetAwaiter().GetResult();
} catch (Exception e) when (e is HttpRequestException or OperationCanceledException or IOException) {
throw new ToolException(Program.ExitFailure, "could not reach the URnetwork API");
}
if (response.Status is 401 or 403) {
throw new ToolException(Program.ExitConfig, "the URnetwork API refused the root credential");
}
if (response.Status == 404) {
// a server that predates a route (EMBED_CONTRACT.md, "Backend tools")
string route = pathAndQuery.Split('?')[0];
throw new ToolException(Program.ExitFailure,
route == Program.AclPath ? Program.AclUnsupportedMessage
: route == Program.EmbedPath ? Program.EmbedUnsupportedMessage
: route.StartsWith(Program.CapPath, StringComparison.Ordinal)
? $"{route} answered 404: the server predates the data-cap routes"
: $"{route} answered 404");
}
if (response.Status is < 200 or > 299) {
throw new ToolException(Program.ExitFailure, $"the URnetwork API answered HTTP {response.Status}");
}
JsonNode? node = null;
try {
node = JsonNode.Parse(response.Body);
} catch (JsonException) {
// reported below
}
return node as JsonObject ??
throw new ToolException(Program.ExitFailure, "the URnetwork API answered something other than a JSON object");
}
}
/// The tool's private map from keys to client ids, in the allocator's format:
/// {"version": 1, "clients": {key: client_id}}, plus "pending_acl", the keys
/// whose new clients still owe their default ACL group, written only while it
/// is not empty. It stores client ids, never tokens.
internal sealed class ClientMap {
public Dictionary<string, string> Clients { get; } = new();
public List<string> PendingAcl { get; } = new();
/// The map in file; an empty map when the file does not exist. A map with
/// fields this tool does not write, such as the token server's pending_caps,
/// is refused, so that two tools never rewrite each other's map.
public static ClientMap Load(string file) {
var map = new ClientMap();
var info = new FileInfo(file);
if (info.LinkTarget == null && !info.Exists) {
return map;
}
if (info.LinkTarget != null || info.Length > Program.ResponseLimit) {
throw Program.Config("the client map must be a regular file");
}
if (!OperatingSystem.IsWindows() && ((int)File.GetUnixFileMode(file) & 0x3f) != 0) {
throw Program.Config("the client map must be private (0600)");
}
JsonNode? node = null;
try {
node = JsonNode.Parse(File.ReadAllText(file));
} catch (JsonException) {
// reported below
}
if (node is not JsonObject root) {
throw Program.Config("the client map is not a JSON object");
}
foreach (var (name, _) in root) {
if (name is not ("version" or "clients" or "pending_acl")) {
throw Program.Config(
"the client map has fields this tool does not write, such as the token server's pending_caps; give each tool its own map");
}
}
if (root["version"] is not JsonValue version || !version.TryGetValue(out int versionNumber) ||
versionNumber != 1 || root["clients"] is not JsonObject clients) {
throw Program.Config("the client map is not version 1 with a clients object");
}
var seen = new HashSet<string>();
foreach (var (key, value) in clients) {
string? id = Program.Text(value);
if (!Program.Keys.IsMatch(key) || id == null || !Program.Ids.IsMatch(id) || !seen.Add(id)) {
throw Program.Config("the client map has an invalid entry");
}
map.Clients[key] = id;
}
if (root.ContainsKey("pending_acl")) {
if (root["pending_acl"] is not JsonArray pending) {
throw Program.Config("the client map's pending_acl is not a list of mapped keys");
}
foreach (JsonNode? entry in pending) {
string? key = Program.Text(entry);
if (key == null || !map.Clients.ContainsKey(key) || map.PendingAcl.Contains(key)) {
throw Program.Config("the client map's pending_acl is not a list of mapped keys");
}
map.PendingAcl.Add(key);
}
}
return map;
}
/// Replaces file atomically with this map, private to its owner.
public void Save(string file) {
var clients = new JsonObject();
foreach (var (key, id) in Clients) {
clients[key] = id;
}
var root = new JsonObject { ["version"] = 1, ["clients"] = clients };
if (PendingAcl.Count > 0) {
root["pending_acl"] = new JsonArray(PendingAcl.Select(key => (JsonNode?)key).ToArray());
}
Program.WritePrivate(file, Encoding.UTF8.GetBytes(root.ToJsonString()));
}
}
/// The map's exclusive lock: a <map>.lock file created exclusively and held
/// through the remote calls and the map update. The other languages' tools
/// create a <map>.lock directory at the same path, so they exclude each other.
internal sealed class MapLock : IDisposable {
private readonly FileStream stream;
private readonly string path;
private MapLock(FileStream stream, string path) {
this.stream = stream;
this.path = path;
}
/// Takes the lock of mapFile, or fails when another run holds it.
public static MapLock Take(string mapFile) {
string path = mapFile + ".lock";
try {
return new MapLock(Program.CreatePrivate(path), path);
} catch (Exception e) when ((e is IOException or UnauthorizedAccessException) &&
(File.Exists(path) || Directory.Exists(path))) {
throw new ToolException(
Program.ExitFailure,
"another run holds the client map's lock; retry, and remove a stale .lock only after confirming that no tool still runs");
}
}
/// Releases the lock.
public void Dispose() {
stream.Dispose();
File.Delete(path);
}
}
/// Commands, settings and the API requests of the tool.
internal static class Program {
public const int ExitOk = 0;
public const int ExitFailure = 1;
// sysexits EX_CONFIG
public const int ExitConfig = 78;
public const int ResponseLimit = 1 << 20;
public const string Description = "embed client";
public const string DeviceSpec = "urnetwork-examples/csharp-embed-server";
public const string ClientDoesNotExist = "Client does not exist.";
public const string ClientLimitMessage =
"client limit reached: your network is at its client limit; see https://ur.io/services";
public const string AuthClientPath = "/network/auth-client";
public const string CapPath = "/network/client-data-cap";
public const string CapsPath = "/network/client-data-caps";
public const string RemovePath = "/network/remove-client";
public const string AclPath = "/network/client-acl-group";
public const string EmbedPath = "/network/embed";
public const string UnmappedMessage = "no client is mapped for that key; run provision first";
public const string 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.
public const string EmbedNotEnabledMessage = "Embed isn't enabled for this network.";
// cap, usage, usage-all and acl print this for the refusal and exit 78
public const string 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
public const string EmbedPendingLine =
"embed not enabled: the client's defaults stay pending until Embed is enabled; see https://ur.io/services";
public const string EmbedUnsupportedMessage = "/network/embed answered 404: the server predates Embed enablement";
public const string Usage =
"usage: provision <key> <client-jwt-file> | cap <key> [--monthly <bytes>|--monthly null] [--total <bytes>|--total null] [--reset-total] | usage <key> | usage-all | remove <key> | acl <key> default|isolated | status | --self-test";
public static readonly Regex Keys = new(@"\Auser:[A-Za-z0-9][A-Za-z0-9_.:@-]{0,122}\z");
public static readonly Regex Ids = new(@"\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z");
private static readonly Regex ByteCounts = new(@"\A[0-9]{1,19}\z");
/// The API for an origin and root credential.
public delegate Func<ApiRequest, Task<ApiResponse>> TransportFactory(Uri origin, string root);
/// The settings of one run: the API and, for the commands that use it, the
/// map file, and the ACL group of each new client ("isolated" or "default").
private sealed record ToolSettings(Api Api, string? MapFile, string AclGroup);
/// "client_id" is mapped to a client that no longer exists.
private sealed class ClientMissingException : Exception {}
/// Runs the command with the process environment and HTTPS.
public static int Main(string[] args) {
return Run(args, Environment.GetEnvironmentVariable, Console.Out, Console.Error, HttpTransport);
}
/// Runs one command and returns its exit code. The self-test passes its own
/// environment, writers and stand-in transport.
public static int Run(string[] args, Func<string, string?> env, TextWriter stdout, TextWriter stderr,
TransportFactory transport) {
try {
switch (args) {
case ["--self-test"]:
try {
SelfTest.Run();
} catch (Exception e) {
// a tool failure inside a check fails the self-test too
stderr.WriteLine($"embed backend tool self-test failed: {e.Message}");
return ExitFailure;
}
stdout.WriteLine("embed backend tool self-test passed");
return ExitOk;
case ["provision", var key, var jwtFile]:
Provision(CheckKey(key), CheckJwtFile(jwtFile), Settings(env, transport, map: true), stdout, stderr);
return ExitOk;
case ["cap", var key, .. var options]:
Cap(CheckKey(key), ParseCapOptions(options), Settings(env, transport, map: true), stdout);
return ExitOk;
case ["usage", var key]:
ReadUsage(CheckKey(key), Settings(env, transport, map: true), stdout);
return ExitOk;
case ["usage-all"]:
ReadUsageAll(Settings(env, transport, map: false), stdout);
return ExitOk;
case ["remove", var key]:
Remove(CheckKey(key), Settings(env, transport, map: true), stdout);
return ExitOk;
case ["acl", var key, var group]:
Acl(CheckKey(key), group is "default" or "isolated" ? group : throw Config(Usage),
Settings(env, transport, map: true), stdout);
return ExitOk;
case ["status"]:
Status(Settings(env, transport, map: false), stdout);
return ExitOk;
default:
throw Config(Usage);
}
} catch (ToolException e) {
stderr.WriteLine(e.Message);
return e.ExitCode;
} catch (Exception e) when (e is IOException or UnauthorizedAccessException) {
stderr.WriteLine($"embed backend tool failed: {e.Message}");
return ExitFailure;
}
}
/// A configuration error (78).
public static ToolException Config(string message) => new(ExitConfig, message);
/// The API refused a request (1), with its message made safe to print.
private static ToolException Refused(string message) =>
new(ExitFailure, $"the URnetwork API refused the request: {Printable(message)}");
/// Reissues the key's client, or provisions a new one, and writes the
/// client JWT to jwtFile. A reissue that answers "Client does not exist."
/// (a client deactivated after 30 days without connecting) drops the
/// mapping and provisions a new client. Prints {"client_id": ...}, never the
/// token. While Embed isn't enabled the default ACL group stays pending, with
/// a line on stderr, and a provision after the team enables Embed applies it.
private static void Provision(string key, string jwtFile, ToolSettings settings, TextWriter stdout,
TextWriter stderr) {
string mapFile = settings.MapFile!;
using MapLock _ = MapLock.Take(mapFile);
ClientMap map = ClientMap.Load(mapFile);
(string ClientId, string Jwt)? result = null;
if (map.Clients.TryGetValue(key, out string? mapped)) {
try {
result = AuthClientResult(settings.Api.Call("POST", AuthClientPath, AuthClientBody(mapped)), mapped);
} catch (ClientMissingException) {
map.Clients.Remove(key);
map.PendingAcl.Remove(key);
map.Save(mapFile);
}
}
if (result == null) {
try {
result = AuthClientResult(settings.Api.Call("POST", AuthClientPath, AuthClientBody(null)), null);
} catch (ClientMissingException) {
throw Refused(ClientDoesNotExist);
}
if (map.Clients.ContainsValue(result.Value.ClientId)) {
throw new ToolException(ExitFailure, "the API answered a client that the map assigns to another key");
}
map.Clients[key] = result.Value.ClientId;
// the mapping and the record that the client owes its group, in one save
if (settings.AclGroup == "isolated") {
map.PendingAcl.Add(key);
}
map.Save(mapFile);
}
bool embedEnabled = true;
if (map.PendingAcl.Contains(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 (settings.AclGroup == "isolated") {
embedEnabled = PostAclGroup(settings.Api, result.Value.ClientId, "isolated", allowNotEnabled: true);
}
// while Embed isn't enabled the record stays and the client works
if (embedEnabled) {
map.PendingAcl.Remove(key);
map.Save(mapFile);
}
}
WritePrivate(jwtFile, Encoding.UTF8.GetBytes(result.Value.Jwt + "\n"));
stdout.WriteLine(new JsonObject { ["client_id"] = result.Value.ClientId }.ToJsonString());
if (!embedEnabled) {
stderr.WriteLine(EmbedPendingLine);
}
}
/// Posts only the given cap fields for the key's client and prints the cap
/// object.
private static void Cap(string key, CapOptions options, ToolSettings settings, TextWriter stdout) {
using MapLock _ = MapLock.Take(settings.MapFile!);
string clientId = MappedClient(ClientMap.Load(settings.MapFile!), key);
stdout.WriteLine(CapObject(settings.Api.Call("POST", CapPath, CapBody(clientId, options))));
}
/// Prints the key's cap object, read with the root credential.
private static void ReadUsage(string key, ToolSettings settings, TextWriter stdout) {
using MapLock _ = MapLock.Take(settings.MapFile!);
string clientId = MappedClient(ClientMap.Load(settings.MapFile!), key);
stdout.WriteLine(CapObject(settings.Api.Call(
"GET", CapPath + "?client_id=" + Uri.EscapeDataString(clientId), null)));
}
/// Pages through every capped client of the network, 1000 at a time, and
/// prints one cap object per line. It stops at a null cursor or a repeated
/// one.
private static void ReadUsageAll(ToolSettings settings, TextWriter stdout) {
var seenCursors = new HashSet<string>();
string? cursor = null;
while (true) {
string path = CapsPath + "?limit=1000" + (cursor == null ? "" : "&cursor=" + Uri.EscapeDataString(cursor));
JsonObject page = settings.Api.Call("GET", path, null);
CheckRefusal(page);
if (page["clients"] is not JsonArray clients) {
throw new ToolException(ExitFailure, "the URnetwork API answered a page without clients");
}
foreach (JsonNode? client in clients) {
if (client is not JsonObject capObject) {
throw new ToolException(ExitFailure, "the URnetwork API answered a client that is not a cap object");
}
stdout.WriteLine(capObject.ToJsonString());
}
string? next = Text(page["next_cursor"]);
if (string.IsNullOrEmpty(next) || !seenCursors.Add(next)) {
return;
}
cursor = next;
}
}
/// Removes the key's client, then its mapping, also when the client is
/// already gone. Prints {"removed": ...}.
private static void Remove(string key, ToolSettings settings, TextWriter stdout) {
string mapFile = settings.MapFile!;
using MapLock _ = MapLock.Take(mapFile);
ClientMap map = ClientMap.Load(mapFile);
string clientId = MappedClient(map, key);
JsonObject answer = settings.Api.Call("POST", RemovePath, new JsonObject { ["client_id"] = clientId });
if (answer["error"] is { } error) {
string message = error is JsonObject errorObject ? Text(errorObject["message"]) ?? "" : "";
if (message != ClientDoesNotExist) {
throw Refused(message);
}
}
map.Clients.Remove(key);
map.PendingAcl.Remove(key);
map.Save(mapFile);
stdout.WriteLine(new JsonObject { ["removed"] = clientId }.ToJsonString());
}
/// Sets the ACL group of the key's client and prints {"client_id": ...,
/// "acl_group": ...}. An explicit group settles a pending default group, so
/// the record is dropped.
private static void Acl(string key, string group, ToolSettings settings, TextWriter stdout) {
string mapFile = settings.MapFile!;
using MapLock _ = MapLock.Take(mapFile);
ClientMap map = ClientMap.Load(mapFile);
string clientId = MappedClient(map, key);
PostAclGroup(settings.Api, clientId, group);
if (map.PendingAcl.Remove(key)) {
map.Save(mapFile);
}
stdout.WriteLine($"{{\"client_id\":\"{clientId}\",\"acl_group\":\"{group}\"}}");
}
/// Posts the client's ACL group; the answer must name the client and the
/// group. A refusal or another answer fails (1), and the Embed-not-enabled
/// refusal exits 78, or returns false when allowNotEnabled is set.
private static bool PostAclGroup(Api api, string clientId, string group, bool allowNotEnabled = false) {
JsonObject answer = api.Call("POST", AclPath, new JsonObject { ["client_id"] = clientId, ["acl_group"] = group });
if (allowNotEnabled && EmbedNotEnabled(answer)) {
return false;
}
CheckRefusal(answer);
if (Text(answer["client_id"]) != clientId || Text(answer["acl_group"]) != group) {
throw new ToolException(ExitFailure, "the URnetwork API answered another client or ACL group");
}
return true;
}
/// Prints 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 (78).
private static void Status(ToolSettings settings, TextWriter stdout) {
JsonObject answer = settings.Api.Call("GET", EmbedPath, null);
if (answer["error"] is { } error) {
string message = error is JsonObject errorObject ? Text(errorObject["message"]) ?? "" : "";
throw Config($"the URnetwork API refused the request: {Printable(message)}");
}
if (answer["enabled"] is not JsonValue enabledValue || !enabledValue.TryGetValue(out bool enabled) ||
Count(answer["client_limit"]) is not long clientLimit ||
Count(answer["active_client_count"]) is not long activeClientCount) {
throw new ToolException(ExitFailure, "the URnetwork API answered network/embed with something invalid");
}
stdout.WriteLine(string.Create(CultureInfo.InvariantCulture,
$"embed enabled: {(enabled ? "yes" : "no")} | client limit: {clientLimit} | active clients: {activeClientCount}"));
}
/// A non-negative JSON integer, or null.
private static long? Count(JsonNode? node) {
return node is JsonValue value && value.GetValueKind() == JsonValueKind.Number &&
value.TryGetValue(out long count) && count >= 0
? count
: null;
}
/// The auth-client request: a new client without client_id, or a reissue of
/// the mapped one. Never source_client_id: embed clients are top-level.
public static JsonObject AuthClientBody(string? clientId) {
var body = new JsonObject { ["description"] = Description, ["device_spec"] = DeviceSpec };
if (clientId != null) {
body["client_id"] = clientId;
}
return body;
}
/// The client id and client JWT of an auth-client answer. A refusal with
/// either client limit flag is the client limit (78); "Client does not
/// exist." throws ClientMissingException; other refusals fail. The JWT's
/// client_id claim must match the answer, and a reissue must answer the
/// mapped client. The claim check is not signature verification.
private static (string ClientId, string Jwt) AuthClientResult(JsonObject answer, string? expected) {
if (answer["error"] is { } errorNode) {
if (errorNode is JsonObject error) {
if (Flag(error, "client_limit_exceeded") || Flag(error, "upgrade_required")) {
throw new ToolException(ExitConfig, ClientLimitMessage);
}
if (Text(error["message"]) == ClientDoesNotExist) {
throw new ClientMissingException();
}
throw Refused(Text(error["message"]) ?? "");
}
throw Refused("");
}
string id = Text(answer["client_id"]) ?? "";
string jwt = Text(answer["by_client_jwt"]) ?? "";
string[] parts = jwt.Split('.');
if (!Ids.IsMatch(id) || parts.Length != 3 || parts.Any(string.IsNullOrEmpty) ||
!Regex.IsMatch(parts[1], @"\A[A-Za-z0-9_-]+\z")) {
throw new ToolException(ExitFailure, "the URnetwork API answered an invalid client");
}
string? claim = null;
try {
using var claims = JsonDocument.Parse(DecodeBase64Url(parts[1]));
if (claims.RootElement.ValueKind == JsonValueKind.Object &&
claims.RootElement.TryGetProperty("client_id", out var claimValue) &&
claimValue.ValueKind == JsonValueKind.String) {
claim = claimValue.GetString();
}
} catch (Exception e) when (e is JsonException or FormatException) {
// reported below
}
if (claim != id || (expected != null && expected != id)) {
throw new ToolException(ExitFailure, "the URnetwork API answered a client JWT for another client");
}
return (id, jwt);
}
/// The cap request: client_id and only the given fields. A cleared cap is
/// JSON null; byte counts are JSON integers; reset_total only when given.
public static JsonObject CapBody(string clientId, CapOptions options) {
var body = new JsonObject { ["client_id"] = clientId };
if (options.MonthlyGiven) {
body["monthly_byte_limit"] = options.Monthly is long monthly ? JsonValue.Create(monthly) : null;
}
if (options.TotalGiven) {
body["total_byte_limit"] = options.Total is long total ? JsonValue.Create(total) : null;
}
if (options.ResetTotal) {
body["reset_total"] = true;
}
return body;
}
/// The cap options; at least one, each at most once. A usage error is a
/// configuration error (78).
public static CapOptions ParseCapOptions(string[] args) {
const string usage =
"cap needs at least one of --monthly <bytes>|null, --total <bytes>|null and --reset-total, each at most once";
var options = new CapOptions();
int index = 0;
while (index < args.Length) {
string option = args[index];
bool hasValue = index + 1 < args.Length;
if (option == "--monthly" && !options.MonthlyGiven && hasValue) {
options.MonthlyGiven = true;
options.Monthly = ByteLimit(args[index + 1]);
index += 2;
} else if (option == "--total" && !options.TotalGiven && hasValue) {
options.TotalGiven = true;
options.Total = ByteLimit(args[index + 1]);
index += 2;
} else if (option == "--reset-total" && !options.ResetTotal) {
options.ResetTotal = true;
index += 1;
} else {
throw Config(usage);
}
}
if (!options.MonthlyGiven && !options.TotalGiven && !options.ResetTotal) {
throw Config(usage);
}
return options;
}
/// A byte count from 0 to 9223372036854775807 without units, or null.
private static long? ByteLimit(string text) {
if (text == "null") {
return null;
}
if (!ByteCounts.IsMatch(text) ||
!long.TryParse(text, NumberStyles.None, CultureInfo.InvariantCulture, out long value)) {
throw Config("a byte count is a decimal integer from 0 to 9223372036854775807 without units, or null");
}
return value;
}
/// The cap object of an answer, as one line of JSON; a refusal fails.
private static string CapObject(JsonObject answer) {
CheckRefusal(answer);
return answer.ToJsonString();
}
/// Fails when an answer carries a refusal: the Embed-not-enabled refusal is
/// a configuration error (78) with the fixed line, another one fails (1).
private static void CheckRefusal(JsonObject answer) {
if (EmbedNotEnabled(answer)) {
throw Config(EmbedNotEnabledLine);
}
if (answer["error"] is { } error) {
throw Refused(error is JsonObject errorObject ? Text(errorObject["message"]) ?? "" : "");
}
}
/// Whether an answer is the Embed-not-enabled refusal.
private static bool EmbedNotEnabled(JsonObject answer) {
return answer["error"] is JsonObject error && Text(error["message"]) == EmbedNotEnabledMessage;
}
/// The client mapped to key; an unmapped key is a configuration error.
private static string MappedClient(ClientMap map, string key) {
return map.Clients.TryGetValue(key, out string? clientId)
? clientId
: throw Config(UnmappedMessage);
}
/// A valid key: user:<service-user-id>, optionally with :<installation-id>.
private static string CheckKey(string key) {
return Keys.IsMatch(key) ? key : throw Config("expected a key user:<service-user-id>[:<installation-id>]");
}
/// The client JWT file: its directory must exist; a symlink is refused.
private static string CheckJwtFile(string path) {
string full;
try {
full = Path.GetFullPath(path);
} catch (Exception e) when (e is ArgumentException or NotSupportedException or PathTooLongException) {
throw Config("the client JWT file path is not valid");
}
if (!Directory.Exists(Path.GetDirectoryName(full)) || Directory.Exists(full) ||
new FileInfo(full).LinkTarget != null) {
throw Config("the client JWT file needs an existing directory and must not be a symlink");
}
return full;
}
/// The settings, checked: the root credential, the API origin and, when the
/// command uses it, the map file.
private static ToolSettings Settings(Func<string, string?> env, TransportFactory transport, bool map) {
string root = env("URNETWORK_ROOT_JWT") ?? "";
if (root.Length == 0 || root.Any(c => c <= ' ' || c > '~')) {
throw Config("set URNETWORK_ROOT_JWT to the root credential (an API key or a network JWT) from the backend's secret store");
}
Uri origin = Endpoint(env("URNETWORK_API_URL") ?? "https://api.bringyour.com");
string? mapFile = null;
if (map) {
mapFile = env("URNETWORK_CLIENT_MAP");
if (string.IsNullOrEmpty(mapFile) || !Path.IsPathFullyQualified(mapFile) ||
!Directory.Exists(Path.GetDirectoryName(mapFile))) {
throw Config("set URNETWORK_CLIENT_MAP to an absolute file path in an existing private, service-owned directory");
}
}
string aclGroup = env("URNETWORK_DEFAULT_ACL_GROUP") ?? "";
if (aclGroup is not ("" or "isolated" or "default")) {
throw Config("URNETWORK_DEFAULT_ACL_GROUP must be default or isolated");
}
return new ToolSettings(new Api(transport(origin, root)), mapFile, aclGroup == "" ? "isolated" : aclGroup);
}
/// The API origin: HTTPS, or explicit loopback HTTP for local mocks; no
/// credentials, path, query or fragment.
public static Uri Endpoint(string value) {
if (!Uri.TryCreate(value, UriKind.Absolute, out Uri? u)) {
throw Config("URNETWORK_API_URL must be an HTTPS origin");
}
bool local = u.Host is "localhost" or "127.0.0.1" or "[::1]" or "::1";
if (u.Host.Length == 0 || u.UserInfo.Length != 0 || u.AbsolutePath != "/" || u.Query.Length != 0 ||
u.Fragment.Length != 0 || (u.Scheme != "https" && !(u.Scheme == "http" && local))) {
throw Config("URNETWORK_API_URL must be an HTTPS origin, or explicit loopback HTTP for a mock");
}
return new Uri(u.GetLeftPart(UriPartial.Authority) + "/");
}
/// HTTPS to the API with the root credential: 15 seconds, no redirects, a
/// bounded answer.
private static Func<ApiRequest, Task<ApiResponse>> HttpTransport(Uri origin, string root) {
var client = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false }) {
Timeout = TimeSpan.FromSeconds(15),
};
return async request => {
using var message = new HttpRequestMessage(new HttpMethod(request.Method), new Uri(origin, request.PathAndQuery));
message.Headers.Authorization = new AuthenticationHeaderValue("Bearer", root);
if (request.Body != null) {
message.Content = new StringContent(request.Body, Encoding.UTF8, "application/json");
}
using HttpResponseMessage response = await client.SendAsync(message, HttpCompletionOption.ResponseHeadersRead);
using Stream input = await response.Content.ReadAsStreamAsync();
using var output = new MemoryStream();
var buffer = new byte[8192];
int count;
while ((count = await input.ReadAsync(buffer)) != 0) {
if (output.Length + count > ResponseLimit) {
throw new IOException("the answer is too large");
}
output.Write(buffer, 0, count);
}
return new ApiResponse((int)response.StatusCode, Encoding.UTF8.GetString(output.ToArray()));
};
}
/// A string JSON value, or null.
public static string? Text(JsonNode? node) {
return node is JsonValue value && value.TryGetValue(out string? text) ? text : null;
}
/// Whether a member is JSON true.
private static bool Flag(JsonObject obj, string name) {
return obj[name] is JsonValue value && value.TryGetValue(out bool flag) && flag;
}
/// Text safe for one stderr line: no control characters, bounded.
private static string Printable(string text) {
return new string(text.Select(c => char.IsControl(c) ? ' ' : c).Take(200).ToArray()).Trim();
}
/// Unpadded base64url.
private static byte[] DecodeBase64Url(string part) {
return Convert.FromBase64String(part.Replace('-', '+').Replace('_', '/') +
new string('=', (4 - part.Length % 4) % 4));
}
/// Creates a new file exclusively, private to its owner on POSIX.
public static FileStream CreatePrivate(string file) {
var options = new FileStreamOptions { Mode = FileMode.CreateNew, Access = FileAccess.Write, Share = FileShare.None };
if (!OperatingSystem.IsWindows()) {
options.UnixCreateMode = UnixFileMode.UserRead | UnixFileMode.UserWrite;
}
return new FileStream(file, options);
}
/// Replaces file atomically: a private temporary file in the same
/// directory, synced, then renamed over it.
public static void WritePrivate(string file, byte[] data) {
string temp = Path.Combine(Path.GetDirectoryName(file) ?? ".",
"." + Path.GetFileName(file) + "." + Guid.NewGuid().ToString("N"));
try {
using (FileStream output = CreatePrivate(temp)) {
output.Write(data);
output.Flush(true);
}
File.Move(temp, file, true);
} finally {
if (File.Exists(temp)) {
File.Delete(temp);
}
}
}
}