settld 0.2.4 → 0.2.6

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/ci/run-public-onboarding-gate.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function parseArgs(argv) {
+  const out = {
+    baseUrl: process.env.SETTLD_BASE_URL ?? "https://api.settld.work",
+    tenantId: process.env.SETTLD_TENANT_ID ?? "tenant_default",
+    email: process.env.SETTLD_ONBOARDING_PROBE_EMAIL ?? "probe@settld.work",
+    out: "artifacts/gates/public-onboarding-gate.json"
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = String(argv[i] ?? "");
+    const next = () => {
+      i += 1;
+      if (i >= argv.length) throw new Error(`missing value for ${arg}`);
+      return String(argv[i] ?? "");
+    };
+    if (arg === "--base-url") out.baseUrl = next();
+    else if (arg.startsWith("--base-url=")) out.baseUrl = arg.slice("--base-url=".length);
+    else if (arg === "--tenant-id") out.tenantId = next();
+    else if (arg.startsWith("--tenant-id=")) out.tenantId = arg.slice("--tenant-id=".length);
+    else if (arg === "--email") out.email = next();
+    else if (arg.startsWith("--email=")) out.email = arg.slice("--email=".length);
+    else if (arg === "--out") out.out = next();
+    else if (arg.startsWith("--out=")) out.out = arg.slice("--out=".length);
+  }
+  out.baseUrl = String(out.baseUrl ?? "").trim().replace(/\/+$/, "");
+  out.tenantId = String(out.tenantId ?? "").trim();
+  out.email = String(out.email ?? "").trim().toLowerCase();
+  out.out = String(out.out ?? "").trim();
+  if (!out.baseUrl) throw new Error("--base-url is required");
+  if (!out.tenantId) throw new Error("--tenant-id is required");
+  if (!out.email) throw new Error("--email is required");
+  if (!out.out) throw new Error("--out is required");
+  return out;
+}
+
+async function requestJson(url, { method = "GET", body = null, headers = {} } = {}) {
+  const res = await fetch(url, {
+    method,
+    headers: {
+      ...(body === null ? {} : { "content-type": "application/json" }),
+      ...headers
+    },
+    body: body === null ? undefined : JSON.stringify(body)
+  });
+  const text = await res.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  return {
+    ok: res.ok,
+    statusCode: res.status,
+    url,
+    text,
+    json
+  };
+}
+
+function summarizeBody(outcome) {
+  if (outcome?.json && typeof outcome.json === "object") {
+    return {
+      code: outcome.json.code ?? null,
+      error: outcome.json.error ?? null,
+      message: outcome.json.message ?? null,
+      authMode: outcome.json.authMode ?? null
+    };
+  }
+  return { raw: String(outcome?.text ?? "").slice(0, 500) };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const startedAt = new Date().toISOString();
+  const steps = [];
+  const errors = [];
+
+  const authMode = await requestJson(`${args.baseUrl}/v1/public/auth-mode`);
+  steps.push({
+    step: "public_auth_mode",
+    statusCode: authMode.statusCode,
+    body: summarizeBody(authMode)
+  });
+  if (authMode.statusCode !== 200 || typeof authMode.json?.authMode !== "string") {
+    errors.push({
+      code: "PUBLIC_AUTH_MODE_UNAVAILABLE",
+      message: `expected GET /v1/public/auth-mode to return 200 with authMode; got ${authMode.statusCode}`
+    });
+  }
+
+  const otpProbe = await requestJson(
+    `${args.baseUrl}/v1/tenants/${encodeURIComponent(args.tenantId)}/buyer/login/otp`,
+    {
+      method: "POST",
+      body: { email: args.email }
+    }
+  );
+  steps.push({
+    step: "buyer_login_otp_probe",
+    statusCode: otpProbe.statusCode,
+    body: summarizeBody(otpProbe)
+  });
+  if ([403, 404, 405, 503].includes(otpProbe.statusCode)) {
+    errors.push({
+      code: "BUYER_LOGIN_OTP_UNAVAILABLE",
+      message: `expected buyer OTP endpoint to be reachable (non-403/404/405/503); got ${otpProbe.statusCode}`
+    });
+  }
+
+  const report = {
+    schemaVersion: "PublicOnboardingGate.v1",
+    ok: errors.length === 0,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    baseUrl: args.baseUrl,
+    tenantId: args.tenantId,
+    steps,
+    errors
+  };
+
+  await fs.mkdir(path.dirname(args.out), { recursive: true });
+  await fs.writeFile(args.out, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+  process.stdout.write(`wrote public onboarding gate report: ${path.resolve(args.out)}\n`);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exit(1);
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(err)}\n`);
+  process.exit(1);
+});
+

package/scripts/setup/login.mjs

@@ -8,6 +8,10 @@ import { fileURLToPath } from "node:url";
 import { cookieHeaderFromSetCookie, defaultSessionPath, writeSavedSession } from "./session-store.mjs";
 
 const FORMAT_OPTIONS = new Set(["text", "json"]);
+const AUTH_MODE_PUBLIC_SIGNUP = "public_signup";
+const AUTH_MODE_ENTERPRISE_PREPROVISIONED = "enterprise_preprovisioned";
+const AUTH_MODE_HYBRID = "hybrid";
+const KNOWN_AUTH_MODES = new Set([AUTH_MODE_PUBLIC_SIGNUP, AUTH_MODE_ENTERPRISE_PREPROVISIONED, AUTH_MODE_HYBRID]);
 
 function usage() {
   const text = [
@@ -151,6 +155,52 @@ async function requestJson(url, { method, body, headers = {}, fetchImpl = fetch
   return { res, text, json };
 }
 
+function normalizeAuthMode(value) {
+  const mode = String(value ?? "").trim().toLowerCase();
+  return KNOWN_AUTH_MODES.has(mode) ? mode : "unknown";
+}
+
+export async function detectDeploymentAuthMode({ baseUrl, fetchImpl = fetch } = {}) {
+  const normalizedBaseUrl = mustHttpUrl(baseUrl, "base URL");
+  let response;
+  try {
+    response = await requestJson(`${normalizedBaseUrl}/v1/public/auth-mode`, {
+      method: "GET",
+      fetchImpl
+    });
+  } catch {
+    return {
+      schemaVersion: "SettldAuthModeDiscovery.v1",
+      mode: "unknown",
+      source: "network_error",
+      enterpriseProvisionedTenantsOnly: null
+    };
+  }
+  if (!response.res.ok) {
+    return {
+      schemaVersion: "SettldAuthModeDiscovery.v1",
+      mode: "unknown",
+      source: `http_${response.res.status}`,
+      enterpriseProvisionedTenantsOnly: null
+    };
+  }
+  const mode = normalizeAuthMode(response.json?.authMode);
+  const enterpriseOnly =
+    typeof response.json?.enterpriseProvisionedTenantsOnly === "boolean"
+      ? response.json.enterpriseProvisionedTenantsOnly
+      : mode === AUTH_MODE_ENTERPRISE_PREPROVISIONED
+        ? true
+        : mode === "unknown"
+          ? null
+          : false;
+  return {
+    schemaVersion: "SettldAuthModeDiscovery.v1",
+    mode,
+    source: "endpoint",
+    enterpriseProvisionedTenantsOnly: enterpriseOnly
+  };
+}
+
 function responseCode({ json }) {
   const direct = typeof json?.code === "string" ? json.code : "";
   if (direct) return direct;
@@ -220,6 +270,15 @@ export async function runLogin({
     }
 
     const baseUrl = mustHttpUrl(state.baseUrl, "base URL");
+    const authMode = await detectDeploymentAuthMode({ baseUrl, fetchImpl });
+    if (interactive && authMode.mode !== "unknown") {
+      stdout.write(`Detected auth mode: ${authMode.mode}\n`);
+    }
+    if (!state.tenantId && authMode.mode === AUTH_MODE_ENTERPRISE_PREPROVISIONED) {
+      throw new Error(
+        "This deployment uses enterprise_preprovisioned mode. Pass --tenant-id <existing_tenant> and login via OTP, or use bootstrap/manual API key flow."
+      );
+    }
     if (!state.email) throw new Error("email is required");
     if (!state.tenantId && !state.company) throw new Error("company is required when tenant ID is omitted");
 
@@ -230,6 +289,17 @@ export async function runLogin({
         fetchImpl
       });
       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."
+          );
+        }
         const message = responseMessage(otpRequest);
         throw new Error(`otp request failed (${otpRequest.res.status}): ${message}`);
       }
@@ -261,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 });
@@ -299,7 +369,8 @@ export async function runLogin({
       tenantId: session.tenantId,
       email: session.email,
       sessionFile: state.sessionFile,
-      expiresAt: session.expiresAt ?? null
+      expiresAt: session.expiresAt ?? null,
+      authMode: authMode.mode
     };
 
     if (state.format === "json") {