@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/alerts.js

@@ -0,0 +1,132 @@
+import { and, eq, gte, sql } from 'drizzle-orm';
+import { orphanedRoleKeys } from './boot.js';
+import { reconcileDerived } from './reconcile.js';
+import { breakGlassSessions, invitations } from './schema.js';
+/** D9's first alert: D19's drift check found a row the tenant tree no longer calls for. */
+export async function checkOrphanMemberships(handle, binding) {
+    const report = await reconcileDerived(handle, binding);
+    if (report.orphans.length === 0)
+        return null;
+    const detail = report.orphans;
+    return {
+        check: 'orphan_memberships',
+        message: `${detail.length} derived membership row(s) are no longer called for by the tenant tree.`,
+        detail,
+    };
+}
+const STUCK_MAIL_THRESHOLD_MS = 60 * 60 * 1000;
+/**
+ * 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 async function checkStuckInvitations(handle, _binding) {
+    const cutoff = new Date(Date.now() - STUCK_MAIL_THRESHOLD_MS);
+    const rows = await handle
+        .select({
+        id: invitations.id,
+        tenantId: invitations.tenantId,
+        // Not the address. This finding goes to the event log, which
+        // `erasePerson` can never reach; an invitation id and its tenant are
+        // enough for somebody to act on the alert, and the address is one
+        // query away for whoever does.
+        failedSince: sql `coalesce(${invitations.mailStateAt}, ${invitations.createdAt})`,
+    })
+        .from(invitations)
+        .where(and(eq(invitations.status, 'pending'), eq(invitations.mailState, 'failed'), 
+    // Measured from when the mail state last changed, not from when the
+    // row was written: a re-invite rotates the token on the SAME row, so
+    // `created_at` answers a different question and answers it early.
+    // `coalesce` covers a row written before `mail_state_at` existed,
+    // which has no better moment to offer.
+    //
+    // The cutoff goes in as an ISO string with an explicit cast, not as
+    // a Date. A raw `sql` template carries no column type for the value
+    // it interpolates, so the driver cannot encode a Date and throws at
+    // bind time; only a comparison against a bare column can be left to
+    // drizzle's own operators.
+    sql `coalesce(${invitations.mailStateAt}, ${invitations.createdAt}) < ${cutoff.toISOString()}::timestamptz`));
+    if (rows.length === 0)
+        return null;
+    return {
+        check: 'stuck_invitations',
+        message: `${rows.length} invitation(s) have sat with failed mail for over an hour.`,
+        detail: rows,
+    };
+}
+const BREAK_GLASS_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** More than this many sessions on one tenant in the rolling window trips the alert. */
+const BREAK_GLASS_BURST_THRESHOLD = 2;
+/**
+ * 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 async function checkBreakGlassBurst(handle, _binding) {
+    const since = new Date(Date.now() - BREAK_GLASS_WINDOW_MS);
+    const rows = await handle
+        .select({ tenantId: breakGlassSessions.tenantId, count: sql `count(*)::int` })
+        .from(breakGlassSessions)
+        .where(gte(breakGlassSessions.startedAt, since))
+        .groupBy(breakGlassSessions.tenantId)
+        .having(sql `count(*) > ${BREAK_GLASS_BURST_THRESHOLD}`);
+    if (rows.length === 0)
+        return null;
+    return {
+        check: 'break_glass_burst',
+        message: `${rows.length} tenant(s) have had more than ${BREAK_GLASS_BURST_THRESHOLD} break-glass sessions opened in the last rolling day.`,
+        detail: rows,
+    };
+}
+/** D9's fourth alert: `boot.ts`'s `orphanedRoleKeys`, imported rather than reimplemented. */
+export async function checkOrphanedRoleKeys(handle, binding) {
+    const found = await orphanedRoleKeys(handle, binding);
+    if (found.length === 0)
+        return null;
+    const detail = found;
+    return {
+        check: 'orphaned_role_keys',
+        message: `${detail.length} row(s) name a role key the running vocabulary does not resolve.`,
+        detail,
+    };
+}
+/**
+ * The one place a finding reaches the sink: the host's `reporting.alert`,
+ * one `alert.<check>` row in its event log, always.
+ */
+export function reportAlert(reporting, finding) {
+    // The finding's detail is projected to flat fields (a list of rows becomes
+    // a count, never the rows) by the host's own `reporting.alert`.
+    reporting.alert(finding);
+}
+/**
+ * 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 async function runAlerts(handle, binding, reporting) {
+    const results = await Promise.all([
+        checkOrphanMemberships(handle, binding),
+        checkStuckInvitations(handle, binding),
+        checkBreakGlassBurst(handle, binding),
+        checkOrphanedRoleKeys(handle, binding),
+    ]);
+    const findings = results.filter((finding) => finding !== null);
+    for (const finding of findings)
+        reportAlert(reporting, finding);
+    return findings;
+}

package/dist/assignments.d.ts

@@ -0,0 +1,71 @@
+import { type ResourceAssignment, type ResourcePrincipal, type ResourceRole } from '@wtfalch/authz';
+import type { StoreBinding } from './binding.js';
+import type { DbOrTx } from './scoped.js';
+import type { Access } from './types.js';
+export declare const identityWhere: (tenantId: string, principal: ResourcePrincipal) => import("drizzle-orm").SQL<unknown> | undefined;
+/**
+ * A display projection only. Authorization always reads every current assignment. `binding`
+ * because the primary assignment this reads is scoped to one application/platform pair, the same
+ * pair every other query in this module takes explicitly rather than importing.
+ */
+export declare const primaryRoleKey: (binding: StoreBinding) => import("drizzle-orm").SQL<string>;
+export declare function primaryAssignment(role: ResourceRole, principal: ResourcePrincipal, expiresAt?: number): ResourceAssignment;
+/**
+ * Both the administrative operation and every scoped grant must be covered. `access` already
+ * carries its own `binding`, so `compileRoleGrants` reads `access.binding.catalogue` rather than
+ * taking a separate catalogue argument, matching how `permits` itself reads `access.binding`.
+ */
+export declare function roleAssignmentRefusal(access: Access, role: ResourceRole, assignment: ResourceAssignment, operation: string | null): string | null;
+/** Caller holds the tenant lock and has checked delegation, guards and recipient eligibility. */
+export declare function writePrimaryAssignment(tx: DbOrTx, binding: StoreBinding, role: ResourceRole, principal: ResourcePrincipal, options?: {
+    source?: string;
+    viaTenantId?: string | null;
+    createdBy?: string | null;
+    expiresAt?: Date | null;
+}): Promise<void>;
+export declare function roleById(tx: DbOrTx, binding: StoreBinding, tenantId: string, id: string): Promise<{
+    id: string;
+    tenantId: string;
+    applicationId: string;
+    platformId: string;
+    key: string;
+    name: string;
+    description: string;
+    builtIn: boolean;
+    revision: number;
+    entries: {
+        permission: string;
+        boundary: {
+            kind: "organisation";
+            organisationId: string;
+            descendants?: boolean | undefined;
+        } | {
+            kind: "organisations";
+            organisationIds: string[];
+        } | {
+            kind: "platform";
+        };
+        scope: {
+            kind: "organisation";
+        } | {
+            kind: "team";
+            teamId: string;
+            descendants: boolean;
+        } | {
+            kind: "own_teams";
+            descendants: boolean;
+        } | {
+            kind: "resource";
+            resourceType: string;
+            resourceId: string;
+        };
+        relation: "any" | "owner" | "actor" | "subject";
+    }[];
+    guards: string[];
+    createdBy: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    updatedBy: string | null;
+} | null>;
+/** Default personal access is an ordinary, persisted assignment created when a person joins. */
+export declare function writeParticipationPolicy(tx: DbOrTx, binding: StoreBinding, tenantId: string, principal: ResourcePrincipal): Promise<void>;

