@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/roles.d.ts

@@ -0,0 +1,36 @@
+import { type ResourceRole } from '@wtfalch/authz';
+import type { StoreBinding } from './binding.js';
+import type { DbOrTx, Scope } from './scoped.js';
+import { type Access, type Result } from './types.js';
+export declare function roleDef(tx: DbOrTx, binding: StoreBinding, tenant: {
+    id: string;
+}, key: string): Promise<ResourceRole | null>;
+export declare function assignableRoles(access: Access): Promise<ResourceRole[]>;
+export interface EditableRole extends ResourceRole {
+    readonly custom: boolean;
+    readonly editable: boolean;
+}
+export declare function rolesForEditor(access: Access): Promise<EditableRole[]>;
+/** Definition edits must cover both its full scope and every existing recipient/scope. */
+export declare function canEditDefinition(access: Access, role: ResourceRole): boolean;
+export interface CreateRoleOptions {
+    readonly key: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly entries: ResourceRole['entries'];
+}
+export interface UpdateRoleOptions {
+    readonly key: string;
+    readonly revision: number;
+    readonly name?: string;
+    readonly description?: string;
+    readonly entries?: ResourceRole['entries'];
+}
+export interface DeleteRoleOptions {
+    readonly key: string;
+}
+export declare function createRole(access: Access, db: DbOrTx, scopeColumn: Scope['column'], options: CreateRoleOptions): Promise<Result<{
+    key: string;
+}>>;
+export declare function updateRole(access: Access, db: DbOrTx, scopeColumn: Scope['column'], options: UpdateRoleOptions): Promise<Result<void>>;
+export declare function deleteRole(access: Access, db: DbOrTx, scopeColumn: Scope['column'], options: DeleteRoleOptions): Promise<Result<void>>;

package/dist/roles.js

