chore: rename aelis to freya (#122)

apps/freya-backend/src/session/feed-source-provider.ts

@@ -0,0 +1,12 @@
+import type { FeedSource } from "@freya/core"
+import type { type } from "arktype"
+
+export type ConfigSchema = ReturnType<typeof type>
+
+export interface FeedSourceProvider {
+	/** The source ID this provider is responsible for (e.g., "freya.location"). */
+	readonly sourceId: string
+	/** Arktype schema for validating user-provided config. Omit if the source has no config. */
+	readonly configSchema?: ConfigSchema
+	feedSourceForUser(userId: string, config: unknown, credentials: unknown): Promise<FeedSource>
+}

apps/freya-backend/src/session/index.ts

@@ -0,0 +1,3 @@
+export type { FeedSourceProvider } from "./feed-source-provider.ts"
+export { UserSession } from "./user-session.ts"
+export { UserSessionManager } from "./user-session-manager.ts"

apps/freya-backend/src/session/user-session-manager.test.ts

@@ -0,0 +1,967 @@
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@freya/core"
+
+import { LocationSource } from "@freya/source-location"
+import { WeatherSource } from "@freya/source-weatherkit"
+import { beforeEach, describe, expect, mock, spyOn, test } from "bun:test"
+
+import type { Database } from "../db/index.ts"
+import type { FeedSourceProvider } from "./feed-source-provider.ts"
+
+import { CredentialEncryptor } from "../lib/crypto.ts"
+import {
+	CredentialStorageUnavailableError,
+	InvalidSourceCredentialsError,
+} from "../sources/errors.ts"
+import { SourceNotFoundError } from "../sources/errors.ts"
+import { UserSessionManager } from "./user-session-manager.ts"
+
+/**
+ * Per-user enabled source IDs used by the mocked `sources` module.
+ * Tests configure this before calling getOrCreate.
+ * Key = userId (or "*" for a default), value = array of enabled sourceIds.
+ */
+const enabledByUser = new Map<string, string[]>()
+
+/** Set which sourceIds are enabled for all users. */
+function setEnabledSources(sourceIds: string[]) {
+	enabledByUser.clear()
+	enabledByUser.set("*", sourceIds)
+}
+
+/** Set which sourceIds are enabled for a specific user. */
+function setEnabledSourcesForUser(userId: string, sourceIds: string[]) {
+	enabledByUser.set(userId, sourceIds)
+}
+
+function getEnabledSourceIds(userId: string): string[] {
+	return enabledByUser.get(userId) ?? enabledByUser.get("*") ?? []
+}
+
+/**
+ * Controls what `find()` returns in the mock. When `undefined` (the default),
+ * `find()` returns a standard enabled row. Set to a specific value (including
+ * `null`) to override the return value for all `find()` calls.
+ */
+let mockFindResult: unknown | undefined
+
+/**
+ * Spy for `updateCredentials` calls. Tests can inspect calls via
+ * `mockUpdateCredentialsCalls` or override behavior.
+ */
+const mockUpdateCredentialsCalls: Array<{ sourceId: string; credentials: Buffer }> = []
+let mockUpdateCredentialsError: Error | null = null
+
+// Mock the sources module so UserSessionManager's DB query returns controlled data.
+mock.module("../sources/user-sources.ts", () => ({
+	sources: (_db: Database, userId: string) => ({
+		async enabled() {
+			const now = new Date()
+			return getEnabledSourceIds(userId).map((sourceId) => ({
+				id: crypto.randomUUID(),
+				userId,
+				sourceId,
+				enabled: true,
+				config: {},
+				credentials: null,
+				createdAt: now,
+				updatedAt: now,
+			}))
+		},
+		async find(sourceId: string) {
+			if (mockFindResult !== undefined) return mockFindResult
+			const now = new Date()
+			return {
+				id: crypto.randomUUID(),
+				userId,
+				sourceId,
+				enabled: true,
+				config: {},
+				credentials: null,
+				createdAt: now,
+				updatedAt: now,
+			}
+		},
+		async findForUpdate(sourceId: string) {
+			// Delegates to find — row locking is a no-op in tests.
+			if (mockFindResult !== undefined) return mockFindResult
+			const now = new Date()
+			return {
+				id: crypto.randomUUID(),
+				userId,
+				sourceId,
+				enabled: true,
+				config: {},
+				credentials: null,
+				createdAt: now,
+				updatedAt: now,
+			}
+		},
+		async updateConfig(_sourceId: string, _update: { enabled?: boolean; config?: unknown }) {
+			// no-op for tests
+		},
+		async upsertConfig(_sourceId: string, _data: { enabled: boolean; config: unknown }) {
+			// no-op for tests
+		},
+		async updateCredentials(sourceId: string, credentials: Buffer) {
+			if (mockUpdateCredentialsError) {
+				throw mockUpdateCredentialsError
+			}
+			mockUpdateCredentialsCalls.push({ sourceId, credentials })
+		},
+	}),
+}))
+
+const fakeDb = {
+	transaction: <T>(fn: (tx: unknown) => Promise<T>) => fn(fakeDb),
+} as unknown as Database
+
+function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
+	return {
+		id,
+		async listActions(): Promise<Record<string, ActionDefinition>> {
+			return {}
+		},
+		async executeAction(): Promise<unknown> {
+			return undefined
+		},
+		async fetchContext(): Promise<readonly ContextEntry[] | null> {
+			return null
+		},
+		async fetchItems() {
+			return items
+		},
+	}
+}
+
+function createStubProvider(
+	sourceId: string,
+	factory: (
+		userId: string,
+		config: Record<string, unknown>,
+		credentials: unknown,
+	) => Promise<FeedSource> = async () => createStubSource(sourceId),
+): FeedSourceProvider {
+	return { sourceId, feedSourceForUser: factory }
+}
+
+const locationProvider: FeedSourceProvider = {
+	sourceId: "freya.location",
+	async feedSourceForUser() {
+		return new LocationSource()
+	},
+}
+
+const weatherProvider: FeedSourceProvider = {
+	sourceId: "freya.weather",
+	async feedSourceForUser() {
+		return new WeatherSource({ client: { fetch: async () => ({}) as never } })
+	},
+}
+
+beforeEach(() => {
+	enabledByUser.clear()
+	mockFindResult = undefined
+	mockUpdateCredentialsCalls.length = 0
+	mockUpdateCredentialsError = null
+})
+
+describe("UserSessionManager", () => {
+	test("getOrCreate creates session on first call", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+
+		const session = await manager.getOrCreate("user-1")
+
+		expect(session).toBeDefined()
+		expect(session.engine).toBeDefined()
+	})
+
+	test("getOrCreate returns same session for same user", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+
+		const session1 = await manager.getOrCreate("user-1")
+		const session2 = await manager.getOrCreate("user-1")
+
+		expect(session1).toBe(session2)
+	})
+
+	test("getOrCreate returns different sessions for different users", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+
+		const session1 = await manager.getOrCreate("user-1")
+		const session2 = await manager.getOrCreate("user-2")
+
+		expect(session1).not.toBe(session2)
+	})
+
+	test("each user gets independent source instances", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+
+		const session1 = await manager.getOrCreate("user-1")
+		const session2 = await manager.getOrCreate("user-2")
+
+		const source1 = session1.getSource<LocationSource>("freya.location")
+		const source2 = session2.getSource<LocationSource>("freya.location")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("remove destroys session and allows re-creation", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+
+		const session1 = await manager.getOrCreate("user-1")
+		manager.remove("user-1")
+		const session2 = await manager.getOrCreate("user-1")
+
+		expect(session1).not.toBe(session2)
+	})
+
+	test("remove is no-op for unknown user", () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+
+		expect(() => manager.remove("unknown")).not.toThrow()
+	})
+
+	test("registers multiple providers", async () => {
+		setEnabledSources(["freya.location", "freya.weather"])
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [locationProvider, weatherProvider],
+		})
+
+		const session = await manager.getOrCreate("user-1")
+
+		expect(session.getSource("freya.location")).toBeDefined()
+		expect(session.getSource("freya.weather")).toBeDefined()
+	})
+
+	test("refresh returns feed result through session", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+
+		const session = await manager.getOrCreate("user-1")
+		const result = await session.engine.refresh()
+
+		expect(result).toHaveProperty("context")
+		expect(result).toHaveProperty("items")
+		expect(result).toHaveProperty("errors")
+		expect(result.context.time).toBeInstanceOf(Date)
+	})
+
+	test("location update via executeAction works", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+
+		const session = await manager.getOrCreate("user-1")
+		await session.engine.executeAction("freya.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		const source = session.getSource<LocationSource>("freya.location")
+		expect(source?.lastLocation?.lat).toBe(51.5074)
+	})
+
+	test("subscribe receives updates after location push", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+		const callback = mock()
+
+		const session = await manager.getOrCreate("user-1")
+		session.engine.subscribe(callback)
+
+		await session.engine.executeAction("freya.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		// Wait for async update propagation
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).toHaveBeenCalled()
+	})
+
+	test("remove stops reactive updates", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+		const callback = mock()
+
+		const session = await manager.getOrCreate("user-1")
+		session.engine.subscribe(callback)
+
+		manager.remove("user-1")
+
+		// Create new session and push location — old callback should not fire
+		const session2 = await manager.getOrCreate("user-1")
+		await session2.engine.executeAction("freya.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).not.toHaveBeenCalled()
+	})
+
+	test("creates session with successful providers when some fail", async () => {
+		setEnabledSources(["freya.location", "freya.failing"])
+		const failingProvider: FeedSourceProvider = {
+			sourceId: "freya.failing",
+			async feedSourceForUser() {
+				throw new Error("provider failed")
+			},
+		}
+
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [locationProvider, failingProvider],
+		})
+
+		const spy = spyOn(console, "error").mockImplementation(() => {})
+
+		const session = await manager.getOrCreate("user-1")
+
+		expect(session).toBeDefined()
+		expect(session.getSource("freya.location")).toBeDefined()
+		expect(spy).toHaveBeenCalled()
+
+		spy.mockRestore()
+	})
+
+	test("throws AggregateError when all providers fail", async () => {
+		setEnabledSources(["freya.fail-1", "freya.fail-2"])
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [
+				{
+					sourceId: "freya.fail-1",
+					async feedSourceForUser() {
+						throw new Error("first failed")
+					},
+				},
+				{
+					sourceId: "freya.fail-2",
+					async feedSourceForUser() {
+						throw new Error("second failed")
+					},
+				},
+			],
+		})
+
+		await expect(manager.getOrCreate("user-1")).rejects.toBeInstanceOf(AggregateError)
+	})
+
+	test("concurrent getOrCreate for same user returns same session", async () => {
+		setEnabledSources(["freya.location"])
+		let callCount = 0
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [
+				{
+					sourceId: "freya.location",
+					async feedSourceForUser() {
+						callCount++
+						await new Promise((resolve) => setTimeout(resolve, 10))
+						return new LocationSource()
+					},
+				},
+			],
+		})
+
+		const [session1, session2] = await Promise.all([
+			manager.getOrCreate("user-1"),
+			manager.getOrCreate("user-1"),
+		])
+
+		expect(session1).toBe(session2)
+		expect(callCount).toBe(1)
+	})
+
+	test("remove during in-flight getOrCreate prevents session from being stored", async () => {
+		setEnabledSources(["freya.location"])
+		let resolveProvider: () => void
+		const providerGate = new Promise<void>((r) => {
+			resolveProvider = r
+		})
+
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [
+				{
+					sourceId: "freya.location",
+					async feedSourceForUser() {
+						await providerGate
+						return new LocationSource()
+					},
+				},
+			],
+		})
+
+		const sessionPromise = manager.getOrCreate("user-1")
+
+		// remove() while provider is still resolving
+		manager.remove("user-1")
+
+		// Let the provider finish
+		resolveProvider!()
+
+		await expect(sessionPromise).rejects.toThrow("removed during creation")
+
+		// A fresh getOrCreate should produce a new session, not the cancelled one
+		const freshSession = await manager.getOrCreate("user-1")
+		expect(freshSession).toBeDefined()
+		expect(freshSession.engine).toBeDefined()
+	})
+
+	test("only invokes providers for sources enabled for the user", async () => {
+		setEnabledSources(["freya.location"])
+		const locationFactory = mock(async () => createStubSource("freya.location"))
+		const weatherFactory = mock(async () => createStubSource("freya.weather"))
+
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [
+				{ sourceId: "freya.location", feedSourceForUser: locationFactory },
+				{ sourceId: "freya.weather", feedSourceForUser: weatherFactory },
+			],
+		})
+
+		const session = await manager.getOrCreate("user-1")
+
+		expect(locationFactory).toHaveBeenCalledTimes(1)
+		expect(weatherFactory).not.toHaveBeenCalled()
+		expect(session.getSource("freya.location")).toBeDefined()
+		expect(session.getSource("freya.weather")).toBeUndefined()
+	})
+
+	test("creates empty session when no sources are enabled", async () => {
+		setEnabledSources([])
+		const factory = mock(async () => createStubSource("freya.location"))
+
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [{ sourceId: "freya.location", feedSourceForUser: factory }],
+		})
+
+		const session = await manager.getOrCreate("user-1")
+
+		expect(factory).not.toHaveBeenCalled()
+		expect(session).toBeDefined()
+		expect(session.getSource("freya.location")).toBeUndefined()
+	})
+
+	test("per-user enabled sources are respected", async () => {
+		enabledByUser.clear()
+		setEnabledSourcesForUser("user-1", ["freya.location"])
+		setEnabledSourcesForUser("user-2", ["freya.weather"])
+
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [createStubProvider("freya.location"), createStubProvider("freya.weather")],
+		})
+
+		const session1 = await manager.getOrCreate("user-1")
+		const session2 = await manager.getOrCreate("user-2")
+
+		expect(session1.getSource("freya.location")).toBeDefined()
+		expect(session1.getSource("freya.weather")).toBeUndefined()
+		expect(session2.getSource("freya.location")).toBeUndefined()
+		expect(session2.getSource("freya.weather")).toBeDefined()
+	})
+})
+
+describe("UserSessionManager.replaceProvider", () => {
+	test("replaces source in all active sessions", async () => {
+		setEnabledSources(["test"])
+		const itemsV1: FeedItem[] = [
+			{
+				id: "v1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 1 },
+			},
+		]
+		const itemsV2: FeedItem[] = [
+			{
+				id: "v2",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 2 },
+			},
+		]
+
+		const providerV1 = createStubProvider("test", async () => createStubSource("test", itemsV1))
+		const manager = new UserSessionManager({ db: fakeDb, providers: [providerV1] })
+
+		const session1 = await manager.getOrCreate("user-1")
+		const session2 = await manager.getOrCreate("user-2")
+
+		// Verify v1 items
+		const feed1 = await session1.feed()
+		expect(feed1.items[0]!.data.version).toBe(1)
+
+		// Replace provider
+		const providerV2 = createStubProvider("test", async () => createStubSource("test", itemsV2))
+		await manager.replaceProvider(providerV2)
+
+		// Both sessions should now serve v2 items
+		const feed1After = await session1.feed()
+		const feed2After = await session2.feed()
+		expect(feed1After.items[0]!.data.version).toBe(2)
+		expect(feed2After.items[0]!.data.version).toBe(2)
+	})
+
+	test("throws for unknown provider sourceId", async () => {
+		setEnabledSources(["freya.location"])
+		const manager = new UserSessionManager({ db: fakeDb, providers: [locationProvider] })
+
+		const unknownProvider = createStubProvider("freya.unknown")
+
+		await expect(manager.replaceProvider(unknownProvider)).rejects.toThrow(
+			"no existing provider with that sourceId",
+		)
+	})
+
+	test("keeps existing source when new provider fails for a user", async () => {
+		setEnabledSources(["test"])
+		const providerV1 = createStubProvider("test", async () => createStubSource("test"))
+		const manager = new UserSessionManager({ db: fakeDb, providers: [providerV1] })
+
+		const session = await manager.getOrCreate("user-1")
+		expect(session.getSource("test")).toBeDefined()
+
+		const spy = spyOn(console, "error").mockImplementation(() => {})
+
+		const failingProvider = createStubProvider("test", async () => {
+			throw new Error("source disabled")
+		})
+		await manager.replaceProvider(failingProvider)
+
+		expect(session.getSource("test")).toBeDefined()
+		expect(spy).toHaveBeenCalled()
+
+		spy.mockRestore()
+	})
+
+	test("new sessions use the replaced provider", async () => {
+		setEnabledSources(["test"])
+		const itemsV1: FeedItem[] = [
+			{
+				id: "v1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 1 },
+			},
+		]
+		const itemsV2: FeedItem[] = [
+			{
+				id: "v2",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 2 },
+			},
+		]
+
+		const providerV1 = createStubProvider("test", async () => createStubSource("test", itemsV1))
+		const manager = new UserSessionManager({ db: fakeDb, providers: [providerV1] })
+
+		const providerV2 = createStubProvider("test", async () => createStubSource("test", itemsV2))
+		await manager.replaceProvider(providerV2)
+
+		// New session should use v2
+		const session = await manager.getOrCreate("user-new")
+		const feed = await session.feed()
+		expect(feed.items[0]!.data.version).toBe(2)
+	})
+
+	test("does not affect other providers' sources", async () => {
+		setEnabledSources(["source-a", "source-b"])
+		const providerA = createStubProvider("source-a", async () =>
+			createStubSource("source-a", [
+				{
+					id: "a-1",
+					sourceId: "source-a",
+					type: "test",
+					timestamp: new Date(),
+					data: { from: "a" },
+				},
+			]),
+		)
+		const providerB = createStubProvider("source-b", async () =>
+			createStubSource("source-b", [
+				{
+					id: "b-1",
+					sourceId: "source-b",
+					type: "test",
+					timestamp: new Date(),
+					data: { from: "b" },
+				},
+			]),
+		)
+
+		const manager = new UserSessionManager({ db: fakeDb, providers: [providerA, providerB] })
+		const session = await manager.getOrCreate("user-1")
+
+		// Replace only source-a
+		const providerA2 = createStubProvider("source-a", async () =>
+			createStubSource("source-a", [
+				{
+					id: "a-2",
+					sourceId: "source-a",
+					type: "test",
+					timestamp: new Date(),
+					data: { from: "a-new" },
+				},
+			]),
+		)
+		await manager.replaceProvider(providerA2)
+
+		// source-b should be unaffected
+		expect(session.getSource("source-b")).toBeDefined()
+		const feed = await session.feed()
+		const ids = feed.items.map((i) => i.id).sort()
+		expect(ids).toEqual(["a-2", "b-1"])
+	})
+
+	test("updates sessions that are still being created", async () => {
+		setEnabledSources(["test"])
+		const itemsV1: FeedItem[] = [
+			{
+				id: "v1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 1 },
+			},
+		]
+		const itemsV2: FeedItem[] = [
+			{
+				id: "v2",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 2 },
+			},
+		]
+
+		let resolveCreation: () => void
+		const creationGate = new Promise<void>((r) => {
+			resolveCreation = r
+		})
+
+		const providerV1 = createStubProvider("test", async () => {
+			await creationGate
+			return createStubSource("test", itemsV1)
+		})
+		const manager = new UserSessionManager({ db: fakeDb, providers: [providerV1] })
+
+		// Start session creation but don't let it finish yet
+		const sessionPromise = manager.getOrCreate("user-1")
+
+		// Replace provider while session is still pending
+		const providerV2 = createStubProvider("test", async () => createStubSource("test", itemsV2))
+		const replacePromise = manager.replaceProvider(providerV2)
+
+		// Let the original creation finish
+		resolveCreation!()
+
+		const session = await sessionPromise
+		await replacePromise
+
+		// Session should have been updated to v2
+		const feed = await session.feed()
+		expect(feed.items[0]!.data.version).toBe(2)
+	})
+
+	test("skips source replacement when source was disabled between creation and replace", async () => {
+		setEnabledSources(["test"])
+		const itemsV1: FeedItem[] = [
+			{
+				id: "v1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 1 },
+			},
+		]
+
+		const providerV1 = createStubProvider("test", async () => createStubSource("test", itemsV1))
+		const manager = new UserSessionManager({ db: fakeDb, providers: [providerV1] })
+
+		const session = await manager.getOrCreate("user-1")
+		const feedBefore = await session.feed()
+		expect(feedBefore.items[0]!.data.version).toBe(1)
+
+		// Simulate the source being disabled/deleted between session creation and replace
+		mockFindResult = null
+
+		const providerV2 = createStubProvider("test", async () =>
+			createStubSource("test", [
+				{
+					id: "v2",
+					sourceId: "test",
+					type: "test",
+					timestamp: new Date(),
+					data: { version: 2 },
+				},
+			]),
+		)
+		await manager.replaceProvider(providerV2)
+
+		// Session should still have v1 — the replace was skipped
+		const feedAfter = await session.feed()
+		expect(feedAfter.items[0]!.data.version).toBe(1)
+	})
+})
+
+const TEST_ENCRYPTION_KEY = "/bv1nbzC4ozZkT/pcv5oQfl+JAMuMZDUSVDesG2dur8="
+const testEncryptor = new CredentialEncryptor(TEST_ENCRYPTION_KEY)
+
+describe("UserSessionManager.updateSourceCredentials", () => {
+	test("encrypts and persists credentials", async () => {
+		setEnabledSources(["test"])
+		const provider = createStubProvider("test")
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [provider],
+			credentialEncryptor: testEncryptor,
+		})
+
+		await manager.updateSourceCredentials("user-1", "test", { token: "secret-123" })
+
+		expect(mockUpdateCredentialsCalls).toHaveLength(1)
+		expect(mockUpdateCredentialsCalls[0]!.sourceId).toBe("test")
+
+		// Verify the persisted buffer decrypts to the original credentials
+		const decrypted = JSON.parse(testEncryptor.decrypt(mockUpdateCredentialsCalls[0]!.credentials))
+		expect(decrypted).toEqual({ token: "secret-123" })
+	})
+
+	test("throws CredentialStorageUnavailableError when encryptor is not configured", async () => {
+		setEnabledSources(["test"])
+		const provider = createStubProvider("test")
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [provider],
+			// no credentialEncryptor
+		})
+
+		await expect(
+			manager.updateSourceCredentials("user-1", "test", { token: "x" }),
+		).rejects.toBeInstanceOf(CredentialStorageUnavailableError)
+	})
+
+	test("throws SourceNotFoundError for unknown source", async () => {
+		setEnabledSources([])
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [],
+			credentialEncryptor: testEncryptor,
+		})
+
+		await expect(
+			manager.updateSourceCredentials("user-1", "unknown", { token: "x" }),
+		).rejects.toBeInstanceOf(SourceNotFoundError)
+	})
+
+	test("propagates InvalidSourceCredentialsError from provider", async () => {
+		setEnabledSources(["test"])
+		let callCount = 0
+		const provider: FeedSourceProvider = {
+			sourceId: "test",
+			async feedSourceForUser(_userId: string, _config: unknown, _credentials: unknown) {
+				callCount++
+				// Succeed on first call (session creation), throw on refresh
+				if (callCount > 1) {
+					throw new InvalidSourceCredentialsError("test", "bad credentials")
+				}
+				return createStubSource("test")
+			},
+		}
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [provider],
+			credentialEncryptor: testEncryptor,
+		})
+
+		// Create a session first so the refresh path is exercised
+		await manager.getOrCreate("user-1")
+
+		await expect(
+			manager.updateSourceCredentials("user-1", "test", { token: "bad" }),
+		).rejects.toBeInstanceOf(InvalidSourceCredentialsError)
+
+		// Credentials should still have been persisted before the provider threw
+		expect(mockUpdateCredentialsCalls).toHaveLength(1)
+	})
+
+	test("refreshes source in active session after credential update", async () => {
+		setEnabledSources(["test"])
+		let receivedCredentials: unknown = null
+		const provider = createStubProvider("test", async (_userId, _config, credentials) => {
+			receivedCredentials = credentials
+			return createStubSource("test")
+		})
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [provider],
+			credentialEncryptor: testEncryptor,
+		})
+
+		await manager.getOrCreate("user-1")
+		await manager.updateSourceCredentials("user-1", "test", { token: "refreshed" })
+
+		expect(receivedCredentials).toEqual({ token: "refreshed" })
+	})
+
+	test("persists credentials without session refresh when no active session", async () => {
+		setEnabledSources(["test"])
+		const factory = mock(async () => createStubSource("test"))
+		const provider: FeedSourceProvider = { sourceId: "test", feedSourceForUser: factory }
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [provider],
+			credentialEncryptor: testEncryptor,
+		})
+
+		// No session created — just update credentials
+		await manager.updateSourceCredentials("user-1", "test", { token: "stored" })
+
+		expect(mockUpdateCredentialsCalls).toHaveLength(1)
+		// feedSourceForUser should not have been called (no session to refresh)
+		expect(factory).not.toHaveBeenCalled()
+	})
+})
+
+describe("UserSessionManager.saveSourceConfig", () => {
+	test("upserts config without credentials (existing behavior)", async () => {
+		setEnabledSources(["test"])
+		const factory = mock(async () => createStubSource("test"))
+		const provider: FeedSourceProvider = { sourceId: "test", feedSourceForUser: factory }
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [provider],
+			credentialEncryptor: testEncryptor,
+		})
+
+		// Create a session first so we can verify the source is refreshed
+		await manager.getOrCreate("user-1")
+
+		await manager.saveSourceConfig("user-1", "test", {
+			enabled: true,
+			config: { key: "value" },
+		})
+
+		// feedSourceForUser called once for session creation, once for upsert refresh
+		expect(factory).toHaveBeenCalledTimes(2)
+		// No credentials should have been persisted
+		expect(mockUpdateCredentialsCalls).toHaveLength(0)
+	})
+
+	test("upserts config with credentials — persists both and passes credentials to source", async () => {
+		setEnabledSources(["test"])
+		let receivedCredentials: unknown = null
+		const factory = mock(async (_userId: string, _config: unknown, creds: unknown) => {
+			receivedCredentials = creds
+			return createStubSource("test")
+		})
+		const provider: FeedSourceProvider = { sourceId: "test", feedSourceForUser: factory }
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [provider],
+			credentialEncryptor: testEncryptor,
+		})
+
+		// Create a session so the source refresh path runs
+		await manager.getOrCreate("user-1")
+
+		const creds = { username: "alice", password: "s3cret" }
+		await manager.saveSourceConfig("user-1", "test", {
+			enabled: true,
+			config: { serverUrl: "https://example.com" },
+			credentials: creds,
+		})
+
+		// Credentials were encrypted and persisted
+		expect(mockUpdateCredentialsCalls).toHaveLength(1)
+		const decrypted = JSON.parse(testEncryptor.decrypt(mockUpdateCredentialsCalls[0]!.credentials))
+		expect(decrypted).toEqual(creds)
+
+		// feedSourceForUser received the provided credentials (not null)
+		expect(receivedCredentials).toEqual(creds)
+	})
+
+	test("upserts config with credentials adds source to session when not already present", async () => {
+		// Start with no enabled sources so the session is empty
+		setEnabledSources([])
+		const factory = mock(async () => createStubSource("test"))
+		const provider: FeedSourceProvider = { sourceId: "test", feedSourceForUser: factory }
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [provider],
+			credentialEncryptor: testEncryptor,
+		})
+
+		const session = await manager.getOrCreate("user-1")
+		expect(session.hasSource("test")).toBe(false)
+
+		// Set mockFindResult to undefined so find() returns a row (simulating the row was just created by upsertConfig)
+		await manager.saveSourceConfig("user-1", "test", {
+			enabled: true,
+			config: {},
+			credentials: { token: "abc" },
+		})
+
+		// Source should now be in the session
+		expect(session.hasSource("test")).toBe(true)
+		expect(mockUpdateCredentialsCalls).toHaveLength(1)
+	})
+
+	test("throws CredentialStorageUnavailableError when credentials provided without encryptor", async () => {
+		setEnabledSources(["test"])
+		const provider = createStubProvider("test")
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [provider],
+			// No credentialEncryptor
+		})
+
+		await expect(
+			manager.saveSourceConfig("user-1", "test", {
+				enabled: true,
+				config: {},
+				credentials: { token: "abc" },
+			}),
+		).rejects.toBeInstanceOf(CredentialStorageUnavailableError)
+	})
+
+	test("throws SourceNotFoundError for unknown provider", async () => {
+		const manager = new UserSessionManager({
+			db: fakeDb,
+			providers: [],
+			credentialEncryptor: testEncryptor,
+		})
+
+		await expect(
+			manager.saveSourceConfig("user-1", "unknown", {
+				enabled: true,
+				config: {},
+			}),
+		).rejects.toBeInstanceOf(SourceNotFoundError)
+	})
+})

