@wtfalch/authz-store 0.2.1 → 0.3.0

package/dist/person-records.d.ts

@@ -0,0 +1,186 @@
+import type { DbOrTx } from './scoped.js';
+import { type Access } from './types.js';
+/**
+ * The grants compiler (authz#83 wave 10a), moved from Boule's own
+ * `src/lib/authz/grants.ts`: `personRecordFor`, the person page's one read
+ * of every grant a human principal holds in one organisation, with its
+ * provenance and the teams they participate in, and `teamRecordFor`, the
+ * team page's own read of what one team is, its place in the hierarchy, who
+ * is in it, and what app access is scoped to it. `src/grants.ts` is a
+ * different file already: the `authz_grants` table and `guestGrants`, grants
+ * stored per person rather than compiled from a role. This file does not
+ * touch that one, on purpose (decision 1).
+ *
+ * **Fresh, scoped queries, not `access.policyState`.** `loadPolicyState`
+ * already pulls this tenant's whole assignment and membership tables into
+ * every request's `Access` (see `policy-access.ts`), but leaning on that here
+ * would make this reader's cost a fact about what else the request happened
+ * to load rather than about what it asked for. `authz_assignments_principal_idx`
+ * and `memberships`'s own primary key both cover `(tenant_id, principal_class,
+ * principal_id)`, so asking by principal directly is the same one-row-range
+ * lookup other readers already use, and it stays true if `loadPolicyState` is
+ * ever changed to stop loading everything.
+ *
+ * **`null`/`[]` is a list convention; this returns one record.** Every other
+ * reader answers "not yours to read" with `null` and "nothing here" with
+ * `[]`, because both are lists. A single record has no empty-list shape to
+ * fall back on, so this returns a small discriminated result instead of
+ * overloading `null` to mean two different refusals — a caller that cannot
+ * tell "you may not see this" from "this does not exist" has not been told
+ * anything.
+ *
+ * **`profiles` is a host port, `PeopleDirectory` (decision 3).** The store
+ * has no `profiles` table of its own; a host's own people directory answers
+ * the two questions this file used to ask Boule's `profiles` table directly.
+ */
+/** What a host must supply about its people, for both grant provenance and a person's own display fields. Reused for both `resolveActorNames` and `personRecordFor`'s own profile lookup, rather than a second port for the same table. */
+export interface PeopleDirectory {
+    people(ids: readonly string[]): Promise<ReadonlyMap<string, {
+        readonly displayName: string | null;
+        readonly email: string | null;
+        readonly lastSeenAt: Date | null;
+    }>>;
+}
+export interface GrantPermission {
+    readonly permission: string;
+    readonly label: string;
+    readonly relation: string;
+}
+export interface PersonGrant {
+    readonly id: string;
+    readonly roleKey: string;
+    readonly roleLabel: string;
+    /** The organisation-role grant every member holds exactly one of, shown on the front as "standing". */
+    readonly primary: boolean;
+    /** Never a raw principal id — resolved to a name, a credential's name, or a truthful sentence. */
+    readonly grantedBy: string;
+    readonly grantedAt: Date;
+    readonly expiresAt: Date | null;
+    readonly source: string;
+    readonly viaTenantName: string | null;
+    readonly permissions: readonly GrantPermission[];
+}
+export interface PersonTeam {
+    readonly teamId: string;
+    readonly teamName: string;
+    readonly parentTeamName: string | null;
+}
+export interface PersonRecord {
+    readonly principalId: string;
+    readonly display: string;
+    readonly email: string | null;
+    readonly tenantName: string;
+    /** The primary grant's role label — the front's standing pill. */
+    readonly standing: string;
+    readonly source: string;
+    readonly viaTenantName: string | null;
+    readonly joinedAt: Date;
+    readonly lastSeenAt: Date | null;
+    readonly grants: readonly PersonGrant[];
+    readonly teams: readonly PersonTeam[];
+    /**
+     * How many of this person's team memberships were dropped by the
+     * `teams.people:read` filter below `teams`, not because they do not
+     * exist. A viewer who may see a team but not its people is told so, never
+     * handed a `teams` list that reads identically to "this person is in no
+     * teams at all".
+     */
+    readonly hiddenTeams: number;
+}
+export type PersonRecordResult = {
+    readonly ok: true;
+    readonly person: PersonRecord;
+} | {
+    readonly ok: false;
+    readonly reason: 'no_permission' | 'not_found';
+};
+export declare function personRecordFor(access: Access, db: DbOrTx, directory: PeopleDirectory, personId: string): Promise<PersonRecordResult>;
+/**
+ * The team page's own read: what one team is, its place in the hierarchy,
+ * who is in it, and what app access is scoped to it -- the same three kinds
+ * of fact `personRecordFor` resolves for a person, read for a team instead.
+ *
+ * **Gated per team, not per organisation, and that is the whole reason this
+ * is a separate function rather than a second branch of `personRecordFor`.**
+ * `members:read` (what gates the person page) has no scope narrower than the
+ * organisation in a host's own resource catalogue; `teams:read` genuinely
+ * does, so two administrators in the same organisation can legitimately see
+ * different teams. A resource overview already filters its own `teams` list
+ * the same way; this is that same check, asked about one team a caller
+ * already has an id for rather than every team at once.
+ *
+ * **A refused team and a nonexistent one both read `not_found`, unlike
+ * `personRecordFor`'s `no_permission`/`not_found` split.** That split is
+ * safe there because it is unreachable in practice: the person page's own
+ * outer gate already demands the exact organisation-wide `members:read` this
+ * reader checks again, so the "no permission" branch can never actually be
+ * taken. Here the two are genuinely different, reachable requests -- a
+ * viewer scoped to Team A can call this function for Team B by typing its
+ * id in the URL -- and a reader that told the two apart would confirm to
+ * that viewer that Team B exists at all. Collapsing both into `not_found` is
+ * the same anti-enumeration posture `personRecordFor` already keeps for a
+ * cross-tenant or malformed id; it just has a real case to earn it here.
+ *
+ * **`peopleReadable` names `teams.people:read`'s own refusal, kept apart
+ * from whether the team genuinely has zero members.** A viewer who can read
+ * this team but not its people must see something different from a team
+ * with no people in it -- the exact defect the person page's own
+ * `hiddenTeams` exists to fix, mirrored here at the single-team granularity
+ * instead of counted across many. `hiddenChildTeams` is the same shape one
+ * level down the hierarchy.
+ */
+export interface TeamGrant {
+    readonly id: string;
+    readonly roleLabel: string;
+    /** Never a raw principal id -- resolved to a name, a credential's name, or a truthful sentence, the same as `PersonGrant.grantedBy`. */
+    readonly grantedBy: string;
+    readonly grantedAt: Date;
+    readonly expiresAt: Date | null;
+    readonly source: string;
+    readonly viaTenantName: string | null;
+    readonly permissions: readonly GrantPermission[];
+}
+/**
+ * A team's own parent, told apart three ways rather than folded into one
+ * nullable field: `root` (no parent), `named` (a parent this viewer can also
+ * read), and `hidden` (a parent exists but `teams:read` refuses it to this
+ * viewer). Conflating `hidden` into `root` would print "no parent" for a
+ * team that has one, exactly the silent-zero shape this file's readers
+ * otherwise refuse to produce.
+ */
+export type TeamParent = {
+    readonly kind: 'root';
+} | {
+    readonly kind: 'named';
+    readonly id: string;
+    readonly name: string;
+} | {
+    readonly kind: 'hidden';
+};
+export interface TeamRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly parent: TeamParent;
+    readonly createdAt: Date;
+    readonly canAddPeople: boolean;
+    readonly canRemovePeople: boolean;
+    /** `teams.people:read` for this specific team; see the function docblock. */
+    readonly peopleReadable: boolean;
+    /** Principal ids only -- names are the caller's own membership lookup. Empty whenever `peopleReadable` is false. */
+    readonly people: readonly string[];
+    readonly childTeams: readonly {
+        readonly id: string;
+        readonly name: string;
+    }[];
+    /** Child teams that exist but this viewer cannot read -- the same shape as `peopleReadable`, one level down the tree. */
+    readonly hiddenChildTeams: number;
+    readonly access: readonly TeamGrant[];
+}
+export type TeamRecordResult = {
+    readonly ok: true;
+    readonly team: TeamRecord;
+} | {
+    readonly ok: false;
+    readonly reason: 'not_found';
+};
+export declare function teamRecordFor(access: Access, db: DbOrTx, directory: PeopleDirectory, teamId: string): Promise<TeamRecordResult>;

