@kelpie/server 0.4.0 → 0.5.0

package/src/modules/auth/index.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 
+import { appUrlConfigSchema } from '../../lib/appUrl.ts'
 import type { KelpieModule } from '../../runtime/module.ts'
 import { mountAuthRoutes } from './routes.ts'
 import * as schema from './schema.ts'
@@ -12,10 +13,12 @@ import { createAuthService } from './service.ts'
  * `users`.
  */
 
-const authConfigSchema = z.object({
-  /** Cookies go out `Secure` everywhere except development. */
-  NODE_ENV: z.enum(['development', 'test', 'production']),
-})
+const authConfigSchema = z
+  .object({
+    /** Cookies go out `Secure` everywhere except development. */
+    NODE_ENV: z.enum(['development', 'test', 'production']),
+  })
+  .merge(appUrlConfigSchema)
 
 export function createAuthModule(migrationsDirectory: string): KelpieModule {
   return {
@@ -30,6 +33,7 @@ export function createAuthModule(migrationsDirectory: string): KelpieModule {
         email: context.email,
         createId: context.createId,
         now: context.now,
+        appBaseUrl: config.APP_BASE_URL,
       })
 
       context.schema(schema, migrationsDirectory)
@@ -39,7 +43,10 @@ export function createAuthModule(migrationsDirectory: string): KelpieModule {
           db: context.db,
           now: context.now,
           service,
-          cookie: { secure: config.NODE_ENV === 'production' },
+          // `Secure` everywhere except development. A test host reaches the API
+          // over http through a test client, which stores the cookie regardless
+          // of the flag, so test is not excluded.
+          cookie: { secure: config.NODE_ENV !== 'development' },
         })
       })
 

package/src/modules/auth/repository.ts

@@ -3,7 +3,13 @@ import { and, desc, eq, gt, isNull, ne } from 'drizzle-orm'
 import type { Database } from '../../lib/database.ts'
 import type { Transaction } from '../../runtime/transaction.ts'
 import { workspaceMembers } from '../workspace/schema.ts'
