Skip to content

feat(frontend): add guardian secret sharing recovery for credentials - #464

Merged
Psalmuel01 merged 3 commits into
ToluLabs:mainfrom
dotmantissa:feature/issue-431-guardian-recovery
Sep 3, 2026
Merged

feat(frontend): add guardian secret sharing recovery for credentials#464
Psalmuel01 merged 3 commits into
ToluLabs:mainfrom
dotmantissa:feature/issue-431-guardian-recovery

Conversation

@dotmantissa

Copy link
Copy Markdown
Contributor

What does this PR do?

This PR introduces client-side Guardian Secret Sharing Recovery for credentials stored in browser localStorage. A holder can now split their 256-bit AES encryption key into N Shamir secret shares across trusted guardians or backup devices, requiring a threshold of K shares (e.g. 2-of-3) to reconstruct the key and restore their credentials. Guardians only receive key shares with zero credential data, ensuring privacy while offering a robust recovery option if browser storage is wiped.

Closes #431

Type of change

  • Bug fix
  • New feature / credential type
  • Refactor / cleanup
  • Docs
  • CI / tooling

Merge requirements

  • CI is greencargo test (contracts), pnpm tsc --noEmit (frontend), pnpm build (frontend), circuit tests — all green
  • Greptile confidence ≥ 4/5 — all review comments addressed, no unresolved threads
  • Circuit changes: fixtures/<type>/ artifacts updated
  • No NEXT_PUBLIC_ prefix on server-only env vars
  • No identity fields stored or logged after KYC provider call
  • prehash:false preserved on any issuer signing path touched
  • Issuer private key never referenced from client-bundled code

✅ Merge requirements

  • All CI checks pass (contracts / frontend / circuits as applicable)
  • Every Greptile review comment is addressed — no unresolved review threads
  • Greptile confidence score is 4/5 or higher

Notes for reviewers

  • Implemented pure Galois Field GF(256) arithmetic and Shamir's Secret Sharing in lib/shamir.ts.
  • Encrypted backup creation, share serialization/parsing (both JSON and compact SC-SHARE:... armored string), key fingerprint verification, and decryption logic are encapsulated in lib/guardian.ts.
  • Built GuardianRecoveryModal.tsx containing both the Key Splitting setup flow and the guided share-collection recovery flow.
  • Dynamically imported the modal in app/holder/page.tsx to preserve the 16 kB bundle limit for the holder route.
  • Added comprehensive unit test suites in lib/__tests__/shamir.test.ts and lib/__tests__/guardian.test.ts covering mathematical properties, threshold variations, edge cases, tamper resistance, and malformed inputs.

@drips-wave

drips-wave Bot commented Aug 31, 2026

Copy link
Copy Markdown

@dotmantissa 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

@dotmantissa
dotmantissa force-pushed the feature/issue-431-guardian-recovery branch from a9bc14e to c7c2909 Compare August 31, 2026 08:05
@Psalmuel01

Copy link
Copy Markdown
Collaborator

The guardian recovery via Shamir secret sharing (#431) is well-designed: K-of-N threshold, guardians receive only key shares (never credential data), client-side reconstruction. It just went conflicting though, #490 (perf telemetry) merged into holder/page.tsx right after this. Please rebase onto latest main. Note #441 also restructured the holder page into components/holder and lib/hooks, so fold the Guardian recovery entry point into that new structure rather than the old monolithic page.

…oluLabs#431)

Allow credential holders to split their 256-bit encryption key into Shamir
secret shares across chosen guardians or backup devices. A configurable
threshold of shares can later reconstruct the key client-side and restore local
storage credentials without exposing plaintext data to guardians.

Adds Shamir secret sharing over GF(256), guardian backup packaging and share
export utilities, and an interactive recovery modal on the holder dashboard with
full test coverage.
@dotmantissa
dotmantissa force-pushed the feature/issue-431-guardian-recovery branch from ee8606a to 81eb7ce Compare September 3, 2026 01:28
@dotmantissa

Copy link
Copy Markdown
Contributor Author

The guardian recovery via Shamir secret sharing (#431) is well-designed: K-of-N threshold, guardians receive only key shares (never credential data), client-side reconstruction. It just went conflicting though, #490 (perf telemetry) merged into holder/page.tsx right after this. Please rebase onto latest main. Note #441 also restructured the holder page into components/holder and lib/hooks, so fold the Guardian recovery entry point into that new structure rather than the old monolithic page.

@Psalmuel01
Implemented the fix, kindly review, and merge.

@Psalmuel01
Psalmuel01 merged commit 056079a into ToluLabs:main Sep 3, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: credential recovery via social/guardian backup of the encryption key

2 participants