Sichere Datei-Uploads in Next.js mit Uppy und signierten Transloadit Templates

Anwendungsautorisierung und Upload-Ausführung trennen

Der Browser ist ein nicht vertrauenswürdiger Aufrufer, selbst wenn die Oberfläche Teil Ihrer Next.js-Anwendung ist. Eine Client Component darf den öffentlichen Auth Key und eine Template ID enthalten, jedoch niemals das Auth Secret für den Workspace, unverarbeitete Speicherzugangsdaten oder die Berechtigung, beliebige Verarbeitungs-Steps auszuwählen. Hinterlegen Sie das Auth Secret hinter einem Route Handler. Dieser Endpunkt muss entscheiden, ob der aktuelle Nutzer der Anwendung genau diesen Upload starten darf.

Diese Entscheidung ist von der Integrität der Transloadit-Anfrage getrennt. Eine gültige Signatur belegt, dass Ihr Server die serialisierten Assembly-Parameter für einen begrenzten Zeitraum genehmigt hat. Sie belegt nicht, dass die Person, die Ihren Server um eine Signatur bittet, Eigentümerin eines Projekts ist, ihr Kontingent einhält, eine CSRF-Prüfung bestanden hat oder das Ergebnis veröffentlichen darf. Der Autorisierungsadapter der Anwendung muss diese Regeln vor der Signierung durchsetzen. Das gespeicherte Template beschränkt anschließend, was Transloadit ausführt.

Das Template vor dem Bereitstellen des Upload-Formulars sperren

Speichern Sie den Verarbeitungsworkflow als Template. Setzen Sie allow_steps_override auf false, damit ein Browser nicht zusammen mit seiner template_id andere Steps übermitteln kann. Aktivieren Sie für dieses Template „Gültige Signatur verlangen“ oder verlangen Sie korrekte Signaturen für den gesamten Workspace. Dies sind separate Steuerelemente: Das gesperrte Template legt den Verarbeitungsgraphen fest, während die Signaturprüfung signierte Parameter zurückweist, die verändert, abgelaufen oder aus anderen Gründen ungültig sind. Ihre Anwendung entscheidet weiterhin, welcher Nutzer diese Parameter erhalten darf.

Wiederholen Sie kostengünstige Schnittstellenbeschränkungen an der Verarbeitungsgrenze. Das Beispiel begrenzt jede Datei auf 50 MiB und die Zahl der Dateien pro Assembly auf fünf. Zudem prüft es mit /file/filter die erkannten MIME-Metadaten, statt dem Dateinamen oder der Browserdeklaration zu vertrauen. Passen Sie die genaue Positivliste an das Produkt an. Ergänzen Sie Verifizierung, Malware-Scanning, Quarantäne oder eine Prüfung durch Menschen, wenn das Inhaltsrisiko dies erfordert. Keine einzelne MIME-Prüfung macht beliebige nutzergenerierte Inhalte sicher.

Der Wert user_uploads bezeichnet Template-Zugangsdaten, die im Workspace gespeichert sind. Gewähren Sie diesem externen Principal nur die Speicheroperationen sowie den Zugriff auf den Bucket und die Pfade, die dieser Workflow benötigt. Der Browser empfängt und signiert den zugrunde liegenden Zugriffsschlüssel nicht. Die Zugangsdaten können daher unabhängig vom Next.js-Bundle rotiert werden. Die Rotation muss jedoch koordiniert erfolgen, da sie jedes Template betrifft, das auf diesen Eintrag verweist.

{
  "allow_steps_override": false,
  "auth": {
    "max_number_of_files": 5,
    "max_size": 52428800
  },
  "notify_url": "https://app.example.com/api/transloadit-notifications",
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^(image/jpeg|image/png|image/webp)$"]
      ],
      "error_on_decline": true,
      "error_msg": "Only JPEG, PNG, and WebP images are accepted"
    },
    "stored": {
      "use": "accepted_images",
      "robot": "/s3/store",
      "credentials": "user_uploads"
    }
  }
}

Eine kurzlebige Anfrage in einem server-only-Modul signieren

Speichern Sie die Serverkonfiguration in Umgebungsvariablen ohne das Präfix NEXT_PUBLIC_ und importieren Sie server-only am Anfang des Signaturmoduls. Next.js lässt den Build fehlschlagen, wenn Client-Code dieses Modul importiert. Der Marker ist eine nützliche Schutzmaßnahme, aber kein Secret-Manager: Zugriffsrichtlinien für die Produktion, das Entfernen vertraulicher Daten aus Logs, die Isolation von Vorschauumgebungen und die Rotation von Zugangsdaten bleiben weiterhin wichtig.

