s3broker 0.0.1

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "s3broker",
+	"version": "0.0.1",
+	"description": "S3 proxy library with SigV4 verification and configurable guardrails policies",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"typecheck": "tsc --noEmit"
+	},
+	"keywords": [
+		"s3",
+		"proxy",
+		"sigv4",
+		"aws",
+		"guardrails",
+		"security"
+	],
+	"license": "MIT",
+	"dependencies": {
+		"aws4fetch": "^1.0.20",
+		"zod": "^4.2.1"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-types": "^4.20241230.0",
+		"typescript": "^5.5.2"
+	},
+	"author": "Tom Shen"
+}

package/src/guardrails/guardrails.ts

@@ -0,0 +1,90 @@
+import { AwsClient } from 'aws4fetch';
+import { GuardrailConfig, GuardrailPolicy, GuardrailViolation, UpstreamError } from './type';
+import { NoDeleteOldPolicy } from './no-delete-old';
+
+/**
+ * Evaluate guardrails for a given request
+ * @param request The incoming request
+ * @param config The guardrail configuration to use
+ * @returns The first guardrail violation if the request violates a policy, null otherwise
+ */
+export async function evaluateGuardrails(
+	request: Request<unknown, IncomingRequestCfProperties>,
+	upstreamFetcher: AwsClient,
+	s3_endpoint: string,
+	currentTimestampMs: number,
+	config: GuardrailConfig,
+): Promise<(GuardrailViolation & { policy: string }) | null> {
+	const path = new URL(request.url).pathname;
+	const policies = getPolicies(config, path, upstreamFetcher, s3_endpoint, currentTimestampMs);
+
+	if (policies.length === 0) {
+		return null;
+	}
+
+	// Create evaluation promises that include policy name
+	const evalPromises = policies.map(({ name: policyName, policy }) => ({
+		policyName,
+		promise: (async () => {
+			const violation = await policy.evaluate(request);
+			return violation ? { ...violation, policy: policyName } : null;
+		})(),
+	}));
+
+	// Race until one returns a violation or all are done
+	// Using Promise.race with a filter pattern to get first non-null result
+	return new Promise((resolve) => {
+		let pendingCount = evalPromises.length;
+
+		for (const { policyName, promise } of evalPromises) {
+			promise
+				.then((result) => {
+					if (result !== null) {
+						// First violation wins
+						resolve(result);
+					} else {
+						pendingCount--;
+						if (pendingCount === 0) {
+							// All policies passed
+							resolve(null);
+						}
+					}
+				})
+				.catch((error) => {
+					// If a policy throws, treat it as a violation
+					let message = error instanceof Error ? error.message : String(error);
+					if (error instanceof UpstreamError) {
+						message = `Error calling upstream when evaluating guardrail: ${message}`;
+					}
+					resolve({ violation: message, policy: policyName });
+				});
+		}
+	});
+}
+
+/**
+ * Get all applicable policies for a given path
+ */
+export function getPolicies(
+	config: GuardrailConfig,
+	path: string,
+	upstreamFetcher: AwsClient,
+	upstreamEndpoint: string,
+	currentTimestampMs: number,
+): { name: string; policy: GuardrailPolicy }[] {
+	const policies: { name: string; policy: GuardrailPolicy }[] = [];
+
+	// Check noDeleteOld policies - first matching pattern wins
+	for (const entry of config.noDeleteOld) {
+		const regex = new RegExp(entry.pattern);
+		if (regex.test(path)) {
+			policies.push({
+				name: 'noDeleteOld',
+				policy: new NoDeleteOldPolicy(entry.config, upstreamFetcher, upstreamEndpoint, currentTimestampMs),
+			});
+			break; // First match wins
+		}
+	}
+
+	return policies;
+}

package/src/guardrails/no-delete-old.ts