apps/freya-backend/src/session/user-session-manager.ts

@@ -0,0 +1,406 @@
+import type { FeedSource } from "@freya/core"
+
+import { type } from "arktype"
+import merge from "lodash.merge"
+
+import type { Database } from "../db/index.ts"
+import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
+import type { CredentialEncryptor } from "../lib/crypto.ts"
+import type { FeedSourceProvider } from "./feed-source-provider.ts"
+
+import {
+	CredentialStorageUnavailableError,
+	InvalidSourceConfigError,
+	SourceNotFoundError,
+} from "../sources/errors.ts"
+import { sources } from "../sources/user-sources.ts"
+import { UserSession } from "./user-session.ts"
+
+export interface UserSessionManagerConfig {
+	db: Database
+	providers: FeedSourceProvider[]
+	feedEnhancer?: FeedEnhancer | null
+	credentialEncryptor?: CredentialEncryptor | null
+}
+
+export class UserSessionManager {
+	private sessions = new Map<string, UserSession>()
+	private pending = new Map<string, Promise<UserSession>>()
+	private readonly db: Database
+	private readonly providers = new Map<string, FeedSourceProvider>()
+	private readonly feedEnhancer: FeedEnhancer | null
+	private readonly encryptor: CredentialEncryptor | null
+
+	constructor(config: UserSessionManagerConfig) {
+		this.db = config.db
+		for (const provider of config.providers) {
+			this.providers.set(provider.sourceId, provider)
+		}
+		this.feedEnhancer = config.feedEnhancer ?? null
+		this.encryptor = config.credentialEncryptor ?? null
+	}
+
+	getProvider(sourceId: string): FeedSourceProvider | undefined {
+		return this.providers.get(sourceId)
+	}
+
+	/**
+	 * Returns the user's config for a source, or defaults if no row exists.
+	 *
+	 * @throws {SourceNotFoundError} if the sourceId has no registered provider
+	 */
+	async fetchSourceConfig(
+		userId: string,
+		sourceId: string,
+	): Promise<{ enabled: boolean; config: unknown }> {
+		const provider = this.providers.get(sourceId)
+		if (!provider) {
+			throw new SourceNotFoundError(sourceId, userId)
+		}
+
+		const row = await sources(this.db, userId).find(sourceId)
+		return {
+			enabled: row?.enabled ?? false,
+			config: row?.config ?? {},
+		}
+	}
+
+	async getOrCreate(userId: string): Promise<UserSession> {
+		const existing = this.sessions.get(userId)
+		if (existing) return existing
+
+		const inflight = this.pending.get(userId)
+		if (inflight) return inflight
+
+		const promise = this.createSession(userId)
+		this.pending.set(userId, promise)
+		try {
+			const session = await promise
+			// If remove() was called while we were awaiting, it clears the
+			// pending entry. Detect that and destroy the session immediately.
+			if (!this.pending.has(userId)) {
+				session.destroy()
+				throw new Error(`Session for user ${userId} was removed during creation`)
+			}
+			this.sessions.set(userId, session)
+			return session
+		} finally {
+			this.pending.delete(userId)
+		}
+	}
+
+	remove(userId: string): void {
+		const session = this.sessions.get(userId)
+		if (session) {
+			session.destroy()
+			this.sessions.delete(userId)
+		}
+		// Cancel any in-flight creation so getOrCreate won't store the session
+		this.pending.delete(userId)
+	}
+
+	/**
+	 * Merges, validates, and persists a user's source config and/or enabled
+	 * state, then invalidates the cached session.
+	 *
+	 * @throws {SourceNotFoundError} if the source row doesn't exist
+	 * @throws {InvalidSourceConfigError} if the merged config fails schema validation
+	 */
+	async updateSourceConfig(
+		userId: string,
+		sourceId: string,
+		update: { enabled?: boolean; config?: unknown },
+	): Promise<void> {
+		const provider = this.providers.get(sourceId)
+		if (!provider) {
+			throw new SourceNotFoundError(sourceId, userId)
+		}
+
+		// Nothing to update
+		if (update.enabled === undefined && update.config === undefined) {
+			// Still validate existence — updateConfig would throw, but
+			// we can avoid the DB write entirely.
+			if (!(await sources(this.db, userId).find(sourceId))) {
+				throw new SourceNotFoundError(sourceId, userId)
+			}
+			return
+		}
+
+		// Use a transaction with SELECT FOR UPDATE to prevent lost updates
+		// when concurrent PATCH requests merge config against the same base.
+		const { existingRow, mergedConfig } = await this.db.transaction(async (tx) => {
+			const existingRow = await sources(tx, userId).findForUpdate(sourceId)
+
+			let mergedConfig: Record<string, unknown> | undefined
+			if (update.config !== undefined && provider.configSchema) {
+				const existingConfig = (existingRow?.config ?? {}) as Record<string, unknown>
+				mergedConfig = merge({}, existingConfig, update.config)
+
+				const validated = provider.configSchema(mergedConfig)
+				if (validated instanceof type.errors) {
+					throw new InvalidSourceConfigError(sourceId, validated.summary)
+				}
+			}
+
+			// Throws SourceNotFoundError if the row doesn't exist
+			await sources(tx, userId).updateConfig(sourceId, {
+				enabled: update.enabled,
+				config: mergedConfig,
+			})
+
+			return { existingRow, mergedConfig }
+		})
+
+		// Refresh the specific source in the active session instead of
+		// destroying the entire session.
+		const session = this.sessions.get(userId)
+		if (session) {
+			if (update.enabled === false) {
+				session.removeSource(sourceId)
+			} else {
+				const credentials = existingRow?.credentials
+					? this.decryptCredentials(existingRow.credentials)
+					: null
+				const source = await provider.feedSourceForUser(userId, mergedConfig ?? {}, credentials)
+				session.replaceSource(sourceId, source)
+			}
+		}
+	}
+
+	/**
+	 * Validates, persists, and upserts a user's source config, then
+	 * refreshes the cached session. Unlike updateSourceConfig, this
+	 * inserts a new row if one doesn't exist and fully replaces config
+	 * (no merge).
+	 *
+	 * When `credentials` is provided, they are encrypted and persisted
+	 * alongside the config in the same flow, avoiding the race condition
+	 * of separate config + credential requests.
+	 *
+	 * @throws {SourceNotFoundError} if the sourceId has no registered provider
+	 * @throws {InvalidSourceConfigError} if config fails schema validation
+	 * @throws {CredentialStorageUnavailableError} if credentials are provided but no encryptor is configured
+	 */
+	async saveSourceConfig(
+		userId: string,
+		sourceId: string,
+		data: { enabled: boolean; config?: unknown; credentials?: unknown },
+	): Promise<void> {
+		const provider = this.providers.get(sourceId)
+		if (!provider) {
+			throw new SourceNotFoundError(sourceId, userId)
+		}
+
+		if (provider.configSchema && data.config !== undefined) {
+			const validated = provider.configSchema(data.config)
+			if (validated instanceof type.errors) {
+				throw new InvalidSourceConfigError(sourceId, validated.summary)
+			}
+		}
+
+		if (data.credentials !== undefined && !this.encryptor) {
+			throw new CredentialStorageUnavailableError()
+		}
+
+		const config = data.config ?? {}
+
+		// Run the upsert + credential update atomically so a failure in
+		// either step doesn't leave the row in an inconsistent state.
+		const existingRow = await this.db.transaction(async (tx) => {
+			const existing = await sources(tx, userId).find(sourceId)
+
+			await sources(tx, userId).upsertConfig(sourceId, {
+				enabled: data.enabled,
+				config,
+			})
+
+			if (data.credentials !== undefined && this.encryptor) {
+				const encrypted = this.encryptor.encrypt(JSON.stringify(data.credentials))
+				await sources(tx, userId).updateCredentials(sourceId, encrypted)
+			}
+
+			return existing
+		})
+
+		const session = this.sessions.get(userId)
+		if (session) {
+			if (!data.enabled) {
+				session.removeSource(sourceId)
+			} else {
+				// Prefer the just-provided credentials over what was in the DB.
+				let credentials: unknown = null
+				if (data.credentials !== undefined) {
+					credentials = data.credentials
+				} else if (existingRow?.credentials) {
+					credentials = this.decryptCredentials(existingRow.credentials)
+				}
+				const source = await provider.feedSourceForUser(userId, config, credentials)
+				if (session.hasSource(sourceId)) {
+					session.replaceSource(sourceId, source)
+				} else {
+					session.addSource(source)
+				}
+			}
+		}
+	}
+
+	/**
+	 * Validates, encrypts, and persists per-user credentials for a source,
+	 * then refreshes the active session.
+	 *
+	 * @throws {SourceNotFoundError} if the source row doesn't exist or has no registered provider
+	 * @throws {CredentialStorageUnavailableError} if no CredentialEncryptor is configured
+	 */
+	async updateSourceCredentials(
+		userId: string,
+		sourceId: string,
+		credentials: unknown,
+	): Promise<void> {
+		const provider = this.providers.get(sourceId)
+		if (!provider) {
+			throw new SourceNotFoundError(sourceId, userId)
+		}
+
+		if (!this.encryptor) {
+			throw new CredentialStorageUnavailableError()
+		}
+
+		const encrypted = this.encryptor.encrypt(JSON.stringify(credentials))
+		await sources(this.db, userId).updateCredentials(sourceId, encrypted)
+
+		// Refresh the source in the active session.
+		// If feedSourceForUser throws (e.g. provider rejects the credentials),
+		// the DB already has the new credentials but the session keeps the old
+		// source. The next session creation will pick up the persisted credentials.
+		const session = this.sessions.get(userId)
+		if (session && session.hasSource(sourceId)) {
+			const row = await sources(this.db, userId).find(sourceId)
+			if (row?.enabled) {
+				const source = await provider.feedSourceForUser(userId, row.config ?? {}, credentials)
+				session.replaceSource(sourceId, source)
+			}
+		}
+	}
+
+	/**
+	 * Replaces a provider and updates all active sessions.
+	 * The new provider must have the same sourceId as an existing one.
+	 * For each active session, queries the user's source config from the DB
+	 * and re-resolves the source. If the provider fails for a user, the
+	 * existing source is kept.
+	 */
+	async replaceProvider(provider: FeedSourceProvider): Promise<void> {
+		if (!this.providers.has(provider.sourceId)) {
+			throw new Error(
+				`Cannot replace provider "${provider.sourceId}": no existing provider with that sourceId`,
+			)
+		}
+
+		this.providers.set(provider.sourceId, provider)
+
+		const updates: Promise<void>[] = []
+
+		for (const [, session] of this.sessions) {
+			updates.push(this.refreshSessionSource(session, provider))
+		}
+
+		// Also update sessions that are currently being created so they
+		// don't land in this.sessions with a stale source.
+		for (const [, pendingPromise] of this.pending) {
+			updates.push(
+				pendingPromise
+					.then((session) => this.refreshSessionSource(session, provider))
+					.catch(() => {
+						// Session creation itself failed — nothing to update.
+					}),
+			)
+		}
+
+		await Promise.all(updates)
+	}
+
+	/**
+	 * Re-resolves a single source for a session by querying the user's config
+	 * from the DB and calling the provider. If the provider fails, the existing
+	 * source is kept.
+	 */
+	private async refreshSessionSource(
+		session: UserSession,
+		provider: FeedSourceProvider,
+	): Promise<void> {
+		if (!session.hasSource(provider.sourceId)) return
+
+		try {
+			const row = await sources(this.db, session.userId).find(provider.sourceId)
+			if (!row?.enabled) return
+
+			const credentials = row.credentials ? this.decryptCredentials(row.credentials) : null
+			const newSource = await provider.feedSourceForUser(
+				session.userId,
+				row.config ?? {},
+				credentials,
+			)
+			session.replaceSource(provider.sourceId, newSource)
+		} catch (err) {
+			console.error(
+				`[UserSessionManager] refreshSource("${provider.sourceId}") failed for user ${session.userId}:`,
+				err,
+			)
+		}
+	}
+
+	private async createSession(userId: string): Promise<UserSession> {
+		const enabledRows = await sources(this.db, userId).enabled()
+
+		const promises: Promise<FeedSource>[] = []
+		for (const row of enabledRows) {
+			const provider = this.providers.get(row.sourceId)
+			if (provider) {
+				const credentials = row.credentials ? this.decryptCredentials(row.credentials) : null
+				promises.push(provider.feedSourceForUser(userId, row.config ?? {}, credentials))
+			}
+		}
+
+		if (promises.length === 0) {
+			return new UserSession(userId, [], this.feedEnhancer)
+		}
+
+		const results = await Promise.allSettled(promises)
+
+		const feedSources: FeedSource[] = []
+		const errors: unknown[] = []
+
+		for (const result of results) {
+			if (result.status === "fulfilled") {
+				feedSources.push(result.value)
+			} else {
+				errors.push(result.reason)
+			}
+		}
+
+		if (feedSources.length === 0 && errors.length > 0) {
+			throw new AggregateError(errors, "All feed source providers failed")
+		}
+
+		for (const error of errors) {
+			console.error("[UserSessionManager] Feed source provider failed:", error)
+		}
+
+		return new UserSession(userId, feedSources, this.feedEnhancer)
+	}
+
+	/**
+	 * Decrypts a credentials buffer from the DB, returning parsed JSON or null.
+	 * Returns null (with a warning) if decryption or parsing fails — e.g. due to
+	 * key rotation, data corruption, or malformed JSON.
+	 */
+	private decryptCredentials(credentials: Buffer): unknown {
+		if (!this.encryptor) return null
+		try {
+			return JSON.parse(this.encryptor.decrypt(credentials))
+		} catch (err) {
+			console.warn("[UserSessionManager] Failed to decrypt credentials:", err)
+			return null
+		}
+	}
+}

