feat: rename keyId → issuerKeyId and add optional issuer field on envelopes

NAOR YUVAL · claude · NAOR YUVAL · commit 35f30d361648 · 2026-03-13T21:53:56.000+02:00
Aligns signed envelope structure with the spec (SignedBudgetAuthorization.md,
SignedPaymentAuthorization.md): the canonical field name is now `issuerKeyId`
and an optional `issuer` field (DID / domain for key resolution) is added to
SBA, SPA, and FleetPolicyAuthorization envelopes.

`keyId` is retired — all schemas, type interfaces, source code, tests, JSON
fixtures, golden vectors, and example files updated. All 166 tests pass.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/examples/ev-charging/settlement-bundle.json b/examples/ev-charging/settlement-bundle.json
@@ -42,7 +42,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "+Oz+9+eGK32BeGW8FON0hj66wcPhN23TZ9xec9HZfLwC2oeKMDLBFZZCYTIh0Me8AxJbKQ0Jv+lOU6ZsIKOrDA==",
-    "keyId": "mpcp-spa-signing-key-1"
+    "issuerKeyId": "mpcp-spa-signing-key-1"
   },
   "sba": {
     "authorization": {
@@ -72,7 +72,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "WT0EExkYrd9KmjNtxR92YKfLOdpdLbgVAPuwZoP7+f+uioGz+N30kQICJAnIAB8mo8dacQz1otJZz17EfSCPCg==",
-    "keyId": "mpcp-sba-signing-key-1"
+    "issuerKeyId": "mpcp-sba-signing-key-1"
   },
   "policyGrant": {
     "grantId": "5ad06052-234c-49e8-8719-3a6ca6b3965a",
diff --git a/examples/ev-charging/signed-budget-auth.json b/examples/ev-charging/signed-budget-auth.json
@@ -26,5 +26,5 @@
     "expiresAt": "2030-12-31T23:59:59Z"
   },
   "signature": "WT0EExkYrd9KmjNtxR92YKfLOdpdLbgVAPuwZoP7+f+uioGz+N30kQICJAnIAB8mo8dacQz1otJZz17EfSCPCg==",
-  "keyId": "mpcp-sba-signing-key-1"
+  "issuerKeyId": "mpcp-sba-signing-key-1"
 }
diff --git a/examples/ev-charging/spa.json b/examples/ev-charging/spa.json
@@ -18,5 +18,5 @@
     "expiresAt": "2030-12-31T23:59:59Z"
   },
   "signature": "+Oz+9+eGK32BeGW8FON0hj66wcPhN23TZ9xec9HZfLwC2oeKMDLBFZZCYTIh0Me8AxJbKQ0Jv+lOU6ZsIKOrDA==",
-  "keyId": "mpcp-spa-signing-key-1"
+  "issuerKeyId": "mpcp-spa-signing-key-1"
 }
