Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -0,0 +1,121 @@
// VA-P23 · attachment import (M09: "Anhänge landen in v1-Files", DoD 5).
//
// Attachments are imported LAZILY on user action (not eagerly during sync —
// Gmail base64 bodies are expensive and Graph >3 MB needs a $value stream):
// adapter download → private bucket via putBufferAsFile → `File` row (source
// `email_attachment`) + polymorphic FileEntityLink (entityType `email_message`).
// Delivery then runs through the normal Files auth-proxy. v1 size cap: 15 MB.
import { randomUUID } from "node:crypto";
import { buildFileStorageKeys } from "@hivegrid/storage";
import { putBufferAsFile, resolveStorageBucket } from "~/utils/integrations/storageService";
import { withTenantRLS } from "~/utils/db/.server/tenantRls.server";
import { adapterForProvider, ensureFreshMailboxCreds, loadMailboxCreds } from "./MailboxConnectionService.server";
import type { EmailOAuthProvider } from "./oauthState.server";
export const EMAIL_ATTACHMENT_MAX_BYTES = 15 * 1024 * 1024;
export class EmailAttachmentError extends Error {
readonly code: "not_found" | "too_large" | "not_connected" | "provider_failed";
constructor(code: EmailAttachmentError["code"]) {
super(code);
this.name = "EmailAttachmentError";
this.code = code;
}
}
/** Provider-side attachment metadata for the detail view. */
export async function listProviderAttachments(input: {
tenantId: string;
mailboxId: string;
provider: EmailOAuthProvider;
providerMessageId: string;
}): Promise<Array<{ attachmentId: string; filename: string; mimeType: string | null; sizeBytes: number }>> {
const creds = await loadMailboxCreds(input.tenantId, input.mailboxId);
if (!creds) {
return [];
}
try {
const fresh = await ensureFreshMailboxCreds(input.tenantId, input.mailboxId, input.provider, creds);
return await adapterForProvider(input.provider).listAttachments(fresh, input.providerMessageId);
} catch {
return [];
}
}
/**
* Import ONE provider attachment into v1-Files and link it to the message.
* Idempotence: linkRole carries the provider attachment id — an existing link
* short-circuits to the already-imported file.
*/
export async function importAttachmentToFiles(input: {
tenantId: string;
userId: string;
mailboxId: string;
provider: EmailOAuthProvider;
messageId: string;
providerMessageId: string;
attachmentId: string;
}): Promise<{ fileId: string }> {
const existing = await withTenantRLS(input.tenantId, async (tx) => {
return tx.fileEntityLink.findFirst({
where: { tenantId: input.tenantId, entityType: "email_message", entityId: input.messageId, linkRole: `attachment:${input.attachmentId}` },
select: { fileId: true },
});
});
if (existing) {
return { fileId: existing.fileId };
}
const creds = await loadMailboxCreds(input.tenantId, input.mailboxId);
if (!creds) {
throw new EmailAttachmentError("not_connected");
}
const fresh = await ensureFreshMailboxCreds(input.tenantId, input.mailboxId, input.provider, creds);
const attachment = await adapterForProvider(input.provider)
.downloadAttachment(fresh, input.providerMessageId, input.attachmentId)
.catch(() => null);
if (!attachment) {
throw new EmailAttachmentError("not_found");
}
const body = Buffer.from(attachment.contentBase64, "base64");
if (body.byteLength > EMAIL_ATTACHMENT_MAX_BYTES) {
throw new EmailAttachmentError("too_large");
}
const fileId = `file_${randomUUID()}`;
const { original: storageKey } = buildFileStorageKeys(input.tenantId, fileId);
await putBufferAsFile({
bucket: resolveStorageBucket(),
key: storageKey,
body,
contentType: attachment.mimeType ?? "application/octet-stream",
});
await withTenantRLS(input.tenantId, async (tx) => {
await tx.file.create({
data: {
id: fileId,
tenantId: input.tenantId,
createdByUserId: input.userId,
displayName: attachment.filename.slice(0, 255),
mimeType: attachment.mimeType ?? "application/octet-stream",
sizeBytes: body.byteLength,
storageKey,
source: "email_attachment",
scanStatus: "pending",
previewStatus: "pending",
},
});
await tx.fileEntityLink.create({
data: {
tenantId: input.tenantId,
createdByUserId: input.userId,
fileId,
entityType: "email_message",
entityId: input.messageId,
linkRole: `attachment:${input.attachmentId}`,
},
});
});
return { fileId };
}
@@ -0,0 +1,173 @@
// VA-P23 · outbound send over the user's OWN mailbox (M09 Block G, DoD 4c).
//
// The send path goes through the provider adapter (Gmail messages.send with
// threadId + In-Reply-To/References; Graph sendMail → 202 without an id). After
// a successful send the message is mirrored locally as direction=outbound —
// for Graph the sent-items delta later collapses onto this mirror via
// internetMessageId. Provider errors surface as Klartext codes (M002).
import { randomUUID } from "node:crypto";
import { GmailError, GraphMailError, type MappedEmailMessage } from "@hivegrid/integrations";
import { logActivity } from "@hivegrid/activity";
import { db } from "~/utils/db.server";
import { adapterForProvider, ensureFreshMailboxCreds, loadMailboxCreds } from "./MailboxConnectionService.server";
import type { EmailOAuthProvider } from "./oauthState.server";
import type { NeutralAddress } from "./adapters/EmailProviderAdapter";
export class EmailSendError extends Error {
readonly code: "no_mailbox" | "not_connected" | "quota_exceeded" | "token_expired" | "provider_failed" | "no_recipients";
constructor(code: EmailSendError["code"]) {
super(code);
this.name = "EmailSendError";
this.code = code;
}
}
export interface SendEmailInput {
tenantId: string;
userId: string;
mailboxId: string;
to: readonly NeutralAddress[];
cc?: readonly NeutralAddress[];
bcc?: readonly NeutralAddress[];
subject: string;
bodyHtml: string;
/** Reply context: the mirrored message being answered (threading headers). */
replyToMessageId?: string | null;
attachments?: ReadonlyArray<{ filename: string; mimeType: string; contentBase64: string }>;
}
function mapProviderError(error: unknown): EmailSendError {
if (error instanceof GmailError) {
if (error.code === "quota_exceeded" || (error.code === "auth_scope_missing" && error.httpStatus === 403)) {
return new EmailSendError("quota_exceeded");
}
if (error.code === "auth_token_expired") {
return new EmailSendError("token_expired");
}
}
if (error instanceof GraphMailError && error.code === "auth_token_expired") {
return new EmailSendError("token_expired");
}
return new EmailSendError("provider_failed");
}
/** Send + mirror. Returns the local mirror message id (detail redirect). */
export async function sendEmail(input: SendEmailInput): Promise<{ messageId: string }> {
if (input.to.length === 0) {
throw new EmailSendError("no_recipients");
}
const mailbox = await db.emailIntegrationMailbox.findFirst({
where: { id: input.mailboxId, tenantId: input.tenantId, ownerUserId: input.userId, archivedAt: null, status: { in: ["active", "connecting", "error"] } },
select: { id: true, provider: true, emailAddress: true, displayName: true },
});
if (!mailbox) {
throw new EmailSendError("no_mailbox");
}
const provider = mailbox.provider as EmailOAuthProvider;
const creds = await loadMailboxCreds(input.tenantId, input.mailboxId);
if (!creds) {
throw new EmailSendError("not_connected");
}
// Reply threading context from the mirrored original (M09 Block G).
const replyTo = input.replyToMessageId
? await db.emailIntegrationMessage.findFirst({
where: { id: input.replyToMessageId, tenantId: input.tenantId },
select: { providerThreadId: true, internetMessageId: true },
})
: null;
let result: { providerMessageId: string | null; providerThreadId: string | null };
try {
const fresh = await ensureFreshMailboxCreds(input.tenantId, input.mailboxId, provider, creds);
result = await adapterForProvider(provider).sendMessage(fresh, {
to: input.to,
cc: input.cc,
bcc: input.bcc,
subject: input.subject,
bodyHtml: input.bodyHtml,
attachments: input.attachments,
providerThreadId: replyTo?.providerThreadId ?? null,
inReplyToInternetMessageId: replyTo?.internetMessageId ?? null,
referencesInternetMessageIds: replyTo?.internetMessageId ? [replyTo.internetMessageId] : undefined,
});
} catch (error) {
throw mapProviderError(error);
}
// Local outbound mirror. Graph returns no id (202) → provisional local id;
// the sent-items delta adopts the provider ids via internetMessageId later.
const now = new Date();
const mirror = await db.emailIntegrationMessage.create({
data: {
tenantId: input.tenantId,
mailboxId: input.mailboxId,
providerMessageId: result.providerMessageId ?? `local_${randomUUID()}`,
providerThreadId: result.providerThreadId ?? replyTo?.providerThreadId ?? null,
internetMessageId: null,
direction: "outbound",
fromAddress: mailbox.emailAddress,
fromName: mailbox.displayName,
toAddresses: input.to as never,
ccAddresses: (input.cc ?? []) as never,
bccAddresses: (input.bcc ?? []) as never,
subject: input.subject,
snippet: input.bodyHtml.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim().slice(0, 140),
bodyHtml: input.bodyHtml,
sentAt: now,
isRead: true,
hasAttachments: (input.attachments?.length ?? 0) > 0,
},
select: { id: true },
});
// Activity at the reply-context entities (auto-match hook covers synced
// inbound mail; the outbound mirror logs directly, actor = the sender).
if (input.replyToMessageId) {
const original = await db.emailIntegrationMessage.findFirst({
where: { id: input.replyToMessageId, tenantId: input.tenantId },
select: { matchedKontaktId: true, matchedLeadId: true, matchedProjektId: true },
});
const subject = original?.matchedKontaktId
? { subjectType: "contact" as const, subjectId: original.matchedKontaktId }
: original?.matchedLeadId
? { subjectType: "lead" as const, subjectId: original.matchedLeadId }
: original?.matchedProjektId
? { subjectType: "project" as const, subjectId: original.matchedProjektId }
: null;
if (subject) {
// The reply inherits the original's match so it shows on the same timeline.
await db.emailIntegrationMessage.update({
where: { id: mirror.id },
data: {
matchedKontaktId: original?.matchedKontaktId ?? null,
matchedLeadId: original?.matchedLeadId ?? null,
matchedProjektId: original?.matchedProjektId ?? null,
matchConfidence: "high",
},
});
await logActivity({
tenantId: input.tenantId,
actorUserId: input.userId,
actorKind: "user",
activityType: "email_sent",
subjectType: subject.subjectType,
subjectId: subject.subjectId,
summaryText: `Ausgehende E-Mail an ${input.to[0]?.name ?? input.to[0]?.address}: ${input.subject.trim() ? `„${input.subject.trim()}“` : "(ohne Betreff)"}`,
metadata: { emailMessageId: mirror.id, mailboxId: input.mailboxId },
}).catch(() => undefined);
}
}
return { messageId: mirror.id };
}
/** Active templates for the compose dropdown (M098 — v1-EmailTemplate reuse). */
export async function listEmailTemplates(tenantId: string): Promise<Array<{ id: string; name: string; subject: string; htmlBody: string }>> {
return db.emailTemplate.findMany({
where: { tenantId, archivedAt: null },
select: { id: true, name: true, subject: true, htmlBody: true },
orderBy: [{ isDefault: "desc" }, { name: "asc" }],
});
}
@@ -0,0 +1,283 @@
// VA-P23 · mailbox connection lifecycle (connect / callback / disconnect).
//
// OAuth tokens are sealed with the per-tenant DEK envelope (AD-8) — never stored
// plain, never logged (DoD 7). Writes are audited automatically by the M001
// Prisma middleware. Webhook subscription is best-effort: a failure degrades the
// mailbox with a Klartext hint, it does not block the connect (mirrors
// CalendarConnectionService). Disconnect revokes provider-side (Gmail token
// revoke + watch stop; Graph subscription delete — Graph has no delegated-token
// revoke, documented in graphMailApi) and nulls the ciphertexts.
import { randomBytes } from "node:crypto";
import { decryptTenantField, encryptTenantField } from "@hivegrid/db/crypto/tenant-envelope.server";
import { GMAIL_GLOBAL_FOLDER, GRAPH_SYNC_FOLDERS } from "./adapters/EmailProviderAdapter";
import type { EmailCreds, EmailProviderAdapter } from "./adapters/EmailProviderAdapter";
import { gmailProviderAdapter } from "./adapters/GmailAdapter.server";
import { microsoftMailProviderAdapter } from "./adapters/MicrosoftMailAdapter.server";
import { EmailInboxNotConfiguredError } from "./adapters/GmailAdapter.server";
import { signEmailOAuthState, verifyEmailOAuthState, type EmailOAuthProvider } from "./oauthState.server";
import { db } from "~/utils/db.server";
export class MailboxConnectError extends Error {
readonly code: "not_configured" | "invalid_state" | "exchange_failed";
constructor(code: MailboxConnectError["code"]) {
super(code);
this.name = "MailboxConnectError";
this.code = code;
}
}
export function adapterForProvider(provider: EmailOAuthProvider): EmailProviderAdapter {
return provider === "gmail" ? gmailProviderAdapter : microsoftMailProviderAdapter;
}
function webhookUrlForProvider(provider: EmailOAuthProvider): string | null {
return (provider === "gmail" ? process.env.GOOGLE_GMAIL_WEBHOOK_URL : process.env.MICROSOFT_MAIL_WEBHOOK_URL) ?? null;
}
/** Which providers are configured (drives the connect buttons' enabled state). */
export function configuredEmailProviders(): { gmail: boolean; microsoft: boolean } {
return { gmail: gmailProviderAdapter.isConfigured(), microsoft: microsoftMailProviderAdapter.isConfigured() };
}
/** Build the provider consent URL for the current tenant user. */
export function buildConnectUrl(input: { tenantId: string; userId: string; tenantSlug: string; provider: EmailOAuthProvider }): string {
const adapter = adapterForProvider(input.provider);
if (!adapter.isConfigured()) {
throw new MailboxConnectError("not_configured");
}
const state = signEmailOAuthState(input);
return adapter.buildAuthorizationUrl(state);
}
/**
* Complete an OAuth callback: verify state (provider-pinned), exchange the code,
* seal the tokens, upsert the per-user mailbox, and best-effort subscribe the
* push channel. Returns the tenant slug + ids so the callback route can kick the
* initial sync (kept out of this service to avoid a sync-service import cycle).
*/
export async function completeOAuthCallback(input: {
code: string;
state: string;
provider: EmailOAuthProvider;
}): Promise<{ tenantSlug: string; tenantId: string; mailboxId: string }> {
const verified = verifyEmailOAuthState(input.state, input.provider);
if (!verified.ok) {
throw new MailboxConnectError("invalid_state");
}
const { tenantId, userId, tenantSlug } = verified.payload;
const adapter = adapterForProvider(input.provider);
let exchange: Awaited<ReturnType<EmailProviderAdapter["exchangeCode"]>>;
try {
exchange = await adapter.exchangeCode(input.code);
} catch (error) {
if (error instanceof EmailInboxNotConfiguredError) {
throw new MailboxConnectError("not_configured");
}
throw new MailboxConnectError("exchange_failed");
}
const { tokens, account } = exchange;
// Seal refresh + access tokens separately (AD-8, DoD 7). A refresh token is
// only guaranteed on first consent; keep an existing one when omitted.
const refreshCiphertext = tokens.refreshToken ? await encryptTenantField(tenantId, tokens.refreshToken) : null;
const accessCiphertext = await encryptTenantField(tenantId, tokens.accessToken);
const provider = input.provider;
const emailAddress = account.email.toLowerCase();
const existingForUser = await db.emailIntegrationMailbox.count({ where: { tenantId, ownerUserId: userId, archivedAt: null } });
const mailbox = await db.emailIntegrationMailbox.upsert({
where: {
tenantId_ownerUserId_provider_externalAccountId: { tenantId, ownerUserId: userId, provider, externalAccountId: account.accountId },
},
create: {
tenantId,
ownerUserId: userId,
provider,
emailAddress,
externalAccountId: account.accountId,
displayName: account.displayName ?? null,
oauthRefreshTokenCiphertext: refreshCiphertext,
oauthAccessTokenCiphertext: accessCiphertext,
oauthAccessTokenExpiresAt: tokens.expiresAt,
oauthScopes: [...tokens.scopes],
isDefaultForUser: existingForUser === 0,
status: "connecting",
},
update: {
emailAddress,
displayName: account.displayName ?? null,
// Preserve the stored refresh token when the provider omits it on re-consent.
...(refreshCiphertext ? { oauthRefreshTokenCiphertext: refreshCiphertext } : {}),
oauthAccessTokenCiphertext: accessCiphertext,
oauthAccessTokenExpiresAt: tokens.expiresAt,
oauthScopes: [...tokens.scopes],
status: "connecting",
lastErrorText: null,
archivedAt: null,
},
select: { id: true },
});
await trySubscribeWebhook({
tenantId,
mailboxId: mailbox.id,
provider,
creds: { accessToken: tokens.accessToken, refreshToken: tokens.refreshToken ?? "" },
});
await ensureSyncCursors(tenantId, mailbox.id, provider);
await db.emailIntegrationMailbox.update({ where: { id: mailbox.id }, data: { status: "active" } });
return { tenantSlug, tenantId, mailboxId: mailbox.id };
}
/**
* Best-effort push subscription. Gmail: users.watch on the shared Pub/Sub topic
* (the mailbox address routes the push, historyId anchors the cursor). Graph:
* /subscriptions with a per-mailbox random clientState (its only auth). Absent
* env or a provider failure degrades with a Klartext hint instead of failing.
*/
async function trySubscribeWebhook(input: {
tenantId: string;
mailboxId: string;
provider: EmailOAuthProvider;
creds: EmailCreds;
}): Promise<void> {
const webhookUrl = webhookUrlForProvider(input.provider);
if (input.provider === "microsoft" && !webhookUrl) {
return;
}
const adapter = adapterForProvider(input.provider);
const clientState = randomBytes(24).toString("base64url");
try {
const subscription = await adapter.subscribeWebhook(input.creds, webhookUrl ?? "", clientState);
await db.emailIntegrationMailbox.update({
where: { id: input.mailboxId },
data: {
webhookSubscriptionId: subscription.subscriptionId,
webhookSubscriptionExpiresAt: subscription.expiresAt,
webhookClientState: clientState,
},
});
// Gmail delivers the current historyId on watch — anchor the global cursor
// so the incremental drain starts at "now" (the initial sync backfills).
if (input.provider === "gmail" && subscription.initialCursor) {
await db.emailIntegrationSyncCursor.upsert({
where: { mailboxId_externalFolderId: { mailboxId: input.mailboxId, externalFolderId: GMAIL_GLOBAL_FOLDER } },
create: {
tenantId: input.tenantId,
mailboxId: input.mailboxId,
externalFolderId: GMAIL_GLOBAL_FOLDER,
cursorToken: subscription.initialCursor,
},
update: { cursorToken: subscription.initialCursor },
});
}
} catch {
await db.emailIntegrationMailbox.update({
where: { id: input.mailboxId },
data: { lastErrorText: "emailInbox.health.webhookSubscriptionFailed" },
});
}
}
/** Ensure the per-folder sync cursor rows exist (initial sync = pending). */
async function ensureSyncCursors(tenantId: string, mailboxId: string, provider: EmailOAuthProvider): Promise<void> {
const folders = provider === "gmail" ? [GMAIL_GLOBAL_FOLDER] : [...GRAPH_SYNC_FOLDERS];
for (const externalFolderId of folders) {
await db.emailIntegrationSyncCursor.upsert({
where: { mailboxId_externalFolderId: { mailboxId, externalFolderId } },
create: { tenantId, mailboxId, externalFolderId, initialSyncStatus: "pending" },
update: {},
});
}
}
/** Decrypt a mailbox's sealed tokens into adapter creds (server-only). */
export async function loadMailboxCreds(tenantId: string, mailboxId: string): Promise<EmailCreds | null> {
const row = await db.emailIntegrationMailbox.findFirst({
where: { id: mailboxId, tenantId },
select: { oauthRefreshTokenCiphertext: true, oauthAccessTokenCiphertext: true, oauthAccessTokenExpiresAt: true },
});
if (!row?.oauthRefreshTokenCiphertext || !row.oauthAccessTokenCiphertext) {
return null;
}
const [refreshToken, accessToken] = await Promise.all([
decryptTenantField(tenantId, row.oauthRefreshTokenCiphertext),
decryptTenantField(tenantId, row.oauthAccessTokenCiphertext),
]);
return { refreshToken, accessToken, expiresAt: row.oauthAccessTokenExpiresAt };
}
/**
* Refresh a mailbox's access token when it expires within `windowMs`, sealing
* the rotated tokens (Graph rotates the refresh token too). Returns fresh creds.
*/
export async function ensureFreshMailboxCreds(
tenantId: string,
mailboxId: string,
provider: EmailOAuthProvider,
creds: EmailCreds,
opts: { now?: Date; windowMs?: number } = {},
): Promise<EmailCreds> {
const now = opts.now ?? new Date();
if (creds.expiresAt && creds.expiresAt.getTime() > now.getTime() + (opts.windowMs ?? 60_000)) {
return creds;
}
const adapter = adapterForProvider(provider);
const refreshed = await adapter.refreshTokens(creds.refreshToken);
const nextRefreshToken = refreshed.refreshToken ?? creds.refreshToken;
const [accessCiphertext, refreshCiphertext] = await Promise.all([
encryptTenantField(tenantId, refreshed.accessToken),
encryptTenantField(tenantId, nextRefreshToken),
]);
await db.emailIntegrationMailbox.update({
where: { id: mailboxId },
data: {
oauthAccessTokenCiphertext: accessCiphertext,
oauthRefreshTokenCiphertext: refreshCiphertext,
oauthAccessTokenExpiresAt: refreshed.expiresAt,
lastErrorText: null,
},
});
return { accessToken: refreshed.accessToken, refreshToken: nextRefreshToken, expiresAt: refreshed.expiresAt };
}
/**
* Disconnect a mailbox (owner or read_all admin — enforced by the route).
* Best-effort provider revoke (Gmail: watch stop + token revoke; Graph:
* subscription delete), then local soft-revoke: status revoked, soft-delete,
* ciphertexts nulled (defense-in-depth). Mirrored messages stay in the CRM
* (M09 Block B disconnect Klartext).
*/
export async function disconnectMailbox(input: { tenantId: string; mailboxId: string }): Promise<void> {
const row = await db.emailIntegrationMailbox.findFirst({
where: { id: input.mailboxId, tenantId: input.tenantId, archivedAt: null },
select: { id: true, provider: true, webhookSubscriptionId: true },
});
if (!row) {
return;
}
const provider = row.provider as EmailOAuthProvider;
const adapter = adapterForProvider(provider);
const creds = await loadMailboxCreds(input.tenantId, input.mailboxId);
if (creds) {
if (row.webhookSubscriptionId) {
await adapter.revokeWebhook(creds, row.webhookSubscriptionId).catch(() => undefined);
}
await adapter.revokeTokens(creds).catch(() => undefined);
}
await db.emailIntegrationMailbox.update({
where: { id: row.id },
data: {
status: "revoked",
archivedAt: new Date(),
oauthRefreshTokenCiphertext: null,
oauthAccessTokenCiphertext: null,
webhookSubscriptionId: null,
webhookClientState: null,
},
});
}
@@ -0,0 +1,130 @@
// VA-P23 · provider-agnostic EmailProviderAdapter contract (M09 Block J).
//
// Two implementations ship in v2: GmailAdapter.server.ts and
// MicrosoftMailAdapter.server.ts. The adapter is a thin PROVIDER BOUNDARY:
// given decrypted creds it performs one network op and returns provider-neutral
// data. The per-user orchestration (cursor persistence, message upserts,
// auto-match, activity) lives in the sync services/worker tasks, not here.
//
// Neutral types deliberately avoid provider naming so both providers (and later
// ones) map into the same domain shapes.
import type { MappedEmailAddress, MappedEmailMessage } from "@hivegrid/integrations";
/** A mailbox's decrypted OAuth credentials (the engine handles envelope crypto). */
export interface EmailCreds {
readonly accessToken: string;
readonly refreshToken: string;
readonly expiresAt?: Date | null;
}
export interface EmailTokens {
readonly accessToken: string;
/** Present on the initial code exchange (Graph also rotates it on refresh). */
readonly refreshToken?: string;
readonly expiresAt: Date;
readonly scopes: readonly string[];
}
export interface EmailAccount {
readonly email: string;
readonly accountId: string;
readonly displayName?: string;
}
// The neutral message/address shapes are SHARED with the worker sync tasks and
// live in @hivegrid/integrations (email-message-mapping.ts) — one mapping, no
// drift between connect-time and cron-time sync.
export type NeutralAddress = MappedEmailAddress;
export type NeutralMessage = MappedEmailMessage;
export interface NeutralAttachmentMeta {
readonly attachmentId: string;
readonly filename: string;
readonly mimeType: string | null;
readonly sizeBytes: number;
}
export interface NeutralAttachmentContent extends NeutralAttachmentMeta {
/** Standard base64 (not base64url) so it can stream into storage directly. */
readonly contentBase64: string;
}
/** One page of the incremental (or initial) pull. */
export interface MailDeltaResult {
readonly messages: readonly NeutralMessage[];
/** Persist as the folder cursor when present (page set complete). */
readonly nextCursor?: string;
/** Continue paging within the same drain when present. */
readonly nextPageToken?: string;
/** True when the provider expired the cursor → bounded full resync. */
readonly fullResyncRequired?: boolean;
}
export interface MailWebhookSubscription {
readonly subscriptionId: string;
readonly expiresAt: Date | null;
/** Provider anchor delivered on subscribe (Gmail historyId); null for Graph. */
readonly initialCursor: string | null;
}
export interface SendMailInput {
readonly to: readonly NeutralAddress[];
readonly cc?: readonly NeutralAddress[];
readonly bcc?: readonly NeutralAddress[];
readonly subject: string;
readonly bodyHtml: string;
readonly bodyText?: string;
readonly attachments?: ReadonlyArray<{ filename: string; mimeType: string; contentBase64: string }>;
/** Reply threading: provider thread + the message-id being answered. */
readonly providerThreadId?: string | null;
readonly inReplyToInternetMessageId?: string | null;
readonly referencesInternetMessageIds?: readonly string[];
}
export interface SendMailResult {
/** Graph sendMail returns 202 without an id → null (sent-items delta dedupes). */
readonly providerMessageId: string | null;
readonly providerThreadId: string | null;
}
/**
* Folder identifiers a sync cursor is keyed by. Gmail history is mailbox-global
* → the single pseudo-folder "*"; Graph delta is per real folder.
*/
export const GMAIL_GLOBAL_FOLDER = "*";
export const GRAPH_SYNC_FOLDERS = ["inbox", "sentitems"] as const;
export interface EmailProviderAdapter {
readonly provider: "gmail" | "microsoft";
/** True only when the provider OAuth config is present (env). */
isConfigured(): boolean;
buildAuthorizationUrl(state: string): string;
exchangeCode(code: string): Promise<{ tokens: EmailTokens; account: EmailAccount }>;
refreshTokens(refreshToken: string): Promise<EmailTokens>;
/**
* Subscribe the mailbox to push notifications. `notificationUrl` is the public
* webhook endpoint; `clientState` the per-mailbox verification secret.
*/
subscribeWebhook(creds: EmailCreds, notificationUrl: string, clientState: string): Promise<MailWebhookSubscription>;
/** Renew an expiring subscription (Graph PATCH; Gmail re-issues the watch). */
renewWebhook(creds: EmailCreds, subscriptionId: string, notificationUrl: string, clientState: string): Promise<MailWebhookSubscription>;
revokeWebhook(creds: EmailCreds, subscriptionId: string): Promise<void>;
/** Best-effort provider-side token revoke (Graph has none → no-op). */
revokeTokens(creds: EmailCreds): Promise<void>;
/**
* Pull messages for one folder. `cursor` is the stored incremental cursor
* (Gmail historyId / Graph deltaLink); absent → bounded initial pull from
* `initialSince`. `pageToken` continues a multi-page drain.
*/
fetchMessages(
creds: EmailCreds,
folderId: string,
opts: { cursor?: string | null; pageToken?: string | null; initialSince?: Date },
): Promise<MailDeltaResult>;
getMessage(creds: EmailCreds, providerMessageId: string): Promise<NeutralMessage | null>;
sendMessage(creds: EmailCreds, input: SendMailInput): Promise<SendMailResult>;
markRead(creds: EmailCreds, providerMessageId: string, isRead: boolean): Promise<void>;
listAttachments(creds: EmailCreds, providerMessageId: string): Promise<NeutralAttachmentMeta[]>;
downloadAttachment(creds: EmailCreds, providerMessageId: string, attachmentId: string): Promise<NeutralAttachmentContent | null>;
}
@@ -0,0 +1,209 @@
// VA-P23 · Gmail implementation of the provider-agnostic EmailProviderAdapter.
//
// Maps the neutral domain shapes to/from the shared @hivegrid/integrations Gmail
// REST client. No Prisma here — the adapter only does network I/O against Google
// and provider↔neutral mapping. Token storage/crypto + orchestration live in the
// connection/sync services (mirrors GoogleCalendarAdapter.server.ts).
import {
GmailError,
buildGmailAuthorizationUrl,
buildRfc2822Message,
exchangeGmailCodeForTokens,
fetchGmailUserInfo,
getAttachment,
getMessage,
listHistory,
listMessageIds,
mapGmailMessage,
modifyMessageLabels,
refreshGmailAccessToken,
resolveGmailOAuthConfig,
revokeGmailToken,
sendRawMessage,
stopWatchMailbox,
toBase64Url,
watchMailbox,
type GmailOAuthConfig,
} from "@hivegrid/integrations";
import {
GMAIL_GLOBAL_FOLDER,
type EmailAccount,
type EmailCreds,
type EmailProviderAdapter,
type EmailTokens,
type MailDeltaResult,
type MailWebhookSubscription,
type NeutralAttachmentContent,
type NeutralAttachmentMeta,
type NeutralMessage,
type SendMailInput,
type SendMailResult,
} from "./EmailProviderAdapter";
/** Thrown when the OAuth config (VEXT-5 env) is absent — surfaced as Klartext. */
export class EmailInboxNotConfiguredError extends Error {
constructor(provider: string) {
super(`email_inbox_not_configured:${provider}`);
this.name = "EmailInboxNotConfiguredError";
}
}
function requireConfig(): GmailOAuthConfig {
const config = resolveGmailOAuthConfig();
if (!config) {
throw new EmailInboxNotConfiguredError("gmail");
}
return config;
}
/** Initial-sync query: bounded window, no spam/trash (M09 Block D). */
function initialSyncQuery(initialSince: Date | undefined): string {
const days = initialSince ? Math.max(1, Math.ceil((Date.now() - initialSince.getTime()) / 86_400_000)) : 90;
return `newer_than:${days}d -in:spam -in:trash`;
}
async function fetchMapped(accessToken: string, messageIds: readonly string[]): Promise<NeutralMessage[]> {
const messages: NeutralMessage[] = [];
for (const id of messageIds) {
try {
const raw = await getMessage(accessToken, id, "full");
messages.push(mapGmailMessage(raw));
} catch (error) {
// A message deleted between listing and fetching is not an error.
if (error instanceof GmailError && error.code === "message_not_found") {
continue;
}
throw error;
}
}
return messages;
}
export const gmailProviderAdapter: EmailProviderAdapter = {
provider: "gmail",
isConfigured(): boolean {
return resolveGmailOAuthConfig() !== null;
},
buildAuthorizationUrl(state: string): string {
return buildGmailAuthorizationUrl(requireConfig(), state);
},
async exchangeCode(code: string): Promise<{ tokens: EmailTokens; account: EmailAccount }> {
const config = requireConfig();
const tokenSet = await exchangeGmailCodeForTokens(config, code);
const info = await fetchGmailUserInfo(tokenSet.accessToken);
return {
tokens: { accessToken: tokenSet.accessToken, refreshToken: tokenSet.refreshToken, expiresAt: tokenSet.expiresAt, scopes: tokenSet.scopes },
account: { email: info.email, accountId: info.sub },
};
},
async refreshTokens(refreshToken: string): Promise<EmailTokens> {
const set = await refreshGmailAccessToken(requireConfig(), refreshToken);
return { accessToken: set.accessToken, refreshToken: set.refreshToken, expiresAt: set.expiresAt, scopes: set.scopes };
},
async subscribeWebhook(creds: EmailCreds): Promise<MailWebhookSubscription> {
const config = requireConfig();
const watch = await watchMailbox(creds.accessToken, config.pubsubTopic);
// Gmail has no per-watch id; the mailbox address routes the push. We anchor
// the incremental sync at the watch's historyId.
return { subscriptionId: `gmail-watch`, expiresAt: watch.expiresAt, initialCursor: watch.historyId || null };
},
async renewWebhook(creds: EmailCreds): Promise<MailWebhookSubscription> {
// Gmail renewal = re-issue users.watch (watches expire after ~7 days).
return this.subscribeWebhook(creds, "", "");
},
async revokeWebhook(creds: EmailCreds): Promise<void> {
await stopWatchMailbox(creds.accessToken);
},
async revokeTokens(creds: EmailCreds): Promise<void> {
await revokeGmailToken(creds.refreshToken || creds.accessToken);
},
async fetchMessages(
creds: EmailCreds,
_folderId: string,
opts: { cursor?: string | null; pageToken?: string | null; initialSince?: Date },
): Promise<MailDeltaResult> {
// Incremental: history since the stored historyId cursor.
if (opts.cursor) {
try {
const page = await listHistory(creds.accessToken, opts.cursor, opts.pageToken ?? undefined);
const messages = await fetchMapped(creds.accessToken, page.addedMessageIds);
return { messages, nextCursor: page.historyId, nextPageToken: page.nextPageToken };
} catch (error) {
if (error instanceof GmailError && error.fullResyncRequired) {
return { messages: [], fullResyncRequired: true };
}
throw error;
}
}
// Initial bounded pull (resumable via pageToken persisted in the cursor row).
const page = await listMessageIds(creds.accessToken, {
q: initialSyncQuery(opts.initialSince),
pageToken: opts.pageToken ?? undefined,
maxResults: 50,
});
const messages = await fetchMapped(creds.accessToken, page.messageIds);
return { messages, nextPageToken: page.nextPageToken };
},
async getMessage(creds: EmailCreds, providerMessageId: string): Promise<NeutralMessage | null> {
try {
return mapGmailMessage(await getMessage(creds.accessToken, providerMessageId, "full"));
} catch (error) {
if (error instanceof GmailError && error.code === "message_not_found") {
return null;
}
throw error;
}
},
async sendMessage(creds: EmailCreds, input: SendMailInput): Promise<SendMailResult> {
const info = await fetchGmailUserInfo(creds.accessToken);
const raw = buildRfc2822Message({
fromAddress: info.email,
to: input.to,
cc: input.cc,
bcc: input.bcc,
subject: input.subject,
bodyHtml: input.bodyHtml,
inReplyToInternetMessageId: input.inReplyToInternetMessageId,
referencesInternetMessageIds: input.referencesInternetMessageIds,
attachments: input.attachments,
});
const result = await sendRawMessage(creds.accessToken, toBase64Url(raw), input.providerThreadId ?? undefined);
return { providerMessageId: result.id, providerThreadId: result.threadId ?? null };
},
async markRead(creds: EmailCreds, providerMessageId: string, isRead: boolean): Promise<void> {
await modifyMessageLabels(creds.accessToken, providerMessageId, isRead ? { removeLabelIds: ["UNREAD"] } : { addLabelIds: ["UNREAD"] });
},
async listAttachments(creds: EmailCreds, providerMessageId: string): Promise<NeutralAttachmentMeta[]> {
const message = await this.getMessage(creds, providerMessageId);
return message ? [...message.attachments] : [];
},
async downloadAttachment(creds: EmailCreds, providerMessageId: string, attachmentId: string): Promise<NeutralAttachmentContent | null> {
const metas = await this.listAttachments(creds, providerMessageId);
const meta = metas.find((m) => m.attachmentId === attachmentId);
if (!meta) {
return null;
}
const body = await getAttachment(creds.accessToken, providerMessageId, attachmentId);
// Gmail returns base64url → normalize to standard base64 for storage.
const normalized = body.data.replace(/-/g, "+").replace(/_/g, "/");
return { ...meta, sizeBytes: body.size || meta.sizeBytes, contentBase64: normalized };
},
};
// Keep the pseudo-folder key exported for the sync services (cursor rows).
export { GMAIL_GLOBAL_FOLDER };
@@ -0,0 +1,182 @@
// VA-P23 · Microsoft Graph implementation of the EmailProviderAdapter.
//
// Maps the neutral domain shapes to/from the shared @hivegrid/integrations Graph
// REST client. No Prisma here. Graph specifics (M09 Block D/G): subscriptions
// live ~3 days (renewal cron PATCHes), delta is PER FOLDER (inbox + sentitems),
// and sendMail answers 202 without a message id → the caller mirrors locally and
// the sent-items delta dedupes via internetMessageId.
import {
GraphMailError,
buildInitialDeltaUrl,
buildMicrosoftAuthorizationUrl,
createMailSubscription,
deleteMailSubscription,
exchangeMicrosoftCodeForTokens,
fetchDeltaPage,
fetchGraphUserProfile,
getGraphAttachment,
getGraphMessage,
listGraphAttachments,
mapGraphMessage,
refreshMicrosoftAccessToken,
renewMailSubscription,
resolveMicrosoftMailOAuthConfig,
sendGraphMail,
setGraphMessageRead,
type MicrosoftMailOAuthConfig,
} from "@hivegrid/integrations";
import {
type EmailAccount,
type EmailCreds,
type EmailProviderAdapter,
type EmailTokens,
type MailDeltaResult,
type MailWebhookSubscription,
type NeutralAttachmentContent,
type NeutralAttachmentMeta,
type NeutralMessage,
type SendMailInput,
type SendMailResult,
} from "./EmailProviderAdapter";
import { EmailInboxNotConfiguredError } from "./GmailAdapter.server";
function requireConfig(): MicrosoftMailOAuthConfig {
const config = resolveMicrosoftMailOAuthConfig();
if (!config) {
throw new EmailInboxNotConfiguredError("microsoft");
}
return config;
}
export const microsoftMailProviderAdapter: EmailProviderAdapter = {
provider: "microsoft",
isConfigured(): boolean {
return resolveMicrosoftMailOAuthConfig() !== null;
},
buildAuthorizationUrl(state: string): string {
return buildMicrosoftAuthorizationUrl(requireConfig(), state);
},
async exchangeCode(code: string): Promise<{ tokens: EmailTokens; account: EmailAccount }> {
const config = requireConfig();
const tokenSet = await exchangeMicrosoftCodeForTokens(config, code);
const profile = await fetchGraphUserProfile(tokenSet.accessToken);
return {
tokens: { accessToken: tokenSet.accessToken, refreshToken: tokenSet.refreshToken, expiresAt: tokenSet.expiresAt, scopes: tokenSet.scopes },
account: { email: profile.email, accountId: profile.id, displayName: profile.displayName },
};
},
async refreshTokens(refreshToken: string): Promise<EmailTokens> {
const set = await refreshMicrosoftAccessToken(requireConfig(), refreshToken);
return { accessToken: set.accessToken, refreshToken: set.refreshToken, expiresAt: set.expiresAt, scopes: set.scopes };
},
async subscribeWebhook(creds: EmailCreds, notificationUrl: string, clientState: string): Promise<MailWebhookSubscription> {
const subscription = await createMailSubscription(creds.accessToken, notificationUrl, clientState);
return { subscriptionId: subscription.id, expiresAt: subscription.expiresAt, initialCursor: null };
},
async renewWebhook(creds: EmailCreds, subscriptionId: string, notificationUrl: string, clientState: string): Promise<MailWebhookSubscription> {
try {
const renewed = await renewMailSubscription(creds.accessToken, subscriptionId);
return { subscriptionId: renewed.id, expiresAt: renewed.expiresAt, initialCursor: null };
} catch (error) {
// Already expired at Microsoft → re-create instead of renew.
if (error instanceof GraphMailError && error.code === "subscription_failed") {
return this.subscribeWebhook(creds, notificationUrl, clientState);
}
throw error;
}
},
async revokeWebhook(creds: EmailCreds, subscriptionId: string): Promise<void> {
await deleteMailSubscription(creds.accessToken, subscriptionId);
},
async revokeTokens(): Promise<void> {
// The Microsoft identity platform has no app-side delegated-token revoke —
// disconnect drops the ciphertexts + subscription (documented in the service).
},
async fetchMessages(
creds: EmailCreds,
folderId: string,
opts: { cursor?: string | null; pageToken?: string | null; initialSince?: Date },
): Promise<MailDeltaResult> {
// Graph paging: cursor = @odata.deltaLink, pageToken = @odata.nextLink —
// both are followed verbatim; absent both, start a bounded initial delta.
const url =
opts.pageToken ??
opts.cursor ??
buildInitialDeltaUrl(folderId, opts.initialSince ? opts.initialSince.toISOString() : undefined);
try {
const page = await fetchDeltaPage(creds.accessToken, url);
const messages = page.messages
.filter((m) => !m["@removed"])
.map((m) => mapGraphMessage(m, folderId));
return { messages, nextCursor: page.deltaLink, nextPageToken: page.nextLink };
} catch (error) {
if (error instanceof GraphMailError && error.fullResyncRequired) {
return { messages: [], fullResyncRequired: true };
}
throw error;
}
},
async getMessage(creds: EmailCreds, providerMessageId: string): Promise<NeutralMessage | null> {
try {
const message = await getGraphMessage(creds.accessToken, providerMessageId);
// Folder context is unknown on a direct fetch — inbox mapping is neutral
// here; the caller preserves the stored direction on upsert.
return mapGraphMessage(message, "inbox");
} catch (error) {
if (error instanceof GraphMailError && error.code === "message_not_found") {
return null;
}
throw error;
}
},
async sendMessage(creds: EmailCreds, input: SendMailInput): Promise<SendMailResult> {
await sendGraphMail(creds.accessToken, {
subject: input.subject,
bodyHtml: input.bodyHtml,
to: input.to,
cc: input.cc,
bcc: input.bcc,
attachments: input.attachments?.map((a) => ({ name: a.filename, contentType: a.mimeType, contentBase64: a.contentBase64 })),
inReplyToInternetMessageId: input.inReplyToInternetMessageId ?? undefined,
});
// 202 without an id — the sent-items delta ingests the provider copy and
// dedupes onto the local outbound mirror via internetMessageId.
return { providerMessageId: null, providerThreadId: input.providerThreadId ?? null };
},
async markRead(creds: EmailCreds, providerMessageId: string, isRead: boolean): Promise<void> {
await setGraphMessageRead(creds.accessToken, providerMessageId, isRead);
},
async listAttachments(creds: EmailCreds, providerMessageId: string): Promise<NeutralAttachmentMeta[]> {
const list = await listGraphAttachments(creds.accessToken, providerMessageId);
return list.map((a) => ({ attachmentId: a.id, filename: a.name, mimeType: a.contentType ?? null, sizeBytes: a.sizeBytes }));
},
async downloadAttachment(creds: EmailCreds, providerMessageId: string, attachmentId: string): Promise<NeutralAttachmentContent | null> {
const attachment = await getGraphAttachment(creds.accessToken, providerMessageId, attachmentId);
if (!attachment.contentBase64) {
// >3 MB needs the $value stream — deferred (v1 size cap in the caller).
return null;
}
return {
attachmentId: attachment.id,
filename: attachment.name,
mimeType: attachment.contentType ?? null,
sizeBytes: attachment.sizeBytes,
contentBase64: attachment.contentBase64,
};
},
};
@@ -0,0 +1,78 @@
import { describe, expect, it, vi } from "vitest";
const findMany = vi.fn();
vi.mock("~/utils/db.server", () => ({
db: { emailIntegrationMailbox: { findMany: (...args: unknown[]) => findMany(...args) } },
}));
import { maskEmailActivitiesForViewer, shouldMaskEmailActivity } from "./emailActivityMasking.server";
// VA-P23 — DoD 6: email.read_own vs read_all must filter the Activity-Stream,
// not just the inbox list. Foreign email activities collapse to the Klartext
// placeholder without subject/snippet details.
const OWN = new Set(["mb-own"]);
describe("shouldMaskEmailActivity (pure)", () => {
it("never masks non-email activities", () => {
expect(shouldMaskEmailActivity({ activityType: "note_added", summaryText: "x" }, { canReadAll: false, canReadOwn: false, ownMailboxIds: OWN })).toBe(false);
});
it("read_all sees everything", () => {
expect(
shouldMaskEmailActivity({ activityType: "email_received", summaryText: "x", metadata: { mailboxId: "mb-foreign" } }, { canReadAll: true, canReadOwn: true, ownMailboxIds: OWN }),
).toBe(false);
});
it("read_own sees own-mailbox activities but not foreign ones", () => {
const viewer = { canReadAll: false, canReadOwn: true, ownMailboxIds: OWN };
expect(shouldMaskEmailActivity({ activityType: "email_received", summaryText: "x", metadata: { mailboxId: "mb-own" } }, viewer)).toBe(false);
expect(shouldMaskEmailActivity({ activityType: "email_sent", summaryText: "x", metadata: { mailboxId: "mb-foreign" } }, viewer)).toBe(true);
});
it("masks conservatively when the mailbox reference is missing", () => {
expect(shouldMaskEmailActivity({ activityType: "email_received", summaryText: "x" }, { canReadAll: false, canReadOwn: true, ownMailboxIds: OWN })).toBe(true);
});
it("no email permission at all masks every email activity", () => {
expect(
shouldMaskEmailActivity({ activityType: "email_received", summaryText: "x", metadata: { mailboxId: "mb-own" } }, { canReadAll: false, canReadOwn: false, ownMailboxIds: new Set() }),
).toBe(true);
});
});
describe("maskEmailActivitiesForViewer", () => {
it("replaces masked rows with the Klartext placeholder and drops metadata", async () => {
findMany.mockResolvedValue([{ id: "mb-own" }]);
const rows = [
{ activityType: "email_received", summaryText: "Eingehende E-Mail: geheim", metadata: { mailboxId: "mb-foreign", snippet: "geheim" } },
{ activityType: "email_sent", summaryText: "Eigene Mail", metadata: { mailboxId: "mb-own" } },
{ activityType: "note_added", summaryText: "Notiz" },
];
const masked = await maskEmailActivitiesForViewer({
tenantId: "t1",
userId: "u1",
permissions: ["email.read_own", "email.write"],
rows,
maskedText: "E-Mail-Aktivität (nicht einsehbar)",
});
expect(masked[0].summaryText).toBe("E-Mail-Aktivität (nicht einsehbar)");
expect(masked[0].metadata).toBeUndefined();
expect(masked[1].summaryText).toBe("Eigene Mail");
expect(masked[2].summaryText).toBe("Notiz");
});
it("short-circuits without a DB query for read_all viewers", async () => {
findMany.mockClear();
const rows = [{ activityType: "email_received", summaryText: "x", metadata: { mailboxId: "mb-foreign" } }];
const result = await maskEmailActivitiesForViewer({
tenantId: "t1",
userId: "u1",
permissions: ["email.read_all"],
rows,
maskedText: "masked",
});
expect(result[0].summaryText).toBe("x");
expect(findMany).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,70 @@
// VA-P23 · Activity-Stream permission masking (M09 Block H, DoD 6).
//
// email_received/email_sent activities on a Kontakt/Lead/Projekt timeline are
// visible only to users who may see the underlying mailbox: `email.read_all`
// sees everything; `email.read_own` sees activities of their OWN mailboxes
// (metadata.mailboxId); everyone else gets the Klartext placeholder
// "E-Mail-Aktivität (nicht einsehbar)" WITHOUT subject/snippet details.
import { db } from "~/utils/db.server";
import { EMAIL_PERMISSIONS } from "../routes/emailInboxAccess.server";
const EMAIL_ACTIVITY_PREFIX = "email_";
export interface MaskableActivityRow {
activityType: string;
summaryText: string;
metadata?: unknown;
}
/** Pure decision: mask this row for a viewer with the given visibility? */
export function shouldMaskEmailActivity(
row: MaskableActivityRow,
viewer: { canReadAll: boolean; canReadOwn: boolean; ownMailboxIds: ReadonlySet<string> },
): boolean {
if (!row.activityType.startsWith(EMAIL_ACTIVITY_PREFIX)) {
return false;
}
if (viewer.canReadAll) {
return false;
}
if (!viewer.canReadOwn) {
return true;
}
const mailboxId = (row.metadata as { mailboxId?: unknown } | null | undefined)?.mailboxId;
// Conservative: an email activity without a mailbox reference is masked too.
return typeof mailboxId !== "string" || !viewer.ownMailboxIds.has(mailboxId);
}
/**
* Mask email activities in-place-safe (returns new row objects where masked).
* `maskedText` is the pre-translated Klartext placeholder from the caller.
*/
export async function maskEmailActivitiesForViewer<T extends MaskableActivityRow>(input: {
tenantId: string;
userId: string;
permissions: readonly string[];
rows: readonly T[];
maskedText: string;
}): Promise<T[]> {
const hasEmailRows = input.rows.some((row) => row.activityType.startsWith(EMAIL_ACTIVITY_PREFIX));
const canReadAll = input.permissions.includes(EMAIL_PERMISSIONS.readAll);
if (!hasEmailRows || canReadAll) {
return [...input.rows];
}
const canReadOwn = input.permissions.includes(EMAIL_PERMISSIONS.readOwn);
const ownMailboxIds = canReadOwn
? new Set(
(
await db.emailIntegrationMailbox.findMany({
where: { tenantId: input.tenantId, ownerUserId: input.userId, archivedAt: null },
select: { id: true },
})
).map((m) => m.id),
)
: new Set<string>();
const viewer = { canReadAll, canReadOwn, ownMailboxIds };
return input.rows.map((row) =>
shouldMaskEmailActivity(row, viewer) ? { ...row, summaryText: input.maskedText, metadata: undefined } : row,
);
}
@@ -0,0 +1,78 @@
// @vitest-environment jsdom
import { describe, expect, it } from "vitest";
import { renderPlainTextAsHtml, sanitizeEmailHtml } from "./emailHtmlSanitizer";
// VA-P23 — the XSS fixtures for the email body renderer (M09 Block F). Email
// HTML is untrusted third-party input; every vector here MUST stay neutralized.
describe("sanitizeEmailHtml — XSS vectors", () => {
it("strips script tags and inline event handlers", () => {
const { html } = sanitizeEmailHtml(`<p>Hi</p><script>alert(1)</script><img src="x" onerror="alert(2)">`);
expect(html).not.toContain("<script");
expect(html).not.toContain("onerror");
expect(html).toContain("<p>Hi</p>");
});
it("neutralizes javascript: URLs", () => {
const { html } = sanitizeEmailHtml(`<a href="javascript:alert(1)">click</a>`);
expect(html).not.toContain("javascript:");
});
it("removes iframes, objects, forms and inputs (phishing surface)", () => {
const { html } = sanitizeEmailHtml(
`<iframe src="https://evil.example"></iframe><object data="x"></object><form action="https://evil.example"><input name="password"></form>`,
);
expect(html).not.toContain("<iframe");
expect(html).not.toContain("<object");
expect(html).not.toContain("<form");
expect(html).not.toContain("<input");
});
it("strips SVG script payloads", () => {
const { html } = sanitizeEmailHtml(`<svg><script>alert(1)</script></svg>`);
expect(html).not.toContain("script");
});
});
describe("sanitizeEmailHtml — external images (opt-in)", () => {
it("blocks external images by default and counts them", () => {
const { html, blockedImageCount } = sanitizeEmailHtml(
`<img src="https://tracker.example/pixel.png"><img src="//cdn.example/x.jpg"><img src="cid:inline-1">`,
);
expect(blockedImageCount).toBe(2);
// No live `src` may point at the network (`data-hg-blocked-src` is inert).
expect(html).not.toMatch(/\ssrc="(https?:)?\/\//);
expect(html).toContain('data-hg-blocked-src="https://tracker.example/pixel.png"');
expect(html).toContain('src="cid:inline-1"');
});
it("keeps external images when the user opted in", () => {
const { html, blockedImageCount } = sanitizeEmailHtml(`<img src="https://cdn.example/x.jpg">`, { allowExternalImages: true });
expect(blockedImageCount).toBe(0);
expect(html).toContain('src="https://cdn.example/x.jpg"');
});
it("strips css url(...) tracking (style + background attr)", () => {
const { html } = sanitizeEmailHtml(`<div style="background-image:url('https://t.example/p.gif');color:red">x</div><td background="https://t.example/bg.gif">y</td>`);
expect(html).not.toContain("t.example");
expect(html).toContain("color:red");
});
});
describe("sanitizeEmailHtml — link hardening", () => {
it("forces target=_blank + noopener on links", () => {
const { html } = sanitizeEmailHtml(`<a href="https://kunde.de/angebot">Angebot</a>`);
expect(html).toContain('target="_blank"');
expect(html).toContain("noopener");
});
});
describe("renderPlainTextAsHtml", () => {
it("escapes html in plain-text bodies", () => {
const html = renderPlainTextAsHtml(`Hallo <script>alert(1)</script>\nZeile 2`);
expect(html).toContain("&lt;script&gt;");
expect(html).not.toContain("<script>");
expect(html).toContain("Zeile 2");
});
});
@@ -0,0 +1,83 @@
// VA-P23 · safe email-HTML rendering (M09 Block F — CSP-hardened container).
//
// Email bodies are UNTRUSTED third-party HTML — the classic stored-XSS vector.
// Sanitization = DOMPurify (isomorphic build: jsdom on the server, native DOM
// in the browser; team decision 2026-07-02) + an email-specific layer on top:
// - external images are BLOCKED by default (`src` moved to `data-hg-blocked-src`,
// the UI re-enables them via the "Bilder laden" opt-in → allowExternalImages)
// - inline `cid:`/`data:` images stay (no network fetch)
// - style url(...) references are stripped (CSS-based tracking pixels)
// - links are forced to target="_blank" rel="noopener noreferrer nofollow"
// - forms/inputs are removed entirely (no credential phishing surface)
import DOMPurify from "isomorphic-dompurify";
export interface SanitizedEmailHtml {
readonly html: string;
/** Number of external images that were blocked (drives the opt-in banner). */
readonly blockedImageCount: number;
}
const FORBIDDEN_TAGS = ["form", "input", "select", "textarea", "button", "iframe", "frame", "object", "embed", "base", "meta", "link"];
const EXTERNAL_SRC = /^(https?:)?\/\//i;
const CSS_URL_PATTERN = /url\s*\(/i;
let hooksInstalled = false;
let hookState: { allowExternalImages: boolean; blockedImageCount: number } = { allowExternalImages: false, blockedImageCount: 0 };
function ensureHooks(): void {
if (hooksInstalled) return;
hooksInstalled = true;
DOMPurify.addHook("afterSanitizeAttributes", (node) => {
const tag = node.tagName?.toLowerCase();
// Block external image loads unless the user opted in ("Bilder laden").
if (tag === "img") {
const src = node.getAttribute("src") ?? "";
if (EXTERNAL_SRC.test(src) && !hookState.allowExternalImages) {
node.setAttribute("data-hg-blocked-src", src);
node.removeAttribute("src");
node.setAttribute("alt", node.getAttribute("alt") ?? "");
hookState.blockedImageCount += 1;
}
node.removeAttribute("srcset");
node.removeAttribute("loading");
}
// Styles: no url(...) (CSS tracking pixels / exfil).
const style = node.getAttribute?.("style");
if (style && CSS_URL_PATTERN.test(style)) {
node.setAttribute("style", style.replace(/url\s*\([^)]*\)/gi, "none"));
}
if (node.hasAttribute?.("background")) {
node.removeAttribute("background");
}
// Links open sandboxed in a new tab.
if (tag === "a") {
node.setAttribute("target", "_blank");
node.setAttribute("rel", "noopener noreferrer nofollow");
}
});
}
/**
* Sanitize an email HTML body for rendering. NOT idempotent state-wise — the
* blocked-image counter is per call (module-level hook state, single-threaded
* per request in Node).
*/
export function sanitizeEmailHtml(html: string, options: { allowExternalImages?: boolean } = {}): SanitizedEmailHtml {
ensureHooks();
hookState = { allowExternalImages: options.allowExternalImages ?? false, blockedImageCount: 0 };
const clean = DOMPurify.sanitize(html, {
USE_PROFILES: { html: true },
FORBID_TAGS: FORBIDDEN_TAGS,
FORBID_ATTR: ["onerror", "onload", "onclick", "formaction", "ping"],
ALLOW_DATA_ATTR: false,
ADD_ATTR: ["data-hg-blocked-src", "target", "rel"],
});
return { html: clean, blockedImageCount: hookState.blockedImageCount };
}
/** Plain-text fallback rendering (bodyText mails) — escaped, newlines kept. */
export function renderPlainTextAsHtml(text: string): string {
const escaped = text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
return `<pre style="white-space:pre-wrap;font-family:inherit">${escaped}</pre>`;
}
@@ -0,0 +1,44 @@
import { describe, expect, it } from "vitest";
import { signEmailOAuthState, verifyEmailOAuthState } from "./oauthState.server";
const secret = "test-email-oauth-secret-please-rotate-32bb";
const input = { tenantId: "tenant-1", userId: "user-1", tenantSlug: "acme", provider: "gmail" as const };
describe("email OAuth state (CSRF + provider pinning)", () => {
it("round-trips a signed state", () => {
const token = signEmailOAuthState(input, { secret });
const result = verifyEmailOAuthState(token, "gmail", { secret });
expect(result.ok).toBe(true);
if (!result.ok) throw new Error("expected ok");
expect(result.payload.tenantId).toBe("tenant-1");
expect(result.payload.userId).toBe("user-1");
expect(result.payload.tenantSlug).toBe("acme");
expect(result.payload.provider).toBe("gmail");
});
it("rejects a state presented to the wrong provider callback", () => {
const token = signEmailOAuthState(input, { secret });
expect(verifyEmailOAuthState(token, "microsoft", { secret })).toEqual({ ok: false, reason: "wrong-provider" });
});
it("rejects a tampered payload", () => {
const token = signEmailOAuthState(input, { secret });
const tampered = `x${token.slice(1)}`;
expect(verifyEmailOAuthState(tampered, "gmail", { secret })).toEqual({ ok: false, reason: "bad-signature" });
});
it("rejects a wrong-secret signature", () => {
const token = signEmailOAuthState(input, { secret });
expect(verifyEmailOAuthState(token, "gmail", { secret: "a-different-secret-value-of-length-32xx" })).toEqual({ ok: false, reason: "bad-signature" });
});
it("rejects a malformed token", () => {
expect(verifyEmailOAuthState("not-a-token", "gmail", { secret })).toEqual({ ok: false, reason: "malformed" });
});
it("rejects an expired state", () => {
const token = signEmailOAuthState(input, { secret, now: () => 1_000_000 });
const later = () => 1_000_000 + 11 * 60 * 1000; // 11 minutes later (> 10m TTL)
expect(verifyEmailOAuthState(token, "gmail", { secret, now: later })).toEqual({ ok: false, reason: "expired" });
});
});
@@ -0,0 +1,115 @@
// VA-P23 · OAuth state signing for the mailbox connect flows (CSRF + context).
//
// The OAuth callbacks at /integrations/email/{google|microsoft}/oauth/callback
// are NOT tenant-scoped (providers redirect to fixed URIs), so tenant + user +
// provider travel inside a SIGNED `state` parameter rather than a cookie. We
// HMAC-SHA256 the JSON payload with CRYPTO_SECRET||SESSION_SECRET (same
// convention as calendar/oauthState.server) and URL-safe-base64 encode it.
// 10-minute TTL bounds the replay window.
import { createHmac, timingSafeEqual } from "node:crypto";
import { loadRequiredWebConfig } from "@hivegrid/config";
const STATE_TTL_MS = 10 * 60 * 1000;
const PAYLOAD_VERSION = "v1";
export type EmailOAuthProvider = "gmail" | "microsoft";
export interface EmailOAuthStatePayload {
readonly tenantId: string;
readonly userId: string;
readonly tenantSlug: string;
readonly provider: EmailOAuthProvider;
/** Epoch milliseconds. */
readonly createdAt: number;
}
export type VerifyEmailStateResult =
| { readonly ok: true; readonly payload: EmailOAuthStatePayload }
| { readonly ok: false; readonly reason: "malformed" | "bad-signature" | "expired" | "wrong-provider" };
function getSecret(override?: string): string {
if (override) return override;
const { cryptoSecret, sessionSecret } = loadRequiredWebConfig();
const secret = cryptoSecret || sessionSecret;
if (!secret) {
throw new Error("CRYPTO_SECRET or SESSION_SECRET is required for email OAuth state.");
}
return secret;
}
function base64UrlEncode(input: string): string {
return Buffer.from(input, "utf8").toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}
function base64UrlDecode(value: string): string {
const pad = value.length % 4 === 0 ? "" : "=".repeat(4 - (value.length % 4));
return Buffer.from(value.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64").toString("utf8");
}
function sign(body: string, secret: string): string {
return Buffer.from(createHmac("sha256", secret).update(body).digest()).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}
/** Sign a fresh state token for the consent redirect. */
export function signEmailOAuthState(
input: { tenantId: string; userId: string; tenantSlug: string; provider: EmailOAuthProvider },
options: { now?: () => number; secret?: string } = {},
): string {
const payload: EmailOAuthStatePayload = {
tenantId: input.tenantId,
userId: input.userId,
tenantSlug: input.tenantSlug,
provider: input.provider,
createdAt: options.now ? options.now() : Date.now(),
};
const body = base64UrlEncode(JSON.stringify({ v: PAYLOAD_VERSION, p: payload }));
return `${body}.${sign(body, getSecret(options.secret))}`;
}
/**
* Verify + decode a state token returned by the provider. `expectedProvider`
* pins the callback route to its provider (a Gmail state on the Microsoft
* callback is rejected).
*/
export function verifyEmailOAuthState(
state: string,
expectedProvider: EmailOAuthProvider,
options: { now?: () => number; secret?: string } = {},
): VerifyEmailStateResult {
const dot = state.lastIndexOf(".");
if (dot <= 0) {
return { ok: false, reason: "malformed" };
}
const body = state.slice(0, dot);
const sig = state.slice(dot + 1);
let secret: string;
try {
secret = getSecret(options.secret);
} catch {
return { ok: false, reason: "malformed" };
}
const expected = sign(body, secret);
const a = Buffer.from(sig);
const b = Buffer.from(expected);
if (a.length !== b.length || !timingSafeEqual(a, b)) {
return { ok: false, reason: "bad-signature" };
}
let decoded: { v: string; p: EmailOAuthStatePayload };
try {
decoded = JSON.parse(base64UrlDecode(body)) as { v: string; p: EmailOAuthStatePayload };
} catch {
return { ok: false, reason: "malformed" };
}
if (decoded.v !== PAYLOAD_VERSION || !decoded.p || typeof decoded.p.createdAt !== "number") {
return { ok: false, reason: "malformed" };
}
if (decoded.p.provider !== expectedProvider) {
return { ok: false, reason: "wrong-provider" };
}
const now = options.now ? options.now() : Date.now();
if (now - decoded.p.createdAt > STATE_TTL_MS) {
return { ok: false, reason: "expired" };
}
return { ok: true, payload: decoded.p };
}