From aa6183a95d69fe7d3379100a3dc2eb612218bf20 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Fri, 24 Jul 2026 22:15:17 +1200 Subject: [PATCH] Better error handling, and handling of numeric config options --- app/src/config/access.ts | 9 ++++ app/src/gallery/builder.ts | 5 +- app/src/http.ts | 28 ++++++++++- app/src/index.ts | 40 +++++++++------- app/src/shared/types.ts | 4 +- app/src/stream/download.ts | 4 +- app/src/utils/text.ts | 13 ++++++ app/src/view/gallery.tsx | 3 +- app/tests/errorHandling.test.ts | 77 +++++++++++++++++++++++++++++++ app/tests/escapeHtml.test.ts | 26 ----------- app/tests/galleryInitJson.test.ts | 59 +++++++++++++++++++++++ app/tests/numericConfig.test.ts | 75 ++++++++++++++++++++++++++++++ app/tests/text.test.ts | 53 +++++++++++++++++++++ 13 files changed, 345 insertions(+), 51 deletions(-) create mode 100644 app/tests/errorHandling.test.ts delete mode 100644 app/tests/escapeHtml.test.ts create mode 100644 app/tests/galleryInitJson.test.ts create mode 100644 app/tests/numericConfig.test.ts create mode 100644 app/tests/text.test.ts diff --git a/app/src/config/access.ts b/app/src/config/access.ts index baa2882..57d0fb6 100644 --- a/app/src/config/access.ts +++ b/app/src/config/access.ts @@ -17,3 +17,12 @@ export function getConfigOption (path: string, defaultOption?: unknown) { } return value } + +/** + * Read a configuration option that must be a finite number. Non-numeric + * values fall back to `defaultOption` instead of propagating `NaN`. + */ +export function getNumericConfigOption (path: string, defaultOption: number): number { + const value = Number(getConfigOption(path, defaultOption)) + return Number.isFinite(value) ? value : defaultOption +} diff --git a/app/src/gallery/builder.ts b/app/src/gallery/builder.ts index 95568eb..118e29e 100644 --- a/app/src/gallery/builder.ts +++ b/app/src/gallery/builder.ts @@ -5,7 +5,7 @@ import { } from '../immich' import { Response } from 'express-serve-static-core' import { AssetType, ImageSize, SharedLink } from '../types' -import { getConfigOption } from '../config/access' +import { getConfigOption, getNumericConfigOption } from '../config/access' import { canDownload, expiryDate, title } from '../share' import { toString } from '../utils/text' import { h } from 'preact' @@ -164,8 +164,7 @@ export async function gallery (res: Response, share: SharedLink, openItem?: numb } // HTML gallery page cache time - const configured = Number(getConfigOption('ipp.gallery.cacheTime', 300)) - const cacheTime = Number.isFinite(configured) ? Math.max(0, configured) : 300 + const cacheTime = Math.max(0, getNumericConfigOption('ipp.gallery.cacheTime', 300)) res.header('Cache-Control', 'public, max-age=' + cacheTime) res.send(renderPage(h(Gallery, props))) } diff --git a/app/src/http.ts b/app/src/http.ts index cfe073f..fa78ae5 100644 --- a/app/src/http.ts +++ b/app/src/http.ts @@ -1,5 +1,7 @@ -import { Response } from 'express-serve-static-core' +import { NextFunction, Request, Response } from 'express-serve-static-core' import { getConfigOption } from './config/access' +import { respondToInvalidRequest } from './invalidRequestHandler' +import { log } from './utils/log' /** * Apply the response headers configured under `ipp.responseHeaders` to the @@ -12,3 +14,27 @@ export function addResponseHeaders (res: Response): void { res.set(header, value) }) } + +/** + * Wrap an async route handler so a rejected promise is passed to Express's + * error chain (and on to `errorHandler`). + */ +export function asyncHandler (fn: (req: Request, res: Response, next: NextFunction) => Promise) { + return (req: Request, res: Response, next: NextFunction): void => { + fn(req, res, next).catch(next) + } +} + +/** + * Terminal Express error middleware. Logs the error server-side, then applies the + * same privacy policy as any other invalid request. + */ +export function errorHandler (err: unknown, req: Request, res: Response, _next: NextFunction): void { + log.error('Error handling ' + req.method + ' ' + req.path + ' - ' + + (err instanceof Error ? (err.stack || err.message) : String(err))) + if (res.headersSent) { + res.end() + return + } + respondToInvalidRequest(res, 404, 'Unhandled error for ' + req.path) +} diff --git a/app/src/index.ts b/app/src/index.ts index 38a2efe..3364989 100644 --- a/app/src/index.ts +++ b/app/src/index.ts @@ -22,7 +22,7 @@ import { NextFunction, Request, Response } from 'express-serve-static-core' import { Asset, AssetType, ImageSize, KeyType, SharedLink } from './types' import { getConfigOption } from './config/access' import { loadConfig } from './config/loader' -import { addResponseHeaders } from './http' +import { addResponseHeaders, asyncHandler, errorHandler } from './http' import { canDownload } from './share' import { toString } from './utils/text' import { decrypt, encrypt } from './encrypt' @@ -140,18 +140,18 @@ async function resolveSharedAsset (req: Request, keyType: KeyType): Promise { +app.get(/^(|\/share)\/healthcheck$/, asyncHandler(async (_req, res) => { if (await accessible()) { res.send('ok') } else { res.status(503).send() } -}) +})) /* * [ROUTE] This is the main URL that someone would visit if they are opening a shared link */ -app.get('/:shareType(share|s)/:key/:mode(download)?', decodeCookie, async (req, res) => { +app.get('/:shareType(share|s)/:key/:mode(download)?', decodeCookie, asyncHandler(async (req, res) => { const keyType = getKeyTypeFromShare(req.params.shareType) if (keyType === KeyType.slug && !getConfigOption('ipp.allowSlugLinks', true)) { @@ -166,7 +166,7 @@ app.get('/:shareType(share|s)/:key/:mode(download)?', decodeCookie, async (req, password: req.password }, res) } -}) +})) /* * [ROUTE] Receive an unlock request from the password page @@ -177,7 +177,7 @@ app.get('/:shareType(share|s)/:key/:mode(download)?', decodeCookie, async (req, * managing user session data. The data is provided to the server by the * user's browser in its encrypted state. */ -app.post('/share/unlock', async (req, res) => { +app.post('/share/unlock', asyncHandler(async (req, res) => { if (req.session && req.body.key) { req.session[req.body.key] = encrypt(JSON.stringify({ password: req.body.password, @@ -185,7 +185,7 @@ app.post('/share/unlock', async (req, res) => { })) } res.send() -}) +})) /* * [ROUTE] Selective download - POST a list of asset IDs, get a zip of just those. @@ -193,7 +193,7 @@ app.post('/share/unlock', async (req, res) => { * Validates each ID against share.assets so the request can't pull anything * outside the share. */ -app.post('/:shareType(share|s)/:key/download', decodeCookie, async (req, res) => { +app.post('/:shareType(share|s)/:key/download', decodeCookie, asyncHandler(async (req, res) => { const keyType = getKeyTypeFromShare(req.params.shareType) let requestedIds: unknown try { @@ -225,7 +225,7 @@ app.post('/:shareType(share|s)/:key/download', decodeCookie, async (req, res) => } await downloadAssets(res, resolved.link, validAssets) -}) +})) /* * [ROUTE] Catch accidental POST requests to share URLs (e.g. from browser history @@ -239,7 +239,7 @@ app.post('/:shareType(share|s)/:key/:mode(download)?', (req, res) => { /* * [ROUTE] This is the direct link to a photo or video asset */ -app.get('/share/:type(photo|video)/:key/:id/:size?', decodeCookie, async (req, res) => { +app.get('/share/:type(photo|video)/:key/:id/:size?', decodeCookie, asyncHandler(async (req, res) => { // Add the headers configured in config.json (most likely `cache-control`) addResponseHeaders(res) @@ -274,8 +274,8 @@ app.get('/share/:type(photo|video)/:key/:id/:size?', decodeCookie, async (req, r key: req.params.key, range: req.headers.range || '' } - assetBuffer(request, res, asset, req.params.size).then() -}) + await assetBuffer(request, res, asset, req.params.size) +})) /* * [ROUTE] On-demand per-asset metadata for lazy album items. @@ -286,7 +286,7 @@ app.get('/share/:type(photo|video)/:key/:id/:size?', decodeCookie, async (req, r * validated against the share's asset set (defence in depth - Immich also * enforces this via the share key) before we fetch `GET /assets/:id`. */ -app.get('/:shareType(share|s)/meta/:key/:id', decodeCookie, async (req, res) => { +app.get('/:shareType(share|s)/meta/:key/:id', decodeCookie, asyncHandler(async (req, res) => { addResponseHeaders(res) const resolved = await resolveSharedAsset(req, getKeyTypeFromShare(req.params.shareType)) @@ -302,7 +302,7 @@ app.get('/:shareType(share|s)/meta/:key/:id', decodeCookie, async (req, res) => } res.json(buildAssetMetadata(detail, resolved.link)) -}) +})) /* * [ROUTE] Home page @@ -327,6 +327,13 @@ app.get('*', (req, res) => { respondToInvalidRequest(res, 404, 'Invalid route ' + req.path) }) +/* + * Terminal error middleware: any throw/rejection inside a route (routed here + * by asyncHandler) is logged and answered per the 404 privacy policy, instead + * of escaping to process level. + */ +app.use(errorHandler) + // Send the correct process error code for any uncaught exceptions // so that Docker can gracefully restart the container process.on('uncaughtException', (err) => { @@ -334,10 +341,11 @@ process.on('uncaughtException', (err) => { server.close() process.exit(1) }) +// Log-only: with asyncHandler routing request errors into errorHandler, a +// stray rejection from a background task (version check, staging-dir sweep, +// etc.) is not worth killing every in-flight request for. process.on('unhandledRejection', (reason, promise) => { console.error('Unhandled Rejection at:', promise, 'reason:', reason) - server.close() - process.exit(1) }) process.on('SIGTERM', () => { console.log('Received SIGTERM. Gracefully shutting down...') diff --git a/app/src/shared/types.ts b/app/src/shared/types.ts index b218d58..92fa3cd 100644 --- a/app/src/shared/types.ts +++ b/app/src/shared/types.ts @@ -96,8 +96,8 @@ export interface MetadataConfig { /** * Shape of the JSON init block embedded in `gallery.tsx` and consumed by - * `client/init.ts`. The server writes it via `JSON.stringify`; the client - * reads it via `readInitParams()`. + * `client/init.ts`. The server writes it via `jsonForInlineScript`; the + * client reads it via `readInitParams()`. */ export interface InitParams { items?: GalleryItem[] diff --git a/app/src/stream/download.ts b/app/src/stream/download.ts index 8f7be94..874c92c 100644 --- a/app/src/stream/download.ts +++ b/app/src/stream/download.ts @@ -1,7 +1,7 @@ import { assetFetchUrl, authHeadersForAsset } from '../immich' import { Response } from 'express-serve-static-core' import { Asset, ImageSize, SharedLink } from '../types' -import { getConfigOption } from '../config/access' +import { getNumericConfigOption } from '../config/access' import { log } from '../utils/log' import archiver, { Archiver } from 'archiver' import { sanitize } from '../utils/sanitize' @@ -96,7 +96,7 @@ export async function downloadAssets (res: Response, share: SharedLink, assets: const options: StagingOptions = { stagingDir: await fs.mkdtemp(join(tmpdir(), STAGING_DIR_PREFIX)), - concurrency: Math.max(1, getConfigOption('ipp.downloadFromImmichConcurrencyLimit', 20) as number), + concurrency: Math.max(1, getNumericConfigOption('ipp.downloadFromImmichConcurrencyLimit', 20)), maxAttempts: 3, headerTimeoutMs: 20_000, idleTimeoutMs: 20_000 diff --git a/app/src/utils/text.ts b/app/src/utils/text.ts index 70dea0c..5bdefae 100644 --- a/app/src/utils/text.ts +++ b/app/src/utils/text.ts @@ -12,6 +12,19 @@ export function escapeHtml (str: string): string { .replace(/'/g, ''') } +/** + * Serialise a value as JSON that is safe to embed inside an inline `` would terminate the script element early and inject markup into + * the page. + */ +export function jsonForInlineScript (value: unknown): string { + return JSON.stringify(value) + .replace(/ { + let server: Server + let base: string + + beforeAll(async () => { + // Silence errorHandler's expected server-side logging during these tests + vi.spyOn(console, 'error').mockImplementation(() => {}) + + const app = express() + app.get('/ok', asyncHandler(async (_req, res) => { res.send('ok') })) + app.get('/boom', asyncHandler(async () => { + throw new TypeError("Cannot read properties of undefined (reading 'headers')") + })) + app.get('/mid-stream', asyncHandler(async (_req, res) => { + res.status(200) + res.write('partial') + throw new Error('upstream died mid-response') + })) + app.use(errorHandler) + + await new Promise(resolve => { + server = app.listen(0, resolve) + }) + base = 'http://127.0.0.1:' + (server.address() as AddressInfo).port + }) + + afterAll(() => { + server?.close() + vi.restoreAllMocks() + }) + + it('turns a rejected route promise into a 404 with an empty body', async () => { + const res = await fetch(base + '/boom') + expect(res.status).toBe(404) + expect(await res.text()).toBe('') + }) + + it('keeps serving other requests after a route has thrown', async () => { + await fetch(base + '/boom') + const res = await fetch(base + '/ok') + expect(res.status).toBe(200) + expect(await res.text()).toBe('ok') + }) + + it('does not leak error detail to the client', async () => { + const res = await fetch(base + '/boom') + const body = await res.text() + expect(body).not.toContain('TypeError') + expect(body).not.toContain('headers') + }) + + it('ends the response when the error hits after headers were sent', async () => { + const res = await fetch(base + '/mid-stream') + // Status was already committed before the throw; the handler can only + // end the stream, not rewrite it to a 404. + expect(res.status).toBe(200) + expect(await res.text()).toBe('partial') + // And the server is still alive afterwards + const ok = await fetch(base + '/ok') + expect(ok.status).toBe(200) + }) +}) diff --git a/app/tests/escapeHtml.test.ts b/app/tests/escapeHtml.test.ts deleted file mode 100644 index 78856c3..0000000 --- a/app/tests/escapeHtml.test.ts +++ /dev/null @@ -1,26 +0,0 @@ -import { describe, it, expect } from 'vitest' -import { escapeHtml } from '../src/utils/text' - -describe('escapeHtml', () => { - it('escapes the five HTML-significant characters', () => { - expect(escapeHtml('')).toBe( - '<script>alert("xss")</script>' - ) - }) - - it('escapes ampersand first so other escapes are not re-escaped', () => { - expect(escapeHtml('&')).toBe('&amp;') - }) - - it('escapes single quotes', () => { - expect(escapeHtml("it's")).toBe('it's') - }) - - it('returns empty string unchanged', () => { - expect(escapeHtml('')).toBe('') - }) - - it('passes through strings with no special characters', () => { - expect(escapeHtml('plain text 123')).toBe('plain text 123') - }) -}) diff --git a/app/tests/galleryInitJson.test.ts b/app/tests/galleryInitJson.test.ts new file mode 100644 index 0000000..d57523b --- /dev/null +++ b/app/tests/galleryInitJson.test.ts @@ -0,0 +1,59 @@ +import { describe, it, expect } from 'vitest' +import { h } from 'preact' +import { Gallery, GalleryProps, GalleryItem } from '../src/view/gallery' +import { renderPage } from '../src/view/render' + +/* + Regression test for the init-JSON XSS: asset strings (originalFileName, EXIF + description/city/make/model) are attacker-influenced and are serialised into + the ` inside + them must not be able to terminate that block and inject markup. +*/ + +function galleryProps (item: Partial): GalleryProps { + return { + items: [{ + id: 'a', + type: 'IMAGE', + previewUrl: '/share/photo/k/a/preview', + thumbnailUrl: '/share/photo/k/a/thumbnail', + downloadFilename: 'photo.jpg', + ...item + }], + title: 'Test gallery', + description: '', + publicBaseUrl: 'https://example.com', + path: '/share/k', + showDownloadZip: false, + showTitle: false, + lightboxConfig: { showArrows: true, showDownload: true, mobileArrows: false, autoPlayVideos: false }, + metadataConfig: { descriptionInCaption: false, descriptionInSidebar: false, sidebarHasContent: false, locationWebLink: false }, + groupByDate: false + } +} + +const payload = '' + +describe('gallery init JSON escaping', () => { + it('neutralises in a crafted download filename', () => { + const html = renderPage(h(Gallery, galleryProps({ downloadFilename: payload }))) + expect(html).not.toContain('') + expect(html).toContain('\\u003c/script>') + }) + + it('neutralises in crafted EXIF metadata', () => { + const html = renderPage(h(Gallery, galleryProps({ + description: payload, + exif: { fileName: payload, city: payload, make: payload } + }))) + expect(html).not.toContain('') + }) + + it('still produces JSON the client can parse back to the same items', () => { + const html = renderPage(h(Gallery, galleryProps({ downloadFilename: payload }))) + const match = html.match(/')).toBe( + '<script>alert("xss")</script>' + ) + }) + + it('escapes ampersand first so other escapes are not re-escaped', () => { + expect(escapeHtml('&')).toBe('&amp;') + }) + + it('escapes single quotes', () => { + expect(escapeHtml("it's")).toBe('it's') + }) + + it('returns empty string unchanged', () => { + expect(escapeHtml('')).toBe('') + }) + + it('passes through strings with no special characters', () => { + expect(escapeHtml('plain text 123')).toBe('plain text 123') + }) +}) + +describe('jsonForInlineScript', () => { + it('escapes < so cannot terminate an inline script block', () => { + const out = jsonForInlineScript({ name: '' }) + expect(out).not.toContain('<') + expect(out).toContain('\\u003c/script>') + }) + + it('round-trips through JSON.parse unchanged', () => { + const value = { + name: ' & \u2028\u2029', + n: 3, + nested: { arr: [1, 'two'] } + } + expect(JSON.parse(jsonForInlineScript(value))).toEqual(value) + }) + + it('escapes the JS line separators U+2028 and U+2029', () => { + const out = jsonForInlineScript({ s: '\u2028\u2029' }) + expect(out).toBe('{"s":"\\u2028\\u2029"}') + }) + + it('matches JSON.stringify for benign values', () => { + const value = { a: 1, b: 'plain text', c: null } + expect(jsonForInlineScript(value)).toBe(JSON.stringify(value)) + }) +})