Developer SDK

Swift examples

Install the SDK · View source on GitHub ↗

provider/Sources/ProviderCore/State.swift

swift
// 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; Windows
// relies on the access control of the user's profile directory.

import Foundation

#if canImport(Darwin)
  import Darwin
#elseif canImport(Glibc)
  import Glibc
#elseif canImport(Musl)
  import Musl
#elseif canImport(CRT)
  import CRT
#endif
#if os(Windows)
  import WinSDK
#endif

public let clientJwtFileName = "client.jwt"
public let instanceIdFileName = "instance-id"
public let identityFileName = "identity.json"

/// The largest state file the app reads.
let stateFileByteLimit = 64 * 1024

public let providerIdentityVersion = 1

/// A missing or invalid installation state: a configuration or credential
/// problem that restarting does not fix (exit code 78).
public struct ProviderConfigError: Error, CustomStringConvertible {
  public let description: String

  /// An error with the given text.
  public init(_ description: String) {
    self.description = description
  }
}

/// A state file that could not be read or written.
public struct StateFileError: Error, CustomStringConvertible {
  public let description: String
  /// the file does not exist
  public let notFound: Bool

  /// An error with the given text.
  init(_ description: String, notFound: Bool = false) {
    self.description = description
    self.notFound = notFound
  }
}

/// identity.json. Byte fields are standard base64 in JSON. An identity belongs
/// to one client: a newly provisioned client gets a new identity.
public struct ProviderIdentity: Codable, Equatable {
  public var version: Int
  public var clientId: String
  public var clientKeySeed: Data
  public var provideTlsCertificatePem: Data
  public var provideTlsPrivateKeyPem: Data
  /// empty when the device keeps none, and then left out of the file
  public var extenderKeySeed: Data

  /// The file's field names.
  enum CodingKeys: String, CodingKey {
    case version
    case clientId = "client_id"
    case clientKeySeed = "client_key_seed"
    case provideTlsCertificatePem = "provide_tls_certificate_pem"
    case provideTlsPrivateKeyPem = "provide_tls_private_key_pem"
    case extenderKeySeed = "extender_key_seed"
  }

  /// An identity with the given values.
  public init(
    version: Int, clientId: String, clientKeySeed: Data, provideTlsCertificatePem: Data,
    provideTlsPrivateKeyPem: Data, extenderKeySeed: Data
  ) {
    self.version = version
    self.clientId = clientId
    self.clientKeySeed = clientKeySeed
    self.provideTlsCertificatePem = provideTlsCertificatePem
    self.provideTlsPrivateKeyPem = provideTlsPrivateKeyPem
    self.extenderKeySeed = extenderKeySeed
  }

  /// Decodes the file; a missing or null field is empty, which loadProviderIdentity
  /// then checks.
  public init(from decoder: Decoder) throws {
    let container = try decoder.container(keyedBy: CodingKeys.self)
    version = try container.decodeIfPresent(Int.self, forKey: .version) ?? 0
    clientId = try container.decodeIfPresent(String.self, forKey: .clientId) ?? ""
    clientKeySeed = try container.decodeIfPresent(Data.self, forKey: .clientKeySeed) ?? Data()
    provideTlsCertificatePem =
      try container.decodeIfPresent(Data.self, forKey: .provideTlsCertificatePem) ?? Data()
    provideTlsPrivateKeyPem =
      try container.decodeIfPresent(Data.self, forKey: .provideTlsPrivateKeyPem) ?? Data()
    extenderKeySeed = try container.decodeIfPresent(Data.self, forKey: .extenderKeySeed) ?? Data()
  }

  /// Encodes the file, leaving out an empty extender seed.
  public func encode(to encoder: Encoder) throws {
    var container = encoder.container(keyedBy: CodingKeys.self)
    try container.encode(version, forKey: .version)
    try container.encode(clientId, forKey: .clientId)
    try container.encode(clientKeySeed, forKey: .clientKeySeed)
    try container.encode(provideTlsCertificatePem, forKey: .provideTlsCertificatePem)
    try container.encode(provideTlsPrivateKeyPem, forKey: .provideTlsPrivateKeyPem)
    if !extenderKeySeed.isEmpty {
      try container.encode(extenderKeySeed, forKey: .extenderKeySeed)
    }
  }
}

