Merge pull request #214 from berkmancenter/cj/topic-resolution

When creating a conversation from a calendar invite, determine owner and which topic it belongs to

Author: cbj0hns0n

.env.example

@@ -65,7 +65,8 @@ JWT_RESET_PASSWORD_EXPIRATION_MINUTES=120
 # Short by design: the token is meant to be clicked from Slack within an hour.
 # HANDOFF_TOKEN_EXPIRATION_MINUTES=60
 
-# SMTP configuration options for the email service
+# SMTP configuration options for the email service.
+# On real deployments, point these at interfaces like Postmark's SMTP interface
 # For testing, you can use a fake SMTP service like Ethereal: https://ethereal.email/create
 SMTP_HOST=email-server
 SMTP_PORT=587
@@ -79,6 +80,11 @@ EMAIL_FROM=support@yourapp.com
 #POSTMARK_WEBHOOK_AUTH_USER=
 #POSTMARK_WEBHOOK_AUTH_SECRET=
 
+# Comma-separated email domains whose senders, if they have no account yet, get a "please sign up"
+# reply to an inbound calendar invite. Invites from any other domain are rejected (no event, no reply).
+# Unset means no domains are allowlisted, so no signup invites are sent.
+#ALLOWED_ORGANIZER_EMAIL_DOMAINS=example.edu
+
 # Public URL of the Nextspace frontend. Used to build links for password
 # reset emails, channel archive emails, and the Slack event-setup handoff
 # link the bot posts when an organizer asks to create an event.

src/config/config.ts

@@ -135,7 +135,10 @@ const envVarsSchema = Joi.object()
       .description('Minutes after scheduledEndTime to auto-stop a conversation'),
     SYSTEM_USERS: Joi.string()
       .default('event-setup-bot:serviceAccount')
-      .description('Comma-separated list of system accounts to create on startup, in username:role format')
+      .description('Comma-separated list of system accounts to create on startup, in username:role format'),
+    ALLOWED_ORGANIZER_EMAIL_DOMAINS: Joi.string().description(
+      'Comma-separated email domains whose senders, if they have no account yet, get a "please sign up" reply to an inbound invite. Invites from any other domain are rejected: no event, no reply. Unset means none, so no signup invites are ever sent.'
+    )
   })
   .unknown()
 
@@ -287,6 +290,10 @@ const config = {
   systemUsers: envVars.SYSTEM_USERS.split(',').map((entry: string) => {
     const [username, role] = entry.trim().split(':')
     return { username, role }
-  })
+  }),
+  allowedOrganizerEmailDomains: (envVars.ALLOWED_ORGANIZER_EMAIL_DOMAINS ?? '')
+    .split(',')
+    .map((domain: string) => domain.trim().toLowerCase())
+    .filter((domain: string) => domain.length > 0)
 }
 export default config

src/docs/components.yml

@@ -759,7 +759,6 @@ components:
         - enableDMs
         - experiments
         - owner
-        - topic
       properties:
         id:
           type: string

src/models/conversation.model.ts

