Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,11 @@ A deleted file usually stays on the drive until something new is written on top
| Your situation | Can Reclaim help? |
| --- | --- |
| SD card, camera card or USB stick | **Usually yes.** These usually use FAT32 or exFAT, which Reclaim reads. |
| External hard drive | **Yes**, if it's formatted as NTFS, FAT32 or exFAT. |
| External hard drive | **Yes**, if it's formatted as NTFS, FAT32, exFAT, ext2, ext3, ext4 or HFS+ (Mac OS Extended). |
| Windows computer's internal drive | **Yes** for hard drives. For SSDs, chances are low (see [SSDs](#why-are-ssds-different)). |
| Your Mac's built-in drive | **Not yet.** Macs use APFS, which Reclaim can't read yet. Memory cards and USB drives used on a Mac are fine. |
| Linux system drive | **Not yet.** It's usually ext4 or Btrfs, which Reclaim can't read yet. |
| Your Mac's built-in drive | **Not yet** on current Macs, which use APFS. Older Macs and external drives formatted as **Mac OS Extended (HFS+)** work. Memory cards and USB drives used on a Mac are fine. |
| Linux drive | **Yes** for ext2, ext3 and ext4. **Not yet** for Btrfs or XFS. On an SSD, chances are low (see [SSDs](#why-are-ssds-different)). |
| Windows Server or Dev Drive using ReFS | **Not yet.** Reclaim recognizes ReFS but can't read it yet. |
| Files that were overwritten | **No.** No software can bring back data that new files have replaced. |

Reclaim is an **early preview**, and no recovery tool can promise every file will come back.
Expand Down Expand Up @@ -62,7 +63,7 @@ Pick the file for your computer from the **[latest release](https://github.com/s
## How to recover your files

1. **Choose the drive** where the files were. Connected drives appear on their own; click **Refresh** after plugging one in. If the drive is encrypted (BitLocker, FileVault, LUKS), unlock it first.
2. **Click Start scanning.** Files appear while the scan runs. You can stop as soon as you see what you need.
2. **Click Start scanning.** Files appear while the scan runs. You can recover them right away, without waiting for the scan to finish, or stop the scan as soon as you see what you need.
3. **Look through the results.** Search by name or type, filter by category (photos, documents…), and click a file to see its details and a preview for pictures.
4. **Tick the files you want and click Recover selected.** Pick a folder on a **different drive**. Then open the recovered files to check they are complete.

Expand Down Expand Up @@ -121,7 +122,7 @@ No. Everything stays on your computer. Reclaim only contacts GitHub to check for
| **Windows: access denied** | Close Reclaim, right-click it and choose **Run as administrator**. |
| **Mac: access denied** | Reading a whole drive needs an administrator password. Also check **System Settings → Privacy & Security** for a request to allow access to removable volumes or Full Disk Access. |
| **Linux: access denied** | Accept the password prompt that appears when you open a drive. If no prompt appears, install your desktop's polkit authentication agent and UDisks2. |
| **"Unused-space scanning needs a supported formatted volume"** | Choose the partition or volume (for example `sdb1`), not the whole disk (`sdb`). The drive must be NTFS, FAT or exFAT. |
| **"Unused-space scanning needs a supported formatted volume"** | Choose the partition or volume (for example `sdb1`), not the whole disk (`sdb`). The drive must be NTFS, FAT, exFAT, ext2/3/4 or HFS+. ReFS, APFS, Btrfs and XFS can't be scanned yet. |
| **Scan finished with unreadable areas, or the drive stopped responding** | Check the cable and try once more. If it happens again, the drive may be failing: recover the files already found and stop using it. |
| **A recovered file won't open** | It may be incomplete or overwritten. Try other results of the same type. |
| **Windows: Reclaim won't start** | An error message explains why. A log is saved at `%LOCALAPPDATA%\Reclaim\logs\reclaim.log`; attach it when you [report a problem](https://github.com/sudo-py-dev/reclaim/issues). |
Expand All @@ -144,7 +145,7 @@ cd reclaim
cargo run --release --locked
```

The [developer guide](docs/DEVELOPMENT.md) covers tests, drive permissions, architecture and detailed limits. See also the [format research](docs/FILE_FORMAT_RESEARCH.md), [translation notes](locales/README.md), [screenshot instructions](docs/screenshots/README.md), [code and UI audit](docs/CODE_UI_AUDIT.md) and the [website](website/README.md).
The [developer guide](docs/DEVELOPMENT.md) covers building, drive permissions, architecture and detailed limits, and [TESTING.md](docs/TESTING.md) every test and its results. See also the [format research](docs/FILE_FORMAT_RESEARCH.md), [translation notes](locales/README.md) and the [website](website/README.md).

<details>
<summary>How scanning works</summary>
Expand Down
90 changes: 0 additions & 90 deletions docs/CODE_UI_AUDIT.md

This file was deleted.

83 changes: 26 additions & 57 deletions docs/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ A Rust desktop app for recovering file candidates from drives and raw disk image
## Features

- **Native drive discovery:** Linux sysfs, Windows storage APIs, and macOS IOKit/Disk Arbitration. No `lsblk`, PowerShell, `diskutil`, or `plutil` subprocesses.
- **Unused-space default:** NTFS, FAT12/16/32, and exFAT volume maps; occupied clusters and filesystem metadata are excluded from signature carving. No full-source fallback.
- **Unused-space default:** NTFS, FAT12/16/32, exFAT, ext2/3/4, and HFS+/HFSX volume maps (ReFS is detected and refused); occupied clusters and filesystem metadata are excluded from signature carving. No full-source fallback.
- **Live scan results:** unused-byte progress, cancellation, and recoverable partial results.
- **Filtered recovery:** search by filename, extension, or source offset; filter by file category. Recovery saves only selected files matching the active filters.
- **Safe output naming:** original NTFS leaf names when available, generated names otherwise, and numeric suffixes to avoid replacing existing files.
Expand Down Expand Up @@ -85,70 +85,30 @@ Reclaim is not a complete filesystem recovery suite. A signature match does not
## Development

```sh
cargo fmt --check
cargo fmt --all -- --check
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
```

`cargo test` includes the project audit in `tests/audit` (security rules tagged
by CWE, translation coverage and dead keys, supply-chain policy). Run it alone
with `cargo test --locked --test audit`. See [the code and UI audit](CODE_UI_AUDIT.md)
for what it checks and how to accept a reviewed finding.
`cargo test` includes the project audit and the headless UI renders.
[TESTING.md](TESTING.md) lists every suite, the audit rules, the layout checks,
fuzzing, the opt-in hardware tests, CI and the real USB drive results.

Tests cover signature boundaries, image validation, NTFS records, filtered exports, collision protection, sector-aligned reads, native Linux metadata fixtures, cancellation, and Slint page rendering in both themes.
### Data preservation

### Data preservation and USB checks

Recovery blocks a destination known to share the scanned physical drive, even
after a confirmation dialog. Unknown topology still requires explicit review;
choose a destination you know is on another physical drive. Linux refuses to
Recovery blocks a destination known to share the scanned physical drive. The
in-app destination dialog names the folder and offers only "Choose another
folder" or Cancel; the drive is checked again just before writing. When the
drive cannot be determined, the dialog also offers "Save here anyway", for a
destination you know is on another physical drive. The dialog is drawn by
Reclaim itself, not a native message box, so it starts no helper program
(such as zenity on Linux) and cannot fail silently when one is missing.
The folder picker opens where the last recovery saved. Linux refuses to
certify separation for anonymous filesystem device numbers (including Btrfs)
or incomplete device-mapper/RAID topology. A single mountinfo source does not
describe every disk in a multi-device filesystem.

The security regression tests simulate a USB disconnect after a partial read,
competing exports with the same filename, invalid candidate ranges, existing
files and symlinks. Failed exports must leave no published partial file or
temporary staging file, and successful exports must preserve existing data:

```sh
cargo test --locked --test security
```

Two opt-in Linux hardware tests only read the selected device or verify that
same-drive export is rejected. They do not format, delete, write test files, or
export recovery candidates. Set the device and its existing mount directory
explicitly, checking their identity first:

```sh
RECLAIM_TEST_DEVICE=/dev/sdX1 cargo test --locked --bin reclaim live_named_volume_can_read_data -- --ignored --nocapture
RECLAIM_TEST_DEVICE=/dev/sdX1 RECLAIM_TEST_DESTINATION=/media/user/USB cargo test --locked --bin reclaim live_usb_export_to_source_drive_is_blocked_before_any_write -- --ignored
```

The read test scans only the first 16 MiB. Normal read permissions or the
desktop's read-only UDisks authorization are required. Disconnect/error behavior
is simulated in automated tests; do not unplug a device during an actual export
or use a failing drive for repeated hardware tests. Mounted source contents and
mount topology can still change externally; these checks are not a guarantee
against every hardware failure or mount race.

Optional headless UI previews:

```sh
mkdir -p /tmp/reclaim-previews
RECLAIM_PREVIEW_DIR=/tmp/reclaim-previews cargo test --locked --bin reclaim slint_workspace
```

The same test run also checks layout automatically: no control leaves the window or overlaps another on any page, state, language or window size, and the scan status line does not move between states (see [the code and UI audit](CODE_UI_AUDIT.md)).

The previews are PNG images rendered from the actual Slint components using its software renderer. They do not test native window management, authentication prompts, or real-device recovery.

[Desktop CI](../.github/workflows/build.yml) runs locked tests (including the UI
and project audit) and Clippy with warnings as errors on Linux, Windows, and
macOS. Formatting runs once on Linux. Separate jobs check dependency advisories,
bans and sources, and install the website's locked dependencies, type-check it,
and build it. Checks run on pull requests, main, and weekly; newer commits cancel
older PR runs. Third-party actions are pinned to immutable revisions.
### Builds and releases

Tests compile the app and UI in the test profile; PR checks do not perform a
second optimized build, package installers, or upload executable artifacts.
Expand All @@ -157,8 +117,17 @@ workflow before building optimized binaries and native installers for all four
shipping targets. Only releases upload artifacts, sign updates, and publish
GitHub downloads. Release runs are serialized per tag and artifacts expire after
seven days. macOS binaries use ad-hoc signing; Developer ID signing and
notarization are not configured. Native desktop and hardware testing remain
necessary; headless tests do not replace them.
notarization are not configured.

### Rules for changes

- Keep disk reads, decoding, downloads, and authentication off the render thread.
- Keep scan queues bounded and cancellation checks inside long-running loops.
- Preserve read-only source access and export without overwriting existing files.
- Use unique, stable widget IDs; preserve virtualization of long result lists.
- Keep image decoding and candidate parsing bounded; validate untrusted sizes.
- Check minimum and default window sizes in light, dark and right-to-left layouts.
- Prefer existing components and dependencies; simplify only with equivalent behavior.

## License and credits

Expand Down
22 changes: 22 additions & 0 deletions docs/DISTRIBUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,28 @@ Build committed source without copying local credentials, caches or disk images:
packaging/snap/build.sh
```

If a local LXD build cannot obtain network access, use Canonical's remote builders
from a full Git checkout of the committed public source (shallow clones are not
supported). Authorize Snapcraft in Launchpad when prompted. Remote builds publish
the source snapshot to Launchpad. Keep build logs private:

```sh
umask 077
snapcraft remote-build --build-for=amd64 --launchpad-accept-public-upload
Comment thread
sudo-py-dev marked this conversation as resolved.
Resolved
```

A remote build downloads the snap into the current directory. Move it where the
upload steps below expect it, replacing any older local build:

```sh
mkdir -p dist
mv -f reclaim_*_amd64.snap dist/
```

The recipe installs Ubuntu's Rustup package and invokes Rust 1.99.0 explicitly.
Toolchain files are installed only in the build environment; they are not shipped
in the application snap.

The result is `dist/reclaim_<version>_amd64.snap`. Upload and request release with:

```sh
Expand Down
Loading
Loading