settld 0.2.4 → 0.2.6

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

@@ -0,0 +1,149 @@
+function pdfEscapeText(s) {
+  return String(s ?? "")
+    .replaceAll("\\", "\\\\")
+    .replaceAll("(", "\\(")
+    .replaceAll(")", "\\)");
+}
+
+function concatBuffers(buffers) {
+  const total = buffers.reduce((sum, b) => sum + b.length, 0);
+  const out = Buffer.allocUnsafe(total);
+  let off = 0;
+  for (const b of buffers) {
+    b.copy(out, off);
+    off += b.length;
+  }
+  return out;
+}
+
+function buildPdfObjects(objs) {
+  const header = Buffer.from("%PDF-1.4\n", "ascii");
+  const parts = [header];
+  const offsets = [0];
+  let offset = header.length;
+
+  for (let i = 0; i < objs.length; i += 1) {
+    offsets.push(offset);
+    const n = i + 1;
+    const body = Buffer.isBuffer(objs[i]) ? objs[i] : Buffer.from(String(objs[i]), "utf8");
+    const prefix = Buffer.from(`${n} 0 obj\n`, "ascii");
+    const suffix = Buffer.from("\nendobj\n", "ascii");
+    const chunk = concatBuffers([prefix, body, suffix]);
+    parts.push(chunk);
+    offset += chunk.length;
+  }
+
+  const xrefStart = offset;
+  const xrefLines = [];
+  xrefLines.push("xref\n");
+  xrefLines.push(`0 ${objs.length + 1}\n`);
+  xrefLines.push("0000000000 65535 f \n");
+  for (let i = 1; i < offsets.length; i += 1) {
+    const off = String(offsets[i]).padStart(10, "0");
+    xrefLines.push(`${off} 00000 n \n`);
+  }
+
+  const xref = Buffer.from(xrefLines.join(""), "ascii");
+  parts.push(xref);
+  offset += xref.length;
+
+  const trailer = Buffer.from(
+    `trailer\n<< /Size ${objs.length + 1} /Root 1 0 R >>\nstartxref\n${xrefStart}\n%%EOF\n`,
+    "ascii"
+  );
+  parts.push(trailer);
+  return concatBuffers(parts);
+}
+
+function formatMoneyFromCentsString({ currency, cents }) {
+  const cur = String(currency ?? "").trim() || "UNK";
+  const raw = String(cents ?? "").trim();
+  if (!/^[0-9]+$/.test(raw)) return `${cur} ${raw}`;
+  if (cur === "USD") {
+    const padded = raw.padStart(3, "0");
+    const dollars = padded.slice(0, -2);
+    const centsPart = padded.slice(-2);
+    return `$${dollars}.${centsPart}`;
+  }
+  return `${cur} ${raw} cents`;
+}
+
+export function buildInvoiceSummaryPdf({ title, lines }) {
+  const safeTitle = String(title ?? "Invoice Summary (non-normative)");
+  const safeLines = Array.isArray(lines) ? lines.map((l) => String(l ?? "")) : [];
+
+  const pageWidth = 612;
+  const pageHeight = 792;
+  const fontSize = 11;
+  const leading = 14;
+  const startX = 72;
+  const startY = 720;
+
+  const content = [];
+  content.push("BT");
+  content.push(`/F1 ${fontSize} Tf`);
+  content.push(`${leading} TL`);
+  content.push(`${startX} ${startY} Td`);
+  content.push(`(${pdfEscapeText(safeTitle)}) Tj`);
+  content.push("T*");
+  for (const line of safeLines) {
+    content.push(`(${pdfEscapeText(line)}) Tj`);
+    content.push("T*");
+  }
+  content.push("ET");
+  const contentStream = Buffer.from(content.join("\n") + "\n", "ascii");
+
+  const obj1 = "<< /Type /Catalog /Pages 2 0 R >>";
+  const obj2 = "<< /Type /Pages /Kids [3 0 R] /Count 1 >>";
+  const obj3 = `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${pageWidth} ${pageHeight}] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>`;
+  const obj4 = "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>";
+  const obj5 = concatBuffers([Buffer.from(`<< /Length ${contentStream.length} >>\nstream\n`, "ascii"), contentStream, Buffer.from("endstream", "ascii")]);
+
+  return buildPdfObjects([obj1, obj2, obj3, obj4, obj5]);
+}
+
+export function buildInvoiceSummaryPdfFromClaim({ claim, verification, trust }) {
+  const invoiceId = typeof claim?.invoiceId === "string" ? claim.invoiceId : "";
+  const tenantId = typeof claim?.tenantId === "string" ? claim.tenantId : "";
+  const currency = typeof claim?.currency === "string" ? claim.currency : "UNK";
+  const totalCents = typeof claim?.totalCents === "string" ? claim.totalCents : "";
+  const createdAt = typeof claim?.createdAt === "string" ? claim.createdAt : "";
+
+  const status = verification?.status ?? "unknown";
+  const bundleSha256 = verification?.zipSha256 ?? "";
+  const manifestHash = verification?.manifestHash ?? "";
+  const mode = verification?.mode ?? "";
+
+  const trustLine = trust?.configured
+    ? `Trust roots: ${Array.isArray(trust.keyIds) ? trust.keyIds.join(", ") : ""}`
+    : "Trust roots: none configured";
+
+  const lines = [];
+  if (invoiceId) lines.push(`Invoice: ${invoiceId}`);
+  if (tenantId) lines.push(`Tenant: ${tenantId}`);
+  if (createdAt) lines.push(`Created: ${createdAt}`);
+  if (totalCents) lines.push(`Total: ${formatMoneyFromCentsString({ currency, cents: totalCents })}`);
+  if (mode) lines.push(`Mode: ${mode}`);
+  lines.push(`Status: ${status}`);
+  if (bundleSha256) lines.push(`Bundle SHA-256: ${bundleSha256}`);
+  if (manifestHash) lines.push(`Manifest hash: ${manifestHash}`);
+  lines.push(trustLine);
+
+  const items = Array.isArray(claim?.lineItems) ? claim.lineItems : [];
+  if (items.length) {
+    lines.push("");
+    lines.push("Line items:");
+    for (const it of items.slice(0, 200)) {
+      const code = typeof it?.code === "string" ? it.code : "";
+      const qty = typeof it?.quantity === "string" ? it.quantity : "";
+      const unit = typeof it?.unitPriceCents === "string" ? it.unitPriceCents : "";
+      const amt = typeof it?.amountCents === "string" ? it.amountCents : "";
+      const row = [code && `code=${code}`, qty && `qty=${qty}`, unit && `unitCents=${unit}`, amt && `amountCents=${amt}`].filter(Boolean).join(" ");
+      if (row) lines.push(`- ${row}`);
+    }
+    if (items.length > 200) lines.push(`… (${items.length - 200} more)`);
+  }
+
+  return buildInvoiceSummaryPdf({ title: "Invoice Summary (non-normative)", lines });
+}
+

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

