Let a standard library ServeMux issue signed upload and download URLs for private invoice PDFs, using Encore on S3 or Cloud Storage, or the AWS SDK by hand.

The Go standard library can accept a POST /invoices/{id}/upload-url and return a JSON URL, and http.ServeMux patterns such as GET /invoices/{id}/file need no extra router.
The bucket around that URL is the part that grows: a private bucket per environment, a way to upload without making the object world-readable, a size and type check after the bytes land, signed downloads, and IAM so the API can sign requests without holding a long-lived access key in the repo.
This guide adds private invoice PDFs to a net/http billing API. It starts with Encore, which declares the bucket in Go next to the ServeMux and provisions it in your own AWS or GCP account, then shows the same handlers with S3 and aws-sdk-go-v2.
Encore works alongside a plain net/http app: the ServeMux and its handlers stay standard library code, and the bucket they sign URLs for is a Go declaration next to them. A raw endpoint is an ordinary http.HandlerFunc, so the mux is mounted in one fallback route. The object storage API issues signed upload and download URLs, and encore run stores objects on the local filesystem.
A coding agent working in this repository adds the bucket declaration and the two URL handlers in the same change, then uses encore run to create a URL, PUT a PDF, and confirm it with Attrs.
Run in your terminal to get started locally.
The schema keeps one invoice row and the object key once the PDF has passed the size and type check:
-- invoices/migrations/1_create_invoices.up.sql
CREATE TABLE invoices (
id TEXT PRIMARY KEY,
customer_id TEXT NOT NULL,
pending_key TEXT,
object_key TEXT,
byte_size BIGINT,
status TEXT NOT NULL DEFAULT 'awaiting_file'
CHECK (status IN ('awaiting_file', 'ready')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
The bucket is private, the upload handler returns a two-hour signed URL for a key the API chooses, and the confirm handler reads Attrs and the PDF magic bytes and rejects a file over 10 MiB or without a %PDF header:
// invoices/invoices.go
package invoices
import (
"context"
"crypto/hmac"
"crypto/rand"
"crypto/sha256"
"crypto/subtle"
"database/sql"
"encoding/hex"
"encoding/json"
"errors"
"io"
"net/http"
"strconv"
"strings"
"time"
"encore.dev/beta/auth"
"encore.dev/beta/errs"
"encore.dev/storage/objects"
"encore.dev/storage/sqldb"
)
var db = sqldb.NewDatabase("invoices", sqldb.DatabaseConfig{
Migrations: "./migrations",
})
// HMAC key for access tokens. Set with `encore secret set`; not stored in the repo.
var secrets struct {
AuthTokenHMAC string
}
// Local disk with `encore run`, S3 or Cloud Storage when deployed, always private.
var files = objects.NewBucket("invoice-pdfs", objects.BucketConfig{})
const maxPDFBytes = 10 << 20 // 10 MiB
//encore:authhandler
func AuthHandler(ctx context.Context, token string) (auth.UID, error) {
uid, err := userIDFromToken(token)
if err != nil {
return "", &errs.Error{Code: errs.Unauthenticated, Message: "invalid token"}
}
return uid, nil
}
// userIDFromToken verifies a signed access token of the form "<id>.<unix-expiry>.<hex hmac>".
// In production, verify a JWT against your IdP JWKS (signature, issuer, audience,
// expiry) and return the subject.
func userIDFromToken(token string) (auth.UID, error) {
if secrets.AuthTokenHMAC == "" {
return "", errors.New("auth secret not set")
}
parts := strings.Split(token, ".")
if len(parts) != 3 {
return "", errors.New("invalid token")
}
id, expStr, sig := parts[0], parts[1], parts[2]
if id == "" || strings.ContainsAny(id, "/ \t\n") {
return "", errors.New("invalid token")
}
exp, err := strconv.ParseInt(expStr, 10, 64)
if err != nil || exp <= time.Now().Unix() {
return "", errors.New("invalid token")
}
mac := hmac.New(sha256.New, []byte(secrets.AuthTokenHMAC))
mac.Write([]byte(id + "." + expStr))
expected := hex.EncodeToString(mac.Sum(nil))
if subtle.ConstantTimeCompare([]byte(sig), []byte(expected)) != 1 {
return "", errors.New("invalid token")
}
return auth.UID(id), nil
}
func authorizeInvoice(r *http.Request) (string, error) {
uid, ok := auth.UserID()
if !ok {
return "", &errs.Error{Code: errs.Unauthenticated, Message: "unauthenticated"}
}
id := r.PathValue("id")
if strings.TrimSpace(id) == "" {
return "", &errs.Error{Code: errs.NotFound, Message: "invoice not found"}
}
var customer string
err := db.QueryRow(r.Context(), `SELECT customer_id FROM invoices WHERE id = $1`, id).Scan(&customer)
if errors.Is(err, sqldb.ErrNoRows) || customer != string(uid) {
return "", &errs.Error{Code: errs.NotFound, Message: "invoice not found"}
} else if err != nil {
return "", err
}
return id, nil
}
func writeAuthError(w http.ResponseWriter, err error) {
var e *errs.Error
if errors.As(err, &e) {
switch e.Code {
case errs.Unauthenticated:
http.Error(w, e.Message, http.StatusUnauthorized)
return
case errs.NotFound:
http.Error(w, e.Message, http.StatusNotFound)
return
}
}
http.Error(w, "could not load invoice", http.StatusInternalServerError)
}
//encore:service
type Service struct {
mux *http.ServeMux
}
func initService() (*Service, error) {
mux := http.NewServeMux()
mux.HandleFunc("POST /invoices/{id}/upload-url", createUploadURL)
mux.HandleFunc("POST /invoices/{id}/confirm", confirmUpload)
mux.HandleFunc("GET /invoices/{id}/file", downloadURL)
return &Service{mux: mux}, nil
}
//encore:api auth raw path=/!fallback
func (s *Service) Fallback(w http.ResponseWriter, req *http.Request) {
s.mux.ServeHTTP(w, req)
}
func newPendingKey(id string) (string, error) {
var b [16]byte
if _, err := rand.Read(b[:]); err != nil {
return "", err
}
return "invoices/" + id + "/" + hex.EncodeToString(b[:]) + ".pdf", nil
}
var errInvoiceReady = errors.New("invoice already has a file")
// existingOrNewPendingKey reuses an unconsumed pending key so two upload-URL
// requests for the same invoice sign the same object instead of orphaning one.
func existingOrNewPendingKey(ctx context.Context, id string) (string, error) {
var pending sql.NullString
err := db.QueryRow(ctx, `
SELECT pending_key FROM invoices WHERE id = $1 AND status = 'awaiting_file'`, id).Scan(&pending)
if errors.Is(err, sqldb.ErrNoRows) {
return "", errInvoiceReady
} else if err != nil {
return "", err
}
if pending.Valid && pending.String != "" {
return pending.String, nil
}
key, err := newPendingKey(id)
if err != nil {
return "", err
}
res, err := db.Exec(ctx, `
UPDATE invoices SET pending_key = $2
WHERE id = $1 AND status = 'awaiting_file' AND pending_key IS NULL`, id, key)
if err != nil {
return "", err
}
if res.RowsAffected() == 1 {
return key, nil
}
err = db.QueryRow(ctx, `
SELECT pending_key FROM invoices WHERE id = $1 AND status = 'awaiting_file'`, id).Scan(&pending)
if errors.Is(err, sqldb.ErrNoRows) || !pending.Valid || pending.String == "" {
return "", errInvoiceReady
} else if err != nil {
return "", err
}
return pending.String, nil
}
func createUploadURL(w http.ResponseWriter, r *http.Request) {
id, err := authorizeInvoice(r)
if err != nil {
writeAuthError(w, err)
return
}
pending, err := existingOrNewPendingKey(r.Context(), id)
if err != nil {
if errors.Is(err, errInvoiceReady) {
http.Error(w, "invoice already has a file", http.StatusConflict)
return
}
http.Error(w, "could not create upload URL", http.StatusInternalServerError)
return
}
signed, err := files.SignedUploadURL(r.Context(), pending, objects.WithTTL(2*time.Hour))
if err != nil {
http.Error(w, "could not create upload URL", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]string{"url": signed.URL, "key": pending})
}
func confirmUpload(w http.ResponseWriter, r *http.Request) {
id, err := authorizeInvoice(r)
if err != nil {
writeAuthError(w, err)
return
}
var key string
err = db.QueryRow(r.Context(), `
SELECT pending_key FROM invoices
WHERE id = $1 AND status = 'awaiting_file' AND pending_key IS NOT NULL`, id).Scan(&key)
if errors.Is(err, sqldb.ErrNoRows) {
http.Error(w, "no pending upload", http.StatusConflict)
return
} else if err != nil {
http.Error(w, "could not confirm invoice", http.StatusInternalServerError)
return
}
attrs, err := files.Attrs(r.Context(), key)
if errors.Is(err, objects.ErrObjectNotFound) {
http.Error(w, "no file at the invoice key", http.StatusNotFound)
return
} else if err != nil {
http.Error(w, "could not read object", http.StatusInternalServerError)
return
}
if attrs.Size > maxPDFBytes {
_ = files.Remove(r.Context(), key)
http.Error(w, "file must be a PDF of at most 10 MiB", http.StatusUnsupportedMediaType)
return
}
// Signed PUTs may not store a Content-Type, so check the PDF magic bytes as well.
reader := files.Download(r.Context(), key)
if err := reader.Err(); err != nil {
http.Error(w, "could not read object", http.StatusInternalServerError)
return
}
defer reader.Close()
head := make([]byte, 5)
n, _ := io.ReadFull(reader, head)
if n < 4 || string(head[:4]) != "%PDF" {
_ = files.Remove(r.Context(), key)
http.Error(w, "file must be a PDF of at most 10 MiB", http.StatusUnsupportedMediaType)
return
}
res, err := db.Exec(r.Context(), `
UPDATE invoices
SET object_key = $2, pending_key = NULL, byte_size = $3, status = 'ready'
WHERE id = $1 AND status = 'awaiting_file'`, id, key, attrs.Size)
if err != nil || res.RowsAffected() == 0 {
http.Error(w, "could not confirm invoice", http.StatusInternalServerError)
return
}
w.WriteHeader(http.StatusNoContent)
}
func downloadURL(w http.ResponseWriter, r *http.Request) {
id, err := authorizeInvoice(r)
if err != nil {
writeAuthError(w, err)
return
}
var key, status string
err = db.QueryRow(r.Context(), `SELECT object_key, status FROM invoices WHERE id = $1`, id).Scan(&key, &status)
if errors.Is(err, sqldb.ErrNoRows) || status != "ready" || key == "" {
http.NotFound(w, r)
return
} else if err != nil {
http.Error(w, "could not load invoice", http.StatusInternalServerError)
return
}
signed, err := files.SignedDownloadURL(r.Context(), key, objects.WithTTL(15*time.Minute))
if err != nil {
http.Error(w, "could not create download URL", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]string{"url": signed.URL})
}
The three routes require a signed-in customer and authorize that caller against the invoice's customer_id before issuing a URL or confirming the object. Upload URLs use a one-time pending key and are refused once the invoice is ready, so a leftover URL cannot overwrite the confirmed object. The signed URL is restricted to that key and expires after the TTL, as described in the signed upload and signed download docs. Confirm runs Attrs and checks the PDF magic bytes before the invoice is marked ready, and download signs only the confirmed object_key.
encore run stores objects on disk and starts Postgres locally for the invoice table. On deploy to your own AWS or GCP account, Encore provisions the bucket as S3 or Cloud Storage, and Encore provisions an IAM role for the service, or a service account on GCP.
Best fit: a net/http API that wants a private bucket declared next to the handlers, with S3 or Cloud Storage in your own account.
The same handlers can call presigned PutObject and GetObject URLs from aws-sdk-go-v2. Authenticate the caller and authorize them against the invoice's customer before issuing a URL or confirming the object; an invoice id is not an access credential. You create the bucket with Block Public Access on, add a bucket policy or IAM role that allows the API to sign and to call HeadObject, and pass the bucket name in configuration.
// cmd/api/main.go
package main
import (
"context"
"crypto/hmac"
"crypto/rand"
"crypto/sha256"
"crypto/subtle"
"database/sql"
"encoding/hex"
"encoding/json"
"errors"
"io"
"log"
"net/http"
"os"
"strconv"
"strings"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
_ "github.com/jackc/pgx/v5/stdlib"
)
type api struct {
presign *s3.PresignClient
s3 *s3.Client
db *sql.DB
bucket string
hmacKey []byte
}
func main() {
cfg, err := config.LoadDefaultConfig(context.Background())
if err != nil {
log.Fatal(err)
}
db, err := sql.Open("pgx", os.Getenv("DATABASE_URL"))
if err != nil {
log.Fatal(err)
}
client := s3.NewFromConfig(cfg)
a := &api{
presign: s3.NewPresignClient(client),
s3: client,
db: db,
bucket: os.Getenv("INVOICE_BUCKET"),
hmacKey: []byte(os.Getenv("AUTH_TOKEN_HMAC")),
}
mux := http.NewServeMux()
mux.HandleFunc("POST /invoices/{id}/upload-url", a.createUploadURL)
mux.HandleFunc("POST /invoices/{id}/confirm", a.confirmUpload)
mux.HandleFunc("GET /invoices/{id}/file", a.downloadURL)
srv := &http.Server{Addr: ":8080", Handler: mux, ReadHeaderTimeout: 5 * time.Second}
log.Fatal(srv.ListenAndServe())
}
func (a *api) authorizeInvoice(r *http.Request) (string, error) {
token := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
uid, err := userIDFromToken(token, a.hmacKey)
if err != nil {
return "", errUnauth
}
id := r.PathValue("id")
var customer string
err = a.db.QueryRowContext(r.Context(), `SELECT customer_id FROM invoices WHERE id = $1`, id).Scan(&customer)
if errors.Is(err, sql.ErrNoRows) || customer != uid {
return "", errNotFound
} else if err != nil {
return "", err
}
return id, nil
}
func (a *api) newPendingKey(id string) (string, error) {
var b [16]byte
if _, err := rand.Read(b[:]); err != nil {
return "", err
}
return "invoices/" + id + "/" + hex.EncodeToString(b[:]) + ".pdf", nil
}
var errInvoiceReady = errors.New("invoice already has a file")
func (a *api) existingOrNewPendingKey(ctx context.Context, id string) (string, error) {
var pending sql.NullString
err := a.db.QueryRowContext(ctx, `
SELECT pending_key FROM invoices WHERE id = $1 AND status = 'awaiting_file'`, id).Scan(&pending)
if errors.Is(err, sql.ErrNoRows) {
return "", errInvoiceReady
} else if err != nil {
return "", err
}
if pending.Valid && pending.String != "" {
return pending.String, nil
}
key, err := a.newPendingKey(id)
if err != nil {
return "", err
}
res, err := a.db.ExecContext(ctx, `
UPDATE invoices SET pending_key = $2
WHERE id = $1 AND status = 'awaiting_file' AND pending_key IS NULL`, id, key)
if err != nil {
return "", err
}
if res.RowsAffected() == 1 {
return key, nil
}
err = a.db.QueryRowContext(ctx, `
SELECT pending_key FROM invoices WHERE id = $1 AND status = 'awaiting_file'`, id).Scan(&pending)
if errors.Is(err, sql.ErrNoRows) || !pending.Valid || pending.String == "" {
return "", errInvoiceReady
} else if err != nil {
return "", err
}
return pending.String, nil
}
func (a *api) createUploadURL(w http.ResponseWriter, r *http.Request) {
id, err := a.authorizeInvoice(r)
if err != nil {
writeAuthError(w, err)
return
}
pending, err := a.existingOrNewPendingKey(r.Context(), id)
if err != nil {
if errors.Is(err, errInvoiceReady) {
http.Error(w, "invoice already has a file", http.StatusConflict)
return
}
http.Error(w, "could not create upload URL", http.StatusInternalServerError)
return
}
out, err := a.presign.PresignPutObject(r.Context(), &s3.PutObjectInput{
Bucket: aws.String(a.bucket),
Key: aws.String(pending),
ContentType: aws.String("application/pdf"),
}, func(o *s3.PresignOptions) { o.Expires = 2 * time.Hour })
if err != nil {
http.Error(w, "could not create upload URL", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]string{"url": out.URL, "key": pending})
}
func (a *api) confirmUpload(w http.ResponseWriter, r *http.Request) {
id, err := a.authorizeInvoice(r)
if err != nil {
writeAuthError(w, err)
return
}
var key string
err = a.db.QueryRowContext(r.Context(), `
SELECT pending_key FROM invoices
WHERE id = $1 AND status = 'awaiting_file' AND pending_key IS NOT NULL`, id).Scan(&key)
if errors.Is(err, sql.ErrNoRows) {
http.Error(w, "no pending upload", http.StatusConflict)
return
} else if err != nil {
http.Error(w, "could not confirm invoice", http.StatusInternalServerError)
return
}
head, err := a.s3.HeadObject(r.Context(), &s3.HeadObjectInput{
Bucket: aws.String(a.bucket),
Key: aws.String(key),
})
if err != nil {
http.Error(w, "no file at the invoice key", http.StatusNotFound)
return
}
if aws.ToInt64(head.ContentLength) > 10<<20 {
_, _ = a.s3.DeleteObject(r.Context(), &s3.DeleteObjectInput{Bucket: aws.String(a.bucket), Key: aws.String(key)})
http.Error(w, "file must be a PDF of at most 10 MiB", http.StatusUnsupportedMediaType)
return
}
// Do not trust Content-Type metadata; check the PDF magic bytes.
obj, err := a.s3.GetObject(r.Context(), &s3.GetObjectInput{
Bucket: aws.String(a.bucket),
Key: aws.String(key),
Range: aws.String("bytes=0-4"),
})
if err != nil {
http.Error(w, "could not read object", http.StatusInternalServerError)
return
}
magic := make([]byte, 5)
n, _ := io.ReadFull(obj.Body, magic)
obj.Body.Close()
if n < 4 || string(magic[:4]) != "%PDF" {
_, _ = a.s3.DeleteObject(r.Context(), &s3.DeleteObjectInput{Bucket: aws.String(a.bucket), Key: aws.String(key)})
http.Error(w, "file must be a PDF of at most 10 MiB", http.StatusUnsupportedMediaType)
return
}
res, err := a.db.ExecContext(r.Context(), `
UPDATE invoices SET object_key = $2, pending_key = NULL, byte_size = $3, status = 'ready'
WHERE id = $1 AND status = 'awaiting_file'`, id, key, aws.ToInt64(head.ContentLength))
if err != nil || res.RowsAffected() == 0 {
http.Error(w, "could not confirm invoice", http.StatusInternalServerError)
return
}
w.WriteHeader(http.StatusNoContent)
}
func (a *api) downloadURL(w http.ResponseWriter, r *http.Request) {
id, err := a.authorizeInvoice(r)
if err != nil {
writeAuthError(w, err)
return
}
var key, status string
err = a.db.QueryRowContext(r.Context(), `SELECT object_key, status FROM invoices WHERE id = $1`, id).Scan(&key, &status)
if err != nil || status != "ready" || key == "" {
http.NotFound(w, r)
return
}
out, err := a.presign.PresignGetObject(r.Context(), &s3.GetObjectInput{
Bucket: aws.String(a.bucket),
Key: aws.String(key),
}, func(o *s3.PresignOptions) { o.Expires = 15 * time.Minute })
if err != nil {
http.Error(w, "could not create download URL", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]string{"url": out.URL})
}
var errUnauth = errors.New("unauthenticated")
var errNotFound = errors.New("invoice not found")
func writeAuthError(w http.ResponseWriter, err error) {
if errors.Is(err, errUnauth) {
http.Error(w, err.Error(), http.StatusUnauthorized)
return
}
if errors.Is(err, errNotFound) {
http.Error(w, err.Error(), http.StatusNotFound)
return
}
http.Error(w, "could not load invoice", http.StatusInternalServerError)
}
// userIDFromToken verifies "<id>.<unix-expiry>.<hex hmac>", the same scheme as the Encore handler.
func userIDFromToken(token string, hmacKey []byte) (string, error) {
if len(hmacKey) == 0 {
return "", errors.New("auth secret not set")
}
parts := strings.Split(token, ".")
if len(parts) != 3 {
return "", errors.New("invalid token")
}
id, expStr, sig := parts[0], parts[1], parts[2]
if id == "" || strings.ContainsAny(id, "/ \t\n") {
return "", errors.New("invalid token")
}
exp, err := strconv.ParseInt(expStr, 10, 64)
if err != nil || exp <= time.Now().Unix() {
return "", errors.New("invalid token")
}
mac := hmac.New(sha256.New, hmacKey)
mac.Write([]byte(id + "." + expStr))
if subtle.ConstantTimeCompare([]byte(sig), []byte(hex.EncodeToString(mac.Sum(nil)))) != 1 {
return "", errors.New("invalid token")
}
return id, nil
}
The client must PUT the PDF to the presigned URL with the same Content-Type the signature covered. The URL points at a one-time pending key, so it cannot overwrite an invoice that is already ready. Confirm checks the PDF magic bytes on the server, not the client-supplied Content-Type, before it stores that key as object_key. Download uses a short-lived presigned GetObject URL for the confirmed key only. Encryption, versioning and access logging stay on the bucket you provision.
Best fit: teams that already have S3 buckets in Terraform and want the net/http process to stay a plain binary.
http.MaxBytesReader plus io.Copy into s3.PutObject keeps the check and the write in one handler, which is fine for small files. The API then has to sit in the path of every byte, handle slow clients, and size timeouts for the largest invoice you will accept. Signed URLs exist so that work can move to the bucket.
Best fit: PDFs of a few hundred kilobytes when you want to inspect the body before any object is created.
Pick Encore when you want the bucket declared next to the ServeMux, objects on local disk with encore run, and S3 or Cloud Storage provisioned in your own account. Pick S3 presigned URLs by hand when the bucket already lives in Terraform and you want to keep the API a plain net/http binary. Accepting the body in the handler is enough for small files and becomes awkward once invoices are large or uploaded over slow links.
The confirm step itself does not depend on the choice: read the stored object attributes, reject the wrong type or size, and only then mark the invoice ready.
Keep the PDF out of the API process: the handler issues a short-lived signed upload URL for a chosen key, the client PUTs the bytes straight to the bucket, and a second handler checks the stored object size and content type before marking the invoice complete. On AWS that is S3 and a presigned PutObject URL from aws-sdk-go-v2.
Declare a private bucket with objects.NewBucket, mount the ServeMux in a raw endpoint with path=/!fallback, and call SignedUploadURL and SignedDownloadURL from the handlers. After the client uploads, call Attrs to confirm size and content type. encore run stores objects on the local filesystem, and deploys provision S3 on AWS or Cloud Storage on GCP in your own account.
A signed upload URL keeps large or slow uploads off the API process and writes bytes straight into the bucket. Accepting the body in the handler is simpler for small files when you want to inspect every byte before anything is stored.
Do not trust the filename or a Content-Type header the client sent to your API. After the upload, read the object attributes and reject anything over your size limit or with a type other than application/pdf, and delete the object if it fails the check.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.