Developer SDK

Java examples

Install the SDK · View source on GitHub ↗

provider/InstallationState.java

java
// 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. Where the
// file system has POSIX permissions, the directory and its files must not be
// accessible to group or others; Windows relies on the access control of the
// user's profile directory. Nothing here calls the SDK.
import java.io.IOException;
import java.io.InputStream;
import java.nio.ByteBuffer;
import java.nio.channels.FileChannel;
import java.nio.charset.StandardCharsets;
import java.nio.file.AccessDeniedException;
import java.nio.file.Files;
import java.nio.file.InvalidPathException;
import java.nio.file.LinkOption;
import java.nio.file.NoSuchFileException;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.nio.file.StandardOpenOption;
import java.nio.file.attribute.BasicFileAttributes;
import java.nio.file.attribute.PosixFilePermission;
import java.nio.file.attribute.PosixFilePermissions;
import java.util.Base64;
import java.util.Collections;
import java.util.EnumSet;
import java.util.LinkedHashMap;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.UUID;
import java.util.regex.Pattern;

/** Loads and saves the installation state. One process owns a state directory at a time. */
final class InstallationState {
  static final String CLIENT_JWT_FILE_NAME = "client.jwt";
  static final String INSTANCE_ID_FILE_NAME = "instance-id";
  static final String IDENTITY_FILE_NAME = "identity.json";
  // the sdk's bounded log files
  static final String LOG_DIR_NAME = "logs";
  // the largest state file the app reads
  static final int STATE_FILE_BYTE_LIMIT = 64 * 1024;
  static final int PROVIDER_IDENTITY_VERSION = 1;
  static final int CLIENT_KEY_SEED_BYTE_COUNT = 32;

  static final Set<PosixFilePermission> OWNER_READ_WRITE =
      PosixFilePermissions.fromString("rw-------");
  static final Set<PosixFilePermission> OWNER_ALL =
      PosixFilePermissions.fromString("rwx------");
  private static final Set<PosixFilePermission> GROUP_AND_OTHERS = EnumSet.of(
      PosixFilePermission.GROUP_READ, PosixFilePermission.GROUP_WRITE,
      PosixFilePermission.GROUP_EXECUTE, PosixFilePermission.OTHERS_READ,
      PosixFilePermission.OTHERS_WRITE, PosixFilePermission.OTHERS_EXECUTE);
  // the 32 hex digits of a uuid, ascii only
  private static final Pattern UUID_HEX = Pattern.compile("[0-9a-fA-F]{32}");

  /** Static members only. */
  private InstallationState() {}

  /** A configuration or credential problem that a restart does not fix (exit 78). */
  static final class ConfigException extends Exception {
    private static final long serialVersionUID = 1;

    /** A configuration error with the message the app prints. */
    ConfigException(String message) { super(message); }
  }

  /**
   * identity.json: the provider identity of one client. Byte fields are standard base64 in the
   * file. An identity belongs to one client: a newly provisioned client gets a new identity. Holds
   * private keys, so toString leaves them out.
   */
  record ProviderIdentity(String clientId, byte[] clientKeySeed,
                          byte[] provideTlsCertificatePem,
                          byte[] provideTlsPrivateKeyPem,
                          byte[] extenderKeySeed) {
    /** The client id only. */
    @Override
    public String toString() {
      return "ProviderIdentity[clientId=" + clientId + "]";
    }
  }

  /**
   * The installation state loaded at start. clientId is the client_id claim of clientJwt. identity
   * is null on first run and when the stored identity belongs to another client. The credential is a
   * bearer secret, so toString leaves it out.
   */
  record ProviderConfig(Path stateDir, String clientJwt, String clientId,
                        String instanceId, ProviderIdentity identity) {
    /** The state directory and ids only. */
    @Override
    public String toString() {
      return "ProviderConfig[stateDir=" + stateDir + ", clientId=" + clientId +
          ", instanceId=" + instanceId + "]";
    }
  }

