ci(release): touch version.js to trigger release-on-version workflow

Updated the video demo date and link in README.

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+---
+github: [error311]
+ko_fi: error311

.github/workflows/release-on-version.yml

@@ -0,0 +1,107 @@
+---
+name: Release on version.js update
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - public/js/version.js
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: release-${{ github.ref }}-${{ github.sha }}
+      cancel-in-progress: false
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Read version from version.js
+        id: ver
+        shell: bash
+        run: |
+          set -euo pipefail
+          VER=$(grep -Eo "APP_VERSION\s*=\s*['\"]v[^'\"]+['\"]" public/js/version.js | sed -E "s/.*['\"](v[^'\"]+)['\"].*/\1/")
+          if [[ -z "$VER" ]]; then
+            echo "Could not parse APP_VERSION from version.js" >&2
+            exit 1
+          fi
+          echo "version=$VER" >> "$GITHUB_OUTPUT"
+          echo "Parsed version: $VER"
+
+      - name: Skip if tag already exists
+        id: tagcheck
+        shell: bash
+        run: |
+          set -euo pipefail
+          git fetch --tags --quiet
+          if git rev-parse -q --verify "refs/tags/${{ steps.ver.outputs.version }}" >/dev/null; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "Tag ${{ steps.ver.outputs.version }} already exists. Skipping release."
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Prepare release notes from CHANGELOG.md (optional)
+        if: steps.tagcheck.outputs.exists == 'false'
+        id: notes
+        shell: bash
+        run: |
+          set -euo pipefail
+          NOTES_PATH=""
+          if [[ -f CHANGELOG.md ]]; then
+            awk '
+              BEGIN{found=0}
+              /^## / && !found {found=1}
+              found && /^---$/ {exit}
+              found {print}
+            ' CHANGELOG.md > RELEASE_BODY.md || true
+
+            # Trim trailing blank lines
+            sed -i -e :a -e '/^\n*$/{$d;N;ba' -e '}' RELEASE_BODY.md || true
+
+            if [[ -s RELEASE_BODY.md ]]; then
+              NOTES_PATH="RELEASE_BODY.md"
+            fi
+          fi
+          echo "path=$NOTES_PATH" >> "$GITHUB_OUTPUT"
+
+      - name: (optional) Build archive to attach
+        if: steps.tagcheck.outputs.exists == 'false'
+        shell: bash
+        run: |
+          set -euo pipefail
+          zip -r "FileRise-${{ steps.ver.outputs.version }}.zip" public/ README.md LICENSE >/dev/null || true
+
+      # Path A: we have extracted notes -> use body_path
+      - name: Create GitHub Release (with CHANGELOG snippet)
+        if: steps.tagcheck.outputs.exists == 'false' && steps.notes.outputs.path != ''
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.ver.outputs.version }}
+          target_commitish: ${{ github.sha }}
+          name: ${{ steps.ver.outputs.version }}
+          body_path: ${{ steps.notes.outputs.path }}
+          generate_release_notes: false
+          files: |
+            FileRise-${{ steps.ver.outputs.version }}.zip
+
+      # Path B: no notes -> let GitHub auto-generate from commits
+      - name: Create GitHub Release (auto notes)
+        if: steps.tagcheck.outputs.exists == 'false' && steps.notes.outputs.path == ''
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.ver.outputs.version }}
+          target_commitish: ${{ github.sha }}
+          name: ${{ steps.ver.outputs.version }}
+          generate_release_notes: true
+          files: |
+            FileRise-${{ steps.ver.outputs.version }}.zip

.github/workflows/sync-changelog.yml

@@ -1,5 +1,5 @@
 ---
-name: Sync Changelog to Docker Repo
+name: Bump version and sync Changelog to Docker Repo
 
 on:
   push:
@@ -10,35 +10,69 @@ permissions:
   contents: write
 
 jobs:
-  sync:
+  bump_and_sync:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout FileRise
-        uses: actions/checkout@v4
-        with:
-          path: file-rise
+      - uses: actions/checkout@v4
+
+      - name: Extract version from commit message
+        id: ver
+        run: |
+          MSG="${{ github.event.head_commit.message }}"
+          if [[ "$MSG" =~ release\((v[0-9]+\.[0-9]+\.[0-9]+)\) ]]; then
+            echo "version=${BASH_REMATCH[1]}" >> $GITHUB_OUTPUT
+            echo "Found version: ${BASH_REMATCH[1]}"
+          else
+            echo "version=" >> $GITHUB_OUTPUT
+            echo "No release(vX.Y.Z) tag in commit message; skipping bump."
+          fi
+
+      - name: Update public/js/version.js
+        if: steps.ver.outputs.version != ''
+        run: |
+          cat > public/js/version.js <<'EOF'
+          // generated by CI
+          window.APP_VERSION = '${{ steps.ver.outputs.version }}';
+          EOF
+
+      - name: Commit version.js (if changed)
+        if: steps.ver.outputs.version != ''
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add public/js/version.js
+          if git diff --cached --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "chore: set APP_VERSION to ${{ steps.ver.outputs.version }}"
+            git push
+          fi
 
       - name: Checkout filerise-docker
+        if: steps.ver.outputs.version != ''
         uses: actions/checkout@v4
         with:
           repository: error311/filerise-docker
           token: ${{ secrets.PAT_TOKEN }}
           path: docker-repo
 
-      - name: Copy CHANGELOG.md
+      - name: Copy CHANGELOG.md and write VERSION
+        if: steps.ver.outputs.version != ''
         run: |
-          cp file-rise/CHANGELOG.md docker-repo/CHANGELOG.md
+          cp CHANGELOG.md docker-repo/CHANGELOG.md
+          echo "${{ steps.ver.outputs.version }}" > docker-repo/VERSION
 
-      - name: Commit & push
+      - name: Commit & push to docker repo
+        if: steps.ver.outputs.version != ''
         working-directory: docker-repo
         run: |
           git config user.name  "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add CHANGELOG.md
+          git add CHANGELOG.md VERSION
           if git diff --cached --quiet; then
             echo "No changes to commit"
           else
-            git commit -m "chore: sync CHANGELOG.md from FileRise"
+            git commit -m "chore: sync CHANGELOG.md and VERSION (${{ steps.ver.outputs.version }}) from FileRise"
             git push origin main
           fi

CHANGELOG.md

@@ -1,5 +1,408 @@
 # Changelog
 
