@use-voltra/ios-client 2.2.0 → 2.3.0

package/ios/shared/WidgetServer/WidgetServerFetcher.swift

@@ -0,0 +1,179 @@
+import Foundation
+
+/// What came back from the server, before either engine decides what it means.
+///
+/// The request side is identical for a payload widget and a Dynamic Widget, so it lives here once.
+/// Only the interpretation of `body` differs: one parses a Voltra payload, the other props.
+public enum WidgetServerFetchResult: Sendable {
+  /// `200` with a body. `etag` is present when the response carried one.
+  case success(body: Data, etag: String?, httpStatus: Int, nextIntervalMinutes: Int?)
+  /// `304`: what is already committed is still current.
+  case notModified(nextIntervalMinutes: Int?)
+  /// The request never completed: no connectivity, DNS, TLS, or a timeout.
+  case networkFailure(message: String)
+  /// The server answered with a status we cannot use.
+  case httpFailure(httpStatus: Int, retryAfterMinutes: Int?)
+  /// A `2xx` whose body is over `WidgetServerUpdateDefaults.maxBodyBytes`. Kept apart from
+  /// `httpFailure` because the server did answer: this is a body the device refuses, so it is
+  /// reported as a parse failure and asking again is pointless.
+  case tooLarge(httpStatus: Int)
+
+  public var isUnauthorized: Bool {
+    if case let .httpFailure(status, _) = self {
+      return status == 401 || status == 403
+    }
+    return false
+  }
+
+  /// True when waiting and asking again could plausibly succeed.
+  public var isTransient: Bool {
+    switch self {
+    case .networkFailure:
+      return true
+    case let .httpFailure(status, _):
+      return status >= 500 || status == 429
+    default:
+      return false
+    }
+  }
+}
+
+/// Executes a request built by `WidgetServerRequestBuilder` and reports what happened, without
+/// deciding what to do about it.
+public enum WidgetServerFetcher {
+  /// Refuses to leave the host the app configured, so an `Authorization` header or a request body
+  /// cannot be replayed somewhere the app never agreed to send it.
+  private final class SameHostRedirectDelegate: NSObject, URLSessionTaskDelegate {
+    func urlSession(
+      _: URLSession,
+      task: URLSessionTask,
+      willPerformHTTPRedirection _: HTTPURLResponse,
+      newRequest request: URLRequest,
+      completionHandler: @escaping (URLRequest?) -> Void
+    ) {
+      guard let originalHost = task.originalRequest?.url?.host,
+            let originalScheme = task.originalRequest?.url?.scheme,
+            let nextHost = request.url?.host,
+            nextHost.caseInsensitiveCompare(originalHost) == .orderedSame,
+            request.url?.scheme == originalScheme
+      else {
+        VoltraLogger.widget.warning("Refusing cross-host redirect for a widget server request")
+        completionHandler(nil)
+        return
+      }
+
+      completionHandler(request)
+    }
+  }
+
+  private static let redirectDelegate = SameHostRedirectDelegate()
+
+  public static func fetch(
+    _ request: URLRequest,
+    session: URLSession = .shared
+  ) async -> WidgetServerFetchResult {
+    do {
+      // bytes(for:) rather than data(for:) so an oversized body is abandoned mid-stream. A widget
+      // extension has a 30 MB ceiling for the whole render, and buffering first would spend it
+      // before we ever got to check.
+      let (stream, response) = try await session.bytes(for: request, delegate: redirectDelegate)
+
+      guard let http = response as? HTTPURLResponse else {
+        return .networkFailure(message: "Response was not an HTTP response")
+      }
+
+      let nextIntervalMinutes = maxAgeMinutes(http.value(forHTTPHeaderField: "Cache-Control"))
+
+      if http.statusCode == 304 {
+        return .notModified(nextIntervalMinutes: nextIntervalMinutes)
+      }
+
+      guard (200 ... 299).contains(http.statusCode) else {
+        return .httpFailure(
+          httpStatus: http.statusCode,
+          retryAfterMinutes: retryAfterMinutes(http.value(forHTTPHeaderField: "Retry-After"))
+        )
+      }
+
+      guard let body = try await readBody(stream) else {
+        // Asking again returns the same oversized body, so this is a failure the app has to fix
+        // rather than one to back off from.
+        VoltraLogger.widget.error(
+          "Response is larger than \(WidgetServerUpdateDefaults.maxBodyBytes, privacy: .public) bytes"
+        )
+        return .tooLarge(httpStatus: http.statusCode)
+      }
+
+      return .success(
+        body: body,
+        etag: http.value(forHTTPHeaderField: "ETag"),
+        httpStatus: http.statusCode,
+        nextIntervalMinutes: nextIntervalMinutes
+      )
+    } catch {
+      return .networkFailure(message: error.localizedDescription)
+    }
+  }
+
+  /// Returns nil as soon as the body passes the cap, without holding the rest of it.
+  private static func readBody(_ stream: URLSession.AsyncBytes) async throws -> Data? {
+    var body = Data()
+    body.reserveCapacity(16 * 1024)
+
+    for try await byte in stream {
+      if body.count >= WidgetServerUpdateDefaults.maxBodyBytes {
+        return nil
+      }
+
+      body.append(byte)
+    }
+
+    return body
+  }
+
+  /// `Cache-Control: max-age=N`, in minutes, rounded down.
+  static func maxAgeMinutes(_ header: String?) -> Int? {
+    guard let header else { return nil }
+
+    let pattern = try? NSRegularExpression(pattern: "max-age\\s*=\\s*(\\d+)", options: .caseInsensitive)
+    let range = NSRange(header.startIndex ..< header.endIndex, in: header)
+
+    guard let match = pattern?.firstMatch(in: header, range: range),
+          let secondsRange = Range(match.range(at: 1), in: header),
+          let seconds = Int(header[secondsRange])
+    else {
+      return nil
+    }
+
+    return seconds / 60
+  }
+
+  /// `Retry-After`, in minutes, rounded up so we never retry early.
+  ///
+  /// The header is delta-seconds or an HTTP date; both are in the wild, so both are read.
+  static func retryAfterMinutes(_ header: String?, now: Date = Date()) -> Int? {
+    guard let value = header?.trimmingCharacters(in: .whitespaces), !value.isEmpty else {
+      return nil
+    }
+
+    if let seconds = Int(value) {
+      return seconds > 0 ? (seconds + 59) / 60 : nil
+    }
+
+    guard let date = httpDateFormatter.date(from: value) else {
+      return nil
+    }
+
+    let seconds = Int(date.timeIntervalSince(now))
+
+    return seconds > 0 ? (seconds + 59) / 60 : nil
+  }
+
+  private static let httpDateFormatter: DateFormatter = {
+    let formatter = DateFormatter()
+    formatter.locale = Locale(identifier: "en_US_POSIX")
+    formatter.timeZone = TimeZone(identifier: "GMT")
+    formatter.dateFormat = "EEE, dd MMM yyyy HH:mm:ss zzz"
+    return formatter
+  }()
+}

