fix(api): widen alembic version_table column to 128 chars

Default varchar(32) alembic_version column truncates long revision IDs
like 003_make_users_hashed_password_nullable (39 chars) on fresh databases.
Set version_table_column_width=128 in both context.configure() calls.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev, uat]
   pull_request:
-    branches: [main]
+    branches: [main, dev, uat]
 
 concurrency:
   group: ci-${{ github.ref }}
@@ -99,10 +99,11 @@ jobs:
 
   build-and-push:
     runs-on: runners-cartsnitch
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    if: github.event_name == 'push'
     needs: [lint, test, e2e]
     outputs:
       calver_tag: ${{ steps.calver.outputs.version }}
+      sha_tag: sha-${{ github.sha }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -126,14 +127,14 @@ jobs:
           echo "CalVer tag: $VERSION"
 
       - name: Log in to Docker Hub
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        if: github.event_name == 'push'
         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'
+        if: github.event_name == 'push'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
@@ -146,7 +147,7 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
-            type=sha,prefix=sha-
+            type=sha,prefix=sha-,format=long
             type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
             type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
 
@@ -154,7 +155,7 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          push: ${{ github.event_name == 'push' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           target: prod
@@ -169,10 +170,11 @@ jobs:
 
   build-and-push-auth:
     runs-on: runners-cartsnitch
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    if: github.event_name == 'push'
     needs: [lint, test, e2e]
     outputs:
       calver_tag: ${{ steps.calver.outputs.version }}
+      sha_tag: sha-${{ github.sha }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -195,14 +197,14 @@ jobs:
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
       - name: Log in to Docker Hub
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        if: github.event_name == 'push'
         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'
+        if: github.event_name == 'push'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
@@ -215,7 +217,7 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.AUTH_IMAGE_NAME }}
           tags: |
-            type=sha,prefix=sha-
+            type=sha,prefix=sha-,format=long
             type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
             type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
 
@@ -224,16 +226,17 @@ jobs:
         with:
           context: ./auth
           file: ./auth/Dockerfile
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          push: ${{ github.event_name == 'push' }}
           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'
+    if: github.event_name == 'push'
     needs: [lint, test]
     outputs:
       calver_tag: ${{ steps.calver.outputs.version }}
+      sha_tag: sha-${{ github.sha }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -251,14 +254,14 @@ jobs:
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
       - name: Log in to Docker Hub
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        if: github.event_name == 'push'
         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'
+        if: github.event_name == 'push'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
@@ -271,7 +274,7 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.RECEIPTWITNESS_IMAGE_NAME }}
           tags: |
-            type=sha,prefix=sha-
+            type=sha,prefix=sha-,format=long
             type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
             type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
 
@@ -280,16 +283,17 @@ jobs:
         with:
           context: .
           file: ./receiptwitness/Dockerfile
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          push: ${{ github.event_name == 'push' }}
           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'
+    if: github.event_name == 'push'
     needs: [lint, test]
     outputs:
       calver_tag: ${{ steps.calver.outputs.version }}
+      sha_tag: sha-${{ github.sha }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -307,14 +311,14 @@ jobs:
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
       - name: Log in to Docker Hub
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        if: github.event_name == 'push'
         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'
+        if: github.event_name == 'push'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
@@ -327,23 +331,23 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.API_IMAGE_NAME }}
           tags: |
-            type=sha,prefix=sha-
+            type=sha,prefix=sha-,format=long
             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: .
+          context: ./api
           file: ./api/Dockerfile
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          push: ${{ github.event_name == 'push' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
 
   deploy-dev:
     runs-on: runners-cartsnitch
     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'
+    if: always() && !cancelled() && github.event_name == 'push' && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main')
     steps:
       - name: Generate GitHub App token
         id: app-token
@@ -368,29 +372,65 @@ jobs:
       - name: Install kustomize
         uses: imranismail/setup-kustomize@v2
 
+      - name: Determine image tag for frontend
+        id: frontend_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
       - 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 }}
+          kustomize edit set image ghcr.io/cartsnitch/cartsnitch:${{ steps.frontend_tag.outputs.tag }}
+
+      - name: Determine image tag for auth
+        id: auth_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-auth.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-auth.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
 
       - 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 }}
+          kustomize edit set image ghcr.io/cartsnitch/auth:${{ steps.auth_tag.outputs.tag }}
+
+      - name: Determine image tag for receiptwitness
+        id: receiptwitness_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-receiptwitness.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-receiptwitness.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
 
       - 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 }}
+          kustomize edit set image ghcr.io/cartsnitch/receiptwitness:${{ steps.receiptwitness_tag.outputs.tag }}
+
+      - name: Determine image tag for api
+        id: api_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-api.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-api.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
 
       - 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 }}
+          kustomize edit set image ghcr.io/cartsnitch/api:${{ steps.api_tag.outputs.tag }}
 
       - name: Commit and push to infra
         run: |
@@ -399,4 +439,103 @@ jobs:
           git config user.email "cartsnitch-ci[bot]@users.noreply.github.com"
           git add apps/overlays/dev/kustomization.yaml
           git commit -m "ci(dev): update cartsnitch, auth, receiptwitness, and api images"
+          git pull --rebase origin main
+          git push origin main
+
+  deploy-uat:
+    runs-on: runners-cartsnitch
+    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/uat' || github.ref == 'refs/heads/main')
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        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
+        with:
+          repository: cartsnitch/infra
+          token: ${{ steps.app-token.outputs.token }}
+          ref: main
+          path: infra
+
+      - name: Install kubectl
+        uses: azure/setup-kubectl@v4
+
+      - name: Install kustomize
+        uses: imranismail/setup-kustomize@v2
+
+      - name: Determine image tag for frontend
+        id: frontend_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update frontend image tag
+        if: needs.build-and-push.result == 'success'
+        run: |
+          cd infra/apps/overlays/uat
+          kustomize edit set image ghcr.io/cartsnitch/cartsnitch:${{ steps.frontend_tag.outputs.tag }}
+
+      - name: Determine image tag for auth
+        id: auth_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-auth.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-auth.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update auth image tag
+        if: needs.build-and-push-auth.result == 'success'
+        run: |
+          cd infra/apps/overlays/uat
+          kustomize edit set image ghcr.io/cartsnitch/auth:${{ steps.auth_tag.outputs.tag }}
+
+      - name: Determine image tag for receiptwitness
+        id: receiptwitness_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-receiptwitness.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-receiptwitness.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update receiptwitness image tag
+        if: needs.build-and-push-receiptwitness.result == 'success'
+        run: |
+          cd infra/apps/overlays/uat
+          kustomize edit set image ghcr.io/cartsnitch/receiptwitness:${{ steps.receiptwitness_tag.outputs.tag }}
+
+      - name: Determine image tag for api
+        id: api_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-api.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-api.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update api image tag
+        if: needs.build-and-push-api.result == 'success'
+        run: |
+          cd infra/apps/overlays/uat
+          kustomize edit set image ghcr.io/cartsnitch/api:${{ steps.api_tag.outputs.tag }}
+
+      - name: Commit and push to infra
+        run: |
+          cd infra
+          git config user.name "cartsnitch-ci[bot]"
+          git config user.email "cartsnitch-ci[bot]@users.noreply.github.com"
+          git add apps/overlays/uat/kustomization.yaml
+          git commit -m "ci(uat): update cartsnitch, auth, receiptwitness, and api images"
+          git pull --rebase origin main
           git push origin main