@@ -0,0 +1,69 @@
+import crypto from "node:crypto";
+
+function isPlainObject(v) {
+  return Boolean(v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+}
+
+function sha256Hex(text) {
+  return crypto.createHash("sha256").update(String(text ?? ""), "utf8").digest("hex");
+}
+
+export function resolvePolicyForRun({ tenantSettings, vendorId, contractId }) {
+  const contractPolicies = isPlainObject(tenantSettings?.contractPolicies) ? tenantSettings.contractPolicies : null;
+  if (contractId && contractPolicies && isPlainObject(contractPolicies[contractId])) {
+    return { policy: contractPolicies[contractId], source: { kind: "contract", id: contractId } };
+  }
+  const vendorPolicies = isPlainObject(tenantSettings?.vendorPolicies) ? tenantSettings.vendorPolicies : null;
+  if (vendorId && vendorPolicies && isPlainObject(vendorPolicies[vendorId])) {
+    return { policy: vendorPolicies[vendorId], source: { kind: "vendor", id: vendorId } };
+  }
+  return { policy: null, source: null };
+}
+
+export function normalizePolicyProfileForEnforcement(profile) {
+  const p = isPlainObject(profile) ? profile : {};
+  const requiredModeRaw = p.requiredMode === undefined ? null : String(p.requiredMode ?? "").trim().toLowerCase();
+  const requiredMode = requiredModeRaw === "auto" || requiredModeRaw === "strict" || requiredModeRaw === "compat" ? requiredModeRaw : null;
+  const failOnWarnings = Boolean(p.failOnWarnings);
+  const allowAmberApprovals = p.allowAmberApprovals === undefined ? true : Boolean(p.allowAmberApprovals);
+  const requireProducerReceiptPresent = Boolean(p.requireProducerReceiptPresent);
+  const retentionDays =
+    p.retentionDays === null || p.retentionDays === undefined
+      ? null
+      : Number.isInteger(p.retentionDays)
+        ? p.retentionDays
+        : Number.parseInt(String(p.retentionDays ?? ""), 10);
+  const requiredSignerKeyIdsRaw = p.requiredPricingMatrixSignerKeyIds;
+  const requiredSignerKeyIds = Array.isArray(requiredSignerKeyIdsRaw)
+    ? [...new Set(requiredSignerKeyIdsRaw.map((x) => String(x ?? "").trim()).filter(Boolean))].sort()
+    : null;
+
+  return {
+    requiredMode,
+    failOnWarnings,
+    allowAmberApprovals,
+    requireProducerReceiptPresent,
+    requiredSignerKeyIds,
+    retentionDays: Number.isInteger(retentionDays) && retentionDays > 0 ? retentionDays : null
+  };
+}
+
+export function policyHashHex(policyEffective) {
+  const obj = {
+    requiredMode: policyEffective?.requiredMode ?? null,
+    failOnWarnings: Boolean(policyEffective?.failOnWarnings),
+    allowAmberApprovals: policyEffective?.allowAmberApprovals === undefined ? true : Boolean(policyEffective?.allowAmberApprovals),
+    requireProducerReceiptPresent: Boolean(policyEffective?.requireProducerReceiptPresent),
+    requiredSignerKeyIds: Array.isArray(policyEffective?.requiredSignerKeyIds) ? policyEffective.requiredSignerKeyIds : null,
+    retentionDays: Number.isInteger(policyEffective?.retentionDays) ? policyEffective.retentionDays : null
+  };
+  return sha256Hex(JSON.stringify(obj));
+}
+
+export function effectiveRetentionDaysForRun({ tenantSettings, vendorId, contractId }) {
+  const base = Number.isInteger(tenantSettings?.retentionDays) ? tenantSettings.retentionDays : 30;
+  const { policy } = resolvePolicyForRun({ tenantSettings, vendorId, contractId });
+  const eff = normalizePolicyProfileForEnforcement(policy);
+  return Number.isInteger(eff.retentionDays) ? eff.retentionDays : base;
+}
+

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

@@ -0,0 +1,6 @@
+export function safeTruncate(s, { max = 500 } = {}) {
+  const v = String(s ?? "");
+  if (v.length <= max) return v;
+  return v.slice(0, Math.max(0, max - 1)) + "…";
+}
+

package/services/magic-link/src/render-model.js

@@ -0,0 +1,70 @@
+import { safeTruncate } from "./redaction.js";
+
+export const MAGIC_LINK_RENDER_MODEL_ALLOWLIST_V1 = {
+  schemaVersion: "MagicLinkRenderModelAllowlist.v1",
+  version: 1,
+  // Source of truth for fields that may appear in hosted outputs (HTML/PDF/CSV/support exports).
+  invoiceClaim: {
+    schemaVersion: { maxChars: 128 },
+    tenantId: { maxChars: 500 },
+    invoiceId: { maxChars: 500 },
+    createdAt: { maxChars: 500 },
+    currency: { maxChars: 16 },
+    subtotalCents: { maxChars: 64 },
+    totalCents: { maxChars: 64 },
+    lineItems: {
+      maxItems: 200,
+      fields: {
+        code: { maxChars: 200 },
+        quantity: { maxChars: 64 },
+        unitPriceCents: { maxChars: 64 },
+        amountCents: { maxChars: 64 }
+      }
+    }
+  },
+  metering: { itemsCount: true, evidenceRefsCount: true },
+  decision: {
+    decision: { maxChars: 64 },
+    decidedAt: { maxChars: 500 },
+    decidedByEmail: { pii: true, maxChars: 320 }
+  }
+};
+
+function isPlainObject(v) {
+  return Boolean(v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+}
+
+export function buildPublicInvoiceClaimFromClaimJson(claimJson) {
+  if (!isPlainObject(claimJson)) return null;
+  return {
+    schemaVersion: typeof claimJson.schemaVersion === "string" ? safeTruncate(claimJson.schemaVersion, { max: 128 }) : claimJson.schemaVersion ?? null,
+    tenantId: typeof claimJson.tenantId === "string" ? safeTruncate(claimJson.tenantId, { max: 500 }) : null,
+    invoiceId: typeof claimJson.invoiceId === "string" ? safeTruncate(claimJson.invoiceId, { max: 500 }) : null,
+    createdAt: typeof claimJson.createdAt === "string" ? safeTruncate(claimJson.createdAt, { max: 500 }) : null,
+    currency: typeof claimJson.currency === "string" ? safeTruncate(claimJson.currency, { max: 16 }) : null,
+    subtotalCents: typeof claimJson.subtotalCents === "string" ? safeTruncate(claimJson.subtotalCents, { max: 64 }) : claimJson.subtotalCents ?? null,
+    totalCents: typeof claimJson.totalCents === "string" ? safeTruncate(claimJson.totalCents, { max: 64 }) : null,
+    lineItems: Array.isArray(claimJson.lineItems)
+      ? claimJson.lineItems.slice(0, 200).map((it) => ({
+          code: typeof it?.code === "string" ? safeTruncate(it.code, { max: 200 }) : null,
+          quantity: typeof it?.quantity === "string" ? safeTruncate(it.quantity, { max: 64 }) : null,
+          unitPriceCents: typeof it?.unitPriceCents === "string" ? safeTruncate(it.unitPriceCents, { max: 64 }) : null,
+          amountCents: typeof it?.amountCents === "string" ? safeTruncate(it.amountCents, { max: 64 }) : null
+        }))
+      : []
+  };
+}
+
+export function sampleRenderModelInvoiceClaimV1() {
+  return {
+    schemaVersion: "InvoiceClaim.v1",
+    tenantId: "tenant_demo",
+    invoiceId: "invoice_demo_1",
+    createdAt: "2026-02-05T00:00:00.000Z",
+    currency: "USD",
+    subtotalCents: "10000",
+    totalCents: "10000",
+    lineItems: [{ code: "WORK_MINUTES", quantity: "10", unitPriceCents: "100", amountCents: "1000" }]
+  };
+}
+

package/services/magic-link/src/retention-gc.js

@@ -0,0 +1,158 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { effectiveRetentionDaysForRun } from "./policy.js";
+import { deleteRunRecordBestEffort } from "./run-records.js";
+
+function isPastRetention(createdAtIso, retentionDays) {
+  const createdMs = Date.parse(String(createdAtIso ?? ""));
+  if (!Number.isFinite(createdMs)) return true;
+  const days = Number.isInteger(retentionDays) ? retentionDays : 30;
+  return Date.now() > createdMs + days * 24 * 3600 * 1000;
+}
+
+async function loadMeta({ dataDir, token }) {
+  const fp = path.join(dataDir, "meta", `${token}.json`);
+  const raw = await fs.readFile(fp, "utf8");
+  return JSON.parse(raw);
+}
+
+export async function deleteTokenFilesBestEffort({ dataDir, token, meta }) {
+  const paths = [];
+  const zipPath = typeof meta?.zipPath === "string" ? meta.zipPath : path.join(dataDir, "zips", `${token}.zip`);
+  const verifyJsonPath = typeof meta?.verifyJsonPath === "string" ? meta.verifyJsonPath : path.join(dataDir, "verify", `${token}.json`);
+  const metaPath = path.join(dataDir, "meta", `${token}.json`);
+  const publicJsonPath = typeof meta?.publicJsonPath === "string" ? meta.publicJsonPath : path.join(dataDir, "public", `${token}.json`);
+  const receiptJsonPath = typeof meta?.receiptJsonPath === "string" ? meta.receiptJsonPath : path.join(dataDir, "receipt", `${token}.json`);
+  const summaryPdfPath = typeof meta?.summaryPdfPath === "string" ? meta.summaryPdfPath : path.join(dataDir, "pdf", `${token}.pdf`);
+  const decisionPath = path.join(dataDir, "decisions", `${token}.json`);
+  const settlementDecisionsDir = path.join(dataDir, "settlement_decisions", token);
+  const closePackDir = typeof meta?.closePackDir === "string" ? meta.closePackDir : path.join(dataDir, "closepack", token);
+  const approvalClosePackZipPath =
+    typeof meta?.approvalClosePackZipPath === "string" ? meta.approvalClosePackZipPath : path.join(dataDir, "closepack_exports", `${token}.zip`);
+
+  // Delete blobs first, then metadata/index surfaces.
+  paths.push(zipPath, closePackDir, approvalClosePackZipPath, verifyJsonPath, summaryPdfPath, receiptJsonPath, decisionPath, settlementDecisionsDir, publicJsonPath, metaPath);
+
+  // Webhook delivery records are stored outside per-run meta paths; remove attempts/records for this token.
+  for (const sub of ["attempts", "record"]) {
+    const dir = path.join(dataDir, "webhooks", sub);
+    let names = [];
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      names = (await fs.readdir(dir)).filter((n) => n.endsWith(".json") && n.startsWith(`${token}_`));
+    } catch {
+      names = [];
+    }
+    for (const name of names) {
+      const fp = path.join(dir, name);
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await fs.rm(fp, { force: true });
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  // Persistent webhook retry queue entries can outlive retention windows;
+  // remove jobs that target this token from pending/dead-letter buckets.
+  for (const sub of ["pending", "dead-letter"]) {
+    const dir = path.join(dataDir, "webhook_retry", sub);
+    let names = [];
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      names = (await fs.readdir(dir)).filter((n) => n.endsWith(".json") && n.includes(`_${token}_`));
+    } catch {
+      names = [];
+    }
+    for (const name of names) {
+      const fp = path.join(dir, name);
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await fs.rm(fp, { force: true });
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  for (const p of paths) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await fs.rm(p, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+}
+
+export async function listTenantIdsWithIndex({ dataDir, max = 10_000 } = {}) {
+  const idxRoot = path.join(dataDir, "index");
+  let entries = [];
+  try {
+    entries = await fs.readdir(idxRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const tenants = entries.filter((e) => e.isDirectory()).map((e) => e.name).slice(0, max);
+  tenants.sort();
+  return tenants;
+}
+
+export async function garbageCollectTenantByRetention({ dataDir, tenantId, tenantSettings }) {
+  const idxDir = path.join(dataDir, "index", tenantId);
+  let names = [];
+  try {
+    names = (await fs.readdir(idxDir)).filter((n) => n.endsWith(".json"));
+  } catch {
+    return { ok: true, deleted: 0, kept: 0 };
+  }
+  let deleted = 0;
+  let kept = 0;
+  for (const name of names) {
+    const fp = path.join(idxDir, name);
+    let idx = null;
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      idx = JSON.parse(await fs.readFile(fp, "utf8"));
+    } catch {
+      idx = null;
+    }
+    const token = typeof idx?.token === "string" ? idx.token : null;
+    if (!token || !/^ml_[0-9a-f]{48}$/.test(token)) {
+      // eslint-disable-next-line no-await-in-loop
+      await fs.rm(fp, { force: true });
+      deleted += 1;
+      continue;
+    }
+    let meta = null;
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      meta = await loadMeta({ dataDir, token });
+    } catch {
+      meta = null;
+    }
+    const retentionDays = meta
+      ? effectiveRetentionDaysForRun({
+          tenantSettings,
+          vendorId: typeof meta.vendorId === "string" ? meta.vendorId : null,
+          contractId: typeof meta.contractId === "string" ? meta.contractId : null
+        })
+      : Number.isInteger(tenantSettings?.retentionDays)
+        ? tenantSettings.retentionDays
+        : 30;
+    if (!meta || isPastRetention(meta.createdAt, retentionDays)) {
+      // eslint-disable-next-line no-await-in-loop
+      await deleteTokenFilesBestEffort({ dataDir, token, meta });
+      // eslint-disable-next-line no-await-in-loop
+      await deleteRunRecordBestEffort({ dataDir, tenantId, token });
+      // eslint-disable-next-line no-await-in-loop
+      await fs.rm(fp, { force: true });
+      deleted += 1;
+      continue;
+    }
+    kept += 1;
+  }
+  return { ok: true, deleted, kept };
+}