@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/activations.js

@@ -0,0 +1,516 @@
+import { randomUUID } from 'node:crypto';
+import { and, eq, gt, isNull, lte, ne, or, sql } from 'drizzle-orm';
+import { primaryAssignment, roleAssignmentRefusal } from './assignments.js';
+import { refreshAccess } from './policy-access.js';
+import { policyActivationApprovals, policyActivations, policyAssignments, policyRoles, } from './policy-schema.js';
+import { done, isUuid, refused, tenantTag } from './types.js';
+/**
+ * ADR 0016 ("No standing authority"), moved from Boule's own
+ * `src/lib/authz/activations.ts` (694 lines, authz#83 wave 11b):
+ * `needsCoApproval`, `requestActivation`, `approveActivation`,
+ * `selfApproveActivation` and `endActivation`. A human principal's time-boxed
+ * request to exercise a subset of the elevated permissions they are
+ * otherwise only *eligible* for. `requestActivation` mints a non-primary,
+ * non-built-in `authz_roles` row holding exactly the requested entries plus
+ * a matching `authz_activations` row (`break-glass.ts`'s `role_id`
+ * indirection, reused). An activation naming none of the catalogue's
+ * `coApproval` permissions takes effect immediately; one naming any of them
+ * waits on `approveActivation` (a second, Aged-and-Independent person) or
+ * `selfApproveActivation` (the requester alone, after 24 hours, only when no
+ * such second person exists) before the shared `activate` step writes the
+ * assignment that actually grants it (`source: 'direct'`, not `'activation'`
+ * as the ADR names it -- see `activate`'s own comment).
+ *
+ * `db` and `scopeColumn` are explicit parameters, the same as every other
+ * moved write module (wave 5a onward). `APPLICATION_ID`/`PLATFORM_ID`/
+ * `catalogue` come off `access.binding`, also the same as every other
+ * module. `elevated` and `requiresCoApproval` cannot: they are ADR 0016
+ * sets, not part of `StoreBinding`, only of `StorePolicy` -- so every
+ * function here that needs one takes `policy: Pick<StorePolicy, ...>`
+ * explicitly (the same shape wave 6's `proposeAttach`/`acceptAttach` and
+ * wave 9a's tenant writes take theirs). Unlike Boule's own module-level
+ * `ELEVATED`/`CO_APPROVAL` constants, `StorePolicy.elevated` and
+ * `.requiresCoApproval` are already typed `ReadonlySet<string>` (`policy.ts`),
+ * so no widening cast off a package `ReadonlySet<Permission>` is needed here.
+ *
+ * Boule's `requestActivation`/`approveActivation`/`selfApproveActivation`
+ * each ran their own `select ... from tenants ... for update` right after
+ * calling `refreshAccess`, purely to serialise against a concurrent write on
+ * the same tenant (no column from that row is read). The store's own
+ * `refreshAccess` (`policy-access.ts`) already does exactly that lock
+ * inside itself before it loads access, so repeating it here would lock the
+ * same row twice in one transaction for no reason; it is dropped, the same
+ * way every other wave 9+ module leans on `refreshAccess`'s own lock rather
+ * than re-taking it. The activation row's own `for('update')` in `approve`/
+ * `selfApprove`/`end` stays: that locks a different row, the one the rest of
+ * the function goes on to read and change.
+ *
+ * No audit event is written anywhere in this file, kept exactly as Boule
+ * had it. Boule's own comment ties this to its installed `@wtfalch/authz`
+ * (0.10.0, unpublished #33) not yet typing `EventName` for
+ * `activation.requested`/`.approved`/`.denied`/`.started`/`.expired`/
+ * `.revoked`, and `authz_events_action_check` not yet accepting them either.
+ * Neither limitation holds in this package: it pins
+ * `@wtfalch/authz workspace:^0.16.0`, and `0001_baseline.sql`'s
+ * `authz_events_action_check` already lists all six names (from Boule's own
+ * `drizzle/0020_activation_events.sql`, folded into the baseline before this
+ * wave). Turning the writes on is nonetheless a behaviour change a plain
+ * move should not make on its own judgement, so every place a real release
+ * would write one still only says so in a comment naming the event, the
+ * same as Boule; `activation.expired` has no such comment because it is
+ * never written at all -- expiry is read lazily off `expires_at`, the same
+ * way `break-glass.ts`'s own `activeSession` never mutates a row just
+ * because it is now in the past. See this wave's report.
+ */
+// No package constant exists for this (unlike break-glass.ts's
+// `core.breakGlass.maxMinutes`): the ADR calls an activation "a working
+// session," not a fixed ceiling -- Boule's own choice, the same way
+// break-glass.ts's own `MAX_REFERENCE` stays a fixed module constant here
+// too rather than becoming a per-host option.
+const MIN_MINUTES = 1;
+const DEFAULT_MINUTES = 60;
+const MAX_MINUTES = 8 * 60;
+// Matches authz_activations_reason_check / _reference_check (migrations/0005_activations.sql).
+const MIN_TEXT = 1;
+const MAX_TEXT = 512;
+// Matches authz_activations_permissions_check (migrations/0005_activations.sql).
+const MAX_PERMISSIONS = 100;
+// ADR: "established at least 24 hours before the activation's requested_at".
+const AGED_MS = 24 * 60 * 60 * 1000;
+// ADR: "refuses until Date.now() - requestedAt >= 24h (a named constant,
+// mirroring DEFAULT_PERIOD_DAYS)" (install-owner.ts).
+const SELF_APPROVE_WAIT_MS = 24 * 60 * 60 * 1000;
+/**
+ * True for a standing assignment -- one whose role was not minted for an
+ * activation. The ADR tells these apart by `source: 'activation'`, but the
+ * deployed `authz_assignments` CHECK only allows `source IN ('direct',
+ * 'inherited', 'activation')` while nothing here actually writes the third
+ * value (see `activate`'s own comment) -- so this correlates by `roleId`
+ * against `authz_activations` instead: an activation's role is minted
+ * fresh, once, and referenced by nothing else.
+ */
+const STANDING = sql `not exists (select 1 from authz_activations act where act.role_id = ${policyAssignments.roleId})`;
+/** Whether a requested set of permissions needs a second approver at all (ADR 0016). */
+export function needsCoApproval(permissions, policy) {
+    return permissions.some((p) => policy.requiresCoApproval.has(p));
+}
+/** Every entry's boundary must match the permission's own declared boundary (`platform.tenants:ceiling`, `people:erase` and a few others are platform-boundary; the rest are organisation-boundary), the same distinction `builtInRoles()` reads off each template entry. */
+function entryBoundary(catalogue, permission, tenantId) {
+    const boundaries = catalogue[permission]?.boundaries ?? [];
+    return boundaries[0] === 'platform'
+        ? { kind: 'platform' }
+        : { kind: 'organisation', organisationId: tenantId };
+}
+/**
+ * The elevated permissions this principal is currently eligible for, across
+ * every standing (non-activation) assignment they hold directly -- "not
+ * limited to one starter role" (ADR). Reads `entries` directly rather than
+ * calling `compileRoleGrants`: eligibility only needs to know a permission is
+ * *named*, not perform a full grant compile, and a standing custom role can
+ * never contain a non-assignable permission in the first place (creating one
+ * would already have failed `roleAssignmentRefusal`), so nothing here can
+ * throw the way minting a fresh role below can.
+ */
+async function eligibleElevatedPermissions(tx, binding, tenantId, elevated, principal) {
+    const rows = await tx
+        .select({ entries: policyRoles.entries })
+        .from(policyAssignments)
+        .innerJoin(policyRoles, eq(policyAssignments.roleId, policyRoles.id))
+        .where(and(eq(policyAssignments.tenantId, tenantId), eq(policyAssignments.applicationId, binding.applicationId), eq(policyAssignments.platformId, binding.platformId), eq(policyAssignments.principalId, principal.id), eq(policyAssignments.principalClass, principal.class), STANDING, or(isNull(policyAssignments.expiresAt), gt(policyAssignments.expiresAt, sql `now()`))));
+    const held = new Set();
+    for (const row of rows) {
+        for (const entry of row.entries) {
+            if (elevated.has(entry.permission))
+                held.add(entry.permission);
+        }
+    }
+    return held;
+}
+/**
+ * Human principals who count as an Aged-and-Independent approver for at
+ * least one of `permissions` (ADR, "An approver must be aged and
+ * independent, or the solo path manufactures one"): eligible through a
+ * standing assignment whose covering role names the permission, that
+ * eligibility established at least 24 hours before `requestedAt`, and not
+ * traceable to `requesterId` either as the assignment's grantor or as the
+ * role's own last editor -- checked with no time limit on that second part.
+ * Shared by `approveActivation` (is this approver in the pool?) and
+ * `selfApproveActivation` (is the pool, excluding the requester, empty?).
+ */
+async function eligibleApprovers(tx, binding, tenantId, permissions, requesterId, requestedAt) {
+    const cutoff = new Date(requestedAt.getTime() - AGED_MS);
+    const namesOneOf = or(...permissions.map((permission) => sql `exists (select 1 from jsonb_array_elements(${policyRoles.entries}) e where e->>'permission' = ${permission})`));
+    if (!namesOneOf)
+        return [];
+    const rows = await tx
+        .select({ principalId: policyAssignments.principalId })
+        .from(policyAssignments)
+        .innerJoin(policyRoles, eq(policyAssignments.roleId, policyRoles.id))
+        .where(and(eq(policyAssignments.tenantId, tenantId), eq(policyAssignments.applicationId, binding.applicationId), eq(policyAssignments.platformId, binding.platformId), eq(policyAssignments.principalClass, 'human'), STANDING, ne(policyAssignments.principalId, requesterId), or(isNull(policyAssignments.expiresAt), gt(policyAssignments.expiresAt, sql `now()`)), lte(policyAssignments.createdAt, cutoff), lte(policyRoles.updatedAt, cutoff), sql `${policyAssignments.createdBy} is distinct from ${requesterId}`, sql `${policyRoles.updatedBy} is distinct from ${requesterId}`, namesOneOf));
+    return [...new Set(rows.map((r) => r.principalId).filter((id) => id !== null))];
+}
+/**
+ * Opens an activation. Every static check runs before the transaction, the
+ * same ordering `startBreakGlass` uses, so a malformed request never reaches
+ * the lock. `principalClass` is always `'human'`: agents and services cannot
+ * open one (no inbox for the self-approve-wait email, nothing eligible to
+ * approve on their behalf), and a credential is not a principal at all
+ * under D10.
+ */
+export async function requestActivation(access, db, scopeColumn, policy, options) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A support session never opens an activation.');
+    }
+    if (access.actor.class !== 'human') {
+        return refused('not_human', 'A credential, agent or service can never hold an activation.');
+    }
+    const permissions = [...new Set(options.permissions)];
+    if (permissions.length < 1 || permissions.length > MAX_PERMISSIONS) {
+        return refused('invalid_permissions', `Name between 1 and ${MAX_PERMISSIONS} permissions.`);
+    }
+    if (!permissions.every((p) => policy.elevated.has(p))) {
+        return refused('not_elevated', 'Every permission named must be one this app treats as elevated.');
+    }
+    if (options.reason.length < MIN_TEXT || options.reason.length > MAX_TEXT) {
+        return refused('invalid_reason', `The reason must be between ${MIN_TEXT} and ${MAX_TEXT} characters.`);
+    }
+    if (options.reference.length < MIN_TEXT || options.reference.length > MAX_TEXT) {
+        return refused('invalid_reference', `The reference must be between ${MIN_TEXT} and ${MAX_TEXT} characters.`);
+    }
+    const minutes = options.minutes ?? DEFAULT_MINUTES;
+    if (!Number.isInteger(minutes) || minutes < MIN_MINUTES || minutes > MAX_MINUTES) {
+        return refused('invalid_minutes', `An activation lasts between ${MIN_MINUTES} and ${MAX_MINUTES} minutes.`);
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.actor.class !== 'human') {
+            return refused('no_permission', 'Your authority changed.');
+        }
+        const eligible = await eligibleElevatedPermissions(tx, fresh.binding, fresh.tenant.id, policy.elevated, { id: fresh.actor.id, class: fresh.actor.class });
+        if (!permissions.every((p) => eligible.has(p))) {
+            return refused('not_eligible', 'You are not eligible for every permission requested.');
+        }
+        const roleId = randomUUID();
+        const entries = permissions.map((permission) => ({
+            permission,
+            boundary: entryBoundary(fresh.binding.catalogue, permission, fresh.tenant.id),
+            scope: { kind: 'organisation' },
+            relation: 'any',
+        }));
+        const role = {
+            id: roleId,
+            key: `activation_${roleId}`,
+            applicationId: fresh.binding.applicationId,
+            platformId: fresh.binding.platformId,
+            organisationId: fresh.tenant.id,
+            label: `Activation ${roleId.slice(0, 8)}`,
+            description: options.reason,
+            revision: 1,
+            builtIn: false,
+            guards: [],
+            entries,
+        };
+        const expiresAt = new Date(Date.now() + minutes * 60_000);
+        const assignment = primaryAssignment(role, { id: fresh.actor.id, class: 'human' }, expiresAt.getTime());
+        // Name-level eligibility is not enough. `eligibleElevatedPermissions`
+        // only asks whether a standing role NAMES the permission; the entries
+        // minted above are always organisation-scoped with `relation: 'any'`.
+        // A person eligible through a team-scoped `teams:update` would otherwise
+        // activate an organisation-wide one -- an escalation, and one that needs
+        // no approval, since `teams:update` is not a coApproval permission.
+        // `roleAssignmentRefusal` is the check the rest of the module already
+        // uses for exactly this: with no operation to check it compiles the role
+        // and requires the actor's own authority to cover every grant
+        // (`canDelegate`, which does scope and relation containment). It also
+        // subsumes the compile: an uncompilable role comes back `invalid_role`,
+        // and minting one would crash every later access check on this tenant,
+        // because `loadPolicyState` compiles every assignment row unconditionally.
+        const refusal = roleAssignmentRefusal(fresh, role, assignment, null);
+        if (refusal === 'not_covered') {
+            return refused('not_eligible', 'This activation would grant more than your standing access covers.');
+        }
+        if (refusal !== null) {
+            // compileRoleGrants throws for any entry whose permission is
+            // `assignable: false` on a non-built-in role -- see Boule's own
+            // comment (activations.ts): every coApproval permission was one of
+            // these on the package version this file was ported from, so none of
+            // them could be minted into an activation's role either.
+            return refused('invalid_role', 'One or more of these permissions cannot yet be granted through a time-boxed activation.');
+        }
+        await tx.insert(policyRoles).values({
+            id: role.id,
+            tenantId: fresh.tenant.id,
+            applicationId: fresh.binding.applicationId,
+            platformId: fresh.binding.platformId,
+            key: role.key,
+            name: role.label,
+            description: role.description,
+            entries: role.entries,
+            guards: [],
+            revision: 1,
+            builtIn: false,
+            createdBy: fresh.actor.id,
+        });
+        const [row] = await tx
+            .insert(policyActivations)
+            .values({
+            tenantId: fresh.tenant.id,
+            applicationId: fresh.binding.applicationId,
+            platformId: fresh.binding.platformId,
+            principalId: fresh.actor.id,
+            principalClass: 'human',
+            permissions,
+            reason: options.reason,
+            reference: options.reference,
+            status: 'pending',
+            startsAt: new Date(),
+            expiresAt,
+            roleId: role.id,
+        })
+            .returning();
+        if (!row)
+            throw new Error('requestActivation: no row returned from the insert');
+        if (!needsCoApproval(permissions, policy)) {
+            // event: `activation.requested` immediately followed by
+            // `activation.started` -- no coApproval permission named, so it takes
+            // effect the moment it is minted.
+            await activate(tx, fresh.binding, row);
+            return done({ id: row.id, status: 'active', expiresAt: row.expiresAt }, [
+                tenantTag(fresh.tenant.id),
+            ]);
+        }
+        // event: `activation.requested` -- emailed to every Aged-and-Independent
+        // eligible approver here, whether zero, one or several exist (ADR: "the
+        // same email the self-approve-wait subsection describes below, sent
+        // once ... not only in the solo case").
+        return done({ id: row.id, status: 'pending', expiresAt: row.expiresAt }, [
+            tenantTag(fresh.tenant.id),
+        ]);
+    });
+}
+/**
+ * Writes the standing-looking assignment that actually grants it, and flips
+ * the row to 'active'. The one place either happens, called once an
+ * activation needs no more decisions.
+ *
+ * The ADR calls this a `source: 'activation'` row. Boule's own comment
+ * explains why its copy instead wrote `source: 'direct'`: its deployed
+ * `authz_assignments` CHECK did not accept `'activation'` and "additive
+ * only, no new migration" ruled out widening it there. This package's own
+ * baseline CHECK (`0001_baseline.sql`'s `authz_assignments_source_check`)
+ * already accepts `'activation'` -- but turning the value on is, the same
+ * as the event-writing decision above this file's header explains, a
+ * behaviour change this move does not make on its own judgement. `'direct'`
+ * is kept, exactly as Boule wrote it. The row is still told apart from an
+ * ordinary grant by `roleId`: this activation's role is minted fresh, once,
+ * and referenced by nothing else (`endActivation` and the eligibility
+ * queries above both key off exactly that).
+ */
+async function activate(tx, binding, activation) {
+    await tx.insert(policyAssignments).values({
+        tenantId: activation.tenantId,
+        applicationId: binding.applicationId,
+        platformId: binding.platformId,
+        roleId: activation.roleId,
+        principalId: activation.principalId,
+        principalClass: activation.principalClass,
+        // Matches writePrimaryAssignment's own primaryAssignment(): the
+        // assignment's own boundary stays the widest ('platform'), and each
+        // entry's own boundary narrows it on compile.
+        boundary: { kind: 'platform' },
+        scope: { kind: 'organisation' },
+        primary: false,
+        source: 'direct',
+        expiresAt: activation.expiresAt,
+        createdBy: activation.principalId,
+    });
+    // event: `activation.started` belongs here -- approved by a second person,
+    // or by the sole eligible requester after the wait, or needing no
+    // approval at all.
+    await tx
+        .update(policyActivations)
+        .set({ status: 'active' })
+        .where(eq(policyActivations.id, activation.id));
+}
+/**
+ * A second person's decision on someone else's pending activation. Refuses
+ * a same-principal row unconditionally, in every branch -- there is no path
+ * here that lets a requester sign their own activation; that is
+ * `selfApproveActivation`, a different action (ADR, "The two-person
+ * approval is Boule's own check").
+ */
+export async function approveActivation(access, db, scopeColumn, policy, options) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A support session never approves an activation.');
+    }
+    if (access.actor.class !== 'human') {
+        return refused('not_human', 'Only a person can approve an activation.');
+    }
+    if (!isUuid(options.activationId)) {
+        return refused('activation_not_found', 'This activation does not exist.');
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.actor.class !== 'human') {
+            return refused('no_permission', 'Your authority changed.');
+        }
+        const [activation] = await tx
+            .select()
+            .from(policyActivations)
+            .where(and(eq(policyActivations.id, options.activationId), eq(policyActivations.tenantId, fresh.tenant.id), eq(policyActivations.applicationId, fresh.binding.applicationId), eq(policyActivations.platformId, fresh.binding.platformId)))
+            .for('update');
+        if (!activation)
+            return refused('activation_not_found', 'This activation does not exist.');
+        if (activation.status !== 'pending') {
+            return refused('not_pending', 'This activation is no longer waiting on a decision.');
+        }
+        if (activation.principalId === fresh.actor.id &&
+            activation.principalClass === fresh.actor.class) {
+            return refused('self_approval', 'You cannot approve your own activation.');
+        }
+        const coApprovalPermissions = activation.permissions.filter((p) => policy.requiresCoApproval.has(p));
+        if (coApprovalPermissions.length === 0) {
+            // Invariant, not a refusal: nothing in this module ever leaves an
+            // activation 'pending' unless it names a coApproval permission (see
+            // requestActivation).
+            throw new Error('approveActivation: a pending activation with no coApproval permission');
+        }
+        const eligible = await eligibleApprovers(tx, fresh.binding, fresh.tenant.id, coApprovalPermissions, activation.principalId, activation.requestedAt);
+        if (!eligible.includes(fresh.actor.id)) {
+            return refused('not_established', 'You are not yet an established, independent approver for this request.');
+        }
+        await tx.insert(policyActivationApprovals).values({
+            activationId: activation.id,
+            approverId: fresh.actor.id,
+            approverClass: 'human',
+            decision: options.decision,
+            reason: options.reason ?? null,
+        });
+        if (options.decision === 'denied') {
+            // event: `activation.denied` belongs here.
+            await tx
+                .update(policyActivations)
+                .set({ status: 'denied', endedAt: sql `now()`, endedBy: fresh.actor.id })
+                .where(eq(policyActivations.id, activation.id));
+            return done({ status: 'denied' }, [tenantTag(fresh.tenant.id)]);
+        }
+        // event: `activation.approved` immediately followed by
+        // `activation.started` belongs here -- one independent, established
+        // approval is the "second person" D11 asks for.
+        await activate(tx, fresh.binding, activation);
+        return done({ status: 'active' }, [tenantTag(fresh.tenant.id)]);
+    });
+}
+/**
+ * The solo path: the requester approves their own activation once no
+ * Aged-and-Independent person besides them is eligible, and only after a
+ * 24-hour wait re-checked inside this locked transaction (ADR, "The
+ * self-approve wait, enforced lazily like everything else here"). A
+ * manufactured second account never counts toward "another eligible
+ * approver exists" here, because `eligibleApprovers` already excludes
+ * anyone whose eligibility traces back to this same requester.
+ */
+export async function selfApproveActivation(access, db, scopeColumn, policy, activationId) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A support session never self-approves an activation.');
+    }
+    if (access.actor.class !== 'human') {
+        return refused('not_human', 'Only a person can self-approve an activation.');
+    }
+    if (!isUuid(activationId))
+        return refused('activation_not_found', 'This activation does not exist.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.actor.class !== 'human') {
+            return refused('no_permission', 'Your authority changed.');
+        }
+        const [activation] = await tx
+            .select()
+            .from(policyActivations)
+            .where(and(eq(policyActivations.id, activationId), eq(policyActivations.tenantId, fresh.tenant.id), eq(policyActivations.applicationId, fresh.binding.applicationId), eq(policyActivations.platformId, fresh.binding.platformId)))
+            .for('update');
+        if (!activation)
+            return refused('activation_not_found', 'This activation does not exist.');
+        if (activation.status !== 'pending') {
+            return refused('not_pending', 'This activation is no longer waiting on a decision.');
+        }
+        if (activation.principalId !== fresh.actor.id ||
+            activation.principalClass !== fresh.actor.class) {
+            return refused('not_requester', 'Only the person who requested this may self-approve it.');
+        }
+        const coApprovalPermissions = activation.permissions.filter((p) => policy.requiresCoApproval.has(p));
+        if (coApprovalPermissions.length === 0) {
+            throw new Error('selfApproveActivation: a pending activation with no coApproval permission');
+        }
+        const others = await eligibleApprovers(tx, fresh.binding, fresh.tenant.id, coApprovalPermissions, activation.principalId, activation.requestedAt);
+        if (others.length > 0) {
+            return refused('approver_available', 'Another established, independent approver exists; ask them to approve instead.');
+        }
+        if (Date.now() - activation.requestedAt.getTime() < SELF_APPROVE_WAIT_MS) {
+            return refused('too_soon', 'Self-approval is available 24 hours after the request.');
+        }
+        await tx.insert(policyActivationApprovals).values({
+            activationId: activation.id,
+            approverId: fresh.actor.id,
+            approverClass: 'human',
+            decision: 'approved',
+            reason: 'Self-approved: no other eligible approver exists after the 24-hour wait.',
+        });
+        // event: `activation.approved` (self) immediately followed by
+        // `activation.started` belongs here.
+        await activate(tx, fresh.binding, activation);
+        return done({ status: 'active' }, [tenantTag(fresh.tenant.id)]);
+    });
+}
+/**
+ * Ends one's own activation, pending or active -- a safety valve, not a
+ * power, the same framing `endBreakGlass` gives ending your own session.
+ * The ADR names no permission for ending someone *else's* (unlike
+ * `break_glass:end-any`), so that branch does not exist here; see this
+ * wave's report.
+ */
+export async function endActivation(access, db, scopeColumn, activationId) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A support session never ends an activation.');
+    }
+    if (!isUuid(activationId))
+        return refused('activation_not_found', 'This activation does not exist.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh)
+            return refused('no_permission', 'Your authority changed.');
+        const [activation] = await tx
+            .select()
+            .from(policyActivations)
+            .where(and(eq(policyActivations.id, activationId), eq(policyActivations.tenantId, fresh.tenant.id), eq(policyActivations.applicationId, fresh.binding.applicationId), eq(policyActivations.platformId, fresh.binding.platformId)))
+            .for('update');
+        if (!activation ||
+            activation.endedAt ||
+            activation.status === 'denied' ||
+            activation.status === 'revoked') {
+            return refused('activation_not_found', 'This activation is not open.');
+        }
+        const isOwn = activation.principalId === fresh.actor.id && activation.principalClass === fresh.actor.class;
+        if (!isOwn)
+            return refused('no_permission', 'You can only end your own activation.');
+        // event: `activation.revoked` belongs here.
+        await tx
+            .update(policyActivations)
+            .set({ status: 'revoked', endedAt: sql `now()`, endedBy: fresh.actor.id })
+            .where(eq(policyActivations.id, activation.id));
+        if (activation.status === 'active') {
+            // Immediate effect, not lazy: an explicit end must remove the grant
+            // now, unlike natural expiry, which is already read lazily off
+            // `expires_at` wherever grants are compiled.
+            await tx
+                .update(policyAssignments)
+                .set({ expiresAt: sql `now()` })
+                .where(and(eq(policyAssignments.tenantId, fresh.tenant.id), eq(policyAssignments.applicationId, fresh.binding.applicationId), eq(policyAssignments.platformId, fresh.binding.platformId), 
+            // roleId alone identifies it: this activation's role is minted
+            // once and referenced by nothing else (see activate()'s comment
+            // on why `source` cannot mark it instead).
+            eq(policyAssignments.roleId, activation.roleId)));
+        }
+        return done(undefined, [tenantTag(fresh.tenant.id)]);
+    });
+}

