release: v0.19.0

Release v0.19.0. See the `## [0.19.0] — 2026-09-29` section of
[CHANGELOG.md](https://github.com/ralksta/immich-folio/blob/dev/CHANGELOG.md)
for the full list.

Highlights: client proofing links (#683), custom content pages (#738),
asset picker search (#740), concurrent-edit detection (#742), env-locked
settings (#739), an accessibility baseline (#741), three security fixes
with advisories (#737, #755, #759), and a pre-release quality pass
(#780–#797).

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Ralf <rohlenbo79@gmail.com>
Co-authored-by: Paul Thies <110185070+ImScheinox@users.noreply.github.com>
Co-authored-by: lancetm714 <108419425+lancetm714@users.noreply.github.com>
Co-authored-by: Lance Martin <lancetaylor95@gmail.com>

app/api/proof/[token]/archive/route.ts

@@ -0,0 +1,72 @@
+/**
+ * GET /api/proof/:token/archive?scope=selection|album — the originals of a
+ * client proofing link as a ZIP.
+ *
+ * What may be downloaded is the session's to say (`download: selection` or
+ * `album`), every successful start counts against its `downloadLimit`, and
+ * the selection ZIP is built from the saved selection, never from the request.
+ * Streaming and the refusal page are shared with the album archive route.
+ */
+
+import { NextRequest } from 'next/server';
+import { resolveProofAccess } from '@/lib/proofAccess';
+import { claimDownload, ProofError } from '@/lib/proofSessions';
+import { refusal, withArchiveSlot, type ArchiveStreamer } from '@/lib/zipArchive';
+
+export const dynamic = 'force-dynamic';
+
+/** Same budget as the album archive: a whole album of originals per request. */
+const ARCHIVE_RPM = 5;
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ token: string }> },
+) {
+  const { token } = await params;
+  // One slot pool with the album archive route, taken before the first Immich
+  // request and before the download is counted against the link's limit.
+  return withArchiveSlot(request, (stream) => streamProofArchive(request, token, stream));
+}
+
+/** The handler's body, run inside the client's archive slot. */
+async function streamProofArchive(
+  request: NextRequest,
+  token: string,
+  stream: ArchiveStreamer,
+): Promise<Response> {
+  const access = await resolveProofAccess(request, token, 'proof-archive', ARCHIVE_RPM);
+  if ('error' in access) {
+    const status = access.error.status;
+    if (status === 429) {
+      const retry = Number(access.error.headers.get('Retry-After')) || undefined;
+      return refusal(request, 429, 'rateLimited', retry);
+    }
+    if (status === 503) return refusal(request, 503, 'immichUnavailable', 30);
+    if (status === 401) return access.error;
+    return refusal(request, 404, 'notAvailable');
+  }
+
+  const { session } = access;
+  const scope = request.nextUrl.searchParams.get('scope') === 'album' ? 'album' : 'selection';
+  if (session.download === 'none') return refusal(request, 404, 'notAvailable');
+  if (scope === 'album' && session.download !== 'album') {
+    return refusal(request, 404, 'notAvailable');
+  }
+
+  const chosen = new Set(session.selection);
+  const assets =
+    scope === 'album' ? access.assets : access.assets.filter((asset) => chosen.has(asset.id));
+  if (assets.length === 0) return refusal(request, 404, 'notAvailable');
+
+  try {
+    await claimDownload(token, scope);
+  } catch (err) {
+    if (err instanceof ProofError && err.code === 'limit') {
+      return refusal(request, 403, 'limitReached');
+    }
+    if (err instanceof ProofError) return refusal(request, 404, 'notAvailable');
+    throw err;
+  }
+
+  return stream(access.albumName, assets);
+}

app/api/proof/[token]/selection/route.ts

@@ -0,0 +1,51 @@
+/**
+ * PUT /api/proof/:token/selection — replace a client's saved selection.
+ *
+ * Body: `{ "assets": [<asset token>, …] }`, the album's opaque asset tokens in
+ * any order. Answers 409 once the selection has been submitted, which the page
+ * turns into its locked state.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { decodeSelection, proofError, resolveProofAccess } from '@/lib/proofAccess';
+import { MAX_SELECTION, ProofError, saveSelection } from '@/lib/proofSessions';
+import { readJsonCapped } from '@/lib/requestBody';
+
+export const dynamic = 'force-dynamic';
+
+/** Autosave fires once per burst of hearts; this is generous for one visitor. */
+const SELECTION_RPM = 60;
+
+/** MAX_SELECTION tokens of ~70 characters each, with room to spare. */
+const MAX_BODY_BYTES = 256 * 1024;
+
+export async function PUT(
+  request: NextRequest,
+  { params }: { params: Promise<{ token: string }> },
+) {
+  const { token } = await params;
+  const access = await resolveProofAccess(request, token, 'proof-save', SELECTION_RPM);
+  if ('error' in access) return access.error;
+
+  const body = (await readJsonCapped(request, MAX_BODY_BYTES)) as { assets?: unknown } | null;
+  const assets = body?.assets;
+  if (!Array.isArray(assets) || assets.length > MAX_SELECTION) {
+    return proofError(400, 'Invalid selection');
+  }
+  const ids = decodeSelection(assets, access.assets);
+  if (!ids) return proofError(400, 'Invalid selection');
+
+  try {
+    const session = await saveSelection(token, ids);
+    return NextResponse.json(
+      { ok: true, selected: session.selection.length },
+      { headers: { 'Cache-Control': 'no-store' } },
+    );
+  } catch (err) {
+    if (err instanceof ProofError && err.code === 'submitted') {
+      return proofError(409, 'Selection already submitted');
+    }
+    if (err instanceof ProofError) return proofError(404, 'Not found');
+    throw err;
+  }
+}

app/api/proof/[token]/submit/route.ts

@@ -0,0 +1,44 @@
+/**
+ * POST /api/proof/:token/submit — lock the client's selection and notify the
+ * photographer.
+ *
+ * Idempotent: submitting twice answers 200 both times, and only the first call
+ * fires the webhook.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { proofError, resolveProofAccess } from '@/lib/proofAccess';
+import { ProofError, submitSelection } from '@/lib/proofSessions';
+import { notifySubmitted } from '@/lib/proofWebhook';
+import { getConfig } from '@/lib/config';
+
+export const dynamic = 'force-dynamic';
+
+const SUBMIT_RPM = 10;
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ token: string }> },
+) {
+  const { token } = await params;
+  const access = await resolveProofAccess(request, token, 'proof-submit', SUBMIT_RPM);
+  if ('error' in access) return access.error;
+
+  try {
+    const { session, firstSubmit } = await submitSelection(token);
+    if (firstSubmit) {
+      // Not awaited: a slow or broken webhook must not hold up the client.
+      void notifySubmitted(session, access.albumName, getConfig().siteUrl);
+    }
+    return NextResponse.json(
+      { ok: true, submittedAt: session.submittedAt },
+      { headers: { 'Cache-Control': 'no-store' } },
+    );
+  } catch (err) {
+    if (err instanceof ProofError && err.code === 'empty') {
+      return proofError(400, 'Nothing selected');
+    }
+    if (err instanceof ProofError) return proofError(404, 'Not found');
+    throw err;
+  }
+}

app/api/proof/__tests__/routes.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { NextRequest } from 'next/server';
+
+/**
+ * The public proofing routes against a real session store in a temp dir. Immich,
+ * the asset tokens, the ZIP stream and the webhook are mocked; what is under
+ * test is the authorisation: which token may change what, and when.
+ */
+
+vi.mock('@/lib/config', () => ({
+  getConfig: vi.fn(() => ({ siteUrl: null })),
+  getConfigOrNull: vi.fn(() => null),
+}));
+vi.mock('@/lib/tokens', () => ({
+  decodeAssetId: vi.fn((token: string) => (token.startsWith('tok-') ? token.slice(4) : null)),
+}));
+vi.mock('@/lib/immich', () => ({
+  immich: { getProofingAlbum: vi.fn() },
+  ImmichUnavailableError: class ImmichUnavailableError extends Error {},
+}));
+vi.mock('@/lib/rate-limit', () => ({
+  checkRateLimit: vi.fn(() => ({ success: true, resetAt: 0 })),
+  getClientIp: vi.fn(() => '127.0.0.1'),
+  retryAfterSeconds: vi.fn(() => 60),
+}));
+vi.mock('@/lib/auth', () => ({ siteLockResponse: vi.fn(() => null) }));
+vi.mock('@/lib/proofWebhook', () => ({ notifySubmitted: vi.fn(async () => {}) }));
+vi.mock('@/lib/zipArchive', () => ({
+  withArchiveSlot: vi.fn(
+    (
+      _req: unknown,
+      handler: (stream: (name: string, assets: { id: string }[]) => Response) => unknown,
+    ) => handler((name, assets) => Response.json({ name, ids: assets.map((a) => a.id) })),
+  ),
+  refusal: vi.fn((_req: unknown, status: number, reason: string) =>
+    Response.json({ reason }, { status }),
+  ),
+}));
+
+import { PUT } from '../[token]/selection/route';
+import { POST } from '../[token]/submit/route';
+import { GET } from '../[token]/archive/route';
+import { immich } from '@/lib/immich';
+import { notifySubmitted } from '@/lib/proofWebhook';
+import { siteLockResponse } from '@/lib/auth';
+import { createSession, getSessionById, sessionInputSchema } from '@/lib/proofSessions';
+
+const mockAlbum = immich.getProofingAlbum as unknown as ReturnType<typeof vi.fn>;
+const mockNotify = notifySubmitted as unknown as ReturnType<typeof vi.fn>;
+const mockLock = siteLockResponse as unknown as ReturnType<typeof vi.fn>;
+
+const ALBUM_ID = '11111111-1111-1111-1111-111111111111';
+const ALBUM = {
+  id: ALBUM_ID,
+  albumName: 'Wedding',
+  assets: [
+    { id: 'a1', type: 'IMAGE', originalFileName: 'a1.jpg' },
+    { id: 'a2', type: 'IMAGE', originalFileName: 'a2.jpg' },
+    { id: 'a3', type: 'VIDEO', originalFileName: 'a3.mp4' },
+  ],
+};
+
+let dir: string;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'folio-proof-routes-'));
+  vi.spyOn(process, 'cwd').mockReturnValue(dir);
+  mockAlbum.mockResolvedValue(structuredClone(ALBUM));
+  mockNotify.mockClear();
+  mockLock.mockReturnValue(null);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+async function session(overrides: Record<string, unknown> = {}) {
+  return createSession(
+    sessionInputSchema.parse({ clientName: 'Anna', albumId: ALBUM_ID, ...overrides }),
+  );
+}
+
+const ctx = (token: string) => ({ params: Promise.resolve({ token }) });
+
+function put(token: string, assets: unknown) {
+  return PUT(
+    new NextRequest(`https://folio.example/api/proof/${token}/selection`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ assets }),
+    }),
+    ctx(token),
+  );
+}
+
+const submit = (token: string) =>
+  POST(
+    new NextRequest(`https://folio.example/api/proof/${token}/submit`, { method: 'POST' }),
+    ctx(token),
+  );
+
+const archive = (token: string, scope = 'selection') =>
+  GET(
+    new NextRequest(`https://folio.example/api/proof/${token}/archive?scope=${scope}`),
+    ctx(token),
+  );
+
+describe('PUT selection', () => {
+  it('saves the selection in album order', async () => {
+    const s = await session();
+    const res = await put(s.token, ['tok-a3', 'tok-a1']);
+    expect(res.status).toBe(200);
+    expect((await getSessionById(s.id))?.selection).toEqual(['a1', 'a3']);
+    // The album comes from the session, not from the request.
+    expect(mockAlbum).toHaveBeenCalledWith(ALBUM_ID);
+  });
+
+  it('refuses an asset from another album', async () => {
+    const s = await session();
+    expect((await put(s.token, ['tok-a1', 'tok-elsewhere'])).status).toBe(400);
+    expect((await put(s.token, ['garbage'])).status).toBe(400);
+    expect((await put(s.token, 'tok-a1')).status).toBe(400);
+    expect((await getSessionById(s.id))?.selection).toEqual([]);
+  });
+
+  it('answers 404 for an unknown or expired link', async () => {
+    expect((await put('x'.repeat(32), ['tok-a1'])).status).toBe(404);
+    const expired = await session({ expiresOn: '2000-01-01' });
+    expect((await put(expired.token, ['tok-a1'])).status).toBe(404);
+  });
+
+  it('answers 409 once submitted', async () => {
+    const s = await session();
+    await put(s.token, ['tok-a1']);
+    await submit(s.token);
+    expect((await put(s.token, ['tok-a2'])).status).toBe(409);
+  });
+
+  it('keeps the site password in charge', async () => {
+    const s = await session();
+    mockLock.mockReturnValue(Response.json({ error: 'locked' }, { status: 401 }));
+    expect((await put(s.token, ['tok-a1'])).status).toBe(401);
+  });
+});
+
+describe('POST submit', () => {
+  it('refuses an empty selection', async () => {
+    const s = await session();
+    expect((await submit(s.token)).status).toBe(400);
+    expect(mockNotify).not.toHaveBeenCalled();
+  });
+
+  it('locks the selection and notifies once', async () => {
+    const s = await session();
+    await put(s.token, ['tok-a2']);
+    expect((await submit(s.token)).status).toBe(200);
+    expect((await submit(s.token)).status).toBe(200);
+    expect(mockNotify).toHaveBeenCalledTimes(1);
+    expect((await getSessionById(s.id))?.submittedAt).toBeTruthy();
+  });
+});
+
+describe('GET archive', () => {
+  it('refuses when the link offers no downloads', async () => {
+    const s = await session();
+    await put(s.token, ['tok-a1']);
+    expect((await archive(s.token)).status).toBe(404);
+  });
+
+  it('streams only the saved selection', async () => {
+    const s = await session({ download: 'selection' });
+    await put(s.token, ['tok-a2']);
+    const res = await archive(s.token);
+    expect(await res.json()).toEqual({ name: 'Wedding', ids: ['a2'] });
+  });
+
+  it('allows the whole album only when the link says so', async () => {
+    const selectionOnly = await session({ download: 'selection' });
+    expect((await archive(selectionOnly.token, 'album')).status).toBe(404);
+
+    const whole = await session({ download: 'album' });
+    const res = await archive(whole.token, 'album');
+    expect((await res.json()).ids).toEqual(['a1', 'a2', 'a3']);
+  });
+
+  it('stops at the download limit', async () => {
+    const s = await session({ download: 'album', downloadLimit: 1 });
+    expect((await archive(s.token, 'album')).status).toBe(200);
+    const refused = await archive(s.token, 'album');
+    expect(refused.status).toBe(403);
+    expect(await refused.json()).toEqual({ reason: 'limitReached' });
+  });
+});