Developer SDK

C# examples

Install the SDK · View source on GitHub ↗

provider/State.cs

c#
// Installation state for one provider install, kept in one private directory
// named by URNETWORK_PROVIDER_STATE_DIR (PROVIDER_CONTRACT.md, "Installation
// state"):
//
//   - client.jwt: the scoped client credential that the developer's backend
//     issued for this installation. The developer writes it; the app rewrites
//     it whenever the SDK refreshes the token.
//   - instance-id: this installation's UUID, created on first run.
//   - identity.json: the provider identity (client key seed, provide TLS
//     certificate and key, extender seed), created on first run so the
//     provider keeps one identity across restarts.
//
// Every file is replaced atomically with owner-only permissions. On POSIX the
// directory and its files must not be accessible to group or others, and a
// symlinked file is refused; Windows relies on the access control of the
// user's profile directory. This is managed code only: the self-test checks
// it without the native SDK runtime.
using System.Diagnostics.CodeAnalysis;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

/// A configuration or credential problem that restarting does not fix (exit
/// 78).
internal sealed class ProviderConfigException : Exception {
  /// A configuration error with the reason to show.
  public ProviderConfigException(string message) : base(message) {}
}

/// UUID text in the forms the SDK parses: 36 characters with dashes or 32 hex
/// digits, in either case. The canonical form is lowercase with dashes, as the
/// SDK writes ids.
internal static class Uuid {
  public const string Zero = "00000000-0000-0000-0000-000000000000";

  /// The canonical form, or null when the text is not a UUID.
  public static string? Parse(string? text) {
    if (text != null && (Guid.TryParseExact(text, "D", out var id) ||
                         Guid.TryParseExact(text, "N", out id))) {
      return id.ToString("D");
    }
    return null;
  }
}

/// identity.json. Byte fields are standard base64 in JSON. An identity belongs
/// to one client: a newly provisioned client gets a new identity.
internal sealed class ProviderIdentity {
  public const int CurrentVersion = 1;

  [JsonPropertyName("version")]
  public int Version { get; set; }
  [JsonPropertyName("client_id")]
  public string ClientId { get; set; } = "";
  [JsonPropertyName("client_key_seed")]
  public byte[]? ClientKeySeed { get; set; }
  [JsonPropertyName("provide_tls_certificate_pem")]
  public byte[]? ProvideTlsCertificatePem { get; set; }
  [JsonPropertyName("provide_tls_private_key_pem")]
  public byte[]? ProvideTlsPrivateKeyPem { get; set; }
  [JsonPropertyName("extender_key_seed")]
  [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
  public byte[]? ExtenderKeySeed { get; set; }
}

/// The installation state loaded at start.
internal sealed class ProviderConfig {
  public required string StateDir { get; init; }
  public required string ClientJwt { get; init; }
  // the client_id claim of ClientJwt
  public required string ClientId { get; init; }
  public required string InstanceId { get; init; }
  // null on first run, and when the stored identity belongs to another client
  public required ProviderIdentity? Identity { get; init; }

  /// Loads the installation state, creating instance-id on first run. Every
  /// error is a configuration error: restarting does not fix it.
  public static ProviderConfig Load(string? stateDir) {
    StateFiles.CheckStateDir(stateDir);
    byte[] clientJwtBytes =
        StateFiles.ReadStateFile(stateDir, StateFiles.ClientJwtFileName) ??
        throw new ProviderConfigException(
            $"read {StateFiles.ClientJwtFileName} from the state directory: the file does not exist; write the scoped client JWT from your backend");
    string clientJwt = StateFiles.DecodeText(clientJwtBytes).Trim();
    string clientId = StateFiles.ParseClientJwtClientId(clientJwt);
    string instanceId = StateFiles.LoadOrCreateInstanceId(stateDir);
    ProviderIdentity? identity = StateFiles.LoadProviderIdentity(stateDir, clientId);
    return new ProviderConfig {
      StateDir = stateDir,
      ClientJwt = clientJwt,
      ClientId = clientId,
      InstanceId = instanceId,
      Identity = identity,
    };
  }
}

/// The files of the state directory.
internal static class StateFiles {
  public const string ClientJwtFileName = "client.jwt";
  public const string InstanceIdFileName = "instance-id";
  public const string IdentityFileName = "identity.json";

