@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/membership-rows.d.ts

@@ -0,0 +1,206 @@
+import type { ResourcePrincipal } from '@wtfalch/authz';
+import { type PolicyBinding } from './owners.js';
+import type { PeopleDirectory } from './person-records.js';
+import type { DbOrTx } from './scoped.js';
+/**
+ * Row-level helpers, ported (authz#83 wave 10b) from `@wtfalch/people` 0.2.3's
+ * `membership.js` (`grantMembership`, `removeMembership`, `changeRole`,
+ * `guardStaysHeld`) and `roster.js` (`membersOf`), typed TypeScript with
+ * people's own comments kept. `@wtfalch/people` depends on this package, so
+ * this package cannot import it back without a cycle (decision, William
+ * 2026-09-29); a later issue in the people repo makes it reuse this copy
+ * instead of carrying its own. Every name here is exported under one distinct
+ * from the policy layer's (`src/memberships.ts`, which keeps Boule's own
+ * names for the same five operations) because this file's names would
+ * otherwise collide with those on the same package surface.
+ *
+ * `identityWhere` is not re-declared here: people's own copy
+ * (`and(eq(tenantId), eq(principalClass), eq(principalId))`) tests the exact
+ * same three columns as `./assignments.js`'s (`and(eq(tenantId),
+ * eq(principalId), eq(principalClass))`), just written in a different
+ * argument order that `and()` does not care about — so this file imports
+ * that one rather than keeping a second copy.
+ */
+/** The host's already-bound audit writer, plus who to credit the change to. Optional: a caller with no audit trail wired up yet still gets a working membership change. Mirrors `@wtfalch/people`'s `AuditOptions`, without that package's `@wtfalch/audit` dependency — this store has none. */
+export interface MembershipRowAuditActor {
+    readonly class: string;
+    readonly id: string;
+    readonly display: string;
+}
+export interface MembershipRowAuditEvent {
+    readonly action: string;
+    readonly actor: MembershipRowAuditActor;
+    readonly target: {
+        readonly type: string;
+        readonly id: string;
+    };
+    readonly tenantId: string;
+    readonly after?: unknown;
+}
+export interface MembershipRowAuditOptions {
+    readonly writer: (event: MembershipRowAuditEvent, db: DbOrTx) => Promise<void>;
+    readonly actor: MembershipRowAuditActor;
+}
+export interface InsertMembershipRowInput {
+    readonly tenantId: string;
+    /** Denormalised onto the row, same as the three hosts do (D5: the switcher reads one index range). */
+    readonly tenantName: string;
+    readonly principal: ResourcePrincipal;
+    /** Defaults to `'direct'`. `'inherited'` is the tenant tree giving it — a host writes that itself, this package does not compute a tree. */
+    readonly source?: string;
+    readonly viaTenantId?: string | null;
+    readonly grantedBy?: string | null;
+    /**
+     * Runs once the `memberships` row insert succeeds, before the audit
+     * write, on the same `db` this call received — pass a transaction to
+     * `insertMembershipRow` and close over it here for this to be atomic with
+     * the row insert. Lets a host attach the role assignment, tenant-tree
+     * propagation and participation-policy write it does today (`src/memberships.ts`'s
+     * policy layer) to this grant without this file importing any of it. Not
+     * called when the row already existed. A throw here propagates, so a
+     * caller inside its own transaction rolls back the row insert too.
+     */
+    readonly onGranted?: () => Promise<void>;
+}
+export type InsertMembershipRowResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'already_member';
+};
+/**
+ * Adds one membership row. This is deliberately narrower than a host's own
+ * `grantMembership`: role assignment (`writePrimaryAssignment`), the
+ * role-boundary refusal checks (`roleAssignmentRefusal`), tenant-tree
+ * propagation and participation-policy writes are `src/memberships.ts`'s
+ * policy layer, not `memberships` table rows, and out of this row helper's
+ * scope (people's own README: "Out of scope: ... permission checks"). The
+ * caller checks whether the acting principal may grant this membership
+ * before calling this, and attaches that policy work via `input.onGranted`
+ * rather than this file reimplementing it.
+ */
+export declare function insertMembershipRow(db: DbOrTx, input: InsertMembershipRowInput, audit?: MembershipRowAuditOptions): Promise<InsertMembershipRowResult>;
+export interface DeleteMembershipRowInput {
+    readonly tenantId: string;
+    readonly principal: ResourcePrincipal;
+    /**
+     * Runs once the `memberships` row delete succeeds, before the audit
+     * write, on the same `db` this call received. Symmetric with
+     * `InsertMembershipRowInput.onGranted` — lets a host end break-glass
+     * sessions, propagate the removal across a tenant tree, or clean up its
+     * own `authz_assignments` rows without this file importing any of that.
+     * Not called when there was no row to remove. A throw here propagates.
+     */
+    readonly onRemoved?: () => Promise<void>;
+}
+export type DeleteMembershipRowResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'not_found';
+};
+/** Removes one membership row. Call `guardStaysHeldRow` first when the removed principal might hold a guarded role — this function does not know what roles a principal holds. */
+export declare function deleteMembershipRow(db: DbOrTx, input: DeleteMembershipRowInput, audit?: MembershipRowAuditOptions): Promise<DeleteMembershipRowResult>;
+export interface ChangeRoleRowInput {
+    readonly tenantId: string;
+    readonly principal: ResourcePrincipal;
+    readonly binding: PolicyBinding;
+    /**
+     * The `authz_roles.id` to make `principal`'s new primary assignment for
+     * `binding`. Resolved from a role key, compiled and refusal-checked by
+     * the caller's own policy layer before calling this — this file does not
+     * evaluate a role definition, the same separation `insertMembershipRow`
+     * keeps.
+     */
+    readonly roleId: string;
+    readonly expiresAt?: Date | null;
+    readonly createdBy?: string | null;
+}
+export type ChangeRoleRowResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'not_member';
+};
+/**
+ * Replaces whatever primary assignment `principal` holds for `binding`'s
+ * `applicationId` with one pointing at `roleId`: the row-level half of a
+ * host's own `changeRole`. Resolving `roleId`, the refusal checks (guard
+ * coverage, self-promotion, custom-role tenant boundary, break-glass),
+ * ending sessions a role change should end, and tenant-tree propagation all
+ * stay the caller's — the same policy-layer line `insertMembershipRow`/
+ * `deleteMembershipRow` already draw. Call `guardStaysHeldRow` first when
+ * replacing a role that might be the last independent owner.
+ *
+ * A single `INSERT ... ON CONFLICT DO UPDATE`, not a delete then an insert:
+ * `authz_assignments`' own `authz_assignments_primary_idx` is a partial
+ * unique index on `(tenant_id, application_id, principal_class,
+ * principal_id) WHERE primary_assignment` — **not** scoped by
+ * `platform_id`, so a principal has at most one primary assignment per
+ * `(tenantId, applicationId)`, no matter which `platformId` it carries.
+ * Conflicting on those exact columns keeps this atomic (one statement, no
+ * transaction required for correctness) and matches that invariant exactly
+ * — a `platformId`-scoped delete would miss an existing row written for a
+ * different `platformId` of the same `applicationId` and then fail the
+ * insert with an unhandled `unique_violation`.
+ *
+ * `boundary`/`scope` are hard-coded to `{ kind: 'platform' }`/
+ * `{ kind: 'organisation' }` — the whole-platform, whole-organisation shape
+ * a host's own `primaryAssignment()` helper writes for a primary
+ * assignment; a scoped or boundary-limited assignment is not a "primary
+ * assignment" in that same sense, and stays the host's own `authz_assignments`
+ * write.
+ */
+export declare function changeRoleRow(db: DbOrTx, input: ChangeRoleRowInput, audit?: MembershipRowAuditOptions): Promise<ChangeRoleRowResult>;
+/**
+ * Whether removing `principal`'s membership (or changing it away from a
+ * guarded role) would leave a protected role with no independent recovery
+ * owner. Ported from manage's `guardStaysHeld`, with one change: it takes
+ * `guards` — the union of `role.guards` across whatever roles are being
+ * revoked — instead of a list of role definitions, because role definitions
+ * are the policy layer's, not this row-level file's. The caller (which
+ * already resolved the roles to compute a refusal reason) reduces them to
+ * this set the same way the original did: `new Set(roles.flatMap((r) =>
+ * r.guards))`.
+ */
+export declare function guardStaysHeldRow(db: DbOrTx, binding: PolicyBinding, tenantId: string, principal: ResourcePrincipal, guards: ReadonlySet<string>): Promise<boolean>;
+export interface MembershipRosterRow {
+    readonly principalId: string;
+    readonly principalClass: string;
+    readonly source: string;
+    readonly display: string;
+    readonly email: string | null;
+    readonly viaTenantName: string | null;
+    readonly joinedAt: Date;
+    readonly lastSeenAt: Date | null;
+    readonly role: string | null;
+    readonly roleLabel: string | null;
+}
+/**
+ * Every member of one tenant, newest membership first is not assumed here —
+ * callers that want an order sort by `joinedAt` themselves; this returns in
+ * principal order, which is what makes the query itself stable to test
+ * against.
+ *
+ * The caller checks `members:read` before calling this — see
+ * `src/memberships.ts`'s `membersOf` — this function does not check it
+ * itself, the same separation people's own store kept from its
+ * `authorization.ts`.
+ *
+ * Pass `roles` (the same `PolicyBinding` `guardStaysHeldRow` takes) to
+ * resolve `role`/`roleLabel` from each member's primary assignment for that
+ * application/platform. Omit it and every row's `role`/`roleLabel` is
+ * `null` — today's v1 shape, unchanged.
+ *
+ * People's `roster.js` joined its own `profiles` table (a `left join`: a
+ * member with no profile row is kept, with null display fields) to resolve
+ * `displayName`/`email`/`lastSeenAt`. This store has no `profiles` table of
+ * its own, so that join becomes a `PeopleDirectory` lookup afterwards —
+ * `person-records.ts`'s wave 10a port — over every human principal id this
+ * query found; a human with no directory entry keeps the same left-join
+ * shape people's SQL gave it: the row stays, `displayName`/`email`/
+ * `lastSeenAt` come back `null`. Non-human members never reach the
+ * directory at all, the same as people's join, which only ever matched
+ * `profiles` for `principalClass = 'human'`.
+ */
+export declare function membersOfRow(db: DbOrTx, tenantId: string, directory: PeopleDirectory, roles?: PolicyBinding): Promise<readonly MembershipRosterRow[]>;

