@peac/transport-grpc 0.12.6

package/dist/metadata.d.ts

@@ -0,0 +1,42 @@
+/**
+ * gRPC metadata keys, types, and helpers for PEAC transport.
+ *
+ * Extracted to a separate module to avoid circular imports between
+ * index.ts and a2a-carrier.ts.
+ */
+/** gRPC metadata shape for PEAC carrier operations */
+export type GrpcMetadataLike = Record<string, string | string[] | undefined>;
+/**
+ * gRPC metadata keys for PEAC transport.
+ */
+export declare const GrpcMetadataKeys: {
+    /** PEAC receipt in metadata */
+    readonly RECEIPT: "peac-receipt";
+    /** PEAC receipt type */
+    readonly RECEIPT_TYPE: "peac-receipt-type";
+    /** TAP signature */
+    readonly TAP_SIGNATURE: "peac-tap-signature";
+    /** TAP signature input */
+    readonly TAP_SIGNATURE_INPUT: "peac-tap-signature-input";
+    /** PEAC error code in trailer */
+    readonly ERROR_CODE: "peac-error-code";
+    /** Request ID for tracing */
+    readonly REQUEST_ID: "peac-request-id";
+};
+/**
+ * Extract PEAC receipt from gRPC metadata.
+ */
+export declare function extractReceiptFromMetadata(metadata: GrpcMetadataLike): string | null;
+/**
+ * Extract receipt type from gRPC metadata.
+ */
+export declare function extractReceiptTypeFromMetadata(metadata: GrpcMetadataLike): string | null;
+/**
+ * Add PEAC receipt to gRPC metadata.
+ *
+ * @param metadata - gRPC metadata object to modify
+ * @param receiptJws - Compact JWS of the signed receipt
+ * @param receiptType - Receipt typ value (defaults to Wire 0.2 `interaction-record+jwt`)
+ */
+export declare function addReceiptToMetadata(metadata: Record<string, string | string[]>, receiptJws: string, receiptType?: string): void;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,sDAAsD;AACtD,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAM7E;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B,+BAA+B;;IAE/B,wBAAwB;;IAExB,oBAAoB;;IAEpB,0BAA0B;;IAE1B,iCAAiC;;IAEjC,6BAA6B;;CAErB,CAAC;AAMX;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CASpF;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CASxF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAC3C,UAAU,EAAE,MAAM,EAClB,WAAW,GAAE,MAAwB,GACpC,IAAI,CAGN"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@peac/transport-grpc",
+  "version": "0.12.6",
+  "description": "PEAC gRPC transport layer with carrier adapter and HTTP StatusCode parity",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "peac",
+    "peacprotocol",
+    "interaction-records",
+    "signed-records",
+    "receipts",
+    "originary",
+    "transport-grpc",
+    "grpc",
+    "protobuf",
+    "rpc",
+    "carrier-adapter"
+  ],
+  "author": "PEAC Protocol Contributors",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@peac/kernel": "0.12.6",
+    "@peac/schema": "0.12.6"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.2",
+    "vitest": "^4.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/peacprotocol/peac/issues"
+  },
+  "homepage": "https://github.com/peacprotocol/peac#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peacprotocol/peac.git",
+    "directory": "packages/transport/grpc"
+  },
+  "scripts": {
+    "build": "pnpm run build:js && pnpm run build:types",
+    "build:js": "tsup",
+    "build:types": "rm -f dist/.tsbuildinfo && tsc && rm -f dist/.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  }
+}

package/src/a2a-carrier.ts