+## Changes 10/25/2025 (v1.6.8)
+
+release(v1.6.8): fix(ui) prevent Extract/Create flash on refresh; remember last folder
+
+- Seed `currentFolder` from `localStorage.lastOpenedFolder` (fallback to "root")
+- Stop eager `loadFileList('root')` on boot; defer initial load to resolved folder
+- Hide capability-gated actions by default (`#extractZipBtn`, `#createBtn`) to avoid pre-auth flash
+- Eliminates transient root state when reloading inside a subfolder
+
+User-visible: refreshing a non-root folder no longer flashes Root items or privileged buttons; app resumes in the last opened folder.
+
+---
+
+## Changes 10/25/2025 (v1.6.7)
+
+release(v1.6.7): Folder Move feature, stable DnD persistence, safer uploads, and ACL/UI polish
+
+### 📂 Folder Move (new major feature)
+
+**Drag & Drop to move folder, use context menu or Move Folder button**  
+
+- Added **Move Folder** support across backend and UI.  
+  - New API endpoint: `public/api/folder/moveFolder.php`  
+  - Controller and ACL updates to validate scope, ownership, and permissions.  
+  - Non-admins can only move within folders they own.  
+  - `ACL::renameTree()` re-keys all subtree ACLs on folder rename/move.  
+- Introduced new capabilities:
+  - `canMoveFolder`
+  - `canMove` (UI alias for backward compatibility)
+- New “Move Folder” button + modal in the UI with full i18n strings (`i18n.js`).  
+- Action button styling and tooltip consistency for all folder actions.
+
+### 🧱 Drag & Drop / Layout Improvements
+
+- Fixed **random sidebar → top zone jumps** on refresh.  
+- Cards/panels now **persist exactly where you placed them** (`userZonesSnapshot`)  
+  — no unwanted repositioning unless the window is resized below the small-screen threshold.
+- Added hysteresis around the 1205 px breakpoint to prevent flicker when resizing.  
+- Eliminated the 50 px “ghost” gutter with `clampSidebarWhenEmpty()`:
+  - Sidebar no longer reserves space when collapsed or empty.  
+  - Temporarily “unclamps” during drag so drop targets remain accurate and full-width.  
+- Removed forced 800 px height on drag highlight; uses natural flex layout now.  
+- General layout polish — smoother transitions when toggling *Hide/Show Panels*.
+
+### ☁️ Uploads & UX
+
+- Stronger folder sanitization and safer base-path handling.  
+- Fixed subfolder creation when uploading directories (now builds under correct parent).  
+- Improved chunk error handling and metadata key correctness.  
+- Clearer success/failure toasts and accurate filename display from server responses.
+
+### 🔐 Permissions / ACL
+
+- Simplified file rename checks — now rely solely on granular `ACL::canRename()`.  
+- Updated capability lists to include move/rename operations consistently.
+
+### 🌐 UI / i18n Enhancements
+
+- Added i18n strings for new “Move Folder” prompts, modals, and tooltips.  
+- Minor UI consistency tweaks: button alignment, focus states, reduced-motion support.  
+
+---
+
+## Changes 10/24/2025 (v1.6.6)
+
+release(v1.6.6): header-mounted toggle, dark-mode polish, persistent layout, and ACL fix
+
+- dragAndDrop: mount zones toggle beside header logo (absolute, non-scrolling);
+  stop click propagation so it doesn’t trigger the logo link; theme-aware styling
+  - live updates via MutationObserver; snapshot card locations on drop and restore
+  on load (prevents sidebar reset); guard first-run defaults with
+  `layoutDefaultApplied_v1`; small/medium layout tweaks & refactors.
+- CSS: switch toggle icon to CSS variable (`--toggle-icon-color`) with dark-mode
+  override; remove hardcoded `!important`.
+- API (capabilities.php): remove unused `disableUpload` flag from `canUpload`
+  and flags payload to resolve undefined variable warning.
+
+---
+
+## Changes 10/24/2025 (v1.6.5)
+
+release(v1.6.5): fix PHP warning and upload-flag check in capabilities.php
+
+- Fix undefined variable: use $disableUpload consistently
+- Harden flag read: (bool)($perms['disableUpload'] ?? false)
+- Prevents warning and ensures Upload capability is computed correctly
+
+---
+
+## Changes 10/24/2025 (v1.6.4)
+
+release(v1.6.4): runtime version injection + CI bump/sync; caching tweaks
+
+- Add public/js/version.js (default "dev") and load it before main.js.
+- adminPanel.js: replace hard-coded string with `window.APP_VERSION || "dev"`.
+- public/.htaccess: add no-cache for js/version.js
+- GitHub Actions: replace sync job with “Bump version and sync Changelog to Docker Repo”.
+  - Parse commit msg `release(vX.Y.Z)` -> set step output `version`.
+  - Write `public/js/version.js` with `window.APP_VERSION = '<version>'`.
+  - Commit/push version.js if changed.
+  - Mirror CHANGELOG.md to filerise-docker and write a VERSION file with `<version>`.
+  - Guard all steps with `if: steps.ver.outputs.version != ''` to no-op on non-release commits.
+
+This wires the UI version label to CI, keeps dev builds showing “dev”, and feeds the Docker repo with CHANGELOG + VERSION for builds.
+
+---
+
+## Changes 10/24/2025 (v1.6.3)
+
+release(v1.6.3): drag/drop card persistence, admin UX fixes, and docs (closes #58)
+
+Drag & Drop - Upload/Folder Management Cards layout
+
+- Persist panel locations across refresh; snapshot + restore when collapsing/expanding.
+- Unified “zones” toggle; header-icon mode no longer loses card state.
+- Responsive: auto-move sidebar cards to top on small screens; restore on resize.
+- Better top-zone placeholder/cleanup during drag; tighter header modal sizing.
+- Safer order saving + deterministic placement for upload/folder cards.
+
+Admin Panel – Folder Access
+
+- Fix: newly created folders now appear without a full page refresh (cache-busted `getFolderList`).
+- Show admin users in the list with full access pre-applied and inputs disabled (read-only).
+- Skip sending updates for admins when saving grants.
+- “Folder” column now has its own horizontal scrollbar so long names / “Inherited from …” are never cut off.
+
+Admin Panel – User Permissions (flags)
+
+- Show admins (marked as Admin) with all switches disabled; exclude from save payload.
+- Clarified helper text (account-level vs per-folder).
+
+UI/Styling
+
+- Added `.folder-cell` scroller in ACL table; improved dark-mode scrollbar/thumb.
+
+Docs
+
+- README edits:
+  - Clarified PUID/PGID mapping and host/NAS ownership requirements for mounted volumes.
+  - Environment variables section added
+  - CHOWN_ON_START additional details
+  - Admin details
+  - Upgrade section added
+  - 💖 Sponsor FileRise section added
+
+---
+
+## Changes 10/23/2025 (v1.6.2)
+
+feat(i18n,auth): add Simplified Chinese (zh-CN) and expose in User Panel
+
+- Add zh-CN locale to i18n.js with full key set.
+- Introduce chinese_simplified label key across locales.
+- Added some missing labels
+- Update language selector mapping to include zh-CN (English/Spanish/French/German/简体中文).
+- Wire zh-CN into Auth/User Panel (authModals) language dropdown.
+- Fallback-safe rendering for language names when a key is missing.
+
+ui: fix “Change Password” button sizing in User Panel
+
+- Keep consistent padding and font size for cleaner layout
+
+---
+
+## Changes 10/23/2025 (v1.6.1)
+
+feat(ui): unified zone toggle + polished interactions for sidebar/top cards
+
+- Add floating toggle button styling (hover lift, press, focus ring, ripple)
+  for #zonesToggleFloating and #sidebarToggleFloating (CSS).
+- Ensure icons are visible and centered; enforce consistent sizing/color.
+- Introduce unified “zones collapsed” state persisted via `localStorage.zonesCollapsed`.
+- Update dragAndDrop.js to:
+  - manage a single floating toggle for both Sidebar and Top Zone
+  - keep toggle visible when cards are in Top Zone; hide only when both cards are in Header
+  - rotate icon 90° when both cards are in Top Zone and panels are open
+  - respect collapsed state during DnD flows and on load
+  - preserve original DnD behaviors and saved orders (sidebar/header)
+- Minor layout/visibility fixes during drag (clear temp heights; honor collapsed).
+
+Notes:
+
+- No breaking API changes; existing `sidebarOrder` / `headerOrder` continue to work.
+- New key: `zonesCollapsed` (string '0'/'1') controls visibility of Sidebar + Top Zone.
+
+UX:
+
+- Floating toggle feels more “material”: subtle hover elevation, press feedback,
+  focus ring, and click ripple to restore the prior interactive feel.
+- Icons remain legible on white (explicit color set), centered in the circular button.
+
+---
+
+## Changes 10/22/2025 (v1.6.0)
+
+feat(acl): granular per-folder permissions + stricter gates; WebDAV & UI aligned
+
+- Add granular ACL buckets: create, upload, edit, rename, copy, move, delete, extract, share_file, share_folder
+- Implement ACL::canX helpers and expand upsert/explicit APIs (preserve read_own)
+- Enforce “write no longer implies read” in canRead; use granular gates for write-ish ops
+- WebDAV: use canDelete for DELETE, canUpload/canEdit + disableUpload for PUT; enforce ownership on overwrite
+- Folder create: require Manage/Owner on parent; normalize paths; seed ACL; rollback on failure
+- FileController: refactor copy/move/rename/delete/extract to granular gates + folder-scope checks + own-only ownership enforcement
+- Capabilities API: compute effective actions with scope + readOnly/disableUpload; protect root
+- Admin Panel (v1.6.0): new Folder Access editor with granular caps, inheritance hints, bulk toggles, and UX validations
+- getFileList: keep root visible but inert for users without visibility; apply own-only filtering server-side
+- Bump version to v1.6.0
+
+---
+
+## Changes 10/20/2025 (v1.5.3)
+
+security(acl): enforce folder-scope & own-only; fix file list “Select All”; harden ops
+
+### fileListView.js (v1.5.3)
+
+- Restore master “Select All” checkbox behavior and row highlighting.
+- Keep selection working with own-only filtered lists.
+- Build preview/thumb URLs via secure API endpoints; avoid direct /uploads.
+- Minor UI polish: slider wiring and pagination focus handling.
+
+### FileController.php (v1.5.3)
+
+- Add enforceFolderScope($folder, $user, $perms, $need) and apply across actions.
+- Copy/Move: require read on source, write on destination; apply scope on both.
+- When user only has read_own, enforce per-file ownership (uploader==user).
+- Extract ZIP: require write + scope; consistent 403 messages.
+- Save/Rename/Delete/Create: tighten ACL checks; block dangerous extensions; consistent CSRF/Auth handling and error codes.
+- Download/ZIP: honor read vs read_own; own-only gates by uploader; safer headers.
+
+### FolderController.php (v1.5.3)
+
+- Align with ACL: enforce folder-scope for non-admins; require owner or bypass for destructive ops.
+- Create/Rename/Delete: gate by write on parent/target + ownership when needed.
+- Share folder link: require share capability; forbid root sharing for non-admins; validate expiry; optional password.
+- Folder listing: return only folders user can fully view or has read_own.
+- Shared downloads/uploads: stricter validation, headers, and error handling.
+
+This commits a consistent, least-privilege ACL model (owners/read/write/share/read_own), fixes bulk-select in the UI, and closes scope/ownership gaps across file & folder actions.
+
+feat(dnd): default cards to sidebar on medium screens when no saved layout
+
+- Adds one-time responsive default in loadSidebarOrder() (uses layoutDefaultApplied_v1)
+- Preserves existing sidebarOrder/headerOrder and small-screen behavior
+- Keeps user changes persistent; no override once a layout exists
+
+feat(editor): make modal non-blocking; add SRI + timeout for CodeMirror mode loads
+
+- Build the editor modal immediately and wire close (✖, Close button, and Esc) before any async work, so the UI is always dismissible.
+- Restore MODE_URL and add normalizeModeName() to resolve aliases (text/html → htmlmixed, php → application/x-httpd-php).
+- Add SRI for each lazily loaded mode (MODE_SRI) and apply integrity/crossOrigin on script tags; switch to async and improved error messages.
+- Introduce MODE_LOAD_TIMEOUT_MS=2500 and Promise.race() to init in text/plain if a mode is slow; auto-upgrade to the real mode once it arrives.
+- Graceful fallback: if CodeMirror core isn’t present, keep textarea, enable Save, and proceed.
+- Minor UX: disable Save until the editor is ready, support theme toggling, better resize handling, and font size controls without blocking.
+
+Security: Locks CDN mode scripts with SRI.
+
+---
+
+## Changes 10/19/2025 (v1.5.2)
+
+fix(admin): modal bugs; chore(api): update ReDoc SRI; docs(openapi): add annotations + spec
+
+- adminPanel.js
+  - Fix modal open/close reliability and stacking order
+  - Prevent background scroll while modal is open
+  - Tidy focus/keyboard handling for better UX
+
+- style.css
+  - Polish styles for Folder Access + Users views (spacing, tables, badges)
+  - Improve responsiveness and visual consistency
+
+- api.php
+  - Update Redoc SRI hash and pin to the current bundle URL
+
+- OpenAPI
+  - Add/refresh inline @OA annotations across endpoints
+  - Introduce src/openapi/Components.php with base Info/Server,
+    common responses, and shared components
+  - Regenerate and commit openapi.json.dist
+
+- public/js/adminPanel.js
+- public/css/style.css
+- public/api.php
+- src/openapi/Components.php
+- openapi.json.dist
+- public/api/** (annotated endpoints)
+
+---
+
+## Changes 10/19/2025 (v1.5.1)
+
+fix(config/ui): serve safe public config to non-admins; init early; gate trash UI to admins; dynamic title; demo toast (closes #56)
+
+Regular users were getting 403s from `/api/admin/getConfig.php`, breaking header title and login option rendering. Issue #56 tracks this.
+
+### What changed
+
+- **AdminController::getConfig**
+  - Return a **public, non-sensitive subset** of config for everyone (incl. unauthenticated and non-admin users): `header_title`, minimal `loginOptions` (disable* flags only), `globalOtpauthUrl`, `enableWebDAV`, `sharedMaxUploadSize`, and OIDC `providerUrl`/`redirectUri`.
+  - For **admins**, merge in admin-only fields (`authBypass`, `authHeaderName`).
+  - Never expose secrets or client IDs.
+- **auth.js**
+  - `loadAdminConfigFunc()` now robustly handles empty/204 responses, writes sane defaults, and sets `document.title` from `header_title`.
+  - `showToast()` override: on `demo.filerise.net` shows a longer demo-creds toast; keeps TOTP “don’t nag” behavior.
+- **main.js**
+  - Call `loadAdminConfigFunc()` early during app init.
+  - Run `setupTrashRestoreDelete()` **only for admins** (based on `localStorage.isAdmin`).
+- **adminPanel.js**
+  - Bump visible version to **v1.5.1**.
+- **index.html**
+  - Keep `<title>FileRise</title>` static; runtime title now driven by `loadAdminConfigFunc()`.
+
+### Security v1.5.1
+
+- Prevents info disclosure by strictly limiting non-admin fields.
+- Avoids noisy 403 for regular users while keeping admin-only data protected.
+
+### QA
+
+- As a non-admin:
+  - Opening the app no longer triggers a 403 on `getConfig.php`.
+  - Header title and login options render; document tab title updates to configured `header_title`.
+  - Trash/restore UI is not initialized.
+- As an admin:
+  - Admin Panel loads extra fields; trash/restore UI initializes.
+  - Title updates correctly.
+- On `demo.filerise.net`:
+  - Pre-login toast shows demo credentials for ~12s.
+
+Closes #56.
+
+---
+
+## Changes 10/17/2025 (v1.5.0)
+
+Security and permission model overhaul. Tightens access controls with explicit, server‑side ACL checks across controllers and WebDAV. Introduces `read_own` for own‑only visibility and separates view from write so uploaders can’t automatically see others’ files. Fixes session warnings and aligns the admin UI with the new capabilities.
+
+> **Security note**
+> This release contains security hardening based on a private report (tracked via a GitHub Security Advisory, CVE pending). For responsible disclosure, details will be published alongside the advisory once available. Users should upgrade promptly.
+
+### Highlights
+
+- **ACL**
+  - New `read_own` bucket (own‑only visibility) alongside `owners`, `read`, `write`, `share`.
+  - **Semantic change:** `write` no longer implies `read`.
+  - `ACL::applyUserGrantsAtomic()` to atomically set per‑folder grants (`view`, `viewOwn`, `upload`, `manage`, `share`).
+  - `ACL::purgeUser($username)` to remove a user from all buckets (used when deleting a user).
+  - Auto‑heal `folder_acl.json` (ensure `root` exists; add missing buckets; de‑dupe; normalize types).
+  - More robust admin detection (role flag or session/admin user).
+
+- **Controllers**
+  - `FileController`: ACL + ownership enforcement for list, download, zip download, extract, move, copy, rename, create, save, tag edit, and share‑link creation. `getFileList()` now filters to the caller’s uploads when they only have `read_own` (no `read`).
+  - `UploadController`: requires `ACL::canWrite()` for the target folder; CSRF refresh path improved; admin bypass intact.
+  - `FolderController`: listing filtered by `ACL::canRead()`; optional parent filter preserved; removed name‑based ownership assumptions.
+
+- **Admin UI**
+  - Folder Access grid now includes **View (own)**; bulk toolbar actions; column alignment fixes; more space for folder names; dark‑mode polish.
+
+- **WebDAV**
+  - WebDAV now enforces ACL consistently: listing requires `read` (or `read_own` ⇒ shows only caller’s files); writes require `write`.
+  - Removed legacy “folderOnly” behavior — ACL is the single source of truth.
+  - Metadata/uploader is preserved through existing models.
+
+### Behavior changes (⚠️ Breaking)
+
+- **`write` no longer implies `read`.**
+  - If you want uploaders to see all files in a folder, also grant **View (all)** (`read`).
+  - If you want uploaders to see only their own files, grant **View (own)** (`read_own`).
+
+- **Removed:** legacy `folderOnly` view logic in favor of ACL‑based access.
+
+### Upgrade checklist
+
+1. Review **Folder Access** in the admin UI and grant **View (all)** or **View (own)** where appropriate.
+2. For users who previously had “upload but not view,” confirm they now have **Upload** + **View (own)** (or add **View (all)** if intended).
+3. Verify WebDAV behavior for representative users:
+   - `read` shows full listings; `read_own` lists only the caller’s files.
+   - Writes only succeed where `write` is granted.
+4. Confirm admin can upload/move/zip across all folders (regression tested).
+
+### Affected areas
+
+- `config/config.php` — session/cookie initialization ordering; proxy header handling.
+- `src/lib/ACL.php` — new bucket, semantics, healing, purge, admin detection.
+- `src/controllers/FileController.php` — ACL + ownership gates across operations.
+- `src/controllers/UploadController.php` — write checks + CSRF refresh handling.
+- `src/controllers/FolderController.php` — ACL‑filtered listing and parent scoping.
+- `public/api/admin/acl/*.php` — includes `viewOwn` round‑trip and sanitization.
+- `public/js/*` & CSS — folder access grid alignment and layout fixes.
+- `src/webdav/*` & `public/webdav.php` — ACL‑aware WebDAV server.
+
+### Credits
+
+- Security report acknowledged privately and will be credited in the published advisory.
+
+### Fix
+
+- fix(folder-model): resolve syntax error, unexpected token
+- Deleted accidental second `<?php`
+
+---
+
 ## Changes 10/15/2025 (v1.4.0)
 
 feat(permissions)!: granular ACL (bypassOwnership/canShare/canZip/viewOwnOnly), admin panel v1.4.0 UI, and broad hardening across controllers/models/frontend

README.md

@@ -2,19 +2,30 @@
 
 [![GitHub stars](https://img.shields.io/github/stars/error311/FileRise?style=social)](https://github.com/error311/FileRise)
 [![Docker pulls](https://img.shields.io/docker/pulls/error311/filerise-docker)](https://hub.docker.com/r/error311/filerise-docker)
+[![Docker CI](https://img.shields.io/github/actions/workflow/status/error311/filerise-docker/main.yml?branch=main&label=Docker%20CI)](https://github.com/error311/filerise-docker/actions/workflows/main.yml)
 [![CI](https://img.shields.io/github/actions/workflow/status/error311/FileRise/ci.yml?branch=master&label=CI)](https://github.com/error311/FileRise/actions/workflows/ci.yml)
-[![Demo](https://img.shields.io/badge/demo-live-brightgreen)](https://demo.filerise.net) **demo / demo**
+[![Demo](https://img.shields.io/badge/demo-live-brightgreen)](https://demo.filerise.net)
 [![Release](https://img.shields.io/github/v/release/error311/FileRise?include_prereleases&sort=semver)](https://github.com/error311/FileRise/releases)
 [![License](https://img.shields.io/github/license/error311/FileRise)](LICENSE)
+[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-❤-red)](https://github.com/sponsors/error311)
+[![Support on Ko-fi](https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-orange)](https://ko-fi.com/error311)
 
 **Quick links:** [Demo](#live-demo) • [Install](#installation--setup) • [Docker](#1-running-with-docker-recommended) • [Unraid](#unraid) • [WebDAV](#quick-start-mount-via-webdav) • [FAQ](#faq--troubleshooting)
 
-**Elevate your File Management** – A modern, self-hosted web file manager.
-Upload, organize, and share files or folders through a sleek web interface. **FileRise** is lightweight yet powerful: think of it as your personal cloud drive that you control. With drag-and-drop uploads, in-browser editing, secure user logins (with SSO and 2FA support), and one-click sharing, **FileRise** makes file management on your server a breeze.
+**Elevate your File Management** – A modern, self-hosted web file manager.  
+Upload, organize, and share files or folders through a sleek, responsive web interface.  
+**FileRise** is lightweight yet powerful — your personal cloud drive that you fully control.  
 
-**4/3/2025 Video demo:**
+Now featuring **Granular Access Control (ACL)** with per-folder permissions, inheritance, and live admin editing.  
+Grant precise capabilities like *view*, *upload*, *rename*, *delete*, or *manage* on a per-user, per-folder basis — enforced across the UI, API, and WebDAV.  
 
-<https://github.com/user-attachments/assets/221f6a53-85f5-48d4-9abe-89445e0af90e>
+With drag-and-drop uploads, in-browser editing, secure user logins (SSO & TOTP 2FA), and one-click public sharing, **FileRise** brings professional-grade file management to your own server — simple to deploy, easy to scale, and fully self-hosted.
+
+> ⚠️ **Security fix in v1.5.0** — ACL hardening. If you’re on ≤1.4.x, please upgrade.
+
+**10/25/2025 Video demo:**
+
+<https://github.com/user-attachments/assets/a2240300-6348-4de7-b72f-1b85b7da3a08>
 
 **Dark mode:**
 ![Dark Header](https://raw.githubusercontent.com/error311/FileRise/refs/heads/master/resources/dark-header.png)
@@ -23,29 +34,57 @@ Upload, organize, and share files or folders through a sleek web interface. **Fi
 
 ## Features at a Glance or [Full Features Wiki](https://github.com/error311/FileRise/wiki/Features)
 
-- 🚀 **Easy File Uploads:** Upload multiple files and folders via drag & drop or file picker. Supports large files with pause/resumable chunked uploads and shows real-time progress for each file. FileRise will pick up where it left off if your connection drops.
+- 🚀 **Easy File Uploads:** Upload multiple files and folders via drag & drop or file picker. Supports large files with resumable chunked uploads, pause/resume, and real-time progress. If your connection drops, FileRise resumes automatically.
 
-- 🗂️ **File Management:** Full set of file/folder operations – move or copy files (via intuitive drag-drop or dialogs), rename items, and delete in batches. You can download selected files as a ZIP archive or extract uploaded ZIP files server-side. Organize content with an interactive folder tree and breadcrumb navigation for quick jumps.
+- 🗂️ **File Management:** Full suite of operations — move/copy (via drag-drop or dialogs), rename, and batch delete. Download selected files as ZIPs or extract uploaded ZIPs server-side. Organize with an interactive folder tree and breadcrumbs for instant navigation.
 
-- 🗃️ **Folder Sharing & File Sharing:** Share entire folders via secure, expiring public links. Folder shares can be password-protected, and shared folders support file uploads from outside users with a separate, secure upload mechanism. Folder listings are paginated (10 items per page) with navigation controls; file sizes are displayed in MB for clarity. Share individual files with one-time or expiring links (optional password protection).
+- 🗃️ **Folder & File Sharing:** Share folders or individual files with expiring, optionally password-protected links. Shared folders can accept external uploads (if enabled). Listings are paginated (10 items/page) with file sizes shown in MB.
 
-- 🔌 **WebDAV Support:** Mount FileRise as a network drive **or use it head-less from the CLI**. Standard WebDAV operations (upload / download / rename / delete) work in Cyberduck, WinSCP, GNOME Files, Finder, etc., and you can also script against it with `curl` – see the [WebDAV](https://github.com/error311/FileRise/wiki/WebDAV) + [curl](https://github.com/error311/FileRise/wiki/Accessing-FileRise-via-curl-(WebDAV)) quick-starts. Folder-Only users are restricted to their personal directory; admins and unrestricted users have full access.
+- 🔐 **Granular Access Control (ACL):**  
+  Per-folder permissions for **owners**, **view**, **view (own)**, **write**, **manage**, **share**, and extended granular capabilities.  
+  Each grant controls specific actions across the UI, API, and WebDAV:
 
-- 📚 **API Documentation:** Auto-generated OpenAPI spec (`openapi.json`) and interactive HTML docs (`api.html`) powered by Redoc.
+  | Permission | Description |
+  |-------------|-------------|
+  | **Manage (Owner)** | Full control of folder and subfolders. Can edit ACLs, rename/delete/create folders, and share items. Implies all other permissions for that folder and below. |
+  | **View (All)** | Allows viewing all files within the folder. Required for folder-level sharing. |
+  | **View (Own)** | Restricts visibility to files uploaded by the user only. Ideal for drop zones or limited-access users. |
+  | **Write** | Grants general write access — enables renaming, editing, moving, copying, deleting, and extracting files. |
+  | **Create** | Allows creating subfolders. Automatically granted to *Manage* users. |
+  | **Upload** | Allows uploading new files without granting full write privileges. |
+  | **Edit / Rename / Copy / Move / Delete / Extract** | Individually toggleable granular file operations. |
+  | **Share File / Share Folder** | Controls sharing capabilities. Folder shares require full View (All). |
 
-- 📝 **Built-in Editor & Preview:** View images, videos, audio, and PDFs inline with a preview modal. Edit text/code files in your browser with a CodeMirror-based editor featuring syntax highlighting and line numbers.
+  - **Automatic Propagation:** Enabling **Manage** on a folder applies to all subfolders; deselecting subfolder permissions overrides inheritance in the UI.
 
-- 🏷️ **Tags & Search:** Categorize your files with color-coded tags and locate them instantly using indexed real-time search. **Advanced Search** adds fuzzy matching across file names, tags, uploader fields, and within text file contents.
+  ACL enforcement is centralized and atomic across:
+  - **Admin Panel:** Interactive ACL editor with batch save and dynamic inheritance visualization.  
+  - **API Endpoints:** All file/folder operations validate server-side.  
+  - **WebDAV:** Uses the same ACL engine — View / Own determine listings, granular permissions control upload/edit/delete/create.
 
-- 🔒 **User Authentication & Permissions:** Username/password login with multi-user support (admin UI). Current permissions: **Folder-only**, **Read-only**, **Disable upload**. SSO via OIDC providers (Google/Authentik/Keycloak) and optional TOTP 2FA.
+- 🔌 **WebDAV (ACL-Aware):** Mount FileRise as a drive (Cyberduck, WinSCP, Finder, etc.) or access via `curl`.  
+  - Listings require **View** or **View (Own)**.  
+  - Uploads require **Upload**.  
+  - Overwrites require **Edit**.  
+  - Deletes require **Delete**.  
+  - Creating folders requires **Create** or **Manage**.  
+  - All ACLs and ownership rules are enforced exactly as in the web UI.
 
-- 🎨 **Responsive UI (Dark/Light Mode):** Mobile-friendly layout with theme toggle. The interface remembers your preferences (layout, items per page, last visited folder, etc.).
+- 📚 **API Documentation:** Auto-generated OpenAPI spec (`openapi.json`) with interactive HTML docs (`api.html`) via Redoc.
 
-- 🌐 **Internationalization & Localization:** Switch languages via the UI (English, Spanish, French, German). Contributions welcome.
+- 📝 **Built-in Editor & Preview:** Inline preview for images, video, audio, and PDFs. CodeMirror-based editor for text/code with syntax highlighting and line numbers.
 
-- 🗑️ **Trash & File Recovery:** Deleted items go to Trash first; admins can restore or empty. Old trash entries auto-purge (default 3 days).
+- 🏷️ **Tags & Search:** Add color-coded tags and search by name, tag, uploader, or content. Advanced fuzzy search indexes metadata and file contents.
 
-- ⚙️ **Lightweight & Self-Contained:** Runs on PHP **8.3+** with no external database. Single-folder install or Docker image. Low footprint; scales to thousands of files with pagination and sorting.
+- 🔒 **Authentication & SSO:** Username/password, optional TOTP 2FA, and OIDC (Google, Authentik, Keycloak).
+
+- 🗑️ **Trash & Recovery:** Deleted items move to Trash for recovery (default 3-day retention). Admins can restore or purge globally.
+
+- 🎨 **Responsive UI (Dark/Light Mode):** Modern, mobile-friendly design with persistent preferences (theme, layout, last folder, etc.).
+
+- 🌐 **Internationalization:** English, Spanish, French, German & Simplified Chinese available. Community translations welcome.
+
+- ⚙️ **Lightweight & Self-Contained:** Runs on PHP 8.3+, no external DB required. Single-folder or Docker deployment with minimal footprint, optimized for Unraid and self-hosting.
 
 (For full features and changelogs, see the [Wiki](https://github.com/error311/FileRise/wiki), [CHANGELOG](https://github.com/error311/FileRise/blob/master/CHANGELOG.md) or [Releases](https://github.com/error311/FileRise/releases).)
 
@@ -56,7 +95,7 @@ Upload, organize, and share files or folders through a sleek web interface. **Fi
 [![Demo](https://img.shields.io/badge/demo-live-brightgreen)](https://demo.filerise.net)
 **Demo credentials:** `demo` / `demo`
 
-Curious about the UI? **Check out the live demo:** <https://demo.filerise.net> (login with username “demo” and password “demo”). *The demo is read-only for security*. Explore the interface, switch themes, preview files, and see FileRise in action!
+Curious about the UI? **Check out the live demo:** <https://demo.filerise.net> (login with username “demo” and password “demo”). **The demo is read-only for security.** Explore the interface, switch themes, preview files, and see FileRise in action!
 
 ---
 
@@ -66,6 +105,22 @@ Deploy FileRise using the **Docker image** (quickest) or a **manual install** on
 
 ---
 
+### Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `TIMEZONE` | `UTC` | PHP/app timezone. |
+| `DATE_TIME_FORMAT` | `m/d/y  h:iA` | Display format used in UI. |
+| `TOTAL_UPLOAD_SIZE` | `5G` | Max combined upload per request (resumable). |
+| `SECURE` | `false` | Set `true` if served behind HTTPS proxy (affects link generation). |
+| `PERSISTENT_TOKENS_KEY` | *(required)* | Secret for “Remember Me” tokens. Change from the example! |
+| `PUID` / `PGID` | `1000` / `1000` | Map `www-data` to host uid:gid (Unraid: often `99:100`). |
+| `CHOWN_ON_START` | `true` | First run: try to chown mounted dirs to PUID:PGID. |
+| `SCAN_ON_START` | `true` | Reindex files added outside UI at boot. |
+| `SHARE_URL` | *(blank)* | Override base URL for share links; blank = auto-detect. |
+
+---
+
 ### 1) Running with Docker (Recommended)
 
 #### Pull the image
@@ -96,6 +151,8 @@ docker run -d \
   error311/filerise-docker:latest
 ```
 
+The app runs as www-data mapped to PUID/PGID. Ensure your mounted uploads/, users/, metadata/ are owned by PUID:PGID (e.g., chown -R 1000:1000 …), or set PUID/PGID to match existing host ownership (e.g., 99:100 on Unraid). On NAS/NFS, apply the ownership change on the host/NAS.
+
 This starts FileRise on port **8080** → visit `http://your-server-ip:8080`.
 
 **Notes**  
@@ -146,6 +203,8 @@ services:
 Access at `http://localhost:8080` (or your server’s IP).  
 The example sets a custom `PERSISTENT_TOKENS_KEY`—change it to a strong random string.
 
+- “`CHOWN_ON_START=true` attempts to align ownership **inside the container**; if the host/NAS disallows changes, set the correct UID/GID on the host.”
+
 **First-time Setup**  
 On first launch, if no users exist, you’ll be prompted to create an **Admin account**. Then use **User Management** to add more users.
 
@@ -210,6 +269,13 @@ Browse to your FileRise URL; you’ll be prompted to create the Admin user on fi
 
 ---
 
+### 3) Admins
+
+> **Admins in ACL UI**
+> Admin accounts appear in the Folder Access and User Permissions modals as **read-only** with full access implied. This is by design—admins always have full control and are excluded from save payloads.
+
+---
+
 ## Unraid
 
 - Install from **Community Apps** → search **FileRise**.  
@@ -219,6 +285,16 @@ Browse to your FileRise URL; you’ll be prompted to create the Admin user on fi
 
 ---
 
+## Upgrade
+
+```bash
+docker pull error311/filerise-docker:latest
+docker stop filerise && docker rm filerise
+# re-run with the same -v and -e flags you used originally
+```
+
+---
+
 ## Quick-start: Mount via WebDAV
 
 Once FileRise is running, enable WebDAV in the admin panel.
@@ -281,6 +357,16 @@ For more Q&A or to ask for help, open a Discussion or Issue.
 
 ---
 
+## Security posture
+
+We practice responsible disclosure. All known security issues are fixed in **v1.5.0** (ACL hardening).
+Advisories: [GHSA-6p87-q9rh-95wh](https://github.com/error311/FileRise/security/advisories/GHSA-6p87-q9rh-95wh) (≤ 1.3.15), [GHSA-jm96-2w52-5qjj](https://github.com/error311/FileRise/security/advisories/GHSA-jm96-2w52-5qjj) (v1.4.0). Fixed in **v1.5.0**. Thanks to [@kiwi865](https://github.com/kiwi865) for reporting.
+If you’re running ≤1.4.x, please upgrade.
+
+See also: [SECURITY.md](./SECURITY.md) for how to report vulnerabilities.
+
+---
+
 ## Contributing
 
 Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).  
@@ -289,6 +375,17 @@ If you like FileRise, a ⭐ star on GitHub is much appreciated!
 
 ---
 
+## 💖 Sponsor FileRise
+
+If FileRise saves you time (or sparks joy 😄), please consider supporting ongoing development:
+
+- ❤️ [**GitHub Sponsors:**](https://github.com/sponsors/error311) recurring or one-time - helps fund new features and docs.
+- ☕ [**Ko-fi:**](https://ko-fi.com/error311) buy me a coffee.
+
+Every bit helps me keep FileRise fast, polished, and well-maintained. Thank you!
+
+---
+
 ## Community and Support
 
 - **Reddit:** [r/selfhosted: FileRise Discussion](https://www.reddit.com/r/selfhosted/comments/1kfxo9y/filerise_v131_major_updates_sneak_peek_at_whats/) – (Announcement and user feedback thread).

SECURITY.md

@@ -4,35 +4,58 @@
 
 We provide security fixes for the latest minor release line.
 
-| Version     | Supported |
-|------------|-----------|
-| v1.4.x     | ✅        |
-| < v1.4.0   | ❌        |
+| Version   | Supported |
+|----------|-----------|
+| v1.5.x   | ✅        |
+| ≤ v1.4.x | ❌        |
+
+> Known issues in ≤ v1.4.x are fixed in **v1.5.0** and later.
 
 ## Reporting a Vulnerability
 
-If you discover a security vulnerability, please do not open a public issue. Instead, follow these steps:
+**Please do not open a public issue.** Use one of the private channels below:
 
-1. **Email Us Privately:**  
-   Send an email to [security@filerise.net](mailto:security@filerise.net) with the subject line “[FileRise] Security Vulnerability Report”.
+1) **GitHub Security Advisory (preferred)**  
+   Open a private report here: <https://github.com/error311/FileRise/security/advisories/new>
 
-2. **Include Details:**  
-   Provide a detailed description of the vulnerability, steps to reproduce it, and any other relevant information (e.g., affected versions, screenshots, logs).
+2) **Email**  
+   Send details to **<security@filerise.net>** with subject: `[FileRise] Security Vulnerability Report`.
 
-3. **Secure Communication (Optional):**  
-   If you wish to discuss the vulnerability securely, you can use our PGP key. You can obtain our PGP key by emailing us, and we will send it upon request.
+### What to include
 
-## Disclosure Policy
+- Affected versions (e.g., v1.4.0), component/endpoint, and impact
+- Reproduction steps / PoC
+- Any logs, screenshots, or crash traces
+- Safe test scope used (see below)
 
-- **Acknowledgement:**  
-  We will acknowledge receipt of your report within 48 hours.
-  
-- **Resolution Timeline:**  
-  We aim to fix confirmed vulnerabilities within 30 days. In cases where a delay is necessary, we will communicate updates to you directly.
+If you’d like encrypted comms, ask for our PGP key in your first email.
 
-- **Public Disclosure:**  
-  After a fix is available, details of the vulnerability will be disclosed publicly in a way that does not compromise user security.
+## Coordinated Disclosure
 
-## Additional Information
+- **Acknowledgement:** within **48 hours**  
+- **Triage & initial assessment:** within **7 days**  
+- **Fix target:** within **30 days** for high-severity issues (may vary by complexity)
+- **CVE & advisory:** we publish a GitHub Security Advisory and request a CVE when appropriate.  
+  We notify the reporter before public disclosure and credit them (unless they prefer to remain anonymous).
 
-We appreciate responsible disclosure of vulnerabilities and thank all researchers who help keep FileRise secure. For any questions related to this policy, please contact us at [admin@filerise.net](mailto:admin@filerise.net).
+## Safe-Harbor / Rules of Engagement
+
+We support good-faith research. Please:
+
+- Avoid privacy violations, data exfiltration, and service disruption (no DoS, spam, or brute-forcing)
+- Don’t access other users’ data beyond what’s necessary to demonstrate the issue
+- Don’t run automated scans against production installs you don’t own
+- Follow applicable laws and make a good-faith effort to respect data and availability
+
+If you follow these guidelines, we won’t pursue or support legal action.
+
+## Published Advisories
+
+- **GHSA-6p87-q9rh-95wh** — ≤ **1.3.15**: Improper ownership/permission validation allowed cross-tenant file operations.  
+- **GHSA-jm96-2w52-5qjj** — **v1.4.0**: Insecure folder visibility via name-based mapping and incomplete ACL checks.  
+
+Both are fixed in **v1.5.0** (ACL hardening). Thanks to **[@kiwi865](https://github.com/kiwi865)** for responsible disclosure.
+
+## Questions
+
+General security questions: **<admin@filerise.net>**

config/config.php

@@ -35,13 +35,12 @@ define('REGEX_USER',       '/^[\p{L}\p{N}_\- ]+$/u');
 
 date_default_timezone_set(TIMEZONE);
 
-
 if (!defined('DEFAULT_BYPASS_OWNERSHIP')) define('DEFAULT_BYPASS_OWNERSHIP', false);
 if (!defined('DEFAULT_CAN_SHARE'))        define('DEFAULT_CAN_SHARE', true);
 if (!defined('DEFAULT_CAN_ZIP'))          define('DEFAULT_CAN_ZIP', true);
 if (!defined('DEFAULT_VIEW_OWN_ONLY'))    define('DEFAULT_VIEW_OWN_ONLY', false);
-
-
+define('FOLDER_OWNERS_FILE', META_DIR . 'folder_owners.json');
+define('ACL_INHERIT_ON_CREATE', true);
 
 // Encryption helpers
 function encryptData($data, $encryptionKey)
@@ -77,16 +76,27 @@ function loadUserPermissions($username)
 {
     global $encryptionKey;
     $permissionsFile = USERS_DIR . 'userPermissions.json';
-    if (file_exists($permissionsFile)) {
-        $content = file_get_contents($permissionsFile);
-        $decrypted = decryptData($content, $encryptionKey);
-        $json = ($decrypted !== false) ? $decrypted : $content;
-        $perms = json_decode($json, true);
-        if (is_array($perms) && isset($perms[$username])) {
-            return !empty($perms[$username]) ? $perms[$username] : false;
-        }
+    if (!file_exists($permissionsFile)) {
+        return false;
     }
-    return false;
+
+    $content   = file_get_contents($permissionsFile);
+    $decrypted = decryptData($content, $encryptionKey);
+    $json      = ($decrypted !== false) ? $decrypted : $content;
+    $permsAll  = json_decode($json, true);
+
+    if (!is_array($permsAll)) {
+        return false;
+    }
+
+    // Try exact match first, then lowercase (since we store keys lowercase elsewhere)
+    $uExact = (string)$username;
+    $uLower = strtolower($uExact);
+
+    $row = $permsAll[$uExact] ?? $permsAll[$uLower] ?? null;
+
+    // Normalize: always return an array when found, else false (to preserve current callers’ behavior)
+    return is_array($row) ? $row : false;
 }
 
 // Determine HTTPS usage
@@ -96,25 +106,39 @@ $secure = ($envSecure !== false)
     : (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off');
 
 // Choose session lifetime based on "remember me" cookie
-$defaultSession = 7200;           // 2 hours
-$persistentDays = 30 * 24 * 60 * 60; // 30 days
-$sessionLifetime = isset($_COOKIE['remember_me_token'])
-    ? $persistentDays
-    : $defaultSession;
-
-// Configure PHP session cookie and GC
-session_set_cookie_params([
-    'lifetime' => $sessionLifetime,
-    'path'     => '/',
-    'domain'   => '',      // adjust if you need a specific domain
-    'secure'   => $secure,
-    'httponly' => true,
-    'samesite' => 'Lax'
-]);
-ini_set('session.gc_maxlifetime', (string)$sessionLifetime);
+$defaultSession  = 7200;              // 2 hours
+$persistentDays  = 30 * 24 * 60 * 60; // 30 days
+$sessionLifetime = isset($_COOKIE['remember_me_token']) ? $persistentDays : $defaultSession;
 
+/**
+ * Start session idempotently:
+ * - If no session: set cookie params + gc_maxlifetime, then session_start().
+ * - If session already active: DO NOT change ini/cookie params; optionally refresh cookie expiry.
+ */
 if (session_status() === PHP_SESSION_NONE) {
+    session_set_cookie_params([
+        'lifetime' => $sessionLifetime,
+        'path'     => '/',
+        'domain'   => '',      // adjust if you need a specific domain
+        'secure'   => $secure,
+        'httponly' => true,
+        'samesite' => 'Lax'
+    ]);
+    ini_set('session.gc_maxlifetime', (string)$sessionLifetime);
     session_start();
+} else {
+    // Optionally refresh the session cookie expiry to keep the user alive
+    $params = session_get_cookie_params();
+    if ($sessionLifetime > 0) {
+        setcookie(session_name(), session_id(), [
+            'expires'  => time() + $sessionLifetime,
+            'path'     => $params['path']     ?: '/',
+            'domain'   => $params['domain']   ?? '',
+            'secure'   => $secure,
+            'httponly' => true,
+            'samesite' => $params['samesite'] ?? 'Lax',
+        ]);
+    }
 }
 
 // CSRF token
@@ -122,8 +146,7 @@ if (empty($_SESSION['csrf_token'])) {
     $_SESSION['csrf_token'] = bin2hex(random_bytes(32));
 }
 
-
-// Auto‑login via persistent token
+// Auto-login via persistent token
 if (empty($_SESSION["authenticated"]) && !empty($_COOKIE['remember_me_token'])) {
     $tokFile = USERS_DIR . 'persistent_tokens.json';
     $tokens = [];

public/.htaccess

@@ -50,6 +50,12 @@ RewriteEngine On
   <FilesMatch "\.(js|css)$">
     Header set Cache-Control "public, max-age=3600, must-revalidate"
   </FilesMatch>
+  # version.js should always revalidate (it changes on releases)
+  <FilesMatch "^js/version\.js$">
+    Header set Cache-Control "no-cache, no-store, must-revalidate"
+    Header set Pragma "no-cache"
+    Header set Expires "0"
+  </FilesMatch>
 </IfModule>
 
 # -----------------------------

public/api.php

@@ -20,7 +20,7 @@ if (isset($_GET['spec'])) {
   <meta name="viewport" content="width=device-width, initial-scale=1"/>
   <title>FileRise API Docs</title>
   <script defer src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"
-          integrity="sha384-4vOjrBu7SuDWXcAw1qFznVLA/sKL+0l4nn+J1HY8w7cpa6twQEYuh4b0Cwuo7CyX"
+          integrity="sha384-70P5pmIdaQdVbxvjhrcTDv1uKcKqalZ3OHi7S2J+uzDl0PW8dO6L+pHOpm9EEjGJ"
           crossorigin="anonymous"></script>
   <script defer src="/js/redoc-init.js"></script>
 </head>

public/api/addUser.php

@@ -1,6 +1,40 @@
 <?php
 // public/api/addUser.php
 
+    /**
+     * @OA\Post(
+     *     path="/api/addUser.php",
+     *     summary="Add a new user",
+     *     description="Adds a new user to the system. In setup mode, the new user is automatically made admin.",
+     *     operationId="addUser",
+     *     tags={"Users"},
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"username", "password"},
+     *             @OA\Property(property="username", type="string", example="johndoe"),
+     *             @OA\Property(property="password", type="string", example="securepassword"),
+     *             @OA\Property(property="isAdmin", type="boolean", example=true)
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="User added successfully",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="success", type="string", example="User added successfully")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=400,
+     *         description="Bad Request"
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 

public/api/admin/acl/getGrants.php

@@ -0,0 +1,85 @@
+<?php
+// public/api/admin/acl/getGrants.php
+declare(strict_types=1);
+
+require_once __DIR__ . '/../../../../config/config.php';
+require_once PROJECT_ROOT . '/src/lib/ACL.php';
+require_once PROJECT_ROOT . '/src/models/FolderModel.php';
+
+if (session_status() !== PHP_SESSION_ACTIVE) session_start();
+header('Content-Type: application/json');
+
+if (empty($_SESSION['authenticated']) || empty($_SESSION['isAdmin'])) {
+  http_response_code(401); echo json_encode(['error'=>'Unauthorized']); exit;
+}
+
+$user = trim((string)($_GET['user'] ?? ''));
+if ($user === '' || !preg_match(REGEX_USER, $user)) {
+  http_response_code(400); echo json_encode(['error'=>'Invalid user']); exit;
+}
+
+// Build the folder list (admin sees all)
+$folders = [];
+try {
+  $rows = FolderModel::getFolderList();
+  if (is_array($rows)) {
+    foreach ($rows as $r) {
+      $f = is_array($r) ? ($r['folder'] ?? '') : (string)$r;
+      if ($f !== '') $folders[$f] = true;
+    }
+  }
+} catch (Throwable $e) { /* ignore */ }
+
+if (empty($folders)) {
+  $aclPath = rtrim(META_DIR, "/\\") . DIRECTORY_SEPARATOR . 'folder_acl.json';
+  if (is_file($aclPath)) {
+    $data = json_decode((string)@file_get_contents($aclPath), true);
+    if (is_array($data['folders'] ?? null)) {
+      foreach ($data['folders'] as $name => $_) $folders[$name] = true;
+    }
+  }
+}
+
+$folderList = array_keys($folders);
+if (!in_array('root', $folderList, true)) array_unshift($folderList, 'root');
+
+$has = function(array $arr, string $u): bool {
+  foreach ($arr as $x) if (strcasecmp((string)$x, $u) === 0) return true;
+  return false;
+};
+
+$out = [];
+foreach ($folderList as $f) {
+  $rec = ACL::explicitAll($f); // legacy + granular
+
+  $isOwner    = $has($rec['owners'], $user);
+  $canViewAll = $isOwner || $has($rec['read'], $user);
+  $canViewOwn = $has($rec['read_own'], $user);
+  $canShare   = $isOwner || $has($rec['share'], $user);
+  $canUpload  = $isOwner || $has($rec['write'], $user) || $has($rec['upload'], $user);
+
+  if ($canViewAll || $canViewOwn || $canUpload || $canShare || $isOwner
+      || $has($rec['create'],$user) || $has($rec['edit'],$user) || $has($rec['rename'],$user)
+      || $has($rec['copy'],$user) || $has($rec['move'],$user) || $has($rec['delete'],$user)
+      || $has($rec['extract'],$user) || $has($rec['share_file'],$user) || $has($rec['share_folder'],$user)) {
+    $out[$f] = [
+      'view'        => $canViewAll,
+      'viewOwn'     => $canViewOwn,
+      'write'       => $has($rec['write'], $user) || $isOwner,
+      'manage'      => $isOwner,
+      'share'       => $canShare, // legacy
+      'create'      => $isOwner || $has($rec['create'], $user),
+      'upload'      => $isOwner || $has($rec['upload'], $user) || $has($rec['write'],$user),
+      'edit'        => $isOwner || $has($rec['edit'], $user)   || $has($rec['write'],$user),
+      'rename'      => $isOwner || $has($rec['rename'], $user) || $has($rec['write'],$user),
+      'copy'        => $isOwner || $has($rec['copy'], $user)   || $has($rec['write'],$user),
+      'move'        => $isOwner || $has($rec['move'], $user)   || $has($rec['write'],$user),
+      'delete'      => $isOwner || $has($rec['delete'], $user) || $has($rec['write'],$user),
+      'extract'     => $isOwner || $has($rec['extract'], $user)|| $has($rec['write'],$user),
+      'shareFile'   => $isOwner || $has($rec['share_file'], $user) || $has($rec['share'],$user),
+      'shareFolder' => $isOwner || $has($rec['share_folder'], $user) || $has($rec['share'],$user),
+    ];
+  }
+}
+
+echo json_encode(['grants' => $out], JSON_UNESCAPED_SLASHES);

public/api/admin/acl/saveGrants.php

@@ -0,0 +1,121 @@
+<?php
+// public/api/admin/acl/saveGrants.php
+declare(strict_types=1);
+
+require_once __DIR__ . '/../../../../config/config.php';
+require_once PROJECT_ROOT . '/src/lib/ACL.php';
+
+if (session_status() !== PHP_SESSION_ACTIVE) session_start();
+header('Content-Type: application/json');
+
+// ---- Auth + CSRF -----------------------------------------------------------
+if (empty($_SESSION['authenticated']) || empty($_SESSION['isAdmin'])) {
+  http_response_code(401);
+  echo json_encode(['error' => 'Unauthorized']);
+  exit;
+}
+
+$headers = function_exists('getallheaders') ? array_change_key_case(getallheaders(), CASE_LOWER) : [];
+$csrf    = trim($headers['x-csrf-token'] ?? ($_POST['csrfToken'] ?? ''));
+
+if (empty($_SESSION['csrf_token']) || $csrf !== $_SESSION['csrf_token']) {
+  http_response_code(403);
+  echo json_encode(['error' => 'Invalid CSRF token']);
+  exit;
+}
+
+// ---- Helpers ---------------------------------------------------------------
+function normalize_caps(array $row): array {
+  // booleanize known keys
+  $bool = function($v){ return !empty($v) && $v !== 'false' && $v !== 0; };
+  $k = [
+    'view','viewOwn','upload','manage','share',
+    'create','edit','rename','copy','move','delete','extract',
+    'shareFile','shareFolder','write'
+  ];
+  $out = [];
+  foreach ($k as $kk) $out[$kk] = $bool($row[$kk] ?? false);
+
+  // BUSINESS RULES:
+  // A) Share Folder REQUIRES View (all). If shareFolder is true but view is false, force view=true.
+  if ($out['shareFolder'] && !$out['view']) {
+    $out['view'] = true;
+  }
+
+  // B) Share File requires at least View (own). If neither view nor viewOwn set, set viewOwn=true.
+  if ($out['shareFile'] && !$out['view'] && !$out['viewOwn']) {
+    $out['viewOwn'] = true;
+  }
+
+  // C) "write" does NOT imply view. It also does not imply granular here; ACL expands legacy write if present.
+  return $out;
+}
+
+function sanitize_grants_map(array $grants): array {
+  $out = [];
+  foreach ($grants as $folder => $caps) {
+    if (!is_string($folder)) $folder = (string)$folder;
+    if (!is_array($caps))    $caps   = [];
+    $out[$folder] = normalize_caps($caps);
+  }
+  return $out;
+}
+
+function valid_user(string $u): bool {
+  return ($u !== '' && preg_match(REGEX_USER, $u));
+}
+
+// ---- Read JSON body --------------------------------------------------------
+$raw = file_get_contents('php://input');
+$in  = json_decode((string)$raw, true);
+if (!is_array($in)) {
+  http_response_code(400);
+  echo json_encode(['error' => 'Invalid JSON']);
+  exit;
+}
+
+// ---- Single user mode: { user, grants } ------------------------------------
+if (isset($in['user']) && isset($in['grants']) && is_array($in['grants'])) {
+  $user = trim((string)$in['user']);
+  if (!valid_user($user)) {
+    http_response_code(400);
+    echo json_encode(['error' => 'Invalid user']);
+    exit;
+  }
+
+  $grants = sanitize_grants_map($in['grants']);
+
+  try {
+    $res = ACL::applyUserGrantsAtomic($user, $grants);
+    echo json_encode($res, JSON_UNESCAPED_SLASHES);
+    exit;
+  } catch (Throwable $e) {
+    http_response_code(500);
+    echo json_encode(['error' => 'Failed to save grants', 'detail' => $e->getMessage()]);
+    exit;
+  }
+}
+
+// ---- Batch mode: { changes: [ { user, grants }, ... ] } --------------------
+if (isset($in['changes']) && is_array($in['changes'])) {
+  $updated = [];
+  foreach ($in['changes'] as $chg) {
+    if (!is_array($chg)) continue;
+    $user = trim((string)($chg['user'] ?? ''));
+    $gr   = $chg['grants'] ?? null;
+    if (!valid_user($user) || !is_array($gr)) continue;
+
+    try {
+      $res = ACL::applyUserGrantsAtomic($user, sanitize_grants_map($gr));
+      $updated[$user] = $res['updated'] ?? [];
+    } catch (Throwable $e) {
+      $updated[$user] = ['error' => $e->getMessage()];
+    }
+  }
+  echo json_encode(['ok' => true, 'updated' => $updated], JSON_UNESCAPED_SLASHES);
+  exit;
+}
+
+// ---- Fallback --------------------------------------------------------------
+http_response_code(400);
+echo json_encode(['error' => 'Invalid payload: expected {user,grants} or {changes:[{user,grants}]}']);

public/api/admin/getConfig.php

@@ -1,6 +1,30 @@
 <?php
 // public/api/admin/getConfig.php
 
+/**
+ * @OA\Get(
+ *   path="/api/admin/getConfig.php",
+ *   tags={"Admin"},
+ *   summary="Get UI configuration",
+ *   description="Returns a public subset for everyone; authenticated admins receive additional loginOptions fields.",
+ *   operationId="getAdminConfig",
+ *   @OA\Response(
+ *     response=200,
+ *     description="Configuration loaded",
+ *     @OA\JsonContent(
+ *       oneOf={
+ *         @OA\Schema(ref="#/components/schemas/AdminGetConfigPublic"),
+ *         @OA\Schema(ref="#/components/schemas/AdminGetConfigAdmin")
+ *       }
+ *     )
+ *   ),
+ *   @OA\Response(response=500, description="Server error")
+ * )
+ *
+ * Retrieves the admin configuration settings and outputs JSON.
+ * @return void
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/AdminController.php';
 

public/api/admin/readMetadata.php

@@ -1,6 +1,35 @@
 <?php
 // public/api/admin/readMetadata.php
 
+/**
+ * @OA\Get(
+ *   path="/api/admin/readMetadata.php",
+ *   summary="Read share metadata JSON",
+ *   description="Admin-only: returns the cleaned metadata for file or folder share links.",
+ *   tags={"Admin"},
+ *   operationId="readMetadata",
+ *   security={{"cookieAuth":{}}},
+ *   @OA\Parameter(
+ *     name="file",
+ *     in="query",
+ *     required=true,
+ *     description="Which metadata file to read",
+ *     @OA\Schema(type="string", enum={"share_links.json","share_folder_links.json"})
+ *   ),
+ *   @OA\Response(
+ *     response=200,
+ *     description="OK",
+ *     @OA\JsonContent(oneOf={
+ *       @OA\Schema(ref="#/components/schemas/ShareLinksMap"),
+ *       @OA\Schema(ref="#/components/schemas/ShareFolderLinksMap")
+ *     })
+ *   ),
+ *   @OA\Response(response=400, description="Missing or invalid file param"),
+ *   @OA\Response(response=403, description="Forbidden (admin only)"),
+ *   @OA\Response(response=500, description="Corrupted JSON")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 
 // Only admins may read these

public/api/admin/updateConfig.php

@@ -1,6 +1,45 @@
 <?php
 // public/api/admin/updateConfig.php
 
+/**
+ * @OA\Put(
+ *   path="/api/admin/updateConfig.php",
+ *   summary="Update admin configuration",
+ *   description="Merges the provided settings into the on-disk configuration and persists them. Requires an authenticated admin session and a valid CSRF token. When OIDC is enabled (disableOIDCLogin=false), `providerUrl`, `redirectUri`, and `clientId` are required and must be HTTPS (HTTP allowed only for localhost).",
+ *   operationId="updateAdminConfig",
+ *   tags={"Admin"},
+ *   security={ {{"cookieAuth": {}, "CsrfHeader": {}}} },
+ *
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(ref="#/components/schemas/AdminUpdateConfigRequest")
+ *   ),
+ *
+ *   @OA\Response(
+ *     response=200,
+ *     description="Configuration updated",
+ *     @OA\JsonContent(ref="#/components/schemas/SimpleSuccess")
+ *   ),
+ *   @OA\Response(
+ *     response=400,
+ *     description="Validation error (e.g., bad authHeaderName, missing OIDC fields when enabled, or negative upload limit)",
+ *     @OA\JsonContent(ref="#/components/schemas/SimpleError")
+ *   ),
+ *   @OA\Response(
+ *     response=403,
+ *     description="Unauthorized access or invalid CSRF token",
+ *     @OA\JsonContent(ref="#/components/schemas/SimpleError")
+ *     // or: ref to the reusable response
+ *     // ref="#/components/responses/Forbidden"
+ *   ),
+ *   @OA\Response(
+ *     response=500,
+ *     description="Server error while loading or saving configuration",
+ *     @OA\JsonContent(ref="#/components/schemas/SimpleError")
+ *   )
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/AdminController.php';
 

public/api/auth/auth.php

@@ -1,6 +1,52 @@
 <?php
 // public/api/auth/auth.php
 
+/**
+     * @OA\Post(
+     *     path="/api/auth/auth.php",
+     *     summary="Authenticate user",
+     *     description="Handles user authentication via OIDC or form-based credentials. For OIDC flows, processes callbacks; otherwise, performs standard authentication with optional TOTP verification.",
+     *     operationId="authUser",
+     *     tags={"Auth"},
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"username", "password"},
+     *             @OA\Property(property="username", type="string", example="johndoe"),
+     *             @OA\Property(property="password", type="string", example="secretpassword"),
+     *             @OA\Property(property="remember_me", type="boolean", example=true),
+     *             @OA\Property(property="totp_code", type="string", example="123456")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="Login successful; returns user info and status",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="status", type="string", example="ok"),
+     *             @OA\Property(property="success", type="string", example="Login successful"),
+     *             @OA\Property(property="username", type="string", example="johndoe"),
+     *             @OA\Property(property="isAdmin", type="boolean", example=true)
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=400,
+     *         description="Bad Request (e.g., missing credentials)"
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized (e.g., invalid credentials, too many attempts)"
+     *     ),
+     *     @OA\Response(
+     *         response=429,
+     *         description="Too many failed login attempts"
+     *     )
+     * )
+     *
+     * Handles user authentication via OIDC or form-based login.
+     *
+     * @return void Redirects on success or outputs JSON error.
+     */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/vendor/autoload.php';
 require_once PROJECT_ROOT . '/src/controllers/AuthController.php';

public/api/auth/checkAuth.php

@@ -1,6 +1,35 @@
 <?php
 // public/api/auth/checkAuth.php
 
+/**
+ * @OA\Get(
+ *   path="/api/auth/checkAuth.php",
+ *   summary="Check authentication status",
+ *   operationId="checkAuth",
+ *   tags={"Auth"},
+ *   @OA\Response(
+ *     response=200,
+ *     description="Authenticated status or setup flag",
+ *     @OA\JsonContent(
+ *       oneOf={
+ *         @OA\Schema(
+ *           type="object",
+ *           @OA\Property(property="authenticated", type="boolean", example=true),
+ *           @OA\Property(property="isAdmin", type="boolean", example=true),
+ *           @OA\Property(property="totp_enabled", type="boolean", example=false),
+ *           @OA\Property(property="username", type="string", example="johndoe"),
+ *           @OA\Property(property="folderOnly", type="boolean", example=false)
+ *         ),
+ *         @OA\Schema(
+ *           type="object",
+ *           @OA\Property(property="setup", type="boolean", example=true)
+ *         )
+ *       }
+ *     )
+ *   )
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/AuthController.php';
 

public/api/auth/login_basic.php

@@ -1,6 +1,32 @@
 <?php
 // public/api/auth/login_basic.php
 
+    /**
+     * @OA\Get(
+     *     path="/api/auth/login_basic.php",
+     *     summary="Authenticate using HTTP Basic Authentication",
+     *     description="Performs HTTP Basic authentication. If credentials are missing, sends a 401 response prompting for Basic auth. On valid credentials, optionally handles TOTP verification and finalizes session login.",
+     *     operationId="loginBasic",
+     *     tags={"Auth"},
+     *     @OA\Response(
+     *         response=200,
+     *         description="Login successful; redirects to index.html",
+     *         @OA\JsonContent(
+     *             type="object",
+     *             @OA\Property(property="success", type="string", example="Login successful")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized due to missing credentials or invalid credentials."
+     *     )
+     * )
+     *
+     * Handles HTTP Basic authentication (with optional TOTP) and logs the user in.
+     *
+     * @return void Redirects on success or sends a 401 header.
+     */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/AuthController.php';
 

public/api/auth/logout.php

@@ -1,6 +1,28 @@
 <?php
 // public/api/auth/logout.php
 
+    /**
+     * @OA\Post(
+     *     path="/api/auth/logout.php",
+     *     summary="Logout user",
+     *     description="Clears the session, removes persistent login tokens, and redirects the user to the login page.",
+     *     operationId="logoutUser",
+     *     tags={"Auth"},
+     *     @OA\Response(
+     *         response=302,
+     *         description="Redirects to the login page with a logout flag."
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized"
+     *     )
+     * )
+     *
+     * Logs the user out by clearing session data, removing persistent tokens, and destroying the session.
+     *
+     * @return void Redirects to index.html with a logout flag.
+     */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/AuthController.php';
 

public/api/auth/token.php

@@ -1,6 +1,29 @@
 <?php
 // public/api/auth/token.php
 
+    /**
+     * @OA\Get(
+     *     path="/api/auth/token.php",
+     *     summary="Retrieve CSRF token and share URL",
+     *     description="Returns the current CSRF token along with the configured share URL.",
+     *     operationId="getToken",
+     *     tags={"Auth"},
+     *     @OA\Response(
+     *         response=200,
+     *         description="CSRF token and share URL",
+     *         @OA\JsonContent(
+     *             type="object",
+     *             @OA\Property(property="csrf_token", type="string", example="0123456789abcdef..."),
+     *             @OA\Property(property="share_url", type="string", example="https://yourdomain.com/share.php")
+     *         )
+     *     )
+     * )
+     *
+     * Returns the CSRF token and share URL.
+     *
+     * @return void Outputs the JSON response.
+     */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/AuthController.php';
 

public/api/changePassword.php

@@ -1,6 +1,44 @@
 <?php
 // public/api/changePassword.php
 
+    /**
+     * @OA\Post(
+     *     path="/api/changePassword.php",
+     *     summary="Change user password",
+     *     description="Allows an authenticated user to change their password by verifying the old password and updating to a new one.",
+     *     operationId="changePassword",
+     *     tags={"Users"},
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"oldPassword", "newPassword", "confirmPassword"},
+     *             @OA\Property(property="oldPassword", type="string", example="oldpass123"),
+     *             @OA\Property(property="newPassword", type="string", example="newpass456"),
+     *             @OA\Property(property="confirmPassword", type="string", example="newpass456")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="Password updated successfully",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="success", type="string", example="Password updated successfully.")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=400,
+     *         description="Bad Request"
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized"
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Invalid CSRF token"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 

public/api/file/copyFiles.php

@@ -1,6 +1,36 @@
 <?php
 // public/api/file/copyFiles.php
 
+/**
+ * @OA\Post(
+ *   path="/api/file/copyFiles.php",
+ *   summary="Copy files between folders",
+ *   description="Requires read access on source and write access on destination. Enforces folder scope and ownership.",
+ *   operationId="copyFiles",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(
+ *     name="X-CSRF-Token", in="header", required=true,
+ *     description="CSRF token from the current session",
+ *     @OA\Schema(type="string")
+ *   ),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"source","destination","files"},
+ *       @OA\Property(property="source", type="string", example="root"),
+ *       @OA\Property(property="destination", type="string", example="userA/projects"),
+ *       @OA\Property(property="files", type="array", @OA\Items(type="string"), example={"report.pdf","notes.txt"})
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Copy result (model-defined)"),
+ *   @OA\Response(response=400, description="Invalid request or folder name"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/createFile.php

@@ -1,6 +1,30 @@
 <?php
 // public/api/file/createFile.php
 
+/**
+ * @OA\Post(
+ *   path="/api/file/createFile.php",
+ *   summary="Create an empty file",
+ *   description="Requires write access on the target folder. Enforces folder-only scope.",
+ *   operationId="createFile",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folder","name"},
+ *       @OA\Property(property="folder", type="string", example="root"),
+ *       @OA\Property(property="name", type="string", example="new.txt")
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Creation result (model-defined)"),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/createShareLink.php

@@ -1,6 +1,42 @@
 <?php
 // public/api/file/createShareLink.php
 
+/**
+ * @OA\Post(
+ *   path="/api/file/createShareLink.php",
+ *   summary="Create a share link for a file",
+ *   description="Requires share permission on the folder. Non-admins must own the file unless bypassOwnership.",
+ *   operationId="createShareLink",
+ *   tags={"Shares"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folder","file"},
+ *       @OA\Property(property="folder", type="string", example="root"),
+ *       @OA\Property(property="file", type="string", example="invoice.pdf"),
+ *       @OA\Property(property="expirationValue", type="integer", example=60),
+ *       @OA\Property(property="expirationUnit", type="string", enum={"seconds","minutes","hours","days"}, example="minutes"),
+ *       @OA\Property(property="password", type="string", example="")
+ *     )
+ *   ),
+ *   @OA\Response(
+ *     response=200,
+ *     description="Share link created",
+ *     @OA\JsonContent(
+ *       type="object",
+ *       @OA\Property(property="token", type="string", example="abc123"),
+ *       @OA\Property(property="url", type="string", example="/api/file/share.php?token=abc123"),
+ *       @OA\Property(property="expires", type="integer", example=1700000000)
+ *     )
+ *   ),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/deleteFiles.php

@@ -1,6 +1,34 @@
 <?php
 // public/api/file/deleteFiles.php
 
+/**
+ * @OA\Post(
+ *   path="/api/file/deleteFiles.php",
+ *   summary="Delete files to Trash",
+ *   description="Requires write access on the folder and (for non-admins) ownership of the files.",
+ *   operationId="deleteFiles",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(
+ *     name="X-CSRF-Token", in="header", required=true,
+ *     @OA\Schema(type="string")
+ *   ),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folder","files"},
+ *       @OA\Property(property="folder", type="string", example="root"),
+ *       @OA\Property(property="files", type="array", @OA\Items(type="string"), example={"old.docx","draft.md"})
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Delete result (model-defined)"),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/deleteShareLink.php

@@ -1,4 +1,25 @@
 <?php
+
+
+/**
+ * @OA\Post(
+ *   path="/api/file/deleteShareLink.php",
+ *   summary="Delete a share link by token",
+ *   description="Deletes a share token. NOTE: Current implementation does not require authentication.",
+ *   operationId="deleteShareLink",
+ *   tags={"Shares"},
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"token"},
+ *       @OA\Property(property="token", type="string", example="abc123")
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Deletion result (success or not found)")
+ * )
+ */
+
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/deleteTrashFiles.php

@@ -1,6 +1,36 @@
 <?php
 // public/api/file/deleteTrashFiles.php
 
+/**
+ * @OA\Post(
+ *   path="/api/file/deleteTrashFiles.php",
+ *   summary="Permanently delete Trash items (admin only)",
+ *   operationId="deleteTrashFiles",
+ *   tags={"Trash"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       oneOf={
+ *         @OA\Schema(
+ *           required={"deleteAll"},
+ *           @OA\Property(property="deleteAll", type="boolean", example=true)
+ *         ),
+ *         @OA\Schema(
+ *           required={"files"},
+ *           @OA\Property(property="files", type="array", @OA\Items(type="string"), example={"trash/abc","trash/def"})
+ *         )
+ *       }
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Deletion result (model-defined)"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Admin only"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/download.php

@@ -1,6 +1,34 @@
 <?php
 // public/api/file/download.php
 
+
+/**
+ * @OA\Get(
+ *   path="/api/file/download.php",
+ *   summary="Download a file",
+ *   description="Requires view access (or own-only with ownership). Streams the file with appropriate Content-Type.",
+ *   operationId="downloadFile",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="folder", in="query", required=true, @OA\Schema(type="string"), example="root"),
+ *   @OA\Parameter(name="file", in="query", required=true, @OA\Schema(type="string"), example="photo.jpg"),
+ *   @OA\Response(
+ *     response=200,
+ *     description="Binary file",
+ *     content={
+ *       "application/octet-stream": @OA\MediaType(
+ *         mediaType="application/octet-stream",
+ *         @OA\Schema(type="string", format="binary")
+ *       )
+ *     }
+ *   ),
+ *   @OA\Response(response=400, description="Invalid folder/file"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=404, description="Not found")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/downloadZip.php

@@ -1,6 +1,41 @@
 <?php
 // public/api/file/downloadZip.php
 
+
+/**
+ * @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.",
+ *   operationId="downloadZip",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @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\Response(
+ *     response=200,
+ *     description="ZIP archive",
+ *     content={
+ *       "application/zip": @OA\MediaType(
+ *         mediaType="application/zip",
+ *         @OA\Schema(type="string", format="binary")
+ *       )
+ *     }
+ *   ),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/extractZip.php

@@ -1,6 +1,31 @@
 <?php
 // public/api/file/extractZip.php
 
+/**
+ * @OA\Post(
+ *   path="/api/file/extractZip.php",
+ *   summary="Extract ZIP file(s) into a folder",
+ *   description="Requires write access on the target folder.",
+ *   operationId="extractZip",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @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\Response(response=200, description="Extraction result (model-defined)"),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/getFileList.php

@@ -1,6 +1,23 @@
 <?php
 // public/api/file/getFileList.php
 
+/**
+ * @OA\Get(
+ *   path="/api/file/getFileList.php",
+ *   summary="List files in a folder",
+ *   description="Requires view access (full) or read_own (own-only results).",
+ *   operationId="getFileList",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="folder", in="query", required=true, @OA\Schema(type="string"), example="root"),
+ *   @OA\Response(response=200, description="Listing result (model-defined JSON)"),
+ *   @OA\Response(response=400, description="Invalid folder"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/getFileTag.php

@@ -1,6 +1,17 @@
 <?php
 // public/api/file/getFileTag.php
 
+/**
+ * @OA\Get(
+ *   path="/api/file/getFileTags.php",
+ *   summary="Get global file tags",
+ *   description="Returns tag metadata (no auth in current implementation).",
+ *   operationId="getFileTags",
+ *   tags={"Tags"},
+ *   @OA\Response(response=200, description="Tags map (model-defined JSON)")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/getShareLinks.php

@@ -1,4 +1,17 @@
 <?php
+
+/**
+ * @OA\Get(
+ *   path="/api/file/getShareLinks.php",
+ *   summary="Get (raw) share links file",
+ *   description="Returns the full share links JSON (no auth in current implementation).",
+ *   operationId="getShareLinks",
+ *   tags={"Shares"},
+ *   @OA\Response(response=200, description="Share links (model-defined JSON)")
+ * )
+ */
+
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/getTrashItems.php

@@ -1,6 +1,20 @@
 <?php
 // public/api/file/getTrashItems.php
 
+/**
+ * @OA\Get(
+ *   path="/api/file/getTrashItems.php",
+ *   summary="List items in Trash (admin only)",
+ *   operationId="getTrashItems",
+ *   tags={"Trash"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Response(response=200, description="Trash contents (model-defined JSON)"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Admin only"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/moveFiles.php

@@ -1,6 +1,20 @@
 <?php
 // public/api/file/moveFiles.php
 
+/**
+ * @OA\Post(
+ *   path="/api/file/moveFiles.php",
+ *   operationId="moveFiles",
+ *   tags={"Files"},
+ *   security={{"cookieAuth":{}}},
+ *   @OA\RequestBody(ref="#/components/requestBodies/MoveFilesRequest"),
+ *   @OA\Response(response=200, description="Moved"),
+ *   @OA\Response(response=400, description="Bad Request"),
+ *   @OA\Response(response=401, ref="#/components/responses/Unauthorized"),
+ *   @OA\Response(response=403, ref="#/components/responses/Forbidden")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/renameFile.php

@@ -1,6 +1,32 @@
 <?php
 // public/api/file/renameFile.php
 
+/**
+ * @OA\Put(
+ *   path="/api/file/renameFile.php",
+ *   summary="Rename a file",
+ *   description="Requires write access; non-admins must own the file.",
+ *   operationId="renameFile",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folder","oldName","newName"},
+ *       @OA\Property(property="folder", type="string", example="root"),
+ *       @OA\Property(property="oldName", type="string", example="old.pdf"),
+ *       @OA\Property(property="newName", type="string", example="new.pdf")
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Rename result (model-defined)"),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/restoreFiles.php

@@ -1,6 +1,28 @@
 <?php
 // public/api/file/restoreFiles.php
 
+/**
+ * @OA\Post(
+ *   path="/api/file/restoreFiles.php",
+ *   summary="Restore files from Trash (admin only)",
+ *   operationId="restoreFiles",
+ *   tags={"Trash"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"files"},
+ *       @OA\Property(property="files", type="array", @OA\Items(type="string"), example={"trash/12345.json"})
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Restore result (model-defined)"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Admin only"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/saveFile.php

@@ -1,6 +1,32 @@
 <?php
 // public/api/file/saveFile.php
 
+/**
+ * @OA\Put(
+ *   path="/api/file/saveFile.php",
+ *   summary="Create or overwrite a file’s content",
+ *   description="Requires write access. Overwrite enforces ownership for non-admins. Certain executable extensions are denied.",
+ *   operationId="saveFile",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folder","fileName","content"},
+ *       @OA\Property(property="folder", type="string", example="root"),
+ *       @OA\Property(property="fileName", type="string", example="readme.txt"),
+ *       @OA\Property(property="content", type="string", example="Hello world")
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Save result (model-defined)"),
+ *   @OA\Response(response=400, description="Invalid input or disallowed extension"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/saveFileTag.php

@@ -1,6 +1,34 @@
 <?php
 // public/api/file/saveFileTag.php
 
+/**
+ * @OA\Post(
+ *   path="/api/file/saveFileTag.php",
+ *   summary="Save tags for a file (or delete one)",
+ *   description="Requires write access and (for non-admins) ownership when modifying.",
+ *   operationId="saveFileTag",
+ *   tags={"Tags"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folder","file"},
+ *       @OA\Property(property="folder", type="string", example="root"),
+ *       @OA\Property(property="file", type="string", example="doc.md"),
+ *       @OA\Property(property="tags", type="array", @OA\Items(type="string"), example={"work","urgent"}),
+ *       @OA\Property(property="deleteGlobal", type="boolean", example=false),
+ *       @OA\Property(property="tagToDelete", type="string", nullable=true, example=null)
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Save result (model-defined)"),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=500, description="Internal error")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/file/share.php

@@ -1,6 +1,32 @@
 <?php
 // public/api/file/share.php
 
+/**
+ * @OA\Get(
+ *   path="/api/file/share.php",
+ *   summary="Open a shared file by token",
+ *   description="If the link is password-protected and no password is supplied, an HTML password form is returned. Otherwise the file is streamed.",
+ *   operationId="shareFile",
+ *   tags={"Shares"},
+ *   @OA\Parameter(name="token", in="query", required=true, @OA\Schema(type="string")),
+ *   @OA\Parameter(name="pass", in="query", required=false, @OA\Schema(type="string")),
+ *   @OA\Response(
+ *     response=200,
+ *     description="Binary file (or HTML password form when missing password)",
+ *     content={
+ *       "application/octet-stream": @OA\MediaType(
+ *         mediaType="application/octet-stream",
+ *         @OA\Schema(type="string", format="binary")
+ *       ),
+ *       "text/html": @OA\MediaType(mediaType="text/html")
+ *     }
+ *   ),
+ *   @OA\Response(response=400, description="Missing token / invalid input"),
+ *   @OA\Response(response=403, description="Expired or invalid password"),
+ *   @OA\Response(response=404, description="Not found")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FileController.php';
 

public/api/folder/capabilities.php

@@ -0,0 +1,245 @@
+<?php
+// public/api/folder/capabilities.php
+
+/**
+ * @OA\Get(
+ *   path="/api/folder/capabilities.php",
+ *   summary="Get effective capabilities for the current user in a folder",
+ *   description="Computes the caller's capabilities for a given folder by combining account flags (readOnly/disableUpload), ACL grants (read/write/share), and the user-folder-only scope. Returns booleans indicating what the user can do.",
+ *   operationId="getFolderCapabilities",
+ *   tags={"Folders"},
+ *   security={{"cookieAuth": {}}},
+ *
+ *   @OA\Parameter(
+ *     name="folder",
+ *     in="query",
+ *     required=false,
+ *     description="Target folder path. Defaults to 'root'. Supports nested paths like 'team/reports'.",
+ *     @OA\Schema(type="string"),
+ *     example="projects/acme"
+ *   ),
+ *
+ *   @OA\Response(
+ *     response=200,
+ *     description="Capabilities computed successfully.",
+ *     @OA\JsonContent(
+ *       type="object",
+ *       required={"user","folder","isAdmin","flags","canView","canUpload","canCreate","canRename","canDelete","canMoveIn","canShare"},
+ *       @OA\Property(property="user", type="string", example="alice"),
+ *       @OA\Property(property="folder", type="string", example="projects/acme"),
+ *       @OA\Property(property="isAdmin", type="boolean", example=false),
+ *       @OA\Property(
+ *         property="flags",
+ *         type="object",
+ *         required={"folderOnly","readOnly","disableUpload"},
+ *         @OA\Property(property="folderOnly", type="boolean", example=false),
+ *         @OA\Property(property="readOnly", type="boolean", example=false),
+ *         @OA\Property(property="disableUpload", type="boolean", example=false)
+ *       ),
+ *       @OA\Property(property="owner", type="string", nullable=true, example="alice"),
+ *       @OA\Property(property="canView",   type="boolean", example=true,  description="User can view items in this folder."),
+ *       @OA\Property(property="canUpload", type="boolean", example=true,  description="User can upload/edit/rename/move/delete items (i.e., WRITE)."),
+ *       @OA\Property(property="canCreate", type="boolean", example=true,  description="User can create subfolders here."),
+ *       @OA\Property(property="canRename", type="boolean", example=true,  description="User can rename items here."),
+ *       @OA\Property(property="canDelete", type="boolean", example=true,  description="User can delete items here."),
+ *       @OA\Property(property="canMoveIn", type="boolean", example=true,  description="User can move items into this folder."),
+ *       @OA\Property(property="canShare",  type="boolean", example=false, description="User can create share links for this folder.")
+ *     )
+ *   ),
+ *   @OA\Response(response=400, description="Invalid folder name."),
+ *   @OA\Response(response=401, ref="#/components/responses/Unauthorized")
+ * )
+ */
+
+declare(strict_types=1);
+if (session_status() !== PHP_SESSION_ACTIVE) session_start();
+
+require_once __DIR__ . '/../../../config/config.php';
+require_once PROJECT_ROOT . '/src/lib/ACL.php';
+require_once PROJECT_ROOT . '/src/models/UserModel.php';
+require_once PROJECT_ROOT . '/src/models/FolderModel.php';
+
+header('Content-Type: application/json');
+
+// --- auth ---
+$username = $_SESSION['username'] ?? '';
+if ($username === '') {
+  http_response_code(401);
+  echo json_encode(['error' => 'Unauthorized']);
+  exit;
+}
+
+// --- helpers ---
+function loadPermsFor(string $u): array {
+  try {
+    if (function_exists('loadUserPermissions')) {
+      $p = loadUserPermissions($u);
+      return is_array($p) ? $p : [];
+    }
+    if (class_exists('userModel') && method_exists('userModel', 'getUserPermissions')) {
+      $all = userModel::getUserPermissions();
+      if (is_array($all)) {
+        if (isset($all[$u])) return (array)$all[$u];
+        $lk = strtolower($u);
+        if (isset($all[$lk])) return (array)$all[$lk];
+      }
+    }
+  } catch (Throwable $e) {}
+  return [];
+}
+
+function isOwnerOrAncestorOwner(string $user, array $perms, string $folder): bool {
+  $f = ACL::normalizeFolder($folder);
+  // direct owner
+  if (ACL::isOwner($user, $perms, $f)) return true;
+  // ancestor owner
+  while ($f !== '' && strcasecmp($f, 'root') !== 0) {
+    $pos = strrpos($f, '/');
+    if ($pos === false) break;
+    $f = substr($f, 0, $pos);
+    if ($f === '' || strcasecmp($f, 'root') === 0) break;
+    if (ACL::isOwner($user, $perms, $f)) return true;
+  }
+  return false;
+}
+
+/**
+ * folder-only scope:
+ * - Admins: always in scope
+ * - Non folder-only accounts: always in scope
+ * - Folder-only accounts: in scope iff:
+ *   - folder == username OR subpath of username, OR
+ *   - user is owner of this folder (or any ancestor)
+ */
+function inUserFolderScope(string $folder, string $u, array $perms, bool $isAdmin): bool {
+  if ($isAdmin) return true;
+  //$folderOnly = !empty($perms['folderOnly']) || !empty($perms['userFolderOnly']) || !empty($perms['UserFolderOnly']);
+  //if (!$folderOnly) return true;
+
+  $f = ACL::normalizeFolder($folder);
+  if ($f === 'root' || $f === '') {
+    // folder-only users cannot act on root unless they own a subfolder (handled below)
+    return isOwnerOrAncestorOwner($u, $perms, $f);
+  }
+
+  if ($f === $u || str_starts_with($f, $u . '/')) return true;
+
+  // Treat ownership as in-scope
+  return isOwnerOrAncestorOwner($u, $perms, $f);
+}
+
+// --- inputs ---
+$folder = isset($_GET['folder']) ? trim((string)$_GET['folder']) : 'root';
+
+// validate folder path
+if ($folder !== 'root') {
+  $parts = array_filter(explode('/', trim($folder, "/\\ ")));
+  if (empty($parts)) {
+    http_response_code(400);
+    echo json_encode(['error' => 'Invalid folder name.']);
+    exit;
+  }
+  foreach ($parts as $seg) {
+    if (!preg_match(REGEX_FOLDER_NAME, $seg)) {
+      http_response_code(400);
+      echo json_encode(['error' => 'Invalid folder name.']);
+      exit;
+    }
+  }
+  $folder = implode('/', $parts);
+}
+
+// --- user + flags ---
+$perms       = loadPermsFor($username);
+$isAdmin     = ACL::isAdmin($perms);
+$readOnly    = !empty($perms['readOnly']);
+$inScope     = inUserFolderScope($folder, $username, $perms, $isAdmin);
+
+// --- ACL base abilities ---
+$canViewBase   = $isAdmin || ACL::canRead($username, $perms, $folder);
+$canViewOwn    = $isAdmin || ACL::canReadOwn($username, $perms, $folder);
+$canWriteBase  = $isAdmin || ACL::canWrite($username, $perms, $folder);
+$canShareBase  = $isAdmin || ACL::canShare($username, $perms, $folder);
+
+$canManageBase = $isAdmin || ACL::canManage($username, $perms, $folder);
+
+// granular base
+$gCreateBase   = $isAdmin || ACL::canCreate($username, $perms, $folder);
+$gRenameBase   = $isAdmin || ACL::canRename($username, $perms, $folder);
+$gDeleteBase   = $isAdmin || ACL::canDelete($username, $perms, $folder);
+$gMoveBase     = $isAdmin || ACL::canMove($username, $perms, $folder);
+$gUploadBase   = $isAdmin || ACL::canUpload($username, $perms, $folder);
+$gEditBase     = $isAdmin || ACL::canEdit($username, $perms, $folder);
+$gCopyBase     = $isAdmin || ACL::canCopy($username, $perms, $folder);
+$gExtractBase  = $isAdmin || ACL::canExtract($username, $perms, $folder);
+$gShareFile    = $isAdmin || ACL::canShareFile($username, $perms, $folder);
+$gShareFolder  = $isAdmin || ACL::canShareFolder($username, $perms, $folder);
+
+// --- Apply scope + flags to effective UI actions ---
+$canView     = $canViewBase && $inScope;              // keep scope for folder-only
+$canUpload   = $gUploadBase   && !$readOnly && $inScope;
+$canCreate   = $canManageBase && !$readOnly && $inScope;  // Create **folder**
+$canRename   = $canManageBase && !$readOnly && $inScope;  // Rename **folder**
+$canDelete   = $gDeleteBase   && !$readOnly && $inScope;
+// Destination can receive items if user can create/write (or manage) here
+$canReceive  = ($gUploadBase || $gCreateBase || $canManageBase) && !$readOnly && $inScope;
+// Back-compat: expose as canMoveIn (used by toolbar/context-menu/drag&drop)
+$canMoveIn   = $canReceive;
+$canMoveAlias = $canMoveIn;
+$canEdit     = $gEditBase     && !$readOnly && $inScope;
+$canCopy     = $gCopyBase     && !$readOnly && $inScope;
+$canExtract  = $gExtractBase  && !$readOnly && $inScope;
+
+// Sharing respects scope; optionally also gate on readOnly
+$canShare         = $canShareBase && $inScope;         // legacy umbrella
+$canShareFileEff  = $gShareFile   && $inScope;
+$canShareFoldEff  = $gShareFolder && $inScope;
+
+// never allow destructive ops on root
+$isRoot = ($folder === 'root');
+if ($isRoot) {
+  $canRename = false;
+  $canDelete = false;
+  $canShareFoldEff = false;
+  $canMoveFolder = false;
+}
+
+if (!$isRoot) {
+  $canMoveFolder = (ACL::canManage($username, $perms, $folder) || ACL::isOwner($username, $perms, $folder))
+                   && !$readOnly;
+}
+
+$owner = null;
+try { $owner = FolderModel::getOwnerFor($folder); } catch (Throwable $e) {}
+
+echo json_encode([
+  'user'    => $username,
+  'folder'  => $folder,
+  'isAdmin' => $isAdmin,
+  'flags'   => [
+    //'folderOnly'    => !empty($perms['folderOnly']) || !empty($perms['userFolderOnly']) || !empty($perms['UserFolderOnly']),
+    'readOnly'      => $readOnly,
+  ],
+  'owner'        => $owner,
+
+  // viewing
+  'canView'      => $canView,
+  'canViewOwn'   => $canViewOwn,
+
+  // write-ish
+  'canUpload'    => $canUpload,
+  'canCreate'    => $canCreate,
+  'canRename'    => $canRename,
+  'canDelete'    => $canDelete,
+  'canMoveIn'    => $canMoveIn,
+  'canMove'       => $canMoveAlias, 
+  'canMoveFolder'=> $canMoveFolder,
+  'canEdit'      => $canEdit,
+  'canCopy'      => $canCopy,
+  'canExtract'   => $canExtract,
+
+  // sharing
+  'canShare'        => $canShare,          // legacy
+  'canShareFile'    => $canShareFileEff,
+  'canShareFolder'  => $canShareFoldEff,
+], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

public/api/folder/createFolder.php

@@ -1,6 +1,36 @@
 <?php
 // public/api/folder/createFolder.php
 
+/**
+ * @OA\Post(
+ *   path="/api/folder/createFolder.php",
+ *   summary="Create a new folder",
+ *   description="Requires authentication, CSRF token, and write access to the parent folder. Seeds ACL owner.",
+ *   operationId="createFolder",
+ *   tags={"Folders"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(
+ *     name="X-CSRF-Token", in="header", required=true,
+ *     description="CSRF token from the current session",
+ *     @OA\Schema(type="string")
+ *   ),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folderName"},
+ *       @OA\Property(property="folderName", type="string", example="reports"),
+ *       @OA\Property(property="parent", type="string", nullable=true, example="root",
+ *         description="Parent folder (default root)")
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Creation result (model-defined JSON)"),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=405, description="Method not allowed")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/folder/createShareFolderLink.php

@@ -1,6 +1,42 @@
 <?php
 // public/api/folder/createShareFolderLink.php
 
+/**
+ * @OA\Post(
+ *   path="/api/folder/createShareFolderLink.php",
+ *   summary="Create a share link for a folder",
+ *   description="Requires authentication, CSRF token, and share permission. Non-admins must own the folder (unless bypass) and cannot share root.",
+ *   operationId="createShareFolderLink",
+ *   tags={"Shared Folders"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folder"},
+ *       @OA\Property(property="folder", type="string", example="team/reports"),
+ *       @OA\Property(property="expirationValue", type="integer", example=60),
+ *       @OA\Property(property="expirationUnit", type="string", enum={"seconds","minutes","hours","days"}, example="minutes"),
+ *       @OA\Property(property="password", type="string", example=""),
+ *       @OA\Property(property="allowUpload", type="integer", enum={0,1}, example=0)
+ *     )
+ *   ),
+ *   @OA\Response(
+ *     response=200,
+ *     description="Share folder link created",
+ *     @OA\JsonContent(
+ *       type="object",
+ *       @OA\Property(property="token", type="string", example="sf_abc123"),
+ *       @OA\Property(property="url", type="string", example="/api/folder/shareFolder.php?token=sf_abc123"),
+ *       @OA\Property(property="expires", type="integer", example=1700000000)
+ *     )
+ *   ),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/folder/deleteFolder.php

@@ -1,6 +1,30 @@
 <?php
 // public/api/folder/deleteFolder.php
 
+/**
+ * @OA\Post(
+ *   path="/api/folder/deleteFolder.php",
+ *   summary="Delete a folder",
+ *   description="Requires authentication, CSRF token, write scope, and (for non-admins) folder ownership.",
+ *   operationId="deleteFolder",
+ *   tags={"Folders"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folder"},
+ *       @OA\Property(property="folder", type="string", example="userA/reports")
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Deletion result (model-defined JSON)"),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=405, description="Method not allowed")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/folder/deleteShareFolderLink.php

@@ -1,4 +1,28 @@
 <?php
+
+/**
+ * @OA\Post(
+ *   path="/api/folder/deleteShareFolderLink.php",
+ *   summary="Delete a shared-folder link by token (admin only)",
+ *   description="Requires authentication, CSRF token, and admin privileges.",
+ *   operationId="deleteShareFolderLink",
+ *   tags={"Shared Folders","Admin"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"token"},
+ *       @OA\Property(property="token", type="string", example="sf_abc123")
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Deleted"),
+ *   @OA\Response(response=400, description="No token provided"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Admin only"),
+ *   @OA\Response(response=404, description="Not found")
+ * )
+ */
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/folder/downloadSharedFile.php

@@ -1,6 +1,30 @@
 <?php
 // public/api/folder/downloadSharedFile.php
 
+/**
+ * @OA\Get(
+ *   path="/api/folder/downloadSharedFile.php",
+ *   summary="Download a file from a shared folder (by token)",
+ *   description="Public endpoint; validates token and file name, then streams the file.",
+ *   operationId="downloadSharedFile",
+ *   tags={"Shared Folders"},
+ *   @OA\Parameter(name="token", in="query", required=true, @OA\Schema(type="string")),
+ *   @OA\Parameter(name="file", in="query", required=true, @OA\Schema(type="string"), example="report.pdf"),
+ *   @OA\Response(
+ *     response=200,
+ *     description="Binary file",
+ *     content={
+ *       "application/octet-stream": @OA\MediaType(
+ *         mediaType="application/octet-stream",
+ *         @OA\Schema(type="string", format="binary")
+ *       )
+ *     }
+ *   ),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=404, description="Not found")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/folder/getFolderList.php

@@ -1,6 +1,38 @@
 <?php
 // public/api/folder/getFolderList.php
 
+
+/**
+ * @OA\Get(
+ *   path="/api/folder/getFolderList.php",
+ *   summary="List folders (optionally under a parent)",
+ *   description="Requires authentication. Non-admins see folders for which they have full view or own-only access.",
+ *   operationId="getFolderList",
+ *   tags={"Folders"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(
+ *     name="folder", in="query", required=false,
+ *     description="Parent folder to include and descend (default all); use 'root' for top-level",
+ *     @OA\Schema(type="string"), example="root"
+ *   ),
+ *   @OA\Response(
+ *     response=200,
+ *     description="List of folders",
+ *     @OA\JsonContent(
+ *       type="array",
+ *       @OA\Items(
+ *         type="object",
+ *         @OA\Property(property="folder", type="string", example="team/reports"),
+ *         @OA\Property(property="fileCount", type="integer", example=12),
+ *         @OA\Property(property="metadataFile", type="string", example="/path/to/meta.json")
+ *       )
+ *     )
+ *   ),
+ *   @OA\Response(response=400, description="Invalid folder"),
+ *   @OA\Response(response=401, description="Unauthorized")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/folder/getShareFolderLinks.php

@@ -1,4 +1,19 @@
 <?php
+
+/**
+ * @OA\Get(
+ *   path="/api/folder/getShareFolderLinks.php",
+ *   summary="List active shared-folder links (admin only)",
+ *   description="Returns all non-expired shared-folder links. Admin-only.",
+ *   operationId="getShareFolderLinks",
+ *   tags={"Shared Folders","Admin"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Response(response=200, description="Active share-folder links (model-defined JSON)"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Admin only")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/folder/moveFolder.php

@@ -0,0 +1,9 @@
+<?php
+// public/api/folder/moveFolder.php
+declare(strict_types=1);
+
+require_once __DIR__ . '/../../../config/config.php';
+require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
+
+$controller = new FolderController();
+$controller->moveFolder();

public/api/folder/renameFolder.php

@@ -1,6 +1,31 @@
 <?php
 // public/api/folder/renameFolder.php
 
+/**
+ * @OA\Post(
+ *   path="/api/folder/renameFolder.php",
+ *   summary="Rename or move a folder",
+ *   description="Requires authentication, CSRF token, scope checks on old and new paths, and (for non-admins) ownership of the source folder.",
+ *   operationId="renameFolder",
+ *   tags={"Folders"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"oldFolder","newFolder"},
+ *       @OA\Property(property="oldFolder", type="string", example="team/q1"),
+ *       @OA\Property(property="newFolder", type="string", example="team/quarter-1")
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Rename result (model-defined JSON)"),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=405, description="Method not allowed")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/folder/shareFolder.php

@@ -1,6 +1,26 @@
 <?php
 // public/api/folder/shareFolder.php
 
+/**
+ * @OA\Get(
+ *   path="/api/folder/shareFolder.php",
+ *   summary="Open a shared folder by token (HTML UI)",
+ *   description="If the share is password-protected and no password is supplied, an HTML password form is returned. Otherwise renders an HTML listing with optional upload form.",
+ *   operationId="shareFolder",
+ *   tags={"Shared Folders"},
+ *   @OA\Parameter(name="token", in="query", required=true, @OA\Schema(type="string")),
+ *   @OA\Parameter(name="pass", in="query", required=false, @OA\Schema(type="string")),
+ *   @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", minimum=1), example=1),
+ *   @OA\Response(
+ *     response=200,
+ *     description="HTML page (password form or folder listing)",
+ *     content={"text/html": @OA\MediaType(mediaType="text/html")}
+ *   ),
+ *   @OA\Response(response=400, description="Missing/invalid token"),
+ *   @OA\Response(response=403, description="Forbidden or wrong password")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/folder/uploadToSharedFolder.php

@@ -1,6 +1,33 @@
 <?php
 // public/api/folder/uploadToSharedFolder.php
 
+/**
+ * @OA\Post(
+ *   path="/api/folder/uploadToSharedFolder.php",
+ *   summary="Upload a file into a shared folder (by token)",
+ *   description="Public form-upload endpoint. Only allowed when the share link has uploads enabled. On success responds with a redirect to the share page.",
+ *   operationId="uploadToSharedFolder",
+ *   tags={"Shared Folders"},
+ *   @OA\RequestBody(
+ *     required=true,
+ *     content={
+ *       "multipart/form-data": @OA\MediaType(
+ *         mediaType="multipart/form-data",
+ *         @OA\Schema(
+ *           type="object",
+ *           required={"token","fileToUpload"},
+ *           @OA\Property(property="token", type="string", description="Share token"),
+ *           @OA\Property(property="fileToUpload", type="string", format="binary", description="File to upload")
+ *         )
+ *       )
+ *     }
+ *   ),
+ *   @OA\Response(response=302, description="Redirect to /api/folder/shareFolder.php?token=..."),
+ *   @OA\Response(response=400, description="Upload error or invalid input"),
+ *   @OA\Response(response=405, description="Method not allowed")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/FolderController.php';
 

public/api/getUserPermissions.php

@@ -1,6 +1,25 @@
 <?php
 // public/api/getUserPermissions.php
 
+    /**
+     * @OA\Get(
+     *     path="/api/getUserPermissions.php",
+     *     summary="Retrieve user permissions",
+     *     description="Returns the permissions for the current user, or all permissions if the user is an admin.",
+     *     operationId="getUserPermissions",
+     *     tags={"Users"},
+     *     @OA\Response(
+     *         response=200,
+     *         description="Successful response with user permissions",
+     *         @OA\JsonContent(type="object")
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 

public/api/getUsers.php

@@ -1,6 +1,32 @@
 <?php
 // public/api/getUsers.php
 
+    /**
+     * @OA\Get(
+     *     path="/api/getUsers.php",
+     *     summary="Retrieve a list of users",
+     *     description="Returns a JSON array of users. Only available to authenticated admin users.",
+     *     operationId="getUsers",
+     *     tags={"Users"},
+     *     @OA\Response(
+     *         response=200,
+     *         description="Successful response with an array of users",
+     *         @OA\JsonContent(
+     *             type="array",
+     *             @OA\Items(
+     *                 type="object",
+     *                 @OA\Property(property="username", type="string", example="johndoe"),
+     *                 @OA\Property(property="role", type="string", example="admin")
+     *             )
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized: the user is not authenticated or is not an admin"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 

public/api/profile/getCurrentUser.php

@@ -1,4 +1,29 @@
 <?php
+
+
+/**
+ * @OA\Get(
+ *   path="/api/profile/getCurrentUser.php",
+ *   operationId="getCurrentUser",
+ *   tags={"Users"},
+ *   security={{"cookieAuth":{}}},
+ *   @OA\Response(
+ *     response=200,
+ *     description="Current user",
+ *     @OA\JsonContent(
+ *       type="object",
+ *       required={"username","isAdmin","totp_enabled","profile_picture"},
+ *       @OA\Property(property="username", type="string", example="ryan"),
+ *       @OA\Property(property="isAdmin", type="boolean"),
+ *       @OA\Property(property="totp_enabled", type="boolean"),
+ *       @OA\Property(property="profile_picture", type="string", example="/uploads/profile_pics/ryan.png")
+ *       // If you had an array: @OA\Property(property="roles", type="array", @OA\Items(type="string"))
+ *     )
+ *   ),
+ *   @OA\Response(response=401, ref="#/components/responses/Unauthorized")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/models/UserModel.php';
 

public/api/profile/uploadPicture.php

@@ -2,6 +2,57 @@
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 
+
+/**
+ * @OA\Post(
+ *   path="/api/profile/uploadPicture.php",
+ *   summary="Upload or replace the current user's profile picture",
+ *   description="Accepts a single image file (JPEG, PNG, or GIF) up to 2 MB. Requires a valid session cookie and CSRF token.",
+ *   operationId="uploadProfilePicture",
+ *   tags={"Users"},
+ *   security={{"cookieAuth": {}}},
+ *
+ *   @OA\Parameter(
+ *     name="X-CSRF-Token",
+ *     in="header",
+ *     required=true,
+ *     description="Anti-CSRF token associated with the current session.",
+ *     @OA\Schema(type="string")
+ *   ),
+ *
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\MediaType(
+ *       mediaType="multipart/form-data",
+ *       @OA\Schema(
+ *         required={"profile_picture"},
+ *         @OA\Property(
+ *           property="profile_picture",
+ *           type="string",
+ *           format="binary",
+ *           description="JPEG, PNG, or GIF image. Max size: 2 MB."
+ *         )
+ *       )
+ *     )
+ *   ),
+ *
+ *   @OA\Response(
+ *     response=200,
+ *     description="Profile picture updated.",
+ *     @OA\JsonContent(
+ *       type="object",
+ *       required={"success","url"},
+ *       @OA\Property(property="success", type="boolean", example=true),
+ *       @OA\Property(property="url", type="string", example="/uploads/profile_pics/alice_9f3c2e1a8bcd.png")
+ *     )
+ *   ),
+ *   @OA\Response(response=400, description="No file uploaded, invalid file type, or file too large."),
+ *   @OA\Response(response=401, ref="#/components/responses/Unauthorized"),
+ *   @OA\Response(response=403, ref="#/components/responses/Forbidden"),
+ *   @OA\Response(response=500, description="Server error while saving the picture.")
+ * )
+ */
+
 // Always JSON, even on PHP notices
 header('Content-Type: application/json');
 

public/api/removeUser.php

@@ -1,6 +1,42 @@
 <?php
 // public/api/removeUser.php
 
+    /**
+     * @OA\Delete(
+     *     path="/api/removeUser.php",
+     *     summary="Remove a user",
+     *     description="Removes the specified user from the system. Cannot remove the currently logged-in user.",
+     *     operationId="removeUser",
+     *     tags={"Users"},
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"username"},
+     *             @OA\Property(property="username", type="string", example="johndoe")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="User removed successfully",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="success", type="string", example="User removed successfully")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=400,
+     *         description="Bad Request"
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized"
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Invalid CSRF token"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 

public/api/totp_disable.php

@@ -1,6 +1,32 @@
 <?php
 // public/api/totp_disable.php
 
+    /**
+     * @OA\Put(
+     *     path="/api/totp_disable.php",
+     *     summary="Disable TOTP for the authenticated user",
+     *     description="Clears the TOTP secret from the users file for the current user.",
+     *     operationId="disableTOTP",
+     *     tags={"TOTP"},
+     *     @OA\Response(
+     *         response=200,
+     *         description="TOTP disabled successfully",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="success", type="boolean", example=true),
+     *             @OA\Property(property="message", type="string", example="TOTP disabled successfully.")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Not authenticated or invalid CSRF token"
+     *     ),
+     *     @OA\Response(
+     *         response=500,
+     *         description="Failed to disable TOTP"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/vendor/autoload.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';

public/api/totp_recover.php

@@ -1,6 +1,46 @@
 <?php
 // public/api/totp_recover.php
 
+    /**
+     * @OA\Post(
+     *     path="/api/totp_recover.php",
+     *     summary="Recover TOTP",
+     *     description="Verifies a recovery code to disable TOTP and finalize login.",
+     *     operationId="recoverTOTP",
+     *     tags={"TOTP"},
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"recovery_code"},
+     *             @OA\Property(property="recovery_code", type="string", example="ABC123DEF456")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="Recovery successful",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="status", type="string", example="ok")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=400,
+     *         description="Invalid input or recovery code"
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Invalid CSRF token"
+     *     ),
+     *     @OA\Response(
+     *         response=405,
+     *         description="Method not allowed"
+     *     ),
+     *     @OA\Response(
+     *         response=429,
+     *         description="Too many attempts"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 

public/api/totp_saveCode.php

@@ -1,6 +1,36 @@
 <?php
 // public/api/totp_saveCode.php
 
+    /**
+     * @OA\Post(
+     *     path="/api/totp_saveCode.php",
+     *     summary="Generate and save a new TOTP recovery code",
+     *     description="Generates a new TOTP recovery code for the authenticated user, stores its hash, and returns the plain text recovery code.",
+     *     operationId="totpSaveCode",
+     *     tags={"TOTP"},
+     *     @OA\Response(
+     *         response=200,
+     *         description="Recovery code generated successfully",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="status", type="string", example="ok"),
+     *             @OA\Property(property="recoveryCode", type="string", example="ABC123DEF456")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=400,
+     *         description="Bad Request"
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Invalid CSRF token or unauthorized"
+     *     ),
+     *     @OA\Response(
+     *         response=405,
+     *         description="Method not allowed"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 

public/api/totp_setup.php

@@ -1,6 +1,31 @@
 <?php
 // public/api/totp_setup.php
 
+    /**
+     * @OA\Get(
+     *     path="/api/totp_setup.php",
+     *     summary="Set up TOTP and generate a QR code",
+     *     description="Generates (or retrieves) the TOTP secret for the user and builds a QR code image for scanning.",
+     *     operationId="setupTOTP",
+     *     tags={"TOTP"},
+     *     @OA\Response(
+     *         response=200,
+     *         description="QR code image for TOTP setup",
+     *         @OA\MediaType(
+     *             mediaType="image/png"
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Unauthorized or invalid CSRF token"
+     *     ),
+     *     @OA\Response(
+     *         response=500,
+     *         description="Server error"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/vendor/autoload.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';

public/api/totp_verify.php

@@ -1,6 +1,43 @@
 <?php
 // public/api/totp_verify.php
 
+    /**
+     * @OA\Post(
+     *     path="/api/totp_verify.php",
+     *     summary="Verify TOTP code",
+     *     description="Verifies a TOTP code and completes login for pending users or validates TOTP for setup verification.",
+     *     operationId="verifyTOTP",
+     *     tags={"TOTP"},
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"totp_code"},
+     *             @OA\Property(property="totp_code", type="string", example="123456")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="TOTP successfully verified",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="status", type="string", example="ok"),
+     *             @OA\Property(property="message", type="string", example="Login successful")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=400,
+     *         description="Bad Request (e.g., invalid input)"
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Not authenticated or invalid CSRF token"
+     *     ),
+     *     @OA\Response(
+     *         response=429,
+     *         description="Too many attempts. Try again later."
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/vendor/autoload.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';

public/api/updateUserPanel.php

@@ -1,6 +1,42 @@
 <?php
 // public/api/updateUserPanel.php
 
+    /**
+     * @OA\Put(
+     *     path="/api/updateUserPanel.php",
+     *     summary="Update user panel settings",
+     *     description="Updates user panel settings by disabling TOTP when not enabled. Accessible to authenticated users.",
+     *     operationId="updateUserPanel",
+     *     tags={"Users"},
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"totp_enabled"},
+     *             @OA\Property(property="totp_enabled", type="boolean", example=false)
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="User panel updated successfully",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="success", type="string", example="User panel updated: TOTP disabled")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized"
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Invalid CSRF token"
+     *     ),
+     *     @OA\Response(
+     *         response=400,
+     *         description="Bad Request"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 

public/api/updateUserPermissions.php

@@ -1,6 +1,52 @@
 <?php
 // public/api/updateUserPermissions.php
 
+   /**
+     * @OA\Put(
+     *     path="/api/updateUserPermissions.php",
+     *     summary="Update user permissions",
+     *     description="Updates permissions for users. Only available to authenticated admin users.",
+     *     operationId="updateUserPermissions",
+     *     tags={"Users"},
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"permissions"},
+     *             @OA\Property(
+     *                 property="permissions",
+     *                 type="array",
+     *                 @OA\Items(
+     *                     type="object",
+     *                     @OA\Property(property="username", type="string", example="johndoe"),
+     *                     @OA\Property(property="folderOnly", type="boolean", example=true),
+     *                     @OA\Property(property="readOnly", type="boolean", example=false),
+     *                     @OA\Property(property="disableUpload", type="boolean", example=false)
+     *                 )
+     *             )
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="User permissions updated successfully",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="success", type="string", example="User permissions updated successfully.")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthorized"
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Invalid CSRF token"
+     *     ),
+     *     @OA\Response(
+     *         response=400,
+     *         description="Bad Request"
+     *     )
+     * )
+     */
+
 require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UserController.php';
 

public/api/upload/removeChunks.php

@@ -1,6 +1,35 @@
 <?php
 // public/api/upload/removeChunks.php
 
+/**
+ * @OA\Post(
+ *   path="/api/upload/removeChunks.php",
+ *   summary="Remove temporary chunk directory",
+ *   description="Deletes the temporary directory used for a chunked upload. Requires a valid CSRF token in the form field.",
+ *   operationId="removeChunks",
+ *   tags={"Uploads"},
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"folder"},
+ *       @OA\Property(property="folder", type="string", example="resumable_myupload123"),
+ *       @OA\Property(property="csrf_token", type="string", description="CSRF token for this session")
+ *     )
+ *   ),
+ *   @OA\Response(
+ *     response=200,
+ *     description="Removal result",
+ *     @OA\JsonContent(
+ *       type="object",
+ *       @OA\Property(property="success", type="boolean", example=true),
+ *       @OA\Property(property="message", type="string", example="Temporary folder removed.")
+ *     )
+ *   ),
+ *   @OA\Response(response=400, description="Invalid input"),
+ *   @OA\Response(response=403, description="Invalid CSRF token")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UploadController.php';
 

public/api/upload/upload.php

@@ -1,5 +1,84 @@
 <?php
 // public/api/upload/upload.php
+
+/**
+ * @OA\Post(
+ *   path="/api/upload/upload.php",
+ *   summary="Upload a file (supports chunked + full uploads)",
+ *   description="Requires a session (cookie) and a CSRF token (header preferred; falls back to form field). Checks user/account flags and folder-level WRITE ACL, then delegates to the model. Returns JSON for chunked uploads; full uploads may redirect after success.",
+ *   operationId="handleUpload",
+ *   tags={"Uploads"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(
+ *     name="X-CSRF-Token", in="header", required=false,
+ *     description="CSRF token for this session (preferred). If omitted, send as form field `csrf_token`.",
+ *     @OA\Schema(type="string")
+ *   ),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     content={
+ *       "multipart/form-data": @OA\MediaType(
+ *         mediaType="multipart/form-data",
+ *         @OA\Schema(
+ *           type="object",
+ *           required={"fileToUpload"},
+ *           @OA\Property(
+ *             property="fileToUpload", type="string", format="binary",
+ *             description="File or chunk payload."
+ *           ),
+ *           @OA\Property(
+ *             property="folder", type="string", example="root",
+ *             description="Target folder (defaults to 'root' if omitted)."
+ *           ),
+ *           @OA\Property(property="csrf_token", type="string", description="CSRF token (form fallback)."),
+ *           @OA\Property(property="upload_token", type="string", description="Legacy alias for CSRF token (accepted by server)."),
+ *           @OA\Property(property="resumableChunkNumber", type="integer"),
+ *           @OA\Property(property="resumableTotalChunks", type="integer"),
+ *           @OA\Property(property="resumableChunkSize", type="integer"),
+ *           @OA\Property(property="resumableCurrentChunkSize", type="integer"),
+ *           @OA\Property(property="resumableTotalSize", type="integer"),
+ *           @OA\Property(property="resumableType", type="string"),
+ *           @OA\Property(property="resumableIdentifier", type="string"),
+ *           @OA\Property(property="resumableFilename", type="string"),
+ *           @OA\Property(property="resumableRelativePath", type="string")
+ *         )
+ *       )
+ *     }
+ *   ),
+ *   @OA\Response(
+ *     response=200,
+ *     description="JSON result (success, chunk status, or CSRF refresh).",
+ *     @OA\JsonContent(
+ *       oneOf={
+ *         @OA\Schema(                       ; Success (full or model-returned)
+ *           type="object",
+ *           @OA\Property(property="success", type="string", example="File uploaded successfully"),
+ *           @OA\Property(property="newFilename", type="string", example="5f2d7c123a_example.png")
+ *         ),
+ *         @OA\Schema(                       ; Chunk flow
+ *           type="object",
+ *           @OA\Property(property="status", type="string", example="chunk uploaded")
+ *         ),
+ *         @OA\Schema(                       ; CSRF soft-refresh path
+ *           type="object",
+ *           @OA\Property(property="csrf_expired", type="boolean", example=true),
+ *           @OA\Property(property="csrf_token", type="string", example="b1c2...f9")
+ *         )
+ *       }
+ *     )
+ *   ),
+ *   @OA\Response(
+ *     response=302,
+ *     description="Redirect after a successful full upload.",
+ *     @OA\Header(header="Location", description="Where the client is redirected", @OA\Schema(type="string"))
+ *   ),
+ *   @OA\Response(response=400, description="Bad request (missing/invalid fields, model error)"),
+ *   @OA\Response(response=401, description="Unauthorized (no session)"),
+ *   @OA\Response(response=403, description="Forbidden (upload disabled or no WRITE to folder)"),
+ *   @OA\Response(response=500, description="Server error while processing upload")
+ * )
+ */
+
 require_once __DIR__ . '/../../../config/config.php';
 require_once PROJECT_ROOT . '/src/controllers/UploadController.php';
 

public/css/styles.css

@@ -1046,11 +1046,6 @@ label {
   display: none;
 }
 
-#createFolderBtn {
-  margin-top: 0px !important;
-  height: 40px !important;
-  font-size: 1rem;
-}
 
 .folder-actions {
   display: flex;
@@ -1058,6 +1053,7 @@ label {
   padding-left: 8px;
   align-items: center;
   white-space: nowrap;
+  padding-top: 10px;
 }
 
 @media (min-width: 600px) and (max-width: 992px) {
@@ -1066,6 +1062,70 @@ label {
   }
 }
 
+.folder-actions .btn {
+  padding: 10px 12px;
+  font-size: 0.85rem;
+  line-height: 1.1;
+  border-radius: 6px;
+}
+
+.folder-actions .material-icons {
+  font-size: 24px;
+  vertical-align: -2px; 
+}
+
+.folder-actions .btn + .btn {
+  margin-left: 6px;
+}
+
+.folder-actions .btn {
+  padding: 10px 12px;
+  font-size: 0.85rem;
+  line-height: 1.1;
+  border-radius: 6px;
+
+  transform: scale(1);
+  transform-origin: center;
+  transition: transform 120ms ease, box-shadow 120ms ease;
+  will-change: transform;
+}
+
+
+.folder-actions .material-icons {
+  font-size: 24px;
+  vertical-align: -2px;
+  transition: transform 120ms ease;
+}
+
+.folder-actions .btn:hover,
+.folder-actions .btn:focus-visible {
+  transform: scale(1.06);
+  box-shadow: 0 2px 8px rgba(0,0,0,0.12);
+}
+
+.folder-actions .btn:hover .material-icons,
+.folder-actions .btn:focus-visible .material-icons {
+  transform: scale(1.05);
+}
+
+.folder-actions .btn:focus-visible {
+  outline: 2px solid rgba(33,150,243,0.6);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .folder-actions .btn,
+  .folder-actions .material-icons {
+    transition: none;
+  }
+}
+
+#moveFolderBtn {
+  background-color: #ff9800;
+  border-color: #ff9800;
+  color: #fff;
+}
+
 .row-selected {
   background-color: #f2f2f2 !important;
 }
@@ -2036,10 +2096,9 @@ body.dark-mode .admin-panel-content label {
 }
 
 #openChangePasswordModalBtn {
-  width: auto;
-  padding: 5px 10px;
+  width: max-content;
+  padding: 6px 12px;
   font-size: 14px;
-  margin-right: 300px;
 }
 
 #changePasswordModal {
@@ -2305,4 +2364,75 @@ body.dark-mode .user-dropdown .user-menu .item:hover {
 .folder-strip-container .folder-item:hover {
   background-color: rgba(255, 255, 255, 0.2);
   box-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);
+}
+
+:root { --perm-caret: #444; }          /* light */
+body.dark-mode { --perm-caret: #ccc; }  /* dark */
+
+#zonesToggleFloating,
+#sidebarToggleFloating {
+  transition:
+    transform 160ms cubic-bezier(.2,.0,.2,1),
+    box-shadow 160ms cubic-bezier(.2,.0,.2,1),
+    border-color 160ms cubic-bezier(.2,.0,.2,1),
+    background-color 160ms cubic-bezier(.2,.0,.2,1);
+}
+
+:root { --toggle-icon-color: #333; }
+body.dark-mode { --toggle-icon-color: #eee; }
+
+#zonesToggleFloating .material-icons,
+#zonesToggleFloating .material-icons-outlined,
+#sidebarToggleFloating .material-icons,
+#sidebarToggleFloating .material-icons-outlined {
+  color: var(--toggle-icon-color);
+  font-size: 22px;
+  line-height: 1;
+  display: block;
+}
+
+#zonesToggleFloating:hover,
+#sidebarToggleFloating:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 6px 16px rgba(0,0,0,.14);
+  border-color: #cfcfcf;
+}
+
+#zonesToggleFloating:active,
+#sidebarToggleFloating:active {
+  transform: translateY(0) scale(.96);
+  box-shadow: 0 3px 8px rgba(0,0,0,.12);
+}
+
+#zonesToggleFloating:focus-visible,
+#sidebarToggleFloating:focus-visible {
+  outline: none;
+  box-shadow:
+    0 6px 16px rgba(0,0,0,.14),
+    0 0 0 3px rgba(25,118,210,.25); /* soft brandy ring */
+}
+
+#zonesToggleFloating::after,
+#sidebarToggleFloating::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background: radial-gradient(circle, rgba(0,0,0,.12) 0%, rgba(0,0,0,0) 60%);
+  transform: scale(0);
+  opacity: 0;
+  transition: transform 300ms ease, opacity 450ms ease;
+  pointer-events: none;
+}
+
+#zonesToggleFloating:active::after,
+#sidebarToggleFloating:active::after {
+  transform: scale(1.4);
+  opacity: 1;
+}
+
+#zonesToggleFloating.is-collapsed,
+#sidebarToggleFloating.is-collapsed {
+  background: #fafafa;
+  border-color: #e2e2e2;
 }