package/dist/assignments.js

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+import { compileRoleGrants, } from '@wtfalch/authz';
+import { and, eq, sql } from 'drizzle-orm';
+import { permits } from './policy-access.js';
+import { policyAssignments, policyRoles } from './policy-schema.js';
+import { memberships } from './schema.js';
+export const identityWhere = (tenantId, principal) => and(eq(memberships.tenantId, tenantId), eq(memberships.principalId, principal.id), eq(memberships.principalClass, principal.class));
+/**
+ * A display projection only. Authorization always reads every current assignment. `binding`
+ * because the primary assignment this reads is scoped to one application/platform pair, the same
+ * pair every other query in this module takes explicitly rather than importing.
+ */
+export const primaryRoleKey = (binding) => sql `coalesce((select r.key from authz_assignments a join authz_roles r on r.id=a.role_id where a.tenant_id="memberships"."tenant_id" and a.principal_id="memberships"."principal_id" and a.principal_class="memberships"."principal_class" and a.application_id=${binding.applicationId} and a.platform_id=${binding.platformId} and a.primary_assignment and (a.expires_at is null or a.expires_at>now())), '')`;
+export function primaryAssignment(role, principal, expiresAt) {
+    return {
+        id: randomUUID(),
+        roleId: role.id,
+        organisationId: role.organisationId,
+        applicationId: role.applicationId,
+        platformId: role.platformId,
+        boundary: { kind: 'platform' },
+        scope: { kind: 'organisation' },
+        recipient: { kind: 'principal', principal: { id: principal.id, class: principal.class } },
+        ...(expiresAt === undefined ? {} : { expiresAt }),
+    };
+}
+/**
+ * Both the administrative operation and every scoped grant must be covered. `access` already
+ * carries its own `binding`, so `compileRoleGrants` reads `access.binding.catalogue` rather than
+ * taking a separate catalogue argument, matching how `permits` itself reads `access.binding`.
+ */
+export function roleAssignmentRefusal(access, role, assignment, operation) {
+    if (access.context === 'break_glass')
+        return 'break_glass';
+    if (operation && !permits(access, operation))
+        return 'no_permission';
+    if (operation && role.guards.some((guard) => !permits(access, guard)))
+        return 'guarded';
+    try {
+        return compileRoleGrants(role, assignment, access.binding.catalogue).every((g) => access.authority.canDelegate(g))
+            ? null
+            : 'not_covered';
+    }
+    catch {
+        return 'invalid_role';
+    }
+}
+/** Caller holds the tenant lock and has checked delegation, guards and recipient eligibility. */
+export async function writePrimaryAssignment(tx, binding, role, principal, options = {}) {
+    const assignment = primaryAssignment(role, principal, options.expiresAt?.getTime());
+    // The compiler validates persisted authority; there is no special built-in runtime evaluator.
+    compileRoleGrants(role, assignment, binding.catalogue);
+    await tx
+        .delete(policyAssignments)
+        .where(and(eq(policyAssignments.tenantId, role.organisationId), eq(policyAssignments.applicationId, binding.applicationId), eq(policyAssignments.platformId, binding.platformId), eq(policyAssignments.principalId, principal.id), eq(policyAssignments.principalClass, principal.class), eq(policyAssignments.primary, true)));
+    await tx.insert(policyAssignments).values({
+        id: assignment.id,
+        tenantId: role.organisationId,
+        applicationId: binding.applicationId,
+        platformId: binding.platformId,
+        roleId: role.id,
+        principalId: principal.id,
+        principalClass: principal.class,
+        boundary: assignment.boundary,
+        scope: { kind: 'organisation' },
+        primary: true,
+        source: options.source ?? 'direct',
+        viaTenantId: options.viaTenantId ?? null,
+        createdBy: options.createdBy ?? null,
+        expiresAt: options.expiresAt ?? null,
+    });
+}
+export async function roleById(tx, binding, tenantId, id) {
+    const [row] = await tx
+        .select()
+        .from(policyRoles)
+        .where(and(eq(policyRoles.id, id), eq(policyRoles.tenantId, tenantId), eq(policyRoles.applicationId, binding.applicationId), eq(policyRoles.platformId, binding.platformId)))
+        .limit(1);
+    return row ?? null;
+}
+/** Default personal access is an ordinary, persisted assignment created when a person joins. */
+export async function writeParticipationPolicy(tx, binding, tenantId, principal) {
+    if (principal.class !== 'human')
+        return;
+    const [role] = await tx
+        .select()
+        .from(policyRoles)
+        .where(and(eq(policyRoles.tenantId, tenantId), eq(policyRoles.applicationId, binding.applicationId), eq(policyRoles.platformId, binding.platformId), eq(policyRoles.key, 'self_service'), eq(policyRoles.builtIn, true)))
+        .limit(1);
+    if (!role)
+        throw new Error('Missing versioned personal access role');
+    await tx.insert(policyAssignments).values({
+        tenantId,
+        applicationId: binding.applicationId,
+        platformId: binding.platformId,
+        roleId: role.id,
+        principalId: principal.id,
+        principalClass: principal.class,
+        boundary: { kind: 'organisation', organisationId: tenantId },
+        scope: { kind: 'organisation' },
+        primary: false,
+    });
+}

