@paybond/kit 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # `@paybond/kit`
 
-Paybond Kit for TypeScript provides a tenant-bound Harbor client, gateway-backed service-account sessions, capability verification, canonical signing helpers for intent creation and evidence submission, tenant-scoped ledger provenance reads, and tenant-scoped Signal analytics and reputation reads.
+Paybond Kit for TypeScript provides a tenant-bound Harbor client, gateway-backed service-account sessions, capability verification, canonical signing helpers for intent creation and evidence submission, x402 / USDC-on-Base intent funding helpers, tenant-scoped ledger provenance reads, and tenant-scoped Signal analytics and reputation reads.
 
 Install the public package with:
 
@@ -56,21 +56,31 @@ try {
 ## What the package includes
 
 - `Paybond.open(...)` for gateway-authenticated, tenant-derived Harbor sessions
-- `HarborClient` for capability verification, intent creation, evidence submission, and ledger reads
-- `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads
+- `HarborClient` for capability verification, intent creation, x402 funding, evidence submission, and ledger reads
+- Protocol-v2 helpers for mandate verification, replay-safe recognition proof verification, receipt reads, and A2A discovery
+- `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads and signed portfolio artifacts
 - `paybond.signal` on `Paybond` sessions opened from one service-account API key
-- `PaybondIntents` helpers for principal-signed intent creation and payee-signed evidence submission
+- `PaybondIntents` helpers for principal-signed intent creation, x402 funding, and payee-signed evidence submission
+- `paybond-mcp-server` for tenant-bound MCP tool exposure to any MCP-compatible host
 - Low-level signing helpers exported for advanced callers
 
 `allowedTools` values are your own tool or operation names, not a Paybond-owned catalog. Harbor enforces string matching against whatever names you chose when creating the intent.
 
+`settlementRail` on intent creation is only a rail request. Stripe destinations and x402 receive addresses stay tenant-owned server-side config and are never supplied by the SDK caller.
+
+The protocol-v2 surface is trust-first: signed mandates, recognition proofs, and receipts work across supported settlement adapters instead of treating any single rail as the product boundary.
+
+Gateway-backed protocol helpers throw `ProtocolHttpError` with parsed `errorCode` and `errorMessage` fields when the gateway returns a JSON error envelope. Recognition-gated flows surface `unregistered_key`, `revoked_key`, `mandate_agent_key_mismatch`, and `protocol_binding_mismatch` explicitly.
+
 ## What it does not include
 
 - No operator-tier settlement or console workflows
+- No model-provider-specific MCP wrapper; the MCP server is host-agnostic and works with any MCP-compatible runtime
 
 ## Docs
 
 - Long-form docs: `docs/kit/`
+- MCP server guide: `docs/kit/mcp-server.md`
 - Agents SDK tutorial: `docs/kit/openai-agents.md`
 - TypeScript quickstart: `docs/kit/quickstart-typescript.md`
 - TypeScript SDK reference: `docs/kit/sdk-reference-typescript.md`

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * Paybond Kit — TypeScript Harbor client with tenant binding, retries, optional upstream JWT,
  * and gateway service-account token exchange (`POST /v1/auth/harbor-access`).
  */
-import { type BuildSignedCreateIntentParams } from "./principal-intent.js";
+import { type BuildSignedCreateIntentParams, type SettlementRail } from "./principal-intent.js";
 import { type SignPayeeEvidenceParams } from "./payee-evidence.js";
 export type VerifyCapabilityResult = {
     allow: boolean;
@@ -18,6 +18,44 @@ export type SubmitEvidenceResult = {
     state: string;
     predicatePassed?: boolean;
 };
+export type IntentFundingResult = {
+    settlementRail: SettlementRail;
+    harborFundEndpoint?: string;
+    status?: string;
+    paymentSessionId?: string;
+    paymentUrl?: string;
+    asset?: string;
+    network?: string;
+    authorizationId?: string;
+    captureId?: string;
+    voidId?: string;
+    refundId?: string;
+    sourceAddress?: string;
+    targetAddress?: string;
+    authorizationExpiresAt?: string;
+    captureExpiresAt?: string;
+    refundExpiresAt?: string;
+    onchainTransactionHashes?: {
+        authorizations?: string[];
+        captures?: string[];
+        voids?: string[];
+        refunds?: string[];
+    };
+};
+export type FundIntentResult = {
+    statusCode: 200 | 202 | 402;
+    paymentRequired?: string;
+    paymentResponse?: string;
+    intentId: string;
+    tenant: string;
+    state: string;
+    settlementRail: SettlementRail;
+    currency: string;
+    amountCents: number;
+    funded: boolean;
+    capabilityToken?: string;
+    funding?: IntentFundingResult;
+};
 /** Async supplier for short-lived Harbor JWTs minted by the Paybond gateway. */
 export type HarborBearerSupplier = () => Promise<string | null | undefined>;
 /**
@@ -57,6 +95,361 @@ export declare class SignalHttpError extends Error {
         bodyText: string;
     });
 }
+export type SignalMetrics = {
+    terminal_intents: number;
+    released: number;
+    refunded: number;
+    disputed: number;
+    success_rate_bps: number;
+    dispute_rate_bps: number;
+    refund_rate_bps: number;
+    mean_latency_nanos: number;
+    latency_sample_count: number;
+    receipted_volume_cents: number;
+};
+export type SignalConfidence = {
+    band: string;
+    support_score: number;
+    summary: string;
+};
+export type SignalSupportDepth = {
+    band: string;
+    terminal_intents: number;
+    receipted_volume_cents: number;
+    history_depth: number;
+    latency_sample_count: number;
+};
+export type SignalExplanationMetricDelta = {
+    metric: string;
+    previous: number;
+    current: number;
+    delta: number;
+};
+export type SignalExplanationDelta = {
+    basis: string;
+    previous_score: number;
+    score_delta: number;
+    previous_ledger_watermark_seq: number;
+    changed_metrics: SignalExplanationMetricDelta[];
+    reason_codes_added: string[];
+    reason_codes_removed: string[];
+    summary: string;
+};
+export type SignalSignedReceipt = {
+    schema_version: number;
+    receipt_version: string;
+    tenant_id: string;
+    operator_did: string;
+    score_version: string;
+    scoring_model: string;
+    scoring_narrative: string;
+    explanation_summary: string;
+    ledger_watermark_seq: number;
+    reason_codes: string[];
+    confidence?: SignalConfidence;
+    support_depth?: SignalSupportDepth;
+    review_state?: string;
+    explanation_delta?: SignalExplanationDelta;
+    metrics: SignalMetrics;
+    score: number;
+    signing_algorithm: string;
+    message_digest_hex: string;
+    signing_public_key_hex: string;
+    signature_hex: string;
+};
+export type SignalReceiptEnvelope = {
+    schema_version: number;
+    updated_at: string;
+    receipt: SignalSignedReceipt;
+};
+export type SignalPortfolioOperator = {
+    operator_did: string;
+    receipt_version?: string;
+    score: number;
+    ledger_watermark_seq: number;
+    receipt_message_digest_hex: string;
+    confidence?: SignalConfidence;
+    support_depth?: SignalSupportDepth;
+    review_state?: string;
+    explanation_delta?: SignalExplanationDelta;
+};
+export type SignalSignedPortfolioArtifact = {
+    schema_version: number;
+    artifact_version: string;
+    kind: string;
+    tenant_id: string;
+    score_model_version: string;
+    scoring_model: string;
+    checkpoint_last_ledger_seq: number;
+    operators: SignalPortfolioOperator[];
+    signing_algorithm: string;
+    message_digest_hex: string;
+    signing_public_key_hex: string;
+    signature_hex: string;
+};
+export type SignalPortfolioSummary = {
+    schema_version: number;
+    tenant_id: string;
+    score_model_version: string;
+    scoring_model: string;
+    checkpoint_last_ledger_seq: number;
+    operator_count: number;
+    average_score: number;
+    total_terminal_intents: number;
+    total_receipted_volume_cents: number;
+    operators_under_review: number;
+};
+export type A2AAgentCard = {
+    name: string;
+    description: string;
+    supportedInterfaces: Array<{
+        url: string;
+        protocolBinding: string;
+        protocolVersion: string;
+        tenant?: string;
+    }>;
+    provider?: {
+        url: string;
+        organization: string;
+    };
+    version: string;
+    documentationUrl?: string;
+    capabilities: {
+        streaming?: boolean;
+        pushNotifications?: boolean;
+        extendedAgentCard?: boolean;
+        extensions?: Array<{
+            uri?: string;
+            description?: string;
+            required?: boolean;
+            params?: Record<string, unknown>;
+        }>;
+    };
+    securitySchemes?: Record<string, unknown>;
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: Array<{
+        id: string;
+        name: string;
+        description: string;
+        tags: string[];
+        examples?: string[];
+        inputModes?: string[];
+        outputModes?: string[];
+        securityRequirements?: Array<Record<string, string[]>>;
+    }>;
+};
+export type A2ATaskField = {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+};
+export type A2ATaskParticipant = {
+    role: string;
+    required: boolean;
+    description: string;
+};
+export type A2ATaskExample = {
+    name: string;
+    description: string;
+    sampleInput?: Record<string, unknown>;
+    sampleResponse?: Record<string, unknown>;
+};
+export type A2ASettlementTaskContractV1 = {
+    schemaVersion: number;
+    kind: string;
+    id: string;
+    name: string;
+    description: string;
+    url: string;
+    routeBindings: string[];
+    requiredTrustArtifacts: string[];
+    settlementPhases: string[];
+    participants: A2ATaskParticipant[];
+    inputModes: string[];
+    outputModes: string[];
+    taskMetadataFields?: A2ATaskField[];
+    inputFields: A2ATaskField[];
+    resultFields: A2ATaskField[];
+    examples?: A2ATaskExample[];
+};
+export type A2ATaskContractCatalogV1 = {
+    schemaVersion: number;
+    kind: string;
+    agentCardUrl: string;
+    documentationUrl?: string;
+    contracts: A2ASettlementTaskContractV1[];
+};
+export type AgentMandateAuthorization = {
+    kind: string;
+    tenant_id: string;
+    principal_subject?: string;
+    principal_type?: string;
+};
+export type AgentMandateAgentIdentity = {
+    subject: string;
+    issuer?: string;
+    key_id?: string;
+    display_name?: string;
+};
+export type AgentMandateSpendCeiling = {
+    amount_minor: number;
+    currency: string;
+};
+export type AgentMandateSettlementRailPolicy = {
+    default_rail: string;
+    allowed_rails: string[];
+};
+export type AgentMandateConstraintReference = {
+    kind: string;
+    id?: string;
+    version?: string;
+    digest_sha256_hex?: string;
+    uri?: string;
+};
+export type AgentMandateV1 = {
+    schema_version: number;
+    kind: string;
+    authorization: AgentMandateAuthorization;
+    agent: AgentMandateAgentIdentity;
+    allowed_actions: string[];
+    allowed_tools: string[];
+    spend_ceiling: AgentMandateSpendCeiling;
+    settlement: AgentMandateSettlementRailPolicy;
+    constraint: AgentMandateConstraintReference;
+    expires_at: string;
+    nonce: string;
+    human_presence_mode: string;
+};
+export type SignedAgentMandateV1 = AgentMandateV1 & {
+    signing_algorithm: string;
+    message_digest_sha256_hex: string;
+    signing_public_key_ed25519_hex: string;
+    ed25519_signature_hex: string;
+};
+export type AgentRecognitionVerifierContext = {
+    tenant_id: string;
+    verifier_id: string;
+};
+export type AgentRecognitionRequestEnvelope = {
+    method: string;
+    path: string;
+    body_digest_sha256_hex: string;
+};
+export type AgentRecognitionProofV1 = {
+    schema_version?: number;
+    kind?: string;
+    key_id: string;
+    signature_algorithm?: string;
+    issued_at: string;
+    expires_at: string;
+    nonce: string;
+    purpose: string;
+    verifier_context: AgentRecognitionVerifierContext;
+    request_envelope: AgentRecognitionRequestEnvelope;
+    message_digest_sha256_hex?: string;
+    signing_public_key_ed25519_hex?: string;
+    ed25519_signature_hex?: string;
+};
+export type ProtocolTransportBindingV1 = {
+    source_protocol?: string;
+    partner_platform?: string;
+    external_authorization_id?: string;
+    request_id?: string;
+};
+export type ProtocolAuthorizationReceiptV1 = {
+    schema_version: number;
+    kind: string;
+    receipt_version: string;
+    receipt_id: string;
+    issued_at: string;
+    status: string;
+    intent_id: string;
+    tenant_id: string;
+    verifier_id: string;
+    transport_binding: ProtocolTransportBindingV1;
+    mandate_digest_sha256_hex: string;
+    imported_mandate_signing_public_key_ed25519_hex: string;
+    authorization: AgentMandateAuthorization;
+    agent: AgentMandateAgentIdentity;
+    allowed_actions: string[];
+    allowed_tools: string[];
+    spend_ceiling: AgentMandateSpendCeiling;
+    settlement: AgentMandateSettlementRailPolicy;
+    constraint: AgentMandateConstraintReference;
+    expires_at: string;
+    nonce: string;
+    human_presence_mode: string;
+    signing_algorithm: string;
+    message_digest_sha256_hex: string;
+    signing_public_key_ed25519_hex: string;
+    ed25519_signature_hex: string;
+};
+export type ProtocolSettlementReceiptV1 = {
+    schema_version: number;
+    kind: string;
+    receipt_version: string;
+    receipt_id: string;
+    issued_at: string;
+    intent_id: string;
+    tenant_id: string;
+    verifier_id: string;
+    transport_binding: ProtocolTransportBindingV1;
+    authorization_receipt_id: string;
+    mandate_digest_sha256_hex: string;
+    harbor_state: string;
+    predicate_passed?: boolean;
+    settlement_rail: string;
+    settlement_mode: string;
+    principal_did: string;
+    payee_did: string;
+    currency: string;
+    amount_cents: number;
+    terminal_observed_at: string;
+    signing_algorithm: string;
+    message_digest_sha256_hex: string;
+    signing_public_key_ed25519_hex: string;
+    ed25519_signature_hex: string;
+};
+export type ImportAgentMandateV1Result = {
+    valid: boolean;
+    intent_id: string;
+    mandate_digest_sha256_hex: string;
+    mandate: AgentMandateV1;
+    authorization_receipt: ProtocolAuthorizationReceiptV1;
+};
+export type VerifyProtocolReceiptV1Result = {
+    valid: boolean;
+    kind: string;
+    receipt_id: string;
+    tenant_id: string;
+    receipt: ProtocolAuthorizationReceiptV1 | ProtocolSettlementReceiptV1 | Record<string, unknown>;
+};
+export declare class A2AHttpError extends Error {
+    readonly statusCode: number;
+    readonly url: string;
+    readonly bodyText: string;
+    constructor(message: string, init: {
+        statusCode: number;
+        url: string;
+        bodyText: string;
+    });
+}
+export declare class ProtocolHttpError extends Error {
+    readonly statusCode: number;
+    readonly url: string;
+    readonly bodyText: string;
+    readonly errorCode?: string;
+    readonly errorMessage?: string;
+    constructor(message: string, init: {
+        statusCode: number;
+        url: string;
+        bodyText: string;
+        errorCode?: string;
+        errorMessage?: string;
+    });
+}
 /**
  * Exchanges a `paybond_sk_` API key for short-lived Harbor JWTs and caches tenant realm from the
  * gateway response (no separate tenant env var for the default path).
@@ -172,6 +565,21 @@ export declare class HarborClient {
     createIntent(body: Record<string, unknown>, options?: {
         idempotencyKey?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * POST `/intents/{intentId}/fund` for x402 / USDC-on-Base funding.
+     *
+     * Harbor returns:
+     * - `402` with `paymentRequired` details when a facilitator or wallet must sign
+     * - `202` while authorization is pending
+     * - `200` once the intent is funded and any capability token is available
+     *
+     * @throws HarborHttpError for non-funding HTTP errors
+     * @throws Error when Harbor echoes a different tenant or intent than requested
+     */
+    fundIntent(intentId: string, options?: {
+        paymentSignature?: string;
+        idempotencyKey?: string;
+    }): Promise<FundIntentResult>;
     /**
      * POST `/intents/{intentId}/evidence` with a signed evidence JSON body.
      *
@@ -220,11 +628,73 @@ export declare class GatewaySignalClient {
     private fetchGetWithRetries;
     private assertTenant;
     private scoreQuery;
-    getReputationReceipt(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
-    getPortfolioSummary(scoreVersion?: string): Promise<Record<string, unknown>>;
+    getReputationReceipt(operatorDid: string, scoreVersion?: string): Promise<SignalReceiptEnvelope | null>;
+    getPortfolioSummary(scoreVersion?: string): Promise<SignalPortfolioSummary>;
+    getSignedPortfolioArtifact(scoreVersion?: string): Promise<SignalSignedPortfolioArtifact>;
     getOperatorExplanation(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
     getOperatorReviewStatus(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
 }
+type GatewayA2AClientOptions = {
+    staticGatewayBearerToken?: string;
+    maxRetries?: number;
+};
+/**
+ * Public or optionally authenticated reader for the gateway's A2A discovery surface.
+ */
+export declare class GatewayA2AClient {
+    private readonly base;
+    private readonly bearerToken?;
+    private readonly maxRetries;
+    constructor(gatewayBaseUrl: string, options?: GatewayA2AClientOptions);
+    private fetchGetWithRetries;
+    getAgentCard(): Promise<A2AAgentCard>;
+    getTaskContracts(): Promise<A2ATaskContractCatalogV1>;
+    getTaskContract(contractId: string): Promise<A2ASettlementTaskContractV1>;
+}
+export declare class GatewayProtocolClient {
+    readonly tenantId: string;
+    private readonly base;
+    private readonly staticGatewayBearerToken;
+    private readonly maxRetries;
+    constructor(gatewayBaseUrl: string, tenantId: string, init?: {
+        staticGatewayBearerToken?: string;
+        maxRetries?: number;
+    });
+    private fetchWithRetries;
+    private headers;
+    private postJSON;
+    importAgentMandateV1(init: {
+        signedMandate: SignedAgentMandateV1;
+        intentId: string;
+        transportBinding?: ProtocolTransportBindingV1;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+    }): Promise<ImportAgentMandateV1Result>;
+    getSettlementReceiptV1(receiptId: string): Promise<ProtocolSettlementReceiptV1>;
+    verifyProtocolReceiptV1(receipt: ProtocolAuthorizationReceiptV1 | ProtocolSettlementReceiptV1 | Record<string, unknown>): Promise<VerifyProtocolReceiptV1Result>;
+    createHarborIntent(init: {
+        body: Record<string, unknown>;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    fundHarborIntent(init: {
+        intentId: string;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+        paymentSignature?: string;
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    submitHarborEvidence(init: {
+        intentId: string;
+        body: Record<string, unknown>;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    confirmHarborSettlement(init: {
+        intentId: string;
+        body: Record<string, unknown>;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+}
 export type ServiceAccountSignalSessionInit = {
     gatewayBaseUrl: string;
     apiKey: string;
@@ -240,24 +710,37 @@ export declare class ServiceAccountSignalSession {
     static open(init: ServiceAccountSignalSessionInit): Promise<ServiceAccountSignalSession>;
     aclose(): Promise<void>;
 }
-/** Parameters for {@link PaybondIntents.create} (tenant is taken from the bound Harbor client). */
+/**
+ * Parameters for {@link PaybondIntents.create} (tenant is taken from the bound Harbor client).
+ * `settlementRail`, when set, requests one allowed rail; Harbor still resolves the destination
+ * from tenant-owned settlement config.
+ */
 export type PaybondCreateIntentParams = Omit<BuildSignedCreateIntentParams, "tenantId" | "intentId"> & {
     intentId?: string;
 };
 /** Parameters for {@link PaybondIntents.submitEvidence} (tenant is taken from the bound Harbor client). */
 export type PaybondSubmitEvidenceParams = Omit<SignPayeeEvidenceParams, "tenantId">;
 /**
- * Ergonomic intent helpers: principal-signed intent create and payee-signed evidence.
+ * Ergonomic intent helpers: principal-signed intent create, x402 funding, and payee-signed evidence.
  */
 export declare class PaybondIntents {
     private readonly harbor;
     constructor(harbor: HarborClient);
     /**
-     * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be 32 bytes.
+     * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be
+     * 32 bytes. `settlementRail` only requests an allowed rail; destinations stay server-owned.
      */
     create(params: PaybondCreateIntentParams & {
         idempotencyKey?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Advance Harbor `/intents/{id}/fund` for x402 / USDC-on-Base intents.
+     */
+    fund(params: {
+        intentId: string;
+        paymentSignature?: string;
+        idempotencyKey?: string;
+    }): Promise<FundIntentResult>;
     /**
      * Sign payee evidence and POST it. `payeeSigningSeed` must be 32 bytes.
      */
@@ -271,6 +754,8 @@ export declare class PaybondIntents {
 export declare class Paybond {
     readonly harbor: HarborClient;
     readonly signal: GatewaySignalClient;
+    readonly a2a: GatewayA2AClient;
+    readonly protocol: GatewayProtocolClient;
     readonly intents: PaybondIntents;
     private readonly session;
     private constructor();
@@ -281,5 +766,5 @@ export declare class Paybond {
     aclose(): Promise<void>;
 }
 export { normalizeJson, jsonValueDigest } from "./json-digest.js";
-export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, type BuildSignedCreateIntentParams, } from "./principal-intent.js";
+export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, type BuildSignedCreateIntentParams, type SettlementRail, } from "./principal-intent.js";
 export { artifactsDigest, signPayeeEvidenceBinding, type SignPayeeEvidenceParams } from "./payee-evidence.js";