@@ -0,0 +1,158 @@
+/**
+ * gRPC CarrierAdapter for A2A transport.
+ *
+ * Implements the PEAC CarrierAdapter interface for gRPC metadata,
+ * enabling receipt attach/extract via gRPC metadata keys. Pure TS
+ * with no @grpc/grpc-js dependency; consumers bring their own gRPC.
+ *
+ * Size default: 8 KiB. gRPC metadata rides in HTTP/2 headers where
+ * servers commonly enforce an 8 KiB limit. For larger receipts, use
+ * reference mode (receipt_url) or negotiate a higher limit with the
+ * gRPC server configuration.
+ */
+
+import { createHash } from 'node:crypto';
+
+import type {
+  CarrierAdapter,
+  PeacEvidenceCarrier,
+  CarrierMeta,
+  CarrierValidationResult,
+  ReceiptRef,
+} from '@peac/kernel';
+import { validateCarrierConstraints } from '@peac/schema';
+
+import { GrpcMetadataKeys, extractReceiptFromMetadata, addReceiptToMetadata } from './metadata.js';
+import type { GrpcMetadataLike } from './metadata.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Default maximum carrier size for gRPC metadata (8 KiB).
+ *
+ * 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. This is a conservative interoperability-safe default.
+ * Consumers with known larger server limits can override via
+ * `createGrpcCarrierMeta({ max_size: ... })`.
+ */
+export const GRPC_MAX_CARRIER_SIZE = 8_192;
+
+/** Binary metadata key suffix per gRPC convention */
+const BINARY_SUFFIX = '-bin';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * CarrierAdapter for gRPC metadata transport.
+ *
+ * Reads and writes PEAC evidence carriers via `GrpcMetadataKeys.RECEIPT`
+ * and `GrpcMetadataKeys.RECEIPT_TYPE` metadata entries.
+ *
+ * `extract()` computes the real SHA-256 receipt_ref synchronously
+ * using Node's `crypto.createHash` (server-first package).
+ */
+export class A2AGrpcCarrierAdapter implements CarrierAdapter<GrpcMetadataLike, GrpcMetadataLike> {
+  /**
+   * Extract PEAC evidence carrier from gRPC metadata.
+   *
+   * Computes the real SHA-256 receipt_ref from the JWS bytes using
+   * Node's synchronous crypto.createHash (server-first package).
+   * Rejects binary metadata keys (gRPC `-bin` suffix convention).
+   *
+   * @returns Extracted carrier with computed receipt_ref, or null if absent
+   */
+  extract(input: GrpcMetadataLike): { receipts: PeacEvidenceCarrier[]; meta: CarrierMeta } | null {
+    // Reject binary-encoded PEAC receipt metadata
+    const binaryReceiptKey = GrpcMetadataKeys.RECEIPT + BINARY_SUFFIX;
+    if (binaryReceiptKey in input) {
+      return null;
+    }
+
+    const receiptJws = extractReceiptFromMetadata(input);
+    if (!receiptJws) return null;
+
+    const digest = createHash('sha256').update(receiptJws).digest('hex');
+    const receiptRef = `sha256:${digest}` as ReceiptRef;
+
+    const carrier: PeacEvidenceCarrier = {
+      receipt_ref: receiptRef,
+      receipt_jws: receiptJws,
+    };
+
+    return {
+      receipts: [carrier],
+      meta: createGrpcCarrierMeta(),
+    };
+  }
+
+  attach(
+    output: GrpcMetadataLike,
+    carriers: PeacEvidenceCarrier[],
+    meta?: CarrierMeta
+  ): GrpcMetadataLike {
+    if (carriers.length === 0) return output;
+
+    const carrier = carriers[0];
+    const effectiveMeta = meta ?? createGrpcCarrierMeta();
+    const result = this.validateConstraints(carrier, effectiveMeta);
+    if (!result.valid) {
+      throw new Error(`Carrier constraint violation: ${result.violations.join('; ')}`);
+    }
+
+    if (carrier.receipt_jws) {
+      addReceiptToMetadata(output as Record<string, string | string[]>, carrier.receipt_jws);
+    }
+
+    return output;
+  }
+
+  validateConstraints(carrier: PeacEvidenceCarrier, meta: CarrierMeta): CarrierValidationResult {
+    return validateCarrierConstraints(carrier, meta);
+  }
+}
+
+/**
+ * Create default CarrierMeta for gRPC transport.
+ *
+ * Default max_size is 8 KiB (HTTP/2 header budget). Override for
+ * environments with known larger server limits.
+ */
+export function createGrpcCarrierMeta(overrides?: Partial<CarrierMeta>): CarrierMeta {
+  return {
+    transport: 'grpc',
+    format: 'embed',
+    max_size: GRPC_MAX_CARRIER_SIZE,
+    ...overrides,
+  };
+}
+
+/**
+ * Validate that the package's own PEAC metadata key constants are ASCII-safe
+ * and do not use the reserved `grpc-` prefix.
+ *
+ * This is a repo-level invariant check, not an inbound metadata validator.
+ * It verifies that all keys defined in `GrpcMetadataKeys` use only
+ * lowercase ASCII letters, digits, hyphens, and underscores per
+ * gRPC metadata key requirements, and that none start with the
+ * reserved `grpc-` prefix.
+ *
+ * @returns Array of invalid keys (empty if all valid)
+ */
+export function validateOwnMetadataKeys(): string[] {
+  const ASCII_KEY_REGEX = /^[a-z0-9_-]+$/;
+  const RESERVED_PREFIX = 'grpc-';
+  const invalid: string[] = [];
+  for (const key of Object.values(GrpcMetadataKeys)) {
+    if (!ASCII_KEY_REGEX.test(key)) {
+      invalid.push(key);
+    } else if (key.startsWith(RESERVED_PREFIX)) {
+      invalid.push(key);
+    }
+  }
+  return invalid;
+}

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,sBAAsB,EAAG,QAAiB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,UAAU;IACrB,cAAc;;IAEd,8BAA8B;;IAE9B,oBAAoB;;IAEpB,wCAAwC;;IAExC,kDAAkD;;IAElD,iCAAiC;;IAEjC,4BAA4B;;IAE5B,8BAA8B;;IAE9B,yBAAyB;;IAEzB,6CAA6C;;IAE7C,mCAAmC;;IAEnC,yBAAyB;;IAEzB,gCAAgC;;IAEhC,qBAAqB;;IAErB,0BAA0B;;IAE1B,gBAAgB;;IAEhB,wBAAwB;;CAEhB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAuCnE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,CAuCnE;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CA2B7D,CAAC;AAEF;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAEjE;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,uBAAuB;IACvB,IAAI,EAAE,cAAc,CAAC;IACrB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAO/F;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B,+BAA+B;;IAE/B,wBAAwB;;IAExB,oBAAoB;;IAEpB,0BAA0B;;IAE1B,iCAAiC;;IAEjC,6BAA6B;;CAErB,CAAC;AAEX;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GACtD,MAAM,GAAG,IAAI,CASf;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAC3C,UAAU,EAAE,MAAM,GACjB,IAAI,CAGN;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,qCAAqC;IACrC,EAAE,EAAE,OAAO,CAAC;IACZ,uBAAuB;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,mCAAmC;IACnC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAM9E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,sBAAsB,CAM5E;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAkBzD,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAE1D"}

