pigeondrop 0.0.0-stage → 1.6.1

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# What's new
+
+## v1.6.1 — 2 November 2026
+
+- Changed: **The page heading reads Pigeonhole.** It is no longer shown in capitals.
+
+## v1.6.0 — 2 November 2026
+
+- New: **Filter the file list by name.** Type in the box above the list to show only the files and folders whose names contain what you typed.
+
+## v1.5.1 — 16 October 2026
+
+- Changed: **Pigeonhole's code now lives at github.com/cventour/pigeondrop.** Old links and install commands still work.
+
+## v1.5.0 — 16 October 2026
+
+- New: **Run it with npx.** `npx pigeondrop` starts Pigeonhole in the folder you are in, with nothing to install. Its files and settings stay in that folder.
+
+## v1.4.0 — 16 October 2026
+
+- New: **Pigeonhole has an icon.** It shows in the browser tab and beside the page heading.
+
+## v1.3.0 — 14 October 2026
+
+- New: **Verify the certificate can be turned off.** For a scanner with a self-signed certificate on a network you trust, the connection is still encrypted.
+- Changed: **TLS failures say why.** Test connection, uploads and Save explain what is wrong with the scanner's certificate or connection and what to change.
+
+## v1.2.0 — 14 October 2026
+
+- New: **Scan over ICAPS.** Settings has a TLS option for ICAP servers that only accept encrypted connections. The server's certificate is checked, and the test explains when it is not trusted.
+
+## v1.1.1 — 2 October 2026
+
+- Fixed: **Settings could not be saved when Pigeonhole runs as a hardened systemd service.** They are now kept in the service's own state folder, and if a folder cannot be written the message says what to change.
+
+## v1.1.0 — 2 October 2026
+
+- New: **Scan uploads with an ICAP server.** Open Settings, enter the server, and every upload is checked before it appears in the list. Files the scanner blocks are discarded and the threat is named.
+- New: **Test connection.** Settings can check a server before you save it, including whether it is able to scan.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christos Ventouris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,525 @@
-# Temporary Holding Version
+<img src="icon.svg" width="88" alt="Pigeonhole icon: a wall of arched pigeonholes, one holding a letter">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Pigeonhole
+
+A file pigeonhole you can stand up in a minute. Put files in, let people take
+them out, and take back whatever they leave you.
+
+Useful when a group needs a shared drop: distributing builds, installers or
+documents to a handful of machines, and collecting files back from them
+without email, chat attachments or a cloud account.
+
+Drag files in or browse for them, with a progress bar on each. Browse folders,
+rename, delete, download, make folders. Tick several items to download them
+together; a folder, or any selection of more than one file, arrives as a
+single zip, streamed as it is built. Optionally, every upload is checked by
+an ICAP virus scanner before it appears. That is the whole feature list and it
+is meant to stay short.
+
+**No dependencies.** Node's standard library and nothing else. No install
+step, no lockfile, nothing to update when someone else's package goes wrong.
+
+## Requirements
+
+Node 20 or newer, on any platform it runs on. That is the entire list.
+
+```
+node --version
+```
+
+## Quickest: npx
+
+```bash
+npx pigeondrop
+```
+
+Runs it from the folder you are in and serves `./files`, created if missing.
+Open http://localhost:3001. Changes made on the Settings page are kept in
+`./settings.json`. The variables under [Configuration](#configuration) work
+the same way:
+
+```bash
+REPO_ROOT=/srv/files PORT=8080 npx pigeondrop
+```
+
+On Windows, set them first, as in
+[Serve a folder you already have](#serve-a-folder-you-already-have-1), then
+run `npx pigeondrop`.
+
+To keep it installed rather than fetched each time, `npm install -g pigeondrop`
+and then run `pigeondrop`.
+
+For anything longer-lived, follow whichever section below matches your
+machine. Each one is self-contained: install, run, share, keep running.
+
+---
+
+# macOS and Linux
+
+Also WSL, and anything else with bash.
+
+## Install it
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/cventour/pigeondrop/main/install.sh -o install.sh
+```
+
+Read it — it is about a hundred lines and does nothing surprising. Then:
+
+```bash
+bash install.sh
+```
+
+It installs to `~/pigeonhole`, checks your Node version, and starts the
+server. Open http://localhost:3001.
+
+Options:
+
+| Option | Meaning |
+|---|---|
+| `--dir` | Where to install. Default `~/pigeonhole`. |
+| `--root` | The directory to serve. Default `<install dir>/files`. |
+| `--port` | Default `3001`. |
+| `--host` | Bind address. Default `127.0.0.1`. |
+| `--title` | Page heading. |
+| `--no-start` | Install without starting. |
+
+So to serve a folder you already have, to the whole network:
+
+```bash
+bash install.sh --root /srv/files --host 0.0.0.0
+```
+
+Run the script again later and it updates the copy it installed.
+
+## Run it by hand
+
+The script saves typing, not much else. The manual version is three lines:
+
+```bash
+git clone https://github.com/cventour/pigeondrop.git
+cd pigeonhole
+node server.js
+```
+
+Files land in `./files`, created on first run.
+
+## Serve a folder you already have
+
+Configuration is environment variables. Set them inline for one run:
+
+```bash
+REPO_ROOT=/srv/files node server.js
+```
+
+Or for the whole shell session:
+
+```bash
+export REPO_ROOT=/srv/files REPO_TITLE="Team Drop"
+```
+
+The path can be anywhere the user running the process can read and write — an
+external drive, a home directory, a network mount.
+
+## Let other machines reach it
+
+It binds `127.0.0.1`, so by default only this machine can reach it. To open it
+to the network, bind all interfaces:
+
+```bash
+HOST=0.0.0.0 PORT=3001 REPO_ROOT=/srv/files node server.js
+```
+
+Find the address to hand out — macOS:
+
+```bash
+ipconfig getifaddr en0
+```
+
+Linux:
+
+```bash
+hostname -I
+```
+
+Others open `http://<that-address>:3001`. Read
+[There is no authentication](#there-is-no-authentication) before you do this.
+
+## Keep it running
+
+The shell that started it owns it. To survive a closed terminal:
+
+```bash
+nohup env REPO_ROOT=/srv/files node server.js > pigeonhole.log 2>&1 &
+```
+
+**Linux, with systemd.** Save as `/etc/systemd/system/pigeonhole.service`:
+
+```ini
+[Unit]
+Description=Pigeonhole
+After=network.target
+
+[Service]
+Type=simple
+User=pigeonhole
+WorkingDirectory=/opt/pigeonhole
+ExecStart=/usr/bin/node /opt/pigeonhole/server.js
+Environment=REPO_ROOT=/srv/files
+# A place the service may write its settings, which ProtectSystem=strict
+# would otherwise refuse. Pigeonhole finds it by itself: /var/lib/pigeonhole.
+StateDirectory=pigeonhole
+# Quote any value containing a space: systemd splits unquoted ones.
+Environment="REPO_TITLE=Team Drop"
+Restart=on-failure
+
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/srv/files
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable --now pigeonhole
+```
+
+```bash
+systemctl status pigeonhole
+```
+
+**macOS, with launchd.** Save as
+`~/Library/LaunchAgents/com.pigeonhole.plist`, with your own paths — launchd
+does not expand `~`, and needs the full path to node:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>              <string>com.pigeonhole</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/node</string>
+    <string>/Users/you/pigeonhole/server.js</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>REPO_ROOT</key>        <string>/Users/you/Shared</string>
+    <key>REPO_TITLE</key>       <string>Team Drop</string>
+  </dict>
+  <key>RunAtLoad</key>          <true/>
+  <key>KeepAlive</key>          <true/>
+  <key>StandardErrorPath</key>  <string>/tmp/pigeonhole.log</string>
+</dict>
+</plist>
+```
+
+`which node` gives the path to use. Then load it:
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.pigeonhole.plist
+```
+
+```bash
+launchctl print gui/$(id -u)/com.pigeonhole
+```
+
+To stop it for good:
+
+```bash
+launchctl bootout gui/$(id -u)/com.pigeonhole
+```
+
+---
+
+# Windows
+
+PowerShell throughout. Every command works in Windows PowerShell 5.1 and in
+PowerShell 7.
+
+## Install it
+
+```powershell
+irm https://raw.githubusercontent.com/cventour/pigeondrop/main/install.ps1 -OutFile install.ps1
+```
+
+Read it — it is about a hundred lines and does nothing surprising. Then:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\install.ps1
+```
+
+Windows blocks downloaded scripts by default, which is why that is longer than
+`.\install.ps1`. It applies to this one run and changes nothing on the machine.
+
+It installs to `$HOME\pigeonhole`, checks your Node version, and starts the
+server. Open http://localhost:3001.
+
+Options:
+
+| Option | Meaning |
+|---|---|
+| `-Dir` | Where to install. Default `$HOME\pigeonhole`. |
+| `-Root` | The directory to serve. Default `<install dir>\files`. |
+| `-Port` | Default `3001`. |
+| `-Bind` | Bind address. Default `127.0.0.1`. |
+| `-Title` | Page heading. |
+| `-NoStart` | Install without starting. |
+
+So to serve a folder you already have, to the whole network:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\install.ps1 -Root D:\files -Bind 0.0.0.0
+```
+
+The switch is `-Bind` rather than `-Host` because `$Host` is a variable
+PowerShell reserves for itself.
+
+Run the script again later and it updates the copy it installed.
+
+## Run it by hand
+
+The script saves typing, not much else. The manual version is three lines:
+
+```powershell
+git clone https://github.com/cventour/pigeondrop.git
+cd pigeonhole
+node server.js
+```
+
+Windows does not ship with git, so on a fresh machine that first line fails.
+Take the zip instead — this needs nothing that is not already there:
+
+```powershell
+irm https://github.com/cventour/pigeondrop/archive/refs/heads/main.zip -OutFile pigeondrop.zip
+Expand-Archive pigeondrop.zip -DestinationPath .
+cd pigeondrop-main
+node server.js
+```
+
+Files land in `.\files`, created on first run.
+
+## Serve a folder you already have
+
+Configuration is environment variables. PowerShell sets them on their own line —
+the `REPO_ROOT=... node server.js` form you see in Unix instructions is not
+valid here:
+
+```powershell
+$env:REPO_ROOT = "D:\files"
+node server.js
+```
+
+They last as long as the window. To set one for good, for your account:
+
+```powershell
+[Environment]::SetEnvironmentVariable("REPO_ROOT", "D:\files", "User")
+```
+
+Open a new PowerShell window for that to take effect.
+
+## Let other machines reach it
+
+It binds `127.0.0.1`, so by default only this machine can reach it. To open it
+to the network, bind all interfaces:
+
+```powershell
+$env:HOST = "0.0.0.0"; $env:REPO_ROOT = "D:\files"; node server.js
+```
+
+Find the address to hand out:
+
+```powershell
+Get-NetIPAddress -AddressFamily IPv4 | Where-Object IPAddress -notlike '127.*' | Select-Object InterfaceAlias, IPAddress
+```
+
+Windows Firewall will block the port even once it is bound, and the prompt is
+easy to miss. Allow it from an **administrator** PowerShell:
+
+```powershell
+New-NetFirewallRule -DisplayName "Pigeonhole" -Direction Inbound -Protocol TCP -LocalPort 3001 -Action Allow
+```
+
+Others open `http://<that-address>:3001`. Read
+[There is no authentication](#there-is-no-authentication) before you do this.
+
+To close it again afterwards:
+
+```powershell
+Remove-NetFirewallRule -DisplayName "Pigeonhole"
+```
+
+## Keep it running
+
+The window that started it owns it. To put it in the background for this
+session:
+
+```powershell
+$p = Start-Process node -ArgumentList "server.js" -WorkingDirectory "$HOME\pigeonhole" -WindowStyle Hidden -PassThru
+```
+
+`-PassThru` hands back the process, so you can stop it again:
+
+```powershell
+Stop-Process -Id $p.Id
+```
+
+To survive a reboot, register a scheduled task from an **administrator**
+PowerShell. Install it somewhere outside your profile first, since the task
+runs as SYSTEM:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\install.ps1 -Dir C:\pigeonhole -NoStart
+```
+
+Set every setting you need machine-wide, because SYSTEM does not see your
+account's variables:
+
+```powershell
+[Environment]::SetEnvironmentVariable("REPO_ROOT", "D:\files", "Machine")
+[Environment]::SetEnvironmentVariable("HOST", "0.0.0.0", "Machine")
+```
+
+```powershell
+$action  = New-ScheduledTaskAction -Execute (Get-Command node).Source -Argument "server.js" -WorkingDirectory "C:\pigeonhole"
+$trigger = New-ScheduledTaskTrigger -AtStartup
+Register-ScheduledTask -TaskName Pigeonhole -Action $action -Trigger $trigger -User SYSTEM -RunLevel Highest
+```
+
+`(Get-Command node).Source` resolves the full path to node.exe, because SYSTEM
+does not necessarily share your `PATH`.
+
+Start it now rather than waiting for a reboot:
+
+```powershell
+Start-ScheduledTask -TaskName Pigeonhole
+```
+
+```powershell
+Get-ScheduledTask -TaskName Pigeonhole | Get-ScheduledTaskInfo
+```
+
+A `LastTaskResult` of `267009` is not an error — it is `0x41301`, "the task is
+currently running", which is what you want to see.
+
+Stop it, or remove it entirely:
+
+```powershell
+Stop-ScheduledTask -TaskName Pigeonhole
+```
+
+```powershell
+Unregister-ScheduledTask -TaskName Pigeonhole -Confirm:$false
+```
+
+---
+
+## Configuration
+
+All optional, all environment variables, identical on every platform.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `REPO_ROOT` | `./files`, in the working directory | The directory it manages. Created if missing. |
+| `HOST` | `127.0.0.1` | Bind address. Loopback by default, on purpose. |
+| `PORT` | `3001` | |
+| `REPO_TITLE` | `Pigeonhole` | Page title and heading |
+| `REPO_SUBTITLE` | `Drop files in. Take files out.` | Line under the heading |
+| `SETTINGS_FILE` | `$STATE_DIRECTORY/settings.json` under systemd, else `settings.json` beside `server.js` (in the working directory when run through npx or a global install) | Where changes made on the Settings page are kept. Mode 600; not in the managed directory. It must be somewhere the service can write. |
+
+Branding is configuration rather than code, so one copy serves any deployment.
+
+How you set them is the only thing that differs:
+
+| | macOS and Linux | Windows |
+|---|---|---|
+| One run | `REPO_ROOT=/srv/files node server.js` | `$env:REPO_ROOT = "D:\files"` then `node server.js` |
+| This session | `export REPO_ROOT=/srv/files` | `$env:REPO_ROOT = "D:\files"` |
+| Permanently | put the `export` in `~/.zshrc` or `~/.bashrc` | `[Environment]::SetEnvironmentVariable("REPO_ROOT", "D:\files", "User")` |
+
+## Scan uploads with ICAP
+
+**Settings** in the toolbar points Pigeonhole at an ICAP server (MetaDefender
+ICAP Server, c-icap with ClamAV, anything that speaks ICAP `REQMOD`). Each
+upload is sent there once it has arrived, and appears in the listing only if
+the scanner passes it. A blocked file is deleted and the upload card shows the
+threat name.
+
+| Field | Meaning |
+|---|---|
+| Server, Port | Where the ICAP server listens. 1344 is the standard port. |
+| Service | The ICAP service name, the last part of `icap://host:1344/service`. |
+| Timeout | Seconds to wait for the scanner before giving up. |
+| Use TLS (ICAPS) | Connect over TLS. The port switches to 11344, the usual ICAPS port, unless you set another. |
+| Verify the certificate | On (the default): the scanner's certificate must be valid and match Server. Off: the link is still encrypted, but any certificate is accepted. |
+| Reject the upload if the scanner cannot be reached or cannot scan | On (the default): such an upload is refused. Off: it is kept, and the page says it was not scanned. |
+
+**Test connection** asks the server what it is and then scans a few harmless
+bytes, so it also catches a server that answers but cannot scan, such as one
+with no licence. It uses the values in the form, so a server can be checked
+before saving.
+
+If the certificate is self-signed or issued by a private CA, either start
+Pigeonhole with `NODE_EXTRA_CA_CERTS` set to that CA's PEM file, or turn off
+**Verify the certificate**. Use the name the certificate was issued for as
+Server.
+
+When a TLS connection fails, Test connection, the upload card and the message
+after Save all say why in plain words: an expired or self-signed certificate, a
+certificate for another name, a CA this server does not trust, no TLS version in
+common, a scanner that wants a client certificate, or a port that does not
+speak TLS (or the other way round).
+
+Only uploads are scanned. Files already in the folder, or put there by other
+means, are not.
+
+## There is no authentication
+
+Read that again before you expose it. Anyone who can reach it can upload,
+rename and delete. Pigeonhole assumes it sits on a network you trust — a home
+or office LAN, a VPN, a lab segment.
+
+That is a scope decision, not an oversight. Authentication done badly is worse
+than none, so it does none and says so plainly.
+
+It binds `127.0.0.1` by default so that exposing it takes a decision.
+
+## Safety
+
+Every client-supplied path is resolved and checked against the root before
+use, so `../../etc` lands inside the managed directory rather than outside it.
+Names for rename and mkdir must be a single path component — a separator is
+refused rather than stripped. Filenames render as text, never as markup.
+
+Because anyone who can reach the page can open Settings, they can also make
+the server connect to any host and port, which is a way to probe the network
+it sits on, and can turn scanning off. Another reason to keep it on a network
+you trust.
+
+None of that substitutes for the authentication it does not have.
+
+## Design notes
+
+Three choices worth explaining, because each looks wrong at first glance.
+
+**Uploads are a raw `PUT` body, not `multipart/form-data`.** Multipart is the
+conventional answer and would need a parser — the one dependency this would
+otherwise have. A raw body streams straight to disk, so a four-gigabyte file
+never lands in memory, and there is nothing to audit or update.
+
+**Uploads use `XMLHttpRequest`, not `fetch`.** `fetch` still cannot report
+upload progress. A large upload with no progress bar is indistinguishable from
+a hang, so XHR stays until browsers fix that.
+
+**Files upload to `<name>.part` and are renamed on completion.** An
+interrupted transfer then leaves nothing behind, rather than a truncated file
+that looks complete until something tries to use it. The ICAP scan runs on
+that `.part` file, before the rename, so a file being scanned is never
+downloadable under its real name.
+
+## Licence
+
+MIT.

package/icon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect x="2" y="2" width="60" height="60" rx="13" fill="#2d3339"/>
+  <g fill="#0f1113">
+    <path d="M8 28V17a7 7 0 0 1 14 0v11z"/>
+    <path d="M25 28V17a7 7 0 0 1 14 0v11z"/>
+    <path d="M8 51V40a7 7 0 0 1 14 0v11z"/>
+    <path d="M25 51V40a7 7 0 0 1 14 0v11z"/>
+    <path d="M42 51V40a7 7 0 0 1 14 0v11z"/>
+  </g>
+  <path d="M42 28V17a7 7 0 0 1 14 0v11z" fill="#ff6a1f"/>
+  <path d="M44.5 19.5h9v6.5h-9z" fill="#1b1e21"/>
+  <path d="M44.5 19.5l4.5 3.5 4.5-3.5" fill="none" stroke="#ff6a1f" stroke-width="1.3"/>
+  <path d="M6 30h52M6 53h52" stroke="#c8ced4" stroke-width="2.5" stroke-linecap="round"/>
+</svg>

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "pigeondrop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.6.1",
+  "description": "A small self-hosted file manager with no dependencies. Drag-and-drop upload with progress, browse, rename, delete, download files or folders as zip.",
+  "type": "module",
+  "main": "server.js",
+  "bin": { "pigeondrop": "./server.js", "pigeonhole": "./server.js" },
+  "scripts": { "start": "node server.js" },
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "keywords": ["file-manager", "upload", "self-hosted", "zero-dependency", "http"],
+  "repository": { "type": "git", "url": "git+https://github.com/cventour/pigeondrop.git" },
+  "files": ["server.js", "public", "icon.svg", "README.md", "LICENSE", "CHANGELOG.md"]
+}