@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/install-owner.d.ts

@@ -0,0 +1,25 @@
+import type { DbOrTx, Scope } from './scoped.js';
+import type { Access, Result } from './types.js';
+export interface InstallOwnerOptions {
+    readonly tenantId: string;
+    readonly principalId: string;
+    /** A verified reference (the tenant's billing contact confirming by mail) that bypasses the freshness check. */
+    readonly reference?: string;
+    /** Days without any owner sign-in before the seat counts as inactive. */
+    readonly periodDays?: number;
+}
+/**
+ * What a host must supply about a person's own sign-in history. That table
+ * (`profiles`) is the host's, not the store's, so the two reads Boule made
+ * directly against it become this lookup instead: `personKnown` answers "has
+ * this id ever signed in here" for the person being installed, and
+ * `lastSeenAt` answers it for a batch of a tenant's current direct owners at
+ * once, so `installOwner` can compare every owner's activity against
+ * `periodDays` in one pass. A person missing from the returned map, or
+ * mapped to `null`, counts as never signed in.
+ */
+export interface OwnerActivityLookup {
+    personKnown(principalId: string): Promise<boolean>;
+    lastSeenAt(principalIds: readonly string[]): Promise<ReadonlyMap<string, Date | null>>;
+}
+export declare function installOwner(operatorAccess: Access, db: DbOrTx, scopeColumn: Scope['column'], activity: OwnerActivityLookup, options: InstallOwnerOptions): Promise<Result<void>>;

package/dist/install-owner.js

