@wtfalch/authz-store 0.2.1 → 0.3.0

package/dist/memberships.js

@@ -0,0 +1,272 @@
+import { and, eq } from 'drizzle-orm';
+import { identityWhere, primaryAssignment, roleAssignmentRefusal, writeParticipationPolicy, writePrimaryAssignment, } from './assignments.js';
+import { record } from './audit.js';
+import { endSessionsFor } from './break-glass.js';
+import { changeRoleRow, deleteMembershipRow, guardStaysHeldRow, insertMembershipRow, membersOfRow, } from './membership-rows.js';
+import { loadAccess, permits, permitsRead, policyAssignment, policyRole, refreshAccess, } from './policy-access.js';
+import { propagateMembershipChange, writerFromAccess } from './propagate.js';
+import { isCustomRoleKey } from './role-keys.js';
+import { roleDef } from './roles.js';
+import { memberships } from './schema.js';
+import { tenantById } from './tenants.js';
+import { childrenOf } from './tree.js';
+import { done, refused, tenantTag } from './types.js';
+/**
+ * The roster read, delegated to this package's own `membersOfRow` (same
+ * query shape this file used to run itself, ported into `membership-rows.ts`
+ * from `@wtfalch/people`'s `membersOf`). Its `role`/`roleLabel` come back
+ * `null` where this file's own `primaryRoleKey` subquery and `names` lookup
+ * used to read `''`/`'Unavailable role'` for "no current primary
+ * assignment" — mapped back to those exact values here so every caller of
+ * `Member` keeps reading the same two fallbacks it always has.
+ */
+export async function membersOf(access, db, directory) {
+    if (!(await permitsRead(access, db, 'members:read')))
+        return null;
+    const rows = await membersOfRow(db, access.tenant.id, directory, access.binding);
+    return rows.map((r) => ({
+        ...r,
+        role: r.role ?? '',
+        roleLabel: r.roleLabel ?? 'Unavailable role',
+    }));
+}
+/**
+ * The viewer's own membership record in this organisation -- when they
+ * joined, and whether their standing here came from this organisation
+ * directly or from a parent. The organisation's home page is gated by
+ * requiring tenant membership alone (D2: "which one this is, and what the
+ * person looking at it is to it"), not by a permission, and reading your
+ * own row is not a further permission decision either -- the same
+ * reasoning that lets `access.role` itself go unchecked.
+ *
+ * **`null` when there is no row to read**, chiefly a break-glass session:
+ * `loadAccess` widens `Access` for an operator's support session without
+ * inserting a `memberships` row, so there is nothing here for that case --
+ * not a refusal, an absence, and a break-glass banner already explains why.
+ */
+export async function selfStanding(access, db) {
+    const [membership] = await db
+        .select({
+        source: memberships.source,
+        viaTenantId: memberships.viaTenantId,
+        joinedAt: memberships.createdAt,
+    })
+        .from(memberships)
+        .where(and(eq(memberships.tenantId, access.tenant.id), eq(memberships.principalId, access.actor.id), eq(memberships.principalClass, access.actor.class)))
+        .limit(1);
+    if (!membership)
+        return null;
+    const viaTenantName = membership.viaTenantId
+        ? ((await tenantById(db, membership.viaTenantId))?.name ?? 'a parent organisation')
+        : null;
+    return { joinedAt: membership.joinedAt, source: membership.source, viaTenantName };
+}
+const noAuthority = () => refused('no_permission', 'You no longer have permission to change this membership.');
+/**
+ * Protected roles cannot lose their last independent recovery owner.
+ * Delegated to `membership-rows.ts`'s `guardStaysHeldRow`, which runs the
+ * exact same coverage count this file used to run itself via `./owners.js`'
+ * `ownerCoverage`/`ownerSeatCovered`.
+ */
+export async function guardStaysHeld(tx, binding, tenantId, roles, principal) {
+    const guards = new Set(roles.flatMap((r) => r.guards));
+    return guardStaysHeldRow(tx, binding, tenantId, principal, guards);
+}
+export async function grantMembership(access, db, scopeColumn, profiles, options) {
+    const principal = {
+        id: options.principalId,
+        class: options.principalClass ?? 'human',
+    };
+    if (principal.class !== 'human')
+        return refused('not_a_person', 'Create a credential with its own issuer and secret.');
+    if (access.context === 'break_glass')
+        return refused('break_glass', 'Support sessions cannot change access.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass')
+            return noAuthority();
+        const [existing] = await tx
+            .select()
+            .from(memberships)
+            .where(identityWhere(fresh.tenant.id, principal))
+            .limit(1);
+        if (existing)
+            return refused(existing.source === 'inherited' ? 'inherited' : 'already_member', 'This person already participates here.');
+        const role = await roleDef(tx, fresh.binding, fresh.tenant, options.role);
+        if (!role)
+            return refused('unknown_role', 'This role no longer exists.');
+        // Not `!role.builtIn`: a starter role (ADR 0016) is `built_in: false` for
+        // a tenant created after that change but is still app-defined, not
+        // tenant-authored, so it can still cross organisation boundaries.
+        if (isCustomRoleKey(role.key) && (await childrenOf(tx, fresh.tenant.id)).length)
+            return refused('custom_role_with_children', 'Custom roles cannot be inherited by another organisation.');
+        const reason = roleAssignmentRefusal(fresh, role, primaryAssignment(role, principal), 'members:grant');
+        if (reason)
+            return refused(reason, 'You cannot delegate that role to this person.');
+        if (!(await profiles.personKnown(principal.id)))
+            return refused('unknown_person', 'This person has never signed in here.');
+        // The row insert itself is `membership-rows.ts`'s `insertMembershipRow`;
+        // the role assignment and participation-policy writes it deliberately
+        // leaves to the host (people's own doc comment: "out of this package's
+        // scope") run from `onGranted`, inside the same row-insert transaction
+        // as before.
+        const granted = await insertMembershipRow(tx, {
+            tenantId: fresh.tenant.id,
+            tenantName: fresh.tenant.name,
+            principal,
+            grantedBy: fresh.actor.id,
+            onGranted: async () => {
+                await writePrimaryAssignment(tx, fresh.binding, role, principal, {
+                    createdBy: fresh.actor.id,
+                });
+                await writeParticipationPolicy(tx, fresh.binding, fresh.tenant.id, principal);
+            },
+        });
+        // Unreachable in practice: `existing` above already checked this inside
+        // the same transaction. Guarded rather than asserted, since a throw here
+        // would surface as an unhandled 500 instead of the refusal this action
+        // already has a message for.
+        if (!granted.ok)
+            return refused('already_member', 'This person already participates here.');
+        await record(tx, fresh, {
+            action: 'membership.created',
+            tenantId: fresh.tenant.id,
+            targetType: 'membership',
+            targetId: principal.id,
+            after: { roleId: role.id, role: role.key, principalClass: principal.class },
+        });
+        const tags = await propagateMembershipChange(tx, fresh.binding, writerFromAccess(fresh), fresh.tenant.id, principal.id);
+        return done(undefined, [tenantTag(fresh.tenant.id), ...tags]);
+    });
+}
+export async function changeRole(access, db, scopeColumn, options) {
+    const principal = {
+        id: options.principalId,
+        class: options.principalClass ?? 'human',
+    };
+    if (access.context === 'break_glass')
+        return refused('break_glass', 'Support sessions cannot change access.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass')
+            return noAuthority();
+        const member = fresh.policyState.memberRows.find((m) => m.principalId === principal.id && m.principalClass === principal.class);
+        if (!member)
+            return refused('not_found', 'This principal does not participate here.');
+        if (member.source !== 'direct')
+            return refused('inherited', 'Manage this membership at its parent organisation.');
+        const previous = fresh.policyState.assignmentRows.find((a) => a.primary && a.principalId === principal.id && a.principalClass === principal.class);
+        const before = previous
+            ? fresh.policyState.roleRows.find((r) => r.id === previous.roleId)
+            : undefined;
+        const role = await roleDef(tx, fresh.binding, fresh.tenant, options.role);
+        if (!role)
+            return refused('unknown_role', 'This role no longer exists.');
+        // Not `!role.builtIn`: a starter role (ADR 0016) is `built_in: false` for
+        // a tenant created after that change but is still app-defined, not
+        // tenant-authored, so it can still cross organisation boundaries.
+        if (isCustomRoleKey(role.key) && (await childrenOf(tx, fresh.tenant.id)).length)
+            return refused('custom_role_with_children', 'Custom roles cannot be inherited by another organisation.');
+        const self = principal.id === fresh.actor.id && principal.class === fresh.actor.class;
+        if (before && previous && !self) {
+            const reason = roleAssignmentRefusal(fresh, policyRole(before), policyAssignment(previous), 'members:revoke');
+            if (reason)
+                return refused(reason, 'You cannot remove that role.');
+        }
+        const reason = roleAssignmentRefusal(fresh, role, primaryAssignment(role, principal, previous?.expiresAt?.getTime()), self ? null : 'members:grant');
+        if (reason)
+            return refused(self ? 'self_promotion' : reason, 'You cannot delegate that role.');
+        if (before &&
+            before.id !== role.id &&
+            !(await guardStaysHeld(tx, fresh.binding, fresh.tenant.id, [policyRole(before)], principal)))
+            return refused('last_owner', 'Appoint another independent owner first.');
+        // The upsert itself is `membership-rows.ts`'s `changeRoleRow` (one
+        // `INSERT ... ON CONFLICT DO UPDATE` on `authz_assignments_primary_idx`,
+        // same target this file's own `writePrimaryAssignment` deleted-then-
+        // inserted against); `compileRoleGrants`'s validation already ran above,
+        // inside `roleAssignmentRefusal`, so nothing here re-checks it.
+        const changed = await changeRoleRow(tx, {
+            tenantId: fresh.tenant.id,
+            principal,
+            binding: fresh.binding,
+            roleId: role.id,
+            expiresAt: previous?.expiresAt,
+            createdBy: fresh.actor.id,
+        });
+        // Unreachable in practice: `member` above already confirmed this
+        // principal's direct row exists inside the same transaction.
+        if (!changed.ok)
+            return refused('not_found', 'This principal does not participate here.');
+        await record(tx, fresh, {
+            action: 'membership.role_changed',
+            tenantId: fresh.tenant.id,
+            targetType: 'membership',
+            targetId: principal.id,
+            before: { roleId: before?.id ?? null },
+            after: { roleId: role.id, role: role.key },
+        });
+        if (fresh.tenant.kind === 'operator' && principal.class === 'human') {
+            const afterAccess = await loadAccess(tx, fresh.binding, db, scopeColumn, { ...principal, display: principal.id, email: null, emailVerified: false }, fresh.tenant.id, false);
+            if (!afterAccess || !permits(afterAccess, 'break_glass:start'))
+                await endSessionsFor(tx, principal.id, 'the operator no longer holds support access');
+        }
+        const tags = await propagateMembershipChange(tx, fresh.binding, writerFromAccess(fresh), fresh.tenant.id, principal.id);
+        return done(undefined, [tenantTag(fresh.tenant.id), ...tags]);
+    });
+}
+export async function removeMembership(access, db, scopeColumn, options) {
+    const principal = {
+        id: options.principalId,
+        class: options.principalClass ?? 'human',
+    };
+    if (access.context === 'break_glass')
+        return refused('break_glass', 'Support sessions cannot change access.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass')
+            return noAuthority();
+        const member = fresh.policyState.memberRows.find((m) => m.principalId === principal.id && m.principalClass === principal.class);
+        if (!member)
+            return refused('not_found', 'This principal does not participate here.');
+        if (member.source !== 'direct')
+            return refused('inherited', 'Manage this membership at its parent organisation.');
+        const self = principal.id === fresh.actor.id && principal.class === fresh.actor.class;
+        if (!self && !permits(fresh, 'members:revoke'))
+            return noAuthority();
+        const assignments = fresh.policyState.assignmentRows.filter((a) => a.principalId === principal.id && a.principalClass === principal.class);
+        const assignedRoles = assignments.map((assignment) => {
+            const row = fresh.policyState.roleRows.find((r) => r.id === assignment.roleId);
+            if (!row)
+                throw new Error('Assignment refers to an unknown role');
+            return { assignment, role: policyRole(row) };
+        });
+        const roles = assignedRoles.map((item) => item.role);
+        if (!self &&
+            assignedRoles.some(({ assignment, role }) => roleAssignmentRefusal(fresh, role, policyAssignment(assignment), 'members:revoke')))
+            return refused('not_covered', 'You cannot remove this principal’s assignments.');
+        if (!(await guardStaysHeld(tx, fresh.binding, fresh.tenant.id, roles, principal)))
+            return refused('last_owner', 'Appoint another independent owner first.');
+        // The row delete itself is `membership-rows.ts`'s `deleteMembershipRow`;
+        // the `authz_assignments` FK to `memberships` is `ON DELETE CASCADE`
+        // (`scripts/authz-v2/store-adopt.mjs`'s adopted shape), so the primary
+        // and every secondary assignment go with it, same as the plain delete
+        // this replaced.
+        const removed = await deleteMembershipRow(tx, { tenantId: fresh.tenant.id, principal });
+        // Unreachable in practice: `member` above already confirmed this
+        // principal's direct row exists inside the same transaction.
+        if (!removed.ok)
+            return refused('not_found', 'This principal does not participate here.');
+        await record(tx, fresh, {
+            action: 'membership.ended',
+            tenantId: fresh.tenant.id,
+            targetType: 'membership',
+            targetId: principal.id,
+            before: { roleIds: roles.map((r) => r.id), principalClass: principal.class },
+            after: null,
+        });
+        if (fresh.tenant.kind === 'operator')
+            await endSessionsFor(tx, principal.id, 'the operator membership was removed');
+        const tags = await propagateMembershipChange(tx, fresh.binding, writerFromAccess(fresh), fresh.tenant.id, principal.id);
+        return done(undefined, [tenantTag(fresh.tenant.id), ...tags]);
+    });
+}

