nts #

Tamper-proof time synchronization for Dart and Flutter.

Why NTS? #

Most apps trust whatever time their device reports, and that time ultimately comes from plain NTP — an unauthenticated protocol that any attacker on the network path can forge or replay. Shifting a client's clock breaks anything anchored to it: TLS certificate validity, JWT expiry, TOTP codes, OAuth refresh windows, license checks, audit logs.

Network Time Security (NTS) fixes this by authenticating the time server with TLS and cryptographically signing every time response. A forged or modified reply is rejected; a hijacked NTP server is detected. The result is a clock you can trust as much as you trust the operator's TLS certificate, rather than as much as you trust the network between you and an anonymous UDP listener.

This package gives Dart and Flutter apps a single async call (ntsGetTime) that returns an authenticated, sleep-aware monotonic-anchored UTC clock, with the protocol details delegated to a bundled native implementation. Lower-level primitives remain available for callers who need manual control. See ARCHITECTURE.md for the underlying RFC 8915 layering and cryptographic specifics.

Getting Started #

Prerequisites #

• Flutter ≥ 3.38.0 (Dart ≥ 3.10). The package depends on the Flutter SDK and ships a Flutter plugin module on Android, so it must be consumed from a Flutter app — dart pub add nts from a pure-Dart project will not resolve.

• rustup on your PATH. The protocol core ships as Rust source and is compiled on your machine by the Flutter Native Assets build hook the first time you run flutter run / flutter build. The hook reads rust/rust-toolchain.toml via rustup, which automatically installs the pinned toolchain (currently Rust 1.98.0) and the cross-compile target for the platform being built. No manual cargo invocation, dylib copying, or build configuration is needed — but without rustup installed the build fails at the hook step.

  New to Rust? Installing rustup is a one-time step; see the official install page (or the longer-form rust-lang.org guide):

  • macOS / Linux: run the curl … | sh one-liner from rustup.rs, or brew install rustup on Homebrew.
  • Windows: download and run rustup-init.exe from rustup.rs. It will prompt you to install the Visual Studio C++ Build Tools if they are missing — accept, as the MSVC linker is required to build the crate.

  Restart your terminal (or IDE) afterwards so the updated PATH is picked up, and verify with rustup --version.

  The same mechanism covers toolchain upgrades: when a release of this package bumps the pin in rust/rust-toolchain.toml, the next flutter run / flutter build auto-downloads the new version — no rustup update or other manual step is needed. The superseded toolchain stays on disk; reclaim the space with rustup toolchain uninstall <old-version> if you like.

• Android NDK r28 or newer in your Android SDK, on Android only. Android 15+ requires 64-bit native libraries to be 16 KB page aligned, and the NDK clang driver only defaults to that from r28 — r27 and earlier produce a 4 KB-aligned libnts_rust.so that Google Play rejects. Nothing to do on a current setup, since every Flutter this package supports installs an r28 NDK; if the newest NDK in your SDK is older, the build hook fails with a message naming the revision it found. Note that this is the NDK installed in the SDK, not the ndkVersion your app's Gradle script pins — the Native Assets build resolves its toolchain from the SDK independently, so raising or lowering ndkVersion does not change which NDK compiles the Rust library.

Install #

flutter pub add nts

Platform support #

Supported on Android, iOS, macOS, Linux, and Windows. On every platform, integration is flutter pub add nts plus one await NtsBridge.ensureInitialized() during application startup before the first ntsGetTime / ntsQuery / ntsWarmCookies call — no per-platform bootstrap code. See "Initialization has two layers" below for the rationale.

On Android the native bootstrap is automatic via the bundled NtsPlugin on the default Flutter/Gradle setup. The plugin adds upstream's GitHub-hosted Maven repository for the rustls-platform-verifier companion AAR (group org.rustls) to the host build, so the first Android build needs network access to github.com, or a mirror of that repository. The one exception: hosts that declare their repositories in settings.gradle.kts under RepositoriesMode.PREFER_SETTINGS (not the flutter create default) must add that repository there, because Gradle then ignores the plugin's project-level one; the rationale comment in this package's android/build.gradle.kts documents the full recipe. RepositoriesMode.FAIL_ON_PROJECT_REPOS is not supported: Gradle rejects the project-level repositories that both this plugin and the Flutter Gradle Plugin declare.

The AAR's manifest is merged into your app's. It adds the INTERNET permission and sets android:networkSecurityConfig to a config that permits cleartext HTTP only to the certificate revocation list (CRL) hosts upstream lists, so revocation checks can download CRLs. If your app sets its own android:networkSecurityConfig, the manifest merge fails until you add tools:replace="android:networkSecurityConfig" to your <application> element. Your config then applies instead: unless it permits cleartext HTTP to those hosts, CRL downloads are blocked and the revocation check soft-fails. A config of your own named network_security_config.xml replaces upstream's without a merge conflict.

