@wtfalch/authz-store 0.2.1 → 0.4.0

package/dist/policy.js

@@ -0,0 +1,78 @@
+import { core, defineResourceCatalogue, } from '@wtfalch/authz';
+/**
+ * Builds a `StorePolicy` from a host's own `policy-catalogue.json` data and its
+ * `{ applicationId, platformId }`. Generic over the host's data because every host's catalogue
+ * differs; this function is the one piece of that shape both applications wrote identically.
+ *
+ * `binding.hostEvents` (0.4.0), when given, is carried onto the returned `StorePolicy` unchanged
+ * so `record`/`recordAs`/`writeServiceEvent` can validate a host's own audit actions against it.
+ * A name in `hostEvents` that repeats a core event name is a configuration error — it would make
+ * an audit row ambiguous about which vocabulary it came from — so this throws rather than let it
+ * pass silently.
+ */
+export function definePolicy(data, binding) {
+    const coreEvents = new Set(core.events);
+    for (const name of binding.hostEvents ?? []) {
+        if (coreEvents.has(name)) {
+            throw new Error(`definePolicy: hostEvents "${name}" collides with a core event name; a host event must not reuse one`);
+        }
+    }
+    const namespaces = [
+        ...new Set(Object.keys(data.permissions).map((key) => key.split(/[.:]/)[0])),
+    ];
+    const catalogue = defineResourceCatalogue(namespaces.map((namespace) => ({
+        namespace,
+        permissions: Object.values(data.permissions).filter((p) => p.id.split(/[.:]/)[0] === namespace),
+    })));
+    // A tenant kind this host has no roles for is a configuration error. Seeding it
+    // with nothing would leave the tenant without an owner seat, so fail loudly,
+    // as the hosts' own catalogue did.
+    const rolesFor = (kind) => {
+        const roles = data.systemRoles[kind];
+        if (!roles)
+            throw new Error(`the policy catalogue has no system roles for tenant kind "${kind}"`);
+        return roles;
+    };
+    function roleFrom(organisationId, role, builtIn) {
+        return {
+            key: role.key,
+            applicationId: binding.applicationId,
+            platformId: binding.platformId,
+            organisationId,
+            label: role.label,
+            description: role.description,
+            revision: role.revision,
+            builtIn,
+            guards: [...role.guards],
+            entries: role.entries.map((entry) => ({
+                permission: entry.permission,
+                boundary: (entry.boundary === 'platform'
+                    ? { kind: 'platform' }
+                    : { kind: 'organisation', organisationId }),
+                scope: ('scope' in entry ? entry.scope : { kind: 'organisation' }),
+                relation: ('relation' in entry ? entry.relation : 'any'),
+            })),
+        };
+    }
+    return {
+        applicationId: binding.applicationId,
+        platformId: binding.platformId,
+        catalogue,
+        hostEvents: binding.hostEvents,
+        defaultCeiling: data.defaultCeiling,
+        maxDepth: data.maxDepth,
+        elevated: new Set(data.elevated),
+        requiresCoApproval: new Set(data.coApproval),
+        offered: Object.keys(catalogue).filter((key) => catalogue[key]?.offered),
+        builtInRoles(organisationId, kind) {
+            return Object.values(rolesFor(kind))
+                .filter((role) => role.key === 'self_service')
+                .map((role) => roleFrom(organisationId, role, true));
+        },
+        starterRoles(organisationId, kind) {
+            return Object.values(rolesFor(kind))
+                .filter((role) => role.key !== 'self_service')
+                .map((role) => roleFrom(organisationId, role, false));
+        },
+    };
+}

package/dist/propagate.d.ts

