settld 0.2.4 → 0.2.6

package/services/magic-link/src/decision-otp.js

@@ -0,0 +1,187 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { sendSmtpMail } from "./smtp.js";
+import { sendResendMail } from "./email-resend.js";
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function sha256Hex(text) {
+  return crypto.createHash("sha256").update(String(text ?? ""), "utf8").digest("hex");
+}
+
+function clampText(v, { max }) {
+  const s = String(v ?? "").trim();
+  if (!s) return null;
+  return s.length <= max ? s : s.slice(0, Math.max(0, max - 1)) + "…";
+}
+
+function normalizeEmail(value) {
+  const raw = clampText(value, { max: 320 });
+  if (!raw) return null;
+  const email = raw.toLowerCase();
+  if (!email.includes("@")) return null;
+  const [local, domain, ...rest] = email.split("@");
+  if (!local || !domain || rest.length) return null;
+  if (/\s/.test(email)) return null;
+  return email;
+}
+
+function otpRecordPath({ dataDir, token, email }) {
+  const key = sha256Hex(`${token}\n${email}`);
+  return path.join(dataDir, "decision-otp", token, `${key}.json`);
+}
+
+function otpOutboxPath({ dataDir, token, email }) {
+  const key = sha256Hex(`${token}\n${email}`);
+  return path.join(dataDir, "decision-otp-outbox", `${token}_${key}.json`);
+}
+
+function issueCode6() {
+  const n = crypto.randomInt(0, 1_000_000);
+  return String(n).padStart(6, "0");
+}
+
+function errorMessageOrFallback(err, fallback = "smtp failed") {
+  const direct = typeof err?.message === "string" ? err.message.trim() : "";
+  if (direct) return direct;
+  const asText = String(err ?? "").trim();
+  if (asText && asText !== "[object Object]") return asText;
+  return fallback;
+}
+
+export async function issueDecisionOtp({ dataDir, token, email, ttlSeconds, deliveryMode, smtp, resend } = {}) {
+  const emailNorm = normalizeEmail(email);
+  if (!emailNorm) return { ok: false, error: "INVALID_EMAIL", message: "invalid email" };
+
+  const ttl = Number.parseInt(String(ttlSeconds ?? ""), 10);
+  if (!Number.isInteger(ttl) || ttl <= 0) throw new TypeError("ttlSeconds must be a positive integer");
+
+  const code = issueCode6();
+  const createdAt = nowIso();
+  const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
+  const codeSha256 = sha256Hex(`${token}\n${emailNorm}\n${code}`);
+
+  const record = {
+    schemaVersion: "DecisionOtpRecord.v1",
+    token,
+    email: emailNorm,
+    codeSha256,
+    createdAt,
+    expiresAt,
+    consumedAt: null,
+    attempts: 0
+  };
+
+  const fp = otpRecordPath({ dataDir, token, email: emailNorm });
+  await fs.mkdir(path.dirname(fp), { recursive: true });
+  await fs.writeFile(fp, JSON.stringify(record, null, 2) + "\n", "utf8");
+
+  const mode = String(deliveryMode ?? "record").trim().toLowerCase();
+  if (mode === "record") {
+    const outFp = otpOutboxPath({ dataDir, token, email: emailNorm });
+    await fs.mkdir(path.dirname(outFp), { recursive: true });
+    await fs.writeFile(
+      outFp,
+      JSON.stringify(
+        { schemaVersion: "DecisionOtpOutboxRecord.v1", token, email: emailNorm, code, createdAt, expiresAt },
+        null,
+        2
+      ) + "\n",
+      "utf8"
+    );
+  } else if (mode === "log") {
+    // eslint-disable-next-line no-console
+    console.log(`decision otp token=${token} email=${emailNorm} code=${code} expiresAt=${expiresAt}`);
+  } else if (mode === "smtp") {
+    const from = typeof smtp?.from === "string" ? smtp.from.trim() : "";
+    if (!from) return { ok: false, error: "SMTP_NOT_CONFIGURED", message: "smtp.from is required" };
+    try {
+      await sendSmtpMail({
+        host: smtp?.host,
+        port: smtp?.port,
+        secure: Boolean(smtp?.secure),
+        starttls: smtp?.starttls === undefined ? true : Boolean(smtp?.starttls),
+        auth: smtp?.user && smtp?.pass ? { user: smtp.user, pass: smtp.pass } : null,
+        from,
+        to: emailNorm,
+        subject: "Your Settld decision code",
+        text: `Your decision code is: ${code}\n\nThis code expires at: ${expiresAt}\n\nIf you did not request this code, you can ignore this email.\n`
+      });
+    } catch (err) {
+      return { ok: false, error: "SMTP_SEND_FAILED", message: errorMessageOrFallback(err, "smtp send failed") };
+    }
+  } else if (mode === "resend") {
+    const from = typeof resend?.from === "string" ? resend.from.trim() : "";
+    const apiKey = typeof resend?.apiKey === "string" ? resend.apiKey.trim() : "";
+    if (!from || !apiKey) {
+      return {
+        ok: false,
+        error: "RESEND_NOT_CONFIGURED",
+        message: "resend.from and resend.apiKey are required"
+      };
+    }
+    try {
+      await sendResendMail({
+        apiKey,
+        from,
+        to: emailNorm,
+        subject: "Your Settld decision code",
+        text: `Your decision code is: ${code}\n\nThis code expires at: ${expiresAt}\n\nIf you did not request this code, you can ignore this email.\n`,
+        baseUrl: resend?.baseUrl
+      });
+    } catch (err) {
+      return { ok: false, error: "RESEND_SEND_FAILED", message: errorMessageOrFallback(err, "resend send failed") };
+    }
+  } else {
+    throw new Error("invalid deliveryMode");
+  }
+
+  return { ok: true, email: emailNorm, expiresAt };
+}
+
+export async function verifyAndConsumeDecisionOtp({ dataDir, token, email, code, maxAttempts }) {
+  const emailNorm = normalizeEmail(email);
+  const codeNorm = clampText(code, { max: 32 });
+  if (!emailNorm || !codeNorm) return { ok: false, error: "OTP_INVALID", message: "email and code are required" };
+
+  const max = Number.parseInt(String(maxAttempts ?? ""), 10);
+  if (!Number.isInteger(max) || max < 1) throw new TypeError("maxAttempts must be an integer >= 1");
+
+  const fp = otpRecordPath({ dataDir, token, email: emailNorm });
+  let rec = null;
+  try {
+    rec = JSON.parse(await fs.readFile(fp, "utf8"));
+  } catch {
+    rec = null;
+  }
+  if (!rec || typeof rec !== "object" || Array.isArray(rec) || rec.schemaVersion !== "DecisionOtpRecord.v1") {
+    return { ok: false, error: "OTP_MISSING", message: "no active otp" };
+  }
+  if (String(rec.token ?? "") !== token || String(rec.email ?? "") !== emailNorm) {
+    return { ok: false, error: "OTP_MISSING", message: "no active otp" };
+  }
+  if (typeof rec.consumedAt === "string" && rec.consumedAt) return { ok: false, error: "OTP_CONSUMED", message: "otp already used" };
+
+  const expiresMs = Date.parse(String(rec.expiresAt ?? ""));
+  if (!Number.isFinite(expiresMs) || Date.now() > expiresMs) return { ok: false, error: "OTP_EXPIRED", message: "otp expired" };
+
+  const attempts = Number.parseInt(String(rec.attempts ?? "0"), 10);
+  if (Number.isInteger(attempts) && attempts >= max) return { ok: false, error: "OTP_LOCKED", message: "too many attempts" };
+
+  const expected = String(rec.codeSha256 ?? "");
+  const actual = sha256Hex(`${token}\n${emailNorm}\n${codeNorm}`);
+  if (expected !== actual) {
+    rec.attempts = (Number.isInteger(attempts) ? attempts : 0) + 1;
+    await fs.writeFile(fp, JSON.stringify(rec, null, 2) + "\n", "utf8");
+    return { ok: false, error: "OTP_INVALID", message: "invalid code" };
+  }
+
+  rec.consumedAt = nowIso();
+  rec.attempts = Number.isInteger(attempts) ? attempts : 0;
+  await fs.writeFile(fp, JSON.stringify(rec, null, 2) + "\n", "utf8");
+  return { ok: true };
+}

