Enable Direct Profile Picture Uploads on Open Library

[Sadashii]

Problem / Opportunity

• Problem: Currently, Open Library users cannot upload or change their profile picture (avatar) directly on the platform. The avatar URL is generated via https://archive.org/services/img/{itemname} (where itemname is the user's Internet Archive item ID, typically @username). To update their profile picture, users have to leave Open Library, navigate to Archive.org, log in there, locate their account item page, and upload their image there.
• Justify: This multi-step, multi-site journey is extremely counter-intuitive. Users expect to edit all their profile details in one place. As a direct result, Lisa and the helpdesk support team receive a steady, high volume of support inquiries from users asking how to update their profile picture or reporting it as broken/missing.
• Success Criteria: Users should be able to upload, update, and delete their profile picture directly from the edit profile page on Open Library. The new profile picture should show up immediately across the site (without waiting for the 24-hour cache expiry).

Proposal

• Add an image file input (with format/size validation) to the profile edit form.
• Create a FastAPI endpoint (e.g. POST /account/avatar) to receive the uploaded image.
• Use the logged-in patron's decrypted s3_keys (via get_s3_keys(account)) to upload the image directly to their Internet Archive account item (typically @username) using the internetarchive Python SDK or S3 API.
• Invalidate the User.get_avatar_url cache upon a successful upload so the change is immediately visible.

Breakdown

Implementation Details (for maintainers)

Related files

Refer to this map of common Endpoints:

• openlibrary/core/models.py - Contains get_avatar_url which generates the avatar link from the Archive.org item.
• openlibrary/plugins/upstream/mybooks.py - Defines the /people/{username}/avatar endpoint which performs a redirect.
• openlibrary/templates/type/user/edit.html - The template for the edit profile form.
• openlibrary/templates/account.html - Links to /people/{username}?m=edit.
• openlibrary/fastapi/account.py - Place for new FastAPI endpoints for handling account modifications.

Requirements Checklist

• Add an image file input (with format/size validation) on the profile edit form.
• Implement a FastAPI endpoint (e.g. POST /account/avatar) to receive the uploaded image.
• Use get_s3_keys to authenticate and upload the photo to the user's Internet Archive item (@username) using the internetarchive Python SDK or S3 API.
• Invalidate the User.get_avatar_url cache upon a successful upload.
• Update documentation to guide users on the new upload feature, and update any helpdesk guides.

Stakeholders

• @seabelis (Community Manager & Support Lead) - Primary contact for user feedback and support coordination.
• Backend Leads / Security team - To review S3 upload policies, rate limits, and allowed image formats.

---

Instructions for Contributors

• Before creating a new branch or pushing up changes to a PR, please first run these commands to ensure your repository is up to date, as the pre-commit bot may add commits to your PRs upstream.

[openlibrary-bot]

Thanks for the suggestion! A staff member will review this and follow up when they can.

[lisa]

@lisa User Notification

Hello! You're receiving this notice because you've tagged me, @lisa, on GitHub, likely in error. Lisa is a common first name, and happens to be mine. I use the @lisa username here on GitHub. While being tagged in various repositories is an interesting way for me to discover new projects, it's likely not your intention. Did you mean to tag someone else? Did you mean to use @lisa instead, in a word as word usage?

Next Steps

I'm unsubscribing from this issue, pull request or project so if you meant to tag someone else to notify them, I would recommend that. If you meant to use my user ID as a plain string, without having GitHub notify me, you can do so by wrapping with backticks (the ` character), like so: @lisa.

[Sadashii]

@seabelis

[mekarpeles]

This may be a difficult feature to implement as it would require syncing images with archive.org (I am not sure an s3 API exists for this function) and also it is likely limited by WAF (firewall) rules.

[RsbhThakur]

I was exploring this issue and reading over Mek's notes regarding S3 APIs, thumbnail syncing, and potential WAF rules. I wanted to see how feasible it would be to prototype in my local dev environment, and while testing things out, I ended up with a working implementation!
Here is what I found while addressing those concerns:

1. S3 API & Auth: Open Library already encrypts user IA S3 keys in account sessions. Using the official internetarchive Python SDK (ia.get_item().upload), uploading avatar.jpg to s3.us.archive.org works smoothly.
2. Server-Side Proxying (No WAF/CORS issues): By routing the upload server-to-server through a new FastAPI endpoint (POST /account/avatar), browser CORS and WAF restrictions are completely avoided.
3. Derive Cluster & Cache Invalidation: Passing queue_derive=True triggers Archive.org's thumbnail derive cluster, and appending ?v={avatar_updated} along with clearing Memcached ensures browsers don't serve stale cached avatars.

I also added a DELETE /account/avatar endpoint so users can remove their photo anytime, along with instant client-side DOM preview and 6 automated unit tests (19/19 pytest tests passing).

I've opened a PR with these changes here: #13290
Would love to hear your thoughts or any feedback on the approach whenever you have a moment!