Der konfigurierte Auth Key wird vom Node SDK hinzugefügt. Anschließend serialisiert das SDK die Parameter und gibt genau diesen params-String zusammen mit seiner Signatur zurück. Geben Sie beide Werte unverändert zurück. Wenn Sie den String nach dem Signieren parsen, ein Feld hinzufügen oder ihn in einer anderen Reihenfolge erneut serialisieren, entsteht eine andere Payload, die abgelehnt werden sollte. Im Beispiel läuft die Gültigkeit nach fünf Minuten ab, da Uppy die Optionen unmittelbar vor dem Erstellen der Assembly anfordert und für jede Autorisierung eine neue Nonce hinzufügt.

Wählen Sie das Template auf dem Server aus. Übernehmen Sie weder template_id, steps, notify_url, Export-Zugangsdaten noch unbegrenzte Transformationswerte aus dem Request-Body, um sie ungeprüft zu signieren. Wenn das Produkt tatsächlich mehrere Upload-Workflows anbietet, ordnen Sie nach Prüfung der Nutzerberechtigung einen kleinen Vorgang auf Anwendungsebene wie avatar oder product-gallery einem Template und Grenzwerten aus einer Positivliste zu.

import 'server-only'

import { randomUUID } from 'node:crypto'

import { Transloadit } from 'transloadit'

export interface AssemblyOptions {
  params: string
  signature: string
}

type TransloaditEnvironmentName =
  | 'TRANSLOADIT_KEY'
  | 'TRANSLOADIT_SECRET'
  | 'TRANSLOADIT_TEMPLATE_ID'

function readServerEnvironment(name: TransloaditEnvironmentName): string {
  const value = process.env[name]
  if (value == null || value === '') {
    throw new Error('Missing Transloadit server configuration')
  }

  return value
}

const templateId = readServerEnvironment('TRANSLOADIT_TEMPLATE_ID')
const transloadit = new Transloadit({
  authKey: readServerEnvironment('TRANSLOADIT_KEY'),
  authSecret: readServerEnvironment('TRANSLOADIT_SECRET'),
})

export function createAssemblyOptions(): AssemblyOptions {
  const requestParameters = {
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      nonce: randomUUID(),
    },
    template_id: templateId,
  }

  return transloadit.calcSignature(requestParameters)
}

Den Signatur-Endpunkt des App Router schützen

Ein Route Handler ist wie jeder andere HTTP-Endpunkt erreichbar. Die Funktion authorizeUpload im Beispiel ist bewusst anwendungsspezifisch: Verbinden Sie sie mit der vorhandenen Sitzungsbibliothek des Projekts, Prüfungen der Ressourceneigentümerschaft, der CSRF-Strategie und der gemeinsamen Begrenzung der Anfragerate. Geben Sie eine Ablehnung zurück, bevor Sie die Signatur erzeugen. Legen Sie bei mandantenfähigen Anwendungen Grenzwerte sowohl nach Mandant als auch nach Nutzer fest und prüfen Sie den Mandanten, dem das spätere Asset gehören wird.

Die Route akzeptiert keine beliebigen Assembly-Parameter und kennzeichnet eine erfolgreiche Antwort mit no-store. Ihre öffentliche Fehlermeldung ist bewusst allgemein gehalten. Protokollieren Sie serverseitig eine interne Request- oder Trace-ID, die Entscheidungskategorie und die Akteur-ID. Geben Sie jedoch keine Stacktraces, Konto-IDs, Antwortinhalte von Drittanbietern oder Details zu Zugangsdaten an den Browser zurück. Lassen Sie unerwartete Fehler von der zentralen, bereinigten Fehlerbehandlung der Anwendung verarbeiten, statt jeden Aufruf in einen unnötig ausführlichen catch-Block einzuschließen.

Die Begrenzung der Anfragerate für die Signatur-Route steuert die Erstellung von Assemblies, ersetzt jedoch weder Abrechnungslimits des Kontos noch Dateilimits des Templates oder Anwendungskontingente. Wenden Sie alle drei an. Eine Signatur ist eine kurzlebige Berechtigung: Wer die vollständige signierte Payload erhält, kann versuchen, sie während ihrer Gültigkeit zu übermitteln. Senden Sie sie daher nur über HTTPS und vermeiden Sie Analytics, Browser-Speicher, URLs und Logs, in denen sie erhalten bleibt.

import type { NextRequest } from 'next/server'

import { NextResponse } from 'next/server'

import { authorizeUpload } from '../../../server/upload-authorization'
import {
  type AssemblyOptions,
  createAssemblyOptions,
} from '../../../server/transloadit-options'

interface ErrorResponse {
  error: string
}

