feat(cabana): add backend user avatars to My account and the top bar

- cabana.BackendUser is an attach.Owner (MorphName Backend\Models\User, cabana.BackendUserMorphType) with one public attachOne avatar (cabana.BackendUserAvatarField), as WinterCMS stores it - POST /account/avatar stores one file_data image (jpg, jpeg, png, gif or webp, image guard, at most cabana.AvatarMaxBytes = 2 MiB, under a server-generated name) and replaces the previous avatar: old rows are deleted in the transaction, their blobs after the commit - DELETE /account/avatar removes the avatar and is idempotent - GET /auth/me and the account routes return avatar {url, thumb_url} (250x250 crop); cabana.BackendUserAvatar lets plugins read it - swag annotations, regenerated admin.json and schema.d.ts; route inventories, CSRF walk (29) and OpenAPI conformance learn both routes - SPA: avatar upload and remove on My account, avatar image in the user menu trigger and header; backend::lang.myaccount avatar strings - rebuilt boardwalk dist; cabana README, users-and-permissions and admin-spa docs
2026-10-09 17:45:43 +02:00
parent 143eca5a1f
commit 64d21c8caf
25 changed files with 1012 additions and 49 deletions
--- a/modules/cabana/README.md
+++ b/modules/cabana/README.md
@@ -33,7 +33,7 @@ Schema-driven admin backend that compiles WinterCMS-style YAML list, form, filte
 - Singleton settings screens declared with `pact.HasSettings`, read and saved by `cabana.SettingsService`. A settings entry whose `Controller` field is set links to that admin controller instead: start-up fails when it also declares a model, form or model factory, or names an unknown controller; `GET /settings` lists it, with its `controller`, only to administrators who pass its permissions and may open the controller; and the singleton settings endpoints answer 404 for its code.
 - Backend navigation (`pact.HasNavigation`) and permissions (`pact.HasPermissions`), filtered per user by `cabana.Registry.Metadata`. An administrator's own `backend_users.permissions` are merged over the role's as in Winter (a `-1` denies a code the role grants). `cabana.Allows` implements the permission check with Winter's `hasAnyAccess` semantics: superusers pass, a principal needs any one of the listed codes, and wildcards match on both sides (a grant ending in `.*` covers every code with that prefix, and a required code ending in `.*` is met by any grant under it).
 - Admin authentication against WinterCMS's `backend_users` and `backend_user_roles` tables (`cabana.BackendUser`, `cabana.BackendUserRole`, `cabana.BackendUsers`): a JWT guard registered in [bouncer](../bouncer/README.md) as `backend` (a guard another plugin already registered under that name fails `cabana.Activate`), login throttling, token refresh and revocation, and two transports. API clients use a Bearer token; the SPA sends `X-Requested-With: XMLHttpRequest` and receives the token in the HttpOnly, SameSite=Strict cookie named by `cabana.AdminCookieName`. Cookie-authenticated requests that change state must carry that header, which blocks cross-site request forgery.
- My account: the signed-in administrator opens `/account` from the user menu and edits their own first name, last name, email and subtitle, and changes their password with the current one (PUT `/account`, body `cabana.AdminAccountRequest`). The row is always the token subject, never a request value, and any key outside the request type (login, role, superuser flag, permissions, activation) is a 422 on that key with nothing written. The subtitle is stored where WinterCMS keeps it, under `subtitle` in the jsonable `backend_users.metadata` column (`cabana.BackendUser.Metadata`), and is read with `cabana.BackendUser.Subtitle`, which treats NULL, `[]` and malformed metadata as an empty subtitle; saving it keeps every other metadata key. A password change ends every other session through `tokens_valid_after` and gives a cookie session a fresh cookie.
+- My account: the signed-in administrator opens `/account` from the user menu and edits their own first name, last name, email and subtitle, and changes their password with the current one (PUT `/account`, body `cabana.AdminAccountRequest`). The row is always the token subject, never a request value, and any key outside the request type (login, role, superuser flag, permissions, activation) is a 422 on that key with nothing written. The subtitle is stored where WinterCMS keeps it, under `subtitle` in the jsonable `backend_users.metadata` column (`cabana.BackendUser.Metadata`), and is read with `cabana.BackendUser.Subtitle`, which treats NULL, `[]` and malformed metadata as an empty subtitle; saving it keeps every other metadata key. A password change ends every other session through `tokens_valid_after` and gives a cookie session a fresh cookie. The same screen uploads and removes the administrator's avatar (POST and DELETE `/account/avatar`): a public attachOne in `system_files` under WinterCMS's morph name (`cabana.BackendUserMorphType`, field `cabana.BackendUserAvatarField`; `cabana.BackendUser` implements `attach.Owner` and `attach.HasRelations`), so avatar rows copied from WinterCMS are picked up as they are. Only jpg, jpeg, png, gif and webp images that pass the image check, of at most `cabana.AvatarMaxBytes` (2 MiB), are stored, under a server-generated name. Plugins read the picture with `cabana.BackendUserAvatar`.
 - A consistent JSON envelope for every response: `cabana.WriteData`, `cabana.WriteError` and `cabana.WriteErrorDetails`, typed for documentation as `cabana.Envelope`, `cabana.ListEnvelope`, `cabana.RecordEnvelope` and `cabana.ErrorEnvelope`. A body that cannot be encoded is logged and answered with the generic 500 envelope, never a success status with a truncated body.
 - OpenAPI documentation: `cabana.AdminList`, `cabana.AdminCreate` and the other `Admin*` functions have empty bodies and exist only to carry the swag annotations of each admin route.
 - Operator commands for creating administrators and resetting their passwords (see CLI commands).
