Project: QRFS File System over QR Codes 1. Introduction QRFS is a user-space file system that uses QR codes as the physical storage medium instead of a traditional block device (disk, partition, image file). The “device” is a directory in the host system (e.g., qrfolder/) containing QR code image files. All file system structure (superblock, inode table, free space map, list of participating QR codes, etc.) and user data is stored indirectly in these QR images. The system must be implemented in Rust and use FUSE to expose a mount point that behaves like a conventional POSIX file system. 2. Scope and Objectives 2.1 General Objective Design and implement a user-space file system called QRFS that: * Uses a set of 200x200 pixel QR code images as the physical storage medium. * Exposes a basic POSIX interface via FUSE, allowing creation, reading, writing, renaming, and deletion of files through a standard mount point. * Uses inodes as the main block indexing structure. * Protects and obfuscates internal organization through a passphrase, encrypting critical metadata. * Provides utilities to create the file system (mkfs.qrfs), check consistency (fsck.qrfs), mount it (mount.qrfs), and generate a “printed” PDF version containing the QR codes (print.qrfs or equivalent). 2.2 Functional Scope QRFS implements a single root directory (/) with no mandatory subdirectories; all regular files reside directly under /. The mkdir operation is optional. If implemented, nested directories beyond depth 1 (one level under /) are not required. 3. Storage and Organization Model 3.1 Physical Set of QR Codes The physical medium is a directory in the host system (e.g., qrfolder/) containing QR code image files: * All images must be QR codes with fixed size 200x200 pixels; any QR generated or updated by the system must respect this resolution. * During mkfs, the system builds a list of participating QR files, which together form the logical “partition” of QRFS. 3.2 Internal Logical Structure (Inodes and Blocks) QRFS must: * Use inodes as the indexing structure. Each inode represents a file or the root directory and stores at least: type (file/directory), basic permissions, logical size, references to data blocks, and timestamps if needed. * Maintain a representation of logical block space with: * A logical block size chosen at design time (e.g., 4 KiB). * A free/used block map (bitmap or similar). * Maintain a superblock containing global information: * Total size of the file system (in blocks). * Number of inodes. * Locations of inode table and block maps. * Version identifiers and integrity signatures. The mapping between logical blocks and QR codes must be clearly defined (e.g., one or several logical blocks packed into the QR payload, with suitable serialization and deserialization). 3.3 Root Directory and Naming Model * A root directory / contains entries for regular files and, optionally, subdirectories (if mkdir is implemented), without requiring deep nesting. * Path resolution can be limited to: * “/” for the root directory. * “/filename” for files at the root level. * Optionally “/subdir/filename” if a single level of subdirectories is supported. 4. Security and Encryption 4.1 Passphrase and File System Signature * During mkfs.qrfs, the user is prompted for a passphrase. * This passphrase is used to: * Generate a signature that robustly identifies the start of the file system among the QR files. * Derive a symmetric key for encrypting sensitive metadata. 4.2 Encrypted Metadata At minimum, the following must be encrypted based on the passphrase: * Superblock. * Free block map. * Inode table or its structural portion. * List of participating QR files and their logical order in the partition. The content of user files (regular file data) may remain in clear text; protection focuses on structure and metadata, not user payload. 5. Required Programs and Functionalities 5.1 QRFS Core and FUSE Operations A main Rust module (library or binary) must implement FUSE operations to expose QRFS as a mounted file system, supporting at least: * getattr * create * open * read * write * rename * mkdir (optional) * readdir * opendir * rmdir * statfs * fsync * access These operations must: * Translate POSIX calls into inode and block operations. * Maintain consistency of internal data structures. * Respect the flat directory model (root plus optional single-level subdirectories). 5.2 mkfs.qrfs Responsible for creating a new QRFS: Suggested syntax: mkfs.qrfs qrfolder/ Minimum responsibilities: 1. Detect QR files in qrfolder/ and build the list of participating files. 2. Optionally allow the user to choose which QR file is the logical start of the partition. 3. Prompt for a passphrase, derive the key, and: * Write an identifiable signature into the starting QR. * Encrypt and store: * Initial superblock. * Initial inode table. * Free block map. * List of participating QRs. The entire file system structure must be protected so that it is only accessible from the beginning of the partition via the passphrase. 4. Create the file system with a fixed size (e.g., total number of logical blocks) specified as a parameter. 5. Prepare the system so it can later support manual resizing (adding more QR codes) and dynamic resizing as space runs low. 6. Organize metadata to support future defragmentation. 5.3 fsck.qrfs Consistency checking tool. Suggested syntax: fsck.qrfs qrfolder/ Responsibilities: * Verify: * Integrity of the initial signature and ability to decrypt with the passphrase. * Consistency between inode table, free block map, and blocks in actual use. * Absence of orphan blocks (marked used but not referenced) and duplicate blocks assigned to multiple inodes (unless hard links are explicitly supported). * Report errors and optionally perform basic repairs. 5.4 mount.qrfs FUSE-based mounting tool. Suggested syntax: mount.qrfs qrfolder/ mountpoint/ Functionality: * Mount the QRFS file system under mountpoint/. * Allow the user to: * Explicitly specify which QR file is the start of the FS, or * Let the program scan all QR images in qrfolder/ to locate the signature automatically. * Prompt for the passphrase, decrypt metadata, and build in-memory structures for FS operations. * Invoke FUSE with the QRFS operations. 5.5 print.qrfs (or Equivalent) Functionality to “print” the file system into a PDF document containing the QR images. Suggested syntax: print.qrfs qrfolder/ output.pdf Requirements: * Read the QR image files that form the file system in qrfolder/. * Verify (or guarantee) that each image is a 200x200 pixel QR code, regenerating images if needed. * Build a PDF where each page contains one or more QR codes, preserving 200x200 logical size, and optionally include minimal labels (e.g., QR index, starting block number). * The resulting PDF must be suitable for physical printing, fulfilling the “printed file system” requirement. * This may be an independent program (print.qrfs) or a subcommand of an existing binary, but must be clearly documented. 6. Additional Technical Requirements * Programming language: Rust (modern stable version). * FUSE interface: use a FUSE-compatible Rust crate (e.g., fuse, fuse3 or equivalent). * The system must compile and run on x86 architectures. * The project must include build configuration files (e.g., Cargo.toml) and clear instructions or scripts to build all required binaries. 7. Deliverables 1) Rust source code for: * QRFS core (FUSE operations). * mkfs.qrfs. * fsck.qrfs. * mount.qrfs. * print.qrfs (or equivalent). 2) Compiled binaries for x86. 3) Documentation source (Markdown or LaTeX) and the final generated PDF. 4) A “printed” PDF of the file system produced by the print functionality, ready for physical printing. 8. Required Documentation The documentation must include at least: * Development environment: OS, Rust version, FUSE library version, and dependencies. * Architecture and data structures: description of superblock, inode table, free block map, other structures, logical-block-to-QR mapping, allocation policies, resizing and defragmentation strategy. * Main functions and modules: summary of Rust modules/crates, key functions, and high-level flows of mkfs.qrfs, mount.qrfs, fsck.qrfs, and print functionality. * Usage instructions: how to compile, create, mount, and use QRFS; how to run fsck.qrfs; how to generate the PDF with QR codes. * UML diagram: conceptual diagram of modules (or logical “classes”) and explanation of design decisions (block size, inode format, directory model, etc.). * Bibliography: references on file systems, FUSE, cryptography used (if applicable), and Rust resources. * Source code documentation: meaningful code comments and optionally generated documentation via tools such as rustdoc.