@@ -0,0 +1,43 @@
+import type { StoreBinding } from './binding.js';
+import type { DbOrTx } from './scoped.js';
+import type { Access, Context, Principal } from './types.js';
+/**
+ * D19's propagation, in one place: after a direct membership row is written
+ * in a tenant, make every derived row that depended on it match again, and
+ * write one audit row per change.
+ *
+ * Every direct write goes through here. There are five and they arrive from
+ * four files: the three writes in `memberships.ts`, an accepted invitation
+ * in `invitations.ts`, an installed owner in `install-owner.ts`, and a
+ * credential minted or revoked in `credentials.ts`. Item 1e left two private
+ * copies of this and 1f would have made a third, which is precisely how the
+ * five stop agreeing about what a propagating write does.
+ *
+ * Two rules worth restating here, because both were bugs before they were
+ * rules. It runs INSIDE the caller's own transaction, never after it commits,
+ * so a membership and the rows it implies are one atomic change. And the
+ * tenant itself is in the recomputed set, not only its descendants: removing
+ * a direct row at a nested tenant does not leave that person with nothing
+ * there, it leaves them with whatever an ancestor still grants.
+ */
+/** How the audit rows get signed: from a resolved `Access`, or from a `Principal` for a write that has none yet (an acceptance, before the accepter is a member). */
+export type PropagationWriter = {
+    readonly kind: 'access';
+    readonly access: Access;
+} | {
+    readonly kind: 'principal';
+    readonly principal: Principal;
+    readonly context: Context;
+};
+/** Signs an audit row as whichever of the two the caller had. Neither path lets a caller name an actor of its own choosing; that is `audit.ts`'s rule and this only passes it through. */
+export declare function writerFromAccess(access: Access): PropagationWriter;
+export declare function writerFromPrincipal(principal: Principal, context: Context): PropagationWriter;
+/**
+ * Recomputes the derived rows this write can have moved, and returns the
+ * cache tags for every tenant it touched, for the caller to add to its own.
+ *
+ * A tenant with nothing above it and nothing below it does no work at all,
+ * which is every tenant in an app that never attaches anything: the two
+ * reads below are the whole cost of nesting for an app that does not use it.
+ */
+export declare function propagateMembershipChange(tx: DbOrTx, binding: StoreBinding, writer: PropagationWriter, tenantId: string, principalId: string): Promise<readonly string[]>;

package/dist/propagate.js

@@ -0,0 +1,47 @@
+import { record, recordAs } from './audit.js';
+import { recomputeDerived } from './tree-writes.js';
+import { derivedEventAction, descendantsOf, nodeById } from './tree.js';
+import { tenantTag } from './types.js';
+/** Signs an audit row as whichever of the two the caller had. Neither path lets a caller name an actor of its own choosing; that is `audit.ts`'s rule and this only passes it through. */
+export function writerFromAccess(access) {
+    return { kind: 'access', access };
+}
+export function writerFromPrincipal(principal, context) {
+    return { kind: 'principal', principal, context };
+}
+/**
+ * Recomputes the derived rows this write can have moved, and returns the
+ * cache tags for every tenant it touched, for the caller to add to its own.
+ *
+ * A tenant with nothing above it and nothing below it does no work at all,
+ * which is every tenant in an app that never attaches anything: the two
+ * reads below are the whole cost of nesting for an app that does not use it.
+ */
+export async function propagateMembershipChange(tx, binding, writer, tenantId, principalId) {
+    const node = await nodeById(tx, tenantId);
+    const descendants = await descendantsOf(tx, tenantId);
+    if (descendants.length === 0 && !node?.parentId)
+        return [];
+    const changes = await recomputeDerived(tx, binding, [tenantId, ...descendants.map((d) => d.id)], [principalId]);
+    const tags = new Set();
+    for (const change of changes) {
+        tags.add(tenantTag(change.tenantId));
+        const input = {
+            action: derivedEventAction(change.kind),
+            tenantId: change.tenantId,
+            targetType: 'membership',
+            targetId: change.principalId,
+            before: change.before
+                ? { role: change.before.role, viaTenantId: change.before.viaTenantId }
+                : undefined,
+            after: change.after
+                ? { role: change.after.role, viaTenantId: change.after.viaTenantId }
+                : undefined,
+        };
+        if (writer.kind === 'access')
+            await record(tx, writer.access, input);
+        else
+            await recordAs(tx, writer.principal, writer.context, input);
+    }
+    return [...tags];
+}

package/dist/reconcile.d.ts