  /**
   * Loads the installation state, creating instance-id on first run. Every error is a configuration
   * error: restarting does not fix it.
   */
  static ProviderConfig load(String stateDirText) throws ConfigException {
    Path stateDir = checkStateDir(stateDirText);
    byte[] clientJwtBytes;
    try {
      clientJwtBytes = readPrivateFile(stateDir.resolve(CLIENT_JWT_FILE_NAME));
    } catch (IOException e) {
      throw new ConfigException("read " + CLIENT_JWT_FILE_NAME +
                                " from the state directory: " + describe(e));
    }
    String clientJwt =
        new String(clientJwtBytes, StandardCharsets.UTF_8).strip();
    String clientId = parseClientJwtClientId(clientJwt);
    String instanceId = loadOrCreateInstanceId(stateDir);
    ProviderIdentity identity = loadProviderIdentity(stateDir, clientId);
    return new ProviderConfig(stateDir, clientJwt, clientId, instanceId,
                              identity);
  }

  /**
   * The state directory, which must be an existing absolute directory, private to its owner where
   * the file system has POSIX permissions.
   */
  static Path checkStateDir(String stateDirText) throws ConfigException {
    if (stateDirText == null || stateDirText.isEmpty()) {
      throw new ConfigException(
          "set URNETWORK_PROVIDER_STATE_DIR to this installation's private state directory");
    }
    Path stateDir;
    try {
      stateDir = Path.of(stateDirText);
    } catch (InvalidPathException e) {
      throw new ConfigException(
          "URNETWORK_PROVIDER_STATE_DIR is not a valid path");
    }
    if (!stateDir.isAbsolute()) {
      throw new ConfigException(
          "URNETWORK_PROVIDER_STATE_DIR must be an absolute path");
    }
    try {
      if (!Files.readAttributes(stateDir, BasicFileAttributes.class)
               .isDirectory()) {
        throw new ConfigException(
            "URNETWORK_PROVIDER_STATE_DIR is not a directory");
      }
      if (hasPosixPermissions(stateDir) &&
          !Collections.disjoint(Files.getPosixFilePermissions(stateDir),
                                GROUP_AND_OTHERS)) {
        throw new ConfigException(
            "the state directory must be private to its owner (chmod 700)");
      }
    } catch (IOException e) {
      throw new ConfigException("state directory: " + describe(e));
    }
    return stateDir;
  }

  /**
   * Reads a regular, private state file of bounded size. A symlink is refused so that the
   * credential cannot be redirected to another file.
   */
  static byte[] readPrivateFile(Path path) throws IOException {
    BasicFileAttributes attributes = Files.readAttributes(
        path, BasicFileAttributes.class, LinkOption.NOFOLLOW_LINKS);
    if (!attributes.isRegularFile()) {
      throw new IOException("not a regular file: " + path);
    }
    if (STATE_FILE_BYTE_LIMIT < attributes.size()) {
      throw new IOException("file is too large: " + path);
    }
    if (hasPosixPermissions(path) &&
        !Collections.disjoint(
            Files.getPosixFilePermissions(path, LinkOption.NOFOLLOW_LINKS),
            GROUP_AND_OTHERS)) {
      throw new IOException("file must be private to its owner (chmod 600): " +
                            path);
    }
    // no-follow again at open, and a bounded read in case the file grew
    try (InputStream input =
             Files.newInputStream(path, LinkOption.NOFOLLOW_LINKS)) {
      byte[] data = input.readNBytes(STATE_FILE_BYTE_LIMIT + 1);
      if (STATE_FILE_BYTE_LIMIT < data.length) {
        throw new IOException("file is too large: " + path);
      }
      return data;
    }
  }

  /**
   * Replaces a state file atomically: a private temporary file in the same directory is written,
   * synced and renamed over the old file.
   */
  static void writePrivateFile(Path path, byte[] data) throws IOException {
    Path dir = path.toAbsolutePath().getParent();
    String prefix = "." + path.getFileName() + ".";
    boolean posix = hasPosixPermissions(dir);
    Path tempPath =
        posix ? Files.createTempFile(
                    dir, prefix, ".tmp",
                    PosixFilePermissions.asFileAttribute(OWNER_READ_WRITE))
              : Files.createTempFile(dir, prefix, ".tmp");
    boolean replaced = false;
    try {
      if (posix) {
        // owner-only whatever the umask
        Files.setPosixFilePermissions(tempPath, OWNER_READ_WRITE);
      }
      try (FileChannel channel =
               FileChannel.open(tempPath, StandardOpenOption.WRITE,
                                StandardOpenOption.TRUNCATE_EXISTING)) {
        ByteBuffer buffer = ByteBuffer.wrap(data);
        while (buffer.hasRemaining()) {
          channel.write(buffer);
        }
        channel.force(true);
      }
      Files.move(tempPath, path, StandardCopyOption.ATOMIC_MOVE,
                 StandardCopyOption.REPLACE_EXISTING);
      replaced = true;
    } finally {
      if (!replaced) {
        try {
          Files.deleteIfExists(tempPath);
        } catch (IOException e) {
          // keep the original failure
        }
      }
    }
  }