package/dist/membership-rows.js

@@ -0,0 +1,271 @@
+import { and, asc, eq, inArray, isNull, or, sql } from 'drizzle-orm';
+import { identityWhere } from './assignments.js';
+import { ownerCoverage, ownerSeatCovered, } from './owners.js';
+import { policyAssignments, policyRoles } from './policy-schema.js';
+import { credentials, memberships, tenants } from './schema.js';
+/**
+ * Adds one membership row. This is deliberately narrower than a host's own
+ * `grantMembership`: role assignment (`writePrimaryAssignment`), the
+ * role-boundary refusal checks (`roleAssignmentRefusal`), tenant-tree
+ * propagation and participation-policy writes are `src/memberships.ts`'s
+ * policy layer, not `memberships` table rows, and out of this row helper's
+ * scope (people's own README: "Out of scope: ... permission checks"). The
+ * caller checks whether the acting principal may grant this membership
+ * before calling this, and attaches that policy work via `input.onGranted`
+ * rather than this file reimplementing it.
+ */
+export async function insertMembershipRow(db, input, audit) {
+    const [existing] = await db
+        .select({ principalId: memberships.principalId })
+        .from(memberships)
+        .where(identityWhere(input.tenantId, input.principal))
+        .limit(1);
+    if (existing)
+        return { ok: false, reason: 'already_member' };
+    const source = input.source ?? 'direct';
+    await db.insert(memberships).values({
+        tenantId: input.tenantId,
+        principalId: input.principal.id,
+        principalClass: input.principal.class,
+        source,
+        viaTenantId: input.viaTenantId ?? null,
+        tenantName: input.tenantName,
+        grantedBy: input.grantedBy ?? null,
+    });
+    if (input.onGranted)
+        await input.onGranted();
+    if (audit) {
+        await audit.writer({
+            action: 'membership.created',
+            actor: audit.actor,
+            target: { type: 'membership', id: input.principal.id },
+            tenantId: input.tenantId,
+            after: { principalClass: input.principal.class, source },
+        }, db);
+    }
+    return { ok: true };
+}
+/** Removes one membership row. Call `guardStaysHeldRow` first when the removed principal might hold a guarded role — this function does not know what roles a principal holds. */
+export async function deleteMembershipRow(db, input, audit) {
+    const [existing] = await db
+        .select({ principalId: memberships.principalId })
+        .from(memberships)
+        .where(identityWhere(input.tenantId, input.principal))
+        .limit(1);
+    if (!existing)
+        return { ok: false, reason: 'not_found' };
+    await db.delete(memberships).where(identityWhere(input.tenantId, input.principal));
+    if (input.onRemoved)
+        await input.onRemoved();
+    if (audit) {
+        await audit.writer({
+            action: 'membership.ended',
+            actor: audit.actor,
+            target: { type: 'membership', id: input.principal.id },
+            tenantId: input.tenantId,
+        }, db);
+    }
+    return { ok: true };
+}
+/**
+ * Replaces whatever primary assignment `principal` holds for `binding`'s
+ * `applicationId` with one pointing at `roleId`: the row-level half of a
+ * host's own `changeRole`. Resolving `roleId`, the refusal checks (guard
+ * coverage, self-promotion, custom-role tenant boundary, break-glass),
+ * ending sessions a role change should end, and tenant-tree propagation all
+ * stay the caller's — the same policy-layer line `insertMembershipRow`/
+ * `deleteMembershipRow` already draw. Call `guardStaysHeldRow` first when
+ * replacing a role that might be the last independent owner.
+ *
+ * A single `INSERT ... ON CONFLICT DO UPDATE`, not a delete then an insert:
+ * `authz_assignments`' own `authz_assignments_primary_idx` is a partial
+ * unique index on `(tenant_id, application_id, principal_class,
+ * principal_id) WHERE primary_assignment` — **not** scoped by
+ * `platform_id`, so a principal has at most one primary assignment per
+ * `(tenantId, applicationId)`, no matter which `platformId` it carries.
+ * Conflicting on those exact columns keeps this atomic (one statement, no
+ * transaction required for correctness) and matches that invariant exactly
+ * — a `platformId`-scoped delete would miss an existing row written for a
+ * different `platformId` of the same `applicationId` and then fail the
+ * insert with an unhandled `unique_violation`.
+ *
+ * `boundary`/`scope` are hard-coded to `{ kind: 'platform' }`/
+ * `{ kind: 'organisation' }` — the whole-platform, whole-organisation shape
+ * a host's own `primaryAssignment()` helper writes for a primary
+ * assignment; a scoped or boundary-limited assignment is not a "primary
+ * assignment" in that same sense, and stays the host's own `authz_assignments`
+ * write.
+ */
+export async function changeRoleRow(db, input, audit) {
+    const [existing] = await db
+        .select({ principalId: memberships.principalId })
+        .from(memberships)
+        .where(identityWhere(input.tenantId, input.principal))
+        .limit(1);
+    if (!existing)
+        return { ok: false, reason: 'not_member' };
+    await db
+        .insert(policyAssignments)
+        .values({
+        tenantId: input.tenantId,
+        applicationId: input.binding.applicationId,
+        platformId: input.binding.platformId,
+        roleId: input.roleId,
+        principalId: input.principal.id,
+        principalClass: input.principal.class,
+        boundary: { kind: 'platform' },
+        scope: { kind: 'organisation' },
+        primary: true,
+        expiresAt: input.expiresAt ?? null,
+        createdBy: input.createdBy ?? null,
+    })
+        .onConflictDoUpdate({
+        target: [
+            policyAssignments.tenantId,
+            policyAssignments.applicationId,
+            policyAssignments.principalClass,
+            policyAssignments.principalId,
+        ],
+        targetWhere: eq(policyAssignments.primary, true),
+        set: {
+            platformId: input.binding.platformId,
+            roleId: input.roleId,
+            boundary: { kind: 'platform' },
+            scope: { kind: 'organisation' },
+            expiresAt: input.expiresAt ?? null,
+            createdBy: input.createdBy ?? null,
+        },
+    });
+    if (audit) {
+        await audit.writer({
+            action: 'membership.role_changed',
+            actor: audit.actor,
+            target: { type: 'membership', id: input.principal.id },
+            tenantId: input.tenantId,
+            after: { roleId: input.roleId },
+        }, db);
+    }
+    return { ok: true };
+}
+/**
+ * Whether removing `principal`'s membership (or changing it away from a
+ * guarded role) would leave a protected role with no independent recovery
+ * owner. Ported from manage's `guardStaysHeld`, with one change: it takes
+ * `guards` — the union of `role.guards` across whatever roles are being
+ * revoked — instead of a list of role definitions, because role definitions
+ * are the policy layer's, not this row-level file's. The caller (which
+ * already resolved the roles to compute a refusal reason) reduces them to
+ * this set the same way the original did: `new Set(roles.flatMap((r) =>
+ * r.guards))`.
+ */
+export async function guardStaysHeldRow(db, binding, tenantId, principal, guards) {
+    if (guards.size === 0)
+        return true;
+    const options = {
+        excludePrincipalId: principal.id,
+        excludePrincipalClass: principal.class,
+    };
+    const coverage = await ownerCoverage(db, binding, tenantId, options);
+    return guards.has('members:grant-owner') ? ownerSeatCovered(coverage) : coverage.directOwners > 0;
+}
+/**
+ * A name for a non-human member once no credential row explains it either —
+ * a dangling reference, not the normal case, since every credential is
+ * minted with a `name`. Still never a raw principal id: a UUID says nothing
+ * a person can act on. Ported from manage's `memberships.ts`.
+ */
+function fallbackCredentialLabel(principalClass) {
+    switch (principalClass) {
+        case 'api_key':
+            return 'An API key no longer on record';
+        case 'agent':
+            return 'An agent no longer on record';
+        case 'service':
+            return 'A service no longer on record';
+        default:
+            return 'A credential no longer on record';
+    }
+}
+/**
+ * Every member of one tenant, newest membership first is not assumed here —
+ * callers that want an order sort by `joinedAt` themselves; this returns in
+ * principal order, which is what makes the query itself stable to test
+ * against.
+ *
+ * The caller checks `members:read` before calling this — see
+ * `src/memberships.ts`'s `membersOf` — this function does not check it
+ * itself, the same separation people's own store kept from its
+ * `authorization.ts`.
+ *
+ * Pass `roles` (the same `PolicyBinding` `guardStaysHeldRow` takes) to
+ * resolve `role`/`roleLabel` from each member's primary assignment for that
+ * application/platform. Omit it and every row's `role`/`roleLabel` is
+ * `null` — today's v1 shape, unchanged.
+ *
+ * People's `roster.js` joined its own `profiles` table (a `left join`: a
+ * member with no profile row is kept, with null display fields) to resolve
+ * `displayName`/`email`/`lastSeenAt`. This store has no `profiles` table of
+ * its own, so that join becomes a `PeopleDirectory` lookup afterwards —
+ * `person-records.ts`'s wave 10a port — over every human principal id this
+ * query found; a human with no directory entry keeps the same left-join
+ * shape people's SQL gave it: the row stays, `displayName`/`email`/
+ * `lastSeenAt` come back `null`. Non-human members never reach the
+ * directory at all, the same as people's join, which only ever matched
+ * `profiles` for `principalClass = 'human'`.
+ */
+export async function membersOfRow(db, tenantId, directory, roles) {
+    // No `roles` given: force the assignment join to match nothing, so every
+    // row's role/roleLabel comes back `null` without a second query shape to
+    // maintain.
+    const roleMatch = roles
+        ? and(eq(policyAssignments.applicationId, roles.applicationId), eq(policyAssignments.platformId, roles.platformId))
+        : sql `false`;
+    const rows = await db
+        .select({
+        principalId: memberships.principalId,
+        principalClass: memberships.principalClass,
+        source: memberships.source,
+        viaTenantId: memberships.viaTenantId,
+        joinedAt: memberships.createdAt,
+        // A non-human member's name is the name its own credential was minted
+        // with, not the principal id `display` falls back to next — a raw
+        // UUID where a name belongs.
+        credentialName: credentials.name,
+        role: policyRoles.key,
+        roleLabel: policyRoles.name,
+    })
+        .from(memberships)
+        .leftJoin(credentials, and(eq(memberships.principalClass, credentials.kind), sql `${memberships.principalId} = ${credentials.id}::text`))
+        .leftJoin(policyAssignments, and(eq(policyAssignments.tenantId, memberships.tenantId), eq(policyAssignments.principalId, memberships.principalId), eq(policyAssignments.principalClass, memberships.principalClass), eq(policyAssignments.primary, true), or(isNull(policyAssignments.expiresAt), sql `${policyAssignments.expiresAt} > now()`), roleMatch))
+        .leftJoin(policyRoles, eq(policyRoles.id, policyAssignments.roleId))
+        .where(eq(memberships.tenantId, tenantId))
+        .orderBy(asc(memberships.principalId), asc(memberships.principalClass));
+    const humanIds = [
+        ...new Set(rows.filter((r) => r.principalClass === 'human').map((r) => r.principalId)),
+    ];
+    const directoryRows = await directory.people(humanIds);
+    const viaTenantIds = [
+        ...new Set(rows.map((r) => r.viaTenantId).filter((id) => id !== null)),
+    ];
+    const viaTenantNames = viaTenantIds.length
+        ? new Map((await db
+            .select({ id: tenants.id, name: tenants.name })
+            .from(tenants)
+            .where(inArray(tenants.id, viaTenantIds))).map((t) => [t.id, t.name]))
+        : new Map();
+    return rows.map(({ credentialName, viaTenantId, ...r }) => {
+        const profile = r.principalClass === 'human' ? directoryRows.get(r.principalId) : undefined;
+        return {
+            ...r,
+            display: profile?.displayName ??
+                profile?.email ??
+                credentialName ??
+                fallbackCredentialLabel(r.principalClass),
+            email: profile?.email ?? null,
+            lastSeenAt: profile?.lastSeenAt ?? null,
+            viaTenantName: viaTenantId
+                ? (viaTenantNames.get(viaTenantId) ?? 'a parent organisation')
+                : null,
+        };
+    });
+}