package/ios/shared/WidgetServer/WidgetServerRequestBuilder.swift

@@ -0,0 +1,114 @@
+import Foundation
+
+/// The device state a request carries that is not part of the settings: the theme and locale the
+/// widget is being drawn in, and who is asking.
+///
+/// Passed in rather than read here so the request contract can be tested without UIKit, and so a
+/// timeline request built for one appearance cannot accidentally report another.
+public struct WidgetServerRequestContext: Equatable, Sendable {
+  public let theme: String
+  public let locale: String
+  public let userAgent: String
+  /// Only payload widgets send `family`: one Dynamic Widget fetch serves every size, so its props
+  /// must be size-agnostic and the entry picks its layout from `env.widgetFamily`.
+  public let family: String?
+
+  public init(theme: String, locale: String, userAgent: String, family: String? = nil) {
+    self.theme = theme
+    self.locale = locale
+    self.userAgent = userAgent
+    self.family = family
+  }
+}
+
+/// Turns resolved settings plus Voltra's own request parameters into the request the device sends.
+///
+/// Both engines build their requests here, so a payload widget and a Dynamic Widget send the same
+/// shape and the app's runtime overrides apply to both. Only the response and what the device does
+/// with it differ.
+public enum WidgetServerRequestBuilder {
+  /// Widgets have limited execution time, so a request that has not answered in this long is not
+  /// going to be useful even if it eventually does.
+  public static let timeoutSeconds: TimeInterval = 15
+
+  /// - Parameter etag: from the last `200`, sent as `If-None-Match`. Callers pass nil when the
+  ///   stored ETag belongs to a different URL than the one being fetched now.
+  /// - Returns: nil when there is nothing to fetch — no URL, fetching is off, or the URL will not
+  ///   parse.
+  public static func build(
+    scope: WidgetScope,
+    settings: ResolvedWidgetServerSettings,
+    context: WidgetServerRequestContext,
+    etag: String? = nil,
+    // The placement's merged configuration (ADR 0007). Empty for a widget with no configuration
+    // parameters, or when the caller only knows the scope's key — the caller is responsible for
+    // passing the same map that produced `scope`'s key, since the key alone cannot be reversed
+    // back into the configuration that produced it.
+    configuration: [String: String] = [:]
+  ) -> URLRequest? {
+    guard settings.shouldFetch, let url = settings.url, var components = URLComponents(string: url) else {
+      return nil
+    }
+
+    var queryItems = components.queryItems ?? []
+    queryItems.append(URLQueryItem(name: "widgetId", value: scope.widgetId))
+    queryItems.append(URLQueryItem(name: "platform", value: "ios"))
+
+    if let family = context.family {
+      queryItems.append(URLQueryItem(name: "family", value: family))
+    }
+
+    queryItems.append(URLQueryItem(name: "theme", value: context.theme))
+    queryItems.append(URLQueryItem(name: "locale", value: context.locale))
+
+    // Present for every method, absent when the widget has no configuration parameters (ADR
+    // 0007). `instance` is the hash of the canonical `configuration`, sent so a backend can cache
+    // or log per instance without recomputing it.
+    if case let .instance(_, key) = scope, let canonicalConfiguration = WidgetCanonicalConfiguration.canonicalize(configuration) {
+      queryItems.append(URLQueryItem(name: "instance", value: key))
+      queryItems.append(URLQueryItem(name: "configuration", value: canonicalConfiguration))
+    }
+
+    // Voltra's own keys are appended first and the app's keys are rejected at call time if they
+    // collide, so nothing here can shadow what the server relies on.
+    for key in settings.query.keys.sorted() {
+      queryItems.append(URLQueryItem(name: key, value: settings.query[key]))
+    }
+
+    components.queryItems = queryItems
+
+    guard let resolvedUrl = components.url else { return nil }
+
+    var request = URLRequest(url: resolvedUrl)
+    let method = settings.method.uppercased()
+
+    request.httpMethod = method
+    request.timeoutInterval = timeoutSeconds
+    request.setValue("application/json", forHTTPHeaderField: "Accept")
+    request.setValue(context.userAgent, forHTTPHeaderField: "User-Agent")
+
+    for (key, value) in settings.headers {
+      request.setValue(value, forHTTPHeaderField: key)
+    }
+
+    if let etag {
+      request.setValue(etag, forHTTPHeaderField: "If-None-Match")
+    }
+
+    if let body = settings.body {
+      if WidgetServerUpdateDefaults.bodylessMethods.contains(method) {
+        // URLSession sends a Content-Length and drops the body on GET, so the server would see a
+        // request the app did not mean to send. Dropping it here is the lesser surprise, and it is
+        // documented.
+        VoltraLogger.widget.warning(
+          "Dropping request body for widget '\(scope.widgetId, privacy: .public)': \(method, privacy: .public) cannot carry one"
+        )
+      } else {
+        request.httpBody = Data(body.utf8)
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+      }
+    }
+
+    return request
+  }
+}

