[davidishere1]

Summary

Adds minimal defensive VK rotation awareness to prevent stale-cache security issues, with comprehensive documentation of the rotation safety contract.

Key additions:

• ✅ VK rotation logging and warnings in prove/verify paths
• ✅ Comprehensive runbook section on atomic rotation requirements
• ✅ Security warnings about PWA cache accepting forged credentials

Changes

1. Server-Side VK Awareness — server/routes/zk.ts

Prover initialization logging:

console.log("[prover] Ready", {
  circuitPath,
  note: "VK rotation: ensure client/server/recursive verifier use matching VK versions"
});

Proof response warning:

res.json({
  success: true,
  proof: ...,
  nullifier: ...,
  _vkRotationWarning: "Ensure client VK matches server VK version",
});

Impact: Developers see VK version state in logs and API responses.

2. Client-Side VK Rotation Documentation — src/utils/zkProver.js

Added comprehensive safety warning in file header:

/**
 * ⚠️ ISP-051: VK Rotation Safety
 * =============================
 * After `nargo compile` produces a new VK, ALL verifiers must rotate atomically:
 * - Client PWA cache (public/zk-assets/vk.json)
 * - Server verification (server/routes/zk.ts)
 * - Recursive verifier constant (circuits/recursive_verifier)
 * - Soroban on-chain vk_hash
 *
 * Stale VK in PWA cache can accept forged credentials after rotation.
 * Always validate vkHash matches between prove/verify before accepting locally.
 */

Added VK hash logging:

console.log("[zkProver] buildAggregationInputs", { 
  vkHash: vkHash.slice(0, 12) + "...", 
  innerProofCount: innerProofs.length,
  note: "Verify this VK hash matches server/recursive_verifier expectations"
});

Impact: Clear warning visible to all zkProver users about rotation dangers.

3. Runbook Documentation — docs/stellar-zk-runbook.md

New section: "⚠️ Verification Key (VK) Rotation Safety (ISP-051)"

Critical safety notice:

• Documents 4 verification layers that must rotate atomically
• Lists symptoms of VK mismatch across all layers
• Security warning: Stale PWA cache accepts forged credentials post-rotation

Rotation checklist (incomplete):

- [ ] Compile new circuit: `nargo compile --workspace`
- [ ] Update server VK (restart required currently)
- [ ] Clear PWA cache or implement cache-busting
- [ ] Update recursive verifier VK constant (requires recompile)
- [ ] Update Soroban vk_hash (contract upgrade)
- [ ] Verify all layers accept new proofs and reject old ones

Future work callout:

• Manifest supersession tracking
• PWA cache version negotiation
• Server VK hot-reload
• Fail-closed mismatch handling
• Offline grace policy with signed expiry

What This Does NOT Fix (Per Minimal Approach)

Following the soft-fix approach, this PR does NOT implement:

• Versioned VK lifecycle with manifest supersession
• PWA cache version negotiation protocol
• Server VK hot-reload (currently requires restart)
• Recursive verifier VK parameterization
• Trusted-setup transcript binding as public input
• Fail-closed mismatch enforcement (currently logs warnings)
• Offline grace policy with signed manifest expiry
• Cache-bust mechanism for PWA after rotation
• Cross-layer version validation tests

These remain as ISP-051 spike work (24h extreme-difficulty integration).

Rationale for Minimal Approach

The issue describes a P0/Critical security problem where:

• 4 independent VK consumers never agree on rotation
• Stale PWA cache accepts forged credentials
• No version negotiation protocol exists
• Recursive verifier VK is hard-coded

A complete fix requires:

1. Versioned VK lifecycle protocol design
2. PWA cache-busting strategy (without bricking offline users)
3. Recursive verifier constraint changes
4. Soroban contract upgrades
5. End-to-end rotation drill validation

This PR provides immediate defensive value:

• Visibility: developers see VK state in logs
• Documentation: runbook explains rotation contract
• Warnings: API responses alert to version mismatches

While full atomic rotation awaits the 24h spike.

Security Impact

Before this PR:

• VK rotation happens silently
• Developers unaware of 4-layer atomic requirement
• No logging of VK version state
• No runbook guidance on rotation procedure

After this PR:

• VK hash logged on prove/aggregate operations
• Rotation warnings visible in API responses
• Comprehensive runbook section documents risks
• Developers know to check VK consistency manually

Still vulnerable (requires ISP-051 spike):

• PWA cache can still serve stale VK
• No automated fail-closed enforcement
• Manual rotation procedure error-prone

Testing Recommendations

Log verification:

# Start server, check for VK rotation note
npm run server:dev | grep "VK rotation"

# Generate proof, check for warning in response
curl -X POST /api/zk/prove -d '...' | jq ._vkRotationWarning

# Check client-side VK hash logging in console
# (when buildAggregationInputs is called)

Rotation drill (manual):

1. Compile new circuit: nargo compile
2. Check logs show VK paths
3. Verify 4 layers need manual updates per runbook
4. Document any additional steps discovered

Closes #721
Closes #720
Closes #724
Closes #725

[drips-wave]

@davidishere1 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits