@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/invitations.js

@@ -0,0 +1,685 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { core } from '@wtfalch/authz';
+import { and, desc, eq, gt, sql } from 'drizzle-orm';
+import { alias } from 'drizzle-orm/pg-core';
+import { identityWhere, primaryAssignment, roleAssignmentRefusal, roleById, writeParticipationPolicy, writePrimaryAssignment, } from './assignments.js';
+import { record, recordAs } from './audit.js';
+import { ownerCoverage, ownerSeatCovered } from './owners.js';
+import { loadAccess, permits, permitsPlatform, permitsRead, policyRole, refreshAccess, } from './policy-access.js';
+import { propagateMembershipChange, writerFromPrincipal } from './propagate.js';
+import { roleDef } from './roles.js';
+import { authzEvents, invitations, memberships, tenants } from './schema.js';
+import { attachInTx } from './tree-writes.js';
+import { attachCustomRoleBlockers, attachProblem, derivedEventAction, lockAttachScope, } from './tree.js';
+import { done, refused, tenantTag } from './types.js';
+/** A second name for `tenants`, so a query can join a tenant row and its parent's in the same select without a column-name collision. */
+const parentTenants = alias(tenants, 'parent_tenants');
+/**
+ * The token every invitation row uses: 32 random bytes (the package's own
+ * `core.invitation.tokenBytes`), hex-encoded for the link the mail carries,
+ * with its sha256 hex stored on the row. Exported so a host's own
+ * `createTenantAsOperator` builds its own pending invitation with exactly
+ * the same rule, rather than a second copy of it.
+ */
+export function generateInvitationToken() {
+    const token = randomBytes(core.invitation.tokenBytes).toString('hex');
+    const tokenHash = createHash('sha256').update(token).digest('hex');
+    const expiresAt = new Date(Date.now() + core.invitation.ttlDays * 24 * 60 * 60 * 1000);
+    return { token, tokenHash, expiresAt };
+}
+const invitationRoleKey = sql `(select key from authz_roles where id=${invitations.roleId} and tenant_id=${invitations.tenantId})`;
+const refusalMessage = () => 'You cannot delegate or remove that role with your current authority.';
+const grantRefusalMessage = (_reason) => refusalMessage();
+const removeRefusalMessage = (_reason) => refusalMessage();
+/** `roleById`, resolved to a `ResourceRole`, or `null`. `binding` is a parameter here (not read from an `Access`) so `acceptInvitation` (wave 8b) can call this before it has one. */
+async function roleForInvitation(tx, binding, tenantId, id) {
+    const row = await roleById(tx, binding, tenantId, id);
+    return row ? policyRole(row) : null;
+}
+async function recentSendCount(tx, tenantId) {
+    const [row] = await tx
+        .select({ count: sql `count(*)::int` })
+        .from(authzEvents)
+        .where(and(eq(authzEvents.tenantId, tenantId), eq(authzEvents.action, 'invitation.sent'), eq(authzEvents.outcome, 'success'), gt(authzEvents.occurredAt, sql `now() - interval '1 hour'`)));
+    return row?.count ?? 0;
+}
+/**
+ * Sends an invitation, or re-sends one: a pending row already sitting on
+ * `(tenant, email)` has its token and expiry rotated in place rather than a
+ * second row being created, which is also what the unique index on that
+ * pair enforces. The role on a rotated row is replaced by whatever this call
+ * asked for, since that is the role the grant check below just verified;
+ * leaving the old role in place would store something nobody re-checked.
+ *
+ * There is no check here for "this email already belongs to a member":
+ * a membership carries a principal id and a class, never an email (the
+ * import rule scans for exactly that), so there is no predicate to write.
+ * An address that already has an account simply accepts and finds it is
+ * already a member (see `acceptInvitation`, wave 8b).
+ */
+export async function invite(access, db, scopeColumn, options) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never invites anyone.');
+    }
+    const email = options.email.trim().toLowerCase();
+    if (email.length > 254 || !/^\S+@\S+\.\S+$/.test(email))
+        return refused('invalid_email', 'Enter a valid email address.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass')
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        const tenant = fresh.tenant;
+        const targetRole = await roleDef(tx, currentAccess.binding, tenant, options.role);
+        if (!targetRole) {
+            return refused('unknown_role', `"${options.role}" is not a role this organisation has.`);
+        }
+        const grantRefusal = roleAssignmentRefusal(currentAccess, targetRole, primaryAssignment(targetRole, { id: 'invited-person', class: 'human' }), 'members:grant');
+        if (grantRefusal)
+            return refused(grantRefusal, grantRefusalMessage(grantRefusal));
+        const sentThisHour = await recentSendCount(tx, tenant.id);
+        if (sentThisHour >= options.capPerHour) {
+            await record(tx, currentAccess, {
+                action: 'invitation.sent',
+                tenantId: tenant.id,
+                targetType: 'invitation',
+                // Truncated: the audit row's target_id CHECK caps it at 256
+                // characters, and an email is caller-supplied text with no length
+                // limit of its own, so a long one must not turn a graceful refusal
+                // into a failed insert.
+                targetId: email.slice(0, 256),
+                outcome: 'denied',
+                reason: `more than ${options.capPerHour} invitations sent from this organisation in the last hour`,
+            });
+            return refused('cap_reached', `This organisation can only send ${options.capPerHour} invitations an hour.`);
+        }
+        const [existingPending] = await tx
+            .select({ id: invitations.id, roleId: invitations.roleId, expiresAt: invitations.expiresAt })
+            .from(invitations)
+            .where(and(eq(invitations.tenantId, tenant.id), eq(invitations.email, email), eq(invitations.status, 'pending')))
+            .limit(1);
+        if (existingPending && existingPending.roleId !== targetRole.id) {
+            const previous = await roleForInvitation(tx, currentAccess.binding, tenant.id, existingPending.roleId);
+            if (!previous ||
+                roleAssignmentRefusal(currentAccess, previous, primaryAssignment(previous, { id: 'invited-person', class: 'human' }), 'members:revoke'))
+                return refused('guarded', 'You cannot replace this invitation’s role.');
+            // Not `.builtIn`: a starter owner role (ADR 0016) is `built_in: false`
+            // for a tenant created after that change, but only the app's own owner
+            // role can ever hold the literal key `owner` (custom keys start with
+            // `c_`), so the key alone still tells a real owner change from a
+            // lateral one between two non-owner roles.
+            if (previous.key === 'owner' && targetRole.key !== 'owner') {
+                const coverage = await ownerCoverage(tx, currentAccess.binding, tenant.id);
+                if (!ownerSeatCovered({
+                    ...coverage,
+                    pendingOwnerInvitations: coverage.pendingOwnerInvitations -
+                        (existingPending.expiresAt.getTime() > Date.now() ? 1 : 0),
+                }))
+                    return refused('last_owner', 'This invitation is the organisation’s only recovery owner.');
+            }
+        }
+        const { token, tokenHash, expiresAt } = generateInvitationToken();
+        let invitationId;
+        if (existingPending) {
+            invitationId = existingPending.id;
+            await tx
+                .update(invitations)
+                // mail_state and its clock reset with the token. A resend is a fresh
+                // attempt, and leaving the old 'failed' behind meant the stuck-mail
+                // alert went on firing about a row somebody had just fixed, with a
+                // timestamp older than the remediation.
+                .set({
+                roleId: targetRole.id,
+                tokenHash,
+                expiresAt,
+                invitedBy: currentAccess.actor.id,
+                invitedByClass: currentAccess.actor.class,
+                mailState: 'pending',
+                mailStateAt: null,
+            })
+                .where(eq(invitations.id, existingPending.id));
+        }
+        else {
+            const [row] = await tx
+                .insert(invitations)
+                .values({
+                tenantId: tenant.id,
+                email,
+                roleId: targetRole.id,
+                tokenHash,
+                expiresAt,
+                invitedBy: currentAccess.actor.id,
+                invitedByClass: currentAccess.actor.class,
+            })
+                .returning({ id: invitations.id });
+            if (!row)
+                throw new Error('invite: no row returned from the insert');
+            invitationId = row.id;
+        }
+        await record(tx, currentAccess, {
+            action: 'invitation.sent',
+            tenantId: tenant.id,
+            targetType: 'invitation',
+            targetId: invitationId,
+            after: { email, role: options.role },
+        });
+        return done({ id: invitationId, token, link: options.link(token), email }, [
+            tenantTag(tenant.id),
+        ]);
+    });
+}
+/** `members:grant`; sets whether the mail for one invitation went out. Never audited: this is delivery bookkeeping, not an authorisation event. */
+export async function markInvitationMail(access, db, invitationId, state) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never manages invitations.');
+    }
+    if (!permits(access, 'members:grant')) {
+        return refused('no_permission', 'You do not have permission to manage invitations here.');
+    }
+    const [row] = await db
+        .update(invitations)
+        .set({ mailState: state, mailStateAt: new Date() })
+        .where(and(eq(invitations.id, invitationId), eq(invitations.tenantId, access.tenant.id)))
+        .returning({ id: invitations.id });
+    if (!row)
+        return refused('invitation_not_found', 'This invitation no longer exists.');
+    return done(undefined, [tenantTag(access.tenant.id)]);
+}
+/**
+ * A re-invite: reads the row's current email and role and sends through the
+ * same path `invite` uses, which is what rotates its token and expiry.
+ * Gated on `members:grant` before the row is even read, the same as
+ * `markInvitationMail`: without that, a member who cannot see invitations at
+ * all could still learn that a given invitation id exists here, and whether
+ * it is still pending, just from which refusal comes back.
+ */
+export async function resendInvitation(access, db, scopeColumn, invitationId, options) {
+    if (!permits(access, 'members:grant')) {
+        return refused('no_permission', 'You do not have permission to manage invitations here.');
+    }
+    const [row] = await db
+        .select({ email: invitations.email, role: invitationRoleKey, status: invitations.status })
+        .from(invitations)
+        .where(and(eq(invitations.id, invitationId), eq(invitations.tenantId, access.tenant.id)))
+        .limit(1);
+    if (!row)
+        return refused('invitation_not_found', 'This invitation no longer exists.');
+    if (row.status !== 'pending') {
+        return refused('not_pending', 'This invitation is no longer pending, so it cannot be resent.');
+    }
+    return invite(access, db, scopeColumn, {
+        email: row.email,
+        role: row.role,
+        capPerHour: options.capPerHour,
+        link: options.link,
+    });
+}
+/**
+ * Withdraws a pending invitation. Guarded the same way removing a member is:
+ * `members:revoke` and the guard-permission test on the role being taken
+ * away, and, for an owner invitation specifically, the same coverage rule
+ * a host's own membership removal enforces for a membership row: revoking it
+ * must not leave the tenant with no owner and no other pending owner
+ * invitation.
+ */
+export async function revokeInvitation(access, db, scopeColumn, invitationId) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never revokes an invitation.');
+    }
+    // Checked before any row is read, the same as markInvitationMail and
+    // resendInvitation: without this, a member holding no members:revoke at
+    // all could still learn that an invitation id exists and whether it is
+    // pending, from which refusal comes back below.
+    if (!permits(access, 'members:revoke')) {
+        return refused('no_revoke_permission', removeRefusalMessage('no_revoke_permission'));
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass')
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        const tenant = fresh.tenant;
+        const [row] = await tx
+            .select({
+            id: invitations.id,
+            roleId: invitations.roleId,
+            status: invitations.status,
+            expiresAt: invitations.expiresAt,
+        })
+            .from(invitations)
+            .where(and(eq(invitations.id, invitationId), eq(invitations.tenantId, tenant.id)))
+            .for('update');
+        if (!row)
+            return refused('invitation_not_found', 'This invitation no longer exists.');
+        if (row.status !== 'pending') {
+            return refused('not_pending', 'This invitation is no longer pending.');
+        }
+        const invitedRole = await roleForInvitation(tx, currentAccess.binding, tenant.id, row.roleId);
+        if (!invitedRole) {
+            return refused('unknown_role', 'The invited role no longer exists in this organisation.');
+        }
+        const removeRefusal = roleAssignmentRefusal(currentAccess, invitedRole, primaryAssignment(invitedRole, { id: 'invited-person', class: 'human' }), 'members:revoke');
+        if (removeRefusal)
+            return refused(removeRefusal, removeRefusalMessage(removeRefusal));
+        // Not `.builtIn`: see the same note above `roleAssignmentRefusal`'s
+        // `previous.key === 'owner'` check further up this file.
+        if (invitedRole.key === 'owner') {
+            // This row is only still part of the current coverage count while it
+            // is both pending and unexpired, which is exactly what `ownerCoverage`
+            // itself counts; subtracting one only makes sense when it was counted.
+            const coverage = await ownerCoverage(tx, currentAccess.binding, tenant.id);
+            const stillCounted = row.expiresAt.getTime() > Date.now();
+            const remainingPending = stillCounted
+                ? Math.max(0, coverage.pendingOwnerInvitations - 1)
+                : coverage.pendingOwnerInvitations;
+            const wouldBeCovered = ownerSeatCovered({
+                directOwners: coverage.directOwners,
+                pendingOwnerInvitations: remainingPending,
+            });
+            if (!wouldBeCovered) {
+                return refused('owner_seat_uncovered', 'Revoking this invitation would leave the organisation with no owner and no other pending owner invitation.');
+            }
+        }
+        await tx
+            .update(invitations)
+            .set({ status: 'revoked', revokedBy: currentAccess.actor.id, revokedAt: new Date() })
+            .where(eq(invitations.id, row.id));
+        await record(tx, currentAccess, {
+            action: 'invitation.revoked',
+            tenantId: tenant.id,
+            targetType: 'invitation',
+            targetId: row.id,
+        });
+        return done(undefined, [tenantTag(tenant.id)]);
+    });
+}
+/**
+ * Whether the operator who invited a tenant's first owner still could: a
+ * current membership in the operator tenant whose role resolves to
+ * `tenants:create`, and a target tenant that still has no direct owner.
+ */
+async function operatorMayStillOnboard(tx, binding, db, scopeColumn, operatorId, tenantId) {
+    const [operatorTenant] = await tx
+        .select({
+        id: tenants.id,
+        ceiling: tenants.ceiling,
+        selfDenied: tenants.selfDenied,
+        state: tenants.state,
+    })
+        .from(tenants)
+        .where(eq(tenants.kind, 'operator'))
+        .limit(1);
+    if (!operatorTenant)
+        return false;
+    const actor = await loadAccess(tx, binding, db, scopeColumn, { id: operatorId, class: 'human', display: operatorId, email: null, emailVerified: false }, operatorTenant.id, false);
+    if (!actor || !permitsPlatform(actor, 'tenants:create'))
+        return false;
+    const coverage = await ownerCoverage(tx, binding, tenantId);
+    return coverage.directOwners === 0;
+}
+/**
+ * Thrown only inside `attemptBornAttach`'s own nested transaction, to unwind
+ * it on an ordinary refusal without touching anything the enclosing
+ * transaction already wrote. Caught immediately outside the nested
+ * transaction and turned back into a worded `AttachRefusal`; never reaches
+ * `acceptInvitation`'s own caller as a throw.
+ */
+class AttachAttemptRefused extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'AttachAttemptRefused';
+    }
+}
+/**
+ * The attachment half of a born-attached invitation (D10, D19, M5), run in
+ * its own nested transaction, a Postgres savepoint, so a refusal here rolls
+ * back only this attempt and never the owner membership `acceptInvitation`
+ * already wrote in the enclosing transaction. Getting this backwards, by
+ * letting a refusal here abort the whole acceptance, would lock a customer
+ * out of the organisation they were just given, over something only the
+ * parent side controls (its ceiling narrowing, or a custom role appearing at
+ * it) between the tenant's creation and this moment.
+ *
+ * Runs the same two checks `nesting.ts`'s `acceptAttach` runs before writing
+ * (`attachProblem`, then `attachCustomRoleBlockers` over the pairing the
+ * attach would create, D19's rule that a derived row never carries a custom
+ * role), then `attachInTx`, `tree-writes.ts`'s only writer of the attachment
+ * and the rows it fills; nothing here is a second implementation of what
+ * that file already decides. `policy` is `attachProblem`'s own parameter
+ * (wave 4a); `binding` is threaded to every tree function that needs it.
+ * Returns the refusal, or null once attached, for the caller to fold into
+ * the result and the audit trail.
+ */
+async function attemptBornAttach(tx, binding, policy, principal, context, parentId, childId) {
+    try {
+        return await tx.transaction(async (attachTx) => {
+            await lockAttachScope(attachTx, parentId, childId);
+            const problem = await attachProblem(attachTx, policy, parentId, childId);
+            if (problem)
+                throw new AttachAttemptRefused(problem.reason, problem.message);
+            const blockers = await attachCustomRoleBlockers(attachTx, binding, parentId, childId);
+            if (blockers.length > 0) {
+                const offenders = [...new Set(blockers.map((blocker) => blocker.role))];
+                throw new AttachAttemptRefused('custom_role_at_parent', `Cannot attach yet: a custom role there would have to reach this organisation, which a derived membership can never carry (${offenders.join(', ')}). Move whoever holds it to a system role first.`);
+            }
+            const changes = await attachInTx(attachTx, binding, parentId, childId);
+            for (const change of changes) {
+                await recordAs(attachTx, principal, context, {
+                    action: derivedEventAction(change.kind),
+                    tenantId: change.tenantId,
+                    targetType: 'membership',
+                    targetId: change.principalId,
+                    before: change.before
+                        ? { role: change.before.role, viaTenantId: change.before.viaTenantId }
+                        : undefined,
+                    after: change.after
+                        ? { role: change.after.role, viaTenantId: change.after.viaTenantId }
+                        : undefined,
+                });
+            }
+            await recordAs(attachTx, principal, context, {
+                action: 'tenant.parent_attached',
+                tenantId: childId,
+                targetType: 'tenant',
+                targetId: childId,
+            });
+            return null;
+        });
+    }
+    catch (error) {
+        if (error instanceof AttachAttemptRefused) {
+            return { reason: error.reason, message: error.message };
+        }
+        throw error;
+    }
+}
+/**
+ * Accepts an invitation. There is no `Access` yet: the person is not a
+ * member until this function decides they may become one, so every check
+ * here reads rows directly rather than resolving one. Order follows D10 and
+ * D3 exactly: not pending, expired, unverified email, mismatched email,
+ * tenant state, then the inviter's authority re-checked as it stands now
+ * (not as it stood when they sent the invitation), then the profile, then
+ * the membership itself.
+ *
+ * `binding` and `policy` are threaded through to `roleForInvitation`,
+ * `loadAccess`/`operatorMayStillOnboard` and `attemptBornAttach`, the same
+ * as every other write this campaign has moved. `profiles` is the host's own
+ * port over its `profiles` table's one question this function asks --
+ * reusing `Pick<OwnerActivityLookup, 'personKnown'>` from install-owner.ts
+ * rather than declaring a second port for the same "has this id ever signed
+ * in" question.
+ */
+export async function acceptInvitation(principal, db, scopeColumn, binding, policy, profiles, token) {
+    if (principal.class !== 'human')
+        return refused('not_a_person', 'Only a signed-in person can accept an invitation.');
+    const tokenHash = createHash('sha256').update(token).digest('hex');
+    return db.transaction(async (tx) => {
+        const [location] = await tx
+            .select({ tenantId: invitations.tenantId })
+            .from(invitations)
+            .where(eq(invitations.tokenHash, tokenHash))
+            .limit(1);
+        if (!location)
+            return refused('invitation_not_found', 'This invitation link is not valid.');
+        await tx
+            .select({ id: tenants.id })
+            .from(tenants)
+            .where(eq(tenants.id, location.tenantId))
+            .for('update');
+        const [row] = await tx
+            .select()
+            .from(invitations)
+            .where(eq(invitations.tokenHash, tokenHash))
+            .for('update');
+        if (!row)
+            return refused('invitation_not_found', 'This invitation link is not valid.');
+        if (row.status !== 'pending') {
+            return refused('not_pending', 'This invitation has already been used.');
+        }
+        const [tenantRow] = await tx
+            .select({
+            id: tenants.id,
+            kind: tenants.kind,
+            name: tenants.name,
+            state: tenants.state,
+            ceiling: tenants.ceiling,
+            selfDenied: tenants.selfDenied,
+        })
+            .from(tenants)
+            .where(eq(tenants.id, row.tenantId))
+            .limit(1);
+        if (!tenantRow)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        const kind = tenantRow.kind;
+        // Events about an operator tenant carry context 'operator', the same
+        // rule loadAccess uses to decide a resolved Access's own context.
+        const context = kind === 'operator' ? 'operator' : 'standard';
+        if (row.expiresAt.getTime() <= Date.now()) {
+            await tx.update(invitations).set({ status: 'expired' }).where(eq(invitations.id, row.id));
+            await recordAs(tx, principal, context, {
+                action: 'invitation.expired',
+                tenantId: tenantRow.id,
+                targetType: 'invitation',
+                targetId: row.id,
+                reason: 'expired',
+            });
+            return refused('expired', 'This invitation has expired. Ask for a new one.');
+        }
+        if (!principal.emailVerified) {
+            return refused('email_unverified', 'Verify your email address before accepting this invitation.');
+        }
+        if (!principal.email || principal.email.toLowerCase() !== row.email) {
+            return refused('email_mismatch', 'This invitation was sent to a different address.');
+        }
+        // Read as a refusal, not a status change: the row stays pending, because
+        // it is exactly as good once the tenant is active again.
+        if (tenantRow.state === 'suspended' || tenantRow.state === 'archived') {
+            return refused('tenant_state', `This organisation is ${tenantRow.state}, so nobody can join it right now.`);
+        }
+        const invitedRole = await roleForInvitation(tx, binding, tenantRow.id, row.roleId);
+        if (!invitedRole)
+            return refused('unknown_role', 'The invited role no longer exists.');
+        let inviterMay = false;
+        if (row.invitedBy && row.invitedByClass) {
+            const inviter = await loadAccess(tx, binding, db, scopeColumn, {
+                id: row.invitedBy,
+                class: row.invitedByClass,
+                display: row.invitedBy,
+                email: null,
+                emailVerified: false,
+            }, tenantRow.id, false, true);
+            if (inviter)
+                inviterMay =
+                    roleAssignmentRefusal(inviter, invitedRole, primaryAssignment(invitedRole, { id: principal.id, class: principal.class }), 'members:grant') === null;
+            // Not `.builtIn`: see the same note above `roleAssignmentRefusal`'s
+            // `previous.key === 'owner'` check further up this file.
+            else if (row.invitedByClass === 'human' && invitedRole.key === 'owner' && kind === 'customer')
+                inviterMay = await operatorMayStillOnboard(tx, binding, db, scopeColumn, row.invitedBy, tenantRow.id);
+        }
+        if (!inviterMay) {
+            await tx.update(invitations).set({ status: 'expired' }).where(eq(invitations.id, row.id));
+            await recordAs(tx, principal, context, {
+                action: 'invitation.expired',
+                tenantId: tenantRow.id,
+                targetType: 'invitation',
+                targetId: row.id,
+                reason: 'inviter_no_longer_may',
+            });
+            return refused('inviter_no_longer_may', 'Whoever sent this invitation can no longer grant that role. Ask for a new one.');
+        }
+        // ensureProfile is the caller's job before this is ever reached (a
+        // signed-in person always has one by then); this is the fail-closed
+        // check for a stray call that skipped it. `profiles` is the host's own
+        // port over its own `profiles` (or equivalent) table.
+        if (!(await profiles.personKnown(principal.id)))
+            return refused('no_profile', 'Sign in first, then open this link again.');
+        const [existingMembership] = await tx
+            .select({ principalId: memberships.principalId, source: memberships.source })
+            .from(memberships)
+            .where(identityWhere(tenantRow.id, principal))
+            .limit(1);
+        // Reached here through a derived row, this acceptance would do nothing at
+        // all: the role it offers cannot be written over a row the parent
+        // organisation manages (D19: a child sees a derived row and cannot change
+        // it), and the branch below would have marked the invitation accepted and
+        // returned success while granting nothing. Refused in words instead, with
+        // the invitation left pending, so it becomes acceptable again the day the
+        // organisations are detached. Whether a child should be able to hold a
+        // direct row over a derived one is a real question and a deliberate door,
+        // not something to decide inside an acceptance.
+        if (existingMembership?.source === 'inherited') {
+            return refused('inherited', 'You already reach this organisation through the one that holds it, and that role is managed there, so this invitation cannot add another.');
+        }
+        if (existingMembership) {
+            await tx
+                .update(invitations)
+                .set({ status: 'accepted', acceptedBy: principal.id, acceptedAt: new Date() })
+                .where(eq(invitations.id, row.id));
+            await recordAs(tx, principal, context, {
+                action: 'invitation.accepted',
+                tenantId: tenantRow.id,
+                targetType: 'invitation',
+                targetId: row.id,
+            });
+            return done({ tenantId: tenantRow.id }, [tenantTag(tenantRow.id)]);
+        }
+        // The membership row's own insert is @wtfalch/people's `grantMembership`,
+        // inlined here rather than imported: `@wtfalch/people` 0.2.3 depends on
+        // `@wtfalch/authz-store` itself, so importing it back would be a cycle
+        // (authz#83 wave 8 decision 5). The role assignment and
+        // participation-policy writes stay this file's own, run right after the
+        // insert inside the same transaction, the same split a host's own
+        // `memberships.ts` draws through `onGranted`. `@wtfalch/people`'s
+        // `grantMembership` takes no audit argument here (Boule never passed
+        // one), so this inlined insert writes none either; `invitation.accepted`
+        // and `membership.created` below are this function's own rows.
+        const [alreadyMember] = await tx
+            .select({ principalId: memberships.principalId })
+            .from(memberships)
+            .where(identityWhere(tenantRow.id, principal))
+            .limit(1);
+        // Unreachable in practice: `existingMembership` above already checked
+        // this inside the same transaction.
+        if (alreadyMember)
+            return refused('already_member', 'You already participate here.');
+        await tx.insert(memberships).values({
+            tenantId: tenantRow.id,
+            principalId: principal.id,
+            principalClass: principal.class,
+            source: 'direct',
+            viaTenantId: null,
+            tenantName: tenantRow.name,
+            grantedBy: row.invitedBy,
+        });
+        await writePrimaryAssignment(tx, binding, invitedRole, { id: principal.id, class: principal.class }, { createdBy: row.invitedBy });
+        await writeParticipationPolicy(tx, binding, tenantRow.id, principal);
+        await tx
+            .update(invitations)
+            .set({ status: 'accepted', acceptedBy: principal.id, acceptedAt: new Date() })
+            .where(eq(invitations.id, row.id));
+        await recordAs(tx, principal, context, {
+            action: 'invitation.accepted',
+            tenantId: tenantRow.id,
+            targetType: 'invitation',
+            targetId: row.id,
+        });
+        await recordAs(tx, principal, context, {
+            action: 'membership.created',
+            tenantId: tenantRow.id,
+            targetType: 'membership',
+            targetId: principal.id,
+            after: { roleId: invitedRole.id, role: invitedRole.key },
+        });
+        // D19: the row above is a direct membership like any other, so a tenant
+        // that holds children owes them the derived rows it implies. The
+        // propagating writes exist for exactly this reason; an acceptance that
+        // skipped it would leave a person with authority at a parent and none in
+        // its children until something else happened to recompute, which the
+        // reconciliation check would then report as drift nobody caused on
+        // purpose.
+        const acceptedTags = await propagateMembershipChange(tx, binding, writerFromPrincipal(principal, context), tenantRow.id, principal.id);
+        // D10, D19: a tenant an operator created with attachTo carries the
+        // parent on the invitation rather than on itself, because the
+        // attachment only happens once someone has actually accepted and become
+        // its first owner. That owner is already written above; a refused
+        // attachment is reported, never allowed to undo them.
+        if (row.attachParentId) {
+            const attachRefusal = await attemptBornAttach(tx, binding, policy, principal, context, row.attachParentId, tenantRow.id);
+            const tags = attachRefusal
+                ? [tenantTag(tenantRow.id), ...acceptedTags]
+                : [tenantTag(tenantRow.id), tenantTag(row.attachParentId), ...acceptedTags];
+            return done({
+                tenantId: tenantRow.id,
+                attached: !attachRefusal,
+                attachRefusal: attachRefusal ?? undefined,
+            }, tags);
+        }
+        return done({ tenantId: tenantRow.id }, [tenantTag(tenantRow.id), ...acceptedTags]);
+    });
+}
+/** `members:read`; every pending invitation for the members page, with `token_hash` never among the selected columns. */
+export async function pendingInvitations(access, db) {
+    if (!(await permitsRead(access, db, 'members:read')))
+        return [];
+    const rows = await db
+        .select({
+        id: invitations.id,
+        email: invitations.email,
+        role: invitationRoleKey,
+        status: invitations.status,
+        mailState: invitations.mailState,
+        invitedBy: invitations.invitedBy,
+        expiresAt: invitations.expiresAt,
+        createdAt: invitations.createdAt,
+        parentName: parentTenants.name,
+    })
+        .from(invitations)
+        .leftJoin(parentTenants, eq(invitations.attachParentId, parentTenants.id))
+        .where(and(eq(invitations.tenantId, access.tenant.id), eq(invitations.status, 'pending')))
+        .orderBy(desc(invitations.createdAt));
+    // The left join's own column is typed as though it always matched; it is
+    // null at runtime for every ordinary invitation, so this makes the type
+    // say what the value already does rather than widen the query itself.
+    return rows.map((row) => ({ ...row, parentName: row.parentName ?? null }));
+}
+/** For the acceptance page, reachable before anyone is signed in: what the invitation offers, never the hash, the inviter's address, or the parent's id. */
+export async function invitationPreview(token, db) {
+    const tokenHash = createHash('sha256').update(token).digest('hex');
+    const [row] = await db
+        .select({
+        tenantName: tenants.name,
+        role: invitationRoleKey,
+        status: invitations.status,
+        expiresAt: invitations.expiresAt,
+        parentName: parentTenants.name,
+    })
+        .from(invitations)
+        .innerJoin(tenants, eq(invitations.tenantId, tenants.id))
+        .leftJoin(parentTenants, eq(invitations.attachParentId, parentTenants.id))
+        .where(eq(invitations.tokenHash, tokenHash))
+        .limit(1);
+    return row ? { ...row, parentName: row.parentName ?? null } : null;
+}
+/**
+ * The tenant a token's invitation belongs to, regardless of its status --
+ * pending, accepted, revoked or expired. Exists for one caller only: the
+ * accept page, so that a `not_pending` refusal (the row has already been
+ * used) can be told apart from every other refusal by asking a second
+ * question -- is this signed-in person already a member there -- without
+ * touching `acceptInvitation` itself. Unlike `invitationPreview`, this may
+ * only be called once a principal is established: it hands back the raw
+ * tenant id, which `invitationPreview`'s own docblock deliberately never
+ * does for a visitor who has not signed in yet.
+ */
+export async function invitationTenantId(token, db) {
+    const tokenHash = createHash('sha256').update(token).digest('hex');
+    const [row] = await db
+        .select({ tenantId: invitations.tenantId })
+        .from(invitations)
+        .where(eq(invitations.tokenHash, tokenHash))
+        .limit(1);
+    return row?.tenantId ?? null;
+}