Imado (+ TUS + AWS Lambda + S3)

Imado is built as a configure-once solution for file handling with the TUS protocol, for public as well as for private files. It supports images and files such as PDF and DOCX and runs on AWS Lambda. Data - including cache - is stored on your own S3 bucket. Optionally it also supports videos.

This repo is a helper to use Imado and is currently being used by CellaJS. The required AWS lambda repo is currently private.

Contact us here if you are interested in using it or email us at info@cellajs.com.

Server

Wrap tus + s3-store and the Imado API to start uploading to your api.

1import { ImadoTus } from "imado";
2import { env } from "env"; // or wherever you store your env variables
3
4const tus = ImadoTus({
5  secret: env.TUS_UPLOAD_API_SECRET,
6  credentials: {
7    bucket: env.AWS_S3_UPLOAD_BUCKET,
8    region: env.AWS_S3_UPLOAD_REGION,
9    accessKeyId: env.AWS_S3_UPLOAD_ACCESS_KEY_ID,
10    secretAccessKey: env.AWS_S3_UPLOAD_SECRET_ACCESS_KEY,
11  },
12});
13
14tus.listen({
15  host: "0.0.0.0",
16  port: Number(env.TUS_PORT ?? "1080"),
17});

Signed (private) URLs

Generate signed URLs for your private CDN (if the url does not include the signUrl it will just pass through).

1import { ImadoUrl } from "imado";
2import { env } from "env";
3
4export const getImadoUrl = new ImadoUrl({
5  signUrl: env.PRIVATE_CDN_ROOT,
6  cloudfrontKeyId: env.AWS_CLOUDFRONT_KEY_ID,
7  cloudfrontPrivateKey: env.AWS_CLOUDFRONT_PRIVATE_KEY,
8});
9
10const thumbnailUrl = `${env.PRIVATE_CDN_ROOT}/thumbnail.jpg`;
11
12const signedThumbnailUrl = getImadoUrl.generate(thumbnailUrl, {
13  width: 100,
14  format: "avif",
15});

What to do on your application

Backend

• Create an endpoint with a JWT including a public boolean and sub in the payload. Recommended would also to define a expiresIn (exp). For example:

1const jwt = require("jsonwebtoken");
2
3async function getUploadToken(ctx) {
4  const isPublic = ctx.req.query("public");
5  const user = ctx.get("user");
6
7  const token = jwt.sign(
8    { sub: user.id, public: isPublic === "true" },
9    process.env.TUS_UPLOAD_API_SECRET
10  );
11
12  return ctx.json({
13    success: true,
14    data: token,
15  });
16}

Frontend

You would include something like Uppy and uppy/tus.

1import Uppy from "@uppy/core";
2import Tus from "@uppy/tus";
3
4// Get the JWT from your server
5const { token } = await (await fetch("/api/upload/token?public=true")).json();
6
7// Convience method to read out JWT (base64) string
8const readJwt = (token: string) => JSON.parse(atob(token.split(".")[1]));
9
10// Read out JWT
11const { public: isPublic, sub } = readJwt(token);
12
13const uppy = new Uppy({
14  meta: {
15    public: isPublic,
16  },
17})
18  .use(Tus, {
19    endpoint: "http://localhost:1080", // endpoint for tus
20    removeFingerprintOnSuccess: true,
21    headers: {
22      authorization: `Bearer ${token}`, // pass the JWT to tus
23    },
24  })
25  .on("complete", (result) => {
26    if (result.successful) {
27      const urls = result.successful.map((file) => {
28        const uploadKey = file.uploadURL.split("/").pop();
29        return new URL(`https://path_to_your_cdn.com/${sub}/${uploadKey}`);
30      });
31
32      // Do something with the urls!
33    }
34  });