@@ -0,0 +1,191 @@
+import { randomUUID } from 'node:crypto';
+import { core, resourceRoleSchema } from '@wtfalch/authz';
+import { and, eq } from 'drizzle-orm';
+import { primaryAssignment, roleAssignmentRefusal } from './assignments.js';
+import { record } from './audit.js';
+import { permits, policyAssignment, policyRole, refreshAccess } from './policy-access.js';
+import { policyAssignments, policyRoles } from './policy-schema.js';
+import { isCustomRoleKey } from './role-keys.js';
+import { invitations } from './schema.js';
+import { done, refused, tenantTag } from './types.js';
+export async function roleDef(tx, binding, tenant, key) {
+    const [row] = await tx
+        .select()
+        .from(policyRoles)
+        .where(and(eq(policyRoles.tenantId, tenant.id), eq(policyRoles.applicationId, binding.applicationId), eq(policyRoles.platformId, binding.platformId), eq(policyRoles.key, key)))
+        .limit(1);
+    return row ? policyRole(row) : null;
+}
+export async function assignableRoles(access) {
+    return access.policyState.roleRows
+        .map(policyRole)
+        .filter((role) => role.key !== 'self_service')
+        .filter((role) => !roleAssignmentRefusal(access, role, primaryAssignment(role, { id: 'prospective-person', class: 'human' }), 'members:grant'));
+}
+export async function rolesForEditor(access) {
+    if (!permits(access, 'roles:read') || access.context === 'break_glass')
+        return [];
+    return access.policyState.roleRows.map(policyRole).map((role) => ({
+        ...role,
+        custom: !role.builtIn,
+        editable: !role.builtIn && permits(access, 'roles:update') && canEditDefinition(access, role),
+    }));
+}
+/** Definition edits must cover both its full scope and every existing recipient/scope. */
+export function canEditDefinition(access, role) {
+    if (roleAssignmentRefusal(access, role, primaryAssignment(role, { id: 'prospective-person', class: 'human' }), null))
+        return false;
+    return access.policyState.assignmentRows
+        .filter((a) => a.roleId === role.id && (!a.expiresAt || a.expiresAt.getTime() > Date.now()))
+        .every((a) => !roleAssignmentRefusal(access, role, policyAssignment(a), null));
+}
+const invalid = () => refused('invalid_role', 'Choose valid operations, boundaries and scopes within your authority.');
+export async function createRole(access, db, scopeColumn, options) {
+    if (access.context === 'break_glass')
+        return refused('break_glass', 'Support sessions cannot change access.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'roles:create'))
+            return refused('no_permission', 'You cannot create roles here.');
+        if (!/^c_[a-z0-9_-]{1,61}$/.test(options.key))
+            return refused('invalid_key', 'Choose a custom role key starting with c_.');
+        const candidate = resourceRoleSchema.safeParse({
+            id: randomUUID(),
+            key: options.key,
+            applicationId: fresh.binding.applicationId,
+            platformId: fresh.binding.platformId,
+            organisationId: fresh.tenant.id,
+            label: options.name,
+            description: options.description || options.name,
+            revision: 1,
+            builtIn: false,
+            entries: options.entries,
+            guards: [],
+        });
+        if (!candidate.success || !canEditDefinition(fresh, candidate.data))
+            return invalid();
+        if (fresh.policyState.roleRows.some((r) => r.key === options.key))
+            return refused('key_taken', 'A role with that key already exists.');
+        // Not `!r.builtIn`: a starter role (ADR 0016) is `built_in: false` for a
+        // tenant created after that change, but it is not tenant-authored, and
+        // must not eat into the custom-role cap the way a real `c_*` role does.
+        if (fresh.policyState.roleRows.filter((r) => isCustomRoleKey(r.key)).length >=
+            core.roleKey.maxCustomPerTenant)
+            return refused('cap_reached', 'This organisation has reached its custom role limit.');
+        const role = candidate.data;
+        await tx.insert(policyRoles).values({
+            id: role.id,
+            tenantId: role.organisationId,
+            applicationId: fresh.binding.applicationId,
+            platformId: fresh.binding.platformId,
+            key: role.key,
+            name: role.label,
+            description: role.description,
+            revision: role.revision,
+            builtIn: false,
+            entries: role.entries,
+            guards: [],
+            createdBy: fresh.actor.id,
+        });
+        await record(tx, fresh, {
+            action: 'role.created',
+            tenantId: fresh.tenant.id,
+            targetType: 'role',
+            targetId: role.id,
+            after: role,
+        });
+        return done({ key: role.key }, [tenantTag(fresh.tenant.id)]);
+    });
+}
+export async function updateRole(access, db, scopeColumn, options) {
+    if (access.context === 'break_glass')
+        return refused('break_glass', 'Support sessions cannot change access.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'roles:update'))
+            return refused('no_permission', 'You cannot update roles here.');
+        const before = await roleDef(tx, fresh.binding, fresh.tenant, options.key);
+        if (!before)
+            return refused('unknown_role', 'This role no longer exists.');
+        if (before.builtIn)
+            return refused('built_in', 'Built-in roles are versioned application policy.');
+        if (before.revision !== options.revision)
+            return refused('stale_revision', 'This role changed. Reload it before saving.');
+        const parsed = resourceRoleSchema.safeParse({
+            ...before,
+            label: options.name ?? before.label,
+            description: options.description ?? before.description,
+            entries: options.entries ?? before.entries,
+            revision: before.revision + 1,
+        });
+        if (!parsed.success ||
+            !canEditDefinition(fresh, before) ||
+            !canEditDefinition(fresh, parsed.data))
+            return invalid();
+        const after = parsed.data;
+        await tx
+            .update(policyRoles)
+            .set({
+            name: after.label,
+            description: after.description,
+            entries: after.entries,
+            revision: after.revision,
+            updatedAt: new Date(),
+            // ADR 0016's Aged-and-Independent approver rule reads this to exclude
+            // an approver whose eligibility the requester granted by editing a
+            // role. `created_by` cannot tell an edit's actor apart from the role's
+            // original author, which is why drizzle/0014_activations.sql added the
+            // column. Left unwritten, the exclusion never fires: a NULL is
+            // distinct from every requester id.
+            updatedBy: fresh.actor.id,
+        })
+            .where(eq(policyRoles.id, after.id));
+        await record(tx, fresh, {
+            action: 'role.updated',
+            tenantId: fresh.tenant.id,
+            targetType: 'role',
+            targetId: after.id,
+            before,
+            after,
+        });
+        return done(undefined, [tenantTag(fresh.tenant.id)]);
+    });
+}
+export async function deleteRole(access, db, scopeColumn, options) {
+    if (access.context === 'break_glass')
+        return refused('break_glass', 'Support sessions cannot change access.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'roles:delete'))
+            return refused('no_permission', 'You cannot delete roles here.');
+        const role = await roleDef(tx, fresh.binding, fresh.tenant, options.key);
+        if (!role)
+            return refused('unknown_role', 'This role no longer exists.');
+        if (role.builtIn)
+            return refused('built_in', 'Built-in roles are versioned application policy.');
+        if (!canEditDefinition(fresh, role))
+            return invalid();
+        const [assignment] = await tx
+            .select({ id: policyAssignments.id })
+            .from(policyAssignments)
+            .where(eq(policyAssignments.roleId, role.id))
+            .limit(1);
+        const [invitation] = await tx
+            .select({ id: invitations.id })
+            .from(invitations)
+            .where(eq(invitations.roleId, role.id))
+            .limit(1);
+        if (assignment || invitation)
+            return refused('role_in_use', 'This role is referenced by assignments or invitation history.');
+        await tx.delete(policyRoles).where(eq(policyRoles.id, role.id));
+        await record(tx, fresh, {
+            action: 'role.deleted',
+            tenantId: fresh.tenant.id,
+            targetType: 'role',
+            targetId: role.id,
+            before: role,
+            after: null,
+        });
+        return done(undefined, [tenantTag(fresh.tenant.id)]);
+    });
+}

