Implement mattertimesync: one-shot Matter time synchronization CLIv0.1.0

A standalone CLI Matter controller that joins Matter devices' existing
setups as a secondary administrator (multi-admin) and sets their clocks
via the standard Time Synchronization cluster. Built on matter.js 0.17.6
using the CommissioningController API. One-shot runs from a systemd
timer, no daemon: being a secondary controller is fabric membership, not
a running process, so each invocation loads the persisted keys,
discovers the device via operational DNS-SD, opens a fresh CASE session,
does its work, and exits.

- TypeScript scaffold: strict tsc, oxlint, prettier, vitest (51 tests:
  Matter epoch conversion, config validation, IANA timezone offsets and
  exact DST transition search, atomic state writes, pairing-code
  parsing, clock-delta reporting)
- Validated JSON configuration with bigint-safe values; unknown fields
  rejected loudly
- Persistent controller fabric with the same identity across restarts.
  The fabric doubles as the device registry: every node commissioned
  onto it is kept in sync, and membership changes only through
  commission and decommission, so no separate device list can drift
- On-network multi-admin commissioning from a manual or QR pairing code;
  any number of devices, one per-device pairing code each. A device
  already on the fabric rejects re-commissioning via fabric conflict
- Commands: nodes, inspect (human/JSON), status, fabrics (reads the
  Operational Credentials fabric table, marks our own entry by fabric ID
  plus root public key, flags likely-stale orphans, and removes them
  with --remove), and decommission (device drops our fabric while
  staying paired to its primary ecosystem). --node selects a device
  where relevant; optional while only one is commissioned
- sync delta reporting: reads the device utcTime before writing and
  reports device time before, time written, and the delta with
  direction, e.g. "device clock was 1m 23s behind". Handles unset clocks
  after power loss and wrong-epoch garbage in exact bigint microseconds.
  The Time Synchronization write commands themselves still await
  real-device capability inspection
- systemd oneshot service (dedicated non-root user, hardening) plus
  hourly timer with randomized delay
- Deployment as a single esbuild bundle (mattertimesync.mjs, ~4.5 MB):
  all runtime deps are pure JavaScript, so the target needs only
  Node 20+, with no npm, registry access, or build toolchain. The Bun
  sqlite driver stays external behind its runtime guard so the bundle
  runs under plain Node. npm pack remains an alternative install path

1 files changed, 120 insertions, 0 deletions

