@paybond/kit 0.12.0 → 0.12.2

package/dist/index.js

@@ -4,6 +4,7 @@
  */
 import { buildSignedCreateIntentBody, buildSignedCreateIntentBodyWithPolicyBinding, } from "./principal-intent.js";
 import { signPayeeEvidenceBinding } from "./payee-evidence.js";
+import { PAYBOND_AGENT_RECEIPT_ATTESTATIONS_HEADER, PAYBOND_AGENT_RECEIPT_SOURCE_RUN_HEADER, } from "./agent-receipt.js";
 import { PaybondAgentRunFacade, createPaybondAgentCallable, PaybondInstrumentBuilder, createGuardedAgent, createGuardedAgentRunner, createPaybondAgent, createPaybondToolRegistry, instrumentPaybondAgent, instrumentPaybondClaudeAgents, instrumentPaybondLangGraph, instrumentPaybondMCP, instrumentPaybondOpenAI, instrumentPaybondVercel, resolveAgentPolicySource, wrapPaybondTools, } from "./agent/index.js";
 import { GatewayAgentRunTraceReporter, } from "./agent/gateway-trace-reporter.js";
 import { fetchWithGatewayRetries, gatewayRetryDelayMs, shouldRetryGatewayResponse, } from "./gateway-retry.js";
@@ -934,6 +935,14 @@ export class GatewayHarborClient {
         return gatewayMutationHeaders(proof, {
             ...(headers ?? {}),
             ...(options?.idempotencyKey?.trim() ? { "idempotency-key": options.idempotencyKey.trim() } : {}),
+            ...(options?.agentReceiptAttestations !== undefined
+                ? {
+                    [PAYBOND_AGENT_RECEIPT_ATTESTATIONS_HEADER]: JSON.stringify(options.agentReceiptAttestations),
+                }
+                : {}),
+            ...(options?.agentReceiptSourceRunId?.trim()
+                ? { [PAYBOND_AGENT_RECEIPT_SOURCE_RUN_HEADER]: options.agentReceiptSourceRunId.trim() }
+                : {}),
         });
     }
     async verifyCapability(input) {
@@ -2202,7 +2211,14 @@ function gatewayMutationHeaders(recognitionProof, headers) {
 function encodeRecognitionProofHeader(proof) {
     return Buffer.from(JSON.stringify(proof), "utf8").toString("base64url");
 }
-async function resolveGatewayTenantId(gatewayBaseUrl, apiKey, principalPath, maxRetries, expectedEnvironment) {
+function readPrincipalEnvironment(actualRaw) {
+    const actual = typeof actualRaw === "string" ? actualRaw.trim() : "";
+    if (actual === "live" || actual === "sandbox") {
+        return actual;
+    }
+    return null;
+}
+async function resolveGatewayPrincipal(gatewayBaseUrl, apiKey, principalPath, maxRetries, expectedEnvironment) {
     const base = normalizeBase(gatewayBaseUrl);
     const path = principalPath.startsWith("/") ? principalPath : `/${principalPath}`;
     const url = `${base}${path}`;
@@ -2246,10 +2262,14 @@ async function resolveGatewayTenantId(gatewayBaseUrl, apiKey, principalPath, max
             });
         }
         assertExpectedEnvironment("gateway principal", body.environment, expected, text);
-        return tenant;
+        return { tenantId: tenant, environment: readPrincipalEnvironment(body.environment) };
     }
     throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
 }
+async function resolveGatewayTenantId(gatewayBaseUrl, apiKey, principalPath, maxRetries, expectedEnvironment) {
+    const principal = await resolveGatewayPrincipal(gatewayBaseUrl, apiKey, principalPath, maxRetries, expectedEnvironment);
+    return principal.tenantId;
+}
 /**
  * Read-only tenant-bound Signal session for one service-account API key.
  */