package/dist/memberships.d.ts

@@ -0,0 +1,87 @@
+import type { ActorClass, ResourcePrincipal, ResourceRole } from '@wtfalch/authz';
+import type { OwnerActivityLookup } from './install-owner.js';
+import type { PolicyBinding } from './owners.js';
+import type { PeopleDirectory } from './person-records.js';
+import type { DbOrTx, Scope } from './scoped.js';
+import { type Access, type Result } from './types.js';
+/**
+ * The policy layer (authz#83 wave 10b), moved from Boule's own
+ * `src/lib/authz/memberships.ts` (407 lines): `membersOf`, `selfStanding`,
+ * `guardStaysHeld`, `grantMembership`, `changeRole` and `removeMembership`.
+ * The row-level work each of the last four delegates to now lives in
+ * `src/membership-rows.ts`, ported from `@wtfalch/people` 0.2.3 in the same
+ * wave (`insertMembershipRow`, `deleteMembershipRow`, `changeRoleRow`,
+ * `guardStaysHeldRow`, `membersOfRow`) rather than imported from that
+ * package — `@wtfalch/people` depends on this one, so importing it back
+ * would be a cycle. Boule's `PEOPLE_BINDING`, built from its own
+ * `APPLICATION_ID`/`PLATFORM_ID` constants, becomes `access.binding`
+ * everywhere, the same as every other moved module.
+ */
+export interface Member {
+    readonly principalId: string;
+    readonly principalClass: string;
+    readonly role: string;
+    readonly roleLabel: string;
+    readonly source: string;
+    readonly display: string;
+    readonly email: string | null;
+    /** Where this membership came from — `null` for `source === 'direct'`,
+     *  the parent organisation's name otherwise. The register's "From" column
+     *  reads this the same way the person page's front does. */
+    readonly viaTenantName: string | null;
+    readonly joinedAt: Date;
+    readonly lastSeenAt: Date | null;
+}
+/**
+ * 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 declare function membersOf(access: Access, db: DbOrTx, directory: PeopleDirectory): Promise<readonly Member[] | null>;
+export interface SelfStanding {
+    readonly joinedAt: Date;
+    /** `'direct'` for an ordinary membership, otherwise the tenant tree gave it. */
+    readonly source: string;
+    /** `null` for `source === 'direct'`; the parent organisation's name otherwise. */
+    readonly viaTenantName: string | null;
+}
+/**
+ * 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 declare function selfStanding(access: Access, db: DbOrTx): Promise<SelfStanding | null>;
+export interface GrantMembershipOptions {
+    readonly principalId: string;
+    readonly principalClass?: ActorClass;
+    readonly role: string;
+}
+export interface ChangeRoleOptions extends GrantMembershipOptions {
+}
+export interface RemoveMembershipOptions {
+    readonly principalId: string;
+    readonly principalClass?: ActorClass;
+}
+/**
+ * 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 declare function guardStaysHeld(tx: DbOrTx, binding: PolicyBinding, tenantId: string, roles: readonly ResourceRole[], principal: ResourcePrincipal): Promise<boolean>;
+export declare function grantMembership(access: Access, db: DbOrTx, scopeColumn: Scope['column'], profiles: Pick<OwnerActivityLookup, 'personKnown'>, options: GrantMembershipOptions): Promise<Result<void>>;
+export declare function changeRole(access: Access, db: DbOrTx, scopeColumn: Scope['column'], options: ChangeRoleOptions): Promise<Result<void>>;
+export declare function removeMembership(access: Access, db: DbOrTx, scopeColumn: Scope['column'], options: RemoveMembershipOptions): Promise<Result<void>>;