Merge branch 'main' into fix/frontend-api-routes

fix(api): hash session token before DB lookup to match Better-Auth storage

.github/workflows/ci.yml

@@ -17,6 +17,9 @@ permissions:
 env:
   REGISTRY: ghcr.io
   IMAGE_NAME: cartsnitch/cartsnitch
+  AUTH_IMAGE_NAME: cartsnitch/auth
+  RECEIPTWITNESS_IMAGE_NAME: cartsnitch/receiptwitness
+  API_IMAGE_NAME: cartsnitch/api
 
 jobs:
   lint:
@@ -45,9 +48,59 @@ jobs:
       - name: Run tests
         run: npx vitest run
 
+  audit:
+    runs-on: runners-cartsnitch
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - name: Check for vulnerabilities
+        run: npm audit --audit-level=high
+
+  e2e:
+    runs-on: runners-cartsnitch
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npx playwright test
+
+  lighthouse:
+    runs-on: runners-cartsnitch
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - name: Install Chromium for Lighthouse
+        run: |
+          npm install -g playwright
+          npx playwright install --with-deps chromium
+      - name: Start preview server
+        run: |
+          npm run preview &
+          npx wait-on http://localhost:4173/ --timeout 30000
+      - name: Run Lighthouse CI
+        run: |
+          CHROME_PATH=$(find /home/runner/.cache/ms-playwright -name chrome -type f 2>/dev/null | head -1)
+          npm install -g @lhci/cli
+          CHROME_PATH="$CHROME_PATH" lhci autorun --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage"
+
   build-and-push:
     runs-on: runners-cartsnitch
-    needs: [lint, test]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [lint, test, e2e]
     outputs:
       calver_tag: ${{ steps.calver.outputs.version }}
     steps:
@@ -72,6 +125,13 @@ jobs:
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "CalVer tag: $VERSION"
 
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
       - name: Log in to GHCR
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: docker/login-action@v3
@@ -107,10 +167,183 @@ jobs:
           git tag "v${{ steps.calver.outputs.version }}"
           git push origin "v${{ steps.calver.outputs.version }}"
 
+  build-and-push-auth:
+    runs-on: runners-cartsnitch
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [lint, test, e2e]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then
+            VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
+            VERSION="${DATE_TAG}.2"
+          else
+            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
+            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to GHCR
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (auth)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.AUTH_IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build and push auth Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./auth
+          file: ./auth/Dockerfile
+          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  build-and-push-receiptwitness:
+    runs-on: runners-cartsnitch
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [lint, test]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then VERSION="${DATE_TAG}.2"
+          else BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//"); VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"; fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to GHCR
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.RECEIPTWITNESS_IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build and push receiptwitness image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./receiptwitness/Dockerfile
+          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  build-and-push-api:
+    runs-on: runners-cartsnitch
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [lint, test]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then VERSION="${DATE_TAG}.2"
+          else BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//"); VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"; fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to GHCR
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (API)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.API_IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build and push API Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./api/Dockerfile
+          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
   deploy-dev:
     runs-on: runners-cartsnitch
-    needs: [build-and-push]
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [build-and-push, build-and-push-auth, build-and-push-receiptwitness, build-and-push-api]
+    if: always() && !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/main'
     steps:
       - name: Generate GitHub App token
         id: app-token
