@kadi.build/file-sharing 1.0.0 → 1.1.1

package/README.md

@@ -7,8 +7,10 @@ Integrates [`@kadi.build/file-manager`](https://www.npmjs.com/package/@kadi.buil
 
 - **HTTP File Server** — Static file serving with directory listing, range requests, CORS, and multi-scheme authentication
 - **Local S3-Compatible API** — Emulates AWS S3 endpoints locally so you can use `@aws-sdk/client-s3` against your local filesystem
+- **Extensible HTTP Pipeline** — Register custom middleware and routes (e.g. Docker Registry v2 endpoints) alongside built-in file serving
 - **Tunnel Integration** — Expose your local server publicly via KĀDI (default), ngrok, serveo, localtunnel, or pinggy
-- **Authentication** — Basic Auth, Bearer Token, and API Key (header / query param) for HTTP; AWS SigV4 / SigV2 / Bearer for S3
+- **Authentication** — Basic Auth, Bearer Token, and API Key (header / query param) for HTTP; AWS SigV4 / SigV2 / Bearer / Basic for S3
+- **Temporary Credentials** — Generate time-limited S3 credentials for secure sharing
 - **Secrets Management** — Automatic `.env` loading (walks up parent directories for monorepo support) + environment variables + explicit config
 - **Download Monitoring** — Track active downloads, progress, speed, and completion statistics
 - **Graceful Shutdown** — Priority-ordered shutdown with timeout and force-kill
@@ -195,6 +197,7 @@ When custom S3 credentials are set (anything other than the default `minioadmin`
 | **AWS SigV4** | Standard `Authorization: AWS4-HMAC-SHA256 Credential=<accessKeyId>/...` |
 | **AWS SigV2** | Legacy `Authorization: AWS <accessKeyId>:signature` |
 | **Bearer** | Convenience `Authorization: Bearer <accessKeyId>` |
+| **Basic** | Docker-style `Authorization: Basic base64(accessKeyId:secretAccessKey)` |
 | **Pre-signed URL** | `?X-Amz-Credential=<accessKeyId>/...` query param |
 
 > With default credentials (`minioadmin`/`minioadmin`), auth is skipped for backward compatibility unless you set `enforceAuth: true` in the S3 config.
@@ -309,6 +312,12 @@ const server = new FileSharingServer({
 | `s3:get` | `{bucket, key}` | S3 GetObject |
 | `s3:put` | `{bucket, key}` | S3 PutObject |
 | `s3:delete` | `{bucket, key}` | S3 DeleteObject |
+| `bucket:removed` | `{bucket}` | Bucket programmatically removed |
+| `credentials:generated` | `{accessKey, expiresAt}` | Temporary credentials created |
+| `middleware:added` | `{name, priority}` | HTTP middleware registered |
+| `middleware:removed` | `{name}` | HTTP middleware removed |
+| `route:added` | `{method, path, priority}` | Custom HTTP route registered |
+| `route:removed` | `{method, path}` | Custom HTTP route removed |
 | `tunnel:created` | `TunnelInfo` | Tunnel established |
 | `tunnel:closed` | — | Tunnel shut down |
 | `tunnel:error` | `Error` | Tunnel failed (non-fatal) |
@@ -317,7 +326,7 @@ const server = new FileSharingServer({
 
 ### HttpServerProvider
 
-Low-level HTTP file server with authentication.
+Low-level HTTP file server with authentication and extensibility.
 
 ```javascript
 import { HttpServerProvider } from '@kadi.build/file-sharing/http';
@@ -333,6 +342,67 @@ const httpServer = new HttpServerProvider({
 await httpServer.start();
 ```
 
+#### Middleware (Extensibility)
+
+Register middleware that runs **before** built-in auth and static file handling. Higher priority runs first.
+
+```javascript
+// Add authentication middleware (priority 10 = runs before default handlers)
+httpServer.addMiddleware('dockerAuth', (req, res, next) => {
+  if (req.url.startsWith('/v2')) {
+    const auth = req.headers.authorization;
+    if (!auth || !isValidToken(auth)) {
+      res.writeHead(401);
+      res.end(JSON.stringify({ errors: [{ code: 'UNAUTHORIZED' }] }));
+      return;
+    }
+    req.user = { token: auth };
+  }
+  next();
+}, { priority: 10 });
+
+// List registered middleware
+httpServer.getMiddleware(); // [{ name: 'dockerAuth', priority: 10 }]
+
+// Remove middleware
+httpServer.removeMiddleware('dockerAuth');
+```
+
+#### Custom Routes (Extensibility)
+
+Register custom route handlers with Express-style `:param` path patterns. Custom routes match **before** built-in static file serving.
+
+```javascript
+// Docker Registry v2 ping
+httpServer.addCustomRoute('GET', '/v2/', (req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end('{}');
+});
+
+// Route with path parameters — req.params is populated automatically
+httpServer.addCustomRoute('GET', '/v2/:name/manifests/:reference', (req, res) => {
+  console.log(req.params); // { name: 'myapp', reference: 'latest' }
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(getManifest(req.params.name, req.params.reference)));
+});
+
+// HEAD method support
+httpServer.addCustomRoute('HEAD', '/v2/:name/blobs/:digest', (req, res) => {
+  res.writeHead(200, { 'Docker-Content-Digest': req.params.digest });
+  res.end();
+});
+
+// List / remove routes
+httpServer.getCustomRoutes();                   // [{ method, path, priority }]
+httpServer.removeCustomRoute('GET', '/v2/');     // true if found
+```
+
+#### Request Pipeline Order
+
+```
+Request → CORS → Middleware Chain → Custom Routes → Built-in Auth → Static Files
+```
+
 ### S3Server
 
 Local S3-compatible API server. Files are stored **on disk**, not on AWS.
@@ -350,7 +420,8 @@ const s3 = new S3Server({
   enforceAuth: true                // validate even with default creds
 });
 
-await s3.start();
+const info = await s3.start();
+console.log(info.serverId);         // 'kadi-s3-9000'
 ```
 
 **Supported S3 Operations:**
@@ -363,6 +434,48 @@ await s3.start();
 - `HeadObject`
 - `CreateMultipartUpload`, `UploadPart`, `CompleteMultipartUpload`
 
+#### Programmatic Authentication Validation
+
+Validate incoming requests against configured credentials. Returns a structured result — useful for layering custom auth (e.g. Docker Registry) on top of S3.
+
+```javascript
+const result = s3.validateAuthentication(req);
+// Success: { success: true, user: { accessKey: 'AKIA...' } }
+// Failure: { success: false, error: 'Invalid credentials' }
+```
+
+Supports AWS SigV4, SigV2, Bearer, Basic Auth (Docker clients), and pre-signed URL query params.
+
+#### Temporary Credentials
+
+Generate time-limited credentials for secure sharing:
+
+```javascript
+const creds = s3.generateTemporaryCredentials({ ttl: 3600 }); // 1 hour
+console.log(creds.accessKey);    // 'AKIA...' (random)
+console.log(creds.secretKey);    // random hex string
+console.log(creds.expiresAt);    // '2026-02-16T...' (ISO string)
+console.log(creds.expiry);       // Date object (backward compat)
+
+// Temp credentials are automatically validated by _checkS3Auth and validateAuthentication
+```
+
+#### Programmatic Bucket Removal
+
+Force-delete a bucket directory and all its contents (for cleanup):
+
+```javascript
+await s3.removeBucket('container-id-123');
+// Emits 'bucket:removed' event. Idempotent (no error if bucket doesn't exist).
+```
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `serverId` | `string` | Stable server identifier (e.g. `kadi-s3-9000`) |
+| `isRunning` | `boolean` | Whether the server is running |
+
 ### createQuickShare
 
 One-liner to share a directory with optional tunnel and auth.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadi.build/file-sharing",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "File sharing service with tunneling and local S3-compatible interface",
   "type": "module",
   "main": "src/index.js",
@@ -29,7 +29,8 @@
     "test:integration": "node tests/test-file-sharing.js",
     "test:monitor": "node tests/test-download-monitor.js",
     "test:shutdown": "node tests/test-shutdown-manager.js",
-    "test:streaming": "node tests/test-streaming.js"
+    "test:streaming": "node tests/test-streaming.js",
+    "test:extensibility": "node tests/test-extensibility.js"
   },
   "keywords": [
     "file-sharing",

package/src/FileSharingServer.js

@@ -123,6 +123,16 @@ function _filterDefined(obj) {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
 }
 
+/**
+ * Convert a bind address (like `0.0.0.0` or `::`) into a client-usable address.
+ * Bind-all addresses are not connectable by clients; replace them with `127.0.0.1`.
+ * @param {string} host
+ * @returns {string}
+ */
+function _clientHost(host) {
+  return (host === '0.0.0.0' || host === '::' || host === '[::]') ? '127.0.0.1' : host;
+}
+
 export class FileSharingServer extends EventEmitter {
   constructor(config = {}) {
     super();
@@ -169,6 +179,24 @@ export class FileSharingServer extends EventEmitter {
       };
     }
 
+    // ----------------------------------------------------------------
+    // Port collision detection: when S3 is enabled and both ports match,
+    // auto-assign s3Port to 0 (OS picks a free port) to avoid EADDRINUSE.
+    // ----------------------------------------------------------------
+    if (this.config.enableS3 && this.config.port === this.config.s3Port && this.config.port !== 0) {
+      const userExplicitlySetS3Port = config.s3Port !== undefined;
+      if (userExplicitlySetS3Port) {
+        throw new Error(
+          `Port collision: port and s3Port are both set to ${this.config.port}. ` +
+          `The HTTP server and S3 server cannot bind the same port. ` +
+          `Please specify a different s3Port (or use s3Port: 0 for auto-assign).`
+        );
+      }
+      // User only set `port` (not s3Port) and it happens to match the s3Port default.
+      // Auto-resolve by letting the OS pick a free port for S3.
+      this.config.s3Port = 0;
+    }
+
     // ----------------------------------------------------------------
     // Load secrets from env vars / .env (constructor config takes priority)
     // ----------------------------------------------------------------
@@ -412,12 +440,13 @@ export class FileSharingServer extends EventEmitter {
    * @returns {object} Server information
    */
   getInfo() {
+    const host = _clientHost(this.config.host);
     return {
       isRunning: this.isRunning,
-      localUrl: `http://${this.config.host}:${this.config.port}`,
+      localUrl: `http://${host}:${this.config.port}`,
       publicUrl: this.tunnel?.publicUrl || null,
       s3Endpoint: this.s3Server?.isRunning
-        ? `http://${this.config.host}:${this.config.s3Port}`
+        ? `http://${host}:${this.s3Server.config.port}`
         : null,
       staticDir: this.config.staticDir,
       stats: this.downloadMonitor.getStats(),
@@ -488,7 +517,7 @@ export class FileSharingServer extends EventEmitter {
   /** @type {string|null} */
   get s3Endpoint() {
     return this.s3Server?.isRunning
-      ? `http://${this.config.host}:${this.config.s3Port}`
+      ? `http://${_clientHost(this.config.host)}:${this.s3Server.config.port}`
       : null;
   }
 

package/src/HttpServerProvider.js

@@ -45,6 +45,10 @@ export class HttpServerProvider extends EventEmitter {
     this.startTime = null;
     this.requestCount = 0;
     this.errorCount = 0;
+
+    // Extensibility: middleware chain and custom routes (sorted by priority desc)
+    this._middlewares = [];
+    this._customRoutes = [];
   }
 
   /**
@@ -84,10 +88,14 @@ export class HttpServerProvider extends EventEmitter {
         this.startTime = new Date();
 
         const protocol = this.config.ssl ? 'https' : 'http';
+        // Use a client-connectable host in the URL (0.0.0.0 is a bind address, not routable)
+        const clientHost = (this.config.host === '0.0.0.0' || this.config.host === '::' || this.config.host === '[::]')
+          ? '127.0.0.1'
+          : this.config.host;
         const info = {
           port: addr.port,
           host: this.config.host,
-          url: `${protocol}://${this.config.host}:${addr.port}`
+          url: `${protocol}://${clientHost}:${addr.port}`
         };
 
         this.emit('started', info);
@@ -143,6 +151,243 @@ export class HttpServerProvider extends EventEmitter {
     }
   }
 
+  // ============================================================================
+  // EXTENSIBILITY — MIDDLEWARE & CUSTOM ROUTES
+  // ============================================================================
+
+  /**
+   * Register a named middleware function into the request pipeline.
+   * Middleware runs BEFORE built-in auth and static-file handling.
+   *
+   * @param {string}   name     - Unique middleware identifier (e.g. 'dockerAuth')
+   * @param {Function} handler  - (req, res, next) => void
+   * @param {Object}   [opts]
+   * @param {number}   [opts.priority=0] - Higher runs first
+   */
+  addMiddleware(name, handler, opts = {}) {
+    if (typeof name !== 'string' || !name) {
+      throw new Error('Middleware name must be a non-empty string');
+    }
+    if (typeof handler !== 'function') {
+      throw new Error('Middleware handler must be a function');
+    }
+
+    // Remove existing middleware with the same name (upsert semantics)
+    this._middlewares = this._middlewares.filter(m => m.name !== name);
+
+    const priority = opts.priority ?? 0;
+    this._middlewares.push({ name, handler, priority });
+
+    // Sort descending by priority (higher priority runs first)
+    this._middlewares.sort((a, b) => b.priority - a.priority);
+
+    this.emit('middleware:added', { name, priority });
+  }
+
+  /**
+   * Remove a named middleware.
+   *
+   * @param {string} name - Middleware identifier to remove
+   * @returns {boolean} true if middleware was found and removed
+   */
+  removeMiddleware(name) {
+    const before = this._middlewares.length;
+    this._middlewares = this._middlewares.filter(m => m.name !== name);
+    const removed = this._middlewares.length < before;
+    if (removed) {
+      this.emit('middleware:removed', { name });
+    }
+    return removed;
+  }
+
+  /**
+   * Get the list of registered middleware names (in execution order).
+   * @returns {string[]}
+   */
+  getMiddleware() {
+    return this._middlewares.map(m => ({ name: m.name, priority: m.priority }));
+  }
+
+  /**
+   * Register a custom route handler.
+   * Custom routes are matched BEFORE built-in static-file/upload handling.
+   *
+   * @param {string}   method   - HTTP method ('GET', 'HEAD', 'POST', etc.)
+   * @param {string}   urlPath  - URL path or pattern. Supports Express-style :param segments.
+   * @param {Function} handler  - (req, res) => void.  req.params populated from path pattern.
+   * @param {Object}   [opts]
+   * @param {number}   [opts.priority=0] - Higher = matched first (before S3/static routes)
+   */
+  addCustomRoute(method, urlPath, handler, opts = {}) {
+    if (typeof method !== 'string' || !method) {
+      throw new Error('Route method must be a non-empty string');
+    }
+    if (typeof urlPath !== 'string') {
+      throw new Error('Route path must be a string');
+    }
+    if (typeof handler !== 'function') {
+      throw new Error('Route handler must be a function');
+    }
+
+    const normalizedMethod = method.toUpperCase();
+    const priority = opts.priority ?? 0;
+    const compiled = this._compilePath(urlPath);
+
+    // Remove existing route with same method + path (upsert)
+    this._customRoutes = this._customRoutes.filter(
+      r => !(r.method === normalizedMethod && r.path === urlPath)
+    );
+
+    this._customRoutes.push({
+      method: normalizedMethod,
+      path: urlPath,
+      handler,
+      priority,
+      ...compiled
+    });
+
+    // Sort descending by priority
+    this._customRoutes.sort((a, b) => b.priority - a.priority);
+
+    this.emit('route:added', { method: normalizedMethod, path: urlPath, priority });
+  }
+
+  /**
+   * Remove a custom route.
+   *
+   * @param {string} method - HTTP method
+   * @param {string} urlPath - URL path pattern
+   * @returns {boolean} true if route was found and removed
+   */
+  removeCustomRoute(method, urlPath) {
+    const normalizedMethod = method.toUpperCase();
+    const before = this._customRoutes.length;
+    this._customRoutes = this._customRoutes.filter(
+      r => !(r.method === normalizedMethod && r.path === urlPath)
+    );
+    const removed = this._customRoutes.length < before;
+    if (removed) {
+      this.emit('route:removed', { method: normalizedMethod, path: urlPath });
+    }
+    return removed;
+  }
+
+  /**
+   * Get the list of registered custom routes.
+   * @returns {Array<{ method: string, path: string, priority: number }>}
+   */
+  getCustomRoutes() {
+    return this._customRoutes.map(r => ({ method: r.method, path: r.path, priority: r.priority }));
+  }
+
+  /**
+   * Compile an Express-style path pattern into a regex and param name list.
+   *
+   * Supports:
+   * - Literal paths: `/v2/`
+   * - Named params:  `/v2/:name/manifests/:reference`
+   *
+   * @private
+   * @param {string} pattern - URL path pattern
+   * @returns {{ regex: RegExp, paramNames: string[] }}
+   */
+  _compilePath(pattern) {
+    const paramNames = [];
+    // Escape special regex chars except : (used for params) and /
+    const regexStr = pattern
+      .replace(/([.+?^${}()|[\]\\])/g, '\\$1')
+      .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, paramName) => {
+        paramNames.push(paramName);
+        return '([^/]+)';
+      });
+
+    // Exact match — anchor both ends
+    const regex = new RegExp(`^${regexStr}$`);
+    return { regex, paramNames };
+  }
+
+  /**
+   * Run the middleware chain. Returns true if a middleware ended the response.
+   * @private
+   * @param {import('http').IncomingMessage} req
+   * @param {import('http').ServerResponse} res
+   * @returns {Promise<boolean>} true if response was ended by middleware
+   */
+  async _runMiddlewareChain(req, res) {
+    const middlewares = this._middlewares;
+    if (middlewares.length === 0) return false;
+
+    let index = 0;
+    let responseEnded = false;
+
+    const runNext = () => {
+      return new Promise((resolve, reject) => {
+        if (responseEnded || res.writableEnded) {
+          responseEnded = true;
+          return resolve();
+        }
+
+        if (index >= middlewares.length) {
+          return resolve(); // All middleware passed through
+        }
+
+        const mw = middlewares[index++];
+        try {
+          const result = mw.handler(req, res, (err) => {
+            if (err) {
+              return reject(err);
+            }
+            if (res.writableEnded) {
+              responseEnded = true;
+              return resolve();
+            }
+            runNext().then(resolve).catch(reject);
+          });
+
+          // Support async middleware that returns a promise
+          if (result && typeof result.then === 'function') {
+            result.catch(reject);
+          }
+        } catch (err) {
+          reject(err);
+        }
+      });
+    };
+
+    await runNext();
+    return responseEnded || res.writableEnded;
+  }
+
+  /**
+   * Try to match an incoming request against registered custom routes.
+   * @private
+   * @param {string} method - HTTP method
+   * @param {string} pathname - Decoded URL pathname
+   * @returns {{ route: object, params: object } | null}
+   */
+  _matchCustomRoute(method, pathname) {
+    const upperMethod = method.toUpperCase();
+
+    for (const route of this._customRoutes) {
+      if (route.method !== upperMethod) continue;
+
+      const match = route.regex.exec(pathname);
+      if (match) {
+        const params = {};
+        route.paramNames.forEach((name, i) => {
+          params[name] = decodeURIComponent(match[i + 1]);
+        });
+        return { route, params };
+      }
+    }
+
+    return null;
+  }
+
+  // ============================================================================
+  // REQUEST HANDLING
+  // ============================================================================
+
   /**
    * Create the main request handler
    * @private
@@ -163,7 +408,29 @@ export class HttpServerProvider extends EventEmitter {
           }
         }
 
-        // Authentication
+        // ── Middleware chain (Gap 1) ──────────────────────────────────
+        // Run registered middleware before auth and routing.
+        // If any middleware ends the response, stop processing.
+        if (this._middlewares.length > 0) {
+          const handled = await this._runMiddlewareChain(req, res);
+          if (handled) return;
+        }
+
+        // ── Custom routes (Gap 2) ────────────────────────────────────
+        // Check registered custom routes before built-in handling.
+        const urlObj = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+        const urlPath = decodeURIComponent(urlObj.pathname);
+
+        if (this._customRoutes.length > 0) {
+          const routeMatch = this._matchCustomRoute(req.method, urlPath);
+          if (routeMatch) {
+            req.params = routeMatch.params;
+            await routeMatch.route.handler(req, res);
+            return;
+          }
+        }
+
+        // ── Built-in authentication ──────────────────────────────────
         if (this.config.auth) {
           if (!this._checkAuth(req)) {
             // Set appropriate WWW-Authenticate based on configured scheme
@@ -179,9 +446,7 @@ export class HttpServerProvider extends EventEmitter {
           }
         }
 
-        // Route request
-        const urlObj = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
-        const urlPath = decodeURIComponent(urlObj.pathname);
+        // ── Static file handling ─────────────────────────────────────
         const filePath = path.join(this.config.staticDir, urlPath);
 
         // Security: prevent directory traversal

package/src/S3Server.js

@@ -48,6 +48,20 @@ export class S3Server extends EventEmitter {
     this.isRunning = false;
     this.multipartUploads = new Map();
     this.requestCount = 0;
+
+    // Temporary credentials store (Gap 7) — Map<accessKey, { secretKey, expiresAt }>
+    this._temporaryCredentials = new Map();
+
+    // Stable server identifier (Gap 5)
+    this._serverId = `kadi-s3-${this.config.port}`;
+  }
+
+  /**
+   * Stable server identifier.
+   * @type {string}
+   */
+  get serverId() {
+    return this._serverId;
   }
 
   /**
@@ -56,9 +70,12 @@ export class S3Server extends EventEmitter {
    */
   async start() {
     if (this.isRunning) {
+      const clientHost = (this.config.host === '0.0.0.0' || this.config.host === '::' || this.config.host === '[::]')
+        ? '127.0.0.1'
+        : this.config.host;
       return {
         port: this.config.port,
-        endpoint: `http://${this.config.host}:${this.config.port}`
+        endpoint: `http://${clientHost}:${this.config.port}`
       };
     }
 
@@ -102,10 +119,17 @@ export class S3Server extends EventEmitter {
         const addr = this.server.address();
         this.config.port = addr.port;
         this.isRunning = true;
+        this._serverId = `kadi-s3-${addr.port}`;
 
+        // Use a client-connectable host in the endpoint (0.0.0.0 is a bind address, not routable)
+        const clientHost = (this.config.host === '0.0.0.0' || this.config.host === '::' || this.config.host === '[::]')
+          ? '127.0.0.1'
+          : this.config.host;
         const info = {
           port: addr.port,
-          endpoint: `http://${this.config.host}:${addr.port}`
+          host: this.config.host,
+          endpoint: `http://${clientHost}:${addr.port}`,
+          serverId: this._serverId
         };
 
         this.emit('started', info);
@@ -893,10 +917,170 @@ export class S3Server extends EventEmitter {
     res.end(xml);
   }
 
+  // ============================================================================
+  // PUBLIC EXTENSIBILITY APIs
+  // ============================================================================
+
+  /**
+   * Validate an incoming request against the server's configured credentials.
+   * Returns a structured result object (unlike the private _checkS3Auth which
+   * returns a plain boolean).
+   *
+   * This is the public API that consumers like container-registry-ability use
+   * to validate Docker Registry API requests carry valid S3 credentials.
+   *
+   * @param {import('http').IncomingMessage} req
+   * @returns {{ success: boolean, user?: { accessKey: string }, error?: string }}
+   */
+  validateAuthentication(req) {
+    // Attempt to extract the access key from the request for the user object
+    const accessKey = this._extractAccessKey(req);
+    const isValid = this._checkS3Auth(req);
+
+    if (isValid) {
+      return {
+        success: true,
+        user: { accessKey: accessKey || this.config.accessKeyId }
+      };
+    }
+
+    return {
+      success: false,
+      error: 'Invalid credentials'
+    };
+  }
+
+  /**
+   * Programmatically remove a bucket (delete its directory from the S3 root).
+   * Unlike the S3 API DeleteBucket handler, this force-deletes even non-empty
+   * directories — intended for cleanup when containers are removed.
+   *
+   * @param {string} bucketName - The bucket/directory name to remove
+   * @returns {Promise<void>}
+   */
+  async removeBucket(bucketName) {
+    if (!bucketName || typeof bucketName !== 'string') {
+      throw new Error('bucketName must be a non-empty string');
+    }
+
+    // Security: prevent directory traversal
+    if (bucketName.includes('..') || bucketName.includes('/') || bucketName.includes('\\')) {
+      throw new Error('Invalid bucket name — must not contain path separators or ".."');
+    }
+
+    const bucketDir = path.join(this.config.rootDir, bucketName);
+
+    // Ensure the resolved path is within rootDir
+    const resolvedRoot = path.resolve(this.config.rootDir);
+    const resolvedBucket = path.resolve(bucketDir);
+    if (!resolvedBucket.startsWith(resolvedRoot)) {
+      throw new Error('Invalid bucket name — path traversal detected');
+    }
+
+    try {
+      await fs.rm(bucketDir, { recursive: true, force: true });
+      this.emit('bucket:removed', { bucket: bucketName });
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+      // Bucket doesn't exist — treat as success (idempotent)
+    }
+  }
+
+  /**
+   * Generate temporary S3 credentials with an expiry.
+   *
+   * Returns both `expiresAt` (ISO string) and `expiry` (Date object) for
+   * backward compatibility with consumers expecting the old property name.
+   *
+   * @param {Object} [opts]
+   * @param {number} [opts.ttl=3600] - Time-to-live in seconds (default: 1 hour)
+   * @returns {{ accessKey: string, secretKey: string, expiresAt: string, expiry: Date }}
+   */
+  generateTemporaryCredentials(opts = {}) {
+    const ttl = opts.ttl ?? 3600;
+    const accessKey = `AKIA${crypto.randomBytes(8).toString('hex').toUpperCase()}`;
+    const secretKey = crypto.randomBytes(20).toString('hex');
+    const expiryDate = new Date(Date.now() + ttl * 1000);
+
+    // Store for validation
+    this._temporaryCredentials.set(accessKey, {
+      secretKey,
+      expiresAt: expiryDate.getTime()
+    });
+
+    // Schedule cleanup
+    setTimeout(() => {
+      this._temporaryCredentials.delete(accessKey);
+    }, ttl * 1000).unref();
+
+    this.emit('credentials:generated', { accessKey, expiresAt: expiryDate.toISOString() });
+
+    return {
+      accessKey,
+      secretKey,
+      expiresAt: expiryDate.toISOString(),
+      expiry: expiryDate // backward compat alias
+    };
+  }
+
   // ============================================================================
   // AUTHENTICATION
   // ============================================================================
 
+  /**
+   * Extract the access key from an incoming request, if present.
+   * Used by validateAuthentication() to populate the user object.
+   *
+   * @private
+   * @param {import('http').IncomingMessage} req
+   * @returns {string|null}
+   */
+  _extractAccessKey(req) {
+    const authHeader = req.headers.authorization || '';
+
+    // AWS Signature V4
+    if (authHeader.startsWith('AWS4-HMAC-SHA256')) {
+      const credMatch = authHeader.match(/Credential=([^/,\s]+)/);
+      if (credMatch) return credMatch[1];
+    }
+
+    // AWS Signature V2
+    if (authHeader.startsWith('AWS ')) {
+      return authHeader.slice(4).split(':')[0] || null;
+    }
+
+    // Bearer
+    if (authHeader.startsWith('Bearer ')) {
+      return authHeader.slice(7) || null;
+    }
+
+    // Basic auth (Docker clients)
+    if (authHeader.startsWith('Basic ')) {
+      try {
+        const decoded = Buffer.from(authHeader.slice(6), 'base64').toString();
+        const [user] = decoded.split(':');
+        return user || null;
+      } catch {
+        return null;
+      }
+    }
+
+    // Query params
+    try {
+      const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+      const amzCred = url.searchParams.get('X-Amz-Credential');
+      if (amzCred) return amzCred.split('/')[0];
+      const awsKey = url.searchParams.get('AWSAccessKeyId');
+      if (awsKey) return awsKey;
+    } catch {
+      // ignore
+    }
+
+    return null;
+  }
+
   /**
    * Validate S3 request authentication.
    *
@@ -907,17 +1091,13 @@ export class S3Server extends EventEmitter {
    *      - AWS Signature V4:  `AWS4-HMAC-SHA256 Credential=<accessKeyId>/…`
    *      - AWS Signature V2:  `AWS <accessKeyId>:…`
    *      - Simple Bearer:     `Bearer <accessKeyId>` (non-standard convenience)
+   *      - Basic auth:        `Basic base64(accessKey:secretKey)` (Docker clients)
    *
    *   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.
+   * Also checks temporary credentials generated via generateTemporaryCredentials().
    *
    * @private
    * @param {import('http').IncomingMessage} req
@@ -939,23 +1119,41 @@ export class S3Server extends EventEmitter {
     // 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;
+      if (credMatch) {
+        if (credMatch[1] === accessKeyId) return true;
+        // Check temporary credentials
+        if (this._checkTempCredentials(credMatch[1])) return true;
       }
     }
 
     // AWS Signature V2: "AWS <accessKeyId>:<signature>"
     if (authHeader.startsWith('AWS ')) {
       const parts = authHeader.slice(4).split(':');
-      if (parts[0] === accessKeyId) {
-        return true;
-      }
+      if (parts[0] === accessKeyId) return true;
+      if (this._checkTempCredentials(parts[0])) return true;
     }
 
     // Simple Bearer (non-standard convenience for agents/scripts)
     if (authHeader.startsWith('Bearer ')) {
-      if (authHeader.slice(7) === accessKeyId) {
-        return true;
+      const token = authHeader.slice(7);
+      if (token === accessKeyId) return true;
+      if (this._checkTempCredentials(token)) return true;
+    }
+
+    // Basic auth (Docker clients send Basic base64(accessKey:secretKey))
+    if (authHeader.startsWith('Basic ')) {
+      try {
+        const decoded = Buffer.from(authHeader.slice(6), 'base64').toString();
+        const [user, pass] = decoded.split(':');
+        // Check against primary credentials
+        if (user === accessKeyId && pass === secretAccessKey) return true;
+        // Check against temporary credentials
+        const tempCred = this._temporaryCredentials.get(user);
+        if (tempCred && tempCred.expiresAt > Date.now() && pass === tempCred.secretKey) {
+          return true;
+        }
+      } catch {
+        // Malformed Basic auth — fall through
       }
     }
 
@@ -965,13 +1163,17 @@ export class S3Server extends EventEmitter {
 
       // V4 pre-signed: ?X-Amz-Credential=<accessKeyId>/…
       const amzCred = url.searchParams.get('X-Amz-Credential');
-      if (amzCred && amzCred.startsWith(accessKeyId + '/')) {
-        return true;
+      if (amzCred) {
+        const credKey = amzCred.split('/')[0];
+        if (credKey === accessKeyId) return true;
+        if (this._checkTempCredentials(credKey)) return true;
       }
 
       // V2 pre-signed: ?AWSAccessKeyId=<accessKeyId>
-      if (url.searchParams.get('AWSAccessKeyId') === accessKeyId) {
-        return true;
+      const awsKey = url.searchParams.get('AWSAccessKeyId');
+      if (awsKey) {
+        if (awsKey === accessKeyId) return true;
+        if (this._checkTempCredentials(awsKey)) return true;
       }
     } catch {
       // Malformed URL — deny
@@ -979,6 +1181,26 @@ export class S3Server extends EventEmitter {
 
     return false;
   }
+
+  /**
+   * Check if an access key matches a valid, non-expired temporary credential.
+   *
+   * @private
+   * @param {string} accessKey
+   * @returns {boolean}
+   */
+  _checkTempCredentials(accessKey) {
+    const cred = this._temporaryCredentials.get(accessKey);
+    if (!cred) return false;
+
+    // Expired?
+    if (cred.expiresAt <= Date.now()) {
+      this._temporaryCredentials.delete(accessKey);
+      return false;
+    }
+
+    return true;
+  }
 }
 
 export default S3Server;