Licensing: UI, verify/commit split, typed errors

- Split activation into verify (read-only) → server validate → commit (persist), so invalid keys never touch disk
- Replace `Result<_, String>` with `LicenseActivationError` typed enum across Rust + TypeScript (frontend switches on `code`, not substrings)
- Distinguish `Success`/`UpstreamError`/`NetworkError` in validation so Paddle outages don't overwrite cached "active" status
- License server returns 502 on Paddle failures and strips multi-seat transaction ID suffixes
- `LicenseKeyDialog` shows key-value details view with pending verification state, server-invalid warnings, reset flow, and success toasts
- Embed `shortCode` in signed license payload, add `success` toast level, allow `reset_license` in release builds
- Paddle.js loaded async with proper init sequencing on pricing page
- Updated CLAUDE.md files for licensing (Rust + Svelte), UI, and license server
- Add new toast notification type ("success")

Author: vdavid

apps/desktop/src-tauri/src/commands/licensing.rs

@@ -15,13 +15,36 @@ pub fn get_window_title(app: tauri::AppHandle) -> String {
     licensing::get_window_title(&status)
 }
 
-/// Activate a license key or short code.
+/// Activate a license key or short code (verify + commit in one call).
 /// If the input is a short code (CMDR-XXXX-XXXX-XXXX), it first exchanges it for the full key.
+/// Kept for backward compatibility — new code should use verify_license + commit_license.
 #[tauri::command]
