@cosmicdrift/kumiko-bundled-features 0.340.0 → 0.341.0

package/dist/auth-email-password/bootstrap.d.ts

@@ -0,0 +1,74 @@
+import { makeDispatchSystemWrite } from "@cosmicdrift/kumiko-framework/api";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
+import type { Redis } from "ioredis";
+import type { GLOBAL_ROLE_OPTIONS } from "../user/constants.js";
+type GlobalRole = (typeof GLOBAL_ROLE_OPTIONS)[number];
+export type BootstrapInvite = {
+    readonly email: string;
+    /** Membership role in the tenant, validated like a tenant-admin invite
+     *  (reserved roles such as SystemAdmin are rejected here). */
+    readonly role: string;
+};
+export type BootstrapSeedDeps = {
+    readonly tenantId: TenantId;
+    readonly db: DbConnection;
+    readonly dispatchSystemWrite: ReturnType<typeof makeDispatchSystemWrite>;
+};
+export type BootstrapConfigValue = string | number | boolean;
+export type BootstrapTenant = {
+    readonly id: TenantId;
+    readonly key: string;
+    readonly name: string;
+    /** Tenant-scope config values by qualified key (e.g.
+     *  `"auth-mfa:config:required": "admins"`), written as system writes on
+     *  EVERY run: config is declarative, so a rerun converges to the plan and
+     *  a value that already matches is not rewritten. Unlike `seed` it also
+     *  applies to tenants that already exist. */
+    readonly config?: Readonly<Record<string, BootstrapConfigValue>>;
+    readonly invites?: readonly BootstrapInvite[];
+};
+export type BootstrapSystemAdmin = {
+    readonly email: string;
+    /** Home tenant: login needs a membership, so the SystemAdmin is invited
+     *  into this tenant with `role` and receives the global role on accept. */
+    readonly tenantId: TenantId;
+    readonly role: string;
+};
+export type BootstrapPlan = {
+    readonly tenants: readonly BootstrapTenant[];
+    readonly systemAdmins?: readonly BootstrapSystemAdmin[];
+    /** Runs for each tenant right after this run created it. An existing
+     *  tenant is never seeded again — also not when a previous run failed
+     *  inside the seed (that run fails; clean up by hand). */
+    readonly seed?: (deps: BootstrapSeedDeps) => Promise<void>;
+};
+export type BootstrapDeps = {
+    readonly db: DbConnection;
+    readonly redis: Redis;
+    readonly dispatcher: Dispatcher;
+};
+export type BootstrapTenantOutcome = "created" | "exists";
+export type BootstrapInviteOutcome = "invited" | "resent" | "pending" | "active" | "cancelled" | "role-mismatch";
+export type BootstrapReport = {
+    readonly tenants: ReadonlyArray<{
+        readonly id: TenantId;
+        readonly outcome: BootstrapTenantOutcome;
+        readonly seeded: boolean;
+        /** Qualified keys this run wrote (new or changed); empty on a no-op rerun. */
+        readonly configApplied: readonly string[];
+    }>;
+    readonly invites: ReadonlyArray<{
+        readonly tenantId: TenantId;
+        readonly email: string;
+        readonly globalRoles: readonly GlobalRole[];
+        readonly outcome: BootstrapInviteOutcome;
+    }>;
+};
+export declare class BootstrapPlanError extends Error {
+}
+export declare class BootstrapWriteError extends Error {
+}
+export declare function bootstrapTenants(deps: BootstrapDeps, plan: BootstrapPlan): Promise<BootstrapReport>;
+export {};

package/dist/auth-email-password/bootstrap.js

