Bucket Permissions

A bucket's permissions block answers one question per operation: who may do this? It uses the same three-shape PermissionValue format as table permissions, so nothing new has to be learned to read it.

Value	Means
all	Everyone, including unauthenticated requests.
authenticated	Any user with a session, whatever their role.
[admin, editor]	Only the listed roles.

buckets:
  - name: documents
    maxFileSize: 52428800
    allowedMimeTypes: [application/pdf, text/csv]
    permissions:
      upload: [admin, editor]
      download: authenticated
      sign: authenticated
      signUpload: [admin, editor]
      delete: [admin]

The Five Operations

Operation	Governs	Default when omitted
upload	Writing a new file into the bucket.	authenticated
download	Reading a file back out.	all on a public bucket, authenticated otherwise
sign	Minting a signed download URL.	[admin]
signUpload	Minting a signed upload URL.	[admin]
delete	Removing a file from storage.	[admin]

Omitting permissions entirely applies every default above. The consequence worth internalising: signing is admin-only until you say otherwise. A bucket that a member should be able to hand out download links for needs sign: authenticated written down; silence means no.

What Is Enforced Today

sign and signUpload are enforced by the signing endpoints, with role resolution and an admin override. The other three are declared in the schema but not yet consulted by the bucket file routes, which gate on the bucket's public flag and the presence of a session instead:

Request	Answer
Upload or delete on a public bucket	Allowed, session or not.
Upload or delete on a private bucket	401 without a session; allowed with one.
Download on a private bucket, no session	404 (anti-enumeration — never 403).
Sign without a session	401.
Sign with a session but no matching permission	404, so the permission boundary stays invisible.

Admin Override and Anonymous Callers

Two rules cut across every signing check:

• admin always passes. A role named admin can sign on any bucket regardless of what the permission lists.
• all still needs a session on the signing endpoints. The signing routes reject anonymous callers with 401 before any permission is evaluated, so sign: all widens access to every logged-in user, not to the public. To serve files without a session, make the bucket public: true — that is the switch for anonymous reads.

Related Pages

• Buckets Overview — the bucket a permission block belongs to.
• Storage Backends — where permitted bytes are written.
• Signed URLs — the flow that reads sign and signUpload.
• Roles & RBAC — where the role names come from.
• Table Permissions — the same value format on tables.