package/src/index.js.map

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

package/src/index.ts

@@ -0,0 +1,313 @@
+/**
+ * PEAC gRPC Transport Layer
+ *
+ * Provides gRPC binding for PEAC receipts with StatusCode parity to HTTP.
+ *
+ * Status code mapping follows these semantics:
+ * - INVALID_ARGUMENT (3): Malformed request (HTTP 400)
+ * - UNAUTHENTICATED (16): Authentication required (HTTP 401)
+ * - FAILED_PRECONDITION (9): Payment required (HTTP 402)
+ * - PERMISSION_DENIED (7): Not authorized (HTTP 403)
+ * - ABORTED (10): Conflict/replay detected (HTTP 409)
+ * - INTERNAL (13): Server error (HTTP 500)
+ *
+ * @packageDocumentation
+ */
+
+export const GRPC_TRANSPORT_VERSION = '0.12.6' as const;
+
+// Metadata keys, types, and helpers (shared with a2a-carrier.ts)
+export {
+  GrpcMetadataKeys,
+  extractReceiptFromMetadata,
+  extractReceiptTypeFromMetadata,
+  addReceiptToMetadata,
+} from './metadata.js';
+export type { GrpcMetadataLike } from './metadata.js';
+
+/**
+ * gRPC status codes.
+ * @see https://grpc.io/docs/guides/status-codes/
+ */
+export const GrpcStatus = {
+  /** Success */
+  OK: 0,
+  /** Operation was cancelled */
+  CANCELLED: 1,
+  /** Unknown error */
+  UNKNOWN: 2,
+  /** Client specified invalid argument */
+  INVALID_ARGUMENT: 3,
+  /** Deadline expired before operation completed */
+  DEADLINE_EXCEEDED: 4,
+  /** Requested entity not found */
+  NOT_FOUND: 5,
+  /** Entity already exists */
+  ALREADY_EXISTS: 6,
+  /** Caller lacks permission */
+  PERMISSION_DENIED: 7,
+  /** Resource exhausted */
+  RESOURCE_EXHAUSTED: 8,
+  /** Operation rejected due to precondition */
+  FAILED_PRECONDITION: 9,
+  /** Operation aborted (conflict) */
+  ABORTED: 10,
+  /** Value out of range */
+  OUT_OF_RANGE: 11,
+  /** Operation not implemented */
+  UNIMPLEMENTED: 12,
+  /** Internal error */
+  INTERNAL: 13,
+  /** Service unavailable */
+  UNAVAILABLE: 14,
+  /** Data loss */
+  DATA_LOSS: 15,
+  /** Not authenticated */
+  UNAUTHENTICATED: 16,
+} as const;
+
+export type GrpcStatusCode = (typeof GrpcStatus)[keyof typeof GrpcStatus];
+
+/**
+ * Map HTTP status code to gRPC status code.
+ *
+ * Mapping semantics:
+ * - 400 Bad Request -> INVALID_ARGUMENT (malformed)
+ * - 401 Unauthorized -> UNAUTHENTICATED (auth required)
+ * - 402 Payment Required -> FAILED_PRECONDITION (payment needed)
+ * - 403 Forbidden -> PERMISSION_DENIED (not authorized)
+ * - 409 Conflict -> ABORTED (replay detected)
+ * - 500 Internal Server Error -> INTERNAL
+ * - Other 4xx -> INVALID_ARGUMENT
+ * - Other 5xx -> INTERNAL
+ */
+export function httpStatusToGrpc(httpStatus: number): GrpcStatusCode {
+  switch (httpStatus) {
+    case 200:
+    case 201:
+    case 204:
+      return GrpcStatus.OK;
+    case 400:
+      return GrpcStatus.INVALID_ARGUMENT;
+    case 401:
+      return GrpcStatus.UNAUTHENTICATED;
+    case 402:
+      return GrpcStatus.FAILED_PRECONDITION;
+    case 403:
+      return GrpcStatus.PERMISSION_DENIED;
+    case 404:
+      return GrpcStatus.NOT_FOUND;
+    case 409:
+      return GrpcStatus.ABORTED;
+    case 429:
+      return GrpcStatus.RESOURCE_EXHAUSTED;
+    case 499:
+      return GrpcStatus.CANCELLED;
+    case 500:
+      return GrpcStatus.INTERNAL;
+    case 501:
+      return GrpcStatus.UNIMPLEMENTED;
+    case 503:
+      return GrpcStatus.UNAVAILABLE;
+    case 504:
+      return GrpcStatus.DEADLINE_EXCEEDED;
+    default:
+      if (httpStatus >= 400 && httpStatus < 500) {
+        return GrpcStatus.INVALID_ARGUMENT;
+      }
+      if (httpStatus >= 500) {
+        return GrpcStatus.INTERNAL;
+      }
+      return GrpcStatus.OK;
+  }
+}
+
+/**
+ * Map gRPC status code to HTTP status code.
+ *
+ * Inverse of httpStatusToGrpc for response translation.
+ */
+export function grpcStatusToHttp(grpcStatus: GrpcStatusCode): number {
+  switch (grpcStatus) {
+    case GrpcStatus.OK:
+      return 200;
+    case GrpcStatus.CANCELLED:
+      return 499;
+    case GrpcStatus.UNKNOWN:
+      return 500;
+    case GrpcStatus.INVALID_ARGUMENT:
+      return 400;
+    case GrpcStatus.DEADLINE_EXCEEDED:
+      return 504;
+    case GrpcStatus.NOT_FOUND:
+      return 404;
+    case GrpcStatus.ALREADY_EXISTS:
+      return 409;
+    case GrpcStatus.PERMISSION_DENIED:
+      return 403;
+    case GrpcStatus.RESOURCE_EXHAUSTED:
+      return 429;
+    case GrpcStatus.FAILED_PRECONDITION:
+      return 402;
+    case GrpcStatus.ABORTED:
+      return 409;
+    case GrpcStatus.OUT_OF_RANGE:
+      return 400;
+    case GrpcStatus.UNIMPLEMENTED:
+      return 501;
+    case GrpcStatus.INTERNAL:
+      return 500;
+    case GrpcStatus.UNAVAILABLE:
+      return 503;
+    case GrpcStatus.DATA_LOSS:
+      return 500;
+    case GrpcStatus.UNAUTHENTICATED:
+      return 401;
+    default:
+      return 500;
+  }
+}
+
+/**
+ * PEAC error code to gRPC status mapping.
+ *
+ * Maps canonical PEAC error codes to appropriate gRPC status codes.
+ */
+export const PEAC_ERROR_TO_GRPC: Record<string, GrpcStatusCode> = {
+  // 402 Payment Required -> FAILED_PRECONDITION
+  E_RECEIPT_MISSING: GrpcStatus.FAILED_PRECONDITION,
+  E_RECEIPT_INVALID: GrpcStatus.FAILED_PRECONDITION,
+  E_RECEIPT_EXPIRED: GrpcStatus.FAILED_PRECONDITION,
+
+  // 401 Unauthenticated -> UNAUTHENTICATED
+  E_TAP_SIGNATURE_MISSING: GrpcStatus.UNAUTHENTICATED,
+  E_TAP_SIGNATURE_INVALID: GrpcStatus.UNAUTHENTICATED,
+  E_TAP_TIME_INVALID: GrpcStatus.UNAUTHENTICATED,
+  E_TAP_KEY_NOT_FOUND: GrpcStatus.UNAUTHENTICATED,
+  E_TAP_REPLAY_PROTECTION_REQUIRED: GrpcStatus.UNAUTHENTICATED,
+
+  // 400 Bad Request -> INVALID_ARGUMENT
+  E_TAP_WINDOW_TOO_LARGE: GrpcStatus.INVALID_ARGUMENT,
+  E_TAP_TAG_UNKNOWN: GrpcStatus.INVALID_ARGUMENT,
+  E_TAP_ALGORITHM_INVALID: GrpcStatus.INVALID_ARGUMENT,
+
+  // 403 Forbidden -> PERMISSION_DENIED
+  E_ISSUER_NOT_ALLOWED: GrpcStatus.PERMISSION_DENIED,
+
+  // 409 Conflict -> ABORTED
+  E_TAP_NONCE_REPLAY: GrpcStatus.ABORTED,
+
+  // 500 Internal -> INTERNAL
+  E_CONFIG_ISSUER_ALLOWLIST_REQUIRED: GrpcStatus.INTERNAL,
+  E_INTERNAL_ERROR: GrpcStatus.INTERNAL,
+};
+
+/**
+ * Get gRPC status for a PEAC error code.
+ */
+export function peacErrorToGrpc(errorCode: string): GrpcStatusCode {
+  return PEAC_ERROR_TO_GRPC[errorCode] ?? GrpcStatus.INTERNAL;
+}
+
+/**
+ * gRPC error with status code.
+ */
+export interface GrpcError {
+  /** gRPC status code */
+  code: GrpcStatusCode;
+  /** Error message */
+  message: string;
+  /** PEAC error code (if applicable) */
+  peacCode?: string;
+  /** Additional error details */
+  details?: unknown;
+}
+
+/**
+ * Create a gRPC error from a PEAC error code.
+ */
+export function createGrpcError(peacCode: string, message: string, details?: unknown): GrpcError {
+  return {
+    code: peacErrorToGrpc(peacCode),
+    message,
+    peacCode,
+    details,
+  };
+}
+
+/**
+ * gRPC verification result.
+ */
+export interface GrpcVerificationResult {
+  /** Whether verification succeeded */
+  ok: boolean;
+  /** gRPC status code */
+  status: GrpcStatusCode;
+  /** Error if verification failed */
+  error?: GrpcError;
+  /** Receipt ID if verification succeeded */
+  receiptId?: string;
+}
+
+/**
+ * Create a successful verification result.
+ */
+export function createSuccessResult(receiptId?: string): GrpcVerificationResult {
+  return {
+    ok: true,
+    status: GrpcStatus.OK,
+    receiptId,
+  };
+}
+
+/**
+ * Create a failed verification result.
+ */
+export function createFailureResult(error: GrpcError): GrpcVerificationResult {
+  return {
+    ok: false,
+    status: error.code,
+    error,
+  };
+}
+
+/**
+ * Status code name mapping for debugging.
+ */
+export const GrpcStatusName: Record<GrpcStatusCode, string> = {
+  [GrpcStatus.OK]: 'OK',
+  [GrpcStatus.CANCELLED]: 'CANCELLED',
+  [GrpcStatus.UNKNOWN]: 'UNKNOWN',
+  [GrpcStatus.INVALID_ARGUMENT]: 'INVALID_ARGUMENT',
+  [GrpcStatus.DEADLINE_EXCEEDED]: 'DEADLINE_EXCEEDED',
+  [GrpcStatus.NOT_FOUND]: 'NOT_FOUND',
+  [GrpcStatus.ALREADY_EXISTS]: 'ALREADY_EXISTS',
+  [GrpcStatus.PERMISSION_DENIED]: 'PERMISSION_DENIED',
+  [GrpcStatus.RESOURCE_EXHAUSTED]: 'RESOURCE_EXHAUSTED',
+  [GrpcStatus.FAILED_PRECONDITION]: 'FAILED_PRECONDITION',
+  [GrpcStatus.ABORTED]: 'ABORTED',
+  [GrpcStatus.OUT_OF_RANGE]: 'OUT_OF_RANGE',
+  [GrpcStatus.UNIMPLEMENTED]: 'UNIMPLEMENTED',
+  [GrpcStatus.INTERNAL]: 'INTERNAL',
+  [GrpcStatus.UNAVAILABLE]: 'UNAVAILABLE',
+  [GrpcStatus.DATA_LOSS]: 'DATA_LOSS',
+  [GrpcStatus.UNAUTHENTICATED]: 'UNAUTHENTICATED',
+};
+
+/**
+ * Get human-readable name for a gRPC status code.
+ */
+export function getStatusName(code: GrpcStatusCode): string {
+  return GrpcStatusName[code] ?? 'UNKNOWN';
+}
+
+// ---------------------------------------------------------------------------
+// Carrier adapter re-exports
+// ---------------------------------------------------------------------------
+
+export {
+  A2AGrpcCarrierAdapter,
+  createGrpcCarrierMeta,
+  validateOwnMetadataKeys,
+  GRPC_MAX_CARRIER_SIZE,
+} from './a2a-carrier.js';

