settld 0.2.4 → 0.2.6

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

@@ -0,0 +1,80 @@
+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));
+}
+
+export function monthKeyUtcNow(d = new Date()) {
+  const year = d.getUTCFullYear();
+  const month = String(d.getUTCMonth() + 1).padStart(2, "0");
+  return `${year}-${month}`;
+}
+
+function usageJsonlPath({ dataDir, tenantId, monthKey }) {
+  return path.join(dataDir, "usage", tenantId, `${monthKey}.jsonl`);
+}
+
+function usageSummaryPath({ dataDir, tenantId, monthKey }) {
+  return path.join(dataDir, "usage", tenantId, `${monthKey}.summary.json`);
+}
+
+export async function appendUsageRecord({ dataDir, tenantId, monthKey, record }) {
+  const jsonl = usageJsonlPath({ dataDir, tenantId, monthKey });
+  const summaryFp = usageSummaryPath({ dataDir, tenantId, monthKey });
+  await fs.mkdir(path.dirname(jsonl), { recursive: true });
+
+  const line = JSON.stringify(record ?? {}) + "\n";
+  await fs.appendFile(jsonl, line, "utf8");
+
+  let summary = null;
+  try {
+    summary = JSON.parse(await fs.readFile(summaryFp, "utf8"));
+  } catch {
+    summary = null;
+  }
+  const cur = isPlainObject(summary) ? summary : { schemaVersion: "MagicLinkUsageSummary.v1", month: monthKey, verificationRuns: 0, uploadedBytes: 0, totalDurationMs: 0 };
+
+  cur.month = monthKey;
+  cur.verificationRuns = Number(cur.verificationRuns ?? 0) + 1;
+  cur.uploadedBytes = Number(cur.uploadedBytes ?? 0) + Number(record?.zipBytes ?? 0);
+  cur.totalDurationMs = Number(cur.totalDurationMs ?? 0) + Number(record?.durationMs ?? 0);
+  cur.lastUpdatedAt = new Date().toISOString();
+
+  await fs.writeFile(summaryFp, JSON.stringify(cur, null, 2) + "\n", "utf8");
+  return cur;
+}
+
+export async function loadUsageSummary({ dataDir, tenantId, monthKey }) {
+  const fp = usageSummaryPath({ dataDir, tenantId, monthKey });
+  try {
+    const raw = await fs.readFile(fp, "utf8");
+    const j = JSON.parse(raw);
+    if (!isPlainObject(j)) return { schemaVersion: "MagicLinkUsageSummary.v1", month: monthKey, verificationRuns: 0, uploadedBytes: 0, totalDurationMs: 0 };
+    return { schemaVersion: "MagicLinkUsageSummary.v1", month: monthKey, verificationRuns: 0, uploadedBytes: 0, totalDurationMs: 0, ...j };
+  } catch {
+    return { schemaVersion: "MagicLinkUsageSummary.v1", month: monthKey, verificationRuns: 0, uploadedBytes: 0, totalDurationMs: 0 };
+  }
+}
+
+export async function loadUsageRecords({ dataDir, tenantId, monthKey, limit = 10_000 } = {}) {
+  const jsonl = usageJsonlPath({ dataDir, tenantId, monthKey });
+  try {
+    const raw = await fs.readFile(jsonl, "utf8");
+    const lines = raw.split("\n").filter((l) => l.trim());
+    const out = [];
+    for (const line of lines.slice(-limit)) {
+      try {
+        const j = JSON.parse(line);
+        if (isPlainObject(j)) out.push(j);
+      } catch {
+        // ignore
+      }
+    }
+    out.sort((a, b) => String(a.startedAt ?? "").localeCompare(String(b.startedAt ?? "")) || String(a.token ?? "").localeCompare(String(b.token ?? "")));
+    return out;
+  } catch {
+    return [];
+  }
+}
+

package/services/magic-link/src/verify-queue.js

