feat: runtime provider hotswap (#82)

Add ability to replace a FeedSourceProvider at runtime and propagate
the new source to all active (and pending) user sessions, invalidating
their feed caches.

Co-authored-by: Ona <no-reply@ona.com>

.github/workflows/build-waitlist-website.yml

@@ -0,0 +1,42 @@
+name: Build waitlist website
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - apps/waitlist-website/**
+      - .github/workflows/build-waitlist-website.yml
+
+  workflow_dispatch:
+
+env:
+  REGISTRY: cr.nym.sh
+  IMAGE_NAME: aelis-waitlist-website
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: apps/waitlist-website
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/test.yml

@@ -21,4 +21,4 @@ jobs:
         run: bun install --frozen-lockfile
 
       - name: Run tests
-        run: bun test
+        run: bun run test

.ona/automations.yaml

@@ -1,8 +1,19 @@
 services:
   expo:
     name: Expo Dev Server
-    description: Expo development server for aris-client
+    description: Expo development server for aelis-client
     triggeredBy:
       - postDevcontainerStart
     commands:
-      start: cd apps/aris-client && ./scripts/run-dev-server.sh
+      start: cd apps/aelis-client && ./scripts/run-dev-server.sh
+
+  drizzle-studio:
+    name: Drizzle Studio
+    description: Drizzle Studio database browser for aelis-backend
+    triggeredBy:
+      - manual
+    commands:
+      start: |
+        FORWARD_URL=$(gitpod environment port open 4983 --name drizzle-studio-server | sed 's|https://||')
+        echo "Drizzle Studio: https://local.drizzle.studio/?host=${FORWARD_URL}&port=443"
+        cd apps/aelis-backend && bunx drizzle-kit studio --host 0.0.0.0 --port 4983

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project
 
-ARIS is an AI-powered personal assistant that aggregates data from various sources into a contextual feed. Monorepo with `packages/` (shared libraries) and `apps/` (applications).
+AELIS is an AI-powered personal assistant that aggregates data from various sources into a contextual feed. Monorepo with `packages/` (shared libraries) and `apps/` (applications).
 
 ## Commands
 

README.md

@@ -1,4 +1,4 @@
-# aris
+# aelis
 
 To install dependencies:
 
@@ -8,14 +8,14 @@ bun install
 
 ## Packages
 
-### @aris/source-tfl
+### @aelis/source-tfl
 
 TfL (Transport for London) feed source for tube, overground, and Elizabeth line alerts.
 
 #### Testing
 
 ```bash
-cd packages/aris-source-tfl
+cd packages/aelis-source-tfl
 bun run test
 ```
 

apps/aelis-backend/.env.example

@@ -4,6 +4,9 @@ DATABASE_URL=postgresql://user:password@localhost:5432/aris
 # BetterAuth secret (min 32 chars, generate with: openssl rand -base64 32)
 BETTER_AUTH_SECRET=
 
+# Encryption key for source credentials at rest (32 bytes, generate with: openssl rand -base64 32)
+CREDENTIALS_ENCRYPTION_KEY=
+
 # Base URL of the backend
 BETTER_AUTH_URL=http://localhost:3000
 

apps/aelis-backend/auth.ts

@@ -0,0 +1,20 @@
+// Used by Better Auth CLI for schema generation.
+// Run: bunx --bun auth@latest generate --config auth.ts --output src/db/auth-schema.ts
+import { betterAuth } from "better-auth"
+import { drizzleAdapter } from "better-auth/adapters/drizzle"
+import { admin } from "better-auth/plugins"
+import { SQL } from "bun"
+import { drizzle } from "drizzle-orm/bun-sql"
+
+const client = new SQL({ url: process.env.DATABASE_URL })
+const db = drizzle({ client })
+
+export const auth = betterAuth({
+	database: drizzleAdapter(db, { provider: "pg" }),
+	emailAndPassword: {
+		enabled: true,
+	},
+	plugins: [admin()],
+})
+
+export default auth

apps/aelis-backend/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "drizzle-kit"
+
+export default defineConfig({
+	out: "./drizzle",
+	schema: "./src/db/schema.ts",
+	dialect: "postgresql",
+	dbCredentials: {
+		url: process.env.DATABASE_URL!,
+	},
+})

apps/aelis-backend/drizzle/0000_wakeful_scorpion.sql

@@ -0,0 +1,66 @@
+CREATE TABLE "account" (
+	"id" text PRIMARY KEY NOT NULL,
+	"account_id" text NOT NULL,
+	"provider_id" text NOT NULL,
+	"user_id" text NOT NULL,
+	"access_token" text,
+	"refresh_token" text,
+	"id_token" text,
+	"access_token_expires_at" timestamp,
+	"refresh_token_expires_at" timestamp,
+	"scope" text,
+	"password" text,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "session" (
+	"id" text PRIMARY KEY NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"token" text NOT NULL,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL,
+	"ip_address" text,
+	"user_agent" text,
+	"user_id" text NOT NULL,
+	CONSTRAINT "session_token_unique" UNIQUE("token")
+);
+--> statement-breakpoint
+CREATE TABLE "user" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"email" text NOT NULL,
+	"email_verified" boolean DEFAULT false NOT NULL,
+	"image" text,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL,
+	CONSTRAINT "user_email_unique" UNIQUE("email")
+);
+--> statement-breakpoint
+CREATE TABLE "user_sources" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"source_id" text NOT NULL,
+	"enabled" boolean DEFAULT true NOT NULL,
+	"config" jsonb DEFAULT '{}'::jsonb,
+	"credentials" "bytea",
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "user_sources_user_id_source_id_unique" UNIQUE("user_id","source_id")
+);
+--> statement-breakpoint
+CREATE TABLE "verification" (
+	"id" text PRIMARY KEY NOT NULL,
+	"identifier" text NOT NULL,
+	"value" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "account" ADD CONSTRAINT "account_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "session" ADD CONSTRAINT "session_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "user_sources" ADD CONSTRAINT "user_sources_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "account_userId_idx" ON "account" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "session_userId_idx" ON "session" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "verification_identifier_idx" ON "verification" USING btree ("identifier");

apps/aelis-backend/drizzle/0001_misty_white_tiger.sql

@@ -0,0 +1 @@
+CREATE INDEX "user_sources_user_id_enabled_idx" ON "user_sources" USING btree ("user_id","enabled");

apps/aelis-backend/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,457 @@
+{
+  "id": "d8c59ec7-b686-41a7-a472-da29f3ab6727",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.account": {
+      "name": "account",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "account_id": {
+          "name": "account_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_token": {
+          "name": "access_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token": {
+          "name": "refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token": {
+          "name": "id_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "access_token_expires_at": {
+          "name": "access_token_expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token_expires_at": {
+          "name": "refresh_token_expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password": {
+          "name": "password",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "account_userId_idx": {
+          "name": "account_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "account_user_id_user_id_fk": {
+          "name": "account_user_id_user_id_fk",
+          "tableFrom": "account",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.session": {
+      "name": "session",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ip_address": {
+          "name": "ip_address",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_agent": {
+          "name": "user_agent",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "session_userId_idx": {
+          "name": "session_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "session_user_id_user_id_fk": {
+          "name": "session_user_id_user_id_fk",
+          "tableFrom": "session",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "session_token_unique": {
+          "name": "session_token_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "token"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user": {
+      "name": "user",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email_verified": {
+          "name": "email_verified",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "user_email_unique": {
+          "name": "user_email_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "email"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_sources": {
+      "name": "user_sources",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "config": {
+          "name": "config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false,
+          "default": "'{}'::jsonb"
+        },
+        "credentials": {
+          "name": "credentials",
+          "type": "bytea",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "user_sources_user_id_user_id_fk": {
+          "name": "user_sources_user_id_user_id_fk",
+          "tableFrom": "user_sources",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "user_sources_user_id_source_id_unique": {
+          "name": "user_sources_user_id_source_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "user_id",
+            "source_id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.verification": {
+      "name": "verification",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "identifier": {
+          "name": "identifier",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "verification_identifier_idx": {
+          "name": "verification_identifier_idx",
+          "columns": [
+            {
+              "expression": "identifier",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

apps/aelis-backend/drizzle/meta/0001_snapshot.json

@@ -0,0 +1,479 @@
+{
+  "id": "d963322c-77e2-4ac9-bd3c-ca544c85ae35",
+  "prevId": "d8c59ec7-b686-41a7-a472-da29f3ab6727",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.account": {
+      "name": "account",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "account_id": {
+          "name": "account_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_token": {
+          "name": "access_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token": {
+          "name": "refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token": {
+          "name": "id_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "access_token_expires_at": {
+          "name": "access_token_expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token_expires_at": {
+          "name": "refresh_token_expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password": {
+          "name": "password",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "account_userId_idx": {
+          "name": "account_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "account_user_id_user_id_fk": {
+          "name": "account_user_id_user_id_fk",
+          "tableFrom": "account",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.session": {
+      "name": "session",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ip_address": {
+          "name": "ip_address",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_agent": {
+          "name": "user_agent",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "session_userId_idx": {
+          "name": "session_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "session_user_id_user_id_fk": {
+          "name": "session_user_id_user_id_fk",
+          "tableFrom": "session",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "session_token_unique": {
+          "name": "session_token_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "token"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user": {
+      "name": "user",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email_verified": {
+          "name": "email_verified",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "user_email_unique": {
+          "name": "user_email_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "email"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_sources": {
+      "name": "user_sources",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "config": {
+          "name": "config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false,
+          "default": "'{}'::jsonb"
+        },
+        "credentials": {
+          "name": "credentials",
+          "type": "bytea",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "user_sources_user_id_enabled_idx": {
+          "name": "user_sources_user_id_enabled_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "enabled",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_sources_user_id_user_id_fk": {
+          "name": "user_sources_user_id_user_id_fk",
+          "tableFrom": "user_sources",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "user_sources_user_id_source_id_unique": {
+          "name": "user_sources_user_id_source_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "user_id",
+            "source_id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.verification": {
+      "name": "verification",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "identifier": {
+          "name": "identifier",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "verification_identifier_idx": {
+          "name": "verification_identifier_idx",
+          "columns": [
+            {
+              "expression": "identifier",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

apps/aelis-backend/drizzle/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1773620066366,
+      "tag": "0000_wakeful_scorpion",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1773624297794,
+      "tag": "0001_misty_white_tiger",
+      "breakpoints": true
+    }
+  ]
+}

apps/aelis-backend/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@aelis/backend",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/server.ts",
+	"scripts": {
+		"dev": "bun run --watch src/server.ts",
+		"start": "bun run src/server.ts",
+		"test": "bun test src/",
+		"db:generate": "bunx drizzle-kit generate",
+		"db:generate-auth": "bunx --bun auth@latest generate --config auth.ts --output src/db/auth-schema.ts -y",
+		"db:push": "bunx drizzle-kit push",
+		"db:migrate": "bunx drizzle-kit migrate",
+		"db:studio": "bunx drizzle-kit studio",
+		"create-admin": "bun run src/scripts/create-admin.ts"
+	},
+	"dependencies": {
+		"@aelis/core": "workspace:*",
+		"@aelis/source-caldav": "workspace:*",
+		"@aelis/source-google-calendar": "workspace:*",
+		"@aelis/source-location": "workspace:*",
+		"@aelis/source-tfl": "workspace:*",
+		"@aelis/source-weatherkit": "workspace:*",
+		"@openrouter/sdk": "^0.9.11",
+		"arktype": "^2.1.29",
+		"better-auth": "^1",
+		"drizzle-orm": "^0.45.1",
+		"hono": "^4"
+	},
+	"devDependencies": {
+		"drizzle-kit": "^0.31.9"
+	}
+}

apps/aelis-backend/src/auth/http.ts

@@ -1,7 +1,7 @@
 import type { Hono } from "hono"
 
-import { auth } from "./index.ts"
+import type { Auth } from "./index.ts"
 
-export function registerAuthHandlers(app: Hono): void {
+export function registerAuthHandlers(app: Hono, auth: Auth): void {
 	app.on(["POST", "GET"], "/api/auth/*", (c) => auth.handler(c.req.raw))
 }

apps/aelis-backend/src/auth/index.ts

@@ -0,0 +1,26 @@
+import { betterAuth } from "better-auth"
+import { drizzleAdapter } from "better-auth/adapters/drizzle"
+import { admin } from "better-auth/plugins"
+
+import type { Database } from "../db/index.ts"
+
+import * as schema from "../db/schema.ts"
+
+export function createAuth(db: Database) {
+	if (!process.env.BETTER_AUTH_SECRET) {
+		throw new Error("BETTER_AUTH_SECRET is not set")
+	}
+
+	return betterAuth({
+		database: drizzleAdapter(db, {
+			provider: "pg",
+			schema,
+		}),
+		emailAndPassword: {
+			enabled: true,
+		},
+		plugins: [admin()],
+	})
+}
+
+export type Auth = ReturnType<typeof createAuth>

apps/aelis-backend/src/auth/session-middleware.ts

@@ -0,0 +1,109 @@
+import type { Context, MiddlewareHandler, Next } from "hono"
+
+import type { Auth } from "./index.ts"
+import type { AuthSession, AuthUser } from "./session.ts"
+
+export interface SessionVariables {
+	user: AuthUser | null
+	session: AuthSession | null
+}
+
+export type AuthSessionEnv = { Variables: SessionVariables }
+
+export type AuthSessionMiddleware = MiddlewareHandler<AuthSessionEnv>
+
+declare module "hono" {
+	interface ContextVariableMap extends SessionVariables {}
+}
+
+/**
+ * Creates a middleware that attaches session and user to the context.
+ * Does not reject unauthenticated requests - use createRequireSession for that.
+ */
+export function createSessionMiddleware(auth: Auth): AuthSessionMiddleware {
+	return async (c: Context, next: Next): Promise<void> => {
+		const session = await auth.api.getSession({ headers: c.req.raw.headers })
+
+		if (session) {
+			c.set("user", session.user)
+			c.set("session", session.session)
+		} else {
+			c.set("user", null)
+			c.set("session", null)
+		}
+
+		await next()
+	}
+}
+
+/**
+ * Creates a middleware that requires a valid session. Returns 401 if not authenticated.
+ */
+export function createRequireSession(auth: Auth): AuthSessionMiddleware {
+	return async (c: Context, next: Next): Promise<Response | void> => {
+		const session = await auth.api.getSession({ headers: c.req.raw.headers })
+
+		if (!session) {
+			return c.json({ error: "Unauthorized" }, 401)
+		}
+
+		c.set("user", session.user)
+		c.set("session", session.session)
+		await next()
+	}
+}
+
+/**
+ * Creates a function to get session from headers. Useful for WebSocket upgrade validation.
+ */
+export function createGetSessionFromHeaders(auth: Auth) {
+	return async (headers: Headers): Promise<{ user: AuthUser; session: AuthSession } | null> => {
+		const session = await auth.api.getSession({ headers })
+		return session
+	}
+}
+
+/**
+ * Dev/test middleware that injects a fake user and session.
+ * Pass userId to simulate an authenticated request, or omit to get 401.
+ */
+export function mockAuthSessionMiddleware(userId?: string): AuthSessionMiddleware {
+	return async (c: Context, next: Next): Promise<Response | void> => {
+		if (!userId) {
+			return c.json({ error: "Unauthorized" }, 401)
+		}
+
+		const now = new Date()
+		const expiresAt = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000)
+
+		const user: AuthUser = {
+			id: "k7Gx2mPqRvNwYs9TdLfA4bHcJeUo1iZn",
+			name: "Dev User",
+			email: "dev@aelis.local",
+			emailVerified: true,
+			image: null,
+			createdAt: now,
+			updatedAt: now,
+			role: "admin",
+			banned: false,
+			banReason: null,
+			banExpires: null,
+		}
+
+		const session: AuthSession = {
+			id: "Wt3FvBpXaQrMhD8sKjE6LcYn0gUz5iRo",
+			userId: "k7Gx2mPqRvNwYs9TdLfA4bHcJeUo1iZn",
+			token: "Vb9CxNfRm2KwQs7TjPeA5dLhYg0UoZi4",
+			expiresAt,
+			ipAddress: "127.0.0.1",
+			userAgent: "aelis-dev",
+			createdAt: now,
+			updatedAt: now,
+		}
+
+		c.set("user", user)
+		c.set("session", session)
+
+		await next()
+	}
+}

