From 95c163e37af964a5d9f4dc202a6a1bdd581f0e20 Mon Sep 17 00:00:00 2001
From: Leo Vasanko <git@vasanko.com>
Date: Thu, 21 May 2026 23:57:48 +0000
Subject: [PATCH] Add profile picture support

- backend avatar storage and OIDC picture claims
- profile and admin UI components
- admin org cards, tests, and docs
---
 .gitignore                                    |   1 +
 docs/API.md                                   |  10 +-
 frontend/src/admin/AdminOrgDetail.vue         |  25 +-
 frontend/src/admin/AdminUserDetail.vue        |  48 +-
 frontend/src/assets/profile-generic.svg       |   5 +
 frontend/src/components/HostProfileView.vue   |   1 +
 frontend/src/components/Modal.vue             |   6 +-
 frontend/src/components/ProfilePicture.vue    | 126 +++++
 .../components/ProfilePictureEditorModal.vue  | 489 ++++++++++++++++++
 frontend/src/components/ProfileView.vue       |  56 +-
 frontend/src/components/UserBasicInfo.vue     |  30 +-
 oidc.md                                       |   8 +-
 paskia/fastapi/admin/adminapp.py              |   8 +-
 paskia/fastapi/admin/users.py                 |   4 +-
 paskia/fastapi/mainapp.py                     |   1 +
 paskia/fastapi/oid.py                         |   8 +-
 paskia/fastapi/user.py                        |  91 +++-
 paskia/util/apistructs.py                     |   9 +-
 paskia/util/avatar.py                         | 102 ++++
 paskia/util/oidjwt.py                         |  39 +-
 paskia/util/userinfo.py                       |   4 +-
 tests/conftest.py                             |  24 +
 tests/test_admin.py                           |  63 ++-
 tests/test_api.py                             | 129 ++++-
 tests/test_user.py                            | 137 ++++-
 25 files changed, 1365 insertions(+), 59 deletions(-)
 create mode 100644 frontend/src/assets/profile-generic.svg
 create mode 100644 frontend/src/components/ProfilePicture.vue
 create mode 100644 frontend/src/components/ProfilePictureEditorModal.vue
 create mode 100644 paskia/util/avatar.py

diff --git a/.gitignore b/.gitignore
index 3fe319d..1afc8db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@ dist/
 package-lock.json
 paskia.sqlite
 *.paskiadb
+*.data
 /paskia/frontend-build
 /paskia/_version.py
 coverage-html/
