@kelpie/server 0.1.0

package/src/modules/auth/credentials.ts

@@ -0,0 +1,153 @@
+import { getCookie } from 'hono/cookie'
+import type { Context } from 'hono'
+
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import { hashToken } from '../../lib/tokens.ts'
+import * as apiKeyRepository from '../api-keys/repository.ts'
+import { readBearerToken } from '../api-keys/keys.ts'
+import { parseMemberRole } from '../workspace/roles.ts'
+import type { MemberRole } from '../workspace/roles.ts'
+import type { Actor } from './actor.ts'
+import * as repository from './repository.ts'
+import { SESSION_COOKIE } from './session.ts'
+
+/**
+ * Turns credentials into an `Actor`. Two kinds are accepted, and `api.md` says
+ * they must behave identically once resolved: same endpoints, same shapes, same
+ * errors.
+ *
+ * A bearer key wins over a cookie. A client sending both is being explicit about
+ * which identity it wants.
+ */
+
+/**
+ * A workspace key acts with admin authority. It is created by an admin and
+ * belongs to the workspace rather than a person, so there is no member row to
+ * read a role from. Owner-only actions stay out of reach.
+ */
+const WORKSPACE_KEY_ROLE: MemberRole = 'admin'
+
+/** Writing `last_used_at` on every request would double the write load for no gain. */
+const LAST_USED_RESOLUTION_MS = 60_000
+
+export interface CredentialDependencies {
+  readonly db: Database
+  readonly now: () => Date
+}
+
+function roleFromMembership(role: string): MemberRole {
+  const parsed = parseMemberRole(role)
+
+  if (parsed === undefined) {
+    throw new Error(`workspace_members.role holds "${role}", which its check constraint forbids`)
+  }
+
+  return parsed
+}
+
+async function resolveSessionActor(
+  dependencies: CredentialDependencies,
+  token: string,
+): Promise<Actor> {
+  const session = await repository.findLiveSessionByTokenHash(
+    dependencies.db,
+    hashToken(token),
+    dependencies.now(),
+  )
+
+  if (session === undefined) {
+    throw AppError.unauthorized('Your session has expired')
+  }
+
+  const membership =
+    session.activeWorkspaceId === null
+      ? undefined
+      : await repository.findMembership(dependencies.db, session.activeWorkspaceId, session.userId)
+
+  // A workspace the user has been removed from resolves to no workspace rather
+  // than an error: losing one must not lock the account out of the product.
+  return {
+    kind: 'session',
+    userId: session.userId,
+    sessionId: session.id,
+    workspaceId: membership?.workspaceId ?? null,
+    role: membership === undefined ? null : roleFromMembership(membership.role),
+    memberId: membership?.id ?? null,
+  }
+}
+
+async function resolveApiKeyActor(
+  dependencies: CredentialDependencies,
+  secret: string,
+): Promise<Actor> {
+  const record = await apiKeyRepository.findBySecretHash(dependencies.db, hashToken(secret))
+
+  if (record === undefined) {
+    throw AppError.unauthorized('That API key is not valid')
+  }
+
+  const now = dependencies.now()
+
+  if (record.lastUsedAt === null || now.getTime() - record.lastUsedAt.getTime() > LAST_USED_RESOLUTION_MS) {
+    await apiKeyRepository.touchLastUsed(dependencies.db, record.id, now)
+  }
+
+  if (record.userId === null) {
+    return {
+      kind: 'api_key',
+      apiKeyId: record.id,
+      userId: null,
+      workspaceId: record.workspaceId,
+      role: WORKSPACE_KEY_ROLE,
+      memberId: null,
+    }
+  }
+
+  const membership = await repository.findMembership(dependencies.db, record.workspaceId, record.userId)
+
+  // A personal key acts as its user. If they are no longer a member, it acts as
+  // nobody, so the key stops working rather than keeping stale access.
+  if (membership === undefined) {
+    throw AppError.unauthorized('That API key is not valid')
+  }
+
+  return {
+    kind: 'api_key',
+    apiKeyId: record.id,
+    userId: record.userId,
+    workspaceId: record.workspaceId,
+    role: roleFromMembership(membership.role),
+    memberId: membership.id,
+  }
+}
+
+/**
+ * @throws AppError 401 when no credential is present, or the one presented is
+ *   unknown or expired.
+ */
+export async function resolveActor(
+  dependencies: CredentialDependencies,
+  credentials: { readonly bearer?: string | undefined; readonly cookie?: string | undefined },
+): Promise<Actor> {
+  if (credentials.bearer !== undefined && credentials.bearer.length > 0) {
+    return resolveApiKeyActor(dependencies, credentials.bearer)
+  }
+
+  if (credentials.cookie !== undefined && credentials.cookie.length > 0) {
+    return resolveSessionActor(dependencies, credentials.cookie)
+  }
+
+  throw AppError.unauthorized('Sign in or present an API key to continue')
+}
+
+/** Reads both credential carriers off a request. */
+export function resolveActorFrom(
+  dependencies: CredentialDependencies,
+  context: Context,
+): Promise<Actor> {
+  return resolveActor(dependencies, {
+    bearer: readBearerToken(context.req.header('Authorization')),
+    cookie: getCookie(context, SESSION_COOKIE),
+  })
+}