apps/aelis-backend/src/auth/session.ts

@@ -0,0 +1,4 @@
+import type { Auth } from "./index.ts"
+
+export type AuthUser = Auth["$Infer"]["Session"]["user"]
+export type AuthSession = Auth["$Infer"]["Session"]["session"]

apps/aelis-backend/src/db/auth-schema.ts

@@ -0,0 +1,96 @@
+import { relations } from "drizzle-orm"
+import { pgTable, text, timestamp, boolean, index } from "drizzle-orm/pg-core"
+
+export const user = pgTable("user", {
+	id: text("id").primaryKey(),
+	name: text("name").notNull(),
+	email: text("email").notNull().unique(),
+	emailVerified: boolean("email_verified").default(false).notNull(),
+	image: text("image"),
+	createdAt: timestamp("created_at").notNull(),
+	updatedAt: timestamp("updated_at")
+		.$onUpdate(() => new Date())
+		.notNull(),
+	role: text("role"),
+	banned: boolean("banned").default(false),
+	banReason: text("ban_reason"),
+	banExpires: timestamp("ban_expires"),
+})
+
+export const session = pgTable(
+	"session",
+	{
+		id: text("id").primaryKey(),
+		expiresAt: timestamp("expires_at").notNull(),
+		token: text("token").notNull().unique(),
+		createdAt: timestamp("created_at").notNull(),
+		updatedAt: timestamp("updated_at")
+			.$onUpdate(() => new Date())
+			.notNull(),
+		ipAddress: text("ip_address"),
+		userAgent: text("user_agent"),
+		userId: text("user_id")
+			.notNull()
+			.references(() => user.id, { onDelete: "cascade" }),
+		impersonatedBy: text("impersonated_by"),
+	},
+	(table) => [index("session_userId_idx").on(table.userId)],
+)
+
+export const account = pgTable(
+	"account",
+	{
+		id: text("id").primaryKey(),
+		accountId: text("account_id").notNull(),
+		providerId: text("provider_id").notNull(),
+		userId: text("user_id")
+			.notNull()
+			.references(() => user.id, { onDelete: "cascade" }),
+		accessToken: text("access_token"),
+		refreshToken: text("refresh_token"),
+		idToken: text("id_token"),
+		accessTokenExpiresAt: timestamp("access_token_expires_at"),
+		refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+		scope: text("scope"),
+		password: text("password"),
+		createdAt: timestamp("created_at").notNull(),
+		updatedAt: timestamp("updated_at")
+			.$onUpdate(() => new Date())
+			.notNull(),
+	},
+	(table) => [index("account_userId_idx").on(table.userId)],
+)
+
+export const verification = pgTable(
+	"verification",
+	{
+		id: text("id").primaryKey(),
+		identifier: text("identifier").notNull(),
+		value: text("value").notNull(),
+		expiresAt: timestamp("expires_at").notNull(),
+		createdAt: timestamp("created_at").notNull(),
+		updatedAt: timestamp("updated_at")
+			.$onUpdate(() => new Date())
+			.notNull(),
+	},
+	(table) => [index("verification_identifier_idx").on(table.identifier)],
+)
+
+export const userRelations = relations(user, ({ many }) => ({
+	sessions: many(session),
+	accounts: many(account),
+}))
+
+export const sessionRelations = relations(session, ({ one }) => ({
+	user: one(user, {
+		fields: [session.userId],
+		references: [user.id],
+	}),
+}))
+
+export const accountRelations = relations(account, ({ one }) => ({
+	user: one(user, {
+		fields: [account.userId],
+		references: [user.id],
+	}),
+}))

