v3.1.0

changelog.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 2025-11-23 - 3.1.0 - feat(logging)
+Add structured Logger and integrate into Smarts3Server; pass full config to server
+
+- Introduce a new Logger class (ts/classes/logger.ts) providing leveled logging (error, warn, info, debug), text/json formats and an enable flag.
+- Integrate Logger into Smarts3Server: use structured logging for server lifecycle events, HTTP request/response logging and S3 errors instead of direct console usage.
+- Smarts3 now passes the full merged configuration into Smarts3Server (config.logging can control logging behavior).
+- Server start/stop messages and internal request/error logs are emitted via the Logger and respect the configured logging level/format and silent option.
+
+## 2025-11-23 - 3.0.4 - fix(smarts3)
+Use filesystem store for bucket creation and remove smartbucket runtime dependency
+
+- Switched createBucket to call the internal FilesystemStore.createBucket instead of using @push.rocks/smartbucket
+- Made Smarts3Server.store public so Smarts3 can access the filesystem store directly
+- Removed runtime import/export of @push.rocks/smartbucket from plugins and moved @push.rocks/smartbucket to devDependencies in package.json
+- Updated createBucket to return a simple { name } object after creating the bucket via the filesystem store
+
+## 2025-11-23 - 3.0.3 - fix(filesystem)
+Migrate filesystem implementation to @push.rocks/smartfs and add Web Streams handling
+
+- Replace dependency @push.rocks/smartfile with @push.rocks/smartfs and update README references
+- plugins: instantiate SmartFs with SmartFsProviderNode and export smartfs (remove direct fs export)
+- Refactor FilesystemStore to use smartfs directory/file APIs for initialize, reset, list, read, write, copy and delete
+- Implement Web Stream ↔ Node.js stream conversion for uploads/downloads (Readable.fromWeb and writer.write with Uint8Array)
+- Persist and read metadata (.metadata.json) and cached MD5 (.md5) via smartfs APIs
+- Update readme.hints and documentation to note successful migration and next steps
+
+## 2025-11-21 - 3.0.2 - fix(smarts3)
+Prepare patch release 3.0.2 — no code changes detected
+
+- No source changes in the diff
+- Bump patch version from 3.0.1 to 3.0.2 for maintenance/release bookkeeping
+
 ## 2025-11-21 - 3.0.1 - fix(readme)
 Add Issue Reporting and Security section to README
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smarts3",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "private": false,
   "description": "A Node.js TypeScript package to create a local S3 endpoint for simulating AWS S3 operations using mapped local directories for development and testing purposes.",
   "main": "dist_ts/index.js",
@@ -19,6 +19,7 @@
     "@git.zone/tsbundle": "^2.5.2",
     "@git.zone/tsrun": "^2.0.0",
     "@git.zone/tstest": "^3.1.0",