  /** Creates a directory private to its owner, or keeps an existing one. */
  static void createPrivateDirectory(Path dir) throws IOException {
    if (Files.isDirectory(dir)) {
      return;
    }
    if (hasPosixPermissions(dir)) {
      Files.createDirectory(dir, PosixFilePermissions.asFileAttribute(OWNER_ALL));
    } else {
      Files.createDirectory(dir);
    }
  }

  /** Whether the file system of path has POSIX permissions; Windows does not. */
  static boolean hasPosixPermissions(Path path) {
    return path.getFileSystem().supportedFileAttributeViews().contains("posix");
  }

  /**
   * 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.
   */
  static String parseClientJwtClientId(String clientJwt)
      throws ConfigException {
    String notJwt =
        "client.jwt does not hold a JWT; write the scoped client JWT from your backend";
    String[] parts = clientJwt.split("\\.", -1);
    if (parts.length != 3 || parts[0].isEmpty() || parts[1].isEmpty() ||
        parts[2].isEmpty()) {
      throw new ConfigException(notJwt);
    }
    byte[] payload;
    try {
      payload = Base64.getUrlDecoder().decode(stripPadding(parts[1]));
    } catch (IllegalArgumentException e) {
      throw new ConfigException(notJwt);
    }
    String clientIdClaim;
    try {
      clientIdClaim =
          Json.string(Json.parseObject(new String(payload, StandardCharsets.UTF_8)),
                      "client_id");
    } catch (Json.ParseException e) {
      // a payload that is not an object, or a client_id that is not a string
      clientIdClaim = null;
    }
    if (clientIdClaim == null || clientIdClaim.isEmpty()) {
      throw new ConfigException(
          "client.jwt has no client_id claim; write a scoped client JWT, not a network JWT");
    }
    String clientId = parseId(clientIdClaim);
    if (clientId == null) {
      throw new ConfigException("client.jwt has an invalid client_id claim");
    }
    return clientId;
  }