package/dist/audit.d.ts

@@ -0,0 +1,122 @@
+import { type ActorClass, type Context, type EventName, type Outcome } from '@wtfalch/authz';
+import type { DbOrTx } from './scoped.js';
+import type { Access, Principal } from './types.js';
+/**
+ * What a caller supplies for one row; everything else (the actor, the
+ * context, the session, the timestamp, the schema version) is filled in by
+ * `record`, `recordAs` or `writeServiceEvent` below, never by the caller, so
+ * a feature module cannot sign a row as someone it is not (D9).
+ */
+export interface EventInput {
+    readonly teamId?: string;
+    readonly subject?: {
+        readonly id: string;
+        readonly class: ActorClass;
+    };
+    readonly action: EventName;
+    readonly tenantId: string | null;
+    readonly targetType: string;
+    readonly targetId: string;
+    readonly outcome?: Outcome;
+    readonly before?: unknown;
+    readonly after?: unknown;
+    readonly reason?: string;
+    readonly reference?: string;
+    readonly tenantVisible?: boolean;
+    readonly request?: {
+        readonly id?: string;
+        readonly ip?: string;
+        readonly userAgent?: string;
+    };
+}
+/**
+ * The audit insert every authority write uses. Actor fields come from the
+ * `Access` it was handed, never from an argument (D9): a feature module
+ * cannot sign a row as anyone but the principal that was actually resolved
+ * for this request. `context` and the break-glass session id, when there is
+ * one, come from the same `Access`, so a row written under a support session
+ * always says so.
+ *
+ * Under a session, `reason` and `reference` fall back to the session's own
+ * (1c): the migration's CHECK requires both, from the closed reason-code
+ * set, on every row whose context is `break_glass`, and a caller writing a
+ * row while a session is open rarely has a different reason to give than the
+ * one the session itself was opened for. A caller's own value, when given,
+ * still wins.
+ */
+export declare function record(tx: DbOrTx, access: Access, input: EventInput): Promise<void>;
+/**
+ * The same insert for a write with no `Access` yet: self-serve `createTenant`
+ * resolves nothing before the tenant row exists, so there is no membership
+ * to build one from. Never carries a break-glass session, because there is
+ * no session without an `Access` to hold it.
+ */
+export declare function recordAs(tx: DbOrTx, actor: Principal, context: Context, input: EventInput): Promise<void>;
+/**
+ * The bootstrap, migration, deploy and job rows: written as `service`, never
+ * as a person or a credential, because nothing signed in to cause them.
+ * `context` defaults to `standard`; pass `'operator'` for a row about the
+ * operator tenant specifically (an operator-only system role changing, say).
+ */
+export declare function writeServiceEvent(tx: DbOrTx, actor: {
+    readonly id: string;
+    readonly display: string;
+}, input: EventInput & {
+    readonly context?: 'standard' | 'operator';
+}): Promise<void>;
+/** One row of the tenant's own security log, already narrowed to what the tenant may see. */
+export interface SecurityLogEntry {
+    readonly id: number;
+    readonly occurredAt: Date;
+    readonly action: string;
+    readonly actorDisplay: string;
+    readonly targetType: string;
+    readonly targetId: string;
+    readonly outcome: string;
+    readonly context: string;
+    readonly reason: string | null;
+    readonly reference: string | null;
+    /** Set when the actor has since been erased, so the display name is a placeholder rather than a person. */
+    readonly erasedAt: Date | null;
+}
+export interface SecurityLogPage {
+    readonly items: readonly SecurityLogEntry[];
+    readonly next: {
+        readonly occurredAt: Date;
+        readonly id: number;
+    } | null;
+}
+/**
+ * The tenant's own security log: what happened to this organisation's
+ * authority, newest first.
+ *
+ * `db` is the host's root handle, taken explicitly rather than imported: the
+ * store has no database of its own to reach for.
+ *
+ * **`tenant_visible` is not optional and not the caller's choice.** The
+ * column decides, per the migration's own words, "whether the tenant's own
+ * security log shows this row", and it is set once per event type from the
+ * vocabulary rather than per write. Operator-side events about a tenant are
+ * written with it false, so a query that forgot the predicate would show a
+ * customer the estate's internal handling of them. It is filtered here, in
+ * the one function a tenant-facing page is meant to call, rather than left to
+ * each page to remember.
+ *
+ * **`null` when the actor may not read it, never an empty page**, the same
+ * distinction `membersOf` draws and for the same reason: "you may not see
+ * this" and "nothing has happened" are different facts, and a log that
+ * renders the second for the first invites somebody to conclude their
+ * organisation has no history.
+ *
+ * Keyset-paged on `(occurred_at, id)` descending, the reverse of the
+ * table's own ordering. A log is read newest first and grows at the end a
+ * reader starts from, which is exactly the case an offset cannot page
+ * stably: a row arriving mid-read shifts every later offset by one.
+ */
+export declare function securityLogFor(access: Access, db: DbOrTx, options?: {
+    readonly limit?: number;
+    readonly after?: {
+        occurredAt: Date;
+        id: number;
+    };
+}): Promise<SecurityLogPage | null>;

