File uploads

files stores what your users upload and returns it through short-lived signed URLs. Every file is scanned and private to its owner. Reach for it whenever a user attaches a photo or a document.

files:
  driver: s3
  bucket: acme-uploads
  region: eu-west-1
  key: secret:S3_SECRET_ACCESS_KEY
  scan: true
  maxSize: 25MB

import { files } from "mainsdk";

const ref = await files.upload(file, { owner: user, label: "personal" });
const url = await files.url(ref, { for: user, expiresIn: "1h" });

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { files } from "mainsdk";

describe("files", () => {
  it("files-share AC1 refuses a reader access denies", async () => {
    const testApp = createTestApp({ main: "./main.yaml" });
    const upload = await files.uploadUrl({ owner: { id: "u1" }, maxSize: "5MB", types: ["image/png"] });
    await testApp.files.put(upload, new Uint8Array([0x89, 0x50, 0x4e, 0x47]), { type: "image/png" });
    const ref = await files.complete(upload.ref.id, { owner: { id: "u1" } });
    await assert.rejects(files.url(ref, { for: { id: "u2" } }), { code: "MAIN-FILES-0002" });
  });
});

files:
  driver: getqr

Quick start

Point files at a store, then upload and read. This runs on the local driver with no account.

files:
  driver: local
  max-size: 5MB

import { auth, files } from "mainsdk";

export async function POST(req: Request) {
  const session = await auth.require(req);
  const file = (await req.formData()).get("file") as File;

  const ref = await files.upload(new Uint8Array(await file.arrayBuffer()), {
    owner: session.user,
    type: file.type,
    label: "personal",
  });
  const url = await files.url(ref, { for: session.user, expiresIn: "1h" });
  return Response.json({ ref, url });
}

use mainsdk::prelude::*;
let app = App::test();
Context::new().tenant("tnt_a").user("u1").scope(async {
use mainsdk::files::Label;
let file = app.files().upload(b"hello".to_vec()).owner("u1").label(Label::Pii).await?;
assert_eq!(file.size, 5);
Ok::<_, MainError>(())
}).await?;

files.upload() takes the bytes and their MIME type, scans them, and returns a FileRef with status: "ready". The URL is signed and stops working after an hour. For anything large, let the browser send the file with files.uploadUrl() (below).

Configuration

Every key lives under files:. With no driver, the app uses local.

