@wtfalch/authz-store 0.2.1 → 0.3.0

package/dist/tree.js

@@ -0,0 +1,565 @@
+import { and, asc, eq, gte, inArray, isNotNull, or, sql } from 'drizzle-orm';
+import { primaryRoleKey } from './assignments.js';
+import { isCustomRoleKey } from './role-keys.js';
+import { authzEvents, memberships, tenants } from './schema.js';
+/**
+ * A parent chain that does not terminate, or is longer than any depth this
+ * app allows. Cycles are impossible through the functions in this file (an
+ * attach refuses one before it is written), so this is a corruption report,
+ * not a condition a caller handles: it throws rather than returning a
+ * refusal, and it fails the transaction it is in.
+ */
+export class TenantCycleError extends Error {
+    constructor(tenantId) {
+        super(`the parent chain above tenant ${tenantId} does not terminate`);
+        this.name = 'TenantCycleError';
+    }
+}
+/**
+ * The hard stop on every traversal, above whatever `maxDepth` a policy sets.
+ * A chain longer than this is data nothing in this file could have written.
+ */
+const MAX_CHAIN = 8;
+const NODE_COLUMNS = {
+    id: tenants.id,
+    kind: tenants.kind,
+    slug: tenants.slug,
+    name: tenants.name,
+    state: tenants.state,
+    parentId: tenants.parentId,
+    ceiling: tenants.ceiling,
+    selfDenied: tenants.selfDenied,
+};
+function nodeOf(row) {
+    return {
+        id: row.id,
+        kind: row.kind,
+        slug: row.slug,
+        name: row.name,
+        state: row.state,
+        parentId: row.parentId,
+        ceiling: row.ceiling,
+        selfDenied: row.selfDenied,
+    };
+}
+/** One tenant, or null. */
+export async function nodeById(tx, tenantId) {
+    const [row] = await tx
+        .select(NODE_COLUMNS)
+        .from(tenants)
+        .where(eq(tenants.id, tenantId))
+        .limit(1);
+    return row ? nodeOf(row) : null;
+}
+/**
+ * Locks the given tenants `FOR UPDATE`, always in ascending id order, and
+ * returns them keyed by id. The order is the point: an attach and a rename
+ * touching the same two rows from opposite ends would deadlock, and sorting
+ * the ids gives every transaction in this module the same lock sequence.
+ * Ids that name no row are simply absent from the map.
+ */
+export async function lockTenantsForUpdate(tx, tenantIds) {
+    const ids = [...new Set(tenantIds)].sort();
+    if (ids.length === 0)
+        return new Map();
+    const rows = await tx
+        .select(NODE_COLUMNS)
+        .from(tenants)
+        .where(inArray(tenants.id, ids))
+        .orderBy(asc(tenants.id))
+        .for('update');
+    return new Map(rows.map((row) => [row.id, nodeOf(row)]));
+}
+/**
+ * Locks a tenant and everything below it, and keeps looking until the set
+ * stops growing.
+ *
+ * Reading the subtree and then locking what it found is not the same thing,
+ * and the difference is a live bug rather than a nicety: an attach that
+ * commits between the read and the lock adds a child the caller will never
+ * see, so a ceiling cascade skips it and an "are there children" check says
+ * no while a child is sitting right there.
+ *
+ * Locking downward in waves closes it. An attach of C under P must lock P,
+ * so once P is locked no new child of P can appear; reading P's children
+ * under that lock gives a set that cannot grow, and locking those children
+ * in turn freezes the next level. The loop runs at most `MAX_CHAIN` times
+ * and, at the depths a policy allows, two or three.
+ */
+export async function lockSubtreeForUpdate(tx, rootId) {
+    const locked = await lockTenantsForUpdate(tx, [rootId]);
+    if (locked.size === 0)
+        return locked;
+    let frontier = [rootId];
+    for (let level = 0; level < MAX_CHAIN && frontier.length > 0; level += 1) {
+        const rows = await tx
+            .select({ id: tenants.id })
+            .from(tenants)
+            .where(inArray(tenants.parentId, frontier));
+        const fresh = rows.map((row) => row.id).filter((id) => !locked.has(id));
+        if (fresh.length === 0)
+            break;
+        for (const [id, node] of await lockTenantsForUpdate(tx, fresh))
+            locked.set(id, node);
+        frontier = fresh;
+    }
+    return locked;
+}
+/**
+ * Locks everything `attachProblem` is about to read: the child and its whole
+ * subtree, the proposed parent, and every ancestor above the parent.
+ *
+ * Locking only the two named tenants is not enough, because the depth rule
+ * counts rows neither of them is. Two attaches at opposite ends of one chain
+ * lock disjoint pairs, each reads a depth that is true at the time and stale
+ * by the time it commits, and together they build a tree deeper than
+ * `maxDepth` allows. That cannot happen at a policy depth of 1, where no
+ * chain is long enough to have two ends; it happens at a two-level host's
+ * depth of 2, which runs this same code.
+ */
+export async function lockAttachScope(tx, parentId, childId) {
+    await lockSubtreeForUpdate(tx, childId);
+    await lockTenantsForUpdate(tx, [parentId, ...(await ancestorsOf(tx, parentId)).map((n) => n.id)]);
+}
+/**
+ * Every ancestor of this tenant, nearest first: its parent, then its
+ * parent's parent, and so on to the root. Empty for a tenant with no parent.
+ * Bounded by `MAX_CHAIN` and by a visited set, so a cycle in the data throws
+ * instead of hanging.
+ */
+export async function ancestorsOf(tx, tenantId) {
+    const chain = [];
+    const seen = new Set([tenantId]);
+    let current = await nodeById(tx, tenantId);
+    while (current?.parentId) {
+        if (seen.has(current.parentId))
+            throw new TenantCycleError(tenantId);
+        seen.add(current.parentId);
+        if (chain.length >= MAX_CHAIN)
+            throw new TenantCycleError(tenantId);
+        const parent = await nodeById(tx, current.parentId);
+        if (!parent)
+            break;
+        chain.push(parent);
+        current = parent;
+    }
+    return chain;
+}
+/** The tenants whose `parent_id` is this one. */
+export async function childrenOf(tx, tenantId) {
+    const rows = await tx
+        .select(NODE_COLUMNS)
+        .from(tenants)
+        .where(eq(tenants.parentId, tenantId))
+        .orderBy(asc(tenants.name));
+    return rows.map(nodeOf);
+}
+/**
+ * Every tenant below this one, breadth first, nearest level first. Excludes
+ * the tenant itself. One query per level rather than a recursive CTE: the
+ * depth is small, so this is two or three round trips with plainly
+ * readable SQL, and the loop is where the cycle guard lives.
+ */
+export async function descendantsOf(tx, tenantId) {
+    const found = [];
+    const seen = new Set([tenantId]);
+    let frontier = [tenantId];
+    for (let level = 0; level < MAX_CHAIN && frontier.length > 0; level += 1) {
+        const rows = await tx
+            .select(NODE_COLUMNS)
+            .from(tenants)
+            .where(inArray(tenants.parentId, frontier))
+            .orderBy(asc(tenants.name));
+        const next = [];
+        for (const row of rows) {
+            if (seen.has(row.id))
+                throw new TenantCycleError(tenantId);
+            seen.add(row.id);
+            found.push(nodeOf(row));
+            next.push(row.id);
+        }
+        frontier = next;
+    }
+    if (frontier.length > 0)
+        throw new TenantCycleError(tenantId);
+    return found;
+}
+/** How many edges sit above this tenant: 0 for a root, 1 for a child of a root. */
+export async function depthAbove(tx, tenantId) {
+    return (await ancestorsOf(tx, tenantId)).length;
+}
+/**
+ * How many edges sit below this tenant at its deepest: 0 for a leaf, 1 for a
+ * tenant whose children are all leaves. Computed from the subtree's own
+ * parent links rather than a second traversal per node.
+ */
+export async function heightBelow(tx, tenantId) {
+    const below = await descendantsOf(tx, tenantId);
+    if (below.length === 0)
+        return 0;
+    const depths = new Map([[tenantId, 0]]);
+    let height = 0;
+    // `descendantsOf` returns breadth first, so a node's parent is always
+    // already in the map by the time the node is read.
+    for (const node of below) {
+        const parentDepth = node.parentId === null ? 0 : (depths.get(node.parentId) ?? 0);
+        const depth = parentDepth + 1;
+        depths.set(node.id, depth);
+        if (depth > height)
+            height = depth;
+    }
+    return height;
+}
+/**
+ * Whether `childId` may be attached under `parentId`, checked against every
+ * cross-row rule D19 and D22 state. Called three times over the life of one
+ * attachment and deliberately so: by the host's `proposeAttach`, so a
+ * proposal that could never be accepted is refused when it is written; by
+ * `acceptAttach` inside the lock, which is the check that actually decides;
+ * and by the born-attached invitation path, where the proposal step never
+ * happened. Nothing is cached between them, because everything it reads can
+ * move while a proposal sits pending.
+ *
+ * Ceilings are the last check rather than the first because its refusal is
+ * the only one that names offenders, and a caller showing "narrow these two
+ * permissions first" should not be shown it about a pair that could never be
+ * attached anyway.
+ *
+ * `policy` carries `maxDepth` and `offered` (wave 3's `StorePolicy`) — the
+ * only two fields this function needs from it, not the role templates.
+ */
+export async function attachProblem(tx, policy, parentId, childId) {
+    if (parentId === childId) {
+        return { reason: 'self', message: 'An organisation cannot hold itself.' };
+    }
+    const parent = await nodeById(tx, parentId);
+    if (!parent) {
+        return { reason: 'parent_not_found', message: 'That organisation no longer exists.' };
+    }
+    const child = await nodeById(tx, childId);
+    if (!child) {
+        return { reason: 'child_not_found', message: 'That organisation no longer exists.' };
+    }
+    // D19: the operator tenant is never a parent or a child, or attaching would
+    // hand every operator standing membership in a customer (M5) or hand a
+    // customer's owners the console. The migration's CHECK stops it being a
+    // child; nothing single-row can see it being a parent, so both are here.
+    if (parent.kind === 'operator' || child.kind === 'operator') {
+        return {
+            reason: 'operator_tenant',
+            message: 'The operator organisation never holds another organisation, and is never held.',
+        };
+    }
+    if (child.parentId !== null) {
+        return {
+            reason: 'child_already_attached',
+            message: 'That organisation is already held by another one. Detach it first.',
+        };
+    }
+    if (child.state === 'archived' || parent.state === 'archived') {
+        return {
+            reason: 'archived',
+            message: 'An archived organisation cannot be attached or hold another.',
+        };
+    }
+    // A cycle is only possible above depth 1, and the depth rule below would
+    // catch most of them, but not all: attaching a root under its own
+    // grandchild keeps every chain short while making the tree circular. Asked
+    // directly rather than inferred.
+    const subtree = await descendantsOf(tx, childId);
+    if (subtree.some((node) => node.id === parentId)) {
+        return {
+            reason: 'cycle',
+            message: 'That organisation is already held below this one.',
+        };
+    }
+    const above = await depthAbove(tx, parentId);
+    const below = await heightBelow(tx, childId);
+    if (above + 1 + below > policy.maxDepth) {
+        return {
+            reason: 'too_deep',
+            message: policy.maxDepth === 1
+                ? 'An organisation that holds another cannot itself be held.'
+                : `Organisations can be nested ${policy.maxDepth} levels deep here, and this would be deeper.`,
+        };
+    }
+    // D22: a child's ceiling is a subset of its parent's, so a reseller offers
+    // its customers at most what it was offered. Refused with the offenders
+    // named, because narrowing the child is the fix and the person doing it
+    // needs to know which permissions to take off.
+    const offenders = child.ceiling.filter((p) => policy.offered.includes(p) && !parent.ceiling.includes(p));
+    if (offenders.length > 0) {
+        return {
+            reason: 'ceiling_exceeds',
+            message: `${child.name} may use more than ${parent.name} does. Narrow it first: ${offenders.join(', ')}.`,
+            offenders,
+        };
+    }
+    return null;
+}
+/**
+ * Which of these principals hold a membership in the operator tenant.
+ *
+ * They are the ones D8's rule is about: "an operator has no standing reach
+ * into membership". An attachment is a customer organisation agreeing to be
+ * held by another, and both sides now consent to it (M5), but neither of them
+ * is agreeing to whoever happens to run the console. Somebody who is both an
+ * operator and an ordinary member of a parent would otherwise be carried into
+ * every child it takes on, silently, as a consequence of a decision that was
+ * about the two organisations and not about them.
+ *
+ * Note what this does NOT do. It is about operator standing, not about
+ * inherited membership in general: a reseller's staff still reach every
+ * client they hold, with no per-person approval, which is the entire point of
+ * nesting. An operator who needs to be in a customer organisation still has
+ * the two routes D8 leaves them: a break-glass session, or an ordinary
+ * invitation from that organisation, which is a direct row and untouched by
+ * this.
+ */
+async function operatorStanding(tx, principalIds) {
+    if (principalIds.length === 0)
+        return new Set();
+    const rows = await tx
+        .select({ principalId: memberships.principalId, principalClass: memberships.principalClass })
+        .from(memberships)
+        .innerJoin(tenants, eq(memberships.tenantId, tenants.id))
+        .where(and(eq(tenants.kind, 'operator'), inArray(memberships.principalId, [...principalIds])));
+    return new Set(rows.map((row) => `${row.principalClass}:${row.principalId}`));
+}
+async function directRowsIn(tx, binding, tenantIds, principalIds) {
+    if (tenantIds.length === 0)
+        return [];
+    const conditions = [
+        inArray(memberships.tenantId, [...tenantIds]),
+        eq(memberships.source, 'direct'),
+    ];
+    if (principalIds) {
+        if (principalIds.length === 0)
+            return [];
+        conditions.push(inArray(memberships.principalId, [...principalIds]));
+    }
+    return tx
+        .select({
+        tenantId: memberships.tenantId,
+        principalId: memberships.principalId,
+        principalClass: memberships.principalClass,
+        role: primaryRoleKey(binding),
+        grantedBy: memberships.grantedBy,
+    })
+        .from(memberships)
+        .where(and(...conditions));
+}
+/**
+ * What derived rows tenant `tenantId` should hold, by the rule at the top of
+ * this file: the nearest ancestor's direct row for each principal, minus
+ * every principal who holds a direct row here. `principalIds` narrows the
+ * question to a few principals, which is what a single grant needs; without
+ * it the answer covers everyone the ancestry knows about, which is what an
+ * attach and the reconciliation check need.
+ *
+ * The one read every writer and the reconciliation check share, on purpose:
+ * reconciliation exists to catch a write that did not happen or a row that
+ * did not go, so it must ask the same question the writer answered. What
+ * catches the rule itself being wrong is the property tests, not a second
+ * copy of the rule that could be wrong in the same way.
+ */
+export async function expectedDerivedFor(tx, binding, tenantId, principalIds) {
+    return derivedFromChain(tx, binding, tenantId, await ancestorsOf(tx, tenantId), principalIds);
+}
+/**
+ * The rule itself, over whatever chain of ancestors it is handed, nearest
+ * first. `expectedDerivedFor` passes the chain a tenant actually has;
+ * `attachCustomRoleBlockers` passes the chain a tenant *would* have, which is
+ * the only way to answer a question about an attachment before writing it.
+ * Both go through here so there is one nearest-ancestor-wins implementation
+ * and not two that can disagree.
+ */
+async function derivedFromChain(tx, binding, tenantId, ancestors, principalIds) {
+    if (ancestors.length === 0)
+        return [];
+    const own = await directRowsIn(tx, binding, [tenantId], principalIds);
+    const identity = (row) => `${row.principalClass}:${row.principalId}`;
+    const held = new Set(own.map(identity));
+    const above = await directRowsIn(tx, binding, ancestors.map((node) => node.id), principalIds);
+    const byTenant = new Map();
+    for (const row of above) {
+        const list = byTenant.get(row.tenantId);
+        if (list)
+            list.push(row);
+        else
+            byTenant.set(row.tenantId, [row]);
+    }
+    // D8: operator standing never becomes standing membership in a customer
+    // organisation, however the tree is shaped. Asked once for the whole
+    // candidate set rather than per row.
+    const operators = await operatorStanding(tx, above.map((row) => row.principalId));
+    const expected = new Map();
+    // Nearest ancestor first, and the first answer for a principal wins.
+    for (const ancestor of ancestors) {
+        for (const row of byTenant.get(ancestor.id) ?? []) {
+            if (held.has(identity(row)))
+                continue;
+            if (expected.has(identity(row)))
+                continue;
+            if (operators.has(identity(row)))
+                continue;
+            expected.set(identity(row), {
+                principalId: row.principalId,
+                principalClass: row.principalClass,
+                role: row.role,
+                viaTenantId: ancestor.id,
+                grantedBy: row.grantedBy,
+            });
+        }
+    }
+    return [...expected.values()].sort((a, b) => a.principalId.localeCompare(b.principalId));
+}
+/**
+ * The custom roles standing in the way of writing derived rows for these
+ * tenants (D19: a derived membership carries a system role, never a custom
+ * one). Empty means the propagation may go ahead. Callers use this to refuse
+ * with the offenders named rather than propagating partially: the fix is to
+ * move those people to a system role at the parent, and only the parent can
+ * decide that.
+ */
+export async function customRoleBlockers(tx, binding, tenantIds, principalIds) {
+    const blockers = [];
+    for (const tenantId of tenantIds) {
+        for (const row of await expectedDerivedFor(tx, binding, tenantId, principalIds)) {
+            if (isCustomRoleKey(row.role)) {
+                blockers.push({
+                    tenantId,
+                    principalId: row.principalId,
+                    role: row.role,
+                    viaTenantId: row.viaTenantId,
+                });
+            }
+        }
+    }
+    return blockers;
+}
+/**
+ * The same question `customRoleBlockers` answers, but about an attachment
+ * that has not happened yet: what custom roles would have to reach the
+ * child's subtree if `childId` were attached under `parentId`.
+ *
+ * This exists because the obvious call does not work. `customRoleBlockers`
+ * reads the ancestry a tenant has *now*, and a child being proposed to still
+ * has none, so asking it before the attach always answers "nothing" and the
+ * refusal D19 asks for could never fire. The two agents that hit this each
+ * worked around it by writing `parent_id` first and undoing the transaction
+ * when the check then fired, which works but makes a refusal cost a rollback
+ * and leaves every future caller to rediscover the trap.
+ *
+ * Call this BEFORE the attachment is written. Afterwards the ordinary
+ * `customRoleBlockers` is the right question, because by then the chain this
+ * one has to imagine is the chain that exists.
+ */
+export async function attachCustomRoleBlockers(tx, binding, parentId, childId) {
+    const parent = await nodeById(tx, parentId);
+    if (!parent)
+        return [];
+    // What would sit above the child once attached: the parent, then whatever
+    // is already above the parent.
+    const chainAboveChild = [parent, ...(await ancestorsOf(tx, parentId))];
+    const blockers = [];
+    for (const node of [{ id: childId }, ...(await descendantsOf(tx, childId))]) {
+        // Inside the child's own subtree the chain is unchanged and terminates at
+        // the child, since the child has no parent yet; the imagined chain simply
+        // continues from there.
+        const chain = [...(await ancestorsOf(tx, node.id)), ...chainAboveChild];
+        for (const row of await derivedFromChain(tx, binding, node.id, chain)) {
+            if (isCustomRoleKey(row.role)) {
+                blockers.push({
+                    tenantId: node.id,
+                    principalId: row.principalId,
+                    role: row.role,
+                    viaTenantId: row.viaTenantId,
+                });
+            }
+        }
+    }
+    return blockers;
+}
+/**
+ * The audit action one derived change writes as: the same three names a
+ * direct write uses. A derived row is a membership like any other, and the
+ * log says which ancestor it came from through `via_tenant_id` on the row
+ * rather than through a fourth action nobody would think to search for.
+ * Exported because every caller of `recomputeDerived` needs it, and three
+ * private copies of one switch is how the three drift apart.
+ */
+export function derivedEventAction(kind) {
+    switch (kind) {
+        case 'created':
+            return 'membership.created';
+        case 'role_changed':
+            return 'membership.role_changed';
+        case 'ended':
+            return 'membership.ended';
+    }
+}
+/**
+ * Every principal holding a direct row anywhere at or above this tenant: the
+ * set whose derived rows can move when the tree does. Used by
+ * `attachInTx`/`detachInTx` (`./tree-writes.js`), which change the shape
+ * rather than one person's role and so cannot narrow the recomputation to a
+ * principal they already know.
+ */
+export async function principalsAtOrAbove(tx, binding, tenantId) {
+    const ancestors = await ancestorsOf(tx, tenantId);
+    const rows = await directRowsIn(tx, binding, [tenantId, ...ancestors.map((node) => node.id)]);
+    return [...new Set(rows.map((row) => row.principalId))].sort();
+}
+/**
+ * What a reseller's staff left behind: every direct membership in this child
+ * that was granted, while the link stood, by someone whose own authority
+ * there was derived from the parent (D19's sixth rule). Nothing is removed;
+ * the child's owner gets the list and decides.
+ *
+ * Read before `detachInTx` (`./tree-writes.js`), because it asks who
+ * currently holds a derived row, and detaching is what takes those rows
+ * away.
+ */
+export async function detachReport(tx, binding, childId, since) {
+    // Who held a derived role here at any point while the link stood, not who
+    // still does. A reseller's staff member whose own role at the parent was
+    // taken away before the detach is exactly the case the report exists for,
+    // and reading only the live `inherited` rows loses them: propagation
+    // deleted their row the moment the parent demoted them, so by detach time
+    // there is nothing left in `memberships` to find. The log has it, because
+    // every derived row this link ever created was written as a membership
+    // event carrying `via_tenant_id`, and the link's own start is `since`.
+    const holders = new Set();
+    const live = await tx
+        .select({ principalId: memberships.principalId })
+        .from(memberships)
+        .where(and(eq(memberships.tenantId, childId), eq(memberships.source, 'inherited')));
+    for (const row of live)
+        holders.add(row.principalId);
+    const historical = await tx
+        .select({ targetId: authzEvents.targetId })
+        .from(authzEvents)
+        .where(and(eq(authzEvents.tenantId, childId), eq(authzEvents.targetType, 'membership'), eq(authzEvents.outcome, 'success'), gte(authzEvents.occurredAt, since), or(sql `${authzEvents.after}->>'viaTenantId' is not null`, sql `${authzEvents.before}->>'viaTenantId' is not null`)));
+    for (const row of historical)
+        holders.add(row.targetId);
+    const granters = [...holders];
+    if (granters.length === 0)
+        return [];
+    const rows = await tx
+        .select({
+        principalId: memberships.principalId,
+        role: primaryRoleKey(binding),
+        grantedBy: memberships.grantedBy,
+        createdAt: memberships.createdAt,
+    })
+        .from(memberships)
+        .where(and(eq(memberships.tenantId, childId), eq(memberships.source, 'direct'), isNotNull(memberships.grantedBy), inArray(memberships.grantedBy, granters), 
+    // `gte`, not a raw `sql` template: a template tag carries no column
+    // type for the value it interpolates, so postgres-js cannot encode a
+    // Date and throws on every detach that has a derived holder to report,
+    // which is every real one. Found by the agent that had to call this.
+    gte(memberships.createdAt, since)))
+        .orderBy(asc(memberships.createdAt));
+    return rows;
+}

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+import type { ActorClass, Context, ResourceAccess, TenantKind, TenantState } from '@wtfalch/authz';
+/** Re-exported so the modules in this directory name one `Context`, the package's. */
+export type { Context } from '@wtfalch/authz';
+import type { StoreBinding } from './binding.js';
+import type { ScopedDb } from './scoped.js';
+/**
+ * Who is acting. A person signed in through the issuer, or a credential (an
+ * API key, an agent, a service) presenting its secret; both hold memberships
+ * with a role and are told apart by `class` alone. `id` is the issuer's
+ * subject id for a person and the credential id for the rest; `display` is
+ * what an audit row and a members list show.
+ */
+export interface Principal {
+    readonly class: ActorClass;
+    readonly id: string;
+    readonly display: string;
+    readonly email: string | null;
+    readonly emailVerified: boolean;
+}
+/** The tenant row as every check reads it. `ceiling` and `selfDenied` are what a host's ceiling gate reads. */
+export interface TenantRow {
+    readonly id: string;
+    readonly kind: TenantKind;
+    readonly slug: string;
+    readonly name: string;
+    readonly state: TenantState;
+    readonly parentId: string | null;
+    readonly ceiling: readonly string[];
+    readonly selfDenied: readonly string[];
+    /** Only the single `kind: 'operator'` row may ever be true. */
+    readonly frozen: boolean;
+}
+/**
+ * What one membership read resolved to, for one principal in one tenant, for
+ * one request. Built only by `loadAccess`; no other code constructs one, so
+ * holding an `Access` means the membership (or a break-glass session) was
+ * read this request.
+ *
+ * `authority` is the sole scoped evaluator for this request. `binding` is the
+ * `StoreBinding` `loadAccess` was called with, carried along so a later call
+ * that only has the `Access` (`permits`, `permitsPlatform`, `policyTarget`,
+ * `explain`) does not need it passed again.
+ * `readOnly` is true whenever the handle must refuse writes: a tenant that is
+ * `read_only` or `suspended`, or a read-only support session; `db` enforces it
+ * at the query-builder layer regardless of what the call site checked.
+ */
+export interface Access {
+    readonly actor: Principal;
+    readonly tenant: TenantRow;
+    /** Display key of the primary assignment, or empty for participation without that assignment. */
+    readonly role: string;
+    readonly authority: ResourceAccess;
+    readonly policyState: import('./policy-access.js').PolicyState;
+    readonly context: Context;
+    readonly breakGlass: BreakGlassGrant | null;
+    readonly readOnly: boolean;
+    readonly db: ScopedDb;
+    readonly binding: StoreBinding;
+}
+/** The session an operator is acting under, when `context` is `break_glass`. */
+export interface BreakGlassGrant {
+    readonly id: string;
+    readonly expiresAt: Date;
+    readonly readOnly: boolean;
+    readonly reason: string;
+    readonly reference: string;
+}
+/**
+ * What an authority write returns. Refusals are words, not throws: a host
+ * hands `message` to the page and `reason` to a test. `tags` are the cache
+ * tags the caller invalidates.
+ */
+export type Result<T = void> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly tags: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly message: string;
+};
+export declare function refused(reason: string, message: string): Result<never>;
+export declare function done<T>(value: T, tags: readonly string[]): Result<T>;
+/** The tag every authority change in a tenant invalidates. */
+export declare function tenantTag(tenantId: string): string;
+/** Whether a string looks like a uuid, checked before it ever reaches a query: a malformed tenant id from a URL is a lookup miss, not a database error. */
+export declare function isUuid(value: string): boolean;

