@wtfalch/authz-store 0.2.1 → 0.4.0

package/dist/tenants.js

@@ -0,0 +1,808 @@
+import { sqlState } from '@wtfalch/db';
+import { and, asc, eq, gt, ilike, or, sql } from 'drizzle-orm';
+import { writeParticipationPolicy, writePrimaryAssignment } from './assignments.js';
+import { record, recordAs } from './audit.js';
+import { ensureBuiltInRoles, seedStarterRoles } from './boot.js';
+import { generateInvitationToken } from './invitations.js';
+import { permits, permitsPlatform, permitsPlatformRead, refreshAccess } from './policy-access.js';
+import { roleDef } from './roles.js';
+import { invitations, memberships, tenants } from './schema.js';
+import { ancestorsOf, attachProblem, childrenOf, descendantsOf, lockSubtreeForUpdate, lockTenantsForUpdate, nodeById, } from './tree.js';
+import { done, isUuid, refused, tenantTag, } from './types.js';
+/**
+ * Tenant-level writes: creating one (self-serve, gated by a host's own
+ * `TENANT_CREATION`), and the operator- or owner-facing settings on an
+ * existing one. Every function here locks the tenant row it is about to
+ * change `FOR UPDATE` before writing, refuses under a break-glass context
+ * (D8: no session ever changes authority or settings), and records exactly
+ * one audit row through the `Access` or `Principal` it was handed.
+ *
+ * Wave 9a (authz#83, issue #99 decision 4) is the member-side writes and the
+ * reads: `createTenant`, `renameTenant`, `setSelfDenied`, `setTenantState`,
+ * `setCeiling`, `tenantById`, `tenantBySlug`, `allTenants`. Wave 9b adds the
+ * operator side: `createTenantAsOperator`, `deleteJustCreatedTenant`,
+ * `archiveTenant`.
+ *
+ * `db` and `scopeColumn` are the host's root handle and tenant-table
+ * registry (wave 1), taken as parameters rather than imported, the same as
+ * every other write module this campaign has moved. `TENANT_CREATION` and
+ * `TENANT_CREATION_CAP_PER_DAY` are no longer package constants: a host
+ * passes both through `CreateTenantConfig` (decision 3). `defaultCeiling`
+ * and `offered` come off the `policy: StorePolicy` (or the narrower
+ * `Pick<StorePolicy, 'defaultCeiling' | 'offered'>` where that is all a
+ * function needs) a caller passes in, rather than an import (decision 4).
+ */
+/**
+ * SQLSTATE may be on the driver error or a native ORM cause; 23505 is
+ * unique_violation. Two requests racing for the same slug both pass the
+ * collision read below and one of them loses here, which is a refusal to
+ * word, not a crash to report.
+ */
+function isUniqueViolation(error) {
+    return sqlState(error) === '23505';
+}
+/**
+ * Whether two ceilings hold exactly the same permissions, order aside: what
+ * `setCeiling`'s descendant walk uses to skip an audit row for a descendant
+ * `clipCeiling` did not actually have to narrow (D19's rule that an already-
+ * inside descendant is not an event).
+ */
+function sameCeiling(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.every((value, index) => value === sortedB[index]);
+}
+/**
+ * The self-serve path (D10): closed by default (`config.creation !==
+ * 'anyone'`), and capped per principal per rolling day when open, refused
+ * inside the same transaction that would otherwise create the row so the
+ * count and the insert never race. The creator becomes the tenant's first
+ * owner in the same transaction, which is also its own audited event, so a
+ * tenant is never observed to exist without someone who can run it.
+ *
+ * `profiles` is the host's own port over its `profiles` (or equivalent)
+ * table's one question this function asks -- reusing `Pick<
+ * OwnerActivityLookup, 'personKnown'>` from install-owner.ts (decision 6)
+ * rather than declaring a second port for the same "has this id ever signed
+ * in" question. `policy` is the full `StorePolicy`, not the narrower pick
+ * decision 4 names for `setSelfDenied`/`setCeiling`: this function also
+ * drives `ensureBuiltInRoles`/`seedStarterRoles`/`roleDef`, which need the
+ * role-template methods and `applicationId`/`platformId` a bare
+ * `Pick<StorePolicy, 'defaultCeiling' | 'offered'>` does not carry.
+ */
+export async function createTenant(principal, db, policy, config, profiles, options) {
+    if (config.creation !== 'anyone') {
+        return refused('creation_closed', 'Only an operator can create an organisation here.');
+    }
+    return db.transaction(async (tx) => {
+        if (principal.class === 'human') {
+            if (!(await profiles.personKnown(principal.id)))
+                return refused('unknown_person', 'This person has never signed in here.');
+        }
+        // There is no tenant row to lock before the tenant exists, so the cap
+        // serialises on the principal instead: a transaction-scoped advisory lock
+        // keyed on their id, held until commit, so two creates racing each other
+        // cannot both read the count below before either inserts.
+        await tx.execute(sql `select pg_advisory_xact_lock(hashtextextended(${principal.id}, 0))`);
+        const [row] = await tx
+            .select({ count: sql `count(*)::int` })
+            .from(tenants)
+            .where(and(eq(tenants.createdBy, principal.id), sql `${tenants.createdAt} > now() - interval '24 hours'`));
+        const createdToday = row?.count ?? 0;
+        if (createdToday >= config.capPerDay) {
+            await recordAs(tx, principal, 'standard', {
+                action: 'tenant.created',
+                tenantId: null,
+                targetType: 'tenant',
+                targetId: options.slug,
+                outcome: 'denied',
+                reason: `more than ${config.capPerDay} organisations created in the last day`,
+            });
+            return refused('cap_reached', `You can only create ${config.capPerDay} organisations a day.`);
+        }
+        const [collision] = await tx
+            .select({ id: tenants.id })
+            .from(tenants)
+            .where(eq(tenants.slug, options.slug))
+            .limit(1);
+        if (collision)
+            return refused('slug_taken', 'That address is already taken.');
+        let tenantRow;
+        try {
+            [tenantRow] = await tx
+                .insert(tenants)
+                .values({
+                kind: 'customer',
+                slug: options.slug,
+                name: options.name,
+                ceiling: [...policy.defaultCeiling],
+                selfDenied: [],
+                createdBy: principal.id,
+            })
+                .returning({ id: tenants.id });
+        }
+        catch (error) {
+            if (isUniqueViolation(error))
+                return refused('slug_taken', 'That address is already taken.');
+            throw error;
+        }
+        if (!tenantRow)
+            throw new Error('createTenant: no row returned from the insert');
+        await ensureBuiltInRoles(tx, policy, { id: tenantRow.id, kind: 'customer' });
+        await seedStarterRoles(tx, policy, { id: tenantRow.id, kind: 'customer' });
+        const owner = await roleDef(tx, policy, tenantRow, 'owner');
+        if (!owner)
+            throw new Error('Missing starter owner role');
+        await tx.insert(memberships).values({
+            tenantId: tenantRow.id,
+            principalId: principal.id,
+            principalClass: principal.class,
+            source: 'direct',
+            tenantName: options.name,
+            grantedBy: principal.id,
+        });
+        await writePrimaryAssignment(tx, policy, owner, principal, { createdBy: principal.id });
+        await writeParticipationPolicy(tx, policy, tenantRow.id, principal);
+        await recordAs(tx, principal, 'standard', {
+            action: 'tenant.created',
+            tenantId: tenantRow.id,
+            targetType: 'tenant',
+            targetId: tenantRow.id,
+            after: { kind: 'customer', slug: options.slug, name: options.name },
+        });
+        await recordAs(tx, principal, 'standard', {
+            action: 'membership.created',
+            tenantId: tenantRow.id,
+            targetType: 'membership',
+            targetId: principal.id,
+            after: { role: 'owner' },
+        });
+        return done({ id: tenantRow.id }, [tenantTag(tenantRow.id)]);
+    });
+}
+/** Renames or re-slugs a tenant, keeping `memberships.tenant_name` in step (D5) when the name changes. */
+export async function renameTenant(access, db, scopeColumn, options) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never changes an organisation and what it is called.');
+    }
+    if (!permits(access, 'tenant:update')) {
+        return refused('no_permission', 'You do not have permission to rename this organisation.');
+    }
+    if (options.name === undefined && options.slug === undefined) {
+        return refused('nothing_to_change', 'Nothing was given to change.');
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'tenant:update'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        const [tenantRow] = await tx
+            .select({ id: tenants.id, name: tenants.name, slug: tenants.slug })
+            .from(tenants)
+            .where(eq(tenants.id, currentAccess.tenant.id))
+            .for('update');
+        if (!tenantRow)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        const nextName = options.name ?? tenantRow.name;
+        const nextSlug = options.slug ?? tenantRow.slug;
+        if (nextSlug !== tenantRow.slug) {
+            const [collision] = await tx
+                .select({ id: tenants.id })
+                .from(tenants)
+                .where(eq(tenants.slug, nextSlug))
+                .limit(1);
+            if (collision)
+                return refused('slug_taken', 'That address is already taken.');
+        }
+        try {
+            await tx
+                .update(tenants)
+                .set({ name: nextName, slug: nextSlug, updatedAt: new Date() })
+                .where(eq(tenants.id, tenantRow.id));
+        }
+        catch (error) {
+            if (isUniqueViolation(error))
+                return refused('slug_taken', 'That address is already taken.');
+            throw error;
+        }
+        if (options.name !== undefined) {
+            await tx
+                .update(memberships)
+                .set({ tenantName: nextName })
+                .where(eq(memberships.tenantId, tenantRow.id));
+        }
+        await record(tx, currentAccess, {
+            action: 'tenant.settings_changed',
+            tenantId: tenantRow.id,
+            targetType: 'tenant',
+            targetId: tenantRow.id,
+            before: { name: tenantRow.name, slug: tenantRow.slug },
+            after: { name: nextName, slug: nextSlug },
+        });
+        return done(undefined, [tenantTag(tenantRow.id)]);
+    });
+}
+/**
+ * Sets what this tenant has switched off for itself, within what it was
+ * offered (D22). Checked before the transaction opens means a bad list never
+ * reaches a lock at all; nothing at read time trips over a stored value that
+ * should never have been written.
+ */
+export async function setSelfDenied(access, db, scopeColumn, policy, list) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never changes what an organisation has switched off for itself.');
+    }
+    if (!permits(access, 'tenant:update')) {
+        return refused('no_permission', 'You do not have permission to change this organisation.');
+    }
+    const problems = list.filter((p) => !policy.offered.includes(p));
+    if (problems.length > 0) {
+        return refused('invalid_self_denied', `Not offered here, so it cannot be switched off: ${problems.join(', ')}.`);
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'tenant:update'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        const [tenantRow] = await tx
+            .select({ id: tenants.id, selfDenied: tenants.selfDenied })
+            .from(tenants)
+            .where(eq(tenants.id, currentAccess.tenant.id))
+            .for('update');
+        if (!tenantRow)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        await tx
+            .update(tenants)
+            .set({ selfDenied: [...list], updatedAt: new Date() })
+            .where(eq(tenants.id, tenantRow.id));
+        await record(tx, currentAccess, {
+            action: 'tenant.settings_changed',
+            tenantId: tenantRow.id,
+            targetType: 'tenant',
+            targetId: tenantRow.id,
+            before: { selfDenied: tenantRow.selfDenied },
+            after: { selfDenied: list },
+        });
+        return done(undefined, [tenantTag(tenantRow.id)]);
+    });
+}
+/**
+ * Moves a tenant between active, read-only, suspended and archived (D11).
+ * `operatorAccess` must be resolved against the operator tenant, which is
+ * how this refuses a signed-in customer who somehow reaches the call: their
+ * `Access` was never built from the operator tenant, so `kind !== 'operator'`
+ * catches it before the permission check even runs. The operator tenant
+ * itself can never be the target, or every operator locks themselves out.
+ *
+ * Archiving is refused while the tenant holds children (D19's fifth rule),
+ * unless `cascade` is asked for: cascading archives every descendant in the
+ * same breath, which is what satisfies "detach or archive them first" in one
+ * transaction rather than requiring it to have already happened.
+ */
+export async function setTenantState(operatorAccess, db, scopeColumn, tenantId, state, options = {}) {
+    if (operatorAccess.context === 'break_glass') {
+        return refused('break_glass', "A break-glass session never changes an organisation's state.");
+    }
+    if (operatorAccess.tenant.kind !== 'operator' ||
+        !permitsPlatform(operatorAccess, 'tenants:state')) {
+        return refused('no_permission', "You do not have permission to change an organisation's state.");
+    }
+    if (!isUuid(tenantId))
+        return refused('tenant_not_found', 'This organisation no longer exists.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, operatorAccess);
+        if (!fresh || fresh.context === 'break_glass' || !permitsPlatform(fresh, 'tenants:state'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        // Locked first, then read. Reading the subtree and then locking what it
+        // found lets an attach commit in between, and the child it adds is
+        // invisible to everything below: a cascade skips it, and the has_children
+        // refusal says there are none while one is sitting there.
+        const locked = await lockSubtreeForUpdate(tx, tenantId);
+        const target = locked.get(tenantId);
+        if (!target)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        if (target.kind === 'operator') {
+            return refused('operator_immutable', 'The operator organisation is always active.');
+        }
+        // The has_children refusal only ever needs to see direct children; a
+        // cascade needs the whole subtree, since the state reaches every level.
+        const subtree = options.cascade
+            ? await descendantsOf(tx, tenantId)
+            : await childrenOf(tx, tenantId);
+        const hasChildren = subtree.some((node) => node.parentId === tenantId);
+        if (state === 'archived' && hasChildren && !options.cascade) {
+            return refused('has_children', 'This organisation holds others. Detach or archive them first.');
+        }
+        await tx.update(tenants).set({ state, updatedAt: new Date() }).where(eq(tenants.id, tenantId));
+        await record(tx, currentAccess, {
+            action: 'tenant.state_changed',
+            tenantId,
+            targetType: 'tenant',
+            targetId: tenantId,
+            before: { state: target.state },
+            after: { state },
+        });
+        const tags = [tenantTag(tenantId)];
+        if (options.cascade) {
+            for (const node of subtree) {
+                const current = locked.get(node.id);
+                if (!current || current.state === state)
+                    continue;
+                await tx
+                    .update(tenants)
+                    .set({ state, updatedAt: new Date() })
+                    .where(eq(tenants.id, node.id));
+                await record(tx, currentAccess, {
+                    action: 'tenant.state_changed',
+                    tenantId: node.id,
+                    targetType: 'tenant',
+                    targetId: node.id,
+                    before: { state: current.state },
+                    after: { state },
+                });
+                tags.push(tenantTag(node.id));
+            }
+        }
+        return done(undefined, tags);
+    });
+}
+/**
+ * Sets what a tenant may use (D22), recorded as `tenant.ceiling_changed`.
+ * `platform.tenants:ceiling` governs operator reach; `tenants:ceiling`
+ * governs a parent's own children. Both require explicit canonical grants.
+ * The target's parent relationship is read from the locked row rather than
+ * trusted from the caller. A ceiling that would exceed the target's own
+ * parent's is refused with the offenders named regardless of which route
+ * authorised the call, and narrowing clips every descendant in the same
+ * transaction, nearest level first, skipping a descendant whose ceiling was
+ * already inside the new one (no change, no event).
+ */
+export async function setCeiling(access, db, scopeColumn, policy, tenantId, list) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never changes what an organisation may use.');
+    }
+    if (!(access.tenant.kind === 'operator'
+        ? permitsPlatform(access, 'platform.tenants:ceiling')
+        : permits(access, 'tenants:ceiling'))) {
+        return refused('no_permission', 'You do not have permission to change what an organisation may use.');
+    }
+    if (!isUuid(tenantId))
+        return refused('tenant_not_found', 'This organisation no longer exists.');
+    const problems = list.filter((p) => !policy.offered.includes(p));
+    if (problems.length > 0) {
+        return refused('invalid_ceiling', `Not an offered permission: ${problems.join(', ')}.`);
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh ||
+            fresh.context === 'break_glass' ||
+            !(fresh.tenant.kind === 'operator'
+                ? permitsPlatform(fresh, 'platform.tenants:ceiling')
+                : permits(fresh, 'tenants:ceiling')))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        // Locked first, then read: a child attached between an unlocked read and
+        // the lock would never be clipped, and would keep a ceiling wider than
+        // the parent it now hangs off, permanently and undetectably (the
+        // reconciliation check reads derived rows, not ceilings).
+        const locked = await lockSubtreeForUpdate(tx, tenantId);
+        const target = locked.get(tenantId);
+        if (!target)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        if (target.parentId) {
+            for (const [id, node] of await lockTenantsForUpdate(tx, [target.parentId])) {
+                locked.set(id, node);
+            }
+        }
+        const descendants = await descendantsOf(tx, tenantId);
+        const isOperator = currentAccess.tenant.kind === 'operator';
+        if (!isOperator && target.parentId !== currentAccess.tenant.id) {
+            return refused('no_permission', 'You do not have permission to change what an organisation may use.');
+        }
+        if (target.parentId) {
+            // Not necessarily in `locked`: the parent id above came from the
+            // unlocked read, so a parent that changed between that read and the
+            // lock is fetched fresh here rather than skipping the check silently.
+            const parent = locked.get(target.parentId) ?? (await nodeById(tx, target.parentId));
+            if (parent) {
+                const offenders = list.filter((p) => !parent.ceiling.includes(p));
+                if (offenders.length > 0) {
+                    return refused('ceiling_exceeds', `${target.name} may use more than ${parent.name} does. Narrow it first: ${offenders.join(', ')}.`);
+                }
+            }
+        }
+        await tx
+            .update(tenants)
+            .set({ ceiling: [...list], updatedAt: new Date() })
+            .where(eq(tenants.id, tenantId));
+        await record(tx, currentAccess, {
+            action: 'tenant.ceiling_changed',
+            tenantId,
+            targetType: 'tenant',
+            targetId: tenantId,
+            before: { ceiling: target.ceiling },
+            after: { ceiling: list },
+        });
+        const tags = [tenantTag(tenantId)];
+        // Clip every descendant against the ceiling directly above it, nearest
+        // level first (descendantsOf returns breadth first), so a grandchild
+        // clips against its own parent's ceiling as just computed here, not
+        // against the tenant this call named.
+        const ceilingAbove = new Map([[tenantId, list]]);
+        for (const node of descendants) {
+            const current = locked.get(node.id);
+            if (!current)
+                continue; // left the subtree between the read and the lock
+            const parentCeiling = ceilingAbove.get(current.parentId ?? '') ?? current.ceiling;
+            const clipped = [...current.ceiling.filter((p) => parentCeiling.includes(p))].sort();
+            ceilingAbove.set(node.id, clipped);
+            if (sameCeiling(current.ceiling, clipped))
+                continue;
+            await tx
+                .update(tenants)
+                .set({ ceiling: clipped, updatedAt: new Date() })
+                .where(eq(tenants.id, node.id));
+            // One per descendant actually clipped (D19, D22), under the same name
+            // as the narrowing that caused it, so a child's own log says its
+            // ceiling moved and names the parent's change as the reason.
+            await record(tx, currentAccess, {
+                action: 'tenant.ceiling_changed',
+                tenantId: node.id,
+                targetType: 'tenant',
+                targetId: node.id,
+                before: { ceiling: current.ceiling },
+                after: { ceiling: clipped },
+            });
+            tags.push(tenantTag(node.id));
+        }
+        return done(undefined, tags);
+    });
+}
+/** A tenant by id, or null. Takes whatever handle the caller already has open, raw or scoped-out. */
+export async function tenantById(handle, id) {
+    const [row] = await handle.select().from(tenants).where(eq(tenants.id, id)).limit(1);
+    return row ?? null;
+}
+/** A tenant by slug, or null. Used to resolve `/org/<slug>` before a membership is known. */
+export async function tenantBySlug(handle, slug) {
+    const [row] = await handle.select().from(tenants).where(eq(tenants.slug, slug)).limit(1);
+    return row ?? null;
+}
+/**
+ * Every organisation, for the operator console (D12).
+ *
+ * **`tenants:read-all`, which is an operator-scoped permission**, so this is
+ * the estate looking at its customers rather than a customer looking at
+ * itself. `null` when the actor does not hold it, never an empty page, the
+ * distinction `membersOf` and `securityLogFor` both draw: an operator with a
+ * narrowed role seeing "no organisations" would conclude the estate was
+ * empty.
+ *
+ * **Archived tenants are included here, unlike in `membershipsFor`.** A
+ * member's own switcher hides them because there is nothing they can do with
+ * one; an operator's console is exactly where somebody needs to see that a
+ * tenant was archived and when. The state is a column on the row rather than
+ * a filter on the query.
+ *
+ * Keyset-paged by `(name, id)`, the same shape and for the same reason as the
+ * chooser: an estate's tenant list is the one that grows without bound.
+ *
+ * `db` is the host's root handle, taken explicitly rather than imported: the
+ * store has no database of its own to reach for.
+ */
+export async function allTenants(access, db, options = {}) {
+    if (!(await permitsPlatformRead(access, db, 'tenants:read')))
+        return null;
+    const limit = Math.min(options.limit ?? 50, 200);
+    const conditions = [];
+    if (options.q) {
+        // A person types a name, not a pattern.
+        const literal = options.q.replace(/[\\%_]/g, (c) => `\\${c}`);
+        conditions.push(ilike(tenants.name, `%${literal}%`));
+    }
+    if (options.after) {
+        const { name, id } = options.after;
+        const keyset = or(gt(tenants.name, name), and(eq(tenants.name, name), gt(tenants.id, id)));
+        if (keyset)
+            conditions.push(keyset);
+    }
+    const rows = await db
+        .select({
+        id: tenants.id,
+        name: tenants.name,
+        slug: tenants.slug,
+        kind: tenants.kind,
+        state: tenants.state,
+        parentId: tenants.parentId,
+        ceiling: tenants.ceiling,
+        selfDenied: tenants.selfDenied,
+    })
+        .from(tenants)
+        .where(conditions.length > 0 ? and(...conditions) : undefined)
+        .orderBy(asc(tenants.name), asc(tenants.id))
+        .limit(limit + 1);
+    const page = rows.slice(0, limit);
+    const last = page.at(-1);
+    return {
+        items: page.map((r) => ({
+            id: r.id,
+            name: r.name,
+            slug: r.slug,
+            kind: r.kind,
+            state: r.state,
+            parentId: r.parentId,
+            ceiling: r.ceiling,
+            selfDenied: r.selfDenied,
+        })),
+        next: rows.length > limit && last ? { name: last.name, id: last.id } : null,
+    };
+}
+/**
+ * The sentinel that unwinds `createTenantAsOperator`'s transaction when
+ * `attachTo` turns out to be impossible: `db.transaction` commits whatever a
+ * callback returns without throwing, and a tenant already inserted by the
+ * time `attachProblem` is checked must not be left behind, standalone and
+ * ownerless in every sense but the pending invitation nobody will now get.
+ * Caught immediately outside the transaction and turned back into the
+ * `Result` refusal it carries, so the function never throws to its own
+ * caller.
+ */
+class BornAttachedRefusal extends Error {
+    result;
+    constructor(result) {
+        super('createTenantAsOperator: attachTo refused');
+        this.result = result;
+    }
+}
+/**
+ * The onboarding path valet and lokessmie use every day: the customer does
+ * not have an account yet, so the tenant is born with a pending owner
+ * invitation and no membership at all (M7). The operator never becomes a
+ * member of it, which is what keeps D8's rule (no standing operator
+ * membership in a customer tenant) true through onboarding; the last-owner
+ * guard tolerates the resulting zero-owner tenant because exactly one owner
+ * invitation is pending (`ownerSeatCovered` in `owners.ts`).
+ *
+ * `policy` is the full `StorePolicy`, the same as `createTenant`: this also
+ * drives `ensureBuiltInRoles`/`seedStarterRoles`/`roleDef` and
+ * `attachProblem`, none of which a bare `Pick<StorePolicy, 'defaultCeiling'
+ * | 'offered'>` would carry.
+ */
+export async function createTenantAsOperator(operatorAccess, db, scopeColumn, policy, options) {
+    if (operatorAccess.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never creates an organisation.');
+    }
+    if (operatorAccess.tenant.kind !== 'operator' ||
+        !permitsPlatform(operatorAccess, 'tenants:create')) {
+        return refused('no_permission', 'You do not have permission to create an organisation.');
+    }
+    const ownerEmail = options.ownerEmail.trim().toLowerCase();
+    try {
+        return await db.transaction(async (tx) => {
+            const fresh = await refreshAccess(tx, db, scopeColumn, operatorAccess);
+            if (!fresh || fresh.context === 'break_glass' || !permitsPlatform(fresh, 'tenants:create'))
+                return refused('no_permission', 'Your authority changed.');
+            const currentAccess = fresh;
+            // Checked ahead of the insert, the same as createTenant above: the
+            // ordinary case (someone reuses a slug that already exists) reads as a
+            // worded refusal here, and the try/catch below is only the backstop
+            // for two operators racing to create the same slug at once.
+            const [collision] = await tx
+                .select({ id: tenants.id })
+                .from(tenants)
+                .where(eq(tenants.slug, options.slug))
+                .limit(1);
+            if (collision)
+                return refused('slug_taken', 'That address is already taken.');
+            if (options.attachTo) {
+                // The parent AND everything above it, locked for the rest of the
+                // transaction. The parent alone is not enough: the depth check a few
+                // lines down counts the chain above it, and an attach that lengthens
+                // that chain concurrently would leave this one reading a depth that
+                // was true when it looked and wrong when it committed.
+                const above = (await ancestorsOf(tx, options.attachTo)).map((node) => node.id);
+                const lockedParent = await lockTenantsForUpdate(tx, [options.attachTo, ...above]);
+                if (!lockedParent.has(options.attachTo)) {
+                    return refused('parent_not_found', 'That organisation no longer exists.');
+                }
+            }
+            let tenantRow;
+            try {
+                [tenantRow] = await tx
+                    .insert(tenants)
+                    .values({
+                    kind: 'customer',
+                    slug: options.slug,
+                    name: options.name,
+                    ceiling: [...policy.defaultCeiling],
+                    selfDenied: [],
+                    createdBy: currentAccess.actor.id,
+                })
+                    .returning({ id: tenants.id });
+            }
+            catch (error) {
+                if (isUniqueViolation(error))
+                    return refused('slug_taken', 'That address is already taken.');
+                throw error;
+            }
+            if (!tenantRow)
+                throw new Error('createTenantAsOperator: no row returned from the insert');
+            await ensureBuiltInRoles(tx, policy, { id: tenantRow.id, kind: 'customer' });
+            await seedStarterRoles(tx, policy, { id: tenantRow.id, kind: 'customer' });
+            const owner = await roleDef(tx, policy, tenantRow, 'owner');
+            if (!owner)
+                throw new Error('Missing starter owner role');
+            if (options.attachTo) {
+                // The only child-side check attachProblem can run before the invitation
+                // is sent: the row now exists, born with parent_id null, so an
+                // impossible pairing (the parent archived, too deep, the child's
+                // default ceiling already wider than the parent's) is refused here
+                // rather than surfacing when someone eventually accepts. Refusing
+                // throws rather than returning, because the tenant row above is
+                // already written in this same transaction and must not be left
+                // behind, standalone, when the pairing the caller asked for cannot
+                // hold.
+                const problem = await attachProblem(tx, policy, options.attachTo, tenantRow.id);
+                if (problem)
+                    throw new BornAttachedRefusal(refused(problem.reason, problem.message));
+            }
+            // Same token rule as invite(): 32 random bytes, shown once, stored
+            // hashed, seven days. There is no existing pending row to rotate here,
+            // since the tenant itself was just created.
+            const { token, tokenHash, expiresAt } = generateInvitationToken();
+            const [invitationRow] = await tx
+                .insert(invitations)
+                .values({
+                tenantId: tenantRow.id,
+                email: ownerEmail,
+                roleId: owner.id,
+                tokenHash,
+                expiresAt,
+                invitedBy: currentAccess.actor.id,
+                invitedByClass: currentAccess.actor.class,
+                attachParentId: options.attachTo ?? null,
+            })
+                .returning({ id: invitations.id });
+            if (!invitationRow) {
+                throw new Error('createTenantAsOperator: no invitation row returned from the insert');
+            }
+            await record(tx, currentAccess, {
+                action: 'tenant.created',
+                tenantId: tenantRow.id,
+                targetType: 'tenant',
+                targetId: tenantRow.id,
+                after: { kind: 'customer', slug: options.slug, name: options.name },
+            });
+            await record(tx, currentAccess, {
+                action: 'invitation.sent',
+                tenantId: tenantRow.id,
+                targetType: 'invitation',
+                targetId: invitationRow.id,
+                after: { email: ownerEmail, role: 'owner' },
+            });
+            return done({ id: tenantRow.id, token, link: options.link(token) }, [
+                tenantTag(tenantRow.id),
+            ]);
+        });
+    }
+    catch (error) {
+        if (error instanceof BornAttachedRefusal)
+            return error.result;
+        throw error;
+    }
+}
+/**
+ * Undoes `createTenantAsOperator` when a caller's own second write fails
+ * afterward and cannot be retried (issue #40: the billing area creates the
+ * tenant first and then a `@wtfalch/foundry` `DeclaredOrg` carrying its id,
+ * in a different database, so the two can never share one transaction). This
+ * is the compensating half -- hard deletes rather than archiving, unlike the
+ * ordinary meaning of `tenant:delete` (`denial.ts`'s `tenant.state_changed`):
+ * a tenant this refuses to touch is never one that has ever been usable, and
+ * archiving would leave a name on the operator's tenant list for something
+ * that does not exist. Refuses once anyone has joined -- the same signal
+ * `createTenantAsOperator` relies on for a tenant that is still only a
+ * pending invitation (M7) -- so this can never reach a tenant somebody may
+ * already be looking at.
+ *
+ * Writes no audit row: `tenant.deleted` is not among `@wtfalch/authz`'s
+ * `core.events` (`schema-check.test.ts` holds the database's closed set
+ * equal to exactly `core.events` plus a host's own `APP_EVENTS`), and nothing
+ * here may widen that package's vocabulary. The `tenant.created` row the
+ * failed attempt already wrote stands on the operator log as the record of
+ * it; every child row this deletes (`invitations`, `roles`,
+ * `role_permissions`) cascades with the tenant, since none of it ever
+ * mattered without it.
+ *
+ * Moves as an ordinary exported store function, copied from archon with its
+ * comment. Its own guards make it operator-only; there is no hook or
+ * extension interface, since it has no archon-only dependency (issue #99
+ * decision 4: "an optional extension" is this, with less machinery, because
+ * only archon ever calls it).
+ */
+export async function deleteJustCreatedTenant(operatorAccess, db, scopeColumn, tenantId) {
+    if (operatorAccess.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never deletes an organisation.');
+    }
+    if (operatorAccess.tenant.kind !== 'operator' ||
+        !permitsPlatform(operatorAccess, 'tenants:create')) {
+        return refused('no_permission', 'You do not have permission to delete this organisation.');
+    }
+    if (!isUuid(tenantId))
+        return refused('tenant_not_found', 'This organisation no longer exists.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, operatorAccess);
+        if (!fresh || fresh.context === 'break_glass' || !permitsPlatform(fresh, 'tenants:create'))
+            return refused('no_permission', 'Your authority changed.');
+        const [tenantRow] = await tx
+            .select({ id: tenants.id, kind: tenants.kind })
+            .from(tenants)
+            .where(eq(tenants.id, tenantId))
+            .for('update');
+        if (!tenantRow)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        if (tenantRow.kind === 'operator') {
+            return refused('operator_immutable', 'The operator organisation can never be deleted.');
+        }
+        const [membership] = await tx
+            .select({ tenantId: memberships.tenantId })
+            .from(memberships)
+            .where(eq(memberships.tenantId, tenantId))
+            .limit(1);
+        if (membership) {
+            return refused('has_members', 'This organisation already has a member and can no longer be rolled back.');
+        }
+        await tx.delete(tenants).where(eq(tenants.id, tenantId));
+        return done(undefined, [tenantTag(tenantId)]);
+    });
+}
+/**
+ * Archives a tenant from inside it, by whoever holds `tenant:delete` there
+ * (the owner: the permission is not assignable, so no other system role
+ * carries it). Refused while the tenant holds children (D19's fifth rule):
+ * an archived parent's own state says nothing about the organisations
+ * hanging off it, so those must be detached or archived on purpose first,
+ * not silently along for the ride.
+ */
+export async function archiveTenant(access, db, scopeColumn) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never archives an organisation.');
+    }
+    if (!permits(access, 'tenant:delete')) {
+        return refused('no_permission', 'You do not have permission to archive this organisation.');
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'tenant:delete'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        // Locked first, then read. The earlier shape read the children, locked
+        // that snapshot, and then only re-checked whether one had LEFT, so a
+        // child attached in the gap was never counted and the tenant archived
+        // out from under it.
+        const locked = await lockSubtreeForUpdate(tx, currentAccess.tenant.id);
+        const tenantRow = locked.get(currentAccess.tenant.id);
+        if (!tenantRow)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        const children = await childrenOf(tx, currentAccess.tenant.id);
+        if (children.length > 0) {
+            return refused('has_children', 'This organisation holds others. Detach or archive them first.');
+        }
+        await tx
+            .update(tenants)
+            .set({ state: 'archived', updatedAt: new Date() })
+            .where(eq(tenants.id, tenantRow.id));
+        await record(tx, currentAccess, {
+            action: 'tenant.state_changed',
+            tenantId: tenantRow.id,
+            targetType: 'tenant',
+            targetId: tenantRow.id,
+            before: { state: tenantRow.state },
+            after: { state: 'archived' },
+        });
+        return done(undefined, [tenantTag(tenantRow.id)]);
+    });
+}