diff --git a/examples/machine-commerce/fleet-demo-bundle.json b/examples/machine-commerce/fleet-demo-bundle.json
@@ -42,7 +42,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "+UOifTtjdYclt1KUNWJZinTHcE7hwcoqy6XmLNznCPoqKyjoqZhLqdm4fY8DNz0HSwXr6FGXxZbNxfYE2eLECw==",
-    "keyId": "mpcp-spa-signing-key-1"
+    "issuerKeyId": "mpcp-spa-signing-key-1"
   },
   "sba": {
     "authorization": {
@@ -73,7 +73,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "BlAUBUG3Ys0E/fXMdk97imKSu+wnjCK5m1BLuG5JQV4fv7WnNnpv9WEf5ecyttW53vP40XGFu95GUWfOvnxLDw==",
-    "keyId": "mpcp-sba-signing-key-1"
+    "issuerKeyId": "mpcp-sba-signing-key-1"
   },
   "policyGrant": {
     "grantId": "902c3c94-22a6-485e-af72-c9623c285482",
diff --git a/examples/parking/guardrails-demo-bundle.json b/examples/parking/guardrails-demo-bundle.json
@@ -41,7 +41,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "pQBITmq+fxF6P5p2LGToKNYAHkwFoWRvul7BKZJEV6Crkc9NgiStW3QUUJoeS9gOFlINsf41/nNw/ofvf2nPCg==",
-    "keyId": "mpcp-spa-signing-key-1"
+    "issuerKeyId": "mpcp-spa-signing-key-1"
   },
   "sba": {
     "authorization": {
@@ -70,7 +70,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "DLfH2/gCHz2Lbj/V/vKUCldMiGHUZ/RThjpos1ko6DRC2AEt2lVVPdX5gzelSWv6xBhccK7HjtG3zEWdC1uCAg==",
-    "keyId": "mpcp-sba-signing-key-1"
+    "issuerKeyId": "mpcp-sba-signing-key-1"
   },
   "policyGrant": {
     "grantId": "91abbafa-339d-441e-8558-36a0792258c7",
diff --git a/examples/parking/offline-demo-bundle.json b/examples/parking/offline-demo-bundle.json
@@ -41,7 +41,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "N2QYryTuhmxZKnKa42tetS9H+E73EmiTX0ZlfZjZ3HF+pcwCaCGLvRJt7wl4mPT4jzfel93e1CrmwiJGhY1FCQ==",
-    "keyId": "mpcp-spa-signing-key-1"
+    "issuerKeyId": "mpcp-spa-signing-key-1"
   },
   "sba": {
     "authorization": {
@@ -70,7 +70,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "aPhw4N0yj4H2GsFj/GFPyEf+8Famb6xaLOnVHtnKU+LFKKHqy522MAUyguGVSPZy/SOs3uPdB1OQ8tBTraOzBA==",
-    "keyId": "mpcp-sba-signing-key-1"
+    "issuerKeyId": "mpcp-sba-signing-key-1"
   },
   "policyGrant": {
     "grantId": "53042784-ef6c-4e3e-bd1b-a65d36bf9aae",
diff --git a/examples/parking/settlement-bundle.json b/examples/parking/settlement-bundle.json
@@ -42,7 +42,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "VFi1xdnwhqB1diVwkd+XQOKP4CqZzWG2joScWEa2ZDGzDjOKMPSKRFEOdUQZfHtM2XDrY7vEHUeUOsyDHgKzCw==",
-    "keyId": "mpcp-spa-signing-key-1"
+    "issuerKeyId": "mpcp-spa-signing-key-1"
   },
   "sba": {
     "authorization": {
@@ -72,7 +72,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "6X8LV6FJfT7huuaxE+H1AM/PlB+/7xUq5zBjsDGuw4zkdEqgi22TFAW3zT1RByJaqOyrMHj6Oou4ItlLtvWUAA==",
-    "keyId": "mpcp-sba-signing-key-1"
+    "issuerKeyId": "mpcp-sba-signing-key-1"
   },
   "policyGrant": {
     "grantId": "0f9576ad-eefe-460d-ab25-9f5dc3785a4a",
diff --git a/examples/parking/signed-budget-auth.json b/examples/parking/signed-budget-auth.json
@@ -26,5 +26,5 @@
     "expiresAt": "2030-12-31T23:59:59Z"
   },
   "signature": "6X8LV6FJfT7huuaxE+H1AM/PlB+/7xUq5zBjsDGuw4zkdEqgi22TFAW3zT1RByJaqOyrMHj6Oou4ItlLtvWUAA==",
-  "keyId": "mpcp-sba-signing-key-1"
+  "issuerKeyId": "mpcp-sba-signing-key-1"
 }
diff --git a/examples/parking/spa.json b/examples/parking/spa.json
@@ -18,5 +18,5 @@
     "expiresAt": "2030-12-31T23:59:59Z"
   },
   "signature": "VFi1xdnwhqB1diVwkd+XQOKP4CqZzWG2joScWEa2ZDGzDjOKMPSKRFEOdUQZfHtM2XDrY7vEHUeUOsyDHgKzCw==",
-  "keyId": "mpcp-spa-signing-key-1"
+  "issuerKeyId": "mpcp-spa-signing-key-1"
 }
diff --git a/examples/xrpl-stablecoin/xrpl-stablecoin-bundle.json b/examples/xrpl-stablecoin/xrpl-stablecoin-bundle.json
@@ -41,7 +41,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "IieBKYdf/Q52SU+AQtuCQTAR+say2jHrQz60ZUlSdmKS3K3BIwcS0e3WaYsfnHtdpzMH2W9MBr6DemTkbuhvDQ==",
-    "keyId": "mpcp-spa-signing-key-1"
+    "issuerKeyId": "mpcp-spa-signing-key-1"
   },
   "sba": {
     "authorization": {
@@ -70,7 +70,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "Oo6kj3SNTViIsFI4KndCWDCxBirLMs/wB3Eu2PFR8BySdObgw1UPHNjE40fY6tu40MWp/hULUEvcPmJ9zhtMCA==",
-    "keyId": "mpcp-sba-signing-key-1"
+    "issuerKeyId": "mpcp-sba-signing-key-1"
   },
   "policyGrant": {
     "grantId": "a851605b-1c3e-470e-ae60-72e782d647da",
@@ -129,4 +129,4 @@
   },
   "sbaPublicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAFpsRC3XWth29Kj9+HK35B/eXJU9+CO566ESYenq89e8=\n-----END PUBLIC KEY-----\n",
   "spaPublicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6hGgw1Vh8e36ymujNtvDP9B3cdfSzNrgQ+3Bo2pvEeo=\n-----END PUBLIC KEY-----\n"
-}
+}
diff --git a/src/cli/verify.ts b/src/cli/verify.ts
@@ -68,13 +68,13 @@ export function runVerify(
       saved.MPCP_SBA_SIGNING_PUBLIC_KEY_PEM = process.env.MPCP_SBA_SIGNING_PUBLIC_KEY_PEM;
       saved.MPCP_SBA_SIGNING_KEY_ID = process.env.MPCP_SBA_SIGNING_KEY_ID;
       process.env.MPCP_SBA_SIGNING_PUBLIC_KEY_PEM = data.sbaPublicKeyPem;
-      process.env.MPCP_SBA_SIGNING_KEY_ID = data.sba.keyId;
+      process.env.MPCP_SBA_SIGNING_KEY_ID = data.sba.issuerKeyId;
     }
     if (data.spaPublicKeyPem) {
       saved.MPCP_SPA_SIGNING_PUBLIC_KEY_PEM = process.env.MPCP_SPA_SIGNING_PUBLIC_KEY_PEM;
       saved.MPCP_SPA_SIGNING_KEY_ID = process.env.MPCP_SPA_SIGNING_KEY_ID;
       process.env.MPCP_SPA_SIGNING_PUBLIC_KEY_PEM = data.spaPublicKeyPem;
-      process.env.MPCP_SPA_SIGNING_KEY_ID = data.spa.keyId;
+      process.env.MPCP_SPA_SIGNING_KEY_ID = data.spa.issuerKeyId;
     }
   }
 
