@agenttrust-sdk/mcp 0.2.1 → 0.2.2

package/dist/embedded-examples/pay-sh-demo/src/middleware.ts

@@ -0,0 +1,198 @@
+/**
+ * `paymentMiddleware` — Express middleware that gates a route behind
+ * Pay.sh / x402 + AgentTrust.
+ *
+ * Flow:
+ *   1. No `PAYMENT-SIGNATURE` / `X-PAYMENT` header → emit 402 with the x402
+ *      v2 envelope (base64) advertising the SERVICE's PaymentRequirements
+ *   2. Header present → parse the proof, run AgentTrust pipeline:
+ *      adapter.parseRequest → decide(ctx) → adapter.formatChallenge
+ *      (Deny path) OR adapter.validatePaymentProof + adapter.emitFeedback
+ *      (Allow path)
+ *   3. Allow → forward to the wrapped handler with `X-Payment-Receipt`
+ *      header set to the feedback CPI signature
+ *
+ * The middleware is the demo's bridge from x402 wire to AgentTrust's
+ * adapter pipeline. In production with a real `simulateGatePayment`-backed
+ * `decide`, this same shape works for any AgentTrust-aware service.
+ */
+
+import type { NextFunction, Request, RequestHandler, Response } from "express";
+import { PublicKey } from "@solana/web3.js";
+
+import {
+  ConfirmedSettlement,
+  GateDecision,
+  PaySh,
+  VerifyContext,
+} from "@agenttrust/trustgate-server";
+
+import { DemoOnChainStub, buildConfirmedSettlement } from "./deps";
+import {
+  PaymentRequirementsBuilder,
+  buildPaymentRequirements,
+  encodeChallengeEnvelope,
+} from "./x402";
+
+export type DecideFn = (ctx: VerifyContext) => Promise<GateDecision>;
+
+export interface PaymentMiddlewareOptions {
+  readonly adapter:                PaySh;
+  readonly chainStub:              DemoOnChainStub;
+  readonly decide:                 DecideFn;
+  readonly buildPaymentRequirements: PaymentRequirementsBuilder;
+  readonly facilitator:            PublicKey;
+  readonly network:                string;
+}
+
+const PAY_SIG_HEADERS = ["payment-signature", "x-payment"];
+
+export function paymentMiddleware(opts: PaymentMiddlewareOptions): RequestHandler {
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const requirements = opts.buildPaymentRequirements(req);
+
+    const proof = readProofHeader(req);
+    if (!proof) {
+      sendChallenge(res, requirements);
+      return;
+    }
+
+    let paymentPayload: unknown;
+    try {
+      paymentPayload = decodeProofHeader(proof);
+    } catch {
+      res.status(400).json({ error: "malformed_payment_proof" });
+      return;
+    }
+
+    const ctx = await opts.adapter.parseRequest(synthesizeRequest({
+      paymentRequirements: requirements,
+      paymentPayload,
+    }));
+    if (!ctx) {
+      res.status(400).json({ error: "facilitator could not parse request" });
+      return;
+    }
+
+    const decision = await opts.decide(ctx);
+
+    if (decision.kind !== "Allow") {
+      const challenge = opts.adapter.formatChallenge(decision, ctx);
+      applyHeaders(res, challenge.headers);
+      res.status(challenge.status).json(challenge.body ?? { decision });
+      return;
+    }
+
+    // Allow path — validate proof + emit feedback.
+    opts.chainStub.setHint({
+      payer:             new PublicKey(extractPayerPubkey(paymentPayload) ?? ctx.payerAgent),
+      transferredAmount: ctx.amount,
+      transferredMint:   ctx.mint,
+      transferRecipient: opts.adapter
+        ? new PublicKey(requirements.extra.agentTrust.payeeRecipient)
+        : ctx.payeeAgent,
+    });
+
+    const validation = await opts.adapter.validatePaymentProof(paymentPayload, ctx);
+    if (!validation.valid) {
+      res.status(402).json({
+        error:  validation.reason,
+        detail: validation.detail,
+      });
+      return;
+    }
+
+    const settlement: ConfirmedSettlement = buildConfirmedSettlement(
+      ctx,
+      validation.txSignature,
+      validation.payer,
+    );
+
+    let feedbackSig: string;
+    try {
+      const fb = await opts.adapter.emitFeedback(ctx, settlement);
+      feedbackSig = fb.feedbackTxSignature;
+    } catch (e) {
+      res.status(500).json({
+        error:  "feedback_emission_failed",
+        detail: e instanceof Error ? e.message : String(e),
+      });
+      return;
+    }
+
+    const settleResp = opts.adapter.formatSettlement(ctx);
+    res.setHeader("X-Payment-Receipt", feedbackSig);
+    res.setHeader("X-Payment-Network", opts.network);
+    Object.entries(settleResp.facilitatorMeta).forEach(([k, v]) => {
+      if (typeof v === "string") res.setHeader(k, v);
+    });
+    next();
+  };
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function readProofHeader(req: Request): string | null {
+  for (const name of PAY_SIG_HEADERS) {
+    const v = req.header(name);
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return null;
+}
+
+function decodeProofHeader(value: string): unknown {
+  // Pay.sh's PAYMENT-SIGNATURE header is the base64-JSON PaymentPayload.
+  // X-PAYMENT (v1) is JSON. Try base64-decode first; fall back to plain JSON.
+  try {
+    const decoded = Buffer.from(value, "base64").toString("utf-8");
+    const json = JSON.parse(decoded);
+    if (json && typeof json === "object") return json;
+  } catch { /* fall through */ }
+  return JSON.parse(value);
+}
+
+function extractPayerPubkey(paymentPayload: unknown): PublicKey | undefined {
+  if (!paymentPayload || typeof paymentPayload !== "object") return undefined;
+  const inner = (paymentPayload as Record<string, unknown>).payload;
+  if (!inner || typeof inner !== "object") return undefined;
+  const auth = (inner as Record<string, unknown>).authorization;
+  if (auth && typeof auth === "object") {
+    const from = (auth as Record<string, unknown>).from;
+    if (typeof from === "string") {
+      try { return new PublicKey(from); } catch { /* skip */ }
+    }
+  }
+  return undefined;
+}
+
+function sendChallenge(res: Response, requirements: ReturnType<PaymentRequirementsBuilder>): void {
+  const envelope = { x402Version: 2 as const, accepts: [requirements] };
+  const b64      = encodeChallengeEnvelope(envelope);
+  res.setHeader("PAYMENT-REQUIRED", b64);
+  res.setHeader("X-Payment-Required", b64);
+  res.setHeader(
+    "Access-Control-Expose-Headers",
+    "PAYMENT-REQUIRED, X-Payment-Required, X-Payment-Receipt",
+  );
+  res.status(402).json({
+    error:   "payment_required",
+    accepts: [requirements],
+  });
+}
+
+function applyHeaders(
+  res: Response,
+  headers: Readonly<Record<string, string | readonly string[]>>,
+): void {
+  Object.entries(headers).forEach(([k, v]) => {
+    res.setHeader(k, v as string | string[]);
+  });
+}
+
+function synthesizeRequest(body: unknown): Request {
+  return { body, header: () => undefined } as unknown as Request;
+}
+
+export { buildPaymentRequirements };

package/dist/embedded-examples/pay-sh-demo/src/policy.ts

@@ -0,0 +1,247 @@
+/**
+ * Demo policy gate. Implements the `decide` function used by the
+ * payment middleware in lieu of an on-chain `gate_payment` simulation.
+ *
+ * Three counterparties at tiers 0 / 1 / 3 give us the three branches the
+ * brief's smoke test exercises:
+ *
+ *   - tier 0  → Deny (CounterpartyTierBelowMin)
+ *   - tier 1  → Deny (CounterpartyTierBelowMin)
+ *   - tier 3  → Allow
+ *
+ * Two factories:
+ *
+ *   - `makeTierDecide(table, minTier)` — static lookup against an in-
+ *     memory table. Used by the mock-chain demo + CI tests.
+ *   - `makeLiveTierDecide({ connection, resolveAtomStats, minTier, ... })` —
+ *     Phase J4. Reads the live `tier_immediate` byte off Quantu's
+ *     `AtomStats` PDA on every gate, with a 60s in-process cache so RPC
+ *     load stays bounded under burst traffic. Falls back to the static
+ *     `fallbackTable` if the on-chain read fails / account not found.
+ *     Wired into `createRealDemoApp` (real-chain demo path).
+ */
+
+import { Connection, PublicKey } from "@solana/web3.js";
+
+import { GateDecision, VerifyContext } from "@agenttrust/trustgate-server";
+
+export const DEMO_POLICY_MIN_TIER = 2;
+
+export interface CounterpartyEntry {
+  readonly tier:  number;
+  readonly label: string;
+}
+
+export type CounterpartyTable = ReadonlyMap<string, CounterpartyEntry>;
+
+const REASON_COUNTERPARTY_TIER_BELOW_MIN = {
+  code: 6,
+  name: "CounterpartyTierBelowMin",
+} as const;
+
+/**
+ * Build a `decide` function that resolves payerAgent → tier from a static
+ * map, compares against `minTier`, and returns Allow / Deny accordingly.
+ *
+ * Unknown payers map to "tier 0" (treated as Deny when minTier > 0). This
+ * matches the on-chain `default_unrated_treatment = UNRATED_DENY` behavior
+ * for the demo policy. Switch to an alternative resolver to change this.
+ */
+export function makeTierDecide(
+  table:   CounterpartyTable,
+  minTier: number,
+): (ctx: VerifyContext) => Promise<GateDecision> {
+  return async (ctx) => {
+    const payerB58 = ctx.payerAgent.toBase58();
+    const entry    = table.get(payerB58);
+    const tier     = entry?.tier ?? 0;
+
+    if (tier >= minTier) {
+      return { kind: "Allow" };
+    }
+    return {
+      kind:       "Deny",
+      reasonCode: REASON_COUNTERPARTY_TIER_BELOW_MIN.code,
+      reasonName: REASON_COUNTERPARTY_TIER_BELOW_MIN.name,
+    };
+  };
+}
+
+export function lookupCounterparty(
+  table: CounterpartyTable,
+  pubkey: PublicKey,
+): CounterpartyEntry | undefined {
+  return table.get(pubkey.toBase58());
+}
+
+// ===========================================================================
+// Phase J4 — live-tier sync against Quantu AtomStats
+// ===========================================================================
+
+// Pinned to the same commit `programs/policy-vault/src/ext/atom_engine.rs`
+// reads on chain. Schema-version canary + tier-range checks prevent silent
+// drift if Quantu re-shapes the account.
+export const ATOM_STATS_SIZE                  = 561;
+export const ATOM_STATS_TRUST_TIER_OFFSET     = 551;
+export const ATOM_STATS_SCHEMA_VERSION_OFFSET = 560;
+export const ATOM_STATS_SCHEMA_VERSION_EXPECTED = 1;
+export const ATOM_TIER_MAX                    = 4;
+
+/** Default cache TTL — 60 seconds matches the brief and matches the
+ *  facilitator's typical inter-payment interval; long enough to amortise
+ *  RPC reads across a burst, short enough that a tier upgrade lands
+ *  before it stales. */
+export const DEFAULT_LIVE_TIER_TTL_MS = 60_000;
+
+export interface CachedTier {
+  readonly tier:        number;
+  readonly source:      "atom-stats" | "fallback-table" | "unrated";
+  readonly fetchedAtMs: number;
+}
+
+export interface LiveTierCache {
+  get(payerB58: string): CachedTier | undefined;
+  set(payerB58: string, entry: CachedTier): void;
+  clear(): void;
+  size(): number;
+}
+
+/** Default in-process Map-backed cache. Drop-in replaceable via the
+ *  `cache` arg of `makeLiveTierDecide` for distributed setups. */
+export function makeInProcessLiveTierCache(): LiveTierCache {
+  const m = new Map<string, CachedTier>();
+  return {
+    get:   (k) => m.get(k),
+    set:   (k, v) => { m.set(k, v); },
+    clear: () => { m.clear(); },
+    size:  () => m.size,
+  };
+}
+
+export interface MakeLiveTierDecideArgs {
+  readonly connection:       Connection;
+  /** Map a payer agent_account pubkey to its `atom_stats` PDA. Returning
+   *  `null` short-circuits to the fallback table. The demo wires this to
+   *  the bundled `devnet-counterparties.json` lookup; real facilitators
+   *  derive via `deriveAtomStatsPda` from the SDK. */
+  readonly resolveAtomStats: (payerAgent: PublicKey) => PublicKey | null;
+  readonly atomEngineId:     PublicKey;
+  readonly minTier:          number;
+  readonly ttlMs?:           number;
+  readonly fallbackTable?:   CounterpartyTable;
+  readonly cache?:           LiveTierCache;
+  /** Lets tests pin the clock without monkey-patching `Date.now`. */
+  readonly nowMs?:           () => number;
+}
+
+/**
+ * Live-tier `decide` factory.
+ *
+ *   1. Resolve the payer's atom_stats PDA. If the resolver returns null,
+ *      the fallback static table (if any) is consulted; otherwise tier 0.
+ *   2. If the cache has a non-expired entry, return it.
+ *   3. Else `getAccountInfo(atom_stats)`, validate owner + size + schema
+ *      version, then read `tier_immediate` at byte 551.
+ *   4. On any failure (account missing, owner mismatch, schema drift),
+ *      consult the fallback table; if that's also empty, treat as tier 0.
+ *   5. Cache the result with `expiresAt = now + ttlMs`.
+ *
+ * Returns Allow when tier >= minTier; otherwise Deny with reasonCode
+ * `CounterpartyTierBelowMin = 6` (matches the chain enum).
+ */
+export function makeLiveTierDecide(
+  args: MakeLiveTierDecideArgs,
+): (ctx: VerifyContext) => Promise<GateDecision> {
+  const ttlMs   = args.ttlMs ?? DEFAULT_LIVE_TIER_TTL_MS;
+  const cache   = args.cache ?? makeInProcessLiveTierCache();
+  const nowMs   = args.nowMs ?? (() => Date.now());
+
+  return async (ctx) => {
+    const tier = await resolveLiveTier({
+      connection:        args.connection,
+      atomEngineId:      args.atomEngineId,
+      resolveAtomStats:  args.resolveAtomStats,
+      fallbackTable:     args.fallbackTable,
+      cache,
+      ttlMs,
+      nowMs,
+      payerAgent:        ctx.payerAgent,
+    });
+
+    if (tier >= args.minTier) {
+      return { kind: "Allow" };
+    }
+    return {
+      kind:       "Deny",
+      reasonCode: REASON_COUNTERPARTY_TIER_BELOW_MIN.code,
+      reasonName: REASON_COUNTERPARTY_TIER_BELOW_MIN.name,
+    };
+  };
+}
+
+interface ResolveLiveTierArgs {
+  connection:       Connection;
+  atomEngineId:     PublicKey;
+  resolveAtomStats: (payerAgent: PublicKey) => PublicKey | null;
+  fallbackTable?:   CounterpartyTable;
+  cache:            LiveTierCache;
+  ttlMs:            number;
+  nowMs:            () => number;
+  payerAgent:       PublicKey;
+}
+
+async function resolveLiveTier(a: ResolveLiveTierArgs): Promise<number> {
+  const payerB58 = a.payerAgent.toBase58();
+
+  const cached = a.cache.get(payerB58);
+  if (cached && a.nowMs() - cached.fetchedAtMs < a.ttlMs) {
+    return cached.tier;
+  }
+
+  const atomStats = a.resolveAtomStats(a.payerAgent);
+  if (atomStats) {
+    try {
+      const info = await a.connection.getAccountInfo(atomStats, "confirmed");
+      const tier = info ? readTierImmediateFromAtomStats(info, a.atomEngineId) : null;
+      if (tier !== null) {
+        a.cache.set(payerB58, { tier, source: "atom-stats", fetchedAtMs: a.nowMs() });
+        return tier;
+      }
+    } catch (_) {
+      // Network errors fall through to fallback; we don't want a transient
+      // RPC blip to flip every payer to Deny.
+    }
+  }
+
+  const fb = a.fallbackTable?.get(payerB58)?.tier ?? 0;
+  a.cache.set(payerB58, {
+    tier:        fb,
+    source:      a.fallbackTable?.has(payerB58) ? "fallback-table" : "unrated",
+    fetchedAtMs: a.nowMs(),
+  });
+  return fb;
+}
+
+/**
+ * Decode `tier_immediate` from an AtomStats account. Returns `null` when
+ * the account is uninitialised, has the wrong owner, or has drifted schema.
+ *
+ * Mirrors `programs/policy-vault/src/ext/atom_engine.rs::parse_atom_stats_bytes`
+ * verbatim (size + schema version + tier-range checks). Importantly the
+ * v1 demo reads `tier_immediate` (byte 551) — `tier_confirmed` (byte 555)
+ * is the post-vesting production value tracked separately.
+ */
+export function readTierImmediateFromAtomStats(
+  info:         { data: Buffer | Uint8Array; owner: PublicKey },
+  atomEngineId: PublicKey,
+): number | null {
+  if (!info.owner.equals(atomEngineId)) return null;
+
+  const data = info.data instanceof Buffer ? info.data : Buffer.from(info.data);
+  if (data.length < ATOM_STATS_SIZE)             return null;
+  if (data[ATOM_STATS_SCHEMA_VERSION_OFFSET] !== ATOM_STATS_SCHEMA_VERSION_EXPECTED) return null;
+
+  const tier = data[ATOM_STATS_TRUST_TIER_OFFSET];
+  if (tier > ATOM_TIER_MAX) return null;
+  return tier;
+}

package/dist/embedded-examples/pay-sh-demo/src/x402.ts

@@ -0,0 +1,140 @@
+/**
+ * x402 v2 wire-format helpers — challenge envelope encoder + the
+ * `PaymentRequirements` builder shape the demo middleware uses.
+ *
+ * Implements the spec from `docs/plan/research/05-trustgate-x402-class.md`
+ * §A.4 (PaymentRequirements) + §A.5 (PaymentPayload). The demo emits v2;
+ * the `X-Payment-Required` header alias is set for v1 fallback compat.
+ */
+
+import type { Request } from "express";
+
+export interface AgentTrustExtraInput {
+  readonly payerAgentAsset: string;
+  readonly payeeAgentAsset: string;
+  readonly payeeRecipient:  string;
+  readonly policyId:        number;
+  readonly issuedAt:        number;
+  readonly serviceSignature: string;
+}
+
+export interface PaymentRequirementsExtraInput {
+  readonly feePayer:    string;
+  readonly memo:        string;
+  readonly agentTrust:  AgentTrustExtraInput;
+}
+
+export interface PaymentRequirementsInput {
+  readonly scheme:            "exact";
+  readonly network:           string;
+  readonly maxAmountRequired: string;
+  readonly asset:             string;
+  readonly payTo:             string;
+  readonly resource:          string;
+  readonly description?:      string;
+  readonly maxTimeoutSeconds: number;
+  readonly extra:             PaymentRequirementsExtraInput;
+}
+
+export interface ChallengeEnvelope {
+  readonly x402Version: 2;
+  readonly accepts:     ReadonlyArray<PaymentRequirementsInput>;
+}
+
+export type PaymentRequirementsBuilder = (req: Request) => PaymentRequirementsInput;
+
+/** Per-challenge ed25519 signer the demo wires to the facilitator
+ *  keypair. Signs canonical envelope bytes (B5). */
+export type SignChallengeFn = (canonicalBytes: Uint8Array) => Uint8Array;
+
+/** Per-request canonical-bytes builder — produced and used inside
+ *  `buildPaymentRequirements` only. Exposed for the test path that
+ *  builds requirements from outside the middleware. */
+export interface AgentTrustHints {
+  readonly payerAgentAsset: string;
+  readonly payeeAgentAsset: string;
+  readonly payeeRecipient:  string;
+  readonly policyId:        number;
+}
+
+/**
+ * Build a PaymentRequirements builder. Captures static fields once and
+ * supplies per-request `memo` + `agentTrust` hints (so the signature
+ * binds to the correct payerAgentAsset for THIS request).
+ *
+ * `signChallenge` is invoked on every emission to bind the requirements
+ * to the facilitator's identity (B5).
+ * `canonicalBytesOf` derives the signing payload — pass the same fn the
+ * AgentTrust adapter uses to keep both sides byte-compatible.
+ */
+export function buildPaymentRequirements(args: {
+  scheme:            "exact";
+  network:           string;
+  amount:            bigint;
+  asset:             string;
+  payTo:             string;
+  resource:          string;
+  description?:      string;
+  maxTimeoutSeconds: number;
+  feePayer:          string;
+  agentTrustFor:     (req: Request) => AgentTrustHints;
+  memoFor:           (req: Request) => string;
+  signChallenge:     SignChallengeFn;
+  canonicalBytesOf:  (input: {
+    issuedAt:        number;
+    network:         string;
+    amount:          bigint;
+    asset:           string;
+    payTo:           string;
+    payerAgentAsset: string;
+    payeeAgentAsset: string;
+    payeeRecipient:  string;
+    policyId:        number;
+    paymentIdHashHex: string;
+  }) => Uint8Array;
+  bytesToHex:        (bytes: Uint8Array) => string;
+  paymentIdHashHexFor: (memo: string) => string;
+}): PaymentRequirementsBuilder {
+  return (req) => {
+    const memo       = args.memoFor(req);
+    const agentTrust = args.agentTrustFor(req);
+    const issuedAt   = Date.now();
+    const paymentIdHashHex = args.paymentIdHashHexFor(memo);
+    const canonical = args.canonicalBytesOf({
+      issuedAt,
+      network:         args.network,
+      amount:          args.amount,
+      asset:           args.asset,
+      payTo:           args.payTo,
+      payerAgentAsset: agentTrust.payerAgentAsset,
+      payeeAgentAsset: agentTrust.payeeAgentAsset,
+      payeeRecipient:  agentTrust.payeeRecipient,
+      policyId:        agentTrust.policyId,
+      paymentIdHashHex,
+    });
+    const sig = args.signChallenge(canonical);
+    return {
+      scheme:            args.scheme,
+      network:           args.network,
+      maxAmountRequired: args.amount.toString(),
+      asset:             args.asset,
+      payTo:             args.payTo,
+      resource:          args.resource,
+      description:       args.description,
+      maxTimeoutSeconds: args.maxTimeoutSeconds,
+      extra: {
+        feePayer:   args.feePayer,
+        memo,
+        agentTrust: {
+          ...agentTrust,
+          issuedAt,
+          serviceSignature: args.bytesToHex(sig),
+        },
+      },
+    };
+  };
+}
+
+export function encodeChallengeEnvelope(envelope: ChallengeEnvelope): string {
+  return Buffer.from(JSON.stringify(envelope), "utf-8").toString("base64");
+}