diff --git a/src/sync.ts b/src/sync.ts
new file mode 100644
index 0000000..ec3577c
--- /dev/null
+++ b/src/sync.ts
@@ -0,0 +1,120 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+/**
+ * Matter epoch conversion.
+ *
+ * Matter UTC time is microseconds since 2000-01-01T00:00:00Z (the "Matter
+ * epoch"), not the Unix epoch. All arithmetic stays in bigint; the full
+ * microsecond timestamp must never pass through a JavaScript number.
+ *
+ * The Time Synchronization write commands (SetUtcTime, SetTimeZone,
+ * SetDstOffset) are intentionally NOT implemented yet: per the project plan
+ * they are Phase 5/6 work that must be driven by the real device's inspected
+ * capabilities. Run `inspect` against the hardware first.
+ */
+
+export const MATTER_EPOCH_UNIX_SECONDS = 946_684_800n;
+
+/** Converts a Unix-epoch timestamp in milliseconds to Matter-epoch microseconds. */
+export function unixMillisToMatterMicros(unixMilliseconds: bigint): bigint {
+  return unixMilliseconds * 1_000n - MATTER_EPOCH_UNIX_SECONDS * 1_000_000n;
+}
+
+/** Converts Matter-epoch microseconds back to Unix-epoch milliseconds (truncating). */
+export function matterMicrosToUnixMillis(matterMicroseconds: bigint): bigint {
+  return (matterMicroseconds + MATTER_EPOCH_UNIX_SECONDS * 1_000_000n) / 1_000n;
+}
+
+/** Current time as Matter-epoch microseconds. */
+export function currentMatterUtcMicroseconds(now: () => number = Date.now): bigint {
+  return unixMillisToMatterMicros(BigInt(now()));
+}
+
+/** Renders Matter-epoch microseconds as an ISO-8601 UTC instant (millisecond precision). */
+export function formatMatterMicros(matterMicroseconds: bigint): string {
+  return new Date(Number(matterMicrosToUnixMillis(matterMicroseconds))).toISOString();
+}
+
+/**
+ * Comparison of the device's reported clock against the time we are about to
+ * set, for the sync report ("was X, set to Y, delta Z").
+ */
+export interface ClockComparison {
+  /** Device time before sync as ISO-8601, or null if its clock was unset. */
+  deviceTime: string | null;
+  /** The time being written, as ISO-8601. */
+  hostTime: string;
+  /** deviceTime - hostTime in microseconds; null when the device clock was unset. */
+  deltaMicroseconds: bigint | null;
+  /** Human-readable summary, e.g. "device clock was 3.2s behind". */
+  description: string;
+}
+
+/**
+ * Compares the device's utcTime attribute (null when the device lost its
+ * clock, e.g. after a power outage) against the host time being written.
+ */
+export function compareDeviceClock(deviceMicros: bigint | null, hostMicros: bigint): ClockComparison {
+  const hostTime = formatMatterMicros(hostMicros);
+  if (deviceMicros === null) {
+    return {
+      deviceTime: null,
+      hostTime,
+      deltaMicroseconds: null,
+      description: "device clock was unset",
+    };
+  }
+  const delta = deviceMicros - hostMicros;
+  const magnitude = delta < 0n ? -delta : delta;
+  const description =
+    magnitude < 1_000_000n
+      ? `device clock was within 1s of host time (${formatDurationMicros(magnitude)} ${
+          delta < 0n ? "behind" : "ahead"
+        })`
+      : `device clock was ${formatDurationMicros(magnitude)} ${delta < 0n ? "behind" : "ahead"}`;
+  return { deviceTime: formatMatterMicros(deviceMicros), hostTime, deltaMicroseconds: delta, description };
+}
+
+/** Formats a non-negative duration in microseconds as a compact human string. */
+export function formatDurationMicros(microseconds: bigint): string {
+  if (microseconds < 0n) throw new Error("duration must be non-negative");
+  if (microseconds < 1_000n) return `${microseconds}us`;
+  if (microseconds < 1_000_000n) return `${microseconds / 1_000n}ms`;
+
+  const totalSeconds = microseconds / 1_000_000n;
+  if (totalSeconds < 60n) {
+    const tenths = (microseconds % 1_000_000n) / 100_000n;
+    return tenths === 0n ? `${totalSeconds}s` : `${totalSeconds}.${tenths}s`;
+  }
+  const days = totalSeconds / 86_400n;
+  const hours = (totalSeconds % 86_400n) / 3_600n;
+  const minutes = (totalSeconds % 3_600n) / 60n;
+  const seconds = totalSeconds % 60n;
+  const parts: string[] = [];
+  if (days > 0n) parts.push(`${days}d`);
+  if (hours > 0n) parts.push(`${hours}h`);
+  if (minutes > 0n) parts.push(`${minutes}m`);
+  if (seconds > 0n && days === 0n) parts.push(`${seconds}s`);
+  return parts.join(" ");
+}
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Whether the host clock is NTP-synchronized, via systemd-timesyncd. The
+ * device must never be set from an unsynchronized clock.
+ *
+ * Returns false on hosts without timedatectl (e.g. during development on
+ * macOS) so callers fail safe; pass `assumeSynchronized` explicitly in tests.
+ */
+export async function isHostClockSynchronized(): Promise<boolean> {
+  try {
+    const { stdout } = await execFileAsync("timedatectl", ["show", "-p", "NTPSynchronized", "--value"], {
+      timeout: 5000,
+    });
+    return stdout.trim() === "yes";
+  } catch {
+    return false;
+  }
+}