@@ -0,0 +1,165 @@
+// Passwordless, idempotent first-run provisioning: tenants plus invitations
+// (optionally carrying global roles such as SystemAdmin). Every write goes
+// through the dispatcher as the system user, so hooks, events and jobs fire
+// exactly as for any other writer. Nobody gets a role before accepting: the
+// invitation row holds membership role + global roles until the invitee
+// accepts through the regular invite-accept routes.
+import { makeDispatchSystemWrite } from "@cosmicdrift/kumiko-framework/api";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { ConfigScopes, createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+// kumiko-lint-ignore cross-feature-import bootstrap sets per-tenant config through the config feature's write handler
+import { ConfigHandlers } from "../config/constants.js";
+// kumiko-lint-ignore cross-feature-import bootstrap compares against the stored config row to stay idempotent
+import { findConfigRow } from "../config/write-helpers.js";
+// kumiko-lint-ignore cross-feature-import bootstrap provisions tenant + invitation rows owned by the tenant feature
+import { TenantHandlers } from "../tenant/constants.js";
+// kumiko-lint-ignore cross-feature-import bootstrap provisions tenant + invitation rows owned by the tenant feature
+import { INVITATION_STATUS, tenantInvitationsTable } from "../tenant/invitation-table.js";
+// kumiko-lint-ignore cross-feature-import bootstrap checks existing memberships
+import { tenantMembershipsTable } from "../tenant/membership-table.js";
+// kumiko-lint-ignore cross-feature-import bootstrap checks for an existing tenant
+import { tenantTable } from "../tenant/schema/tenant.js";
+// kumiko-lint-ignore cross-feature-import bootstrap skips already activated users
+import { userTable } from "../user/schema/user.js";
+import { AuthHandlers } from "./constants.js";
+import { hasLiveInviteToken } from "./invite-token-store.js";
+export class BootstrapPlanError extends Error {
+}
+export class BootstrapWriteError extends Error {
+}
+function planInvites(plan) {
+    const tenantIds = new Set(plan.tenants.map((t) => t.id));
+    const invites = [];
+    for (const admin of plan.systemAdmins ?? []) {
+        if (!tenantIds.has(admin.tenantId)) {
+            throw new BootstrapPlanError(`systemAdmins: ${admin.email} references tenant ${admin.tenantId}, which is not in tenants`);
+        }
+        invites.push({
+            tenantId: admin.tenantId,
+            email: admin.email.toLowerCase(),
+            role: admin.role,
+            globalRoles: ["SystemAdmin"],
+        });
+    }
+    for (const tenant of plan.tenants) {
+        for (const invite of tenant.invites ?? []) {
+            invites.push({
+                tenantId: tenant.id,
+                email: invite.email.toLowerCase(),
+                role: invite.role,
+                globalRoles: [],
+            });
+        }
+    }
+    // One invitation row per (tenant, email): a second entry would overwrite
+    // the first one's role or global roles.
+    const seen = new Set();
+    for (const invite of invites) {
+        const key = `${invite.tenantId}\u0000${invite.email}`;
+        if (seen.has(key)) {
+            throw new BootstrapPlanError(`${invite.email} is listed twice for tenant ${invite.tenantId} (systemAdmins and tenants[].invites share one invitation per tenant)`);
+        }
+        seen.add(key);
+    }
+    return invites;
+}
+async function ensureTenant(deps, tenant) {
+    const existing = await fetchOne(deps.db, tenantTable, { id: tenant.id });
+    if (existing)
+        return "exists";
+    const result = await deps.dispatcher.write(TenantHandlers.create, { id: tenant.id, key: tenant.key, name: tenant.name }, createSystemUser(tenant.id));
+    if (!result.isSuccess) {
+        throw new BootstrapWriteError(`creating tenant ${tenant.key} (${tenant.id}) failed: ${result.error.code} — ${result.error.message}`);
+    }
+    return "created";
+}
+async function applyTenantConfig(deps, tenant) {
+    const applied = [];
+    for (const [key, value] of Object.entries(tenant.config ?? {})) {
+        const existing = await findConfigRow(deps.db, key, tenant.id, null);
+        if (existing?.value === JSON.stringify(value))
+            continue;
+        const result = await deps.dispatcher.write(ConfigHandlers.set, { key, value, scope: ConfigScopes.tenant }, 
+        // SystemAdmin on top of the system role: keys with the default tenant
+        // write access (admin roles) reject a bare system user, system-only keys
+        // accept it.
+        createSystemUser(tenant.id, ["SystemAdmin"]));
+        if (!result.isSuccess) {
+            throw new BootstrapWriteError(`setting config ${key} for tenant ${tenant.id} failed: ${result.error.code} — ${result.error.message}`);
+        }
+        applied.push(key);
+    }
+    return applied;
+}
+async function holdsInvitedAccess(deps, invite) {
+    const user = await fetchOne(deps.db, userTable, {
+        email: invite.email,
+        isDeleted: false,
+    });
+    if (!user)
+        return false;
+    const membership = await fetchOne(deps.db, tenantMembershipsTable, {
+        userId: user.id,
+        tenantId: invite.tenantId,
+    });
+    if (!membership)
+        return false;
+    const userGlobalRoles = parseRoles(user.roles);
+    return invite.globalRoles.every((role) => userGlobalRoles.includes(role));
+}
+async function decideInvite(deps, invite) {
+    if (await holdsInvitedAccess(deps, invite))
+        return "active";
+    const invitation = await fetchOne(deps.db, tenantInvitationsTable, {
+        tenantId: invite.tenantId,
+        email: invite.email,
+    });
+    if (!invitation)
+        return "invited";
+    if (invitation.status === INVITATION_STATUS.cancelled)
+        return "cancelled";
+    const storedGlobalRoles = parseRoles(invitation.globalRoles);
+    if (!invite.globalRoles.every((role) => storedGlobalRoles.includes(role))) {
+        return "role-mismatch";
+    }
+    if (invitation.status === INVITATION_STATUS.accepted)
+        return "active";
+    if (await hasLiveInviteToken(deps.redis, invitation.id))
+        return "pending";
+    return "resent";
+}
+function isMailingOutcome(outcome) {
+    return outcome === "invited" || outcome === "resent";
+}
+export async function bootstrapTenants(deps, plan) {
+    const plannedInvites = planInvites(plan);
+    const dispatchSystemWrite = makeDispatchSystemWrite(deps.dispatcher);
+    const tenants = [];
+    for (const tenant of plan.tenants) {
+        const outcome = await ensureTenant(deps, tenant);
+        const shouldSeed = outcome === "created" && plan.seed !== undefined;
+        if (shouldSeed) {
+            await plan.seed?.({ tenantId: tenant.id, db: deps.db, dispatchSystemWrite });
+        }
+        const configApplied = await applyTenantConfig(deps, tenant);
+        tenants.push({ id: tenant.id, outcome, seeded: shouldSeed, configApplied });
+    }
+    const invites = [];
+    for (const invite of plannedInvites) {
+        const outcome = await decideInvite(deps, invite);
+        if (isMailingOutcome(outcome)) {
+            const result = await deps.dispatcher.write(AuthHandlers.systemInviteCreate, { email: invite.email, role: invite.role, globalRoles: invite.globalRoles }, createSystemUser(invite.tenantId));
+            if (!result.isSuccess) {
+                throw new BootstrapWriteError(`inviting ${invite.email} into tenant ${invite.tenantId} failed: ${result.error.code} — ${result.error.message}`);
+            }
+        }
+        invites.push({
+            tenantId: invite.tenantId,
+            email: invite.email,
+            globalRoles: invite.globalRoles,
+            outcome,
+        });
+    }
+    return { tenants, invites };
+}

package/dist/auth-email-password/constants.d.ts

@@ -13,6 +13,7 @@ export declare const AuthHandlers: {
     readonly signupRequest: "auth-email-password:write:signup-request";
     readonly signupConfirm: "auth-email-password:write:signup-confirm";
     readonly inviteCreate: "auth-email-password:write:invite-create";
+    readonly systemInviteCreate: "auth-email-password:write:system-invite-create";
     readonly inviteAccept: "auth-email-password:write:invite-accept";
     readonly inviteAcceptWithLogin: "auth-email-password:write:invite-accept-with-login";
     readonly inviteSignupComplete: "auth-email-password:write:invite-signup-complete";
@@ -38,6 +39,7 @@ export declare const AuthErrors: {
     readonly invalidInviteToken: "invalid_invite_token";
     readonly inviteEmailMismatch: "invite_email_mismatch";
     readonly inviteAlreadyMember: "invite_already_member";
+    readonly inviteAlreadyAccepted: "invite_already_accepted";
     readonly accountLocked: "account_locked";
     readonly accountRestricted: "account_restricted";
 };

package/dist/auth-email-password/constants.js

@@ -38,6 +38,9 @@ export const AuthHandlers = {
     //   inviteSignupComplete: anon user with new email → POST token + password
     //   inviteCancel: admin cancels a pending invite
     inviteCreate: "auth-email-password:write:invite-create",
+    // System-only variant (access.system) that may carry global roles — see
+    // invite-create.write.ts. Dispatched in-process by runBootstrap.
+    systemInviteCreate: "auth-email-password:write:system-invite-create",
     inviteAccept: "auth-email-password:write:invite-accept",
     inviteAcceptWithLogin: "auth-email-password:write:invite-accept-with-login",
     inviteSignupComplete: "auth-email-password:write:invite-signup-complete",
@@ -92,6 +95,8 @@ export const AuthErrors = {
     invalidInviteToken: "invalid_invite_token",
     inviteEmailMismatch: "invite_email_mismatch",
     inviteAlreadyMember: "invite_already_member",
+    // System invite (waitlist) refuses to reset an invitation the invitee already accepted.
+    inviteAlreadyAccepted: "invite_already_accepted",
     // Account-lockout: login refuses with this code when the user's streak of
     // failed attempts has crossed the configured threshold. The error detail
     // carries `retryAfterSeconds` so the UI can show a countdown. Returning a

package/dist/auth-email-password/errors.d.ts

@@ -1,6 +1,7 @@
 export declare function invalidCredentials(): import("@cosmicdrift/kumiko-types/write-error-info-types").WriteFailure;
 export declare function invalidInviteToken(): import("@cosmicdrift/kumiko-types/write-error-info-types").WriteFailure;
 export declare function inviteEmailMismatch(): import("@cosmicdrift/kumiko-types/write-error-info-types").WriteFailure;
+export declare function inviteAlreadyAccepted(): import("@cosmicdrift/kumiko-types/write-error-info-types").WriteFailure;
 export declare function invalidResetToken(): import("@cosmicdrift/kumiko-types/write-error-info-types").WriteFailure;
 export declare function invalidUnlockToken(): import("@cosmicdrift/kumiko-types/write-error-info-types").WriteFailure;
 export declare function invalidVerificationToken(): import("@cosmicdrift/kumiko-types/write-error-info-types").WriteFailure;

package/dist/auth-email-password/errors.js

@@ -19,6 +19,12 @@ export function inviteEmailMismatch() {
     }));
 }
 // @wrapper-known error-helper
+export function inviteAlreadyAccepted() {
+    return writeFailure(new UnprocessableError(AuthErrors.inviteAlreadyAccepted, {
+        i18nKey: "auth.errors.inviteAlreadyAccepted",
+    }));
+}
+// @wrapper-known error-helper
 export function invalidResetToken() {
     return writeFailure(new UnprocessableError(AuthErrors.invalidResetToken, {
         i18nKey: "auth.errors.invalidResetToken",

package/dist/auth-email-password/feature.js

@@ -5,7 +5,7 @@ import { changePasswordWrite } from "./handlers/change-password.write.js";
 import { createConfirmAccountUnlockHandler } from "./handlers/confirm-account-unlock.write.js";
 import { createInviteAcceptHandler } from "./handlers/invite-accept.write.js";
 import { createInviteAcceptWithLoginHandler } from "./handlers/invite-accept-with-login.write.js";
-import { createInviteCreateHandler, } from "./handlers/invite-create.write.js";
+import { createInviteCreateHandler, createSystemInviteCreateHandler, } from "./handlers/invite-create.write.js";
 import { inviteInfoQuery } from "./handlers/invite-info.query.js";
 import { createInviteSignupCompleteHandler } from "./handlers/invite-signup-complete.write.js";
 import { createLoginHandler } from "./handlers/login.write.js";
@@ -123,6 +123,7 @@ export function createAuthEmailPasswordFeature(opts = {}) {
         }
         if (opts.invite) {
             r.writeHandler(createInviteCreateHandler(opts.invite));
+            r.writeHandler(createSystemInviteCreateHandler(opts.invite));
             r.writeHandler(createInviteAcceptHandler());
             // Same gates as the `login` handler above (lockout, password,
             // email-verified, account-status, MFA) — see invite-accept-with-login.write.ts.

package/dist/auth-email-password/handlers/invite-accept-with-login.write.js

@@ -30,6 +30,8 @@ import { decryptStoredPii, sessionLocaleField, sessionTimezoneField } from "../.
 import { INVITATION_STATUS, tenantInvitationEntity, tenantInvitationsTable, } from "../../tenant/invitation-table.js";
 // kumiko-lint-ignore cross-feature-import membership grant for a privileged cross-tenant add
 import { grantInvitedMembershipRole, invitationIssuedAt } from "../../tenant/invited-membership.js";
+// kumiko-lint-ignore cross-feature-import global roles granted on invite accept live on the user row
+import { grantInvitedGlobalRoles, parseInvitedGlobalRoles, } from "../../user/invited-global-roles.js";
 // kumiko-lint-ignore cross-feature-import login-style password-check
 import { userTable } from "../../user/schema/user.js";
 import { AUTH_LOCKOUT_DEFAULT_DURATION_MINUTES, AUTH_LOCKOUT_DEFAULT_MAX_FAILED_ATTEMPTS, } from "../constants.js";
@@ -120,6 +122,12 @@ export function createInviteAcceptWithLoginHandler(opts = {}) {
                 });
                 if (!grant.isSuccess)
                     return grant;
+                const globalGrant = await grantInvitedGlobalRoles(dbConn, {
+                    userId,
+                    globalRoles: parseInvitedGlobalRoles(invitation.globalRoles),
+                });
+                if (!globalGrant.isSuccess)
+                    return globalGrant;
                 // Invitation → accepted: TenantDb for the invitation's tenant.
                 const invitationTdb = createTenantDb(dbConn, invitationTenantId, "system");
                 const updateResult = await invitationExecutor.update({
@@ -132,7 +140,7 @@ export function createInviteAcceptWithLoginHandler(opts = {}) {
                 await deleteInviteToken(ctx.redis, { invitationId, token: event.payload.token });
                 // buildSessionRoles calls stripForbiddenMembershipRoles internally —
                 // a reserved role on an existing membership must never reach the session.
-                const mergedRoles = buildSessionRoles([], grant.data.roles);
+                const mergedRoles = buildSessionRoles(globalGrant.data.roles, grant.data.roles);
                 // MFA gate runs after membership is granted (mirrors login.write.ts's
                 // own order: membership resolution before MFA) — a challenge halts
                 // the session mint, not the invite acceptance itself.

package/dist/auth-email-password/handlers/invite-accept.write.js

@@ -24,6 +24,8 @@ import { decryptStoredPii } from "../../shared/index.js";
 import { INVITATION_STATUS, tenantInvitationEntity, tenantInvitationsTable, } from "../../tenant/invitation-table.js";
 // kumiko-lint-ignore cross-feature-import membership grant for a privileged cross-tenant add (like provisionSignupAccount)
 import { grantInvitedMembershipRole, invitationIssuedAt } from "../../tenant/invited-membership.js";
+// kumiko-lint-ignore cross-feature-import global roles granted on invite accept live on the user row
+import { grantInvitedGlobalRoles, parseInvitedGlobalRoles, } from "../../user/invited-global-roles.js";
 // kumiko-lint-ignore cross-feature-import auth handler reads user-row für email-match
 import { userTable } from "../../user/schema/user.js";
 import { invalidInviteToken, inviteEmailMismatch } from "../errors.js";
@@ -96,6 +98,12 @@ export function createInviteAcceptHandler() {
                 if (!grant.isSuccess)
                     return grant;
                 const { alreadyMember } = grant.data;
+                const globalGrant = await grantInvitedGlobalRoles(dbConn, {
+                    userId: event.user.id,
+                    globalRoles: parseInvitedGlobalRoles(invitation.globalRoles),
+                });
+                if (!globalGrant.isSuccess)
+                    return globalGrant;
                 // Invitation-Status → accepted via event-store-executor.
                 // Tenant-scoping: ctx.db ist auf event.user.tenantId gescopt
                 // (= NICHT der invitation-tenant). Eigene TenantDb für den

package/dist/auth-email-password/handlers/invite-create.write.d.ts

@@ -1,11 +1,14 @@
 import * as z from "zod";
+import { GLOBAL_ROLE_OPTIONS } from "../../user/constants.js";
 import type { AuthMailLocale } from "../email-templates.js";
+type GlobalRole = (typeof GLOBAL_ROLE_OPTIONS)[number];
 export type InviteCreateData = {
     readonly kind: "invite-created";
     readonly invitationId: string;
     readonly tenantId: string;
     readonly email: string;
     readonly role: string;
+    readonly globalRoles: readonly GlobalRole[];
     readonly expiresAt: string;
 };
 export type InviteCreateOptions = {
@@ -31,3 +34,11 @@ export declare function createInviteCreateHandler(opts: InviteCreateOptions): im
     email: z.ZodEmail;
     role: z.ZodString;
 }, z.core.$strip>, InviteCreateData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export declare function createSystemInviteCreateHandler(opts: InviteCreateOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"system-invite-create", z.ZodObject<{
+    email: z.ZodEmail;
+    role: z.ZodString;
+    globalRoles: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        SystemAdmin: "SystemAdmin";
+    }>>>;
+}, z.core.$strip>, InviteCreateData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export {};

package/dist/auth-email-password/handlers/invite-create.write.js

@@ -19,15 +19,18 @@
 import { generateToken } from "@cosmicdrift/kumiko-framework/api";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { access, assignableAppRolesOf, defineWriteHandler, } from "@cosmicdrift/kumiko-framework/engine";
-import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "temporal-polyfill";
 import * as z from "zod";
 // kumiko-lint-ignore cross-feature-import invite-flow lebt in auth-email-password (Magic-Link-Pattern), DB-row-owner ist tenant-feature
 import { INVITATION_STATUS, tenantInvitationEntity, tenantInvitationsTable, } from "../../tenant/invitation-table.js";
 // kumiko-lint-ignore cross-feature-import membership-role validation owned by tenant-feature
 import { findForbiddenMembershipRole, findForbiddenRoleAssignment, reservedMembershipRoleError, unassignableMembershipRoleError, } from "../../tenant/membership-roles.js";
+// kumiko-lint-ignore cross-feature-import global-role options are owned by the user feature
+import { GLOBAL_ROLE_OPTIONS } from "../../user/constants.js";
 import { AUTH_INVITE_DEFAULT_TTL_MINUTES } from "../constants.js";
 import { renderInviteEmail } from "../email-templates.js";
+import { inviteAlreadyAccepted } from "../errors.js";
 import { invalidateExistingInviteToken, storeInviteToken } from "../invite-token-store.js";
 import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-mail.js";
 const INVITE_NOTIFICATION_TYPE = "auth-email-password:invite";
@@ -44,102 +47,146 @@ const executor = createEventStoreExecutor(tenantInvitationsTable, tenantInvitati
 function findRankedRole(roles) {
     return roles.find((role) => findForbiddenRoleAssignment(["system"], [role], []) === undefined);
 }
-export function createInviteCreateHandler(opts) {
+function checkAssignableInviteRole(opts, inviterRoles, role, ctx) {
+    const forbiddenRole = findForbiddenMembershipRole([role]);
+    if (forbiddenRole !== undefined)
+        return writeFailure(reservedMembershipRoleError(forbiddenRole));
+    const elevationForbidden = findForbiddenRoleAssignment(inviterRoles, [role], [], assignableAppRolesOf(ctx.registry));
+    if (elevationForbidden !== undefined &&
+        !opts.additionalAssignableRoles?.includes(elevationForbidden)) {
+        return writeFailure(unassignableMembershipRoleError(elevationForbidden));
+    }
+    if (opts.canAssignRole && !opts.canAssignRole(inviterRoles, role)) {
+        return writeFailure(unassignableMembershipRoleError(role));
+    }
+    return undefined;
+}
+async function issueInvitation(opts, ttlSeconds, request, inviter, ctx, refuseAccepted = false) {
+    if (!ctx.redis) {
+        return writeFailure(new InternalError({ message: "invite-create requires ctx.redis for token store" }));
+    }
+    const email = request.email.toLowerCase();
+    const tenantId = inviter.tenantId;
+    const expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });
+    // The unique index allows one row per (tenantId, email). Whatever its
+    // status, a re-invite resets it to pending with a fresh token.
+    const existing = await ctx.db.fetchOne(tenantInvitationsTable, { tenantId, email });
+    let invitationId;
+    if (existing) {
+        // Provisioning callers (waitlist) must not flip an accepted invite back to
+        // pending: that would let them cancel a live membership's invitation.
+        // The tenant-admin path keeps resetting because re-inviting a member is
+        // how roles get re-assigned.
+        if (refuseAccepted && existing["status"] === INVITATION_STATUS.accepted) {
+            return inviteAlreadyAccepted();
+        }
+        invitationId = existing["id"]; // @cast-boundary db-row
+        const existingVersion = existing["version"]; // @cast-boundary db-row
+        // At most one live invite token per invitation: invalidate
+        // whatever's there before minting the new one.
+        await invalidateExistingInviteToken(ctx.redis, invitationId);
+        const updateResult = await executor.update({
+            id: invitationId,
+            version: existingVersion,
+            changes: {
+                role: request.role,
+                // Always written, also as []: a tenant-admin resend must drop
+                // global roles a previous system invite put on this row.
+                globalRoles: [...request.globalRoles],
+                status: INVITATION_STATUS.pending,
+                invitedBy: inviter.id,
+                expiresAt,
+            },
+        }, inviter, ctx.db);
+        if (!updateResult.isSuccess)
+            return updateResult;
+    }
+    else {
+        const createResult = await executor.create({
+            email,
+            role: request.role,
+            globalRoles: [...request.globalRoles],
+            status: INVITATION_STATUS.pending,
+            invitedBy: inviter.id,
+            expiresAt,
+        }, inviter, ctx.db);
+        if (!createResult.isSuccess)
+            return createResult;
+        invitationId = createResult.data.id; // @cast-boundary engine-payload
+    }
+    const token = generateToken();
+    await storeInviteToken(ctx.redis, { invitationId, token, ttlSeconds });
+    const locale = resolveHandlerMailLocale(ctx, opts.locale);
+    await dispatchMagicLinkMail(ctx.notify, {
+        handlerName: "invite-create",
+        notificationType: INVITE_NOTIFICATION_TYPE,
+        renderContent: (renderArgs) => renderInviteEmail({ ...renderArgs, role: request.role }),
+    }, {
+        email,
+        appUrl: opts.appUrl,
+        token,
+        expiresAt: expiresAt.toString(),
+        ...(opts.appName !== undefined && { appName: opts.appName }),
+        locale,
+    });
+    return {
+        isSuccess: true,
+        data: {
+            kind: "invite-created",
+            invitationId,
+            tenantId,
+            email,
+            role: request.role,
+            globalRoles: request.globalRoles,
+            expiresAt: expiresAt.toString(),
+        },
+    };
+}
+function assertAppDefinedAdditionalRoles(opts) {
     const rankedRole = findRankedRole(opts.additionalAssignableRoles ?? []);
     if (rankedRole !== undefined) {
         throw new Error(`[auth-email-password] invite.additionalAssignableRoles must list app-defined roles only; "${rankedRole}" is a framework-ranked role`);
     }
-    const ttlMinutes = opts.tokenTtlMinutes ?? AUTH_INVITE_DEFAULT_TTL_MINUTES;
-    const ttlSeconds = ttlMinutes * 60;
+}
+export function createInviteCreateHandler(opts) {
+    assertAppDefinedAdditionalRoles(opts);
+    const ttlSeconds = (opts.tokenTtlMinutes ?? AUTH_INVITE_DEFAULT_TTL_MINUTES) * 60;
     return defineWriteHandler({
         name: "invite-create",
         schema: InviteCreateSchema,
         access: { roles: access.admin },
         description: "Invites an email address into the caller's tenant with a chosen membership role, creating or reusing the invitation and mailing the invitee a fresh accept link; re-inviting the same address invalidates the previous link.",
         handler: async (event, ctx) => {
-            if (!ctx.redis) {
-                return writeFailure(new InternalError({ message: "invite-create requires ctx.redis for token store" }));
-            }
-            const forbiddenRole = findForbiddenMembershipRole([event.payload.role]);
-            if (forbiddenRole !== undefined) {
-                return writeFailure(reservedMembershipRoleError(forbiddenRole));
-            }
-            const elevationForbidden = findForbiddenRoleAssignment(event.user.roles, [event.payload.role], [], assignableAppRolesOf(ctx.registry));
-            if (elevationForbidden !== undefined &&
-                !opts.additionalAssignableRoles?.includes(elevationForbidden)) {
-                return writeFailure(unassignableMembershipRoleError(elevationForbidden));
-            }
-            if (opts.canAssignRole && !opts.canAssignRole(event.user.roles, event.payload.role)) {
-                return writeFailure(unassignableMembershipRoleError(event.payload.role));
-            }
-            const email = event.payload.email.toLowerCase();
-            const tenantId = event.user.tenantId;
-            const expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });
-            // Existing row für (tenantId, email) — unique-index garantiert
-            // max. eine Row. Status egal (cancelled/accepted/expired/pending);
-            // wir setzen sie auf pending zurück und vergeben einen frischen
-            // Token wenn der bisherige nicht mehr lebt.
-            const existing = await ctx.db.fetchOne(tenantInvitationsTable, { tenantId, email });
-            let invitationId;
-            let token;
-            if (existing) {
-                invitationId = existing["id"]; // @cast-boundary db-row
-                const existingVersion = existing["version"]; // @cast-boundary db-row
-                // At most one live invite token per invitation: invalidate
-                // whatever's there before minting the new one.
-                await invalidateExistingInviteToken(ctx.redis, invitationId);
-                token = generateToken();
-                const updateResult = await executor.update({
-                    id: invitationId,
-                    version: existingVersion,
-                    changes: {
-                        role: event.payload.role,
-                        status: INVITATION_STATUS.pending,
-                        invitedBy: event.user.id,
-                        expiresAt,
-                    },
-                }, event.user, ctx.db);
-                if (!updateResult.isSuccess)
-                    return updateResult;
-            }
-            else {
-                const createResult = await executor.create({
-                    email,
-                    role: event.payload.role,
-                    status: INVITATION_STATUS.pending,
-                    invitedBy: event.user.id,
-                    expiresAt,
-                }, event.user, ctx.db);
-                if (!createResult.isSuccess)
-                    return createResult;
-                invitationId = createResult.data.id; // @cast-boundary engine-payload
-                token = generateToken();
-            }
-            await storeInviteToken(ctx.redis, { invitationId, token, ttlSeconds });
-            const locale = resolveHandlerMailLocale(ctx, opts.locale);
-            await dispatchMagicLinkMail(ctx.notify, {
-                handlerName: "invite-create",
-                notificationType: INVITE_NOTIFICATION_TYPE,
-                renderContent: (renderArgs) => renderInviteEmail({ ...renderArgs, role: event.payload.role }),
-            }, {
-                email,
-                appUrl: opts.appUrl,
-                token,
-                expiresAt: expiresAt.toString(),
-                ...(opts.appName !== undefined && { appName: opts.appName }),
-                locale,
-            });
-            return {
-                isSuccess: true,
-                data: {
-                    kind: "invite-created",
-                    invitationId,
-                    tenantId,
-                    email,
-                    role: event.payload.role,
-                    expiresAt: expiresAt.toString(),
-                },
-            };
+            const roleRejection = checkAssignableInviteRole(opts, event.user.roles, event.payload.role, ctx);
+            if (roleRejection)
+                return roleRejection;
+            return issueInvitation(opts, ttlSeconds, { email: event.payload.email, role: event.payload.role, globalRoles: [] }, event.user, ctx);
+        },
+    });
+}
+const SystemInviteCreateSchema = z.object({
+    email: z.email(),
+    role: z.string().min(1).max(50),
+    globalRoles: z.array(z.enum(GLOBAL_ROLE_OPTIONS)).max(GLOBAL_ROLE_OPTIONS.length).default([]),
+});
+// System-only sibling of invite-create: the only path that can put global
+// roles (SystemAdmin) on an invitation. No session mint path yields the
+// "system" role (users.roles only accepts GLOBAL_ROLE_OPTIONS), so only
+// in-process callers dispatching as createSystemUser (runBootstrap) get here.
+export function createSystemInviteCreateHandler(opts) {
+    assertAppDefinedAdditionalRoles(opts);
+    const ttlSeconds = (opts.tokenTtlMinutes ?? AUTH_INVITE_DEFAULT_TTL_MINUTES) * 60;
+    return defineWriteHandler({
+        name: "system-invite-create",
+        schema: SystemInviteCreateSchema,
+        access: { roles: access.system },
+        agent: { expose: false },
+        description: "System-only invite into the dispatching tenant that may additionally carry global roles, which the invitee receives only when accepting; used by provisioning such as runBootstrap.",
+        handler: async (event, ctx) => {
+            const roleRejection = checkAssignableInviteRole(opts, event.user.roles, event.payload.role, ctx);
+            if (roleRejection)
+                return roleRejection;
+            return issueInvitation(opts, ttlSeconds, event.payload, event.user, ctx, true);
         },
     });
 }