Filelayer

Filelayer

The file layer for SaaS applications. Public files and private files, with one authorization model behind both. → 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.

Looking for three to five design partners. We will help you integrate this and stay on hand while you do, in exchange for hearing where it breaks. 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:

What none of that measures is load, or anyone's production. The complete table, including the rows that are zero, is on the trust page.

The five that make people decline

The complete list is LIMITATIONS.md -- fourteen entries, each with its reasoning, shipped in the npm tarball so an install has it on disk. These five are the ones that should make you close the tab if they apply to you:

1. No CDN on the private delivery path. Bytes proxy through your application, and authenticated responses carry Cache-Control: no-store. That is not an oversight, it is P4: a URL that can be revoked is a URL that has to be asked about. An opt-in redirect mode trades a bounded revocation window of up to 300 seconds for cacheability. If your workload is public images at volume, use a bucket behind a CDN and come back when you need to take a URL back.

2. A grant id is not a person's access, and shares.create() still inserts a row per call by default. Two calls with an expiresIn are two legitimately different windows, so the engine cannot dedupe on its own. Pass an idempotencyKey and a retry returns the grant that already exists; without one, a double-clicked share button gives one reader two grants. revoke() now answers subjectCanStillRead, so revoking one grant and not removing somebody's access is visible in the reply rather than in an audit later. Use shares.unshare(fileId, { as, user }) to remove a named person, and note there is still no bound on how many live grants one subject may hold.

   The cost of that is no longer the problem it was. Until 0.17.0 the read paid one recursive chain walk per grant held: 4.3 ms at five, 5 911 ms at a hundred thousand. The short-circuit moved into SQL and the cliff went with it — 30.4 ms at two hundred thousand concentrated grants, 1.13x the owner read on the same file, measured in benchmark/load/RESULTS.md H4b. What remains is a correctness trap, not a performance cliff.

3. No resumable or multipart upload. One signed PUT, one object. A large upload that fails starts over, and fl.files.put() holds the whole body in memory -- only the core fl.upload() takes a stream, and neither imposes a size ceiling, so that is yours to enforce.

4. Org admins and owners can read private files. Deliberate: retention and legal hold are useless if the people accountable for them cannot see what they are holding. But it is a policy decision, and if you need to exclude the operator you need envelope encryption, which we do not have.

5. Alpha, and the schema has changed twelve times. Any 0.x → 0.(x+1) may break the API, the schema or both. Every break has a numbered entry in MIGRATIONS.md and a runnable file under migrations/ that CI applies to the previous release's schema and checks produces the next one -- but there is no LTS branch, no backporting, and no independent security review.

Install

npm install @filelayer/core

Requires Node ≥ 22.18. The package ships compiled JavaScript and type declarations in dist/; the TypeScript source and the full test suite are in the tarball as well, so every claim on this page is inspectable from what you installed.

That install has zero runtime dependencies. Filelayer talks to your Postgres and your bucket, so it ships neither. The throwaway instance below is the one exception: quickstart() runs on an embedded WebAssembly Postgres, declared as an optional peer dependency so that it never lands in a production node_modules. Add it if you want the throwaway instance, and skip it otherwise. createTestDb() will tell you, by name, if you need it:

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

Install PGlite with that version constraint. Filelayer supports the 0.3.x line, which is what peerDependencies declares and what the suite runs against. 0.5.x is not supported: we ran the full suite against 0.5.8 and it does not pass, so the range has not been widened. PGlite's latest on npm is a 0.5.x release, so omitting the constraint can install a version outside the supported range, and npm then refuses the whole tree with ERESOLVE. The quotes are for your shell, not for npm: ^ is a glob operator under zsh with extendedglob and an escape character in cmd.exe.

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

const fl2 = await Filelayer.quickstart();          // PGlite + in-memory bytes
const { url: avatarUrl } = await fl2.files.put(bytes, { public: true });

quickstart() is ephemeral: everything is lost when the process exits.

Serving the bytes

Authorizing a read is not the same as answering the request. Two handlers do the second, and which one you want is decided by your runtime, not by preference:

They are the same two routes with the same behaviour. deliveryFetch returns null for a request it does not own, so a catch-all route can fall through to the rest of your application instead of swallowing it.

Mounting the wrong one is the most common integration failure we see. A node:http handler in an App Router route exports a function with the wrong shape; the symptom is not a type error at the mount point but a request that never answers.

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

const serve = deliveryFetch(fl, {
  principal: async () => ({ as: await currentUserId() }),
});

export async function GET(req: Request) {
  return (await serve(req)) ?? new Response('Not found', { status: 404 });
}

