ubriot-updates-rn 0.1.4 → 0.4.0

package/README.md

@@ -14,8 +14,21 @@ native + JS runtime that consumes those updates in a bare app.
 - Talks to the existing `GET /ubriot/updates/manifest` endpoint (Expo-Updates-style
   manifest contract, including the `expo-runtime-version`, `expo-channel-name`, and
   `expo-current-update-id` request headers).
-- Downloads the manifest's `launchAsset` bundle to app storage (iOS
-  `Library/ubriot-updates/`, Android `filesDir/ubriot-updates/`).
+- Downloads the manifest's `launchAsset` bundle AND every asset in `manifest.assets`
+  (fonts, images, anything the bundle references) into one folder per update (iOS
+  `Library/ubriot-updates/<id>/`, Android `filesDir/ubriot-updates/<id>/`). Redirects are
+  followed and each file's SHA-256 is checked when the manifest carries a `hash`. The
+  update is only staged once every file is present and verified; any failure discards
+  it and the app keeps running what it has.
+- Keeps every verified file in a content-addressed cache (`ubriot-updates/cache/`, keyed
+  by hash), so a download cut short by the user leaving the app resumes where it stopped
+  on the next launch, and files that did not change between updates are never fetched
+  twice. The cache is trimmed to the last staged update's files. On iOS the download
+  also asks for background time, so it keeps going for a short while after the app is
+  sent to the background.
+- Resolves the bundle's `require('./font.ttf')` / `require('./image.png')` references to
+  the downloaded files (matched by content hash), falling back to the copy embedded in
+  the native build for anything the update did not ship.
 - Persists which bundle is `pending`, `active`, `verified`, and `lastKnownGood` in a
   small `state.json` next to the bundles.
 - Boots the verified/active downloaded bundle instead of the embedded one, with
@@ -47,6 +60,8 @@ UbriotUpdates.configure({
   appSlug: "your-app-slug",
   channel: "production",
   runtimeVersion: "your-app-1.0.0",
+  nativeBuildId: "358",
+  nativeBuildCreatedAt: "2026-09-26T00:00:00.000Z",
 });
 
 // Convenience: check -> download -> apply (does not restart by default)
@@ -57,25 +72,60 @@ const { available, manifestId } = await UbriotUpdates.checkForUpdate();
 const { ready } = await UbriotUpdates.downloadUpdate();
 await UbriotUpdates.applyUpdate({ restart: true }); // reload JS now
 
-// Call once the app has rendered and run OK. Promotes the active bundle to
-// "verified" so it becomes the rollback target instead of being rolled back.
+// Call once the first real screen has rendered (not the splash). Promotes the
+// running bundle to "verified" so it becomes the rollback target instead of being
+// rolled back on the next launch.
 UbriotUpdates.markLaunchSuccessful();
+
+// Fallback only: mark the launch after a delay if you cannot hook a render.
+// Returns a cancel function. An explicit markLaunchSuccessful() cancels it.
+const cancel = UbriotUpdates.markLaunchSuccessfulAfter(4000);
 ```
 
-Recommended app-start pattern:
+Import the package once at the top of your entry file (`index.js` / `App.tsx`) so its
+asset resolver is installed before any font or image is resolved:
 
 ```ts
