// VA-P23 ยท shared loader/action guard for the email-inbox module (mirrors // calendarAccess). The MODULE gate is the plan-gated `email-inbox` feature // (tenantHasModule). Visibility (M09 Block I): `email.read_own` sees only // mailboxes with ownerUserId = self, `email.read_all` sees every tenant mailbox, // `email.write` composes/sends over the own mailbox. Module-off renders a locked // empty VM on GET and 404s on write (Bauprinzip A.5.3); a permission miss is // also a 404, never a 403. import { CatalogError, foundationErrors } from "@hivegrid/foundation"; import { requireAuth } from "~/utils/loaders.middleware"; import { getTenantIdFromUrl } from "~/utils/services/.server/urlService"; import { getUserInfo } from "~/utils/session.server"; import { tenantHasModule } from "~/utils/connector/tenantConnector.server"; import { getPermissionsByUser } from "~/utils/db/permissions/userRoles.db.server"; import { EMAIL_INBOX_MODULE_KEY } from "./emailInboxRoutePaths"; /** Email-inbox atomic permissions (M09 Block I). */ export const EMAIL_PERMISSIONS = { /** See mails of the user's OWN connected mailboxes (default tenant-user capability). */ readOwn: "email.read_own", /** See every tenant mailbox's mails (tenant administration). */ readAll: "email.read_all", /** Compose/send over the user's own connected mailbox. */ write: "email.write", } as const; export type EmailInboxRouteContext = { tenantId: string; userId: string; permissions: readonly string[]; hasModule: boolean; }; /** * Resolve the email-inbox route context: auth + tenant + the email-inbox module * gate + the user's permissions. With `requireModule` a module-off tenant 404s * (write paths); GET paths can render a locked empty VM from `hasModule === false`. */ export async function loadEmailInboxContext({ request, params, requireModule = false, }: { request: Request; params: Record; requireModule?: boolean; }): Promise { await requireAuth({ request, params }); const [tenantId, userInfo] = await Promise.all([getTenantIdFromUrl(params), getUserInfo(request)]); if (!tenantId || !userInfo.userId) { throw new CatalogError(foundationErrors.notFound); } const [hasModule, permissions] = await Promise.all([ tenantHasModule({ tenantId, userId: userInfo.userId, moduleKey: EMAIL_INBOX_MODULE_KEY }), getPermissionsByUser(userInfo.userId, tenantId), ]); if (requireModule && !hasModule) { throw new CatalogError(foundationErrors.notFound, { module: EMAIL_INBOX_MODULE_KEY }); } return { tenantId, userId: userInfo.userId, permissions, hasModule }; } /** True when the user may see EVERY tenant mailbox (read_all bundle). */ export function canReadAllMailboxes(ctx: EmailInboxRouteContext): boolean { return ctx.permissions.includes(EMAIL_PERMISSIONS.readAll); } /** True when the user may see at least their own mailboxes. */ export function canReadOwnMailboxes(ctx: EmailInboxRouteContext): boolean { return ctx.permissions.includes(EMAIL_PERMISSIONS.readOwn) || canReadAllMailboxes(ctx); } /** True when the user may compose/send over their own mailbox. */ export function canWriteEmail(ctx: EmailInboxRouteContext): boolean { return ctx.permissions.includes(EMAIL_PERMISSIONS.write); } /** Require any read capability; 404 if missing (A.5.3). */ export function requireEmailRead(ctx: EmailInboxRouteContext): EmailInboxRouteContext { if (!canReadOwnMailboxes(ctx)) { throw new CatalogError(foundationErrors.notFound, { permission: EMAIL_PERMISSIONS.readOwn }); } return ctx; } /** Require the write capability; 404 if missing (A.5.3). */ export function requireEmailWrite(ctx: EmailInboxRouteContext): EmailInboxRouteContext { if (!canWriteEmail(ctx)) { throw new CatalogError(foundationErrors.notFound, { permission: EMAIL_PERMISSIONS.write }); } return ctx; } /** * Owner-check for mailbox-scoped resources (M09 Block I): with only read_own the * caller must own the mailbox; read_all lifts the restriction. Miss = 404. */ export function requireMailboxVisibility(ctx: EmailInboxRouteContext, mailboxOwnerUserId: string): EmailInboxRouteContext { if (ctx.userId === mailboxOwnerUserId || canReadAllMailboxes(ctx)) { return ctx; } throw new CatalogError(foundationErrors.notFound, { owner: "mismatch" }); }