package/dist/alerts.d.ts

@@ -0,0 +1,86 @@
+import type { StoreBinding } from './binding.js';
+import type { DbOrTx } from './scoped.js';
+/**
+ * D9's four alerts: "no dashboards; four alerts and a sink." Each check is
+ * pure over whatever handle and binding it is given (the same `DbOrTx`,
+ * `StoreBinding` shape `reconcile.ts` and `boot.ts` take), returns a
+ * described finding or `null` on a clean read, and never writes anything
+ * itself. `reportAlert` is the one place that reaches the sink: the host's
+ * own `AuthzReporting.alert`, an `alert.<check>` row in its event log (a
+ * structural port replacing Boule's `@/lib/reporting/core`'s `reporting`,
+ * since the store has no reporting package of its own to import).
+ *
+ * Nothing here is wired to a schedule; `startup.ts`'s `registerHousekeeping`
+ * is what a nightly job or a boot hook calls.
+ */
+export type AlertCheck = 'orphan_memberships' | 'stuck_invitations' | 'break_glass_burst' | 'orphaned_role_keys';
+export interface AlertFinding {
+    readonly check: AlertCheck;
+    readonly message: string;
+    readonly detail: unknown;
+}
+/**
+ * The structural subset of `@wtfalch/reporting` (checked against Boule's
+ * `@/lib/reporting/core`) that `alerts.ts` and `startup.ts` call. A host's
+ * real reporting binding satisfies this without change; nothing here is
+ * imported from the package itself, since the store has no dependency on it.
+ */
+export interface AuthzReporting {
+    alert(finding: {
+        check: string;
+        message: string;
+        detail?: unknown;
+    }): void;
+    event(e: {
+        kind: string;
+        message: string;
+        level?: 'info' | 'warn';
+        data?: Record<string, unknown>;
+    }): void;
+    log: {
+        info(obj: object, msg: string): void;
+        error(obj: object, msg: string): void;
+    };
+    captureError(error: unknown, context: Record<string, unknown>): void;
+}
+/** D9's first alert: D19's drift check found a row the tenant tree no longer calls for. */
+export declare function checkOrphanMemberships(handle: DbOrTx, binding: StoreBinding): Promise<AlertFinding | null>;
+/**
+ * D9's second alert: an invitation stuck with failed mail for more than an
+ * hour. `invitations` carries no separate "mail state last changed at"
+ * column beyond `mail_state_at` (0001), only `created_at` for a row that
+ * predates it, and a re-invite rotates the token on the same row rather than
+ * creating a new one (`invitations.ts`'s `resendInvitation` calls straight
+ * back through `invite`), so a resend that fails again does not reset this
+ * clock; that is a real gap in what this table can say and not something
+ * this check can paper over. `created_at` is what a pre-0001 row has, and
+ * for a row that has never once sent successfully (the common failure, a bad
+ * address or a mail provider outage) it is exactly the right clock: the
+ * invitation has been unusable since it was created.
+ *
+ * `binding` is unused here — see this module's header on why every check
+ * takes it.
+ */
+export declare function checkStuckInvitations(handle: DbOrTx, _binding: StoreBinding): Promise<AlertFinding | null>;
+/**
+ * D9's third alert: more than two break-glass sessions opened on one tenant
+ * in a rolling day, regardless of which operator opened them or whether any
+ * are still open.
+ *
+ * `binding` is unused here — see this module's header on why every check
+ * takes it.
+ */
+export declare function checkBreakGlassBurst(handle: DbOrTx, _binding: StoreBinding): Promise<AlertFinding | null>;
+/** D9's fourth alert: `boot.ts`'s `orphanedRoleKeys`, imported rather than reimplemented. */
+export declare function checkOrphanedRoleKeys(handle: DbOrTx, binding: StoreBinding): Promise<AlertFinding | null>;
+/**
+ * The one place a finding reaches the sink: the host's `reporting.alert`,
+ * one `alert.<check>` row in its event log, always.
+ */
+export declare function reportAlert(reporting: AuthzReporting, finding: AlertFinding): void;
+/**
+ * Runs all four checks against one handle and binding and reports whatever
+ * fired. What a nightly job or a boot hook calls; `startup.ts`'s
+ * `registerHousekeeping` is the only caller in this package.
+ */
+export declare function runAlerts(handle: DbOrTx, binding: StoreBinding, reporting: AuthzReporting): Promise<readonly AlertFinding[]>;