docs: release notes for v3.7.0-beta

feat: post deletion

.air.toml

@@ -0,0 +1,20 @@
+root = "."
+tmp_dir = "tmp/air"
+
+[build]
+  cmd = "go build -tags nofrontend -o ./tmp/air/renewcms ./cmd/server"
+  bin = "tmp/air/renewcms"
+  delay = 500
+  exclude_dir = ["tmp", "tmp/air", "bin", "data", "web", "features", "docs", "internal/infrastructure/assets/dist", ".claude"]
+  exclude_regex = ["_test.go"]
+  include_ext = ["go", "html"]
+  log = "build-errors.log"
+  send_interrupt = true
+  kill_delay = "2s"
+  stop_on_error = true
+
+[log]
+  time = false
+
+[misc]
+  clean_on_exit = true

.dockerignore

@@ -0,0 +1,17 @@
+.git
+.gitignore
+.dockerignore
+.env
+docker.env
+tmp/
+bin/
+data/
+node_modules
+web/node_modules
+internal/infrastructure/assets/dist
+.task/
+.claude/
+.idea
+.vscode
+*.db
+*.exe

.env.example

@@ -0,0 +1,43 @@
+PUBLIC_URL=http://localhost:5173
+JWT_SECRET=change-me-to-a-long-random-string
+SMTP_HOST=mail.service.abc
+SMTP_PORT=465
+SMTP_LOGIN=a@b.c
+SMTP_PASSWORD=12341234
+SMTP_SENDER=a@b.c
+
+ENVIRONMENT=development
+PORT=8080
+DB_FILE=./data/renewcms.db
+UPLOAD_DIR=./data/uploads
+CORS_ALLOWED_ORIGINS=
+AUTH_RATE_LIMIT_MAX_ATTEMPTS=5
+AUTH_RATE_LIMIT_WINDOW_SECONDS=60
+TRUSTED_PROXIES=
+SMTP_ALLOW_INSECURE=false
+UPDATE_FEED_URL=https://git.floriansylvain.fr
+RENEWCMS_CONTAINER=false
+IMAGE_VARIANT_MAX_SOURCE_BYTES=10485760
+IMAGE_VARIANT_MAX_SOURCE_PIXELS=50000000
+IMAGE_VARIANT_MAX_CONCURRENT_RENDERS=4
+DB_DRIVER=sqlite
+DATA_DIR=
+DB_HOST=
+DB_PORT=
+DB_USER=
+DB_PASSWORD=
+DB_NAME=
+DB_TLS=false
+DB_SSLMODE=disable
+DB_MAX_OPEN_CONNS=10
+DB_MAX_IDLE_CONNS=5
+DB_CONN_MAX_LIFETIME_SECONDS=300
+STORAGE_DRIVER=local
+S3_BUCKET=
+S3_REGION=us-east-1
+S3_ENDPOINT=
+S3_ACCESS_KEY_ID=
+S3_SECRET_ACCESS_KEY=
+S3_KEY_PREFIX=
+S3_PATH_STYLE=false
+S3_TLS=true

.gitattributes

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.ico binary
+*.png binary
+*.jpg binary

.gitignore

@@ -1,31 +1,35 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-lerna-debug.log*
-
-node_modules
-.DS_Store
-dist
-dist-ssr
-coverage
-*.local
-
-/cypress/videos/
-/cypress/screenshots/
-
-# Editor directories and files
-.vscode/*
-!.vscode/extensions.json
+# IDE
 .idea
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
+.vscode
 
-mongodbdata
+# DB
+*.db
+/data/
+
+# Build
+bin
+dist/
+
+# Environment
 .env
+docker.env
+
+# Generated files
+tmp/
+.task/
+build-errors.log
+uploadedImages/
+*.exe
+
+# AI fest
+.claude/
+CLAUDE.md
+.codex/
+.agents/
+AGENTS.md
+codex-workflow.md
+CODING_STANDARDS.md
+
+# Generated LLM docs
+internal/infrastructure/llmdocs/generated/*
+!internal/infrastructure/llmdocs/generated/.gitkeep

Dockerfile

@@ -0,0 +1,35 @@
+FROM oven/bun:1-alpine AS web
+WORKDIR /src/web
+COPY web/package.json web/bun.lock ./
+RUN bun install --frozen-lockfile
+COPY web/ ./
+RUN bun run build-only
+WORKDIR /src
+COPY docs/ ./docs/
+COPY scripts/generate-llms.ts ./scripts/generate-llms.ts
+RUN bun scripts/generate-llms.ts
+
+FROM golang:1.27.3-alpine AS server
+ARG VERSION=dev
+ENV CGO_ENABLED=0
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+COPY --from=web /src/internal/infrastructure/assets/dist ./internal/infrastructure/assets/dist
+COPY --from=web /src/internal/infrastructure/llmdocs/generated ./internal/infrastructure/llmdocs/generated
+RUN go build -trimpath -ldflags "-s -w -X main.version=${VERSION}" -o /out/renewcms ./cmd/server
+
+FROM alpine:3.22
+RUN addgroup -S -g 10001 renewcms \
+	&& adduser -S -u 10001 -G renewcms -H -s /sbin/nologin renewcms \
+	&& mkdir /data \
+	&& chown renewcms:renewcms /data
+COPY --from=server /out/renewcms /usr/local/bin/renewcms
+ENV RENEWCMS_CONTAINER=true
+USER renewcms
+WORKDIR /data
+VOLUME /data
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD ["wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ENTRYPOINT ["/usr/local/bin/renewcms"]

Dockerfile.backend

@@ -1,14 +0,0 @@
-FROM golang:1.19
-
-WORKDIR /app
-
-COPY go.mod ./
-COPY go.sum ./
-RUN go mod download
-
-ADD cmd ./cmd/
-ADD internal ./internal/
-COPY .env ./
-RUN go build -o ./GohCMS/ ./...
-
-CMD ["./GohCMS/cmd"]

Dockerfile.frontend

@@ -1,12 +0,0 @@
-FROM node:latest as build-stage
-WORKDIR /app
-COPY ./web/admin-gui/package*.json ./
-COPY ./.env ./
-RUN npm install
-COPY ./web/admin-gui/ .
-RUN npm run build
-
-FROM nginx as production-stage
-RUN mkdir /app
-COPY --from=build-stage /app/dist /app
-COPY ./web/admin-gui/nginx.conf /etc/nginx/nginx.conf

README.md

@@ -1,43 +1,61 @@
-# GohCMS
+# RenewCMS
 
-## 🚧 This project is under development !
+A small self-hosted CMS: a Go API and a Vue 3 admin/front SPA, shipped as **a single executable** backed by a SQLite file.
 
-The features are not complete, not fully tested and subject to many changes.
+> 🚧 **Under development.** Features are incomplete, not fully tested and subject to change.
 
-## Setup
+## Quick start
 
-Don't forget to setup the [Environment variables](#environment-variables)!
+### Run a release binary
 
-### Use with Docker
-
-To **run** the app, run the command
-
-```shell
-docker-compose up
+```sh
+cp .env.example .env    # fill in PUBLIC_URL, JWT_SECRET and SMTP_*
+./renewcms              # → http://localhost:8080
 ```
 
-### Build and run it yourself
+Data is stored in `./data/` by default. For a real server (systemd, HTTPS, backups), see **[docs/deployment.md](docs/deployment.md)**.
 
-TODO
+### Run with Docker
 
-### Environment variables
-
-- ./env:
-
-```
-APP_API_ADDRESS=http://example.com
-APP_FRONT_ADDRESS=http://example.com
-APP_BASE_API_PATH=/example
-APP_BASE_FRONT_PATH=/example
-APP_API_PORT=1234
-APP_FRONT_PORT=1234
-APP_JWT_SECRET=secret
+```sh
+cp docker.env.example docker.env    # fill in PUBLIC_URL, JWT_SECRET and SMTP_*
+docker compose pull
+docker compose up -d                # http://localhost:8080
 ```
 
-## API Usage
+Upgrade with `docker compose pull && docker compose up -d`. The image is `git.floriansylvain.fr/fsylvain/renewcms`. Every release is a pre-release for now, so the default tag is the moving `beta`. Pin a version with `RENEWCMS_IMAGE`. Tags, building from source and publishing are in **[docs/docker.md](docs/docker.md)**.
 
-TODO
+### Updates from the browser
 
-## Demo
+On Linux with systemd, install v2.6.0-beta or newer manually, then follow [the browser-update setup guide](docs/deployment.md#browser-updates). It covers finding the actual database directory, installing the helper, testing a restart and troubleshooting. Other platforms use manual upgrades.
 
-TODO
+### Develop
+
+Requires Go 1.27+, Node.js 22, [Bun](https://bun.sh) and [Task](https://taskfile.dev).
+
+```sh
+cp .env.example .env
+task setup
+task dev                # API with hot reload + Vite HMR → http://localhost:5173
+```
+
+## Documentation
+
+| Doc | Contents |
+|---|---|
+| [docs/development.md](docs/development.md) | Dev setup, how Vite and the API fit together, tests, lint, `task` commands |
+| [docs/deployment.md](docs/deployment.md) | Building release binaries, running as a service, HTTPS, backups, upgrades |
+| [docs/docker.md](docs/docker.md) | Running RenewCMS in Docker: image, Compose, data volume, backups, reverse proxy, tags, upgrades, publishing |
+| [docs/configuration.md](docs/configuration.md) | Every environment variable |
+| [docs/privacy.md](docs/privacy.md) | Personal data stored, retention, cookies, outbound connections and GDPR requests |
+| [docs/architecture.md](docs/architecture.md) | Backend layering and how the SPA is embedded |
+| [docs/performance.md](docs/performance.md) | Measured costs, such as the `?seo=` article filter |
+| [docs/api.md](docs/api.md) | API reference: authentication, API keys, routes and the activity log |
+| [docs/api/articles.md](docs/api/articles.md) | Reading articles: pagination, search, `format` and body schemas |
+| [docs/custom-content-types.md](docs/custom-content-types.md) | Custom content types: layering, phase 1 limitations and their fix path |
+| [docs/image-variants.md](docs/image-variants.md) | Image variants and their cache |
+| [docs/release-notes.md](docs/release-notes.md) | Release notes format, the published releases and how to publish one |
+
+## TODOs
+
+- Cancel button when email validation pending or expired

Taskfile.yml

@@ -0,0 +1,439 @@
+version: '3'
+
+vars:
+  BINARY: renewcms
+  DIST_DIR: internal/infrastructure/assets/dist
+  LLMS_DIR: internal/infrastructure/llmdocs/generated
+  VERSION:
+    sh: git describe --tags --always --dirty
+  LDFLAGS: -s -w -X main.version={{.VERSION}}
+  RELEASE_TARGETS: [windows/amd64, windows/arm64, linux/amd64, linux/arm64, darwin/amd64, darwin/arm64]
+
+env:
+  CGO_ENABLED: '0'
+  __COMPAT_LAYER: RunAsInvoker
+
+tasks:
+  default:
+    cmds:
+      - task --list
+    silent: true
+
+  setup:
+    desc: Install dev tools, Go modules and frontend dependencies
+    cmds:
+      - go install github.com/air-verse/air@latest
+      - go install github.com/go-gremlins/gremlins/cmd/gremlins@latest
+      - go mod download
+      - task: web:install
+
+  dev:
+    desc: Run the API (air, hot reload) and the SPA (Vite, HMR) together → http://localhost:5173
+    deps: [dev:api, dev:web]
+
+  dev:api:
+    desc: Run the API with hot reload on :8080 (SPA not embedded)
+    deps: [build:llms]
+    cmds:
+      - air
+
+  dev:web:
+    desc: Run the Vite dev server on :5173, proxying /v1 to the API
+    dir: web
+    deps: [web:install]
+    cmds:
+      - bun dev
+
+  test:
+    desc: Run the Go tests
+    cmds:
+      - go test -tags nofrontend ./test/... -count=1 {{.CLI_ARGS}}
+
+  test:mysql:
+    desc: Run the MySQL tests against real servers (mysql:8.4 then mariadb:11 in Docker, removed afterwards)
+    cmds:
+      - cmd: |
+          PASSWORD=renewcms-test-root
+          STATUS=0
+          run_engine() {
+            NAME="renewcms-test-$1"
+            IMAGE="$2"
+            docker rm -f "$NAME" >/dev/null 2>&1
+            docker run -d --name "$NAME" -e MYSQL_ROOT_PASSWORD="$PASSWORD" -p 127.0.0.1::3306 "$IMAGE" >/dev/null || return 1
+            MAPPING="$(docker port "$NAME" 3306/tcp)"
+            PORT="${MAPPING##*:}"
+            READY=no
+            TRIES=0
+            while [ "$TRIES" -lt 90 ]; do
+              if docker exec "$NAME" sh -c "\$(command -v mariadb || command -v mysql) -h127.0.0.1 -uroot -p$PASSWORD -e 'SELECT 1'" >/dev/null 2>&1; then
+                READY=yes
+                break
+              fi
+              TRIES=$((TRIES + 1))
+              sleep 2
+            done
+            if [ "$READY" != yes ]; then
+              echo "$IMAGE did not become ready" >&2
+              docker logs "$NAME" 2>&1 | tail -n 20 >&2
+              docker rm -f "$NAME" >/dev/null 2>&1
+              return 1
+            fi
+            echo "== $IMAGE on 127.0.0.1:$PORT"
+            RENEWCMS_TEST_MYSQL_DSN="root:$PASSWORD@tcp(127.0.0.1:$PORT)/mysql" go test -tags nofrontend ./test/... -run MySQL -count=1 {{.CLI_ARGS}}
+            RESULT=$?
+            docker rm -f "$NAME" >/dev/null 2>&1
+            return $RESULT
+          }
+          run_engine mysql mysql:8.4 || STATUS=1
+          run_engine mariadb mariadb:11 || STATUS=1
+          exit $STATUS
+        silent: true
+
+  test:postgres:
+    desc: Run the PostgreSQL tests against real servers (postgres:16 then postgres:17 in Docker, removed afterwards)
+    cmds:
+      - cmd: |
+          PASSWORD=renewcms-test-postgres
+          STATUS=0
+          run_engine() {
+            NAME="renewcms-test-postgres-$1"
+            IMAGE="postgres:$1"
+            docker rm -f "$NAME" >/dev/null 2>&1
+            docker run -d --name "$NAME" -e POSTGRES_PASSWORD="$PASSWORD" -p 127.0.0.1::5432 "$IMAGE" >/dev/null || return 1
+            MAPPING="$(docker port "$NAME" 5432/tcp | head -n 1)"
+            PORT="${MAPPING##*:}"
+            READY=no
+            TRIES=0
+            while [ "$TRIES" -lt 90 ]; do
+              if docker exec "$NAME" pg_isready -h 127.0.0.1 -U postgres >/dev/null 2>&1 && docker exec "$NAME" psql -h 127.0.0.1 -U postgres -c 'SELECT 1' >/dev/null 2>&1; then
+                READY=yes
+                break
+              fi
+              TRIES=$((TRIES + 1))
+              sleep 2
+            done
+            if [ "$READY" != yes ]; then
+              echo "$IMAGE did not become ready" >&2
+              docker logs "$NAME" 2>&1 | tail -n 20 >&2
+              docker rm -f "$NAME" >/dev/null 2>&1
+              return 1
+            fi
+            echo "== $IMAGE on 127.0.0.1:$PORT"
+            RENEWCMS_TEST_POSTGRES_DSN="postgres://postgres:$PASSWORD@127.0.0.1:$PORT/postgres?sslmode=disable" go test -tags nofrontend ./test/... -run Postgres -count=1 {{.CLI_ARGS}}
+            RESULT=$?
+            docker rm -f "$NAME" >/dev/null 2>&1
+            return $RESULT
+          }
+          run_engine 16 || STATUS=1
+          run_engine 17 || STATUS=1
+          exit $STATUS
+        silent: true
+
+  test:s3:
+    desc: Run the S3 storage integration test against a throwaway SeaweedFS in Docker (skipped when Docker is unavailable)
+    cmds:
+      - cmd: |
+          if ! docker info >/dev/null 2>&1; then
+            echo "Docker is not available, skipping the S3 integration test"
+            exit 0
+          fi
+          export MSYS_NO_PATHCONV=1
+          NAME=renewcms-test-seaweedfs
+          IMAGE=chrislusf/seaweedfs:4.48
+          BUCKET=renewcms-test
+          ACCESS_KEY=renewcms-test
+          SECRET_KEY=renewcms-test-secret
+          docker rm -f "$NAME" >/dev/null 2>&1
+          docker run -d --name "$NAME" -e AWS_ACCESS_KEY_ID="$ACCESS_KEY" -e AWS_SECRET_ACCESS_KEY="$SECRET_KEY" -p 127.0.0.1::8333 "$IMAGE" server -dir=/data -s3 -s3.port=8333 >/dev/null || exit 1
+          MAPPING="$(docker port "$NAME" 8333/tcp | head -n 1)"
+          PORT="${MAPPING##*:}"
+          READY=no
+          TRIES=0
+          while [ "$TRIES" -lt 60 ]; do
+            if docker run --rm --network "container:$NAME" --entrypoint sh "$IMAGE" -c "echo 's3.bucket.create -name $BUCKET' | timeout 30 weed shell -master=127.0.0.1:9333 && echo s3.bucket.list | timeout 30 weed shell -master=127.0.0.1:9333 | grep -q $BUCKET" >/dev/null 2>&1; then
+              READY=yes
+              break
+            fi
+            TRIES=$((TRIES + 1))
+            sleep 2
+          done
+          if [ "$READY" != yes ]; then
+            echo "SeaweedFS did not become ready" >&2
+            docker logs "$NAME" 2>&1 | tail -n 20 >&2
+            docker rm -f "$NAME" >/dev/null 2>&1
+            exit 1
+          fi
+          echo "== SeaweedFS on 127.0.0.1:$PORT"
+          RENEWCMS_TEST_S3_ENDPOINT="http://127.0.0.1:$PORT" RENEWCMS_TEST_S3_BUCKET="$BUCKET" RENEWCMS_TEST_S3_ACCESS_KEY="$ACCESS_KEY" RENEWCMS_TEST_S3_SECRET_KEY="$SECRET_KEY" go test -tags nofrontend ./test/... -run S3StorageIntegration -count=1 -v {{.CLI_ARGS}}
+          RESULT=$?
+          docker rm -f "$NAME" >/dev/null 2>&1
+          exit $RESULT
+        silent: true
+
+  cover:
+    desc: Go test coverage of the use cases → tmp/coverage.out
+    cmds:
+      - mkdir -p tmp
+      - go test -tags nofrontend ./test/... -count=1 -coverpkg=./internal/infrastructure/useCases/... -coverprofile=tmp/coverage.out
+      - go tool cover -func=tmp/coverage.out
+
+  mutate:
+    desc: Gremlins mutation testing of the use cases → tmp/gremlins.json
+    cmds:
+      - bash scripts/mutate.sh {{.CLI_ARGS}}
+
+  test:web:
+    desc: Run the SPA test suite (Vitest) in run mode
+    dir: web
+    deps: [web:install]
+    cmds:
+      - bun run vitest run
+
+  visual:check:
+    desc: Screenshot a design screen's states next to the built SPA (Playwright) → tmp/visual/<screen>/
+    dir: web
+    deps: [web:install]
+    cmds:
+      - bun visual/check.ts {{.CLI_ARGS}}
+
+  lint:
+    desc: gofmt check, go vet, eslint (--fix) and vue-tsc
+    cmds:
+      - task: lint:go
+      - task: lint:web
+
+  lint:go:
+    cmds:
+      - cmd: test -z "$(gofmt -l .)" || (gofmt -l . && echo "unformatted Go files, run 'task fmt'" && exit 1)
+        silent: true
+      - go vet -tags nofrontend ./...
+
+  lint:web:
+    dir: web
+    deps: [web:install]
+    cmds:
+      - bun lint
+      - bun run type-check
+
+  fmt:
+    desc: Format Go and frontend sources
+    cmds:
+      - gofmt -w .
+      - bun run --cwd web format
+
+  web:install:
+    internal: true
+    dir: web
+    sources: [package.json, bun.lock]
+    generates: ['node_modules/.bin/vite*']
+    cmds:
+      - bun install --frozen-lockfile
+
+  build:web:
+    desc: Type-check and build the SPA into {{.DIST_DIR}}
+    dir: web
+    deps: [web:install]
+    sources: [src/**/*, public/**/*, vite/**/*, index.html, vite.config.ts, tsconfig*.json, package.json, bun.lock]
+    generates: ['../{{.DIST_DIR}}/index.html']
+    cmds:
+      - bun run build
+
+  build:llms:
+    desc: Generate llms.txt, llms-full.txt and openapi.json from the route catalogue and docs/ → {{.LLMS_DIR}}
+    deps: [web:install]
+    sources: [scripts/generate-llms.ts, web/src/data/apiCatalogue.ts, docs/api.md, docs/api/*.md, docs/llm/*.md, docs/configuration.md]
+    generates: ['{{.LLMS_DIR}}/llms-full.txt']
+    cmds:
+      - bun scripts/generate-llms.ts
+
+  build:
+    desc: Production binary for this machine → bin/{{.BINARY}}
+    deps: [build:web, build:llms]
+    cmds:
+      - go build -trimpath -ldflags "{{.LDFLAGS}}" -o bin/{{.BINARY}}{{exeExt}} ./cmd/server
+
+  build:mcp:
+    desc: MCP server (stdio) for this machine → bin/{{.BINARY}}-mcp
+    cmds:
+      - go build -trimpath -ldflags "{{.LDFLAGS}}" -o bin/{{.BINARY}}-mcp{{exeExt}} ./cmd/mcp
+
+  release:
+    desc: Cross-compile and sign production binaries for all release targets → bin/ (needs RELEASE_SIGNING_KEY)
+    cmds:
+      - task: release:check
+      - task: build:web
+      - task: build:llms
+      - for: { var: RELEASE_TARGETS }
+        task: build:target
+        vars:
+          GOOS: '{{index (splitList "/" .ITEM) 0}}'
+          GOARCH: '{{index (splitList "/" .ITEM) 1}}'
+      - go run ./cmd/releasesign checksums bin --match "{{.BINARY}}_{{.VERSION}}_*"
+      - go run ./cmd/releasesign sign bin/checksums.txt
+      - go run ./cmd/releasesign verify bin/checksums.txt
+
+  release:check:
+    internal: true
+    cmds:
+      - cmd: 'test -n "$RELEASE_SIGNING_KEY" || { echo "RELEASE_SIGNING_KEY is not set. Point it at the private release key file (see task release:keygen)." >&2; exit 1; }'
+        silent: true
+      - cmd: 'test -f "$RELEASE_SIGNING_KEY" || { echo "RELEASE_SIGNING_KEY points to a missing file: $RELEASE_SIGNING_KEY" >&2; exit 1; }'
+        silent: true
+      - mkdir -p tmp
+      - echo probe > tmp/release-probe.txt
+      - defer: rm -f tmp/release-probe.txt tmp/release-probe.txt.sig
+      - go run ./cmd/releasesign sign tmp/release-probe.txt
+
+  release:keygen:
+    desc: One-time release key pair. Usage, task release:keygen -- <private key path outside the repository>
+    cmds:
+      - cmd: 'test -n "{{.CLI_ARGS}}" || { echo "usage: task release:keygen -- <private key path outside the repository>" >&2; exit 1; }'
+        silent: true
+      - go run ./cmd/releasesign keygen {{.CLI_ARGS}}
+
+  build:target:
+    internal: true
+    vars:
+      EXT: '{{if eq .GOOS "windows"}}.exe{{end}}'
+    env:
+      GOOS: '{{.GOOS}}'
+      GOARCH: '{{.GOARCH}}'
+    cmds:
+      - go build -trimpath -ldflags "{{.LDFLAGS}}" -o bin/{{.BINARY}}_{{.VERSION}}_{{.GOOS}}_{{.GOARCH}}{{.EXT}} ./cmd/server
+
+  run:
+    desc: Build and run the production binary locally
+    deps: [build]
+    cmds:
+      - ./bin/{{.BINARY}}{{exeExt}}
+
+  docker:build:
+    desc: Build the Docker image tagged with the git describe version and latest
+    cmds:
+      - docker build --build-arg VERSION={{.VERSION}} -t renewcms:{{.VERSION}} -t renewcms:latest .
+
+  docker:run:
+    desc: Run the image once on a named volume, reading docker.env, on http://localhost:8080
+    cmds:
+      - docker run --rm --name renewcms -p 8080:8080 --env-file docker.env -e DB_FILE=/data/renewcms.db -e UPLOAD_DIR=/data/uploads -v renewcms-data:/data --stop-timeout 15 renewcms:latest
+
+  docker:up:
+    desc: Build from the local sources and start the Compose service in the background
+    env:
+      VERSION: '{{.VERSION}}'
+    cmds:
+      - docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+
+  docker:pull:
+    desc: Pull the published image (RENEWCMS_IMAGE, default the beta tag)
+    cmds:
+      - docker compose pull
+
+  docker:upgrade:
+    desc: Pull the published image and recreate the Compose service on it
+    cmds:
+      - docker compose pull
+      - docker compose up -d
+
+  docker:down:
+    desc: Stop and remove the Compose service (the data volume is kept)
+    cmds:
+      - docker compose down
+
+  docker:logs:
+    desc: Follow the Compose service logs
+    cmds:
+      - docker compose logs -f renewcms
+
+  docker:publish:
+    desc: 'Build and push the multi-arch image to the registry. Usage, task docker:publish [-- --dry-run]'
+    vars:
+      REGISTRY_IMAGE:
+        sh: echo "${REGISTRY_IMAGE-git.floriansylvain.fr/fsylvain/renewcms}"
+    cmds:
+      - cmd: |
+          IMAGE='{{.REGISTRY_IMAGE}}'
+          V='{{.VERSION}}'
+          ARGS='{{.CLI_ARGS}}'
+          fail() { echo "docker:publish refused: $1" >&2; exit 1; }
+          DRY=no
+          case "$ARGS" in
+            "") ;;
+            "--dry-run") DRY=yes ;;
+            *) fail "unknown argument '$ARGS' (only --dry-run is accepted)" ;;
+          esac
+          [ -n "$IMAGE" ] || fail "REGISTRY_IMAGE is empty"
+          case "$V" in
+            v*) ;;
+            *) fail "VERSION '$V' must be an exact tag vX.Y.Z or vX.Y.Z-<pre>" ;;
+          esac
+          R="${V#v}"
+          CORE="${R%%-*}"
+          PRE=""
+          [ "$CORE" = "$R" ] || PRE="${R#*-}"
+          MAJOR="${CORE%%.*}"
+          REST="${CORE#*.}"
+          MINOR="${REST%%.*}"
+          PATCH="${REST#*.}"
+          for N in "$MAJOR" "$MINOR" "$PATCH"; do
+            case "$N" in
+              ""|*[!0-9]*) fail "VERSION '$V' must be an exact tag vX.Y.Z or vX.Y.Z-<pre>" ;;
+            esac
+          done
+          [ "$CORE" = "$MAJOR.$MINOR.$PATCH" ] || fail "VERSION '$V' must be an exact tag vX.Y.Z or vX.Y.Z-<pre>"
+          if [ "$R" != "$CORE" ]; then
+            case "$PRE" in
+              ""|*[!0-9A-Za-z.-]*) fail "VERSION '$V' has an invalid pre-release part" ;;
+            esac
+            PRENAME="${PRE%%[!A-Za-z]*}"
+            [ -n "$PRENAME" ] || fail "VERSION '$V' pre-release must start with letters, for example -beta or -rc.1"
+          fi
+          if [ "$DRY" = no ]; then
+            [ -z "$(git status --porcelain)" ] || fail "the work tree has uncommitted changes"
+            [ "$(git describe --tags --exact-match 2>/dev/null)" = "$V" ] || fail "VERSION '$V' is not an exact git tag on HEAD (an override is accepted only with --dry-run)"
+          fi
+          TAGS="$V $R"
+          if [ -n "$PRE" ]; then
+            TAGS="$TAGS $PRENAME"
+          else
+            TAGS="$TAGS $MAJOR.$MINOR latest"
+          fi
+          ARGS_TAGS=""
+          LIST=""
+          for T in $TAGS; do
+            ARGS_TAGS="$ARGS_TAGS -t $IMAGE:$T"
+            LIST="$LIST, $T"
+          done
+          echo "image: $IMAGE"
+          echo "tags: ${LIST#, }"
+          if [ "$DRY" = yes ]; then
+            echo "dry run: building for the host platform only, loading locally, pushing nothing"
+            docker buildx build --load --build-arg VERSION="$V" $ARGS_TAGS .
+            exit 0
+          fi
+          BUILDER="$(docker buildx inspect 2>&1)" || fail "docker buildx is not available or no builder is selected (see docs/docker.md, Maintainer: publishing)"
+          STORE="$(docker info 2>&1)"
+          case "$BUILDER" in
+            *linux/amd64*) ;;
+            *) fail "the selected buildx builder does not support linux/amd64 (see docs/docker.md, Maintainer: publishing)" ;;
+          esac
+          case "$BUILDER" in
+            *linux/arm64*) ;;
+            *) fail "the selected buildx builder does not support linux/arm64: enable QEMU/binfmt (see docs/docker.md, Maintainer: publishing)" ;;
+          esac
+          case "$BUILDER" in
+            *"Driver:"*"docker-container"*|*"Driver:"*"kubernetes"*|*"Driver:"*"remote"*) ;;
+            *)
+              case "$STORE" in
+                *io.containerd.snapshotter*) ;;
+                *) fail "the selected builder uses the plain docker driver without the containerd image store, which cannot build multi-platform images: run 'docker buildx create --use' (see docs/docker.md, Maintainer: publishing)" ;;
+              esac
+              ;;
+          esac
+          docker buildx build --platform linux/amd64,linux/arm64 --build-arg VERSION="$V" $ARGS_TAGS --push .
+        silent: true
+
+  clean:
+    desc: Remove build output, the built SPA and tmp/
+    cmds:
+      - rm -rf bin tmp {{.DIST_DIR}}

api/dependecyInjection.go

@@ -0,0 +1,586 @@
+package api
+
+import (
+	"RenewCMS/api/pkg/authtoken"
+	domainAPIKey "RenewCMS/internal/domain/apikey"
+	domainArticle "RenewCMS/internal/domain/article"
+	domainAudit "RenewCMS/internal/domain/audit"
+	domainAuthor "RenewCMS/internal/domain/author"
+	domainContentType "RenewCMS/internal/domain/contenttype"
+	domainEntry "RenewCMS/internal/domain/entry"
+	domainImage "RenewCMS/internal/domain/image"
+	domainInvite "RenewCMS/internal/domain/invite"
+	domainMail "RenewCMS/internal/domain/mail"
+	domainPurge "RenewCMS/internal/domain/purge"
+	domainRole "RenewCMS/internal/domain/role"
+	domainSession "RenewCMS/internal/domain/session"
+	domainSite "RenewCMS/internal/domain/site"
+	domainTransaction "RenewCMS/internal/domain/transaction"
+	domainUpdate "RenewCMS/internal/domain/update"
+	domainUser "RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/auditing"
+	"RenewCMS/internal/infrastructure/config"
+	"RenewCMS/internal/infrastructure/hashing"
+	"RenewCMS/internal/infrastructure/imaging"
+	"RenewCMS/internal/infrastructure/mailer"
+	"RenewCMS/internal/infrastructure/markdown"
+	"RenewCMS/internal/infrastructure/persistence/database"
+	persistence "RenewCMS/internal/infrastructure/persistence/repositories"
+	"RenewCMS/internal/infrastructure/scheduler"
+	"RenewCMS/internal/infrastructure/storage"
+	"RenewCMS/internal/infrastructure/update"
+	"RenewCMS/internal/infrastructure/usage"
+	"RenewCMS/internal/infrastructure/useCases"
+	"context"
+	"crypto/ed25519"
+	"log"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"sync"
+	"time"
+)
+
+type UseCases struct {
+	apiKeyAuthOnce                  sync.Once
+	apiKeyAuthMiddleware            func(http.Handler) http.Handler
+	Token                           *authtoken.Auth
+	PurgeScheduler                  *scheduler.Runner
+	ActivityCleanupScheduler        *scheduler.Runner
+	RetentionScheduler              *scheduler.Runner
+	CreateArticleUseCase            *useCases.CreateArticleUseCase
+	GetArticleUseCase               *useCases.GetArticleUseCase
+	ListArticlesUseCase             *useCases.ListArticlesUseCase
+	UpdateArticleUseCase            *useCases.UpdateArticleUseCase
+	ResolveArticleSEOUseCase        *useCases.ResolveArticleSEOUseCase
+	CheckArticleSEOUseCase          *useCases.CheckArticleSEOUseCase
+	ListSitemapUseCase              *useCases.ListSitemapUseCase
+	DeleteArticleUseCase            *useCases.DeleteArticleUseCase
+	ListAuthorsUseCase              *useCases.ListAuthorsUseCase
+	CreateAuthorUseCase             *useCases.CreateAuthorUseCase
+	CreateMyAuthorUseCase           *useCases.CreateMyAuthorUseCase
+	UpdateAuthorUseCase             *useCases.UpdateAuthorUseCase
+	DeleteAuthorUseCase             *useCases.DeleteAuthorUseCase
+	GetMyAuthorUseCase              *useCases.GetMyAuthorUseCase
+	GetMyAccessUseCase              *useCases.GetMyAccessUseCase
+	CheckPermissionUseCase          *useCases.CheckPermissionUseCase
+	ListPermissionsUseCase          *useCases.ListPermissionsUseCase
+	ListSitesUseCase                *useCases.ListSitesUseCase
+	CreateSiteUseCase               *useCases.CreateSiteUseCase
+	UpdateSiteUseCase               *useCases.UpdateSiteUseCase
+	SetDefaultSiteUseCase           *useCases.SetDefaultSiteUseCase
+	DeleteSiteUseCase               *useCases.DeleteSiteUseCase
+	CreateContentTypeUseCase        *useCases.CreateContentTypeUseCase
+	ListContentTypesUseCase         *useCases.ListContentTypesUseCase
+	GetContentTypeUseCase           *useCases.GetContentTypeUseCase
+	UpdateContentTypeUseCase        *useCases.UpdateContentTypeUseCase
+	DeleteContentTypeUseCase        *useCases.DeleteContentTypeUseCase
+	ListRolesUseCase                *useCases.ListRolesUseCase
+	GetRoleUseCase                  *useCases.GetRoleUseCase
+	CreateRoleUseCase               *useCases.CreateRoleUseCase
+	UpdateRoleUseCase               *useCases.UpdateRoleUseCase
+	DeleteRoleUseCase               *useCases.DeleteRoleUseCase
+	ReassignRoleMembersUseCase      *useCases.ReassignRoleMembersUseCase
+	ListBuiltinTypesUseCase         *useCases.ListBuiltinTypesUseCase
+	GetBuiltinTypeUseCase           *useCases.GetBuiltinTypeUseCase
+	LookupUserNamesUseCase          *useCases.LookupUserNamesUseCase
+	CreateEntryUseCase              *useCases.CreateEntryUseCase
+	GetEntryUseCase                 *useCases.GetEntryUseCase
+	ListEntriesUseCase              *useCases.ListEntriesUseCase
+	UpdateEntryUseCase              *useCases.UpdateEntryUseCase
+	DeleteEntryUseCase              *useCases.DeleteEntryUseCase
+	GetUserUseCase                  *useCases.GetUserUseCase
+	CreateUserUseCase               *useCases.CreateUserUseCase
+	AuthenticateUserUseCase         *useCases.AuthenticateUserUseCase
+	VerifyUserUseCase               *useCases.VerifyUserUseCase
+	CancelRegistrationUseCase       *useCases.CancelRegistrationUseCase
+	RequestPasswordResetUseCase     *useCases.RequestPasswordResetUseCase
+	ResetPasswordUseCase            *useCases.ResetPasswordUseCase
+	UpdateUserProfileUseCase        *useCases.UpdateUserProfileUseCase
+	RequestEmailChangeUseCase       *useCases.RequestEmailChangeUseCase
+	ResendEmailChangeUseCase        *useCases.ResendEmailChangeUseCase
+	CancelEmailChangeUseCase        *useCases.CancelEmailChangeUseCase
+	ConfirmEmailChangeUseCase       *useCases.ConfirmEmailChangeUseCase
+	ListUsersUseCase                *useCases.ListUsersUseCase
+	CreateInviteUseCase             *useCases.CreateInviteUseCase
+	CancelInviteUseCase             *useCases.CancelInviteUseCase
+	RenewInviteUseCase              *useCases.RenewInviteUseCase
+	ListUsersAndInvitesUseCase      *useCases.ListUsersAndInvitesUseCase
+	ChangeUserRoleUseCase           *useCases.ChangeUserRoleUseCase
+	RemoveUserUseCase               *useCases.RemoveUserUseCase
+	ExportUserDataUseCase           *useCases.ExportUserDataUseCase
+	DeleteOwnAccountUseCase         *useCases.DeleteOwnAccountUseCase
+	TransferOwnershipUseCase        *useCases.TransferOwnershipUseCase
+	GetInviteUseCase                *useCases.GetInviteUseCase
+	AcceptInviteUseCase             *useCases.AcceptInviteUseCase
+	SendMailUseCase                 *useCases.SendMailUseCase
+	CreateImageUseCase              *useCases.CreateImageUseCase
+	OpenMediaUseCase                *useCases.OpenMediaUseCase
+	ListMediaUseCase                *useCases.ListMediaUseCase
+	RenameMediaUseCase              *useCases.RenameMediaUseCase
+	DeleteMediaUseCase              *useCases.DeleteMediaUseCase
+	MergeMediaUseCase               *useCases.MergeMediaUseCase
+	GetMediaUsageUseCase            *useCases.GetMediaUsageUseCase
+	GetPurgeSettingsUseCase         *useCases.GetPurgeSettingsUseCase
+	UpdatePurgeSettingsUseCase      *useCases.UpdatePurgeSettingsUseCase
+	PreviewPurgeUseCase             *useCases.PreviewPurgeUseCase
+	RunPurgeUseCase                 *useCases.RunPurgeUseCase
+	GetSettingsUseCase              *useCases.GetSettingsUseCase
+	GetUpdateStatusUseCase          *useCases.GetUpdateStatusUseCase
+	CheckForUpdateUseCase           *useCases.CheckForUpdateUseCase
+	StartUpdateDownloadUseCase      *useCases.StartUpdateDownloadUseCase
+	RequestRestartUseCase           *useCases.RequestRestartUseCase
+	RecordRunningInfoUseCase        *useCases.RecordRunningInfoUseCase
+	CreateAPIKeyUseCase             *useCases.CreateAPIKeyUseCase
+	ListAPIKeysUseCase              *useCases.ListAPIKeysUseCase
+	RevokeAPIKeyUseCase             *useCases.RevokeAPIKeyUseCase
+	AuthenticateAPIKeyUseCase       *useCases.AuthenticateAPIKeyUseCase
+	ListActivityUseCase             *useCases.ListActivityUseCase
+	GetActivitySummaryUseCase       *useCases.GetActivitySummaryUseCase
+	ExportActivityUseCase           *useCases.ExportActivityUseCase
+	GetActivityRetentionUseCase     *useCases.GetActivityRetentionUseCase
+	UpdateActivityRetentionUseCase  *useCases.UpdateActivityRetentionUseCase
+	ListVariantsUseCase             *useCases.ListVariantsUseCase
+	CreateVariantUseCase            *useCases.CreateVariantUseCase
+	UpdateVariantUseCase            *useCases.UpdateVariantUseCase
+	SetVariantEnabledUseCase        *useCases.SetVariantEnabledUseCase
+	DeleteVariantUseCase            *useCases.DeleteVariantUseCase
+	PurgeVariantUseCase             *useCases.PurgeVariantUseCase
+	ServeVariantUseCase             *useCases.ServeVariantUseCase
+	ListImageVariantsUseCase        *useCases.ListImageVariantsUseCase
+	GenerateImageVariantUseCase     *useCases.GenerateImageVariantUseCase
+	GenerateAllImageVariantsUseCase *useCases.GenerateAllImageVariantsUseCase
+	PurgeImageVariantUseCase        *useCases.PurgeImageVariantUseCase
+	GenerateVariantsOnUploadUseCase *useCases.GenerateVariantsOnUploadUseCase
+	GetVariantCacheStatsUseCase     *useCases.GetVariantCacheStatsUseCase
+	PurgeVariantCacheUseCase        *useCases.PurgeVariantCacheUseCase
+	VariantUsageTracker             *usage.Tracker
+}
+
+func (c *UseCases) RunSchedulers(ctx context.Context) {
+	var running sync.WaitGroup
+	for _, runner := range []*scheduler.Runner{c.PurgeScheduler, c.ActivityCleanupScheduler, c.RetentionScheduler} {
+		if runner == nil {
+			continue
+		}
+		running.Add(1)
+		go func() {
+			defer running.Done()
+			runner.Run(ctx)
+		}()
+	}
+	running.Wait()
+}
+
+type Repositories struct {
+	ArticleRepo       domainArticle.Repository
+	SiteRepo          domainSite.Repository
+	ContentTypeRepo   domainContentType.Repository
+	EntryRepo         domainEntry.Repository
+	AuthorRepo        domainAuthor.Repository
+	UserRepo          domainUser.Repository
+	UserEraser        domainUser.Eraser
+	RoleRepo          domainRole.Repository
+	ImageRepo         domainImage.Repository
+	Transactor        domainTransaction.Transactor
+	VariantRepo       domainImage.VariantRepository
+	VariantFileRepo   domainImage.VariantFileRepository
+	VariantCacheRepo  domainImage.VariantCacheRepository
+	VariantUsageRepo  domainImage.VariantUsageRepository
+	VariantRenderer   domainImage.VariantRenderer
+	InviteRepo        domainInvite.Repository
+	APIKeyRepo        domainAPIKey.Repository
+	SessionRepo       domainSession.Repository
+	PurgeSettingsRepo domainPurge.Repository
+	AuditRepo         domainAudit.Repository
+	AuditSettingsRepo domainAudit.SettingsRepository
+	MailRepo          domainMail.Repository
+	ReleaseFeed       domainUpdate.ReleaseFeed
+	UpdateStore       domainUpdate.StatusStore
+	UpdateJobs        domainUpdate.JobStore
+	UpdateHelper      domainUpdate.HelperDetector
+	AssetFetcher      domainUpdate.AssetFetcher
+	SignatureVerifier domainUpdate.SignatureVerifier
+	StagedRunner      domainUpdate.StagedBinaryRunner
+	DatabaseBackup    domainUpdate.DatabaseBackup
+	UpdateResults     domainUpdate.ResultStore
+	RestartRequests   domainUpdate.RestartRequestStore
+	RunningInfo       domainUpdate.RunningInfoStore
+}
+
+const (
+	updateStatusFileName = "update-status.json"
+	updateJobFileName    = "update-job.json"
+	updateHelperFileName = "update-helper.json"
+	updatesDirName       = "updates"
+	backupsDirName       = "backups"
+
+	maxConcurrentDataExports = 2
+)
+
+func imageStorageConfig(settings config.Settings) storage.Config {
+	if settings.Storage.Driver == config.StorageDriverS3 {
+		s3 := settings.Storage.S3
+		return storage.Config{
+			Driver: storage.DriverS3,
+			S3: storage.S3Config{
+				Bucket:          s3.Bucket,
+				Region:          s3.Region,
+				Endpoint:        s3.Endpoint,
+				AccessKeyID:     s3.AccessKeyID,
+				SecretAccessKey: s3.SecretAccessKey,
+				KeyPrefix:       s3.KeyPrefix,
+				PathStyle:       s3.PathStyle,
+				TLS:             s3.TLS,
+			},
+		}
+	}
+	return storage.Config{Driver: storage.DriverLocal, Location: settings.UploadDir}
+}
+
+func openImageStorage(settings config.Settings) domainImage.Storage {
+	imageStorage, err := storage.Open(imageStorageConfig(settings))
+	if err != nil {
+		panic("Unable to open the image storage: " + err.Error())
+	}
+	return imageStorage
+}
+
+func databaseConfig(settings config.Settings) database.Config {
+	switch settings.Database.Driver {
+	case config.DatabaseDriverMySQL:
+		return mysqlDatabaseConfig(settings.Database)
+	case config.DatabaseDriverPostgres:
+		return postgresDatabaseConfig(settings.Database)
+	case "", config.DatabaseDriverSQLite:
+		return database.Config{Driver: database.DriverSQLite, Source: settings.DBFile}
+	default:
+		return database.Config{Driver: settings.Database.Driver}
+	}
+}
+
+func mysqlDatabaseConfig(settings config.DatabaseSettings) database.Config {
+	return database.Config{
+		Driver: database.DriverMySQL,
+		Source: database.MySQLDSN(database.MySQLConfig{
+			Host:     settings.Host,
+			Port:     settings.Port,
+			User:     settings.User,
+			Password: settings.Password,
+			Name:     settings.Name,
+			TLS:      settings.TLS,
+		}),
+		Pool: &database.PoolSettings{
+			MaxOpenConns:    settings.MaxOpenConns,
+			MaxIdleConns:    settings.MaxIdleConns,
+			ConnMaxLifetime: settings.ConnMaxLifetime,
+		},
+	}
+}
+
+func postgresDatabaseConfig(settings config.DatabaseSettings) database.Config {
+	return database.Config{
+		Driver: database.DriverPostgres,
+		Source: database.PostgresDSN(database.PostgresConfig{
+			Host:     settings.Host,
+			Port:     settings.Port,
+			User:     settings.User,
+			Password: settings.Password,
+			Name:     settings.Name,
+			SSLMode:  settings.SSLMode,
+		}),
+		Pool: &database.PoolSettings{
+			MaxOpenConns:    settings.MaxOpenConns,
+			MaxIdleConns:    settings.MaxIdleConns,
+			ConnMaxLifetime: settings.ConnMaxLifetime,
+		},
+	}
+}
+
+func openDatabase(settings config.Settings) *database.Connection {
+	connection, err := database.Connect(databaseConfig(settings))
+	if err != nil {
+		panic("Unable to open the database: " + err.Error())
+	}
+	if err := database.Migrate(connection.DB, settings.PublicURL); err != nil {
+		panic("Failed to migrate database: " + err.Error())
+	}
+	return connection
+}
+
+func releasePublicKey() ed25519.PublicKey {
+	key, err := update.EmbeddedPublicKey()
+	if err != nil {
+		panic("Unable to read the embedded release key: " + err.Error())
+	}
+	return key
+}
+
+func getRepositories(connection *database.Connection, settings config.Settings) *Repositories {
+	db := connection.DB
+	dataDir := settings.DataDir()
+	variantFiles := persistence.NewVariantFileRepository(db)
+	return &Repositories{
+		ArticleRepo:       persistence.NewArticleRepository(db),
+		SiteRepo:          persistence.NewSiteRepository(db),
+		ContentTypeRepo:   persistence.NewContentTypeRepository(db),
+		EntryRepo:         persistence.NewEntryRepository(db),
+		AuthorRepo:        persistence.NewAuthorRepository(db),
+		UserRepo:          persistence.NewUserRepository(db),
+		UserEraser:        persistence.NewAccountEraser(db),
+		RoleRepo:          persistence.NewRoleRepository(db),
+		ImageRepo:         persistence.NewImageRepository(db),
+		Transactor:        persistence.NewTransactor(db),
+		VariantRepo:       persistence.NewVariantRepository(db),
+		VariantFileRepo:   variantFiles,
+		VariantCacheRepo:  variantFiles,
+		VariantUsageRepo:  persistence.NewVariantUsageRepository(db),
+		VariantRenderer:   imaging.NewVariantRenderer(),
+		InviteRepo:        persistence.NewInviteRepository(db),
+		APIKeyRepo:        persistence.NewAPIKeyRepository(db),
+		SessionRepo:       persistence.NewRevokedSessionRepository(db),
+		PurgeSettingsRepo: persistence.NewPurgeSettingsRepository(db),
+		AuditRepo:         persistence.NewAuditEventRepository(db),
+		AuditSettingsRepo: persistence.NewAuditSettingsRepository(db),
+		MailRepo:          mailer.NewMailRepository(settings.Smtp),
+		ReleaseFeed:       update.NewGiteaReleaseFeed(settings.UpdateFeedURL),
+		UpdateStore:       update.NewJSONStatusStore(filepath.Join(dataDir, updateStatusFileName)),
+		UpdateJobs:        update.NewJSONJobStore(filepath.Join(dataDir, updateJobFileName)),
+		UpdateHelper:      update.NewContainerHelperDetector(update.NewFileHelperDetector(filepath.Join(dataDir, updateHelperFileName)), settings.Container),
+		AssetFetcher:      update.NewHTTPAssetFetcher(settings.UpdateFeedURL),
+		SignatureVerifier: update.NewEd25519SignatureVerifier(releasePublicKey()),
+		StagedRunner:      update.NewExecStagedBinaryRunner(),
+		DatabaseBackup:    connection.NewBackup(filepath.Join(dataDir, backupsDirName), time.Now),
+		UpdateResults:     update.NewJSONResultStore(filepath.Join(dataDir, domainUpdate.ResultFileName)),
+		RestartRequests:   update.NewJSONRestartRequestStore(filepath.Join(dataDir, domainUpdate.RestartRequestFileName)),
+		RunningInfo:       update.NewJSONRunningInfoStore(filepath.Join(dataDir, domainUpdate.RunningInfoFileName)),
+	}
+}
+
+func getUseCases(repos *Repositories, imageStorage domainImage.Storage, settings config.Settings) *UseCases {
+	hasher := hashing.NewBcryptHasher()
+	mailDispatcher := mailer.NewAsyncDispatcher()
+	sessionRevocation := useCases.NewSessionRevocationUseCase(repos.SessionRepo, time.Now)
+	renderer := markdown.NewConverter()
+	keyGenerator := hashing.NewSHA256KeyGenerator()
+	recorder := auditing.NewRecorder(repos.AuditRepo, time.Now, log.Default())
+	mediaUsage := useCases.NewGetMediaUsageUseCase(repos.ImageRepo, repos.ArticleRepo, repos.SiteRepo, repos.AuthorRepo, repos.ContentTypeRepo, repos.EntryRepo)
+	mergeMedia := useCases.NewMergeMediaUseCase(repos.ImageRepo, repos.ArticleRepo, imageStorage, repos.VariantFileRepo, recorder, repos.ContentTypeRepo, repos.EntryRepo, repos.Transactor, log.Default())
+
+	runPurge := useCases.NewRunPurgeUseCase(repos.ImageRepo, repos.ArticleRepo, mergeMedia, repos.PurgeSettingsRepo, time.Now, log.Default(), recorder, repos.SiteRepo, repos.AuthorRepo)
+	purgeScheduler := useCases.NewPurgeSchedulerUseCase(repos.PurgeSettingsRepo, runPurge, recorder)
+	activityCleanup := useCases.NewCleanupActivityUseCase(repos.AuditRepo, repos.AuditSettingsRepo, recorder)
+
+	usageTracker := usage.NewTracker(repos.VariantUsageRepo, time.Now)
+	serveVariant := useCases.NewServeVariantUseCase(repos.VariantRepo, repos.VariantFileRepo, repos.ImageRepo, imageStorage, repos.VariantRenderer, useCases.ServeVariantLimits{MaxSourceBytes: settings.ImageVariantMaxSourceBytes, MaxSourcePixels: settings.ImageVariantMaxSourcePixels, MaxConcurrentRenders: settings.ImageVariantMaxConcurrentRenders}).WithUsageTracker(usageTracker)
+
+	return &UseCases{
+		PurgeScheduler:                  scheduler.NewSystemRunner(purgeScheduler, log.Default()),
+		ActivityCleanupScheduler:        scheduler.NewSystemCleanupRunner(activityCleanup, log.Default()),
+		RetentionScheduler:              scheduler.NewSystemRetentionRunner(useCases.NewEnforceRetentionUseCase(repos.UserRepo, repos.InviteRepo, repos.SessionRepo), log.Default()),
+		Token:                           authtoken.New([]byte(settings.JWTSecret), authtoken.WithRevocationStore(sessionRevocation)),
+		CreateArticleUseCase:            useCases.NewCreateArticleUseCase(repos.ArticleRepo, renderer, recorder, repos.SiteRepo, repos.AuthorRepo),
+		GetArticleUseCase:               useCases.NewGetArticleUseCase(repos.ArticleRepo, renderer),
+		ListArticlesUseCase:             useCases.NewListArticlesUseCase(repos.ArticleRepo, renderer, repos.SiteRepo),
+		UpdateArticleUseCase:            useCases.NewUpdateArticleUseCase(repos.ArticleRepo, renderer, recorder, repos.SiteRepo, repos.AuthorRepo, repos.ImageRepo),
+		DeleteArticleUseCase:            useCases.NewDeleteArticleUseCase(repos.ArticleRepo, recorder),
+		ResolveArticleSEOUseCase:        useCases.NewResolveArticleSEOUseCase(repos.ArticleRepo, repos.SiteRepo, repos.ImageRepo),
+		CheckArticleSEOUseCase:          useCases.NewCheckArticleSEOUseCase(repos.ArticleRepo, repos.SiteRepo, repos.ImageRepo),
+		ListSitemapUseCase:              useCases.NewListSitemapUseCase(repos.ArticleRepo, repos.SiteRepo),
+		ListAuthorsUseCase:              useCases.NewListAuthorsUseCase(repos.AuthorRepo, repos.UserRepo),
+		CreateAuthorUseCase:             useCases.NewCreateAuthorUseCase(repos.AuthorRepo, repos.UserRepo, repos.ImageRepo, recorder),
+		CreateMyAuthorUseCase:           useCases.NewCreateMyAuthorUseCase(repos.AuthorRepo, repos.UserRepo, recorder),
+		UpdateAuthorUseCase:             useCases.NewUpdateAuthorUseCase(repos.AuthorRepo, repos.UserRepo, repos.ImageRepo, recorder),
+		DeleteAuthorUseCase:             useCases.NewDeleteAuthorUseCase(repos.AuthorRepo, recorder),
+		GetMyAuthorUseCase:              useCases.NewGetMyAuthorUseCase(repos.AuthorRepo),
+		GetMyAccessUseCase:              useCases.NewGetMyAccessUseCase(repos.RoleRepo, repos.UserRepo),
+		CheckPermissionUseCase:          useCases.NewCheckPermissionUseCase(repos.RoleRepo),
+		ListPermissionsUseCase:          useCases.NewListPermissionsUseCase(),
+		ListSitesUseCase:                useCases.NewListSitesUseCase(repos.SiteRepo),
+		CreateSiteUseCase:               useCases.NewCreateSiteUseCase(repos.SiteRepo, repos.ImageRepo, recorder),
+		UpdateSiteUseCase:               useCases.NewUpdateSiteUseCase(repos.SiteRepo, repos.ImageRepo, recorder),
+		SetDefaultSiteUseCase:           useCases.NewSetDefaultSiteUseCase(repos.SiteRepo, recorder),
+		DeleteSiteUseCase:               useCases.NewDeleteSiteUseCase(repos.SiteRepo, recorder),
+		CreateContentTypeUseCase:        useCases.NewCreateContentTypeUseCase(repos.ContentTypeRepo, repos.RoleRepo, time.Now),
+		ListContentTypesUseCase:         useCases.NewListContentTypesUseCase(repos.ContentTypeRepo),
+		GetContentTypeUseCase:           useCases.NewGetContentTypeUseCase(repos.ContentTypeRepo),
+		UpdateContentTypeUseCase:        useCases.NewUpdateContentTypeUseCase(repos.ContentTypeRepo, repos.EntryRepo, time.Now),
+		DeleteContentTypeUseCase:        useCases.NewDeleteContentTypeUseCase(repos.ContentTypeRepo, repos.EntryRepo, repos.RoleRepo),
+		ListRolesUseCase:                useCases.NewListRolesUseCase(repos.RoleRepo, repos.UserRepo, repos.ContentTypeRepo),
+		GetRoleUseCase:                  useCases.NewGetRoleUseCase(repos.RoleRepo, repos.UserRepo, repos.ContentTypeRepo),
+		CreateRoleUseCase:               useCases.NewCreateRoleUseCase(repos.RoleRepo, repos.UserRepo, repos.ContentTypeRepo, recorder),
+		UpdateRoleUseCase:               useCases.NewUpdateRoleUseCase(repos.RoleRepo, repos.UserRepo, repos.ContentTypeRepo, recorder, time.Now),
+		DeleteRoleUseCase:               useCases.NewDeleteRoleUseCase(repos.RoleRepo, repos.UserRepo, repos.ContentTypeRepo, recorder),
+		ReassignRoleMembersUseCase:      useCases.NewReassignRoleMembersUseCase(repos.RoleRepo, repos.UserRepo, repos.ContentTypeRepo, recorder),
+		ListBuiltinTypesUseCase:         useCases.NewListBuiltinTypesUseCase(),
+		GetBuiltinTypeUseCase:           useCases.NewGetBuiltinTypeUseCase(),
+		LookupUserNamesUseCase:          useCases.NewLookupUserNamesUseCase(repos.UserRepo),
+		CreateEntryUseCase:              useCases.NewCreateEntryUseCase(repos.ContentTypeRepo, repos.EntryRepo, repos.ImageRepo, time.Now),
+		GetEntryUseCase:                 useCases.NewGetEntryUseCase(repos.ContentTypeRepo, repos.EntryRepo, repos.ImageRepo),
+		ListEntriesUseCase:              useCases.NewListEntriesUseCase(repos.ContentTypeRepo, repos.EntryRepo, repos.ImageRepo),
+		UpdateEntryUseCase:              useCases.NewUpdateEntryUseCase(repos.ContentTypeRepo, repos.EntryRepo, repos.ImageRepo, time.Now),
+		DeleteEntryUseCase:              useCases.NewDeleteEntryUseCase(repos.ContentTypeRepo, repos.EntryRepo),
+		GetUserUseCase:                  useCases.NewGetUserUseCase(repos.UserRepo),
+		CreateUserUseCase:               useCases.NewCreateUserUseCase(repos.UserRepo, repos.RoleRepo, hasher, repos.MailRepo, settings.PublicURL, recorder),
+		AuthenticateUserUseCase:         useCases.NewAuthenticateUserUseCase(repos.UserRepo, hasher, recorder),
+		VerifyUserUseCase:               useCases.NewVerifyUserUseCase(repos.UserRepo, hasher, recorder),
+		CancelRegistrationUseCase:       useCases.NewCancelRegistrationUseCase(repos.UserRepo),
+		RequestPasswordResetUseCase:     useCases.NewRequestPasswordResetUseCase(repos.UserRepo, hasher, repos.MailRepo, settings.PublicURL, recorder),
+		ResetPasswordUseCase:            useCases.NewResetPasswordUseCase(repos.UserRepo, hasher, repos.APIKeyRepo, time.Now, recorder),
+		UpdateUserProfileUseCase:        useCases.NewUpdateUserProfileUseCase(repos.UserRepo, recorder),
+		RequestEmailChangeUseCase:       useCases.NewRequestEmailChangeUseCase(repos.UserRepo, hasher, repos.MailRepo, mailDispatcher, settings.PublicURL, time.Now, recorder),
+		ResendEmailChangeUseCase:        useCases.NewResendEmailChangeUseCase(repos.UserRepo, hasher, repos.MailRepo, mailDispatcher, settings.PublicURL, time.Now, recorder),
+		CancelEmailChangeUseCase:        useCases.NewCancelEmailChangeUseCase(repos.UserRepo, recorder),
+		ConfirmEmailChangeUseCase:       useCases.NewConfirmEmailChangeUseCase(repos.UserRepo, hasher, time.Now, recorder),
+		ListUsersUseCase:                useCases.NewListUsersUseCase(repos.UserRepo),
+		CreateInviteUseCase:             useCases.NewCreateInviteUseCase(repos.UserRepo, repos.InviteRepo, repos.RoleRepo, repos.ContentTypeRepo, hasher, repos.MailRepo, settings.PublicURL, recorder),
+		CancelInviteUseCase:             useCases.NewCancelInviteUseCase(repos.InviteRepo, recorder),
+		RenewInviteUseCase:              useCases.NewRenewInviteUseCase(repos.UserRepo, repos.InviteRepo, repos.RoleRepo, repos.ContentTypeRepo, hasher, repos.MailRepo, settings.PublicURL, recorder),
+		ListUsersAndInvitesUseCase:      useCases.NewListUsersAndInvitesUseCase(repos.UserRepo, repos.InviteRepo, repos.RoleRepo),
+		ChangeUserRoleUseCase:           useCases.NewChangeUserRoleUseCase(repos.UserRepo, repos.RoleRepo, repos.ContentTypeRepo, recorder),
+		RemoveUserUseCase:               useCases.NewRemoveUserUseCase(repos.UserRepo, repos.RoleRepo, repos.ContentTypeRepo, recorder),
+		ExportUserDataUseCase:           useCases.NewExportUserDataUseCase(repos.UserRepo, repos.RoleRepo, repos.AuthorRepo, repos.APIKeyRepo, repos.ArticleRepo, repos.EntryRepo, repos.ContentTypeRepo, repos.ImageRepo, repos.AuditRepo, time.Now, recorder, maxConcurrentDataExports),
+		DeleteOwnAccountUseCase:         useCases.NewDeleteOwnAccountUseCase(repos.UserRepo, repos.RoleRepo, hasher, repos.UserEraser, sessionRevocation, repos.MailRepo, mailDispatcher, settings.PublicURL, recorder, repos.AuthorRepo, repos.ImageRepo, mediaUsage, imageStorage, repos.VariantFileRepo),
+		TransferOwnershipUseCase:        useCases.NewTransferOwnershipUseCase(repos.UserRepo, repos.RoleRepo, recorder),
+		GetInviteUseCase:                useCases.NewGetInviteUseCase(repos.InviteRepo, hasher),
+		AcceptInviteUseCase:             useCases.NewAcceptInviteUseCase(repos.UserRepo, repos.InviteRepo, repos.RoleRepo, hasher, recorder),
+		SendMailUseCase:                 useCases.NewSendMailUseCase(repos.MailRepo),
+		CreateImageUseCase:              useCases.NewCreateImageUseCase(repos.ImageRepo, imageStorage, recorder, imaging.NewMetadataStripper()),
+		OpenMediaUseCase:                useCases.NewOpenMediaUseCase(imageStorage),
+		ListMediaUseCase:                useCases.NewListMediaUseCase(repos.ImageRepo, repos.ArticleRepo, repos.UserRepo, repos.VariantFileRepo, repos.SiteRepo, repos.AuthorRepo, repos.ContentTypeRepo, repos.EntryRepo),
+		RenameMediaUseCase:              useCases.NewRenameMediaUseCase(repos.ImageRepo, recorder),
+		DeleteMediaUseCase:              useCases.NewDeleteMediaUseCase(repos.ImageRepo, imageStorage, repos.VariantFileRepo, recorder, repos.SiteRepo, repos.AuthorRepo, repos.ArticleRepo),
+		MergeMediaUseCase:               mergeMedia,
+		GetMediaUsageUseCase:            mediaUsage,
+		GetPurgeSettingsUseCase:         useCases.NewGetPurgeSettingsUseCase(repos.PurgeSettingsRepo),
+		UpdatePurgeSettingsUseCase:      useCases.NewUpdatePurgeSettingsUseCase(repos.PurgeSettingsRepo, time.Now),
+		PreviewPurgeUseCase:             useCases.NewPreviewPurgeUseCase(repos.ImageRepo, repos.ArticleRepo, repos.SiteRepo, repos.AuthorRepo, repos.ContentTypeRepo, repos.EntryRepo),
+		RunPurgeUseCase:                 runPurge,
+		GetSettingsUseCase:              useCases.NewGetSettingsUseCase(settings.Version),
+		GetUpdateStatusUseCase:          useCases.NewGetUpdateStatusUseCase(repos.UpdateStore, repos.UpdateJobs, repos.UpdateHelper, repos.UpdateResults, repos.RestartRequests, settings.Version, settings.Container, time.Now),
+		CheckForUpdateUseCase:           useCases.NewCheckForUpdateUseCase(repos.ReleaseFeed, repos.UpdateStore, settings.Version, time.Now, recorder),
+		StartUpdateDownloadUseCase:      startUpdateDownloadUseCase(repos, settings, recorder),
+		RequestRestartUseCase:           useCases.NewRequestRestartUseCase(repos.UpdateStore, repos.UpdateJobs, repos.UpdateHelper, repos.UpdateResults, repos.RestartRequests, settings.Version, time.Now, recorder),
+		RecordRunningInfoUseCase:        useCases.NewRecordRunningInfoUseCase(repos.RunningInfo, settings.Version, os.Getpid(), time.Now),
+		CreateAPIKeyUseCase:             useCases.NewCreateAPIKeyUseCase(repos.APIKeyRepo, keyGenerator, time.Now, recorder),
+		ListAPIKeysUseCase:              useCases.NewListAPIKeysUseCase(repos.APIKeyRepo, repos.UserRepo, time.Now),
+		RevokeAPIKeyUseCase:             useCases.NewRevokeAPIKeyUseCase(repos.APIKeyRepo, time.Now, recorder),
+		AuthenticateAPIKeyUseCase:       useCases.NewAuthenticateAPIKeyUseCase(repos.APIKeyRepo, keyGenerator, repos.UserRepo, time.Now),
+		ListActivityUseCase:             useCases.NewListActivityUseCase(repos.AuditRepo, repos.UserRepo, repos.ArticleRepo, repos.ImageRepo, repos.APIKeyRepo, time.Now, repos.SiteRepo, repos.AuthorRepo),
+		GetActivitySummaryUseCase:       useCases.NewGetActivitySummaryUseCase(repos.AuditRepo, time.Now),
+		ExportActivityUseCase:           useCases.NewExportActivityUseCase(repos.AuditRepo, time.Now),
+		GetActivityRetentionUseCase:     useCases.NewGetActivityRetentionUseCase(repos.AuditSettingsRepo, repos.AuditRepo, time.Now),
+		UpdateActivityRetentionUseCase:  useCases.NewUpdateActivityRetentionUseCase(repos.AuditSettingsRepo, repos.AuditRepo, recorder, time.Now),
+		ListVariantsUseCase:             useCases.NewListVariantsUseCase(repos.VariantRepo, repos.VariantFileRepo),
+		CreateVariantUseCase:            useCases.NewCreateVariantUseCase(repos.VariantRepo, repos.VariantRenderer, time.Now, recorder),
+		UpdateVariantUseCase:            useCases.NewUpdateVariantUseCase(repos.VariantRepo, repos.VariantFileRepo, imageStorage, repos.VariantRenderer, time.Now, recorder),
+		SetVariantEnabledUseCase:        useCases.NewSetVariantEnabledUseCase(repos.VariantRepo, repos.VariantFileRepo, time.Now, recorder),
+		DeleteVariantUseCase:            useCases.NewDeleteVariantUseCase(repos.VariantRepo, repos.VariantFileRepo, imageStorage, recorder),
+		PurgeVariantUseCase:             useCases.NewPurgeVariantUseCase(repos.VariantRepo, repos.VariantFileRepo, imageStorage, recorder),
+		ServeVariantUseCase:             serveVariant,
+		ListImageVariantsUseCase:        useCases.NewListImageVariantsUseCase(repos.ImageRepo, repos.VariantRepo, repos.VariantFileRepo, repos.VariantRenderer),
+		GenerateImageVariantUseCase:     useCases.NewGenerateImageVariantUseCase(repos.ImageRepo, repos.VariantRepo, repos.VariantFileRepo, repos.VariantRenderer, serveVariant),
+		GenerateAllImageVariantsUseCase: useCases.NewGenerateAllImageVariantsUseCase(repos.ImageRepo, repos.VariantRepo, repos.VariantFileRepo, repos.VariantRenderer, serveVariant, recorder),
+		PurgeImageVariantUseCase:        useCases.NewPurgeImageVariantUseCase(repos.ImageRepo, repos.VariantRepo, repos.VariantFileRepo, imageStorage, recorder),
+		GenerateVariantsOnUploadUseCase: useCases.NewGenerateVariantsOnUploadUseCase(repos.VariantRepo, serveVariant, log.Default()),
+		GetVariantCacheStatsUseCase:     useCases.NewGetVariantCacheStatsUseCase(repos.VariantRepo, repos.VariantFileRepo, repos.VariantCacheRepo, repos.ImageRepo, repos.VariantUsageRepo, usageTracker, time.Now),
+		PurgeVariantCacheUseCase:        useCases.NewPurgeVariantCacheUseCase(repos.VariantRepo, repos.ImageRepo, repos.VariantCacheRepo, repos.VariantFileRepo, imageStorage, time.Now, recorder),
+		VariantUsageTracker:             usageTracker,
+	}
+}
+
+func startUpdateDownloadUseCase(repos *Repositories, settings config.Settings, recorder domainAudit.Recorder) *useCases.StartUpdateDownloadUseCase {
+	return useCases.NewStartUpdateDownloadUseCase(useCases.StartUpdateDownloadDependencies{
+		Store:          repos.UpdateStore,
+		Jobs:           repos.UpdateJobs,
+		Helper:         repos.UpdateHelper,
+		Results:        repos.UpdateResults,
+		Requests:       repos.RestartRequests,
+		Fetcher:        repos.AssetFetcher,
+		Verifier:       repos.SignatureVerifier,
+		Runner:         repos.StagedRunner,
+		Backup:         repos.DatabaseBackup,
+		Staging:        update.NewOSStagingArea(filepath.Join(settings.DataDir(), updatesDirName)),
+		Logger:         log.Default(),
+		CurrentVersion: settings.Version,
+		Platform:       domainUpdate.Platform{OS: runtime.GOOS, Arch: runtime.GOARCH},
+		FeedURL:        settings.UpdateFeedURL,
+		Now:            time.Now,
+		Recorder:       recorder,
+	})
+}
+
+func backfillImageMetadata(imageRepo domainImage.Repository, imageStorage domainImage.Storage, settings config.Settings) error {
+	run := func(readable domainImage.Storage) error {
+		return useCases.NewBackfillImageMetadataUseCase(imageRepo, readable).Run()
+	}
+	if settings.Storage.Driver == config.StorageDriverS3 {
+		return storage.RunBackfillReportingReads(imageStorage, log.Default(), run)
+	}
+	return run(imageStorage)
+}
+
+func InitContainer(settings config.Settings) (*UseCases, func() error) {
+	imageStorage := openImageStorage(settings)
+	connection := openDatabase(settings)
+	repos := getRepositories(connection, settings)
+	if err := backfillImageMetadata(repos.ImageRepo, imageStorage, settings); err != nil {
+		panic("Failed to backfill image metadata: " + err.Error())
+	}
+	container := getUseCases(repos, imageStorage, settings)
+	return container, container.runUsageTracker(connection.Close)
+}
+
+func (c *UseCases) runUsageTracker(closeDatabase func() error) func() error {
+	ctx, stop := context.WithCancel(context.Background())
+	stopped := make(chan struct{})
+	go func() {
+		defer close(stopped)
+		c.VariantUsageTracker.Run(ctx)
+	}()
+	return func() error {
+		stop()
+		<-stopped
+		return closeDatabase()
+	}
+}
+
+type BrowserUpdateCommands struct {
+	Enable  *useCases.EnableBrowserUpdatesUseCase
+	Disable *useCases.DisableBrowserUpdatesUseCase
+}
+
+func InitBrowserUpdateCommands() *BrowserUpdateCommands {
+	units := update.NewSystemdUnits()
+	dependencies := useCases.ManageBrowserUpdatesDependencies{
+		Probe:   update.NewSystemMachineProbe(),
+		Locator: units,
+		Units:   units,
+		Manager: update.NewSystemctlControl(domainUpdate.ServiceUnitName),
+		Status:  update.NewJSONHelperStatusWriter(),
+		Now:     time.Now,
+	}
+	return &BrowserUpdateCommands{
+		Enable:  useCases.NewEnableBrowserUpdatesUseCase(dependencies),
+		Disable: useCases.NewDisableBrowserUpdatesUseCase(dependencies),
+	}
+}
+
+func InitApplyUpdateCommand(options domainUpdate.InstallOptions) *useCases.ApplyRestartRequestUseCase {
+	layout := domainUpdate.HelperLayout{DataDir: options.DataDir, BinaryPath: options.Binary}
+	files := update.NewNoFollowFilesystem()
+	return useCases.NewApplyRestartRequestUseCase(useCases.ApplyRestartRequestDependencies{
+		Requests: update.NewFSRestartRequestStore(files, layout.RestartRequestPath()),
+		Results:  update.NewFSResultStore(files, layout.ResultPath()),
+		Running:  update.NewJSONRunningInfoStore(filepath.Join(options.DataDir, domainUpdate.RunningInfoFileName)),
+		Files:    files,
+		Service:  update.NewSystemctlControl(options.Service),
+		Health:   update.NewHTTPHealthChecker(options.Port),
+		Verifier: update.NewEd25519SignatureVerifier(releasePublicKey()),
+		Clock:    update.NewSystemClock(),
+		Logger:   log.Default(),
+		Layout:   layout,
+		Platform: domainUpdate.Platform{OS: runtime.GOOS, Arch: runtime.GOARCH},
+	})
+}

api/handlers/activity/activityHandler.go

@@ -0,0 +1,249 @@
+package activity
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/audit"
+	"RenewCMS/internal/domain/role"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/url"
+	"strconv"
+	"time"
+)
+
+const (
+	csvContentType        = "text/csv; charset=utf-8"
+	csvContentDisposition = `attachment; filename="activity.csv"`
+)
+
+type Handler struct {
+	ListUseCase    *useCases.ListActivityUseCase
+	SummaryUseCase *useCases.GetActivitySummaryUseCase
+	ExportUseCase  *useCases.ExportActivityUseCase
+}
+
+type filterQuery struct {
+	Q        string `validate:"max=200"`
+	Actor    string `validate:"max=40"`
+	Category string `validate:"omitempty,oneof=articles media users api_keys auth system sites authors"`
+	Outcome  string `validate:"omitempty,oneof=all success failed"`
+	Security string `validate:"omitempty,oneof=true"`
+	Range    string `validate:"omitempty,oneof=today 7d 30d all custom"`
+	From     string `validate:"max=10"`
+	To       string `validate:"max=10"`
+}
+
+type listQuery struct {
+	filterQuery
+	Page int `validate:"gte=1"`
+	Size int `validate:"oneof=5 25 50 100"`
+}
+
+type actorResponse struct {
+	Type audit.ActorType `json:"type"`
+	ID   *uint32         `json:"id"`
+	Name string          `json:"name"`
+}
+
+type targetResponse struct {
+	Type   string `json:"type"`
+	ID     string `json:"id"`
+	Name   string `json:"name"`
+	Exists bool   `json:"exists"`
+}
+
+type itemResponse struct {
+	ID            uint64          `json:"id"`
+	CreatedAt     time.Time       `json:"created_at"`
+	Action        string          `json:"action"`
+	Category      audit.Category  `json:"category"`
+	Actor         actorResponse   `json:"actor"`
+	Target        *targetResponse `json:"target"`
+	Outcome       audit.Outcome   `json:"outcome"`
+	FailureReason *string         `json:"failure_reason"`
+	Security      bool            `json:"security"`
+	Source        audit.Source    `json:"source"`
+	IP            *string         `json:"ip"`
+	UserAgent     *string         `json:"user_agent"`
+	Params        map[string]any  `json:"params"`
+	Changes       []audit.Change  `json:"changes"`
+}
+
+type listResponse struct {
+	Items []itemResponse `json:"items"`
+	Total int            `json:"total"`
+	Page  int            `json:"page"`
+	Size  int            `json:"size"`
+}
+
+func NewHandler(list *useCases.ListActivityUseCase, summary *useCases.GetActivitySummaryUseCase, export *useCases.ExportActivityUseCase) *Handler {
+	return &Handler{ListUseCase: list, SummaryUseCase: summary, ExportUseCase: export}
+}
+
+func readFilterQuery(values url.Values) filterQuery {
+	return filterQuery{
+		Q:        values.Get("q"),
+		Actor:    values.Get("actor"),
+		Category: values.Get("category"),
+		Outcome:  values.Get("outcome"),
+		Security: values.Get("security"),
+		Range:    values.Get("range"),
+		From:     values.Get("from"),
+		To:       values.Get("to"),
+	}
+}
+
+func readListQuery(values url.Values) (listQuery, error) {
+	page, err := intParam(values, "page", 1)
+	if err != nil {
+		return listQuery{}, err
+	}
+	size, err := intParam(values, "size", 25)
+	if err != nil {
+		return listQuery{}, err
+	}
+	return listQuery{filterQuery: readFilterQuery(values), Page: page, Size: size}, nil
+}
+
+func intParam(values url.Values, name string, fallback int) (int, error) {
+	if !values.Has(name) {
+		return fallback, nil
+	}
+	return strconv.Atoi(values.Get(name))
+}
+
+func toActivityQuery(query filterQuery) useCases.ActivityQuery {
+	return useCases.ActivityQuery{
+		Q:        query.Q,
+		Actor:    query.Actor,
+		Category: query.Category,
+		Outcome:  query.Outcome,
+		Security: query.Security,
+		Range:    query.Range,
+		From:     query.From,
+		To:       query.To,
+	}
+}
+
+func writeActivityError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, audit.ErrInvalidFilter):
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, audit.ErrActorNotAllowed):
+		access.WriteMissingPermission(w, role.KeyActivityView)
+	case access.WriteIfMissingPermission(w, err):
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	query, err := readListQuery(r.URL.Query())
+	if err != nil || validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	viewerId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	activityQuery := toActivityQuery(query.filterQuery)
+	activityQuery.Page, activityQuery.Size = query.Page, query.Size
+	page, err := h.ListUseCase.ListActivity(useCases.ListActivityCommand{ViewerID: viewerId, Grants: access.Grants(r), Query: activityQuery})
+	if err != nil {
+		writeActivityError(w, err)
+		return
+	}
+
+	items := make([]itemResponse, 0, len(page.Items))
+	for _, entry := range page.Items {
+		items = append(items, toItemResponse(entry))
+	}
+	writeJSON(w, listResponse{Items: items, Total: page.Total, Page: page.Page, Size: page.Size})
+}
+
+func toItemResponse(entry useCases.ActivityEntry) itemResponse {
+	event := entry.Event
+	item := itemResponse{
+		ID:            event.ID,
+		CreatedAt:     event.CreatedAt,
+		Action:        event.Action,
+		Category:      event.Category,
+		Actor:         actorResponse{Type: event.Actor.Type, ID: event.Actor.ID, Name: event.Actor.Name},
+		Outcome:       event.Outcome,
+		FailureReason: event.FailureReason,
+		Security:      event.Security,
+		Source:        event.Source,
+		IP:            event.IP,
+		UserAgent:     event.UserAgent,
+		Params:        event.Params,
+		Changes:       event.Changes,
+	}
+	if item.Params == nil {
+		item.Params = map[string]any{}
+	}
+	if item.Changes == nil {
+		item.Changes = []audit.Change{}
+	}
+	if event.Target.Type != "" {
+		item.Target = &targetResponse{Type: event.Target.Type, ID: event.Target.ID, Name: event.Target.Name, Exists: entry.TargetExists}
+	}
+	return item
+}
+
+func (h *Handler) Summary(w http.ResponseWriter, r *http.Request) {
+	query := readFilterQuery(r.URL.Query())
+	if validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	summary, err := h.SummaryUseCase.GetActivitySummary(toActivityQuery(query))
+	if err != nil {
+		writeActivityError(w, err)
+		return
+	}
+	writeJSON(w, summary)
+}
+
+func (h *Handler) Export(w http.ResponseWriter, r *http.Request) {
+	query := readFilterQuery(r.URL.Query())
+	if validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	viewerId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	prepared, err := h.ExportUseCase.Prepare(useCases.ExportActivityCommand{ViewerID: viewerId, Grants: access.Grants(r), Query: toActivityQuery(query)})
+	if err != nil {
+		writeActivityError(w, err)
+		return
+	}
+
+	w.Header().Set("Content-Type", csvContentType)
+	w.Header().Set("Content-Disposition", csvContentDisposition)
+	w.Header().Set("Cache-Control", "no-store")
+	_ = prepared.WriteCSV(w)
+}
+
+func writeJSON(w http.ResponseWriter, payload any) {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}

api/handlers/apikey/apiKeyHandler.go

@@ -0,0 +1,181 @@
+package apikey
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	validator "RenewCMS/api/pkg/validator"
+	domain "RenewCMS/internal/domain/apikey"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	CreateUseCase *useCases.CreateAPIKeyUseCase
+	ListUseCase   *useCases.ListAPIKeysUseCase
+	RevokeUseCase *useCases.RevokeAPIKeyUseCase
+}
+
+type CreateAPIKeyRequest struct {
+	Name      string     `json:"name" validate:"required,max=60"`
+	ExpiresAt *time.Time `json:"expires_at"`
+}
+
+type createdKeyResponse struct {
+	ID        uint32     `json:"id"`
+	Name      string     `json:"name"`
+	Prefix    string     `json:"prefix"`
+	Key       string     `json:"key"`
+	CreatedAt time.Time  `json:"created_at"`
+	ExpiresAt *time.Time `json:"expires_at"`
+}
+
+type keyListItem struct {
+	ID            uint32        `json:"id"`
+	UserID        uint32        `json:"user_id"`
+	Name          string        `json:"name"`
+	Prefix        string        `json:"prefix"`
+	Status        domain.Status `json:"status"`
+	CreatedAt     time.Time     `json:"created_at"`
+	LastUsedAt    *time.Time    `json:"last_used_at"`
+	ExpiresAt     *time.Time    `json:"expires_at"`
+	RevokedAt     *time.Time    `json:"revoked_at"`
+	CreatedByName *string       `json:"created_by_name,omitempty"`
+}
+
+func NewHandler(create *useCases.CreateAPIKeyUseCase, list *useCases.ListAPIKeysUseCase, revoke *useCases.RevokeAPIKeyUseCase) *Handler {
+	return &Handler{CreateUseCase: create, ListUseCase: list, RevokeUseCase: revoke}
+}
+
+func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
+	var request CreateAPIKeyRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	created, err := h.CreateUseCase.CreateAPIKey(r.Context(), useCases.CreateAPIKeyCommand{
+		UserID:    userId,
+		Name:      request.Name,
+		ExpiresAt: request.ExpiresAt,
+	})
+	if err != nil {
+		if errors.Is(err, domain.ErrExpiryNotInFuture) {
+			http.Error(w, apperr.APIKeyExpiryErrorMessage, http.StatusBadRequest)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	body, err := json.Marshal(createdKeyResponse{
+		ID:        created.Key.ID,
+		Name:      created.Key.Name,
+		Prefix:    created.Key.Prefix,
+		Key:       created.RawKey,
+		CreatedAt: created.Key.CreatedAt,
+		ExpiresAt: created.Key.ExpiresAt,
+	})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	w.WriteHeader(http.StatusCreated)
+	_, _ = w.Write(body)
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	entries, err := h.ListUseCase.ListAPIKeys(userId, access.Grants(r))
+	if err != nil {
+		if access.WriteIfMissingPermission(w, err) {
+			return
+		}
+		if errors.Is(err, user.ErrUserNotFound) {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	items := make([]keyListItem, 0, len(entries))
+	for _, entry := range entries {
+		key := entry.Key
+		item := keyListItem{
+			ID:         key.ID,
+			UserID:     key.UserID,
+			Name:       key.Name,
+			Prefix:     key.Prefix,
+			Status:     entry.Status,
+			CreatedAt:  key.CreatedAt,
+			LastUsedAt: key.LastUsedAt,
+			ExpiresAt:  key.ExpiresAt,
+			RevokedAt:  key.RevokedAt,
+		}
+		if entry.ListsCreator {
+			item.CreatedByName = &entry.CreatorName
+		}
+		items = append(items, item)
+	}
+
+	body, err := json.Marshal(items)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}
+
+func (h *Handler) Revoke(w http.ResponseWriter, r *http.Request) {
+	id, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	if err := h.RevokeUseCase.RevokeAPIKey(r.Context(), userId, uint32(id), access.Grants(r)); err != nil {
+		switch {
+		case access.WriteIfMissingPermission(w, err):
+		case errors.Is(err, domain.ErrAPIKeyNotFound):
+			http.Error(w, apperr.APIKeyNotFoundErrorMessage, http.StatusNotFound)
+		case errors.Is(err, user.ErrUserNotFound):
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		default:
+			http.Error(w, "Internal server error", http.StatusInternalServerError)
+		}
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

api/handlers/article/articleHandler.go

@@ -0,0 +1,637 @@
+package article
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	domain "RenewCMS/internal/domain/article"
+	"RenewCMS/internal/domain/author"
+	"RenewCMS/internal/domain/image"
+	"RenewCMS/internal/domain/site"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"net/url"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	playground "github.com/go-playground/validator/v10"
+)
+
+type Handler struct {
+	CreateUseCase *useCases.CreateArticleUseCase
+	GetUseCase    *useCases.GetArticleUseCase
+	ListUseCase   *useCases.ListArticlesUseCase
+	DeleteUseCase *useCases.DeleteArticleUseCase
+	UpdateUseCase *useCases.UpdateArticleUseCase
+}
+
+type PostArticle struct {
+	Title string `json:"title" validate:"required,min=3,max=200"`
+	Body  string `json:"body"`
+}
+
+func NewHandler(create *useCases.CreateArticleUseCase, get *useCases.GetArticleUseCase, list *useCases.ListArticlesUseCase, delete *useCases.DeleteArticleUseCase, update *useCases.UpdateArticleUseCase) *Handler {
+	return &Handler{
+		CreateUseCase: create,
+		GetUseCase:    get,
+		ListUseCase:   list,
+		DeleteUseCase: delete,
+		UpdateUseCase: update,
+	}
+}
+
+type baseArticleResponse struct {
+	ID         uint32            `json:"id"`
+	Title      string            `json:"title"`
+	Body       json.RawMessage   `json:"body"`
+	BodyFormat domain.BodyFormat `json:"body_format"`
+	IsOnline   bool              `json:"is_online"`
+	SiteID     uint32            `json:"site_id"`
+	CreatedBy  *uint32           `json:"created_by,omitempty"`
+	Authors    []author.Byline   `json:"authors"`
+	CreatedAt  time.Time         `json:"created_at"`
+	UpdatedAt  time.Time         `json:"updated_at"`
+}
+
+type articleResponse struct {
+	baseArticleResponse
+	Slug              string   `json:"slug"`
+	Excerpt           string   `json:"excerpt"`
+	SEOTitle          string   `json:"seo_title"`
+	SEODescription    string   `json:"seo_description"`
+	CoverImageID      *uint32  `json:"cover_image_id"`
+	CoverImageAlt     string   `json:"cover_image_alt"`
+	SocialTitle       string   `json:"social_title"`
+	SocialDescription string   `json:"social_description"`
+	SocialImageID     *uint32  `json:"social_image_id"`
+	CanonicalURL      string   `json:"canonical_url"`
+	Noindex           bool     `json:"noindex"`
+	SEODismissed      []string `json:"seo_dismissed"`
+}
+
+type listItemResponse struct {
+	baseArticleResponse
+	Excerpt        string `json:"excerpt"`
+	Slug           string `json:"slug"`
+	SEOStatus      string `json:"seo_status"`
+	SEOSuggestions int    `json:"seo_suggestions"`
+}
+
+func creatorFor(article domain.Article, viewer access.Caller) *uint32 {
+	if viewer.UserID == 0 {
+		return nil
+	}
+	createdBy := article.CreatedBy
+	return &createdBy
+}
+
+func toBaseResponse(article domain.Article, format domain.BodyFormat, viewer access.Caller) (baseArticleResponse, error) {
+	body := json.RawMessage(article.Body)
+	if format != domain.BodyFormatJSON {
+		encoded, err := json.Marshal(article.Body)
+		if err != nil {
+			return baseArticleResponse{}, err
+		}
+		body = encoded
+	}
+	authors := article.Authors
+	if authors == nil {
+		authors = []author.Byline{}
+	}
+	return baseArticleResponse{
+		ID:         article.ID,
+		Title:      article.Title,
+		Body:       body,
+		BodyFormat: format,
+		IsOnline:   article.IsOnline,
+		SiteID:     article.SiteID,
+		CreatedBy:  creatorFor(article, viewer),
+		Authors:    authors,
+		CreatedAt:  article.CreatedAt,
+		UpdatedAt:  article.UpdatedAt,
+	}, nil
+}
+
+func toArticleResponse(article domain.Article, format domain.BodyFormat, viewer access.Caller) (articleResponse, error) {
+	base, err := toBaseResponse(article, format, viewer)
+	if err != nil {
+		return articleResponse{}, err
+	}
+	dismissed := article.SEODismissed
+	if dismissed == nil {
+		dismissed = []string{}
+	}
+	return articleResponse{
+		baseArticleResponse: base,
+		Slug:                article.Slug,
+		Excerpt:             article.Excerpt,
+		SEOTitle:            article.SEOTitle,
+		SEODescription:      article.SEODescription,
+		CoverImageID:        article.CoverImageID,
+		CoverImageAlt:       article.CoverImageAlt,
+		SocialTitle:         article.SocialTitle,
+		SocialDescription:   article.SocialDescription,
+		SocialImageID:       article.SocialImageID,
+		CanonicalURL:        article.CanonicalURL,
+		Noindex:             article.Noindex,
+		SEODismissed:        dismissed,
+	}, nil
+}
+
+func toListItemResponse(article domain.Article, summary domain.SEOSummary, format domain.BodyFormat, viewer access.Caller) (listItemResponse, error) {
+	base, err := toBaseResponse(article, format, viewer)
+	if err != nil {
+		return listItemResponse{}, err
+	}
+	return listItemResponse{baseArticleResponse: base, Excerpt: article.Excerpt, Slug: article.Slug, SEOStatus: summary.Status, SEOSuggestions: summary.Suggestions}, nil
+}
+
+func encodeArticle(article domain.Article, format domain.BodyFormat, viewer access.Caller) ([]byte, error) {
+	response, err := toArticleResponse(article, format, viewer)
+	if err != nil {
+		return nil, err
+	}
+	return json.Marshal(response)
+}
+
+func parseBodyFormat(w http.ResponseWriter, r *http.Request) (domain.BodyFormat, bool) {
+	format, err := domain.ParseBodyFormat(r.URL.Query().Get("format"))
+	if err != nil {
+		http.Error(w, apperr.ArticleBodyFormatErrorMessage, http.StatusBadRequest)
+		return "", false
+	}
+	return format, true
+}
+
+func parseArticleId(r *http.Request) (uint32, error) {
+	id, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	return uint32(id), err
+}
+
+func (h *Handler) GetArticle(w http.ResponseWriter, r *http.Request) {
+	id, err := parseArticleId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	format, ok := parseBodyFormat(w, r)
+	if !ok {
+		return
+	}
+
+	article, err := h.GetUseCase.GetArticle(id, format, access.CallerOf(r))
+	if err != nil {
+		if errors.Is(err, domain.ErrArticleNotFound) {
+			http.Error(w, apperr.ArticleNotFoundErrorMessage, http.StatusNotFound)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	articleJson, err := encodeArticle(article, format, access.CallerOf(r))
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+
+	if _, err := w.Write(articleJson); err != nil {
+		fmt.Printf("Failed to write response: %v", err)
+	}
+}
+
+func (h *Handler) PostArticle(w http.ResponseWriter, r *http.Request) {
+	format, ok := parseBodyFormat(w, r)
+	if !ok {
+		return
+	}
+
+	var localArticle PostArticle
+	if err := json.NewDecoder(r.Body).Decode(&localArticle); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	if err := validator.Validate.Struct(localArticle); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	createdArticle, err := h.CreateUseCase.CreateArticle(r.Context(), useCases.CreateArticleCommand{
+		Title:  localArticle.Title,
+		Body:   localArticle.Body,
+		Format: format,
+		Caller: access.CallerOf(r),
+	})
+	if err != nil {
+		if errors.Is(err, domain.ErrInvalidTitle) {
+			http.Error(w, apperr.ArticleTitleErrorMessage, http.StatusBadRequest)
+			return
+		}
+		if !writeKnownArticleError(w, err) {
+			http.Error(w, "Failed to create article", http.StatusInternalServerError)
+		}
+		return
+	}
+
+	writeArticleJsonResponse(w, r, http.StatusCreated, createdArticle, format)
+}
+
+func writeArticleErrorResponse(w http.ResponseWriter, err error) {
+	if !writeKnownArticleError(w, err) {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func writeKnownArticleError(w http.ResponseWriter, err error) bool {
+	if access.WriteIfMissingPermission(w, err) {
+		return true
+	}
+	if errors.Is(err, domain.ErrArticleNotFound) {
+		http.Error(w, apperr.ArticleNotFoundErrorMessage, http.StatusNotFound)
+		return true
+	}
+	if errors.Is(err, site.ErrSiteNotFound) {
+		http.Error(w, apperr.SiteNotFoundErrorMessage, http.StatusNotFound)
+		return true
+	}
+	if errors.Is(err, author.ErrAuthorNotFound) {
+		http.Error(w, apperr.AuthorNotFoundErrorMessage, http.StatusNotFound)
+		return true
+	}
+	if errors.Is(err, domain.ErrSlugTaken) {
+		writeSlugTaken(w, err)
+		return true
+	}
+	if errors.Is(err, domain.ErrInvalidSlug) {
+		http.Error(w, apperr.InvalidSlugErrorMessage, http.StatusBadRequest)
+		return true
+	}
+	if errors.Is(err, domain.ErrInvalidCanonicalURL) {
+		http.Error(w, apperr.InvalidURLErrorMessage, http.StatusUnprocessableEntity)
+		return true
+	}
+	if errors.Is(err, image.ErrImageNotFound) {
+		http.Error(w, apperr.ArticleImageNotFoundErrorMessage, http.StatusBadRequest)
+		return true
+	}
+	return false
+}
+
+func writeSlugTaken(w http.ResponseWriter, err error) {
+	var conflict *domain.SlugTakenError
+	if errors.As(err, &conflict) && conflict.Suggestion != "" {
+		w.Header().Set(apperr.SlugSuggestionHeader, conflict.Suggestion)
+	}
+	http.Error(w, apperr.ArticleSlugTakenErrorMessage, http.StatusConflict)
+}
+
+func writeValidationError(w http.ResponseWriter, err error) {
+	var failures playground.ValidationErrors
+	if errors.As(err, &failures) {
+		for _, failure := range failures {
+			if failure.Tag() == validator.ArticleSlugTag {
+				http.Error(w, apperr.InvalidSlugErrorMessage, http.StatusBadRequest)
+				return
+			}
+		}
+	}
+	http.Error(w, err.Error(), http.StatusBadRequest)
+}
+
+func writeArticleJsonResponse(w http.ResponseWriter, r *http.Request, status int, article domain.Article, format domain.BodyFormat) {
+	articleJson, err := encodeArticle(article, format, access.CallerOf(r))
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+
+	if status != http.StatusOK {
+		w.WriteHeader(status)
+	}
+	if _, err := w.Write(articleJson); err != nil {
+		log.Printf("Failed to write response: %v", err)
+	}
+}
+
+func (h *Handler) setIsOnline(w http.ResponseWriter, r *http.Request, isOnline bool) {
+	id, err := parseArticleId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	format, ok := parseBodyFormat(w, r)
+	if !ok {
+		return
+	}
+
+	updatedArticle, err := h.UpdateUseCase.UpdateIsOnline(r.Context(), id, access.CallerOf(r), isOnline, format)
+	if err != nil {
+		writeArticleErrorResponse(w, err)
+		return
+	}
+
+	writeArticleJsonResponse(w, r, http.StatusOK, updatedArticle, format)
+}
+
+type optionalImageID struct {
+	Set   bool
+	Value *uint32 `validate:"omitempty,gte=1"`
+}
+
+func (o *optionalImageID) UnmarshalJSON(data []byte) error {
+	o.Set = true
+	if string(data) == "null" {
+		o.Value = nil
+		return nil
+	}
+	var value uint32
+	if err := json.Unmarshal(data, &value); err != nil {
+		return err
+	}
+	o.Value = &value
+	return nil
+}
+
+func (o optionalImageID) toNullable() domain.Nullable[uint32] {
+	return domain.Nullable[uint32]{Set: o.Set, Value: o.Value}
+}
+
+type UpdateArticleBody struct {
+	Body              *string         `json:"body"`
+	SiteID            *uint32         `json:"site_id" validate:"omitempty,gte=1"`
+	AuthorIDs         *[]uint32       `json:"author_ids" validate:"omitempty,dive,gte=1"`
+	Slug              *string         `json:"slug" validate:"omitempty,articleslug"`
+	Excerpt           *string         `json:"excerpt" validate:"omitempty,max=300"`
+	SEOTitle          *string         `json:"seo_title" validate:"omitempty,max=120"`
+	SEODescription    *string         `json:"seo_description" validate:"omitempty,max=320"`
+	CoverImageID      optionalImageID `json:"cover_image_id"`
+	CoverImageAlt     *string         `json:"cover_image_alt" validate:"omitempty,max=200"`
+	SocialTitle       *string         `json:"social_title" validate:"omitempty,max=120"`
+	SocialDescription *string         `json:"social_description" validate:"omitempty,max=320"`
+	SocialImageID     optionalImageID `json:"social_image_id"`
+	CanonicalURL      *string         `json:"canonical_url" validate:"omitempty,max=2048"`
+	Noindex           *bool           `json:"noindex"`
+	SEODismissed      *[]string       `json:"seo_dismissed" validate:"omitempty,dive,oneof=title_long title_empty desc_short desc_long cover_alt cover_none slug_long no_au no_h body_alt short"`
+}
+
+var nonNullableArticleFields = []string{"body", "site_id", "author_ids", "slug", "excerpt", "seo_title", "seo_description", "cover_image_alt", "social_title", "social_description", "canonical_url", "noindex", "seo_dismissed"}
+
+var nullableArticleFields = []string{"cover_image_id", "social_image_id"}
+
+func hasDuplicates(ids []uint32) bool {
+	seen := make(map[uint32]bool, len(ids))
+	for _, id := range ids {
+		if seen[id] {
+			return true
+		}
+		seen[id] = true
+	}
+	return false
+}
+
+func countKnownFields(fields map[string]json.RawMessage, nonNullable []string) (int, bool) {
+	known := 0
+	for name, value := range fields {
+		switch {
+		case slices.Contains(nonNullable, name):
+			if string(value) == "null" {
+				return 0, false
+			}
+			known++
+		case slices.Contains(nullableArticleFields, name):
+			known++
+		}
+	}
+	return known, true
+}
+
+func readUpdateArticleBody(r *http.Request) (UpdateArticleBody, bool) {
+	raw, err := io.ReadAll(r.Body)
+	if err != nil {
+		return UpdateArticleBody{}, false
+	}
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &fields); err != nil {
+		return UpdateArticleBody{}, false
+	}
+	known, ok := countKnownFields(fields, nonNullableArticleFields)
+	if !ok || known == 0 {
+		return UpdateArticleBody{}, false
+	}
+	var request UpdateArticleBody
+	if err := json.Unmarshal(raw, &request); err != nil {
+		return UpdateArticleBody{}, false
+	}
+	if request.AuthorIDs != nil && hasDuplicates(*request.AuthorIDs) {
+		return UpdateArticleBody{}, false
+	}
+	return request, true
+}
+
+func (h *Handler) UpdateArticleBody(w http.ResponseWriter, r *http.Request) {
+	id, err := parseArticleId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	format, ok := parseBodyFormat(w, r)
+	if !ok {
+		return
+	}
+
+	request, ok := readUpdateArticleBody(r)
+	if !ok {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	if err := validator.Validate.Struct(request); err != nil {
+		writeValidationError(w, err)
+		return
+	}
+
+	updatedArticle, err := h.UpdateUseCase.Update(r.Context(), id, access.CallerOf(r), useCases.UpdateArticleCommand{
+		Body:              request.Body,
+		SiteID:            request.SiteID,
+		AuthorIDs:         request.AuthorIDs,
+		Slug:              request.Slug,
+		Excerpt:           request.Excerpt,
+		SEOTitle:          request.SEOTitle,
+		SEODescription:    request.SEODescription,
+		CoverImageID:      request.CoverImageID.toNullable(),
+		CoverImageAlt:     request.CoverImageAlt,
+		SocialTitle:       request.SocialTitle,
+		SocialDescription: request.SocialDescription,
+		SocialImageID:     request.SocialImageID.toNullable(),
+		CanonicalURL:      request.CanonicalURL,
+		Noindex:           request.Noindex,
+		SEODismissed:      request.SEODismissed,
+		Format:            format,
+	})
+	if err != nil {
+		writeArticleErrorResponse(w, err)
+		return
+	}
+
+	writeArticleJsonResponse(w, r, http.StatusOK, updatedArticle, format)
+}
+
+func (h *Handler) PublishArticle(w http.ResponseWriter, r *http.Request) {
+	h.setIsOnline(w, r, true)
+}
+
+func (h *Handler) UnpublishArticle(w http.ResponseWriter, r *http.Request) {
+	h.setIsOnline(w, r, false)
+}
+
+const (
+	defaultListPage = 1
+	defaultListSize = 25
+)
+
+type listQuery struct {
+	Page   int     `validate:"gte=1"`
+	Size   int     `validate:"oneof=5 25 50 100"`
+	Q      string  `validate:"max=200"`
+	Status string  `validate:"omitempty,oneof=online draft"`
+	Site   *string `validate:"omitempty,min=1"`
+	SEO    string  `validate:"omitempty,oneof=ready suggestions hidden"`
+	Sort   string  `validate:"oneof=title:asc title:desc status:asc status:desc created_at:asc created_at:desc updated_at:asc updated_at:desc"`
+}
+
+const defaultListSort = "updated_at:desc"
+
+func parseSort(value string) domain.Sort {
+	field, direction, _ := strings.Cut(value, ":")
+	return domain.Sort{Field: domain.SortField(field), Direction: domain.SortDirection(direction)}
+}
+
+type listResponse struct {
+	Items  []listItemResponse `json:"items"`
+	Total  int                `json:"total"`
+	Page   int                `json:"page"`
+	Size   int                `json:"size"`
+	Counts domain.Counts      `json:"counts"`
+}
+
+func intQueryParam(values url.Values, name string, fallback int) (int, error) {
+	if !values.Has(name) {
+		return fallback, nil
+	}
+	return strconv.Atoi(values.Get(name))
+}
+
+func readListQuery(values url.Values) (listQuery, error) {
+	page, err := intQueryParam(values, "page", defaultListPage)
+	if err != nil {
+		return listQuery{}, err
+	}
+	size, err := intQueryParam(values, "size", defaultListSize)
+	if err != nil {
+		return listQuery{}, err
+	}
+	status := values.Get("status")
+	if values.Has("status") && status == "" {
+		return listQuery{}, errors.New("empty status")
+	}
+	sortValue := defaultListSort
+	if values.Has("sort") {
+		sortValue = values.Get("sort")
+	}
+	var siteKey *string
+	if values.Has("site") {
+		key := values.Get("site")
+		if key == "" {
+			return listQuery{}, errors.New("empty site")
+		}
+		siteKey = &key
+	}
+	seoStatus := values.Get("seo")
+	if values.Has("seo") && seoStatus == "" {
+		return listQuery{}, errors.New("empty seo")
+	}
+	return listQuery{Page: page, Size: size, Q: values.Get("q"), Status: status, Sort: sortValue, Site: siteKey, SEO: seoStatus}, nil
+}
+
+func (h *Handler) ListArticles(w http.ResponseWriter, r *http.Request) {
+	format, ok := parseBodyFormat(w, r)
+	if !ok {
+		return
+	}
+
+	query, err := readListQuery(r.URL.Query())
+	if err != nil || validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	page, err := h.ListUseCase.ListArticlesPage(useCases.ListArticlesCommand{
+		Format:  format,
+		Caller:  access.CallerOf(r),
+		Page:    query.Page,
+		Size:    query.Size,
+		Q:       query.Q,
+		Status:  query.Status,
+		Sort:    parseSort(query.Sort),
+		SiteKey: query.Site,
+		SEO:     query.SEO,
+	})
+	if err != nil {
+		http.Error(w, "Failed to retrieve articles", http.StatusInternalServerError)
+		return
+	}
+
+	responses := make([]listItemResponse, 0, len(page.Items))
+	for _, article := range page.Items {
+		response, err := toListItemResponse(article, page.SEO[article.ID], format, access.CallerOf(r))
+		if err != nil {
+			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+			return
+		}
+		responses = append(responses, response)
+	}
+
+	articlesJson, err := json.Marshal(listResponse{Items: responses, Total: page.Total, Page: page.Page, Size: page.Size, Counts: page.Counts})
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+
+	if _, err := w.Write(articlesJson); err != nil {
+		log.Printf("Failed to write response: %v", err)
+	}
+}
+
+func (h *Handler) DeleteArticle(w http.ResponseWriter, r *http.Request) {
+	id, err := parseArticleId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	if err := h.DeleteUseCase.DeleteArticle(r.Context(), id, access.CallerOf(r)); err != nil {
+		if errors.Is(err, domain.ErrArticleNotFound) {
+			http.Error(w, apperr.ArticleNotFoundErrorMessage, http.StatusNotFound)
+			return
+		}
+		if access.WriteIfMissingPermission(w, err) {
+			return
+		}
+		http.Error(w, "Failed to delete article", http.StatusInternalServerError)
+		return
+	}
+
+	w.WriteHeader(http.StatusNoContent)
+}

api/handlers/article/seoHandler.go

@@ -0,0 +1,127 @@
+package article
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/infrastructure/useCases"
+	"bytes"
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+)
+
+type SEOHandler struct {
+	ResolveUseCase *useCases.ResolveArticleSEOUseCase
+	CheckUseCase   *useCases.CheckArticleSEOUseCase
+}
+
+func NewSEOHandler(resolve *useCases.ResolveArticleSEOUseCase, check *useCases.CheckArticleSEOUseCase) *SEOHandler {
+	return &SEOHandler{ResolveUseCase: resolve, CheckUseCase: check}
+}
+
+type CheckArticleSEOBody struct {
+	Body              *string         `json:"body"`
+	Slug              *string         `json:"slug" validate:"omitempty,articleslug"`
+	Excerpt           *string         `json:"excerpt" validate:"omitempty,max=300"`
+	SEOTitle          *string         `json:"seo_title" validate:"omitempty,max=120"`
+	SEODescription    *string         `json:"seo_description" validate:"omitempty,max=320"`
+	CoverImageID      optionalImageID `json:"cover_image_id"`
+	CoverImageAlt     *string         `json:"cover_image_alt" validate:"omitempty,max=200"`
+	SocialTitle       *string         `json:"social_title" validate:"omitempty,max=120"`
+	SocialDescription *string         `json:"social_description" validate:"omitempty,max=320"`
+	SocialImageID     optionalImageID `json:"social_image_id"`
+	CanonicalURL      *string         `json:"canonical_url" validate:"omitempty,max=2048"`
+	Noindex           *bool           `json:"noindex"`
+	SEODismissed      *[]string       `json:"seo_dismissed" validate:"omitempty,dive,oneof=title_long title_empty desc_short desc_long cover_alt cover_none slug_long no_au no_h body_alt short"`
+}
+
+var checkNonNullableFields = []string{"body", "slug", "excerpt", "seo_title", "seo_description", "cover_image_alt", "social_title", "social_description", "canonical_url", "noindex", "seo_dismissed"}
+
+func readCheckBody(r *http.Request) (CheckArticleSEOBody, bool) {
+	raw, err := io.ReadAll(r.Body)
+	if err != nil {
+		return CheckArticleSEOBody{}, false
+	}
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &fields); err != nil || fields == nil {
+		return CheckArticleSEOBody{}, false
+	}
+	known, ok := countKnownFields(fields, checkNonNullableFields)
+	if !ok || known != len(fields) {
+		return CheckArticleSEOBody{}, false
+	}
+	var request CheckArticleSEOBody
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&request); err != nil {
+		return CheckArticleSEOBody{}, false
+	}
+	return request, true
+}
+
+func (h *SEOHandler) Resolve(w http.ResponseWriter, r *http.Request) {
+	id, err := parseArticleId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	resolved, err := h.ResolveUseCase.Resolve(id, access.CallerOf(r))
+	if err != nil {
+		writeArticleErrorResponse(w, err)
+		return
+	}
+	writeSEOJson(w, resolved)
+}
+
+func (h *SEOHandler) Check(w http.ResponseWriter, r *http.Request) {
+	id, err := parseArticleId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	request, ok := readCheckBody(r)
+	if !ok {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		writeValidationError(w, err)
+		return
+	}
+
+	checked, err := h.CheckUseCase.Check(id, access.CallerOf(r), useCases.CheckArticleSEOCommand{
+		Body:              request.Body,
+		Slug:              request.Slug,
+		Excerpt:           request.Excerpt,
+		SEOTitle:          request.SEOTitle,
+		SEODescription:    request.SEODescription,
+		CoverImageID:      request.CoverImageID.toNullable(),
+		CoverImageAlt:     request.CoverImageAlt,
+		SocialTitle:       request.SocialTitle,
+		SocialDescription: request.SocialDescription,
+		SocialImageID:     request.SocialImageID.toNullable(),
+		CanonicalURL:      request.CanonicalURL,
+		Noindex:           request.Noindex,
+		SEODismissed:      request.SEODismissed,
+	})
+	if err != nil {
+		writeArticleErrorResponse(w, err)
+		return
+	}
+	writeSEOJson(w, checked)
+}
+
+func writeSEOJson(w http.ResponseWriter, payload any) {
+	encoded, err := json.Marshal(payload)
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+	if _, err := w.Write(encoded); err != nil {
+		log.Printf("Failed to write response: %v", err)
+	}
+}

api/handlers/auth/acceptInviteHandler.go

@@ -0,0 +1,103 @@
+package auth
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/authtoken"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/invite"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+)
+
+type AcceptInviteHandler struct {
+	Token               *authtoken.Auth
+	GetInviteUseCase    *useCases.GetInviteUseCase
+	AcceptInviteUseCase *useCases.AcceptInviteUseCase
+	IsProduction        bool
+}
+
+type AcceptInviteRequest struct {
+	Code     string `json:"code" validate:"required"`
+	Username string `json:"username" validate:"required,min=3,max=20"`
+	Password string `json:"password" validate:"required,min=8"`
+}
+
+type inviteEmailResponse struct {
+	Email string `json:"email"`
+}
+
+func NewAcceptInviteHandler(getInvite *useCases.GetInviteUseCase, acceptInvite *useCases.AcceptInviteUseCase, token *authtoken.Auth, isProduction bool) *AcceptInviteHandler {
+	return &AcceptInviteHandler{
+		Token:               token,
+		GetInviteUseCase:    getInvite,
+		AcceptInviteUseCase: acceptInvite,
+		IsProduction:        isProduction,
+	}
+}
+
+func (h *AcceptInviteHandler) GetInvite(w http.ResponseWriter, r *http.Request) {
+	found, err := h.GetInviteUseCase.GetInvite(r.URL.Query().Get("c"))
+	if err != nil {
+		writeAcceptInviteError(w, err)
+		return
+	}
+
+	body, err := json.Marshal(inviteEmailResponse{Email: found.Email})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}
+
+func (h *AcceptInviteHandler) AcceptInvite(w http.ResponseWriter, r *http.Request) {
+	var request AcceptInviteRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	createdUser, err := h.AcceptInviteUseCase.AcceptInvite(r.Context(), useCases.AcceptInviteCommand{
+		Code:     request.Code,
+		Username: request.Username,
+		Password: request.Password,
+	})
+	if err != nil {
+		writeAcceptInviteError(w, err)
+		return
+	}
+
+	if err := setJwtCookie(w, h.Token, h.IsProduction, createdUser); err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	message, _ := json.Marshal(map[string]any{"message": "Invite accepted! HTTPonly jwt cookie created"})
+	_, _ = w.Write(message)
+}
+
+func writeAcceptInviteError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, invite.ErrInviteInvalid):
+		http.Error(w, apperr.InviteInvalidErrorMessage, http.StatusNotFound)
+	case errors.Is(err, invite.ErrInviteExpired):
+		http.Error(w, apperr.InviteExpiredErrorMessage, http.StatusGone)
+	case errors.Is(err, user.ErrUsernameTaken):
+		http.Error(w, apperr.UsernameTakenErrorMessage, http.StatusConflict)
+	case errors.Is(err, invite.ErrEmailHasAccount):
+		http.Error(w, apperr.EmailHasAccountErrorMessage, http.StatusConflict)
+	case errors.Is(err, user.ErrPasswordTooLong):
+		http.Error(w, apperr.PasswordTooLongErrorMessage, http.StatusBadRequest)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}

api/handlers/auth/emailChangeHandler.go

@@ -0,0 +1,151 @@
+package auth
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+)
+
+type EmailChangeHandler struct {
+	RequestUseCase *useCases.RequestEmailChangeUseCase
+	ResendUseCase  *useCases.ResendEmailChangeUseCase
+	CancelUseCase  *useCases.CancelEmailChangeUseCase
+	ConfirmUseCase *useCases.ConfirmEmailChangeUseCase
+}
+
+type RequestEmailChangeCredentials struct {
+	NewEmail        string `json:"new_email" validate:"required,max=255,inviteemail"`
+	CurrentPassword string `json:"current_password" validate:"required"`
+}
+
+type ConfirmEmailChangeCredentials struct {
+	Code string `json:"code" validate:"required"`
+}
+
+func NewEmailChangeHandler(request *useCases.RequestEmailChangeUseCase, resend *useCases.ResendEmailChangeUseCase, cancel *useCases.CancelEmailChangeUseCase, confirm *useCases.ConfirmEmailChangeUseCase) *EmailChangeHandler {
+	return &EmailChangeHandler{
+		RequestUseCase: request,
+		ResendUseCase:  resend,
+		CancelUseCase:  cancel,
+		ConfirmUseCase: confirm,
+	}
+}
+
+func (h *EmailChangeHandler) Request(w http.ResponseWriter, r *http.Request) {
+	var credentials RequestEmailChangeCredentials
+	if err := json.NewDecoder(r.Body).Decode(&credentials); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(credentials); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	pending, err := h.RequestUseCase.RequestEmailChange(r.Context(), useCases.RequestEmailChangeCommand{
+		UserID:          userId,
+		NewEmail:        credentials.NewEmail,
+		CurrentPassword: credentials.CurrentPassword,
+	})
+	if err != nil {
+		writeEmailChangeError(w, err)
+		return
+	}
+	writePendingEmail(w, pending)
+}
+
+func (h *EmailChangeHandler) Resend(w http.ResponseWriter, r *http.Request) {
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	pending, err := h.ResendUseCase.ResendEmailChange(r.Context(), userId)
+	if err != nil {
+		writeEmailChangeError(w, err)
+		return
+	}
+	writePendingEmail(w, pending)
+}
+
+func (h *EmailChangeHandler) Cancel(w http.ResponseWriter, r *http.Request) {
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	if err := h.CancelUseCase.CancelEmailChange(r.Context(), userId); err != nil {
+		writeEmailChangeError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (h *EmailChangeHandler) Confirm(w http.ResponseWriter, r *http.Request) {
+	var credentials ConfirmEmailChangeCredentials
+	if err := json.NewDecoder(r.Body).Decode(&credentials); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(credentials); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	email, err := h.ConfirmUseCase.ConfirmEmailChange(r.Context(), userId, credentials.Code)
+	if err != nil {
+		writeEmailChangeError(w, err)
+		return
+	}
+	body, err := json.Marshal(map[string]string{"email": email})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	_, _ = w.Write(body)
+}
+
+func writePendingEmail(w http.ResponseWriter, pending string) {
+	body, err := json.Marshal(map[string]string{"pending_email": pending})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	_, _ = w.Write(body)
+}
+
+func writeEmailChangeError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, user.ErrUserNotFound):
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+	case errors.Is(err, user.ErrWrongPassword):
+		http.Error(w, apperr.WrongPasswordErrorCode, http.StatusForbidden)
+	case errors.Is(err, user.ErrSameEmail):
+		http.Error(w, apperr.SameEmailErrorCode, http.StatusBadRequest)
+	case errors.Is(err, user.ErrNoPendingEmailChange):
+		http.Error(w, apperr.NoPendingEmailChangeErrorCode, http.StatusNotFound)
+	case errors.Is(err, user.ErrInvalidEmailChangeCode):
+		http.Error(w, apperr.InvalidEmailChangeCodeErrorCode, http.StatusForbidden)
+	case errors.Is(err, user.ErrEmailUnavailable):
+		http.Error(w, apperr.EmailUnavailableErrorCode, http.StatusConflict)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}

api/handlers/auth/loginHandler.go

@@ -0,0 +1,154 @@
+package auth
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/authtoken"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"time"
+)
+
+type LoginHandler struct {
+	Token               *authtoken.Auth
+	CreateUseCase       *useCases.CreateUserUseCase
+	AuthenticateUseCase *useCases.AuthenticateUserUseCase
+	IsProduction        bool
+}
+
+type RegisterCredentials struct {
+	Username string `json:"username" validate:"required,min=3,max=20"`
+	Password string `json:"password" validate:"required,min=8"`
+	Email    string `json:"email" validate:"required,email"`
+}
+
+type LoginCredentials struct {
+	Username string `json:"username" validate:"required,min=3,max=20"`
+	Password string `json:"password" validate:"required,min=8"`
+}
+
+func NewLoginHandler(token *authtoken.Auth, create *useCases.CreateUserUseCase, authenticate *useCases.AuthenticateUserUseCase, isProduction bool) *LoginHandler {
+	return &LoginHandler{
+		Token:               token,
+		CreateUseCase:       create,
+		AuthenticateUseCase: authenticate,
+		IsProduction:        isProduction,
+	}
+}
+
+func removeJwtCookie(w http.ResponseWriter, isProduction bool) {
+	http.SetCookie(w, authtoken.ExpiredCookie(isProduction))
+}
+
+func setJwtCookie(w http.ResponseWriter, token *authtoken.Auth, isProduction bool, u user.User) error {
+	tokenString, err := token.Encode(map[string]any{"user_id": u.ID, "token_version": u.TokenVersion})
+	if err != nil {
+		return err
+	}
+	http.SetCookie(w, &http.Cookie{
+		Name:     authtoken.CookieName,
+		Value:    tokenString,
+		Expires:  time.Now().Add(authtoken.SessionLifetime),
+		Secure:   isProduction,
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+		Path:     "/",
+	})
+	return nil
+}
+
+func (h *LoginHandler) SetJwtCookie(w *http.ResponseWriter, u user.User) error {
+	return setJwtCookie(*w, h.Token, h.IsProduction, u)
+}
+
+func (h *LoginHandler) Login(w http.ResponseWriter, r *http.Request) {
+	var credentials LoginCredentials
+
+	err := json.NewDecoder(r.Body).Decode(&credentials)
+	if err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	err = validator.Validate.Struct(credentials)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	dbUser, err := h.AuthenticateUseCase.Authenticate(r.Context(), credentials.Username, credentials.Password)
+	if err != nil {
+		http.Error(w, apperr.LogsErrorMessage, http.StatusForbidden)
+		return
+	}
+
+	_ = h.SetJwtCookie(&w, dbUser)
+
+	message, _ := json.Marshal(map[string]any{"message": "User logged in! HTTPonly jwt cookie created"})
+	_, _ = w.Write(message)
+}
+
+func (h *LoginHandler) Register(w http.ResponseWriter, r *http.Request) {
+	var credentials RegisterCredentials
+	err := json.NewDecoder(r.Body).Decode(&credentials)
+	if err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	err = validator.Validate.Struct(credentials)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	createdUser, err := h.CreateUseCase.CreateUser(r.Context(), useCases.CreateUserCommand{
+		Username: credentials.Username,
+		Password: credentials.Password,
+		Email:    credentials.Email,
+	})
+	if err != nil {
+		if errors.Is(err, user.ErrRegistrationClosed) {
+			http.Error(w, apperr.RegistrationClosedErrorMessage, http.StatusForbidden)
+			return
+		}
+		if errors.Is(err, user.ErrPasswordTooLong) {
+			http.Error(w, apperr.PasswordTooLongErrorMessage, http.StatusBadRequest)
+			return
+		}
+		http.Error(w, apperr.RegistrationFailedErrorMessage, http.StatusInternalServerError)
+		return
+	}
+
+	_ = h.SetJwtCookie(&w, createdUser)
+
+	message, _ := json.Marshal(map[string]any{"message": "User registered! HTTPonly jwt cookie created"})
+	_, _ = w.Write(message)
+}
+
+func (h *LoginHandler) RegistrationStatus(w http.ResponseWriter, _ *http.Request) {
+	open, err := h.CreateUseCase.IsRegistrationOpen()
+	if err != nil {
+		http.Error(w, apperr.RegistrationFailedErrorMessage, http.StatusInternalServerError)
+		return
+	}
+	body, _ := json.Marshal(map[string]bool{"open": open})
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}
+
+func (h *LoginHandler) Logout(w http.ResponseWriter, r *http.Request) {
+	removeJwtCookie(w, h.IsProduction)
+	if claims, err := authtoken.FromContext(r.Context()); err == nil {
+		if err := h.Token.Revoke(claims); err != nil {
+			http.Error(w, "Internal server error", http.StatusInternalServerError)
+			return
+		}
+	}
+	h.AuthenticateUseCase.Logout(r.Context())
+	message, _ := json.Marshal(map[string]any{"message": "User logged out! HTTPonly jwt cookie deleted"})
+	_, _ = w.Write(message)
+}

api/handlers/auth/meHandler.go

@@ -0,0 +1,107 @@
+package auth
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/api/pkg/payload"
+	"RenewCMS/api/pkg/publicuser"
+	"RenewCMS/internal/domain/author"
+	"RenewCMS/internal/domain/role"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+)
+
+type MeHandler struct {
+	GetUseCase       *useCases.GetUserUseCase
+	GetAuthorUseCase *useCases.GetMyAuthorUseCase
+	GetAccessUseCase *useCases.GetMyAccessUseCase
+}
+
+func NewMeHandler(getUser *useCases.GetUserUseCase, getAuthor *useCases.GetMyAuthorUseCase, getAccess *useCases.GetMyAccessUseCase) *MeHandler {
+	return &MeHandler{
+		GetUseCase:       getUser,
+		GetAuthorUseCase: getAuthor,
+		GetAccessUseCase: getAccess,
+	}
+}
+
+type meAuthor struct {
+	author.Byline
+	ArticleCount int `json:"article_count"`
+}
+
+type meAccess struct {
+	Role           payload.RoleRef       `json:"role"`
+	Permissions    []role.Grant          `json:"permissions"`
+	RoleAssignedBy *payload.RoleAssigner `json:"role_assigned_by"`
+}
+
+type meResponse struct {
+	publicuser.PublicUser
+	PendingEmail *string   `json:"pending_email"`
+	Author       *meAuthor `json:"author"`
+	Access       meAccess  `json:"access"`
+}
+
+func toMeAccess(access useCases.Access) meAccess {
+	return meAccess{
+		Role:           payload.RoleRefOf(useCases.NewRoleRef(access.Role)),
+		Permissions:    access.Permissions,
+		RoleAssignedBy: payload.RoleAssignerPtrOf(access.RoleAssignedBy),
+	}
+}
+
+func toMeAuthor(found *author.Author) *meAuthor {
+	if found == nil {
+		return nil
+	}
+	return &meAuthor{Byline: found.Byline(), ArticleCount: found.ArticleCount}
+}
+
+func pendingEmailOf(account user.User) *string {
+	if account.PendingEmail == "" {
+		return nil
+	}
+	return &account.PendingEmail
+}
+
+func (h *MeHandler) Me(w http.ResponseWriter, r *http.Request) {
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	loadedUser, err := h.GetUseCase.GetUser(userId)
+	if err != nil {
+		if errors.Is(err, user.ErrUserNotFound) {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	linked, err := h.GetAuthorUseCase.Get(loadedUser.ID)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	access, err := h.GetAccessUseCase.Get(loadedUser)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	body, err := json.Marshal(meResponse{PublicUser: publicuser.New(loadedUser), PendingEmail: pendingEmailOf(loadedUser), Author: toMeAuthor(linked), Access: toMeAccess(access)})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}

api/handlers/auth/passwordResetHandler.go

@@ -0,0 +1,85 @@
+package auth
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+)
+
+type PasswordResetHandler struct {
+	RequestPasswordResetUseCase *useCases.RequestPasswordResetUseCase
+	ResetPasswordUseCase        *useCases.ResetPasswordUseCase
+}
+
+type RequestPasswordResetCredentials struct {
+	Email string `json:"email" validate:"required,email"`
+}
+
+type ResetPasswordCredentials struct {
+	Email    string `json:"email" validate:"required,email"`
+	Code     string `json:"code" validate:"required"`
+	Password string `json:"password" validate:"required,min=8"`
+}
+
+func NewPasswordResetHandler(requestPasswordReset *useCases.RequestPasswordResetUseCase, resetPassword *useCases.ResetPasswordUseCase) *PasswordResetHandler {
+	return &PasswordResetHandler{
+		RequestPasswordResetUseCase: requestPasswordReset,
+		ResetPasswordUseCase:        resetPassword,
+	}
+}
+
+func (h *PasswordResetHandler) RequestPasswordReset(w http.ResponseWriter, r *http.Request) {
+	var credentials RequestPasswordResetCredentials
+	err := json.NewDecoder(r.Body).Decode(&credentials)
+	if err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	err = validator.Validate.Struct(credentials)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	_ = h.RequestPasswordResetUseCase.RequestPasswordReset(r.Context(), credentials.Email)
+
+	message, _ := json.Marshal(map[string]any{"message": apperr.PasswordResetRequestedMessage})
+	_, _ = w.Write(message)
+}
+
+func (h *PasswordResetHandler) ResetPassword(w http.ResponseWriter, r *http.Request) {
+	var credentials ResetPasswordCredentials
+	err := json.NewDecoder(r.Body).Decode(&credentials)
+	if err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	err = validator.Validate.Struct(credentials)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	err = h.ResetPasswordUseCase.ResetPassword(r.Context(), credentials.Email, credentials.Code, credentials.Password)
+	if err != nil {
+		if errors.Is(err, user.ErrInvalidPasswordResetCode) || errors.Is(err, user.ErrPasswordResetCodeExpired) {
+			http.Error(w, apperr.PasswordResetFailedErrorMessage, http.StatusForbidden)
+			return
+		}
+		if errors.Is(err, user.ErrPasswordTooLong) {
+			http.Error(w, apperr.PasswordTooLongErrorMessage, http.StatusBadRequest)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	message, _ := json.Marshal(map[string]any{"message": "Your password has been reset. You can now log in."})
+	_, _ = w.Write(message)
+}

api/handlers/auth/verificationHandler.go

@@ -0,0 +1,99 @@
+package auth
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/api/pkg/publicuser"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+)
+
+type VerificationHandler struct {
+	VerifyUseCase *useCases.VerifyUserUseCase
+	CancelUseCase *useCases.CancelRegistrationUseCase
+	IsProduction  bool
+}
+
+type VerifyCredentials struct {
+	Code string `json:"code" validate:"required"`
+}
+
+func NewVerificationHandler(verify *useCases.VerifyUserUseCase, cancel *useCases.CancelRegistrationUseCase, isProduction bool) *VerificationHandler {
+	return &VerificationHandler{
+		VerifyUseCase: verify,
+		CancelUseCase: cancel,
+		IsProduction:  isProduction,
+	}
+}
+
+func (h *VerificationHandler) Verify(w http.ResponseWriter, r *http.Request) {
+	var credentials VerifyCredentials
+	err := json.NewDecoder(r.Body).Decode(&credentials)
+	if err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	err = validator.Validate.Struct(credentials)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	verifiedUser, err := h.VerifyUseCase.Verify(r.Context(), userId, credentials.Code)
+	if err != nil {
+		if errors.Is(err, user.ErrUserNotFound) {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		if errors.Is(err, user.ErrInvalidVerificationCode) || errors.Is(err, user.ErrVerificationCodeExpired) {
+			http.Error(w, apperr.VerificationFailedErrorMessage, http.StatusForbidden)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	body, err := json.Marshal(publicuser.New(verifiedUser))
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	_, _ = w.Write(body)
+}
+
+func (h *VerificationHandler) CancelRegistration(w http.ResponseWriter, r *http.Request) {
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	err := h.CancelUseCase.CancelRegistration(userId)
+	if err != nil {
+		if errors.Is(err, user.ErrUserNotFound) {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		if errors.Is(err, user.ErrAlreadyVerified) {
+			http.Error(w, apperr.AlreadyVerifiedErrorMessage, http.StatusForbidden)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	removeJwtCookie(w, h.IsProduction)
+	message, _ := json.Marshal(map[string]any{"message": "Registration cancelled! Account deleted and HTTPonly jwt cookie cleared"})
+	_, _ = w.Write(message)
+}

api/handlers/author/authorHandler.go

@@ -0,0 +1,383 @@
+package author
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	validator "RenewCMS/api/pkg/validator"
+	domain "RenewCMS/internal/domain/author"
+	"RenewCMS/internal/domain/image"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"io"
+	"log"
+	"net/http"
+	"net/url"
+	"strconv"
+
+	"github.com/go-chi/chi/v5"
+	playground "github.com/go-playground/validator/v10"
+)
+
+const (
+	defaultListPage = 1
+	defaultListSize = 25
+	reassignParam   = "reassign_to"
+	reassignNone    = "none"
+)
+
+type Handler struct {
+	ListUseCase     *useCases.ListAuthorsUseCase
+	CreateUseCase   *useCases.CreateAuthorUseCase
+	CreateMyUseCase *useCases.CreateMyAuthorUseCase
+	UpdateUseCase   *useCases.UpdateAuthorUseCase
+	DeleteUseCase   *useCases.DeleteAuthorUseCase
+}
+
+func NewHandler(list *useCases.ListAuthorsUseCase, create *useCases.CreateAuthorUseCase, createMy *useCases.CreateMyAuthorUseCase, update *useCases.UpdateAuthorUseCase, deleteUseCase *useCases.DeleteAuthorUseCase) *Handler {
+	return &Handler{ListUseCase: list, CreateUseCase: create, CreateMyUseCase: createMy, UpdateUseCase: update, DeleteUseCase: deleteUseCase}
+}
+
+type socialLinkRequest struct {
+	Type string `json:"type" validate:"socialtype"`
+	URL  string `json:"url"`
+}
+
+func toLinks(requests []socialLinkRequest) []domain.SocialLink {
+	links := make([]domain.SocialLink, 0, len(requests))
+	for _, request := range requests {
+		links = append(links, domain.SocialLink{Type: request.Type, URL: request.URL})
+	}
+	return links
+}
+
+type PostAuthor struct {
+	Name        string              `json:"name" validate:"authorname"`
+	Slug        string              `json:"slug" validate:"omitempty,authorslug"`
+	Bio         string              `json:"bio"`
+	AvatarID    *uint32             `json:"avatar_id" validate:"omitempty,gte=1"`
+	Website     *string             `json:"website"`
+	SocialLinks []socialLinkRequest `json:"social_links" validate:"omitempty,dive"`
+	UserID      *uint32             `json:"user_id" validate:"omitempty,gte=1"`
+}
+
+type optional[T any] struct {
+	Set   bool
+	Value *T
+}
+
+func (o *optional[T]) UnmarshalJSON(data []byte) error {
+	o.Set = true
+	if string(data) == "null" {
+		o.Value = nil
+		return nil
+	}
+	var value T
+	if err := json.Unmarshal(data, &value); err != nil {
+		return err
+	}
+	o.Value = &value
+	return nil
+}
+
+type PatchAuthor struct {
+	Name        *string              `json:"name" validate:"authorname"`
+	Slug        *string              `json:"slug" validate:"authorslug"`
+	Bio         *string              `json:"bio"`
+	AvatarID    optional[uint32]     `json:"avatar_id"`
+	Website     optional[string]     `json:"website"`
+	SocialLinks *[]socialLinkRequest `json:"social_links" validate:"omitempty,dive"`
+	UserID      optional[uint32]     `json:"user_id"`
+}
+
+func (p PatchAuthor) toPatch() domain.Patch {
+	patch := domain.Patch{
+		Name:     p.Name,
+		Slug:     p.Slug,
+		Bio:      p.Bio,
+		AvatarID: domain.Nullable[uint32]{Set: p.AvatarID.Set, Value: p.AvatarID.Value},
+		Website:  domain.Nullable[string]{Set: p.Website.Set, Value: p.Website.Value},
+		UserID:   domain.Nullable[uint32]{Set: p.UserID.Set, Value: p.UserID.Value},
+	}
+	if p.SocialLinks != nil {
+		links := toLinks(*p.SocialLinks)
+		patch.SocialLinks = &links
+	}
+	return patch
+}
+
+var requiredNonNullFields = []string{"name", "slug", "bio", "social_links"}
+
+var nullableFields = []string{"avatar_id", "website", "user_id"}
+
+func readPatchAuthor(r *http.Request) (PatchAuthor, bool) {
+	raw, err := io.ReadAll(r.Body)
+	if err != nil {
+		return PatchAuthor{}, false
+	}
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &fields); err != nil {
+		return PatchAuthor{}, false
+	}
+	known := false
+	for _, name := range requiredNonNullFields {
+		value, present := fields[name]
+		if !present {
+			continue
+		}
+		if string(value) == "null" {
+			return PatchAuthor{}, false
+		}
+		known = true
+	}
+	for _, name := range nullableFields {
+		if _, present := fields[name]; present {
+			known = true
+		}
+	}
+	if !known {
+		return PatchAuthor{}, false
+	}
+	var request PatchAuthor
+	if err := json.Unmarshal(raw, &request); err != nil {
+		return PatchAuthor{}, false
+	}
+	return request, true
+}
+
+func parseAuthorId(r *http.Request) (uint32, error) {
+	id, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	return uint32(id), err
+}
+
+type ownAuthorResponse struct {
+	domain.Author
+	SlugAdjusted bool `json:"slug_adjusted"`
+}
+
+func presentAuthor(a domain.Author) domain.Author {
+	if a.SocialLinks == nil {
+		a.SocialLinks = []domain.SocialLink{}
+	}
+	return a
+}
+
+func writeJSON(w http.ResponseWriter, status int, payload any) {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+	if status != http.StatusOK {
+		w.WriteHeader(status)
+	}
+	if _, err := w.Write(body); err != nil {
+		log.Printf("Failed to write response: %v", err)
+	}
+}
+
+func writeAuthorError(w http.ResponseWriter, err error) {
+	switch {
+	case access.WriteIfMissingPermission(w, err):
+	case errors.Is(err, domain.ErrAuthorNotFound):
+		http.Error(w, apperr.AuthorNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, domain.ErrSlugTaken):
+		http.Error(w, apperr.AuthorSlugTakenErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrAuthorHasArticles):
+		http.Error(w, apperr.AuthorHasArticlesErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrUserAlreadyLinked):
+		http.Error(w, apperr.UserAlreadyLinkedErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrAuthorAlreadyLinked):
+		http.Error(w, apperr.AuthorAlreadyLinkedErrorMessage, http.StatusConflict)
+	case errors.Is(err, user.ErrUserNotFound):
+		http.Error(w, apperr.UserNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, domain.ErrAuthorRights):
+		http.Error(w, apperr.AuthorRightsErrorMessage, http.StatusForbidden)
+	case errors.Is(err, domain.ErrBioTooLong):
+		http.Error(w, apperr.BioTooLongErrorMessage, http.StatusUnprocessableEntity)
+	case errors.Is(err, domain.ErrInvalidURL):
+		http.Error(w, apperr.InvalidURLErrorMessage, http.StatusUnprocessableEntity)
+	case errors.Is(err, domain.ErrTooManyLinks):
+		http.Error(w, apperr.TooManyLinksErrorMessage, http.StatusUnprocessableEntity)
+	case errors.Is(err, domain.ErrInvalidSocialType):
+		http.Error(w, apperr.InvalidSocialTypeErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidSlug):
+		http.Error(w, apperr.InvalidSlugErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidReassign):
+		http.Error(w, apperr.InvalidReassignErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, image.ErrImageNotFound):
+		http.Error(w, apperr.AuthorImageNotFoundErrorMessage, http.StatusBadRequest)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func writeValidationError(w http.ResponseWriter, err error) {
+	var failures playground.ValidationErrors
+	if errors.As(err, &failures) {
+		for _, failure := range failures {
+			if failure.Tag() == validator.AuthorSlugTag {
+				http.Error(w, apperr.InvalidSlugErrorMessage, http.StatusBadRequest)
+				return
+			}
+		}
+	}
+	http.Error(w, err.Error(), http.StatusBadRequest)
+}
+
+type listQuery struct {
+	Page int    `validate:"gte=1"`
+	Size int    `validate:"oneof=5 25 50 100"`
+	Q    string `validate:"max=200"`
+}
+
+type listResponse struct {
+	Items []domain.Author `json:"items"`
+	Total int             `json:"total"`
+	Page  int             `json:"page"`
+	Size  int             `json:"size"`
+}
+
+func intQueryParam(values url.Values, name string, fallback int) (int, error) {
+	if !values.Has(name) {
+		return fallback, nil
+	}
+	return strconv.Atoi(values.Get(name))
+}
+
+func readListQuery(values url.Values) (listQuery, error) {
+	page, err := intQueryParam(values, "page", defaultListPage)
+	if err != nil {
+		return listQuery{}, err
+	}
+	size, err := intQueryParam(values, "size", defaultListSize)
+	if err != nil {
+		return listQuery{}, err
+	}
+	return listQuery{Page: page, Size: size, Q: values.Get("q")}, nil
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	query, err := readListQuery(r.URL.Query())
+	if err != nil || validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	page, err := h.ListUseCase.List(useCases.ListAuthorsCommand{Q: query.Q, Page: query.Page, Size: query.Size, Grants: access.Grants(r)})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	items := make([]domain.Author, 0, len(page.Items))
+	for _, item := range page.Items {
+		items = append(items, presentAuthor(item))
+	}
+	w.Header().Set("X-Total-Count", strconv.Itoa(page.Total))
+	writeJSON(w, http.StatusOK, listResponse{Items: items, Total: page.Total, Page: page.Page, Size: page.Size})
+}
+
+func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
+	var request PostAuthor
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		writeValidationError(w, err)
+		return
+	}
+
+	created, err := h.CreateUseCase.Create(r.Context(), useCases.CreateAuthorCommand{
+		Name:        request.Name,
+		Slug:        request.Slug,
+		Bio:         request.Bio,
+		AvatarID:    request.AvatarID,
+		Website:     request.Website,
+		SocialLinks: toLinks(request.SocialLinks),
+		UserID:      request.UserID,
+	})
+	if err != nil {
+		writeAuthorError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusCreated, presentAuthor(created))
+}
+
+func (h *Handler) CreateMine(w http.ResponseWriter, r *http.Request) {
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	created, err := h.CreateMyUseCase.Create(r.Context(), userId)
+	if err != nil {
+		writeAuthorError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusCreated, ownAuthorResponse{Author: presentAuthor(created.Author), SlugAdjusted: created.SlugAdjusted})
+}
+
+func (h *Handler) Update(w http.ResponseWriter, r *http.Request) {
+	id, err := parseAuthorId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	request, ok := readPatchAuthor(r)
+	if !ok {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		writeValidationError(w, err)
+		return
+	}
+
+	callerID, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+	updated, err := h.UpdateUseCase.Update(r.Context(), id, useCases.AuthorCaller{UserID: callerID, Grants: access.Grants(r)}, request.toPatch())
+	if err != nil {
+		writeAuthorError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, presentAuthor(updated))
+}
+
+func readReassignment(r *http.Request) useCases.Reassignment {
+	query := r.URL.Query()
+	if !query.Has(reassignParam) {
+		return useCases.Reassignment{Mode: useCases.ReassignAbsent}
+	}
+	value := query.Get(reassignParam)
+	if value == reassignNone {
+		return useCases.Reassignment{Mode: useCases.ReassignNone}
+	}
+	parsed, err := strconv.ParseUint(value, 10, 32)
+	if err != nil {
+		return useCases.Reassignment{Mode: useCases.ReassignMalformed}
+	}
+	return useCases.Reassignment{Mode: useCases.ReassignToAuthor, Destination: uint32(parsed)}
+}
+
+func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
+	id, err := parseAuthorId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	if err := h.DeleteUseCase.Delete(r.Context(), id, readReassignment(r)); err != nil {
+		writeAuthorError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

api/handlers/builtintype/builtinTypeHandler.go

@@ -0,0 +1,38 @@
+package builtintype
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/response"
+	domain "RenewCMS/internal/domain/builtintype"
+	"RenewCMS/internal/infrastructure/useCases"
+	"errors"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	ListUseCase *useCases.ListBuiltinTypesUseCase
+	GetUseCase  *useCases.GetBuiltinTypeUseCase
+}
+
+func NewHandler(list *useCases.ListBuiltinTypesUseCase, get *useCases.GetBuiltinTypeUseCase) *Handler {
+	return &Handler{ListUseCase: list, GetUseCase: get}
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	response.WriteJSON(w, http.StatusOK, h.ListUseCase.List())
+}
+
+func (h *Handler) Get(w http.ResponseWriter, r *http.Request) {
+	found, err := h.GetUseCase.Get(chi.URLParam(r, "key"))
+	if errors.Is(err, domain.ErrNotFound) {
+		http.Error(w, apperr.BuiltinTypeNotFoundErrorMessage, http.StatusNotFound)
+		return
+	}
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	response.WriteJSON(w, http.StatusOK, found)
+}

api/handlers/contenttype/contentTypeHandler.go

@@ -0,0 +1,184 @@
+package contenttype
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/response"
+	validator "RenewCMS/api/pkg/validator"
+	domain "RenewCMS/internal/domain/contenttype"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	CreateUseCase *useCases.CreateContentTypeUseCase
+	ListUseCase   *useCases.ListContentTypesUseCase
+	GetUseCase    *useCases.GetContentTypeUseCase
+	UpdateUseCase *useCases.UpdateContentTypeUseCase
+	DeleteUseCase *useCases.DeleteContentTypeUseCase
+}
+
+func NewHandler(create *useCases.CreateContentTypeUseCase, list *useCases.ListContentTypesUseCase, get *useCases.GetContentTypeUseCase, update *useCases.UpdateContentTypeUseCase, deleteUseCase *useCases.DeleteContentTypeUseCase) *Handler {
+	return &Handler{CreateUseCase: create, ListUseCase: list, GetUseCase: get, UpdateUseCase: update, DeleteUseCase: deleteUseCase}
+}
+
+type iconInput struct {
+	value   *string
+	invalid bool
+}
+
+func (i *iconInput) UnmarshalJSON(data []byte) error {
+	if string(data) == "null" {
+		return nil
+	}
+	var text string
+	if err := json.Unmarshal(data, &text); err != nil {
+		i.invalid = true
+		return nil
+	}
+	i.value = &text
+	return nil
+}
+
+type PostContentType struct {
+	Key    string         `json:"key" validate:"required"`
+	Name   string         `json:"name" validate:"required,max=100"`
+	Icon   iconInput      `json:"icon"`
+	Fields []domain.Field `json:"fields"`
+}
+
+type PutContentType struct {
+	Key    string         `json:"key"`
+	Name   string         `json:"name" validate:"required,max=100"`
+	Icon   iconInput      `json:"icon"`
+	Fields []domain.Field `json:"fields"`
+}
+
+type contentTypeResponse struct {
+	ID        uint32         `json:"id"`
+	Key       string         `json:"key"`
+	Name      string         `json:"name"`
+	Icon      *string        `json:"icon"`
+	Fields    []domain.Field `json:"fields"`
+	CreatedAt time.Time      `json:"created_at"`
+	UpdatedAt time.Time      `json:"updated_at"`
+}
+
+func toResponse(contentType domain.ContentType) contentTypeResponse {
+	fields := contentType.Fields
+	if fields == nil {
+		fields = []domain.Field{}
+	}
+	return contentTypeResponse{
+		ID:        contentType.ID,
+		Key:       contentType.Key,
+		Name:      contentType.Name,
+		Icon:      contentType.Icon,
+		Fields:    fields,
+		CreatedAt: contentType.CreatedAt,
+		UpdatedAt: contentType.UpdatedAt,
+	}
+}
+
+func writeContentTypeError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, domain.ErrContentTypeNotFound):
+		http.Error(w, apperr.ContentTypeNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, domain.ErrKeyTaken):
+		http.Error(w, apperr.ContentTypeKeyTakenErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrHasEntries):
+		http.Error(w, apperr.ContentTypeHasEntriesErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrReferenced):
+		http.Error(w, apperr.ContentTypeReferencedErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrSchemaIncompatible):
+		http.Error(w, apperr.SchemaIncompatibleErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrInvalidName):
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidIcon):
+		http.Error(w, apperr.InvalidIconErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidKey):
+		http.Error(w, apperr.InvalidContentTypeKeyErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidField):
+		http.Error(w, apperr.InvalidFieldErrorMessage, http.StatusUnprocessableEntity)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	found, err := h.ListUseCase.List()
+	if err != nil {
+		writeContentTypeError(w, err)
+		return
+	}
+	responses := make([]contentTypeResponse, 0, len(found))
+	for _, contentType := range found {
+		responses = append(responses, toResponse(contentType))
+	}
+	response.WriteJSON(w, http.StatusOK, responses)
+}
+
+func (h *Handler) Get(w http.ResponseWriter, r *http.Request) {
+	found, err := h.GetUseCase.Get(chi.URLParam(r, "key"))
+	if err != nil {
+		writeContentTypeError(w, err)
+		return
+	}
+	response.WriteJSON(w, http.StatusOK, toResponse(found))
+}
+
+func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
+	var request PostContentType
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if request.Icon.invalid {
+		writeContentTypeError(w, domain.ErrInvalidIcon)
+		return
+	}
+	created, err := h.CreateUseCase.Create(useCases.CreateContentTypeCommand{Key: request.Key, Name: request.Name, Icon: request.Icon.value, Fields: request.Fields})
+	if err != nil {
+		writeContentTypeError(w, err)
+		return
+	}
+	response.WriteJSON(w, http.StatusCreated, toResponse(created))
+}
+
+func (h *Handler) Update(w http.ResponseWriter, r *http.Request) {
+	var request PutContentType
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if request.Icon.invalid {
+		writeContentTypeError(w, domain.ErrInvalidIcon)
+		return
+	}
+	updated, err := h.UpdateUseCase.Update(useCases.UpdateContentTypeCommand{Key: chi.URLParam(r, "key"), Name: request.Name, Icon: request.Icon.value, Fields: request.Fields})
+	if err != nil {
+		writeContentTypeError(w, err)
+		return
+	}
+	response.WriteJSON(w, http.StatusOK, toResponse(updated))
+}
+
+func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
+	if err := h.DeleteUseCase.Delete(chi.URLParam(r, "key")); err != nil {
+		writeContentTypeError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

api/handlers/entry/entryHandler.go

@@ -0,0 +1,291 @@
+package entry
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/response"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/contenttype"
+	domain "RenewCMS/internal/domain/entry"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/url"
+	"strconv"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	CreateUseCase *useCases.CreateEntryUseCase
+	GetUseCase    *useCases.GetEntryUseCase
+	ListUseCase   *useCases.ListEntriesUseCase
+	UpdateUseCase *useCases.UpdateEntryUseCase
+	DeleteUseCase *useCases.DeleteEntryUseCase
+}
+
+func NewHandler(create *useCases.CreateEntryUseCase, get *useCases.GetEntryUseCase, list *useCases.ListEntriesUseCase, update *useCases.UpdateEntryUseCase, deleteUseCase *useCases.DeleteEntryUseCase) *Handler {
+	return &Handler{CreateUseCase: create, GetUseCase: get, ListUseCase: list, UpdateUseCase: update, DeleteUseCase: deleteUseCase}
+}
+
+type EntryBody struct {
+	Data map[string]any `json:"data" validate:"required"`
+}
+
+type entryResponse struct {
+	ID          uint32         `json:"id"`
+	ContentType string         `json:"content_type"`
+	Data        map[string]any `json:"data"`
+	CreatedBy   uint32         `json:"created_by"`
+	UpdatedBy   uint32         `json:"updated_by"`
+	CreatedAt   time.Time      `json:"created_at"`
+	UpdatedAt   time.Time      `json:"updated_at"`
+	Media       map[string]any `json:"media"`
+	Relations   map[string]any `json:"relations"`
+}
+
+type firstFieldBody struct {
+	Key   string                `json:"key"`
+	Type  contenttype.FieldType `json:"type"`
+	Value any                   `json:"value"`
+}
+
+type relationBody struct {
+	ID          uint32         `json:"id"`
+	ContentType string         `json:"content_type"`
+	FirstField  firstFieldBody `json:"first_field"`
+}
+
+type missingRelationBody struct {
+	ID      uint32 `json:"id"`
+	Missing bool   `json:"missing"`
+}
+
+func toRelationItem(item useCases.EntryRelation) any {
+	if item.Missing {
+		return missingRelationBody{ID: item.ID, Missing: true}
+	}
+	return relationBody{ID: item.ID, ContentType: item.ContentType, FirstField: firstFieldBody{Key: item.FirstField.Key, Type: item.FirstField.Type, Value: item.FirstField.Value}}
+}
+
+func toRelationsResponse(relations map[string]useCases.EntryRelations) map[string]any {
+	body := make(map[string]any, len(relations))
+	for key, held := range relations {
+		if !held.Many {
+			if len(held.Items) > 0 {
+				body[key] = toRelationItem(held.Items[0])
+			}
+			continue
+		}
+		items := make([]any, 0, len(held.Items))
+		for _, item := range held.Items {
+			items = append(items, toRelationItem(item))
+		}
+		body[key] = items
+	}
+	return body
+}
+
+type mediaBody struct {
+	ID           uint32 `json:"id"`
+	Filename     string `json:"filename"`
+	Width        *int   `json:"width"`
+	Height       *int   `json:"height"`
+	Size         int64  `json:"size"`
+	ThumbnailURL string `json:"thumbnail_url"`
+}
+
+type missingMediaBody struct {
+	ID      uint32 `json:"id"`
+	Missing bool   `json:"missing"`
+}
+
+func toMediaResponse(media map[string]useCases.EntryMedia) map[string]any {
+	body := make(map[string]any, len(media))
+	for key, item := range media {
+		if item.Missing {
+			body[key] = missingMediaBody{ID: item.ID, Missing: true}
+			continue
+		}
+		body[key] = mediaBody{ID: item.ID, Filename: item.Filename, Width: item.Width, Height: item.Height, Size: item.Size, ThumbnailURL: item.ThumbnailURL}
+	}
+	return body
+}
+
+func toResponse(typed useCases.TypedEntry) entryResponse {
+	return entryResponse{
+		ID:          typed.ID,
+		ContentType: typed.ContentTypeKey,
+		Data:        typed.Data,
+		CreatedBy:   typed.CreatedBy,
+		UpdatedBy:   typed.UpdatedBy,
+		CreatedAt:   typed.CreatedAt,
+		UpdatedAt:   typed.UpdatedAt,
+		Media:       toMediaResponse(typed.Media),
+		Relations:   toRelationsResponse(typed.Relations),
+	}
+}
+
+type pageResponse struct {
+	Items []entryResponse `json:"items"`
+	Total int             `json:"total"`
+	Page  int             `json:"page"`
+	Size  int             `json:"size"`
+}
+
+const (
+	defaultListPage = 1
+	defaultListSize = 25
+)
+
+type listQuery struct {
+	Page int `validate:"gte=1"`
+	Size int `validate:"oneof=5 25 50 100"`
+	Sort domain.Sort
+}
+
+func intQueryParam(values url.Values, name string, fallback int) (int, error) {
+	if !values.Has(name) {
+		return fallback, nil
+	}
+	return strconv.Atoi(values.Get(name))
+}
+
+func readListQuery(values url.Values) (listQuery, error) {
+	page, err := intQueryParam(values, "page", defaultListPage)
+	if err != nil {
+		return listQuery{}, err
+	}
+	size, err := intQueryParam(values, "size", defaultListSize)
+	if err != nil {
+		return listQuery{}, err
+	}
+	order := domain.DefaultSort()
+	if values.Has("sort") {
+		order, err = domain.ParseSort(values.Get("sort"))
+		if err != nil {
+			return listQuery{}, err
+		}
+	}
+	return listQuery{Page: page, Size: size, Sort: order}, nil
+}
+
+func parseEntryId(r *http.Request) (uint32, error) {
+	id, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	return uint32(id), err
+}
+
+func writeEntryError(w http.ResponseWriter, err error) {
+	if access.WriteIfMissingPermission(w, err) {
+		return
+	}
+	var fieldError domain.FieldError
+	switch {
+	case errors.Is(err, contenttype.ErrContentTypeNotFound):
+		http.Error(w, apperr.ContentTypeNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, domain.ErrEntryNotFound):
+		http.Error(w, apperr.EntryNotFoundErrorMessage, http.StatusNotFound)
+	case errors.As(err, &fieldError):
+		http.Error(w, apperr.InvalidEntryErrorMessage+": "+fieldError.Error(), fieldErrorStatus(err))
+	case errors.Is(err, domain.ErrInvalidPage), errors.Is(err, domain.ErrInvalidSort):
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidEntry):
+		http.Error(w, apperr.InvalidEntryErrorMessage, http.StatusUnprocessableEntity)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func fieldErrorStatus(err error) int {
+	if errors.Is(err, domain.ErrUniqueViolation) {
+		return http.StatusConflict
+	}
+	return http.StatusUnprocessableEntity
+}
+
+func readBody(w http.ResponseWriter, r *http.Request) (EntryBody, bool) {
+	var body EntryBody
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || validator.Validate.Struct(body) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return EntryBody{}, false
+	}
+	return body, true
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	query, err := readListQuery(r.URL.Query())
+	if err != nil || validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	page, err := h.ListUseCase.ListPage(useCases.ListEntriesCommand{ContentTypeKey: chi.URLParam(r, "key"), Page: query.Page, Size: query.Size, Sort: query.Sort, Query: r.URL.Query().Get("q"), Caller: access.CallerOf(r)})
+	if err != nil {
+		writeEntryError(w, err)
+		return
+	}
+	items := make([]entryResponse, 0, len(page.Items))
+	for _, typed := range page.Items {
+		items = append(items, toResponse(typed))
+	}
+	response.WriteJSON(w, http.StatusOK, pageResponse{Items: items, Total: page.Total, Page: page.Page, Size: page.Size})
+}
+
+func (h *Handler) Get(w http.ResponseWriter, r *http.Request) {
+	id, err := parseEntryId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+	found, err := h.GetUseCase.Get(chi.URLParam(r, "key"), id, access.CallerOf(r))
+	if err != nil {
+		writeEntryError(w, err)
+		return
+	}
+	response.WriteJSON(w, http.StatusOK, toResponse(found))
+}
+
+func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
+	body, ok := readBody(w, r)
+	if !ok {
+		return
+	}
+	created, err := h.CreateUseCase.Create(useCases.CreateEntryCommand{ContentTypeKey: chi.URLParam(r, "key"), Data: body.Data, Caller: access.CallerOf(r)})
+	if err != nil {
+		writeEntryError(w, err)
+		return
+	}
+	response.WriteJSON(w, http.StatusCreated, toResponse(created))
+}
+
+func (h *Handler) Update(w http.ResponseWriter, r *http.Request) {
+	id, err := parseEntryId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+	body, ok := readBody(w, r)
+	if !ok {
+		return
+	}
+	updated, err := h.UpdateUseCase.Update(useCases.UpdateEntryCommand{ContentTypeKey: chi.URLParam(r, "key"), ID: id, Data: body.Data, Caller: access.CallerOf(r)})
+	if err != nil {
+		writeEntryError(w, err)
+		return
+	}
+	response.WriteJSON(w, http.StatusOK, toResponse(updated))
+}
+
+func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
+	id, err := parseEntryId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := h.DeleteUseCase.Delete(chi.URLParam(r, "key"), id, access.CallerOf(r)); err != nil {
+		writeEntryError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

api/handlers/frontend/frontHandler.go

@@ -0,0 +1,108 @@
+package frontend
+
+import (
+	"RenewCMS/internal/infrastructure/assets"
+	"bytes"
+	"io"
+	"io/fs"
+	"net/http"
+	"path"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+const hashedAssetsPrefix = "assets/"
+
+const (
+	hashedAssetCacheControl = "public, max-age=31536000, immutable"
+	staticFileCacheControl  = "public, max-age=3600"
+	indexCacheControl       = "no-store, no-cache, must-revalidate"
+)
+
+const devNotice = "RenewCMS was built with -tags nofrontend: the SPA is served by the Vite dev server (http://localhost:5173)."
+
+type spaHandler struct {
+	staticFS fs.FS
+	modTime  time.Time
+}
+
+func NewFrontendRouter() http.Handler {
+	r := chi.NewRouter()
+
+	if assets.Dist == nil {
+		r.Get("/*", serveDevNotice)
+		return r
+	}
+
+	handler := &spaHandler{
+		staticFS: assets.Dist,
+		modTime:  time.Now(),
+	}
+
+	r.Get("/*", handler.ServeHTTP)
+	return r
+}
+
+func serveDevNotice(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.WriteHeader(http.StatusNotFound)
+	_, _ = io.WriteString(w, devNotice)
+}
+
+func (h *spaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	path := h.cleanPath(r.URL.Path)
+	if h.fileExists(path) {
+		h.serveAsset(w, r, path)
+		return
+	}
+	h.serveIndex(w, r)
+}
+
+func (h *spaHandler) cleanPath(p string) string {
+	return strings.TrimPrefix(path.Clean("/"+p), "/")
+}
+
+func (h *spaHandler) fileExists(path string) bool {
+	if path == "" || path == "." {
+		return false
+	}
+	f, err := h.staticFS.Open(path)
+	if err != nil {
+		return false
+	}
+	defer f.Close()
+	stat, err := f.Stat()
+	return err == nil && !stat.IsDir()
+}
+
+func (h *spaHandler) serveAsset(w http.ResponseWriter, r *http.Request, path string) {
+	if strings.HasPrefix(path, hashedAssetsPrefix) {
+		w.Header().Set("Cache-Control", hashedAssetCacheControl)
+	} else {
+		w.Header().Set("Cache-Control", staticFileCacheControl)
+	}
+	http.FileServer(http.FS(h.staticFS)).ServeHTTP(w, r)
+}
+
+func (h *spaHandler) serveIndex(w http.ResponseWriter, r *http.Request) {
+	f, err := h.staticFS.Open("index.html")
+	if err != nil {
+		http.Error(w, "Index not found", http.StatusNotFound)
+		return
+	}
+	defer f.Close()
+
+	html, err := io.ReadAll(f)
+	if err != nil {
+		http.Error(w, "Index not readable", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Cache-Control", indexCacheControl)
+	if policy := w.Header().Get("Content-Security-Policy"); policy != "" {
+		w.Header().Set("Content-Security-Policy", AllowInlineScripts(policy, html))
+	}
+	http.ServeContent(w, r, "index.html", h.modTime, bytes.NewReader(html))
+}

api/handlers/frontend/inlineScripts.go

@@ -0,0 +1,33 @@
+package frontend
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"regexp"
+	"strings"
+)
+
+const scriptSrcSelf = "script-src 'self'"
+
+var inlineScriptPattern = regexp.MustCompile(`(?is)<script(\s[^>]*)?>(.*?)</script>`)
+var srcAttributePattern = regexp.MustCompile(`(?i)\ssrc\s*=`)
+
+func inlineScriptSources(html []byte) []string {
+	var sources []string
+	for _, match := range inlineScriptPattern.FindAllSubmatch(html, -1) {
+		if srcAttributePattern.Match(match[1]) || strings.TrimSpace(string(match[2])) == "" {
+			continue
+		}
+		digest := sha256.Sum256(match[2])
+		sources = append(sources, "'sha256-"+base64.StdEncoding.EncodeToString(digest[:])+"'")
+	}
+	return sources
+}
+
+func AllowInlineScripts(policy string, html []byte) string {
+	sources := inlineScriptSources(html)
+	if len(sources) == 0 {
+		return policy
+	}
+	return strings.Replace(policy, scriptSrcSelf, scriptSrcSelf+" "+strings.Join(sources, " "), 1)
+}

api/handlers/imagevariant/cacheHandler.go

@@ -0,0 +1,141 @@
+package imagevariant
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/image"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"math"
+	"net/http"
+
+	validatorlib "github.com/go-playground/validator/v10"
+)
+
+type cacheUnusedResponse struct {
+	Files int   `json:"files"`
+	Bytes int64 `json:"bytes"`
+	Days  int   `json:"days"`
+}
+
+type cacheVariantResponse struct {
+	Name    string `json:"name"`
+	Enabled bool   `json:"enabled"`
+	Files   int    `json:"files"`
+	Bytes   int64  `json:"bytes"`
+}
+
+type cacheImageResponse struct {
+	ID       uint32 `json:"id"`
+	Filename string `json:"filename"`
+	URL      string `json:"url"`
+	Files    int    `json:"files"`
+	Bytes    int64  `json:"bytes"`
+}
+
+type cacheResponse struct {
+	GeneratedFiles     int                    `json:"generated_files"`
+	DiskUsed           int64                  `json:"disk_used"`
+	VariantsDefined    int                    `json:"variants_defined"`
+	VariantsEnabled    int                    `json:"variants_enabled"`
+	VariantsDisabled   int                    `json:"variants_disabled"`
+	RejectedRequests   int                    `json:"rejected_requests"`
+	RejectedWindowDays int                    `json:"rejected_window_days"`
+	Unused             cacheUnusedResponse    `json:"unused"`
+	ByVariant          []cacheVariantResponse `json:"by_variant"`
+	TopImages          []cacheImageResponse   `json:"top_images"`
+}
+
+type cachePurgeRequest struct {
+	Scope   string `json:"scope" validate:"required,oneof=all unused variant image"`
+	Variant string `json:"variant" validate:"required_if=Scope variant"`
+	ImageID int64  `json:"image_id" validate:"required_if=Scope image,omitempty,gt=0,lte=4294967295"`
+}
+
+type cachePurgeResponse struct {
+	Scope       string `json:"scope"`
+	PurgedFiles int    `json:"purged_files"`
+	PurgedBytes int64  `json:"purged_bytes"`
+	FailedFiles int    `json:"failed_files"`
+}
+
+func (r *cachePurgeRequest) ignoreUnusedTargets() {
+	if r.Scope != string(image.CacheScopeVariant) {
+		r.Variant = ""
+	}
+	if r.Scope != string(image.CacheScopeImage) {
+		r.ImageID = 0
+	}
+}
+
+func cacheResponseOf(stats useCases.VariantCacheStats) cacheResponse {
+	response := cacheResponse{
+		GeneratedFiles:     stats.GeneratedFiles,
+		DiskUsed:           stats.DiskUsed,
+		VariantsDefined:    stats.VariantsDefined,
+		VariantsEnabled:    stats.VariantsEnabled,
+		VariantsDisabled:   stats.VariantsDisabled,
+		RejectedRequests:   stats.RejectedRequests,
+		RejectedWindowDays: stats.RejectedWindowDays,
+		Unused:             cacheUnusedResponse{Files: stats.Unused.Files, Bytes: stats.Unused.Bytes, Days: stats.UnusedDays},
+		ByVariant:          make([]cacheVariantResponse, 0, len(stats.ByVariant)),
+		TopImages:          make([]cacheImageResponse, 0, len(stats.TopImages)),
+	}
+	for _, entry := range stats.ByVariant {
+		response.ByVariant = append(response.ByVariant, cacheVariantResponse{Name: entry.Name, Enabled: entry.Enabled, Files: entry.Files, Bytes: entry.Bytes})
+	}
+	for _, top := range stats.TopImages {
+		response.TopImages = append(response.TopImages, cacheImageResponse{ID: top.ID, Filename: top.Filename, URL: top.URL, Files: top.Files, Bytes: top.Bytes})
+	}
+	return response
+}
+
+func (h *Handler) CacheStats(w http.ResponseWriter, _ *http.Request) {
+	stats, err := h.cacheStats.Get()
+	if err != nil {
+		h.writeError(w, "", err)
+		return
+	}
+	writeJSON(w, http.StatusOK, cacheResponseOf(stats))
+}
+
+func (h *Handler) PurgeCache(w http.ResponseWriter, r *http.Request) {
+	var request cachePurgeRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	request.ignoreUnusedTargets()
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, cachePurgeValidationMessage(err), http.StatusUnprocessableEntity)
+		return
+	}
+
+	result, err := h.purgeCache.Purge(r.Context(), useCases.PurgeVariantCacheCommand{
+		Scope:   image.CachePurgeScope(request.Scope),
+		Variant: request.Variant,
+		ImageID: uint32(min(request.ImageID, math.MaxUint32)),
+	})
+	if err != nil {
+		h.writePurgeCacheError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, cachePurgeResponse{Scope: string(result.Scope), PurgedFiles: result.Files, PurgedBytes: result.Bytes, FailedFiles: result.Failed})
+}
+
+func cachePurgeValidationMessage(err error) string {
+	var failures validatorlib.ValidationErrors
+	if errors.As(err, &failures) && len(failures) > 0 && failures[0].StructField() != "Scope" {
+		return apperr.CachePurgeTargetErrorMessage
+	}
+	return apperr.CachePurgeScopeErrorMessage
+}
+
+func (h *Handler) writePurgeCacheError(w http.ResponseWriter, err error) {
+	if errors.Is(err, image.ErrImageNotFound) {
+		http.Error(w, apperr.ImageNotFoundErrorMessage, http.StatusNotFound)
+		return
+	}
+	h.writeError(w, "", err)
+}

api/handlers/imagevariant/imageVariantHandler.go

@@ -0,0 +1,266 @@
+package imagevariant
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/image"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	validatorlib "github.com/go-playground/validator/v10"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	list       *useCases.ListVariantsUseCase
+	create     *useCases.CreateVariantUseCase
+	update     *useCases.UpdateVariantUseCase
+	setEnabled *useCases.SetVariantEnabledUseCase
+	remove     *useCases.DeleteVariantUseCase
+	purge      *useCases.PurgeVariantUseCase
+	cacheStats *useCases.GetVariantCacheStatsUseCase
+	purgeCache *useCases.PurgeVariantCacheUseCase
+}
+
+func NewHandler(list *useCases.ListVariantsUseCase, create *useCases.CreateVariantUseCase, update *useCases.UpdateVariantUseCase, setEnabled *useCases.SetVariantEnabledUseCase, remove *useCases.DeleteVariantUseCase, purge *useCases.PurgeVariantUseCase, cacheStats *useCases.GetVariantCacheStatsUseCase, purgeCache *useCases.PurgeVariantCacheUseCase) *Handler {
+	return &Handler{list, create, update, setEnabled, remove, purge, cacheStats, purgeCache}
+}
+
+type definitionRequest struct {
+	Width   *int   `json:"width" validate:"required_without=Height,omitempty,min=1,max=8000"`
+	Height  *int   `json:"height" validate:"required_without=Width,omitempty,min=1,max=8000"`
+	Fit     string `json:"fit" validate:"omitempty,oneof=cover contain inside"`
+	Format  string `json:"format" validate:"omitempty,oneof=original jpeg png webp"`
+	Quality *int   `json:"quality" validate:"omitempty,min=1,max=100"`
+}
+
+type switchesRequest struct {
+	GenerateOnUpload *bool `json:"generate_on_upload"`
+	Enabled          *bool `json:"enabled"`
+}
+
+type createRequest struct {
+	Name string `json:"name" validate:"required,variantname"`
+	definitionRequest
+	switchesRequest
+}
+
+type updateRequest struct {
+	definitionRequest
+	switchesRequest
+}
+
+type enabledRequest struct {
+	Enabled *bool `json:"enabled" validate:"required"`
+}
+
+type variantResponse struct {
+	Name             string              `json:"name"`
+	Width            *int                `json:"width"`
+	Height           *int                `json:"height"`
+	Fit              image.VariantFit    `json:"fit"`
+	Format           image.VariantFormat `json:"format"`
+	Quality          *int                `json:"quality"`
+	GenerateOnUpload bool                `json:"generate_on_upload"`
+	Enabled          bool                `json:"enabled"`
+	GeneratedFiles   int                 `json:"generated_files"`
+	CacheSize        int64               `json:"cache_size"`
+	CreatedAt        time.Time           `json:"created_at"`
+	UpdatedAt        time.Time           `json:"updated_at"`
+}
+
+type updatedVariantResponse struct {
+	variantResponse
+	PurgedFiles int `json:"purged_files"`
+}
+
+type listResponse struct {
+	Items []variantResponse `json:"items"`
+}
+
+type purgeResponse struct {
+	PurgedFiles int   `json:"purged_files"`
+	PurgedBytes int64 `json:"purged_bytes"`
+}
+
+func responseOf(summary useCases.VariantSummary) variantResponse {
+	variant := summary.Variant
+	return variantResponse{
+		Name:             variant.Name,
+		Width:            variant.Width,
+		Height:           variant.Height,
+		Fit:              variant.Fit,
+		Format:           variant.Format,
+		Quality:          variant.Quality,
+		GenerateOnUpload: variant.GenerateOnUpload,
+		Enabled:          variant.Enabled,
+		GeneratedFiles:   summary.GeneratedFiles,
+		CacheSize:        summary.CacheSize,
+		CreatedAt:        variant.CreatedAt,
+		UpdatedAt:        variant.UpdatedAt,
+	}
+}
+
+func (h *Handler) List(w http.ResponseWriter, _ *http.Request) {
+	summaries, err := h.list.List()
+	if err != nil {
+		h.writeError(w, "", err)
+		return
+	}
+	items := make([]variantResponse, 0, len(summaries))
+	for _, summary := range summaries {
+		items = append(items, responseOf(summary))
+	}
+	writeJSON(w, http.StatusOK, listResponse{items})
+}
+
+func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
+	var request createRequest
+	if !h.decode(w, r, &request) {
+		return
+	}
+
+	summary, err := h.create.Create(r.Context(), useCases.CreateVariantCommand{
+		Name:                     request.Name,
+		VariantDefinitionCommand: request.definitionRequest.command(),
+		GenerateOnUpload:         request.GenerateOnUpload,
+		Enabled:                  request.Enabled,
+	})
+	if err != nil {
+		h.writeError(w, request.Name, err)
+		return
+	}
+	writeJSON(w, http.StatusCreated, responseOf(summary))
+}
+
+func (h *Handler) Update(w http.ResponseWriter, r *http.Request) {
+	var request updateRequest
+	if !h.decode(w, r, &request) {
+		return
+	}
+
+	name := chi.URLParam(r, "name")
+	result, err := h.update.Update(r.Context(), useCases.UpdateVariantCommand{
+		Name:                     name,
+		VariantDefinitionCommand: request.definitionRequest.command(),
+		GenerateOnUpload:         request.GenerateOnUpload,
+		Enabled:                  request.Enabled,
+	})
+	if err != nil {
+		h.writeError(w, name, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, updatedVariantResponse{responseOf(result.VariantSummary), result.PurgedFiles})
+}
+
+func (h *Handler) SetEnabled(w http.ResponseWriter, r *http.Request) {
+	var request enabledRequest
+	if !h.decode(w, r, &request) {
+		return
+	}
+
+	name := chi.URLParam(r, "name")
+	summary, err := h.setEnabled.SetEnabled(r.Context(), name, *request.Enabled)
+	if err != nil {
+		h.writeError(w, name, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, responseOf(summary))
+}
+
+func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	if err := h.remove.Delete(r.Context(), name); err != nil {
+		h.writeError(w, name, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (h *Handler) Purge(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	purged, err := h.purge.Purge(r.Context(), name)
+	if err != nil {
+		h.writeError(w, name, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, purgeResponse{purged.Files, purged.Bytes})
+}
+
+func (d definitionRequest) command() useCases.VariantDefinitionCommand {
+	return useCases.VariantDefinitionCommand{Width: d.Width, Height: d.Height, Fit: d.Fit, Format: d.Format, Quality: d.Quality}
+}
+
+func (h *Handler) decode(w http.ResponseWriter, r *http.Request, request any) bool {
+	if err := json.NewDecoder(r.Body).Decode(request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return false
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, h.validationMessage(err), http.StatusUnprocessableEntity)
+		return false
+	}
+	return true
+}
+
+func (h *Handler) validationMessage(err error) string {
+	var failures validatorlib.ValidationErrors
+	if !errors.As(err, &failures) || len(failures) == 0 {
+		return apperr.VariantInvalidErrorMessage
+	}
+	switch failures[0].StructField() {
+	case "Name":
+		return apperr.VariantNameErrorMessage
+	case "Width", "Height":
+		return apperr.VariantDimensionsErrorMessage
+	case "Fit":
+		return apperr.VariantFitErrorMessage
+	case "Format":
+		return h.formatMessage()
+	case "Quality":
+		return apperr.VariantQualityErrorMessage
+	default:
+		return apperr.VariantInvalidErrorMessage
+	}
+}
+
+func (h *Handler) formatMessage() string {
+	encodable := h.create.EncodableFormats()
+	names := make([]string, 0, len(encodable))
+	for _, format := range encodable {
+		names = append(names, string(format))
+	}
+	last := len(names) - 1
+	return fmt.Sprintf(apperr.VariantFormatErrorMessageFormat, strings.Join(names[:last], ", ")+" or "+names[last])
+}
+
+func (h *Handler) writeError(w http.ResponseWriter, name string, err error) {
+	switch {
+	case errors.Is(err, image.ErrVariantNotFound):
+		http.Error(w, apperr.VariantNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, image.ErrVariantExists):
+		http.Error(w, fmt.Sprintf(apperr.VariantExistsErrorMessageFormat, name), http.StatusConflict)
+	case errors.Is(err, image.ErrVariantFormatUnavailable):
+		http.Error(w, h.formatMessage(), http.StatusUnprocessableEntity)
+	case errors.Is(err, image.ErrVariantInvalid):
+		http.Error(w, apperr.VariantInvalidErrorMessage, http.StatusUnprocessableEntity)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func writeJSON(w http.ResponseWriter, status int, value any) {
+	body, err := json.Marshal(value)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.WriteHeader(status)
+	_, _ = w.Write(body)
+}

api/handlers/llms/llmsHandler.go

@@ -0,0 +1,76 @@
+package llms
+
+import (
+	"io/fs"
+	"net/http"
+	"path"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+)
+
+const (
+	versionPlaceholder = "{{VERSION}}"
+	baseURLPlaceholder = "{{BASE_URL}}"
+	pageSuffix         = ".md"
+	cacheControl       = "public, max-age=300"
+	notBuiltNotice     = "The LLM documentation was not generated for this build. Run `task build:llms`."
+)
+
+type Handler struct {
+	docs    fs.FS
+	version string
+	baseURL string
+}
+
+func NewHandler(docs fs.FS, version string, publicURL string) *Handler {
+	return &Handler{
+		docs:    docs,
+		version: version,
+		baseURL: strings.TrimRight(publicURL, "/"),
+	}
+}
+
+func (h *Handler) Register(r chi.Router) {
+	r.Get("/llms.txt", h.serve("llms.txt", "text/plain; charset=utf-8"))
+	r.Get("/llms-full.txt", h.serve("llms-full.txt", "text/plain; charset=utf-8"))
+	r.Get("/openapi.json", h.serve("openapi.json", "application/json"))
+	r.Get("/llms/{page}", h.page)
+}
+
+func (h *Handler) page(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "page")
+	if !strings.HasSuffix(name, pageSuffix) || strings.ContainsAny(name, "/\\") {
+		h.notFound(w)
+		return
+	}
+	h.write(w, path.Join("llms", name), "text/markdown; charset=utf-8")
+}
+
+func (h *Handler) serve(name string, contentType string) http.HandlerFunc {
+	return func(w http.ResponseWriter, _ *http.Request) {
+		h.write(w, name, contentType)
+	}
+}
+
+func (h *Handler) write(w http.ResponseWriter, name string, contentType string) {
+	if h.docs == nil {
+		h.notFound(w)
+		return
+	}
+	raw, err := fs.ReadFile(h.docs, name)
+	if err != nil {
+		h.notFound(w)
+		return
+	}
+	text := strings.NewReplacer(versionPlaceholder, h.version, baseURLPlaceholder, h.baseURL).Replace(string(raw))
+	w.Header().Set("Content-Type", contentType)
+	w.Header().Set("Cache-Control", cacheControl)
+	_, _ = w.Write([]byte(text))
+}
+
+func (h *Handler) notFound(w http.ResponseWriter) {
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.WriteHeader(http.StatusNotFound)
+	_, _ = w.Write([]byte(notBuiltNotice))
+}

api/handlers/media/mediaHandler.go

@@ -0,0 +1,402 @@
+package media
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/api/pkg/upload"
+	validator "RenewCMS/api/pkg/validator"
+	domainImage "RenewCMS/internal/domain/image"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	CreateUseCase              *useCases.CreateImageUseCase
+	ListUseCase                *useCases.ListMediaUseCase
+	RenameUseCase              *useCases.RenameMediaUseCase
+	DeleteUseCase              *useCases.DeleteMediaUseCase
+	MergeUseCase               *useCases.MergeMediaUseCase
+	UsageUseCase               *useCases.GetMediaUsageUseCase
+	PurgeSettingsUseCase       *useCases.GetPurgeSettingsUseCase
+	UpdatePurgeSettingsUseCase *useCases.UpdatePurgeSettingsUseCase
+	PreviewPurgeUseCase        *useCases.PreviewPurgeUseCase
+	RunPurgeUseCase            *useCases.RunPurgeUseCase
+	ListVariantsUseCase        *useCases.ListImageVariantsUseCase
+	GenerateVariantUseCase     *useCases.GenerateImageVariantUseCase
+	GenerateAllUseCase         *useCases.GenerateAllImageVariantsUseCase
+	PurgeVariantUseCase        *useCases.PurgeImageVariantUseCase
+	GenerateOnUploadUseCase    *useCases.GenerateVariantsOnUploadUseCase
+}
+
+type RenameRequest struct {
+	Filename string `json:"filename" validate:"required"`
+}
+
+type MergeRequest struct {
+	KeepID   uint32   `json:"keep_id" validate:"required,gt=0"`
+	MergeIDs []uint32 `json:"merge_ids" validate:"required,min=1,dive,gt=0"`
+}
+
+type mediaItemResponse struct {
+	ID          uint32    `json:"id"`
+	Filename    string    `json:"filename"`
+	URL         string    `json:"url"`
+	Size        int64     `json:"size"`
+	ContentType string    `json:"content_type"`
+	Width       *int      `json:"width"`
+	Height      *int      `json:"height"`
+	SHA256      string    `json:"sha256"`
+	UploadedBy  string    `json:"uploaded_by"`
+	CreatedAt   time.Time `json:"created_at"`
+	UsedIn      int       `json:"used_in"`
+	Duplicate   bool      `json:"duplicate"`
+
+	VariantCount int   `json:"variant_count"`
+	VariantSize  int64 `json:"variant_size"`
+}
+
+type countsResponse struct {
+	All        int `json:"all"`
+	Unused     int `json:"unused"`
+	Duplicates int `json:"duplicates"`
+}
+
+type listResponse struct {
+	Items  []mediaItemResponse `json:"items"`
+	Total  int                 `json:"total"`
+	Page   int                 `json:"page"`
+	Size   int                 `json:"size"`
+	Counts countsResponse      `json:"counts"`
+}
+
+type pagingQuery struct {
+	Page int `validate:"gte=1"`
+	Size int `validate:"oneof=5 25 50 100"`
+}
+
+func intQueryParam(values url.Values, name string, fallback int) (int, error) {
+	if !values.Has(name) {
+		return fallback, nil
+	}
+	return strconv.Atoi(values.Get(name))
+}
+
+type usageResponse struct {
+	Type      string   `json:"type"`
+	ID        uint32   `json:"id"`
+	Title     string   `json:"title,omitempty"`
+	Published *bool    `json:"published,omitempty"`
+	Fields    []string `json:"fields"`
+
+	ContentTypeKey  string               `json:"content_type_key,omitempty"`
+	ContentTypeName string               `json:"content_type_name,omitempty"`
+	FirstField      *usageFirstFieldBody `json:"first_field,omitempty"`
+}
+
+type usageFirstFieldBody struct {
+	Key   string `json:"key"`
+	Type  string `json:"type"`
+	Value any    `json:"value"`
+}
+
+func toUsageResponse(usage useCases.MediaUsage) usageResponse {
+	body := usageResponse{Type: usage.Type, ID: usage.ID, Title: usage.Title, Published: usage.Published, Fields: usage.Fields, ContentTypeKey: usage.ContentTypeKey, ContentTypeName: usage.ContentTypeName}
+	if usage.FirstField != nil {
+		body.FirstField = &usageFirstFieldBody{Key: usage.FirstField.Key, Type: string(usage.FirstField.Type), Value: usage.FirstField.Value}
+	}
+	return body
+}
+
+type mergeResponse struct {
+	ArticlesUpdated int `json:"articles_updated"`
+	SitesUpdated    int `json:"sites_updated"`
+	AuthorsUpdated  int `json:"authors_updated"`
+	Merged          int `json:"merged"`
+}
+
+func NewHandler(create *useCases.CreateImageUseCase, list *useCases.ListMediaUseCase, rename *useCases.RenameMediaUseCase, deleteUseCase *useCases.DeleteMediaUseCase, merge *useCases.MergeMediaUseCase, usage *useCases.GetMediaUsageUseCase, purgeSettings *useCases.GetPurgeSettingsUseCase, updatePurgeSettings *useCases.UpdatePurgeSettingsUseCase, previewPurge *useCases.PreviewPurgeUseCase, runPurge *useCases.RunPurgeUseCase, listVariants *useCases.ListImageVariantsUseCase, generateVariant *useCases.GenerateImageVariantUseCase, generateAll *useCases.GenerateAllImageVariantsUseCase, purgeVariant *useCases.PurgeImageVariantUseCase, generateOnUpload *useCases.GenerateVariantsOnUploadUseCase) *Handler {
+	return &Handler{
+		CreateUseCase:              create,
+		ListUseCase:                list,
+		RenameUseCase:              rename,
+		DeleteUseCase:              deleteUseCase,
+		MergeUseCase:               merge,
+		UsageUseCase:               usage,
+		PurgeSettingsUseCase:       purgeSettings,
+		UpdatePurgeSettingsUseCase: updatePurgeSettings,
+		PreviewPurgeUseCase:        previewPurge,
+		RunPurgeUseCase:            runPurge,
+		ListVariantsUseCase:        listVariants,
+		GenerateVariantUseCase:     generateVariant,
+		GenerateAllUseCase:         generateAll,
+		PurgeVariantUseCase:        purgeVariant,
+		GenerateOnUploadUseCase:    generateOnUpload,
+	}
+}
+
+func writeInternalServerError(w http.ResponseWriter) {
+	http.Error(w, "Internal server error", http.StatusInternalServerError)
+}
+
+func writeJSON(w http.ResponseWriter, status int, payload any) {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		writeInternalServerError(w)
+		return
+	}
+	w.WriteHeader(status)
+	_, _ = w.Write(body)
+}
+
+func writeImageError(w http.ResponseWriter, err error) {
+	if errors.Is(err, domainImage.ErrImageNotFound) {
+		http.Error(w, apperr.ImageNotFoundErrorMessage, http.StatusNotFound)
+		return
+	}
+	writeInternalServerError(w)
+}
+
+func parseImageId(w http.ResponseWriter, r *http.Request) (uint32, bool) {
+	id, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return 0, false
+	}
+	return uint32(id), true
+}
+
+func dimension(value int) *int {
+	if value == 0 {
+		return nil
+	}
+	return &value
+}
+
+func toResponse(item useCases.MediaItem) mediaItemResponse {
+	return mediaItemResponse{
+		ID:          item.Image.ID,
+		Filename:    item.Image.Filename,
+		URL:         item.Image.Path,
+		Size:        item.Image.Size,
+		ContentType: item.Image.ContentType,
+		Width:       dimension(item.Image.Width),
+		Height:      dimension(item.Image.Height),
+		SHA256:      item.Image.SHA256,
+		UploadedBy:  item.UploadedBy,
+		CreatedAt:   item.Image.CreatedAt,
+		UsedIn:      item.UsedIn,
+		Duplicate:   item.Duplicate,
+
+		VariantCount: item.VariantCount,
+		VariantSize:  item.VariantSize,
+	}
+}
+
+func parseListQuery(r *http.Request) (domainImage.ListQuery, error) {
+	values, err := url.ParseQuery(r.URL.RawQuery)
+	if err != nil {
+		return domainImage.ListQuery{}, domainImage.ErrInvalidQuery
+	}
+
+	query := domainImage.NewListQuery()
+	query.Search = values.Get("q")
+	query.Hash = strings.ToLower(values.Get("hash"))
+	if values.Has("filter") {
+		query.Filter = domainImage.Filter(values.Get("filter"))
+	}
+	if values.Has("variants") {
+		if values.Get("variants") == "" {
+			return domainImage.ListQuery{}, domainImage.ErrInvalidQuery
+		}
+		query.Variants = domainImage.VariantsFilter(values.Get("variants"))
+	}
+	if values.Has("sort") {
+		query.Sort = domainImage.Sort(values.Get("sort"))
+	}
+	page, err := intQueryParam(values, "page", domainImage.DefaultListPage)
+	if err != nil {
+		return domainImage.ListQuery{}, domainImage.ErrInvalidQuery
+	}
+	size, err := intQueryParam(values, "size", domainImage.DefaultListSize)
+	if err != nil {
+		return domainImage.ListQuery{}, domainImage.ErrInvalidQuery
+	}
+	if validator.Validate.Struct(pagingQuery{Page: page, Size: size}) != nil {
+		return domainImage.ListQuery{}, domainImage.ErrInvalidQuery
+	}
+	query.Page = page
+	query.Size = size
+	return query, nil
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	query, err := parseListQuery(r)
+	if err != nil {
+		http.Error(w, apperr.MediaQueryErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	page, err := h.ListUseCase.List(query)
+	if err != nil {
+		if errors.Is(err, domainImage.ErrInvalidQuery) {
+			http.Error(w, apperr.MediaQueryErrorMessage, http.StatusBadRequest)
+			return
+		}
+		writeInternalServerError(w)
+		return
+	}
+
+	items := make([]mediaItemResponse, 0, len(page.Items))
+	for _, item := range page.Items {
+		items = append(items, toResponse(item))
+	}
+	response := listResponse{
+		Items:  items,
+		Total:  page.Total,
+		Page:   page.Page,
+		Size:   page.Size,
+		Counts: countsResponse{All: page.Counts.All, Unused: page.Counts.Unused, Duplicates: page.Counts.Duplicates},
+	}
+	writeJSON(w, http.StatusOK, response)
+}
+
+func (h *Handler) Get(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+	item, err := h.ListUseCase.Get(id)
+	if err != nil {
+		writeImageError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, toResponse(item))
+}
+
+func (h *Handler) Upload(w http.ResponseWriter, r *http.Request) {
+	userId, _ := claims.UserId(r)
+	input, closeFile, ok := upload.ReadImageInput(w, r, userId)
+	if !ok {
+		return
+	}
+	defer closeFile()
+
+	created, err := h.CreateUseCase.CreateImage(r.Context(), input)
+	if err != nil {
+		upload.WriteCreateError(w, err)
+		return
+	}
+
+	h.GenerateOnUploadUseCase.Generate(r.Context(), created)
+	h.writeItem(w, http.StatusCreated, created)
+}
+
+func (h *Handler) writeItem(w http.ResponseWriter, status int, img domainImage.Image) {
+	item, err := h.ListUseCase.Describe(img)
+	if err != nil {
+		writeInternalServerError(w)
+		return
+	}
+	writeJSON(w, status, toResponse(item))
+}
+
+func (h *Handler) Rename(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	var request RenameRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, apperr.MediaFilenameErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	renamed, err := h.RenameUseCase.Rename(r.Context(), id, request.Filename)
+	if err != nil {
+		if errors.Is(err, domainImage.ErrInvalidFilename) {
+			http.Error(w, apperr.MediaFilenameErrorMessage, http.StatusBadRequest)
+			return
+		}
+		writeImageError(w, err)
+		return
+	}
+
+	h.writeItem(w, http.StatusOK, renamed)
+}
+
+func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	if err := h.DeleteUseCase.Delete(r.Context(), id); err != nil {
+		writeImageError(w, err)
+		return
+	}
+
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (h *Handler) Usage(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	usages, err := h.UsageUseCase.Usage(id)
+	if err != nil {
+		writeImageError(w, err)
+		return
+	}
+
+	response := make([]usageResponse, 0, len(usages))
+	for _, usage := range usages {
+		response = append(response, toUsageResponse(usage))
+	}
+	writeJSON(w, http.StatusOK, response)
+}
+
+func (h *Handler) Merge(w http.ResponseWriter, r *http.Request) {
+	var request MergeRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.MediaMergeRequestErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, apperr.MediaMergeRequestErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	result, err := h.MergeUseCase.Merge(r.Context(), request.KeepID, request.MergeIDs)
+	if err != nil {
+		writeMergeError(w, err)
+		return
+	}
+
+	writeJSON(w, http.StatusOK, mergeResponse{ArticlesUpdated: result.ArticlesUpdated, SitesUpdated: result.SitesUpdated, AuthorsUpdated: result.AuthorsUpdated, Merged: result.Merged})
+}
+
+func writeMergeError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, domainImage.ErrInvalidMergeRequest):
+		http.Error(w, apperr.MediaMergeRequestErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domainImage.ErrMergeCopyMissing), errors.Is(err, domainImage.ErrMergeHashMismatch):
+		http.Error(w, apperr.MediaMergeConflictErrorMessage, http.StatusConflict)
+	default:
+		writeImageError(w, err)
+	}
+}

api/handlers/media/purgeHandler.go

@@ -0,0 +1,173 @@
+package media
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/purge"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"time"
+)
+
+type PurgeSettingsRequest struct {
+	AutoPurgeEnabled      *bool `json:"auto_purge_enabled"`
+	AutoPurgeIntervalDays *int  `json:"auto_purge_interval_days" validate:"omitempty,gte=1,lte=365"`
+}
+
+type PurgeRunRequest struct {
+	Fingerprint *string `json:"fingerprint"`
+}
+
+type purgeSettingsResponse struct {
+	AutoPurgeEnabled         bool       `json:"auto_purge_enabled"`
+	AutoPurgeIntervalDays    int        `json:"auto_purge_interval_days"`
+	LastPurgeAt              *time.Time `json:"last_purge_at"`
+	LastPurgeMerged          int        `json:"last_purge_merged"`
+	LastPurgeArticlesUpdated int        `json:"last_purge_articles_updated"`
+	EnabledAt                *time.Time `json:"enabled_at"`
+	NextPurgeAt              *time.Time `json:"next_purge_at"`
+}
+
+type purgePreviewGroupResponse struct {
+	KeepID   uint32 `json:"keep_id"`
+	Filename string `json:"filename"`
+	URL      string `json:"url"`
+	UsedIn   int    `json:"used_in"`
+	Merged   int    `json:"merged"`
+}
+
+type purgePreviewResponse struct {
+	Groups      int                         `json:"groups"`
+	Copies      int                         `json:"copies"`
+	Articles    int                         `json:"articles"`
+	List        []purgePreviewGroupResponse `json:"list"`
+	More        int                         `json:"more"`
+	Fingerprint string                      `json:"fingerprint"`
+}
+
+type purgeRunResponse struct {
+	GroupsTotal     int `json:"groups_total"`
+	GroupsPurged    int `json:"groups_purged"`
+	Merged          int `json:"merged"`
+	ArticlesUpdated int `json:"articles_updated"`
+	SitesUpdated    int `json:"sites_updated"`
+	AuthorsUpdated  int `json:"authors_updated"`
+	FailedGroups    int `json:"failed_groups"`
+}
+
+func toPurgeSettingsResponse(settings purge.Settings) purgeSettingsResponse {
+	return purgeSettingsResponse{
+		AutoPurgeEnabled:         settings.AutoPurgeEnabled,
+		AutoPurgeIntervalDays:    settings.AutoPurgeIntervalDays,
+		LastPurgeAt:              settings.LastPurgeAt,
+		LastPurgeMerged:          settings.LastPurgeMerged,
+		LastPurgeArticlesUpdated: settings.LastPurgeArticlesUpdated,
+		EnabledAt:                settings.EnabledAt,
+		NextPurgeAt:              settings.NextPurgeAt(),
+	}
+}
+
+func writePurgeError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, purge.ErrInvalidPurgeInterval):
+		http.Error(w, apperr.PurgeIntervalErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, purge.ErrPurgeConflict):
+		http.Error(w, apperr.PurgeConflictErrorMessage, http.StatusConflict)
+	case errors.Is(err, purge.ErrPurgeBusy):
+		http.Error(w, apperr.PurgeBusyErrorMessage, http.StatusConflict)
+	default:
+		writeInternalServerError(w)
+	}
+}
+
+func (h *Handler) GetPurgeSettings(w http.ResponseWriter, _ *http.Request) {
+	settings, err := h.PurgeSettingsUseCase.Get()
+	if err != nil {
+		writePurgeError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, toPurgeSettingsResponse(settings))
+}
+
+func (h *Handler) UpdatePurgeSettings(w http.ResponseWriter, r *http.Request) {
+	var request PurgeSettingsRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, apperr.PurgeIntervalErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	settings, err := h.UpdatePurgeSettingsUseCase.Update(useCases.UpdatePurgeSettingsCommand{
+		AutoPurgeEnabled:      request.AutoPurgeEnabled,
+		AutoPurgeIntervalDays: request.AutoPurgeIntervalDays,
+	})
+	if err != nil {
+		writePurgeError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, toPurgeSettingsResponse(settings))
+}
+
+func (h *Handler) PreviewPurge(w http.ResponseWriter, _ *http.Request) {
+	preview, err := h.PreviewPurgeUseCase.Preview()
+	if err != nil {
+		writePurgeError(w, err)
+		return
+	}
+
+	list := make([]purgePreviewGroupResponse, 0, len(preview.List))
+	for _, group := range preview.List {
+		list = append(list, purgePreviewGroupResponse{
+			KeepID:   group.KeepID,
+			Filename: group.Filename,
+			URL:      group.URL,
+			UsedIn:   group.UsedIn,
+			Merged:   group.Merged,
+		})
+	}
+	writeJSON(w, http.StatusOK, purgePreviewResponse{
+		Groups:      preview.Groups,
+		Copies:      preview.Copies,
+		Articles:    preview.Articles,
+		List:        list,
+		More:        preview.More,
+		Fingerprint: preview.Fingerprint,
+	})
+}
+
+func (h *Handler) RunPurge(w http.ResponseWriter, r *http.Request) {
+	raw, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	var request PurgeRunRequest
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &request); err != nil {
+			http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+			return
+		}
+	}
+
+	result, err := h.RunPurgeUseCase.Run(r.Context(), request.Fingerprint)
+	if err != nil {
+		writePurgeError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, purgeRunResponse{
+		GroupsTotal:     result.GroupsTotal,
+		GroupsPurged:    result.GroupsPurged,
+		Merged:          result.Merged,
+		ArticlesUpdated: result.ArticlesUpdated,
+		SitesUpdated:    result.SitesUpdated,
+		AuthorsUpdated:  result.AuthorsUpdated,
+		FailedGroups:    result.FailedGroups,
+	})
+}

api/handlers/media/variantsHandler.go

@@ -0,0 +1,161 @@
+package media
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	domainImage "RenewCMS/internal/domain/image"
+	"RenewCMS/internal/infrastructure/useCases"
+	"errors"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type imageVariantResponse struct {
+	Name         string                    `json:"name"`
+	Width        *int                      `json:"width"`
+	Height       *int                      `json:"height"`
+	Fit          domainImage.VariantFit    `json:"fit"`
+	Format       domainImage.VariantFormat `json:"format"`
+	OutputWidth  int                       `json:"output_width"`
+	OutputHeight int                       `json:"output_height"`
+	OutputFormat domainImage.VariantFormat `json:"output_format"`
+	Generated    bool                      `json:"generated"`
+	Size         *int64                    `json:"size"`
+	URL          string                    `json:"url"`
+}
+
+type imageVariantListResponse struct {
+	Unsupported *string                `json:"unsupported"`
+	Items       []imageVariantResponse `json:"items"`
+}
+
+type variantFailureResponse struct {
+	Name  string `json:"name"`
+	Cause string `json:"cause"`
+}
+
+type generateAllResponse struct {
+	Generated int                      `json:"generated"`
+	Failed    int                      `json:"failed"`
+	Failures  []variantFailureResponse `json:"failures"`
+	Items     []imageVariantResponse   `json:"items"`
+}
+
+type variantPurgeResponse struct {
+	PurgedFiles int   `json:"purged_files"`
+	PurgedBytes int64 `json:"purged_bytes"`
+}
+
+func toImageVariantResponse(view useCases.ImageVariantView) imageVariantResponse {
+	response := imageVariantResponse{
+		Name:         view.Variant.Name,
+		Width:        view.Variant.Width,
+		Height:       view.Variant.Height,
+		Fit:          view.Variant.Fit,
+		Format:       view.Variant.Format,
+		OutputWidth:  view.OutputWidth,
+		OutputHeight: view.OutputHeight,
+		OutputFormat: view.OutputFormat,
+		Generated:    view.Generated,
+		URL:          view.URL,
+	}
+	if view.Generated {
+		size := view.Size
+		response.Size = &size
+	}
+	return response
+}
+
+func toImageVariantResponses(views []useCases.ImageVariantView) []imageVariantResponse {
+	items := make([]imageVariantResponse, 0, len(views))
+	for _, view := range views {
+		items = append(items, toImageVariantResponse(view))
+	}
+	return items
+}
+
+func writeImageVariantError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, domainImage.ErrVariantNotFound):
+		http.Error(w, apperr.VariantNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, domainImage.ErrVariantSourceUnsupported):
+		http.Error(w, apperr.VariantSourceUnsupportedErrorMessage, http.StatusUnprocessableEntity)
+	case errors.Is(err, domainImage.ErrSourceTooLarge):
+		http.Error(w, apperr.VariantSourceTooLargeErrorMessage, http.StatusRequestEntityTooLarge)
+	case errors.Is(err, domainImage.ErrVariantSourceUnreadable):
+		http.Error(w, apperr.VariantSourceUnreadableErrorMessage, http.StatusUnsupportedMediaType)
+	default:
+		writeImageError(w, err)
+	}
+}
+
+func (h *Handler) ListVariants(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	list, err := h.ListVariantsUseCase.List(id)
+	if err != nil {
+		writeImageVariantError(w, err)
+		return
+	}
+
+	response := imageVariantListResponse{Items: toImageVariantResponses(list.Items)}
+	if list.Unsupported != "" {
+		response.Unsupported = &list.Unsupported
+	}
+	writeJSON(w, http.StatusOK, response)
+}
+
+func (h *Handler) GenerateVariant(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	view, err := h.GenerateVariantUseCase.Generate(r.Context(), id, chi.URLParam(r, "name"))
+	if err != nil {
+		writeImageVariantError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, toImageVariantResponse(view))
+}
+
+func (h *Handler) GenerateAllVariants(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	result, err := h.GenerateAllUseCase.Generate(r.Context(), id)
+	if err != nil {
+		writeImageVariantError(w, err)
+		return
+	}
+
+	failures := make([]variantFailureResponse, 0, len(result.Failures))
+	for _, failure := range result.Failures {
+		failures = append(failures, variantFailureResponse{Name: failure.Name, Cause: failure.Cause})
+	}
+	writeJSON(w, http.StatusOK, generateAllResponse{
+		Generated: result.Generated,
+		Failed:    result.Failed,
+		Failures:  failures,
+		Items:     toImageVariantResponses(result.Items),
+	})
+}
+
+func (h *Handler) PurgeVariant(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	purged, err := h.PurgeVariantUseCase.Purge(r.Context(), id, chi.URLParam(r, "name"))
+	if err != nil {
+		writeImageVariantError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, variantPurgeResponse{PurgedFiles: purged.Files, PurgedBytes: purged.Bytes})
+}

api/handlers/ownership/ownershipHandler.go

@@ -0,0 +1,69 @@
+package ownership
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/payload"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+)
+
+type Handler struct {
+	TransferUseCase *useCases.TransferOwnershipUseCase
+}
+
+type TransferRequest struct {
+	UserID       uint32 `json:"user_id" validate:"required"`
+	ConfirmEmail string `json:"confirm_email" validate:"required"`
+}
+
+func NewHandler(transfer *useCases.TransferOwnershipUseCase) *Handler {
+	return &Handler{TransferUseCase: transfer}
+}
+
+func (h *Handler) Transfer(w http.ResponseWriter, r *http.Request) {
+	var request TransferRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	transferred, err := h.TransferUseCase.Transfer(r.Context(), useCases.TransferOwnershipCommand{
+		Caller:       access.CallerOf(r),
+		UserID:       request.UserID,
+		ConfirmEmail: request.ConfirmEmail,
+	})
+	if err != nil {
+		writeTransferError(w, err)
+		return
+	}
+
+	body, err := json.Marshal(payload.OwnershipTransferOf(transferred))
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}
+
+func writeTransferError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, user.ErrInvalidTransfer):
+		http.Error(w, apperr.InvalidTransferErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, user.ErrConfirmationMismatch):
+		http.Error(w, apperr.ConfirmationMismatchErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, user.ErrRoleChanged):
+		http.Error(w, apperr.UserRoleChangedErrorMessage, http.StatusConflict)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}

api/handlers/permission/permissionHandler.go

@@ -0,0 +1,53 @@
+package permission
+
+import (
+	"RenewCMS/internal/domain/role"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"net/http"
+)
+
+type Handler struct {
+	ListUseCase *useCases.ListPermissionsUseCase
+}
+
+func NewHandler(list *useCases.ListPermissionsUseCase) *Handler {
+	return &Handler{ListUseCase: list}
+}
+
+type permissionItem struct {
+	Key       string    `json:"key"`
+	ScopeKind role.Kind `json:"scope_kind"`
+	OwnerOnly bool      `json:"owner_only"`
+	PerType   bool      `json:"per_type"`
+}
+
+type permissionGroup struct {
+	Key   string           `json:"key"`
+	Items []permissionItem `json:"items"`
+}
+
+type permissionResponse struct {
+	Groups []permissionGroup `json:"groups"`
+}
+
+func toResponse(groups []useCases.PermissionGroup) permissionResponse {
+	response := permissionResponse{Groups: make([]permissionGroup, 0, len(groups))}
+	for _, group := range groups {
+		items := make([]permissionItem, 0, len(group.Items))
+		for _, permission := range group.Items {
+			items = append(items, permissionItem{Key: permission.Key, ScopeKind: permission.Kind, OwnerOnly: permission.OwnerOnly, PerType: permission.PerType()})
+		}
+		response.Groups = append(response.Groups, permissionGroup{Key: group.Key, Items: items})
+	}
+	return response
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	body, err := json.Marshal(toResponse(h.ListUseCase.List()))
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	_, _ = w.Write(body)
+}

api/handlers/role/roleHandler.go

@@ -0,0 +1,251 @@
+package role
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/payload"
+	validator "RenewCMS/api/pkg/validator"
+	domain "RenewCMS/internal/domain/role"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"log"
+	"net/http"
+	"strconv"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	ListUseCase     *useCases.ListRolesUseCase
+	GetUseCase      *useCases.GetRoleUseCase
+	CreateUseCase   *useCases.CreateRoleUseCase
+	UpdateUseCase   *useCases.UpdateRoleUseCase
+	DeleteUseCase   *useCases.DeleteRoleUseCase
+	ReassignUseCase *useCases.ReassignRoleMembersUseCase
+}
+
+func NewHandler(list *useCases.ListRolesUseCase, get *useCases.GetRoleUseCase, create *useCases.CreateRoleUseCase, update *useCases.UpdateRoleUseCase, deleteUseCase *useCases.DeleteRoleUseCase, reassign *useCases.ReassignRoleMembersUseCase) *Handler {
+	return &Handler{ListUseCase: list, GetUseCase: get, CreateUseCase: create, UpdateUseCase: update, DeleteUseCase: deleteUseCase, ReassignUseCase: reassign}
+}
+
+type GrantRequest struct {
+	Key   string `json:"key" validate:"required,max=100"`
+	Scope string `json:"scope"`
+}
+
+type PostRole struct {
+	Name        string         `json:"name" validate:"required,max=100"`
+	Description string         `json:"description" validate:"max=255"`
+	Grants      []GrantRequest `json:"grants" validate:"dive"`
+}
+
+type PutRole struct {
+	Name        string         `json:"name" validate:"required,max=100"`
+	Description string         `json:"description" validate:"max=255"`
+	Grants      []GrantRequest `json:"grants" validate:"dive"`
+	Version     uint32         `json:"version" validate:"required,min=1"`
+}
+
+type ResetRole struct {
+	Version uint32 `json:"version" validate:"required,min=1"`
+}
+
+type ReassignRole struct {
+	TargetRoleID uint32 `json:"target_role_id" validate:"required"`
+}
+
+func toGrants(requested []GrantRequest) []domain.Grant {
+	grants := make([]domain.Grant, 0, len(requested))
+	for _, grant := range requested {
+		grants = append(grants, domain.Grant{Key: grant.Key, Scope: domain.Scope(grant.Scope)})
+	}
+	return grants
+}
+
+func parseRoleId(r *http.Request) (uint32, error) {
+	id, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	return uint32(id), err
+}
+
+func decodeRequest(w http.ResponseWriter, r *http.Request, request any) bool {
+	if err := json.NewDecoder(r.Body).Decode(request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return false
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return false
+	}
+	return true
+}
+
+func readId(w http.ResponseWriter, r *http.Request) (uint32, bool) {
+	id, err := parseRoleId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return 0, false
+	}
+	return id, true
+}
+
+func writeJSON(w http.ResponseWriter, status int, payload any) {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+	if status != http.StatusOK {
+		w.WriteHeader(status)
+	}
+	if _, err := w.Write(body); err != nil {
+		log.Printf("Failed to write response: %v", err)
+	}
+}
+
+type refusal struct {
+	cause   error
+	status  int
+	message string
+}
+
+var refusals = []refusal{
+	{domain.ErrRoleNotFound, http.StatusNotFound, apperr.RoleNotFoundErrorMessage},
+	{domain.ErrRoleLocked, http.StatusForbidden, apperr.RoleLockedErrorMessage},
+	{domain.ErrBuiltInRole, http.StatusConflict, apperr.RoleBuiltInErrorMessage},
+	{domain.ErrBuiltInName, http.StatusBadRequest, apperr.BuiltInNameErrorMessage},
+	{domain.ErrNotBuiltIn, http.StatusBadRequest, apperr.NotBuiltInErrorMessage},
+	{domain.ErrOwnRole, http.StatusForbidden, apperr.OwnRoleErrorMessage},
+	{domain.ErrRoleNameTaken, http.StatusConflict, apperr.RoleNameTakenErrorMessage},
+	{domain.ErrRoleConflict, http.StatusConflict, apperr.RoleConflictErrorMessage},
+	{domain.ErrRoleHasMembers, http.StatusConflict, apperr.RoleHasMembersErrorMessage},
+	{domain.ErrReassignTargetNotFound, http.StatusConflict, apperr.ReassignTargetNotFoundErrorMessage},
+	{domain.ErrInvalidReassign, http.StatusBadRequest, apperr.InvalidReassignErrorMessage},
+	{domain.ErrInvalidRoleName, http.StatusBadRequest, apperr.InvalidRoleNameErrorMessage},
+	{domain.ErrUnknownPermission, http.StatusBadRequest, apperr.UnknownPermissionErrorMessage},
+	{domain.ErrInvalidScope, http.StatusBadRequest, apperr.InvalidScopeErrorMessage},
+	{domain.ErrOwnerOnlyGrant, http.StatusBadRequest, apperr.OwnerOnlyPermissionErrorMessage},
+	{domain.ErrDuplicateGrant, http.StatusBadRequest, apperr.DuplicatePermissionErrorMessage},
+	{domain.ErrUnknownContentType, http.StatusBadRequest, apperr.UnknownContentTypeErrorMessage},
+}
+
+func writeRoleError(w http.ResponseWriter, err error) {
+	if access.WriteIfMissingPermission(w, err) {
+		return
+	}
+	var escalation domain.EscalationError
+	if errors.As(err, &escalation) {
+		w.Header().Set(apperr.EscalationHeader, escalation.Key)
+		http.Error(w, apperr.EscalationErrorMessage, http.StatusForbidden)
+		return
+	}
+	for _, candidate := range refusals {
+		if errors.Is(err, candidate.cause) {
+			http.Error(w, candidate.message, candidate.status)
+			return
+		}
+	}
+	http.Error(w, "Internal server error", http.StatusInternalServerError)
+}
+
+func (h *Handler) List(w http.ResponseWriter, _ *http.Request) {
+	listed, err := h.ListUseCase.List()
+	if err != nil {
+		writeRoleError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, payload.RoleViewsOf(listed))
+}
+
+func (h *Handler) Get(w http.ResponseWriter, r *http.Request) {
+	id, ok := readId(w, r)
+	if !ok {
+		return
+	}
+	found, err := h.GetUseCase.Get(id)
+	if err != nil {
+		writeRoleError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, payload.RoleViewOf(found))
+}
+
+func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
+	var request PostRole
+	if !decodeRequest(w, r, &request) {
+		return
+	}
+	created, err := h.CreateUseCase.Create(r.Context(), useCases.CreateRoleCommand{
+		Caller: access.CallerOf(r), Name: request.Name, Description: request.Description, Grants: toGrants(request.Grants),
+	})
+	if err != nil {
+		writeRoleError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusCreated, payload.RoleViewOf(created))
+}
+
+func (h *Handler) Update(w http.ResponseWriter, r *http.Request) {
+	id, ok := readId(w, r)
+	if !ok {
+		return
+	}
+	var request PutRole
+	if !decodeRequest(w, r, &request) {
+		return
+	}
+	updated, err := h.UpdateUseCase.Update(r.Context(), useCases.UpdateRoleCommand{
+		Caller: access.CallerOf(r), ID: id, Name: request.Name, Description: request.Description, Grants: toGrants(request.Grants), Version: request.Version,
+	})
+	if err != nil {
+		writeRoleError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, payload.RoleViewOf(updated))
+}
+
+func (h *Handler) Reset(w http.ResponseWriter, r *http.Request) {
+	id, ok := readId(w, r)
+	if !ok {
+		return
+	}
+	var request ResetRole
+	if !decodeRequest(w, r, &request) {
+		return
+	}
+	restored, err := h.UpdateUseCase.Reset(r.Context(), useCases.ResetRoleCommand{Caller: access.CallerOf(r), ID: id, Version: request.Version})
+	if err != nil {
+		writeRoleError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, payload.RoleViewOf(restored))
+}
+
+func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
+	id, ok := readId(w, r)
+	if !ok {
+		return
+	}
+	if err := h.DeleteUseCase.Delete(r.Context(), useCases.DeleteRoleCommand{Caller: access.CallerOf(r), ID: id}); err != nil {
+		writeRoleError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (h *Handler) Reassign(w http.ResponseWriter, r *http.Request) {
+	id, ok := readId(w, r)
+	if !ok {
+		return
+	}
+	var request ReassignRole
+	if !decodeRequest(w, r, &request) {
+		return
+	}
+	moved, err := h.ReassignUseCase.Reassign(r.Context(), useCases.ReassignRoleMembersCommand{Caller: access.CallerOf(r), SourceID: id, TargetID: request.TargetRoleID})
+	if err != nil {
+		writeRoleError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]int{"moved": moved})
+}

api/handlers/settings/settingsHandler.go

@@ -0,0 +1,108 @@
+package settings
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/audit"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"time"
+)
+
+type Handler struct {
+	GetSettingsUseCase             *useCases.GetSettingsUseCase
+	GetActivityRetentionUseCase    *useCases.GetActivityRetentionUseCase
+	UpdateActivityRetentionUseCase *useCases.UpdateActivityRetentionUseCase
+}
+
+type UpdateSettingsRequest struct {
+	ActivityRetentionDays  *int `json:"activity_retention_days" validate:"omitempty,oneof=0 30 90 365"`
+	ActivityRetentionMaxGB *int `json:"activity_retention_max_gb" validate:"omitempty,oneof=0 1 5 10 25 50"`
+}
+
+type settingsResponse struct {
+	Version                    string     `json:"version"`
+	ActivityRetentionDays      int        `json:"activity_retention_days"`
+	ActivityRetentionMaxGB     int        `json:"activity_retention_max_gb"`
+	ActivityLogSizeBytes       int64      `json:"activity_log_size_bytes"`
+	ActivityLastCleanupAt      *time.Time `json:"activity_last_cleanup_at"`
+	ActivityLastCleanupRemoved int        `json:"activity_last_cleanup_removed"`
+	ActivityNextCleanupAt      *time.Time `json:"activity_next_cleanup_at"`
+}
+
+func NewHandler(getSettings *useCases.GetSettingsUseCase, getRetention *useCases.GetActivityRetentionUseCase, updateRetention *useCases.UpdateActivityRetentionUseCase) *Handler {
+	return &Handler{GetSettingsUseCase: getSettings, GetActivityRetentionUseCase: getRetention, UpdateActivityRetentionUseCase: updateRetention}
+}
+
+func (h *Handler) GetSettings(w http.ResponseWriter, _ *http.Request) {
+	retention, err := h.GetActivityRetentionUseCase.GetActivityRetention()
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	h.write(w, retention)
+}
+
+func (h *Handler) UpdateSettings(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(r.Body)
+	if err != nil || hasNullValue(body) {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	var request UpdateSettingsRequest
+	if err := json.Unmarshal(body, &request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	retention, err := h.UpdateActivityRetentionUseCase.UpdateActivityRetention(r.Context(), useCases.UpdateActivityRetentionCommand{
+		Days:  request.ActivityRetentionDays,
+		MaxGB: request.ActivityRetentionMaxGB,
+	})
+	if err != nil {
+		if errors.Is(err, audit.ErrInvalidRetention) {
+			http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	h.write(w, retention)
+}
+
+func hasNullValue(body []byte) bool {
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(body, &fields); err != nil {
+		return false
+	}
+	for _, value := range fields {
+		if string(value) == "null" {
+			return true
+		}
+	}
+	return false
+}
+
+func (h *Handler) write(w http.ResponseWriter, retention audit.Settings) {
+	body, err := json.Marshal(settingsResponse{
+		Version:                    h.GetSettingsUseCase.GetSettings().Version,
+		ActivityRetentionDays:      retention.RetentionDays,
+		ActivityRetentionMaxGB:     retention.RetentionMaxGB,
+		ActivityLogSizeBytes:       retention.LogSizeBytes,
+		ActivityLastCleanupAt:      retention.LastCleanupAt,
+		ActivityLastCleanupRemoved: retention.LastCleanupRemoved,
+		ActivityNextCleanupAt:      retention.NextCleanupAt,
+	})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	_, _ = w.Write(body)
+}

api/handlers/site/siteHandler.go

@@ -0,0 +1,296 @@
+package site
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/image"
+	domain "RenewCMS/internal/domain/site"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"log"
+	"net/http"
+	"net/url"
+	"strconv"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	ListUseCase       *useCases.ListSitesUseCase
+	CreateUseCase     *useCases.CreateSiteUseCase
+	UpdateUseCase     *useCases.UpdateSiteUseCase
+	SetDefaultUseCase *useCases.SetDefaultSiteUseCase
+	DeleteUseCase     *useCases.DeleteSiteUseCase
+}
+
+func NewHandler(list *useCases.ListSitesUseCase, create *useCases.CreateSiteUseCase, update *useCases.UpdateSiteUseCase, setDefault *useCases.SetDefaultSiteUseCase, deleteUseCase *useCases.DeleteSiteUseCase) *Handler {
+	return &Handler{ListUseCase: list, CreateUseCase: create, UpdateUseCase: update, SetDefaultUseCase: setDefault, DeleteUseCase: deleteUseCase}
+}
+
+type PostSite struct {
+	Name                 string  `json:"name" validate:"required,sitename"`
+	Key                  string  `json:"key" validate:"required,sitekey"`
+	BaseURL              string  `json:"base_url" validate:"required"`
+	DefaultRobots        string  `json:"default_robots" validate:"omitempty,oneof=index noindex"`
+	Locale               *string `json:"locale"`
+	DefaultSocialImageID *uint32 `json:"default_social_image_id"`
+	IsDefault            bool    `json:"is_default"`
+	SiteName             string  `json:"site_name" validate:"max=100"`
+	TitleTemplate        *string `json:"title_template" validate:"omitempty,max=200"`
+	DefaultDescription   string  `json:"default_description" validate:"max=320"`
+}
+
+type optional[T any] struct {
+	Set   bool
+	Value *T
+}
+
+func (o *optional[T]) UnmarshalJSON(data []byte) error {
+	o.Set = true
+	if string(data) == "null" {
+		o.Value = nil
+		return nil
+	}
+	var value T
+	if err := json.Unmarshal(data, &value); err != nil {
+		return err
+	}
+	o.Value = &value
+	return nil
+}
+
+type PatchSite struct {
+	Name                 *string          `json:"name" validate:"omitempty,sitename"`
+	Key                  *string          `json:"key" validate:"omitempty,sitekey"`
+	BaseURL              *string          `json:"base_url"`
+	DefaultRobots        *string          `json:"default_robots" validate:"omitempty,oneof=index noindex"`
+	Locale               optional[string] `json:"locale"`
+	DefaultSocialImageID optional[uint32] `json:"default_social_image_id"`
+	IsDefault            *bool            `json:"is_default"`
+	SiteName             *string          `json:"site_name" validate:"omitempty,max=100"`
+	TitleTemplate        *string          `json:"title_template" validate:"omitempty,max=200"`
+	DefaultDescription   *string          `json:"default_description" validate:"omitempty,max=320"`
+}
+
+func (p PatchSite) toPatch() domain.Patch {
+	return domain.Patch{
+		Name:                 p.Name,
+		Key:                  p.Key,
+		BaseURL:              p.BaseURL,
+		DefaultRobots:        p.DefaultRobots,
+		Locale:               domain.Nullable[string]{Set: p.Locale.Set, Value: p.Locale.Value},
+		DefaultSocialImageID: domain.Nullable[uint32]{Set: p.DefaultSocialImageID.Set, Value: p.DefaultSocialImageID.Value},
+		IsDefault:            p.IsDefault,
+		SiteName:             p.SiteName,
+		TitleTemplate:        p.TitleTemplate,
+		DefaultDescription:   p.DefaultDescription,
+	}
+}
+
+func parseSiteId(r *http.Request) (uint32, error) {
+	id, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	return uint32(id), err
+}
+
+func writeSite(w http.ResponseWriter, status int, s domain.Site) {
+	body, err := json.Marshal(s)
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+	if status != http.StatusOK {
+		w.WriteHeader(status)
+	}
+	if _, err := w.Write(body); err != nil {
+		log.Printf("Failed to write response: %v", err)
+	}
+}
+
+func writeSiteError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, domain.ErrSiteNotFound):
+		http.Error(w, apperr.SiteNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, domain.ErrSiteKeyTaken):
+		http.Error(w, apperr.SiteKeyTakenErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrSiteHasArticles):
+		http.Error(w, apperr.SiteHasArticlesErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrDefaultSite):
+		http.Error(w, apperr.DefaultSiteErrorMessage, http.StatusForbidden)
+	case errors.Is(err, domain.ErrKeyImmutable):
+		http.Error(w, apperr.SiteKeyImmutableErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidSiteURL):
+		http.Error(w, apperr.InvalidSiteURLErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidTitleTemplate):
+		http.Error(w, apperr.InvalidTitleTemplateErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidLocale):
+		http.Error(w, apperr.InvalidLocaleErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, image.ErrImageNotFound):
+		http.Error(w, apperr.SiteImageNotFoundErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrUseSetDefault):
+		http.Error(w, apperr.UseSetDefaultErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrInvalidReassign):
+		http.Error(w, apperr.InvalidReassignErrorMessage, http.StatusBadRequest)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+const (
+	defaultListPage = 1
+	defaultListSize = 25
+)
+
+type listQuery struct {
+	Page int    `validate:"gte=1"`
+	Size int    `validate:"omitempty,oneof=5 25 50 100"`
+	Q    string `validate:"max=200"`
+}
+
+func intQueryParam(values url.Values, name string, fallback int) (int, error) {
+	if !values.Has(name) {
+		return fallback, nil
+	}
+	return strconv.Atoi(values.Get(name))
+}
+
+func readListQuery(values url.Values) (listQuery, error) {
+	paged := values.Has("page") || values.Has("size")
+	page, err := intQueryParam(values, "page", defaultListPage)
+	if err != nil {
+		return listQuery{}, err
+	}
+	size := 0
+	if paged {
+		size, err = intQueryParam(values, "size", defaultListSize)
+		if err != nil {
+			return listQuery{}, err
+		}
+		if size == 0 {
+			return listQuery{}, errors.New("invalid size")
+		}
+	}
+	return listQuery{Page: page, Size: size, Q: values.Get("q")}, nil
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	query, err := readListQuery(r.URL.Query())
+	if err != nil || validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	page, err := h.ListUseCase.ListPage(useCases.ListSitesCommand{Q: query.Q, Page: query.Page, Size: query.Size})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	body, err := json.Marshal(page.Items)
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("X-Total-Count", strconv.Itoa(page.Total))
+	if _, err := w.Write(body); err != nil {
+		log.Printf("Failed to write response: %v", err)
+	}
+}
+
+func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
+	var request PostSite
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	created, err := h.CreateUseCase.Create(r.Context(), useCases.CreateSiteCommand{
+		Name:                 request.Name,
+		Key:                  request.Key,
+		BaseURL:              request.BaseURL,
+		DefaultRobots:        request.DefaultRobots,
+		Locale:               request.Locale,
+		DefaultSocialImageID: request.DefaultSocialImageID,
+		IsDefault:            request.IsDefault,
+		SiteName:             request.SiteName,
+		TitleTemplate:        request.TitleTemplate,
+		DefaultDescription:   request.DefaultDescription,
+	})
+	if err != nil {
+		writeSiteError(w, err)
+		return
+	}
+	writeSite(w, http.StatusCreated, created)
+}
+
+func (h *Handler) Update(w http.ResponseWriter, r *http.Request) {
+	id, err := parseSiteId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	var request PatchSite
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	updated, err := h.UpdateUseCase.Update(r.Context(), id, request.toPatch())
+	if err != nil {
+		writeSiteError(w, err)
+		return
+	}
+	writeSite(w, http.StatusOK, updated)
+}
+
+func (h *Handler) SetDefault(w http.ResponseWriter, r *http.Request) {
+	id, err := parseSiteId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	updated, err := h.SetDefaultUseCase.SetDefault(r.Context(), id)
+	if err != nil {
+		writeSiteError(w, err)
+		return
+	}
+	writeSite(w, http.StatusOK, updated)
+}
+
+const reassignQueryParam = "reassign_to"
+
+func readReassign(r *http.Request) (*uint32, bool) {
+	query := r.URL.Query()
+	if !query.Has(reassignQueryParam) {
+		return nil, false
+	}
+	parsed, err := strconv.ParseUint(query.Get(reassignQueryParam), 10, 32)
+	if err != nil {
+		return nil, true
+	}
+	destination := uint32(parsed)
+	return &destination, false
+}
+
+func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
+	id, err := parseSiteId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	reassignTo, invalid := readReassign(r)
+	if err := h.DeleteUseCase.Delete(r.Context(), useCases.DeleteSiteCommand{ID: id, ReassignTo: reassignTo, ReassignInvalid: invalid}); err != nil {
+		writeSiteError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

api/handlers/site/sitemapHandler.go

@@ -0,0 +1,87 @@
+package site
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"log"
+	"net/http"
+	"net/url"
+	"strconv"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+const (
+	defaultSitemapPage = 1
+	defaultSitemapSize = 100
+	totalCountHeader   = "X-Total-Count"
+)
+
+type SitemapHandler struct {
+	ListUseCase *useCases.ListSitemapUseCase
+}
+
+func NewSitemapHandler(list *useCases.ListSitemapUseCase) *SitemapHandler {
+	return &SitemapHandler{ListUseCase: list}
+}
+
+type sitemapQuery struct {
+	Page int `validate:"gte=1"`
+	Size int `validate:"oneof=25 50 100 500"`
+}
+
+type sitemapItem struct {
+	URL        string `json:"url"`
+	ModifiedAt string `json:"modified_at"`
+	Noindex    bool   `json:"noindex"`
+}
+
+func sitemapIntParam(values url.Values, name string, fallback int) (int, error) {
+	if !values.Has(name) {
+		return fallback, nil
+	}
+	return strconv.Atoi(values.Get(name))
+}
+
+func readSitemapQuery(values url.Values) (sitemapQuery, error) {
+	page, err := sitemapIntParam(values, "page", defaultSitemapPage)
+	if err != nil {
+		return sitemapQuery{}, err
+	}
+	size, err := sitemapIntParam(values, "size", defaultSitemapSize)
+	if err != nil {
+		return sitemapQuery{}, err
+	}
+	return sitemapQuery{Page: page, Size: size}, nil
+}
+
+func (h *SitemapHandler) Sitemap(w http.ResponseWriter, r *http.Request) {
+	query, err := readSitemapQuery(r.URL.Query())
+	if err != nil || validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	page, err := h.ListUseCase.List(chi.URLParam(r, "key"), query.Page, query.Size)
+	if err != nil {
+		writeSiteError(w, err)
+		return
+	}
+
+	items := make([]sitemapItem, 0, len(page.Entries))
+	for _, entry := range page.Entries {
+		items = append(items, sitemapItem{URL: entry.URL, ModifiedAt: entry.ModifiedAt.UTC().Format(time.RFC3339), Noindex: entry.Noindex})
+	}
+	body, err := json.Marshal(items)
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set(totalCountHeader, strconv.Itoa(page.Total))
+	if _, err := w.Write(body); err != nil {
+		log.Printf("Failed to write response: %v", err)
+	}
+}

api/handlers/staticimages/staticImagesHandler.go

@@ -0,0 +1,182 @@
+package staticimages
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/internal/domain/image"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"path"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+const cacheControl = "public, no-cache"
+const svgContentSecurityPolicy = "default-src 'none'; style-src 'unsafe-inline'; sandbox"
+const fallbackContentType = "application/octet-stream"
+const unknownVariantCode = "unknown_variant"
+const unsupportedParameterCode = "unsupported_parameter"
+
+var contentTypeExtensions = map[string]string{
+	".png":  "image/png",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".svg":  "image/svg+xml",
+	".gif":  "image/gif",
+}
+
+type Handler struct {
+	openMedia    *useCases.OpenMediaUseCase
+	serveVariant *useCases.ServeVariantUseCase
+	modTime      time.Time
+}
+
+func NewHandler(openMedia *useCases.OpenMediaUseCase, serveVariant *useCases.ServeVariantUseCase) *Handler {
+	return &Handler{
+		openMedia:    openMedia,
+		serveVariant: serveVariant,
+		modTime:      time.Now(),
+	}
+}
+
+type requestErrorBody struct {
+	Status  int    `json:"status"`
+	Error   string `json:"error"`
+	Message string `json:"message"`
+	Detail  string `json:"detail"`
+}
+
+func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+
+	cleaned := cleanPath(requestedPath(r))
+	served, err := h.serveVariant.Serve(variantRequestFrom(r, cleaned))
+	if err != nil {
+		writeServeError(w, r, err)
+		return
+	}
+	switch {
+	case served.NotModified:
+		writeNotModified(w, served)
+	case served.Original:
+		h.serveOriginal(w, r, cleaned)
+	default:
+		serveVariantFile(w, r, cleaned, served)
+	}
+}
+
+func variantRequestFrom(r *http.Request, storedName string) useCases.ServeVariantRequest {
+	query := r.URL.Query()
+	request := useCases.ServeVariantRequest{Context: r.Context(), StoredName: storedName, IfNoneMatch: r.Header.Get("If-None-Match")}
+	for parameter := range query {
+		request.Parameters = append(request.Parameters, parameter)
+	}
+	if query.Has(image.VariantQueryParameter) {
+		name := query.Get(image.VariantQueryParameter)
+		request.Variant = &name
+	}
+	return request
+}
+
+func writeServeError(w http.ResponseWriter, r *http.Request, err error) {
+	switch {
+	case errors.Is(err, image.ErrUnknownVariant):
+		writeRequestError(w, unknownVariantCode, apperr.VariantUnknownMessage, err)
+	case errors.Is(err, image.ErrUnsupportedParameter):
+		writeRequestError(w, unsupportedParameterCode, apperr.VariantUnsupportedParameterMessage, err)
+	case errors.Is(err, image.ErrBlobNotFound), errors.Is(err, image.ErrImageNotFound):
+		http.NotFound(w, r)
+	case errors.Is(err, image.ErrSourceTooLarge):
+		http.Error(w, apperr.VariantSourceTooLargeErrorMessage, http.StatusRequestEntityTooLarge)
+	default:
+		http.Error(w, "Unable to read the file", http.StatusInternalServerError)
+	}
+}
+
+func writeRequestError(w http.ResponseWriter, code string, message string, err error) {
+	body, marshalErr := json.Marshal(requestErrorBody{
+		Status:  http.StatusBadRequest,
+		Error:   code,
+		Message: message,
+		Detail:  image.VariantRequestDetail(err),
+	})
+	if marshalErr != nil {
+		http.Error(w, "Unable to read the file", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusBadRequest)
+	_, _ = w.Write(body)
+}
+
+func writeNotModified(w http.ResponseWriter, served useCases.ServedVariant) {
+	w.Header().Set("ETag", served.ETag)
+	w.Header().Set("Cache-Control", cacheControl)
+	w.WriteHeader(http.StatusNotModified)
+}
+
+func serveVariantFile(w http.ResponseWriter, r *http.Request, name string, served useCases.ServedVariant) {
+	defer served.Content.Close()
+	w.Header().Set("ETag", served.ETag)
+	serveContent(w, r, name, served.ContentType, image.Blob{Content: served.Content, Size: served.Size, ModTime: served.ModTime})
+}
+
+func (h *Handler) serveOriginal(w http.ResponseWriter, r *http.Request, name string) {
+	blob, err := h.openMedia.Open(name)
+	if errors.Is(err, image.ErrBlobNotFound) {
+		http.NotFound(w, r)
+		return
+	}
+	if err != nil {
+		http.Error(w, "Unable to read the file", http.StatusInternalServerError)
+		return
+	}
+	defer blob.Content.Close()
+
+	serveContent(w, r, name, contentTypeFor(name), blob)
+}
+
+func serveContent(w http.ResponseWriter, r *http.Request, name string, contentType string, blob image.Blob) {
+	w.Header().Set("Content-Type", contentType)
+	w.Header().Set("Cache-Control", cacheControl)
+	if contentType == "image/svg+xml" {
+		w.Header().Set("Content-Security-Policy", svgContentSecurityPolicy)
+	}
+
+	if content, ok := blob.Content.(io.ReadSeeker); ok {
+		http.ServeContent(w, r, name, blob.ModTime, content)
+		return
+	}
+	w.Header().Set("Content-Length", strconv.FormatInt(blob.Size, 10))
+	if !blob.ModTime.IsZero() {
+		w.Header().Set("Last-Modified", blob.ModTime.UTC().Format(http.TimeFormat))
+	}
+	w.WriteHeader(http.StatusOK)
+	if r.Method != http.MethodHead {
+		_, _ = io.Copy(w, blob.Content)
+	}
+}
+
+func requestedPath(r *http.Request) string {
+	if rctx := chi.RouteContext(r.Context()); rctx != nil && rctx.RoutePath != "" {
+		return rctx.RoutePath
+	}
+	return r.URL.Path
+}
+
+func cleanPath(p string) string {
+	return strings.TrimPrefix(path.Clean("/"+p), "/")
+}
+
+func contentTypeFor(p string) string {
+	ext := path.Ext(p)
+	if contentType, ok := contentTypeExtensions[ext]; ok {
+		return contentType
+	}
+	return fallbackContentType
+}

api/handlers/update/updateHandler.go

@@ -0,0 +1,139 @@
+package update
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/role"
+	domain "RenewCMS/internal/domain/update"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+)
+
+const restartBodyLimitBytes = 1024
+
+type Handler struct {
+	GetUpdateStatusUseCase     *useCases.GetUpdateStatusUseCase
+	CheckForUpdateUseCase      *useCases.CheckForUpdateUseCase
+	StartUpdateDownloadUseCase *useCases.StartUpdateDownloadUseCase
+	RequestRestartUseCase      *useCases.RequestRestartUseCase
+}
+
+type restartRequest struct {
+	Kind *string `json:"kind" validate:"omitempty,oneof=update restart"`
+}
+
+func NewHandler(getStatus *useCases.GetUpdateStatusUseCase, checkForUpdate *useCases.CheckForUpdateUseCase, startDownload *useCases.StartUpdateDownloadUseCase, requestRestart *useCases.RequestRestartUseCase) *Handler {
+	return &Handler{
+		GetUpdateStatusUseCase:     getStatus,
+		CheckForUpdateUseCase:      checkForUpdate,
+		StartUpdateDownloadUseCase: startDownload,
+		RequestRestartUseCase:      requestRestart,
+	}
+}
+
+func (h *Handler) GetStatus(w http.ResponseWriter, r *http.Request) {
+	writeStatus(w, http.StatusOK, h.GetUpdateStatusUseCase.GetStatus(canApply(r)))
+}
+
+func (h *Handler) Check(w http.ResponseWriter, r *http.Request) {
+	if _, err := h.CheckForUpdateUseCase.Check(r.Context()); err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	writeStatus(w, http.StatusOK, h.GetUpdateStatusUseCase.GetStatus(canApply(r)))
+}
+
+func (h *Handler) Download(w http.ResponseWriter, r *http.Request) {
+	status, err := h.StartUpdateDownloadUseCase.Start(r.Context())
+	if err != nil {
+		writeDownloadError(w, err)
+		return
+	}
+	writeStatus(w, http.StatusAccepted, status)
+}
+
+func (h *Handler) Restart(w http.ResponseWriter, r *http.Request) {
+	kind, ok := decodeRestartKind(w, r)
+	if !ok {
+		return
+	}
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+	status, err := h.RequestRestartUseCase.Request(r.Context(), userId, kind)
+	if err != nil {
+		writeRestartError(w, err)
+		return
+	}
+	writeStatus(w, http.StatusAccepted, status)
+}
+
+func decodeRestartKind(w http.ResponseWriter, r *http.Request) (string, bool) {
+	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, restartBodyLimitBytes))
+	if err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return "", false
+	}
+	if strings.TrimSpace(string(body)) == "" {
+		return "", true
+	}
+	var request restartRequest
+	if err := json.Unmarshal(body, &request); err != nil || validator.Validate.Struct(request) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return "", false
+	}
+	if request.Kind == nil {
+		return "", true
+	}
+	return *request.Kind, true
+}
+
+func canApply(r *http.Request) bool {
+	return access.Grants(r).Holds(role.KeySystemApplyUpdates)
+}
+
+func writeDownloadError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, domain.ErrNotPrepared):
+		http.Error(w, apperr.UpdateNotPreparedErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrJobInProgress), errors.Is(err, domain.ErrRestartPending):
+		http.Error(w, apperr.UpdateAlreadyRunningErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrNothingToUpdate):
+		http.Error(w, apperr.NothingToUpdateErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, domain.ErrPreflightRefused):
+		http.Error(w, apperr.UpdateRefusedErrorMessage, http.StatusUnprocessableEntity)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func writeRestartError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, domain.ErrNotPrepared):
+		http.Error(w, apperr.UpdateNotPreparedErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrJobInProgress), errors.Is(err, domain.ErrRestartPending):
+		http.Error(w, apperr.UpdateAlreadyRunningErrorMessage, http.StatusConflict)
+	case errors.Is(err, domain.ErrRestartKindMismatch):
+		http.Error(w, apperr.UpdateRestartMismatchErrorMessage, http.StatusConflict)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func writeStatus(w http.ResponseWriter, code int, status domain.UpdateStatus) {
+	body, err := json.Marshal(status)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.WriteHeader(code)
+	_, _ = w.Write(body)
+}

api/handlers/user/deleteAccountHandler.go

@@ -0,0 +1,81 @@
+package user
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/authtoken"
+	"RenewCMS/api/pkg/claims"
+	validator "RenewCMS/api/pkg/validator"
+	domain "RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"time"
+)
+
+type DeleteAccountHandler struct {
+	DeleteUseCase *useCases.DeleteOwnAccountUseCase
+	IsProduction  bool
+}
+
+type DeleteAccountRequest struct {
+	CurrentPassword string `json:"current_password" validate:"required"`
+	Confirmation    string `json:"confirmation" validate:"required,eq=DELETE"`
+}
+
+func NewDeleteAccountHandler(deleteAccount *useCases.DeleteOwnAccountUseCase, isProduction bool) *DeleteAccountHandler {
+	return &DeleteAccountHandler{DeleteUseCase: deleteAccount, IsProduction: isProduction}
+}
+
+func (h *DeleteAccountHandler) Delete(w http.ResponseWriter, r *http.Request) {
+	var request DeleteAccountRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	command := useCases.DeleteOwnAccountCommand{UserID: userId, CurrentPassword: request.CurrentPassword}
+	command.SessionID, command.SessionExpiresAt = sessionOf(r)
+	if err := h.DeleteUseCase.Delete(r.Context(), command); err != nil {
+		writeDeleteAccountError(w, err)
+		return
+	}
+	http.SetCookie(w, authtoken.ExpiredCookie(h.IsProduction))
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func sessionOf(r *http.Request) (string, time.Time) {
+	tokenClaims, err := authtoken.FromContext(r.Context())
+	if err != nil {
+		return "", time.Time{}
+	}
+	id, _ := tokenClaims["jti"].(string)
+	expiry, _ := tokenClaims["exp"].(float64)
+	return id, time.Unix(int64(expiry), 0)
+}
+
+func writeDeleteAccountError(w http.ResponseWriter, err error) {
+	var lastAdmin domain.LastAdminError
+	switch {
+	case errors.Is(err, domain.ErrUserNotFound):
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+	case errors.Is(err, domain.ErrWrongPassword):
+		http.Error(w, apperr.WrongPasswordErrorCode, http.StatusForbidden)
+	case errors.As(err, &lastAdmin):
+		w.Header().Set(apperr.LastRoleHeader, lastAdmin.Role)
+		http.Error(w, apperr.LastAdminErrorCode, http.StatusConflict)
+	case errors.Is(err, domain.ErrAccountNotDeletable):
+		http.Error(w, apperr.AccountNotDeletableErrorCode, http.StatusConflict)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}

api/handlers/user/exportHandler.go

@@ -0,0 +1,44 @@
+package user
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/internal/infrastructure/useCases"
+	"context"
+	"errors"
+	"net/http"
+	"strconv"
+)
+
+type ExportHandler struct {
+	ExportUseCase *useCases.ExportUserDataUseCase
+}
+
+func NewExportHandler(export *useCases.ExportUserDataUseCase) *ExportHandler {
+	return &ExportHandler{ExportUseCase: export}
+}
+
+func (h *ExportHandler) Export(w http.ResponseWriter, r *http.Request) {
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	archive, err := h.ExportUseCase.Export(r.Context(), userId)
+	if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+		http.Error(w, "Service unavailable", http.StatusServiceUnavailable)
+		return
+	}
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/zip")
+	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("Content-Disposition", "attachment; filename=\""+archive.Filename+"\"")
+	w.Header().Set("Content-Length", strconv.Itoa(len(archive.Content)))
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write(archive.Content)
+}

api/handlers/user/inviteHandler.go

@@ -0,0 +1,226 @@
+package user
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/api/pkg/payload"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/invite"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type InviteHandler struct {
+	CreateInviteUseCase        *useCases.CreateInviteUseCase
+	CancelInviteUseCase        *useCases.CancelInviteUseCase
+	RenewInviteUseCase         *useCases.RenewInviteUseCase
+	ListUsersAndInvitesUseCase *useCases.ListUsersAndInvitesUseCase
+}
+
+type CreateInviteRequest struct {
+	Email  string `json:"email" validate:"required,inviteemail"`
+	RoleID uint32 `json:"role_id"`
+}
+
+type inviteResponse struct {
+	ID        uint32          `json:"id"`
+	Kind      string          `json:"kind"`
+	Email     string          `json:"email"`
+	Status    string          `json:"status"`
+	Role      payload.RoleRef `json:"role"`
+	CreatedAt time.Time       `json:"created_at"`
+	ExpiresAt time.Time       `json:"expires_at"`
+}
+
+type inviteListItem struct {
+	ID        uint32           `json:"id"`
+	Kind      string           `json:"kind"`
+	Email     string           `json:"email"`
+	Role      *payload.RoleRef `json:"role"`
+	Status    string           `json:"status"`
+	CreatedAt time.Time        `json:"created_at"`
+}
+
+type userListItem struct {
+	ID             uint32                `json:"id"`
+	Kind           string                `json:"kind"`
+	Username       string                `json:"username"`
+	DisplayName    string                `json:"display_name"`
+	Email          string                `json:"email"`
+	Role           *payload.RoleRef      `json:"role"`
+	RoleAssignedBy *payload.RoleAssigner `json:"role_assigned_by"`
+	Status         string                `json:"status"`
+	CreatedAt      time.Time             `json:"created_at"`
+}
+
+func NewInviteHandler(createInvite *useCases.CreateInviteUseCase, cancelInvite *useCases.CancelInviteUseCase, renewInvite *useCases.RenewInviteUseCase, listUsersAndInvites *useCases.ListUsersAndInvitesUseCase) *InviteHandler {
+	return &InviteHandler{
+		CreateInviteUseCase:        createInvite,
+		CancelInviteUseCase:        cancelInvite,
+		RenewInviteUseCase:         renewInvite,
+		ListUsersAndInvitesUseCase: listUsersAndInvites,
+	}
+}
+
+func (h *InviteHandler) CreateInvite(w http.ResponseWriter, r *http.Request) {
+	var request CreateInviteRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	created, err := h.CreateInviteUseCase.CreateInvite(r.Context(), useCases.CreateInviteCommand{
+		Caller:    access.CallerOf(r),
+		Email:     request.Email,
+		InvitedBy: userId,
+		RoleID:    request.RoleID,
+	})
+	if err != nil {
+		writeCreateInviteError(w, err)
+		return
+	}
+
+	writeInviteResponse(w, http.StatusCreated, created)
+}
+
+func writeInviteResponse(w http.ResponseWriter, status int, entry useCases.InviteView) {
+	body, err := json.Marshal(inviteResponse{
+		ID:        entry.ID,
+		Kind:      useCases.EntryKindInvite,
+		Email:     entry.Email,
+		Status:    string(entry.StatusAt(time.Now())),
+		Role:      payload.RoleRefOf(entry.Role),
+		CreatedAt: entry.CreatedAt,
+		ExpiresAt: entry.ExpiresAt,
+	})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	w.WriteHeader(status)
+	_, _ = w.Write(body)
+}
+
+func parseInviteId(r *http.Request) (uint32, error) {
+	id, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	return uint32(id), err
+}
+
+func (h *InviteHandler) CancelInvite(w http.ResponseWriter, r *http.Request) {
+	id, err := parseInviteId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	if err := h.CancelInviteUseCase.CancelInvite(r.Context(), id); err != nil {
+		writeManageInviteError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (h *InviteHandler) RenewInvite(w http.ResponseWriter, r *http.Request) {
+	id, err := parseInviteId(r)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	renewed, err := h.RenewInviteUseCase.RenewInvite(r.Context(), useCases.RenewInviteCommand{Caller: access.CallerOf(r), ID: id, RenewedBy: userId})
+	if err != nil {
+		writeManageInviteError(w, err)
+		return
+	}
+	writeInviteResponse(w, http.StatusOK, renewed)
+}
+
+func writeManageInviteError(w http.ResponseWriter, err error) {
+	if writeRoleRefusal(w, err) {
+		return
+	}
+	switch {
+	case errors.Is(err, invite.ErrInviteNotFound):
+		http.Error(w, apperr.InviteNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, invite.ErrInviteAlreadyAccepted):
+		http.Error(w, apperr.InviteAlreadyAcceptedErrorMessage, http.StatusConflict)
+	case errors.Is(err, invite.ErrInviteEmailNotSent):
+		http.Error(w, apperr.InviteNotSentErrorMessage, http.StatusInternalServerError)
+	case errors.Is(err, user.ErrUserNotFound):
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func writeCreateInviteError(w http.ResponseWriter, err error) {
+	if writeRoleRefusal(w, err) {
+		return
+	}
+	switch {
+	case errors.Is(err, invite.ErrEmailHasAccount):
+		w.Header().Set(apperr.ErrorCodeHeader, apperr.EmailHasAccountErrorCode)
+		http.Error(w, apperr.EmailHasAccountErrorMessage, http.StatusConflict)
+	case errors.Is(err, invite.ErrPendingInvite):
+		w.Header().Set(apperr.ErrorCodeHeader, apperr.InvitePendingErrorCode)
+		http.Error(w, apperr.PendingInviteErrorMessage, http.StatusConflict)
+	case errors.Is(err, invite.ErrInviteEmailNotSent):
+		http.Error(w, apperr.InviteNotSentErrorMessage, http.StatusInternalServerError)
+	case errors.Is(err, user.ErrUserNotFound):
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func (h *InviteHandler) ListUsers(w http.ResponseWriter, _ *http.Request) {
+	entries, err := h.ListUsersAndInvitesUseCase.ListUsersAndInvites()
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	items := make([]any, 0, len(entries))
+	for _, entry := range entries {
+		if entry.Kind == useCases.EntryKindInvite {
+			items = append(items, inviteListItem{
+				ID:        entry.ID,
+				Kind:      entry.Kind,
+				Email:     entry.Email,
+				Role:      payload.RoleRefPtrOf(entry.Role),
+				Status:    entry.Status,
+				CreatedAt: entry.CreatedAt,
+			})
+			continue
+		}
+		items = append(items, userListItemOf(entry))
+	}
+
+	writeNoStoreJSON(w, http.StatusOK, items)
+}

api/handlers/user/lookupHandler.go

@@ -0,0 +1,66 @@
+package user
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/response"
+	domainUser "RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+)
+
+type LookupHandler struct {
+	LookupUseCase *useCases.LookupUserNamesUseCase
+}
+
+type userNameResponse struct {
+	ID          uint32 `json:"id"`
+	DisplayName string `json:"display_name"`
+}
+
+func NewLookupHandler(lookup *useCases.LookupUserNamesUseCase) *LookupHandler {
+	return &LookupHandler{LookupUseCase: lookup}
+}
+
+func parseLookupIDs(raw string) ([]uint32, bool) {
+	if raw == "" {
+		return nil, false
+	}
+	if strings.Count(raw, ",")+1 > domainUser.MaxLookupIDs {
+		return nil, false
+	}
+	parts := strings.Split(raw, ",")
+	ids := make([]uint32, 0, len(parts))
+	for _, part := range parts {
+		id, err := strconv.ParseUint(part, 10, 32)
+		if err != nil {
+			return nil, false
+		}
+		ids = append(ids, uint32(id))
+	}
+	return ids, true
+}
+
+func (h *LookupHandler) Lookup(w http.ResponseWriter, r *http.Request) {
+	ids, ok := parseLookupIDs(r.URL.Query().Get("ids"))
+	if !ok {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	names, err := h.LookupUseCase.Lookup(ids)
+	if errors.Is(err, domainUser.ErrInvalidLookup) {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	items := make([]userNameResponse, 0, len(names))
+	for _, name := range names {
+		items = append(items, userNameResponse{ID: name.ID, DisplayName: name.DisplayName})
+	}
+	response.WriteJSON(w, http.StatusOK, items)
+}

api/handlers/user/removeHandler.go

@@ -0,0 +1,62 @@
+package user
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/internal/domain/role"
+	domain "RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type RemoveHandler struct {
+	RemoveUserUseCase *useCases.RemoveUserUseCase
+}
+
+func NewRemoveHandler(removeUser *useCases.RemoveUserUseCase) *RemoveHandler {
+	return &RemoveHandler{RemoveUserUseCase: removeUser}
+}
+
+func (h *RemoveHandler) Remove(w http.ResponseWriter, r *http.Request) {
+	targetID, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+	expectedRoleID, err := strconv.ParseUint(r.URL.Query().Get("expected_role_id"), 10, 32)
+	if err != nil || expectedRoleID == 0 {
+		http.Error(w, apperr.InvalidRoleErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	err = h.RemoveUserUseCase.Remove(r.Context(), useCases.RemoveUserCommand{
+		Caller:         access.CallerOf(r),
+		TargetID:       uint32(targetID),
+		ExpectedRoleID: uint32(expectedRoleID),
+	})
+	if err != nil {
+		writeRemoveError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func writeRemoveError(w http.ResponseWriter, err error) {
+	if writeRoleRefusal(w, err) {
+		return
+	}
+	switch {
+	case errors.Is(err, role.ErrOwnRole):
+		http.Error(w, apperr.OwnRoleErrorMessage, http.StatusForbidden)
+	case errors.Is(err, domain.ErrUserNotFound):
+		http.Error(w, apperr.UserNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, domain.ErrRoleChanged):
+		http.Error(w, apperr.UserRoleChangedErrorMessage, http.StatusConflict)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}

api/handlers/user/roleHandler.go

@@ -0,0 +1,73 @@
+package user
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/role"
+	domain "RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type RoleHandler struct {
+	ChangeUserRoleUseCase *useCases.ChangeUserRoleUseCase
+}
+
+type ChangeRoleRequest struct {
+	RoleID uint32 `json:"role_id" validate:"required"`
+}
+
+func NewRoleHandler(changeRole *useCases.ChangeUserRoleUseCase) *RoleHandler {
+	return &RoleHandler{ChangeUserRoleUseCase: changeRole}
+}
+
+func (h *RoleHandler) Change(w http.ResponseWriter, r *http.Request) {
+	targetID, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	var request ChangeRoleRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	changed, err := h.ChangeUserRoleUseCase.ChangeRole(r.Context(), useCases.ChangeUserRoleCommand{
+		Caller:   access.CallerOf(r),
+		TargetID: uint32(targetID),
+		RoleID:   request.RoleID,
+	})
+	if err != nil {
+		writeChangeRoleError(w, err)
+		return
+	}
+	writeNoStoreJSON(w, http.StatusOK, userListItemOf(changed))
+}
+
+func writeChangeRoleError(w http.ResponseWriter, err error) {
+	if writeRoleRefusal(w, err) {
+		return
+	}
+	switch {
+	case errors.Is(err, role.ErrOwnRole):
+		http.Error(w, apperr.OwnRoleErrorMessage, http.StatusForbidden)
+	case errors.Is(err, domain.ErrUserNotFound):
+		http.Error(w, apperr.UserNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, domain.ErrRoleChanged):
+		http.Error(w, apperr.UserRoleChangedErrorMessage, http.StatusConflict)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}

api/handlers/user/shared.go

@@ -0,0 +1,52 @@
+package user
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/payload"
+	"RenewCMS/internal/domain/role"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+)
+
+func userListItemOf(entry useCases.DirectoryEntry) userListItem {
+	return userListItem{
+		ID:             entry.ID,
+		Kind:           entry.Kind,
+		Username:       entry.Username,
+		DisplayName:    entry.DisplayName,
+		Email:          entry.Email,
+		Role:           payload.RoleRefPtrOf(entry.Role),
+		RoleAssignedBy: payload.RoleAssignerPtrOf(entry.RoleAssignedBy),
+		Status:         entry.Status,
+		CreatedAt:      entry.CreatedAt,
+	}
+}
+
+func writeNoStoreJSON(w http.ResponseWriter, status int, payload any) {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	w.WriteHeader(status)
+	_, _ = w.Write(body)
+}
+
+func writeRoleRefusal(w http.ResponseWriter, err error) bool {
+	var escalation role.EscalationError
+	switch {
+	case errors.As(err, &escalation):
+		w.Header().Set(apperr.EscalationHeader, escalation.Key)
+		http.Error(w, apperr.EscalationErrorMessage, http.StatusForbidden)
+	case errors.Is(err, role.ErrRoleLocked):
+		http.Error(w, apperr.RoleLockedErrorMessage, http.StatusForbidden)
+	case errors.Is(err, role.ErrUnknownRole):
+		http.Error(w, apperr.InvalidRoleErrorMessage, http.StatusBadRequest)
+	default:
+		return false
+	}
+	return true
+}

api/handlers/user/userHandler.go

@@ -0,0 +1,70 @@
+package user
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/api/pkg/publicuser"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+)
+
+type Handler struct {
+	UpdateProfileUseCase *useCases.UpdateUserProfileUseCase
+}
+
+type UpdateProfileRequest struct {
+	DisplayName *string `json:"display_name" validate:"required"`
+}
+
+func NewHandler(updateProfile *useCases.UpdateUserProfileUseCase) *Handler {
+	return &Handler{
+		UpdateProfileUseCase: updateProfile,
+	}
+}
+
+func (h *Handler) UpdateMe(w http.ResponseWriter, r *http.Request) {
+	var request UpdateProfileRequest
+	err := json.NewDecoder(r.Body).Decode(&request)
+	if err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	err = validator.Validate.Struct(request)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	updatedUser, err := h.UpdateProfileUseCase.UpdateDisplayName(r.Context(), userId, *request.DisplayName)
+	if err != nil {
+		if errors.Is(err, user.ErrInvalidDisplayName) {
+			http.Error(w, apperr.DisplayNameErrorMessage, http.StatusBadRequest)
+			return
+		}
+		if errors.Is(err, user.ErrUserNotFound) {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	body, err := json.Marshal(publicuser.New(updatedUser))
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}

api/middleware/apiKey.go

@@ -0,0 +1,106 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/authtoken"
+	"RenewCMS/internal/domain/apikey"
+	"RenewCMS/internal/infrastructure/useCases"
+	"context"
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const bearerScheme = "bearer "
+
+type apiKeyIdContextKey struct{}
+
+type apiKeyNameContextKey struct{}
+
+func bearerAPIKey(r *http.Request) (string, bool) {
+	header := r.Header.Get("Authorization")
+	if len(header) < len(bearerScheme) || !strings.EqualFold(header[:len(bearerScheme)], bearerScheme) {
+		return "", false
+	}
+
+	credential := strings.TrimSpace(header[len(bearerScheme):])
+	return credential, strings.HasPrefix(credential, apikey.RawKeyPrefix)
+}
+
+func apiKeyIdFrom(r *http.Request) (uint32, bool) {
+	id, ok := r.Context().Value(apiKeyIdContextKey{}).(uint32)
+	return id, ok
+}
+
+func apiKeyNameFrom(r *http.Request) string {
+	name, _ := r.Context().Value(apiKeyNameContextKey{}).(string)
+	return name
+}
+
+func RequireSession(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if _, isKey := bearerAPIKey(r); isKey {
+			http.Error(w, apperr.SessionRequiredErrorMessage, http.StatusForbidden)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func RejectAPIKey(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if _, authenticatedByKey := apiKeyIdFrom(r); authenticatedByKey {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func APIKeyAuth(authenticate *useCases.AuthenticateAPIKeyUseCase, maxRequests int, window time.Duration) func(http.Handler) http.Handler {
+	limiter := newKeyedRateLimiter(maxRequests, window, apiKeyRateLimitKey)
+
+	return func(next http.Handler) http.Handler {
+		limited := limiter(next)
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			rawKey, isKey := bearerAPIKey(r)
+			if !isKey {
+				next.ServeHTTP(w, r)
+				return
+			}
+
+			authenticated, err := authenticate.AuthenticateAPIKey(rawKey)
+			if err != nil {
+				writeAPIKeyError(w, err)
+				return
+			}
+
+			ctx := authtoken.NewContext(r.Context(), sessionClaimsFor(authenticated), nil)
+			ctx = context.WithValue(ctx, apiKeyIdContextKey{}, authenticated.Key.ID)
+			ctx = context.WithValue(ctx, apiKeyNameContextKey{}, authenticated.Key.Name)
+			limited.ServeHTTP(w, r.WithContext(ctx))
+		})
+	}
+}
+
+func writeAPIKeyError(w http.ResponseWriter, err error) {
+	if errors.Is(err, apikey.ErrAPIKeyInvalid) {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+	http.Error(w, "Internal server error", http.StatusInternalServerError)
+}
+
+func sessionClaimsFor(authenticated useCases.AuthenticatedAPIKey) authtoken.Claims {
+	return authtoken.Claims{
+		"user_id":       float64(authenticated.User.ID),
+		"token_version": float64(authenticated.User.TokenVersion),
+	}
+}
+
+func apiKeyRateLimitKey(r *http.Request) string {
+	id, _ := apiKeyIdFrom(r)
+	return strconv.FormatUint(uint64(id), 10)
+}

api/middleware/auditContext.go

@@ -0,0 +1,66 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/internal/domain/audit"
+	"RenewCMS/internal/infrastructure/useCases"
+	"net/http"
+)
+
+func AuditContext(getUser *useCases.GetUserUseCase, trustedProxies []string) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			r = access.WithCurrentUser(r)
+			origin := audit.Origin{
+				Actor:     auditActor(getUser, r),
+				Source:    auditSource(r),
+				IP:        clientIP(r, trustedProxies),
+				UserAgent: truncatedUserAgent(r),
+			}
+			next.ServeHTTP(w, r.WithContext(audit.WithOrigin(r.Context(), origin)))
+		})
+	}
+}
+
+func auditActor(getUser *useCases.GetUserUseCase, r *http.Request) audit.Actor {
+	if id, ok := apiKeyIdFrom(r); ok {
+		return audit.APIKeyActor(id, apiKeyNameFrom(r))
+	}
+	userId, ok := claims.UserId(r)
+	if !ok {
+		return audit.AnonymousActor("")
+	}
+	current, err := access.LoadUser(getUser, r, userId)
+	if err != nil {
+		return audit.AnonymousActor("")
+	}
+	tokenVersion, ok := claims.TokenVersion(r)
+	if !ok || tokenVersion != current.TokenVersion {
+		return audit.AnonymousActor("")
+	}
+	return audit.UserActor(current)
+}
+
+func auditSource(r *http.Request) audit.Source {
+	if _, ok := apiKeyIdFrom(r); ok {
+		return audit.SourceAPIKey
+	}
+	return audit.SourceWeb
+}
+
+func clientIP(r *http.Request, trustedProxies []string) string {
+	realIP := r.Header.Get("X-Real-IP")
+	if realIP != "" && isTrustedProxy(r.RemoteAddr, trustedProxies) {
+		return realIP
+	}
+	return hostOf(r.RemoteAddr)
+}
+
+func truncatedUserAgent(r *http.Request) string {
+	runes := []rune(r.Header.Get("User-Agent"))
+	if len(runes) > audit.MaxUserAgentLength {
+		runes = runes[:audit.MaxUserAgentLength]
+	}
+	return string(runes)
+}

api/middleware/auth.go

@@ -0,0 +1,82 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"errors"
+	"net/http"
+)
+
+func JsonContentTypeMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		next.ServeHTTP(w, r)
+	})
+}
+
+func resolveCurrentUser(getUser *useCases.GetUserUseCase, w http.ResponseWriter, r *http.Request) (user.User, bool) {
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return user.User{}, false
+	}
+
+	currentUser, err := access.LoadUser(getUser, r, userId)
+	if err != nil {
+		if errors.Is(err, user.ErrUserNotFound) {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return user.User{}, false
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return user.User{}, false
+	}
+
+	return currentUser, true
+}
+
+func RequireCurrentToken(getUser *useCases.GetUserUseCase) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			r = access.WithCurrentUser(r)
+			currentUser, ok := resolveCurrentUser(getUser, w, r)
+			if !ok {
+				return
+			}
+
+			tokenVersion, ok := claims.TokenVersion(r)
+			if !ok {
+				http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+				return
+			}
+
+			if tokenVersion != currentUser.TokenVersion {
+				http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+				return
+			}
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+func RequireVerifiedUser(getUser *useCases.GetUserUseCase) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			r = access.WithCurrentUser(r)
+			currentUser, ok := resolveCurrentUser(getUser, w, r)
+			if !ok {
+				return
+			}
+
+			if !currentUser.IsVerified {
+				http.Error(w, apperr.VerificationRequiredErrorMessage, http.StatusForbidden)
+				return
+			}
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}

api/middleware/cors.go

@@ -0,0 +1,138 @@
+package middleware
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+)
+
+const (
+	corsAllowAnyOrigin   = "*"
+	corsWildcardMarker   = "*"
+	corsPreflightMaxAge  = 300
+	corsPreflightSuccess = http.StatusNoContent
+)
+
+var (
+	corsAllowedMethods = []string{http.MethodGet, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete, http.MethodOptions}
+	corsAllowedHeaders = []string{"Accept", "Authorization", "Content-Type", "X-CSRF-Token"}
+	corsExposedHeaders = []string{"Link", "X-Total-Count"}
+)
+
+type originWildcard struct {
+	prefix string
+	suffix string
+}
+
+func (w originWildcard) matches(origin string) bool {
+	return len(origin) >= len(w.prefix)+len(w.suffix) && strings.HasPrefix(origin, w.prefix) && strings.HasSuffix(origin, w.suffix)
+}
+
+type originPolicy struct {
+	anyOrigin bool
+	exact     map[string]struct{}
+	wildcards []originWildcard
+}
+
+func newOriginPolicy(origins []string) originPolicy {
+	policy := originPolicy{exact: map[string]struct{}{}}
+	for _, origin := range origins {
+		origin = strings.ToLower(strings.TrimSpace(origin))
+		prefix, suffix, hasWildcard := strings.Cut(origin, corsWildcardMarker)
+		switch {
+		case origin == "":
+		case origin == corsAllowAnyOrigin:
+			policy.anyOrigin = true
+		case hasWildcard:
+			policy.wildcards = append(policy.wildcards, originWildcard{prefix: prefix, suffix: suffix})
+		default:
+			policy.exact[origin] = struct{}{}
+		}
+	}
+	return policy
+}
+
+func (p originPolicy) allows(origin string) bool {
+	if p.anyOrigin {
+		return true
+	}
+	origin = strings.ToLower(origin)
+	if _, ok := p.exact[origin]; ok {
+		return true
+	}
+	for _, wildcard := range p.wildcards {
+		if wildcard.matches(origin) {
+			return true
+		}
+	}
+	return false
+}
+
+func isPreflight(r *http.Request) bool {
+	return r.Method == http.MethodOptions && r.Header.Get("Access-Control-Request-Method") != ""
+}
+
+func containsFold(allowed []string, value string) bool {
+	for _, candidate := range allowed {
+		if strings.EqualFold(candidate, value) {
+			return true
+		}
+	}
+	return false
+}
+
+func requestedHeadersAllowed(r *http.Request) bool {
+	requested := r.Header.Get("Access-Control-Request-Headers")
+	if requested == "" {
+		return true
+	}
+	for _, header := range strings.Split(requested, ",") {
+		if header = strings.TrimSpace(header); header != "" && !containsFold(corsAllowedHeaders, header) {
+			return false
+		}
+	}
+	return true
+}
+
+func CORS(allowedOrigins []string) func(http.Handler) http.Handler {
+	policy := newOriginPolicy(allowedOrigins)
+
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			origin := r.Header.Get("Origin")
+			if origin == "" {
+				next.ServeHTTP(w, r)
+				return
+			}
+
+			w.Header().Add("Vary", "Origin")
+			if isPreflight(r) {
+				answerPreflight(w, r, origin, policy)
+				return
+			}
+
+			if policy.allows(origin) {
+				w.Header().Set("Access-Control-Allow-Origin", origin)
+				w.Header().Set("Access-Control-Expose-Headers", strings.Join(corsExposedHeaders, ", "))
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+func answerPreflight(w http.ResponseWriter, r *http.Request, origin string, policy originPolicy) {
+	w.Header().Add("Vary", "Access-Control-Request-Method")
+	w.Header().Add("Vary", "Access-Control-Request-Headers")
+
+	method := r.Header.Get("Access-Control-Request-Method")
+	if !policy.allows(origin) || !containsFold(corsAllowedMethods, method) || !requestedHeadersAllowed(r) {
+		w.WriteHeader(http.StatusOK)
+		return
+	}
+
+	w.Header().Set("Access-Control-Allow-Origin", origin)
+	w.Header().Set("Access-Control-Allow-Methods", strings.ToUpper(method))
+	w.Header().Set("Access-Control-Allow-Headers", strings.Join(corsAllowedHeaders, ", "))
+	w.Header().Set("Access-Control-Max-Age", strconv.Itoa(corsPreflightMaxAge))
+	w.WriteHeader(corsPreflightSuccess)
+}

api/middleware/crossOrigin.go

@@ -0,0 +1,36 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"net/http"
+	"net/url"
+)
+
+func CrossOriginProtection(publicURL string) func(http.Handler) http.Handler {
+	protection := http.NewCrossOriginProtection()
+	if origin, ok := originOf(publicURL); ok {
+		_ = protection.AddTrustedOrigin(origin)
+	}
+	protection.SetDenyHandler(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, apperr.CrossOriginErrorMessage, http.StatusForbidden)
+	}))
+
+	return func(next http.Handler) http.Handler {
+		protected := protection.Handler(next)
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Header.Get("Authorization") != "" {
+				next.ServeHTTP(w, r)
+				return
+			}
+			protected.ServeHTTP(w, r)
+		})
+	}
+}
+
+func originOf(rawURL string) (string, bool) {
+	parsed, err := url.Parse(rawURL)
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+		return "", false
+	}
+	return parsed.Scheme + "://" + parsed.Host, true
+}

api/middleware/optionalAccess.go

@@ -0,0 +1,53 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"errors"
+	"net/http"
+)
+
+func OptionalAccess(getUser *useCases.GetUserUseCase, check *useCases.CheckPermissionUseCase) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			r = access.WithCurrentUser(r)
+			account, signedIn, err := verifiedAccount(getUser, r)
+			if err != nil {
+				http.Error(w, "Internal server error", http.StatusInternalServerError)
+				return
+			}
+			if !signedIn {
+				next.ServeHTTP(w, r)
+				return
+			}
+			grants, err := check.Grants(account)
+			if err != nil {
+				http.Error(w, "Internal server error", http.StatusInternalServerError)
+				return
+			}
+			caller := access.Caller{UserID: account.ID, Grants: grants}
+			next.ServeHTTP(w, r.WithContext(access.WithCaller(r.Context(), caller)))
+		})
+	}
+}
+
+func verifiedAccount(getUser *useCases.GetUserUseCase, r *http.Request) (user.User, bool, error) {
+	userID, ok := claims.UserId(r)
+	if !ok {
+		return user.User{}, false, nil
+	}
+	account, err := access.LoadUser(getUser, r, userID)
+	if errors.Is(err, user.ErrUserNotFound) {
+		return user.User{}, false, nil
+	}
+	if err != nil {
+		return user.User{}, false, err
+	}
+	tokenVersion, ok := claims.TokenVersion(r)
+	if !ok || tokenVersion != account.TokenVersion {
+		return user.User{}, false, nil
+	}
+	return account, account.IsVerified, nil
+}

api/middleware/permission.go

@@ -0,0 +1,62 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/access"
+	"RenewCMS/internal/domain/builtintype"
+	"RenewCMS/internal/domain/role"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"github.com/go-chi/chi/v5"
+	"net/http"
+)
+
+type grantCheck func(account user.User, r *http.Request) (role.GrantSet, error)
+
+func ArticleTypeKey(*http.Request) string {
+	return builtintype.KeyArticle
+}
+
+func PathTypeKey(r *http.Request) string {
+	return chi.URLParam(r, "key")
+}
+
+func RequirePermission(getUser *useCases.GetUserUseCase, check *useCases.CheckPermissionUseCase, key string) func(http.Handler) http.Handler {
+	return enforce(getUser, func(account user.User, _ *http.Request) (role.GrantSet, error) {
+		return check.Require(account, key)
+	})
+}
+
+func RequireFullScope(getUser *useCases.GetUserUseCase, check *useCases.CheckPermissionUseCase, key string) func(http.Handler) http.Handler {
+	return enforce(getUser, func(account user.User, _ *http.Request) (role.GrantSet, error) {
+		return check.RequireAll(account, key)
+	})
+}
+
+func RequireTypedPermission(getUser *useCases.GetUserUseCase, check *useCases.CheckPermissionUseCase, key string, typeKey func(r *http.Request) string) func(http.Handler) http.Handler {
+	return enforce(getUser, func(account user.User, r *http.Request) (role.GrantSet, error) {
+		return check.RequireFor(account, key, typeKey(r))
+	})
+}
+
+func enforce(getUser *useCases.GetUserUseCase, verify grantCheck) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			r = access.WithCurrentUser(r)
+			currentUser, ok := resolveCurrentUser(getUser, w, r)
+			if !ok {
+				return
+			}
+
+			grants, err := verify(currentUser, r)
+			if err != nil {
+				if !access.WriteIfMissingPermission(w, err) {
+					http.Error(w, "Internal server error", http.StatusInternalServerError)
+				}
+				return
+			}
+
+			caller := access.Caller{UserID: currentUser.ID, Grants: grants}
+			next.ServeHTTP(w, r.WithContext(access.WithCaller(r.Context(), caller)))
+		})
+	}
+}

api/middleware/rateLimit.go

@@ -0,0 +1,96 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	"net/http"
+	"strconv"
+	"sync"
+	"time"
+)
+
+type rateLimitWindow struct {
+	start time.Time
+	count int
+}
+
+type rateLimitCounters struct {
+	mu        sync.Mutex
+	window    time.Duration
+	windows   map[string]*rateLimitWindow
+	lastSweep time.Time
+}
+
+func NewRateLimiter(maxAttempts int, window time.Duration) func(http.Handler) http.Handler {
+	return newKeyedRateLimiter(maxAttempts, window, connectionHostKey)
+}
+
+func connectionHostKey(r *http.Request) string {
+	return hostOf(r.RemoteAddr)
+}
+
+func NewUserRateLimiter(maxAttempts int, window time.Duration) func(http.Handler) http.Handler {
+	return newKeyedRateLimiter(maxAttempts, window, userRateLimitKey)
+}
+
+func userRateLimitKey(r *http.Request) string {
+	userId, _ := claims.UserId(r)
+	return strconv.FormatUint(uint64(userId), 10)
+}
+
+func newKeyedRateLimiter(maxAttempts int, window time.Duration, keyOf func(*http.Request) string) func(http.Handler) http.Handler {
+	counters := &rateLimitCounters{window: window, windows: make(map[string]*rateLimitWindow)}
+
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			retryAfter, allowed := counters.recordAttempt(keyOf(r), maxAttempts, time.Now())
+			if !allowed {
+				w.Header().Set("Retry-After", strconv.Itoa(retryAfter))
+				http.Error(w, apperr.TooManyRequestsErrorMessage, http.StatusTooManyRequests)
+				return
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+func (c *rateLimitCounters) recordAttempt(key string, maxAttempts int, now time.Time) (int, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.sweepExpired(now)
+	current, exists := c.windows[key]
+	if !exists || now.Sub(current.start) >= c.window {
+		current = &rateLimitWindow{start: now}
+		c.windows[key] = current
+	}
+
+	current.count++
+	if current.count > maxAttempts {
+		return retryAfterSeconds(c.window - now.Sub(current.start)), false
+	}
+	return 0, true
+}
+
+func (c *rateLimitCounters) sweepExpired(now time.Time) {
+	if now.Sub(c.lastSweep) < c.window {
+		return
+	}
+	c.lastSweep = now
+	for key, current := range c.windows {
+		if now.Sub(current.start) >= c.window {
+			delete(c.windows, key)
+		}
+	}
+}
+
+func retryAfterSeconds(remaining time.Duration) int {
+	seconds := int(remaining / time.Second)
+	if remaining%time.Second > 0 {
+		seconds++
+	}
+	if seconds < 0 {
+		return 0
+	}
+	return seconds
+}

api/middleware/requireSignedIn.go

@@ -0,0 +1,17 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/authtoken"
+	"net/http"
+)
+
+func RequireSignedIn(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if _, err := authtoken.FromContext(r.Context()); err != nil {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}

api/middleware/securityHeaders.go

@@ -0,0 +1,33 @@
+package middleware
+
+import "net/http"
+
+const contentSecurityPolicy = "default-src 'self'; " +
+	"script-src 'self' 'wasm-unsafe-eval'; " +
+	"style-src 'self' 'unsafe-inline'; " +
+	"font-src 'self'; " +
+	"img-src 'self' data: blob: https:; " +
+	"connect-src 'self'; " +
+	"object-src 'none'; " +
+	"base-uri 'self'; " +
+	"form-action 'self'; " +
+	"frame-ancestors 'none'"
+
+const strictTransportSecurity = "max-age=31536000"
+
+func SecurityHeaders(hsts bool) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			h := w.Header()
+			h.Set("Content-Security-Policy", contentSecurityPolicy)
+			h.Set("X-Content-Type-Options", "nosniff")
+			h.Set("X-Frame-Options", "DENY")
+			h.Set("Referrer-Policy", "strict-origin-when-cross-origin")
+			h.Set("Cross-Origin-Opener-Policy", "same-origin")
+			if hsts {
+				h.Set("Strict-Transport-Security", strictTransportSecurity)
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}

api/middleware/successRateLimit.go

@@ -0,0 +1,90 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"net/http"
+	"strconv"
+	"sync"
+	"time"
+)
+
+type successSlots struct {
+	mu     sync.Mutex
+	window time.Duration
+	now    func() time.Time
+	taken  map[string]time.Time
+}
+
+func NewUserSuccessLimiter(window time.Duration) func(http.Handler) http.Handler {
+	return NewUserSuccessLimiterAt(window, time.Now)
+}
+
+func NewUserSuccessLimiterAt(window time.Duration, now func() time.Time) func(http.Handler) http.Handler {
+	slots := &successSlots{window: window, now: now, taken: make(map[string]time.Time)}
+
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			key := userRateLimitKey(r)
+			claimed, retryAfter, granted := slots.claim(key)
+			if !granted {
+				w.Header().Set("Retry-After", strconv.Itoa(retryAfter))
+				http.Error(w, apperr.TooManyRequestsErrorMessage, http.StatusTooManyRequests)
+				return
+			}
+
+			recorder := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
+			succeeded := false
+			defer func() {
+				if !succeeded {
+					slots.release(key, claimed)
+				}
+			}()
+			next.ServeHTTP(recorder, r)
+			succeeded = recorder.status < http.StatusBadRequest
+		})
+	}
+}
+
+func (s *successSlots) claim(key string) (time.Time, int, bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	now := s.now()
+	s.sweepExpired(now)
+	if claimedAt, held := s.taken[key]; held {
+		return time.Time{}, retryAfterSeconds(s.window - now.Sub(claimedAt)), false
+	}
+	s.taken[key] = now
+	return now, 0, true
+}
+
+func (s *successSlots) release(key string, claimedAt time.Time) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if current, held := s.taken[key]; held && current.Equal(claimedAt) {
+		delete(s.taken, key)
+	}
+}
+
+func (s *successSlots) sweepExpired(now time.Time) {
+	for key, claimedAt := range s.taken {
+		if now.Sub(claimedAt) >= s.window {
+			delete(s.taken, key)
+		}
+	}
+}
+
+type statusRecorder struct {
+	http.ResponseWriter
+	status int
+}
+
+func (s *statusRecorder) WriteHeader(status int) {
+	s.status = status
+	s.ResponseWriter.WriteHeader(status)
+}
+
+func (s *statusRecorder) Unwrap() http.ResponseWriter {
+	return s.ResponseWriter
+}

api/middleware/trustedProxyRealIP.go

@@ -0,0 +1,44 @@
+package middleware
+
+import (
+	"net"
+	"net/http"
+)
+
+func TrustedProxyRealIP(trustedProxies []string) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			realIP := r.Header.Get("X-Real-IP")
+			if realIP != "" && isTrustedProxy(r.RemoteAddr, trustedProxies) {
+				r.RemoteAddr = withRewrittenHost(r.RemoteAddr, realIP)
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+func isTrustedProxy(remoteAddr string, trustedProxies []string) bool {
+	host := hostOf(remoteAddr)
+	for _, trusted := range trustedProxies {
+		if host == trusted {
+			return true
+		}
+	}
+	return false
+}
+
+func hostOf(remoteAddr string) string {
+	host, _, err := net.SplitHostPort(remoteAddr)
+	if err != nil {
+		return remoteAddr
+	}
+	return host
+}
+
+func withRewrittenHost(remoteAddr string, newHost string) string {
+	_, port, err := net.SplitHostPort(remoteAddr)
+	if err != nil {
+		return newHost
+	}
+	return net.JoinHostPort(newHost, port)
+}

api/pkg/access/access.go

@@ -0,0 +1,41 @@
+package access
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/internal/domain/role"
+	"RenewCMS/internal/infrastructure/useCases"
+	"context"
+	"errors"
+	"net/http"
+)
+
+type Caller = useCases.ContentCaller
+
+type callerContextKey struct{}
+
+func WithCaller(ctx context.Context, caller Caller) context.Context {
+	return context.WithValue(ctx, callerContextKey{}, caller)
+}
+
+func CallerOf(r *http.Request) Caller {
+	caller, _ := r.Context().Value(callerContextKey{}).(Caller)
+	return caller
+}
+
+func Grants(r *http.Request) role.GrantSet {
+	return CallerOf(r).Grants
+}
+
+func WriteMissingPermission(w http.ResponseWriter, key string) {
+	w.Header().Set(apperr.MissingPermissionHeader, key)
+	http.Error(w, apperr.MissingPermissionErrorMessage, http.StatusForbidden)
+}
+
+func WriteIfMissingPermission(w http.ResponseWriter, err error) bool {
+	var missing role.MissingPermissionError
+	if !errors.As(err, &missing) {
+		return false
+	}
+	WriteMissingPermission(w, missing.Key)
+	return true
+}

api/pkg/access/currentUser.go

@@ -0,0 +1,37 @@
+package access
+
+import (
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"context"
+	"net/http"
+)
+
+type currentUserContextKey struct{}
+
+type currentUserHolder struct {
+	loaded  bool
+	userID  uint32
+	account user.User
+	err     error
+}
+
+func WithCurrentUser(r *http.Request) *http.Request {
+	if _, present := r.Context().Value(currentUserContextKey{}).(*currentUserHolder); present {
+		return r
+	}
+	return r.WithContext(context.WithValue(r.Context(), currentUserContextKey{}, &currentUserHolder{}))
+}
+
+func LoadUser(getUser *useCases.GetUserUseCase, r *http.Request, userID uint32) (user.User, error) {
+	holder, present := r.Context().Value(currentUserContextKey{}).(*currentUserHolder)
+	if !present {
+		return getUser.GetUser(userID)
+	}
+	if !holder.loaded || holder.userID != userID {
+		holder.account, holder.err = getUser.GetUser(userID)
+		holder.userID = userID
+		holder.loaded = true
+	}
+	return holder.account, holder.err
+}

api/pkg/apperr/messages.go

@@ -0,0 +1,138 @@
+package apperr
+
+const LogsErrorMessage = "Access to the requested resource is forbidden due to incorrect password and/or username."
+const BodyErrorMessage = "The request cannot be processed due to a mismatch in the format of the body."
+const IdUint32ErrorMessage = "The server expects the ID to be in the format of an unsigned 32-bit integer (uint32)."
+const ArticleNotFoundErrorMessage = "Article not found"
+const ImageNotFoundErrorMessage = "Image not found"
+const DisplayNameErrorMessage = "Display name must be 60 characters or fewer."
+const ArticleTitleErrorMessage = "Article title must be between 3 and 200 characters."
+const RegistrationClosedErrorMessage = "You are not allowed to create a user. Log in or reset database."
+const RegistrationFailedErrorMessage = "Registration failed. Please try again later."
+const UnauthorizedErrorMessage = "You must be logged in to access this resource."
+const VerificationFailedErrorMessage = "The verification code is invalid or has expired."
+const AlreadyVerifiedErrorMessage = "This account is already verified and cannot be cancelled this way."
+const VerificationRequiredErrorMessage = "You must verify your account to access this resource."
+const PasswordResetRequestedMessage = "If an account exists for that email, a password reset link has been sent."
+const PasswordResetFailedErrorMessage = "The password reset code is invalid or has expired."
+const TooManyRequestsErrorMessage = "Too many requests. Please try again later."
+const CrossOriginErrorMessage = "Cross-origin requests are not allowed."
+const EmailHasAccountErrorMessage = "This address already has an account."
+const PendingInviteErrorMessage = "There's already a pending invite for this address."
+const ErrorCodeHeader = "X-Error-Code"
+const EmailHasAccountErrorCode = "email_has_account"
+const InvitePendingErrorCode = "invite_pending"
+const InviteNotSentErrorMessage = "Couldn't send the invite. Try again in a moment."
+const InviteNotFoundErrorMessage = "Invite not found"
+const InviteAlreadyAcceptedErrorMessage = "This invite has already been accepted."
+const InviteInvalidErrorMessage = "This invite link doesn't work."
+const InviteExpiredErrorMessage = "This invite has expired."
+const UsernameTakenErrorMessage = "That username is taken. Try another."
+const PasswordTooLongErrorMessage = "The password must be 72 bytes or fewer."
+const MediaQueryErrorMessage = "The media query is invalid."
+const MediaFilenameErrorMessage = "Enter a filename."
+const MediaMergeConflictErrorMessage = "Some of the images to merge changed. Refresh and try again."
+const MediaMergeRequestErrorMessage = "Choose an image to keep and at least one other image to merge into it."
+const UpdateNotPreparedErrorMessage = "This server cannot update itself yet."
+const UpdateAlreadyRunningErrorMessage = "An update is already running or waiting to be installed."
+const NothingToUpdateErrorMessage = "There is nothing to update."
+const UpdateRefusedErrorMessage = "This update cannot be downloaded."
+const UpdateRestartMismatchErrorMessage = "The update state changed. Reload the page and try again."
+const ArticleBodyFormatErrorMessage = "The format must be one of: markdown, html, json."
+const APIKeyNotFoundErrorMessage = "API key not found"
+const APIKeyExpiryErrorMessage = "The expiry must be a date in the future."
+const MissingPermissionErrorMessage = "missing_permission"
+const MissingPermissionHeader = "X-Missing-Permission"
+const SessionRequiredErrorMessage = "This action needs a real session."
+const PurgeConflictErrorMessage = "The library changed, so nothing was purged. Check the new summary and try again."
+const PurgeBusyErrorMessage = "A purge is already running."
+const PurgeIntervalErrorMessage = "Enter a whole number of days between 1 and 365."
+const VariantNotFoundErrorMessage = "Variant not found"
+const VariantNameErrorMessage = "Use lowercase letters, numbers and dashes, 2 to 32 characters."
+const VariantDimensionsErrorMessage = "Width and height must be between 1 and 8000, and one of them is required."
+const VariantFitErrorMessage = "Fit must be cover, contain or inside."
+const VariantQualityErrorMessage = "Quality must be between 1 and 100."
+const VariantInvalidErrorMessage = "The variant is not valid."
+const VariantExistsErrorMessageFormat = "A variant named “%s” already exists. Choose another name."
+const VariantFormatErrorMessageFormat = "Format must be %s."
+const VariantSourceTooLargeErrorMessage = "The source image is too large to generate this variant."
+const VariantSourceUnsupportedErrorMessage = "Variants aren't generated for this format."
+const VariantSourceUnreadableErrorMessage = "The source image can't be read, so this variant can't be generated."
+const CachePurgeScopeErrorMessage = "Scope must be all, unused, variant or image."
+const CachePurgeTargetErrorMessage = "A variant name or an image id is required for this scope."
+const VariantUnknownMessage = "Unknown variant"
+const VariantUnsupportedParameterMessage = "Unsupported parameter"
+const SiteNotFoundErrorMessage = "site_not_found"
+const SiteKeyTakenErrorMessage = "site_key_taken"
+const SiteHasArticlesErrorMessage = "site_has_articles"
+const DefaultSiteErrorMessage = "default_site"
+const SiteKeyImmutableErrorMessage = "key_immutable"
+const InvalidSiteURLErrorMessage = "invalid_site_url"
+const InvalidLocaleErrorMessage = "invalid_locale"
+const SiteImageNotFoundErrorMessage = "image_not_found"
+const UseSetDefaultErrorMessage = "use_set_default"
+const InvalidReassignErrorMessage = "invalid_reassign"
+const ReassignTargetNotFoundErrorMessage = "target_role_not_found"
+const InvalidSocialTypeErrorMessage = "invalid_social_type"
+
+const AuthorNotFoundErrorMessage = "author_not_found"
+const AuthorSlugTakenErrorMessage = "author_slug_taken"
+const AuthorHasArticlesErrorMessage = "author_has_articles"
+const UserAlreadyLinkedErrorMessage = "user_already_linked"
+const AuthorAlreadyLinkedErrorMessage = "author_already_linked"
+const UserNotFoundErrorMessage = "user_not_found"
+const AuthorRightsErrorMessage = "author_rights"
+const BioTooLongErrorMessage = "bio_too_long"
+const InvalidURLErrorMessage = "invalid_url"
+const TooManyLinksErrorMessage = "too_many_links"
+const InvalidSlugErrorMessage = "invalid_slug"
+const AuthorImageNotFoundErrorMessage = "image_not_found"
+
+const ArticleSlugTakenErrorMessage = "slug_taken"
+const ArticleImageNotFoundErrorMessage = "image_not_found"
+const InvalidTitleTemplateErrorMessage = "invalid_title_template"
+const SlugSuggestionHeader = "X-Slug-Suggestion"
+
+const ContentTypeNotFoundErrorMessage = "content_type_not_found"
+const ContentTypeKeyTakenErrorMessage = "content_type_key_taken"
+const ContentTypeHasEntriesErrorMessage = "content_type_has_entries"
+const ContentTypeReferencedErrorMessage = "content_type_referenced"
+const InvalidContentTypeKeyErrorMessage = "invalid_content_type_key"
+const InvalidIconErrorMessage = "invalid_icon"
+const BuiltinTypeNotFoundErrorMessage = "builtin_type_not_found"
+const InvalidFieldErrorMessage = "invalid_field"
+const SchemaIncompatibleErrorMessage = "schema_incompatible"
+const EntryNotFoundErrorMessage = "entry_not_found"
+const InvalidEntryErrorMessage = "invalid_entry"
+
+const RoleNotFoundErrorMessage = "role_not_found"
+const RoleLockedErrorMessage = "role_locked"
+const RoleBuiltInErrorMessage = "role_built_in"
+const BuiltInNameErrorMessage = "built_in_name"
+const NotBuiltInErrorMessage = "not_built_in"
+const OwnRoleErrorMessage = "own_role"
+const EscalationErrorMessage = "escalation"
+const EscalationHeader = "X-Escalation-Key"
+const RoleNameTakenErrorMessage = "role_name_taken"
+const RoleConflictErrorMessage = "role_conflict"
+const RoleHasMembersErrorMessage = "role_has_members"
+const InvalidRoleNameErrorMessage = "invalid_role_name"
+const UnknownPermissionErrorMessage = "unknown_permission"
+const InvalidScopeErrorMessage = "invalid_scope"
+const OwnerOnlyPermissionErrorMessage = "owner_only_permission"
+const DuplicatePermissionErrorMessage = "duplicate_permission"
+const UnknownContentTypeErrorMessage = "unknown_content_type"
+
+const InvalidRoleErrorMessage = "invalid_role"
+const UserRoleChangedErrorMessage = "user_role_changed"
+const InvalidTransferErrorMessage = "invalid_transfer"
+const ConfirmationMismatchErrorMessage = "confirmation_mismatch"
+const WrongPasswordErrorCode = "wrong_password"
+const SameEmailErrorCode = "same_email"
+const NoPendingEmailChangeErrorCode = "no_pending_email_change"
+const InvalidEmailChangeCodeErrorCode = "invalid_email_change_code"
+const EmailUnavailableErrorCode = "email_unavailable"
+
+const LastAdminErrorCode = "last_admin"
+const AccountNotDeletableErrorCode = "account_not_deletable"
+const LastRoleHeader = "X-Last-Role"

api/pkg/authtoken/authtoken.go

@@ -0,0 +1,225 @@
+package authtoken
+
+import (
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"maps"
+	"strings"
+	"time"
+)
+
+const (
+	SessionLifetime = 24 * time.Hour
+
+	algorithmHS256 = "HS256"
+	tokenType      = "JWT"
+	maxTokenBytes  = 4096
+	segmentCount   = 3
+	segmentSep     = "."
+)
+
+var (
+	ErrNoToken     = errors.New("no token found")
+	ErrInvalid     = errors.New("token is invalid")
+	ErrExpired     = errors.New("token is expired")
+	ErrNotYetValid = errors.New("token is not yet valid")
+	ErrRevoked     = errors.New("token is revoked")
+)
+
+type RevocationStore interface {
+	Revoke(id string, expiresAt time.Time) error
+	IsRevoked(id string) (bool, error)
+}
+
+type Claims map[string]any
+
+type header struct {
+	Algorithm string `json:"alg"`
+	Type      string `json:"typ,omitempty"`
+}
+
+type Auth struct {
+	secret      []byte
+	clock       func() time.Time
+	revocations RevocationStore
+}
+
+type Option func(*Auth)
+
+func WithClock(clock func() time.Time) Option {
+	return func(a *Auth) { a.clock = clock }
+}
+
+func WithRevocationStore(store RevocationStore) Option {
+	return func(a *Auth) { a.revocations = store }
+}
+
+func New(secret []byte, options ...Option) *Auth {
+	auth := &Auth{secret: secret, clock: time.Now}
+	for _, option := range options {
+		option(auth)
+	}
+	return auth
+}
+
+func (a *Auth) Encode(claims map[string]any) (string, error) {
+	payload := maps.Clone(claims)
+	if payload == nil {
+		payload = map[string]any{}
+	}
+	now := a.clock()
+	if _, ok := payload["iat"]; !ok {
+		payload["iat"] = now.Unix()
+	}
+	if _, ok := payload["exp"]; !ok {
+		payload["exp"] = now.Add(SessionLifetime).Unix()
+	}
+	if _, ok := payload["jti"]; !ok {
+		payload["jti"] = rand.Text()
+	}
+
+	headerSegment, err := encodeSegment(header{Algorithm: algorithmHS256, Type: tokenType})
+	if err != nil {
+		return "", err
+	}
+	payloadSegment, err := encodeSegment(payload)
+	if err != nil {
+		return "", err
+	}
+
+	signingInput := headerSegment + segmentSep + payloadSegment
+	return signingInput + segmentSep + a.sign(signingInput), nil
+}
+
+func (a *Auth) Decode(token string) (Claims, error) {
+	if token == "" {
+		return nil, ErrNoToken
+	}
+	if len(token) > maxTokenBytes {
+		return nil, ErrInvalid
+	}
+
+	segments := strings.Split(token, segmentSep)
+	if len(segments) != segmentCount {
+		return nil, ErrInvalid
+	}
+
+	var tokenHeader header
+	if err := decodeSegment(segments[0], &tokenHeader); err != nil || tokenHeader.Algorithm != algorithmHS256 {
+		return nil, ErrInvalid
+	}
+
+	signingInput := segments[0] + segmentSep + segments[1]
+	if !hmac.Equal([]byte(a.sign(signingInput)), []byte(segments[2])) {
+		return nil, ErrInvalid
+	}
+
+	var claims Claims
+	if err := decodeSegment(segments[1], &claims); err != nil || claims == nil {
+		return nil, ErrInvalid
+	}
+
+	if err := a.validateTimes(claims); err != nil {
+		return nil, err
+	}
+	if err := a.checkRevocation(claims); err != nil {
+		return nil, err
+	}
+	return claims, nil
+}
+
+func (a *Auth) Revoke(claims Claims) error {
+	id, ok := claims["jti"].(string)
+	if !ok || a.revocations == nil {
+		return nil
+	}
+	expiry, present, err := numericDate(claims, "exp")
+	if err != nil || !present {
+		return ErrInvalid
+	}
+	return a.revocations.Revoke(id, expiry)
+}
+
+func (a *Auth) checkRevocation(claims Claims) error {
+	raw, present := claims["jti"]
+	if !present {
+		return nil
+	}
+	id, ok := raw.(string)
+	if !ok {
+		return ErrInvalid
+	}
+	if a.revocations == nil {
+		return nil
+	}
+	revoked, err := a.revocations.IsRevoked(id)
+	if err != nil {
+		return errors.Join(ErrInvalid, err)
+	}
+	if revoked {
+		return ErrRevoked
+	}
+	return nil
+}
+
+func (a *Auth) validateTimes(claims Claims) error {
+	now := a.clock()
+
+	expiry, present, err := numericDate(claims, "exp")
+	if err != nil {
+		return err
+	}
+	if !present {
+		return ErrInvalid
+	}
+	if !now.Before(expiry) {
+		return ErrExpired
+	}
+
+	notBefore, present, err := numericDate(claims, "nbf")
+	if err != nil {
+		return err
+	}
+	if present && now.Before(notBefore) {
+		return ErrNotYetValid
+	}
+	return nil
+}
+
+func numericDate(claims Claims, name string) (time.Time, bool, error) {
+	raw, present := claims[name]
+	if !present {
+		return time.Time{}, false, nil
+	}
+	seconds, ok := raw.(float64)
+	if !ok {
+		return time.Time{}, false, ErrInvalid
+	}
+	return time.Unix(int64(seconds), 0), true, nil
+}
+
+func (a *Auth) sign(signingInput string) string {
+	mac := hmac.New(sha256.New, a.secret)
+	mac.Write([]byte(signingInput))
+	return base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
+}
+
+func encodeSegment(value any) (string, error) {
+	encoded, err := json.Marshal(value)
+	if err != nil {
+		return "", err
+	}
+	return base64.RawURLEncoding.EncodeToString(encoded), nil
+}
+
+func decodeSegment(segment string, into any) error {
+	decoded, err := base64.RawURLEncoding.DecodeString(segment)
+	if err != nil {
+		return err
+	}
+	return json.Unmarshal(decoded, into)
+}

api/pkg/authtoken/cookie.go

@@ -0,0 +1,19 @@
+package authtoken
+
+import (
+	"net/http"
+	"time"
+)
+
+func ExpiredCookie(secure bool) *http.Cookie {
+	return &http.Cookie{
+		Name:     CookieName,
+		Value:    "",
+		Expires:  time.Now(),
+		MaxAge:   -1,
+		Secure:   secure,
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+		Path:     "/",
+	}
+}

api/pkg/authtoken/middleware.go

@@ -0,0 +1,79 @@
+package authtoken
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"context"
+	"net/http"
+	"strings"
+)
+
+const (
+	CookieName   = "jwt"
+	bearerPrefix = "bearer "
+)
+
+type contextKey struct{}
+
+type verdict struct {
+	claims Claims
+	err    error
+}
+
+func Verifier(auth *Auth) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			claims, err := auth.Decode(tokenFromRequest(r))
+			next.ServeHTTP(w, r.WithContext(NewContext(r.Context(), claims, err)))
+		})
+	}
+}
+
+func Authenticator(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if _, err := FromContext(r.Context()); err != nil {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func NewContext(ctx context.Context, claims Claims, err error) context.Context {
+	return context.WithValue(ctx, contextKey{}, verdict{claims: claims, err: err})
+}
+
+func FromContext(ctx context.Context) (Claims, error) {
+	stored, ok := ctx.Value(contextKey{}).(verdict)
+	switch {
+	case !ok:
+		return nil, ErrNoToken
+	case stored.err != nil:
+		return nil, stored.err
+	case stored.claims == nil:
+		return nil, ErrNoToken
+	}
+	return stored.claims, nil
+}
+
+func tokenFromRequest(r *http.Request) string {
+	if token := tokenFromHeader(r); token != "" {
+		return token
+	}
+	return tokenFromCookie(r)
+}
+
+func tokenFromHeader(r *http.Request) string {
+	header := r.Header.Get("Authorization")
+	if len(header) <= len(bearerPrefix) || !strings.EqualFold(header[:len(bearerPrefix)], bearerPrefix) {
+		return ""
+	}
+	return header[len(bearerPrefix):]
+}
+
+func tokenFromCookie(r *http.Request) string {
+	cookie, err := r.Cookie(CookieName)
+	if err != nil {
+		return ""
+	}
+	return cookie.Value
+}

api/pkg/claims/claims.go

@@ -0,0 +1,49 @@
+package claims
+
+import (
+	"RenewCMS/api/pkg/authtoken"
+	"math"
+	"net/http"
+)
+
+func UserId(r *http.Request) (uint32, bool) {
+	claims, err := authtoken.FromContext(r.Context())
+	if err != nil {
+		return 0, false
+	}
+
+	rawUserId, ok := claims["user_id"]
+	if !ok {
+		return 0, false
+	}
+
+	userIdFloat, ok := rawUserId.(float64)
+	if !ok {
+		return 0, false
+	}
+
+	if userIdFloat < 0 || userIdFloat > math.MaxUint32 || userIdFloat != math.Trunc(userIdFloat) {
+		return 0, false
+	}
+
+	return uint32(userIdFloat), true
+}
+
+func TokenVersion(r *http.Request) (uint32, bool) {
+	claims, err := authtoken.FromContext(r.Context())
+	if err != nil {
+		return 0, false
+	}
+
+	rawTokenVersion, ok := claims["token_version"]
+	if !ok {
+		return 0, false
+	}
+
+	tokenVersionFloat, ok := rawTokenVersion.(float64)
+	if !ok {
+		return 0, false
+	}
+
+	return uint32(tokenVersionFloat), true
+}

api/pkg/payload/role.go

@@ -0,0 +1,91 @@
+package payload
+
+import (
+	"RenewCMS/internal/domain/role"
+	"RenewCMS/internal/infrastructure/useCases"
+	"time"
+)
+
+type RoleRef struct {
+	ID      uint32 `json:"id"`
+	Name    string `json:"name"`
+	BuiltIn bool   `json:"built_in"`
+	Locked  bool   `json:"locked"`
+}
+
+type RoleAssigner struct {
+	ID   uint32 `json:"id"`
+	Name string `json:"name"`
+}
+
+type RoleEditor struct {
+	ID   uint32 `json:"id"`
+	Name string `json:"name"`
+}
+
+type RoleView struct {
+	role.Role
+	Members   int         `json:"members"`
+	UpdatedAt *time.Time  `json:"updated_at"`
+	UpdatedBy *RoleEditor `json:"updated_by"`
+}
+
+type OwnershipSuccessor struct {
+	ID   uint32 `json:"id"`
+	Name string `json:"name"`
+}
+
+type OwnershipPredecessor struct {
+	ID   uint32  `json:"id"`
+	Name string  `json:"name"`
+	Role RoleRef `json:"role"`
+}
+
+type OwnershipTransfer struct {
+	Owner       OwnershipSuccessor   `json:"owner"`
+	FormerOwner OwnershipPredecessor `json:"former_owner"`
+}
+
+func RoleRefOf(ref useCases.RoleRef) RoleRef {
+	return RoleRef(ref)
+}
+
+func RoleRefPtrOf(ref *useCases.RoleRef) *RoleRef {
+	if ref == nil {
+		return nil
+	}
+	converted := RoleRefOf(*ref)
+	return &converted
+}
+
+func RoleAssignerPtrOf(assigner *useCases.RoleAssigner) *RoleAssigner {
+	if assigner == nil {
+		return nil
+	}
+	converted := RoleAssigner(*assigner)
+	return &converted
+}
+
+func RoleViewOf(view useCases.RoleView) RoleView {
+	converted := RoleView{Role: view.Role, Members: view.Members, UpdatedAt: view.UpdatedAt}
+	if view.UpdatedBy != nil {
+		editor := RoleEditor(*view.UpdatedBy)
+		converted.UpdatedBy = &editor
+	}
+	return converted
+}
+
+func RoleViewsOf(views []useCases.RoleView) []RoleView {
+	converted := make([]RoleView, 0, len(views))
+	for _, view := range views {
+		converted = append(converted, RoleViewOf(view))
+	}
+	return converted
+}
+
+func OwnershipTransferOf(transfer useCases.OwnershipTransfer) OwnershipTransfer {
+	return OwnershipTransfer{
+		Owner:       OwnershipSuccessor(transfer.Owner),
+		FormerOwner: OwnershipPredecessor{ID: transfer.FormerOwner.ID, Name: transfer.FormerOwner.Name, Role: RoleRefOf(transfer.FormerOwner.Role)},
+	}
+}

api/pkg/publicuser/publicUser.go

@@ -0,0 +1,28 @@
+package publicuser
+
+import (
+	"RenewCMS/internal/domain/user"
+	"time"
+)
+
+type PublicUser struct {
+	ID          uint32    `json:"id"`
+	Username    string    `json:"username"`
+	Email       string    `json:"email"`
+	IsVerified  bool      `json:"is_verified"`
+	CreatedAt   time.Time `json:"created_at"`
+	UpdatedAt   time.Time `json:"updated_at"`
+	DisplayName string    `json:"display_name"`
+}
+
+func New(u user.User) PublicUser {
+	return PublicUser{
+		ID:          u.ID,
+		Username:    u.Username,
+		Email:       u.Email,
+		IsVerified:  u.IsVerified,
+		CreatedAt:   u.CreatedAt,
+		UpdatedAt:   u.UpdatedAt,
+		DisplayName: u.DisplayName,
+	}
+}

api/pkg/response/json.go

@@ -0,0 +1,21 @@
+package response
+
+import (
+	"encoding/json"
+	"log"
+	"net/http"
+)
+
+func WriteJSON(w http.ResponseWriter, status int, payload any) {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+	if status != http.StatusOK {
+		w.WriteHeader(status)
+	}
+	if _, err := w.Write(body); err != nil {
+		log.Printf("Failed to write response: %v", err)
+	}
+}

api/pkg/upload/upload.go

@@ -0,0 +1,49 @@
+package upload
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/internal/domain/image"
+	"errors"
+	"net/http"
+)
+
+const multipartOverheadAllowance = 1 << 20
+
+const fileField = "file"
+
+func ReadImageInput(w http.ResponseWriter, r *http.Request, uploadedById uint32) (image.ImageInput, func(), bool) {
+	r.Body = http.MaxBytesReader(w, r.Body, image.MaxImageSize+multipartOverheadAllowance)
+
+	file, header, err := r.FormFile(fileField)
+	if err != nil {
+		var tooLarge *http.MaxBytesError
+		if errors.As(err, &tooLarge) {
+			http.Error(w, image.ErrImageTooLarge.Error(), http.StatusRequestEntityTooLarge)
+			return image.ImageInput{}, nil, false
+		}
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return image.ImageInput{}, nil, false
+	}
+
+	input := image.ImageInput{
+		Content:      file,
+		Filename:     header.Filename,
+		Size:         header.Size,
+		ContentType:  header.Header.Get("Content-Type"),
+		UploadedByID: uploadedById,
+	}
+	return input, func() { _ = file.Close() }, true
+}
+
+func WriteCreateError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, image.ErrImageTypeNotAllowed):
+		http.Error(w, err.Error(), http.StatusUnsupportedMediaType)
+	case errors.Is(err, image.ErrImageTooLarge):
+		http.Error(w, err.Error(), http.StatusRequestEntityTooLarge)
+	case errors.Is(err, image.ErrImageUnreadable):
+		http.Error(w, err.Error(), http.StatusBadRequest)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}

api/pkg/validator/validator.go

@@ -0,0 +1,77 @@
+package validator
+
+import (
+	"RenewCMS/internal/domain/article"
+	"RenewCMS/internal/domain/author"
+	"RenewCMS/internal/domain/image"
+	"RenewCMS/internal/domain/site"
+	"reflect"
+	"regexp"
+
+	"github.com/go-playground/validator/v10"
+)
+
+const inviteEmailTag = "inviteemail"
+const variantNameTag = "variantname"
+const siteKeyTag = "sitekey"
+const siteNameTag = "sitename"
+const AuthorNameTag = "authorname"
+const AuthorSlugTag = "authorslug"
+const SocialTypeTag = "socialtype"
+const ArticleSlugTag = "articleslug"
+
+var inviteEmailPattern = regexp.MustCompile(`^[^\s@]+@[^\s@.]+(\.[^\s@.]+)+$`)
+
+var Validate *validator.Validate
+
+func InitValidator() {
+	Validate = validator.New()
+	_ = Validate.RegisterValidation(inviteEmailTag, isInviteEmail)
+	_ = Validate.RegisterValidation(variantNameTag, isVariantName)
+	_ = Validate.RegisterValidation(siteKeyTag, isSiteKey)
+	_ = Validate.RegisterValidation(siteNameTag, isSiteName)
+	_ = Validate.RegisterValidation(AuthorNameTag, isAuthorName, true)
+	_ = Validate.RegisterValidation(AuthorSlugTag, isAuthorSlug, true)
+	_ = Validate.RegisterValidation(SocialTypeTag, isSocialType, true)
+	_ = Validate.RegisterValidation(ArticleSlugTag, isArticleSlug, true)
+}
+
+func isArticleSlug(field validator.FieldLevel) bool {
+	if isAbsent(field) {
+		return true
+	}
+	value := field.Field().String()
+	return value == "" || article.IsValidSlug(value)
+}
+
+func isAbsent(field validator.FieldLevel) bool {
+	return field.Field().Kind() == reflect.Ptr && field.Field().IsNil()
+}
+
+func isAuthorName(field validator.FieldLevel) bool {
+	return isAbsent(field) || author.IsValidName(field.Field().String())
+}
+
+func isSocialType(field validator.FieldLevel) bool {
+	return author.IsValidSocialType(field.Field().String())
+}
+
+func isAuthorSlug(field validator.FieldLevel) bool {
+	return isAbsent(field) || author.IsValidSlug(field.Field().String())
+}
+
+func isSiteKey(field validator.FieldLevel) bool {
+	return site.IsValidKey(field.Field().String())
+}
+
+func isSiteName(field validator.FieldLevel) bool {
+	return site.IsValidName(field.Field().String())
+}
+
+func isVariantName(field validator.FieldLevel) bool {
+	return image.IsValidVariantName(field.Field().String())
+}
+
+func isInviteEmail(field validator.FieldLevel) bool {
+	return inviteEmailPattern.MatchString(field.Field().String())
+}

api/router.go

@@ -0,0 +1,642 @@
+package api
+
+import (
+	"RenewCMS/api/handlers/activity"
+	"RenewCMS/api/handlers/apikey"
+	"RenewCMS/api/handlers/article"
+	"RenewCMS/api/handlers/auth"
+	"RenewCMS/api/handlers/author"
+	"RenewCMS/api/handlers/builtintype"
+	"RenewCMS/api/handlers/contenttype"
+	"RenewCMS/api/handlers/entry"
+	"RenewCMS/api/handlers/frontend"
+	"RenewCMS/api/handlers/imagevariant"
+	"RenewCMS/api/handlers/llms"
+	"RenewCMS/api/handlers/media"
+	"RenewCMS/api/handlers/ownership"
+	"RenewCMS/api/handlers/permission"
+	rolehandler "RenewCMS/api/handlers/role"
+	"RenewCMS/api/handlers/settings"
+	"RenewCMS/api/handlers/site"
+	"RenewCMS/api/handlers/staticimages"
+	"RenewCMS/api/handlers/update"
+	"RenewCMS/api/handlers/user"
+	"RenewCMS/api/middleware"
+	"RenewCMS/api/pkg/authtoken"
+	"RenewCMS/internal/domain/role"
+	"RenewCMS/internal/infrastructure/config"
+	"RenewCMS/internal/infrastructure/llmdocs"
+	"encoding/json"
+	"log"
+	"net/http"
+	"os"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	chimiddleware "github.com/go-chi/chi/v5/middleware"
+)
+
+func enableLoggingIfDev(r *chi.Mux, routerName string, environment string) {
+	if environment == "development" {
+		r.Use(chimiddleware.RequestLogger(&chimiddleware.DefaultLogFormatter{
+			Logger: log.New(os.Stdout, "["+routerName+"] ", log.LstdFlags),
+		}))
+	}
+}
+
+func GetHelloWorld(w http.ResponseWriter, _ *http.Request) {
+	msg, _ := json.Marshal(map[string]string{"message": "Hello World"})
+	_, _ = w.Write(msg)
+}
+
+const (
+	apiKeyMaxRequests = 120
+	apiKeyWindow      = time.Minute
+
+	emailChangeMaxRequests = 5
+	emailChangeWindow      = 15 * time.Minute
+
+	dataExportWindow = 15 * time.Minute
+
+	accountDeleteMaxRequests = 5
+	accountDeleteWindow      = 15 * time.Minute
+)
+
+func (c *UseCases) apiKeyAuth() func(http.Handler) http.Handler {
+	c.apiKeyAuthOnce.Do(func() {
+		c.apiKeyAuthMiddleware = middleware.APIKeyAuth(c.AuthenticateAPIKeyUseCase, apiKeyMaxRequests, apiKeyWindow)
+	})
+	return c.apiKeyAuthMiddleware
+}
+
+func (c *UseCases) require(key string) func(http.Handler) http.Handler {
+	return middleware.RequirePermission(c.GetUserUseCase, c.CheckPermissionUseCase, key)
+}
+
+func (c *UseCases) requireTyped(key string, typeKey func(*http.Request) string) func(http.Handler) http.Handler {
+	return middleware.RequireTypedPermission(c.GetUserUseCase, c.CheckPermissionUseCase, key, typeKey)
+}
+
+func (c *UseCases) requireArticle(key string) func(http.Handler) http.Handler {
+	return c.requireTyped(key, middleware.ArticleTypeKey)
+}
+
+func (c *UseCases) requireEntry(key string) func(http.Handler) http.Handler {
+	return c.requireTyped(key, middleware.PathTypeKey)
+}
+
+func (c *UseCases) requireAll(key string) func(http.Handler) http.Handler {
+	return middleware.RequireFullScope(c.GetUserUseCase, c.CheckPermissionUseCase, key)
+}
+
+func NewArticleRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+	r.Use(container.apiKeyAuth())
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+
+	articleHandler := article.NewHandler(container.CreateArticleUseCase, container.GetArticleUseCase, container.ListArticlesUseCase, container.DeleteArticleUseCase, container.UpdateArticleUseCase)
+
+	seoHandler := article.NewSEOHandler(container.ResolveArticleSEOUseCase, container.CheckArticleSEOUseCase)
+
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.OptionalAccess(container.GetUserUseCase, container.CheckPermissionUseCase))
+		r.Get("/", articleHandler.ListArticles)
+		r.Get("/{id}", articleHandler.GetArticle)
+		r.Get("/{id}/seo", seoHandler.Resolve)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.With(container.requireArticle(role.KeyContentCreate)).Post("/", articleHandler.PostArticle)
+		r.With(container.requireArticle(role.KeyContentDelete)).Delete("/{id}", articleHandler.DeleteArticle)
+		r.With(container.requireArticle(role.KeyContentUpdate)).Patch("/{id}", articleHandler.UpdateArticleBody)
+		r.With(container.requireArticle(role.KeyContentPublish)).Patch("/{id}/publish", articleHandler.PublishArticle)
+		r.With(container.requireArticle(role.KeyContentPublish)).Patch("/{id}/unpublish", articleHandler.UnpublishArticle)
+		r.With(container.requireArticle(role.KeyContentRead)).Post("/{id}/seo/check", seoHandler.Check)
+	})
+	return r
+}
+
+func NewAuthRouter(container *UseCases, isProduction bool, rateLimit config.AuthRateLimitSettings, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+	r.Use(authtoken.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+
+	loginHandler := auth.NewLoginHandler(container.Token, container.CreateUserUseCase, container.AuthenticateUserUseCase, isProduction)
+	verificationHandler := auth.NewVerificationHandler(container.VerifyUserUseCase, container.CancelRegistrationUseCase, isProduction)
+	meHandler := auth.NewMeHandler(container.GetUserUseCase, container.GetMyAuthorUseCase, container.GetMyAccessUseCase)
+	passwordResetHandler := auth.NewPasswordResetHandler(container.RequestPasswordResetUseCase, container.ResetPasswordUseCase)
+	emailChangeHandler := auth.NewEmailChangeHandler(container.RequestEmailChangeUseCase, container.ResendEmailChangeUseCase, container.CancelEmailChangeUseCase, container.ConfirmEmailChangeUseCase)
+	acceptInviteHandler := auth.NewAcceptInviteHandler(container.GetInviteUseCase, container.AcceptInviteUseCase, container.Token, isProduction)
+
+	r.Post("/register", loginHandler.Register)
+	r.Get("/registration", loginHandler.RegistrationStatus)
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.TrustedProxyRealIP(trustedProxies))
+		r.Use(middleware.NewRateLimiter(rateLimit.MaxAttempts, rateLimit.Window))
+		r.Post("/login", loginHandler.Login)
+	})
+	r.Post("/logout", loginHandler.Logout)
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.TrustedProxyRealIP(trustedProxies))
+		r.Use(middleware.NewRateLimiter(rateLimit.MaxAttempts, rateLimit.Window))
+		r.Post("/password-reset", passwordResetHandler.RequestPasswordReset)
+	})
+	r.Post("/password-reset/confirm", passwordResetHandler.ResetPassword)
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.TrustedProxyRealIP(trustedProxies))
+		r.Use(middleware.NewRateLimiter(rateLimit.MaxAttempts, rateLimit.Window))
+		r.Get("/invite", acceptInviteHandler.GetInvite)
+		r.Post("/invite/accept", acceptInviteHandler.AcceptInvite)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Post("/verify", verificationHandler.Verify)
+		r.Delete("/register", verificationHandler.CancelRegistration)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Delete("/email/change", emailChangeHandler.Cancel)
+		r.Post("/email/confirm", emailChangeHandler.Confirm)
+		r.Group(func(r chi.Router) {
+			r.Use(middleware.NewUserRateLimiter(emailChangeMaxRequests, emailChangeWindow))
+			r.Post("/email/change", emailChangeHandler.Request)
+			r.Post("/email/resend", emailChangeHandler.Resend)
+		})
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(container.apiKeyAuth())
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Get("/me", meHandler.Me)
+	})
+	return r
+}
+
+func NewUserRouter(container *UseCases, isProduction bool, rateLimit config.AuthRateLimitSettings, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	userHandler := user.NewHandler(container.UpdateUserProfileUseCase)
+	lookupHandler := user.NewLookupHandler(container.LookupUserNamesUseCase)
+	inviteHandler := user.NewInviteHandler(container.CreateInviteUseCase, container.CancelInviteUseCase, container.RenewInviteUseCase, container.ListUsersAndInvitesUseCase)
+	roleHandler := user.NewRoleHandler(container.ChangeUserRoleUseCase)
+	removeHandler := user.NewRemoveHandler(container.RemoveUserUseCase)
+	exportHandler := user.NewExportHandler(container.ExportUserDataUseCase)
+	deleteAccountHandler := user.NewDeleteAccountHandler(container.DeleteOwnAccountUseCase, isProduction)
+
+	r.Group(func(r chi.Router) {
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(container.apiKeyAuth())
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Patch("/me", userHandler.UpdateMe)
+		r.With(container.require(role.KeyUsersView)).Get("/", inviteHandler.ListUsers)
+		r.Get("/lookup", lookupHandler.Lookup)
+		r.Group(func(r chi.Router) {
+			r.Use(container.require(role.KeyUsersInvite))
+			r.Use(middleware.TrustedProxyRealIP(trustedProxies))
+			r.Use(middleware.NewRateLimiter(rateLimit.MaxAttempts, rateLimit.Window))
+			r.Post("/invite", inviteHandler.CreateInvite)
+			r.Delete("/invite/{id}", inviteHandler.CancelInvite)
+			r.Post("/invite/{id}/renew", inviteHandler.RenewInvite)
+		})
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.With(middleware.NewUserSuccessLimiter(dataExportWindow)).Get("/me/export", exportHandler.Export)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Use(middleware.NewUserRateLimiter(accountDeleteMaxRequests, accountDeleteWindow))
+		r.Delete("/me", deleteAccountHandler.Delete)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Use(container.require(role.KeyUsersChangeRole))
+		r.Put("/{id}/role", roleHandler.Change)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Use(container.require(role.KeyUsersRemove))
+		r.Delete("/{id}", removeHandler.Remove)
+	})
+	return r
+}
+
+func NewSettingsRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	settingsHandler := settings.NewHandler(container.GetSettingsUseCase, container.GetActivityRetentionUseCase, container.UpdateActivityRetentionUseCase)
+
+	r.Group(func(r chi.Router) {
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(container.apiKeyAuth())
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Use(container.require(role.KeySettingsView))
+		r.Get("/", settingsHandler.GetSettings)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Use(container.require(role.KeySystemEditRetention))
+		r.Patch("/", settingsHandler.UpdateSettings)
+	})
+	return r
+}
+
+func NewSiteRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	siteHandler := site.NewHandler(container.ListSitesUseCase, container.CreateSiteUseCase, container.UpdateSiteUseCase, container.SetDefaultSiteUseCase, container.DeleteSiteUseCase)
+
+	sitemapHandler := site.NewSitemapHandler(container.ListSitemapUseCase)
+
+	ownershipHandler := ownership.NewHandler(container.TransferOwnershipUseCase)
+
+	r.Get("/{key}/sitemap", sitemapHandler.Sitemap)
+	r.Group(func(r chi.Router) {
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(container.apiKeyAuth())
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Get("/", siteHandler.List)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.With(container.require(role.KeySettingsManageSites)).Post("/", siteHandler.Create)
+		r.With(container.require(role.KeySettingsManageSites)).Patch("/{id}", siteHandler.Update)
+		r.With(container.require(role.KeySettingsManageSites)).Patch("/{id}/default", siteHandler.SetDefault)
+		r.With(container.require(role.KeySettingsDeleteSite)).Delete("/{id}", siteHandler.Delete)
+		r.With(container.require(role.KeySystemTransferOwnership)).Post("/transfer-ownership", ownershipHandler.Transfer)
+	})
+	return r
+}
+
+func NewRoleRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	roleHandler := rolehandler.NewHandler(container.ListRolesUseCase, container.GetRoleUseCase, container.CreateRoleUseCase, container.UpdateRoleUseCase, container.DeleteRoleUseCase, container.ReassignRoleMembersUseCase)
+
+	r.Group(func(r chi.Router) {
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(container.apiKeyAuth())
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Use(container.require(role.KeyRolesView))
+		r.Get("/", roleHandler.List)
+		r.Get("/{id}", roleHandler.Get)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Use(container.require(role.KeyRolesManage))
+		r.Post("/", roleHandler.Create)
+		r.Put("/{id}", roleHandler.Update)
+		r.Delete("/{id}", roleHandler.Delete)
+		r.Post("/{id}/reassign", roleHandler.Reassign)
+		r.Post("/{id}/reset", roleHandler.Reset)
+	})
+	return r
+}
+
+func NewAuthorRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	authorHandler := author.NewHandler(container.ListAuthorsUseCase, container.CreateAuthorUseCase, container.CreateMyAuthorUseCase, container.UpdateAuthorUseCase, container.DeleteAuthorUseCase)
+
+	r.Group(func(r chi.Router) {
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(container.apiKeyAuth())
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Use(container.require(role.KeyAuthorsView))
+		r.Get("/", authorHandler.List)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(authtoken.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(authtoken.Authenticator)
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Post("/me", authorHandler.CreateMine)
+		r.With(container.require(role.KeyAuthorsEdit)).Patch("/{id}", authorHandler.Update)
+		r.With(container.require(role.KeyAuthorsCreate)).Post("/", authorHandler.Create)
+		r.With(container.require(role.KeyAuthorsDelete)).Delete("/{id}", authorHandler.Delete)
+	})
+	return r
+}
+
+func NewContentTypeRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	contentTypeHandler := contenttype.NewHandler(container.CreateContentTypeUseCase, container.ListContentTypesUseCase, container.GetContentTypeUseCase, container.UpdateContentTypeUseCase, container.DeleteContentTypeUseCase)
+
+	entryHandler := entry.NewHandler(container.CreateEntryUseCase, container.GetEntryUseCase, container.ListEntriesUseCase, container.UpdateEntryUseCase, container.DeleteEntryUseCase)
+
+	r.Use(authtoken.Verifier(container.Token))
+	r.Use(container.apiKeyAuth())
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(middleware.RequireSignedIn)
+	r.Use(authtoken.Authenticator)
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.With(container.require(role.KeySchemaView)).Get("/", contentTypeHandler.List)
+	r.With(container.require(role.KeySchemaView)).Get("/{key}", contentTypeHandler.Get)
+	r.With(container.require(role.KeySchemaEdit)).Post("/", contentTypeHandler.Create)
+	r.With(container.require(role.KeySchemaEdit)).Put("/{key}", contentTypeHandler.Update)
+	r.With(container.require(role.KeySchemaDelete)).Delete("/{key}", contentTypeHandler.Delete)
+	r.With(container.requireEntry(role.KeyContentRead)).Get("/{key}/entry", entryHandler.List)
+	r.With(container.requireEntry(role.KeyContentCreate)).Post("/{key}/entry", entryHandler.Create)
+	r.With(container.requireEntry(role.KeyContentRead)).Get("/{key}/entry/{id}", entryHandler.Get)
+	r.With(container.requireEntry(role.KeyContentUpdate)).Put("/{key}/entry/{id}", entryHandler.Update)
+	r.With(container.requireEntry(role.KeyContentDelete)).Delete("/{key}/entry/{id}", entryHandler.Delete)
+	return r
+}
+
+func NewBuiltinTypeRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	builtinTypeHandler := builtintype.NewHandler(container.ListBuiltinTypesUseCase, container.GetBuiltinTypeUseCase)
+
+	r.Use(authtoken.Verifier(container.Token))
+	r.Use(container.apiKeyAuth())
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(middleware.RequireSignedIn)
+	r.Use(authtoken.Authenticator)
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.Use(container.require(role.KeySchemaView))
+	r.Get("/", builtinTypeHandler.List)
+	r.Get("/{key}", builtinTypeHandler.Get)
+	return r
+}
+
+func NewActivityRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	activityHandler := activity.NewHandler(container.ListActivityUseCase, container.GetActivitySummaryUseCase, container.ExportActivityUseCase)
+
+	r.Use(middleware.RequireSession)
+	r.Use(authtoken.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(middleware.RequireSignedIn)
+	r.Use(authtoken.Authenticator)
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.With(container.require(role.KeyActivityView)).Get("/", activityHandler.List)
+	r.With(container.requireAll(role.KeyActivityView)).Get("/summary", activityHandler.Summary)
+	r.With(container.require(role.KeyActivityExport), container.require(role.KeyActivityView)).Get("/export", activityHandler.Export)
+	return r
+}
+
+const (
+	updateCheckMaxAttempts    = 5
+	updateCheckWindow         = time.Minute
+	updateDownloadMaxAttempts = 5
+	updateDownloadWindow      = time.Minute
+)
+
+func NewSystemRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	updateHandler := update.NewHandler(container.GetUpdateStatusUseCase, container.CheckForUpdateUseCase, container.StartUpdateDownloadUseCase, container.RequestRestartUseCase)
+
+	r.Use(middleware.RequireSession)
+	r.Use(authtoken.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(authtoken.Authenticator)
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.With(container.require(role.KeySettingsView)).Get("/update", updateHandler.GetStatus)
+	r.Group(func(r chi.Router) {
+		r.Use(container.require(role.KeySystemApplyUpdates))
+		r.Use(middleware.NewUserRateLimiter(updateCheckMaxAttempts, updateCheckWindow))
+		r.Post("/update/check", updateHandler.Check)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(container.require(role.KeySystemApplyUpdates))
+		r.Use(middleware.NewUserRateLimiter(updateDownloadMaxAttempts, updateDownloadWindow))
+		r.Post("/update/download", updateHandler.Download)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(container.require(role.KeySystemApplyUpdates))
+		r.Post("/update/restart", updateHandler.Restart)
+	})
+	return r
+}
+
+func NewAPIKeyRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	apiKeyHandler := apikey.NewHandler(container.CreateAPIKeyUseCase, container.ListAPIKeysUseCase, container.RevokeAPIKeyUseCase)
+
+	r.Use(middleware.RequireSession)
+	r.Use(authtoken.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(authtoken.Authenticator)
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.With(container.require(role.KeyAPIKeysCreate)).Post("/", apiKeyHandler.Create)
+	r.With(container.require(role.KeyAPIKeysView)).Get("/", apiKeyHandler.List)
+	r.With(container.require(role.KeyAPIKeysRevoke)).Delete("/{id}", apiKeyHandler.Revoke)
+	return r
+}
+
+func NewPermissionRouter(container *UseCases) http.Handler {
+	r := chi.NewRouter()
+
+	permissionHandler := permission.NewHandler(container.ListPermissionsUseCase)
+
+	r.Use(authtoken.Verifier(container.Token))
+	r.Use(container.apiKeyAuth())
+	r.Use(authtoken.Authenticator)
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.Get("/", permissionHandler.List)
+	return r
+}
+
+func NewMediaRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	mediaHandler := media.NewHandler(container.CreateImageUseCase, container.ListMediaUseCase, container.RenameMediaUseCase, container.DeleteMediaUseCase, container.MergeMediaUseCase, container.GetMediaUsageUseCase, container.GetPurgeSettingsUseCase, container.UpdatePurgeSettingsUseCase, container.PreviewPurgeUseCase, container.RunPurgeUseCase, container.ListImageVariantsUseCase, container.GenerateImageVariantUseCase, container.GenerateAllImageVariantsUseCase, container.PurgeImageVariantUseCase, container.GenerateVariantsOnUploadUseCase)
+
+	r.Use(authtoken.Verifier(container.Token))
+	r.Use(container.apiKeyAuth())
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(middleware.RequireSignedIn)
+	r.Use(authtoken.Authenticator)
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.With(container.require(role.KeySettingsView)).Get("/purge-settings", mediaHandler.GetPurgeSettings)
+	r.With(container.require(role.KeySettingsEditGeneral)).Patch("/purge-settings", mediaHandler.UpdatePurgeSettings)
+	r.With(container.requireAll(role.KeyMediaDelete)).Get("/purge-preview", mediaHandler.PreviewPurge)
+	r.With(container.requireAll(role.KeyMediaDelete)).Post("/purge", mediaHandler.RunPurge)
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RejectAPIKey)
+		r.With(container.require(role.KeyMediaView)).Get("/{id}/variants", mediaHandler.ListVariants)
+		r.With(container.require(role.KeySettingsEditGeneral)).Post("/{id}/variants", mediaHandler.GenerateAllVariants)
+		r.With(container.require(role.KeySettingsEditGeneral)).Post("/{id}/variants/{name}", mediaHandler.GenerateVariant)
+		r.With(container.require(role.KeySettingsEditGeneral)).Delete("/{id}/variants/{name}", mediaHandler.PurgeVariant)
+	})
+	r.With(container.require(role.KeyMediaView)).Get("/", mediaHandler.List)
+	r.With(container.require(role.KeyMediaUpload)).Post("/", mediaHandler.Upload)
+	r.With(container.requireAll(role.KeyMediaDelete)).Post("/merge", mediaHandler.Merge)
+	r.With(container.require(role.KeyMediaUpload)).Patch("/{id}", mediaHandler.Rename)
+	r.With(container.requireAll(role.KeyMediaDelete)).Delete("/{id}", mediaHandler.Delete)
+	r.With(container.require(role.KeyMediaView)).Get("/{id}", mediaHandler.Get)
+	r.With(container.require(role.KeyMediaView)).Get("/{id}/usage", mediaHandler.Usage)
+	return r
+}
+
+func NewImageVariantRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	variantHandler := imagevariant.NewHandler(container.ListVariantsUseCase, container.CreateVariantUseCase, container.UpdateVariantUseCase, container.SetVariantEnabledUseCase, container.DeleteVariantUseCase, container.PurgeVariantUseCase, container.GetVariantCacheStatsUseCase, container.PurgeVariantCacheUseCase)
+
+	r.Use(authtoken.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(middleware.RequireSignedIn)
+	r.Use(authtoken.Authenticator)
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.With(container.require(role.KeyMediaView)).Get("/", variantHandler.List)
+	r.With(container.require(role.KeySettingsEditGeneral)).Post("/", variantHandler.Create)
+	r.With(container.require(role.KeySettingsView)).Get("/cache", variantHandler.CacheStats)
+	r.With(container.require(role.KeySettingsEditGeneral)).Post("/cache/purge", variantHandler.PurgeCache)
+	r.With(container.require(role.KeySettingsEditGeneral)).Put("/{name}", variantHandler.Update)
+	r.With(container.require(role.KeySettingsEditGeneral)).Patch("/{name}", variantHandler.SetEnabled)
+	r.With(container.require(role.KeySettingsEditGeneral)).Delete("/{name}", variantHandler.Delete)
+	r.With(container.require(role.KeySettingsEditGeneral)).Post("/{name}/purge", variantHandler.Purge)
+	return r
+}
+
+func InitBackendRoutes(container *UseCases, settings config.Settings) *chi.Mux {
+	r := chi.NewRouter()
+
+	enableLoggingIfDev(r, "backend", settings.Environment)
+
+	r.Use(chimiddleware.GetHead)
+	r.Use(middleware.JsonContentTypeMiddleware)
+	r.Get("/", GetHelloWorld)
+	r.Group(func(r chi.Router) {
+		r.Use(authtoken.Verifier(container.Token))
+		r.Mount("/article", NewArticleRouter(container, settings.TrustedProxies))
+	})
+	r.Mount("/user", NewUserRouter(container, settings.IsProduction(), settings.AuthRateLimit, settings.TrustedProxies))
+	r.Mount("/settings", NewSettingsRouter(container, settings.TrustedProxies))
+	r.Mount("/site", NewSiteRouter(container, settings.TrustedProxies))
+	r.Mount("/role", NewRoleRouter(container, settings.TrustedProxies))
+	r.Mount("/author", NewAuthorRouter(container, settings.TrustedProxies))
+	r.Mount("/content-type", NewContentTypeRouter(container, settings.TrustedProxies))
+	r.Mount("/builtin-type", NewBuiltinTypeRouter(container, settings.TrustedProxies))
+	r.Mount("/activity", NewActivityRouter(container, settings.TrustedProxies))
+	r.Mount("/media", NewMediaRouter(container, settings.TrustedProxies))
+	r.Mount("/image-variants", NewImageVariantRouter(container, settings.TrustedProxies))
+	r.Mount("/api-key", NewAPIKeyRouter(container, settings.TrustedProxies))
+	r.Mount("/permission", NewPermissionRouter(container))
+	r.Mount("/system", NewSystemRouter(container, settings.TrustedProxies))
+	r.Mount("/auth", NewAuthRouter(container, settings.IsProduction(), settings.AuthRateLimit, settings.TrustedProxies))
+
+	return r
+}
+
+func InitFrontendRoutes(environment string) *chi.Mux {
+	r := chi.NewRouter()
+
+	enableLoggingIfDev(r, "frontend", environment)
+
+	r.Mount("/", frontend.NewFrontendRouter())
+
+	return r
+}
+
+func GetHealth(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	_, _ = w.Write([]byte("ok"))
+}
+
+func enableCorsIfConfigured(r *chi.Mux, origins []string) {
+	if len(origins) == 0 {
+		return
+	}
+	r.Use(middleware.CORS(origins))
+}
+
+func InitRoutes(container *UseCases, settings config.Settings) *chi.Mux {
+	backend := InitBackendRoutes(container, settings)
+	frontend := InitFrontendRoutes(settings.Environment)
+
+	apiRouter := chi.NewRouter()
+	apiRouter.Use(middleware.SecurityHeaders(settings.IsProduction()))
+	enableCorsIfConfigured(apiRouter, settings.CorsAllowedOrigins)
+	apiRouter.Use(middleware.CrossOriginProtection(settings.PublicURL))
+	apiRouter.Use(chimiddleware.GetHead)
+	apiRouter.Get("/healthz", GetHealth)
+	llms.NewHandler(llmdocs.Docs, settings.Version, settings.PublicURL).Register(apiRouter)
+	apiRouter.Mount("/v1", backend)
+	apiRouter.Mount("/static/uploadedImages", staticimages.NewHandler(container.OpenMediaUseCase, container.ServeVariantUseCase))
+	apiRouter.Mount("/", frontend)
+
+	return apiRouter
+}

cmd/main.go

@@ -1,99 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"os"
-
-	"github.com/Floriansylvain/GohCMS/internal/api"
-	"github.com/Floriansylvain/GohCMS/internal/articles"
-	"github.com/gin-gonic/gin"
-	"github.com/joho/godotenv"
-)
-
-var (
-	ginMode      string
-	apiPort      string
-	apiBaseUrl   string
-	frontAddress string
-)
-
-func initEnvVariables() {
-	if godotenv.Load() != nil {
-		panic("Error loading .env file.")
-	}
-
-	ginMode = os.Getenv("APP_GIN_MODE")
-	apiPort = os.Getenv("APP_API_PORT")
-	apiBaseUrl = os.Getenv("APP_BASE_API_PATH")
-	frontAddress = os.Getenv("APP_FRONT_ADDRESS")
-}
-
-func initJWT() {
-	errInit := api.AuthMiddleware.MiddlewareInit()
-	if errInit != nil {
-		fmt.Printf(errInit.Error())
-	}
-}
-
-func initBasicRoutes(r *gin.RouterGroup) {
-	r.POST("/login/", api.AuthMiddleware.LoginHandler)
-	r.POST("/logout/", api.AuthMiddleware.LogoutHandler)
-	r.GET("/ping/", api.Ping)
-}
-
-func corsMiddleware(c *gin.Context) {
-	c.Writer.Header().Set("Access-Control-Allow-Origin", frontAddress)
-	c.Writer.Header().Set("Access-Control-Allow-Credentials", "true")
-	c.Writer.Header().Set("Access-Control-Allow-Headers", "Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization, accept, origin, Cache-Control, X-Requested-With")
-	c.Writer.Header().Set("Access-Control-Allow-Methods", "POST, OPTIONS, GET, PUT")
-	if c.Request.Method == "OPTIONS" {
-		c.AbortWithStatus(204)
-		return
-	}
-	c.Next()
-}
-
-func jwtProxyMiddleware(c *gin.Context) {
-	jwtToken, _ := c.Cookie("jwt")
-	c.Request.Header.Set("Authorization", fmt.Sprintf("Bearer %v", jwtToken))
-	c.Next()
-}
-
-func initArticlesRoutes(r *gin.RouterGroup) {
-	articlesRouter := r.Group("/articles")
-	articlesRouter.Use(corsMiddleware, api.AuthMiddleware.MiddlewareFunc())
-
-	articlesRouter.GET("/", articles.Get)
-	articlesRouter.GET("/:id", articles.GetUnique)
-	articlesRouter.POST("/:id", articles.Add)
-	articlesRouter.PUT("/:id", articles.Edit)
-	articlesRouter.DELETE("/:id", articles.Delete)
-}
-
-func initGin() {
-	r := gin.Default()
-	r.Use(jwtProxyMiddleware, corsMiddleware)
-
-	var router *gin.RouterGroup
-	if apiBaseUrl != "" {
-		router = r.Group(apiBaseUrl)
-	} else {
-		router = &r.RouterGroup
-	}
-
-	if ginMode == "release" {
-		gin.SetMode(ginMode)
-		api.AuthMiddleware.SecureCookie = true
-	}
-
-	initBasicRoutes(router)
-	initArticlesRoutes(router)
-
-	r.Run(":" + apiPort)
-}
-
-func main() {
-	initEnvVariables()
-	initGin()
-	initJWT()
-}

cmd/mcp/main.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"RenewCMS/internal/infrastructure/mcpserver"
+	"context"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+var version = "dev"
+
+func main() {
+	allowDestructive := flag.Bool("allow-destructive", false, "also expose delete_article and delete_media")
+	showVersion := flag.Bool("version", false, "print the version and exit")
+	flag.Parse()
+	if *showVersion {
+		fmt.Println(version)
+		return
+	}
+
+	baseURL := os.Getenv("RENEWCMS_URL")
+	apiKey := os.Getenv("RENEWCMS_API_KEY")
+	if baseURL == "" || apiKey == "" {
+		log.Fatal("RENEWCMS_URL and RENEWCMS_API_KEY must be set")
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	server := mcpserver.New(mcpserver.NewClient(baseURL, apiKey, nil), mcpserver.Options{
+		Version:          version,
+		AllowDestructive: *allowDestructive,
+	})
+	if err := server.Run(ctx, &mcp.StdioTransport{}); err != nil {
+		log.Fatal(err)
+	}
+}

cmd/releasesign/main.go

@@ -0,0 +1,10 @@
+package main
+
+import (
+	"RenewCMS/internal/infrastructure/update/releasesign"
+	"os"
+)
+
+func main() {
+	os.Exit(releasesign.Run(os.Args[1:], os.Stdout, os.Stderr))
+}

cmd/server/commands.go

@@ -0,0 +1,90 @@
+package main
+
+import (
+	"RenewCMS/api"
+	"RenewCMS/internal/domain/update"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+)
+
+const (
+	enableCommand  = "enable-browser-updates"
+	disableCommand = "disable-browser-updates"
+	applyCommand   = "apply-update"
+
+	exitOK    = 0
+	exitError = 1
+	exitUsage = 2
+
+	usageText = "usage: renewcms [--version]\n" +
+		"       renewcms enable-browser-updates [--service NAME] [--binary PATH] [--data-dir DIR] [--port PORT]\n" +
+		"       renewcms disable-browser-updates [--service NAME] [--data-dir DIR]\n" +
+		"       renewcms apply-update --binary PATH --data-dir DIR [--service NAME] [--port PORT]"
+
+	applyNeedsFlagsMessage = "apply-update needs --binary and --data-dir."
+)
+
+func runCommand(args []string, stdout io.Writer, stderr io.Writer) int {
+	name, rest := args[0], args[1:]
+	switch name {
+	case enableCommand:
+		return withOptions(name, rest, stderr, func(options update.InstallOptions) int {
+			message, err := api.InitBrowserUpdateCommands().Enable.Enable(options)
+			return printOutcome(stdout, stderr, message, err)
+		})
+	case disableCommand:
+		return withOptions(name, rest, stderr, func(options update.InstallOptions) int {
+			message, err := api.InitBrowserUpdateCommands().Disable.Disable(options)
+			return printOutcome(stdout, stderr, message, err)
+		})
+	case applyCommand:
+		return withOptions(name, rest, stderr, func(options update.InstallOptions) int {
+			return apply(options, stderr)
+		})
+	}
+	fmt.Fprintln(stderr, usageText)
+	return exitUsage
+}
+
+func withOptions(name string, args []string, stderr io.Writer, run func(update.InstallOptions) int) int {
+	flags := flag.NewFlagSet(name, flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	var options update.InstallOptions
+	flags.StringVar(&options.Service, "service", "", "systemd service name of RenewCMS")
+	flags.StringVar(&options.Binary, "binary", "", "path of the RenewCMS binary")
+	flags.StringVar(&options.DataDir, "data-dir", "", "directory that holds DB_FILE")
+	flags.StringVar(&options.Port, "port", "", "port RenewCMS listens on")
+	if err := flags.Parse(args); err != nil {
+		return exitUsage
+	}
+	return run(options)
+}
+
+func printOutcome(stdout io.Writer, stderr io.Writer, message string, err error) int {
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return exitError
+	}
+	fmt.Fprintln(stdout, message)
+	return exitOK
+}
+
+func apply(options update.InstallOptions, stderr io.Writer) int {
+	if options.Binary == "" || options.DataDir == "" {
+		fmt.Fprintln(stderr, applyNeedsFlagsMessage)
+		return exitUsage
+	}
+	if options.Service == "" {
+		options.Service = update.DefaultService
+	}
+	if options.Port == "" {
+		options.Port = update.DefaultPort
+	}
+	if err := api.InitApplyUpdateCommand(options).Apply(); err != nil {
+		log.Printf("apply-update failed: %v", err)
+		return exitError
+	}
+	return exitOK
+}

cmd/server/main.go

@@ -0,0 +1,202 @@
+package main
+
+import (
+	"RenewCMS/api"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/infrastructure/config"
+	"context"
+	"errors"
+	"fmt"
+	"io/fs"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/signal"
+	"slices"
+	"syscall"
+	"time"
+)
+
+var version = "dev"
+
+const (
+	readHeaderTimeout = 10 * time.Second
+	readTimeout       = 30 * time.Second
+	writeTimeout      = 60 * time.Second
+	idleTimeout       = 120 * time.Second
+	shutdownTimeout   = 10 * time.Second
+)
+
+var possibleEnvFileLocations = []string{".env", "../.env"}
+
+var requiredEnvVars = []string{
+	"PUBLIC_URL",
+	"JWT_SECRET",
+	"SMTP_LOGIN",
+	"SMTP_SENDER",
+	"SMTP_PASSWORD",
+	"SMTP_HOST",
+	"SMTP_PORT",
+}
+
+var envDefaults = map[string]string{
+	"ENVIRONMENT":                              "production",
+	"PORT":                                     "8080",
+	"DB_FILE":                                  "./data/renewcms.db",
+	config.EnvDatabaseDriver:                   config.DefaultDatabaseDriver,
+	"DB_TLS":                                   config.DefaultDatabaseTLS,
+	"DB_SSLMODE":                               config.DefaultDatabaseSSLMode,
+	"DB_MAX_OPEN_CONNS":                        config.DefaultMaxOpenConns,
+	"DB_MAX_IDLE_CONNS":                        config.DefaultMaxIdleConns,
+	"DB_CONN_MAX_LIFETIME_SECONDS":             config.DefaultConnMaxLifetimeSeconds,
+	"UPLOAD_DIR":                               "./data/uploads",
+	config.EnvStorageDriver:                    config.DefaultStorageDriver,
+	"S3_REGION":                                config.DefaultS3Region,
+	"S3_PATH_STYLE":                            config.DefaultS3PathStyle,
+	"S3_TLS":                                   config.DefaultS3TLS,
+	"AUTH_RATE_LIMIT_MAX_ATTEMPTS":             "5",
+	"AUTH_RATE_LIMIT_WINDOW_SECONDS":           "60",
+	"TRUSTED_PROXIES":                          "",
+	config.EnvSmtpAllowInsecure:                config.DefaultSmtpAllowInsecure,
+	"UPDATE_FEED_URL":                          "https://git.floriansylvain.fr",
+	"RENEWCMS_CONTAINER":                       "false",
+	config.EnvImageVariantMaxSourceBytes:       config.DefaultImageVariantMaxSourceBytes,
+	config.EnvImageVariantMaxSourcePixels:      config.DefaultImageVariantMaxSourcePixels,
+	config.EnvImageVariantMaxConcurrentRenders: config.DefaultImageVariantMaxConcurrentRenders,
+}
+
+const versionFlag = "--version"
+
+func main() {
+	if len(os.Args) == 2 && os.Args[1] == versionFlag {
+		fmt.Println(version)
+		return
+	}
+	if len(os.Args) > 1 {
+		os.Exit(runCommand(os.Args[1:], os.Stdout, os.Stderr))
+	}
+	if err := run(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run() error {
+	initEnvVariables()
+
+	settings, err := config.NewSettingsFromEnv()
+	if err != nil {
+		return err
+	}
+	settings.Version = version
+
+	container, closeDb := api.InitContainer(settings)
+	defer closeDatabase(closeDb)
+	validator.InitValidator()
+
+	server := newServer(api.InitRoutes(container, settings), settings)
+	return serveUntilStopped(server, settings, container.RecordRunningInfoUseCase.Record, container.RunSchedulers)
+}
+
+func initEnvVariables() {
+	loadEnvFile()
+	applyEnvDefaults()
+	ensureRequiredEnvVars()
+}
+
+func loadEnvFile() {
+	for _, envLocation := range possibleEnvFileLocations {
+		err := config.LoadDotenv(envLocation)
+		if err == nil {
+			return
+		}
+		if !errors.Is(err, fs.ErrNotExist) {
+			log.Println("WARNING: Could not parse env file:", err)
+		}
+	}
+	log.Println("WARNING: Could not load any .env file")
+}
+
+func applyEnvDefaults() {
+	for envVar, value := range envDefaults {
+		if _, isSet := os.LookupEnv(envVar); !isSet {
+			_ = os.Setenv(envVar, value)
+		}
+	}
+}
+
+func ensureRequiredEnvVars() {
+	required := slices.Concat(
+		requiredEnvVars,
+		config.DatabaseRequiredEnvVars(os.Getenv(config.EnvDatabaseDriver)),
+		config.StorageRequiredEnvVars(os.Getenv(config.EnvStorageDriver)),
+	)
+	if err := config.MissingEnvVarError(required, os.LookupEnv); err != nil {
+		panic(err.Error())
+	}
+}
+
+func closeDatabase(closeDb func() error) {
+	if err := closeDb(); err != nil {
+		log.Println("error closing database:", err)
+	}
+}
+
+func newServer(handler http.Handler, settings config.Settings) *http.Server {
+	return &http.Server{
+		Addr:              ":" + settings.Port,
+		Handler:           handler,
+		ReadHeaderTimeout: readHeaderTimeout,
+		ReadTimeout:       readTimeout,
+		WriteTimeout:      writeTimeout,
+		IdleTimeout:       idleTimeout,
+	}
+}
+
+func serveUntilStopped(server *http.Server, settings config.Settings, recordRunning func() error, runScheduler func(context.Context)) error {
+	stopSignal, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+
+	schedulerDone := make(chan struct{})
+	go func() {
+		defer close(schedulerDone)
+		runScheduler(stopSignal)
+	}()
+	defer func() {
+		stop()
+		<-schedulerDone
+	}()
+
+	serverErr := make(chan error, 1)
+	go listen(server, serverErr, settings, recordRunning)
+
+	select {
+	case err := <-serverErr:
+		return err
+	case <-stopSignal.Done():
+		return shutdown(server)
+	}
+}
+
+func listen(server *http.Server, serverErr chan<- error, settings config.Settings, recordRunning func() error) {
+	listener, err := net.Listen("tcp", server.Addr)
+	if err != nil {
+		serverErr <- err
+		return
+	}
+	if err := recordRunning(); err != nil {
+		log.Printf("WARNING: could not write the running-version file: %v", err)
+	}
+	log.Printf("RenewCMS %s (%s) listening on %s, public URL %s", version, settings.Environment, server.Addr, settings.PublicURL)
+	err = server.Serve(listener)
+	if errors.Is(err, http.ErrServerClosed) {
+		err = nil
+	}
+	serverErr <- err
+}
+
+func shutdown(server *http.Server) error {
+	log.Println("shutting down...")
+	ctx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
+	defer cancel()
+	return server.Shutdown(ctx)
+}

docker-compose.build.yml

@@ -0,0 +1,7 @@
+services:
+  renewcms:
+    build:
+      context: .
+      args:
+        VERSION: ${VERSION:-dev}
+    image: renewcms:${VERSION:-dev}

docker-compose.mysql.yml

@@ -0,0 +1,51 @@
+services:
+  mysql:
+    image: mysql:8.4
+    restart: unless-stopped
+    environment:
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?set MYSQL_ROOT_PASSWORD}
+      MYSQL_DATABASE: renewcms
+      MYSQL_USER: renewcms
+      MYSQL_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+    volumes:
+      - mysql-data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -u root -p\"$$MYSQL_ROOT_PASSWORD\" --silent"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  renewcms:
+    image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}
+    restart: unless-stopped
+    depends_on:
+      mysql:
+        condition: service_healthy
+    env_file:
+      - docker.env
+    environment:
+      DB_DRIVER: mysql
+      DB_HOST: mysql
+      DB_PORT: "3306"
+      DB_NAME: renewcms
+      DB_USER: renewcms
+      DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+      DATA_DIR: /data
+      UPLOAD_DIR: /data/uploads
+      RENEWCMS_CONTAINER: "true"
+    ports:
+      - "8080:8080"
+    volumes:
+      - renewcms-data:/data
+    stop_grace_period: 15s
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  renewcms-data:
+  mysql-data:

docker-compose.postgres.yml

@@ -0,0 +1,51 @@
+services:
+  postgres:
+    image: postgres:17
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: renewcms
+      POSTGRES_USER: renewcms
+      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U renewcms -d renewcms"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  renewcms:
+    image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    env_file:
+      - docker.env
+    environment:
+      DB_DRIVER: postgres
+      DB_HOST: postgres
+      DB_PORT: "5432"
+      DB_NAME: renewcms
+      DB_USER: renewcms
+      DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+      DB_SSLMODE: disable
+      DATA_DIR: /data
+      UPLOAD_DIR: /data/uploads
+      RENEWCMS_CONTAINER: "true"
+    ports:
+      - "8080:8080"
+    volumes:
+      - renewcms-data:/data
+    stop_grace_period: 15s
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  renewcms-data:
+  postgres-data:

docker-compose.s3.yml

@@ -0,0 +1,56 @@
+services:
+  seaweedfs:
+    image: ${SEAWEEDFS_IMAGE:-chrislusf/seaweedfs:4.48}
+    restart: unless-stopped
+    command: ["server", "-dir=/data", "-s3", "-s3.port=8333"]
+    environment:
+      AWS_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-renewcms}
+      AWS_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:?set S3_SECRET_ACCESS_KEY}
+    volumes:
+      - seaweedfs-data:/data
+
+  seaweedfs-init:
+    image: ${SEAWEEDFS_IMAGE:-chrislusf/seaweedfs:4.48}
+    restart: "no"
+    depends_on:
+      - seaweedfs
+    entrypoint: ["sh", "-c"]
+    command:
+      - |
+        until echo "s3.bucket.create -name renewcms-media" | timeout 30 weed shell -master=seaweedfs:9333 && echo "s3.bucket.list" | timeout 30 weed shell -master=seaweedfs:9333 | grep -q renewcms-media; do
+          sleep 2
+        done
+
+  renewcms:
+    image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}
+    restart: unless-stopped
+    depends_on:
+      seaweedfs-init:
+        condition: service_completed_successfully
+    env_file:
+      - docker.env
+    environment:
+      STORAGE_DRIVER: s3
+      S3_ENDPOINT: http://seaweedfs:8333
+      S3_BUCKET: renewcms-media
+      S3_REGION: us-east-1
+      S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-renewcms}
+      S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:?set S3_SECRET_ACCESS_KEY}
+      S3_PATH_STYLE: "true"
+      DB_FILE: /data/renewcms.db
+      RENEWCMS_CONTAINER: "true"
+    ports:
+      - "8080:8080"
+    volumes:
+      - renewcms-data:/data
+    stop_grace_period: 15s
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  renewcms-data:
+  seaweedfs-data:

docker-compose.yml

@@ -1,38 +1,24 @@
 services:
-  backend:
-    build:
-      context: ./
-      dockerfile: ./Dockerfile.backend
-    image: gohcms-backend
+  renewcms:
+    image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}
+    restart: unless-stopped
     env_file:
-      - .env
-    ports:
-      - "${APP_API_PORT}:${APP_API_PORT}"
-    networks:
-      - back-net
-  frontend:
-    build:
-      context: ./
-      dockerfile: ./Dockerfile.frontend
-    image: gohcms-frontend
-    env_file:
-      - .env
-    ports:
-      - "${APP_FRONT_PORT}:80"
-    networks:
-      - front-net
-  db:
-    image: mongo:6.0.2
-    # ports:
-    #   - "27017:27017"
+      - docker.env
     environment:
-      - MONGO_INITDB_DATABASE=gohcms
+      DB_FILE: /data/renewcms.db
+      UPLOAD_DIR: /data/uploads
+      RENEWCMS_CONTAINER: "true"
+    ports:
+      - "8080:8080"
     volumes:
-      - ./mongodbdata:/data/db
-      - ./mongo-init.js:/docker-entrypoint-initdb.d/mongo-init.js
-    networks:
-      - back-net
+      - renewcms-data:/data
+    stop_grace_period: 15s
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
 
-networks:
-  front-net:
-  back-net:
+volumes:
+  renewcms-data:

docker.env.example

@@ -0,0 +1,34 @@
+PUBLIC_URL=https://cms.example.com
+JWT_SECRET=replace-with-output-of-openssl-rand-hex-32
+SMTP_HOST=smtp.example.com
+SMTP_PORT=465
+SMTP_LOGIN=noreply@example.com
+SMTP_PASSWORD=replace-me
+SMTP_SENDER=noreply@example.com
+
+ENVIRONMENT=production
+CORS_ALLOWED_ORIGINS=
+AUTH_RATE_LIMIT_MAX_ATTEMPTS=5
+AUTH_RATE_LIMIT_WINDOW_SECONDS=60
+TRUSTED_PROXIES=
+DB_DRIVER=sqlite
+DATA_DIR=
+DB_HOST=
+DB_PORT=
+DB_USER=
+DB_PASSWORD=
+DB_NAME=
+DB_TLS=false
+DB_SSLMODE=disable
+DB_MAX_OPEN_CONNS=10
+DB_MAX_IDLE_CONNS=5
+DB_CONN_MAX_LIFETIME_SECONDS=300
+STORAGE_DRIVER=local
+S3_BUCKET=
+S3_REGION=us-east-1
+S3_ENDPOINT=
+S3_ACCESS_KEY_ID=
+S3_SECRET_ACCESS_KEY=
+S3_KEY_PREFIX=
+S3_PATH_STYLE=false
+S3_TLS=true

docs/api.md

@@ -0,0 +1,613 @@
+# API reference
+
+The full, searchable reference is the Integration page of the running app (`/integration`). It
+renders `web/src/data/apiCatalogue.ts`, which is the single source for this page. This file is for
+readers without the UI. Reading articles (pagination, `format`, body schemas) has its own page,
+[api/articles.md](api/articles.md), and API keys are covered in [api/api-keys.md](api/api-keys.md).
+
+## Base URL
+The origin that serves the app, for example `https://cms.example`. Every path starts with `/v1`,
+for example `https://cms.example/v1/article/`.
+
+## Authentication
+- Public routes need nothing: `GET /v1/article/`, `GET /v1/article/{id}`, `GET /v1/article/{id}/seo`
+  and `GET /v1/site/{key}/sitemap`. They return online articles, plus the drafts the caller's role may read
+  (see [Content permissions](#content-permissions)); any other draft answers 404 `Article not found`.
+- Everything else needs a signed-in browser session (the `jwt` cookie) or an API key:
+  `Authorization: Bearer rcms_...`. Create keys at `/integration/api-keys`. A key acts as its
+  creator, with that user's role, and shows in full once.
+- A key cannot call `POST /v1/auth/verify`, `DELETE /v1/auth/register`, `/v1/api-key/*` or
+  `/v1/system/*`. Those answer 403 "This action needs a real session." An invalid, unknown, expired
+  or revoked key answers 401, even on public routes. The site writes (`POST`, `PATCH` and `DELETE`
+  under `/v1/site`) and the author writes (`POST`, `PATCH` and `DELETE` under `/v1/author`, `POST /v1/author/me` included) are session only too.
+- Each key can make 120 requests per minute. Beyond that: 429 with a `Retry-After` header.
+- A session lasts 24 hours. `POST /v1/auth/logout` revokes it on the server, so a copied cookie
+  stops working at once; other sessions of the same user stay valid. A password reset ends every
+  session and revokes every key of that user.
+- A browser `POST`, `PUT`, `PATCH` or `DELETE` sent from another origin without an
+  `Authorization` header answers 403 "Cross-origin requests are not allowed." This blocks
+  cross-site request forgery with the cookie; scripts on other origins must send their key.
+
+## Routes a key can call (30)
+| Group | Routes |
+| --- | --- |
+| Articles | GET /v1/article/, GET /v1/article/{id}, GET /v1/article/{id}/seo, POST /v1/article/{id}/seo/check, POST /v1/article/, PATCH /v1/article/{id}, PATCH /v1/article/{id}/publish, PATCH /v1/article/{id}/unpublish, DELETE /v1/article/{id} |
+| Media | GET /v1/media/, GET /v1/media/{id}, POST /v1/media/, PATCH /v1/media/{id}, DELETE /v1/media/{id}, POST /v1/media/merge, GET /v1/media/{id}/usage, GET /v1/media/purge-settings (owner or admin), PATCH /v1/media/purge-settings (owner or admin), GET /v1/media/purge-preview (owner or admin), POST /v1/media/purge (owner or admin), GET /v1/media/{id}/variants (owner or admin, session only), POST /v1/media/{id}/variants (owner or admin, session only), POST /v1/media/{id}/variants/{name} (owner or admin, session only), DELETE /v1/media/{id}/variants/{name} (owner or admin, session only) |
+| Users and invites | GET /v1/user/ (`users.view`), PATCH /v1/user/me, GET /v1/user/me/export, DELETE /v1/user/me, POST /v1/user/invite (`users.invite`), DELETE /v1/user/invite/{id} (`users.invite`), POST /v1/user/invite/{id}/renew (`users.invite`), GET /v1/auth/me (with the linked `author`) |
+| Settings | GET /v1/settings |
+| Sites | GET /v1/site/, GET /v1/site/{key}/sitemap |
+| Authors | GET /v1/author/ |
+
+## Activity log
+The activity routes are session only: a key answers 403 "This action needs a real session." and a
+key never reads the audit trail. Events are append-only; there is no `POST`, `PUT`, `PATCH` or
+`DELETE` under `/v1/activity`.
+
+| Route | Who | Purpose |
+| --- | --- | --- |
+| `GET /v1/activity` | Any verified user | Filtered, paged events. A role with `activity.view` at all sees every event; a role at own is scoped to its own events, and `actor` set to someone else answers 403 `missing_permission`. |
+| `GET /v1/activity/summary` | Owner, admin | Counts for the range, the previous period, active people and seven-bucket series. |
+| `GET /v1/activity/export` | Owner, admin | The same filters as the list without `page` or `size`, as a `text/csv; charset=utf-8` attachment (`when,actor,action,target,outcome,source,ip`). Cells starting with `=`, `+`, `-` or `@` get a leading quote. |
+
+Query: `q`, `actor` (`user:ID`, `key:ID`, `system`), `category` (`articles`, `media`, `users`,
+`api_keys`, `auth`, `system`, `sites`, `authors`, `roles`), `outcome` (`all`, `success`, `failed`), `security` (`true`), `range`
+(`today`, `7d`, `30d`, `all`, `custom`; default `7d`), `from` and `to` (dates, with `custom`), `page` (from
+1) and `size` (25, 50 or 100). Any invalid value answers 400 with the body-mismatch message. Dates
+are UTC. The list answers `{ items, total, page, size }`, newest first (`created_at`, then `id`).
+
+`GET /v1/settings` also returns `activity_retention_days` (30, 90, 365 or 0 for forever, default
+90), `activity_retention_max_gb` (0 for no size limit), `activity_log_size_bytes`,
+`activity_last_cleanup_at` and `activity_last_cleanup_removed`. `PATCH /v1/settings` with
+`{"activity_retention_days": 30}`, `{"activity_retention_max_gb": 5}` or both is session only and
+needs `system.edit_retention` (403 `missing_permission`); any other value answers 400. The daily cleanup
+removes events past the age limit, then the oldest events until the log fits the size limit.
+Whichever limit is reached first wins.
+
+### What is recorded
+Every real action is recorded by its use case, once, after the change was made (outcome `success`)
+or after the use case refused it (outcome `failed`, with a plain `failure_reason`). Nothing is
+recorded for a read (no `GET`, no list, no public article read, no status poll), for a request that
+fails validation, or for a target that does not exist (404). A failed audit write is logged and
+never changes the response or the change itself.
+
+| Category | Actions |
+| --- | --- |
+| `articles` | `article.create`, `article.edit`, `article.publish`, `article.unpublish`, `article.delete` |
+| `media` | `media.upload`, `media.rename`, `media.delete`, `media.merge`, `media.purge`, `media.variant_create`, `media.variant_update`, `media.variant_delete`, `media.variant_enable`, `media.variant_disable`, `media.variant_purge`, `media.variant_generate_all`, `media.variant_purge_image`, `media.variant_purge_all`, `media.variant_purge_unused` |
+| `users` | `user.register`, `user.verify`, `user.update_profile`, `user.request_email_change`, `user.resend_email_change`, `user.cancel_email_change`, `user.confirm_email_change`, `user.export_data`, `user.delete_account` (flagged `security`), `user.change_role`, `user.remove`, `user.transfer_ownership` (flagged `security`), `invite.create`, `invite.cancel`, `invite.renew`, `invite.accept` |
+| `sites` | `site.create`, `site.edit`, `site.set_default`, `site.delete` |
+| `authors` | `author.create`, `author.edit`, `author.delete` |
+| `system` | `system.media_purge` (scheduled), `system.update_checked`, `system.update_downloaded`, `system.restart_requested`, `system.activity_cleanup`, `system.activity_retention_changed` |
+
+Target types: `article`, `site`, `author`, `image`, `image_variant` (id and name are the variant name), `user`, `invite`,
+`api_key` and `release` (id and name are the tag).
+Only the fields `title`, `online`, `body`, `site`, `name`, `base_url`, `default_robots`, `locale`, `default_social_image`, `slug`, `canonical_url`, `noindex`, `cover_image`, `social_image`, `excerpt`, `seo_title`, `seo_description`, `social_title`, `social_description`, `cover_image_alt`, `site_name`, `title_template`, `default_description`, `bio`, `website`, `social_links`, `avatar`, `user`, `authors`, `filename`, `display_name`, `width`, `height`, `fit`, `format` and `quality` appear in `changes` (a site key is never a change; moving an article records `site` with the site names; changing the credited authors records `authors` with the names in order; the `user` change of an author holds usernames, never an email), with the
+kinds `text` and `body`; a body edit carries a signed character count delta and never the text; the free-text SEO fields (`excerpt`, `seo_title`, `seo_description`, `social_title`, `social_description`, `cover_image_alt`) do the same under their own field name, while `slug`, `canonical_url`, `noindex`, `cover_image`, `social_image` (image file names) and the site fields `site_name`, `title_template`, `default_description` carry `before` and `after`. `seo_dismissed` is not an edit and records nothing. A
+change that leaves a value as it was (same body, same publish state, same file name, same display
+name) records nothing. Params: `media.merge` and `media.purge` and `system.media_purge` carry
+`merged` and `articles_updated`, plus `failed_groups` when a group failed (still outcome `success`);
+`media.variant_generate_all` carries `generated`, `failed` and `causes` (a list of `too_large`,
+`unsupported_format` or `failed`) and is `failed` only when nothing was generated and something failed;
+`media.variant_purge_image` carries `purged_files` and `purged_bytes`; both have an `image` target
+and are recorded only when files were generated or removed;
+`media.variant_purge_all` and `media.variant_purge_unused` (no target) carry `purged_files` and
+`purged_bytes`, the latter also `older_than_days`; a partial purge adds `failed_files` and stays
+`success`, and a purge that removed nothing while some files failed is `failed`; nothing is recorded
+when no file was removed or failed;
+`system.update_checked` carries `update_available`; `system.restart_requested` carries `kind` and,
+for an update, `tag` (it has no target). `system.update_downloaded` is recorded when the job reaches
+`ready` or `failed`, with the origin captured at request time; a refusal at the start is recorded
+immediately. A failed registration or invite acceptance has an `anonymous` actor named by the
+attempted username.
+
+`failure_reason` is one fixed sentence per domain error, matched with `errors.Is`, at most 255
+characters, for example "The title must be between 3 and 200 characters.", "That file name is not
+valid.", "The merge request is not valid.", "A purge is already running.", "Registration is closed
+on this site.", "That invitation has expired.", "The release feed could not be reached." or "The
+update could not be downloaded.". Any other error becomes "Something went wrong on our side. Please
+try again."; the text of the error never reaches the event, the API or the CSV. Passwords, hashes,
+codes, article bodies, file bytes, storage paths and asset urls are never recorded.
+
+Article routes accept `?format=markdown|html|json` (default `markdown`). `GET /v1/media/` accepts
+`q`, `hash`, `filter` (`all`, `unused` or `duplicates`), `sort` (`newest`, `oldest`, `name`,
+`largest` or `total_size`, the original plus its generated variants), `variants` (`with` or
+`without` generated variant files), `page` (a whole number from 1, default 1) and `size` (5, 25, 50
+or 100, default 25). The body is `{ "items": [...], "total", "page", "size", "counts" }`: `total` is
+the number of images matching `q`, `hash`, `filter` and `variants` before paging, `page` and `size`
+echo the values applied, and `counts` (`all`, `unused`, `duplicates`) stays library-wide, ignoring
+every filter and the paging. Ordering is applied to the whole matching list before slicing, with the
+image id as the final tie-break, so pages never overlap or skip. A page past the last answers 200
+with `items: []` and the real `total`. Any invalid `page`, `size`, `filter`, `sort`, `variants` or
+`hash` is 400 "The media query is invalid.". Every item carries `variant_count` and `variant_size`
+(the index rows of the image and their bytes, 0 when none).
+
+`GET /v1/media/{id}` reads one image with the same auth as the list (a verified session or an API key; 403 for an
+unverified account, 401 without credentials) and writes nothing, so it records no activity event. It answers 200 with
+the object of one `items` element of the list, a missing image is 404 "Image not found" and a malformed id is 400 with
+the id-format message.
+
+Breaking change: `next_cursor` is gone and no `X-Total-Count` header is sent. `cursor` and `limit`
+are no longer parameters; they are ignored, never an error, and have no effect on paging.
+
+## Sites
+Every article belongs to exactly one site, and exactly one site is the default. A site is `{ id,
+name, key, base_url, default_social_image_id, default_robots, locale, is_default, article_count }`:
+`name` is 1 to 100 characters, `key` is 2 to 32 characters of lowercase letters, digits and single
+dashes (`^[a-z0-9]+(-[a-z0-9]+)*$`) and never changes, `base_url` is `https` (or `http` for
+`localhost`, `127.0.0.1` and `[::1]`) with no path, query or user info (a trailing slash is
+stripped, uniqueness is not enforced), `default_robots` is `index` (default) or `noindex`, `locale`
+is `null` or a tag such as `en` or `fr-CA` (an empty string means none) and `default_social_image_id`
+is `null` or the id of an image. Read access needs a verified session or an API key; every write is
+session only and need `settings.manage_sites` (`settings.delete_site` for DELETE): 403 `missing_permission`, or "This action needs a real
+session." with a key. The role is checked before the body.
+
+| Route | Purpose |
+| --- | --- |
+| `GET /v1/site/` | The sites, default first and then by name, each with `article_count`. Query `q` (up to 200 characters, matched in `name`, `key` or `base_url`, ignoring case and accents, `%` and `_` literal), `page` (a whole number from 1) and `size` (5, 25, 50 or 100). Without `page` and `size` every matching site is returned; with only `page`, `size` is 25; with only `size`, `page` is 1. The body stays a JSON array (`[]` when nothing matches, never `null`) and `X-Total-Count` holds the number of matching sites before paging. A page past the end is `200 []` with the total. An invalid `page`, `size` or `q` is 400 with the body-mismatch message and no `X-Total-Count`. |
+| `POST /v1/site/` | Create. 201 with the site. `is_default: true` makes it the default. `site_name`, `title_template` and `default_description` are optional and validated like on `PATCH`. |
+| `PATCH /v1/site/{id}` | Edit `name`, `base_url`, `default_robots`, `locale`, `default_social_image_id`, `site_name`, `title_template`, `default_description`. Absent fields are untouched. `key` may only be repeated unchanged; `is_default` is refused. |
+| `PATCH /v1/site/{id}/default` | Make the site the default, atomically. Setting the current default is a no-op. |
+| `DELETE /v1/site/{id}?reassign_to={id}` | 204. A site with articles needs `reassign_to`; the articles move and the site is deleted in one transaction. `reassign_to` is ignored when the site has no article. |
+
+Errors are plain text whose body is exactly the token: 409 `site_key_taken`, 409 `site_has_articles`,
+403 `default_site` (checked before the articles), 400 `key_immutable`, 400 `invalid_site_url`, 400
+`invalid_locale`, 400 `invalid_title_template`, 400 `image_not_found`, 400 `use_set_default`, 400 `invalid_reassign` (missing
+number, the site itself or not a whole number) and 404 `site_not_found`. Refused writes except `site_not_found` and `image_not_found` are recorded as failed events. A body that cannot be
+decoded is 400 with the body-mismatch message, a malformed id is 400 with the uint32 message, and a
+field that fails validation (`name`, `key` format, `default_robots`, `site_name` over 100 characters, `title_template` over 200, `default_description` over 320) is 400 with the validator text.
+
+A site also carries `site_name` (at most 100 characters, `""` by default), `title_template` (at most 200 characters, `%title% | %site%` by default; it must contain `%title%`, case sensitive, otherwise 400 `invalid_title_template`, an empty template included) and `default_description` (at most 320 characters, `""` by default). They appear on every site response, `POST` accepts them and `PATCH` edits them like the other site fields. Existing sites get the defaults when the server starts after the upgrade.
+
+Articles carry `site_id`. A new article starts on the default site. `GET /v1/article/?site=<key>`
+keeps only the articles of that site and composes with `status`, `q`, `sort`, `size` and `page`;
+`counts` stay global, an unknown key answers 200 with no item and an empty `site=` is 400 with the
+body-mismatch message. `PATCH /v1/article/{id}` takes `body`, `site_id`, `author_ids` and the SEO
+fields below, and nothing else, such as `title`: absent fields are untouched, an empty object, an object without
+those fields, a `null` value (except on `cover_image_id` and `social_image_id`) or a malformed value is 400 with the body-mismatch message, `site_id: 0` is
+400 with the validator text and an unknown site is 404 `site_not_found`. Moving an article never
+changes `is_online`. `{"body": ""}` still sets an empty body, but `{}` and `{"body": null}` no longer do: they are 400.
+
+### Resolved SEO, check, list status and sitemap
+
+RenewCMS renders no page and injects no meta tag: it returns the data a frontend needs.
+
+| Route | Who | Purpose |
+| --- | --- | --- |
+| `GET /v1/article/{id}/seo` | public for online articles; a verified session or API key also reads the drafts its role may read | The resolved object `{ title, description, canonical_url, robots, og, twitter, image, authors, published_at, modified_at, fallbacks, json_ld }`. It never carries the body, the id or `seo_dismissed`, ignores `format`, and writes nothing. An offline article for any other caller, and a missing one, is 404 `Article not found`. |
+| `POST /v1/article/{id}/seo/check` | verified session or API key (401 without credentials, 403 unverified) | Evaluates the article without saving. The body is `{}` or any of the twelve SEO fields of `PATCH` plus `body`; each replaces the saved value for this check only. `site_id`, `author_ids`, unknown fields and `null` (except on `cover_image_id` and `social_image_id`) are 400 with the body-mismatch message. The other validation is the one of `PATCH` (`invalid_slug`, `invalid_url` as 422, `image_not_found`, validator text). Answers `{ status, suggestions, slug }` where `suggestions` is `[{ code, field, params }]` and `slug` is `{ available, suggestion }`. A taken slug is a 200 with `available: false` and the first free `<slug>-N` in `suggestion`, never a 409. |
+| `GET /v1/site/{key}/sitemap` | public | A JSON array `[{ url, modified_at, noindex }]` of the online articles of the site with that key, by id ascending. `url` is `base_url/slug` (never the canonical override). `page` (default 1) and `size` (25, 50, 100 or 500, default 100); an invalid value is 400 with the body-mismatch message. The total is in the `X-Total-Count` header. An unknown key, an id included, is 404 `site_not_found`. |
+
+`GET /v1/article/` also takes `seo=ready|suggestions|hidden` (any other value, an empty one included, is 400 with the body-mismatch message, after the `format` check). It is applied before paging and composes with `q`, `status`, `site`, `sort`, `page` and `size`; `total` follows it and `counts` ignore it. Every item carries `seo_status` (`ready`, `suggestions` or `hidden`) and `seo_suggestions` (the number of suggestions that are not dismissed). The filter is evaluated in memory over every matching article, so its cost grows with the number of articles on the site; without it only the returned page is assessed.
+
+`X-Total-Count` is added to `Access-Control-Expose-Headers` next to `Link`, so a browser on an allowed origin can read it.
+
+### Article SEO fields
+
+An article carries twelve search and sharing fields, all edited through `PATCH /v1/article/{id}` and returned by
+every single-article read (`GET /v1/article/{id}`, `POST`, `PATCH`, `publish`, `unpublish`):
+`slug`, `excerpt`, `seo_title`, `seo_description`, `cover_image_id`, `cover_image_alt`, `social_title`,
+`social_description`, `social_image_id`, `canonical_url`, `noindex` and `seo_dismissed`. Text fields are `""`
+when empty, the two image ids are `null` when unset, `noindex` is `false` and `seo_dismissed` is `[]` by
+default. Each item of `GET /v1/article/` carries `excerpt` and `slug` and none of the other ten.
+The limits are counted in characters: `excerpt` 300, `seo_title` 120, `seo_description` 320,
+`cover_image_alt` 200, `social_title` 120, `social_description` 320, `canonical_url` 2048; going over is
+400 with the validator text. `cover_image_id` and `social_image_id` accept `null` (and only those two do);
+`0` is 400 with the validator text and an unknown image is 400 `image_not_found`. `canonical_url` is `""` or an absolute
+`https` URL with a host, otherwise 422 `invalid_url`. `seo_dismissed` is a list of the codes `title_long`,
+`title_empty`, `desc_short`, `desc_long`, `cover_alt`, `cover_none`, `slug_long`, `no_au`, `no_h`, `body_alt`
+and `short`: an unknown code is 400 with the validator text and duplicates are collapsed with the order
+kept. `noindex` is only a flag, it does not take the article offline.
+
+The `slug` matches `^[a-z0-9]+(-[a-z0-9]+)*$` with 1 to 100 characters (400 `invalid_slug`) and is unique per
+site, never globally. It is generated from the title when the article is created: lowercase, accents folded,
+every run of other characters becomes one dash, dashes trimmed, cut to 100 characters, and `article` when no
+letter or digit is left; a slug already used on the site gets `-2`, `-3`... silently. The same rule
+backfills the existing articles when the server starts after the upgrade (in id order within each site, so
+the oldest article keeps the plain slug). Sending `slug: ""` regenerates the slug from the title. A slug
+used by another article on the target site (the new site when `site_id` is sent too, and a move re-checks
+the current slug) is 409 with the plain-text body `slug_taken`; the response then carries the header
+`X-Slug-Suggestion` holding the first free `<slug>-N` from 2 on that site, fitting 100 characters. The header
+is set on this 409 only, never on another response. A regeneration that collides is refused the same way, never suffixed
+silently. Saving an article with its own slug is not a collision. Publishing never changes a slug, a deleted article
+frees its slug.
+
+New error tokens are plain text from the handler: 409 `slug_taken`, 400 `invalid_slug`, 422 `invalid_url`, 400
+`image_not_found` and 400 `invalid_title_template` (sites). Edits that change a SEO field are recorded as
+`article.edit` events (`slug`, `canonical_url`, `noindex`, `cover_image`, `social_image` with before and after;
+the free-text fields as a size delta only); a refused slug is recorded as failed.
+
+A site's `default_social_image_id` counts as a use of that image: it raises `used_in` and keeps the
+image out of the `unused` filter. Deleting the image sets the field to `null` and succeeds. `POST /v1/media/merge` and `POST
+/v1/media/purge` repoint the sites of the merged copies to the kept image and report it as
+`sites_updated` next to `articles_updated`.
+
+An article's `cover_image_id` and `social_image_id` count the same way. `used_in` counts every article that uses the
+image in its body, as cover or as social image once, plus the authors using it as an avatar and the sites using it as default
+social image. Deleting an image never fails because of its uses: the covers and social images pointing at it are set to `null`
+(the `cover_image_alt` and the bodies are untouched), and a failed delete leaves every reference in place. A merge or a purge repoints
+the covers and social images of the copies to the kept image, and an article rewritten in its body and its cover counts once in
+`articles_updated`.
+
+`GET /v1/media/{id}/usage` stays an array. Every item keeps the keys it had and gains `type` (`article`,
+`author` or `site`) and `fields`. An article item is `{ "type": "article", "id", "title", "published", "fields" }` with
+`fields` from `body`, `cover` and `social` (one item per article, in that order); an author item is
+`{ "type": "author", "id", "title": <name>, "fields": ["avatar"] }` and a site item is `{ "type": "site", "id", "title": <name>,
+"fields": ["default_social_image"] }`; author and site items have no `published` key. The array is `[]` for an unused image.
+
+## Authors
+
+An author is a public byline, with or without an account. It is `{ id, name, slug, bio, avatar_id,
+website, social_links, user_id, is_linked, article_count }`, plus `user_email` for owners and admins
+only (absent for every other caller). `name` is 1 to 100 characters after trimming, `slug` matches
+`^[a-z0-9]+(-[a-z0-9]+)*$` with 1 to 100 characters and is unique (generated from the name when
+omitted: accents folded, punctuation runs become one dash, `author` when nothing is left), `bio` has
+at most 280 characters (counted in runes), `avatar_id` is `null` or an image id, `website` is `null`
+or an `https` URL with a host (an empty string means none, at most 2048 characters),
+`social_links` holds at most 5 `{ "type", "url" }` with `type` one of `x`, `linkedin`, `github`,
+`mastodon`, `custom` and an `https` URL. `user_id` is the unique link to a user. Zero authors on an
+article is allowed and never blocks publishing.
+
+| Route | Who | Purpose |
+| --- | --- | --- |
+| `GET /v1/author/` | verified session or API key | The authors newest first. Query `q` (name or slug, accent and case insensitive), `page` (default 1), `size` (5, 25, 50 or 100, default 25). Body `{ items, total, page, size }`, with `total` repeated in the `X-Total-Count` header on every 200; a bad query is 400 with the body-mismatch message and no header. |
+| `POST /v1/author/` | owner or admin, session only | Create. 201 with the author. `user_id` links an account that has no author. |
+| `POST /v1/author/me` | any verified session | Create the caller's own author from the display name (or the username). A taken slug gets `-2`, `-3`... silently. 201 with the author plus `slug_adjusted`: `true` when the stored slug differs from the plain slug of the name (a collision suffix was added), `false` otherwise. No other author response carries this field. |
+| `PATCH /v1/author/{id}` | owner or admin on any author; any verified session on the author linked to it; session only | Edit `name`, `slug`, `bio`, `avatar_id`, `website`, `social_links`, `user_id`. Absent fields are untouched, `avatar_id`, `website` and `user_id` accept `null`, `social_links` is replaced as a whole. `user_id` links or unlinks the account and is owner or admin only. |
+| `DELETE /v1/author/{id}?reassign_to={id\|none}` | owner or admin, session only | 204. An author credited on articles needs `reassign_to`: an author id (that author takes the deleted one's position and is never duplicated on an article) or `none` (the credit is removed). The move and the delete are one transaction. `reassign_to` is ignored when the author has no article. The linked account is untouched. |
+
+The role checks use the existing bodies: 403 `missing_permission` for `POST /` and
+`DELETE`, 403 `author_rights` for a `PATCH` by a role that holds `authors.edit` at own on an author
+that is not its own (or that sends `user_id`), and 403 "This action needs a real session." for a key.
+Errors are plain text whose body is exactly the token: 404 `author_not_found`, 404 `user_not_found`,
+409 `author_slug_taken`, 409 `author_has_articles`, 409 `user_already_linked`, 409
+`author_already_linked`, 400 `invalid_slug`, 400 `invalid_reassign` (own id, not a whole number,
+negative or empty), 400 `image_not_found`, 422 `bio_too_long`, 422 `invalid_url` and 422
+`too_many_links`. A body that cannot be decoded, an empty `PATCH` or one that nulls a required field
+is 400 with the body-mismatch message, a malformed id is 400 with the uint32 message and other
+validation failures (`name`, link `type`) are 400 with the validator text. Writes refused for a
+reason other than a missing target or an invalid value are recorded as failed events.
+
+Articles carry `authors`, the ordered credits (the first is the primary byline), each with only `id`,
+`name`, `slug`, `bio`, `avatar_id`, `website` and `social_links`; it is `[]` when there is none and it
+is visible on online articles to anonymous readers. `PATCH /v1/article/{id}` also takes
+`author_ids`, the whole ordered list: it replaces the credits, `[]` empties them, an unknown id is 404
+`author_not_found`, a duplicate, `null` or a malformed list is 400 with the body-mismatch message and
+`0` is 400 with the validator text. Absent means unchanged. A new article is credited to the
+creator's linked author when there is one. `GET /v1/auth/me` returns the existing user fields plus
+`author`: the caller's linked author (`id`, `name`, `slug`, `bio`, `avatar_id`, `website`,
+`social_links`, `article_count`) or `null`.
+
+An author's `avatar_id` counts as a use of that image like a site's social image: it raises `used_in`
+and keeps the image out of the `unused` filter, and `GET /v1/media/{id}/usage` lists the author with the field `avatar`.
+Deleting the image sets `avatar_id` to `null`. `POST /v1/media/merge` and `POST /v1/media/purge`
+repoint the avatars of the merged copies and report it as `authors_updated`.
+
+## Image variants
+Owners and admins manage named variants of the stored images. These routes are session only (no API
+key) and sit behind the verified-user check; a role without the needed permission gets 403 `missing_permission`. Behaviour, caching and the public `?v=<name>` contract are in [image-variants.md](image-variants.md).
+
+| Route | Purpose |
+| --- | --- |
+| `GET /v1/image-variants` | `{ "items": [...] }`, ordered by name. |
+| `POST /v1/image-variants` | Create. 201 with the variant. 409 when the name exists. |
+| `PUT /v1/image-variants/{name}` | Replace the definition (the name in the body is ignored). 200 with the variant and `purged_files`. |
+| `PATCH /v1/image-variants/{name}` | `{ "enabled": true }` or `{ "enabled": false }`. Keeps the generated files. |
+| `DELETE /v1/image-variants/{name}` | 204. Removes the definition and its generated files. |
+| `POST /v1/image-variants/{name}/purge` | `{ "purged_files", "purged_bytes" }`. Keeps the definition. |
+| `GET /v1/image-variants/cache` | Cache statistics, see below. |
+| `POST /v1/image-variants/cache/purge` | Purge generated files by scope, see below. |
+
+A variant is `{ name, width, height, fit, format, quality, generate_on_upload, enabled,
+generated_files, cache_size, created_at, updated_at }`. `width` and `height` are 1 to 8000 or `null`
+(at least one is required), `fit` is `cover`, `contain` or `inside` (default `cover`), `format` is
+`original`, `jpeg`, `png` or `webp` (default `original`), `quality` is 1 to 100 (default 82, `null`
+for `png`), `generate_on_upload` defaults to `false`, `enabled` to `true`, and `cache_size` is in
+bytes. A `PUT` that omits `generate_on_upload` or `enabled` keeps the stored value.
+
+Errors are plain text: 400 for a body that is not valid JSON, 404 "Variant not found", 409 "A variant
+named “thumb” already exists. Choose another name." and 422 with one sentence for the first invalid
+field (name, width and height, fit, format, quality).
+
+### Cache statistics and purge by scope
+
+`GET /v1/image-variants/cache` answers `{ generated_files, disk_used, variants_defined,
+variants_enabled, variants_disabled, rejected_requests, rejected_window_days, unused: { files, bytes,
+days }, by_variant: [{ name, enabled, files, bytes }], top_images: [{ id, filename, url, files, bytes }] }`.
+`by_variant` lists every defined variant by bytes descending then name; `top_images` lists the ten
+images using the most variant bytes (ties by id, images that no longer exist are skipped). `unused`
+counts the files of enabled variants whose reference time (the last public request, or the creation
+time when never requested) is older than 30 days. `rejected_requests` counts the public requests
+refused with 400 over today and the six previous UTC days. Pending request tracking is flushed before
+the read. Arrays are never `null`.
+
+`POST /v1/image-variants/cache/purge` takes `{ "scope": "all" | "unused" | "variant" | "image",
+"variant": "<name>", "image_id": <id> }` (`variant` for the scope `variant`, `image_id` for `image`; a
+target given for another scope is ignored) and answers `{ scope, purged_files, purged_bytes,
+failed_files }`. A purge that fails on some files still answers 200 with `failed_files` above 0; the
+failed rows are kept so the same request can be sent again. Errors are plain text: 400 for a body that
+is not valid JSON, 422 "Scope must be all, unused, variant or image." or "A variant name or an image
+id is required for this scope.", 404 "Variant not found" or "Image not found", 500 when the rows
+cannot be listed.
+
+### Variants of one image
+Owners and admins only, session only: a request with an API key is 401. All ids are image ids.
+
+| Route | Purpose |
+| --- | --- |
+| `GET /v1/media/{id}/variants` | `{ "unsupported": null, "items": [...] }` for the enabled variants in name order. `unsupported` is `"svg"` (with `items: []`) for an SVG. |
+| `POST /v1/media/{id}/variants` | Generates every enabled variant that is missing. `{ "generated", "failed", "failures": [{ "name", "cause" }], "items": [...] }`, 200 even when some fail. |
+| `POST /v1/media/{id}/variants/{name}` | Generates one enabled variant. 200 with the item. |
+| `DELETE /v1/media/{id}/variants/{name}` | Removes the generated file. `{ "purged_files", "purged_bytes" }`, also for a disabled variant. |
+
+An item is `{ name, width, height, fit, format, output_width, output_height, output_format,
+generated, size, url }`: `width` and `height` are the settings (`null` when auto), `output_*` the
+size and format the file has or will have (never above the source), `generated` is true only when
+the file exists with the variant's current settings, `size` is its bytes or `null`, and `url` is
+`/static/uploadedImages/<stored name>?v=<name>`. A `cause` is `too_large`, `unsupported_format` or
+`failed`. A file generated here is the same file the public url serves, and the other way round.
+Uploads generate the variants flagged `generate_on_upload` (enabled ones, raster sources only)
+before answering; a failure there is logged and never fails the upload.
+
+Errors are plain text: 400 for a malformed id, 404 "Image not found" or "Variant not found" (also for a
+disabled variant on `POST`), 413 "The source image is too large to generate this variant.", 415 "The
+source image can't be read, so this variant can't be generated.", 422 "Variants aren't generated for
+this format." and 500 "Internal server error".
+
+## Roles
+
+Routes under `/v1/role`, behind the verified chain. Reads accept a key; every write is session only (a key answers
+403 "This action needs a real session."). The permission is checked before the id, the body and any lookup.
+
+| Route | Permission | Purpose |
+| --- | --- | --- |
+| `GET /v1/role` | `roles.view` | Every role by id, built-ins first. |
+| `GET /v1/role/{id}` | `roles.view` | One role. |
+| `POST /v1/role` | `roles.manage` | Create a role (201). `built_in` and `locked` in the body are ignored. |
+| `PUT /v1/role/{id}` | `roles.manage` | Replace name, description and grants. `version` is required and must match. |
+| `DELETE /v1/role/{id}` | `roles.manage` | Delete a role with no members (204). |
+| `POST /v1/role/{id}/reassign` | `roles.manage` | Move every member to `{"target_role_id": N}`; answers `{"moved": n}`. |
+| `POST /v1/role/{id}/reset` | `roles.manage` and `roles.edit_owner_only` | Restore a built-in role to its seeded grants and description; body `{"version": N}`. |
+
+A role is `{ id, name, description, built_in, locked, version, grants, members, updated_at, updated_by }`.
+`grants` is the normalised effective list: catalogue order, unknown keys and owner-only keys on an unlocked role
+dropped, duplicates resolved to the most restrictive scope, and a per-type entry (`content.update:events`, scope
+`none` included) right after its wildcard. A response is always valid as the `grants` of a `PUT`. `members` counts
+the users holding the role plus the open invites (pending or expired, never accepted ones) for it, counted in two
+statements whatever the number of roles. A user whose `role_id` is 0 or names no role counts for nobody.
+`updated_at` (RFC 3339, UTC) and `updated_by` (`{ id, name }`, the display name else the username) are `null` for a role
+never edited since seeding, and `updated_by` is also `null` once the saving user is deleted.
+
+Refusals are plain text, one snake_case code per body:
+
+| Status | Body | When |
+| --- | --- | --- |
+| 400 | `unknown_permission`, `invalid_scope`, `owner_only_permission`, `duplicate_permission`, `unknown_content_type` | A grant is not valid (`unknown_content_type` for a `content.*:{type}` key that is neither `article` nor a content type). |
+| 409 | `target_role_not_found` | `POST /v1/role/{id}/reassign` when the target role does not exist (any longer). |
+| 400 | `invalid_role_name`, `built_in_name`, `not_built_in`, `invalid_reassign` | Blank name after trim; renaming a built-in role; resetting a custom role; a bad reassign target (self, 0, a locked role, a role the caller cannot cover). |
+| 403 | `role_locked` | Editing, deleting or moving from the Owner role. |
+| 403 | `missing_permission` | The usual gate, plus `X-Missing-Permission: roles.edit_owner_only` when a built-in role is edited or reset without that permission. |
+| 403 | `own_role` | Editing, deleting or moving members out of the caller's own role. |
+| 403 | `escalation` | The caller would grant, or touch a role holding, more than they hold. `X-Escalation-Key` names the first offending key, such as `content.publish` or `content.publish:events`. |
+| 404 | `role_not_found` | Unknown role id. |
+| 409 | `role_name_taken`, `role_conflict`, `role_has_members`, `role_built_in` | Name already used (case-insensitive); stale `version`; the role still has members (users or open invites); deleting or moving members out of a built-in role. |
+
+Names are trimmed and unique case-insensitively. The order of checks on a write is: permission, id, body, role lookup,
+locked, built-in rules, own role, existing role covered by the caller, version, grant validation, new grants covered
+by the caller, name taken, write. Only the Owner holds `roles.edit_owner_only`, so only the Owner edits the Admin and
+Writer roles; owner-only keys are refused on every role a client can write. A save with nothing changed answers 200
+at the same version and records nothing. Members see an edit on their next request, and so do the keys they created.
+
+Activity: `role.create`, `role.edit`, `role.delete` and `role.reassign` in the `roles` category, target
+`{ type: "role", id, name }`. `role.edit` carries `name` and `description` changes and the params `added`, `removed`,
+`changed` (`{ key, from, to }`) and `members`; `role.reassign` carries `from`, `to`, `to_name` (the destination role's name at move time; absent on older events) and `moved` (users and open invites together) and is recorded only when
+`moved` is above 0. A refusal records nothing.
+
+`GET /v1/auth/me` lists per-type entries in `access.permissions` (scope `none` included), right after their wildcard.
+Deleting a content type removes its per-type rows from every role (the affected roles' `version` goes up by one), and
+creating one with the key of a deleted type clears any stale row for that key.
+
+## Changing the email address
+
+Four session-only routes under `/v1/auth` let a verified user change their own email address. A missing or invalid
+cookie is 401, an API key is 403 `This action needs a real session.` and an unverified user is 403
+`You must verify your account to access this resource.`
+
+| Route | Body | Success |
+| --- | --- | --- |
+| `POST /v1/auth/email/change` | `{ "new_email": "...", "current_password": "..." }` | 200 `{ "pending_email": "<new>" }` |
+| `POST /v1/auth/email/resend` | none | 200 `{ "pending_email": "<new>" }` |
+| `DELETE /v1/auth/email/change` | none | 204, no body |
+| `POST /v1/auth/email/confirm` | `{ "code": "<raw code>" }` | 200 `{ "email": "<new>" }` |
+
+`users.email` does not change until the link is confirmed, so the old address keeps receiving password-reset links and
+the password and username keep working. A request stores `pending_email`, a bcrypt hash of a random code and an
+expiration two hours ahead, then mails the raw code as a link to the new address (`verify-new-email`) and a notice to
+the old one (`email-change-notice`). A new request or a resend replaces the previous code; cancelling clears it. The
+link works once.
+
+Errors are plain text and the code is the whole body: 400 `same_email` (the new address equals the current one,
+whatever its case), 403 `wrong_password`, 404 `no_pending_email_change` (resend only), 403
+`invalid_email_change_code` (nothing pending, wrong, expired, cancelled or issued to another user) and 409
+`email_unavailable` (the address belongs to another user at confirmation time; the pending change is cleared). A body
+that is not JSON is 400 with the body-mismatch message, and a failed validation is 400 with the validator text
+(`new_email` must be a full address, `current_password` and `code` are required).
+
+A request for an address that another user already holds answers exactly like a success, stores the pending change and
+still sends the notice to the old address, but sends no verification mail, so the response never reveals that an account
+exists. A failed send is logged without the code and does not change the response. `POST /v1/auth/email/change` and
+`POST /v1/auth/email/resend` share one limit of 5 attempts per user per 15 minutes; the sixth is 429 with a
+`Retry-After` header. Cancel and confirm are not limited.
+
+Audit actions (category `users`, source `web`): `user.request_email_change`, `user.resend_email_change` and
+`user.confirm_email_change` are flagged `security`; `user.cancel_email_change` is not, and cancelling with nothing
+pending records nothing. A refused request, resend or confirm records a failed event of the same action, flagged `security`, with a specific reason. No email address is written into an event, and a wrong password records a failed
+`user.request_email_change` with the reason `Wrong password.`
+
+## Exporting your own data
+
+`GET /v1/user/me/export` answers a ZIP of the caller's personal data. It needs a real, verified session: no cookie is 401,
+an API key is 403 "This action needs a real session." and an unverified account is 403. There is no body and no permission
+gate, since it only reads the caller's own data. The success answer is 200 with `Content-Type: application/zip`,
+`Cache-Control: no-store` and `Content-Disposition: attachment; filename="renewcms-export-<username>-<YYYY-MM-DD>.zip"`;
+the username is lowercased and reduced to `a-z`, `0-9` and `-`, and the date is the UTC day of the export. The archive is
+built in memory first, so a failure is a plain text 500 and never a half file.
+
+| File | Content |
+| --- | --- |
+| `profile.json` | `id`, `username`, `display_name`, `email`, `pending_email`, `role {id, name}`, `is_verified`, `created_at`, `updated_at`, `author` (the linked author profile or `null`), `api_keys [{id, name, prefix, created_at, last_used_at, revoked_at}]` |
+| `authored-content.json` | `articles [{id, title, body, slug, site_id, is_online, created_at, updated_at, authors}]` created by the caller (drafts included) or published and crediting their author profile, with `authors [{id, name, slug}]`, and `entries [{id, content_type, data, created_at, updated_at}]` created by the caller; soft-deleted articles are left out |
+| `uploaded-media.json` | `images [{id, filename, mime, size, hash, uploaded_at}]`: references only, no file bytes; soft-deleted images are left out |
+| `account-activity.json` | `events [{id, created_at, action, category, target, outcome, security, source, ip, user_agent, params}]` where the caller is the actor, without events whose target is another user, an invite or another person's author profile |
+
+The archive never holds the password hash, a verification, reset or email-change code, the token version or an API-key
+hash. One export succeeds per user every 15 minutes; a second attempt is 429 "Too many requests. Please try again later."
+with a `Retry-After` header in seconds. An export that fails with a 500 does not use the slot. A successful export records
+one `user.export_data` audit event (category `users`, not flagged `security`).
+
+The archive is built in memory. At most 2 exports are built at the same time across all users (the constant
+`maxConcurrentDataExports` in `api/dependecyInjection.go`); another request waits for a free slot. If the request is
+cancelled or times out while waiting, the answer is 503 "Service unavailable" and the user's 15-minute slot is not used.
+
+## Deleting your own account
+
+`DELETE /v1/user/me` deletes the caller's account and personal data. It needs a real, verified session: no cookie is 401,
+an API key is 403 "This action needs a real session." and an unverified account is 403. It is not `DELETE /v1/user/{id}`,
+which stays the admin action and is unchanged.
+
+Body: `{"current_password": "...", "confirmation": "DELETE"}`. The password is required, and `confirmation` must be exactly
+`DELETE` (case-sensitive, no spaces). The checks run in this order:
+
+| Answer | Body | When |
+| --- | --- | --- |
+| 400 | the validator message, or "The request cannot be processed due to a mismatch in the format of the body." | the body is not JSON, the password is empty or `confirmation` is not `DELETE` |
+| 403 | `wrong_password` | the password is not the account's |
+| 409 | `last_admin`, with the header `X-Last-Role: Owner` or `X-Last-Role: Admin` | the caller holds the built-in Owner role and no other verified user does, or the built-in Admin role and no other verified user holds Owner or Admin. Other roles, custom ones included, are never blocked. |
+| 409 | `account_not_deletable` | the holders of the role changed between the check and the removal; nothing was removed |
+| 429 | "Too many requests. Please try again later." with `Retry-After` | more than 5 attempts per user in 15 minutes, counted before any check |
+| 500 | "Internal server error" | the removal failed; everything is rolled back |
+| 204 | none, and a `Set-Cookie` that expires `jwt` | the account is deleted |
+
+The removal is one atomic operation: the user row, all the user's API keys, the linked author (deleted when no article
+credits it, otherwise kept as "Deleted user" with the slug `deleted-user-<author id>`, no bio, avatar, website or links and
+no user; the avatar image is deleted too, with its stored file after the commit, unless something else uses it), and the user's past activity events (actor and target names become "Deleted user", the IP address, user agent, `params` and `changes` are emptied, and author events on the user's own profile lose the profile name; the events stay). Articles, entries and images keep the old user id. The current session is revoked, and
+one `account-deleted` mail (the site address only, no personal data) is sent to the address the account had; a failed send
+is logged and does not change the 204. A successful deletion records one `user.delete_account` event (category `users`,
+flagged `security`, actor and target named "Deleted user", no email in the params); a refused attempt records a failed
+`user.delete_account` event with the reason `Wrong password.`, `Last Owner.` or `Last administrator.`.
+
+## Users, invites and ownership
+
+A user has exactly one stored role, `role_id`, and nothing else: there is no `role` string any more (the
+`users.role` column of older databases stays in place, unused). `RoleRef` is the one role summary shape,
+`{ id, name, built_in, locked }`. It appears as `access.role` in `GET /v1/auth/me`, as `role` on user and invite items
+(`null` for a user whose role cannot be resolved) and in the responses below. `PublicUser` is exactly `id`, `username`,
+`email`, `is_verified`, `created_at`, `updated_at` and `display_name` in every response that includes a user (login,
+verify, register, invite accept, `GET /v1/auth/me`); `GET /v1/auth/me` adds `pending_email` (string or `null`), `author` and `access`.
+
+`role_assigned_by` is `{ id, name }` or `null`: who last set the user's role. It is stored as the nullable column
+`role_assigned_by_id` on the user (no foreign key, no backfill, existing rows are `NULL`) and the name is never stored: it
+is read from the current record of that user at read time (`display_name` when set, else `username`), so a rename shows
+at once. When that record is gone the whole object is `null`. It is set by `PUT /v1/user/{id}/role` to the caller (a
+request with the user's current role writes nothing), by invite accept to the inviter (`NULL` when the inviter record is
+missing), and by the ownership transfer: the new Owner is assigned by the former Owner, whose own value becomes `NULL`.
+First-user registration and `POST /v1/role/{id}/reassign` leave it alone. The key is always present on accepted-user
+items of `GET /v1/user` (gate `users.view`, unchanged; assigners are resolved from the users already loaded) and on
+`access` of `GET /v1/auth/me` (own data, one extra lookup at most). Invite items never carry it, and `PublicUser` and the
+login, verify, register and invite-accept bodies do not change.
+
+| Route | Permission | Session only | Purpose |
+| --- | --- | --- | --- |
+| `GET /v1/user` | `users.view` | no | Users and open invites, newest first. A user is `{ id, kind: "user", username, display_name, email, role, role_assigned_by, status: "accepted", created_at }`; an invite is `{ id, kind: "invite", email, role, status, created_at }`. The roles are read with one `List` call. |
+| `PUT /v1/user/{id}/role` | `users.change_role` | yes | Body `{"role_id": N}` (required). Answers 200 with the user item, whose `role_assigned_by` is the caller. |
+| `DELETE /v1/user/{id}?expected_role_id=N` | `users.remove` | yes | Removes an accepted user (204, no body). `expected_role_id` is required (a whole number above 0, else 400 `invalid_role`) and must be the id of the role the target still holds: a compare-and-swap (`DeleteIfRole`), 409 `user_role_changed` otherwise. Order of checks: session, permission, id, `expected_role_id`, target (404 `user_not_found`), target is the caller (403 `own_role`), stale role (409), target role locked (403 `role_locked`), target role covered (403 `escalation`), delete. The removed user's cookie sessions and API keys answer 401 afterwards; articles, entries, media, invites and audit events they created stay. Records `user.remove` (category `users`, target the user); a refusal records nothing and a storage failure records it with outcome `failed`. Invites are cancelled with `DELETE /v1/user/invite/{id}`. |
+| `POST /v1/user/invite` | `users.invite` | no | Body `{"email", "role_id"}`; `role_id` is optional and 0 or absent means the Writer role. Answers 201 `{ id, kind: "invite", email, status, role, created_at, expires_at }`. |
+| `POST /v1/user/invite/{id}/renew` | `users.invite` | no | Renews an expired or pending invite; it keeps its role and the response carries it. |
+| `DELETE /v1/user/invite/{id}` | `users.invite` | no | Cancels an invite (204). No coverage is needed: cancelling removes power. |
+| `POST /v1/site/transfer-ownership` | `system.transfer_ownership` | yes | Body `{"user_id", "confirm_email"}` (both required). Answers 200 `{ "owner": { id, name }, "former_owner": { id, name, role } }`. |
+
+The no-escalation rule applies to people as it does to roles: the caller must cover (`GrantSet.Covers`) the target's
+current role and the new role on a role change, the role of an invite on create and renew. An API key may create and
+renew invites, and the check then uses the live role of the key's creator. Nobody can give, take away or invite to the
+Owner role: `PUT /v1/user/{id}/role` to or from it, and an invite for it, are 403 `role_locked`; only the transfer moves
+the Owner role. Changing the role of your own account is 403 `own_role`. Giving the role a user already holds answers
+200 and writes and records nothing. A role change keeps `token_version`, sessions and keys: the next request is decided
+by the new grants. An unverified user may be given a role.
+
+The order of checks on `PUT /v1/user/{id}/role` is: session, permission, id, body, target user, target holds a locked
+role, `role_id` lookup, new role locked, own account, current role covered, new role covered, same role (no-op), write.
+On `POST /v1/user/invite`: permission, rate limiter, body, inviter, role (default Writer), role locked, role covered,
+email already has an account, pending invite, create, mail. On `POST /v1/user/invite/{id}/renew`: invite lookup (404),
+already accepted (409), invite role covered, renew, mail. On `POST /v1/site/transfer-ownership`: session, permission,
+body, target, `confirm_email`, write. Every refusal writes nothing, not even the deletion of an expired invite.
+
+| Status | Body | When |
+| --- | --- | --- |
+| 409 | the human message | `POST /v1/user/invite` only. "This address already has an account." carries `X-Error-Code: email_has_account`; "There's already a pending invite for this address." carries `X-Error-Code: invite_pending`. |
+| 400 | `invalid_role` | `role_id` names no role (user change or invite), or the invite's role no longer exists on renew. |
+| 400 | `invalid_transfer` | The transfer target is unknown, yourself, unverified, or not a user (an invite id is never valid). |
+| 400 | `confirmation_mismatch` | `confirm_email` differs from the target's email (exact, case-sensitive match). |
+| 403 | `role_locked` | The target holds the Owner role, or the role to give is the Owner role. |
+| 403 | `own_role` | The target of a role change is the caller's own account. |
+| 403 | `escalation` | A role to cover is above the caller's grants; `X-Escalation-Key` names the first offending key. |
+| 403 | `missing_permission` | The gate, with `X-Missing-Permission`. A key on a session-only route answers 403 "This action needs a real session." first. |
+| 404 | `user_not_found` | Unknown user id on `PUT /v1/user/{id}/role`. |
+| 409 | `user_role_changed` | `DELETE /v1/user/{id}` as well: the target's role changed between read and write (a compare-and-swap on the role that was read), or the caller no longer holds the Owner role on a transfer. |
+
+Transferring ownership moves the Owner role to the target and gives the former owner the built-in Admin role in one
+transaction; both keep `token_version`, cookies and API keys, so the former owner's next request is decided by the
+Admin grants and the new owner's by the Owner grants. Exactly one verified user holds the Owner role afterwards, also
+under two simultaneous transfers (one answers 200, the other 409).
+
+Accepting an invite (`POST /v1/auth/invite/accept`) creates the user with the role the invite names, read at accept
+time; an invite whose `role_id` is 0 or names a deleted role answers the usual invalid-invite 404 and creates nothing.
+Registration creates the first user with the built-in Owner role; when the Owner role is not seeded it answers 500.
+A user whose `role_id` is 0 or names no role is denied on every gated route (403 `missing_permission`) and gets 500 on
+`GET /v1/auth/me`; it is never promoted.
+
+Activity: `user.change_role` (category `users`, target the user, `changes` holds `{ field: "role", kind: "text", before,
+after }` with the role names, params `from` and `to` hold the role ids) and `user.transfer_ownership` (category `users`,
+`security: true`, target the new owner, params `from` and `to` hold the two user ids). `invite.create` and
+`invite.accept` carry the params `role_id` and `role` (the role name); `invite.renew` is unchanged. A refusal and a
+no-op record nothing; a storage failure at the write records the same event with outcome `failed`.
+
+## Content permissions
+
+Articles and the entries of custom content types are checked against the `content.*` permissions of the
+caller's role, which is read on every request (a key follows its creator's role).
+
+| Route | Permission | Scope check after the lookup |
+| --- | --- | --- |
+| `GET /v1/article/`, `GET /v1/article/{id}`, `GET /v1/article/{id}/seo` | public, `content.read` widens what drafts show | online articles, plus drafts when `content.read` is `all`, or the caller's own drafts when it is `own` |
+| `POST /v1/article/{id}/seo/check` | `content.read` | the article must be visible, else 404 |
+| `POST /v1/article/` | `content.create` | none; `created_by` is the caller and the article is always a draft |
+| `PATCH /v1/article/{id}` | `content.update` | `own` needs `created_by` to be the caller |
+| `DELETE /v1/article/{id}` | `content.delete` | same |
+| `PATCH /v1/article/{id}/publish`, `/unpublish` | `content.publish` | same; `PATCH` never changes `is_online` |
+| `GET /v1/content-type/{key}/entry`, `GET .../entry/{id}` | `content.read` for `{key}` | `own` lists only the caller's entries (total, page, size and `q` follow) and answers 404 `entry_not_found` for another's entry |
+| `POST /v1/content-type/{key}/entry` | `content.create` for `{key}` | `created_by` is the caller |
+| `PUT`, `DELETE .../entry/{id}` | `content.update`, `content.delete` for `{key}` | `own` needs `created_by` to be the caller |
+
+Each action reads its own permission: publish does not imply update, update does not imply read. `own`
+means `created_by` equals the caller; an unattributed item (`created_by` 0) is owned by nobody. A permission
+can also be set for one content type (`content.update:blog`, `content.update:article` for articles); that
+row replaces the wildcard for the type, whether it lowers or raises it, and a `none` row denies. Only the
+wildcard applies to a type with no row. An id that does not exist is 404 even for a caller at `own`. Article responses expose `created_by` to signed-in callers and API keys only (never to anonymous callers), so a client can tell which rows are its own; see `docs/api/articles.md`.
+
+A refusal is 403 `missing_permission` with `X-Missing-Permission` set to the base key (`content.update`,
+never `content.update:blog`). The permission is checked before the id and the body are read, then the scope
+after the lookup, and a refused call writes nothing and records no activity event. The verification and
+token checks still come first. Creating a content type whose key is `article`, `author`, `site`, `media`
+or `user` is 409 `content_type_key_taken`. Owner-only permissions only count on the locked Owner role: the
+same key placed by hand on another role is ignored and `GET /v1/auth/me` does not list it.
+
+## Errors
+Every error is a plain-text body with one sentence; the status is in the HTTP status line. The
+statuses are 400, 401, 403, 404, 409, 429 and 500. Messages are listed on the Integration page.
+
+A caller whose role lacks the permission a route needs gets 403 with the body `missing_permission` and the
+header `X-Missing-Permission` set to the permission key (for example `users.invite`). The role is read on
+every request, so an API key follows the current role of its creator.
+
+## Notes
+- Images in `body` use paths like `/static/uploadedImages/<uuid>.png`. Prefix them with the base URL.
+- Browsers can call the API only from origins in the server's CORS setting.

docs/api/api-keys.md

@@ -0,0 +1,23 @@
+# API keys
+
+Developers can authenticate against `/v1` with a named API key sent as `Authorization: Bearer rcms_...` instead of the `jwt` cookie. A key acts with exactly the rights of the user who created it.
+
+## Managing keys
+
+Key management needs a real session (the `jwt` cookie from a verified user).
+
+- `POST /v1/api-key` with `{"name": "ci", "expires_at": "<RFC3339, optional>"}` answers `201` with `id`, `name`, `prefix`, `key`, `created_at`, `expires_at`. The full `key` is shown once and never again.
+- `GET /v1/api-key` lists the caller's keys (all keys for the owner), newest first, with a `status` of `active`, `expired` or `revoked`.
+- `DELETE /v1/api-key/{id}` revokes a key and answers `204`. Revoking twice keeps the first `revoked_at`.
+
+Only the SHA-256 hash and a 12 character prefix are stored.
+
+## Where a key is accepted
+
+`/v1/article` (public and protected routes), `/v1/user`, `/v1/media`, `/v1/settings` and `GET /v1/auth/me`. An invalid, expired or revoked `rcms_` key answers `401` and is never treated as anonymous. Each key is limited to 120 requests per minute (`429` with `Retry-After`). `last_used_at` is updated at most once per minute.
+
+## Session-only routes
+
+`/v1/api-key`, `POST /v1/auth/verify`, `DELETE /v1/auth/register` and every `/v1/system` route answer `403 This action needs a real session.` to any `rcms_` Bearer header. The public auth routes ignore the header.
+
+A successful password reset revokes every key of that user.

docs/api/articles.md

@@ -0,0 +1,221 @@
+# Reading articles
+
+Every route that returns an article accepts the optional `format` query parameter and returns the article body in that format. Articles are stored as HTML (Tiptap output). Storage and the request bodies of `POST /v1/article/` and `PATCH /v1/article/{id}` stay HTML.
+
+`PATCH /v1/article/{id}` takes `body`, `site_id`, `author_ids` (the whole ordered list of author ids, see `docs/api.md`) and the SEO fields listed below, and nothing else. The request must contain at least one of them, and `null` answers `400` except for `cover_image_id` and `social_image_id`. Behaviour change: `{}` and `{"body": null}` used to set an empty body and now answer `400`; send `{"body": ""}` to empty a body.
+
+## Routes that honour `format`
+
+- `GET /v1/article/`
+- `GET /v1/article/{id}`
+- `POST /v1/article/`
+- `PATCH /v1/article/{id}`
+- `PATCH /v1/article/{id}/publish`
+- `PATCH /v1/article/{id}/unpublish`
+
+Anonymous and unverified callers only see online articles, and an offline article answers `404 Article not found`. A verified caller also sees the drafts that `content.read` covers: every draft at `all`, only their own at `own`, and none without the permission. The `all`, `online` and `draft` counts follow the same visible set.
+
+## Pagination, search and counts
+
+`GET /v1/article/` always answers one page inside an envelope, with or without query parameters:
+
+```json
+{
+  "items": [],
+  "total": 30,
+  "page": 1,
+  "size": 25,
+  "counts": { "all": 30, "online": 30, "draft": 0, "suggestions": 4 }
+}
+```
+
+| Parameter | Values | Default |
+| --- | --- | --- |
+| `page` | integer >= 1 | `1` |
+| `size` | `5`, `25`, `50` or `100` | `25` |
+| `q` | up to 200 characters, matched anywhere in the title, ignoring case and accents | none |
+| `status` | `online` or `draft` | none |
+| `site` | the `key` of a site; an unknown key gives an empty page, an empty value is `400` | none |
+| `seo` | `ready`, `suggestions` or `hidden`; any other value, an empty one included, is `400` | none |
+| `sort` | `title`, `status`, `created_at` or `updated_at`, then `:asc` or `:desc` (lowercase, for example `title:asc`) | `updated_at:desc` |
+
+- `items` is `[]` when empty, never `null`. Each item is the article object below.
+- Items follow `sort` (default `updated_at:desc`) across the whole list before paging. `title` ignores case, `status` orders on online state (`status:asc` puts drafts first), and every ordering ends with `id` descending so pages never overlap.
+- `total` is the number of visible articles matching `q` and `status`, before paging. `page` and `size` echo the values applied.
+- `counts` ignores `q`, `status`, `site`, `seo`, `sort`, `page` and `size`, so tab counts do not move while searching. `suggestions` is the number of visible articles whose `seo_status` is `suggestions` (hidden and ready articles and dismissed codes are not counted); it equals the `total` of `?seo=suggestions` sent with no other filter by the same caller. For anonymous and unverified callers `all` equals `online` and `draft` is `0`, and `status=draft` answers `items: []` and `total: 0`.
+- Each item also carries `seo_status` and `seo_suggestions` (see [SEO status and suggestions](#seo-status-and-suggestions)). `seo` filters on the status before paging, so `total` follows it while `counts` do not.
+- A page beyond the last answers `200` with `items: []` and the real `total`.
+- An invalid `page`, `size`, `status`, `sort` or an over-long `q` answers `400` with the plain-text message `The request cannot be processed due to a mismatch in the format of the body.` An invalid `format` is reported first.
+
+Breaking change: this route used to answer a bare JSON array. Clients must read the `items` property.
+
+## The `format` parameter
+
+| Value | `body` | `body_format` |
+| --- | --- | --- |
+| empty or absent | markdown string | `markdown` |
+| `markdown` | markdown string | `markdown` |
+| `html` | the stored HTML string | `html` |
+| `json` | JSON array of blocks | `json` |
+
+Values are case-insensitive. When `format` is repeated, the first value is used. Any other value answers `400` with the plain-text message `The format must be one of: markdown, html, json.` before any article is read or written. An invalid id is reported first, ahead of the format.
+
+Breaking change: the default used to be HTML. Clients that need HTML must send `?format=html`. The web interface does so.
+
+## Article object
+
+```json
+{
+  "id": 1,
+  "title": "Backyard Renovation Update",
+  "body": "## Plan\n\nReplace the **old** deck.",
+  "body_format": "markdown",
+  "is_online": true,
+  "site_id": 1,
+  "created_by": 1,
+  "authors": [],
+  "slug": "backyard-renovation-update",
+  "excerpt": "",
+  "seo_title": "",
+  "seo_description": "",
+  "cover_image_id": null,
+  "cover_image_alt": "",
+  "social_title": "",
+  "social_description": "",
+  "social_image_id": null,
+  "canonical_url": "",
+  "noindex": false,
+  "seo_dismissed": [],
+  "created_at": "2026-03-12T09:14:00Z",
+  "updated_at": "2026-09-10T07:00:00Z"
+}
+```
+
+`created_by` is the id of the user who created the article (`0` when it is attributed to nobody). It is present on every article object (list, read, create and update responses) only when the caller is signed in with a verified session or authenticates with an API key; the key acts as its creator. Anonymous callers, and unverified or stale sessions, get the same object without the field. The SPA reads it to decide which rows a role limited to `own` can edit, delete or publish.
+
+Every single-article read (`GET /v1/article/{id}`, `POST`, `PATCH`, `publish`, `unpublish`) carries the twelve SEO fields. Each item of `GET /v1/article/` carries `slug` and `excerpt` only, and none of the other ten.
+
+## SEO fields
+
+| Field | Type | Limit and rule |
+| --- | --- | --- |
+| `slug` | string | `^[a-z0-9]+(-[a-z0-9]+)*$`, 1 to 100 characters, unique per site. `""` regenerates it from the title. |
+| `excerpt` | string | 300 characters |
+| `seo_title` | string | 120 characters |
+| `seo_description` | string | 320 characters |
+| `cover_image_id` | number or `null` | an existing image id (`0` is refused) |
+| `cover_image_alt` | string | 200 characters, independent of the cover |
+| `social_title` | string | 120 characters |
+| `social_description` | string | 320 characters |
+| `social_image_id` | number or `null` | an existing image id (`0` is refused) |
+| `canonical_url` | string | `""` or an absolute `https` URL with a host, at most 2048 characters |
+| `noindex` | boolean | only a flag: the article stays online |
+| `seo_dismissed` | array of strings | any of `title_long`, `title_empty`, `desc_short`, `desc_long`, `cover_alt`, `cover_none`, `slug_long`, `no_au`, `no_h`, `body_alt`, `short`; duplicates are collapsed, order kept |
+
+Limits are counted in characters (runes), not bytes. Absent fields are untouched; text fields and `noindex` are cleared with `""`, `false` and `[]`, the two image ids with `null`.
+
+### The slug
+
+A slug is unique per site (`site_id`, `slug`), never globally. At creation it is generated from the title: lowercase, accents folded, every run of other characters becomes one dash, dashes trimmed, cut to 100 characters without a trailing dash, and `article` when no letter or digit is left. A slug already used on the site gets `-2`, `-3`... silently, the base being truncated so the result fits 100 characters. The same rule backfills existing articles on the first start after the upgrade, in id order within each site.
+
+Editing a slug that another article of the target site already uses (the new site when `site_id` is sent in the same request; moving an article also re-checks its current slug there) answers `409` with the plain-text body `slug_taken`, and the response header `X-Slug-Suggestion` holds the first free `<slug>-N` from 2 on that site, fitting 100 characters. `X-Slug-Suggestion` is set on this `409` only and on no other response. A request with `slug: ""` that regenerates onto another article's slug is refused the same way and never suffixed silently. Re-sending an article's own slug is not a conflict. A refused request changes nothing.
+
+Publishing, unpublishing and `noindex` never change a slug. A deleted article frees its slug.
+
+## Resolved SEO object
+
+`GET /v1/article/{id}/seo` answers the data a frontend renders in its `<head>`. Online articles are public; a draft needs a verified session or API key whose role may read it (see [Content permissions](../api.md#content-permissions)) and is otherwise `404 Article not found`. The query is ignored (no `format`). Keys:
+
+`title`, `description`, `canonical_url`, `robots`, `og` (`type`, `title`, `description`, `image`, `image_alt`, `url`, `site_name`, `locale`), `twitter` (`card`, `title`, `description`, `image`, `image_alt`), `image` (`url`, `alt`, `source`), `authors` (`name`, `url`, `same_as`), `published_at`, `modified_at`, `fallbacks` and `json_ld` (a ready schema.org `Article`).
+
+The fallback chain, first non-empty wins:
+
+| Output | Chain | `fallbacks` value |
+| --- | --- | --- |
+| `title` | `seo_title`, then the article title, then the site `title_template` (`%title%`, `%site%` replaced by `site_name`, result trimmed) | `seo_title`, `title` |
+| `description` | `seo_description`, `excerpt`, the first sentence of the body (tags removed), the site `default_description` | `seo_description`, `excerpt`, `body`, `site`, `none` |
+| `image` | `social_image_id`, `cover_image_id` (with `cover_image_alt`), the site `default_social_image_id`; `url` is the site `base_url` plus the image path, `""` and `none` when there is none | `social`, `cover`, `site`, `none` |
+| `canonical_url` | `canonical_url`, then site `base_url` + `/` + `slug` | `canonical_url`, `site` |
+| `robots` | `noindex, nofollow` when `noindex` is true, otherwise from the site `default_robots` (`index, follow` or `noindex, nofollow`) | none |
+| `og` and `twitter` title and description | `social_title` and `social_description`, then the resolved values | none |
+
+`og.type` is `article`, `og.locale` is the site locale (`""` when none), `twitter.card` is `summary_large_image` with an image and `summary` without. `published_at` is the creation time of an online article and `null` for a draft; `modified_at` is `updated_at`. `authors[].url` is the author website (`""` when none) and `same_as` lists the social link URLs only. `json_ld.headline` is the meta title without the site template, and `author`, `image` and `datePublished` are left out when empty.
+
+## SEO status and suggestions
+
+`POST /v1/article/{id}/seo/check` and the list use one rule set. Soft ranges never block saving or publishing; lengths are counted in characters.
+
+| Code | Field | Fires when | `params` |
+| --- | --- | --- | --- |
+| `title_long` | `seo_title` | the meta title (`seo_title`, else the title) is over 60 characters | `length`, `max` |
+| `title_empty` | `seo_title` | the meta title is empty after trimming | none |
+| `desc_short` | `seo_description` | the resolved description is under 70 characters | `length`, `min` |
+| `desc_long` | `seo_description` | the resolved description is over 160 characters | `length`, `max` |
+| `cover_alt` | `cover_image_alt` | there is a cover and its alt text is empty | none |
+| `cover_none` | `cover_image_id` | there is no cover | none |
+| `slug_long` | `slug` | the slug is over 75 characters | `length`, `max` |
+| `no_au` | `author_ids` | no author is credited | none |
+| `no_h` | `body` | the text has at least 1000 characters and no `h2` to `h6` | none |
+| `body_alt` | `body` | an image of the body has no alt text | `count` |
+| `short` | `body` | the text has fewer than 300 characters | `length`, `min` |
+
+Suggestions come in that order. Codes in `seo_dismissed` are never reported or counted. The status is `hidden` when `noindex` is true, else `suggestions` when at least one suggestion remains, else `ready`. The list items carry `seo_status` and `seo_suggestions` (the count, also for a hidden article).
+
+## Markdown output
+
+Headings, bold, italic, links, bullet and ordered lists, blockquotes, fenced code blocks, rules, images and inline code are converted. Anything else is reduced to its text. `script` and `style` content is removed, and the source HTML is never passed through; the only HTML in the output is the alignment wrapper described below. List indentation attributes are dropped. Links with a scheme other than http, https, mailto or tel are reduced to their text. Characters that markdown would read as formatting (`*`, `_`, `` ` ``, `[`, `]`, `<`, `\`) and line starts that would read as a heading, list, quote or rule (`#`, `-`, `+`, `>`, `1.`) are backslash-escaped, so plain text stays plain text. A line break becomes a backslash followed by a newline.
+
+### Text alignment
+
+Markdown has no syntax for alignment, so centered, right-aligned and justified paragraphs and headings are wrapped in a `div` with an inline style. The blank lines around the content make CommonMark parse the inside as markdown:
+
+```markdown
+<div style="text-align: center">
+
+A **centered** paragraph
+
+</div>
+```
+
+Left alignment is the default and produces no wrapper. Your markdown renderer must allow raw HTML for the alignment to show (`html: true` in markdown-it); otherwise the wrapper tags appear as text, and a client that does not want them can request `?format=json` instead, where the alignment is a field.
+
+## JSON block schema
+
+`body` is a native JSON array. Every block has a `type`.
+
+| Block | Fields |
+| --- | --- |
+| `heading` | `level` (1 to 6), `align` (only when `center`, `right` or `justify`), `children` (text nodes) |
+| `paragraph` | `align` (only when `center`, `right` or `justify`), `children` (text nodes, empty array for an empty paragraph) |
+| `list` | `ordered` (boolean), `items` (array of items, each an array of blocks) |
+| `blockquote` | `children` (blocks) |
+| `code` | `language` (empty string when unknown), `text` |
+| `hr` | none |
+| `image` | `src`, `alt` (empty string when missing) |
+
+Text node: `{"type":"text","text":"...","marks":[...]}`. `marks` is always an array, listed outermost first. A mark is `{"type":"bold"}`, `{"type":"italic"}` or `{"type":"link","href":"..."}`. A line break becomes a `"\n"` inside the text. Adjacent text with identical marks is merged. Inline code, underline, strike-through and other formatting degrade to plain text. An image inside a paragraph becomes its own block and splits the paragraph. An empty body is `[]`.
+
+Example for `<h2>Plan</h2><p>Replace the <strong>old</strong> deck.</p>`:
+
+```json
+[
+  {"type":"heading","level":2,"children":[{"type":"text","text":"Plan","marks":[]}]},
+  {"type":"paragraph","children":[
+    {"type":"text","text":"Replace the ","marks":[]},
+    {"type":"text","text":"old","marks":[{"type":"bold"}]},
+    {"type":"text","text":" deck.","marks":[]}
+  ]}
+]
+```
+
+## Errors
+
+| Status | Body |
+| --- | --- |
+| `400` | `The server expects the ID to be in the format of an unsigned 32-bit integer (uint32).` for an invalid id |
+| `400` | `The format must be one of: markdown, html, json.` for an unsupported format |
+| `400` | `invalid_slug`, `image_not_found` or the validator text for an over-long SEO field, `cover_image_id: 0` or an unknown `seo_dismissed` code |
+| `404` | `Article not found` |
+| `409` | `slug_taken`, with the header `X-Slug-Suggestion: <first free slug>` (this response only) |
+| `422` | `invalid_url` for a `canonical_url` that is not an absolute `https` URL with a host |
+| `500` | `Internal server error` when the body cannot be converted |

docs/architecture.md

@@ -0,0 +1,173 @@
+# Architecture
+
+RenewCMS is a Go HTTP API and a Vue 3 SPA, shipped as a single binary.
+
+## Backend layering
+
+Dependencies point inward:
+
+```
+api/  ──▶  internal/infrastructure/useCases  ──▶  internal/domain  ◀──  internal/infrastructure/{persistence,mailer}
+```
+
+| Layer | Location | Rules |
+|---|---|---|
+| Domain | `internal/domain/<name>/` | Entities, `Err…` sentinel errors, `Repository` interfaces. Imports only the stdlib and other domain packages, with no GORM tags. |
+| Use cases | `internal/infrastructure/useCases/` | Application logic. Depends only on domain interfaces, never on persistence, mailer, GORM or `net/http`. |
+| Adapters | `internal/infrastructure/persistence/{models,mappers,repositories}`, `internal/infrastructure/mailer` | Implement a domain `Repository` (assert with `var _ domain.Repository = &X{}`). GORM structs stay in `models` and are converted by `mappers`. |
+| Database drivers | `internal/infrastructure/persistence/database` | `database.Connect(Config{Driver, Source})` looks the driver up in a registry and returns a `Connection` (GORM handle, `NewBackup`, `Close`). A `Driver` implements `Open` and `NewBackup`, so a new database is one new file plus one registry entry. `database.Migrate` owns the `AutoMigrate` model list and the role backfills (legacy `users.role` into `role_id` while that column exists, invites without a role to Admin, then `created_by`). Only `sqlite` exists today. |
+| Blob storage | `domain/image.Storage`, `internal/infrastructure/storage` | `Storage` (`Put`, `Open`, `Delete`) is the port for uploaded image bytes. `storage.Open(Config{Driver, Location})` picks the adapter; `local` is the only one. Repositories never touch files: use cases coordinate `Storage` and `image.Repository`. |
+| Delivery | `api/handlers/<name>/`, `api/router.go` | HTTP handlers receive use cases through `NewHandler(...)`. They never import persistence, mailer or GORM. |
+| Composition root | `api/dependecyInjection.go` | The only place that picks the database and storage drivers, builds repositories and use cases, and runs `database.Migrate` and the image metadata backfill at boot. |
+| Entry point | `cmd/server/main.go` | Env/config, HTTP server, graceful shutdown. |
+
+Nothing under `internal/` imports `api/`.
+
+### Delivery packages
+
+| Package | Role |
+|---|---|
+| `api/handlers/user` | Authenticated user endpoints: profile update (`UpdateMe`), the users list with invitations (`CreateInvite`, `ListUsers`) and the role change (`RoleHandler.Change`). |
+| `api/handlers/ownership` | `POST /v1/site/transfer-ownership`, built by `NewHandler(TransferOwnershipUseCase)` and mounted by `NewSiteRouter` in the session group. |
+| `api/handlers/media` | The media library under `/v1/media` (list, upload, rename, delete, merge, usage). Images belong to the library, not to an article: deleting an article never deletes an image, and an image's "used in" is read from article bodies each time. |
+| `api/pkg/upload` | Multipart `file` reading and the mapping of upload errors (415, 413, 400) shared by both upload routes. |
+| `api/pkg/publicuser` | `PublicUser`, the JSON shape of a user with no password, codes or token version. `publicuser.New` converts a domain `user.User`, so handlers never serialise the domain struct directly. |
+
+### Media purge
+
+`internal/domain/purge` holds `Settings` (automatic purge on or off, interval of 1 to 365 days, `last_purge_*` history, `enabled_at`), the `Repository` interface (`Get` returns the defaults when nothing was saved, `Save`, and `SaveLastRun`, which writes only the `last_purge_*` columns so a settings change made during a run is never overwritten) and the sentinels `ErrInvalidPurgeInterval`, `ErrPurgeConflict` (stale fingerprint) and `ErrPurgeBusy` (a run is already in progress). `Settings.NextPurgeAt` is `max(last_purge_at, enabled_at)` plus the interval when automatic purge is on, and null otherwise. The settings live in a single-row `purge_settings` table (`models.PurgeSettings`, `mappers.PurgeSettings*`, `persistence.PurgeSettingsRepository`), created by `AutoMigrate`.
+
+The use cases `GetPurgeSettings`, `UpdatePurgeSettings`, `PreviewPurge` and `RunPurge` depend only on domain interfaces, an injected clock and an injected `*log.Logger`, so a scheduler can call them. `PreviewPurge` and `RunPurge` share one plan (`purgePlan.go`): a duplicate group (same non-empty sha256) is planned only when a copy is used in an article, the most used copy is kept (ties: oldest `created_at`, then lowest id) and every other copy is merged into it. The fingerprint is a SHA-256 over the planned groups. `RunPurge` takes a non-blocking in-process lock (`ErrPurgeBusy` for a concurrent call), refuses a non-matching fingerprint with `ErrPurgeConflict`, merges group by group with `MergeMedia` (a failing group is counted and skipped), unions the `UpdatedArticleIDs` of the fully merged groups, and records `last_purge_*` after every run.
+
+#### Automatic purge scheduler
+
+`PurgeSchedulerUseCase.Tick(now)` returns the `purge.RunResult` of the run, whether it ran and an error. It reads the purge settings on every call and runs `RunPurge.Run(nil)` (no fingerprint) when `Settings.NextPurgeAt()` is set and `now` is not before it. It never writes settings: only `RunPurge` records `last_purge_*`, through `SaveLastRun`, which moves the anchor forward even when nothing was purged. The runner in `internal/infrastructure/scheduler` calls `Tick` and logs one line with `groups_purged`, `merged`, `articles_updated` and `failed_groups` when a run happened. It calls `Tick` once after a startup delay of 1 minute, which catches up a run missed during downtime in a single purge, then once every hour. `api/dependecyInjection.go` builds it and `cmd/server/main.go` starts it with the signal context of the server. Changes to the settings apply on the next tick, with no restart.
+
+- Overlap guard: a manual run holds the `RunPurge` lock, so `Tick` returns `ErrPurgeBusy` at once. The runner treats it as a skip, logs nothing and re-evaluates at the next tick.
+- Failures: any other error is logged and the loop keeps going. There is no retry inside a tick; the next hourly tick evaluates the schedule again.
+- Shutdown: on SIGINT or SIGTERM the runner stops taking ticks and waits, with no time limit, for a `Tick` in progress. `main` waits for the runner to return before the database is closed.
+
+`middleware.RequireOwnerOrAdmin` lets only the roles owner and admin through (403 otherwise, including an empty role). The media router mounts these routes after the verified chain and before the `/{id}` routes:
+
+| Route | Purpose |
+|---|---|
+| `GET /v1/media/purge-settings` | Settings with `next_purge_at`. |
+| `PATCH /v1/media/purge-settings` | Partial update of `auto_purge_enabled` and `auto_purge_interval_days`. |
+| `GET /v1/media/purge-preview` | Groups, copies, distinct articles, the first 5 groups, `more` and the fingerprint. |
+| `POST /v1/media/purge` | Runs the purge. Optional `fingerprint`; 409 when stale or when a run is in progress. |
+
+### Sessions and personal data retention
+
+A session is an HS256 token from `api/pkg/authtoken`. `Encode` adds a random `jti` and an `exp` 24 hours ahead; `Decode` refuses a token without `exp`. `authtoken.WithRevocationStore` plugs in `useCases.SessionRevocationUseCase`, which stores a `session.Revocation` (`jti`, `exp`) through the `internal/domain/session` `Repository` (`persistence.RevokedSessionRepository`, table `revoked_sessions`). `LoginHandler.Logout` revokes the presented token; from then on `Decode` answers `ErrRevoked` for it, and a store that cannot be read makes every token invalid rather than valid. Revoking every session of a user stays the job of `token_version`, bumped by a password reset.
+
+`useCases.EnforceRetentionUseCase.Tick(now)` deletes revocations past their expiry, unverified accounts 7 days after their code expired (`user.UnverifiedRetention`) and invites 30 days after they expired or were accepted (`invite.Retention`), and returns a `retention.Result`. `scheduler.NewSystemRetentionRunner` calls it one minute after startup and then hourly, logs one line only when something was removed, and stops with the other runners on shutdown.
+
+Uploads go through the `image.MetadataStripper` port before they are measured for size, hashed and stored. `imaging.MetadataStripper` walks the JPEG segments, PNG chunks and WebP RIFF chunks without re-encoding pixels, drops metadata, keeps colour profiles and re-adds an orientation-only EXIF block when the photo was rotated. A container it cannot walk fails the upload with `image.ErrImageUnreadable`.
+
+### Activity log
+
+`internal/domain/audit` holds the append-only `Event` (actor, target and failure-reason snapshots, outcome, security flag, source, ip, user agent, `params` and `changes`), the closed vocabularies (actor type, category, outcome, source, change kind), the `Filter`, `Summary` and `Settings` types, the `Repository` interface (`Append`, `List`, `Summary`, `DeleteOlderThan`: no way to edit or delete one event), the `SettingsRepository` (`Get`, `SaveRetention`, `SaveLastCleanup`; no row means 90 days) and the sentinels `ErrInvalidFilter`, `ErrInvalidRetention`, `ErrInvalidEvent` and `ErrActorNotAllowed`. The `Recorder` port is `Record(ctx, event)`; it returns nothing, so a caller can never fail on it.
+
+`internal/infrastructure/auditing.Recorder` is the adapter. It fills a missing actor, source, ip and user agent from the `audit.Origin` carried by the request context, stamps `created_at` from the injected clock in UTC, bounds long names, drops an event outside the vocabulary, and recovers from any error or panic of the repository by writing one line to the process log (the action and the error only). `middleware.AuditContext` builds the origin after the credential middleware: a session gives a `user` actor and source `web`, an API key an `api_key` actor and source `api_key`, no valid credential an `anonymous` actor; the ip is the peer address, or `X-Real-IP` when the peer is a trusted proxy; the user agent is cut to 255 characters. Use cases that produce events (authenticate and logout, password reset request and completion, API key create and revoke, retention change, cleanup) take the context and an `audit.Recorder`; secrets (passwords, raw keys, reset codes, tokens and their hashes) are never put in an event or in its log line.
+
+Persistence is `models.AuditEvent` (`audit_events`, indexes on `created_at`, `(actor_type, actor_id, created_at)` and `(category, created_at)`; `params` and `changes` are JSON text) and `models.AuditSettings` (one row), both in `AutoMigrate`. The queries use only portable SQL (`LOWER(...) LIKE ... ESCAPE '!'`, `COUNT(DISTINCT ...)`, `CASE` sums), so they run on SQLite, MySQL/MariaDB and PostgreSQL. The summary splits the range into seven equal buckets, oldest first.
+
+The use cases `ListActivity`, `GetActivitySummary` and `ExportActivity` turn the raw query into a domain filter (`range` defaults to 7 days; `custom` needs two dates, `to` included), scope a caller who is not owner or admin to its own events, and resolve `target.exists` at read time. The export reads the log through `List` in pages of 500 and writes the CSV with `encoding/csv`. `/v1/activity` and the settings `PATCH` sit behind `RequireSession`, the verifier, the current-token and verified-user checks; summary and export also behind `RequireOwnerOrAdmin`, the settings `PATCH` behind `RequireOwner`.
+
+`CleanupActivityUseCase.Tick(now)` follows the `PurgeScheduler` model. With a retention of 0 it never runs. Otherwise it is due once a day, at or after 03:00 in the location of `now` and when the last cleanup is before today's 03:00. It deletes events older than `now` minus the retention days (never newer than 24 hours), records the run (`activity_last_cleanup_at`, `activity_last_cleanup_removed`) even when nothing was removed, and only then records a `system.activity_cleanup` event when something was removed. A failing delete returns the error and leaves the last-cleanup fields as they were, so the next tick retries. `scheduler.Runner` now wraps a task with a label: `NewRunner` keeps the purge behaviour and log line, and `NewCleanupRunner` ticks the cleanup. `UseCases.RunSchedulers` runs both runners and `cmd/server/main.go` starts it with the server's signal context.
+
+Producers: `ArticleChanges`, `TextChange` and `BodyChange` in `internal/domain/audit` build the change lists (the body change holds only a signed rune count delta), and `NewTarget` and `ReleaseTarget` build the target snapshots (types `article`, `image`, `user`, `invite`, `api_key`, `release`). The use cases create, edit, publish, unpublish and delete article, upload, rename, delete, merge and purge media, register, verify, update profile, create, cancel, renew and accept invite, check, download and restart take the request context first and an `audit.Recorder` last, and record exactly one event after the change or the refusal (the action catalogue is in `docs/api.md`). Events are never written by handlers, middleware or GORM hooks, and nothing is recorded for reads or for a target that does not exist. `useCases/auditFailures.go` holds the fixed table of failure sentences keyed by domain `Err...` sentinels (matched with `errors.Is`, each at most 255 characters; the restart action overrides `ErrJobInProgress`) with the generic fallback "Something went wrong on our side. Please try again."; raw error text is never stored. The manual purge runs the groups through the non-recording `MergeMediaUseCase.merge`, so only one `media.purge` event is written; `RunPurgeUseCase.Execute` is the non-recording run that `PurgeSchedulerUseCase.Tick(now)` uses to record one `system.media_purge` event with the system actor and `context.Background()`. `StartUpdateDownloadUseCase` hands `context.WithoutCancel(ctx)` to its job goroutine so the `system.update_downloaded` event, written when the job becomes `ready` or `failed`, keeps the origin of the request. `middleware.AuditContext` is mounted on the article, user, media and system routers (after the API key middleware where keys are accepted), so API key calls are attributed to the key.
+
+### Sites
+
+`internal/domain/site` holds the `Site` entity (name, immutable key, normalised base URL, optional default social image, `index` or `noindex` robots, optional locale, the default flag and the computed `article_count`), `NormalizeBaseURL`, `SeedBaseURL`, `NormalizeLocale`, `IsValidKey`, the `Patch` type (with `Nullable` for the two nullable fields), the `Err...` sentinels (`ErrSiteNotFound`, `ErrSiteKeyTaken`, `ErrSiteHasArticles`, `ErrDefaultSite`, `ErrKeyImmutable`, `ErrInvalidSiteURL`, `ErrInvalidLocale`, `ErrUseSetDefault`, `ErrInvalidReassign`) and the `Repository` interface. `persistence.SiteRepository` implements it over `models.Site` (`sites`, unique `site_key`); the single default is kept by the transactional operations `Create` (when flagged) and `SetDefault`, not by an index, and `DeleteMovingArticles` moves the articles and deletes the site in one transaction. Articles carry a `site_id` (indexed, no foreign key, so the SQL stays portable).
+
+The use cases `ListSites`, `CreateSite`, `UpdateSite`, `SetDefaultSite` and `DeleteSite` live in `internal/infrastructure/useCases`; the article, media and purge use cases take the site repository as a required constructor argument, wired by the composition root (new articles take the default site, `UpdateArticle` moves an article and records `site` with site names, the media use cases count, clear and repoint default social images). `api/handlers/site` serves `/v1/site`; reads accept a session or an API key, writes are session only behind `RequireOwner`. `database.Migrate(db, publicURL)` registers the model, seeds one default site from `PUBLIC_URL` when the table is empty and backfills `articles.site_id`.
+
+### Authors
+
+`internal/domain/author` holds the `Author` entity (name, unique slug, bio, optional avatar, optional website, social links, the unique optional `user_id`, `is_linked`, the computed `article_count` and a `user_email` that only owner and admin responses carry), the public `Byline` shape embedded in articles, the `Patch` type, the slug generation (a hand-written Latin diacritic folding table, no external dependency), the value rules (`ValidateBio`, `ValidateURL`, `ValidateLinks`, `IsValidSlug`, `IsValidName`), the `Err...` sentinels (`ErrAuthorNotFound`, `ErrSlugTaken`, `ErrAuthorHasArticles`, `ErrUserAlreadyLinked`, `ErrAuthorAlreadyLinked`, `ErrAuthorRights`, `ErrBioTooLong`, `ErrInvalidURL`, `ErrTooManyLinks`, `ErrInvalidSlug`, `ErrInvalidReassign`) and the `Repository` interface. `persistence.AuthorRepository` implements it over `models.Author` (`authors`, unique `slug` and unique nullable `user_id`) and the ordered join `models.ArticleAuthor` (`article_authors`, unique `(article_id, author_id)` and a `position`); uniqueness is checked inside the transaction and re-explained after a failed write, so a race still answers a domain sentinel, and `DeleteMovingCredits` moves the credits (keeping the position, never duplicating) and deletes the author in one transaction. `ArticleRepository` attaches the ordered `Byline`s to the articles it returns, writes `author_ids` in the article update transaction and removes the credits when an article is deleted.
+
+The use cases `ListAuthors`, `CreateAuthor`, `CreateMyAuthor`, `UpdateAuthor`, `DeleteAuthor` and `GetMyAuthor` live in `internal/infrastructure/useCases`; `CreateArticle` credits the creator's author, `UpdateArticle` validates and records `author_ids`, and the media, purge and activity use cases take the author repository as a required constructor argument (avatars count as media usage, are cleared on delete and repointed on merge and purge). `api/handlers/author` serves `/v1/author`: the list accepts a session or an API key, every write is session only, `POST /` and `DELETE` sit behind `RequireOwnerOrAdmin`, and the edit rights (owner or admin, or the caller's own linked author) are decided by `UpdateAuthor` from the caller the handler passes in. `GET /v1/auth/me` adds the linked author through `GetMyAuthor`.
+
+### Article SEO data
+
+`internal/domain/slug` holds the one slug rule (`Generate`, `WithSuffix`, `IsValid`: lowercase, accents folded, runs of other characters become one dash, 100 characters, a caller-chosen fallback). `internal/domain/article` uses it with the fallback `article` and holds the twelve SEO fields of `Article`, the `Update` fields for them (`Nullable` for the two image ids), `ValidateCanonicalURL`, the eleven dismiss codes and `NormalizeDismissed`, and the sentinels `ErrInvalidSlug`, `ErrSlugTaken` and `ErrInvalidCanonicalURL`. `*SlugTakenError` wraps `ErrSlugTaken` and carries the suggested free slug; the handler turns it into the `X-Slug-Suggestion` header of the 409. `author.GenerateSlug` delegates to the same package.
+
+Slugs are unique per site, enforced by the unique index `idx_articles_site_slug` on `(site_id, slug)`. The use cases decide first: `CreateArticle` generates the slug from the title and takes the first free `-N` on the default site (retrying when the repository reports a race), `UpdateArticle` re-checks the slug on the target site for an edited slug, an empty slug (regenerated from the title) and a move, and computes the suggestion as the first free `-N` from 2, fitting 100 characters. `ArticleRepository` locks the site row, checks the slug inside the transaction and re-explains a failed write as `ErrSlugTaken`. Deleting an article replaces its slug with the tombstone `#deleted-<id>` (it can never match a valid slug) before the soft delete, so the slug is free again while the unique index keeps covering soft-deleted rows.
+
+`database.Migrate` adds the columns with `AutoMigrate`, then runs `BackfillSiteTitleTemplates` and `BackfillArticleSlugs` (only rows with an empty slug, in id order, per site, applying the same rule and the same suffixes, with the tombstone for soft-deleted rows) and only then creates the unique index, so it is idempotent and completes a partly backfilled table. The default `title_template` is written by the backfill and the seed, not by a column default, because the SQLite migrator rebuilds the table on every start when the default contains `%` and `|`.
+
+Media usage has more sources than article bodies: `Article.CoverImageID` and `SocialImageID`, `Author.AvatarID` and `Site.DefaultSocialImageID`. `ListMedia`, the purge plan and `GetMediaUsage` count an article once however many places use the image. `DeleteMedia` clears the cover and social references (`article.Repository.ClearImage`, restored with `RestoreImage` when the delete fails), `MergeMedia` repoints them (`RepointImage`) and counts an article rewritten in its body and its cover once, and `GetMediaUsage` (now built with the site and author repositories) returns articles, authors and sites with `type` and `fields`.
+
+### Image variants
+
+`internal/domain/image` holds the `Variant` entity and its rules (`VariantSettings.Normalized`, the settings `Fingerprint`, `VariantETag`, `ETagMatches`, `IsAnimatedGIF`), the sentinels (`ErrVariantNotFound`, `ErrVariantExists`, `ErrVariantInvalid`, `ErrVariantFormatUnavailable`, `ErrUnknownVariant`, `ErrUnsupportedParameter`, `ErrSourceTooLarge`) and three ports: `VariantRepository` (definitions), `VariantFileRepository` (the index of generated files: variant name, source stored name, cached stored name, content type, size and the settings fingerprint, needed because `Storage.Put` chooses the stored name itself) and `VariantRenderer` (decode a source, encode a variant, report the formats it can encode). `internal/infrastructure/imaging` is the renderer adapter, free of GORM and HTTP; the persistence adapters are `VariantRepository` and `VariantFileRepository` over `models.ImageVariant` and `models.ImageVariantFile`.
+
+Generated bytes are stored only through `image.Storage`, so they follow `STORAGE_DRIVER`, and are never rows of `images`. `ServeVariantUseCase` checks, in order: unsupported parameters, the variant (it must exist and be enabled), the source blob, SVG and animated GIF (served as they are), the size cap, the `If-None-Match` ETag, then the cached file, and generates under an in-process single-flight group keyed by variant, settings and source. A row whose fingerprint no longer matches, or whose blob vanished, is replaced. `UpdateVariantUseCase` purges a variant's files when a rendering setting changes; `DeleteVariantUseCase` and `PurgeVariantUseCase` purge a blob and then its row, so a failed blob delete keeps the row and a retry can finish; `mediaRemover` purges the files of a source before it deletes the source (delete and merge).
+
+The cache screen adds three ports in `internal/domain/image`: `VariantCacheRepository` (unused totals, top sources by bytes and cursor-paged row listing, implemented by the same persistence type as `VariantFileRepository`), `VariantUsageRepository` (one batched write of request times and per-day rejection counts, and the rejection total of a window) and `VariantUsageTracker` (in-memory hits and rejections). `internal/infrastructure/usage.Tracker` implements the tracker; `GetVariantCacheStatsUseCase` and `PurgeVariantCacheUseCase` use the ports only. See [image-variants.md](image-variants.md).
+
+### Image metadata backfill
+
+At boot, `BackfillImageMetadataUseCase` (through `image.Repository.ListMissingMetadata` and `UpdateMetadata`) fills `filename`, `size`, `content_type`, `width`, `height` and `sha256` for image rows that lack them, reading the bytes through `image.Storage` (the files in `UPLOAD_DIR` with the local adapter, the bucket objects with the S3 adapter). It is idempotent, and a row whose file is missing or unreadable is left as it is without stopping the boot. The old `article_id` column and the `article_images` table are kept and never written.
+
+### Roles and permissions
+
+`internal/domain/role` holds the permission catalogue, the built-in roles, one exported constant per catalogue key (`roleKeys.go`, the only place a key is spelled in `api/`) and the pure rules over grants: `ValidateGrants`, `ParseTypedKey` and `Role.GrantSet()`. `Role.GrantSet()` is the single constructor of a `GrantSet` and the only place a stored grant becomes an effective one: it drops unknown keys, typed keys on non-content permissions or with an invalid type key, and owner-only permissions on a role that is not locked; it treats a toggle stored at `own` as `none`; and it resolves duplicate rows to the most restrictive scope. `ValidateGrants` rejects the same rows at write time (`ErrDuplicateGrant`, `ErrOwnerOnlyGrant`, `ErrInvalidScope`, `ErrUnknownPermission`), so a bad row is refused when written and ignored when read. A toggle permission only counts at scope `all`, a scoped one at `own` or `all`. A content permission can be narrowed or widened per content type with a key such as `content.update:blog`; the typed row replaces the wildcard for that type and a `none` row denies. A `GrantSet` is opaque: `ScopeFor(key, typeKey)` resolves wildcard and typed rows, `Permits(key, typeKey, callerID, createdBy)` is the one implementation of own and all (`created_by` 0 and caller 0 own nothing), and `Holds`, `HoldsFor` and `HoldsAll` answer the gate questions. Use cases, handlers and middleware never compare a caller id with `CreatedBy` and never read grant rows. `role.Repository` holds `List` (with every role's grants, in one pass), `Get`, `GetByName`, `Create`, `Save`, `Delete`, `ReassignMembers`, `RemoveTypedGrants` and `MemberCounts` (users grouped by `role_id` plus invites with `accepted_at` NULL grouped by `role_id`, two statements for any number of roles); no role use case scans `user.Repository.GetAll`. `user.Repository` gains `UpdateRole(id, from, to)`, a compare-and-swap on the role the use case read (`ErrRoleChanged`, `ErrUserNotFound`, `role.ErrRoleNotFound`), and `TransferOwnership(from, to, ownerRoleID, formerRoleID)`, which updates both rows in one transaction and fails whole when `from` no longer holds the Owner role (`ErrRoleChanged`) or `to` is missing or unverified (`ErrInvalidTransfer`). `invite.Invite` carries `RoleID`. `ChangeUserRoleUseCase`, `TransferOwnershipUseCase` and the amended invite use cases find the built-in roles with one helper, `builtInRole(roles, name)` (`GetByName`, then `built_in` must be true), and a user's role with `resolveRole`, which reads `role_id` only. `Delete` re-counts users and open invites inside its transaction and `ReassignMembers` moves users and open invites in one transaction and returns their sum. `Save` is version checked: it updates the row only when the caller's version matches, bumps the version, writes `updated_at` and `updated_by`, replaces the grants in the same transaction and returns `ErrRoleConflict` otherwise. It never changes `built_in` or `locked`. `Delete` removes the role and its grants in one transaction and returns `ErrRoleHasMembers` when a user still has the role id; `ReassignMembers(from, to)` changes only `role_id` and returns the count; `RemoveTypedGrants(typeKey)` removes the five `content.*:{typeKey}` rows from every role and bumps the version of each affected role once. The role domain also owns `GrantSet.Covers(other, typeKeys)`, the single implementation of "the caller holds at least these grants" behind the no-escalation rule (it returns an `EscalationError` naming the first offending key), `Role.EffectiveGrants()` (the normalised list used by role responses, the audit diff and `/v1/auth/me`) and `DiffGrants`. The roles API (`/v1/role`) is served by `ListRolesUseCase`, `GetRoleUseCase`, `CreateRoleUseCase`, `UpdateRoleUseCase` (which also resets a built-in role), `DeleteRoleUseCase` and `ReassignRoleMembersUseCase`; they depend on `role.Repository`, `user.Repository`, `contenttype.Repository` and `audit.Recorder` only, and `api/handlers/role` maps their domain errors to the status and code. `DeleteContentTypeUseCase` and `CreateContentTypeUseCase` also take the role repository to clear per-type grants. `DeleteContentTypeUseCase` deletes the type and then clears its typed rows; if that cleanup fails the rows stay, which is safe because the role views (`GET /v1/role`, `GET /v1/role/{id}` and every write response) drop typed rows for content types that no longer exist, so a GET body stays a valid PUT body, and `CreateContentTypeUseCase` clears the rows of a key right after a successful create, before any role can match the new type. A failed create never touches the roles. The repository re-checks the name case-insensitively inside the `Create` and `Save` transactions (`ErrRoleNameTaken`), locks the role row in `Delete` before counting members (a no-op on SQLite) and guards the `ReassignMembers` update with an `EXISTS` on the target role, answering `ErrInvalidReassign` when the target vanished.
+
+Enforcement path. The first middleware that needs the signed-in user (`AuditContext`, `RequireCurrentToken`, `RequireVerifiedUser` or a permission gate) stores a request-scoped holder in the context (`access.WithCurrentUser`), so the user is loaded once per request; an API key adds the one load of its own authentication. `CheckPermissionUseCase` resolves the caller's role with one `role.Repository.Get` (a user whose `role_id` is 0 resolves to `ErrRoleNotFound`, an empty grant set), builds the `GrantSet` from the grants the role already carries and never calls `List`. `RequireTypedPermission` gates a content route on the typed scope before any lookup (the type key is `article` for articles and the `{key}` of the URL for entries) and puts the caller (`access.Caller`: user id and grants) in the context. The optional `OptionalAccess` middleware does the same for the public article routes without ever refusing: no cookie, an unverified user, a stale token or an unresolvable role leave the caller anonymous, and only a role repository failure answers 500. The handler passes the caller to the use case as `useCases.ContentCaller`; the use case loads the article or entry, decides the scope with `Permits` right after the load and before any other lookup or validation, and returns a `role.MissingPermissionError`, which `access.WriteIfMissingPermission` writes as 403 with the base key in `X-Missing-Permission`. Reading follows the same helper: an article is visible when it is online or `content.read` permits its `created_by`, and an entry the caller may not read is `entry.ErrEntryNotFound`. A list under scope `own` is filtered before totals, search and paging. `CreateContentTypeUseCase` refuses the built-in type keys with `contenttype.ErrKeyTaken`.
+
+Built-in reconciliation: `database.SeedBuiltInRoles` creates the three built-in roles when they are missing and never overwrites an edited one. On every start it adds the catalogue keys a built-in role lacks: always for Owner, at scope `all`, and for Admin and Writer only while their version is still 1. It never removes or downgrades a grant and never bumps the version.
+
+Created-by backfill: `database.BackfillCreatedBy` assigns articles (soft-deleted ones included) and entries whose `created_by` is 0 to the first owner by id. A database without an owner is left alone. Entries have no soft delete, so no unscoped query is needed for them.
+
+## Frontend ↔ backend
+
+```
+web/ (Vue, Vite)
+  │  task build:web  (vue-tsc + vite build)
+  ▼
+internal/infrastructure/assets/dist/        gitignored build output
+  │  //go:embed all:dist   (assets_embed.go, default build)
+  ▼
+bin/renewcms  ──  /v1/*  API
+               ──  /healthz
+               ──  /*    SPA (api/handlers/frontend), index.html fallback
+```
+
+- **Production:** a single origin. The SPA calls the API with relative URLs, so the JWT cookie works without CORS. Files under `assets/` are content-hashed by Vite and cached for a year. `index.html` is never cached.
+- **Development:** built with `-tags nofrontend` (`assets_stub.go`, `assets.Dist == nil`). Vite serves the SPA on :5173 and proxies `/v1` to the API on :8080. See [development.md](development.md).
+
+## Storage and database seams
+
+Uploaded images are addressed by a stored name (`<uuid>.<ext>`). `CreateImageUseCase` calls `Storage.Put` (which generates the name), then `Repository.Create` with `Path = /static/uploadedImages/<name>`, and deletes the blob again if the row cannot be created. `DeleteMediaUseCase` and `MergeMediaUseCase` remove the blob first and the row second (`mediaRemover`), so a failed blob delete keeps the row and the delete can be retried. `GET /static/uploadedImages/<name>` is served by `OpenMediaUseCase` through `api/handlers/staticimages`, which uses `http.ServeContent` when the blob is seekable and streams it otherwise; `ErrBlobNotFound` maps to 404 and any other error to 500.
+
+SQL in repositories must run on SQLite, MySQL/MariaDB and PostgreSQL: substring searches use `LIKE ... ESCAPE '!'` through `containsPattern` instead of `instr`. `Settings.DataDir()` is where update state, staging and backups live; it is `DATA_DIR` when set and the directory of `DB_FILE` otherwise, so it does not depend on where the database is.
+
+Three drivers are registered in `database.drivers`: `sqlite` (default), `mysql` (MySQL 8 and MariaDB 11, through `gorm.io/driver/mysql`) and `postgres` (PostgreSQL 16 and 17, alias `postgresql`, through `gorm.io/driver/postgres` on pgx v5); all are pure Go so `CGO_ENABLED=0` and the six release targets still build. `DB_DRIVER` picks one in `databaseConfig` (composition root); an unknown name fails in `database.Connect` with `unsupported database driver "<name>"`. `database.MySQLDSN` and `database.PostgresDSN` build the DSN from separate variables (the PostgreSQL one as an escaped URL with `sslmode`, `timezone=UTC` and a connect timeout), and the driver redacts the password from every error and names only host and port. `Connect` applies the optional `PoolSettings` to any driver. What keeps the repositories identical on both engines, all without touching the domain, use cases or handlers:
+
+- Indexed and unique strings carry `size:` tags in the models (a MySQL index needs a bounded `varchar`). SQLite maps them to the same `text` column, so an existing SQLite file migrates with no schema or row change (`test/sqlite_schema_unchanged_test.go` builds a file from the old model definitions and compares `sqlite_master` and every row).
+- `Migrate` creates MySQL tables with `utf8mb4_bin` (`gorm:table_options`), so `Bob` and `bob` are distinct like in SQLite. The DSN also sets `collation=utf8mb4_bin`.
+- The DSN sets `clientFoundRows=true`: an update that matches a row but changes nothing still reports one affected row, as in SQLite. `InviteRepository.Renew`, `deleteOrNotFound` and `PurgeSettingsRepository.SaveLastRun` depend on that.
+- The Go driver sends a zero `time.Time` as `0000-00-00`, which MySQL's default `NO_ZERO_DATE` rejects, so each session sets `sql_mode` to the server default minus `NO_ZERO_DATE`. Reading `0000-00-00` gives the zero time back.
+- `UserRepository.Create` returns the filled model instead of re-reading it, because MySQL has no `RETURNING`.
+
+On PostgreSQL the MySQL-only table options are not applied, pgx returns `timestamptz` values in the local zone so a query callback in the driver converts them to UTC, and only the `public` schema is used.
+
+Backups are a `domain/update.DatabaseBackup` per driver. SQLite uses `VACUUM INTO`. MySQL uses `DumpBackup`, a pure Go logical dump (`SHOW CREATE TABLE` plus every row, strings escaped and binary values as hex, NULL and zero dates kept) written inside one repeatable-read transaction to `DATA_DIR/backups/renewcms-<time>.sql.partial` and renamed once complete. Any failure removes the partial file and returns an error, so the update download fails instead of claiming a backup. PostgreSQL reuses `DumpBackup` with its own `dumpDialect` (double-quoted identifiers, doubled single quotes, `\x` bytea literals): `CREATE TABLE` is rebuilt from `pg_catalog` (serial columns, defaults, primary key, unique and check constraints), followed by the indexes, the rows and a `setval` per `id` sequence, all inside one repeatable-read read-only transaction. All drivers keep the newest 3 files (`pruneBackups`).
+
+`task test` runs everything that needs no server. The repository contract tests (`test/repository_contract_test.go`) run on SQLite always, and on MySQL when `RENEWCMS_TEST_MYSQL_DSN` points at a server (admin DSN; each test creates and drops its own database). `task test:mysql` starts `mysql:8.4` and then `mariadb:11` in Docker and runs the `MySQL` tests against each. The same contract tests run on PostgreSQL when `RENEWCMS_TEST_POSTGRES_DSN` points at a server (admin DSN, for example `postgres://postgres:pw@127.0.0.1:5432/postgres?sslmode=disable`), and `task test:postgres` starts `postgres:16` then `postgres:17` in Docker and runs the `Postgres` tests against each.
+
+Two storage adapters implement `image.Storage`: `local` (default, files in `UPLOAD_DIR`) and `s3` (`storage.S3Storage`, `aws-sdk-go-v2` over plain HTTPS, pure Go so `CGO_ENABLED=0` still holds). `STORAGE_DRIVER` picks one in `imageStorageConfig` (composition root, from `config.StorageSettings`); `storage.Open` fails with `unsupported storage driver "<name>"` for anything else, and `openImageStorage` panics with the error. The S3 adapter works as follows, with no change to the domain, use cases, repositories or the `staticimages` handler:
+
+- `Open` calls `GetObject` and returns a `Blob` whose `Content` is an `io.ReadSeeker` (`s3Reader`): `Size` and `ModTime` come from `ContentLength` and `LastModified`, the first bytes are read from that response and every `Seek` to another offset makes the next `Read` issue a ranged `GetObject`. `http.ServeContent` therefore answers `Range` (206, 416) and `If-Modified-Since` (304) with no `ETag`. A 404 maps to `image.ErrBlobNotFound`; any other failure is a plain error (500 in the handler).
+- `Put` does one `PutObject` of `<S3_KEY_PREFIX><uuid>.<ext>` with the upload's `Content-Type`. `Delete` treats 404 as success. Names that are not plain file names are never requested, as in the local adapter.
+- Each call has a 30 second timeout to get a response (the body then streams without a deadline) and the SDK default retries. Request checksums are only sent when required, so older S3-compatible servers work.
+- `storage.Open` checks the bucket with `HeadBucket`. The failure text names the bucket and the reason (404, 403, other status or transport error) and never the credentials.
+- At boot, `RunBackfillReportingReads` wraps the storage in a counter for the `BackfillImageMetadataUseCase` run and logs how many images it read; the use case itself is unchanged.
+- Update backups (`DATA_DIR`) never include uploads, whatever the driver.
+
+`task test:s3` starts SeaweedFS in Docker and runs `TestS3StorageIntegration` against it (skipped without Docker, and not part of `task test`). Everything else uses an in-process fake S3 server listening on `127.0.0.1`.
+
+Adding a database driver: implement `database.Driver` (`Open`, and `NewBackup` returning a `domain/update.DatabaseBackup`), register it in `drivers`, then select it in `databaseConfig` in the composition root (and add the env vars to `main.go`, `.env.example` and `configuration.md`). Adding a storage backend: implement `image.Storage`, add a case to `storage.Open`, and select it in `openImageStorage`. No use case, handler or repository changes.

docs/configuration.md

@@ -0,0 +1,120 @@
+# Configuration
+
+RenewCMS reads its configuration from environment variables. On startup it also loads a `.env` file from the working directory (or its parent) if one exists. Real environment variables take precedence over `.env`. The parser reads `NAME=value` lines, an optional `export ` prefix, `#` comments (inline ones need a space before the `#`), and single- or double-quoted values (`\n`, `\t`, `\"` and `\\` are unescaped in double quotes). It does not expand `$VARIABLES` and does not support multi-line values. A malformed line makes the whole file ignored, and the server logs the line number.
+
+Copy [`.env.example`](../.env.example) to `.env` to get started. When a required variable is missing, the server refuses to start and names the variable.
+
+## Variables
+
+### Required
+
+| Name            | Description                                                                                                         | Example                    |
+|-----------------|---------------------------------------------------------------------------------------------------------------------|----------------------------|
+| `PUBLIC_URL`    | Public base URL of the site, including scheme and no trailing slash. Used for links in emails and in the startup log. It is also the CMS's own address: at the first migration, when the sites table is empty, it seeds the default site (name "Default", key "default") with its scheme and host (path dropped, non-loopback `http` upgraded to `https`); an unparseable value stops the migration. It is never read for sites afterwards. | `https://cms.example.com`  |
+| `JWT_SECRET`    | Secret used to sign the auth JWT. It must be at least 32 bytes, and the example values from `.env.example` and `docker.env.example` are refused: the server stops at startup with `JWT_SECRET is too weak` and how to generate one. Changing it logs everyone out. | `openssl rand -hex 32`     |
+| `SMTP_LOGIN`    | SMTP username used to authenticate with the server. Some providers (e.g. Brevo) issue a login distinct from the sender address. | `noreply@example.com` |
+| `SMTP_SENDER`   | Sender address used in the `From` header. Must be an address/domain the SMTP provider allows that login to send as.  | `noreply@example.com`      |
+| `SMTP_PASSWORD` | SMTP password.                                                                                                      |                            |
+| `SMTP_HOST`     | SMTP server host.                                                                                                   | `smtp.example.com`         |
+| `SMTP_PORT`     | SMTP server port.                                                                                                   | `465`                      |
+
+### Optional
+
+| Name                   | Default              | Description                                                                                                                                                                                                                     |
+|------------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `ENVIRONMENT`          | `production`         | `production` or `development`. In `production` the auth cookie is `Secure`, so it is only sent over HTTPS. `development` turns on HTTP request logging.                                                                           |
+| `PORT`                 | `8080`               | Port the HTTP server listens on (all interfaces).                                                                                                                                                                               |
+| `DB_DRIVER`            | `sqlite`             | `sqlite`, `mysql` (MySQL and MariaDB) or `postgres` (alias `postgresql`). Any other value stops the server with `unsupported database driver "<value>"`. See [Database](#database).                                                                             |
+| `DB_FILE`              | `./data/renewcms.db` | Path to the SQLite database file. Missing parent directories are created. The schema is migrated automatically at startup. Ignored when `DB_DRIVER` is `mysql` or `postgres`.                                                                     |
+| `DATA_DIR`             | directory of `DB_FILE` | Directory for update state, staged updates and database backups (`backups/`). Set it with `DB_DRIVER=mysql` or `postgres`, where there is no database file to sit beside (the default still follows `DB_FILE`). With SQLite, leave it unset to keep everything beside the database. |
+| `STORAGE_DRIVER`       | `local`              | `local` (files in `UPLOAD_DIR`) or `s3` (an S3-compatible bucket). Any other value stops the server with `unsupported storage driver "<value>"`. See [Image storage](#image-storage). |
+| `UPLOAD_DIR`           | `./data/uploads`     | Directory where uploaded images are stored. Ignored, without error, when `STORAGE_DRIVER=s3`.                                                                                                                                                                                     |
+| `CORS_ALLOWED_ORIGINS` | *(empty)*            | Semicolon-separated list of origins allowed to call the API. Matching is case-insensitive. An entry may contain one `*` (`https://*.preview.example.com`), and a lone `*` allows every origin. Credentials are never allowed cross-origin. When empty, no CORS headers are sent. That is the right setting whenever the SPA is served by RenewCMS itself (production) or through the Vite proxy (development). |
+| `AUTH_RATE_LIMIT_MAX_ATTEMPTS` | `5`           | Maximum number of requests a single client IP may send to `POST /v1/auth/login`, `POST /v1/auth/password-reset` or the invite-accept pair (`GET /v1/auth/invite` and `POST /v1/auth/invite/accept`, sharing one counter) within the window, tracked independently per route.                                                          |
+| `AUTH_RATE_LIMIT_WINDOW_SECONDS` | `60`        | Length, in seconds, of the fixed rate-limit window for the routes above.                                                                                                                                                    |
+| `SMTP_ALLOW_INSECURE`  | `false`              | `true` lets RenewCMS deliver mail without encryption to a server on another host that does not offer STARTTLS (a relay on a private network, a local Mailpit container). By default such delivery fails with an error naming this variable; port `465` always uses implicit TLS and `localhost`, `127.0.0.1` and `::1` are always allowed in clear text. Credentials (`SMTP_LOGIN`/`SMTP_PASSWORD`) are never sent unencrypted to another host, whatever this says. Any value other than `true` or `false` (case-insensitive) stops the server at boot. |
+| `TRUSTED_PROXIES`      | *(empty)*            | Semicolon-separated list of exact IP addresses (no CIDR) of reverse proxies allowed to supply the client IP via `X-Real-IP` for the rate limiting of the routes above. When a request's connection address is not in this list, any `X-Real-IP` or `X-Forwarded-For` header it sends is ignored and the connection address is used instead. See [deployment.md](deployment.md).      |
+| `RENEWCMS_CONTAINER` | `false` | Set to `true` (case-insensitive; any other value means `false`) when the app runs in a container. Settings then tells the owner to update by pulling a new image instead of offering browser updates, and `can_apply` is always `false`. The Dockerfile and `docker-compose.yml` set it to `true`. Update checks still work. |
+| `IMAGE_VARIANT_MAX_SOURCE_BYTES` | `10485760` | Largest stored image, in bytes, that an [image variant](image-variants.md) may be generated from. A request for a bigger source answers 413 with a plain-text body. The original is never affected, and SVG and animated GIF are always served as they are. A value that is not a whole number greater than zero stops the server at boot with an error naming the variable. |
+| `IMAGE_VARIANT_MAX_SOURCE_PIXELS` | `50000000` | Largest declared width x height, in pixels, that an [image variant](image-variants.md) may be generated from. It is read from the image header before any pixel buffer is allocated; a bigger source answers 413 with the same plain-text body as the byte cap. The original is never affected, and SVG and animated GIF are always served as they are. A value that is not a whole number greater than zero stops the server at boot with an error naming the variable. |
+| `IMAGE_VARIANT_MAX_CONCURRENT_RENDERS` | `4` | Number of [image variant](image-variants.md) renders that may run at once. Other requests wait for a free slot until their client goes away; cached files never wait. A value that is not a whole number greater than zero stops the server at boot with an error naming the variable. |
+| `UPDATE_FEED_URL`      | `https://git.floriansylvain.fr` | Base URL of the Gitea server that publishes RenewCMS releases. The Settings page asks `{UPDATE_FEED_URL}/api/v1/repos/fsylvain/RenewCMS/releases` when the owner checks for updates. The last result is kept in `update-status.json`, in the data directory. |
+
+Automatic media purge has no environment variable. Its schedule (on or off, interval, `enabled_at`, `last_purge_at`) lives in the purge settings row of the database, is changed from the Settings page or `PATCH /v1/media/purge-settings`, and is read again at every hourly tick.
+
+## Image storage
+
+By default uploaded images are files in `UPLOAD_DIR`. To keep them in an S3-compatible bucket (AWS S3, MinIO, Ceph, Cloudflare R2, Backblaze B2 and similar), set `STORAGE_DRIVER=s3` and the variables below. They are only read when `STORAGE_DRIVER=s3`. Image URLs do not change: the app still serves `/static/uploadedImages/<name>`, reading the object from the bucket (the bucket stays private, and `Range` and `If-Modified-Since` requests keep working; there is no `ETag`).
+
+| Name                   | Default     | Description                                                                                                                                                                      |
+|------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `S3_BUCKET`            | required    | Name of an existing bucket. A missing value stops the server with `Environment variable S3_BUCKET is not set`.                                                                  |
+| `S3_REGION`            | `us-east-1` | Bucket region. Most S3-compatible servers accept the default.                                                                                                                    |
+| `S3_ENDPOINT`          | *(empty)*   | Host (with optional port) or full URL of an S3-compatible server. Leave empty for AWS S3.                                                                                       |
+| `S3_ACCESS_KEY_ID`     | *(empty)*   | Access key. Set it together with `S3_SECRET_ACCESS_KEY`, or set neither. Setting only one stops the server with an error naming the missing one.                                |
+| `S3_SECRET_ACCESS_KEY` | *(empty)*   | Secret key. Never logged and never in an error message. When both keys are empty, the default AWS credential chain is used (`AWS_*` variables, shared credentials file, instance or task role). |
+| `S3_KEY_PREFIX`        | *(empty)*   | Prefix put before every object key, for example `uploads/`. Include the trailing slash.                                                                                          |
+| `S3_PATH_STYLE`        | `false`     | `true` addresses the bucket as `endpoint/bucket` instead of `bucket.endpoint`. SeaweedFS, MinIO and most self-hosted servers need `true`.                                                  |
+| `S3_TLS`               | `true`      | Only used when `S3_ENDPOINT` has no `http://` or `https://` prefix: `true` means `https`, `false` means `http`.                                                                 |
+
+At startup the server checks the bucket (`HeadBucket`). A missing bucket, refused credentials or an unreachable server stop startup with `Unable to open the image storage: S3 bucket "<name>" is not usable: <reason>`; the error never contains the secret. Each S3 call has a 30 second timeout and the SDK default retries. At boot, images whose metadata is missing are read back from the bucket to fill it; when there were some, one log line says how many.
+
+### Moving existing uploads to a bucket
+
+There is no automatic migration and the database does not change: image rows only hold the stored name, so the same names must exist in the bucket. With the site stopped, copy the files under the same names, under `S3_KEY_PREFIX` if you set one, then set `STORAGE_DRIVER=s3` and restart:
+
+```sh
+aws s3 sync ./data/uploads s3://my-bucket/uploads/
+rclone sync ./data/uploads remote:my-bucket/uploads
+```
+
+Keep `UPLOAD_DIR` until you have checked the site. Moving back is the same copy in the other direction.
+
+### Backups
+
+The pre-update backup covers the database only (and `DATA_DIR` state). Neither the update backup nor the data directory includes uploads, so back the bucket up with your provider (versioning, replication) or with `aws s3 sync` / `mc mirror`.
+
+## Database
+
+SQLite is the default and needs nothing but `DB_FILE`. To run against MySQL 8 or MariaDB 11 instead, set `DB_DRIVER=mysql` and the connection variables below. They are only read (and the four required ones only checked) when `DB_DRIVER` is `mysql` or `postgres`. A required variable that is not set stops the server with `Environment variable DB_HOST is not set` (or `DB_USER`, `DB_PASSWORD`, `DB_NAME`).
+
+| Name                           | Default  | Description                                                                                                                      |
+|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------|
+| `DB_HOST`                      | required | Server host name or IP address.                                                                                                  |
+| `DB_PORT`                      | `3306` (`5432` for PostgreSQL) | Server port.                                                                                                       |
+| `DB_USER`                      | required | Database user. It needs full rights on `DB_NAME`, because the schema is created and migrated at startup.                        |
+| `DB_PASSWORD`                  | required | Database password. It is never logged and never appears in an error message.                                                     |
+| `DB_NAME`                      | required | Name of an existing database. The server does not create it.                                                                     |
+| `DB_TLS`                       | `false`  | `false`, `true`, `skip-verify` or `preferred`. Any other value stops the server with an error naming `DB_TLS` and these values. `true` verifies the server certificate; `skip-verify` encrypts without verifying it. |
+| `DB_SSLMODE`                   | `disable` | PostgreSQL only: `disable`, `require`, `verify-ca` or `verify-full`. Any other value stops the server with an error naming `DB_SSLMODE` and these values. Ignored for SQLite and MySQL (use `DB_TLS` there). |
+| `DB_MAX_OPEN_CONNS`            | `10`     | Maximum open connections in the pool. `0` means unlimited.                                                                       |
+| `DB_MAX_IDLE_CONNS`            | `5`      | Maximum idle connections kept in the pool.                                                                                       |
+| `DB_CONN_MAX_LIFETIME_SECONDS` | `300`    | Seconds after which a connection is closed and replaced. `0` keeps connections forever. Keep it below the server's `wait_timeout`. |
+
+A non numeric (or negative) pool value stops the server with an error naming the variable. There is no DSN variable: the connection string is built from the variables above, with `parseTime=true`, `loc=UTC`, `charset=utf8mb4`, `collation=utf8mb4_bin` and `clientFoundRows=true`. Connecting uses a 5 second timeout, so a wrong host, port, password or database name stops startup quickly with `Unable to open the database`, naming the host and port but never the password.
+
+### PostgreSQL
+
+Set `DB_DRIVER=postgres` (or `postgresql`) and the same connection variables, with `DB_PORT` defaulting to `5432` and `DB_SSLMODE` instead of `DB_TLS`. PostgreSQL 16 and 17 are tested. The database must already exist and `DB_USER` needs full rights on the `public` schema, which is the only schema used. The connection string is built with escaping from the variables (a password may contain spaces, quotes, `@` or `/`), sets the session time zone to UTC and a 5 second connect timeout, and the pool variables above apply. A failure to connect stops startup with `Unable to open the database`, naming the host and port but never the password. Usernames and emails compare case-sensitively, as on SQLite. Before an update download RenewCMS writes a logical dump to `DATA_DIR/backups/renewcms-<time>.sql` (the newest 3 are kept); replay it into an empty database with `psql -f`. For routine backups prefer `pg_dump`.
+
+### MySQL settings
+
+Why those settings: tables are created with the `utf8mb4_bin` collation so that usernames and emails compare case-sensitively exactly like in SQLite (`Bob` and `bob` are different users). The collation of `DB_NAME` itself does not matter, but tables that already exist keep the collation they have. `clientFoundRows` makes an update that does not change a row still count as matched, which the invite and purge-settings code relies on. Each session also drops the server's `NO_ZERO_DATE` SQL mode, because the Go driver sends a zero time as `0000-00-00`. The other strict modes stay on.
+
+With MySQL the data directory (`DATA_DIR`) holds update state and backups only. The pre-update backup is a `renewcms-<time>.sql` logical dump (schema and rows, written by RenewCMS itself, no `mysqldump` needed) that keeps the newest 3. If the dump fails, the update download fails with it. The dump holds your data, such as password hashes, but not the connection password.
+
+Relative paths are resolved against the process's working directory. In production, use absolute paths (see [deployment.md](deployment.md)).
+
+For example, `WorkingDirectory=/var/lib/renewcms` with `DB_FILE=./data/renewcms.db` puts the database in `/var/lib/renewcms/data`. Browser-update `--data-dir` must name that directory, because the app reads helper status and update records beside the database. It is not necessarily `WorkingDirectory` or `ReadWritePaths`. Do not change an existing `DB_FILE` merely to match the helper: that could open a different, empty database. See [browser-update setup](deployment.md#browser-updates).
+
+## Activity log retention
+
+The activity log needs no environment variable. Its retention (an age of 30, 90, 365 days or forever, 90 by default, and an optional maximum size in GB, none by default; whichever limit is reached first removes the oldest events) is a setting the owner changes with `PATCH /v1/settings`, and the daily cleanup runs at 03:00 in the server's time zone (`TZ`, or the host's zone).
+
+## Adding a variable
+
+1. Read it in the code where it is needed (infrastructure or `api/`, never `internal/domain`).
+2. Register it in [`cmd/server/main.go`](../cmd/server/main.go): add it to `requiredEnvVars` if it is required (or to `DatabaseRequiredEnvVars` in `internal/infrastructure/config` if only one database driver needs it), or to `envDefaults` if it has a default.
+3. Add it to [`.env.example`](../.env.example) and to the tables above.
+
+Never hardcode a secret, and never commit `.env`.

docs/custom-content-types.md

@@ -0,0 +1,20 @@
+# Custom content types
+
+A content type is a named schema (a key, a name and 1 to 50 fields) stored as one row with the fields as a JSON text column. Entries of every type share one generic table whose `data` column holds a JSON object. No DDL runs at runtime, so creating or changing a type never alters the database schema.
+
+## Icon, built-in types and user lookup
+
+- A content type has an optional `icon`: `null` or a string matching `^[a-z][a-z0-9-]{0,39}$`, validated in the domain (`ErrInvalidIcon`, `400 invalid_icon`) and never checked against a list of known icons. `""` is stored as `null`. `PUT` replaces the icon like the name and the fields, so an absent icon clears it. The column is nullable, so rows stored before it existed read as `null`.
+- `GET /v1/builtin-type` and `GET /v1/builtin-type/{key}` expose a static, read-only catalogue (`internal/domain/builtintype`) of the built-in types `article`, `author`, `site`, `media` and `user` as `key`, `name` and `fields` shaped like content type fields. Owners and admins only. It uses no repository; an unknown key is `404 builtin_type_not_found`. A test checks that every catalogue field key exists in the JSON of the matching entity.
+- `GET /v1/user/lookup?ids=1,2,3` returns `[{id, display_name}]` for any verified user, ordered by id, with the username when the display name is empty. 1 to 100 distinct uint32 ids; anything else is `400`. Unknown ids are omitted.
+
+## Layering
+
+The domain packages `internal/domain/contenttype` and `internal/domain/entry` own the rules: key, name and field validation, entry validation against a schema, the sort whitelist, the page limits and the value equality used by uniqueness. The use cases orchestrate them through the two repositories. The repositories only store and load rows. Entry counting for the "type still has entries" rule lives on the entry repository.
+
+## Known limitations of phase 1
+
+- Uniqueness and schema re-validation are O(n). Checking a unique field loads every entry of the type and compares values in Go, and updating a type with stored entries loads all of them to re-validate. This keeps the SQL portable across SQLite, MySQL/MariaDB and PostgreSQL. The path to fix it is the filterable-fields phase: project the values of unique and filterable fields into an indexed table, so uniqueness becomes an indexed lookup and re-validation can be restricted to the changed fields.
+- Unique values are checked without a transaction, so two concurrent writes of the same unique value can both succeed. A content type key is protected by a unique index, and a violation is reported as `content_type_key_taken` (409).
+- `entry.Repository.DeleteByContentType` is intentionally unused for now. A content type that still has entries cannot be deleted; the method is kept as part of the repository contract for a later cascade.
+- Listing is limited to page 1,000,000 and to page sizes of 100 so that the SQL offset cannot overflow.

docs/deployment.md

@@ -0,0 +1,341 @@
+# Deployment
+
+RenewCMS ships as **one self-contained executable**. It serves:
+
+| Path       | What                                    |
+|------------|-----------------------------------------|
+| `/v1/*`    | JSON API                                |
+| `/healthz` | Liveness check, returns `200 ok`        |
+| `/*`       | The Vue SPA (embedded), with fallback to `index.html` for client-side routes |
+
+Runtime state includes the SQLite database (`DB_FILE`, or a MySQL/MariaDB or PostgreSQL server, see [Using MySQL or MariaDB](#using-mysql-or-mariadb) and [Using PostgreSQL](#using-postgresql)), uploads (`UPLOAD_DIR`, or an S3-compatible bucket with `STORAGE_DRIVER=s3`, see [configuration.md](configuration.md#image-storage)), and update records, staged binaries and backups beside the database. Running a release binary needs no Go, Bun or Node installation. Browser updates additionally require Linux with systemd and the helper setup below.
+
+To run it in a container instead, see [docker.md](docker.md). The published image `git.floriansylvain.fr/fsylvain/renewcms` is upgraded with `docker compose pull && docker compose up -d`. Tags are `vX.Y.Z`, `X.Y.Z`, `X.Y` and `latest` for a stable release, and `vX.Y.Z-<pre>`, `X.Y.Z-<pre>` and the moving `<pre-name>` (`beta`, `rc`) for a pre-release, which never moves `latest`. Maintainers publish with `task docker:publish` after `docker login git.floriansylvain.fr`; there is no CI. See [Maintainer: publishing](docker.md#maintainer-publishing).
+
+## 1. Build
+
+On any machine with the [dev prerequisites](development.md#prerequisites):
+
+```sh
+task build     # this OS/arch → bin/renewcms[.exe]
+task release   # all targets  → bin/renewcms_<version>_<os>_<arch>[.exe]
+```
+
+`task release` also signs the release: it writes `bin/checksums.txt` (SHA-256 of the six binaries) and signs it into `bin/checksums.txt.sig` with an Ed25519 key. It refuses to start, before building anything, unless `RELEASE_SIGNING_KEY` points to the private key file and that key matches the public key committed as `internal/infrastructure/update/release.pub`. The one-time setup is below.
+
+The frontend is built once and embedded into every binary. The binaries are static (`CGO_ENABLED=0`), so a Linux build runs on any distribution. The version comes from `git describe`: tag a release (`git tag v1.2.0`) before building, and the binary logs its version at startup.
+
+### Release signing key (maintainers, once)
+
+1. Run `task release:keygen -- <path>` with a path outside the repository (for example `~/.renewcms/release.key`). The private key is written there and never leaves your machine; keygen refuses a path inside the work tree.
+2. Commit the printed public key as `internal/infrastructure/update/release.pub`. A placeholder key (32 zero bytes) prevents signing. Official releases already embed the project's public key; this setup is for release maintainers, not site operators. Never copy the private signing key to a CMS server.
+3. Export `RELEASE_SIGNING_KEY=<path to the private key>` before every `task release`.
+
+To check a download by hand: `go run ./cmd/releasesign verify checksums.txt`, with `checksums.txt.sig` next to it, then compare the binary's hash with the matching line of `checksums.txt`.
+
+### Update checks
+
+The owner's Settings page asks the release feed for the newest release (see `UPDATE_FEED_URL` in [configuration.md](configuration.md)) and keeps the last result in `update-status.json`, next to `DB_FILE`. Back it up with the rest of the data directory if you like; it is rebuilt by the next check when missing. The Settings page reports a newer version. To install it from the browser, set up [Browser updates](#browser-updates) once on the server. In Docker (`RENEWCMS_CONTAINER=true`) browser updates are not offered; Settings tells the owner to pull a new image instead, see [docker.md](docker.md).
+
+### Update downloads
+
+Once the restart helper is installed (it writes `update-helper.json` next to `DB_FILE`), the owner's Update button downloads the new binary, `checksums.txt` and `checksums.txt.sig` from the release feed host over https only, checks the ed25519 signature and the SHA-256, runs the staged binary with `--version`, copies the database into `backups/` (the last 3 copies are kept) and stages everything under `updates/<tag>/`, all next to `DB_FILE`. The job record is `update-job.json`. Nothing running is replaced and the site is not restarted by the download: the owner's Restart button does that, as described in [Browser updates](#browser-updates). `renewcms --version` prints the build version and exits.
+
+### Browser updates
+
+The owner's Restart button installs a downloaded update, or just restarts the site, without touching the server by hand. The app itself stays unprivileged: the systemd unit below keeps `ProtectSystem=strict` and only the data directory (the directory that holds `DB_FILE`) is writable. The only privileged code is a small helper, the same binary started as `renewcms apply-update` by a systemd service that runs as root.
+
+First install v2.6.0-beta or newer manually, back up the database, uploads and current binary, and confirm the app runs as an unprivileged service user. The binary and its parent directory should be controlled by root. Owners can start updates and restarts; admins have read-only update status.
+
+#### Find the actual database directory
+
+The helper's `--data-dir` must be the directory containing `DB_FILE`. Inspect the relevant settings without printing the configuration's secrets:
+
+```sh
+sudo systemctl show renewcms -p User -p WorkingDirectory
+sudo grep '^DB_FILE=' /etc/renewcms/renewcms.env
+```
+
+| WorkingDirectory | DB_FILE | Correct --data-dir |
+| --- | --- | --- |
+| `/var/lib/renewcms` | `/var/lib/renewcms/renewcms.db` | `/var/lib/renewcms` |
+| `/var/lib/renewcms` | `./data/renewcms.db` | `/var/lib/renewcms/data` |
+
+Leave an existing `DB_FILE` unchanged: changing it can open a different, empty database. Configure the helper to match the existing database instead.
+
+#### Enable the helper
+
+For this guide's absolute database path and port 8080, run:
+
+```sh
+sudo /opt/renewcms/renewcms enable-browser-updates \
+  --service renewcms \
+  --binary /opt/renewcms/renewcms \
+  --data-dir /var/lib/renewcms \
+  --port 8080
+```
+
+Replace these flags with your actual paths and port. For the relative database example above and port 8788, use `--data-dir /var/lib/renewcms/data --port 8788`. The absolute executable path works even when `/opt/renewcms` is absent from sudo's PATH.
+
+Without explicit flags, discovery reads `/etc/systemd/system/renewcms.service` and takes its first `ReadWritePaths` entry as the data directory. It does not resolve `DB_FILE`, so explicit flags are necessary when these directories differ or the unit lives elsewhere. The port comes from `--port`, else `PORT` in the unit's `EnvironmentFile`, else 8080. The helper polls `/healthz` on `127.0.0.1` at that port. It then:
+
+- writes `renewcms-update.path` and `renewcms-update.service` next to your other units in `/etc/systemd/system` (no secret and no environment value goes into them);
+- runs `systemctl daemon-reload` and enables and starts the path unit;
+- writes `update-helper.json` in the data directory last, so the Settings page only offers Update and Restart once everything else worked.
+
+Running it again rewrites the units and the status file to the current values. If a step fails, the units it wrote are removed again and `update-helper.json` is not written.
+
+#### Verify setup and test a plain restart
+
+For the layout above, run these checks, substituting your service user and database directory if different:
+
+```sh
+systemctl is-active renewcms-update.path
+systemctl is-enabled renewcms-update.path
+sudo systemctl cat renewcms-update.service
+sudo -u renewcms cat /var/lib/renewcms/update-helper.json
+```
+
+Expect `active`, `enabled`, an `ExecStart` with the correct paths and port, and readable JSON. Reload Settings as owner. With no update waiting, Restart should appear. Press it, confirm the plain restart dialog, and expect the overlay followed by the site returning and a “Site restarted” message.
+
+Then run:
+
+```sh
+systemctl is-active renewcms
+sudo cat /var/lib/renewcms/update-result.json
+sudo cat /var/lib/renewcms/update-running.json
+sudo journalctl -u renewcms-update.service -n 30 --no-pager
+curl --retry 5 --retry-connrefused --retry-delay 2 -fsS http://127.0.0.1:8080/healthz
+```
+
+Expect an active app service, result `kind: restart` with `outcome: succeeded`, the installed version and a new process in `update-running.json`, and health response `ok`. Check `/healthz` through your public HTTPS hostname too. A brief connection refusal during startup can be transient. The oneshot helper normally becomes inactive after success; the path unit stays active.
+
+#### Install a future update
+
+When a newer signed release exists, check for updates in Settings, read its notes and click Update. The site stays online while the files are downloaded, verified and backed up. Wait for Ready to install, then click Restart and confirm installation. Afterwards, check the version in Settings, public health, the helper journal and `update-result.json`: expect `kind: update` and `outcome: succeeded`.
+
+On the latest release you can test only a plain restart. Test installation, forced rollback and hostile-file cases on an isolated Linux/systemd machine with its own data and service. The helper unit names are fixed, so setting up another instance on the same machine replaces that machine's existing helper configuration.
+
+#### Troubleshooting
+
+- **Restart is missing:** reload Settings, confirm you are owner, and inspect `GET /v1/system/update` in the browser's Network panel. For an idle owner, `can_apply: false` means the app did not detect the helper. Check that `update-helper.json` is beside the actual database and readable by the service user.
+- **Wrong helper directory:** disable the helper with the old `--data-dir`, then enable it with the correct directory and port. Do not change `DB_FILE` to compensate.
+- **Overlay does not clear:** inspect the helper journal, `update-result.json` and `update-running.json` in the actual database directory. Check localhost health on the configured port, then public health through the proxy. Do not cache `/healthz` at the proxy.
+- **Old binary panics on `--version`:** older releases may interpret it as normal startup and require server environment variables. v2.6.0-beta and newer print their version without loading configuration. A separately launched process failing this way does not stop the systemd service.
+- **Download or verification fails:** inspect the app journal. All assets and redirects must use HTTPS on the configured feed host. The release must include the six binaries, `checksums.txt` and `checksums.txt.sig`.
+- **Update rolls back:** check the previous version and helper journal. Automatic rollback restores the binary, not the database; schema changes still require a recovery plan.
+
+#### Disable the helper
+
+Use the same database directory you supplied when enabling it:
+
+```sh
+sudo /opt/renewcms/renewcms disable-browser-updates \
+  --service renewcms \
+  --data-dir /var/lib/renewcms
+```
+
+This stops and disables the path unit, removes both unit files and `update-helper.json`, and runs `systemctl daemon-reload`. The restart request, result, staged files and backups stay. `can_apply` becomes false: Settings shows “Not prepared” when an update is available, or “You're up to date” without Restart otherwise.
+
+How it works: pressing Restart makes the app write `update-restart-request.json` in the data directory. The path unit notices it and starts the helper, which deletes the request, checks the staged files again, installs the update, restarts the service and waits up to 60 seconds for the site to answer `/healthz` and for the new process to write `update-running.json`. The helper writes its outcome to `update-result.json`; the Settings page reads it. The technical reason of a failure goes to the journal only (`journalctl -u renewcms-update`).
+
+Files in the data directory:
+
+| File | Written by | What |
+|------|------------|------|
+| `update-restart-request.json` | the app | The request: `kind` (`update` or `restart`), `tag` (updates only), `requested_at`, `requested_by`. The helper deletes it first. |
+| `update-result.json` | the helper | The outcome: `running`, `succeeded`, `rolled_back` or `failed`, with `kind`, `tag`, `from_version`, `started_at`, `finished_at`. It stays until the next download or restart. |
+| `update-helper.json` | `enable-browser-updates` | Marks browser updates as set up (`version`, `service`, `binary`, `data_dir`, `installed_at`). |
+| `update-running.json` | the server, at every start | `version`, `pid` and `started_at` of the running process. The helper uses it to tell a new process from an old one. |
+
+What is supported and what is not:
+
+- Linux with systemd only. Not Windows, macOS, Docker or other init systems: there the command refuses with a clear message and the Settings page keeps showing "Not prepared".
+- Before the swap the helper copies the staged files into a private temp directory, checks the signature and the SHA-256 on that copy and installs the copy. It refuses symbolic links under `updates/` and on the request file.
+- The previous binary is kept as `<name>.previous` next to the binary, and the update download keeps a database backup in `backups/`.
+- If the new version does not come up within 60 seconds, the helper puts `<name>.previous` back, restarts the service and records `rolled_back`. If even that fails the result is `failed` and the journal says so loudly.
+- A plain restart (no update waiting) restarts the service the same way and records `succeeded` or `failed`; no binary is replaced.
+- Only the owner can press Restart. The site is unavailable for about 10 seconds.
+
+#### Verification status
+
+A real v2.6.0-beta plain browser restart was confirmed on Linux/systemd on 2026-10-02: the path unit triggered the helper, a new server process started, the result was `succeeded`, and public health returned `ok`. Real signed installation, forced rollback and adversarial filesystem checks remain unverified. The manual cases are listed in [the restart QA procedure](../features/updates_restart_helper.qa.md).
+
+## 2. Lay out the server
+
+The following is a suggested layout for Linux:
+
+```
+/opt/renewcms/renewcms          the binary
+/etc/renewcms/renewcms.env      configuration (chmod 600, owned by root)
+/var/lib/renewcms/              data: renewcms.db, uploads/  (owned by the service user)
+```
+
+```sh
+sudo useradd --system --home /var/lib/renewcms --shell /usr/sbin/nologin renewcms
+sudo install -d -o renewcms -g renewcms /var/lib/renewcms
+sudo install -D -m 755 bin/renewcms_v1.2.0_linux_amd64 /opt/renewcms/renewcms
+sudo install -D -m 600 /dev/null /etc/renewcms/renewcms.env   # then edit it
+```
+
+`/etc/renewcms/renewcms.env` looks like this (see [configuration.md](configuration.md) for every variable):
+
+```sh
+ENVIRONMENT=production
+PUBLIC_URL=https://cms.example.com
+PORT=8080
+DB_FILE=/var/lib/renewcms/renewcms.db
+UPLOAD_DIR=/var/lib/renewcms/uploads
+JWT_SECRET=<openssl rand -hex 32>
+SMTP_LOGIN=noreply@example.com
+SMTP_SENDER=noreply@example.com
+SMTP_PASSWORD=...
+SMTP_HOST=smtp.example.com
+SMTP_PORT=465
+```
+
+## 3. Run it as a service (systemd)
+
+`/etc/systemd/system/renewcms.service`:
+
+```ini
+[Unit]
+Description=RenewCMS
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+User=renewcms
+Group=renewcms
+WorkingDirectory=/var/lib/renewcms
+EnvironmentFile=/etc/renewcms/renewcms.env
+ExecStart=/opt/renewcms/renewcms
+Restart=on-failure
+# RenewCMS shuts down gracefully on SIGTERM (up to 10 s to finish requests and close the DB)
+TimeoutStopSec=15
+
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+ReadWritePaths=/var/lib/renewcms
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```sh
+sudo systemctl daemon-reload
+sudo systemctl enable --now renewcms
+journalctl -u renewcms -f
+curl -fsS http://localhost:8080/healthz
+```
+
+On Windows, register the binary as a service with a wrapper such as [NSSM](https://nssm.cc/) or [WinSW](https://github.com/winsw/winsw), and set the same environment variables.
+
+## 4. Put HTTPS in front
+
+With `ENVIRONMENT=production` the auth cookie is `Secure`, so **the site must be served over HTTPS**. Terminate TLS in a reverse proxy and keep RenewCMS on localhost.
+
+[Caddy](https://caddyserver.com) handles certificates automatically:
+
+```caddyfile
+cms.example.com {
+	reverse_proxy localhost:8080 {
+		header_up X-Real-IP {remote_host}
+	}
+}
+```
+
+nginx:
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name cms.example.com;
+    # ssl_certificate ... (e.g. certbot)
+
+    client_max_body_size 20m;   # image uploads
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+If RenewCMS runs on the same host as the proxy, consider firewalling port 8080.
+
+Either way, set `TRUSTED_PROXIES` (see [configuration.md](configuration.md)) to the proxy's own address as seen by RenewCMS, typically `127.0.0.1` when the proxy and RenewCMS share a host, so the login/password-reset rate limiter honors the forwarded client IP instead of the proxy's own address.
+
+### Security headers
+
+RenewCMS sends `Content-Security-Policy` (including `frame-ancestors 'none'`), `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` and `Cross-Origin-Opener-Policy` itself, so the proxy doesn't need to add them. With `ENVIRONMENT=production` it also sends `Strict-Transport-Security: max-age=31536000` (browsers ignore it over plain HTTP, so serve the site over HTTPS only). Don't add the same headers in the proxy, or they will be duplicated.
+
+The CSP serves fonts from `'self'` only (the SPA bundles its fonts, so no visitor IP address is sent to a font CDN) and allows `https:` images, because articles may embed remote images. `style-src` keeps `'unsafe-inline'` for the article editor; `script-src` is `'self'` only.
+
+## Using MySQL or MariaDB
+
+SQLite is the default. To use an existing MySQL 8 or MariaDB 11 server instead, create an empty database and a user with full rights on it, then set in `/etc/renewcms/renewcms.env`:
+
+```sh
+DB_DRIVER=mysql
+DB_HOST=db.example.com
+DB_USER=renewcms
+DB_PASSWORD=<generated password>
+DB_NAME=renewcms
+DB_TLS=true
+DATA_DIR=/var/lib/renewcms
+```
+
+`DB_FILE` is then ignored. `DATA_DIR` is where update state, staged updates and backups live, so give it the same value as the helper's `--data-dir` (see [browser updates](#browser-updates)). Use `DB_TLS=true` (or `preferred`) whenever the server is not on the same host. Every variable is described in [configuration.md](configuration.md#database). The schema is created and migrated at startup, so the first start on an empty database needs nothing else.
+
+## Using PostgreSQL
+
+To use an existing PostgreSQL 16 or 17 server, create an empty database and a user with full rights on its `public` schema, then set in `/etc/renewcms/renewcms.env`:
+
+```sh
+DB_DRIVER=postgres
+DB_HOST=db.example.com
+DB_USER=renewcms
+DB_PASSWORD=<generated password>
+DB_NAME=renewcms
+DB_SSLMODE=require
+DATA_DIR=/var/lib/renewcms
+```
+
+`DB_FILE` is then ignored, and `DB_PORT` defaults to `5432`. `DATA_DIR` is where update state, staged updates and backups live, so give it the same value as the helper's `--data-dir`. Use `DB_SSLMODE=require` (or `verify-full`) whenever the server is not on the same host. Every variable is described in [configuration.md](configuration.md#database). The schema is created and migrated at startup. Moving an existing SQLite site is a manual procedure like the MySQL one below, and RenewCMS writes a logical `.sql` dump to `DATA_DIR/backups` before each update download.
+
+### Moving an existing SQLite site to MySQL
+
+There is no migration tool. The manual procedure, with the site stopped:
+
+1. Take a backup of the data directory (database file and uploads).
+2. Start RenewCMS once on the empty MySQL database so it creates the schema, then stop it.
+3. Export the rows from the SQLite file with `sqlite3 renewcms.db .dump`, keep only the `INSERT INTO` statements for `articles`, `images`, `users`, `invites`, `api_keys` and `purge_settings`, and import them into MySQL. Quoting and date formats differ between the two engines, so check a sample first: SQLite writes times such as `2026-01-02 03:04:05.123456789+00:00`, and the `+00:00` suffix must be removed for MariaDB and older MySQL versions. An unset time (`0001-01-01 00:00:00`) is valid as it is in MySQL and is read back as unset.
+4. Copy `uploads/` to the new `UPLOAD_DIR`, set `DB_DRIVER=mysql` and the connection variables, and start the service.
+
+Keep the SQLite file until you have checked the site.
+
+## Backups
+
+With MySQL, MariaDB or PostgreSQL, back the database up with your server's own tools (for example `mysqldump --single-transaction` or `pg_dump`), plus the uploads directory. RenewCMS also writes a logical dump to `DATA_DIR/backups` before each update download. The rest of this section is about SQLite.
+
+Everything worth backing up is under the data directory. Take a consistent SQLite copy while the service is running:
+
+```sh
+sqlite3 /var/lib/renewcms/renewcms.db ".backup '/backups/renewcms-$(date +%F).db'"
+rsync -a /var/lib/renewcms/uploads/ /backups/uploads/
+```
+
+Alternatively, run `systemctl stop renewcms`, copy the directory, and run `systemctl start renewcms`.
+
+## Upgrading
+
+1. Back up (see above). The schema is migrated automatically at startup (GORM `AutoMigrate`), and there is no down-migration.
+2. Replace `/opt/renewcms/renewcms` with the new binary.
+3. Run `sudo systemctl restart renewcms`, then check `journalctl -u renewcms` for the new version line.
+
+To roll back, put the previous binary back and restore the database backup if the schema changed.

docs/design/README.md

@@ -0,0 +1,156 @@
+# RenewCMS design pass 2
+
+Nuxt UI v4 back-office. Tokens only, no raw hex (brand mark excepted). Light and dark. 1440×900 and 390×844. Radius 0.
+
+## Boards
+- `RenewCMS Screens Back-office.dc.html`: every back-office screen, Settings → Media (variants, cache), and the group "States matrix: controls". Frames: `AppFrame` (shell), `DirectoryFrame` (Sites and Authors), `ActivityFrame`, `MediaFrame`, `VariantsFrame`, `IntegrationPage`, `IntegrationSearch`, `IntegrationImages`, `CodeSnippet`, `StatesMatrix`.
+- `RenewCMS Screens Auth.dc.html` (7 groups, 50 states), `RenewCMS Screens API keys.dc.html` (12 states).
+- `RenewCMS Prototype.dc.html`: updated to match (title-only New article, no body limit or counter, neutral count, pagination, link button, AppFrame's mobile drawer).
+- Unchanged: Foundations, Components, Handoff, Directions and Emails boards.
+
+## Pass 3: sites and authors (revised)
+Roles, decisions and the slice order are in `sites-authors-slices.md` (Sites and Authors) and `seo-slices.md` (SEO).
+
+Back-office board groups: Sites, Sites: form, Sites: delete, Authors, Authors: form, Authors: delete, Editor: site and authors, Profile: author profile, Articles: sites and authors. Plus tables: decisions to confirm (13 rows, 5 marked Decided), deviations, API and errors (with the 403 rows), components, accessibility, copy per state.
+- Roles: only creating, editing, deleting and setting the default site are owner only (no sidebar entry or Publishing card for others, 403 page on a direct link). Anyone who can edit an article can set its site and read the site list. Authors: owner and admin manage; other roles read-only, and any role can create and edit their own author (user link locked, no delete).
+- The site key is immutable: read-only with a lock in the edit form; the warning state and dialog are gone.
+- The "Author profile" card is drawn in every existing Profile frame. The "Site and authors" section shows collapsed in every existing Editor frame that has the details sidebar (39 already did; the Loading frame now shows the header with a skeleton summary). The Not found frame has no editor, and on mobile the section is inside the Details sheet. The dedicated groups keep only the feature-specific states.
+- Shared pieces (list, slide-over, delete-with-reassign dialog, slug field, media field) are defined once in `DirectoryFrame`, used by Sites and Authors. The Profile card is defined once in `AppFrame`.
+- States trimmed from 87 to 68 (Sites 9, Sites: form 7, Sites: delete 3, Authors 8, Authors: form 11, Authors: delete 6, Editor: site and authors 16, Profile: author profile 5, Articles: sites and authors 3). Dropped: in-progress and done variants (covered by the button loading pattern and the confirm state's trigger), per-error URL variants, the site picker (same picker as the avatar), manual slug override, long names (merged into Many authors), per-field duplicates. The blocked-delete dialog is one frame, "Server fallback (409)".
+- Only individual states that render a relative time or a countdown carry the "Clock-sensitive" tag (13 states, listed in states.md). No Home or Articles frame is tagged as a whole.
+- Role-restricted variants drawn: read-only Authors list and detail, hidden Sites entry, Sites 403, own-author edit.
+
+## Pass 4: custom content types
+Board `RenewCMS Screens Schema.dc.html` (frames: `SchemaFrame`, mounted in `AppFrame`): 11 groups, 99 states. 1 Schema list 7, 2 Schema builder 19, 3 Review and delete 9, 4 Field types 7, 5 Content and entry list 12, 6 Entry editor 23, 7 Relations 5, 8 Permissions 2, 9 Export and import 3, 10 Media picker for a field 8, 11 Media library usage 4. The Media field type (pass 5) is specified in `media-field-changes.md`; the exact copy and measurements are there, and the boards are the visual reference. Plus tables: scope, routes, new components with their Nuxt UI mapping, errors to copy, needs backend (4 rows), decisions to confirm, accessibility. Specs: screens/schema.md, content.md, entry.md, schema-later.md, media.md, media-picker.md, and media-field-changes.md for the Media field type.
+- AppFrame gains a Schema item (owner and admin) and a Content group (sidebar and mobile drawer). Nothing else in AppFrame changed.
+- Backend gaps still open: built-in types and fields, display names for created_by and updated_by, a type icon, per-change entry counts.
+- Not done: Back-office and Prototype boards were not compared visually after the sidebar change (see Checks below).
+
+## Specs
+routes.md · components.md · states.md · foundations.md · change-list.md · activity-spec.js · screens/*.md (24 files)
+
+## Status
+| Section | Status |
+|---|---|
+| A1 Activity export | Done: CSV only, synchronous; progress state removed; JSON proposed |
+| A2 Pagination `page`/`size` | Done in frames, routes.md, change-list.md |
+| A3 Unknown variant and unsupported parameter | Done: both 400 bodies in the Responses table |
+| A4 New tokens | Done: foundations.md table |
+| A5 screens/*.md | Done: 22 files, copy generated from the board source |
+| B1 Editor link | Done: 11 states |
+| B2 Duplicates | Done for sidebar, topbar, drawer, code block, modal geometry; see Not done |
+| B3 CodeSnippet | Done |
+| B4 Overlays | Done |
+| B5 Prototype | Done |
+| B6 Contrast and states matrix | Done for the pairs listed; matrix drawn |
+| B7 Consistency sweep | Done for the roles listed |
+| B8 Copy glossary | Done by search; not every line re-read |
+| B9 Media and picker | Badge added; Media pagination drawn (9 states); filter, sort and size not folded in |
+| B10 "proposed" labels | Only article pagination and JSON export |
+
+## State counts (Back-office board: 341 before pass 3, plus 68 for sites and authors = 413)
+| Group | States |
+|---|---|
+| Boot | 1 |
+| Home | 10 |
+| Articles | 14 |
+| Articles: pagination | 11 |
+| New article | 5 |
+| Editor | 41 |
+| Media | 56 |
+| Media picker | 13 |
+| Integration | 8 |
+| Activity | 9 |
+| Activity: filter cards | 10 |
+| Activity: export | 15 |
+| Activity details | 6 |
+| My activity | 3 |
+| Users | 17 |
+| Settings | 25 |
+| Settings: Media cleanup | 9 |
+| Purge dialog | 8 |
+| Purge results | 2 |
+| Media duplicates entry | 2 |
+| Settings: Retention | 6 |
+| Profile | 13 |
+| Global | 4 |
+| Integration: images | 9 |
+| Settings navigation | 5 |
+| Variants list | 12 |
+| Add edit variant | 11 |
+| Media library (variants) | 6 |
+| Image detail | 8 |
+| Cache panel | 10 |
+| Editor picker | 5 |
+
+Back-office total 341 (pass 2 groups, table above) + 68 (sites and authors) + 4 (Media: used elsewhere) = 413. Auth board 50 (Log in 9, Register 6, Pending 6, Verify 6, Accept invite 10, Forgot password 6, Reset password 7). API keys board 12. Total 481 states; every one has a desktop and a mobile frame, and the theme switch gives light and dark. The matrix has 24 control rows, 5 states on desktop and 4 on mobile (no hover). screens/*.md list the states of the pass 2 groups and the 68 pass 3 states.
+
+## Fixes applied (pass 2)
+1. Activity export dialog: removed the 42% progress bar, the "large export" state, the server-job copy and the "ready later" toast; added "Preparing download…" (indeterminate), "Download started", failed, nothing to export, 403; CSV only, with one proposed JSON state.
+2. Export dialog and menu copy now match the implemented endpoint (current view with filters, all with optional range).
+3. Articles pagination used `per_page`, sizes 10/25/50, default 10, 32 pages. Now `page`/`size`, 5/25/50/100, default 25, 13 pages; frames, route, URL examples and the change list updated.
+4. The Integration responses table now shows both 400 bodies, `unknown_variant` and `unsupported_parameter`.
+5. `--rc-sand` and `--rc-on-sand` (and the other `--rc-*` tokens) documented as new tokens with light and dark values and their uses.
+6. Raw colours removed from frames: crop handles and mask, tooltip, transparency checker, drag-drop text, selected-row text in MediaFrame, hex in the Prototype. Only the brand mark keeps hex.
+7. ActivityFrame, MediaFrame and VariantsFrame sidebars, topbars and (Variants) mobile drawer deleted; they render inside AppFrame. Activity now follows the sidebar order (Users, Activity, Integration, Settings).
+8. Prototype's own mobile drawer (Home, Articles, Users, Integration only) replaced by AppFrame's drawer.
+9. All code blocks on Integration (auth example, endpoint examples, error response), the base URL, the image URL builder and the one-time API key use CodeSnippet; the three older block styles are gone. CodeSnippet tabs changed from sand pills to the underline style used by tabs elsewhere.
+10. Variant form: mobile full page replaced by a 92% bottom sheet with grabber and close ×; back arrow removed.
+11. Dialog geometry unified (140 px top offset on desktop, flush bottom sheets with grabber on mobile, header 20 24 0, footer secondary left and primary right, close × 44 px on mobile). Changed: Media and Variants dialogs (mobile inset), Activity export (centered, header bar, 480 wide), API keys dialogs (border, 18 px title, 44 px buttons, 120 px offset).
+12. Current page in the paginator: border `--ui-primary` instead of sand (was 1.3:1).
+13. Page padding 24/16 everywhere (was 32 and 24); card padding 16 (was 16 and 20); section gap 16 (was 16, 20, 28); page title 20/28 (was 28/36, 24/32, 20/28); stat figure 24/32; card title 15/24; inputs 32/44 (were 40); one 13 px icon became 14; toast width 356 (was 360, 372).
+14. Copy: "Removed N …" in activity lines became "Deleted N …"; export titles and footers per the glossary.
+15. Media screen: variant count badge added to grid card, list row and mobile row, matching the Variants board.
+16. Editor toolbar on mobile was a cut-down 9-button subset; it now has the full toolbar with sideways scroll and edge fades.
+17. Editor words and characters show "0 words · 0 characters" for a new empty article (was a fallback sample count).
+
+## Defaults chosen
+- Slide-over rule: only forms with a live preview and record details; on mobile always a 92% bottom sheet.
+- Hover, active, disabled and focus tokens for the matrix (components not specified before): primary hover `--ui-text`, active `--ui-text-toned`; destructive hover opacity 0.85 and active 0.75; disabled 40% (rows 55%).
+- Article pagination: Shipped shapes: the article list body is {items, total, page, size, counts}; the media list body is an array with the total in `X-Total-Count`. Users and authors follow their own routes (see routes.md).
+- The Remove action in the link popover has no confirmation; undo restores the link.
+- The link button is disabled when an image is selected.
+- The tooltip text is "Insert link (Ctrl+K)" and "Insert link (⌘K)" on macOS.
+- Mobile toolbar scrolls sideways; no wrap, no overflow menu.
+- Selected nav items keep the sand fill plus weight 500 and `aria-current` (the fill alone is 1.3:1 in light).
+- Syntax colouring dropped from code samples (one rendering).
+- Export "Download started" offers only Close.
+- New article keeps the title counter "n / 200" (title is limited to 200); the body has no limit and no counter.
+- Page title 20/28, page padding 24/16, card padding 16 (foundations.md).
+- Activity position in the sidebar follows AppFrame.
+- The Prototype shows a toast "Not in this prototype" for sidebar items it has no screen for (Media, Activity, Settings).
+
+## Checks run
+- Opened `RenewCMS Screens Back-office.dc.html` in the preview: it loaded, 38 sections rendered, and I read the DOM of the Activity, Export, Media, Variants, Editor, Integration, Pagination, Picker, Editor picker and States matrix groups to confirm the frames render text and the sidebar. I did not read the console.
+- Computed the contrast table from token values with a script.
+- Searched frames and boards for raw hex and rgb values (only token definitions on the board roots and the brand mark remain), for exclamation marks, Remove and Delete, Update and Save, and per_page.
+- Generated screens/*.md and counted states from the board source; the counts equal the DOM counts for the Back-office board.
+
+## Not done
+- Console errors on the Auth, API keys, Prototype, Foundations and Components boards were not read by me. The delivery check covers the Back-office board; the other boards use the changed frames (AppFrame, ApiKeysPage, AuthCard, MediaFrame) and may need a look.
+- Light and dark were checked for the Back-office board by reading DOM only; I did not view the screenshots of each state at 1440 and 390, so visual regressions from the shell change (slot mode) are possible.
+- Media screen: the "With variants / Without" filter, the "Largest total size" sort and a total-size column exist only on the Variants board states; they are not folded into the Media toolbar.
+- Media picker tiles and the Editor picker were not compared field by field.
+- Duplicated implementations that look alike are not merged in code: toasts (5), badges (2), empty states (2), modal shells (4). Only their visuals were aligned.
+- Hover, active and focus-visible are drawn once in the matrix; screens do not redraw them. Hover and active tokens for destructive buttons use opacity, not a token.
+- Contrast was not computed for every hover and active background, only the pairs listed in foundations.md.
+- The glossary pass was a search for known patterns, not a line-by-line read of every string. Titles in Title Case were not searched.
+- The Components, Handoff and Foundations boards were not updated to mention the new tokens, CodeSnippet or the matrix.
+- Integration still lists "max 10000" for article bodies, as the backend does today (change-list item 11).
+- The sandbox cannot export; no files were bundled.
+
+## Pass 5: roles and permissions
+Board `RenewCMS Screens Roles.dc.html` (frame `RolesFrame`, data `roles-spec.js`): 16 groups, 96 states, all Available now (pass 6 added groups 12 to 15 and changed groups 5, 8 and 9; see change-log-roles-sync.md). Spec `screens/roles.md`; additions in components.md, states.md, routes.md, change-list.md. The Permissions grid is folded into the role editor and `/settings/permissions` is retired. Writer frames use AppFrame's existing restricted `user` navigation. Not done: AppFrame itself is unchanged, so the Back-office board still shows owner/admin/user nav; Schema board group 8 (Permissions) should be marked superseded.
+
+The Schema board group 7 (Relations) now has 4 states; the Integration page and the Activity category filter follow the roles sync (see `change-log-roles-sync.md`).
+
+## Sync notes (app sync)
+- Back-office board: +4 Media states (Used elsewhere: avatar, site, both, none). Roles board: +6 states (group 12b Remove user).
+- Pagination: articles return {items, total, page, size, counts}; media returns an array with X-Total-Count.
+- Event names follow the backend: role.create, role.edit, role.delete, role.reassign, user.change_role, user.transfer_ownership, user.remove.
+- Counts above include the Media (+4) and Roles (+6) states only. States added this round to the Editor, Articles, Sites, Authors, Profile and Schema groups are on the boards and in the screens files, and are not yet recounted here.
+
+## Pass 7: account self-service (email, export, delete)
+Board `source/RenewCMS Screens Account.dc.html` (33 states: change email 14, export 9, delete 10), Auth board groups "Verify new email" (7) and "Account deleted" (1), four email templates in `source/emails/` (previews on the Emails board). Specs: `screens/account.md`, `emails.md`, `routes.md`, `components.md`, `states.md`. Frames: `source/AccountCards.dc.html` (new; copy in `source/account-copy.js`), `AppFrame.dc.html` (Profile hooks, modal list, warning, link and disabled confirm). Every Profile frame on the other boards shows the new cards in their default state. English only.
+Decided: authored content is anonymized to "Deleted user"; email-change link 2 hours; export link 24 hours, one export per 15 minutes; direct download is the primary export flow, the emailed link is the documented alternative; the export-ready link needs a logged-in session; "last administrator" counts Owner; a change request for an address already in use answers like success; the account-deleted email goes to the address the account had.
+Not done: Foundations and Components boards and the Prototype are not updated. The 15-minute rate-limit state is clock-sensitive (frozen clock 09:41) and is skipped by `task visual:check`.

docs/design/change-list.md

@@ -0,0 +1,122 @@
+# Change list for implementation (status after pass 2; SEO round drawn; cleanup round drawn)
+
+## Cleanup round
+
+1. Editor: site and authors, "Create author" states (4 states, desktop and mobile): the mobile dialog sat under the Details sheet (z-index 50 against 55) and was hidden. It now stacks above the sheet (z-index 60), as the SEO panel does. Full-width bottom sheet with grabber, same fields, Cancel left and "Create author" right (Cancel below on mobile, as the other mobile dialogs). Frame: `DirectoryFrame.dc.html`. The four states share the fix: dialog, "for me", slug taken, failed.
+2. Integration, "6. Errors": the 403 row gets the muted note "Site SEO defaults are owner only. Article SEO fields need only the right to edit the article." The row below shifts down by the wrapped note height (two 18 px lines desktop, three mobile, plus the 2 px row gap). The old inline parenthetical with the same sentence in the 403 cause text was removed, so it isn't said twice. Frame: `IntegrationPage.dc.html`.
+3. Integration, sitemap errors: 404 now shows the body `site_not_found` in code style (was "Site not found"); 400 now shows the generic body-mismatch text used by the other routes (was "Invalid page or size.").
+4. New groups on the Back-office board: "Sites: pagination" and "Authors: pagination", 10 states each (20 states, every one desktop and mobile; light and dark by the theme switch). Back-office total 409 → 429. Same pager as Articles and Media, sizes 5, 25, 50, 100, default 25 (no difference to report). One deviation: on a single page the page-size select is hidden and only "N sites" or "N authors" remains.
+5. Specs: screens/sites.md, screens/authors.md (pager states, URL rules, out-of-range fallback), screens/integration.md, states.md (pagination states, three HTTP rows), components.md (single-page variant, no new component), routes.md (Sites pagination in the URL).
+
+**Backend assumptions to confirm.** GET /v1/site/ takes `q`, `page`, `size` and returns `X-Total-Count` (it returns every site today). GET /v1/author/ gets `page`, `size` and `X-Total-Count` (it has `q`).
+
+**Open points.**
+- Sites has no search field. The two states that need one (empty after search, search resets to page 1) draw the Authors field on Sites with "Search by name or key". Drop those states if you don't want search on Sites.
+- Stale copy found, not changed: GET /v1/article/ on Integration still shows the 400 caption "Invalid page or size." while every other route, and now the sitemap, uses the body-mismatch text. The 404 row of the Errors table still lists only the four resource messages and doesn't mention `site_not_found`. The existing Sites and Authors "Default" frames don't draw the count line. README.md state counts and the "Pagination" notes were not updated (outside this round).
+
+## SEO round: decisions (frames drawn)
+
+**Placement.** A "Search and sharing" section sits under "Site and authors" in the Editor sidebar and in the mobile Details sheet. It is collapsed by default, shows a one-line summary ("Ready", "2 suggestions" or "Hidden from search") and is remembered per browser like Site and authors. It holds only the slug, the full URL and three actions: "Edit search and sharing", "What the frontend gets" and the suggestion list. The fields and live previews open in a slide-over (desktop) or a 92% bottom sheet stacked over the Details sheet (mobile), because the 280 px sidebar is too narrow for previews and the slide-over rule already covers forms with a live preview. The API preview is a 720 px dialog (desktop) or a bottom sheet (mobile).
+
+**Principles.** RenewCMS does not render pages or inject meta tags. Every field is optional and the UI shows its fallback. No scores. Suggestions never block saving or publishing; publishing is allowed regardless. Suggestions are dismissible per article.
+
+**Fallback chain (resolved server-side, shown in the UI).**
+| Output | Order |
+|---|---|
+| title | seo_title, then article title; site title_template applied last |
+| description | seo_description, then excerpt, then first sentence of the body, then site default_description |
+| image | og_image_id, then cover_image_id, then site social image |
+| canonical | canonical_url, then site base_url + "/" + slug |
+| robots | noindex true gives "noindex, nofollow"; otherwise site default_robots |
+| og/twitter title and description | social_title, social_description, then the resolved values above |
+
+**Soft ranges (counters, never blocks).** Meta title 30–60 characters; description 70–160; slug "very long" above 75 characters. Counter turns neutral-warning (`--ui-warning`) outside the range, never red.
+
+**New article fields (PATCH /v1/article/{id}, all optional, snake_case).** `slug`, `excerpt` (max 300), `seo_title` (max 120), `seo_description` (max 320), `cover_image_id`, `cover_image_alt` (max 200; the cover is "ready" only with alt text), `social_title`, `social_description`, `social_image_id`, `canonical_url` (absolute https URL), `noindex` (boolean; only sets a flag in the API, it doesn't change visibility), `seo_dismissed` (string[] of suggestion codes). Slug: lowercase letters, numbers, hyphens; unique per site; 409 `slug_taken` with `suggestion` ("<slug>-2"); auto-generated from the title until edited.
+
+**New site fields (PATCH /v1/site/{id}, owner only).** `site_name`, `title_template` (default "%title% | %site%", must contain %title%), `default_description` (max 320), `social_image_id` (existing), `default_robots` ("index" | "noindex"; existing as robots).
+
+**New endpoints.**
+- `GET /v1/article/{id}/seo`: resolved object, public for online articles, 404 for drafts to anonymous callers. Shape: `{ title, description, canonical_url, robots, og: { type, title, description, image, image_alt, url, site_name, locale }, twitter: { card, title, description, image, image_alt }, image: { url, alt, source }, authors: [{ name, url, same_as: [] }], published_at, modified_at, fallbacks: { title, description, image, canonical }, json_ld }`. `json_ld` is a ready Article object (headline, description, image, author[] with name, url and sameAs from author profile URL and social links, datePublished, dateModified, mainEntityOfPage).
+- `GET /v1/site/{key}/sitemap?page=&size=`: published URLs only, total in `X-Total-Count`. Items: `{ url, modified_at, noindex }`. Decision: yes, shown on Integration under "Search and sharing" with a copy button; noindex articles are included with the flag so the frontend can skip them.
+- `GET /v1/article/?seo=ready|suggestions|hidden`: filter behind "Needs attention" (suggestions) with `seo_status` and `seo_suggestions` (count) added to list items.
+
+**Articles list.** Quiet indicator inside the Status cell (and under the title on mobile cards): nothing when ready, a lightbulb chip "N" for suggestions, an eye-off chip "Hidden" for noindex. Toolbar gets a "Needs attention" toggle next to search; tabs and counts are unchanged. It behaves the same on a single-site install (independent of the Site filter, which stays hidden).
+
+**Authors.** No change to the Authors screen. Profile URL (website) and social links feed `authors[].url` and `same_as`, and JSON-LD `author[].sameAs`; the API preview shows them.
+
+**Permissions.** Anyone who can edit an article edits its SEO fields. Only the owner edits site SEO defaults. 401 and 403 rows join the existing HTTP table: 403 `owner_only` on Site SEO fields, 401 on a missing session.
+
+**Left out on purpose.** Keyword scoring and focus keywords, readability scores, redirects management, schema types beyond Article, hreflang, robots.txt and sitemap rendering (RenewCMS only provides data), automatic image generation for social cards.
+
+**Open questions.**
+1. Is `slug` immutable after first publish, or can it change (and break URLs with no redirects)?
+2. Does the API return the SEO object for drafts to authenticated callers (for frontend previews)?
+3. Should noindex articles be excluded from the sitemap endpoint instead of flagged?
+4. Is title_template applied by the API (resolved title) or only returned for the frontend to apply?
+5. Backfill: generate slugs for existing articles from their titles at migration, with `-2` suffixes on conflicts?
+6. Should excerpt be exposed in the list payload as the article teaser?
+
+**Status.** Frames drawn on the Back-office board (groups: Articles: search status, Editor: search and sharing, Editor: what the frontend gets, Sites: SEO defaults), Integration page group added, specs updated. Placement rationale: the sidebar holds only the summary, address and suggestions because it is 280 px wide; previews and fields need a slide-over.
+
+
+Ordered by implementation dependency: tokens and shell first, then shared components, then screens. "Frontend only" means no backend work is needed.
+
+| # | Screen | Change | Done in design? | Needs backend (yes/no, what) | Needs new tokens or components | Frontend only |
+|---|---|---|---|---|---|---|
+| 1 | All | Add the `--rc-*` tokens (sand, on-sand, four soft grounds, overlay, two shadows) to the app CSS, light and dark (foundations.md) | Yes | No | 9 new tokens | Yes |
+| 2 | All | One sidebar, topbar and mobile drawer; Settings parent and child selected states; Activity sits between Users and Integration | Yes | No | NavItem, NavGroup | Yes |
+| 3 | All | Overlay pattern: dialog (desktop) and bottom sheet (mobile); slide-over only for the variant form and record details; footer secondary left, primary right | Yes | No | Modal wrapper rules (components.md) | Yes |
+| 4 | All | CodeSnippet is the only code block (Integration, Images, API keys, base URL, image URL) | Yes | No | CodeSnippet | Yes |
+| 5 | All | Copy glossary pass (Delete vs Remove, Save vs Update, toast phrasing) | Yes, by search; not every line re-read | No | None | Yes |
+| 6 | Settings | "Media" card with "Manage image variants" and "Cache usage" | Yes | No | MediaLinksCard | Yes |
+| 7 | Media, picker | Variant count badge on grid, list and mobile rows | Yes | No (variant counts already come with GET /v1/media?variants=) | Badge "N variants" | Yes |
+| 8 | Media | "With variants / Without" filter and "Largest total size" sort in the Media toolbar | Drawn on the Variants board only, not folded into the Media screen | No (GET /v1/media?variants=&sort=total_size exists) | None | Yes |
+| 9 | Image variants | Variant form as slide-over (desktop) and tall sheet (mobile) | Yes | No | None | Yes |
+| 10 | New article | Title only. Body removed from the modal; the editor opens straight away | Yes | Maybe: confirm `POST /v1/article/` accepts an empty `body` (it is "required" today); otherwise the frontend sends an empty string | NewArticleModal | Yes if empty body is accepted |
+| 11 | Editor | Remove the 10,000 character limit, counter, limit and over-limit states; neutral count | Yes | Yes: remove the body length validation on `POST /v1/article/` and `PATCH /v1/article/{id}` | EditorStatusBar | No |
+| 12 | Editor | Insert-link button (default, hover, active, disabled), tooltip, LinkModal, link popover and touch sheet, rendered link, toolbar scrolling at 390 px | Yes | No (editor only) | LinkModal, LinkPopover, ToolbarButton | Yes |
+| 13 | Articles | Pagination with `page` and `size` (5, 25, 50, 100; default 25), URL state, loading, error, out of range | Yes | **Yes:** `page`, `size` on `GET /v1/article/` (same convention and 400 as Activity); total in `X-Total-Count`, array body unchanged; Integration reference updated | Paginator, PageSizeSelect | No |
+| 13b | Media | Pagination under the grid and list, same Paginator and PageSizeSelect as Articles; `page` and `size` in the URL; saved size preference | Yes (9 states in the Media group) | **Yes:** `page`, `size` on `GET /v1/media/` (replaces `cursor` and `limit`); total in `X-Total-Count`, array body unchanged; Integration reference | None (reuses Paginator, PageSizeSelect) | No |
+| 14 | Activity | Failed-action and security cards as toggles, synced chip and segment | Yes | No | FilterCardToggle | Yes |
+| 15 | Activity | Export menu and dialog, CSV: current view (active filters) and all activity (no filters, optional `from`/`to`). Preparing, started, failed, nothing to export, 403 | Yes | No: `GET /v1/activity/export` is implemented (CSV, synchronous, owner and admin, same filters as the list) | ExportMenu, ExportDialog | Yes |
+| 16 | Activity | JSON export (format control CSV or JSON) | Yes, one state, labelled proposed | **Yes (proposed):** `format=json` on `GET /v1/activity/export` | Segmented format control | No |
+| 17 | Integration | Images and variants section, URL builder, response bodies `unknown_variant` and `unsupported_parameter` | Yes | No | UrlBuilder | Yes |
+| 18 | All | States matrix for controls (hover, focus-visible, active, disabled) | Yes (board "States matrix: controls") | No | None | Yes |
+| 19 | All | Contrast fixes: paginator current page border, no muted text on sand | Yes | No | None | Yes |
+| 20 | All | Spacing, type and icon sizes made consistent (foundations.md, "One value per role") | Yes in the frames listed there | No | None | Yes |
+| 21 | Settings, sidebar | Sites screen under Settings → Sites ("Publishing" group); "Publishing" card on Settings. Owner only: hidden for other roles, 403 page on a direct link. Key immutable after creation | Yes | **Yes:** `site` table, GET/POST/PATCH/DELETE /v1/site/ (writes owner only; PATCH rejects a changed key), `reassign_to`, seed from PUBLIC_URL | SitesTable, SiteForm, SlugField (locked variant), ReassignDialog | No |
+| 22 | Sidebar | Authors entry between Media and Users, all roles. Owner and admin manage; other roles read-only list and detail | Yes | **Yes:** `author` table, GET /v1/author/ (any role), POST/PATCH/DELETE (owner and admin; a user may PATCH their own linked author), POST /v1/author/me (any role) | AuthorsTable, AuthorForm, SocialLinksRepeater, MediaField | No |
+| 23 | Editor | "Site and authors" section in every Editor frame (collapsed by default): Site select (any role that can edit the article), reorderable authors, inline create (owner and admin), hint | Yes | **Yes:** `site_id`, `author_ids[]` on PATCH /v1/article/{id} | MetaSection, AuthorList, AuthorSelect, SiteSelect, CreateAuthorHint | No |
+| 24 | Articles | Authors column; Site column and filter when more than one site | Yes | **Yes:** `site` filter, `site` and `authors` in the list payload | AuthorStack | No |
+| 25 | Profile | "Author profile" card in every Profile frame, one-click create, edit own author (user link locked) | Yes | **Yes:** POST /v1/author/me | AuthorProfileCard | No |
+| 26 | Backfill | Existing articles get the default site; authors start empty | n/a | **Yes:** migration | None | No |
+
+## Roles and permissions: screens that change
+
+| Screen | Change |
+|---|---|
+| Sidebar and mobile drawer (AppFrame) | Items are listed per permission, not per fixed role. Writer sees Home, Articles, Media, Authors, Activity and Content. A Roles entry appears under Settings for people who can view roles. |
+| Settings navigation (AppFrame, done) | New "Access" group with a "Roles" item (shield icon) under Settings in the sidebar and the mobile drawer, shown to everyone except the restricted `user` role. "Permissions" is removed. |
+| /settings/permissions | Retired. 301 to /settings/roles. The grid lives in the role editor. |
+| Users (list, invite, row menu) | Role badges, Change role dialog, role picker in invite (default Writer), pending invites show the role, Transfer ownership, protected owner row. |
+| Articles list and Editor | Publish hidden for roles without it; status shows Draft with "Ask an editor to publish." Delete and Edit disabled with a reason when scope is Own and the item is someone else's. |
+| Content entry lists and editor | Same Own rules. View only mark. |
+| Settings pages | Read-only mode with banner for people who can view but not edit. Owner-only actions disabled with an Owner only tag. |
+| Schema | Hidden for roles without Schema view. Read-only for view-only roles. |
+| API keys | Info alert "Keys follow their creator's role", a Follows role column. |
+| Profile | Your role card and See what I can do. |
+| Activity and filters | New event types, role diff in the detail panel. |
+| Error and 403 copy | Two codes and the page-level state added. |
+
+Decisions to confirm:
+| # | Decision made | Alternative |
+|---|---|---|
+| 1 | Content permissions come before General permissions in the editor, because the common case (Contributor) only touches the grid. | General first, as in the brief. |
+| 2 | Writer gets Authors: view and edit own, and Activity: own. | No Authors or Activity access. |
+| 3 | A new role starts with nothing granted; presets fill the grid. | Start from a copy of Writer. |
+| 4 | Own-scope rows others created show "View only" with a lock icon, not a hidden row. | Hide other people's entries. |
+| 5 | Reset to default exists for built-in roles edited by the owner. | No reset. |
+| 6 | Activity own/all scope uses the same None / Own / All control. | Toggle plus a separate scope select. |
+| 7 | Transfer ownership takes effect at once, no email to the new owner. | The new owner must accept. |
+| 8 | A user with Roles: manage cannot edit their own role, even in a custom role. | Allow narrowing only. |

docs/design/change-log-roles-sync.md

@@ -0,0 +1,119 @@
+# Change log: roles sync (pass 6)
+
+Diff this against the code. "Old" is the previous design copy, "New" is the copy now in the design. EN is the design language; FR is in the board table "Final copy: toasts and errors, EN and FR" (screens/roles.md, same title). Every state is drawn light and dark, 1440×900 and 390×844, on `RenewCMS Screens Roles.dc.html` (data `roles-spec.js`, frame `RolesFrame.dc.html`) unless stated. Roles board: 61 → 90 states, 11 → 15 groups.
+
+## 3. Differences adopted
+
+### 3.1 Neutral wording ("they")
+| File · state | Old | New |
+|---|---|---|
+| roles-spec.js, screens/roles.md, RolesFrame · Users: Change role dialog and Change role: options blocked | Her API keys follow the new role. | Their API keys follow the new role. |
+| same · Users: Transfer ownership: confirm | You become an Admin. You can't take ownership back unless he transfers it. | You become an Admin. You can't take ownership back unless they transfer it. |
+Searched all .md, .js, .dc.html and email files for he, she, his, her, him, hers. No other occurrence.
+
+### 3.2 Event names
+| File | Old | New |
+|---|---|---|
+| routes.md, screens/roles.md (Needs backend), roles-spec.js | role.created, role.updated, role.deleted, user.role_changed, site.ownership_transferred | role.create, role.update, role.delete, role.reassign (new), user.role_change, site.ownership_transfer |
+| states.md (new section "Roles sync"), screens/activity.md (new section) | event names and sentences were not written down | table of name, sentence, failed sentence |
+Sentences themselves are unchanged ("Role Contributor created", and so on).
+
+### 3.3 Invite endpoint
+| File | Old | New |
+|---|---|---|
+| screens/roles.md group 5, roles-spec.js group 5 | POST /v1/invite | POST /v1/user/invite |
+routes.md, components.md and the other screen files never cited `/v1/invite`. IntegrationPage already said `/v1/user/invite`.
+
+## 1. Copy
+All EN and FR strings: roles board, table "Final copy: toasts and errors, EN and FR", and group 12 (toasts) and 13 (inline errors).
+| State | EN |
+|---|---|
+| Toast: role changed (group 12) | Role changed · Ines Duarte is now Content lead, and their API keys follow the new role. |
+| Toast: role edited elsewhere, 409 | Role changed elsewhere · Jonas Weber edited Contributor, so nothing was saved. Reload and try again. · Reload |
+| Toast: role deleted elsewhere | That role no longer exists · It was deleted somewhere else, so we removed it from the list. |
+| Toast: member's role changed before a change | Role not changed · Ines Duarte's role changed in the meantime, so nothing was saved. Reload and try again. · Reload |
+| Toast: target's role changed before a transfer | Ownership not transferred · Jonas Weber's role changed in the meantime, so nothing was transferred. Check it and try again. · Reload |
+| Toast: member's role changed before a removal | User not removed · Ines Duarte's role changed in the meantime, so nothing was removed. Check it and try again. · Reload |
+| Role editor: save failed (new) | Couldn't save the role · Your changes are still here. Try again in a moment. · Try again |
+| Change role: failed (new) | Couldn't change the role · Nothing was changed. Try again in a moment. |
+| Delete role: target deleted (new) | Writer no longer exists · It was deleted somewhere else. Choose another role to move the members to. |
+| Delete role: role gained members (new) | Role still has members · Intern now has 1 member. Move them to another role first. |
+| Delete role: move failed (new) | Couldn't move the members · Nothing was changed. Try again in a moment. |
+| Invite: invalid email (new) | Enter a valid email address. |
+| Invite: account exists, 409 (new) | This address already has an account. |
+| Invite: role above yours (new) | Your role can't assign a role with more power than yours. |
+| Invite: send failed (new) | Couldn't send the invite · Try again in a moment. |
+| Activity, role.reassign | Moved 3 members from Intern to Writer |
+| Activity, failed sentences | Failed to {verb} {object}; one per event in the table "Activity events: failed sentences, EN and FR" |
+| Activity filter, category names | Articles · Media · Users and invites (old: Users & invites) · Roles (new) · API keys · Authentication · System |
+Unchanged and still correct: Name required, Name already taken, Escalation blocked, Conflict banner, Permission lowered.
+
+## 2. Profile role card (group 9)
+Decision: the summary line is removed. "Assigned by Marta Alves" is removed with it, because `access.role` has no such field either. "See what I can do" stays; its summary is computed from the permission list in GET /v1/me.
+| State | Old | New |
+|---|---|---|
+| Role card: custom role | Your role · Contributor · Assigned by Marta Alves · Creates content and edits only their own. · See what I can do · Your API keys follow this role… | Your role · [Contributor badge] [Custom tag] · See what I can do · Your API keys follow this role. If your role changes, they change too. |
+| Role card: Owner (new) | none | Your role · [Owner badge] [Locked] [Built-in] · See what I can do · same key line |
+Layout, top to bottom, inside the existing card: title; one row of badges (role badge with icon, then Locked if `locked`, then Built-in or Custom from `built_in`); link row with the list-checks icon; muted key line. Gap 12, as every card.
+
+## 4. Behaviour
+### Read = Own (group 14, new, 5 states; also group 2 Role editor and group 3 preview via the same editor)
+| State | Content |
+|---|---|
+| Role editor: Read set to Own | New info alert under the grid: Read: Own · Articles show online articles plus the person's own drafts. Custom content types show only entries the person created. Status counts follow the same rule. The preview sentence for Read = Own is now type-specific: "Can read online articles and their own drafts" (Articles) and "Can read only entries they created" (custom types). Old preview text was "read only their own". |
+| Articles list: Read = Own | Junior writer: 3 online articles by others and 2 own drafts. Tabs All 5, Online 3, Draft 2. Banner: Drafts by others are hidden. |
+| Articles list: no drafts of their own | Draft tab, counts All 3, Online 3, Draft 0. You have no drafts · Drafts you create appear here. Your role can't see drafts by other people. |
+| Entry list: Read = Own | Only own entries, "3 entries", banner Entries by others aren't shown. |
+| Entry list: no entries of their own | You haven't created an event yet · Your role shows only entries you created, so other people's events aren't listed here. Use New entry to add one. |
+Decisions table row 4 now says Update and Delete set to Own keep the View only rows, Read set to Own hides them.
+
+### 409 conflicts (group 15, new, 5 states)
+| State | Where | Edits kept | Recovery |
+|---|---|---|---|
+| Stale save: banner (existing Conflict state, copy unchanged) | Banner above the form | Yes, Save off | Reload role, or Review differences |
+| Stale save: review differences (new) | Dialog over the editor | Yes | Keep my edits (reload and re-apply edits on top, Save on) or Use the saved role (drop edits) |
+| Stale save: edits kept after reload (new) | Info toast, form shows saved role plus edits | Yes | Review, then Save |
+| Change role: member's role changed (new) | Alert inside the dialog; toast if closed | Selection kept; Current mark moves | Change role again |
+| Transfer ownership: target's role changed (new) | Alert inside the dialog; toast if closed | Typed email kept; primary off | Reload member, then Transfer ownership |
+
+### Integration page (IntegrationPage.dc.html, Back-office board group Integration)
+| Item | Old | New |
+|---|---|---|
+| Authentication, API key card | …with that user's role (owner or admin). A key never has more rights than its creator. | …with that user's role as it is now. A key never has more rights than its creator. A route that needs a permission answers 403 "missing_permission" to a key whose creator's role lacks it. |
+| Errors table, 403 | "This action needs a real session.", "Only the owner can do this.", "Only owners and admins can do this." or "You must verify your account to access this resource." | "This action needs a real session.", `missing_permission` (code style, literal body), or "You must verify your account to access this resource." Note: `missing_permission` is the literal body, not a sentence. Site SEO defaults need the permission to manage sites. Article SEO fields need only the right to edit the article. |
+| Access chip on 9 routes (content types create, update, delete; built-in types list, get; media purge settings get, patch, preview, purge) | Owner or admin | Needs permission. The route description ends with Needs the permission "…". Proposed permissions: Create and edit content types; Delete content types; View content types; Delete files (purge routes). |
+| Per-route 403 line on those routes | Only owners and admins can do this. | missing_permission (code style) |
+| Content types section intro | An owner or admin creates a type… | A user whose role can create and edit content types defines a type… |
+"Owner only" chips are kept for the owner-only routes.
+
+### Relation picker (SchemaFrame, Schema board group 7, Later)
+Sample data: 25 venues per page (the design had 3 sample results, never 10), footer "Showing 25 of 62" with Load more. New state "Relation picker: loading more": skeleton rows, Loading… on a disabled button. Group 7: 3 → 4 states.
+
+## Files touched
+roles-spec.js, RolesFrame.dc.html, screens/roles.md (regenerated from the spec), routes.md, states.md, screens/activity.md, screens/integration.md, screens/schema-later.md, schema-spec.js, SchemaFrame.dc.html, IntegrationPage.dc.html, README.md.
+
+## Open items for you
+See the end of this file's companion list in the chat reply; repeated here.
+1. Relation picker: the design never had a "Load more" frame or a 10-result sample. Both were added, not updated.
+2. Activity event names: states.md and screens/activity.md did not contain event names; they only existed in roles.md, roles-spec.js and routes.md. I added the table to the first two.
+3. `user.role_changed` and `site.ownership_transferred` became `user.role_change` and `site.ownership_transfer`. Your brief said "the same present-tense pattern for the other role events". Confirm those two are included.
+4. `/v1/invite` appeared only in screens/roles.md and roles-spec.js. routes.md, components.md and the other screens already had `/v1/user/invite` or no citation.
+5. The 403 row in the design did not list "missing_permission". It listed "Only the owner can do this." and "Only owners and admins can do this.", which I removed. Check that owner-only routes now also answer `missing_permission`.
+6. Status naming: you say All / Online / Draft; the design already used Online and Draft, so no change.
+7. "Role deleted by someone else (409)": a deleted role normally answers 404. I drew 404 for the roles list and an inline 409 only where the deleted role was a reassign target. Confirm the codes.
+8. "Changing a role that changed meanwhile": I read it as the member's role having changed, not the role definition. Confirm.
+9. Profile: `access.role` has no assigned_by, so "Assigned by" was removed along with the summary. Confirm that the permission summary can be built from /v1/me.
+10. Activity categories: the filter had six categories. I added Roles and renamed "Users & invites" to "Users and invites" to match the permission group. Authors, Sites and Content types have activity in the product but no category in the filter; I did not add them.
+11. Purge routes: the catalogue has no permission for media purge. I used Delete files. Pick the real one.
+12. Not changed, but now out of date: IntegrationPage Entries intro still says "Any verified user can write entries"; screens/schema.md and the Schema frames say "Owner or admin" for Schema; states.md "Sites and authors: roles" and the 403 owner_only rows still describe fixed roles; screens/profile.md Display name copy. Say if you want these aligned.
+13. Decision 4 in "Decisions to confirm" was narrowed (Read = Own hides rows). Direct link to a hidden item answers the existing 404 page; this is proposed.
+14. French role names: built-in names (Owner, Admin, Writer) stay English in FR copy until you decide.
+15. Toast bodies use two short sentences in places; the glossary says one. Kept for clarity.
+
+## Corrections made while importing into the repo
+These were checked against the backend and applied to the repo copy of the design (the Claude Design copy still has the old values).
+1. Event names: the backend emits `role.edit` (not `role.update`), `user.change_role` (not `user.role_change`) and `user.transfer_ownership` (not `site.ownership_transfer`). The other three, `role.create`, `role.delete` and `role.reassign`, match.
+2. Media purge permissions: `GET /v1/media/purge-settings` needs "View settings", `PATCH /v1/media/purge-settings` needs "Edit general settings", and `GET /v1/media/purge-preview` and `POST /v1/media/purge` need "Delete files".
+3. Open item 7 (deleted role): the backend answers 404 for a deleted role and 409 for a stale role save, as drawn.
+4. Open item 8: "changing a role that changed meanwhile" means the member's role, as read.
+5. Event names now match the backend: role.create, role.edit, role.delete, role.reassign, user.change_role, user.transfer_ownership, user.remove. The living specs (screens/roles.md, roles-spec.js, routes.md, states.md, screens/activity.md) use these names; the history rows above keep the names as they were at the time.

docs/design/components.md

@@ -0,0 +1,170 @@
+# Components
+
+Frames: `AppFrame.dc.html` (shell: sidebar, topbar, mobile nav drawer, modal, toasts, articles, editor, users, settings, profile), `ActivityFrame`, `MediaFrame`, `VariantsFrame` (page bodies only), `IntegrationPage`, `IntegrationImages`, `ApiKeysPage`, `CodeSnippet`, `StatesMatrix`. The page-body frames mount inside AppFrame through two props (`slotBody`, `slotOverlays`) so there is one sidebar, one topbar and one drawer.
+
+## Overlay pattern (one rule, applies everywhere)
+| Kind | Desktop | Mobile (390) | Use |
+|---|---|---|---|
+| Dialog | Centered horizontally, 140 px from the top, width 460 (560 wide forms, 640 crop), `--rc-shadow-modal` | Bottom sheet: full width, flush to the bottom, grabber (36×4, `--ui-border-accented`) | Confirmations and forms with up to about four fields |
+| Slide-over | Right panel, full height, over a scrim (Variant form 960 wide with live preview, Media detail, Activity details 480) | Tall bottom sheet, 92% height, grabber, close ×, sticky footer. Never a full page | Only forms with a live preview, and record details. Nothing else may be a slide-over |
+| Menu | Popover under the trigger | Bottom sheet with a title and a close × | Action lists (Export, row menus on mobile) |
+
+Dialog anatomy: header (title 16/24 weight 600, optional description in `--ui-text-muted`, close × 28 px desktop / 44 px mobile), body (padding 20 24 0, gap 16), footer (padding 20 24). Footer order: secondary on the left, primary on the right, aligned right. On mobile the buttons stack with the primary on top, 44 px high. Destructive confirms use `--ui-error` fill with `--ui-bg` text and the verb of the action ("Delete image", "Revoke key"). The scrim is `--rc-overlay`. Esc, the scrim and swipe close unless an action is in flight. In flight, the primary shows `loader-circle` and the verb in -ing form; Cancel is disabled; the dialog cannot be dismissed. Focus is trapped and returns to the trigger.
+Cancel is replaced by an explicit label where "Cancel" would read as the action: "Keep invite", "Keep key", "Restart later".
+Redrawn to this pattern in pass 2: variant form (mobile full page became a sheet), Activity export dialog (was centered, with a header bar and a 480 wide box), API keys dialogs (bordered box, 18 px title, 44 px buttons, 120 px offset), all Media and Variants dialogs (mobile floated with a 16 px inset; now flush sheet with grabber).
+
+## Unified in pass 2
+- Sidebar: ActivityFrame, MediaFrame and VariantsFrame each had their own copy (VariantsFrame's with the Settings group, MediaFrame's with a raw colour). Removed. AppFrame's is the only one. Prototype's own mobile drawer was replaced by AppFrame's drawer (`s.drawer`).
+- Topbar (breadcrumb on desktop, title and lead button on mobile): three copies removed; AppFrame's is used.
+- Mobile nav drawer: VariantsFrame's drawer removed; AppFrame renders one (with the Settings > Media group).
+- Code block: Integration endpoints, Authentication example, error response, API keys (one-time key), base URL field and the image URL builder all use `CodeSnippet`.
+- Modal geometry: AppFrame, MediaFrame, VariantsFrame, ActivityFrame (export) and ApiKeysPage now draw the same dialog and sheet.
+- Toast width: 356 px desktop everywhere (was 356, 360, 372).
+Still separate implementations that look the same (not merged in code, see README "Not done"): toast (5 copies), badge (`Bd` in MediaFrame and VariantsFrame), empty state (MediaFrame and VariantsFrame), modal shell (AppFrame template and the JS shells).
+
+## CodeSnippet
+One component for every code or copyable value. Props: `tabs` (`{ k, label, code }[]`), `active`, `copied`. A header row (min 44 px) holds the tabs and the Copy button; selected tab has a 2 px `--ui-primary` underline and `--ui-text-highlighted` text. With one tab the label is plain muted text (no tab). Copy reads "Copy", then "Copied" with `check` for 2 s (`--ui-success`), announced politely. Body is `pre`, IBM Plex Mono 12/19, scrolls horizontally, `tabindex="0"`. No syntax colouring. Background `--ui-bg-elevated`, border `--ui-border`.
+
+## Editor: link
+- **Toolbar button** (icon `link`, after the list buttons): default `--ui-text-toned`; hover `--ui-bg-elevated` with tooltip "Insert link (Ctrl+K)" (macOS: "Insert link (⌘K)"); focus-visible 2 px `--ui-primary` outline; active when the cursor is inside a link (`aria-pressed`, `--rc-sand` and `--rc-on-sand`); disabled at 40% opacity when an image is selected. 28 px desktop, 40 px mobile.
+- **LinkModal**: dialog on desktop, bottom sheet on mobile. Fields "Link text" (prefilled from the selection), "URL" (http, https, mailto, relative path, #anchor), toggle "Open in new tab". Footer: Cancel left, "Insert link" or "Save link" right; "Remove link" as a text button in edit mode. Errors: "Enter the link text." and "Enter a valid URL. Use http(s), mailto, a path or #anchor." Helper text under the toggle: "Links open in the same tab unless you turn on a new tab."
+- **Link popover** (desktop): under the link, 288 px, URL in mono on top, then "Edit", "Open", "Remove" (error colour). Opens on click or Enter on a focused link; Esc closes. **Touch**: bottom sheet with the link text, the URL and three 48 px rows "Edit link", "Open link", "Remove link". Remove needs no confirmation (undo restores).
+- **Rendered link**: `--ui-text-highlighted`, 1 px underline, 3 px offset. Hover 2 px underline. Focus 2 px `--ui-primary` outline, offset 2. Selected: `--rc-sand` fill, `--rc-on-sand` text.
+- **Toolbar at 390 px**: the full toolbar (22 buttons) does not fit. It scrolls sideways in one row, never wraps; a 24 px fade (`--ui-bg` to transparent) marks hidden content on each side. Buttons stay 40 px.
+
+## Paginator
+First, previous, page numbers, next, last; "Showing 26–50 of 312"; page-size select "5 per page", "25 per page", "50 per page", "100 per page" (default 25). Mobile: previous, "Page 2 of 13", next. Hidden when there is one page. Desktop layout, one row: the summary on the left (it takes the free space), the page-size select next to it, the page controls right-aligned; Sites, Authors, Articles and Media draw it the same way. Buttons 32 px (44 px mobile), current page `--rc-sand` with `--ui-primary` border, disabled controls 40% opacity, focus ring 2 px `--ui-primary`. Page size and page live in the URL as `size` and `page`.
+
+Variant for Sites and Authors (no new component): when everything fits on one page the page-size select is hidden together with the controls and the footer shows only the count line "N sites" or "N authors" in `--ui-text-muted`. Loading dims the whole pager to 40% and disables it; the summary reads "Loading page N…". Sizes are unchanged: 5, 25, 50, 100.
+
+## Activity export
+Menu: "Export current view" (CSV, active filters, all pages) and "Export all activity…" (CSV, ignores filters; owner and admin only). Dialog: Format (read-only "CSV"; a CSV and JSON control appears when JSON ships, proposed), Date range (default "All time"). States: configure, "Preparing download…" (indeterminate bar, no percentage, Cancel left, "Preparing…" disabled right), "Download started" (Close), "Couldn't prepare the download" (Cancel, Retry), "Nothing to export" (Close), 403 "You can't export all activity" (Close). Synchronous: no job, no progress, no later notification.
+
+## FilterCardToggle
+Button with `aria-pressed`; pressed uses `--rc-sand` and `--rc-on-sand` with a `--ui-primary` border; pressing again clears. Synced with the Outcome segment and the chip.
+
+## NavItem and NavGroup
+Row 32 px (44 px in the mobile drawer). Parent selected: `--rc-sand`, `--rc-on-sand`, weight 500. Child selected: parent unfilled, `--ui-text-highlighted`, weight 500, chevron-down; child filled as above. Group label "Media" 11 px uppercase `--ui-text-muted`. Children indent 19 px with a 1 px `--ui-border` rail.
+
+## Media badges (Media library, picker, Variants board)
+`Unused` (warning soft, icon unlink), `Used in N` (outline), `Duplicate` (info soft, icon copy), `N variants` (info soft, icon layers; "1 variant"; none shown at 0). The Media grid card, the list row and the mobile row show all of them. Size column and "Size" meta use the original file size only; the "with variants" size and the sort are on the Variants board (see README, Not done).
+
+## Other
+- **PurgeDuplicatesDialog**: `UModal`, `sm:max-w-md`, sheet on mobile, cancel first, confirm `color="error"`. Props `open`, `preview`, `status` (loading, ready, purging, nothing, error, partial, conflict). Emits `purged`.
+- **MediaCleanupCard**: square `USwitch`, `UInputNumber` with "days" suffix, saves on change.
+- **MediaLinksCard**: rows "Manage image variants" and "Cache usage", 44 px min height.
+- **StatesMatrix**: the board "States matrix: controls".
+
+## Sites and authors (pass 3)
+
+Frames: `DirectoryFrame.dc.html` (Sites, Authors, editor section content; the list, slide-over, delete-with-reassign dialog, slug field and media field are defined once there and used by both Sites and Authors); `AppFrame.dc.html` changed in place (sidebar items, Articles columns and filter, editor section and mobile details sheet, Settings card, Profile card, role-based sidebar). Existing components are reused unchanged: dialogs, toasts, empty states, skeletons, paginator, media picker.
+
+| Component | Status | Nuxt UI | Notes |
+|---|---|---|---|
+| SitesTable, AuthorsTable | New | UTable; below 640 px a list of UCard | Same row heights as Users. Defined once as DirectoryList in DirectoryFrame and used by both. Read-only variant has no actions, chevron instead of the menu |
+| SiteForm, AuthorForm | New | USlideover + UForm, UFormField, UInput, UTextarea, URadioGroup, USwitch | Sheet on mobile. Close with changes opens the discard UModal |
+| SlugField | New | UInput + UButton (icon) + UBadge | Defined once in DirectoryFrame. Auto badge, pencil, "Reset to match the name". Locked read-only variant (lock icon, "Used in API paths, so it can't change.") for the site key after creation |
+| SocialLinksRepeater | New | USelect + UInput + UButton, in UFormField | Max 5 rows. Placeholder follows the type |
+| MediaField | New | UButton + UModal (existing picker) | Defined once in DirectoryFrame. Used for the social image and the avatar |
+| AuthorViewPanel | New | USlideover, read-only | Detail for roles without author rights. Close is the only action |
+| AuthorAvatar | New | UAvatar | Initials fallback, square, radius 0 |
+| AuthorStack | New | UAvatarGroup max=3 | Shows "+N" |
+| AuthorList | New | List of UButton, UAvatar, UBadge; sorting with useSortable | No Nuxt UI match for sortable rows. Keyboard reordering is custom |
+| AuthorSelect | New | USelectMenu multiple with create-item | Footer item "Create author…" opens the dialog |
+| SiteSelect | New | USelectMenu | Item slot shows name and host |
+| UserSelect | New | USelectMenu | Only users without an author |
+| ReassignDialog | New | UModal + USelectMenu + UAlert | Defined once in DirectoryFrame. Used for site and author deletion |
+| MetaSection | New | UCollapsible | Desktop sidebar and mobile sheet. Site select for anyone who can edit the article. No "Create author…" row without author rights |
+| AuthorProfileCard | New | UCard + UButton + UAlert | Profile screen. Defined once in AppFrame; every Profile frame shows it |
+| CreateAuthorHint | New | UAlert closable | Dismissal stored per user |
+| Default badge, Linked badge, Guest badge | New | UBadge | Sand fill, info soft fill, outline |
+| Row menu with a disabled item | Existing + change | UDropdownMenu + UTooltip | The item stays focusable |
+| SearchSharingSection | New | UCollapsible + UButton + USeparator | Editor sidebar and Details sheet, after Site and authors. Summary: Ready, N suggestions, Hidden from search, Checking… |
+| SeoPanel | New | USlideover (desktop 960 px) / bottom sheet (mobile) + UFormField, UInput, UTextarea, USwitch, UCollapsible | Defined once in DirectoryFrame. Reuses SlugField, MediaField and the picker. Fallback chip: dashed outline, "Using …" |
+| SoftCounter | New | text | Mono, "n / max". Amber (--ui-warning) outside the recommended range, never red, never blocks |
+| SearchPreview | New | UCard | Desktop and Mobile toggle (UTabs, 2 items). Title cut at 60 (desktop) or 70 (mobile) characters including the template, description at 160 or 120 |
+| SocialCardPreview | New | UCard | 1.91:1 image, host, title, 2-line description; fallback chips |
+| SuggestionList | New | UAlert-style rows + UButton (link, ghost icon) | Calm elevated block. States: list, all good, checking. Per-article dismiss; "Show dismissed" |
+| ApiPreviewDialog | New | UModal / bottom sheet + UTabs + UButton + UAlert | Formatted and Raw; Copy JSON; loading, error, draft note |
+| SeoStatusChip | New | UBadge | Lightbulb + count (warning soft) or eye-off "Hidden" (outline). Articles rows and cards |
+| NeedsAttentionToggle | New | UButton (pressed state) | Articles toolbar, sand when on |
+| TitleTemplateField | New | UInput + live example | Sites form |
+
+
+## Custom content types (pass 4)
+
+Frames: `SchemaFrame.dc.html` (all schema, content and entry bodies; relation, permissions and import frames are Later), mounted in `AppFrame.dc.html`. Existing pieces are reused unchanged: dialogs and sheets, toasts, alerts, paginator, skeletons, empty states, SlugField, CodeSnippet, the single switch.
+
+**AppFrame changes.** Sidebar: a "Schema" item (icon shapes) after Users, owner and admin only. A "Content" group under the main items, one row per custom type (default icon files, name truncated with the full name in the tooltip, selected row sand). Over 5 types it shows the first 5 and the selected one, then "Show all N". Mobile drawer: the group is one collapsed row "All content types" with the count; expanded it lists the types at 44 px. New props on the shell state: `content` (types), `contentOn`, `contentOpen`. The group is hidden when there are no custom types. No existing item changed.
+
+| Component | Status | Nuxt UI | Notes |
+|---|---|---|---|
+| SchemaTable | New | UTable; below 640 px a list of UCard | Same pattern as SitesTable. Built-in rows add the lock and a Built-in badge |
+| BuiltInBadge | New | UBadge outline + lock icon | Existing badges have no lock; same size as the Linked badge |
+| FieldList | New | List of UButton rows, useSortable, UBadge | No Nuxt UI sortable list. Keyboard: the grip is a button; Space picks up, arrows move, Space drops, Esc cancels. Move up and Move down buttons on the selected row. Same approach as AuthorList |
+| FieldInspector | New | UForm, UFormField, UInput, UInputNumber, UInputDate, USelect, UTextarea, USwitch | Composition only. Controls follow the field type |
+| FieldTypePicker | New | URadioGroup variant="card" in a grid, icon in the label | Existing radio cards fit; only the icon and the lock state are added |
+| KeyField | Existing | SlugField (UInput + UButton + UBadge) | Reused for the type key and field keys. Locked variant already exists |
+| ChoicesEditor | New | UInput + UButton rows, useSortable | UInputTags can't reorder or flag a blank or duplicate per row |
+| ApiPreview | New | UCollapsible + CodeSnippet + UButton | CodeSnippet is reused. Sheet on mobile |
+| ChangeReview | New | UModal (sheet on mobile), UBadge, list rows | Dialog pattern unchanged. Rows reuse the UAlert-style row of SuggestionList |
+| SchemaRefusal, DeleteTypeDialog | New | UModal + UAlert | Dialog pattern unchanged. Delete uses color="error" |
+| ContentNavGroup | New | UNavigationMenu group "Content" (NavGroup) | Adds the 5 + selected cap, "Show all N" and the collapsed mobile row |
+| EntryTable | New | UTable with column visibility | Cells per field type (FieldCell). Cards on mobile |
+| ColumnPicker | New | UPopover + UCheckbox list; bottom sheet on mobile | UDropdownMenu closes on each pick and has no cap message |
+| SortSelect | New | USelect + UButton icon | ID, Created and Updated only |
+| FieldControl | New | UInput, UInputNumber, UInputDate, USelect, USwitch (the single toggle), MarkdownField | One switch per field type, generated from the schema |
+| MarkdownField | New | UTextarea + UTabs (Write, Preview) + toolbar of UButton | The article editor is a full document editor. This is a compact one |
+| FieldCell | New | text, UBadge outline (choice), icon + text (yes or no) | Renders one value per type, with the empty dash |
+| EntryForm | New | UForm generated from the schema | Provenance footer, schema-changed alert |
+| RelationPicker (later) | New | URadioGroup card + USelect | Sentence preview is text |
+| RelationField (later) | New | UInputMenu multiple | Chips and search |
+| PermissionsGrid (later) | New | UTable + UCheckbox; UCard list on mobile |  |
+| SchemaImportDialog (later) | New | UModal + UFileUpload |  |
+
+## Media field (pass 5)
+
+Frames: `SchemaFrame.dc.html` (`MCtl`) and `MediaFrame.dc.html` (picker in field mode, usage). Full spec: `media-field-changes.md`.
+
+| Component | Status | Nuxt UI | Notes |
+|---|---|---|---|
+| MediaFieldControl | New | UFormField, UButton outline and ghost, UModal (desktop) or bottom UDrawer (mobile) for the picker, UTooltip, UIcon (image, image-off, unlink, image-plus). The thumbnail is a plain button | Props label, required, modelValue (image id or null), image (filename, width, height, size, or missing), disabled, error. Emits update:modelValue. States: empty, filled, hover, focus, error, missing, saving, read-only |
+| FieldCell (media) | Extended | Thumbnail 40 px square, dash when empty, dashed square with unlink when the image is gone | Row height 48 px, mobile card thumbnail 32 px |
+| MediaPicker (field mode) | Extended | Existing picker | Title "Choose an image", "Use this image", no alt text, no variant select, "Current" badge, optional "No image" row |
+
+## Roles and permissions (new)
+
+| Component | Used for | Nuxt UI mapping |
+|---|---|---|
+| ScopeControl (tri-state) | None / Own / All in grid cells, mobile cards and general rows | URadioGroup variant="table" orientation="horizontal" size="xs", three items, in a grid cell. Selected item: sand fill, weight 600 and an underline |
+| OnOffCell | Create column and boolean rows | USwitch with visible On/Off label |
+| PermissionGrid | Content permissions | Custom grid (role="grid") of ScopeControl cells; header buttons use UDropdownMenu for bulk actions |
+| PresetPills | Read only, Write own, Full content | UButton variant="outline" size="xs", pressed state via aria-pressed |
+| PermissionGroup | Collapsible group with "x of y enabled" | UCollapsible; header UButton variant="ghost" |
+| OwnerOnlyTag | Locked owner-only items | UBadge variant="subtle" with lucide lock icon |
+| RoleBadge | Users, roles, API keys | UBadge variant="outline" with role icon (crown, shield, pencil, user-round) |
+| RolePreview | What this role can do | Card on desktop (UCard), USlideover side="bottom" on mobile |
+| RolePicker | Change role, invite, reassign on delete | URadioGroup variant="card" with description; USelectMenu for the reassign field; items disabled with a reason in description |
+| SaveBar | Unsaved changes | Sticky container with UButton color="neutral" variant="outline" and UButton color="primary" |
+| ReadOnlyBanner | Read-only pages | UAlert color="info" icon="i-lucide-lock" variant="soft" |
+| ViewOnlyMark | Own scope rows | Text with lucide lock icon and UTooltip |
+
+Accessibility of the tri-state cell:
+| Item | Pattern |
+|---|---|
+| Structure | The grid is role="grid". Each cell contains a role="radiogroup" named "{Type}: {Action}" (for example "Events: Update") with three role="radio" items None, Own, All. Create is a role="switch" named "Events: Create". |
+| Keyboard | Tab moves between cells (one stop per cell). Inside a group, Left and Right (or Up and Down) move and select, Home and End jump to None and All. Arrow keys also move the roving tabindex. Space selects. Header bulk buttons open a menu with the same three values. |
+| Announcement | Selected item is aria-checked="true". A polite live region announces changes: "Events, Update, set to Own." Disabled items are aria-disabled and described by the reason ("You can only grant what your role has."). |
+| Not by color alone | Selected segment: sand fill plus weight 600 plus a 2 px underline in --ui-primary. Locked: lock icon. Changed cell: square marker. Mixed: text badge. |
+| Targets | 26 px segments on desktop, 44 px on mobile. Focus: 2 px --ui-primary outline, offset 2 px. |
+
+## Account (change email, export, delete)
+| Component | Status | Nuxt UI mapping | Where |
+|---|---|---|---|
+| EmailChangeForm | New | UFormField + UInput (email, password) + UButton, inside the Account UCard | Profile |
+| PendingEmailNotice | New | UAlert (info) + two UButton (outline) | Profile |
+| DataExportCard | New | UCard + UButton; notices as UAlert | Profile |
+| DangerZoneCard | New | UCard with border var(--ui-error), UButton color error | Profile |
+| DeleteAccountDialog | New | UModal (existing destructive ConfirmDialog shell) + UInput x2 + list + UAlert info + ULink | Profile |
+| BlockedDialog | New | UModal with dismissible false, no close button; UButton primary for the next step | Profile |
+Specs: field heights 40 (44 mobile), buttons 36 (44 mobile), card padding 16, section gap 16. Colors from tokens only. Destructive confirm is disabled at 40% opacity until valid. Implemented in AccountCards.dc.html and the AppFrame modal.

docs/design/emails.md

@@ -0,0 +1,28 @@
+# Emails
+
+Go `html/template` files, ready to replace `internal/infrastructure/mailer/templates/`:
+
+- `source/emails/verification.html` uses `{{.Host}}` and `{{.VerificationCode}}`, linking to `{{.Host}}/register/validate?c={{.VerificationCode}}`.
+- `source/emails/password-reset.html` uses `{{.Host}}`, `{{.VerificationCode}}` and `{{.Email}}`, linking to `{{.Host}}/register/reset/validate?c={{.VerificationCode}}&email={{.Email}}`.
+
+- `source/emails/invitation.html` uses `{{.Host}}`, `{{.VerificationCode}}`, `{{.Email}}` and `{{.InvitedBy}}`, linking to `{{.Host}}/invite/accept?c={{.VerificationCode}}`. `{{.Email}}` is the invited address, shown in the body only. `{{.InvitedBy}}` is the inviter's display name, or their username when they have none. The subject is "{{.InvitedBy}} invited you to RenewCMS". The invite expires in 3 days and works once.
+
+Previews: `source/RenewCMS Emails.dc.html`.
+
+## Transactional emails
+
+Three Go html/template files: emails/verification.html, emails/password-reset.html and emails/invitation.html . They use a table layout with inline CSS and a 600 px maximum width. The button is bulletproof: a colored table cell plus a padded link, so it survives Outlook. Each has a plain-URL fallback, a hidden preheader, and prefers-color-scheme overrides for clients that support them. The mark is live text in a black cell rather than an image, so it shows even when images are blocked. Previews below use example values.
+
+Suggested subjects are "Verify your RenewCMS account", "Reset your RenewCMS password" and "<InvitedBy> invited you to RenewCMS", where .InvitedBy is the inviter's display name or username. html/template escapes the .Email value for the query string in the reset link (the @ becomes %40), and the confirm route reads it back decoded.
+
+## Account emails (change email, deletion, export)
+Go `html/template` files built from `source/emails/verification.html` (same table layout, tokens, dark overrides, bulletproof button, URL fallback). English only.
+
+| File | To | Subject | Variables |
+|---|---|---|---|
+| `source/emails/verify-new-email.html` | the new address | Confirm your new RenewCMS email address | `.Host`, `.Username`, `.VerificationCode`, linking to `{{.Host}}/account/email/confirm?c={{.VerificationCode}}` (expires in 2 hours, works once) |
+| `source/emails/email-change-notice.html` | the old address, at request time | Your RenewCMS email address change was requested | `.Host`, `.Username`, `.NewEmail`, linking to `{{.Host}}/profile` |
+| `source/emails/account-deleted.html` | the address the account had, sent once | Your RenewCMS account has been deleted | `.Host`, `.Username`, `.DeletedAt`; no button, generic text, no personal data |
+| `source/emails/export-ready.html` | the account address, async flow only | Your RenewCMS data export is ready | `.Host`, `.Username`, `.VerificationCode`, linking to `{{.Host}}/account/export/{{.VerificationCode}}` (expires in 24 hours, requires a logged-in session) |
+
+`export-ready.html` is only needed if the async export alternative is built. Previews are rows on `source/RenewCMS Emails.dc.html`.

docs/design/foundations.md

@@ -0,0 +1,87 @@
+# Foundations
+
+Tokens only. No raw hex or rgb in any frame. The one exception is the brand mark SVG (`#111` and `#fff` fills). Radius is 0 everywhere (no `border-radius` is declared in any frame).
+
+## New tokens (do not exist in the app yet)
+`tokens/renewcms.css` defines no `--rc-*` token. The frames use the ones below. They are **new**. Add them to the app's CSS, light values in `:root` and dark values in `.dark`. No `--ui-*` token is changed.
+
+| Name | Light | Dark | Used by |
+|---|---|---|---|
+| `--rc-sand` | #e8dfd1 | #d4c5b0 | Selected nav item (parent and child), selected table row and media card, current paginator page, pressed filter card, avatars, account chip, "In this article" tag, drag-drop fill |
+| `--rc-on-sand` | #111111 | #111111 | Text and icons on `--rc-sand`. Never use `--ui-text-muted` or white on sand |
+| `--rc-success-soft` | #eaefea | #1f241f | Success badge, success alert and toast icon ground |
+| `--rc-info-soft` | #ebeef0 | #202428 | Info badge, info alert, "variants" badge, duplicate badge |
+| `--rc-warning-soft` | #f0ede6 | #2a251e | Warning badge and alert, "Unused" badge |
+| `--rc-error-soft` | #f3eae9 | #2c201f | Error badge and alert, failed-actions card |
+| `--rc-overlay` | rgb(10 10 10 / 0.4) | rgb(0 0 0 / 0.6) | Dialog, sheet and slide-over scrim; crop mask |
+| `--rc-shadow-pop` | 0 4px 16px rgb(17 17 17 / 0.08), 0 1px 2px rgb(17 17 17 / 0.06) | 0 4px 16px rgb(0 0 0 / 0.5) | Menus, popovers, toasts. Same as `--shadow-popover` |
+| `--rc-shadow-modal` | 0 16px 48px rgb(17 17 17 / 0.18) | 0 16px 48px rgb(0 0 0 / 0.6) | Dialogs, sheets, slide-overs. Same as `--shadow-modal` |
+| `--rc-canvas` | #ecebe8 | #1c1c1c | Design boards only. Not for the app |
+
+Implementers may alias `--rc-shadow-pop` and `--rc-shadow-modal` to the existing `--shadow-popover` and `--shadow-modal`. The Nuxt UI `UAlert`/`UBadge` `soft` variants can map to the four `-soft` tokens.
+
+## Contrast (computed, AA: text 4.5:1, UI components 3:1)
+Light | dark. Computed with the WCAG relative luminance formula from the token values above and the `--ui-*` values in the board root.
+
+| Pair | Light | Dark | Result |
+|---|---|---|---|
+| Success, info, warning, error on their `-soft` ground (badges, alerts) | 6.7 / 6.9 / 7.1 / 7.3 | 8.7 / 8.4 / 8.1 / 8.1 | Pass |
+| Neutral badge: `--ui-text-toned` on `--ui-bg-elevated` | 8.7 | 10.9 | Pass |
+| Chip, selected row, current page: `--rc-on-sand` on `--rc-sand` | 14.3 | 11.2 | Pass |
+| Neutral chip: `--ui-text-highlighted` on `--ui-bg-accented` | 14.9 | 15.2 | Pass |
+| Toast title on `--ui-bg` | 18.9 | 18.1 | Pass |
+| Toast body `--ui-text-toned` / `--ui-text-muted` on `--ui-bg` | 9.7 / 5.7 | 11.8 / 6.6 | Pass |
+| Banner (offline): `--ui-text-inverted` on `--ui-bg-inverted` | 18.9 | 18.1 | Pass |
+| Table text `--ui-text` on `--ui-bg`; on hover `--ui-bg-elevated` | 15.9; 14.2 | 14.9; 13.7 | Pass |
+| Table header and hover meta: `--ui-text-muted` on `--ui-bg-elevated` | 5.1 | 6.1 | Pass |
+| Tab selected / unselected / count | 18.9 / 9.7 / 5.7 | 18.1 / 11.8 / 6.6 | Pass |
+| Segmented: selected `--ui-bg` on `--ui-primary`; unselected `--ui-text-toned` on `--ui-bg` | 18.9; 9.7 | 18.1; 11.8 | Pass |
+| Placeholder `--ui-text-muted` on `--ui-bg` | 5.7 | 6.6 | Pass |
+| `--ui-text-muted` on `--rc-sand` | 4.3 | 1.7 | **Fails.** Never place muted text on sand. Frames use `--rc-on-sand` |
+| `--ui-text-dimmed` on `--ui-bg` | 2.8 | 3.3 | **Fails.** Not used for text. Allowed for disabled icons and decorative strokes |
+| Disabled controls at 40% opacity (label on `--ui-bg`) | 2.6 | 3.7 | Exempt (inactive component). Never carry information only in a disabled label |
+| Disabled table row at 55% opacity | not computed | not computed | Exempt (inactive) |
+| UI: `--ui-border-accented` on `--ui-bg` (input, checkbox, segmented, secondary button borders) | 3.6 | 3.3 | Pass (3:1) |
+| UI: focus ring `--ui-primary` on `--ui-bg` | 18.9 | 18.1 | Pass |
+| UI: `--rc-sand` fill against `--ui-bg` | 1.3 | 11.2 | **Fails in light** as the only indicator |
+| UI: `--ui-border` on `--ui-bg` | 1.3 | 1.5 | Decorative only (card and table lines). Never the only boundary of a control |
+
+Fixes applied (token swaps):
+- Current page in the paginator: border changed from `--rc-sand` to `--ui-primary` (18.9 / 18.1) so the state does not rely on a 1.3:1 fill.
+- Selected media cards and rows keep `--ui-primary` outline with the sand fill (already so).
+- Selected nav items still rely on the sand fill plus weight 500 and `aria-current="page"`. The fill alone is 1.3:1 in light; the weight change and the programmatic state carry the information. This is accepted and recorded here, not "fixed".
+- Rule added: `--ui-text-muted` is never used on `--rc-sand`.
+Not computed: hover and active backgrounds of every control against every text colour; the states-matrix uses combinations already listed above.
+
+## One value per role (spacing, radius, type, icons)
+Sweep of the frames (`AppFrame`, `ActivityFrame`, `MediaFrame`, `VariantsFrame`, `IntegrationPage`, `IntegrationImages`, `ApiKeysPage`, `CodeSnippet`, `AuthCard`). "Found" is what was drawn before pass 2.
+
+| Role | Found | Value now (desktop / mobile) |
+|---|---|---|
+| Page padding | 32 px (Home, Users, Settings, Integration, API keys), 24 px (Media, Activity, Variants); mobile 20 16 or 16 | 24 px / 16 px. Extra bottom padding only to clear a fixed bar (88 or 96 px) |
+| Section gap on a page | 20, 28 (Home, Settings), 16 elsewhere | 16 px |
+| Card padding | 16 px and 20 px | 16 px |
+| Card inner gap | 8, 12, 14, 16 | 12 px (6 px between a label and its control, 8 px between buttons) |
+| Banner and alert padding | 10 12, 12 14 | 12 14 |
+| Radius | none declared | 0 |
+| Page title | 28/36 (Home, Integration, API keys), 24/32 (Variants), 20/28 (rest) | 20/28, weight 600, same on mobile |
+| Section heading (reference pages) | 18/26 | 18/26 |
+| Card title | 14/22, 15/22, 15/24 | 15/24, weight 600 |
+| Sub heading | 14/22 | 14/22 |
+| Dialog title | 16/24 | 16/24 |
+| Stat figure | 28/36 (Home), 24/32 (Activity), 22/36 (Variants mobile) | 24/32, mobile 22/32 |
+| Error and 404 page title | 24/32 | 24/32 (unchanged) |
+| Editor article title | 18/26 | 18/26 (own role) |
+| Body text | 13/20 | 13/20 |
+| Small and meta text | 12/18 | 12/18 |
+| Icon in text and buttons | 16 (91), 14 (87), 12 (20), 13 (1), 18, 20, 22, 28 | 16 px. 14 px inside compact controls and badges (12 px in badges). 20 px in the mobile top bar. 18 px in mobile list rows and sheet rows. The 13 px icon became 14. Auth card (22) and the empty-state glyph (28) stay as illustration sizes |
+| Control height (button, input, select) | 28, 32, 40 (inputs in API keys, Integration, Images) | 32 px / 44 px. Inline row buttons 28 px on desktop, 44 px on mobile. The 40 px inputs became 32 / 44 |
+| Dialog | top offset 120 and 140, centered (export), padding 20 | width 460 (560 wide, 640 crop), 140 px from the top, header 20 24 0, body 20 24 0, footer 20 24 |
+| Table row | 40, 48, 56 | 48 px; media rows 56 px (thumbnail); mobile 56 px |
+
+## Pairings
+- Selected rows use `--rc-sand` with `--rc-on-sand` text and icon in both themes. Hover, focus-visible and active on a selected row keep sand. Focus adds a 2 px `--ui-primary` outline.
+- Child selected: the parent row is not filled. It uses `--ui-text-highlighted`, weight 500, chevron down.
+- Focus-visible: 2 px `--ui-primary`, offset 2 px (inset -2 px for tabs, segmented controls and rows).
+- Disabled: 40% opacity (table rows 55%).
+- Hover, active and the rest: board "States matrix: controls" (`StatesMatrix.dc.html`). Hover and active tokens: primary button hover `--ui-text`, active `--ui-text-toned`; secondary and ghost hover `--ui-bg-elevated`, active `--ui-bg-accented`; destructive hover opacity 0.85, active 0.75; input hover border `--ui-text-muted`, focus border `--ui-primary`.

docs/design/media-field-changes.md

@@ -0,0 +1,121 @@
+# Media field type: change list for implementation
+
+Board: `RenewCMS Screens Schema.dc.html`. Frames changed: `SchemaFrame.dc.html`, `MediaFrame.dc.html`. Spec data: `schema-spec.js` (states) and `media-field-tables.js` (tables, appended to the board). No new tokens, no new colors, radius 0.
+
+## 1. Behaviour
+- New field type `media`, name "Media", icon `lucide:image`, description "One image from your media library".
+- Stored value: id of a library image, or null. The file is never copied. The field always shows the current library image.
+- Options: label, key, required. No default, unique, min, max or choices. The inspector hides them.
+- Required: the entry can't be saved while the field is empty (422 invalid_entry, rule required).
+- A saved field's type never changes. Key and type are locked after the first save (existing rule).
+- Adding a required media field to a type with entries is refused, because a media field can't have a default. The review step shows this before the server is asked.
+- Image deleted while entries point at it: the entry keeps the id. The control shows the missing state. Saving is refused only if the field is required.
+- Entries count as uses of an image in Media. Deleting a used image is allowed after a warning.
+- Variants: the editor preview uses the original. No variant select in the field. Nothing about variants in the builder.
+- Galleries (several images) are out of scope and not drawn.
+
+## 2. New component: MediaFieldControl
+Props: label, required, modelValue (image id or null), image (filename, width, height, size, or `missing: true`), disabled, error. Emits `update:modelValue`. Opens the picker.
+Nuxt UI v4: `UFormField` (label, help, error, required), `UButton` outline ("Pick an image", "Change image", "Choose another image"), `UButton` ghost ("Remove", "Clear"), `UModal` on desktop and bottom `UDrawer` on mobile for the picker, `UTooltip` for the list placeholder and the badge, `UIcon` lucide:image, image-off, unlink, image-plus. The thumbnail is a plain `button`.
+
+States and measurements (SchemaFrame `MCtl`):
+| State | Drawing |
+|---|---|
+| Empty | Dashed box (1px dashed `--ui-border-accented`), padding 12, 40 px icon square (`--ui-bg-elevated`), "No image selected.", button "Pick an image" (icon image-plus). Mobile: stacked, 44 px button |
+| Filled | Solid 1px `--ui-border-accented` box, padding 12. Thumbnail 160 × 120 (mobile: full width, 16:9). Filename weight 500, then "1600 × 900 · 240 KB" 12/18 muted. Buttons "Change image" (outline, icon image) and "Remove" (ghost, icon x). Help line "One image from your library." |
+| Hover (desktop) | Border `--ui-text-muted`. Bottom bar 28 px, `--ui-bg-inverted` with `--ui-text-inverted`, icon image 14 and "Change image". No hover on mobile |
+| Focus | 2 px `--ui-primary` outline, offset 2, on the thumbnail button |
+| Error | Box border `--ui-error` plus inset 1px `--ui-error`, error line with circle-alert 14: "Pick an image for Thumbnail." Focus ring on the first button (Pick an image, or Choose another image) |
+| Missing | Dashed 160 × 120 (mobile 16:9) placeholder with image-off 24. Text "This image is no longer in the library" (weight 500). Help: optional "You can still save. The entry keeps the link until you change it." / required "Thumbnail is required. Choose another image to save." Buttons "Choose another image" (outline) and "Clear" (ghost) |
+| Saving | Thumbnail at 60%, buttons at 40%, all form fields disabled, Save reads "Saving…" |
+| Read-only (fields changed) | Same as saving, plus warning alert "The fields of Events changed" and button "Reload form" |
+
+Label is the field label, plus " *" when required (existing form rule; "(optional)" is not used).
+
+## 3. Per screen
+
+### 3.1 Schema list (group 1), state "Custom type: read-only view"
+Fields table of a custom type (Label, Key, Type, Rules) in the built-in table style. Thumbnail row: image icon, key `thumbnail`, type "Media", rules "One image from the library". Header "Events" with badge "Read only" (lock). Alert: "You can read these fields here" / "Only an owner or admin can change a content type." The built-in Media type in Schema is unchanged. Decision needed: no route shows a custom type read-only today.
+
+### 3.2 Schema builder (group 2), 3 states
+- "Media field selected": saved Thumbnail row selected (index 7). Inspector: Label, Key (locked, "Used in the API, so it can't change."), Type tiles (seven, Media selected, others dimmed with "Can't change after saving"), Required switch ("Required" / "An entry can't be saved with this field empty."). Hidden for media: Unique values, Default value, limits, choices. Hint (info-soft block, info icon): "Holds one image from the media library. Entries link to the image instead of keeping a copy, so they always show its current version."
+- "New media field, seven types": new row with "New" badge, key editable ("The name used in the API. Starts with a letter. Lowercase letters, digits and underscores."), type tiles all enabled. State chip "Unsaved changes".
+- "Media field, required": row shows the existing Required marker.
+- Field row: grip, 28 px icon square (image), label, key (mono), badges. Mobile: inspector in the existing 92% sheet (title "Field: Thumbnail", footer "Done").
+- Type tile grid now has seven tiles (3 columns desktop inspector, 2 in sheets).
+
+### 3.3 Review (group 3), 2 states
+Dialog "Review changes to Events" / "Apply them to save the content type." Summary "Add 1 field" / "Events has 12 entries. Each one is checked against the new fields when you apply." The info bar in the builder behind reads "12 entries use this content type…".
+- Refused: row "Add Thumbnail", warning flag "Can't be applied", text "Media, required. A media field can't have a default, so the 12 existing entries would have no image. Make Thumbnail optional to add it." Note "Back to editing keeps your other changes." Buttons "Back to editing", "Apply changes" (disabled). This departs from the existing review (Apply is never disabled): decision.
+- Clean: row "Add Thumbnail", "Media, optional. 12 entries are unaffected." Apply enabled.
+
+### 3.4 Field types (group 4), state "Media"
+Per-type frame like the others: header icon image, "Media", "One image from your media library", `type: "media"`. Columns: inspector options, entry form control (filled with hover, then empty), list cell (Filled thumbnail, Empty "–", Image missing), errors by rule, filter (later).
+Errors by rule: required 422 "Pick an image for Thumbnail."; type 422 "Thumbnail must be an image from the library."; min, max, options, unique: "Not used for media." Filter widget: "Thumbnail: has an image" with Any / Has an image / No image, tagged Later.
+
+### 3.5 Entry list (group 5), 3 states
+Columns shown: Title, Thumbnail, Starts on, Category (user choice). Header "Thumbnail", no sort icon, column 80 px. Cell: 40 px square thumbnail; "–" when empty; dashed 40 px square with unlink icon, accessible name "Image no longer in the library", when the image is gone. Row height stays 48 px (thumbnail fits with 4 px above and below). Mobile card: 32 px thumbnail leads the card (empty: "–", missing: dashed square), card min height 68 px. Columns menu lists Thumbnail with the image icon ("4 of 6", "Choose up to 6 fields to show. 4 selected." on mobile). Tooltip on the missing placeholder (desktop): "Image no longer in the library".
+
+### 3.6 Entry editor (group 6), 10 states
+Control sits after Description, at the end of the form (schema order; see conflicts). States: empty optional, empty required, filled, hover, focus, validation error (status chip "Not saved"), image no longer in the library, missing + required (error), saving, read-only. The board scrolls the form so the control is visible in the frame; the real form is not scrolled.
+
+### 3.7 Picker (group 10), 8 states, MediaFrame field mode
+Existing picker (Upload and Library tabs, single selection, search "Search by filename", "Newest first · 48 images", Load more, 4 columns desktop and 3 on mobile, square tiles). Differences:
+- Title "Choose an image".
+- Primary "Use this image" (disabled until a tile is chosen). When "No image" is chosen it reads "Remove image".
+- No alt text field, no variant select. Selected strip shows thumbnail, filename, "dimensions · size".
+- Current image tile badge "Current" (replaces "In this article").
+- Optional fields only: row "No image" / "Leave this field empty." at the top of the Library tab. Selected: sand fill, primary border, check.
+- Empty: "Your library is empty" / "Images you upload appear here, ready to use in any article or entry." / "Upload an image".
+- Failed: "Couldn't load your library" / "Check your connection and try again." / "Try again".
+- Loading: skeleton tiles after 150 ms.
+- Upload tab: unchanged flow (crop, resize); the new image lands in the library and is selected.
+- Desktop dialog 640 wide, mobile bottom sheet.
+
+### 3.8 Media library (group 11), 4 states
+- Badge "Used in N" = articles + entries. The tooltip (hover or focus) reads "Used in entries: 3" and, if articles also use it, "Used in articles: 2" on the first line. Example: bathroom-tiles.png, 3 entries, "Used in 3".
+- List view: same badge in the list row and mobile card.
+- Detail panel (lime-plaster.jpg, 2 articles, 5 entries): preview is shorter when the image has entries; existing "Used in 2 articles" list; new section "Used in entries" with up to 3 rows (type name muted, entry title as link, arrow-up-right) and "and 2 more". When there are entries the empty-articles line reads "No article shows it." (not "safe to delete").
+- Delete: title "Delete an image that's in use?" (existing in-use dialog), body `"lime-plaster.jpg" is used in 5 entries and 2 articles. Those entry fields will show "This image is no longer in the library", and the articles will show a broken image. This can't be undone.` with the entries and articles lists; "Cancel" and destructive "Delete image".
+
+## 4. Copy added (exact)
+Media · One image from your media library · Holds one image from the media library. Entries link to the image instead of keeping a copy, so they always show its current version. · No image selected. · Pick an image · Change image · Remove · Choose another image · Clear · One image from your library. · This image is no longer in the library · You can still save. The entry keeps the link until you change it. · Thumbnail is required. Choose another image to save. · Pick an image for Thumbnail. · Thumbnail must be an image from the library. · Not used for media. · Image no longer in the library · Choose an image · Use this image · Remove image · Current · No image · Leave this field empty. · Used in entries · and 2 more · Used in entries: 3 · Can't be applied · Media, required. A media field can't have a default, so the 12 existing entries would have no image. Make Thumbnail optional to add it. · Media, optional. 12 entries are unaffected. · The Thumbnail field was changed after you opened this form. Reload the form to continue. What you typed here can't be saved against the old fields.
+Sentence case, "image" never "asset", buttons are verbs.
+
+## 5. API and backend
+- Schema API accepts type `media` with label, key, required. Value: image id or null.
+- 422 invalid_entry: required → "Pick an image for Thumbnail."; type (id not in the library on a changed value) → "Thumbnail must be an image from the library."
+- Entry and list responses include, per media field, filename, width, height, size and a thumbnail URL, or `missing: true`.
+- GET /v1/media/{id}/usage returns articles and entries (content type name, key, entry id, title), a total and the first few items. GET /v1/media/ list items carry the combined use count.
+- DELETE /v1/media/{id} stays allowed for used images. Entries keep the id.
+- A new required media field on a type with entries is refused (schema_incompatible). The client shows the refusal first.
+
+HTTP to copy (picker and field), from states.md: 400 "That request wasn't valid. Check the fields and try again."; 401/403 global; 404 "That item no longer exists."; 409 "This changed somewhere else. Reload and try again."; 413 "That file is too large."; 429 "Too many requests. Try again in a few minutes."; 500/network "Something went wrong on our side. Nothing was changed. Try again in a moment."
+
+## 6. Accessibility
+- Control is `role="group"` labelled by the field label. Required: `aria-required` on the main button.
+- Names: "Pick an image for Thumbnail"; thumbnail "Change image, lime-plaster-workshop.jpg, 1600 by 900, 240 KB"; "Remove image from Thumbnail"; "Clear Thumbnail"; missing placeholder `role="img"` "Image no longer in the library".
+- Error: error text has an id. The main button gets `aria-invalid="true"` and `aria-describedby` (error id, then help id). Focus moves to the first invalid control on a refused save.
+- Order: label, thumbnail, Change image, Remove, help or error. The thumbnail duplicates Change image; use `tabindex="-1"` on it if one stop is preferred.
+- One polite live region: "Image selected: lime-plaster-workshop.jpg", "Image removed from Thumbnail.", "Thumbnail cleared."
+- Focus: Use this image → Change image. Remove or Clear → Pick an image. Cancel or Esc → the opener.
+- Picker: tiles are buttons with `aria-pressed`, names "stone-steps.jpg, 310 KB, Current". "No image" has `aria-pressed`. "Use this image" uses `aria-disabled`.
+- Contrast: Current badge and selected rows use `--rc-on-sand`; hover bar 18.9 (inverted pair). 44 px targets on mobile. No hover on mobile.
+
+## 7. Conflicts to decide
+1. Row height: design is 48 px (56 px media rows, 68 px cards), not 32 px. Drawn at 48 and 68.
+2. Thumbnail position: existing form has Description last. Drawn after Description (end of form).
+3. "Used in N" counted articles. Now articles + entries.
+4. Delete title: existing in-use title kept; "Delete this image?" stays for unused images.
+5. "Clear" vs glossary "Remove".
+6. "1600 × 900 · 240 KB" (design separator) instead of "1600 x 900 - 240 KB".
+7. Review step disables Apply for the certain refusal; existing review never does.
+8. Picker button "Use this image" vs article picker "Insert image"; "Remove image" when No image is chosen is my addition.
+9. "Pick an image" also on optional empty fields.
+10. No read-only route for custom types.
+11. Two tab stops for the same picker (thumbnail and Change image).
+12. Disabled opacity: form 60%, foundations 40%.
+13. The picker frame shows a stand-in entry form, not the real editor.
+
+## 8. Not done
+README.md, states.md and the screens/*.md files are not updated with the new counts (group 2 +3, 3 +2, 4 +1, 5 +3, 6 +10, 1 +1, new groups 10 (8) and 11 (4): 32 states). Light/dark and mobile frames were checked by reading the DOM, not state by state on screen.

docs/design/routes.md

@@ -0,0 +1,83 @@
+# Routes
+
+| Route | Screen | Query | API |
+|---|---|---|---|
+| /settings | Settings (Version, Media card, Media cleanup, Retention) | none | GET/PATCH /v1/media/purge-settings, GET/PATCH /v1/settings |
+| /settings/media/variants | Image variants (admin) | none | GET/PATCH/DELETE /v1/image-variants, POST /v1/image-variants/{name}/purge |
+| /settings/media/cache | Cache (admin) | none | GET /v1/image-variants/cache, POST /v1/image-variants/cache/purge {scope: all|unused|variant|image} |
+| /media | Media library | page, size, q, filter, sort, view | GET /v1/media/?page=&size=&q=&filter=&variants=&sort= (page, size; total in the `X-Total-Count` header) |
+| /media (detail) | Variants tab | none | GET /v1/media/{id}/variants, POST and DELETE /v1/media/{id}/variants/{name} |
+| /articles | Articles list | page, size, tab, q | GET /v1/article/?page=&size=&q=&status= (page, size; total in the `X-Total-Count` header; array body unchanged) |
+| /activity | Activity | q, actor, category, outcome, security, range, from, to, page, size | GET /v1/activity (page, size), GET /v1/activity/export (shipped, CSV) |
+| /integration | Integration | none | none |
+| /settings/sites | Sites (owner only; other roles get a 403 page and no sidebar entry): list, add and edit slide-over, delete with reassignment. The key is read-only after creation | none | GET/POST /v1/site/, PATCH/DELETE /v1/site/{id} (DELETE takes `reassign_to`) |
+| /authors | Authors, all roles. Owner and admin: list, search, add and edit slide-over, delete with reassignment. Other roles: read-only list and detail | q, page, size | GET/POST /v1/author/, PATCH/DELETE /v1/author/{id}, POST /v1/author/me |
+| /articles | Articles list gains Authors column; Site column and filter when more than one site | site | GET /v1/article/?site={key} |
+| /article/:id/edit | Editor gains the "Site and authors" section (Site select and authors, any role that can edit the article) | none | PATCH /v1/article/{id} {site_id, author_ids[]} |
+| /profile | Profile gains the "Author profile" card, all roles | none | POST /v1/author/me |
+| /integration/api-keys | API keys | none | GET/POST /v1/api-key, DELETE /v1/api-key/{id} |
+| /schema | Schema list, custom and built-in types (owner or admin; others get a 403 page and no sidebar entry). Available now | none | GET /v1/content-type |
+| /schema/new | Schema builder, new type (owner or admin). Available now | none | POST /v1/content-type |
+| /schema/:key | Schema builder for a custom type, read-only view for a built-in (owner or admin). Review step on save when the type has entries. Available now | none | GET/PUT/DELETE /v1/content-type/{key} |
+| /content/:key | Entry list (any verified user). Available now | page, size, sort | GET /v1/content-type/{key}, GET /v1/content-type/{key}/entry?page=&size=&sort= |
+| /content/:key/new | New entry (any verified user). Available now | none | POST /v1/content-type/{key}/entry |
+| /content/:key/:id | Entry editor (any verified user). Available now | none | GET/PUT/DELETE /v1/content-type/{key}/entry/{id} |
+| /settings/permissions | Retired. 301 to /settings/roles (see Roles and permissions below) | none | not built |
+
+## Pagination in the URL (Articles, Media)
+`/articles?page=2&size=50` and `/media?page=7&size=50`. Parameter names follow the repo (activity already uses `page` and `size`). Allowed sizes 5, 25, 50, 100. Defaults `page=1`, `size=25`, omitted from the URL when default. Changing search, tab, filter or size resets `page` to 1. `page` above the last page redirects (replace) to the last page and shows "That page doesn't exist. Showing the last page." An invalid `size` falls back to 25.
+**API:** `GET /v1/article/` accepts `page` (default 1) and `size` (5, 25, 50, 100; default 25), as `GET /v1/activity` does. The body stays a JSON array so existing consumers keep working; the total comes back in `X-Total-Count` (the response shape is to be confirmed with the specifier). Anonymous callers only see online articles, and the total counts only those. Invalid `page` or `size` answers 400, the same as Activity.
+
+**Media API:** `GET /v1/media/` takes the same `page` and `size`, with the same 400 and the total in `X-Total-Count`; the array body stays. The earlier `cursor` and `limit` parameters are replaced by them.
+
+**Page size memory:** the size chosen on Articles, Activity or Media is remembered for the user and used when the URL has no `size`; an explicit `size` in the URL wins.
+
+**SPA:** never shows that 400. A `size` outside 5, 25, 50, 100 or a `page` that is not a positive integer is replaced in the URL by the default (`history.replace`), silently. A `page` past the last page is replaced by the last page and the notice "That page doesn't exist. Showing the last page." appears.
+
+## Activity pagination
+`page` and `size`, allowed sizes 5, 25, 50, 100, default 25 (as implemented).
+
+## Activity export
+`GET /v1/activity/export`: implemented. CSV only, synchronous (one streamed download, no job, no progress, no later notification). Accepts the list filters q, actor, category, outcome, security, range, from, to. Owner and admin only; others get 403. "Export current view" calls it with the active filters. "Export all activity" calls it with no filters and an optional `from`/`to` range. JSON (`format=json`) is **proposed**: new backend feature.
+
+## Public image request
+`/media/photo.png?v=<variant-name>`. Unknown or disabled variant: 400 `{ "status": 400, "error": "unknown_variant", "message": "Unknown variant", "detail": "<name>" }`. Any other query parameter: 400 `{ "status": 400, "error": "unsupported_parameter", "message": "Unsupported parameter", "detail": "<parameter>" }`. Missing source image: 404.
+
+## Sites and authors in the URL
+`/articles?site=journal` filters by site key; it combines with `page`, `size`, `tab` and `q`, and resets `page` to 1 when it changes. An unknown key is dropped from the URL with no error. `/authors?q=camille&page=2&size=25` follows the same pagination rules as Articles. Deep links: `/authors?edit={slug}` and `/settings/sites?edit={key}` open the slide-over for owner and admin (authors) and the owner (sites); an unknown value shows the info toast "That author no longer exists" or "That site no longer exists". For other roles `/authors?edit={slug}` opens the read-only detail, and `/settings/sites` and its `?edit=` link show the 403 page "You don't have access to Sites".
+
+Sites pagination: `/settings/sites?q=&page=&size=` with the same rules as Articles (sizes 5, 25, 50, 100; default 25; defaults omitted; search and size changes reset to page 1; a page past the end falls back to the last page). API: GET /v1/site/?q=&page=&size=, total in `X-Total-Count` (design assumption). Authors: `/authors?q=&page=&size=` as above.
+
+## SEO
+No new page routes. The panel and dialog are overlays on `/article/:id/edit`: `?panel=seo` (optionally `&field=seo_title|seo_description|slug|cover|authors|body` for the suggestion jump) and `?dialog=seo-api`. `/articles?seo=suggestions` is the Needs attention filter. API: GET /v1/article/{id}/seo, GET /v1/site/{key}/sitemap?page=&size=, PATCH /v1/article/{id} (new fields), PATCH /v1/site/{id} {site_name, title_template, default_description, social_image_id, default_robots}, GET /v1/article/?seo=ready|suggestions|hidden. 401 without a session; 403 owner_only on site SEO fields; 409 slug_taken {suggestion} on PATCH slug; 400 on invalid canonical_url or title_template.
+
+## Custom content types in the URL
+`/content/events?page=2&size=50&sort=created_at:desc`. `page` and `size` follow Articles (sizes 5, 25, 50, 100; default 25). `sort` is one parameter, `<id|created_at|updated_at>:<asc|desc>`, default `updated_at:desc`. Defaults are omitted from the URL; a size or sort change resets `page` to 1; invalid values are replaced silently by the default; a `page` past the end falls back to the last page. The response carries `total`, `page`, `size` and `sort`: use them for the summary ("Showing 1–5 of 37"), the pager and the "37 entries use this content type" line of the review step. No filter or search on custom fields yet. Auth: `/schema*` owner or admin (403 page otherwise), `/content*` any verified user (unverified accounts are redirected to /register/pending). Unknown type: 404 content_type_not_found page. Unknown entry: 404 entry_not_found page.
+
+## Roles and permissions
+
+| Route | Purpose | Access |
+|---|---|---|
+| /settings/roles | Roles list | Roles: view |
+| /settings/roles/new | New role | Roles: manage |
+| /settings/roles/:id | Role editor (read-only without manage) | Roles: view |
+| /settings/permissions | Retired. 301 to /settings/roles | n/a |
+
+API: GET/POST /v1/role · GET/PUT/DELETE /v1/role/{id} · POST /v1/role/{id}/reassign · PUT /v1/user/{id}/role · POST /v1/site/transfer-ownership · GET /v1/me · GET /v1/permission. Errors: 403 missing_permission, 403 role_locked, 409 role_has_members, 409 role_name_taken, 409 role_conflict.
+
+Needs backend:
+| Item | Detail |
+|---|---|
+| Role storage | Table role (id, name, description, built_in, locked, version) and role_permission (role_id, key, scope none|own|all). One role_id on user. Built-ins seeded and non-deletable. |
+| Endpoints | GET/POST /v1/role · GET/PUT/DELETE /v1/role/{id} · POST /v1/role/{id}/reassign · PUT /v1/user/{id}/role · POST /v1/site/transfer-ownership · GET /v1/me (role and permissions) · GET /v1/permission (catalogue) |
+| created_by | Add created_by (user id) to articles and entries so Own scope can be checked on read, update, delete and publish. Backfill from existing author or activity data. |
+| Enforcement | Server checks every call against role permissions and the no-escalation rules. API keys resolve the creator's current role on each request. |
+| Version field | role.version for the conflict state (409 role_conflict). |
+| Activity events | role.create, role.edit (with a diff of added and removed permissions), role.delete, role.reassign, user.change_role, user.transfer_ownership. Present tense, as the backend emits them. |
+
+## Account: change email, export, delete
+| Route | Screen | Auth | API (assumed) |
+|---|---|---|---|
+| /account/email/confirm?c=CODE | Verify new email (AuthCard). States in screens/account.md | Session required; without one, inline log in (as /register/validate) | POST /v1/auth/email/confirm |
+| /profile | Gains change email, Your data, Danger zone | Any verified user | POST /v1/auth/email/change, POST /v1/auth/email/resend, DELETE /v1/auth/email/change, GET /v1/user/me/export, DELETE /v1/user/me |
+| /login?reason=account-deleted | One-time message after deletion | Public | none |