@@ -119,7 +119,8 @@ const conversationSchema = new mongoose.Schema<IConversation, ConversationModel>
     topic: {
       type: mongoose.SchemaTypes.ObjectId,
       ref: 'Topic',
-      required: true,
+      // Optional so a draft created from an inbound invite with no matching Topic can be saved with a
+      // blank topic for the organizer to fill in. Non-draft conversations still get one at creation.
       index: true
     },
     scheduledTime: {

src/services/conversation.service/index.ts

@@ -12,6 +12,7 @@ import config from '../../config/config.js'
 import adapterService from '../adapter.service.js'
 import channelService from '../channel.service.js'
 import { ConversationDocument } from '../../models/conversation.model.js'
+import { TopicDocument } from '../../models/topic.model.js'
 import { getConversationType } from '../../conversations/index.js'
 import adapterTypes from '../../adapters/index.js'
 import resolveConversationType from '../../conversations/resolver.js'
@@ -60,7 +61,7 @@ const startConversation = async (conversationOrId, user) => {
   await conversation.populate(['topic', 'agents', 'adapters'])
   if (
     user._id.toString() !== conversation.owner._id.toString() &&
-    user._id.toString() !== conversation.topic.owner._id.toString()
+    user._id.toString() !== conversation.topic?.owner?._id.toString()
   ) {
     throw new ApiError(httpStatus.FORBIDDEN, 'Only conversation or topic owner can start conversation')
   }
@@ -76,7 +77,10 @@ const stopConversation = async (conversationOrId, user) => {
     }
   }
   await conversation.populate(['topic', 'agents', 'adapters'])
-  if (user._id.toString() !== conversation.owner.toString() && user._id.toString() !== conversation.topic.owner.toString()) {
+  if (
+    user._id.toString() !== conversation.owner.toString() &&
+    user._id.toString() !== conversation.topic?.owner?.toString()
+  ) {
     throw new ApiError(httpStatus.FORBIDDEN, 'Only conversation or topic owner can stop conversation')
   }
   return doStopConversation(conversation)
@@ -141,17 +145,25 @@ async function scheduleConversationEndingSoon(conversation) {
 /**
  * Create a conversation
  * @param {Object} conversationBody
+ * @param {Object} user
+ * @param {Object} [options]
+ * @param {boolean} [options.allowDraft] trusted internal callers only; lets a conversation be created
+ *   with no topic, saved as a draft for the owner to complete (see createConversationFromType)
  * @returns {Promise<Conversation>}
  */
-const createConversation = async (conversationBody, user) => {
-  if (!conversationBody.topicId) throw new ApiError(httpStatus.BAD_REQUEST, 'topic id must be passed in request body')
-  const topicId = new mongoose.Types.ObjectId(conversationBody.topicId)
-  const topic = await Topic.findById(topicId)
-  if (!topic) {
-    throw new ApiError(httpStatus.BAD_REQUEST, 'No such topic')
-  }
-  if (!topic?.conversationCreationAllowed && user._id.toString() !== topic?.owner.toString()) {
-    throw new ApiError(httpStatus.FORBIDDEN, 'Conversation creation not allowed.')
+const createConversation = async (conversationBody, user, { allowDraft = false } = {}) => {
+  let topic: TopicDocument | null = null
+  if (conversationBody.topicId) {
+    const topicId = new mongoose.Types.ObjectId(conversationBody.topicId)
+    topic = await Topic.findById(topicId)
+    if (!topic) {
+      throw new ApiError(httpStatus.BAD_REQUEST, 'No such topic')
+    }
+    if (!topic.conversationCreationAllowed && user._id.toString() !== topic.owner.toString()) {
+      throw new ApiError(httpStatus.FORBIDDEN, 'Conversation creation not allowed.')
+    }
+  } else if (!allowDraft) {
+    throw new ApiError(httpStatus.BAD_REQUEST, 'topic id must be passed in request body')
   }
 
   if (conversationBody.scheduledTime && new Date(conversationBody.scheduledTime) <= new Date()) {
@@ -167,7 +179,7 @@ const createConversation = async (conversationBody, user) => {
   const conversation = new Conversation({
     name: conversationBody.name,
     owner: user,
-    topic,
+    ...(topic && { topic }),
     enableAgents: !!conversationBody.agentTypes?.length,
     ...(conversationBody.enableDMs !== undefined && { enableDMs: conversationBody.enableDMs }),
     ...(conversationBody.conversationType !== undefined && { conversationType: conversationBody.conversationType }),
@@ -212,8 +224,13 @@ const createConversation = async (conversationBody, user) => {
     await channelService.createChannel(conversation, channelProps)
   }
 
-  topic.conversations.push(conversation.toObject())
-  await Promise.all([conversation.save(), topic.save()])
+  // A topicless draft has nothing to link back to, so only touch the topic when one resolved.
+  if (topic) {
+    topic.conversations.push(conversation.toObject())
+    await Promise.all([conversation.save(), topic.save()])
+  } else {
+    await conversation.save()
+  }
   await transcript.loadEventMetadataIntoVectorStore(conversation)
 
   websocketGateway.broadcastNewConversation(conversation)
@@ -253,7 +270,7 @@ const createConversationFromType = async (params, user, { allowDraft = false } =
   }
 
   const resolved = resolveConversationType(params, conversationType, allowDraft)
-  return createConversation({ ...params, conversationType: type, ...resolved }, user)
+  return createConversation({ ...params, conversationType: type, ...resolved }, user, { allowDraft })
 }
 
 /**
@@ -269,7 +286,7 @@ const updateConversation = async (conversationBody, user) => {
   }
   if (
     user._id.toString() !== conversationDoc.owner.toString() &&
-    user._id.toString() !== conversationDoc.topic.owner.toString()
+    user._id.toString() !== conversationDoc.topic?.owner?.toString()
   ) {
     throw new ApiError(httpStatus.FORBIDDEN, 'Only conversation or topic owner can update.')
   }
@@ -702,7 +719,10 @@ const deleteConversation = async (id, user) => {
   if (!conversation) {
     throw new ApiError(httpStatus.NOT_FOUND, `Conversation with id ${id} not found`)
   }
-  if (user._id.toString() !== conversation.owner.toString() && user._id.toString() !== conversation.topic.owner.toString()) {
+  if (
+    user._id.toString() !== conversation.owner.toString() &&
+    user._id.toString() !== conversation.topic?.owner?.toString()
+  ) {
     throw new ApiError(httpStatus.FORBIDDEN, 'Only conversation or topic owner can delete.')
   }
   if (conversation.active) {
@@ -737,7 +757,10 @@ const patchConversationAgent = async (id, agentId, body, user) => {
     throw new ApiError(httpStatus.NOT_FOUND, `Conversation with id ${id} not found`)
   }
   const agentIdStr = agentId.toString() ? agentId.toString() : agentId
-  if (user._id.toString() !== conversation.owner.toString() && user._id.toString() !== conversation.topic.owner.toString()) {
+  if (
+    user._id.toString() !== conversation.owner.toString() &&
+    user._id.toString() !== conversation.topic?.owner?.toString()
+  ) {
     throw new ApiError(httpStatus.FORBIDDEN, 'Only conversation or topic owner can patch agents')
   }
   const agent = conversation.agents.find((a) => a._id!.toString() === agentIdStr)

src/services/email.service.ts

@@ -101,12 +101,32 @@ To prevent archival and keep your channel on Conversations, please copy and past
   await sendEmailAsync(to, subject, text, html)
 }
 
+/**
+ * Invite an inbound-invite sender who has no account yet to sign up.
+ * Only sent to senders inside an allowlisted domain (see emailSetup.service); an event is created
+ * only once they have an account, so this is the reply that unblocks them.
+ * @param {string} to
+ * @returns {Promise}
+ */
+const sendSignupInviteEmail = async (to) => {
+  const subject = 'Set up your account to create your event'
+  const signupUrl = `${config.appHost}/signup`
+  const text = `Hello,
+We received your calendar invite, but there's no account for this email address yet.
+To finish setting up your event, sign up here and then resend the invite: ${signupUrl}`
+  const html = `<p>Hello,</p>
+<p>We received your calendar invite, but there's no account for this email address yet.</p>
+<p>To finish setting up your event, <a href="${signupUrl}">sign up here</a> and then resend the invite.</p>`
+  await sendEmailAsync(to, subject, text, html)
+}
+
 const emailService = {
   transport,
   sendEmail,
   sendEmailAsync,
   sendPasswordResetEmail,
   sendPasswordResetEmailAsync,
-  sendArchiveTopicEmail
+  sendArchiveTopicEmail,
+  sendSignupInviteEmail
 }
 export default emailService

src/services/eventSetup/emailSetup.service.ts

@@ -0,0 +1,110 @@
+/**
+ * Resolves the two things an inbound calendar invite doesn't state directly: who owns the event
+ * (the organizer) and which Topic it belongs to. Both are decided deterministically here, with no
+ * LLM involved (see the plan's "Topic matching never uses the LLM"). The fuzzy fields (Zoom link,
+ * speakers, etc.) are extracted separately.
+ */
+import config from '../../config/config.js'
+import logger from '../../config/logger.js'
+import { Topic } from '../../models/index.js'
+import { TopicDocument } from '../../models/topic.model.js'
+import userService from '../user.service.js'
+import topicService from '../topic.service.js'
+import emailService from '../email.service.js'
+import { InboundInvite } from '../../types/index.types.js'
+
+/**
+ * The Topic prefix an invite's SUMMARY points at: the substring before the first colon, trimmed.
+ * Conversations in a series are named "<topic>: <additional info>", so "Team Sync: Jane Presents"
+ * points at the "Team Sync" topic. Returns null when there's no colon or the prefix is empty, which
+ * the caller reads as "no prefix to match, fall back to a new Topic."
+ */
+export const topicPrefixFromSummary = (summary?: string): string | null => {
+  if (!summary) return null
+  const colonIndex = summary.indexOf(':')
+  if (colonIndex === -1) return null
+  const prefix = summary.slice(0, colonIndex).trim()
+  return prefix.length > 0 ? prefix : null
+}
+
+/**
+ * Pick the candidate Topic whose name exactly equals the invite SUMMARY's prefix, comparing
+ * case-insensitively and ignoring surrounding whitespace. Exact match only: "Team Sync" must not
+ * match a "Team Syncs" Topic. Returns null when there's no prefix or nothing matches. The candidate
+ * list is the permission boundary; the caller decides which Topics go in it.
+ */
+export const matchTopicByPrefix = <T extends { name?: string }>(summary: string | undefined, candidates: T[]): T | null => {
+  const prefix = topicPrefixFromSummary(summary)
+  if (!prefix) return null
+  const target = prefix.toLowerCase()
+  return candidates.find((candidate) => (candidate.name ?? '').trim().toLowerCase() === target) ?? null
+}
+
+/** The lowercased domain of an email address, or null if it isn't shaped like `local@domain`. */
+const emailDomain = (address: string): string | null => {
+  const atIndex = address.lastIndexOf('@')
+  if (atIndex === -1) return null
+  const domain = address
+    .slice(atIndex + 1)
+    .trim()
+    .toLowerCase()
+  return domain.length > 0 ? domain : null
+}
+
+/** True when the sender is inside a domain we invite to sign up (see ALLOWED_ORGANIZER_EMAIL_DOMAINS). */
+const isAllowedOrganizerDomain = (address: string): boolean => {
+  const domain = emailDomain(address)
+  return domain !== null && config.allowedOrganizerEmailDomains.includes(domain)
+}
+
+/**
+ * Find the account that owns this invite, keying off the envelope From that Postmark
+ * received (never the spoofable .ics ORGANIZER). Returns the organizer, or null when no event should
+ * be created. The allowlisted domain is a hard gate checked first: any sender outside it is rejected
+ * outright, account or not, with no reply (confirming the address "just needs to sign up" would be a
+ * small information leak to arbitrary outsiders). Inside the allowlist, a known sender is the
+ * organizer and an unknown one gets a "please sign up" reply.
+ */
+export const resolveOrganizer = async (inboundInvite: InboundInvite) => {
+  const { fromAddress, invite } = inboundInvite
+
+  if (!isAllowedOrganizerDomain(fromAddress)) {
+    logger.warn(`Email webhook: sender ${fromAddress} is outside the allowlisted domains; rejecting, no event created`)
+    return null
+  }
+
+  // Match the organizer case-insensitively: the domain gate above already lowercases, and a
+  // lowercase-stored account would otherwise be missed by a mixed-case From and wrongly bounced.
+  const organizer = await userService.getUserByEmail(fromAddress.toLowerCase())
+  if (organizer) {
+    // A mismatch is worth watching (a spoof attempt, or a relay rewriting headers) but not worth
+    // blocking a real organizer's event over, so log and proceed on the trusted From.
+    if (invite.organizer && invite.organizer.toLowerCase() !== fromAddress.toLowerCase()) {
+      logger.warn(
+        `Email webhook: .ics ORGANIZER ${invite.organizer} differs from envelope From ${fromAddress}; trusting From`
+      )
+    }
+    return organizer
+  }
+
+  await emailService.sendSignupInviteEmail(fromAddress)
+  logger.info(`Email webhook: no account for ${fromAddress} (allowlisted domain); sent signup invite`)
+  return null
+}
+
+/**
+ * Decide which existing Topic this invite belongs to, deterministically. Match the SUMMARY's
+ * "<topic>:" prefix against the sender's candidate set (public Topics plus their own private ones),
+ * case-insensitively; the candidate set is the permission boundary. Returns the matched Topic, or
+ * null when nothing matches. On null the draft event is created with a blank topic for the organizer
+ * to fill in later, rather than inventing a Topic from a one-off invite.
+ */
+export const resolveTopic = async (inboundInvite: InboundInvite, organizer): Promise<TopicDocument | null> => {
+  const { invite } = inboundInvite
+
+  const candidates = await topicService.allTopicsByUser(organizer)
+  const matched = matchTopicByPrefix(invite.summary, candidates)
+  if (!matched?.id) return null
+
+  return Topic.findById(matched.id)
+}

src/services/resource.service.ts

@@ -100,7 +100,7 @@ const savePdf = async (conversationId: string, resourceId: string, fileBuffer: B
 
   const userId = user._id.toString()
   const isConvOwner = conv.owner.toString() === userId
-  const isTopicOwner = conv.topic.owner.toString() === userId
+  const isTopicOwner = conv.topic?.owner?.toString() === userId
   if (!isConvOwner && !isTopicOwner) {
     throw new ApiError(httpStatus.FORBIDDEN, 'Only conversation or topic owner can upload resources')
   }

src/types/index.types.ts

@@ -15,6 +15,14 @@ export interface ParsedInvite {
   organizer?: string // organizer email from the .ics ORGANIZER field, mailto: stripped
 }
 
+/* The trust boundary in one shape: `invite` is attacker-supplied .ics file content (anyone can put
+   any UID or ORGANIZER in a raw .ics), while `fromAddress` is the envelope From that Postmark actually
+   received. Identity resolution keys off fromAddress; ORGANIZER is only ever compared against it. */
+export interface InboundInvite {
+  fromAddress: string
+  invite: ParsedInvite
+}
+
 export interface PaginateResults<T> {
   results: Array<T>
   page: number

src/websockets/websocketGateway.ts

@@ -74,10 +74,13 @@ class WebsocketGateway {
   }
 
   async broadcastNewConversation(conversation) {
+    // A topicless draft (e.g. from an unmatched inbound invite) has no topic room to broadcast into.
+    if (!conversation.topic) return
     await this.broadcast(conversation.topic._id.toString(), 'conversation:new', conversation)
   }
 
   async broadcastConversationUpdate(conversation) {
+    if (!conversation.topic) return
     await this.broadcast(conversation.topic._id.toString(), 'conversation:update', conversation)
   }