/// The byte values that recreate a device's identity: the arguments of
/// urnet_new_device_local_key_material and
/// urnet_device_local_key_material_set_extender_key_seed.
public struct ProviderKeyMaterial: Equatable {
  public var clientKeySeed: [UInt8]
  public var provideTlsCertificatePem: [UInt8]
  public var provideTlsPrivateKeyPem: [UInt8]
  /// empty when the identity has none
  public var extenderKeySeed: [UInt8]
}

/// The key material that recreates the identity. nil without an identity (the
/// first run, or another client's identity): the device then gets key material
/// handle 0 and makes a new identity, which the app saves.
public func providerKeyMaterial(_ identity: ProviderIdentity?) -> ProviderKeyMaterial? {
  guard let identity else {
    return nil
  }
  return ProviderKeyMaterial(
    clientKeySeed: [UInt8](identity.clientKeySeed),
    provideTlsCertificatePem: [UInt8](identity.provideTlsCertificatePem),
    provideTlsPrivateKeyPem: [UInt8](identity.provideTlsPrivateKeyPem),
    extenderKeySeed: [UInt8](identity.extenderKeySeed))
}

/// The installation state loaded at start.
public struct ProviderConfig {
  public let stateDir: String
  public let clientJwt: String
  /// the client_id claim of clientJwt
  public let clientId: String
  public let instanceId: String
  /// nil on first run, and when the stored identity belongs to another client
  public let identity: ProviderIdentity?
}

/// Loads the installation state, creating instance-id on first run. Every error
/// is a ProviderConfigError: restarting does not fix it.
public func loadProviderConfig(stateDir: String?) throws -> ProviderConfig {
  let stateDir = stateDir ?? ""
  try checkStateDir(stateDir)
  let clientJwtData: Data
  do {
    clientJwtData = try readPrivateFile(joinPath(stateDir, clientJwtFileName))
  } catch {
    throw ProviderConfigError("read \(clientJwtFileName) from the state directory: \(error)")
  }
  let clientJwt = String(decoding: clientJwtData, as: UTF8.self).trimmingCharacters(
    in: .whitespacesAndNewlines)
  let clientId = try parseClientJwtClientId(clientJwt)
  let instanceId = try loadOrCreateInstanceId(stateDir: stateDir)
  let identity = try loadProviderIdentity(stateDir: stateDir, clientId: clientId)
  return ProviderConfig(
    stateDir: stateDir, clientJwt: clientJwt, clientId: clientId, instanceId: instanceId,
    identity: identity)
}

/// The state directory must be an existing absolute directory, private to its
/// owner on POSIX.
public func checkStateDir(_ stateDir: String) throws {
  if stateDir.isEmpty {
    throw ProviderConfigError(
      "set URNETWORK_PROVIDER_STATE_DIR to this installation's private state directory")
  }
  if !isAbsolutePath(stateDir) {
    throw ProviderConfigError("URNETWORK_PROVIDER_STATE_DIR must be an absolute path")
  }
  var isDirectory: ObjCBool = false
  if !FileManager.default.fileExists(atPath: stateDir, isDirectory: &isDirectory) {
    throw ProviderConfigError("state directory: \(stateDir) does not exist")
  }
  if !isDirectory.boolValue {
    throw ProviderConfigError("URNETWORK_PROVIDER_STATE_DIR is not a directory")
  }
  #if !os(Windows)
    // the directory the path names, following a symlink as fileExists does
    var info = stat()
    if stat(stateDir, &info) != 0 {
      throw ProviderConfigError("state directory: \(stateDir) cannot be read")
    }
    if UInt32(info.st_mode) & 0o077 != 0 {
      throw ProviderConfigError("the state directory must be private to its owner (chmod 700)")
    }
  #endif
}

/// Whether path is absolute: from the root on POSIX; with a drive letter (C:\)
/// or a UNC prefix (\\server) on Windows.
func isAbsolutePath(_ path: String) -> Bool {
  #if os(Windows)
    if path.hasPrefix("\\\\") || path.hasPrefix("//") {
      return true
    }
    let characters = Array(path)
    return 3 <= characters.count && characters[0].isASCII && characters[0].isLetter
      && characters[1] == ":" && (characters[2] == "\\" || characters[2] == "/")
  #else
    return path.hasPrefix("/")
  #endif
}