package/ios/shared/WidgetServer/WidgetServerSettingsCodec.swift

@@ -0,0 +1,47 @@
+import Foundation
+
+/// Serializes one settings layer for storage. Written as a small versioned envelope so a future
+/// shape change can be recognised rather than guessed at, the same way Dynamic Widget props are
+/// stored.
+public enum WidgetServerSettingsCodec {
+  private static let versionKey = "widgetServerSettingsVersion"
+  private static let settingsKey = "widgetServerSettings"
+  private static let version = 1
+
+  public static func encode(_ settings: WidgetServerUpdateSettings) -> Data? {
+    var payload: [String: Any] = [:]
+
+    settings.url.map { payload["url"] = $0 }
+    settings.intervalMinutes.map { payload["intervalMinutes"] = $0 }
+    settings.enabled.map { payload["enabled"] = $0 }
+    settings.method.map { payload["method"] = $0 }
+    settings.query.map { payload["query"] = $0 }
+    settings.headers.map { payload["headers"] = $0 }
+    settings.body.map { payload["body"] = $0 }
+
+    let envelope: [String: Any] = [versionKey: version, settingsKey: payload]
+
+    return try? JSONSerialization.data(withJSONObject: envelope)
+  }
+
+  /// Returns nil for anything this version cannot read, so a bad record reads as "no opinion".
+  public static func decode(_ data: Data?) -> WidgetServerUpdateSettings? {
+    guard let data,
+          let envelope = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+          envelope[versionKey] as? Int == version,
+          let payload = envelope[settingsKey] as? [String: Any]
+    else {
+      return nil
+    }
+
+    return WidgetServerUpdateSettings(
+      url: payload["url"] as? String,
+      intervalMinutes: payload["intervalMinutes"] as? Int,
+      enabled: payload["enabled"] as? Bool,
+      method: payload["method"] as? String,
+      query: payload["query"] as? [String: String],
+      headers: payload["headers"] as? [String: String],
+      body: payload["body"] as? String
+    )
+  }
+}

