@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/boot.d.ts

@@ -0,0 +1,54 @@
+import type { TenantKind } from '@wtfalch/authz';
+import type { StoreBinding } from './binding.js';
+import type { StorePolicy } from './policy.js';
+import type { DbOrTx } from './scoped.js';
+export type SystemRoleCheckStatus = 'first_seen' | 'unchanged' | 'updated';
+export interface SystemRoleCheckResult {
+    readonly kind: TenantKind;
+    readonly roleKey: string;
+    readonly status: SystemRoleCheckStatus;
+}
+/**
+ * The exact string `ensureBuiltInRoles` compares a stored row against. Exported
+ * for a rollback test that pins what a released catalogue holds: a rollback runs
+ * the PREVIOUS release's copy of this function against rows the current one
+ * seeded, so the two must agree character for character.
+ */
+export declare const content: (role: {
+    entries: unknown;
+    guards: readonly string[];
+    label: string;
+    description: string;
+}) => string;
+/** Called in the tenant creation/deploy transaction while its tenant row is locked. */
+export declare function ensureBuiltInRoles(tx: DbOrTx, policy: StorePolicy, tenant: {
+    id: string;
+    kind: TenantKind;
+}): Promise<SystemRoleCheckResult[]>;
+/**
+ * The starter role set (ADR 0016): copied into a brand-new tenant exactly
+ * once, as ordinary rows nothing here resyncs afterward — unlike
+ * `ensureBuiltInRoles`, this never updates an existing row. Guarded by
+ * `onConflictDoNothing` on the same `(tenant, application, key)` uniqueness
+ * `ensureBuiltInRoles` relies on, so a caller may call it more than once for
+ * the same tenant (a retried transaction, or a tenant whose roles already
+ * exist from before this change shipped) without duplicating or throwing.
+ *
+ * Stored `built_in: true`, not the `false` `starterRoles()` itself declares,
+ * for the reasons the host's own boot.ts documents (`@wtfalch/authz`'s
+ * `compileRoleGrants` refuses a non-`assignable` entry unless the role is
+ * `built_in`, and today's owner/admin templates carry several).
+ */
+export declare function seedStarterRoles(tx: DbOrTx, policy: StorePolicy, tenant: {
+    id: string;
+    kind: TenantKind;
+}): Promise<void>;
+export declare function checkSystemRoles(handle: DbOrTx, policy: StorePolicy): Promise<readonly SystemRoleCheckResult[]>;
+export interface OrphanedRoleKey {
+    readonly source: 'membership' | 'invitation';
+    readonly tenantId: string;
+    readonly rowKey: string;
+    readonly roleKey: string;
+}
+/** Referential integrity rejects orphan roles at write time; boot also validates the policy version. */
+export declare function orphanedRoleKeys(handle: DbOrTx, binding: StoreBinding): Promise<readonly OrphanedRoleKey[]>;