export async function POST(
  request: NextRequest,
): Promise<NextResponse<AssemblyOptions | ErrorResponse>> {
  const permission = await authorizeUpload(request)
  if (!permission.allowed) {
    return NextResponse.json({ error: 'Upload not allowed' }, { status: 403 })
  }

  return NextResponse.json(createAssemblyOptions(), {
    headers: { 'Cache-Control': 'no-store' },
  })
}

Uppy einmal innerhalb einer Client Component einbinden

Uppy benötigt Browser-APIs. Daher befindet sich der Dateiuploader hinter einer use client-Grenze. Erstellen Sie die Uppy-Instanz mit einem verzögerten State-Initialisierer genau einmal. Wird sie während des Renderns neu erstellt, gehen ausgewählte Dateien verloren und die Zuständigkeit für den Lebenszyklus wird unterbrochen. Diese Komponente zerstört die Instanz, wenn sie für den gesamten Upload-Lebenszyklus zuständig ist. Müssen Uploads die Navigation zwischen Routen überdauern, verschieben Sie die Instanz in einen langlebigeren Client-Anbieter und zerstören Sie sie, wenn dieser Anbieter beendet wird.

Die asynchrone Funktion assemblyOptions ruft die geschützte Route auf, während Uppy den Upload vorbereitet. Sie prüft response.ok, verarbeitet fehlerhaftes JSON sicher, validiert die Struktur der Antwort und zeigt Nutzern nur einen stabilen Autorisierungsfehler an. Das Dashboard von Uppy stellt die Benutzeroberfläche für Auswahl, Fortschritt, Abbruch und Fehler bereit. Das Transloadit-Plugin erstellt währenddessen die Assembly und sendet Dateien über eine fortsetzbare Upload-Infrastruktur. Der begrenzte Zeitplan für Wiederholungsversuche hilft bei vorübergehenden Fehlern, ohne diese unbegrenzt fortzusetzen.

Diese Wiederholungsversuche laufen, solange diese Uppy-Instanz aktiv bleibt. Sie sorgen nicht dafür, dass die gezeigte Komponente nach dem erneuten Laden der Seite ausgewählte Dateien und den Zustand der Assembly wiederherstellt. Wenn die Wiederherstellung nach dem erneuten Laden eine Produktanforderung ist, konfigurieren und testen Sie das Golden-Retriever-Plugin oder ein anderes dokumentiertes Persistenzkonzept mit dem Transloadit-Plugin. Leiten Sie diese Funktion nicht allein aus tus oder retryDelays ab.

Die Browser-Grenzwerte entsprechen dem Template und ermöglichen schnelles Feedback, bilden aber nicht die Sicherheitsgrenze. Ein Aufrufer kann die Komponente umgehen, und Dateimetadaten können falsch sein. Legen Sie die maßgeblichen Vorgaben für Dateianzahl, Bytegröße, Prüfungen erkannter Inhalte und Exportrichtlinien im gesperrten Template fest. Entscheiden Sie außerdem, ob ein Abbruch im Browser nur die Übertragung, die Assembly oder den Asset-Datensatz der Anwendung abbrechen soll. Testen Sie diese Entscheidung, statt anzunehmen, dass alle drei Zustände identisch sind.

'use client'

import Uppy from '@uppy/core'
import Dashboard from '@uppy/react/dashboard'
import Transloadit from '@uppy/transloadit'
import { type ReactNode, useEffect, useState } from 'react'
import { z } from 'zod'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

const assemblyOptionsSchema = z.object({
  params: z.string().min(1),
  signature: z.string().regex(/^(sha1|sha256|sha384):[0-9a-f]+$/),
})

async function fetchAssemblyOptions(): Promise<z.infer<typeof assemblyOptionsSchema>> {
  const response = await fetch('/api/transloadit-params', {
    method: 'POST',
    headers: { Accept: 'application/json' },
  })

  if (!response.ok) {
    throw new Error('Could not authorize this upload. Try again.')
  }

  const responseBody: unknown = await response.json().catch(() => null)
  const parsedOptions = assemblyOptionsSchema.safeParse(responseBody)
  if (!parsedOptions.success) {
    throw new Error('Could not authorize this upload. Try again.')
  }

  return parsedOptions.data
}

function createUppy(): Uppy {
  return new Uppy({
    restrictions: {
      allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
      maxFileSize: 50 * 1024 * 1024,
      maxNumberOfFiles: 5,
    },
  }).use(Transloadit, {
    assemblyOptions: fetchAssemblyOptions,
    retryDelays: [0, 1_000, 3_000, 5_000],
    waitForEncoding: false,
  })
}

export function UploadForm(): ReactNode {
  const [uppy] = useState(createUppy)

  useEffect(() => {
    return () => uppy.destroy()
  }, [uppy])

  return <Dashboard height={420} proudlyDisplayPoweredByUppy={false} uppy={uppy} />
}