package/dist/person-records.js

@@ -0,0 +1,263 @@
+import { and, asc, desc, eq, inArray, isNull, sql } from 'drizzle-orm';
+import { permitsRead } from './policy-access.js';
+import { policyAssignments, policyRoles } from './policy-schema.js';
+import { accessTeamMembers, accessTeams } from './resource-schema.js';
+import { credentials, memberships } from './schema.js';
+import { tenantById } from './tenants.js';
+import { isUuid } from './types.js';
+/** `grantedBy`/`createdBy` name only who acted, never why they still can; resolve it truthfully or say so. */
+async function resolveActorNames(db, ids, directory) {
+    if (ids.length === 0)
+        return new Map();
+    const [people, creds] = await Promise.all([
+        directory.people(ids),
+        db
+            .select({ id: credentials.id, name: credentials.name })
+            .from(credentials)
+            // `credentials.id` is a uuid column; `ids` holds arbitrary principal
+            // ids (a real Zitadel subject id is a string, not uuid-shaped), so the
+            // comparison casts the *column* to text -- the same direction other
+            // files' own `sql`${memberships.principalId} = ${credentials.id}::text``
+            // joins cast, and never the other way around. Parsing an arbitrary
+            // string as uuid instead throws Postgres's `22P02 invalid input syntax
+            // for type uuid`, which took Boule's whole Server Component down with
+            // it.
+            .where(inArray(sql `${credentials.id}::text`, ids)),
+    ]);
+    const names = new Map();
+    for (const [id, p] of people)
+        names.set(id, p.displayName ?? p.email ?? 'A person on this platform');
+    for (const c of creds)
+        if (!names.has(c.id))
+            names.set(c.id, `${c.name} (a credential)`);
+    return names;
+}
+function actorDisplay(id, names) {
+    if (!id)
+        return 'Set automatically, not by a person';
+    return names.get(id) ?? 'Someone no longer on this platform';
+}
+export async function personRecordFor(access, db, directory, personId) {
+    if (!(await permitsRead(access, db, 'members:read')))
+        return { ok: false, reason: 'no_permission' };
+    const [membershipRow] = await db
+        .select({
+        source: memberships.source,
+        viaTenantId: memberships.viaTenantId,
+        grantedBy: memberships.grantedBy,
+        createdAt: memberships.createdAt,
+    })
+        .from(memberships)
+        .where(and(eq(memberships.tenantId, access.tenant.id), eq(memberships.principalId, personId), eq(memberships.principalClass, 'human')))
+        .limit(1);
+    if (!membershipRow)
+        return { ok: false, reason: 'not_found' };
+    // Boule's own query ran an inner join against `profiles` here, so a member
+    // with no profile row was excluded from the result entirely. With the
+    // `PeopleDirectory` port there is no join to run; the same exclusion is
+    // this lookup coming up empty for `personId`.
+    const directoryRows = await directory.people([personId]);
+    const profile = directoryRows.get(personId);
+    if (!profile)
+        return { ok: false, reason: 'not_found' };
+    const assignmentRows = await db
+        .select({
+        id: policyAssignments.id,
+        source: policyAssignments.source,
+        viaTenantId: policyAssignments.viaTenantId,
+        primary: policyAssignments.primary,
+        expiresAt: policyAssignments.expiresAt,
+        createdAt: policyAssignments.createdAt,
+        createdBy: policyAssignments.createdBy,
+        roleKey: policyRoles.key,
+        roleLabel: policyRoles.name,
+        entries: policyRoles.entries,
+    })
+        .from(policyAssignments)
+        .innerJoin(policyRoles, eq(policyRoles.id, policyAssignments.roleId))
+        .where(and(eq(policyAssignments.tenantId, access.tenant.id), eq(policyAssignments.applicationId, access.binding.applicationId), eq(policyAssignments.platformId, access.binding.platformId), eq(policyAssignments.principalId, personId), eq(policyAssignments.principalClass, 'human')))
+        .orderBy(desc(policyAssignments.primary), asc(policyRoles.name));
+    const allTeamMemberRows = await db
+        .select({ teamId: accessTeamMembers.teamId })
+        .from(accessTeamMembers)
+        .where(and(eq(accessTeamMembers.tenantId, access.tenant.id), eq(accessTeamMembers.principalId, personId), eq(accessTeamMembers.principalClass, 'human')));
+    // Reading who is in a team is `teams.people:read`, checked per team the
+    // same way a resource overview filters its own `participants` — this
+    // reader does not get to skip that gate just because it reached the fact
+    // from a person rather than from a team. `access.authority` is the same
+    // scoped evaluator a request's own `Access` already carries.
+    const teamMemberRows = allTeamMemberRows.filter((row) => access.authority.allows('teams.people:read', {
+        applicationId: access.binding.applicationId,
+        platformId: access.binding.platformId,
+        organisationId: access.tenant.id,
+        type: 'team',
+        id: row.teamId,
+        teamId: row.teamId,
+    }));
+    // One small, tenant-bounded (max 1,000 teams) fetch to resolve names and
+    // one parent hop each, rather than a query per team.
+    const teamRows = teamMemberRows.length
+        ? await db.select().from(accessTeams).where(eq(accessTeams.tenantId, access.tenant.id))
+        : [];
+    const teamById = new Map(teamRows.map((t) => [t.id, t]));
+    const actorIds = [
+        ...new Set([membershipRow.grantedBy, ...assignmentRows.map((a) => a.createdBy)].filter((id) => !!id)),
+    ];
+    const actorNames = await resolveActorNames(db, actorIds, directory);
+    const viaTenantIds = [
+        ...new Set([membershipRow.viaTenantId, ...assignmentRows.map((a) => a.viaTenantId)].filter((id) => !!id)),
+    ];
+    const viaTenantNamePairs = await Promise.all(viaTenantIds.map(async (id) => [id, (await tenantById(db, id))?.name ?? null]));
+    const viaTenantNames = new Map(viaTenantNamePairs);
+    const viaName = (id) => id ? (viaTenantNames.get(id) ?? 'a parent organisation') : null;
+    const primaryRow = assignmentRows.find((a) => a.primary);
+    return {
+        ok: true,
+        person: {
+            principalId: personId,
+            display: profile.displayName ?? profile.email ?? 'A person on this platform',
+            email: profile.email,
+            tenantName: access.tenant.name,
+            standing: primaryRow?.roleLabel ?? 'No standing role',
+            source: membershipRow.source,
+            viaTenantName: viaName(membershipRow.viaTenantId),
+            joinedAt: membershipRow.createdAt,
+            lastSeenAt: profile.lastSeenAt,
+            grants: assignmentRows.map((a) => ({
+                id: a.id,
+                roleKey: a.roleKey,
+                roleLabel: a.roleLabel,
+                primary: a.primary,
+                grantedBy: actorDisplay(a.createdBy, actorNames),
+                grantedAt: a.createdAt,
+                expiresAt: a.expiresAt,
+                source: a.source,
+                viaTenantName: viaName(a.viaTenantId),
+                permissions: a.entries.map((entry) => ({
+                    permission: entry.permission,
+                    label: access.binding.catalogue[entry.permission]?.label ?? entry.permission,
+                    relation: entry.relation,
+                })),
+            })),
+            teams: teamMemberRows.map((row) => {
+                const team = teamById.get(row.teamId);
+                const parent = team?.parentId ? teamById.get(team.parentId) : undefined;
+                return {
+                    teamId: row.teamId,
+                    teamName: team?.name ?? 'A team that no longer exists',
+                    parentTeamName: parent?.name ?? null,
+                };
+            }),
+            hiddenTeams: allTeamMemberRows.length - teamMemberRows.length,
+        },
+    };
+}
+function teamTarget(access, teamId) {
+    return {
+        applicationId: access.binding.applicationId,
+        platformId: access.binding.platformId,
+        organisationId: access.tenant.id,
+        type: 'team',
+        id: teamId,
+        teamId,
+    };
+}
+export async function teamRecordFor(access, db, directory, teamId) {
+    // The id comes from the URL and `access_teams.id` is a uuid column, so a
+    // malformed id would raise 22P02 and render a 500. It names no team.
+    if (!isUuid(teamId))
+        return { ok: false, reason: 'not_found' };
+    const [row] = await db
+        .select()
+        .from(accessTeams)
+        .where(and(eq(accessTeams.tenantId, access.tenant.id), eq(accessTeams.id, teamId)))
+        .limit(1);
+    if (!row || row.archivedAt)
+        return { ok: false, reason: 'not_found' };
+    if (!access.authority.allows('teams:read', teamTarget(access, row.id)))
+        return { ok: false, reason: 'not_found' };
+    const peopleReadable = access.authority.allows('teams.people:read', teamTarget(access, row.id));
+    // `siblingTeams`: one small, tenant-bounded (max 1,000 teams) fetch,
+    // reused for both the parent lookup and the child list -- the same trade
+    // `personRecordFor` makes for a person's own teams, rather than a query
+    // per relationship.
+    const [memberRows, siblingTeams, assignmentRows] = await Promise.all([
+        peopleReadable
+            ? db
+                .select({ principalId: accessTeamMembers.principalId })
+                .from(accessTeamMembers)
+                .where(and(eq(accessTeamMembers.tenantId, access.tenant.id), eq(accessTeamMembers.teamId, row.id)))
+            : Promise.resolve([]),
+        db
+            .select()
+            .from(accessTeams)
+            .where(and(eq(accessTeams.tenantId, access.tenant.id), isNull(accessTeams.archivedAt))),
+        db
+            .select({
+            id: policyAssignments.id,
+            source: policyAssignments.source,
+            viaTenantId: policyAssignments.viaTenantId,
+            expiresAt: policyAssignments.expiresAt,
+            createdAt: policyAssignments.createdAt,
+            createdBy: policyAssignments.createdBy,
+            roleLabel: policyRoles.name,
+            entries: policyRoles.entries,
+        })
+            .from(policyAssignments)
+            .innerJoin(policyRoles, eq(policyRoles.id, policyAssignments.roleId))
+            .where(and(eq(policyAssignments.tenantId, access.tenant.id), eq(policyAssignments.applicationId, access.binding.applicationId), eq(policyAssignments.platformId, access.binding.platformId), eq(policyAssignments.teamId, row.id)))
+            .orderBy(asc(policyRoles.name)),
+    ]);
+    let parent;
+    if (!row.parentId) {
+        parent = { kind: 'root' };
+    }
+    else {
+        const parentRow = siblingTeams.find((t) => t.id === row.parentId);
+        parent =
+            parentRow && access.authority.allows('teams:read', teamTarget(access, parentRow.id))
+                ? { kind: 'named', id: parentRow.id, name: parentRow.name }
+                : { kind: 'hidden' };
+    }
+    const children = siblingTeams.filter((t) => t.parentId === row.id);
+    const visibleChildren = children.filter((t) => access.authority.allows('teams:read', teamTarget(access, t.id)));
+    const actorIds = [
+        ...new Set(assignmentRows.map((a) => a.createdBy).filter((id) => !!id)),
+    ];
+    const actorNames = await resolveActorNames(db, actorIds, directory);
+    const viaTenantIds = [
+        ...new Set(assignmentRows.map((a) => a.viaTenantId).filter((id) => !!id)),
+    ];
+    const viaTenantNamePairs = await Promise.all(viaTenantIds.map(async (id) => [id, (await tenantById(db, id))?.name ?? null]));
+    const viaTenantNames = new Map(viaTenantNamePairs);
+    const viaName = (id) => id ? (viaTenantNames.get(id) ?? 'a parent organisation') : null;
+    return {
+        ok: true,
+        team: {
+            id: row.id,
+            name: row.name,
+            parent,
+            createdAt: row.createdAt,
+            canAddPeople: access.authority.allows('teams.people:add', teamTarget(access, row.id)),
+            canRemovePeople: access.authority.allows('teams.people:remove', teamTarget(access, row.id)),
+            peopleReadable,
+            people: memberRows.map((m) => m.principalId),
+            childTeams: visibleChildren.map((t) => ({ id: t.id, name: t.name })),
+            hiddenChildTeams: children.length - visibleChildren.length,
+            access: assignmentRows.map((a) => ({
+                id: a.id,
+                roleLabel: a.roleLabel,
+                grantedBy: actorDisplay(a.createdBy, actorNames),
+                grantedAt: a.createdAt,
+                expiresAt: a.expiresAt,
+                source: a.source,
+                viaTenantName: viaName(a.viaTenantId),
+                permissions: a.entries.map((entry) => ({
+                    permission: entry.permission,
+                    label: access.binding.catalogue[entry.permission]?.label ?? entry.permission,
+                    relation: entry.relation,
+                })),
+            })),
+        },
+    };
+}

