@perkos/agent-sdk 0.2.0 → 0.3.0

package/docs/X402_PAYMENTS.md

@@ -0,0 +1,143 @@
+# Paying Nayori x402 resources
+
+Nayori's payer flow prepares a standard, non-sponsored Stacks transaction for direct STX, sBTC,
+or USDCx payment. It binds the payment to the exact HTTP request and returns a body suitable for the
+hosted facilitator. The SDK does not broadcast the transaction.
+
+The public Nayori Platform deployment is currently quote-only. Payment verification, settlement,
+reconciliation, and delivery remain runtime-disabled until the testnet release gates and external
+review are complete. The APIs below are developer foundations, not a claim that production
+settlement is live.
+
+## Safe offline quickstart
+
+The included quickstart creates a testnet USDCx quote, deterministic payment intent, policy
+reservation, and canonical unsigned transaction. It contains no private key, requests no wallet
+approval, performs no network call, and releases the reservation without signing:
+
+```bash
+npm run quickstart:x402:payer
+```
+
+## Shared payment policy
+
+Both interactive and automated signers use the same mandatory, fail-closed policy:
+
+```ts
+import { NayoriX402PaymentPolicy } from "@perkos/agent-sdk";
+
+const policy = new NayoriX402PaymentPolicy({
+  allowedNetworks: ["mainnet"],
+  allowedAssets: ["sbtc", "usdcx"],
+  allowedRecipients: [merchantStacksAddress],
+  allowedOrigins: ["https://merchant.example"],
+  allowedMerchantIds: ["merchant-research"],
+  maxPerTransaction: { sbtc: 25_000n, usdcx: 5_000_000n },
+  maxPerSession: { sbtc: 100_000n, usdcx: 20_000_000n },
+  maxFeePerTransaction: 5_000n,
+  maxFeePerSession: 25_000n,
+  minQuoteValiditySeconds: 30,
+});
+```
+
+All values are atomic units: micro-STX, satoshis, or 10^-6 USDCx. Fee limits are micro-STX.
+Authorization reserves amount and fee before asynchronous signing. A valid signature commits that
+usage even if settlement later becomes ambiguous. Failed or cancelled signing releases it. Active
+reservations count toward session limits, so concurrent agents cannot oversubscribe the budget.
+
+## Interactive Leather signing
+
+Connect the wallet with the official `@stacks/connect` package and select its STX address and
+compressed public key. Pass the package's `request` function to `LeatherSigner`:
+
+```ts
+import { connect, request } from "@stacks/connect";
+import {
+  LeatherSigner,
+  NayoriX402PaymentClient,
+} from "@perkos/agent-sdk";
+
+const connection = await connect();
+const account = connection.addresses.find(
+  (candidate) => candidate.symbol === "STX" || candidate.address.startsWith("S")
+);
+if (!account) throw new Error("The wallet did not return a Stacks account");
+
+const signer = new LeatherSigner({
+  network: "mainnet",
+  address: account.address,
+  publicKey: account.publicKey,
+  request,
+});
+const payer = new NayoriX402PaymentClient({ signer, policy });
+
+const prepared = await payer.preparePayment({
+  signedQuote: quoteResponse.signedQuote,
+  quote: quoteResponse.quote,
+  paymentRequirements: quoteResponse.paymentRequirements,
+  request: protectedRequest,
+  fee: quotedFeeMicroStx,
+  nonce: currentAccountNonce,
+});
+```
+
+`LeatherSigner` calls only `stx_signTransaction` with `broadcast: false`. It rejects a wallet result
+that contains only a txid because the Nayori facilitator must receive, reserve, and broadcast the
+signed bytes exactly once.
+
+## Automated agent signing
+
+`PolicySigner` delegates the cryptographic operation to an application-owned service. The callback
+receives the immutable intent and unsigned transaction, never a key:
+
+```ts
+import {
+  NayoriX402PaymentClient,
+  PolicySigner,
+} from "@perkos/agent-sdk";
+
+const signer = new PolicySigner({
+  network: "mainnet",
+  address: agentStacksAddress,
+  publicKey: agentCompressedPublicKey,
+  sign: async ({ intent, transaction }) => {
+    const response = await fetch("https://signer.internal/v1/stacks/sign", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ intent, transaction }),
+    });
+    if (!response.ok) throw new Error("The custody policy denied signing");
+    return response.json() as Promise<{ transaction: string }>;
+  },
+});
+const payer = new NayoriX402PaymentClient({ signer, policy });
+```
+
+Keep the signing service on a private, mutually authenticated boundary. It must independently
+validate the intent, enforce its own durable limits and nonce policy, and call a KMS/HSM or isolated
+wallet. Do not send a private key to the SDK callback or load one into an LLM/agent process. The
+in-process SDK policy is defense in depth; the custody service is the final authorization boundary.
+
+## Submit to the facilitator
+
+After local verification, `prepared.settlementRequest` is exactly the JSON body expected by
+`POST /v1/x402/settle`:
+
+```ts
+const response = await fetch(`${facilitatorOrigin}/v1/x402/settle`, {
+  method: "POST",
+  headers: {
+    authorization: `Bearer ${merchantCredential}`,
+    "content-type": "application/json",
+  },
+  body: JSON.stringify(prepared.settlementRequest),
+});
+```
+
+The merchant credential belongs to the protected resource or its trusted backend, not to the payer
+agent. In the normal x402 exchange, the payer returns its payment payload to the resource server and
+that server calls or proxies the authenticated facilitator operation.
+
+Before releasing a resource, require confirmed settlement and a valid signed settlement receipt.
+Do not treat wallet approval, a local txid, a broadcast response, or an unconfirmed mempool entry as
+completed payment.

