Implement onboarding reset functionality and enhance backup features

- Added a new method to reset the onboarding state, allowing users to re-initiate the onboarding process. - Integrated backup creation functionality, enabling users to create encrypted backups of their node identity. - Updated API endpoints to handle onboarding reset and backup creation requests. - Enhanced UI components to support the new onboarding reset and backup features, including error handling and user feedback. - Introduced new dependencies for cryptographic operations and data encoding.
2026-03-02 08:34:13 +00:00 · 2026-03-02 08:34:13 +00:00 · 62d6c13764
commit 62d6c13764
parent 94eb1e4283
23 changed files with 559 additions and 88 deletions
--- a/core/Cargo.lock
+++ b/core/Cargo.lock
@ -45,8 +45,11 @@ dependencies = [
 "archipelago-parmanode",
 "archipelago-performance",
 "archipelago-security",
+ "argon2",
+ "base64 0.21.7",
 "bcrypt",
 "bs58",
+ "chacha20poly1305",
 "chrono",
 "ed25519-dalek",
 "futures-util",
@ -134,6 +137,18 @@ dependencies = [
 "uuid",
 ]

+[[package]]
+name = "argon2"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
+dependencies = [
+ "base64ct",
+ "blake2",
+ "cpufeatures",
+ "password-hash",
+]
+
 [[package]]
 name = "arrayvec"
 version = "0.7.6"
@ -277,6 +292,15 @@ version = "2.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3"

+[[package]]
+name = "blake2"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
+dependencies = [
+ "digest",
+]
+
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
--- a/core/archipelago/Cargo.toml
+++ b/core/archipelago/Cargo.toml
@ -60,5 +60,10 @@ reqwest = { version = "0.11", features = ["json", "socks"] }
 # Nostr (node discovery)
 nostr-sdk = "0.44"

+# Backup encryption (DID identity export)
+argon2 = "0.5"
+chacha20poly1305 = "0.10"
+base64 = "0.21"
+
 [dev-dependencies]
 tokio-test = "0.4"
--- a/core/archipelago/src/api/rpc.rs
+++ b/core/archipelago/src/api/rpc.rs
@ -1,4 +1,5 @@
 use crate::auth::AuthManager;
+use crate::backup;
 use crate::config::Config;
 use crate::container::docker_packages;
 use crate::container::DevContainerOrchestrator;
@ -88,6 +89,7 @@ impl RpcHandler {
            "auth.changePassword" => self.handle_auth_change_password(rpc_req.params).await,
            "auth.onboardingComplete" => self.handle_auth_onboarding_complete().await,
            "auth.isOnboardingComplete" => self.handle_auth_is_onboarding_complete().await,
+            "auth.resetOnboarding" => self.handle_auth_reset_onboarding().await,
            
            // Container orchestration (for Archipelago-managed containers)
            "container-install" => self.handle_container_install(rpc_req.params).await,
@ -119,6 +121,8 @@ impl RpcHandler {
            "node-messages-received" => self.handle_node_messages_received().await,
            "node-nostr-discover" => self.handle_node_nostr_discover().await,
            "node.did" => self.handle_node_did().await,
+            "node.signChallenge" => self.handle_node_sign_challenge(rpc_req.params).await,
+            "node.createBackup" => self.handle_node_create_backup(rpc_req.params).await,
            "node.tor-address" => self.handle_node_tor_address().await,
            "node.nostr-publish" => self.handle_node_nostr_publish().await,
            "node.nostr-pubkey" => self.handle_node_nostr_pubkey().await,
@ -239,12 +243,61 @@ impl RpcHandler {
        Ok(serde_json::json!(complete))
    }

+    async fn handle_auth_reset_onboarding(&self) -> Result<serde_json::Value> {
+        self.auth_manager.reset_onboarding().await?;
+        Ok(serde_json::json!(true))
+    }
+
    async fn handle_node_did(&self) -> Result<serde_json::Value> {
        let (data, _) = self.state_manager.get_snapshot().await;
        let did = identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
        Ok(serde_json::json!({ "did": did, "pubkey": data.server_info.pubkey }))
    }

+    /// Sign a challenge to prove control of the node DID (proof-of-control for onboarding).
+    async fn handle_node_sign_challenge(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let challenge = params
+            .get("challenge")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing challenge string"))?;
+
+        let identity_dir = self.config.data_dir.join("identity");
+        let identity = identity::NodeIdentity::load_or_create(&identity_dir).await?;
+        let signature = identity.sign(challenge.as_bytes());
+
+        Ok(serde_json::json!({ "signature": signature }))
+    }
+
+    /// Create an encrypted backup of the node identity (for onboarding).
+    async fn handle_node_create_backup(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let passphrase = params
+            .get("passphrase")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing passphrase"))?;
+
+        let (data, _) = self.state_manager.get_snapshot().await;
+        let did = identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
+        let identity_dir = self.config.data_dir.join("identity");
+
+        let backup = backup::create_encrypted_backup(
+            &identity_dir,
+            passphrase,
+            &did,
+            &data.server_info.pubkey,
+        )
+        .await?;
+
+        Ok(backup)
+    }
+
    async fn handle_node_tor_address(&self) -> Result<serde_json::Value> {
        let tor_address = docker_packages::read_tor_address("archipelago");
        Ok(serde_json::json!({ "tor_address": tor_address }))
--- a/core/archipelago/src/auth.rs
+++ b/core/archipelago/src/auth.rs
@ -86,6 +86,24 @@ impl AuthManager {
        Ok(())
    }

+    /// Reset onboarding state so the user can go through onboarding again (dev/testing).
+    pub async fn reset_onboarding(&self) -> Result<()> {
+        let onboarding_file = self.data_dir.join("onboarding.json");
+        let state = OnboardingState { complete: false };
+        fs::write(
+            &onboarding_file,
+            serde_json::to_string_pretty(&state)?,
+        )
+        .await?;
+        if let Some(mut user) = self.get_user().await? {
+            user.onboarding_complete = false;
+            let user_file = self.data_dir.join("user.json");
+            let content = serde_json::to_string_pretty(&user)?;
+            fs::write(&user_file, content).await?;
+        }
+        Ok(())
+    }
+
    pub async fn is_onboarding_complete(&self) -> Result<bool> {
        // Check onboarding.json first (persisted before user setup)
        let onboarding_file = self.data_dir.join("onboarding.json");
--- a/core/archipelago/src/backup.rs
+++ b/core/archipelago/src/backup.rs
@ -0,0 +1,68 @@
+//! Encrypted DID identity backup for onboarding.
+//! Uses Argon2 for key derivation and ChaCha20-Poly1305 for encryption.
+
+use anyhow::{Context, Result};
+use argon2::Argon2;
+use base64::{engine::general_purpose::STANDARD as BASE64, Engine};
+use chacha20poly1305::aead::{Aead, KeyInit};
+use rand::RngCore;
+use std::path::Path;
+use tokio::fs;
+
+const BACKUP_VERSION: u32 = 1;
+const SALT_LEN: usize = 16;
+const NONCE_LEN: usize = 12;
+const KEY_LEN: usize = 32;
+
+/// Create an encrypted backup of the node identity key.
+/// Returns JSON-serializable backup metadata + encrypted blob (base64).
+pub async fn create_encrypted_backup(
+    identity_dir: &Path,
+    passphrase: &str,
+    did: &str,
+    pubkey_hex: &str,
+) -> Result<serde_json::Value> {
+    let key_path = identity_dir.join("node_key");
+    let key_bytes = fs::read(&key_path)
+        .await
+        .context("Failed to read node key")?;
+    if key_bytes.len() != 32 {
+        anyhow::bail!("Invalid node key length");
+    }
+
+    let mut salt = [0u8; SALT_LEN];
+    let mut nonce = [0u8; NONCE_LEN];
+    rand::rngs::OsRng.fill_bytes(&mut salt);
+    rand::rngs::OsRng.fill_bytes(&mut nonce);
+
+    let argon2 = Argon2::default();
+    let mut key = [0u8; KEY_LEN];
+    argon2
+        .hash_password_into(passphrase.as_bytes(), &salt, &mut key)
+        .map_err(|e| anyhow::anyhow!("Argon2 key derivation failed: {}", e))?;
+
+    let cipher = chacha20poly1305::ChaCha20Poly1305::new_from_slice(&key)
+        .map_err(|e| anyhow::anyhow!("Cipher init: {}", e))?;
+    let ciphertext = cipher
+        .encrypt(
+            chacha20poly1305::aead::generic_array::GenericArray::from_slice(&nonce),
+            key_bytes.as_ref(),
+        )
+        .map_err(|e| anyhow::anyhow!("Encryption failed: {}", e))?;
+
+    let mut blob = Vec::with_capacity(SALT_LEN + NONCE_LEN + ciphertext.len());
+    blob.extend_from_slice(&salt);
+    blob.extend_from_slice(&nonce);
+    blob.extend_from_slice(&ciphertext);
+    let blob_b64 = BASE64.encode(&blob);
+
+    Ok(serde_json::json!({
+        "version": BACKUP_VERSION,
+        "did": did,
+        "pubkey": pubkey_hex,
+        "kid": format!("{}#key-1", did),
+        "encrypted": true,
+        "blob": blob_b64,
+        "timestamp": chrono::Utc::now().to_rfc3339(),
+    }))
+}
--- a/core/archipelago/src/main.rs
+++ b/core/archipelago/src/main.rs
@ -7,6 +7,7 @@ use tracing::info;

 mod api;
 mod auth;
+mod backup;
 mod config;
 mod electrs_status;
 mod container;
--- a/docs/DID_ONBOARDING_ASSESSMENT.md
+++ b/docs/DID_ONBOARDING_ASSESSMENT.md
@ -0,0 +1,189 @@
+# DID Onboarding Flow: Assessment & Implementation Plan
+
+## Executive Summary
+
+The current onboarding DID flow is **partially implemented** and has several significant gaps compared to the W3C DID protocol and Web5 expectations. The core `did:key` format is **correct**, but the user-facing flow includes mock/fake behavior and the backup/verify steps don't actually use the DID infrastructure.
+
+---
+
+## What We Have (Current State)
+
+### ✅ Correct Implementation
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| **did:key format** | ✅ Correct | Ed25519 multicodec `0xed 0x01`, base58btc encoding, `z` prefix |
+| **Key generation** | ✅ Correct | Ed25519 via `ed25519_dalek`, persisted at `/var/lib/archipelago/identity/` |
+| **node.did RPC** | ✅ Correct | Returns `{ did, pubkey }` from server state |
+| **Identity persistence** | ✅ Correct | Key survives reboots, 0o600 permissions on Unix |
+| **Sign/verify primitives** | ✅ Present | `NodeIdentity::sign()`, `NodeIdentity::verify()` exist in Rust |
+
+### ⚠️ Partial / Misleading Implementation
+
+| Component | Status | Issue |
+|-----------|--------|-------|
+| **OnboardingDid.vue** | ⚠️ Misleading copy | Says "Generate DID" but we *fetch* from server; key is created at first boot, not during onboarding |
+| **OnboardingVerify.vue** | ❌ Fake | Uses `generateMockSignature()` – random chars, no backend call. Doesn't prove DID control |
+| **OnboardingBackup.vue** | ❌ Non-functional | Backup is mock JSON with `{ did, kid }`; no encrypted key material; **restore is impossible** |
+| **kid usage** | ⚠️ Non-standard | We store `pubkey` as `kid`; proper did:key uses fragment like `#key-1` or `did:key:z...#key-1` |
+
+### ❌ Missing
+
+| Component | Status |
+|-----------|--------|
+| **node.sign RPC** | Not exposed – backend can sign but no API |
+| **Challenge-sign flow** | No backend support for proof-of-control |
+| **Encrypted backup** | No real backup with key material or recovery path |
+| **DID Document endpoint** | Not exposed (optional for did:key – can be derived client-side) |
+| **keyAgreement / X25519** | Not derived – full DID Document would need Ed25519→X25519 for encryption |
+
+---
+
+## DID Protocol Requirements (W3C / Web5)
+
+### did:key Method (W3C CCG)
+
+1. **Format**: `did:key:z<base58btc(multicodec + raw-public-key-bytes)>` ✅ We do this
+2. **DID Document**: Can be derived from the DID string; no registry. Libraries like `@digitalcredentials/did-method-key` expand it.
+3. **Verification methods**: `verificationMethod`, `authentication`, `assertionMethod`, `keyAgreement` (X25519 derived), `capabilityDelegation`, `capabilityInvocation`
+4. **Key ID (kid)**: Typically `{did}#key-1` or similar fragment
+
+### Proof of Control
+
+To prove control of a DID, you must **sign a challenge** with the private key. The verifier checks the signature against the public key in the DID. Our OnboardingVerify step claims to do this but **does not**.
+
+### Backup / Recovery
+
+A proper identity backup for recovery would:
+
+- Include the private key (or encrypted key material)
+- Be encrypted with a user passphrase
+- Allow restore on a new device
+
+Our backup has none of this – it's display-only.
+
+---
+
+## Recommended Implementation Plan
+
+### Phase 1: Fix Verify Step (Proof of Control)
+
+**Goal**: Replace the fake "Sign Challenge" with a real cryptographic proof.
+
+1. **Backend**: Add `node.signChallenge` RPC
+   - Input: `{ challenge: string }` (nonce from frontend)
+   - Output: `{ signature: string }` (hex-encoded Ed25519 signature)
+   - Uses `NodeIdentity::sign()` with `challenge.as_bytes()`
+
+2. **Frontend (OnboardingVerify.vue)**:
+   - Generate a random nonce (e.g. 32 bytes, base64)
+   - Call `node.signChallenge({ challenge })`
+   - Verify signature locally using the pubkey from `node.did` (optional – or trust server)
+   - Display the real signature; remove `generateMockSignature()`
+
+**Effort**: ~2–4 hours
+
+---
+
+### Phase 2: Improve UX and Terminology
+
+**Goal**: Align copy and flow with actual behavior.
+
+1. **OnboardingDid.vue**:
+   - Change "Generate DID" → "Get your node's identity" or "Retrieve DID"
+   - Clarify that the DID is created when the node first starts (not on button click)
+   - Optionally auto-fetch on mount if identity exists (no button needed for returning state)
+
+2. **kid / Key ID**:
+   - Use `#key-1` or full `{did}#key-1` in backup and state
+   - Or follow [did:key key IDs](https://www.w3.org/TR/did-core/#relative-did-urls)
+
+**Effort**: ~1–2 hours
+
+---
+
+### Phase 3: Real Backup (Encrypted Export)
+
+**Goal**: Backup that can actually be used for recovery.
+
+**Design choice**: The private key lives on the **server**. Two options:
+
+- **Option A (simpler)**: Backup is a signed, encrypted blob containing the key material. Restore requires:
+  - Upload backup file
+  - Enter passphrase
+  - Server imports key and replaces current identity (or restores to same node)
+
+- **Option B (more self-sovereign)**: User can export key to their own wallet. Higher complexity and key-handling risk.
+
+**Recommended: Option A**
+
+1. **Backend**: Add `node.createBackup` RPC
+   - Input: `{ passphrase: string }`
+   - Encrypt the raw key bytes (e.g. XChaCha20-Poly1305 or AES-256-GCM) with a key derived from passphrase (Argon2)
+   - Return JSON: `{ version, did, backupBlob (base64), salt, ... }` or trigger download
+
+2. **Backend**: Add `node.restoreBackup` RPC (for restore flow)
+   - Input: `{ backupBlob, passphrase }`
+   - Decrypt, validate, write to identity dir
+   - Restart or reload identity
+
+3. **Frontend (OnboardingBackup.vue)**:
+   - Call `node.createBackup` instead of building mock JSON locally
+   - Download the real backup file
+
+4. **Restore flow**: Add a restore path (e.g. from login or onboarding options) that accepts backup file + passphrase and calls `node.restoreBackup`
+
+**Effort**: ~1–2 days (crypto, testing, edge cases)
+
+---
+
+### Phase 4: DID Document & Web5 Interop (Optional)
+
+**Goal**: Full compatibility with Web5 resolvers and DWN.
+
+1. **DID Document endpoint**: `GET /.well-known/did.json` or `/did/{did}`
+   - Resolve did:key to a full DID Document
+   - Include `verificationMethod`, `authentication`, `keyAgreement` (X25519 from Ed25519)
+   - Reference: [did:key expansion](https://github.com/digitalbazaar/did-method-key)
+
+2. **X25519 derivation**: Add `curve25519-dalek` or equivalent; derive X25519 pubkey from Ed25519 for `keyAgreement`
+
+3. **Web5/DWN**: Ensure `web5-dwn` and `did-wallet` use our node DID correctly for resolution and operations
+
+**Effort**: ~2–3 days
+
+---
+
+### Phase 5: DID as Authentication (Future)
+
+**Goal**: Use DID + proof instead of (or in addition to) password.
+
+- DID Auth / SIOP flow: prove control of DID via challenge-response
+- Could reduce or replace password for API access
+- Larger design and security review required
+
+**Effort**: TBD
+
+---
+
+## Priority Recommendation
+
+| Priority | Phase | Reason |
+|----------|-------|--------|
+| **P0** | Phase 1 (Verify) | Removes fake crypto; proves DID control |
+| **P1** | Phase 2 (UX) | Quick wins; honest representation of flow |
+| **P2** | Phase 3 (Backup) | Makes backup/restore actually useful |
+| **P3** | Phase 4 (DID Doc) | Needed for full Web5 interop |
+| **P4** | Phase 5 (DID Auth) | Longer-term identity architecture |
+
+---
+
+## Quick Reference: Current vs. Target
+
+| Step | Current | Target |
+|------|---------|--------|
+| DID fetch | `node.did` ✅ | Same, better UX |
+| Prove control | Fake random "signature" ❌ | Real `node.signChallenge` |
+| Backup | Mock JSON, no key ❌ | Encrypted key material + restore |
+| kid | Raw pubkey | `#key-1` or standard fragment |
+| Restore | Not possible | `node.restoreBackup` |
--- a/neode-ui/dev-dist/sw.js
+++ b/neode-ui/dev-dist/sw.js
@ -82,7 +82,7 @@ define(['./workbox-21a80088'], (function (workbox) { 'use strict';
    "revision": "3ca0b8505b4bec776b69afdba2768812"
  }, {
    "url": "index.html",
-    "revision": "0.dbmr9lf4rv4"
+    "revision": "0.00fear1bobk"
  }], {});
  workbox.cleanupOutdatedCaches();
  workbox.registerRoute(new workbox.NavigationRoute(workbox.createHandlerBoundToURL("index.html"), {
--- a/neode-ui/mock-backend.js
+++ b/neode-ui/mock-backend.js
@ -693,6 +693,12 @@ app.post('/rpc/v1', (req, res) => {
        return res.json({ result: userState.onboardingComplete })
      }

+      case 'auth.resetOnboarding': {
+        userState.onboardingComplete = false
+        console.log('[Auth] Onboarding reset')
+        return res.json({ result: true })
+      }
+
      case 'node.did': {
        const mockDid = 'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH'
        const mockPubkey = 'a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456'
@ -705,6 +711,32 @@ app.post('/rpc/v1', (req, res) => {
        return res.json({ result: { nostr_pubkey: 'mock-nostr-pubkey-hex' } })
      }

+      case 'node.signChallenge': {
+        const { challenge } = params || {}
+        const mockSig = Buffer.from(`mock-sig-${challenge || 'challenge'}`).toString('hex')
+        return res.json({ result: { signature: mockSig } })
+      }
+
+      case 'node.createBackup': {
+        const { passphrase } = params || {}
+        if (!passphrase) {
+          return res.json({ error: { code: -32602, message: 'Missing passphrase' } })
+        }
+        const mockDid = 'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH'
+        const mockPubkey = 'a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456'
+        return res.json({
+          result: {
+            version: 1,
+            did: mockDid,
+            pubkey: mockPubkey,
+            kid: `${mockDid}#key-1`,
+            encrypted: true,
+            blob: Buffer.from(`mock-encrypted-backup-${passphrase}`).toString('base64'),
+            timestamp: new Date().toISOString(),
+          },
+        })
+      }
+
      case 'auth.login': {
        const { password } = params
        
--- a/neode-ui/public/assets/img/bg-intro-1.jpg
+++ b/neode-ui/public/assets/img/bg-intro-1.jpg
--- a/neode-ui/public/assets/img/bg-intro-2.jpg
+++ b/neode-ui/public/assets/img/bg-intro-2.jpg
--- a/neode-ui/public/assets/img/bg-intro-3.jpg
+++ b/neode-ui/public/assets/img/bg-intro-3.jpg
--- a/neode-ui/public/assets/img/bg-intro-4.jpg
+++ b/neode-ui/public/assets/img/bg-intro-4.jpg
--- a/neode-ui/public/assets/img/bg-intro-5.jpg
+++ b/neode-ui/public/assets/img/bg-intro-5.jpg
--- a/neode-ui/public/assets/img/bg-intro-6.jpg
+++ b/neode-ui/public/assets/img/bg-intro-6.jpg
--- a/neode-ui/src/App.vue
+++ b/neode-ui/src/App.vue
@ -111,16 +111,16 @@ function onUserActivity() {
 function onKeyDown(e: KeyboardEvent) {
  const isMac = navigator.platform.toUpperCase().includes('MAC')
  const mod = isMac ? e.metaKey : e.ctrlKey
-  // Cmd+K / Ctrl+K or plain K (when not typing in input)
+  // Cmd+K / Ctrl+K only (modifier required - avoids accidental trigger when typing)
  const target = e.target as HTMLElement
  const isInput = target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable
-  if ((mod && e.key === 'k') || ((e.key === 'k' || e.key === 'K') && !isInput)) {
+  if (mod && e.key === 'k') {
    e.preventDefault()
    spotlightStore.toggle()
    return
  }
-  // Cmd+Shift+` / Ctrl+Shift+` or plain C - CLI popup
-  if ((mod && e.shiftKey && e.key === '`') || ((e.key === 'c' || e.key === 'C') && !isInput)) {
+  // Cmd+Shift+` / Ctrl+Shift+` or Cmd+Shift+C / Ctrl+Shift+C - CLI popup (modifier required)
+  if ((mod && e.shiftKey && e.key === '`') || (mod && e.shiftKey && (e.key === 'c' || e.key === 'C'))) {
    e.preventDefault()
    cliStore.toggle()
    return
--- a/neode-ui/src/api/rpc-client.ts
+++ b/neode-ui/src/api/rpc-client.ts
@ -135,6 +135,13 @@ class RPCClient {
    })
  }

+  async resetOnboarding(): Promise<boolean> {
+    return this.call({
+      method: 'auth.resetOnboarding',
+      params: {},
+    })
+  }
+
  async getNodeDid(): Promise<{ did: string; pubkey: string }> {
    return this.call({
      method: 'node.did',
@ -142,6 +149,28 @@ class RPCClient {
    })
  }

+  async signChallenge(challenge: string): Promise<{ signature: string }> {
+    return this.call({
+      method: 'node.signChallenge',
+      params: { challenge },
+    })
+  }
+
+  async createBackup(passphrase: string): Promise<{
+    version: number
+    did: string
+    pubkey: string
+    kid: string
+    encrypted: boolean
+    blob: string
+    timestamp: string
+  }> {
+    return this.call({
+      method: 'node.createBackup',
+      params: { passphrase },
+    })
+  }
+
  async publishNostrIdentity(): Promise<{ event_id: string; success: number; failed: number }> {
    return this.call({
      method: 'node.nostr-publish',
--- a/neode-ui/src/router/index.ts
+++ b/neode-ui/src/router/index.ts
@ -124,6 +124,22 @@ const router = createRouter({
  ],
 })

+// Session check with timeout - avoids endless spinner on mobile/slow networks
+const SESSION_CHECK_TIMEOUT_MS = 8000
+
+async function checkSessionWithTimeout(store: ReturnType<typeof useAppStore>): Promise<boolean> {
+  try {
+    return await Promise.race([
+      store.checkSession(),
+      new Promise<boolean>((resolve) =>
+        setTimeout(() => resolve(false), SESSION_CHECK_TIMEOUT_MS)
+      ),
+    ])
+  } catch {
+    return false
+  }
+}
+
 /**
 * Navigation Guard
 * Handles authentication and onboarding flow routing
@ -134,16 +150,16 @@ router.beforeEach(async (to, _from, next) => {

  // Allow all public routes (login, onboarding) without auth check
  if (isPublic) {
-    // If authenticated and visiting /login, validate session first
+    // If authenticated and visiting /login: show login immediately, validate in background.
+    // This prevents endless spinner on mobile when checkSession hangs (slow/unreachable network).
    if (to.path === '/login' && store.isAuthenticated) {
      if (store.needsSessionValidation()) {
-        const valid = await store.checkSession()
-        if (valid) {
-          next({ name: 'home' })
-          return
-        }
-        // Session invalid, allow login page
        next()
+        checkSessionWithTimeout(store).then((valid) => {
+          if (valid) {
+            router.replace({ name: 'home' }).catch(() => {})
+          }
+        })
        return
      }
      next({ name: 'home' })
@ -153,9 +169,9 @@ router.beforeEach(async (to, _from, next) => {
    return
  }

-  // Protected routes: validate session if stale auth from localStorage
+  // Protected routes: validate session if stale auth from localStorage (with timeout)
  if (store.needsSessionValidation()) {
-    const valid = await store.checkSession()
+    const valid = await checkSessionWithTimeout(store)
    if (!valid) {
      next('/login')
      return
@ -164,9 +180,9 @@ router.beforeEach(async (to, _from, next) => {
    return
  }

-  // Not authenticated at all
+  // Not authenticated at all (with timeout to avoid endless spinner on mobile)
  if (!store.isAuthenticated) {
-    const hasSession = await store.checkSession()
+    const hasSession = await checkSessionWithTimeout(store)
    if (hasSession) {
      next()
      return
--- a/neode-ui/src/views/Login.vue
+++ b/neode-ui/src/views/Login.vue
@ -116,14 +116,22 @@
        </div>
      </div>

-      <!-- Replay Intro - Bottom of Page -->
-      <div class="mt-8 text-center">
+      <!-- Replay Intro / Restart Onboarding - Bottom of Page -->
+      <div class="mt-8 text-center flex items-center justify-center gap-4">
        <button 
          @click="replayIntro" 
          class="text-xs text-white/50 hover:text-white/70 transition-colors underline-offset-2 hover:underline"
        >
          Replay Intro
        </button>
+        <span class="text-white/30">|</span>
+        <button 
+          @click="restartOnboarding" 
+          :disabled="isResettingOnboarding"
+          class="text-xs text-white/50 hover:text-white/70 transition-colors underline-offset-2 hover:underline disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {{ isResettingOnboarding ? 'Resetting...' : 'Onboarding' }}
+        </button>
      </div>
    </div>
  </div>
@ -286,6 +294,27 @@ function replayIntro() {
  // Navigate to root to trigger splash screen
  window.location.href = '/'
 }
+
+const isResettingOnboarding = ref(false)
+
+async function restartOnboarding() {
+  if (isResettingOnboarding.value) return
+  isResettingOnboarding.value = true
+  try {
+    await rpcClient.resetOnboarding()
+    localStorage.removeItem('neode_onboarding_complete')
+    localStorage.removeItem('neode_did')
+    localStorage.removeItem('neode_did_state')
+    localStorage.removeItem('neode_backup_created')
+    await router.push('/onboarding/intro')
+    window.location.reload()
+  } catch (err) {
+    console.error('Failed to reset onboarding:', err)
+    error.value = err instanceof Error ? err.message : 'Failed to reset onboarding'
+  } finally {
+    isResettingOnboarding.value = false
+  }
+}
 </script>

 <style scoped>
--- a/neode-ui/src/views/OnboardingBackup.vue
+++ b/neode-ui/src/views/OnboardingBackup.vue
@ -15,6 +15,7 @@
      <!-- Content Area -->
      <div class="flex flex-col items-center gap-4 sm:gap-6 mb-4 sm:mb-6 px-3 sm:px-4">
        <div class="w-full max-w-[600px] space-y-4 sm:space-y-6">
+          <p v-if="errorMessage" class="text-red-400 text-sm">{{ errorMessage }}</p>
          <!-- Passphrase Input -->
          <div class="path-option-card cursor-default px-4 py-4 sm:px-6 sm:py-6">
            <div class="text-left w-full">
@ -65,7 +66,7 @@
          <!-- Success Message -->
          <div v-if="downloaded" class="text-center">
            <p class="text-sm text-white/70">
-              Backup saved as <span class="font-mono text-white/90">neode-did-backup.json</span>
+              Backup saved as <span class="font-mono text-white/90">archipelago-did-backup.json</span>
            </p>
          </div>
        </div>
@ -81,8 +82,8 @@
        </button>
        <button
          @click="proceed"
-          :disabled="!passphrase"
-          class="path-action-button path-action-button--continue"
+          :disabled="!downloaded"
+          class="path-action-button path-action-button--continue disabled:opacity-50"
        >
          Continue
        </button>
@ -94,48 +95,40 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { useRouter } from 'vue-router'
+import { rpcClient } from '@/api/rpc-client'

 const router = useRouter()
 const passphrase = ref('')
 const isDownloading = ref(false)
 const downloaded = ref(false)
+const errorMessage = ref('')

 async function downloadBackup() {
  if (!passphrase.value) return
-  
+
  isDownloading.value = true
-  
-  // Simulate backup creation
-  await new Promise(resolve => setTimeout(resolve, 1000))
-  
-  // Get DID from localStorage
-  const didStateStr = localStorage.getItem('neode_did_state')
-  const didState = didStateStr ? JSON.parse(didStateStr) : { did: 'did:key:unknown', kid: 'kid:mock' }
-  
-  // Create backup data
-  const backupData = {
-    version: '1.0',
-    did: didState.did,
-    kid: didState.kid,
-    encrypted: true,
-    timestamp: new Date().toISOString(),
-    // In production, this would be properly encrypted with the passphrase
-    note: 'This is a mock backup. In production, this would contain encrypted key material.'
+  errorMessage.value = ''
+
+  try {
+    const backupData = await rpcClient.createBackup(passphrase.value)
+
+    const blob = new Blob([JSON.stringify(backupData, null, 2)], {
+      type: 'application/json',
+    })
+    const a = document.createElement('a')
+    a.href = URL.createObjectURL(blob)
+    a.download = 'archipelago-did-backup.json'
+    a.click()
+    URL.revokeObjectURL(a.href)
+
+    downloaded.value = true
+    localStorage.setItem('neode_backup_created', '1')
+  } catch (err) {
+    errorMessage.value =
+      err instanceof Error ? err.message : 'Failed to create backup. Please try again.'
+  } finally {
+    isDownloading.value = false
  }
-  
-  // Create and download file
-  const blob = new Blob([JSON.stringify(backupData, null, 2)], { type: 'application/json' })
-  const a = document.createElement('a')
-  a.href = URL.createObjectURL(blob)
-  a.download = 'neode-did-backup.json'
-  a.click()
-  URL.revokeObjectURL(a.href)
-  
-  downloaded.value = true
-  isDownloading.value = false
-  
-  // Store passphrase hint (not the actual passphrase!)
-  localStorage.setItem('neode_backup_created', '1')
 }

 function proceed() {
--- a/neode-ui/src/views/OnboardingDid.vue
+++ b/neode-ui/src/views/OnboardingDid.vue
@ -5,10 +5,10 @@
      <!-- Header -->
      <div v-if="!generatedDid" class="text-center flex-shrink-0">
        <h1 class="text-[26px] font-semibold text-white/96 mb-6 drop-shadow-[0_2px_6px_rgba(0,0,0,0.4)]">
-          Take control of your new identity
+          Your node's identity
        </h1>
        <p class="text-[20px] text-white/75 leading-relaxed max-w-[600px] mx-auto mb-6">
-          Generate a Decentralized Identifier (DID) for secure, passwordless authentication. Your identity, your control.
+          Your node has a Decentralized Identifier (DID) for secure, passwordless authentication. Retrieve it to continue.
        </p>
      </div>

@ -16,20 +16,20 @@
      <div class="flex flex-col items-center gap-6 mb-6">
        <!-- Error message -->
        <p v-if="errorMessage" class="text-red-400 text-sm mb-4">{{ errorMessage }}</p>
-        <!-- Generate Button (if no DID yet) -->
+        <!-- Fetch Button (if no DID yet) -->
        <button
          v-if="!generatedDid"
-          @click="generateDid"
+          @click="fetchDid"
          :disabled="isGenerating"
          class="path-action-button path-action-button--continue"
        >
-          <span v-if="!isGenerating">Generate DID</span>
+          <span v-if="!isGenerating">Retrieve DID</span>
          <span v-else class="flex items-center gap-2">
            <svg class="animate-spin h-5 w-5" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
              <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
              <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
            </svg>
-            Generating...
+            Retrieving...
          </span>
        </button>

@ -45,7 +45,7 @@
              </div>
            </div>
            <p class="text-[20px] text-white/80 leading-relaxed max-w-[600px] mx-auto mb-6">
-              Your decentralized identifier has been generated
+              Your node's decentralized identifier
            </p>
          </div>

@ -59,7 +59,7 @@
                </p>
              </div>
              <p class="text-base text-white/60">
-                This identifier is stored securely on your device
+                This identifier is stored securely on your node
              </p>
            </div>
          </div>
@ -88,7 +88,7 @@
 </template>

 <script setup lang="ts">
-import { ref } from 'vue'
+import { ref, onMounted } from 'vue'
 import { useRouter } from 'vue-router'
 import { rpcClient } from '@/api/rpc-client'

@ -97,7 +97,13 @@ const generatedDid = ref<string>('')
 const isGenerating = ref(false)
 const errorMessage = ref<string>('')

-async function generateDid() {
+/** Store DID state with proper kid (DID#key-1 per W3C) */
+function storeDidState(did: string, pubkey: string) {
+  localStorage.setItem('neode_did', did)
+  localStorage.setItem('neode_did_state', JSON.stringify({ did, kid: `${did}#key-1`, pubkey }))
+}
+
+async function fetchDid() {
  isGenerating.value = true
  errorMessage.value = ''

@ -105,8 +111,7 @@ async function generateDid() {
    try {
      const { did, pubkey } = await rpcClient.getNodeDid()
      generatedDid.value = did
-      localStorage.setItem('neode_did', did)
-      localStorage.setItem('neode_did_state', JSON.stringify({ did, kid: pubkey }))
+      storeDidState(did, pubkey)
      break
    } catch (err) {
      errorMessage.value = err instanceof Error ? err.message : 'Server unavailable. Retrying...'
@ -120,6 +125,14 @@ async function generateDid() {
  isGenerating.value = false
 }

+onMounted(() => {
+  // Auto-fetch if identity may already exist (e.g. returning to this step)
+  const cached = localStorage.getItem('neode_did')
+  if (cached && !cached.includes('...')) {
+    generatedDid.value = cached
+  }
+})
+
 function proceed() {
  if (generatedDid.value && !generatedDid.value.includes('...')) {
    router.push('/onboarding/backup').catch(() => {})
--- a/neode-ui/src/views/OnboardingIntro.vue
+++ b/neode-ui/src/views/OnboardingIntro.vue
@ -3,13 +3,9 @@
    <div class="max-w-2xl w-full">
      <div class="glass-card p-12 pt-20 text-center animate-fade-up relative overflow-visible">
        <!-- Logo - half in, half out of container -->
-        <div class="absolute -top-[52px] left-1/2 -translate-x-1/2">
-          <div class="logo-gradient-border">
-            <img 
-              src="/assets/img/favico.svg" 
-              alt="Archipelago" 
-              class="w-20 h-20"
-            />
+        <div class="absolute -top-10 left-1/2 -translate-x-1/2 z-10">
+          <div class="logo-gradient-border w-20 h-20">
+            <AnimatedLogo no-border fit />
          </div>
        </div>
        
@ -34,6 +30,7 @@

 <script setup lang="ts">
 import { useRouter } from 'vue-router'
+import AnimatedLogo from '@/components/AnimatedLogo.vue'

 const router = useRouter()

--- a/neode-ui/src/views/OnboardingVerify.vue
+++ b/neode-ui/src/views/OnboardingVerify.vue
@ -14,6 +14,7 @@

      <!-- Content Area -->
      <div class="flex flex-col items-center gap-6 mb-6">
+        <p v-if="errorMessage" class="text-red-400 text-sm">{{ errorMessage }}</p>
        <!-- Sign Button (if not verified yet) -->
        <button
          v-if="!verified"
@ -84,32 +85,35 @@
 import { ref } from 'vue'
 import { useRouter } from 'vue-router'
 import { completeOnboarding } from '@/composables/useOnboarding'
+import { rpcClient } from '@/api/rpc-client'

 const router = useRouter()
 const verified = ref(false)
 const isSigning = ref(false)
 const signature = ref('')
+const errorMessage = ref('')
+
+/** Generate a cryptographically random challenge (32 bytes, base64) */
+function generateChallenge(): string {
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  return btoa(String.fromCharCode(...bytes))
+}

 async function signChallenge() {
  isSigning.value = true
+  errorMessage.value = ''

-  // Simulate signing challenge
-  await new Promise(resolve => setTimeout(resolve, 1500))
-
-  const mockSignature = generateMockSignature()
-  signature.value = mockSignature
-  verified.value = true
-
-  isSigning.value = false
-}
-
-function generateMockSignature(): string {
-  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/='
-  let result = ''
-  for (let i = 0; i < 128; i++) {
-    result += chars.charAt(Math.floor(Math.random() * chars.length))
+  try {
+    const challenge = generateChallenge()
+    const { signature: sig } = await rpcClient.signChallenge(challenge)
+    signature.value = sig
+    verified.value = true
+  } catch (err) {
+    errorMessage.value = err instanceof Error ? err.message : 'Failed to sign challenge. Please try again.'
+  } finally {
+    isSigning.value = false
  }
-  return result
 }

 async function proceed() {