Filelayer

Filelayer

The file layer for SaaS applications. A customer's security review asks who opened a file and who was refused. A link you sent has to stop working now. Someone asks to be erased from your logs. Filelayer answers all three for the files your users upload: per-file permissions, links you can take back, and an audit trail of every allowed and denied access, on your own Postgres. → [filelayer.dev](https://filelayer.dev)

You tell Filelayer who the caller is. Filelayer decides what they may do with a file, serves the bytes with the right headers, and writes the audit event. For file access that goes through Filelayer, that decision is made in one place, packages/core/src/authz.ts, so you write no ownership checks in route handlers, no presigned-URL expiry logic, and no per-route access rules of your own.

Built to be adopted without us. The quickstart, the guides, the examples

and llms.txt are written so that you, or your coding agent, can integrate it

alone. Where it breaks, open an issue.

Free and open source; paid plans add support and priority, see

pricing.

Alpha, and the numbers behind that word are all on one page:

should you depend on this? ·

what it does not do ·

roadmap to 1.0

// Public avatar

const { url } = await fl.files.put(bytes, { public: true });

// Private, user-owned const { id } = await fl.files.put(bytes, { owner: 'user_123' }); const file = await fl.files.get(id, { as: 'user_123' });

// Multi-tenant, role-controlled await fl.files.put(bytes, { org: 'acme', owner: 'user_123' });

// Shared with an expiry, a password and a download cap, and revocable const share = await fl.shares.create(id, { as: 'user_123', expiresIn: 3600, maxDownloads: 3, password: 'hunter2', }); await fl.shares.revoke(share.grantId, { as: 'user_123' }); // this link, now

// Shared with a named user, and taken back. unshare is the one you want for // a person: create() is not idempotent, so revoking a single grant id you // happen to be holding can leave an earlier one live. await fl.shares.create(id, { as: 'user_123', withUser: 'user_456' }); await fl.shares.unshare(id, { as: 'user_123', user: 'user_456' }); // all of it

Start at whichever line matches your problem. Complexity is incremental: each tier adds one concept, and no tier makes you pay for a concept you are not using. → docs/QUICKSTART.md

The three layers

your application          fl.files.put / get / list, fl.shares, fl.orgs

you pass YOUR user id; nothing here knows a uuid ─────────────────────────────────────────────────────────────────────── Filelayer ONE authorization function answers every request grants, roles, expiry, download caps, revocation the audit event, written in the decision's own transaction so the log cannot disagree with it ─────────────────────────────────────────────────────────────────────── your Postgres 9 tables. Filelayer owns the schema, you own the your bucket database. Bytes go to S3, R2, B2 or a directory behind one adapter; storage is replaceable

Filelayer sits between the two things you already run. It brings no database and no storage of its own, and zero runtime dependencies.

It is authorization middleware, not row-level security. It decides for calls made through it, in your process. The schema additionally refuses cross-tenant grants, cross-project identities and delegation that amplifies authority from *every* writer, including a psql session — those are constraints and triggers. But there is no RLS policy in schema.sql, and a direct SELECT against these tables is filtered by nothing. Filelayer composes with database-level enforcement; it does not replace it.

What it is for, and what it is not for

Worth the overhead when: files are private, belong to specific people or tenants, and their permissions change over time. Documents, contracts, attachments, exports, anything with a share link you might later want back.

Not worth the overhead when:

Against the two things you would otherwise do

The last two rows are losses and they are not close. We publish the full comparison, including every case we lose, in ARCHITECTURE-PROGRESSIVE.md §5. Short version: for a public avatar, Supabase is 10 lines and Filelayer is 16. If avatars are your whole problem, use Supabase.

The five security properties

These are the product. Each is enforced in the schema or the authorization engine, not by convention, and each has tests named after it.

Three more properties are enforced in the schema and documented in packages/core/SEMANTICS.md: atomic download counters (P6), deletion as a liveness predicate rather than a cascade (P7), and per-project identifier namespaces (P8).

Two consequences worth knowing before you adopt:

• Revocation actually works. fl.files.unpublish(id) makes a URL that has been printed, indexed and pasted into a support ticket stop working on the next request. No deletion, no key rotation, no cache purge. Supabase's getPublicUrl() is offline string concatenation, so it has no request at which to make that decision; deleting the object is the only withdrawal.
• This costs you a byte path. P4 is why the default is to serve bytes rather than hand out a presigned URL, and it is why the default path has no CDN in front of it. The two facts are the same fact. Redirect delivery trades a bounded revocation window for that CDN and is opt-in; see packages/core/SEMANTICS.md.

What backs that up

Said once, here, because every number in it is checked by a gate that fails the build when a public surface and the run disagree:

| Live object storage | 12 tests against live Cloudflare R2 and 12 against live AWS S3, every commit, plus a thirteenth each on the nightly run: an 11 MB multipart upload reassembled byte-exactly. R2 is