feat(auth): add AWS SigV4 authentication and bucket policy support

readme.md

@@ -16,7 +16,8 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 | Range requests | ✅ Seek-based | ✅ | ❌ Full read |
 | Language | Rust + TypeScript | Go | JavaScript |
 | Multipart uploads | ✅ Full support | ✅ | ❌ |
-| Auth | AWS v2/v4 key extraction | Full IAM | Basic |
+| Auth | ✅ AWS SigV4 (full verification) | Full IAM | Basic |
+| Bucket policies | ✅ IAM-style evaluation | ✅ | ❌ |
 
 ### Core Features
 
@@ -25,7 +26,8 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - 📂 **Filesystem-backed storage** — buckets map to directories, objects to files
 - 📤 **Streaming multipart uploads** — large files without memory pressure
 - 🎯 **Byte-range requests** — `seek()` directly to the requested byte offset
-- 🔐 **Authentication** — AWS v2/v4 signature key extraction
+- 🔐 **AWS SigV4 authentication** — full signature verification with constant-time comparison and 15-min clock skew enforcement
+- 📜 **Bucket policies** — IAM-style JSON policies with Allow/Deny evaluation, wildcard matching, and anonymous access support
 - 🌐 **CORS middleware** — configurable cross-origin support
 - 📊 **Structured logging** — tracing-based, error through debug levels
 - 🧹 **Clean slate mode** — wipe storage on startup for test isolation
@@ -73,6 +75,7 @@ const config: ISmarts3Config = {
     port: 3000,              // Default: 3000
     address: '0.0.0.0',      // Default: '0.0.0.0'
     silent: false,           // Default: false
+    region: 'us-east-1',    // Default: 'us-east-1' — used for SigV4 signing
   },
   storage: {
     directory: './my-data',  // Default: .nogit/bucketsDir
@@ -241,6 +244,56 @@ await client.send(new CompleteMultipartUploadCommand({
 }));
 ```
 
+## 📜 Bucket Policies
+
+smarts3 supports AWS-style bucket policies for fine-grained access control. Policies use the same IAM JSON format as real S3 — so you can develop and test your policy logic locally before deploying.
+
+When `auth.enabled` is `true`, the auth pipeline works as follows:
+1. **Authenticate** — verify the AWS SigV4 signature (anonymous requests skip this step)
+2. **Authorize** — evaluate bucket policies against the request action, resource, and caller identity
+3. **Default** — authenticated users get full access; anonymous requests are denied unless a policy explicitly allows them
+
+### Setting a Bucket Policy
+
+Use the S3 `PutBucketPolicy` API (or any S3 client that supports it):
+
+```typescript
+import { PutBucketPolicyCommand } from '@aws-sdk/client-s3';
+
+// Allow anonymous read access to all objects in a bucket
+await client.send(new PutBucketPolicyCommand({
+  Bucket: 'public-assets',
+  Policy: JSON.stringify({
+    Version: '2012-10-17',
+    Statement: [{
+      Sid: 'PublicRead',
+      Effect: 'Allow',
+      Principal: '*',
+      Action: ['s3:GetObject'],
+      Resource: ['arn:aws:s3:::public-assets/*'],
+    }],
+  }),
+}));
+```
+
+### Policy Features
+
+- **Effect**: `Allow` and `Deny` (explicit Deny always wins)
+- **Principal**: `"*"` (everyone) or `{ "AWS": ["arn:..."] }` for specific identities
+- **Action**: IAM-style actions like `s3:GetObject`, `s3:PutObject`, `s3:*`, or prefix wildcards like `s3:Get*`
+- **Resource**: ARN patterns with `*` and `?` wildcards (e.g. `arn:aws:s3:::my-bucket/*`)
+- **Persistence**: Policies survive server restarts — stored as JSON on disk alongside your data
+
+### Policy CRUD Operations
+
+| Operation | AWS SDK Command | HTTP |
+|-----------|----------------|------|
+| Get policy | `GetBucketPolicyCommand` | `GET /{bucket}?policy` |
+| Set policy | `PutBucketPolicyCommand` | `PUT /{bucket}?policy` |
+| Delete policy | `DeleteBucketPolicyCommand` | `DELETE /{bucket}?policy` |
+
+Deleting a bucket automatically removes its associated policy.
+
 ## 🧪 Testing Integration
 
 ```typescript
@@ -314,7 +367,8 @@ smarts3 uses a **hybrid Rust + TypeScript** architecture:
 │  ├─ S3 path-style routing      │
 │  ├─ Streaming storage layer    │
 │  ├─ Multipart manager          │
-│  ├─ CORS / Auth middleware     │
+│  ├─ SigV4 auth + policy engine │
+│  ├─ CORS middleware            │
 │  └─ S3 XML response builder   │
 ├─────────────────────────────────┤
 │  TypeScript (thin IPC wrapper)  │
@@ -347,6 +401,9 @@ smarts3 uses a **hybrid Rust + TypeScript** architecture:
 | CompleteMultipartUpload | `POST /{bucket}/{key}?uploadId` | |
 | AbortMultipartUpload | `DELETE /{bucket}/{key}?uploadId` | |
 | ListMultipartUploads | `GET /{bucket}?uploads` | |
+| GetBucketPolicy | `GET /{bucket}?policy` | |
+| PutBucketPolicy | `PUT /{bucket}?policy` | |
+| DeleteBucketPolicy | `DELETE /{bucket}?policy` | |
 
 ### On-Disk Format
 
@@ -362,6 +419,8 @@ smarts3 uses a **hybrid Rust + TypeScript** architecture:
       part-1                      # Part data files
       part-2
       ...
+  .policies/
+    {bucket}.policy.json          # Bucket policy (IAM JSON format)
 ```
 
 ## 🔗 Related Packages