apps/freya-backend/src/session/user-session.test.ts

@@ -0,0 +1,394 @@
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@freya/core"
+
+import { LocationSource } from "@freya/source-location"
+import { describe, expect, spyOn, test } from "bun:test"
+
+import { UserSession } from "./user-session.ts"
+
+function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
+	return {
+		id,
+		async listActions(): Promise<Record<string, ActionDefinition>> {
+			return {}
+		},
+		async executeAction(): Promise<unknown> {
+			return undefined
+		},
+		async fetchContext(): Promise<readonly ContextEntry[] | null> {
+			return null
+		},
+		async fetchItems() {
+			return items
+		},
+	}
+}
+
+describe("UserSession", () => {
+	test("registers sources and starts engine", async () => {
+		const session = new UserSession("test-user", [
+			createStubSource("test-a"),
+			createStubSource("test-b"),
+		])
+
+		const result = await session.engine.refresh()
+
+		expect(result.errors).toHaveLength(0)
+	})
+
+	test("getSource returns registered source", () => {
+		const location = new LocationSource()
+		const session = new UserSession("test-user", [location])
+
+		const result = session.getSource<LocationSource>("freya.location")
+
+		expect(result).toBe(location)
+	})
+
+	test("getSource returns undefined for unknown source", () => {
+		const session = new UserSession("test-user", [createStubSource("test")])
+
+		expect(session.getSource("unknown")).toBeUndefined()
+	})
+
+	test("destroy stops engine and clears sources", () => {
+		const session = new UserSession("test-user", [createStubSource("test")])
+
+		session.destroy()
+
+		expect(session.getSource("test")).toBeUndefined()
+	})
+
+	test("engine.executeAction routes to correct source", async () => {
+		const location = new LocationSource()
+		const session = new UserSession("test-user", [location])
+
+		await session.engine.executeAction("freya.location", "update-location", {
+			lat: 51.5,
+			lng: -0.1,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		expect(location.lastLocation).toBeDefined()
+		expect(location.lastLocation!.lat).toBe(51.5)
+	})
+})
+
+describe("UserSession.feed", () => {
+	test("returns feed items without enhancer", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const session = new UserSession("test-user", [createStubSource("test", items)])
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.id).toBe("item-1")
+	})
+
+	test("returns enhanced items when enhancer is provided", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const enhancer = async (feedItems: FeedItem[]) =>
+			feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+
+		const session = new UserSession("test-user", [createStubSource("test", items)], enhancer)
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.data.enhanced).toBe(true)
+	})
+
+	test("caches enhanced items on subsequent calls", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		let enhancerCallCount = 0
+		const enhancer = async (feedItems: FeedItem[]) => {
+			enhancerCallCount++
+			return feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+		}
+
+		const session = new UserSession("test-user", [createStubSource("test", items)], enhancer)
+
+		const result1 = await session.feed()
+		expect(result1.items[0]!.data.enhanced).toBe(true)
+		expect(enhancerCallCount).toBe(1)
+
+		const result2 = await session.feed()
+		expect(result2.items[0]!.data.enhanced).toBe(true)
+		expect(enhancerCallCount).toBe(1)
+	})
+
+	test("re-enhances after engine refresh with new data", async () => {
+		let currentItems: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { version: 1 },
+			},
+		]
+		const source = createStubSource("test", currentItems)
+		// Make fetchItems dynamic so refresh returns new data
+		source.fetchItems = async () => currentItems
+
+		const enhancedVersions: number[] = []
+		const enhancer = async (feedItems: FeedItem[]) => {
+			const version = feedItems[0]!.data.version as number
+			enhancedVersions.push(version)
+			return feedItems.map((item) => ({
+				...item,
+				data: { ...item.data, enhanced: true },
+			}))
+		}
+
+		const session = new UserSession("test-user", [source], enhancer)
+
+		// First feed triggers refresh + enhancement
+		const result1 = await session.feed()
+		expect(result1.items[0]!.data.version).toBe(1)
+		expect(result1.items[0]!.data.enhanced).toBe(true)
+
+		// Update source data and trigger engine refresh
+		currentItems = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-02T00:00:00.000Z"),
+				data: { version: 2 },
+			},
+		]
+		await session.engine.refresh()
+
+		// Wait for subscriber-triggered background enhancement
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		// feed() should now serve re-enhanced items with version 2
+		const result2 = await session.feed()
+		expect(result2.items[0]!.data.version).toBe(2)
+		expect(result2.items[0]!.data.enhanced).toBe(true)
+		expect(enhancedVersions).toEqual([1, 2])
+	})
+
+	test("falls back to unenhanced items when enhancer throws", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const enhancer = async () => {
+			throw new Error("enhancement exploded")
+		}
+
+		const session = new UserSession("test-user", [createStubSource("test", items)], enhancer)
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.id).toBe("item-1")
+		expect(result.items[0]!.data.value).toBe(42)
+	})
+})
+
+describe("UserSession.replaceSource", () => {
+	test("replaces source and invalidates feed cache", async () => {
+		const itemsA: FeedItem[] = [
+			{
+				id: "a-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { from: "a" },
+			},
+		]
+		const itemsB: FeedItem[] = [
+			{
+				id: "b-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { from: "b" },
+			},
+		]
+
+		const sourceA = createStubSource("test", itemsA)
+		const session = new UserSession("test-user", [sourceA])
+
+		const result1 = await session.feed()
+		expect(result1.items).toHaveLength(1)
+		expect(result1.items[0]!.data.from).toBe("a")
+
+		const sourceB = createStubSource("test", itemsB)
+		session.replaceSource("test", sourceB)
+
+		const result2 = await session.feed()
+		expect(result2.items).toHaveLength(1)
+		expect(result2.items[0]!.data.from).toBe("b")
+	})
+
+	test("getSource returns new source after replace", () => {
+		const sourceA = createStubSource("test")
+		const session = new UserSession("test-user", [sourceA])
+
+		const sourceB = createStubSource("test")
+		session.replaceSource("test", sourceB)
+
+		expect(session.getSource("test")).toBe(sourceB)
+		expect(session.getSource("test")).not.toBe(sourceA)
+	})
+
+	test("throws when replacing a source that is not registered", () => {
+		const session = new UserSession("test-user", [createStubSource("test")])
+
+		expect(() => session.replaceSource("nonexistent", createStubSource("other"))).toThrow(
+			'Cannot replace source "nonexistent": not registered',
+		)
+	})
+
+	test("other sources are unaffected by replace", async () => {
+		const sourceA = createStubSource("source-a", [
+			{
+				id: "a-1",
+				sourceId: "source-a",
+				type: "test",
+				timestamp: new Date(),
+				data: { from: "a" },
+			},
+		])
+		const sourceB = createStubSource("source-b", [
+			{
+				id: "b-1",
+				sourceId: "source-b",
+				type: "test",
+				timestamp: new Date(),
+				data: { from: "b" },
+			},
+		])
+		const session = new UserSession("test-user", [sourceA, sourceB])
+
+		const replacement = createStubSource("source-a", [
+			{
+				id: "a-2",
+				sourceId: "source-a",
+				type: "test",
+				timestamp: new Date(),
+				data: { from: "a-new" },
+			},
+		])
+		session.replaceSource("source-a", replacement)
+
+		const result = await session.feed()
+		expect(result.items).toHaveLength(2)
+
+		const ids = result.items.map((i) => i.id).sort()
+		expect(ids).toEqual(["a-2", "b-1"])
+	})
+
+	test("invalidates enhancement cache on replace", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 1 },
+			},
+		]
+		let enhanceCount = 0
+		const enhancer = async (feedItems: FeedItem[]) => {
+			enhanceCount++
+			return feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+		}
+
+		const session = new UserSession("test-user", [createStubSource("test", items)], enhancer)
+
+		await session.feed()
+		expect(enhanceCount).toBe(1)
+
+		const newItems: FeedItem[] = [
+			{
+				id: "item-2",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 2 },
+			},
+		]
+		session.replaceSource("test", createStubSource("test", newItems))
+
+		const result = await session.feed()
+		expect(enhanceCount).toBe(2)
+		expect(result.items[0]!.id).toBe("item-2")
+		expect(result.items[0]!.data.enhanced).toBe(true)
+	})
+})
+
+describe("UserSession.removeSource", () => {
+	test("removes source from engine and sources map", () => {
+		const session = new UserSession("test-user", [
+			createStubSource("test-a"),
+			createStubSource("test-b"),
+		])
+
+		session.removeSource("test-a")
+
+		expect(session.getSource("test-a")).toBeUndefined()
+		expect(session.getSource("test-b")).toBeDefined()
+	})
+
+	test("invalidates feed cache on remove", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: {},
+			},
+		]
+		const session = new UserSession("test-user", [createStubSource("test", items)])
+
+		const result1 = await session.feed()
+		expect(result1.items).toHaveLength(1)
+
+		session.removeSource("test")
+
+		const result2 = await session.feed()
+		expect(result2.items).toHaveLength(0)
+	})
+
+	test("is a no-op for unknown source", () => {
+		const session = new UserSession("test-user", [createStubSource("test")])
+
+		expect(() => session.removeSource("unknown")).not.toThrow()
+		expect(session.getSource("test")).toBeDefined()
+	})
+})

