@kelpie/server 0.10.0 → 0.12.0

package/src/modules/auth/index.ts

@@ -5,6 +5,7 @@ import type { KelpieModule } from '../../runtime/module.ts'
 import { mountAuthRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createAuthService } from './service.ts'
+import { describeClient, writeSessionCookie } from './session.ts'
 
 /**
  * Accounts, sessions, and password recovery.
@@ -38,6 +39,11 @@ export function createAuthModule(migrationsDirectory: string): KelpieModule {
         appBaseUrl,
       })
 
+      // `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.
+      const cookie = { secure: NODE_ENV !== 'development' }
+
       context.schema(schema, migrationsDirectory)
 
       context.routes((router) => {
@@ -45,11 +51,26 @@ export function createAuthModule(migrationsDirectory: string): KelpieModule {
           db: context.db,
           now: context.now,
           service,
-          // `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: NODE_ENV !== 'development' },
+          cookie,
+        })
+      })
+
+      // How a module signs a browser in. It verifies an identity its own way
+      // and hands it here; everything from the cookie onwards is what a
+      // password sign-in does, through the same helper with the same flags.
+      context.provideExternalSignIn(async (honoContext, identity) => {
+        const issued = await service.completeExternalSignIn({
+          ...identity,
+          ...describeClient(honoContext),
         })
+
+        writeSessionCookie(honoContext, issued.sessionToken, cookie)
+
+        return {
+          account: issued.account,
+          created: issued.created,
+          activeWorkspaceId: issued.activeWorkspaceId,
+        }
       })
 
       return Promise.resolve()

package/src/modules/auth/repository.ts

@@ -48,10 +48,11 @@ export async function insertUser(db: Queryable, values: typeof users.$inferInser
   return created
 }
 
+/** `null` clears the password, leaving the account reachable only through a module or a reset. */
 export async function updateUserPassword(
   db: Queryable,
   userId: string,
-  passwordHash: string,
+  passwordHash: string | null,
   now: Date,
 ): Promise<void> {
   await db

package/src/modules/auth/routes.ts

@@ -11,7 +11,7 @@ import { resolveActorFrom } from './credentials.ts'
 import type { CredentialDependencies } from './credentials.ts'
 import type { PreferenceValues } from './preferences.ts'
 import type { AccountView, AuthService, IssuedSession, SessionView } from './service.ts'
-import { clearSessionCookie, writeSessionCookie } from './session.ts'
+import { clearSessionCookie, describeClient, writeSessionCookie } from './session.ts'
 import type { SessionCookieOptions } from './session.ts'
 
 /**
@@ -108,13 +108,6 @@ async function readBody<T>(context: Context, schema: z.ZodType<T>): Promise<T> {
   return parsed.data
 }
 
-/** The device and location shown on the Security page come from the request itself. */
-function describeClient(context: Context): { device?: string; location?: string } {
-  const userAgent = context.req.header('User-Agent')
-
-  return userAgent === undefined ? {} : { device: userAgent }
-}
-
 function accountResponse(issued: IssuedSession): Record<string, unknown> {
   return {
     account: accountBody(issued.account),
@@ -149,6 +142,7 @@ function sessionResponse(session: SessionView): Record<string, unknown> {
     location: session.location,
     last_active_at: session.lastActiveAt.toISOString(),
     current: session.current,
+    signed_in_via: session.signedInVia,
   }
 }
 

package/src/modules/auth/schema.ts

@@ -18,7 +18,12 @@ export const users = pgTable('users', {
   id: primaryId(),
   email: citext('email').notNull().unique(),
   name: text('name').notNull(),
-  passwordHash: text('password_hash').notNull(),
+  /**
+   * Null for an account that has only ever signed in through an identity
+   * module. Password sign-in is refused while it is null; a password is set
+   * through the reset flow, whose emailed link proves control of the address.
+   */
+  passwordHash: text('password_hash'),
   /** Null until the address is verified, either by confirming a token or by accepting a workspace invite. */
   emailVerifiedAt: moment('email_verified_at'),
   createdAt: createdAt(),
@@ -34,6 +39,12 @@ export const sessions = pgTable('sessions', {
   tokenHash: text('token_hash').notNull().unique(),
   device: text('device'),
   location: text('location'),
+  /**
+   * Which module completed this sign-in (`sign-in:google`), null for a password
+   * one. The Security page lists sessions, and a person should be able to tell
+   * the two apart.
+   */
+  signedInVia: text('signed_in_via'),
   lastActiveAt: moment('last_active_at').notNull().defaultNow(),
   expiresAt: moment('expires_at').notNull(),
   createdAt: createdAt(),

package/src/modules/auth/service.ts

@@ -1,12 +1,13 @@
 import { APP_LINK_PATHS, buildAppLink } from '../../lib/appUrl.ts'
 import type { EmailSender } from '../../lib/email.ts'
 import { renderEmail } from '../../lib/emailContent.ts'
-import { AppError } from '../../lib/errors.ts'
+import { AppError, ExternalSignInError } from '../../lib/errors.ts'
 import type { IdFactory } from '../../lib/ids.ts'
 import { UNIQUE_VIOLATION, postgresErrorCode } from '../../lib/database.ts'
 import type { Database } from '../../lib/database.ts'
 import { MINIMUM_PASSWORD_LENGTH, hashPassword, verifyPassword } from '../../lib/passwords.ts'
 import { generateToken, hashToken } from '../../lib/tokens.ts'
+import type { VerifiedIdentity } from '../../runtime/module.ts'
 import type { TransactionScope } from '../../runtime/transaction.ts'
 import type { SessionActor } from './actor.ts'
 import { DEFAULT_PREFERENCES, applyPreferenceChanges } from './preferences.ts'
@@ -54,12 +55,19 @@ export interface IssuedSession {
   readonly activeWorkspaceId: string | null
 }
 
+/** What `completeExternalSignIn` returns: an issued session plus whether it made the account. */
+export interface ExternalIssuedSession extends IssuedSession {
+  readonly created: boolean
+}
+
 export interface SessionView {
   readonly id: string
   readonly device: string | null
   readonly location: string | null
   readonly lastActiveAt: Date
   readonly current: boolean
+  /** The module that signed this session in, or null for a password sign-in. */
+  readonly signedInVia: string | null
 }
 
 export interface SignUpInput {
@@ -85,6 +93,12 @@ export interface LogInInput {
   readonly location?: string
 }
 
+/** A `VerifiedIdentity` plus what the request itself says about the client. */
+export interface ExternalSignInInput extends VerifiedIdentity {
+  readonly device?: string
+  readonly location?: string
+}
+
 function toAccountView(user: repository.UserRecord): AccountView {
   return { id: user.id, email: user.email, name: user.name, emailVerified: user.emailVerifiedAt !== null }
 }
@@ -105,6 +119,16 @@ function normaliseEmail(email: string): string {
   return email.trim().toLowerCase()
 }
 
+/**
+ * The name to use when a provider sends none. `users.name` is not nullable and
+ * an address is the only other thing an identity is guaranteed to carry.
+ */
+function localPartOf(email: string): string {
+  const [local] = email.split('@')
+
+  return local === undefined || local.length === 0 ? email : local
+}
+
 /**
  * Rejects a field that is only whitespace.
  *
@@ -128,6 +152,12 @@ export interface AuthService {
   /** Creates the account only. The first workspace comes from onboarding. */
   signUp(input: SignUpInput): Promise<IssuedSession>
   logIn(input: LogInInput): Promise<IssuedSession>
+  /**
+   * Signs in an identity a module verified elsewhere, provisioning the account
+   * when the module asked for it. Never sends a verification email: the
+   * provider already proved control of the address.
+   */
+  completeExternalSignIn(input: ExternalSignInInput): Promise<ExternalIssuedSession>
   logOut(actor: SessionActor): Promise<void>
   getAccount(actor: SessionActor): Promise<AccountView>
   updateAccount(actor: SessionActor, changes: UpdateAccountChanges): Promise<AccountView>
@@ -167,6 +197,8 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
     user: repository.UserRecord,
     device: string | undefined,
     location: string | undefined,
+    /** The module that verified the identity, or null for a password sign-in. */
+    signedInVia: string | null = null,
   ): Promise<IssuedSession> {
     const now = dependencies.now()
     const token = newToken()
@@ -180,6 +212,7 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
       tokenHash: hashToken(token),
       device: device ?? null,
       location: location ?? null,
+      signedInVia,
       lastActiveAt: now,
       expiresAt,
     })
@@ -269,17 +302,113 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
     async logIn(input: LogInInput): Promise<IssuedSession> {
       const user = await repository.findUserByEmail(dependencies.db, normaliseEmail(input.email))
 
-      // Hash a throwaway password when the user is unknown, so a missing account
-      // and a wrong password take the same time to answer.
+      // Hash a throwaway password when the account is unknown or has no
+      // password, so all three cases take the same time to answer.
       const storedHash = user?.passwordHash ?? (await hashPassword('not-a-real-password-placeholder'))
-
-      if (!(await verifyPassword(storedHash, input.password)) || user === undefined) {
+      // Always run the verify, even when the hash is the placeholder: skipping
+      // it would make a passwordless account answer faster than a wrong one.
+      const matches = await verifyPassword(storedHash, input.password)
+
+      // The null check is the guard, not the placeholder hash. Without it,
+      // whoever guessed the placeholder string would sign in to every account
+      // that has no password.
+      if (user === undefined || user.passwordHash === null || !matches) {
         throw AppError.unauthorized('Email or password is incorrect')
       }
 
       return dependencies.transaction(({ tx }) => issueSession(tx, user, input.device, input.location))
     },
 
+    /**
+     * Signs in an identity a module already verified.
+     *
+     * Core does not redo the verification and never learns the protocol. What
+     * it owns is everything downstream: finding or provisioning the account,
+     * issuing the session, and recording which module vouched for it.
+     */
+    async completeExternalSignIn(input: ExternalSignInInput): Promise<ExternalIssuedSession> {
+      // An unverified address is not an identity. A provider that does not say
+      // it checked is treated as not having checked.
+      if (!input.emailVerified) {
+        throw new ExternalSignInError('email_unverified')
+      }
+
+      const email = requireText(normaliseEmail(input.email), 'email')
+      const name = requireText(input.name ?? localPartOf(email), 'name')
+      const now = dependencies.now()
+
+      const link = async (
+        tx: repository.Queryable,
+        user: repository.UserRecord,
+      ): Promise<ExternalIssuedSession> => {
+        // Signing in through a provider on an account whose address was never
+        // confirmed is the pre-registration takeover case: somebody registered
+        // this address with a password and never proved they own it. The
+        // provider just proved the opposite. Drop that password and every
+        // session it opened; the real owner sets a new one through a reset.
+        if (user.emailVerifiedAt === null) {
+          await repository.updateUserPassword(tx, user.id, null, now)
+          await repository.deleteAllSessionsForUser(tx, user.id)
+        }
+
+        // The provider proved control of the address, which is the same thing
+        // accepting an invite proves.
+        await repository.markEmailVerified(tx, user.id, now)
+
+        const issued = await issueSession(
+          tx,
+          { ...user, emailVerifiedAt: user.emailVerifiedAt ?? now },
+          input.device,
+          input.location,
+          input.verifiedBy,
+        )
+
+        return { ...issued, created: false }
+      }
+
+      const existing = await repository.findUserByEmail(dependencies.db, email)
+
+      if (existing !== undefined) {
+        return dependencies.transaction(({ tx }) => link(tx, existing))
+      }
+
+      if (input.provision === 'refuse') {
+        throw new ExternalSignInError('unknown_identity')
+      }
+
+      return dependencies.transaction(async ({ tx }) => {
+        let user: repository.UserRecord
+
+        try {
+          user = await repository.insertUser(tx, {
+            id: dependencies.createId('user'),
+            email,
+            name,
+            passwordHash: null,
+            emailVerifiedAt: now,
+          })
+        } catch (error: unknown) {
+          if (postgresErrorCode(error) !== UNIQUE_VIOLATION) {
+            throw error
+          }
+
+          // Two first sign-ins for the same address at once. The other one won;
+          // this is now an ordinary link.
+          const raced = await repository.findUserByEmail(tx, email)
+
+          if (raced === undefined) {
+            throw error
+          }
+
+          return link(tx, raced)
+        }
+
+        const issued = await issueSession(tx, user, input.device, input.location, input.verifiedBy)
+
+        return { ...issued, created: true }
+      })
+    },
+
     async logOut(actor: SessionActor): Promise<void> {
       await repository.deleteSession(dependencies.db, actor.userId, actor.sessionId)
     },
@@ -308,9 +437,12 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
           : { email: requireText(normaliseEmail(changes.email), 'email') }),
       }
 
+      // A passwordless account cannot prove itself this way. It sets a password
+      // through the reset flow first, which is the same bar this check is.
       if (
         changes.email !== undefined &&
         (changes.currentPassword === undefined ||
+          user.passwordHash === null ||
           !(await verifyPassword(user.passwordHash, changes.currentPassword)))
       ) {
         throw AppError.unauthorized('Current password is incorrect')
@@ -405,6 +537,7 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
         location: record.location,
         lastActiveAt: record.lastActiveAt,
         current: record.id === actor.sessionId,
+        signedInVia: record.signedInVia,
       }))
     },
 
@@ -494,7 +627,11 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
 
       const user = await repository.findUserById(dependencies.db, actor.userId)
 
-      if (user === undefined || !(await verifyPassword(user.passwordHash, currentPassword))) {
+      if (
+        user === undefined ||
+        user.passwordHash === null ||
+        !(await verifyPassword(user.passwordHash, currentPassword))
+      ) {
         throw AppError.unauthorized('Current password is incorrect')
       }
 

package/src/modules/auth/session.ts

@@ -11,6 +11,20 @@ import type { Context } from 'hono'
 
 export const SESSION_COOKIE = 'kelpie_session'
 
+/**
+ * The device and location shown on the Security page come from the request
+ * itself.
+ *
+ * Here rather than in `routes.ts` because the external sign-in handler needs
+ * the same description, and a session created by a module should look the same
+ * on that page as one created by the login form.
+ */
+export function describeClient(context: Context): { device?: string; location?: string } {
+  const userAgent = context.req.header('User-Agent')
+
+  return userAgent === undefined ? {} : { device: userAgent }
+}
+
 /** Thirty days, matching the session row's expiry. */
 const COOKIE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60
 

package/src/modules/consent-purposes/index.ts

@@ -10,7 +10,7 @@ import { registerConsentPurposesTools } from './tools.ts'
  * Consent purposes: the workspace catalog every capture site names.
  *
  * Structural because Person consent rows carry `purpose_id`, and forms /
- * lists / imports each reference one; a disabled module would leave those
+ * forms / imports each reference one; a disabled module would leave those
  * references without a definition to resolve.
  *
  * Registers before people, forms, lists, and import-export so their `_fk`

package/src/modules/consent-purposes/schema.ts

@@ -7,9 +7,9 @@ import { workspaces } from '../workspace/schema.ts'
 /**
  * Workspace-defined consent purposes.
  *
- * Every capture site — a form's consent field, a list, an import job, the
- * manual override on a Person — names one of these. `slug` is set at create
- * and immutable after: a rename would strand every form/list/import that
+ * Every capture site — a form's consent field, an import job, the manual
+ * override on a Person — names one of these. `slug` is set at create and
+ * immutable after: a rename would strand every form/import that names it and
  * names it and every `person_consents` row that carries it (identified by
  * the purpose id). The strict PATCH body naturally refuses either as a `422`.
  *

package/src/modules/consent-purposes/service.ts

@@ -20,7 +20,6 @@ import type { Transaction, TransactionScope } from '../../runtime/transaction.ts
 import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
 import { formFields } from '../forms/schema.ts'
-import { lists } from '../lists/schema.ts'
 import { roleAllows } from '../workspace/roles.ts'
 import { CONSENT_PURPOSES_LIMIT } from './capabilities.ts'
 import './events.ts'
@@ -39,7 +38,7 @@ import type {
  *
  * Reads are open to any workspace member — every capture site needs to list
  * them to render its purpose picker. Writes need the admin role: a purpose
- * change touches every form, list, and import job that names it, and it is
+ * change touches every form and import job that names it, and it is
  * team-wide config rather than a per-user preference.
  */
 
@@ -143,17 +142,16 @@ function validateDefaultStatus(status: string): void {
 }
 
 /**
- * A purpose still named by a form's consent field or a list's
- * `consent_purpose_id` cannot be deleted. Counted here so the 409 lists both
- * types; the FK on either side would refuse the delete on its own but only
- * name one.
+ * A purpose still named by a form's consent field cannot be deleted. Counted
+ * here so the 409 names the referencing type; the FK on either side would
+ * refuse the delete on its own but only name one.
  */
 async function referencingTypes(
   db: Database | Transaction,
   workspaceId: string,
   id: string,
 ): Promise<readonly string[]> {
-  const [fieldRow, listRow] = await Promise.all([
+  const [fieldRow] = await Promise.all([
     db
       .select({ count: sql<number>`count(*)::int` })
       .from(formFields)
@@ -165,19 +163,12 @@ async function referencingTypes(
           sql`${id} = ANY(${formFields.consentPurposeIds})`,
         ),
       ),
-    db
-      .select({ count: sql<number>`count(*)::int` })
-      .from(lists)
-      .where(and(eq(lists.workspaceId, workspaceId), eq(lists.consentPurposeId, id))),
   ])
 
   const referencing: string[] = []
   if (Number(fieldRow[0]?.count ?? 0) > 0) {
     referencing.push('form_field')
   }
-  if (Number(listRow[0]?.count ?? 0) > 0) {
-    referencing.push('list')
-  }
   return referencing
 }
 
@@ -390,7 +381,7 @@ export function createConsentPurposesService(
           const referencing = await referencingTypes(tx, workspaceId, id)
           if (referencing.length > 0) {
             throw AppError.conflict(
-              'Remove this purpose from every form and list that names it before deleting it',
+              'Remove this purpose from every form field that names it before deleting it',
               referencing.map((type) => ({ field: type, message: 'still references this purpose' })),
             )
           }
@@ -400,7 +391,7 @@ export function createConsentPurposesService(
           } catch (error: unknown) {
             if (postgresErrorCode(error) === FOREIGN_KEY_VIOLATION) {
               throw AppError.conflict(
-                'Remove this purpose from every form and list that names it before deleting it',
+                'Remove this purpose from every form field that names it before deleting it',
                 [{ field: 'id', message: 'still referenced' }],
               )
             }

package/src/modules/consent-purposes/starters.ts

@@ -5,7 +5,7 @@ import type { ConsentPurposeStatus } from '@kelpie/schemas'
  * owner may rename, reorder, or delete them, and add any others they need.
  *
  * Both starters default to `unknown` — silence about a person's wishes is not
- * a grant, and every capture site (forms, lists, imports, manual override)
+ * a grant, and every capture site (forms, imports, manual override)
  * writes an explicit `person_consents` row when consent is actually given.
  */
 

package/src/modules/consent-purposes/tools.ts

@@ -31,7 +31,7 @@ export function registerConsentPurposesTools(
     subject: 'consent purpose',
     about:
       'A workspace-defined consent purpose. Read these before writing a person ' +
-      'consent or setting a form/list/import purpose_id.',
+      'consent or setting a form/import purpose_id.',
     service,
     render: consentPurposeResponse,
     listArgs,

package/src/modules/conversions/clearPointers.ts

@@ -0,0 +1,81 @@
+import { and, eq } from 'drizzle-orm'
+import type { PipelineKind } from '@kelpie/schemas'
+
+import type { Queryable } from '../../runtime/transaction.ts'
+import { deals } from '../deals/schema.ts'
+import { enquiries } from '../enquiries/schema.ts'
+import { opportunities } from '../opportunities/schema.ts'
+import { partnerships } from '../partnerships/schema.ts'
+import { raises } from '../raises/schema.ts'
+
+/**
+ * Clears `converted_target_*` on every pipeline record that pointed at a target
+ * being deleted. Enquiries also lose `converted_deal_id` when the target is a
+ * deal, matching the legacy FK `on delete set null` behaviour and allowing a
+ * fresh conversion once the created record is gone.
+ */
+export async function clearConversionPointersToTarget(
+  tx: Queryable,
+  workspaceId: string,
+  targetKind: PipelineKind,
+  targetId: string,
+): Promise<void> {
+  const match = and(
+    eq(deals.workspaceId, workspaceId),
+    eq(deals.convertedTargetType, targetKind),
+    eq(deals.convertedTargetId, targetId),
+  )
+
+  await tx
+    .update(enquiries)
+    .set({
+      convertedTargetType: null,
+      convertedTargetId: null,
+      ...(targetKind === 'deal' ? { convertedDealId: null } : {}),
+    })
+    .where(
+      and(
+        eq(enquiries.workspaceId, workspaceId),
+        eq(enquiries.convertedTargetType, targetKind),
+        eq(enquiries.convertedTargetId, targetId),
+      ),
+    )
+
+  await tx
+    .update(deals)
+    .set({ convertedTargetType: null, convertedTargetId: null })
+    .where(match)
+
+  await tx
+    .update(opportunities)
+    .set({ convertedTargetType: null, convertedTargetId: null })
+    .where(
+      and(
+        eq(opportunities.workspaceId, workspaceId),
+        eq(opportunities.convertedTargetType, targetKind),
+        eq(opportunities.convertedTargetId, targetId),
+      ),
+    )
+
+  await tx
+    .update(raises)
+    .set({ convertedTargetType: null, convertedTargetId: null })
+    .where(
+      and(
+        eq(raises.workspaceId, workspaceId),
+        eq(raises.convertedTargetType, targetKind),
+        eq(raises.convertedTargetId, targetId),
+      ),
+    )
+
+  await tx
+    .update(partnerships)
+    .set({ convertedTargetType: null, convertedTargetId: null })
+    .where(
+      and(
+        eq(partnerships.workspaceId, workspaceId),
+        eq(partnerships.convertedTargetType, targetKind),
+        eq(partnerships.convertedTargetId, targetId),
+      ),
+    )
+}

package/src/modules/conversions/factory.ts

@@ -0,0 +1,20 @@
+import type { ModuleContext } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { createCustomFieldValues } from '../custom-fields/index.ts'
+import { createConversionsService } from './service.ts'
+import type { ConversionsService } from './service.ts'
+
+/** Build the shared conversion service from a module registration context. */
+export function createConversionsFromContext(context: ModuleContext): ConversionsService {
+  return createConversionsService({
+    db: context.db,
+    transaction: context.transaction,
+    createId: context.createId,
+    now: context.now,
+    recordActivity: createActivityRecorder({
+      createId: context.createId,
+      now: context.now,
+    }),
+    customFields: createCustomFieldValues({ db: context.db }),
+  })
+}