package/ios/shared/WidgetServer/WidgetServerSettingsResolver.swift

@@ -0,0 +1,129 @@
+import Foundation
+
+/// One source of server-update settings. Implementations return a partial
+/// `WidgetServerUpdateSettings`, or nil when they have nothing to say about the scope.
+///
+/// Layers are stacked in a fixed order by `WidgetServerSettingsResolver` and never consulted
+/// directly: nothing outside this folder reads Info.plist, the Keychain, or anything else for
+/// server-update purposes.
+public protocol WidgetServerSettingsLayer: Sendable {
+  /// A short name used in logs, so a surprising resolved value can be traced to its source.
+  var name: String { get }
+
+  func settings(for scope: WidgetScope) -> WidgetServerUpdateSettings?
+
+  /// Whether this layer knows the scope to be server-driven at all. Only the config layer can
+  /// answer this — a runtime layer setting a URL does not turn a locally-rendered widget into a
+  /// server-driven one, because the engine is chosen at generate time.
+  func isServerDriven(_ scope: WidgetScope) -> Bool
+}
+
+public extension WidgetServerSettingsLayer {
+  func isServerDriven(_: WidgetScope) -> Bool {
+    false
+  }
+}
+
+/// The only way to read server-update settings.
+///
+/// Layers are walked lowest to highest and merged by the rule stated once here: `headers` and
+/// `query` merge per key, everything else takes the value from the highest layer that sets it.
+/// Adding a layer later — an instance layer above `widget`, say — is a new
+/// `WidgetServerSettingsLayer` plus one entry in `layers`; this API and every caller stay as they
+/// are.
+public struct WidgetServerSettingsResolver: Sendable {
+  private let layers: [any WidgetServerSettingsLayer]
+  private let revisionSource: @Sendable () -> Int
+
+  /// - Parameter layers: lowest priority first: config, credentials, global, widget.
+  public init(layers: [any WidgetServerSettingsLayer], revisionSource: @escaping @Sendable () -> Int) {
+    self.layers = layers
+    self.revisionSource = revisionSource
+  }
+
+  /// Flattens every layer for `scope`. Safe to call for any widget: a widget that is not
+  /// server-driven resolves to disabled with no URL, so a caller that fetches on `shouldFetch`
+  /// does nothing rather than guessing.
+  public func resolve(_ scope: WidgetScope) -> ResolvedWidgetServerSettings {
+    var merged = WidgetServerUpdateSettings.empty
+    var intervalFromConfig = false
+
+    for (index, layer) in layers.enumerated() {
+      guard let settings = layer.settings(for: scope) else { continue }
+
+      if settings.intervalMinutes != nil {
+        // Index 0 is the config layer. An interval that came from app.json was already validated
+        // against this platform's rules when the native project was generated, so clamping it
+        // again here would silently change an existing widget's schedule.
+        intervalFromConfig = index == 0
+      }
+
+      merged = Self.merge(lower: merged, higher: settings)
+    }
+
+    let serverDriven = isServerDriven(scope)
+    let url = serverDriven ? merged.url.flatMap { $0.isEmpty ? nil : $0 } : nil
+    let intervalMinutes = merged.intervalMinutes ?? WidgetServerUpdateDefaults.defaultIntervalMinutes
+
+    return ResolvedWidgetServerSettings(
+      url: url,
+      intervalMinutes: intervalFromConfig
+        ? intervalMinutes
+        : WidgetServerUpdateDefaults.clampIntervalMinutes(intervalMinutes),
+      enabled: serverDriven && (merged.enabled ?? true),
+      method: merged.method ?? WidgetServerUpdateDefaults.defaultMethod,
+      query: merged.query ?? [:],
+      headers: merged.headers ?? [:],
+      body: merged.body
+    )
+  }
+
+  /// True when app.json marked this widget server-driven. The engine is chosen at generate time,
+  /// so a runtime URL cannot make a widget server-driven and `setWidgetServerUpdate` rejects
+  /// settings for one that is not.
+  public func isServerDriven(_ scope: WidgetScope) -> Bool {
+    layers.contains { $0.isServerDriven(scope) }
+  }
+
+  /// Raw contents of the global layer: no defaulting, no merge — there is nothing to resolve
+  /// against without a widget scope. Nil when nothing has been set globally.
+  public func globalSettings() -> WidgetServerUpdateSettings? {
+    layers.lazy.compactMap { $0 as? GlobalWidgetServerSettingsLayer }.first?.raw()
+  }
+
+  /// Monotonic counter of settings changes. A fetcher records it before fetching and commits only
+  /// if it is still current, so settings changed mid-flight cannot commit a response built from
+  /// the old ones.
+  ///
+  /// It is one counter for the whole store rather than one per scope: a change to another widget
+  /// can make an in-flight fetch drop its result, and the reload that every `set` queues fetches
+  /// again, so the cost is one wasted request in a rare race.
+  public func revision(_: WidgetScope) -> Int {
+    revisionSource()
+  }
+
+  static func merge(
+    lower: WidgetServerUpdateSettings,
+    higher: WidgetServerUpdateSettings
+  ) -> WidgetServerUpdateSettings {
+    WidgetServerUpdateSettings(
+      url: higher.url ?? lower.url,
+      intervalMinutes: higher.intervalMinutes ?? lower.intervalMinutes,
+      enabled: higher.enabled ?? lower.enabled,
+      method: higher.method ?? lower.method,
+      query: mergePerKey(lower.query, higher.query),
+      headers: mergePerKey(lower.headers, higher.headers),
+      body: higher.body ?? lower.body
+    )
+  }
+
+  private static func mergePerKey(
+    _ lower: [String: String]?,
+    _ higher: [String: String]?
+  ) -> [String: String]? {
+    guard let lower else { return higher }
+    guard let higher else { return lower }
+
+    return lower.merging(higher) { _, fromHigher in fromHigher }
+  }
+}

