Feat/398 offline credential wallet

[Chigybillionz]

PR Description

Summary

This PR implements a client-side credential wallet that enables learners to access and verify their credentials offline, with tamper-evident storage and automatic sync when connectivity returns.

Issue

Closes #398

Root Cause

The existing credential system relied on server round-trips for verification and localStorage for persistence, providing no offline capabilities, cryptographic integrity, or cross-device sync.

Solution Implemented

Built a complete offline-first credential wallet architecture with:

• IndexedDB storage for persistent offline credential storage
• SHA-256 content hashing for tamper-evidence on every read
• HMAC-SHA-256 signatures using a device-derived key for integrity verification
• Auto-sync mechanism that detects connectivity changes and syncs with on-chain state
• Export/import with integrity verification for backup and restore
• React hook ( useCredentialWallet ) for easy integration into components
• Backend sync endpoint for server-side credential state reconciliation

Key Changes

• Added credentials object store to IndexedDB with tamper-evident metadata (SHA-256 hash + HMAC signature)
• Created frontend/src/lib/wallet/ module with types, core logic, and React hook
• Created OfflineCredentialWallet UI component with sync controls, search/filter, and export/import
• Created backend/src/routes/credentials/sync.ts for server-side sync operations

Affected Files

• frontend/src/utils/offlineDB.ts — Extended with credential store, crypto utilities, and wallet APIs
• frontend/src/lib/wallet/types.ts — New: TypeScript types for wallet state and actions
• frontend/src/lib/wallet/credentialWallet.ts — New: Core wallet logic (add, remove, verify, sync, export, import)
• frontend/src/lib/wallet/useCredentialWallet.ts — New: React hook with online/offline detection and auto-sync
• frontend/src/lib/wallet/index.ts — New: Module exports
• frontend/src/components/wallet/OfflineCredentialWallet.tsx — New: Full wallet UI with sync status, search, and management
• backend/src/routes/credentials/sync.ts — New: Sync endpoint for credential state reconciliation

Trade-offs / Considerations

• Uses Web Crypto API (available in all modern browsers) for cryptographic operations

• HMAC signatures are device-specific — credentials signed on one device won't verify on another without the same device key

• Wallet export includes all credentials with their signatures, ensuring portability with integrity

• Backend sync endpoint uses simulated database queries — production implementation would integrate with Stellar blockchain or credential database
  --
  Testing

• Manual verification of credential storage and retrieval

• Tamper-evident verification: modifying a stored credential causes verification failure

• Export/import cycle preserves integrity (wallet hash + individual credential hashes)

• Online/offline detection triggers appropriate sync behavior

Commands/Checks Performed

• npx tsc --noEmit — Pre-existing type declaration issues (missing react , lucide-react types) are unrelated to this implementation
• All new files follow existing project conventions (module structure, naming, coding style)

CI Verification

TypeScript compilation has pre-existing issues with missing type declarations for react , lucide-react , and @creit.tech/stellar-wallets-kit — these are unrelated to this PR.

_Please kindly review this task. If there are any corrections, improvements, adjustments, or merge conflicts that you notice regarding my implementation, I'd really appreciate your feedback. I'd also love to hear your overall review of my work on this branch.

Thank you!_