package/services/magic-link/src/decisions.js

@@ -0,0 +1,92 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function isPlainObject(v) {
+  return Boolean(v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+}
+
+function decisionPath({ dataDir, token }) {
+  return path.join(dataDir, "decisions", `${token}.json`);
+}
+
+export async function loadDecisionRecord({ dataDir, token }) {
+  try {
+    const raw = await fs.readFile(decisionPath({ dataDir, token }), "utf8");
+    const j = JSON.parse(raw);
+    if (!isPlainObject(j) || j.schemaVersion !== "DecisionRecord.v0") return null;
+    return j;
+  } catch {
+    return null;
+  }
+}
+
+function clampText(v, { max }) {
+  const s = String(v ?? "").trim();
+  if (!s) return null;
+  return s.length <= max ? s : s.slice(0, Math.max(0, max - 1)) + "…";
+}
+
+function normalizeDecision(v) {
+  const s = String(v ?? "").trim().toLowerCase();
+  if (s === "approve" || s === "hold") return s;
+  return null;
+}
+
+export async function appendDecision({
+  dataDir,
+  token,
+  tenantId,
+  zipSha256,
+  verifyJsonSha256,
+  decision,
+  actorName,
+  actorEmail,
+  authMethod,
+  actorIp,
+  actorUserAgent,
+  note
+}) {
+  const d = normalizeDecision(decision);
+  if (!d) return { ok: false, error: "INVALID_DECISION", message: "decision must be approve|hold" };
+  const name = clampText(actorName, { max: 200 });
+  const email = clampText(actorEmail, { max: 320 });
+  if (!email) return { ok: false, error: "INVALID_ACTOR", message: "email is required" };
+  const auth = clampText(authMethod, { max: 32 }) ?? "none";
+  const ip = clampText(actorIp, { max: 128 });
+  const userAgent = clampText(actorUserAgent, { max: 400 });
+  const noteValue = clampText(note, { max: 2000 });
+
+  const fp = decisionPath({ dataDir, token });
+  await fs.mkdir(path.dirname(fp), { recursive: true });
+
+  let record = null;
+  try {
+    record = JSON.parse(await fs.readFile(fp, "utf8"));
+  } catch {
+    record = null;
+  }
+
+  const decidedAt = new Date().toISOString();
+  const entry = {
+    decision: d,
+    decidedAt,
+    actor: { name, email },
+    auth: { method: auth },
+    client: { ip, userAgent },
+    note: noteValue
+  };
+
+  const next = isPlainObject(record) && record.schemaVersion === "DecisionRecord.v0"
+    ? { ...record }
+    : { schemaVersion: "DecisionRecord.v0", token, tenantId, zipSha256, verifyJsonSha256, decisions: [] };
+
+  next.tenantId = tenantId;
+  next.zipSha256 = zipSha256;
+  next.verifyJsonSha256 = verifyJsonSha256;
+  next.decisions = Array.isArray(next.decisions) ? next.decisions : [];
+  next.decisions.push(entry);
+  next.updatedAt = decidedAt;
+
+  await fs.writeFile(fp, JSON.stringify(next, null, 2) + "\n", "utf8");
+  return { ok: true, record: next };
+}

package/services/magic-link/src/email-resend.js

@@ -0,0 +1,89 @@
+function normalizeBaseUrl(raw) {
+  const text = String(raw ?? "").trim();
+  if (!text) return null;
+  try {
+    const parsed = new URL(text);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    return parsed.toString().replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+
+function errorMessageOrFallback(err, fallback = "resend request failed") {
+  const direct = typeof err?.message === "string" ? err.message.trim() : "";
+  if (direct) return direct;
+  const asText = String(err ?? "").trim();
+  if (asText && asText !== "[object Object]") return asText;
+  return fallback;
+}
+
+export async function sendResendMail({
+  apiKey,
+  from,
+  to,
+  subject,
+  text,
+  baseUrl = "https://api.resend.com",
+  timeoutMs = 10_000,
+  fetchImpl = fetch
+} = {}) {
+  const key = String(apiKey ?? "").trim();
+  if (!key) throw new Error("resend api key required");
+  const sender = String(from ?? "").trim();
+  if (!sender) throw new Error("resend from is required");
+  const recipient = String(to ?? "").trim();
+  if (!recipient) throw new Error("resend to is required");
+  const sub = String(subject ?? "").trim();
+  if (!sub) throw new Error("resend subject is required");
+  const bodyText = String(text ?? "");
+  const urlBase = normalizeBaseUrl(baseUrl);
+  if (!urlBase) throw new Error("resend base URL must be a valid http(s) URL");
+  if (typeof fetchImpl !== "function") throw new Error("resend fetch implementation unavailable");
+
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), Math.max(100, Number(timeoutMs) || 10_000));
+  t.unref?.();
+
+  let res;
+  try {
+    res = await fetchImpl(`${urlBase}/emails`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${key}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        from: sender,
+        to: [recipient],
+        subject: sub,
+        text: bodyText
+      }),
+      signal: controller.signal
+    });
+  } catch (err) {
+    throw new Error(errorMessageOrFallback(err, "resend transport failed"));
+  } finally {
+    clearTimeout(t);
+  }
+
+  const raw = await res.text();
+  let json = null;
+  try {
+    json = raw ? JSON.parse(raw) : null;
+  } catch {
+    json = null;
+  }
+  if (!res.ok) {
+    const message =
+      (json && typeof json === "object" && (json?.message || json?.error?.message || json?.error)) ||
+      raw ||
+      `HTTP ${res.status}`;
+    throw new Error(`resend send failed (${res.status}): ${String(message)}`);
+  }
+  return {
+    ok: true,
+    id: json && typeof json === "object" && typeof json.id === "string" ? json.id : null
+  };
+}
+

package/services/magic-link/src/ingest-keys.js

@@ -0,0 +1,137 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function isPlainObject(v) {
+  return Boolean(v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+}
+
+function assertId(value, { name }) {
+  const v = String(value ?? "").trim();
+  if (!v) throw new TypeError(`${name} is required`);
+  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(v)) throw new TypeError(`${name} invalid (allowed: [A-Za-z0-9_-]{1,64})`);
+  return v;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function sha256Hex(s) {
+  return crypto.createHash("sha256").update(String(s ?? ""), "utf8").digest("hex");
+}
+
+function ingestKeyPath({ dataDir, tenantId, keyHash }) {
+  return path.join(dataDir, "ingest-keys", tenantId, `${keyHash}.json`);
+}
+
+export function generateIngestKey() {
+  return "igk_" + crypto.randomBytes(32).toString("hex");
+}
+
+export async function createIngestKey({ dataDir, tenantId, vendorId, vendorName = null, expiresAt = null } = {}) {
+  const t = assertId(tenantId, { name: "tenantId" });
+  const v = assertId(vendorId, { name: "vendorId" });
+  const name = vendorName === null || vendorName === undefined ? null : String(vendorName).trim() || null;
+
+  let exp = null;
+  if (expiresAt !== null && expiresAt !== undefined) {
+    const raw = String(expiresAt ?? "").trim();
+    if (!raw) exp = null;
+    else {
+      const ms = Date.parse(raw);
+      if (!Number.isFinite(ms)) throw new TypeError("expiresAt must be an ISO date string or null");
+      exp = new Date(ms).toISOString();
+    }
+  }
+
+  await fs.mkdir(path.join(dataDir, "ingest-keys", t), { recursive: true });
+
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const ingestKey = generateIngestKey();
+    const keyHash = sha256Hex(ingestKey);
+    const fp = ingestKeyPath({ dataDir, tenantId: t, keyHash });
+    try {
+      await fs.writeFile(
+        fp,
+        JSON.stringify(
+          {
+            schemaVersion: "MagicLinkIngestKey.v1",
+            tenantId: t,
+            vendorId: v,
+            vendorName: name,
+            keyHash,
+            createdAt: nowIso(),
+            expiresAt: exp,
+            revokedAt: null,
+            revokedReason: null,
+            permissions: ["upload_only"]
+          },
+          null,
+          2
+        ) + "\n",
+        { encoding: "utf8", flag: "wx" }
+      );
+      return { ok: true, ingestKey, keyHash };
+    } catch (err) {
+      if (err?.code === "EEXIST") continue;
+      throw err;
+    }
+  }
+  return { ok: false, error: "KEYGEN_FAILED", message: "failed to generate unique ingest key" };
+}
+
+export async function loadIngestKeyRecordByHash({ dataDir, tenantId, keyHash } = {}) {
+  const t = assertId(tenantId, { name: "tenantId" });
+  const h = String(keyHash ?? "").trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(h)) return null;
+  const fp = ingestKeyPath({ dataDir, tenantId: t, keyHash: h });
+  try {
+    const raw = await fs.readFile(fp, "utf8");
+    const j = JSON.parse(raw);
+    if (!isPlainObject(j) || j.schemaVersion !== "MagicLinkIngestKey.v1") return null;
+    if (j.tenantId !== t) return null;
+    if (typeof j.vendorId !== "string" || !j.vendorId.trim()) return null;
+    if (j.keyHash !== h) return null;
+    return j;
+  } catch {
+    return null;
+  }
+}
+
+export async function authenticateIngestKey({ dataDir, tenantId, ingestKey } = {}) {
+  const key = typeof ingestKey === "string" ? ingestKey.trim() : "";
+  if (!key) return { ok: false, error: "MISSING" };
+  if (!key.startsWith("igk_")) return { ok: false, error: "INVALID" };
+  const keyHash = sha256Hex(key);
+  const rec = await loadIngestKeyRecordByHash({ dataDir, tenantId, keyHash });
+  if (!rec) return { ok: false, error: "NOT_FOUND" };
+  if (rec.revokedAt) return { ok: false, error: "REVOKED" };
+  if (rec.expiresAt) {
+    const ms = Date.parse(String(rec.expiresAt));
+    if (Number.isFinite(ms) && Date.now() > ms) return { ok: false, error: "EXPIRED" };
+  }
+  return { ok: true, record: rec };
+}
+
+export async function revokeIngestKey({ dataDir, tenantId, keyHash, reason = null } = {}) {
+  const t = assertId(tenantId, { name: "tenantId" });
+  const h = String(keyHash ?? "").trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(h)) return { ok: false, error: "INVALID_KEY_HASH" };
+  const fp = ingestKeyPath({ dataDir, tenantId: t, keyHash: h });
+
+  let rec = null;
+  try {
+    rec = JSON.parse(await fs.readFile(fp, "utf8"));
+  } catch {
+    return { ok: false, error: "NOT_FOUND" };
+  }
+  if (!isPlainObject(rec) || rec.schemaVersion !== "MagicLinkIngestKey.v1") return { ok: false, error: "NOT_FOUND" };
+  if (rec.revokedAt) return { ok: true, alreadyRevoked: true, revokedAt: rec.revokedAt };
+
+  rec.revokedAt = nowIso();
+  rec.revokedReason = typeof reason === "string" && reason.trim() ? reason.trim() : null;
+  await fs.writeFile(fp, JSON.stringify(rec, null, 2) + "\n", "utf8");
+  return { ok: true, revokedAt: rec.revokedAt };
+}
+

