settld 0.1.2 → 0.2.0

package/scripts/test/check-no-generated-artifacts.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/../.."
+
+bad="$(git ls-files -z -- '*.pyc' '**/__pycache__/**' '.venv/**' | tr '\0' '\n' | sed '/^$/d' || true)"
+if [[ -n "$bad" ]]; then
+  echo "generated artifacts are tracked in git (must be removed):" >&2
+  echo "$bad" >&2
+  exit 1
+fi
+

package/scripts/test/run.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/../.."
+
+PROBLEM_TESTS=(
+  "test/api-e2e-x402-authorize-payment.test.js"
+  "test/api-python-sdk-first-paid-task-smoke.test.js"
+  "test/api-python-sdk-first-verified-run-smoke.test.js"
+  "test/magic-link-onboarding-live-contract.test.js"
+  "test/magic-link-service.test.js"
+  "test/mcp-http-gateway.test.js"
+  "test/mcp-stdio-spike.test.js"
+  "test/payment-triggers.test.js"
+  "test/sdk-tenant-analytics-examples-smoke.test.js"
+  "test/trust-config-wizard-cli.test.js"
+)
+
+NOO_REGRESSION_TEST_FILE="test/api-e2e-x402-authorize-payment.test.js"
+REQUIRED_NOO_REGRESSION_TESTS=(
+  "API e2e: x402 authorize-payment and verify fail closed on missing or revoked passport when required"
+  "API e2e: x402 authorize-payment requires valid execution intent when enabled"
+  "API e2e: verify enforces strict request binding evidence for quote-bound authorization"
+)
+
+for test_name in "${REQUIRED_NOO_REGRESSION_TESTS[@]}"; do
+  if ! grep -F "test(\"${test_name}\"" "$NOO_REGRESSION_TEST_FILE" >/dev/null; then
+    echo "missing required NOO regression test: ${test_name}" >&2
+    exit 1
+  fi
+done
+
+SAFE_TESTS=()
+for fp in $(ls test/*.test.js | sort); do
+  is_problem_test=0
+  for problem in "${PROBLEM_TESTS[@]}"; do
+    if [[ "$fp" == "$problem" ]]; then
+      is_problem_test=1
+      break
+    fi
+  done
+  if [[ "$is_problem_test" -eq 0 ]]; then
+    SAFE_TESTS+=("$fp")
+  fi
+done
+
+# Phase 1: bulk suite (fast).
+# NOTE: These files sporadically fail when executed *after* a large multi-file
+# `node --test` run (Node 18 test runner multi-file mode), while they pass when
+# run first in a fresh process. Running them first keeps `npm test` stable.
+for fp in "${PROBLEM_TESTS[@]}"; do
+  node --test "$fp"
+done
+
+# Phase 2: bulk suite (fast).
+node --test "${SAFE_TESTS[@]}"
+
+# Post-check: ensure we never accidentally track generated artifacts.
+bash scripts/test/check-no-generated-artifacts.sh

package/scripts/trust/validate-trust-file.mjs

@@ -0,0 +1,57 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+
+function usage() {
+  fsSync.writeFileSync(2, "usage: node scripts/trust/validate-trust-file.mjs <trust.json>\n");
+  process.exit(2);
+}
+
+function isPlainObject(v) {
+  return Boolean(v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+}
+
+function validateKeyMap(map, label) {
+  if (map === undefined || map === null) return { ok: true, keys: 0 };
+  if (!isPlainObject(map)) return { ok: false, error: `${label} must be an object mapping keyId -> publicKeyPem` };
+  for (const [k, v] of Object.entries(map)) {
+    if (typeof k !== "string" || !k.trim()) return { ok: false, error: `${label} has an invalid keyId` };
+    if (typeof v !== "string" || !v.trim()) return { ok: false, error: `${label}[${k}] must be a non-empty PEM string` };
+    // Best-effort sanity check (format may evolve, but we at least reject obvious garbage).
+    if (!v.includes("BEGIN PUBLIC KEY") || !v.includes("END PUBLIC KEY")) return { ok: false, error: `${label}[${k}] does not look like a public key PEM` };
+  }
+  return { ok: true, keys: Object.keys(map).length };
+}
+
+async function main() {
+  const fp = process.argv[2] ?? null;
+  if (!fp || fp === "--help" || fp === "-h") usage();
+  const abs = path.resolve(process.cwd(), fp);
+  const raw = await fs.readFile(abs, "utf8");
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    fsSync.writeFileSync(2, `invalid JSON: ${err?.message ?? String(err ?? "")}\n`);
+    process.exit(2);
+  }
+  if (!isPlainObject(json)) {
+    fsSync.writeFileSync(2, "trust.json must be an object\n");
+    process.exit(2);
+  }
+
+  const gov = validateKeyMap(json.governanceRoots, "governanceRoots");
+  if (!gov.ok) {
+    fsSync.writeFileSync(2, String(gov.error ?? "invalid governanceRoots") + "\n");
+    process.exit(2);
+  }
+  const time = validateKeyMap(json.timeAuthorities, "timeAuthorities");
+  if (!time.ok) {
+    fsSync.writeFileSync(2, String(time.error ?? "invalid timeAuthorities") + "\n");
+    process.exit(2);
+  }
+
+  fsSync.writeFileSync(1, `ok governanceRoots=${gov.keys} timeAuthorities=${time.keys}\n`);
+}
+
+await main();

package/scripts/trust-config/rotate-settld-pay.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { createEd25519Keypair, keyIdFromPublicKeyPem } from "../../src/core/crypto.js";
+import { buildSettldPayKeysetV1 } from "../../src/core/settld-keys.js";
+
+const SERVER_SIGNER_FILENAME = "server-signer.json";
+const SETTLD_PAY_KEYSET_STORE_FILENAME = "settld-pay-keyset-store.json";
+
+function usage() {
+  return [
+    "Usage:",
+    "  node scripts/trust-config/rotate-settld-pay.mjs [--data-dir <path>] [--report <path>] [--keep-previous <n>] [--bootstrap]",
+    "",
+    "Options:",
+    "  --data-dir <path>      Data directory containing signer material (default: $PROXY_DATA_DIR or ./data)",
+    "  --report <path>        Optional JSON artifact path for rotation report",
+    "  --keep-previous <n>    Number of previous public keys to keep published (default: 2)",
+    "  --bootstrap            Allow creating an initial signer if no existing signer is found",
+    "  --help                 Show this help"
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const out = {
+    dataDir: process.env.PROXY_DATA_DIR && String(process.env.PROXY_DATA_DIR).trim() !== "" ? String(process.env.PROXY_DATA_DIR).trim() : "data",
+    reportPath: null,
+    keepPrevious: 2,
+    bootstrap: false
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = String(argv[i] ?? "");
+    if (a === "--help" || a === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (a === "--bootstrap") {
+      out.bootstrap = true;
+      continue;
+    }
+    if (a === "--data-dir") {
+      const value = argv[i + 1];
+      if (!value) throw new Error("--data-dir requires a value");
+      out.dataDir = String(value);
+      i += 1;
+      continue;
+    }
+    if (a === "--report") {
+      const value = argv[i + 1];
+      if (!value) throw new Error("--report requires a value");
+      out.reportPath = String(value);
+      i += 1;
+      continue;
+    }
+    if (a === "--keep-previous") {
+      const value = Number(argv[i + 1]);
+      if (!Number.isSafeInteger(value) || value < 0) throw new Error("--keep-previous must be a non-negative integer");
+      out.keepPrevious = value;
+      i += 1;
+      continue;
+    }
+    throw new Error(`unknown argument: ${a}`);
+  }
+  return out;
+}
+
+function normalizeKeyRow(row, { requirePrivate = false, fieldPath = "key" } = {}) {
+  if (!row || typeof row !== "object" || Array.isArray(row)) throw new Error(`${fieldPath} must be an object`);
+  const publicKeyPem = typeof row.publicKeyPem === "string" && row.publicKeyPem.trim() !== "" ? row.publicKeyPem : null;
+  if (!publicKeyPem) throw new Error(`${fieldPath}.publicKeyPem is required`);
+  const privateKeyPem = typeof row.privateKeyPem === "string" && row.privateKeyPem.trim() !== "" ? row.privateKeyPem : null;
+  if (requirePrivate && !privateKeyPem) throw new Error(`${fieldPath}.privateKeyPem is required`);
+  const derivedKeyId = keyIdFromPublicKeyPem(publicKeyPem);
+  const keyId = typeof row.keyId === "string" && row.keyId.trim() !== "" ? row.keyId.trim() : derivedKeyId;
+  if (keyId !== derivedKeyId) throw new Error(`${fieldPath}.keyId does not match publicKeyPem`);
+  return {
+    keyId,
+    publicKeyPem,
+    privateKeyPem,
+    rotatedAt: typeof row.rotatedAt === "string" && row.rotatedAt.trim() !== "" ? row.rotatedAt : null
+  };
+}
+
+function dedupePrevious(rows, { max = 2 } = {}) {
+  const out = [];
+  const seen = new Set();
+  for (const row of rows) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    const normalized = normalizeKeyRow(row, { requirePrivate: false, fieldPath: "previous[]" });
+    if (seen.has(normalized.keyId)) continue;
+    seen.add(normalized.keyId);
+    out.push({
+      keyId: normalized.keyId,
+      publicKeyPem: normalized.publicKeyPem,
+      rotatedAt: normalized.rotatedAt
+    });
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+async function readJsonFileSafe(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const raw = await readFile(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+async function loadSignerMaterial({ dataDir }) {
+  const keysetStorePath = path.join(dataDir, SETTLD_PAY_KEYSET_STORE_FILENAME);
+  const signerPath = path.join(dataDir, SERVER_SIGNER_FILENAME);
+  const keysetStore = await readJsonFileSafe(keysetStorePath);
+  if (keysetStore) {
+    const active = normalizeKeyRow(keysetStore.active, { requirePrivate: true, fieldPath: "active" });
+    const previous = Array.isArray(keysetStore.previous)
+      ? keysetStore.previous.map((row, idx) => normalizeKeyRow(row, { requirePrivate: false, fieldPath: `previous[${idx}]` }))
+      : [];
+    return {
+      source: "keyset-store",
+      active,
+      previous
+    };
+  }
+
+  const signer = await readJsonFileSafe(signerPath);
+  if (signer) {
+    const active = normalizeKeyRow(signer, { requirePrivate: true, fieldPath: "server-signer" });
+    return { source: "legacy-signer", active, previous: [] };
+  }
+
+  return null;
+}
+
+function buildProviderNotificationSnippet({
+  keysetUrl = "https://<your-settld-host>/.well-known/settld-keys.json",
+  newKeyId,
+  previousKeyIds,
+  overlapRecommendation
+} = {}) {
+  const previous = Array.isArray(previousKeyIds) && previousKeyIds.length > 0 ? previousKeyIds.join(", ") : "none";
+  return [
+    "Subject: SettldPay signing key rotation notice",
+    "",
+    `Settld has rotated its SettldPay signing key.`,
+    `- New active kid: ${newKeyId}`,
+    `- Previous kids still published: ${previous}`,
+    `- Keyset URL: ${keysetUrl}`,
+    "",
+    "Action requested:",
+    "1. Keep verifying tokens by resolving kid from the keyset URL.",
+    "2. Refresh cached keyset according to Cache-Control (or immediately if pinned).",
+    `3. Do not remove previously cached keys before overlap window ends (${overlapRecommendation}).`
+  ].join("\n");
+}
+
+async function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`${err?.message ?? String(err)}\n\n${usage()}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (args.help) {
+    process.stdout.write(usage() + "\n");
+    return;
+  }
+
+  const dataDir = path.resolve(process.cwd(), args.dataDir);
+  await mkdir(dataDir, { recursive: true });
+
+  const existing = await loadSignerMaterial({ dataDir });
+  if (!existing && !args.bootstrap) {
+    throw new Error(
+      `no existing signer found in ${dataDir}; rerun with --bootstrap to create the initial signer and keyset store`
+    );
+  }
+
+  const nowIso = new Date().toISOString();
+  const newKeypair = createEd25519Keypair();
+  const newKeyId = keyIdFromPublicKeyPem(newKeypair.publicKeyPem);
+  const oldActive = existing?.active ?? null;
+
+  const previousRows = dedupePrevious(
+    [
+      ...(oldActive
+        ? [
+            {
+              keyId: oldActive.keyId,
+              publicKeyPem: oldActive.publicKeyPem,
+              rotatedAt: nowIso
+            }
+          ]
+        : []),
+      ...(existing?.previous ?? [])
+    ],
+    { max: args.keepPrevious }
+  );
+
+  const keysetStore = {
+    schemaVersion: "SettldPayKeysetStore.v1",
+    updatedAt: nowIso,
+    active: {
+      keyId: newKeyId,
+      publicKeyPem: newKeypair.publicKeyPem,
+      privateKeyPem: newKeypair.privateKeyPem,
+      rotatedFromKeyId: oldActive?.keyId ?? null
+    },
+    previous: previousRows
+  };
+
+  const signerCompat = {
+    publicKeyPem: newKeypair.publicKeyPem,
+    privateKeyPem: newKeypair.privateKeyPem
+  };
+
+  const keysetStorePath = path.join(dataDir, SETTLD_PAY_KEYSET_STORE_FILENAME);
+  const signerPath = path.join(dataDir, SERVER_SIGNER_FILENAME);
+  await writeFile(keysetStorePath, JSON.stringify(keysetStore, null, 2) + "\n", "utf8");
+  await writeFile(signerPath, JSON.stringify(signerCompat, null, 2) + "\n", "utf8");
+
+  const servedKeyset = buildSettldPayKeysetV1({
+    activeKey: { keyId: newKeyId, publicKeyPem: newKeypair.publicKeyPem },
+    fallbackKeys: previousRows.map((row) => ({ keyId: row.keyId, publicKeyPem: row.publicKeyPem })),
+    refreshedAt: nowIso
+  });
+  const activeJwksEntry = Array.isArray(servedKeyset.keys) ? servedKeyset.keys.find((row) => row.kid === newKeyId) : null;
+  const notification = buildProviderNotificationSnippet({
+    newKeyId,
+    previousKeyIds: previousRows.map((row) => row.keyId),
+    overlapRecommendation: "token TTL + cache max-age safety margin"
+  });
+
+  const report = {
+    schemaVersion: "SettldPayKeyRotationReport.v1",
+    rotatedAt: nowIso,
+    dataDir,
+    source: existing?.source ?? "bootstrap",
+    oldActiveKeyId: oldActive?.keyId ?? null,
+    newActiveKeyId: newKeyId,
+    previousKeyIds: previousRows.map((row) => row.keyId),
+    files: {
+      keysetStorePath,
+      signerCompatPath: signerPath
+    },
+    servedKeyset
+  };
+
+  if (args.reportPath) {
+    const reportPath = path.resolve(process.cwd(), args.reportPath);
+    await mkdir(path.dirname(reportPath), { recursive: true });
+    await writeFile(reportPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+    report.reportPath = reportPath;
+  }
+
+  process.stdout.write(`rotated_at=${nowIso}\n`);
+  process.stdout.write(`data_dir=${dataDir}\n`);
+  process.stdout.write(`old_active_kid=${oldActive?.keyId ?? "none"}\n`);
+  process.stdout.write(`new_active_kid=${newKeyId}\n`);
+  process.stdout.write(`previous_kids=${previousRows.map((row) => row.keyId).join(",") || "none"}\n`);
+  process.stdout.write("\nJWKS active entry:\n");
+  process.stdout.write(JSON.stringify(activeJwksEntry ?? null, null, 2) + "\n");
+  process.stdout.write("\nProvider notification snippet:\n");
+  process.stdout.write(notification + "\n");
+  if (report.reportPath) {
+    process.stdout.write(`\nrotation_report=${report.reportPath}\n`);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(err)}\n`);
+  process.exitCode = 1;
+});

package/scripts/trust-config/wizard.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+
+import {
+  SLA_POLICY_TEMPLATE_CATALOG_VERSION,
+  getSlaPolicyTemplate,
+  listSlaPolicyTemplates,
+  renderSlaPolicyTemplate
+} from "../../src/core/sla-policy-templates.js";
+
+function usage() {
+  const text = [
+    "usage:",
+    "  node scripts/trust-config/wizard.mjs list [--vertical delivery|security] [--format json|text]",
+    "  node scripts/trust-config/wizard.mjs show --template <templateId> [--format json|text]",
+    "  node scripts/trust-config/wizard.mjs render --template <templateId> [--overrides-json <json>] [--out <path>] [--format json|text]",
+    "  node scripts/trust-config/wizard.mjs validate --template <templateId> [--overrides-json <json>] [--format json|text]"
+  ].join("\n");
+  process.stderr.write(text + "\n");
+}
+
+function parseArgs(argv) {
+  const out = {
+    command: argv[0] ?? null,
+    templateId: null,
+    vertical: null,
+    overridesJson: null,
+    outPath: null,
+    format: "json"
+  };
+  for (let i = 1; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--template") {
+      out.templateId = String(argv[i + 1] ?? "");
+      i += 1;
+      continue;
+    }
+    if (arg === "--vertical") {
+      out.vertical = String(argv[i + 1] ?? "");
+      i += 1;
+      continue;
+    }
+    if (arg === "--overrides-json") {
+      out.overridesJson = String(argv[i + 1] ?? "");
+      i += 1;
+      continue;
+    }
+    if (arg === "--out") {
+      out.outPath = String(argv[i + 1] ?? "");
+      i += 1;
+      continue;
+    }
+    if (arg === "--format") {
+      out.format = String(argv[i + 1] ?? "").trim().toLowerCase();
+      i += 1;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      usage();
+      process.exit(0);
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!out.command) throw new Error("command is required");
+  if (out.format !== "json" && out.format !== "text") throw new Error("format must be json or text");
+  return out;
+}
+
+function parseOverrides(overridesJson) {
+  if (!overridesJson || !String(overridesJson).trim()) return null;
+  try {
+    return JSON.parse(String(overridesJson));
+  } catch (err) {
+    throw new Error(`invalid --overrides-json: ${err?.message ?? "parse failed"}`);
+  }
+}
+
+function renderTextList(templates) {
+  const lines = [];
+  for (const template of templates) {
+    lines.push(`${template.templateId}\t${template.vertical}\t${template.name}`);
+  }
+  return lines.join("\n") + (lines.length ? "\n" : "");
+}
+
+function renderTextShow(template) {
+  return [
+    `templateId: ${template.templateId}`,
+    `vertical: ${template.vertical}`,
+    `name: ${template.name}`,
+    `description: ${template.description}`
+  ].join("\n") + "\n";
+}
+
+async function output({ format, payload, text, outPath }) {
+  const body = format === "json" ? JSON.stringify(payload, null, 2) + "\n" : text;
+  if (outPath) {
+    await fs.writeFile(outPath, body, "utf8");
+    return;
+  }
+  process.stdout.write(body);
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    usage();
+    process.stderr.write(`${err?.message ?? "invalid arguments"}\n`);
+    process.exit(2);
+  }
+
+  const overrides = parseOverrides(parsed.overridesJson);
+
+  if (parsed.command === "list") {
+    const templates = listSlaPolicyTemplates({ vertical: parsed.vertical });
+    const payload = { schemaVersion: SLA_POLICY_TEMPLATE_CATALOG_VERSION, templates };
+    await output({ format: parsed.format, payload, text: renderTextList(templates), outPath: parsed.outPath });
+    return;
+  }
+
+  if (parsed.command === "show") {
+    if (!parsed.templateId) throw new Error("--template is required for show");
+    const template = getSlaPolicyTemplate({ templateId: parsed.templateId });
+    if (!template) throw new Error("template not found");
+    await output({ format: parsed.format, payload: template, text: renderTextShow(template), outPath: parsed.outPath });
+    return;
+  }
+
+  if (parsed.command === "render") {
+    if (!parsed.templateId) throw new Error("--template is required for render");
+    const rendered = renderSlaPolicyTemplate({ templateId: parsed.templateId, overrides });
+    if (!rendered) throw new Error("template not found");
+    const payload = {
+      schemaVersion: "SettldTrustWizardOutput.v1",
+      templateId: rendered.templateId,
+      config: rendered.defaults
+    };
+    const text = JSON.stringify(payload.config, null, 2) + "\n";
+    await output({ format: parsed.format, payload, text, outPath: parsed.outPath });
+    return;
+  }
+
+  if (parsed.command === "validate") {
+    if (!parsed.templateId) throw new Error("--template is required for validate");
+    const rendered = renderSlaPolicyTemplate({ templateId: parsed.templateId, overrides });
+    if (!rendered) throw new Error("template not found");
+    const payload = { ok: true, templateId: rendered.templateId };
+    const text = "ok\n";
+    await output({ format: parsed.format, payload, text, outPath: parsed.outPath });
+    return;
+  }
+
+  throw new Error(`unsupported command: ${parsed.command}`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.message ?? "error"}\n`);
+  process.exit(1);
+});