/// name inside directory, with the platform's separator.
public func joinPath(_ directory: String, _ name: String) -> String {
  #if os(Windows)
    let separator: Character = "\\"
    let hasSeparator = directory.hasSuffix("\\") || directory.hasSuffix("/")
  #else
    let separator: Character = "/"
    let hasSeparator = directory.hasSuffix("/")
  #endif
  return hasSeparator ? directory + name : directory + String(separator) + name
}

/// Reads a regular, private state file of bounded size. A symlink is refused so
/// that the credential cannot be redirected to another file.
func readPrivateFile(_ path: String) throws -> Data {
  let attributes: [FileAttributeKey: Any]
  do {
    // the file itself: a symlink is not followed
    attributes = try FileManager.default.attributesOfItem(atPath: path)
  } catch let error as CocoaError
    where error.code == .fileReadNoSuchFile || error.code == .fileNoSuchFile
  {
    throw StateFileError("no such file", notFound: true)
  } catch {
    throw StateFileError("cannot read the file: \(error.localizedDescription)")
  }
  if attributes[.type] as? FileAttributeType != .typeRegular {
    throw StateFileError("not a regular file")
  }
  if let byteCount = (attributes[.size] as? NSNumber)?.int64Value,
    Int64(stateFileByteLimit) < byteCount
  {
    throw StateFileError("file is too large")
  }
  #if !os(Windows)
    let permissions = (attributes[.posixPermissions] as? NSNumber)?.intValue ?? 0o777
    if permissions & 0o077 != 0 {
      throw StateFileError("file must be private to its owner (chmod 600)")
    }
  #endif
  guard let data = FileManager.default.contents(atPath: path) else {
    throw StateFileError("cannot read the file")
  }
  return data
}

/// Replaces a state file atomically: a private temporary file in the same
/// directory is written, synced and renamed over the old file. A failed write
/// removes its temporary file and leaves the old file as it was.
public func writePrivateFile(_ path: String, _ data: Data) throws {
  #if os(Windows)
    let separatorIndex = path.lastIndex(where: { $0 == "\\" || $0 == "/" })
  #else
    let separatorIndex = path.lastIndex(of: "/")
  #endif
  guard let separatorIndex else {
    throw StateFileError("not a path in a directory")
  }
  let directory = String(path[..<separatorIndex])
  let name = String(path[path.index(after: separatorIndex)...])
  #if os(Windows)
    // the user's profile directory keeps the file private to the user
    let tempPath = joinPath(directory, ".\(name).\(UUID().uuidString)")
    if !FileManager.default.createFile(atPath: tempPath, contents: nil) {
      throw StateFileError("cannot create a temporary file")
    }
    do {
      guard let handle = FileHandle(forWritingAtPath: tempPath) else {
        throw StateFileError("cannot open the temporary file")
      }
      defer { try? handle.close() }
      try handle.write(contentsOf: data)
      try handle.synchronize()
    } catch {
      try? FileManager.default.removeItem(atPath: tempPath)
      throw error
    }
    let moved = tempPath.withCString(encodedAs: UTF16.self) { tempPathW in
      path.withCString(encodedAs: UTF16.self) { pathW in
        MoveFileExW(tempPathW, pathW, DWORD(MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH))
      }
    }
    if !moved {
      try? FileManager.default.removeItem(atPath: tempPath)
      throw StateFileError("cannot replace the file (error \(GetLastError()))")
    }
  #else
    // mkstemp creates the file with mode 0600 and a unique name
    var template = Array(joinPath(directory, ".\(name).XXXXXX").utf8CString)
    let fd = template.withUnsafeMutableBufferPointer { mkstemp($0.baseAddress!) }
    if fd < 0 {
      throw StateFileError("cannot create a temporary file (errno \(errno))")
    }
    let tempPath = template.withUnsafeBufferPointer { String(cString: $0.baseAddress!) }
    let failure = { (text: String) -> StateFileError in
      let error = StateFileError("\(text) (errno \(errno))")
      close(fd)
      unlink(tempPath)
      return error
    }
    if fchmod(fd, 0o600) != 0 {
      throw failure("cannot make the temporary file private")
    }
    let written = data.withUnsafeBytes { buffer -> Bool in
      var offset = 0
      while offset < buffer.count {
        let count = write(fd, buffer.baseAddress! + offset, buffer.count - offset)
        if count < 0 {
          if errno == EINTR {
            continue
          }
          return false
        }
        offset += count
      }
      return true
    }
    if !written {
      throw failure("cannot write the temporary file")
    }
    if fsync(fd) != 0 {
      throw failure("cannot sync the temporary file")
    }
    if close(fd) != 0 {
      let error = StateFileError("cannot close the temporary file (errno \(errno))")
      unlink(tempPath)
      throw error
    }
    if rename(tempPath, path) != 0 {
      let error = StateFileError("cannot replace the file (errno \(errno))")
      unlink(tempPath)
      throw error
    }
  #endif
}

