diff --git a/.gitignore b/.gitignore index d88609c..7aee33b 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ app/public/js/ /app/config.dev.json .npm-cache/ *.tsbuildinfo +upload-app/public/js/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3183a77..db1bf4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,26 +26,27 @@ Request flow for a typical share URL like `https://proxy.example.com/share/ ### Repository layout -The repo is an npm workspace with two packages: `shared/` is `@ipp/core`, the read-side code that IPP shares with the planned upload service, and `app/` is IPP itself. Run `npm install` at the root; there is one lockfile. +The repo is an npm workspace with three packages: `shared/` is `@ipp/core`, the read-side code both apps share; `app/` is IPP itself; and `upload-app/` is the optional upload service, the only code that writes to Immich. Run `npm install` at the root; there is one lockfile. ``` .github/workflows/ CI: builds and pushes Docker image on v* tags package.json Workspace root: scripts that delegate to the workspaces; no dependencies package-lock.json The one lockfile for every workspace -.eslintrc Lint config for both workspaces +.eslintrc Lint config for every workspace shared/ @ipp/core - read-side only, knows nothing about galleries src/ index.ts Barrel: everything the apps import comes from '@ipp/core' types.ts Share-level types (SharedLink, Asset, KeyType, ...) immich/client.ts Immich API request helper, URL building, key/id checks, version guard - immich/share.ts fetchSharedLink, password login + token cache, auth headers, title + immich/share.ts fetchSharedLink, password login + token cache, auth headers, title, slug-link gate config/loader.ts loadConfig() reads env / file; the app passes its default path config/access.ts getConfigOption() reads the loaded config http.ts Operator-configured and no-store response headers, abortOnClose, asyncHandler, CORE_PUBLIC_DIR invalidRequest.ts The 404 policy (never cached), errorHandler, and setInvalidRequestHandler for the app's own handler file session.ts Cookie session, decodeCookie, unlock handler, invalid-password response encrypt.ts Cookie-session encryption for password-protected shares - utils/ log, sanitize (filenames), text (escaping), ttlLruCache, webStream + version.ts App version from APP_VERSION or the app's package.json + utils/ log, sanitize (filenames), text (escaping), ttlLruCache, webStream (incl. streaming request bodies) view/ Page renderer, theme script, password page public/ Static assets both apps serve: pico, Inter font, favicon, theme.css (tokens and page base) tests/ Vitest unit tests for core @@ -77,6 +78,22 @@ app/ thumbhash/, images/ style.css, photoswipe-overrides.css tests/ Vitest unit tests for IPP +upload-app/ immich-public-proxy-upload - one page per share; streams visitor files to Immich's POST /assets + config.json Default ipp.upload.* options; no responseHeaders + src/ + index.ts Express setup and routes, mounted under PUBLIC_BASE_URL's path + config.ts Env and ipp.upload.* readers, base path + share.ts Share lookup through core, cached 60 s + gate.ts The upload permit: the share's Immich toggle and the slug-link gate + receive.ts Validates one upload request: rate limit, length, filename, type, byte budget + forward.ts The only Immich write call: multipart POST /assets under the share key + limits.ts Fixed-window budgets for the rate limit and the byte budget + filename.ts Stored filename: sanitised, prefixed, extension kept + notify.ts Optional JSON webhook per stored file + idleTimeoutStream.ts Drops a request body that stalls + view/upload.tsx The upload page + shared/ Rules and types shared by the server and the page client + tests/ Vitest unit tests for the upload app docs/ User docs site (VitePress); docs/README.md explains its structure Dockerfile Multi-stage build; IPP runs from /app as the non-root `node` user docker-compose.yml Reference deployment @@ -128,7 +145,7 @@ At the repo root: ```bash npm run build # core, then IPP's server and client; output to dist/ and app/public/js/ npm test # vitest run in every workspace (unit tests on pure functions) -npm run lint # ESLint over both workspaces +npm run lint # ESLint over every workspace npm run bump -- 4.0.1 # set the version in every workspace manifest and the lockfile ``` diff --git a/app/src/index.ts b/app/src/index.ts index c75e3d9..ea74212 100644 --- a/app/src/index.ts +++ b/app/src/index.ts @@ -4,7 +4,6 @@ import 'dotenv/config' import express from 'express' import { resolve } from 'path' import { - accessible, addNoStoreHeaders, addResponseHeaders, Asset, @@ -16,6 +15,7 @@ import { errorHandler, getConfigOption, getKeyTypeFromShare, + healthcheck, isId, isKey, KeyType, @@ -25,6 +25,7 @@ import { sessionMiddleware, setInvalidRequestHandler, SharedLink, + slugLinksDisabled, unlockHandler } from '@ipp/core' import { fetchAssetDetail, getShareByKey, handleShareRequest } from './immich' @@ -97,11 +98,6 @@ type SharedAssetResolution = | { ok: true, link: SharedLink, asset: Asset } | { ok: false, status: number, reason: string, passwordRequired?: boolean } -/** Whether this is a slug link and the operator has turned slug links off. */ -function slugLinksDisabled (keyType: KeyType): boolean { - return keyType === KeyType.slug && !getConfigOption('ipp.allowSlugLinks', true) -} - async function resolveShare (req: Request, keyType: KeyType): Promise { if (slugLinksDisabled(keyType)) { return { ok: false, status: 404, reason: 'Slug links are disabled in config.json' } @@ -152,13 +148,7 @@ async function resolveSharedAsset (req: Request, keyType: KeyType, allowMotion = * [ROUTE] Healthcheck * The path matches for /share/healthcheck, and also the legacy /healthcheck */ -app.get(/^(|\/share)\/healthcheck$/, asyncHandler(async (_req, res) => { - if (await accessible()) { - res.send('ok') - } else { - res.status(503).send() - } -})) +app.get(/^(|\/share)\/healthcheck$/, asyncHandler(healthcheck)) /* * [ROUTE] This is the main URL that someone would visit if they are opening a shared link diff --git a/app/src/version.ts b/app/src/version.ts index 17405af..55aafd0 100644 --- a/app/src/version.ts +++ b/app/src/version.ts @@ -1,22 +1,7 @@ -import { readFileSync } from 'fs' import { join } from 'path' +import { resolveAppVersion } from '@ipp/core' -/** - * Resolve the running application version. Prefers the APP_VERSION env var - * baked in at Docker build time (see Dockerfile); falls back to package.json - * for local dev (`npm run dev`), and finally to 'dev' if neither is readable. - */ -function resolveVersion (): string { - if (process.env.APP_VERSION) return process.env.APP_VERSION - try { - const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8')) - return pkg.version || 'dev' - } catch { - return 'dev' - } -} - -export const APP_VERSION = resolveVersion() +export const APP_VERSION = resolveAppVersion(join(__dirname, '..', 'package.json')) /** URL-safe cache-busting segment for static asset paths. */ export const ASSET_VERSION = encodeURIComponent(APP_VERSION) diff --git a/package-lock.json b/package-lock.json index cb58443..dd97168 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,7 +8,8 @@ "name": "immich-public-proxy-workspace", "workspaces": [ "shared", - "app" + "app", + "upload-app" ] }, "app": { @@ -4115,6 +4116,10 @@ "resolved": "app", "link": true }, + "node_modules/immich-public-proxy-upload": { + "resolved": "upload-app", + "link": true + }, "node_modules/import-fresh": { "version": "3.3.0", "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz", @@ -7582,6 +7587,32 @@ "typescript": "^5.6.2", "vitest": "^4" } + }, + "upload-app": { + "name": "immich-public-proxy-upload", + "version": "3.4.1", + "license": "AGPL-3.0", + "dependencies": { + "@ipp/core": "*", + "dayjs": "^1.11.13", + "dotenv": "^16.4.5", + "express": "^4.21.1", + "preact": "^10.29.2", + "tslib": "^2.8.1" + }, + "devDependencies": { + "@types/cookie-session": "^2.0.49", + "@types/express": "^4.17.21", + "@types/node": "^22", + "@typescript-eslint/eslint-plugin": "^7", + "@typescript-eslint/parser": "^7", + "concurrently": "^10.0.3", + "eslint": "^8.57.0", + "eslint-config-standard": "^17.1.0", + "tsx": "^4", + "typescript": "^5.6.2", + "vitest": "^4" + } } } } diff --git a/package.json b/package.json index dd68924..96e947b 100644 --- a/package.json +++ b/package.json @@ -3,12 +3,13 @@ "private": true, "workspaces": [ "shared", - "app" + "app", + "upload-app" ], "scripts": { "build": "npm run build --workspaces", "test": "npm test --workspaces", - "lint": "eslint shared app --ext .ts,.tsx", + "lint": "eslint shared app upload-app --ext .ts,.tsx", "dev": "npm run dev --workspace=app", "bump": "npm version --no-git-tag-version --workspaces" } diff --git a/shared/src/http.ts b/shared/src/http.ts index 3b7c8f3..76830cc 100644 --- a/shared/src/http.ts +++ b/shared/src/http.ts @@ -1,6 +1,7 @@ import { NextFunction, Request, Response } from 'express-serve-static-core' import { resolve } from 'path' import { getConfigOption } from './config/access' +import { accessible } from './immich/client' /** Static assets both apps serve from core: pico, the Inter font, the favicon and theme.css. */ export const CORE_PUBLIC_DIR = resolve(__dirname, '../public') @@ -36,6 +37,15 @@ export function abortOnClose (res: Response): AbortSignal { return controller.signal } +/** `GET /healthcheck`: `ok` while Immich answers, else 503. */ +export async function healthcheck (_req: Request, res: Response): Promise { + if (await accessible()) { + res.send('ok') + } else { + res.status(503).send() + } +} + /** * Wrap an async route handler so a rejected promise is passed to Express's * error chain (and on to `errorHandler`). diff --git a/shared/src/immich/share.ts b/shared/src/immich/share.ts index ef87800..0838238 100644 --- a/shared/src/immich/share.ts +++ b/shared/src/immich/share.ts @@ -1,5 +1,6 @@ import dayjs from 'dayjs' import { KeyType, SharedLink, SharedLinkResult } from '../types' +import { getConfigOption } from '../config/access' import { log } from '../utils/log' import { cachedPromise, TtlLruCache } from '../utils/ttlLruCache' import { apiUrl, buildUrl } from './client' @@ -16,6 +17,11 @@ import { apiUrl, buildUrl } from './client' */ const tokenCache = new TtlLruCache>({ ttlMs: 120_000, max: 100 }) +/** Whether this is a slug link and the operator has turned slug links off. */ +export function slugLinksDisabled (keyType: KeyType): boolean { + return keyType === KeyType.slug && !getConfigOption('ipp.allowSlugLinks', true) +} + /** * Display title for a shared link. Prefers the user-set link description, * falls back to the album name (for album shares), or a generic placeholder. diff --git a/shared/src/index.ts b/shared/src/index.ts index 8a5dc20..8413686 100644 --- a/shared/src/index.ts +++ b/shared/src/index.ts @@ -10,6 +10,7 @@ export * from './config/access' export * from './http' export * from './invalidRequest' export * from './session' +export * from './version' export * from './encrypt' export * from './utils/log' export * from './utils/webStream' diff --git a/shared/src/utils/webStream.ts b/shared/src/utils/webStream.ts index c08cfa0..7947b57 100644 --- a/shared/src/utils/webStream.ts +++ b/shared/src/utils/webStream.ts @@ -12,3 +12,19 @@ export function readableFromWeb (body: ReadableStream): Readable { // eslint-disable-next-line @typescript-eslint/no-explicit-any return Readable.fromWeb(body as any) } + +/** + * Build a `fetch` init that streams `body` as the request body. + * + * Node's fetch refuses a stream body unless `duplex: 'half'` is set, but that + * option is absent from the DOM `RequestInit` the project's `lib` resolves + * to, so it has to go on behind a cast. + */ +export function streamingRequestInit (init: RequestInit, body: Readable): RequestInit { + return { + ...init, + // eslint-disable-next-line @typescript-eslint/no-explicit-any + body: Readable.toWeb(body) as any, + duplex: 'half' + } as RequestInit +} diff --git a/shared/src/version.ts b/shared/src/version.ts new file mode 100644 index 0000000..868bec5 --- /dev/null +++ b/shared/src/version.ts @@ -0,0 +1,15 @@ +import { readFileSync } from 'fs' + +/** + * Resolve the running application version. Prefers the APP_VERSION env var + * baked in at Docker build time (see the Dockerfiles); falls back to the + * app's package.json for local dev, and finally to 'dev' if neither is readable. + */ +export function resolveAppVersion (packageJsonPath: string): string { + if (process.env.APP_VERSION) return process.env.APP_VERSION + try { + return JSON.parse(readFileSync(packageJsonPath, 'utf-8')).version || 'dev' + } catch { + return 'dev' + } +} diff --git a/upload-app/config.json b/upload-app/config.json new file mode 100644 index 0000000..d0aeea7 --- /dev/null +++ b/upload-app/config.json @@ -0,0 +1,15 @@ +{ + "ipp": { + "allowSlugLinks": true, + "customInvalidResponse": false, + "upload": { + "maxFileSize": 500, + "rateLimit": 60, + "byteBudget": 10240, + "filenamePrefix": "ipp_upload_", + "notifyUrl": "", + "notifyHeaders": {}, + "notifyTimeout": 10000 + } + } +} diff --git a/upload-app/package.json b/upload-app/package.json new file mode 100644 index 0000000..0590ac0 --- /dev/null +++ b/upload-app/package.json @@ -0,0 +1,42 @@ +{ + "name": "immich-public-proxy-upload", + "version": "3.4.1", + "private": true, + "scripts": { + "predev": "tsc -b ../shared", + "dev": "concurrently -n core,server,client -c magenta,blue,green \"tsc -b -w --preserveWatchOutput ../shared\" \"tsx watch src/index.ts\" \"tsc -w -p tsconfig.client.json\"", + "build": "tsc -b && tsc -p tsconfig.client.json", + "test": "vitest run", + "test:watch": "vitest", + "start": "node dist/index.js" + }, + "author": "Alan Grainger", + "license": "AGPL-3.0", + "description": "Lets visitors of an Immich Public Proxy share send photos and videos back to it.", + "repository": { + "type": "git", + "url": "https://github.com/alangrainger/immich-public-proxy.git" + }, + "main": "dist/index.js", + "dependencies": { + "@ipp/core": "*", + "dayjs": "^1.11.13", + "dotenv": "^16.4.5", + "express": "^4.21.1", + "preact": "^10.29.2", + "tslib": "^2.8.1" + }, + "devDependencies": { + "@types/cookie-session": "^2.0.49", + "@types/express": "^4.17.21", + "@types/node": "^22", + "@typescript-eslint/eslint-plugin": "^7", + "@typescript-eslint/parser": "^7", + "concurrently": "^10.0.3", + "eslint": "^8.57.0", + "eslint-config-standard": "^17.1.0", + "tsx": "^4", + "typescript": "^5.6.2", + "vitest": "^4" + } +} diff --git a/upload-app/src/config.ts b/upload-app/src/config.ts new file mode 100644 index 0000000..276720c --- /dev/null +++ b/upload-app/src/config.ts @@ -0,0 +1,56 @@ +import { getConfigOption, getNumericConfigOption } from '@ipp/core' + +const MB = 1024 * 1024 + +/** + * Path the share routes are mounted under, from `PUBLIC_BASE_URL`: `''` for + * an own-hostname deployment, `/upload` for `https://photos.example.com/upload`. + */ +export function basePathFrom (publicBaseUrl: string | undefined): string { + if (!publicBaseUrl) return '' + try { + return new URL(publicBaseUrl).pathname.replace(/\/+$/, '') + } catch { + return '' + } +} + +/** IPP's public URL from `GALLERY_URL`, without a trailing slash, or undefined when unset. */ +export function galleryUrl (): string | undefined { + return (process.env.GALLERY_URL || '').replace(/\/+$/, '') || undefined +} + +/** Largest single file accepted, in bytes, from `ipp.upload.maxFileSize` (MB). */ +export function maxFileSize (): number { + return Math.max(1, getNumericConfigOption('ipp.upload.maxFileSize', 500)) * MB +} + +/** Files per minute per visitor address and share, from `ipp.upload.rateLimit`. `0` is no limit. */ +export function rateLimit (): number { + return getNumericConfigOption('ipp.upload.rateLimit', 60) +} + +/** Bytes accepted per share per hour, from `ipp.upload.byteBudget` (MB). `0` is no limit. */ +export function byteBudget (): number { + return Math.max(0, getNumericConfigOption('ipp.upload.byteBudget', 10240)) * MB +} + +/** Prefix for every stored filename, from `ipp.upload.filenamePrefix`. */ +export function filenamePrefix (): string { + const configured = getConfigOption('ipp.upload.filenamePrefix', 'ipp_upload_') + return typeof configured === 'string' ? configured : '' +} + +/** Notification webhook settings from `ipp.upload.notify*`, or undefined when no URL is set. */ +export function notifyConfig (): { url: string, headers: Record, timeoutMs: number } | undefined { + const url = getConfigOption('ipp.upload.notifyUrl', '') + if (typeof url !== 'string' || !url) return undefined + const headers: Record = {} + const configured = getConfigOption('ipp.upload.notifyHeaders', {}) + if (configured && typeof configured === 'object' && !Array.isArray(configured)) { + for (const [name, value] of Object.entries(configured as Record)) { + if (typeof value === 'string') headers[name] = value + } + } + return { url, headers, timeoutMs: getNumericConfigOption('ipp.upload.notifyTimeout', 10_000) } +} diff --git a/upload-app/src/filename.ts b/upload-app/src/filename.ts new file mode 100644 index 0000000..09bf164 --- /dev/null +++ b/upload-app/src/filename.ts @@ -0,0 +1,28 @@ +import { sanitize } from '@ipp/core' + +const MAX_FILENAME_LENGTH = 254 + +/** + * Turn the visitor-supplied filename into the name Immich will store, with + * `prefix` applied once. Returns undefined when nothing usable is left, or + * when there is no extension: Immich types an asset by its extension and + * would refuse it. + */ +export function uploadFilename (raw: unknown, prefix: string): string | undefined { + if (typeof raw !== 'string') return undefined + const base = raw.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})$/) + if (!parts) return undefined + const extension = parts[2] + const stem = sanitize(parts[1]).trim() + // An empty stem is a dotfile; a leading dot is a traversal remnant. + if (!stem || stem.startsWith('.')) return undefined + + const cleanPrefix = sanitize(prefix).trim() + // Don't stack the prefix on a file that already carries it + const wanted = stem.startsWith(cleanPrefix) ? '' : cleanPrefix + const room = MAX_FILENAME_LENGTH - wanted.length - extension.length + return wanted + stem.slice(0, Math.max(1, room)) + extension +} diff --git a/upload-app/src/forward.ts b/upload-app/src/forward.ts new file mode 100644 index 0000000..3343230 --- /dev/null +++ b/upload-app/src/forward.ts @@ -0,0 +1,134 @@ +import { Readable } from 'stream' +import crypto from 'crypto' +import { apiUrl, authHeaders, buildUrl, log, streamingRequestInit } from '@ipp/core' +import { UploadPermit, assertPermit } from './gate' + +/** + * Everything forwarded about one file, already validated by `receive.ts`. + * `filename` is sanitised and carries an extension; `mimeType` is the bare + * type with no parameters. + */ +export interface IncomingUpload { + filename: string + mimeType: string + fileCreatedAt: string + fileModifiedAt: string + /** Raw file bytes, streamed straight through and never buffered. */ + body: Readable + /** The declared `Content-Length`; the upload aborts past it. */ + maxBytes: number +} + +export type ForwardResult = + | { ok: true, status: 'created' | 'duplicate', id: string, bytes: number } + | { ok: false, status: number, reason: string } + +export const NOT_ACCEPTING_UPLOADS = 'This share does not accept uploads' + +/** Thrown by the body generator when an upload runs past `maxBytes`. */ +class UploadTooLargeError extends Error {} + +/** + * Serialise one multipart/form-data body for Immich's `POST /assets`. The + * field set is fixed, so it is written by hand. The async generator pulls a + * chunk only when the socket to Immich is ready for it. + * + * Only the two timestamps and the file are sent, so fields Immich would + * otherwise honour (`visibility`, `livePhotoVideoId`, `metadata`, + * `sidecarData`) cannot be set by a visitor. The filename rides on the + * part's own Content-Disposition, which is where Immich reads it from. + */ +function multipartBody (boundary: string, upload: IncomingUpload, counter: { bytes: number }): Readable { + const fields: Record = { + fileCreatedAt: upload.fileCreatedAt, + fileModifiedAt: upload.fileModifiedAt + } + const part = (headers: string) => Buffer.from(`--${boundary}\r\n${headers}\r\n\r\n`) + + async function * generate () { + for (const [name, value] of Object.entries(fields)) { + yield part(`Content-Disposition: form-data; name="${name}"`) + yield Buffer.from(value + '\r\n') + } + yield part( + `Content-Disposition: form-data; name="assetData"; filename="${upload.filename}"\r\n` + + `Content-Type: ${upload.mimeType}` + ) + for await (const chunk of upload.body) { + counter.bytes += chunk.length + if (counter.bytes > upload.maxBytes) throw new UploadTooLargeError() + yield chunk + } + yield Buffer.from(`\r\n--${boundary}--\r\n`) + } + + return Readable.from(generate()) +} + +/** + * Map Immich's answer to an upload onto the reply the visitor gets. 201 is a + * new asset; 200 is a checksum match with an asset the owner already has, + * which Immich still adds to the album or link. 400 is Immich refusing the + * file itself. 401 and 403 mean the share no longer accepts uploads. + */ +export function replyForImmichStatus (status: number, body?: { id?: string, status?: string } | null): ForwardResult { + if (status === 200 || status === 201) { + return { ok: true, status: body?.status === 'duplicate' ? 'duplicate' : 'created', id: body?.id || '', bytes: 0 } + } + if (status === 400) return { ok: false, status: 400, reason: 'Immich would not accept this file' } + if (status === 401 || status === 403) return { ok: false, status: 403, reason: NOT_ACCEPTING_UPLOADS } + return { ok: false, status: 502, reason: 'Immich rejected the upload' } +} + +/** + * Send one upload to Immich as the share, and report what Immich made of it. + * Authentication is the visitor's share key (plus the password token for a + * password share); Immich files the asset into the album or the link itself. + * Errors are returned, except a permit failure, which is a bug. + */ +export async function forwardUpload (permit: UploadPermit, upload: IncomingUpload, signal: AbortSignal): Promise { + assertPermit(permit) + + const boundary = '----IPPUpload' + crypto.randomBytes(16).toString('hex') + const counter = { bytes: 0 } + const url = buildUrl(apiUrl() + '/assets', { [permit.keyType]: permit.key }) + + let res: globalThis.Response + try { + res = await fetch(url, streamingRequestInit({ + method: 'POST', + headers: { + 'Content-Type': 'multipart/form-data; boundary=' + boundary, + ...(await authHeaders(permit.keyType, permit.key, permit.password)) + }, + signal + }, multipartBody(boundary, upload, counter))) + } catch (e) { + // The generator's throw surfaces here as the fetch rejecting + if (causedBy(e, UploadTooLargeError)) return { ok: false, status: 413, reason: 'File is larger than declared' } + if (signal.aborted) return { ok: false, status: 499, reason: 'Visitor cancelled the upload' } + log.warn('Upload to Immich failed for ' + upload.filename + ': ' + errorText(e)) + return { ok: false, status: 502, reason: 'Could not reach Immich' } + } + + const body = await res.json().catch(() => null) as { id?: string, status?: string, message?: string } | null + const result = replyForImmichStatus(res.status, body) + if (result.ok) return { ...result, bytes: counter.bytes } + log.warn('Immich refused upload ' + upload.filename + ' with status ' + res.status + + (body?.message ? ': ' + body.message : '')) + return result +} + +/** Walk the `cause` chain: fetch wraps the body generator's error. */ +function causedBy (e: unknown, type: new () => Error): boolean { + let current: unknown = e + while (current instanceof Error) { + if (current instanceof type) return true + current = (current as { cause?: unknown }).cause + } + return false +} + +function errorText (e: unknown): string { + return e instanceof Error ? e.message : String(e) +} diff --git a/upload-app/src/gate.ts b/upload-app/src/gate.ts new file mode 100644 index 0000000..553d1a2 --- /dev/null +++ b/upload-app/src/gate.ts @@ -0,0 +1,60 @@ +/* + The upload authorisation gate. The upload is the only place this codebase + writes to Immich, so the check is not left to a caller remembering it: + + 1. `authoriseUpload()` - per request, once the share is resolved. Returns + an `UploadPermit`, which `forwardUpload` cannot be called without. + 2. `assertPermit()` - immediately before the request to Immich is built. + + The gate is the owner's "Allow public user to upload" toggle on the share, + read from a share lookup at most 60 s old. Immich enforces the same toggle + on every upload, so a mistake here still cannot upload to a share whose + owner said no. +*/ + +import { KeyType, SharedLink, slugLinksDisabled } from '@ipp/core' + +/* + A real symbol rather than a type-only brand, so `assertPermit` has + something to test once types are erased. Not exported and not in the + global registry, so a permit cannot be built outside this file. +*/ +const permitBrand: unique symbol = Symbol('ipp.uploadPermit') + +/** + * Proof that a share passed the upload gate, plus the share-scoped + * credentials the forwarder needs. Obtainable only from `authoriseUpload`. + */ +export interface UploadPermit { + readonly [permitBrand]: true + readonly link: SharedLink + /** The key exactly as the visitor's URL carried it (a key or a slug). */ + readonly key: string + readonly keyType: KeyType + /** Share password from the session cookie, for password-protected shares. */ + readonly password?: string +} + +/** Whether this share accepts uploads through this key type right now. */ +export function uploadAllowed (link: SharedLink, keyType: KeyType): boolean { + return link.allowUpload === true && !slugLinksDisabled(keyType) +} + +/** Issue a permit, or null when this share does not accept uploads. */ +export function authoriseUpload (link: SharedLink, key: string, keyType: KeyType, password?: string): UploadPermit | null { + if (!uploadAllowed(link, keyType)) return null + return { [permitBrand]: true, link, key, keyType, password } as UploadPermit +} + +/** + * Re-check the gate at the point of use. Throws, because reaching here + * without a valid permit is a bug, not a visitor error. + */ +export function assertPermit (permit: UploadPermit): void { + if (!permit || permit[permitBrand] !== true) { + throw new Error('Upload attempted without a permit') + } + if (!uploadAllowed(permit.link, permit.keyType)) { + throw new Error('Upload attempted for a share that does not allow uploads') + } +} diff --git a/app/src/utils/idleTimeoutStream.ts b/upload-app/src/idleTimeoutStream.ts similarity index 71% rename from app/src/utils/idleTimeoutStream.ts rename to upload-app/src/idleTimeoutStream.ts index 7739286..d0df426 100644 --- a/app/src/utils/idleTimeoutStream.ts +++ b/upload-app/src/idleTimeoutStream.ts @@ -1,5 +1,8 @@ import { Transform } from 'stream' +/** The error an idle 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 @@ -11,7 +14,7 @@ export function createIdleTimeoutStream (idleMs: number): Transform { const transform: Transform = new Transform({ transform (chunk, _, cb) { if (timer) clearTimeout(timer) - timer = setTimeout(() => transform.destroy(new Error(`No data received for ${idleMs}ms`)), idleMs) + timer = setTimeout(() => transform.destroy(new IdleTimeoutError(`No data received for ${idleMs}ms`)), idleMs) cb(null, chunk) }, flush (cb) { @@ -21,6 +24,6 @@ export function createIdleTimeoutStream (idleMs: number): Transform { }) // Arm the timer immediately so a response that returns headers but never // sends a body also times out. - timer = setTimeout(() => transform.destroy(new Error(`No data received for ${idleMs}ms`)), idleMs) + timer = setTimeout(() => transform.destroy(new IdleTimeoutError(`No data received for ${idleMs}ms`)), idleMs) return transform } diff --git a/upload-app/src/index.ts b/upload-app/src/index.ts new file mode 100644 index 0000000..aa22137 --- /dev/null +++ b/upload-app/src/index.ts @@ -0,0 +1,161 @@ +#!/usr/bin/env node + +import 'dotenv/config' +import express, { Router } from 'express' +import { Request } from 'express-serve-static-core' +import { resolve } from 'path' +import dayjs from 'dayjs' +import { h } from 'preact' +import { + addNoStoreHeaders, + asyncHandler, + CORE_PUBLIC_DIR, + decodeCookie, + enforceMinimumImmichVersion, + errorHandler, + getKeyTypeFromShare, + healthcheck, + invalidPasswordResponse, + isKey, + KeyType, + loadConfig, + Password, + renderPage, + respondToInvalidRequest, + sessionMiddleware, + SharedLink, + slugLinksDisabled, + title, + unlockHandler +} from '@ipp/core' +import { basePathFrom, galleryUrl, maxFileSize } from './config' +import { uploadAllowed } from './gate' +import { createUploadReceiver } from './receive' +import { getShare } from './share' +import { ASSET_VERSION } from './version' +import { UploadPage } from './view/upload' + +// Must run before any code that calls getConfigOption. The bundled +// config.json sits one level above this file, which is /app/config.json in +// the image. +loadConfig({ defaultPath: resolve(__dirname, '../config.json') }) + +const basePath = basePathFrom(process.env.PUBLIC_BASE_URL) +const receiveUpload = createUploadReceiver() +const inProduction = process.env.NODE_ENV === 'production' + +const app = express() +app.disable('x-powered-by') + +// Reachable at the root whatever the mount prefix, so one compose healthcheck fits both routing shapes +app.get(['/healthcheck', '/share/healthcheck'], asyncHandler(healthcheck)) + +const router = Router() + +for (const dir of ['public', CORE_PUBLIC_DIR]) { + router.use('/share/static/' + ASSET_VERSION, express.static(dir, { immutable: inProduction, maxAge: inProduction ? '365d' : 0 })) + router.use('/share/static', express.static(dir)) +} + +// Everything past the static assets is never cached +router.use((_req, res, next) => { + addNoStoreHeaders(res) + next() +}) +router.use(sessionMiddleware({ name: 'upload-session', path: basePath || '/' })) + +type ShareResolution = + | { ok: true, link: SharedLink, keyType: KeyType } + | { ok: false, reason: string, passwordRequired?: boolean } + +/** Validate the share in the URL against Immich, with the password from the session cookie. */ +async function resolveShare (req: Request): Promise { + const keyType = getKeyTypeFromShare(req.params.shareType) + if (slugLinksDisabled(keyType)) return { ok: false, reason: 'Slug links are disabled in config.json' } + if (!isKey(req.params.key)) return { ok: false, reason: 'Invalid key for ' + req.path } + const share = await getShare(req.params.key, keyType, req.password) + if (!share.valid) return { ok: false, reason: 'Invalid share link' } + if (share.passwordRequired || !share.link) return { ok: false, reason: 'Password required', passwordRequired: true } + return { ok: true, link: share.link, keyType } +} + +/* + * [ROUTE] Upload page, or the password page for a locked share + */ +router.get('/:shareType(share|s)/:key', decodeCookie, asyncHandler(async (req, res) => { + const key = req.params.key + const resolved = await resolveShare(req) + if (!resolved.ok && resolved.passwordRequired) { + if (req.password) invalidPasswordResponse(req, res, key) + res.send(renderPage(h(Password, { shareKey: key, notifyInvalidPassword: !!req.password, basePath }))) + return + } + if (!resolved.ok || !uploadAllowed(resolved.link, resolved.keyType)) { + respondToInvalidRequest(res, 404, resolved.ok ? 'Share does not accept uploads' : resolved.reason) + return + } + const gallery = galleryUrl() + res.send(renderPage(h(UploadPage, { + config: { + uploadUrl: `${basePath}/${req.params.shareType}/${encodeURIComponent(key)}/upload`, + maxFileSize: maxFileSize(), + title: title(resolved.link) + }, + basePath, + galleryLink: gallery && `${gallery}/${req.params.shareType}/${encodeURIComponent(key)}` + }))) +})) + +/* + * [ROUTE] Password unlock from the password page + */ +router.post('/share/unlock', express.json({ limit: '10kb' }), unlockHandler) + +/* + * [ROUTE] One file from a visitor, streamed to Immich + */ +router.post('/:shareType(share|s)/:key/upload', decodeCookie, asyncHandler(async (req, res) => { + const resolved = await resolveShare(req) + if (!resolved.ok) { + res.set('Connection', 'close') + respondToInvalidRequest(res, 404, resolved.reason) + return + } + await receiveUpload(req, res, resolved.link, resolved.keyType) +})) + +router.get(['/healthcheck', '/share/healthcheck'], asyncHandler(healthcheck)) + +app.use(basePath || '/', router) + +/* + * Everything else, including `/`, gets the 404 policy + */ +app.all('*', (req, res) => { + addNoStoreHeaders(res) + respondToInvalidRequest(res, 404, 'Invalid route ' + req.path) +}) + +app.use(errorHandler) + +process.on('uncaughtException', (err) => { + console.error('There was an uncaught error', err) + server.close() + process.exit(1) +}) +process.on('unhandledRejection', (reason, promise) => { + console.error('Unhandled Rejection at:', promise, 'reason:', reason) +}) +process.on('SIGTERM', () => { + console.log('Received SIGTERM. Gracefully shutting down...') + server.close() + process.exit(0) +}) + +const port = Number(process.env.IPP_PORT) || 3000 +const server = app.listen(port, () => { + console.log(dayjs().format() + ' Upload service started on port ' + port + (basePath ? ' under ' + basePath : '')) + enforceMinimumImmichVersion().catch(() => {}) +}) +// A large video on a phone uplink outlasts any whole-request limit; the body has an idle timeout instead +server.requestTimeout = 0 diff --git a/upload-app/src/limits.ts b/upload-app/src/limits.ts new file mode 100644 index 0000000..5fa7ada --- /dev/null +++ b/upload-app/src/limits.ts @@ -0,0 +1,54 @@ +import { TtlLruCache } from '@ipp/core' + +export type Admission = + | { ok: true, release: () => void } + | { ok: false, retryAfterSeconds: number } + +interface Window { + used: number + resetAt: number +} + +/** + * Fixed-window budget: each key may admit up to `limit` units per window. + * The rate limit admits one unit per file; the byte budget admits a file's + * declared length, and releases it if the upload then fails. + * + * Backed by TtlLruCache, so a flood of distinct keys evicts instead of + * growing without limit. The window lives on the entry rather than on the + * cache TTL, so admitting inside a window never extends it. A `limit` of 0 + * or less means no limit. + */ +export function createWindowBudget (opts: { limit: number, windowMs: number, maxKeys?: number }): (key: string, amount?: number) => Admission { + const windows = new TtlLruCache({ + // Twice the window, so the cache never drops an entry while its window is open + ttlMs: opts.windowMs * 2, + max: opts.maxKeys ?? 5000 + }) + const unlimited: Admission = { ok: true, release: () => {} } + + return function admit (key: string, amount = 1): Admission { + if (opts.limit <= 0) return unlimited + const now = Date.now() + let window = windows.get(key) + if (!window || window.resetAt <= now) { + window = { used: 0, resetAt: now + opts.windowMs } + windows.set(key, window) + } + if (window.used + amount > opts.limit) { + return { ok: false, retryAfterSeconds: Math.max(1, Math.ceil((window.resetAt - now) / 1000)) } + } + window.used += amount + const admitted = window + let released = false + return { + ok: true, + release: () => { + // A release after its window closed has nothing left to give back + if (released || admitted.resetAt <= Date.now()) return + released = true + admitted.used -= amount + } + } + } +} diff --git a/upload-app/src/notify.ts b/upload-app/src/notify.ts new file mode 100644 index 0000000..9c311fb --- /dev/null +++ b/upload-app/src/notify.ts @@ -0,0 +1,80 @@ +import { AlbumType, log, SharedLink, title } from '@ipp/core' +import { formatSize } from './shared/upload' +import { notifyConfig } from './config' + +/* + Optional upload notification: one JSON POST per stored file to + `ipp.upload.notifyUrl`, for ntfy, Gotify, Home Assistant and the like. + The payload never carries the share key, slug or password. +*/ + +export interface UploadNotification { + title: string + message: string + data: { + event: 'upload' + time: string + share: { type: 'album' | 'individual', id: string, title: string } + file: { name: string, size: number, type: string } + asset: { id: string, status: 'created' | 'duplicate' } + } +} + +/** + * Build the notification body for one stored file. `title` and `message` are + * top level so a receiver expecting a flat shape shows something readable + * with no mapping; everything structured lives under `data`. + */ +export function buildNotification ( + share: SharedLink, + file: { name: string, size: number, type: string }, + asset: { id: string, status: 'created' | 'duplicate' } +): UploadNotification { + const isAlbum = share.type === AlbumType.album + const shareTitle = title(share) + return { + title: 'Photo sent to ' + shareTitle, + message: `${file.name} (${formatSize(file.size)}) was uploaded to ${shareTitle}.`, + data: { + event: 'upload', + time: new Date().toISOString(), + share: { + type: isAlbum ? 'album' : 'individual', + // An album share is named by its album, an individual share by the link + id: (isAlbum ? share.album?.id : share.id) || '', + title: shareTitle + }, + file, + asset + } + } +} + +/** + * Post the notification, if one is configured. Fire and forget: a timeout, + * no retry, failures logged and swallowed. Only the URL's host is logged, + * because ntfy topics and Gotify tokens live in the URL. + */ +export async function sendNotification (notification: UploadNotification): Promise { + const config = notifyConfig() + if (!config) return + try { + const res = await fetch(config.url, { + method: 'POST', + headers: { 'Content-Type': 'application/json', ...config.headers }, + body: JSON.stringify(notification), + signal: AbortSignal.timeout(config.timeoutMs) + }) + if (!res.ok) log.warn('Upload notification to ' + hostOf(config.url) + ' answered ' + res.status) + } catch (e) { + log.warn('Upload notification to ' + hostOf(config.url) + ' failed: ' + (e instanceof Error ? e.message : String(e))) + } +} + +function hostOf (url: string): string { + try { + return new URL(url).host + } catch { + return 'an invalid URL' + } +} diff --git a/upload-app/src/receive.ts b/upload-app/src/receive.ts new file mode 100644 index 0000000..1f05947 --- /dev/null +++ b/upload-app/src/receive.ts @@ -0,0 +1,141 @@ +import { pipeline } from 'stream' +import { Request, Response } from 'express-serve-static-core' +import dayjs from 'dayjs' +import { abortOnClose, KeyType, log, respondToInvalidRequest, SharedLink } from '@ipp/core' +import { byteBudget, filenamePrefix, maxFileSize, rateLimit } from './config' +import { uploadFilename } from './filename' +import { forwardUpload } from './forward' +import { authoriseUpload } from './gate' +import { createIdleTimeoutStream, IdleTimeoutError } from './idleTimeoutStream' +import { createWindowBudget } from './limits' +import { buildNotification, sendNotification } from './notify' +import { formatSize, isUploadableType } from './shared/upload' + +/* + The visitor-facing half of the upload path: validate one request, then + hand it to `forward.ts` with a permit from `gate.ts`. + + Each file is its own POST whose body is the raw bytes, with the name and + timestamps in the query string. The app re-encodes for Immich anyway, so + it runs no multipart parser on visitor input, and nothing is buffered or + written to disk. +*/ + +// A body that sends nothing for this long is dropped +const BODY_IDLE_MS = 60_000 + +/** + * Answer an upload the server will not take, in the shape the page reads. + * `Connection: close` stops a body still in flight costing its full bandwidth. + */ +function refuse (res: Response, status: number, reason: string): void { + res.set('Connection', 'close') + res.status(status).json({ error: reason }) +} + +/** The declared `Content-Length`, or undefined when absent or malformed. */ +export function declaredLength (header: string | undefined): number | undefined { + return header && /^\d+$/.test(header) ? Number(header) : undefined +} + +/** + * Parse a visitor-supplied timestamp, falling back to now. Only a starting + * point: Immich replaces it from EXIF when the file carries a better date. + */ +export function uploadTimestamp (raw: unknown): string { + const parsed = typeof raw === 'string' && raw ? dayjs(raw) : undefined + return (parsed?.isValid() ? parsed : dayjs()).toISOString() +} + +/** + * Build the handler for `POST /upload`, with its rate limit and byte + * budget read from config. Called once, after the config has loaded. + * + * Once the share has passed the gate, failures a visitor can act on answer + * with a status and a short JSON reason rather than the 404 policy. + */ +export function createUploadReceiver () { + // Keyed on address and share; behind a reverse proxy every visitor has the proxy's address + const rate = createWindowBudget({ limit: rateLimit(), windowMs: 60_000 }) + const budget = createWindowBudget({ limit: byteBudget(), windowMs: 60 * 60_000 }) + const maxBytes = maxFileSize() + const prefix = filenamePrefix() + + return async function receiveUpload (req: Request, res: Response, link: SharedLink, keyType: KeyType): Promise { + const key = req.params.key + const permit = authoriseUpload(link, key, keyType, req.password) + if (!permit) { + res.set('Connection', 'close') + respondToInvalidRequest(res, 404, 'Share does not accept uploads') + return + } + 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 > maxBytes) { + refuse(res, 413, 'Larger than the ' + formatSize(maxBytes) + ' limit') + return + } + + const filename = uploadFilename(req.query.filename, prefix) + if (!filename) { + refuse(res, 400, 'Missing or unusable filename') + return + } + + const mimeType = (req.headers['content-type'] || '').split(';')[0].trim().toLowerCase() + if (!isUploadableType(mimeType)) { + refuse(res, 415, 'Only photos and videos can be sent') + return + } + + // Reserved before streaming, so parallel uploads cannot overshoot the budget together + const reserved = budget(shareId, length) + if (!reserved.ok) { + res.set('Retry-After', String(reserved.retryAfterSeconds)) + refuse(res, 413, 'This share has received its limit for the hour. Try again later.') + 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 result = await forwardUpload(permit, { + filename, + mimeType, + fileCreatedAt: uploadTimestamp(req.query.fileCreatedAt), + fileModifiedAt: uploadTimestamp(req.query.fileModifiedAt), + body, + maxBytes: length + }, abortOnClose(res)) + + if (!result.ok) { + reserved.release() + // The visitor hung up; there is nobody left to answer + if (result.status === 499) return + refuse(res, result.status, result.reason) + return + } + + log('Received upload ' + filename + ' for share ' + (link.slug || link.id) + ' (' + result.status + ')') + res.json({ status: result.status }) + + // After the reply, so a slow webhook never holds up the visitor + sendNotification(buildNotification( + link, + { name: filename, size: result.bytes, type: mimeType }, + { id: result.id, status: result.status } + )) + } +} diff --git a/upload-app/src/share.ts b/upload-app/src/share.ts new file mode 100644 index 0000000..8845d59 --- /dev/null +++ b/upload-app/src/share.ts @@ -0,0 +1,13 @@ +import { cachedPromise, fetchSharedLink, KeyType, SharedLinkResult, TtlLruCache } from '@ipp/core' + +/* + Share lookups, cached for 60 s per (key type, key, password). The cache + bounds how stale the `allowUpload` check can be when an owner turns the + toggle off; Immich enforces the toggle on every upload regardless. +*/ +const shareCache = new TtlLruCache>({ ttlMs: 60_000, max: 100 }) + +/** Look up a share through `@ipp/core`, sharing one Immich call across concurrent requests. */ +export function getShare (key: string, keyType: KeyType, password?: string): Promise { + return cachedPromise(shareCache, `${keyType}:${key}:${password || ''}`, () => fetchSharedLink(key, keyType, password), result => result.valid) +} diff --git a/upload-app/src/shared/limiter.ts b/upload-app/src/shared/limiter.ts new file mode 100644 index 0000000..267f903 --- /dev/null +++ b/upload-app/src/shared/limiter.ts @@ -0,0 +1,21 @@ +/** + * Returns a function that runs at most `limit` async tasks concurrently. + * Tasks queue when the limit is reached and resume in FIFO order. + */ +export function createLimiter (limit: number) { + let active = 0 + const queue: Array<() => void> = [] + return async function run (fn: () => Promise): Promise { + if (active >= limit) { + await new Promise(resolve => queue.push(resolve)) + } + active++ + try { + return await fn() + } finally { + active-- + const next = queue.shift() + if (next) next() + } + } +} diff --git a/upload-app/src/shared/upload.ts b/upload-app/src/shared/upload.ts new file mode 100644 index 0000000..91c1ced --- /dev/null +++ b/upload-app/src/shared/upload.ts @@ -0,0 +1,82 @@ +/* + Upload rules the page client and the server both apply: the client filters + with them before anything leaves the browser, the server decides with them. +*/ + +/** `accept` attribute for the file picker: the camera roll on a phone. */ +export const UPLOAD_ACCEPT = 'image/*,video/*' + +/** + * Whether a file of this media type may be sent. Any image or video except + * SVG, the one image type a browser may execute. Immich types an asset by its + * extension and refuses anything outside its own list, so the finer check is + * left to Immich. + */ +export function isUploadableType (mimeType: string): boolean { + const type = (mimeType || '').split(';')[0].trim().toLowerCase() + if (type === 'image/svg+xml') return false + return type.startsWith('image/') || type.startsWith('video/') +} + +/* + Types for files a desktop browser reports with an empty `File.type`: HEIC, + HEIF, camera RAW and some video containers. Immich types the asset by its + extension, so these only need to pass `isUploadableType`. +*/ +const TYPE_BY_EXTENSION: Record = { + heic: 'image/heic', + heif: 'image/heif', + hif: 'image/heif', + avif: 'image/avif', + jxl: 'image/jxl', + dng: 'image/x-adobe-dng', + cr2: 'image/x-canon-cr2', + cr3: 'image/x-canon-cr3', + nef: 'image/x-nikon-nef', + nrw: 'image/x-nikon-nrw', + arw: 'image/x-sony-arw', + raf: 'image/x-fuji-raf', + orf: 'image/x-olympus-orf', + rw2: 'image/x-panasonic-rw2', + pef: 'image/x-pentax-pef', + srw: 'image/x-samsung-srw', + mts: 'video/mp2t', + m2ts: 'video/mp2t', + mkv: 'video/x-matroska', + insv: 'video/mp4' +} + +/** The browser's type for a file, or one derived from its extension when the browser gives none. */ +export function fileType (name: string, browserType: string): string { + if (browserType) return browserType + const extension = name.split('.').pop()?.toLowerCase() || '' + return TYPE_BY_EXTENSION[extension] || '' +} + +/** Bytes as a short human-readable string. */ +export function formatSize (bytes: number): string { + if (bytes >= 1024 * 1024 * 1024) return (bytes / (1024 * 1024 * 1024)).toFixed(1) + ' GB' + if (bytes >= 1024 * 1024) return (bytes / (1024 * 1024)).toFixed(1) + ' MB' + if (bytes >= 1024) return Math.round(bytes / 1024) + ' KB' + return bytes + ' bytes' +} + +/** Page settings the server renders into the init JSON for the client. */ +export interface UploadPageConfig { + /** Path of this share's upload endpoint, including any mount prefix. */ + uploadUrl: string + /** Largest single file the server accepts, in bytes. */ + maxFileSize: number + /** Share title, for the drop overlay and the completion message. */ + title: string +} + +/** Success body of `POST /upload`. */ +export interface UploadResponse { + status: 'created' | 'duplicate' +} + +/** Failure body of `POST /upload`. */ +export interface UploadErrorResponse { + error: string +} diff --git a/upload-app/src/version.ts b/upload-app/src/version.ts new file mode 100644 index 0000000..b6837b7 --- /dev/null +++ b/upload-app/src/version.ts @@ -0,0 +1,5 @@ +import { join } from 'path' +import { resolveAppVersion } from '@ipp/core' + +/** URL-safe cache-busting segment for static asset paths. */ +export const ASSET_VERSION = encodeURIComponent(resolveAppVersion(join(__dirname, '..', 'package.json'))) diff --git a/upload-app/src/view/upload.tsx b/upload-app/src/view/upload.tsx new file mode 100644 index 0000000..a9d317c --- /dev/null +++ b/upload-app/src/view/upload.tsx @@ -0,0 +1,47 @@ +import { jsonForInlineScript, ThemeScript } from '@ipp/core' +import { UPLOAD_ACCEPT, UploadPageConfig } from '../shared/upload' +import { ASSET_VERSION } from '../version' + +export interface UploadPageProps { + config: UploadPageConfig + /** Path prefix the app is mounted under, without a trailing slash. Empty at the root. */ + basePath: string + /** This share's gallery on IPP, when `GALLERY_URL` is set. */ + galleryLink?: string +} + +/** The upload page for one share: the share title, the picker, and the list the client fills. */ +export function UploadPage ({ config, basePath, galleryLink }: UploadPageProps) { + const staticPath = `${basePath}/share/static/${ASSET_VERSION}` + return ( + + + + + + {'Send photos to ' + config.title} + + + + + + +
+