package/dist/audit.js

@@ -0,0 +1,194 @@
+import { authzEventSchema, core, tenantVisibleByDefault, } from '@wtfalch/authz';
+import { and, desc, eq, lt, or } from 'drizzle-orm';
+import { permitsRead } from './policy-access.js';
+import { authzEvents } from './schema.js';
+/**
+ * The one place a row actually gets built and inserted. Every field the
+ * schema requires is filled in here, the candidate row is validated with
+ * `authzEventSchema.parse` before anything is sent (the package refuses an
+ * unknown key or a field past its length limit, so a mistake here fails
+ * loudly at write time rather than becoming a silently wrong row), and only
+ * then does it reach `tx.insert`. `tx` rather than a fixed transaction type,
+ * because a plain `Db` insert is just as valid a single statement as one
+ * inside a transaction; callers that need this row atomic with another
+ * write (which is every authority write except a service log) pass their
+ * own transaction through.
+ */
+async function insertEvent(tx, actor, context, sessionId, input) {
+    const occurredAt = new Date();
+    const row = {
+        occurred_at: occurredAt.toISOString(),
+        tenant_id: input.tenantId,
+        actor_class: actor.class,
+        actor_id: actor.id,
+        actor_display: actor.display,
+        action: input.action,
+        target_type: input.targetType,
+        target_id: input.targetId,
+        outcome: input.outcome ?? 'success',
+        context,
+        session_id: sessionId,
+        reason: input.reason ?? null,
+        reference: input.reference ?? null,
+        request_id: input.request?.id ?? null,
+        ip: input.request?.ip ?? null,
+        user_agent: input.request?.userAgent ?? null,
+        tenant_visible: input.tenantVisible ?? tenantVisibleByDefault(input.action),
+        before: input.before ?? null,
+        after: input.after ?? null,
+        erased_at: null,
+        schema_version: core.version,
+    };
+    authzEventSchema.parse(row);
+    await tx.insert(authzEvents).values({
+        occurredAt,
+        tenantId: row.tenant_id,
+        teamId: input.teamId ?? null,
+        subjectId: input.subject?.id ?? null,
+        subjectClass: input.subject?.class ?? null,
+        actorClass: row.actor_class,
+        actorId: row.actor_id,
+        actorDisplay: row.actor_display,
+        action: row.action,
+        targetType: row.target_type,
+        targetId: row.target_id,
+        outcome: row.outcome,
+        context: row.context,
+        sessionId: row.session_id,
+        reason: row.reason,
+        reference: row.reference,
+        requestId: row.request_id,
+        ip: row.ip,
+        userAgent: row.user_agent,
+        tenantVisible: row.tenant_visible,
+        before: row.before,
+        after: row.after,
+        schemaVersion: row.schema_version,
+    });
+}
+/**
+ * The audit insert every authority write uses. Actor fields come from the
+ * `Access` it was handed, never from an argument (D9): a feature module
+ * cannot sign a row as anyone but the principal that was actually resolved
+ * for this request. `context` and the break-glass session id, when there is
+ * one, come from the same `Access`, so a row written under a support session
+ * always says so.
+ *
+ * Under a session, `reason` and `reference` fall back to the session's own
+ * (1c): the migration's CHECK requires both, from the closed reason-code
+ * set, on every row whose context is `break_glass`, and a caller writing a
+ * row while a session is open rarely has a different reason to give than the
+ * one the session itself was opened for. A caller's own value, when given,
+ * still wins.
+ */
+export async function record(tx, access, input) {
+    // `??` rather than a spread: a caller passing `reason: undefined` by way
+    // of an optional argument must still get the session's value, or the row
+    // fails the migration's CHECK.
+    const grant = access.context === 'break_glass' ? access.breakGlass : null;
+    const withSession = grant
+        ? {
+            ...input,
+            reason: input.reason ?? grant.reason,
+            reference: input.reference ?? grant.reference,
+        }
+        : input;
+    await insertEvent(tx, { class: access.actor.class, id: access.actor.id, display: access.actor.display }, access.context, access.breakGlass?.id ?? null, withSession);
+}
+/**
+ * The same insert for a write with no `Access` yet: self-serve `createTenant`
+ * resolves nothing before the tenant row exists, so there is no membership
+ * to build one from. Never carries a break-glass session, because there is
+ * no session without an `Access` to hold it.
+ */
+export async function recordAs(tx, actor, context, input) {
+    await insertEvent(tx, { class: actor.class, id: actor.id, display: actor.display }, context, null, input);
+}
+/**
+ * The bootstrap, migration, deploy and job rows: written as `service`, never
+ * as a person or a credential, because nothing signed in to cause them.
+ * `context` defaults to `standard`; pass `'operator'` for a row about the
+ * operator tenant specifically (an operator-only system role changing, say).
+ */
+export async function writeServiceEvent(tx, actor, input) {
+    const { context = 'standard', ...rest } = input;
+    await insertEvent(tx, { class: 'service', id: actor.id, display: actor.display }, context, null, rest);
+}
+/**
+ * The tenant's own security log: what happened to this organisation's
+ * authority, newest first.
+ *
+ * `db` is the host's root handle, taken explicitly rather than imported: the
+ * store has no database of its own to reach for.
+ *
+ * **`tenant_visible` is not optional and not the caller's choice.** The
+ * column decides, per the migration's own words, "whether the tenant's own
+ * security log shows this row", and it is set once per event type from the
+ * vocabulary rather than per write. Operator-side events about a tenant are
+ * written with it false, so a query that forgot the predicate would show a
+ * customer the estate's internal handling of them. It is filtered here, in
+ * the one function a tenant-facing page is meant to call, rather than left to
+ * each page to remember.
+ *
+ * **`null` when the actor may not read it, never an empty page**, the same
+ * distinction `membersOf` draws and for the same reason: "you may not see
+ * this" and "nothing has happened" are different facts, and a log that
+ * renders the second for the first invites somebody to conclude their
+ * organisation has no history.
+ *
+ * Keyset-paged on `(occurred_at, id)` descending, the reverse of the
+ * table's own ordering. A log is read newest first and grows at the end a
+ * reader starts from, which is exactly the case an offset cannot page
+ * stably: a row arriving mid-read shifts every later offset by one.
+ */
+export async function securityLogFor(access, db, options = {}) {
+    if (!(await permitsRead(access, db, 'platform.audit:read')))
+        return null;
+    const limit = Math.min(options.limit ?? 50, 200);
+    const conditions = [
+        eq(authzEvents.tenantId, access.tenant.id),
+        eq(authzEvents.tenantVisible, true),
+    ];
+    if (options.after) {
+        const { occurredAt, id } = options.after;
+        // Strictly before the cursor in the same order the query sorts by, with
+        // the identity column breaking ties, so two events in one transaction
+        // cannot hide each other across a page boundary.
+        const keyset = or(lt(authzEvents.occurredAt, occurredAt), and(eq(authzEvents.occurredAt, occurredAt), lt(authzEvents.id, id)));
+        if (keyset)
+            conditions.push(keyset);
+    }
+    const rows = await db
+        .select({
+        id: authzEvents.id,
+        occurredAt: authzEvents.occurredAt,
+        action: authzEvents.action,
+        actorDisplay: authzEvents.actorDisplay,
+        targetType: authzEvents.targetType,
+        targetId: authzEvents.targetId,
+        outcome: authzEvents.outcome,
+        context: authzEvents.context,
+        reason: authzEvents.reason,
+        reference: authzEvents.reference,
+        erasedAt: authzEvents.erasedAt,
+    })
+        .from(authzEvents)
+        .where(and(...conditions))
+        .orderBy(desc(authzEvents.occurredAt), desc(authzEvents.id))
+        .limit(limit + 1);
+    const page = rows.slice(0, limit);
+    const last = page.at(-1);
+    // Reads that expose another party's activity are events too (0.9.0): a
+    // read of a security log is itself audited, tenant-visible by default, so
+    // the tenant sees what was read, not only that it exists.
+    await record(db, access, {
+        action: 'audit_log.viewed',
+        tenantId: access.tenant.id,
+        targetType: 'audit',
+        targetId: access.tenant.id,
+    });
+    return {
+        items: page,
+        next: rows.length > limit && last ? { occurredAt: last.occurredAt, id: last.id } : null,
+    };
+}

