settld 0.2.5 → 0.2.7

package/packages/api-sdk/src/index.js

@@ -0,0 +1,10 @@
+export { SettldClient } from "./client.js";
+export { fetchWithSettldAutopay } from "./x402-autopay.js";
+export {
+  verifySettldWebhookSignature,
+  SettldWebhookSignatureError,
+  SettldWebhookSignatureHeaderError,
+  SettldWebhookTimestampToleranceError,
+  SettldWebhookNoMatchingSignatureError
+} from "./webhook-signature.js";
+export { verifySettldWebhook } from "./express-middleware.js";

package/packages/api-sdk/src/webhook-signature.js

@@ -0,0 +1,182 @@
+import crypto from "node:crypto";
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+function toBodyBuffer(rawBody) {
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(rawBody)) return rawBody;
+  if (typeof rawBody === "string") return Buffer.from(rawBody, "utf8");
+  if (rawBody instanceof ArrayBuffer) return Buffer.from(rawBody);
+  if (rawBody instanceof Uint8Array) return Buffer.from(rawBody.buffer, rawBody.byteOffset, rawBody.byteLength);
+  throw new TypeError("rawBody must be a string, Buffer, Uint8Array, or ArrayBuffer");
+}
+
+function parseTimestampToMs(timestamp) {
+  const raw = String(timestamp ?? "").trim();
+  if (!raw) return Number.NaN;
+  if (/^\d+$/.test(raw)) {
+    const asSeconds = Number(raw);
+    if (!Number.isSafeInteger(asSeconds) || asSeconds <= 0) return Number.NaN;
+    return asSeconds * 1000;
+  }
+  const asMs = Date.parse(raw);
+  if (!Number.isFinite(asMs)) return Number.NaN;
+  return asMs;
+}
+
+function normalizeHex(value) {
+  const candidate = String(value ?? "").trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(candidate)) return null;
+  return candidate;
+}
+
+function timingSafeEqualHex(leftHex, rightHex) {
+  const left = normalizeHex(leftHex);
+  const right = normalizeHex(rightHex);
+  if (!left || !right) return false;
+  const leftBuf = Buffer.from(left, "hex");
+  const rightBuf = Buffer.from(right, "hex");
+  if (leftBuf.length !== rightBuf.length) return false;
+  return crypto.timingSafeEqual(leftBuf, rightBuf);
+}
+
+function parseSignatureHeader(signatureHeader) {
+  if (!isNonEmptyString(signatureHeader)) {
+    throw new SettldWebhookSignatureHeaderError("x-settld-signature header is required");
+  }
+  const parts = signatureHeader
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (parts.length === 0) {
+    throw new SettldWebhookSignatureHeaderError("x-settld-signature header is empty");
+  }
+
+  let timestamp = null;
+  const signatures = [];
+  for (const part of parts) {
+    const separatorIndex = part.indexOf("=");
+    if (separatorIndex <= 0) {
+      signatures.push(part);
+      continue;
+    }
+    const key = part.slice(0, separatorIndex).trim().toLowerCase();
+    const value = part.slice(separatorIndex + 1).trim();
+    if (!value) continue;
+    if (key === "t") {
+      timestamp = value;
+      continue;
+    }
+    if (key === "v1") {
+      signatures.push(value);
+    }
+  }
+
+  if (signatures.length === 0) {
+    throw new SettldWebhookSignatureHeaderError("x-settld-signature header did not include any signatures");
+  }
+  return { timestamp, signatures };
+}
+
+function parseVerifyOptions(optionsOrTolerance) {
+  if (optionsOrTolerance === null || optionsOrTolerance === undefined) {
+    return { toleranceSeconds: 300, timestamp: null, nowMs: Date.now() };
+  }
+  if (typeof optionsOrTolerance === "number") {
+    return { toleranceSeconds: optionsOrTolerance, timestamp: null, nowMs: Date.now() };
+  }
+  if (!optionsOrTolerance || typeof optionsOrTolerance !== "object" || Array.isArray(optionsOrTolerance)) {
+    throw new TypeError("options must be a number or plain object");
+  }
+  return {
+    toleranceSeconds:
+      optionsOrTolerance.toleranceSeconds === undefined || optionsOrTolerance.toleranceSeconds === null
+        ? 300
+        : Number(optionsOrTolerance.toleranceSeconds),
+    timestamp: optionsOrTolerance.timestamp ?? null,
+    nowMs:
+      optionsOrTolerance.nowMs === undefined || optionsOrTolerance.nowMs === null
+        ? Date.now()
+        : Number(optionsOrTolerance.nowMs)
+  };
+}
+
+export class SettldWebhookSignatureError extends Error {
+  constructor(message, { code = "SETTLD_WEBHOOK_SIGNATURE_ERROR" } = {}) {
+    super(message);
+    this.name = "SettldWebhookSignatureError";
+    this.code = code;
+  }
+}
+
+export class SettldWebhookSignatureHeaderError extends SettldWebhookSignatureError {
+  constructor(message) {
+    super(message, { code: "SETTLD_WEBHOOK_SIGNATURE_HEADER_INVALID" });
+    this.name = "SettldWebhookSignatureHeaderError";
+  }
+}
+
+export class SettldWebhookTimestampToleranceError extends SettldWebhookSignatureError {
+  constructor(message, { timestamp = null, toleranceSeconds = null, nowMs = null } = {}) {
+    super(message, { code: "SETTLD_WEBHOOK_TIMESTAMP_OUTSIDE_TOLERANCE" });
+    this.name = "SettldWebhookTimestampToleranceError";
+    this.timestamp = timestamp;
+    this.toleranceSeconds = toleranceSeconds;
+    this.nowMs = nowMs;
+  }
+}
+
+export class SettldWebhookNoMatchingSignatureError extends SettldWebhookSignatureError {
+  constructor(message) {
+    super(message, { code: "SETTLD_WEBHOOK_SIGNATURE_NO_MATCH" });
+    this.name = "SettldWebhookNoMatchingSignatureError";
+  }
+}
+
+export function verifySettldWebhookSignature(rawBody, signatureHeader, secret, optionsOrTolerance = 300) {
+  if (!isNonEmptyString(secret)) throw new TypeError("secret is required");
+  const bodyBuffer = toBodyBuffer(rawBody);
+  const parsed = parseSignatureHeader(signatureHeader);
+  const options = parseVerifyOptions(optionsOrTolerance);
+
+  if (!Number.isFinite(options.toleranceSeconds) || options.toleranceSeconds <= 0) {
+    throw new TypeError("toleranceSeconds must be a positive number");
+  }
+  if (!Number.isFinite(options.nowMs)) {
+    throw new TypeError("nowMs must be a finite number");
+  }
+
+  const timestamp = isNonEmptyString(parsed.timestamp)
+    ? parsed.timestamp.trim()
+    : isNonEmptyString(options.timestamp)
+      ? String(options.timestamp).trim()
+      : null;
+  if (!timestamp) {
+    throw new SettldWebhookSignatureHeaderError("timestamp is required (use t=... in signature header or options.timestamp)");
+  }
+
+  const timestampMs = parseTimestampToMs(timestamp);
+  if (!Number.isFinite(timestampMs)) {
+    throw new SettldWebhookSignatureHeaderError("timestamp is invalid");
+  }
+  const ageSeconds = Math.abs(options.nowMs - timestampMs) / 1000;
+  if (ageSeconds > options.toleranceSeconds) {
+    throw new SettldWebhookTimestampToleranceError("signature timestamp is outside tolerance", {
+      timestamp,
+      toleranceSeconds: options.toleranceSeconds,
+      nowMs: options.nowMs
+    });
+  }
+
+  const hmac = crypto.createHmac("sha256", String(secret));
+  hmac.update(`${timestamp}.`, "utf8");
+  hmac.update(bodyBuffer);
+  const expected = hmac.digest("hex");
+  for (const provided of parsed.signatures) {
+    if (timingSafeEqualHex(provided, expected)) {
+      return true;
+    }
+  }
+  throw new SettldWebhookNoMatchingSignatureError("no matching signature in x-settld-signature header");
+}