package/docs/plans/2026-08-27-x402-paying-flow-design.md

@@ -0,0 +1,125 @@
+# Nayori x402 paying flow design
+
+Date: 2026-08-27
+
+Status: approved for implementation
+
+## Objective
+
+Add a payer-side TypeScript flow for Nayori's direct Stacks x402 profile. The same immutable
+payment intent must support an interactive Leather wallet and an automated agent whose key stays
+inside an application-owned KMS, HSM, secret manager, or wallet service. The SDK prepares and
+validates the payment; it does not broadcast. The Nayori facilitator remains the only component
+authorized to reserve and broadcast a submitted payment.
+
+This increment does not modify or redeploy the approved Milestone 1 contracts, enable Platform
+settlement, or claim Milestone 2 transaction/adoption evidence.
+
+## Constraints and external behavior
+
+- Direct payments use the existing `stacks-signed-tx-v1` profile for STX, sBTC, and USDCx.
+- `PaymentIntent` is deterministic, serializable, request-bound, and contains no private material.
+- The SDK must validate the trusted quote, accepted x402 requirement, request digest, payer,
+  recipient, asset, atomic amount, fee, nonce, signature, memo, and post-conditions before returning
+  settlement input.
+- A signer receives only an immutable intent and the canonical unsigned transaction.
+- Leather integration uses the current Stacks Connect `stx_signTransaction` method with
+  `broadcast: false`; a missing signed transaction is a failure even if a wallet returns a txid.
+- Headless integration delegates signing to an application callback. The SDK never accepts,
+  requests, stores, or logs the agent's private key.
+- Spending policy is mandatory and fail-closed. An LLM or agent cannot override its decision.
+- Session limits count signed authorizations, not confirmed settlements. This conservative rule
+  prevents repeated signing after an ambiguous network result.
+
+## Public API
+
+The new module exports:
+
+- `NayoriX402PaymentIntent` and `createNayoriX402PaymentIntent`;
+- `NayoriX402PaymentPolicy`, its explicit configuration, and read-only session usage;
+- `NayoriX402PaymentSigner` as the common signer contract;
+- `LeatherSigner`, a Stacks Connect callback adapter;
+- `PolicySigner`, a remote/headless signing callback adapter;
+- `NayoriX402PaymentClient`, which builds, authorizes, signs, verifies, and returns the exact input
+  accepted by the hosted `/v1/x402/settle` route.
+
+The client input contains the signed quote bundle returned by Nayori, the protected request, fee,
+and nonce. Address and compressed public key come from the signer. The output contains
+`signedQuote`, `paymentRequirements`, `paymentPayload`, `request`, and locally verified payment
+metadata. It never broadcasts.
+
+## Intent and transaction construction
+
+Intent construction first normalizes the quote and proves that:
+
+1. the protected method, canonical URL, and body digest match the quote;
+2. the accepted x402 requirement is exactly the requirement derived from that quote;
+3. the quote is currently valid with the configured clock-skew allowance;
+4. the signer's compressed public key derives the declared Stacks payer address;
+5. fee and nonce are canonical unsigned integers.
+
+The intent ID is a SHA-256 digest over a domain-separated canonical representation containing the
+quote fingerprint, payer, public key, fee, and nonce. The signed transaction is constructed as:
+
+- STX: a native token transfer with the quote fingerprint in the memo;
+- sBTC/USDCx: the canonical SIP-010 `transfer` call with the payer and recipient principals, the
+  fingerprint in the optional memo, deny mode, and one exact fungible-token post-condition.
+
+All three paths are standard, non-sponsored transactions. Fee and nonce are provided explicitly so
+transaction preparation is deterministic and performs no hidden network request.
+
+## Policy and concurrency
+
+Policy configuration explicitly lists allowed networks, assets, recipients, and HTTPS origins,
+plus per-transaction and per-session atomic limits for every allowed asset and a maximum fee in
+micro-STX. Optional merchant IDs and a minimum remaining quote lifetime further narrow authority.
+
+Authorization reserves both payment amount and fee synchronously before asynchronous signing. The
+reservation is committed after a valid signed transaction is produced, or released if building,
+signing, or local verification fails. Active reservations are included in session-limit checks, so
+concurrent agent calls cannot oversubscribe the budget. A committed intent cannot be signed again
+by the same policy instance.
+
+## Signer boundaries
+
+`LeatherSigner` is configured with the connected address, compressed public key, and an injected
+Stacks Connect-compatible request function. It calls only:
+
+```text
+stx_signTransaction({ transaction: unsignedHex, broadcast: false })
+```
+
+`PolicySigner` is configured with the same public identity and a remote callback. That callback may
+talk to a KMS/HSM/wallet service and must return a fully signed serialized transaction. No example
+introduced for this payer flow uses an environment variable or local raw private key. The older,
+explicitly opt-in escrow lifecycle example remains separate from this x402 custody boundary.
+
+Neither signer result is trusted. The client runs the existing pure x402 verifier and additionally
+checks payer, nonce, fee, non-sponsored authorization, and the canonical intent fields before
+committing policy usage.
+
+## Errors and observability
+
+Invalid quote context returns `X402_INVALID`; policy rejection returns the existing `POLICY_DENIED`
+or `POLICY_LIMIT_REQUIRED`; signer cancellation or malformed output returns `SIGNING_FAILED`.
+Errors include stable, non-secret context such as intent ID, asset, or quote ID. Signed quote tokens,
+request bodies, unsigned/signed transaction bytes, and callbacks are not included in error details.
+
+## Tests and release gate
+
+Regression coverage must include all three assets, Leather `broadcast: false`, remote signing,
+request/requirement mismatch, public-key mismatch, fee and amount limits, recipient/origin denial,
+quote expiry, signer mutation, invalid signatures, cancellation, concurrent reservation, release on
+failure, and duplicate-intent prevention. `npm run verify`, `npm audit --audit-level=high`, package
+contents inspection, and a clean-room consumer import are required before the PR is opened.
+
+## Primary references
+
+- Stacks Connect `request` API and normalized `stx_signTransaction` result:
+  https://docs.stacks.co/reference/stacks.js/stacks-connect/request/request
+- Stacks Connect wallet compatibility, including Leather support:
+  https://docs.stacks.co/stacks-connect/wallet-support
+- Stacks transaction construction and unsigned transaction primitives:
+  https://docs.stacks.co/stacks.js/build-transactions
+- Stacks node raw transaction broadcast boundary:
+  https://docs.stacks.co/reference/api/stacks-node-rpc/transactions

