fix(security): path traversal and SSRF protections from pre-launch audit

Fixes 4 high-severity findings from a comprehensive security audit:

1. Path traversal on ZIM file delete — resolve()+startsWith() containment
2. Path traversal on Map file delete — same pattern
3. Path traversal on docs read — same pattern (already used in rag_service)
4. SSRF on download endpoints — block private/internal IPs, require TLD

Also adds assertNotPrivateUrl() to content update endpoints.

Full audit report attached as admin/docs/security-audit-v1.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

admin/app/controllers/collection_updates_controller.ts

@@ -1,5 +1,6 @@
 import { CollectionUpdateService } from '#services/collection_update_service'
 import {
+  assertNotPrivateUrl,
   applyContentUpdateValidator,
   applyAllContentUpdatesValidator,
 } from '#validators/common'
@@ -13,12 +14,16 @@ export default class CollectionUpdatesController {
 
   async applyUpdate({ request }: HttpContext) {
     const update = await request.validateUsing(applyContentUpdateValidator)
+    assertNotPrivateUrl(update.download_url)
     const service = new CollectionUpdateService()
     return await service.applyUpdate(update)
   }
 
   async applyAllUpdates({ request }: HttpContext) {
     const { updates } = await request.validateUsing(applyAllContentUpdatesValidator)
+    for (const update of updates) {
+      assertNotPrivateUrl(update.download_url)
+    }
     const service = new CollectionUpdateService()
     return await service.applyAllUpdates(updates)
   }

admin/app/controllers/maps_controller.ts

@@ -1,5 +1,6 @@
 import { MapService } from '#services/map_service'
 import {
+  assertNotPrivateUrl,
   downloadCollectionValidator,
   filenameParamValidator,
   remoteDownloadValidator,
@@ -25,12 +26,14 @@ export default class MapsController {
 
   async downloadBaseAssets({ request }: HttpContext) {
     const payload = await request.validateUsing(remoteDownloadValidatorOptional)
+    if (payload.url) assertNotPrivateUrl(payload.url)
     await this.mapService.downloadBaseAssets(payload.url)
     return { success: true }
   }
 
   async downloadRemote({ request }: HttpContext) {
     const payload = await request.validateUsing(remoteDownloadValidator)
+    assertNotPrivateUrl(payload.url)
     const filename = await this.mapService.downloadRemote(payload.url)
     return {
       message: 'Download started successfully',
@@ -52,6 +55,7 @@ export default class MapsController {
   // For providing a "preflight" check in the UI before actually starting a background download
   async downloadRemotePreflight({ request }: HttpContext) {
     const payload = await request.validateUsing(remoteDownloadValidator)
+    assertNotPrivateUrl(payload.url)
     const info = await this.mapService.downloadRemotePreflight(payload.url)
     return info
   }

admin/app/controllers/zim_controller.ts

@@ -1,5 +1,6 @@
 import { ZimService } from '#services/zim_service'
 import {
+  assertNotPrivateUrl,
   downloadCategoryTierValidator,
   filenameParamValidator,
   remoteDownloadWithMetadataValidator,
@@ -25,6 +26,7 @@ export default class ZimController {
 
   async downloadRemote({ request }: HttpContext) {
     const payload = await request.validateUsing(remoteDownloadWithMetadataValidator)
+    assertNotPrivateUrl(payload.url)
     const { filename, jobId } = await this.zimService.downloadRemote(payload.url)
 
     return {

admin/app/services/docs_service.ts

@@ -66,12 +66,19 @@ export class DocsService {
 
       const filename = _filename.endsWith('.md') ? _filename : `${_filename}.md`
 
-      const fileExists = await getFileStatsIfExists(path.join(this.docsPath, filename))
+      // Prevent path traversal — resolved path must stay within the docs directory
+      const basePath = path.resolve(this.docsPath)
+      const fullPath = path.resolve(path.join(this.docsPath, filename))
+      if (!fullPath.startsWith(basePath + path.sep)) {
+        throw new Error('Invalid document slug')
+      }
+
+      const fileExists = await getFileStatsIfExists(fullPath)
       if (!fileExists) {
         throw new Error(`File not found: ${filename}`)
       }
 
-      const fileStream = await getFile(path.join(this.docsPath, filename), 'stream')
+      const fileStream = await getFile(fullPath, 'stream')
       if (!fileStream) {
         throw new Error(`Failed to read file stream: ${filename}`)
       }

admin/app/services/map_service.ts

@@ -13,7 +13,7 @@ import {
   getFile,
   ensureDirectoryExists,
 } from '../utils/fs.js'
-import { join } from 'path'
+import { join, resolve, sep } from 'path'
 import urlJoin from 'url-join'
 import { RunDownloadJob } from '#jobs/run_download_job'
 import logger from '@adonisjs/core/services/logger'
@@ -404,7 +404,13 @@ export class MapService implements IMapService {
       fileName += '.pmtiles'
     }
 
-    const fullPath = join(this.baseDirPath, 'pmtiles', fileName)
+    const basePath = resolve(join(this.baseDirPath, 'pmtiles'))
+    const fullPath = resolve(join(basePath, fileName))
+
+    // Prevent path traversal — resolved path must stay within the storage directory
+    if (!fullPath.startsWith(basePath + sep)) {
+      throw new Error('Invalid filename')
+    }
 
     const exists = await getFileStatsIfExists(fullPath)
     if (!exists) {

admin/app/services/zim_service.ts

@@ -16,7 +16,7 @@ import {
   listDirectoryContents,
   ZIM_STORAGE_PATH,
 } from '../utils/fs.js'
-import { join } from 'path'
+import { join, resolve, sep } from 'path'
 import { WikipediaOption, WikipediaState } from '../../types/downloads.js'
 import vine from '@vinejs/vine'
 import { wikipediaOptionsFileSchema } from '#validators/curated_collections'
@@ -332,7 +332,13 @@ export class ZimService {
       fileName += '.zim'
     }
 
-    const fullPath = join(process.cwd(), ZIM_STORAGE_PATH, fileName)
+    const basePath = resolve(join(process.cwd(), ZIM_STORAGE_PATH))
+    const fullPath = resolve(join(basePath, fileName))
+
+    // Prevent path traversal — resolved path must stay within the storage directory
+    if (!fullPath.startsWith(basePath + sep)) {
+      throw new Error('Invalid filename')
+    }
 
     const exists = await getFileStatsIfExists(fullPath)
     if (!exists) {

admin/app/validators/common.ts

@@ -1,12 +1,39 @@
 import vine from '@vinejs/vine'
 
+/**
+ * Checks whether a URL points to a private/internal network address.
+ * Used to prevent SSRF — the server should not fetch from localhost,
+ * private RFC1918 ranges, link-local, or cloud metadata endpoints.
+ *
+ * Throws an error if the URL is internal/private.
+ */
+export function assertNotPrivateUrl(urlString: string): void {
+  const parsed = new URL(urlString)
+  const hostname = parsed.hostname.toLowerCase()
+
+  const privatePatterns = [
+    /^localhost$/,
+    /^127\.\d+\.\d+\.\d+$/,
+    /^10\.\d+\.\d+\.\d+$/,
+    /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/,
+    /^192\.168\.\d+\.\d+$/,
+    /^169\.254\.\d+\.\d+$/, // Link-local / cloud metadata
+    /^0\.0\.0\.0$/,
+    /^\[::1\]$/,
+    /^\[?fe80:/i,
+    /^\[?fd[0-9a-f]{2}:/i, // Unique local IPv6
+  ]
+
+  if (privatePatterns.some((re) => re.test(hostname))) {
+    throw new Error(`Download URL must not point to a private/internal address: ${hostname}`)
+  }
+}
+
 export const remoteDownloadValidator = vine.compile(
   vine.object({
     url: vine
       .string()
-      .url({
-        require_tld: false, // Allow local URLs
-      })
+      .url()
       .trim(),
   })
 )
@@ -15,9 +42,7 @@ export const remoteDownloadWithMetadataValidator = vine.compile(
   vine.object({
     url: vine
       .string()
-      .url({
-        require_tld: false, // Allow local URLs
-      })
+      .url()
       .trim(),
     metadata: vine
       .object({
@@ -34,9 +59,7 @@ export const remoteDownloadValidatorOptional = vine.compile(
   vine.object({
     url: vine
       .string()
-      .url({
-        require_tld: false, // Allow local URLs
-      })
+      .url()
       .trim()
       .optional(),
   })