@@ -118,6 +351,8 @@ jobs:
         with:
           app-id: ${{ secrets.CARTSNITCH_APP_ID }}
           private-key: ${{ secrets.CARTSNITCH_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: infra
 
       - name: Checkout infra repo
         uses: actions/checkout@v4
@@ -125,40 +360,43 @@ jobs:
           repository: cartsnitch/infra
           token: ${{ steps.app-token.outputs.token }}
           ref: main
+          path: infra
 
       - name: Install kubectl
         uses: azure/setup-kubectl@v4
 
-      - name: Update dev overlay image tag
-        working-directory: apps/overlays/dev
+      - name: Install kustomize
+        uses: imranismail/setup-kustomize@v2
+
+      - name: Update frontend image tag
+        if: needs.build-and-push.result == 'success'
         run: |
+          cd infra/apps/overlays/dev
           kustomize edit set image ghcr.io/cartsnitch/cartsnitch:${{ needs.build-and-push.outputs.calver_tag }}
 
+      - name: Update auth image tag
+        if: needs.build-and-push-auth.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/auth:${{ needs.build-and-push-auth.outputs.calver_tag }}
+
+      - name: Update receiptwitness image tag
+        if: needs.build-and-push-receiptwitness.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/receiptwitness:${{ needs.build-and-push-receiptwitness.outputs.calver_tag }}
+
+      - name: Update api image tag
+        if: needs.build-and-push-api.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/api:${{ needs.build-and-push-api.outputs.calver_tag }}
+
       - name: Commit and push to infra
         run: |
-          cd apps/overlays/dev
+          cd infra
           git config user.name "cartsnitch-ci[bot]"
           git config user.email "cartsnitch-ci[bot]@users.noreply.github.com"
-          git add kustomization.yaml
-          git commit -m "ci(dev): update cartsnitch image to ${{ needs.build-and-push.outputs.calver_tag }}"
+          git add apps/overlays/dev/kustomization.yaml
+          git commit -m "ci(dev): update cartsnitch, auth, receiptwitness, and api images"
           git push origin main
-
-  trigger-uat:
-    runs-on: runners-cartsnitch
-    needs: [deploy-dev, build-and-push]
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    steps:
-      - name: Create UAT issue in Paperclip
-        run: |
-          curl -s -X POST \
-            -H "Authorization: Bearer ${{ secrets.PAPERCLIP_API_KEY }}" \
-            -H "Content-Type: application/json" \
-            "${{ secrets.PAPERCLIP_API_URL }}/api/companies/${{ secrets.PAPERCLIP_COMPANY_ID }}/issues" \
-            --data-raw '{
-              "title": "UAT: cartsnitch ${{ needs.build-and-push.outputs.calver_tag }} deployed to dev",
-              "description": "## UAT Required\n\nService: cartsnitch (frontend)\nImage: ghcr.io/cartsnitch/cartsnitch:${{ needs.build-and-push.outputs.calver_tag }}\nCommit: ${{ github.sha }}\nWorkflow run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\n\nPlease run full regression against cartsnitch.dev.farh.net",
-              "status": "todo",
-              "priority": "high",
-              "assigneeAgentId": "1fc33bd9-308c-4abf-a355-87d12b6b0064",
-              "projectId": "05f7827d-54df-4ff8-9b27-293ffba6e049"
-            }'

.gitignore

@@ -11,6 +11,7 @@ node_modules
 dist
 dist-ssr
 *.local
+.env
 
 # Editor directories and files
 .vscode/*

CLAUDE.md

@@ -12,6 +12,7 @@ CartSnitch is a self-hosted grocery price intelligence platform. This repo (`car
 | Directory | Service | Purpose |
 |-----------|---------|---------|
 | `/` (root) | Frontend | React PWA, mobile-first (this directory) |
+| `auth/` | Auth | Better-Auth Node.js service (session management, email/password, OAuth) |
 | `api/` | API Gateway | Frontend-facing REST API |
 | `common/` | Common | Shared Python models, schemas, Alembic migrations |
 | `receiptwitness/` | ReceiptWitness | Purchase data ingestion via retailer scrapers |
@@ -166,9 +167,13 @@ frontend/
 
 All data comes from the CartSnitch API gateway (`cartsnitch/api`). Base URL configured via environment variable `VITE_API_URL`.
 
-- JWT auth: store access token in memory (not localStorage), refresh token in httpOnly cookie if possible, or secure storage.
+- **Authentication via Better-Auth** (`auth/` service). Sessions are managed via httpOnly cookies — no tokens in localStorage or memory.
+  - Auth service URL configured via `VITE_AUTH_URL` (default: `http://localhost:3001`)
+  - Frontend uses `better-auth/react` client for sign-in, sign-up, sign-out, and `useSession()` hook
+  - API gateway validates sessions by querying the shared `sessions` table in Postgres
+  - Both cookie-based and Bearer token auth are supported (cookies for web, Bearer for API clients)
 - TanStack Query handles caching, background refetching, and optimistic updates.
-- API client should handle 401 responses by attempting token refresh before retrying.
+- API client sends `credentials: 'include'` on all requests to forward session cookies.
 
 ## Development Workflow
 

README.md

@@ -1,45 +1 @@
-# CartSnitch Monorepo
-
-CartSnitch is a self-hosted grocery price intelligence platform. This repo consolidates the core services and the flagship frontend PWA.
-
-## Services
-
-| Directory | Service | Purpose |
-|-----------|---------|---------|
-| `/` (root) | **Frontend** | React 18 PWA — mobile-first price intelligence UI |
-| `api/` | **API Gateway** | FastAPI — frontend-facing REST API |
-| `common/` | **Common** | Shared Python models, schemas, Alembic migrations |
-| `receiptwitness/` | **ReceiptWitness** | Purchase ingestion via retailer scrapers |
-
-## Quick Start
-
-### Frontend (root)
-
-```bash
-npm install
-npm run dev        # http://localhost:5173
-npm run build      # production build
-npm run test       # unit tests (Vitest)
-```
-
-### Python Services
-
-Each Python service uses [uv](https://github.com/astral-sh/uv) and has its own `pyproject.toml`:
-
-```bash
-cd api             # or common / receiptwitness
-uv sync
-uv run pytest
-```
-
-## Development Workflow
-
-- **Never push directly to main.** Always open a PR from a feature branch.
-- Branch naming: `feature/<description>` or `fix/<description>`
-- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
-
-## Architecture
-
-For full details see [CLAUDE.md](./CLAUDE.md) or the per-service `CLAUDE.md` in each subdirectory.
-
-CartSnitch is a polyrepo-style monorepo: each service can be built and deployed independently, but sharing code between `common/` and the other Python services is done via local path dependencies in `pyproject.toml`.
+# CartSnitch

api/.github/workflows/ci.yml

@@ -1,164 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  packages: write
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: cartsnitch/api
-
-jobs:
-  lint:
-    runs-on: runners-cartsnitch
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - run: pip install ruff
-      - name: Ruff lint
-        run: ruff check .
-      - name: Ruff format check
-        run: ruff format --check .
-
-  typecheck:
-    runs-on: runners-cartsnitch
-    continue-on-error: true
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y libpq-dev build-essential
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git"
-      - run: pip install -e ".[dev]" mypy
-      - name: Type check
-        run: mypy src/cartsnitch_api
-
-  test:
-    runs-on: runners-cartsnitch
-    services:
-      postgres:
-        image: postgres:15-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        env:
-          POSTGRES_USER: cartsnitch
-          POSTGRES_PASSWORD: cartsnitch_test
-          POSTGRES_DB: cartsnitch_test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-      redis:
-        image: redis:7-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-    env:
-      CARTSNITCH_DATABASE_URL: postgresql+asyncpg://cartsnitch:cartsnitch_test@localhost:5432/cartsnitch_test
-      CARTSNITCH_REDIS_URL: redis://localhost:6379/0
-      CARTSNITCH_JWT_SECRET_KEY: test-secret-do-not-use-in-prod
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y libpq-dev build-essential
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git"
-      - run: pip install -e ".[dev]"
-      - name: Run tests
-        run: pytest --tb=short -q
-
-  build-and-push:
-    runs-on: runners-cartsnitch
-    needs: [lint, test]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate CalVer tag
-        id: calver
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          DATE_TAG=$(date -u +%Y.%m.%d)
-          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
-          if [ -z "$EXISTING" ]; then
-            VERSION="$DATE_TAG"
-          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
-            VERSION="${DATE_TAG}.2"
-          else
-            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
-            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "CalVer tag: $VERSION"
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Log in to GHCR
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=sha,prefix=sha-
-            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
-            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
-
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          target: prod
-
-      - name: Create git tag
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          git tag "v${{ steps.calver.outputs.version }}"
-          git push origin "v${{ steps.calver.outputs.version }}"

api/Dockerfile

@@ -1,3 +1,5 @@
+# Stage 1: Build dependencies
+# Build context is the repo root.  Paths below are relative to the root.
 FROM python:3.12-slim AS build
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -6,16 +8,21 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
-COPY pyproject.toml ./
-COPY src/ ./src/
+COPY api/pyproject.toml ./
+COPY api/src/ ./src/
 RUN pip install --no-cache-dir --prefix=/install .
 
+# Stage 2: Production image
 FROM python:3.12-slim AS prod
 
+RUN apt-get update && apt-get install -y --no-install-recommends libpq5 && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
 RUN adduser --system --group --uid 1000 app
 COPY --from=build /install /usr/local
-COPY src/ ./src/
+COPY api/src/ ./src/
+COPY api/alembic.ini ./
+COPY api/alembic/ ./alembic/
 
 USER 1000
 EXPOSE 8000
@@ -23,4 +30,4 @@ EXPOSE 8000
 HEALTHCHECK --interval=30s --timeout=3s \
     CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
 
-CMD ["uvicorn", "cartsnitch_api.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["sh", "-c", "python -m alembic upgrade head && uvicorn cartsnitch_api.main:app --host 0.0.0.0 --port 8000"]

api/alembic/versions/002_better_auth_tables.py

@@ -0,0 +1,101 @@
+"""Add Better-Auth tables and extend users table.
+
+Creates sessions, accounts, and verifications tables for Better-Auth.
+Adds email_verified and image columns to existing users table.
+Migrates password hashes from users.hashed_password to accounts.password.
+
+Revision ID: 002_better_auth_tables
+Revises: 001_encrypt_session_data
+Create Date: 2026-03-28
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import text
+
+from alembic import op
+
+revision = "002_better_auth_tables"
+down_revision = "001_encrypt_session_data"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # --- Extend users table for Better-Auth compatibility ---
+    op.add_column("users", sa.Column("email_verified", sa.Boolean(), nullable=False, server_default="false"))
+    op.add_column("users", sa.Column("image", sa.Text(), nullable=True))
+
+    # --- Create sessions table ---
+    op.create_table(
+        "sessions",
+        sa.Column("id", sa.Text(), nullable=False),
+        sa.Column("token", sa.Text(), nullable=False),
+        sa.Column("user_id", sa.Text(), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("ip_address", sa.Text(), nullable=True),
+        sa.Column("user_agent", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_sessions_token", "sessions", ["token"], unique=True)
+    op.create_index("ix_sessions_user_id", "sessions", ["user_id"])
+
+    # --- Create accounts table ---
+    op.create_table(
+        "accounts",
+        sa.Column("id", sa.Text(), nullable=False),
+        sa.Column("user_id", sa.Text(), nullable=False),
+        sa.Column("account_id", sa.Text(), nullable=False),
+        sa.Column("provider_id", sa.Text(), nullable=False),
+        sa.Column("access_token", sa.Text(), nullable=True),
+        sa.Column("refresh_token", sa.Text(), nullable=True),
+        sa.Column("access_token_expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("refresh_token_expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("scope", sa.Text(), nullable=True),
+        sa.Column("id_token", sa.Text(), nullable=True),
+        sa.Column("password", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_accounts_user_id", "accounts", ["user_id"])
+
+    # --- Create verifications table ---
+    op.create_table(
+        "verifications",
+        sa.Column("id", sa.Text(), nullable=False),
+        sa.Column("identifier", sa.Text(), nullable=False),
+        sa.Column("value", sa.Text(), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+    # --- Migrate existing password hashes to accounts table ---
+    # For each user with a hashed_password, create a 'credential' account row
+    conn = op.get_bind()
+    users = conn.execute(
+        text("SELECT id, hashed_password FROM users WHERE hashed_password IS NOT NULL")
+    ).fetchall()
+
+    for user_id, hashed_password in users:
+        user_id_str = str(user_id)
+        conn.execute(
+            text(
+                "INSERT INTO accounts (id, user_id, account_id, provider_id, password, created_at, updated_at) "
+                "VALUES (gen_random_uuid()::text, :user_id, :account_id, 'credential', :password, now(), now())"
+            ),
+            {"user_id": user_id_str, "account_id": user_id_str, "password": hashed_password},
+        )
+
+
+def downgrade() -> None:
+    op.drop_table("verifications")
+    op.drop_table("accounts")
+    op.drop_index("ix_sessions_user_id", table_name="sessions")
+    op.drop_index("ix_sessions_token", table_name="sessions")
+    op.drop_table("sessions")
+    op.drop_column("users", "image")
+    op.drop_column("users", "email_verified")

api/alembic/versions/003_make_users_hashed_password_nullable.py

@@ -0,0 +1,26 @@
+"""Make users.hashed_password nullable.
+
+Better-Auth inserts users without hashed_password (passwords live in the
+accounts table). This column is now purely optional.
+
+Revision ID: 003_make_users_hashed_password_nullable
+Revises: 002_better_auth_tables
+Create Date: 2026-03-30
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "003_make_users_hashed_password_nullable"
+down_revision = "002_better_auth_tables"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.alter_column("users", "hashed_password", existing_type=sa.String(255), nullable=True)
+
+
+def downgrade() -> None:
+    op.alter_column("users", "hashed_password", existing_type=sa.String(255), nullable=False)

api/alembic/versions/004_fix_user_id_text.py

@@ -0,0 +1,122 @@
+"""Fix users.id UUID->text type mismatch for Better-Auth compatibility.
+
+Better-Auth generates nanoid-style text IDs (e.g. pGud2ln2WAFHC0KYjBVKR4Rc7mM8OcTI),
+but the users table was using PostgreSQL uuid type. When Better-Auth tries to INSERT
+a new user, Postgres throws:
+  ERROR: invalid input syntax for type uuid: "pGud2ln2WAFHC0KYjBVKR4Rc7mM8OcTI"
+
+The sessions, accounts, and verifications tables already use text IDs — only users,
+user_store_accounts.user_id, and purchases.user_id needed fixing.
+
+Revision ID: 004_fix_user_id_text
+Revises: 003_make_users_hashed_password_nullable
+Create Date: 2026-03-31
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import text
+
+from alembic import op
+
+revision = "004_fix_user_id_text"
+down_revision = "003_make_users_hashed_password_nullable"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Step 1: Drop existing FK constraints
+    op.execute(text("ALTER TABLE user_store_accounts DROP CONSTRAINT IF EXISTS user_store_accounts_user_id_fkey"))
+    op.execute(text("ALTER TABLE purchases DROP CONSTRAINT IF EXISTS purchases_user_id_fkey"))
+
+    # Step 2: Alter users.id from uuid to text
+    op.alter_column(
+        "users",
+        "id",
+        type_=sa.Text(),
+        existing_type=sa.UUID(),
+        postgresql_using="id::text",
+    )
+
+    # Step 3: Alter user_store_accounts.user_id from uuid to text
+    op.alter_column(
+        "user_store_accounts",
+        "user_id",
+        type_=sa.Text(),
+        existing_type=sa.UUID(),
+        postgresql_using="user_id::text",
+    )
+
+    # Step 4: Alter purchases.user_id from uuid to text
+    op.alter_column(
+        "purchases",
+        "user_id",
+        type_=sa.Text(),
+        existing_type=sa.UUID(),
+        postgresql_using="user_id::text",
+    )
+
+    # Step 5: Re-add FK constraints
+    op.execute(
+        text(
+            "ALTER TABLE user_store_accounts "
+            "ADD CONSTRAINT user_store_accounts_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
+    op.execute(
+        text(
+            "ALTER TABLE purchases "
+            "ADD CONSTRAINT purchases_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
+
+
+def downgrade() -> None:
+    # Drop FK constraints
+    op.execute(text("ALTER TABLE user_store_accounts DROP CONSTRAINT IF EXISTS user_store_accounts_user_id_fkey"))
+    op.execute(text("ALTER TABLE purchases DROP CONSTRAINT IF EXISTS purchases_user_id_fkey"))
+
+    # Revert users.id from text to uuid
+    op.alter_column(
+        "users",
+        "id",
+        type_=sa.UUID(),
+        existing_type=sa.Text(),
+        postgresql_using="id::uuid",
+    )
+
+    # Revert user_store_accounts.user_id from text to uuid
+    op.alter_column(
+        "user_store_accounts",
+        "user_id",
+        type_=sa.UUID(),
+        existing_type=sa.Text(),
+        postgresql_using="user_id::uuid",
+    )
+
+    # Revert purchases.user_id from text to uuid
+    op.alter_column(
+        "purchases",
+        "user_id",
+        type_=sa.UUID(),
+        existing_type=sa.Text(),
+        postgresql_using="user_id::uuid",
+    )
+
+    # Re-add FK constraints (PostgreSQL will auto-name them)
+    op.execute(
+        text(
+            "ALTER TABLE user_store_accounts "
+            "ADD CONSTRAINT user_store_accounts_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
+    op.execute(
+        text(
+            "ALTER TABLE purchases "
+            "ADD CONSTRAINT purchases_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )

api/src/cartsnitch_api/auth/dependencies.py

@@ -1,34 +1,92 @@
-"""FastAPI dependency injection for authentication."""
+"""FastAPI dependency injection for authentication.
 
+Validates Better-Auth session tokens from cookies or Bearer header.
+Sessions are verified by querying the shared sessions table directly.
+"""
+
+from datetime import UTC, datetime
+from hashlib import sha256
 from uuid import UUID
 
-from fastapi import Depends, Header, HTTPException, status
+from fastapi import Cookie, Depends, Header, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
 
-from cartsnitch_api.auth.jwt import decode_token
 from cartsnitch_api.config import settings
+from cartsnitch_api.database import get_db
 
-bearer_scheme = HTTPBearer()
+# Keep Bearer scheme as optional — Better-Auth primarily uses cookies,
+# but we support Bearer tokens for service-to-service or mobile clients.
+bearer_scheme = HTTPBearer(auto_error=False)
+
+# Better-Auth session cookie name
+SESSION_COOKIE_NAME = "better-auth.session_token"
+
+
+async def _validate_session_token(token: str, db: AsyncSession) -> UUID:
+    """Validate a Better-Auth session token against the sessions table.
+
+    Returns the user_id (as UUID) if the session is valid and not expired.
+    Better-Auth v1.5.6+ stores tokens as SHA-256 hashes, so we hash the
+    incoming raw token before querying.
+    """
+    hashed_token = sha256(token.encode("utf-8")).hexdigest()
+    result = await db.execute(
+        text("SELECT user_id, expires_at FROM sessions WHERE token = :token"),
+        {"token": hashed_token},
+    )
+    row = result.first()
+
+    if not row:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid session token",
+        )
+
+    user_id, expires_at = row
+    if expires_at.tzinfo is None:
+        # Treat naive datetimes as UTC
+        expires_at = expires_at.replace(tzinfo=UTC)
+
+    if expires_at < datetime.now(UTC):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Session expired",
+        )
+
+    return UUID(str(user_id))
 
 
 async def get_current_user(
-    credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
+    request: Request,
+    credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
+    db: AsyncSession = Depends(get_db),
 ) -> UUID:
-    try:
-        payload = decode_token(credentials.credentials)
-    except ValueError:
+    """Extract and validate the session token from cookie or Authorization header.
+
+    Checks in order:
+    1. Better-Auth session cookie (primary — web clients)
+    2. Bearer token in Authorization header (fallback — API clients)
+    """
+    token: str | None = None
+
+    # 1. Check session cookie
+    cookie_token = request.cookies.get(SESSION_COOKIE_NAME)
+    if cookie_token:
+        token = cookie_token
+
+    # 2. Fall back to Bearer header
+    if not token and credentials:
+        token = credentials.credentials
+
+    if not token:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Invalid or expired token",
-        ) from None
+            detail="Authentication required",
+        )
 
-    if payload.get("type") != "access":
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Invalid token type",
-        ) from None
-
-    return UUID(payload["sub"])
+    return await _validate_session_token(token, db)
 
 
 async def verify_service_key(x_service_key: str = Header()) -> None:

api/src/cartsnitch_api/auth/routes.py

@@ -1,4 +1,9 @@
-"""Auth routes: register, login, refresh, me, update, delete."""
+"""Auth routes: user profile management.
+
+Registration, login, refresh, and session management are handled by
+the Better-Auth service (auth/). This router provides user profile
+endpoints that query our own user data from the shared database.
+"""
 
 from uuid import UUID
 
@@ -8,10 +13,6 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from cartsnitch_api.auth.dependencies import get_current_user
 from cartsnitch_api.database import get_db
 from cartsnitch_api.schemas import (
-    LoginRequest,
-    RefreshRequest,
-    RegisterRequest,
-    TokenResponse,
     UpdateUserRequest,
     UserResponse,
 )
@@ -20,37 +21,6 @@ from cartsnitch_api.services.auth import AuthService
 router = APIRouter(prefix="/auth", tags=["auth"])
 
 
-@router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED)
-async def register(body: RegisterRequest, db: AsyncSession = Depends(get_db)):
-    svc = AuthService(db)
-    try:
-        return await svc.register(body.email, body.password, body.display_name)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e)) from e
-
-
-@router.post("/login", response_model=TokenResponse)
-async def login(body: LoginRequest, db: AsyncSession = Depends(get_db)):
-    svc = AuthService(db)
-    try:
-        return await svc.login(body.email, body.password)
-    except ValueError:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid email or password"
-        ) from None
-
-
-@router.post("/refresh", response_model=TokenResponse)
-async def refresh(body: RefreshRequest, db: AsyncSession = Depends(get_db)):
-    svc = AuthService(db)
-    try:
-        return await svc.refresh(body.refresh_token)
-    except ValueError:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid refresh token"
-        ) from None
-
-
 @router.get("/me", response_model=UserResponse)
 async def get_me(
     user_id: UUID = Depends(get_current_user),

api/src/cartsnitch_api/config.py

@@ -19,6 +19,8 @@ class Settings(BaseSettings):
     # Valid Fernet key for local dev — MUST be overridden in production
     fernet_key: str = "7reF42nmTwbdN21PBoubGp7h_FU8qSimstmlaMLoRK8="
 
+    auth_service_url: str = "http://auth:3001"
+
     cors_origins: list[str] = ["http://localhost:3000", "https://cartsnitch.com"]
 
     receiptwitness_url: str = "http://receiptwitness:8001"

api/src/cartsnitch_api/main.py

@@ -2,7 +2,7 @@
 
 from contextlib import asynccontextmanager
 
-from fastapi import FastAPI
+from fastapi import APIRouter, FastAPI
 
 from cartsnitch_api.auth.routes import router as auth_router
 from cartsnitch_api.middleware.cors import add_cors_middleware
@@ -46,15 +46,19 @@ def create_app() -> FastAPI:
     # Routers
     app.include_router(health_router)
     app.include_router(auth_router)
-    app.include_router(stores_router)
-    app.include_router(purchases_router)
-    app.include_router(products_router)
-    app.include_router(prices_router)
-    app.include_router(coupons_router)
-    app.include_router(shopping_router)
-    app.include_router(alerts_router)
-    app.include_router(scraping_router)
-    app.include_router(public_router)
+
+    # Data endpoints mounted under /api/v1
+    v1_router = APIRouter(prefix="/api/v1")
+    v1_router.include_router(stores_router)
+    v1_router.include_router(purchases_router)
+    v1_router.include_router(products_router)
+    v1_router.include_router(prices_router)
+    v1_router.include_router(coupons_router)
+    v1_router.include_router(shopping_router)
+    v1_router.include_router(alerts_router)
+    v1_router.include_router(scraping_router)
+    v1_router.include_router(public_router)
+    app.include_router(v1_router)
 
     return app
 

api/src/cartsnitch_api/models/purchase.py

@@ -32,7 +32,7 @@ class Purchase(UUIDPrimaryKeyMixin, TimestampMixin, Base):
 
     __tablename__ = "purchases"
 
-    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), nullable=False)
+    user_id: Mapped[str] = mapped_column(ForeignKey("users.id"), nullable=False)
     store_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("stores.id"), nullable=False)
     store_location_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("store_locations.id"))
     receipt_id: Mapped[str] = mapped_column(String(200), nullable=False)

api/src/cartsnitch_api/models/user.py

@@ -4,7 +4,7 @@ import uuid
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import DateTime, ForeignKey, String, UniqueConstraint
+from sqlalchemy import DateTime, ForeignKey, String, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_api.constants import AccountStatus
@@ -16,11 +16,12 @@ if TYPE_CHECKING:
     from cartsnitch_api.models.store import Store
 
 
-class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+class User(TimestampMixin, Base):
     """Application user."""
 
     __tablename__ = "users"
 
+    id: Mapped[str] = mapped_column(Text, primary_key=True)
     email: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
     hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
     display_name: Mapped[str | None] = mapped_column(String(100))
@@ -36,7 +37,7 @@ class UserStoreAccount(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     __tablename__ = "user_store_accounts"
     __table_args__ = (UniqueConstraint("user_id", "store_id", name="uq_user_store_account"),)
 
-    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), nullable=False)
+    user_id: Mapped[str] = mapped_column(ForeignKey("users.id"), nullable=False)
     store_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("stores.id"), nullable=False)
     session_data: Mapped[dict | None] = mapped_column(EncryptedJSON)
     session_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))

api/src/cartsnitch_api/schemas.py

@@ -6,28 +6,8 @@ from uuid import UUID
 from pydantic import BaseModel, EmailStr, Field
 
 # ---------- Auth ----------
-
-
-class RegisterRequest(BaseModel):
-    email: EmailStr
-    password: str = Field(min_length=8, max_length=128)
-    display_name: str = Field(min_length=1, max_length=100)
-
-
-class LoginRequest(BaseModel):
-    email: EmailStr
-    password: str
-
-
-class RefreshRequest(BaseModel):
-    refresh_token: str
-
-
-class TokenResponse(BaseModel):
-    access_token: str
-    refresh_token: str
-    token_type: str = "bearer"
-    expires_in: int
+# Registration, login, and session management are handled by Better-Auth (auth/ service).
+# These schemas are for the profile management endpoints only.
 
 
 class UpdateUserRequest(BaseModel):
@@ -36,7 +16,7 @@ class UpdateUserRequest(BaseModel):
 
 
 class UserResponse(BaseModel):
-    id: UUID
+    id: str
     email: str
     display_name: str
     created_at: datetime

api/src/cartsnitch_api/services/auth.py

@@ -1,67 +1,20 @@
-"""Auth service — user registration, login, token management."""
+"""Auth service — user profile management.
+
+Registration, login, token management, and session handling are now
+handled by the Better-Auth service (auth/). This service provides
+user lookup and profile update operations for the API gateway.
+"""
 
 from uuid import UUID
 
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from cartsnitch_api.auth.jwt import create_access_token, create_refresh_token, decode_token
-from cartsnitch_api.auth.passwords import hash_password, verify_password
-from cartsnitch_api.config import settings
-
 
 class AuthService:
     def __init__(self, db: AsyncSession) -> None:
         self.db = db
 
-    async def register(self, email: str, password: str, display_name: str) -> dict:
-        from cartsnitch_api.models import User
-
-        existing = await self.db.execute(select(User).where(User.email == email))
-        if existing.scalar_one_or_none():
-            raise ValueError("Email already registered")
-
-        user = User(
-            email=email,
-            hashed_password=hash_password(password),
-            display_name=display_name,
-        )
-        self.db.add(user)
-        await self.db.commit()
-        await self.db.refresh(user)
-
-        return self._make_token_response(user.id)
-
-    async def login(self, email: str, password: str) -> dict:
-        from cartsnitch_api.models import User
-
-        result = await self.db.execute(select(User).where(User.email == email))
-        user = result.scalar_one_or_none()
-        if not user or not verify_password(password, user.hashed_password):
-            raise ValueError("Invalid email or password")
-
-        return self._make_token_response(user.id)
-
-    async def refresh(self, refresh_token: str) -> dict:
-        from cartsnitch_api.models import User
-
-        try:
-            payload = decode_token(refresh_token)
-        except ValueError:
-            raise ValueError("Invalid refresh token") from None
-
-        if payload.get("type") != "refresh":
-            raise ValueError("Invalid token type") from None
-
-        user_id = UUID(payload["sub"])
-
-        # Verify the user still exists before issuing new tokens
-        result = await self.db.execute(select(User).where(User.id == user_id))
-        if not result.scalar_one_or_none():
-            raise ValueError("User no longer exists")
-
-        return self._make_token_response(user_id)
-
     async def get_user(self, user_id: UUID) -> dict:
         from cartsnitch_api.models import User
 
@@ -115,11 +68,3 @@ class AuthService:
 
         await self.db.delete(user)
         await self.db.commit()
-
-    def _make_token_response(self, user_id: UUID) -> dict:
-        return {
-            "access_token": create_access_token(user_id),
-            "refresh_token": create_refresh_token(user_id),
-            "token_type": "bearer",
-            "expires_in": settings.jwt_access_token_expire_minutes * 60,
-        }

api/tests/conftest.py

@@ -1,8 +1,16 @@
-"""Shared test fixtures with in-memory SQLite database."""
+"""Shared test fixtures with in-memory SQLite database.
+
+Session-based auth: tests create users and sessions directly in the DB,
+matching the Better-Auth session validation flow.
+"""
+
+import secrets
+import uuid
+from datetime import UTC, datetime, timedelta
 
 import pytest
 from httpx import ASGITransport, AsyncClient
-from sqlalchemy import create_engine, event
+from sqlalchemy import create_engine, event, text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import sessionmaker
 
@@ -51,6 +59,46 @@ async def db_engine():
 
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
+        # Create Better-Auth tables (not managed by SQLAlchemy models)
+        await conn.execute(text("""
+            CREATE TABLE IF NOT EXISTS sessions (
+                id TEXT PRIMARY KEY,
+                token TEXT NOT NULL UNIQUE,
+                user_id TEXT NOT NULL,
+                expires_at TIMESTAMP NOT NULL,
+                ip_address TEXT,
+                user_agent TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+            )
+        """))
+        await conn.execute(text("""
+            CREATE TABLE IF NOT EXISTS accounts (
+                id TEXT PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                account_id TEXT NOT NULL,
+                provider_id TEXT NOT NULL,
+                access_token TEXT,
+                refresh_token TEXT,
+                access_token_expires_at TIMESTAMP,
+                refresh_token_expires_at TIMESTAMP,
+                scope TEXT,
+                id_token TEXT,
+                password TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+            )
+        """))
+        await conn.execute(text("""
+            CREATE TABLE IF NOT EXISTS verifications (
+                id TEXT PRIMARY KEY,
+                identifier TEXT NOT NULL,
+                value TEXT NOT NULL,
+                expires_at TIMESTAMP NOT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+            )
+        """))
 
     yield engine
 
@@ -85,17 +133,55 @@ async def client(db_engine):
     app.dependency_overrides.clear()
 
 
+async def _create_test_user_and_session(client: AsyncClient, db_engine, **user_overrides) -> tuple[dict, str]:
+    """Create a test user and a valid session directly in the DB.
+
+    Returns (user_dict, session_token).
+    """
+    user_id = str(uuid.uuid4())
+    email = user_overrides.get("email", "test@example.com")
+    display_name = user_overrides.get("display_name", "Test User")
+    session_token = secrets.token_urlsafe(32)
+    session_id = str(uuid.uuid4())
+    now = datetime.now(UTC).isoformat()
+    expires = (datetime.now(UTC) + timedelta(days=7)).isoformat()
+
+    async with db_engine.begin() as conn:
+        await conn.execute(
+            text(
+                "INSERT INTO users (id, email, hashed_password, display_name, email_verified, created_at, updated_at) "
+                "VALUES (:id, :email, :hashed_password, :display_name, :email_verified, :created_at, :updated_at)"
+            ),
+            {
+                "id": user_id,
+                "email": email,
+                "hashed_password": "not-used-with-better-auth",
+                "display_name": display_name,
+                "email_verified": False,
+                "created_at": now,
+                "updated_at": now,
+            },
+        )
+        await conn.execute(
+            text(
+                "INSERT INTO sessions (id, token, user_id, expires_at, created_at, updated_at) "
+                "VALUES (:id, :token, :user_id, :expires_at, :created_at, :updated_at)"
+            ),
+            {
+                "id": session_id,
+                "token": session_token,
+                "user_id": user_id,
+                "expires_at": expires,
+                "created_at": now,
+                "updated_at": now,
+            },
+        )
+
+    return {"id": user_id, "email": email, "display_name": display_name}, session_token
+
+
 @pytest.fixture
-async def auth_headers(client):
-    """Register a test user and return auth headers."""
-    resp = await client.post(
-        "/auth/register",
-        json={
-            "email": "test@example.com",
-            "password": "testpass123",
-            "display_name": "Test User",
-        },
-    )
-    assert resp.status_code == 201
-    token = resp.json()["access_token"]
-    return {"Authorization": f"Bearer {token}"}
+async def auth_headers(client, db_engine):
+    """Create a test user with a valid session and return auth headers."""
+    _, session_token = await _create_test_user_and_session(client, db_engine)
+    return {"Cookie": f"better-auth.session_token={session_token}"}

api/tests/test_auth/test_auth_endpoints.py

@@ -1,146 +1,13 @@
-"""Integration tests for auth endpoints."""
+"""Integration tests for auth profile endpoints.
+
+Registration, login, and session management are handled by the Better-Auth
+service. These tests cover the profile endpoints (GET/PATCH/DELETE /auth/me)
+which validate sessions via the shared sessions table.
+"""
 
 import pytest
 
 
-@pytest.mark.asyncio
-async def test_register_success(client):
-    resp = await client.post(
-        "/auth/register",
-        json={
-            "email": "new@example.com",
-            "password": "securepass123",
-            "display_name": "New User",
-        },
-    )
-    assert resp.status_code == 201
-    data = resp.json()
-    assert "access_token" in data
-    assert "refresh_token" in data
-    assert data["token_type"] == "bearer"
-    assert data["expires_in"] == 900  # 15 min * 60
-
-
-@pytest.mark.asyncio
-async def test_register_duplicate_email(client):
-    await client.post(
-        "/auth/register",
-        json={
-            "email": "dupe@example.com",
-            "password": "securepass123",
-            "display_name": "User One",
-        },
-    )
-    resp = await client.post(
-        "/auth/register",
-        json={
-            "email": "dupe@example.com",
-            "password": "securepass456",
-            "display_name": "User Two",
-        },
-    )
-    assert resp.status_code == 409
-
-
-@pytest.mark.asyncio
-async def test_register_short_password(client):
-    resp = await client.post(
-        "/auth/register",
-        json={
-            "email": "short@example.com",
-            "password": "short",
-            "display_name": "Short Pass",
-        },
-    )
-    assert resp.status_code == 422
-
-
-@pytest.mark.asyncio
-async def test_login_success(client):
-    await client.post(
-        "/auth/register",
-        json={
-            "email": "login@example.com",
-            "password": "securepass123",
-            "display_name": "Login User",
-        },
-    )
-    resp = await client.post(
-        "/auth/login",
-        json={
-            "email": "login@example.com",
-            "password": "securepass123",
-        },
-    )
-    assert resp.status_code == 200
-    assert "access_token" in resp.json()
-
-
-@pytest.mark.asyncio
-async def test_login_wrong_password(client):
-    await client.post(
-        "/auth/register",
-        json={
-            "email": "wrong@example.com",
-            "password": "securepass123",
-            "display_name": "Wrong Pass",
-        },
-    )
-    resp = await client.post(
-        "/auth/login",
-        json={
-            "email": "wrong@example.com",
-            "password": "badpassword1",
-        },
-    )
-    assert resp.status_code == 401
-
-
-@pytest.mark.asyncio
-async def test_login_nonexistent_user(client):
-    resp = await client.post(
-        "/auth/login",
-        json={
-            "email": "ghost@example.com",
-            "password": "doesntmatter",
-        },
-    )
-    assert resp.status_code == 401
-
-
-@pytest.mark.asyncio
-async def test_refresh_token(client):
-    reg = await client.post(
-        "/auth/register",
-        json={
-            "email": "refresh@example.com",
-            "password": "securepass123",
-            "display_name": "Refresh User",
-        },
-    )
-    refresh_token = reg.json()["refresh_token"]
-
-    resp = await client.post(
-        "/auth/refresh",
-        json={
-            "refresh_token": refresh_token,
-        },
-    )
-    assert resp.status_code == 200
-    assert "access_token" in resp.json()
-
-
-@pytest.mark.asyncio
-async def test_refresh_with_invalid_token(client):
-    resp = await client.post(
-        "/auth/refresh",
-        json={
-            "refresh_token": "invalid.token.here",
-        },
-    )
-    assert resp.status_code == 401
-
-
 @pytest.mark.asyncio
 async def test_get_me(client, auth_headers):
     resp = await client.get("/auth/me", headers=auth_headers)
@@ -155,7 +22,32 @@ async def test_get_me(client, auth_headers):
 @pytest.mark.asyncio
 async def test_get_me_unauthorized(client):
     resp = await client.get("/auth/me")
-    assert resp.status_code in (401, 403)  # No auth header
+    assert resp.status_code in (401, 403)
+
+
+@pytest.mark.asyncio
+async def test_get_me_invalid_session(client):
+    resp = await client.get(
+        "/auth/me",
+        headers={"Cookie": "better-auth.session_token=invalid-token"},
+    )
+    assert resp.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_get_me_with_bearer_token(client, db_engine):
+    """Session tokens can also be passed as Bearer tokens for API clients."""
+    from tests.conftest import _create_test_user_and_session
+
+    _, session_token = await _create_test_user_and_session(
+        client, db_engine, email="bearer@example.com", display_name="Bearer User"
+    )
+    resp = await client.get(
+        "/auth/me",
+        headers={"Authorization": f"Bearer {session_token}"},
+    )
+    assert resp.status_code == 200
+    assert resp.json()["email"] == "bearer@example.com"
 
 
 @pytest.mark.asyncio
@@ -163,9 +55,7 @@ async def test_update_me(client, auth_headers):
     resp = await client.patch(
         "/auth/me",
         headers=auth_headers,
-        json={
-            "display_name": "Updated Name",
-        },
+        json={"display_name": "Updated Name"},
     )
     assert resp.status_code == 200
     assert resp.json()["display_name"] == "Updated Name"
@@ -176,34 +66,58 @@ async def test_delete_me(client, auth_headers):
     resp = await client.delete("/auth/me", headers=auth_headers)
     assert resp.status_code == 204
 
-    # Verify user is gone (token still valid but user deleted)
+    # Session is still valid but user is gone
     resp = await client.get("/auth/me", headers=auth_headers)
     assert resp.status_code == 404
 
 
 @pytest.mark.asyncio
-async def test_refresh_after_delete_fails(client):
-    """Refresh token for a deleted user must be rejected."""
-    reg = await client.post(
-        "/auth/register",
-        json={
-            "email": "ghost@example.com",
-            "password": "securepass123",
-            "display_name": "Ghost User",
-        },
-    )
-    tokens = reg.json()
-    headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+async def test_expired_session_rejected(client, db_engine):
+    """Expired sessions must be rejected."""
+    import secrets
+    import uuid
+    from datetime import UTC, datetime, timedelta
 
-    # Delete the user
-    resp = await client.delete("/auth/me", headers=headers)
-    assert resp.status_code == 204
+    from sqlalchemy import text
 
-    # Refresh token should now fail
-    resp = await client.post(
-        "/auth/refresh",
-        json={
-            "refresh_token": tokens["refresh_token"],
-        },
+    user_id = str(uuid.uuid4())
+    session_token = secrets.token_urlsafe(32)
+    now = datetime.now(UTC).isoformat()
+    expired = (datetime.now(UTC) - timedelta(hours=1)).isoformat()
+
+    async with db_engine.begin() as conn:
+        await conn.execute(
+            text(
+                "INSERT INTO users (id, email, hashed_password, display_name, email_verified, created_at, updated_at) "
+                "VALUES (:id, :email, :hp, :dn, :ev, :ca, :ua)"
+            ),
+            {
+                "id": user_id,
+                "email": "expired@example.com",
+                "hp": "unused",
+                "dn": "Expired User",
+                "ev": False,
+                "ca": now,
+                "ua": now,
+            },
+        )
+        await conn.execute(
+            text(
+                "INSERT INTO sessions (id, token, user_id, expires_at, created_at, updated_at) "
+                "VALUES (:id, :token, :uid, :ea, :ca, :ua)"
+            ),
+            {
+                "id": str(uuid.uuid4()),
+                "token": session_token,
+                "uid": user_id,
+                "ea": expired,
+                "ca": now,
+                "ua": now,
+            },
+        )
+
+    resp = await client.get(
+        "/auth/me",
+        headers={"Cookie": f"better-auth.session_token={session_token}"},
     )
     assert resp.status_code == 401

api/tests/test_e2e/conftest.py

@@ -10,9 +10,9 @@ from decimal import Decimal
 from uuid import UUID
 
 import pytest
+from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
-from cartsnitch_api.auth.jwt import decode_token
 from cartsnitch_api.models import (
     Coupon,
     NormalizedProduct,
@@ -126,10 +126,16 @@ async def seed_data(db_engine, auth_headers):
         session.add_all(prices)
         await session.flush()
 
-        # -- Purchases (need the user_id from the registered test user) --
-        token = auth_headers["Authorization"].split(" ")[1]
-        payload = decode_token(token)
-        user_id = UUID(payload["sub"])
+        # -- Get the user_id from the session token in auth_headers --
+        cookie_str = auth_headers.get("Cookie", "")
+        session_token = cookie_str.split("=", 1)[1] if "=" in cookie_str else ""
+
+        result = await session.execute(
+            text("SELECT user_id FROM sessions WHERE token = :token"),
+            {"token": session_token},
+        )
+        row = result.first()
+        user_id = UUID(row[0])
 
         purchase1 = Purchase(
             user_id=user_id,

api/tests/test_e2e/test_auth_validation.py

@@ -1,132 +1,103 @@
-"""E2E: Auth and token validation flows."""
+"""E2E: Auth and session validation flows.
 
-import asyncio
+Registration and login are handled by the Better-Auth service.
+These tests validate session token handling at the API gateway level.
+"""
 
 import pytest
 
-
-@pytest.mark.asyncio
-class TestAuthRegistrationLogin:
-    """Full registration → login → token refresh → profile flow."""
-
-    async def test_full_auth_lifecycle(self, client, db_engine):
-        """Register → login → get profile → refresh → get profile again."""
-        # Register
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "lifecycle@example.com",
-                "password": "securepass123",
-                "display_name": "Lifecycle User",
-            },
-        )
-        assert reg.status_code == 201
-        tokens = reg.json()
-        assert "access_token" in tokens
-        assert "refresh_token" in tokens
-        assert tokens["token_type"] == "bearer"
-        assert tokens["expires_in"] > 0
-
-        headers = {"Authorization": f"Bearer {tokens['access_token']}"}
-
-        # Get profile with access token
-        me = await client.get("/auth/me", headers=headers)
-        assert me.status_code == 200
-        assert me.json()["email"] == "lifecycle@example.com"
-        assert me.json()["display_name"] == "Lifecycle User"
-
-        # Sleep 1s so the new token has a different exp than the registration token
-        await asyncio.sleep(1)
-
-        # Login with same credentials
-        login = await client.post(
-            "/auth/login",
-            json={"email": "lifecycle@example.com", "password": "securepass123"},
-        )
-        assert login.status_code == 200
-        login_tokens = login.json()
-        assert login_tokens["access_token"] != tokens["access_token"]
-
-        # Refresh token
-        refresh = await client.post(
-            "/auth/refresh",
-            json={"refresh_token": tokens["refresh_token"]},
-        )
-        assert refresh.status_code == 200
-        new_tokens = refresh.json()
-        assert new_tokens["access_token"] != tokens["access_token"]
-
-        # Use refreshed token to access profile
-        new_headers = {"Authorization": f"Bearer {new_tokens['access_token']}"}
-        me2 = await client.get("/auth/me", headers=new_headers)
-        assert me2.status_code == 200
-        assert me2.json()["email"] == "lifecycle@example.com"
+from tests.conftest import _create_test_user_and_session
 
 
 @pytest.mark.asyncio
-class TestTokenValidation:
-    """Token edge cases and error responses."""
+class TestSessionValidation:
+    """Session edge cases and error responses."""
 
-    async def test_expired_token_rejected(self, client, db_engine):
-        """Manually craft an expired token and verify rejection."""
-        import uuid
-        from datetime import UTC, datetime, timedelta
-
-        from jose import jwt
-
-        from cartsnitch_api.config import settings
-
-        payload = {
-            "sub": str(uuid.uuid4()),
-            "exp": datetime.now(UTC) - timedelta(minutes=5),
-            "type": "access",
-        }
-        token = jwt.encode(payload, settings.jwt_secret_key, algorithm=settings.jwt_algorithm)
-        resp = await client.get("/auth/me", headers={"Authorization": f"Bearer {token}"})
+    async def test_invalid_session_token_rejected(self, client, db_engine):
+        resp = await client.get(
+            "/auth/me",
+            headers={"Cookie": "better-auth.session_token=not-a-real-token"},
+        )
         assert resp.status_code == 401
 
-    async def test_invalid_token_rejected(self, client, db_engine):
-        resp = await client.get("/auth/me", headers={"Authorization": "Bearer not-a-real-token"})
-        assert resp.status_code == 401
-
-    async def test_missing_auth_header(self, client, db_engine):
+    async def test_missing_auth(self, client, db_engine):
         resp = await client.get("/auth/me")
         assert resp.status_code in (401, 403)
 
-    async def test_refresh_token_cannot_access_endpoints(self, client, db_engine):
-        """A refresh token should not work as an access token."""
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "refresh-test@example.com",
-                "password": "securepass123",
-                "display_name": "Refresh Test",
-            },
+    async def test_bearer_token_also_works(self, client, db_engine):
+        """Session tokens passed as Bearer tokens should also be accepted."""
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="bearer@e2e.com", display_name="Bearer E2E"
         )
-        refresh_token = reg.json()["refresh_token"]
-        resp = await client.get("/auth/me", headers={"Authorization": f"Bearer {refresh_token}"})
-        assert resp.status_code == 401
-
-    async def test_deleted_user_token_invalid(self, client, db_engine):
-        """After deleting an account, tokens should no longer work."""
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "delete-me@example.com",
-                "password": "securepass123",
-                "display_name": "Delete Me",
-            },
+        resp = await client.get(
+            "/auth/me",
+            headers={"Authorization": f"Bearer {session_token}"},
         )
-        tokens = reg.json()
-        headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+        assert resp.status_code == 200
+        assert resp.json()["email"] == "bearer@e2e.com"
+
+    async def test_deleted_user_session_returns_not_found(self, client, db_engine):
+        """After deleting a user, their session should result in 404 for profile."""
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="delete-me@e2e.com", display_name="Delete Me"
+        )
+        headers = {"Cookie": f"better-auth.session_token={session_token}"}
 
-        # Delete account
         delete_resp = await client.delete("/auth/me", headers=headers)
         assert delete_resp.status_code == 204
 
-        # Profile should fail
         me = await client.get("/auth/me", headers=headers)
-        assert me.status_code in (401, 404)
+        assert me.status_code == 404
+
+    async def test_expired_session_rejected(self, client, db_engine):
+        """Expired sessions must be rejected."""
+        import secrets
+        import uuid
+        from datetime import UTC, datetime, timedelta
+
+        from sqlalchemy import text
+
+        user_id = str(uuid.uuid4())
+        session_token = secrets.token_urlsafe(32)
+        now = datetime.now(UTC).isoformat()
+        expired = (datetime.now(UTC) - timedelta(hours=1)).isoformat()
+
+        async with db_engine.begin() as conn:
+            await conn.execute(
+                text(
+                    "INSERT INTO users (id, email, hashed_password, display_name, email_verified, created_at, updated_at) "
+                    "VALUES (:id, :email, :hp, :dn, :ev, :ca, :ua)"
+                ),
+                {
+                    "id": user_id,
+                    "email": "expired@e2e.com",
+                    "hp": "unused",
+                    "dn": "Expired User",
+                    "ev": False,
+                    "ca": now,
+                    "ua": now,
+                },
+            )
+            await conn.execute(
+                text(
+                    "INSERT INTO sessions (id, token, user_id, expires_at, created_at, updated_at) "
+                    "VALUES (:id, :token, :uid, :ea, :ca, :ua)"
+                ),
+                {
+                    "id": str(uuid.uuid4()),
+                    "token": session_token,
+                    "uid": user_id,
+                    "ea": expired,
+                    "ca": now,
+                    "ua": now,
+                },
+            )
+
+        resp = await client.get(
+            "/auth/me",
+            headers={"Cookie": f"better-auth.session_token={session_token}"},
+        )
+        assert resp.status_code == 401
 
 
 @pytest.mark.asyncio
@@ -154,60 +125,38 @@ class TestAuthProtectedEndpoints:
 class TestCrossUserDataIsolation:
     """Verify that users cannot access other users' data."""
 
-    async def test_user_b_cannot_access_user_a_purchases(self, client, seed_data):
-        """Register a second user and verify they cannot see User A's purchases."""
-        # User A's purchase (from seed_data)
+    async def test_user_b_cannot_access_user_a_purchases(self, client, db_engine, seed_data):
+        """A second user cannot see User A's purchases."""
         purchase_id = str(seed_data["purchases"]["meijer_trip"].id)
 
-        # Register User B
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "userb@example.com",
-                "password": "securepass123",
-                "display_name": "User B",
-            },
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="userb@e2e.com", display_name="User B"
         )
-        assert reg.status_code == 201
-        user_b_headers = {"Authorization": f"Bearer {reg.json()['access_token']}"}
+        user_b_headers = {"Cookie": f"better-auth.session_token={session_token}"}
 
-        # User B tries to access User A's specific purchase
         resp = await client.get(f"/purchases/{purchase_id}", headers=user_b_headers)
         assert resp.status_code in (403, 404), (
             "User B should not be able to access User A's purchase"
         )
 
-    async def test_user_b_purchase_list_is_empty(self, client, seed_data):
-        """A new user should see no purchases (not User A's purchases)."""
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "userc@example.com",
-                "password": "securepass123",
-                "display_name": "User C",
-            },
+    async def test_user_b_purchase_list_is_empty(self, client, db_engine, seed_data):
+        """A new user should see no purchases."""
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="userc@e2e.com", display_name="User C"
         )
-        assert reg.status_code == 201
-        user_c_headers = {"Authorization": f"Bearer {reg.json()['access_token']}"}
+        user_c_headers = {"Cookie": f"better-auth.session_token={session_token}"}
 
         resp = await client.get("/purchases", headers=user_c_headers)
         assert resp.status_code == 200
         assert len(resp.json()) == 0, "New user should have no purchases"
 
-    async def test_user_b_stores_isolated(self, client, seed_data):
+    async def test_user_b_stores_isolated(self, client, db_engine, seed_data):
         """User B's connected stores should be independent from User A."""
-        reg = await client.post(
-            "/auth/register",
-            json={
-                "email": "userd@example.com",
-                "password": "securepass123",
-                "display_name": "User D",
-            },
+        _, session_token = await _create_test_user_and_session(
+            client, db_engine, email="userd@e2e.com", display_name="User D"
         )
-        assert reg.status_code == 201
-        user_d_headers = {"Authorization": f"Bearer {reg.json()['access_token']}"}
+        user_d_headers = {"Cookie": f"better-auth.session_token={session_token}"}
 
-        # User D should have no connected stores
         resp = await client.get("/me/stores", headers=user_d_headers)
         assert resp.status_code == 200
         assert len(resp.json()) == 0, "New user should have no connected stores"

api/tests/test_routes/test_purchases.py

@@ -1,26 +1,25 @@
 """Integration tests for purchase endpoints."""
 
+import secrets
 import uuid
-from datetime import date
+from datetime import UTC, date, datetime, timedelta
 from decimal import Decimal
 
 import pytest
+from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
-from cartsnitch_api.auth.jwt import create_access_token
 from cartsnitch_api.models import Purchase, PurchaseItem, Store, User
 
 
 @pytest.fixture
 async def purchase_data(db_engine):
-    """Seed a user, store, purchase, and items."""
+    """Seed a user, store, purchase, items, and a valid session."""
     factory = async_sessionmaker(db_engine, class_=AsyncSession, expire_on_commit=False)
     async with factory() as session:
-        from cartsnitch_api.auth.passwords import hash_password
-
         user = User(
             email="buyer@example.com",
-            hashed_password=hash_password("testpass123"),
+            hashed_password="not-used-with-better-auth",
             display_name="Buyer",
         )
         store = Store(name="Kroger", slug="kroger")
@@ -50,13 +49,33 @@ async def purchase_data(db_engine):
         session.add(item)
         await session.commit()
 
-        token = create_access_token(user.id)
-        return {
-            "user": user,
-            "store": store,
-            "purchase": purchase,
-            "headers": {"Authorization": f"Bearer {token}"},
-        }
+    # Create a session token directly in the sessions table
+    session_token = secrets.token_urlsafe(32)
+    now = datetime.now(UTC).isoformat()
+    expires = (datetime.now(UTC) + timedelta(days=7)).isoformat()
+
+    async with db_engine.begin() as conn:
+        await conn.execute(
+            text(
+                "INSERT INTO sessions (id, token, user_id, expires_at, created_at, updated_at) "
+                "VALUES (:id, :token, :user_id, :expires_at, :created_at, :updated_at)"
+            ),
+            {
+                "id": str(uuid.uuid4()),
+                "token": session_token,
+                "user_id": str(user.id),
+                "expires_at": expires,
+                "created_at": now,
+                "updated_at": now,
+            },
+        )
+
+    return {
+        "user": user,
+        "store": store,
+        "purchase": purchase,
+        "headers": {"Cookie": f"better-auth.session_token={session_token}"},
+    }
 
 
 @pytest.mark.asyncio

auth/.env.example

@@ -0,0 +1,11 @@
+# Required: Generate with `openssl rand -base64 32`
+BETTER_AUTH_SECRET=change-me-in-production-min-32-chars!!
+
+# Base URL of the auth service
+BETTER_AUTH_URL=http://localhost:3001
+
+# Shared PostgreSQL database
+DATABASE_URL=postgresql://cartsnitch:cartsnitch@localhost:5432/cartsnitch
+
+# Port the auth service listens on
+PORT=3001

auth/Dockerfile

@@ -0,0 +1,17 @@
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci
+COPY tsconfig.json ./
+COPY src/ src/
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json package-lock.json* ./
+RUN npm ci --omit=dev
+COPY --from=builder /app/dist/ dist/
+USER 101
+EXPOSE 3001
+CMD ["node", "dist/index.js"]

auth/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@cartsnitch/auth",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "generate": "npx @better-auth/cli generate"
+  },
+  "dependencies": {
+    "better-auth": "^1.2.0",
+    "pg": "^8.13.0",
+    "bcrypt": "^5.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.11.0",
+    "@types/bcrypt": "^5.0.2",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

auth/src/auth.ts

@@ -0,0 +1,99 @@
+import { betterAuth } from "better-auth";
+import bcrypt from "bcrypt";
+import pg from "pg";
+
+const { Pool } = pg;
+
+const pool = new Pool({
+  connectionString:
+    process.env.DATABASE_URL ??
+    "postgresql://cartsnitch:cartsnitch@localhost:5432/cartsnitch",
+});
+
+const secret = process.env.BETTER_AUTH_SECRET;
+if (!secret) {
+  throw new Error("BETTER_AUTH_SECRET environment variable is required");
+}
+
+export const auth = betterAuth({
+  database: pool,
+  basePath: "/auth",
+  secret,
+  baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:3001",
+
+  emailAndPassword: {
+    enabled: true,
+    minPasswordLength: 8,
+    maxPasswordLength: 128,
+    password: {
+      hash: async (password: string) => {
+        return bcrypt.hash(password, 10);
+      },
+      verify: async (data: { hash: string; password: string }) => {
+        return bcrypt.compare(data.password, data.hash);
+      },
+    },
+  },
+
+  session: {
+    modelName: "sessions",
+    fields: {
+      userId: "user_id",
+      expiresAt: "expires_at",
+      ipAddress: "ip_address",
+      userAgent: "user_agent",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+    updateAge: 60 * 60 * 24, // refresh after 1 day
+    cookieCache: {
+      enabled: true,
+      maxAge: 5 * 60, // 5-minute cookie cache
+    },
+  },
+
+  user: {
+    modelName: "users",
+    fields: {
+      name: "display_name",
+      emailVerified: "email_verified",
+      image: "image",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
+  },
+
+  account: {
+    modelName: "accounts",
+    fields: {
+      userId: "user_id",
+      accountId: "account_id",
+      providerId: "provider_id",
+      accessToken: "access_token",
+      refreshToken: "refresh_token",
+      accessTokenExpiresAt: "access_token_expires_at",
+      refreshTokenExpiresAt: "refresh_token_expires_at",
+      idToken: "id_token",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
+  },
+
+  verification: {
+    modelName: "verifications",
+    fields: {
+      expiresAt: "expires_at",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
+  },
+
+  trustedOrigins: [
+    "http://localhost:3000",
+    "http://localhost:5173",
+    "https://cartsnitch.com",
+    "https://cartsnitch.farh.net",
+    "https://cartsnitch.dev.farh.net",
+  ],
+});

auth/src/index.ts

@@ -0,0 +1,23 @@
+import { createServer } from "node:http";
+import { toNodeHandler } from "better-auth/node";
+import { auth } from "./auth.js";
+
+const port = parseInt(process.env.PORT ?? "3001", 10);
+
+const handler = toNodeHandler(auth);
+
+const server = createServer(async (req, res) => {
+  // Health check
+  if (req.url === "/health" && req.method === "GET") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ status: "ok" }));
+    return;
+  }
+
+  // All /auth/* routes handled by Better-Auth
+  await handler(req, res);
+});
+
+server.listen(port, "0.0.0.0", () => {
+  console.log(`CartSnitch auth service listening on port ${port}`);
+});

auth/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

common/README.md

@@ -0,0 +1,28 @@
+# CartSnitch Common
+
+Shared models, schemas, and utilities for CartSnitch services.
+
+## Test Users
+
+The following users are seeded by `cartsnitch-seed` and can be used for local development and UAT.
+
+| Email | Password | Display Name | Notes |
+|---|---|---|---|
+| `uat@cartsnitch.com` | `CartSnitch-UAT-2026!` | UAT Tester | Primary UAT account. Use for regression testing in the CartSnitch frontend. Created by the seed runner via Better-Auth's bcrypt path — credentials work against the live auth service. Idempotent; re-running the seed skips this user if it already exists. |
+
+### Running the Seed
+
+```bash
+# Install with seed dependencies
+pip install -e "cartsnitch-common[seed]"
+
+# Run (requires CARTSNITCH_DATABASE_URL_SYNC)
+CARTSNITCH_DATABASE_URL_SYNC=postgresql://user:pass@localhost:5432/cartsnitch \
+  cartsnitch-seed
+```
+
+### Architecture
+
+- **Models** live in `src/cartsnitch_common/models/`
+- **Alembic migrations** run via the `api` service (`api/alembic/`)
+- **Seed runner** runs via `cartsnitch-seed` (installed as a package entry point)

common/pyproject.toml

@@ -27,6 +27,7 @@ dev = [
 ]
 seed = [
     "faker>=33.0,<34.0",
+    "bcrypt>=4.0,<6.0",
 ]
 
 [project.scripts]

common/src/cartsnitch_common/models/user.py

@@ -4,7 +4,7 @@ import uuid
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import JSON, DateTime, ForeignKey, String, UniqueConstraint
+from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, String, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_common.constants import AccountStatus
@@ -21,8 +21,10 @@ class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     __tablename__ = "users"
 
     email: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
+    hashed_password: Mapped[str | None] = mapped_column(String(255), nullable=True)
     display_name: Mapped[str | None] = mapped_column(String(100))
+    email_verified: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default="false")
+    image: Mapped[str | None] = mapped_column(Text, nullable=True)
 
     # Relationships
     store_accounts: Mapped[list["UserStoreAccount"]] = relationship(back_populates="user")

common/src/cartsnitch_common/seed/runner.py

@@ -2,8 +2,10 @@
 
 import random
 import time
+import uuid
 from typing import Any
 
+import bcrypt
 from faker import Faker
 from sqlalchemy import text
 from sqlalchemy.orm import Session
@@ -184,6 +186,65 @@ def run_seed(
 
         session.commit()
 
+        _seed_uat_user(session)
+
     elapsed = time.monotonic() - t0
     _log("")
     _log(f"Seed complete in {elapsed:.1f}s")
+
+
+# ---------------------------------------------------------------------------
+# UAT seed user
+# ---------------------------------------------------------------------------
+
+UAT_EMAIL = "uat@cartsnitch.com"
+UAT_PASSWORD = "CartSnitch-UAT-2026!"
+UAT_DISPLAY_NAME = "UAT Tester"
+UAT_USER_ID = uuid.UUID("00000000-0000-0000-0000-000000000001")
+
+
+def _seed_uat_user(session: Session) -> None:
+    """Insert or verify the dedicated UAT test user.
+
+    The user is created via Better-Auth's bcrypt hashing path so credentials
+    work against the live auth service. Idempotent — skips if the user already
+    exists.
+    """
+    existing = session.execute(
+        text("SELECT id FROM users WHERE email = :email"),
+        {"email": UAT_EMAIL},
+    ).fetchone()
+
+    if existing is not None:
+        _log(f"UAT user {UAT_EMAIL} already exists — skipping")
+        return
+
+    password_hash = bcrypt.hashpw(UAT_PASSWORD.encode(), bcrypt.gensalt()).decode()
+
+    session.execute(
+        text(
+            "INSERT INTO users (id, email, hashed_password, display_name, email_verified, created_at, updated_at) "
+            "VALUES (:id, :email, :hashed_password, :display_name, true, now(), now())"
+        ),
+        {
+            "id": str(UAT_USER_ID),
+            "email": UAT_EMAIL,
+            "hashed_password": password_hash,
+            "display_name": UAT_DISPLAY_NAME,
+        },
+    )
+
+    session.execute(
+        text(
+            "INSERT INTO accounts (id, user_id, account_id, provider_id, password, created_at, updated_at) "
+            "VALUES (gen_random_uuid()::text, :user_id, :account_id, 'credential', :password, now(), now())"
+        ),
+        {
+            "user_id": str(UAT_USER_ID),
+            "account_id": str(UAT_USER_ID),
+            "password": password_hash,
+        },
+    )
+
+    session.commit()
+    _log(f"UAT user {UAT_EMAIL} created")

docs/uat-runbook.md

@@ -0,0 +1,151 @@
+# CartSnitch UAT Runbook v1
+
+**Version:** 1.0
+**Author:** Savannah Savings, CTO
+**Date:** 2026-03-30
+**Effective:** Immediately upon Phase 1 completion
+
+---
+
+## 1. Defect Severity Classification
+
+Every defect discovered during UAT **must** be classified by severity and priority before triage.
+
+### Severity Levels
+
+| Severity | Definition | Examples |
+|----------|-----------|----------|
+| **S1 — Critical** | Blocks all users from completing a core journey. System is down, data is lost, or security is breached. | Login page crashes for all users; purchase data deleted; auth tokens exposed in response |
+| **S2 — High** | Blocks a major user flow for a significant portion of users. Core feature is broken but workarounds may exist. | Registration fails for email addresses with `+` character; price alerts never trigger; store comparison shows wrong prices |
+| **S3 — Medium** | Feature is degraded but usable. User can complete the journey with friction. | Date formatting shows raw ISO string instead of friendly date; slow page load (>5s) on product detail; search results not sorted correctly |
+| **S4 — Low** | Cosmetic issue, minor UI inconsistency, or edge case with minimal user impact. | Button text truncated on narrow screens; extra whitespace in footer; tooltip shows on hover but not on focus |
+
+### Priority Levels
+
+Priority determines **when** the defect must be fixed. Priority is set by the CTO based on severity, business impact, and sprint capacity.
+
+| Priority | SLA | When to Use |
+|----------|-----|------------|
+| **P0 — Fix Now** | Triage within 1 hour, fix deployed within 4 hours | S1 defects, any security vulnerability, data integrity issues |
+| **P1 — Fix This Sprint** | Triage within 4 hours, fix in current sprint | S2 defects blocking upcoming release, S1 defects with viable workaround |
+| **P2 — Fix Next Sprint** | Triage within 24 hours, scheduled for next sprint | S3 defects, S2 defects with easy workarounds |
+| **P3 — Backlog** | Triage within 48 hours, prioritized against backlog | S4 defects, minor improvements, nice-to-haves |
+
+### Defect Report Template
+
+Every defect filed during UAT must include:
+
+```
+**Title:** [Short description]
+**Severity:** S1/S2/S3/S4
+**Priority:** P0/P1/P2/P3 (set by CTO at triage)
+**Journey:** [Which user journey — J1 through J10]
+**Environment:** [Dev / Prod, deployed image tag]
+**Steps to Reproduce:**
+1. Navigate to ...
+2. Click ...
+3. Enter ...
+**Expected Result:** ...
+**Actual Result:** ...
+**Screenshots/Logs:** [Attach or link]
+**Browser/Device:** [e.g., Chromium 124, mobile viewport 390x844]
+```
+
+---
+
+## 2. UAT Entry Criteria
+
+UAT **must not begin** until ALL of the following are satisfied. Checkout Charlie verifies these before opening the UAT gate.
+
+| # | Criterion | Verified By |
+|---|-----------|------------|
+| E1 | CI pipeline passes on the merged commit (lint, type-check, unit tests, build) | GitHub Actions (automated) |
+| E2 | Docker image is built and pushed to GHCR with a CalVer tag | GitHub Actions (automated) |
+| E3 | Dev environment is deployed and accessible at `cartsnitch.dev.farh.net` | Flux reconciliation + health check |
+| E4 | All Playwright E2E tests pass in CI | GitHub Actions (automated) |
+| E5 | No open S1/S2 defects from previous UAT cycle | Checkout Charlie (manual check) |
+| E6 | PR has been reviewed and approved by QA (Checkout Charlie) and CTO (Savannah Savings) | GitHub PR approvals |
+| E7 | PR has been merged to main by CEO (Coupon Carl) | GitHub merge event |
+| E8 | Acceptance criteria for the feature/change are documented in the Paperclip issue | Checkout Charlie (manual check) |
+
+**If any entry criterion is not met**, UAT is blocked. Checkout Charlie must comment on the Paperclip issue specifying which criteria failed and assign back to the responsible party.
+
+---
+
+## 3. UAT Exit Criteria
+
+UAT is **complete** only when ALL of the following are satisfied. Rollback Rhonda verifies these before signing off.
+
+| # | Criterion | Verified By |
+|---|-----------|------------|
+| X1 | All 10 critical user journeys (J1-J10) have been executed | Rollback Rhonda (full regression) |
+| X2 | Zero open S1 (Critical) defects | Defect tracker |
+| X3 | Zero open S2 (High) defects, OR CTO has granted a documented exception | Defect tracker + CTO sign-off |
+| X4 | All S3/S4 defects are logged and triaged (not necessarily fixed) | Defect tracker |
+| X5 | 100% test execution rate -- every test case was run, none skipped | Rollback Rhonda's UAT report |
+| X6 | Accessibility scan (axe-core) reports zero critical violations | Automated in E2E suite |
+| X7 | Lighthouse performance score >= 50, accessibility score >= 90 | Lighthouse CI |
+| X8 | Written sign-off from Rollback Rhonda confirming all criteria met | Paperclip comment on issue |
+
+**If any exit criterion is not met**, the release is blocked. Rollback Rhonda must:
+1. File defects for all failures using the Defect Report Template above.
+2. Comment on the Paperclip issue specifying which exit criteria failed.
+3. Assign back to CTO for triage and redistribution.
+
+---
+
+## 4. UAT Execution Procedure
+
+### 4.1 Pre-UAT (Checkout Charlie)
+
+1. Verify all entry criteria (E1-E8) are met.
+2. Comment on the Paperclip issue: "UAT gate open -- all entry criteria verified."
+3. Assign to Rollback Rhonda with status todo.
+
+### 4.2 UAT Execution (Rollback Rhonda)
+
+1. **Full regression run** -- execute ALL 10 user journeys against cartsnitch.dev.farh.net. No partial runs. No exceptions.
+2. For each journey, verify:
+   - All interactive elements respond correctly (buttons, forms, links, toggles)
+   - State transitions are correct (auth state, data mutations, navigation)
+   - Error states are handled gracefully (invalid input, network failures)
+   - Accessibility scan passes (axe-core integrated in Playwright)
+3. Log results for each journey: PASS / FAIL with details.
+4. File defects immediately for any failures.
+5. Complete the UAT report with execution results.
+
+### 4.3 Post-UAT Sign-Off
+
+1. If all exit criteria (X1-X8) are met:
+   - Rollback Rhonda posts sign-off comment: "UAT PASSED -- all exit criteria met."
+   - Production promotion is automated via Flux on UAT pass.
+2. If any exit criterion fails:
+   - Rollback Rhonda posts failure comment with specific failures.
+   - CTO triages defects and redistributes to engineers.
+   - After fixes are merged, UAT restarts from 4.1 (full cycle).
+
+---
+
+## 5. Critical User Journeys Reference
+
+| ID | Journey | Key Interactions |
+|----|---------|-----------------|
+| J1 | Registration -> Login -> Dashboard | Form submission, auth state, redirect |
+| J2 | Login -> Browse Products -> View Detail -> Price Chart | Search, navigation, data visualization |
+| J3 | Login -> Purchases -> Purchase Detail -> Product Link | List navigation, detail view, cross-linking |
+| J4 | Login -> Connect Store Account -> Verify Connection | OAuth flow, external integration |
+| J5 | Login -> Create Price Alert -> View -> Delete Alert | CRUD operations, confirmation dialogs |
+| J6 | Login -> Browse Coupons -> Copy Code | Clipboard interaction, toast feedback |
+| J7 | Login -> Settings -> Toggle Preferences -> Sign Out | Checkbox toggles, theme switch, session termination |
+| J8 | Login -> Store Comparison -> Compare Prices | Data comparison, sorting, price display |
+| J9 | Forgot Password Flow | Email input, validation, redirect |
+| J10 | Unauth Access -> Redirect to Login | Route protection, redirect behavior |
+
+---
+
+## 6. Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | 2026-03-30 | Savannah Savings | Initial runbook -- defect taxonomy, entry/exit criteria, execution procedure |
+

e2e/fixtures.ts

@@ -0,0 +1,12 @@
+import { test as base, expect } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+export const test = base.extend<{ axeCheck: void }>({
+  axeCheck: [async ({ page }, use) => {
+    await use();
+    const results = await new AxeBuilder({ page }).analyze();
+    expect(results.violations).toEqual([]);
+  }, { auto: true }],
+});
+
+export { expect } from "@playwright/test";

e2e/journeys/j1-registration-login.spec.ts

@@ -0,0 +1,56 @@
+import { test, expect } from '@playwright/test';
+
+const uniqueEmail = () => `betty+e2e-${Date.now()}@cartsnitch.test`;
+
+test.describe('J1: Registration and Login', () => {
+  test('can register a new account and lands on dashboard', async ({ page }) => {
+    await page.goto('/register');
+    await page.fill('[placeholder="Full Name"]', 'Betty Tester');
+    await page.fill('[placeholder="Email"]', uniqueEmail());
+    await page.fill('[placeholder="Password (min. 8 characters)"]', 'TestPass123!');
+    await page.click('button[type="submit"]');
+
+    // With VITE_MOCK_AUTH=true the app navigates to "/" on success
+    await expect(page).toHaveURL('http://localhost:5173/');
+    await expect(page.getByRole('heading', { name: /cart/i })).toBeVisible();
+  });
+
+  test('shows validation error when registration fields are empty', async ({ page }) => {
+    await page.goto('/register');
+    await page.click('button[type="submit"]');
+
+    await expect(page.locator('.bg-red-50')).toContainText('Please fill in all fields');
+  });
+
+  test('can navigate from register to login', async ({ page }) => {
+    await page.goto('/register');
+    await page.getByRole('link', { name: /sign in/i }).click();
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('can sign in with credentials and land on dashboard', async ({ page }) => {
+    // Register first so we have a real account
+    const email = uniqueEmail();
+    await page.goto('/register');
+    await page.fill('[placeholder="Full Name"]', 'Login Betty');
+    await page.fill('[placeholder="Email"]', email);
+    await page.fill('[placeholder="Password (min. 8 characters)"]', 'TestPass123!');
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL('http://localhost:5173/');
+
+    // Sign out by clearing the mock session (reload with no session)
+    await page.goto('/');
+    await page.reload();
+
+    // Now sign in
+    await page.goto('/login');
+    await page.fill('[placeholder="Email"]', email);
+    await page.fill('[placeholder="Password"]', 'TestPass123!');
+    await page.click('button[type="submit"]');
+
+    await expect(page).toHaveURL('http://localhost:5173/');
+  });
+
+});

e2e/journeys/j8-unauth-access.spec.ts

@@ -0,0 +1,49 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('J8: Unauthenticated Access', () => {
+  test('redirects /dashboard (/) to /login when not authenticated', async ({ page }) => {
+    // No session cookie — start fresh
+    await page.context().clearCookies();
+    await page.goto('/');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('redirects /purchases to /login when not authenticated', async ({ page }) => {
+    await page.context().clearCookies();
+    await page.goto('/purchases');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('redirects /products to /login when not authenticated', async ({ page }) => {
+    await page.context().clearCookies();
+    await page.goto('/products');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('redirects /coupons to /login when not authenticated', async ({ page }) => {
+    await page.context().clearCookies();
+    await page.goto('/coupons');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('shows loading spinner while auth session is pending', async ({ page }) => {
+    // Intercept but don't respond — session stays pending
+    await page.context().clearCookies();
+    await page.request.fetch('/api/auth/session', {
+      method: 'GET',
+    });
+
+    // Just navigate to a protected route — ProtectedRoute will show spinner while session is pending
+    await page.goto('/purchases');
+    // Spinner is visible briefly; once resolved, should redirect to login
+    await expect(page).toHaveURL(/\/login/, { timeout: 10_000 });
+  });
+});

e2e/smoke.spec.ts

@@ -0,0 +1,8 @@
+import { test, expect } from './fixtures';
+
+test('app loads', async ({ page }) => {
+  await page.goto('/');
+  // Unauthenticated users are redirected to /login
+  await expect(page).toHaveURL(/\/login/);
+  await expect(page.getByRole('heading', { name: /CartSnitch/i })).toBeVisible();
+});

lighthouserc.json

@@ -0,0 +1,24 @@
+{
+  "ci": {
+    "collect": {
+      "staticDistDir": "./dist",
+      "url": ["http://localhost:4173/"],
+      "numberOfRuns": 1,
+      "settings": {
+        "chromeFlags": ["--headless=new", "--no-sandbox", "--disable-gpu", "--disable-dev-shm-usage"],
+        "skipAudits": ["bf-cache"],
+        "disableFullPageScreenshot": true
+      }
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["warn", { "minScore": 0.7 }],
+        "categories:accessibility": ["error", { "minScore": 0.9 }],
+        "categories:best-practices": ["warn", { "minScore": 0.8 }]
+      }
+    },
+    "upload": {
+      "target": "temporary-public-storage"
+    }
+  }
+}

package.json

@@ -9,10 +9,13 @@
     "lint": "eslint .",
     "preview": "vite preview",
     "test": "NODE_ENV=test vitest run",
-    "test:watch": "NODE_ENV=test vitest"
+    "test:watch": "NODE_ENV=test vitest",
+    "test:e2e": "npx playwright test"
   },
   "dependencies": {
     "@tanstack/react-query": "^5.0.0",
+    "better-auth": "^1.2.0",
+    "picomatch": "4.0.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-router-dom": "^7.0.0",
@@ -20,24 +23,33 @@
     "zustand": "^5.0.0"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.10.0",
     "@eslint/js": "^9.39.4",
+    "@playwright/test": "^1.58.2",
     "@tailwindcss/vite": "^4.0.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.12.0",
     "@types/react": "^18.3.28",
     "@types/react-dom": "^18.3.7",
-    "@vitejs/plugin-react": "^4.5.2",
+    "@vitejs/plugin-react": "^4.7.0",
     "eslint": "^9.39.4",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "globals": "^17.4.0",
     "jsdom": "^25.0.1",
+    "msw": "^2.12.14",
+    "playwright": "^1.58.2",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.56.1",
     "vite": "^6.3.5",
     "vite-plugin-pwa": "^0.21.2",
     "vitest": "^3.2.4"
+  },
+  "overrides": {
+    "@rollup/pluginutils": "5.3.0",
+    "flatted": "^3.4.2",
+    "serialize-javascript": "7.0.5"
   }
 }

playwright.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  webServer: {
+    command: 'VITE_MOCK_AUTH=true npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+  use: {
+    baseURL: 'http://localhost:5173',
+  },
+});

public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://cartsnitch.com/sitemap.xml

receiptwitness/.github/workflows/ci.yml

@@ -1,168 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  packages: write
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: cartsnitch/receiptwitness
-
-jobs:
-  lint:
-    runs-on: runners-cartsnitch
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b"
-      - run: pip install ruff
-      - name: Ruff lint
-        run: ruff check .
-      - name: Ruff format check
-        run: ruff format --check .
-
-  typecheck:
-    runs-on: runners-cartsnitch
-    continue-on-error: true
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b"
-      - run: pip install -e ".[dev]" mypy
-      - name: Type check
-        run: mypy src/receiptwitness
-
-  test:
-    runs-on: runners-cartsnitch
-    services:
-      postgres:
-        image: postgres:15-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        env:
-          POSTGRES_USER: cartsnitch
-          POSTGRES_PASSWORD: cartsnitch_test
-          POSTGRES_DB: cartsnitch_test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-      redis:
-        image: redis:7-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-    env:
-      DATABASE_URL: postgresql://cartsnitch:cartsnitch_test@localhost:5432/cartsnitch_test
-      REDIS_URL: redis://localhost:6379/0
-      ENCRYPTION_KEY: dGVzdC1lbmNyeXB0aW9uLWtleS0xMjM0NTY3ODk=
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b"
-      - run: pip install -e ".[dev]"
-      - name: Install Playwright browsers
-        run: playwright install chromium --with-deps
-      - name: Run tests
-        run: pytest --tb=short -q
-
-  build-and-push:
-    runs-on: runners-cartsnitch
-    needs: [lint, test]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate CalVer tag
-        id: calver
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          DATE_TAG=$(date -u +%Y.%m.%d)
-          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
-          if [ -z "$EXISTING" ]; then
-            VERSION="$DATE_TAG"
-          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
-            VERSION="${DATE_TAG}.2"
-          else
-            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
-            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "CalVer tag: $VERSION"
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Log in to GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=sha,prefix=sha-
-            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
-            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
-
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          target: prod
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-      - name: Create git tag
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          git tag "v${{ steps.calver.outputs.version }}"
-          git push origin "v${{ steps.calver.outputs.version }}"

receiptwitness/Dockerfile

@@ -3,24 +3,21 @@ FROM python:3.12-slim AS build
 
 WORKDIR /app
 
-# git is required to install cartsnitch-common from GitHub; build-essential and
-# libpq-dev are needed to compile any C-extension wheels (e.g. psycopg2 fallback)
+# build-essential and libpq-dev are needed to compile any C-extension wheels
+# (e.g. psycopg2 fallback).  No git needed — common/ is copied from the repo root.
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    git \
     libpq-dev \
     build-essential \
     && rm -rf /var/lib/apt/lists/*
 
-COPY pyproject.toml ./
-COPY src/ ./src/
+# Build context is the repo root.  These paths are relative to the root.
+COPY receiptwitness/pyproject.toml ./
+COPY receiptwitness/src/ ./src/
+COPY common/ ./common/
 
-# cartsnitch-common is not on PyPI — install it directly from GitHub, then
-# install the rest of the package dependencies in a single resolver pass so
-# pip can satisfy the cartsnitch-common>=0.1.0 constraint declared in
-# pyproject.toml without hitting PyPI for it.
-RUN pip install --no-cache-dir --prefix=/install \
-    "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b" \
-    .
+# Install from the local common/ (cartsnitch-common>=0.1.0 in pyproject.toml
+# will be satisfied by the local package) then install receiptwitness itself.
+RUN pip install --no-cache-dir --prefix=/install ./common/ .
 
 # Stage 2: Production image with Playwright + Chromium
 FROM python:3.12-slim AS prod
@@ -51,7 +48,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 RUN adduser --system --group --uid 1000 app
 
 COPY --from=build /install /usr/local
-COPY src/ ./src/
+COPY receiptwitness/src/ ./src/
 
 # Install Playwright Chromium browser (runs as root; /opt/playwright is world-readable)
 RUN PLAYWRIGHT_BROWSERS_PATH=/opt/playwright playwright install chromium

src/App.test.tsx

@@ -1,17 +1,17 @@
-import { render, screen } from '@testing-library/react'
-import { describe, it, expect } from 'vitest'
-import App from './App.tsx'
-
-describe('App', () => {
-  it('renders the dashboard on the root route', () => {
-    render(<App />)
-    expect(screen.getByText('CartSnitch')).toBeInTheDocument()
-  })
-
-  it('renders the bottom navigation', () => {
-    render(<App />)
-    expect(screen.getByText('Home')).toBeInTheDocument()
-    expect(screen.getByText('Purchases')).toBeInTheDocument()
-    expect(screen.getByText('Products')).toBeInTheDocument()
-  })
-})
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import App from './App.tsx'
+
+vi.mock('./lib/auth-client.ts', () => ({
+  authClient: {
+    useSession: () => ({ data: null, isPending: false }),
+  },
+}))
+
+describe('App', () => {
+  it('redirects unauthenticated users to login', () => {
+    render(<App />)
+    expect(screen.getByText('CartSnitch')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /sign in/i })).toBeInTheDocument()
+  })
+})

src/App.tsx

@@ -31,8 +31,8 @@ export default function App() {
       <BrowserRouter>
         <Routes>
           <Route element={<Layout />}>
-            <Route index element={<Dashboard />} />
             <Route element={<ProtectedRoute />}>
+              <Route index element={<Dashboard />} />
               <Route path="purchases" element={<Purchases />} />
               <Route path="purchases/:id" element={<PurchaseDetail />} />
               <Route path="products" element={<Products />} />

src/components/ProtectedRoute.tsx

@@ -1,10 +1,35 @@
+import { useEffect } from 'react'
 import { Navigate, Outlet } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
 import { useAuthStore } from '../stores/auth.ts'
 
 export function ProtectedRoute() {
+  const isMockAuth = import.meta.env.VITE_MOCK_AUTH === 'true'
+  const { data: session, isPending } = authClient.useSession()
   const isAuthenticated = useAuthStore((s) => s.isAuthenticated)
+  const setAuthenticated = useAuthStore((s) => s.setAuthenticated)
 
-  if (!isAuthenticated) {
+  useEffect(() => {
+    if (!isMockAuth) {
+      setAuthenticated(!!session)
+    }
+  }, [session, setAuthenticated, isMockAuth])
+
+  // In mock auth mode, rely on Zustand store (set by Login/Register pages)
+  if (isMockAuth) {
+    if (!isAuthenticated) return <Navigate to="/login" replace />
+    return <Outlet />
+  }
+
+  if (isPending) {
+    return (
+      <div className="flex min-h-screen items-center justify-center">
+        <div className="h-8 w-8 animate-spin rounded-full border-2 border-brand-blue border-t-transparent" />
+      </div>
+    )
+  }
+
+  if (!session) {
     return <Navigate to="/login" replace />
   }
 

src/hooks/__tests__/useApi.test.tsx

@@ -0,0 +1,45 @@
+import { renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { usePurchases } from '../useApi'
+import { http, HttpResponse } from 'msw'
+import { server } from '../../test/mocks/server'
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  })
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        {children}
+      </QueryClientProvider>
+    )
+  }
+}
+
+describe('useApi hooks', () => {
+  describe('usePurchases', () => {
+    it('fetches and returns purchases', async () => {
+      const { result } = renderHook(() => usePurchases(), { wrapper: createWrapper() })
+
+      await waitFor(() => expect(result.current.isSuccess).toBe(true))
+
+      expect(result.current.data).toHaveLength(1)
+      expect(result.current.data![0]).toMatchObject({
+        id: 'pur_1',
+        storeName: 'Kroger',
+        total: 42.5,
+      })
+    })
+
+    it('returns an error when the endpoint fails', async () => {
+      server.use(
+        http.get('/api/v1/purchases', () => HttpResponse.error()),
+      )
+
+      const { result } = renderHook(() => usePurchases(), { wrapper: createWrapper() })
+
+      await waitFor(() => expect(result.current.isError).toBe(true))
+    })
+  })
+})

src/hooks/useApi.ts

@@ -35,7 +35,7 @@ export function useProduct(id: string) {
 export function usePriceHistory(productId: string) {
   return useQuery({
     queryKey: ['priceHistory', productId],
-    queryFn: () => api.get<PriceHistory[]>(`/products/${productId}/price-history`),
+    queryFn: () => api.get<PriceHistory[]>(`/products/${productId}/prices`),
     enabled: !!productId,
   })
 }
@@ -50,6 +50,6 @@ export function useCoupons() {
 export function usePriceAlerts() {
   return useQuery({
     queryKey: ['priceAlerts'],
-    queryFn: () => api.get<PriceAlert[]>('/price-alerts'),
+    queryFn: () => api.get<PriceAlert[]>('/alerts'),
   })
 }

src/lib/api.ts

@@ -1,100 +1,98 @@
-import { useAuthStore } from '../stores/auth.ts'
-import {
-  mockPurchases,
-  mockProducts,
-  mockCoupons,
-  mockAlerts,
-  getMockPriceHistory,
-} from './mock-data.ts'
-
-const API_BASE = import.meta.env.VITE_API_URL ?? '/api/v1'
-const USE_MOCK = import.meta.env.VITE_MOCK_API === 'true'
-
-// Mock response lookup table
-const mockRoutes: Record<string, (path: string) => unknown> = {
-  '/purchases': () => mockPurchases,
-  '/products': () => mockProducts,
-  '/coupons': () => mockCoupons,
-  '/price-alerts': () => mockAlerts,
-}
-
-function matchMockRoute<T>(path: string): T | null {
-  // Exact match
-  if (mockRoutes[path]) return mockRoutes[path](path) as T
-
-  // /purchases/:id
-  const purchaseMatch = path.match(/^\/purchases\/(.+)$/)
-  if (purchaseMatch) {
-    const purchase = mockPurchases.find((p) => p.id === purchaseMatch[1])
-    return (purchase ?? null) as T
-  }
-
-  // /products/:id/price-history
-  const priceHistoryMatch = path.match(/^\/products\/(.+)\/price-history$/)
-  if (priceHistoryMatch) {
-    return getMockPriceHistory(priceHistoryMatch[1]) as T
-  }
-
-  // /products?q=search or /products/:id
-  const productMatch = path.match(/^\/products\/(.+)$/)
-  if (productMatch) {
-    const product = mockProducts.find((p) => p.id === productMatch[1])
-    return (product ?? null) as T
-  }
-
-  const productsSearch = path.match(/^\/products\?q=(.+)$/)
-  if (productsSearch) {
-    const q = decodeURIComponent(productsSearch[1]).toLowerCase()
-    return mockProducts.filter(
-      (p) =>
-        p.name.toLowerCase().includes(q) ||
-        p.brand.toLowerCase().includes(q) ||
-        p.category.toLowerCase().includes(q),
-    ) as T
-  }
-
-  return null
-}
-
-async function apiFetch<T>(path: string, options?: RequestInit): Promise<T> {
-  // Mock interceptor: return mock data without hitting the network
-  if (USE_MOCK && (!options?.method || options.method === 'GET')) {
-    const mockResult = matchMockRoute<T>(path)
-    if (mockResult !== null) {
-      // Simulate network delay for realistic loading states
-      await new Promise((r) => setTimeout(r, 300))
-      return mockResult
-    }
-  }
-
-  const token = useAuthStore.getState().token
-
-  const res = await fetch(`${API_BASE}${path}`, {
-    ...options,
-    headers: {
-      'Content-Type': 'application/json',
-      ...(token ? { Authorization: `Bearer ${token}` } : {}),
-      ...options?.headers,
-    },
-  })
-
-  if (res.status === 401) {
-    useAuthStore.getState().logout()
-    throw new Error('Unauthorized')
-  }
-
-  if (!res.ok) {
-    throw new Error(`API error: ${res.status}`)
-  }
-
-  return res.json() as Promise<T>
-}
-
-export const api = {
-  get: <T>(path: string) => apiFetch<T>(path),
-  post: <T>(path: string, body: unknown) =>
-    apiFetch<T>(path, { method: 'POST', body: JSON.stringify(body) }),
-  put: <T>(path: string, body: unknown) =>
-    apiFetch<T>(path, { method: 'PUT', body: JSON.stringify(body) }),
-  delete: <T>(path: string) => apiFetch<T>(path, { method: 'DELETE' }),
-}
+import { useAuthStore } from '../stores/auth.ts'
+import {
+  mockPurchases,
+  mockProducts,
+  mockCoupons,
+  mockAlerts,
+  getMockPriceHistory,
+} from './mock-data.ts'
+
+const API_BASE = import.meta.env.VITE_API_URL ?? '/api/v1'
+const USE_MOCK = import.meta.env.VITE_MOCK_API === 'true'
+
+// Mock response lookup table
+const mockRoutes: Record<string, (path: string) => unknown> = {
+  '/purchases': () => mockPurchases,
+  '/products': () => mockProducts,
+  '/coupons': () => mockCoupons,
+  '/alerts': () => mockAlerts,
+}
+
+function matchMockRoute<T>(path: string): T | null {
+  // Exact match
+  if (mockRoutes[path]) return mockRoutes[path](path) as T
+
+  // /purchases/:id
+  const purchaseMatch = path.match(/^\/purchases\/(.+)$/)
+  if (purchaseMatch) {
+    const purchase = mockPurchases.find((p) => p.id === purchaseMatch[1])
+    return (purchase ?? null) as T
+  }
+
+  // /products/:id/price-history
+  const priceHistoryMatch = path.match(/^\/products\/(.+)\/prices$/)
+  if (priceHistoryMatch) {
+    return getMockPriceHistory(priceHistoryMatch[1]) as T
+  }
+
+  // /products/:id
+  const productMatch = path.match(/^\/products\/(.+)$/)
+  if (productMatch) {
+    const product = mockProducts.find((p) => p.id === productMatch[1])
+    return (product ?? null) as T
+  }
+
+  const productsSearch = path.match(/^\/products\?q=(.+)$/)
+  if (productsSearch) {
+    const q = decodeURIComponent(productsSearch[1]).toLowerCase()
+    return mockProducts.filter(
+      (p) =>
+        p.name.toLowerCase().includes(q) ||
+        p.brand.toLowerCase().includes(q) ||
+        p.category.toLowerCase().includes(q),
+    ) as T
+  }
+
+  return null
+}
+
+async function apiFetch<T>(path: string, options?: RequestInit): Promise<T> {
+  // Mock interceptor: return mock data without hitting the network
+  if (USE_MOCK && (!options?.method || options.method === 'GET')) {
+    const mockResult = matchMockRoute<T>(path)
+    if (mockResult !== null) {
+      // Simulate network delay for realistic loading states
+      await new Promise((r) => setTimeout(r, 300))
+      return mockResult
+    }
+  }
+
+  const res = await fetch(`${API_BASE}${path}`, {
+    ...options,
+    credentials: 'include', // Send Better-Auth session cookie
+    headers: {
+      'Content-Type': 'application/json',
+      ...options?.headers,
+    },
+  })
+
+  if (res.status === 401) {
+    useAuthStore.getState().setAuthenticated(false)
+    throw new Error('Unauthorized')
+  }
+
+  if (!res.ok) {
+    throw new Error(`API error: ${res.status}`)
+  }
+
+  return res.json() as Promise<T>
+}
+
+export const api = {
+  get: <T>(path: string) => apiFetch<T>(path),
+  post: <T>(path: string, body: unknown) =>
+    apiFetch<T>(path, { method: 'POST', body: JSON.stringify(body) }),
+  put: <T>(path: string, body: unknown) =>
+    apiFetch<T>(path, { method: 'PUT', body: JSON.stringify(body) }),
+  delete: <T>(path: string) => apiFetch<T>(path, { method: 'DELETE' }),
+}

src/lib/auth-client.ts

@@ -0,0 +1,36 @@
+import { createAuthClient } from "better-auth/react"
+import type { BetterFetchPlugin } from "@better-fetch/fetch"
+
+/**
+ * Maps 'name' -> 'display_name' in register requests to match the API's RegisterRequest schema.
+ */
+const displayNameMapper: BetterFetchPlugin = {
+  id: "display-name-mapper",
+  name: "display-name-mapper",
+  hooks: {
+    onRequest: async (context) => {
+      const url = typeof context.url === "string" ? context.url : context.url.pathname
+      if (
+        url.endsWith("/auth/register") &&
+        context.method === "POST" &&
+        context.body &&
+        "name" in context.body
+      ) {
+        context.body = {
+          ...context.body,
+          display_name: context.body.name as string,
+          name: undefined,
+        }
+      }
+      return context
+    },
+  },
+}
+
+export const authClient = createAuthClient({
+  baseURL: import.meta.env.VITE_AUTH_URL || "",
+  basePath: "/auth",
+  fetchPlugins: [displayNameMapper],
+})
+
+export const { useSession, signIn, signUp, signOut } = authClient

src/pages/Dashboard.tsx

@@ -1,197 +1,201 @@
-import React, { Suspense } from 'react'
-import { Link } from 'react-router-dom'
-import { useAuthStore } from '../stores/auth.ts'
-import { usePurchases, usePriceAlerts, usePriceHistory } from '../hooks/useApi.ts'
-import { StoreIcon } from '../components/StoreIcon.tsx'
-
-const LazySparklineCard = React.lazy(() =>
-  import('../components/SparklineChart.tsx').then((mod) => ({ default: mod.SparklineCard }))
-)
-
-export function Dashboard() {
-  const user = useAuthStore((s) => s.user)
-  const isAuthenticated = useAuthStore((s) => s.isAuthenticated)
-
-  if (!isAuthenticated) {
-    return (
-      <div className="py-8 text-center">
-        <h1 className="text-2xl font-bold text-gray-900">CartSnitch</h1>
-        <p className="mt-2 text-sm text-gray-500">Track prices. Save money.</p>
-        <div className="mt-8 space-y-3">
-          <Link
-            to="/login"
-            className="block min-h-12 rounded-xl bg-brand-blue px-4 py-3 text-center text-base font-medium text-white active:bg-brand-blue/90"
-          >
-            Sign In
-          </Link>
-          <Link
-            to="/register"
-            className="block min-h-12 rounded-xl border border-gray-200 px-4 py-3 text-center text-base font-medium text-gray-700 active:bg-gray-50"
-          >
-            Create Account
-          </Link>
-        </div>
-      </div>
-    )
-  }
-
-  return <AuthenticatedDashboard userName={user?.name ?? 'there'} />
-}
-
-function AuthenticatedDashboard({ userName }: { userName: string }) {
-  const { data: purchases = [], isLoading: purchasesLoading } = usePurchases()
-  const { data: alerts = [], isLoading: alertsLoading } = usePriceAlerts()
-  const { data: eggHistory = [] } = usePriceHistory('prod10')
-  const { data: milkHistory = [] } = usePriceHistory('prod1')
-
-  const triggeredAlerts = alerts.filter((a) => a.triggered)
-  const watchingAlerts = alerts.filter((a) => !a.triggered)
-  const recentPurchases = purchases.slice(0, 3)
-
-  const sparklineData = eggHistory.filter((p) => p.storeId === 'meijer').slice(-8)
-  const milkSparkline = milkHistory.filter((p) => p.storeId === 'kroger').slice(-8)
-
-  const eggCurrent = sparklineData.length > 0 ? `$${sparklineData[sparklineData.length - 1].price.toFixed(2)}` : '—'
-  const milkCurrent = milkSparkline.length > 0 ? `$${milkSparkline[milkSparkline.length - 1].price.toFixed(2)}` : '—'
-
-  if (purchasesLoading || alertsLoading) {
-    return <DashboardSkeleton />
-  }
-
-  return (
-    <div>
-      <h1 className="text-2xl font-bold text-gray-900">
-        Hi, {userName.split(' ')[0]}
-      </h1>
-
-      {/* Triggered alerts banner */}
-      {triggeredAlerts.length > 0 && (
-        <Link
-          to="/alerts"
-          className="mt-4 flex items-center gap-3 rounded-xl bg-green-50 p-4"
-        >
-          <span className="flex h-10 w-10 items-center justify-center rounded-full bg-green-500 text-lg text-white">
-            &#x2713;
-          </span>
-          <div>
-            <p className="text-sm font-semibold text-green-800">
-              {triggeredAlerts.length} price {triggeredAlerts.length === 1 ? 'alert' : 'alerts'} triggered!
-            </p>
-            <p className="text-xs text-green-700">
-              {triggeredAlerts.map((a) => a.productName).join(', ')}
-            </p>
-          </div>
-        </Link>
-      )}
-
-      {/* Quick stats */}
-      <div className="mt-4 grid grid-cols-2 gap-3">
-        <div className="rounded-xl bg-white p-4 shadow-sm">
-          <p className="text-xs font-medium text-gray-500">Watching</p>
-          <p className="mt-1 text-2xl font-bold text-gray-900">{watchingAlerts.length}</p>
-          <p className="text-xs text-gray-400">price alerts</p>
-        </div>
-        <div className="rounded-xl bg-white p-4 shadow-sm">
-          <p className="text-xs font-medium text-gray-500">This Month</p>
-          <p className="mt-1 text-2xl font-bold text-gray-900">
-            ${recentPurchases.reduce((sum, p) => sum + p.total, 0).toFixed(0)}
-          </p>
-          <p className="text-xs text-gray-400">grocery spend</p>
-        </div>
-      </div>
-
-      {/* Price trend sparklines */}
-      <section className="mt-6">
-        <h2 className="mb-3 text-lg font-semibold text-gray-700">Price Trends</h2>
-        <div className="space-y-3">
-          <Suspense fallback={<SparklinePlaceholder />}>
-            <LazySparklineCard label="Eggs (dozen)" data={sparklineData} current={eggCurrent} />
-            <LazySparklineCard label="Whole Milk (1 gal)" data={milkSparkline} current={milkCurrent} />
-          </Suspense>
-        </div>
-      </section>
-
-      {/* Recent purchases */}
-      <section className="mt-6">
-        <div className="flex items-center justify-between">
-          <h2 className="text-lg font-semibold text-gray-700">Recent Purchases</h2>
-          <Link to="/purchases" className="text-sm text-brand-blue">
-            View all
-          </Link>
-        </div>
-        <div className="mt-3 space-y-3">
-          {recentPurchases.map((purchase) => (
-            <Link
-              key={purchase.id}
-              to={`/purchases/${purchase.id}`}
-              className="flex items-center gap-3 rounded-xl bg-white p-4 shadow-sm active:bg-gray-50"
-            >
-              <StoreIcon storeId={purchase.storeId} />
-              <div className="min-w-0 flex-1">
-                <p className="text-sm font-medium text-gray-900">{purchase.storeName}</p>
-                <p className="text-xs text-gray-500">
-                  {new Date(purchase.date).toLocaleDateString('en-US', {
-                    month: 'short',
-                    day: 'numeric',
-                  })}{' '}
-                  &middot; {purchase.items.length} items
-                </p>
-              </div>
-              <span className="text-sm font-semibold text-gray-900">
-                ${purchase.total.toFixed(2)}
-              </span>
-            </Link>
-          ))}
-        </div>
-      </section>
-
-      {/* Quick actions */}
-      <section className="mt-6 pb-4">
-        <h2 className="mb-3 text-lg font-semibold text-gray-700">Quick Actions</h2>
-        <div className="grid grid-cols-2 gap-3">
-          <Link
-            to="/products"
-            className="flex min-h-12 items-center justify-center rounded-xl border border-gray-200 bg-white px-4 py-3 text-sm font-medium text-gray-700 shadow-sm active:bg-gray-50"
-          >
-            Compare Prices
-          </Link>
-          <Link
-            to="/settings"
-            className="flex min-h-12 items-center justify-center rounded-xl border border-gray-200 bg-white px-4 py-3 text-sm font-medium text-gray-700 shadow-sm active:bg-gray-50"
-          >
-            Link a Store
-          </Link>
-        </div>
-      </section>
-    </div>
-  )
-}
-
-function DashboardSkeleton() {
-  return (
-    <div className="animate-pulse">
-      <div className="h-8 w-40 rounded bg-gray-200" />
-      <div className="mt-4 grid grid-cols-2 gap-3">
-        <div className="h-24 rounded-xl bg-gray-200" />
-        <div className="h-24 rounded-xl bg-gray-200" />
-      </div>
-      <div className="mt-6 h-5 w-28 rounded bg-gray-200" />
-      <div className="mt-3 space-y-3">
-        <div className="h-16 rounded-xl bg-gray-200" />
-        <div className="h-16 rounded-xl bg-gray-200" />
-      </div>
-    </div>
-  )
-}
-
-function SparklinePlaceholder() {
-  return (
-    <div className="flex items-center gap-4 rounded-xl bg-white p-4 shadow-sm animate-pulse">
-      <div className="min-w-0 flex-1">
-        <div className="h-4 w-24 rounded bg-gray-200" />
-        <div className="mt-2 h-6 w-16 rounded bg-gray-200" />
-      </div>
-      <div className="h-10 w-24 rounded bg-gray-100" />
-    </div>
-  )
-}
+import React, { Suspense } from 'react'
+import { Link } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
+import { usePurchases, usePriceAlerts, usePriceHistory } from '../hooks/useApi.ts'
+import { StoreIcon } from '../components/StoreIcon.tsx'
+
+const LazySparklineCard = React.lazy(() =>
+  import('../components/SparklineChart.tsx').then((mod) => ({ default: mod.SparklineCard }))
+)
+
+export function Dashboard() {
+  const { data: session, isPending } = authClient.useSession()
+
+  if (isPending) {
+    return <DashboardSkeleton />
+  }
+
+  if (!session) {
+    return (
+      <div className="py-8 text-center">
+        <h1 className="text-2xl font-bold text-gray-900">CartSnitch</h1>
+        <p className="mt-2 text-sm text-gray-500">Track prices. Save money.</p>
+        <div className="mt-8 space-y-3">
+          <Link
+            to="/login"
+            className="block min-h-12 rounded-xl bg-brand-blue px-4 py-3 text-center text-base font-medium text-white active:bg-brand-blue/90"
+          >
+            Sign In
+          </Link>
+          <Link
+            to="/register"
+            className="block min-h-12 rounded-xl border border-gray-200 px-4 py-3 text-center text-base font-medium text-gray-700 active:bg-gray-50"
+          >
+            Create Account
+          </Link>
+        </div>
+      </div>
+    )
+  }
+
+  return <AuthenticatedDashboard userName={session.user?.name ?? 'there'} />
+}
+
+function AuthenticatedDashboard({ userName }: { userName: string }) {
+  const { data: purchases = [], isLoading: purchasesLoading } = usePurchases()
+  const { data: alerts = [], isLoading: alertsLoading } = usePriceAlerts()
+  const { data: eggHistory = [] } = usePriceHistory('prod10')
+  const { data: milkHistory = [] } = usePriceHistory('prod1')
+
+  const triggeredAlerts = alerts.filter((a) => a.triggered)
+  const watchingAlerts = alerts.filter((a) => !a.triggered)
+  const recentPurchases = purchases.slice(0, 3)
+
+  const sparklineData = eggHistory.filter((p) => p.storeId === 'meijer').slice(-8)
+  const milkSparkline = milkHistory.filter((p) => p.storeId === 'kroger').slice(-8)
+
+  const eggCurrent = sparklineData.length > 0 ? `$${sparklineData[sparklineData.length - 1].price.toFixed(2)}` : '—'
+  const milkCurrent = milkSparkline.length > 0 ? `$${milkSparkline[milkSparkline.length - 1].price.toFixed(2)}` : '—'
+
+  if (purchasesLoading || alertsLoading) {
+    return <DashboardSkeleton />
+  }
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold text-gray-900">
+        Hi, {userName.split(' ')[0]}
+      </h1>
+
+      {/* Triggered alerts banner */}
+      {triggeredAlerts.length > 0 && (
+        <Link
+          to="/alerts"
+          className="mt-4 flex items-center gap-3 rounded-xl bg-green-50 p-4"
+        >
+          <span className="flex h-10 w-10 items-center justify-center rounded-full bg-green-500 text-lg text-white">
+            &#x2713;
+          </span>
+          <div>
+            <p className="text-sm font-semibold text-green-800">
+              {triggeredAlerts.length} price {triggeredAlerts.length === 1 ? 'alert' : 'alerts'} triggered!
+            </p>
+            <p className="text-xs text-green-700">
+              {triggeredAlerts.map((a) => a.productName).join(', ')}
+            </p>
+          </div>
+        </Link>
+      )}
+
+      {/* Quick stats */}
+      <div className="mt-4 grid grid-cols-2 gap-3">
+        <div className="rounded-xl bg-white p-4 shadow-sm">
+          <p className="text-xs font-medium text-gray-500">Watching</p>
+          <p className="mt-1 text-2xl font-bold text-gray-900">{watchingAlerts.length}</p>
+          <p className="text-xs text-gray-400">price alerts</p>
+        </div>
+        <div className="rounded-xl bg-white p-4 shadow-sm">
+          <p className="text-xs font-medium text-gray-500">This Month</p>
+          <p className="mt-1 text-2xl font-bold text-gray-900">
+            ${recentPurchases.reduce((sum, p) => sum + p.total, 0).toFixed(0)}
+          </p>
+          <p className="text-xs text-gray-400">grocery spend</p>
+        </div>
+      </div>
+
+      {/* Price trend sparklines */}
+      <section className="mt-6">
+        <h2 className="mb-3 text-lg font-semibold text-gray-700">Price Trends</h2>
+        <div className="space-y-3">
+          <Suspense fallback={<SparklinePlaceholder />}>
+            <LazySparklineCard label="Eggs (dozen)" data={sparklineData} current={eggCurrent} />
+            <LazySparklineCard label="Whole Milk (1 gal)" data={milkSparkline} current={milkCurrent} />
+          </Suspense>
+        </div>
+      </section>
+
+      {/* Recent purchases */}
+      <section className="mt-6">
+        <div className="flex items-center justify-between">
+          <h2 className="text-lg font-semibold text-gray-700">Recent Purchases</h2>
+          <Link to="/purchases" className="text-sm text-brand-blue">
+            View all
+          </Link>
+        </div>
+        <div className="mt-3 space-y-3">
+          {recentPurchases.map((purchase) => (
+            <Link
+              key={purchase.id}
+              to={`/purchases/${purchase.id}`}
+              className="flex items-center gap-3 rounded-xl bg-white p-4 shadow-sm active:bg-gray-50"
+            >
+              <StoreIcon storeId={purchase.storeId} />
+              <div className="min-w-0 flex-1">
+                <p className="text-sm font-medium text-gray-900">{purchase.storeName}</p>
+                <p className="text-xs text-gray-500">
+                  {new Date(purchase.date).toLocaleDateString('en-US', {
+                    month: 'short',
+                    day: 'numeric',
+                  })}{' '}
+                  &middot; {purchase.items.length} items
+                </p>
+              </div>
+              <span className="text-sm font-semibold text-gray-900">
+                ${purchase.total.toFixed(2)}
+              </span>
+            </Link>
+          ))}
+        </div>
+      </section>
+
+      {/* Quick actions */}
+      <section className="mt-6 pb-4">
+        <h2 className="mb-3 text-lg font-semibold text-gray-700">Quick Actions</h2>
+        <div className="grid grid-cols-2 gap-3">
+          <Link
+            to="/products"
+            className="flex min-h-12 items-center justify-center rounded-xl border border-gray-200 bg-white px-4 py-3 text-sm font-medium text-gray-700 shadow-sm active:bg-gray-50"
+          >
+            Compare Prices
+          </Link>
+          <Link
+            to="/settings"
+            className="flex min-h-12 items-center justify-center rounded-xl border border-gray-200 bg-white px-4 py-3 text-sm font-medium text-gray-700 shadow-sm active:bg-gray-50"
+          >
+            Link a Store
+          </Link>
+        </div>
+      </section>
+    </div>
+  )
+}
+
+function DashboardSkeleton() {
+  return (
+    <div className="animate-pulse">
+      <h1 className="sr-only">Loading CartSnitch…</h1>
+      <div className="h-8 w-40 rounded bg-gray-200" />
+      <div className="mt-4 grid grid-cols-2 gap-3">
+        <div className="h-24 rounded-xl bg-gray-200" />
+        <div className="h-24 rounded-xl bg-gray-200" />
+      </div>
+      <div className="mt-6 h-5 w-28 rounded bg-gray-200" />
+      <div className="mt-3 space-y-3">
+        <div className="h-16 rounded-xl bg-gray-200" />
+        <div className="h-16 rounded-xl bg-gray-200" />
+      </div>
+    </div>
+  )
+}
+
+function SparklinePlaceholder() {
+  return (
+    <div className="flex items-center gap-4 rounded-xl bg-white p-4 shadow-sm animate-pulse">
+      <div className="min-w-0 flex-1">
+        <div className="h-4 w-24 rounded bg-gray-200" />
+        <div className="mt-2 h-6 w-16 rounded bg-gray-200" />
+      </div>
+      <div className="h-10 w-24 rounded bg-gray-100" />
+    </div>
+  )
+}

