@filelayer/core 0.3.0

package/dist/store.js

@@ -0,0 +1,862 @@
+/**
+ * STORE LAYER
+ *
+ * Implements `AuthzDeps` (see authz.ts) against PostgreSQL.
+ *
+ * The authorization grant lookups below MUST read through the `live_grant`
+ * view, never `file_grant`. The liveness predicate -- not revoked, not expired,
+ * under cap, AND the same for every ancestor of the grant -- is expressed
+ * exactly once, in the schema, and every caller inherits it. If a future query
+ * here reaches for `file_grant` directly it has silently opted out of
+ * revocation, expiry and delegation control, which is P4, which is the product.
+ * The view is the enforcement point, not a convenience.
+ *
+ * The one deliberate exception is `findGrantBySecret`, which reads
+ * `file_grant`. It exists so that a denial can be ATTRIBUTED and EXPLAINED in
+ * the audit log, and the engine never uses its result to allow anything. It is
+ * named to make that obvious and it is the only such query in the file.
+ *
+ * ------------------------------------------------------------------------
+ * TRUST BOUNDARY. EVERY METHOD ON `PostgresStore` IS UNAUTHORIZED.
+ * ------------------------------------------------------------------------
+ * This class is the engine's DEPENDENCY surface (`AuthzDeps`), not an API.
+ * `getFile`, `getActorGrants`, `listAuthorizedFiles`, `listAudit`,
+ * `verifyAuditChain` and `consumeDownload` all take resource ids and no
+ * principal, because the engine has already established standing before it
+ * calls them -- that is the division of labour. They are the same shape as the
+ * defect fixed in `Filelayer.getFileRecord`, and they are safe only because
+ * they are not reachable from the developer's surface.
+ *
+ * The rule that keeps that true, stated so it can be enforced in review:
+ * `@filelayer/sdk` -- the only thing a customer touches in a hosted deployment
+ * -- MUST NOT re-export `PostgresStore`, `Filelayer.store`, or `store.db`. A
+ * developer holding `store.db` holds arbitrary SQL over every tenant in the
+ * hosted database, which is precisely the connection a hosted deployment exists
+ * to take away from them.
+ */
+import { createHash, randomBytes, scrypt as _scrypt, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+import { membershipCells } from "./authz.js";
+const scrypt = promisify(_scrypt);
+const SCRYPT_KEYLEN = 32;
+/**
+ * PGlite returns text[] as a JS array already; node-postgres does too. This
+ * guard exists because a raw text round-trip ('{read,write}') would otherwise
+ * silently produce a single-element array containing the literal braces, and a
+ * capability check against that string would deny everything -- fail closed,
+ * but confusingly.
+ */
+export function toCapabilities(v) {
+    if (Array.isArray(v))
+        return v;
+    return String(v)
+        .replace(/^\{|\}$/g, '')
+        .split(',')
+        .filter(Boolean);
+}
+function toGrantRow(r) {
+    return {
+        id: r.id,
+        fileId: r.file_id,
+        orgId: r.org_id,
+        parentGrantId: r.parent_grant_id ?? null,
+        subjectType: r.subject_type,
+        subjectOrgId: r.subject_org_id ?? null,
+        subjectMinRole: r.subject_min_role ?? null,
+        ...(r.matched_role !== undefined && r.matched_role !== null
+            ? { matchedRole: r.matched_role }
+            : {}),
+        capabilities: toCapabilities(r.capabilities),
+        passwordHash: r.password_hash,
+        expiresAt: r.expires_at ? new Date(r.expires_at) : null,
+        maxDownloads: r.max_downloads,
+        downloadCount: r.download_count,
+        revokedAt: r.revoked_at ? new Date(r.revoked_at) : null,
+    };
+}
+// -----------------------------------------------------------------------------
+// Store
+// -----------------------------------------------------------------------------
+/**
+ * The project every row belongs to when nobody named one. Mirrors the row
+ * inserted by schema.sql; see the PROJECT section there for why it exists.
+ */
+export const DEFAULT_PROJECT_ID = '00000000-0000-0000-0000-0000000f11e1';
+export class PostgresStore {
+    db;
+    /** Null means unscoped. See StoreOptions. */
+    projectId;
+    constructor(db, opts = {}) {
+        this.db = db;
+        this.projectId = opts.projectId === undefined ? DEFAULT_PROJECT_ID : opts.projectId;
+    }
+    /**
+     * The same store, bound to a different connection -- in practice, to an open
+     * transaction.
+     *
+     * This is what puts the audit write in the same transaction as the mutation
+     * it records. The engine calls `deps.audit()`; if `deps` is a store bound to
+     * the transaction, the event and the mutation commit or roll back together,
+     * and `audit_append()`'s advisory lock is held across BOTH rather than across
+     * one autocommit statement. `projectId` rides along, so a transactional store
+     * cannot accidentally become an unscoped one.
+     */
+    withDb(db) {
+        return new PostgresStore(db, { projectId: this.projectId });
+    }
+    now() {
+        return new Date();
+    }
+    // --- AuthzDeps ------------------------------------------------------------
+    async getFile(fileId) {
+        if (!isUuid(fileId))
+            return null; // a malformed id is "not found", not a 500
+        const { rows } = await this.db.query(`SELECT id, org_id, owner_id, state, visibility, expires_at, retain_until, deleted_at
+         FROM file WHERE id = $1 AND ($2::uuid IS NULL OR project_id = $2::uuid)`, [fileId, this.projectId]);
+        const r = rows[0];
+        if (!r)
+            return null;
+        return {
+            id: r.id,
+            orgId: r.org_id,
+            ownerId: r.owner_id,
+            // A soft-deleted row is 'deleted' regardless of the state column, so a
+            // half-applied delete cannot leave a readable file behind.
+            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,
+        };
+    }
+    /**
+     * "Is there an org here that this store may speak about?"
+     *
+     * A soft-deleted org is not one, and neither is an org whose PROJECT is
+     * soft-deleted -- deleting a customer must not leave their tenants
+     * addressable. Nor is an org in a different project.
+     *
+     * The return value decides which audit chain a denial is written to, so this
+     * predicate is also the thing that keeps a probe at another project's org id
+     * off that org's chain.
+     */
+    async orgExists(orgId) {
+        if (!isUuid(orgId))
+            return false;
+        const { rows } = await this.db.query(`SELECT 1 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]);
+        return rows.length > 0;
+    }
+    /**
+     * Membership confers nothing when the org, the project, or the ACTOR
+     * has been soft-deleted (P7).
+     *
+     * The actor clause is the one that was missing. `deleted_at` existed on
+     * `actor` and nothing read it, so a "deleted" user kept every role-derived
+     * capability they had -- which made the column decorative and made the answer
+     * to "what does deleting a user do?" depend on which method you asked.
+     */
+    async getMembership(orgId, actorId) {
+        if (!isUuid(orgId) || !isUuid(actorId))
+            return null;
+        const { rows } = await this.db.query(`SELECT m.role FROM membership m
+         JOIN org o     ON o.id = m.org_id
+         JOIN project p ON p.id = o.project_id
+         JOIN actor a   ON a.id = m.actor_id
+        WHERE m.org_id = $1 AND m.actor_id = $2
+          AND o.deleted_at IS NULL
+          AND p.deleted_at IS NULL
+          AND a.deleted_at IS NULL
+          AND ($3::uuid IS NULL OR o.project_id = $3::uuid)`, [orgId, actorId, this.projectId]);
+        return rows[0]?.role ?? null;
+    }
+    async countOwners(orgId) {
+        if (!isUuid(orgId))
+            return 0;
+        const { rows } = await this.db.query(`SELECT count(*)::int AS c FROM membership WHERE org_id = $1 AND role = 'owner'`, [orgId]);
+        return Number(rows[0]?.c ?? 0);
+    }
+    /**
+     * live_grant only.
+     *
+     * THE ORDER BY IS LOAD-BEARING, and its absence was a latent defect found
+     * while adding the group subject types. `resolveStanding` attributes an allow
+     * to the FIRST grant in this result that supplies the requested capability,
+     * and on the delegation path that grant becomes the new grant's
+     * `parent_grant_id` -- so it decides the ceiling the attenuation trigger will
+     * measure the child against. With no ORDER BY, Postgres returned heap order,
+     * which is not a defined order at all: it changes with page layout, with
+     * VACUUM, and (this is how it surfaced) with the width of the row. A
+     * principal holding several grants on one file could therefore have a
+     * `share()` call succeed or fail depending on physical storage.
+     *
+     * Oldest-first makes the choice deterministic and makes it the sensible one:
+     * the authority you were given first is the one you delegate from, and it is
+     * the same rule `getAnonymousGrant` already applies. See the note on the
+     * residual union-vs-parent gap in `authorizeShare`.
+     */
+    async getActorGrants(fileId, actorId) {
+        if (!isUuid(fileId) || !isUuid(actorId))
+            return [];
+        const { rows } = await this.db.query(`SELECT * FROM live_grant
+        WHERE file_id = $1 AND subject_type = 'actor' AND subject_id = $2
+        ORDER BY created_at ASC, id ASC`, [fileId, actorId]);
+        return rows.map(toGrantRow);
+    }
+    /**
+     * live_grant only. THE GROUP-GRANT PATH (RFC-001).
+     *
+     * ONE JOIN. Not a fan-out table, not a cached member list, not a
+     * materialized view -- a join against `membership`, evaluated on this
+     * request. That is the whole implementation of "membership changes must
+     * change access on the next request, without recomputation": there is
+     * nothing to recompute, because nothing was ever computed. Adding a member
+     * makes the join match; removing one makes it stop matching; no `file_grant`
+     * row is read, written, or even looked at during either operation. The test
+     * that asserts this counts grant rows before and after a join and a leave.
+     *
+     * The membership half carries the same three liveness clauses `getMembership`
+     * applies -- org, project and actor not soft-deleted -- because a group grant
+     * must not confer through a membership that confers nothing on its own. The
+     * SUBJECT ORG's own deletion is handled one level down, inside
+     * `grant_scope_is_live` (I2), so it binds `consume_download` and the
+     * attenuation trigger as well and not merely this query.
+     *
+     * `subject_min_role` is compared against the held role by tuple membership
+     * in the DERIVED cell list -- see `membershipCellSql` -- so the threshold is
+     * not restated in SQL here or in `listAuthorizedFiles`.
+     */
+    async getGroupGrants(fileId, actorId) {
+        if (!isUuid(fileId) || !isUuid(actorId))
+            return [];
+        const { rows } = await this.db.query(`SELECT g.*, m.role AS matched_role
+         FROM live_grant g
+         JOIN membership m ON m.org_id = g.subject_org_id AND m.actor_id = $2::uuid
+         JOIN org so       ON so.id = m.org_id
+         JOIN project sp   ON sp.id = so.project_id
+         JOIN actor sa     ON sa.id = m.actor_id
+        WHERE g.file_id = $1::uuid
+          AND g.subject_type IN ('org', 'role')
+          AND so.deleted_at IS NULL
+          AND sp.deleted_at IS NULL
+          AND sa.deleted_at IS NULL
+          AND ($3::uuid IS NULL OR so.project_id = $3::uuid)
+          AND ${membershipCellSql(membershipCells())}
+        ORDER BY g.created_at ASC, g.id ASC`, [fileId, actorId, this.projectId]);
+        return rows.map(toGrantRow);
+    }
+    /** live_grant only. Lookup is by hash; the plaintext never reaches the DB. */
+    async findLiveGrantBySecret(secretHash) {
+        const { rows } = await this.db.query(`SELECT * FROM live_grant
+        WHERE subject_type = 'link' AND secret_hash = $1
+        LIMIT 1`, [secretHash]);
+        return rows[0] ? toGrantRow(rows[0]) : null;
+    }
+    /**
+     * ATTRIBUTION ONLY -- never an authorization input.
+     *
+     * Reads `file_grant`, so it sees revoked, expired, exhausted and
+     * ancestor-dead grants. The engine calls it exclusively on paths that have
+     * already denied, in order to name the grant in the audit event and record
+     * WHY the link stopped working. Any future use of this result to grant
+     * access is a P4 violation and should fail review.
+     */
+    async findGrantBySecret(secretHash) {
+        const { rows } = await this.db.query(`SELECT * FROM file_grant
+        WHERE subject_type = 'link' AND secret_hash = $1
+        LIMIT 1`, [secretHash]);
+        return rows[0] ? toGrantRow(rows[0]) : null;
+    }
+    async isDescendantOf(ancestorId, grantId) {
+        if (!isUuid(ancestorId) || !isUuid(grantId))
+            return false;
+        const { rows } = await this.db.query(`SELECT 1 FROM grant_ancestry($1) WHERE id = $2`, [grantId, ancestorId]);
+        return rows.length > 0;
+    }
+    /** live_grant only. */
+    async getAnonymousGrant(fileId) {
+        if (!isUuid(fileId))
+            return null;
+        const { rows } = await this.db.query(`SELECT * FROM live_grant
+        WHERE file_id = $1 AND subject_type = 'anonymous'
+        ORDER BY created_at ASC
+        LIMIT 1`, [fileId]);
+        return rows[0] ? toGrantRow(rows[0]) : null;
+    }
+    /**
+     * THE SET FORM OF THE DECISION.
+     *
+     * One query, one round trip, for the same predicate `authorize()` evaluates
+     * per file. Read it against `resolveStanding()` in authz.ts -- the three OR
+     * branches are the three sources of authority, in the same order, with the
+     * same conditions:
+     *
+     *   1. org role      -> membership x the DERIVED role-cell list
+     *   2. actor grant   -> live_grant, subject_type='actor', subject_id=caller
+     *   3. anonymous     -> the EARLIEST live anonymous grant, read only
+     *
+     * ...and the lifecycle gate is the DERIVED lifecycle-cell list.
+     *
+     * The role and lifecycle tuples are not written here. They are generated by
+     * `listPredicate()` from `fileCapabilities()` and `lifecycleDenial()`, so
+     * changing the role model changes this query automatically. The tuples are
+     * still validated against the enum vocabulary before interpolation, because a
+     * generated string that reaches SQL unchecked is a generated string that can
+     * be made to reach SQL unchecked.
+     *
+     * `now` is passed in rather than read from the database so that the point
+     * check and the set query cannot disagree about what time it is. Grant
+     * liveness still uses the database clock, via `live_grant`, in BOTH paths.
+     *
+     * Ordering is (created_at, id) ascending -- total, because id is unique --
+     * and pagination is keyset, not OFFSET, so a concurrent insert cannot make a
+     * row skip a page.
+     */
+    async listAuthorizedFiles(q) {
+        if (!isUuid(q.orgId))
+            return [];
+        if (q.actorId !== null && !isUuid(q.actorId))
+            return [];
+        const lifecycle = lifecycleSql(q.predicate);
+        const roles = roleCellSql(q.predicate);
+        if (lifecycle === null)
+            return []; // no state is usable for this capability
+        // The GROUP branch (RFC-001). Structurally identical to `getGroupGrants`:
+        // the same join, the same three membership-liveness clauses, the same
+        // derived threshold cells. It is written twice only in the sense that the
+        // whole union is -- which is exactly what the differential test in
+        // test/listing.test.ts exists to police, and why that test's corpus now
+        // contains org and role grants.
+        //
+        // No capability branch, mirroring `resolveStanding`: a group grant may
+        // carry any capability, so it is consulted for all of them.
+        const group = `OR EXISTS (
+                   SELECT 1
+                     FROM live_grant g
+                     JOIN membership m ON m.org_id = g.subject_org_id AND m.actor_id = $2::uuid
+                     JOIN org so       ON so.id = m.org_id
+                     JOIN project sp   ON sp.id = so.project_id
+                     JOIN actor sa     ON sa.id = m.actor_id
+                    WHERE g.file_id = f.id
+                      AND g.subject_type IN ('org', 'role')
+                      AND so.deleted_at IS NULL
+                      AND sp.deleted_at IS NULL
+                      AND sa.deleted_at IS NULL
+                      AND ($6::uuid IS NULL OR so.project_id = $6::uuid)
+                      AND ${membershipCellSql(q.predicate.membershipCells ?? [])}
+                      AND $4::grant_capability = ANY (g.capabilities)
+                 )`;
+        const anon = q.predicate.anonymousEligible
+            ? `OR EXISTS (
+             SELECT 1 FROM (
+               SELECT g2.capabilities
+                 FROM live_grant g2
+                WHERE g2.file_id = f.id AND g2.subject_type = 'anonymous'
+                ORDER BY g2.created_at ASC
+                LIMIT 1
+             ) ag
+            WHERE $4::grant_capability = ANY (ag.capabilities)
+          )`
+            : '';
+        const params = [
+            q.orgId,
+            q.actorId,
+            q.now.toISOString(),
+            q.predicate.capability,
+            Math.max(1, Math.min(q.limit, LIST_MAX_LIMIT)),
+            this.projectId,
+        ];
+        let cursorClause = '';
+        if (q.cursor) {
+            params.push(q.cursor.createdAt.toISOString(), q.cursor.id);
+            cursorClause = `AND (f.created_at, f.id) > ($7::timestamptz, $8::uuid)`;
+        }
+        const { rows } = await this.db.query(`SELECT f.id, f.org_id, f.owner_id, f.name, f.content_type, f.size_bytes,
+              f.storage_provider, f.storage_key, f.state, f.visibility,
+              f.expires_at, f.retain_until,
+              f.created_at, f.deleted_at
+         FROM file f
+        WHERE f.org_id = $1::uuid
+          AND ($6::uuid IS NULL OR f.project_id = $6::uuid)
+          AND ${lifecycle}
+          AND (
+                ${roles === null
+            ? 'false'
+            : `EXISTS (
+                   SELECT 1
+                     FROM membership m
+                     JOIN org o     ON o.id = m.org_id
+                     JOIN project p ON p.id = o.project_id
+                     JOIN actor a   ON a.id = m.actor_id
+                    WHERE m.org_id = f.org_id
+                      AND m.actor_id = $2::uuid
+                      AND o.deleted_at IS NULL
+                      AND p.deleted_at IS NULL
+                      AND a.deleted_at IS NULL
+                      AND (m.role::text,
+                           coalesce(f.owner_id = $2::uuid, false),
+                           f.visibility::text) IN ${roles}
+                 )`}
+             OR EXISTS (
+                   SELECT 1 FROM live_grant g
+                    WHERE g.file_id = f.id
+                      AND g.subject_type = 'actor'
+                      AND g.subject_id = $2::uuid
+                      AND $4::grant_capability = ANY (g.capabilities)
+                 )
+             ${group}
+             ${anon}
+              )
+          ${cursorClause}
+        ORDER BY f.created_at ASC, f.id ASC
+        LIMIT $5`, params);
+        return rows.map(toListedFile);
+    }
+    /**
+     * Link secrets are 256 bits of CSPRNG output, so they are not guessable and
+     * not enumerable; an unsalted SHA-256 is the correct primitive here (it must
+     * be deterministic to be indexable, and there is no low-entropy input to
+     * protect). Passwords are the opposite case and use scrypt below.
+     */
+    async hashSecret(secret) {
+        return createHash('sha256').update(secret, 'utf8').digest('hex');
+    }
+    async hashPassword(password) {
+        const salt = randomBytes(16);
+        const key = await scrypt(password, salt, SCRYPT_KEYLEN);
+        return `scrypt$${salt.toString('base64')}$${key.toString('base64')}`;
+    }
+    async verifyPassword(password, hash) {
+        const parts = hash.split('$');
+        if (parts.length !== 3 || parts[0] !== 'scrypt')
+            return false;
+        const salt = Buffer.from(parts[1], 'base64');
+        const expected = Buffer.from(parts[2], 'base64');
+        const actual = await scrypt(password, salt, expected.length);
+        return actual.length === expected.length && timingSafeEqual(actual, expected);
+    }
+    // --- Audit (P5) -----------------------------------------------------------
+    /**
+     * Hash chain. Each event commits to its predecessor in the same chain, where
+     * a chain is an org -- or the SYSTEM chain, `org_id IS NULL`, for decisions
+     * with no tenant to attribute them to.
+     *
+     * The digest now covers EVERY forensically relevant column, not the
+     * seven it used to cover. `reason`, `grant_id`, `ip`, `user_agent` and
+     * `context` are exactly the fields an incident responder relies on and
+     * exactly the fields an attacker would rewrite; leaving them outside the
+     * commitment made the chain decorative for the questions that matter.
+     *
+     * JSON encoding rather than string concatenation because concatenation is
+     * ambiguous: ('ab','c') and ('a','bc') would hash identically and a forger
+     * could shift field boundaries. `context` is canonicalised with sorted keys
+     * at every level, because jsonb does not preserve key order and the digest
+     * must survive the round trip through the database.
+     *
+     * CONCURRENCY -- fixed. This used to be a SELECT of the last hash
+     * followed by an INSERT, from here, in two statements -- atomic only under a
+     * single writer, and a chain FORK under two. It is now one call to
+     * `audit_append()`, which takes `pg_advisory_xact_lock` on the chain, reads
+     * the predecessor and inserts, all inside one statement and therefore one
+     * transaction. See the long comment on that function in schema.sql, including
+     * what PGlite can and cannot prove about it.
+     *
+     * The canonical encoding still lives here and only here: this method computes
+     * everything in the digest input EXCEPT the predecessor hash (which it cannot
+     * know without racing) and hands it over as `hash_tail`. The database
+     * prepends the predecessor it read under the lock. `verifyAuditChain` then
+     * recomputes the entire digest in TypeScript on read, so the SQL side and the
+     * TypeScript side are checked against each other by every chain verification
+     * in the suite.
+     *
+     * CHAIN FLOODING -- AND WHY IT IS NOT FIXED HERE.
+     *
+     * An unauthenticated caller who guesses an org UUID can cause denials to be
+     * appended to that tenant's chain. Under the per-chain lock above that is
+     * worse than storage growth: the tenant's own requests each take the same
+     * lock on the way through their audit write, so a flood is a latency attack
+     * on that tenant's whole request path, not merely noise in their log. (That
+     * interaction is new with the per-chain lock and is worth stating on its own.)
+     *
+     * It still does not belong in this function:
+     *
+     *  - P5 says every decision is recorded, INCLUDING denials, because denials
+     *    are the security-relevant events. Any in-engine mitigation is a rule for
+     *    DROPPING audit events, and a log with a "we stop recording under load"
+     *    clause is worthless in exactly the incident it exists for.
+     *  - The engine cannot distinguish a flood from reconnaissance. They are the
+     *    same request; only the rate differs, and rate is not observable from
+     *    inside a single decision.
+     *  - Admission control is the layer that can see it, and it belongs above the
+     *    engine.
+     *
+     * WHAT IS FIXED HERE: the blast radius. `orgExists` is project-scoped, so a
+     * caller can only reach a tenant chain inside a project they are already
+     * authenticated for; probes at every other org id land on the system chain.
+     * The exposure goes from "any internet caller can degrade any tenant" to "an
+     * authenticated customer can degrade their own tenant" -- a quota question.
+     * That reduction is asserted in test/semantics.test.ts.
+     *
+     * WHAT REMAINS AN OPERATIONAL REQUIREMENT ON THE API LAYER. Stated as a
+     * requirement, not a hope, and repeated in SEMANTICS.md:
+     *
+     *   R1. Every request carries a project credential; no project, no engine.
+     *   R2. Rate limit per (project, source address) BEFORE the engine runs.
+     *   R3. Cap per-project audit append rate and shed with 429 -- never by
+     *       dropping a decision that was actually made.
+     *   R4. Alert on SYSTEM-chain append rate. That chain is where unattributable
+     *       probes go, so its rate is the enumeration signal.
+     */
+    async audit(event) {
+        const occurredAt = this.now();
+        const ip = normalizeIp(event.ip);
+        const context = { ...(event.context ?? {}) };
+        // An address we cannot store as `inet` is kept verbatim in `context` rather
+        // than thrown away or, worse, passed to the cast: a malformed
+        // X-Forwarded-For must not be able to abort the audit write, because an
+        // audit write that fails takes the whole request with it.
+        if (event.ip !== undefined && event.ip !== null && ip === null) {
+            context['rawIp'] = String(event.ip).slice(0, 64);
+        }
+        const fields = {
+            // The predecessor is supplied by the database, under the chain lock.
+            prevHash: null,
+            orgId: event.orgId,
+            occurredAt,
+            action: event.action,
+            decision: event.decision,
+            reason: event.reason ?? null,
+            actorId: event.actorId,
+            fileId: event.fileId,
+            grantId: event.grantId ?? null,
+            ip,
+            userAgent: event.userAgent ?? null,
+            context,
+        };
+        await this.db.query(`SELECT id FROM audit_append($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::jsonb,$12)`, [
+            event.orgId,
+            occurredAt.toISOString(),
+            event.action,
+            event.decision,
+            fields.reason,
+            event.actorId,
+            event.fileId,
+            fields.grantId,
+            fields.ip,
+            fields.userAgent,
+            JSON.stringify(fields.context),
+            auditHashTail(fields),
+        ]);
+    }
+    async listAudit(orgId, filter = {}) {
+        const params = [orgId];
+        const clauses = ['org_id IS NOT DISTINCT FROM $1'];
+        if (filter.decision) {
+            params.push(filter.decision);
+            clauses.push(`decision = $${params.length}`);
+        }
+        if (filter.fileId) {
+            params.push(filter.fileId);
+            clauses.push(`file_id = $${params.length}`);
+        }
+        if (filter.actorId) {
+            params.push(filter.actorId);
+            clauses.push(`actor_id = $${params.length}`);
+        }
+        if (filter.action) {
+            params.push(filter.action);
+            clauses.push(`action = $${params.length}`);
+        }
+        params.push(Math.min(filter.limit ?? 500, 5000));
+        const { rows } = await this.db.query(`${AUDIT_COLUMNS}
+        WHERE ${clauses.join(' AND ')}
+        ORDER BY id ASC
+        LIMIT $${params.length}`, params);
+        return rows.map(mapAuditRow);
+    }
+    /**
+     * Full chain replay. Returns the first inconsistency found, if any.
+     * Pass `null` to verify the system chain.
+     */
+    async verifyAuditChain(orgId) {
+        const { rows } = await this.db.query(`${AUDIT_COLUMNS} WHERE org_id IS NOT DISTINCT FROM $1 ORDER BY id ASC`, [orgId]);
+        const events = rows.map(mapAuditRow);
+        let prev = null;
+        for (const e of events) {
+            if (e.prevHash !== prev) {
+                return {
+                    valid: false,
+                    checked: events.length,
+                    brokenAt: e.id,
+                    problem: 'prev_hash_mismatch',
+                };
+            }
+            const expected = auditHash({
+                prevHash: e.prevHash,
+                orgId: e.orgId,
+                occurredAt: e.occurredAt,
+                action: e.action,
+                decision: e.decision,
+                reason: e.reason,
+                actorId: e.actorId,
+                fileId: e.fileId,
+                grantId: e.grantId,
+                ip: e.ip,
+                userAgent: e.userAgent,
+                context: e.context,
+            });
+            if (expected !== e.hash) {
+                return { valid: false, checked: events.length, brokenAt: e.id, problem: 'hash_mismatch' };
+            }
+            prev = e.hash;
+        }
+        return { valid: true, checked: events.length };
+    }
+    // --- Counters (P6) --------------------------------------------------------
+    /**
+     * The conditional write *is* the reservation, and it charges the whole
+     * ancestor chain (see `consume_download` in schema.sql). Never read the
+     * counter and then decide -- see the "naive" comparison in the test suite for
+     * what that costs.
+     *
+     * The function now always returns exactly one row, and this reads
+     * `granted === true` rather than defaulting a missing value. Both halves of
+     * that had to change: an explicit `(false, 0)` row makes the SQL side
+     * unambiguous, and an explicit `=== true` makes the TypeScript side fail
+     * closed even if the SQL side is ever replaced with something that returns
+     * nothing at all.
+     */
+    async consumeDownload(grantId) {
+        if (!isUuid(grantId))
+            return { granted: false, remaining: 0 };
+        const { rows } = await this.db.query(`SELECT granted, remaining FROM consume_download($1)`, [grantId]);
+        const r = rows[0];
+        if (!r || r.granted !== true)
+            return { granted: false, remaining: 0 };
+        return { granted: true, remaining: r.remaining === null ? null : Number(r.remaining) };
+    }
+    // --- Metering -------------------------------------------------------------
+    async recordUsage(orgId, kind, bytes = 0) {
+        const col = kind === 'authz' ? 'authz_checks' : kind === 'read' ? 'file_reads' : 'file_writes';
+        await this.db.query(`INSERT INTO usage_daily (org_id, day, ${col}, bytes_egressed)
+       VALUES ($1, current_date, 1, $2)
+       ON CONFLICT (org_id, day) DO UPDATE
+         SET ${col} = usage_daily.${col} + 1,
+             bytes_egressed = usage_daily.bytes_egressed + EXCLUDED.bytes_egressed`, [orgId, bytes]);
+    }
+    /**
+     * Distinct actors who own a file on a given day. `usage_daily` counts events;
+     * this counts PEOPLE, which is the quantity authorization load actually
+     * tracks -- the graph walk behind every decision grows with the number of
+     * distinct holders, not with how many bytes they hold. Idempotent per
+     * (org, day, actor).
+     */
+    async recordFileOwner(orgId, actorId) {
+        if (!isUuid(orgId) || !isUuid(actorId))
+            return;
+        await this.db.query(`INSERT INTO file_owning_user_daily (org_id, day, actor_id)
+       VALUES ($1, current_date, $2)
+       ON CONFLICT (org_id, day, actor_id) DO NOTHING`, [orgId, actorId]);
+    }
+}
+/**
+ * A page is bounded so that one request cannot be turned into an unbounded
+ * scan, and so that the single audit event's `fileIds` array stays bounded too.
+ */
+export const LIST_MAX_LIMIT = 200;
+export const LIST_DEFAULT_LIMIT = 50;
+/** Enum labels are `[a-z_]+` by construction. Assert it rather than assume it. */
+function enumLiteral(v) {
+    if (!/^[a-z_]+$/.test(v))
+        throw new Error(`unexpected enum literal: ${v}`);
+    return `'${v}'`;
+}
+/**
+ * `(role, is_owner, visibility) IN ((...),(...))`, generated from the derived
+ * cells. Returns null when the capability is unreachable by any role, so the
+ * caller can substitute a constant `false` -- `IN ()` is a syntax error, and a
+ * generator that emits a syntax error under a fail-CLOSED input is a generator
+ * that will one day be "fixed" by removing the branch.
+ */
+function roleCellSql(p) {
+    if (p.roleCells.length === 0)
+        return null;
+    return `(${p.roleCells
+        .map((c) => `(${enumLiteral(c.role)}, ${c.isOwner}, ${enumLiteral(c.visibility)})`)
+        .join(', ')})`;
+}
+/**
+ * `(floor, held role) IN ((...),(...))` -- the group-grant threshold, generated
+ * from the derived cells rather than written as `m.role >= g.subject_min_role`.
+ *
+ * WHY NOT JUST `>=`. Postgres would happily compare two `org_role` values by
+ * their DECLARATION ORDER in the enum, and it would be correct today. It would
+ * also be a second, independent statement of the role ordering, sitting in SQL,
+ * agreeing with `ROLE_RANK` in authz.ts only by coincidence -- and reordering
+ * the enum (or inserting a value into the middle of it, which
+ * `ALTER TYPE ... ADD VALUE BEFORE` permits) would silently change who can read
+ * what, with no test failing. Generating the pairs from `roleMeets()` keeps one
+ * definition of the ordering, in TypeScript, where the point check reads it.
+ *
+ * A `role` grant with no floor is not representable (the CHECK requires one)
+ * and an `org` grant's NULL floor reads as 'viewer', which is what the coalesce
+ * says.
+ *
+ * Returns `false` when the cell list is empty, for the same reason
+ * `roleCellSql` returns null: `IN ()` is a syntax error, and a generator that
+ * crashes on a fail-CLOSED input is a generator someone will "fix".
+ */
+export function membershipCellSql(cells) {
+    if (cells.length === 0)
+        return 'false';
+    const tuples = cells
+        .map((c) => `(${enumLiteral(c.minRole)}, ${enumLiteral(c.role)})`)
+        .join(', ');
+    return `(coalesce(g.subject_min_role::text, 'viewer'), m.role::text) IN (${tuples})`;
+}
+/**
+ * The lifecycle gate. `state` is the EFFECTIVE state -- a soft-deleted row is
+ * 'deleted' whatever the state column says, exactly as `getFile()` maps it, so
+ * a half-applied delete cannot leave a listable file behind.
+ */
+function lifecycleSql(p) {
+    if (p.lifecycleCells.length === 0)
+        return null;
+    const tuples = p.lifecycleCells
+        .map((c) => `(${enumLiteral(c.state)}, ${c.expired}, ${c.retained})`)
+        .join(', ');
+    return `(
+            CASE WHEN f.deleted_at IS NOT NULL THEN 'deleted' ELSE f.state::text END,
+            (f.expires_at IS NOT NULL AND f.expires_at <= $3::timestamptz),
+            (f.retain_until IS NOT NULL AND f.retain_until > $3::timestamptz)
+          ) IN (${tuples})`;
+}
+function toListedFile(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']),
+    };
+}
+const AUDIT_COLUMNS = `SELECT id, org_id, occurred_at, action, decision, reason, actor_id,
+              file_id, grant_id, host(ip) AS ip, user_agent, context, prev_hash, hash
+         FROM audit_event`;
+/**
+ * Canonical JSON: object keys sorted at every depth, so a value that has been
+ * through jsonb (which does not preserve insertion order) hashes identically to
+ * the value that was written.
+ */
+export function canonicalJson(v) {
+    if (Array.isArray(v))
+        return v.map(canonicalJson);
+    if (v && typeof v === 'object') {
+        const src = v;
+        const out = {};
+        for (const k of Object.keys(src).sort())
+            out[k] = canonicalJson(src[k]);
+        return out;
+    }
+    return v === undefined ? null : v;
+}
+/**
+ * Everything in the digest input EXCEPT the predecessor hash, as the tail of a
+ * JSON array -- i.e. `orgId,...,context]`, with no leading bracket.
+ *
+ * This split is what lets `audit_append()` (schema.sql) take the chain lock,
+ * read the predecessor and compute the digest in ONE statement without any of
+ * the canonical encoding being duplicated in SQL. The database performs one
+ * concatenation:
+ *
+ *     '[' || to_json(prev_hash) || ',' || tail
+ *
+ * `prevHash` is the first element of the array for exactly this reason, and
+ * moving it would silently break the chain -- which is why the ordering is
+ * asserted by a test rather than left to a comment.
+ */
+export function auditHashTail(input) {
+    return JSON.stringify([
+        input.orgId,
+        input.occurredAt.toISOString(),
+        input.action,
+        input.decision,
+        input.reason ?? null,
+        input.actorId,
+        input.fileId,
+        input.grantId ?? null,
+        input.ip ?? null,
+        input.userAgent ?? null,
+        canonicalJson(input.context ?? {}),
+    ]).slice(1); // drop the leading '['; the database supplies it with prev_hash
+}
+export function auditHash(input) {
+    const canonical = `[${JSON.stringify(input.prevHash)},${auditHashTail(input)}`;
+    return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+function mapAuditRow(r) {
+    const rawContext = r['context'];
+    return {
+        id: Number(r['id']),
+        orgId: r['org_id'] ?? null,
+        occurredAt: new Date(r['occurred_at']),
+        action: r['action'],
+        decision: r['decision'],
+        reason: r['reason'] ?? null,
+        actorId: r['actor_id'] ?? null,
+        fileId: r['file_id'] ?? null,
+        grantId: r['grant_id'] ?? null,
+        ip: r['ip'] ?? null,
+        userAgent: r['user_agent'] ?? null,
+        context: typeof rawContext === 'string'
+            ? JSON.parse(rawContext)
+            : (rawContext ?? {}),
+        prevHash: r['prev_hash'] ?? null,
+        hash: r['hash'],
+    };
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isUuid(v) {
+    return typeof v === 'string' && UUID_RE.test(v);
+}
+const IPV4_RE = /^\d{1,3}(\.\d{1,3}){3}$/;
+const IPV6_RE = /^[0-9a-f:]{2,45}$/i;
+/**
+ * Accept only what `inet` will take back out unchanged.
+ *
+ * Two reasons this is not paranoia. First, `host(inet)` is what the chain
+ * verifier reads, so any value Postgres would normalise (a CIDR suffix, for
+ * instance) would silently break tamper-evidence for every subsequent event.
+ * Second, an unparseable address would raise on INSERT, and since the audit
+ * write is on the critical path of every request, that turns a malformed
+ * `X-Forwarded-For` header into an outage.
+ */
+export function normalizeIp(v) {
+    if (typeof v !== 'string')
+        return null;
+    const s = v.trim();
+    if (s.length === 0 || s.length > 45 || s.includes('/'))
+        return null;
+    if (IPV4_RE.test(s)) {
+        return s.split('.').every((o) => Number(o) <= 255 && String(Number(o)) === o) ? s : null;
+    }
+    if (!s.includes(':') || !IPV6_RE.test(s.replace(/\.\d{1,3}/g, '')))
+        return null;
+    // ::ffff:1.2.3.4 and friends: the tail must still be a legal dotted quad.
+    const tail = s.slice(s.lastIndexOf(':') + 1);
+    if (tail.includes('.') && !IPV4_RE.test(tail))
+        return null;
+    return s;
+}
+//# sourceMappingURL=store.js.map