Store and share files

What you will build

Your notes app lets people attach a file. You will create a private bucket, upload a file, make a time-limited link, and see how your server can hand out upload links.

Create a private bucket

1. Open Storage Vault in the sidebar.
2. Choose Create Bucket (or Create First Bucket).
3. Name it attachments. Names are 3 to 63 characters of lowercase letters, numbers and hyphens.
4. Under Access choose Private: members, the secret API key, or signed links only.
5. Choose Create Bucket.

Private is the safer default for anything a user uploads. It never serves files to the public.

Upload and organise

1. Choose Open Bucket on attachments.
2. Choose Create Folder and name it reports.
3. Open the folder, choose Upload, pick a small PDF or image under Select File, and choose Upload File.

The table shows the file's Name, Type, Size and Last Modified. For a private bucket the link action reads Copy Signed Link.

Share one file for 15 minutes

Choose Copy Signed Link. The link works for 15 minutes and for that one file only. Paste it into a private browser window and the file opens. After it expires, the same link stops working. Try the bucket's public address, https://<your-project>.pgbhub.app/storage/attachments/reports/<file>. It answers "not found", because the bucket is private and you did not use the secret key.

Switch visibility

Next to the bucket name you will see a Private bucket badge and a Make Public button. Do not use it for this bucket. A public bucket's files can be opened by anyone with the address, and copies already fetched by browsers cannot be recalled after you go private again. Use public buckets only for things like product images.

Signed links from your server

A browser should not hold your secret key. The usual pattern is for your server to create a signed upload link and hand it to the browser:

const admin = createClient({ projectId: "my-project", apiKey: process.env.PGB_SECRET_KEY });

const put = await admin.storage.createSignedUrl("attachments", `reports/${fileName}`, {
  method: "PUT",
  contentType: "application/pdf",
});
// return put.url to the browser, which then sends the file straight to it

Download links work the same way with createSignedUrl(bucket, path, { expiresIn: 900 }). Download links last at most 24 hours and upload links at most 1 hour. A link bound to a contentType only accepts exactly that type, and without one, uploads of HTML, SVG, XML and JavaScript are refused.

Habits that keep you safe

• Make the bucket private first, and public only on purpose.
• Name files by a generated id rather than the user's file name, to avoid clashes.
• Store the file's path in your database, linked to the user, and protect that table with the policies from the last lesson.
• Do not rely on keeping an address secret. Use signed links.

Recap

• Buckets hold files. Choose Public or Private when you create one.
• Copy Signed Link shares a private file for 15 minutes.
• Your server, with the secret key, creates signed download and upload links.
• Private files return "not found" to anyone without access.