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' });   // takes effect now

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 — and it attaches 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

All five run from the repository with one command each, and the full B2B document workspace 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, and we would rather say so than ship one for the announcement — there is no hosted API to expose over it.

The state of it, in numbers

Filelayer is alpha and nobody runs it in production. Should you depend on it? Probably not yet — and this section exists so you can decide that quickly instead of inferring it from what a landing page does not say.

• Version0.4.4 — alpha
• Known production deployments0
• Maintainers with commit rights1
• Independent security reviewnone
• Storage adapter against live AWS / Cloudflarenever run
• Tests, on Node 22 / 24 / 26, every commit324 across 74 suites
• Adversarial suite27 attacks, 0 breaches
• Runtime dependencies0
• LicenceApache-2.0, with a patent grant

What would change the numbers above, in the order it matters: production deployments that are not ours; the storage adapter proven against live R2 and S3 in CI; an independent review of schema.sql and authz.ts published in full; 1.0 with a frozen schema; a second maintainer. We report against that list publicly, including when a number stays at zero.

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.