  /**
   * Reads instance-id, creating it on first run. An installation keeps one instance id for its
   * lifetime.
   */
  static String loadOrCreateInstanceId(Path stateDir) throws ConfigException {
    Path path = stateDir.resolve(INSTANCE_ID_FILE_NAME);
    try {
      String instanceId = parseId(
          new String(readPrivateFile(path), StandardCharsets.UTF_8).strip());
      if (instanceId == null) {
        throw new ConfigException(INSTANCE_ID_FILE_NAME + " does not hold a UUID");
      }
      return instanceId;
    } catch (NoSuchFileException e) {
      // first run
    } catch (IOException e) {
      throw new ConfigException("read " + INSTANCE_ID_FILE_NAME +
                                " from the state directory: " + describe(e));
    }
    String instanceId = UUID.randomUUID().toString();
    try {
      writePrivateFile(path,
                       (instanceId + "\n").getBytes(StandardCharsets.UTF_8));
    } catch (IOException e) {
      throw new ConfigException("write " + INSTANCE_ID_FILE_NAME + ": " +
                                describe(e));
    }
    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. A file that does not parse,
   * has another version or a client key seed that is not 32 bytes is a configuration error.
   */
  static ProviderIdentity loadProviderIdentity(Path stateDir, String clientId)
      throws ConfigException {
    byte[] data;
    try {
      data = readPrivateFile(stateDir.resolve(IDENTITY_FILE_NAME));
    } catch (NoSuchFileException e) {
      return null;
    } catch (IOException e) {
      throw new ConfigException("read " + IDENTITY_FILE_NAME +
                                " from the state directory: " + describe(e));
    }
    ProviderIdentity identity;
    try {
      identity = parseProviderIdentity(new String(data, StandardCharsets.UTF_8));
    } catch (Json.ParseException | IllegalArgumentException e) {
      // not json, a field of the wrong type, or invalid base64
      identity = null;
    }
    if (identity == null) {
      throw new ConfigException(
          IDENTITY_FILE_NAME +
          " is not a valid provider identity; remove it to create a new one");
    }
    if (!identity.clientId().equals(clientId)) {
      return null;
    }
    return identity;
  }

  /** Writes identity.json. */
  static void saveProviderIdentity(Path stateDir, ProviderIdentity identity)
      throws IOException {
    Map<String, Object> members = new LinkedHashMap<>();
    members.put("version", PROVIDER_IDENTITY_VERSION);
    members.put("client_id", identity.clientId());
    members.put("client_key_seed", base64(identity.clientKeySeed()));
    members.put("provide_tls_certificate_pem",
                base64(identity.provideTlsCertificatePem()));
    members.put("provide_tls_private_key_pem",
                base64(identity.provideTlsPrivateKeyPem()));
    if (identity.extenderKeySeed() != null &&
        0 < identity.extenderKeySeed().length) {
      members.put("extender_key_seed", base64(identity.extenderKeySeed()));
    }
    writePrivateFile(stateDir.resolve(IDENTITY_FILE_NAME),
                     Json.write(members).getBytes(StandardCharsets.UTF_8));
  }

  /**
   * The canonical lowercase form of a UUID, given in its 36-character form or as 32 hex digits;
   * null when the text is not one.
   */
  static String parseId(String text) {
    String hex;
    if (text.length() == 36) {
      if (text.charAt(8) != '-' || text.charAt(13) != '-' ||
          text.charAt(18) != '-' || text.charAt(23) != '-') {
        return null;
      }
      hex = text.substring(0, 8) + text.substring(9, 13) +
          text.substring(14, 18) + text.substring(19, 23) + text.substring(24);
    } else if (text.length() == 32) {
      hex = text;
    } else {
      return null;
    }
    if (!UUID_HEX.matcher(hex).matches()) {
      return null;
    }
    hex = hex.toLowerCase(Locale.ROOT);
    return hex.substring(0, 8) + "-" + hex.substring(8, 12) + "-" +
        hex.substring(12, 16) + "-" + hex.substring(16, 20) + "-" +
        hex.substring(20);
  }

  /** A short reason for a file error, without a stack trace. */
  static String describe(IOException e) {
    if (e instanceof NoSuchFileException) {
      return "no such file: " + e.getMessage();
    }
    if (e instanceof AccessDeniedException) {
      return "permission denied: " + e.getMessage();
    }
    // a FileSystemException message names the file and the reason
    String message = e.getMessage();
    return message != null ? message : e.getClass().getSimpleName();
  }

  /** identity.json's fields; null when the version or the client key seed is not valid. */
  private static ProviderIdentity parseProviderIdentity(String text)
      throws Json.ParseException {
    Map<String, Object> members = Json.parseObject(text);
    if (Json.longValue(members, "version", 0) != PROVIDER_IDENTITY_VERSION) {
      return null;
    }
    byte[] clientKeySeed = base64Member(members, "client_key_seed");
    if (clientKeySeed.length != CLIENT_KEY_SEED_BYTE_COUNT) {
      return null;
    }
    String clientId = Json.string(members, "client_id");
    return new ProviderIdentity(
        clientId == null ? "" : clientId, clientKeySeed,
        base64Member(members, "provide_tls_certificate_pem"),
        base64Member(members, "provide_tls_private_key_pem"),
        base64Member(members, "extender_key_seed"));
  }

  /** A standard base64 member as bytes; empty when it is absent or null. */
  private static byte[] base64Member(Map<String, Object> members, String name)
      throws Json.ParseException {
    String value = Json.string(members, name);
    if (value == null) {
      return new byte[0];
    }
    return Base64.getDecoder().decode(value);
  }

  /** Standard base64 of bytes; "" for none. */
  private static String base64(byte[] bytes) {
    return bytes == null ? "" : Base64.getEncoder().encodeToString(bytes);
  }

  /** The text without trailing base64 padding. */
  private static String stripPadding(String text) {
    int end = text.length();
    while (0 < end && text.charAt(end - 1) == '=') {
      end -= 1;
    }
    return text.substring(0, end);
  }
}