package/ios/shared/WidgetServer/WidgetServerSettingsStore.swift

@@ -0,0 +1,170 @@
+import Foundation
+import Security
+
+/// The only way to write server-update settings, and the storage behind the three runtime layers.
+///
+/// Records live in the same shared Keychain the widget credentials have always used, so nothing
+/// migrates: the deprecated `setWidgetServerCredentials` keeps writing the accounts it always did,
+/// and this store adds its own accounts alongside them. The Keychain is also the only store both
+/// the app and the widget extension can reach without depending on an App Group being configured.
+///
+/// Callers do not read through this class. They read through `WidgetServerSettingsResolver`, which
+/// is what keeps the layer order and the merge rule in one place.
+public enum WidgetServerSettingsStore {
+  private static let service = "voltra-widget-server-credentials"
+  private static let globalAccount = "server_update_global"
+  private static let widgetAccountPrefix = "server_update_widget_"
+  private static let revisionAccount = "server_update_revision"
+
+  // MARK: - Writes
+
+  /// Replaces the global layer, or one widget's layer when `scope` is given.
+  @discardableResult
+  public static func set(_ settings: WidgetServerUpdateSettings, scope: WidgetScope?) -> Bool {
+    guard let data = WidgetServerSettingsCodec.encode(settings) else { return false }
+
+    let saved = write(data, account: account(for: scope))
+    bumpRevision()
+
+    return saved
+  }
+
+  /// Empties the global layer, or one widget's layer when `scope` is given.
+  public static func clear(scope: WidgetScope?) {
+    delete(account: account(for: scope))
+    bumpRevision()
+  }
+
+  /// Bumps the revision without changing a layer. The credentials layer writes through the
+  /// deprecated credential API, which does not go through `set`, so it calls this to make sure an
+  /// in-flight fetch built with the old token does not commit.
+  public static func bumpRevision() {
+    let next = revision() &+ 1
+    write(Data("\(next)".utf8), account: revisionAccount)
+  }
+
+  public static func revision() -> Int {
+    guard let data = read(account: revisionAccount),
+          let text = String(data: data, encoding: .utf8),
+          let value = Int(text)
+    else {
+      return 0
+    }
+
+    return value
+  }
+
+  // MARK: - Reads
+
+  static func settings(scope: WidgetScope?) -> WidgetServerUpdateSettings? {
+    WidgetServerSettingsCodec.decode(read(account: account(for: scope)))
+  }
+
+  private static func account(for scope: WidgetScope?) -> String {
+    guard let scope else { return globalAccount }
+
+    return "\(widgetAccountPrefix)\(scope.storageKey)"
+  }
+
+  // MARK: - Keychain
+
+  private static func baseQuery(account: String) -> [String: Any] {
+    var query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: account,
+    ]
+
+    if let group = VoltraConfig.keychainGroup() {
+      query[kSecAttrAccessGroup as String] = group
+    }
+
+    return query
+  }
+
+  @discardableResult
+  private static func write(_ data: Data, account: String) -> Bool {
+    delete(account: account)
+
+    var query = baseQuery(account: account)
+    query[kSecValueData as String] = data
+    query[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlock
+
+    let status = SecItemAdd(query as CFDictionary, nil)
+
+    if status != errSecSuccess {
+      VoltraLogger.keychain.error("Failed to save widget server settings: \(status, privacy: .public)")
+    }
+
+    return status == errSecSuccess
+  }
+
+  private static func read(account: String) -> Data? {
+    var query = baseQuery(account: account)
+    query[kSecReturnData as String] = true
+    query[kSecMatchLimit as String] = kSecMatchLimitOne
+
+    var item: CFTypeRef?
+    let status = SecItemCopyMatching(query as CFDictionary, &item)
+
+    guard status == errSecSuccess, let data = item as? Data else {
+      if status != errSecItemNotFound {
+        VoltraLogger.keychain.error("Failed to read widget server settings: \(status, privacy: .public)")
+      }
+      return nil
+    }
+
+    return data
+  }
+
+  private static func delete(account: String) {
+    SecItemDelete(baseQuery(account: account) as CFDictionary)
+  }
+}
+
+/// Settings the app set for every server-driven widget.
+struct GlobalWidgetServerSettingsLayer: WidgetServerSettingsLayer {
+  let name = "global"
+
+  func settings(for _: WidgetScope) -> WidgetServerUpdateSettings? {
+    WidgetServerSettingsStore.settings(scope: nil)
+  }
+
+  /// Raw contents of this layer, for reading back what was set — no scope to resolve against.
+  func raw() -> WidgetServerUpdateSettings? {
+    WidgetServerSettingsStore.settings(scope: nil)
+  }
+}
+
+/// Settings the app set for one widget. Highest layer until instance scopes arrive.
+struct WidgetWidgetServerSettingsLayer: WidgetServerSettingsLayer {
+  let name = "widget"
+
+  func settings(for scope: WidgetScope) -> WidgetServerUpdateSettings? {
+    WidgetServerSettingsStore.settings(scope: scope)
+  }
+}
+
+/// The deprecated `setWidgetServerCredentials` API, expressed as a settings layer.
+///
+/// It reads the same token and header records it always has, which is why nothing migrates. It
+/// sits below the global layer so an app that has moved to
+/// `setWidgetServerUpdate({ headers: { Authorization: ... } })` overrides whatever an older call
+/// left behind, rather than the other way round.
+struct CredentialsWidgetServerSettingsLayer: WidgetServerSettingsLayer {
+  let name = "credentials"
+
+  func settings(for _: WidgetScope) -> WidgetServerUpdateSettings? {
+    var headers: [String: String] = [:]
+
+    if let token = VoltraKeychainHelper.readToken(), !token.isEmpty {
+      headers["Authorization"] = "Bearer \(token)"
+    }
+
+    if let custom = VoltraKeychainHelper.readHeaders() {
+      headers.merge(custom) { _, fromCustom in fromCustom }
+    }
+
+    return headers.isEmpty ? nil : WidgetServerUpdateSettings(headers: headers)
+  }
+}