apps/aelis-backend/src/db/index.ts

@@ -0,0 +1,23 @@
+import { SQL } from "bun"
+import { drizzle, type BunSQLDatabase } from "drizzle-orm/bun-sql"
+
+import * as schema from "./schema.ts"
+
+export type Database = BunSQLDatabase<typeof schema>
+
+export interface DatabaseConnection {
+	db: Database
+	close: () => Promise<void>
+}
+
+export function createDatabase(url: string): DatabaseConnection {
+	if (!url) {
+		throw new Error("DATABASE_URL is required")
+	}
+
+	const client = new SQL({ url })
+	return {
+		db: drizzle({ client, schema }),
+		close: () => client.close(),
+	}
+}

apps/aelis-backend/src/db/schema.ts

@@ -0,0 +1,62 @@
+import {
+	boolean,
+	customType,
+	index,
+	jsonb,
+	pgTable,
+	text,
+	timestamp,
+	unique,
+	uuid,
+} from "drizzle-orm/pg-core"
+
+// ---------------------------------------------------------------------------
+// Better Auth core tables
+// Re-exported from CLI-generated schema.
+// Regenerate with: bunx --bun auth@latest generate --config auth.ts --output src/db/auth-schema.ts
+// ---------------------------------------------------------------------------
+
+export {
+	user,
+	session,
+	account,
+	verification,
+	userRelations,
+	sessionRelations,
+	accountRelations,
+} from "./auth-schema.ts"
+
+import { user } from "./auth-schema.ts"
+
+// ---------------------------------------------------------------------------
+// AELIS — per-user source configuration
+// ---------------------------------------------------------------------------
+
+const bytea = customType<{ data: Buffer }>({
+	dataType() {
+		return "bytea"
+	},
+})
+
+export const userSources = pgTable(
+	"user_sources",
+	{
+		id: uuid("id").primaryKey().defaultRandom(),
+		userId: text("user_id")
+			.notNull()
+			.references(() => user.id, { onDelete: "cascade" }),
+		sourceId: text("source_id").notNull(),
+		enabled: boolean("enabled").notNull().default(true),
+		config: jsonb("config").default({}),
+		credentials: bytea("credentials"),
+		createdAt: timestamp("created_at").notNull().defaultNow(),
+		updatedAt: timestamp("updated_at")
+			.notNull()
+			.defaultNow()
+			.$onUpdate(() => new Date()),
+	},
+	(t) => [
+		unique("user_sources_user_id_source_id_unique").on(t.userId, t.sourceId),
+		index("user_sources_user_id_enabled_idx").on(t.userId, t.enabled),
+	],
+)

apps/aelis-backend/src/engine/http.test.ts

@@ -0,0 +1,369 @@
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aelis/core"
+
+import { contextKey } from "@aelis/core"
+import { describe, expect, spyOn, test } from "bun:test"
+import { Hono } from "hono"
+
+import { mockAuthSessionMiddleware } from "../auth/session-middleware.ts"
+import { UserSessionManager } from "../session/index.ts"
+import { registerFeedHttpHandlers } from "./http.ts"
+
+interface FeedResponse {
+	items: Array<{
+		id: string
+		type: string
+		priority: number
+		timestamp: string
+		data: Record<string, unknown>
+	}>
+	errors: Array<{ sourceId: string; error: string }>
+}
+
+function createStubSource(
+	id: string,
+	items: FeedItem[] = [],
+	contextEntries: readonly ContextEntry[] | null = null,
+): FeedSource {
+	return {
+		id,
+		async listActions(): Promise<Record<string, ActionDefinition>> {
+			return {}
+		},
+		async executeAction(): Promise<unknown> {
+			return undefined
+		},
+		async fetchContext(): Promise<readonly ContextEntry[] | null> {
+			return contextEntries
+		},
+		async fetchItems() {
+			return items
+		},
+	}
+}
+
+function buildTestApp(sessionManager: UserSessionManager, userId?: string) {
+	const app = new Hono()
+	registerFeedHttpHandlers(app, {
+		sessionManager,
+		authSessionMiddleware: mockAuthSessionMiddleware(userId),
+	})
+	return app
+}
+
+describe("GET /api/feed", () => {
+	test("returns 401 without auth", async () => {
+		const manager = new UserSessionManager({ providers: [] })
+		const app = buildTestApp(manager)
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(401)
+	})
+
+	test("returns cached feed when available", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				priority: 0.8,
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const manager = new UserSessionManager({
+			providers: [
+				{
+					sourceId: "test",
+					async feedSourceForUser() {
+						return createStubSource("test", items)
+					},
+				},
+			],
+		})
+		const app = buildTestApp(manager, "user-1")
+
+		// Prime the cache
+		const session = await manager.getOrCreate("user-1")
+		await session.engine.refresh()
+		expect(session.engine.lastFeed()).not.toBeNull()
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as FeedResponse
+		expect(body.items).toHaveLength(1)
+		expect(body.items[0]!.id).toBe("item-1")
+		expect(body.items[0]!.type).toBe("test")
+		expect(body.items[0]!.priority).toBe(0.8)
+		expect(body.items[0]!.timestamp).toBe("2025-01-01T00:00:00.000Z")
+		expect(body.errors).toHaveLength(0)
+	})
+
+	test("forces refresh when no cached feed", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "fresh-1",
+				sourceId: "test",
+				type: "test",
+				priority: 0.5,
+				timestamp: new Date("2025-06-01T12:00:00.000Z"),
+				data: { fresh: true },
+			},
+		]
+		const manager = new UserSessionManager({
+			providers: [
+				{
+					sourceId: "test",
+					async feedSourceForUser() {
+						return createStubSource("test", items)
+					},
+				},
+			],
+		})
+		const app = buildTestApp(manager, "user-1")
+
+		// No prior refresh — lastFeed() returns null, handler should call refresh()
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as FeedResponse
+		expect(body.items).toHaveLength(1)
+		expect(body.items[0]!.id).toBe("fresh-1")
+		expect(body.items[0]!.data.fresh).toBe(true)
+		expect(body.errors).toHaveLength(0)
+	})
+
+	test("serializes source errors as message strings", async () => {
+		const failingSource: FeedSource = {
+			id: "failing",
+			async listActions() {
+				return {}
+			},
+			async executeAction() {
+				return undefined
+			},
+			async fetchContext() {
+				return null
+			},
+			async fetchItems() {
+				throw new Error("connection timeout")
+			},
+		}
+		const manager = new UserSessionManager({
+			providers: [
+				{
+					sourceId: "failing",
+					async feedSourceForUser() {
+						return failingSource
+					},
+				},
+			],
+		})
+		const app = buildTestApp(manager, "user-1")
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as FeedResponse
+		expect(body.items).toHaveLength(0)
+		expect(body.errors).toHaveLength(1)
+		expect(body.errors[0]!.sourceId).toBe("failing")
+		expect(body.errors[0]!.error).toBe("connection timeout")
+	})
+
+	test("returns 503 when all providers fail", async () => {
+		const manager = new UserSessionManager({
+			providers: [
+				{
+					sourceId: "test",
+					async feedSourceForUser() {
+						throw new Error("provider down")
+					},
+				},
+			],
+		})
+		const app = buildTestApp(manager, "user-1")
+
+		const spy = spyOn(console, "error").mockImplementation(() => {})
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(503)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toBe("Service unavailable")
+
+		spy.mockRestore()
+	})
+})
+
+describe("GET /api/context", () => {
+	const weatherKey = contextKey("aelis.weather", "weather")
+	const weatherData = { temperature: 20, condition: "Clear" }
+	const contextEntries: readonly ContextEntry[] = [[weatherKey, weatherData]]
+
+	// The mock auth middleware always injects this hardcoded user ID
+	const mockUserId = "k7Gx2mPqRvNwYs9TdLfA4bHcJeUo1iZn"
+
+	async function buildContextApp(userId?: string) {
+		const manager = new UserSessionManager({
+			providers: [
+				{
+					sourceId: "weather",
+					async feedSourceForUser() {
+						return createStubSource("weather", [], contextEntries)
+					},
+				},
+			],
+		})
+		const app = buildTestApp(manager, userId)
+		const session = await manager.getOrCreate(mockUserId)
+		return { app, session }
+	}
+
+	test("returns 401 without auth", async () => {
+		const manager = new UserSessionManager({ providers: [] })
+		const app = buildTestApp(manager)
+
+		const res = await app.request('/api/context?key=["aelis.weather","weather"]')
+
+		expect(res.status).toBe(401)
+	})
+
+	test("returns 400 when key param is missing", async () => {
+		const { app } = await buildContextApp("user-1")
+
+		const res = await app.request("/api/context")
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when key is invalid JSON", async () => {
+		const { app } = await buildContextApp("user-1")
+
+		const res = await app.request("/api/context?key=notjson")
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when key is not an array", async () => {
+		const { app } = await buildContextApp("user-1")
+
+		const res = await app.request('/api/context?key="string"')
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when key contains invalid element types", async () => {
+		const { app } = await buildContextApp("user-1")
+
+		const res = await app.request("/api/context?key=[true,null,[1,2]]")
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when key is an empty array", async () => {
+		const { app } = await buildContextApp("user-1")
+
+		const res = await app.request("/api/context?key=[]")
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("key")
+	})
+
+	test("returns 400 when match param is invalid", async () => {
+		const { app } = await buildContextApp("user-1")
+
+		const res = await app.request('/api/context?key=["aelis.weather"]&match=invalid')
+
+		expect(res.status).toBe(400)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toContain("match")
+	})
+
+	test("returns exact match with match=exact", async () => {
+		const { app, session } = await buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather","weather"]&match=exact')
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as { match: string; value: unknown }
+		expect(body.match).toBe("exact")
+		expect(body.value).toEqual(weatherData)
+	})
+
+	test("returns 404 with match=exact when only prefix would match", async () => {
+		const { app, session } = await buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather"]&match=exact')
+
+		expect(res.status).toBe(404)
+	})
+
+	test("returns prefix match with match=prefix", async () => {
+		const { app, session } = await buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather"]&match=prefix')
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as {
+			match: string
+			entries: Array<{ key: unknown[]; value: unknown }>
+		}
+		expect(body.match).toBe("prefix")
+		expect(body.entries).toHaveLength(1)
+		expect(body.entries[0]!.key).toEqual(["aelis.weather", "weather"])
+		expect(body.entries[0]!.value).toEqual(weatherData)
+	})
+
+	test("default mode returns exact match when available", async () => {
+		const { app, session } = await buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather","weather"]')
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as { match: string; value: unknown }
+		expect(body.match).toBe("exact")
+		expect(body.value).toEqual(weatherData)
+	})
+
+	test("default mode falls back to prefix when no exact match", async () => {
+		const { app, session } = await buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["aelis.weather"]')
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as {
+			match: string
+			entries: Array<{ key: unknown[]; value: unknown }>
+		}
+		expect(body.match).toBe("prefix")
+		expect(body.entries).toHaveLength(1)
+		expect(body.entries[0]!.value).toEqual(weatherData)
+	})
+
+	test("returns 404 when neither exact nor prefix matches", async () => {
+		const { app, session } = await buildContextApp("user-1")
+		await session.engine.refresh()
+
+		const res = await app.request('/api/context?key=["nonexistent"]')
+
+		expect(res.status).toBe(404)
+		const body = (await res.json()) as { error: string }
+		expect(body.error).toBe("Context key not found")
+	})
+})

