@crewhaus/federation-protocol 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/federation-protocol",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Cross-deployment A2A wire protocol: federation envelope (extends @crewhaus/a2a-protocol) + mTLS HTTPS POST transport with cert pinning (Section 34)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/federation-protocol"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/federation-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/fixtures-cert.pem

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDDTCCAfWgAwIBAgIUNuMAUkUqNO9Tc0sSHfzY6tkBG+IwDQYJKoZIhvcNAQEL
+BQAwFjEUMBIGA1UEAwwLZmVkLWZpeHR1cmUwHhcNMjYwNTA5MDYyNjU2WhcNMzYw
+NTA2MDYyNjU2WjAWMRQwEgYDVQQDDAtmZWQtZml4dHVyZTCCASIwDQYJKoZIhvcN
+AQEBBQADggEPADCCAQoCggEBAM1mvBIz/XRal0mR8YM92oVzYTg+gdS2x8RAmU7k
+ryN1RXe8XVFg1agTLRObpzb0NxHV4zsN+9s+AVr1DBZuwcfaXpRHGlADf4t/cAUp
+Sl6xoKdWf7cFk4RloE5BOKtkVYzgrAktY/xZVk5TN2i2/fNSrdj71D852nWhy/9/
+LKInPuSRNRazdPMs3REvcJOvO1+Y0JQCiyQIcMfGRNc25piPQOhJaQDunBhcSWnR
+G3RWNCZiwQwv6MozEHq/3ZAne5ypJBaVJ0c/5na2PEBSiOWcvKu6tJTHhauADhKH
+5r+npdlvRgoCVriBJ72Khy38pMYrI7SUnMD81ArBLc40+kECAwEAAaNTMFEwHQYD
+VR0OBBYEFMBWXUbAQba+bx4z8KPFJoqv7jBvMB8GA1UdIwQYMBaAFMBWXUbAQba+
+bx4z8KPFJoqv7jBvMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEB
+ACgcZnPU1/MsYGJSK7Lwu3vHV5MtMrbLmdCoHTFguo26moUHjjD/6BTDIv9sddp6
+G4/BGHr/QWuaowMzqDTspIKFNMF8Pi4YuZvR4mdUOfXtq33vEb76YcVeyLeHr1da
+ZJtySefk9o9igq7FRj65EtVcW9/gFsP8ztcolOHSgysTtopDkxra5xkS64w7BmZf
+OlVoX1v1dctFWz23lddM43tYURmJq+ai2YSBmTIDy+aWDAdyHTf+s0iMJ/F4O7FH
+6n9gQliYsXCWOekTbjnLGz8aRnfhqwGQ/aCjPBhLv2QVjgRpZ5gNLpeMx6TSAqJt
+vShbklJd013K4tjA/5wSVH4=
+-----END CERTIFICATE-----

