ergosteurandClaude Opus 5
1d86fa3583
Security - Fix path traversal in GET /api/archives/:name/files. Express decodes route params after segment matching, so `..%2f..%2fetc` escaped ARCHIVES_DIR and returned a recursive listing of arbitrary directories. - Add CSP and baseline security headers; disable x-powered-by. - Stop baking GEMINI_API_KEY into the client bundle (the SDK was unused). - Run the container as `node` instead of root. Performance - Add a directory-mtime-keyed archive index, warmed in the background and persisted. Listing 110k files went from ~52s to ~0.1s; the largest archive (24k files) serves in ~0.3s. Per-file stat over CIFS costs ~1.4ms and does not parallelise, so it is now done once rather than per request. - Build media URLs from the File directly instead of `new Blob([await file.arrayBuffer()])`, which read every media file fully into memory (a 20GB archive tried to become 20GB of resident blobs). - Track and revoke object URLs; previously none were ever revoked. - Give `requestThumbnail` a stable identity so a completed thumbnail stops re-running the effect in every mounted thumbnail. - Namespace IndexedDB keys so listing archives no longer deserializes every cached thumbnail blob, and thumbnails no longer collide across archives. - Serve real file sizes: RemoteArchiveFile was constructed with size 0, which silently disabled high-res thumbnailing for every server archive. Correctness - Local archives cached media as blob: URLs, which die with the document, so a cached local archive restored as an archive of broken images. Media now carries a stable path and is rehydrated from a persisted directory handle (File System Access API), falling back to re-prompting for the folder. - Fix permalinks: the URL-writing effect erased ?a= on mount before the archive list arrived to consume it, so deep links never resolved. - Make cache invalidation detect nested changes via a directory signature. - Add an error boundary and tolerate unparseable dates, which previously threw a RangeError and blanked the app. - Default video to muted so autoplay is not blocked by Safari/Firefox. Features - Fold sidecar directories into their base profile: `<user> - reels`, `story - <user>` and `story highlights - <user> - <title>` now appear as reels, the story ring and Instagram-style highlight circles rather than as separate archives. Housekeeping - Add @types/react; React was previously type-checked against its JavaScript source, so `npm run lint` gave almost no type safety on components. - Vendor fonts and PWA icons locally; the app made third-party CDN requests despite advertising offline support and local-only processing. - Drop unused better-sqlite3 (a native module that broke `npm install`). - Add vitest with 36 tests over the filename and directory-naming rules. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011uBWhwV3wFQ5MBCcMHHem7
InstaArchive Viewer
A high-performance React PWA for browsing archived Instagram data with a native-feeling interface. Supports both official Instagram exports and Instaloader archives.
Features
- Advanced Carousel: Seamless, zero-latency transitions between slides with intelligent preloading. Navigating between different posts is now near-instant thanks to inter-post background preloading.
- High-Res Performance: Handles 50MP+ images effortlessly using a background Web Worker and a memory-safe serial processing queue.
- Persistent Local Caching: Uses IndexedDB to store parsed archives and generated thumbnails. Local folders now load instantly from cache on return visits without needing to re-upload files.
- Permalinks: State is synchronized with the URL, allowing you to share direct links to archives, tabs, or specific posts. Navigating back to the explorer cleans up URL parameters automatically.
- Glassy Scanning UI: A refined, translucent white terminal experience with flicker-free, double-buffered dynamic blurred backgrounds.
- PWA with Auto-Update: Fully offline-capable and installable. Clients automatically receive updates when a new version is deployed to the server.
- Local Privacy: All processing is done client-side. Even when using the self-hosted version, your media is processed locally in your browser and never uploaded.
- Smart Fallbacks: Automatically detects usernames from folder names and uses the oldest archive image as a profile picture if one is missing.
- Customizable Grid: 1:1 or 3:4 aspect ratios with adjustable "bumps" for aesthetic alignment.
- Story Viewer: Native-like story experience with segmented progress bars, auto-playback, and audio controls.
- Navigation Protection: Intercepts accidental browser "Back" or "Refresh" actions to protect your current session.
Deployment
Docker (Recommended)
The easiest way to run InstaArchive is using Docker.
docker run -d \
-p 3000:3000 \
-v /path/to/your/archives:/archives:ro \
ghcr.io/ergosteur/instaarchive-viewer:latest
Note for Linux/SELinux users: If you see "Permission Denied" in the logs, append
,zto your volume mount:-v /path/to/archives:/archives:ro,z
Docker Compose
Create a compose.yml file:
services:
instaarchive:
image: ghcr.io/ergosteur/instaarchive-viewer:latest
ports:
- "3000:3000"
volumes:
- ./archives:/archives:ro,z # ,z handles SELinux permissions
Troubleshooting Permissions
If the app shows "No Archives Found" and logs EACCES: permission denied:
- Check Directory Permissions: Ensure the archive folder is world-readable:
chmod -R 755 /path/to/archives - SELinux (Fedora/RHEL/CentOS): Use the
:zflag in your volume mount as shown above. - User Mapping: You can force the container to run as your host user:
docker run --user $(id -u):$(id -g) ...
Supported Archive Structure
Place your archive folders inside the mounted /archives directory. The directory name will be used as the account username.
Example Structure:
archives/
├── wanderlust_explorer/ # Instaloader format
│ ├── 2024-01-01_12-00-00_UTC.jpg
│ ├── 2024-01-01_12-00-00_UTC.json.xz
│ └── wanderlust_explorer_profile_pic.jpg
└── pixel_architect/ # Instagram Export format
├── 2023-12-25_pixel_architect - post_123.jpg
├── 2023-12-25_pixel_architect - post_123.json
└── pixel_architect.jpg
Local Development
Prerequisites: Node.js (LTS recommended)
- Install dependencies:
npm install - Start dev server:
npm run dev(Frontend on port 3000) - Start local backend:
npm run server(Optional, serves./_sample-archiveson port 3001) - Build production:
npm run build(Generates./distfor frontend and./dist-serverfor the API)