diff --git a/docs/API.md b/docs/API.md
index e420a5f..0f99123 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -26,13 +26,17 @@ The `validate` and `forward` endpoints take query arguments `perm=` and `max_age
 
 | Method | Path | Used for | Notes |
 |---:|---|---|---|
-| PUT | `/auth/api/user/display-name` | Update the user’s display name | Body: JSON `{ "display_name": "..." }` |
+| PATCH | `/auth/api/user/display-name` | Update the user’s display name | Body: JSON `{ "display_name": "..." }` |
+| GET | `/auth/api/user/{uuid}/profile.webp` | Canonical avatar image URL | Public on the auth host; serves `image/webp` with `ETag` and short-lived cache headers |
+| PUT | `/auth/api/user/{uuid}/profile.webp` | Upload or replace a user avatar | Multipart form with `file`; upload must already be square WebP prepared in the browser |
+| DELETE | `/auth/api/user/{uuid}/profile.webp` | Remove a user avatar | Allowed for the user, master admin, or org admin for users in the same org |
 | POST | `/auth/api/user/logout-all` | Terminate all user sessions | Clears current host cookie |
 | DELETE | `/auth/api/user/session/{session_id}` | Terminate one session | Session IDs are server-issued |
 | DELETE | `/auth/api/user/credential/{uuid}` | Delete a credential | Requires recent authentication |
 | POST | `/auth/api/user/create-link` | Create a device-add link | Requires recent authentication |
 
-These are used mostly from the user profile panel and modify the current user.
+These are used mostly from the user profile panel. The avatar route is also used by admins when managing other users.
+`GET /auth/api/user-info` includes `user.avatar_url` when the user has an uploaded avatar, using the same canonical `/auth/api/user/{uuid}/profile.webp` path.
 
 ### Admin API: `/auth/api/admin/*`
 
@@ -72,6 +76,8 @@ E.g. Org admin cannot see anything of the other orgs that he has no admin access
 | GET | `/auth/api/admin/server-config/` | Get server config | Returns rp_name, auth_host, origins |
 | PATCH | `/auth/api/admin/server-config/` | Update server config | Body: JSON with rp_name, auth_host, origins |
 
+Admins edit user avatars through the same canonical `/auth/api/user/{uuid}/profile.webp` PUT and DELETE endpoints.
+
 ### WebSockets: `/auth/ws/*`
 
 | Path | Used for | Notes |
diff --git a/frontend/src/admin/AdminOrgDetail.vue b/frontend/src/admin/AdminOrgDetail.vue
index 9458fba..d808c66 100644
--- a/frontend/src/admin/AdminOrgDetail.vue
+++ b/frontend/src/admin/AdminOrgDetail.vue
@@ -1,6 +1,7 @@
 <script setup>
 import { computed, ref } from 'vue'
 import draggable from 'vuedraggable'
+import ProfilePicture from '@/components/ProfilePicture.vue'
 import { getDirection, navigateButtonRow, focusPreferred } from '@/utils/keynav'
 
 const props = defineProps({
@@ -396,8 +397,19 @@ defineExpose({ focusFirstElement })
                 @keydown.enter="$emit('openUser', u)"
                 :title="u.uuid"
               >
-                <span class="name">{{ u.display_name }}</span>
-                <span class="meta">{{ u.last_seen ? new Date(u.last_seen).toLocaleDateString(undefined, { month: 'short', day: 'numeric', year: 'numeric' }) : '—' }}</span>
+                <ProfilePicture
+                  class="user-chip-picture"
+                  :src="u.avatar_url"
+                  :title="u.display_name"
+                  width="3.25rem"
+                  height="100%"
+                  radius="0"
+                  fallback-size="1.3rem"
+                />
+                <span class="user-chip-body">
+                  <span class="name">{{ u.display_name }}</span>
+                  <span class="meta">{{ u.last_seen ? new Date(u.last_seen).toLocaleDateString(undefined, { month: 'short', day: 'numeric', year: 'numeric' }) : '—' }}</span>
+                </span>
               </li>
             </template>
           </draggable>
@@ -418,7 +430,7 @@ defineExpose({ focusFirstElement })
 .perm-matrix-grid .role-head span { writing-mode: vertical-rl; transform: rotate(180deg); font-size: 0.65rem; }
 .perm-matrix-grid .add-role-head { cursor: pointer; }
 .roles-grid { display: flex; flex-wrap: wrap; gap: 0; margin-top: var(--space-lg); justify-content: flex-start; align-items: stretch; }
-.role-column { flex: 0 0 240px; border-radius: var(--radius-md); padding: var(--space-md); display: flex; flex-direction: column; }
+.role-column { flex: 0 0 17em; border-radius: var(--radius-md); padding: var(--space-md); display: flex; flex-direction: column; }
 .role-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: var(--space-md); }
 .role-name { display: flex; align-items: center; gap: var(--space-xs); font-size: 1.1rem; color: var(--color-heading); }
 .role-actions { display: flex; gap: var(--space-xs); }
@@ -426,9 +438,12 @@ defineExpose({ focusFirstElement })
 .plus-btn:hover { background: rgba(37, 99, 235, 0.18); }
 .user-list-wrapper { position: relative; flex: 1; display: flex; flex-direction: column; min-height: 5.5rem; }
 .user-list { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: var(--space-xs); flex: 1; }
-.user-chip { background: var(--color-accent-strong); color: var(--color-accent-contrast); border: none; border-radius: var(--radius-md); padding: 0.45rem 0.6rem; display: flex; justify-content: space-between; gap: var(--space-sm); cursor: grab; }
+.user-chip { background: var(--color-accent-strong); color: var(--color-accent-contrast); border: none; border-radius: var(--radius-md); padding: 0; display: grid; grid-template-columns: 3.25rem minmax(0, 1fr); align-items: stretch; gap: 0; cursor: grab; overflow: hidden; min-height: 3.25rem; }
 .user-chip:focus { outline: 2px solid var(--color-accent); outline-offset: 1px; }
-.user-chip .meta { font-size: 0.7rem; }
+.user-chip-picture { align-self: stretch; }
+.user-chip-body { display: flex; min-width: 0; flex-direction: column; justify-content: center; gap: 0.1rem; padding: 0.45rem 0.6rem; }
+.user-chip .name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.user-chip .meta { font-size: 0.7rem; opacity: 0.85; }
 .user-chip.sortable-ghost { opacity: 0.5; }
 .user-chip.sortable-chosen { box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2); }
 .empty-role { position: absolute; inset: 0; border: 1px dashed var(--color-border-strong); border-radius: var(--radius-md); display: flex; align-items: center; justify-content: center; pointer-events: none; }
diff --git a/frontend/src/admin/AdminUserDetail.vue b/frontend/src/admin/AdminUserDetail.vue
index 608afaf..c7ed288 100644
--- a/frontend/src/admin/AdminUserDetail.vue
+++ b/frontend/src/admin/AdminUserDetail.vue
@@ -2,6 +2,7 @@
 import { ref, computed } from 'vue'
 import UserBasicInfo from '@/components/UserBasicInfo.vue'
 import CredentialList from '@/components/CredentialList.vue'
+import ProfilePictureEditorModal from '@/components/ProfilePictureEditorModal.vue'
 import RegistrationLinkModal from '@/components/RegistrationLinkModal.vue'
 import SessionList from '@/components/SessionList.vue'
 import { useAuthStore } from '@/stores/auth'
@@ -23,6 +24,8 @@ const authStore = useAuthStore()
 const terminatingSessions = ref({})
 const hoveredCredentialUuid = ref(null)
 const hoveredSession = ref(null)
+const showPictureDialog = ref(false)
+const avatarRenderVersion = ref(0)
 
 // Convert credentials dict to array with uuid attached as 'credential'
 const credentials = computed(() =>
@@ -48,6 +51,20 @@ function handleEditName() {
   emit('editUserName', props.selectedUser)
 }
 
+function openPictureDialog() {
+  if (!props.userDetail || props.userDetail.error) return
+  showPictureDialog.value = true
+}
+
+function closePictureDialog() {
+  showPictureDialog.value = false
+}
+
+function handlePictureUpdated() {
+  avatarRenderVersion.value += 1
+  emit('refreshUserDetail')
+}
+
 async function handleDelete(credential) {
   try {
     const data = await apiJson(`/auth/api/admin/users/${props.selectedUser.uuid}/credentials/${credential.credential}`, { method: 'DELETE' })
@@ -102,7 +119,7 @@ function handleUserInfoKeydown(event) {
   event.preventDefault()
 
   if (direction === 'left' || direction === 'right') {
-    navigateButtonRow(userInfoRef.value, event.target, direction, { itemSelector: '.mini-btn' })
+    navigateButtonRow(userInfoRef.value, event.target, direction, { itemSelector: '.user-picture-btn, .mini-btn' })
   } else if (direction === 'up') {
     emit('navigateOut', 'up')
   } else if (direction === 'down') {
@@ -124,7 +141,7 @@ function handleRegActionsKeydown(event) {
     navigateButtonRow(regActionsRef.value, event.target, direction, { itemSelector: 'button' })
   } else if (direction === 'up') {
     // Move to user info edit button
-    focusPreferred(userInfoRef.value, { itemSelector: '.mini-btn' })
+    focusPreferred(userInfoRef.value, { itemSelector: '.user-picture-btn, .mini-btn' })
   } else if (direction === 'down') {
     // Move to credential list
     credentialListRef.value?.$el?.focus()
@@ -174,10 +191,22 @@ function handleBackButtonKeydown(event) {
 
 // Focus helper for external navigation
 function focusFirstElement() {
-  focusPreferred(userInfoRef.value, { itemSelector: '.mini-btn' })
+  focusPreferred(userInfoRef.value, { itemSelector: '.user-picture-btn, .mini-btn' })
 }
 
 defineExpose({ focusFirstElement })
+
+const currentPictureEndpoint = computed(() => {
+  if (!props.selectedUser?.uuid) return null
+  return `/auth/api/user/${props.selectedUser.uuid}/profile.webp`
+})
+
+const adminPictureTitle = computed(() => {
+  const username = props.userDetail?.user?.preferred_username || props.selectedUser?.preferred_username
+  const displayName = props.userDetail?.user?.display_name || props.selectedUser?.display_name
+  const label = username || displayName || 'User'
+  return `Profile Picture for ${label}`
+})
 </script>
 
 <template>
@@ -186,6 +215,9 @@ defineExpose({ focusFirstElement })
       <UserBasicInfo
         v-if="userDetail && !userDetail.error"
         :name="userDetail.user.display_name || selectedUser.display_name"
+        :avatar-url="userDetail.user.avatar_url"
+        :avatar-render-version="avatarRenderVersion"
+        avatar-clickable
         :visits="userDetail.user.visits"
         :created-at="userDetail.user.created_at"
         :last-seen="userDetail.user.last_seen"
@@ -196,6 +228,7 @@ defineExpose({ focusFirstElement })
         :role-name="userDetail.role.display_name"
         :update-endpoint="`/auth/api/admin/users/${selectedUser.uuid}/info`"
         @saved="$emit('onUserNameSaved')"
+        @avatar-click="openPictureDialog"
         @edit="handleEditName"
       >
         <div class="admin-actions">
@@ -258,6 +291,15 @@ defineExpose({ focusFirstElement })
       @close="$emit('closeRegModal')"
       @copied="onLinkCopied"
     />
+    <ProfilePictureEditorModal
+      v-if="showPictureDialog && currentPictureEndpoint"
+      :endpoint="currentPictureEndpoint"
+      :picture-url="userDetail?.user?.avatar_url"
+      :render-version="avatarRenderVersion"
+      :title="adminPictureTitle"
+      @close="closePictureDialog"
+      @updated="handlePictureUpdated"
+    />
   </div>
 </template>
 
diff --git a/frontend/src/assets/profile-generic.svg b/frontend/src/assets/profile-generic.svg
new file mode 100644
index 0000000..63604d4
--- /dev/null
+++ b/frontend/src/assets/profile-generic.svg
@@ -0,0 +1,5 @@
+<?xml version="1.0"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="340" height="340">
+<path fill="#DDD" d="m169,.5a169,169 0 1,0 2,0zm0,86a76,76 0 1
+1-2,0zM57,287q27-35 67-35h92q40,0 67,35a164,164 0 0,1-226,0"/>
+</svg>
\ No newline at end of file
diff --git a/frontend/src/components/HostProfileView.vue b/frontend/src/components/HostProfileView.vue
index 142fa79..2128b29 100644
--- a/frontend/src/components/HostProfileView.vue
+++ b/frontend/src/components/HostProfileView.vue
@@ -10,6 +10,7 @@
         <UserBasicInfo
           v-if="ctx"
           :name="ctx.user.display_name"
+          :avatar-url="authStore.userInfo.user.avatar_url"
           :visits="authStore.userInfo.user.visits"
           :created-at="authStore.userInfo.user.created_at"
           :last-seen="authStore.userInfo.user.last_seen"
diff --git a/frontend/src/components/Modal.vue b/frontend/src/components/Modal.vue
index f59db5e..a918fbc 100644
--- a/frontend/src/components/Modal.vue
+++ b/frontend/src/components/Modal.vue
@@ -1,6 +1,6 @@
 <template>
   <div class="dialog-overlay" @click="$emit('close')">
-    <div ref="dialog" class="modal-panel" @keydown="handleDialogKeydown" @click.stop>
+    <div ref="dialog" :class="['modal-panel', panelClass]" @keydown="handleDialogKeydown" @click.stop>
       <slot />
     </div>
   </div>
@@ -17,7 +17,9 @@ const props = defineProps({
   // Optional: index to help find next sibling when item is deleted
   focusIndex: { type: Number, default: -1 },
   // Optional: selector for finding siblings when restoring focus
-  focusSiblingSelector: { type: String, default: '' }
+  focusSiblingSelector: { type: String, default: '' },
+  // Optional: extra class name(s) for the modal panel
+  panelClass: { type: [String, Array, Object], default: '' }
 })
 
 const emit = defineEmits(['close'])
diff --git a/frontend/src/components/ProfilePicture.vue b/frontend/src/components/ProfilePicture.vue
new file mode 100644
index 0000000..b85df79
--- /dev/null
+++ b/frontend/src/components/ProfilePicture.vue
@@ -0,0 +1,126 @@
+<template>
+  <component
+    :is="rootTag"
+    v-bind="rootAttrs"
+    class="profile-picture"
+    :class="{ 'profile-picture-btn': clickable }"
+    :style="pictureStyle"
+    @click="handleClick"
+  >
+    <img
+      v-if="showPicture"
+      :key="`${src || 'none'}:${renderVersion}`"
+      :src="src"
+      alt=""
+      class="profile-picture-image"
+      @error="handleError"
+    />
+    <img
+      v-else
+      :src="profileGeneric"
+      alt=""
+      class="profile-picture-fallback"
+    />
+  </component>
+</template>
+
+<script setup>
+import profileGeneric from '@/assets/profile-generic.svg'
+import { computed, ref, watch } from 'vue'
+
+const props = defineProps({
+  src: { type: String, default: null },
+  clickable: { type: Boolean, default: false },
+  loading: { type: Boolean, default: false },
+  title: { type: String, default: '' },
+  renderVersion: { type: [Number, String], default: 0 },
+  width: { type: String, default: '3rem' },
+  height: { type: String, default: '3rem' },
+  radius: { type: String, default: '0.9rem' },
+  fit: { type: String, default: 'cover' },
+  filter: { type: String, default: 'none' },
+  fallbackSize: { type: String, default: '2em' }
+})
+
+const emit = defineEmits(['click'])
+const pictureAvailable = ref(true)
+
+const rootTag = computed(() => (props.clickable ? 'button' : 'div'))
+const showPicture = computed(() => !!props.src && pictureAvailable.value)
+const pictureStyle = computed(() => ({
+  '--profile-picture-width': props.width,
+  '--profile-picture-height': props.height,
+  '--profile-picture-radius': props.radius,
+  '--profile-picture-fit': props.fit,
+  '--profile-picture-filter': props.filter,
+  '--profile-picture-fallback-size': props.fallbackSize
+}))
+const rootAttrs = computed(() => {
+  if (!props.clickable) return { title: props.title || undefined }
+  return {
+    type: 'button',
+    disabled: props.loading,
+    title: props.title || undefined
+  }
+})
+
+watch(() => props.src, () => {
+  pictureAvailable.value = true
+})
+
+const handleError = () => {
+  pictureAvailable.value = false
+}
+
+const handleClick = () => {
+  if (!props.clickable || props.loading) return
+  emit('click')
+}
+</script>
+
+<style scoped>
+.profile-picture {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--profile-picture-width);
+  height: var(--profile-picture-height);
+  font-size: var(--profile-picture-fallback-size);
+  line-height: 1;
+  overflow: hidden;
+  border-radius: var(--profile-picture-radius);
+  background: transparent;
+  flex-shrink: 0;
+}
+
+.profile-picture-btn {
+  padding: 0;
+  border: 0;
+  transition: transform 0.12s ease, box-shadow 0.12s ease;
+  cursor: pointer;
+}
+
+.profile-picture-btn:hover:not(:disabled) {
+  transform: translateY(-1px);
+  box-shadow: inset 0 0 0 1px var(--color-accent);
+}
+
+.profile-picture-btn:disabled {
+  cursor: progress;
+}
+
+.profile-picture-image {
+  width: 100%;
+  height: 100%;
+  object-fit: var(--profile-picture-fit);
+  display: block;
+  filter: var(--profile-picture-filter);
+}
+
+.profile-picture-fallback {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  display: block;
+}
+</style>
diff --git a/frontend/src/components/ProfilePictureEditorModal.vue b/frontend/src/components/ProfilePictureEditorModal.vue
new file mode 100644
index 0000000..b78aff4
--- /dev/null
+++ b/frontend/src/components/ProfilePictureEditorModal.vue
@@ -0,0 +1,489 @@
+<template>
+  <Modal panel-class="modal-panel--avatar" @close="closeEditor">
+    <h3>{{ title }}</h3>
+    <input
+      ref="pictureInput"
+      type="file"
+      accept="image/*"
+      class="profile-picture-editor-input"
+      :disabled="saving"
+      @change="handlePictureSelected"
+    />
+    <div ref="picturePreview" class="profile-picture-editor-preview" :style="previewStyle">
+      <img
+        v-if="editorImageUrl && displayMetrics"
+        :src="editorImageUrl"
+        alt=""
+        class="profile-picture-editor-image"
+        :style="editorImageStyle"
+      />
+      <img
+        v-if="editorImageUrl && displayMetrics"
+        :src="editorImageUrl"
+        alt=""
+        class="profile-picture-editor-image profile-picture-editor-image--overlay"
+        :style="editorOverlayStyle"
+      />
+      <div
+        v-if="editorImageUrl && displayMetrics"
+        class="profile-picture-editor-crop"
+        :style="cropBoxStyle"
+        @pointerdown="startMove"
+      >
+        <div class="profile-picture-editor-guides" aria-hidden="true">
+          <div class="profile-picture-editor-guide profile-picture-editor-guide--circle"></div>
+          <div class="profile-picture-editor-guide profile-picture-editor-guide--eyes"></div>
+          <div class="profile-picture-editor-guide profile-picture-editor-guide--cheek-left"></div>
+          <div class="profile-picture-editor-guide profile-picture-editor-guide--cheek-right"></div>
+        </div>
+        <button
+          type="button"
+          class="profile-picture-editor-handle profile-picture-editor-handle--nw"
+          @pointerdown.stop="startResize($event, 'nw')"
+        ></button>
+        <button
+          type="button"
+          class="profile-picture-editor-handle profile-picture-editor-handle--ne"
+          @pointerdown.stop="startResize($event, 'ne')"
+        ></button>
+        <button
+          type="button"
+          class="profile-picture-editor-handle profile-picture-editor-handle--sw"
+          @pointerdown.stop="startResize($event, 'sw')"
+        ></button>
+        <button
+          type="button"
+          class="profile-picture-editor-handle profile-picture-editor-handle--se"
+          @pointerdown.stop="startResize($event, 'se')"
+        ></button>
+      </div>
+      <ProfilePicture
+        v-else
+        class="profile-picture-editor-trigger"
+        :src="pictureUrl"
+        :render-version="renderVersion"
+        clickable
+        :loading="saving"
+        title="Choose profile picture"
+        width="100%"
+        height="100%"
+        radius="0"
+        fit="contain"
+        fallback-size="5rem"
+        @click="triggerPictureSelect"
+      />
+    </div>
+    <div v-if="errorMessage" class="error small">{{ errorMessage }}</div>
+    <div class="modal-actions">
+      <button type="button" class="btn-secondary" :disabled="saving" @click="closeEditor">Back</button>
+      <button
+        v-if="!editorImageUrl && pictureUrl"
+        type="button"
+        class="btn-danger"
+        :disabled="saving"
+        @click="removePicture"
+      >Delete</button>
+      <button
+        v-if="editorImageUrl"
+        type="button"
+        class="btn-primary"
+        :disabled="saving"
+        @click="savePicture"
+      >Save</button>
+    </div>
+  </Modal>
+</template>
+
+<script setup>
+import { computed, nextTick, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
+import { apiJson } from 'paskia'
+import { useAuthStore } from '@/stores/auth'
+import Modal from '@/components/Modal.vue'
+import ProfilePicture from '@/components/ProfilePicture.vue'
+
+const AVATAR_UPLOAD_SIZE = 720
+const MIN_CROP_SIZE = 36
+
+const props = defineProps({
+  endpoint: { type: String, required: true },
+  pictureUrl: { type: String, default: null },
+  renderVersion: { type: [Number, String], default: 0 },
+  title: { type: String, default: 'Profile Picture' }
+})
+
+const emit = defineEmits(['close', 'updated'])
+const authStore = useAuthStore()
+
+const pictureInput = ref(null)
+const picturePreview = ref(null)
+const editorImage = ref(null)
+const editorImageUrl = ref('')
+const previewObjectUrl = ref(null)
+const saving = ref(false)
+const errorMessage = ref('')
+const cropRect = reactive({ x: 0, y: 0, size: 0 })
+const previewRect = reactive({ width: 0, height: 0 })
+const viewportSize = reactive({ width: 0, height: 0 })
+let dragState = null
+let previewObserver = null
+
+onMounted(async () => {
+  viewportSize.width = window.innerWidth
+  viewportSize.height = window.innerHeight
+  window.addEventListener('pointermove', handlePointerMove)
+  window.addEventListener('pointerup', endPointerInteraction)
+  window.addEventListener('resize', syncPreviewRect)
+  await nextTick()
+  syncPreviewRect()
+  if (picturePreview.value && typeof ResizeObserver !== 'undefined') {
+    previewObserver = new ResizeObserver(() => syncPreviewRect())
+    previewObserver.observe(picturePreview.value)
+  }
+})
+
+onUnmounted(() => {
+  window.removeEventListener('pointermove', handlePointerMove)
+  window.removeEventListener('pointerup', endPointerInteraction)
+  window.removeEventListener('resize', syncPreviewRect)
+  previewObserver?.disconnect()
+  clearPreviewObjectUrl()
+})
+
+watch(editorImage, async (image) => {
+  if (!image) return
+  await nextTick()
+  syncPreviewRect()
+  initializeCrop()
+})
+
+const clearPreviewObjectUrl = () => {
+  if (!previewObjectUrl.value) return
+  URL.revokeObjectURL(previewObjectUrl.value)
+  previewObjectUrl.value = null
+}
+
+const resetEditor = () => {
+  clearPreviewObjectUrl()
+  editorImage.value = null
+  editorImageUrl.value = ''
+  cropRect.x = 0
+  cropRect.y = 0
+  cropRect.size = 0
+  errorMessage.value = ''
+  if (pictureInput.value) pictureInput.value.value = ''
+}
+
+const syncPreviewRect = () => {
+  viewportSize.width = window.innerWidth
+  viewportSize.height = window.innerHeight
+  const element = picturePreview.value
+  if (!element) return
+  previewRect.width = element.clientWidth
+  previewRect.height = element.clientHeight
+}
+
+const previewStyle = computed(() => {
+  const image = editorImage.value
+  if (!image) {
+    const size = Math.min(viewportSize.width * 0.72, viewportSize.height * 0.42, 352)
+    return {
+      width: `${Math.max(160, Math.round(size))}px`,
+      height: `${Math.max(160, Math.round(size))}px`
+    }
+  }
+
+  const maxWidth = Math.min(viewportSize.width * 0.88, 928)
+  const maxHeight = Math.min(viewportSize.height * 0.62, 620)
+  const scale = Math.min(maxWidth / image.naturalWidth, maxHeight / image.naturalHeight)
+
+  return {
+    width: `${Math.max(1, Math.round(image.naturalWidth * scale))}px`,
+    height: `${Math.max(1, Math.round(image.naturalHeight * scale))}px`
+  }
+})
+
+const displayMetrics = computed(() => {
+  const image = editorImage.value
+  if (!image || !previewRect.width || !previewRect.height) return null
+  const scale = Math.min(previewRect.width / image.naturalWidth, previewRect.height / image.naturalHeight)
+  const width = image.naturalWidth * scale
+  const height = image.naturalHeight * scale
+  return {
+    x: (previewRect.width - width) / 2,
+    y: (previewRect.height - height) / 2,
+    width,
+    height
+  }
+})
+
+const editorImageStyle = computed(() => {
+  const metrics = displayMetrics.value
+  if (!metrics) return null
+  return {
+    width: `${metrics.width}px`,
+    height: `${metrics.height}px`,
+    left: `${metrics.x}px`,
+    top: `${metrics.y}px`
+  }
+})
+
+const editorOverlayStyle = computed(() => {
+  const metrics = displayMetrics.value
+  if (!metrics || !cropRect.size) return editorImageStyle.value
+
+  const left = cropRect.x
+  const top = cropRect.y
+  const right = cropRect.x + cropRect.size
+  const bottom = cropRect.y + cropRect.size
+
+  return {
+    ...editorImageStyle.value,
+    clipPath: `polygon(evenodd, 0 0, 100% 0, 100% 100%, 0 100%, 0 0, ${left}px ${top}px, ${left}px ${bottom}px, ${right}px ${bottom}px, ${right}px ${top}px, ${left}px ${top}px)`
+  }
+})
+
+const cropBoxStyle = computed(() => {
+  const metrics = displayMetrics.value
+  if (!metrics || !cropRect.size) return null
+  return {
+    left: `${metrics.x + cropRect.x}px`,
+    top: `${metrics.y + cropRect.y}px`,
+    width: `${cropRect.size}px`,
+    height: `${cropRect.size}px`
+  }
+})
+
+const initializeCrop = () => {
+  const metrics = displayMetrics.value
+  if (!metrics) return
+  const size = Math.min(metrics.width, metrics.height)
+  cropRect.size = size
+  cropRect.x = (metrics.width - size) / 2
+  cropRect.y = (metrics.height - size) / 2
+}
+
+const triggerPictureSelect = () => {
+  pictureInput.value?.click()
+}
+
+const handlePictureSelected = async (event) => {
+  const nextFile = event.target.files?.[0] || null
+  resetEditor()
+  if (!nextFile) return
+
+  previewObjectUrl.value = URL.createObjectURL(nextFile)
+  editorImageUrl.value = previewObjectUrl.value
+  const image = new Image()
+  image.decoding = 'async'
+  image.src = editorImageUrl.value
+  try {
+    await image.decode()
+    editorImage.value = image
+  } catch {
+    errorMessage.value = 'Failed to load image'
+    resetEditor()
+  }
+}
+
+const startMove = (event) => {
+  if (!displayMetrics.value || saving.value) return
+  event.preventDefault()
+  dragState = {
+    mode: 'move',
+    startX: event.clientX,
+    startY: event.clientY,
+    initialX: cropRect.x,
+    initialY: cropRect.y,
+    initialSize: cropRect.size
+  }
+}
+
+const startResize = (event, handle) => {
+  if (!displayMetrics.value || saving.value) return
+  event.preventDefault()
+  dragState = {
+    mode: 'resize',
+    handle,
+    startX: event.clientX,
+    startY: event.clientY,
+    initialX: cropRect.x,
+    initialY: cropRect.y,
+    initialSize: cropRect.size
+  }
+}
+
+const handlePointerMove = (event) => {
+  if (!dragState) return
+  const metrics = displayMetrics.value
+  if (!metrics) return
+
+  const dx = event.clientX - dragState.startX
+  const dy = event.clientY - dragState.startY
+
+  if (dragState.mode === 'move') {
+    cropRect.x = Math.max(0, Math.min(metrics.width - dragState.initialSize, dragState.initialX + dx))
+    cropRect.y = Math.max(0, Math.min(metrics.height - dragState.initialSize, dragState.initialY + dy))
+    return
+  }
+
+  const directionMap = {
+    nw: { deltaX: -1, deltaY: -1 },
+    ne: { deltaX: 1, deltaY: -1 },
+    sw: { deltaX: -1, deltaY: 1 },
+    se: { deltaX: 1, deltaY: 1 }
+  }
+  const direction = directionMap[dragState.handle]
+  if (!direction) return
+
+  const delta = Math.max(dx * direction.deltaX, dy * direction.deltaY)
+  const nextSize = Math.max(
+    MIN_CROP_SIZE,
+    Math.min(getResizeLimit(metrics, dragState), dragState.initialSize + delta)
+  )
+
+  applyResize(dragState, nextSize)
+}
+
+const endPointerInteraction = () => {
+  dragState = null
+}
+
+const getResizeLimit = (metrics, state) => {
+  const { initialX, initialY, initialSize, handle } = state
+
+  if (handle === 'nw') return Math.min(initialX + initialSize, initialY + initialSize)
+  if (handle === 'ne') return Math.min(metrics.width - initialX, initialY + initialSize)
+  if (handle === 'sw') return Math.min(initialX + initialSize, metrics.height - initialY)
+  return Math.min(metrics.width - initialX, metrics.height - initialY)
+}
+
+const applyResize = (state, size) => {
+  const { initialX, initialY, initialSize, handle } = state
+
+  if (handle === 'nw') {
+    cropRect.x = initialX + initialSize - size
+    cropRect.y = initialY + initialSize - size
+    cropRect.size = size
+    return
+  }
+
+  if (handle === 'ne') {
+    cropRect.x = initialX
+    cropRect.y = initialY + initialSize - size
+    cropRect.size = size
+    return
+  }
+
+  if (handle === 'sw') {
+    cropRect.x = initialX + initialSize - size
+    cropRect.y = initialY
+    cropRect.size = size
+    return
+  }
+
+  cropRect.x = initialX
+  cropRect.y = initialY
+  cropRect.size = size
+}
+
+const renderPictureBlob = async () => {
+  const image = editorImage.value
+  if (!image) throw new Error('No image selected')
+  const metrics = displayMetrics.value
+  if (!metrics || !cropRect.size) throw new Error('Crop selection unavailable')
+
+  const canvas = document.createElement('canvas')
+  canvas.width = AVATAR_UPLOAD_SIZE
+  canvas.height = AVATAR_UPLOAD_SIZE
+  const context = canvas.getContext('2d')
+  if (!context) throw new Error('Canvas unavailable')
+
+  const sourceScale = image.naturalWidth / metrics.width
+  const sourceX = cropRect.x * sourceScale
+  const sourceY = cropRect.y * sourceScale
+  const sourceSize = cropRect.size * sourceScale
+  context.drawImage(image, sourceX, sourceY, sourceSize, sourceSize, 0, 0, AVATAR_UPLOAD_SIZE, AVATAR_UPLOAD_SIZE)
+
+  return await new Promise((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (!blob) {
+        reject(new Error('Failed to export cropped picture'))
+        return
+      }
+      resolve(blob)
+    }, 'image/webp', 0.9)
+  })
+}
+
+const reloadPictureFromCache = async () => {
+  const response = await fetch(props.endpoint, {
+    method: 'GET',
+    credentials: 'same-origin',
+    cache: 'reload'
+  })
+  if (!response.ok) throw new Error('Failed to refresh profile picture')
+}
+
+const savePicture = async () => {
+  try {
+    saving.value = true
+    errorMessage.value = ''
+    const blob = await renderPictureBlob()
+    const formData = new FormData()
+    formData.append('file', blob, 'profile.webp')
+    await apiJson(props.endpoint, { method: 'PUT', body: formData })
+    await reloadPictureFromCache()
+    authStore.showMessage('Profile picture updated.', 'success', 3000)
+    emit('updated')
+    closeEditor()
+  } catch (error) {
+    errorMessage.value = error.message || 'Failed to update profile picture'
+  } finally {
+    saving.value = false
+  }
+}
+
+const removePicture = async () => {
+  try {
+    saving.value = true
+    errorMessage.value = ''
+    await apiJson(props.endpoint, { method: 'DELETE' })
+    authStore.showMessage('Profile picture removed.', 'success', 3000)
+    emit('updated')
+    closeEditor()
+  } catch (error) {
+    errorMessage.value = error.message || 'Failed to remove profile picture'
+  } finally {
+    saving.value = false
+  }
+}
+
+const closeEditor = () => {
+  resetEditor()
+  emit('close')
+}
+</script>
+
+<style scoped>
+.profile-picture-editor-input { display: none; }
+.profile-picture-editor-preview { position: relative; display: flex; justify-content: center; align-items: center; width: auto; max-width: min(58rem, 88vw); min-height: 0; margin: 0 auto; overflow: visible; }
+.profile-picture-editor-trigger { min-width: 0; }
+.profile-picture-editor-image { position: absolute; user-select: none; pointer-events: none; object-fit: contain; }
+.profile-picture-editor-image--overlay { filter: grayscale(0.45) saturate(0.7) brightness(0.68); }
+.profile-picture-editor-crop { position: absolute; border: 2px solid white; cursor: move; touch-action: none; }
+.profile-picture-editor-guides { position: absolute; inset: 0; pointer-events: none; }
+.profile-picture-editor-guide { position: absolute; border-color: rgba(255, 255, 255, 0.52); }
+.profile-picture-editor-guide--circle { inset: 0; border: 1.5px solid rgba(255, 255, 255, 0.62); border-radius: 999px; box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.18); }
+.profile-picture-editor-guide--eyes { left: 18%; right: 18%; top: 38%; border-top: 1.5px solid rgba(255, 255, 255, 0.56); }
+.profile-picture-editor-guide--cheek-left { top: 24%; bottom: 18%; left: 24%; border-left: 1.5px solid rgba(255, 255, 255, 0.48); }
+.profile-picture-editor-guide--cheek-right { top: 24%; bottom: 18%; right: 24%; border-right: 1.5px solid rgba(255, 255, 255, 0.48); }
+.profile-picture-editor-handle { position: absolute; width: 1.1rem; height: 1.1rem; border-radius: 999px; border: 2px solid white; background: var(--color-accent); padding: 0; }
+.profile-picture-editor-handle--nw { left: -0.55rem; top: -0.55rem; cursor: nwse-resize; }
+.profile-picture-editor-handle--ne { right: -0.55rem; top: -0.55rem; cursor: nesw-resize; }
+.profile-picture-editor-handle--sw { left: -0.55rem; bottom: -0.55rem; cursor: nesw-resize; }
+.profile-picture-editor-handle--se { right: -0.55rem; bottom: -0.55rem; cursor: nwse-resize; }
+:deep(.modal-panel--avatar) { width: fit-content; max-width: min(58rem, 94vw); }
+@media (max-width: 720px) {
+  .profile-picture-editor-preview { max-width: 100%; }
+}
+</style>
diff --git a/frontend/src/components/ProfileView.vue b/frontend/src/components/ProfileView.vue
index 0e93325..eecf57a 100644
--- a/frontend/src/components/ProfileView.vue
+++ b/frontend/src/components/ProfileView.vue
@@ -15,6 +15,9 @@
         v-if="authStore.userInfo?.user"
         ref="userBasicInfo"
         :name="authStore.userInfo.user.display_name"
+        :avatar-url="authStore.userInfo.user.avatar_url"
+        :avatar-render-version="avatarRenderVersion"
+        avatar-clickable
         :email="authStore.userInfo.user.email"
         :preferred_username="authStore.userInfo.user.preferred_username"
         :telephone="authStore.userInfo.user.telephone"
@@ -26,6 +29,7 @@
         :role-name="authStore.userInfo.role.display_name"
         update-endpoint="/auth/api/user/info"
         @saved="authStore.loadUserInfo()"
+        @avatar-click="openAvatarDialog"
         @edit="openEditDialog"
         @keydown="handleUserInfoKeydown"
       >
@@ -131,6 +135,15 @@
       </form>
     </Modal>
 
+    <ProfilePictureEditorModal
+      v-if="showAvatarDialog && currentAvatarEndpoint"
+      :endpoint="currentAvatarEndpoint"
+      :picture-url="authStore.userInfo?.user?.avatar_url"
+      :render-version="avatarRenderVersion"
+      @close="closeAvatarDialog"
+      @updated="handleProfilePictureUpdated"
+    />
+
     <RegistrationLinkModal
       v-if="showRegLink"
       endpoint="/auth/api/user/create-link"
@@ -144,6 +157,7 @@
 import { ref, onMounted, onUnmounted, computed, watch } from 'vue'
 import Breadcrumbs from '@/components/Breadcrumbs.vue'
 import CredentialList from '@/components/CredentialList.vue'
+import ProfilePictureEditorModal from '@/components/ProfilePictureEditorModal.vue'
 import ThemeSelector from '@/components/ThemeSelector.vue'
 import UserBasicInfo from '@/components/UserBasicInfo.vue'
 import Modal from '@/components/Modal.vue'
@@ -160,11 +174,13 @@ import { navigateButtonRow, focusPreferred, focusAtIndex, getDirection } from '@
 const authStore = useAuthStore()
 const updateInterval = ref(null)
 const showEditDialog = ref(false)
+const showAvatarDialog = ref(false)
 const showRegLink = ref(false)
 const editName = ref('')
 const editEmail = ref('')
 const editUsername = ref('')
 const editTelephone = ref('')
+const avatarRenderVersion = ref(0)
 const saving = ref(false)
 const editError = ref('')
 const hoveredCredentialUuid = ref(null)
@@ -176,14 +192,15 @@ const credentialButtons = ref(null)
 const sessionList = ref(null)
 const logoutButtons = ref(null)
 const breadcrumbs = ref(null)
-const userBasicInfo = ref(null)
 const userInfoSection = ref(null)
 
 // Check if any modal/dialog is open (blocks arrow key navigation)
-const hasActiveModal = computed(() => showEditDialog.value || showRegLink.value)
+const hasActiveModal = computed(() => showEditDialog.value || showAvatarDialog.value || showRegLink.value)
 
 watch(showEditDialog, (open) => {
-  if (!open) return
+  if (!open) {
+    return
+  }
   const user = authStore.userInfo.user
   editName.value = user.display_name ?? ''
   editEmail.value = user.email ?? ''
@@ -196,7 +213,28 @@ onMounted(() => {
   updateInterval.value = setInterval(() => { if (authStore.userInfo) authStore.userInfo = { ...authStore.userInfo } }, 60000)
 })
 
-onUnmounted(() => { if (updateInterval.value) clearInterval(updateInterval.value) })
+onUnmounted(() => {
+  if (updateInterval.value) clearInterval(updateInterval.value)
+})
+
+const currentAvatarEndpoint = computed(() => {
+  const userUuid = authStore.userInfo?.user?.uuid
+  if (!userUuid) return null
+  return `/auth/api/user/${userUuid}/profile.webp`
+})
+
+const openAvatarDialog = () => {
+  showAvatarDialog.value = true
+}
+
+const closeAvatarDialog = () => {
+  showAvatarDialog.value = false
+}
+
+const handleProfilePictureUpdated = async () => {
+  await authStore.loadUserInfo()
+  avatarRenderVersion.value += 1
+}
 
 const addNewCredential = async () => {
   try {
@@ -245,7 +283,7 @@ const handleBreadcrumbKeydown = (event) => {
   if (direction === 'down') {
     event.preventDefault()
     // Move to user info section - always focus edit button first
-    focusPreferred(userInfoSection.value, { primarySelector: '.mini-btn', itemSelector: '.mini-btn, .pairing-input' })
+    focusPreferred(userInfoSection.value, { primarySelector: '.mini-btn', itemSelector: '.user-picture-btn, .mini-btn, .pairing-input' })
   }
   // ArrowUp at the top does nothing
 }
@@ -257,7 +295,7 @@ const handleUserInfoKeydown = (event) => {
   if (!direction) return
 
   event.preventDefault()
-  const itemSelector = '.mini-btn, .pairing-input'
+  const itemSelector = '.user-picture-btn, .mini-btn, .pairing-input'
 
   if (direction === 'left' || direction === 'right') {
     navigateButtonRow(userInfoSection.value, event.target, direction, { itemSelector })
@@ -278,7 +316,7 @@ const handleCredentialNavigateOut = (direction) => {
     focusPreferredButton(credentialButtons.value)
   } else if (direction === 'up' || direction === 'left') {
     // Focus user info section - always focus edit button first
-    focusPreferred(userInfoSection.value, { primarySelector: '.mini-btn', itemSelector: '.mini-btn, .pairing-input' })
+    focusPreferred(userInfoSection.value, { primarySelector: '.mini-btn', itemSelector: '.user-picture-btn, .mini-btn, .pairing-input' })
   }
 }
 
@@ -399,6 +437,7 @@ const saveProfile = async () => {
   try {
     editError.value = ''
     saving.value = true
+    let changed = false
     const body = {}
     if (name !== user.display_name) body.display_name = name
     if (emailVal !== (user.email || null)) body.email = emailVal
@@ -406,6 +445,9 @@ const saveProfile = async () => {
     if (telephoneVal !== (user.telephone || null)) body.telephone = telephoneVal
     if (Object.keys(body).length) {
       await apiJson('/auth/api/user/info', { method: 'PATCH', body })
+      changed = true
+    }
+    if (changed) {
       await authStore.loadUserInfo()
       authStore.showMessage('Profile updated!', 'success', 3000)
     }
diff --git a/frontend/src/components/UserBasicInfo.vue b/frontend/src/components/UserBasicInfo.vue
index e0f9e41..0fa6a2c 100644
--- a/frontend/src/components/UserBasicInfo.vue
+++ b/frontend/src/components/UserBasicInfo.vue
@@ -1,9 +1,20 @@
 <template>
   <div v-if="userLoaded" class="user-info" :class="{ 'has-extra': $slots.default }">
     <div class="user-info-content">
-      <div class="user-picture">
-        <span>👤</span>
-      </div>
+      <ProfilePicture
+        :src="avatarUrl"
+        :render-version="avatarRenderVersion"
+        :clickable="avatarClickable"
+        :loading="loading"
+        :title="avatarClickable ? 'Change profile picture' : ''"
+        width="5.25rem"
+        height="5.25rem"
+        radius="var(--radius-sm)"
+        fallback-size="2.8em"
+        class="user-picture"
+        :class="avatarClickable ? 'user-picture-btn' : ''"
+        @click="emit('avatar-click')"
+      />
       <h3 class="user-name-heading">
         <span class="user-name-row">
           <span class="display-name" :title="name">{{ name }}</span>
@@ -42,11 +53,13 @@
 
 <script setup>
 import { computed } from 'vue'
-import { useAuthStore } from '@/stores/auth'
+import ProfilePicture from '@/components/ProfilePicture.vue'
 import { formatDate } from '@/utils/helpers'
 
 const props = defineProps({
   name: { type: String, required: true },
+  avatarUrl: { type: String, default: null },
+  avatarRenderVersion: { type: [Number, String], default: 0 },
   email: { type: String, default: null },
   preferred_username: { type: String, default: null },
   telephone: { type: String, default: null },
@@ -55,14 +68,13 @@ const props = defineProps({
   lastSeen: { type: [String, Number, Date], default: null },
   updateEndpoint: { type: String, default: null },
   canEdit: { type: Boolean, default: true },
+  avatarClickable: { type: Boolean, default: false },
   loading: { type: Boolean, default: false },
   orgDisplayName: { type: String, default: '' },
   roleName: { type: String, default: '' }
 })
 
-const emit = defineEmits(['saved', 'edit'])
-const authStore = useAuthStore()
-
+const emit = defineEmits(['saved', 'edit', 'avatar-click'])
 const userLoaded = computed(() => !!props.name)
 </script>
 
@@ -96,12 +108,12 @@ const userLoaded = computed(() => !!props.name)
   grid-template-areas:
     "picture heading fields"
     "picture org fields"
-    ". info info";
+    "picture info info";
   gap: 0 1rem;
   min-width: 0;
 }
 
-.user-picture { grid-area: picture; display: flex; align-items: flex-start; font-size: 2em; line-height: 1; }
+:deep(.user-picture) { grid-area: picture; align-self: stretch; }
 .user-name-heading { grid-area: heading; display: flex; align-items: center; flex-wrap: wrap; margin: 0 0 0.25rem 0; min-width: 0; }
 .org-role-sub { grid-area: org; display: flex; flex-direction: column; min-width: 0; }
 .org-line { font-size: .7rem; font-weight: 600; line-height: 1.1; color: var(--color-text-muted); text-transform: uppercase; letter-spacing: 0.05em; }
diff --git a/oidc.md b/oidc.md
index 03f4cc0..fb290ec 100644
--- a/oidc.md
+++ b/oidc.md
@@ -75,10 +75,16 @@ Discovery: `backchannel_logout_supported: true`
 - `GET /.well-known/openid-configuration` — Discovery
 - `GET /auth/oidc/keys` — Keys (EdDSA)
 - `POST /auth/oidc/token` — Exchange/refresh
-- `GET /auth/oidc/userinfo` — User (bearer token)
+- `GET /auth/oidc/userinfo` — User (bearer token, includes `picture` when `profile` scope is granted and avatar exists)
 - `POST /auth/oidc/backchannel-logout` — Logout
 - `POST /auth/api/exchange` — Native auth code → cookie
 
+## Claims
+
+- `profile` scope may include `name`, `preferred_username`, and `picture`
+- `email` scope may include `email`
+- `groups` is emitted from client-scoped permissions
+
 ## Files
 
 **Created:** [paskia/authcode.py](paskia/authcode.py), [paskia/util/crypto.py](paskia/util/crypto.py), [paskia/fastapi/oid.py](paskia/fastapi/oid.py)
diff --git a/paskia/fastapi/admin/adminapp.py b/paskia/fastapi/admin/adminapp.py
index 68df84f..c3dbe4a 100644
--- a/paskia/fastapi/admin/adminapp.py
+++ b/paskia/fastapi/admin/adminapp.py
@@ -17,6 +17,7 @@ from paskia.fastapi.front import frontend
 from paskia.fastapi.response import MsgspecResponse
 from paskia.fastapi.session import AUTH_COOKIE
 from paskia.util import (
+    avatar,
     permutil,
     vitedev,
 )
@@ -26,6 +27,7 @@ from paskia.util.apistructs import (
     ApiOrg,
     ApiOrgResponse,
     ApiPermission,
+    ApiUser,
 )
 
 app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
@@ -79,7 +81,11 @@ async def admin_info(request: Request, auth=AUTH_COOKIE):
             org=ApiOrg.from_db(o),
             permissions={p.uuid: p for p in o.permissions},
             roles={r.uuid: r for r in roles},
-            users={u.uuid: u for r in roles for u in r.users},
+            users={
+                u.uuid: ApiUser.from_db(u, avatar_url=avatar.avatar_browser_url(u.uuid))
+                for r in roles
+                for u in r.users
+            },
         )
 
     orgs_dict = {o.uuid: org_to_dict(o) for o in orgs}
diff --git a/paskia/fastapi/admin/users.py b/paskia/fastapi/admin/users.py
index e344f2e..8a9011c 100644
--- a/paskia/fastapi/admin/users.py
+++ b/paskia/fastapi/admin/users.py
@@ -9,7 +9,7 @@ from paskia.fastapi import authz
 from paskia.fastapi.admin.errors import install_error_handlers
 from paskia.fastapi.response import MsgspecResponse
 from paskia.fastapi.session import AUTH_COOKIE
-from paskia.util import hostutil, permutil
+from paskia.util import avatar, hostutil, permutil
 from paskia.util.apistructs import (
     ApiAaguidInfo,
     ApiCreateLinkResponse,
@@ -165,7 +165,7 @@ async def admin_get_user_detail(
 
     return MsgspecResponse(
         ApiUserDetail(
-            user=ApiUser.from_db(user),
+            user=ApiUser.from_db(user, avatar_url=avatar.avatar_browser_url(user.uuid)),
             credentials={c.uuid: c for c in user.credentials},
             aaguid_info={
                 k: ApiAaguidInfo(**v)
diff --git a/paskia/fastapi/mainapp.py b/paskia/fastapi/mainapp.py
index 87f9a54..257ab52 100644
--- a/paskia/fastapi/mainapp.py
+++ b/paskia/fastapi/mainapp.py
@@ -126,6 +126,7 @@ async def openid_configuration(request: Request):
             "name",
             "preferred_username",
             "email",
+            "picture",
             "groups",
             "sid",
         ],
diff --git a/paskia/fastapi/oid.py b/paskia/fastapi/oid.py
index 7a663f0..d659001 100644
--- a/paskia/fastapi/oid.py
+++ b/paskia/fastapi/oid.py
@@ -22,7 +22,7 @@ from fastapi.security import HTTPBearer
 
 from paskia import authcode, db
 from paskia.db.structs import Session
-from paskia.util import oidjwt
+from paskia.util import avatar, oidjwt
 from paskia.util.crypto import hash_secret
 
 _logger = logging.getLogger(__name__)
@@ -361,6 +361,7 @@ def _build_token_response(
         name=user.display_name,
         preferred_username=user.preferred_username,
         email=user.email,
+        picture=avatar.current_avatar_url(user.uuid),
         groups=groups or None,
         auth_time=auth_time,
     )
@@ -442,12 +443,15 @@ async def userinfo(
 
     # Build userinfo response based on scope
     scope = payload.get("scope", "openid").split()
-    response = {"sub": str(user.uuid)}
+    response: dict[str, object] = {"sub": str(user.uuid)}
 
     if "profile" in scope:
         response["name"] = user.display_name
         if user.preferred_username:
             response["preferred_username"] = user.preferred_username
+        picture = avatar.current_avatar_url(user.uuid)
+        if picture:
+            response["picture"] = picture
 
     if "email" in scope and user.email:
         response["email"] = user.email
diff --git a/paskia/fastapi/user.py b/paskia/fastapi/user.py
index 1b5e227..24b8521 100644
--- a/paskia/fastapi/user.py
+++ b/paskia/fastapi/user.py
@@ -3,11 +3,13 @@ from uuid import UUID
 from fastapi import (
     Body,
     FastAPI,
+    File,
     HTTPException,
     Request,
     Response,
+    UploadFile,
 )
-from fastapi.responses import JSONResponse
+from fastapi.responses import FileResponse, JSONResponse
 
 from paskia import db
 from paskia.authsession import (
@@ -18,12 +20,48 @@ from paskia.authsession import (
 from paskia.fastapi import authz, session
 from paskia.fastapi.response import MsgspecResponse
 from paskia.fastapi.session import AUTH_COOKIE
-from paskia.util import hostutil
+from paskia.util import avatar, hostutil
 from paskia.util.apistructs import ApiCreateLinkResponse
 
 app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
 
 
+def _can_manage_avatar(ctx, target_user) -> bool:
+    if ctx.user.uuid == target_user.uuid:
+        return True
+
+    if any(p.scope == "auth:admin" for p in ctx.permissions):
+        return True
+
+    return ctx.org.uuid == target_user.org.uuid and any(
+        p.scope == "auth:org:admin" for p in ctx.permissions
+    )
+
+
+def _avatar_write_ctx(request: Request, user_uuid: UUID, auth):
+    if not auth:
+        raise authz.AuthException(
+            status_code=401, detail="Authentication Required", mode="login"
+        )
+
+    ctx = session_ctx(auth, request.headers.get("host"))
+    if not ctx:
+        raise authz.AuthException(
+            status_code=401, detail="Session expired", mode="login"
+        )
+
+    user = db.data().users.get(user_uuid)
+    if not user:
+        raise HTTPException(status_code=404, detail="Avatar not found")
+
+    if not _can_manage_avatar(ctx, user):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    return ctx, user
+
+
 @app.exception_handler(authz.AuthException)
 async def auth_exception_handler(_request, exc: authz.AuthException):
     """Handle AuthException with auth info for UI."""
@@ -103,6 +141,55 @@ async def user_update_info(
     return {"status": "ok"}
 
 
+@app.get("/{user_uuid}/profile.webp")
+async def serve_avatar(request: Request, user_uuid: UUID):
+    """Serve a user's current avatar with short-lived caching and ETag."""
+    user = db.data().users.get(user_uuid)
+    if not user:
+        raise HTTPException(status_code=404, detail="Avatar not found")
+
+    path = avatar.avatar_path(user_uuid)
+    if not path.is_file():
+        raise HTTPException(status_code=404, detail="Avatar not found")
+
+    data = avatar.read_avatar_bytes(user_uuid)
+    if data is None:
+        raise HTTPException(status_code=404, detail="Avatar not found")
+
+    etag = avatar.avatar_etag(data)
+    if request.headers.get("if-none-match") == f'"{etag}"':
+        return Response(status_code=304, headers={"ETag": f'"{etag}"'})
+
+    headers = {
+        "ETag": f'"{etag}"',
+        "Cache-Control": "public, max-age=300",
+    }
+
+    return FileResponse(path, media_type="image/webp", headers=headers)
+
+
+@app.put("/{user_uuid}/profile.webp")
+async def upload_avatar(
+    request: Request,
+    user_uuid: UUID,
+    file: UploadFile = File(...),
+    auth=AUTH_COOKIE,
+):
+    """Upload a user's browser-prepared WebP avatar on the same URL it is served from."""
+    _ctx, _user = _avatar_write_ctx(request, user_uuid, auth)
+    data = await avatar.read_upload(file)
+    avatar.store_avatar(user_uuid, data)
+    return {"status": "ok", "avatar_url": avatar.avatar_browser_url(user_uuid)}
+
+
+@app.delete("/{user_uuid}/profile.webp")
+async def delete_avatar(request: Request, user_uuid: UUID, auth=AUTH_COOKIE):
+    """Delete a user's avatar image on the same URL it is served from."""
+    _ctx, _user = _avatar_write_ctx(request, user_uuid, auth)
+    avatar.remove_avatar_file(user_uuid)
+    return {"status": "ok"}
+
+
 @app.patch("/theme")
 async def user_update_theme(
     request: Request,
diff --git a/paskia/util/apistructs.py b/paskia/util/apistructs.py
index f4a454f..5ce0ca0 100644
--- a/paskia/util/apistructs.py
+++ b/paskia/util/apistructs.py
@@ -24,10 +24,11 @@ class ApiUser(User, kw_only=True):
     """User with uuid serialized."""
 
     uuid: UUID
+    avatar_url: str | None = None
 
     @classmethod
-    def from_db(cls, u: User) -> ApiUser:
-        return cls(uuid=u.uuid, **msgspec.structs.asdict(u))
+    def from_db(cls, u: User, *, avatar_url: str | None = None) -> ApiUser:
+        return cls(uuid=u.uuid, avatar_url=avatar_url, **msgspec.structs.asdict(u))
 
 
 class ApiOrg(Org, kw_only=True):
@@ -139,7 +140,7 @@ class ApiUserDetail(msgspec.Struct, kw_only=True):
     user: ApiUser
     credentials: dict[UUID, Credential]
     aaguid_info: dict[str, ApiAaguidInfo]
-    sessions: dict[bytes, ApiUserSession]
+    sessions: dict[str, ApiUserSession]
     permissions: dict[UUID, ApiPermission] = {}
     org: ApiOrg | None = None
     role: ApiRole | None = None
@@ -156,7 +157,7 @@ class ApiOrgResponse(msgspec.Struct, kw_only=True):
     org: ApiOrg
     permissions: dict[UUID, Permission]
     roles: dict[UUID, Role]
-    users: dict[UUID, User]
+    users: dict[UUID, ApiUser]
 
 
 class ApiSettings(msgspec.Struct):
diff --git a/paskia/util/avatar.py b/paskia/util/avatar.py
new file mode 100644
index 0000000..8dc5390
--- /dev/null
+++ b/paskia/util/avatar.py
@@ -0,0 +1,102 @@
+"""Avatar storage and URL helpers."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+from pathlib import Path
+from uuid import UUID
+
+from fastapi import HTTPException, UploadFile
+
+from paskia.util import hostutil
+
+MAX_UPLOAD_BYTES = 10 * 1024 * 1024
+
+
+def media_root() -> Path:
+    """Return the filesystem root for auxiliary media files."""
+    db_path = Path(os.environ.get("PASKIA_DB", "localhost.paskiadb")).resolve()
+    db_name = db_path.name
+    hostname = db_name.removesuffix(".paskiadb") or db_path.stem
+    return db_path.parent / f"{hostname}.data"
+
+
+def avatars_root() -> Path:
+    """Return the filesystem root for stored avatar images."""
+    return media_root() / "user"
+
+
+def avatar_path(user_uuid: UUID) -> Path:
+    """Return the avatar file path for a user."""
+    return avatars_root() / str(user_uuid) / "profile.webp"
+
+
+def avatar_public_path(user_uuid: UUID) -> str:
+    """Return the public relative path for a user's avatar."""
+    return f"/auth/api/user/{user_uuid}/profile.webp"
+
+
+def avatar_browser_url(user_uuid: UUID) -> str | None:
+    """Return the browser-facing avatar URL."""
+    if not avatar_path(user_uuid).is_file():
+        return None
+    return avatar_public_path(user_uuid)
+
+
+def avatar_url(user_uuid: UUID) -> str | None:
+    """Return the absolute public avatar URL for a user, or None."""
+    if not avatar_path(user_uuid).is_file():
+        return None
+    return f"{hostutil.auth_site_url()}api/user/{user_uuid}/profile.webp"
+
+
+def current_avatar_url(user_uuid: UUID) -> str | None:
+    """Return the current absolute avatar URL for a user UUID."""
+    return avatar_url(user_uuid)
+
+
+def remove_avatar_file(user_uuid: UUID) -> None:
+    """Delete a stored avatar file if it exists."""
+    with contextlib.suppress(FileNotFoundError):
+        avatar_path(user_uuid).unlink()
+
+
+def read_avatar_bytes(user_uuid: UUID) -> bytes | None:
+    """Read the stored avatar file for a user, if present."""
+    path = avatar_path(user_uuid)
+    if not path.is_file():
+        return None
+    return path.read_bytes()
+
+
+def _is_webp(data: bytes) -> bool:
+    """Return True when bytes look like a RIFF WebP file."""
+    return len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP"
+
+
+async def read_upload(upload: UploadFile) -> bytes:
+    """Read an uploaded avatar and require it to already be WebP."""
+    data = await upload.read(MAX_UPLOAD_BYTES + 1)
+    if not data:
+        raise HTTPException(status_code=400, detail="No avatar file uploaded")
+    if len(data) > MAX_UPLOAD_BYTES:
+        raise HTTPException(status_code=413, detail="Avatar upload too large")
+
+    if not _is_webp(data):
+        raise HTTPException(status_code=400, detail="Avatar upload must be WebP")
+
+    return data
+
+
+def store_avatar(user_uuid: UUID, data: bytes) -> None:
+    """Store avatar bytes."""
+    path = avatar_path(user_uuid)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+
+
+def avatar_etag(data: bytes) -> str:
+    """Return a stable ETag value for avatar bytes."""
+    return hashlib.sha256(data).hexdigest()[:16]
diff --git a/paskia/util/oidjwt.py b/paskia/util/oidjwt.py
index a627003..7c3de54 100644
--- a/paskia/util/oidjwt.py
+++ b/paskia/util/oidjwt.py
@@ -78,6 +78,7 @@ def create_id_token(
     name: str | None = None,
     preferred_username: str | None = None,
     email: str | None = None,
+    picture: str | None = None,
     groups: list[str] | None = None,
     auth_time: datetime | None = None,
     expires_in: int = 3600,
@@ -93,6 +94,7 @@ def create_id_token(
         name: User's display name
         preferred_username: User's preferred username
         email: User's email address
+        picture: User avatar URL
         groups: List of permission scopes (groups claim)
         auth_time: When the user authenticated (last credential use time)
         expires_in: Token lifetime in seconds
@@ -101,8 +103,9 @@ def create_id_token(
         Signed JWT string
     """
     _ensure_key()
+    assert _private_key is not None
     now = datetime.now(UTC)
-    payload = {
+    payload: dict[str, object] = {
         "iss": issuer,
         "sub": str(subject),
         "aud": audience,
@@ -119,6 +122,8 @@ def create_id_token(
         payload["preferred_username"] = preferred_username
     if email:
         payload["email"] = email
+    if picture:
+        payload["picture"] = picture
     if groups:
         payload["groups"] = groups
     if auth_time:
@@ -147,8 +152,9 @@ def create_access_token(
         Signed JWT string
     """
     _ensure_key()
+    assert _private_key is not None
     now = datetime.now(UTC)
-    payload = {
+    payload: dict[str, object] = {
         "iss": issuer,
         "sub": str(subject),
         "aud": audience,
@@ -173,20 +179,24 @@ def decode_access_token(
         Decoded payload or None if invalid
     """
     _ensure_key()
+    assert _public_key is not None
     try:
-        # PyJWT requires audience parameter when token has aud claim.
-        # When audience is None, we skip PyJWT's audience validation and validate manually.
-        options = {}
-        decode_kwargs = {
-            "algorithms": ["EdDSA"],
-            "issuer": issuer,
-        }
         if audience is not None:
-            decode_kwargs["audience"] = audience
-        else:
-            options["verify_aud"] = False
+            return jwt.decode(
+                token,
+                _public_key,
+                algorithms=["EdDSA"],
+                issuer=issuer,
+                audience=audience,
+            )
 
-        return jwt.decode(token, _public_key, options=options, **decode_kwargs)
+        return jwt.decode(
+            token,
+            _public_key,
+            algorithms=["EdDSA"],
+            issuer=issuer,
+            options={"verify_aud": False},
+        )
     except jwt.PyJWTError:
         return None
 
@@ -212,8 +222,9 @@ def create_logout_token(
         Signed JWT string
     """
     _ensure_key()
+    assert _private_key is not None
     now = datetime.now(UTC)
-    payload = {
+    payload: dict[str, object] = {
         "iss": issuer,
         "aud": audience,
         "iat": int(now.timestamp()),
diff --git a/paskia/util/userinfo.py b/paskia/util/userinfo.py
index b01d73b..0db6abf 100644
--- a/paskia/util/userinfo.py
+++ b/paskia/util/userinfo.py
@@ -2,7 +2,7 @@
 
 from paskia import aaguid, db
 from paskia.db import SessionContext
-from paskia.util import hostutil
+from paskia.util import avatar, hostutil
 from paskia.util.apistructs import (
     ApiAaguidInfo,
     ApiOrg,
@@ -56,7 +56,7 @@ async def build_user_info(
     }
 
     return ApiUserDetail(
-        user=ApiUser.from_db(user),
+        user=ApiUser.from_db(user, avatar_url=avatar.avatar_browser_url(user.uuid)),
         credentials={c.uuid: c for c in user.credentials},
         aaguid_info={
             k: ApiAaguidInfo(**v)
diff --git a/tests/conftest.py b/tests/conftest.py
index 869b74d..019f68c 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -283,3 +283,27 @@ def create_test_session(
     with ops_db._db.transaction("create_test_session"):
         session.store(now)
     return session.key, token
+
+
+def create_test_image_bytes(
+    *,
+    image_format: str = "WEBP",
+) -> bytes:
+    """Return deterministic test upload bytes without image-library dependencies."""
+    fixtures = {
+        "WEBP": (
+            b"RIFF\x1a\x00\x00\x00WEBPVP8 "
+            b"\x0e\x00\x00\x000\x01\x00\x9d\x01*\x01\x00\x01\x00\x01\x00"
+        ),
+        "PNG": (
+            b"\x89PNG\r\n\x1a\n"
+            b"\x00\x00\x00\rIHDR"
+            b"\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00"
+            b"\x90wS\xde"
+        ),
+    }
+
+    try:
+        return fixtures[image_format.upper()]
+    except KeyError as exc:
+        raise ValueError(f"Unsupported test image format: {image_format}") from exc
diff --git a/tests/test_admin.py b/tests/test_admin.py
index 33bf194..e3333af 100644
--- a/tests/test_admin.py
+++ b/tests/test_admin.py
@@ -14,6 +14,7 @@ These tests cover:
 import os
 import secrets
 from datetime import UTC, datetime
+from urllib.parse import urlsplit
 from uuid import UUID
 
 import httpx
@@ -37,7 +38,7 @@ from paskia.db import (
 )
 from paskia.db.operations import DB
 from paskia.util.crypto import hash_secret
-from tests.conftest import auth_headers, create_test_session
+from tests.conftest import auth_headers, create_test_image_bytes, create_test_session
 
 # -------------------- Additional Fixtures --------------------
 
@@ -238,6 +239,38 @@ class TestAdminOrganizations:
         assert "roles" in org_data
         assert "users" in org_data
 
+    @pytest.mark.asyncio
+    async def test_list_orgs_includes_user_avatar_urls(
+        self,
+        client: httpx.AsyncClient,
+        session_token: str,
+        test_org,
+        test_user,
+        tmp_path,
+        monkeypatch,
+    ):
+        """Admin org payload should include canonical avatar URLs for listed users."""
+        monkeypatch.setenv("PASKIA_DB", str(tmp_path / "test-avatar-db.paskiadb"))
+
+        upload = await client.put(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            files={"file": ("avatar.webp", create_test_image_bytes(), "image/webp")},
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert upload.status_code == 200
+
+        response = await client.get(
+            "/auth/api/admin/info",
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 200
+
+        data = response.json()
+        listed_user = data["orgs"][str(test_org.uuid)]["users"][str(test_user.uuid)]
+        parts = urlsplit(listed_user["avatar_url"])
+        assert parts.path.endswith(f"/auth/api/user/{test_user.uuid}/profile.webp")
+        assert parts.query == ""
+
     @pytest.mark.asyncio
     async def test_list_orgs_with_org_admin(
         self,
@@ -902,6 +935,34 @@ class TestAdminUsersInOrg:
         data = response.json()
         assert "display_name too long" in data["detail"]
 
+    @pytest.mark.asyncio
+    async def test_admin_can_upload_user_avatar(
+        self,
+        client: httpx.AsyncClient,
+        session_token: str,
+        test_user: User,
+        tmp_path,
+        monkeypatch,
+    ):
+        """Admin should be able to upload avatar for a managed user."""
+        monkeypatch.setenv("PASKIA_DB", str(tmp_path / "test-admin-avatar-db.paskiadb"))
+
+        response = await client.put(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            files={"file": ("avatar.webp", create_test_image_bytes(), "image/webp")},
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 200
+
+        detail = await client.get(
+            f"/auth/api/admin/users/{test_user.uuid}",
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert detail.status_code == 200
+        avatar_url = detail.json()["user"]["avatar_url"]
+        parts = urlsplit(avatar_url)
+        assert parts.path.endswith(f"/auth/api/user/{test_user.uuid}/profile.webp")
+
     @pytest.mark.asyncio
     async def test_update_user_role_in_org(
         self,
diff --git a/tests/test_api.py b/tests/test_api.py
index d951f30..197ae57 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -12,6 +12,7 @@ These tests cover:
 
 import secrets
 from datetime import UTC, datetime, timedelta
+from urllib.parse import urlsplit
 
 import httpx
 import pytest
@@ -19,8 +20,10 @@ import pytest
 from paskia import authcode
 from paskia.authsession import EXPIRES
 from paskia.db import delete_session
+from paskia.db.structs import Client
+from paskia.util import oidjwt
 from paskia.util.passphrase import generate
-from tests.conftest import auth_headers, create_test_session
+from tests.conftest import auth_headers, create_test_image_bytes, create_test_session
 
 
 class TestSettingsEndpoint:
@@ -46,6 +49,15 @@ class TestSettingsEndpoint:
         data = response.json()
         assert "ui_base_path" in data
 
+    @pytest.mark.asyncio
+    async def test_openid_configuration_includes_picture_claim(
+        self, client: httpx.AsyncClient
+    ):
+        """Discovery document should advertise picture claim support."""
+        response = await client.get("/.well-known/openid-configuration")
+        assert response.status_code == 200
+        assert "picture" in response.json()["claims_supported"]
+
 
 class TestValidateEndpoint:
     """Tests for POST /auth/api/validate"""
@@ -294,6 +306,121 @@ class TestUserInfoEndpoint:
         data = response.json()
         assert "permissions" in data
 
+    @pytest.mark.asyncio
+    async def test_user_info_includes_avatar_url(
+        self,
+        client: httpx.AsyncClient,
+        session_token: str,
+        test_user,
+        tmp_path,
+        monkeypatch,
+    ):
+        """User info should include the canonical avatar URL when present."""
+        monkeypatch.setenv("PASKIA_DB", str(tmp_path / "test-avatar-db.paskiadb"))
+
+        upload = await client.put(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            files={"file": ("avatar.webp", create_test_image_bytes(), "image/webp")},
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert upload.status_code == 200
+
+        response = await client.get(
+            "/auth/api/user-info",
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        avatar_url = data["user"]["avatar_url"]
+        parts = urlsplit(avatar_url)
+        assert parts.path.endswith(f"/auth/api/user/{test_user.uuid}/profile.webp")
+        assert parts.query == ""
+
+    @pytest.mark.asyncio
+    async def test_avatar_route_returns_304_for_matching_etag(
+        self,
+        client: httpx.AsyncClient,
+        session_token: str,
+        test_user,
+        tmp_path,
+        monkeypatch,
+    ):
+        """Avatar route should honor If-None-Match for unchanged avatars."""
+        monkeypatch.setenv("PASKIA_DB", str(tmp_path / "test-avatar-db.paskiadb"))
+
+        upload = await client.put(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            files={"file": ("avatar.webp", create_test_image_bytes(), "image/webp")},
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert upload.status_code == 200
+        parts = urlsplit(upload.json()["avatar_url"])
+
+        first = await client.get(parts.path, headers={"Host": "localhost:4401"})
+        assert first.status_code == 200
+
+        response = await client.get(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            headers={
+                "Host": "localhost:4401",
+                "If-None-Match": first.headers["etag"],
+            },
+        )
+        assert response.status_code == 304
+        assert response.headers["etag"] == first.headers["etag"]
+
+
+class TestOidcUserInfoEndpoint:
+    """Tests for OIDC userinfo metadata relevant to avatars."""
+
+    @pytest.mark.asyncio
+    async def test_userinfo_includes_picture_claim(
+        self,
+        client: httpx.AsyncClient,
+        test_db,
+        session_token: str,
+        test_user,
+        tmp_path,
+        monkeypatch,
+    ):
+        """OIDC userinfo should expose picture when profile scope is granted."""
+        monkeypatch.setenv("PASKIA_DB", str(tmp_path / "test-avatar-db.paskiadb"))
+
+        upload = await client.put(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            files={"file": ("avatar.webp", create_test_image_bytes(), "image/webp")},
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert upload.status_code == 200
+        avatar_url = upload.json()["avatar_url"]
+
+        oidc_client, _secret = Client.create(
+            name="Test Client",
+            redirect_uris=["https://client.example/callback"],
+            client_secret="topsecret",
+        )
+        with test_db.transaction("create_test_oidc_client"):
+            test_db.oidc.clients[oidc_client.uuid] = oidc_client
+
+        access_token = oidjwt.create_access_token(
+            issuer="http://localhost:4401",
+            subject=test_user.uuid,
+            audience=str(oidc_client.uuid),
+            scope="openid profile",
+        )
+
+        response = await client.get(
+            "/auth/oidc/userinfo",
+            headers={
+                "Authorization": f"Bearer {access_token}",
+                "Host": "localhost:4401",
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert urlsplit(data["picture"]).path == urlsplit(avatar_url).path
+        assert data["picture"].startswith("http")
+
 
 class TestSetSessionEndpoint:
     """Tests for POST /auth/api/set-session"""
diff --git a/tests/test_user.py b/tests/test_user.py
index 7350f12..bdf3f98 100644
--- a/tests/test_user.py
+++ b/tests/test_user.py
@@ -3,16 +3,19 @@ Tests for the user API endpoints (/auth/api/user/).
 
 These tests cover user self-service operations:
 - Display name update
+- Avatar upload/delete
 - Logout all sessions
 - Session management (delete specific session)
 - Credential management (delete credential)
 - Device addition link creation
 """
 
+from urllib.parse import urlsplit
+
 import httpx
 import pytest
 
-from tests.conftest import auth_headers
+from tests.conftest import auth_headers, create_test_image_bytes
 
 
 class TestUserDisplayName:
@@ -67,6 +70,138 @@ class TestUserDisplayName:
         assert response.status_code == 400
 
 
+class TestUserAvatar:
+    """Tests for PUT/DELETE /auth/api/user/{user_uuid}/profile.webp"""
+
+    @pytest.mark.asyncio
+    async def test_upload_avatar_requires_auth(self, client: httpx.AsyncClient):
+        """Uploading avatar without auth should return 401."""
+        response = await client.put(
+            "/auth/api/user/00000000-0000-0000-0000-000000000000/profile.webp",
+            files={"file": ("avatar.webp", create_test_image_bytes(), "image/webp")},
+        )
+        assert response.status_code in (401, 404)
+
+    @pytest.mark.asyncio
+    async def test_upload_avatar_success(
+        self,
+        client: httpx.AsyncClient,
+        session_token: str,
+        test_user,
+        tmp_path,
+        monkeypatch,
+    ):
+        """Uploading a WebP avatar should store and expose the canonical URL."""
+        monkeypatch.setenv("PASKIA_DB", str(tmp_path / "test-avatar-db.paskiadb"))
+
+        upload_bytes = create_test_image_bytes()
+
+        response = await client.put(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            files={"file": ("avatar.webp", upload_bytes, "image/webp")},
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        avatar_url = data["avatar_url"]
+        parts = urlsplit(avatar_url)
+        assert parts.query == ""
+
+        avatar_response = await client.get(
+            parts.path,
+            headers={"Host": "localhost:4401"},
+        )
+        assert avatar_response.status_code == 200
+        assert avatar_response.headers["cache-control"] == "public, max-age=300"
+        assert avatar_response.headers["content-type"] == "image/webp"
+        assert "etag" in avatar_response.headers
+        assert avatar_response.content == upload_bytes
+
+        not_modified = await client.get(
+            parts.path,
+            headers={
+                "Host": "localhost:4401",
+                "If-None-Match": avatar_response.headers["etag"],
+            },
+        )
+        assert not_modified.status_code == 304
+        assert not_modified.headers["etag"] == avatar_response.headers["etag"]
+
+    @pytest.mark.asyncio
+    async def test_upload_avatar_rejects_non_webp(
+        self,
+        client: httpx.AsyncClient,
+        session_token: str,
+        test_user,
+        tmp_path,
+        monkeypatch,
+    ):
+        """Avatar uploads must already be browser-prepared WebP."""
+        monkeypatch.setenv("PASKIA_DB", str(tmp_path / "test-avatar-db.paskiadb"))
+
+        response = await client.put(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            files={
+                "file": (
+                    "avatar.png",
+                    create_test_image_bytes(image_format="PNG"),
+                    "image/png",
+                )
+            },
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+
+        assert response.status_code == 400
+        assert response.json()["detail"] == "Avatar upload must be WebP"
+
+    @pytest.mark.asyncio
+    async def test_delete_avatar_success(
+        self,
+        client: httpx.AsyncClient,
+        session_token: str,
+        test_user,
+        tmp_path,
+        monkeypatch,
+    ):
+        """Deleting avatar should clear the user avatar URL."""
+        monkeypatch.setenv("PASKIA_DB", str(tmp_path / "test-avatar-db.paskiadb"))
+
+        await client.put(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            files={"file": ("avatar.webp", create_test_image_bytes(), "image/webp")},
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+
+        response = await client.delete(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 200
+
+    @pytest.mark.asyncio
+    async def test_regular_user_cannot_upload_another_users_avatar(
+        self,
+        client: httpx.AsyncClient,
+        regular_session_token: str,
+        session_token: str,
+        test_user,
+    ):
+        """A non-admin user should not be able to upload another user's avatar."""
+        response = await client.put(
+            f"/auth/api/user/{test_user.uuid}/profile.webp",
+            files={"file": ("avatar.webp", create_test_image_bytes(), "image/webp")},
+            headers={**auth_headers(regular_session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 403
+
+        info = await client.get(
+            "/auth/api/user-info",
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert info.status_code == 200
+        assert info.json()["user"].get("avatar_url") is None
+
+
 class TestUserLogoutAll:
     """Tests for POST /auth/api/user/logout-all"""