@filelayer/core 0.3.0

package/dist/filelayer.js

@@ -0,0 +1,1360 @@
+/**
+ * FILELAYER -- the surface an application developer actually touches.
+ *
+ * Design rule for this file: every method that touches a file or an org calls
+ * into the authorization engine and does nothing before it. There is no
+ * "internal" variant that skips the check, because the moment such a variant
+ * exists someone will call it from a route handler at 6pm on a Friday.
+ *
+ * SECOND design rule, added after the security review: this file contains no
+ * security LOGIC, only security PLUMBING. Every rule that used to live here as
+ * a "patch at the wrong layer" has moved into `authz.ts` or `schema.sql`:
+ *
+ *   - capability attenuation on share       -> authorizeShare() + a BEFORE
+ *                                              INSERT trigger on file_grant
+ *   - the 410/409 existence-oracle downgrade
+ *     and its `hasStanding()` helper        -> evaluation order in authorize()
+ *   - the membership / viewer checks in
+ *     upload()                              -> authorizeOrg('create_file')
+ *   - the admin check in auditLog()         -> authorizeOrg('read_audit')
+ *   - the unaudited early return in redeem()
+ *     for unknown secrets                   -> the engine's system chain
+ *
+ * Errors are thrown as `FilelayerError`, already collapsed through
+ * `toPublicError`, so the developer cannot accidentally return our internal
+ * deny reason to an attacker. That collapsing is a security-sensitive decision
+ * we make once, here, instead of asking the developer to make it per-route.
+ */
+import { randomBytes, randomUUID } from 'node:crypto';
+import { auditUnresolvedSecret, authorize, authorizeList, authorizeMembershipChange, authorizeOrg, authorizeRevoke, authorizeShare, schemaRefusal, toPublicError, } from "./authz.js";
+import { CommitThenThrow, withTransaction, } from "./db.js";
+import { PostgresStore, DEFAULT_PROJECT_ID, isUuid, toCapabilities, LIST_DEFAULT_LIMIT, LIST_MAX_LIMIT, } from "./store.js";
+import { canList, canPresign, collectStream, } from "./storage.js";
+import { FilesApi, OrgsApi, SharesApi } from "./simple.js";
+import { contentDisposition, deliveryHeaders, isActiveContentType, redirectHeaders, resolveRedirectConfig, safeContentType, } from "./delivery.js";
+import { FilelayerError } from "./errors.js";
+// Declared in `errors.ts` so that `delivery.ts` can classify errors without
+// importing this module (which imports `delivery.ts`). Re-exported here because
+// this is where every existing caller imports it from.
+export { FilelayerError };
+export class Filelayer {
+    store;
+    db;
+    storage;
+    opts;
+    _files;
+    _orgs;
+    _shares;
+    /** Null unless redirect delivery was configured AND acknowledged. */
+    redirect;
+    constructor(db, storage, opts = {}) {
+        this.db = db;
+        this.storage = storage;
+        this.opts = opts;
+        // A provider name is half of an object's primary identity (see the UNIQUE
+        // index). An adapter that does not supply one is a configuration error, not
+        // a default to guess at -- guessing is how it became 'memory' in the first
+        // place.
+        if (typeof storage.provider !== 'string' || storage.provider.length === 0) {
+            throw new Error('storage adapter must declare a non-empty `provider`');
+        }
+        this.store = new PostgresStore(db, {
+            ...(opts.projectId !== undefined ? { projectId: opts.projectId } : {}),
+        });
+        this.redirect = opts.redirectDelivery ? resolveRedirectConfig(opts.redirectDelivery) : null;
+    }
+    /**
+     * Run a unit of work in one transaction, on one connection.
+     *
+     * `fn` receives a store bound to the transaction, so the audit events the
+     * engine writes and the mutation they describe commit together -- and so
+     * `audit_append()`'s advisory lock, which is a `pg_advisory_XACT_lock`, is
+     * held across the whole unit rather than across one autocommit statement.
+     *
+     * THE ONE SUBTLETY, AND IT IS THE IMPORTANT ONE.
+     *
+     * A DENIAL writes an audit event and then throws. If a throw always rolled
+     * back we would lose exactly the events P5 exists to keep, silently, while
+     * the caller still saw their 403 -- an audit log that omits refusals is worse
+     * than no audit log, because it looks complete.
+     *
+     * So `FilelayerError` -- and ONLY `FilelayerError` -- is treated as a DECIDED
+     * outcome: commit, then throw. Every `FilelayerError` this library raises is
+     * a decision or a lookup miss, never a half-applied mutation; the one place
+     * that could have been (the schema attenuation backstop in `share()`) uses a
+     * SAVEPOINT so the failed INSERT is undone before the deny event is written.
+     * Anything else -- a driver error, an unanticipated constraint, a bug --
+     * rolls the whole unit back.
+     */
+    #transaction(fn) {
+        return withTransaction(this.db, async (tx) => {
+            try {
+                return await fn(tx, this.store.withDb(tx));
+            }
+            catch (err) {
+                if (err instanceof FilelayerError)
+                    throw new CommitThenThrow(err);
+                throw err;
+            }
+        });
+    }
+    /**
+     * A throwaway, in-process instance: PGlite + in-memory bytes.
+     *
+     * For a five-minute first run and for tests. **Everything is lost when the
+     * process exits** -- there is no file on disk and no bucket. Production is
+     * `new Filelayer(pgPool, new S3Storage({...}), { baseUrl })`; see
+     * docs/QUICKSTART.md, which does not hide the three configuration steps.
+     */
+    static async quickstart(opts = {}) {
+        const { createTestDb } = await import("./db.js");
+        const { MemoryStorage } = await import("./storage.js");
+        const { db } = await createTestDb();
+        return new Filelayer(db, new MemoryStorage(), {
+            baseUrl: opts.baseUrl ?? 'http://localhost:3000',
+        });
+    }
+    /** Where public URLs are rooted. Read-only; set once at construction. */
+    get baseUrl() {
+        return this.opts.baseUrl;
+    }
+    /** The project this instance is bound to. Null means unscoped. */
+    get projectId() {
+        return this.store.projectId;
+    }
+    // ---------------------------------------------------------------------------
+    // The tiered surface (see src/simple.ts). Purely additive: every method below
+    // this line is unchanged, and the facade calls into it rather than around it.
+    // ---------------------------------------------------------------------------
+    get files() {
+        return (this._files ??= new FilesApi(this));
+    }
+    get orgs() {
+        return (this._orgs ??= new OrgsApi(this));
+    }
+    get shares() {
+        return (this._shares ??= new SharesApi(this));
+    }
+    // ---------------------------------------------------------------------------
+    // Tenancy
+    // ---------------------------------------------------------------------------
+    /**
+     * Create an organization, optionally with its first owner.
+     *
+     * Creating a tenant is a control-plane operation: there is no principal
+     * inside the system yet who could be authorized to do it, and pretending
+     * otherwise would be theatre. Passing `ownerActorId` closes the bootstrap
+     * gap that would otherwise exist -- an org is never memberless, so there is
+     * never a "the org has no members yet, let anyone in" path for an attacker to
+     * find. Every subsequent membership change is authorized (see `addMember`).
+     */
+    async createOrg(externalId, name, opts = {}) {
+        const { rows } = await this.db.query(`INSERT INTO org (project_id, external_id, name)
+       VALUES (coalesce($3::uuid, '${DEFAULT_PROJECT_ID}'::uuid), $1, $2) RETURNING id`, [externalId, name ?? null, this.projectId]);
+        const id = rows[0].id;
+        if (opts.ownerActorId) {
+            await this.db.query(`INSERT INTO membership (org_id, actor_id, role) VALUES ($1,$2,'owner')`, [id, opts.ownerActorId]);
+            await this.store.audit({
+                orgId: id,
+                action: 'member.bootstrap',
+                decision: 'allow',
+                actorId: opts.ownerActorId,
+                fileId: null,
+                context: { targetActorId: opts.ownerActorId, toRole: 'owner', via: 'org.create' },
+            });
+        }
+        return { id };
+    }
+    async createActor(externalId) {
+        const { rows } = await this.db.query(`INSERT INTO actor (project_id, external_id)
+       VALUES (coalesce($2::uuid, '${DEFAULT_PROJECT_ID}'::uuid), $1) RETURNING id`, [externalId, this.projectId]);
+        return { id: rows[0].id };
+    }
+    /**
+     * Register a customer application. Control plane; see the note on the
+     * lifecycle methods below for why these three take no principal.
+     */
+    async createProject(key, name) {
+        const { rows } = await this.db.query(`INSERT INTO project (key, name) VALUES ($1, $2)
+         ON CONFLICT (key) DO UPDATE SET key = EXCLUDED.key
+       RETURNING id`, [key, name ?? null]);
+        return { id: rows[0].id };
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle: soft delete and restore (P7)
+    // ---------------------------------------------------------------------------
+    //
+    // WHY THESE ARE CONTROL-PLANE OPERATIONS AND TAKE NO `Principal`.
+    //
+    // It is tempting to require `owner` in the org to delete it. That design has
+    // a trap in it: deleting an org kills membership-derived access (that is the
+    // whole point), so the moment it succeeds NOBODY holds a role in that org and
+    // therefore nobody can ever restore it. An authorization rule that makes its
+    // own inverse unreachable is not a rule, it is a one-way door.
+    //
+    // So org and actor lifecycle sits where org and actor CREATION already sits:
+    // the control plane, authenticated by the customer's project credential at
+    // the API boundary rather than by an end-user principal inside the model.
+    // That boundary sits above the engine and is the same one that
+    // authenticates every other request. This is stated as an explicit
+    // operational requirement in SEMANTICS.md rather than left implicit.
+    //
+    // Every one of them is audited to the affected tenant's chain, so a
+    // control-plane action is as visible in the compliance record as a user one.
+    /**
+     * Soft-delete a tenant. Every grant on every file in it is dead on the next
+     * request; every membership stops conferring anything. Nothing is erased and
+     * no row a retention hold protects is touched, so this cannot be used to
+     * defeat retention -- see SEMANTICS.md.
+     */
+    async softDeleteOrg(orgId) {
+        await this.#setOrgDeleted(orgId, true);
+    }
+    /** Exactly reverses `softDeleteOrg`. Liveness is derived, so nothing is lost. */
+    async restoreOrg(orgId) {
+        await this.#setOrgDeleted(orgId, false);
+    }
+    async #setOrgDeleted(orgId, deleted) {
+        if (!isUuid(orgId))
+            throw new FilelayerError(404, 'not_found');
+        const { rows } = await this.db.query(`UPDATE org SET deleted_at = ${deleted ? 'now()' : 'NULL'}
+        WHERE id = $1 AND ($2::uuid IS NULL OR project_id = $2::uuid)
+        RETURNING id`, [orgId, this.projectId]);
+        if (!rows[0])
+            throw new FilelayerError(404, 'not_found');
+        await this.store.audit({
+            orgId,
+            action: deleted ? 'org.delete' : 'org.restore',
+            decision: 'allow',
+            actorId: null,
+            fileId: null,
+            context: { via: 'control_plane' },
+        });
+    }
+    /**
+     * Soft-delete an identity.
+     *
+     * Three things die at once, and all three are derived rather than written:
+     * their role-derived access, every grant issued TO them, and every grant they
+     * ISSUED. The third is the judgement call; the reasoning is in schema.sql at
+     * `grant_scope_is_live` and in SEMANTICS.md. It is loud on purpose: deleting
+     * a prolific sharer revokes a lot of links, and that is the correct reading of
+     * P4, not a side effect.
+     */
+    async softDeleteActor(actorId) {
+        await this.#setActorDeleted(actorId, true);
+    }
+    async restoreActor(actorId) {
+        await this.#setActorDeleted(actorId, false);
+    }
+    async #setActorDeleted(actorId, deleted) {
+        if (!isUuid(actorId))
+            throw new FilelayerError(404, 'not_found');
+        const { rows } = await this.db.query(`UPDATE actor SET deleted_at = ${deleted ? 'now()' : 'NULL'}
+        WHERE id = $1 AND ($2::uuid IS NULL OR project_id = $2::uuid)
+        RETURNING id`, [actorId, this.projectId]);
+        if (!rows[0])
+            throw new FilelayerError(404, 'not_found');
+        // Attributed to every org the identity is a member of: "who lost access
+        // here, and when" must be answerable from each affected tenant's own chain.
+        const { rows: orgs } = await this.db.query(`SELECT org_id FROM membership WHERE actor_id = $1`, [actorId]);
+        for (const o of orgs) {
+            await this.store.audit({
+                orgId: o.org_id,
+                action: deleted ? 'actor.delete' : 'actor.restore',
+                decision: 'allow',
+                actorId,
+                fileId: null,
+                context: { via: 'control_plane', targetActorId: actorId },
+            });
+        }
+    }
+    /**
+     * Soft-delete a customer application: every org, every file and every grant
+     * inside it stops working immediately. This is the "we terminated that
+     * customer" operation and it is the widest blast radius in the system.
+     */
+    async softDeleteProject(projectId) {
+        await this.#setProjectDeleted(projectId, true);
+    }
+    async restoreProject(projectId) {
+        await this.#setProjectDeleted(projectId, false);
+    }
+    async #setProjectDeleted(projectId, deleted) {
+        if (!isUuid(projectId))
+            throw new FilelayerError(404, 'not_found');
+        const { rows } = await this.db.query(`UPDATE project SET deleted_at = ${deleted ? 'now()' : 'NULL'}
+        WHERE id = $1 RETURNING id`, [projectId]);
+        if (!rows[0])
+            throw new FilelayerError(404, 'not_found');
+        // The system chain: a project is above every tenant, so there is no single
+        // tenant to charge the event to, and writing it to all of them would let a
+        // control-plane action inflate an arbitrary number of customer chains.
+        await this.store.audit({
+            orgId: null,
+            action: deleted ? 'project.delete' : 'project.restore',
+            decision: 'allow',
+            actorId: null,
+            fileId: null,
+            context: { chain: 'system', projectId, via: 'control_plane' },
+        });
+    }
+    /**
+     * Add a member, or change an existing member's role.
+     *
+     * This used to take no principal at all. Anyone who could reach it could
+     * make anyone an owner of any org, and nothing was written to the audit log.
+     * Membership is the privilege that confers every other privilege, so it is
+     * now authorized by the same engine as everything else and audited on every
+     * outcome.
+     */
+    async addMember(principal, orgId, actorId, role) {
+        const decision = await authorizeMembershipChange(this.store, principal, orgId, actorId, role);
+        this.#raise(decision);
+        await this.db.query(`INSERT INTO membership (org_id, actor_id, role) VALUES ($1,$2,$3)
+       ON CONFLICT (org_id, actor_id) DO UPDATE SET role = EXCLUDED.role`, [orgId, actorId, role]);
+    }
+    async removeMember(principal, orgId, actorId) {
+        const decision = await authorizeMembershipChange(this.store, principal, orgId, actorId, null);
+        this.#raise(decision);
+        await this.db.query(`DELETE FROM membership WHERE org_id = $1 AND actor_id = $2`, [
+            orgId,
+            actorId,
+        ]);
+    }
+    // ---------------------------------------------------------------------------
+    // Files
+    // ---------------------------------------------------------------------------
+    /**
+     * Creation is the one file operation with no file to authorize against, so
+     * the question is org-scoped: does this actor hold `create_file` in this org?
+     * That is now asked of the engine rather than answered here.
+     *
+     * SIGNATURE CHANGE. This used to take a bare
+     * `actorId: string` while every other method took a `Principal`. That
+     * inconsistency was itself the defect: at the one call site in the example the
+     * developer passed `b.uploaderId` -- a value out of the REQUEST BODY -- rather
+     * than the authenticated actor, because the parameter's type did not tell them
+     * which one it wanted. Files are private-by-default AND owner-readable, so
+     * forging `owner_id` hands the wrong person permanent read access to the
+     * document, silently. A `Principal` is not confusable with a request field.
+     */
+    async upload(principal, orgId, input) {
+        const actorId = principal.actorId;
+        // DELIBERATELY OUTSIDE THE TRANSACTION, and the reason is the storage write
+        // that has to happen between this and the INSERT.
+        //
+        // With `emitAllow: false` this call writes AT MOST ONE STATEMENT: an audit
+        // event on the deny path, which `audit_append()` already makes atomic on its
+        // own. There is no mutation for it to be atomic *with*. Wrapping it would
+        // mean either holding a database connection open across the whole object
+        // upload -- minutes, for a large file, on a pooled connection -- or opening a
+        // second transaction anyway. The allow event is emitted below, inside the
+        // transaction, carrying the file id.
+        const decision = await authorizeOrg(this.store, principal, orgId, 'create_file', {
+            action: 'file.create',
+            emitAllow: false, // the allow event is emitted below, with the file id on it
+        });
+        this.#raise(decision);
+        // `authorizeOrg` denies an anonymous principal before we get here, so the
+        // uploader is known. The engine is the thing that established that, which
+        // is the point: ownership is derived from the authorized identity and can
+        // no longer be supplied alongside it.
+        const uploaderId = actorId;
+        const id = randomUUID();
+        const storageKey = `${orgId}/${id}`;
+        const now = Date.now();
+        const expiresAt = input.expiresIn ? new Date(now + input.expiresIn * 1000) : null;
+        const retainUntil = input.retainFor ? new Date(now + input.retainFor * 1000) : null;
+        const visibility = input.visibility ?? 'private';
+        // ORDERING: BYTES FIRST, METADATA SECOND. See the long note in db.ts.
+        //
+        // The storage write cannot join the transaction, so one of the two possible
+        // orderings has to lose. Committing metadata first and crashing would leave
+        // a 'ready' file whose object does not exist -- permanent, customer-visible
+        // data loss on a row the customer can see in a listing. Writing bytes first
+        // and crashing leaves an object no row points at: unreachable (the key is a
+        // fresh UUID, never reissued, and every read path starts from a `file` row)
+        // and therefore purely a storage cost. That is the cheaper failure and it is
+        // the one we take. `collectStorageOrphans()` cleans up; running it is a
+        // required operational job, not an optional one.
+        //
+        // It also means the adapter, not the caller, reports how many bytes exist.
+        const put = await this.storage.put(storageKey, input.body, input.contentType, {
+            ...(input.size !== undefined ? { contentLength: input.size } : {}),
+        });
+        return this.#transaction(async (tx, store) => {
+            const { rows } = await tx.query(`INSERT INTO file
+           (id, org_id, owner_id, name, content_type, size_bytes, storage_provider,
+            storage_key, state, visibility, expires_at, retain_until, metadata)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,'ready',$9,$10,$11,$12::jsonb)
+         RETURNING id, org_id, owner_id, name, content_type, size_bytes,
+                   storage_provider, storage_key, state, visibility, expires_at,
+                   retain_until, created_at`, [
+                id,
+                orgId,
+                uploaderId,
+                input.name,
+                input.contentType,
+                // What was actually written, not what the caller claimed.
+                put.bytes,
+                // THE FIX. This was the literal 'memory'.
+                this.storage.provider,
+                storageKey,
+                visibility,
+                expiresAt?.toISOString() ?? null,
+                retainUntil?.toISOString() ?? null,
+                JSON.stringify(input.metadata ?? {}),
+            ]);
+            // Same transaction as the INSERT it describes. Before this, a failure
+            // between the two produced a file with no audit record -- in a product
+            // whose headline is a tamper-evident audit trail, an intact chain that
+            // simply does not mention the upload.
+            await store.audit({
+                orgId,
+                action: 'file.create',
+                decision: 'allow',
+                actorId: uploaderId,
+                fileId: id,
+                context: { visibility, storageProvider: this.storage.provider },
+            });
+            await store.recordUsage(orgId, 'write', put.bytes);
+            // Metering counts distinct FILE-OWNING USERS as well as bytes, because
+            // authorization load tracks people rather than volume. The write path is
+            // the only place a new owner can appear, so it is the only place this can
+            // be recorded.
+            await store.recordFileOwner(orgId, uploaderId);
+            return toFileRecord(rows[0]);
+        });
+    }
+    /**
+     * Read a file's bytes, WITH the headers required to serve them safely.
+     *
+     * The `headers` field closes a header-handling defect. Before it, this method returned a
+     * `Uint8Array` and the application decided what `Content-Type`,
+     * `Content-Disposition`, `X-Content-Type-Options` and `Cache-Control` to put
+     * on the response -- three security-sensitive decisions the library was
+     * handing back to the developer while claiming to have removed them, and
+     * which the example got wrong. They are computed here now, from the file
+     * record, with no option to disable them. See `delivery.ts`.
+     *
+     * This path now CHARGES the download cap. See `deliver()` below for the
+     * semantics and the reasoning.
+     */
+    async read(principal, fileId, opts = {}) {
+        // The buffered convenience form. It is `readStream()` plus a collect, so
+        // there is exactly one authorization path, one reservation and one audit
+        // event whichever form a caller uses. It FORCES proxy mode: a buffered read
+        // of a redirect is a contradiction, and silently fetching the presigned URL
+        // ourselves would spend the redirect's egress budget AND the proxy's.
+        const d = await this.readStream(principal, fileId, { ...opts, mode: 'proxy' });
+        if (d.mode !== 'proxy')
+            throw new FilelayerError(500, 'internal', 'unexpected_redirect');
+        const body = await collectStream(d.body);
+        return {
+            file: d.file,
+            body,
+            headers: d.headers,
+            ...(d.grantId ? { grantId: d.grantId } : {}),
+            remainingDownloads: d.remainingDownloads,
+        };
+    }
+    /**
+     * The streaming read. Same decision, same charge, same audit -- no buffer.
+     *
+     * Returns either a `ProxyDelivery` (bytes, as a stream) or, when redirect
+     * delivery is configured AND this delivery is eligible, a `RedirectDelivery`
+     * (a 302 to a short-lived presigned URL). The mode is on the returned object
+     * and in the audit log; nothing about it is implicit.
+     */
+    async readStream(principal, fileId, 
+    /**
+     * `mode` defaults to 'auto', which means "apply this instance's redirect
+     * policy". On an instance that has not configured `redirectDelivery` -- the
+     * default -- that policy is "never redirect", so 'auto' and 'proxy' are the
+     * same thing and nothing becomes cacheable that was not before. Pass
+     * 'proxy' to force proxying on an instance that HAS opted in.
+     */
+    opts = {}) {
+        // THE DECISION AND THE CHARGE, IN ONE TRANSACTION.
+        //
+        // `authorize()` writes the access event and `consumeDownload()` spends the
+        // cap. Those two were separate autocommit statements, so a crash between
+        // them left an allow event for a delivery that was never charged, or -- on
+        // the redeem path -- a charge with no event. They now commit together.
+        const reserved = await this.#transaction(async (tx, store) => {
+            const decision = await authorize(store, principal, fileId, 'read');
+            this.#raise(decision);
+            return this.#reserve(tx, store, fileId, decision, principal, opts);
+        });
+        return this.#fetchDelivery(reserved, opts);
+    }
+    /**
+     * Metadata without bytes, authorized exactly like `read`.
+     *
+     * This exists because `getFileRecord()` used to be public and took no
+     * principal -- see the note on it below. Callers that wanted a file's
+     * metadata had an unauthorized way to get it; now they have an authorized one.
+     *
+     * It does NOT charge the download cap, and that asymmetry is the whole point
+     * of the delivery-cap rule: the cap counts BYTES LEAVING, and `stat` delivers
+     * none.
+     */
+    async stat(principal, fileId) {
+        return this.#transaction(async (tx, store) => {
+            const decision = await authorize(store, principal, fileId, 'read');
+            this.#raise(decision);
+            const file = await getFileRecord(tx, this.projectId, fileId);
+            if (!file)
+                throw new FilelayerError(404, 'not_found');
+            return file;
+        });
+    }
+    /**
+     * THE ONE PLACE BYTES LEAVE THE SYSTEM -- and therefore the one place the
+     * download cap is charged (P6).
+     *
+     * THE DEFECT. `max_downloads` was charged only by `redeem()`, the share-link
+     * path. An ACTOR grant carrying `maxDownloads: 3` permitted unlimited direct
+     * `read()` calls, because nothing on that path touched the counter. So the
+     * field meant "link redemptions" on one path and "nothing at all" on another,
+     * while being named, documented and billed as a download cap. In practice the
+     * direct path is the COMMON one -- the SDK calls `read()` --
+     * so the dimension was a lie on the path most customers use.
+     *
+     * THE DECISION, of the three that were on the table:
+     *
+     *   (a) rename it `maxRedemptions`. Rejected: it would still be settable on
+     *       an actor grant, where it would then mean nothing, so the ambiguity
+     *       moves rather than closes.
+     *   (b) refuse `maxDownloads` on non-link grants. Rejected: "you may read
+     *       this three times" is a thing customers legitimately want to say about
+     *       a named person, and refusing it removes a capability to avoid
+     *       defining one.
+     *   (c) CHARGE ON EVERY DELIVERY. Chosen. A cap of 3 means the bytes leave at
+     *       most 3 times, through any path, by any principal, at any delegation
+     *       depth. It is the reading a customer already has, it is the only one
+     *       that is true on every path, and it makes the cap enforceable rather
+     *       than advisory.
+     *
+     * THE RULE, precisely: a delivery is charged when, and only when, the
+     * authorization decision was reached VIA A GRANT. Authority from an org role
+     * is not a metered credential and is not charged -- an admin doing their job
+     * must not silently burn a contractor's link budget. `authorize()` alone does
+     * not charge (it is a decision, not a delivery) and neither does `stat()`.
+     *
+     * ORDERING: reserve BEFORE fetching bytes, exactly as `redeem()` does. The
+     * reservation is the write (P6), so two concurrent deliveries against a cap
+     * of 1 yield one delivery; doing it the other way round would let both read
+     * the object and only then discover one of them was over budget. A storage
+     * failure after a successful reservation therefore still spends a download.
+     * That is the fail-closed direction and it is deliberate.
+     *
+     * KNOWN COST, recorded rather than hidden. `consume_download` runs even
+     * when no grant in the chain carries a cap, because `download_count` is also
+     * the answer to "how many times has this link been downloaded", which
+     * `listGrants` reports and a compliance screen asks for. That makes every
+     * grant-authorized delivery a row UPDATE holding a row lock -- and for a
+     * TIER-1 PUBLIC ASSET, where one anonymous grant row serves every request,
+     * that single row becomes a write hotspot under load. It is a scalability
+     * problem, not a correctness one, and the fix (skip the write when no
+     * ancestor has a cap, and meter deliveries elsewhere) trades away the
+     * per-grant download count. Not taken here because that count is a shipped
+     * feature; flagged so the trade is made deliberately when volume forces it.
+     */
+    async #reserve(tx, store, fileId, decision, principal, opts) {
+        const grantId = decision.grantId ?? null;
+        let remainingDownloads = null;
+        if (grantId !== null) {
+            const consumed = await store.consumeDownload(grantId);
+            if (!consumed.granted) {
+                // Reachable only when the cap is hit between the decision and the
+                // reservation. The engine records the ordinary case; this records the
+                // race, so the two cannot silently become one.
+                const file = await getFileRecord(tx, this.projectId, fileId);
+                await store.audit({
+                    orgId: file?.orgId ?? null,
+                    action: 'file.read',
+                    decision: 'deny',
+                    reason: 'grant_exhausted',
+                    actorId: principal.actorId,
+                    fileId,
+                    grantId,
+                    ...(principal.ip !== undefined ? { ip: principal.ip } : {}),
+                    context: { race: true, ...(file ? {} : { chain: 'system' }) },
+                });
+                throw new FilelayerError(404, 'not_found', 'grant_exhausted');
+            }
+            remainingDownloads = consumed.remaining;
+        }
+        const file = await getFileRecord(tx, this.projectId, fileId);
+        if (!file)
+            throw new FilelayerError(404, 'not_found');
+        const headers = deliveryHeaders(file, opts);
+        const mode = this.#redirectEligible(decision, opts.mode ?? 'auto');
+        if (mode === 'proxy') {
+            return { kind: 'proxy', file, headers, remainingDownloads, grantId };
+        }
+        // The presigned URL is minted INSIDE the transaction, before the audit
+        // event that records it. `presignGet` for the S3 adapter is local HMAC with
+        // no I/O; an adapter for which that is not true must still keep it cheap,
+        // because it sits inside an open transaction. Minting first means we never
+        // audit a redirect we then failed to produce.
+        const redirect = this.redirect;
+        const url = await this.storage.presignGet(file.storageKey, {
+            expiresInSeconds: redirect.ttlSeconds,
+            // Pin the SAME neutralised type and disposition the proxied path would
+            // have sent, so a redirect cannot be a way to lose them.
+            responseContentType: headers['content-type'],
+            responseContentDisposition: headers['content-disposition'],
+        });
+        const expiresAt = new Date(Date.now() + redirect.ttlSeconds * 1000);
+        // THE EVENT THAT MAKES THE MODE AUDITABLE. Written only for redirects, in
+        // the same transaction as the reservation. A compliance auditor asking "which
+        // deliveries left our control?" filters `action = 'file.deliver'`; every
+        // other delivery was proxied.
+        await store.audit({
+            orgId: file.orgId,
+            action: 'file.deliver',
+            decision: 'allow',
+            actorId: principal.actorId,
+            fileId,
+            grantId,
+            ...(principal.ip !== undefined ? { ip: principal.ip } : {}),
+            ...(principal.userAgent !== undefined ? { userAgent: principal.userAgent } : {}),
+            context: {
+                mode: 'redirect',
+                via: decision.via,
+                ttlSeconds: redirect.ttlSeconds,
+                // The number a compliance document quotes. Spelled out rather than
+                // derived, so it survives a change to how the TTL is computed.
+                revocationWindowSeconds: redirect.ttlSeconds,
+                expiresAt: expiresAt.toISOString(),
+                cacheable: decision.via === 'grant:anonymous',
+            },
+        });
+        return {
+            kind: 'redirect',
+            file,
+            headers,
+            remainingDownloads,
+            grantId,
+            url,
+            expiresAt,
+            ttlSeconds: redirect.ttlSeconds,
+            cacheable: decision.via === 'grant:anonymous',
+        };
+    }
+    /**
+     * Is this delivery allowed to be a redirect?
+     *
+     * Four conditions, all required, and the default answer is no:
+     *   1. the caller asked for 'auto' (routes default to 'proxy');
+     *   2. redirect delivery is configured -- which required the acknowledgement;
+     *   3. the adapter can actually mint a presigned URL;
+     *   4. the authority came from an ANONYMOUS grant, unless the scope was
+     *      explicitly widened to 'all-grants'.
+     *
+     * Condition 4 is the one that matters. `via` is the engine's own account of
+     * where the authority came from, so "public" here means "the customer
+     * published this file", not "the request looked public".
+     */
+    #redirectEligible(decision, requested) {
+        if (requested !== 'auto')
+            return 'proxy';
+        if (this.redirect === null)
+            return 'proxy';
+        if (!canPresign(this.storage))
+            return 'proxy';
+        if (this.redirect.scope === 'anonymous-grants-only' && decision.via !== 'grant:anonymous') {
+            return 'proxy';
+        }
+        return 'redirect';
+    }
+    /**
+     * Turn a committed reservation into bytes (or a 302).
+     *
+     * Deliberately OUTSIDE the transaction. Fetching an object can take minutes;
+     * holding a database connection open for that is how a pool dies. It also
+     * preserves the documented P6 property that a storage failure after a
+     * successful reservation still spends a download -- the reservation is
+     * already committed, so nothing can give it back.
+     */
+    async #fetchDelivery(r, opts) {
+        if (r.kind === 'redirect') {
+            const d = {
+                mode: 'redirect',
+                file: r.file,
+                status: 302,
+                url: r.url,
+                expiresAt: r.expiresAt,
+                revocationWindowSeconds: r.ttlSeconds,
+                headers: redirectHeaders(r.url, { ttlSeconds: r.ttlSeconds, cacheable: r.cacheable }),
+                remainingDownloads: r.remainingDownloads,
+                ...(r.grantId ? { grantId: r.grantId } : {}),
+            };
+            return d;
+        }
+        const obj = await this.storage.stream(r.file.storageKey, {
+            ...(opts.range ? { range: opts.range } : {}),
+        });
+        if (!obj)
+            throw new FilelayerError(404, 'not_found');
+        // Metering is deliberately outside the transaction and best-effort: it is
+        // not a decision, and a metering failure must not fail a delivery the
+        // system already authorized, charged and audited.
+        const bytes = obj.size ?? r.file.sizeBytes ?? 0;
+        await this.store.recordUsage(r.file.orgId, 'read', bytes).catch(() => { });
+        const headers = { ...r.headers };
+        // Trust the store's length over the column: a `size_bytes` that disagrees
+        // with the object truncates or hangs the response.
+        if (obj.size !== null)
+            headers['content-length'] = String(obj.size);
+        else
+            delete headers['content-length'];
+        if (obj.range) {
+            headers['content-range'] = `bytes ${obj.range.start}-${obj.range.end}/${obj.range.total}`;
+            headers['accept-ranges'] = 'bytes';
+        }
+        const d = {
+            mode: 'proxy',
+            file: r.file,
+            headers,
+            body: obj.body,
+            bytes: obj.size,
+            remainingDownloads: r.remainingDownloads,
+            ...(r.grantId ? { grantId: r.grantId } : {}),
+        };
+        return d;
+    }
+    // ---------------------------------------------------------------------------
+    // Listing -- the authorized query surface
+    // ---------------------------------------------------------------------------
+    /**
+     * Which files in this org may this principal `capability`?
+     *
+     * This is the primitive that was missing, and its absence was
+     * the reason the "0 authorization lines" claim survived: the example simply
+     * did not have a listing screen, and building one meant hand-rolling the org
+     * filter, the visibility rule, the owner check, the role check and the union
+     * over `file_grant` in application SQL.
+     *
+     * WHY IT CANNOT BE GOT WRONG.
+     *
+     *  - There is no filter parameter. The signature takes a principal, an org,
+     *    a capability, a page size and an opaque cursor. There is nothing here to
+     *    forget to pass and nothing that widens the result set.
+     *  - The predicate is generated from the same role table and the same
+     *    lifecycle gate `authorize()` uses (see `listPredicate` in authz.ts), so
+     *    the two cannot drift by editing one of them.
+     *  - `test/listing.test.ts` asserts set equality against `authorize()` over a
+     *    randomized corpus, on every capability, on every run.
+     *
+     * WHAT IT COSTS. One SQL query and one audit event, independent of page size.
+     * A per-file `authorize()` loop would be 4 round trips x N.
+     *
+     * The empty page is a valid answer: a caller with no standing sees nothing,
+     * and so does a caller naming an org that does not exist. Neither is an error,
+     * because distinguishing them would rebuild the existence oracle.
+     */
+    async listFiles(principal, orgId, opts = {}) {
+        // A link secret is a bearer credential for exactly one file. Refused rather
+        // than ignored: a silently-dropped credential is how a caller ends up
+        // believing they listed something they did not.
+        if (principal.linkSecret !== undefined) {
+            throw new FilelayerError(400, 'link_principal_cannot_list', 'link_principal_cannot_list');
+        }
+        const capability = opts.capability ?? 'read';
+        const limit = Math.max(1, Math.min(opts.limit ?? LIST_DEFAULT_LIMIT, LIST_MAX_LIMIT));
+        const { files, hasMore } = await authorizeList(this.store, principal, orgId, {
+            capability,
+            limit,
+            cursor: decodeCursor(opts.cursor),
+        });
+        const last = files[files.length - 1];
+        return {
+            // `ListedFile` and `FileRecord` are the same shape; the store returns the
+            // columns `getFileRecord` returns, so nothing is re-fetched per row.
+            files: files,
+            nextCursor: hasMore && last ? encodeCursor(last.createdAt, last.id) : null,
+        };
+    }
+    /**
+     * ORDERING, and it is the mirror image of `upload()`.
+     *
+     * The metadata delete COMMITS FIRST -- the decision, the audit event the
+     * engine wrote for it, and the state change, all in one transaction -- and
+     * only then are the bytes removed. A crash in between leaves an object no row
+     * points at, which is an orphan and therefore a garbage-collection problem.
+     * The other ordering would leave a live, listable, authorizable `file` row
+     * whose object is gone, which is data loss.
+     *
+     * The bytes are removed OUTSIDE the transaction for the same reason they are
+     * written outside it: object storage cannot roll back, so including it would
+     * mean a rolled-back transaction had already destroyed the object.
+     */
+    async delete(principal, fileId) {
+        const file = await this.#transaction(async (tx, store) => {
+            const decision = await authorize(store, principal, fileId, 'delete');
+            this.#raise(decision);
+            const f = await getFileRecord(tx, this.projectId, fileId);
+            if (!f)
+                throw new FilelayerError(404, 'not_found');
+            await tx.query(`UPDATE file SET state = 'deleted', deleted_at = now(), updated_at = now()
+          WHERE id = $1`, [fileId]);
+            return f;
+        });
+        await this.storage.delete(file.storageKey);
+    }
+    /**
+     * COLLECT ORPHANED OBJECTS. A REQUIRED OPERATIONAL JOB.
+     *
+     * An orphan is an object in the store with no `file` row pointing at
+     * (provider, key). Two things produce them, both of them by design:
+     *
+     *   - a crash between `storage.put()` and the metadata commit in `upload()`;
+     *   - a crash between the metadata commit and `storage.delete()` in
+     *     `delete()`.
+     *
+     * Neither is a correctness problem -- an orphan is unreachable, because every
+     * read path in the system starts from a `file` row, and keys are fresh UUIDs
+     * that are never reissued -- but both cost money, and an uncollected orphan
+     * from a delete is a compliance problem: the customer was told the bytes were
+     * gone.
+     *
+     * WHAT MAKES THIS SAFE. Two things, and they are both load-bearing:
+     *
+     *  1. `olderThanSeconds` (default 1 hour, minimum 60s). An object written
+     *     seconds ago may belong to an upload whose transaction has not committed
+     *     yet. Deleting it would turn a successful upload into permanent data
+     *     loss -- the exact failure this whole ordering exists to avoid. The grace
+     *     period must exceed the longest plausible upload-plus-commit.
+     *  2. The `file` lookup is by (storage_provider, storage_key), the pair the
+     *     UNIQUE index is on, and it is NOT project-scoped and NOT filtered on
+     *     `deleted_at`. A soft-deleted file whose bytes were never removed still
+     *     has a row; this job must not race the delete path into removing bytes a
+     *     retention hold is protecting. It only removes what NOTHING references.
+     *
+     * Control plane: it takes no principal for the same reason the other
+     * lifecycle operations do not (see above). `dryRun` is the default.
+     */
+    async collectStorageOrphans(opts = {}) {
+        if (!canList(this.storage)) {
+            throw new FilelayerError(500, 'storage_cannot_list', 'orphan collection needs a storage adapter that implements list()');
+        }
+        const grace = Math.max(60, opts.olderThanSeconds ?? 3600) * 1000;
+        const limit = Math.max(1, Math.min(opts.limit ?? 1000, 10_000));
+        const cutoff = Date.now() - grace;
+        const dryRun = opts.dryRun ?? true;
+        let cursor = null;
+        let scanned = 0;
+        const orphans = [];
+        let truncated = false;
+        do {
+            const page = await this.storage.list(opts.prefix ?? '', {
+                limit: Math.min(1000, limit),
+                cursor,
+            });
+            cursor = page.cursor;
+            for (const e of page.entries) {
+                scanned++;
+                // No timestamp means we cannot prove it is old. Fail closed: skip it.
+                if (e.lastModified === null || e.lastModified.getTime() > cutoff)
+                    continue;
+                const { rows } = await this.db.query(`SELECT 1 FROM file WHERE storage_provider = $1 AND storage_key = $2`, [this.storage.provider, e.key]);
+                if (rows.length > 0)
+                    continue;
+                orphans.push(e.key);
+                if (orphans.length >= limit) {
+                    truncated = true;
+                    break;
+                }
+            }
+        } while (cursor !== null && !truncated);
+        let deleted = 0;
+        if (!dryRun) {
+            for (const key of orphans) {
+                await this.storage.delete(key);
+                deleted++;
+            }
+            await this.store.audit({
+                orgId: null,
+                action: 'storage.gc',
+                decision: 'allow',
+                actorId: null,
+                fileId: null,
+                context: {
+                    chain: 'system',
+                    provider: this.storage.provider,
+                    scanned,
+                    deleted,
+                    via: 'control_plane',
+                },
+            });
+        }
+        return { scanned, orphans, deleted, truncated };
+    }
+    // ---------------------------------------------------------------------------
+    // Grants
+    // ---------------------------------------------------------------------------
+    async share(principal, fileId, input) {
+        const capabilities = input.capabilities ?? ['read'];
+        // ONE TRANSACTION: the decision, the grant row, and the audit event that
+        // records both. Previously these were three autocommit statements, so a
+        // failure in the middle could leave a live grant that the audit log has no
+        // record of anyone creating -- a grant with no provenance, which for a
+        // capability system is the worst possible row to be missing.
+        return this.#transaction(async (tx, store) => {
+            // One call, two questions: may you share, and is what you are handing out a
+            // subset of what you hold? Both are answered by the engine. The
+            // engine also tells us which grant your authority came from, which becomes
+            // this grant's parent and is what makes revocation transitive.
+            // The subject type is part of the authorization question, not a detail of
+            // the row: I6 says a grant-derived issuer may not widen the population.
+            // Passing it here is what lets the ENGINE refuse -- with a reason and an
+            // audit event -- rather than leaving the trigger to raise at INSERT time.
+            const decision = await authorizeShare(store, principal, fileId, capabilities, {
+                subjectType: input.subject.type,
+            });
+            if (!decision.allow) {
+                const pub = toPublicError(decision.reason);
+                throw new FilelayerError(pub.status, pub.code, decision.reason);
+            }
+            const file = await getFileRecord(tx, this.projectId, fileId);
+            if (!file)
+                throw new FilelayerError(404, 'not_found');
+            const expiresAt = input.expiresIn ? new Date(Date.now() + input.expiresIn * 1000) : null;
+            let secret;
+            let secretHash = null;
+            let subjectId = null;
+            let subjectOrgId = null;
+            let subjectMinRole = null;
+            if (input.subject.type === 'link') {
+                // 256 bits from the CSPRNG. Base64url so it survives a URL path segment.
+                secret = randomBytes(32).toString('base64url');
+                secretHash = await this.store.hashSecret(secret);
+            }
+            else if (input.subject.type === 'actor') {
+                subjectId = input.subject.actorId;
+            }
+            else if (input.subject.type === 'org' || input.subject.type === 'role') {
+                // I1/P8. The composite FK already makes a cross-PROJECT subject org
+                // unrepresentable; this resolves it first so the caller gets the same
+                // uniform 404 they get for any other id they may not name, instead of a
+                // foreign-key violation that would confirm the id exists somewhere. An
+                // org in another project, an org that does not exist, and a malformed id
+                // are one answer -- the same symmetry the file paths keep.
+                subjectOrgId = await this.#resolveSubjectOrg(tx, input.subject.orgId);
+                if (input.subject.type === 'role')
+                    subjectMinRole = input.subject.minRole;
+            }
+            const passwordHash = input.password ? await this.store.hashPassword(input.password) : null;
+            // org_id is taken from the FILE, never from the caller. The composite FK
+            // (file_id, org_id) -> file(id, org_id) makes a mismatch unrepresentable,
+            // but taking it from the caller at all would be an invitation.
+            //
+            // The RETURNING clause reads back expires_at and max_downloads because the
+            // attenuation trigger may have tightened them against the parent grant. We
+            // report what was actually stored, not what was asked for.
+            //
+            // THE SAVEPOINT IS NOT OPTIONAL. A statement that RAISES inside a Postgres
+            // transaction aborts the whole transaction: every subsequent statement
+            // fails with "current transaction is aborted". The attenuation trigger
+            // raising is precisely the case where we must keep going, because the
+            // refusal has to be AUDITED. Without the savepoint the audit write below
+            // would itself fail and the refusal would vanish -- the transaction work
+            // would have silently deleted a security event.
+            let rows;
+            try {
+                ({ rows } = await tx.savepoint(() => tx.query(`INSERT INTO file_grant
+           (file_id, org_id, parent_grant_id, subject_type, subject_id, subject_org_id,
+            subject_min_role, capabilities,
+            secret_hash, password_hash, expires_at, max_downloads, created_by)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8::grant_capability[],$9,$10,$11,$12,$13)
+         RETURNING id, expires_at, max_downloads`, [
+                    fileId,
+                    file.orgId,
+                    decision.parentGrantId,
+                    input.subject.type,
+                    subjectId,
+                    subjectOrgId,
+                    subjectMinRole,
+                    pgArrayLiteral(capabilities),
+                    secretHash,
+                    passwordHash,
+                    expiresAt?.toISOString() ?? null,
+                    input.maxDownloads ?? null,
+                    principal.actorId,
+                ])));
+            }
+            catch (err) {
+                // The schema is the backstop for attenuation; if it fires, it has caught
+                // something the engine let through.
+                const refusal = schemaRefusal(err);
+                if (!refusal)
+                    throw err;
+                await store.audit({
+                    orgId: file.orgId,
+                    action: 'grant.create',
+                    decision: 'deny',
+                    reason: refusal,
+                    actorId: principal.actorId,
+                    fileId,
+                    grantId: decision.parentGrantId,
+                    context: { capabilities, subjectType: input.subject.type },
+                });
+                throw new FilelayerError(403, 'forbidden', refusal);
+            }
+            const grantId = rows[0].id;
+            const effectiveExpiry = rows[0].expires_at ? new Date(rows[0].expires_at) : null;
+            const effectiveCap = rows[0].max_downloads ?? null;
+            await store.audit({
+                orgId: file.orgId,
+                action: 'grant.create',
+                decision: 'allow',
+                actorId: principal.actorId,
+                fileId,
+                grantId,
+                context: {
+                    subjectType: input.subject.type,
+                    ...(subjectOrgId ? { subjectOrgId } : {}),
+                    ...(subjectMinRole ? { subjectMinRole } : {}),
+                    capabilities,
+                    parentGrantId: decision.parentGrantId,
+                    expiresAt: effectiveExpiry?.toISOString() ?? null,
+                    maxDownloads: effectiveCap,
+                },
+            });
+            return {
+                grantId,
+                ...(secret ? { secret } : {}),
+                ...(secret && this.opts.baseUrl ? { url: `${this.opts.baseUrl}/d/${secret}` } : {}),
+                expiresAt: effectiveExpiry,
+                maxDownloads: effectiveCap,
+                parentGrantId: decision.parentGrantId,
+            };
+        });
+    }
+    /**
+     * Resolve the org named by an `org` / `role` grant subject (RFC-001, I1).
+     *
+     * Three things have to be true and only one of them is about convenience:
+     *
+     *  - the org must EXIST and not be soft-deleted (a grant naming a dead tenant
+     *    would be born non-live anyway -- see `grant_scope_is_live` -- so minting
+     *    one is a caller error worth reporting);
+     *  - it must be in THIS instance's project. That is the P8 boundary, and it
+     *    is the thing that makes a cross-project group grant unrepresentable. The
+     *    composite foreign key enforces it regardless; this exists so the answer
+     *    is a clean 404 rather than a constraint violation whose message would
+     *    itself confirm the id resolves to a row somewhere in the database.
+     *  - it need NOT be the file's own org. Cross-ORG group grants inside one
+     *    project are the whole point of the feature.
+     */
+    async #resolveSubjectOrg(tx, orgId) {
+        if (!isUuid(orgId))
+            throw new FilelayerError(404, 'not_found', 'unknown_subject_org');
+        const { rows } = await tx.query(`SELECT o.id FROM org o
+         JOIN project p ON p.id = o.project_id
+        WHERE o.id = $1
+          AND o.deleted_at IS NULL
+          AND p.deleted_at IS NULL
+          AND ($2::uuid IS NULL OR o.project_id = $2::uuid)`, [orgId, this.projectId]);
+        if (!rows[0])
+            throw new FilelayerError(404, 'not_found', 'unknown_subject_org');
+        return rows[0].id;
+    }
+    /**
+     * Revoke a grant.
+     *
+     * Nothing cascades, and nothing needs to: liveness is evaluated over the
+     * ancestor chain, so every grant ever delegated from this one dies in the
+     * same instant, at any depth, with no second write to get wrong (P4).
+     */
+    async revoke(principal, grantId) {
+        if (!isUuid(grantId))
+            throw new FilelayerError(404, 'not_found');
+        // Revocation is the operation the product is sold on, so the state change
+        // and the event proving it happened must not be separable. Both are in this
+        // transaction.
+        //
+        // LOCK ORDERING, and it is not decorative. Because `audit_append()` takes a
+        // `pg_advisory_XACT_lock` on the org's chain, a transaction now holds that
+        // lock from its FIRST audit write until commit -- which it did not before,
+        // when every statement was its own transaction. Two transactions that take
+        // the chain lock and a `file_grant` row lock in OPPOSITE orders deadlock.
+        // The rule, followed by every method here, is:
+        //
+        //     THE AUDIT CHAIN LOCK IS ALWAYS TAKEN BEFORE ANY ROW LOCK.
+        //
+        // `authorizeRevoke` emits its allow event (chain lock) before the UPDATE
+        // below (row lock), and the delivery path likewise audits in `authorize()`
+        // before `consume_download()` touches the grant row. This SELECT therefore
+        // deliberately does NOT take `FOR UPDATE`: that would grab the row lock
+        // first and invert the order against every other path. Nothing is lost --
+        // the UPDATE is `WHERE revoked_at IS NULL`, so a concurrent revoke is
+        // idempotent rather than a lost update.
+        await this.#transaction(async (tx, store) => {
+            const { rows } = await tx.query(`SELECT file_id, org_id FROM file_grant WHERE id = $1`, [grantId]);
+            const g = rows[0];
+            // Unknown grant and "not yours" are the same answer, for the same reason
+            // file ids are: otherwise this endpoint is a grant-id oracle.
+            if (!g)
+                throw new FilelayerError(404, 'not_found');
+            const decision = await authorizeRevoke(store, principal, {
+                id: grantId,
+                fileId: g.file_id,
+                orgId: g.org_id,
+            });
+            this.#raise(decision);
+            await tx.query(`UPDATE file_grant SET revoked_at = now() WHERE id = $1 AND revoked_at IS NULL`, [grantId]);
+            await store.audit({
+                orgId: g.org_id,
+                action: 'grant.revoke',
+                decision: 'allow',
+                actorId: principal.actorId,
+                fileId: g.file_id,
+                grantId,
+            });
+        });
+    }
+    async listGrants(principal, fileId) {
+        const decision = await authorize(this.store, principal, fileId, 'share');
+        this.#raise(decision);
+        const { rows } = await this.db.query(`SELECT id, file_id, parent_grant_id, subject_type, subject_id,
+              subject_org_id, subject_min_role, capabilities,
+              (password_hash IS NOT NULL) AS has_password,
+              expires_at, max_downloads, download_count, revoked_at,
+              grant_is_live(id) AS live,
+              created_by, created_at
+         FROM file_grant WHERE file_id = $1 ORDER BY created_at ASC`, [fileId]);
+        // Note what is NOT selected: secret_hash and password_hash. A "list what
+        // we've shared" screen is exactly where a hash would leak into a log.
+        return rows.map((r) => ({
+            id: r['id'],
+            fileId: r['file_id'],
+            parentGrantId: r['parent_grant_id'] ?? null,
+            subjectType: r['subject_type'],
+            subjectId: r['subject_id'] ?? null,
+            subjectOrgId: r['subject_org_id'] ?? null,
+            subjectMinRole: r['subject_min_role'] ?? null,
+            capabilities: toCapabilities(r['capabilities']),
+            hasPassword: Boolean(r['has_password']),
+            expiresAt: r['expires_at'] ? new Date(r['expires_at']) : null,
+            maxDownloads: r['max_downloads'] ?? null,
+            downloadCount: Number(r['download_count']),
+            revokedAt: r['revoked_at'] ? new Date(r['revoked_at']) : null,
+            live: Boolean(r['live']),
+            createdBy: r['created_by'] ?? null,
+            createdAt: new Date(r['created_at']),
+        }));
+    }
+    /**
+     * The share-link download path.
+     *
+     * Order matters: authorize FIRST (which re-validates the grant and its whole
+     * ancestor chain against `live_grant` -- P4, revocation beats a live URL),
+     * then consume the counter atomically (P6). Consuming before authorizing
+     * would let a revoked link burn a download; authorizing without consuming
+     * would make the cap a suggestion.
+     */
+    async redeem(linkSecret, opts = {}) {
+        // Buffered convenience form of `redeemStream()`, exactly as `read()` is of
+        // `readStream()`. Forces proxy mode for the same reason.
+        const d = await this.redeemStream(linkSecret, { ...opts, mode: 'proxy' });
+        if (d.mode !== 'proxy')
+            throw new FilelayerError(500, 'internal', 'unexpected_redirect');
+        return {
+            file: d.file,
+            body: await collectStream(d.body),
+            headers: d.headers,
+            remainingDownloads: d.remainingDownloads,
+        };
+    }
+    /** The streaming share-link path. See `redeem()` for the ordering rationale. */
+    async redeemStream(linkSecret, opts = {}) {
+        const principal = {
+            actorId: null,
+            linkSecret,
+            ...(opts.password !== undefined ? { password: opts.password } : {}),
+            ...(opts.ip !== undefined ? { ip: opts.ip } : {}),
+            ...(opts.userAgent !== undefined ? { userAgent: opts.userAgent } : {}),
+        };
+        const hash = await this.store.hashSecret(linkSecret);
+        const reserved = await this.#transaction(async (tx, store) => {
+            // Resolve the secret to a FILE, not to an authorization. This
+            // deliberately reads through the non-live lookup: a revoked, expired or
+            // exhausted link must still reach the engine so that the denial is
+            // attributed to the right tenant and recorded with the right reason.
+            // Nothing here grants anything -- `authorize` below re-resolves through
+            // `live_grant`.
+            const grant = await store.findGrantBySecret(hash);
+            if (!grant) {
+                // No file and no tenant: the system chain exists precisely so that a
+                // brute-force sweep against the credential itself is not invisible.
+                // In the transaction, so the sweep cannot be made invisible by a
+                // failure on the way out either.
+                await auditUnresolvedSecret(store, principal, hash);
+                throw new FilelayerError(404, 'not_found', 'bad_link_secret');
+            }
+            const decision = await authorize(store, principal, grant.fileId, 'read');
+            this.#raise(decision);
+            // Same reservation path as `readStream()`: one place charges the cap, one
+            // place decides the mode, one place computes the headers. `no-store` on
+            // the proxied response is not cosmetic here -- immediate revocation is the
+            // product's headline property, and a cacheable share response makes a
+            // revoked link replayable from the recipient's disk cache or from any
+            // intermediary.
+            return this.#reserve(tx, store, grant.fileId, decision, principal, opts);
+        });
+        return this.#fetchDelivery(reserved, opts);
+    }
+    // ---------------------------------------------------------------------------
+    // Audit
+    // ---------------------------------------------------------------------------
+    /** Requires `read_audit` in the org, which is admin+. Asked of the engine. */
+    async auditLog(principal, orgId, filter = {}) {
+        const decision = await authorizeOrg(this.store, principal, orgId, 'read_audit', {
+            action: 'audit.read',
+            emitAllow: false, // reading the log should not spam the log
+        });
+        this.#raise(decision);
+        return this.store.listAudit(orgId, filter);
+    }
+    /**
+     * Verify the tamper-evidence chain for an org.
+     *
+     * Authorized, because `checked` is a count of everything that has ever
+     * happened in the org and an unauthenticated caller should not be able to
+     * measure another tenant's activity.
+     */
+    async verifyAuditChain(principal, orgId) {
+        const decision = await authorizeOrg(this.store, principal, orgId, 'read_audit', {
+            action: 'audit.verify',
+            emitAllow: false,
+        });
+        this.#raise(decision);
+        return this.store.verifyAuditChain(orgId);
+    }
+    // ---------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------
+    /**
+     * Turn a denial into an HTTP-shaped error.
+     *
+     * That is all it does now. It used to additionally re-run the whole
+     * authorization question in order to downgrade 410/409 to 404 for callers
+     * with no standing, because `authorize()` evaluated lifecycle gates before
+     * establishing standing and therefore leaked existence. The engine
+     * evaluates standing first now, so there is nothing left to compensate for --
+     * and, not incidentally, one fewer place for a second entry point to forget.
+     */
+    #raise(decision) {
+        if (decision.allow)
+            return;
+        const pub = toPublicError(decision.reason);
+        throw new FilelayerError(pub.status, pub.code, decision.reason);
+    }
+}
+/**
+ * A file's full record from its id, with NO principal.
+ *
+ * IT IS A MODULE-LEVEL FUNCTION, NOT A PRIVATE METHOD, AND THAT IS THE POINT.
+ *
+ * This was once a PUBLIC method taking a file id and no principal, returning
+ * name, content type, size, storage key, owner and org for any file in the
+ * database. It sat under an `// Internals` comment, which binds nobody:
+ * `fl.getFileRecord(anyUuid)` was a complete cross-tenant metadata read with no
+ * decision, no denial and no audit event. A resource id without a principal is
+ * not a question the system is allowed to answer.
+ *
+ * Making it `private` fixed the TYPE and not the RUNTIME. TypeScript's `private`
+ * is erased at compile time: `(fl as any).getFileRecord(id)` still worked, and
+ * so did `fl['getFileRecord'](id)` from plain JavaScript -- which is what an SDK
+ * consumer actually holds. A test in test/persistence.test.ts caught exactly
+ * that. Module scope is the only privacy JavaScript actually enforces, so the
+ * function lives out here, where nothing outside this file can name it.
+ *
+ * Every caller inside the class reaches it only AFTER `authorize()` has
+ * returned allow for the same file; the authorized replacement for external
+ * callers is `stat()`. It is project-scoped, so even an internal caller cannot
+ * read across a project boundary.
+ */
+async function getFileRecord(db, projectId, fileId) {
+    if (!isUuid(fileId))
+        return null;
+    const { rows } = await db.query(`SELECT id, org_id, owner_id, name, content_type, size_bytes,
+            storage_provider, storage_key,
+            state, visibility, expires_at, retain_until, created_at, deleted_at
+       FROM file WHERE id = $1 AND ($2::uuid IS NULL OR project_id = $2::uuid)`, [fileId, projectId]);
+    return rows[0] ? toFileRecord(rows[0]) : null;
+}
+/**
+ * Keyset pagination over (created_at, id).
+ *
+ * Keyset, not OFFSET: with OFFSET a row inserted or deleted between pages
+ * shifts the window and a file silently skips a page, which on a compliance
+ * listing screen is a file the reviewer never saw.
+ *
+ * The cursor is opaque but not authenticated, and it does not need to be: it
+ * carries only a position, it is applied AFTER the authorization predicate, and
+ * it is confined to the org named in the call. A forged cursor can move you
+ * within your own authorized set and nowhere else. It is validated on the way
+ * in so that a malformed one is a 400 rather than a silently-ignored filter.
+ */
+function encodeCursor(createdAt, id) {
+    return Buffer.from(`${createdAt.toISOString()}|${id}`, 'utf8').toString('base64url');
+}
+function decodeCursor(cursor) {
+    if (cursor === undefined || cursor === null || cursor === '')
+        return null;
+    let decoded;
+    try {
+        decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+    }
+    catch {
+        throw new FilelayerError(400, 'bad_cursor');
+    }
+    const sep = decoded.lastIndexOf('|');
+    if (sep < 0)
+        throw new FilelayerError(400, 'bad_cursor');
+    const createdAt = new Date(decoded.slice(0, sep));
+    const id = decoded.slice(sep + 1);
+    if (Number.isNaN(createdAt.getTime()) || !isUuid(id)) {
+        throw new FilelayerError(400, 'bad_cursor');
+    }
+    return { createdAt, id };
+}
+/**
+ * Postgres array literal. The driver will not serialize a JS array into an
+ * enum[] parameter, and a silent misencoding here would either error loudly
+ * (fine) or store a single bogus capability (not fine), so the encoding is
+ * explicit. Enum labels are a closed set of [a-z]+ and cannot contain a
+ * separator, so no quoting is required -- but we assert that rather than
+ * assume it.
+ */
+export function pgArrayLiteral(values) {
+    for (const v of values) {
+        if (!/^[a-z_]+$/.test(v))
+            throw new Error(`unexpected capability literal: ${v}`);
+    }
+    return `{${values.join(',')}}`;
+}
+function toFileRecord(r) {
+    return {
+        id: r['id'],
+        orgId: r['org_id'],
+        ownerId: r['owner_id'] ?? null,
+        name: r['name'],
+        contentType: r['content_type'],
+        sizeBytes: r['size_bytes'] == null ? null : Number(r['size_bytes']),
+        storageProvider: r['storage_provider'],
+        storageKey: r['storage_key'],
+        state: r['deleted_at'] ? 'deleted' : r['state'],
+        visibility: r['visibility'],
+        expiresAt: r['expires_at'] ? new Date(r['expires_at']) : null,
+        retainUntil: r['retain_until'] ? new Date(r['retain_until']) : null,
+        createdAt: new Date(r['created_at']),
+    };
+}
+//# sourceMappingURL=filelayer.js.map