@@ -0,0 +1,78 @@
+import type { StoreBinding } from './binding.js';
+import type { DbOrTx } from './scoped.js';
+/**
+ * D19's drift check: every derived membership row compared against what the
+ * tenant tree actually calls for, read only.
+ *
+ * It reports a difference and never fixes one. D19's failure mode is drift, a
+ * row that should have gone and did not or one that never got written, and a
+ * check that silently repairs a wrong row hides the bug that let it drift.
+ * See `tree.ts`'s header for the derived rule this compares against; it asks
+ * that file the same question the writers answer, rather than keeping a
+ * second copy of the rule that could be wrong in the same way.
+ *
+ * `reconcileDerived` takes whatever handle its caller already has and opens
+ * no connection of its own, so a nightly job, a route and a test all reach it
+ * the same way.
+ */
+/**
+ * A derived row that is present but that the tree no longer calls for: the
+ * parent link was cleared without `detachInTx` running, the ancestor's own
+ * direct row went without `recomputeDerived` running, or the row was written
+ * by hand. Nothing about the tenant that held it is assumed still valid, so
+ * `viaTenantId` is reported exactly as stored, including null.
+ */
+export interface ReconcileOrphan {
+    readonly tenantId: string;
+    readonly principalId: string;
+    readonly role: string;
+    readonly viaTenantId: string | null;
+}
+/** A derived row the tree calls for that is not there. */
+export interface ReconcileMissing {
+    readonly tenantId: string;
+    readonly principalId: string;
+    readonly role: string;
+    readonly viaTenantId: string;
+}
+/** A derived row that is present for the right principal but does not match what the tree calls for. */
+export interface ReconcileWrongRole {
+    readonly tenantId: string;
+    readonly principalId: string;
+    readonly actual: {
+        readonly role: string;
+        readonly viaTenantId: string | null;
+    };
+    readonly expected: {
+        readonly role: string;
+        readonly viaTenantId: string;
+    };
+}
+/** What one reconciliation run found. Every array is empty on a healthy tree. */
+export interface ReconcileReport {
+    readonly orphans: readonly ReconcileOrphan[];
+    readonly missing: readonly ReconcileMissing[];
+    readonly wrongRole: readonly ReconcileWrongRole[];
+    /** How many tenants were asked the question, whether or not they turned up a difference. */
+    readonly checkedTenants: number;
+    /** How many stored `inherited` rows were read across those tenants. */
+    readonly checkedRows: number;
+}
+/**
+ * Whether the `inherited` membership rows in the database match what
+ * `expectedDerivedFor` (tree.ts) says they should be, for every tenant a
+ * derived row could possibly belong to. Read-only: nothing here writes.
+ *
+ * A tenant is worth asking about in one of two ways: it has a `parent_id`,
+ * so the rule may call for rows in it, or it currently holds at least one
+ * `inherited` row, so a difference can exist even if its `parent_id` was
+ * cleared without the recomputation that should have gone with it (which is
+ * exactly the corruption an orphan row represents). Checking the union
+ * rather than only the first is what lets a hand-cleared or hand-inserted
+ * row be caught rather than silently skipped.
+ *
+ * Pure over the handle it is given: a host's own nightly job builds a plain
+ * handle from its own `DATABASE_URL`, and a test passes a transaction
+ * directly.
+ */
+export declare function reconcileDerived(handle: DbOrTx, binding: StoreBinding): Promise<ReconcileReport>;

package/dist/reconcile.js

