Merge pull request #39 from mpcp-protocol/fix/security-hardening

fix: security hardening — policyHash min, SPA nonce, PolicyGrant signing, cumulative budget, hash binding

Author: naory

docs/reference/sdk.md

@@ -32,14 +32,17 @@ import {
 ## Policy Grant
 
 ```typescript
-import { createPolicyGrant } from "mpcp-service/sdk";
+import { createPolicyGrant, createSignedPolicyGrant } from "mpcp-service/sdk";
 
 const grant = createPolicyGrant({
-  policyHash: "a1b2c3",
+  policyHash: "a1b2c3d4e5f6",
   allowedRails: ["xrpl", "evm"],
   allowedAssets: [{ kind: "IOU", currency: "RLUSD", issuer: "rIssuer" }],
   expiresAt: "2030-12-31T23:59:59Z",
 });
+
+// Signed (requires MPCP_POLICY_GRANT_SIGNING_PRIVATE_KEY_PEM — returns null if not set)
+const signedGrant = createSignedPolicyGrant(grant);
 ```
 
 ## Budget Authorization
@@ -129,6 +132,19 @@ const { result, steps } = verifySettlementWithReport(context);
 const { valid, checks } = verifySettlementDetailed(context);
 ```
 
+## Cumulative Budget Enforcement
+
+When performing multiple payments in a session, pass `cumulativeSpentMinor` to the verification context so the budget check accounts for all prior spending:
+
+```typescript
+const result = verifySettlement({
+  ...context,
+  cumulativeSpentMinor: "5000", // total minor-unit amount spent before this payment
+});
+```
+
+The session authority MUST maintain this counter. The verifier is stateless and will not track prior payments on its own.
+
 ## Environment Variables
 
 | Variable | Purpose |
@@ -139,6 +155,9 @@ const { valid, checks } = verifySettlementDetailed(context);
 | MPCP_SPA_SIGNING_PRIVATE_KEY_PEM | Private key for signing SPAs |
 | MPCP_SPA_SIGNING_PUBLIC_KEY_PEM | Public key for verifying SPAs |
 | MPCP_SPA_SIGNING_KEY_ID | Key identifier (default: mpcp-spa-signing-key-1) |
+| MPCP_POLICY_GRANT_SIGNING_PRIVATE_KEY_PEM | Private key for signing PolicyGrants |
+| MPCP_POLICY_GRANT_SIGNING_PUBLIC_KEY_PEM | Public key for verifying PolicyGrant signatures (when set, unsigned grants are rejected) |
+| MPCP_POLICY_GRANT_SIGNING_KEY_ID | Key identifier (default: mpcp-policy-grant-signing-key-1) |
 
 ## See Also
 

src/cli/bundle.ts

@@ -50,7 +50,7 @@ export function isSettlementBundle(obj: unknown): obj is SettlementBundle {
  * Build a minimal PaymentPolicyDecision from SPA authorization.
  * Used when bundle omits paymentPolicyDecision.
  */
-function decisionFromSpa(spa: SignedPaymentAuthorization): PaymentPolicyDecision {
+function decisionFromSpa(spa: SignedPaymentAuthorization): PaymentPolicyDecision & { _synthesized: true } {
   const a = spa.authorization;
   const quote = {
     quoteId: a.quoteId,
@@ -70,6 +70,7 @@ function decisionFromSpa(spa: SignedPaymentAuthorization): PaymentPolicyDecision
     asset: a.asset,
     chosen: { rail: a.rail, quoteId: a.quoteId },
     settlementQuotes: [quote],
+    _synthesized: true,
   };
 }
 
@@ -79,6 +80,9 @@ function decisionFromSpa(spa: SignedPaymentAuthorization): PaymentPolicyDecision
 export function bundleToContext(bundle: SettlementBundle): SettlementVerificationContext {
   const decision =
     bundle.paymentPolicyDecision ?? decisionFromSpa(bundle.spa);
+  if (!bundle.paymentPolicyDecision) {
+    console.warn("[mpcp] Warning: paymentPolicyDecision absent — synthesized from SPA. Policy evaluation not verified.");
+  }
   return {
     policyGrant: bundle.policyGrant,
     signedBudgetAuthorization: bundle.sba,

src/cli/formatReport.ts

@@ -4,6 +4,7 @@
  */
 
 import type { VerificationReport, VerificationStep } from "../verifier/types.js";
+import type { PaymentPolicyDecision } from "../policy-core/types.js";
 
 const CHECK = "✔";
 const CROSS = "✗";
@@ -25,10 +26,15 @@ function orderSteps(steps: VerificationStep[]): VerificationStep[] {
   return ordered;
 }
 
-export function formatVerificationReport(report: VerificationReport): string {
+export function formatVerificationReport(report: VerificationReport & { decision?: PaymentPolicyDecision & { _synthesized?: boolean } }): string {
   const lines: string[] = [];
   const ordered = orderSteps(report.steps);
 
+  if (report.decision?._synthesized) {
+    lines.push("⚠ Policy decision: SYNTHESIZED FROM SPA (policy evaluation not verified)");
+    lines.push("");
+  }
+
   for (const step of ordered) {
     const icon = step.ok ? CHECK : CROSS;
     const msg = step.ok ? step.name : `${step.name}: ${step.reason ?? "failed"}`;
@@ -37,6 +43,12 @@ export function formatVerificationReport(report: VerificationReport): string {
 
   if (ordered.length > 0) lines.push("");
 
+  if (report.hashBindingChecked === true) {
+    lines.push("Hash binding: CHECKED");
+  } else if (report.hashBindingChecked === false) {
+    lines.push("Hash binding: NOT CHECKED (Lite Profile — intentHash absent)");
+  }
+
   if (report.result.valid) {
     lines.push("MPCP verification PASSED");
   } else {

src/protocol/policyGrant.ts

@@ -0,0 +1,70 @@
+import crypto, { createHash } from "node:crypto";
+import { canonicalJson } from "../hash/canonicalJson.js";
+import type { PolicyGrantLike } from "../verifier/types.js";
+
+export interface SignedPolicyGrant {
+  grant: PolicyGrantLike;
+  issuer?: string;
+  issuerKeyId: string;
+  signature: string;
+}
+
+function getExpectedKeyId(): string {
+  return process.env.MPCP_POLICY_GRANT_SIGNING_KEY_ID || "mpcp-policy-grant-signing-key-1";
+}
+
+function hashGrant(grant: PolicyGrantLike): Buffer {
+  return createHash("sha256").update("MPCP:PolicyGrant:1.0:" + canonicalJson(grant)).digest();
+}
+
+function parseSigningPrivateKey(): crypto.KeyObject | null {
+  const pem = process.env.MPCP_POLICY_GRANT_SIGNING_PRIVATE_KEY_PEM;
+  if (!pem) return null;
+  try {
+    return crypto.createPrivateKey(pem);
+  } catch {
+    return null;
+  }
+}
+
+function parseVerificationPublicKey(): crypto.KeyObject | null {
+  const pem = process.env.MPCP_POLICY_GRANT_SIGNING_PUBLIC_KEY_PEM;
+  if (!pem) return null;
+  try {
+    return crypto.createPublicKey(pem);
+  } catch {
+    return null;
+  }
+}
+
+export function createSignedPolicyGrant(
+  grant: PolicyGrantLike,
+  options?: { issuer?: string; keyId?: string },
+): SignedPolicyGrant | null {
+  const privateKey = parseSigningPrivateKey();
+  if (!privateKey) return null;
+
+  const issuerKeyId = options?.keyId ?? getExpectedKeyId();
+  const signature = crypto.sign(null, hashGrant(grant), privateKey).toString("base64");
+  const result: SignedPolicyGrant = { grant, issuerKeyId, signature };
+  if (options?.issuer) result.issuer = options.issuer;
+  return result;
+}
+
+export function verifyPolicyGrantSignature(
+  envelope: SignedPolicyGrant,
+): { ok: true } | { 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" };
+
+  const isValid = crypto.verify(
+    null,
+    hashGrant(envelope.grant),
+    publicKey,
+    Buffer.from(envelope.signature, "base64"),
+  );
+  if (!isValid) return { ok: false, reason: "invalid_signature" };
+  return { ok: true };
+}

src/protocol/sba.ts

@@ -107,7 +107,7 @@ export function createSignedSessionBudgetAuthorization(input: {
 
 export function verifySignedSessionBudgetAuthorizationForDecision(
   envelope: SignedSessionBudgetAuthorization,
-  input: { sessionId: string; decision: PaymentPolicyDecision; nowMs?: number },
+  input: { sessionId: string; decision: PaymentPolicyDecision; nowMs?: number; cumulativeSpentMinor?: string },
 ): { ok: true } | { ok: false; reason: "invalid_signature" | "expired" | "budget_exceeded" | "mismatch" } {
   if (envelope.issuerKeyId !== getExpectedKeyId()) return { ok: false, reason: "invalid_signature" };
   const publicKey = parseVerificationPublicKey();
@@ -143,7 +143,8 @@ export function verifySignedSessionBudgetAuthorizationForDecision(
   if (decision.priceFiat?.amountMinor) {
     const budgetMinor = BigInt(authorization.maxAmountMinor);
     const decisionMinor = BigInt(decision.priceFiat.amountMinor);
-    if (decisionMinor > budgetMinor) return { ok: false, reason: "budget_exceeded" };
+    const alreadySpent = BigInt(input.cumulativeSpentMinor ?? "0");
+    if (alreadySpent + decisionMinor > budgetMinor) return { ok: false, reason: "budget_exceeded" };
   }
 
   const quoteId = decision.chosen?.quoteId;

src/protocol/schema/paymentAuthorization.ts

@@ -20,6 +20,7 @@ export const paymentAuthorizationSchema = z.strictObject({
   amount: z.string(),
   destination: z.string().optional(),
   intentHash: intentHashSchema.optional(),
+  nonce: z.string().optional(),
   expiresAt: iso8601DatetimeSchema,
 });
 

src/protocol/schema/shared.ts

@@ -14,8 +14,8 @@ export const minorUnitSchema = z.number().int().min(0);
 /** ISO 4217 currency code (3 uppercase letters) */
 export const currencySchema = z.string().length(3).regex(/^[A-Z]{3}$/);
 
-/** Policy hash (hex, 6–64 chars; allows truncated hashes) */
-export const policyHashSchema = z.string().regex(/^[a-f0-9]{6,64}$/);
+/** Policy hash (hex, 12–64 chars; Full Profile SHOULD use SHA-256 (64 chars)) */
+export const policyHashSchema = z.string().regex(/^[a-f0-9]{12,64}$/);
 
 /** SHA256 hex hash (64 chars) */
 export const intentHashSchema = z.string().length(64).regex(/^[a-f0-9]{64}$/);

src/protocol/schema/verifySchemas.ts

@@ -19,6 +19,9 @@ export const policyGrantForVerificationSchema = z
     expiresAtISO: iso8601DatetimeSchema.optional(),
     allowedRails: z.array(railSchema),
     allowedAssets: z.array(assetSchema).optional(),
+    issuer: z.string().optional(),
+    issuerKeyId: z.string().optional(),
+    signature: z.string().optional(),
   })
   .refine((g) => g.expiresAt != null || g.expiresAtISO != null, {
     message: "policy_grant_missing_expiry",

src/protocol/spa.ts

@@ -1,4 +1,4 @@
-import crypto, { createHash } from "node:crypto";
+import crypto, { createHash, randomUUID } from "node:crypto";
 import type { Asset, PaymentPolicyDecision, Rail, SettlementResult } from "../policy-core/types.js";
 import { canonicalJson, computeIntentHash } from "../hash/index.js";
 
@@ -14,6 +14,7 @@ export interface PaymentAuthorization {
   amount: string;
   destination: string;
   intentHash?: string;
+  nonce?: string;
   expiresAt: string;
 }
 
@@ -107,12 +108,13 @@ function assetMatches(a: Asset, b: Asset): boolean {
 export function createSignedPaymentAuthorization(
   sessionId: string,
   decision: PaymentPolicyDecision,
-  options?: { settlementIntent?: unknown; budgetId?: string },
+  options?: { settlementIntent?: unknown; budgetId?: string; nonce?: string },
 ): SignedPaymentAuthorization | null {
   const authorization = buildAuthorization(sessionId, decision, options);
   const privateKey = parseSigningPrivateKey();
   if (!authorization || !privateKey) return null;
 
+  authorization.nonce = options?.nonce ?? randomUUID();
   const signature = crypto.sign(null, hashAuthorization(authorization), privateKey).toString("base64");
   return { authorization, issuerKeyId: getExpectedSigningKeyId(), signature };
 }

src/sdk/createPolicyGrant.ts

@@ -1,5 +1,7 @@
 import { randomUUID } from "node:crypto";
 import type { PolicyGrantLike } from "../verifier/types.js";
+export { createSignedPolicyGrant } from "../protocol/policyGrant.js";
+export type { SignedPolicyGrant } from "../protocol/policyGrant.js";
 
 export interface CreatePolicyGrantInput {
   policyHash: string;