Add self-managed vault recovery option for lost secret key

[0xFirekeeper]

Introduces an option for users of managed vaults who have lost their secret key to create a new self-managed (ejected) vault. Updates the recovery dialog to allow users to choose between providing their secret key for a managed vault or proceeding with self-management, improving recovery flexibility and user experience.

---

PR-Codex overview

This PR introduces a new option for users who have lost their secret key, allowing them to manage vault keys themselves. It modifies the logic around vault creation and user input requirements based on whether the vault is managed or self-managed.

Detailed summary

• Added manageKeysSelf state for users who lost their secret key.
• Updated vault creation logic to create an ejected vault if not managed or if users choose to manage keys.
• Adjusted conditions for requiring a secret key based on vault type.
• Modified UI to conditionally display secret key input and checkbox for self-management.

✨ Ask PR-Codex anything about this PR by commenting with /codex {your question}

Summary by CodeRabbit

Release Notes

• New Features
  • Users can now choose to self-manage vault keys during the recovery process, with options to download and handle keys independently.
  • Updated recovery flow to support both managed and self-managed vault configurations.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: b9d9be4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
thirdweb-www	Ready	Preview, Comment	Jan 12, 2026 4:00pm

4 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
docs-v2	Skipped		Jan 12, 2026 4:00pm
nebula	Skipped		Jan 12, 2026 4:00pm
thirdweb_playground	Skipped		Jan 12, 2026 4:00pm
wallet-ui	Skipped		Jan 12, 2026 4:00pm

[coderabbitai]

Walkthrough

Adds a feature allowing users to choose between managed vaults (using provided secret keys) and self-managed vaults (user controls keys). Introduces manageKeysSelf state that determines credential passing, validation rules, and UI presentation based on the chosen management approach.

Changes

Cohort / File(s)

Summary

Vault Recovery Key Management Mode apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

Adds manageKeysSelf state and derived willCreateEjectedVault flag to enable users to manage vault keys independently. Modifies credential passing logic to omit projectSecretKey for ejected vaults. Updates validation to require only confirmation for self-managed mode versus secret key + confirmation for managed mode. Adjusts success flow reload behavior and renders conditional UI paths for key management selection and ejected vault key download.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	❓ Inconclusive	The description explains the feature well but deviates from the repository's template format, which requires '[SDK/Dashboard/Portal] Feature/Fix:' prefix, issue tag, and explicit testing details sections.	Restructure the description to follow the template format: add the required title prefix, include the Linear issue tag (if available), and provide an explicit 'How to test' section with testing instructions.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a self-managed vault recovery option for users who lost their secret key, which aligns with the file modifications and PR objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 5ca4d74 and b9d9be4.

📒 Files selected for processing (1)

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

🧰 Additional context used

📓 Path-based instructions (9)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx}: Write idiomatic TypeScript with explicit function declarations and return types
Limit each TypeScript file to one stateless, single-responsibility function for clarity
Re-use shared types from @/types or local types.ts barrels
Prefer type aliases over interface except for nominal shapes in TypeScript
Avoid any and unknown in TypeScript unless unavoidable; narrow generics when possible
Choose composition over inheritance; leverage utility types (Partial, Pick, etc.) in TypeScript

**/*.{ts,tsx}: Write idiomatic TypeScript with explicit function declarations and return types
Limit each file to one stateless, single-responsibility function for clarity and testability
Re-use shared types from @/types or local types.ts barrel exports
Prefer type aliases over interface except for nominal shapes
Avoid any and unknown unless unavoidable; narrow generics whenever possible
Choose composition over inheritance; leverage utility types (Partial, Pick, etc.)
Comment only ambiguous logic in TypeScript files; avoid restating TypeScript types and signatures in prose

Files:

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

apps/{dashboard,playground-web}/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

apps/{dashboard,playground-web}/src/**/*.{ts,tsx}: Import UI component primitives from @/components/ui/* (Button, Input, Select, Tabs, Card, Sidebar, Badge, Separator) in dashboard and playground
Use Tailwind CSS only – no inline styles or CSS modules in dashboard and playground
Use cn() from @/lib/utils for conditional Tailwind class merging
Use design system tokens for styling (backgrounds: bg-card, borders: border-border, muted text: text-muted-foreground)
Expose className prop on root element for component overrides

Files:

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

apps/dashboard/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

apps/dashboard/src/**/*.{ts,tsx}: Use NavLink for internal navigation with automatic active states in dashboard
Start server component files with import "server-only"; in Next.js
Read cookies/headers with next/headers in server components
Access server-only environment variables in server components
Perform heavy data fetching in server components
Implement redirect logic with redirect() from next/navigation in server components
Begin client component files with 'use client'; directive in Next.js
Handle interactive UI with React hooks (useState, useEffect, React Query, wallet hooks) in client components
Access browser APIs (localStorage, window, IntersectionObserver) in client components
Support fast transitions with prefetched data in client components
Always call getAuthToken() to retrieve JWT from cookies on server side
Use Authorization: Bearer header for API calls – never embed tokens in URLs
Return typed results (Project[], User[]) from server-side data fetches – avoid any
Wrap client-side API calls in React Query (@tanstack/react-query)
Use descriptive, stable queryKeys in React Query for cache hits
Configure staleTime/cacheTime in React Query based on freshness (default ≥ 60s)
Keep tokens secret via internal API routes or server actions
Never import posthog-js in server components – only use analytics client-side

Files:

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

apps/dashboard/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/dashboard.mdc)