package/src/fixtures-key.pem

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDNZrwSM/10WpdJ
+kfGDPdqFc2E4PoHUtsfEQJlO5K8jdUV3vF1RYNWoEy0Tm6c29DcR1eM7DfvbPgFa
+9QwWbsHH2l6URxpQA3+Lf3AFKUpesaCnVn+3BZOEZaBOQTirZFWM4KwJLWP8WVZO
+Uzdotv3zUq3Y+9Q/Odp1ocv/fyyiJz7kkTUWs3TzLN0RL3CTrztfmNCUAoskCHDH
+xkTXNuaYj0DoSWkA7pwYXElp0Rt0VjQmYsEML+jKMxB6v92QJ3ucqSQWlSdHP+Z2
+tjxAUojlnLyrurSUx4WrgA4Sh+a/p6XZb0YKAla4gSe9ioct/KTGKyO0lJzA/NQK
+wS3ONPpBAgMBAAECggEAMtMXeWec8SQTaFRxDtkIz9m3djvdU12w+6pCZSeoAJ2d
+hV26N48+/vpTvpTW4P23/LVQp0W0CtGCc1fMWGaqk4HAwm7/n0nmTwXHGbfYW6sX
+RiDctFRwZqPg8UwpMhu/IX9cgl7VbVVLylDEFqilGQbd1qGlqMlveYkCGeQFjs+2
+vfBkC9Oag3JmNkJvmbKxNU/Sg1s56ipr4cWzngz3n6bweWFUYUYyupSDvKV8tkWm
+gG3p2UltPN5dIFo0d6DRNcJrjdoiMPZADjcveW0Y1ceCxPnIpaeAzDb7kYQgkCYG
+iRAqP/7/wZqJt05cOEyvbcPduMbzd7iNFNTPbOwWywKBgQDoOsb4Zejs674lR2BN
+AkL/r+ESfnl7ezVvg2dxjOKk57dWZ9oip9iXPjiWNvZeM79pyEG7beJxVbvr7VH+
+GK5KNWEMa78JirgmjU7dmnhAJ09byH59pzofKNvdVfCWysGKLutnUsMzqisFJDGI
+WCfY/6IdcyEkxjNkEI7ylI1S4wKBgQDibPaCnvE365Il4U4KQKGdxmsIBFEJ9FNC
+vvdY6QdDfRIqcoOgks7GYYcP+wnC4kqLud1zqYGwB1koF9TFfimPo5t0lvFMtRR8
+LEFebtgHzNQDDbUo+Ud9vI6lN3IQJs5ezd+bjtZh4lvcTf98d/+Y4YiA8frJJone
+ZafoLV9ziwKBgClw67bCANnei7T9UrsLT0dvbFuvhCA78WIv8dK6kGtbCkV6DNwo
+VadPrCtqLXbMBzlqSgiXaFRPN1S3qe0NHHUTp3je9V1PiuMeTlePTCwul6PKWIA1
+ylJrKSkLP/64uebdzpZGl5ztnfWx6sDo8ltv6s8Uj3KPh/YwWkIBrmJ/AoGBALYT
+IPdQkHCDQfasAnFEH7IbyB2eOvxiOEHIBma8nFas0FrJ0wbght4HtvAm0magSYmq
+YGWNvPesMQmIgFR/azRSP8O1TTx9sIdZnwcs4xMCpsn9z9uu+MonQh2hRFuwmOqr
+alBQwBveRjgVkIiqhiKN2ZK3Aw+Vqe/oluig88yZAoGAffBD5P811mtiIHCfHjNJ
+doQYDaMrGbOmRb35fSP0zbkjipPrxLZ4VfGINl+R7ARfuzeAuf/12IDeijU+mDnZ
+B2qwnFAFbeR/nO3uN2CUJJMe8HPA4GllrEwUk2tKzbUZRP7tDUdbdKb4NI/sFwRo
+KCgT8P8cB6fwxXHI0bm8N9g=
+-----END PRIVATE KEY-----

package/src/fixtures-other-cert.pem

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDCTCCAfGgAwIBAgIUAzomCw25jCV7mNtPw2n+QlhutFkwDQYJKoZIhvcNAQEL
+BQAwFDESMBAGA1UEAwwJZmVkLW90aGVyMB4XDTI2MDUwOTA2MjcxNFoXDTM2MDUw
+NjA2MjcxNFowFDESMBAGA1UEAwwJZmVkLW90aGVyMIIBIjANBgkqhkiG9w0BAQEF
+AAOCAQ8AMIIBCgKCAQEAnvOVbMR+UkwpeiO2/bFzsT8FoxPD02xygTaBzEjTqenf
+UyW2hjKbs4n4lLsepAeIXCiBehvqXN8igQb0JrVjzw79IBH6VFVltJWWAmI3REqi
+cAeHgpvI8grWtdP71NqxaeIn1xF50InRozRiefiJV3L97QEW80v15c/wVQmVnIvl
+eWBz5atAR+3LyImU92nRNbEhqryut4np9CUCt893koRgJvkDH8ptskI8+kG27jIG
+Ppna0YOH+DRR6LeKfAcyzvL9dS5iY8gShMGu9EAuBwJqOpBnnpbLbAMd0OmrCELU
+LK7L1PPpCHEWG8dpUyzCxWuGhjPddZWQrCtizFMjlQIDAQABo1MwUTAdBgNVHQ4E
+FgQUZAzwEop03t58CqYfVC0p+EX8JQUwHwYDVR0jBBgwFoAUZAzwEop03t58CqYf
+VC0p+EX8JQUwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAPV1E
+SX+0JEr+9witMtq23mnHMOWFQhceRrelbxf3N5PhLWJVN7XEpKgYVpQEd0LuUj6K
+tav0BTEVpNJtwi0YgGNvyjxG8WvMoJt3MiuI1ekQ+WteEehQajCF9dxm2MN+wtkK
+7FD+NXJM+HpJP6xQrHipE2xqKMK52ANQWfm4FqUWjJgGcQnxzEE8jf0ZNlx+XR+n
+tD5ftM+M1VM8bR2KxTeC3jF/HOAOEaHCu+xShxwfJTxdO/oyx7wq52v/3gTC2eoH
+7bDN3oxzUgKPZB/P9xjAXhEnJHg75mHbulK/dEj/LmBW0QnYvSSv0ghqbV42rc/j
+cCMRZXPrb3BCN7rHHA==
+-----END CERTIFICATE-----