@@ -46,8 +46,9 @@ All paths are relative to `<prefix>/api/v1`. A controller ID `vendor.plugin.cont
 |-----------------|---------|
 | POST `/auth/login`, POST `/auth/refresh` | Sign in (throttled) and refresh a token. Public. |
 | GET `/lang` | The `backend::lang` string bundle for the request locale. Public, so the login screen can load it. |
-| POST `/auth/logout`, GET `/auth/me` | Revoke the current token, also when its access lifetime has expired but its refresh window is open, and clear the session cookie; return the signed-in administrator (`cabana.AdminProfile`, with the `subtitle`). |
+| POST `/auth/logout`, GET `/auth/me` | Revoke the current token, also when its access lifetime has expired but its refresh window is open, and clear the session cookie; return the signed-in administrator (`cabana.AdminProfile`, with the `subtitle` and, when there is one, the `avatar` URLs as a `cabana.AdminAvatar`). |
 | PUT `/account` | Save the signed-in administrator's own first name, last name, email and subtitle and, with `current_password`, a new password (`cabana.AdminAccountRequest`); answers the `cabana.AdminProfile`. Other keys are a 422. The email must be valid, 6 to 255 characters and not equal, ignoring case, another administrator's email or login. A password needs at least 4 characters, at most 72 bytes and an equal `password_confirmation`. Needs any backend session. |
+| POST and DELETE `/account/avatar` | Upload the signed-in administrator's avatar (one multipart `file_data` part: a jpg, jpeg, png, gif or webp image of at most 2 MiB; anything else is a 422 on `avatar`, a body over the cap a 413) replacing the previous one, or remove it (also 200 when there is none). Both answer the `cabana.AdminProfile`. Needs any backend session. |
 | GET `/navigation`, GET `/settings` | Navigation and settings entries the administrator may open; a settings entry's `controller` names the admin controller a link entry opens and is empty for a singleton form. |
 | GET `/settings/{code}/schema`, GET and PUT `/settings/{code}` | Settings form schema, values and update. |
 | POST `/markdown/preview` | Render `{markdown}` through `cabana.RenderMarkdown` for the form preview and answer `{html}`; a refused output is a 422 `validation_failed` on `markdown`. Needs any backend session. |
@@ -217,7 +218,12 @@ func (p *Plugin) AdminFS() fs.FS { return adminFS }
 | `cabana.BackendUser.Subtitle` | The administrator's subtitle, `backend_users.metadata.subtitle`; empty for NULL, `[]`, malformed metadata or a non-string value. |
 | `cabana.AdminProfile` | The signed-in administrator returned by GET `/auth/me` and the My account routes: id, login, email, names, `subtitle`, superuser flag and role. |
 | `cabana.AdminAccountRequest` | Body of PUT `/account`: `email`, `first_name`, `last_name`, `subtitle` and the optional `current_password`, `password` and `password_confirmation`. These are the only accepted keys. |
-| `cabana.AdminAccountUpdate` | Swag annotation of the My account route. |
+| `cabana.AdminAccountUpdate` / `cabana.AdminAccountAvatarUpload` / `cabana.AdminAccountAvatarRemove` | Swag annotations of the My account routes. |
+| `cabana.AdminAvatar` | The `avatar` of a `cabana.AdminProfile`: the public `url` and the 250x250 crop `thumb_url` (left out when the thumbnail cannot be made). |
+| `cabana.AvatarMaxBytes` | Largest avatar image the upload route accepts, 2 MiB; `http.body_limits.upload_bytes` still caps the request. |
+| `cabana.BackendUserAvatar` | Returns a backend user's avatar `attach.File` (the newest avatar row), or nil when there is none; `File.URL` and `File.Thumb` give its public URLs. |
+| `cabana.BackendUserMorphType` / `cabana.BackendUserAvatarField` | The avatar's `system_files.attachment_type` (WinterCMS's `Backend\Models\User`) and `field` (`avatar`). |
+| `cabana.BackendUser.MorphName` / `cabana.BackendUser.AttachRelations` | `attach.Owner` and `attach.HasRelations` of the backend user: one public attachOne `avatar`. |
 | `cabana.Allows` | Checks a principal against required permission codes. |
 | `cabana.TxFromContext` | The transaction a write route is running in, from the context of a lifecycle hook or scope. |
 | `cabana.VirtualFieldsFromContext` | The submitted values of the form's virtual fields (`pact.FormVirtualFields`), from the context of a Form hook during a create or update; a copy, keyed by field name. |
--- a/modules/cabana/account.go
+++ b/modules/cabana/account.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"io"
 	"log/slog"
 	"net/http"
 	"slices"
@@ -13,8 +14,10 @@ import (

 	"git.golem15.com/golem15/summercms/modules/bouncer"
 	"git.golem15.com/golem15/summercms/modules/lagoon"
+	"git.golem15.com/golem15/summercms/modules/lagoon/attach"
 	"git.golem15.com/golem15/summercms/modules/phrasebook"
 	"github.com/jackc/pgx/v5/pgconn"
+	"gocloud.dev/blob"
 	"gorm.io/gorm"
 	"gorm.io/gorm/clause"
 )
@@ -23,6 +26,24 @@ import (
 // the key WinterCMS's Journal author component reads.
 const metadataSubtitle = "subtitle"

+// AvatarMaxBytes is the largest avatar image POST /account/avatar accepts:
+// 2 MiB. http.body_limits.upload_bytes still caps the whole request.
+const AvatarMaxBytes int64 = 2 << 20
+
+// avatarThumbEdge is the edge of the avatar's crop thumbnail, WinterCMS's
+// myaccount avatar size.
+const avatarThumbEdge = 250
+
+// avatarLimits are the attach.Store rules of an avatar: a raster image (jpg,
+// jpeg, png, gif or webp, a sniffed image MIME type and the decode guard) of
+// at most AvatarMaxBytes.
+var avatarLimits = attach.Limits{
+	MaxBytes:   AvatarMaxBytes,
+	Extensions: attach.DefaultImageExtensions,
+	MIMETypes:  attach.AllowedImageMIMEs,
+	Image:      true,
+}
+
 // passwordMaxBytes is bcrypt's input limit: HashPassword refuses longer input.
 const passwordMaxBytes = 72

@@ -120,8 +141,10 @@ func setMetadataString(raw *string, key, value string) (*string, error) {
 }

 // profileFor is the AdminProfile of user, the payload of GET /auth/me and of
-// the My account routes.
-func (s *service) profileFor(_ context.Context, _ *gorm.DB, user BackendUser) AdminProfile {
+// the My account routes. The avatar is looked up through db; a lookup or
+// thumbnail failure is logged and leaves the avatar (or its thumb_url) out,
+// so the profile never fails on it.
+func (s *service) profileFor(ctx context.Context, db *gorm.DB, user BackendUser) AdminProfile {
 	profile := AdminProfile{
 		ID:          user.ID,
 		Login:       user.Login,
@@ -134,9 +157,60 @@ func (s *service) profileFor(_ context.Context, _ *gorm.DB, user BackendUser) Ad
 	if user.Role.ID != 0 {
 		profile.Role = &AdminRoleSummary{ID: user.Role.ID, Code: user.Role.Code, Name: user.Role.Name}
 	}
+	if db != nil {
+		profile.Avatar = s.avatarOf(ctx, db, user.ID)
+	}
 	return profile
 }

+// avatarOf is the public URL and the 250x250 crop thumbnail URL of an
+// admin's avatar, or nil when there is none. A protected row (is_public
+// false, possible only in copied data) has no public URL and is left out.
+func (s *service) avatarOf(ctx context.Context, db *gorm.DB, userID uint) *AdminAvatar {
+	f, err := BackendUserAvatar(ctx, db, userID)
+	if err != nil {
+		slog.Default().WarnContext(ctx, "cabana: avatar lookup failed", "admin_id", userID, "error", err)
+		return nil
+	}
+	if f == nil || !f.Public() {
+		return nil
+	}
+	out := &AdminAvatar{URL: f.URL()}
+	if bucket := s.bucket(); bucket != nil && slices.Contains(attach.AllowedImageMIMEs, f.ContentType) {
+		thumb, err := f.Thumb(ctx, bucket, avatarThumbEdge, avatarThumbEdge, "crop")
+		if err != nil {
+			slog.Default().WarnContext(ctx, "cabana: avatar thumbnail failed", "admin_id", userID, "file_id", f.ID, "error", err)
+		} else {
+			out.ThumbURL = thumb
+		}
+	}
+	return out
+}
+
+// BackendUserAvatar returns a backend user's avatar: the newest system_files
+// row with attachment_type cabana.BackendUserMorphType, field
+// cabana.BackendUserAvatarField and the user's id, or nil, nil when there is
+// none. Plugins call it to show an author's picture (File.URL, File.Thumb).
+func BackendUserAvatar(ctx context.Context, db *gorm.DB, userID uint) (*attach.File, error) {
+	if db == nil {
+		return nil, errors.New("cabana: avatar lookup without a database")
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	var files []attach.File
+	err := db.Session(&gorm.Session{NewDB: true, Context: ctx}).
+		Where("attachment_type = ? AND field = ? AND attachment_id = ?", BackendUserMorphType, BackendUserAvatarField, uitoa(userID)).
+		Order("id DESC").Limit(1).Find(&files).Error
+	if err != nil {
+		return nil, err
+	}
+	if len(files) == 0 {
+		return nil, nil
+	}
+	return &files[0], nil
+}
+
 // accountPrincipal is the signed-in backend principal, or nil after a 401
 // was written.
 func accountPrincipal(w http.ResponseWriter, r *http.Request) *bouncer.Principal {
@@ -430,3 +504,208 @@ func (s *service) writeAccountError(w http.ResponseWriter, r *http.Request, err
 	}
 	writeCRUDError(w, err)
 }
+
+// avatarCap is the request body cap of an avatar upload: AvatarMaxBytes plus
+// the multipart framing, lowered to http.body_limits.upload_bytes.
+func (s *service) avatarCap() int64 {
+	limit := AvatarMaxBytes + multipartOverhead
+	if s != nil && s.uploadBytes > 0 && s.uploadBytes < limit {
+		limit = s.uploadBytes
+	}
+	return limit
+}
+
+// detachAvatars deletes every avatar row of an admin inside tx and returns
+// the blob keys of the originals and their thumbnails. The rows are locked
+// first; the caller deletes the blobs after the commit.
+func detachAvatars(ctx context.Context, tx *gorm.DB, userID uint, keep uint) ([]string, error) {
+	var rows []attach.File
+	err := tx.Session(&gorm.Session{NewDB: true, Context: ctx}).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("attachment_type = ? AND field = ? AND attachment_id = ? AND id <> ?", BackendUserMorphType, BackendUserAvatarField, uitoa(userID), keep).
+		Order("id").Find(&rows).Error
+	if err != nil || len(rows) == 0 {
+		return nil, err
+	}
+	ids := make([]uint, 0, len(rows))
+	var keys []string
+	for _, f := range rows {
+		ids = append(ids, f.ID)
+		keys = append(keys, attach.BlobKeys(f)...)
+	}
+	if err := tx.Session(&gorm.Session{NewDB: true, Context: ctx}).Where("id IN ?", ids).Delete(&attach.File{}).Error; err != nil {
+		return nil, err
+	}
+	return keys, nil
+}
+
+// deleteAvatarBlobs removes detached avatar blobs once tx has committed; a
+// failure is logged and never fails the request.
+func deleteAvatarBlobs(ctx context.Context, tx *gorm.DB, bucket *blob.Bucket, userID uint, keys []string) {
+	if len(keys) == 0 {
+		return
+	}
+	lagoon.AfterCommit(ctx, tx, func(ctx context.Context, _ *gorm.DB) {
+		if bucket == nil {
+			slog.Default().WarnContext(ctx, "cabana: no storage bucket; blobs of a removed avatar were kept", "admin_id", userID)
+			return
+		}
+		if err := attach.DeleteKeys(context.WithoutCancel(ctx), bucket, keys); err != nil {
+			slog.Default().WarnContext(ctx, "cabana: deleting a removed avatar's blobs failed", "admin_id", userID, "error", err)
+		}
+	})
+}
+
+// avatarUpload serves POST /account/avatar: one multipart file_data part,
+// stored through attach.Store as a public image of at most AvatarMaxBytes
+// under a server-generated disk name, attached to the signed-in admin as the
+// avatar attachOne. The previous avatar row is deleted in the same
+// transaction and its blobs after the commit.
+func (s *service) avatarUpload(w http.ResponseWriter, r *http.Request) {
+	principal := accountPrincipal(w, r)
+	if principal == nil {
+		return
+	}
+	db, err := s.db()
+	if err != nil {
+		slog.Default().ErrorContext(r.Context(), "cabana: avatar upload without a database", "error", err)
+		WriteError(w, http.StatusInternalServerError, "error", msgServerError)
+		return
+	}
+	bucket := s.bucket()
+	if bucket == nil {
+		slog.Default().ErrorContext(r.Context(), "cabana: avatar upload without a storage bucket")
+		WriteError(w, http.StatusInternalServerError, "error", msgServerError)
+		return
+	}
+	body := &bodyReader{r: http.MaxBytesReader(w, r.Body, s.avatarCap())}
+	r.Body = io.NopCloser(body)
+	mr, err := r.MultipartReader()
+	if err != nil {
+		writeCRUDError(w, invalidBody())
+		return
+	}
+	part, err := mr.NextPart()
+	if err != nil {
+		s.writeAvatarError(w, r, body, err)
+		return
+	}
+	if part.FormName() != "file_data" || strings.TrimSpace(part.FileName()) == "" {
+		writeCRUDError(w, invalidBody())
+		return
+	}
+	var stored *attach.File
+	var saved BackendUser
+	err = lagoon.Transaction(r.Context(), db, func(ctx context.Context, tx *gorm.DB) error {
+		// The row lock serialises concurrent avatar changes of one admin.
+		user, err := lockAccount(ctx, tx, principal.ID)
+		if err != nil {
+			return err
+		}
+		// Store keeps only a sanitized base name as file_name; the disk name
+		// and the blob key are generated, never taken from the client.
+		f, err := attach.Store(ctx, tx, bucket, attach.Upload{FileName: part.FileName(), Body: part, Public: true}, avatarLimits)
+		if err != nil {
+			return err
+		}
+		stored = f
+		// Exactly one part: anything after file_data is refused.
+		if _, err := mr.NextPart(); !errors.Is(err, io.EOF) {
+			if err == nil {
+				return invalidBody()
+			}
+			return err
+		}
+		q := tx.Session(&gorm.Session{NewDB: true, Context: ctx})
+		if err := q.Model(&attach.File{}).Where("id = ?", f.ID).Updates(map[string]any{
+			"attachment_id":   uitoa(user.ID),
+			"attachment_type": BackendUserMorphType,
+			"field":           BackendUserAvatarField,
+		}).Error; err != nil {
+			return err
+		}
+		keys, err := detachAvatars(ctx, tx, user.ID, f.ID)
+		if err != nil {
+			return err
+		}
+		deleteAvatarBlobs(ctx, tx, bucket, user.ID, keys)
+		saved = user
+		return nil
+	})
+	if err != nil {
+		// attach.Store wrote the blob before the row; a rolled-back
+		// transaction leaves it to this caller.
+		if stored != nil {
+			_ = attach.DeleteKeys(context.WithoutCancel(r.Context()), bucket, attach.BlobKeys(*stored))
+		}
+		s.writeAvatarError(w, r, body, err)
+		return
+	}
+	WriteData(w, http.StatusOK, s.profileFor(r.Context(), db, saved), map[string]any{})
+}
+
+// avatarRemove serves DELETE /account/avatar: it deletes the signed-in
+// admin's avatar rows now and their blobs after the commit. Removing an
+// avatar that is not there also answers 200.
+func (s *service) avatarRemove(w http.ResponseWriter, r *http.Request) {
+	principal := accountPrincipal(w, r)
+	if principal == nil {
+		return
+	}
+	db, err := s.db()
+	if err != nil {
+		slog.Default().ErrorContext(r.Context(), "cabana: avatar removal without a database", "error", err)
+		WriteError(w, http.StatusInternalServerError, "error", msgServerError)
+		return
+	}
+	bucket := s.bucket()
+	var saved BackendUser
+	err = lagoon.Transaction(r.Context(), db, func(ctx context.Context, tx *gorm.DB) error {
+		user, err := lockAccount(ctx, tx, principal.ID)
+		if err != nil {
+			return err
+		}
+		keys, err := detachAvatars(ctx, tx, user.ID, 0)
+		if err != nil {
+			return err
+		}
+		deleteAvatarBlobs(ctx, tx, bucket, user.ID, keys)
+		saved = user
+		return nil
+	})
+	if err != nil {
+		s.writeAccountError(w, r, err)
+		return
+	}
+	WriteData(w, http.StatusOK, s.profileFor(r.Context(), db, saved), map[string]any{})
+}
+
+// writeAvatarError maps an avatar upload failure as writeFileError does,
+// with the field name avatar: a body past the cap is 413, an attach.Store
+// refusal a 422 on avatar and a malformed multipart body a 422 on body.
+func (s *service) writeAvatarError(w http.ResponseWriter, r *http.Request, body *bodyReader, err error) {
+	var tooBig *http.MaxBytesError
+	if errors.As(err, &tooBig) || (body != nil && errors.As(body.err, &tooBig)) {
+		WriteError(w, http.StatusRequestEntityTooLarge, "payload_too_large", msgPayloadTooLarge)
+		return
+	}
+	ctx, tr := r.Context(), s.translator()
+	var detail string
+	switch {
+	case errors.Is(err, attach.ErrTooLarge):
+		detail = fieldMessage(ctx, tr, "max.file", BackendUserAvatarField, map[string]string{"max": strconv.FormatInt(AvatarMaxBytes/1024, 10)})
+	case errors.Is(err, attach.ErrFileType), errors.Is(err, attach.ErrMIMEType):
+		detail = fieldMessage(ctx, tr, "mimes", BackendUserAvatarField, map[string]string{"values": strings.Join(attach.DefaultImageExtensions, ", ")})
+	case errors.Is(err, attach.ErrNotImage):
+		detail = fieldMessage(ctx, tr, "image", BackendUserAvatarField, nil)
+	}
+	if detail != "" {
+		writeCRUDError(w, &ValidationError{Details: fieldDetail(BackendUserAvatarField, detail)})
+		return
+	}
+	if body != nil && body.err != nil {
+		writeCRUDError(w, invalidBody())
+		return
+	}
+	s.writeAccountError(w, r, err)
+}
--- a/modules/cabana/account_test.go
+++ b/modules/cabana/account_test.go
@@ -1,12 +1,26 @@
 package cabana_test

 import (
+	"bytes"
 	"encoding/json"
+	"mime/multipart"
 	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"testing"
 	"time"

+	"git.golem15.com/golem15/summercms/modules/backpack"
 	"git.golem15.com/golem15/summercms/modules/cabana"
+	"git.golem15.com/golem15/summercms/modules/compass"
+	"git.golem15.com/golem15/summercms/modules/lagoon"
+	"git.golem15.com/golem15/summercms/modules/lagoon/attach"
+	"git.golem15.com/golem15/summercms/modules/party"
+	"git.golem15.com/golem15/summercms/modules/surf"
+	"gocloud.dev/blob"
+	"gocloud.dev/blob/memblob"
+	"gorm.io/gorm"
 )

 // accountStamp is a per-run suffix for logins and emails, so the shared
@@ -91,3 +105,90 @@ func TestAccountProfileSmoke(t *testing.T) {
 		t.Fatalf("is_superuser=%v err=%v", superuser, err)
 	}
 }
+
+// avatarHandler assembles the admin router like adminHandler, with a memblob
+// attachment bucket published and an 8 MiB upload cap. withBucket false
+// leaves the bucket out.
+func avatarHandler(t *testing.T, gdb *gorm.DB, withBucket bool) (http.Handler, *blob.Bucket) {
+	t.Helper()
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "app.yaml"), []byte("name: cabana-account\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := compass.Open(compass.Options{Dir: dir, Environ: []string{"SUMMER_ENV=development", "SUMMER_ADMIN__JWT__SECRET=" + adminTestSecret}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for key, value := range map[string]any{"http.body_limits.default_bytes": 1 << 20, "http.body_limits.upload_bytes": 8 << 20} {
+		if err := cfg.Set(key, value); err != nil {
+			t.Fatal(err)
+		}
+	}
+	app := backpack.New(cfg)
+	if err := lagoon.Publish(app, adminSQL, gdb); err != nil {
+		t.Fatal(err)
+	}
+	var bucket *blob.Bucket
+	if withBucket {
+		bucket = memblob.OpenBucket(nil)
+		t.Cleanup(func() { _ = bucket.Close() })
+		if err := attach.Publish(app, bucket); err != nil {
+			t.Fatal(err)
+		}
+	}
+	h, err := surf.Assemble(app, []party.Plugin{demoPlugin{fsys: demoFS()}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return h, bucket
+}
+
+// uploadAvatar posts one multipart part (name field, file name name) to
+// POST /account/avatar with a Bearer token.
+func uploadAvatar(t *testing.T, h http.Handler, token, field, name string, data []byte) *httptest.ResponseRecorder {
+	t.Helper()
+	var buf bytes.Buffer
+	mw := multipart.NewWriter(&buf)
+	part, err := mw.CreateFormFile(field, name)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := part.Write(data); err != nil {
+		t.Fatal(err)
+	}
+	if err := mw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, adminAPI("/account/avatar"), &buf)
+	req.Header.Set("Content-Type", mw.FormDataContentType())
+	req.Header.Set("Authorization", "Bearer "+token)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	return rec
+}
+
+func TestAccountAvatarSmoke(t *testing.T) {
+	gdb := adminGorm(t)
+	h, _ := avatarHandler(t, gdb, true)
+	login := "acct-avatar-" + accountStamp()
+	insertAdmin(t, gdb, login, login+"@example.test", adminTestPassword, true, false)
+	token := signIn(t, h, login)
+
+	up := uploadAvatar(t, h, token, "file_data", "me.png", conformPNG(t))
+	if up.Code != http.StatusOK {
+		t.Fatalf("upload status=%d body=%s", up.Code, up.Body.String())
+	}
+	me := getAuth(t, h, adminAPI("/auth/me"), token)
+	got := profileOf(t, me.Body.Bytes())
+	if got.Avatar == nil || got.Avatar.URL == "" || got.Avatar.ThumbURL == "" {
+		t.Fatalf("me avatar = %+v body=%s", got.Avatar, me.Body.String())
+	}
+	del := postAuth(t, h, http.MethodDelete, adminAPI("/account/avatar"), token, nil)
+	if del.Code != http.StatusOK {
+		t.Fatalf("delete status=%d body=%s", del.Code, del.Body.String())
+	}
+	me = getAuth(t, h, adminAPI("/auth/me"), token)
+	if got := profileOf(t, me.Body.Bytes()); got.Avatar != nil {
+		t.Fatalf("avatar after delete = %+v", got.Avatar)
+	}
+}
--- a/modules/cabana/admin_openapi.go
+++ b/modules/cabana/admin_openapi.go
@@ -108,6 +108,15 @@ type AdminProfile struct {
 	Subtitle    string            `json:"subtitle"`
 	IsSuperuser bool              `json:"is_superuser"`
 	Role        *AdminRoleSummary `json:"role,omitempty"`
+	// Avatar is present when the admin has a public avatar.
+	Avatar *AdminAvatar `json:"avatar,omitempty"`
+}
+
+// AdminAvatar is an admin's avatar: the public URL of the image and of its
+// 250x250 crop thumbnail (left out when the thumbnail cannot be made).
+type AdminAvatar struct {
+	URL      string `json:"url"`
+	ThumbURL string `json:"thumb_url,omitempty"`
 }

 // AdminAccountRequest is the body of PUT /account. It documents the only keys
@@ -181,7 +190,7 @@ func AdminLogout() {}
 // AdminMe documents GET /auth/me.
 //
 // @Summary Current admin
-// @Description The signed-in admin's profile: login, email, names, the subtitle (backend_users.metadata.subtitle, "" when not set), the superuser flag and the role.
+// @Description The signed-in admin's profile: login, email, names, the subtitle (backend_users.metadata.subtitle, "" when not set), the superuser flag, the role and, when the admin has one, the avatar with its public url and the 250x250 crop thumb_url.
 // @Tags admin
 // @Produce json
 // @Security BackendBearer
@@ -209,6 +218,36 @@ func AdminMe() {}
 // @Router /account [put]
 func AdminAccountUpdate() {}

+// AdminAccountAvatarUpload documents POST /account/avatar.
+//
+// @Summary Upload my avatar
+// @Description Stores one multipart file_data part as the signed-in admin's avatar, a public attachOne (system_files attachment_type Backend\Models\User, field avatar) under a server-generated name, and replaces the previous avatar. Only jpg, jpeg, png, gif and webp images that pass the image check, of at most 2 MiB, are accepted; anything else is a 422 on avatar. A body over the upload cap answers 413 payload_too_large.
+// @Tags admin
+// @Accept multipart/form-data
+// @Produce json
+// @Security BackendBearer
+// @Param file_data formData file true "Image (jpg, jpeg, png, gif or webp, at most 2 MiB)"
+// @Success 200 {object} Envelope[AdminProfile]
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 413 {object} ErrorEnvelope
+// @Failure 422 {object} ErrorEnvelope
+// @Router /account/avatar [post]
+func AdminAccountAvatarUpload() {}
+
+// AdminAccountAvatarRemove documents DELETE /account/avatar.
+//
+// @Summary Remove my avatar
+// @Description Removes the signed-in admin's avatar and its files. Removing an avatar that is not there also answers 200.
+// @Tags admin
+// @Produce json
+// @Security BackendBearer
+// @Success 200 {object} Envelope[AdminProfile]
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Router /account/avatar [delete]
+func AdminAccountAvatarRemove() {}
+
 // AdminNavigation documents GET /navigation.
 //
 // @Summary Admin navigation
--- a/modules/cabana/contracts.go
+++ b/modules/cabana/contracts.go
@@ -9,6 +9,7 @@ import (
 	"time"

 	"git.golem15.com/golem15/summercms/modules/bouncer"
+	"git.golem15.com/golem15/summercms/modules/lagoon/attach"
 	"git.golem15.com/golem15/summercms/modules/pact"
 	"gorm.io/gorm"
 )
@@ -59,6 +60,25 @@ type BackendUser struct {

 func (BackendUser) TableName() string { return "backend_users" }

+const (
+	// BackendUserMorphType is the system_files attachment_type of a backend
+	// user's files: WinterCMS's class string, so avatar rows copied from
+	// WinterCMS match as they are.
+	BackendUserMorphType = "Backend\\Models\\User"
+	// BackendUserAvatarField is the attachOne relation (system_files.field)
+	// of a backend user's avatar.
+	BackendUserAvatarField = "avatar"
+)
+
+// MorphName implements attach.Owner with WinterCMS's class string.
+func (BackendUser) MorphName() string { return BackendUserMorphType }
+
+// AttachRelations implements attach.HasRelations: one public attachOne
+// avatar, as WinterCMS's Backend\Models\User declares it.
+func (BackendUser) AttachRelations() []attach.Relation {
+	return []attach.Relation{{Name: BackendUserAvatarField, Public: true}}
+}
+
 // Subtitle returns metadata.subtitle, the key WinterCMS's Journal author
 // component reads. NULL, blank, null, [], invalid JSON and a non-string value
 // all read as an empty subtitle.
--- a/modules/cabana/http.go
+++ b/modules/cabana/http.go
@@ -238,6 +238,8 @@ func (s *service) mount(r pact.Router) {
 		g.Get("/auth/me", s.me)
 		// My account: the signed-in admin edits their own profile.
 		g.Put("/account", requireAjax(s.accountUpdate))
+		g.Post("/account/avatar", requireAjax(s.avatarUpload))
+		g.Delete("/account/avatar", requireAjax(s.avatarRemove))
 		g.Get("/navigation", s.navigation)
 		// Form previews render through RenderMarkdown; nothing is stored.
 		g.Post("/markdown/preview", requireAjax(s.markdownPreview))
--- a/modules/cabana/openapi_conformance_test.go
+++ b/modules/cabana/openapi_conformance_test.go
@@ -366,6 +366,34 @@ func TestPhase10OpenAPIConformance(t *testing.T) {
 			}
 			return rec
 		}, into[cabana.Envelope[cabana.AdminProfile]](), nil},
+		{"POST /account/avatar", 200, "cabana.Envelope-cabana_AdminProfile", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder {
+			var buf bytes.Buffer
+			mw := multipart.NewWriter(&buf)
+			part, err := mw.CreateFormFile("file_data", "avatar.png")
+			if err != nil {
+				t.Fatal(err)
+			}
+			if _, err := part.Write(conformPNG(t)); err != nil {
+				t.Fatal(err)
+			}
+			if err := mw.Close(); err != nil {
+				t.Fatal(err)
+			}
+			rec := e.sendWith(t, http.MethodPost, "/account/avatar", buf.Bytes(), mw.FormDataContentType(), nil)
+			var body cabana.Envelope[cabana.AdminProfile]
+			if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil || body.Data.Avatar == nil || body.Data.Avatar.URL == "" {
+				t.Fatalf("avatar upload body = %s (%v)", rec.Body.String(), err)
+			}
+			return rec
+		}, into[cabana.Envelope[cabana.AdminProfile]](), nil},
+		{"DELETE /account/avatar", 200, "cabana.Envelope-cabana_AdminProfile", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder {
+			rec := e.sendWith(t, http.MethodDelete, "/account/avatar", nil, "", nil)
+			var body cabana.Envelope[cabana.AdminProfile]
+			if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil || body.Data.Avatar != nil {
+				t.Fatalf("avatar remove body = %s (%v)", rec.Body.String(), err)
+			}
+			return rec
+		}, into[cabana.Envelope[cabana.AdminProfile]](), nil},
 		{"POST /auth/logout", 200, "cabana.Envelope-cabana_AdminLogoutData", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder {
 			return e.send(t, http.MethodPost, "/auth/logout", nil, true)
 		}, into[cabana.Envelope[cabana.AdminLogoutData]](), nil},
--- a/modules/cabana/phase10_coverage_test.go
+++ b/modules/cabana/phase10_coverage_test.go
@@ -88,9 +88,11 @@ func TestPhase10Coverage(t *testing.T) {
 		}
 		sort.Strings(unsafe)
 		want := []string{
+			"DELETE /account/avatar",
 			"DELETE /{vendor}/{plugin}/{controller}/{id}",
 			"DELETE /{vendor}/{plugin}/{controller}/{id}/files/{field}/{file}",
 			"DELETE /{vendor}/{plugin}/{controller}/{id}/relations/{name}/records/{child}/files/{field}/{file}",
+			"POST /account/avatar",
 			"POST /auth/login",
 			"POST /auth/logout",
 			"POST /auth/refresh",
@@ -118,7 +120,7 @@ func TestPhase10Coverage(t *testing.T) {
 			"PUT /{vendor}/{plugin}/{controller}/{id}/relations/{name}/records/{child}/files/{field}/{file}",
 		}
 		if strings.Join(unsafe, "\n") != strings.Join(want, "\n") {
-			t.Fatalf("unsafe routes changed; extend TestPhase10CSRF (it expects 27 besides login):\n%s", strings.Join(unsafe, "\n"))
+			t.Fatalf("unsafe routes changed; extend TestPhase10CSRF (it expects 29 besides login):\n%s", strings.Join(unsafe, "\n"))
 		}
 		// The routes added in Phase 10 are safe reads: GET /lang and the shared
 		// nested pattern serving field options, filter options and relation lists.
--- a/modules/cabana/phase10_csrf_test.go
+++ b/modules/cabana/phase10_csrf_test.go
@@ -66,14 +66,14 @@ func TestPhase10CSRF(t *testing.T) {
 			}
 		})
 	}
-	// refresh, logout, account update, markdown preview, settings put, create, bulk-delete, bulk action,
+	// refresh, logout, account update, avatar upload and remove, markdown preview, settings put, create, bulk-delete, bulk action,
 	// widget action, toolbar action, update, delete, record action, link,
 	// unlink, file
 	// upload, file reorder, file caption, file remove, relation child
 	// create, update and delete, pivot update, child file upload, reorder,
 	// caption and remove
-	if unsafe != 27 {
-		t.Fatalf("walked %d state-changing routes, want 27: %v", unsafe, router.order)
+	if unsafe != 29 {
+		t.Fatalf("walked %d state-changing routes, want 29: %v", unsafe, router.order)
 	}

 	loginHandler := router.handlers[login]
--- a/modules/cabana/security_coverage_test.go
+++ b/modules/cabana/security_coverage_test.go
@@ -40,6 +40,8 @@ var phase09Routes = []adminRoute{
 	{key: "POST /auth/logout", public: true},
 	{key: "GET /auth/me"},
 	{key: "PUT /account"},
+	{key: "POST /account/avatar"},
+	{key: "DELETE /account/avatar"},
 	{key: "GET /navigation"},
 	{key: "GET /settings"},
 	{key: "GET /settings/{code}/schema"},