Web and WebAssembly are unsupported: NTS-KE needs a raw TCP socket on :4460 and NTPv4 needs a raw UDP socket on :123, neither of which is reachable from a browser tab.

The strict clock selects a native backend on all five platforms, but how much of its behaviour has been observed differs by platform; see Platform evidence.

Quick start #

For most applications, ntsGetTime is the whole integration: one call that performs the NTS-KE handshake, takes a burst of up to 8 authenticated samples under a single 8-second total budget, picks the sample with the lowest network delay — the RFC 5905 peer delay when it falls inside the selection window (0, roundTripMicros], which healthy samples normally do, else the measured round trip — applies the standard delay / 2 compensation, and returns a synchronized clock with offset, jitter, and worst-case error-bound statistics.

import 'package:nts/nts.dart';

Future<void> main() async {
  // 1. Initialize the FRB bridge before anything else in this
  //    package. This loads the bundled Rust binary that does the
  //    actual NTS-KE handshake and AEAD-NTP exchange and wires the
  //    Dart-side dispatch table. Required on every platform, and safe
  //    to call from more than one bootstrap path.
  await NtsBridge.ensureInitialized();

  // 2. Pick an RFC 8915 NTS-KE endpoint. Port 4460 is the IANA default.
  const spec = NtsServerSpec(host: 'time.cloudflare.com', port: 4460);

  // 3. Synchronize. Handshake + 8-sample burst + lowest-delay
  //    selection + delay/2 compensation, all automatic under one
  //    8-second total budget.
  final synced = await ntsGetTime(spec: spec);

  // 4. Read the clock. `utcNow` projects the authenticated instant
  //    forward on a sleep-aware monotonic anchor (keeps counting
  //    through device deep sleep), so it stays correct even if the
  //    user or OS steps the system clock after the sync.
  print('authenticated utc = ${synced.utcNow}');
  print('winning sample rtt = ${synced.roundTripMicros}µs '
      '(${synced.samplesUsed} samples used)');
  print('offset = ${synced.offsetMicros}µs, '
      'jitter = ${synced.jitterMicros}µs, '
      'error ≤ ${synced.errorBoundMicros}µs at sync');
}

Keep the returned NtsSyncedTime and read utcNow on demand rather than re-querying per read; elapsedSinceSync reports the age of the sync so you can decide when a refresh is worth it. Local oscillator drift accumulates roughly a millisecond per minute-to-hour of age depending on hardware.

ntsGetTime's tuning is deliberately fixed (8-sample burst, one 8-second total budget, package-default concurrency caps): a zero-decision call sized to serve phones and desktops alike. If you need different numbers, compose the primitives yourself — see Manual control below.

Initialization has two layers. Get them straight before deciding what your host code needs to do.

1. Native platform bootstrap (Android only, automatic). On Android the bundled NtsPlugin captures the JavaVM + application Context that rustls-platform-verifier needs to reach the system X509TrustManager. It runs from GeneratedPluginRegistrant before Dart main() executes, so adding nts to your pubspec.yaml is enough — there is no MainActivity shim, JNI symbol, or app/build.gradle.kts Maven entry to maintain on the default Flutter/Gradle setup. (The PREFER_SETTINGS exception described under "Platform support" above is the one deviation from this.) iOS, macOS, Linux, and Windows have no equivalent step. Hosts that bypass the standard Flutter activity lifecycle (custom embeddings, isolates spawned ahead of plugin registration, integration tests driving the dylib directly) can call com.nllewellyn.nts.PlatformInit.init(context) from Kotlin directly; see the KDoc on that class.

2. Dart/FRB initialization (await NtsBridge.ensureInitialized(), every platform, manual). This loads the bundled Rust dylib through the Native Assets pipeline and wires the flutter_rust_bridge v2 dispatch table on the calling isolate. The Android plugin does not subsume this step: it mutates Dart isolate state, and the plugin runs on the Android platform thread before the Dart isolate exists. Calling ntsGetTime, ntsQuery, or ntsWarmCookies before it resolves raises an error. In a Flutter app, do it right after WidgetsFlutterBinding.ensureInitialized() in main(); while the bridge stays initialized, repeated and concurrent calls converge on the first one rather than re-initializing, so it is safe to call from a shared bootstrap path. A call after a disposal starts a fresh attempt instead.

   The underlying NtsRustLib.init() is exported too, for callers that need to drive the generated entrypoint directly (supplying their own api:, for instance). It rejects a call made while the entrypoint holds state, throwing a StateError; either NtsBridge.dispose() or the raw NtsRustLib.dispose() clears that state, so outside a deliberate teardown the first call is the only one that succeeds. Prefer NtsBridge.ensureInitialized() unless you specifically need the raw entrypoint.