+    "@push.rocks/smartbucket": "^4.3.0",
     "@types/node": "^22.9.0"
   },
   "browserslist": [
@@ -37,8 +38,7 @@
     "readme.md"
   ],
   "dependencies": {
-    "@push.rocks/smartbucket": "^4.3.0",
-    "@push.rocks/smartfile": "^11.2.7",
+    "@push.rocks/smartfs": "^1.1.0",
     "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartxml": "^2.0.0",
     "@tsclass/tsclass": "^9.3.0"

pnpm-lock.yaml

@@ -8,12 +8,9 @@ importers:
 
   .:
     dependencies:
-      '@push.rocks/smartbucket':
-        specifier: ^4.3.0
-        version: 4.3.0
-      '@push.rocks/smartfile':
-        specifier: ^11.2.7
-        version: 11.2.7
+      '@push.rocks/smartfs':
+        specifier: ^1.1.0
+        version: 1.1.0
       '@push.rocks/smartpath':
         specifier: ^6.0.0
         version: 6.0.0
@@ -39,6 +36,9 @@ importers:
       '@git.zone/tstest':
         specifier: ^3.1.0
         version: 3.1.0(socks@2.8.7)(typescript@5.9.3)
+      '@push.rocks/smartbucket':
+        specifier: ^4.3.0
+        version: 4.3.0
       '@types/node':
         specifier: ^22.9.0
         version: 22.19.1
@@ -644,6 +644,9 @@ packages:
   '@push.rocks/smartfile@11.2.7':
     resolution: {integrity: sha512-8Yp7/sAgPpWJBHohV92ogHWKzRomI5MEbSG6b5W2n18tqwfAmjMed0rQvsvGrSBlnEWCKgoOrYIIZbLO61+J0Q==}
 
+  '@push.rocks/smartfs@1.1.0':
+    resolution: {integrity: sha512-fg8JIjFUPPX5laRoBpTaGwhMfZ3Y8mFT4fUaW54Y4J/BfOBa/y0+rIFgvgvqcOZgkQlyZU+FIfL8Z6zezqxyTg==}
+
   '@push.rocks/smartguard@3.1.0':
     resolution: {integrity: sha512-J23q84f1O+TwFGmd4lrO9XLHUh2DaLXo9PN/9VmTWYzTkQDv5JehmifXVI0esophXcCIfbdIu6hbt7/aHlDF4A==}
 
@@ -4920,6 +4923,10 @@ snapshots:
       glob: 11.1.0
       js-yaml: 4.1.1
 
+  '@push.rocks/smartfs@1.1.0':
+    dependencies:
+      '@push.rocks/smartpath': 6.0.0
+
   '@push.rocks/smartguard@3.1.0':
     dependencies:
       '@push.rocks/smartpromise': 4.2.3

production-readiness.md

@@ -0,0 +1,438 @@
+# Production-Readiness Plan for smarts3
+
+**Goal:** Make smarts3 production-ready as a MinIO alternative for use cases where:
+- Running MinIO is out of scope
+- You have a program written for S3 and want to use the local filesystem
+- You need a lightweight, zero-dependency S3-compatible server
+
+---
+
+## 🔍 Current State Analysis
+
+### ✅ What's Working
+
+- **Native S3 server** with zero framework dependencies
+- **Core S3 operations:** PUT, GET, HEAD, DELETE (objects & buckets)
+- **List buckets and objects** (V1 and V2 API)
+- **Object copy** with metadata handling
+- **Range requests** for partial downloads
+- **MD5 checksums** and ETag support
+- **Custom metadata** (x-amz-meta-*)
+- **Filesystem-backed storage** with Windows compatibility
+- **S3-compatible XML error responses**
+- **Middleware system** and routing
+- **AWS SDK v3 compatibility** (tested)
+
+### ❌ Production Gaps Identified
+
+---
+
+## 🎯 Critical Features (Required for Production)
+
+### 1. Multipart Upload Support 🚀 **HIGHEST PRIORITY**
+
+**Why:** Essential for uploading files >5MB efficiently. Without this, smarts3 can't handle real-world production workloads.
+
+**Implementation Required:**
+- `POST /:bucket/:key?uploads` - CreateMultipartUpload
+- `PUT /:bucket/:key?partNumber=X&uploadId=Y` - UploadPart
+- `POST /:bucket/:key?uploadId=X` - CompleteMultipartUpload
+- `DELETE /:bucket/:key?uploadId=X` - AbortMultipartUpload
+- `GET /:bucket/:key?uploadId=X` - ListParts
+- Multipart state management (temp storage for parts)
+- Part ETag tracking and validation
+- Automatic cleanup of abandoned uploads
+
+**Files to Create/Modify:**
+- `ts/controllers/multipart.controller.ts` (new)
+- `ts/classes/filesystem-store.ts` (add multipart methods)
+- `ts/classes/smarts3-server.ts` (add multipart routes)
+
+---
+
+### 2. Configurable Authentication 🔐
+
+**Why:** Currently hardcoded credentials ('S3RVER'/'S3RVER'). Production needs custom credentials.
+
+**Implementation Required:**
+- Support custom access keys and secrets via configuration
+- Implement AWS Signature V4 verification
+- Support multiple credential pairs (IAM-like users)
+- Optional: Disable authentication for local dev use
+
+**Configuration Example:**
+```typescript
+interface IAuthConfig {
+  enabled: boolean;
+  credentials: Array<{
+    accessKeyId: string;
+    secretAccessKey: string;
+  }>;
+  signatureVersion: 'v4' | 'none';
+}
+```
+
+**Files to Create/Modify:**
+- `ts/classes/auth-middleware.ts` (new)
+- `ts/classes/signature-validator.ts` (new)
+- `ts/classes/smarts3-server.ts` (integrate auth middleware)
+- `ts/index.ts` (add auth config options)
+
+---
+
+### 3. CORS Support 🌐
+
+**Why:** Required for browser-based uploads and modern web apps.
+
+**Implementation Required:**
+- Add CORS middleware
+- Support preflight OPTIONS requests
+- Configurable CORS origins, methods, headers
+- Per-bucket CORS configuration (optional)
+
+**Configuration Example:**
+```typescript
+interface ICorsConfig {
+  enabled: boolean;
+  allowedOrigins: string[]; // ['*'] or ['https://example.com']
+  allowedMethods: string[]; // ['GET', 'POST', 'PUT', 'DELETE']
+  allowedHeaders: string[]; // ['*'] or specific headers
+  exposedHeaders: string[]; // ['ETag', 'x-amz-*']
+  maxAge: number; // 3600 (seconds)
+  allowCredentials: boolean;
+}
+```
+
+**Files to Create/Modify:**
+- `ts/classes/cors-middleware.ts` (new)
+- `ts/classes/smarts3-server.ts` (integrate CORS middleware)
+- `ts/index.ts` (add CORS config options)
+
+---
+
+### 4. SSL/TLS Support 🔒
+
+**Why:** Production systems require encrypted connections.
+
+**Implementation Required:**
+- HTTPS server option with cert/key configuration
+- Auto-redirect HTTP to HTTPS (optional)
+- Support for self-signed certs in dev mode
+
+**Configuration Example:**
+```typescript
+interface ISslConfig {
+  enabled: boolean;
+  cert: string; // Path to certificate file or cert content
+  key: string; // Path to key file or key content
+  ca?: string; // Optional CA cert
+  redirectHttp?: boolean; // Redirect HTTP to HTTPS
+}
+```
+
+**Files to Create/Modify:**
+- `ts/classes/smarts3-server.ts` (add HTTPS server creation)
+- `ts/index.ts` (add SSL config options)
+
+---
+
+### 5. Production Configuration System ⚙️
+
+**Why:** Production needs flexible configuration, not just constructor options.
+
+**Implementation Required:**
+- Support configuration file (JSON/YAML)
+- Environment variable support
+- Configuration validation
+- Sensible production defaults
+- Example configurations for common use cases
+
+**Configuration File Example (`smarts3.config.json`):**
+```json
+{
+  "server": {
+    "port": 3000,
+    "address": "0.0.0.0",
+    "ssl": {
+      "enabled": true,
+      "cert": "./certs/server.crt",
+      "key": "./certs/server.key"
+    }
+  },
+  "storage": {
+    "directory": "./s3-data",
+    "cleanSlate": false
+  },
+  "auth": {
+    "enabled": true,
+    "credentials": [
+      {
+        "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
+        "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+      }
+    ]
+  },
+  "cors": {
+    "enabled": true,
+    "allowedOrigins": ["*"],
+    "allowedMethods": ["GET", "POST", "PUT", "DELETE", "HEAD"],
+    "allowedHeaders": ["*"]
+  },
+  "limits": {
+    "maxObjectSize": 5368709120,
+    "maxMetadataSize": 2048,
+    "requestTimeout": 300000
+  },
+  "logging": {
+    "level": "info",
+    "format": "json",
+    "accessLog": {
+      "enabled": true,
+      "path": "./logs/access.log"
+    },
+    "errorLog": {
+      "enabled": true,
+      "path": "./logs/error.log"
+    }
+  }
+}
+```
+
+**Files to Create/Modify:**
+- `ts/classes/config-loader.ts` (new)
+- `ts/classes/config-validator.ts` (new)
+- `ts/index.ts` (use config loader)
+- Create example config files in root
+
+---
+
+### 6. Production Logging 📝
+
+**Why:** Console logs aren't suitable for production monitoring.
+
+**Implementation Required:**
+- Structured logging (JSON format option)
+- Log levels (ERROR, WARN, INFO, DEBUG)
+- File rotation support
+- Access logs (S3 standard format)
+- Integration with logging library
+
+**Files to Create/Modify:**
+- `ts/classes/logger.ts` (new - use @push.rocks/smartlog?)
+- `ts/classes/access-logger-middleware.ts` (new)
+- `ts/classes/smarts3-server.ts` (replace console.log with logger)
+- All controller files (use structured logging)
+
+---
+
+## 🔧 Important Features (Should Have)
+
+### 7. Health Check & Metrics 💊
+
+**Implementation Required:**
+- `GET /_health` endpoint (non-S3, for monitoring)
+- `GET /_metrics` endpoint (Prometheus format?)
+- Server stats (requests/sec, storage used, uptime)
+- Readiness/liveness probes for Kubernetes
+
+**Files to Create/Modify:**
+- `ts/controllers/health.controller.ts` (new)
+- `ts/classes/metrics-collector.ts` (new)
+- `ts/classes/smarts3-server.ts` (add health routes)
+
+---
+
+### 8. Batch Operations 📦
+
+**Implementation Required:**
+- `POST /:bucket?delete` - DeleteObjects (delete multiple objects in one request)
+- Essential for efficient cleanup operations
+
+**Files to Create/Modify:**
+- `ts/controllers/object.controller.ts` (add deleteObjects method)
+
+---
+
+### 9. Request Size Limits & Validation 🛡️
+
+**Implementation Required:**
+- Max object size configuration
+- Max metadata size limits
+- Request timeout configuration
+- Body size limits
+- Bucket name validation (S3 rules)
+- Key name validation
+
+**Files to Create/Modify:**
+- `ts/classes/validation-middleware.ts` (new)
+- `ts/utils/validators.ts` (new)
+- `ts/classes/smarts3-server.ts` (integrate validation middleware)
+
+---
+
+### 10. Conditional Requests 🔄
+
+**Implementation Required:**
+- If-Match / If-None-Match (ETag validation)
+- If-Modified-Since / If-Unmodified-Since
+- Required for caching and conflict prevention
+
+**Files to Create/Modify:**
+- `ts/controllers/object.controller.ts` (add conditional logic to GET/HEAD)
+
+---
+
+### 11. Graceful Shutdown 👋
+
+**Implementation Required:**
+- Drain existing connections
+- Reject new connections
+- Clean multipart cleanup on shutdown
+- SIGTERM/SIGINT handling
+
+**Files to Create/Modify:**
+- `ts/classes/smarts3-server.ts` (add graceful shutdown logic)
+- `ts/index.ts` (add signal handlers)
+
+---
+
+## 💡 Nice-to-Have Features
+
+### 12. Advanced Features
+
+- Bucket versioning support
+- Object tagging
+- Lifecycle policies (auto-delete old objects)
+- Storage class simulation (STANDARD, GLACIER, etc.)
+- Server-side encryption simulation
+- Presigned URL support (for time-limited access)
+
+### 13. Performance Optimizations
+
+- Stream optimization for large files
+- Optional in-memory caching for small objects
+- Parallel upload/download support
+- Compression support (gzip)
+
+### 14. Developer Experience
+
+- Docker image for easy deployment
+- Docker Compose examples
+- Kubernetes manifests
+- CLI for server management
+- Admin API for bucket management
+
+---
+
+## 📐 Implementation Phases
+
+### Phase 1: Critical Production Features (Priority 1)
+
+**Estimated Effort:** 2-3 weeks
+
+1. ✅ Multipart uploads (biggest technical lift)
+2. ✅ Configurable authentication
+3. ✅ CORS middleware
+4. ✅ Production configuration system
+5. ✅ Production logging
+
+**Outcome:** smarts3 can handle real production workloads
+
+---
+
+### Phase 2: Reliability & Operations (Priority 2)
+
+**Estimated Effort:** 1-2 weeks
+
+6. ✅ SSL/TLS support
+7. ✅ Health checks & metrics
+8. ✅ Request validation & limits
+9. ✅ Graceful shutdown
+10. ✅ Batch operations
+
+**Outcome:** smarts3 is operationally mature
+
+---
+
+### Phase 3: S3 Compatibility (Priority 3)
+
+**Estimated Effort:** 1-2 weeks
+
+11. ✅ Conditional requests
+12. ✅ Additional S3 features as needed
+13. ✅ Comprehensive test suite
+14. ✅ Documentation updates
+
+**Outcome:** smarts3 has broad S3 API compatibility
+
+---
+
+### Phase 4: Polish (Priority 4)
+
+**Estimated Effort:** As needed
+
+15. ✅ Docker packaging
+16. ✅ Performance optimization
+17. ✅ Advanced features based on user feedback
+
+**Outcome:** smarts3 is a complete MinIO alternative
+
+---
+
+## 🤔 Open Questions
+
+1. **Authentication:** Do you want full AWS Signature V4 validation, or simpler static credential checking?
+2. **Configuration:** Prefer JSON, YAML, or .env file format?
+3. **Logging:** Do you have a preferred logging library, or shall I use @push.rocks/smartlog?
+4. **Scope:** Should we tackle all of Phase 1, or start with a subset (e.g., just multipart + auth)?
+5. **Testing:** Should we add comprehensive tests as we go, or batch them at the end?
+6. **Breaking changes:** Can I modify the constructor options interface, or must it remain backward compatible?
+
+---
+
+## 🎯 Target Use Cases
+
+**With this plan implemented, smarts3 will be a solid MinIO alternative for:**
+
+✅ **Local S3 development** - Fast, simple, no Docker required
+✅ **Testing S3 integrations** - Reliable, repeatable tests
+✅ **Microservices using S3 API** with filesystem backend
+✅ **CI/CD pipelines** - Lightweight S3 for testing
+✅ **Small-to-medium production deployments** where MinIO is overkill
+✅ **Edge computing** - S3 API for local file storage
+✅ **Embedded systems** - Minimal dependencies, small footprint
+
+---
+
+## 📊 Current vs. Production Comparison
+
+| Feature | Current | After Phase 1 | After Phase 2 | Production Ready |
+|---------|---------|---------------|---------------|------------------|
+| Basic S3 ops | ✅ | ✅ | ✅ | ✅ |
+| Multipart upload | ❌ | ✅ | ✅ | ✅ |
+| Authentication | ⚠️ (hardcoded) | ✅ | ✅ | ✅ |
+| CORS | ❌ | ✅ | ✅ | ✅ |
+| SSL/TLS | ❌ | ❌ | ✅ | ✅ |
+| Config files | ❌ | ✅ | ✅ | ✅ |
+| Production logging | ⚠️ (console) | ✅ | ✅ | ✅ |
+| Health checks | ❌ | ❌ | ✅ | ✅ |
+| Request limits | ❌ | ❌ | ✅ | ✅ |
+| Graceful shutdown | ❌ | ❌ | ✅ | ✅ |
+| Conditional requests | ❌ | ❌ | ❌ | ✅ |
+| Batch operations | ❌ | ❌ | ✅ | ✅ |
+
+---
+
+## 📝 Notes
+
+- All features should maintain backward compatibility where possible
+- Each feature should include comprehensive tests
+- Documentation (readme.md) should be updated as features are added
+- Consider adding a migration guide for users upgrading from testing to production use
+- Performance benchmarks should be established and maintained
+
+---
+
+**Last Updated:** 2025-11-23
+**Status:** Planning Phase
+**Next Step:** Get approval and prioritize implementation order

readme.hints.md

@@ -1 +1,74 @@
- 
+# Project Hints for smarts3
+
+## Current State (v3.0.0)
+
+- Native custom S3 server implementation (Smarts3Server)
+- No longer uses legacy s3rver backend (removed in v3.0.0)
+- Core S3 operations working: PUT, GET, HEAD, DELETE for objects and buckets
+- Multipart upload NOT yet implemented (critical gap for production)
+- Authentication is hardcoded ('S3RVER'/'S3RVER') - not production-ready
+- No CORS support yet
+- No SSL/TLS support yet
+
+## Production Readiness
+
+See `production-readiness.md` for the complete gap analysis and implementation plan.
+
+**Key Missing Features for Production:**
+1. Multipart upload support (HIGHEST PRIORITY)
+2. Configurable authentication
+3. CORS middleware
+4. SSL/TLS support
+5. Production configuration system
+6. Production logging
+
+## Architecture Notes
+
+### File Structure
+- `ts/classes/smarts3-server.ts` - Main server class
+- `ts/classes/filesystem-store.ts` - Storage layer (filesystem-backed)
+- `ts/classes/router.ts` - URL routing with pattern matching
+- `ts/classes/middleware-stack.ts` - Middleware execution
+- `ts/classes/context.ts` - Request/response context
+- `ts/classes/s3-error.ts` - S3-compatible error handling
+- `ts/controllers/` - Service, bucket, and object controllers
+- `ts/index.ts` - Main export (Smarts3 class)
+
+### Storage Layout
+- Objects stored as: `{bucket}/{encodedKey}._S3_object`
+- Metadata stored as: `{bucket}/{encodedKey}._S3_object.metadata.json`
+- MD5 stored as: `{bucket}/{encodedKey}._S3_object.md5`
+- Keys are encoded for Windows compatibility (hex encoding for invalid chars)
+
+### Current Limitations
+- Max file size limited by available memory (no streaming multipart)
+- Single server instance only (no clustering)
+- No versioning support
+- No access control beyond basic auth
+
+## Testing
+
+- Main test: `test/test.aws-sdk.node.ts` - Tests AWS SDK v3 compatibility
+- Run with: `pnpm test`
+- Tests run with cleanSlate mode enabled
+
+## Dependencies
+
+- `@push.rocks/smartbucket` - S3 abstraction layer
+- `@push.rocks/smartfs` - Modern filesystem operations with Web Streams API (replaced smartfile)
+- `@push.rocks/smartxml` - XML generation/parsing
+- `@push.rocks/smartpath` - Path utilities
+- `@tsclass/tsclass` - TypeScript utilities
+
+## Migration Notes (2025-11-23)
+
+Successfully migrated from `@push.rocks/smartfile` + native `fs` to `@push.rocks/smartfs`:
+- All file/directory operations now use smartfs fluent API
+- Web Streams → Node.js Streams conversion for HTTP compatibility
+- All tests passing ✅
+- Build successful ✅
+
+## Next Steps
+
+Waiting for approval to proceed with production-readiness implementation.
+Priority 1 is implementing multipart uploads.

readme.md

@@ -413,7 +413,7 @@ interface ISmarts3ContructorOptions {
 ## 🔗 Related Packages
 
 - [`@push.rocks/smartbucket`](https://www.npmjs.com/package/@push.rocks/smartbucket) - Powerful S3 abstraction layer
-- [`@push.rocks/smartfile`](https://www.npmjs.com/package/@push.rocks/smartfile) - Advanced file system operations
+- [`@push.rocks/smartfs`](https://www.npmjs.com/package/@push.rocks/smartfs) - Modern filesystem with Web Streams support
 - [`@tsclass/tsclass`](https://www.npmjs.com/package/@tsclass/tsclass) - TypeScript class helpers
 
 ## License and Legal Information

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smarts3',
-  version: '3.0.1',
+  version: '3.1.0',
   description: 'A Node.js TypeScript package to create a local S3 endpoint for simulating AWS S3 operations using mapped local directories for development and testing purposes.'
 }

ts/classes/filesystem-store.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../plugins.js';
 import { S3Error } from './s3-error.js';
-import type { Readable } from 'stream';
+import { Readable } from 'stream';
 
 export interface IS3Bucket {
   name: string;
@@ -39,7 +39,7 @@ export interface IRangeOptions {
 }
 
 /**
- * Filesystem-backed storage for S3 objects
+ * Filesystem-backed storage for S3 objects using smartfs
  */
 export class FilesystemStore {
   constructor(private rootDir: string) {}
@@ -48,14 +48,19 @@ export class FilesystemStore {
    * Initialize store (ensure root directory exists)
    */
   public async initialize(): Promise<void> {
-    await plugins.fs.promises.mkdir(this.rootDir, { recursive: true });
+    await plugins.smartfs.directory(this.rootDir).recursive().create();
   }
 
   /**
    * Reset store (delete all buckets)
    */
   public async reset(): Promise<void> {
-    await plugins.smartfile.fs.ensureEmptyDir(this.rootDir);
+    // Delete directory and recreate it
+    const exists = await plugins.smartfs.directory(this.rootDir).exists();
+    if (exists) {
+      await plugins.smartfs.directory(this.rootDir).recursive().delete();
+    }
+    await plugins.smartfs.directory(this.rootDir).recursive().create();
   }
 
   // ============================
@@ -66,17 +71,16 @@ export class FilesystemStore {
    * List all buckets
    */
   public async listBuckets(): Promise<IS3Bucket[]> {
-    const dirs = await plugins.smartfile.fs.listFolders(this.rootDir);
+    const entries = await plugins.smartfs.directory(this.rootDir).includeStats().list();
     const buckets: IS3Bucket[] = [];
 
-    for (const dir of dirs) {
-      const bucketPath = plugins.path.join(this.rootDir, dir);
-      const stats = await plugins.smartfile.fs.stat(bucketPath);
-
-      buckets.push({
-        name: dir,
-        creationDate: stats.birthtime,
-      });
+    for (const entry of entries) {
+      if (entry.isDirectory && entry.stats) {
+        buckets.push({
+          name: entry.name,
+          creationDate: entry.stats.birthtime,
+        });
+      }
     }
 
     return buckets.sort((a, b) => a.name.localeCompare(b.name));
@@ -87,7 +91,7 @@ export class FilesystemStore {
    */
   public async bucketExists(bucket: string): Promise<boolean> {
     const bucketPath = this.getBucketPath(bucket);
-    return plugins.smartfile.fs.isDirectory(bucketPath);
+    return plugins.smartfs.directory(bucketPath).exists();
   }
 
   /**
@@ -95,7 +99,7 @@ export class FilesystemStore {
    */
   public async createBucket(bucket: string): Promise<void> {
     const bucketPath = this.getBucketPath(bucket);
-    await plugins.fs.promises.mkdir(bucketPath, { recursive: true });
+    await plugins.smartfs.directory(bucketPath).recursive().create();
   }
 
   /**
@@ -110,12 +114,12 @@ export class FilesystemStore {
     }
 
     // Check if bucket is empty
-    const files = await plugins.smartfile.fs.listFileTree(bucketPath, '**/*');
+    const files = await plugins.smartfs.directory(bucketPath).recursive().list();
     if (files.length > 0) {
       throw new S3Error('BucketNotEmpty', 'The bucket you tried to delete is not empty');
     }
 
-    await plugins.smartfile.fs.remove(bucketPath);
+    await plugins.smartfs.directory(bucketPath).recursive().delete();
   }
 
   // ============================
@@ -142,13 +146,16 @@ export class FilesystemStore {
       continuationToken,
     } = options;
 
-    // List all object files
-    const objectPattern = '**/*._S3_object';
-    const objectFiles = await plugins.smartfile.fs.listFileTree(bucketPath, objectPattern);
+    // List all object files recursively with filter
+    const entries = await plugins.smartfs
+      .directory(bucketPath)
+      .recursive()
+      .filter((entry) => entry.name.endsWith('._S3_object'))
+      .list();
 
     // Convert file paths to keys
-    let keys = objectFiles.map((filePath) => {
-      const relativePath = plugins.path.relative(bucketPath, filePath);
+    let keys = entries.map((entry) => {
+      const relativePath = plugins.path.relative(bucketPath, entry.path);
       const key = this.decodeKey(relativePath.replace(/\._S3_object$/, ''));
       return key;
     });
@@ -226,7 +233,7 @@ export class FilesystemStore {
     const md5Path = `${objectPath}.md5`;
 
     const [stats, metadata, md5] = await Promise.all([
-      plugins.smartfile.fs.stat(objectPath),
+      plugins.smartfs.file(objectPath).stat(),
       this.readMetadata(metadataPath),
       this.readMD5(objectPath, md5Path),
     ]);
@@ -245,7 +252,7 @@ export class FilesystemStore {
    */
   public async objectExists(bucket: string, key: string): Promise<boolean> {
     const objectPath = this.getObjectPath(bucket, key);
-    return plugins.smartfile.fs.fileExists(objectPath);
+    return plugins.smartfs.file(objectPath).exists();
   }
 
   /**
@@ -265,14 +272,15 @@ export class FilesystemStore {
     }
 
     // Ensure parent directory exists
-    await plugins.fs.promises.mkdir(plugins.path.dirname(objectPath), { recursive: true });
+    const parentDir = plugins.path.dirname(objectPath);
+    await plugins.smartfs.directory(parentDir).recursive().create();
 
     // Write with MD5 calculation
     const result = await this.writeStreamWithMD5(stream, objectPath);
 
     // Save metadata
     const metadataPath = `${objectPath}.metadata.json`;
-    await plugins.fs.promises.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    await plugins.smartfs.file(metadataPath).write(JSON.stringify(metadata, null, 2));
 
     return result;
   }
@@ -293,14 +301,50 @@ export class FilesystemStore {
 
     const info = await this.getObjectInfo(bucket, key);
 
-    // Create read stream with optional range (using native fs for range support)
-    const stream = range
-      ? plugins.fs.createReadStream(objectPath, { start: range.start, end: range.end })
-      : plugins.fs.createReadStream(objectPath);
+    // Get Web ReadableStream from smartfs
+    const webStream = await plugins.smartfs.file(objectPath).readStream();
+
+    // Convert Web Stream to Node.js Readable stream
+    let nodeStream = Readable.fromWeb(webStream as any);
+
+    // Handle range requests if needed
+    if (range) {
+      // For range requests, we need to skip bytes and limit output
+      let bytesRead = 0;
+      const rangeStart = range.start;
+      const rangeEnd = range.end;
+
+      nodeStream = nodeStream.pipe(new (require('stream').Transform)({
+        transform(chunk: Buffer, encoding, callback) {
+          const chunkStart = bytesRead;
+          const chunkEnd = bytesRead + chunk.length - 1;
+          bytesRead += chunk.length;
+
+          // Skip chunks before range
+          if (chunkEnd < rangeStart) {
+            callback();
+            return;
+          }
+
+          // Stop after range
+          if (chunkStart > rangeEnd) {
+            this.end();
+            callback();
+            return;
+          }
+
+          // Slice chunk to fit range
+          const sliceStart = Math.max(0, rangeStart - chunkStart);
+          const sliceEnd = Math.min(chunk.length, rangeEnd - chunkStart + 1);
+
+          callback(null, chunk.slice(sliceStart, sliceEnd));
+        }
+      }));
+    }
 
     return {
       ...info,
-      content: stream,
+      content: nodeStream,
     };
   }
 
@@ -314,9 +358,9 @@ export class FilesystemStore {
 
     // S3 doesn't throw error if object doesn't exist
     await Promise.all([
-      plugins.smartfile.fs.remove(objectPath).catch(() => {}),
-      plugins.smartfile.fs.remove(metadataPath).catch(() => {}),
-      plugins.smartfile.fs.remove(md5Path).catch(() => {}),
+      plugins.smartfs.file(objectPath).delete().catch(() => {}),
+      plugins.smartfs.file(metadataPath).delete().catch(() => {}),
+      plugins.smartfs.file(md5Path).delete().catch(() => {}),
     ]);
   }
 
@@ -345,30 +389,31 @@ export class FilesystemStore {
     }
 
     // Ensure parent directory exists
-    await plugins.fs.promises.mkdir(plugins.path.dirname(destObjectPath), { recursive: true });
+    const parentDir = plugins.path.dirname(destObjectPath);
+    await plugins.smartfs.directory(parentDir).recursive().create();
 
     // Copy object file
-    await plugins.smartfile.fs.copy(srcObjectPath, destObjectPath);
+    await plugins.smartfs.file(srcObjectPath).copy(destObjectPath);
 
     // Handle metadata
     if (metadataDirective === 'COPY') {
       // Copy metadata
       const srcMetadataPath = `${srcObjectPath}.metadata.json`;
       const destMetadataPath = `${destObjectPath}.metadata.json`;
-      await plugins.smartfile.fs.copy(srcMetadataPath, destMetadataPath).catch(() => {});
+      await plugins.smartfs.file(srcMetadataPath).copy(destMetadataPath).catch(() => {});
     } else if (newMetadata) {
       // Replace with new metadata
       const destMetadataPath = `${destObjectPath}.metadata.json`;
-      await plugins.fs.promises.writeFile(destMetadataPath, JSON.stringify(newMetadata, null, 2));
+      await plugins.smartfs.file(destMetadataPath).write(JSON.stringify(newMetadata, null, 2));
     }
 
     // Copy MD5
     const srcMD5Path = `${srcObjectPath}.md5`;
     const destMD5Path = `${destObjectPath}.md5`;
-    await plugins.smartfile.fs.copy(srcMD5Path, destMD5Path).catch(() => {});
+    await plugins.smartfs.file(srcMD5Path).copy(destMD5Path).catch(() => {});
 
     // Get result info
-    const stats = await plugins.smartfile.fs.stat(destObjectPath);
+    const stats = await plugins.smartfs.file(destObjectPath).stat();
     const md5 = await this.readMD5(destObjectPath, destMD5Path);
 
     return { size: stats.size, md5 };
@@ -432,25 +477,41 @@ export class FilesystemStore {
     const hash = plugins.crypto.createHash('md5');
     let totalSize = 0;
 
-    return new Promise((resolve, reject) => {
-      const output = plugins.fs.createWriteStream(destPath);
+    return new Promise(async (resolve, reject) => {
+      // Get Web WritableStream from smartfs
+      const webWriteStream = await plugins.smartfs.file(destPath).writeStream();
+      const writer = webWriteStream.getWriter();
 
-      input.on('data', (chunk: Buffer) => {
+      // Read from Node.js stream and write to Web stream
+      input.on('data', async (chunk: Buffer) => {
         hash.update(chunk);
         totalSize += chunk.length;
+
+        try {
+          await writer.write(new Uint8Array(chunk));
+        } catch (err) {
+          reject(err);
+        }
       });
 
-      input.on('error', reject);
-      output.on('error', reject);
+      input.on('error', (err) => {
+        writer.abort(err);
+        reject(err);
+      });
 
-      input.pipe(output).on('finish', async () => {
-        const md5 = hash.digest('hex');
+      input.on('end', async () => {
+        try {
+          await writer.close();
+          const md5 = hash.digest('hex');
 
-        // Save MD5 to separate file
-        const md5Path = `${destPath}.md5`;
-        await plugins.fs.promises.writeFile(md5Path, md5);
+          // Save MD5 to separate file
+          const md5Path = `${destPath}.md5`;
+          await plugins.smartfs.file(md5Path).write(md5);
 
-        resolve({ size: totalSize, md5 });
+          resolve({ size: totalSize, md5 });
+        } catch (err) {
+          reject(err);
+        }
       });
     });
   }
@@ -461,22 +522,28 @@ export class FilesystemStore {
   private async readMD5(objectPath: string, md5Path: string): Promise<string> {
     try {
       // Try to read cached MD5
-      const md5 = await plugins.smartfile.fs.toStringSync(md5Path);
+      const md5 = await plugins.smartfs.file(md5Path).encoding('utf8').read() as string;
       return md5.trim();
     } catch (err) {
       // Calculate MD5 if not cached
-      return new Promise((resolve, reject) => {
+      return new Promise(async (resolve, reject) => {
         const hash = plugins.crypto.createHash('md5');
-        const stream = plugins.fs.createReadStream(objectPath);
 
-        stream.on('data', (chunk: Buffer) => hash.update(chunk));
-        stream.on('end', async () => {
-          const md5 = hash.digest('hex');
-          // Cache it
-          await plugins.fs.promises.writeFile(md5Path, md5);
-          resolve(md5);
-        });
-        stream.on('error', reject);
+        try {
+          const webStream = await plugins.smartfs.file(objectPath).readStream();
+          const nodeStream = Readable.fromWeb(webStream as any);
+
+          nodeStream.on('data', (chunk: Buffer) => hash.update(chunk));
+          nodeStream.on('end', async () => {
+            const md5 = hash.digest('hex');
+            // Cache it
+            await plugins.smartfs.file(md5Path).write(md5);
+            resolve(md5);
+          });
+          nodeStream.on('error', reject);
+        } catch (err) {
+          reject(err);
+        }
       });
     }
   }
@@ -486,7 +553,7 @@ export class FilesystemStore {
    */
   private async readMetadata(metadataPath: string): Promise<Record<string, string>> {
     try {
-      const content = await plugins.smartfile.fs.toStringSync(metadataPath);
+      const content = await plugins.smartfs.file(metadataPath).encoding('utf8').read() as string;
       return JSON.parse(content);
     } catch (err) {
       return {};

ts/classes/logger.ts

@@ -0,0 +1,130 @@
+import type { ILoggingConfig } from '../index.js';
+
+/**
+ * Log levels in order of severity
+ */
+const LOG_LEVELS = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+} as const;
+
+type LogLevel = keyof typeof LOG_LEVELS;
+
+/**
+ * Structured logger with configurable levels and formats
+ */
+export class Logger {
+  private config: Required<ILoggingConfig>;
+  private minLevel: number;
+
+  constructor(config: ILoggingConfig) {
+    // Apply defaults for any missing config
+    this.config = {
+      level: config.level ?? 'info',
+      format: config.format ?? 'text',
+      enabled: config.enabled ?? true,
+    };
+    this.minLevel = LOG_LEVELS[this.config.level];
+  }
+
+  /**
+   * Check if a log level should be output
+   */
+  private shouldLog(level: LogLevel): boolean {
+    if (!this.config.enabled) {
+      return false;
+    }
+    return LOG_LEVELS[level] <= this.minLevel;
+  }
+
+  /**
+   * Format a log message
+   */
+  private format(level: LogLevel, message: string, meta?: Record<string, any>): string {
+    const timestamp = new Date().toISOString();
+
+    if (this.config.format === 'json') {
+      return JSON.stringify({
+        timestamp,
+        level,
+        message,
+        ...(meta || {}),
+      });
+    }
+
+    // Text format
+    const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
+    return `[${timestamp}] ${level.toUpperCase()}: ${message}${metaStr}`;
+  }
+
+  /**
+   * Log at error level
+   */
+  public error(message: string, meta?: Record<string, any>): void {
+    if (this.shouldLog('error')) {
+      console.error(this.format('error', message, meta));
+    }
+  }
+
+  /**
+   * Log at warn level
+   */
+  public warn(message: string, meta?: Record<string, any>): void {
+    if (this.shouldLog('warn')) {
+      console.warn(this.format('warn', message, meta));
+    }
+  }
+
+  /**
+   * Log at info level
+   */
+  public info(message: string, meta?: Record<string, any>): void {
+    if (this.shouldLog('info')) {
+      console.log(this.format('info', message, meta));
+    }
+  }
+
+  /**
+   * Log at debug level
+   */
+  public debug(message: string, meta?: Record<string, any>): void {
+    if (this.shouldLog('debug')) {
+      console.log(this.format('debug', message, meta));
+    }
+  }
+
+  /**
+   * Log HTTP request
+   */
+  public request(method: string, url: string, meta?: Record<string, any>): void {
+    this.info(`→ ${method} ${url}`, meta);
+  }
+
+  /**
+   * Log HTTP response
+   */
+  public response(method: string, url: string, statusCode: number, duration: number): void {
+    const level: LogLevel = statusCode >= 500 ? 'error' : statusCode >= 400 ? 'warn' : 'info';
+
+    if (this.shouldLog(level)) {
+      const message = `← ${method} ${url} - ${statusCode} (${duration}ms)`;
+
+      if (level === 'error') {
+        this.error(message, { statusCode, duration });
+      } else if (level === 'warn') {
+        this.warn(message, { statusCode, duration });
+      } else {
+        this.info(message, { statusCode, duration });
+      }
+    }
+  }
+
+  /**
+   * Log S3 error
+   */
+  public s3Error(code: string, message: string, status: number): void {
+    this.error(`[S3Error] ${code}: ${message}`, { code, status });
+  }
+}

ts/classes/multipart-manager.ts

@@ -0,0 +1,238 @@
+import * as plugins from '../plugins.js';
+import { Readable } from 'stream';
+
+/**
+ * Multipart upload metadata
+ */
+export interface IMultipartUpload {
+  uploadId: string;
+  bucket: string;
+  key: string;
+  initiated: Date;
+  parts: Map<number, IPartInfo>;
+  metadata: Record<string, string>;
+}
+
+/**
+ * Part information
+ */
+export interface IPartInfo {
+  partNumber: number;
+  etag: string;
+  size: number;
+  lastModified: Date;
+}
+
+/**
+ * Manages multipart upload state and storage
+ */
+export class MultipartUploadManager {
+  private uploads: Map<string, IMultipartUpload> = new Map();
+  private uploadDir: string;
+
+  constructor(private rootDir: string) {
+    this.uploadDir = plugins.path.join(rootDir, '.multipart');
+  }
+
+  /**
+   * Initialize multipart uploads directory
+   */
+  public async initialize(): Promise<void> {
+    await plugins.smartfs.directory(this.uploadDir).recursive().create();
+  }
+
+  /**
+   * Generate a unique upload ID
+   */
+  private generateUploadId(): string {
+    return plugins.crypto.randomBytes(16).toString('hex');
+  }
+
+  /**
+   * Initiate a new multipart upload
+   */
+  public async initiateUpload(
+    bucket: string,
+    key: string,
+    metadata: Record<string, string>
+  ): Promise<string> {
+    const uploadId = this.generateUploadId();
+
+    this.uploads.set(uploadId, {
+      uploadId,
+      bucket,
+      key,
+      initiated: new Date(),
+      parts: new Map(),
+      metadata,
+    });
+
+    // Create directory for this upload's parts
+    const uploadPath = plugins.path.join(this.uploadDir, uploadId);
+    await plugins.smartfs.directory(uploadPath).recursive().create();
+
+    return uploadId;
+  }
+
+  /**
+   * Upload a part
+   */
+  public async uploadPart(
+    uploadId: string,
+    partNumber: number,
+    stream: Readable
+  ): Promise<IPartInfo> {
+    const upload = this.uploads.get(uploadId);
+    if (!upload) {
+      throw new Error('No such upload');
+    }
+
+    const partPath = plugins.path.join(this.uploadDir, uploadId, `part-${partNumber}`);
+
+    // Write part to disk
+    const webWriteStream = await plugins.smartfs.file(partPath).writeStream();
+    const writer = webWriteStream.getWriter();
+
+    let size = 0;
+    const hash = plugins.crypto.createHash('md5');
+
+    for await (const chunk of stream) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      await writer.write(new Uint8Array(buffer));
+      hash.update(buffer);
+      size += buffer.length;
+    }
+
+    await writer.close();
+
+    const etag = hash.digest('hex');
+
+    const partInfo: IPartInfo = {
+      partNumber,
+      etag,
+      size,
+      lastModified: new Date(),
+    };
+
+    upload.parts.set(partNumber, partInfo);
+
+    return partInfo;
+  }
+
+  /**
+   * Complete multipart upload - combine all parts
+   */
+  public async completeUpload(
+    uploadId: string,
+    parts: Array<{ PartNumber: number; ETag: string }>
+  ): Promise<{ etag: string; size: number }> {
+    const upload = this.uploads.get(uploadId);
+    if (!upload) {
+      throw new Error('No such upload');
+    }
+
+    // Verify all parts are uploaded
+    for (const part of parts) {
+      const uploadedPart = upload.parts.get(part.PartNumber);
+      if (!uploadedPart) {
+        throw new Error(`Part ${part.PartNumber} not uploaded`);
+      }
+      // Normalize ETag format (remove quotes if present)
+      const normalizedETag = part.ETag.replace(/"/g, '');
+      if (uploadedPart.etag !== normalizedETag) {
+        throw new Error(`Part ${part.PartNumber} ETag mismatch`);
+      }
+    }
+
+    // Sort parts by part number
+    const sortedParts = parts.sort((a, b) => a.PartNumber - b.PartNumber);
+
+    // Combine parts into final object
+    const finalPath = plugins.path.join(this.uploadDir, uploadId, 'final');
+    const webWriteStream = await plugins.smartfs.file(finalPath).writeStream();
+    const writer = webWriteStream.getWriter();
+
+    const hash = plugins.crypto.createHash('md5');
+    let totalSize = 0;
+
+    for (const part of sortedParts) {
+      const partPath = plugins.path.join(this.uploadDir, uploadId, `part-${part.PartNumber}`);
+
+      // Read part and write to final file
+      const partContent = await plugins.smartfs.file(partPath).read();
+      const buffer = Buffer.isBuffer(partContent) ? partContent : Buffer.from(partContent as string);
+
+      await writer.write(new Uint8Array(buffer));
+      hash.update(buffer);
+      totalSize += buffer.length;
+    }
+
+    await writer.close();
+
+    const etag = hash.digest('hex');
+
+    return { etag, size: totalSize };
+  }
+
+  /**
+   * Get the final combined file path
+   */
+  public getFinalPath(uploadId: string): string {
+    return plugins.path.join(this.uploadDir, uploadId, 'final');
+  }
+
+  /**
+   * Get upload metadata
+   */
+  public getUpload(uploadId: string): IMultipartUpload | undefined {
+    return this.uploads.get(uploadId);
+  }
+
+  /**
+   * Abort multipart upload - clean up parts
+   */
+  public async abortUpload(uploadId: string): Promise<void> {
+    const upload = this.uploads.get(uploadId);
+    if (!upload) {
+      throw new Error('No such upload');
+    }
+
+    // Delete upload directory
+    const uploadPath = plugins.path.join(this.uploadDir, uploadId);
+    await plugins.smartfs.directory(uploadPath).recursive().delete();
+
+    // Remove from memory
+    this.uploads.delete(uploadId);
+  }
+
+  /**
+   * Clean up upload after completion
+   */
+  public async cleanupUpload(uploadId: string): Promise<void> {
+    const uploadPath = plugins.path.join(this.uploadDir, uploadId);
+    await plugins.smartfs.directory(uploadPath).recursive().delete();
+    this.uploads.delete(uploadId);
+  }
+
+  /**
+   * List all in-progress uploads for a bucket
+   */
+  public listUploads(bucket?: string): IMultipartUpload[] {
+    const uploads = Array.from(this.uploads.values());
+    if (bucket) {
+      return uploads.filter((u) => u.bucket === bucket);
+    }
+    return uploads;
+  }
+
+  /**
+   * List parts for an upload
+   */
+  public listParts(uploadId: string): IPartInfo[] {
+    const upload = this.uploads.get(uploadId);
+    if (!upload) {
+      throw new Error('No such upload');
+    }
+    return Array.from(upload.parts.values()).sort((a, b) => a.partNumber - b.partNumber);
+  }
+}

ts/classes/smarts3-server.ts

@@ -4,9 +4,11 @@ import { MiddlewareStack } from './middleware-stack.js';
 import { S3Context } from './context.js';
 import { FilesystemStore } from './filesystem-store.js';
 import { S3Error } from './s3-error.js';
+import { Logger } from './logger.js';
 import { ServiceController } from '../controllers/service.controller.js';
 import { BucketController } from '../controllers/bucket.controller.js';
 import { ObjectController } from '../controllers/object.controller.js';
+import type { ISmarts3Config } from '../index.js';
 
 export interface ISmarts3ServerOptions {
   port?: number;
@@ -14,6 +16,7 @@ export interface ISmarts3ServerOptions {
   directory?: string;
   cleanSlate?: boolean;
   silent?: boolean;
+  config?: Required<ISmarts3Config>;
 }
 
 /**
@@ -24,19 +27,58 @@ export class Smarts3Server {
   private httpServer?: plugins.http.Server;
   private router: S3Router;
   private middlewares: MiddlewareStack;
-  private store: FilesystemStore;
-  private options: Required<ISmarts3ServerOptions>;
+  public store: FilesystemStore; // Made public for direct access from Smarts3 class
+  private options: Required<Omit<ISmarts3ServerOptions, 'config'>>;
+  private config: Required<ISmarts3Config>;
+  private logger: Logger;
 
   constructor(options: ISmarts3ServerOptions = {}) {
     this.options = {
-      port: 3000,
-      address: '0.0.0.0',
-      directory: plugins.path.join(process.cwd(), '.nogit/bucketsDir'),
-      cleanSlate: false,
-      silent: false,
-      ...options,
+      port: options.port ?? 3000,
+      address: options.address ?? '0.0.0.0',
+      directory: options.directory ?? plugins.path.join(process.cwd(), '.nogit/bucketsDir'),
+      cleanSlate: options.cleanSlate ?? false,
+      silent: options.silent ?? false,
     };
 
+    // Store config for middleware and feature configuration
+    // If no config provided, create minimal default (for backward compatibility)
+    this.config = options.config ?? {
+      server: {
+        port: this.options.port,
+        address: this.options.address,
+        silent: this.options.silent,
+      },
+      storage: {
+        directory: this.options.directory,
+        cleanSlate: this.options.cleanSlate,
+      },
+      auth: {
+        enabled: false,
+        credentials: [{ accessKeyId: 'S3RVER', secretAccessKey: 'S3RVER' }],
+      },
+      cors: {
+        enabled: false,
+        allowedOrigins: ['*'],
+        allowedMethods: ['GET', 'POST', 'PUT', 'DELETE', 'HEAD', 'OPTIONS'],
+        allowedHeaders: ['*'],
+        exposedHeaders: ['ETag', 'x-amz-request-id', 'x-amz-version-id'],
+        maxAge: 86400,
+        allowCredentials: false,
+      },
+      logging: {
+        level: 'info',
+        format: 'text',
+        enabled: true,
+      },
+      limits: {
+        maxObjectSize: 5 * 1024 * 1024 * 1024,
+        maxMetadataSize: 2048,
+        requestTimeout: 300000,
+      },
+    };
+
+    this.logger = new Logger(this.config.logging);
     this.store = new FilesystemStore(this.options.directory);
     this.router = new S3Router();
     this.middlewares = new MiddlewareStack();
@@ -49,20 +91,118 @@ export class Smarts3Server {
    * Setup middleware stack
    */
   private setupMiddlewares(): void {
-    // Logger middleware
-    if (!this.options.silent) {
+    // CORS middleware (must be first to handle preflight requests)
+    if (this.config.cors.enabled) {
       this.middlewares.use(async (req, res, ctx, next) => {
-        const start = Date.now();
-        console.log(`→ ${req.method} ${req.url}`);
-        console.log(`  Headers:`, JSON.stringify(req.headers, null, 2).slice(0, 200));
+        const origin = req.headers.origin || req.headers.referer;
+
+        // Check if origin is allowed
+        const allowedOrigins = this.config.cors.allowedOrigins || ['*'];
+        const isOriginAllowed =
+          allowedOrigins.includes('*') ||
+          (origin && allowedOrigins.includes(origin));
+
+        if (isOriginAllowed) {
+          // Set CORS headers
+          res.setHeader(
+            'Access-Control-Allow-Origin',
+            allowedOrigins.includes('*') ? '*' : origin || '*'
+          );
+
+          if (this.config.cors.allowCredentials) {
+            res.setHeader('Access-Control-Allow-Credentials', 'true');
+          }
+
+          // Handle preflight OPTIONS request
+          if (req.method === 'OPTIONS') {
+            res.setHeader(
+              'Access-Control-Allow-Methods',
+              (this.config.cors.allowedMethods || []).join(', ')
+            );
+            res.setHeader(
+              'Access-Control-Allow-Headers',
+              (this.config.cors.allowedHeaders || []).join(', ')
+            );
+            if (this.config.cors.maxAge) {
+              res.setHeader(
+                'Access-Control-Max-Age',
+                String(this.config.cors.maxAge)
+              );
+            }
+            res.writeHead(204);
+            res.end();
+            return; // Don't call next() for OPTIONS
+          }
+
+          // Set exposed headers for actual requests
+          if (this.config.cors.exposedHeaders && this.config.cors.exposedHeaders.length > 0) {
+            res.setHeader(
+              'Access-Control-Expose-Headers',
+              this.config.cors.exposedHeaders.join(', ')
+            );
+          }
+        }
+
         await next();
-        const duration = Date.now() - start;
-        console.log(`← ${req.method} ${req.url} - ${res.statusCode} (${duration}ms)`);
       });
     }
 
-    // TODO: Add authentication middleware
-    // TODO: Add CORS middleware
+    // Authentication middleware (simple static credentials)
+    if (this.config.auth.enabled) {
+      this.middlewares.use(async (req, res, ctx, next) => {
+        const authHeader = req.headers.authorization;
+
+        // Extract access key from Authorization header
+        let accessKeyId: string | undefined;
+
+        if (authHeader) {
+          // Support multiple auth formats:
+          // 1. AWS accessKeyId:signature
+          // 2. AWS4-HMAC-SHA256 Credential=accessKeyId/date/region/service/aws4_request, ...
+          if (authHeader.startsWith('AWS ')) {
+            accessKeyId = authHeader.substring(4).split(':')[0];
+          } else if (authHeader.startsWith('AWS4-HMAC-SHA256')) {
+            const credentialMatch = authHeader.match(/Credential=([^/]+)\//);
+            accessKeyId = credentialMatch ? credentialMatch[1] : undefined;
+          }
+        }
+
+        // Check if access key is valid
+        const isValid = this.config.auth.credentials.some(
+          (cred) => cred.accessKeyId === accessKeyId
+        );
+
+        if (!isValid) {
+          ctx.throw('AccessDenied', 'Access Denied');
+          return;
+        }
+
+        await next();
+      });
+    }
+
+    // Logger middleware
+    if (!this.options.silent && this.config.logging.enabled) {
+      this.middlewares.use(async (req, res, ctx, next) => {
+        const start = Date.now();
+
+        // Log request
+        this.logger.request(req.method || 'UNKNOWN', req.url || '/', {
+          headers: req.headers,
+        });
+
+        await next();
+
+        // Log response
+        const duration = Date.now() - start;
+        this.logger.response(
+          req.method || 'UNKNOWN',
+          req.url || '/',
+          res.statusCode || 500,
+          duration
+        );
+      });
+    }
   }
 
   /**
@@ -122,11 +262,14 @@ export class Smarts3Server {
   ): Promise<void> {
     const s3Error = err instanceof S3Error ? err : S3Error.fromError(err);
 
-    if (!this.options.silent) {
-      console.error(`[S3Error] ${s3Error.code}: ${s3Error.message}`);
-      if (s3Error.status >= 500) {
-        console.error(err.stack || err);
-      }
+    // Log the error
+    this.logger.s3Error(s3Error.code, s3Error.message, s3Error.status);
+
+    // Log stack trace for server errors
+    if (s3Error.status >= 500) {
+      this.logger.debug('Error stack trace', {
+        stack: err.stack || err.toString(),
+      });
     }
 
     // Send error response
@@ -155,7 +298,10 @@ export class Smarts3Server {
     // Create HTTP server
     this.httpServer = plugins.http.createServer((req, res) => {
       this.handleRequest(req, res).catch((err) => {
-        console.error('Fatal error in request handler:', err);
+        this.logger.error('Fatal error in request handler', {
+          error: err.message,
+          stack: err.stack,
+        });
         if (!res.headersSent) {
           res.writeHead(500, { 'Content-Type': 'text/plain' });
           res.end('Internal Server Error');
@@ -169,9 +315,7 @@ export class Smarts3Server {
         if (err) {
           reject(err);
         } else {
-          if (!this.options.silent) {
-            console.log(`S3 server listening on ${this.options.address}:${this.options.port}`);
-          }
+          this.logger.info(`S3 server listening on ${this.options.address}:${this.options.port}`);
           resolve();
         }
       });
@@ -191,9 +335,7 @@ export class Smarts3Server {
         if (err) {
           reject(err);
         } else {
-          if (!this.options.silent) {
-            console.log('S3 server stopped');
-          }
+          this.logger.info('S3 server stopped');
           resolve();
         }
       });

ts/index.ts

@@ -2,39 +2,185 @@ import * as plugins from './plugins.js';
 import * as paths from './paths.js';
 import { Smarts3Server } from './classes/smarts3-server.js';
 
-export interface ISmarts3ContructorOptions {
+/**
+ * Authentication configuration
+ */
+export interface IAuthConfig {
+  enabled: boolean;
+  credentials: Array<{
+    accessKeyId: string;
+    secretAccessKey: string;
+  }>;
+}
+
+/**
+ * CORS configuration
+ */
+export interface ICorsConfig {
+  enabled: boolean;
+  allowedOrigins?: string[];
+  allowedMethods?: string[];
+  allowedHeaders?: string[];
+  exposedHeaders?: string[];
+  maxAge?: number;
+  allowCredentials?: boolean;
+}
+
+/**
+ * Logging configuration
+ */
+export interface ILoggingConfig {
+  level?: 'error' | 'warn' | 'info' | 'debug';
+  format?: 'text' | 'json';
+  enabled?: boolean;
+}
+
+/**
+ * Request limits configuration
+ */
+export interface ILimitsConfig {
+  maxObjectSize?: number;
+  maxMetadataSize?: number;
+  requestTimeout?: number;
+}
+
+/**
+ * Server configuration
+ */
+export interface IServerConfig {
   port?: number;
+  address?: string;
+  silent?: boolean;
+}
+
+/**
+ * Storage configuration
+ */
+export interface IStorageConfig {
+  directory?: string;
   cleanSlate?: boolean;
 }
 
+/**
+ * Complete smarts3 configuration
+ */
+export interface ISmarts3Config {
+  server?: IServerConfig;
+  storage?: IStorageConfig;
+  auth?: IAuthConfig;
+  cors?: ICorsConfig;
+  logging?: ILoggingConfig;
+  limits?: ILimitsConfig;
+}
+
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG: ISmarts3Config = {
+  server: {
+    port: 3000,
+    address: '0.0.0.0',
+    silent: false,
+  },
+  storage: {
+    directory: paths.bucketsDir,
+    cleanSlate: false,
+  },
+  auth: {
+    enabled: false,
+    credentials: [
+      {
+        accessKeyId: 'S3RVER',
+        secretAccessKey: 'S3RVER',
+      },
+    ],
+  },
+  cors: {
+    enabled: false,
+    allowedOrigins: ['*'],
+    allowedMethods: ['GET', 'POST', 'PUT', 'DELETE', 'HEAD', 'OPTIONS'],
+    allowedHeaders: ['*'],
+    exposedHeaders: ['ETag', 'x-amz-request-id', 'x-amz-version-id'],
+    maxAge: 86400,
+    allowCredentials: false,
+  },
+  logging: {
+    level: 'info',
+    format: 'text',
+    enabled: true,
+  },
+  limits: {
+    maxObjectSize: 5 * 1024 * 1024 * 1024, // 5GB
+    maxMetadataSize: 2048,
+    requestTimeout: 300000, // 5 minutes
+  },
+};
+
+/**
+ * Merge user config with defaults (deep merge)
+ */
+function mergeConfig(userConfig: ISmarts3Config): Required<ISmarts3Config> {
+  return {
+    server: {
+      ...DEFAULT_CONFIG.server!,
+      ...(userConfig.server || {}),
+    },
+    storage: {
+      ...DEFAULT_CONFIG.storage!,
+      ...(userConfig.storage || {}),
+    },
+    auth: {
+      ...DEFAULT_CONFIG.auth!,
+      ...(userConfig.auth || {}),
+    },
+    cors: {
+      ...DEFAULT_CONFIG.cors!,
+      ...(userConfig.cors || {}),
+    },
+    logging: {
+      ...DEFAULT_CONFIG.logging!,
+      ...(userConfig.logging || {}),
+    },
+    limits: {
+      ...DEFAULT_CONFIG.limits!,
+      ...(userConfig.limits || {}),
+    },
+  };
+}
+
+/**
+ * Main Smarts3 class - production-ready S3-compatible server
+ */
 export class Smarts3 {
   // STATIC
-  public static async createAndStart(
-    optionsArg: ConstructorParameters<typeof Smarts3>[0],
-  ) {
-    const smartS3Instance = new Smarts3(optionsArg);
+  public static async createAndStart(configArg: ISmarts3Config = {}) {
+    const smartS3Instance = new Smarts3(configArg);
     await smartS3Instance.start();
     return smartS3Instance;
   }
 
   // INSTANCE
-  public options: ISmarts3ContructorOptions;
+  public config: Required<ISmarts3Config>;
   public s3Instance: Smarts3Server;
 
-  constructor(optionsArg: ISmarts3ContructorOptions) {
-    this.options = optionsArg;
+  constructor(configArg: ISmarts3Config = {}) {
+    this.config = mergeConfig(configArg);
   }
 
   public async start() {
     this.s3Instance = new Smarts3Server({
-      port: this.options.port || 3000,
-      address: '0.0.0.0',
-      directory: paths.bucketsDir,
-      cleanSlate: this.options.cleanSlate || false,
-      silent: false,
+      port: this.config.server.port,
+      address: this.config.server.address,
+      directory: this.config.storage.directory,
+      cleanSlate: this.config.storage.cleanSlate,
+      silent: this.config.server.silent,
+      config: this.config, // Pass full config to server
     });
     await this.s3Instance.start();
-    console.log('s3 server is running');
+
+    if (!this.config.server.silent) {
+      console.log('s3 server is running');
+    }
   }
 
   public async getS3Descriptor(
@@ -48,11 +194,9 @@ export class Smarts3 {
   }
 
   public async createBucket(bucketNameArg: string) {
-    const smartbucketInstance = new plugins.smartbucket.SmartBucket(
-      await this.getS3Descriptor(),
-    );
-    const bucket = await smartbucketInstance.createBucket(bucketNameArg);
-    return bucket;
+    // Call the filesystem store directly instead of using the client library
+    await this.s3Instance.store.createBucket(bucketNameArg);
+    return { name: bucketNameArg };
   }
 
   public async stop() {

ts/plugins.ts

@@ -3,17 +3,18 @@ import * as path from 'path';
 import * as http from 'http';
 import * as crypto from 'crypto';
 import * as url from 'url';
-import * as fs from 'fs';
 
-export { path, http, crypto, url, fs };
+export { path, http, crypto, url };
 
 // @push.rocks scope
-import * as smartbucket from '@push.rocks/smartbucket';
-import * as smartfile from '@push.rocks/smartfile';
+import { SmartFs, SmartFsProviderNode } from '@push.rocks/smartfs';
 import * as smartpath from '@push.rocks/smartpath';
 import { SmartXml } from '@push.rocks/smartxml';
 
-export { smartbucket, smartfile, smartpath, SmartXml };
+// Create SmartFs instance with Node.js provider
+export const smartfs = new SmartFs(new SmartFsProviderNode());
+
+export { smartpath, SmartXml };
 
 // @tsclass scope
 import * as tsclass from '@tsclass/tsclass';