public/index.html

@@ -4,7 +4,7 @@
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title data-i18n-key="title">FileRise</title>
+  <title>FileRise</title>
   <link rel="icon" type="image/png" href="/assets/logo.png">
   <link rel="icon" type="image/svg+xml" href="/assets/logo.svg">
   <meta name="csrf-token" content="">
@@ -286,9 +286,27 @@
                           </div>
                         </div>
                       </div>
+                      <button id="moveFolderBtn" class="btn btn-warning ml-2" data-i18n-title="move_folder">
+                        <i class="material-icons">drive_file_move</i>
+                      </button>
+                      <!-- MOVE FOLDER MODAL (place near your other folder modals) -->
+                      <div id="moveFolderModal" class="modal" style="display:none;">
+                        <div class="modal-content">
+                          <h4 data-i18n-key="move_folder_title">Move Folder</h4>
+                          <p data-i18n-key="move_folder_message">Select a destination folder to move the current folder
+                            into:</p>
+                          <select id="moveFolderTarget" class="form-control modal-input"></select>
+                          <div class="modal-footer" style="margin-top:15px; text-align:right;">
+                            <button id="cancelMoveFolder" class="btn btn-secondary"
+                              data-i18n-key="cancel">Cancel</button>
+                            <button id="confirmMoveFolder" class="btn btn-primary" data-i18n-key="move">Move</button>
+                          </div>
+                        </div>
+                      </div>
                       <button id="renameFolderBtn" class="btn btn-warning ml-2" data-i18n-title="rename_folder">
                         <i class="material-icons">drive_file_rename_outline</i>
                       </button>
