@perkos/agent-sdk 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -4,7 +4,20 @@ All notable changes to `@perkos/agent-sdk` are documented here.
 
 ## Unreleased
 
-No changes yet.
+### Added
+
+- `NayoriPartnerClient` for invitation-bound wallet challenges, one-time OAuth client enrollment,
+  minimum-scope client-credentials tokens and authenticated MCP JSON-RPC calls.
+- `createStacksConnectPartnerSigner` adapter for Leather-compatible `stx_signMessage` responses
+  without giving the SDK wallet key material.
+- Partner-pilot documentation covering exact-message review, one-time secret handling, scopes,
+  MCP tools and the separate wallet payment-signing boundary.
+
+### Security
+
+- Normalize and validate recoverable signatures and compressed public keys before registration.
+- Keep OAuth credentials caller-owned: the SDK does not persist, log, refresh or treat them as
+  payment authorization.
 
 ## 0.3.2 - 2026-08-27
 

package/README.md

@@ -9,14 +9,15 @@ This repository is the continuation of `PerkOS-xyz/PerkOS-Agent-SDK`, renamed to
 public SDK with the Nayori product identity. The npm package remains `@perkos/agent-sdk` and the
 complete Git history, releases, issues, and pull requests are preserved.
 
-> Status: 0.3.2 developer release. Read clients, transaction builders, browser and headless signer
+> Status: 0.4.0 developer release. Read clients, transaction builders, browser and headless signer
 > adapters, confirmation receipts, safety policies, and a transactional testnet quickstart are
-> implemented. The x402 v2 client and Stacks facilitator foundations are implemented; hosted quote
-> infrastructure now exists separately, while production settlement enablement, MCP adapters,
-> external review, and adoption evidence remain before Milestone 2 completion. The direct x402
+> implemented. The x402 v2 client and Stacks facilitator foundations are implemented; this release
+> adds wallet-linked OAuth and MCP support for the planned invite-only testnet pilot. Hosted rollout,
+> external review and adoption evidence remain before Milestone 2 completion. The direct x402
 > profile includes request-bound pure verification
 > and payer-side intent, policy, Leather, and remote-signer foundations for STX, sBTC, and USDCx.
-> It does not broadcast transactions, and hosted production settlement remains disabled.
+> Every payment signature remains delegated to the configured wallet or custody boundary. Mainnet
+> facilitator settlement remains disabled.
 
 ## Requirements
 
@@ -148,6 +149,43 @@ const perkos = new PerkOSClient({ network: "mainnet", signer });
 Install `@stacks/connect` in the browser application. Wallet discovery and account selection stay
 at the application boundary so the SDK cannot silently choose an account.
 
+## Invite-only partner OAuth and MCP
+
+`NayoriPartnerClient` enrolls an invited partner without taking custody of a wallet. It requests a
+single-use challenge, delegates the exact plaintext to Leather through `stx_signMessage`, submits
+the signature and returns the generated OAuth client secret once. OAuth authorizes API/MCP access
+only; every payment remains a separate wallet-signed transaction.
+
+```ts
+import { request } from "@stacks/connect";
+import {
+  NayoriPartnerClient,
+  createStacksConnectPartnerSigner,
+} from "@perkos/agent-sdk";
+
+const partners = new NayoriPartnerClient();
+const credentials = await partners.enroll({
+  invitationToken,
+  walletAddress: connectedTestnetAddress,
+  signMessage: createStacksConnectPartnerSigner(request),
+});
+
+// Move the one-time secret directly into the application's secret manager.
+const token = await partners.requestToken({
+  clientId: credentials.clientId,
+  clientSecret: credentials.clientSecret,
+  scopes: ["mcp:invoke"],
+});
+
+const tools = await partners.callMcp({
+  accessToken: token.accessToken,
+  method: "tools/list",
+});
+```
+
+See [Partner pilot](docs/PARTNER_PILOT.md) for the complete enrollment, scope and secret-handling
+boundary.
+
 ## Headless signer
 
 `HeadlessSigner` requests key material only when deriving the public address or signing. It caches
@@ -391,11 +429,16 @@ or facilitator-submitted signed transaction.
 - Automated workflows can wait for an explicit terminal confirmation before their next action.
 - x402 quotes are bound to the configured network, escrow contract, asset, job, and exact budget.
 - x402 settlement verifies current chain evidence and atomically consumes each funding txid once.