package/src/modules/auth/index.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+
+import type { KelpieModule } from '../../runtime/module.ts'
+import { mountAuthRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createAuthService } from './service.ts'
+
+/**
+ * Accounts, sessions, and password recovery.
+ *
+ * Registers before `workspace`, because `workspace_members.user_id` references
+ * `users`.
+ */
+
+const authConfigSchema = z.object({
+  /** Cookies go out `Secure` everywhere except development. */
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+})
+
+export function createAuthModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'auth',
+    structural: true,
+
+    register(context) {
+      const config = context.config(authConfigSchema)
+      const service = createAuthService({
+        db: context.db,
+        transaction: context.transaction,
+        email: context.email,
+        createId: context.createId,
+        now: context.now,
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountAuthRoutes(router, {
+          db: context.db,
+          now: context.now,
+          service,
+          cookie: { secure: config.NODE_ENV === 'production' },
+        })
+      })
+
+      return Promise.resolve()
+    },
+  }
+}

package/src/modules/auth/preferences.ts

@@ -0,0 +1,57 @@
+import type { ThemePreference } from '@kelpie/schemas'
+
+/**
+ * What an account's preferences are before anyone has saved any, and how a
+ * partial change becomes the whole row.
+ *
+ * `user_preferences` has no row until the first save. The alternative, seeding
+ * one at signup, would leave every account created before this table was written
+ * to without one, so the read path has to answer for a missing row regardless.
+ * Given that, defaults live here rather than in the database, where a `PATCH`
+ * would still have to know them to build an insert.
+ */
+
+export interface PreferenceValues {
+  readonly timezone: string
+  readonly theme: ThemePreference
+  readonly emailDigest: boolean
+  readonly mentionEmails: boolean
+  readonly productUpdates: boolean
+}
+
+/**
+ * UTC, not the workspace's zone. An account is global and may belong to several
+ * workspaces in different zones, so deriving from one of them would be picking
+ * arbitrarily and calling it the person's answer.
+ */
+export const DEFAULT_PREFERENCES: PreferenceValues = {
+  timezone: 'UTC',
+  theme: 'system',
+  emailDigest: true,
+  mentionEmails: true,
+  productUpdates: false,
+}
+
+export type PreferenceChanges = Partial<PreferenceValues>
+
+/**
+ * Folds a `PATCH` body onto what is stored, or onto the defaults when nothing is.
+ *
+ * The result is always a complete row, which is what makes the write an upsert
+ * with no read-modify-write hazard in the caller: the same request applied twice
+ * produces the same row.
+ */
+export function applyPreferenceChanges(
+  stored: PreferenceValues | undefined,
+  changes: PreferenceChanges,
+): PreferenceValues {
+  const current = stored ?? DEFAULT_PREFERENCES
+
+  return {
+    timezone: changes.timezone ?? current.timezone,
+    theme: changes.theme ?? current.theme,
+    emailDigest: changes.emailDigest ?? current.emailDigest,
+    mentionEmails: changes.mentionEmails ?? current.mentionEmails,
+    productUpdates: changes.productUpdates ?? current.productUpdates,
+  }
+}