@@ -0,0 +1,159 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { writeParticipationPolicy, writePrimaryAssignment } from './assignments.js';
+import { record } from './audit.js';
+import { permitsPlatform, refreshAccess } from './policy-access.js';
+import { roleDef } from './roles.js';
+import { memberships, tenants } from './schema.js';
+import { recomputeDerived } from './tree-writes.js';
+import { derivedEventAction, descendantsOf } from './tree.js';
+import { done, isUuid, refused, tenantTag } from './types.js';
+/**
+ * The one exception to D8's rule that no session, and no standing operator
+ * reach, ever changes who belongs to a tenant. A tenant whose owner seat is
+ * gone or compromised has nobody left inside it who could appoint a
+ * replacement, which is exactly what the last-owner guard elsewhere is
+ * designed to prevent working around, so this is an ordinary operator
+ * action, gated by its own permission, never a break-glass session (M1).
+ */
+const DEFAULT_PERIOD_DAYS = 30;
+export async function installOwner(operatorAccess, db, scopeColumn, activity, options) {
+    if (operatorAccess.context === 'break_glass') {
+        return refused('break_glass', 'A support session never installs an owner.');
+    }
+    if (operatorAccess.tenant.kind !== 'operator' ||
+        !permitsPlatform(operatorAccess, 'owners:install')) {
+        return refused('no_permission', 'You do not have permission to install an owner.');
+    }
+    if (!isUuid(options.tenantId)) {
+        return refused('tenant_not_found', 'This organisation no longer exists.');
+    }
+    if (options.tenantId === operatorAccess.tenant.id) {
+        return refused('operator_tenant', 'The operator organisation is not what this action is for.');
+    }
+    if (!(await activity.personKnown(options.principalId)))
+        return refused('unknown_person', 'This person has never signed in here.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, operatorAccess);
+        if (!fresh || fresh.context !== 'operator' || !permitsPlatform(fresh, 'owners:install'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        const [tenantRow] = await tx
+            .select({ id: tenants.id, name: tenants.name })
+            .from(tenants)
+            .where(eq(tenants.id, options.tenantId))
+            .for('update');
+        if (!tenantRow)
+            return refused('tenant_not_found', 'This organisation no longer exists.');
+        const owners = await tx
+            .select({ principalId: memberships.principalId })
+            .from(memberships)
+            .where(and(eq(memberships.tenantId, tenantRow.id), eq(memberships.principalClass, 'human'), 
+        // Not `and r.built_in`: a starter owner role (ADR 0016) is
+        // `built_in: false` for a tenant created after that change, but
+        // only the app's own owner role can ever hold the literal key
+        // `owner` (custom role keys always start with `c_`).
+        sql `exists(select 1 from authz_assignments a join authz_roles r on r.id=a.role_id where a.tenant_id=${memberships.tenantId} and a.principal_id=${memberships.principalId} and a.principal_class='human' and a.source='direct' and a.expires_at is null and r.key='owner')`, eq(memberships.source, 'direct')));
+        const lastSeen = await activity.lastSeenAt(owners.map((owner) => owner.principalId));
+        const periodMs = (options.periodDays ?? DEFAULT_PERIOD_DAYS) * 24 * 60 * 60 * 1000;
+        const cutoff = Date.now() - periodMs;
+        // Null (or missing from the map) counts as never signed in: this asks
+        // whether SOME owner is still within the period, not whether every
+        // owner has a timestamp at all.
+        const anOwnerIsActive = owners.some((owner) => {
+            const seenAt = lastSeen.get(owner.principalId) ?? null;
+            return seenAt !== null && seenAt.getTime() >= cutoff;
+        });
+        let reason;
+        if (owners.length === 0) {
+            reason = 'no_owner';
+        }
+        else if (!anOwnerIsActive) {
+            reason = 'owners_inactive';
+        }
+        else if (options.reference) {
+            // An owner is still within the period; only a verified reference
+            // overrides that, which is why this is checked last rather than first.
+            reason = 'reference';
+        }
+        else {
+            return refused('owners_active', 'An owner has signed in recently. A verified reference is needed to install another.');
+        }
+        const [existing] = await tx
+            .select({ principalId: memberships.principalId, source: memberships.source })
+            .from(memberships)
+            .where(and(eq(memberships.tenantId, tenantRow.id), eq(memberships.principalId, options.principalId), eq(memberships.principalClass, 'human')))
+            .limit(1);
+        if (existing) {
+            // grantedBy moves to the operator too: this is the operator's own act
+            // right now, not a continuation of whoever originally added the row.
+            //
+            // `source` moves to direct as well, and `via_tenant_id` goes with it.
+            // The point of this function is that the tenant gains an owner seat of
+            // its own, and `ownerCoverage` counts direct rows only (D19), so
+            // promoting a row that arrived from a parent and leaving it derived
+            // would satisfy nothing: the tenant would still read as ownerless, and
+            // the next propagation would recompute the role straight back off it.
+            await tx
+                .update(memberships)
+                .set({
+                source: 'direct',
+                viaTenantId: null,
+                grantedBy: currentAccess.actor.id,
+                updatedAt: new Date(),
+            })
+                .where(and(eq(memberships.tenantId, tenantRow.id), eq(memberships.principalId, options.principalId), eq(memberships.principalClass, 'human')));
+        }
+        else {
+            await tx.insert(memberships).values({
+                tenantId: tenantRow.id,
+                principalId: options.principalId,
+                principalClass: 'human',
+                source: 'direct',
+                tenantName: tenantRow.name,
+                grantedBy: currentAccess.actor.id,
+            });
+            await writeParticipationPolicy(tx, currentAccess.binding, tenantRow.id, {
+                id: options.principalId,
+                class: 'human',
+            });
+        }
+        const owner = await roleDef(tx, currentAccess.binding, tenantRow, 'owner');
+        if (!owner)
+            throw new Error('Missing owner role');
+        await writePrimaryAssignment(tx, currentAccess.binding, owner, { id: options.principalId, class: 'human' }, { createdBy: currentAccess.actor.id });
+        await record(tx, currentAccess, {
+            action: 'owner.installed',
+            tenantId: tenantRow.id,
+            targetType: 'membership',
+            targetId: options.principalId,
+            after: { role: 'owner' },
+            reason,
+            reference: options.reference,
+        });
+        // D19: the row just written is a direct membership, so a tenant holding
+        // children owes them the derived rows it implies, the same as every
+        // other direct write. An installed owner who did not reach the children
+        // would be an owner of a parent with no authority below it.
+        const descendants = await descendantsOf(tx, tenantRow.id);
+        const tags = [tenantTag(tenantRow.id)];
+        if (descendants.length > 0) {
+            const changes = await recomputeDerived(tx, currentAccess.binding, descendants.map((node) => node.id), [options.principalId]);
+            for (const change of changes) {
+                tags.push(tenantTag(change.tenantId));
+                await record(tx, currentAccess, {
+                    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,
+                });
+            }
+        }
+        return done(undefined, tags);
+    });
+}

package/dist/invitations.d.ts

@@ -0,0 +1,160 @@
+import type { StoreBinding } from './binding.js';
+import type { OwnerActivityLookup } from './install-owner.js';
+import type { StorePolicy } from './policy.js';
+import type { DbOrTx, Scope } from './scoped.js';
+import { type Access, type Principal, type Result } from './types.js';
+/**
+ * Invitations (D10): a pending offer of membership, its own row rather than
+ * a pending membership, so it can expire, be revoked, or sit visibly as
+ * "mail failed" until someone retries. Every write here locks the tenant row
+ * first, refuses under a break-glass context (D8: no session ever changes
+ * who belongs), and records exactly one audit row through the `Access` or
+ * `Principal` it was handed.
+ *
+ * Wave 8a (authz#83) is the sending and management half:
+ * `generateInvitationToken`, `invite`, `markInvitationMail`,
+ * `resendInvitation`, `revokeInvitation`, `pendingInvitations`,
+ * `invitationPreview` and `invitationTenantId`. Wave 8b adds
+ * `acceptInvitation` and the born-attach savepoint it runs.
+ *
+ * `acceptInvitationForUser` does not move: it is the one caller of Boule's
+ * own `requireUser`, `ensureProfile` and `principalFromUser` from
+ * `access.ts`, none of which this package can reach, and stays in Boule as
+ * a non-goal (issue #98 decision 1).
+ */
+export interface InviteOptions {
+    readonly email: string;
+    readonly role: string;
+    /** The host's own per-hour send limit (authz#83 wave 8 decision 2: no longer a package constant). */
+    readonly capPerHour: number;
+    /** The host's own acceptance route (decision 3): the store never hard-codes one. */
+    readonly link: (token: string) => string;
+}
+/**
+ * What a successful send hands back. The token is returned here once and
+ * never stored or logged in clear. `email` is the row's own, normalised
+ * address -- on `resendInvitation` this is the only place a caller who
+ * supplied nothing but an id can read it back, so the mail it sends targets
+ * the invitation's real address rather than whatever a form happened to
+ * carry.
+ */
+export interface InvitationHandle {
+    readonly id: string;
+    readonly token: string;
+    readonly link: string;
+    readonly email: string;
+}
+export interface GeneratedInvitationToken {
+    readonly token: string;
+    readonly tokenHash: string;
+    readonly expiresAt: Date;
+}
+/**
+ * The token every invitation row uses: 32 random bytes (the package's own
+ * `core.invitation.tokenBytes`), hex-encoded for the link the mail carries,
+ * with its sha256 hex stored on the row. Exported so a host's own
+ * `createTenantAsOperator` builds its own pending invitation with exactly
+ * the same rule, rather than a second copy of it.
+ */
+export declare function generateInvitationToken(): GeneratedInvitationToken;
+/**
+ * Sends an invitation, or re-sends one: a pending row already sitting on
+ * `(tenant, email)` has its token and expiry rotated in place rather than a
+ * second row being created, which is also what the unique index on that
+ * pair enforces. The role on a rotated row is replaced by whatever this call
+ * asked for, since that is the role the grant check below just verified;
+ * leaving the old role in place would store something nobody re-checked.
+ *
+ * There is no check here for "this email already belongs to a member":
+ * a membership carries a principal id and a class, never an email (the
+ * import rule scans for exactly that), so there is no predicate to write.
+ * An address that already has an account simply accepts and finds it is
+ * already a member (see `acceptInvitation`, wave 8b).
+ */
+export declare function invite(access: Access, db: DbOrTx, scopeColumn: Scope['column'], options: InviteOptions): Promise<Result<InvitationHandle>>;
+/** `members:grant`; sets whether the mail for one invitation went out. Never audited: this is delivery bookkeeping, not an authorisation event. */
+export declare function markInvitationMail(access: Access, db: DbOrTx, invitationId: string, state: 'sent' | 'failed'): Promise<Result<void>>;
+/**
+ * A re-invite: reads the row's current email and role and sends through the
+ * same path `invite` uses, which is what rotates its token and expiry.
+ * Gated on `members:grant` before the row is even read, the same as
+ * `markInvitationMail`: without that, a member who cannot see invitations at
+ * all could still learn that a given invitation id exists here, and whether
+ * it is still pending, just from which refusal comes back.
+ */
+export declare function resendInvitation(access: Access, db: DbOrTx, scopeColumn: Scope['column'], invitationId: string, options: Pick<InviteOptions, 'capPerHour' | 'link'>): Promise<Result<InvitationHandle>>;
+/**
+ * Withdraws a pending invitation. Guarded the same way removing a member is:
+ * `members:revoke` and the guard-permission test on the role being taken
+ * away, and, for an owner invitation specifically, the same coverage rule
+ * a host's own membership removal enforces for a membership row: revoking it
+ * must not leave the tenant with no owner and no other pending owner
+ * invitation.
+ */
+export declare function revokeInvitation(access: Access, db: DbOrTx, scopeColumn: Scope['column'], invitationId: string): Promise<Result<void>>;
+/** What a born-attached invitation reports when the attachment itself could not be completed. The new owner stands either way; see `attemptBornAttach`. */
+export interface AttachRefusal {
+    readonly reason: string;
+    readonly message: string;
+}
+export interface AcceptInvitationResult {
+    readonly tenantId: string;
+    /** Set only on a born-attached invitation: whether `attemptBornAttach` actually completed the attachment. */
+    readonly attached?: boolean;
+    /** Set only when a born-attached invitation's attachment was refused. The membership this function just wrote stands regardless. */
+    readonly attachRefusal?: AttachRefusal;
+}
+/**
+ * Accepts an invitation. There is no `Access` yet: the person is not a
+ * member until this function decides they may become one, so every check
+ * here reads rows directly rather than resolving one. Order follows D10 and
+ * D3 exactly: not pending, expired, unverified email, mismatched email,
+ * tenant state, then the inviter's authority re-checked as it stands now
+ * (not as it stood when they sent the invitation), then the profile, then
+ * the membership itself.
+ *
+ * `binding` and `policy` are threaded through to `roleForInvitation`,
+ * `loadAccess`/`operatorMayStillOnboard` and `attemptBornAttach`, the same
+ * as every other write this campaign has moved. `profiles` is the host's own
+ * port over its `profiles` table's one question this function asks --
+ * reusing `Pick<OwnerActivityLookup, 'personKnown'>` from install-owner.ts
+ * rather than declaring a second port for the same "has this id ever signed
+ * in" question.
+ */
+export declare function acceptInvitation(principal: Principal, db: DbOrTx, scopeColumn: Scope['column'], binding: StoreBinding, policy: Pick<StorePolicy, 'maxDepth' | 'offered'>, profiles: Pick<OwnerActivityLookup, 'personKnown'>, token: string): Promise<Result<AcceptInvitationResult>>;
+export interface PendingInvitationSummary {
+    readonly id: string;
+    readonly email: string;
+    readonly role: string;
+    readonly status: string;
+    readonly mailState: string;
+    readonly invitedBy: string | null;
+    readonly expiresAt: Date;
+    readonly createdAt: Date;
+    /** The organisation this invitation would attach to on acceptance, born-attached only (D19). */
+    readonly parentName: string | null;
+}
+/** `members:read`; every pending invitation for the members page, with `token_hash` never among the selected columns. */
+export declare function pendingInvitations(access: Access, db: DbOrTx): Promise<readonly PendingInvitationSummary[]>;
+export interface InvitationPreview {
+    readonly tenantName: string;
+    readonly role: string;
+    readonly status: string;
+    readonly expiresAt: Date;
+    /** The organisation this invitation would attach to on acceptance, born-attached only (D19). Never the parent's id: this page is reachable before anyone is signed in. */
+    readonly parentName: string | null;
+}
+/** For the acceptance page, reachable before anyone is signed in: what the invitation offers, never the hash, the inviter's address, or the parent's id. */
+export declare function invitationPreview(token: string, db: DbOrTx): Promise<InvitationPreview | null>;
+/**
+ * The tenant a token's invitation belongs to, regardless of its status --
+ * pending, accepted, revoked or expired. Exists for one caller only: the
+ * accept page, so that a `not_pending` refusal (the row has already been
+ * used) can be told apart from every other refusal by asking a second
+ * question -- is this signed-in person already a member there -- without
+ * touching `acceptInvitation` itself. Unlike `invitationPreview`, this may
+ * only be called once a principal is established: it hands back the raw
+ * tenant id, which `invitationPreview`'s own docblock deliberately never
+ * does for a visitor who has not signed in yet.
+ */
+export declare function invitationTenantId(token: string, db: DbOrTx): Promise<string | null>;