settld 0.1.5 → 0.2.0

package/scripts/slo/check.mjs

@@ -1,33 +1,43 @@
 import assert from "node:assert/strict";
 import fs from "node:fs/promises";
 
-const API_BASE_URL = process.env.SLO_API_BASE_URL ?? "http://127.0.0.1:3000";
-const METRICS_PATH = process.env.SLO_METRICS_PATH ?? "/metrics";
-const METRICS_FILE = process.env.SLO_METRICS_FILE ?? null;
+const SLO_CHECK_SCHEMA_VERSION = "OperationalSloCheck.v1";
 
-const MAX_HTTP_5XX_TOTAL = Number(process.env.SLO_MAX_HTTP_5XX_TOTAL ?? "0");
-const MAX_OUTBOX_PENDING = Number(process.env.SLO_MAX_OUTBOX_PENDING ?? "200");
-const MAX_DELIVERY_DLQ = Number(process.env.SLO_MAX_DELIVERY_DLQ ?? "0");
-const MAX_DELIVERIES_PENDING = Number(process.env.SLO_MAX_DELIVERIES_PENDING ?? "0");
-const MAX_DELIVERIES_FAILED = Number(process.env.SLO_MAX_DELIVERIES_FAILED ?? "0");
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
 
-function assertFiniteNumber(n, name) {
+export function assertFiniteNumber(n, name) {
   if (!Number.isFinite(n)) throw new TypeError(`${name} must be finite`);
 }
 
-for (const [k, v] of [
-  ["SLO_MAX_HTTP_5XX_TOTAL", MAX_HTTP_5XX_TOTAL],
-  ["SLO_MAX_OUTBOX_PENDING", MAX_OUTBOX_PENDING],
-  ["SLO_MAX_DELIVERY_DLQ", MAX_DELIVERY_DLQ],
-  ["SLO_MAX_DELIVERIES_PENDING", MAX_DELIVERIES_PENDING],
-  ["SLO_MAX_DELIVERIES_FAILED", MAX_DELIVERIES_FAILED]
-]) {
-  assertFiniteNumber(v, k);
-  if (v < 0) throw new TypeError(`${k} must be >= 0`);
+export function parseSloThresholds(env = process.env) {
+  return {
+    maxHttp5xxTotal: Number(env.SLO_MAX_HTTP_5XX_TOTAL ?? "0"),
+    maxOutboxPending: Number(env.SLO_MAX_OUTBOX_PENDING ?? "200"),
+    maxDeliveryDlq: Number(env.SLO_MAX_DELIVERY_DLQ ?? "0"),
+    maxDeliveriesPending: Number(env.SLO_MAX_DELIVERIES_PENDING ?? "0"),
+    maxDeliveriesFailed: Number(env.SLO_MAX_DELIVERIES_FAILED ?? "0")
+  };
+}
+
+export function validateSloThresholds(thresholds) {
+  for (const [k, v] of [
+    ["SLO_MAX_HTTP_5XX_TOTAL", thresholds.maxHttp5xxTotal],
+    ["SLO_MAX_OUTBOX_PENDING", thresholds.maxOutboxPending],
+    ["SLO_MAX_DELIVERY_DLQ", thresholds.maxDeliveryDlq],
+    ["SLO_MAX_DELIVERIES_PENDING", thresholds.maxDeliveriesPending],
+    ["SLO_MAX_DELIVERIES_FAILED", thresholds.maxDeliveriesFailed]
+  ]) {
+    assertFiniteNumber(v, k);
+    if (v < 0) throw new TypeError(`${k} must be >= 0`);
+  }
 }
 
 function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 async function fetchTextWithTimeout(url, timeoutMs = 5000) {
@@ -43,7 +53,6 @@ async function fetchTextWithTimeout(url, timeoutMs = 5000) {
 }
 
 function unescapeLabelValue(value) {
-  // Prometheus exposition escaping.
   return String(value).replaceAll("\\\\", "\\").replaceAll("\\n", "\n").replaceAll('\\"', '"');
 }
 
@@ -94,13 +103,12 @@ function parseLabels(src) {
   return labels;
 }
 
-function parsePrometheusText(text) {
+export function parsePrometheusText(text) {
   const series = [];
   const lines = String(text ?? "").split("\n");
   for (const lineRaw of lines) {
     const line = lineRaw.trim();
     if (!line || line.startsWith("#")) continue;
-    // name{labels} value
     const m = /^([a-zA-Z_:][a-zA-Z0-9_:]*)(\{[^}]*\})?\s+([-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?|NaN|Inf|-Inf)\s*$/.exec(line);
     if (!m) continue;
     const name = m[1];
@@ -112,67 +120,120 @@ function parsePrometheusText(text) {
   return series;
 }
 
-function sumWhere(series, { name, where = () => true } = {}) {
+export function sumWhere(series, { name, where = () => true } = {}) {
   let sum = 0;
-  for (const s of series) {
-    if (s.name !== name) continue;
-    if (!where(s.labels, s.value)) continue;
-    const v = Number(s.value);
-    if (!Number.isFinite(v)) continue;
-    sum += v;
+  for (const sample of series) {
+    if (sample.name !== name) continue;
+    if (!where(sample.labels, sample.value)) continue;
+    const value = Number(sample.value);
+    if (!Number.isFinite(value)) continue;
+    sum += value;
   }
   return sum;
 }
 
-function getOne(series, { name, where = () => true } = {}) {
-  for (const s of series) {
-    if (s.name !== name) continue;
-    if (!where(s.labels, s.value)) continue;
-    return Number(s.value);
+export function getOne(series, { name, where = () => true } = {}) {
+  for (const sample of series) {
+    if (sample.name !== name) continue;
+    if (!where(sample.labels, sample.value)) continue;
+    return Number(sample.value);
   }
   return null;
 }
 
-async function main() {
-  let metricsText;
-  if (METRICS_FILE) {
-    metricsText = await fs.readFile(METRICS_FILE, "utf8");
-  } else {
-    // Give the server a moment to flush post-lifecycle gauges.
-    await sleep(250);
-    const r = await fetchTextWithTimeout(`${API_BASE_URL}${METRICS_PATH}`, 10_000);
-    assert.equal(r.status, 200, `GET ${METRICS_PATH} failed: http ${r.status}`);
-    metricsText = r.text;
-  }
-
-  const series = parsePrometheusText(metricsText);
-
+export function collectOperationalSloSummary(series) {
   const http5xxTotal = sumWhere(series, {
     name: "http_requests_total",
     where: (labels) => typeof labels.status === "string" && labels.status.startsWith("5")
   });
-
   const outboxPending = sumWhere(series, { name: "outbox_pending_gauge" });
-  const deliveryDlq = getOne(series, { name: "delivery_dlq_pending_total_gauge" }) ?? 0;
-  const deliveriesPending = getOne(series, { name: "deliveries_pending_gauge", where: (l) => l.state === "pending" }) ?? 0;
-  const deliveriesFailed = getOne(series, { name: "deliveries_pending_gauge", where: (l) => l.state === "failed" }) ?? 0;
-
-  const summary = {
+  const deliveryDlq = sumWhere(series, { name: "delivery_dlq_pending_total_gauge" });
+  const deliveriesPending = sumWhere(series, {
+    name: "deliveries_pending_gauge",
+    where: (labels) => labels.state === "pending"
+  });
+  const deliveriesFailed = sumWhere(series, {
+    name: "deliveries_pending_gauge",
+    where: (labels) => labels.state === "failed"
+  });
+  return {
     http5xxTotal,
     outboxPending,
     deliveryDlq,
     deliveriesPending,
     deliveriesFailed
   };
-  // Single-line JSON for CI logs.
-  console.log(JSON.stringify({ slo: summary }));
+}
 
-  assert.ok(http5xxTotal <= MAX_HTTP_5XX_TOTAL, `SLO breach: http 5xx total ${http5xxTotal} > ${MAX_HTTP_5XX_TOTAL}`);
-  assert.ok(outboxPending <= MAX_OUTBOX_PENDING, `SLO breach: outbox pending ${outboxPending} > ${MAX_OUTBOX_PENDING}`);
-  assert.ok(deliveryDlq <= MAX_DELIVERY_DLQ, `SLO breach: delivery DLQ ${deliveryDlq} > ${MAX_DELIVERY_DLQ}`);
-  assert.ok(deliveriesPending <= MAX_DELIVERIES_PENDING, `SLO breach: deliveries pending ${deliveriesPending} > ${MAX_DELIVERIES_PENDING}`);
-  assert.ok(deliveriesFailed <= MAX_DELIVERIES_FAILED, `SLO breach: deliveries failed ${deliveriesFailed} > ${MAX_DELIVERIES_FAILED}`);
+export function assertOperationalSlo(summary, thresholds) {
+  assert.ok(
+    summary.http5xxTotal <= thresholds.maxHttp5xxTotal,
+    `SLO breach: http 5xx total ${summary.http5xxTotal} > ${thresholds.maxHttp5xxTotal}`
+  );
+  assert.ok(
+    summary.outboxPending <= thresholds.maxOutboxPending,
+    `SLO breach: outbox pending ${summary.outboxPending} > ${thresholds.maxOutboxPending}`
+  );
+  assert.ok(
+    summary.deliveryDlq <= thresholds.maxDeliveryDlq,
+    `SLO breach: delivery DLQ ${summary.deliveryDlq} > ${thresholds.maxDeliveryDlq}`
+  );
+  assert.ok(
+    summary.deliveriesPending <= thresholds.maxDeliveriesPending,
+    `SLO breach: deliveries pending ${summary.deliveriesPending} > ${thresholds.maxDeliveriesPending}`
+  );
+  assert.ok(
+    summary.deliveriesFailed <= thresholds.maxDeliveriesFailed,
+    `SLO breach: deliveries failed ${summary.deliveriesFailed} > ${thresholds.maxDeliveriesFailed}`
+  );
 }
 
-await main();
+export async function loadMetricsText({
+  metricsFile = null,
+  apiBaseUrl = "http://127.0.0.1:3000",
+  metricsPath = "/metrics",
+  flushDelayMs = 250
+} = {}) {
+  if (metricsFile) {
+    return await fs.readFile(metricsFile, "utf8");
+  }
+  await sleep(flushDelayMs);
+  const response = await fetchTextWithTimeout(`${apiBaseUrl}${metricsPath}`, 10_000);
+  assert.equal(response.status, 200, `GET ${metricsPath} failed: http ${response.status}`);
+  return response.text;
+}
+
+export async function runSloCheck({ env = process.env } = {}) {
+  const thresholds = parseSloThresholds(env);
+  validateSloThresholds(thresholds);
+  const metricsFile = normalizeOptionalString(env.SLO_METRICS_FILE);
+  const metricsText = await loadMetricsText({
+    metricsFile,
+    apiBaseUrl: env.SLO_API_BASE_URL ?? "http://127.0.0.1:3000",
+    metricsPath: env.SLO_METRICS_PATH ?? "/metrics"
+  });
+  const series = parsePrometheusText(metricsText);
+  const summary = collectOperationalSloSummary(series);
+  assertOperationalSlo(summary, thresholds);
+  return summary;
+}
+
+async function main() {
+  const summary = await runSloCheck({ env: process.env });
+  console.log(JSON.stringify({ schemaVersion: SLO_CHECK_SCHEMA_VERSION, slo: summary }));
+}
 
+const isDirectExecution = (() => {
+  try {
+    return import.meta.url === new URL(`file://${process.argv[1]}`).href;
+  } catch {
+    return false;
+  }
+})();
+
+if (isDirectExecution) {
+  main().catch((err) => {
+    process.stderr.write(`${err?.stack ?? err?.message ?? String(err)}\n`);
+    process.exit(1);
+  });
+}

package/scripts/spec/generate-protocol-vectors.mjs

@@ -22,6 +22,8 @@ import { buildDisputeOpenEnvelopeV1 } from "../../src/core/dispute-open-envelope
 import { buildAgreementDelegationV1 } from "../../src/core/agreement-delegation.js";
 import { buildToolCallAgreementV1 } from "../../src/core/tool-call-agreement.js";
 import { buildToolCallEvidenceV1 } from "../../src/core/tool-call-evidence.js";
+import { buildPolicyDecisionV1 } from "../../src/core/policy-decision.js";
+import { computeOperatorActionHashV1, signOperatorActionV1 } from "../../src/core/operator-action.js";
 
 function bytes(text) {
   return new TextEncoder().encode(text);
@@ -499,6 +501,7 @@ async function main() {
     decisionReason: null,
     verificationStatus: "green",
     policyHashUsed: "3".repeat(64),
+    profileHashUsed: "a".repeat(64),
     verificationMethodHashUsed: "4".repeat(64),
     policyRef: {
       policyHash: "3".repeat(64),
@@ -518,6 +521,70 @@ async function main() {
   });
   const settlementDecisionRecordV2Canonical = canonicalJsonStringify(settlementDecisionRecordV2);
 
+  const policyDecision = buildPolicyDecisionV1({
+    decisionId: "pdec_run_vectors_0001_auto",
+    tenantId,
+    runId: agentRun.runId,
+    settlementId: agentRunSettlement.settlementId,
+    gateId: "gate_vectors_0001",
+    policyInput: {
+      policyId: "policy_vectors_0001",
+      policyVersion: 1
+    },
+    policyHashUsed: "3".repeat(64),
+    verificationMethodHashUsed: "4".repeat(64),
+    policyDecision: {
+      decisionMode: "automatic",
+      verificationStatus: "green",
+      runStatus: "completed",
+      shouldAutoResolve: true,
+      settlementStatus: "released",
+      releaseRatePct: 100,
+      releaseAmountCents: 1250,
+      refundAmountCents: 0,
+      reasonCodes: []
+    },
+    createdAt: "2026-02-01T00:02:00.000Z",
+    signerKeyId: keyId,
+    signerPrivateKeyPem: privateKeyPem
+  });
+  const policyDecisionCanonical = canonicalJsonStringify(policyDecision);
+
+  const operatorActionCore = {
+    schemaVersion: "OperatorAction.v1",
+    actionId: "opact_vectors_0001",
+    caseRef: {
+      kind: "dispute",
+      caseId: "dsp_run_vectors_0001"
+    },
+    action: "OVERRIDE_ALLOW",
+    justificationCode: "OPS_OVERRIDE_APPROVED",
+    justification: "vector override approved",
+    actor: {
+      operatorId: "op_vectors_0001",
+      role: "incident_commander",
+      tenantId,
+      sessionId: "ops_session_vectors_01",
+      metadata: {
+        source: "ops-console",
+        ticketId: "INC-VECTORS-1"
+      }
+    },
+    actedAt: "2026-02-01T00:02:10.000Z",
+    metadata: {
+      severity: "critical",
+      checklist: ["evidence-reviewed", "lead-approved"]
+    }
+  };
+  const operatorAction = signOperatorActionV1({
+    action: operatorActionCore,
+    signedAt: "2026-02-01T00:02:11.000Z",
+    publicKeyPem,
+    privateKeyPem
+  });
+  const operatorActionCanonical = canonicalJsonStringify(operatorAction);
+  const operatorActionCoreCanonical = canonicalJsonStringify(operatorActionCore);
+
   const settlementReceipt = buildSettlementReceipt({
     receiptId: "rcpt_run_vectors_0001_auto",
     tenantId,
@@ -843,6 +910,27 @@ async function main() {
       canonicalJson: settlementDecisionRecordV2Canonical,
       sha256: sha256Hex(settlementDecisionRecordV2Canonical)
     },
+    policyDecision: {
+      schemaVersion: policyDecision.schemaVersion,
+      decisionId: policyDecision.decisionId,
+      policyDecisionHash: policyDecision.policyDecisionHash,
+      evaluationHash: policyDecision.evaluationHash,
+      canonicalJson: policyDecisionCanonical,
+      sha256: sha256Hex(policyDecisionCanonical),
+      signatureKeyId: policyDecision.signature?.signerKeyId ?? null,
+      signature: policyDecision.signature?.signature ?? null
+    },
+    operatorAction: {
+      schemaVersion: operatorAction.schemaVersion,
+      actionId: operatorAction.actionId ?? null,
+      actionHash: operatorAction.signature?.actionHash ?? computeOperatorActionHashV1({ action: operatorActionCore }),
+      canonicalJson: operatorActionCanonical,
+      sha256: sha256Hex(operatorActionCanonical),
+      coreCanonicalJson: operatorActionCoreCanonical,
+      coreSha256: sha256Hex(operatorActionCoreCanonical),
+      signatureKeyId: operatorAction.signature?.keyId ?? null,
+      signature: operatorAction.signature?.signatureBase64 ?? null
+    },
     settlementReceipt: {
       schemaVersion: settlementReceipt.schemaVersion,
       receiptId: settlementReceipt.receiptId,

package/scripts/test/run.sh

@@ -4,6 +4,7 @@ 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"
@@ -15,19 +16,32 @@ PROBLEM_TESTS=(
   "test/trust-config-wizard-cli.test.js"
 )
 
-declare -A PROBLEM_SET=()
-for fp in "${PROBLEM_TESTS[@]}"; do
-  PROBLEM_SET["$fp"]=1
-done
+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"
+)
 
-mapfile -t ALL_TESTS < <(ls test/*.test.js | sort)
+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 "${ALL_TESTS[@]}"; do
-  if [[ -n "${PROBLEM_SET[$fp]+x}" ]]; then
-    continue
+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
-  SAFE_TESTS+=("$fp")
 done
 
 # Phase 1: bulk suite (fast).

package/services/x402-gateway/src/server.js

@@ -6,6 +6,7 @@ import { Readable } from "node:stream";
 import { parseX402PaymentRequired } from "../../../src/core/x402-gate.js";
 import { canonicalJsonStringify } from "../../../src/core/canonical-json.js";
 import { keyIdFromPublicKeyPem } from "../../../src/core/crypto.js";
+import { normalizeReasonCodes as normalizePolicyDecisionReasonCodes } from "../../../src/core/policy-decision.js";
 import { buildToolProviderQuotePayloadV1, verifyToolProviderQuoteSignatureV1 } from "../../../src/core/provider-quote-signature.js";
 import { computeSettldPayRequestBindingSha256V1 } from "../../../src/core/settld-pay-token.js";
 import { computeToolProviderSignaturePayloadHashV1, verifyToolProviderSignatureV1 } from "../../../src/core/tool-provider-signature.js";
@@ -225,6 +226,31 @@ function parseProviderQuoteHeaders(headers) {
   };
 }
 
+function parseAgentPassportHeader(headers) {
+  const rawHeader = headers?.["x-settld-agent-passport"] ?? headers?.["X-Settld-Agent-Passport"] ?? null;
+  const raw = typeof rawHeader === "string" ? rawHeader.trim() : Array.isArray(rawHeader) ? String(rawHeader[0] ?? "").trim() : "";
+  if (!raw) return { ok: true, agentPassport: null };
+  let text = null;
+  try {
+    if (raw.startsWith("{")) {
+      text = raw;
+    } else {
+      text = Buffer.from(raw, "base64url").toString("utf8");
+    }
+  } catch {
+    return { ok: false, message: "x-settld-agent-passport must be base64url JSON or raw JSON object" };
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { ok: false, message: "x-settld-agent-passport must decode to a JSON object" };
+    }
+    return { ok: true, agentPassport: parsed };
+  } catch {
+    return { ok: false, message: "x-settld-agent-passport is not valid JSON" };
+  }
+}
+
 async function verifyProviderQuoteChallenge({
   offerFields,
   amountCents,
@@ -435,6 +461,107 @@ async function settldJson(path, { tenantId, method, idempotencyKey = null, body
   return json;
 }
 
+function readDecisionRecordFromVerify(gateVerify) {
+  if (!gateVerify || typeof gateVerify !== "object" || Array.isArray(gateVerify)) return null;
+  const direct =
+    gateVerify.decisionRecord && typeof gateVerify.decisionRecord === "object" && !Array.isArray(gateVerify.decisionRecord)
+      ? gateVerify.decisionRecord
+      : null;
+  if (direct) return direct;
+  const fromTrace =
+    gateVerify?.settlement?.decisionTrace?.decisionRecord &&
+    typeof gateVerify.settlement.decisionTrace.decisionRecord === "object" &&
+    !Array.isArray(gateVerify.settlement.decisionTrace.decisionRecord)
+      ? gateVerify.settlement.decisionTrace.decisionRecord
+      : null;
+  return fromTrace;
+}
+
+function collectReasonCodesFromVerify(gateVerify) {
+  const fromGateDecision = Array.isArray(gateVerify?.gate?.decision?.reasonCodes) ? gateVerify.gate.decision.reasonCodes : [];
+  const fromDecision = Array.isArray(gateVerify?.decision?.reasonCodes) ? gateVerify.decision.reasonCodes : [];
+  return normalizePolicyDecisionReasonCodes([...fromGateDecision, ...fromDecision], "gateVerify.reasonCodes");
+}
+
+function derivePolicyDecisionFromVerify(gateVerify) {
+  const settlementStatus = String(gateVerify?.settlement?.status ?? "").trim().toLowerCase();
+  if (settlementStatus === "released") return "allow";
+  if (settlementStatus === "refunded") return "deny";
+  if (gateVerify?.decision?.shouldAutoResolve === false) return "challenge";
+  if (settlementStatus) return "escalate";
+  return null;
+}
+
+function applySettldDecisionHeaders(outHeaders, { gateId, gateVerify } = {}) {
+  if (gateId) outHeaders["x-settld-gate-id"] = gateId;
+  if (!gateVerify || typeof gateVerify !== "object" || Array.isArray(gateVerify)) return;
+
+  outHeaders["x-settld-settlement-status"] = String(gateVerify?.settlement?.status ?? "");
+  outHeaders["x-settld-released-amount-cents"] = String(gateVerify?.settlement?.releasedAmountCents ?? "");
+  outHeaders["x-settld-refunded-amount-cents"] = String(gateVerify?.settlement?.refundedAmountCents ?? "");
+
+  const verificationStatus = String(gateVerify?.gate?.decision?.verificationStatus ?? "").trim();
+  if (verificationStatus) outHeaders["x-settld-verification-status"] = verificationStatus;
+
+  const policyDecision = derivePolicyDecisionFromVerify(gateVerify);
+  if (policyDecision) outHeaders["x-settld-policy-decision"] = policyDecision;
+
+  const reasonCodes = collectReasonCodesFromVerify(gateVerify);
+  if (reasonCodes.length > 0) {
+    outHeaders["x-settld-verification-codes"] = reasonCodes.join(",");
+    outHeaders["x-settld-reason-code"] = reasonCodes[0];
+  } else if (policyDecision) {
+    const fallbackReasonCode =
+      policyDecision === "allow"
+        ? "POLICY_ALLOW"
+        : policyDecision === "deny"
+          ? "POLICY_DENY"
+          : policyDecision === "challenge"
+            ? "POLICY_CHALLENGE"
+            : "POLICY_ESCALATE";
+    outHeaders["x-settld-reason-code"] = fallbackReasonCode;
+  }
+
+  const decisionRecord = readDecisionRecordFromVerify(gateVerify);
+  const decisionId = typeof decisionRecord?.decisionId === "string" ? decisionRecord.decisionId.trim() : "";
+  if (decisionId) outHeaders["x-settld-decision-id"] = decisionId;
+
+  const policyHashRaw =
+    typeof decisionRecord?.policyHashUsed === "string" && decisionRecord.policyHashUsed.trim() !== ""
+      ? decisionRecord.policyHashUsed
+      : typeof decisionRecord?.policyRef?.policyHash === "string" && decisionRecord.policyRef.policyHash.trim() !== ""
+        ? decisionRecord.policyRef.policyHash
+        : null;
+  const policyHash = typeof policyHashRaw === "string" ? policyHashRaw.trim().toLowerCase() : "";
+  if (/^[0-9a-f]{64}$/.test(policyHash)) outHeaders["x-settld-policy-hash"] = policyHash;
+
+  const policyVersion = Number(decisionRecord?.bindings?.policyDecisionFingerprint?.policyVersion ?? Number.NaN);
+  if (Number.isSafeInteger(policyVersion) && policyVersion > 0) {
+    outHeaders["x-settld-policy-version"] = String(policyVersion);
+  }
+  const policyDecisionFingerprint =
+    decisionRecord?.bindings?.policyDecisionFingerprint &&
+    typeof decisionRecord.bindings.policyDecisionFingerprint === "object" &&
+    !Array.isArray(decisionRecord.bindings.policyDecisionFingerprint)
+      ? decisionRecord.bindings.policyDecisionFingerprint
+      : null;
+  const policyVerificationMethodHash =
+    typeof policyDecisionFingerprint?.verificationMethodHash === "string"
+      ? policyDecisionFingerprint.verificationMethodHash.trim().toLowerCase()
+      : "";
+  if (/^[0-9a-f]{64}$/.test(policyVerificationMethodHash)) {
+    outHeaders["x-settld-policy-verification-method-hash"] = policyVerificationMethodHash;
+  }
+  const policyEvaluationHash =
+    typeof policyDecisionFingerprint?.evaluationHash === "string" ? policyDecisionFingerprint.evaluationHash.trim().toLowerCase() : "";
+  if (/^[0-9a-f]{64}$/.test(policyEvaluationHash)) {
+    outHeaders["x-settld-policy-evaluation-hash"] = policyEvaluationHash;
+  }
+
+  if (gateVerify?.gate?.holdback?.status) outHeaders["x-settld-holdback-status"] = String(gateVerify.gate.holdback.status);
+  if (gateVerify?.gate?.holdback?.amountCents !== undefined) outHeaders["x-settld-holdback-amount-cents"] = String(gateVerify.gate.holdback.amountCents);
+}
+
 async function handleProxy(req, res) {
   const url = new URL(req.url ?? "/", "http://localhost");
   if (req.method === "GET" && url.pathname === "/healthz") {
@@ -445,10 +572,24 @@ async function handleProxy(req, res) {
 
   const tenantId = tenantIdForRequest(req);
   const upstreamUrl = new URL(url.pathname + url.search, UPSTREAM_URL);
+  const parsedAgentPassportHeader = parseAgentPassportHeader(req.headers);
+  if (!parsedAgentPassportHeader.ok) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    res.end(
+      JSON.stringify({
+        ok: false,
+        error: "invalid_agent_passport_header",
+        message: parsedAgentPassportHeader.message
+      })
+    );
+    return;
+  }
+  const requestAgentPassport = parsedAgentPassportHeader.agentPassport;
   const headers = new Headers();
   for (const [k, v] of Object.entries(req.headers)) {
     if (v === undefined) continue;
     if (k.toLowerCase() === "host") continue;
+    if (k.toLowerCase() === "x-settld-agent-passport") continue;
     if (Array.isArray(v)) headers.set(k, v.join(","));
     else headers.set(k, String(v));
   }
@@ -642,6 +783,7 @@ async function handleProxy(req, res) {
           holdbackBps: HOLDBACK_BPS,
           disputeWindowMs: DISPUTE_WINDOW_MS,
           ...(offeredToolId ? { toolId: offeredToolId } : {}),
+          ...(requestAgentPassport ? { agentPassport: requestAgentPassport } : {}),
           ...(X402_PROVIDER_PUBLIC_KEY_PEM ? { providerPublicKeyPem: X402_PROVIDER_PUBLIC_KEY_PEM } : {}),
           paymentRequiredHeader: { "x-payment-required": parsed.raw }
         }
@@ -696,18 +838,7 @@ async function handleProxy(req, res) {
       });
 
       const outHeaders = Object.fromEntries(upstreamRes.headers.entries());
-      outHeaders["x-settld-gate-id"] = gateId;
-      outHeaders["x-settld-settlement-status"] = String(gateVerify?.settlement?.status ?? "");
-      outHeaders["x-settld-released-amount-cents"] = String(gateVerify?.settlement?.releasedAmountCents ?? "");
-      outHeaders["x-settld-refunded-amount-cents"] = String(gateVerify?.settlement?.refundedAmountCents ?? "");
-      if (gateVerify?.gate?.decision?.verificationStatus) {
-        outHeaders["x-settld-verification-status"] = String(gateVerify.gate.decision.verificationStatus);
-      }
-      if (Array.isArray(gateVerify?.gate?.decision?.reasonCodes) && gateVerify.gate.decision.reasonCodes.length > 0) {
-        outHeaders["x-settld-verification-codes"] = gateVerify.gate.decision.reasonCodes.join(",");
-      }
-      if (gateVerify?.gate?.holdback?.status) outHeaders["x-settld-holdback-status"] = String(gateVerify.gate.holdback.status);
-      if (gateVerify?.gate?.holdback?.amountCents !== undefined) outHeaders["x-settld-holdback-amount-cents"] = String(gateVerify.gate.holdback.amountCents);
+      applySettldDecisionHeaders(outHeaders, { gateId, gateVerify });
 
       res.writeHead(502, outHeaders);
       res.end(`gateway: response too large to verify (>${2 * 1024 * 1024} bytes); refunded`);
@@ -853,19 +984,8 @@ async function handleProxy(req, res) {
     });
 
     const outHeaders = Object.fromEntries(upstreamRes.headers.entries());
-    outHeaders["x-settld-gate-id"] = gateId;
     outHeaders["x-settld-response-sha256"] = respHash;
-    outHeaders["x-settld-settlement-status"] = String(gateVerify?.settlement?.status ?? "");
-    outHeaders["x-settld-released-amount-cents"] = String(gateVerify?.settlement?.releasedAmountCents ?? "");
-    outHeaders["x-settld-refunded-amount-cents"] = String(gateVerify?.settlement?.refundedAmountCents ?? "");
-    if (gateVerify?.gate?.decision?.verificationStatus) {
-      outHeaders["x-settld-verification-status"] = String(gateVerify.gate.decision.verificationStatus);
-    }
-    if (Array.isArray(gateVerify?.gate?.decision?.reasonCodes) && gateVerify.gate.decision.reasonCodes.length > 0) {
-      outHeaders["x-settld-verification-codes"] = gateVerify.gate.decision.reasonCodes.join(",");
-    }
-    if (gateVerify?.gate?.holdback?.status) outHeaders["x-settld-holdback-status"] = String(gateVerify.gate.holdback.status);
-    if (gateVerify?.gate?.holdback?.amountCents !== undefined) outHeaders["x-settld-holdback-amount-cents"] = String(gateVerify.gate.holdback.amountCents);
+    applySettldDecisionHeaders(outHeaders, { gateId, gateVerify });
 
     res.writeHead(upstreamRes.status, outHeaders);
     res.end(capture.buf);
@@ -900,19 +1020,10 @@ async function handleProxy(req, res) {
     } catch {}
 
     const outHeaders = Object.fromEntries(upstreamRes.headers.entries());
-    outHeaders["x-settld-gate-id"] = gateId;
     if (gateVerify) {
-      outHeaders["x-settld-settlement-status"] = String(gateVerify?.settlement?.status ?? "");
-      outHeaders["x-settld-released-amount-cents"] = String(gateVerify?.settlement?.releasedAmountCents ?? "");
-      outHeaders["x-settld-refunded-amount-cents"] = String(gateVerify?.settlement?.refundedAmountCents ?? "");
-      if (gateVerify?.gate?.decision?.verificationStatus) {
-        outHeaders["x-settld-verification-status"] = String(gateVerify.gate.decision.verificationStatus);
-      }
-      if (Array.isArray(gateVerify?.gate?.decision?.reasonCodes) && gateVerify.gate.decision.reasonCodes.length > 0) {
-        outHeaders["x-settld-verification-codes"] = gateVerify.gate.decision.reasonCodes.join(",");
-      }
-      if (gateVerify?.gate?.holdback?.status) outHeaders["x-settld-holdback-status"] = String(gateVerify.gate.holdback.status);
-      if (gateVerify?.gate?.holdback?.amountCents !== undefined) outHeaders["x-settld-holdback-amount-cents"] = String(gateVerify.gate.holdback.amountCents);
+      applySettldDecisionHeaders(outHeaders, { gateId, gateVerify });
+    } else if (gateId) {
+      outHeaders["x-settld-gate-id"] = gateId;
     }
 
     res.writeHead(502, outHeaders);