package/dist/boot.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { and, eq } from 'drizzle-orm';
+import { writeServiceEvent } from './audit.js';
+import { policyRole, requirePolicySchema } from './policy-access.js';
+import { policyRoles } from './policy-schema.js';
+import { tenants } from './schema.js';
+/** JSONB changes object key order; compare policy content independently of serialization. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+            .join(',')}}`;
+    return JSON.stringify(value);
+}
+/**
+ * The exact string `ensureBuiltInRoles` compares a stored row against. Exported
+ * for a rollback test that pins what a released catalogue holds: a rollback runs
+ * the PREVIOUS release's copy of this function against rows the current one
+ * seeded, so the two must agree character for character.
+ */
+export const content = (role) => canonical({
+    entries: [...role.entries].map(canonical).sort(),
+    guards: [...role.guards].sort(),
+    label: role.label,
+    description: role.description,
+});
+/** Called in the tenant creation/deploy transaction while its tenant row is locked. */
+export async function ensureBuiltInRoles(tx, policy, tenant) {
+    const rows = await tx
+        .select()
+        .from(policyRoles)
+        .where(and(eq(policyRoles.tenantId, tenant.id), eq(policyRoles.applicationId, policy.applicationId), eq(policyRoles.platformId, policy.platformId)));
+    const result = [];
+    for (const template of policy.builtInRoles(tenant.id, tenant.kind)) {
+        const existing = rows.find((r) => r.key === template.key);
+        let status = 'unchanged';
+        if (existing) {
+            if (!existing.builtIn)
+                throw new Error(`Reserved role key collision: ${template.key}`);
+            if (existing.revision > template.revision)
+                throw new Error('Policy rollback requires a maintenance migration');
+            if (content(policyRole(existing)) !== content(template)) {
+                if (existing.revision === template.revision)
+                    throw new Error(`Built-in policy ${template.key} changed without a revision`);
+                await tx
+                    .update(policyRoles)
+                    .set({
+                    name: template.label,
+                    description: template.description,
+                    entries: template.entries,
+                    guards: template.guards,
+                    revision: template.revision,
+                    updatedAt: new Date(),
+                })
+                    .where(eq(policyRoles.id, existing.id));
+                await writeServiceEvent(tx, { id: 'deploy', display: 'deploy' }, {
+                    action: 'role.updated',
+                    tenantId: tenant.id,
+                    targetType: 'role',
+                    targetId: existing.id,
+                    context: tenant.kind === 'operator' ? 'operator' : 'standard',
+                    before: policyRole(existing),
+                    after: { id: existing.id, ...template },
+                });
+                status = 'updated';
+            }
+        }
+        else {
+            const id = randomUUID();
+            await tx.insert(policyRoles).values({
+                id,
+                tenantId: tenant.id,
+                applicationId: policy.applicationId,
+                platformId: policy.platformId,
+                key: template.key,
+                name: template.label,
+                description: template.description,
+                entries: template.entries,
+                guards: template.guards,
+                revision: template.revision,
+                builtIn: true,
+            });
+            status = 'first_seen';
+        }
+        result.push({ kind: tenant.kind, roleKey: template.key, status });
+    }
+    return result;
+}
+/**
+ * The starter role set (ADR 0016): copied into a brand-new tenant exactly
+ * once, as ordinary rows nothing here resyncs afterward — unlike
+ * `ensureBuiltInRoles`, this never updates an existing row. Guarded by
+ * `onConflictDoNothing` on the same `(tenant, application, key)` uniqueness
+ * `ensureBuiltInRoles` relies on, so a caller may call it more than once for
+ * the same tenant (a retried transaction, or a tenant whose roles already
+ * exist from before this change shipped) without duplicating or throwing.
+ *
+ * Stored `built_in: true`, not the `false` `starterRoles()` itself declares,
+ * for the reasons the host's own boot.ts documents (`@wtfalch/authz`'s
+ * `compileRoleGrants` refuses a non-`assignable` entry unless the role is
+ * `built_in`, and today's owner/admin templates carry several).
+ */
+export async function seedStarterRoles(tx, policy, tenant) {
+    const rows = policy.starterRoles(tenant.id, tenant.kind).map((template) => ({
+        id: randomUUID(),
+        tenantId: tenant.id,
+        applicationId: policy.applicationId,
+        platformId: policy.platformId,
+        key: template.key,
+        name: template.label,
+        description: template.description,
+        entries: template.entries,
+        guards: template.guards,
+        revision: template.revision,
+        builtIn: true,
+    }));
+    if (!rows.length)
+        return;
+    await tx
+        .insert(policyRoles)
+        .values(rows)
+        .onConflictDoNothing({
+        target: [policyRoles.tenantId, policyRoles.applicationId, policyRoles.key],
+    });
+}
+export async function checkSystemRoles(handle, policy) {
+    await requirePolicySchema(handle, policy);
+    return handle.transaction(async (tx) => {
+        const rows = await tx.select().from(tenants).orderBy(tenants.id).for('update');
+        const results = [];
+        for (const tenant of rows)
+            results.push(...(await ensureBuiltInRoles(tx, policy, tenant)));
+        return results;
+    });
+}
+/** Referential integrity rejects orphan roles at write time; boot also validates the policy version. */
+export async function orphanedRoleKeys(handle, binding) {
+    await requirePolicySchema(handle, binding);
+    return [];
+}