@@ -0,0 +1,63 @@
+import { GuardrailPolicy, GuardrailViolation, UpstreamError } from './type';
+import { z } from 'zod';
+import { AwsClient } from 'aws4fetch';
+import { getObjectMetadata } from './s3_helper';
+
+export const NoDeleteOldPolicyConfig = z.object({
+	noDeleteBeforeSeconds: z.number().int(),
+});
+
+export type NoDeleteOldPolicyConfig = z.infer<typeof NoDeleteOldPolicyConfig>;
+
+export class NoDeleteOldPolicy implements GuardrailPolicy {
+	private config: NoDeleteOldPolicyConfig;
+	private upstreamFetcher: AwsClient;
+	private upstreamEndpoint: string;
+	private currentTimestampMs: number;
+
+	constructor(config: NoDeleteOldPolicyConfig, upstreamFetcher: AwsClient, upstreamEndpoint: string, currentTimestampMs: number) {
+		this.config = config;
+		this.upstreamFetcher = upstreamFetcher;
+		this.upstreamEndpoint = upstreamEndpoint;
+		this.currentTimestampMs = currentTimestampMs;
+	}
+
+	async evaluate(request: Request<unknown, IncomingRequestCfProperties>): Promise<GuardrailViolation | null> {
+		// Only applies to DELETE requests
+		if (request.method !== 'DELETE') {
+			return null;
+		}
+
+		const url = new URL(request.url);
+		const objectPath = this.upstreamEndpoint + url.pathname;
+
+		try {
+			const headers = await getObjectMetadata(this.upstreamFetcher, objectPath);
+
+			// Get the Last-Modified header to determine object age
+			const lastModified = headers.get('Last-Modified');
+			if (!lastModified) {
+				// If no Last-Modified header, allow deletion (object might be newly created)
+				return null;
+			}
+
+			const objectCreatedAtMs = new Date(lastModified).getTime();
+			const objectAgeMs = this.currentTimestampMs - objectCreatedAtMs;
+			const thresholdMs = this.config.noDeleteBeforeSeconds * 1000;
+
+			if (objectAgeMs > thresholdMs) {
+				return {
+					violation: `Cannot delete object: object is ${Math.floor(objectAgeMs / 1000)} seconds old, which exceeds the ${this.config.noDeleteBeforeSeconds} seconds threshold`,
+				};
+			}
+
+			return null;
+		} catch (error) {
+			if (error instanceof UpstreamError && error.code === '404') {
+				// Object doesn't exist, allow deletion attempt (will fail at upstream)
+				return null;
+			}
+			throw error;
+		}
+	}
+}

package/src/guardrails/s3_helper.ts

@@ -0,0 +1,16 @@
+import { AwsClient } from 'aws4fetch';
+import { UpstreamError } from './type';
+/**
+ * Issue a `HEAD` request to retrieve object metadata
+ * @param upstream
+ * @param objectPath
+ */
+export async function getObjectMetadata(upstream: AwsClient, objectPath: string): Promise<Headers> {
+	const response = await upstream.fetch(objectPath, {
+		method: 'HEAD',
+	});
+	if (!response.ok) {
+		throw new UpstreamError(response.status.toString(), response.statusText);
+	}
+	return response.headers;
+}

package/src/guardrails/type.ts

@@ -0,0 +1,36 @@
+import { z, ZodType } from 'zod';
+import { NoDeleteOldPolicyConfig } from './no-delete-old';
+
+export interface GuardrailPolicy {
+	evaluate(request: Request<unknown, IncomingRequestCfProperties>): Promise<GuardrailViolation | null>;
+}
+
+export type GuardrailViolation = {
+	violation: string;
+};
+
+/*
+ * Corresponding config for each object path pattern in regex. First match wins.
+ */
+export const GuardrailPolicyConfigPerPattern = <T extends ZodType>(policy: T) =>
+	z.array(
+		z.object({
+			pattern: z.string(),
+			config: policy,
+		}),
+	);
+export const GuardrailConfig = z.object({
+	noDeleteOld: GuardrailPolicyConfigPerPattern(NoDeleteOldPolicyConfig),
+});
+export type GuardrailConfig = z.infer<typeof GuardrailConfig>;
+
+/**
+ * Error calling upstream when evaluating guardrails
+ */
+export class UpstreamError extends Error {
+	code: string;
+	constructor(code: string, message: string) {
+		super(message);
+		this.code = code;
+	}
+}

package/src/index.ts