A complete, runnable version with exhaustive NtsError handling lives in example/main.dart. For valid hostnames to plug into NtsServerSpec, see the community-maintained NTS server list.

Upgrading #

Migration notes for breaking releases live in CHANGELOG.md under the relevant version header. Releases up to and including 5.2.4 — among them the 5.0.0 RustLib → NtsRustLib rename and the 1.4.0 Android bootstrap rework (JNI symbol rename plus auto-init plugin) — are in CHANGELOG_ARCHIVE.md, which is kept in the repository but not shipped in the package.

Manual control (advanced primitives) #

ntsGetTime is the packaged implementation of the standard NTP-hygiene recipe. When its fixed tuning does not fit — a different burst size, a tighter or looser budget, handshake timing decoupled from sampling, custom filtering — the same protocol primitives it is built from are public:

• ntsQuery — one authenticated NTPv4 round-trip. Returns the raw protocol output (NtsTimeSample): the server's transmit timestamp plus the locally measured RTT. The first call handshakes implicitly; later calls reuse the cached session. Exposes the timeout, dnsConcurrencyCap, and bridgeConcurrencyCap knobs that ntsGetTime fixes internally.
• ntsWarmCookies — force a fresh NTS-KE handshake without sampling, e.g. to front-load the TLS cost at app startup or on a known-good network window. The returned NtsWarmCookiesOutcome.freshCookies reports how many single-use cookies the server delivered (RFC 8915 §4 leaves the pool size to server policy), which bounds how many ntsQuery calls can follow before the next implicit handshake.
• NtsClient — an owned client with its own session table and trust policy, for callers who need isolation from the default singleton or non-default TrustModes. Carries per-client query / warmCookies / getTime twins plus invalidate / clear session management. See Security considerations below.

A hand-rolled synchronized clock adds two layers on top of raw samples — the same two ntsGetTime automates:

1. Burst sampling. A single NTPv4 reply carries whatever jitter the network and the server's queueing happened to introduce on that one packet. Calling ntsWarmCookies once and then ntsQuery several times in quick succession — one query per delivered cookie — produces a small distribution you can reason about statistically. Pick the sample with the smallest network delay (peerDelayMicros when it falls inside (0, roundTripMicros], else roundTripMicros); on a low-delay path the symmetric-path assumption below holds tightest, so that sample carries the smallest residual offset error. T1 shares an anchor with roundTripMicros (stamped immediately before the request is built and sealed, which the send follows), so the window normally admits δ rather than rejecting it on the ordinary setup cost it carried before 9.2. What δ still carries that the round trip does not is that request build and seal plus the socket write-timeout re-arm before the send — neither blocking on I/O, but enough to put δ outside the window when the server's own T3−T2 is smaller still. Beyond that overhead, a δ outside the window is a clock step, a slew, or — on a loaded host — the worker being preempted between T1 and the send. Any such interval p adds p to δ and p/2 to offsetMicros, so taking the fallback keeps p out of the delay halved below; it does not undo the p/2 in the offset. See the peerDelayMicros dartdoc for the allowance to measure when applying a bound of your own. More sophisticated callers can median-filter, score by serverStratum, or run Marzullo's algorithm across multiple servers.

2. Symmetric-path delay compensation. utcUnixMicros is the moment the server stamped the reply, not the moment it landed locally. The reply then spent roughly half the network delay travelling back to the client, so the server's clock at the moment of arrival is best approximated as utcUnixMicros plus half the delay selected above. This is the standard NTP correction (RFC 5905 §8); it assumes the outbound and return paths are symmetric, which is why filtering on the lowest-delay sample matters — short paths are more likely to be symmetric.