Both parse Range, which matters more than it sounds: a <video> element will not let the user scrub until a range request is answered, and a PDF reader asks for the end of the file first. An invalid range is answered 200 with the whole representation, as RFC 9110 requires, and only a range that parsed cleanly and cannot be satisfied gets 416 with Content-Range: bytes */<size>. Accept-Ranges: bytes goes on the plain 200 as well, because that is how a client learns it may seek at all.

Two defaults to know before you mount either one. disposition defaults to attachment, which downloads rather than plays, so a media route needs disposition: 'inline'. And redirecting to a presigned URL instead of proxying is opt-in, because it moves revocation out of your process for the life of the URL; it requires a storage adapter that can sign, and it refuses with redirect_not_acknowledged until the configuration says so out loud. docs/guides/serving-private-files.md is the measured comparison of the two.

Everything else, one page per thing

That is the whole integration for most applications: install, quickstart() to see it work, then a real database and one of these handlers. The rest is a page each, and every one of them ships inside the npm tarball, so an install has them on disk.

The guides are also rendered at filelayer.dev/guides, which is the same markdown and is easier to read than a repository file.

Versioning

Pre-1.0. The version is 0.MINOR.PATCH and the promise is deliberately narrow:

• 0.x → 0.(x+1) may break the API, the schema, or both. Every break is in packages/core/CHANGELOG.md, and every schema break has a migration in packages/core/MIGRATIONS.md.
• 0.x.y → 0.x.(y+1) is additive or a fix. No schema change that requires action, no signature change.
• There is no long-term support branch and no backporting before 1.0.

The schema has changed twelve times. MIGRATIONS.md has fifteen numbered entries, ten of which carry forward SQL; the other two schema changes predate the oldest tag in the repository and cannot be verified against an earlier schema. Budget an upgrade against that file rather than against this paragraph. Every figure in this paragraph is derived from migrations/manifest.json by check:versions, which fails the build if any of them drifts — because these numbers were last corrected by hand at 0.15.0 and had drifted again by 0.33.0.

Which version a database is at is readable off the database. schemaStatus(db) reports where a database is, what this build expects, and which files under migrations/ are outstanding. It issues no DDL: your application owns the migration runner, which is the position MIGRATIONS.md §2 takes and is keeping.

Layout

Documents

• docs/QUICKSTART.md — install → first file → the advanced capabilities
• LIMITATIONS.md — the complete list of what this does not do, fourteen entries with their reasoning
• ROADMAP.md — the nine things an outside evaluator said would change its answer, eight of them done, and what is deliberately not coming
• docs/guides/ — four answers to questions people actually ask, useful whether or not you use this library; the code in them is executed in CI
• packages/core/SEMANTICS.md — the exact behaviour of every edge: liveness, delegation, deletion, the audit chain
• packages/core/MIGRATIONS.md — how schema changes are delivered and what the pre-1.0 compatibility promise is
• packages/core/CHANGELOG.md — the real history, including the security defects we found in ourselves
• ARCHITECTURE-PROGRESSIVE.md — the tier model, lines of code versus the alternatives, and where we lose
• architecture/TIER5-DESIGN-NOTE.md — large files, streaming, range requests, CDN
• llms.txt — the same map, written for an agent implementing an integration
• openapi.yaml — the two HTTP routes the library serves, as OpenAPI 3.1

Every link above points at GitHub, and an installed consumer may have no network and no browser. The npm package therefore carries the same files on disk under node_modules/@filelayer/core/, and three resolve as subpath imports — @filelayer/core/llms.txt, @filelayer/core/openapi.json and @filelayer/core/schema.sql — so a reader does not have to guess at the layout of node_modules.

License

Apache-2.0, with an express patent grant and a patent-retaliation termination clause. No copyleft obligation on your own code; preserve the notices and state significant changes. LICENSE and NOTICE both ship in the tarball, so the grant travels with the artifact.

SPDX-License-Identifier: Apache-2.0
Copyright 2026 Technology Pro Bono S.L.

Dependencies. No runtime dependencies, and a job in CI fails the build if one appears. The third-party packages are all devDependencies: @electric-sql/pglite (Apache-2.0), also an optional peer dependency and what quickstart() runs on, plus pg and embedded-postgres for the contention tests that need two real backends. A production install contains none of them, and no third-party code is copied or embedded anywhere in this repository.

Contributing, security and conduct

• CONTRIBUTING.md — how to set up, what npm run verify covers, and what a pull request needs.
• SECURITY.md — report vulnerabilities privately, never as a public issue. Includes our disclosure timetable and what is in and out of scope.
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1.

Bugs, questions and "this document is wrong" reports go to GitHub Issues. A report that the product does not do what this README says is the most valuable thing you can send us, and every one so far has been fixed the same day.