s3broker 0.0.1 → 0.4.3

package/README.md

@@ -0,0 +1,87 @@
+# 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.
+
+This is a work in progress. More guardrails and features would be added soon.
+
+## Overview
+
+S3Broker is a TypeScript library for building proxies and guardrails for S3-compatible storage. The library is intended to be used on Cloudflare Workers.
+
+When you have an S3 secret key with read/write access, any client using that key can perform destructive operations. Your data is vulnerable to:
+
+- **Accidental deletion** by users or misconfigured tools
+- **Ransomware attacks** that encrypt or delete your files
+
+S3Broker acts as a protective layer between your clients and the upstream S3 endpoint. Instead of giving clients direct access to your upstream key (Key B), you give them a different key (Key A). S3Broker validates every request against configurable guardrails and blocks dangerous operations before they reach your storage.
+
+```
+==========              ============             ============
+||Client|| -- Key A --> ||S3Broker|| -- Key B --> ||Upstream||
+==========              ============             ============
+```
+
+## 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.3",
 	"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)