Add upload endpoint (#60)

Author: SteffenDE

README.md

@@ -108,11 +108,19 @@ features.
 
 Vite's `tidewave` accepts the configuration options below:
 
-- `allow_remote_access:` Tidewave only allows requests from localhost by
-  default, even if your server listens on other interfaces, for security
-  purposes. Read
+- `allowRemoteAccess`: Tidewave only allows requests from localhost by default,
+  even if your server listens on other interfaces, for security purposes. Read
   [our security guidelines for more information and when to allow remote access](https://hexdocs.pm/tidewave/security.html)
   (if you know what you are doing)
+- `allowedOrigins`: a list of values matched against the `Origin` header to
+  prevent cross origin and DNS rebinding attacks. Each value must be a string of
+  shape `[scheme:]//host[:port]`, where both scheme and port are optional. The
+  host may also start with `*`. Example: `["//localhost:8000", "//*.test"]`. By
+  default, Tidewave allows Vite's configured server host and port, using
+  `localhost` when Vite uses its implicit host
+- `tmpDir`: temporary directory Tidewave uses for screenshots and recordings.
+  Defaults to `tmp`, storing files under `tmp/tidewave/screenshots` and
+  `tmp/tidewave/recordings`
 - `team`: enable Tidewave Web for teams
 
 ## Available tools

src/core.ts

@@ -142,10 +142,14 @@ export function createExtractError(
 }
 
 export interface TidewaveConfig {
+  port?: number;
+  host?: string;
   clientUrl?: string;
   allowRemoteAccess?: boolean;
+  allowedOrigins?: string[];
   projectName?: string;
   framework?: string;
+  tmpDir?: string;
   team?: {
     id?: string;
     token?: string;

src/http/handlers/config.ts

@@ -20,6 +20,7 @@ export function createHandleConfig(
         tidewave_version: tidewavePackage.version,
         team: config.team || {},
         local_port: getLocalPort?.(),
+        tmp_dir: config.tmpDir || 'tmp',
       };
 
       res.statusCode = 200;

src/http/handlers/upload.ts

@@ -0,0 +1,227 @@
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import type { TidewaveConfig } from '../../core';
+import type { TidewaveHandler, TidewaveNext, TidewaveRequest, TidewaveResponse } from '../types';
+import { magicByteType } from '../magic-bytes';
+import { checkOrigin } from '../security';
+
+const MAX_UPLOAD_SIZE = 200_000_000;
+const ALLOWED_UPLOAD_CONTENT_TYPES = ['image/png', 'image/jpeg', 'video/webm'] as const;
+const ALLOWED_UPLOAD_TYPES = ['screenshot', 'recording'] as const;
+const ALLOWED_UPLOAD_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webm'] as const;
+const INVALID_UPLOAD = 'Bad Request: missing or invalid file parameter';
+
+class InvalidUploadError extends Error {}
+
+interface UploadedFile {
+  readonly name: string;
+  readonly type: string;
+  arrayBuffer(): Promise<ArrayBuffer>;
+}
+
+interface UploadFormData {
+  get(name: string): unknown;
+}
+
+export function createHandleUpload(config: TidewaveConfig): TidewaveHandler {
+  return async function handleUpload(
+    req: TidewaveRequest,
+    res: TidewaveResponse,
+    next: TidewaveNext,
+  ): Promise<void> {
+    try {
+      if (req.method !== 'POST') {
+        notFound(res);
+        return;
+      }
+
+      if (!checkOrigin(req, res, config)) return;
+      if (uploadTooLarge(req)) {
+        badRequest(res);
+        return;
+      }
+
+      const formData = await parseFormData(req);
+      const type = formData.get('type');
+      const file = formData.get('file');
+
+      if (!isAllowedUploadType(type) || !isUploadedFile(file)) {
+        badRequest(res);
+        return;
+      }
+
+      const buffer = Buffer.from(await file.arrayBuffer());
+
+      if (!isAllowedUpload(file, buffer)) {
+        badRequest(res);
+        return;
+      }
+
+      const destination = uploadPath(config, type, file.name);
+      if (!destination) {
+        badRequest(res);
+        return;
+      }
+
+      await mkdir(uploadDir(config, type), { recursive: true });
+      await writeFile(destination, buffer);
+
+      res.statusCode = 200;
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify({ status: 'ok', path: destination }));
+    } catch (err) {
+      if (err instanceof InvalidUploadError) {
+        badRequest(res);
+        return;
+      }
+
+      console.error(`[Tidewave] Failed to handle upload: ${err}`);
+
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.end('Internal server error');
+      }
+
+      next(err);
+    }
+  };
+}
+
+function uploadTooLarge(req: TidewaveRequest): boolean {
+  const contentLength = firstHeaderValue(req.headers['content-length']);
+  if (!contentLength) return false;
+
+  const size = Number(contentLength);
+  return Number.isFinite(size) && size > MAX_UPLOAD_SIZE;
+}
+
+async function parseFormData(req: TidewaveRequest): Promise<UploadFormData> {
+  const body = await readRequestBody(req);
+  const request = new Request(requestUrl(req), {
+    method: req.method,
+    headers: requestHeaders(req),
+    body: toArrayBuffer(body),
+  });
+
+  try {
+    return await request.formData();
+  } catch {
+    throw new InvalidUploadError(INVALID_UPLOAD);
+  }
+}
+
+async function readRequestBody(req: TidewaveRequest): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+
+    if (size > MAX_UPLOAD_SIZE) {
+      throw new InvalidUploadError(INVALID_UPLOAD);
+    }
+
+    chunks.push(buffer);
+  }
+
+  return Buffer.concat(chunks);
+}
+
+function toArrayBuffer(buffer: Buffer): ArrayBuffer {
+  const arrayBuffer = new ArrayBuffer(buffer.byteLength);
+  new Uint8Array(arrayBuffer).set(buffer);
+  return arrayBuffer;
+}
+
+function requestUrl(req: TidewaveRequest): string {
+  const host = firstHeaderValue(req.headers.host) || 'localhost';
+  return `http://${host}${req.url || '/'}`;
+}
+
+function requestHeaders(req: TidewaveRequest): Headers {
+  const headers = new Headers();
+
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(name, item);
+    } else if (value !== undefined) {
+      headers.set(name, value);
+    }
+  }
+
+  return headers;
+}
+
+function firstHeaderValue(value: string | string[] | undefined): string | undefined {
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+
+function isAllowedUploadType(type: unknown): type is (typeof ALLOWED_UPLOAD_TYPES)[number] {
+  return typeof type === 'string' && isOneOf(ALLOWED_UPLOAD_TYPES, type);
+}
+
+function isUploadedFile(file: unknown): file is UploadedFile {
+  if (typeof file !== 'object' || file === null) return false;
+
+  const candidate = file as Partial<UploadedFile>;
+  return (
+    typeof candidate.name === 'string' &&
+    typeof candidate.type === 'string' &&
+    typeof candidate.arrayBuffer === 'function'
+  );
+}
+
+function isAllowedUpload(file: UploadedFile, buffer: Buffer): boolean {
+  const [contentType] = file.type.split(';');
+
+  return (
+    isOneOf(ALLOWED_UPLOAD_CONTENT_TYPES, contentType || '') &&
+    magicByteType(buffer.subarray(0, 128)) !== 'unknown'
+  );
+}
+
+function uploadDir(config: TidewaveConfig, type: (typeof ALLOWED_UPLOAD_TYPES)[number]): string {
+  return path.join(tmpDir(config), 'tidewave', folderForType(type));
+}
+
+function uploadPath(
+  config: TidewaveConfig,
+  type: (typeof ALLOWED_UPLOAD_TYPES)[number],
+  filename: string,
+): string | null {
+  if (!/^[A-Za-z0-9_.-]+$/.test(filename)) return null;
+
+  const ext = path.extname(filename).toLowerCase();
+  if (!isOneOf(ALLOWED_UPLOAD_EXTENSIONS, ext)) return null;
+
+  return path.join(uploadDir(config, type), filename);
+}
+
+function isOneOf<const T extends readonly string[]>(values: T, value: string): value is T[number] {
+  return values.includes(value);
+}
+
+function tmpDir(config: TidewaveConfig): string {
+  return config.tmpDir || 'tmp';
+}
+
+function folderForType(type: (typeof ALLOWED_UPLOAD_TYPES)[number]): string {
+  switch (type) {
+    case 'screenshot':
+      return 'screenshots';
+    case 'recording':
+      return 'recordings';
+  }
+}
+
+function badRequest(res: TidewaveResponse): void {
+  res.statusCode = 400;
+  res.end(INVALID_UPLOAD);
+}
+
+function notFound(res: TidewaveResponse): void {
+  res.statusCode = 404;
+  res.end('Not Found');
+}

src/http/index.ts

@@ -2,6 +2,7 @@ import { checkRemoteIp } from './security';
 import { handleMcp } from './handlers/mcp';
 import { createHandleHtml } from './handlers/html';
 import { createHandleConfig, type LocalPortGetter } from './handlers/config';
+import { createHandleUpload } from './handlers/upload';
 import bodyParser from 'body-parser';
 import type { TidewaveConfig } from '../core';
 import type {
@@ -30,6 +31,7 @@ export function configureServer(
   server.use(`${ENDPOINT}`, securityChecker);
   server.use(`${ENDPOINT}/`, createHandleHtml(config));
   server.use(`${ENDPOINT}/config`, createHandleConfig(config, options.getLocalPort));
+  server.use(`${ENDPOINT}/upload`, createHandleUpload(config));
   server.use(`${ENDPOINT}/mcp`, bodyParser.json());
   server.use(`${ENDPOINT}/mcp`, handleMcp);
 

src/http/magic-bytes.ts

@@ -0,0 +1,26 @@
+export type MagicByteType = 'jpg' | 'png' | 'webm' | 'unknown';
+
+export function magicByteType(bytes: Uint8Array): MagicByteType {
+  if (startsWith(bytes, [0xff, 0xd8, 0xff])) return 'jpg';
+
+  if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) {
+    return 'png';
+  }
+
+  if (startsWith(bytes, [0x1a, 0x45, 0xdf, 0xa3])) {
+    return includesAscii(bytes, 'webm') ? 'webm' : 'unknown';
+  }
+
+  return 'unknown';
+}
+
+function startsWith(bytes: Uint8Array, prefix: number[]): boolean {
+  if (bytes.length < prefix.length) return false;
+
+  return prefix.every((byte, index) => bytes[index] === byte);
+}
+
+function includesAscii(bytes: Uint8Array, text: string): boolean {
+  const needle = Buffer.from(text, 'ascii');
+  return Buffer.from(bytes).includes(needle);
+}

src/http/security.ts

@@ -39,6 +39,81 @@ export function checkRemoteIp(
   return false;
 }
 
+export function checkOrigin(
+  req: TidewaveRequest,
+  res: TidewaveResponse,
+  config: TidewaveConfig,
+): boolean {
+  const { origin } = req.headers;
+
+  // No origin header means non-browser request (e.g. Claude Code, Cursor)
+  if (!origin) return true;
+
+  const allowedOrigins = config.allowedOrigins || getDefaultAllowedOrigins(config);
+  const originUrl = parseUrl(origin);
+
+  if (!originUrl) {
+    const message = `For security reasons, Tidewave only accepts requests from allowed origins.\n\nInvalid origin: ${origin}`;
+    console.warn(message);
+    res.statusCode = 403;
+    res.end(message);
+    return false;
+  }
+
+  const isAllowed = allowedOrigins.some(allowed => isOriginAllowed(originUrl, parseUrl(allowed)));
+
+  if (!isAllowed) {
+    const message = `For security reasons, Tidewave only accepts requests from the same origin your web app is running on.\n\nIf you really want to allow remote connections, configure the Tidewave with the \`allowedOrigins: [${JSON.stringify(origin)}]\` option.`;
+    console.warn(message);
+    res.statusCode = 403;
+    res.end(message);
+    return false;
+  }
+
+  return true;
+}
+
+export function getDefaultAllowedOrigins(config: TidewaveConfig): string[] {
+  const { host, port } = config;
+  if (!(host || port)) return [];
+  return [`http://${host}:${port}`, `https://${host}:${port}`];
+}
+
+export function parseUrl(url: string): { scheme?: string; host: string; port?: number } | null {
+  try {
+    const isProtocolRelative = url.startsWith('//');
+    const parsed = new URL(isProtocolRelative ? 'http:' + url : url);
+    return {
+      scheme: isProtocolRelative ? undefined : parsed.protocol?.slice(0, -1),
+      host: parsed.hostname,
+      port: parsed.port ? parseInt(parsed.port) : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function isOriginAllowed(
+  origin: ReturnType<typeof parseUrl>,
+  allowed: ReturnType<typeof parseUrl>,
+): boolean {
+  if (!origin || !allowed) return false;
+
+  // Check scheme (if specified in allowed)
+  if (allowed.scheme && origin.scheme !== allowed.scheme) return false;
+
+  // Check port (if specified in allowed)
+  if (allowed.port && origin.port !== allowed.port) return false;
+
+  // Check host with wildcard support
+  if (allowed.host.startsWith('*.')) {
+    const allowedDomain = allowed.host.slice(2);
+    return origin.host === allowedDomain || origin.host.endsWith('.' + allowedDomain);
+  }
+
+  return origin.host === allowed.host;
+}
+
 export function isLocalIp(ip?: string): boolean {
   if (!ip) return false;