s3broker 0.0.1 → 0.4.2

package/README.md

@@ -0,0 +1,85 @@
+# S3Broker
+
+[![npm version](https://img.shields.io/npm/v/s3broker.svg)](https://www.npmjs.com/package/s3broker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Cloudflare Workers library for building S3 proxies with guardrails.
+
+## Overview
+
+S3Broker is a TypeScript library for building proxies and guardrails for S3-compatible storage. It sits between your S3 clients and your S3-compatible storage, providing dual-key authentication and policy-based guardrails:
+
+```
+==========              ============             ============
+||Client|| -- Key A --> ||S3Broker|| -- Key B --> ||Upstream||
+==========              ============             ============
+```
+
+**Key Features:**
+
+- **Two-Key Authentication**: Clients authenticate with Key A; S3Broker re-signs requests with Key B for the upstream
+- **Guardrails Framework**: Configurable policies to protect your data (e.g., prevent deletion of recently created objects)
+- **Full S3 Compatibility**: Works with any S3 client (AWS SDK, s3cmd, rclone, etc.)
+- **Cloudflare Workers**: Built for Cloudflare Workers runtime
+
+## Installation
+
+```bash
+npm install s3broker
+```
+
+## Quick Start
+
+```typescript
+import { handle } from 's3broker';
+
+export default {
+	async fetch(request, env, ctx) {
+		return handle(request, {
+			s3Endpoint: env.S3_ENDPOINT,
+			clientAccessKeyId: env.CLIENT_ACCESS_KEY_ID,
+			clientSecretAccessKey: env.CLIENT_SECRET_ACCESS_KEY,
+			upstreamAccessKeyId: env.UPSTREAM_ACCESS_KEY_ID,
+			upstreamSecretAccessKey: env.UPSTREAM_SECRET_ACCESS_KEY,
+		});
+	},
+};
+```
+
+## With Custom Guardrails
+
+```typescript
+import { handle } from 's3broker';
+
+export default {
+	async fetch(request, env, ctx) {
+		return handle(request, {
+			s3Endpoint: env.S3_ENDPOINT,
+			clientAccessKeyId: env.CLIENT_ACCESS_KEY_ID,
+			clientSecretAccessKey: env.CLIENT_SECRET_ACCESS_KEY,
+			upstreamAccessKeyId: env.UPSTREAM_ACCESS_KEY_ID,
+			upstreamSecretAccessKey: env.UPSTREAM_SECRET_ACCESS_KEY,
+			guardrailConfig: {
+				noDeleteOld: [
+					{
+						pattern: '/protected/.*',
+						config: { noDeleteBeforeSeconds: 3600 }, // Files older than 1h in /protected/ could not be deleted
+					},
+				],
+			},
+		});
+	},
+};
+```
+
+## Limitations
+
+- **`STREAMING-AWS4-HMAC-SHA256-PAYLOAD`** payload signing method is not supported.
+
+## Documentation
+
+For full documentation, see the [GitHub repository](https://github.com/tsunrise/s3broker).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "s3broker",
-	"version": "0.0.1",
+	"version": "0.4.2",
 	"description": "S3 proxy library with SigV4 verification and configurable guardrails policies",
 	"main": "src/index.ts",
 	"types": "src/index.ts",
@@ -21,8 +21,12 @@
 		"zod": "^4.2.1"
 	},
 	"devDependencies": {
-		"@cloudflare/workers-types": "^4.20241230.0",
-		"typescript": "^5.5.2"
+		"typescript": "^5.5.2",
+		"@cloudflare/workers-types": "^4.1.1"
 	},
-	"author": "Tom Shen"
+	"author": "Tom Shen",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/tsunrise/s3broker"
+	}
 }

package/src/index.ts

@@ -1,14 +1,11 @@
 /**
- * S3Broker - S3 Proxy Library with SigV4 Verification and Guardrails
+ * S3Broker - S3 Proxy Library for Cloudflare Workers
  *
  * ==========              ===========             ============
  * ||Client|| -- Key A --> ||S3Broker|| -- Key B --> ||Upstream||
  * ==========              ===========             ============
  *
- * S3Broker is a library for building secure S3-compatible proxies. It can be used in:
- * - Cloudflare Workers
- * - Any other serverless platforms (Vercel, Netlify, etc.)
- * - Any JavaScript/TypeScript runtime with fetch API support
+ * S3Broker is a Cloudflare Workers library for building secure S3-compatible proxies.
  *
  * Features:
  * 1. Verifies incoming requests signed with Key A (client credentials)
@@ -97,7 +94,6 @@ export const defaultGuardrailConfig: GuardrailConfig = {
  * Handle an incoming S3 request with signature verification, guardrails, and proxying.
  *
  * @param request - The incoming HTTP request (must be a valid S3 API request)
- * @param _ctx - Execution context (unused, reserved for future use)
  * @param options - S3Broker configuration options including credentials and guardrails
  * @returns Response from the upstream S3 service, or an error response if validation fails
  *
@@ -114,11 +110,7 @@ export const defaultGuardrailConfig: GuardrailConfig = {
  * });
  * ```
  */
-export async function handle(
-	request: Request<unknown, IncomingRequestCfProperties>,
-	_ctx: ExecutionContext,
-	options: S3BrokerOptions,
-): Promise<Response> {
+export async function handle(request: Request<unknown, IncomingRequestCfProperties>, options: S3BrokerOptions): Promise<Response> {
 	const currentTimestamp = Date.now();
 
 	// Verify the incoming request signature (Client Key)