apps/aelis-backend/src/engine/http.ts

@@ -0,0 +1,133 @@
+import type { Context, Hono } from "hono"
+
+import { contextKey } from "@aelis/core"
+import { createMiddleware } from "hono/factory"
+
+import type { AuthSessionMiddleware } from "../auth/session-middleware.ts"
+import type { UserSessionManager } from "../session/index.ts"
+
+type Env = {
+	Variables: {
+		sessionManager: UserSessionManager
+	}
+}
+
+interface FeedHttpHandlersDeps {
+	sessionManager: UserSessionManager
+	authSessionMiddleware: AuthSessionMiddleware
+}
+
+export function registerFeedHttpHandlers(
+	app: Hono,
+	{ sessionManager, authSessionMiddleware }: FeedHttpHandlersDeps,
+) {
+	const inject = createMiddleware<Env>(async (c, next) => {
+		c.set("sessionManager", sessionManager)
+		await next()
+	})
+
+	app.get("/api/feed", inject, authSessionMiddleware, handleGetFeed)
+	app.get("/api/context", inject, authSessionMiddleware, handleGetContext)
+}
+
+async function handleGetFeed(c: Context<Env>) {
+	const user = c.get("user")!
+	const sessionManager = c.get("sessionManager")
+
+	let session
+	try {
+		session = await sessionManager.getOrCreate(user.id)
+	} catch (err) {
+		console.error("[handleGetFeed] Failed to create session:", err)
+		return c.json({ error: "Service unavailable" }, 503)
+	}
+
+	const feed = await session.feed()
+
+	return c.json({
+		items: feed.items,
+		errors: feed.errors.map((e) => ({
+			sourceId: e.sourceId,
+			error: e.error.message,
+		})),
+	})
+}
+
+async function handleGetContext(c: Context<Env>) {
+	const keyParam = c.req.query("key")
+	if (!keyParam) {
+		return c.json({ error: 'Invalid or missing "key" parameter: must be a JSON array' }, 400)
+	}
+
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(keyParam)
+	} catch {
+		return c.json({ error: 'Invalid or missing "key" parameter: must be a JSON array' }, 400)
+	}
+
+	if (!Array.isArray(parsed) || parsed.length === 0 || !parsed.every(isContextKeyPart)) {
+		return c.json({ error: 'Invalid or missing "key" parameter: must be a JSON array' }, 400)
+	}
+
+	const matchParam = c.req.query("match")
+	if (matchParam !== undefined && matchParam !== "exact" && matchParam !== "prefix") {
+		return c.json({ error: 'Invalid "match" parameter: must be "exact" or "prefix"' }, 400)
+	}
+
+	const user = c.get("user")!
+	const sessionManager = c.get("sessionManager")
+
+	let session
+	try {
+		session = await sessionManager.getOrCreate(user.id)
+	} catch (err) {
+		console.error("[handleGetContext] Failed to create session:", err)
+		return c.json({ error: "Service unavailable" }, 503)
+	}
+
+	const context = session.engine.currentContext()
+	const key = contextKey(...parsed)
+
+	if (matchParam === "exact") {
+		const value = context.get(key)
+		if (value === undefined) {
+			return c.json({ error: "Context key not found" }, 404)
+		}
+		return c.json({ match: "exact", value })
+	}
+
+	if (matchParam === "prefix") {
+		const entries = context.find(key)
+		if (entries.length === 0) {
+			return c.json({ error: "Context key not found" }, 404)
+		}
+		return c.json({ match: "prefix", entries })
+	}
+
+	// Default: single find() covers both exact and prefix matches
+	const entries = context.find(key)
+	if (entries.length === 0) {
+		return c.json({ error: "Context key not found" }, 404)
+	}
+
+	// If exactly one result with the same key length, treat as exact match
+	if (entries.length === 1 && entries[0]!.key.length === parsed.length) {
+		return c.json({ match: "exact", value: entries[0]!.value })
+	}
+
+	return c.json({ match: "prefix", entries })
+}
+
+/** Validates that a value is a valid ContextKeyPart (string, number, or plain object of primitives). */
+function isContextKeyPart(value: unknown): boolean {
+	if (typeof value === "string" || typeof value === "number") {
+		return true
+	}
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+		return Object.values(value).every(
+			(v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean",
+		)
+	}
+	return false
+}

apps/aelis-backend/src/enhancement/enhance-feed.ts

@@ -1,4 +1,4 @@
-import type { FeedItem } from "@aris/core"
+import type { FeedItem } from "@aelis/core"
 
 import type { LlmClient } from "./llm-client.ts"
 

apps/aelis-backend/src/enhancement/merge.test.ts

@@ -1,4 +1,4 @@
-import type { FeedItem } from "@aris/core"
+import type { FeedItem } from "@aelis/core"
 
 import { describe, expect, test } from "bun:test"
 
