@filelayer/core 0.3.0

package/dist/authz.js

@@ -0,0 +1,889 @@
+/**
+ * FILELAYER AUTHORIZATION ENGINE
+ *
+ * Every access question in the system is answered here. There is deliberately
+ * no second path. Reads, writes, deletes, shares, signed-URL redemptions,
+ * membership changes, file creation and audit access all resolve through this
+ * module, against one decision core (`allow` / `deny`).
+ *
+ * The engine has exactly two resource scopes:
+ *
+ *   authorize()     (actor, file, capability)      -- file-scoped
+ *   authorizeOrg()  (actor, org,  org capability)  -- org-scoped
+ *
+ * The org scope exists because some privileges are not about a file: creating
+ * one, reading the audit log, and changing who is in the organization. Those
+ * used to be hand-rolled checks in the API layer or entirely absent.
+ * Membership is a privilege change like any other, so it goes through
+ * the same path, with the same deny reasons and the same audit guarantee.
+ *
+ * WHY ONE ENGINE MATTERS MORE THAN IT LOOKS:
+ * The design goal is to minimise the "number of security-sensitive decisions a
+ * developer must make". In a hand-rolled integration built directly on Supabase,
+ * Convex or Vercel, that number scales with the number of *places* the
+ * developer touches files:
+ * every route, every RLS policy, every presign call is an independent chance
+ * to leak. Here the developer makes none of them, because there is exactly one
+ * place a decision can be made and it is not in the application.
+ *
+ * INVARIANTS (mirrored from schema.sql, enforced here in code):
+ *   P1 deny by default          - DENY unless a rule fires, at the file
+ *                                 boundary as well as the tenant boundary
+ *   P2 no ambient authority     - storage keys/URLs/ids are never inputs
+ *   P4 URL <= permission        - redemption re-validates the grant AND its
+ *                                 whole ancestor chain, always
+ *   P5 audit every decision     - every return path emits exactly one event,
+ *                                 including decisions with no tenant to charge
+ *
+ * EVALUATION ORDER IS A SECURITY PROPERTY:
+ *   1. Does the file exist?           -> no: deny, audit to the system chain
+ *   2. Does the caller have STANDING? -> no: deny, and say nothing more
+ *   3. Does their standing carry the requested capability?
+ *   4. Only then: lifecycle gates (deleted / expired / not ready / retained)
+ *
+ * Steps 1-3 are indistinguishable to the caller: everything is 404. The
+ * lifecycle statuses that are NOT 404 (410 Gone, 409 retention hold) are only
+ * ever reachable by someone who has already proven they may perform the
+ * operation, so they cannot be used to probe for the existence of a file.
+ * Previously these gates ran first and the API layer patched over the resulting
+ * oracle; that patch is gone.
+ */
+export const ALL_CAPABILITIES = ['read', 'write', 'delete', 'share'];
+const ALL_ROLES = ['viewer', 'member', 'admin', 'owner'];
+const ALL_VISIBILITIES = ['private', 'org'];
+const ALL_STATES = ['pending', 'ready', 'deleted'];
+/** Ordered so comparisons are possible. Higher index = strictly more power. */
+const ROLE_RANK = {
+    viewer: 0,
+    member: 1,
+    admin: 2,
+    owner: 3,
+};
+/**
+ * The subject types an issuer whose authority is GRANT-DERIVED may mint (I6).
+ *
+ * `actor` names one person and `link` is a bearer credential for one file;
+ * neither widens the population the issuer could already reach. `org`, `role`
+ * and `anonymous` all do, so a delegate may not create them at any depth.
+ *
+ * Exported so the rule is nameable in one place and testable directly, and so
+ * that adding a sixth subject type forces a decision about it here rather than
+ * silently defaulting to "delegable".
+ */
+export const DELEGABLE_SUBJECT_TYPES = ['actor', 'link'];
+/**
+ * THE ROLE THRESHOLD, DEFINED ONCE.
+ *
+ * `subject_min_role` is a floor over the existing four-value `org_role` enum
+ * and nothing more -- no custom roles, no nesting, no configurable inheritance.
+ * A `role` grant matches a principal holding `actual` iff this returns true; an
+ * `org` grant is the same question with `min = 'viewer'`.
+ *
+ * Both the point check (`getGroupGrants`) and the set query
+ * (`listAuthorizedFiles`) need this rule in SQL. Neither restates it: both are
+ * generated from `membershipCells()` below, which is generated from this
+ * function, exactly as the role matrix is generated from `fileCapabilities()`.
+ */
+export function roleMeets(actual, min) {
+    return ROLE_RANK[actual] >= ROLE_RANK[min];
+}
+/**
+ * Every (floor, held) pair that satisfies `roleMeets`. 4 x 4 = 16 probes of a
+ * pure function; 10 cells survive. This is the whole group-membership rule, in
+ * a form SQL can test with a tuple `IN` list.
+ */
+export function membershipCells() {
+    const cells = [];
+    for (const minRole of ALL_ROLES) {
+        for (const role of ALL_ROLES) {
+            if (roleMeets(role, minRole))
+                cells.push({ minRole, role });
+        }
+    }
+    return cells;
+}
+/**
+ * What each org role may do to a file in its own org.
+ *
+ * Deliberately small and total. Every cell is enumerated -- there is no
+ * fallthrough, no "and also if", no special case. A reviewer can read this
+ * table in ten seconds and know the entire role model, which is the point:
+ * an authorization model you cannot hold in your head is one you cannot audit.
+ *
+ * `visibility` closes the "every viewer in an org could read every file in it"
+ * defect. Under the default ('private') a file is not
+ * visible to the org at large at all; membership alone buys nothing at the file
+ * boundary. Org admins and owners keep full access under both settings, because
+ * retention, deletion and legal hold are their responsibility, and a control
+ * the accountable party cannot exercise is not a control.
+ */
+export function fileCapabilities(role, isOwner, visibility) {
+    const none = new Set();
+    const readOnly = new Set(['read']);
+    const full = new Set(['read', 'write', 'delete', 'share']);
+    switch (role) {
+        case 'viewer':
+            // Viewers never do more than read, and under 'private' they read only
+            // what is theirs.
+            return isOwner || visibility === 'org' ? readOnly : none;
+        case 'member':
+            // Members fully control their own files, and may read others' in the org
+            // only when the file was created org-visible.
+            if (isOwner)
+                return full;
+            return visibility === 'org' ? readOnly : none;
+        case 'admin':
+        case 'owner':
+            return full;
+    }
+}
+/**
+ * What each org role may do to the organization itself.
+ *
+ * The same shape as the file table above, and enumerated for the same reason.
+ * `manage_members` is admin+: membership is the most powerful thing in the
+ * system, because it is the thing that confers everything else.
+ */
+export function orgCapabilities(role) {
+    switch (role) {
+        case 'viewer':
+            return new Set();
+        case 'member':
+            return new Set(['create_file']);
+        case 'admin':
+        case 'owner':
+            return new Set(['create_file', 'manage_members', 'read_audit']);
+    }
+}
+/**
+ * Classify why a grant we can see is not live, for the audit log only.
+ *
+ * A grant that is self-consistent but still absent from `live_grant` is one
+ * whose ancestor chain is dead: that is P4 working, and the log should say so
+ * rather than reporting a forged secret.
+ */
+function deadGrantReason(g, now) {
+    if (g.revokedAt)
+        return 'grant_revoked';
+    if (g.expiresAt && g.expiresAt <= now)
+        return 'grant_expired';
+    if (g.maxDownloads !== null && g.downloadCount >= g.maxDownloads)
+        return 'grant_exhausted';
+    return 'grant_ancestor_dead';
+}
+/**
+ * @param complete when true, consult every source of authority even after the
+ *   requested capability has been found. The fast path stops as soon as it can
+ *   answer the question asked, which is right for an access check and wrong for
+ *   delegation: attenuation compares against everything the issuer holds, and a
+ *   partially-resolved set would refuse to pass on authority the issuer really
+ *   has. Only the share path pays for it.
+ */
+async function resolveStanding(deps, principal, file, capability, now, complete = false) {
+    const capabilities = new Set();
+    const acc = {
+        via: null,
+        grant: null,
+        role: null,
+    };
+    /** Absorb a capability set; report whether it supplied the one we need. */
+    const take = (caps, path, g) => {
+        let got = false;
+        for (const c of caps) {
+            capabilities.add(c);
+            if (c === capability)
+                got = true;
+        }
+        if (got && acc.via === null) {
+            acc.via = path;
+            acc.grant = g;
+        }
+        return got;
+    };
+    const settled = (halt = null) => ({
+        recognised: capabilities.size > 0,
+        role: acc.role,
+        capabilities,
+        grant: acc.grant,
+        via: acc.via,
+        halt,
+    });
+    // --- org role -------------------------------------------------------------
+    if (principal.actorId) {
+        acc.role = await deps.getMembership(file.orgId, principal.actorId);
+        if (acc.role) {
+            const caps = fileCapabilities(acc.role, file.ownerId === principal.actorId, file.visibility);
+            if (take(caps, 'role', null) && !complete)
+                return settled();
+        }
+        // --- explicit actor grants ---------------------------------------------
+        // A member of the org without the capability may still hold an explicit
+        // grant, so we accumulate rather than deciding here.
+        const grants = await deps.getActorGrants(file.id, principal.actorId);
+        for (const g of grants) {
+            if (take(g.capabilities, 'grant:actor', g) && !complete)
+                return settled();
+        }
+        // --- group grants: 'org' and 'role' (RFC-001) --------------------------
+        // Consulted AFTER the actor grants, so a grant naming this person by name
+        // wins the `via` attribution over one that reaches them as part of a
+        // population. Both are ordinary grant rows; nothing here is a special case
+        // in liveness, revocation, delegation or capability handling.
+        //
+        // ONE EXTRA QUERY, resolved by JOIN. No fan-out, no materialized member
+        // list, nothing cached: add or remove a member and the very next call to
+        // this function sees it, with no grant row touched.
+        const groupGrants = await deps.getGroupGrants(file.id, principal.actorId);
+        for (const g of groupGrants) {
+            const path = g.subjectType === 'role' ? 'grant:role' : 'grant:org';
+            if (take(g.capabilities, path, g) && !complete)
+                return settled();
+        }
+        if (acc.via !== null && !complete)
+            return settled();
+    }
+    // --- link grants ----------------------------------------------------------
+    if (principal.linkSecret) {
+        const hash = await deps.hashSecret(principal.linkSecret);
+        const live = await deps.findLiveGrantBySecret(hash);
+        // The grant must belong to the file being requested. Without this check a
+        // valid link for file A would authorize file B -- the classic confused
+        // deputy. It is one line and it is the whole ballgame.
+        if (live && live.fileId === file.id) {
+            if (live.passwordHash) {
+                const ok = principal.password !== undefined &&
+                    (await deps.verifyPassword(principal.password, live.passwordHash));
+                if (!ok)
+                    return settled({ reason: 'bad_password', grantId: live.id });
+            }
+            if (take(live.capabilities, 'grant:link', live) && !complete)
+                return settled();
+        }
+        else if (!live) {
+            // Attribution only, never authorization: if the secret is real but the
+            // grant (or an ancestor of it) is dead, the log records which grant and
+            // why. This is what makes an exhausted or revoked link visible in the
+            // compliance record instead of looking like a forged one.
+            const any = await deps.findGrantBySecret(hash);
+            if (any && any.fileId === file.id) {
+                return settled({ reason: deadGrantReason(any, now), grantId: any.id });
+            }
+        }
+    }
+    // --- anonymous grants -----------------------------------------------------
+    // Note this is NOT a "public" flag on the file. It is an explicitly created,
+    // individually revocable, individually auditable grant row (P1). Anonymous
+    // grants are read-only by CHECK constraint, so there is nothing to look up
+    // when a stronger capability was asked for -- unless we are resolving the
+    // full set for delegation.
+    if (capability === 'read' || complete) {
+        const anon = await deps.getAnonymousGrant(file.id);
+        if (anon)
+            take(anon.capabilities, 'grant:anonymous', anon);
+    }
+    return settled();
+}
+/** The reason to report when a principal has no standing on a file at all. */
+function noStandingReason(principal, role) {
+    if (principal.actorId)
+        return role ? 'insufficient_role' : 'no_membership';
+    if (principal.linkSecret)
+        return 'bad_link_secret';
+    return 'no_grant';
+}
+/**
+ * File lifecycle gates, in order of severity. Null means the file is usable.
+ *
+ * Retention holds block deletion even for org owners. This is the point of
+ * retention: it must bind the people who would otherwise be able to override
+ * it, or it is not a compliance control.
+ */
+function lifecycleDenial(file, capability, now) {
+    if (file.state === 'deleted')
+        return 'file_deleted';
+    if (file.expiresAt && file.expiresAt <= now)
+        return 'file_expired';
+    if (file.state === 'pending' && capability === 'read')
+        return 'file_not_ready';
+    if (capability === 'delete' && file.retainUntil && file.retainUntil > now) {
+        return 'retention_hold';
+    }
+    return null;
+}
+/**
+ * The whole file-scoped decision, exactly once, emitting exactly one event.
+ * `authorize` and `authorizeShare` both run through here so that asking a
+ * second question about the same request cannot cost a second audit event or a
+ * second round of queries.
+ */
+async function decideFile(deps, principal, fileId, capability, complete = false) {
+    const now = deps.now();
+    const file = await deps.getFile(fileId);
+    // --- 1. Existence ---------------------------------------------------------
+    // Audited against the SYSTEM chain: there is no tenant to charge an
+    // enumeration probe to, and inventing one would itself leak whether the file
+    // exists. Dropping the event -- which is what we used to do -- made a file-id
+    // sweep completely invisible.
+    if (!file) {
+        return {
+            decision: await deny(deps, null, principal, fileId, capability, 'file_not_found'),
+            file: null,
+            standing: null,
+        };
+    }
+    // --- 2. Standing ----------------------------------------------------------
+    const standing = await resolveStanding(deps, principal, file, capability, now, complete);
+    const out = (decision) => ({ decision, file, standing });
+    if (standing.halt) {
+        return out(await deny(deps, file.orgId, principal, fileId, capability, standing.halt.reason, standing.halt.grantId));
+    }
+    if (!standing.recognised) {
+        return out(await deny(deps, file.orgId, principal, fileId, capability, noStandingReason(principal, standing.role)));
+    }
+    // --- 3. Capability --------------------------------------------------------
+    if (!standing.capabilities.has(capability)) {
+        return out(await deny(deps, file.orgId, principal, fileId, capability, standing.role ? 'insufficient_role' : 'grant_wrong_capability'));
+    }
+    // --- 4. Lifecycle ---------------------------------------------------------
+    // Reached only by a caller who both has standing and holds the capability,
+    // so a 410 or a 409 here tells an attacker nothing they did not already have
+    // the authority to learn.
+    const lifecycle = lifecycleDenial(file, capability, now);
+    if (lifecycle) {
+        return out(await deny(deps, file.orgId, principal, fileId, capability, lifecycle, standing.grant?.id));
+    }
+    return out(await allow(deps, file.orgId, principal, fileId, capability, standing.via, standing.grant));
+}
+/** THE authorization decision. */
+export async function authorize(deps, principal, fileId, capability) {
+    return (await decideFile(deps, principal, fileId, capability)).decision;
+}
+/**
+ * Derive the set predicate from the point-check functions.
+ *
+ * Pure, total, and cheap enough to call per request (28 function calls). It is
+ * called per request rather than memoised so that it cannot go stale against a
+ * hot-reloaded or monkey-patched role table.
+ */
+export function listPredicate(capability) {
+    const roleCells = [];
+    for (const role of ALL_ROLES) {
+        for (const isOwner of [false, true]) {
+            for (const visibility of ALL_VISIBILITIES) {
+                if (fileCapabilities(role, isOwner, visibility).has(capability)) {
+                    roleCells.push({ role, isOwner, visibility });
+                }
+            }
+        }
+    }
+    // A fixed reference clock: we are probing a pure function, not reading time.
+    const now = new Date(1_000_000);
+    const past = new Date(now.getTime() - 1000);
+    const future = new Date(now.getTime() + 1000);
+    const lifecycleCells = [];
+    for (const state of ALL_STATES) {
+        for (const expired of [false, true]) {
+            for (const retained of [false, true]) {
+                const probe = {
+                    id: '',
+                    orgId: '',
+                    ownerId: null,
+                    state,
+                    visibility: 'private',
+                    expiresAt: expired ? past : null,
+                    retainUntil: retained ? future : null,
+                };
+                if (lifecycleDenial(probe, capability, now) === null) {
+                    lifecycleCells.push({ state, expired, retained });
+                }
+            }
+        }
+    }
+    // Mirrors `resolveStanding`: the anonymous grant is consulted only for
+    // `read` on the access path. (Anonymous grants are read-only by CHECK, so
+    // this is belt and braces -- but the point check has the branch, so the set
+    // query must have it too or the two are not the same predicate.)
+    //
+    // Group grants have NO capability branch: unlike anonymous, they may carry
+    // any capability, so they are consulted for every capability -- which is
+    // exactly what `resolveStanding` does. The membership cells are the whole of
+    // the extra rule, and they are derived, not written.
+    return {
+        capability,
+        roleCells,
+        lifecycleCells,
+        membershipCells: membershipCells(),
+        anonymousEligible: capability === 'read',
+    };
+}
+/**
+ * THE set-scoped authorization decision.
+ *
+ * Note what this does NOT do: it does not gate on org membership before
+ * running the query. That would be a SECOND, different rule -- and it would be
+ * WRONG, because a grant may be issued to an actor who is not a member of the
+ * owning org at all. Such an actor's `authorize(read)` returns allow, so their
+ * `listFiles` must return that file, or the two disagree and the set query is
+ * not the access model.
+ *
+ * The empty set is therefore the correct answer for a caller with no standing,
+ * and it is also the answer for an org that does not exist. That symmetry is
+ * deliberate: a 404 for "no such org" against a 200 for "org you cannot see"
+ * would rebuild the existence oracle that the evaluation order closes.
+ *
+ * AUDIT: ONE event per call, not one per file. Reasoning in full, because it is
+ * a judgement call, and the reasons are recorded here:
+ *
+ *  - The principal made ONE decision request and the engine evaluated ONE
+ *    predicate. N events would describe an operation that did not happen: the
+ *    caller did not access N files, they enumerated their own authorized set.
+ *  - N events would put N hash-chain writes on the critical path of a read.
+ *    The chain is serialized per org (see the chain-append note in store.ts),
+ *    so a 200-row page would
+ *    serialize 200 writes behind one lock. That is not a cost trade, it is an
+ *    availability defect.
+ *  - It would make unauthenticated chain flooding trivially worse: one
+ *    request would append a page's worth of events.
+ *  - A per-file loop would also emit a DENY for every file the caller may not
+ *    see, which in a tenant with 100k files is 100k rows per listing screen.
+ *
+ * What is NOT given up: the event records the predicate (capability), the
+ * caller's role, the result cardinality and the returned ids, so "what did this
+ * principal learn the existence of, and when" is answerable from the log. And
+ * an empty result from a caller with no standing is recorded as a DENY with the
+ * same reason vocabulary the point check uses, so enumeration of a tenant by a
+ * non-member still shows up in a `decision = 'deny'` query.
+ */
+export async function authorizeList(deps, principal, orgId, opts) {
+    const now = deps.now();
+    const exists = await deps.orgExists(orgId);
+    const role = exists && principal.actorId ? await deps.getMembership(orgId, principal.actorId) : null;
+    // One row over the page size, so "is there another page" costs nothing. A
+    // count(*) would have to evaluate the predicate over the whole tenant, which
+    // is both slow and a way to measure a tenant you cannot read.
+    //
+    // NOTE: the query runs whether or not `orgExists` said yes, and `exists` is
+    // used ONLY to decide which audit chain the event belongs to. Gating the
+    // query on it would be a precondition the point check does not have.
+    //
+    // This is where a stale-scope defect was found. `getMembership` joined `org` on
+    // `deleted_at IS NULL` and `getActorGrants` did not, so a soft-deleted org
+    // stopped conferring membership while leaving outstanding grants alive:
+    // `authorize()` still allowed a grant-holder to read those files, and a
+    // version of this function that skipped the query returned LESS than
+    // `authorize()` permitted. Fail-closed, and still a divergence, and the
+    // differential test caught it.
+    //
+    // That is now closed in the schema (`grant_scope_is_live`), so BOTH sides
+    // return nothing for a deleted org -- and they return nothing for the same
+    // reason, evaluated in the same predicate, rather than by two functions that
+    // happen to agree. The structure here is unchanged on purpose: `exists`
+    // still selects a chain and never gates a query.
+    const fetched = await deps.listAuthorizedFiles({
+        orgId,
+        actorId: principal.actorId,
+        predicate: listPredicate(opts.capability),
+        now,
+        limit: opts.limit + 1,
+        cursor: opts.cursor,
+    });
+    const hasMore = fetched.length > opts.limit;
+    const files = hasMore ? fetched.slice(0, opts.limit) : fetched;
+    const empty = files.length === 0;
+    await deps.audit({
+        // An org we cannot confirm goes to the system chain, exactly as
+        // `authorizeOrg` does, and for the same reason.
+        orgId: exists ? orgId : null,
+        action: 'file.list',
+        decision: empty ? 'deny' : 'allow',
+        ...(empty ? { reason: noStandingReason(principal, role) } : {}),
+        actorId: principal.actorId,
+        fileId: null,
+        ...(principal.ip !== undefined ? { ip: principal.ip } : {}),
+        ...(principal.userAgent !== undefined ? { userAgent: principal.userAgent } : {}),
+        context: {
+            ...(exists ? {} : { chain: 'system', orgId }),
+            capability: opts.capability,
+            role,
+            count: files.length,
+            fileIds: files.map((f) => f.id),
+            paged: opts.cursor !== null,
+            hasMore,
+        },
+    });
+    return { files, hasMore, role };
+}
+/**
+ * May this principal mint a grant on this file carrying these capabilities, to
+ * this kind of subject?
+ *
+ * Three questions, and all three belong here rather than in the API layer:
+ *
+ *   1. May they share at all?
+ *   2. Is what they are handing out a SUBSET of what they hold?   (capability)
+ *   3. Is who they are handing it to no WIDER than they may reach? (I6, breadth)
+ *
+ * (2) used to live in `filelayer.share()`, which meant any second entry point
+ * built on `authorize()` silently reintroduced the escalation: a holder
+ * of `{share}` minting themselves `{delete}`. It is an authorization question,
+ * so the authorization engine answers it. The schema enforces the same rule
+ * again on the row itself, because a rule that exists only in application code
+ * binds only the application.
+ *
+ * (3) is the same argument in the other dimension, and it is new (RFC-001, I6).
+ * Attenuation over capabilities says what a delegate may DO; without a rule
+ * over subject breadth, a contractor holding one `{read, share}` grant could
+ * re-grant to an entire organization -- or to `anonymous` -- and every
+ * capability check would pass, because the child's set is a subset. Authority
+ * derived from an ORG ROLE (`via` of 'role' or 'owner') may name any subject;
+ * authority derived from a GRANT may name only an `actor` or mint a `link`.
+ *
+ * The engine refuses first, so the refusal is a decision with a reason and an
+ * audit event. The trigger in schema.sql refuses the same row again, so the
+ * rule holds for a caller issuing raw SQL. Same structure, same reasoning, as
+ * capability attenuation.
+ *
+ * -----------------------------------------------------------------------------
+ * KNOWN GAP, RECORDED RATHER THAN HIDDEN: `held` IS A UNION, `parentGrantId` IS
+ * ONE ROW.
+ * -----------------------------------------------------------------------------
+ * `held` is the union of every capability the issuer holds from every source,
+ * while `parentGrantId` is the SINGLE grant that supplied `share`. When a
+ * principal holds several grants on one file, the engine can therefore approve
+ * a capability set that no single ancestor covers -- and the attenuation
+ * trigger, which compares the child against its ONE parent, then refuses the
+ * INSERT. The outcome is a 403 rather than a disclosure, so the failure is
+ * fail-CLOSED and P4 is intact; what is wrong is that a legitimate delegation
+ * can be refused, and which one depends on the order the grants come back in.
+ *
+ * That order is now defined (`getActorGrants` sorts oldest-first) so the
+ * behaviour is at least deterministic and reproducible. Closing the gap
+ * properly means either picking the parent that covers the requested set, or
+ * minting one child per contributing ancestor, and both are changes to the
+ * delegation model rather than to this rule. Out of scope for RFC-001; flagged
+ * here so it is a decision rather than an accident.
+ */
+export async function authorizeShare(deps, principal, fileId, requested, opts = {}) {
+    const resolved = await decideFile(deps, principal, fileId, 'share', true);
+    if (!resolved.decision.allow)
+        return { allow: false, reason: resolved.decision.reason };
+    const held = resolved.standing.capabilities;
+    for (const cap of requested) {
+        if (!held.has(cap)) {
+            await deps.audit({
+                orgId: resolved.file.orgId,
+                action: 'grant.create',
+                decision: 'deny',
+                reason: 'attenuation_violation',
+                actorId: principal.actorId,
+                fileId,
+                ...(principal.ip !== undefined ? { ip: principal.ip } : {}),
+                context: { requested: [...requested], held: [...held] },
+            });
+            return { allow: false, reason: 'attenuation_violation' };
+        }
+    }
+    // I6. `grantId` is set exactly when the authority that carried `share` came
+    // from a grant rather than from an org role -- it is the same value that
+    // becomes `parent_grant_id` below, which is what makes the engine's rule and
+    // the trigger's rule the same rule rather than two rules that agree.
+    const parentGrantId = resolved.decision.grantId ?? null;
+    const subjectType = opts.subjectType;
+    if (parentGrantId !== null &&
+        subjectType !== undefined &&
+        !DELEGABLE_SUBJECT_TYPES.includes(subjectType)) {
+        await deps.audit({
+            orgId: resolved.file.orgId,
+            action: 'grant.create',
+            decision: 'deny',
+            reason: 'subject_breadth_amplification',
+            actorId: principal.actorId,
+            fileId,
+            grantId: parentGrantId,
+            ...(principal.ip !== undefined ? { ip: principal.ip } : {}),
+            context: {
+                requestedSubjectType: subjectType,
+                via: resolved.decision.via,
+                delegableSubjectTypes: [...DELEGABLE_SUBJECT_TYPES],
+            },
+        });
+        return { allow: false, reason: 'subject_breadth_amplification' };
+    }
+    return {
+        allow: true,
+        via: resolved.decision.via,
+        // Authority derived from an org role has no parent grant; authority
+        // derived from a grant does, and the child is bound to it forever.
+        parentGrantId: resolved.decision.grantId ?? null,
+        held: [...held],
+    };
+}
+/**
+ * May this principal revoke this grant?
+ *
+ * Found during the review of the delegation work and fixed with it: holding
+ * `share` on a file used to mean holding revoke over EVERY grant on that file.
+ * A contractor given a delegated `{read, share}` could therefore revoke the
+ * owner's unrelated share links -- not a disclosure, but a straightforward
+ * denial of service against the file's other recipients, and a strange thing
+ * for "you may pass this on" to imply.
+ *
+ * The rule mirrors the delegation model rather than adding a new one:
+ *
+ *   - authority from an org ROLE (admin, owner, or the file's own owner)
+ *     carries revoke over every grant on the file, as before;
+ *   - authority from a GRANT carries revoke only over that grant's own subtree,
+ *     which is exactly the authority it was given.
+ */
+export async function authorizeRevoke(deps, principal, grant) {
+    const resolved = await decideFile(deps, principal, grant.fileId, 'share');
+    if (!resolved.decision.allow)
+        return resolved.decision;
+    const via = resolved.decision.grantId ?? null;
+    if (via === null || grant.id === via || (await deps.isDescendantOf(via, grant.id))) {
+        return resolved.decision;
+    }
+    await deps.audit({
+        orgId: grant.orgId,
+        action: 'grant.revoke',
+        decision: 'deny',
+        reason: 'foreign_grant',
+        actorId: principal.actorId,
+        fileId: grant.fileId,
+        grantId: grant.id,
+        ...(principal.ip !== undefined ? { ip: principal.ip } : {}),
+        context: { viaGrantId: via },
+    });
+    return { allow: false, reason: 'foreign_grant' };
+}
+// =============================================================================
+// THE ORG DECISION
+// =============================================================================
+export async function authorizeOrg(deps, principal, orgId, capability, opts = {}) {
+    const action = opts.action ?? `org.${capability}`;
+    const emitAllow = opts.emitAllow ?? true;
+    // An org we cannot see is audited to the system chain, for the same reason a
+    // file we cannot see is: attributing the event would confirm the org id, and
+    // the audit row's own foreign key would fail anyway.
+    const exists = await deps.orgExists(orgId);
+    if (!exists || !principal.actorId) {
+        return denyOrg(deps, exists ? orgId : null, principal, orgId, action, 'no_membership');
+    }
+    const role = await deps.getMembership(orgId, principal.actorId);
+    if (!role)
+        return denyOrg(deps, orgId, principal, orgId, action, 'no_membership');
+    if (!orgCapabilities(role).has(capability)) {
+        return denyOrg(deps, orgId, principal, orgId, action, 'insufficient_role');
+    }
+    if (emitAllow) {
+        await deps.audit({
+            orgId,
+            action,
+            decision: 'allow',
+            actorId: principal.actorId,
+            fileId: null,
+            ...(principal.ip !== undefined ? { ip: principal.ip } : {}),
+            ...(principal.userAgent !== undefined ? { userAgent: principal.userAgent } : {}),
+            context: { via: 'role', role, capability },
+        });
+    }
+    return { allow: true, via: 'role' };
+}
+/**
+ * May this principal set `targetActorId` to `newRole` (null = remove them)?
+ *
+ * Membership is the privilege that confers every other privilege, so the rules
+ * are stated here rather than left to the application:
+ *
+ *   - you must hold `manage_members` (admin or owner);
+ *   - you may not grant a role above your own -- otherwise `admin` is just
+ *     `owner` with an extra step;
+ *   - you may not modify anyone who currently outranks you;
+ *   - you may not remove or demote the last owner, because an org nobody
+ *     administers cannot honour a retention hold or a deletion request.
+ *
+ * Exactly one audit event is emitted per attempt, allow or deny. A membership
+ * change that leaves no trace is indistinguishable from a breach after the
+ * fact.
+ */
+export async function authorizeMembershipChange(deps, principal, orgId, targetActorId, newRole) {
+    const orgReal = await deps.orgExists(orgId);
+    const currentRole = orgReal ? await deps.getMembership(orgId, targetActorId) : null;
+    const action = newRole === null ? 'member.remove' : currentRole === null ? 'member.add' : 'member.role_change';
+    const base = await authorizeOrg(deps, principal, orgId, 'manage_members', {
+        action,
+        emitAllow: false,
+    });
+    if (!base.allow)
+        return base;
+    const actorRole = (await deps.getMembership(orgId, principal.actorId));
+    const context = { targetActorId, fromRole: currentRole, toRole: newRole, byRole: actorRole };
+    const settle = async (reason) => {
+        await deps.audit({
+            orgId,
+            action,
+            decision: reason ? 'deny' : 'allow',
+            ...(reason ? { reason } : {}),
+            actorId: principal.actorId,
+            fileId: null,
+            ...(principal.ip !== undefined ? { ip: principal.ip } : {}),
+            ...(principal.userAgent !== undefined ? { userAgent: principal.userAgent } : {}),
+            context,
+        });
+        return reason ? { allow: false, reason } : { allow: true, via: 'role' };
+    };
+    if (currentRole !== null && ROLE_RANK[currentRole] > ROLE_RANK[actorRole]) {
+        return settle('superior_target');
+    }
+    if (newRole !== null && ROLE_RANK[newRole] > ROLE_RANK[actorRole]) {
+        return settle('role_escalation');
+    }
+    if (currentRole === 'owner' && newRole !== 'owner' && (await deps.countOwners(orgId)) <= 1) {
+        return settle('last_owner');
+    }
+    return settle(null);
+}
+// =============================================================================
+// DECISION CORE -- the only places an access event is written
+// =============================================================================
+/**
+ * I4. For a group grant, "why did this succeed?" is not answered by `via`
+ * alone -- the caller is one of a population, and a compliance auditor needs to know
+ * which membership put them in it. The event already carries `actor_id` and
+ * `grant_id`, so the missing half is the subject org, the floor the grant
+ * asked for, and the role the caller actually held. All three come out of the
+ * membership join that already matched; none of them costs a second query.
+ */
+function membershipContext(grant) {
+    if (!grant || grant.subjectOrgId === null)
+        return {};
+    return {
+        viaOrgId: grant.subjectOrgId,
+        viaMinRole: grant.subjectMinRole,
+        ...(grant.matchedRole !== undefined ? { viaRole: grant.matchedRole } : {}),
+    };
+}
+async function allow(deps, orgId, p, fileId, capability, via, grant) {
+    await deps.audit({
+        orgId,
+        action: `file.${capability}`,
+        decision: 'allow',
+        actorId: p.actorId,
+        fileId,
+        grantId: grant?.id ?? null,
+        ...(p.ip !== undefined ? { ip: p.ip } : {}),
+        ...(p.userAgent !== undefined ? { userAgent: p.userAgent } : {}),
+        context: { via, ...membershipContext(grant) },
+    });
+    return {
+        allow: true,
+        via,
+        ...(grant ? { grantId: grant.id } : {}),
+        remainingDownloads: grant == null || grant.maxDownloads == null ? null : grant.maxDownloads - grant.downloadCount,
+    };
+}
+async function deny(deps, orgId, p, fileId, capability, reason, grantId) {
+    await deps.audit({
+        orgId,
+        action: `file.${capability}`,
+        decision: 'deny',
+        reason,
+        actorId: p.actorId,
+        fileId,
+        grantId: grantId ?? null,
+        ...(p.ip !== undefined ? { ip: p.ip } : {}),
+        ...(p.userAgent !== undefined ? { userAgent: p.userAgent } : {}),
+        ...(orgId === null ? { context: { chain: 'system' } } : {}),
+    });
+    return { allow: false, reason };
+}
+async function denyOrg(deps, auditOrgId, p, orgId, action, reason) {
+    await deps.audit({
+        orgId: auditOrgId,
+        action,
+        decision: 'deny',
+        reason,
+        actorId: p.actorId,
+        fileId: null,
+        ...(p.ip !== undefined ? { ip: p.ip } : {}),
+        ...(p.userAgent !== undefined ? { userAgent: p.userAgent } : {}),
+        context: auditOrgId === null ? { chain: 'system', orgId } : { orgId },
+    });
+    return { allow: false, reason };
+}
+/**
+ * Emit an audit event for a decision that never reached the engine because the
+ * credential presented could not be resolved to anything at all -- a link
+ * secret matching no grant. There is no file and no tenant, so it goes to the
+ * system chain. A truncated hash of the presented secret is recorded so a
+ * brute-force sweep is correlatable; it is a 48-bit prefix of a SHA-256, not
+ * the credential, and it is useless without the original.
+ */
+export async function auditUnresolvedSecret(deps, principal, secretHash) {
+    await deps.audit({
+        orgId: null,
+        action: 'file.read',
+        decision: 'deny',
+        reason: 'bad_link_secret',
+        actorId: principal.actorId,
+        fileId: null,
+        ...(principal.ip !== undefined ? { ip: principal.ip } : {}),
+        ...(principal.userAgent !== undefined ? { userAgent: principal.userAgent } : {}),
+        context: { chain: 'system', secretHashPrefix: secretHash.slice(0, 12) },
+    });
+}
+/**
+ * The refusals the schema raises on its own account (see the attenuation
+ * trigger in schema.sql).
+ *
+ * The engine refuses these cases first, so a trigger firing means the engine
+ * and the schema disagree -- which is a bug worth an alert, not a stack trace
+ * in a caller's face. The vocabulary lives here, next to the rules it mirrors,
+ * so that the two cannot drift apart in separate files.
+ */
+const SCHEMA_REFUSAL = /^(grant_capability_amplification|grant_subject_amplification|grant_parent_not_live|grant_parent_exhausted|grant_parent_missing|grant_delegation_too_deep|grant_lineage_immutable)/;
+export function schemaRefusal(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return SCHEMA_REFUSAL.test(message) ? message.split(':')[0] : null;
+}
+/**
+ * Collapse internal deny reasons into what the caller is told.
+ *
+ * Internally we record precisely why access was denied, because that is what
+ * makes the audit log useful for incident response. Externally we return 404
+ * for everything that would otherwise confirm a file's existence -- otherwise
+ * the error message becomes an enumeration oracle across tenants.
+ *
+ * Grant-level lifecycle reasons (revoked / expired / exhausted / ancestor dead)
+ * collapse to 404 as well. A 410 "your link is used up" would be friendlier and
+ * is reachable only by someone holding a 256-bit secret, so the leak is
+ * theoretical -- but it costs nothing to make a dead link indistinguishable
+ * from a forged one, and the audit log carries the true reason for the operator
+ * who actually needs it.
+ *
+ * The asymmetry between what we log and what we return is intentional and is
+ * the kind of decision a hand-rolled integration requires developers to make
+ * themselves, in every route, correctly, every time.
+ */
+export function toPublicError(reason) {
+    switch (reason) {
+        case 'bad_password':
+            return { status: 401, code: 'password_required' };
+        case 'file_expired':
+            return { status: 410, code: 'gone' };
+        case 'retention_hold':
+            return { status: 409, code: 'retention_hold' };
+        // Attenuation and membership-management refusals are answered to a caller
+        // who has already proven standing and already knows the resource exists:
+        // 403 leaks nothing and is far more useful than a 404.
+        case 'attenuation_violation':
+        case 'subject_breadth_amplification':
+        case 'role_escalation':
+        case 'superior_target':
+        case 'last_owner':
+            return { status: 403, code: 'forbidden' };
+        default:
+            return { status: 404, code: 'not_found' };
+    }
+}
+//# sourceMappingURL=authz.js.map