@peac/schema 0.11.0 → 0.11.1

package/dist/carrier.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Evidence Carrier Contract schemas and helpers (DD-124)
+ *
+ * Zod validation schemas for PeacEvidenceCarrier and CarrierMeta,
+ * plus the canonical computeReceiptRef() and validateCarrierConstraints()
+ * functions used by all carrier adapters.
+ */
+import { z } from 'zod';
+import type { CarrierMeta, CarrierValidationResult, PeacEvidenceCarrier, ReceiptRef } from '@peac/kernel';
+/** Maximum carrier size per transport (DD-127) */
+export declare const CARRIER_TRANSPORT_LIMITS: {
+    /** MCP _meta: 64 KB */
+    readonly mcp: 65536;
+    /** A2A metadata: 64 KB */
+    readonly a2a: 65536;
+    /** ACP embed in body: 64 KB; headers only: 8 KB */
+    readonly acp_embed: 65536;
+    readonly acp_headers: 8192;
+    /** UCP webhook body: 64 KB */
+    readonly ucp: 65536;
+    /** x402 embed in body: 64 KB; headers only: 8 KB */
+    readonly x402_embed: 65536;
+    readonly x402_headers: 8192;
+    /** HTTP headers only: 8 KB */
+    readonly http: 8192;
+};
+/** Validates a content-addressed receipt reference: sha256:<64 hex chars> */
+export declare const ReceiptRefSchema: z.ZodString;
+/** Validates a compact JWS: header.payload.signature (base64url parts) */
+export declare const CompactJwsSchema: z.ZodString;
+/** Carrier format schema */
+export declare const CarrierFormatSchema: z.ZodEnum<{
+    embed: "embed";
+    reference: "reference";
+}>;
+/** Schema for PeacEvidenceCarrier */
+export declare const PeacEvidenceCarrierSchema: z.ZodObject<{
+    receipt_ref: z.ZodString;
+    receipt_jws: z.ZodOptional<z.ZodString>;
+    policy_binding: z.ZodOptional<z.ZodString>;
+    actor_binding: z.ZodOptional<z.ZodString>;
+    request_nonce: z.ZodOptional<z.ZodString>;
+    verification_report_ref: z.ZodOptional<z.ZodString>;
+    use_policy_ref: z.ZodOptional<z.ZodString>;
+    representation_ref: z.ZodOptional<z.ZodString>;
+    attestation_ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Schema for CarrierMeta */
+export declare const CarrierMetaSchema: z.ZodObject<{
+    transport: z.ZodString;
+    format: z.ZodEnum<{
+        embed: "embed";
+        reference: "reference";
+    }>;
+    max_size: z.ZodNumber;
+    redaction: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Canonical receipt_ref computation (single source of truth).
+ *
+ * Computes SHA-256 of the UTF-8 bytes of the compact JWS string as emitted.
+ * All carrier adapters MUST use this function rather than computing SHA-256
+ * locally, to ensure consistency across protocols (correction item 4).
+ */
+export declare function computeReceiptRef(jws: string): Promise<ReceiptRef>;
+/**
+ * Canonical carrier constraint validator (DD-127, DD-129, DD-131).
+ *
+ * Validates a carrier against transport-specific constraints using
+ * the provided CarrierMeta. This is the single validation function
+ * that all CarrierAdapter.validateConstraints() implementations delegate to.
+ *
+ * Checks performed:
+ * 1. receipt_ref format (sha256:<hex64>)
+ * 2. receipt_jws format (if present): valid compact JWS
+ * 3. Total serialized size within meta.max_size
+ * 4. If receipt_jws present: receipt_ref consistency (DD-129)
+ * 5. All string fields within MAX_STRING_LENGTH
+ */
+export declare function validateCarrierConstraints(carrier: PeacEvidenceCarrier, meta: CarrierMeta): CarrierValidationResult;
+/**
+ * Verify receipt_ref consistency with receipt_jws (DD-129).
+ *
+ * If both receipt_ref and receipt_jws are present, verifies that
+ * sha256(receipt_jws) equals receipt_ref. This prevents carrier
+ * tampering after attachment.
+ *
+ * Returns null if consistent or receipt_jws is absent;
+ * returns an error string if inconsistent.
+ */
+export declare function verifyReceiptRefConsistency(carrier: PeacEvidenceCarrier): Promise<string | null>;
+export type { CarrierFormat, CarrierMeta, CarrierValidationResult, PeacEvidenceCarrier, ReceiptRef, CarrierAdapter, } from '@peac/kernel';
+//# sourceMappingURL=carrier.d.ts.map

package/dist/carrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carrier.d.ts","sourceRoot":"","sources":["../src/carrier.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAEV,WAAW,EACX,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EACX,MAAM,cAAc,CAAC;AAQtB,kDAAkD;AAClD,eAAO,MAAM,wBAAwB;IACnC,uBAAuB;;IAEvB,0BAA0B;;IAE1B,mDAAmD;;;IAGnD,8BAA8B;;IAE9B,oDAAoD;;;IAGpD,8BAA8B;;CAEtB,CAAC;AAMX,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,aAEiD,CAAC;AAE/E,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,aAK1B,CAAC;AAEJ,4BAA4B;AAC5B,eAAO,MAAM,mBAAmB;;;EAAiC,CAAC;AAElE,qCAAqC;AACrC,eAAO,MAAM,yBAAyB;;;;;;;;;;iBAUpC,CAAC;AAEH,6BAA6B;AAC7B,eAAO,MAAM,iBAAiB;;;;;;;;iBAK5B,CAAC;AAMH;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAaxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,WAAW,GAChB,uBAAuB,CA8CzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAMD,YAAY,EACV,aAAa,EACb,WAAW,EACX,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EACV,cAAc,GACf,MAAM,cAAc,CAAC"}

package/dist/index.cjs

@@ -2650,6 +2650,103 @@ function isAttestationOnly(claims) {
 function isPaymentReceipt(claims) {
   return "amt" in claims && "cur" in claims && "payment" in claims;
 }
+var CARRIER_TRANSPORT_LIMITS = {
+  /** MCP _meta: 64 KB */
+  mcp: 65536,
+  /** A2A metadata: 64 KB */
+  a2a: 65536,
+  /** ACP embed in body: 64 KB; headers only: 8 KB */
+  acp_embed: 65536,
+  acp_headers: 8192,
+  /** UCP webhook body: 64 KB */
+  ucp: 65536,
+  /** x402 embed in body: 64 KB; headers only: 8 KB */
+  x402_embed: 65536,
+  x402_headers: 8192,
+  /** HTTP headers only: 8 KB */
+  http: 8192
+};
+var ReceiptRefSchema2 = zod.z.string().regex(/^sha256:[a-f0-9]{64}$/, "receipt_ref must be sha256:<64 hex chars>");
+var CompactJwsSchema = zod.z.string().regex(
+  /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/,
+  "receipt_jws must be a valid compact JWS (header.payload.signature)"
+);
+var CarrierFormatSchema = zod.z.enum(["embed", "reference"]);
+var PeacEvidenceCarrierSchema = zod.z.object({
+  receipt_ref: ReceiptRefSchema2,
+  receipt_jws: CompactJwsSchema.optional(),
+  policy_binding: zod.z.string().max(KERNEL_CONSTRAINTS.MAX_STRING_LENGTH).optional(),
+  actor_binding: zod.z.string().max(KERNEL_CONSTRAINTS.MAX_STRING_LENGTH).optional(),
+  request_nonce: zod.z.string().max(KERNEL_CONSTRAINTS.MAX_STRING_LENGTH).optional(),
+  verification_report_ref: zod.z.string().max(KERNEL_CONSTRAINTS.MAX_STRING_LENGTH).optional(),
+  use_policy_ref: zod.z.string().max(KERNEL_CONSTRAINTS.MAX_STRING_LENGTH).optional(),
+  representation_ref: zod.z.string().max(KERNEL_CONSTRAINTS.MAX_STRING_LENGTH).optional(),
+  attestation_ref: zod.z.string().max(KERNEL_CONSTRAINTS.MAX_STRING_LENGTH).optional()
+});
+var CarrierMetaSchema = zod.z.object({
+  transport: zod.z.string().min(1),
+  format: CarrierFormatSchema,
+  max_size: zod.z.number().int().positive(),
+  redaction: zod.z.array(zod.z.string()).optional()
+});
+async function computeReceiptRef(jws) {
+  if (!globalThis.crypto?.subtle) {
+    throw new Error(
+      "computeReceiptRef requires WebCrypto (crypto.subtle). Supported runtimes: Node >= 20, Cloudflare Workers, Deno, Bun."
+    );
+  }
+  const data = new TextEncoder().encode(jws);
+  const hash = await globalThis.crypto.subtle.digest("SHA-256", data);
+  const hex = Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `sha256:${hex}`;
+}
+function validateCarrierConstraints(carrier, meta) {
+  const violations = [];
+  const refResult = ReceiptRefSchema2.safeParse(carrier.receipt_ref);
+  if (!refResult.success) {
+    violations.push(`invalid receipt_ref format: ${carrier.receipt_ref}`);
+  }
+  if (carrier.receipt_jws !== void 0) {
+    const jwsResult = CompactJwsSchema.safeParse(carrier.receipt_jws);
+    if (!jwsResult.success) {
+      violations.push("invalid receipt_jws format: not a valid compact JWS");
+    }
+  }
+  const serialized = JSON.stringify(carrier);
+  const sizeBytes = new TextEncoder().encode(serialized).byteLength;
+  if (sizeBytes > meta.max_size) {
+    violations.push(
+      `carrier size ${sizeBytes} bytes exceeds transport limit ${meta.max_size} bytes for ${meta.transport}`
+    );
+  }
+  const stringFields = [
+    ["policy_binding", carrier.policy_binding],
+    ["actor_binding", carrier.actor_binding],
+    ["request_nonce", carrier.request_nonce],
+    ["verification_report_ref", carrier.verification_report_ref],
+    ["use_policy_ref", carrier.use_policy_ref],
+    ["representation_ref", carrier.representation_ref],
+    ["attestation_ref", carrier.attestation_ref]
+  ];
+  for (const [name, value] of stringFields) {
+    if (value !== void 0 && value.length > KERNEL_CONSTRAINTS.MAX_STRING_LENGTH) {
+      violations.push(
+        `${name} length ${value.length} exceeds MAX_STRING_LENGTH ${KERNEL_CONSTRAINTS.MAX_STRING_LENGTH}`
+      );
+    }
+  }
+  return { valid: violations.length === 0, violations };
+}
+async function verifyReceiptRefConsistency(carrier) {
+  if (carrier.receipt_jws === void 0) {
+    return null;
+  }
+  const computed = await computeReceiptRef(carrier.receipt_jws);
+  if (computed !== carrier.receipt_ref) {
+    return `receipt_ref mismatch: expected ${computed}, got ${carrier.receipt_ref}`;
+  }
+  return null;
+}
 
 // src/receipt-parser.ts
 function classifyReceipt(obj) {
@@ -2727,10 +2824,14 @@ exports.AttributionUsageSchema = AttributionUsageSchema;
 exports.BindingDetailsSchema = BindingDetailsSchema;
 exports.CANONICAL_DIGEST_ALGS = CANONICAL_DIGEST_ALGS;
 exports.CANONICAL_PURPOSES = CANONICAL_PURPOSES;
+exports.CARRIER_TRANSPORT_LIMITS = CARRIER_TRANSPORT_LIMITS;
 exports.CONTRIBUTION_TYPES = CONTRIBUTION_TYPES;
 exports.CONTROL_TYPES = CONTROL_TYPES;
 exports.CREDIT_METHODS = CREDIT_METHODS;
 exports.CanonicalPurposeSchema = CanonicalPurposeSchema;
+exports.CarrierFormatSchema = CarrierFormatSchema;
+exports.CarrierMetaSchema = CarrierMetaSchema;
+exports.CompactJwsSchema = CompactJwsSchema;
 exports.ContactMethodSchema = ContactMethodSchema;
 exports.ContentHashSchema = ContentHashSchema;
 exports.ContributionObligationSchema = ContributionObligationSchema;
@@ -2823,6 +2924,7 @@ exports.PayloadRefSchema = PayloadRefSchema;
 exports.PaymentEvidenceSchema = PaymentEvidenceSchema;
 exports.PaymentRoutingSchema = PaymentRoutingSchema;
 exports.PaymentSplitSchema = PaymentSplitSchema;
+exports.PeacEvidenceCarrierSchema = PeacEvidenceCarrierSchema;
 exports.PolicyContextSchema = PolicyContextSchema;
 exports.ProofMethodSchema = ProofMethodSchema;
 exports.PurposeReasonSchema = PurposeReasonSchema;
@@ -2833,6 +2935,7 @@ exports.RESERVED_KIND_PREFIXES = RESERVED_KIND_PREFIXES;
 exports.RESULT_STATUSES = RESULT_STATUSES;
 exports.ReceiptClaims = ReceiptClaims;
 exports.ReceiptClaimsSchema = ReceiptClaimsSchema;
+exports.ReceiptRefSchema = ReceiptRefSchema2;
 exports.RefsSchema = RefsSchema;
 exports.RemediationSchema = RemediationSchema;
 exports.RemediationTypeSchema = RemediationTypeSchema;
@@ -2861,6 +2964,7 @@ exports.WorkflowSummaryAttestationSchema = WorkflowSummaryAttestationSchema;
 exports.WorkflowSummaryEvidenceSchema = WorkflowSummaryEvidenceSchema;
 exports.assertJsonSafeIterative = assertJsonSafeIterative;
 exports.canTransitionTo = canTransitionTo;
+exports.computeReceiptRef = computeReceiptRef;
 exports.computeTotalWeight = computeTotalWeight;
 exports.createAgentIdentityAttestation = createAgentIdentityAttestation;
 exports.createAttestationReceiptClaims = createAttestationReceiptClaims;
@@ -2930,6 +3034,7 @@ exports.validateAgentIdentityAttestation = validateAgentIdentityAttestation;
 exports.validateAttestationReceiptClaims = validateAttestationReceiptClaims;
 exports.validateAttributionAttestation = validateAttributionAttestation;
 exports.validateAttributionSource = validateAttributionSource;
+exports.validateCarrierConstraints = validateCarrierConstraints;
 exports.validateContentHash = validateContentHash;
 exports.validateContributionObligation = validateContributionObligation;
 exports.validateCreditObligation = validateCreditObligation;
@@ -2949,5 +3054,6 @@ exports.validateSubjectSnapshot = validateSubjectSnapshot;
 exports.validateWorkflowContext = validateWorkflowContext;
 exports.validateWorkflowContextOrdered = validateWorkflowContextOrdered;
 exports.validateWorkflowSummaryAttestation = validateWorkflowSummaryAttestation;
+exports.verifyReceiptRefConsistency = verifyReceiptRefConsistency;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map