@@ -9,6 +9,7 @@ import { mergeEnhancement } from "./merge.ts"
 function makeItem(overrides: Partial<FeedItem> = {}): FeedItem {
 	return {
 		id: "item-1",
+		sourceId: "test",
 		type: "test",
 		timestamp: new Date("2025-01-01T00:00:00Z"),
 		data: { value: 42 },

apps/aelis-backend/src/enhancement/merge.ts

@@ -1,7 +1,9 @@
-import type { FeedItem } from "@aris/core"
+import type { FeedItem } from "@aelis/core"
 
 import type { EnhancementResult } from "./schema.ts"
 
+const ENHANCEMENT_SOURCE_ID = "aelis.enhancement"
+
 /**
  * Merges an EnhancementResult into feed items.
  *
@@ -10,7 +12,11 @@ import type { EnhancementResult } from "./schema.ts"
  * - Returns a new array (no mutation)
  * - Ignores fills for items/slots that don't exist
  */
-export function mergeEnhancement(items: FeedItem[], result: EnhancementResult, currentTime: Date): FeedItem[] {
+export function mergeEnhancement(
+	items: FeedItem[],
+	result: EnhancementResult,
+	currentTime: Date,
+): FeedItem[] {
 	const merged = items.map((item) => {
 		const fills = result.slotFills[item.id]
 		if (!fills || !item.slots) return item
@@ -31,6 +37,7 @@ export function mergeEnhancement(items: FeedItem[], result: EnhancementResult, c
 	for (const synthetic of result.syntheticItems) {
 		merged.push({
 			id: synthetic.id,
+			sourceId: ENHANCEMENT_SOURCE_ID,
 			type: synthetic.type,
 			timestamp: currentTime,
 			data: { text: synthetic.text },

apps/aelis-backend/src/enhancement/prompt-builder.test.ts

@@ -1,4 +1,4 @@
-import type { FeedItem } from "@aris/core"
+import type { FeedItem } from "@aelis/core"
 
 import { describe, expect, test } from "bun:test"
 
@@ -7,6 +7,7 @@ import { buildPrompt, hasUnfilledSlots } from "./prompt-builder.ts"
 function makeItem(overrides: Partial<FeedItem> = {}): FeedItem {
 	return {
 		id: "item-1",
+		sourceId: "test",
 		type: "test",
 		timestamp: new Date("2025-01-01T00:00:00Z"),
 		data: { value: 42 },
@@ -60,7 +61,9 @@ describe("buildPrompt", () => {
 
 		expect(parsed.items).toHaveLength(1)
 		expect((parsed.items as Array<Record<string, unknown>>)[0]!.id).toBe("item-1")
-		expect((parsed.items as Array<Record<string, unknown>>)[0]!.slots).toEqual({ insight: "Weather insight" })
+		expect((parsed.items as Array<Record<string, unknown>>)[0]!.slots).toEqual({
+			insight: "Weather insight",
+		})
 		expect((parsed.items as Array<Record<string, unknown>>)[0]!.type).toBeUndefined()
 		expect(parsed.context).toHaveLength(0)
 	})

apps/aelis-backend/src/enhancement/prompt-builder.ts

@@ -1,7 +1,7 @@
-import type { FeedItem } from "@aris/core"
+import type { FeedItem } from "@aelis/core"
 
-import { CalDavFeedItemType } from "@aris/source-caldav"
-import { CalendarFeedItemType } from "@aris/source-google-calendar"
+import { CalDavFeedItemType } from "@aelis/source-caldav"
+import { CalendarFeedItemType } from "@aelis/source-google-calendar"
 
 import systemPromptBase from "./prompts/system.txt"
 

apps/aelis-backend/src/enhancement/prompts/system.txt

@@ -1,4 +1,4 @@
-You are ARIS, a personal assistant. You enhance a user's feed by filling slots and optionally generating synthetic items.
+You are AELIS, a personal assistant. You enhance a user's feed by filling slots and optionally generating synthetic items.
 
 The user message is a JSON object with:
 - "items": feed items with data and named slots to fill. Each slot has a description of what to write.

apps/aelis-backend/src/lib/crypto.test.ts

@@ -0,0 +1,62 @@
+import { randomBytes } from "node:crypto"
+import { describe, expect, test } from "bun:test"
+
+import { CredentialEncryptor } from "./crypto.ts"
+
+const TEST_KEY = randomBytes(32).toString("base64")
+
+describe("CredentialEncryptor", () => {
+	const encryptor = new CredentialEncryptor(TEST_KEY)
+
+	test("round-trip with simple string", () => {
+		const plaintext = "hello world"
+		const encrypted = encryptor.encrypt(plaintext)
+		expect(encryptor.decrypt(encrypted)).toBe(plaintext)
+	})
+
+	test("round-trip with JSON credentials", () => {
+		const credentials = JSON.stringify({
+			accessToken: "ya29.a0AfH6SMB...",
+			refreshToken: "1//0dx...",
+			expiresAt: "2025-12-01T00:00:00Z",
+		})
+		const encrypted = encryptor.encrypt(credentials)
+		expect(encryptor.decrypt(encrypted)).toBe(credentials)
+	})
+
+	test("round-trip with empty string", () => {
+		const encrypted = encryptor.encrypt("")
+		expect(encryptor.decrypt(encrypted)).toBe("")
+	})
+
+	test("round-trip with unicode", () => {
+		const plaintext = "日本語テスト 🔐"
+		const encrypted = encryptor.encrypt(plaintext)
+		expect(encryptor.decrypt(encrypted)).toBe(plaintext)
+	})
+
+	test("each encryption produces different ciphertext (unique IV)", () => {
+		const plaintext = "same input"
+		const a = encryptor.encrypt(plaintext)
+		const b = encryptor.encrypt(plaintext)
+		expect(a).not.toEqual(b)
+		expect(encryptor.decrypt(a)).toBe(plaintext)
+		expect(encryptor.decrypt(b)).toBe(plaintext)
+	})
+
+	test("tampered ciphertext throws", () => {
+		const encrypted = encryptor.encrypt("secret")
+		encrypted[13]! ^= 0xff
+		expect(() => encryptor.decrypt(encrypted)).toThrow()
+	})
+
+	test("truncated data throws", () => {
+		expect(() => encryptor.decrypt(Buffer.alloc(10))).toThrow("Encrypted data is too short")
+	})
+
+	test("throws when key is wrong length", () => {
+		expect(() => new CredentialEncryptor(Buffer.from("too-short").toString("base64"))).toThrow(
+			"must be 32 bytes",
+		)
+	})
+})

apps/aelis-backend/src/lib/crypto.ts

@@ -0,0 +1,60 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto"
+
+const ALGORITHM = "aes-256-gcm"
+const IV_LENGTH = 12
+const AUTH_TAG_LENGTH = 16
+
+/**
+ * AES-256-GCM encryption for credential storage.
+ *
+ * Caches the parsed key on construction to avoid repeated
+ * env reads and Buffer allocations.
+ */
+export class CredentialEncryptor {
+	private readonly key: Buffer
+
+	constructor(base64Key: string) {
+		const key = Buffer.from(base64Key, "base64")
+		if (key.length !== 32) {
+			throw new Error(
+				`Encryption key must be 32 bytes (got ${key.length}). Generate with: openssl rand -base64 32`,
+			)
+		}
+		this.key = key
+	}
+
+	/**
+	 * Encrypts plaintext using AES-256-GCM.
+	 *
+	 * Output format: [12-byte IV][ciphertext][16-byte auth tag]
+	 */
+	encrypt(plaintext: string): Buffer {
+		const iv = randomBytes(IV_LENGTH)
+		const cipher = createCipheriv(ALGORITHM, this.key, iv)
+
+		const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()])
+		const authTag = cipher.getAuthTag()
+
+		return Buffer.concat([iv, encrypted, authTag])
+	}
+
+	/**
+	 * Decrypts a buffer produced by `encrypt`.
+	 *
+	 * Expects format: [12-byte IV][ciphertext][16-byte auth tag]
+	 */
+	decrypt(data: Buffer): string {
+		if (data.length < IV_LENGTH + AUTH_TAG_LENGTH) {
+			throw new Error("Encrypted data is too short")
+		}
+
+		const iv = data.subarray(0, IV_LENGTH)
+		const authTag = data.subarray(data.length - AUTH_TAG_LENGTH)
+		const ciphertext = data.subarray(IV_LENGTH, data.length - AUTH_TAG_LENGTH)
+
+		const decipher = createDecipheriv(ALGORITHM, this.key, iv)
+		decipher.setAuthTag(authTag)
+
+		return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8")
+	}
+}

apps/aelis-backend/src/location/http.ts

@@ -3,10 +3,9 @@ import type { Context, Hono } from "hono"
 import { type } from "arktype"
 import { createMiddleware } from "hono/factory"
 
+import type { AuthSessionMiddleware } from "../auth/session-middleware.ts"
 import type { UserSessionManager } from "../session/index.ts"
 
-import { requireSession } from "../auth/session-middleware.ts"
-
 type Env = { Variables: { sessionManager: UserSessionManager } }
 
 const locationInput = type({
@@ -16,16 +15,21 @@ const locationInput = type({
 	timestamp: "string.date.iso",
 })
 
+interface LocationHttpHandlersDeps {
+	sessionManager: UserSessionManager
+	authSessionMiddleware: AuthSessionMiddleware
+}
+
 export function registerLocationHttpHandlers(
 	app: Hono,
-	{ sessionManager }: { sessionManager: UserSessionManager },
+	{ sessionManager, authSessionMiddleware }: LocationHttpHandlersDeps,
 ) {
 	const inject = createMiddleware<Env>(async (c, next) => {
 		c.set("sessionManager", sessionManager)
 		await next()
 	})
 
-	app.post("/api/location", inject, requireSession, handleUpdateLocation)
+	app.post("/api/location", inject, authSessionMiddleware, handleUpdateLocation)
 }
 
 async function handleUpdateLocation(c: Context<Env>) {
@@ -44,8 +48,16 @@ async function handleUpdateLocation(c: Context<Env>) {
 
 	const user = c.get("user")!
 	const sessionManager = c.get("sessionManager")
-	const session = sessionManager.getOrCreate(user.id)
-	await session.engine.executeAction("aris.location", "update-location", {
+
+	let session
+	try {
+		session = await sessionManager.getOrCreate(user.id)
+	} catch (err) {
+		console.error("[handleUpdateLocation] Failed to create session:", err)
+		return c.json({ error: "Service unavailable" }, 503)
+	}
+
+	await session.engine.executeAction("aelis.location", "update-location", {
 		lat: result.lat,
 		lng: result.lng,
 		accuracy: result.accuracy,

apps/aelis-backend/src/location/provider.ts

@@ -0,0 +1,26 @@
+import { LocationSource } from "@aelis/source-location"
+
+import type { Database } from "../db/index.ts"
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+import { SourceDisabledError } from "../sources/errors.ts"
+import { sources } from "../sources/user-sources.ts"
+
+export class LocationSourceProvider implements FeedSourceProvider {
+	readonly sourceId = "aelis.location"
+	private readonly db: Database
+
+	constructor(db: Database) {
+		this.db = db
+	}
+
+	async feedSourceForUser(userId: string): Promise<LocationSource> {
+		const row = await sources(this.db, userId).find("aelis.location")
+
+		if (!row || !row.enabled) {
+			throw new SourceDisabledError("aelis.location", userId)
+		}
+
+		return new LocationSource()
+	}
+}

apps/aelis-backend/src/scripts/create-admin.ts

@@ -0,0 +1,63 @@
+/**
+ * Creates an admin user account via Better Auth's server-side API.
+ *
+ * Usage:
+ *   bun run src/scripts/create-admin.ts --name "Admin" --email admin@example.com --password secret123
+ *
+ * Requires DATABASE_URL and BETTER_AUTH_SECRET to be set (reads .env automatically).
+ */
+
+import { parseArgs } from "util"
+
+import { createAuth } from "../auth/index.ts"
+import { createDatabase } from "../db/index.ts"
+
+function parseCliArgs(): { name: string; email: string; password: string } {
+	const { values } = parseArgs({
+		args: Bun.argv.slice(2),
+		options: {
+			name: { type: "string" },
+			email: { type: "string" },
+			password: { type: "string" },
+		},
+		strict: true,
+	})
+
+	if (!values.name || !values.email || !values.password) {
+		console.error(
+			"Usage: bun run src/scripts/create-admin.ts --name <name> --email <email> --password <password>",
+		)
+		process.exit(1)
+	}
+
+	return { name: values.name, email: values.email, password: values.password }
+}
+
+async function main() {
+	const { name, email, password } = parseCliArgs()
+
+	const databaseUrl = process.env.DATABASE_URL
+	if (!databaseUrl) {
+		console.error("DATABASE_URL is not set")
+		process.exit(1)
+	}
+
+	const { db, close } = createDatabase(databaseUrl)
+
+	try {
+		const auth = createAuth(db)
+
+		const result = await auth.api.createUser({
+			body: { name, email, password, role: "admin" },
+		})
+
+		console.log(`Admin account created: ${result.user.id} (${result.user.email})`)
+	} finally {
+		await close()
+	}
+}
+
+main().catch((err) => {
+	console.error("Failed to create admin account:", err)
+	process.exit(1)
+})

apps/aelis-backend/src/server.ts

@@ -1,16 +1,21 @@
-import { LocationSource } from "@aris/source-location"
 import { Hono } from "hono"
 
 import { registerAuthHandlers } from "./auth/http.ts"
-import { requireSession } from "./auth/session-middleware.ts"
+import { createAuth } from "./auth/index.ts"
+import { createRequireSession } from "./auth/session-middleware.ts"
+import { createDatabase } from "./db/index.ts"
+import { registerFeedHttpHandlers } from "./engine/http.ts"
 import { createFeedEnhancer } from "./enhancement/enhance-feed.ts"
 import { createLlmClient } from "./enhancement/llm-client.ts"
-import { registerFeedHttpHandlers } from "./feed/http.ts"
 import { registerLocationHttpHandlers } from "./location/http.ts"
+import { LocationSourceProvider } from "./location/provider.ts"
 import { UserSessionManager } from "./session/index.ts"
 import { WeatherSourceProvider } from "./weather/provider.ts"
 
 function main() {
+	const { db, close: closeDb } = createDatabase(process.env.DATABASE_URL!)
+	const auth = createAuth(db)
+
 	const openrouterApiKey = process.env.OPENROUTER_API_KEY
 	const feedEnhancer = openrouterApiKey
 		? createFeedEnhancer({
@@ -26,8 +31,9 @@ function main() {
 
 	const sessionManager = new UserSessionManager({
 		providers: [
-			() => new LocationSource(),
+			new LocationSourceProvider(db),
 			new WeatherSourceProvider({
+				db,
 				credentials: {
 					privateKey: process.env.WEATHERKIT_PRIVATE_KEY!,
 					keyId: process.env.WEATHERKIT_KEY_ID!,
@@ -43,12 +49,20 @@ function main() {
 
 	app.get("/health", (c) => c.json({ status: "ok" }))
 
-	registerAuthHandlers(app)
+	const authSessionMiddleware = createRequireSession(auth)
+
+	registerAuthHandlers(app, auth)
+
 	registerFeedHttpHandlers(app, {
 		sessionManager,
-		authSessionMiddleware: requireSession,
+		authSessionMiddleware,
+	})
+	registerLocationHttpHandlers(app, { sessionManager, authSessionMiddleware })
+
+	process.on("SIGTERM", async () => {
+		await closeDb()
+		process.exit(0)
 	})
-	registerLocationHttpHandlers(app, { sessionManager })
 
 	return app
 }

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

@@ -0,0 +1,7 @@
+import type { FeedSource } from "@aelis/core"
+
+export interface FeedSourceProvider {
+	/** The source ID this provider is responsible for (e.g., "aelis.location"). */
+	readonly sourceId: string
+	feedSourceForUser(userId: string): Promise<FeedSource>
+}

apps/aelis-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/aelis-backend/src/session/user-session-manager.test.ts

@@ -0,0 +1,490 @@
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aelis/core"
+
+import { LocationSource } from "@aelis/source-location"
+import { WeatherSource } from "@aelis/source-weatherkit"
+import { describe, expect, mock, spyOn, test } from "bun:test"
+
+import type { FeedSourceProvider } from "./feed-source-provider.ts"
+
+import { UserSessionManager } from "./user-session-manager.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
+		},
+	}
+}
+
+function createStubProvider(
+	sourceId: string,
+	factory: (userId: string) => Promise<FeedSource> = async () => createStubSource(sourceId),
+): FeedSourceProvider {
+	return { sourceId, feedSourceForUser: factory }
+}
+
+const locationProvider: FeedSourceProvider = {
+	sourceId: "aelis.location",
+	async feedSourceForUser() {
+		return new LocationSource()
+	},
+}
+
+const weatherProvider: FeedSourceProvider = {
+	sourceId: "aelis.weather",
+	async feedSourceForUser() {
+		return new WeatherSource({ client: { fetch: async () => ({}) as never } })
+	},
+}
+
+describe("UserSessionManager", () => {
+	test("getOrCreate creates session on first call", async () => {
+		const manager = new UserSessionManager({ 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 () => {
+		const manager = new UserSessionManager({ 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 () => {
+		const manager = new UserSessionManager({ 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 () => {
+		const manager = new UserSessionManager({ providers: [locationProvider] })
+
+		const session1 = await manager.getOrCreate("user-1")
+		const session2 = await manager.getOrCreate("user-2")
+
+		const source1 = session1.getSource<LocationSource>("aelis.location")
+		const source2 = session2.getSource<LocationSource>("aelis.location")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("remove destroys session and allows re-creation", async () => {
+		const manager = new UserSessionManager({ 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", () => {
+		const manager = new UserSessionManager({ providers: [locationProvider] })
+
+		expect(() => manager.remove("unknown")).not.toThrow()
+	})
+
+	test("registers multiple providers", async () => {
+		const manager = new UserSessionManager({
+			providers: [locationProvider, weatherProvider],
+		})
+
+		const session = await manager.getOrCreate("user-1")
+
+		expect(session.getSource("aelis.location")).toBeDefined()
+		expect(session.getSource("aelis.weather")).toBeDefined()
+	})
+
+	test("refresh returns feed result through session", async () => {
+		const manager = new UserSessionManager({ 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 () => {
+		const manager = new UserSessionManager({ providers: [locationProvider] })
+
+		const session = await manager.getOrCreate("user-1")
+		await session.engine.executeAction("aelis.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		const source = session.getSource<LocationSource>("aelis.location")
+		expect(source?.lastLocation?.lat).toBe(51.5074)
+	})
+
+	test("subscribe receives updates after location push", async () => {
+		const manager = new UserSessionManager({ providers: [locationProvider] })
+		const callback = mock()
+
+		const session = await manager.getOrCreate("user-1")
+		session.engine.subscribe(callback)
+
+		await session.engine.executeAction("aelis.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 () => {
+		const manager = new UserSessionManager({ 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("aelis.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 () => {
+		const failingProvider: FeedSourceProvider = {
+			sourceId: "aelis.failing",
+			async feedSourceForUser() {
+				throw new Error("provider failed")
+			},
+		}
+
+		const manager = new UserSessionManager({
+			providers: [locationProvider, failingProvider],
+		})
+
+		const spy = spyOn(console, "error").mockImplementation(() => {})
+
+		const session = await manager.getOrCreate("user-1")
+
+		expect(session).toBeDefined()
+		expect(session.getSource("aelis.location")).toBeDefined()
+		expect(spy).toHaveBeenCalled()
+
+		spy.mockRestore()
+	})
+
+	test("throws AggregateError when all providers fail", async () => {
+		const manager = new UserSessionManager({
+			providers: [
+				{
+					sourceId: "aelis.fail-1",
+					async feedSourceForUser() {
+						throw new Error("first failed")
+					},
+				},
+				{
+					sourceId: "aelis.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 () => {
+		let callCount = 0
+		const manager = new UserSessionManager({
+			providers: [
+				{
+					sourceId: "aelis.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 () => {
+		let resolveProvider: () => void
+		const providerGate = new Promise<void>((r) => {
+			resolveProvider = r
+		})
+
+		const manager = new UserSessionManager({
+			providers: [
+				{
+					sourceId: "aelis.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()
+	})
+})
+
+describe("UserSessionManager.replaceProvider", () => {
+	test("replaces source in all active sessions", async () => {
+		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({ 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 () => {
+		const manager = new UserSessionManager({ providers: [locationProvider] })
+
+		const unknownProvider = createStubProvider("aelis.unknown")
+
+		await expect(manager.replaceProvider(unknownProvider)).rejects.toThrow(
+			"no existing provider with that sourceId",
+		)
+	})
+
+	test("removes source from session when new provider fails for a user", async () => {
+		const providerV1 = createStubProvider("test", async () => createStubSource("test"))
+		const manager = new UserSessionManager({ 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")).toBeUndefined()
+		expect(spy).toHaveBeenCalled()
+
+		spy.mockRestore()
+	})
+
+	test("new sessions use the replaced provider", async () => {
+		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({ 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 () => {
+		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({ 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 () => {
+		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({ 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)
+	})
+})

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

@@ -0,0 +1,139 @@
+import type { FeedSource } from "@aelis/core"
+
+import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
+import type { FeedSourceProvider } from "./feed-source-provider.ts"
+
+import { UserSession } from "./user-session.ts"
+
+export interface UserSessionManagerConfig {
+	providers: FeedSourceProvider[]
+	feedEnhancer?: FeedEnhancer | null
+}
+
+export class UserSessionManager {
+	private sessions = new Map<string, { userId: string; session: UserSession }>()
+	private pending = new Map<string, Promise<UserSession>>()
+	private readonly providers = new Map<string, FeedSourceProvider>()
+	private readonly feedEnhancer: FeedEnhancer | null
+
+	constructor(config: UserSessionManagerConfig) {
+		for (const provider of config.providers) {
+			this.providers.set(provider.sourceId, provider)
+		}
+		this.feedEnhancer = config.feedEnhancer ?? null
+	}
+
+	async getOrCreate(userId: string): Promise<UserSession> {
+		const existing = this.sessions.get(userId)
+		if (existing) return existing.session
+
+		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, { userId, session })
+			return session
+		} finally {
+			this.pending.delete(userId)
+		}
+	}
+
+	remove(userId: string): void {
+		const entry = this.sessions.get(userId)
+		if (entry) {
+			entry.session.destroy()
+			this.sessions.delete(userId)
+		}
+		// Cancel any in-flight creation so getOrCreate won't store the session
+		this.pending.delete(userId)
+	}
+
+	/**
+	 * Replaces a provider and updates all active sessions.
+	 * The new provider must have the same sourceId as an existing one.
+	 * For each active session, resolves a new source from the provider.
+	 * If the provider fails for a user, the old source is removed from that session.
+	 */
+	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 [, { userId, session }] of this.sessions) {
+			updates.push(this.updateSessionSource(provider, userId, session))
+		}
+
+		// Also update sessions that are currently being created so they
+		// don't land in this.sessions with a stale source.
+		for (const [userId, pendingPromise] of this.pending) {
+			updates.push(
+				pendingPromise
+					.then((session) => this.updateSessionSource(provider, userId, session))
+					.catch(() => {
+						// Session creation itself failed — nothing to update.
+					}),
+			)
+		}
+
+		await Promise.all(updates)
+	}
+
+	private async updateSessionSource(
+		provider: FeedSourceProvider,
+		userId: string,
+		session: UserSession,
+	): Promise<void> {
+		try {
+			const newSource = await provider.feedSourceForUser(userId)
+			session.replaceSource(provider.sourceId, newSource)
+		} catch (err) {
+			console.error(
+				`[UserSessionManager] replaceProvider("${provider.sourceId}") failed for user ${userId}:`,
+				err,
+			)
+			session.removeSource(provider.sourceId)
+		}
+	}
+
+	private async createSession(userId: string): Promise<UserSession> {
+		const results = await Promise.allSettled(
+			Array.from(this.providers.values()).map((p) => p.feedSourceForUser(userId)),
+		)
+
+		const sources: FeedSource[] = []
+		const errors: unknown[] = []
+
+		for (const result of results) {
+			if (result.status === "fulfilled") {
+				sources.push(result.value)
+			} else {
+				errors.push(result.reason)
+			}
+		}
+
+		if (sources.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(sources, this.feedEnhancer)
+	}
+}

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

@@ -1,6 +1,6 @@
-import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aris/core"
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aelis/core"
 
-import { LocationSource } from "@aris/source-location"
+import { LocationSource } from "@aelis/source-location"
 import { describe, expect, test } from "bun:test"
 
 import { UserSession } from "./user-session.ts"
@@ -36,7 +36,7 @@ describe("UserSession", () => {
 		const location = new LocationSource()
 		const session = new UserSession([location])
 
-		const result = session.getSource<LocationSource>("aris.location")
+		const result = session.getSource<LocationSource>("aelis.location")
 
 		expect(result).toBe(location)
 	})
@@ -59,7 +59,7 @@ describe("UserSession", () => {
 		const location = new LocationSource()
 		const session = new UserSession([location])
 
-		await session.engine.executeAction("aris.location", "update-location", {
+		await session.engine.executeAction("aelis.location", "update-location", {
 			lat: 51.5,
 			lng: -0.1,
 			accuracy: 10,
@@ -76,6 +76,7 @@ describe("UserSession.feed", () => {
 		const items: FeedItem[] = [
 			{
 				id: "item-1",
+				sourceId: "test",
 				type: "test",
 				timestamp: new Date("2025-01-01T00:00:00.000Z"),
 				data: { value: 42 },
@@ -93,6 +94,7 @@ describe("UserSession.feed", () => {
 		const items: FeedItem[] = [
 			{
 				id: "item-1",
+				sourceId: "test",
 				type: "test",
 				timestamp: new Date("2025-01-01T00:00:00.000Z"),
 				data: { value: 42 },
@@ -113,6 +115,7 @@ describe("UserSession.feed", () => {
 		const items: FeedItem[] = [
 			{
 				id: "item-1",
+				sourceId: "test",
 				type: "test",
 				timestamp: new Date("2025-01-01T00:00:00.000Z"),
 				data: { value: 42 },
@@ -139,6 +142,7 @@ describe("UserSession.feed", () => {
 		let currentItems: FeedItem[] = [
 			{
 				id: "item-1",
+				sourceId: "test",
 				type: "test",
 				timestamp: new Date("2025-01-01T00:00:00.000Z"),
 				data: { version: 1 },
@@ -169,6 +173,7 @@ describe("UserSession.feed", () => {
 		currentItems = [
 			{
 				id: "item-1",
+				sourceId: "test",
 				type: "test",
 				timestamp: new Date("2025-01-02T00:00:00.000Z"),
 				data: { version: 2 },
@@ -190,6 +195,7 @@ describe("UserSession.feed", () => {
 		const items: FeedItem[] = [
 			{
 				id: "item-1",
+				sourceId: "test",
 				type: "test",
 				timestamp: new Date("2025-01-01T00:00:00.000Z"),
 				data: { value: 42 },
@@ -208,3 +214,175 @@ describe("UserSession.feed", () => {
 		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([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([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([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([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([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([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([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([createStubSource("test")])
+
+		expect(() => session.removeSource("unknown")).not.toThrow()
+		expect(session.getSource("test")).toBeDefined()
+	})
+})

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

@@ -1,4 +1,4 @@
-import { FeedEngine, type FeedItem, type FeedResult, type FeedSource } from "@aris/core"
+import { FeedEngine, type FeedItem, type FeedResult, type FeedSource } from "@aelis/core"
 
 import type { FeedEnhancer } from "../enhancement/enhance-feed.ts"
 
@@ -67,6 +67,59 @@ export class UserSession {
 		return this.sources.get(sourceId) as T | undefined
 	}
 
+	/**
+	 * 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

apps/aelis-backend/src/sources/errors.ts

@@ -0,0 +1,32 @@
+/**
+ * Thrown by a FeedSourceProvider when the source is not enabled for a user.
+ *
+ * UserSessionManager's Promise.allSettled handles this gracefully —
+ * the source is excluded from the session without crashing.
+ */
+export class SourceDisabledError extends Error {
+	readonly sourceId: string
+	readonly userId: string
+
+	constructor(sourceId: string, userId: string) {
+		super(`Source "${sourceId}" is not enabled for user "${userId}"`)
+		this.name = "SourceDisabledError"
+		this.sourceId = sourceId
+		this.userId = userId
+	}
+}
+
+/**
+ * Thrown when an operation targets a user source that doesn't exist.
+ */
+export class SourceNotFoundError extends Error {
+	readonly sourceId: string
+	readonly userId: string
+
+	constructor(sourceId: string, userId: string) {
+		super(`Source "${sourceId}" not found for user "${userId}"`)
+		this.name = "SourceNotFoundError"
+		this.sourceId = sourceId
+		this.userId = userId
+	}
+}

apps/aelis-backend/src/sources/user-sources.ts

@@ -0,0 +1,79 @@
+import { and, eq } from "drizzle-orm"
+
+import type { Database } from "../db/index.ts"
+
+import { userSources } from "../db/schema.ts"
+import { SourceNotFoundError } from "./errors.ts"
+
+export function sources(db: Database, userId: string) {
+	return {
+		/** Returns all enabled sources for the user. */
+		async enabled() {
+			return db
+				.select()
+				.from(userSources)
+				.where(and(eq(userSources.userId, userId), eq(userSources.enabled, true)))
+		},
+
+		/** Returns a specific source by ID, or undefined. */
+		async find(sourceId: string) {
+			const rows = await db
+				.select()
+				.from(userSources)
+				.where(and(eq(userSources.userId, userId), eq(userSources.sourceId, sourceId)))
+				.limit(1)
+
+			return rows[0]
+		},
+
+		/** Enables a source for the user. Throws if the source row doesn't exist. */
+		async enableSource(sourceId: string) {
+			const rows = await db
+				.update(userSources)
+				.set({ enabled: true, updatedAt: new Date() })
+				.where(and(eq(userSources.userId, userId), eq(userSources.sourceId, sourceId)))
+				.returning({ id: userSources.id })
+
+			if (rows.length === 0) {
+				throw new SourceNotFoundError(sourceId, userId)
+			}
+		},
+
+		/** Disables a source for the user. Throws if the source row doesn't exist. */
+		async disableSource(sourceId: string) {
+			const rows = await db
+				.update(userSources)
+				.set({ enabled: false, updatedAt: new Date() })
+				.where(and(eq(userSources.userId, userId), eq(userSources.sourceId, sourceId)))
+				.returning({ id: userSources.id })
+
+			if (rows.length === 0) {
+				throw new SourceNotFoundError(sourceId, userId)
+			}
+		},
+
+		/** Creates or updates the config for a source. */
+		async upsertConfig(sourceId: string, config: Record<string, unknown>) {
+			await db
+				.insert(userSources)
+				.values({ userId, sourceId, config })
+				.onConflictDoUpdate({
+					target: [userSources.userId, userSources.sourceId],
+					set: { config, updatedAt: new Date() },
+				})
+		},
+
+		/** Updates the encrypted credentials for a source. Throws if the source row doesn't exist. */
+		async updateCredentials(sourceId: string, credentials: Buffer) {
+			const rows = await db
+				.update(userSources)
+				.set({ credentials, updatedAt: new Date() })
+				.where(and(eq(userSources.userId, userId), eq(userSources.sourceId, sourceId)))
+				.returning({ id: userSources.id })
+
+			if (rows.length === 0) {
+				throw new SourceNotFoundError(sourceId, userId)
+			}
+		},
+	}
+}

apps/aelis-backend/src/tfl/provider.ts

@@ -0,0 +1,48 @@
+import { TflSource, type ITflApi, type TflLineId } from "@aelis/source-tfl"
+import { type } from "arktype"
+
+import type { Database } from "../db/index.ts"
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+import { SourceDisabledError } from "../sources/errors.ts"
+import { sources } from "../sources/user-sources.ts"
+
+export type TflSourceProviderOptions =
+	| { db: Database; apiKey: string; client?: never }
+	| { db: Database; apiKey?: never; client: ITflApi }
+
+const tflConfig = type({
+	"lines?": "string[]",
+})
+
+export class TflSourceProvider implements FeedSourceProvider {
+	readonly sourceId = "aelis.tfl"
+	private readonly db: Database
+	private readonly apiKey: string | undefined
+	private readonly client: ITflApi | undefined
+
+	constructor(options: TflSourceProviderOptions) {
+		this.db = options.db
+		this.apiKey = "apiKey" in options ? options.apiKey : undefined
+		this.client = "client" in options ? options.client : undefined
+	}
+
+	async feedSourceForUser(userId: string): Promise<TflSource> {
+		const row = await sources(this.db, userId).find("aelis.tfl")
+
+		if (!row || !row.enabled) {
+			throw new SourceDisabledError("aelis.tfl", userId)
+		}
+
+		const parsed = tflConfig(row.config ?? {})
+		if (parsed instanceof type.errors) {
+			throw new Error(`Invalid TFL config for user ${userId}: ${parsed.summary}`)
+		}
+
+		return new TflSource({
+			apiKey: this.apiKey,
+			client: this.client,
+			lines: parsed.lines as TflLineId[] | undefined,
+		})
+	}
+}

apps/aelis-backend/src/weather/provider.ts

@@ -0,0 +1,54 @@
+import { WeatherSource, type WeatherSourceOptions } from "@aelis/source-weatherkit"
+import { type } from "arktype"
+
+import type { Database } from "../db/index.ts"
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+import { SourceDisabledError } from "../sources/errors.ts"
+import { sources } from "../sources/user-sources.ts"
+
+export interface WeatherSourceProviderOptions {
+	db: Database
+	credentials: WeatherSourceOptions["credentials"]
+	client?: WeatherSourceOptions["client"]
+}
+
+const weatherConfig = type({
+	"units?": "'metric' | 'imperial'",
+	"hourlyLimit?": "number",
+	"dailyLimit?": "number",
+})
+
+export class WeatherSourceProvider implements FeedSourceProvider {
+	readonly sourceId = "aelis.weather"
+	private readonly db: Database
+	private readonly credentials: WeatherSourceOptions["credentials"]
+	private readonly client: WeatherSourceOptions["client"]
+
+	constructor(options: WeatherSourceProviderOptions) {
+		this.db = options.db
+		this.credentials = options.credentials
+		this.client = options.client
+	}
+
+	async feedSourceForUser(userId: string): Promise<WeatherSource> {
+		const row = await sources(this.db, userId).find("aelis.weather")
+
+		if (!row || !row.enabled) {
+			throw new SourceDisabledError("aelis.weather", userId)
+		}
+
+		const parsed = weatherConfig(row.config ?? {})
+		if (parsed instanceof type.errors) {
+			throw new Error(`Invalid weather config for user ${userId}: ${parsed.summary}`)
+		}
+
+		return new WeatherSource({
+			credentials: this.credentials,
+			client: this.client,
+			units: parsed.units,
+			hourlyLimit: parsed.hourlyLimit,
+			dailyLimit: parsed.dailyLimit,
+		})
+	}
+}

apps/aelis-client/app.json

@@ -1,11 +1,11 @@
 {
 	"expo": {
-		"name": "Aris",
-		"slug": "aris-client",
+		"name": "Aelis",
+		"slug": "aelis-client",
 		"version": "1.0.0",
 		"orientation": "portrait",
 		"icon": "./assets/images/icon.png",
-		"scheme": "aris",
+		"scheme": "aelis",
 		"userInterfaceStyle": "automatic",
 		"newArchEnabled": true,
 		"ios": {
@@ -15,7 +15,7 @@
 				},
 				"ITSAppUsesNonExemptEncryption": false
 			},
-			"bundleIdentifier": "sh.nym.aris"
+			"bundleIdentifier": "sh.nym.aelis"
 		},
 		"android": {
 			"adaptiveIcon": {
@@ -26,7 +26,7 @@
 			},
 			"edgeToEdgeEnabled": true,
 			"predictiveBackGestureEnabled": false,
-			"package": "sh.nym.aris"
+			"package": "sh.nym.aelis"
 		},
 		"web": {
 			"output": "static",