-useEffect(() => {
-  UbriotUpdates.configure({ /* ... */ });
-  UbriotUpdates.sync().catch(() => {});
-  const t = setTimeout(() => UbriotUpdates.markLaunchSuccessful(), 4000);
-  return () => clearTimeout(t);
-}, []);
+import * as UbriotUpdates from "ubriot-updates-rn";
+```
+
+Recommended app-start pattern:
+
+```tsx
+function Root() {
+  useEffect(() => {
+    UbriotUpdates.configure({ /* ... */ });
+    UbriotUpdates.sync().catch(() => {});
+  }, []);
+  return <App onFirstScreenRendered={() => UbriotUpdates.markLaunchSuccessful()} />;
+}
 ```
 
+Call `markLaunchSuccessful()` from the first screen that proves the app works (for
+example in a `useEffect` of the signed-in or signed-out home screen, after fonts have
+loaded). Do not call it from a timer on the splash: a timer marks a hung or broken
+update as good, and then it is never rolled back. `markLaunchSuccessfulAfter(ms)` exists
+only as a fallback for apps that cannot hook a render; it gives crash-on-launch
+protection but not hang protection.
+
 `sync()` downloads and stages the update; it applies on the next launch. Use
 `applyUpdate({ restart: true })` if you want to reload immediately.
 
+`nativeBuildId` and `nativeBuildCreatedAt` are optional and let the server-side
+staleness guard tell a stale native shell apart from a stale OTA bundle. Expo apps can
+read these from `Constants.expoConfig?.extra?.ubriotBuild` (set by the config plugin at
+build time) and pass them straight into `configure()`. Bare RN apps that don't use Expo
+config can supply their own build metadata the same way. `nativeBuildCreatedAt` must be
+a UTC ISO string (e.g. `2026-09-26T00:00:00.000Z`).
+
+Apps that use a dynamic Expo config (`app.config.js` / `app.config.ts` instead of
+`app.json` / `app.config.json`) are not auto-stamped: the Ubriot build worker only
+writes `expo.extra.ubriotBuild` into static JSON config files, and skips dynamic config
+with a warning in the build logs. Those apps must supply `nativeBuildId` and
+`nativeBuildCreatedAt` to `configure()` themselves (for example, by reading build
+metadata baked in through `app.config.js`'s own logic), otherwise per-device OTA
+staleness checks are skipped for that app.
+
 ## Rollback model
 
 - A freshly applied bundle is `active` but unverified.
@@ -84,8 +134,33 @@ useEffect(() => {
 - If the app boots that bundle again while still unverified (meaning the previous launch
   never reached `markLaunchSuccessful()`, e.g. it crashed on load), the client reverts to
   the last known good bundle (or the embedded bundle) instead.
-- `markLaunchSuccessful()` marks the active bundle verified and records it as the new last
-  known good.
+- `markLaunchSuccessful()` marks the bundle that is actually running verified and records
+  it as the new last known good. An update that was downloaded and applied during this
+  session (and has not run yet) is never marked verified by it.
+- An update that was rolled back is remembered (`failedUpdateIds`) and is not downloaded
+  again, so a bad update cannot loop.
+
+## Upgrading from 0.1.x
+
+0.2.0 changes native code, so it needs a new native build (TestFlight / Play). On an old
+native build the new JS falls back to the old bundle-only download. Replace any
+`setTimeout(() => markLaunchSuccessful(), 4000)` with a call from your first rendered
+screen. If you added your own asset source transformer as a workaround for missing OTA
+assets, remove it, or register it after importing this package.
+
+## React Native 0.88 and Expo SDK 58
+
+0.4.0 builds and type-checks against React Native 0.88 and its strict TypeScript API
+(public `react-native` imports only), and still against 0.83. The native module does not
+use app delegate callbacks or the key window, so the SDK 58 scene life cycle
+(`SceneDelegate.swift`) needs no changes: the release bundle is still chosen in
+`ReactNativeDelegate.bundleURL()`. For the R8 minification SDK 58 enables by default, the
+Android library ships `consumer-rules.pro`, which keeps `dev.ubriot.updates.**` and every
+`@ReactMethod`, and apps pick it up automatically. This is expected to work but has not yet
+been confirmed with a real `assembleRelease` build.
+The config plugin now also patches the `ExpoReactHostFactory.getDefaultReactHost` host
+used by Expo templates from SDK 55. Moving to SDK 58 is a native change: give the new
+build a new `runtimeVersion`.
 
 ## Native integration
 
@@ -166,8 +241,52 @@ The `runtimeVersion` you pass here MUST match the `runtimeVersion` passed to
 `configure()`. Only JS-only changes can ship over the air; anything touching native code
 requires a new store/TestFlight build with a bumped runtime version.
 
-## Signature verification
+## Code signing
+
+From 0.3.0, updates can be code signed. Verification runs natively on iOS
+(Security.framework) and Android (`java.security`), against certificates embedded in the
+binary at build time, using the same wire format as expo-updates.
+
+Set it up with the Ubriot CLI, which writes these plugin options for you:
+
+```sh
+ubriot signing init --app my-app
+ubriot signing configure --app my-app
+```
+
+```json
+["ubriot-updates-rn", {
+  "codeSigningCertificate": "./certs/ubriot-ota-main.pem",
+  "codeSigningMetadata": { "keyid": "main", "alg": "rsa-v1_5-sha256" },
+  "codeSigningIncludeManifestResponseCertificateChain": false,
+  "additionalTrustedCertificates": [{ "certificate": "./certs/ubriot-ota-next.pem", "keyid": "next" }]
+}]
+```
 
-Manifest signature verification is stubbed (`verifyManifestSignature` currently returns
-`true`) and structured as a single async gate in `checkForUpdate`, ready to enforce a
-signed-manifest policy later.
+- `codeSigningCertificate`: the certificate (simple mode) or root certificate (chain mode)
+  to trust. Only the public certificate is embedded; a file containing a private key is
+  refused at prebuild.
+- `codeSigningIncludeManifestResponseCertificateChain`: `true` for chain mode.
+- `additionalTrustedCertificates`: optional pre-provisioned keys, so a simple mode key can
+  be rotated without a new binary.
+- `codeSigningAllowUnsignedManifests` is not supported.
+
+With a certificate configured, `checkForUpdate()` asks the native module to fetch and
+verify the manifest (`fetchManifest`), and `downloadUpdate()` passes only the opaque token
+of a verified manifest, so JavaScript cannot hand the downloader an unverified asset list.
+Every asset must carry a hash. Signed updates are also bound to the configured app,
+platform and runtime version, and an update older than the newest one this device accepted
+for that runtime is refused unless the device accepted that update before. Channel
+rollbacks to an update the device already ran therefore still apply, but a device that never
+had the older update stays where it is; to roll those devices back, publish the old code
+again as a new update. A `createdAt` more than ten minutes in the future is never recorded,
+so a wrong developer clock cannot lock a runtime.
+
+A rejected update never changes the running code: `checkForUpdate()` returns
+`{ available: false }` and the reason is reported to Ubriot (`missing-signature`,
+`bad-signature`, `untrusted-certificate`, `expired-certificate`, `binding-mismatch`,
+`parse-error`). If a binary has a certificate but its native module is older than 0.3.0,
+updates fail closed. `configure({ ..., requireCodeSigning: true })` forces the same fail
+closed behaviour from JavaScript; set it only in binaries that embed a certificate.
+
+Apps without these options behave exactly as before.

package/android/build.gradle

@@ -12,6 +12,7 @@ android {
   defaultConfig {
     minSdkVersion safeExtGet("minSdkVersion", 24)
     targetSdkVersion safeExtGet("targetSdkVersion", 36)
+    consumerProguardFiles "consumer-rules.pro"
   }
 
   buildFeatures {

package/android/consumer-rules.pro

@@ -0,0 +1,4 @@
+-keep class dev.ubriot.updates.** { *; }
+-keepclassmembers class * {
+    @com.facebook.react.bridge.ReactMethod <methods>;
+}

package/android/src/main/java/dev/ubriot/updates/UbriotCodeSigning.kt

@@ -0,0 +1,334 @@
+package dev.ubriot.updates
+
+import java.security.Signature
+import java.security.cert.CertificateExpiredException
+import java.security.cert.CertificateFactory
+import java.security.cert.CertificateNotYetValidException
+import java.security.cert.X509Certificate
+import java.util.Date
+import kotlin.math.min
+
+object UbriotCodeSigning {
+  const val ALGORITHM = "rsa-v1_5-sha256"
+  const val DEFAULT_KEYID = "root"
+  private const val CODE_SIGNING_EKU = "1.3.6.1.5.5.7.3.3"
+  private const val BEGIN = "-----BEGIN CERTIFICATE-----"
+  private const val END = "-----END CERTIFICATE-----"
+  private const val MAX_CLOCK_SKEW_MS = 10 * 60 * 1000L
+  private val ISO_INSTANT = Regex("^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$")
+
+  data class TrustedCertificate(val pem: String, val keyid: String)
+
+  data class Config(val trusted: List<TrustedCertificate>, val includeChain: Boolean)
+
+  class ParsedResponse(val manifestBody: ByteArray, val signature: String?, val certificateChain: String?)
+
+  sealed class Outcome {
+    class Verified(val body: ByteArray) : Outcome()
+    class Rejected(val reason: String, val detail: String) : Outcome()
+  }
+
+  class RejectedException(val reason: String, message: String) : Exception(message)
+
+  data class SignatureHeader(val sig: String, val keyid: String, val alg: String)
+
+  fun expectSignatureHeader(keyid: String): String = "sig, keyid=\"${escape(keyid)}\", alg=\"$ALGORITHM\""
+
+  private fun escape(value: String) = value.replace("\\", "\\\\").replace("\"", "\\\"")
+
+  fun parseDictionaryStrings(header: String): Map<String, String?> {
+    val out = LinkedHashMap<String, String?>()
+    var i = 0
+    val n = header.length
+    fun skipSpaces() { while (i < n && (header[i] == ' ' || header[i] == '\t')) i++ }
+    while (true) {
+      skipSpaces()
+      if (i >= n) break
+      val keyStart = i
+      while (i < n && (header[i].isLetterOrDigit() || header[i] == '_' || header[i] == '-' || header[i] == '.' || header[i] == '*')) i++
+      val key = header.substring(keyStart, i)
+      if (key.isEmpty()) throw IllegalArgumentException("Malformed structured header at offset $i")
+      var value: String? = null
+      if (i < n && header[i] == '=') {
+        i++
+        if (i < n && header[i] == '"') {
+          i++
+          val sb = StringBuilder()
+          var closed = false
+          while (i < n) {
+            val c = header[i++]
+            if (c == '\\') {
+              if (i >= n) throw IllegalArgumentException("Unterminated escape")
+              sb.append(header[i++])
+            } else if (c == '"') {
+              closed = true
+              break
+            } else {
+              sb.append(c)
+            }
+          }
+          if (!closed) throw IllegalArgumentException("Unterminated string")
+          value = sb.toString()
+        } else {
+          while (i < n && header[i] != ',' && header[i] != ';') i++
+        }
+      }
+      while (i < n && header[i] != ',') {
+        if (header[i] == '"') throw IllegalArgumentException("Unexpected quote")
+        i++
+      }
+      out[key] = value
+      if (i < n && header[i] == ',') i++
+    }
+    return out
+  }
+
+  fun parseSignatureHeader(header: String): SignatureHeader {
+    val members = parseDictionaryStrings(header)
+    val sig = members["sig"] ?: throw IllegalArgumentException("Structured field sig not found in expo-signature header")
+    return SignatureHeader(sig, members["keyid"] ?: DEFAULT_KEYID, members["alg"] ?: ALGORITHM)
+  }
+
+  fun splitCertificates(pem: String): List<String> {
+    val out = mutableListOf<String>()
+    var index = 0
+    while (true) {
+      val start = pem.indexOf(BEGIN, index)
+      val end = pem.indexOf(END, index)
+      if (start == -1 || end == -1 || end < start) break
+      out.add(pem.substring(start, end + END.length))
+      index = end + END.length
+    }
+    return out
+  }
+
+  private fun indexOf(haystack: ByteArray, needle: ByteArray, from: Int): Int {
+    if (needle.isEmpty()) return from
+    var i = from
+    while (i <= haystack.size - needle.size) {
+      var match = true
+      for (j in needle.indices) {
+        if (haystack[i + j] != needle[j]) {
+          match = false
+          break
+        }
+      }
+      if (match) return i
+      i++
+    }
+    return -1
+  }
+
+  private fun dispositionName(value: String?): String? {
+    if (value == null) return null
+    val match = Regex("name\\s*=\\s*\"?([^\";]+)\"?", RegexOption.IGNORE_CASE).find(value) ?: return null
+    return match.groupValues[1]
+  }
+
+  fun parseResponse(contentType: String?, headerSignature: String?, body: ByteArray): ParsedResponse {
+    val type = contentType?.lowercase() ?: ""
+    if (!type.startsWith("multipart/")) return ParsedResponse(body, headerSignature, null)
+    val boundary = Regex("boundary=\"?([^\";]+)\"?", RegexOption.IGNORE_CASE).find(contentType!!)?.groupValues?.get(1)
+      ?: throw RejectedException("parse-error", "multipart response without boundary")
+    val delimiter = "--$boundary".toByteArray(Charsets.UTF_8)
+    val separator = "\r\n--$boundary".toByteArray(Charsets.UTF_8)
+    val headerEnd = "\r\n\r\n".toByteArray(Charsets.UTF_8)
+    var manifest: ByteArray? = null
+    var signature: String? = null
+    var chain: String? = null
+    var index = indexOf(body, delimiter, 0)
+    while (index != -1) {
+      val after = index + delimiter.size
+      if (after + 2 <= body.size && body[after] == '-'.code.toByte() && body[after + 1] == '-'.code.toByte()) break
+      val headersStart = after + 2
+      val headersEnd = indexOf(body, headerEnd, headersStart)
+      if (headersEnd == -1) throw RejectedException("parse-error", "malformed multipart part")
+      val next = indexOf(body, separator, headersEnd)
+      if (next == -1) throw RejectedException("parse-error", "unterminated multipart part")
+      val headers = HashMap<String, String>()
+      String(body, headersStart, headersEnd - headersStart, Charsets.UTF_8).split("\r\n").forEach { line ->
+        val colon = line.indexOf(':')
+        if (colon > 0) headers[line.substring(0, colon).trim().lowercase()] = line.substring(colon + 1).trim()
+      }
+      val partBody = body.copyOfRange(headersEnd + headerEnd.size, next)
+      when (dispositionName(headers["content-disposition"])) {
+        "manifest" -> {
+          manifest = partBody
+          signature = headers["expo-signature"]
+        }
+        "certificate_chain" -> chain = String(partBody, Charsets.UTF_8)
+      }
+      index = next + 2
+    }
+    val manifestBody = manifest ?: throw RejectedException("parse-error", "multipart response without a manifest part")
+    return ParsedResponse(manifestBody, signature, chain)
+  }
+
+  private fun certificate(pem: String): X509Certificate {
+    return CertificateFactory.getInstance("X.509").generateCertificate(pem.byteInputStream()) as X509Certificate
+  }
+
+  private fun X509Certificate.isCodeSigning(): Boolean {
+    val usage = keyUsage
+    val extended = extendedKeyUsage
+    return usage != null && usage.isNotEmpty() && usage[0] && extended != null && extended.contains(CODE_SIGNING_EKU)
+  }
+
+  private fun X509Certificate.isCertificateAuthority(): Boolean {
+    val usage = keyUsage
+    return basicConstraints > -1 && usage != null && usage.size > 5 && usage[5]
+  }
+
+  private fun validateChain(chain: List<X509Certificate>, now: Date): X509Certificate {
+    if (chain.isEmpty()) throw RejectedException("untrusted-certificate", "No certificates")
+    for (cert in chain) {
+      try {
+        cert.checkValidity(now)
+      } catch (error: CertificateExpiredException) {
+        throw RejectedException("expired-certificate", "Certificate expired")
+      } catch (error: CertificateNotYetValidException) {
+        throw RejectedException("expired-certificate", "Certificate not yet valid")
+      }
+    }
+    try {
+      for (i in 0 until chain.size - 1) {
+        if (chain[i].issuerX500Principal != chain[i + 1].subjectX500Principal) throw RejectedException("untrusted-certificate", "Certificates do not chain")
+        chain[i].verify(chain[i + 1].publicKey)
+      }
+      val root = chain.last()
+      if (root.issuerX500Principal != root.subjectX500Principal) throw RejectedException("untrusted-certificate", "Root certificate not self-signed")
+      root.verify(root.publicKey)
+    } catch (error: RejectedException) {
+      throw error
+    } catch (error: Exception) {
+      throw RejectedException("untrusted-certificate", "Certificate chain does not verify")
+    }
+    if (chain.size > 1) {
+      val root = chain.last()
+      if (!root.isCertificateAuthority()) throw RejectedException("untrusted-certificate", "Root certificate must be a certificate authority")
+      var maxPathLength = root.basicConstraints
+      for (i in chain.size - 2 downTo 1) {
+        val cert = chain[i]
+        if (!cert.isCertificateAuthority()) throw RejectedException("untrusted-certificate", "Intermediate certificate must be a certificate authority")
+        if (maxPathLength <= 0) throw RejectedException("untrusted-certificate", "pathLenConstraint violated")
+        maxPathLength = min(cert.basicConstraints, maxPathLength - 1)
+      }
+    }
+    val leaf = chain.first()
+    if (!leaf.isCodeSigning()) throw RejectedException("untrusted-certificate", "Leaf is not a code signing certificate")
+    return leaf
+  }
+
+  private fun decodeBase64(input: String): ByteArray {
+    val alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+    val clean = input.filter { !it.isWhitespace() }.trimEnd('=')
+    val out = java.io.ByteArrayOutputStream()
+    var buffer = 0
+    var bits = 0
+    for (c in clean) {
+      val value = alphabet.indexOf(c)
+      if (value < 0) throw IllegalArgumentException("Invalid base64")
+      buffer = (buffer shl 6) or value
+      bits += 6
+      if (bits >= 8) {
+        bits -= 8
+        out.write((buffer shr bits) and 0xff)
+      }
+    }
+    return out.toByteArray()
+  }
+
+  fun verify(config: Config, response: ParsedResponse, now: Date = Date()): Outcome {
+    return try {
+      val header = response.signature ?: throw RejectedException("missing-signature", "No expo-signature")
+      val info = try {
+        parseSignatureHeader(header)
+      } catch (error: Exception) {
+        throw RejectedException("bad-signature", "Malformed expo-signature")
+      }
+      if (info.alg != ALGORITHM) throw RejectedException("bad-signature", "Unsupported algorithm")
+      val leaf = if (config.includeChain) {
+        val served = splitCertificates(response.certificateChain ?: "")
+        var lastError: RejectedException? = null
+        var accepted: X509Certificate? = null
+        for (anchor in config.trusted) {
+          try {
+            accepted = validateChain((served + anchor.pem).map { certificate(it) }, now)
+            break
+          } catch (error: RejectedException) {
+            lastError = error
+          }
+        }
+        accepted ?: throw (lastError ?: RejectedException("untrusted-certificate", "No trusted root"))
+      } else {
+        val anchor = config.trusted.firstOrNull { it.keyid == info.keyid }
+          ?: throw RejectedException("untrusted-certificate", "keyid ${info.keyid} is not trusted by this binary")
+        validateChain(listOf(certificate(anchor.pem)), now)
+      }
+      val signatureBytes = try {
+        decodeBase64(info.sig)
+      } catch (error: Exception) {
+        throw RejectedException("bad-signature", "Signature is not base64")
+      }
+      val valid = try {
+        Signature.getInstance("SHA256withRSA").run {
+          initVerify(leaf.publicKey)
+          update(response.manifestBody)
+          verify(signatureBytes)
+        }
+      } catch (error: Exception) {
+        false
+      }
+      if (!valid) throw RejectedException("bad-signature", "Incorrect signature")
+      Outcome.Verified(response.manifestBody)
+    } catch (error: RejectedException) {
+      Outcome.Rejected(error.reason, error.message ?: error.reason)
+    } catch (error: Exception) {
+      Outcome.Rejected("untrusted-certificate", error.message ?: "Certificate error")
+    }
+  }
+
+  fun checkBindings(
+    expectedRuntime: String,
+    configuredApp: String,
+    manifestRuntime: String?,
+    boundAppId: String?,
+    boundSlugs: List<String>?,
+    manifestId: String,
+    createdAt: String?,
+    newestAcceptedCreatedAt: String?,
+    allowedIds: Set<String>,
+    devicePlatform: String,
+    boundPlatform: String?,
+  ): String? {
+    if (manifestRuntime != expectedRuntime) return "runtime version ${manifestRuntime ?: "missing"} does not match $expectedRuntime"
+    if (boundPlatform != null && boundPlatform != devicePlatform) return "manifest was built for $boundPlatform"
+    if (boundAppId != null || boundSlugs != null) {
+      val matches = boundAppId == configuredApp || (boundSlugs?.contains(configuredApp) == true)
+      if (!matches) return "manifest is bound to another app"
+    }
+    if (createdAt != null && newestAcceptedCreatedAt != null && manifestId !in allowedIds &&
+      ISO_INSTANT.matches(createdAt) && ISO_INSTANT.matches(newestAcceptedCreatedAt) && normalizeInstant(createdAt) < normalizeInstant(newestAcceptedCreatedAt)
+    ) {
+      return "manifest is older than one this device already accepted"
+    }
+    return null
+  }
+
+  fun laterInstant(current: String?, candidate: String?, now: Date = Date()): String? {
+    if (candidate == null || !ISO_INSTANT.matches(candidate)) return current
+    val limit = java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", java.util.Locale.US).apply {
+      timeZone = java.util.TimeZone.getTimeZone("UTC")
+    }.format(Date(now.time + MAX_CLOCK_SKEW_MS))
+    if (normalizeInstant(candidate) > normalizeInstant(limit)) return current
+    if (current == null || !ISO_INSTANT.matches(current)) return candidate
+    return if (normalizeInstant(candidate) > normalizeInstant(current)) candidate else current
+  }
+
+  private fun normalizeInstant(value: String): String {
+    val dot = value.indexOf('.')
+    if (dot == -1) return value.dropLast(1) + ".000000000Z"
+    val fraction = value.substring(dot + 1, value.length - 1).padEnd(9, '0')
+    return value.substring(0, dot) + "." + fraction + "Z"
+  }
+}