apps/freya-backend/src/session/user-session.ts

@@ -0,0 +1,189 @@
+import { FeedEngine, type FeedItem, type FeedResult, type FeedSource } from "@freya/core"
+
+import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
+
+export class UserSession {
+	readonly userId: string
+	readonly engine: FeedEngine
+	private sources = new Map<string, FeedSource>()
+	private readonly enhancer: FeedEnhancer | null
+	private enhancedItems: FeedItem[] | null = null
+	/** The FeedResult that enhancedItems was derived from. */
+	private enhancedSource: FeedResult | null = null
+	private enhancingPromise: Promise<void> | null = null
+	private unsubscribe: (() => void) | null = null
+
+	constructor(userId: string, sources: FeedSource[], enhancer?: FeedEnhancer | null) {
+		this.userId = userId
+		this.engine = new FeedEngine()
+		this.enhancer = enhancer ?? null
+		for (const source of sources) {
+			this.sources.set(source.id, source)
+			this.engine.register(source)
+		}
+
+		if (this.enhancer) {
+			this.unsubscribe = this.engine.subscribe((result) => {
+				this.invalidateEnhancement()
+				this.runEnhancement(result)
+			})
+		}
+
+		this.engine.start()
+	}
+
+	/**
+	 * Returns the current feed, refreshing if the engine cache expired.
+	 * Enhancement runs eagerly on engine updates; this method awaits
+	 * any in-flight enhancement or triggers one if needed.
+	 */
+	async feed(): Promise<FeedResult> {
+		const cached = this.engine.lastFeed()
+		const result = cached ?? (await this.engine.refresh())
+
+		if (!this.enhancer) {
+			return result
+		}
+
+		// Wait for any in-flight background enhancement to finish
+		if (this.enhancingPromise) {
+			await this.enhancingPromise
+		}
+
+		// Serve cached enhancement only if it matches the current engine result
+		if (this.enhancedItems && this.enhancedSource === result) {
+			return { ...result, items: this.enhancedItems }
+		}
+
+		// Stale or missing — re-enhance
+		await this.runEnhancement(result)
+
+		if (this.enhancedItems) {
+			return { ...result, items: this.enhancedItems }
+		}
+
+		return result
+	}
+
+	getSource<T extends FeedSource>(sourceId: string): T | undefined {
+		return this.sources.get(sourceId) as T | undefined
+	}
+
+	hasSource(sourceId: string): boolean {
+		return this.sources.has(sourceId)
+	}
+
+	/**
+	 * Registers a new source in the engine and invalidates all caches.
+	 * Stops and restarts the engine to establish reactive subscriptions.
+	 */
+	addSource(source: FeedSource): void {
+		if (this.sources.has(source.id)) {
+			throw new Error(`Cannot add source "${source.id}": already registered`)
+		}
+
+		const wasStarted = this.engine.isStarted()
+
+		if (wasStarted) {
+			this.engine.stop()
+		}
+
+		this.engine.register(source)
+		this.sources.set(source.id, source)
+
+		this.invalidateEnhancement()
+		this.enhancingPromise = null
+
+		if (wasStarted) {
+			this.engine.start()
+		}
+	}
+
+	/**
+	 * Replaces a source in the engine and invalidates all caches.
+	 * Stops and restarts the engine to re-establish reactive subscriptions.
+	 */
+	replaceSource(oldSourceId: string, newSource: FeedSource): void {
+		if (!this.sources.has(oldSourceId)) {
+			throw new Error(`Cannot replace source "${oldSourceId}": not registered`)
+		}
+
+		const wasStarted = this.engine.isStarted()
+
+		if (wasStarted) {
+			this.engine.stop()
+		}
+
+		this.engine.unregister(oldSourceId)
+		this.sources.delete(oldSourceId)
+
+		this.engine.register(newSource)
+		this.sources.set(newSource.id, newSource)
+
+		this.invalidateEnhancement()
+		this.enhancingPromise = null
+
+		if (wasStarted) {
+			this.engine.start()
+		}
+	}
+
+	/**
+	 * Removes a source from the engine and invalidates all caches.
+	 * Stops and restarts the engine to clean up reactive subscriptions.
+	 */
+	removeSource(sourceId: string): void {
+		if (!this.sources.has(sourceId)) return
+
+		const wasStarted = this.engine.isStarted()
+
+		if (wasStarted) {
+			this.engine.stop()
+		}
+
+		this.engine.unregister(sourceId)
+		this.sources.delete(sourceId)
+
+		this.invalidateEnhancement()
+		this.enhancingPromise = null
+
+		if (wasStarted) {
+			this.engine.start()
+		}
+	}
+
+	destroy(): void {
+		this.unsubscribe?.()
+		this.unsubscribe = null
+		this.engine.stop()
+		this.sources.clear()
+		this.invalidateEnhancement()
+		this.enhancingPromise = null
+	}
+
+	private invalidateEnhancement(): void {
+		this.enhancedItems = null
+		this.enhancedSource = null
+	}
+
+	private runEnhancement(result: FeedResult): Promise<void> {
+		const promise = this.enhance(result)
+		this.enhancingPromise = promise
+		promise.finally(() => {
+			if (this.enhancingPromise === promise) {
+				this.enhancingPromise = null
+			}
+		})
+		return promise
+	}
+
+	private async enhance(result: FeedResult): Promise<void> {
+		try {
+			this.enhancedItems = await this.enhancer!(result.items)
+			this.enhancedSource = result
+		} catch (err) {
+			console.error("[enhancement] Unexpected error:", err)
+			this.invalidateEnhancement()
+		}
+	}
+}