Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
+121
@@ -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 };
|
||||
}
|
||||
+173
@@ -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" }],
|
||||
});
|
||||
}
|
||||
+283
@@ -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,
|
||||
},
|
||||
});
|
||||
}
|
||||
+130
@@ -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>;
|
||||
}
|
||||
+209
@@ -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 };
|
||||
+182
@@ -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,
|
||||
};
|
||||
},
|
||||
};
|
||||
+78
@@ -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();
|
||||
});
|
||||
});
|
||||
+70
@@ -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,
|
||||
);
|
||||
}
|
||||
+78
@@ -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("<script>");
|
||||
expect(html).not.toContain("<script>");
|
||||
expect(html).toContain("Zeile 2");
|
||||
});
|
||||
});
|
||||
+83
@@ -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, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """);
|
||||
return `<pre style="white-space:pre-wrap;font-family:inherit">${escaped}</pre>`;
|
||||
}
|
||||
+44
@@ -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" });
|
||||
});
|
||||
});
|
||||
+115
@@ -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 };
|
||||
}
|
||||
Reference in new issue
Block a user