Security

dimah-s3 follows a presign-first security model: AWS credentials remain on the server, while clients upload directly to storage via short-lived signed URLs.

Public NEXT_PUBLIC_ keys in a browser bundle are a leak, not a configuration shortcut:

export const awsS3 = new S3Client({
  credentials: {
    accessKeyId: process.env.NEXT_PUBLIC_S3_ACCESS_KEY_ID!, 
    secretAccessKey: process.env.NEXT_PUBLIC_S3_SECRET_ACCESS_KEY!, 
  },
});

Security modelCopy Anchor Link

1. Server owns keys — The client requests an upload for a named route. The server decides the destination key path (avatar/{uuid}/{fileName} or customized via object).
2. Namespace isolation — keyPrefix defaults to the route name. Upload generates keys under it; confirm, download, and delete reject keys outside it (INVALID_KEY). This check always runs in @dimah-s3/server.
3. Verified metadata via HeadObject — Presign payloads (size/type) are untrusted. Stored byte length and Content-Type metadata are read server-side via HeadObject in upload.onConfirmed.
4. Guards and authorization — Route guard and feature guards (upload.guard, download.guard, delete.guard) control per-user authorization. Namespace isolation is not ownership.

Route namespace vs ownershipCopy Anchor Link

keyPrefix and a guard answer different questions:

The same prefix is used on the way in and the way out. With two routes:

avatar: route({ upload: { fileTypes: ["image/*"] }, delete: true }),
document: route({ upload: { fileTypes: ["application/pdf"] }, delete: true }),

• Upload on avatar creates avatar/{uuid}/photo.jpg — the client does not send a key.
• DELETE ?route=avatar&key=avatar/{uuid}/photo.jpg is in-namespace.
• DELETE ?route=avatar&key=document/{uuid}/cv.pdf is INVALID_KEY.

db() does not replace that prefix check. It stores a route column for listings; its guards look up (bucket, key) and compare scope. A key from another route is still rejected by the server before those guards run.

Scoping objects and user tenancyCopy Anchor Link

Use upload.object to isolate files by tenant or user ID:

import { dimahS3, errors, route } from "@dimah-s3/server";

export const s3 = dimahS3({
  client: awsS3,
  bucket: process.env.S3_BUCKET!,
  routes: {
    avatar: route({
      guard: async ({ request }) => {
        const session = await getSession(request);
        if (!session) throw errors.unauthorized();
      },
      upload: {
        fileTypes: ["image/*"],
        maxFileSize: 2 * 1024 * 1024,
        object: async ({ request }) => {
          const session = await getSession(request);
          return {
            folder: `users/${session.userId}`, 
            // Generates: avatar/users/{userId}/{uuid}/{fileName}
          };
        },
        onConfirmed: async ({ key, contentLength, request }) => {
          // Trusted stored size and server-owned key from S3 HeadObject
          const session = await getSession(request); 
          await db.user.update({
            where: { id: session.userId }, 
            data: { avatarKey: key, avatarSize: contentLength }, 
          }); 
        }, 
      },
      download: true,
      delete: true,
    }),
  },
});

Returning folder: users/{userId} only shapes the key. The route guard above requires a session; it does not stop one signed-in user from targeting another user's key. Add download.guard / delete.guard (or db()) for ownership.

Object ACLCopy Anchor Link

Uploads are private by default. Set acl on the route or return it dynamically from upload.object:

avatar: route({
  upload: {
    acl: "public-read", 
    fileTypes: ["image/*"],
    maxFileSize: 2 * 1024 * 1024,
  },
}),

Hook error mappingCopy Anchor Link

Frequently asked questionsCopy Anchor Link

import { GetObjectCommand } from "@aws-sdk/client-s3";
import { sniffContentType } from "@dimah-s3/core";
import { dimahS3, errors, route } from "@dimah-s3/server";
import { awsS3 } from "./aws-s3";

const bucket = process.env.S3_BUCKET!;
const allowedTypes = new Set(["image/png", "image/jpeg", "image/webp"]);

export const s3 = dimahS3({
  client: awsS3,
  bucket,
  routes: {
    avatar: route({
      upload: {
        fileTypes: ["image/png", "image/jpeg", "image/webp"],
        onConfirmed: async ({ key, fileName }) => {
          const response = await awsS3.send(
            new GetObjectCommand({
              Bucket: bucket,
              Key: key,
              Range: "bytes=0-15",
            }),
          );
          if (!response.Body) throw errors.objectNotFound();

          const bytes = await response.Body.transformToByteArray();
          const detectedType = sniffContentType(bytes);
          if (!detectedType || !allowedTypes.has(detectedType)) {
            throw errors.fileTypeNotAllowed(fileName ?? key, detectedType);
          }
        },
      },
    }),
  },
});

avatar: route({
  delete: true, 
}),

avatar: route({
  delete: {
    guard: async ({ key, request }) => { 
      const session = await getSession(request); 
      const isOwner = await checkAvatarOwnership(session.userId, key); 
      if (!isOwner) throw errors.forbidden(); 
    }, 
  },
}),