+
                       <div id="renameFolderModal" class="modal">
                         <div class="modal-content">
                           <h4 data-i18n-key="rename_folder_title">Rename Folder</h4>
@@ -389,16 +407,14 @@
             </div>
             <button id="downloadZipBtn" class="btn action-btn" style="display: none;" disabled
               data-i18n-key="download_zip">Download ZIP</button>
-            <button id="extractZipBtn" class="btn action-btn btn-sm btn-info" data-i18n-title="extract_zip"
+            <button id="extractZipBtn" class="btn action-btn btn-sm btn-info"  style="display: none;" disabled
               data-i18n-key="extract_zip_button">Extract Zip</button>
-              <div id="createDropdown" class="dropdown-container" style="position:relative; display:inline-block;">
-                <button id="createBtn"  class="btn action-btn" data-i18n-key="create">
-                  ${t('create')} <span class="material-icons" style="font-size:16px;vertical-align:middle;">arrow_drop_down</span>
-                </button>
-                <ul
-                  id="createMenu"
-                  class="dropdown-menu"
-                  style="
+            <div id="createDropdown" class="dropdown-container" style="position:relative; display:inline-block;">
+              <button id="createBtn" class="btn action-btn" style="display: none;" data-i18n-key="create">
+                ${t('create')} <span class="material-icons"
+                  style="font-size:16px;vertical-align:middle;">arrow_drop_down</span>
+              </button>
+              <ul id="createMenu" class="dropdown-menu" style="
                     display: none;
                     position: absolute;
                     top: 100%;