package/dist/bootstrap.d.ts

@@ -0,0 +1,28 @@
+import type { StorePolicy } from './policy.js';
+import type { DbOrTx } from './scoped.js';
+/**
+ * The first operator (D10, D12). A host resolves its own bootstrap subject
+ * (an environment variable naming a signed-in subject id, never an email: a
+ * subject id is what the issuer hands back on every sign-in, so there is no
+ * address to normalise or spoof) and passes it in as `options.subject`; this
+ * package reads no environment variable and imports no host's own auth
+ * package. `options.ensureProfile` is the host's own person-row write --
+ * `profiles` is the host's table, not the store's -- generic over the user
+ * type `U` so a host's own richer `User` flows straight through to its own
+ * `ensureProfile` without this function knowing its shape beyond `id`.
+ *
+ * Nothing in this function reaches for a request, a cookie or a session
+ * itself; it only ever acts on the `user` its caller already resolved, and
+ * on whether that user's id is the one `options.subject` names.
+ *
+ * Idempotent and inert once the operator tenant has a direct owner, and inert
+ * for anyone but the named subject, so leaving a host's own bootstrap
+ * variable set in the environment after first use is harmless: every later
+ * call is a fast no-op that changes nothing.
+ */
+export declare function bootstrapOperator<U extends {
+    id: string;
+}>(db: DbOrTx, policy: StorePolicy, user: U, options: {
+    readonly subject: string | undefined;
+    ensureProfile(user: U): Promise<void>;
+}): Promise<boolean>;

package/dist/bootstrap.js

@@ -0,0 +1,83 @@
+import { eq } from 'drizzle-orm';
+import { writeParticipationPolicy, writePrimaryAssignment } from './assignments.js';
+import { writeServiceEvent } from './audit.js';
+import { ensureBuiltInRoles, seedStarterRoles } from './boot.js';
+import { ownerCoverage } from './owners.js';
+import { roleDef } from './roles.js';
+import { memberships, tenants } from './schema.js';
+/**
+ * The first operator (D10, D12). A host resolves its own bootstrap subject
+ * (an environment variable naming a signed-in subject id, never an email: a
+ * subject id is what the issuer hands back on every sign-in, so there is no
+ * address to normalise or spoof) and passes it in as `options.subject`; this
+ * package reads no environment variable and imports no host's own auth
+ * package. `options.ensureProfile` is the host's own person-row write --
+ * `profiles` is the host's table, not the store's -- generic over the user
+ * type `U` so a host's own richer `User` flows straight through to its own
+ * `ensureProfile` without this function knowing its shape beyond `id`.
+ *
+ * Nothing in this function reaches for a request, a cookie or a session
+ * itself; it only ever acts on the `user` its caller already resolved, and
+ * on whether that user's id is the one `options.subject` names.
+ *
+ * Idempotent and inert once the operator tenant has a direct owner, and inert
+ * for anyone but the named subject, so leaving a host's own bootstrap
+ * variable set in the environment after first use is harmless: every later
+ * call is a fast no-op that changes nothing.
+ */
+export async function bootstrapOperator(db, policy, user, options) {
+    if (!options.subject || options.subject !== user.id)
+        return false;
+    // `ensureProfile` always writes through a host's own raw handle rather
+    // than taking a transaction parameter, so it cannot join the locked
+    // transaction below. It runs first, as its own statement: the tenant row
+    // lock below is what actually serialises two concurrent bootstrap attempts
+    // against each other (the owner count is read only after the lock is
+    // held), so the profile row existing a moment earlier changes nothing
+    // about that race.
+    await options.ensureProfile(user);
+    return db.transaction(async (tx) => {
+        const [operatorTenant] = await tx
+            .select({ id: tenants.id, name: tenants.name, kind: tenants.kind })
+            .from(tenants)
+            .where(eq(tenants.kind, 'operator'))
+            .for('update');
+        if (!operatorTenant) {
+            throw new Error('bootstrapOperator: no operator tenant found; has the store’s baseline migration run?');
+        }
+        if ((await ownerCoverage(tx, policy, operatorTenant.id)).directOwners > 0)
+            return false;
+        await ensureBuiltInRoles(tx, policy, operatorTenant);
+        await seedStarterRoles(tx, policy, operatorTenant);
+        const owner = await roleDef(tx, policy, operatorTenant, 'owner');
+        if (!owner)
+            throw new Error('Missing versioned owner policy');
+        const inserted = await tx
+            .insert(memberships)
+            .values({
+            tenantId: operatorTenant.id,
+            principalId: user.id,
+            principalClass: 'human',
+            source: 'direct',
+            tenantName: operatorTenant.name,
+            grantedBy: null,
+        })
+            .onConflictDoNothing()
+            .returning({ id: memberships.principalId });
+        await writePrimaryAssignment(tx, policy, owner, { id: user.id, class: 'human' });
+        if (inserted.length)
+            await writeParticipationPolicy(tx, policy, operatorTenant.id, {
+                id: user.id,
+                class: 'human',
+            });
+        await writeServiceEvent(tx, { id: 'bootstrap', display: 'bootstrap' }, {
+            action: 'operator.bootstrapped',
+            tenantId: operatorTenant.id,
+            targetType: 'membership',
+            targetId: user.id,
+            context: 'operator',
+            after: { principalId: user.id, role: 'owner' },
+        });
+        return true;
+    });
+}