/// 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 func parseClientJwtClientId(_ clientJwt: String) throws -> String {
  let notJwt = ProviderConfigError(
    "client.jwt does not hold a JWT; write the scoped client JWT from your backend")
  let parts = clientJwt.split(separator: ".", omittingEmptySubsequences: false)
  if parts.count != 3 || parts.contains(where: { $0.isEmpty }) {
    throw notJwt
  }
  // the payload is base64url without padding
  var payloadText = String(parts[1])
  while payloadText.hasSuffix("=") {
    payloadText.removeLast()
  }
  let base64UrlCharacter = { (character: Character) -> Bool in
    character.isASCII
      && (character.isLetter || character.isNumber || character == "-" || character == "_")
  }
  if payloadText.isEmpty || !payloadText.allSatisfy(base64UrlCharacter) {
    throw notJwt
  }
  var base64 = payloadText.replacingOccurrences(of: "-", with: "+").replacingOccurrences(
    of: "_", with: "/")
  base64 += String(repeating: "=", count: (4 - base64.count % 4) % 4)
  guard let payload = Data(base64Encoded: base64) else {
    throw notJwt
  }
  /// The one claim the app reads.
  struct Claims: Decodable {
    var clientId: String?

    /// The claim's name.
    enum CodingKeys: String, CodingKey {
      case clientId = "client_id"
    }
  }
  guard let claims = try? JSONDecoder().decode(Claims.self, from: payload),
    let clientIdText = claims.clientId, !clientIdText.isEmpty
  else {
    throw ProviderConfigError(
      "client.jwt has no client_id claim; write a scoped client JWT, not a network JWT")
  }
  guard let clientId = UUID(uuidString: clientIdText) else {
    throw ProviderConfigError("client.jwt has an invalid client_id claim")
  }
  return clientId.uuidString.lowercased()
}

/// Reads instance-id, creating it on first run. An installation keeps one
/// instance id for its lifetime.
public func loadOrCreateInstanceId(stateDir: String) throws -> String {
  let path = joinPath(stateDir, instanceIdFileName)
  do {
    let data = try readPrivateFile(path)
    let text = String(decoding: data, as: UTF8.self).trimmingCharacters(in: .whitespacesAndNewlines)
    guard let instanceId = UUID(uuidString: text) else {
      throw ProviderConfigError("\(instanceIdFileName) does not hold a UUID")
    }
    return instanceId.uuidString.lowercased()
  } catch let error as StateFileError where error.notFound {
    let instanceId = UUID().uuidString.lowercased()
    do {
      try writePrivateFile(path, Data((instanceId + "\n").utf8))
    } catch {
      throw ProviderConfigError("write \(instanceIdFileName): \(error)")
    }
    return instanceId
  } catch let error as StateFileError {
    throw ProviderConfigError("read \(instanceIdFileName) from the state directory: \(error)")
  }
}

/// Reads identity.json for clientId. A missing file, or an identity of another
/// client, returns nil: the device then creates a new identity, which the app
/// saves.
public func loadProviderIdentity(stateDir: String, clientId: String) throws -> ProviderIdentity? {
  let data: Data
  do {
    data = try readPrivateFile(joinPath(stateDir, identityFileName))
  } catch let error as StateFileError where error.notFound {
    return nil
  } catch {
    throw ProviderConfigError("read \(identityFileName) from the state directory: \(error)")
  }
  guard let identity = try? JSONDecoder().decode(ProviderIdentity.self, from: data),
    identity.version == providerIdentityVersion, identity.clientKeySeed.count == 32
  else {
    throw ProviderConfigError(
      "\(identityFileName) is not a valid provider identity; remove it to create a new one")
  }
  if identity.clientId != clientId {
    return nil
  }
  return identity
}

/// Writes identity.json.
public func saveProviderIdentity(stateDir: String, identity: ProviderIdentity) throws {
  let encoder = JSONEncoder()
  encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
  try writePrivateFile(joinPath(stateDir, identityFileName), try encoder.encode(identity))
}