  // the largest state file the app reads
  public const int StateFileByteLimit = 64 * 1024;

  // the permission bits that make a file or directory accessible to group or
  // others (0o077)
  public const UnixFileMode GroupOrOtherAccess =
      UnixFileMode.GroupRead | UnixFileMode.GroupWrite |
      UnixFileMode.GroupExecute | UnixFileMode.OtherRead |
      UnixFileMode.OtherWrite | UnixFileMode.OtherExecute;

  /// The state directory must be an existing absolute directory, private to
  /// its owner on POSIX. A symlinked directory is checked at its target.
  public static void CheckStateDir([NotNull] string? stateDir) {
    if (string.IsNullOrEmpty(stateDir)) {
      throw new ProviderConfigException(
          "set URNETWORK_PROVIDER_STATE_DIR to this installation's private state directory");
    }
    if (!Path.IsPathFullyQualified(stateDir)) {
      throw new ProviderConfigException(
          "URNETWORK_PROVIDER_STATE_DIR must be an absolute path");
    }
    if (!Directory.Exists(stateDir)) {
      throw new ProviderConfigException(
          File.Exists(stateDir)
              ? "URNETWORK_PROVIDER_STATE_DIR is not a directory"
              : $"state directory {stateDir} does not exist");
    }
    if (!OperatingSystem.IsWindows() &&
        (File.GetUnixFileMode(stateDir) & GroupOrOtherAccess) != 0) {
      throw new ProviderConfigException(
          "the state directory must be private to its owner (chmod 700)");
    }
  }

  /// Reads a regular, private state file of bounded size; null when it does
  /// not exist. A symlink is refused so that the credential cannot be
  /// redirected to another file. Other problems throw IOException.
  public static byte[]? ReadPrivateFile(string path) {
    // FileInfo reads the path itself: a dangling symlink exists and has a target
    var info = new FileInfo(path);
    if (info.LinkTarget == null && !info.Exists && !Directory.Exists(path)) {
      return null;
    }
    if (info.LinkTarget != null || !info.Exists) {
      throw new IOException("not a regular file");
    }
    if (StateFileByteLimit < info.Length) {
      throw new IOException("file is too large");
    }
    if (!OperatingSystem.IsWindows() &&
        (File.GetUnixFileMode(path) & GroupOrOtherAccess) != 0) {
      throw new IOException("file must be private to its owner (chmod 600)");
    }
    return File.ReadAllBytes(path);
  }

  /// Replaces a state file atomically: a private temporary file in the same
  /// directory is written, synced and renamed over the old file.
  public static void WritePrivateFile(string path, byte[] data) {
    string directory = Path.GetDirectoryName(path) ?? ".";
    string tempPath = Path.Combine(
        directory, "." + Path.GetFileName(path) + "." + Guid.NewGuid().ToString("N"));
    try {
      var options = new FileStreamOptions {
        Mode = FileMode.CreateNew,
        Access = FileAccess.Write,
        Share = FileShare.None,
      };
      if (!OperatingSystem.IsWindows()) {
        options.UnixCreateMode = UnixFileMode.UserRead | UnixFileMode.UserWrite;
      }
      using (var file = new FileStream(tempPath, options)) {
        file.Write(data);
        file.Flush(flushToDisk: true);
      }
      File.Move(tempPath, path, overwrite: true);
    } finally {
      if (File.Exists(tempPath)) {
        File.Delete(tempPath);
      }
    }
  }

  /// One file of the state directory, null when it does not exist. Every other
  /// problem is a configuration error that names the file.
  public static byte[]? ReadStateFile(string stateDir, string fileName) {
    try {
      return ReadPrivateFile(Path.Combine(stateDir, fileName));
    } catch (Exception e) when (e is IOException or UnauthorizedAccessException) {
      throw new ProviderConfigException(
          $"read {fileName} from the state directory: {e.Message}");
    }
  }

  /// The text of a state file: UTF-8, or the encoding its byte order mark names
  /// (Windows PowerShell 5 writes UTF-16 with one).
  public static string DecodeText(byte[] data) {
    using var reader = new StreamReader(new MemoryStream(data), Encoding.UTF8,
                                        detectEncodingFromByteOrderMarks: true);
    return reader.ReadToEnd();
  }