package/examples/x402-payment-intent.ts

@@ -0,0 +1,81 @@
+import {
+  NayoriX402PaymentPolicy,
+  buildNayoriX402UnsignedPaymentTransaction,
+  createNayoriX402PaymentIntent,
+  createNayoriX402PaymentRequirements,
+  createNayoriX402Quote,
+} from "@perkos/agent-sdk";
+
+const payer = "ST1THWXQ8368SDN2MJGE4BMDKMCHZ2GSVTSQDA7QF";
+const payerPublicKey =
+  "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798";
+const payTo = "ST3AZN3BSQYJ5VWMNG92N88Z4G9498VYSHDZD9EK";
+const now = Math.floor(Date.now() / 1_000);
+const request = {
+  method: "POST",
+  url: "https://api.example.com/v1/weather",
+  body: JSON.stringify({ city: "Miami" }),
+} as const;
+
+const quote = await createNayoriX402Quote({
+  quoteId: "quote-payer-quickstart",
+  merchantId: "merchant-weather",
+  network: "testnet",
+  asset: "usdcx",
+  amount: 100_000n,
+  payTo,
+  ...request,
+  issuedAt: now,
+  expiresAt: now + 300,
+});
+const paymentRequirements = await createNayoriX402PaymentRequirements(quote);
+const intent = await createNayoriX402PaymentIntent({
+  quote,
+  paymentRequirements,
+  request,
+  payer,
+  publicKey: payerPublicKey,
+  fee: 300n,
+  nonce: 7n,
+  nowSeconds: now,
+});
+const policy = new NayoriX402PaymentPolicy(
+  {
+    allowedNetworks: ["testnet"],
+    allowedAssets: ["usdcx"],
+    allowedRecipients: [payTo],
+    allowedOrigins: ["https://api.example.com"],
+    allowedMerchantIds: ["merchant-weather"],
+    maxPerTransaction: { usdcx: 100_000n },
+    maxPerSession: { usdcx: 500_000n },
+    maxFeePerTransaction: 500n,
+    maxFeePerSession: 2_500n,
+  },
+  () => now
+);
+const authorization = policy.reserve(intent);
+const unsignedTransaction = await buildNayoriX402UnsignedPaymentTransaction(intent);
+
+console.log(
+  JSON.stringify(
+    {
+      status: "ready-for-signature",
+      intentId: intent.intentId,
+      quoteId: intent.quoteId,
+      asset: intent.asset,
+      amount: intent.amount,
+      payer: intent.payer,
+      payTo: intent.payTo,
+      fee: intent.fee,
+      nonce: intent.nonce,
+      quoteFingerprint: intent.quoteFingerprint,
+      unsignedTransactionBytes: unsignedTransaction.length / 2,
+      policyRemaining: authorization.remainingThisSession.toString(),
+      broadcast: false,
+    },
+    null,
+    2
+  )
+);
+
+authorization.release();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perkos/agent-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript SDK for agent identity, escrow settlement, and reputation on Stacks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,6 +33,8 @@
     "quickstart:x402": "node --import tsx examples/x402-foundation.ts",
     "prequickstart:x402:facilitator": "npm run build",
     "quickstart:x402:facilitator": "node --import tsx examples/x402-facilitator.ts",
+    "prequickstart:x402:payer": "npm run build",
+    "quickstart:x402:payer": "node --import tsx examples/x402-payment-intent.ts",
     "prequickstart:testnet": "npm run build",
     "quickstart:testnet": "node --import tsx examples/testnet-lifecycle.ts"
   },