src/pages/Login.tsx

@@ -1,92 +1,103 @@
-import { useState } from 'react'
-import { Link, useNavigate } from 'react-router-dom'
-import { useAuthStore } from '../stores/auth.ts'
-import { api } from '../lib/api.ts'
-import { mockUser } from '../lib/mock-data.ts'
-import type { User } from '../types/api.ts'
-
-export function Login() {
-  const [email, setEmail] = useState('')
-  const [password, setPassword] = useState('')
-  const [error, setError] = useState('')
-  const [loading, setLoading] = useState(false)
-  const navigate = useNavigate()
-  const setAuth = useAuthStore((s) => s.setAuth)
-
-  async function handleSubmit(e: React.FormEvent) {
-    e.preventDefault()
-    setError('')
-
-    if (!email || !password) {
-      setError('Please fill in all fields.')
-      return
-    }
-
-    setLoading(true)
-    try {
-      const res = await api.post<{ user: User; token: string }>('/auth/login', { email, password })
-      setAuth(res.user, res.token)
-      navigate('/')
-    } catch {
-      if (import.meta.env.VITE_MOCK_AUTH === 'true') {
-        // Fallback to mock auth for demo
-        setAuth(mockUser, 'mock-jwt-token')
-        navigate('/')
-      } else {
-        setError('Invalid email or password. Please try again.')
-      }
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  return (
-    <div className="flex min-h-screen flex-col items-center justify-center px-4">
-      <h1 className="mb-2 text-3xl font-bold text-gray-900">CartSnitch</h1>
-      <p className="mb-8 text-sm text-gray-500">Track prices. Save money.</p>
-
-      {error && (
-        <div className="mb-4 w-full max-w-sm rounded-xl bg-red-50 px-4 py-3 text-sm text-red-700">
-          {error}
-        </div>
-      )}
-
-      <form className="w-full max-w-sm space-y-4" onSubmit={handleSubmit}>
-        <input
-          type="email"
-          placeholder="Email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          autoComplete="email"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <input
-          type="password"
-          placeholder="Password"
-          value={password}
-          onChange={(e) => setPassword(e.target.value)}
-          autoComplete="current-password"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <button
-          type="submit"
-          disabled={loading}
-          className="min-h-12 w-full rounded-xl bg-brand-blue px-4 py-3 text-base font-medium text-white active:bg-brand-blue/90 disabled:opacity-60"
-        >
-          {loading ? 'Signing in...' : 'Sign In'}
-        </button>
-      </form>
-
-      <Link to="/forgot-password" className="mt-4 text-sm text-brand-blue">
-        Forgot password?
-      </Link>
-
-      <p className="mt-6 text-sm text-gray-500">
-        Don't have an account?{' '}
-        <Link to="/register" className="text-brand-blue">
-          Sign up
-        </Link>
-      </p>
-    </div>
-  )
-}
+import { useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
+import { useAuthStore } from '../stores/auth.ts'
+
+export function Login() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+  const [loading, setLoading] = useState(false)
+  const navigate = useNavigate()
+  const setAuthenticated = useAuthStore((s) => s.setAuthenticated)
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    setError('')
+
+    if (!email || !password) {
+      setError('Please fill in all fields.')
+      return
+    }
+
+    setLoading(true)
+    try {
+      const { error: authError } = await authClient.signIn.email({
+        email,
+        password,
+      })
+
+      if (authError) {
+        throw new Error(authError.message ?? 'Sign in failed')
+      }
+
+      // After successful signIn, force a session fetch to confirm the cookie is set
+      // before navigating to the protected route
+      const sessionResult = await authClient.getSession()
+      if (sessionResult.data) {
+        navigate('/')
+      } else {
+        setError('Sign in failed. Please try again.')
+      }
+    } catch {
+      if (import.meta.env.VITE_MOCK_AUTH === 'true') {
+        setAuthenticated(true)
+        navigate('/')
+      } else {
+        setError('Invalid email or password. Please try again.')
+      }
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center px-4">
+      <h1 className="mb-2 text-3xl font-bold text-gray-900">CartSnitch</h1>
+      <p className="mb-8 text-sm text-gray-500">Track prices. Save money.</p>
+
+      {error && (
+        <div className="mb-4 w-full max-w-sm rounded-xl bg-red-50 px-4 py-3 text-sm text-red-700">
+          {error}
+        </div>
+      )}
+
+      <form className="w-full max-w-sm space-y-4" onSubmit={handleSubmit}>
+        <input
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          autoComplete="email"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <input
+          type="password"
+          placeholder="Password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          autoComplete="current-password"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <button
+          type="submit"
+          disabled={loading}
+          className="min-h-12 w-full rounded-xl bg-brand-blue px-4 py-3 text-base font-medium text-white active:bg-brand-blue/90 disabled:opacity-60"
+        >
+          {loading ? 'Signing in...' : 'Sign In'}
+        </button>
+      </form>
+
+      <Link to="/forgot-password" className="mt-4 text-sm text-brand-blue">
+        Forgot password?
+      </Link>
+
+      <p className="mt-6 text-sm text-gray-500">
+        Don't have an account?{' '}
+        <Link to="/register" className="text-brand-blue underline">
+          Sign up
+        </Link>
+      </p>
+    </main>
+  )
+}

src/pages/Register.tsx

@@ -1,102 +1,115 @@
-import { useState } from 'react'
-import { Link, useNavigate } from 'react-router-dom'
-import { useAuthStore } from '../stores/auth.ts'
-import { api } from '../lib/api.ts'
-import { mockUser } from '../lib/mock-data.ts'
-import type { User } from '../types/api.ts'
-
-export function Register() {
-  const [name, setName] = useState('')
-  const [email, setEmail] = useState('')
-  const [password, setPassword] = useState('')
-  const [error, setError] = useState('')
-  const [loading, setLoading] = useState(false)
-  const navigate = useNavigate()
-  const setAuth = useAuthStore((s) => s.setAuth)
-
-  async function handleSubmit(e: React.FormEvent) {
-    e.preventDefault()
-    setError('')
-
-    if (!name || !email || !password) {
-      setError('Please fill in all fields.')
-      return
-    }
-
-    if (password.length < 8) {
-      setError('Password must be at least 8 characters.')
-      return
-    }
-
-    setLoading(true)
-    try {
-      const res = await api.post<{ user: User; token: string }>('/auth/register', { name, email, password })
-      setAuth(res.user, res.token)
-      navigate('/')
-    } catch {
-      if (import.meta.env.VITE_MOCK_AUTH === 'true') {
-        // Fallback to mock auth for demo
-        setAuth({ ...mockUser, name, email }, 'mock-jwt-token')
-        navigate('/')
-      } else {
-        setError('Registration failed. Please try again.')
-      }
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  return (
-    <div className="flex min-h-screen flex-col items-center justify-center px-4">
-      <h1 className="mb-2 text-3xl font-bold text-gray-900">Create Account</h1>
-      <p className="mb-8 text-sm text-gray-500">Start tracking your grocery prices.</p>
-
-      {error && (
-        <div className="mb-4 w-full max-w-sm rounded-xl bg-red-50 px-4 py-3 text-sm text-red-700">
-          {error}
-        </div>
-      )}
-
-      <form className="w-full max-w-sm space-y-4" onSubmit={handleSubmit}>
-        <input
-          type="text"
-          placeholder="Full Name"
-          value={name}
-          onChange={(e) => setName(e.target.value)}
-          autoComplete="name"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <input
-          type="email"
-          placeholder="Email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          autoComplete="email"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <input
-          type="password"
-          placeholder="Password (min. 8 characters)"
-          value={password}
-          onChange={(e) => setPassword(e.target.value)}
-          autoComplete="new-password"
-          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
-        />
-        <button
-          type="submit"
-          disabled={loading}
-          className="min-h-12 w-full rounded-xl bg-brand-blue px-4 py-3 text-base font-medium text-white active:bg-brand-blue/90 disabled:opacity-60"
-        >
-          {loading ? 'Creating account...' : 'Create Account'}
-        </button>
-      </form>
-
-      <p className="mt-6 text-sm text-gray-500">
-        Already have an account?{' '}
-        <Link to="/login" className="text-brand-blue">
-          Sign in
-        </Link>
-      </p>
-    </div>
-  )
-}
+import { useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
+import { useAuthStore } from '../stores/auth.ts'
+
+export function Register() {
+  const [name, setName] = useState('')
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+  const [loading, setLoading] = useState(false)
+  const navigate = useNavigate()
+  const setAuthenticated = useAuthStore((s) => s.setAuthenticated)
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    setError('')
+
+    if (!name || !email || !password) {
+      setError('Please fill in all fields.')
+      return
+    }
+
+    if (password.length < 8) {
+      setError('Password must be at least 8 characters.')
+      return
+    }
+
+    setLoading(true)
+    try {
+      const { error: authError } = await authClient.signUp.email({
+        name,
+        email,
+        password,
+      })
+
+      if (authError) {
+        throw new Error(authError.message ?? 'Registration failed')
+      }
+
+      // After successful signUp, force a session fetch to confirm the cookie is set
+      // before navigating to the protected route
+      const sessionResult = await authClient.getSession()
+      if (sessionResult.data) {
+        navigate('/')
+      } else {
+        // Session not established — show success message and link to login
+        setError('Account created! Please sign in.')
+      }
+    } catch {
+      if (import.meta.env.VITE_MOCK_AUTH === 'true') {
+        setAuthenticated(true)
+        navigate('/')
+      } else {
+        setError('Registration failed. Please try again.')
+      }
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center px-4">
+      <h1 className="mb-2 text-3xl font-bold text-gray-900">Create Account</h1>
+      <p className="mb-8 text-sm text-gray-500">Start tracking your grocery prices.</p>
+
+      {error && (
+        <div className="mb-4 w-full max-w-sm rounded-xl bg-red-50 px-4 py-3 text-sm text-red-700">
+          {error}
+        </div>
+      )}
+
+      <form className="w-full max-w-sm space-y-4" onSubmit={handleSubmit}>
+        <input
+          type="text"
+          placeholder="Full Name"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          autoComplete="name"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <input
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          autoComplete="email"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <input
+          type="password"
+          placeholder="Password (min. 8 characters)"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          autoComplete="new-password"
+          className="min-h-12 w-full rounded-xl border border-gray-200 px-4 text-base focus:border-brand-blue focus:outline-none focus:ring-1 focus:ring-brand-blue"
+        />
+        <button
+          type="submit"
+          disabled={loading}
+          className="min-h-12 w-full rounded-xl bg-brand-blue px-4 py-3 text-base font-medium text-white active:bg-brand-blue/90 disabled:opacity-60"
+        >
+          {loading ? 'Creating account...' : 'Create Account'}
+        </button>
+      </form>
+
+      <p className="mt-6 text-sm text-gray-500">
+        Already have an account?{' '}
+        <Link to="/login" className="text-brand-blue">
+          Sign in
+        </Link>
+      </p>
+    </div>
+  )
+}

src/pages/Settings.tsx

@@ -1,18 +1,21 @@
 import { Link, useNavigate } from 'react-router-dom'
+import { authClient } from '../lib/auth-client.ts'
 import { useAuthStore } from '../stores/auth.ts'
 import { useThemeStore } from '../stores/theme.ts'
 import { StoreIcon } from '../components/StoreIcon.tsx'
 
 export function Settings() {
-  const user = useAuthStore((s) => s.user)
-  const logout = useAuthStore((s) => s.logout)
+  const { data: session } = authClient.useSession()
+  const setAuthenticated = useAuthStore((s) => s.setAuthenticated)
   const navigate = useNavigate()
   const { theme, setTheme } = useThemeStore()
 
-  const connectedStores = user?.connectedStores ?? []
+  const user = session?.user
+  const connectedStores: string[] = []
 
-  function handleSignOut() {
-    logout()
+  async function handleSignOut() {
+    await authClient.signOut()
+    setAuthenticated(false)
     navigate('/login')
   }
 

src/stores/auth.ts

@@ -1,27 +1,18 @@
-import { create } from 'zustand'
-import { persist } from 'zustand/middleware'
-import type { User } from '../types/api.ts'
-
-interface AuthState {
-  user: User | null
-  token: string | null
-  isAuthenticated: boolean
-  setAuth: (user: User, token: string) => void
-  logout: () => void
-}
-
-export const useAuthStore = create<AuthState>()(
-  persist(
-    (set) => ({
-      user: null,
-      token: null,
-      isAuthenticated: false,
-      setAuth: (user, token) => set({ user, token, isAuthenticated: true }),
-      logout: () => set({ user: null, token: null, isAuthenticated: false }),
-    }),
-    {
-      name: 'cartsnitch-auth',
-      partialize: (state) => ({ user: state.user, isAuthenticated: state.isAuthenticated }),
-    },
-  ),
-)
+import { create } from 'zustand'
+
+/**
+ * Minimal auth state for UI reactivity.
+ *
+ * Session management is handled by Better-Auth via httpOnly cookies.
+ * This store only tracks whether we have an active session for UI
+ * gating (protected routes, nav state). No tokens in memory or localStorage.
+ */
+interface AuthState {
+  isAuthenticated: boolean
+  setAuthenticated: (value: boolean) => void
+}
+
+export const useAuthStore = create<AuthState>()((set) => ({
+  isAuthenticated: false,
+  setAuthenticated: (value) => set({ isAuthenticated: value }),
+}))

src/test/mocks/handlers.ts

@@ -0,0 +1,65 @@
+import { http, HttpResponse } from 'msw'
+import type { Purchase, Product, Coupon, PriceAlert } from '../../types/api.ts'
+
+const mockPurchases: Purchase[] = [
+  {
+    id: 'pur_1',
+    storeId: 'store_1',
+    storeName: 'Kroger',
+    date: '2024-01-15',
+    total: 42.5,
+    items: [
+      { id: 'item_1', productId: 'prod_1', name: 'Milk', quantity: 1, price: 3.99, unitPrice: 3.99 },
+      { id: 'item_2', productId: 'prod_2', name: 'Bread', quantity: 2, price: 5.98, unitPrice: 2.99 },
+    ],
+  },
+]
+
+const mockProducts: Product[] = [
+  {
+    id: 'prod_1',
+    name: 'Whole Milk',
+    brand: 'Kroger',
+    category: 'Dairy',
+    prices: [{ storeId: 'store_1', storeName: 'Kroger', price: 3.99, lastUpdated: '2024-01-15' }],
+  },
+  {
+    id: 'prod_2',
+    name: 'Whole Wheat Bread',
+    brand: 'Nature\'s Own',
+    category: 'Bakery',
+    prices: [{ storeId: 'store_1', storeName: 'Kroger', price: 2.99, lastUpdated: '2024-01-15' }],
+  },
+]
+
+const mockCoupons: Coupon[] = [
+  {
+    id: 'coupon_1',
+    productId: 'prod_1',
+    storeName: 'Kroger',
+    description: '$1 off milk',
+    discount: '$1.00',
+    expiresAt: '2024-12-31',
+    code: 'MILK1',
+  },
+]
+
+const mockAlerts: PriceAlert[] = [
+  {
+    id: 'alert_1',
+    productId: 'prod_1',
+    productName: 'Whole Milk',
+    targetPrice: 2.99,
+    currentPrice: 3.99,
+    triggered: false,
+  },
+]
+
+export const handlers = [
+  http.get('/api/v1/health', () => HttpResponse.json({ status: 'ok' })),
+  http.get('/api/v1/purchases', () => HttpResponse.json(mockPurchases)),
+  http.get('/api/v1/products', () => HttpResponse.json(mockProducts)),
+  http.get('/api/v1/products/prod_1', () => HttpResponse.json(mockProducts[0])),
+  http.get('/api/v1/coupons', () => HttpResponse.json(mockCoupons)),
+  http.get('/api/v1/alerts', () => HttpResponse.json(mockAlerts)),
+]

src/test/mocks/server.ts

@@ -0,0 +1,4 @@
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)

src/test/setup.ts

@@ -1 +1,6 @@
 import '@testing-library/jest-dom/vitest'
+import { server } from './mocks/server'
+
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())

src/utils/__tests__/formatCurrency.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { formatCurrency } from '../formatCurrency';
+
+describe('formatCurrency', () => {
+  it('formats 0 cents as $0.00', () => {
+    expect(formatCurrency(0)).toBe('$0.00');
+  });
+
+  it('formats 199 cents as $1.99', () => {
+    expect(formatCurrency(199)).toBe('$1.99');
+  });
+
+  it('formats 10000 cents as $100.00', () => {
+    expect(formatCurrency(10000)).toBe('$100.00');
+  });
+
+  it('handles negative values', () => {
+    expect(formatCurrency(-500)).toBe('-$5.00');
+  });
+
+  it('handles large numbers', () => {
+    expect(formatCurrency(99999999)).toBe('$999,999.99');
+  });
+
+  it('supports custom locale', () => {
+    expect(formatCurrency(1999, 'de-DE', 'EUR')).toContain('19,99');
+  });
+
+  it('supports custom currency', () => {
+    const result = formatCurrency(1000, 'en-US', 'EUR');
+    expect(result).toContain('10.00');
+  });
+});

src/utils/__tests__/formatDate.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { formatDate } from '../formatDate';
+
+describe('formatDate', () => {
+  describe('short style', () => {
+    it('formats an ISO date string', () => {
+      const result = formatDate('2024-03-15', 'short');
+      expect(result).toMatch(/Mar 15, 2024/);
+    });
+
+    it('formats a Date object', () => {
+      const result = formatDate(new Date('2024-03-15'), 'short');
+      expect(result).toMatch(/Mar 15, 2024/);
+    });
+  });
+
+  describe('long style', () => {
+    it('formats with weekday and full month name', () => {
+      const result = formatDate('2024-03-15', 'long');
+      expect(result).toMatch(/Friday/);
+      expect(result).toMatch(/March/);
+    });
+  });
+
+  describe('relative style', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('returns "just now" for very recent dates', () => {
+      const now = new Date('2024-01-01T12:00:00Z');
+      vi.setSystemTime(now);
+      const result = formatDate(new Date('2024-01-01T11:59:59Z'), 'relative');
+      expect(result).toBe('just now');
+    });
+
+    it('returns minutes ago', () => {
+      const now = new Date('2024-01-01T12:00:00Z');
+      vi.setSystemTime(now);
+      const result = formatDate(new Date('2024-01-01T11:45:00Z'), 'relative');
+      expect(result).toBe('15m ago');
+    });
+
+    it('returns hours ago', () => {
+      const now = new Date('2024-01-01T12:00:00Z');
+      vi.setSystemTime(now);
+      const result = formatDate(new Date('2024-01-01T09:00:00Z'), 'relative');
+      expect(result).toBe('3h ago');
+    });
+
+    it('returns days ago', () => {
+      const now = new Date('2024-01-05T12:00:00Z');
+      vi.setSystemTime(now);
+      const result = formatDate(new Date('2024-01-01T12:00:00Z'), 'relative');
+      expect(result).toBe('4d ago');
+    });
+  });
+});

src/utils/__tests__/storeSlugs.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { getStore, getStoreName, STORE_SLUGS } from '../storeSlugs';
+
+describe('storeSlugs', () => {
+  describe('STORE_SLUGS constant', () => {
+    it('contains meijer, kroger, and target', () => {
+      expect(STORE_SLUGS).toHaveProperty('meijer');
+      expect(STORE_SLUGS).toHaveProperty('kroger');
+      expect(STORE_SLUGS).toHaveProperty('target');
+    });
+  });
+
+  describe('getStore', () => {
+    it('returns store data for known slug', () => {
+      const store = getStore('meijer');
+      expect(store).toEqual({
+        name: 'Meijer',
+        color: '#e31837',
+        icon: '/icons/stores/meijer.svg',
+      });
+    });
+
+    it('returns null for unknown slug', () => {
+      expect(getStore('unknown-store')).toBeNull();
+    });
+
+    it('is case insensitive', () => {
+      expect(getStore('KROGER')).toBeTruthy();
+      expect(getStore('Target')).toBeTruthy();
+    });
+  });
+
+  describe('getStoreName', () => {
+    it('returns store name for known slug', () => {
+      expect(getStoreName('kroger')).toBe('Kroger');
+    });
+
+    it('returns raw slug for unknown store', () => {
+      expect(getStoreName('unknown-store')).toBe('unknown-store');
+    });
+
+    it('is case insensitive', () => {
+      expect(getStoreName('TARGET')).toBe('Target');
+    });
+  });
+});

src/utils/formatCurrency.ts

@@ -0,0 +1,10 @@
+export function formatCurrency(
+  cents: number,
+  locale = 'en-US',
+  currency = 'USD'
+): string {
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+  }).format(cents / 100);
+}

src/utils/formatDate.ts

@@ -0,0 +1,34 @@
+export function formatDate(
+  date: string | Date,
+  style: 'short' | 'long' | 'relative' = 'short'
+): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+
+  if (style === 'short') {
+    return d.toLocaleDateString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric',
+    });
+  }
+
+  if (style === 'long') {
+    return d.toLocaleDateString('en-US', {
+      weekday: 'long',
+      month: 'long',
+      day: 'numeric',
+      year: 'numeric',
+    });
+  }
+
+  // relative
+  const diff = Date.now() - d.getTime();
+  const seconds = Math.floor(diff / 1000);
+  if (seconds < 60) return 'just now';
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}

src/utils/storeSlugs.ts

@@ -0,0 +1,13 @@
+export const STORE_SLUGS: Record<string, { name: string; color: string; icon: string }> = {
+  meijer: { name: 'Meijer', color: '#e31837', icon: '/icons/stores/meijer.svg' },
+  kroger: { name: 'Kroger', color: '#0033a0', icon: '/icons/stores/kroger.svg' },
+  target: { name: 'Target', color: '#cc0000', icon: '/icons/stores/target.svg' },
+};
+
+export function getStore(slug: string) {
+  return STORE_SLUGS[slug.toLowerCase()] ?? null;
+}
+
+export function getStoreName(slug: string): string {
+  return getStore(slug)?.name ?? slug;
+}

vitest.config.ts

@@ -7,5 +7,6 @@ export default defineConfig({
     environment: 'jsdom',
     globals: true,
     setupFiles: ['./src/test/setup.ts'],
+    exclude: ['e2e/**', 'node_modules/**'],
   },
 })