@@ -411,27 +427,23 @@
                     box-shadow: 0 2px 6px rgba(0,0,0,0.2);
                     z-index: 1000;
                     min-width: 140px;
-                  "
-                >
-                  <li id="createFileOption" class="dropdown-item" data-i18n-key="create_file" style="padding:8px 12px; cursor:pointer;">
-                    ${t('create_file')}
-                  </li>
-                  <li id="createFolderOption" class="dropdown-item" data-i18n-key="create_folder" style="padding:8px 12px; cursor:pointer;">
-                    ${t('create_folder')}
-                  </li>
-                </ul>
-              </div>
+                  ">
+                <li id="createFileOption" class="dropdown-item" data-i18n-key="create_file"
+                  style="padding:8px 12px; cursor:pointer;">
+                  ${t('create_file')}
+                </li>
+                <li id="createFolderOption" class="dropdown-item" data-i18n-key="create_folder"
+                  style="padding:8px 12px; cursor:pointer;">
+                  ${t('create_folder')}
+                </li>
+              </ul>
+            </div>
             <!-- Create File Modal -->
             <div id="createFileModal" class="modal" style="display:none;">
               <div class="modal-content">
                 <h4 data-i18n-key="create_new_file">Create New File</h4>
-                <input
-                  type="text"
-                  id="createFileNameInput"
-                  class="form-control"
-                  placeholder="Enter filename…"
-                  data-i18n-placeholder="newfile_placeholder"
-                />
+                <input type="text" id="createFileNameInput" class="form-control" placeholder="Enter filename…"
+                  data-i18n-placeholder="newfile_placeholder" />
                 <div class="modal-footer" style="margin-top:1rem; text-align:right;">
                   <button id="cancelCreateFile" class="btn btn-secondary" data-i18n-key="cancel">Cancel</button>
                   <button id="confirmCreateFile" class="btn btn-primary" data-i18n-key="create">Create</button>
@@ -563,6 +575,7 @@
       </div>
     </div>
   </div>
+  <script src="js/version.js"></script>
   <script type="module" src="js/main.js"></script>
 </body>
 

public/js/auth.js

@@ -36,13 +36,33 @@ window.currentOIDCConfig = currentOIDCConfig;
 window.pendingTOTP = new URLSearchParams(window.location.search).get('totp_required') === '1';
 
 // override showToast to suppress the "Please log in to continue." toast during TOTP