package/src/fixtures-other-key.pem

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCe85VsxH5STCl6
+I7b9sXOxPwWjE8PTbHKBNoHMSNOp6d9TJbaGMpuzifiUux6kB4hcKIF6G+pc3yKB
+BvQmtWPPDv0gEfpUVWW0lZYCYjdESqJwB4eCm8jyCta10/vU2rFp4ifXEXnQidGj
+NGJ5+IlXcv3tARbzS/Xlz/BVCZWci+V5YHPlq0BH7cvIiZT3adE1sSGqvK63ien0
+JQK3z3eShGAm+QMfym2yQjz6QbbuMgY+mdrRg4f4NFHot4p8BzLO8v11LmJjyBKE
+wa70QC4HAmo6kGeelstsAx3Q6asIQtQsrsvU8+kIcRYbx2lTLMLFa4aGM911lZCs
+K2LMUyOVAgMBAAECggEAJ3OhXZT6nn4RWGOnblm+M5rHESYdd2smE3yeJEBaKsTl
+vWsxnabPfvUqee3kqcVF2svh8RcfKQxn8bryW+4vFuwrNuvHZGmqu/LZv/81JPHa
+VfCEeY4lhq/agVhbW8Yo/TUY+tg3UiN24SlmHMxreEVOEaZw1hO/NVpSViTyGZ+6
+QaFU2+M3ZH95Svtmw9Qy1aY9qxjTUnbD7fm63CqXlCKNqJ1oDkpAAMa03Ufp4lxv
+nucIuLdThKGkZFq815Y4GbExb0XogsMd1tN00dkqYPF4b9uAPaSf/jtz3HaFHMuz
+Hr/PAhC/NyoVG6M7LXRDRYgNvlaK3bazRIoJBRgp8QKBgQDL1qjIGTsa2ulaTCzM
+Iyb+O1L2JwmxTAzBQZXD0b1LJbCsHQCQK/M06W1sETjk9h+yiRKNEjefFi89bSvJ
+JipbA+srsMO0fAVASIKmjVGaywvm1zquL1JAMr+0ZziMb8eRRuYyytPMwtOwaxp4
+z3TTONKRHZpCN0UPdcxfOO8/8QKBgQDHoGcPiA4HyaFfC5yQLx8jq2+lZZefZFWl
+bRPFYeo37xfYO+QItZV0nMz36NZYcWI9z+MuSmuvaHHCV27LQ9VtZqPxgPEqM8Qm
+Rhf38nBOAinGLeitaZKaS5BMf9VU6yoi+kKOZQtd+96GbQYdUmp3HNYIrXwzUxh5
+Mqr9Hv8B5QKBgCpgqVxYaoJNyr/cIGAcWsn2GWxVd11l2yz+bp10aG9MGavep7RR
+ftGcSgRynCp1xOdAOhwcEnY/jXiuzrCV/65GZUkDCdzm/8x6hrcLoFCXMBVA39FA
+w0/XfSWLZCVGQ+4/GDKtGlVyl8IQskM1lisnoBdNWTm09eWd7uxJEOxxAoGBAJq8
+A4avcCirKpFQn8/HJrzwUr8Ci096Z0St0uhpaDJo+rOaYLw7fBiCvgHfkd3GLV86
+N58XAndZXuxD91ZJQzLkn2lACC8tJvp/1G5VlqVw2c6KoVNhhMhij/wsDkEfc27f
+Sx2yxufXpnnOIjIyQuIHEQRy7NWfsFWpZ46CKyndAoGBAKBXTSFaaH0q7nlxfqN3
+agg/gg63MRjzWdIvWdFoNPm/5+M6ElxM6how34mYGUXSN0O+M9Dyeb+wdRFU3uqr
+jdU1uajgBEZZaf99XLxZ0mve5mwYQmmYqWQwYU1+ZDWMzNL6Q9RPMI6z2AuQ9YzI
+A8emo7hcJXJz0gFG3S9e5V/V
+-----END PRIVATE KEY-----

