@peac/transport-grpc

PEAC gRPC transport layer: carrier adapter, HTTP/gRPC status code parity, and metadata key conventions for signed interaction receipts over gRPC.

Installation

pnpm add @peac/transport-grpc

What It Does

@peac/transport-grpc provides gRPC transport bindings for PEAC evidence carriers using embedded metadata. It maps receipts to gRPC metadata keys, translates between HTTP and gRPC status codes, and implements the CarrierAdapter interface for gRPC-based A2A deployments. This package handles embedded metadata carriers only; for larger receipts that exceed the metadata budget, use reference-based patterns (receipt_url) handled by @peac/net-node. Pure TypeScript with no @grpc/grpc-js dependency; consumers bring their own gRPC runtime.

How Do I Use It?

Attach a receipt to gRPC metadata

import { addReceiptToMetadata } from '@peac/transport-grpc';

const metadata: Record<string, string> = {};
addReceiptToMetadata(metadata, receiptJws);
// metadata['peac-receipt'] = receiptJws
// metadata['peac-receipt-type'] = 'interaction-record+jwt'

Extract a receipt from gRPC metadata

import { extractReceiptFromMetadata } from '@peac/transport-grpc';

const jws = extractReceiptFromMetadata(incomingMetadata);
if (jws) {
  // verify with @peac/protocol verifyLocal()
}

Use the CarrierAdapter

import { A2AGrpcCarrierAdapter } from '@peac/transport-grpc';

const adapter = new A2AGrpcCarrierAdapter();

// Attach carrier to metadata
const metadata = adapter.attach({}, [carrier]);

// Extract carrier (computes real SHA-256 receipt_ref)
const result = adapter.extract(metadata);
if (result) {
  console.log(result.receipts[0].receipt_ref); // sha256:<real digest>
}

Map HTTP status codes to gRPC

import { httpStatusToGrpc, grpcStatusToHttp, GrpcStatus } from '@peac/transport-grpc';

httpStatusToGrpc(402); // GrpcStatus.FAILED_PRECONDITION (9)
grpcStatusToHttp(GrpcStatus.UNAUTHENTICATED); // 401

Use Wire 0.1 receipt type

import { addReceiptToMetadata } from '@peac/transport-grpc';

addReceiptToMetadata(metadata, receiptJws, 'peac-receipt/0.1');

Header Size Constraints

gRPC metadata is carried in HTTP/2 headers. Official gRPC guidance warns that servers may limit request headers, with a common default of 8 KiB. The default GRPC_MAX_CARRIER_SIZE is set to 8,192 bytes as the conservative interoperability-safe default. Larger limits are deployment-specific and require explicit server configuration.

For environments with known larger server limits, override via:

import { createGrpcCarrierMeta } from '@peac/transport-grpc';

const meta = createGrpcCarrierMeta({ max_size: 65_536 }); // 64 KiB

For receipts exceeding the header budget, prefer reference mode (receipt_url) instead of embedding the full JWS in metadata.

Integrates With

• @peac/kernel (Layer 0): Types, constants, error codes
• @peac/schema (Layer 1): Carrier constraint validation
• @peac/mappings-a2a (Layer 4): A2A metadata carrier operations
• @peac/protocol (Layer 3): Receipt issuance and verification

For Agent Developers

If you are building an AI agent or MCP server that needs evidence receipts:

• Start with @peac/mcp-server for a ready-to-use MCP tool server
• Use @peac/protocol for programmatic receipt issuance and verification
• See the llms.txt for a concise overview

License

Apache-2.0

PEAC Protocol is an open source project stewarded by Originary and community contributors.

Docs | GitHub | Originary