diff --git a/src/protocol/sba.ts b/src/protocol/sba.ts
@@ -24,8 +24,9 @@ export interface SessionBudgetAuthorization {
 
 export interface SignedSessionBudgetAuthorization {
   authorization: SessionBudgetAuthorization;
+  issuer?: string;
+  issuerKeyId: string;
   signature: string;
-  keyId: string;
 }
 
 function hashAuthorization(authorization: SessionBudgetAuthorization): Buffer {
@@ -99,16 +100,16 @@ export function createSignedSessionBudgetAuthorization(input: {
   const signature = crypto.sign(null, hashAuthorization(authorization), privateKey).toString("base64");
   return {
     authorization,
+    issuerKeyId: getExpectedKeyId(),
     signature,
-    keyId: getExpectedKeyId(),
   };
 }
 
 export function verifySignedSessionBudgetAuthorizationForDecision(
   envelope: SignedSessionBudgetAuthorization,
   input: { sessionId: string; decision: PaymentPolicyDecision; nowMs?: number },
 ): { ok: true } | { ok: false; reason: "invalid_signature" | "expired" | "budget_exceeded" | "mismatch" } {
-  if (envelope.keyId !== getExpectedKeyId()) return { ok: false, reason: "invalid_signature" };
+  if (envelope.issuerKeyId !== getExpectedKeyId()) return { ok: false, reason: "invalid_signature" };
   const publicKey = parseVerificationPublicKey();
   if (!publicKey) return { ok: false, reason: "invalid_signature" };
 
diff --git a/src/protocol/schema/fleetPolicyAuthorization.ts b/src/protocol/schema/fleetPolicyAuthorization.ts
@@ -27,8 +27,9 @@ export const fleetPolicyAuthorizationPayloadSchema = z.strictObject({
 
 export const fleetPolicyAuthorizationSchema = z.strictObject({
   authorization: fleetPolicyAuthorizationPayloadSchema,
+  issuer: z.string().optional(),
+  issuerKeyId: z.string(),
   signature: z.string(),
-  keyId: z.string(),
 });
 
 export type FleetPolicyAuthorizationPayload = z.infer<typeof fleetPolicyAuthorizationPayloadSchema>;
diff --git a/src/protocol/schema/paymentAuthorization.ts b/src/protocol/schema/paymentAuthorization.ts
@@ -25,8 +25,9 @@ export const paymentAuthorizationSchema = z.strictObject({
 
 export const signedPaymentAuthorizationSchema = z.strictObject({
   authorization: paymentAuthorizationSchema,
+  issuer: z.string().optional(),
+  issuerKeyId: z.string(),
   signature: z.string(),
-  keyId: z.string(),
 });
 
 export type PaymentAuthorization = z.infer<typeof paymentAuthorizationSchema>;
diff --git a/src/protocol/schema/signedBudgetAuthorization.ts b/src/protocol/schema/signedBudgetAuthorization.ts
@@ -3,8 +3,9 @@ import { budgetAuthorizationSchema } from "./budgetAuthorization.js";
 
 export const signedBudgetAuthorizationSchema = z.strictObject({
   authorization: budgetAuthorizationSchema,
+  issuer: z.string().optional(),
+  issuerKeyId: z.string(),
   signature: z.string(),
-  keyId: z.string(),
 });
 
 export type SignedBudgetAuthorization = z.infer<typeof signedBudgetAuthorizationSchema>;
diff --git a/src/protocol/spa.ts b/src/protocol/spa.ts
@@ -19,8 +19,9 @@ export interface PaymentAuthorization {
 
 export interface SignedPaymentAuthorization {
   authorization: PaymentAuthorization;
+  issuer?: string;
+  issuerKeyId: string;
   signature: string;
-  keyId: string;
 }
 
 function getExpectedSigningKeyId(): string {
@@ -113,7 +114,7 @@ export function createSignedPaymentAuthorization(
   if (!authorization || !privateKey) return null;
 
   const signature = crypto.sign(null, hashAuthorization(authorization), privateKey).toString("base64");
-  return { authorization, signature, keyId: getExpectedSigningKeyId() };
+  return { authorization, issuerKeyId: getExpectedSigningKeyId(), signature };
 }
 
 export function verifySignedPaymentAuthorizationForSettlement(
@@ -122,7 +123,7 @@ export function verifySignedPaymentAuthorizationForSettlement(
   settlement: SettlementResult,
   options?: { nowISO?: string; nowMs?: number; settlementIntent?: unknown },
 ): { ok: true } | { ok: false; reason: "invalid_signature" | "expired" | "mismatch" } {
-  if (envelope.keyId !== getExpectedSigningKeyId()) return { ok: false, reason: "invalid_signature" };
+  if (envelope.issuerKeyId !== getExpectedSigningKeyId()) return { ok: false, reason: "invalid_signature" };
 
   const publicKey = parseVerificationPublicKey();
   if (!publicKey) return { ok: false, reason: "invalid_signature" };
diff --git a/test/fixtures/settlement.json b/test/fixtures/settlement.json
@@ -42,7 +42,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "K4lftg4R8EnhBriA91fxudI1viM/x3LQHkTgFecFK7OW6iPOOhjq8Ds2TLxmVZz4KD0cS42u8ovPYanzgY5UDg==",
-    "keyId": "mpcp-sba-signing-key-1"
+    "issuerKeyId": "mpcp-sba-signing-key-1"
   },
   "signedPaymentAuthorization": {
     "authorization": {
@@ -64,7 +64,7 @@
       "expiresAt": "2030-12-31T23:59:59Z"
     },
     "signature": "SVpmJHwoJFyHsBuLoTDOpmaGNA0pHgUQgzqq3XjmF+7IMnwR2c4jAFU5Oig/WlS1/U/U0MOZwZEk7MLpJB0dBA==",
-    "keyId": "mpcp-spa-signing-key-1"
+    "issuerKeyId": "mpcp-spa-signing-key-1"
   },
   "settlement": {
     "amount": "19440000",
diff --git a/test/schema/artifact-schemas.test.ts b/test/schema/artifact-schemas.test.ts
@@ -179,25 +179,25 @@ describe("SignedBudgetAuthorization schema", () => {
   it("accepts valid envelope", () => {
     const result = validateWithSchema(signedBudgetAuthorizationSchema, {
       authorization: validBudgetAuthorization,
+      issuerKeyId: "mpcp-sba-signing-key-1",
       signature: "base64...",
-      keyId: "mpcp-sba-signing-key-1",
     });
     expect(result.ok).toBe(true);
   });
 
   it("rejects missing signature", () => {
     const result = validateWithSchema(signedBudgetAuthorizationSchema, {
       authorization: validBudgetAuthorization,
-      keyId: "key",
+      issuerKeyId: "key",
     });
     expect(result.ok).toBe(false);
   });
 
   it("rejects unexpected fields (strict)", () => {
     const result = validateWithSchema(signedBudgetAuthorizationSchema, {
       authorization: validBudgetAuthorization,
+      issuerKeyId: "key",
       signature: "base64...",
-      keyId: "key",
       unknown: true,
     });
     expect(result.ok).toBe(false);
@@ -239,17 +239,17 @@ describe("SignedPaymentAuthorization schema", () => {
   it("accepts valid envelope", () => {
     const result = validateWithSchema(signedPaymentAuthorizationSchema, {
       authorization: validPaymentAuthorization,
+      issuerKeyId: "mpcp-spa-signing-key-1",
       signature: "base64...",
-      keyId: "mpcp-spa-signing-key-1",
     });
     expect(result.ok).toBe(true);
   });
 
   it("rejects unexpected fields (strict)", () => {
     const result = validateWithSchema(signedPaymentAuthorizationSchema, {
       authorization: validPaymentAuthorization,
+      issuerKeyId: "key",
       signature: "base64...",
-      keyId: "key",
       unknownField: "invalid",
     });
     expect(result.ok).toBe(false);
@@ -291,17 +291,17 @@ describe("FleetPolicyAuthorization schema", () => {
   it("accepts valid FleetPolicyAuthorization", () => {
     const result = validateWithSchema(fleetPolicyAuthorizationSchema, {
       authorization: validFleetPolicyPayload,
+      issuerKeyId: "fleet-signing-key-1",
       signature: "base64...",
-      keyId: "fleet-signing-key-1",
     });
     expect(result.ok).toBe(true);
   });
 
   it("rejects unexpected fields in envelope (strict)", () => {
     const result = validateWithSchema(fleetPolicyAuthorizationSchema, {
       authorization: validFleetPolicyPayload,
+      issuerKeyId: "key",
       signature: "base64...",
-      keyId: "key",
       unwanted: true,
     });
     expect(result.ok).toBe(false);
@@ -310,8 +310,8 @@ describe("FleetPolicyAuthorization schema", () => {
   it("rejects unexpected fields in payload (strict)", () => {
     const result = validateWithSchema(fleetPolicyAuthorizationSchema, {
       authorization: { ...validFleetPolicyPayload, invalidPayloadField: "x" },
+      issuerKeyId: "key",
       signature: "base64...",
-      keyId: "key",
     });
     expect(result.ok).toBe(false);
   });
@@ -327,13 +327,13 @@ const validArtifactBundle = {
   },
   sba: {
     authorization: validBudgetAuthorization,
+    issuerKeyId: "mpcp-sba-signing-key-1",
     signature: "base64...",
-    keyId: "mpcp-sba-signing-key-1",
   },
   spa: {
     authorization: validPaymentAuthorization,
+    issuerKeyId: "mpcp-spa-signing-key-1",
     signature: "base64...",
-    keyId: "mpcp-spa-signing-key-1",
   },
   settlement: {
     amount: "19440000",
diff --git a/test/vectors/budget-exceeded.json b/test/vectors/budget-exceeded.json
diff --git a/test/vectors/expired-grant.json b/test/vectors/expired-grant.json
diff --git a/test/vectors/goldenVectors.test.ts b/test/vectors/goldenVectors.test.ts
diff --git a/test/vectors/intent-hash-mismatch.json b/test/vectors/intent-hash-mismatch.json
diff --git a/test/vectors/settlement-mismatch.json b/test/vectors/settlement-mismatch.json
diff --git a/test/vectors/valid-settlement.json b/test/vectors/valid-settlement.json
diff --git a/test/verify/verifyDisputedSettlement.test.ts b/test/verify/verifyDisputedSettlement.test.ts

Original file line number	Diff line number	Diff line change
`@@ -26,5 +26,5 @@`
`26`	`26`	`"expiresAt": "2030-12-31T23:59:59Z"`
`27`	`27`	`},`
`28`	`28`	`"signature": "WT0EExkYrd9KmjNtxR92YKfLOdpdLbgVAPuwZoP7+f+uioGz+N30kQICJAnIAB8mo8dacQz1otJZz17EfSCPCg==",`
`29`		`- "keyId": "mpcp-sba-signing-key-1"`
	`29`	`+ "issuerKeyId": "mpcp-sba-signing-key-1"`
`30`	`30`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,5 +18,5 @@`
`18`	`18`	`"expiresAt": "2030-12-31T23:59:59Z"`
`19`	`19`	`},`
`20`	`20`	`"signature": "+Oz+9+eGK32BeGW8FON0hj66wcPhN23TZ9xec9HZfLwC2oeKMDLBFZZCYTIh0Me8AxJbKQ0Jv+lOU6ZsIKOrDA==",`
`21`		`- "keyId": "mpcp-spa-signing-key-1"`
	`21`	`+ "issuerKeyId": "mpcp-spa-signing-key-1"`
`22`	`22`	`}`