apps/dashboard/**/*.{ts,tsx}: Always import from the central UI library under @/components/ui/* for reusable core UI components like Button, Input, Select, Tabs, Card, Sidebar, Separator, Badge
Use NavLink from @/components/ui/NavLink for internal navigation to ensure active states are handled automatically
For notices and skeletons, rely on AnnouncementBanner, GenericLoadingPage, and EmptyStateCard components
Import icons from lucide-react or the project-specific …/icons exports; never embed raw SVG
Keep components pure; fetch data outside using server components or hooks and pass it down via props
Use Tailwind CSS as the styling system; avoid inline styles or CSS modules
Merge class names with cn from @/lib/utils to keep conditional logic readable
Stick to design tokens: use bg-card, border-border, text-muted-foreground and other Tailwind variables instead of hard-coded colors
Use spacing utilities (px-*, py-*, gap-*) instead of custom margins
Follow mobile-first responsive design with Tailwind helpers (max-sm, md, lg, xl)
Never hard-code colors; always use Tailwind variables
Combine class names via cn, and expose className prop if useful in components
Use React Query (@tanstack/react-query) for all client-side data fetching with typed hooks

Files:

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

apps/dashboard/**/*.client.tsx

📄 CodeRabbit inference engine (.cursor/rules/dashboard.mdc)

apps/dashboard/**/*.client.tsx: Name component files after the component in PascalCase; append .client.tsx when the component is interactive
Client components must start with 'use client'; directive before imports

Files:

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

**/*.{js,jsx,ts,tsx,json}

📄 CodeRabbit inference engine (AGENTS.md)

Biome governs formatting and linting; its rules live in biome.json. Run pnpm fix & pnpm lint before committing, ensure there are no linting errors

Files:

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

apps/{dashboard,playground}/**/*.{tsx,ts}

📄 CodeRabbit inference engine (AGENTS.md)

apps/{dashboard,playground}/**/*.{tsx,ts}: Import UI primitives from @/components/ui/_ (Button, Input, Select, Tabs, Card, Sidebar, Badge, Separator) in Dashboard and Playground apps
Use NavLink for internal navigation so active states are handled automatically
Use Tailwind CSS for styling – no inline styles or CSS modules
Merge class names with cn() from @/lib/utils to keep conditional logic readable
Stick to design tokens for styling: backgrounds (bg-card), borders (border-border), muted text (text-muted-foreground), etc.
Server Components: Read cookies/headers with next/headers, access server-only environment variables or secrets, perform heavy data fetching, implement redirect logic with redirect() from next/navigation, and start files with import 'server-only'; to prevent client bundling
Client Components: Begin files with 'use client'; before imports, handle interactive UI relying on React hooks (useState, useEffect, React Query, wallet hooks), access browser APIs (localStorage, window, IntersectionObserver, etc.), and support fast transitions with client-side data prefetching
For client-side data fetching: Wrap calls in React Query (@tanstack/react-query), use descriptive and stable queryKeys for cache hits, configure staleTime / cacheTime based on freshness requirements (default ≥ 60 s), and keep tokens secret by calling internal API routes or server actions

Files:

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

apps/{dashboard,playground}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

apps/{dashboard,playground}/**/*.{ts,tsx}: For server-side data fetching: Always call getAuthToken() to retrieve the JWT from cookies and inject the token as an Authorization: Bearer header – never embed it in the URL. Return typed results (Project[], User[], …) – avoid any
Never import posthog-js in server components; analytics reporting is client-side only

Files:

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Lazy-import optional features; avoid top-level side-effects

Files:

• apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx

🧬 Code graph analysis (1)

apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx (1)

apps/dashboard/src/@/components/ui/checkbox.tsx (1)

• Checkbox (34-34)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)

• GitHub Check: E2E Tests (pnpm, webpack)
• GitHub Check: E2E Tests (pnpm, esbuild)
• GitHub Check: E2E Tests (pnpm, vite)
• GitHub Check: Lint Packages
• GitHub Check: Size
• GitHub Check: Build Packages
• GitHub Check: Unit Tests
• GitHub Check: Analyze (javascript)

🔇 Additional comments (6)

apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/wallets/server-wallets/wallets/vault-recovery-card.client.tsx (6)

48-61: LGTM!

The state management and derived willCreateEjectedVault logic is clear and correctly handles both scenarios: users who never had a managed vault and managed vault users who lost their secret key.

---

67-87: LGTM!

The mutation correctly conditionally passes the secret key based on vault type and appropriately handles the success flow—reloading immediately for managed vaults while keeping the dialog open for ejected vaults to display the admin key.

---

118-122: LGTM!

The validation logic correctly differentiates between the two flows: ejected vaults only require confirmation, while managed vaults require both confirmation and a non-empty secret key input.

---

173-246: LGTM!

The key download flow provides a secure UX pattern—requiring users to confirm they've saved their admin key before allowing them to close the dialog. The combination of copy, download, and confirmation checkbox ensures users don't accidentally lose access to their vault.

---

275-321: LGTM!

The UI correctly toggles between the secret key input and the self-manage option. Clearing the secret key input when the user opts to manage keys themselves prevents stale data from being accidentally submitted. The password input type appropriately conceals the secret key.

---

343-348: LGTM!

The cancel handler appropriately resets all user input state including the new manageKeysSelf flag, ensuring a clean slate when reopening the dialog.

Warning

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (1)

• TEAM-0000: Entity not found: Issue - Could not find referenced Issue.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 53.02%. Comparing base (5ca4d74) to head (b9d9be4).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8619   +/-   ##
=======================================
  Coverage   53.02%   53.02%           
=======================================
  Files         924      924           
  Lines       61726    61726           
  Branches     4035     4035           
=======================================
  Hits        32730    32730           
  Misses      28898    28898           
  Partials       98       98           

Flag	Coverage Δ
packages	53.02% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

size-limit report 📦

Path	Size
@thirdweb-dev/nexus (esm)	105.66 KB (0%)
@thirdweb-dev/nexus (cjs)	319.47 KB (0%)