+- Partner OAuth enrollment signs an exact, short-lived, invitation-bound message in the wallet;
+  the SDK normalizes the public signature but never receives a private key.
+- OAuth client secrets and access tokens are application secrets. The SDK returns them to the
+  caller but does not persist, log or refresh them automatically.
 
 This package has not yet completed the external security review required for PerkOS Milestone 2.
 Do not treat the developer release as audited software.
 
-See [Architecture](docs/ARCHITECTURE.md) and [Security](SECURITY.md) for the trust boundaries and
+See [Architecture](docs/ARCHITECTURE.md), [Partner pilot](docs/PARTNER_PILOT.md) and
+[Security](SECURITY.md) for the trust boundaries and
 responsible disclosure process.
 
 ## Development

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Release status
 
-`@perkos/agent-sdk` 0.2.0 is an M2 developer release and has not completed the external security
+`@perkos/agent-sdk` 0.4.0 is an M2 developer release and has not completed the external security
 review required for the PerkOS Stacks Endowment milestone.
 
 Do not use this developer release to control material funds without your own review. Inspect every
@@ -40,6 +40,10 @@ disclosure.
 - Explicit direct-payment recipient, HTTPS origin, merchant, amount, fee, and session limits.
 - Concurrent payment reservations that prevent asynchronous agents from oversubscribing a budget.
 - Independent verification of every signed direct-payment transaction before facilitator submission.
+- Invitation-bound partner enrollment through exact Stacks message signing, with compressed public
+  key and recoverable-signature validation before API submission.
+- OAuth client secrets and tokens remain caller-owned and are never persisted or automatically
+  refreshed by the SDK.
 
 ## Key handling
 
@@ -62,6 +66,12 @@ in-process policy is defense in depth and can be bypassed by a malicious host ap
 custody service must independently authenticate callers, revalidate intent, enforce durable limits,
 and keep keys outside the agent/LLM process.
 
+`createStacksConnectPartnerSigner` uses `stx_signMessage` only for the exact partner-enrollment
+challenge. This signature authorizes OAuth client creation, not a payment. The host must show the
+message, network and selected address to the user, move the returned one-time client secret into a
+secret manager and keep invitations, signatures, secrets and access tokens out of telemetry and
+prompts.
+
 ## Confirmation handling
 
 A broadcast receipt means a node accepted the transaction, not that the contract call succeeded.

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { SpendingPolicy } from "./policy.js";
 export { HeadlessSigner, StacksConnectSigner } from "./signers.js";
 export { TransactionTracker } from "./tracker.js";
 export { PerkOSError } from "./errors.js";
+export { NAYORI_PARTNER_SCOPES, NayoriPartnerApiError, NayoriPartnerClient, createStacksConnectPartnerSigner, } from "./partner.js";
 export { DEFAULT_DEPLOYMENTS, JOB_STATUS, CLARITY_ERROR_MESSAGES } from "./constants.js";
 export { resolveConfig, toUint } from "./validation.js";
 export { normalizeTxid } from "./txid.js";