@@ -0,0 +1,179 @@
+import crypto from "node:crypto";
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, Number(ms) || 0)));
+}
+
+class InMemoryQueue {
+  constructor() {
+    this.items = [];
+    this.waiters = [];
+  }
+
+  size() {
+    return this.items.length;
+  }
+
+  enqueue(item) {
+    if (this.waiters.length) {
+      const waiter = this.waiters.shift();
+      waiter(item);
+      return;
+    }
+    this.items.push(item);
+  }
+
+  async dequeue() {
+    if (this.items.length) return this.items.shift();
+    return await new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+}
+
+function jobId() {
+  return `vq_${crypto.randomBytes(16).toString("hex")}`;
+}
+
+export function createVerifyQueue({
+  workerCount = 1,
+  maxAttempts = 3,
+  retryBackoffMs = 250,
+  handler,
+  onRetry = null,
+  onDeadLetter = null,
+  onDepthChange = null
+} = {}) {
+  if (typeof handler !== "function") throw new TypeError("handler is required");
+  const workers = Math.max(1, Number.parseInt(String(workerCount ?? "1"), 10) || 1);
+  const queue = new InMemoryQueue();
+  const deadLetters = [];
+  let closed = false;
+
+  function emitDepth() {
+    if (typeof onDepthChange === "function") {
+      try {
+        onDepthChange(queue.size());
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  function enqueue(entry) {
+    queue.enqueue(entry);
+    emitDepth();
+  }
+
+  function requeue(entry) {
+    const backoff = Math.max(0, Math.trunc(retryBackoffMs * Math.pow(2, Math.max(0, entry.attempt - 1))));
+    setTimeout(() => {
+      if (closed) return;
+      enqueue(entry);
+    }, backoff);
+  }
+
+  async function workerLoop() {
+    while (!closed) {
+      const entry = await queue.dequeue();
+      emitDepth();
+      if (!entry || closed) continue;
+      const startedAtMs = Date.now();
+      let out = null;
+      try {
+        out = await handler(entry.payload);
+      } catch (err) {
+        out = { ok: false, error: "VERIFY_QUEUE_HANDLER_ERROR", detail: { message: err?.message ?? String(err ?? "") } };
+      }
+
+      const ok = Boolean(out?.ok);
+      if (ok) {
+        entry.resolve({
+          ...out,
+          queued: {
+            id: entry.id,
+            attempt: entry.attempt,
+            startedAt: new Date(startedAtMs).toISOString(),
+            finishedAt: new Date().toISOString(),
+            latencyMs: Math.max(0, Date.now() - entry.enqueuedAtMs)
+          }
+        });
+        continue;
+      }
+
+      if (entry.attempt < maxAttempts) {
+        entry.attempt += 1;
+        if (typeof onRetry === "function") {
+          try {
+            onRetry({ id: entry.id, attempt: entry.attempt, error: out?.error ?? "VERIFY_FAILED" });
+          } catch {
+            // ignore
+          }
+        }
+        requeue(entry);
+        continue;
+      }
+
+      const dead = {
+        id: entry.id,
+        attempt: entry.attempt,
+        enqueuedAt: new Date(entry.enqueuedAtMs).toISOString(),
+        failedAt: new Date().toISOString(),
+        payload: entry.payload,
+        result: out
+      };
+      deadLetters.push(dead);
+      if (typeof onDeadLetter === "function") {
+        try {
+          onDeadLetter(dead);
+        } catch {
+          // ignore
+        }
+      }
+      entry.resolve({
+        ok: false,
+        error: out?.error ?? "VERIFY_QUEUE_DEAD_LETTER",
+        detail: out?.detail ?? null,
+        deadLetter: dead
+      });
+    }
+  }
+
+  for (let i = 0; i < workers; i += 1) {
+    workerLoop().catch(() => {
+      // ignore worker loop failures; per-job failures are reported through queue outputs.
+    });
+  }
+
+  return {
+    async submit(payload) {
+      if (closed) return { ok: false, error: "VERIFY_QUEUE_CLOSED" };
+      return await new Promise((resolve) => {
+        enqueue({ id: jobId(), payload, attempt: 1, enqueuedAtMs: Date.now(), resolve });
+      });
+    },
+    stats() {
+      return { queued: queue.size(), workers, deadLetters: deadLetters.length };
+    },
+    deadLetters() {
+      return [...deadLetters];
+    },
+    async drain({ timeoutMs = 30_000 } = {}) {
+      const started = Date.now();
+      while (queue.size() > 0) {
+        if (Date.now() - started > timeoutMs) return { ok: false, error: "VERIFY_QUEUE_DRAIN_TIMEOUT" };
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(10);
+      }
+      return { ok: true };
+    },
+    close() {
+      closed = true;
+      while (queue.waiters.length) {
+        const waiter = queue.waiters.shift();
+        waiter(null);
+      }
+    }
+  };
+}
+

package/services/magic-link/src/verify-worker.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+import fsSync from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { verifyClosePackBundleDir, verifyInvoiceBundleDir } from "../../../packages/artifact-verify/src/index.js";
+
+function usage() {
+  // eslint-disable-next-line no-console
+  console.error("usage: verify-worker --dir <bundleDir> [--strict|--nonstrict] [--hash-concurrency <n>]");
+  process.exit(2);
+}
+
+function readJsonSync(fp) {
+  const raw = fsSync.readFileSync(fp, "utf8");
+  return JSON.parse(raw);
+}
+
+function readJsonIfExistsSync(fp) {
+  try {
+    return readJsonSync(fp);
+  } catch {
+    return null;
+  }
+}
+
+function readBundleType(dir) {
+  const fp = path.join(dir, "settld.json");
+  try {
+    const raw = fsSync.readFileSync(fp, "utf8");
+    const j = JSON.parse(raw);
+    const t = typeof j?.type === "string" ? j.type : null;
+    return t;
+  } catch {
+    return null;
+  }
+}
+
+function parseArgs(argv) {
+  const out = { dir: null, strict: false, hashConcurrency: 16 };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--dir") {
+      out.dir = String(argv[i + 1] ?? "");
+      if (!out.dir) usage();
+      i += 1;
+      continue;
+    }
+    if (a === "--strict") {
+      out.strict = true;
+      continue;
+    }
+    if (a === "--nonstrict") {
+      out.strict = false;
+      continue;
+    }
+    if (a === "--hash-concurrency") {
+      const v = argv[i + 1] ?? null;
+      const n = Number.parseInt(String(v ?? ""), 10);
+      if (!Number.isInteger(n) || n < 1) usage();
+      out.hashConcurrency = n;
+      i += 1;
+      continue;
+    }
+    usage();
+  }
+  if (!out.dir) usage();
+  return out;
+}
+
+function deriveEvidenceTypeKeyFromIndexItem(it) {
+  if (!it || typeof it !== "object" || Array.isArray(it)) return null;
+  const kind = typeof it.kind === "string" ? it.kind.toLowerCase() : "";
+  const contentType = typeof it.contentType === "string" ? it.contentType.toLowerCase() : "";
+  const key = typeof it.key === "string" ? it.key.toLowerCase() : "";
+  const pathValue = typeof it.path === "string" ? it.path.toLowerCase() : "";
+
+  if (kind.includes("checkpoint") || key.includes("checkpoint") || pathValue.includes("checkpoint")) return "checkpoint";
+  if (kind.includes("gps") || key.includes("gps") || pathValue.includes("gps") || kind.includes("track") || key.includes("track")) return "gps";
+  if (contentType.startsWith("video/") || kind.includes("video") || key.includes("video") || pathValue.includes("video")) return "video";
+  return null;
+}
+
+function computeEvalPassFail({ overallStatus, results, failStatus = "fail" } = {}) {
+  const res = Array.isArray(results) ? results : [];
+  const failing = res.filter((r) => r && typeof r === "object" && !Array.isArray(r) && String(r.status ?? "") === failStatus).length;
+  const pass = String(overallStatus ?? "") === "ok" && failing === 0;
+  return { pass, failingCount: failing };
+}
+
+function computeClosePackSummaryV1({ dir } = {}) {
+  const evidenceIndex = readJsonIfExistsSync(path.join(dir, "evidence", "evidence_index.json"));
+  const evidenceItems = Array.isArray(evidenceIndex?.items) ? evidenceIndex.items : [];
+  const byType = { gps: 0, video: 0, checkpoint: 0 };
+  for (const it of evidenceItems) {
+    const k = deriveEvidenceTypeKeyFromIndexItem(it);
+    if (k && Object.hasOwn(byType, k)) byType[k] += 1;
+  }
+
+  const slaDef = readJsonIfExistsSync(path.join(dir, "sla", "sla_definition.json"));
+  const slaEval = readJsonIfExistsSync(path.join(dir, "sla", "sla_evaluation.json"));
+  const slaPresent = Boolean(slaDef && slaEval);
+  const slaComputed = slaPresent ? computeEvalPassFail({ overallStatus: slaEval?.overallStatus ?? null, results: slaEval?.results ?? null }) : null;
+
+  const accCrit = readJsonIfExistsSync(path.join(dir, "acceptance", "acceptance_criteria.json"));
+  const accEval = readJsonIfExistsSync(path.join(dir, "acceptance", "acceptance_evaluation.json"));
+  const accPresent = Boolean(accCrit && accEval);
+  const accComputed = accPresent ? computeEvalPassFail({ overallStatus: accEval?.overallStatus ?? null, results: accEval?.results ?? null }) : null;
+
+  return {
+    hasClosePack: true,
+    sla: {
+      present: slaPresent,
+      pass: slaPresent ? Boolean(slaComputed?.pass) : false,
+      failingClausesCount: slaPresent ? Number(slaComputed?.failingCount ?? 0) : 0
+    },
+    acceptance: {
+      present: accPresent,
+      pass: accPresent ? Boolean(accComputed?.pass) : false,
+      failingCriteriaCount: accPresent ? Number(accComputed?.failingCount ?? 0) : 0
+    },
+    evidenceIndex: {
+      present: Boolean(evidenceIndex),
+      itemCount: evidenceItems.length,
+      byType
+    }
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const bundleType = readBundleType(args.dir);
+  const result =
+    bundleType === "ClosePack.v1"
+      ? await verifyClosePackBundleDir({ dir: args.dir, strict: args.strict, hashConcurrency: args.hashConcurrency })
+      : bundleType === "InvoiceBundle.v1"
+        ? await verifyInvoiceBundleDir({ dir: args.dir, strict: args.strict, hashConcurrency: args.hashConcurrency })
+        : { ok: false, error: "unsupported bundle type", type: bundleType, warnings: [] };
+
+  if (bundleType === "ClosePack.v1" && result && typeof result === "object" && !Array.isArray(result)) {
+    // Only attach the hosted summary when verification succeeded, so the UI doesn't summarize untrusted/broken surfaces.
+    if (result.ok === true) {
+      try {
+        result.closepackSummaryV1 = computeClosePackSummaryV1({ dir: args.dir });
+      } catch {
+        // ignore
+      }
+    }
+  }
+  // Use sync FD writes so callers reading from pipes don't race on "exit" vs "stdout data" delivery.
+  fsSync.writeFileSync(1, JSON.stringify(result));
+}
+
+main().catch((err) => {
+  process.stderr.write(String(err?.stack ?? err?.message ?? err ?? "unknown error") + "\n");
+  process.exitCode = 1;
+});