Fortschritt, Wiederholungsversuche und Abschluss abgleichen

Übertragungsfortschritt und Verarbeitungsfortschritt beantworten unterschiedliche Fragen. Mit waitForEncoding: false kann die Benutzeroberfläche den Vorgang abschließen, sobald die Bytes Transloadit erreicht haben, während Validierung, Transformation und Export fortgesetzt werden. Reagieren Sie auf transloadit:assembly-created und verknüpfen Sie die Assembly ID mit einem ausstehenden Anwendungsdatensatz. Eine Navigation kann dann die Beobachtung im Browser unterbrechen, ohne die für den Abgleich benötigte Identität zu verlieren.

Hinterlegen Sie für den asynchronen Abschluss eine feste notify_url im serverseitig verwalteten Template. Der Notification Handler muss die Signatur mit dem Auth Secret prüfen, dem der Auth Key der Assembly zugeordnet ist. Anschließend muss er die Payload validieren, die Assembly ID dem erwarteten ausstehenden Datensatz zuordnen und die Ergebnisse idempotent anwenden, bevor er den Erfolg zurückgibt. Notifications können erneut zugestellt werden. Ein Duplikat muss daher den vorhandenen Endzustand bestätigen, statt ein weiteres Asset oder Veröffentlichungsereignis zu erstellen.

Verwenden Sie waitForEncoding: true nur für kurze Workflows, bei denen der Nutzer auf der Seite bleiben soll und Browsercode die endgültigen Ergebnisse tatsächlich benötigt. Behalten Sie selbst dann einen serverseitigen Wiederherstellungspfad bei, da Tabs geschlossen werden und Verbindungen abbrechen können. Ein geplanter Abgleichvorgang kann nicht abgeschlossene Assemblies abfragen, deren Benachrichtigungen nicht eingegangen sind. Legen Sie die Wiederholungsrichtlinie je nach Fehler fest: Setzen Sie nach einer Netzwerkunterbrechung die Übertragung fort, fordern Sie neue signierte Optionen an, wenn sie vor dem Erstellen der Assembly ablaufen, und stoppen Sie nach einer Richtlinienablehnung, bis der Nutzer die Datei ändert.

Die Kontrollen als Angreifer und als Nutzer mit unterbrochener Verbindung testen

Testen Sie den Signatur-Endpunkt ohne Sitzung, mit dem falschen Mandanten, gegebenenfalls mit einem fehlenden oder ungültigen CSRF-Token, oberhalb des Limits für die Anfragerate und nach dem Entzug von Berechtigungen. Vergewissern Sie sich, dass weder Antworten noch Protokolle das Auth Secret, Template-Zugangsdaten, einen Stacktrace oder unverarbeitete Abhängigkeitsfehler enthalten. Versuchen Sie, template_id zu ersetzen, steps hinzuzufügen, auth.expires zu verlängern und signierte Optionen nach ihrem Ablauf zu übermitteln. Die Signaturprüfung oder die Durchsetzung durch das Template sollte die ungültige Anfrage ablehnen.

Testen Sie ein zulässiges JPEG, einen unzulässigen MIME-Typ mit einer Bilddateiendung, eine zu große Datei, zu viele Dateien, eine Datei mit null Byte, Verbindungsabbrüche an mehreren Positionen, das Neuladen des Browsers, einen Abbruch, eine abgelaufene Autorisierung, eine doppelte Benachrichtigung, eine Speicherablehnung und einen Verarbeitungsfehler nach dem Upload. Vergewissern Sie sich, dass das Verhalten beim Neuladen dem Persistenzkonzept entspricht, statt eine automatische Wiederherstellung vorauszusetzen. Prüfen Sie mit Tastatur und Hilfstechnologien, ob Fortschritts- und Fehlermeldungen barrierefrei zugänglich sind. Untersuchen Sie anschließend den temporären Speicher und die Anwendungsdatensätze auf Datenlecks oder dauerhaft ausstehende Zustände.

Überwachen Sie abgelehnte Signaturen, Entscheidungen zur Begrenzung der Anfragerate, die Erstellungs- und Fehlerraten von Assemblies, die Wiederherstellung von Uploads, die Verarbeitungslatenz, das Alter von Benachrichtigungen, Speicherfehler und das Alter ausstehender Datensätze, ohne geschützte Nutzdaten zu protokollieren. Lösen Sie Warnungen bei anhaltenden Änderungen aus, nicht bei einzelnen Nutzerfehlern. Halten Sie die Template ID und die von der Anwendung verwaltete Workflow-Version in den Betriebsdaten fest, da sich ein gespeichertes Template im Laufe der Zeit ändern kann.