@@ -0,0 +1,94 @@
+import { and, eq } from 'drizzle-orm';
+import { primaryRoleKey } from './assignments.js';
+import { memberships, tenants } from './schema.js';
+import { expectedDerivedFor } from './tree.js';
+/**
+ * Whether the `inherited` membership rows in the database match what
+ * `expectedDerivedFor` (tree.ts) says they should be, for every tenant a
+ * derived row could possibly belong to. Read-only: nothing here writes.
+ *
+ * A tenant is worth asking about in one of two ways: it has a `parent_id`,
+ * so the rule may call for rows in it, or it currently holds at least one
+ * `inherited` row, so a difference can exist even if its `parent_id` was
+ * cleared without the recomputation that should have gone with it (which is
+ * exactly the corruption an orphan row represents). Checking the union
+ * rather than only the first is what lets a hand-cleared or hand-inserted
+ * row be caught rather than silently skipped.
+ *
+ * Pure over the handle it is given: a host's own nightly job builds a plain
+ * handle from its own `DATABASE_URL`, and a test passes a transaction
+ * directly.
+ */
+export async function reconcileDerived(handle, binding) {
+    const tenantRows = await handle
+        .select({ id: tenants.id, parentId: tenants.parentId })
+        .from(tenants);
+    const toCheck = new Set();
+    for (const row of tenantRows) {
+        if (row.parentId !== null)
+            toCheck.add(row.id);
+    }
+    const inheritedRows = await handle
+        .select({ tenantId: memberships.tenantId })
+        .from(memberships)
+        .where(eq(memberships.source, 'inherited'));
+    for (const row of inheritedRows)
+        toCheck.add(row.tenantId);
+    const orphans = [];
+    const missing = [];
+    const wrongRole = [];
+    let checkedRows = 0;
+    for (const tenantId of [...toCheck].sort()) {
+        const expected = await expectedDerivedFor(handle, binding, tenantId);
+        const identity = (row) => `${row.principalClass}:${row.principalId}`;
+        const expectedById = new Map(expected.map((row) => [identity(row), row]));
+        const actual = await handle
+            .select({
+            principalId: memberships.principalId,
+            principalClass: memberships.principalClass,
+            role: primaryRoleKey(binding),
+            viaTenantId: memberships.viaTenantId,
+        })
+            .from(memberships)
+            .where(and(eq(memberships.tenantId, tenantId), eq(memberships.source, 'inherited')));
+        checkedRows += actual.length;
+        const actualById = new Map(actual.map((row) => [identity(row), row]));
+        for (const row of actual) {
+            const want = expectedById.get(identity(row));
+            if (!want) {
+                orphans.push({
+                    tenantId,
+                    principalId: row.principalId,
+                    role: row.role,
+                    viaTenantId: row.viaTenantId,
+                });
+                continue;
+            }
+            if (want.role !== row.role || want.viaTenantId !== row.viaTenantId) {
+                wrongRole.push({
+                    tenantId,
+                    principalId: row.principalId,
+                    actual: { role: row.role, viaTenantId: row.viaTenantId },
+                    expected: { role: want.role, viaTenantId: want.viaTenantId },
+                });
+            }
+        }
+        for (const row of expected) {
+            if (!actualById.has(identity(row))) {
+                missing.push({
+                    tenantId,
+                    principalId: row.principalId,
+                    role: row.role,
+                    viaTenantId: row.viaTenantId,
+                });
+            }
+        }
+    }
+    return {
+        orphans,
+        missing,
+        wrongRole,
+        checkedTenants: toCheck.size,
+        checkedRows,
+    };
+}

package/dist/resource-access.d.ts

