nuxt-local-assets

Nuxt module for serving user-uploaded files from local storage with authentication, authorization, and audit logging.

Features

• Serve files from external directories (outside the build)
• Path traversal protection
• Authentication integration
• Custom authorization hooks
• Audit logging for compliance
• HTTP caching (ETag, Last-Modified, Cache-Control)
• Range request support (resume downloads, video streaming)
• Response compression (gzip/brotli)
• MIME type validation
• URL redirects (301/302)
• V8-optimized for performance

Installation

pnpm add nuxt-local-assets

Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-local-assets'],

  localAssets: {
    dirs: [{
      name: 'uploads',
      path: '/data/uploads',      // Production path
      route: '/files',            // URL prefix
      devPath: './dev-uploads',   // Development path
    }],

    auth: {
      required: true,
      authorize: '~/server/utils/authorize',
    },

    audit: {
      enabled: true,
      handler: '~/server/utils/audit',
    },

    security: {
      allowedMimeTypes: ['image/*', 'application/pdf'],
      blockedExtensions: ['.exe', '.sh', '.bat'],
      maxFileSize: '100mb',
    },

    cache: {
      etag: true,
      lastModified: true,
      rules: [
        { match: /\.(jpg|png|gif)$/i, maxAge: 86400 },
        { match: /\.pdf$/i, maxAge: 3600 },
      ],
    },

    compression: {
      enabled: true,
      types: ['text/*', 'application/json', 'application/xml', 'application/javascript'],
      threshold: '1kb',
    },

    rangeRequest: {
      enabled: true,
      maxChunkSize: '10mb',
    },

    redirect: {
      handler: '~/server/utils/redirect',
    },
  },
})

Configuration Reference

dirs

Directory configurations for serving files.

