release(v3.0.1): archive create/extract upgrades (7z + RAR via unar) + login focus fix (closes #82)

- add 7z archive format option for multi-file downloads (worker + download streaming)
- expand extraction to support ZIP + 7z formats via 7z, with RAR preferring unar when available
- harden archive extraction against traversal, symlinks, zip-bombs, and empty/escaped outputs
- improve archive job robustness (stale job cleanup, clearer queued/worker errors, correct MIME/filenames)
- UI: archive format selector + name normalization, better “Extract Archive” handling, i18n updates
- fix login screen focus (auto-focus username when login prompt shows)

Closes #82

Author: error311

CHANGELOG.md

@@ -1,6 +1,70 @@
 # Changelog
 
-## Changes 1/11/2025 (V3.0.0)
+## Changes 01/14/2026 (v3.0.1 Archive update + login focus)
+
+`release(v3.0.1): archive create/extract upgrades (7z + RAR via unar) + login focus fix (closes #82)`
+
+**Commit message**  
+
+```text
+release(v3.0.1): archive create/extract upgrades (7z + RAR via unar) + login focus fix (closes #82)
+
+- add 7z archive format option for multi-file downloads (worker + download streaming)
+- expand extraction to support ZIP + 7z formats via 7z, with RAR preferring unar when available
+- harden archive extraction against traversal, symlinks, zip-bombs, and empty/escaped outputs
+- improve archive job robustness (stale job cleanup, clearer queued/worker errors, correct MIME/filenames)
+- UI: archive format selector + name normalization, better “Extract Archive” handling, i18n updates
+- fix login screen focus (auto-focus username when login prompt shows)
+
+Closes #82
+```
+
+**Added**  
+
+- **Archive download format selector (ZIP / 7z)** in the “Download Selected Files as Archive” modal.
+- **7z archive creation** support in the background worker (`zip_worker.php`) using `7zz/7z`.
+- **RAR extraction prefers `unar`** when available (FOSS-friendly); falls back to `7z` when needed.
+- **Archive detection helper** `isArchiveFileName()` supporting:
+  - `.zip`, `.7z`, `.tar.*`, `.gz`, `.bz2`, `.xz`, `.rar`
+  - RAR split parts like `.r01`, `.r02`, etc.
+
+**Changed**  
+
+- **“ZIP” language → “Archive” language** across UI, admin notes, and translations.
+- **Archive job enqueue + download endpoint** now supports a `format` field (`zip` or `7z`):
+  - download streaming sets correct extension + MIME type (`application/zip` or `application/x-7z-compressed`)
+  - filename normalization strips any existing `.zip/.7z` and applies the chosen extension
+- **Archive extraction** is no longer ZIP-only:
+  - ZIP still uses `ZipArchive`
+  - non-ZIP formats use `7z` listing (`7z l -slt`) + extraction of an allow-listed set
+  - RAR parts like `.r01` map to their base `.rar` / `.part1.rar` automatically
+- **Archive queue robustness**
+  - stale queued/working jobs are cleaned up (PID checks + cmdline sanity where available)
+  - queued jobs that never start can surface a clearer error message (“worker did not start…”)
+
+**Fixed**  
+
+- **Login UX:** auto-focus username field when the login prompt appears (reduces “why can’t I type?” friction).
+- **Extract action visibility:** Extract button/menu now appears for supported archive formats (not just `.zip`).
+- **Better extraction feedback:** extraction API returns optional `warning` text; UI shows success + warning separately when partial issues occur.
+
+**Security / Hardening**  
+
+- **Archive extraction safety controls**:
+  - blocks absolute paths / traversal (`../`) and unsupported folder names
+  - skips dotfiles (configurable) instead of extracting hidden entries by default
+  - detects and skips symlinks and removes any symlinks created during extraction
+  - zip-bomb limits: max uncompressed bytes + max files (configurable)
+  - prunes empty outputs that indicate partial/broken extraction and removes any files that escape the extraction root
+
+**Docker**  
+
+- Image now installs **7zip + unar** so archive create/extract works out-of-the-box with FOSS tooling.
+- Ubuntu repo components are restricted to **`main universe`** (avoids non-free repos by default).
+
+---
+
+## Changes 1/11/2026 (V3.0.0)
 
 `release(v3.0.0): storage adapter seam + source-aware core (Sources-ready)`
 
@@ -131,7 +195,7 @@ FileRise v3.0.0 is a major internal milestone: a new storage adapter seam + sour
 
 ---
 
-## Changes 1/2/2025 (v2.13.1)
+## Changes 1/2/2026 (v2.13.1)
 
 `release(v2.13.1): harden Docker startup perms + explicit inline MIME mapping (see #79)`
 

Dockerfile

@@ -33,13 +33,18 @@ ENV DEBIAN_FRONTEND=noninteractive \
     PUID=99 PGID=100
 
 # Install Apache, PHP, and required extensions
-RUN apt-get update && \
+RUN if [ -f /etc/apt/sources.list.d/ubuntu.sources ]; then \
+        sed -i 's/^Components: .*/Components: main universe/' /etc/apt/sources.list.d/ubuntu.sources; \
+    fi && \
+    apt-get update && \
     apt-get upgrade -y && \
     apt-get install -y --no-install-recommends \
       apache2 \
       php php-json php-curl php-zip php-mbstring php-gd php-xml \
       ca-certificates curl git openssl \
       smbclient \
+      7zip \
+      unar \
       clamav clamav-freshclam \
     && apt-get clean && rm -rf /var/lib/apt/lists/*
 

public/api/file/downloadZip.php

@@ -5,8 +5,8 @@
 /**
  * @OA\Post(
  *   path="/api/file/downloadZip.php",
- *   summary="Download multiple files as a ZIP",
- *   description="Requires view access (or own-only with ownership). May be gated by account flag.",
+ *   summary="Queue an archive download",
+ *   description="Queues a background archive build. Requires view access (or own-only with ownership). May be gated by account flag.",
  *   operationId="downloadZip",
  *   tags={"Files"},
  *   security={{"cookieAuth": {}}},
@@ -16,18 +16,19 @@
  *     @OA\JsonContent(
  *       required={"folder","files"},
  *       @OA\Property(property="folder", type="string", example="root"),
- *       @OA\Property(property="files", type="array", @OA\Items(type="string"), example={"a.jpg","b.png"})
+ *       @OA\Property(property="files", type="array", @OA\Items(type="string"), example={"a.jpg","b.png"}),
+ *       @OA\Property(property="format", type="string", example="zip", enum={"zip","7z"}, description="Archive format")
  *     )
  *   ),
  *   @OA\Response(
  *     response=200,
- *     description="ZIP archive",
- *     content={
- *       "application/zip": @OA\MediaType(
- *         mediaType="application/zip",
- *         @OA\Schema(type="string", format="binary")
- *       )
- *     }
+ *     description="Archive job queued",
+ *     @OA\JsonContent(
+ *       @OA\Property(property="ok", type="boolean", example=true),
+ *       @OA\Property(property="token", type="string"),
+ *       @OA\Property(property="statusUrl", type="string"),
+ *       @OA\Property(property="downloadUrl", type="string")
+ *     )
  *   ),
  *   @OA\Response(response=400, description="Invalid input"),
  *   @OA\Response(response=401, description="Unauthorized"),
@@ -40,4 +41,4 @@
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 
 $fileController = new FileController();
-$fileController->downloadZip();
+$fileController->downloadZip();

public/api/file/downloadZipFile.php

@@ -4,14 +4,14 @@
 /**
  * @OA\Get(
  *   path="/api/file/downloadZipFile.php",
- *   summary="Download a finished ZIP by token",
- *   description="Streams the zip once; token is one-shot.",
+ *   summary="Download a finished archive by token",
+ *   description="Streams the archive once; token is one-shot.",
  *   operationId="downloadZipFile",
  *   tags={"Files"},
  *   security={{"cookieAuth": {}}},
  *   @OA\Parameter(name="k", in="query", required=true, @OA\Schema(type="string"), description="Job token"),
  *   @OA\Parameter(name="name", in="query", required=false, @OA\Schema(type="string"), description="Suggested filename"),
- *   @OA\Response(response=200, description="ZIP stream"),
+ *   @OA\Response(response=200, description="Archive stream"),
  *   @OA\Response(response=401, description="Unauthorized"),
  *   @OA\Response(response=404, description="Not found")
  * )
@@ -21,4 +21,4 @@
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 
 $controller = new FileController();
-$controller->downloadZipFile();
+$controller->downloadZipFile();

public/api/file/extractZip.php

@@ -4,8 +4,8 @@
 /**
  * @OA\Post(
  *   path="/api/file/extractZip.php",
- *   summary="Extract ZIP file(s) into a folder",
- *   description="Requires write access on the target folder.",
+ *   summary="Extract archive file(s) into a folder",
+ *   description="Supports ZIP/7Z and RAR extraction via server tools. Requires write access on the target folder.",
  *   operationId="extractZip",
  *   tags={"Files"},
  *   security={{"cookieAuth": {}}},
@@ -15,7 +15,7 @@
  *     @OA\JsonContent(
  *       required={"folder","files"},
  *       @OA\Property(property="folder", type="string", example="root"),
- *       @OA\Property(property="files", type="array", @OA\Items(type="string"), example={"archive.zip"})
+ *       @OA\Property(property="files", type="array", @OA\Items(type="string"), example={"archive.zip","archive.7z"})
  *     )
  *   ),
  *   @OA\Response(response=200, description="Extraction result (model-defined)"),
@@ -30,4 +30,4 @@
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 
 $fileController = new FileController();
-$fileController->extractZip();
+$fileController->extractZip();

public/api/file/zipStatus.php

@@ -4,7 +4,7 @@
 /**
  * @OA\Get(
  *   path="/api/file/zipStatus.php",
- *   summary="Check status of a background ZIP build",
+ *   summary="Check status of a background archive build",
  *   description="Returns status for the authenticated user's token.",
  *   operationId="zipStatus",
  *   tags={"Files"},
@@ -20,4 +20,4 @@
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 
 $controller = new FileController();
-$controller->zipStatus();
+$controller->zipStatus();

public/index.html

@@ -326,7 +326,7 @@ <h2 id="fileListTitle" data-i18n-key="file_list_title">Files in (Root)</h2>
               </div>
               <div class="action-separator secondary-separator" aria-hidden="true"></div>
               <div class="action-group secondary-actions">
-                <button id="downloadZipBtn" class="btn action-btn icon-only" disabled title="Download selected" data-i18n-title="download">
+                <button id="downloadZipBtn" class="btn action-btn icon-only" disabled title="Download archive" data-i18n-title="download_zip">
                   <span class="material-icons" aria-hidden="true">file_download</span>
                 </button>
                 <button id="copySelectedBtn" class="btn action-btn icon-only" disabled title="Copy" data-i18n-title="copy_files">
@@ -344,7 +344,7 @@ <h2 id="fileListTitle" data-i18n-key="file_list_title">Files in (Root)</h2>
                 <button id="deleteSelectedBtn" class="btn action-btn icon-only" disabled title="Delete" data-i18n-title="delete_files">
                   <span class="material-icons" aria-hidden="true">delete</span>
                 </button>
-                <button id="extractZipBtn" class="btn action-btn icon-only" style="display: none;" disabled title="Extract zip" data-i18n-title="extract_zip_button">
+                <button id="extractZipBtn" class="btn action-btn icon-only" style="display: none;" disabled title="Extract archive" data-i18n-title="extract_zip_button">
                   <span class="material-icons" aria-hidden="true">unarchive</span>
                 </button>
                 <button id="toolbarMenuBtn" class="btn action-btn icon-only" title="More actions">
@@ -442,8 +442,13 @@ <h4 data-i18n-key="create_new_file">Create New File</h4>
             </div>
             <div id="downloadZipModal" class="modal" style="display:none;">
               <div class="modal-content">
-                <h4 data-i18n-key="download_zip_title">Download Selected Files as Zip</h4>
-                <p data-i18n-key="download_zip_prompt">Enter a name for the zip file:</p>
+                <h4 data-i18n-key="download_zip_title">Download Selected Files as Archive</h4>
+                <label for="archiveFormatSelect" data-i18n-key="download_archive_format" style="display:block; margin-top:10px;">Archive format</label>
+                <select id="archiveFormatSelect" class="form-control">
+                  <option value="zip">ZIP (.zip)</option>
+                  <option value="7z">7-Zip (.7z)</option>
+                </select>
+                <p data-i18n-key="download_zip_prompt" style="margin-top:10px;">Enter a name for the archive file:</p>
                 <input type="text" id="zipFileNameInput" class="form-control" data-i18n-placeholder="zip_placeholder"
                   placeholder="files.zip" />
                 <div class="modal-footer" style="margin-top:15px; text-align:right;">
@@ -579,7 +584,7 @@ <h3 data-i18n-key="create_new_user_title">Create New User</h3>
             data-action="download_zip"
             data-when="any">
       <i class="material-icons">archive</i>
-      <span>Download as ZIP</span>
+      <span>Download Archive</span>
     </button>
 
     <!-- NEW: multi-download without ZIP -->
@@ -594,7 +599,7 @@ <h3 data-i18n-key="create_new_user_title">Create New User</h3>
             data-action="extract_zip"
             data-when="zip">
       <i class="material-icons">unarchive</i>
-      <span>Extract ZIP</span>
+      <span>Extract Archive</span>
     </button>
 
     <div class="sep" data-when="any"></div>

public/js/adminFolderAccess.js

@@ -374,9 +374,9 @@ function renderFolderGrantsUI(principal, container, folders, grants) {
           ${group(
             tf('write_full', 'Write/Modify'),
             `
-              ${toggle('write', tf('write_full', 'Write (file ops)'), writeMetaChecked, false, tf('write_help', 'File-level: upload, edit, rename, copy, delete, extract ZIPs (no folder creation).'))}
+              ${toggle('write', tf('write_full', 'Write (file ops)'), writeMetaChecked, false, tf('write_help', 'File-level: upload, edit, rename, copy, delete, extract archives (no folder creation).'))}
               ${toggle('edit', tf('edit', 'Edit File'), g.edit, false, tf('edit_help', 'Edit file contents'))}
-              ${toggle('extract', tf('extract', 'Extract ZIP'), g.extract, false, tf('extract_help', 'Extract ZIP archives'))}
+              ${toggle('extract', tf('extract', 'Extract Archive'), g.extract, false, tf('extract_help', 'Extract archive files'))}
               ${toggle('rename', tf('rename', 'Rename File'), g.rename, false, tf('rename_help', 'Rename a file'))}
               ${toggle('copy', tf('copy', 'Copy File'), g.copy, false, tf('copy_help', 'Copy a file'))}
             `,

public/js/adminPanel.js

@@ -679,7 +679,7 @@ function renderAdminEncryptionSection({ config, dark }) {
       </div>
 
       <div class="small text-muted" style="margin-top:8px;">
-        ${tf("encryption_v1_note", "Admin notes:<ul style=\"margin:6px 0 0 18px; padding:0;\"><li>Master key can be set via <code>FR_ENCRYPTION_MASTER_KEY</code> (env overrides the key file) or via <code>META_DIR/encryption_master.key</code> (32 raw bytes).</li><li>Encrypted folders are recursive; shares, shared-folder uploads, WebDAV, and ZIP create/extract are blocked under encrypted folders.</li><li>Video/audio previews are disabled (no HTTP Range) but users can still download files normally.</li></ul>")}
+        ${tf("encryption_v1_note", "Admin notes:<ul style=\"margin:6px 0 0 18px; padding:0;\"><li>Master key can be set via <code>FR_ENCRYPTION_MASTER_KEY</code> (env overrides the key file) or via <code>META_DIR/encryption_master.key</code> (32 raw bytes).</li><li>Encrypted folders are recursive; shares, shared-folder uploads, WebDAV, and archive create/extract are blocked under encrypted folders.</li><li>Video/audio previews are disabled (no HTTP Range) but users can still download files normally.</li></ul>")}
       </div>
     </div>
   `;

public/js/domUtils.js

@@ -2,6 +2,30 @@
 import { t } from './i18n.js?v={{APP_QVER}}';
 import { openDownloadModal } from './fileActions.js?v={{APP_QVER}}';
 
+const ARCHIVE_EXTS = [
+  ".zip",
+  ".7z",
+  ".tar",
+  ".tar.gz",
+  ".tgz",
+  ".tar.bz2",
+  ".tbz2",
+  ".tar.xz",
+  ".txz",
+  ".gz",
+  ".bz2",
+  ".xz",
+  ".rar"
+];
+const RAR_PART_RE = /\.r\d{2}$/i;
+
+export function isArchiveFileName(name) {
+  const lower = String(name || "").toLowerCase();
+  if (!lower) return false;
+  if (RAR_PART_RE.test(lower)) return true;
+  return ARCHIVE_EXTS.some(ext => lower.endsWith(ext));
+}
+
 // Basic DOM Helpers
 export function toggleVisibility(elementId, shouldShow) {
   const element = document.getElementById(elementId);
@@ -60,7 +84,7 @@ export function updateFileActionButtons() {
   const anySelected = selectedCheckboxes.length > 0;
   const anyFolderSelected = selectedFolders.length > 0;
   const anyZip = Array.from(selectedCheckboxes)
-    .some(cb => cb.value.toLowerCase().endsWith(".zip"));
+    .some(cb => isArchiveFileName(cb.value));
   const singleSelected = selectedCheckboxes.length === 1;
   const currentFolderCaps = window.currentFolderCaps || null;
   const selectedFolderCaps = window.selectedFolderCaps || null;
@@ -158,7 +182,7 @@ export function updateFileActionButtons() {
   if (shareBtn) shareBtn.style.display = (showFileActions && !inEncryptedFolder) ? "" : "none";
   if (createBtn) createBtn.style.display = "";
 
-  // Extract ZIP still appears only when a .zip is selected (and file mode)
+  // Extract archive appears only when a supported archive is selected (and file mode)
   if (extractZipBtn) extractZipBtn.style.display = (showFileActions && anyZip && !inEncryptedFolder) ? "" : "none";
 
   // Finally disable the ones that are shown but shouldn’t be clickable