@@ -15,6 +16,7 @@ export type { HeadlessSignerOptions, HeadlessTransactionExecutor, HeadlessTransa
 export type { TrackerFetch, TransactionTrackerOptions, } from "./tracker.js";
 export type { AgentEndpoint, AgentRecord, Amount, AmountLike, AssignProviderInput, ConfirmationOptions, ConfirmedTransactionReceipt, ContractCallPlan, ContractId, CreateJobInput, FundJobInput, JobAmountInput, JobRecord, JobStatus, PaymentAsset, PerkOSConfig, PerkOSContracts, PerkOSNetwork, PerkOSOperation, PerkOSSigner, RateProviderInput, ReadOnlyCall, ReadOnlyTransport, RegisterAgentInput, ReputationRecord, ResolvedPerkOSConfig, SettleJobInput, SignerResult, SpendingApproval, SpendingPolicyInput, SubmitWorkInput, TransactionIntent, TransactionConfirmation, TransactionConfirmationStatus, TransactionReceipt, TransactionResultValue, TransactionTrackerLike, UpdateAgentInput, } from "./types.js";
 export type { PerkOSErrorCode, PerkOSErrorDetails } from "./errors.js";
+export type { NayoriPartnerAccessToken, NayoriPartnerChallenge, NayoriPartnerCredentials, NayoriPartnerFetch, NayoriPartnerMessageSignature, NayoriPartnerMessageSigner, NayoriPartnerNetwork, NayoriPartnerScope, StacksConnectMessageRequest, } from "./partner.js";
 export type { ParsedPerkOSX402Requirement, PaymentPayload, PaymentRequired, PaymentRequirements, PerkOSX402ClientLike, PerkOSX402PaymentProof, PerkOSX402PaymentRequiredInput, PerkOSX402SchemeClientOptions, ResourceInfo, SettleResponse, } from "./x402.js";
 export type { HiroX402TransactionSourceOptions, PerkOSX402FacilitatorOptions, PerkOSX402ReplayRecord, PerkOSX402ReplayStore, PerkOSX402TransactionSource, PerkOSX402VerifiedPayment, X402VerifierFetch, } from "./x402-facilitator.js";
 export type { NayoriStacksX402Network, NayoriX402AssetDefinition, NayoriX402DirectPaymentPayloadInput, NayoriX402PaymentAsset, NayoriX402ProtectedRequest, NayoriX402Quote, NayoriX402QuoteInput, NayoriX402VerifiedDirectPayment, NayoriX402ValidatedPaymentContext, ValidateNayoriX402PaymentContextInput, VerifyNayoriX402DirectPaymentInput, } from "./x402-direct.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -4,6 +4,7 @@ export { SpendingPolicy } from "./policy.js";
 export { HeadlessSigner, StacksConnectSigner } from "./signers.js";
 export { TransactionTracker } from "./tracker.js";
 export { PerkOSError } from "./errors.js";
+export { NAYORI_PARTNER_SCOPES, NayoriPartnerApiError, NayoriPartnerClient, createStacksConnectPartnerSigner, } from "./partner.js";
 export { DEFAULT_DEPLOYMENTS, JOB_STATUS, CLARITY_ERROR_MESSAGES } from "./constants.js";
 export { resolveConfig, toUint } from "./validation.js";
 export { normalizeTxid } from "./txid.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,iCAAiC,EACjC,wBAAwB,EACxB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,6BAA6B,EAC7B,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,qBAAqB,EACrB,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,yBAAyB,EACzB,wCAAwC,EACxC,+BAA+B,EAC/B,oCAAoC,EACpC,yBAAyB,EACzB,iCAAiC,EACjC,2BAA2B,EAC3B,iCAAiC,EACjC,oCAAoC,EACpC,mCAAmC,EACnC,qBAAqB,EACrB,gCAAgC,EAChC,kBAAkB,EAClB,yBAAyB,EACzB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,iCAAiC,EACjC,kCAAkC,EAClC,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACZ,yCAAyC,EACzC,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,gCAAgC,GACjC,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,iCAAiC,EACjC,wBAAwB,EACxB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,6BAA6B,EAC7B,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,qBAAqB,EACrB,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,yBAAyB,EACzB,wCAAwC,EACxC,+BAA+B,EAC/B,oCAAoC,EACpC,yBAAyB,EACzB,iCAAiC,EACjC,2BAA2B,EAC3B,iCAAiC,EACjC,oCAAoC,EACpC,mCAAmC,EACnC,qBAAqB,EACrB,gCAAgC,EAChC,kBAAkB,EAClB,yBAAyB,EACzB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,iCAAiC,EACjC,kCAAkC,EAClC,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACZ,yCAAyC,EACzC,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC"}

package/dist/partner.d.ts