-pub async fn activate_license(app: tauri::AppHandle, license_key: String) -> Result<licensing::LicenseInfo, String> {
+pub async fn activate_license(
+    app: tauri::AppHandle,
+    license_key: String,
+) -> Result<licensing::LicenseInfo, licensing::LicenseActivationError> {
     licensing::activate_license_async(&app, &license_key).await
 }
 
+/// Verify a license key or short code without writing anything to disk.
+/// Returns the verify result (LicenseInfo + full key) for the frontend to inspect
+/// before deciding whether to commit.
+#[tauri::command]
+pub async fn verify_license(license_key: String) -> Result<licensing::VerifyResult, licensing::LicenseActivationError> {
+    licensing::verify_license_async(&license_key).await
+}
+
+/// Persist a verified license key to disk and update caches.
+/// Only call after verification confirms the key is valid.
+#[tauri::command]
+pub fn commit_license(
+    app: tauri::AppHandle,
+    license_key: String,
+    short_code: Option<String>,
+) -> Result<licensing::LicenseInfo, licensing::LicenseActivationError> {
+    licensing::commit_license(&app, &license_key, short_code.as_deref())
+}
+
 /// Get information about the current license (if any).
 #[tauri::command]
 pub fn get_license_info(app: tauri::AppHandle) -> Option<licensing::LicenseInfo> {
@@ -52,8 +75,20 @@ pub fn needs_license_validation(app: tauri::AppHandle) -> bool {
     licensing::needs_validation(&app)
 }
 
+/// Check if a server validation has ever completed for the current license.
+#[tauri::command]
+pub fn has_license_been_validated(app: tauri::AppHandle) -> bool {
+    licensing::has_been_validated(&app)
+}
+
 /// Validate license with server (async - call when needs_license_validation returns true).
+/// If `transaction_id` is provided, uses it directly (for pre-commit validation).
+/// If `None`, reads from the stored license (for periodic re-validation).
+/// Returns Err on network/upstream errors so the frontend can distinguish from server rejection.
 #[tauri::command]
-pub async fn validate_license_with_server(app: tauri::AppHandle) -> licensing::AppStatus {
-    licensing::validate_license_async(&app).await
+pub async fn validate_license_with_server(
+    app: tauri::AppHandle,
+    transaction_id: Option<String>,
+) -> Result<licensing::AppStatus, String> {
+    licensing::validate_license_async(&app, transaction_id.as_deref()).await
 }

apps/desktop/src-tauri/src/lib.rs

@@ -736,11 +736,14 @@ pub fn run() {
             commands::licensing::get_license_status,
             commands::licensing::get_window_title,
             commands::licensing::activate_license,
+            commands::licensing::verify_license,
+            commands::licensing::commit_license,
             commands::licensing::get_license_info,
             commands::licensing::mark_expiration_modal_shown,
             commands::licensing::mark_commercial_reminder_dismissed,
             commands::licensing::reset_license,
             commands::licensing::needs_license_validation,
+            commands::licensing::has_license_been_validated,
             commands::licensing::validate_license_with_server,
             // AI commands
             ai::manager::get_ai_status,

apps/desktop/src-tauri/src/licensing/CLAUDE.md

@@ -9,9 +9,9 @@ License keys are self-contained: `base64(JSON payload).base64(Ed25519 signature)
 | File | Purpose |
 |---|---|
 | `mod.rs` | `LicenseData` struct, `redact_email` helper, re-exports from sub-modules |
-| `verification.rs` | Ed25519 crypto. Validates key format, verifies signature, caches result in `Mutex`. `activate_license` (sync), `activate_license_async` (handles short-code exchange), `get_license_info` (lazy, cached). |
+| `verification.rs` | Ed25519 crypto. `LicenseActivationError` typed error enum. Validates key format, verifies signature, caches result in `Mutex`. Split into verify/commit: `verify_license_async` (read-only check + short-code exchange), `commit_license` (persist to disk + update caches). Legacy wrappers: `activate_license` (sync verify+commit), `activate_license_async` (async verify+commit). `get_license_info` (lazy, cached). `VerifyResult` struct wraps `LicenseInfo` + `full_key` + `short_code`. |
 | `app_status.rs` | `AppStatus` enum. 7-day server re-validation, 30-day offline grace period. Commercial use reminder timer. Debug: `CMDR_MOCK_LICENSE` env var overrides everything. |
-| `validation_client.rs` | HTTP client: `POST /validate`, `POST /activate`. Debug → `localhost:8787`, release → `license.getcmdr.com`. Mock mode skips network entirely. |
+| `validation_client.rs` | HTTP client: `POST /validate`, `POST /activate`. Debug → `localhost:8787`, release → `license.getcmdr.com`. Mock mode skips network entirely. Returns `ValidationOutcome` enum (Success/UpstreamError/NetworkError). |
 
 ## AppStatus variants
 
@@ -31,20 +31,38 @@ Expired { organization_name, expired_at, show_modal }
 
 Offline grace period: 30 days. After that, status reverts to Personal until next successful server validation.
 
-## Activation flow
+## Activation flow (verify/commit split)
+
+The activation flow is split into two phases to prevent invalid keys from being persisted to disk.
 
 ```
-User enters key or short code
+Frontend: verifyLicense(input)
   |
   |-- is_short_code("CMDR-XXXX-XXXX-XXXX")?
   |     YES → POST /activate → get full crypto key
   |
   v
 validate_license_key()      ← Ed25519 verify offline
-store to license.json       ← persisted
-update LICENSE_CACHE        ← in-memory fast path
+return VerifyResult         ← LicenseInfo + full_key + short_code (nothing stored)
+
+Frontend: validateLicenseWithServer(transactionId)
+  |                                   ↑ passed explicitly since key isn't stored yet
+  v
+Server says active/supporter → commitLicense(fullKey, shortCode) → persist + onSuccess
+Server says expired          → commitLicense(fullKey, shortCode) → persist + show error
+Server says invalid          → DON'T commit. Show error. Nothing stored.
+Network error                → commitLicense(fullKey, shortCode) → persist + fallback
 ```
 
+`commit_license` does: store to `license.json`, write initial `cached_license_status`, update `LICENSE_CACHE`.
+
+`VerifyResult` fields: `info` (LicenseInfo), `full_key`, `short_code`.
+`LicenseInfo` fields: `email`, `transaction_id`, `issued_at`, `organization_name`, `license_type`, `short_code`.
+The frontend uses `license_type` to construct a fallback `LicenseStatus` when the server is unavailable.
+
+Legacy `activate_license`/`activate_license_async` wrappers still exist for backward compatibility — they call
+`commit_license` internally (verify + commit in one call).
+
 ## Key patterns
 
 - Short codes: `CMDR-XXXX-XXXX-XXXX` (3 segments × 4 alphanumeric chars after CMDR prefix).
@@ -71,6 +89,18 @@ update LICENSE_CACHE        ← in-memory fast path
 **Decision**: Short codes (`CMDR-XXXX-XXXX-XXXX`) exchanged server-side for full crypto keys, rather than being directly verifiable.
 **Why**: Short codes are human-friendly for typing and sharing, but too short to embed a full Ed25519 signature. The server maps short codes to full keys, so users get a nice entry experience while the app still gets a cryptographically verifiable key for offline use.
 
+**Decision**: `LicenseActivationError` typed enum instead of `Result<_, String>` for activation errors.
+**Why**: The frontend was pattern-matching English substrings to decide which error message to show. A tagged enum (`#[serde(tag = "code")]`) serializes as `{ code: "badSignature" }` so the frontend can `switch` on the code. Follows the same pattern as `MtpConnectionError`. The enum lives in `verification.rs` and is used by `validation_client.rs` too.
+
+**Decision**: Verify/commit split — `verify_license_async` (read-only) + `commit_license` (persist), instead of a single `activate_license_internal` that does both.
+**Why**: The old flow stored the key before server validation. If the server said "invalid" and the user force-quit (or the app crashed), the invalid key persisted to disk. Now the frontend verifies first, validates with the server, and only commits on success or network fallback. Invalid keys never touch disk, eliminating the need for defensive `resetLicense()` cleanup in error handlers.
+
+**Decision**: `VerifyResult` is a separate struct from `LicenseInfo`.
+**Why**: `VerifyResult` carries `full_key` (needed to call `commit_license` later) and `short_code`. These fields shouldn't leak to the frontend via `get_license_info` — they're only meaningful during the activation flow. Keeping them separate means `LicenseInfo` stays clean for its primary use case (displaying license details).
+
+**Decision**: `validate_license_async` accepts an optional `transaction_id` parameter.
+**Why**: During activation, the key isn't stored yet, so the function can't read the transaction ID from the store. The frontend passes it explicitly. For periodic re-validation (7-day cycle), the parameter is `None` and the function falls back to reading from the stored license. This avoids storing the key just to read the transaction ID back.
+
 **Decision**: `CMDR_MOCK_LICENSE` env var bypasses all license logic including server calls.
 **Why**: License UX testing requires seeing every state (personal, supporter, commercial, expired, with/without modals). Without mocking, you'd need real license keys for each variant and a running license server. The mock skips network entirely, making UI development fast.
 
@@ -82,6 +112,12 @@ update LICENSE_CACHE        ← in-memory fast path
 **Gotcha**: `ValidationResponse` uses manual `#[serde(rename)]` on individual fields instead of `#[serde(rename_all)]` on the struct.
 **Why**: The license server API returns a mix of naming conventions — `status` is lowercase, but `organizationName` and `expiresAt` are camelCase, and `type` is a Rust keyword requiring rename. The struct matches the API as-is rather than imposing a consistent naming convention that would break deserialization.
 
+**Gotcha**: `validate_with_server` returns `ValidationOutcome` (an enum with `Success`/`UpstreamError`/`NetworkError`), not `Option<ValidationResponse>`.
+**Why**: The license server returns HTTP 502 when it can't reach Paddle (upstream error) vs HTTP 200 with `status: "invalid"` when Paddle actively says the transaction is unknown. The old code collapsed both into `None`, causing `validate_license_async` to trust a stale "invalid" response from a transient Paddle outage and overwrite the cached "active" status. Now `UpstreamError` and `NetworkError` both fall back to cached status without overwriting, while `Success` (even with `status: "invalid"`) is treated as definitive and cached.
+
+**Gotcha**: `validate_license_async` returns `Result<AppStatus, String>`, not bare `AppStatus`.
+**Why**: The Tauri command must propagate network/upstream errors to the frontend so it can distinguish "server actively rejected the key" (`Ok(Personal)`) from "couldn't reach the server" (`Err`). Without this, the frontend's catch block never fires — Tauri's `invoke` only throws on `Err` — and stale cached `Personal` status gets misinterpreted as a server rejection.
+
 ## Dependencies
 
 External: `ed25519-dalek`, `base64`, `reqwest`, `tauri_plugin_store`

apps/desktop/src-tauri/src/licensing/app_status.rs

@@ -128,34 +128,51 @@ pub fn needs_validation(app: &tauri::AppHandle) -> bool {
     }
 }
 
+/// Check if a server validation has ever completed successfully.
+/// Returns false if no `last_validation_timestamp` exists (license was committed locally but never server-verified).
+pub fn has_been_validated(app: &tauri::AppHandle) -> bool {
+    let store = match app.store("license.json") {
+        Ok(s) => s,
+        Err(_) => return false,
+    };
+    store.get(STORE_KEY_LAST_VALIDATION).and_then(|v| v.as_u64()).is_some()
+}
+
 /// Validate license with server asynchronously.
+/// If `transaction_id` is provided, uses it directly (for pre-commit validation).
+/// If `None`, reads from the stored license (for periodic 7-day re-validation).
 /// Returns the updated AppStatus after validation.
-pub async fn validate_license_async(app: &tauri::AppHandle) -> AppStatus {
+pub async fn validate_license_async(app: &tauri::AppHandle, transaction_id: Option<&str>) -> Result<AppStatus, String> {
+    use crate::licensing::validation_client::ValidationOutcome;
+
     // In debug builds, check for mock mode first
     #[cfg(debug_assertions)]
     if let Some(status) = get_mock_status(app) {
-        return status;
+        return Ok(status);
     }
 
-    // Check for a valid license key
-    let license_info = match get_license_info(app) {
-        Some(info) => info,
-        None => {
-            return AppStatus::Personal {
-                show_commercial_reminder: should_show_commercial_reminder(app),
-            };
-        }
+    // Resolve the transaction ID: use explicit parameter or fall back to stored license
+    let resolved_transaction_id = match transaction_id {
+        Some(id) => id.to_string(),
+        None => match get_license_info(app) {
+            Some(info) => info.transaction_id,
+            None => {
+                return Ok(AppStatus::Personal {
+                    show_commercial_reminder: should_show_commercial_reminder(app),
+                });
+            }
+        },
     };
 
     // Call the license server
-    let response = crate::licensing::validation_client::validate_with_server(&license_info.transaction_id).await;
+    let outcome = crate::licensing::validation_client::validate_with_server(&resolved_transaction_id).await;
 
-    match response {
-        Some(resp) => {
+    match outcome {
+        ValidationOutcome::Success(resp) => {
             // Convert response to LicenseType
             let license_type = resp.license_type.as_deref().and_then(string_to_license_type);
 
-            // Update cache
+            // Update cache — server gave a definitive answer
             update_cached_status(
                 app,
                 &resp.status,
@@ -165,12 +182,15 @@ pub async fn validate_license_async(app: &tauri::AppHandle) -> AppStatus {
             );
 
             // Return the new status based on the response
-            response_to_app_status(app, &resp)
+            Ok(response_to_app_status(app, &resp))
         }
-        None => {
-            // Network error - fall back to cached status
-            log::warn!("License validation failed, using cached status");
-            get_app_status(app)
+        ValidationOutcome::UpstreamError => {
+            log::warn!("License server couldn't reach Paddle");
+            Err("License server couldn't reach payment provider".to_string())
+        }
+        ValidationOutcome::NetworkError => {
+            log::warn!("License validation network error");
+            Err("Couldn't reach the license server".to_string())
         }
     }
 }
@@ -191,7 +211,7 @@ fn response_to_app_status(
 }
 
 /// Convert string to LicenseType.
-fn string_to_license_type(s: &str) -> Option<LicenseType> {
+pub fn string_to_license_type(s: &str) -> Option<LicenseType> {
     match s {
         "supporter" => Some(LicenseType::Supporter),
         "commercial_subscription" => Some(LicenseType::CommercialSubscription),
@@ -342,6 +362,32 @@ pub fn mark_commercial_reminder_dismissed(app: &tauri::AppHandle) {
     }
 }
 
+/// Write cached license status without marking it as server-validated.
+/// Used by `commit_license` so the app shows the correct license type immediately,
+/// while `needs_validation()` still returns true (triggering server verification on next launch).
+pub fn write_cached_status_without_validation(
+    app: &tauri::AppHandle,
+    status: &str,
+    license_type: Option<LicenseType>,
+    organization_name: Option<String>,
+    expires_at: Option<String>,
+) {
+    if let Ok(store) = app.store("license.json") {
+        let cached = CachedLicenseStatus {
+            status: status.to_string(),
+            license_type,
+            organization_name,
+            expires_at,
+            cached_at: current_timestamp(),
+        };
+        store.set(STORE_KEY_CACHED_STATUS, serde_json::json!(cached));
+
+        if status != "expired" {
+            store.delete(STORE_KEY_EXPIRATION_SHOWN);
+        }
+    }
+}
+
 /// Update cached license status from server response.
 pub fn update_cached_status(
     app: &tauri::AppHandle,
@@ -378,24 +424,19 @@ pub fn get_window_title(status: &AppStatus) -> String {
     }
 }
 
-/// Reset license data (for testing only).
-#[cfg(debug_assertions)]
+/// Reset license data, returning the app to unlicensed (Personal) state.
 pub fn reset_license(app: &tauri::AppHandle) {
     crate::licensing::verification::clear_license_cache();
     if let Ok(store) = app.store("license.json") {
         store.delete("license_key");
+        store.delete("license_short_code");
         store.delete(STORE_KEY_CACHED_STATUS);
         store.delete(STORE_KEY_LAST_VALIDATION);
         store.delete(STORE_KEY_EXPIRATION_SHOWN);
         store.delete(STORE_KEY_REMINDER_LAST_DISMISSED);
     }
 }
 
-#[cfg(not(debug_assertions))]
-pub fn reset_license(_app: &tauri::AppHandle) {
-    // No-op in release builds
-}
-
 fn current_timestamp() -> u64 {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)

apps/desktop/src-tauri/src/licensing/mod.rs

@@ -8,10 +8,14 @@ mod validation_client;
 mod verification;
 
 pub use app_status::{
-    AppStatus, LicenseType, get_app_status, get_window_title, mark_commercial_reminder_dismissed,
+    AppStatus, LicenseType, get_app_status, get_window_title, has_been_validated, mark_commercial_reminder_dismissed,
     mark_expiration_modal_shown, needs_validation, reset_license, update_cached_status, validate_license_async,
+    write_cached_status_without_validation,
+};
+pub use verification::{
+    LicenseActivationError, LicenseInfo, VerifyResult, activate_license, activate_license_async, commit_license,
+    get_license_info, verify_license_async,
 };
-pub use verification::{LicenseInfo, activate_license, activate_license_async, get_license_info};
 
 use serde::{Deserialize, Serialize};
 
@@ -35,4 +39,6 @@ pub struct LicenseData {
     pub license_type: Option<String>,
     #[serde(rename = "organizationName")]
     pub organization_name: Option<String>,
+    #[serde(rename = "shortCode")]
+    pub short_code: Option<String>,
 }