package/dist/types.js

@@ -0,0 +1,15 @@
+export function refused(reason, message) {
+    return { ok: false, reason, message };
+}
+export function done(value, tags) {
+    return { ok: true, value, tags };
+}
+/** The tag every authority change in a tenant invalidates. */
+export function tenantTag(tenantId) {
+    return `authz:${tenantId}`;
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Whether a string looks like a uuid, checked before it ever reaches a query: a malformed tenant id from a URL is a lookup miss, not a database error. */
+export function isUuid(value) {
+    return UUID_PATTERN.test(value);
+}

package/migrations/0003_product_tenant_kind.sql

@@ -0,0 +1,14 @@
+-- `tenants.kind` gains 'product': a tenant of its own kind whose children are
+-- customer tenants, and which is never itself a child. See
+-- https://github.com/wtfalch/authz/issues/72.
+ALTER TABLE "tenants" DROP CONSTRAINT "tenants_kind_check";
+--> statement-breakpoint
+ALTER TABLE "tenants" ADD CONSTRAINT "tenants_kind_check"
+  CHECK (("kind" = ANY (ARRAY['customer'::text, 'operator'::text, 'product'::text])));
+--> statement-breakpoint
+-- A product is never a child, the same shape as tenants_operator_no_parent_check.
+-- Between this and that existing check, a non-null parent_id now implies
+-- kind = 'customer', which is what makes a product's children customer
+-- tenants: no third rule is needed to say so.
+ALTER TABLE "tenants" ADD CONSTRAINT "tenants_product_no_parent_check"
+  CHECK ((("kind" <> 'product'::text) OR ("parent_id" IS NULL)));