package/dist/break-glass.d.ts

@@ -0,0 +1,61 @@
+import type { BreakGlassReason } from '@wtfalch/authz';
+import { type BreakGlassSession } from './schema.js';
+import type { DbOrTx, Scope } from './scoped.js';
+import type { Access, Result } from './types.js';
+export interface StartBreakGlassOptions {
+    readonly tenantId: string;
+    readonly reasonCode: BreakGlassReason;
+    readonly reference: string;
+    readonly minutes?: number;
+    readonly readOnly?: boolean;
+    /** Which customer-tenant role the session acts as. The target is always a customer tenant, never the operator one. */
+    readonly role?: string;
+}
+/**
+ * Opens a support session. Every check below runs before a row is written or
+ * a query touches the database that does not have to, so a malformed request
+ * never reaches the transaction that would otherwise lock the wrong tenant
+ * for no reason.
+ */
+export declare function startBreakGlass(operatorAccess: Access, db: DbOrTx, scopeColumn: Scope['column'], options: StartBreakGlassOptions): Promise<Result<{
+    id: string;
+    expiresAt: Date;
+}>>;
+/**
+ * Ends one session: the operator who holds it may always end their own, no
+ * matter what they hold now, because that is a safety valve, not a power;
+ * ending someone else's needs `break_glass:end-any`.
+ */
+export declare function endBreakGlass(operatorAccess: Access, db: DbOrTx, scopeColumn: Scope['column'], sessionId: string): Promise<Result<void>>;
+/**
+ * Force-ends every session one operator holds, inside whatever transaction
+ * the caller already has open: a host's own `memberships.ts` calls this the
+ * moment an operator-tenant membership is removed or changed to a role
+ * without `break_glass:start`, so a session never outlives the authority
+ * that opened it (M9). Written as the `service:authz` actor rather than
+ * through `record`, because there is no `Access` for the operator whose
+ * session this is inside a transaction that is busy ending their
+ * membership, not building one.
+ */
+export declare function endSessionsFor(tx: DbOrTx, operatorId: string, reason: string): Promise<void>;
+/**
+ * The session that would currently grant access, or null: not yet ended and
+ * not past its expiry. A host's own `access.ts` reads this to resolve a
+ * session `Access`, and `startBreakGlass` reads it to refuse a second
+ * session on top of one that is already live; an expired-but-unended row
+ * counts as gone for both.
+ */
+export declare function activeSession(tx: DbOrTx, operatorId: string, tenantId: string): Promise<BreakGlassSession | null>;
+export interface SessionsForOptions {
+    /** Every session on this tenant (its console page); omitted for the operator's own history instead. */
+    readonly tenantId?: string;
+}
+/**
+ * Sessions for the console: one tenant's history when `tenantId` is given,
+ * or the calling operator's own history otherwise. A page-rendering read
+ * with no transaction to join, the same as `assignableRoles`; the caller is
+ * expected to have already resolved `operatorAccess` through its own
+ * `requireOperator` with whatever permission its own page needs. `db` is the
+ * host's root handle, taken explicitly rather than imported.
+ */
+export declare function sessionsFor(operatorAccess: Access, db: DbOrTx, options?: SessionsForOptions): Promise<BreakGlassSession[]>;