package/packages/api-sdk/src/x402-autopay.js

@@ -0,0 +1,210 @@
+function assertFetchFunction(fetchImpl) {
+  if (typeof fetchImpl !== "function") throw new TypeError("fetch must be a function");
+  return fetchImpl;
+}
+
+function normalizeHeaderName(name, fallback) {
+  const raw = typeof name === "string" && name.trim() !== "" ? name.trim() : fallback;
+  return raw.toLowerCase();
+}
+
+function parseBooleanLike(value) {
+  const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (raw === "1" || raw === "true" || raw === "yes" || raw === "on") return true;
+  if (raw === "0" || raw === "false" || raw === "no" || raw === "off") return false;
+  return null;
+}
+
+function normalizeChallengeRef(value) {
+  const raw = typeof value === "string" ? value.trim() : "";
+  return raw === "" ? null : raw;
+}
+
+function normalizeChallengeHash(value) {
+  const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return /^[0-9a-f]{64}$/.test(raw) ? raw : null;
+}
+
+function parseChallengeFields(text) {
+  const raw = typeof text === "string" ? text.trim() : "";
+  if (!raw) return null;
+  if (raw.startsWith("{") && raw.endsWith("}")) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  const out = {};
+  for (const part of raw.split(";")) {
+    const chunk = part.trim();
+    if (!chunk) continue;
+    const idx = chunk.indexOf("=");
+    if (idx <= 0) continue;
+    const key = chunk.slice(0, idx).trim();
+    const value = chunk.slice(idx + 1).trim();
+    if (!key) continue;
+    out[key] = value;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+function parseBase64UrlJson(value) {
+  const raw = typeof value === "string" ? value.trim() : "";
+  if (!raw) return null;
+  if (typeof Buffer === "undefined") return null;
+  try {
+    const text = Buffer.from(raw, "base64url").toString("utf8");
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function sortedJsonClone(value) {
+  if (Array.isArray(value)) return value.map((entry) => sortedJsonClone(entry));
+  if (!value || typeof value !== "object") return value;
+  const out = {};
+  for (const key of Object.keys(value).sort((left, right) => left.localeCompare(right))) {
+    out[key] = sortedJsonClone(value[key]);
+  }
+  return out;
+}
+
+function normalizeAgentPassportHeaderValue(agentPassport) {
+  if (agentPassport === null || agentPassport === undefined) return null;
+  if (!agentPassport || typeof agentPassport !== "object" || Array.isArray(agentPassport)) {
+    throw new TypeError("agentPassport must be an object when provided");
+  }
+  if (typeof Buffer === "undefined") {
+    throw new TypeError("agentPassport header encoding requires Buffer support");
+  }
+  const canonical = JSON.stringify(sortedJsonClone(agentPassport));
+  return Buffer.from(canonical, "utf8").toString("base64url");
+}
+
+function buildX402ChallengeMetadata(res, { gateHeaderName }) {
+  const gateIdRaw = res.headers.get(gateHeaderName);
+  const gateId = typeof gateIdRaw === "string" && gateIdRaw.trim() !== "" ? gateIdRaw.trim() : null;
+  const paymentRequiredRaw = res.headers.get("x-payment-required") ?? res.headers.get("payment-required");
+  const paymentRequired = typeof paymentRequiredRaw === "string" && paymentRequiredRaw.trim() !== "" ? paymentRequiredRaw.trim() : null;
+  const fields = paymentRequired ? parseChallengeFields(paymentRequired) : null;
+  const quote = parseBase64UrlJson(res.headers.get("x-settld-provider-quote"));
+  const quoteSignature = parseBase64UrlJson(res.headers.get("x-settld-provider-quote-signature"));
+  const quoteRequired = parseBooleanLike(fields?.quoteRequired);
+  return {
+    gateId,
+    paymentRequired,
+    fields,
+    policyChallenge: {
+      spendAuthorizationMode: normalizeChallengeRef(fields?.spendAuthorizationMode),
+      requestBindingMode: normalizeChallengeRef(fields?.requestBindingMode),
+      requestBindingSha256: normalizeChallengeHash(fields?.requestBindingSha256),
+      quoteRequired,
+      quoteId: normalizeChallengeRef(fields?.quoteId),
+      providerId: normalizeChallengeRef(fields?.providerId),
+      toolId: normalizeChallengeRef(fields?.toolId),
+      policyRef: normalizeChallengeRef(fields?.policyRef),
+      policyVersion: normalizeChallengeRef(fields?.policyVersion),
+      policyHash: normalizeChallengeHash(fields?.policyHash),
+      policyFingerprint: normalizeChallengeHash(fields?.policyFingerprint),
+      sponsorRef: normalizeChallengeRef(fields?.sponsorRef),
+      sponsorWalletRef: normalizeChallengeRef(fields?.sponsorWalletRef)
+    },
+    providerQuote: quote,
+    providerQuoteSignature: quoteSignature
+  };
+}
+
+function cloneBodyForRetry(body) {
+  if (body === null || body === undefined) return { ok: true, value: undefined };
+  if (typeof body === "string") return { ok: true, value: body };
+  if (body instanceof URLSearchParams) return { ok: true, value: new URLSearchParams(body) };
+  if (body instanceof ArrayBuffer) return { ok: true, value: body.slice(0) };
+  if (ArrayBuffer.isView(body)) {
+    const bytes = new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    return { ok: true, value: Uint8Array.from(bytes) };
+  }
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(body)) return { ok: true, value: Buffer.from(body) };
+  return { ok: false, reason: "body_not_replayable" };
+}
+
+function normalizeInitHeaders(initHeaders) {
+  const out = new Headers();
+  if (!initHeaders) return out;
+  const input = new Headers(initHeaders);
+  for (const [k, v] of input.entries()) out.set(k, v);
+  return out;
+}
+
+function buildInitialInit(init, { agentPassportHeaderName, agentPassportHeaderValue }) {
+  const safeInit = init && typeof init === "object" ? init : {};
+  const headers = normalizeInitHeaders(safeInit.headers);
+  if (agentPassportHeaderValue) headers.set(agentPassportHeaderName, agentPassportHeaderValue);
+  return {
+    ...safeInit,
+    headers
+  };
+}
+
+function buildRetryInit(init, { gateHeaderName, gateId, agentPassportHeaderName, agentPassportHeaderValue }) {
+  const safeInit = init && typeof init === "object" ? init : {};
+  const bodyResult = cloneBodyForRetry(safeInit.body);
+  if (!bodyResult.ok) {
+    const err = new Error("x402 autopay cannot replay this request body");
+    err.code = "SETTLD_AUTOPAY_BODY_NOT_REPLAYABLE";
+    throw err;
+  }
+
+  const headers = normalizeInitHeaders(safeInit.headers);
+  headers.set(gateHeaderName, gateId);
+  if (agentPassportHeaderValue) headers.set(agentPassportHeaderName, agentPassportHeaderValue);
+
+  return {
+    ...safeInit,
+    headers,
+    body: bodyResult.value
+  };
+}
+
+export async function fetchWithSettldAutopay(url, init = {}, opts = {}) {
+  const fetchImpl = assertFetchFunction(opts?.fetch ?? globalThis.fetch);
+  const gateHeaderName = normalizeHeaderName(opts?.gateHeaderName, "x-settld-gate-id");
+  const agentPassportHeaderName = normalizeHeaderName(opts?.agentPassportHeaderName, "x-settld-agent-passport");
+  const agentPassportHeaderValue = normalizeAgentPassportHeaderValue(opts?.agentPassport ?? null);
+  const onChallenge = typeof opts?.onChallenge === "function" ? opts.onChallenge : null;
+  const maxAttemptsRaw = Number(opts?.maxAttempts ?? 2);
+  const maxAttempts = Number.isSafeInteger(maxAttemptsRaw) && maxAttemptsRaw >= 1 ? maxAttemptsRaw : 2;
+
+  let attempt = 0;
+  let currentInit = buildInitialInit(init, { agentPassportHeaderName, agentPassportHeaderValue });
+  let lastResponse = null;
+  while (attempt < maxAttempts) {
+    attempt += 1;
+    const res = await fetchImpl(url, currentInit);
+    lastResponse = res;
+    if (res.status !== 402) return res;
+
+    if (onChallenge) {
+      try {
+        onChallenge(buildX402ChallengeMetadata(res, { gateHeaderName }));
+      } catch {
+        // Ignore callback failures to keep autopay deterministic.
+      }
+    }
+    if (attempt >= maxAttempts) return res;
+
+    const gateIdRaw = res.headers.get(gateHeaderName);
+    const gateId = typeof gateIdRaw === "string" ? gateIdRaw.trim() : "";
+    if (!gateId) return res;
+
+    const nextInit = buildRetryInit(currentInit, { gateHeaderName, gateId, agentPassportHeaderName, agentPassportHeaderValue });
+    currentInit = nextInit;
+  }
+
+  return lastResponse;
+}

package/scripts/ci/cli-pack-smoke.mjs

@@ -42,6 +42,8 @@ async function main() {
     sh("tar", ["-xzf", tarballPath, "-C", unpackDir], { env: npmEnv });
     const packageRoot = path.join(unpackDir, "package");
     const cliPath = path.join(packageRoot, "bin", "settld.js");
+    await fs.access(path.join(packageRoot, "scripts", "mcp", "settld-mcp-server.mjs"));
+    await fs.access(path.join(packageRoot, "packages", "api-sdk", "src", "x402-autopay.js"));
 
     const runTarballCli = (args) => {
       const cmd = ["npx", "--yes", "--package", tarballPath, "--", "settld", ...args].map(shellQuote).join(" ");

package/scripts/setup/login.mjs

@@ -290,6 +290,11 @@ export async function runLogin({
       });
       if (!otpRequest.res.ok) {
         const code = responseCode(otpRequest);
+        if (otpRequest.res.status === 400 && code === "BUYER_AUTH_DISABLED") {
+          throw new Error(
+            "buyer OTP login is not enabled for this tenant. This tenant may be stale on the onboarding service; rerun `settld login` without --tenant-id to create a fresh tenant, or use bootstrap/manual API key mode."
+          );
+        }
         if (otpRequest.res.status === 403 && code === "FORBIDDEN") {
           throw new Error(
             "OTP login is unavailable on this base URL. Use `Generate during setup` with an onboarding bootstrap API key, or use an existing tenant API key."
@@ -326,7 +331,7 @@ export async function runLogin({
       otpAlreadyIssued = Boolean(signup.json?.otpIssued);
       if (interactive) stdout.write(`Created tenant: ${tenantId}\n`);
     }
-    if (!otpAlreadyIssued) await requestTenantOtp(tenantId);
+    if (!otpAlreadyIssued && !state.otp) await requestTenantOtp(tenantId);
 
     if (!state.otp && interactive) {
       state.otp = await promptLine(rl, "OTP code", { required: true });

package/scripts/setup/onboard.mjs

@@ -1020,6 +1020,17 @@ async function runGuidedQuickFlow({
     }
   }
 
+  const paidToolsBaseUrl = String(actionEnv.SETTLD_PAID_TOOLS_BASE_URL ?? "").trim();
+  if (!paidToolsBaseUrl) {
+    summary.firstPaidCall = {
+      ok: false,
+      skipped: true,
+      reason: "SETTLD_PAID_TOOLS_BASE_URL not configured"
+    };
+    summary.warnings.push("first paid call probe skipped (SETTLD_PAID_TOOLS_BASE_URL not configured)");
+    return summary;
+  }
+
   const paidProbe = runMcpPaidCallProbe({ env: actionEnv });
   if (paidProbe.ok) {
     summary.firstPaidCall = { ok: true };
@@ -1126,10 +1137,24 @@ async function requestRuntimeBootstrapMcpEnv({
     json = null;
   }
   if (!res.ok) {
+    const responseCode =
+      json && typeof json === "object" && (typeof json?.code === "string" || typeof json?.error === "string")
+        ? String(json?.code ?? json?.error ?? "").trim().toUpperCase()
+        : "";
     const message =
       json && typeof json === "object"
         ? json?.message ?? json?.error ?? `HTTP ${res.status}`
         : text || `HTTP ${res.status}`;
+    if (res.status === 403 && cookie && !apiKey) {
+      throw new Error(
+        `runtime bootstrap request failed (403): ${String(message)}. Saved login session was rejected for this tenant; rerun \`settld login\` without --tenant-id to create a fresh tenant, or choose \`Generate during setup\`.`
+      );
+    }
+    if (res.status === 400 && responseCode === "BUYER_AUTH_DISABLED") {
+      throw new Error(
+        "runtime bootstrap request failed (400): buyer OTP login is not enabled for this tenant. Rerun `settld login` without --tenant-id to create a fresh tenant, or choose `Generate during setup`."
+      );
+    }
     throw new Error(`runtime bootstrap request failed (${res.status}): ${String(message)}`);
   }
   return extractBootstrapMcpEnv(json);
@@ -1944,7 +1969,8 @@ export async function runOnboard({
       if (guided.ran) {
         lines.push(`- wallet fund: ${guided.walletFund?.ok ? "ok" : "not completed"}`);
         lines.push(`- wallet balance watch: ${guided.walletBalanceWatch?.ok ? "ok" : "not completed"}`);
-        lines.push(`- first paid call: ${guided.firstPaidCall?.ok ? "ok" : "failed"}`);
+        const firstPaidCallState = guided.firstPaidCall?.skipped ? "skipped" : guided.firstPaidCall?.ok ? "ok" : "failed";
+        lines.push(`- first paid call: ${firstPaidCallState}`);
       } else {
         lines.push("- skipped");
       }

package/scripts/setup/onboarding-failure-taxonomy.mjs

@@ -19,6 +19,17 @@ const FAILURE_CLASSES = Object.freeze([
     patterns: [/OTP_(INVALID|EXPIRED|CONSUMED|MISSING)/i, /otp code is required/i, /invalid otp/i],
     remediation: "Request a fresh OTP and retry `settld login`."
   },
+  {
+    code: "ONBOARDING_AUTH_TENANT_DISABLED",
+    phase: "auth",
+    patterns: [
+      /buyer OTP login is not enabled for this tenant/i,
+      /BUYER_AUTH_DISABLED/i,
+      /Saved login session was rejected for this tenant/i
+    ],
+    remediation:
+      "Rerun `settld login` without `--tenant-id` to create a fresh tenant, or choose `Generate during setup` / `Paste existing key`."
+  },
   {
     code: "ONBOARDING_BOOTSTRAP_FORBIDDEN",
     phase: "bootstrap",

package/services/magic-link/README.md

@@ -27,7 +27,8 @@ Example:
 export MAGIC_LINK_HOST=127.0.0.1   # set 0.0.0.0 in prod
 export MAGIC_LINK_PORT=8787
 export MAGIC_LINK_API_KEY='dev_key'
-export MAGIC_LINK_DATA_DIR=/tmp/settld-magic-link
+export MAGIC_LINK_DATA_DIR=/tmp/settld-magic-link # dev only; use a persistent volume path in production
+export MAGIC_LINK_REQUIRE_DURABLE_DATA_DIR=0      # set 1 in production to fail fast on ephemeral paths
 export MAGIC_LINK_VERIFY_TIMEOUT_MS=60000
 export MAGIC_LINK_RATE_LIMIT_UPLOADS_PER_HOUR=100
 export MAGIC_LINK_VERIFY_QUEUE_WORKERS=2
@@ -82,11 +83,12 @@ Magic Link can deliver OTP codes in three modes:
 - `record` (default): write OTPs to an on-disk outbox under `MAGIC_LINK_DATA_DIR` (dev/testing)
 - `log`: log OTP codes to stdout (dev only)
 - `smtp`: send OTP codes via SMTP (production)
+- `resend`: send OTP codes via Resend HTTPS API (recommended on hosts where SMTP egress is restricted)
 
 Env vars:
 
-- `MAGIC_LINK_BUYER_OTP_DELIVERY_MODE=record|log|smtp`
-- `MAGIC_LINK_DECISION_OTP_DELIVERY_MODE=record|log|smtp`
+- `MAGIC_LINK_BUYER_OTP_DELIVERY_MODE=record|log|smtp|resend`
+- `MAGIC_LINK_DECISION_OTP_DELIVERY_MODE=record|log|smtp|resend`
 
 SMTP config (required for `smtp` mode):
 
@@ -95,7 +97,13 @@ SMTP config (required for `smtp` mode):
 - `MAGIC_LINK_SMTP_SECURE=1|0` (default `0`; set `1` for SMTPS/465)
 - `MAGIC_LINK_SMTP_STARTTLS=1|0` (default `1`; ignored when `SECURE=1`)
 - `MAGIC_LINK_SMTP_USER`, `MAGIC_LINK_SMTP_PASS` (optional; enables `AUTH PLAIN`)
-- `MAGIC_LINK_SMTP_FROM` (required when `MAGIC_LINK_SMTP_HOST` is set)
+- `MAGIC_LINK_SMTP_FROM` (required when `MAGIC_LINK_SMTP_HOST` is set; use bare email for envelope sender, e.g. `ops@settld.work`)
+
+Resend config (required for `resend` mode):
+
+- `MAGIC_LINK_RESEND_API_KEY`
+- `MAGIC_LINK_RESEND_FROM` (verified sender, e.g. `onboarding@settld.work`)
+- `MAGIC_LINK_RESEND_BASE_URL` (optional, default `https://api.resend.com`)
 
 ## Data dir format + upgrades
 
@@ -106,6 +114,7 @@ Magic Link persists state under `MAGIC_LINK_DATA_DIR`. A small format marker is
 On startup, Magic Link can initialize/migrate this marker (default: enabled):
 
 - `MAGIC_LINK_MIGRATE_ON_STARTUP=1` (default)
+- `MAGIC_LINK_REQUIRE_DURABLE_DATA_DIR=1|0` (default `0`; set `1` in production to block startup when `MAGIC_LINK_DATA_DIR` points to `/tmp`)
 
 You can also run an explicit check/migrate command without starting the server:
 

package/services/magic-link/src/buyer-auth.js

@@ -3,6 +3,7 @@ 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();
@@ -44,7 +45,15 @@ function issueCode6() {
   return String(n).padStart(6, "0");
 }
 
-export async function issueBuyerOtp({ dataDir, tenantId, email, ttlSeconds, deliveryMode, smtp } = {}) {
+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 issueBuyerOtp({ dataDir, tenantId, email, ttlSeconds, deliveryMode, smtp, resend } = {}) {
   const emailNorm = normalizeEmailLower(email);
   if (!emailNorm) return { ok: false, error: "INVALID_EMAIL", message: "invalid email" };
 
@@ -106,7 +115,29 @@ export async function issueBuyerOtp({ dataDir, tenantId, email, ttlSeconds, deli
         text: `Your login 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: err?.message ?? String(err ?? "smtp failed") };
+      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 login code",
+        text: `Your login 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");

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

@@ -3,6 +3,7 @@ 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();
@@ -44,7 +45,15 @@ function issueCode6() {
   return String(n).padStart(6, "0");
 }
 
-export async function issueDecisionOtp({ dataDir, token, email, ttlSeconds, deliveryMode, smtp } = {}) {
+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" };
 
@@ -103,7 +112,29 @@ export async function issueDecisionOtp({ dataDir, token, email, ttlSeconds, deli
         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: err?.message ?? String(err ?? "smtp failed") };
+      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");