package/dist/binding.d.ts

@@ -0,0 +1,17 @@
+import type { ResourceCatalogue, ResourcePermission } from '@wtfalch/authz';
+import type { PolicyBinding } from './owners.js';
+/**
+ * `PolicyBinding` (`applicationId`, `platformId`) plus the host's own resource catalogue. The
+ * store has no catalogue of its own — each host defines its own permissions — so every moved
+ * module that used to read `APPLICATION_ID`, `PLATFORM_ID` or `catalogue` from its own
+ * policy-catalogue file now takes a `StoreBinding` as a parameter instead.
+ */
+export interface StoreBinding extends PolicyBinding {
+    readonly catalogue: ResourceCatalogue;
+}
+/**
+ * The one lookup every moved module did as `catalogue[permission]`. A tiny helper rather than
+ * each call site repeating the index expression, since `permits`, `permitsPlatform`,
+ * `policyTarget` and `explain` all need it.
+ */
+export declare function permissionOf(binding: StoreBinding, permission: string): ResourcePermission | undefined;

package/dist/binding.js

@@ -0,0 +1,8 @@
+/**
+ * The one lookup every moved module did as `catalogue[permission]`. A tiny helper rather than
+ * each call site repeating the index expression, since `permits`, `permitsPlatform`,
+ * `policyTarget` and `explain` all need it.
+ */
+export function permissionOf(binding, permission) {
+    return binding.catalogue[permission];
+}