package/dist/nesting.d.ts

@@ -0,0 +1,124 @@
+import type { StorePolicy } from './policy.js';
+import type { DbOrTx, Scope } from './scoped.js';
+import { type DetachReportRow } from './tree.js';
+import type { Access, Result } from './types.js';
+/**
+ * The consent flow over `tree.ts`'s mechanism (D19, D22, X6 M5 and M6):
+ * propose, accept, decline, detach, and the two reads a members page and a
+ * console page need. Every write here locks the tenant rows it is about,
+ * refuses under a break-glass context (D8: no session ever changes who
+ * belongs or what holds what), and records exactly one `tenant.*` audit row
+ * plus one `membership.*` row per derived change `tree.ts` actually made.
+ *
+ * This file never reimplements the derived rule: `attachProblem`,
+ * `customRoleBlockers` and `recomputeDerived` (via `attachInTx`/`detachInTx`)
+ * are `tree.ts`'s and `tree-writes.ts`'s, called here, not copied.
+ *
+ * `db` and `scopeColumn` are the host's root handle and tenant-table
+ * registry (wave 1), taken as parameters rather than imported, the same as
+ * every other write module this campaign has moved. `policy: Pick<StorePolicy,
+ * 'maxDepth' | 'offered'>` is `attachProblem`'s own parameter (wave 4a),
+ * threaded through here for the two functions that call it.
+ */
+/** The closed set a proposal's `reason` is drawn from. `other` exists so the console is never stuck without a word for it. */
+export type AttachReason = 'reseller' | 'reorganisation' | 'onboarding' | 'other';
+/** Exported for a page's reason picker, so the closed set is declared once. */
+export declare const ATTACH_REASONS: readonly AttachReason[];
+export interface ProposeAttachOptions {
+    readonly childId: string;
+    readonly reason: string;
+    readonly reference: string;
+    /**
+     * Which tenant is proposed as the parent. Only meaningful when
+     * `access.tenant.kind` is `'operator'`: an operator's own tenant can never
+     * be the parent (`attachProblem`'s job to refuse), so an operator must name
+     * one from the console. Ignored for every other caller, whose own tenant is
+     * the parent (D19: "the actor's tenant is the parent").
+     */
+    readonly parentId?: string;
+}
+/**
+ * Proposes that `access.tenant` (or, for an operator, `options.parentId`)
+ * hold `options.childId`. Two refusals beyond the ordinary ones apply only to
+ * an operator actor (M5): an operator's own tenant can never be the parent,
+ * caught by `attachProblem` the same as any other pairing; and an operator
+ * who personally holds a direct role at the proposed parent may not propose
+ * it, because accepting would hand that same operator a standing derived
+ * role in the child the moment it goes through, exactly the reach into
+ * membership D8 forbids operators otherwise.
+ */
+export declare function proposeAttach(access: Access, db: DbOrTx, scopeColumn: Scope['column'], policy: Pick<StorePolicy, 'maxDepth' | 'offered'>, options: ProposeAttachOptions): Promise<Result<{
+    id: string;
+}>>;
+/**
+ * Accepts a pending proposal. `access` must already be resolved against the
+ * child (the child's own owner is who may accept), so a proposal for a
+ * different tenant is refused as `wrong_tenant` rather than acted on.
+ * Re-runs `attachProblem` inside the lock, because the ceiling, the depth or
+ * the parentage can all have moved since the proposal was written, and this
+ * second run is the one that actually decides. `customRoleBlockers` runs
+ * against the ancestry the attach would create, which only exists once the
+ * parent link is written, so that write happens here (not through
+ * `attachInTx`, which would also recompute in the same step) and is undone by
+ * throwing out of the transaction if a blocker turns up, rather than by
+ * `recomputeDerived` itself refusing partway through the subtree (D19: no
+ * partial propagation).
+ */
+export declare function acceptAttach(access: Access, db: DbOrTx, scopeColumn: Scope['column'], policy: Pick<StorePolicy, 'maxDepth' | 'offered'>, proposalId: string): Promise<Result<void>>;
+/** Declines a pending proposal. Same authority as `acceptAttach`; nothing is written to either tenant. */
+export declare function declineAttach(access: Access, db: DbOrTx, scopeColumn: Scope['column'], proposalId: string): Promise<Result<void>>;
+export interface DetachOptions {
+    readonly childId: string;
+}
+export interface DetachResult {
+    readonly grantedByDerivedHolders: readonly DetachReportRow[];
+}
+/**
+ * Detaches a child from its parent. Allowed to the child's own owner, to the
+ * parent (the child among its own children), or to an operator, all through
+ * `tenants:detach`. The report is read before `detachInTx`, on purpose: it
+ * asks who currently holds a derived row in the child, and detaching is
+ * exactly what takes those rows away, so reading it after would see nothing
+ * left to report.
+ */
+export declare function detach(access: Access, db: DbOrTx, scopeColumn: Scope['column'], options: DetachOptions): Promise<Result<DetachResult>>;
+export interface AttachProposalForChild {
+    readonly id: string;
+    readonly parentId: string;
+    readonly parentName: string;
+    readonly reason: AttachReason;
+    readonly reference: string;
+    readonly proposedBy: string;
+    readonly createdAt: Date;
+}
+/** `tenants:attach` or `members:read`; every pending proposal to hold this organisation, for the page beside pending invitations. */
+export declare function pendingProposalsForChild(access: Access, db: DbOrTx): Promise<readonly AttachProposalForChild[]>;
+export interface AttachProposalFromParent {
+    readonly id: string;
+    readonly childId: string;
+    readonly childName: string;
+    readonly status: 'pending_parent' | 'pending' | 'accepted' | 'declined';
+    readonly reason: AttachReason;
+    readonly reference: string;
+    readonly createdAt: Date;
+    readonly decidedAt: Date | null;
+}
+/** `tenants:attach` or `members:read`; every proposal this organisation has sent as a parent, pending or decided, for its own console. */
+/** An operator's draft waiting on this organisation to agree to hold another one. */
+export interface AttachProposalForParent {
+    readonly id: string;
+    readonly childId: string;
+    readonly childName: string;
+    readonly reason: AttachReason;
+    readonly reference: string;
+    readonly proposedBy: string;
+    readonly createdAt: Date;
+}
+/**
+ * What an operator has proposed that this organisation hold, and nobody has
+ * agreed to yet. The parent answers these before the child ever sees them
+ * (M5): accepting hands this organisation's own members authority inside
+ * another one, which the console does not get to decide on its behalf.
+ */
+export declare function pendingProposalsForParent(access: Access, db: DbOrTx): Promise<readonly AttachProposalForParent[]>;
+export declare function proposalsFromParent(access: Access, db: DbOrTx): Promise<readonly AttachProposalFromParent[]>;