@@ -0,0 +1,205 @@
+/**
+ * S3Broker - S3 Proxy Library with SigV4 Verification and Guardrails
+ *
+ * ==========              ===========             ============
+ * ||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
+ *
+ * Features:
+ * 1. Verifies incoming requests signed with Key A (client credentials)
+ * 2. Enforces configurable guardrails policies (e.g., prevent deletion of recent objects)
+ * 3. Re-signs requests with Key B (upstream credentials) for the upstream S3 service
+ * 4. Proxies the request to any S3-compatible endpoint (AWS S3, Cloudflare R2, MinIO, etc.)
+ */
+
+import { AwsClient } from 'aws4fetch';
+import { verifySignature } from './sigv4';
+import { textErrorResponse, ErrorCode } from './utils';
+import { evaluateGuardrails } from './guardrails/guardrails';
+import type { S3BrokerOptions } from './types';
+import { GuardrailConfig } from './guardrails/type';
+
+// Re-export types
+export type { S3BrokerOptions } from './types';
+export type { GuardrailConfig, GuardrailViolation } from './guardrails/type';
+
+// Headers that should be forwarded to upstream (allowlist approach)
+const HEADERS_TO_INCLUDE = new Set([
+	// S3-specific headers
+	'x-amz-date',
+	'x-amz-content-sha256',
+	'x-amz-security-token',
+	'x-amz-server-side-encryption',
+	'x-amz-server-side-encryption-aws-kms-key-id',
+	'x-amz-server-side-encryption-customer-algorithm',
+	'x-amz-server-side-encryption-customer-key',
+	'x-amz-server-side-encryption-customer-key-md5',
+	'x-amz-storage-class',
+	'x-amz-tagging',
+	'x-amz-website-redirect-location',
+	'x-amz-acl',
+	'x-amz-grant-read',
+	'x-amz-grant-write',
+	'x-amz-grant-read-acp',
+	'x-amz-grant-write-acp',
+	'x-amz-grant-full-control',
+	'x-amz-metadata-directive',
+	'x-amz-copy-source',
+	'x-amz-copy-source-if-match',
+	'x-amz-copy-source-if-none-match',
+	'x-amz-copy-source-if-unmodified-since',
+	'x-amz-copy-source-if-modified-since',
+	'x-amz-copy-source-range',
+	// Standard HTTP headers that S3 uses
+	'content-type',
+	'content-length',
+	'content-md5',
+	'content-encoding',
+	'content-disposition',
+	'cache-control',
+	'expires',
+	'range',
+	'if-match',
+	'if-none-match',
+	'if-modified-since',
+	'if-unmodified-since',
+	'user-agent',
+]);
+
+// Presigned URL parameters that should be stripped when re-signing
+const PRESIGNED_PARAMS = new Set([
+	'X-Amz-Algorithm',
+	'X-Amz-Credential',
+	'X-Amz-Date',
+	'X-Amz-Expires',
+	'X-Amz-SignedHeaders',
+	'X-Amz-Signature',
+	'X-Amz-Security-Token',
+]);
+
+export const defaultGuardrailConfig: GuardrailConfig = {
+	noDeleteOld: [
+		{
+			pattern: '/.*',
+			config: {
+				noDeleteBeforeSeconds: 60,
+			},
+		},
+	],
+};
+
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { handle } from 's3broker';
+ *
+ * const response = await handle(request, ctx, {
+ *   s3Endpoint: 'https://my-bucket.s3.amazonaws.com',
+ *   clientAccessKeyId: 'CLIENT_KEY',
+ *   clientSecretAccessKey: 'CLIENT_SECRET',
+ *   upstreamAccessKeyId: 'UPSTREAM_KEY',
+ *   upstreamSecretAccessKey: 'UPSTREAM_SECRET',
+ * });
+ * ```
+ */
+export async function handle(
+	request: Request<unknown, IncomingRequestCfProperties>,
+	_ctx: ExecutionContext,
+	options: S3BrokerOptions,
+): Promise<Response> {
+	const currentTimestamp = Date.now();
+
+	// Verify the incoming request signature (Client Key)
+	const verificationResult = await verifySignature(request, options.clientSecretAccessKey, options.clientAccessKeyId, currentTimestamp);
+
+	if (!verificationResult.valid) {
+		return textErrorResponse(`Signature verification failed: ${verificationResult.error}`, ErrorCode.Forbidden);
+	}
+
+	// Parse the request URL
+	const url = new URL(request.url);
+
+	// Evaluate guardrails
+	const guardrailUpstreamClient = new AwsClient({
+		accessKeyId: options.upstreamAccessKeyId,
+		secretAccessKey: options.upstreamSecretAccessKey,
+		retries: 5,
+	});
+
+	const guardrailViolation = await evaluateGuardrails(
+		request,
+		guardrailUpstreamClient,
+		options.s3Endpoint,
+		currentTimestamp,
+		options.guardrailConfig || defaultGuardrailConfig,
+	);
+
+	if (guardrailViolation) {
+		console.log(`Guardrail violation`, {
+			path: url.pathname,
+			method: request.method,
+			query: url.search,
+			policy: guardrailViolation.policy,
+			violation: guardrailViolation.violation,
+		});
+		return textErrorResponse(
+			`Request violating guardrail policy ${guardrailViolation.policy}: ${guardrailViolation.violation}`,
+			ErrorCode.Forbidden,
+		);
+	}
+
+	// Build upstream URL, stripping presigned parameters
+	const upstreamUrl = new URL(url.pathname, options.s3Endpoint);
+	for (const [key, value] of url.searchParams.entries()) {
+		if (!PRESIGNED_PARAMS.has(key)) {
+			upstreamUrl.searchParams.set(key, value);
+		}
+	}
+
+	// Build upstream headers (allowlist approach)
+	const upstreamHeaders = new Headers();
+	for (const [key, value] of request.headers.entries()) {
+		if (HEADERS_TO_INCLUDE.has(key.toLowerCase())) {
+			upstreamHeaders.set(key, value);
+		}
+	}
+	upstreamHeaders.set('x-amz-content-sha256', 'UNSIGNED-PAYLOAD');
+
+	// Create upstream request
+	const upstreamRequest = new Request(upstreamUrl.toString(), {
+		method: request.method,
+		headers: upstreamHeaders,
+		body: request.body,
+		// @ts-ignore - duplex is needed for streaming bodies
+		duplex: 'half',
+	});
+
+	// Sign and send to upstream
+	const proxyUpstreamAws = new AwsClient({
+		accessKeyId: options.upstreamAccessKeyId,
+		secretAccessKey: options.upstreamSecretAccessKey,
+		retries: 0,
+	});
+
+	try {
+		return await proxyUpstreamAws.fetch(upstreamRequest);
+	} catch (error) {
+		console.error('Upstream request failed:', error);
+		return textErrorResponse(
+			`Upstream request failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+			ErrorCode.UpstreamFailure,
+		);
+	}
+}

