The file layer for SaaS applications.

One file model, from simple to complex

A public avatar and a board deck under legal hold are the same row, authorized by the same function, on the same table. There is no second code path for the simple case, and no migration when the simple case grows up.

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

// The same file, now owned by someone
const { id } = await fl.files.put(bytes, { owner: 'user_123' });
const file  = await fl.files.get(id, { as: 'user_123' });

// The same file, now inside a tenant with roles
await fl.files.put(bytes, { org: 'acme', owner: 'user_123' });

// The same file, now shared — with an expiry, a 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

// For a named person, unshare: create() is not idempotent, so one grant id
// is not necessarily all of their access.
await fl.shares.unshare(id, { as: 'user_123', user: 'user_456' });

Five concepts, and you only meet the ones you use.

Don't rebuild file semantics in every application

Storage is solved. What is not solved is everything that attaches to a file once real people start using your product. It arrives one question at a time, usually in this order.

Each of these is maybe fifty lines. The cost is that they end up as fifty lines in your application, in different route handlers, written at different times by different people. Filelayer moves them behind one interface so a new file path cannot quietly skip one.

How it fits

For file access that goes through Filelayer, the decision is made in one place. That is the whole value of the middle layer: you write no ownership checks in route handlers, no presigned-URL expiry logic, and no per-route access rules of your own. It is authorization middleware, not row-level security. A client that queries your Postgres directly bypasses it. Where that boundary is, exactly →

From an avatar to an audit trail

The same API the whole way up. Each rung adds one concept, and no rung makes you pay for a concept you are not using.

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

// later — the URL is printed, indexed, pasted into a ticket
await fl.files.unpublish(id);
// the next request 404s. No deletion, no key rotation, no cache purge.

const { id } = await fl.files.put(bytes, { owner: 'alice' });

await fl.files.get(id, { as: 'alice' });   // bytes
await fl.files.get(id, { as: 'bob' });     // throws 404
await fl.files.get(id);                    // throws 404

await fl.orgs.create('acme', { name: 'Acme Inc', owner: 'ceo' });
await fl.orgs.setRole('acme', 'analyst', 'member', { as: 'ceo' });

const { id } = await fl.files.put(deck, {
  org: 'acme', owner: 'ceo', name: 'board-deck.pdf',
});

await fl.files.get(id, { as: 'analyst' });  // 404 insufficient_role

const share = await fl.shares.create(id, {
  as: 'ceo', expiresIn: 3600, maxDownloads: 3, password: 'hunter2',
});

await fl.shares.redeem(share.secret, { password: 'hunter2' });  // bytes

// ...forwarded to someone it should not have been
await fl.shares.revoke(share.grantId, { as: 'ceo' });

await fl.shares.redeem(share.secret, { password: 'hunter2' });  // 404 grant_revoked

for (const row of await fl.orgs.audit('acme', { as: 'ceo' }))
  console.log(row.summary);

ceo       file.create   allow                    board-deck.pdf @acme
analyst   file.read     deny:insufficient_role   board-deck.pdf @acme
ceo       file.share    allow                    board-deck.pdf @acme
anonymous file.read     allow                    board-deck.pdf @acme
ceo       grant.revoke  allow                    board-deck.pdf @acme
anonymous file.read     deny:grant_revoked       board-deck.pdf @acme

Tiers 1 to 3 each run from the repository with one command. Sharing and the audit trail come together in the B2B document workspace, which runs over HTTP: examples/ →

One case where a bucket is still the better answer today: public assets served at CDN volume. Filelayer's default byte path goes through your process, so there is no CDN in front of it. Filelayer earns its place when a file needs an owner, an expiry, or a link you can take back.

Install, and have a file in the same session

npm install @filelayer/core
npm install --save-dev "@electric-sql/pglite@^0.3.11"

import { Filelayer } from '@filelayer/core';

const fl = await Filelayer.quickstart({ baseUrl: 'http://localhost:3000' });
const bytes = new TextEncoder().encode('hello');

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

Readable by machines, not just by people

Every surface below already exists in the repository and ships inside the npm tarball. This is not a roadmap section.

Using a coding agent? Point it at the map:

Add Filelayer to my app: https://github.com/filelayer/filelayer/blob/main/llms.txt

No MCP server yet. There is no hosted API to put behind one.

The state of it, in numbers

Every figure below is produced by a job you can read, on every commit, and is reproducible from the repository. The full set — including what this project has not earned yet — is on the trust page, which is where we keep the numbers that do not flatter us.

• Version0.33.0 — alpha
• Storage adapter against live Cloudflare R212 tests, every commit
• Storage adapter against live AWS S312 tests, every commit
• Tests against a real PostgreSQL, every commit729 across 161 suites
• Concurrency, against a real PostgreSQL8 tests, every commit
• Adversarial suite27 attacks, 0 breaches
• Runtime dependencies0
• LicenceApache-2.0, with a patent grant

Production deployments, maintainers, independent review and the rest of the set: the trust page →

The full trust page →  ·  Security policy →  ·  Where we are the wrong tool →

Give your files a model

Not a demo account. A file you actually own, in a process you actually run.

npm install @filelayer/core

If something on this page confused you, that is a defect and we want the report.