s3-trebuchet

Tiny express library to help with s3 uploads and downloads initiated from the browser

Uploading

To upload successfully to s3 from the browser, every request needs to come with a base64-encoded policy.

The policy generation needs to happen on the server, as we don't want to leak S3 keys on the browser.

s3-trebuchet exposes an express middleware that helps in generating this policy.

Downloading

If you don't want to allow public access to your s3 bucket, you can allow downloads with temporary generate URLs.

s3-trebuchet exposes an express middleware that helps in generating those temporary URLs.

Install

npm install --save s3-trebuchet

Usage

Using the express middleware

const initS3Trebuchet = require('s3-trebuchet');
const s3rverConfiguration = {
  accessKeyId: 's3-access-key-id',
  secretAccessKey: 's3-secret-access-key',
  bucket: 'bucket',
  region: 'eu-west-1',
};

const s3Trebuchet = initS3Trebuchet(s3rverConfiguration);
app.put('/get-multipart-params', s3Trebuchet.multipartParamsHandler);
app.put('/validate/:fileKey', s3Trebuchet.fileValidationHandler('fileKey'));
app.get('/temporary-url/:fileKey', s3Trebuchet.goToTemporaryUrlForFileHandler('fileKey', 'fileName'));

Client file upload:

const file = document.getElementById('file').files[0]
const response = await fetch('https://server/get-multipart-params', { method: 'PUT' });
const multipartParams = await response.json()
const formData = new FormData();
Object.keys(multipartParams).forEach(key => formData.append(key, multipartParams[key]));
formData.append("file", file);
await fetch(`https://s3-server.aws/bucket/${file.name}`, { method: 'PUT', body: formData });

Client validate upload:

await fetch(`https://server/validate/${fileKey}`, { method: 'PUT' });

Client get temporary URL

await fetch(`https://server/get-temporary-url/${fileKey}`, { method: 'PUT' });

You can find an example inside the example folder

Configuration

initS3Trebuchet(configuration)

Option	Type	Default	Description
accessKeyId	string		(Required) s3 AccessKey
secretAccessKey	string		(Required) s3 SecretAccessKey
bucket	string		(Required) s3 bucket name
region	string	eu-west-1	s3 region
maxFileSize	number		Acceptable content length upper limit
urlExpiryMilliseconds	number	1800000	Default signed urls expiration in ms
keyPrefix	string		Prepended string to the generated key uuid
acl	string		ACL policy (e.g. public-read)