package/src/modules/auth/repository.ts

@@ -0,0 +1,240 @@
+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'
+
+/**
+ * Drizzle queries for accounts and sessions. No business logic: the service
+ * decides, these read and write.
+ *
+ * Users and sessions are global rather than workspace-scoped, so unlike the CRM
+ * repositories these do not take a `workspaceId` first argument.
+ */
+
+/** Either the pool or an open transaction. Repositories never open one themselves. */
+export type Queryable = Database | Transaction
+
+export type UserRecord = typeof users.$inferSelect
+export type SessionRecord = typeof sessions.$inferSelect
+export type UserPreferencesRecord = typeof userPreferences.$inferSelect
+
+export async function findUserByEmail(db: Queryable, email: string): Promise<UserRecord | undefined> {
+  const [found] = await db.select().from(users).where(eq(users.email, email)).limit(1)
+
+  return found
+}
+
+export async function findUserById(db: Queryable, userId: string): Promise<UserRecord | undefined> {
+  const [found] = await db.select().from(users).where(eq(users.id, userId)).limit(1)
+
+  return found
+}
+
+export async function insertUser(db: Queryable, values: typeof users.$inferInsert): Promise<UserRecord> {
+  const [created] = await db.insert(users).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting user ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateUserPassword(
+  db: Queryable,
+  userId: string,
+  passwordHash: string,
+  now: Date,
+): Promise<void> {
+  await db
+    .update(users)
+    .set({ passwordHash, updatedAt: now })
+    .where(eq(users.id, userId))
+}
+
+/**
+ * Writes name and email. Not the password: that one has its own function because
+ * it also ends sessions, and the two must not be reachable through one call.
+ */
+export async function updateUserProfile(
+  db: Queryable,
+  userId: string,
+  changes: { readonly name?: string; readonly email?: string },
+  now: Date,
+): Promise<UserRecord | undefined> {
+  const [updated] = await db
+    .update(users)
+    .set({ ...changes, updatedAt: now })
+    .where(eq(users.id, userId))
+    .returning()
+
+  return updated
+}
+
+export async function findPreferences(
+  db: Queryable,
+  userId: string,
+): Promise<UserPreferencesRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(userPreferences)
+    .where(eq(userPreferences.userId, userId))
+    .limit(1)
+
+  return found
+}
+
+/**
+ * Inserts the row or replaces it, since the caller always has a complete set of
+ * values. Repeating a save writes the same row rather than failing on the
+ * primary key.
+ */
+export async function upsertPreferences(
+  db: Queryable,
+  values: typeof userPreferences.$inferInsert,
+): Promise<UserPreferencesRecord> {
+  const [saved] = await db
+    .insert(userPreferences)
+    .values(values)
+    .onConflictDoUpdate({ target: userPreferences.userId, set: values })
+    .returning()
+
+  if (saved === undefined) {
+    throw new Error(`Upserting preferences for ${values.userId} returned no row`)
+  }
+
+  return saved
+}
+
+export async function insertSession(
+  db: Queryable,
+  values: typeof sessions.$inferInsert,
+): Promise<SessionRecord> {
+  const [created] = await db.insert(sessions).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting session ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+/** Only returns sessions that have not expired; an expired row is not a session. */
+export async function findLiveSessionByTokenHash(
+  db: Queryable,
+  tokenHash: string,
+  now: Date,
+): Promise<SessionRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(sessions)
+    .where(and(eq(sessions.tokenHash, tokenHash), gt(sessions.expiresAt, now)))
+    .limit(1)
+
+  return found
+}
+
+export async function listSessionsForUser(db: Queryable, userId: string): Promise<SessionRecord[]> {
+  return db.select().from(sessions).where(eq(sessions.userId, userId)).orderBy(desc(sessions.lastActiveAt))
+}
+
+export async function touchSession(db: Queryable, sessionId: string, now: Date): Promise<void> {
+  await db.update(sessions).set({ lastActiveAt: now }).where(eq(sessions.id, sessionId))
+}
+
+export async function deleteSession(db: Queryable, userId: string, sessionId: string): Promise<number> {
+  const deleted = await db
+    .delete(sessions)
+    .where(and(eq(sessions.id, sessionId), eq(sessions.userId, userId)))
+    .returning({ id: sessions.id })
+
+  return deleted.length
+}
+
+export async function deleteAllSessionsForUser(db: Queryable, userId: string): Promise<void> {
+  await db.delete(sessions).where(eq(sessions.userId, userId))
+}
+
+/** Signs every other device out while leaving the caller where they are. */
+export async function deleteOtherSessionsForUser(
+  db: Queryable,
+  userId: string,
+  keepSessionId: string,
+): Promise<void> {
+  await db.delete(sessions).where(and(eq(sessions.userId, userId), ne(sessions.id, keepSessionId)))
+}
+
+export async function setActiveWorkspace(
+  db: Queryable,
+  sessionId: string,
+  workspaceId: string,
+): Promise<void> {
+  await db.update(sessions).set({ activeWorkspaceId: workspaceId }).where(eq(sessions.id, sessionId))
+}
+
+export async function insertPasswordResetToken(
+  db: Queryable,
+  values: typeof passwordResetTokens.$inferInsert,
+): Promise<void> {
+  await db.insert(passwordResetTokens).values(values)
+}
+
+/** Unused and unexpired. A used or stale token is not a token. */
+export async function findUsablePasswordResetToken(
+  db: Queryable,
+  tokenHash: string,
+  now: Date,
+): Promise<typeof passwordResetTokens.$inferSelect | undefined> {
+  const [found] = await db
+    .select()
+    .from(passwordResetTokens)
+    .where(
+      and(
+        eq(passwordResetTokens.tokenHash, tokenHash),
+        isNull(passwordResetTokens.usedAt),
+        gt(passwordResetTokens.expiresAt, now),
+      ),
+    )
+    .limit(1)
+
+  return found
+}
+
+export async function markPasswordResetTokenUsed(db: Queryable, id: string, now: Date): Promise<void> {
+  await db
+    .update(passwordResetTokens)
+    .set({ usedAt: now })
+    .where(eq(passwordResetTokens.id, id))
+}
+
+/** The membership a session's active workspace resolves to, if any. */
+export async function findMembership(
+  db: Queryable,
+  workspaceId: string,
+  userId: string,
+): Promise<typeof workspaceMembers.$inferSelect | undefined> {
+  const [found] = await db
+    .select()
+    .from(workspaceMembers)
+    .where(and(eq(workspaceMembers.workspaceId, workspaceId), eq(workspaceMembers.userId, userId)))
+    .limit(1)
+
+  return found
+}
+
+/** The workspace a returning user lands in when their session has no active one. */
+export async function findFirstMembership(
+  db: Queryable,
+  userId: string,
+): Promise<typeof workspaceMembers.$inferSelect | undefined> {
+  const [found] = await db
+    .select()
+    .from(workspaceMembers)
+    .where(eq(workspaceMembers.userId, userId))
+    .orderBy(workspaceMembers.joinedAt)
+    .limit(1)
+
+  return found
+}