Update docs

This commit is contained in:
Alan Grainger
2026-10-07 18:04:57 +13:00
parent 7a9ff2e6ee
commit 172f247418
14 changed files with 243 additions and 37 deletions
+3 -2
View File
@@ -328,9 +328,10 @@ if (getConfigOption('ipp.showHomePage', true)) {
}
/*
* Send a 404 for all other routes
* Send a 404 for all other routes and methods. `all`, so a POST or DELETE to an
* unknown path gets the same policy instead of Express's own HTML error page.
*/
app.get('*', (req, res) => {
app.all('*', (req, res) => {
respondToInvalidRequest(res, 404, 'Invalid route ' + req.path)
})
+7 -3
View File
@@ -58,7 +58,8 @@ A reverse proxy or CDN in front of the service can have a lower limit of its own
Files accepted per minute from one visitor address to one share. Over the limit, the service answers with the time to
wait, and the page sends the file again after it, up to three tries. A wait of more than a minute is shown as a
failure with a retry button instead. `0` turns the limit off.
failure with a retry button instead. `0` turns the limit off. A request the service refuses, for example for its
size or type, does not count.
The address is the one that connects to the service. Behind a reverse proxy every visitor has the proxy's address, so
the limit covers each share as a whole.
@@ -71,6 +72,9 @@ MB accepted per share per hour, from all visitors together. Each file's declared
starts and released if the upload fails. A file that would exceed the budget is refused until the hour ends. `0`
turns the budget off.
An upload that delivers less than 8 KB/s over a minute is dropped and its reservation released, so a stalled
connection cannot hold the budget. The page retries a dropped upload.
### `filenamePrefix`
**Type:** `string` · **Default:** `"ipp_upload_"`
@@ -158,10 +162,10 @@ one of these codes and a short reason, which the page shows to the visitor:
| Code | Reason |
|------|------------------------------------------------------------------------------------------------------------------|
| 400 | The filename has no extension, or Immich refused the file, for example because the owner's storage quota is full. |
| 400 | The file is empty, the filename has no extension, or Immich refused the file, for example because the owner's storage quota is full. |
| 403 | The share no longer accepts uploads. |
| 411 | The request has no `Content-Length` header. |
| 413 | The file is larger than `maxFileSize`, sent more bytes than its `Content-Length` declared, or the share has used its `byteBudget` for the hour. |
| 415 | The file is not a photo or a video. SVG files are refused. |
| 415 | The file is not a photo or a video. SVG files are refused, by media type and by extension. |
| 429 | The visitor is over `rateLimit`. `Retry-After` gives the wait in seconds. |
| 502 | Immich could not be reached, or failed. |
+1 -1
View File
@@ -27,7 +27,7 @@
<!-- Reverse proxy -->
<rect x="60" y="130" width="780" height="54" rx="8" fill="#ffffff" stroke="#9aa0b4"/>
<text x="450" y="152" text-anchor="middle" font-size="14" font-weight="600">Your reverse proxy</text>
<text x="250" y="173" text-anchor="middle" fill="#5b6070" font-size="12">everything else</text>
<text x="250" y="173" text-anchor="middle" fill="#5b6070" font-size="12">normal IPP requests</text>
<text x="650" y="173" text-anchor="middle" fill="#4250af" font-size="12">/upload/* (or its own hostname)</text>
<!-- Proxy to containers -->

Before

Width:  |  Height:  |  Size: 6.2 KiB

After

Width:  |  Height:  |  Size: 6.2 KiB

+5 -1
View File
@@ -3,6 +3,7 @@ import cookieSession from 'cookie-session'
import dayjs from 'dayjs'
import { NextFunction, Request, Response } from 'express-serve-static-core'
import { decrypt, encrypt } from './encrypt'
import { isKey } from './immich/client'
import { log } from './utils/log'
import { toString } from './utils/text'
@@ -78,9 +79,12 @@ export function storeUnlock (req: Request, key: string, password: string) {
/**
* Receive an unlock request from the password page (`POST <basePath>/share/unlock`).
* Only a share-shaped key and a string password are stored; anything else is
* ignored, so a stray object never reaches the cookie or the Immich login.
*/
export function unlockHandler (req: Request, res: Response) {
if (req.body.key) storeUnlock(req, req.body.key, req.body.password)
const { key, password } = req.body ?? {}
if (typeof key === 'string' && isKey(key) && typeof password === 'string') storeUnlock(req, key, password)
res.send()
}
+59
View File
@@ -0,0 +1,59 @@
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import express from 'express'
import type { Server } from 'http'
import type { AddressInfo } from 'net'
import { sessionMiddleware, unlockHandler } from '../src/session'
/*
The unlock body is visitor input. Only a share-shaped key with a string
password is stored; anything else is dropped before it reaches the cookie,
so a stray object can never become `req.password` or a session key.
*/
describe('unlockHandler', () => {
let server: Server
let base: string
beforeAll(async () => {
const app = express()
app.use(sessionMiddleware({ name: 'test-session' }))
app.use(express.json())
app.post('/share/unlock', unlockHandler)
await new Promise<void>(resolve => {
server = app.listen(0, resolve)
})
base = 'http://127.0.0.1:' + (server.address() as AddressInfo).port
})
afterAll(() => server?.close())
async function unlock (body: unknown): Promise<Response> {
return fetch(base + '/share/unlock', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body)
})
}
it('stores a share-shaped key with a string password', async () => {
const res = await unlock({ key: 'abc-DEF_123', password: 'hunter2' })
expect(res.status).toBe(200)
expect(res.headers.get('set-cookie')).toContain('test-session=')
})
it('ignores a key that is not share-shaped', async () => {
for (const key of ['../../etc', '__proto__', 'a b', '', 42, { k: 1 }]) {
const res = await unlock({ key, password: 'hunter2' })
expect(res.status).toBe(200)
expect(res.headers.get('set-cookie')).toBeNull()
}
})
it('ignores a password that is not a string', async () => {
for (const password of [{ nested: true }, ['a'], 42, null, undefined]) {
const res = await unlock({ key: 'abc', password })
expect(res.status).toBe(200)
expect(res.headers.get('set-cookie')).toBeNull()
}
})
})
+2 -2
View File
@@ -7,7 +7,7 @@
// to the request body.
import { createLimiter } from '../shared/limiter.js'
import { fileType, formatSize, isUploadableType } from '../shared/upload.js'
import { fileType, formatSize, isUploadableName, isUploadableType } from '../shared/upload.js'
import type { UploadErrorResponse, UploadPageConfig, UploadResponse } from '../shared/upload.js'
import {
ICON_ALERT_CIRCLE,
@@ -305,7 +305,7 @@ function queueFiles (files: File[]) {
const type = fileType(file.name, file.type)
const row = addRow(file, type)
stats.total++
if (!isUploadableType(type)) {
if (!isUploadableType(type) || !isUploadableName(file.name)) {
finish(row, 'error', 'Only photos and videos can be sent')
} else if (file.size > config.maxFileSize) {
finish(row, 'error', 'Larger than the ' + formatSize(config.maxFileSize) + ' limit')
+8 -1
View File
@@ -2,6 +2,13 @@ import { sanitize } from '@ipp/core'
const MAX_FILENAME_LENGTH = 254
/*
Zero-width and bidirectional format characters: invisible in Immich and in a
notification, or able to make `holiday\u202Egpj.mp4` read as `holiday4pm.jpg`.
`sanitize` strips C0/C1 controls only.
*/
const formatCharsRe = /[\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g
/**
* Turn the visitor-supplied filename into the name Immich will store, with
* `prefix` applied once. Returns undefined when nothing usable is left, or
@@ -10,7 +17,7 @@ const MAX_FILENAME_LENGTH = 254
*/
export function uploadFilename (raw: unknown, prefix: string): string | undefined {
if (typeof raw !== 'string') return undefined
const base = raw.split(/[\\/]/).pop() || ''
const base = (raw.normalize('NFC').replace(formatCharsRe, '').split(/[\\/]/).pop() || '')
// Split the extension off first: `sanitize` truncates at 254 characters,
// which on a very long name would cut the extension away.
const parts = base.match(/^(.*)(\.[A-Za-z0-9]{1,16})$/)
+24 -13
View File
@@ -1,29 +1,40 @@
import { Transform } from 'stream'
/** The error an idle stream is destroyed with. */
/** The error a stalled stream is destroyed with. */
export class IdleTimeoutError extends Error {}
/**
* A pass-through Transform that destroys itself if no data flows through for
* `idleMs`. The timer is set when the transform is created and reset on every
* chunk, so a slow-but-steady download (large video over a slow link) keeps
* going, while a genuinely stalled connection still fails fast.
* A pass-through Transform that destroys itself when fewer than `minBytes`
* flow through it in any `idleMs` interval. The check is armed when the
* transform is created, so a body that never starts also times out.
*
* With `minBytes` left at 1 this is a plain idle timeout: a slow-but-steady
* stream keeps going, a stalled one fails. A higher `minBytes` is a floor on
* throughput, which stops a trickle of one byte a minute holding the
* resources an upload reserved for as long as the sender likes.
*/
export function createIdleTimeoutStream (idleMs: number): Transform {
let timer: NodeJS.Timeout | undefined
export function createIdleTimeoutStream (idleMs: number, minBytes = 1): Transform {
let received = 0
const check = () => {
if (received < minBytes) {
transform.destroy(new IdleTimeoutError(`Fewer than ${minBytes} bytes received in ${idleMs}ms`))
}
received = 0
}
const timer = setInterval(check, idleMs)
const transform: Transform = new Transform({
transform (chunk, _, cb) {
if (timer) clearTimeout(timer)
timer = setTimeout(() => transform.destroy(new IdleTimeoutError(`No data received for ${idleMs}ms`)), idleMs)
received += chunk.length
cb(null, chunk)
},
flush (cb) {
if (timer) clearTimeout(timer)
clearInterval(timer)
cb()
},
destroy (err, cb) {
clearInterval(timer)
cb(err)
}
})
// Arm the timer immediately so a response that returns headers but never
// sends a body also times out.
timer = setTimeout(() => transform.destroy(new IdleTimeoutError(`No data received for ${idleMs}ms`)), idleMs)
return transform
}
+3 -1
View File
@@ -56,9 +56,11 @@ for (const dir of ['public', CORE_PUBLIC_DIR]) {
router.use('/share/static', express.static(dir))
}
// Everything past the static assets is never cached
// Everything past the static assets is never cached, and no page may be framed
router.use((_req, res, next) => {
addNoStoreHeaders(res)
res.set('X-Frame-Options', 'DENY')
res.set('Content-Security-Policy', "frame-ancestors 'none'")
next()
})
router.use(sessionMiddleware({ name: 'upload-session' }))
+24 -12
View File
@@ -9,7 +9,7 @@ import { authoriseUpload } from './gate'
import { createIdleTimeoutStream, IdleTimeoutError } from './idleTimeoutStream'
import { createWindowBudget } from './limits'
import { buildNotification, sendNotification } from './notify'
import { formatSize, isUploadableType } from './shared/upload'
import { formatSize, isUploadableName, isUploadableType } from './shared/upload'
/*
The visitor-facing half of the upload path: validate one request, then
@@ -21,8 +21,14 @@ import { formatSize, isUploadableType } from './shared/upload'
written to disk.
*/
// A body that sends nothing for this long is dropped
/*
A body that delivers less than this in any one-minute interval is dropped.
The floor is far below any phone uplink (8 KB/s is 64 kbit/s), yet it means
a connection that trickles bytes to keep its byte-budget reservation alive
has to keep spending real bandwidth to do so.
*/
const BODY_IDLE_MS = 60_000
const BODY_MIN_BYTES_PER_INTERVAL = 8 * 1024 * BODY_IDLE_MS / 1000
/**
* Answer an upload the server will not take, in the shape the page reads.
@@ -71,18 +77,15 @@ export function createUploadReceiver () {
}
const shareId = link.id || key
const rated = rate(req.ip + ':' + shareId)
if (!rated.ok) {
res.set('Retry-After', String(rated.retryAfterSeconds))
refuse(res, 429, 'Too many uploads. Wait a moment and try again.')
return
}
const length = declaredLength(req.headers['content-length'])
if (length === undefined) {
refuse(res, 411, 'The upload has no Content-Length')
return
}
if (length === 0) {
refuse(res, 400, 'The file is empty')
return
}
if (length > maxBytes) {
refuse(res, 413, 'Larger than the ' + formatSize(maxBytes) + ' limit')
return
@@ -95,11 +98,20 @@ export function createUploadReceiver () {
}
const mimeType = (req.headers['content-type'] || '').split(';')[0].trim().toLowerCase()
if (!isUploadableType(mimeType)) {
if (!isUploadableType(mimeType) || !isUploadableName(filename)) {
refuse(res, 415, 'Only photos and videos can be sent')
return
}
// Charged only once the request is one the service would take, so a
// stream of malformed requests cannot use up everyone's allowance
const rated = rate(req.ip + ':' + shareId)
if (!rated.ok) {
res.set('Retry-After', String(rated.retryAfterSeconds))
refuse(res, 429, 'Too many uploads. Wait a moment and try again.')
return
}
// Reserved before streaming, so parallel uploads cannot overshoot the budget together
const reserved = budget(shareId, length)
if (!reserved.ok) {
@@ -108,8 +120,8 @@ export function createUploadReceiver () {
return
}
const body = pipeline(req, createIdleTimeoutStream(BODY_IDLE_MS), err => {
if (err instanceof IdleTimeoutError) log('Dropped upload ' + filename + ': nothing received for ' + BODY_IDLE_MS / 1000 + ' s')
const body = pipeline(req, createIdleTimeoutStream(BODY_IDLE_MS, BODY_MIN_BYTES_PER_INTERVAL), err => {
if (err instanceof IdleTimeoutError) log('Dropped upload ' + filename + ': too little received in ' + BODY_IDLE_MS / 1000 + ' s')
})
const result = await forwardUpload(permit, {
filename,
+13
View File
@@ -18,6 +18,19 @@ export function isUploadableType (mimeType: string): boolean {
return type.startsWith('image/') || type.startsWith('video/')
}
// Extensions Immich stores as SVG, whatever media type the request declares
const REFUSED_EXTENSIONS = new Set(['svg', 'svgz'])
/**
* Whether a file with this name may be sent. The media type is the sender's
* claim and Immich types the stored asset by its extension, so the SVG rule
* has to hold on the name as well or `evil.svg` sent as `image/jpeg` gets in.
*/
export function isUploadableName (filename: string): boolean {
const extension = filename.split('.').pop()?.toLowerCase() || ''
return !REFUSED_EXTENSIONS.has(extension)
}
/*
Types for files a desktop browser reports with an empty or generic `File.type`: HEIC,
HEIF, camera RAW and some video containers. Immich types the asset by its
+11
View File
@@ -15,6 +15,17 @@ describe('uploadFilename', () => {
expect(uploadFilename('we"rd:na*me.jpg', '')).toBe('werdname.jpg')
})
it('removes zero-width and direction-changing characters', () => {
expect(uploadFilename('holiday\u202Egpj.mp4', '')).toBe('holidaygpj.mp4')
expect(uploadFilename('IMG\u200B_0042\uFEFF.jpg', '')).toBe('IMG_0042.jpg')
// Only format characters go: a bidi override cannot hide a dotfile
expect(uploadFilename('\u202E.htaccess', '')).toBeUndefined()
})
it('normalises to NFC so one name has one spelling', () => {
expect(uploadFilename('Cafe\u0301.jpg', '')).toBe('Caf\u00E9.jpg')
})
it('rejects a name with no extension', () => {
expect(uploadFilename('photo', '')).toBeUndefined()
})
@@ -0,0 +1,68 @@
import { describe, it, expect, vi, afterEach } from 'vitest'
import { createIdleTimeoutStream, IdleTimeoutError } from '../src/idleTimeoutStream'
afterEach(() => vi.useRealTimers())
/** Resolve with the stream's error, or undefined when it ends cleanly. */
function outcome (stream: NodeJS.ReadableStream): Promise<Error | undefined> {
return new Promise(resolve => {
stream.on('data', () => {})
stream.on('error', resolve)
stream.on('end', () => resolve(undefined))
})
}
describe('createIdleTimeoutStream', () => {
it('drops a body that never starts', async () => {
vi.useFakeTimers()
const stream = createIdleTimeoutStream(1000)
const result = outcome(stream)
await vi.advanceTimersByTimeAsync(1000)
expect(await result).toBeInstanceOf(IdleTimeoutError)
})
it('keeps a slow but steady body flowing', async () => {
vi.useFakeTimers()
const stream = createIdleTimeoutStream(1000)
const result = outcome(stream)
for (let i = 0; i < 5; i++) {
stream.write(Buffer.alloc(1))
await vi.advanceTimersByTimeAsync(900)
}
stream.end()
expect(await result).toBeUndefined()
})
it('drops a body that trickles below the byte floor', async () => {
vi.useFakeTimers()
const stream = createIdleTimeoutStream(1000, 100)
const result = outcome(stream)
stream.write(Buffer.alloc(99))
await vi.advanceTimersByTimeAsync(1000)
expect(await result).toBeInstanceOf(IdleTimeoutError)
})
it('keeps a body that meets the byte floor in every interval', async () => {
vi.useFakeTimers()
const stream = createIdleTimeoutStream(1000, 100)
const result = outcome(stream)
for (let i = 0; i < 3; i++) {
stream.write(Buffer.alloc(50))
await vi.advanceTimersByTimeAsync(400)
stream.write(Buffer.alloc(50))
await vi.advanceTimersByTimeAsync(600)
}
stream.end()
expect(await result).toBeUndefined()
})
it('stops its timer when the body ends, so a small file is never judged by a partial interval', async () => {
vi.useFakeTimers()
const stream = createIdleTimeoutStream(1000, 100)
const result = outcome(stream)
stream.end(Buffer.alloc(10))
expect(await result).toBeUndefined()
await vi.advanceTimersByTimeAsync(5000)
expect(vi.getTimerCount()).toBe(0)
})
})
+15 -1
View File
@@ -1,5 +1,5 @@
import { describe, it, expect } from 'vitest'
import { fileType, formatSize, isUploadableType } from '../src/shared/upload'
import { fileType, formatSize, isUploadableName, isUploadableType } from '../src/shared/upload'
import { declaredLength, uploadTimestamp } from '../src/receive'
describe('isUploadableType', () => {
@@ -22,6 +22,20 @@ describe('isUploadableType', () => {
})
})
describe('isUploadableName', () => {
it('refuses an SVG extension whatever type the request declares', () => {
expect(isUploadableName('evil.svg')).toBe(false)
expect(isUploadableName('ipp_upload_evil.SVG')).toBe(false)
expect(isUploadableName('evil.svgz')).toBe(false)
})
it('accepts photo and video extensions, and leaves the finer check to Immich', () => {
expect(isUploadableName('IMG_0042.jpg')).toBe(true)
expect(isUploadableName('clip.mp4')).toBe(true)
expect(isUploadableName('my.svg.jpg')).toBe(true)
})
})
describe('fileType', () => {
it('keeps the type the browser gave', () => {
expect(fileType('IMG_0042.HEIC', 'image/heic')).toBe('image/heic')