api/.github/workflows/ci.yml

@@ -0,0 +1,164 @@
+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,5 +1,3 @@
-# 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 \
@@ -8,11 +6,10 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
-COPY api/pyproject.toml ./
-COPY api/src/ ./src/
+COPY pyproject.toml ./
+COPY 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/*
@@ -20,9 +17,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends libpq5 && rm -r
 WORKDIR /app
 RUN adduser --system --group --uid 1000 app
 COPY --from=build /install /usr/local
-COPY api/src/ ./src/
-COPY api/alembic.ini ./
-COPY api/alembic/ ./alembic/
+COPY src/ ./src/
+COPY alembic.ini ./
+COPY alembic/ ./alembic/
 
 USER 1000
 EXPOSE 8000
@@ -30,4 +27,4 @@ EXPOSE 8000
 HEALTHCHECK --interval=30s --timeout=3s \
     CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
 
-CMD ["sh", "-c", "python -m alembic upgrade head && 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/env.py

@@ -6,7 +6,7 @@ from logging.config import fileConfig
 from sqlalchemy import engine_from_config, pool
 
 from alembic import context
-from cartsnitch_api.models import Base  # noqa: F401 — imports all models for autogenerate
+from cartsnitch_api.models.base import Base  # noqa: F401 — imports all models for autogenerate
 
 config = context.config
 if config.config_file_name is not None:
@@ -18,7 +18,7 @@ if not db_url:
         "CARTSNITCH_DATABASE_URL_SYNC must be set. "
         "Example: postgresql://user:pass@localhost:5432/cartsnitch"
     )
-config.set_main_option("sqlalchemy.url", db_url)
+config.set_main_option("sqlalchemy.url", db_url.replace("%", "%%"))
 
 target_metadata = Base.metadata
 
@@ -31,6 +31,7 @@ def run_migrations_offline() -> None:
         target_metadata=target_metadata,
         literal_binds=True,
         dialect_opts={"paramstyle": "named"},
+        version_table_column_width=128,
     )
     with context.begin_transaction():
         context.run_migrations()
@@ -44,9 +45,19 @@ def run_migrations_online() -> None:
         poolclass=pool.NullPool,
     )
     with connectable.connect() as connection:
-        context.configure(connection=connection, target_metadata=target_metadata)
+        context.configure(connection=connection, target_metadata=target_metadata, version_table_column_width=128)
         with context.begin_transaction():
             context.run_migrations()
+        # Create any tables defined in models but not yet created by migrations.
+        # This bootstraps fresh databases that have no legacy schema.
+        # checkfirst=True ensures this is a no-op on existing databases.
+        try:
+            Base.metadata.create_all(bind=connection, checkfirst=True)
+        except Exception as exc:
+            import logging
+            logging.getLogger("alembic.env").warning(
+                "create_all failed (non-fatal, migrations should handle table creation): %s", exc
+            )
 
 
 if context.is_offline_mode():

api/alembic/versions/001_encrypt_session_data.py

@@ -33,6 +33,21 @@ def _is_fernet_token(value: str) -> bool:
 
 
 def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    # Fresh DB — table created by Base.metadata.create_all with correct TEXT type
+    if not inspector.has_table("user_store_accounts"):
+        return
+
+    # Already migrated? Skip if session_data is already TEXT (not JSON)
+    cols = {c["name"]: c for c in inspector.get_columns("user_store_accounts")}
+    if "session_data" not in cols:
+        return
+    col_type = str(cols["session_data"]["type"]).lower()
+    if "text" in col_type and "json" not in col_type:
+        return  # already TEXT — nothing to do
+
     # Change column type from JSON to TEXT to hold Fernet ciphertext
     op.alter_column(
         "user_store_accounts",
@@ -43,7 +58,6 @@ def upgrade() -> None:
         postgresql_using="session_data::text",
     )
 
-    conn = op.get_bind()
     rows = conn.execute(
         text("SELECT id, session_data FROM user_store_accounts WHERE session_data IS NOT NULL")
     ).fetchall()

api/alembic/versions/002_better_auth_tables.py

@@ -21,81 +21,94 @@ depends_on = None
 
 
 def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
     # --- 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))
+    # Guard: on a fresh DB Base.metadata.create_all (called in env.py after migrations)
+    # creates the users table with all columns, so migration 002 must not re-run add_column.
+    if inspector.has_table("users"):
+        existing_user_cols = [c["name"] for c in inspector.get_columns("users")]
+        if "email_verified" not in existing_user_cols:
+            op.add_column("users", sa.Column("email_verified", sa.Boolean(), nullable=False, server_default="false"))
+        if "image" not in existing_user_cols:
+            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"])
+    if not inspector.has_table("sessions"):
+        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"])
+    if not inspector.has_table("accounts"):
+        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"),
-    )
+    if not inspector.has_table("verifications"):
+        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()
+    # Only run on existing (non-fresh) DBs that already have users table with data
+    if inspector.has_table("users"):
+        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},
-        )
+        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")
+    op.execute(text("DROP INDEX IF EXISTS ix_accounts_user_id"))
+    op.execute(text("DROP TABLE IF EXISTS verifications"))
+    op.execute(text("DROP TABLE IF EXISTS accounts"))
+    op.execute(text("DROP INDEX IF EXISTS ix_sessions_user_id"))
+    op.execute(text("DROP INDEX IF EXISTS ix_sessions_token"))
+    op.execute(text("DROP TABLE IF EXISTS sessions"))
+    op.execute(text("ALTER TABLE users DROP COLUMN IF EXISTS image"))
+    op.execute(text("ALTER TABLE users DROP COLUMN IF EXISTS email_verified"))

api/alembic/versions/003_make_users_hashed_password_nullable.py

@@ -19,8 +19,25 @@ depends_on = None
 
 
 def upgrade() -> None:
-    op.alter_column("users", "hashed_password", existing_type=sa.String(255), nullable=True)
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    # Fresh DB — nothing to alter
+    if not inspector.has_table("users"):
+        return
+
+    cols = {c["name"]: c for c in inspector.get_columns("users")}
+    if "hashed_password" in cols and not cols["hashed_password"]["nullable"]:
+        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)
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    if not inspector.has_table("users"):
+        return
+
+    cols = {c["name"]: c for c in inspector.get_columns("users")}
+    if "hashed_password" in cols and cols["hashed_password"]["nullable"]:
+        op.alter_column("users", "hashed_password", existing_type=sa.String(255), nullable=False)

api/alembic/versions/004_fix_user_id_text.py

@@ -25,7 +25,21 @@ depends_on = None
 
 
 def upgrade() -> None:
-    # Step 1: Drop existing FK constraints
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    # Fresh DB — no tables yet, nothing to convert
+    if not inspector.has_table("users"):
+        return
+
+    # Check if already TEXT (Base.metadata.create_all uses TEXT for fresh DB)
+    users_cols = {c["name"]: c for c in inspector.get_columns("users")}
+    if "id" in users_cols:
+        id_type = str(users_cols["id"]["type"]).lower()
+        if "text" in id_type and "uuid" not in id_type:
+            return  # already TEXT — nothing to do
+
+    # Step 1: Drop existing FK constraints (ignore if they don't exist)
     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"))
 

api/alembic/versions/005_add_email_inbound_token.py

@@ -0,0 +1,57 @@
+"""Add email_inbound_token to users.
+
+Revision ID: 005_add_email_inbound_token
+Revises: 004_fix_user_id_text
+Create Date: 2026-04-02
+"""
+
+import secrets
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "005_add_email_inbound_token"
+down_revision = "004_fix_user_id_text"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    # Guard: on a fresh DB Base.metadata.create_all creates users table with the column already present
+    if not inspector.has_table("users"):
+        return
+    existing_cols = [c["name"] for c in inspector.get_columns("users")]
+    if "email_inbound_token" in existing_cols:
+        return
+
+    # Add column nullable first so existing rows can be backfilled
+    op.add_column(
+        "users",
+        sa.Column("email_inbound_token", sa.String(22), nullable=True),
+    )
+
+    # Backfill existing users with unique tokens
+    result = conn.execute(sa.text("SELECT id FROM users WHERE email_inbound_token IS NULL"))
+    for (user_id,) in result:
+        token = secrets.token_urlsafe(16)
+        conn.execute(
+            sa.text("UPDATE users SET email_inbound_token = :token WHERE id = :id"),
+            {"token": token, "id": user_id},
+        )
+
+    # Now enforce non-null and unique
+    op.alter_column("users", "email_inbound_token", nullable=False)
+    op.create_index(
+        "ix_users_email_inbound_token",
+        "users",
+        ["email_inbound_token"],
+        unique=True,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_users_email_inbound_token", table_name="users")
+    op.drop_column("users", "email_inbound_token")

api/alembic/versions/006_email_inbound_token_server_default.py

@@ -0,0 +1,42 @@
+"""Add server_default to users.email_inbound_token.
+
+Revision ID: 006_email_inbound_token_server_default
+Revises: 005_add_email_inbound_token
+Create Date: 2026-04-04
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "006_email_inbound_token_server_default"
+down_revision = "005_add_email_inbound_token"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    # Guard: on a fresh DB Base.metadata.create_all already sets the server_default
+    if not inspector.has_table("users"):
+        return
+    cols = {c["name"]: c for c in inspector.get_columns("users")}
+    if "email_inbound_token" not in cols:
+        return
+    if cols["email_inbound_token"].get("default") is not None:
+        return
+    op.alter_column(
+        "users",
+        "email_inbound_token",
+        server_default=sa.text(
+            "replace(replace(trim(trailing '=' from encode(gen_random_bytes(16), 'base64')), '+', '-'), '/', '_')"
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.alter_column(
+        "users",
+        "email_inbound_token",
+        server_default=None,
+    )

api/alembic/versions/007_bootstrap_users_table.py

@@ -0,0 +1,47 @@
+"""Bootstrap users table on fresh databases.
+
+On fresh databases, migrations 001-006 skip users-table operations because
+the table does not exist yet. Base.metadata.create_all() in env.py is meant
+to handle this, but if it fails (import errors, etc.) the table is never
+created. This migration creates the users table with raw SQL as a safety net.
+
+Revision ID: 007_bootstrap_users_table
+Revises: 006_email_inbound_token_server_default
+Create Date: 2026-04-04
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import text
+
+from alembic import op
+
+revision = "007_bootstrap_users_table"
+down_revision = "006_email_inbound_token_server_default"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    if inspector.has_table("users"):
+        return  # Table already exists (non-fresh DB or create_all already ran)
+
+    conn.execute(text("""
+        CREATE TABLE users (
+            id TEXT PRIMARY KEY,
+            email VARCHAR(255) NOT NULL UNIQUE,
+            hashed_password VARCHAR(255),
+            display_name VARCHAR(100),
+            email_verified BOOLEAN NOT NULL DEFAULT false,
+            image TEXT,
+            email_inbound_token VARCHAR(22) NOT NULL UNIQUE
+                DEFAULT replace(replace(trim(trailing '=' from encode(gen_random_bytes(16), 'base64')), '+', '-'), '/', '_'),
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        )
+    """))
+
+
+def downgrade() -> None:
+    op.execute(text("DROP TABLE IF EXISTS users"))

api/src/cartsnitch_api/auth/dependencies.py

@@ -5,7 +5,6 @@ Sessions are verified by querying the shared sessions table directly.
 """
 
 from datetime import UTC, datetime
-
 from fastapi import Cookie, Depends, Header, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from sqlalchemy import text
@@ -18,27 +17,18 @@ from cartsnitch_api.database import get_db
 # but we support Bearer tokens for service-to-service or mobile clients.
 bearer_scheme = HTTPBearer(auto_error=False)
 
-# Better-Auth session cookie names.
-# Over HTTPS Better-Auth adds the __Secure- prefix automatically.
-SESSION_COOKIE_NAMES = [
-    "__Secure-better-auth.session_token",  # HTTPS (deployed)
-    "better-auth.session_token",            # HTTP (local dev)
-]
+# Better-Auth session cookie name
+SESSION_COOKIE_NAME = "better-auth.session_token"
 
 
 async def _validate_session_token(token: str, db: AsyncSession) -> str:
     """Validate a Better-Auth session token against the sessions table.
 
     Returns the user_id (as str) if the session is valid and not expired.
-    Better-Auth v1.5.6 stores raw tokens in the DB. The session cookie
-    is signed: ``rawToken.base64HMACSignature``. Strip the signature
-    before querying.
     """
-    # Signed cookie format: rawToken.hmacSignature — split and use only the token part
-    raw_token = token.split(".")[0] if "." in token else token
     result = await db.execute(
         text("SELECT user_id, expires_at FROM sessions WHERE token = :token"),
-        {"token": raw_token},
+        {"token": token},
     )
     row = result.first()
 
@@ -75,12 +65,8 @@ async def get_current_user(
     """
     token: str | None = None
 
-    # 1. Check session cookie (try both names for HTTP/HTTPS compatibility)
-    cookie_token = None
-    for name in SESSION_COOKIE_NAMES:
-        cookie_token = request.cookies.get(name)
-        if cookie_token:
-            break
+    # 1. Check session cookie
+    cookie_token = request.cookies.get(SESSION_COOKIE_NAME)
     if cookie_token:
         token = cookie_token
 

api/src/cartsnitch_api/auth/jwt.py

@@ -2,21 +2,22 @@
 
 from datetime import UTC, datetime, timedelta
 from typing import Any, cast
+from uuid import UUID
 
 from jose import JWTError, jwt
 
 from cartsnitch_api.config import settings
 
 
-def create_access_token(user_id: str) -> str:
+def create_access_token(user_id: UUID) -> str:
     expire = datetime.now(UTC) + timedelta(minutes=settings.jwt_access_token_expire_minutes)
-    payload = {"sub": user_id, "exp": expire, "type": "access"}
+    payload = {"sub": str(user_id), "exp": expire, "type": "access"}
     return cast(str, jwt.encode(payload, settings.jwt_secret_key, algorithm=settings.jwt_algorithm))
 
 
-def create_refresh_token(user_id: str) -> str:
+def create_refresh_token(user_id: UUID) -> str:
     expire = datetime.now(UTC) + timedelta(days=settings.jwt_refresh_token_expire_days)
-    payload = {"sub": user_id, "exp": expire, "type": "refresh"}
+    payload = {"sub": str(user_id), "exp": expire, "type": "refresh"}
     return cast(str, jwt.encode(payload, settings.jwt_secret_key, algorithm=settings.jwt_algorithm))
 
 

api/src/cartsnitch_api/auth/routes.py

@@ -6,10 +6,13 @@ endpoints that query our own user data from the shared database.
 """
 
 from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel
+from sqlalchemy import select
 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.models import User
 from cartsnitch_api.schemas import (
     UpdateUserRequest,
     UserResponse,

api/src/cartsnitch_api/main.py

@@ -18,6 +18,7 @@ from cartsnitch_api.routes.purchases import router as purchases_router
 from cartsnitch_api.routes.scraping import router as scraping_router
 from cartsnitch_api.routes.shopping import router as shopping_router
 from cartsnitch_api.routes.stores import router as stores_router
+from cartsnitch_api.routes.user import router as user_router
 
 
 @asynccontextmanager
@@ -49,6 +50,7 @@ def create_app() -> FastAPI:
 
     # Data endpoints mounted under /api/v1
     v1_router = APIRouter(prefix="/api/v1")
+    v1_router.include_router(user_router)
     v1_router.include_router(stores_router)
     v1_router.include_router(purchases_router)
     v1_router.include_router(products_router)

api/src/cartsnitch_api/models/coupon.py

@@ -9,14 +9,14 @@ from sqlalchemy import Boolean, Date, DateTime, ForeignKey, Numeric, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_api.constants import DiscountType
-from cartsnitch_api.models.base import Base, UUIDPrimaryKeyMixin
+from cartsnitch_api.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
     from cartsnitch_api.models.product import NormalizedProduct
     from cartsnitch_api.models.store import Store
 
 
-class Coupon(UUIDPrimaryKeyMixin, Base):
+class Coupon(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     """A coupon or deal for a product at a store."""
 
     __tablename__ = "coupons"

api/src/cartsnitch_api/models/price.py

@@ -9,7 +9,7 @@ from sqlalchemy import Date, ForeignKey, Index, Numeric, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_api.constants import PriceSource
-from cartsnitch_api.models.base import Base, UUIDPrimaryKeyMixin
+from cartsnitch_api.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
     from cartsnitch_api.models.product import NormalizedProduct
@@ -17,7 +17,7 @@ if TYPE_CHECKING:
     from cartsnitch_api.models.store import Store
 
 
-class PriceHistory(UUIDPrimaryKeyMixin, Base):
+class PriceHistory(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     """A single price observation for a product at a store on a date."""
 
     __tablename__ = "price_history"

api/src/cartsnitch_api/models/purchase.py

@@ -18,7 +18,7 @@ from sqlalchemy import (
 )
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
-from cartsnitch_api.models.base import Base, UUIDPrimaryKeyMixin
+from cartsnitch_api.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
     from cartsnitch_api.models.price import PriceHistory
@@ -27,13 +27,13 @@ if TYPE_CHECKING:
     from cartsnitch_api.models.user import User
 
 
-class Purchase(UUIDPrimaryKeyMixin, Base):
+class Purchase(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     """A single shopping trip / receipt."""
 
     __tablename__ = "purchases"
 
     user_id: Mapped[str] = mapped_column(ForeignKey("users.id"), nullable=False)
-    store_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("stores.id"), nullable=False)
+    store_id: Mapped[str] = 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)
     purchase_date: Mapped[date] = mapped_column(Date, nullable=False)
@@ -61,7 +61,7 @@ class Purchase(UUIDPrimaryKeyMixin, Base):
     )
 
 
-class PurchaseItem(UUIDPrimaryKeyMixin, Base):
+class PurchaseItem(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     """Individual line item on a receipt."""
 
     __tablename__ = "purchase_items"

api/src/cartsnitch_api/models/shrinkflation.py

@@ -9,13 +9,13 @@ from sqlalchemy import Date, ForeignKey, Numeric, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_api.constants import SizeUnit
-from cartsnitch_api.models.base import Base, UUIDPrimaryKeyMixin
+from cartsnitch_api.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
     from cartsnitch_api.models.product import NormalizedProduct
 
 
-class ShrinkflationEvent(UUIDPrimaryKeyMixin, Base):
+class ShrinkflationEvent(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     """Detected shrinkflation event — product size changed while price held or rose."""
 
     __tablename__ = "shrinkflation_events"

api/src/cartsnitch_api/models/user.py

@@ -1,10 +1,11 @@
 """User and UserStoreAccount models."""
 
-import uuid
+import secrets
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import DateTime, ForeignKey, String, Text, UniqueConstraint
+import sqlalchemy as sa
+from sqlalchemy import Boolean, DateTime, ForeignKey, String, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_api.constants import AccountStatus
@@ -23,8 +24,21 @@ class User(TimestampMixin, Base):
 
     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)
+    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)
+    email_inbound_token: Mapped[str] = mapped_column(
+        String(22),
+        nullable=False,
+        unique=True,
+        default=lambda: secrets.token_urlsafe(16),
+        server_default=sa.text(
+            "replace(replace(trim(trailing '=' from encode(gen_random_bytes(16), 'base64')), '+', '-'), '/', '_')"
+        ),
+    )
 
     # Relationships
     store_accounts: Mapped[list["UserStoreAccount"]] = relationship(back_populates="user")
@@ -38,7 +52,7 @@ class UserStoreAccount(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     __table_args__ = (UniqueConstraint("user_id", "store_id", name="uq_user_store_account"),)
 
     user_id: Mapped[str] = mapped_column(ForeignKey("users.id"), nullable=False)
-    store_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("stores.id"), nullable=False)
+    store_id: Mapped[str] = 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))
     last_sync_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))

api/src/cartsnitch_api/routes/alerts.py

@@ -1,5 +1,7 @@
 """Alert routes: list alerts, manage settings."""
 
+from uuid import UUID
+
 from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -13,7 +15,7 @@ router = APIRouter(prefix="/alerts", tags=["alerts"])
 
 @router.get("", response_model=list[AlertResponse])
 async def list_alerts(
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = AlertService(db)
@@ -22,7 +24,7 @@ async def list_alerts(
 
 @router.get("/settings", response_model=AlertSettingsResponse)
 async def get_alert_settings(
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = AlertService(db)
@@ -32,7 +34,7 @@ async def get_alert_settings(
 @router.put("/settings")
 async def update_alert_settings(
     body: AlertSettingsRequest,
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     raise HTTPException(

api/src/cartsnitch_api/routes/coupons.py

@@ -16,7 +16,7 @@ router = APIRouter(prefix="/coupons", tags=["coupons"])
 @router.get("", response_model=list[CouponResponse])
 async def list_coupons(
     store_id: UUID | None = Query(None),
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = CouponService(db)
@@ -25,7 +25,7 @@ async def list_coupons(
 
 @router.get("/relevant", response_model=list[CouponResponse])
 async def relevant_coupons(
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = CouponService(db)

api/src/cartsnitch_api/routes/prices.py

@@ -20,7 +20,7 @@ router = APIRouter(prefix="/prices", tags=["prices"])
 
 @router.get("/trends", response_model=list[PriceTrendResponse])
 async def price_trends(
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     category: str | None = Query(None),
     db: AsyncSession = Depends(get_db),
 ):
@@ -30,7 +30,7 @@ async def price_trends(
 
 @router.get("/increases", response_model=list[PriceIncreaseResponse])
 async def price_increases(
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = PriceService(db)
@@ -40,7 +40,7 @@ async def price_increases(
 @router.get("/comparison", response_model=list[PriceComparisonResponse])
 async def price_comparison(
     product_ids: Annotated[list[UUID], Query()],
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = PriceService(db)

api/src/cartsnitch_api/routes/products.py

@@ -15,7 +15,7 @@ router = APIRouter(prefix="/products", tags=["products"])
 
 @router.get("", response_model=list[ProductResponse])
 async def list_products(
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     q: str | None = Query(None),
     category: str | None = Query(None),
     page: int = Query(1, ge=1),
@@ -29,7 +29,7 @@ async def list_products(
 @router.get("/{product_id}", response_model=ProductDetailResponse)
 async def get_product(
     product_id: UUID,
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = ProductService(db)
@@ -44,7 +44,7 @@ async def get_product(
 @router.get("/{product_id}/prices", response_model=PriceTrendResponse)
 async def get_product_prices(
     product_id: UUID,
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = ProductService(db)

api/src/cartsnitch_api/routes/purchases.py

@@ -15,7 +15,7 @@ router = APIRouter(prefix="/purchases", tags=["purchases"])
 
 @router.get("", response_model=list[PurchaseResponse])
 async def list_purchases(
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     store_id: UUID | None = Query(None),
     page: int = Query(1, ge=1),
     page_size: int = Query(20, ge=1, le=100),
@@ -27,7 +27,7 @@ async def list_purchases(
 
 @router.get("/stats", response_model=PurchaseStatsResponse)
 async def purchase_stats(
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = PurchaseService(db)
@@ -37,7 +37,7 @@ async def purchase_stats(
 @router.get("/{purchase_id}", response_model=PurchaseDetailResponse)
 async def get_purchase(
     purchase_id: UUID,
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = PurchaseService(db)

api/src/cartsnitch_api/routes/scraping.py

@@ -1,5 +1,7 @@
 """Scraping routes: trigger sync, check status (proxy to ReceiptWitness)."""
 
+from uuid import UUID
+
 from fastapi import APIRouter, Depends, HTTPException, status
 from httpx import HTTPStatusError, RequestError
 
@@ -11,7 +13,7 @@ router = APIRouter(prefix="/scraping", tags=["scraping"])
 
 
 @router.post("/{store_slug}/sync", response_model=SyncTriggerResponse)
-async def trigger_sync(store_slug: str, user_id: str = Depends(get_current_user)):
+async def trigger_sync(store_slug: str, user_id: UUID = Depends(get_current_user)):
     client = ReceiptWitnessClient()
     try:
         result = await client.trigger_sync(str(user_id), store_slug)
@@ -29,7 +31,7 @@ async def trigger_sync(store_slug: str, user_id: str = Depends(get_current_user)
 
 
 @router.get("/status", response_model=list[SyncStatusResponse])
-async def sync_status(user_id: str = Depends(get_current_user)):
+async def sync_status(user_id: UUID = Depends(get_current_user)):
     client = ReceiptWitnessClient()
     try:
         return await client.get_sync_status(str(user_id))

api/src/cartsnitch_api/routes/shopping.py

@@ -1,5 +1,7 @@
 """Shopping routes: optimize list, saved lists."""
 
+from uuid import UUID
+
 from fastapi import APIRouter, Depends, HTTPException, status
 from httpx import HTTPStatusError, RequestError
 
@@ -11,7 +13,7 @@ router = APIRouter(prefix="/shopping", tags=["shopping"])
 
 
 @router.post("/optimize", response_model=OptimizeResponse)
-async def optimize_shopping(body: OptimizeRequest, user_id: str = Depends(get_current_user)):
+async def optimize_shopping(body: OptimizeRequest, user_id: UUID = Depends(get_current_user)):
     client = ClipArtistClient()
     try:
         result = await client.optimize(
@@ -35,7 +37,7 @@ async def optimize_shopping(body: OptimizeRequest, user_id: str = Depends(get_cu
 
 
 @router.get("/lists", response_model=list[ShoppingListResponse])
-async def list_shopping_lists(user_id: str = Depends(get_current_user)):
+async def list_shopping_lists(user_id: UUID = Depends(get_current_user)):
     client = ClipArtistClient()
     try:
         return await client.get_shopping_lists(str(user_id))

api/src/cartsnitch_api/routes/stores.py

@@ -1,5 +1,7 @@
 """Store routes: list stores, manage user store connections."""
 
+from uuid import UUID
+
 from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -19,7 +21,7 @@ async def list_stores(db: AsyncSession = Depends(get_db)):
 
 @router.get("/me/stores", response_model=list[StoreAccountResponse])
 async def list_user_stores(
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = StoreService(db)
@@ -34,7 +36,7 @@ async def list_user_stores(
 async def connect_store(
     store_slug: str,
     body: ConnectStoreRequest,
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = StoreService(db)
@@ -49,7 +51,7 @@ async def connect_store(
 @router.delete("/me/stores/{store_slug}", status_code=status.HTTP_204_NO_CONTENT)
 async def disconnect_store(
     store_slug: str,
-    user_id: str = Depends(get_current_user),
+    user_id: UUID = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = StoreService(db)

api/src/cartsnitch_api/routes/user.py

@@ -0,0 +1,32 @@
+"""User routes: per-user account endpoints (email-in address, etc.)."""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+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 EmailInAddressResponse
+from cartsnitch_api.services.auth import AuthService
+
+router = APIRouter(tags=["user"])
+
+
+@router.get("/me/email-in-address", response_model=EmailInAddressResponse)
+async def get_email_in_address(
+    user_id: str = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    svc = AuthService(db)
+    try:
+        email_address = await svc.get_email_in_address(user_id)
+        return EmailInAddressResponse(
+            email_address=email_address,
+            instructions=(
+                "Forward your digital receipt emails to this address. "
+                "We currently support Meijer, Kroger, and Target receipt emails."
+            ),
+        )
+    except LookupError:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
+        ) from None

api/src/cartsnitch_api/schemas.py

@@ -1,6 +1,6 @@
 """Pydantic v2 request/response schemas for all API endpoints."""
 
-from datetime import date, datetime
+from datetime import datetime
 from uuid import UUID
 
 from pydantic import BaseModel, EmailStr, Field
@@ -22,6 +22,11 @@ class UserResponse(BaseModel):
     created_at: datetime
 
 
+class EmailInAddressResponse(BaseModel):
+    email_address: str
+    instructions: str
+
+
 # ---------- Stores ----------
 
 
@@ -60,7 +65,7 @@ class PurchaseResponse(BaseModel):
     id: UUID
     store_id: UUID
     store_name: str
-    purchased_at: date
+    purchased_at: datetime
     total: float
     item_count: int
 
@@ -142,7 +147,7 @@ class CouponResponse(BaseModel):
     discount_value: float
     discount_type: str
     product_id: UUID | None = None
-    expires_at: date | None = None
+    expires_at: datetime | None = None
 
 
 # ---------- Shopping ----------

api/src/cartsnitch_api/services/alerts.py

@@ -4,6 +4,8 @@ Alerts are generated by StickerShock and ShrinkRay services and written to the D
 This service reads them for the API gateway.
 """
 
+from uuid import UUID
+
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
@@ -13,7 +15,7 @@ class AlertService:
     def __init__(self, db: AsyncSession) -> None:
         self.db = db
 
-    async def list_alerts(self, user_id: str) -> list[dict]:
+    async def list_alerts(self, user_id: UUID) -> list[dict]:
         """List shrinkflation events for products the user has purchased."""
         from cartsnitch_api.models import Purchase, PurchaseItem, ShrinkflationEvent
 
@@ -55,7 +57,7 @@ class AlertService:
             for e in events
         ]
 
-    async def get_settings(self, user_id: str) -> dict:
+    async def get_settings(self, user_id: UUID) -> dict:
         # Alert settings would be stored in a user_settings table.
         # For now, return defaults since the table doesn't exist yet in common lib.
         return {
@@ -64,7 +66,7 @@ class AlertService:
             "email_notifications": False,
         }
 
-    async def update_settings(self, user_id: str, **fields) -> dict:
+    async def update_settings(self, user_id: UUID, **fields) -> dict:
         # Would update user_settings table. Return merged defaults for now.
         current = await self.get_settings(user_id)
         for k, v in fields.items():

api/src/cartsnitch_api/services/auth.py

@@ -66,3 +66,14 @@ class AuthService:
 
         await self.db.delete(user)
         await self.db.commit()
+
+    async def get_email_in_address(self, user_id: str) -> str:
+        """Return the per-user email-in address for receipt forwarding."""
+        from cartsnitch_api.models import User
+
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+        if not user:
+            raise LookupError("User not found")
+
+        return f"receipts+{user.email_inbound_token}@receipts.cartsnitch.com"

api/src/cartsnitch_api/services/coupons.py

@@ -29,7 +29,7 @@ class CouponService:
         coupons = result.scalars().all()
         return [self._to_dict(c) for c in coupons]
 
-    async def relevant_coupons(self, user_id: str) -> list[dict]:
+    async def relevant_coupons(self, user_id: UUID) -> list[dict]:
         """Coupons for products the user has purchased."""
         from cartsnitch_api.models import Coupon, PurchaseItem
 

api/src/cartsnitch_api/services/purchases.py

@@ -13,7 +13,7 @@ class PurchaseService:
 
     async def list_purchases(
         self,
-        user_id: str,
+        user_id: UUID,
         store_id: UUID | None = None,
         page: int = 1,
         page_size: int = 20,
@@ -56,7 +56,7 @@ class PurchaseService:
             for p, item_count, store_name in result.all()
         ]
 
-    async def get_purchase(self, purchase_id: UUID, user_id: str) -> dict:
+    async def get_purchase(self, purchase_id: UUID, user_id: UUID) -> dict:
         from cartsnitch_api.models import Purchase
 
         result = await self.db.execute(
@@ -88,7 +88,7 @@ class PurchaseService:
             ],
         }
 
-    async def get_stats(self, user_id: str) -> dict:
+    async def get_stats(self, user_id: UUID) -> dict:
         from cartsnitch_api.models import Purchase
 
         result = await self.db.execute(

api/src/cartsnitch_api/services/stores.py

@@ -1,6 +1,7 @@
 """Store service — list stores, manage user store account connections."""
 
 import json
+from uuid import UUID
 
 from cryptography.fernet import Fernet
 from sqlalchemy import select
@@ -34,7 +35,7 @@ class StoreService:
             for s in stores
         ]
 
-    async def list_user_stores(self, user_id: str) -> list[dict]:
+    async def list_user_stores(self, user_id: UUID) -> list[dict]:
         from cartsnitch_api.models import UserStoreAccount
 
         result = await self.db.execute(
@@ -59,7 +60,7 @@ class StoreService:
             for a in accounts
         ]
 
-    async def connect_store(self, user_id: str, store_slug: str, credentials: dict | None) -> dict:
+    async def connect_store(self, user_id: UUID, store_slug: str, credentials: dict | None) -> dict:
         from cartsnitch_api.models import Store, UserStoreAccount
 
         result = await self.db.execute(select(Store).where(Store.slug == store_slug))
@@ -106,7 +107,7 @@ class StoreService:
             "sync_status": "active",
         }
 
-    async def disconnect_store(self, user_id: str, store_slug: str) -> None:
+    async def disconnect_store(self, user_id: UUID, store_slug: str) -> None:
         from cartsnitch_api.models import Store, UserStoreAccount
 
         result = await self.db.execute(select(Store).where(Store.slug == store_slug))

api/tests/test_e2e/test_email_in_address.py

@@ -0,0 +1,61 @@
+"""Tests for GET /api/v1/me/email-in-address endpoint."""
+
+import pytest
+from httpx import AsyncClient
+
+
+@pytest.mark.asyncio
+async def test_get_email_in_address_authenticated(client: AsyncClient, auth_headers: dict):
+    """Authenticated user gets their email-in address."""
+    response = await client.get(
+        "/api/v1/me/email-in-address",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 200
+    data = response.json()
+    assert "email_address" in data
+    assert data["email_address"].startswith("receipts+")
+    assert data["email_address"].endswith("@receipts.cartsnitch.com")
+    assert len(data["email_address"]) > len("receipts+@receipts.cartsnitch.com")
+    assert "instructions" in data
+    assert "Meijer" in data["instructions"]
+    assert "Kroger" in data["instructions"]
+    assert "Target" in data["instructions"]
+
+
+@pytest.mark.asyncio
+async def test_get_email_in_address_unauthenticated(client: AsyncClient):
+    """Unauthenticated request returns 401."""
+    response = await client.get("/api/v1/me/email-in-address")
+    assert response.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_get_email_in_address_invalid_token(client: AsyncClient):
+    """Invalid JWT token returns 401."""
+    response = await client.get(
+        "/api/v1/me/email-in-address",
+        headers={"Authorization": "Bearer invalid-token-xyz"},
+    )
+    assert response.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_email_address_format(client: AsyncClient, auth_headers: dict):
+    """Email address format is receipts+{22-char-urlsafe-token}@receipts.cartsnitch.com."""
+    response = await client.get(
+        "/api/v1/me/email-in-address",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 200
+    data = response.json()
+    email = data["email_address"]
+    # Format: receipts+<22-char-urlsafe-token>@receipts.cartsnitch.com
+    assert email.startswith("receipts+")
+    assert email.endswith("@receipts.cartsnitch.com")
+    # token_urlsafe(16) produces 22 chars
+    middle = email[len("receipts+") : -len("@receipts.cartsnitch.com")]
+    assert len(middle) == 22
+    assert "@" not in middle

api/tests/test_openapi.py

@@ -6,13 +6,14 @@ from httpx import ASGITransport, AsyncClient
 from cartsnitch_api.main import app
 
 EXPECTED_ROUTES = [
-    # Auth (6)
+    # Auth (7)
     ("post", "/auth/register"),
     ("post", "/auth/login"),
     ("post", "/auth/refresh"),
     ("get", "/auth/me"),
     ("patch", "/auth/me"),
     ("delete", "/auth/me"),
+    ("get", "/auth/me/email-in-address"),
     # Stores (4)
     ("get", "/stores"),
     ("get", "/me/stores"),
@@ -89,4 +90,4 @@ async def test_route_count():
                 if method in ("get", "post", "put", "delete", "patch"):
                     count += 1
 
-        assert count == 33, f"Expected 33 routes, found {count}"
+        assert count == 34, f"Expected 34 routes, found {count}"

auth/src/auth.ts

@@ -95,5 +95,6 @@ export const auth = betterAuth({
     "https://cartsnitch.com",
     "https://cartsnitch.farh.net",
     "https://cartsnitch.dev.farh.net",
+    "https://cartsnitch.uat.farh.net",
   ],
 });

common/alembic/env.py

@@ -14,7 +14,7 @@ if config.config_file_name is not None:
 
 db_url = os.environ.get("CARTSNITCH_DATABASE_URL_SYNC")
 if db_url:
-    config.set_main_option("sqlalchemy.url", db_url)
+    config.set_main_option("sqlalchemy.url", db_url.replace("%", "%%"))
 
 target_metadata = Base.metadata
 

common/alembic/versions/001_add_email_inbound_token.py

@@ -0,0 +1,37 @@
+"""Add email_inbound_token to users.
+
+Revision ID: 001_add_email_inbound_token
+Revises:
+Create Date: 2026-04-02
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "001_add_email_inbound_token"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("email_inbound_token", sa.String(22), nullable=True))
+    op.create_unique_constraint("uq_users_email_inbound_token", "users", ["email_inbound_token"])
+
+    # Backfill existing users with generated tokens (PostgreSQL)
+    op.execute(
+        "UPDATE users SET email_inbound_token = "
+        "substring(replace(gen_random_uuid()::text, '-', ''), 1, 22) "
+        "WHERE email_inbound_token IS NULL"
+    )
+
+    # Alter to non-nullable
+    op.alter_column("users", "email_inbound_token", nullable=False)
+
+
+def downgrade() -> None:
+    op.drop_constraint("uq_users_email_inbound_token", "users", type_="unique")
+    op.drop_column("users", "email_inbound_token")

common/src/cartsnitch_common/models/user.py

@@ -1,10 +1,11 @@
 """User and UserStoreAccount models."""
 
+import secrets
 import uuid
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, String, Text, UniqueConstraint
+from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, String, Text, UniqueConstraint, text
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_common.constants import AccountStatus
@@ -21,6 +22,15 @@ class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     __tablename__ = "users"
 
     email: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
+    email_inbound_token: Mapped[str] = mapped_column(
+        String(22),
+        nullable=False,
+        unique=True,
+        default=lambda: secrets.token_urlsafe(16),
+        server_default=text(
+            "replace(replace(trim(trailing '=' from encode(gen_random_bytes(16), 'base64')), '+', '-'), '/', '_')"
+        ),
+    )
     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")

common/src/cartsnitch_common/schemas/user.py

@@ -20,6 +20,7 @@ class UserRead(BaseModel):
     id: uuid.UUID
     email: str
     display_name: str | None
+    email_inbound_token: str
     created_at: datetime
     updated_at: datetime
 

common/tests/test_models.py

@@ -147,6 +147,40 @@ class TestStoreLocationModel:
         assert loc.lat == pytest.approx(42.2808)
 
 
+class TestUserModel:
+    def test_email_inbound_token_auto_populated(self, session):
+        user = User(
+            id=uuid.uuid4(),
+            email="token_test@example.com",
+            hashed_password="hashed",
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+        )
+        session.add(user)
+        session.commit()
+        assert user.email_inbound_token is not None
+        assert len(user.email_inbound_token) == 22
+
+    def test_email_inbound_token_unique(self, session):
+        user1 = User(
+            id=uuid.uuid4(),
+            email="user1@example.com",
+            hashed_password="hashed",
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+        )
+        user2 = User(
+            id=uuid.uuid4(),
+            email="user2@example.com",
+            hashed_password="hashed",
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+        )
+        session.add_all([user1, user2])
+        session.commit()
+        assert user1.email_inbound_token != user2.email_inbound_token
+
+
 class TestUserStoreAccountModel:
     def test_account_status_enum(self, session):
         user = User(

package.json

@@ -50,6 +50,9 @@
   "overrides": {
     "@rollup/pluginutils": "5.3.0",
     "flatted": "^3.4.2",
-    "serialize-javascript": "7.0.5"
+    "serialize-javascript": "7.0.5",
+    "brace-expansion": ">=1.1.13",
+    "lodash": ">=4.17.24",
+    "minimatch": "^10.2.4"
   }
 }

receiptwitness/src/receiptwitness/api/routes.py

@@ -17,7 +17,11 @@ TOKEN_PATTERN = re.compile(r"receipts\+([A-Za-z0-9_-]+)@")
 
 def verify_mailgun_signature(token: str, timestamp: str, signature: str) -> bool:
     """Verify Mailgun webhook signature."""
-    if abs(time.time() - int(timestamp)) > 300:  # 5 min freshness
+    try:
+        ts = int(timestamp)
+    except (ValueError, TypeError):
+        return False
+    if abs(time.time() - ts) > 300:  # 5 min freshness
         return False
     key = settings.mailgun_webhook_signing_key.encode()
     hmac_digest = hmac.new(key, f"{timestamp}{token}".encode(), hashlib.sha256).hexdigest()

receiptwitness/tests/test_api/test_webhook.py

@@ -99,3 +99,27 @@ def test_stale_timestamp(client, mock_redis):
     assert response.status_code == 406
     assert response.json()["detail"] == "Invalid signature"
     mock_redis["enqueue"].assert_not_awaited()
+
+
+def test_invalid_timestamp_returns_406(client, mock_redis):
+    """Empty timestamp should return 406, not 500."""
+    with patch("receiptwitness.api.routes.settings") as mock_settings:
+        mock_settings.mailgun_webhook_signing_key = "test-secret"
+        form = {
+            "token": "test-token",
+            "timestamp": "",
+            "signature": "any-sig",
+            "sender": "sender@example.com",
+            "recipient": "receipts+user123@example.com",
+            "subject": "Receipt",
+        }
+        response = client.post("/inbound/email", data=form)
+    assert response.status_code == 406
+    assert response.json()["detail"] == "Invalid signature"
+    mock_redis["enqueue"].assert_not_awaited()
+
+
+def test_get_inbound_email_returns_405(client):
+    """GET /inbound/email is not allowed."""
+    response = client.get("/inbound/email")
+    assert response.status_code == 405

src/pages/Settings.tsx

@@ -1,3 +1,4 @@
+import { useState, useEffect } from 'react'
 import { Link, useNavigate } from 'react-router-dom'
 import { authClient } from '../lib/auth-client.ts'
 import { useAuthStore } from '../stores/auth.ts'
@@ -9,6 +10,26 @@ export function Settings() {
   const setAuthenticated = useAuthStore((s) => s.setAuthenticated)
   const navigate = useNavigate()
   const { theme, setTheme } = useThemeStore()
+  const [emailInAddress, setEmailInAddress] = useState<string | null>(null)
+  const [copied, setCopied] = useState(false)
+
+  useEffect(() => {
+    if (!session?.user) return
+    fetch('/api/v1/me/email-in-address', {
+      credentials: 'include',
+    })
+      .then((res) => res.json())
+      .then((data) => setEmailInAddress(data.email_address))
+      .catch(() => setEmailInAddress(null))
+  }, [session])
+
+  async function handleCopyEmail() {
+    if (emailInAddress) {
+      await navigator.clipboard.writeText(emailInAddress)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    }
+  }
 
   const user = session?.user
   const connectedStores: string[] = []
@@ -113,6 +134,30 @@ export function Settings() {
           </button>
         </div>
       </section>
+
+      {/* Receipt Email section */}
+      <section className="mt-6">
+        <h2 className="mb-3 text-sm font-semibold text-gray-500">Receipt Email</h2>
+        <div className="rounded-xl bg-white p-4 shadow-sm">
+          <p className="mb-2 text-sm text-gray-600">
+            Forward your digital receipt emails to this address:
+          </p>
+          <div className="flex items-center gap-2">
+            <code className="flex-1 rounded-lg bg-gray-100 px-3 py-2 text-sm font-mono text-gray-800 truncate">
+              {emailInAddress ?? 'Loading...'}
+            </code>
+            <button
+              onClick={handleCopyEmail}
+              className="rounded-lg bg-brand-blue px-3 py-2 text-sm font-medium text-white hover:bg-brand-blue/90 transition-colors"
+            >
+              {copied ? 'Copied!' : 'Copy'}
+            </button>
+          </div>
+          <p className="mt-2 text-xs text-gray-400">
+            Supports Meijer, Kroger, and Target receipt emails.
+          </p>
+        </div>
+      </section>
     </div>
   )
 }