-function showToast(msgKey) {
-  const msg = t(msgKey);
-  if (window.pendingTOTP && msgKey === "please_log_in_to_continue") {
+
+function showToast(msgKeyOrText, type) {
+  const isDemoHost = window.location.hostname.toLowerCase() === "demo.filerise.net";
+
+  // If it's the pre-login prompt and we're on the demo site, show demo creds instead.
+  if (isDemoHost) {
+    return originalShowToast("Demo site — use: \nUsername: demo\nPassword: demo", 12000);
+  }
+
+  // Don’t nag during pending TOTP, as you already had
+  if (window.pendingTOTP && msgKeyOrText === "please_log_in_to_continue") {
     return;
   }
-  originalShowToast(msg);
+
+  // Translate if a key; otherwise pass through the raw text
+  let msg = msgKeyOrText;
+  try {
+    const translated = t(msgKeyOrText);
+    // If t() changed it or it's a key-like string, use the translation
+    if (typeof translated === "string" && translated !== msgKeyOrText) {
+      msg = translated;
+    }
+  } catch { /* if t() isn’t available here, just use the original */ }
+
+  return originalShowToast(msg);
 }
+
 window.showToast = showToast;
 
 const originalFetch = window.fetch;
@@ -161,27 +181,31 @@ function updateLoginOptionsUIFromStorage() {
 
 export function loadAdminConfigFunc() {
   return fetch("/api/admin/getConfig.php", { credentials: "include" })
-    .then(response => response.json())
-    .then(config => {
-      localStorage.setItem("headerTitle", config.header_title || "FileRise");
+    .then(async (response) => {
+      // If a proxy or some edge returns 204/empty, handle gracefully
+      let config = {};
+      try { config = await response.json(); } catch { config = {}; }
 
-      // Update login options using the nested loginOptions object.
-      localStorage.setItem("disableFormLogin", config.loginOptions.disableFormLogin);
-      localStorage.setItem("disableBasicAuth", config.loginOptions.disableBasicAuth);
-      localStorage.setItem("disableOIDCLogin", config.loginOptions.disableOIDCLogin);
-      localStorage.setItem("globalOtpauthUrl", config.globalOtpauthUrl || "otpauth://totp/{label}?secret={secret}&issuer=FileRise");
-      localStorage.setItem("authBypass", String(!!config.loginOptions.authBypass));
-      localStorage.setItem("authHeaderName", config.loginOptions.authHeaderName || "X-Remote-User");
+      const headerTitle = config.header_title || "FileRise";
+      localStorage.setItem("headerTitle", headerTitle);
+
+      document.title = headerTitle;
+      const lo = config.loginOptions || {};
+      localStorage.setItem("disableFormLogin",  String(!!lo.disableFormLogin));
+      localStorage.setItem("disableBasicAuth",  String(!!lo.disableBasicAuth));
+      localStorage.setItem("disableOIDCLogin",  String(!!lo.disableOIDCLogin));
+      localStorage.setItem("globalOtpauthUrl",  config.globalOtpauthUrl || "otpauth://totp/{label}?secret={secret}&issuer=FileRise");
+      // These may be absent for non-admins; default them
+      localStorage.setItem("authBypass",        String(!!lo.authBypass));
+      localStorage.setItem("authHeaderName",    lo.authHeaderName || "X-Remote-User");
 
       updateLoginOptionsUIFromStorage();
 
       const headerTitleElem = document.querySelector(".header-title h1");
-      if (headerTitleElem) {
-        headerTitleElem.textContent = config.header_title || "FileRise";
-      }
+      if (headerTitleElem) headerTitleElem.textContent = headerTitle;
     })
     .catch(() => {
-      // Use defaults.
+      // Fallback defaults if request truly fails
       localStorage.setItem("headerTitle", "FileRise");
       localStorage.setItem("disableFormLogin", "false");
       localStorage.setItem("disableBasicAuth", "false");
@@ -190,9 +214,7 @@ export function loadAdminConfigFunc() {
       updateLoginOptionsUIFromStorage();
 
       const headerTitleElem = document.querySelector(".header-title h1");
-      if (headerTitleElem) {
-        headerTitleElem.textContent = "FileRise";
-      }
+      if (headerTitleElem) headerTitleElem.textContent = "FileRise";
     });
 }
 

public/js/authModals.js

@@ -328,10 +328,19 @@ export async function openUserPanel() {
     const langSel = document.createElement('select');
     langSel.id = 'languageSelector';
     langSel.className = 'form-select';
-    ['en', 'es', 'fr', 'de'].forEach(code => {
+    const languages = [
+      { code: 'en',    labelKey: 'english',             fallback: 'English' },
+      { code: 'es',    labelKey: 'spanish',             fallback: 'Español' },
+      { code: 'fr',    labelKey: 'french',              fallback: 'Français' },
+      { code: 'de',    labelKey: 'german',              fallback: 'Deutsch' },
+      { code: 'zh-CN', labelKey: 'chinese_simplified',  fallback: '简体中文' },
+    ];
+    
+    languages.forEach(({ code, labelKey, fallback }) => {
       const opt = document.createElement('option');
       opt.value = code;
-      opt.textContent = t(code === 'en' ? 'english' : code === 'es' ? 'spanish' : code === 'fr' ? 'french' : 'german');
+      // use i18n if available, otherwise fallback
+      opt.textContent = (typeof t === 'function' ? t(labelKey) : '') || fallback;
       langSel.appendChild(opt);
     });
     langSel.value = localStorage.getItem('language') || 'en';

public/js/fileEditor.js

@@ -9,29 +9,62 @@ const EDITOR_BLOCK_THRESHOLD = 10 * 1024 * 1024; // >10 MiB => block editing
 
 // Lazy-load CodeMirror modes on demand
 const CM_CDN = "https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.5/";
+
+// Which mode file to load for a given name/mime
 const MODE_URL = {
-  // core you've likely already loaded:
-  "xml": "mode/xml/xml.min.js",
-  "css": "mode/css/css.min.js",
+  // core/common
+  "xml":        "mode/xml/xml.min.js",
+  "css":        "mode/css/css.min.js",
   "javascript": "mode/javascript/javascript.min.js",
 
-  // extras you may want on-demand:
-  "htmlmixed": "mode/htmlmixed/htmlmixed.min.js",
+  // meta / combos
+  "htmlmixed":  "mode/htmlmixed/htmlmixed.min.js",
   "application/x-httpd-php": "mode/php/php.min.js",
-  "php": "mode/php/php.min.js",
-  "markdown": "mode/markdown/markdown.min.js",
-  "python": "mode/python/python.min.js",
-  "sql": "mode/sql/sql.min.js",
-  "shell": "mode/shell/shell.min.js",
-  "yaml": "mode/yaml/yaml.min.js",
+
+  // docs / data
+  "markdown":   "mode/markdown/markdown.min.js",
+  "yaml":       "mode/yaml/yaml.min.js",
   "properties": "mode/properties/properties.min.js",
-  "text/x-csrc": "mode/clike/clike.min.js",
-  "text/x-c++src": "mode/clike/clike.min.js",
-  "text/x-java": "mode/clike/clike.min.js",
-  "text/x-csharp": "mode/clike/clike.min.js",
-  "text/x-kotlin": "mode/clike/clike.min.js"
+  "sql":        "mode/sql/sql.min.js",
+
+  // shells
+  "shell":      "mode/shell/shell.min.js",
+
+  // languages
+  "python":     "mode/python/python.min.js",
+  "text/x-csrc":    "mode/clike/clike.min.js",
+  "text/x-c++src":  "mode/clike/clike.min.js",
+  "text/x-java":    "mode/clike/clike.min.js",
+  "text/x-csharp":  "mode/clike/clike.min.js",
+  "text/x-kotlin":  "mode/clike/clike.min.js"
 };
 
+// Map any mime/alias to the key we use in MODE_URL
+function normalizeModeName(modeOption) {
+  const name = typeof modeOption === "string" ? modeOption : (modeOption && modeOption.name);
+  if (!name) return null;
+  if (name === "text/html") return "htmlmixed";          // CodeMirror uses htmlmixed for HTML
+  if (name === "php") return "application/x-httpd-php";  // prefer the full mime
+  return name;
+}
+
+const MODE_SRI = {
+  "mode/xml/xml.min.js": "sha512-LarNmzVokUmcA7aUDtqZ6oTS+YXmUKzpGdm8DxC46A6AHu+PQiYCUlwEGWidjVYMo/QXZMFMIadZtrkfApYp/g==",
+  "mode/css/css.min.js": "sha512-oikhYLgIKf0zWtVTOXh101BWoSacgv4UTJHQOHU+iUQ1Dol3Xjz/o9Jh0U33MPoT/d4aQruvjNvcYxvkTQd0nA==",
+  "mode/javascript/javascript.min.js": "sha512-I6CdJdruzGtvDyvdO4YsiAq+pkWf2efgd1ZUSK2FnM/u2VuRASPC7GowWQrWyjxCZn6CT89s3ddGI+be0Ak9Fg==",
+  "mode/htmlmixed/htmlmixed.min.js": "sha512-HN6cn6mIWeFJFwRN9yetDAMSh+AK9myHF1X9GlSlKmThaat65342Yw8wL7ITuaJnPioG0SYG09gy0qd5+s777w==",
+  "mode/php/php.min.js": "sha512-jZGz5n9AVTuQGhKTL0QzOm6bxxIQjaSbins+vD3OIdI7mtnmYE6h/L+UBGIp/SssLggbkxRzp9XkQNA4AyjFBw==",
+  "mode/markdown/markdown.min.js": "sha512-DmMao0nRIbyDjbaHc8fNd3kxGsZj9PCU6Iu/CeidLQT9Py8nYVA5n0PqXYmvqNdU+lCiTHOM/4E7bM/G8BttJg==",
+  "mode/python/python.min.js": "sha512-2M0GdbU5OxkGYMhakED69bw0c1pW3Nb0PeF3+9d+SnwN1ryPx3wiDdNqK3gSM7KAU/pEV+2tFJFbMKjKAahOkQ==",
+  "mode/sql/sql.min.js": "sha512-u8r8NUnG9B9L2dDmsfvs9ohQ0SO/Z7MB8bkdLxV7fE0Q8bOeP7/qft1D4KyE8HhVrpH3ihSrRoDiMbYR1VQBWQ==",
+  "mode/shell/shell.min.js": "sha512-HoC6JXgjHHevWAYqww37Gfu2c1G7SxAOv42wOakjR8csbTUfTB7OhVzSJ95LL62nII0RCyImp+7nR9zGmJ1wRQ==",
+  "mode/yaml/yaml.min.js": "sha512-+aXDZ93WyextRiAZpsRuJyiAZ38ztttUyO/H3FZx4gOAOv4/k9C6Um1CvHVtaowHZ2h7kH0d+orWvdBLPVwb4g==",
+  "mode/properties/properties.min.js": "sha512-P4OaO+QWj1wPRsdkEHlrgkx+a7qp6nUC8rI6dS/0/HPjHtlEmYfiambxowYa/UfqTxyNUnwTyPt5U6l1GO76yw==",
+  "mode/clike/clike.min.js": "sha512-l8ZIWnQ3XHPRG3MQ8+hT1OffRSTrFwrph1j1oc1Fzc9UKVGef5XN9fdO0vm3nW0PRgQ9LJgck6ciG59m69rvfg=="
+};
+
+const MODE_LOAD_TIMEOUT_MS = 2500; // allow closing immediately; don't wait forever
+
 function loadScriptOnce(url) {
   return new Promise((resolve, reject) => {
     const key = `cm:${url}`;
@@ -39,30 +72,47 @@ function loadScriptOnce(url) {
     if (s) {
       if (s.dataset.loaded === "1") return resolve();
       s.addEventListener("load", () => resolve());
-      s.addEventListener("error", reject);
+      s.addEventListener("error", () => reject(new Error(`Load failed: ${url}`)));
       return;
     }
     s = document.createElement("script");
     s.src = url;
-    s.defer = true;
+    s.async = true;
     s.dataset.key = key;
+
+    // 🔒 Add SRI if we have it
+    const relPath = url.replace(/^https:\/\/cdnjs\.cloudflare\.com\/ajax\/libs\/codemirror\/5\.65\.5\//, "");
+    const sri = MODE_SRI[relPath];
+    if (sri) {
+      s.integrity = sri;
+      s.crossOrigin = "anonymous";
+      // (Optional) further tighten referrer behavior:
+      // s.referrerPolicy = "no-referrer";
+    }
+
     s.addEventListener("load", () => { s.dataset.loaded = "1"; resolve(); });
-    s.addEventListener("error", reject);
+    s.addEventListener("error", () => reject(new Error(`Load failed: ${url}`)));
     document.head.appendChild(s);
   });
 }
 
+
 async function ensureModeLoaded(modeOption) {
-  if (!window.CodeMirror) return; // CM core must be present
-  const name = typeof modeOption === "string" ? modeOption : (modeOption && modeOption.name);
+  if (!window.CodeMirror) return;
+
+  const name = normalizeModeName(modeOption);
   if (!name) return;
-  // Already registered?
-  if ((CodeMirror.modes && CodeMirror.modes[name]) || (CodeMirror.mimeModes && CodeMirror.mimeModes[name])) {
-    return;
-  }
+
+  const isRegistered = () =>
+    (window.CodeMirror?.modes && window.CodeMirror.modes[name]) ||
+    (window.CodeMirror?.mimeModes && window.CodeMirror.mimeModes[name]);
+
+  if (isRegistered()) return;
+
   const url = MODE_URL[name];
-  if (!url) return; // unknown -> fallback to text/plain
-  // Dependencies (htmlmixed needs xml/css/js; php highlighting with HTML also benefits from htmlmixed)
+  if (!url) return; // unknown -> stay in text/plain
+
+  // Dependencies
   if (name === "htmlmixed") {
     await Promise.all([
       ensureModeLoaded("xml"),
@@ -73,6 +123,7 @@ async function ensureModeLoaded(modeOption) {
   if (name === "application/x-httpd-php") {
     await ensureModeLoaded("htmlmixed");
   }
+
   await loadScriptOnce(CM_CDN + url);
 }
 
@@ -81,67 +132,39 @@ function getModeForFile(fileName) {
   const ext = dot >= 0 ? fileName.slice(dot + 1).toLowerCase() : "";
 
   switch (ext) {
-    // markup
     case "html":
-    case "htm":
-      return "text/html";                 // ensureModeLoaded will map to htmlmixed
-    case "xml":
-      return "xml";
+    case "htm": return "text/html";
+    case "xml": return "xml";
     case "md":
-    case "markdown":
-      return "markdown";
+    case "markdown": return "markdown";
     case "yml":
-    case "yaml":
-      return "yaml";
-
-    // styles & scripts
-    case "css":
-      return "css";
-    case "js":
-      return "javascript";
-    case "json":
-      return { name: "javascript", json: true };
-
-    // server / langs
-    case "php":
-      return "application/x-httpd-php";
-    case "py":
-      return "python";
-    case "sql":
-      return "sql";
+    case "yaml": return "yaml";
+    case "css": return "css";
+    case "js": return "javascript";
+    case "json": return { name: "javascript", json: true };
+    case "php": return "application/x-httpd-php";
+    case "py": return "python";
+    case "sql": return "sql";
     case "sh":
     case "bash":
     case "zsh":
-    case "bat":
-      return "shell";
-
-    // config-y files
+    case "bat": return "shell";
     case "ini":
     case "conf":
     case "config":
-    case "properties":
-      return "properties";
-
-    // C-family / JVM
+    case "properties": return "properties";
     case "c":
-    case "h":
-      return "text/x-csrc";
+    case "h": return "text/x-csrc";
     case "cpp":
     case "cxx":
     case "hpp":
     case "hh":
-    case "hxx":
-      return "text/x-c++src";
-    case "java":
-      return "text/x-java";
-    case "cs":
-      return "text/x-csharp";
+    case "hxx": return "text/x-c++src";
+    case "java": return "text/x-java";
+    case "cs": return "text/x-csharp";
     case "kt":
-    case "kts":
-      return "text/x-kotlin";
-
-    default:
-      return "text/plain";
+    case "kts": return "text/x-kotlin";
+    default: return "text/plain";
   }
 }
 export { getModeForFile };
@@ -158,18 +181,15 @@ export { adjustEditorSize };
 
 function observeModalResize(modal) {
   if (!modal) return;
-  const resizeObserver = new ResizeObserver(() => {
-    adjustEditorSize();
-  });
+  const resizeObserver = new ResizeObserver(() => adjustEditorSize());
   resizeObserver.observe(modal);
 }
 export { observeModalResize };
 
 export function editFile(fileName, folder) {
+  // destroy any previous editor
   let existingEditor = document.getElementById("editorContainer");
-  if (existingEditor) {
-    existingEditor.remove();
-  }
+  if (existingEditor) existingEditor.remove();
 
   const folderUsed = folder || window.currentFolder || "root";
   const folderPath = folderUsed === "root"
@@ -179,9 +199,7 @@ export function editFile(fileName, folder) {
 
   fetch(fileUrl, { method: "HEAD" })
     .then(response => {
-      const lenHeader =
-        response.headers.get("content-length") ??
-        response.headers.get("Content-Length");
+      const lenHeader = response.headers.get("content-length") ?? response.headers.get("Content-Length");
       const sizeBytes = lenHeader ? parseInt(lenHeader, 10) : null;
 
       if (sizeBytes !== null && sizeBytes > EDITOR_BLOCK_THRESHOLD) {
@@ -192,104 +210,143 @@ export function editFile(fileName, folder) {
     })
     .then(() => fetch(fileUrl))
     .then(response => {
-      if (!response.ok) {
-        throw new Error("HTTP error! Status: " + response.status);
-      }
-      const lenHeader =
-        response.headers.get("content-length") ??
-        response.headers.get("Content-Length");
+      if (!response.ok) throw new Error("HTTP error! Status: " + response.status);
+      const lenHeader = response.headers.get("content-length") ?? response.headers.get("Content-Length");
       const sizeBytes = lenHeader ? parseInt(lenHeader, 10) : null;
       return Promise.all([response.text(), sizeBytes]);
     })
     .then(([content, sizeBytes]) => {
-      const forcePlainText =
-        sizeBytes !== null && sizeBytes > EDITOR_PLAIN_THRESHOLD;
+      const forcePlainText = sizeBytes !== null && sizeBytes > EDITOR_PLAIN_THRESHOLD;
 
+      // --- Build modal immediately and wire close controls BEFORE any async loads ---
       const modal = document.createElement("div");
       modal.id = "editorContainer";
       modal.classList.add("modal", "editor-modal");
+      modal.setAttribute("tabindex", "-1"); // for Escape handling
       modal.innerHTML = `
-      <div class="editor-header">
-        <h3 class="editor-title">${t("editing")}: ${escapeHTML(fileName)}${
-          forcePlainText ? " <span style='font-size:.8em;opacity:.7'>(plain text mode)</span>" : ""
-        }</h3>
-        <div class="editor-controls">
-           <button id="decreaseFont" class="btn btn-sm btn-secondary">${t("decrease_font")}</button>
-           <button id="increaseFont" class="btn btn-sm btn-secondary">${t("increase_font")}</button>
+        <div class="editor-header">
+          <h3 class="editor-title">
+            ${t("editing")}: ${escapeHTML(fileName)}
+            ${forcePlainText ? " <span style='font-size:.8em;opacity:.7'>(plain text mode)</span>" : ""}
+          </h3>
+          <div class="editor-controls">
+            <button id="decreaseFont" class="btn btn-sm btn-secondary">${t("decrease_font")}</button>
+            <button id="increaseFont" class="btn btn-sm btn-secondary">${t("increase_font")}</button>
+          </div>
+          <button id="closeEditorX" class="editor-close-btn" aria-label="${t("close")}">&times;</button>
         </div>
-        <button id="closeEditorX" class="editor-close-btn">&times;</button>
-      </div>
-      <textarea id="fileEditor" class="editor-textarea">${escapeHTML(content)}</textarea>
-      <div class="editor-footer">
-        <button id="saveBtn" class="btn btn-primary">${t("save")}</button>
-        <button id="closeBtn" class="btn btn-secondary">${t("close")}</button>
-      </div>
-    `;
+        <textarea id="fileEditor" class="editor-textarea">${escapeHTML(content)}</textarea>
+        <div class="editor-footer">
+          <button id="saveBtn" class="btn btn-primary" disabled>${t("save")}</button>
+          <button id="closeBtn" class="btn btn-secondary">${t("close")}</button>
+        </div>
+      `;
       document.body.appendChild(modal);
       modal.style.display = "block";
+      modal.focus();
 
-      const isDarkMode = document.body.classList.contains("dark-mode");
-      const theme = isDarkMode ? "material-darker" : "default";
-
-      // choose mode + lighter settings for large files
-      const mode = forcePlainText ? "text/plain" : getModeForFile(fileName);
-      const cmOptions = {
-        lineNumbers: !forcePlainText,
-        mode: mode,
-        theme: theme,
-        viewportMargin: forcePlainText ? 20 : Infinity,
-        lineWrapping: false,
+      let canceled = false;
+      const doClose = () => {
+        canceled = true;
+        window.currentEditor = null;
+        modal.remove();
       };
 
-      // ✅ LOAD MODE FIRST, THEN INSTANTIATE CODEMIRROR
-      ensureModeLoaded(mode).finally(() => {
-        const editor = CodeMirror.fromTextArea(
+      // Wire close actions right away
+      modal.addEventListener("keydown", (e) => { if (e.key === "Escape") doClose(); });
+      document.getElementById("closeEditorX").addEventListener("click", doClose);
+      document.getElementById("closeBtn").addEventListener("click", doClose);
+
+      // Keep buttons responsive even before editor exists
+      const decBtn = document.getElementById("decreaseFont");
+      const incBtn = document.getElementById("increaseFont");
+      decBtn.addEventListener("click", () => {});
+      incBtn.addEventListener("click", () => {});
+
+      // Theme + mode selection
+      const isDarkMode = document.body.classList.contains("dark-mode");
+      const theme = isDarkMode ? "material-darker" : "default";
+      const desiredMode = forcePlainText ? "text/plain" : getModeForFile(fileName);
+
+      // Helper to check whether a mode is currently registered
+      const modeName = typeof desiredMode === "string" ? desiredMode : (desiredMode && desiredMode.name);
+      const isModeRegistered = () =>
+        (window.CodeMirror?.modes && window.CodeMirror.modes[modeName]) ||
+        (window.CodeMirror?.mimeModes && window.CodeMirror.mimeModes[modeName]);
+
+      // Start mode loading (don’t block closing)
+      const modePromise = ensureModeLoaded(desiredMode);
+
+      // Wait up to MODE_LOAD_TIMEOUT_MS; then proceed with whatever is available
+      const timeout = new Promise((res) => setTimeout(res, MODE_LOAD_TIMEOUT_MS));
+
+      Promise.race([modePromise, timeout]).then(() => {
+        if (canceled) return;
+        if (!window.CodeMirror) {
+          // Core not present: keep plain <textarea>; enable Save and bail gracefully
+          document.getElementById("saveBtn").disabled = false;
+          observeModalResize(modal);
+          return;
+        }
+
+        const initialMode = (forcePlainText || !isModeRegistered()) ? "text/plain" : desiredMode;
+        const cmOptions = {
+          lineNumbers: !forcePlainText,
+          mode: initialMode,
+          theme,
+          viewportMargin: forcePlainText ? 20 : Infinity,
+          lineWrapping: false
+        };
+
+        const editor = window.CodeMirror.fromTextArea(
           document.getElementById("fileEditor"),
           cmOptions
         );
-
         window.currentEditor = editor;
 
-        setTimeout(() => {
-          adjustEditorSize();
-        }, 50);
-
+        setTimeout(adjustEditorSize, 50);
         observeModalResize(modal);
 
+        // Font controls (now that editor exists)
         let currentFontSize = 14;
-        editor.getWrapperElement().style.fontSize = currentFontSize + "px";
+        const wrapper = editor.getWrapperElement();
+        wrapper.style.fontSize = currentFontSize + "px";
         editor.refresh();
 
-        document.getElementById("closeEditorX").addEventListener("click", function () {
-          modal.remove();
-        });
-
-        document.getElementById("decreaseFont").addEventListener("click", function () {
+        decBtn.addEventListener("click", function () {
           currentFontSize = Math.max(8, currentFontSize - 2);
-          editor.getWrapperElement().style.fontSize = currentFontSize + "px";
+          wrapper.style.fontSize = currentFontSize + "px";
           editor.refresh();
         });
-
-        document.getElementById("increaseFont").addEventListener("click", function () {
+        incBtn.addEventListener("click", function () {
           currentFontSize = Math.min(32, currentFontSize + 2);
-          editor.getWrapperElement().style.fontSize = currentFontSize + "px";
+          wrapper.style.fontSize = currentFontSize + "px";
           editor.refresh();
         });
 
-        document.getElementById("saveBtn").addEventListener("click", function () {
+        // Save
+        const saveBtn = document.getElementById("saveBtn");
+        saveBtn.disabled = false;
+        saveBtn.addEventListener("click", function () {
           saveFile(fileName, folderUsed);
         });
 
-        document.getElementById("closeBtn").addEventListener("click", function () {
-          modal.remove();
-        });
-
+        // Theme switch
         function updateEditorTheme() {
           const isDark = document.body.classList.contains("dark-mode");
           editor.setOption("theme", isDark ? "material-darker" : "default");
         }
         const toggle = document.getElementById("darkModeToggle");
         if (toggle) toggle.addEventListener("click", updateEditorTheme);
+
+        // If we started in plain text due to timeout, flip to the real mode once it arrives
+        modePromise.then(() => {
+          if (!canceled && !forcePlainText && isModeRegistered()) {
+            editor.setOption("mode", desiredMode);
+          }
+        }).catch(() => {
+          // If the mode truly fails to load, we just stay in plain text
+        });
       });
     })
     .catch(error => {
@@ -298,7 +355,6 @@ export function editFile(fileName, folder) {
     });
 }
 
-
 export function saveFile(fileName, folder) {
   const editor = window.currentEditor;
   if (!editor) {

public/js/i18n.js

@@ -216,6 +216,7 @@ const translations = {
     "spanish": "Spanish",
     "french": "French",
     "german": "German",
+    "chinese_simplified": "Chinese (Simplified)",
     "use_totp_code_instead": "Use TOTP Code instead",
     "submit_recovery_code": "Submit Recovery Code",
     "please_enter_recovery_code": "Please enter your recovery code.",
@@ -275,7 +276,33 @@ const translations = {
     "newfile_placeholder": "New file name",
     "file_created_successfully": "File created successfully!",
     "error_creating_file": "Error creating file",
-    "file_created":          "File created successfully!"
+    "file_created": "File created successfully!",
+    "no_access_to_resource": "You do not have access to this resource.",
+    "can_share": "Can Share",
+    "bypass_ownership": "Bypass Ownership",
+    "error_loading_user_grants": "Error loading user grants",
+    "click_to_edit": "Click to edit",
+    "folder_access": "Folder Access",
+    "move_folder": "Move Folder",
+    "move_folder_message": "Select a destination folder to move this folder to:",
+    "move_folder_title": "Move this folder",
+    "move_folder_success": "Folder moved successfully.",
+    "move_folder_error": "Error moving folder.",
+    "move_folder_invalid": "Invalid source or destination folder.",
+    "move_folder_denied": "You do not have permission to move this folder.",
+    "move_folder_same_dest": "Destination cannot be the source or one of its subfolders.",
+    "move_folder_same_owner": "Source and destination must have the same owner.",
+    "move_folder_confirm": "Are you sure you want to move this folder?",
+    "move_folder_select_dest": "Select a destination folder",
+    "move_folder_select_dest_help": "Choose where this folder should be moved to.",
+    "acl_move_folder_label": "Move Folder (source)",
+    "acl_move_folder_help": "Allows moving this folder to a different parent. Requires Manage or Ownership on the folder.",
+    "acl_move_in_label": "Allow Moves Into This Folder (destination)",
+    "acl_move_in_help": "Allows items or folders from elsewhere to be moved into this folder. Requires Manage on the destination folder.",
+    "acl_move_folder_info": "Moving folders is restricted to folder owners or managers. Destination folders must also allow moves in.",
+    "context_move_folder": "Move Folder...",
+    "context_move_here": "Move Here",
+    "context_move_cancel": "Cancel Move"
   },
   es: {
     "please_log_in_to_continue": "Por favor, inicie sesión para continuar.",
@@ -458,6 +485,7 @@ const translations = {
     "spanish": "Español",
     "french": "Francés",
     "german": "Alemán",
+    "chinese_simplified": "Chino (simplificado)",
     "use_totp_code_instead": "Usar código TOTP en su lugar",
     "submit_recovery_code": "Enviar código de recuperación",
     "please_enter_recovery_code": "Por favor, ingrese su código de recuperación.",
@@ -686,6 +714,7 @@ const translations = {
     "spanish": "Espagnol",
     "french": "Français",
     "german": "Allemand",
+    "chinese_simplified": "Chinois (simplifié)",
     "use_totp_code_instead": "Utiliser le code TOTP à la place",
     "submit_recovery_code": "Soumettre le code de récupération",
     "please_enter_recovery_code": "Veuillez entrer votre code de récupération.",
@@ -923,6 +952,7 @@ const translations = {
     "spanish": "Spanisch",
     "french": "Französisch",
     "german": "Deutsch",
+    "chinese_simplified": "Chinesisch (vereinfacht)",
     "use_totp_code_instead": "Stattdessen TOTP-Code verwenden",
     "submit_recovery_code": "Wiederherstellungscode absenden",
     "please_enter_recovery_code": "Bitte geben Sie Ihren Wiederherstellungscode ein.",
@@ -972,7 +1002,275 @@ const translations = {
     "show": "Zeige",
     "items_per_page": "elemente pro seite",
     "columns": "Spalten"
+  },
+  "zh-CN": {
+    "please_log_in_to_continue": "请登录以继续。",
+    "no_files_selected": "未选择文件。",
+    "confirm_delete_files": "确定要删除所选的 {count} 个文件吗？",
+    "element_not_found": "未找到 ID 为 \"{id}\" 的元素。",
+    "search_placeholder": "搜索文件、标签和上传者…",
+    "search_placeholder_advanced": "高级搜索：文件、标签、上传者和内容…",
+    "basic_search_tooltip": "基础搜索：按文件名、标签和上传者搜索。",
+    "advanced_search_tooltip": "高级搜索：包括文件内容、文件名、标签和上传者。",
+    "file_name": "文件名",
+    "date_modified": "修改日期",
+    "upload_date": "上传日期",
+    "file_size": "文件大小",
+    "uploader": "上传者",
+    "enter_totp_code": "输入 TOTP 验证码",
+    "use_recovery_code_instead": "改用恢复代码",
+    "enter_recovery_code": "输入恢复代码",
+    "editing": "正在编辑",
+    "decrease_font": "A-",
+    "increase_font": "A+",
+    "save": "保存",
+    "close": "关闭",
+    "no_files_found": "未找到文件。",
+    "switch_to_table_view": "切换到表格视图",
+    "switch_to_gallery_view": "切换到图库视图",
+    "share_file": "分享文件",
+    "set_expiration": "设置到期时间：",
+    "password_optional": "密码（可选）：",
+    "generate_share_link": "生成分享链接",
+    "shareable_link": "可分享链接：",
+    "copy_link": "复制链接",
+    "tag_file": "标记文件",
+    "tag_name": "标签名称：",
+    "tag_color": "标签颜色：",
+    "save_tag": "保存标签",
+    "light_mode": "浅色模式",
+    "dark_mode": "深色模式",
+    "upload_instruction": "将文件/文件夹拖到此处，或点击“选择文件”",
+    "no_files_selected_default": "未选择文件",
+    "choose_files": "选择文件",
+    "delete_selected": "删除所选",
+    "copy_selected": "复制所选",
+    "move_selected": "移动所选",
+    "tag_selected": "标记所选",
+    "download_zip": "下载 ZIP",
+    "extract_zip": "解压 ZIP",
+    "preview": "预览",
+    "edit": "编辑",
+    "rename": "重命名",
+    "trash_empty": "回收站为空。",
+    "no_trash_selected": "未选择要还原的回收站项目。",
+
+    "title": "FileRise",
+    "header_title": "FileRise",
+    "header_title_text": "标题文本",
+    "logout": "退出登录",
+    "change_password": "更改密码",
+    "restore_text": "还原或",
+    "delete_text": "删除回收站项目",
+    "restore_selected": "还原所选",
+    "restore_all": "全部还原",
+    "delete_selected_trash": "删除所选",
+    "delete_all": "全部删除",
+    "upload_header": "上传文件/文件夹",
+
+    "folder_navigation": "文件夹导航与管理",
+    "create_folder": "创建文件夹",
+    "create_folder_title": "创建文件夹",
+    "enter_folder_name": "输入文件夹名称",
+    "cancel": "取消",
+    "create": "创建",
+    "rename_folder": "重命名文件夹",
+    "rename_folder_title": "重命名文件夹",
+    "rename_folder_placeholder": "输入新的文件夹名称",
+    "delete_folder": "删除文件夹",
+    "delete_folder_title": "删除文件夹",
+    "delete_folder_message": "确定要删除此文件夹吗？",
+    "folder_help": "文件夹帮助",
+    "folder_help_item_1": "点击文件夹以查看其中的文件。",
+    "folder_help_item_2": "使用 [-] 折叠，使用 [+] 展开文件夹。",
+    "folder_help_item_3": "选择一个文件夹并点击“创建文件夹”以添加子文件夹。",
+    "folder_help_item_4": "要重命名或删除文件夹，请选择后点击相应按钮。",
+
+    "actions": "操作",
+    "file_list_title": "文件列表（根目录）",
+    "files_in": "文件位于",
+    "delete_files": "删除文件",
+    "delete_selected_files_title": "删除所选文件",
+    "delete_files_message": "确定要删除所选文件吗？",
+    "copy_files": "复制文件",
+    "copy_files_title": "复制所选文件",
+    "copy_files_message": "选择目标文件夹以复制所选文件：",
+    "move_files": "移动文件",
+    "move_files_title": "移动所选文件",
+    "move_files_message": "选择目标文件夹以移动所选文件：",
+    "move": "移动",
+    "extract_zip_button": "解压 ZIP",
+    "download_zip_title": "将所选文件打包为 ZIP 下载",
+    "download_zip_prompt": "输入 ZIP 文件名：",
+    "zip_placeholder": "files.zip",
+    "share": "分享",
+    "total_files": "文件总数",
+    "total_size": "总大小",
+    "prev": "上一页",
+    "next": "下一页",
+    "page": "第",
+    "of": "页，共",
+
+    "login": "登录",
+    "remember_me": "记住我",
+    "login_oidc": "使用 OIDC 登录",
+    "basic_http_login": "使用基本 HTTP 登录",
+
+    "change_password_title": "更改密码",
+    "old_password": "旧密码",
+    "new_password": "新密码",
+    "confirm_new_password": "确认新密码",
+
+    "create_new_user_title": "创建新用户",
+    "username": "用户名：",
+    "password": "密码：",
+    "enter_password": "密码",
+    "preparing_download": "正在准备下载…",
+    "download_file": "下载文件",
+    "confirm_or_change_filename": "确认或修改下载文件名：",
+    "filename": "文件名",
+    "download": "下载",
+    "grant_admin": "授予管理员权限",
+    "save_user": "保存用户",
+
+    "remove_user_title": "删除用户",
+    "select_user_remove": "选择要删除的用户：",
+    "delete_user": "删除用户",
+
+    "rename_file_title": "重命名文件",
+    "rename_file_placeholder": "输入新的文件名",
+
+    "share_folder": "分享文件夹",
+    "allow_uploads": "允许上传",
+    "share_link_generated": "已生成分享链接",
+    "error_generating_share_link": "生成分享链接时出错",
+    "custom": "自定义",
+    "duration": "持续时间",
+    "seconds": "秒",
+    "minutes": "分钟",
+    "hours": "小时",
+    "days": "天",
+    "custom_duration_warning": "⚠️ 使用较长的到期时间可能存在安全风险，请谨慎使用。",
+
+    "folder_share": "分享文件夹",
+
+    "yes": "是",
+    "no": "否",
+    "unsaved_changes_confirm": "您有未保存的更改，确定要关闭而不保存吗？",
+    "delete": "删除",
+    "upload": "上传",
+    "copy": "复制",
+    "extract": "解压",
+    "user": "用户：",
+    "unknown_error": "未知错误",
+    "link_copied": "链接已复制到剪贴板",
+    "weeks": "周",
+    "months": "月",
+
+    "dark_mode_toggle": "深色模式",
+    "light_mode_toggle": "浅色模式",
+    "switch_to_light_mode": "切换到浅色模式",
+    "switch_to_dark_mode": "切换到深色模式",
+
+    "header_settings": "标题设置",
+    "shared_max_upload_size_bytes_title": "共享最大上传大小",
+    "shared_max_upload_size_bytes": "共享最大上传大小（字节）",
+    "max_bytes_shared_uploads_note": "请输入共享文件夹上传的最大允许字节数",
+    "manage_shared_links": "管理分享链接",
+    "folder_shares": "文件夹分享",
+    "file_shares": "文件分享",
+    "loading": "正在加载…",
+    "error_loading_share_links": "加载分享链接时出错",
+    "share_deleted_successfully": "分享已成功删除",
+    "error_deleting_share": "删除分享时出错",
+    "password_protected": "受密码保护",
+    "no_shared_links_available": "暂无可用的分享链接",
+
+    "admin_panel": "管理员面板",
+    "user_panel": "用户面板",
+    "user_settings": "用户设置",
+    "save_profile_picture": "保存头像",
+    "please_select_picture": "请选择图片",
+    "profile_picture_updated": "头像已更新",
+    "error_updating_picture": "更新头像时出错",
+    "trash_restore_delete": "回收站恢复/删除",
+    "totp_settings": "TOTP 设置",
+    "enable_totp": "启用 TOTP",
+    "language": "语言",
+    "select_language": "选择语言",
+    "english": "英语",
+    "spanish": "西班牙语",
+    "french": "法语",
+    "german": "德语",
+    "chinese_simplified": "简体中文",
+    "use_totp_code_instead": "改用 TOTP 验证码",
+    "submit_recovery_code": "提交恢复代码",
+    "please_enter_recovery_code": "请输入您的恢复代码。",
+    "recovery_code_verification_failed": "恢复代码验证失败",
+    "error_verifying_recovery_code": "验证恢复代码时出错",
+    "totp_verification_failed": "TOTP 验证失败",
+    "error_verifying_totp_code": "验证 TOTP 代码时出错",
+    "totp_setup": "TOTP 设置",
+    "scan_qr_code": "请使用验证器应用扫描此二维码。",
+    "enter_totp_confirmation": "输入应用生成的 6 位验证码以确认设置：",
+    "confirm": "确认",
+    "please_enter_valid_code": "请输入有效的 6 位验证码。",
+    "totp_enabled_successfully": "TOTP 启用成功。",
+    "error_generating_recovery_code": "生成恢复代码时出错",
+    "error_loading_qr_code": "加载二维码时出错。",
+    "error_disabling_totp_setting": "禁用 TOTP 设置时出错",
+    "user_management": "用户管理",
+    "add_user": "添加用户",
+    "remove_user": "删除用户",
+    "user_permissions": "用户权限",
+    "oidc_configuration": "OIDC 配置",
+    "oidc_provider_url": "OIDC 提供者 URL",
+    "oidc_client_id": "OIDC 客户端 ID",
+    "oidc_client_secret": "OIDC 客户端密钥",
+    "oidc_redirect_uri": "OIDC 重定向 URI",
+    "global_totp_settings": "全局 TOTP 设置",
+    "global_otpauth_url": "全局 OTPAuth URL",
+    "login_options": "登录选项",
+    "disable_login_form": "禁用登录表单",
+    "disable_basic_http_auth": "禁用基本 HTTP 认证",
+    "disable_oidc_login": "禁用 OIDC 登录",
+    "save_settings": "保存设置",
+    "at_least_one_login_method": "至少保留一种登录方式。",
+    "settings_updated_successfully": "设置已成功更新。",
+    "error_updating_settings": "更新设置时出错",
+    "user_permissions_updated_successfully": "用户权限已成功更新。",
+    "error_updating_permissions": "更新权限时出错",
+    "no_users_found": "未找到用户。",
+    "user_folder_only": "仅限用户文件夹",
+    "read_only": "只读",
+    "disable_upload": "禁用上传",
+    "error_loading_users": "加载用户时出错",
+    "save_permissions": "保存权限",
+    "your_recovery_code": "您的恢复代码",
+    "please_save_recovery_code": "请妥善保存此代码。此代码仅显示一次且只能使用一次。",
+    "ok": "确定",
+    "show": "显示",
+    "items_per_page": "每页项目数",
+    "columns": "列",
+    "row_height": "行高",
+    "api_docs": "API 文档",
+    "show_folders_above_files": "在文件上方显示文件夹",
+    "display": "显示",
+    "create_file": "创建文件",
+    "create_new_file": "创建新文件",
+    "enter_file_name": "输入文件名",
+    "newfile_placeholder": "新文件名",
+    "file_created_successfully": "文件创建成功！",
+    "error_creating_file": "创建文件时出错",
+    "file_created": "文件创建成功！",
+    "no_access_to_resource": "您无权访问此资源。",
+    "can_share": "可分享",
+    "bypass_ownership": "绕过所有权限制",
+    "error_loading_user_grants": "加载用户授权时出错",
+    "click_to_edit": "点击编辑",
+    "folder_access": "文件夹访问"
   }
+
 };
 
 let currentLocale = 'en';

public/js/main.js

@@ -51,6 +51,52 @@ async function fetchWithCsrfAndRefresh(input, init = {}) {
 // Replace global fetch with the wrapped version so *all* callers benefit.
 window.fetch = fetchWithCsrfAndRefresh;
 
+/* =========================
+   SAFE API HELPERS
+   ========================= */
+export async function apiGETJSON(url, opts = {}) {
+  const res = await fetch(url, { credentials: "include", ...opts });
+  if (res.status === 401) throw new Error("auth");
+  if (res.status === 403) throw new Error("forbidden");
+  if (!res.ok) throw new Error(`http ${res.status}`);
+  try { return await res.json(); } catch { return {}; }
+}
+
+export async function apiPOSTJSON(url, body, opts = {}) {
+  const headers = {
+    "Content-Type": "application/json",
+    "X-CSRF-Token": getCsrfToken(),
+    ...(opts.headers || {})
+  };
+  const res = await fetch(url, {
+    method: "POST",
+    credentials: "include",
+    headers,
+    body: JSON.stringify(body ?? {}),
+    ...opts
+  });
+  if (res.status === 401) throw new Error("auth");
+  if (res.status === 403) throw new Error("forbidden");
+  if (!res.ok) throw new Error(`http ${res.status}`);
+  try { return await res.json(); } catch { return {}; }
+}
+
+// Optional: expose on window for legacy callers
+window.apiGETJSON = apiGETJSON;
+window.apiPOSTJSON = apiPOSTJSON;
+
+// Global handler to keep UX friendly if something forgets to catch
+window.addEventListener("unhandledrejection", (ev) => {
+  const msg = (ev?.reason && ev.reason.message) || "";
+  if (msg === "auth") {
+    showToast(t("please_sign_in_again") || "Please sign in again.", "error");
+    ev.preventDefault();
+  } else if (msg === "forbidden") {
+    showToast(t("no_access_to_resource") || "You don’t have access to that.", "error");
+    ev.preventDefault();
+  }
+});
+
 /* =========================
    APP INIT
    ========================= */
@@ -59,12 +105,14 @@ export function initializeApp() {
   const saved = parseInt(localStorage.getItem('rowHeight') || '48', 10);
   document.documentElement.style.setProperty('--file-row-height', saved + 'px');
 
-  window.currentFolder = "root";
+  //window.currentFolder = "root";
+  const last = localStorage.getItem('lastOpenedFolder');
+  window.currentFolder = last ? last : "root";
   const stored = localStorage.getItem('showFoldersInList');
   window.showFoldersInList = stored === null ? true : stored === 'true';
-
+  loadAdminConfigFunc();
   initTagSearch();
-  loadFileList(window.currentFolder);
+  //loadFileList(window.currentFolder);
 
   const fileListArea = document.getElementById('fileListContainer');
   const uploadArea = document.getElementById('uploadDropArea');
@@ -93,8 +141,12 @@ export function initializeApp() {
   initFileActions();
   initUpload();
   loadFolderTree();
-  setupTrashRestoreDelete();
-  loadAdminConfigFunc();
+  // Only run trash/restore for admins
+ const isAdmin =
+   localStorage.getItem('isAdmin') === '1' ||  localStorage.getItem('isAdmin') === 'true';
+ if (isAdmin) {
+   setupTrashRestoreDelete();
+ }
 
   const helpBtn = document.getElementById("folderHelpBtn");
   const helpTooltip = document.getElementById("folderHelpTooltip");
@@ -170,6 +222,7 @@ window.openDownloadModal = openDownloadModal;
 window.currentFolder = "root";
 
 document.addEventListener("DOMContentLoaded", function () {
+  // Load admin config early
   loadAdminConfigFunc();
 
   // i18n

public/js/upload.js

@@ -161,91 +161,91 @@ function createFileEntry(file) {
   const removeBtn = document.createElement("button");
   removeBtn.classList.add("remove-file-btn");
   removeBtn.textContent = "×";
-// In your remove button event listener, replace the fetch call with:
-removeBtn.addEventListener("click", function (e) {
-  e.stopPropagation();
-  const uploadIndex = file.uploadIndex;
-  window.selectedFiles = window.selectedFiles.filter(f => f.uploadIndex !== uploadIndex);
-  
-  // Cancel the file upload if possible.
-  if (typeof file.cancel === "function") {
-    file.cancel();
-    console.log("Canceled file upload:", file.fileName);
-  }
-  
-  // Remove file from the resumable queue.
-  if (resumableInstance && typeof resumableInstance.removeFile === "function") {
-    resumableInstance.removeFile(file);
-  }
-  
-  // Call our helper repeatedly to remove the chunk folder.
-  if (file.uniqueIdentifier) {
-    removeChunkFolderRepeatedly(file.uniqueIdentifier, window.csrfToken, 3, 1000);
-  }
-  
-  li.remove();
-  updateFileInfoCount();
-});
+  // In your remove button event listener, replace the fetch call with:
+  removeBtn.addEventListener("click", function (e) {
+    e.stopPropagation();
+    const uploadIndex = file.uploadIndex;
+    window.selectedFiles = window.selectedFiles.filter(f => f.uploadIndex !== uploadIndex);
+
+    // Cancel the file upload if possible.
+    if (typeof file.cancel === "function") {
+      file.cancel();
+      console.log("Canceled file upload:", file.fileName);
+    }
+
+    // Remove file from the resumable queue.
+    if (resumableInstance && typeof resumableInstance.removeFile === "function") {
+      resumableInstance.removeFile(file);
+    }
+
+    // Call our helper repeatedly to remove the chunk folder.
+    if (file.uniqueIdentifier) {
+      removeChunkFolderRepeatedly(file.uniqueIdentifier, window.csrfToken, 3, 1000);
+    }
+
+    li.remove();
+    updateFileInfoCount();
+  });
   li.removeBtn = removeBtn;
   li.appendChild(removeBtn);
 
   // Add pause/resume/restart button if the file supports pause/resume.
-// Conditionally add the pause/resume button only if file.pause is available
-// Pause/Resume button (for resumable file–picker uploads)
-if (typeof file.pause === "function") {
-  const pauseResumeBtn = document.createElement("button");
-  pauseResumeBtn.setAttribute("type", "button"); // not a submit button
-  pauseResumeBtn.classList.add("pause-resume-btn");
-  // Start with pause icon and disable button until upload starts
-  pauseResumeBtn.innerHTML = '<span class="material-icons pauseResumeBtn">pause_circle_outline</span>';
-  pauseResumeBtn.disabled = true; 
-  pauseResumeBtn.addEventListener("click", function (e) {
-    e.stopPropagation();
-    if (file.isError) {
-      // If the file previously failed, try restarting upload.
-      if (typeof file.retry === "function") {
-        file.retry();
-        file.isError = false;
-        pauseResumeBtn.innerHTML = '<span class="material-icons pauseResumeBtn">pause_circle_outline</span>';
-      }
-    } else if (!file.paused) {
-      // Pause the upload (if possible)
-      if (typeof file.pause === "function") {
-        file.pause();
-        file.paused = true;
-        pauseResumeBtn.innerHTML = '<span class="material-icons pauseResumeBtn">play_circle_outline</span>';
-      } else {
-      }
-    } else if (file.paused) {
-      // Resume sequence: first call to resume (or upload() fallback)
-      if (typeof file.resume === "function") {
-        file.resume();
-      } else {
-        resumableInstance.upload();
-      }
-      // After a short delay, pause again then resume
-      setTimeout(() => {
+  // Conditionally add the pause/resume button only if file.pause is available
+  // Pause/Resume button (for resumable file–picker uploads)
+  if (typeof file.pause === "function") {
+    const pauseResumeBtn = document.createElement("button");
+    pauseResumeBtn.setAttribute("type", "button"); // not a submit button
+    pauseResumeBtn.classList.add("pause-resume-btn");
+    // Start with pause icon and disable button until upload starts
+    pauseResumeBtn.innerHTML = '<span class="material-icons pauseResumeBtn">pause_circle_outline</span>';
+    pauseResumeBtn.disabled = true;
+    pauseResumeBtn.addEventListener("click", function (e) {
+      e.stopPropagation();
+      if (file.isError) {
+        // If the file previously failed, try restarting upload.
+        if (typeof file.retry === "function") {
+          file.retry();
+          file.isError = false;
+          pauseResumeBtn.innerHTML = '<span class="material-icons pauseResumeBtn">pause_circle_outline</span>';
+        }
+      } else if (!file.paused) {
+        // Pause the upload (if possible)
         if (typeof file.pause === "function") {
           file.pause();
+          file.paused = true;
+          pauseResumeBtn.innerHTML = '<span class="material-icons pauseResumeBtn">play_circle_outline</span>';
+        } else {
+        }
+      } else if (file.paused) {
+        // Resume sequence: first call to resume (or upload() fallback)
+        if (typeof file.resume === "function") {
+          file.resume();
         } else {
           resumableInstance.upload();
         }
+        // After a short delay, pause again then resume
         setTimeout(() => {
-          if (typeof file.resume === "function") {
-            file.resume();
+          if (typeof file.pause === "function") {
+            file.pause();
           } else {
             resumableInstance.upload();
           }
+          setTimeout(() => {
+            if (typeof file.resume === "function") {
+              file.resume();
+            } else {
+              resumableInstance.upload();
+            }
+          }, 100);
         }, 100);
-      }, 100);
-      file.paused = false;
-      pauseResumeBtn.innerHTML = '<span class="material-icons pauseResumeBtn">pause_circle_outline</span>';
-    } else {
-      console.error("Pause/resume function not available for file", file);
-    }
-  });
-  li.appendChild(pauseResumeBtn);
-}
+        file.paused = false;
+        pauseResumeBtn.innerHTML = '<span class="material-icons pauseResumeBtn">pause_circle_outline</span>';
+      } else {
+        console.error("Pause/resume function not available for file", file);
+      }
+    });
+    li.appendChild(pauseResumeBtn);
+  }
 
   // Preview element
   const preview = document.createElement("div");
@@ -406,20 +406,27 @@ let resumableInstance;
 function initResumableUpload() {
   resumableInstance = new Resumable({
     target: "/api/upload/upload.php",
-    query: { folder: window.currentFolder || "root", upload_token: window.csrfToken },
-    chunkSize: 1.5 * 1024 * 1024, // 1.5 MB chunks
+    chunkSize: 1.5 * 1024 * 1024,
     simultaneousUploads: 3,
     forceChunkSize: true,
     testChunks: false,
-    throttleProgressCallbacks: 1,
     withCredentials: true,
     headers: { 'X-CSRF-Token': window.csrfToken },
-    query: {
+    query: () => ({
       folder: window.currentFolder || "root",
-      upload_token: window.csrfToken   // still as a fallback
-    }
+      upload_token: window.csrfToken
+    })
   });
 
+  // keep query fresh when folder changes (call this from your folder nav code)
+  function updateResumableQuery() {
+    if (!resumableInstance) return;
+    resumableInstance.opts.headers['X-CSRF-Token'] = window.csrfToken;
+    // if you're not using a function for query, do:
+    resumableInstance.opts.query.folder = window.currentFolder || 'root';
+    resumableInstance.opts.query.upload_token = window.csrfToken;
+  }
+
   const fileInput = document.getElementById("file");
   if (fileInput) {
     // Assign Resumable to file input for file picker uploads.
@@ -432,6 +439,7 @@ function initResumableUpload() {
   }
 
   resumableInstance.on("fileAdded", function (file) {
+
     // Initialize custom paused flag
     file.paused = false;
     file.uploadIndex = file.uniqueIdentifier;
@@ -461,16 +469,17 @@ function initResumableUpload() {
     li.dataset.uploadIndex = file.uniqueIdentifier;
     list.appendChild(li);
     updateFileInfoCount();
+    updateResumableQuery();
   });
 
-  resumableInstance.on("fileProgress", function(file) {
+  resumableInstance.on("fileProgress", function (file) {
     const progress = file.progress(); // value between 0 and 1
     const percent = Math.floor(progress * 100);
     const li = document.querySelector(`li.upload-progress-item[data-upload-index="${file.uniqueIdentifier}"]`);
     if (li && li.progressBar) {
       if (percent < 99) {
         li.progressBar.style.width = percent + "%";
-        
+
         // Calculate elapsed time and speed.
         const elapsed = (Date.now() - li.startTime) / 1000;
         let speed = "";
@@ -491,7 +500,7 @@ function initResumableUpload() {
         li.progressBar.style.width = "100%";
         li.progressBar.innerHTML = '<i class="material-icons spinning" style="vertical-align: middle;">autorenew</i>';
       }
-      
+
       // Enable the pause/resume button once progress starts.
       const pauseResumeBtn = li.querySelector(".pause-resume-btn");
       if (pauseResumeBtn) {
@@ -499,8 +508,8 @@ function initResumableUpload() {
       }
     }
   });
-  
-  resumableInstance.on("fileSuccess", function(file, message) {
+
+  resumableInstance.on("fileSuccess", function (file, message) {
     // Try to parse JSON response
     let data;
     try {
@@ -508,18 +517,18 @@ function initResumableUpload() {
     } catch (e) {
       data = null;
     }
-  
+
     // 1) Soft‐fail CSRF? then update token & retry this file
     if (data && data.csrf_expired) {
       // Update global and Resumable headers
       window.csrfToken = data.csrf_token;
       resumableInstance.opts.headers['X-CSRF-Token'] = data.csrf_token;
-      resumableInstance.opts.query.upload_token        = data.csrf_token;
+      resumableInstance.opts.query.upload_token = data.csrf_token;
       // Retry this chunk/file
       file.retry();
-      return; 
+      return;
     }
-  
+
     // 2) Otherwise treat as real success:
     const li = document.querySelector(
       `li.upload-progress-item[data-upload-index="${file.uniqueIdentifier}"]`
@@ -531,13 +540,13 @@ function initResumableUpload() {
       const pauseResumeBtn = li.querySelector(".pause-resume-btn");
       if (pauseResumeBtn) pauseResumeBtn.style.display = "none";
       const removeBtn = li.querySelector(".remove-file-btn");
-      if (removeBtn)   removeBtn.style.display = "none";
+      if (removeBtn) removeBtn.style.display = "none";
       setTimeout(() => li.remove(), 5000);
     }
-  
+
     loadFileList(window.currentFolder);
   });
-  
+
 
 
   resumableInstance.on("fileError", function (file, message) {
@@ -637,7 +646,7 @@ function submitFiles(allFiles) {
       } catch (e) {
         jsonResponse = null;
       }
-    
+
       // ─── Soft-fail CSRF: retry this upload ───────────────────────
       if (jsonResponse && jsonResponse.csrf_expired) {
         console.warn("CSRF expired during upload, retrying chunk", file.uploadIndex);
@@ -650,10 +659,10 @@ function submitFiles(allFiles) {
         xhr.send(formData);
         return;  // skip the "finishedCount++" and error/success logic for now
       }
-    
+
       // ─── Normal success/error handling ────────────────────────────  
       const li = progressElements[file.uploadIndex];
-    
+
       if (xhr.status >= 200 && xhr.status < 300 && (!jsonResponse || !jsonResponse.error)) {
         // real success
         if (li) {
@@ -662,6 +671,7 @@ function submitFiles(allFiles) {
           if (li.removeBtn) li.removeBtn.style.display = "none";
         }
         uploadResults[file.uploadIndex] = true;
+
       } else {
         // real failure
         if (li) {
@@ -681,12 +691,17 @@ function submitFiles(allFiles) {
           }
         }, 5000);
       }
-    
+
       // ─── Only now count this chunk as finished ───────────────────
       finishedCount++;
-      if (finishedCount === allFiles.length) {
-        refreshFileList(allFiles, uploadResults, progressElements);
-      }
+if (finishedCount === allFiles.length) {
+  const succeededCount = uploadResults.filter(Boolean).length;
+  const failedCount = allFiles.length - succeededCount;
+
+  setTimeout(() => {
+    refreshFileList(allFiles, uploadResults, progressElements);
+  }, 250);
+}
     });
 
     xhr.addEventListener("error", function () {
@@ -699,6 +714,9 @@ function submitFiles(allFiles) {
       finishedCount++;
       if (finishedCount === allFiles.length) {
         refreshFileList(allFiles, uploadResults, progressElements);
+        // Immediate summary toast based on actual XHR outcomes
+        const succeededCount = uploadResults.filter(Boolean).length;
+        const failedCount = allFiles.length - succeededCount;
       }
     });
 
@@ -725,17 +743,30 @@ function submitFiles(allFiles) {
     loadFileList(folderToUse)
       .then(serverFiles => {
         initFileActions();
-        serverFiles = (serverFiles || []).map(item => item.name.trim().toLowerCase());
+        // Be tolerant to API shapes: string or object with name/fileName/filename
+        serverFiles = (serverFiles || [])
+          .map(item => {
+            if (typeof item === 'string') return item;
+            const n = item?.name ?? item?.fileName ?? item?.filename ?? '';
+            return String(n);
+          })
+          .map(s => s.trim().toLowerCase())
+          .filter(Boolean);
         let overallSuccess = true;
+        let succeeded = 0;
         allFiles.forEach(file => {
           const clientFileName = file.name.trim().toLowerCase();
           const li = progressElements[file.uploadIndex];
-          if (!uploadResults[file.uploadIndex] || !serverFiles.includes(clientFileName)) {
+          const hadRelative = !!(file.webkitRelativePath || file.customRelativePath);
+          if (!uploadResults[file.uploadIndex] || (!hadRelative && !serverFiles.includes(clientFileName))) {
             if (li) {
               li.progressBar.innerText = "Error";
             }
             overallSuccess = false;
+            
           } else if (li) {
+            succeeded++;
+            
             // Schedule removal of successful file entry after 5 seconds.
             setTimeout(() => {
               li.remove();
@@ -757,9 +788,12 @@ function submitFiles(allFiles) {
             }, 5000);
           }
         });
-        
+
         if (!overallSuccess) {
-          showToast("Some files failed to upload. Please check the list.");
+          const failed = allFiles.length - succeeded;
+          showToast(`${failed} file(s) failed, ${succeeded} succeeded. Please check the list.`);
+        } else {
+          showToast(`${succeeded} file succeeded. Please check the list.`);
         }
       })
       .catch(error => {
@@ -768,6 +802,7 @@ function submitFiles(allFiles) {
       })
       .finally(() => {
         loadFolderTree(window.currentFolder);
+        
       });
   }
 }

public/js/version.js

@@ -0,0 +1,2 @@
+// generated by CI
+window.APP_VERSION = 'v1.6.8';

public/webdav.php

@@ -13,56 +13,62 @@ if (
 }
 
 // ─── 1) Bootstrap & load models ─────────────────────────────────────────────
-require_once __DIR__ . '/../config/config.php';        // UPLOAD_DIR, META_DIR, DATE_TIME_FORMAT
+require_once __DIR__ . '/../config/config.php';        // UPLOAD_DIR, META_DIR, loadUserPermissions(), etc.
 require_once __DIR__ . '/../vendor/autoload.php';      // Composer & SabreDAV
-require_once __DIR__ . '/../src/models/AuthModel.php'; // AuthModel::authenticate(), getUserRole(), loadFolderPermission()
-require_once __DIR__ . '/../src/models/AdminModel.php'; // AdminModel::getConfig()
+require_once __DIR__ . '/../src/models/AuthModel.php'; // AuthModel::authenticate(), getUserRole()
+require_once __DIR__ . '/../src/models/AdminModel.php';// AdminModel::getConfig()
+require_once __DIR__ . '/../src/lib/ACL.php';          // ACL checks
+require_once __DIR__ . '/../src/webdav/CurrentUser.php';
 
 // ─── 1.1) Global WebDAV feature toggle ──────────────────────────────────────
-$adminConfig   = AdminModel::getConfig();
-$enableWebDAV  = isset($adminConfig['enableWebDAV']) && $adminConfig['enableWebDAV'];
+$adminConfig  = AdminModel::getConfig();
+$enableWebDAV = isset($adminConfig['enableWebDAV']) && $adminConfig['enableWebDAV'];
 if (!$enableWebDAV) {
     header('HTTP/1.1 403 Forbidden');
     echo 'WebDAV access is currently disabled by administrator.';
     exit;
 }
 
-// ─── 2) Load WebDAV directory implementation ──────────────────────────
+// ─── 2) Load WebDAV directory implementation (ACL-aware) ────────────────────
 require_once __DIR__ . '/../src/webdav/FileRiseDirectory.php';
+
 use Sabre\DAV\Server;
 use Sabre\DAV\Auth\Backend\BasicCallBack;
 use Sabre\DAV\Auth\Plugin          as AuthPlugin;
 use Sabre\DAV\Locks\Plugin         as LocksPlugin;
 use Sabre\DAV\Locks\Backend\File   as LocksFileBackend;
 use FileRise\WebDAV\FileRiseDirectory;
+use FileRise\WebDAV\CurrentUser;
 
-// ─── 3) HTTP‑Basic backend ─────────────────────────────────────────────────
+// ─── 3) HTTP-Basic backend (delegates to your AuthModel) ────────────────────
 $authBackend = new BasicCallBack(function(string $user, string $pass) {
     return \AuthModel::authenticate($user, $pass) !== false;
 });
 $authPlugin = new AuthPlugin($authBackend, 'FileRise');
 
-// ─── 4) Determine user scope ────────────────────────────────────────────────
-$user       = $_SERVER['PHP_AUTH_USER'] ?? '';
-$isAdmin    = (\AuthModel::getUserRole($user) === '1');
-$folderOnly = (bool)\AuthModel::loadFolderPermission($user);
-
-if ($isAdmin || !$folderOnly) {
-    // Admins (or users without folder-only restriction) see the full /uploads
-    $rootPath = rtrim(UPLOAD_DIR, '/\\');
-} else {
-    // Folder‑only users see only /uploads/{username}
-    $rootPath = rtrim(UPLOAD_DIR, '/\\') . DIRECTORY_SEPARATOR . $user;
-    if (!is_dir($rootPath)) {
-        mkdir($rootPath, 0755, true);
-    }
+// ─── 4) Resolve authenticated user + perms ──────────────────────────────────
+$user = $_SERVER['PHP_AUTH_USER'] ?? '';
+if ($user === '') {
+    header('HTTP/1.1 401 Unauthorized');
+    header('WWW-Authenticate: Basic realm="FileRise"');
+    echo 'Authentication required.';
+    exit;
 }
 
-// ─── 5) Spin up SabreDAV ────────────────────────────────────────────────────
+$perms   = is_callable('loadUserPermissions') ? (loadUserPermissions($user) ?: []) : [];
+$isAdmin = (\AuthModel::getUserRole($user) === '1');
+
+// set for metadata attribution in WebDAV writes
+CurrentUser::set($user);
+
+// ─── 5) Mount the real uploads root; ACL filters everything at node level ───
+$rootPath = rtrim(UPLOAD_DIR, '/\\');
+
 $server = new Server([
-    new FileRiseDirectory($rootPath, $user, $folderOnly),
+    new FileRiseDirectory($rootPath, $user, $isAdmin, $perms),
 ]);
 
+// Auth + Locks
 $server->addPlugin($authPlugin);
 $server->addPlugin(
     new LocksPlugin(
@@ -70,5 +76,8 @@ $server->addPlugin(
     )
 );
 
+// Base URI (adjust if you serve from a subdir or rewrite rule)
 $server->setBaseUri('/webdav.php/');
+
+// Execute
 $server->exec();

src/controllers/AdminController.php

@@ -5,148 +5,57 @@ require_once __DIR__ . '/../../config/config.php';
 require_once PROJECT_ROOT . '/src/models/AdminModel.php';
 
 class AdminController
-{
-
-    /**
-     * @OA\Get(
-     *     path="/api/admin/getConfig.php",
-     *     summary="Retrieve admin configuration",
-     *     description="Returns the admin configuration settings, decrypting the configuration file and providing default values if not set.",
-     *     operationId="getAdminConfig",
-     *     tags={"Admin"},
-     *     @OA\Response(
-     *         response=200,
-     *         description="Configuration retrieved successfully",
-     *         @OA\JsonContent(
-     *             type="object",
-     *             @OA\Property(property="header_title", type="string", example="FileRise"),
-     *             @OA\Property(
-     *                 property="oidc",
-     *                 type="object",
-     *                 @OA\Property(property="providerUrl", type="string", example="https://your-oidc-provider.com"),
-     *                 @OA\Property(property="clientId", type="string", example="YOUR_CLIENT_ID"),
-     *                 @OA\Property(property="clientSecret", type="string", example="YOUR_CLIENT_SECRET"),
-     *                 @OA\Property(property="redirectUri", type="string", example="https://yourdomain.com/auth.php?oidc=callback")
-     *             ),
-     *             @OA\Property(
-     *                 property="loginOptions",
-     *                 type="object",
-     *                 @OA\Property(property="disableFormLogin", type="boolean", example=false),
-     *                 @OA\Property(property="disableBasicAuth", type="boolean", example=false),
-     *                 @OA\Property(property="disableOIDCLogin", type="boolean", example=false)
-     *             ),
-     *             @OA\Property(property="globalOtpauthUrl", type="string", example=""),
-     *             @OA\Property(property="enableWebDAV", type="boolean", example=false),
-     *             @OA\Property(property="sharedMaxUploadSize", type="integer", example=52428800)
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=500,
-     *         description="Failed to decrypt configuration or server error"
-     *     )
-     * )
-     *
-     * Retrieves the admin configuration settings.
-     *
-     * @return void Outputs a JSON response with configuration data.
-     */
+{ 
     public function getConfig(): void
-    {
-        header('Content-Type: application/json');
+{
+    header('Content-Type: application/json');
 
-        // Require authenticated admin to read config (prevents information disclosure)
-        if (
-            empty($_SESSION['authenticated']) || $_SESSION['authenticated'] !== true ||
-            empty($_SESSION['isAdmin'])
-        ) {
-            http_response_code(403);
-            echo json_encode(['error' => 'Unauthorized access.']);
-            exit;
-        }
-
-        $config = AdminModel::getConfig();
-        if (isset($config['error'])) {
-            http_response_code(500);
-            echo json_encode(['error' => $config['error']]);
-            exit;
-        }
-    
-        // Build a safe subset for the front-end
-        $safe = [
-          'header_title'        => $config['header_title'] ?? '',
-          'loginOptions'        => $config['loginOptions'] ?? [],
-          'globalOtpauthUrl'    => $config['globalOtpauthUrl'] ?? '',
-          'enableWebDAV'        => $config['enableWebDAV'] ?? false,
-          'sharedMaxUploadSize' => $config['sharedMaxUploadSize'] ?? 0,
-          'oidc' => [
-            'providerUrl' => $config['oidc']['providerUrl'] ?? '',
-            'redirectUri' => $config['oidc']['redirectUri'] ?? '',
-            // clientSecret and clientId never exposed here
-          ],
-        ];
-    
-        echo json_encode($safe);
+    // Load raw config (no disclosure yet)
+    $config = AdminModel::getConfig();
+    if (isset($config['error'])) {
+        http_response_code(500);
+        echo json_encode(['error' => $config['error']]);
         exit;
     }
 
-    /**
-     * @OA\Put(
-     *     path="/api/admin/updateConfig.php",
-     *     summary="Update admin configuration",
-     *     description="Updates the admin configuration settings. Requires admin privileges and a valid CSRF token.",
-     *     operationId="updateAdminConfig",
-     *     tags={"Admin"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"header_title", "oidc", "loginOptions"},
-     *             @OA\Property(property="header_title", type="string", example="FileRise"),
-     *             @OA\Property(
-     *                 property="oidc",
-     *                 type="object",
-     *                 @OA\Property(property="providerUrl", type="string", example="https://your-oidc-provider.com"),
-     *                 @OA\Property(property="clientId", type="string", example="YOUR_CLIENT_ID"),
-     *                 @OA\Property(property="clientSecret", type="string", example="YOUR_CLIENT_SECRET"),
-     *                 @OA\Property(property="redirectUri", type="string", example="https://yourdomain.com/api/auth/auth.php?oidc=callback")
-     *             ),
-     *             @OA\Property(
-     *                 property="loginOptions",
-     *                 type="object",
-     *                 @OA\Property(property="disableFormLogin", type="boolean", example=false),
-     *                 @OA\Property(property="disableBasicAuth", type="boolean", example=false),
-     *                 @OA\Property(property="disableOIDCLogin", type="boolean", example=false)
-     *             ),
-     *             @OA\Property(property="globalOtpauthUrl", type="string", example=""),
-     *             @OA\Property(property="enableWebDAV", type="boolean", example=false),
-     *             @OA\Property(property="sharedMaxUploadSize", type="integer", example=52428800)
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="Configuration updated successfully",
-     *         @OA\JsonContent(
-     *             type="object",
-     *             @OA\Property(property="success", type="string", example="Configuration updated successfully.")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request (e.g., invalid input, incomplete OIDC configuration)"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Unauthorized (user not admin or invalid CSRF token)"
-     *     ),
-     *     @OA\Response(
-     *         response=500,
-     *         description="Server error (failed to write configuration file)"
-     *     )
-     * )
-     *
-     * Updates the admin configuration settings.
-     *
-     * @return void Outputs a JSON response indicating success or failure.
-     */
+    // Minimal, safe subset for all callers (unauth users and regular users)
+    $public = [
+        'header_title'        => $config['header_title'] ?? 'FileRise',
+        'loginOptions'        => [
+            // expose only what the login page / header needs
+            'disableFormLogin'  => (bool)($config['loginOptions']['disableFormLogin']  ?? false),
+            'disableBasicAuth'  => (bool)($config['loginOptions']['disableBasicAuth']  ?? false),
+            'disableOIDCLogin'  => (bool)($config['loginOptions']['disableOIDCLogin']  ?? false),
+        ],
+        'globalOtpauthUrl'    => $config['globalOtpauthUrl'] ?? '',
+        'enableWebDAV'        => (bool)($config['enableWebDAV'] ?? false),
+        'sharedMaxUploadSize' => (int)($config['sharedMaxUploadSize'] ?? 0),
+
+        'oidc' => [
+            'providerUrl' => (string)($config['oidc']['providerUrl'] ?? ''),
+            'redirectUri' => (string)($config['oidc']['redirectUri'] ?? ''),
+            // never expose clientId / clientSecret
+        ],
+    ];
+
+    $isAdmin = !empty($_SESSION['authenticated']) && !empty($_SESSION['isAdmin']);
+
+    if ($isAdmin) {
+        // Add admin-only fields (used by Admin Panel UI)
+        $adminExtra = [
+            'loginOptions' => array_merge($public['loginOptions'], [
+                'authBypass'     => (bool)($config['loginOptions']['authBypass']     ?? false),
+                'authHeaderName' => (string)($config['loginOptions']['authHeaderName'] ?? 'X-Remote-User'),
+            ]),
+        ];
+        echo json_encode(array_merge($public, $adminExtra));
+        return;
+    }
+
+    // Non-admins / unauthenticated: only the public subset
+    echo json_encode($public);
+}
+
     public function updateConfig(): void
     {
         header('Content-Type: application/json');

src/controllers/AuthController.php

@@ -13,53 +13,6 @@ use Jumbojett\OpenIDConnectClient;
 class AuthController
 {
 
-    /**
-     * @OA\Post(
-     *     path="/api/auth/auth.php",
-     *     summary="Authenticate user",
-     *     description="Handles user authentication via OIDC or form-based credentials. For OIDC flows, processes callbacks; otherwise, performs standard authentication with optional TOTP verification.",
-     *     operationId="authUser",
-     *     tags={"Auth"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"username", "password"},
-     *             @OA\Property(property="username", type="string", example="johndoe"),
-     *             @OA\Property(property="password", type="string", example="secretpassword"),
-     *             @OA\Property(property="remember_me", type="boolean", example=true),
-     *             @OA\Property(property="totp_code", type="string", example="123456")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="Login successful; returns user info and status",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="status", type="string", example="ok"),
-     *             @OA\Property(property="success", type="string", example="Login successful"),
-     *             @OA\Property(property="username", type="string", example="johndoe"),
-     *             @OA\Property(property="isAdmin", type="boolean", example=true)
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request (e.g., missing credentials)"
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized (e.g., invalid credentials, too many attempts)"
-     *     ),
-     *     @OA\Response(
-     *         response=429,
-     *         description="Too many failed login attempts"
-     *     )
-     * )
-     *
-     * Handles user authentication via OIDC or form-based login.
-     *
-     * @return void Redirects on success or outputs JSON error.
-     */
-    // in src/controllers/AuthController.php
-
     public function auth(): void
     {
         header('Content-Type: application/json');
@@ -307,40 +260,6 @@ class AuthController
         exit();
     }
 
-    /**
-     * @OA\Get(
-     *     path="/api/auth/checkAuth.php",
-     *     summary="Check authentication status",
-     *     description="Checks if the current session is authenticated. If the users file is missing or empty, returns a setup flag. Also returns information about admin privileges, TOTP status, and folder-only access.",
-     *     operationId="checkAuth",
-     *     tags={"Auth"},
-     *     @OA\Response(
-     *         response=200,
-     *         description="Returns authentication status and user details",
-     *         @OA\JsonContent(
-     *             type="object",
-     *             @OA\Property(property="authenticated", type="boolean", example=true),
-     *             @OA\Property(property="isAdmin", type="boolean", example=true),
-     *             @OA\Property(property="totp_enabled", type="boolean", example=false),
-     *             @OA\Property(property="username", type="string", example="johndoe"),
-     *             @OA\Property(property="folderOnly", type="boolean", example=false)
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="Setup mode (if the users file is missing or empty)",
-     *         @OA\JsonContent(
-     *             type="object",
-     *             @OA\Property(property="setup", type="boolean", example=true)
-     *         )
-     *     )
-     * )
-     *
-     * Checks whether the user is authenticated or if the system is in setup mode.
-     *
-     * @return void Outputs a JSON response with authentication details.
-     */
-
     public function checkAuth(): void
     {
 
@@ -427,28 +346,6 @@ class AuthController
         exit();
     }
 
-    /**
-     * @OA\Get(
-     *     path="/api/auth/token.php",
-     *     summary="Retrieve CSRF token and share URL",
-     *     description="Returns the current CSRF token along with the configured share URL.",
-     *     operationId="getToken",
-     *     tags={"Auth"},
-     *     @OA\Response(
-     *         response=200,
-     *         description="CSRF token and share URL",
-     *         @OA\JsonContent(
-     *             type="object",
-     *             @OA\Property(property="csrf_token", type="string", example="0123456789abcdef..."),
-     *             @OA\Property(property="share_url", type="string", example="https://yourdomain.com/share.php")
-     *         )
-     *     )
-     * )
-     *
-     * Returns the CSRF token and share URL.
-     *
-     * @return void Outputs the JSON response.
-     */
     public function getToken(): void
     {
         // 1) Ensure session and CSRF token exist
@@ -468,31 +365,6 @@ class AuthController
         exit;
     }
 
-    /**
-     * @OA\Get(
-     *     path="/api/auth/login_basic.php",
-     *     summary="Authenticate using HTTP Basic Authentication",
-     *     description="Performs HTTP Basic authentication. If credentials are missing, sends a 401 response prompting for Basic auth. On valid credentials, optionally handles TOTP verification and finalizes session login.",
-     *     operationId="loginBasic",
-     *     tags={"Auth"},
-     *     @OA\Response(
-     *         response=200,
-     *         description="Login successful; redirects to index.html",
-     *         @OA\JsonContent(
-     *             type="object",
-     *             @OA\Property(property="success", type="string", example="Login successful")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized due to missing credentials or invalid credentials."
-     *     )
-     * )
-     *
-     * Handles HTTP Basic authentication (with optional TOTP) and logs the user in.
-     *
-     * @return void Redirects on success or sends a 401 header.
-     */
     public function loginBasic(): void
     {
         // Set header for plain-text or JSON as needed.
@@ -550,27 +422,6 @@ class AuthController
         exit;
     }
 
-    /**
-     * @OA\Post(
-     *     path="/api/auth/logout.php",
-     *     summary="Logout user",
-     *     description="Clears the session, removes persistent login tokens, and redirects the user to the login page.",
-     *     operationId="logoutUser",
-     *     tags={"Auth"},
-     *     @OA\Response(
-     *         response=302,
-     *         description="Redirects to the login page with a logout flag."
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized"
-     *     )
-     * )
-     *
-     * Logs the user out by clearing session data, removing persistent tokens, and destroying the session.
-     *
-     * @return void Redirects to index.html with a logout flag.
-     */
     public function logout(): void
     {
         // Retrieve headers and check CSRF token.

src/controllers/UploadController.php

@@ -2,198 +2,107 @@
 // src/controllers/UploadController.php
 
 require_once __DIR__ . '/../../config/config.php';
+require_once PROJECT_ROOT . '/src/lib/ACL.php';
 require_once PROJECT_ROOT . '/src/models/UploadModel.php';
 
 class UploadController {
 
-    /**
-     * @OA\Post(
-     *     path="/api/upload/upload.php",
-     *     summary="Handle file upload",
-     *     description="Handles file uploads for both chunked and non-chunked (full) uploads. Validates CSRF, user authentication, and permissions, and processes file uploads accordingly. On success, returns a JSON status for chunked uploads or redirects for full uploads.",
-     *     operationId="handleUpload",
-     *     tags={"Uploads"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         description="Multipart form data for file upload. For chunked uploads, include fields like 'resumableChunkNumber', 'resumableTotalChunks', 'resumableIdentifier', 'resumableFilename', etc.",
-     *         @OA\MediaType(
-     *             mediaType="multipart/form-data",
-     *             @OA\Schema(
-     *                 required={"token", "fileToUpload"},
-     *                 @OA\Property(property="token", type="string", description="Share token or upload token."),
-     *                 @OA\Property(
-     *                     property="fileToUpload",
-     *                     type="string",
-     *                     format="binary",
-     *                     description="The file to upload."
-     *                 ),
-     *                 @OA\Property(property="resumableChunkNumber", type="integer", description="Chunk number for chunked uploads."),
-     *                 @OA\Property(property="resumableTotalChunks", type="integer", description="Total number of chunks."),
-     *                 @OA\Property(property="resumableFilename", type="string", description="Original filename."),
-     *                 @OA\Property(property="folder", type="string", description="Target folder (default 'root').")
-     *             )
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="File uploaded successfully (or chunk uploaded status).",
-     *         @OA\JsonContent(
-     *             type="object",
-     *             @OA\Property(property="success", type="string", example="File uploaded successfully"),
-     *             @OA\Property(property="newFilename", type="string", example="5f2d7c123a_example.png"),
-     *             @OA\Property(property="status", type="string", example="chunk uploaded")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=302,
-     *         description="Redirection on full upload success."
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request (e.g., missing file, invalid parameters)"
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Forbidden (e.g., invalid CSRF token, upload disabled)"
-     *     ),
-     *     @OA\Response(
-     *         response=500,
-     *         description="Server error during file processing"
-     *     )
-     * )
-     *
-     * Handles file uploads, both chunked and full, and redirects upon success.
-     *
-     * @return void Outputs JSON response (for chunked uploads) or redirects on successful full upload.
-     */
     public function handleUpload(): void {
         header('Content-Type: application/json');
-  
-        //
-        // 1) CSRF – pull from header or POST fields
-        //
-        $headersArr = array_change_key_case(getallheaders(), CASE_LOWER);
+    
+        // ---- 1) CSRF (header or form field) ----
+        $headersArr = array_change_key_case(getallheaders() ?: [], CASE_LOWER);
         $received = '';
         if (!empty($headersArr['x-csrf-token'])) {
             $received = trim($headersArr['x-csrf-token']);
         } elseif (!empty($_POST['csrf_token'])) {
             $received = trim($_POST['csrf_token']);
         } elseif (!empty($_POST['upload_token'])) {
+            // legacy alias
             $received = trim($_POST['upload_token']);
         }
     
-        // 1a) If it doesn’t match, soft-fail: send new token and let client retry
         if (!isset($_SESSION['csrf_token']) || $received !== $_SESSION['csrf_token']) {
-            // regenerate
+            // Soft-fail so client can retry with refreshed token
             $_SESSION['csrf_token'] = bin2hex(random_bytes(32));
-            // tell client “please retry with this new token”
             http_response_code(200);
             echo json_encode([
-              'csrf_expired' => true,
-              'csrf_token'   => $_SESSION['csrf_token']
+                'csrf_expired' => true,
+                'csrf_token'   => $_SESSION['csrf_token']
             ]);
-            exit;
+            return;
         }
     
-        //
-        // 2) Auth checks
-        //
-        if (empty($_SESSION['authenticated']) || $_SESSION['authenticated'] !== true) {
+        // ---- 2) Auth + account-level flags ----
+        if (empty($_SESSION['authenticated'])) {
             http_response_code(401);
-            echo json_encode(["error" => "Unauthorized"]);
-            exit;
-        }
-        $userPerms = loadUserPermissions($_SESSION['username']);
-        if (!empty($userPerms['disableUpload'])) {
-            http_response_code(403);
-            echo json_encode(["error" => "Upload disabled for this user."]);
-            exit;
+            echo json_encode(['error' => 'Unauthorized']);
+            return;
         }
     
-        //
-        // 3) Delegate the actual file handling
-        //
+        $username  = (string)($_SESSION['username'] ?? '');
+        $userPerms = loadUserPermissions($username) ?: [];
+        $isAdmin   = ACL::isAdmin($userPerms);
+    
+        // Admins should never be blocked by account-level "disableUpload"
+        if (!$isAdmin && !empty($userPerms['disableUpload'])) {
+            http_response_code(403);
+            echo json_encode(['error' => 'Upload disabled for this user.']);
+            return;
+        }
+    
+        // ---- 3) Folder-level WRITE permission (ACL) ----
+        // Always require client to send the folder; fall back to GET if needed.
+        $folderParam   = isset($_POST['folder']) ? (string)$_POST['folder'] : (isset($_GET['folder']) ? (string)$_GET['folder'] : 'root');
+        $targetFolder  = ACL::normalizeFolder($folderParam);
+    
+        // Admins bypass folder canWrite checks
+        if (!$isAdmin && !ACL::canUpload($username, $userPerms, $targetFolder)) {
+            http_response_code(403);
+            echo json_encode(['error' => 'Forbidden: no write access to folder "'.$targetFolder.'".']);
+            return;
+        }
+    
+        // ---- 4) Delegate to model (actual file/chunk processing) ----
+        // (Optionally re-check in UploadModel before finalizing.)
         $result = UploadModel::handleUpload($_POST, $_FILES);
     
-        //
-        // 4) Respond
-        //
+        // ---- 5) Response ----
         if (isset($result['error'])) {
             http_response_code(400);
             echo json_encode($result);
-            exit;
+            return;
         }
         if (isset($result['status'])) {
+            // e.g., {"status":"chunk uploaded"}
             echo json_encode($result);
-            exit;
+            return;
         }
     
-        // full‐upload redirect
-        $_SESSION['upload_message'] = "File uploaded successfully.";
-        exit;
+        echo json_encode([
+            'success'     => 'File uploaded successfully',
+            'newFilename' => $result['newFilename'] ?? null
+        ]);
     }
-
-    /**
-     * @OA\Post(
-     *     path="/api/upload/removeChunks.php",
-     *     summary="Remove chunked upload temporary directory",
-     *     description="Removes the temporary directory used for chunked uploads, given a folder name matching the expected resumable pattern.",
-     *     operationId="removeChunks",
-     *     tags={"Uploads"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"folder"},
-     *             @OA\Property(property="folder", type="string", example="resumable_myupload123")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="Temporary folder removed successfully",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="success", type="boolean", example=true),
-     *             @OA\Property(property="message", type="string", example="Temporary folder removed.")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Invalid input (e.g., missing folder or invalid folder name)"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Invalid CSRF token"
-     *     )
-     * )
-     *
-     * Removes the temporary upload folder for chunked uploads.
-     *
-     * @return void Outputs a JSON response.
-     */
+    
     public function removeChunks(): void {
         header('Content-Type: application/json');
-        
-        // CSRF Protection: Validate token from POST data.
+
         $receivedToken = isset($_POST['csrf_token']) ? trim($_POST['csrf_token']) : '';
-        if ($receivedToken !== $_SESSION['csrf_token']) {
+        if ($receivedToken !== ($_SESSION['csrf_token'] ?? '')) {
             http_response_code(403);
-            echo json_encode(["error" => "Invalid CSRF token"]);
-            exit;
+            echo json_encode(['error' => 'Invalid CSRF token']);
+            return;
         }
-        
-        // Check that the folder parameter is provided.
+
         if (!isset($_POST['folder'])) {
             http_response_code(400);
-            echo json_encode(["error" => "No folder specified"]);
-            exit;
+            echo json_encode(['error' => 'No folder specified']);
+            return;
         }
-        
-        $folder = $_POST['folder'];
+
+        $folder = (string)$_POST['folder'];
         $result = UploadModel::removeChunks($folder);
         echo json_encode($result);
-        exit;
     }
 }

src/controllers/UserController.php

@@ -60,16 +60,37 @@ class UserController
 
     /** Enforce admin (401). */
     private static function requireAdmin(): void
-    {
-        self::requireAuth();
-        if (empty($_SESSION['isAdmin']) || $_SESSION['isAdmin'] !== true) {
-            http_response_code(401);
-            header('Content-Type: application/json');
-            echo json_encode(['error' => 'Unauthorized']);
-            exit;
+{
+    self::requireAuth();
+
+    // Prefer the session flag
+    $isAdmin = (!empty($_SESSION['isAdmin']) && $_SESSION['isAdmin'] === true);
+
+    // Fallback: check the user’s role in storage (e.g., users.txt/DB)
+    if (!$isAdmin) {
+        $u = $_SESSION['username'] ?? '';
+        if ($u) {
+            try {
+                // UserModel::getUserRole($u) should return '1' for admins
+                $isAdmin = (UserModel::getUserRole($u) === '1');
+                if ($isAdmin) {
+                    // Normalize session so downstream ACL checks see admin
+                    $_SESSION['isAdmin'] = true;
+                }
+            } catch (\Throwable $e) {
+                // ignore and continue to deny
+            }
         }
     }
 
+    if (!$isAdmin) {
+        http_response_code(403);
+        header('Content-Type: application/json');
+        echo json_encode(['error' => 'Admin privileges required.']);
+        exit;
+    }
+}
+
     /** Enforce CSRF using X-CSRF-Token header (or csrfToken param as fallback). */
     private static function requireCsrf(): void
     {
@@ -101,31 +122,6 @@ class UserController
 
     /* ------------------------- End helpers -------------------------- */
 
-    /**
-     * @OA\Get(
-     *     path="/api/getUsers.php",
-     *     summary="Retrieve a list of users",
-     *     description="Returns a JSON array of users. Only available to authenticated admin users.",
-     *     operationId="getUsers",
-     *     tags={"Users"},
-     *     @OA\Response(
-     *         response=200,
-     *         description="Successful response with an array of users",
-     *         @OA\JsonContent(
-     *             type="array",
-     *             @OA\Items(
-     *                 type="object",
-     *                 @OA\Property(property="username", type="string", example="johndoe"),
-     *                 @OA\Property(property="role", type="string", example="admin")
-     *             )
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized: the user is not authenticated or is not an admin"
-     *     )
-     * )
-     */
     public function getUsers()
     {
         self::jsonHeaders();
@@ -137,39 +133,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Post(
-     *     path="/api/addUser.php",
-     *     summary="Add a new user",
-     *     description="Adds a new user to the system. In setup mode, the new user is automatically made admin.",
-     *     operationId="addUser",
-     *     tags={"Users"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"username", "password"},
-     *             @OA\Property(property="username", type="string", example="johndoe"),
-     *             @OA\Property(property="password", type="string", example="securepassword"),
-     *             @OA\Property(property="isAdmin", type="boolean", example=true)
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="User added successfully",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="success", type="string", example="User added successfully")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request"
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized"
-     *     )
-     * )
-     */
     public function addUser()
     {
         self::jsonHeaders();
@@ -237,41 +200,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Delete(
-     *     path="/api/removeUser.php",
-     *     summary="Remove a user",
-     *     description="Removes the specified user from the system. Cannot remove the currently logged-in user.",
-     *     operationId="removeUser",
-     *     tags={"Users"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"username"},
-     *             @OA\Property(property="username", type="string", example="johndoe")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="User removed successfully",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="success", type="string", example="User removed successfully")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request"
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Invalid CSRF token"
-     *     )
-     * )
-     */
     public function removeUser()
     {
         self::jsonHeaders();
@@ -301,24 +229,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Get(
-     *     path="/api/getUserPermissions.php",
-     *     summary="Retrieve user permissions",
-     *     description="Returns the permissions for the current user, or all permissions if the user is an admin.",
-     *     operationId="getUserPermissions",
-     *     tags={"Users"},
-     *     @OA\Response(
-     *         response=200,
-     *         description="Successful response with user permissions",
-     *         @OA\JsonContent(type="object")
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized"
-     *     )
-     * )
-     */
     public function getUserPermissions()
     {
         self::jsonHeaders();
@@ -329,51 +239,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Put(
-     *     path="/api/updateUserPermissions.php",
-     *     summary="Update user permissions",
-     *     description="Updates permissions for users. Only available to authenticated admin users.",
-     *     operationId="updateUserPermissions",
-     *     tags={"Users"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"permissions"},
-     *             @OA\Property(
-     *                 property="permissions",
-     *                 type="array",
-     *                 @OA\Items(
-     *                     type="object",
-     *                     @OA\Property(property="username", type="string", example="johndoe"),
-     *                     @OA\Property(property="folderOnly", type="boolean", example=true),
-     *                     @OA\Property(property="readOnly", type="boolean", example=false),
-     *                     @OA\Property(property="disableUpload", type="boolean", example=false)
-     *                 )
-     *             )
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="User permissions updated successfully",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="success", type="string", example="User permissions updated successfully.")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Invalid CSRF token"
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request"
-     *     )
-     * )
-     */
     public function updateUserPermissions()
     {
         self::jsonHeaders();
@@ -394,43 +259,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Post(
-     *     path="/api/changePassword.php",
-     *     summary="Change user password",
-     *     description="Allows an authenticated user to change their password by verifying the old password and updating to a new one.",
-     *     operationId="changePassword",
-     *     tags={"Users"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"oldPassword", "newPassword", "confirmPassword"},
-     *             @OA\Property(property="oldPassword", type="string", example="oldpass123"),
-     *             @OA\Property(property="newPassword", type="string", example="newpass456"),
-     *             @OA\Property(property="confirmPassword", type="string", example="newpass456")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="Password updated successfully",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="success", type="string", example="Password updated successfully.")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request"
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Invalid CSRF token"
-     *     )
-     * )
-     */
     public function changePassword()
     {
         self::jsonHeaders();
@@ -467,41 +295,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Put(
-     *     path="/api/updateUserPanel.php",
-     *     summary="Update user panel settings",
-     *     description="Updates user panel settings by disabling TOTP when not enabled. Accessible to authenticated users.",
-     *     operationId="updateUserPanel",
-     *     tags={"Users"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"totp_enabled"},
-     *             @OA\Property(property="totp_enabled", type="boolean", example=false)
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="User panel updated successfully",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="success", type="string", example="User panel updated: TOTP disabled")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=401,
-     *         description="Unauthorized"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Invalid CSRF token"
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request"
-     *     )
-     * )
-     */
     public function updateUserPanel()
     {
         self::jsonHeaders();
@@ -530,31 +323,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Put(
-     *     path="/api/totp_disable.php",
-     *     summary="Disable TOTP for the authenticated user",
-     *     description="Clears the TOTP secret from the users file for the current user.",
-     *     operationId="disableTOTP",
-     *     tags={"TOTP"},
-     *     @OA\Response(
-     *         response=200,
-     *         description="TOTP disabled successfully",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="success", type="boolean", example=true),
-     *             @OA\Property(property="message", type="string", example="TOTP disabled successfully.")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Not authenticated or invalid CSRF token"
-     *     ),
-     *     @OA\Response(
-     *         response=500,
-     *         description="Failed to disable TOTP"
-     *     )
-     * )
-     */
     public function disableTOTP()
     {
         self::jsonHeaders();
@@ -580,45 +348,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Post(
-     *     path="/api/totp_recover.php",
-     *     summary="Recover TOTP",
-     *     description="Verifies a recovery code to disable TOTP and finalize login.",
-     *     operationId="recoverTOTP",
-     *     tags={"TOTP"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"recovery_code"},
-     *             @OA\Property(property="recovery_code", type="string", example="ABC123DEF456")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="Recovery successful",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="status", type="string", example="ok")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Invalid input or recovery code"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Invalid CSRF token"
-     *     ),
-     *     @OA\Response(
-     *         response=405,
-     *         description="Method not allowed"
-     *     ),
-     *     @OA\Response(
-     *         response=429,
-     *         description="Too many attempts"
-     *     )
-     * )
-     */
     public function recoverTOTP()
     {
         self::jsonHeaders();
@@ -660,35 +389,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Post(
-     *     path="/api/totp_saveCode.php",
-     *     summary="Generate and save a new TOTP recovery code",
-     *     description="Generates a new TOTP recovery code for the authenticated user, stores its hash, and returns the plain text recovery code.",
-     *     operationId="totpSaveCode",
-     *     tags={"TOTP"},
-     *     @OA\Response(
-     *         response=200,
-     *         description="Recovery code generated successfully",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="status", type="string", example="ok"),
-     *             @OA\Property(property="recoveryCode", type="string", example="ABC123DEF456")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Invalid CSRF token or unauthorized"
-     *     ),
-     *     @OA\Response(
-     *         response=405,
-     *         description="Method not allowed"
-     *     )
-     * )
-     */
     public function saveTOTPRecoveryCode()
     {
         self::jsonHeaders();
@@ -718,30 +418,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Get(
-     *     path="/api/totp_setup.php",
-     *     summary="Set up TOTP and generate a QR code",
-     *     description="Generates (or retrieves) the TOTP secret for the user and builds a QR code image for scanning.",
-     *     operationId="setupTOTP",
-     *     tags={"TOTP"},
-     *     @OA\Response(
-     *         response=200,
-     *         description="QR code image for TOTP setup",
-     *         @OA\MediaType(
-     *             mediaType="image/png"
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Unauthorized or invalid CSRF token"
-     *     ),
-     *     @OA\Response(
-     *         response=500,
-     *         description="Server error"
-     *     )
-     * )
-     */
     public function setupTOTP()
     {
         // Allow access if authenticated OR pending TOTP
@@ -778,42 +454,6 @@ class UserController
         exit;
     }
 
-    /**
-     * @OA\Post(
-     *     path="/api/totp_verify.php",
-     *     summary="Verify TOTP code",
-     *     description="Verifies a TOTP code and completes login for pending users or validates TOTP for setup verification.",
-     *     operationId="verifyTOTP",
-     *     tags={"TOTP"},
-     *     @OA\RequestBody(
-     *         required=true,
-     *         @OA\JsonContent(
-     *             required={"totp_code"},
-     *             @OA\Property(property="totp_code", type="string", example="123456")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=200,
-     *         description="TOTP successfully verified",
-     *         @OA\JsonContent(
-     *             @OA\Property(property="status", type="string", example="ok"),
-     *             @OA\Property(property="message", type="string", example="Login successful")
-     *         )
-     *     ),
-     *     @OA\Response(
-     *         response=400,
-     *         description="Bad Request (e.g., invalid input)"
-     *     ),
-     *     @OA\Response(
-     *         response=403,
-     *         description="Not authenticated or invalid CSRF token"
-     *     ),
-     *     @OA\Response(
-     *         response=429,
-     *         description="Too many attempts. Try again later."
-     *     )
-     * )
-     */
     public function verifyTOTP()
     {
         header('Content-Type: application/json');