package/dist/schema.d.ts

@@ -1268,7 +1268,7 @@ export declare const credentials: import("drizzle-orm/pg-core").PgTableWithColum
             columnType: "PgText";
             data: string;
             driverParam: string;
-            notNull: true;
+            notNull: false;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
@@ -1295,6 +1295,23 @@ export declare const credentials: import("drizzle-orm/pg-core").PgTableWithColum
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        keysIssuedId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "keys_issued_id";
+            tableName: "credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         createdBy: import("drizzle-orm/pg-core").PgColumn<{
             name: "created_by";
             tableName: "credentials";

package/dist/schema.js

@@ -141,10 +141,17 @@ export const credentials = pgTable('credentials', {
     issuerId: text('issuer_id').notNull(),
     issuerClass: text('issuer_class').notNull(),
     name: text('name').notNull(),
-    secretHash: text('secret_hash').notNull().unique(),
+    // Nullable since 0004: a credential minted through `@wtfalch/keys/issued`
+    // carries no hash of its own here (its secret is checked against that
+    // package's own signed row instead); a pre-cutover row still has one.
+    secretHash: text('secret_hash').unique(),
     // The first characters of the secret's random half, kept in clear so a
     // list can tell one credential from another (0006). Not a secret.
     secretPrefix: text('secret_prefix'),
+    // The matching `keys_issued_credentials.id` (0004), so a revoke can
+    // revoke it there too. Null on a pre-cutover row and on every row
+    // `credential-secret.ts` still mints.
+    keysIssuedId: text('keys_issued_id'),
     createdBy: text('created_by'),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().default(sql `now()`),
     expiresAt: timestamp('expires_at', { withTimezone: true }),

package/dist/startup.d.ts

@@ -0,0 +1,57 @@
+import { type AuthzReporting } from './alerts.js';
+import type { StoreBinding } from './binding.js';
+import type { StorePolicy } from './policy.js';
+import type { DbOrTx } from './scoped.js';
+/**
+ * The authorisation checks a host runs once when its server starts, the
+ * store's half of Boule's own `src/lib/authz/startup.ts` (`src/instrumentation.ts`
+ * called `runStartupChecks()` with no arguments there; this version takes
+ * `db`, `policy`, `reporting` and `housekeeping` explicitly, the same split
+ * every other moved module makes).
+ *
+ * **One of these refuses to serve.** `checkSystemRoles` verifies the policy
+ * schema version and the built-in role revisions against the database. A v2
+ * binary in front of a database a maintenance migration has not converted,
+ * or the other way round, must not answer a single request, so the error is
+ * reported and rethrown.
+ *
+ * Boule's own version returned early with no `DATABASE_URL` (a public
+ * preview build with nothing to check). That check is dropped here: this
+ * function takes `db` as a required parameter, so a host that has no
+ * database to check simply does not call it, rather than this package
+ * inspecting `process.env` (which it never does, being framework-neutral)
+ * to decide the same thing for itself.
+ *
+ * **Nothing else does.** The orphaned-role-key scan lists membership and
+ * invitation rows naming a role this build cannot resolve, the shape a
+ * rollback leaves behind; those rows already resolve to nothing, so a
+ * failure here is a finding, never an outage. Findings go to `reporting`,
+ * and the daily alerts and the nightly drift check are registered on
+ * `housekeeping` at the end.
+ */
+export declare function runStartupChecks(db: DbOrTx, policy: StorePolicy, reporting: AuthzReporting, housekeeping: HousekeepingRegistry): Promise<void>;
+/**
+ * The structural subset of a host's housekeeping registry (Boule's own
+ * `@/lib/reporting/core`'s `housekeeping`) that `registerHousekeeping`
+ * calls: one job registration, run on a lease so two containers never both
+ * run the same tick at once.
+ */
+export interface HousekeepingRegistry {
+    register(job: {
+        name: string;
+        every: number;
+        lease: number;
+        retry: number;
+        run(ctx: {
+            db: DbOrTx;
+        }): Promise<void>;
+    }): void;
+}
+/**
+ * The four alerts daily and the drift check nightly, on the housekeeping
+ * tick: claimed with a row lock, so two containers never both run one, and
+ * reported through `reportAlert`, so a finding is a row in the host's event
+ * log. Idempotent to register, because `runStartupChecks` is called once per
+ * process and the registry keys on the name.
+ */
+export declare function registerHousekeeping(housekeeping: HousekeepingRegistry, binding: StoreBinding, reporting: AuthzReporting): void;

package/dist/startup.js

@@ -0,0 +1,113 @@
+import { reportAlert, runAlerts } from './alerts.js';
+import { checkSystemRoles, orphanedRoleKeys } from './boot.js';
+import { reconcileDerived } from './reconcile.js';
+/**
+ * The authorisation checks a host runs once when its server starts, the
+ * store's half of Boule's own `src/lib/authz/startup.ts` (`src/instrumentation.ts`
+ * called `runStartupChecks()` with no arguments there; this version takes
+ * `db`, `policy`, `reporting` and `housekeeping` explicitly, the same split
+ * every other moved module makes).
+ *
+ * **One of these refuses to serve.** `checkSystemRoles` verifies the policy
+ * schema version and the built-in role revisions against the database. A v2
+ * binary in front of a database a maintenance migration has not converted,
+ * or the other way round, must not answer a single request, so the error is
+ * reported and rethrown.
+ *
+ * Boule's own version returned early with no `DATABASE_URL` (a public
+ * preview build with nothing to check). That check is dropped here: this
+ * function takes `db` as a required parameter, so a host that has no
+ * database to check simply does not call it, rather than this package
+ * inspecting `process.env` (which it never does, being framework-neutral)
+ * to decide the same thing for itself.
+ *
+ * **Nothing else does.** The orphaned-role-key scan lists membership and
+ * invitation rows naming a role this build cannot resolve, the shape a
+ * rollback leaves behind; those rows already resolve to nothing, so a
+ * failure here is a finding, never an outage. Findings go to `reporting`,
+ * and the daily alerts and the nightly drift check are registered on
+ * `housekeeping` at the end.
+ */
+export async function runStartupChecks(db, policy, reporting, housekeeping) {
+    try {
+        const results = await checkSystemRoles(db, policy);
+        const updated = results.filter((r) => r.status === 'updated');
+        if (updated.length > 0) {
+            // Not an alert: a deploy changing a bundle is a thing somebody did on
+            // purpose, and the durable record is the `role.updated` row the check
+            // has already written. This line is for whoever is watching the
+            // deploy.
+            reporting.log.info({ roles: updated.map((r) => `${r.kind}/${r.roleKey}`) }, `authz: ${updated.length} system role bundle(s) changed and were recorded`);
+        }
+    }
+    catch (error) {
+        reporting.log.error({ err: error instanceof Error ? error.message : String(error) }, 'authz: the policy check refused this database; not serving');
+        reporting.captureError(error, { kind: 'authz-v2-policy' });
+        throw error;
+    }
+    try {
+        const orphans = await orphanedRoleKeys(db, policy);
+        if (orphans.length > 0) {
+            reportAlert(reporting, {
+                check: 'orphaned_role_keys',
+                message: `${orphans.length} membership or invitation row(s) name a role this build does not know.`,
+                detail: orphans,
+            });
+        }
+    }
+    catch (error) {
+        reporting.log.error({ err: error instanceof Error ? error.message : String(error) }, 'authz: the orphaned role key scan failed');
+        reporting.alert({
+            check: 'orphaned_role_keys_scan_failed',
+            message: 'the orphaned role key scan failed; the error is in the container log',
+        });
+    }
+    registerHousekeeping(housekeeping, policy, reporting);
+}
+const DAY = 24 * 60 * 60 * 1000;
+/**
+ * The four alerts daily and the drift check nightly, on the housekeeping
+ * tick: claimed with a row lock, so two containers never both run one, and
+ * reported through `reportAlert`, so a finding is a row in the host's event
+ * log. Idempotent to register, because `runStartupChecks` is called once per
+ * process and the registry keys on the name.
+ */
+export function registerHousekeeping(housekeeping, binding, reporting) {
+    housekeeping.register({
+        name: 'authz.alerts',
+        every: DAY,
+        lease: 5 * 60 * 1000,
+        retry: 60 * 60 * 1000,
+        async run(ctx) {
+            // `runAlerts` reports each finding itself; the event here is the run.
+            const findings = await runAlerts(ctx.db, binding, reporting);
+            reporting.event({
+                kind: 'authz.alerts_ran',
+                message: `${findings.length} alert(s) fired`,
+                data: { findings: findings.length },
+            });
+        },
+    });
+    housekeeping.register({
+        name: 'authz.reconcile',
+        every: DAY,
+        lease: 10 * 60 * 1000,
+        retry: 60 * 60 * 1000,
+        async run(ctx) {
+            const report = await reconcileDerived(ctx.db, binding);
+            const drift = report.orphans.length + report.missing.length + report.wrongRole.length;
+            reporting.event({
+                kind: 'authz.reconciled',
+                level: drift > 0 ? 'warn' : 'info',
+                message: drift > 0
+                    ? `derived memberships drifted: ${drift} row(s)`
+                    : 'derived memberships agree with the tenant tree',
+                data: {
+                    orphans: report.orphans.length,
+                    missing: report.missing.length,
+                    wrongRole: report.wrongRole.length,
+                },
+            });
+        },
+    });
+}

package/dist/tenants.d.ts

@@ -0,0 +1,213 @@
+import type { TenantKind, TenantState } from '@wtfalch/authz';
+import type { OwnerActivityLookup } from './install-owner.js';
+import type { StorePolicy } from './policy.js';
+import { type Tenant } from './schema.js';
+import type { DbOrTx, Scope } from './scoped.js';
+import { type Access, type Principal, type Result } from './types.js';
+/** Who may create a new tenant, mirroring Boule's own `TenantCreation` (`config.ts`). */
+export type TenantCreationMode = 'anyone' | 'operator' | 'off';
+export interface CreateTenantConfig {
+    /** The host's own `TENANT_CREATION` (decision 3: no longer a package constant). */
+    readonly creation: TenantCreationMode;
+    /** The host's own `TENANT_CREATION_CAP_PER_DAY`. */
+    readonly capPerDay: number;
+}
+export interface CreateTenantOptions {
+    readonly name: string;
+    readonly slug: string;
+}
+/**
+ * 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 declare function createTenant(principal: Principal, db: DbOrTx, policy: StorePolicy, config: CreateTenantConfig, profiles: Pick<OwnerActivityLookup, 'personKnown'>, options: CreateTenantOptions): Promise<Result<{
+    id: string;
+}>>;
+export interface RenameTenantOptions {
+    readonly name?: string;
+    readonly slug?: string;
+}
+/** Renames or re-slugs a tenant, keeping `memberships.tenant_name` in step (D5) when the name changes. */
+export declare function renameTenant(access: Access, db: DbOrTx, scopeColumn: Scope['column'], options: RenameTenantOptions): Promise<Result<void>>;
+/**
+ * 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 declare function setSelfDenied(access: Access, db: DbOrTx, scopeColumn: Scope['column'], policy: Pick<StorePolicy, 'defaultCeiling' | 'offered'>, list: readonly string[]): Promise<Result<void>>;
+export interface SetTenantStateOptions {
+    /**
+     * Apply the same state to every descendant in the same transaction,
+     * writing one event per tenant actually changed (D19's fourth rule).
+     * Without it, tenant state stays per tenant: a suspended parent does not
+     * suspend its children, because the reasons differ.
+     */
+    readonly cascade?: boolean;
+}
+/**
+ * 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 declare function setTenantState(operatorAccess: Access, db: DbOrTx, scopeColumn: Scope['column'], tenantId: string, state: TenantState, options?: SetTenantStateOptions): Promise<Result<void>>;
+/**
+ * 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 declare function setCeiling(access: Access, db: DbOrTx, scopeColumn: Scope['column'], policy: Pick<StorePolicy, 'defaultCeiling' | 'offered'>, tenantId: string, list: readonly string[]): Promise<Result<void>>;
+/** A tenant by id, or null. Takes whatever handle the caller already has open, raw or scoped-out. */
+export declare function tenantById(handle: DbOrTx, id: string): Promise<Tenant | null>;
+/** A tenant by slug, or null. Used to resolve `/org/<slug>` before a membership is known. */
+export declare function tenantBySlug(handle: DbOrTx, slug: string): Promise<Tenant | null>;
+/** One row of the operator console's tenant list. */
+export interface TenantSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly kind: TenantKind;
+    readonly state: TenantState;
+    readonly parentId: string | null;
+    readonly ceiling: readonly string[];
+    readonly selfDenied: readonly string[];
+}
+export interface AllTenantsPage {
+    readonly items: readonly TenantSummary[];
+    readonly next: {
+        readonly name: string;
+        readonly id: string;
+    } | 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 declare function allTenants(access: Access, db: DbOrTx, options?: {
+    readonly q?: string;
+    readonly after?: {
+        name: string;
+        id: string;
+    };
+    readonly limit?: number;
+}): Promise<AllTenantsPage | null>;
+export interface CreateTenantAsOperatorOptions {
+    readonly name: string;
+    readonly slug: string;
+    readonly ownerEmail: string;
+    /**
+     * Born attached (D10, D19): the tenant is created standalone
+     * (`parent_id` null) and this parent is written onto the pending owner
+     * invitation instead. The attachment itself happens when the first owner
+     * accepts, in the same transaction as their membership; that branch is
+     * `acceptInvitation`'s (the propagation agent's), not this function's.
+     */
+    readonly attachTo?: string;
+    /** The host's own acceptance route (wave 8's decision 3, the same shape `invite` takes): the store never hard-codes one. */
+    readonly link: (token: string) => string;
+}
+export interface CreateTenantAsOperatorResult {
+    readonly id: string;
+    readonly token: string;
+    readonly link: string;
+}
+/**
+ * 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 declare function createTenantAsOperator(operatorAccess: Access, db: DbOrTx, scopeColumn: Scope['column'], policy: StorePolicy, options: CreateTenantAsOperatorOptions): Promise<Result<CreateTenantAsOperatorResult>>;
+/**
+ * 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 declare function deleteJustCreatedTenant(operatorAccess: Access, db: DbOrTx, scopeColumn: Scope['column'], tenantId: string): Promise<Result<void>>;
+/**
+ * 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 declare function archiveTenant(access: Access, db: DbOrTx, scopeColumn: Scope['column']): Promise<Result<void>>;