Send photos to {config.title}

+ + + {galleryLink &&

Back to gallery

} + +
+ + + + + ) +} diff --git a/upload-app/tests/config.test.ts b/upload-app/tests/config.test.ts new file mode 100644 index 0000000..69fb605 --- /dev/null +++ b/upload-app/tests/config.test.ts @@ -0,0 +1,43 @@ +import { describe, it, expect, afterEach } from 'vitest' +import { basePathFrom, byteBudget, filenamePrefix, maxFileSize, notifyConfig } from '../src/config' +import { resetConfig, setConfig } from './helpers' + +afterEach(resetConfig) + +const MB = 1024 * 1024 + +describe('basePathFrom', () => { + it('is empty for an own-hostname deployment', () => { + expect(basePathFrom('https://upload.example.com')).toBe('') + expect(basePathFrom('https://upload.example.com/')).toBe('') + expect(basePathFrom(undefined)).toBe('') + }) + + it('is the URL path for a path-prefix deployment, without a trailing slash', () => { + expect(basePathFrom('https://photos.example.com/upload')).toBe('/upload') + expect(basePathFrom('https://photos.example.com/a/b/')).toBe('/a/b') + }) + + it('is empty for a value that is not a URL', () => { + expect(basePathFrom('not a url')).toBe('') + }) +}) + +describe('upload options', () => { + it('has the documented defaults', () => { + expect(maxFileSize()).toBe(500 * MB) + expect(byteBudget()).toBe(10240 * MB) + expect(filenamePrefix()).toBe('ipp_upload_') + expect(notifyConfig()).toBeUndefined() + }) + + it('never lets maxFileSize reach zero, which would refuse every file', () => { + setConfig({ ipp: { upload: { maxFileSize: 0 } } }) + expect(maxFileSize()).toBe(MB) + }) + + it('keeps only string notification headers', () => { + setConfig({ ipp: { upload: { notifyUrl: 'https://ntfy.example.com/topic', notifyHeaders: { Authorization: 'Bearer x', Bad: 1 } } } }) + expect(notifyConfig()).toEqual({ url: 'https://ntfy.example.com/topic', headers: { Authorization: 'Bearer x' }, timeoutMs: 10_000 }) + }) +}) diff --git a/upload-app/tests/filename.test.ts b/upload-app/tests/filename.test.ts new file mode 100644 index 0000000..43d2d96 --- /dev/null +++ b/upload-app/tests/filename.test.ts @@ -0,0 +1,44 @@ +import { describe, it, expect } from 'vitest' +import { uploadFilename } from '../src/filename' + +describe('uploadFilename', () => { + it('keeps an ordinary filename', () => { + expect(uploadFilename('IMG_0042.jpg', '')).toBe('IMG_0042.jpg') + }) + + it('strips path components so traversal cannot survive', () => { + expect(uploadFilename('../../etc/passwd.jpg', '')).toBe('passwd.jpg') + expect(uploadFilename('C:\\Users\\bob\\holiday.png', '')).toBe('holiday.png') + }) + + it('removes characters that are illegal in a filename or would break the multipart header', () => { + expect(uploadFilename('we"rd:na*me.jpg', '')).toBe('werdname.jpg') + }) + + it('rejects a name with no extension', () => { + expect(uploadFilename('photo', '')).toBeUndefined() + }) + + it('rejects dotfiles and non-string input', () => { + expect(uploadFilename('.htaccess', '')).toBeUndefined() + expect(uploadFilename('', '')).toBeUndefined() + expect(uploadFilename(undefined, '')).toBeUndefined() + expect(uploadFilename(['a.jpg'], '')).toBeUndefined() + }) + + it('applies the prefix once', () => { + expect(uploadFilename('IMG_0042.jpg', 'ipp_upload_')).toBe('ipp_upload_IMG_0042.jpg') + expect(uploadFilename('ipp_upload_IMG_0042.jpg', 'ipp_upload_')).toBe('ipp_upload_IMG_0042.jpg') + }) + + it('sanitises an operator prefix that would break the filename', () => { + expect(uploadFilename('IMG_0042.jpg', '../ev"il/')).toBe('..evilIMG_0042.jpg') + }) + + it('stays within 254 characters with the extension intact', () => { + const result = uploadFilename('x'.repeat(400) + '.jpg', 'ipp_upload_') || '' + expect(result.startsWith('ipp_upload_')).toBe(true) + expect(result.endsWith('.jpg')).toBe(true) + expect(result.length).toBeLessThanOrEqual(254) + }) +}) diff --git a/upload-app/tests/forward.test.ts b/upload-app/tests/forward.test.ts new file mode 100644 index 0000000..e57c40d --- /dev/null +++ b/upload-app/tests/forward.test.ts @@ -0,0 +1,23 @@ +import { describe, it, expect } from 'vitest' +import { NOT_ACCEPTING_UPLOADS, replyForImmichStatus } from '../src/forward' + +describe('replyForImmichStatus', () => { + it('reports a new asset and a duplicate as success', () => { + expect(replyForImmichStatus(201, { id: 'a1', status: 'created' })).toMatchObject({ ok: true, status: 'created', id: 'a1' }) + expect(replyForImmichStatus(200, { id: 'a1', status: 'duplicate' })).toMatchObject({ ok: true, status: 'duplicate', id: 'a1' }) + }) + + it('passes Immich refusing the file through as 400', () => { + expect(replyForImmichStatus(400)).toMatchObject({ ok: false, status: 400 }) + }) + + it('reads 401 and 403 as the share no longer accepting uploads', () => { + expect(replyForImmichStatus(401)).toEqual({ ok: false, status: 403, reason: NOT_ACCEPTING_UPLOADS }) + expect(replyForImmichStatus(403)).toEqual({ ok: false, status: 403, reason: NOT_ACCEPTING_UPLOADS }) + }) + + it('reports anything else as an upstream failure', () => { + expect(replyForImmichStatus(500)).toMatchObject({ ok: false, status: 502 }) + expect(replyForImmichStatus(413)).toMatchObject({ ok: false, status: 502 }) + }) +}) diff --git a/upload-app/tests/gate.test.ts b/upload-app/tests/gate.test.ts new file mode 100644 index 0000000..dca894b --- /dev/null +++ b/upload-app/tests/gate.test.ts @@ -0,0 +1,38 @@ +import { describe, it, expect, afterEach } from 'vitest' +import { KeyType } from '@ipp/core' +import { assertPermit, authoriseUpload, UploadPermit } from '../src/gate' +import { resetConfig, setConfig, share } from './helpers' + +afterEach(resetConfig) + +describe('authoriseUpload', () => { + it('issues a permit only when the share\'s Immich toggle is on', () => { + expect(authoriseUpload(share(), 'k', KeyType.key)).not.toBeNull() + expect(authoriseUpload(share({ allowUpload: false }), 'k', KeyType.key)).toBeNull() + expect(authoriseUpload(share({ allowUpload: undefined }), 'k', KeyType.key)).toBeNull() + }) + + it('refuses slug links when the operator has turned them off', () => { + setConfig({ ipp: { allowSlugLinks: false } }) + expect(authoriseUpload(share(), 'my-slug', KeyType.slug)).toBeNull() + expect(authoriseUpload(share(), 'k', KeyType.key)).not.toBeNull() + }) +}) + +describe('assertPermit', () => { + it('passes a permit from authoriseUpload', () => { + expect(() => assertPermit(authoriseUpload(share(), 'k', KeyType.key)!)).not.toThrow() + }) + + it('throws for a permit built by hand', () => { + const forged = { link: share(), key: 'k', keyType: KeyType.key } as unknown as UploadPermit + expect(() => assertPermit(forged)).toThrow('without a permit') + }) + + it('throws when the share stopped accepting uploads after the permit was issued', () => { + const link = share() + const permit = authoriseUpload(link, 'k', KeyType.key)! + link.allowUpload = false + expect(() => assertPermit(permit)).toThrow('does not allow uploads') + }) +}) diff --git a/upload-app/tests/helpers.ts b/upload-app/tests/helpers.ts new file mode 100644 index 0000000..d7fc0a4 --- /dev/null +++ b/upload-app/tests/helpers.ts @@ -0,0 +1,26 @@ +import { AlbumType, KeyType, loadConfig, SharedLink } from '@ipp/core' + +/** Load `config` as if it came from the `CONFIG` env var. */ +export function setConfig (config: Record) { + process.env.CONFIG = JSON.stringify(config) + loadConfig() +} + +export function resetConfig () { + delete process.env.CONFIG + loadConfig() +} + +export function share (overrides: Partial = {}): SharedLink { + return { + id: 'ffffffff-0000-0000-0000-000000000001', + key: 'share-key', + keyType: KeyType.key, + type: AlbumType.album, + assets: [], + expiresAt: null, + allowUpload: true, + album: { id: 'aaaaaaaa-0000-0000-0000-000000000002', albumName: 'Holiday 2025' }, + ...overrides + } +} diff --git a/upload-app/tests/limits.test.ts b/upload-app/tests/limits.test.ts new file mode 100644 index 0000000..80c6841 --- /dev/null +++ b/upload-app/tests/limits.test.ts @@ -0,0 +1,69 @@ +import { describe, it, expect, vi, afterEach } from 'vitest' +import { createWindowBudget } from '../src/limits' + +afterEach(() => { + vi.useRealTimers() +}) + +describe('createWindowBudget as a rate limit', () => { + it('admits up to the limit, then refuses with the seconds left in the window', () => { + vi.useFakeTimers() + const rate = createWindowBudget({ limit: 3, windowMs: 60_000 }) + expect([1, 2, 3].map(() => rate('ip:share').ok)).toEqual([true, true, true]) + vi.advanceTimersByTime(20_000) + expect(rate('ip:share')).toEqual({ ok: false, retryAfterSeconds: 40 }) + }) + + it('counts only admitted requests', () => { + const rate = createWindowBudget({ limit: 1, windowMs: 60_000 }) + rate('a') + rate('a') + rate('a') + expect(rate('b').ok).toBe(true) + }) + + it('starts a fresh window once the old one has passed', () => { + vi.useFakeTimers() + const rate = createWindowBudget({ limit: 1, windowMs: 60_000 }) + expect(rate('a').ok).toBe(true) + expect(rate('a').ok).toBe(false) + vi.advanceTimersByTime(60_000) + expect(rate('a').ok).toBe(true) + }) + + it('treats a limit of 0 as no limit', () => { + const rate = createWindowBudget({ limit: 0, windowMs: 60_000 }) + expect([1, 2, 3, 4].every(() => rate('a').ok)).toBe(true) + }) +}) + +describe('createWindowBudget as a byte budget', () => { + it('reserves on admission, so parallel uploads cannot overshoot together', () => { + const budget = createWindowBudget({ limit: 100, windowMs: 3_600_000 }) + expect(budget('share', 60).ok).toBe(true) + expect(budget('share', 60).ok).toBe(false) + expect(budget('share', 40).ok).toBe(true) + }) + + it('gives a failed upload\'s reservation back, once', () => { + const budget = createWindowBudget({ limit: 100, windowMs: 3_600_000 }) + const first = budget('share', 80) + expect(budget('share', 80).ok).toBe(false) + if (first.ok) { + first.release() + first.release() + } + expect(budget('share', 80).ok).toBe(true) + expect(budget('share', 80).ok).toBe(false) + }) + + it('ignores a release after its window has closed', () => { + vi.useFakeTimers() + const budget = createWindowBudget({ limit: 100, windowMs: 1000 }) + const old = budget('share', 100) + vi.advanceTimersByTime(1000) + expect(budget('share', 100).ok).toBe(true) + if (old.ok) old.release() + expect(budget('share', 1).ok).toBe(false) + }) +}) diff --git a/upload-app/tests/notify.test.ts b/upload-app/tests/notify.test.ts new file mode 100644 index 0000000..f087b01 --- /dev/null +++ b/upload-app/tests/notify.test.ts @@ -0,0 +1,39 @@ +import { describe, it, expect } from 'vitest' +import { AlbumType } from '@ipp/core' +import { buildNotification } from '../src/notify' +import { share } from './helpers' + +const file = { name: 'ipp_upload_IMG_0042.jpg', size: 3145728, type: 'image/jpeg' } +const asset = { id: 'bbbbbbbb-0000-0000-0000-000000000003', status: 'created' as const } + +describe('buildNotification', () => { + it('names an album share by its album id', () => { + expect(buildNotification(share(), file, asset).data.share).toEqual({ + type: 'album', + id: 'aaaaaaaa-0000-0000-0000-000000000002', + title: 'Holiday 2025' + }) + }) + + it('names an individual share by the link id', () => { + const payload = buildNotification(share({ type: AlbumType.individual, album: undefined, description: 'Some photos' }), file, asset) + expect(payload.data.share).toEqual({ + type: 'individual', + id: 'ffffffff-0000-0000-0000-000000000001', + title: 'Some photos' + }) + }) + + it('carries a flat title and message for simple receivers', () => { + const payload = buildNotification(share(), file, asset) + expect(payload.title).toBe('Photo sent to Holiday 2025') + expect(payload.message).toBe('ipp_upload_IMG_0042.jpg (3.0 MB) was uploaded to Holiday 2025.') + }) + + it('never carries the share key, slug or password', () => { + const payload = JSON.stringify(buildNotification(share({ key: 'secret-key', slug: 'secret-slug', password: 'hunter2' }), file, asset)) + expect(payload).not.toContain('secret-key') + expect(payload).not.toContain('secret-slug') + expect(payload).not.toContain('hunter2') + }) +}) diff --git a/upload-app/tests/uploadRules.test.ts b/upload-app/tests/uploadRules.test.ts new file mode 100644 index 0000000..147f8df --- /dev/null +++ b/upload-app/tests/uploadRules.test.ts @@ -0,0 +1,75 @@ +import { describe, it, expect } from 'vitest' +import { fileType, formatSize, isUploadableType } from '../src/shared/upload' +import { declaredLength, uploadTimestamp } from '../src/receive' + +describe('isUploadableType', () => { + it('accepts photos and videos, with or without parameters', () => { + expect(isUploadableType('image/jpeg')).toBe(true) + expect(isUploadableType('video/quicktime')).toBe(true) + expect(isUploadableType('IMAGE/HEIC')).toBe(true) + expect(isUploadableType('image/jpeg; charset=binary')).toBe(true) + }) + + it('refuses SVG, the one image type a browser may execute', () => { + expect(isUploadableType('image/svg+xml')).toBe(false) + expect(isUploadableType('IMAGE/SVG+XML; charset=utf-8')).toBe(false) + }) + + it('refuses anything else', () => { + expect(isUploadableType('application/octet-stream')).toBe(false) + expect(isUploadableType('text/html')).toBe(false) + expect(isUploadableType('')).toBe(false) + }) +}) + +describe('fileType', () => { + it('keeps the type the browser gave', () => { + expect(fileType('IMG_0042.HEIC', 'image/heic')).toBe('image/heic') + }) + + it('derives a type from the extension when the browser gives none', () => { + expect(fileType('IMG_0042.HEIC', '')).toBe('image/heic') + expect(fileType('DSC_0001.NEF', '')).toBe('image/x-nikon-nef') + expect(isUploadableType(fileType('clip.mts', ''))).toBe(true) + }) + + it('gives up on an unknown extension, so the client refuses the file', () => { + expect(fileType('notes.txt', '')).toBe('') + }) +}) + +describe('formatSize', () => { + it('picks a readable unit', () => { + expect(formatSize(512)).toBe('512 bytes') + expect(formatSize(3 * 1024)).toBe('3 KB') + expect(formatSize(3145728)).toBe('3.0 MB') + expect(formatSize(2.5 * 1024 * 1024 * 1024)).toBe('2.5 GB') + }) +}) + +describe('declaredLength', () => { + it('reads a plain decimal Content-Length', () => { + expect(declaredLength('3145728')).toBe(3145728) + expect(declaredLength('0')).toBe(0) + }) + + it('rejects a missing or malformed header', () => { + expect(declaredLength(undefined)).toBeUndefined() + expect(declaredLength('')).toBeUndefined() + expect(declaredLength('12abc')).toBeUndefined() + expect(declaredLength('-1')).toBeUndefined() + expect(declaredLength('1e9')).toBeUndefined() + }) +}) + +describe('uploadTimestamp', () => { + it('passes through a valid timestamp as ISO 8601', () => { + expect(uploadTimestamp('2026-09-14T07:18:00.000Z')).toBe('2026-09-14T07:18:00.000Z') + }) + + it('falls back to now for junk or missing input', () => { + for (const input of ['not a date', '', undefined, 42]) { + expect(Number.isNaN(Date.parse(uploadTimestamp(input)))).toBe(false) + } + }) +}) diff --git a/upload-app/tsconfig.client.json b/upload-app/tsconfig.client.json new file mode 100644 index 0000000..4ce1e2d --- /dev/null +++ b/upload-app/tsconfig.client.json @@ -0,0 +1,27 @@ +{ + "compilerOptions": { + "rootDir": "src", + "outDir": "public/js", + "module": "esnext", + "moduleResolution": "bundler", + "target": "ES2022", + "lib": [ + "DOM", + "DOM.Iterable", + "ES2022" + ], + "strict": true, + "noImplicitAny": true, + "strictNullChecks": true, + "isolatedModules": true, + "esModuleInterop": true, + "allowSyntheticDefaultImports": true, + "skipLibCheck": true, + "inlineSourceMap": true, + "inlineSources": true + }, + "include": [ + "src/client/**/*.ts", + "src/shared/**/*.ts" + ] +} diff --git a/upload-app/tsconfig.json b/upload-app/tsconfig.json new file mode 100644 index 0000000..6b1cb2d --- /dev/null +++ b/upload-app/tsconfig.json @@ -0,0 +1,41 @@ +{ + "compilerOptions": { + "baseUrl": "src", + "outDir": "dist", + "inlineSourceMap": true, + "inlineSources": true, + "module": "CommonJS", + "target": "ES6", + "allowJs": true, + "noImplicitAny": true, + "esModuleInterop": true, + "moduleResolution": "node", + "importHelpers": true, + "isolatedModules": true, + "strictNullChecks": true, + "lib": [ + "DOM", + "ES5", + "ES6", + "ES7" + ], + "allowSyntheticDefaultImports": true, + "skipLibCheck": true, + "jsx": "react-jsx", + "jsxImportSource": "preact" + }, + "include": [ + "**/*.ts", + "**/*.tsx" + ], + "exclude": [ + "node_modules", + "dist", + "tests", + "vitest.config.ts", + "src/client" + ], + "references": [ + { "path": "../shared" } + ] +} diff --git a/upload-app/vitest.config.ts b/upload-app/vitest.config.ts new file mode 100644 index 0000000..c064754 --- /dev/null +++ b/upload-app/vitest.config.ts @@ -0,0 +1,13 @@ +import { resolve } from 'path' +import { defineConfig } from 'vitest/config' + +export default defineConfig({ + resolve: { + // Test against core's source, so `npm test` needs no build of shared/ + alias: { '@ipp/core': resolve(__dirname, '../shared/src/index.ts') } + }, + test: { + include: ['tests/**/*.test.ts'], + environment: 'node' + } +})