| Option | Type | Required | Description | |--------|------|----------|-------------| | name | string | Yes | Unique identifier for this directory | | path | string | Yes | Absolute path to files in production | | route | string | Yes | URL prefix (e.g., /files serves at /files/*) | | devPath | string | No | Relative path used in development mode |

auth

Authentication and authorization settings.

| Option | Type | Default | Description | |--------|------|---------|-------------| | required | boolean | false | Require authenticated user for all requests | | authorize | string | - | Path to custom authorization function (e.g., ~/server/utils/authorize) |

audit

Audit logging configuration.

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | false | Enable audit logging | | handler | string | - | Path to audit handler function (e.g., ~/server/utils/audit) |

security

Security restrictions.

| Option | Type | Default | Description | |--------|------|---------|-------------| | allowedMimeTypes | string[] | [] | Whitelist of allowed MIME types. Supports wildcards: image/*, text/*. Empty = allow all | | blockedExtensions | string[] | ['.exe', '.sh', '.bat', '.cmd', '.ps1'] | File extensions to block | | maxFileSize | string | '100mb' | Maximum file size. Supports: b, kb, mb, gb, tb |

cache

HTTP caching configuration.

| Option | Type | Default | Description | |--------|------|---------|-------------| | etag | boolean | true | Generate ETag header for cache validation | | lastModified | boolean | true | Send Last-Modified header | | rules | CacheRule[] | [] | Pattern-based Cache-Control rules |

CacheRule format:

{
  match: RegExp,        // Pattern to match file paths
  maxAge: number,       // Cache-Control max-age in seconds
  mustRevalidate?: boolean,
  immutable?: boolean,
}

compression

Response compression settings.

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable gzip/brotli compression | | types | string[] | ['text/*', 'application/json', 'application/xml', 'application/javascript'] | MIME types to compress | | threshold | string | '1kb' | Minimum file size to compress |

rangeRequest

HTTP Range request support (for video streaming, resume downloads).

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable Range request support (206 Partial Content) | | maxChunkSize | string | - | Maximum bytes per range request (e.g., 10mb) |

redirect

URL redirect configuration.

| Option | Type | Default | Description | |--------|------|---------|-------------| | handler | string | - | Path to redirect function (e.g., ~/server/utils/redirect) |

Authorization Function

// server/utils/authorize.ts
import type { FileAccessContext } from 'nuxt-local-assets'

export default function(ctx: FileAccessContext): boolean {
  const { user, filePath } = ctx

  if (!user) return false
  if (user.role === 'admin') return true
  if (filePath.startsWith(`users/${user.id}/`)) return true

  return false
}

Audit Handler

// server/utils/audit.ts
import type { AuditLogEntry } from 'nuxt-local-assets'

export default async function(entry: AuditLogEntry): Promise<void> {
  await db.audit_log.create({ data: entry })
}

Redirect Function

Handle URL redirects for moved files, short URLs, or version-based routing:

// server/utils/redirect.ts
import type { RedirectContext, RedirectResult } from 'nuxt-local-assets'

export default async function(ctx: RedirectContext): Promise<string | RedirectResult | null> {
  const { filePath, user } = ctx

  // Redirect old file to new location (301 permanent)
  if (filePath === 'old-document.pdf') {
    return {
      url: '/files/documents/new-document.pdf',
      statusCode: 301,
    }
  }

  // Short URL redirect (302 temporary)
  if (filePath.startsWith('s/')) {
    const short_code = filePath.slice(2)
    const resolved = await lookupShortCode(short_code)
    if (resolved) return resolved
  }

  // Return null to continue normal file serving
  return null
}

RedirectContext

interface RedirectContext {
  filePath: string           // Relative path within directory
  urlPath: string            // Full URL path
  user: unknown | null       // Authenticated user
  event: H3Event
  dirConfig: LocalAssetsDirConfig
}

RedirectResult

interface RedirectResult {
  url: string                // URL to redirect to
  statusCode?: 301 | 302     // HTTP status (default: 302)
}

Types

FileAccessContext

interface FileAccessContext {
  user: unknown | null
  filePath: string        // Relative path within directory
  fullPath: string        // Absolute filesystem path
  fileMeta?: {
    size: number
    mtime: Date
    mimeType: string
  }
  event: H3Event
  dirConfig: LocalAssetsDirConfig
}

AuditLogEntry

interface AuditLogEntry {
  timestamp: Date
  idUser: string | null
  action: 'access' | 'denied' | 'not_found' | 'error'
  filePath: string
  ipAddress: string
  userAgent: string
  reason?: string
  dirName: string
}

Security

The module implements multiple layers of security:

• Path sanitization: Blocks directory traversal (../), null bytes, absolute paths
• MIME type validation: Whitelist allowed content types
• Extension blocking: Block dangerous file extensions
• File size limits: Prevent serving oversized files
• Path escape detection: Ensure resolved paths stay within base directory

Development

# Install dependencies
pnpm install

# Prepare for development
pnpm dev:prepare

# Run playground
pnpm dev

# Run tests
pnpm test

# Run single test file
npx vitest run test/path.test.ts

Manual Testing

After starting the playground with pnpm dev, test features using curl:

# Basic file access
curl -i http://localhost:3000/files/test.txt

# Test gzip compression
curl -i -H "Accept-Encoding: gzip" http://localhost:3000/files/test.txt

# Test brotli compression
curl -i -H "Accept-Encoding: br" http://localhost:3000/files/test.txt

# Test Range request (partial content)
curl -i -H "Range: bytes=0-100" http://localhost:3000/files/test.txt

# Test 304 Not Modified (use ETag from previous response)
curl -i -H 'If-None-Match: "etag-value"' http://localhost:3000/files/test.txt

# Test blocked extension
curl -i http://localhost:3000/files/test.exe

# Test directory traversal protection
curl -i http://localhost:3000/files/../../../etc/passwd

Add test files to playground/uploads/ directory for testing different MIME types.

Roadmap

Future enhancements under consideration:

• [ ] HEAD request support
• [ ] Directory listing (optional feature)
• [ ] Content-Disposition header for downloads
• [ ] Rate limiting support
• [ ] Signed URL for temporary access
• [ ] npm publish / CI/CD

License

MIT