> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletwall.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Key Management & Recovery Model

> What WalletWall does and does not do with keys: no key storage, no seed phrases, and recovery flows that are not implemented yet.

# Key Management & Recovery Model

> Status: **Design model + non-custodial guardrails.** This document defines the
> rules the next phase (private-key management and recovery UX) must follow. The
> current implementation is read-only orchestration only — no key handling, no
> recovery writes.

WalletWall is a wallet **intelligence** product. As we move toward helping users
*act* on what they see — rotating keys, configuring recovery, migrating to
recovery-aware accounts — we are writing down the non-negotiable boundaries
first, so every later feature can be checked against them.

## Non-custodial guarantees (hard rules)

These are invariants. Code, tests, and copy must never contradict them.

<Steps>
  <Step title="Never stores private keys">
    WalletWall never stores private keys. Not in the browser, not on a
    server, not in a database, not in logs.
  </Step>

  <Step title="Never asks for a seed phrase">
    WalletWall never asks for a seed phrase. There is no input, modal, paste
    target, or API that accepts mnemonic/seed material. Ever.
  </Step>

  <Step title="Signing happens in the user's own wallet">
    All signing happens through the user's own wallet provider or a smart
    account module. WalletWall constructs unsigned, inspectable intents; the
    wallet (or smart-account validator) signs. WalletWall holds no signing
    authority.
  </Step>

  <Step title="No custodial flows">
    No custodial flows. WalletWall never takes possession, control, or
    discretionary authority over user funds.
  </Step>

  <Step title="Explicit intent required">
    Every sensitive flow requires explicit user intent. No silent, batched,
    or "convenience" actions that move value or change security-critical
    configuration without a clear, per-action confirmation by the user.
  </Step>
</Steps>

## Recovery must be one of these shapes

When recovery is implemented, it must be **contract-based, guardian-based,
passkey-assisted, or MPC-based** — never custodial:

<Tabs>
  <Tab title="Contract-based">
    Recovery logic lives in a smart account the user owns (e.g. a
    social-recovery or modular smart account). WalletWall facilitates; the
    contract enforces.
  </Tab>

  <Tab title="Guardian-based">
    A set of trusted guardians can approve recovery. No single guardian (and
    certainly not WalletWall) can recover alone.
  </Tab>

  <Tab title="Passkey-assisted">
    Device passkeys / WebAuthn provide a second factor or signer, removing
    the "seed phrase to lose" failure mode.
  </Tab>

  <Tab title="MPC-based">
    Signing key is split into shares so no single location holds a complete
    key.
  </Tab>
</Tabs>

## Required properties of any recovery flow

Every recovery (and any security-critical configuration change) must include:

* **Simulation first.** The user can preview exactly what will happen — which
  account, which guardians, which timelock — before anything is submitted.
* **Timelock.** Security-critical actions are delayed, giving the real owner a
  window to notice and react.
* **Cancellation.** The owner can cancel a pending recovery/withdrawal during
  the timelock window.
* **Auditability.** Every step emits an inspectable, on-chain (or verifiable)
  record. No hidden state transitions.
* **Explicit intent at each step.** See hard rule #5.

## Post-quantum verifier status

<Warning>
  The WalletWall Vault prototype models a hybrid classical + post-quantum
  authorization flow (ML-DSA / FIPS 204, with related SLH-DSA / FIPS 205
  research). **The on-chain post-quantum verifier hooks are experimental /
  prototype only and must not be relied upon unless and until independently
  audited.** No copy may claim quantum-proof, quantum-secure, or guaranteed
  quantum resistance.
</Warning>

## How the orchestration layer enforces this today

The Wallet Security Orchestration Layer is the read-only foundation the
recovery phase builds on. It reuses the existing quantum-exposure,
migration-readiness, and quantum-vault-readiness scoring rather than
re-scoring, and **performs no writes, no signing, and no key handling**.