package/dist/break-glass.js

@@ -0,0 +1,247 @@
+import { core } from '@wtfalch/authz';
+import { and, desc, eq, gt, isNull, sql } from 'drizzle-orm';
+import { record, writeServiceEvent } from './audit.js';
+import { permits, refreshAccess } from './policy-access.js';
+import { isCustomRoleKey } from './role-keys.js';
+import { roleDef } from './roles.js';
+import { breakGlassSessions, memberships, tenants } from './schema.js';
+import { done, isUuid, refused, tenantTag } from './types.js';
+/**
+ * An operator's time-boxed, reasoned, audited way into a tenant they do not
+ * belong to (D8). This is the one place a session is opened, ended or force-
+ * ended; `access.ts` (the host's own) reads the row this writes to build the
+ * `Access` a session resolves to, and every authority write in this module
+ * refuses a `break_glass` context outright, so nothing here can turn into a
+ * standing membership no matter how these functions are combined.
+ */
+const MIN_MINUTES = 1;
+const MAX_MINUTES = core.breakGlass.maxMinutes;
+const REASON_CODES = new Set(core.breakGlass.reasonCodes);
+const MIN_REFERENCE = 1;
+// Matches bg_reference_check in the migration; kept as a constant here
+// rather than read from the package, which has no field for it (the
+// invitation and break-glass row shapes differ enough that this is a
+// column limit on this table, not a vocabulary rule).
+const MAX_REFERENCE = 512;
+/**
+ * Opens a support session. Every check below runs before a row is written or
+ * a query touches the database that does not have to, so a malformed request
+ * never reaches the transaction that would otherwise lock the wrong tenant
+ * for no reason.
+ */
+export async function startBreakGlass(operatorAccess, db, scopeColumn, options) {
+    if (operatorAccess.context === 'break_glass') {
+        return refused('break_glass', 'A support session never opens another one.');
+    }
+    if (operatorAccess.tenant.kind !== 'operator' || !permits(operatorAccess, 'break_glass:start')) {
+        return refused('no_permission', 'You do not have permission to open a support session.');
+    }
+    const readOnlySession = options.readOnly ?? true;
+    if (!readOnlySession && !permits(operatorAccess, 'break_glass:start-write')) {
+        return refused('no_permission', 'You do not have permission to open a read-write support session.');
+    }
+    if (!isUuid(options.tenantId)) {
+        return refused('tenant_not_found', 'This organisation no longer exists.');
+    }
+    if (options.tenantId === operatorAccess.tenant.id) {
+        return refused('operator_tenant', 'The operator organisation is not reached through a support session.');
+    }
+    const minutes = options.minutes ?? 30;
+    if (!Number.isInteger(minutes) || minutes < MIN_MINUTES || minutes > MAX_MINUTES) {
+        return refused('invalid_minutes', `A support session lasts between ${MIN_MINUTES} and ${MAX_MINUTES} minutes.`);
+    }
+    if (!REASON_CODES.has(options.reasonCode)) {
+        return refused('invalid_reason', `"${options.reasonCode}" is not a reason this app knows.`);
+    }
+    if (options.reference.length < MIN_REFERENCE || options.reference.length > MAX_REFERENCE) {
+        return refused('invalid_reference', `The reference must be between ${MIN_REFERENCE} and ${MAX_REFERENCE} characters.`);
+    }
+    const role = options.role ?? 'owner';
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, operatorAccess);
+        if (!fresh ||
+            fresh.actor.class !== 'human' ||
+            fresh.context !== 'operator' ||
+            !permits(fresh, 'break_glass:start') ||
+            (!readOnlySession && !permits(fresh, 'break_glass:start-write')))
+            return refused('no_permission', 'Your support authority changed.');
+        const currentAccess = fresh;
+        // Locked though nothing here writes to the row: this is what serialises
+        // a session starting against a membership write landing on the same
+        // tenant at the same instant, the same reason every other authority
+        // write in this module locks the tenant first, and it is what turns a
+        // non-existent tenant into a clean refusal instead of a foreign-key
+        // error from the insert below.
+        const [targetTenant] = await tx
+            .select({ id: tenants.id })
+            .from(tenants)
+            .where(eq(tenants.id, options.tenantId))
+            .for('update');
+        if (!targetTenant)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        const supportRole = await roleDef(tx, currentAccess.binding, { id: options.tenantId }, role);
+        // Not `.builtIn`: a starter role (ADR 0016) is `built_in: false` for a
+        // tenant created after that change, but a support session must still
+        // never run as a tenant-authored custom role — `isCustomRoleKey` is the
+        // check that actually distinguishes the two.
+        if (!supportRole || isCustomRoleKey(supportRole.key))
+            return refused('invalid_role', 'Support requires an application-defined role in the target organisation.');
+        // A direct row always wins (D5): if the operator already belongs here,
+        // a session would be a second, weaker path into a tenant they can
+        // already reach properly, and accessFor never looks for one anyway.
+        const [direct] = await tx
+            .select({ principalId: memberships.principalId })
+            .from(memberships)
+            .where(and(eq(memberships.tenantId, options.tenantId), eq(memberships.principalId, currentAccess.actor.id), eq(memberships.principalClass, currentAccess.actor.class)))
+            .limit(1);
+        if (direct) {
+            return refused('direct_member', 'You already belong to this organisation; a support session is not how you reach it.');
+        }
+        if (await activeSession(tx, currentAccess.actor.id, options.tenantId)) {
+            return refused('session_active', 'You already have an open support session on this organisation.');
+        }
+        const [row] = await tx
+            .insert(breakGlassSessions)
+            .values({
+            operatorId: currentAccess.actor.id,
+            tenantId: options.tenantId,
+            roleId: supportRole.id,
+            readOnly: readOnlySession,
+            reasonCode: options.reasonCode,
+            reference: options.reference,
+            expiresAt: new Date(Date.now() + minutes * 60_000),
+        })
+            .returning({ id: breakGlassSessions.id, expiresAt: breakGlassSessions.expiresAt });
+        if (!row)
+            throw new Error('startBreakGlass: no row returned from the insert');
+        // Written as the operator's own act, not under the session it opens: the
+        // row about starting a session belongs to context 'operator', and a row
+        // written once the session is live carries context 'break_glass' instead.
+        await record(tx, currentAccess, {
+            action: 'break_glass.started',
+            tenantId: options.tenantId,
+            targetType: 'break_glass_session',
+            targetId: row.id,
+            reason: options.reasonCode,
+            reference: options.reference,
+        });
+        return done({ id: row.id, expiresAt: row.expiresAt }, [tenantTag(options.tenantId)]);
+    });
+}
+/**
+ * Ends one session: the operator who holds it may always end their own, no
+ * matter what they hold now, because that is a safety valve, not a power;
+ * ending someone else's needs `break_glass:end-any`.
+ */
+export async function endBreakGlass(operatorAccess, db, scopeColumn, sessionId) {
+    if (operatorAccess.context === 'break_glass') {
+        return refused('break_glass', 'A support session never ends a session as an authority act.');
+    }
+    if (operatorAccess.tenant.kind !== 'operator') {
+        return refused('no_permission', 'You do not have permission to end a support session.');
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, operatorAccess);
+        if (!fresh)
+            return refused('no_permission', 'Your operator membership ended.');
+        const currentAccess = fresh;
+        const [session] = await tx
+            .select()
+            .from(breakGlassSessions)
+            .where(eq(breakGlassSessions.id, sessionId))
+            .for('update');
+        if (!session || session.endedAt) {
+            return refused('session_not_found', 'This support session is not open.');
+        }
+        const isOwnSession = session.operatorId === currentAccess.actor.id;
+        if (!isOwnSession && !permits(currentAccess, 'break_glass:end-any')) {
+            return refused('no_permission', "You do not have permission to end another operator's support session.");
+        }
+        await tx
+            .update(breakGlassSessions)
+            // `now()` and not a Date from this process. `started_at` defaults to
+            // the database's clock, and `bg_ended_check` requires `ended_at` not to
+            // precede it; taking one end from Node and the other from Postgres
+            // makes that CHECK a race on the few milliseconds between two clocks,
+            // which is exactly how it failed intermittently in the integration
+            // tier. One clock decides both ends of a session.
+            .set({ endedAt: sql `now()`, endedBy: currentAccess.actor.id })
+            .where(eq(breakGlassSessions.id, sessionId));
+        await record(tx, currentAccess, {
+            action: 'break_glass.ended',
+            tenantId: session.tenantId,
+            targetType: 'break_glass_session',
+            targetId: session.id,
+            reason: session.reasonCode,
+            reference: session.reference,
+        });
+        return done(undefined, [tenantTag(session.tenantId)]);
+    });
+}
+/**
+ * Force-ends every session one operator holds, inside whatever transaction
+ * the caller already has open: a host's own `memberships.ts` calls this the
+ * moment an operator-tenant membership is removed or changed to a role
+ * without `break_glass:start`, so a session never outlives the authority
+ * that opened it (M9). Written as the `service:authz` actor rather than
+ * through `record`, because there is no `Access` for the operator whose
+ * session this is inside a transaction that is busy ending their
+ * membership, not building one.
+ */
+export async function endSessionsFor(tx, operatorId, reason) {
+    const sessions = await tx
+        .select()
+        .from(breakGlassSessions)
+        .where(and(eq(breakGlassSessions.operatorId, operatorId), isNull(breakGlassSessions.endedAt)));
+    for (const session of sessions) {
+        await tx
+            .update(breakGlassSessions)
+            // The same one-clock rule as endBreakGlass above.
+            .set({ endedAt: sql `now()`, endedBy: null })
+            .where(eq(breakGlassSessions.id, session.id));
+        await writeServiceEvent(tx, { id: 'authz', display: 'authz' }, {
+            action: 'break_glass.ended',
+            tenantId: session.tenantId,
+            targetType: 'break_glass_session',
+            targetId: session.id,
+            reason,
+            reference: session.reference,
+            context: 'operator',
+        });
+    }
+}
+/**
+ * The session that would currently grant access, or null: not yet ended and
+ * not past its expiry. A host's own `access.ts` reads this to resolve a
+ * session `Access`, and `startBreakGlass` reads it to refuse a second
+ * session on top of one that is already live; an expired-but-unended row
+ * counts as gone for both.
+ */
+export async function activeSession(tx, operatorId, tenantId) {
+    const [row] = await tx
+        .select()
+        .from(breakGlassSessions)
+        .where(and(eq(breakGlassSessions.operatorId, operatorId), eq(breakGlassSessions.tenantId, tenantId), isNull(breakGlassSessions.endedAt), gt(breakGlassSessions.expiresAt, sql `now()`)))
+        .limit(1);
+    return row ?? null;
+}
+/**
+ * Sessions for the console: one tenant's history when `tenantId` is given,
+ * or the calling operator's own history otherwise. A page-rendering read
+ * with no transaction to join, the same as `assignableRoles`; the caller is
+ * expected to have already resolved `operatorAccess` through its own
+ * `requireOperator` with whatever permission its own page needs. `db` is the
+ * host's root handle, taken explicitly rather than imported.
+ */
+export async function sessionsFor(operatorAccess, db, options = {}) {
+    if (operatorAccess.tenant.kind !== 'operator')
+        return [];
+    const condition = options.tenantId
+        ? eq(breakGlassSessions.tenantId, options.tenantId)
+        : eq(breakGlassSessions.operatorId, operatorAccess.actor.id);
+    return db
+        .select()
+        .from(breakGlassSessions)
+        .where(condition)
+        .orderBy(desc(breakGlassSessions.startedAt));
+}