package/src/metadata.ts

@@ -0,0 +1,85 @@
+/**
+ * gRPC metadata keys, types, and helpers for PEAC transport.
+ *
+ * Extracted to a separate module to avoid circular imports between
+ * index.ts and a2a-carrier.ts.
+ */
+
+import { WIRE_02_JWS_TYP } from '@peac/kernel';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** gRPC metadata shape for PEAC carrier operations */
+export type GrpcMetadataLike = Record<string, string | string[] | undefined>;
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * gRPC metadata keys for PEAC transport.
+ */
+export const GrpcMetadataKeys = {
+  /** PEAC receipt in metadata */
+  RECEIPT: 'peac-receipt',
+  /** PEAC receipt type */
+  RECEIPT_TYPE: 'peac-receipt-type',
+  /** TAP signature */
+  TAP_SIGNATURE: 'peac-tap-signature',
+  /** TAP signature input */
+  TAP_SIGNATURE_INPUT: 'peac-tap-signature-input',
+  /** PEAC error code in trailer */
+  ERROR_CODE: 'peac-error-code',
+  /** Request ID for tracing */
+  REQUEST_ID: 'peac-request-id',
+} as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract PEAC receipt from gRPC metadata.
+ */
+export function extractReceiptFromMetadata(metadata: GrpcMetadataLike): string | null {
+  const receipt = metadata[GrpcMetadataKeys.RECEIPT];
+  if (typeof receipt === 'string') {
+    return receipt;
+  }
+  if (Array.isArray(receipt) && receipt.length > 0) {
+    return receipt[0];
+  }
+  return null;
+}
+
+/**
+ * Extract receipt type from gRPC metadata.
+ */
+export function extractReceiptTypeFromMetadata(metadata: GrpcMetadataLike): string | null {
+  const typ = metadata[GrpcMetadataKeys.RECEIPT_TYPE];
+  if (typeof typ === 'string') {
+    return typ;
+  }
+  if (Array.isArray(typ) && typ.length > 0) {
+    return typ[0];
+  }
+  return null;
+}
+
+/**
+ * Add PEAC receipt to gRPC metadata.
+ *
+ * @param metadata - gRPC metadata object to modify
+ * @param receiptJws - Compact JWS of the signed receipt
+ * @param receiptType - Receipt typ value (defaults to Wire 0.2 `interaction-record+jwt`)
+ */
+export function addReceiptToMetadata(
+  metadata: Record<string, string | string[]>,
+  receiptJws: string,
+  receiptType: string = WIRE_02_JWS_TYP
+): void {
+  metadata[GrpcMetadataKeys.RECEIPT] = receiptJws;
+  metadata[GrpcMetadataKeys.RECEIPT_TYPE] = receiptType;
+}