@wtfalch/authz-store 0.2.1 → 0.4.0

package/dist/nesting.js

@@ -0,0 +1,515 @@
+import { auditRowLimits } from '@wtfalch/authz';
+import { sqlState } from '@wtfalch/db';
+import { and, desc, eq, inArray } from 'drizzle-orm';
+import { record } from './audit.js';
+import { permits, permitsRead, refreshAccess } from './policy-access.js';
+import { attachProposals, memberships, tenants } from './schema.js';
+import { attachInTx, detachInTx } from './tree-writes.js';
+import { attachCustomRoleBlockers, attachProblem, descendantsOf, detachReport, lockAttachScope, lockSubtreeForUpdate, lockTenantsForUpdate, nodeById, } from './tree.js';
+import { done, refused, tenantTag } from './types.js';
+/** Exported for a page's reason picker, so the closed set is declared once. */
+export const ATTACH_REASONS = [
+    'reseller',
+    'reorganisation',
+    'onboarding',
+    'other',
+];
+function isAttachReason(value) {
+    return ATTACH_REASONS.includes(value);
+}
+const REFERENCE_MIN = 1;
+const REFERENCE_MAX = 512;
+/** SQLSTATE may be on the driver error or a native ORM cause; 23505 is unique_violation. */
+function isUniqueViolation(error) {
+    return sqlState(error) === '23505';
+}
+/** `DerivedChange.kind` turned into the audit action it is written as. */
+function derivedChangeAction(kind) {
+    switch (kind) {
+        case 'created':
+            return 'membership.created';
+        case 'role_changed':
+            return 'membership.role_changed';
+        case 'ended':
+            return 'membership.ended';
+    }
+}
+/** One audit row per `DerivedChange`, the shape both `acceptAttach` and `detach` need. */
+async function recordDerivedChanges(tx, access, changes) {
+    for (const change of changes) {
+        await record(tx, access, {
+            action: derivedChangeAction(change.kind),
+            tenantId: change.tenantId,
+            targetType: 'membership',
+            targetId: change.principalId,
+            before: change.before,
+            after: change.after,
+        });
+    }
+}
+function customRoleBlockersMessage(blockers) {
+    const offenders = blockers.map((b) => `${b.principalId} in ${b.tenantId} (role "${b.role}", via ${b.viaTenantId})`);
+    return `Accepting would hand down a custom role, which this app never propagates: ${offenders.join('; ')}. Move them to a system role at the parent first, or narrow the child's own tree.`;
+}
+function jsonSafeReport(rows) {
+    return rows.map((row) => ({ ...row, createdAt: row.createdAt.toISOString() }));
+}
+/** Fits the detach report inside the audit row's 64 KB JSON limit, dropping rows from the end rather than failing the write. `record()`'s own validation uses the same limit, so this mirrors it rather than guessing a number. */
+function detachReportForAudit(report) {
+    let kept = report;
+    while (kept.length > 0 &&
+        JSON.stringify({ grantedByDerivedHolders: jsonSafeReport(kept) }).length >
+            auditRowLimits.jsonBytes) {
+        kept = kept.slice(0, Math.ceil(kept.length / 2));
+    }
+    if (kept.length === report.length)
+        return { grantedByDerivedHolders: jsonSafeReport(report) };
+    return { grantedByDerivedHolders: jsonSafeReport(kept), truncated: true };
+}
+/**
+ * Proposes that `access.tenant` (or, for an operator, `options.parentId`)
+ * hold `options.childId`. Two refusals beyond the ordinary ones apply only to
+ * an operator actor (M5): an operator's own tenant can never be the parent,
+ * caught by `attachProblem` the same as any other pairing; and an operator
+ * who personally holds a direct role at the proposed parent may not propose
+ * it, because accepting would hand that same operator a standing derived
+ * role in the child the moment it goes through, exactly the reach into
+ * membership D8 forbids operators otherwise.
+ */
+export async function proposeAttach(access, db, scopeColumn, policy, options) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never proposes attaching an organisation.');
+    }
+    if (!permits(access, 'tenants:attach')) {
+        return refused('no_permission', 'You do not have permission to propose attaching an organisation.');
+    }
+    if (!isAttachReason(options.reason)) {
+        return refused('invalid_reason', `"${options.reason}" is not a reason a proposal can carry.`);
+    }
+    const reference = options.reference.trim();
+    if (reference.length < REFERENCE_MIN || reference.length > REFERENCE_MAX) {
+        return refused('invalid_reference', `Give a reference between ${REFERENCE_MIN} and ${REFERENCE_MAX} characters.`);
+    }
+    const isOperatorActor = access.tenant.kind === 'operator';
+    const parentId = isOperatorActor ? options.parentId : access.tenant.id;
+    if (!parentId) {
+        return refused('parent_required', 'Say which organisation is proposed as the parent.');
+    }
+    const childId = options.childId;
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'tenants:attach'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        await lockAttachScope(tx, parentId, childId);
+        // attachProblem first: an operator naming their own tenant as the
+        // parent is refused as 'operator_tenant' (an impossible pairing) rather
+        // than 'operator_holds_role_at_parent', which is reserved for a parent
+        // the operator does not belong to by virtue of being the operator.
+        const problem = await attachProblem(tx, policy, parentId, childId);
+        if (problem)
+            return refused(problem.reason, problem.message);
+        if (isOperatorActor) {
+            const [operatorDirect] = await tx
+                .select({ principalId: memberships.principalId })
+                .from(memberships)
+                .where(and(eq(memberships.tenantId, parentId), eq(memberships.principalId, currentAccess.actor.id), eq(memberships.principalClass, currentAccess.actor.class), eq(memberships.source, 'direct')))
+                .limit(1);
+            if (operatorDirect) {
+                return refused('operator_holds_role_at_parent', 'An operator who holds a direct role at the proposed parent cannot propose attaching under it: accepting would hand them a standing role in the child too.');
+            }
+        }
+        const [existingPending] = await tx
+            .select({ id: attachProposals.id })
+            .from(attachProposals)
+            .where(and(eq(attachProposals.parentId, parentId), eq(attachProposals.childId, childId), inArray(attachProposals.status, ['pending_parent', 'pending'])))
+            .limit(1);
+        if (existingPending) {
+            return refused('already_proposed', 'A proposal for this pair is already pending.');
+        }
+        let proposalId;
+        try {
+            const [row] = await tx
+                .insert(attachProposals)
+                .values({
+                parentId,
+                childId,
+                // An operator's is a draft until the proposed parent takes it on;
+                // a parent proposing for itself has consented by asking.
+                status: isOperatorActor ? 'pending_parent' : 'pending',
+                reason: options.reason,
+                reference,
+                proposedBy: currentAccess.actor.id,
+            })
+                .returning({ id: attachProposals.id });
+            if (!row)
+                throw new Error('proposeAttach: no row returned from the insert');
+            proposalId = row.id;
+        }
+        catch (error) {
+            if (isUniqueViolation(error)) {
+                return refused('already_proposed', 'A proposal for this pair is already pending.');
+            }
+            throw error;
+        }
+        await record(tx, currentAccess, {
+            action: 'tenant.attach_proposed',
+            tenantId: childId,
+            targetType: 'proposal',
+            targetId: proposalId,
+            reason: options.reason,
+            reference,
+            after: { parentId },
+        });
+        return done({ id: proposalId }, [tenantTag(parentId), tenantTag(childId)]);
+    });
+}
+/**
+ * Accepts a pending proposal. `access` must already be resolved against the
+ * child (the child's own owner is who may accept), so a proposal for a
+ * different tenant is refused as `wrong_tenant` rather than acted on.
+ * Re-runs `attachProblem` inside the lock, because the ceiling, the depth or
+ * the parentage can all have moved since the proposal was written, and this
+ * second run is the one that actually decides. `customRoleBlockers` runs
+ * against the ancestry the attach would create, which only exists once the
+ * parent link is written, so that write happens here (not through
+ * `attachInTx`, which would also recompute in the same step) and is undone by
+ * throwing out of the transaction if a blocker turns up, rather than by
+ * `recomputeDerived` itself refusing partway through the subtree (D19: no
+ * partial propagation).
+ */
+export async function acceptAttach(access, db, scopeColumn, policy, proposalId) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never accepts a proposal.');
+    }
+    if (!permits(access, 'tenants:attach')) {
+        return refused('no_permission', 'You do not have permission to decide this proposal.');
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'tenants:attach'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        const [peek] = await tx
+            .select({ parentId: attachProposals.parentId, childId: attachProposals.childId })
+            .from(attachProposals)
+            .where(eq(attachProposals.id, proposalId))
+            .limit(1);
+        if (!peek)
+            return refused('proposal_not_found', 'This proposal no longer exists.');
+        // Which side is answering. A proposal an operator drafted is put to the
+        // parent first, and only becomes the child's to decide once the parent
+        // has taken it on.
+        const side = peek.childId === currentAccess.tenant.id
+            ? 'child'
+            : peek.parentId === currentAccess.tenant.id
+                ? 'parent'
+                : null;
+        if (!side)
+            return refused('wrong_tenant', 'This proposal is not for this organisation.');
+        await lockAttachScope(tx, peek.parentId, peek.childId);
+        const [proposal] = await tx
+            .select()
+            .from(attachProposals)
+            .where(eq(attachProposals.id, proposalId))
+            .for('update');
+        if (!proposal)
+            return refused('proposal_not_found', 'This proposal no longer exists.');
+        if (proposal.status !== 'pending' && proposal.status !== 'pending_parent') {
+            return refused('not_pending', 'This proposal is no longer pending.');
+        }
+        if (proposal.status === 'pending_parent' && side !== 'parent') {
+            return refused('awaiting_parent', 'The organisation proposed to hold this one has not accepted yet.');
+        }
+        if (proposal.status === 'pending' && side !== 'child') {
+            return refused('awaiting_child', 'This proposal is waiting on the other organisation.');
+        }
+        // The parent's half of an operator's draft. Accepting means this
+        // organisation's own members gain authority inside the child, which is
+        // why it is asked at all rather than assumed from the console. It does
+        // not attach anything yet: the child still has to agree.
+        if (side === 'parent') {
+            const early = await attachProblem(tx, policy, proposal.parentId, proposal.childId);
+            if (early)
+                return refused(early.reason, early.message);
+            await tx
+                .update(attachProposals)
+                .set({
+                status: 'pending',
+                parentAcceptedBy: currentAccess.actor.id,
+                parentAcceptedAt: new Date(),
+            })
+                .where(eq(attachProposals.id, proposal.id));
+            // Written now, as the parent, because from here the proposal is the
+            // parent's own: an operator drafted it, this organisation is making it.
+            await record(tx, currentAccess, {
+                action: 'tenant.attach_proposed',
+                tenantId: proposal.childId,
+                targetType: 'proposal',
+                targetId: proposal.id,
+                reason: proposal.reason,
+                reference: proposal.reference,
+                after: { parentId: proposal.parentId },
+            });
+            return done(undefined, [tenantTag(proposal.parentId), tenantTag(proposal.childId)]);
+        }
+        const problem = await attachProblem(tx, policy, proposal.parentId, proposal.childId);
+        if (problem)
+            return refused(problem.reason, problem.message);
+        // Asked about the chain the attachment WOULD create, before anything is
+        // written: the ordinary customRoleBlockers reads the ancestry the child
+        // has now, which is none, and would always answer "nothing" here.
+        const blockers = await attachCustomRoleBlockers(tx, currentAccess.binding, proposal.parentId, proposal.childId);
+        if (blockers.length > 0) {
+            return refused('custom_role_at_parent', customRoleBlockersMessage(blockers));
+        }
+        const subtree = [
+            proposal.childId,
+            ...(await descendantsOf(tx, proposal.childId)).map((node) => node.id),
+        ];
+        const changes = await attachInTx(tx, currentAccess.binding, proposal.parentId, proposal.childId);
+        await tx
+            .update(attachProposals)
+            .set({ status: 'accepted', decidedBy: currentAccess.actor.id, decidedAt: new Date() })
+            .where(eq(attachProposals.id, proposal.id));
+        await record(tx, currentAccess, {
+            action: 'tenant.parent_attached',
+            tenantId: proposal.childId,
+            targetType: 'tenant',
+            targetId: proposal.parentId,
+            reason: proposal.reason,
+            reference: proposal.reference,
+            after: { parentId: proposal.parentId },
+        });
+        await recordDerivedChanges(tx, currentAccess, changes);
+        return done(undefined, [tenantTag(proposal.parentId), ...subtree.map(tenantTag)]);
+    });
+}
+/** Declines a pending proposal. Same authority as `acceptAttach`; nothing is written to either tenant. */
+export async function declineAttach(access, db, scopeColumn, proposalId) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never declines a proposal.');
+    }
+    if (!permits(access, 'tenants:attach')) {
+        return refused('no_permission', 'You do not have permission to decide this proposal.');
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'tenants:attach'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        const [peek] = await tx
+            .select({ parentId: attachProposals.parentId, childId: attachProposals.childId })
+            .from(attachProposals)
+            .where(eq(attachProposals.id, proposalId))
+            .limit(1);
+        if (!peek)
+            return refused('proposal_not_found', 'This proposal no longer exists.');
+        const side = peek.childId === currentAccess.tenant.id
+            ? 'child'
+            : peek.parentId === currentAccess.tenant.id
+                ? 'parent'
+                : null;
+        if (!side)
+            return refused('wrong_tenant', 'This proposal is not for this organisation.');
+        await lockTenantsForUpdate(tx, [peek.parentId, peek.childId]);
+        const [proposal] = await tx
+            .select()
+            .from(attachProposals)
+            .where(eq(attachProposals.id, proposalId))
+            .for('update');
+        if (!proposal)
+            return refused('proposal_not_found', 'This proposal no longer exists.');
+        if (proposal.status !== 'pending' && proposal.status !== 'pending_parent') {
+            return refused('not_pending', 'This proposal is no longer pending.');
+        }
+        // Whichever side is being asked may say no, and that ends it: a parent
+        // declining an operator's draft means the child is never troubled with
+        // it, and a child declining ends a proposal its parent already took on.
+        const asked = proposal.status === 'pending_parent' ? 'parent' : 'child';
+        if (side !== asked) {
+            return refused('not_asked', 'This proposal is not waiting on this organisation.');
+        }
+        await tx
+            .update(attachProposals)
+            .set({ status: 'declined', decidedBy: currentAccess.actor.id, decidedAt: new Date() })
+            .where(eq(attachProposals.id, proposal.id));
+        await record(tx, currentAccess, {
+            action: 'tenant.attach_declined',
+            tenantId: proposal.childId,
+            targetType: 'proposal',
+            targetId: proposal.id,
+            reason: proposal.reason,
+            reference: proposal.reference,
+        });
+        return done(undefined, [tenantTag(proposal.parentId), tenantTag(proposal.childId)]);
+    });
+}
+/** When the current attachment between this exact parent and child began: the accepted proposal's `decided_at`, or the child's own `created_at` when it was born attached and no proposal exists (D10). */
+async function attachedSince(tx, parentId, childId) {
+    const [proposal] = await tx
+        .select({ decidedAt: attachProposals.decidedAt })
+        .from(attachProposals)
+        .where(and(eq(attachProposals.parentId, parentId), eq(attachProposals.childId, childId), eq(attachProposals.status, 'accepted')))
+        .orderBy(desc(attachProposals.decidedAt))
+        .limit(1);
+    if (proposal?.decidedAt)
+        return proposal.decidedAt;
+    const [child] = await tx
+        .select({ createdAt: tenants.createdAt })
+        .from(tenants)
+        .where(eq(tenants.id, childId))
+        .limit(1);
+    if (!child)
+        throw new Error(`attachedSince: tenant ${childId} no longer exists`);
+    return child.createdAt;
+}
+/**
+ * Detaches a child from its parent. Allowed to the child's own owner, to the
+ * parent (the child among its own children), or to an operator, all through
+ * `tenants:detach`. The report is read before `detachInTx`, on purpose: it
+ * asks who currently holds a derived row in the child, and detaching is
+ * exactly what takes those rows away, so reading it after would see nothing
+ * left to report.
+ */
+export async function detach(access, db, scopeColumn, options) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never detaches an organisation.');
+    }
+    if (!permits(access, 'tenants:detach')) {
+        return refused('no_permission', 'You do not have permission to detach an organisation.');
+    }
+    const childId = options.childId;
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'tenants:detach'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        const peek = await nodeById(tx, childId);
+        if (!peek)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        if (!peek.parentId)
+            return refused('not_attached', 'This organisation is not held by another one.');
+        // The whole subtree, because detachInTx recomputes every level of it, and
+        // the parent besides. Locking the two named rows only would let an attach
+        // under a descendant land unseen.
+        const locked = await lockSubtreeForUpdate(tx, childId);
+        for (const [id, node] of await lockTenantsForUpdate(tx, [peek.parentId])) {
+            locked.set(id, node);
+        }
+        const child = locked.get(childId);
+        if (!child)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        if (!child.parentId) {
+            return refused('not_attached', 'This organisation is not held by another one.');
+        }
+        if (child.parentId !== peek.parentId) {
+            // Raced with another attach or detach between the peek above and the
+            // lock: the safe answer is to ask the caller to look again, not to act
+            // on a parent id that is no longer current.
+            return refused('parent_changed', "This organisation's parent changed. Try again.");
+        }
+        const parentId = child.parentId;
+        const authorised = currentAccess.tenant.kind === 'operator' ||
+            currentAccess.tenant.id === childId ||
+            currentAccess.tenant.id === parentId;
+        if (!authorised) {
+            return refused('not_authorised', 'You may not detach this organisation.');
+        }
+        const subtree = [childId, ...(await descendantsOf(tx, childId)).map((node) => node.id)];
+        const since = await attachedSince(tx, parentId, childId);
+        const report = await detachReport(tx, currentAccess.binding, childId, since);
+        const changes = await detachInTx(tx, currentAccess.binding, childId);
+        await record(tx, currentAccess, {
+            action: 'tenant.parent_detached',
+            tenantId: childId,
+            targetType: 'tenant',
+            targetId: parentId,
+            before: { parentId },
+            after: detachReportForAudit(report),
+        });
+        await recordDerivedChanges(tx, currentAccess, changes);
+        return done({ grantedByDerivedHolders: report }, [
+            tenantTag(parentId),
+            ...subtree.map(tenantTag),
+        ]);
+    });
+}
+/** `tenants:attach` or `members:read`; every pending proposal to hold this organisation, for the page beside pending invitations. */
+export async function pendingProposalsForChild(access, db) {
+    if (!(await permitsRead(access, db, 'tenants:attach')) &&
+        !(await permitsRead(access, db, 'members:read'))) {
+        return [];
+    }
+    const rows = await db
+        .select({
+        id: attachProposals.id,
+        parentId: attachProposals.parentId,
+        parentName: tenants.name,
+        reason: attachProposals.reason,
+        reference: attachProposals.reference,
+        proposedBy: attachProposals.proposedBy,
+        createdAt: attachProposals.createdAt,
+    })
+        .from(attachProposals)
+        .innerJoin(tenants, eq(attachProposals.parentId, tenants.id))
+        .where(and(eq(attachProposals.childId, access.tenant.id), 
+    // 'pending' only: a proposal still waiting on the parent is not the
+    // child's to see, let alone decide.
+    eq(attachProposals.status, 'pending')))
+        .orderBy(desc(attachProposals.createdAt));
+    return rows.map((row) => ({ ...row, reason: row.reason }));
+}
+/**
+ * What an operator has proposed that this organisation hold, and nobody has
+ * agreed to yet. The parent answers these before the child ever sees them
+ * (M5): accepting hands this organisation's own members authority inside
+ * another one, which the console does not get to decide on its behalf.
+ */
+export async function pendingProposalsForParent(access, db) {
+    if (!(await permitsRead(access, db, 'tenants:attach')) &&
+        !(await permitsRead(access, db, 'members:read'))) {
+        return [];
+    }
+    const rows = await db
+        .select({
+        id: attachProposals.id,
+        childId: attachProposals.childId,
+        childName: tenants.name,
+        reason: attachProposals.reason,
+        reference: attachProposals.reference,
+        proposedBy: attachProposals.proposedBy,
+        createdAt: attachProposals.createdAt,
+    })
+        .from(attachProposals)
+        .innerJoin(tenants, eq(attachProposals.childId, tenants.id))
+        .where(and(eq(attachProposals.parentId, access.tenant.id), eq(attachProposals.status, 'pending_parent')))
+        .orderBy(desc(attachProposals.createdAt));
+    return rows.map((row) => ({ ...row, reason: row.reason }));
+}
+export async function proposalsFromParent(access, db) {
+    if (!(await permitsRead(access, db, 'tenants:attach')) &&
+        !(await permitsRead(access, db, 'members:read'))) {
+        return [];
+    }
+    const rows = await db
+        .select({
+        id: attachProposals.id,
+        childId: attachProposals.childId,
+        childName: tenants.name,
+        status: attachProposals.status,
+        reason: attachProposals.reason,
+        reference: attachProposals.reference,
+        createdAt: attachProposals.createdAt,
+        decidedAt: attachProposals.decidedAt,
+    })
+        .from(attachProposals)
+        .innerJoin(tenants, eq(attachProposals.childId, tenants.id))
+        .where(eq(attachProposals.parentId, access.tenant.id))
+        .orderBy(desc(attachProposals.createdAt));
+    return rows.map((row) => ({
+        ...row,
+        reason: row.reason,
+        status: row.status,
+    }));
+}