package/src/index.test.ts

@@ -0,0 +1,208 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+
+import {
+  FEDERATION_VERSION,
+  type FederationEnvelope,
+  FederationProtocolError,
+  type FederationTransport,
+  decodeFederationEnvelope,
+  encodeFederationEnvelope,
+  federationCall,
+  fingerprintCert,
+  validateCredentials,
+} from "./index";
+import { type FixtureCertSet, makeFixtureCertSet, makeFixtureCertSetOther } from "./test-helpers";
+
+const goodEnvelope: FederationEnvelope = {
+  version: FEDERATION_VERSION,
+  traceparent: "00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01",
+  federation: {
+    from: { deployment: "deployment-a", role: "researcher" },
+    to: { deployment: "deployment-b", role: "code-reviewer" },
+    mtls: { client_cert_subject: "CN=deployment-a" },
+  },
+  kind: "question",
+  payload: "review the patch in /tmp/x",
+};
+
+let certs: FixtureCertSet;
+let otherCerts: FixtureCertSet;
+
+beforeAll(() => {
+  certs = makeFixtureCertSet();
+  otherCerts = makeFixtureCertSetOther();
+});
+
+afterAll(() => {
+  certs.cleanup();
+  otherCerts.cleanup();
+});
+
+describe("encodeFederationEnvelope / decodeFederationEnvelope (T2)", () => {
+  test("round-trip happy path", () => {
+    const text = encodeFederationEnvelope(goodEnvelope);
+    const parsed = decodeFederationEnvelope(text);
+    expect(parsed).toEqual(goodEnvelope);
+  });
+
+  test("rejects invalid version", () => {
+    const bad = {
+      ...goodEnvelope,
+      version: "crewhaus.federation.v0",
+    } as unknown as FederationEnvelope;
+    expect(() => encodeFederationEnvelope(bad)).toThrow(/unsupported version/);
+    expect(() => decodeFederationEnvelope(JSON.stringify(bad))).toThrow(/unsupported version/);
+  });
+
+  test("rejects missing federation field", () => {
+    const bad = { ...goodEnvelope, federation: undefined } as unknown as FederationEnvelope;
+    expect(() => decodeFederationEnvelope(JSON.stringify(bad))).toThrow(/missing federation/);
+  });
+
+  test("rejects malformed party", () => {
+    const bad = JSON.parse(JSON.stringify(goodEnvelope)) as FederationEnvelope;
+    (bad.federation as unknown as { from: unknown }).from = { deployment: "x" };
+    expect(() => decodeFederationEnvelope(JSON.stringify(bad))).toThrow(/from\/to must be/);
+  });
+
+  test("rejects invalid kind", () => {
+    const bad = { ...goodEnvelope, kind: "explosion" } as unknown as FederationEnvelope;
+    expect(() => decodeFederationEnvelope(JSON.stringify(bad))).toThrow(/invalid kind/);
+  });
+
+  test("rejects non-string payload", () => {
+    const bad = { ...goodEnvelope, payload: 123 } as unknown as FederationEnvelope;
+    expect(() => decodeFederationEnvelope(JSON.stringify(bad))).toThrow(/payload must be a string/);
+  });
+
+  test("rejects missing traceparent", () => {
+    const bad = { ...goodEnvelope, traceparent: "" } as FederationEnvelope;
+    expect(() => decodeFederationEnvelope(JSON.stringify(bad))).toThrow(/traceparent/);
+  });
+
+  test("rejects malformed JSON", () => {
+    expect(() => decodeFederationEnvelope("{not json")).toThrow(FederationProtocolError);
+  });
+
+  test("decode rejects mtls.client_cert_subject missing", () => {
+    const bad = JSON.parse(JSON.stringify(goodEnvelope)) as FederationEnvelope;
+    (bad.federation as unknown as { mtls: unknown }).mtls = {};
+    expect(() => decodeFederationEnvelope(JSON.stringify(bad))).toThrow(/client_cert_subject/);
+  });
+});
+
+describe("validateCredentials (T8)", () => {
+  test("happy path accepts a valid set", () => {
+    expect(() =>
+      validateCredentials({
+        caCertPem: certs.caCertPem,
+        clientCertPem: certs.clientCertPem,
+        clientKeyPem: certs.clientKeyPem,
+        pinnedFingerprint: certs.pinnedFingerprint,
+      }),
+    ).not.toThrow();
+  });
+
+  test("rejects non-PEM ca", () => {
+    expect(() =>
+      validateCredentials({
+        caCertPem: "not a cert",
+        clientCertPem: certs.clientCertPem,
+        clientKeyPem: certs.clientKeyPem,
+        pinnedFingerprint: certs.pinnedFingerprint,
+      }),
+    ).toThrow(/caCertPem is not PEM-encoded/);
+  });
+
+  test("rejects non-PEM cert", () => {
+    expect(() =>
+      validateCredentials({
+        caCertPem: certs.caCertPem,
+        clientCertPem: "not a cert",
+        clientKeyPem: certs.clientKeyPem,
+        pinnedFingerprint: certs.pinnedFingerprint,
+      }),
+    ).toThrow(/clientCertPem is not PEM-encoded/);
+  });
+
+  test("rejects non-PEM key", () => {
+    expect(() =>
+      validateCredentials({
+        caCertPem: certs.caCertPem,
+        clientCertPem: certs.clientCertPem,
+        clientKeyPem: "not a key",
+        pinnedFingerprint: certs.pinnedFingerprint,
+      }),
+    ).toThrow(/clientKeyPem is not PEM-encoded/);
+  });
+
+  test("rejects malformed pinnedFingerprint (length)", () => {
+    expect(() =>
+      validateCredentials({
+        caCertPem: certs.caCertPem,
+        clientCertPem: certs.clientCertPem,
+        clientKeyPem: certs.clientKeyPem,
+        pinnedFingerprint: "abc",
+      }),
+    ).toThrow(/pinnedFingerprint must be 64-char hex/);
+  });
+
+  test("rejects malformed pinnedFingerprint (non-hex chars)", () => {
+    expect(() =>
+      validateCredentials({
+        caCertPem: certs.caCertPem,
+        clientCertPem: certs.clientCertPem,
+        clientKeyPem: certs.clientKeyPem,
+        pinnedFingerprint: "z".repeat(64),
+      }),
+    ).toThrow(/pinnedFingerprint must be 64-char hex/);
+  });
+});
+
+describe("fingerprintCert", () => {
+  test("matches the openssl-computed fingerprint", () => {
+    const fp = fingerprintCert(certs.clientCertPem);
+    expect(fp).toBe(certs.pinnedFingerprint);
+  });
+});
+
+describe("federationCall — injected transport (T2)", () => {
+  test("happy path round-trip", async () => {
+    const captured: Array<{ url: string; envelope: FederationEnvelope }> = [];
+    const transport: FederationTransport = async (url, envelope) => {
+      captured.push({ url, envelope });
+      return { status: 200, body: '{"reply":"ack"}' };
+    };
+    const result = await federationCall({
+      url: "https://deployment-b.example/federation",
+      envelope: goodEnvelope,
+      credentials: {
+        caCertPem: certs.caCertPem,
+        clientCertPem: certs.clientCertPem,
+        clientKeyPem: certs.clientKeyPem,
+        pinnedFingerprint: certs.pinnedFingerprint,
+      },
+      transport,
+    });
+    expect(result.status).toBe(200);
+    expect(captured[0]?.url).toBe("https://deployment-b.example/federation");
+    expect(captured[0]?.envelope).toEqual(goodEnvelope);
+  });
+
+  test("validates credentials before invoking transport", async () => {
+    const transport: FederationTransport = async () => ({ status: 200, body: "" });
+    await expect(
+      federationCall({
+        url: "https://deployment-b.example/",
+        envelope: goodEnvelope,
+        credentials: {
+          caCertPem: "not a cert",
+          clientCertPem: certs.clientCertPem,
+          clientKeyPem: certs.clientKeyPem,
+          pinnedFingerprint: certs.pinnedFingerprint,
+        },
+        transport,
+      }),
+    ).rejects.toThrow(/caCertPem is not PEM-encoded/);
+  });
+});