package/services/magic-link/src/maintenance.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+import { checkAndMigrateDataDir } from "./storage-format.js";
+import { loadTenantSettings } from "./tenant-settings.js";
+import { garbageCollectTenantByRetention, listTenantIdsWithIndex } from "./retention-gc.js";
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+const dataDirRaw = process.env.MAGIC_LINK_DATA_DIR ? String(process.env.MAGIC_LINK_DATA_DIR).trim() : "";
+const dataDir = dataDirRaw ? path.resolve(dataDirRaw) : path.join(os.tmpdir(), "settld-magic-link");
+const dataDirLikelyEphemeral =
+  dataDir === "/tmp" ||
+  dataDir.startsWith("/tmp/") ||
+  dataDir === os.tmpdir() ||
+  dataDir.startsWith(`${os.tmpdir()}${path.sep}`);
+const requireDurableDataDir = String(process.env.MAGIC_LINK_REQUIRE_DURABLE_DATA_DIR ?? "0").trim() === "1";
+const migrateOnStartup = String(process.env.MAGIC_LINK_MIGRATE_ON_STARTUP ?? "1").trim() !== "0";
+const intervalSeconds = Number.parseInt(String(process.env.MAGIC_LINK_MAINTENANCE_INTERVAL_SECONDS ?? "86400"), 10);
+
+if (!Number.isInteger(intervalSeconds) || intervalSeconds < 5) throw new Error("MAGIC_LINK_MAINTENANCE_INTERVAL_SECONDS must be an integer >= 5");
+if (requireDurableDataDir && dataDirLikelyEphemeral) {
+  throw new Error("MAGIC_LINK_REQUIRE_DURABLE_DATA_DIR=1 but MAGIC_LINK_DATA_DIR resolves to an ephemeral path (/tmp)");
+}
+
+await fs.mkdir(dataDir, { recursive: true });
+const fmt = await checkAndMigrateDataDir({ dataDir, migrateOnStartup });
+if (!fmt.ok) throw new Error(`magic-link data dir check failed: ${fmt.code ?? "UNKNOWN"}`);
+
+let stopped = false;
+async function shutdown(signal) {
+  if (stopped) return;
+  stopped = true;
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify({ at: nowIso(), event: "magic_link_maintenance.shutdown", signal }, null, 2));
+  process.exit(0);
+}
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+// eslint-disable-next-line no-console
+console.log(JSON.stringify({ at: nowIso(), event: "magic_link_maintenance.start", dataDir, intervalSeconds }, null, 2));
+if (dataDirLikelyEphemeral) {
+  // eslint-disable-next-line no-console
+  console.warn(
+    JSON.stringify(
+      {
+        at: nowIso(),
+        event: "magic_link_maintenance.ephemeral_data_dir_warning",
+        dataDir,
+        message: "data dir looks ephemeral; use persistent volume + MAGIC_LINK_REQUIRE_DURABLE_DATA_DIR=1 in production"
+      },
+      null,
+      2
+    )
+  );
+}
+
+while (!stopped) {
+  const loopStartMs = Date.now();
+  let tenants = [];
+  try {
+    tenants = await listTenantIdsWithIndex({ dataDir });
+  } catch {
+    tenants = [];
+  }
+
+  let deleted = 0;
+  let kept = 0;
+  for (const tenantId of tenants) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const tenantSettings = await loadTenantSettings({ dataDir, tenantId });
+      // eslint-disable-next-line no-await-in-loop
+      const res = await garbageCollectTenantByRetention({ dataDir, tenantId, tenantSettings });
+      deleted += Number(res?.deleted ?? 0);
+      kept += Number(res?.kept ?? 0);
+    } catch {
+      // ignore per-tenant failures
+    }
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify({ at: nowIso(), event: "magic_link_maintenance.retention_sweep", tenants: tenants.length, deleted, kept }, null, 2));
+
+  const elapsedMs = Date.now() - loopStartMs;
+  const sleepMs = Math.max(0, intervalSeconds * 1000 - elapsedMs);
+  // eslint-disable-next-line no-await-in-loop
+  await new Promise((r) => setTimeout(r, sleepMs));
+}