<AccordionGroup>
  <Accordion title="WalletSecurityState classification">
    Classifies a wallet into a single shared `WalletSecurityState`
    (`unknown`, `safe-monitor`, `signature-exposed`, `high-value-exposed`,
    `dormant-high-value`, `migration-ready`, `vault-candidate`,
    `recovery-needed`).
  </Accordion>

  <Accordion title="Vault eligibility evaluation">
    Evaluates **vault eligibility** — eligible, recommendedPath, reason,
    blockers, requiredActions, user-facing disclosure, and developer notes.
  </Accordion>

  <Accordion title="Recovery readiness classification">
    Classifies **recovery readiness** into one of `not-applicable`,
    `monitor-only`, `should-rotate`, `should-migrate-multisig`,
    `should-migrate-smart-vault`, `should-configure-recovery`,
    `needs-urgent-migration`.
  </Accordion>
</AccordionGroup>

The wallet-security profile builder unifies the three into one profile and
recommends which Vault-route view to show:

```mermaid theme={null}
flowchart TD
    accTitle: Vault route view by connection state and profile signal
    accDescr: The wallet-security profile builder recommends a Vault route view from connection state and profile signal. Not connected shows the Scanner with a Check recovery readiness prompt. Connected with no vault and an eligible vaultEligibility signal shows the Create Vault or Recovery Plan preview. Connected with an existing vault shows the Vault candidate dashboard. Connected but not eligible shows Monitor or rotate guidance. Connected with a recovery-needed or needs-urgent-migration signal shows the Recovery planning panel.
    notConnected["Not connected"]:::input --> scanner["Scanner +<br/>'Check recovery readiness'"]:::output
    connectedEligible["Connected, no vault,<br/>eligible"]:::input -->|vaultEligibility.eligible| createVault["Create Vault /<br/>Recovery Plan preview"]:::output
    connectedVaultExists["Connected,<br/>vault exists"]:::input --> dashboard["Vault candidate dashboard"]:::output
    connectedNotEligible["Connected,<br/>not eligible"]:::input -->|not eligible| monitor["Monitor / rotate guidance"]:::output
    connectedRecoveryNeeded["Connected,<br/>recovery-needed"]:::input -->|recovery-needed /<br/>needs-urgent-migration| recoveryPanel["Recovery planning panel"]:::risk
    classDef input fill:#FAFAF0,stroke:#B87333,color:#2B2118,stroke-width:1.5px;
    classDef output fill:#9AAB89,stroke:#526246,color:#172014,stroke-width:1.5px;
    classDef risk fill:#8F2F1D,stroke:#5E1D12,color:#FFF7E8,stroke-width:1.5px;
```

*The `recovery-needed` / `needs-urgent-migration` path is the only one that routes to the Recovery planning panel — every other connection state routes to monitoring, review, or dashboard guidance.*

| Connection state              | Profile signal                               | Vault route view                     |
| ----------------------------- | -------------------------------------------- | ------------------------------------ |
| Not connected                 | —                                            | Scanner + "Check recovery readiness" |
| Connected, no vault, eligible | `vaultEligibility.eligible`                  | Create Vault / Recovery Plan preview |
| Connected, vault exists       | —                                            | Vault candidate dashboard            |
| Connected, not eligible       | not eligible                                 | Monitor / rotate guidance            |
| Connected, recovery-needed    | `recovery-needed` / `needs-urgent-migration` | Recovery planning panel              |

## What remains before implementing private-key management & recovery

<AccordionGroup>
  <Accordion title="Outstanding gaps before implementation">
    * No real recovery **writes** exist yet; classification is advisory only.
    * Wallet connection in the Vault dashboard does not yet run a security scan for
      the connected address (connected-state classification is conservative until
      it does).
    * Smart-account / guardian module integration, passkey, and MPC paths are
      design targets, not implementations.
    * The post-quantum verifier remains unaudited and experimental.
  </Accordion>
</AccordionGroup>

<Note>
  Until those land, all recovery surfaces stay **planning guidance** —
  clearly labelled, non-alarmist, and bound by the hard rules above.
</Note>