@magmacomputing/tempo-plugin-ntp

A lightweight, zero-dependency Tempo plugin that provides client-server network time synchronization and monotonic clock drift compensation using Cristian's algorithm and HTTP Server-Timing / Date headers.

⚡ Why Use the NTP Plugin?

Client device clocks are notoriously inaccurate—frequently skewed by seconds or minutes due to dead CMOS batteries, manual time changes, or battery-saver throttles.

• Auctions, Ticketing & Flash Sales: Countdown timers evaluate against true server time so bids close accurately.
• Fintech & 2FA / TOTP: Prevents authentication and trade-slippage failures caused by skewed device clocks.
• Offline-First & CRDTs: Eliminates Last-Write-Wins (LWW) document overwrite bugs.
• Anti-Tampering: Detects local clock tampering on timed forms and quizzes.

📦 Installation

npm install @magmacomputing/tempo-plugin-ntp

🚀 Quick Start

import { Tempo } from '@magmacomputing/tempo';
import { NtpPlugin } from '@magmacomputing/tempo-plugin-ntp';

// 1. Install the plugin with optional target server
Tempo.use(NtpPlugin, {
  server: '/api/time',          // Default time sync endpoint
  syncInterval: '15m',          // Automatic periodic re-sync
  interceptFetch: true          // Passively calibrate on existing fetch API calls
});

// 2. Query true calibrated atomic time (100% synchronous!)
const now = Tempo.ntp.now();
console.log(`True UTC Time: ${now.format('{yyyy}-{mm}-{dd} {hh}:{mi}:{ss}.{ms}')}`);

// 3. Inspect telemetry and drift
console.log(`Clock Offset: ${Tempo.ntp.offset}ms`);
console.log(`Uncertainty: ±${Tempo.ntp.drift.uncertaintyMs}ms`);

// 4. Manually trigger an immediate synchronization
await Tempo.ntp.sync('/api/time');

⚡ Try this live in the interactive Tempo Sandbox ↗

📖 Features

1. Tempo.ntp.now(timeZone?)

Returns a Tempo instance anchored to the calibrated server time. This method is 100% synchronous and non-blocking—it instantly applies the cached offset without initiating network calls during render.

2. Tempo.ntp.sync(endpoint?)

Asynchronously triggers an active HTTP HEAD ping to calculate Round-Trip Time (RTT) and update the Exponential Moving Average (EMA) drift offset using Cristian's algorithm.

3. Tempo.ntp.drift & Tempo.ntp.offset

• Tempo.ntp.offset: Fast integer getter returning the current clock drift offset in milliseconds (serverTime = localTime + offset).
• Tempo.ntp.drift: Telemetry snapshot returning { offsetMs, uncertaintyMs, lastSyncedAt, sampleCount }.

4. Tempo.ntp.reset()

Resets the calibration state back to zero.

5. tempo.toNtpTime()

Converts any existing Tempo instance to its calibrated NTP-adjusted equivalent.

📄 Licensing

This is a Community plugin. It is completely free and open-source for personal and commercial use. No license token is required.

📖 Read the Official NTP Plugin Documentation