Developer SDK

Swift examples

Install the SDK · View source on GitHub ↗

embed/Sources/EmbedCore/State.swift

swift
// Installation state for one embed installation, kept in one private
// directory named by URNETWORK_EMBED_STATE_DIR (EMBED_CONTRACT.md,
// "Installation state"):
//
// - client.jwt: the scoped client JWT, written by the token fetch, by the
//   backend tool's provision or by the developer, and rewritten by the app
//   whenever the SDK refreshes the token.
// - instance-id: this installation's UUID, created on first run. It is also the
//   installation ID the app sends to the token server.
// - logs/: the SDK's bounded log files.
//
// 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. The file functions are the Swift provider
// example's.

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"

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

/// A missing or invalid installation state: a configuration or credential
/// problem that restarting does not fix (exit code 78).
public struct EmbedConfigError: 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
  }
}

/// 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 EmbedConfigError(
      "set URNETWORK_EMBED_STATE_DIR to this installation's private state directory")
  }
  if !isAbsolutePath(stateDir) {
    throw EmbedConfigError("URNETWORK_EMBED_STATE_DIR must be an absolute path")
  }
  var isDirectory: ObjCBool = false
  if !FileManager.default.fileExists(atPath: stateDir, isDirectory: &isDirectory) {
    throw EmbedConfigError("state directory: \(stateDir) does not exist")
  }
  if !isDirectory.boolValue {
    throw EmbedConfigError("URNETWORK_EMBED_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 EmbedConfigError("state directory: \(stateDir) cannot be read")
    }
    if UInt32(info.st_mode) & 0o077 != 0 {
      throw EmbedConfigError("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.
public 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 = EmbedConfigError(
    "client.jwt does not hold a JWT; obtain 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 EmbedConfigError(
      "client.jwt has no client_id claim; write a scoped client JWT, not a network JWT")
  }
  guard let clientId = UUID(uuidString: clientIdText) else {
    throw EmbedConfigError("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 EmbedConfigError("\(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 EmbedConfigError("write \(instanceIdFileName): \(error)")
    }
    return instanceId
  } catch let error as StateFileError {
    throw EmbedConfigError("read \(instanceIdFileName) from the state directory: \(error)")
  }
}

/// Reads client.jwt and its client_id claim: nil when the file is missing. A
/// file that cannot be read, or holds no client JWT (a network JWT has no
/// client_id claim), throws EmbedConfigError. The token itself is never printed.
public func loadClientJwt(stateDir: String) throws -> (clientJwt: String, clientId: String)? {
  let data: Data
  do {
    data = try readPrivateFile(joinPath(stateDir, clientJwtFileName))
  } catch let error as StateFileError where error.notFound {
    return nil
  } catch {
    throw EmbedConfigError("read \(clientJwtFileName) from the state directory: \(error)")
  }
  let clientJwt = String(decoding: data, as: UTF8.self).trimmingCharacters(
    in: .whitespacesAndNewlines)
  return (clientJwt, try parseClientJwtClientId(clientJwt))
}

/// Replaces client.jwt atomically with the token and a line break.
public func saveClientJwt(stateDir: String, clientJwt: String) throws {
  try writePrivateFile(joinPath(stateDir, clientJwtFileName), Data((clientJwt + "\n").utf8))
}