@@ -2446,7 +2466,14 @@ export class Paybond {
     audit;
     agentRun;
     agent;
-    constructor(harbor, guardrails, signal, fraud, a2a, protocol, audit) {
+    /**
+     * Deployment environment this session is bound to, as reported by the gateway principal
+     * (`"live"` or `"sandbox"`), or `null` when the gateway did not report one. Server-derived —
+     * prefer this over the client-supplied `expectedEnvironment` hint when gating environment-sensitive
+     * behavior (for example, refusing live Stripe secrets in a sandbox-only demo).
+     */
+    environment;
+    constructor(harbor, guardrails, signal, fraud, a2a, protocol, audit, environment) {
         this.harbor = harbor;
         this.guardrails = guardrails;
         this.signal = signal;
@@ -2457,12 +2484,14 @@ export class Paybond {
         this.audit = audit;
         this.agentRun = new PaybondAgentRunFacade(this);
         this.agent = createPaybondAgentCallable(protocol, (input) => createPaybondAgent(this, input));
+        this.environment = environment;
     }
     /** Open a tenant-bound hosted Paybond session from a service-account API key. */
     static async open(init) {
         const gatewayBaseUrl = defaultGatewayBaseUrl(init.gatewayBaseUrl);
         const maxRetries = Math.max(1, init.maxRetries ?? 3);
-        const tenantId = await resolveGatewayTenantId(gatewayBaseUrl, init.apiKey, init.principalPath ?? DEFAULT_PRINCIPAL_PATH, maxRetries, init.expectedEnvironment);
+        const principal = await resolveGatewayPrincipal(gatewayBaseUrl, init.apiKey, init.principalPath ?? DEFAULT_PRINCIPAL_PATH, maxRetries, init.expectedEnvironment);
+        const tenantId = principal.tenantId;
         const harbor = new GatewayHarborClient(gatewayBaseUrl, tenantId, {
             staticGatewayBearerToken: init.apiKey,
             maxRetries,
@@ -2491,7 +2520,7 @@ export class Paybond {
             staticGatewayBearerToken: init.apiKey,
             maxRetries,
         }));
-        return new Paybond(harbor, guardrails, signal, fraud, a2a, protocol, audit);
+        return new Paybond(harbor, guardrails, signal, fraud, a2a, protocol, audit, principal.environment);
     }
     /** Reserved for future HTTP client cleanup; safe to call after work completes. */
     async aclose() {
@@ -2569,6 +2598,9 @@ export { artifactsDigest, evidenceSignBytesV1, signPayeeEvidenceBinding, } from
 export { AGENT_RECOGNITION_GATEWAY_VERIFIER_ID, AGENT_RECOGNITION_PROOF_KIND_V1, AGENT_RECOGNITION_PURPOSE_CREATE, AGENT_RECOGNITION_PURPOSE_FUND, AGENT_RECOGNITION_PURPOSE_EVIDENCE_SUBMIT, newAgentRecognitionRequestEnvelope, signAgentRecognitionProofV1, signHarborCreateRecognitionProof, signHarborFundRecognitionProof, signHarborEvidenceSubmitRecognitionProof, signHarborSettlementConfirmRecognitionProof, } from "./agent-recognition.js";
 export { executeFundWithX402, buildX402FundRequestEnvelope, PaybondX402FundingFailedError, PaybondX402FundingPendingError, } from "./x402-funding.js";
 export { executeFundWithMpp, executeFundWithMppCharge, executeFundWithMppSession, buildMppFundRequestEnvelope, parsePaymentAuthChallenge, selectMppChargeChallenge, selectMppSessionChallenge, PaybondMppFundingFailedError, PaybondMppFundingPendingError, } from "./mpp-funding.js";
+export { buildPaybondStripeMetadata, assertNotStripeFundingWebhook, mapStripeToolResultToEvidence, STRIPE_COMMERCE_MAPPER_VERSION, PAYBOND_STRIPE_METADATA_TENANT_ID_KEY, PAYBOND_STRIPE_METADATA_INTENT_ID_KEY, PAYBOND_STRIPE_METADATA_RAIL_KEY, } from "./stripe-commerce/index.js";
+export { PAYBOND_UCP_AGENT_PROFILE_URL, PAYBOND_SHOPIFY_UCP_VERSION, SHOPIFY_COMMERCE_MAPPER_VERSION, assertNotShopifyFundingWebhook, createCheckoutWithBinding, createGuardedShopifyCheckoutHandler, getOrder, instrumentShopifyCheckout, mapShopifyToolResultToEvidence, mergeBindingIntoCheckoutPayload, toUcpCheckoutLineItems, } from "./shopify/index.js";
+export { normalizeCommerceBinding, encodeCommerceBindingToStripeMetadata, decodeCommerceBindingFromStripeMetadata, encodeCommerceBindingToShopifyNoteAttributes, decodeCommerceBindingFromShopifyNoteAttributes, PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY, PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY, } from "./commerce-binding.js";
 export { validateCompletionEvidence, } from "./completion-validate-evidence.js";
 export { completionSchemaDigestHex, computeVendorContractDigests, verifyVendorContract, verifyCatalogVendorContracts, } from "./completion-contract-digest.js";
 export { contractSnapshotForPreset, mapVendorEvidenceToCanonical, resolveCompletionPreset, } from "./completion-resolve.js";
@@ -2577,5 +2609,9 @@ export { PaybondAudit, PaybondAuditExports, GatewayAuditExportsClient, parseAudi
 export { PaybondPolicy, composePolicyLayers, composeBundledPresetDefault, domain, guardrails, paybondPolicyPresets, resolveComposedPresetDocument, } from "./policy/index.js";
 export { getSolutionSmokeDefaults, isKnownSolutionId, listSolutionIds, loadSolutionManifest, paybondSolutionPresets, } from "./solutions/index.js";
 export { appendDirectHarborPaymentAuthorization, formatPaymentAuthorizationValue, PAYBOND_PAYMENT_AUTHORIZATION_HEADER, PAYMENT_TRANSPORT_RESPONSE_HEADERS, paymentAuthorizationGatewayHeader, readFundPaymentTransportHeaders, } from "./payment-transport.js";
-export { AGENT_RECEIPT_KIND_V1, AGENT_RECEIPT_SCHEMA_VERSION, AGENT_RECEIPT_SCOPE_ACTION, AGENT_RECEIPT_SCOPE_INTENT_TERMINAL, AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519, AGENT_RECEIPT_VERSION_V1, AGENT_RECEIPT_WELL_KNOWN_PATH, actionReceiptId, canonicalAgentReceiptBytes, configHashSha256Hex, promptHashSha256Hex, valueDigestSha256Hex, verifyAgentReceiptV1, } from "./agent-receipt.js";
-export { AGENT_RECEIPT_EXTERNAL_SOURCE_SEP2828, AGENT_RECEIPT_EXTERNAL_SOURCE_X402, partnerRecordDigestSha256Hex, resolveExternalAttestations, sep2828RecordsToExternalAttestations, x402ReceiptToExternalAttestations, } from "./agent-receipt-external-attestations.js";
+export { AGENT_RECEIPT_KIND_V1, AGENT_RECEIPT_SCHEMA_VERSION, AGENT_RECEIPT_SCOPE_ACTION, AGENT_RECEIPT_SCOPE_INTENT_TERMINAL, AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519, AGENT_RECEIPT_VERSION_V1, AGENT_RECEIPT_SIGNING_KEYS_WELL_KNOWN_PATH, AGENT_RECEIPT_WELL_KNOWN_PATH, PAYBOND_AGENT_RECEIPT_ATTESTATIONS_HEADER, PAYBOND_AGENT_RECEIPT_SOURCE_RUN_HEADER, actionReceiptId, attachOperatorAttestationV1, canonicalAgentReceiptBytes, configHashSha256Hex, promptHashSha256Hex, valueDigestSha256Hex, verifyAgentReceiptV1, verifyAgentReceiptV1FromJSON, } from "./agent-receipt.js";
+export { FORBIDDEN_AGENT_RECEIPT_FIELDS, parseAgentReceiptJSON, validateAgentReceiptJSON, } from "./agent-receipt-prevalidate.js";
+export { AGENT_RECEIPT_EXTERNAL_SOURCE_AP2, AGENT_RECEIPT_EXTERNAL_SOURCE_SEP2828, AGENT_RECEIPT_EXTERNAL_SOURCE_X402, partnerRecordDigestSha256Hex, protocolAuthorizationReceiptToExternalAttestations, protocolSettlementReceiptToExternalAttestations, resolveExternalAttestations, sep2828RecordsToExternalAttestations, signedMandateToExternalAttestations, x402ReceiptToExternalAttestations, } from "./agent-receipt-external-attestations.js";
+export { AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL, AGENT_RECEIPT_PDF_EXPORT_MANIFEST_KIND, AGENT_RECEIPT_PDF_EXPORT_MANIFEST_SCHEMA_VERSION, FORBIDDEN_PDF_EXPORT_MANIFEST_FIELDS, gateAgentReceiptPDFExport, parseAgentReceiptPDFExportManifestJSON, validateAgentReceiptPDFExportManifestJSON, } from "./agent-receipt-pdf-export.js";
+export { AGENT_AUTHORIZATION_KIND_PRINCIPAL, AGENT_AUTHORIZATION_KIND_TENANT, AGENT_MANDATE_KIND_V1, AGENT_MANDATE_SCHEMA_VERSION, AGENT_MANDATE_SIGNING_ALGORITHM_ED25519_SHA256, CONSTRAINT_REFERENCE_KIND_POLICY, CONSTRAINT_REFERENCE_KIND_PREDICATE, HUMAN_PRESENCE_MODE_HUMAN_NOT_PRESENT, HUMAN_PRESENCE_MODE_HUMAN_PRESENT, agentMandateDigestSha256Hex, canonicalAgentMandateJsonBytes, normalizeAgentMandateV1, signAgentMandateV1, verifySignedAgentMandateV1, } from "./agent-mandate.js";
+export { PROTOCOL_AUTHORIZATION_RECEIPT_KIND_V1, PROTOCOL_RECEIPT_SCHEMA_VERSION, PROTOCOL_RECEIPT_SIGNING_ALGORITHM_ED25519_SHA256, PROTOCOL_RECEIPT_STATUS_AUTHORIZED, PROTOCOL_RECEIPT_VERSION_V1, PROTOCOL_SETTLEMENT_RECEIPT_KIND_V1, PROTOCOL_SOURCE_ACP, PROTOCOL_SOURCE_AP2, PROTOCOL_SOURCE_UCP, normalizeProtocolAuthorizationReceiptV1, normalizeProtocolSettlementReceiptV1, signProtocolAuthorizationReceiptV1, signProtocolSettlementReceiptV1, verifyProtocolAuthorizationReceiptV1, verifyProtocolSettlementReceiptV1, } from "./protocol-receipt.js";

package/dist/mcp-server.d.ts

@@ -49,6 +49,7 @@ export declare class PaybondMCPServer {
         uri: string;
         mimeType: string;
         text: string;
+        _meta?: Record<string, unknown>;
     }>;
     listTools(): Array<Record<string, unknown>>;
     callTool(name: string, args?: Record<string, unknown>): Promise<MCPCallToolResult>;

package/dist/mcp-server.js

@@ -11,10 +11,11 @@ import { MCP_TOOL_ALLOWLIST_ENV, MCP_TOOL_POLICY_ENV, mergeMcpToolPolicy, parseM
 import { MCP_EVIDENCE_POLICY_ENV, McpEvidenceValidationGate, completionEvidenceValidationOk, extractHarborEvidenceValidationInput, extractSandboxGuardrailValidationInput, parseMcpEvidencePolicy, } from "./mcp-evidence-policy.js";
 import { McpCapabilityTokenCache, mcpToolStoresCapabilityToken, parseMcpCapabilityTokenCacheConfig, } from "./mcp-capability-token-cache.js";
 import { createMcpPolicyGatewayAdapter, McpPolicyReloadGate, parseMcpPolicyReloadConfig, } from "./mcp-policy-reload.js";
+import { verifyAgentReceiptV1FromJSON } from "./agent-receipt.js";
 import { agentReceiptResourceTemplateDefinition, agentReceiptResourceUri, MCP_AGENT_RECEIPT_RESOURCE_MIME_TYPE, parseAgentReceiptResourceUri, } from "./mcp-receipt-resource.js";
 import { DEFAULT_PAYBOND_GATEWAY_BASE_URL, GatewayFraudClient, GatewaySignalClient, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
-const SERVER_VERSION = "0.12.0";
+const SERVER_VERSION = "0.12.2";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const DEFAULT_RECOGNITION_VERIFIER_ID = "paybond-gateway";
@@ -633,7 +634,10 @@ class PaybondMCPRuntime {
     requireEvidenceValidation(input) {
         this.evidenceGate.requirePass(input);
     }
-    /** Resolve and cache the gateway principal during MCP server startup. */
+    /**
+     * Best-effort principal warm-up. Callers must not await this on the MCP
+     * initialize path; principal resolves lazily on first tool use.
+     */
     async preloadPrincipal() {
         await this.principal();
     }
@@ -919,10 +923,23 @@ export class PaybondMCPServer {
     async readResource(uri) {
         const receiptId = parseAgentReceiptResourceUri(uri);
         const receipt = await this.runtime.getAgentReceiptV1(receiptId);
+        let verified;
+        try {
+            verified = await verifyAgentReceiptV1FromJSON(receipt);
+        }
+        catch (err) {
+            throw new Error(`agent receipt verification failed for ${receiptId}: ${formatError(err)}`);
+        }
         return {
             uri: agentReceiptResourceUri(receiptId),
             mimeType: MCP_AGENT_RECEIPT_RESOURCE_MIME_TYPE,
             text: JSON.stringify(receipt, null, 2),
+            _meta: {
+                verification: {
+                    valid: true,
+                    message_digest: verified.message_digest_sha256_hex,
+                },
+            },
         };
     }
     listTools() {
@@ -992,7 +1009,12 @@ export class PaybondMCPServer {
         }
         switch (method) {
             case "initialize":
-                await this.runtime.preloadPrincipal();
+                // Do not block the MCP handshake on Gateway principal preload. Registry
+                // hosts time out initialize if egress is slow or blocked; principal is
+                // resolved lazily on the first tool that needs it.
+                void this.runtime.preloadPrincipal().catch(() => {
+                    // Best-effort warm cache; failures surface on subsequent tool calls.
+                });
                 return {
                     jsonrpc: "2.0",
                     id: message.id,
@@ -1054,14 +1076,19 @@ export class PaybondMCPServer {
             case "resources/read": {
                 const params = ensureObject(message.params, "resources/read params");
                 const uri = stringArg(params.uri, "uri");
-                const contents = await this.readResource(uri);
-                return {
-                    jsonrpc: "2.0",
-                    id: message.id,
-                    result: {
-                        contents: [contents],
-                    },
-                };
+                try {
+                    const contents = await this.readResource(uri);
+                    return {
+                        jsonrpc: "2.0",
+                        id: message.id,
+                        result: {
+                            contents: [contents],
+                        },
+                    };
+                }
+                catch (err) {
+                    return responseError(message.id, -32000, formatError(err));
+                }
             }
             case "tools/call": {
                 const params = ensureObject(message.params, "tools/call params");

package/dist/policy/presets.d.ts

@@ -1,7 +1,7 @@
 import type { LayeredPolicyPresetId } from "./compose.js";
 import { type PaybondPolicyDocumentV1 } from "./schema.js";
 export type { LayeredPolicyPresetId };
-declare const KNOWN_POLICY_PRESET_IDS: readonly ["travel", "shopping", "saas", "aws", "read-only", "strict"];
+declare const KNOWN_POLICY_PRESET_IDS: readonly ["travel", "shopping", "saas", "aws", "stripe-commerce", "read-only", "strict"];
 export type PolicyPresetId = (typeof KNOWN_POLICY_PRESET_IDS)[number];
 /** True when `value` is a bundled vertical policy preset id (not a file path). */
 export declare function isKnownPolicyPresetId(value: string): value is PolicyPresetId;

package/dist/policy/presets.js

@@ -10,6 +10,7 @@ const KNOWN_POLICY_PRESET_IDS = [
     "shopping",
     "saas",
     "aws",
+    "stripe-commerce",
     "read-only",
     "strict",
 ];

package/dist/project-init.d.ts

@@ -1,7 +1,7 @@
 import type { PolicyPresetId } from "./policy/presets.js";
 import { type SolutionId } from "./solutions/catalog.js";
 export type ProjectInitSolution = SolutionId | "mcp-server";
-export type ProjectInitFramework = "openai" | "langgraph" | "mcp" | "generic";
+export type ProjectInitFramework = "openai" | "langgraph" | "mcp" | "generic" | "shopify";
 export type ProjectInitLanguage = "typescript" | "python";
 export type ProjectInitOptions = {
     cwd: string;

package/dist/project-init.js

@@ -33,6 +33,7 @@ const FRAMEWORK_ALIASES = {
     langgraph: "langgraph",
     mcp: "mcp",
     generic: "generic",
+    shopify: "shopify",
 };
 function usage() {
     return [

package/dist/protocol-receipt.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Local verification for protocol-v2 authorization and settlement receipts.
+ *
+ * Canonical JSON matches the Go gateway `protocolAuthorizationReceiptCanonicalV1` /
+ * `protocolSettlementReceiptCanonicalV1` marshalers (fixed struct field order, signing
+ * fields stripped, RFC3339Nano UTC timestamps, HTML-safe `\u` escapes), not Kit's generic
+ * JCS-style `normalizeJson`. Ported from `go/gateway/internal/protocolv2/receipt.go`.
+ */
+import { type AgentMandateAgentIdentity, type AgentMandateAuthorization, type AgentMandateConstraintReference, type AgentMandateSettlementRailPolicy, type AgentMandateSpendCeiling } from "./agent-mandate.js";
+export declare const PROTOCOL_RECEIPT_SCHEMA_VERSION = 1;
+export declare const PROTOCOL_RECEIPT_VERSION_V1 = "1";
+export declare const PROTOCOL_RECEIPT_SIGNING_ALGORITHM_ED25519_SHA256 = "ed25519-sha256-json-v1";
+export declare const PROTOCOL_AUTHORIZATION_RECEIPT_KIND_V1 = "paybond.protocol_authorization_receipt_v1";
+export declare const PROTOCOL_SETTLEMENT_RECEIPT_KIND_V1 = "paybond.protocol_settlement_receipt_v1";
+export declare const PROTOCOL_RECEIPT_STATUS_AUTHORIZED = "authorized";
+/** Default protocol source (AP2-aligned) for imported mandates and exported receipts. */
+export declare const PROTOCOL_SOURCE_AP2 = "ap2";
+/** Stripe Agentic Commerce Protocol (ACP) source identifier for partner receipts. */
+export declare const PROTOCOL_SOURCE_ACP = "acp";
+/** Stripe Unified Commerce Protocol (UCP) source identifier for partner receipts. */
+export declare const PROTOCOL_SOURCE_UCP = "ucp";
+/** Partner transport metadata for imported mandates and exported receipts. */
+export type ProtocolTransportBindingV1 = {
+    source_protocol: string;
+    partner_platform?: string;
+    external_authorization_id?: string;
+    request_id?: string;
+};
+/** Signed acknowledgement emitted after accepting a partner mandate binding. */
+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;
+};
+/** Signed terminal outcome artifact for a Harbor intent bound to a partner mandate. */
+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;
+};
+type ProtocolAuthorizationReceiptInput = ProtocolAuthorizationReceiptV1 | Record<string, unknown>;
+type ProtocolSettlementReceiptInput = ProtocolSettlementReceiptV1 | Record<string, unknown>;
+/**
+ * Validates and canonicalizes an authorization receipt for hashing and signing.
+ *
+ * Signing fields are lower/trim-normalized but not recomputed here.
+ *
+ * @throws When structure or field values are invalid.
+ */
+export declare function normalizeProtocolAuthorizationReceiptV1(input: ProtocolAuthorizationReceiptInput): ProtocolAuthorizationReceiptV1;
+/**
+ * Validates and canonicalizes a settlement receipt for hashing and signing.
+ *
+ * @throws When structure or field values are invalid.
+ */
+export declare function normalizeProtocolSettlementReceiptV1(input: ProtocolSettlementReceiptInput): ProtocolSettlementReceiptV1;
+/**
+ * Validates, canonicalizes, and signs an authorization receipt with
+ * Ed25519-over-SHA-256(canonical JSON).
+ *
+ * @param signingSeed - 32-byte Ed25519 seed (noble private key).
+ */
+export declare function signProtocolAuthorizationReceiptV1(signingSeed: Uint8Array, input: ProtocolAuthorizationReceiptInput): ProtocolAuthorizationReceiptV1;
+/**
+ * Validates, canonicalizes, and signs a settlement receipt with
+ * Ed25519-over-SHA-256(canonical JSON).
+ *
+ * @param signingSeed - 32-byte Ed25519 seed (noble private key).
+ */
+export declare function signProtocolSettlementReceiptV1(signingSeed: Uint8Array, input: ProtocolSettlementReceiptInput): ProtocolSettlementReceiptV1;
+/**
+ * Checks structure, canonical digest recompute, and detached Ed25519 signature.
+ *
+ * @returns The normalized authorization receipt on success.
+ * @throws When structure, digest, or signature verification fails.
+ */
+export declare function verifyProtocolAuthorizationReceiptV1(input: ProtocolAuthorizationReceiptInput): ProtocolAuthorizationReceiptV1;
+/**
+ * Checks structure, canonical digest recompute, and detached Ed25519 signature.
+ *
+ * @returns The normalized settlement receipt on success.
+ * @throws When structure, digest, or signature verification fails.
+ */
+export declare function verifyProtocolSettlementReceiptV1(input: ProtocolSettlementReceiptInput): ProtocolSettlementReceiptV1;
+export {};