@paybond/kit 0.3.0 → 0.4.0

package/README.md

@@ -57,22 +57,30 @@ try {
 
 - `Paybond.open(...)` for gateway-authenticated, tenant-derived Harbor sessions
 - `HarborClient` for capability verification, intent creation, x402 funding, evidence submission, and ledger reads
-- `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal 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, 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

@@ -95,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).
@@ -273,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;
@@ -337,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();