@kadi.build/file-sharing 1.0.0

package/src/S3Server.js

@@ -0,0 +1,984 @@
+/**
+ * S3Server - Local S3-compatible API server for @kadi.build/file-sharing
+ *
+ * Provides a LOCAL S3-compatible server that emulates AWS S3 API endpoints.
+ * Files are stored locally on disk, NOT on AWS. This allows using AWS SDK tools
+ * (like @aws-sdk/client-s3) to interact with your local file system.
+ *
+ * Supported operations:
+ * - ListBuckets
+ * - ListObjects / ListObjectsV2
+ * - GetObject (with range requests)
+ * - PutObject
+ * - DeleteObject
+ * - HeadObject
+ * - HeadBucket
+ * - CreateBucket
+ * - DeleteBucket
+ * - CreateMultipartUpload / UploadPart / CompleteMultipartUpload
+ *
+ * Migrated from src/s3Server.js
+ */
+
+import { EventEmitter } from 'events';
+import http from 'http';
+import path from 'path';
+import fs from 'fs/promises';
+import { createReadStream, createWriteStream } from 'fs';
+import crypto from 'crypto';
+import { Builder } from 'xml2js';
+
+export class S3Server extends EventEmitter {
+  constructor(config = {}) {
+    super();
+
+    this.config = {
+      port: 9000,
+      host: '0.0.0.0',
+      rootDir: process.cwd(),
+      accessKeyId: 'minioadmin',
+      secretAccessKey: 'minioadmin',
+      bucketName: 'local',
+      region: 'us-east-1',
+      maxFileSize: null,
+      ...config
+    };
+
+    this.server = null;
+    this.isRunning = false;
+    this.multipartUploads = new Map();
+    this.requestCount = 0;
+  }
+
+  /**
+   * Start the S3 server
+   * @returns {{ port: number, endpoint: string }}
+   */
+  async start() {
+    if (this.isRunning) {
+      return {
+        port: this.config.port,
+        endpoint: `http://${this.config.host}:${this.config.port}`
+      };
+    }
+
+    // Ensure bucket directory exists
+    const bucketDir = path.join(this.config.rootDir, this.config.bucketName);
+    await fs.mkdir(bucketDir, { recursive: true });
+
+    return new Promise((resolve, reject) => {
+      this.server = http.createServer(async (req, res) => {
+        this.requestCount++;
+        try {
+          // Set CORS headers
+          res.setHeader('Access-Control-Allow-Origin', '*');
+          res.setHeader('Access-Control-Allow-Methods', 'GET, PUT, POST, DELETE, HEAD, OPTIONS');
+          res.setHeader('Access-Control-Allow-Headers', '*');
+          res.setHeader('Access-Control-Expose-Headers', 'ETag, x-amz-request-id, x-amz-id-2, Content-Length, Content-Type');
+
+          if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+          }
+
+          // S3 authentication check
+          if (!this._checkS3Auth(req)) {
+            this._sendError(res, 'AccessDenied',
+              'Access Denied. Provide valid AWS credentials via Authorization header or query parameters.', 403);
+            return;
+          }
+
+          await this._handleRequest(req, res);
+        } catch (error) {
+          this.emit('error', error);
+          if (!res.headersSent) {
+            this._sendError(res, 'InternalError', error.message, 500);
+          }
+        }
+      });
+
+      this.server.listen(this.config.port, this.config.host, () => {
+        const addr = this.server.address();
+        this.config.port = addr.port;
+        this.isRunning = true;
+
+        const info = {
+          port: addr.port,
+          endpoint: `http://${this.config.host}:${addr.port}`
+        };
+
+        this.emit('started', info);
+        resolve(info);
+      });
+
+      this.server.on('error', (err) => {
+        this.emit('error', err);
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Stop the S3 server
+   */
+  async stop() {
+    if (!this.isRunning) return;
+
+    return new Promise((resolve) => {
+      this.server.close(() => {
+        this.isRunning = false;
+        this.server = null;
+        this.multipartUploads.clear();
+        this.emit('stopped');
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Get bucket configuration
+   * @returns {{ name: string, rootDir: string }}
+   */
+  getBucket() {
+    return { name: this.config.bucketName, rootDir: this.config.rootDir };
+  }
+
+  /**
+   * List objects in bucket (programmatic access)
+   * @param {string} prefix - Optional prefix filter
+   * @returns {Promise<Array>}
+   */
+  async listObjects(prefix = '') {
+    const bucketDir = path.join(this.config.rootDir, this.config.bucketName);
+    const searchDir = prefix ? path.join(bucketDir, prefix) : bucketDir;
+
+    try {
+      const entries = await this._walkDirectory(searchDir, bucketDir);
+      return entries;
+    } catch {
+      return [];
+    }
+  }
+
+  // ============================================================================
+  // REQUEST ROUTING
+  // ============================================================================
+
+  /**
+   * Main request router
+   * @private
+   */
+  async _handleRequest(req, res) {
+    const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+    const pathParts = url.pathname.split('/').filter(Boolean);
+
+    // Add S3 response headers
+    res.setHeader('x-amz-request-id', crypto.randomBytes(8).toString('hex').toUpperCase());
+    res.setHeader('x-amz-id-2', crypto.randomBytes(16).toString('base64'));
+    res.setHeader('Server', 'KadiS3');
+
+    // Root: List buckets
+    if (pathParts.length === 0) {
+      if (req.method === 'GET') {
+        return this._listBuckets(req, res);
+      }
+    }
+
+    const bucket = pathParts[0];
+    const key = pathParts.slice(1).join('/');
+
+    // Bucket-level operations (no key)
+    if (!key && !url.search.includes('prefix')) {
+      switch (req.method) {
+        case 'GET':
+          return this._listObjects(req, res, bucket, url.searchParams);
+        case 'HEAD':
+          return this._headBucket(req, res, bucket);
+        case 'PUT':
+          return this._createBucket(req, res, bucket);
+        case 'DELETE':
+          return this._deleteBucket(req, res, bucket);
+      }
+    }
+
+    // Object-level operations
+    if (key || url.searchParams.has('prefix')) {
+      switch (req.method) {
+        case 'GET':
+          // Could be list with prefix if no explicit key
+          if (!key) {
+            return this._listObjects(req, res, bucket, url.searchParams);
+          }
+          return this._getObject(req, res, bucket, key);
+        case 'HEAD':
+          if (!key) {
+            return this._headBucket(req, res, bucket);
+          }
+          return this._headObject(req, res, bucket, key);
+        case 'PUT': {
+          // Check if this is a multipart upload part
+          const uploadId = url.searchParams.get('uploadId');
+          const partNumber = url.searchParams.get('partNumber');
+          if (uploadId && partNumber) {
+            return this._uploadPart(req, res, bucket, key, uploadId, parseInt(partNumber, 10));
+          }
+          return this._putObject(req, res, bucket, key);
+        }
+        case 'DELETE':
+          return this._deleteObject(req, res, bucket, key);
+        case 'POST': {
+          // Multipart upload operations
+          if (url.searchParams.has('uploads')) {
+            return this._createMultipartUpload(req, res, bucket, key);
+          }
+          const uploadIdPost = url.searchParams.get('uploadId');
+          if (uploadIdPost) {
+            return this._completeMultipartUpload(req, res, bucket, key, uploadIdPost);
+          }
+          // Fallback: treat POST like PUT
+          return this._putObject(req, res, bucket, key);
+        }
+      }
+    }
+
+    this._sendError(res, 'MethodNotAllowed', `Method ${req.method} not allowed`, 405);
+  }
+
+  // ============================================================================
+  // S3 API HANDLERS
+  // ============================================================================
+
+  /**
+   * S3 API: ListBuckets
+   * @private
+   */
+  async _listBuckets(req, res) {
+    const buckets = [{
+      Name: this.config.bucketName,
+      CreationDate: new Date().toISOString()
+    }];
+
+    // Also check for additional bucket directories
+    try {
+      const entries = await fs.readdir(this.config.rootDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && entry.name !== this.config.bucketName) {
+          buckets.push({
+            Name: entry.name,
+            CreationDate: new Date().toISOString()
+          });
+        }
+      }
+    } catch {
+      // Ignore readdir errors
+    }
+
+    const xml = this._buildXml('ListAllMyBucketsResult', {
+      $: { xmlns: 'http://s3.amazonaws.com/doc/2006-03-01/' },
+      Owner: { ID: 'owner', DisplayName: 'owner' },
+      Buckets: { Bucket: buckets }
+    });
+
+    this._sendXml(res, xml);
+  }
+
+  /**
+   * S3 API: ListObjects / ListObjectsV2
+   * @private
+   */
+  async _listObjects(req, res, bucket, params) {
+    const prefix = params.get('prefix') || '';
+    const delimiter = params.get('delimiter') || '';
+    const maxKeys = parseInt(params.get('max-keys') || '1000', 10);
+    const listType = params.get('list-type');
+
+    const bucketDir = path.join(this.config.rootDir, bucket);
+
+    try {
+      await fs.access(bucketDir);
+    } catch {
+      // Bucket doesn't exist - return empty result
+      const emptyResponse = this._formatListObjectsV2Response(
+        { objects: [], prefixes: [] }, bucket, prefix, delimiter, maxKeys
+      );
+      return this._sendXml(res, emptyResponse);
+    }
+
+    try {
+      const items = await this._listDirectoryForS3(bucketDir, prefix, delimiter, maxKeys);
+
+      const response = listType === '2'
+        ? this._formatListObjectsV2Response(items, bucket, prefix, delimiter, maxKeys)
+        : this._formatListObjectsResponse(items, bucket, prefix, delimiter, maxKeys);
+
+      this._sendXml(res, response);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        this._sendXml(res, this._formatListObjectsV2Response(
+          { objects: [], prefixes: [] }, bucket, prefix, delimiter, maxKeys
+        ));
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * S3 API: GetObject
+   * @private
+   */
+  async _getObject(req, res, bucket, key) {
+    const filePath = path.join(this.config.rootDir, bucket, key);
+
+    // Security: prevent directory traversal
+    const resolvedRoot = path.resolve(this.config.rootDir, bucket);
+    const resolvedPath = path.resolve(filePath);
+    if (!resolvedPath.startsWith(resolvedRoot)) {
+      return this._sendError(res, 'AccessDenied', 'Access Denied', 403);
+    }
+
+    try {
+      const stats = await fs.stat(filePath);
+
+      if (stats.isDirectory()) {
+        return this._sendError(res, 'NoSuchKey', 'The specified key does not exist', 404);
+      }
+
+      const etag = `"${crypto.createHash('md5').update(`${stats.size}-${stats.mtime.getTime()}`).digest('hex')}"`;
+
+      // Handle range requests
+      const range = req.headers.range;
+      if (range) {
+        const parts = range.replace(/bytes=/, '').split('-');
+        const start = parseInt(parts[0], 10);
+        const end = parts[1] ? parseInt(parts[1], 10) : stats.size - 1;
+        const chunkSize = end - start + 1;
+
+        res.writeHead(206, {
+          'Content-Range': `bytes ${start}-${end}/${stats.size}`,
+          'Accept-Ranges': 'bytes',
+          'Content-Length': chunkSize,
+          'Content-Type': 'application/octet-stream',
+          'Last-Modified': stats.mtime.toUTCString(),
+          'ETag': etag
+        });
+
+        createReadStream(filePath, { start, end }).pipe(res);
+      } else {
+        res.writeHead(200, {
+          'Content-Length': stats.size,
+          'Content-Type': 'application/octet-stream',
+          'Accept-Ranges': 'bytes',
+          'Last-Modified': stats.mtime.toUTCString(),
+          'ETag': etag
+        });
+
+        createReadStream(filePath).pipe(res);
+      }
+
+      this.emit('object:get', { bucket, key, size: stats.size });
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        this._sendError(res, 'NoSuchKey', 'The specified key does not exist', 404);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * S3 API: PutObject
+   * @private
+   */
+  async _putObject(req, res, bucket, key) {
+    const filePath = path.join(this.config.rootDir, bucket, key);
+    const dirPath = path.dirname(filePath);
+
+    // Security: prevent directory traversal
+    const resolvedRoot = path.resolve(this.config.rootDir, bucket);
+    const resolvedPath = path.resolve(filePath);
+    if (!resolvedPath.startsWith(resolvedRoot)) {
+      return this._sendError(res, 'AccessDenied', 'Access Denied', 403);
+    }
+
+    // Ensure bucket and parent directories exist
+    await fs.mkdir(dirPath, { recursive: true });
+
+    return new Promise((resolve, reject) => {
+      const writeStream = createWriteStream(filePath);
+      let size = 0;
+
+      req.on('data', (chunk) => {
+        size += chunk.length;
+        writeStream.write(chunk);
+      });
+
+      req.on('end', async () => {
+        writeStream.end();
+
+        // Wait for write stream to finish
+        writeStream.on('finish', async () => {
+          try {
+            const stats = await fs.stat(filePath);
+            const etag = `"${crypto.createHash('md5').update(`${stats.size}-${stats.mtime.getTime()}`).digest('hex')}"`;
+
+            res.writeHead(200, {
+              'ETag': etag,
+              'Content-Length': 0
+            });
+            res.end();
+
+            this.emit('object:put', { bucket, key, size });
+            resolve();
+          } catch (err) {
+            reject(err);
+          }
+        });
+      });
+
+      req.on('error', (err) => {
+        writeStream.destroy();
+        reject(err);
+      });
+
+      writeStream.on('error', (err) => {
+        if (!res.headersSent) {
+          this._sendError(res, 'InternalError', err.message, 500);
+        }
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * S3 API: DeleteObject
+   * @private
+   */
+  async _deleteObject(req, res, bucket, key) {
+    const filePath = path.join(this.config.rootDir, bucket, key);
+
+    try {
+      await fs.unlink(filePath);
+      this.emit('object:delete', { bucket, key });
+    } catch (error) {
+      // S3 returns success even if object doesn't exist
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+
+    res.writeHead(204);
+    res.end();
+  }
+
+  /**
+   * S3 API: HeadObject
+   * @private
+   */
+  async _headObject(req, res, bucket, key) {
+    const filePath = path.join(this.config.rootDir, bucket, key);
+
+    try {
+      const stats = await fs.stat(filePath);
+
+      if (stats.isDirectory()) {
+        return this._sendError(res, 'NoSuchKey', 'The specified key does not exist', 404);
+      }
+
+      const etag = `"${crypto.createHash('md5').update(`${stats.size}-${stats.mtime.getTime()}`).digest('hex')}"`;
+
+      res.writeHead(200, {
+        'Content-Length': stats.size,
+        'Content-Type': 'application/octet-stream',
+        'Last-Modified': stats.mtime.toUTCString(),
+        'ETag': etag
+      });
+      res.end();
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        this._sendError(res, 'NoSuchKey', 'The specified key does not exist', 404);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * S3 API: HeadBucket
+   * @private
+   */
+  async _headBucket(req, res, bucket) {
+    const bucketDir = path.join(this.config.rootDir, bucket);
+
+    try {
+      await fs.access(bucketDir);
+      res.writeHead(200, {
+        'x-amz-bucket-region': this.config.region
+      });
+      res.end();
+    } catch {
+      this._sendError(res, 'NoSuchBucket', 'The specified bucket does not exist', 404);
+    }
+  }
+
+  /**
+   * S3 API: CreateBucket
+   * @private
+   */
+  async _createBucket(req, res, bucket) {
+    const bucketDir = path.join(this.config.rootDir, bucket);
+
+    try {
+      await fs.mkdir(bucketDir, { recursive: true });
+      res.writeHead(200, {
+        'Location': `/${bucket}`
+      });
+      res.end();
+    } catch (error) {
+      this._sendError(res, 'InternalError', error.message, 500);
+    }
+  }
+
+  /**
+   * S3 API: DeleteBucket
+   * @private
+   */
+  async _deleteBucket(req, res, bucket) {
+    const bucketDir = path.join(this.config.rootDir, bucket);
+
+    try {
+      const entries = await fs.readdir(bucketDir);
+      if (entries.length > 0) {
+        return this._sendError(res, 'BucketNotEmpty', 'The bucket you tried to delete is not empty', 409);
+      }
+      await fs.rmdir(bucketDir);
+      res.writeHead(204);
+      res.end();
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        this._sendError(res, 'NoSuchBucket', 'The specified bucket does not exist', 404);
+      } else {
+        this._sendError(res, 'InternalError', error.message, 500);
+      }
+    }
+  }
+
+  // ============================================================================
+  // MULTIPART UPLOAD HANDLERS
+  // ============================================================================
+
+  /**
+   * S3 API: CreateMultipartUpload
+   * @private
+   */
+  async _createMultipartUpload(req, res, bucket, key) {
+    const uploadId = crypto.randomBytes(16).toString('hex');
+
+    this.multipartUploads.set(uploadId, {
+      bucket,
+      key,
+      parts: new Map(),
+      createdAt: new Date()
+    });
+
+    const xml = this._buildXml('InitiateMultipartUploadResult', {
+      $: { xmlns: 'http://s3.amazonaws.com/doc/2006-03-01/' },
+      Bucket: bucket,
+      Key: key,
+      UploadId: uploadId
+    });
+
+    this._sendXml(res, xml);
+  }
+
+  /**
+   * S3 API: UploadPart
+   * @private
+   */
+  async _uploadPart(req, res, bucket, key, uploadId, partNumber) {
+    const upload = this.multipartUploads.get(uploadId);
+    if (!upload) {
+      return this._sendError(res, 'NoSuchUpload', 'The specified multipart upload does not exist', 404);
+    }
+
+    const chunks = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+    const body = Buffer.concat(chunks);
+
+    const etag = `"${crypto.createHash('md5').update(body).digest('hex')}"`;
+    upload.parts.set(partNumber, { body, etag });
+
+    res.writeHead(200, {
+      'ETag': etag
+    });
+    res.end();
+  }
+
+  /**
+   * S3 API: CompleteMultipartUpload
+   * @private
+   */
+  async _completeMultipartUpload(req, res, bucket, key, uploadId) {
+    const upload = this.multipartUploads.get(uploadId);
+    if (!upload) {
+      return this._sendError(res, 'NoSuchUpload', 'The specified multipart upload does not exist', 404);
+    }
+
+    // Collect request body (XML with part list)
+    const chunks = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+
+    // Assemble parts in order
+    const sortedParts = Array.from(upload.parts.entries())
+      .sort(([a], [b]) => a - b);
+
+    const bodyParts = sortedParts.map(([, part]) => part.body);
+    const fullBody = Buffer.concat(bodyParts);
+
+    // Write the assembled file
+    const filePath = path.join(this.config.rootDir, bucket, key);
+    const dirPath = path.dirname(filePath);
+    await fs.mkdir(dirPath, { recursive: true });
+    await fs.writeFile(filePath, fullBody);
+
+    const etag = `"${crypto.createHash('md5').update(fullBody).digest('hex')}"`;
+
+    // Cleanup
+    this.multipartUploads.delete(uploadId);
+
+    const xml = this._buildXml('CompleteMultipartUploadResult', {
+      $: { xmlns: 'http://s3.amazonaws.com/doc/2006-03-01/' },
+      Location: `http://${this.config.host}:${this.config.port}/${bucket}/${key}`,
+      Bucket: bucket,
+      Key: key,
+      ETag: etag
+    });
+
+    this._sendXml(res, xml);
+    this.emit('object:put', { bucket, key, size: fullBody.length });
+  }
+
+  // ============================================================================
+  // DIRECTORY LISTING HELPERS
+  // ============================================================================
+
+  /**
+   * List directory contents for S3-style listing
+   * @private
+   */
+  async _listDirectoryForS3(bucketDir, prefix, delimiter, maxKeys) {
+    const objects = [];
+    const prefixes = new Set();
+
+    const searchDir = prefix ? path.join(bucketDir, prefix) : bucketDir;
+
+    try {
+      // If prefix points to a specific directory, list its contents
+      const stats = await fs.stat(searchDir);
+      if (stats.isDirectory()) {
+        const entries = await fs.readdir(searchDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+          if (objects.length >= maxKeys) break;
+
+          const entryKey = prefix
+            ? `${prefix}${prefix.endsWith('/') ? '' : '/'}${entry.name}`
+            : entry.name;
+
+          if (entry.isDirectory()) {
+            if (delimiter) {
+              prefixes.add(entryKey.endsWith('/') ? entryKey : `${entryKey}/`);
+            } else {
+              // Recurse into subdirectory
+              const subDir = path.join(searchDir, entry.name);
+              const subEntries = await this._walkDirectory(subDir, bucketDir);
+              objects.push(...subEntries.slice(0, maxKeys - objects.length));
+            }
+          } else {
+            const filePath = path.join(searchDir, entry.name);
+            const fileStat = await fs.stat(filePath);
+            objects.push({
+              Key: entryKey,
+              LastModified: fileStat.mtime.toISOString(),
+              ETag: `"${crypto.createHash('md5').update(`${fileStat.size}-${fileStat.mtime.getTime()}`).digest('hex')}"`,
+              Size: fileStat.size,
+              StorageClass: 'STANDARD'
+            });
+          }
+        }
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        // Try prefix as a file prefix in parent directory
+        const parentDir = path.dirname(searchDir);
+        const filePrefix = path.basename(searchDir);
+
+        try {
+          const entries = await fs.readdir(parentDir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (objects.length >= maxKeys) break;
+            if (entry.name.startsWith(filePrefix)) {
+              const entryPath = path.join(parentDir, entry.name);
+              const entryStat = await fs.stat(entryPath);
+              const relKey = path.relative(bucketDir, entryPath);
+
+              if (entry.isFile()) {
+                objects.push({
+                  Key: relKey,
+                  LastModified: entryStat.mtime.toISOString(),
+                  ETag: `"${crypto.createHash('md5').update(`${entryStat.size}-${entryStat.mtime.getTime()}`).digest('hex')}"`,
+                  Size: entryStat.size,
+                  StorageClass: 'STANDARD'
+                });
+              } else if (delimiter) {
+                prefixes.add(relKey.endsWith('/') ? relKey : `${relKey}/`);
+              }
+            }
+          }
+        } catch {
+          // Parent dir doesn't exist either
+        }
+      }
+    }
+
+    return { objects, prefixes: Array.from(prefixes) };
+  }
+
+  /**
+   * Walk directory recursively, collecting file entries
+   * @private
+   */
+  async _walkDirectory(dir, baseDir) {
+    const results = [];
+
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isFile()) {
+          const stats = await fs.stat(fullPath);
+          const relKey = path.relative(baseDir, fullPath);
+          results.push({
+            Key: relKey,
+            LastModified: stats.mtime.toISOString(),
+            ETag: `"${crypto.createHash('md5').update(`${stats.size}-${stats.mtime.getTime()}`).digest('hex')}"`,
+            Size: stats.size,
+            StorageClass: 'STANDARD'
+          });
+        } else if (entry.isDirectory()) {
+          const subResults = await this._walkDirectory(fullPath, baseDir);
+          results.push(...subResults);
+        }
+      }
+    } catch {
+      // Ignore errors during walk
+    }
+
+    return results;
+  }
+
+  // ============================================================================
+  // XML RESPONSE FORMATTING
+  // ============================================================================
+
+  /**
+   * Format ListObjects (v1) response
+   * @private
+   */
+  _formatListObjectsResponse(items, bucket, prefix, delimiter, maxKeys) {
+    const response = {
+      $: { xmlns: 'http://s3.amazonaws.com/doc/2006-03-01/' },
+      Name: bucket,
+      Prefix: prefix || '',
+      MaxKeys: maxKeys,
+      IsTruncated: false
+    };
+
+    if (delimiter) {
+      response.Delimiter = delimiter;
+    }
+
+    if (items.objects.length > 0) {
+      response.Contents = items.objects;
+    }
+
+    if (items.prefixes.length > 0) {
+      response.CommonPrefixes = items.prefixes.map(p => ({ Prefix: p }));
+    }
+
+    return this._buildXml('ListBucketResult', response);
+  }
+
+  /**
+   * Format ListObjectsV2 response
+   * @private
+   */
+  _formatListObjectsV2Response(items, bucket, prefix, delimiter, maxKeys) {
+    const response = {
+      $: { xmlns: 'http://s3.amazonaws.com/doc/2006-03-01/' },
+      Name: bucket,
+      Prefix: prefix || '',
+      MaxKeys: maxKeys,
+      KeyCount: items.objects.length,
+      IsTruncated: false
+    };
+
+    if (delimiter) {
+      response.Delimiter = delimiter;
+    }
+
+    if (items.objects.length > 0) {
+      response.Contents = items.objects;
+    }
+
+    if (items.prefixes.length > 0) {
+      response.CommonPrefixes = items.prefixes.map(p => ({ Prefix: p }));
+    }
+
+    return this._buildXml('ListBucketResult', response);
+  }
+
+  // ============================================================================
+  // XML HELPERS
+  // ============================================================================
+
+  /**
+   * Build XML response
+   * @private
+   */
+  _buildXml(rootName, content) {
+    const builder = new Builder({
+      rootName,
+      headless: false,
+      xmldec: { version: '1.0', encoding: 'UTF-8' }
+    });
+    return builder.buildObject(content);
+  }
+
+  /**
+   * Send XML response
+   * @private
+   */
+  _sendXml(res, xml) {
+    res.writeHead(200, {
+      'Content-Type': 'application/xml',
+      'Content-Length': Buffer.byteLength(xml)
+    });
+    res.end(xml);
+  }
+
+  /**
+   * Send S3-formatted error response
+   * @private
+   */
+  _sendError(res, code, message, statusCode) {
+    const xml = this._buildXml('Error', {
+      Code: code,
+      Message: message,
+      RequestId: crypto.randomBytes(8).toString('hex'),
+      HostId: crypto.randomBytes(16).toString('base64')
+    });
+
+    res.writeHead(statusCode, {
+      'Content-Type': 'application/xml',
+      'Content-Length': Buffer.byteLength(xml)
+    });
+    res.end(xml);
+  }
+
+  // ============================================================================
+  // AUTHENTICATION
+  // ============================================================================
+
+  /**
+   * Validate S3 request authentication.
+   *
+   * When `config.enforceAuth` is `true` (or when non-default credentials are
+   * configured), every request must carry valid credentials via one of:
+   *
+   *   1. `Authorization` header containing the access key id
+   *      - AWS Signature V4:  `AWS4-HMAC-SHA256 Credential=<accessKeyId>/…`
+   *      - AWS Signature V2:  `AWS <accessKeyId>:…`
+   *      - Simple Bearer:     `Bearer <accessKeyId>` (non-standard convenience)
+   *
+   *   2. Query-string pre-signed URL parameters
+   *      - V4: `?X-Amz-Credential=<accessKeyId>/…`
+   *      - V2: `?AWSAccessKeyId=<accessKeyId>`
+   *
+   * Note: This is intentionally *identity-based* (checks access key) rather
+   * than a full HMAC signature check. A full SigV4 implementation would
+   * require reconstructing the canonical request exactly as the SDK built it,
+   * which is fragile and unnecessary for a local dev server. The goal is to
+   * prevent accidental unauthenticated access when credentials are configured,
+   * not to replicate AWS IAM.
+   *
+   * @private
+   * @param {import('http').IncomingMessage} req
+   * @returns {boolean} `true` if the request is authorized
+   */
+  _checkS3Auth(req) {
+    const { accessKeyId, secretAccessKey, enforceAuth } = this.config;
+
+    // If using default credentials and enforceAuth is not explicitly true,
+    // skip auth checks (backward compatible — local dev convenience).
+    const isDefault = accessKeyId === 'minioadmin' && secretAccessKey === 'minioadmin';
+    if (isDefault && !enforceAuth) {
+      return true;
+    }
+
+    // --- Check Authorization header ---
+    const authHeader = req.headers.authorization || '';
+
+    // AWS Signature V4: "AWS4-HMAC-SHA256 Credential=<accessKeyId>/date/region/s3/aws4_request, …"
+    if (authHeader.startsWith('AWS4-HMAC-SHA256')) {
+      const credMatch = authHeader.match(/Credential=([^/,\s]+)/);
+      if (credMatch && credMatch[1] === accessKeyId) {
+        return true;
+      }
+    }
+
+    // AWS Signature V2: "AWS <accessKeyId>:<signature>"
+    if (authHeader.startsWith('AWS ')) {
+      const parts = authHeader.slice(4).split(':');
+      if (parts[0] === accessKeyId) {
+        return true;
+      }
+    }
+
+    // Simple Bearer (non-standard convenience for agents/scripts)
+    if (authHeader.startsWith('Bearer ')) {
+      if (authHeader.slice(7) === accessKeyId) {
+        return true;
+      }
+    }
+
+    // --- Check query parameters (pre-signed URL) ---
+    try {
+      const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+
+      // V4 pre-signed: ?X-Amz-Credential=<accessKeyId>/…
+      const amzCred = url.searchParams.get('X-Amz-Credential');
+      if (amzCred && amzCred.startsWith(accessKeyId + '/')) {
+        return true;
+      }
+
+      // V2 pre-signed: ?AWSAccessKeyId=<accessKeyId>
+      if (url.searchParams.get('AWSAccessKeyId') === accessKeyId) {
+        return true;
+      }
+    } catch {
+      // Malformed URL — deny
+    }
+
+    return false;
+  }
+}
+
+export default S3Server;