Each sample also carries the fully computed RFC 5905 §8 statistics — offsetMicros (the true clock offset θ, from all four on-wire timestamps) and peerDelayMicros (the round trip minus the server's processing time) — plus the server-reported rootDelayMicros, rootDispersionMicros, and serverPrecision, so a custom filter can implement the full RFC 5905 clock-filter and root-distance recipes without re-deriving anything. Persist the winning offset and apply it on top of the device's monotonic clock rather than calling ntsQuery on every read; a few-second jitter floor on cellular networks makes per-call queries strictly worse than one well-filtered offset reused across many reads. (ntsGetTime does exactly this, returning the projection as NtsSyncedTime.utcNow alongside the winning offset, the burst's RMS jitter, and a worst-case errorBoundMicros.)

Below ntsGetTime, the package stops at protocol primitives by design: the right filter (lowest-delay, median, Marzullo across multiple servers, weighted by stratum), the right resampling cadence, and the right way to project the offset onto DateTime.now() are all workload specific. The example/main.dart snippet shows the minimum burst-filter-compensate flow described above built from the primitives.

Monotonic Time & Measurement Accuracy #

A time-synchronization package cannot trust the clock it exists to correct, so package:nts never meters a timeout or measures a network delay against the system clock. All internal timing runs on monotonic sources:

• Sleep-aware on the Dart side. Budgets and projections read the suspend-inclusive "boottime" clock family through the Rust core (CLOCK_BOOTTIME on Android/Linux, mach_continuous_time on iOS/macOS, QueryInterruptTimePrecise on Windows), exposed publicly as MonotonicClock. Unlike Dart's Stopwatch, readings keep advancing while the device is in deep sleep, so the NtsSyncedTime.utcNow projection stays correct across suspend/resume and an in-flight getTime budget expires on schedule instead of stalling.
• Monotonic deadlines in the Rust core. The NTS-KE handshake (DNS, TCP connect, TLS, record exchange) and the UDP exchange run under single shrinking Instant-anchored deadlines, so timeouts fire neither prematurely nor late regardless of NTP slews, clock steps, or manual adjustments mid-call.
• Trustworthy RTT. roundTripMicros is measured monotonically around the UDP round-trip, which matters because it is both the selection ceiling for the peer delay and the fallback delay driving ntsGetTime's burst selection and delay / 2 compensation whenever the peer delay falls outside that ceiling. A contaminated RTT would corrupt the synchronized time itself.

For the platform syscall mappings, epoch semantics, the bridge-initialization requirement, and how to synchronize your own protocol-level timeouts with the package's clock, see doc/MONOTONIC_TIME.md.

MonotonicClock is best effort. Callers that need every reading to be attributable to the native clock, or to fail, should use the strict clock instead.

Strict clock #

New in 10.0. MonotonicClock and the NtsSyncedTime it anchors are best effort: if the platform clock cannot be read, the native core can latch a process-local counter that may not count device sleep, and nothing on the reading says so. The strict path removes that fallback. A StrictClockContext names the clock it reads, and every read either returns a reading attributed to that clock or throws on that call.

Legacy versus strict #

The legacy entry points are not untouched in 10.0: the native core now runs its own deadline, session and receipt clock reads strictly for every caller, so ntsGetTime, ntsQuery and ntsWarmCookies can also fail with NtsError.clockFault. See the ## 10.0.0 entry in CHANGELOG.md.

Resolve, read and sync #

StrictClockContext.resolve() needs an initialized native bridge. It is synchronous, never cached, and fails distinctly: StrictClockUninitialized before NtsBridge.ensureInitialized(), StrictClockMockOnly on a hand-written mock bridge, StrictClockUnsupported when the build has no supported backend, a source fault, a regression or StrictClockUnknownSource when the binding read cannot be trusted, and StrictClockInvalidated with reason nativeGeneration when a process-wide invalidation races that read. now() performs the bridge-state checks and one synchronous native read; it does no I/O.

import 'package:nts/nts.dart';

Future<void> main() async {
  await NtsBridge.ensureInitialized();

  final StrictClockContext clock;
  try {
    clock = StrictClockContext.resolve();
  } on StrictClockError catch (e) {
    // Fail closed: do not substitute MonotonicClock or DateTime.now().
    print('strict clock unavailable: $e');
    return;
  }

  const spec = NtsServerSpec(host: 'time.cloudflare.com', port: 4460);
  try {
    final start = clock.now();
    print('${start.descriptor}, generation ${start.generation}');

    final synced = await ntsGetTimeStrict(spec: spec, context: clock);
    print('authenticated utc = ${synced.utcNow()}');
    print('sync age = ${synced.elapsedSinceSync()}');
    print('since start = ${clock.elapsedSince(start)}');
  } on NtsErrorClockFault catch (e) {
    print('clock could not vouch at ${e.stage.name}: ${e.fault}');
  } on NtsError catch (e) {
    print('sync failed: $e');
  } on StrictClockError catch (e) {
    // Raised by now(), utcNow(), elapsedSinceSync() and elapsedSince().
    // `clock` is now invalid; resolve a new context to continue.
    print('strict clock failed: $e');
  }
}

Network calls report a clock failure as NtsError.clockFault, whose stage names where the read served and whose fault is the underlying StrictClockError. Context methods and the StrictSyncedTime projections throw a failed clock read's StrictClockError directly. The transfer methods can also fail in other ways: exportReference throws ArgumentError for a StrictSyncedTime bound to another context, and once a provider is consulted, exportReference and bindReference propagate whatever its current() throws.

Errors and invalidation #

• A failing read invalidates. A source fault or a regression on now() or elapsedSince() throws that error and leaves the context permanently invalid.
• Lifecycle events invalidate. After NtsBridge.dispose(), a raw NtsRustLib.dispose() / init(), an explicit invalidate(), or an advance of the native generation, the next now() / elapsedSince() throws StrictClockInvalidated with the matching reason. The generation is process-wide: a native fault, or the disposal of a native bridge, on any isolate or engine in the process advances it, and every context in the process fails on its next read.
• Foreign readings are rejected without invalidating. elapsedSince() given a reading from another bridge incarnation, coordinate or generation throws StrictClockSourceIncompatible, StrictClockDescriptorIncompatible or StrictClockGenerationIncompatible without reading the clock, and the context stays valid.
• isValid is not a liveness probe. isValid and invalidationReason report only failures this context has already observed. A reset or generation advance elsewhere shows up on the next read, so call now() to learn the current state.

Recovery #

An invalid context is never repaired. Resolve a new one with StrictClockContext.resolve(), which itself fails if the clock is still unusable, and re-sync with ntsGetTimeStrict on the new context. Discard the old context's readings and StrictSyncedTime rather than carrying them over: the old StrictSyncedTime keeps throwing, and a new context rejects readings from an earlier bridge incarnation or generation.

Ownership and scope #

• A reading means nothing outside the process that took it. The generation is a per-process lifecycle token, so equal generations in two processes prove nothing. Do not persist raw micros or compare them across processes or reboots.
• ClockSourceDescriptor values can be persisted and compared with isCompatibleWith. Compatibility says two coordinates use the same source and conversion rules; it does not say two readings share a counter epoch.
• Same-boot transfer between processes (exportReference / bindReference) is unavailable as shipped. No boot-scope provider is approved, so a native context refuses with StrictClockBootScopeUnavailable and reason BootScopeUnavailableReason.providerNotApproved. Local strict reads do not depend on it.

Portability limits #

• One device, one counter. A strict reading is a position on one device's boot-time counter. Compare readings only within one boot of one device. A restored backup or a migrated install is a different counter, and nothing in the package maps between them.
• Engines own their contexts; disposal is process-wide. Every engine calls NtsBridge.ensureInitialized() and resolves its own contexts; contexts are not shared between isolates. Because the generation is process-wide, NtsBridge.dispose() on a native bridge in one engine invalidates the contexts of every engine in the process. A raw NtsRustLib.dispose() followed by initMock(api:) with the same object is not detected; use NtsBridge.dispose() when a reset must be observed.
• Raw readings cannot be upgraded. A stored micros integer, a MonotonicClock reading or an NtsSyncedTime anchor has no export provenance, and wrapping it in the public SameBootReference constructor does not give it any. That constructor exists to rebuild a reference the consumer exported and kept in storage it authenticates. exportReference accepts only a StrictSyncedTime bound to the exporting context.
• Reference time is not export time. A SameBootReference carries the instant its StrictSyncedTime was referenced to (the winning sample's wire receipt), not the instant it was exported, stored or bound, and binding maps it without conversion. A receipt at 1,234,567 µs exported at 4,000,111 µs and bound when the receiver reads 5,000,123 µs is 3,765,556 µs old, not 1,000,012 µs.
• Comparable is not trusted. Same-boot comparability, once a provider exists, says only that two readings are on one counter. It does not authenticate a stored reference, prove that it is the latest one (rollback freshness), make its UTC trustworthy after the fact, or bound drift or real-time error. Those stay with the consumer.
• iOS boot continuity is unsupported. iOS exposes no cold-restore boot identity to apps (kern.bootsessionuuid is no longer available to apps as of iOS 18). The package does not substitute boot time, uptime comparisons, stored identifiers or hashes of them, so transfer on iOS stays unavailable with no provider planned. Local strict reads are unaffected.
• Android scope is conditional. Settings.Global.BOOT_COUNT (API 24 and later) is a candidate boot-scope provider only. Its reset behaviour has not been validated and it is not approved, so Android refuses transfer like every other platform until a reviewed release approves it. Linux, macOS and Windows have no evaluated provider.

Platform evidence #

Every platform selects a suspend-inclusive source, but what has been observed differs. This table is what the strict clock evidence matrix records today; anything not listed is unverified. Floors follow the package's: Android API 24 (the plugin's minSdk), Windows 10 (QueryInterruptTimePrecise), and the Flutter SDK's deployment targets on iOS and macOS.

Only Android and iOS have recorded evidence that strict readings advance correctly across a real suspend, stay put across a wall-clock change, and behave as specified across process death, reboot and multiple engines, each on one physical device. Hermetic tests and simulators do not count as that evidence.

Security considerations #

The package handles authentication and replay protection on its own side of the wire (RFC 8915 NTS over TLS 1.3, AEAD on every NTPv4 exchange, single-use cookies, UID and origin-timestamp echo checks, strict TrustMode.platformOnly available for callers who want the platform CA store with no static-bundle downgrade). What it does not do — and structurally cannot do, because the whole point of the API is "take a caller-supplied host and connect to it" — is constrain which hosts a caller is allowed to reach.

If your app accepts hostnames from untrusted input (e.g. a user- entered NTS server URL, a remotely-fetched server list, a deep-link parameter) and passes them through to ntsQuery / ntsWarmCookies / NtsClient, treat those call sites as a server-side-request- forgery (SSRF) surface and apply the validation your threat model requires before dispatching into this library. Reasonable controls include:

• Allowlist — pin the set of acceptable hosts at the application layer (e.g. against a curated catalog like the one the Flutter showcase ships). Most consumer-facing apps that need authenticated time can ship with a fixed allowlist and never resolve attacker-controlled hostnames at all.
• Reject private-range resolution — if you do accept arbitrary hostnames, resolve them yourself first, refuse the call if the resolved address falls in an RFC 1918 / RFC 4193 / loopback / link-local range, and only then pass the (resolved, validated) hostname through. This is a textbook SSRF mitigation; this library cannot apply it on your behalf because legitimate on-premise deployments routinely point at RFC 1918 hostnames (a stratum-1 GPS receiver on a corporate VLAN) and the library has no way to tell those apart from a callsite that's being exploited.
• Constrain the port — the wrapper rejects ports outside 1..65535 as NtsError.invalidSpec, but every value inside that range is reachable. If your threat model requires it, gate the port at the application layer before the call.

The bounded DNS worker pool (kDefaultDnsConcurrencyCap = 4, see the API summary section) bounds the amplification exposure of a saturated hostname-resolution path, but does not gate destinations — that gate is the caller's responsibility.

Trust-anchor selection #

The default TrustMode.platformWithFallback consults the platform trust store, which is the right choice for the broadest connectivity: it honours corporate CAs, MDM-installed roots, and user-added certificates, so the client works out of the box on managed devices and private networks.

The security trade-off is that platform-managed stores on corporate or MDM-managed devices often include an inspection CA installed by policy. An appliance holding a certificate signed by that CA can complete a man-in-the-middle NTS-KE handshake and derive the same AEAD keying material the client derives. Because NTS authenticates time responses using those keys, a middlebox with a platform-trusted cert can forge NTPv4 replies that the client accepts as authentic.

If your threat model requires end-to-end integrity against TLS inspection, construct the client explicitly with TrustMode.bundledOnly:

import 'package:nts/nts.dart';

Future<void> main() async {
  await NtsBridge.ensureInitialized(); // before using NtsClient
  final client = NtsClient(trustMode: TrustMode.bundledOnly);
  final sample = await client.query(
    spec: const NtsServerSpec(host: 'time.cloudflare.com', port: 4460),
    bridgeConcurrencyCap: 4, // built-in default, shown for visibility
  );
}

bundledOnly limits trust anchors to the library's static webpki-roots bundle. An inspection appliance cannot present a certificate this client will accept, because the bundle contains only public CAs and no CA injected via MDM or policy. The trade-off is that bundledOnly will reject certificates from private or enterprise CAs, so it is unsuitable for NTS servers that present private-CA-issued certificates. For those deployments, use TrustMode.custom with the relevant root bundle supplied via customRoots. See the TrustMode API documentation and ARCHITECTURE.md for the full decision matrix.

Reaching multiple trust domains #

A single client applies one trust policy to every host it queries — the TrustMode is fixed at construction and immutable per client. You cannot route different per-host trust policies through one client. A TrustMode.custom client built around a private CA accepts only certificates that chain to that CA, so it rejects time.cloudflare.com; a bundledOnly client trusts only the public webpki-roots bundle, so it rejects a server presenting a private-CA certificate. (A platform-mode client is the awkward middle case: whether it accepts a private-CA server depends on whether that CA is installed in the OS trust store, so it does not give a clean, predictable boundary either way.)

When an app must enforce distinct boundaries for distinct hosts — say an internal NTS server behind a private CA and public servers — mint one client per trust domain and route each query to the matching client:

import 'dart:io';
import 'package:nts/nts.dart';

Future<void> main() async {
  await NtsBridge.ensureInitialized(); // before using NtsClient

  // Trusts only the private CA, so it authenticates only the
  // internal server; public hosts are rejected.
  final privateRoots = File('/etc/nts/internal-ca.pem').readAsBytesSync();
  final internalClient = NtsClient(
    trustMode: TrustMode.custom,
    customRoots: privateRoots,
  );

  // Trusts only the public webpki-roots bundle, so an MDM-injected
  // root or the private CA above cannot authenticate these hosts.
  final publicClient = NtsClient(trustMode: TrustMode.bundledOnly);

  // Both clients share one isolate-wide bridge admission gate, so the
  // explicit `bridgeConcurrencyCap` (the built-in default of 4) bounds
  // their combined worker occupancy, not each client's separately.
  final internal = await internalClient.query(
    spec: const NtsServerSpec(host: 'ntp.internal.example', port: 4460),
    bridgeConcurrencyCap: 4,
  );
  final external = await publicClient.query(
    spec: const NtsServerSpec(host: 'time.cloudflare.com', port: 4460),
    bridgeConcurrencyCap: 4,
  );
}

Per-client scoping is the security point, not just an ergonomic convenience: it keeps the private CA trusted only for the internal server. Merging both anchor sets into one client would let the private CA authenticate a public hostname (and vice-versa), widening every server's trusted-issuer set to the union — the exact exposure the per-client boundary exists to prevent. Each client also owns its own session table, so cookies and AEAD keys never cross the domain boundary.

Non-Flutter Dart callers must pass externalLibrary explicitly #

The automatic library resolution described under Prerequisites is a Flutter-specific feature: the Native Assets build hook only runs inside flutter run / flutter build, where it compiles the Rust crate and hands bridge initialization a controlled absolute path to the resulting dynamic library.

Pure Dart environments — a dart run CLI such as the bundled example/bin/nts_cli.dart, a server-side script, an integration-test harness — never trigger that hook. Nothing compiles the crate for you (build it with cargo build --release in rust/), and nothing supplies a load path: without one, the FRB-generated default loader falls back to resolving the relative directory rust/target/release/ against the current working directory.

That fallback is a security problem, not just a convenience gap. Initializing with no externalLibrary: argument from a working directory an attacker can influence is a library-hijack surface: a malicious rust/target/release/libnts_rust.dylib (or .so / .dll) dropped there yields arbitrary code execution under the calling process's privileges — before any of this package's TLS / NTS code is even reached.

Outside Flutter, therefore, always resolve an absolute path to the compiled library (.so on Linux, .dylib on macOS, .dll on Windows) from a trusted source — a packaged install location, an environment variable owned by the deploying operator, a command-line argument — and pass it through the externalLibrary parameter:

import 'package:nts/nts.dart';
import 'package:flutter_rust_bridge/flutter_rust_bridge_for_generated.dart'
    show ExternalLibrary;

await NtsBridge.ensureInitialized(
  externalLibrary: ExternalLibrary.open('/absolute/path/to/libnts_rust.dylib'),
);

Flutter callers can keep using the bare await NtsBridge.ensureInitialized() form: the Native Assets pipeline supplies the load path before the relative fallback can fire.

Note that externalLibrary configures the first initialization only. A later ensureInitialized() call passing a different library ignores it, because the bridge is already initialized — so the call site that owns the trusted path must be the one that runs first. A disposal — NtsBridge.dispose(), or the raw NtsRustLib.dispose() — does clear that state, and a call after it is a fresh first initialization, but disposal is a teardown rather than a reconfiguration hook: it invalidates everything the disposed bridge was serving.

Ignored is not the same as harmless. ExternalLibrary.open maps the library synchronously, in its own constructor, so writing

import 'package:nts/nts.dart';
import 'package:flutter_rust_bridge/flutter_rust_bridge_for_generated.dart'
    show ExternalLibrary;

final String untrustedPath = '/some/path/libnts_rust.dylib';

await NtsBridge.ensureInitialized(
  externalLibrary: ExternalLibrary.open(untrustedPath),
);

executes that library's load-time initializers even when the call turns out to be a no-op — the argument is evaluated before ensureInitialized runs at all. The hijack surface described above is therefore closed by controlling where the path comes from, not by relying on a later call being ignored: nominate one call site as the initialization owner, and construct an ExternalLibrary only there.

NtsBridge.state is not a substitute for that. It rules out a completed initialization, not an in-flight one — an attempt that is still awaiting its library load has not installed entrypoint state yet, so state reads uninitialized for the whole of that window and a second call site guarding on it maps its library anyway.

API summary #

ntsGetTime, ntsQuery, and ntsWarmCookies ship as a hand-written wrapper around the bundled FFI surface; consumers can omit timeout, dnsConcurrencyCap, bridgeConcurrencyCap, and verificationTime to inherit the package defaults, and future internal-only Rust signature changes do not propagate as breaking call-site edits. See ARCHITECTURE.md's "Public API stability layer" section for the contract.

Three tuning parameters deserve a short orientation here; the full mechanics live in ARCHITECTURE.md ("Timeout budget and bounded DNS", "Bridge admission gate") and in each constant's dartdoc.

• timeout is a single wall-clock budget anchored at the start of the call: DNS, TCP connect, TLS handshake, KE record I/O, and the UDP exchange all draw from one shrinking deadline, so no phase can stretch the total cost past the caller's budget. Exhaustion at any phase surfaces as NtsError.timeout carrying the TimeoutPhase that ran out; use a switch expression on NtsError for exhaustive failure handling. The FFI boundary is millisecond-resolution: a sub-millisecond timeout component is rounded up to the next whole millisecond, and sub-millisecond verificationTime precision is truncated to whole milliseconds since the epoch — microseconds do not round-trip through either parameter.
• dnsConcurrencyCap (default 4) bounds in-flight getaddrinfo worker threads process-wide. getaddrinfo is non-cancellable, so a stalled lookup is detached rather than killed; the cap bounds thread-stack accumulation when a resolver blackholes traffic. Values must lie in 1..4294967295 (0 is rejected as NtsError.invalidSpec); saturation surfaces as NtsError.timeout.
• bridgeConcurrencyCap (default 4) bounds how many of this package's calls occupy flutter_rust_bridge worker threads at once. Excess calls queue on the Dart side holding no worker; queue wait is charged against timeout, and a budget that expires while queued fails with TimeoutPhase.bridgeSaturation without ever dispatching. Same validation range as the DNS cap; the gate is isolate-local, while the DNS counter is process-wide.

The two caps compose rather than conflict: with the bridge cap at or below the DNS cap (the defaults are both 4), live calls alone can never saturate the DNS pool. For high distinct-host fan-out, raise both caps together; ARCHITECTURE.md covers the mixed-cap admission semantics and the skewed-cap trade-offs.

Running the examples #

Everything above covers integrating nts as a library dependency in your own app. The repository additionally ships runnable reference surfaces under example/, in increasing order of complexity:

• example/main.dart — the minimal single-file usage snippet: one authenticated NTPv4 query plus an exhaustive NtsError switch. Start here.

• Flutter GUI (example/lib/) — visual showcase with a server catalog, favourites, region filtering, and a unified live log:

  cd example
  flutter run -d macos -t lib/main.dart
  

  The GUI drives the real Rust bridge by default and falls back to an in-memory mock (with an explanatory banner) if the dylib cannot be loaded; pass --dart-define=NTS_BRIDGE=mock to opt into the mock explicitly. See the GUI User Manual for navigation, the NTS Query / Warm Cookies / Get Time actions, the legacy / strict / compare clock modes, and how to read the status banners.

• Dart CLI (example/bin/nts_cli.dart) — scriptable companion for batched probing, cron jobs, and CI smoke checks. See the CLI User Manual for the positional host arguments and the --port / --timeout / --warm / --mock / --json / --exit-on-error flags.

All surfaces share the same Rust-backed bridge and the same formatting helpers; see the example README for the internal wiring.

Version compatibility #

nts depends on flutter_rust_bridge with an exact pin rather than a caret range. The Dart code generated into lib/src/ffi/ and the Rust runtime crate linked into libnts_rust share a wire format that upstream does not guarantee to be stable across minor versions. A mismatched pair does not fail to compile or throw — it misreads each other's memory layout, so the failure mode is silent memory corruption. The pin makes the mismatch a resolution error instead.

The consequence is that your app's flutter_rust_bridge constraint must admit exactly the version nts pins:

If your app does not depend on flutter_rust_bridge directly there is nothing to do — pub resolves the transitive pin for you. If it does, and resolution fails, match the constraint to the row above rather than adding a dependency_overrides entry: an override silences the resolver but reintroduces the corruption the pin exists to prevent.

Technical reference #

For internals, contribution workflow, and operational tuning:

• CONTRIBUTING.md — prerequisites, the branch and pull request loop, the quality gates a change must clear, and the code conventions this repository enforces.
• ARCHITECTURE.md — Dart ↔ FRB ↔ Rust layering, module-by-module breakdown of the Rust crate, and the repository layout.
• DEVELOPMENT.md — Rust toolchain, regenerating FRB bindings via check_bindings.dart (which also serves as the drift gate), running Rust / Dart tests, and the verbose_logs Native Assets user-define for enabling rustls trace output.
• RFC 8915 — Official IETF specification for Network Time Security.

Contact #

Maintainer: Nicholas Llewellyn — nllewelln@gmail.com. For bugs and feature requests, prefer GitHub issues; for private security reports, see SECURITY.md.

License #

MIT. See LICENSE.