package/src/index.ts

@@ -0,0 +1,275 @@
+import { X509Certificate, createPrivateKey, createPublicKey } from "node:crypto";
+import { type Agent as HttpsAgent, type RequestOptions, request as httpsRequest } from "node:https";
+/**
+ * @crewhaus/federation-protocol — Section 34
+ *
+ * Cross-deployment A2A wire protocol. Extends the in-crew envelope from
+ * `@crewhaus/a2a-protocol` (Section 22) with `federation` fields:
+ *
+ *   {
+ *     ...A2AEnvelope,
+ *     version: "crewhaus.federation.v1",  // strict — rejected without exact match
+ *     federation: {
+ *       from: { deployment, role },
+ *       to:   { deployment, role },
+ *       mtls: { client_cert_subject }
+ *     }
+ *   }
+ *
+ * Transport: HTTPS POST with mutual TLS. Each deployment has a
+ * CA-issued certificate identifying its `deployment_id`; peers verify
+ * via cert pinning (SHA256 fingerprint check) plus standard TLS chain
+ * validation.
+ *
+ * Errors map to `recovery-engine` taxonomy:
+ *   - cert mismatch / expired → tombstone (auth failure)
+ *   - connection refused / timeout → retry with exponential backoff
+ *   - 5xx → retry; 4xx → tombstone
+ */
+import { CrewhausError } from "@crewhaus/errors";
+
+export class FederationProtocolError extends CrewhausError {
+  override readonly name = "FederationProtocolError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export const FEDERATION_VERSION = "crewhaus.federation.v1" as const;
+export type FederationVersion = typeof FEDERATION_VERSION;
+
+export type FederationParty = {
+  readonly deployment: string;
+  readonly role: string;
+};
+
+export type FederationEnvelope = {
+  readonly version: FederationVersion;
+  readonly traceparent: string;
+  readonly federation: {
+    readonly from: FederationParty;
+    readonly to: FederationParty;
+    readonly mtls: { readonly client_cert_subject: string };
+  };
+  /** A2A envelope kind, mirroring `@crewhaus/a2a-protocol`. */
+  readonly kind: "question" | "answer" | "notify";
+  /** Free-form message body — typically a question prompt. */
+  readonly payload: string;
+};
+
+export function encodeFederationEnvelope(envelope: FederationEnvelope): string {
+  validateEnvelope(envelope);
+  return JSON.stringify(envelope);
+}
+
+export function decodeFederationEnvelope(text: string): FederationEnvelope {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause) {
+    throw new FederationProtocolError("federation envelope: invalid JSON", cause);
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new FederationProtocolError("federation envelope: not an object");
+  }
+  const env = parsed as Record<string, unknown>;
+  if (env["version"] !== FEDERATION_VERSION) {
+    throw new FederationProtocolError(
+      `federation envelope: unsupported version ${String(env["version"])} (expected ${FEDERATION_VERSION})`,
+    );
+  }
+  validateEnvelope(env as unknown as FederationEnvelope);
+  return env as unknown as FederationEnvelope;
+}
+
+function validateEnvelope(env: FederationEnvelope): void {
+  if (env.version !== FEDERATION_VERSION) {
+    throw new FederationProtocolError(`unsupported version ${String(env.version)}`);
+  }
+  if (!env.federation || typeof env.federation !== "object") {
+    throw new FederationProtocolError("federation envelope: missing federation field");
+  }
+  const f = env.federation;
+  if (!isParty(f.from) || !isParty(f.to)) {
+    throw new FederationProtocolError("federation envelope: from/to must be {deployment,role}");
+  }
+  if (!f.mtls || typeof f.mtls.client_cert_subject !== "string") {
+    throw new FederationProtocolError("federation envelope: missing mtls.client_cert_subject");
+  }
+  if (env.kind !== "question" && env.kind !== "answer" && env.kind !== "notify") {
+    throw new FederationProtocolError(`federation envelope: invalid kind ${String(env.kind)}`);
+  }
+  if (typeof env.payload !== "string") {
+    throw new FederationProtocolError("federation envelope: payload must be a string");
+  }
+  if (typeof env.traceparent !== "string" || env.traceparent.length === 0) {
+    throw new FederationProtocolError("federation envelope: missing traceparent");
+  }
+}
+
+function isParty(p: unknown): p is FederationParty {
+  return (
+    typeof p === "object" &&
+    p !== null &&
+    typeof (p as FederationParty).deployment === "string" &&
+    typeof (p as FederationParty).role === "string" &&
+    (p as FederationParty).deployment.length > 0 &&
+    (p as FederationParty).role.length > 0
+  );
+}
+
+// ─── mTLS transport ────────────────────────────────────────────────────────
+
+export type MtlsCredentials = {
+  /** PEM-encoded CA bundle the peer's cert chain must validate against. */
+  readonly caCertPem: string;
+  /** PEM-encoded client certificate this deployment presents. */
+  readonly clientCertPem: string;
+  /** PEM-encoded private key matching `clientCertPem`. */
+  readonly clientKeyPem: string;
+  /**
+   * SHA256 fingerprint of the peer's expected leaf cert (hex, lowercase,
+   * 64 chars; no `:` separators). Strict pin: any other cert is rejected
+   * even if it chains to the same CA.
+   */
+  readonly pinnedFingerprint: string;
+};
+
+export type FederationTransport = (
+  url: string,
+  envelope: FederationEnvelope,
+  creds: MtlsCredentials,
+) => Promise<{ status: number; body: string }>;
+
+export type FederationCallOptions = {
+  readonly url: string;
+  readonly envelope: FederationEnvelope;
+  readonly credentials: MtlsCredentials;
+  /** Test injection point. Defaults to a real `node:https` POST. */
+  readonly transport?: FederationTransport;
+  /** Timeout in ms. Default 30s. */
+  readonly timeoutMs?: number;
+};
+
+export async function federationCall(
+  opts: FederationCallOptions,
+): Promise<{ status: number; body: string }> {
+  validateCredentials(opts.credentials);
+  const transport = opts.transport ?? defaultTransport(opts.timeoutMs ?? 30_000);
+  return transport(opts.url, opts.envelope, opts.credentials);
+}
+
+/**
+ * Asserts the credentials are well-formed BEFORE we try to build a TLS
+ * agent. Surfaces clear, actionable errors instead of openssl-flavoured
+ * mystery.
+ */
+export function validateCredentials(creds: MtlsCredentials): void {
+  if (!creds.caCertPem.includes("-----BEGIN CERTIFICATE-----")) {
+    throw new FederationProtocolError("credentials: caCertPem is not PEM-encoded");
+  }
+  if (!creds.clientCertPem.includes("-----BEGIN CERTIFICATE-----")) {
+    throw new FederationProtocolError("credentials: clientCertPem is not PEM-encoded");
+  }
+  if (
+    !creds.clientKeyPem.includes("-----BEGIN PRIVATE KEY-----") &&
+    !creds.clientKeyPem.includes("-----BEGIN RSA PRIVATE KEY-----") &&
+    !creds.clientKeyPem.includes("-----BEGIN EC PRIVATE KEY-----")
+  ) {
+    throw new FederationProtocolError("credentials: clientKeyPem is not PEM-encoded");
+  }
+  if (!/^[0-9a-f]{64}$/.test(creds.pinnedFingerprint)) {
+    throw new FederationProtocolError(
+      `credentials: pinnedFingerprint must be 64-char hex sha256 (got ${creds.pinnedFingerprint.length} chars)`,
+    );
+  }
+  // Sanity: keys parse + cert parses + cert hasn't expired
+  try {
+    createPublicKey(creds.clientCertPem);
+    createPrivateKey(creds.clientKeyPem);
+  } catch (cause) {
+    throw new FederationProtocolError("credentials: client cert/key did not parse", cause);
+  }
+  try {
+    const cert = new X509Certificate(creds.clientCertPem);
+    const now = Date.now();
+    if (Date.parse(cert.validTo) < now) {
+      throw new FederationProtocolError(`credentials: client cert expired at ${cert.validTo}`);
+    }
+  } catch (cause) {
+    if (cause instanceof FederationProtocolError) throw cause;
+    throw new FederationProtocolError("credentials: client cert parse failed", cause);
+  }
+}
+
+/** Compute the SHA256 fingerprint of a PEM-encoded cert (hex, no separators). */
+export function fingerprintCert(certPem: string): string {
+  const cert = new X509Certificate(certPem);
+  return cert.fingerprint256.replaceAll(":", "").toLowerCase();
+}
+
+/** Default transport — real `node:https` POST with mTLS + cert pinning. */
+function defaultTransport(timeoutMs: number): FederationTransport {
+  return async (url, envelope, creds) => {
+    const u = new URL(url);
+    if (u.protocol !== "https:") {
+      throw new FederationProtocolError(
+        `federation transport requires https://, got ${u.protocol}`,
+      );
+    }
+    const body = encodeFederationEnvelope(envelope);
+    const opts: RequestOptions = {
+      method: "POST",
+      protocol: u.protocol,
+      hostname: u.hostname,
+      port: u.port || 443,
+      path: `${u.pathname}${u.search}`,
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body, "utf8").toString(),
+        "X-Crewhaus-Federation-Version": FEDERATION_VERSION,
+      },
+      ca: creds.caCertPem,
+      cert: creds.clientCertPem,
+      key: creds.clientKeyPem,
+      rejectUnauthorized: true,
+      timeout: timeoutMs,
+      checkServerIdentity: (_host, cert) => {
+        // Strict pin: the peer's leaf cert fingerprint must match exactly.
+        const fp = cert.fingerprint256?.replaceAll(":", "").toLowerCase() ?? "";
+        if (fp !== creds.pinnedFingerprint) {
+          return new Error(
+            `cert-pin mismatch: peer fingerprint ${fp} != pinned ${creds.pinnedFingerprint}`,
+          );
+        }
+        return undefined;
+      },
+    };
+
+    return new Promise((resolve, reject) => {
+      const req = httpsRequest(opts, (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (c) => chunks.push(c as Buffer));
+        res.on("end", () =>
+          resolve({
+            status: res.statusCode ?? 0,
+            body: Buffer.concat(chunks).toString("utf8"),
+          }),
+        );
+      });
+      req.on("error", (err) =>
+        reject(new FederationProtocolError(`federation transport error: ${err.message}`, err)),
+      );
+      req.on("timeout", () => {
+        req.destroy(
+          new FederationProtocolError(`federation transport timeout after ${timeoutMs}ms`),
+        );
+      });
+      req.write(body);
+      req.end();
+    });
+  };
+}
+
+/** Re-export for callers that need to spawn their own agent (rare). */
+export type { HttpsAgent };