  /// The client_id claim of a scoped client JWT, in canonical form. This checks
  /// the token's shape and claim only; the SDK and the server verify the token
  /// itself.
  public static string ParseClientJwtClientId(string clientJwt) {
    const string notJwt =
        "client.jwt does not hold a JWT; write the scoped client JWT from your backend";
    string[] parts = clientJwt.Split('.');
    if (parts.Length != 3 || parts.Any(part => part.Length == 0)) {
      throw new ProviderConfigException(notJwt);
    }
    byte[] payload = DecodeBase64Url(parts[1].TrimEnd('=')) ??
                     throw new ProviderConfigException(notJwt);
    string claim = "";
    try {
      using var claims = JsonDocument.Parse(payload);
      if (claims.RootElement.ValueKind == JsonValueKind.Object &&
          claims.RootElement.TryGetProperty("client_id", out var clientId) &&
          clientId.ValueKind == JsonValueKind.String) {
        claim = clientId.GetString() ?? "";
      }
    } catch (Exception e) when (e is JsonException or ArgumentException or
                                    InvalidOperationException) {
      // not a JSON object: no claim
    }
    if (claim == "") {
      throw new ProviderConfigException(
          "client.jwt has no client_id claim; write a scoped client JWT, not a network JWT");
    }
    return Uuid.Parse(claim) ??
           throw new ProviderConfigException("client.jwt has an invalid client_id claim");
  }

  /// Unpadded base64url, as JWT parts are encoded; null when the text is not.
  private static byte[]? DecodeBase64Url(string text) {
    if (text.Length % 4 == 1 ||
        text.Any(c => !char.IsAsciiLetterOrDigit(c) && c != '-' && c != '_')) {
      return null;
    }
    string base64 = text.Replace('-', '+').Replace('_', '/') +
                    new string('=', (4 - text.Length % 4) % 4);
    try {
      return Convert.FromBase64String(base64);
    } catch (FormatException) {
      return null;
    }
  }

  /// Reads instance-id, creating it on first run. An installation keeps one
  /// instance id for its lifetime.
  public static string LoadOrCreateInstanceId(string stateDir) {
    byte[]? data = ReadStateFile(stateDir, InstanceIdFileName);
    if (data != null) {
      return Uuid.Parse(DecodeText(data).Trim()) ??
             throw new ProviderConfigException($"{InstanceIdFileName} does not hold a UUID");
    }
    string instanceId = Guid.NewGuid().ToString("D");
    try {
      WritePrivateFile(Path.Combine(stateDir, InstanceIdFileName),
                       Encoding.UTF8.GetBytes(instanceId + "\n"));
    } catch (Exception e) when (e is IOException or UnauthorizedAccessException) {
      throw new ProviderConfigException($"write {InstanceIdFileName}: {e.Message}");
    }
    return instanceId;
  }

  /// Reads identity.json for clientId. A missing file, or an identity of
  /// another client, returns null: the device then creates a new identity,
  /// which the app saves.
  public static ProviderIdentity? LoadProviderIdentity(string stateDir,
                                                       string clientId) {
    byte[]? data = ReadStateFile(stateDir, IdentityFileName);
    if (data == null) {
      return null;
    }
    ProviderIdentity? identity;
    try {
      identity = JsonSerializer.Deserialize<ProviderIdentity>(data);
    } catch (Exception e) when (e is JsonException or FormatException or
                                    InvalidOperationException) {
      identity = null;
    }
    if (identity == null || identity.Version != ProviderIdentity.CurrentVersion ||
        identity.ClientKeySeed?.Length != 32) {
      throw new ProviderConfigException(
          $"{IdentityFileName} is not a valid provider identity; remove it to create a new one");
    }
    if (identity.ClientId != clientId) {
      return null;
    }
    return identity;
  }

  /// Writes identity.json.
  public static void SaveProviderIdentity(string stateDir,
                                          ProviderIdentity identity) {
    WritePrivateFile(Path.Combine(stateDir, IdentityFileName),
                     JsonSerializer.SerializeToUtf8Bytes(identity));
  }
}