@kelpie/server 0.11.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/runtime/module.ts

@@ -1,4 +1,4 @@
-import type { Handler, Hono, MiddlewareHandler } from 'hono'
+import type { Context, Handler, Hono, MiddlewareHandler } from 'hono'
 import type { ZodType } from 'zod'
 
 import type { Actor } from '../lib/actor.ts'
@@ -58,6 +58,53 @@ export interface McpToolRegistry {
   tool<Input>(definition: McpToolDefinition<Input>): void
 }
 
+/**
+ * An identity a module verified somewhere else, handed back for core to sign in.
+ *
+ * Core never learns what OIDC or SAML is. Verification is the module's job and
+ * core does not redo it; core's job is that everything downstream of the cookie
+ * is identical to a password sign-in.
+ */
+export interface VerifiedIdentity {
+  readonly email: string
+  /** Core refuses the identity when false, rather than assuming the module checked. */
+  readonly emailVerified: boolean
+  /** The provider's display name, when it has one. The local part of the address is used otherwise. */
+  readonly name: string | null
+  /** Who verified it, recorded on the session: the module id, optionally suffixed (`sign-in:google`). */
+  readonly verifiedBy: string
+  /**
+   * What to do with an address core has never seen. The policy is the module's,
+   * because only it knows whether its provider vouches for strangers; executing
+   * it is core's.
+   */
+  readonly provision: 'create' | 'refuse'
+}
+
+/** The account a completed sign-in belongs to. */
+export interface CompletedSignInAccount {
+  readonly id: string
+  readonly email: string
+  readonly name: string
+  readonly emailVerified: boolean
+}
+
+export interface CompletedSignIn {
+  readonly account: CompletedSignInAccount
+  /** True when this sign-in provisioned the account rather than finding it. */
+  readonly created: boolean
+  readonly activeWorkspaceId: string | null
+}
+
+/**
+ * Completes a sign-in. Takes the Hono context because writing the session
+ * cookie on it is the point.
+ */
+export type ExternalSignInHandler = (
+  context: Context,
+  identity: VerifiedIdentity,
+) => Promise<CompletedSignIn>
+
 /**
  * What a module gets to build with, beyond its own contributions.
  *
@@ -119,6 +166,28 @@ export interface ModuleContext extends ModuleServices {
    * delegates to the provider `email.provider` picked.
    */
   readonly email: EmailSender
+  /**
+   * Installs the one implementation of external sign-in. Core's `auth` module
+   * calls this; a second caller fails boot.
+   *
+   * The same shape as `provideEmailSender`: a capability only one module owns,
+   * reached by every module through a proxy, so registration order does not
+   * matter to a consumer.
+   */
+  provideExternalSignIn(handler: ExternalSignInHandler): void
+  /**
+   * Completes a sign-in for an identity this module already verified: finds or
+   * provisions the account, issues a session, and writes the session cookie on
+   * `context`.
+   *
+   * The alternative is a module writing core's `sessions` table itself, which
+   * ties it to core's token hashing, cookie flags and expiry with nothing
+   * keeping the two in step (`modules.md`).
+   *
+   * @throws ExternalSignInError when the identity is unverified, or unknown and
+   *   the module asked for `provision: 'refuse'`.
+   */
+  completeExternalSignIn(context: Context, identity: VerifiedIdentity): Promise<CompletedSignIn>
   /**
    * Registers routes that mount under `/v1/public`, take no credentials, and
    * answer cross-origin requests from any site.

package/src/runtime/registry.ts

@@ -13,12 +13,15 @@ import type { EntitlementRegistry } from './entitlements.ts'
 import { createEventBus } from './events.ts'
 import type { EventBus } from './events.ts'
 import type {
+  CompletedSignIn,
+  ExternalSignInHandler,
   KelpieModule,
   McpTool,
   ModuleCatalogEntry,
   ModuleContext,
   ModuleServices,
   SchemaContribution,
+  VerifiedIdentity,
 } from './module.ts'
 import { createModuleConfigProvider, moduleCapabilityName, validateModuleConfig } from './moduleConfig.ts'
 import { ModuleBootError, orderModules } from './order.ts'
@@ -180,6 +183,46 @@ class EmailSenderProxy implements EmailSender {
   }
 }
 
+/**
+ * Completes a sign-in for an identity a module verified elsewhere.
+ *
+ * Same shape as `EmailSenderProxy`, and for the same reason: one module owns
+ * the implementation, every module reaches it through this object, and a
+ * consumer captures the proxy at register time but only calls it at request
+ * time, so registration order does not matter.
+ *
+ * Exactly one installer, unlike email's named registry: there is one `users`
+ * table and one session cookie, so "which implementation" is never a question
+ * an assembly should have to answer.
+ */
+class ExternalSignInProxy {
+  private target: ExternalSignInHandler | undefined = undefined
+  private installedBy: string | undefined = undefined
+
+  install(moduleId: string, handler: ExternalSignInHandler): void {
+    if (this.installedBy !== undefined) {
+      throw new ModuleBootError([
+        `module "${moduleId}" provides external sign-in, but module "${this.installedBy}" already did`,
+      ])
+    }
+
+    this.target = handler
+    this.installedBy = moduleId
+  }
+
+  complete(context: Context, identity: VerifiedIdentity): Promise<CompletedSignIn> {
+    if (this.target === undefined) {
+      return Promise.reject(
+        new Error(
+          'external sign-in used before a module installed it. Is the auth module in the assembly?',
+        ),
+      )
+    }
+
+    return this.target(context, identity)
+  }
+}
+
 /**
  * The name the runtime uses for its built-in log sender. Reserved: a module
  * that tries to register under this name fails boot.
@@ -204,11 +247,20 @@ function createModuleContext(
   moduleCatalog: readonly ModuleCatalogEntry[],
   emailProxy: EmailSenderProxy,
   providers: Map<string, RegisteredProvider>,
+  externalSignIn: ExternalSignInProxy,
 ): ModuleContext {
   return {
     ...options.services,
     email: emailProxy,
 
+    provideExternalSignIn(handler) {
+      externalSignIn.install(module.id, handler)
+    },
+
+    completeExternalSignIn(context, identity) {
+      return externalSignIn.complete(context, identity)
+    },
+
     provideEmailSender(name, build) {
       if (name === LOG_PROVIDER_NAME) {
         throw new ModuleBootError([
@@ -348,6 +400,7 @@ export async function registerModules(options: ModuleRuntimeOptions): Promise<Mo
   const entitlements = options.entitlements ?? createEntitlementRegistry()
   const emailProxy = new EmailSenderProxy()
   const emailProviders = new Map<string, RegisteredProvider>()
+  const externalSignIn = new ExternalSignInProxy()
 
   // The built-in log provider is always available, no module required. Named
   // 'log' in kelpie.config.ts's email.provider picks this one. Built eagerly
@@ -429,6 +482,7 @@ export async function registerModules(options: ModuleRuntimeOptions): Promise<Mo
       moduleCatalog,
       emailProxy,
       emailProviders,
+      externalSignIn,
     )
 
     try {