@@ -0,0 +1,344 @@
+import type { DbOrTx, Scope } from './scoped.js';
+import { type Access, type Result } from './types.js';
+/** Every surface consumes the same request-time evaluator and canonical stored assignments. */
+export declare function resourceAccessFor(access: Access, tx: DbOrTx, db: DbOrTx, scopeColumn: Scope['column']): Promise<{
+    foreignPolicy: boolean;
+    evaluator: import("@wtfalch/authz").ResourceAccess<string>;
+    teams: {
+        id: string;
+        tenantId: string;
+        parentId: string | null;
+        name: string;
+        archivedAt: Date | null;
+        createdAt: Date;
+    }[];
+    participants: {
+        tenantId: string;
+        teamId: string;
+        principalId: string;
+        principalClass: string;
+    }[];
+    roleRows: {
+        permissions: {
+            permission: string;
+            relation: "any" | "owner" | "actor" | "subject";
+        }[];
+        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;
+    }[];
+    assignmentRows: {
+        id: string;
+        tenantId: string;
+        applicationId: string;
+        platformId: string;
+        roleId: string;
+        principalId: string | null;
+        principalClass: string | null;
+        teamId: string | null;
+        recipientDescendants: boolean;
+        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;
+        };
+        source: string;
+        viaTenantId: string | null;
+        primary: boolean;
+        expiresAt: Date | null;
+        createdBy: string | null;
+        createdAt: Date;
+    }[];
+    grants: {
+        id: string;
+        applicationId: string;
+        platformId: string;
+        boundary: {
+            kind: "organisation";
+            organisationId: string;
+            descendants?: boolean | undefined;
+        } | {
+            kind: "organisations";
+            organisationIds: string[];
+        } | {
+            kind: "platform";
+        };
+        permission: string;
+        recipient: {
+            kind: "principal";
+            principal: {
+                id: string;
+                class: "human" | "api_key" | "agent" | "service";
+            };
+        } | {
+            kind: "team";
+            teamId: string;
+            descendants: boolean;
+        };
+        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";
+        constraints?: ({
+            kind: "organisation";
+        } | {
+            kind: "team";
+            teamId: string;
+            descendants: boolean;
+        } | {
+            kind: "own_teams";
+            descendants: boolean;
+        } | {
+            kind: "resource";
+            resourceType: string;
+            resourceId: string;
+        })[] | undefined;
+        startsAt?: number | undefined;
+        expiresAt?: number | undefined;
+        conditions?: ({
+            kind: "attribute";
+            attribute: string;
+            in: string[];
+        } | {
+            kind: "schedule";
+            timeZone: string;
+            windows: {
+                days: ("mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun")[];
+                from: string;
+                to: string;
+            }[];
+        })[] | undefined;
+        guest?: true | undefined;
+        budget?: {
+            limit: number;
+            windowSeconds: number;
+        } | undefined;
+    }[];
+    identities: Map<string, {
+        id: string;
+        class: "human";
+    }>;
+}>;
+export declare function resourceOverview(access: Access, db: DbOrTx, scopeColumn: Scope['column']): Promise<{
+    teams: {
+        parentId: string | null;
+        canUpdate: boolean;
+        canCreateChild: boolean;
+        canAddPeople: boolean;
+        canRemovePeople: boolean;
+        canArchive: boolean;
+        canReadPeople: boolean;
+        id: string;
+        tenantId: string;
+        name: string;
+        archivedAt: Date | null;
+        createdAt: Date;
+    }[];
+    participants: {
+        tenantId: string;
+        teamId: string;
+        principalId: string;
+        principalClass: string;
+    }[];
+    roles: {
+        permissions: {
+            permission: string;
+            relation: "any" | "owner" | "actor" | "subject";
+        }[];
+        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;
+    }[];
+    assignments: {
+        id: string;
+        tenantId: string;
+        applicationId: string;
+        platformId: string;
+        roleId: string;
+        principalId: string | null;
+        principalClass: string | null;
+        teamId: string | null;
+        recipientDescendants: boolean;
+        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;
+        };
+        source: string;
+        viaTenantId: string | null;
+        primary: boolean;
+        expiresAt: Date | null;
+        createdBy: string | null;
+        createdAt: Date;
+    }[];
+    canReadRoles: boolean;
+    canReadTeams: boolean;
+    canCreateTeam: boolean;
+    canCreateRole: boolean;
+    canAssign: boolean;
+    canUnassign: boolean;
+    canDeleteRoles: boolean;
+    canEditTeams: boolean;
+    canEditRoles: boolean;
+    canReadAudit: boolean;
+}>;
+export declare function saveAppRole(access: Access, db: DbOrTx, scopeColumn: Scope['column'], input: unknown): Promise<Result<{
+    id: string;
+}>>;
+export declare function assignAppRole(access: Access, db: DbOrTx, scopeColumn: Scope['column'], input: unknown): Promise<Result<{
+    id: string;
+}>>;
+export declare function removeAppAssignment(access: Access, db: DbOrTx, scopeColumn: Scope['column'], id: string): Promise<Result<void>>;
+export declare function deleteAppRole(access: Access, db: DbOrTx, scopeColumn: Scope['column'], id: string): Promise<Result<void>>;
+export declare function saveTeam(access: Access, db: DbOrTx, scopeColumn: Scope['column'], input: unknown): Promise<Result<{
+    id: string;
+}>>;
+export declare function archiveTeam(access: Access, db: DbOrTx, scopeColumn: Scope['column'], id: string): Promise<Result<void>>;
+export declare function changeTeamParticipant(access: Access, db: DbOrTx, scopeColumn: Scope['column'], input: unknown): Promise<Result<void>>;
+export declare function scopedAuditLog(access: Access, db: DbOrTx, scopeColumn: Scope['column'], options?: {
+    id?: string;
+    limit?: number;
+    after?: {
+        occurredAt: Date;
+        id: number;
+    };
+}): Promise<{
+    items: {
+        id: number;
+        occurredAt: Date;
+        action: string;
+        outcome: string;
+        teamId: string | null;
+    }[];
+    next: {
+        occurredAt: Date;
+        id: number;
+    } | null;
+} | null>;