package/src/test-helpers.ts

@@ -0,0 +1,66 @@
+/**
+ * Test helpers for federation-protocol — read pre-generated fixture
+ * certs from disk so tests don't shell to openssl on every run.
+ *
+ * The fixture certs are self-signed RSA 2048, valid for 10 years, with
+ * CN=fed-fixture (and CN=fed-other for the "wrong key" pair). Generated
+ * once via:
+ *
+ *   openssl req -x509 -newkey rsa:2048 -nodes \
+ *     -keyout fixtures-key.pem -out fixtures-cert.pem \
+ *     -days 3650 -subj "/CN=fed-fixture" -sha256
+ *
+ * Test-only secrets — no production deployment uses these.
+ *
+ * Earlier iterations shelled to openssl on every test run; that timed
+ * out on CI runners with slow entropy and racy `openssl x509 ...
+ * -fingerprint -sha256` invocations. Static fixtures are deterministic
+ * + fast (~1 ms read).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { fingerprintCert } from "./index";
+
+export type FixtureCertSet = {
+  readonly caCertPem: string;
+  readonly clientCertPem: string;
+  readonly clientKeyPem: string;
+  readonly pinnedFingerprint: string;
+  /** No-op — kept for backwards compat with the old openssl-based helper. */
+  readonly cleanup: () => void;
+};
+
+// `tsc -b` also compiles this file into `dist/`, but the PEM fixtures live
+// next to the source. Map the dist path back so the dist copy finds them too.
+const FIXTURES_DIR = import.meta.dir.replace(/([/\\])dist$/, "$1src");
+
+/**
+ * Returns the canonical fixture cert pair (CN=fed-fixture). The
+ * `_commonName` arg is accepted for backwards compat with the
+ * generate-on-the-fly helper this replaced; it has no effect.
+ */
+export function makeFixtureCertSet(_commonName = "fed-fixture"): FixtureCertSet {
+  return readFixtures("fixtures-cert.pem", "fixtures-key.pem");
+}
+
+/**
+ * Returns a second, unrelated cert pair (CN=fed-other) — used by the
+ * "wrong public key" / "tampered cert" tests to assert pinning rejects
+ * keys that don't match the configured fingerprint.
+ */
+export function makeFixtureCertSetOther(): FixtureCertSet {
+  return readFixtures("fixtures-other-cert.pem", "fixtures-other-key.pem");
+}
+
+function readFixtures(certFile: string, keyFile: string): FixtureCertSet {
+  const certPem = readFileSync(join(FIXTURES_DIR, certFile), "utf8");
+  const keyPem = readFileSync(join(FIXTURES_DIR, keyFile), "utf8");
+  return {
+    caCertPem: certPem,
+    clientCertPem: certPem,
+    clientKeyPem: keyPem,
+    pinnedFingerprint: fingerprintCert(certPem),
+    cleanup: () => undefined,
+  };
+}