@rovela-ai/sdk 0.2.0 → 0.3.0

package/dist/admin/server/user-management.js

@@ -0,0 +1,846 @@
+/**
+ * @rovela/sdk/admin/server/user-management
+ *
+ * User lifecycle management for store admins — list, deactivate, reactivate,
+ * and hard-delete operations, with all invariants enforced at the service
+ * layer so every future caller inherits them automatically.
+ *
+ * # Invariants (enforced in every mutation)
+ *
+ *   1. Self-protection: actor cannot act on themselves via these helpers.
+ *      Self-service flows (password change, profile update) go through
+ *      dedicated `/api/admin/me/*` endpoints (Phase 4).
+ *
+ *   2. Last-owner protection: there must ALWAYS be at least one admin with
+ *      role='owner' AND status='active'. Deactivating, demoting, or deleting
+ *      the last active owner is rejected. This is enforced via an atomic
+ *      conditional UPDATE (or a pre-check for hard delete), not a
+ *      check-then-act pattern — no TOCTOU race window.
+ *
+ *   3. Lateral-escalation protection: administrators can only touch managers
+ *      and users. They cannot modify owners or other administrators.
+ *      Enforced via `canManageUser(actor, target)` from `permissions.ts`.
+ *
+ *   4. Hard delete requires prior deactivation: you cannot DELETE an admin
+ *      whose status is 'active' or 'invited'. Must call `deactivateAdmin`
+ *      first. This creates a two-step safety rail for irreversible actions.
+ *
+ *   5. Audit trail on deactivate: `deactivated_at` and `deactivated_by` are
+ *      populated from the service layer. Reactivate clears them.
+ *
+ *   6. Reactivate only applies to 'deactivated' admins, not 'invited'.
+ *      Invited admins must accept their invite (Phase 3) to become active.
+ *
+ * # Session cache invalidation
+ *
+ * Every mutation ends with `invalidateAdminSession(targetId)` so the 30-second
+ * per-admin status cache in `requireAdmin()` sees the new state on the very
+ * next request. Without this call, a deactivated admin could continue making
+ * authenticated requests for up to 30 seconds.
+ *
+ * # This module never throws on invariant failures — it returns a typed
+ * discriminated union `{ ok: true }` or `{ ok: false, error: {...} }`.
+ * Unexpected runtime errors (DB connectivity, etc.) still throw and bubble
+ * up to the API route's try/catch.
+ */
+import { and, eq, ilike, or, sql, desc } from 'drizzle-orm';
+import { getDb } from '../../core/db/client';
+import * as schema from '../../core/db/schema';
+import { canManageUser, roleLabel } from '../permissions';
+import { findAdminById, findAdminByEmail } from './admin-service';
+import { invalidateAdminSession } from './admin-session';
+import { createInviteToken, deleteAdminInviteTokens, INVITE_EXPIRY_HOURS, } from './admin-invite';
+import { sendAdminInviteEmail } from '../../emails/send/admin-auth';
+import { getStoreUrl } from '../../emails/config';
+// =============================================================================
+// List (read path)
+// =============================================================================
+/**
+ * List admins with filters and pagination.
+ *
+ * Returns the raw `StoreAdmin` rows — the caller is responsible for stripping
+ * sensitive fields (`passwordHash`) before serializing to JSON. The API
+ * handler does this mapping.
+ */
+export async function listAdmins(opts = {}) {
+    const db = getDb();
+    const limit = Math.max(1, Math.min(100, opts.limit ?? 20));
+    const offset = Math.max(0, opts.offset ?? 0);
+    // Build WHERE conditions
+    const conditions = [];
+    if (opts.search && opts.search.trim()) {
+        const pattern = `%${opts.search.trim()}%`;
+        conditions.push(or(ilike(schema.storeAdmins.email, pattern), ilike(schema.storeAdmins.name, pattern)));
+    }
+    if (opts.status && opts.status !== 'all') {
+        conditions.push(eq(schema.storeAdmins.status, opts.status));
+    }
+    if (opts.role && opts.role !== 'all') {
+        conditions.push(eq(schema.storeAdmins.role, opts.role));
+    }
+    const whereClause = conditions.length > 0 ? and(...conditions) : undefined;
+    // Two parallel queries: page + count
+    const [admins, countResult] = await Promise.all([
+        db
+            .select()
+            .from(schema.storeAdmins)
+            .where(whereClause)
+            // Owners first, then by creation date (newest first)
+            .orderBy(sql `CASE ${schema.storeAdmins.role}
+          WHEN 'owner' THEN 0
+          WHEN 'administrator' THEN 1
+          WHEN 'admin' THEN 1
+          WHEN 'manager' THEN 2
+          WHEN 'user' THEN 3
+          ELSE 4
+        END`, desc(schema.storeAdmins.createdAt))
+            .limit(limit)
+            .offset(offset),
+        db
+            .select({ count: sql `COUNT(*)::int` })
+            .from(schema.storeAdmins)
+            .where(whereClause),
+    ]);
+    return {
+        admins,
+        total: Number(countResult[0]?.count ?? 0),
+    };
+}
+// =============================================================================
+// Helper: count active owners
+// =============================================================================
+/**
+ * Count admins with role='owner' and status='active'.
+ *
+ * The single source of truth for the last-owner invariant. Always queried
+ * fresh — it's a one-row COUNT, trivially fast, and caching would introduce
+ * staleness risk for a safety-critical check.
+ */
+export async function countActiveOwners() {
+    const db = getDb();
+    const [row] = await db
+        .select({ count: sql `COUNT(*)::int` })
+        .from(schema.storeAdmins)
+        .where(and(eq(schema.storeAdmins.role, 'owner'), eq(schema.storeAdmins.status, 'active')));
+    return Number(row?.count ?? 0);
+}
+// =============================================================================
+// Deactivate
+// =============================================================================
+/**
+ * Soft-delete an admin: set status='deactivated' and stamp audit fields.
+ *
+ * Rejects on any invariant violation. Never throws on business errors;
+ * returns a typed result the caller can branch on.
+ *
+ * Uses an atomic conditional UPDATE to enforce the last-owner invariant —
+ * no check-then-act race window. If another request deactivates the second-
+ * to-last owner between our check and our update, our UPDATE's WHERE clause
+ * will match zero rows and we return LAST_OWNER_PROTECTED.
+ */
+export async function deactivateAdmin(actor, targetId) {
+    // Load target
+    const target = await findAdminById(targetId);
+    if (!target) {
+        return {
+            ok: false,
+            error: { code: 'NOT_FOUND', message: 'Admin not found.' },
+        };
+    }
+    // Self-protection
+    if (actor.id === targetId) {
+        return {
+            ok: false,
+            error: {
+                code: 'SELF_ACTION_FORBIDDEN',
+                message: 'You cannot deactivate your own account.',
+            },
+        };
+    }
+    // Lateral-escalation protection
+    if (!canManageUser(actor, { id: target.id, role: target.role })) {
+        return {
+            ok: false,
+            error: {
+                code: 'FORBIDDEN',
+                message: 'You do not have permission to deactivate this admin.',
+            },
+        };
+    }
+    // Must currently be active (nothing to deactivate otherwise)
+    if (target.status !== 'active') {
+        return {
+            ok: false,
+            error: {
+                code: 'INVALID_STATE',
+                message: `Admin is already ${target.status}.`,
+            },
+        };
+    }
+    const db = getDb();
+    // Atomic update with embedded last-owner guard. If the target is an owner
+    // and they're the last active one, the subquery `> 1` evaluates to false
+    // and the UPDATE matches zero rows.
+    //
+    // For non-owner targets, the subquery check is short-circuited because the
+    // role condition in the WHERE clause excludes them from the owner-counting
+    // branch. We use two separate UPDATEs keyed on the target's role to keep
+    // the SQL readable.
+    if (target.role === 'owner') {
+        // Guarded: only succeeds if there's at least one OTHER active owner.
+        const result = await db
+            .update(schema.storeAdmins)
+            .set({
+            status: 'deactivated',
+            deactivatedAt: new Date(),
+            deactivatedBy: actor.id,
+        })
+            .where(and(eq(schema.storeAdmins.id, targetId), eq(schema.storeAdmins.status, 'active'), sql `(SELECT COUNT(*)::int FROM ${schema.storeAdmins} WHERE role = 'owner' AND status = 'active') > 1`))
+            .returning({ id: schema.storeAdmins.id });
+        if (result.length === 0) {
+            return {
+                ok: false,
+                error: {
+                    code: 'LAST_OWNER_PROTECTED',
+                    message: 'Cannot deactivate the last active owner. Transfer ownership or promote another user first.',
+                },
+            };
+        }
+    }
+    else {
+        // Non-owner: straightforward update, still guarded on current status
+        // so concurrent requests don't double-apply.
+        const result = await db
+            .update(schema.storeAdmins)
+            .set({
+            status: 'deactivated',
+            deactivatedAt: new Date(),
+            deactivatedBy: actor.id,
+        })
+            .where(and(eq(schema.storeAdmins.id, targetId), eq(schema.storeAdmins.status, 'active')))
+            .returning({ id: schema.storeAdmins.id });
+        if (result.length === 0) {
+            // Raced with another request — target was modified mid-flight
+            return {
+                ok: false,
+                error: {
+                    code: 'INVALID_STATE',
+                    message: 'Admin state changed concurrently. Please refresh and try again.',
+                },
+            };
+        }
+    }
+    // Force the target's next request to re-read from DB → 401 kick-out
+    invalidateAdminSession(targetId);
+    return { ok: true };
+}
+// =============================================================================
+// Reactivate
+// =============================================================================
+/**
+ * Reactivate a previously-deactivated admin: set status='active', clear
+ * audit fields. Does NOT apply to 'invited' admins — they must accept
+ * their invite (Phase 3) to become active.
+ */
+export async function reactivateAdmin(actor, targetId) {
+    const target = await findAdminById(targetId);
+    if (!target) {
+        return {
+            ok: false,
+            error: { code: 'NOT_FOUND', message: 'Admin not found.' },
+        };
+    }
+    // Self-protection — a deactivated admin can't hit this endpoint anyway
+    // (they can't sign in), but defense-in-depth is cheap.
+    if (actor.id === targetId) {
+        return {
+            ok: false,
+            error: {
+                code: 'SELF_ACTION_FORBIDDEN',
+                message: 'You cannot modify your own account here.',
+            },
+        };
+    }
+    if (!canManageUser(actor, { id: target.id, role: target.role })) {
+        return {
+            ok: false,
+            error: {
+                code: 'FORBIDDEN',
+                message: 'You do not have permission to reactivate this admin.',
+            },
+        };
+    }
+    if (target.status !== 'deactivated') {
+        return {
+            ok: false,
+            error: {
+                code: 'INVALID_STATE',
+                message: `Only deactivated admins can be reactivated. This admin is ${target.status}.`,
+            },
+        };
+    }
+    const db = getDb();
+    const result = await db
+        .update(schema.storeAdmins)
+        .set({
+        status: 'active',
+        deactivatedAt: null,
+        deactivatedBy: null,
+    })
+        .where(and(eq(schema.storeAdmins.id, targetId), eq(schema.storeAdmins.status, 'deactivated')))
+        .returning({ id: schema.storeAdmins.id });
+    if (result.length === 0) {
+        return {
+            ok: false,
+            error: {
+                code: 'INVALID_STATE',
+                message: 'Admin state changed concurrently. Please refresh and try again.',
+            },
+        };
+    }
+    invalidateAdminSession(targetId);
+    return { ok: true };
+}
+// =============================================================================
+// Hard delete (owner-only, requires prior deactivation)
+// =============================================================================
+/**
+ * Permanently delete an admin row. Cascades to `admin_password_reset_tokens`
+ * and `admin_invite_tokens` via the `ON DELETE CASCADE` foreign keys defined
+ * in the Phase 0 schema.
+ *
+ * Requires the target to already be 'deactivated' — this is a two-step
+ * irreversible action. The API route additionally gates on `users.delete`
+ * permission (owner-only), but we re-check here for defense-in-depth.
+ *
+ * Dangling `deactivated_by` / `created_by` references on other admin rows
+ * are intentionally left as dangling UUIDs. The UI renders them as
+ * "Unknown user". Phase 4 may revisit.
+ */
+export async function hardDeleteAdmin(actor, targetId) {
+    const target = await findAdminById(targetId);
+    if (!target) {
+        return {
+            ok: false,
+            error: { code: 'NOT_FOUND', message: 'Admin not found.' },
+        };
+    }
+    if (actor.id === targetId) {
+        return {
+            ok: false,
+            error: {
+                code: 'SELF_ACTION_FORBIDDEN',
+                message: 'You cannot delete your own account.',
+            },
+        };
+    }
+    // Defense-in-depth: only owners reach this code path because the API
+    // handler gates on `users.delete` permission, but we re-check here so
+    // the invariant holds even if a non-owner caller bypasses the HTTP layer.
+    if (actor.role !== 'owner') {
+        return {
+            ok: false,
+            error: {
+                code: 'FORBIDDEN',
+                message: 'Only owners can permanently delete admins.',
+            },
+        };
+    }
+    if (!canManageUser(actor, { id: target.id, role: target.role })) {
+        return {
+            ok: false,
+            error: {
+                code: 'FORBIDDEN',
+                message: 'You do not have permission to delete this admin.',
+            },
+        };
+    }
+    // Must already be deactivated — the two-step safety rail for irreversible
+    // destruction. The UI never offers "Delete" on an active row.
+    if (target.status !== 'deactivated') {
+        return {
+            ok: false,
+            error: {
+                code: 'MUST_DEACTIVATE_FIRST',
+                message: 'You must deactivate this admin before permanently deleting them.',
+            },
+        };
+    }
+    // Deactivated owners don't count toward the active-owner total, so the
+    // last-owner invariant cannot be violated by this delete — but we still
+    // short-circuit with a defensive check in case the schema grows in the
+    // future and the 'deactivated' state becomes ambiguous.
+    if (target.role === 'owner') {
+        const activeOwners = await countActiveOwners();
+        if (activeOwners < 1) {
+            return {
+                ok: false,
+                error: {
+                    code: 'LAST_OWNER_PROTECTED',
+                    message: 'Cannot delete the last owner — at least one active owner must exist.',
+                },
+            };
+        }
+    }
+    const db = getDb();
+    const result = await db
+        .delete(schema.storeAdmins)
+        .where(and(eq(schema.storeAdmins.id, targetId), eq(schema.storeAdmins.status, 'deactivated')))
+        .returning({ id: schema.storeAdmins.id });
+    if (result.length === 0) {
+        return {
+            ok: false,
+            error: {
+                code: 'INVALID_STATE',
+                message: 'Admin state changed concurrently. Please refresh and try again.',
+            },
+        };
+    }
+    invalidateAdminSession(targetId);
+    return { ok: true };
+}
+// =============================================================================
+// Helper: HTTP status code mapping for errors
+// =============================================================================
+/**
+ * Map a `UserManagementError.code` to the HTTP status the API handler
+ * should respond with. Exported so both the API handlers and any future
+ * caller use the same mapping.
+ */
+export function statusCodeFor(code) {
+    switch (code) {
+        case 'NOT_FOUND':
+            return 404;
+        case 'FORBIDDEN':
+        case 'SELF_ACTION_FORBIDDEN':
+            return 403;
+        case 'VALIDATION_ERROR':
+            return 400;
+        case 'LAST_OWNER_PROTECTED':
+        case 'MUST_DEACTIVATE_FIRST':
+        case 'INVALID_STATE':
+        case 'EMAIL_ALREADY_EXISTS':
+        case 'EMAIL_ALREADY_INVITED':
+        case 'EMAIL_DEACTIVATED_EXISTS':
+            return 409;
+        default:
+            // Exhaustiveness safeguard — if the union grows without this
+            // function being updated, TS will complain here at compile time.
+            return 500;
+    }
+}
+/**
+ * Invite a new admin to manage the store.
+ *
+ * Creates a `store_admins` row in `invited` status with no password,
+ * issues an invite token (72h expiry), and sends the invite email. The
+ * caller receives both the token AND the fully-qualified invite URL — so
+ * if email delivery fails, the UI can show a "copy link manually"
+ * fallback instead of silently losing the invite.
+ *
+ * # Invariants (in order)
+ *
+ *   1. `canManageUser(actor, {role})` — actor can grant the requested role.
+ *      Administrators cannot invite owners or other administrators.
+ *   2. Valid email format + name length ≥ 2.
+ *   3. Email uniqueness — rejects with a distinct error code depending on
+ *      the existing row's status (active / invited / deactivated) so the
+ *      UI can show actionable messages.
+ *   4. Legal role: must be one of 'owner' | 'administrator' | 'manager' | 'user'.
+ *      The legacy 'admin' value is never chosen by the caller here — new
+ *      invites always use the canonical names.
+ *
+ * Email send failures are logged but NOT propagated — the invite row +
+ * token are already persisted, the caller gets the URL, and the UI
+ * handles fallback display.
+ */
+export async function inviteAdmin(actor, request) {
+    const email = (request.email || '').trim().toLowerCase();
+    const name = (request.name || '').trim();
+    const role = request.role;
+    // Basic format validation
+    if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        return {
+            ok: false,
+            error: {
+                code: 'VALIDATION_ERROR',
+                message: 'Please enter a valid email address.',
+            },
+        };
+    }
+    if (name.length < 2) {
+        return {
+            ok: false,
+            error: {
+                code: 'VALIDATION_ERROR',
+                message: 'Name must be at least 2 characters.',
+            },
+        };
+    }
+    if (role !== 'owner' &&
+        role !== 'administrator' &&
+        role !== 'manager' &&
+        role !== 'user') {
+        return {
+            ok: false,
+            error: {
+                code: 'VALIDATION_ERROR',
+                message: 'Invalid role. Must be owner, administrator, manager, or user.',
+            },
+        };
+    }
+    // Permission: actor must be allowed to grant this role. We pass a
+    // synthetic target with a fake id so `canManageUser` is just checking
+    // the role-vs-role hierarchy (it does an actor.id === target.id check
+    // for self-protection, which is irrelevant here — no self-invite).
+    if (!canManageUser(actor, { id: '__new_invitee__', role })) {
+        return {
+            ok: false,
+            error: {
+                code: 'FORBIDDEN',
+                message: `You do not have permission to invite someone as ${roleLabel(role)}.`,
+            },
+        };
+    }
+    // Email uniqueness
+    const existing = await findAdminByEmail(email);
+    if (existing) {
+        const existingStatus = existing.status ?? 'active';
+        if (existingStatus === 'active') {
+            return {
+                ok: false,
+                error: {
+                    code: 'EMAIL_ALREADY_EXISTS',
+                    message: 'An active admin with this email already exists.',
+                },
+            };
+        }
+        if (existingStatus === 'invited') {
+            return {
+                ok: false,
+                error: {
+                    code: 'EMAIL_ALREADY_INVITED',
+                    message: 'This email was already invited. Use the Resend invite action instead.',
+                },
+            };
+        }
+        return {
+            ok: false,
+            error: {
+                code: 'EMAIL_DEACTIVATED_EXISTS',
+                message: 'A previously deactivated admin exists with this email. Reactivate them instead of re-inviting.',
+            },
+        };
+    }
+    // Insert the invited admin row. passwordHash stays null until the
+    // invitee accepts the invite and sets their own.
+    const db = getDb();
+    const [created] = await db
+        .insert(schema.storeAdmins)
+        .values({
+        email,
+        name,
+        passwordHash: null,
+        role,
+        status: 'invited',
+        createdBy: actor.id,
+    })
+        .returning({ id: schema.storeAdmins.id });
+    if (!created) {
+        return {
+            ok: false,
+            error: {
+                code: 'INVALID_STATE',
+                message: 'Failed to create invited admin. Please try again.',
+            },
+        };
+    }
+    // Create the invite token (72h)
+    const { token } = await createInviteToken({
+        adminId: created.id,
+        invitedBy: actor.id,
+    });
+    // Build the invite URL. `getStoreUrl` reads from NEXT_PUBLIC_APP_URL /
+    // NEXTAUTH_URL and returns '' if neither is set — the UI still gets a
+    // valid (if short) URL it can show.
+    const storeUrl = getStoreUrl();
+    const inviteUrl = `${storeUrl}/admin/accept-invite?token=${encodeURIComponent(token)}`;
+    // Best-effort send. We never fail the invite just because the email
+    // broker is down — the owner sees the URL in the response and can
+    // share it manually.
+    try {
+        // Resolve the inviter's display name from the `store_admins` row so
+        // we can render it in the email greeting.
+        const inviter = await findAdminById(actor.id);
+        const inviterName = inviter?.name || 'An admin';
+        await sendAdminInviteEmail({
+            to: email,
+            adminName: name,
+            inviterName,
+            roleLabel: roleLabel(role),
+            acceptLink: inviteUrl,
+            expiryHours: INVITE_EXPIRY_HOURS,
+        });
+    }
+    catch (err) {
+        console.error('[user-management] Failed to send invite email:', err instanceof Error ? err.message : err);
+        // Intentionally swallow — the caller already has the URL.
+    }
+    return {
+        ok: true,
+        adminId: created.id,
+        token,
+        inviteUrl,
+    };
+}
+/**
+ * Resend an invite to an admin who is still in `invited` status.
+ *
+ * Generates a fresh token (invalidating any previous ones) and resends
+ * the email. Preserves the single-active-token policy — older tokens
+ * are deleted before the new one is created.
+ */
+export async function resendAdminInvite(actor, targetId) {
+    const target = await findAdminById(targetId);
+    if (!target) {
+        return {
+            ok: false,
+            error: { code: 'NOT_FOUND', message: 'Admin not found.' },
+        };
+    }
+    if (!canManageUser(actor, { id: target.id, role: target.role })) {
+        return {
+            ok: false,
+            error: {
+                code: 'FORBIDDEN',
+                message: 'You do not have permission to resend this invite.',
+            },
+        };
+    }
+    if (target.status !== 'invited') {
+        return {
+            ok: false,
+            error: {
+                code: 'INVALID_STATE',
+                message: target.status === 'active'
+                    ? 'This admin has already accepted their invite.'
+                    : 'This admin cannot be re-invited.',
+            },
+        };
+    }
+    // Clear previous tokens so only the new one is valid
+    await deleteAdminInviteTokens(target.id);
+    const { token } = await createInviteToken({
+        adminId: target.id,
+        invitedBy: actor.id,
+    });
+    const storeUrl = getStoreUrl();
+    const inviteUrl = `${storeUrl}/admin/accept-invite?token=${encodeURIComponent(token)}`;
+    try {
+        const inviter = await findAdminById(actor.id);
+        const inviterName = inviter?.name || 'An admin';
+        await sendAdminInviteEmail({
+            to: target.email,
+            adminName: target.name,
+            inviterName,
+            roleLabel: roleLabel(target.role),
+            acceptLink: inviteUrl,
+            expiryHours: INVITE_EXPIRY_HOURS,
+        });
+    }
+    catch (err) {
+        console.error('[user-management] Failed to resend invite email:', err instanceof Error ? err.message : err);
+    }
+    return { ok: true, token, inviteUrl };
+}
+// =============================================================================
+// Phase 3 — Cancel invite
+// =============================================================================
+/**
+ * Cancel a pending invite. Hard-deletes the `store_admins` row — which
+ * cascades via FK to delete all `admin_invite_tokens` rows for that
+ * admin. Only valid for `invited` status (not `active` / `deactivated`).
+ *
+ * Uses `users.write` permission (administrators + owners), unlike the
+ * DELETE endpoint which is owner-only. Canceling an invite for a manager
+ * or user is a normal administrator action, not a destructive one.
+ */
+export async function cancelAdminInvite(actor, targetId) {
+    const target = await findAdminById(targetId);
+    if (!target) {
+        return {
+            ok: false,
+            error: { code: 'NOT_FOUND', message: 'Admin not found.' },
+        };
+    }
+    // Defense-in-depth: self-action should be impossible (you can't invite
+    // yourself), but check anyway.
+    if (actor.id === targetId) {
+        return {
+            ok: false,
+            error: {
+                code: 'SELF_ACTION_FORBIDDEN',
+                message: 'You cannot cancel your own invite.',
+            },
+        };
+    }
+    if (!canManageUser(actor, { id: target.id, role: target.role })) {
+        return {
+            ok: false,
+            error: {
+                code: 'FORBIDDEN',
+                message: 'You do not have permission to cancel this invite.',
+            },
+        };
+    }
+    if (target.status !== 'invited') {
+        return {
+            ok: false,
+            error: {
+                code: 'INVALID_STATE',
+                message: 'Only pending invites can be cancelled.',
+            },
+        };
+    }
+    const db = getDb();
+    const result = await db
+        .delete(schema.storeAdmins)
+        .where(and(eq(schema.storeAdmins.id, targetId), eq(schema.storeAdmins.status, 'invited')))
+        .returning({ id: schema.storeAdmins.id });
+    if (result.length === 0) {
+        return {
+            ok: false,
+            error: {
+                code: 'INVALID_STATE',
+                message: 'Admin state changed concurrently. Please refresh and try again.',
+            },
+        };
+    }
+    invalidateAdminSession(targetId);
+    return { ok: true };
+}
+// =============================================================================
+// Phase 3 — Change role
+// =============================================================================
+/**
+ * Change an admin's role.
+ *
+ * Invariants (in strict order):
+ *
+ *   1. Target exists (→ NOT_FOUND).
+ *   2. Self-protection — actor cannot change their own role (→
+ *      SELF_ACTION_FORBIDDEN). A solo owner needing to demote themselves
+ *      must either invite another owner first, or use a future Phase 4
+ *      emergency-reset flow.
+ *   3. canManageUser at CURRENT role — actor must be allowed to manage
+ *      the target at their current role (administrator cannot touch
+ *      owners or other administrators).
+ *   4. canManageUser at NEW role — actor must be allowed to grant the
+ *      new role (administrator cannot promote to administrator/owner).
+ *   5. No-op fast path — if newRole === current role, return success
+ *      without touching the DB.
+ *   6. Last-owner protection — if target is currently 'owner' and the
+ *      new role is not 'owner', require `countActiveOwners() > 1`.
+ *      Enforced atomically via a conditional UPDATE so there's no
+ *      check-then-act race window.
+ *   7. Update; invalidate session cache.
+ */
+export async function changeAdminRole(actor, targetId, newRole) {
+    const target = await findAdminById(targetId);
+    if (!target) {
+        return {
+            ok: false,
+            error: { code: 'NOT_FOUND', message: 'Admin not found.' },
+        };
+    }
+    if (actor.id === targetId) {
+        return {
+            ok: false,
+            error: {
+                code: 'SELF_ACTION_FORBIDDEN',
+                message: 'You cannot change your own role. Ask another owner to make this change.',
+            },
+        };
+    }
+    // Validate role value
+    if (newRole !== 'owner' &&
+        newRole !== 'administrator' &&
+        newRole !== 'manager' &&
+        newRole !== 'user') {
+        return {
+            ok: false,
+            error: {
+                code: 'VALIDATION_ERROR',
+                message: 'Invalid role.',
+            },
+        };
+    }
+    // canManageUser at CURRENT role
+    if (!canManageUser(actor, { id: target.id, role: target.role })) {
+        return {
+            ok: false,
+            error: {
+                code: 'FORBIDDEN',
+                message: 'You do not have permission to manage this admin.',
+            },
+        };
+    }
+    // canManageUser at NEW role (pass a synthetic target id so the
+    // self-check is neutral; we already ruled out self above)
+    if (!canManageUser(actor, { id: '__new_role_target__', role: newRole })) {
+        return {
+            ok: false,
+            error: {
+                code: 'FORBIDDEN',
+                message: `You do not have permission to grant the ${roleLabel(newRole)} role.`,
+            },
+        };
+    }
+    // No-op fast path. Note: the legacy 'admin' value is equivalent to
+    // 'administrator' in our permission model, so treat them as identical
+    // here to avoid rewriting old rows to the new name. The validation
+    // block above narrows `newRole` to the four canonical values, so we
+    // only need to normalize the TARGET's role (which may still be 'admin').
+    const currentCanonical = target.role === 'admin' ? 'administrator' : target.role;
+    if (currentCanonical === newRole) {
+        return { ok: true };
+    }
+    const db = getDb();
+    if (target.role === 'owner' && newRole !== 'owner') {
+        // Demotion from owner — guarded with the last-owner invariant
+        const result = await db
+            .update(schema.storeAdmins)
+            .set({ role: newRole })
+            .where(and(eq(schema.storeAdmins.id, targetId), eq(schema.storeAdmins.role, 'owner'), sql `(SELECT COUNT(*)::int FROM ${schema.storeAdmins} WHERE role = 'owner' AND status = 'active') > 1`))
+            .returning({ id: schema.storeAdmins.id });
+        if (result.length === 0) {
+            return {
+                ok: false,
+                error: {
+                    code: 'LAST_OWNER_PROTECTED',
+                    message: 'Cannot demote the last active owner. Promote another admin to owner first.',
+                },
+            };
+        }
+    }
+    else {
+        // Non-owner-demotion path: straightforward update
+        const result = await db
+            .update(schema.storeAdmins)
+            .set({ role: newRole })
+            .where(eq(schema.storeAdmins.id, targetId))
+            .returning({ id: schema.storeAdmins.id });
+        if (result.length === 0) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INVALID_STATE',
+                    message: 'Admin state changed concurrently. Please refresh and try again.',
+                },
+            };
+        }
+    }
+    invalidateAdminSession(targetId);
+    return { ok: true };
+}
+//# sourceMappingURL=user-management.js.map