Twenty-nine commits since v0.12.0. See CHANGELOG.md for the full list
and the upgrade notes.
Ten additions — the SEO package (site URL, robots.txt, sitemap.xml,
JSON-LD), slideshow mode, opt-in original downloads, copy-link,
previous/next album navigation, alt text from the Immich description,
per-album location precision, the update notice, a Help tab, and a
subpage cover grid separate from its photo grid. Two fixes: CJK album
slugs, and the lightbox control bar.
Photo of the Day (#476) was built on `dev` and reverted as not planned;
it never appears in a release.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01DmsHVRL9yQvckUB1ZpVWre
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
## Was ist das?
Sieben neue Portfolio-Features, alle als **experimental** gekennzeichnet
— in YAML-Kommentaren, Admin-Panel-Labels und Commit-Scopes, damit sie
einzeln nachvollziehbar und revertierbar bleiben.
## Features (je ein Commit)
| Commit | Feature |
| --- | --- |
| `justified rows gallery layout` | Neues Grid-Layout `justified`:
zeilenbasiert, gleiche Höhen, volle Breite — Flexbox ohne JS-Messung,
letzte Zeile bleibt natürlich klein |
| `hide subpages from navigation` | `hidden: true`: Seite aus
Nav/Homepage raus, per Direktlink erreichbar — im Gegensatz zu `enabled:
false` (404) |
| `lightbox captions` | Immich-Asset-Description als Bildunterschrift im
Info-Panel; EXIF-Route liefert bei `exifOnHover: false` jetzt nur noch
die Caption statt 403 |
| `per-album grid overrides` | `grid:` pro Album-Eintrag, Präzedenz
global < Subpage < Album |
| `per-album cover focal point` | `coverPosition:` → `object-position`
auf Cover-Karten, strikt validiert |
| `external links in header navigation` | `navLinks:` in settings.yaml,
nur http(s), sanitisiert |
| `cover splash hero style` | `heroStyle: cover`: Fullscreen-Splash mit
Enter-Link ins Portfolio |
Alle Optionen sind im Admin-Panel editierbar (PageBuilder /
SettingsEditor).
## Tests
- 356 Unit-Tests grün (13 neue: deriveGallery hidden/grid/coverPosition,
sanitizeNavLinks, EXIF-Route-Captions, justified-Layout-Validierung)
- `npx tsc --noEmit`: 0 Fehler
- `npm run build`: sauber
- Justified-Zeilenmathematik und Cover-Splash per Browser-Harness
visuell/numerisch verifiziert (volle Zeilen enden exakt an der
Containerkante, letzte Zeile bleibt natürlich)
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: lancetm714 <108419425+lancetm714@users.noreply.github.com>
Photo Essay mode, client proofing, studio-modern preset, admin panel overhaul, watermark, cookieless analytics, subpage toggle, SEO title templates. Analytics API now admin-only, Trivy scan on publish. Album order mirrors the Immich timeline; map theme, admin status panel, lightbox counter and Docker health check fixed.
See CHANGELOG.md for the full list and the health-check upgrade note.
* feat(admin): add backup manager UI with 1-click restore
* feat(admin): collapse older backup entries by default
* fix(theme): isolate admin layout, instant DOM theme updates, and add Light/Dark mode toggle
* feat(admin): replace text controls for Photo Frame and Hero Style with visual preview cards
* fix(admin): define missing CSS rules for button system (.btn, .preset-btn)
* feat(admin): redesign theme settings with segmented mode toggle, accent color swatches, and custom iOS-style toggle cards
* feat(admin): upgrade all settings tabs with visual grid previews, Google SEO snippet preview, and toggle cards
* feat(admin): overhaul Pages Builder UX with slide-over drawer, card hover badges, real-time search, and floating save bar
* fix(admin): remove leftover dangling syntax snippet in PageBuilder.tsx
* fix(admin): add position: relative to subpage-tile so hover overlay is contained inside the tile
* style(admin): replace all emojis with clean Leica-style vector SVG icons
* fix(types): extend IconProps with SVGProps to allow style prop on Leica SVG icons
* feat(admin): add subpage live-preview, privacy analytics, and asset protection settings
* fix(typecheck): fix AlbumEntry property access in subpage drawer preview mode
* fix(types): fix ImmichAlbumInfo property names thumbnailAssetId and albumName in PageBuilder.tsx
* fix(types): add protection and watermark optional properties to AppConfig interface
* feat(settings): add toggle for disabling analytics tracking (defaults to enabled)
* feat(ux): show status banner when analytics tracking is disabled + add live sync indicator
* feat(watermark): render customizable watermark overlay on Lightbox images + rename section to Portfolio Features & Modules
* fix(types): import type LightboxWatermark in PhotoGrid.tsx
* fix(types): destructure watermark prop in PhotoGrid function signature
* feat(seo): add configurable subpage title template and metadata descriptions
* feat(seo): add generateMetadata to about page for title template support
* feat(proofing): add client proofing, favorites selection, compact URL bitmasking, and export modal
* feat(essay): add Photo Essay storytelling mode with RSC markdown parser and fullbleed/pair layouts
* feat(subpages): add page enabled toggle to deactivate subpages without deleting them
* feat(admin): add visual essay block builder for photo essay storytelling pages
* security: add Trivy container scan to Docker publish workflow
Scans the built image for CRITICAL/HIGH CVEs on every release and
uploads results to the GitHub Security tab. Non-blocking for now
(exit-code 0) so releases aren't gated on findings. Also documents
the scan and existing Dependabot coverage in the README.
---------
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
* docs: brainstorm resilience/adoption features and plan follow-up work
Brainstorm and deep-dive on where Immich Folio breaks under Immich
outages and what blocks self-hosted adoption, plus an implementation
plan for the remaining gaps after v0.9.2 (route-handler tests,
stale-while-error caching, loading skeletons).
* test: enable route-handler tests and cover admin guards and image content-type
vitest.config.ts only ran lib/__tests__/**, so route handlers were
structurally untestable. Two mechanisms live only at the route level and
cannot be extracted the way lib/imageSize.ts was: the admin auth guards
and the image proxy's Content-Type sanitisation (the stored-XSS fix from
c2fa8e7). Both were correct but unverified by any test.
Adds a table-driven test over all ten guarded /api/admin/* handlers,
including a filesystem walk that fails if a future route is added
without a row in the table. Adds a route-level test for
/api/image/[id] covering token validation, the six Content-Type
rewrite cases, ETag/304, and the 404 vs 503 (ImmichUnavailableError)
distinction.
Verified both catch real regressions by temporarily removing the admin
guards and the Content-Type rewrite and confirming the expected tests
fail, then restoring and confirming green again.
134 new tests (244 total, up from 210), tsc 0 errors, build succeeds.
* feat: serve stale cache entries while Immich is unavailable
v0.9.2 (#394) correctly split "gone" (404/410) from "unavailable"
(ImmichUnavailableError), and pages now render a 5xx instead of a false
404 during an outage — but that 5xx still replaced a gallery that had
loaded fine seconds earlier. lib/cache.ts deleted expired entries on
access, so nothing survived long enough to fall back to.
Cache entries now carry two deadlines: staleAt (the existing CACHE_TTL,
after which get() still reports a miss) and hardExpiresAt (the new
STALE_MAX_AGE, default 24h, after which the entry is dropped entirely).
Between the two, getStale() can still return the data.
getAlbums(), getAlbum() and getAssetInfo() catch ImmichUnavailableError
and fall back to getStale() before propagating. The two MISSING-sentinel
writes (definitive 404s) are deliberately left on the short cacheTtl
window — a corrected asset ID should take effect after the normal TTL,
not sit in the 24h stale window meant for outages.
STALE_MAX_AGE=0 disables the fallback. Verified the fallback only
engages on a real outage, not on a cache hit at the TTL boundary, and
that a definitive 404 still reports missing rather than falling back.
256 tests (up from 244), tsc 0 errors, build succeeds.
* feat: add loading skeletons for dynamic gallery routes
Every gallery route is force-dynamic and waits on a live Immich
round-trip — up to IMMICH_TIMEOUT_MS when the server is struggling —
with nothing rendered until it resolves. loading.tsx renders instantly
while the page component awaits its data.
Not browser-verified against live data: this worktree has no
.env.local and only .example content files, so the app boots into
setup mode (confirmed the dev server starts cleanly and the setup
screen renders, HTTP 200). tsc 0 errors, build succeeds, no new lint
errors.
* docs: document stale cache window, image token revocation, route-test convention
- README: STALE_MAX_AGE env var and a "Behaviour when Immich is
unreachable" section (stale-serves-until-STALE_MAX_AGE, 503 not 404,
outages never cached).
- docs/gallery-config.md: new "Image Token Revocation" subsection under
System & Security — un-publishing an album does not revoke already
issued image URLs; rotating AUTH_SECRET does.
- CLAUDE.md: updated cache description to cover the stale window and
MISSING sentinel, and a new code-convention note that route-level
logic (guards, header sanitisation) should get a route-level test
rather than being extracted into lib/ just to reach the test runner.
---------
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
* fix: migrate deprecated middleware convention to proxy
Next.js 16 deprecated the `middleware` file convention in favour of
`proxy`. The build warned on every run, and the convention is slated for
removal in a future major — at which point Next.js would silently stop
invoking this file. That is not a cosmetic failure: proxy.ts owns the
Content-Security-Policy and the per-request nonce, so an uninvoked file
means every document response ships with no CSP at all, with nothing in
the build output to catch it.
Renames middleware.ts to proxy.ts and the exported middleware() to
proxy(), per the official migration. The config.matcher export is
unchanged, so route coverage is identical.
Adds lib/__tests__/proxy.test.ts, which pins the export name and
verifies the behaviour a silent regression would take out: a CSP is set,
the nonce in the policy matches the one forwarded to pages via x-nonce,
nonces differ per request, x-pathname still reaches the root layout, and
the matcher continues to cover /admin.
Verified: tsc 0 errors, 105 unit tests passing (98 before), production
build succeeds with 0 deprecation warnings.
* fix: stop reporting Immich outages as missing albums
lib/immich.ts request() returned null for every failure mode: a 5xx, a
rejected API key, a network error, and a non-JSON body all looked exactly
like "Immich answered and said this does not exist". Callers had no way
to tell the two apart, and app/[...path]/page.tsx calls notFound() on a
null album in five places.
The result was that while Immich was down or returning 5xx, every album
URL served a hard 404 — for albums that exist. Visitors saw "not found",
and crawlers were free to de-index real content over a transient outage.
request() now throws ImmichUnavailableError for anything that is not a
definitive answer about the resource, and reserves null for 404 and 410.
Pages let that propagate, so an outage surfaces as a 500 rather than a
404. Two callers must not propagate and are handled explicitly:
- ping() catches and returns false — it answers "is Immich reachable",
and both callers (/api/health, /api/admin/status) render that as a
status field.
- /api/exif and /api/map return 503 with Retry-After instead of 404 and
an empty marker list respectively. An empty map is otherwise
indistinguishable from a gallery with no GPS data.
Adds 10 tests: each failure mode maps to the right outcome, getAlbum and
getAlbums propagate rather than reporting empty, ping stays non-throwing,
and a failed request leaves no stale entry in the in-flight coalescing
map — which would otherwise replay the failure after Immich recovered.
Verified: tsc 0 errors, 115 unit tests passing (105 before), production
build exit 0, eslint 0 errors on all touched files.
* fix: bound how long Immich requests may hang
lib/immich.ts set no timeout on any of its three fetch call sites, so the
only ceiling was undici's built-in default, measured in minutes. Every
page is force-dynamic, which means an Immich that accepts connections but
never answers held each visitor's render open for that whole window —
and since nothing caches the failure, load kept arriving.
Adds IMMICH_TIMEOUT_MS (default 15000, floored at 1000 so a stray 0
cannot mean "no timeout"), threaded through env.ts and AppConfig like
CACHE_TTL.
The two kinds of call need different treatment:
- request() carries a whole-exchange AbortSignal.timeout(). JSON
payloads are small, so one budget can cover headers and body.
- streamAsset()/streamVideo() use an AbortController whose timer is
cleared in a finally the moment response headers arrive. A large
original photo or a long video is legitimately slow to transfer; a
whole-request timeout would truncate playback and break seeking, since
every range request would restart the clock.
A timed-out request surfaces as ImmichUnavailableError naming the budget,
so a misconfigured value is diagnosable from the log line alone.
Adds 5 tests, including the two that pin the distinction: a stream whose
headers have arrived is not aborted an hour later, while a stream that
never sends headers still is.
Verified: tsc 0 errors, 120 unit tests passing (115 before), production
build exit 0, no new eslint errors (the one error in env.ts is
pre-existing — confirmed against a clean tree).
* fix: stop caching Immich outages as permanently missing media
f3 split "gone" from "unavailable" in request(), but streamAsset() and
streamVideo() have their own fetch calls and were left returning null for
every failure. Both proxy routes turn null into a 404.
That 404 carried no Cache-Control, and a 404 is heuristically cacheable
per RFC 9111 — on URLs the success path serves as `immutable`. So a
transient outage, or a timeout introduced in 370e668, could pin a broken
image or an unplayable video in the visitor's browser cache well after
Immich recovered.
Both stream methods now throw ImmichUnavailableError for transport
failures, timeouts, and any error status other than 404/410, and reserve
null for genuinely absent media. A 200 with no body counts as
unavailable, not as missing. The routes translate that into 503 with
Retry-After, and both error responses — the 503 and the real 404 — now
send Cache-Control: no-store.
streamVideo keeps accepting 206, so range requests and seeking are
unaffected.
Adds 7 tests covering each failure mode for both methods plus the 206
path, and updates the F4 timeout test, which asserted the old null return.
Verified: tsc 0 errors, 127 unit tests passing (120 before), production
build exit 0, eslint 0 errors on touched files.
* perf: cache "does not exist" answers from Immich
getAlbum() and getAssetInfo() cached successes but discarded a definitive
"not found", so a missing resource was re-queried upstream on every call.
Measured before: 5 sequential lookups of a missing asset produced 5
upstream fetches. After: 1.
This is not hypothetical. app/page.tsx resolves every gallery.yaml hero
ID through getAssetInfo() on each render, and the homepage is
force-dynamic — so a hero photo deleted from Immich but still listed in
gallery.yaml cost one 404 round-trip per page view, indefinitely.
Absence is stored as a frozen MISSING sentinel because the cache cannot
distinguish a miss from a stored null; both read back as null.
Only definitive 404/410 answers are cached. An outage throws
ImmichUnavailableError and is deliberately never stored — caching one
would keep the gallery broken after Immich recovered. A test pins that:
a 503 followed by a healthy response must reach Immich the second time.
Stored under the normal cacheTtl rather than a separate shorter negative
TTL, because the reason for a shorter one no longer applies: outages are
not cached at all now, and both invalidation paths (the Immich webhook
and the admin save/reload) clear the entry immediately, so a corrected
asset ID takes effect at once rather than waiting out a TTL.
Also raises the test config's cacheTtl from 0, which expired entries in
the same millisecond they were written and would have made any caching
assertion flaky. Test isolation comes from cache.clear() in beforeEach.
Verified: tsc 0 errors, 131 unit tests passing (127 before), production
build exit 0, eslint 0 errors on touched files.
* fix: add themed error and not-found pages
The app had no app/error.tsx, app/not-found.tsx or global-error.tsx, so
every failure fell through to Next.js's unstyled default page.
That gap became visible with 253ade0, which made an Immich outage produce
a 500 instead of a false 404 — correct, but what a visitor saw was a bare
framework error screen with none of the site's theming.
The two pages also carry the distinction the error split was for, and
they carry it structurally rather than by inspecting the error: notFound()
renders not-found.tsx, a throw renders error.tsx. That matters because
Next.js strips error messages in production and replaces them with a
digest — this component genuinely cannot tell an Immich outage from any
other server error, so it does not claim to. It frames the failure as
temporary and offers reset(); not-found.tsx deliberately does not, since
a real 404 is not transient.
The digest is shown so a user report can be traced to a log line. The raw
error message is never rendered — it can carry an upstream URL, a header
or a config value.
Both pages reuse .empty-state, which existed in globals.css but was
unreferenced anywhere in the app; extended with title, actions and button
elements matching the PasswordGate button, the only other action button
in the codebase.
Tested by server-rendering both components (react-dom/server, no new
dependencies) — 8 tests covering the styling hook, the retry and home
affordances, digest handling, and that a message containing an API key or
host address does not reach the markup. Note vitest.config.ts only
includes lib/__tests__/**/*.test.ts, so the test uses createElement
rather than JSX; a .tsx file there would never run.
Not verified in a browser: this worktree has no .env.local and only
.example content files, so the app boots into setup mode and neither
Playwright nor a dev server can exercise these routes here.
Verified: tsc 0 errors, 139 unit tests passing (131 before), production
build exit 0 with /_not-found registered, eslint 0 errors.
* perf: drop the unused originalUrl from every photo item
PhotoItem declared originalUrl and toPhotoItems computed it for every
asset, but a repo-wide grep found exactly two references: the field
declaration and the assignment. Nothing ever read it — the grid uses
thumbUrl, the lightbox uses previewUrl.
The cost was not the encryption. PhotoItem is a server-to-client prop, so
the dead field was serialized into the RSC payload and shipped to the
browser for every photo.
Measured: 137 bytes per asset once serialized, so 6.7 KB for a 50-photo
album and 66.9 KB for a 500-photo one — transferred and parsed on every
page view, never read.
Removed rather than wired up to a "view original" affordance. Exposing
full-size originals is a bandwidth and privacy decision for the project
to make deliberately, not something to infer from a dangling field.
No unit test: this is a deletion whose correctness is exactly "nothing
referenced it", which tsc and a repo-wide grep already establish. A test
asserting the absence of a field would restate the type checker.
Verified: tsc 0 errors, 139 unit tests passing, production build exit 0,
eslint unchanged at 4 pre-existing errors on the touched files (unused
imports, confirmed identical against a stashed clean tree).
* chore: remove four orphaned imports from the catch-all route
Link, Image, PhotoGrid and BackLink were imported by app/[...path]/page.tsx
and never used — 4 of the 6 no-unused-vars errors in the repo baseline.
Verified they are leftovers, not a dropped render path: PhotoGrid and
BackLink are both rendered by AlbumDetailView, which imports them itself,
and BackLink is also used by the impressum and map pages. Rendering was
extracted out of page.tsx into AlbumDetailView/SubpageGridView at some
point and the imports stayed behind. `type PhotoItem` is still needed by
toPhotoItems, so that import narrows to a type-only import rather than
disappearing.
No bundle win, measured: .next/static is 1084 KB across 20 JS chunks both
before and after, byte-identical. Turbopack already tree-shook them. The
backlog note that predicted unused client-component imports would hold
them in the client graph was wrong, and has been corrected there.
The value is readability and lint: repo errors drop from 54 to 50, and
page.tsx no longer reads as though it renders the grid itself.
chore: rather than fix:/perf: — nothing behaves differently and the
measurement showed no performance change, so either of those labels would
misdescribe it. CLAUDE.md lists chore: as a valid prefix.
Verified: tsc 0 errors, 139 unit tests passing, production build exit 0,
eslint 0 errors on the touched file.
* fix: make ?w= able to narrow the image tier instead of being ignored
The image proxy resolved its Immich rendition with `?size=` winning
whenever present, falling back to `?w=` otherwise. lib/urls.ts always
writes `?size=`, so for every URL this app generates the width branch was
unreachable and widthToSize() was dead code — while CLAUDE.md documented
the width mapping as the actual behaviour.
`?size=` is now a ceiling rather than an override: when both are present
the smaller tier wins, so a width can narrow the request but never widen
it. That asymmetry is the point. Letting width win outright — the obvious
reading of the docs — would have been a real regression: next/image emits
widths up to 3840 and widthToSize(1920) is 'original', so every large
display would have started downloading full-size originals in place of
previews. A test pins that specific case.
No measured change today. The only URLs carrying both parameters are
?size=preview with next/image widths, whose smallest vw-based deviceSize
is 640 — already preview either way. This is a correctness fix that makes
the documented contract true and testable, not a performance win.
Moved the logic to lib/imageSize.ts so it can be tested at all:
vitest.config.ts only collects lib/__tests__, so nothing inside a route
file is reachable from the suite. 9 tests cover the tier boundaries, both
single-parameter paths, malformed input, and the ceiling behaviour.
CLAUDE.md updated to describe the ceiling rule rather than a plain
width mapping.
Verified: tsc 0 errors, 148 unit tests passing (139 before), production
build exit 0, eslint 0 errors on touched files.
* fix: validate the per-album heroImage UUID from gallery.yaml
Every asset ID in gallery.yaml is routed through validateUuid before it
can reach encodeAssetId, which encrypts whatever it is handed. One was
not: for a per-album entry the album ID (the map key) was validated while
the heroImage value was stored raw.
A typo there produced a perfectly well-formed image URL that 404s forever,
with nothing in the log naming the cause — the failure surfaced as a
broken hero image on an album page, far from the line that caused it.
This is narrower than the finding that prompted it, which proposed
guarding encodeAssetId itself. Validation belongs at config load, where it
runs once and can name the file and the album; a guard in encodeAssetId
would run on every render and duplicate validateUuid at the wrong layer.
The heroImage path was the only unvalidated route into it.
validateUuid warns and substitutes the nil UUID rather than throwing, so a
bad ID still degrades to a missing image instead of taking the page down —
and since f511e62 that 404 is negative-cached, so it costs one upstream
request rather than one per render.
Adds 4 tests. The two that pin the wiring were mutation-checked: both fail
against the unfixed code and pass with it.
Verified: tsc 0 errors, 152 unit tests passing (148 before), production
build exit 0, eslint 0 errors on touched files.
* fix: keep /admin reachable when gallery.yaml cannot be derived
getConfig() throws on three shapes the admin page builder is able to
write: a gallery with neither albums nor subpages, a subpage with no name,
and a subpage with neither albums nor sections.
RootLayout called it unguarded, and a throw in a *layout* is not caught by
app/error.tsx — that needs a global-error boundary, which this app does
not have. /admin renders inside that same layout, so one bad save took
down the site together with the only tool that could undo it. Recovery
meant editing content/gallery.yaml on the host, or exec'ing into the
container. This is issue #326's failure mode reached through an invalid
config instead of a missing one.
Adds getConfigOrNull(), which returns null rather than throwing and logs
the underlying error plus the path to content/.backups/. The layout treats
null exactly like needsSetup: setup screen for visitors, children rendered
for admin paths so the panel still loads. generateMetadata() is guarded
too — it also calls getConfig(), and it also runs before any error
boundary.
This is the half of the finding that makes every broken config
recoverable, including ones this app never wrote: a hand-edited file, a
restored backup, a config from an older version. The other half —
validating in the admin PUT so the bad state is never written — is filed
separately; it prevents new breakage but cannot repair existing breakage,
so it was not the one to do first.
Adds 10 tests. Three pin the premise by asserting getConfig() really does
throw on each shape, so the fallback cannot quietly become dead weight.
One asserts the needsSetup path still returns a config rather than null,
since missing and invalid are different states that must not collapse.
Not verified in a browser: this worktree has no .env.local and only
.example content files, so the layout/error-boundary interaction is
reasoned from Next.js semantics and covered at the getConfig level only.
Verified: tsc 0 errors, 162 unit tests passing (152 before), production
build exit 0, eslint 0 errors on touched files.
* fix: reject an admin save the site would not be able to load
The admin PUT validated only the shape of the hero field, then wrote. None
of getConfig()'s three throw conditions was checked, so the page builder
could persist a gallery.yaml that cannot be loaded — and the user got
"Saved successfully" for it. Since 95877af that no longer locks anyone
out, but the public site still drops to the setup screen until someone
notices.
Extracts the gallery half of getConfig() into deriveGallery(), which the
route now runs against the proposed gallery before writing. Two
alternatives were rejected on purpose:
- Re-checking the three conditions in the route would put a second copy of
the rules next to the first, and the two would drift.
- Write-then-verify-then-roll-back leaves a window in which other requests
read the broken config.
The extraction is a pure move: no logic changed inside it, and all 162
pre-existing tests pass untouched, which is what makes that claim
checkable rather than asserted.
The 400 carries the derivation's own message, so the admin UI names the
offending subpage instead of saying "invalid gallery" — a builder with a
dozen subpages needs to know which one. A test pins that the message
identifies it.
Adds 8 tests: each rejected shape, the named-subpage message, and the
valid structures (standalone albums, subpage membership, sections,
per-album overrides and hero images) so the extraction cannot silently
lose behaviour.
Verified: tsc 0 errors, 170 unit tests passing (162 before), production
build exit 0, eslint 0 errors on touched files.
* fix: hash subpage passwords off the main thread
verifyScrypt used crypto.scryptSync, measured at 22.8ms per call — 22.8ms
during which the Node process serves nothing else, because the sync
variant runs on the main thread rather than the libuv threadpool.
The /api/auth rate limit does not contain this. It allows 10 attempts per
minute, but the bucket key is the client IP, and with the default
TRUSTED_PROXY_HOPS=0 that IP is read from x-real-ip / x-forwarded-for —
both attacker-controlled. lib/rate-limit.ts already documents that those
headers are spoofable at hops=0; what followed from it was not written
down anywhere: one attacker rotating a header gets unlimited buckets, and
each request buys 22.8ms of dead process. Roughly 44 requests per second
saturates it.
Switches verifyScrypt and generateScryptHash to the async crypto.scrypt,
which runs on the threadpool. This does not stop the spoofing — that is
inherent to hops=0 and already documented — it removes the amplification
that made spoofing worth doing.
authenticate() becomes async. It had exactly one caller
(app/api/auth/route.ts). isAuthenticated() is deliberately left
synchronous: it only computes an HMAC, and it is called from server
components.
Adds 4 tests, two of which pin the fix and were mutation-checked against
the old implementation — both fail with scryptSync and pass with scrypt.
One asserts scryptSync is never called; the other asserts a 2ms interval
still fires during a hash, which is the property that actually matters. A
slower machine lengthens the hash and yields more ticks, so that test
fails on a blocked loop rather than on a busy one.
Also adds a scrypt-hashed fixture subpage, so the suite exercises
verifyScrypt rather than only the deprecated plaintext fallback.
Verified: tsc 0 errors, 174 unit tests passing (170 before), production
build exit 0, eslint 0 errors on touched files.
* fix: warn when TRUSTED_PROXY_HOPS cannot identify a client
getClientIp falls back to a shared 'unknown' bucket whenever the
X-Forwarded-For chain is shorter than the configured hop count, or the
header is absent with hops > 1.
That fallback is correct — the alternative is trusting a spoofable entry —
but it was silent, and silence is the problem. Every unidentified request
shares one bucket per endpoint, and this is an image proxy: a single
50-photo grid issues ~50 /api/image requests, so the default
RATE_LIMIT_RPM=1500 is collectively spent by roughly 30 page loads a
minute. Someone who sets TRUSTED_PROXY_HOPS=2 for Cloudflare-plus-nginx
and then reaches nginx directly gets a site that 429s everyone, with
nothing in the log pointing at the cause.
Warns once per process, naming the configured hop count and what was
actually seen — the chain length, or which header was missing. Once, not
per request: enough to diagnose without flooding the log.
The fallback itself is unchanged. Trusting a shorter chain would hand
every client its own bucket key and defeat the limiter entirely.
No warning at hops=0, where the shared bucket is the documented
consequence of not declaring a proxy rather than a misconfiguration.
Adds 6 tests covering each fall-through path, the once-per-process
behaviour, and both silence cases. The once-per-process flag needs a test
seam to re-arm, hence the __resetProxyWarningForTests export.
Verified: tsc 0 errors, 180 unit tests passing (174 before), production
build exit 0, eslint 0 errors on touched files.
* fix: send Retry-After on every rate-limited response
/api/image, /api/video and /api/exif each computed the retry delay,
interpolated it into a console.warn, and then returned a 429 without it —
the number was calculated and thrown away. /api/og did not compute it at
all. Only /api/auth and /api/map sent the header.
This matters more for an image proxy than for a typical API: one gallery
page issues around fifty /api/image requests, so a burst that trips the
limit produces fifty rejections carrying no back-off signal. The browser
and next/image then retry on their own schedule — a retry storm against a
server that just reported it was overloaded.
Adds Retry-After and Cache-Control: no-store to all four. no-store because
the success path serves these same URLs as `immutable`.
The delay now comes from a shared retryAfterSeconds() helper rather than
an inline Math.ceil in each route, which also fixes an edge every copy
shared: a window on the point of expiring yields 0, and Retry-After: 0
tells the client to retry immediately, which is the opposite of what a 429
means. A resetAt already in the past yields a negative number, which is
not valid HTTP. The helper floors at 1.
The three routes that already sent the header (/api/auth, /api/map,
/api/admin/auth) and /api/health now use the helper too — leaving four
copies of the buggy arithmetic behind while centralising the rest would
have been worse than not centralising at all.
Adds 2 tests, one of them specifically for the zero-and-negative edge.
Verified: tsc 0 errors, 182 unit tests passing (180 before), production
build exit 0, eslint 0 errors on all ten touched files.
* fix: add an escape hatch for stale browser image caches
Image and video responses are served
`Cache-Control: public, max-age=31536000, immutable`, so a browser does
not revalidate them for a year — the ETag is not even consulted. When
Immich regenerates thumbnails after a job re-run, or a photo is rotated,
the asset ID does not change, so neither does the deterministic token or
the URL. Visitors keep the old rendition, and the webhook that clears the
server-side caches cannot reach a browser. The only existing remedy was
rotating AUTH_SECRET, which invalidates every token on the site.
Corrects the framing this started from. The finding described it as an
ETag problem, but `immutable` means the ETag is never reached in the case
that matters. The URL is the only lever a browser cache responds to, so
the buster belongs there. It is also mixed into the ETag, since a matching
ETag across two different URLs would be wrong regardless.
Adds IMAGE_CACHE_VERSION, empty by default. Unset, the generated URLs are
byte-identical to before — a test asserts exactly that, because a
cache-busting feature that changes URLs when nobody asked for it would
silently discard every visitor's cache on deploy.
The value is URL-encoded at parse time; an unescaped one could otherwise
inject query parameters into every image URL on the site.
Deliberately not done: shortening max-age or dropping `immutable`. Both
trade a large, real bandwidth win for a rare correctness case, and the
cost is not measurable from this worktree. The aggressive caching stays
the default; this only adds a way out.
Adds 6 tests: default-unchanged, whitespace treated as unset, both URL
shapes, escaping, and that a bump changes the query while leaving the
token intact.
Verified: tsc 0 errors, 188 unit tests passing (182 before), production
build exit 0, eslint unchanged (the one error in env.ts is pre-existing,
confirmed against a stashed tree).
* security: validate the backup filename before restoring from it
restoreBackup() joined its argument straight into a path and copied the
result over a content file. path.join resolves `..`, so
restoreBackup('../../../../etc/passwd') would have written any readable
file over content/settings.yaml — whose contents the admin GET endpoints
hand straight back. The destination was chosen by
backupFilename.includes('gallery.yaml'), which is substring matching on
the same attacker-supplied string, so the caller picked that too.
Not exploitable today: the function has zero callers. That is precisely
why it was worth fixing rather than leaving — it is an exported function
carrying a traversal bug, waiting for whoever wires up the restore button
the admin panel does not yet have.
Hardened rather than deleted. The status endpoint already reports backup
counts, so restore is plainly intended; removing a half-built feature is
the maintainer's call, not a side effect of a security fix.
The name must now match the pattern this service itself produces, and the
destination is derived from the matched group rather than a substring
search. The redundant basename check is kept on purpose: it preserves the
guarantee if that pattern is ever loosened.
Adds 12 tests. Nine of them fail against the unguarded version —
mutation-checked by removing the guard and confirming, rather than
assuming they would.
Verified: tsc 0 errors, 200 unit tests passing (188 before), production
build exit 0, eslint 0 errors on touched files.
* fix: give each admin save its own temp file
writeYamlFile wrote to a constant `${filePath}.tmp` before renaming. The
rename is what makes the write atomic; the temp filename was not. Two
saves of the same file in flight at once shared that path, so the second
writeFile could interleave with the first's rename — publishing one save's
bytes under the other's, or a truncated mix of both. A double-clicked Save
in the page builder is enough to reach it.
The temp name now carries the pid and a per-process counter, so concurrent
writers cannot collide either within a process or across workers.
Also wraps the write and rename so a failure unlinks the temp file instead
of leaving it in content/. The cleanup swallows its own errors: failing to
tidy up must not replace the real error with a misleading one.
Adds 7 tests, and both halves were mutation-checked independently —
reverting to the fixed temp path fails two of them, removing the cleanup
fails two others. Two of the tests exist to pin properties that are easy
to regress silently: that the rename targets the temp file just written,
and that the happy path issues no unlink.
Verified: tsc 0 errors, 207 unit tests passing (200 before), production
build exit 0, eslint 0 errors on touched files.
* fix: await the stream-timeout rejection before advancing timers
`npm run test:unit` exited 1 even though all 207 tests passed. The
timeout test started `streamAsset`, advanced the fake timers past the
15s budget, and only then attached the rejection expectation. The abort
fires *during* `advanceTimersByTimeAsync`, so for one microtask turn the
promise was rejected with no handler attached — Node reports that as an
unhandled rejection, and vitest fails the whole run on it regardless of
test outcomes. CI would have blocked on a green suite.
Attaching the assertion before advancing the timers fixes the ordering
without weakening it: the same rejection and the same `captured.aborted`
check still run, just awaited after the advance rather than created
after it.
Verified: vitest exit 0, 207/207 passing, tsc 0 errors, prettier clean.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix: honour gallery.yaml order for homepage albums
getStandaloneAlbums() filtered the Immich API album list but kept the
API's own (creation/update) order, so reordering the albums list in
gallery.yaml or the admin panel had no effect on the homepage. Sort by
the config list's index instead.
Fixes#352
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: serve fresh settings after admin save without restart
getConfig() short-circuited on a per-worker in-memory cache in
production. Admin saves invalidate that cache only in the worker that
handles the API request; when Next.js renders pages in a different
worker/process, its copy stayed stale until a container restart.
Drop the in-memory config cache entirely and rebuild the config per
call. Freshness comes from the existing mtime-checked YAML cache in
loadYaml() — one statSync per file, negligible next to Immich API
calls, and the same behaviour dev mode has always had.
Fixes#351
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Seven security issues from an audit, plus album pages and the map coming
up empty against Immich 3.x. Verified against a real Immich 3.0.3
instance in a production build.
Security:
- Admin session forgery via a hardcoded 'dev-fallback-secret' signing key
that bypassed the production AUTH_SECRET guard
- /api/map ignored album passwords and returned working asset tokens;
rewriting ?size=thumbnail to ?size=original downloaded full-resolution
originals from protected albums
- Admin login had no rate limit, and the client IP came from a spoofable
header, so rotating it bypassed every limit in the app
- Raw Immich asset UUIDs were serialized into the RSC payload
- Album tokens never expired server-side; a captured token replayed forever
- Path traversal into the Immich API via an unvalidated album id
- /admin ran with no enforced CSP (only Report-Only reached it)
TRUSTED_PROXIES is replaced by TRUSTED_PROXY_HOPS. The old variable
matched proxy IPs against the socket peer address, which self-hosted
Next.js never exposes, so the check could never pass: unset, the limiter
read a spoofable header; set, every request shared one bucket and a single
client could rate-limit the whole site. Migrates automatically.
Immich 3.x: GET /albums/:id no longer embeds assets. Assets now come from
POST /search/metadata with withExif: true — without that flag EXIF is
omitted and grid aspect ratios, the lightbox panel and map markers stay
empty. Drops support for Immich below 3.0, which now logs a warning.
Upgrade: requires Immich 3.0+; set TRUSTED_PROXY_HOPS (nginx = 1);
visitors of protected areas and admin sessions must log in once more.
91 unit tests (25 new); the new admin-auth and rate-limit cases were
confirmed to fail against the pre-fix code.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
When saving gallery/settings via admin, the config cache was invalidated
but the Immich album cache (which stores resolved title overrides and
descriptions) was not cleared. This meant changes only appeared after
the TTL expired or a manual 'Reload' click.
Now both gallery and settings saves also call immich.invalidateAll()
to flush the album cache, making changes visible on next page load.
- Add /api/video/[id] route with Range header support for seeking
- Add /api/webhook route for Immich event-driven cache invalidation
- Add streamVideo() to ImmichClient with 206 Partial Content support
- Support album description overrides in gallery.yaml
- Add videoUrl() helper to lib/urls.ts
- Export cache.delete() and cache.clear() methods
Add Promise deduplication (request coalescing) to the `getAssetInfo`
method in `ImmichClient` (`lib/immich.ts`) to prevent concurrent
identical requests from firing multiple times to the Immich server.
This is particularly helpful when calling `Promise.all` on multiple
assets concurrently (e.g. hero images on the homepage or multiple
album cover placeholder hashes).
Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
- Extract EXIF and Swipe logic into custom hooks for Lightbox
- Extract Map layout data formatting into mapService
- Extract AlbumDetailView and SubpageGridView components from page router
- Restructure monolithic config.ts into clean config/ directory
- /map page with Leaflet (CartoDB dark tiles)
- Photos clustered by city/country (not per-photo)
- /api/map endpoint with encrypted cover asset IDs
- Configurable via gallery.yaml (map: true/false)
- Conditional nav link in header
- CSP updated for Leaflet CDN and tile servers
- Theme-aware popups with cover thumbnails and album links
- Hero carousel: gallery.yaml hero accepts single UUID or array, crossfade component
- Full-bleed single albums: subpages with 1 album skip grid, render photos directly
- EXIF on hover: camera/lens/focal length overlay on grid items (toggle via exifOnHover)
- Customizable grid: columns/gap/aspectRatio/layout (masonry|uniform) via gallery.yaml
- Per-subpage grid overrides: each subpage can override global grid config
- True masonry: per-image aspect ratios from EXIF dimensions
- next/image migration: homepage hero, album covers, grid thumbnails, about portrait
- ThumbHash blur placeholders and dominant color backgrounds
- Custom next/image loader via image proxy with width/quality params
- Lightbox fade-in transition with dominant color background
- Password-protected subpages, health check, rate limiting, OG images