-import { passwordResetTokens, sessions, userPreferences, users } from './schema.ts'
+import {
+  emailVerificationTokens,
+  passwordResetTokens,
+  sessions,
+  userPreferences,
+  users,
+} from './schema.ts'
 
 /**
  * Drizzle queries for accounts and sessions. No business logic: the service
@@ -209,6 +215,55 @@ export async function markPasswordResetTokenUsed(db: Queryable, id: string, now:
     .where(eq(passwordResetTokens.id, id))
 }
 
+export async function insertEmailVerificationToken(
+  db: Queryable,
+  values: typeof emailVerificationTokens.$inferInsert,
+): Promise<void> {
+  await db.insert(emailVerificationTokens).values(values)
+}
+
+/** Unused and unexpired. A used or stale token is not a token. */
+export async function findUsableEmailVerificationToken(
+  db: Queryable,
+  tokenHash: string,
+  now: Date,
+): Promise<typeof emailVerificationTokens.$inferSelect | undefined> {
+  const [found] = await db
+    .select()
+    .from(emailVerificationTokens)
+    .where(
+      and(
+        eq(emailVerificationTokens.tokenHash, tokenHash),
+        isNull(emailVerificationTokens.usedAt),
+        gt(emailVerificationTokens.expiresAt, now),
+      ),
+    )
+    .limit(1)
+
+  return found
+}
+
+export async function markEmailVerificationTokenUsed(db: Queryable, id: string, now: Date): Promise<void> {
+  await db
+    .update(emailVerificationTokens)
+    .set({ usedAt: now })
+    .where(eq(emailVerificationTokens.id, id))
+}
+
+/**
+ * Sets `email_verified_at` if it is not already set.
+ *
+ * Guarded in the `WHERE` clause rather than read-then-write, so accepting a
+ * second invite or confirming a stale token after the account is already
+ * verified is a no-op instead of overwriting the original verification time.
+ */
+export async function markEmailVerified(db: Queryable, userId: string, now: Date): Promise<void> {
+  await db
+    .update(users)
+    .set({ emailVerifiedAt: now })
+    .where(and(eq(users.id, userId), isNull(users.emailVerifiedAt)))
+}
+
 /** The membership a session's active workspace resolves to, if any. */
 export async function findMembership(
   db: Queryable,

package/src/modules/auth/routes.ts

@@ -31,8 +31,6 @@ const logInBody = z.object({
 
 const resetRequestBody = z.object({
   email: z.string().min(1),
-  /** Where the emailed link points. `{token}` is replaced with the reset token. */
-  reset_url_template: z.string().min(1).includes('{token}'),
 })
 
 const resetConfirmBody = z.object({
@@ -45,6 +43,10 @@ const changePasswordBody = z.object({
   new_password: z.string().min(1),
 })
 
+const verifyEmailConfirmBody = z.object({
+  token: z.string().min(1),
+})
+
 const updateAccountBody = z
   .strictObject({
     name: z.string().min(1),
@@ -95,13 +97,18 @@ function describeClient(context: Context): { device?: string; location?: string
 
 function accountResponse(issued: IssuedSession): Record<string, unknown> {
   return {
-    account: { id: issued.account.id, email: issued.account.email, name: issued.account.name },
+    account: accountBody(issued.account),
     active_workspace_id: issued.activeWorkspaceId,
   }
 }
 
 function accountBody(account: AccountView): Record<string, unknown> {
-  return { id: account.id, email: account.email, name: account.name }
+  return {
+    id: account.id,
+    email: account.email,
+    name: account.name,
+    email_verified: account.emailVerified,
+  }
 }
 
 function preferencesResponse(preferences: PreferenceValues): Record<string, unknown> {
@@ -131,7 +138,12 @@ export function mountAuthRoutes(router: Hono, dependencies: AuthRoutesDependenci
 
   router.post('/auth/signup', async (context) => {
     const body = await readBody(context, signUpBody)
-    const issued = await dependencies.service.signUp({ ...body, ...describeClient(context) })
+    const issued = await dependencies.service.signUp({
+      email: body.email,
+      name: body.name,
+      password: body.password,
+      ...describeClient(context),
+    })
 
     writeSessionCookie(context, issued.sessionToken, dependencies.cookie)
 
@@ -156,12 +168,14 @@ export function mountAuthRoutes(router: Hono, dependencies: AuthRoutesDependenci
 
   router.get('/auth/me', async (context) => {
     const actor = await requireActor(context)
+    const account = await dependencies.service.getAccount(actor)
 
     return context.json({
       user_id: actor.userId,
       session_id: actor.sessionId,
       workspace_id: actor.workspaceId,
       role: actor.role,
+      email_verified: account.emailVerified,
     })
   })
 
@@ -233,7 +247,7 @@ export function mountAuthRoutes(router: Hono, dependencies: AuthRoutesDependenci
    */
   router.post('/auth/password-reset', async (context) => {
     const body = await readBody(context, resetRequestBody)
-    await dependencies.service.requestPasswordReset(body.email, body.reset_url_template)
+    await dependencies.service.requestPasswordReset(body.email)
 
     return context.body(null, 202)
   })
@@ -244,4 +258,18 @@ export function mountAuthRoutes(router: Hono, dependencies: AuthRoutesDependenci
 
     return context.body(null, 204)
   })
+
+  /** Also what a "resend" button calls: a fresh token each time, and a no-op once verified. */
+  router.post('/auth/verify-email', async (context) => {
+    await dependencies.service.requestEmailVerification(await requireActor(context))
+
+    return context.body(null, 202)
+  })
+
+  router.post('/auth/verify-email/confirm', async (context) => {
+    const body = await readBody(context, verifyEmailConfirmBody)
+    await dependencies.service.confirmEmailVerification(body.token)
+
+    return context.body(null, 204)
+  })
 }

package/src/modules/auth/schema.ts

@@ -19,6 +19,8 @@ export const users = pgTable('users', {
   email: citext('email').notNull().unique(),
   name: text('name').notNull(),
   passwordHash: text('password_hash').notNull(),
+  /** Null until the address is verified, either by confirming a token or by accepting a workspace invite. */
+  emailVerifiedAt: moment('email_verified_at'),
   createdAt: createdAt(),
   updatedAt: updatedAt(),
 })
@@ -75,3 +77,18 @@ export const passwordResetTokens = pgTable('password_reset_tokens', {
   usedAt: moment('used_at'),
   createdAt: createdAt(),
 })
+
+/**
+ * One-shot tokens for the sign-up verification link. Same shape and the same
+ * reasoning as `passwordResetTokens`: hashed, marked used rather than deleted.
+ */
+export const emailVerificationTokens = pgTable('email_verification_tokens', {
+  id: primaryId(),
+  userId: text('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  tokenHash: text('token_hash').notNull().unique(),
+  expiresAt: moment('expires_at').notNull(),
+  usedAt: moment('used_at'),
+  createdAt: createdAt(),
+})

package/src/modules/auth/service.ts

@@ -1,3 +1,4 @@
+import { APP_LINK_PATHS, buildAppLink } from '../../lib/appUrl.ts'
 import type { EmailSender } from '../../lib/email.ts'
 import { AppError } from '../../lib/errors.ts'
 import type { IdFactory } from '../../lib/ids.ts'
@@ -22,6 +23,8 @@ import * as repository from './repository.ts'
 
 const SESSION_LIFETIME_MS = 30 * 24 * 60 * 60 * 1000
 const RESET_TOKEN_LIFETIME_MS = 60 * 60 * 1000
+/** Longer than a reset token: there is no stolen-account urgency, and an inbox is checked on its own time. */
+const EMAIL_VERIFICATION_TOKEN_LIFETIME_MS = 24 * 60 * 60 * 1000
 
 export interface AuthDependencies {
   readonly db: Database
@@ -29,6 +32,8 @@ export interface AuthDependencies {
   readonly email: EmailSender
   readonly createId: IdFactory
   readonly now: () => Date
+  /** The deployment's own base URL. Every emailed link is built from it. */
+  readonly appBaseUrl: string
   /** Injected only so tests can pin tokens. Production uses the crypto default. */
   readonly newToken?: () => string
 }
@@ -37,6 +42,7 @@ export interface AccountView {
   readonly id: string
   readonly email: string
   readonly name: string
+  readonly emailVerified: boolean
 }
 
 /** A session plus the plaintext token, which exists only in this return value. */
@@ -79,7 +85,7 @@ export interface LogInInput {
 }
 
 function toAccountView(user: repository.UserRecord): AccountView {
-  return { id: user.id, email: user.email, name: user.name }
+  return { id: user.id, email: user.email, name: user.name, emailVerified: user.emailVerifiedAt !== null }
 }
 
 function toPreferenceValues(record: repository.UserPreferencesRecord): PreferenceValues {
@@ -129,9 +135,12 @@ export interface AuthService {
   listSessions(actor: SessionActor): Promise<readonly SessionView[]>
   revokeSession(actor: SessionActor, sessionId: string): Promise<void>
   /** Resolves whether or not the address is registered. */
-  requestPasswordReset(email: string, resetUrlTemplate: string): Promise<void>
+  requestPasswordReset(email: string): Promise<void>
   confirmPasswordReset(token: string, newPassword: string): Promise<void>
   changePassword(actor: SessionActor, currentPassword: string, newPassword: string): Promise<void>
+  /** Issues a fresh verification token and emails it. A no-op once already verified. */
+  requestEmailVerification(actor: SessionActor): Promise<void>
+  confirmEmailVerification(token: string): Promise<void>
 }
 
 export function createAuthService(dependencies: AuthDependencies): AuthService {
@@ -181,6 +190,16 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
     }
   }
 
+  function sendVerificationEmail(to: string, token: string): Promise<void> {
+    const link = buildAppLink(dependencies.appBaseUrl, APP_LINK_PATHS.verifyEmail, token)
+
+    return dependencies.email.send({
+      to,
+      subject: 'Verify your Kelpie email address',
+      body: `Confirm this address to finish setting up your account:\n\n${link}\n\nThe link expires in 24 hours.`,
+    })
+  }
+
   return {
     /** Creates the account only. The first workspace comes from onboarding. */
     async signUp(input: SignUpInput): Promise<IssuedSession> {
@@ -192,8 +211,10 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
 
       const email = normaliseEmail(input.email)
       const passwordHash = await hashPassword(input.password)
+      const now = dependencies.now()
+      const verificationToken = newToken()
 
-      return dependencies.transaction(async ({ tx }) => {
+      const issued = await dependencies.transaction(async ({ tx }) => {
         let user: repository.UserRecord
 
         try {
@@ -215,8 +236,20 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
           throw error
         }
 
+        await repository.insertEmailVerificationToken(tx, {
+          id: dependencies.createId('emailVerificationToken'),
+          userId: user.id,
+          tokenHash: hashToken(verificationToken),
+          expiresAt: new Date(now.getTime() + EMAIL_VERIFICATION_TOKEN_LIFETIME_MS),
+        })
+
         return issueSession(tx, user, input.device, input.location)
       })
+
+      // Sent after commit, so a rolled-back signup never emails a token.
+      await sendVerificationEmail(email, verificationToken)
+
+      return issued
     },
 
     async logIn(input: LogInInput): Promise<IssuedSession> {
@@ -367,7 +400,7 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
      * Always resolves, whether or not the address is registered. Telling a
      * stranger which addresses have accounts is the whole attack.
      */
-    async requestPasswordReset(email: string, resetUrlTemplate: string): Promise<void> {
+    async requestPasswordReset(email: string): Promise<void> {
       const user = await repository.findUserByEmail(dependencies.db, normaliseEmail(email))
 
       if (user === undefined) {
@@ -384,10 +417,12 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
         expiresAt: new Date(now.getTime() + RESET_TOKEN_LIFETIME_MS),
       })
 
+      const link = buildAppLink(dependencies.appBaseUrl, APP_LINK_PATHS.passwordReset, token)
+
       await dependencies.email.send({
         to: user.email,
         subject: 'Reset your Kelpie password',
-        body: `Use this link within the hour to choose a new password:\n\n${resetUrlTemplate.replace('{token}', token)}\n\nIf you did not ask for this, ignore it.`,
+        body: `Use this link within the hour to choose a new password:\n\n${link}\n\nIf you did not ask for this, ignore it.`,
       })
     },
 
@@ -437,5 +472,43 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
         await repository.deleteOtherSessionsForUser(tx, user.id, actor.sessionId)
       })
     },
+
+    async requestEmailVerification(actor: SessionActor): Promise<void> {
+      const user = await requireUser(actor.userId)
+
+      if (user.emailVerifiedAt !== null) {
+        return
+      }
+
+      const now = dependencies.now()
+      const token = newToken()
+
+      await repository.insertEmailVerificationToken(dependencies.db, {
+        id: dependencies.createId('emailVerificationToken'),
+        userId: user.id,
+        tokenHash: hashToken(token),
+        expiresAt: new Date(now.getTime() + EMAIL_VERIFICATION_TOKEN_LIFETIME_MS),
+      })
+
+      await sendVerificationEmail(user.email, token)
+    },
+
+    async confirmEmailVerification(token: string): Promise<void> {
+      const now = dependencies.now()
+      const record = await repository.findUsableEmailVerificationToken(
+        dependencies.db,
+        hashToken(token),
+        now,
+      )
+
+      if (record === undefined) {
+        throw AppError.unauthorized('That verification link is invalid or has expired')
+      }
+
+      await dependencies.transaction(async ({ tx }) => {
+        await repository.markEmailVerificationTokenUsed(tx, record.id, now)
+        await repository.markEmailVerified(tx, record.userId, now)
+      })
+    },
   }
 }

package/src/modules/deals/repository.ts

@@ -44,6 +44,7 @@ function companyNameMatches(pattern: string): SQL {
     select 1
     from ${companies}
     where ${companies.id} = ${deals.companyId}
+      and ${companies.workspaceId} = ${deals.workspaceId}
       and ${companies.name} ilike ${pattern}
   )`
 }

package/src/modules/decisions/repository.ts

@@ -49,12 +49,12 @@ export interface DecisionFilters {
  * away, so a candidate-targeted decision matches on body and rationale only.
  */
 const NAMED_TARGET_TABLES = [
-  { table: people, id: people.id, name: people.name },
-  { table: companies, id: companies.id, name: companies.name },
-  { table: deals, id: deals.id, name: deals.name },
-  { table: opportunities, id: opportunities.id, name: opportunities.name },
-  { table: partnerships, id: partnerships.id, name: partnerships.name },
-  { table: raises, id: raises.id, name: raises.name },
+  { table: people, id: people.id, workspaceId: people.workspaceId, name: people.name },
+  { table: companies, id: companies.id, workspaceId: companies.workspaceId, name: companies.name },
+  { table: deals, id: deals.id, workspaceId: deals.workspaceId, name: deals.name },
+  { table: opportunities, id: opportunities.id, workspaceId: opportunities.workspaceId, name: opportunities.name },
+  { table: partnerships, id: partnerships.id, workspaceId: partnerships.workspaceId, name: partnerships.name },
+  { table: raises, id: raises.id, workspaceId: raises.workspaceId, name: raises.name },
 ]
 
 /**
@@ -64,10 +64,11 @@ const NAMED_TARGET_TABLES = [
  */
 function targetNameMatches(pattern: string): SQL[] {
   return NAMED_TARGET_TABLES.map(
-    ({ table, id, name }) => sql`exists (
+    ({ table, id, workspaceId, name }) => sql`exists (
       select 1
       from ${table}
       where ${id} = ${decisions.targetId}
+        and ${workspaceId} = ${decisions.workspaceId}
         and ${name} ilike ${pattern}
     )`,
   )

package/src/modules/forms/index.ts

@@ -41,6 +41,7 @@ export function createFormsModule(migrationsDirectory: string): KelpieModule {
           createId: context.createId,
           now: context.now,
         }),
+        entitlements: context.entitlements,
       })
 
       context.schema(schema, migrationsDirectory)
@@ -50,7 +51,11 @@ export function createFormsModule(migrationsDirectory: string): KelpieModule {
       })
 
       context.publicRoutes((router) => {
-        mountPublicFormRoutes(router, { db: context.db, submissions })
+        mountPublicFormRoutes(router, {
+          db: context.db,
+          submissions,
+          entitlements: context.entitlements,
+        })
       })
 
       registerFormsTools(context.mcp, service)

package/src/modules/forms/publicRoutes.ts

@@ -4,6 +4,9 @@ import { z } from 'zod'
 import type { Database } from '../../lib/database.ts'
 import { AppError } from '../../lib/errors.ts'
 import { PUBLIC_ROUTE_PREFIX, readJsonBody, requestOrigin } from '../../lib/http.ts'
+import { requireCapability } from '../../runtime/entitlements.ts'
+import type { EntitlementRegistry } from '../../runtime/entitlements.ts'
+import { moduleCapabilityName } from '../../runtime/moduleConfig.ts'
 import { embedContentSecurityPolicy, renderEmbedPage } from './embed.ts'
 import * as repository from './repository.ts'
 import type { FormSubmitService, SubmitOutcome } from './submission.ts'
@@ -28,17 +31,20 @@ export interface PublicFormRoutesDependencies {
   /** Injected so a test can pin the value the CSP and the tags share. */
   readonly generateNonce?: () => string
   readonly submissions: FormSubmitService
+  /** The embed of a form in a workspace that has turned the module off is refused. */
+  readonly entitlements: EntitlementRegistry
 }
 
 function submitResponse(outcome: SubmitOutcome): Record<string, unknown> {
+  // The upserted record ids stay off this response on purpose. The caller is an
+  // unauthenticated website, and a Kelpie id is a ULID whose timestamp would tell
+  // that caller whether the person or company it named was already in the CRM.
+  // The service still computes them for its own events and activities; they are
+  // simply not on the wire here.
   return {
     id: outcome.submissionId,
     form_id: outcome.formId,
     submitted_at: outcome.submittedAt.toISOString(),
-    person_id: outcome.personId,
-    company_id: outcome.companyId,
-    position_id: outcome.positionId,
-    deal_id: outcome.dealId,
     // Echoed so an embed can render the confirmation without a second request
     // for a form definition it has no other reason to fetch.
     thank_you_message: outcome.thankYouMessage,
@@ -73,6 +79,10 @@ export function mountPublicFormRoutes(
       throw AppError.notFound('Form not found')
     }
 
+    // Ungated by the runtime, like the submit route: a workspace with the forms
+    // module off does not serve its embed either.
+    await requireCapability(dependencies.entitlements, form.workspaceId, moduleCapabilityName('forms'))
+
     const nonce = generateNonce()
     const page = renderEmbedPage({
       form,

package/src/modules/forms/submission.ts

@@ -1,6 +1,9 @@
 import type { Database } from '../../lib/database.ts'
 import { AppError } from '../../lib/errors.ts'
 import type { IdFactory } from '../../lib/ids.ts'
+import { requireCapability } from '../../runtime/entitlements.ts'
+import type { EntitlementRegistry } from '../../runtime/entitlements.ts'
+import { moduleCapabilityName } from '../../runtime/moduleConfig.ts'
 import type { BufferedEvents, Transaction, TransactionScope } from '../../runtime/transaction.ts'
 import type { ActivityRecorder, SystemActor } from '../activities/recorder.ts'
 import { describeCreationVia, describeFormSubmission } from '../activities/wording.ts'
@@ -85,6 +88,8 @@ export interface SubmissionDependencies {
   readonly createId: IdFactory
   readonly now: () => Date
   readonly recordActivity: ActivityRecorder
+  /** A submit into a workspace that has turned the forms module off is refused. */
+  readonly entitlements: EntitlementRegistry
 }
 
 /** What the submit created or matched. Each id is null when the rule did not apply. */
@@ -394,6 +399,11 @@ export function createFormSubmitService(dependencies: SubmissionDependencies): F
       throw AppError.notFound('Form not found')
     }
 
+    // The public surface is ungated by the runtime (`runtime/registry.ts` gates
+    // only credentialled routes), so a workspace that has turned the forms
+    // module off is refused here, the same 403 the REST surface gives.
+    await requireCapability(dependencies.entitlements, form.workspaceId, moduleCapabilityName('forms'))
+
     if (form.status === 'paused') {
       throw AppError.conflict('This form is not accepting submissions')
     }

package/src/modules/opportunities/repository.ts

@@ -43,6 +43,7 @@ function companyNameMatches(pattern: string): SQL {
     select 1
     from ${companies}
     where ${companies.id} = ${opportunities.companyId}
+      and ${companies.workspaceId} = ${opportunities.workspaceId}
       and ${companies.name} ilike ${pattern}
   )`
 }

package/src/modules/partnerships/repository.ts

@@ -46,6 +46,7 @@ function companyNameMatches(pattern: string): SQL {
     select 1
     from ${companies}
     where ${companies.id} = ${partnerships.companyId}
+      and ${companies.workspaceId} = ${partnerships.workspaceId}
       and ${companies.name} ilike ${pattern}
   )`
 }

package/src/modules/raises/repository.ts

@@ -47,6 +47,7 @@ function companyNameMatches(pattern: string): SQL {
     select 1
     from ${companies}
     where ${companies.id} = ${raises.companyId}
+      and ${companies.workspaceId} = ${raises.workspaceId}
       and ${companies.name} ilike ${pattern}
   )`
 }