@@ -0,0 +1,79 @@
+export declare const NAYORI_PARTNER_SCOPES: readonly ["catalog:read", "quotes:create", "payments:verify", "payments:settle", "payments:read", "mcp:invoke"];
+export type NayoriPartnerScope = (typeof NAYORI_PARTNER_SCOPES)[number];
+export type NayoriPartnerNetwork = "testnet" | "mainnet";
+export type NayoriPartnerFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type NayoriPartnerChallenge = {
+    readonly challengeId: string;
+    readonly message: string;
+    readonly expiresAt: string;
+    readonly walletAddress: string;
+    readonly network: NayoriPartnerNetwork;
+};
+export type NayoriPartnerCredentials = {
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly tokenEndpoint: string;
+    readonly scopes: readonly NayoriPartnerScope[];
+    readonly walletAddress: string;
+};
+export type NayoriPartnerAccessToken = {
+    readonly accessToken: string;
+    readonly tokenType: "Bearer";
+    readonly expiresIn: number;
+    readonly scopes: readonly NayoriPartnerScope[];
+};
+export type NayoriPartnerMessageSignature = {
+    readonly signature: string;
+    readonly publicKey: string;
+};
+export type NayoriPartnerMessageSigner = (input: {
+    readonly message: string;
+    readonly walletAddress: string;
+    readonly network: NayoriPartnerNetwork;
+}) => Promise<NayoriPartnerMessageSignature>;
+export type StacksConnectMessageRequest = (method: "stx_signMessage", params: {
+    readonly message: string;
+}) => Promise<{
+    readonly signature: string;
+    readonly publicKey: string;
+}>;
+export declare class NayoriPartnerApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function createStacksConnectPartnerSigner(request: StacksConnectMessageRequest): NayoriPartnerMessageSigner;
+export declare class NayoriPartnerClient {
+    readonly origin: string;
+    private readonly fetchImpl;
+    constructor(options?: {
+        readonly origin?: string;
+        readonly fetch?: NayoriPartnerFetch;
+    });
+    requestChallenge(input: {
+        readonly invitationToken: string;
+        readonly walletAddress: string;
+    }): Promise<NayoriPartnerChallenge>;
+    register(input: {
+        readonly challengeId: string;
+        readonly signature: string;
+        readonly publicKey: string;
+    }): Promise<NayoriPartnerCredentials>;
+    enroll(input: {
+        readonly invitationToken: string;
+        readonly walletAddress: string;
+        readonly signMessage: NayoriPartnerMessageSigner;
+    }): Promise<NayoriPartnerCredentials>;
+    requestToken(input: {
+        readonly clientId: string;
+        readonly clientSecret: string;
+        readonly scopes?: readonly NayoriPartnerScope[];
+    }): Promise<NayoriPartnerAccessToken>;
+    callMcp(input: {
+        readonly accessToken: string;
+        readonly id?: string | number;
+        readonly method: "initialize" | "ping" | "tools/list" | "tools/call";
+        readonly params?: unknown;
+    }): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=partner.d.ts.map

package/dist/partner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partner.d.ts","sourceRoot":"","sources":["../src/partner.ts"],"names":[],"mappings":"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"}

package/dist/partner.js

@@ -0,0 +1,195 @@
+export const NAYORI_PARTNER_SCOPES = [
+    "catalog:read",
+    "quotes:create",
+    "payments:verify",
+    "payments:settle",
+    "payments:read",
+    "mcp:invoke",
+];
+export class NayoriPartnerApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "NayoriPartnerApiError";
+    }
+}
+function apiOrigin(value) {
+    const url = new URL(value ?? "https://api.nayori.ai");
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if (url.protocol !== "https:" && !local) {
+        throw new Error("Nayori partner API origin must use HTTPS outside local development.");
+    }
+    return url.origin;
+}
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}
+function string(value, label) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`${label} is invalid.`);
+    return value;
+}
+function normalizedHex(value, pattern, label) {
+    const normalized = value.startsWith("0x") ? value.slice(2) : value;
+    if (!pattern.test(normalized))
+        throw new Error(`${label} is invalid.`);
+    return normalized;
+}
+function scopes(value) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.some((scope) => typeof scope !== "string" ||
+            !NAYORI_PARTNER_SCOPES.includes(scope))) {
+        throw new Error("Nayori partner scopes are invalid.");
+    }
+    return value;
+}
+async function responseJson(response) {
+    let payload = {};
+    try {
+        payload = object(await response.json(), "Nayori API response");
+    }
+    catch {
+        if (response.ok)
+            throw new Error("Nayori API returned invalid JSON.");
+    }
+    if (!response.ok) {
+        const nested = payload.error && typeof payload.error === "object"
+            ? payload.error
+            : null;
+        const code = (typeof payload.error === "string" && payload.error) ||
+            (nested && typeof nested.code === "string" && nested.code) ||
+            "nayori_api_error";
+        const message = (typeof payload.error_description === "string" && payload.error_description) ||
+            (nested && typeof nested.message === "string" && nested.message) ||
+            `Nayori API returned HTTP ${response.status}.`;
+        throw new NayoriPartnerApiError(response.status, code, message);
+    }
+    return payload;
+}
+export function createStacksConnectPartnerSigner(request) {
+    return async ({ message }) => {
+        const result = await request("stx_signMessage", { message });
+        return {
+            signature: normalizedHex(result.signature, /^[0-9a-f]{130}$/i, "Leather signature"),
+            publicKey: normalizedHex(result.publicKey, /^(02|03)[0-9a-f]{64}$/i, "Leather public key"),
+        };
+    };
+}
+export class NayoriPartnerClient {
+    origin;
+    fetchImpl;
+    constructor(options = {}) {
+        this.origin = apiOrigin(options.origin);
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async requestChallenge(input) {
+        const response = await this.fetchImpl(`${this.origin}/v1/partners/challenges`, {
+            method: "POST",
+            headers: { Accept: "application/json", "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        const payload = await responseJson(response);
+        const challenge = object(payload.challenge, "Nayori partner challenge");
+        const network = string(challenge.network, "challenge.network");
+        if (network !== "testnet" && network !== "mainnet") {
+            throw new Error("challenge.network is invalid.");
+        }
+        return {
+            challengeId: string(challenge.challengeId, "challenge.challengeId"),
+            message: string(challenge.message, "challenge.message"),
+            expiresAt: string(challenge.expiresAt, "challenge.expiresAt"),
+            walletAddress: string(challenge.walletAddress, "challenge.walletAddress"),
+            network,
+        };
+    }
+    async register(input) {
+        const response = await this.fetchImpl(`${this.origin}/v1/partners/register`, {
+            method: "POST",
+            headers: { Accept: "application/json", "Content-Type": "application/json" },
+            body: JSON.stringify({
+                challengeId: input.challengeId,
+                signature: normalizedHex(input.signature, /^[0-9a-f]{130}$/i, "wallet signature"),
+                publicKey: normalizedHex(input.publicKey, /^(02|03)[0-9a-f]{64}$/i, "wallet public key"),
+            }),
+        });
+        const payload = await responseJson(response);
+        const client = object(payload.client, "Nayori OAuth client");
+        return {
+            clientId: string(client.clientId, "client.clientId"),
+            clientSecret: string(client.clientSecret, "client.clientSecret"),
+            tokenEndpoint: string(client.tokenEndpoint, "client.tokenEndpoint"),
+            scopes: scopes(client.scopes),
+            walletAddress: string(client.walletAddress, "client.walletAddress"),
+        };
+    }
+    async enroll(input) {
+        const challenge = await this.requestChallenge(input);
+        if (challenge.walletAddress !== input.walletAddress) {
+            throw new Error("Nayori challenge wallet does not match the requested wallet.");
+        }
+        const signed = await input.signMessage({
+            message: challenge.message,
+            walletAddress: challenge.walletAddress,
+            network: challenge.network,
+        });
+        const credentials = await this.register({
+            challengeId: challenge.challengeId,
+            ...signed,
+        });
+        if (credentials.walletAddress !== input.walletAddress) {
+            throw new Error("Nayori OAuth client wallet does not match the enrolled wallet.");
+        }
+        return credentials;
+    }
+    async requestToken(input) {
+        const body = new URLSearchParams({ grant_type: "client_credentials" });
+        if (input.scopes?.length)
+            body.set("scope", scopes([...input.scopes]).join(" "));
+        const response = await this.fetchImpl(`${this.origin}/oauth/token`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                Authorization: `Basic ${btoa(`${input.clientId}:${input.clientSecret}`)}`,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: body.toString(),
+        });
+        const payload = await responseJson(response);
+        if (payload.token_type !== "Bearer")
+            throw new Error("Nayori token type is invalid.");
+        if (typeof payload.expires_in !== "number" || !Number.isSafeInteger(payload.expires_in)) {
+            throw new Error("Nayori token expiry is invalid.");
+        }
+        return {
+            accessToken: string(payload.access_token, "access_token"),
+            tokenType: "Bearer",
+            expiresIn: payload.expires_in,
+            scopes: scopes(string(payload.scope, "scope").split(" ")),
+        };
+    }
+    async callMcp(input) {
+        const response = await this.fetchImpl(`${this.origin}/mcp`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                Authorization: `Bearer ${input.accessToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: input.id ?? 1,
+                method: input.method,
+                ...(input.params === undefined ? {} : { params: input.params }),
+            }),
+        });
+        return responseJson(response);
+    }
+}
+//# sourceMappingURL=partner.js.map

package/dist/partner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partner.js","sourceRoot":"","sources":["../src/partner.ts"],"names":[],"mappings":"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"}

package/docs/PARTNER_PILOT.md

@@ -0,0 +1,95 @@
+# Nayori invite-only partner pilot
+
+The partner pilot exposes the Nayori x402 Platform on Stacks testnet without giving the API or SDK
+custody of a wallet. An operator privately creates a single-use invitation for an existing merchant.
+The partner binds that invitation to a Stacks address by signing the exact server challenge in
+Leather. The server derives the address from the returned public key and atomically consumes both
+the invitation and challenge before creating the OAuth client.
+
+## Browser enrollment
+
+Install the SDK and the official Stacks Connect package:
+
+```bash
+npm install @perkos/agent-sdk @stacks/connect
+```
+
+Use the account already selected by the application. The SDK never selects an account and never
+receives a private key:
+
+```ts
+import { request } from "@stacks/connect";
+import {
+  NayoriPartnerClient,
+  createStacksConnectPartnerSigner,
+} from "@perkos/agent-sdk";
+
+const nayori = new NayoriPartnerClient({ origin: "https://api.nayori.ai" });
+const credentials = await nayori.enroll({
+  invitationToken,
+  walletAddress: selectedTestnetAddress,
+  signMessage: createStacksConnectPartnerSigner(request),
+});
+```
+
+Leather displays the exact challenge. Verify the origin, `testnet` network, merchant, wallet,
+challenge identifier and expiration before approving. The client rejects a response bound to a
+different wallet. The API independently verifies the recoverable signature and derived address.
+
+`clientSecret` is returned once. Send it directly to an application-owned secret manager. Do not
+put the invitation, client secret, access token or wallet signature in source, screenshots, logs,
+analytics, issue trackers or prompts.
+
+## Scoped access token
+
+Request only the scopes needed by the current process:
+
+```ts
+const token = await nayori.requestToken({
+  clientId: credentials.clientId,
+  clientSecret: credentials.clientSecret,
+  scopes: ["quotes:create", "mcp:invoke"],
+});
+```
+
+Supported scopes are:
+
+- `catalog:read`
+- `quotes:create`
+- `payments:verify`
+- `payments:settle`
+- `payments:read`
+- `mcp:invoke`
+
+The API uses `client_credentials` plus `client_secret_basic` and returns a short-lived EdDSA JWT.
+The SDK deliberately does not persist or automatically refresh it.
+
+## MCP
+
+The authenticated Streamable HTTP endpoint implements JSON-RPC `initialize`, `ping`, `tools/list`
+and `tools/call`. Current tools are `nayori_supported`, `nayori_request_quote` and
+`nayori_get_settlement`.
+
+```ts
+const response = await nayori.callMcp({
+  accessToken: token.accessToken,
+  method: "tools/call",
+  params: {
+    name: "nayori_supported",
+    arguments: {},
+  },
+});
+```
+
+`mcp:invoke` opens the MCP endpoint, while a quote or settlement tool also enforces its own
+downstream scope and merchant isolation.
+
+## Payment boundary
+
+OAuth and the enrollment signature cannot authorize a payment. For each STX, sBTC or USDCx
+payment, create a request-bound quote and let the payer separately inspect and sign the exact Stacks
+transaction. Quote issuance, verification, broadcast or `pending` state is not confirmed
+settlement. Require the confirmed settlement state and signed receipt before delivery.
+
+The hosted pilot remains Stacks-testnet-only. Mainnet facilitator settlement, sponsorship and
+arbitrary resource proxying remain disabled while the external review gate is open.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perkos/agent-sdk",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "TypeScript SDK for agent identity, escrow settlement, and reputation on Stacks.",
   "type": "module",
   "main": "./dist/index.js",