files:
  driver: getqr                  # getqr | s3 | local   (uploadthing, vercel-blob: planned)
  key: secret:GETQR_API_KEY      # the driver's secret, always a secret reference
  scan: true                     # scan every upload before it becomes readable
  max-size: 25MB                  # largest file accepted
  types: [image/*, application/pdf]   # allowed MIME types; empty allows any

Secret references match secret:[A-Z0-9_]+ and resolve through secrets on the server.

Config for each driver

files: { driver: getqr, key: secret:GETQR_API_KEY, scan: true, max-size: 25MB }

files: { driver: s3, bucket: acme-uploads, region: eu-west-1, access-key-id: AKIA…, key: secret:S3_SECRET_ACCESS_KEY, scan: true }
# on AWS, omit access-key-id and key to use the runtime's IAM role
# R2, MinIO and B2 also set: endpoint: https://<their-endpoint>

files: { driver: local }   # stores under .mainsdk/files

Setup for each store is on its page: getqr.id and Amazon S3.

Choosing a driver

Every driver keeps the same guarantees (ADR-0013): the SDK enforces owner scope, signed single-use upload targets, the scan and short-lived read URLs; drivers only move bytes.

Overlays by environment

Use the local driver in development so you need no account with any store:

files:
  driver: local

See main.yaml for overlay order and merge rules.

What you get

files stores the files your users upload and gives them back through short-lived signed URLs. You choose the store in main.yaml: getqr.id (the default), your own S3 bucket or an S3-compatible store, or local disk for development. Whichever you choose, uploads go through files, are scanned before anyone can read them, and belong to their owner: only the owner, or someone access allows, can read one. An idempotency key makes a retried upload return the same file. Reach for it whenever a user attaches a photo, a document or a proof video. mainsdk check fails if route code uses a storage SDK directly.

Examples

Resumable upload with an idempotency key

Pass an idempotency key. A retry with the same key and owner returns the same file instead of a second one.

"use server";
import { auth, files } from "mainsdk";
import type { FileRef } from "mainsdk/files";

declare function saveProof(user: string, claimId: string, proof: FileRef): Promise<void>;   // your own record

export async function attachProof(req: Request, claimId: string, video: Uint8Array) {
  const session = await auth.require(req);
  const ref = await files.upload(video, {
    owner: session.user,
    type: "video/mp4",
    label: "personal",
    idempotencyKey: `claim:${claimId}:proof`,   // same key on retry
  });
  await saveProof(session.user, claimId, ref);
  return ref;
}

Upload straight from the browser

For large files, let the browser send the bytes to the store and keep them off your server. files.uploadUrl() returns an Upload: method (PUT or POST), a signed single-use url, headers or fields, and a pending FileRef in upload.ref. The file is not readable until files.complete() has scanned it. files.complete() takes the owner too, and refuses anyone but the uploader with MAIN-FILES-0002. An upload target works once and expires in 15 minutes.

import { auth, files } from "mainsdk";

export async function POST(req: Request) {
  const session = await auth.require(req);
  const upload = await files.uploadUrl({
    owner: session.user,
    maxSize: "5MB",
    types: ["image/png", "image/jpeg"],
  });
  return Response.json(upload);
}

import { auth, files } from "mainsdk";

export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const session = await auth.require(req);
  const { id } = await params;                                   // upload.ref.id
  const ref = await files.complete(id, { owner: session.user }); // only the uploader can finish it
  const url = await files.url(ref, { for: session.user, expiresIn: "1h" });
  return Response.json({ url });
}

The browser sends the file to upload.url with upload.method: for PUT, the bytes as the body with upload.headers; for POST, a form with upload.fields first and the file last. Then it calls the complete route with upload.ref.id. The store refuses a file over maxSize (MAIN-FILES-0006, 413) or outside types (MAIN-FILES-0007, 415), and a used or expired target fails with MAIN-FILES-0004. The full browser function is in Upload files with S3 or getqr.id.

Upload from a form with the Upload component

With the getqr.id driver, <Upload/> from @getqr/react handles the browser side (drop zone, paste, camera, progress and the scan) and shows "Powered by getqr.id". Its props belong to @getqr/react.

"use client";
import { Upload } from "@getqr/react";

export function UploadProof() {
  return <Upload accept={["video/*", "image/*"]} onError={(err) => console.error(err)} />;
}

Let a reviewer read a file

files.url() checks access for the reader. If the decision denies them, it throws MAIN-FILES-0002 with status 403. The action is files.read, so a role rule such as support: [files.read] lets support staff read any file.

import { auth, files } from "mainsdk";
import type { FileRef } from "mainsdk/files";

declare function proofOf(user: string, claimId: string): Promise<FileRef>;   // your own record

export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const session = await auth.require(req, { role: "reviewer" });
  const proof = await proofOf(session.user, id);
  const url = await files.url(proof, { for: session.user, expiresIn: "1h" });
  return Response.redirect(url, 302);
}

Read the bytes on the server

files.read(ref, { for }) returns { bytes, type } for the owner or an allowed reader, for server code that processes a file (for example documents). It needs a store that serves bytes to the server: local and s3 do, getqr does not (MAIN-FILES-0015).

import { files } from "mainsdk";

export async function textOf(fileId: string, userId: string) {
  const { bytes, type } = await files.read(fileId, { for: { id: userId } });
  return { type, text: new TextDecoder().decode(bytes) };
}

Look up a file

files.get(id) returns a file's current record (status, owner, size, type) or undefined for an unknown id. It is synchronous and never returns the bytes.

import { files } from "mainsdk";

export function isReady(fileId: string) {
  return files.get(fileId)?.status === "ready";
}

Reference: driver and route calls

These calls sit under the upload and read flow. Your routes seldom need them, but drivers, adapters and tests do.

Errors and checks

The full list is in check codes. Run mainsdk explain MAIN-FILES-0005 for the cause and fix offline.

Swapping drivers

Switch one line; files.upload(), files.uploadUrl(), files.complete(), files.url() and files.read() stay the same.

files:
  driver: s3   # was getqr

Existing files stay where they are until you migrate them. Sharing is separate from storage: share(), links and QR codes always use getqr.id, whichever files driver holds the file (see Share links and QR codes).

Testing

createTestApp() puts files on its in-memory fake. The fake enforces the same owner scope and scanning as production, and testApp.files.put(upload, bytes, { type }) plays the browser's part in the direct flow. The built-in scan refuses the EICAR test file.

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { files } from "mainsdk";

describe("files", () => {
  it("files-share AC1 refuses a reader access denies", async () => {
    const testApp = createTestApp({ main: "./main.yaml" });
    const upload = await files.uploadUrl({ owner: { id: "u1" }, maxSize: "5MB", types: ["image/png"] });
    await testApp.files.put(upload, new Uint8Array([0x89, 0x50, 0x4e, 0x47]), { type: "image/png" });
    const ref = await files.complete(upload.ref.id, { owner: { id: "u1" } });
    await assert.rejects(files.url(ref, { for: { id: "u2" } }), { code: "MAIN-FILES-0002" });
  });
});

Use clock.advance("61m") to expire a one-hour signed URL without waiting. The infected-file test is in the upload guide.

Security and privacy

• Files are private to their owner. Readers go through an access decision, and URLs are signed and short-lived.
• files.complete() scans each upload before it becomes readable; infected files are quarantined and audited.
• Label personal files (label: "personal") so logs, errors and exports treat them as personal data.
• With tenancy, a file of another tenant is refused with MAIN-TENANT-0005 before any owner check, and its object key carries the tenant's region.
• Browser upload targets are single-use and limited in size and type, so a client cannot send a larger or different file than you allowed.
• With the default driver you also get first-party tracking from getqr.id.

FAQ

Who scans the file, getqr.id or the SDK? With the getqr.id driver, getqr.id scans server side and files.complete() trusts its verdict. With the other drivers the SDK scans in files.complete(): the built-in scan matches the EICAR test signature, and a real engine plugs in through the scanner option when you build the app in code.

Can I keep using S3? Yes, as the files driver. What fails mainsdk check with MAIN-FILES-0010 is importing its SDK in route code instead of going through files.

How do I share a file with someone outside the app? Use share() to make a private, expiring getqr.id link.

Next

• Share links and QR codes: share a file or record as an expiring link.
• Images and video: resize and transcode uploads (planned).
• Permissions: decide who else can read a file.