package/dist/platform.d.ts

@@ -0,0 +1,20 @@
+import type { DbOrTx, Scope } from './scoped.js';
+import { type Access, type Result } from './types.js';
+/**
+ * The operator tenant's current freeze flag, or null for someone who may not
+ * switch it (the console then does not draw the switch). A read is never
+ * affected by the freeze itself.
+ */
+export declare function platformFrozen(access: Access, db: DbOrTx): Promise<boolean | null>;
+/**
+ * The platform write freeze (0.9.0, SCOPED-ACCESS.md "Write freeze"), gated on
+ * `platform:freeze`. That permission survives the freeze, so the operator who
+ * froze the platform can always unfreeze it.
+ *
+ * Setting the value it already has writes nothing: no row update, no event.
+ * A change writes `platform.frozen` or `platform.unfrozen` as a platform row
+ * (tenant_id null) in the same transaction as the update.
+ */
+export declare function setPlatformFrozen(access: Access, db: DbOrTx, scopeColumn: Scope['column'], frozen: boolean): Promise<Result<{
+    changed: boolean;
+}>>;

package/dist/platform.js

@@ -0,0 +1,65 @@
+import { eq } from 'drizzle-orm';
+import { record } from './audit.js';
+import { permitsPlatform, refreshAccess } from './policy-access.js';
+import { tenants } from './schema.js';
+import { done, refused } from './types.js';
+/**
+ * The operator tenant's current freeze flag, or null for someone who may not
+ * switch it (the console then does not draw the switch). A read is never
+ * affected by the freeze itself.
+ */
+export async function platformFrozen(access, db) {
+    if (!permitsPlatform(access, 'platform:freeze'))
+        return null;
+    const [operator] = await db
+        .select({ frozen: tenants.frozen })
+        .from(tenants)
+        .where(eq(tenants.kind, 'operator'))
+        .limit(1);
+    return operator?.frozen ?? false;
+}
+/**
+ * The platform write freeze (0.9.0, SCOPED-ACCESS.md "Write freeze"), gated on
+ * `platform:freeze`. That permission survives the freeze, so the operator who
+ * froze the platform can always unfreeze it.
+ *
+ * Setting the value it already has writes nothing: no row update, no event.
+ * A change writes `platform.frozen` or `platform.unfrozen` as a platform row
+ * (tenant_id null) in the same transaction as the update.
+ */
+export async function setPlatformFrozen(access, db, scopeColumn, frozen) {
+    if (access.context === 'break_glass') {
+        return refused('break_glass', 'A break-glass session never freezes the platform.');
+    }
+    if (!permitsPlatform(access, 'platform:freeze')) {
+        return refused('no_permission', 'You do not have permission to freeze the platform.');
+    }
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permitsPlatform(fresh, 'platform:freeze')) {
+            return refused('no_permission', 'You do not have permission to freeze the platform.');
+        }
+        const [operator] = await tx
+            .select({ id: tenants.id, frozen: tenants.frozen })
+            .from(tenants)
+            .where(eq(tenants.kind, 'operator'))
+            .for('update');
+        if (!operator)
+            return refused('tenant_not_found', 'There is no operator organisation.');
+        if (operator.frozen === frozen)
+            return done({ changed: false }, []);
+        await tx
+            .update(tenants)
+            .set({ frozen, updatedAt: new Date() })
+            .where(eq(tenants.id, operator.id));
+        await record(tx, fresh, {
+            action: frozen ? 'platform.frozen' : 'platform.unfrozen',
+            tenantId: null,
+            targetType: 'tenant',
+            targetId: operator.id,
+            before: { frozen: operator.frozen },
+            after: { frozen },
+        });
+        return done({ changed: true }, []);
+    });
+}