fix: PR23 guardrails polish - canonical names, SBA scope, deterministic timestamp, doc clarity

Made-with: Cursor

Author: NAOR YUVAL

docs/examples/machine-wallet-guardrails.md

@@ -1,6 +1,6 @@
 # Machine Wallet Guardrails Example
 
-Runnable example demonstrating MPCP as a **machine wallet guardrail layer**.
+Runnable example showing how MPCP acts as a **machine wallet guardrail layer**.
 
 ## Overview
 
@@ -12,6 +12,8 @@ A machine wallet should not send funds unless payment requests satisfy:
 
 This example shows the integration pattern: check all three layers before signing.
 
+This example focuses on wallet-side guardrail logic and uses a preloaded SBA-shaped authorization object rather than demonstrating full SBA issuance and signature verification.
+
 ## Run
 
 ```bash
@@ -27,14 +29,14 @@ node examples/machine-wallet-guardrails/wallet-integration.mjs
 
 ## What It Demonstrates
 
-1. **Allowed request** — $15 to rParking passes all checks; SPA is signed
+1. **Allowed request** — $15 to rParking passes all checks; SignedPaymentAuthorization is created
 2. **Wrong destination** — $5 to rAttacker is rejected (not in allowlist)
 3. **Would exceed budget** — $20 to rCharging when session already spent $15 is rejected
 
 ## Guardrail Check Flow
 
 ```
-Payment request → PolicyGrant check → SBA check → Sign SPA (or reject)
+Payment request → PolicyGrant validation → SignedBudgetAuthorization validation → SignedPaymentAuthorization creation (or reject)
 ```
 
 See [Machine Wallet Guardrails](../implementation/machine-wallet-guardrails.md) for the full guide and threat model.

docs/implementation/machine-wallet-guardrails.md

@@ -33,7 +33,7 @@ MPCP provides three layers of enforcement before a machine can pay:
 
 - **Amount binding** — SPA commits to a specific amount and destination
 - **Intent hash** — SPA binds to a canonical SettlementIntent
-- **Tamper resistance** — Settlement must match the signed authorization
+- **Tamper resistance** — SettlementIntent and final settlement must match the signed authorization
 
 ## Wallet Integration
 
@@ -44,15 +44,15 @@ A machine wallet integrates MPCP by performing checks *before* signing an SPA.
 ```
 Payment request received
     ↓
-Check PolicyGrant (rail, asset, expiry)
+PolicyGrant validation (rail, asset, expiry)
     ↓ PASS
-Check SBA (amount ≤ remaining, destination in allowlist, expiry)
+SignedBudgetAuthorization validation (amount ≤ remaining, destination in allowlist, expiry)
     ↓ PASS
-Create SettlementIntent + SPA
+Create SettlementIntent + SignedPaymentAuthorization
     ↓
-Sign SPA
+SignedPaymentAuthorization creation (or reject)
     ↓
-Return SPA (and optional SettlementIntent) to payee
+Return SignedPaymentAuthorization (and optional SettlementIntent) to payee
 ```
 
 ### Integration Checklist
@@ -65,7 +65,7 @@ Before signing an SPA, the wallet **must**:
 4. Use `createSignedPaymentAuthorization` with the policy decision and intent
 5. Never sign if any check fails
 
-See the [wallet integration example](../examples/machine-wallet-guardrails.md) for a runnable implementation.
+See the [wallet integration example](../examples/machine-wallet-guardrails.md) for a runnable implementation. That example focuses on wallet-side guardrail logic and uses a preloaded SBA-shaped authorization object rather than demonstrating full SBA issuance and signature verification.
 
 ## Bounded Authorization
 

examples/machine-wallet-guardrails/README.md

@@ -4,6 +4,8 @@ Runnable example showing how a machine wallet integrates MPCP guardrails before
 
 ## Concept
 
+This example focuses on wallet-side guardrail logic and uses a preloaded SBA-shaped authorization object rather than demonstrating full SBA issuance and signature verification.
+
 A machine wallet should **not** send funds unless the payment request satisfies:
 
 1. **PolicyGrant** — Rail, asset, expiration
@@ -26,7 +28,7 @@ npm run build
 node examples/machine-wallet-guardrails/wallet-integration.mjs
 ```
 
-## Full Flow Demo
+## Full Guardrail Flow Demo
 
 For a complete narrative demo (policy → budget → SPA → verification → tamper detection), see:
 

examples/machine-wallet-guardrails/wallet-integration.mjs

@@ -56,7 +56,21 @@ function checkGuardrails(policyGrant, sba, paymentRequest) {
     return { ok: false, reason: "policy expired" };
   }
 
-  // Layer 2: SBA
+  // Layer 2: SBA (rail, asset, amount, destination, expiry)
+  const sbaAllowedRails = new Set(sba.authorization.allowedRails ?? []);
+  if (!sbaAllowedRails.has(rail)) {
+    return { ok: false, reason: "rail not in budget authorization" };
+  }
+  const sbaAllowedAssets = sba.authorization.allowedAssets ?? [];
+  const sbaAssetMatch = sbaAllowedAssets.some(
+    (a) =>
+      a.kind === asset?.kind &&
+      a.currency === asset?.currency &&
+      a.issuer === asset?.issuer
+  );
+  if (!sbaAssetMatch) {
+    return { ok: false, reason: "asset not in budget authorization" };
+  }
   const maxMinor = BigInt(sba.authorization.maxAmountMinor ?? "0");
   const reqMinor = BigInt(amount);
   if (reqMinor > maxMinor) {
@@ -95,7 +109,7 @@ async function handlePaymentRequest(policyGrant, sba, paymentRequest, sessionSpe
     amount: paymentRequest.amount,
     destination: paymentRequest.destination,
     asset: paymentRequest.asset,
-    createdAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+    createdAt: "2030-01-01T00:00:00Z",
   });
 
   const paymentPolicyDecision = {