package/src/sigv4.ts

@@ -0,0 +1,352 @@
+/**
+ * AWS Signature Version 4 verification utilities
+ *
+ * This module provides functions to verify incoming S3 requests signed with SigV4.
+ * It parses the Authorization header, reconstructs the canonical request, and
+ * verifies the signature matches what we expect.
+ */
+
+interface SigV4Params {
+	algorithm: string;
+	credential: {
+		accessKeyId: string;
+		date: string;
+		region: string;
+		service: string;
+	};
+	signedHeaders: string[];
+	signature: string;
+	// Presigned URL specific
+	expires?: number;
+	isPresigned?: boolean;
+}
+
+/**
+ * Check if request uses presigned URL authentication
+ */
+export function isPresignedUrl(request: Request): boolean {
+	const url = new URL(request.url);
+	return url.searchParams.has('X-Amz-Signature');
+}
+
+/**
+ * Parse presigned URL query parameters
+ * Query params: X-Amz-Algorithm, X-Amz-Credential, X-Amz-Date, X-Amz-Expires, X-Amz-SignedHeaders, X-Amz-Signature
+ */
+export function parsePresignedUrl(request: Request): SigV4Params {
+	const url = new URL(request.url);
+
+	const algorithm = url.searchParams.get('X-Amz-Algorithm');
+	const credential = url.searchParams.get('X-Amz-Credential');
+	const signedHeaders = url.searchParams.get('X-Amz-SignedHeaders');
+	const signature = url.searchParams.get('X-Amz-Signature');
+	const expires = url.searchParams.get('X-Amz-Expires');
+
+	if (!algorithm || algorithm !== 'AWS4-HMAC-SHA256') {
+		throw new Error('Invalid or missing X-Amz-Algorithm');
+	}
+	if (!credential || !signedHeaders || !signature) {
+		throw new Error('Missing required presigned URL parameters');
+	}
+
+	// Parse credential: accessKeyId/date/region/service/aws4_request
+	const credentialParts = credential.split('/');
+	if (credentialParts.length !== 5 || credentialParts[4] !== 'aws4_request') {
+		throw new Error('Invalid credential format in presigned URL');
+	}
+
+	return {
+		algorithm: 'AWS4-HMAC-SHA256',
+		credential: {
+			accessKeyId: credentialParts[0],
+			date: credentialParts[1],
+			region: credentialParts[2],
+			service: credentialParts[3],
+		},
+		signedHeaders: signedHeaders.split(';'),
+		signature: signature,
+		expires: expires ? parseInt(expires, 10) : undefined,
+		isPresigned: true,
+	};
+}
+
+/**
+ * Parse the AWS SigV4 Authorization header
+ * Format: AWS4-HMAC-SHA256 Credential=AKID/20231224/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=...
+ */
+export function parseAuthorizationHeader(authHeader: string): SigV4Params {
+	if (!authHeader.startsWith('AWS4-HMAC-SHA256 ')) {
+		throw new Error('Invalid authorization header: must start with AWS4-HMAC-SHA256');
+	}
+
+	// Split by comma and trim whitespace to handle both "key=value, key=value" and "key=value,key=value"
+	const parts = authHeader
+		.substring('AWS4-HMAC-SHA256 '.length)
+		.split(',')
+		.map((p) => p.trim());
+	const params: Record<string, string> = {};
+
+	for (const part of parts) {
+		const [key, value] = part.split('=', 2);
+		params[key] = value;
+	}
+
+	if (!params.Credential || !params.SignedHeaders || !params.Signature) {
+		throw new Error('Missing required authorization parameters');
+	}
+
+	// Parse credential: accessKeyId/date/region/service/aws4_request
+	const credentialParts = params.Credential.split('/');
+	if (credentialParts.length !== 5 || credentialParts[4] !== 'aws4_request') {
+		throw new Error('Invalid credential format');
+	}
+
+	return {
+		algorithm: 'AWS4-HMAC-SHA256',
+		credential: {
+			accessKeyId: credentialParts[0],
+			date: credentialParts[1],
+			region: credentialParts[2],
+			service: credentialParts[3],
+		},
+		signedHeaders: params.SignedHeaders.split(';'),
+		signature: params.Signature,
+		isPresigned: false,
+	};
+}
+
+/**
+ * Build the canonical request from the incoming request
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html
+ *
+ * @param isPresigned - If true, exclude X-Amz-Signature from query string
+ */
+export async function buildCanonicalRequest(
+	request: Request,
+	signedHeaders: string[],
+	hashedPayload: string,
+	isPresigned: boolean = false,
+): Promise<string> {
+	const url = new URL(request.url);
+	const httpMethod = request.method;
+
+	// Canonical URI (path)
+	const canonicalUri = url.pathname || '/';
+
+	// Canonical query string (sorted, exclude X-Amz-Signature for presigned URLs)
+	const canonicalQueryString = Array.from(url.searchParams.entries())
+		.filter(([key]) => !isPresigned || key !== 'X-Amz-Signature')
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+		.join('&');
+
+	// Canonical headers (lowercase, sorted, trimmed)
+	const headers: Record<string, string> = {};
+	for (const headerName of signedHeaders) {
+		const value = request.headers.get(headerName);
+		if (value !== null) {
+			headers[headerName.toLowerCase()] = value.trim();
+		}
+	}
+
+	const canonicalHeaders = signedHeaders.map((name) => `${name.toLowerCase()}:${headers[name.toLowerCase()] || ''}\n`).join('');
+
+	const canonicalSignedHeaders = signedHeaders.map((h) => h.toLowerCase()).join(';');
+
+	// Combine into canonical request
+	return [httpMethod, canonicalUri, canonicalQueryString, canonicalHeaders, canonicalSignedHeaders, hashedPayload].join('\n');
+}
+
+/**
+ * Create the string to sign
+ * https://docs.aws.amazon.com/general/latest/gr/sigv4-create-string-to-sign.html
+ */
+export async function createStringToSign(
+	algorithm: string,
+	requestDate: string,
+	credentialScope: string,
+	canonicalRequest: string,
+): Promise<string> {
+	const encoder = new TextEncoder();
+	const canonicalRequestHash = await crypto.subtle.digest('SHA-256', encoder.encode(canonicalRequest));
+	const canonicalRequestHashHex = Array.from(new Uint8Array(canonicalRequestHash))
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('');
+
+	return [algorithm, requestDate, credentialScope, canonicalRequestHashHex].join('\n');
+}
+
+/**
+ * Derive the signing key
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html
+ */
+export async function deriveSigningKey(secretKey: string, date: string, region: string, service: string): Promise<ArrayBuffer> {
+	const encoder = new TextEncoder();
+
+	const kDate = await hmacSha256(encoder.encode('AWS4' + secretKey), encoder.encode(date));
+	const kRegion = await hmacSha256(kDate, encoder.encode(region));
+	const kService = await hmacSha256(kRegion, encoder.encode(service));
+	const kSigning = await hmacSha256(kService, encoder.encode('aws4_request'));
+
+	return kSigning;
+}
+
+/**
+ * HMAC-SHA256 helper
+ */
+async function hmacSha256(key: ArrayBuffer | Uint8Array, data: Uint8Array): Promise<ArrayBuffer> {
+	const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+	return crypto.subtle.sign('HMAC', cryptoKey, data);
+}
+
+/**
+ * Calculate the signature
+ */
+export async function calculateSignature(signingKey: ArrayBuffer, stringToSign: string): Promise<string> {
+	const encoder = new TextEncoder();
+	const signature = await hmacSha256(signingKey, encoder.encode(stringToSign));
+	return Array.from(new Uint8Array(signature))
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('');
+}
+
+/**
+ * Constant-time string comparison using crypto.subtle.timingSafeEqual
+ * Prevents timing attacks on signature comparison
+ */
+async function constantTimeCompare(a: string, b: string): Promise<boolean> {
+	if (a.length !== b.length) return false;
+
+	const encoder = new TextEncoder();
+	const aBytes = encoder.encode(a);
+	const bBytes = encoder.encode(b);
+
+	try {
+		return await crypto.subtle.timingSafeEqual(aBytes, bBytes);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Parse AWS date format (YYYYMMDDTHHMMSSZ) to timestamp (ms)
+ */
+function parseAmzDate(dateStr: string): number {
+	const year = parseInt(dateStr.substring(0, 4));
+	const month = parseInt(dateStr.substring(4, 6)) - 1;
+	const day = parseInt(dateStr.substring(6, 8));
+	const hour = parseInt(dateStr.substring(9, 11));
+	const minute = parseInt(dateStr.substring(11, 13));
+	const second = parseInt(dateStr.substring(13, 15));
+	return Date.UTC(year, month, day, hour, minute, second);
+}
+
+/**
+ * Verify the signature of an incoming request
+ * Supports both Authorization header and presigned URL authentication
+ */
+export async function verifySignature(
+	request: Request,
+	clientSecretKey: string,
+	expectedAccessKeyId: string,
+	currentTimestampMs: number,
+): Promise<{ valid: boolean; error?: string; isPresigned?: boolean }> {
+	try {
+		const url = new URL(request.url);
+		const authHeader = request.headers.get('Authorization');
+		const isPresigned = url.searchParams.has('X-Amz-Signature');
+
+		// Parse auth params from either header or query parameters
+		let params: SigV4Params;
+		if (isPresigned) {
+			params = parsePresignedUrl(request);
+		} else if (authHeader) {
+			params = parseAuthorizationHeader(authHeader);
+		} else {
+			return { valid: false, error: 'Missing authentication (no Authorization header or presigned URL parameters)' };
+		}
+
+		// Verify access key ID matches
+		if (params.credential.accessKeyId !== expectedAccessKeyId) {
+			return { valid: false, error: 'Access key ID mismatch' };
+		}
+
+		// Get request date early for both staleness and expiration checks
+		let requestDate: string | null;
+		if (isPresigned) {
+			requestDate = url.searchParams.get('X-Amz-Date');
+		} else {
+			requestDate = request.headers.get('x-amz-date');
+		}
+
+		if (!requestDate) {
+			return { valid: false, error: 'Missing request date (x-amz-date)' };
+		}
+
+		// Check request date staleness to prevent replay attacks
+		// For presigned URLs, expiration is checked separately below
+		if (!isPresigned) {
+			const requestDateMs = parseAmzDate(requestDate);
+			const MAX_CLOCK_SKEW_MS = 5 * 60 * 1000; // 5 minutes
+
+			if (Math.abs(currentTimestampMs - requestDateMs) > MAX_CLOCK_SKEW_MS) {
+				return { valid: false, error: 'Request date too old or in future (max 5 min clock skew)' };
+			}
+		}
+		// For presigned URLs, check expiration
+		else if (isPresigned && params.expires !== undefined) {
+			const requestDateMs = parseAmzDate(requestDate);
+			const expiresAt = requestDateMs + params.expires * 1000;
+
+			if (currentTimestampMs > expiresAt) {
+				return { valid: false, error: 'Presigned URL has expired' };
+			}
+		}
+
+		// Get the payload hash
+		let payloadHash: string;
+		if (isPresigned) {
+			// Presigned URLs always use UNSIGNED-PAYLOAD
+			payloadHash = 'UNSIGNED-PAYLOAD';
+		} else {
+			payloadHash = request.headers.get('x-amz-content-sha256') || 'UNSIGNED-PAYLOAD';
+		}
+
+		// Check for streaming payload (not supported)
+		if (payloadHash === 'STREAMING-AWS4-HMAC-SHA256-PAYLOAD') {
+			return { valid: false, error: 'Streaming payload signatures are not supported' };
+		}
+
+		// Build canonical request
+		const canonicalRequest = await buildCanonicalRequest(request, params.signedHeaders, payloadHash, isPresigned);
+
+		// Create credential scope
+		const credentialScope = `${params.credential.date}/${params.credential.region}/${params.credential.service}/aws4_request`;
+
+		// Create string to sign
+		const stringToSign = await createStringToSign(params.algorithm, requestDate, credentialScope, canonicalRequest);
+
+		// Derive signing key
+		const signingKey = await deriveSigningKey(clientSecretKey, params.credential.date, params.credential.region, params.credential.service);
+
+		// Calculate expected signature
+		const expectedSignature = await calculateSignature(signingKey, stringToSign);
+
+		// Compare signatures using constant-time comparison to prevent timing attacks
+		const signatureValid = await constantTimeCompare(expectedSignature, params.signature);
+
+		if (!signatureValid) {
+			return { valid: false, error: 'Signature mismatch', isPresigned };
+		}
+
+		// SECURITY NOTE: We do not validate the 'host' header against an expected value.
+		// If you need to restrict which domains can use these credentials, consider adding:
+		// - An environment variable for expected host(s)
+		// - Validation that request.headers.get('host') matches the expected value
+		// This would prevent credentials from being used on different worker domains.
+
+		return { valid: true, isPresigned };
+	} catch (error) {
+		return { valid: false, error: error instanceof Error ? error.message : 'Unknown error' };
+	}
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+import { GuardrailConfig } from './guardrails/type';
+
+/**
+ * Configuration options for the S3Broker handler.
+ *
+ * S3Broker uses a two-key authentication model:
+ * - **Client credentials (Key A)**: Used to verify incoming requests from your clients
+ * - **Upstream credentials (Key B)**: Used to sign requests to the upstream S3 service
+ */
+export interface S3BrokerOptions {
+	/**
+	 * The upstream S3-compatible endpoint URL.
+	 *
+	 * Supports AWS S3, Cloudflare R2, MinIO, and other S3-compatible services.
+	 *
+	 * @example 'https://s3.us-east-1.amazonaws.com'
+	 * @example 'https://account-id.r2.cloudflarestorage.com'
+	 */
+	s3Endpoint: string;
+
+	/**
+	 * Access Key ID for client authentication (Key A)
+	 * Used to verify incoming requests
+	 */
+	clientAccessKeyId: string;
+
+	/**
+	 * Secret Access Key for client authentication (Key A)
+	 * Used to verify incoming requests
+	 */
+	clientSecretAccessKey: string;
+
+	/**
+	 * Access Key ID for upstream authentication (Key B)
+	 * Used to sign requests to the upstream S3 service
+	 */
+	upstreamAccessKeyId: string;
+
+	/**
+	 * Secret Access Key for upstream authentication (Key B)
+	 * Used to sign requests to the upstream S3 service
+	 */
+	upstreamSecretAccessKey: string;
+
+	/**
+	 * Optional custom guardrail configuration
+	 * If not provided, default configuration will be used
+	 */
+	guardrailConfig?: GuardrailConfig;
+}

package/src/utils.ts

@@ -0,0 +1,8 @@
+export enum ErrorCode {
+	Forbidden = 403,
+	UpstreamFailure = 502,
+}
+
+export function textErrorResponse(text: string, errorCode: ErrorCode): Response {
+	return new Response(text, { status: errorCode, headers: { 'Content-Type': 'text/plain' } });
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"lib": ["ES2022"],
+		"types": ["@cloudflare/workers-types"],
+		"strict": true,
+		"skipLibCheck": true,
+		"declaration": true,
+		"declarationMap": true,
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"resolveJsonModule": true,
+		"removeComments": false
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}