Profile picture & cover

Live

A member's picture starts as their Authvio photo. You keep your own WebP copy in Bolrach Storage, and the member can change or remove their picture and cover on your platform whenever they like. One shared helper makes these decisions for every Bolrach platform.

Helper @empire/storage/authvio-pictureStorage scope storage:ingestAccount routes bolrach.com/api/me

The Authvio side, meaning the picture claim, its sizes and the change event, is described on docs.authvio.com: Profile pictures. This page covers what a Bolrach platform does with that claim.

The rules

  • A member with no picture gets their Authvio photo at sign-in. Members who joined earlier get it from a one-off backfill.
  • Your pages and apps show your stored copy. They never load cdn.authvio.com directly.
  • A picture the member uploads themselves is never replaced by a later Authvio change.
  • If they remove their own upload, the Authvio photo comes back, or initials if there is none.
  • If they remove the Authvio photo, they get initials, and that choice is remembered.
  • Covers start empty, because Authvio has no cover. Members can set or remove a cover at any time.
  • Each file has a size limit (a server setting today, with an admin setting coming). There is no limit on how often someone changes their picture.

What you store per member

FieldTypeMeaning
picture_refstring | nullYour stored WebP. Null means show initials.
picture_source'authvio' · 'own' · 'none' · nullWhere the picture came from. 'none' means the member removed the Authvio photo; null means nothing has been decided yet.
picture_authvio_urlstring | nullThe claim you last copied. A new ?v= in the claim means a new Authvio photo.
cover_ref, cover_sourcekey · 'own' · 'none' · nullThe same pattern for the cover, without the Authvio step.

In the helper these three fields are one PictureState: { ref: string | null; source: PictureSource; authvioUrl: string | null }, where PictureSource is 'authvio' | 'own' | 'none' | null.

The helper

Import from @empire/storage/authvio-picture (or from the @empire/storage root). It runs on the server only. Apps need nothing from it, because they show the address your API returns.

FunctionWhen to call itWhat it does
decideAuthvioPicture({ claimUrl, current })At every Authvio sign-in (web and app) and in the one-off backfill.Returns { action: 'leave' }, { action: 'seed', url } or { action: 'refresh', url }. Pure, no I/O.
importAuthvioPicture(ingest, { url, bucket, key, squares?, widths? })After a seed or refresh, in the background (never awaited in sign-in).Copies the Authvio photo into your bucket as WebP and returns { ref, authvioUrl, source: 'authvio', ingest }. Throws on any failure.
stillApplies(readAtDecision, now)Before saving a background copy.True only if ref, source and authvioUrl are unchanged since the decision, so an upload made meanwhile wins.
removePicture({ current, claimUrl })When the member taps Remove on their photo.Returns { action: 'seed', url } (the picture was not known to be Authvio's, and a claim exists) or { action: 'clear', source }: source is 'none' only when the removed picture was Authvio's, otherwise null. Pure.
removeAuthvioPictureObjects(links, { bucket, keys, reason, memberPrefix })When a picture is replaced or removed, or the account is erased.Deletes those objects through Storage and returns { deleted, failed, refused }. A failed delete never throws; keys outside memberPrefix (or containing ..) go to refused and are never sent. It throws authvio_picture_member_prefix_required only when memberPrefix is missing, does not end in /, or contains ...
pictureObjectKeys(stored)Before deleting a stored picture.Lists the main key and every size variant of one ingest result.
authvioPictureUrl(claim)When you need the claim on its own.Returns the claim if it is https on cdn.authvio.com, otherwise null.

How the sign-in decision works

  • Source 'own' or 'none', or no usable claim: leave.
  • No stored picture: seed it from the claim.
  • Source 'authvio' and the claim differs from picture_authvio_url: refresh.
  • In every other case: leave.

What the copy checks

importAuthvioPicture downloads from cdn.authvio.com over https on your server and nowhere else. A redirect is an error. So is a file over 10 MB (AUTHVIO_PICTURE_MAX_BYTES) or a type outside WebP, JPEG, PNG, GIF, AVIF, HEIC and HEIF; an SVG is always refused. The bytes then go to Storage ingest, the same path a member's own upload takes, and come out as a scanned WebP with EXIF removed. Every copy has a fresh key, so it is cached for a year (AUTHVIO_PICTURE_CACHE_CONTROL). When it throws, the message is one of authvio_picture_url_refused, authvio_picture_fetch_<HTTP status>, authvio_picture_not_image, authvio_picture_too_large, authvio_picture_not_converted or authvio_picture_not_clean; log it and move on. If you pass links, a stored result that is refused (not converted, or not clean) is deleted again before the error is thrown.

Storage access

The API signs in to Storage as its own workload, empire:<app>:storage (audience https://storage.bolrach.com, scope storage:ingest), and storage-api must grant it your bucket. Add storage:delete if it cleans up old pictures, which it should. The service's drop-in carries:

STORAGE_WIF_CLIENT_ID=…
STORAGE_WIF_KEY_FILE=<path to the workload key>
STORAGE_WIF_AUDIENCE=https://storage.bolrach.com
STORAGE_API_URL=<Storage's internal address>

Set STORAGE_API_URL to Storage's internal address. The default is the public edge, which refuses server-to-server calls. The Storage owners give you the address, the workload and the grant.

At sign-in

The decision is instant. The copy is not, so start it and let sign-in finish without waiting. When the copy comes back, write it with a compare-and-set update against the row you read (or check stillApplies first). If the member uploaded a photo in the meantime, the write misses and the copy gets deleted. If the copy failed, nothing is written; the next sign-in has another go.

import {
  decideAuthvioPicture, importAuthvioPicture, type PictureState,
} from "@empire/storage/authvio-picture";
import { StorageIngest } from "@empire/storage";
import { authvioAuthFromEnv } from "@authvio/workload";

const credential = authvioAuthFromEnv("STORAGE", process.env, {
  audience: "https://storage.bolrach.com", scope: "storage:ingest",
});
const ingest = new StorageIngest({ credential, base: process.env.STORAGE_API_URL });

// Member, db, BUCKET, log and dropObjects are your app's own.
// Call this at the end of every Authvio sign-in (web OIDC and the app door).
// It returns at once: sign-in never waits for the copy.
export function afterSignIn(member: Member, claims: { picture?: unknown }) {
  const read: PictureState = {
    ref: member.picture_ref, source: member.picture_source, authvioUrl: member.picture_authvio_url,
  };
  const d = decideAuthvioPicture({ claimUrl: claims.picture, current: read });
  if (d.action !== "seed" && d.action !== "refresh") return;

  const key = `members/${member.id}/${crypto.randomUUID()}.webp`;
  void importAuthvioPicture(ingest, { url: d.url, bucket: BUCKET, key, squares: [96, 256, 512] })
    .then(async (copy) => {
      // Save only if nothing changed since we read the row: an upload made meanwhile wins.
      const saved = await db.updatePictureIf(member.id, read, {
        ref: copy.ref, source: "authvio", authvioUrl: copy.authvioUrl,
      });
      if (!saved) await dropObjects(member.id, copy.ingest);
    })
    .catch((e) => log.warn("Authvio picture not copied; tries again next sign-in", e));
}

Remove

Someone who removes a photo they uploaded gets their Authvio photo back. The same applies to any picture not known to be Authvio's (source 'own' or null, for example one written before this helper existed). With no Authvio photo, or when the copy fails, they get initials and source goes back to null, which lets a later Authvio photo fill the gap. Source becomes 'none' in one case only: the picture they removed was the Authvio photo.

import { removePicture, importAuthvioPicture, type PictureSource } from "@empire/storage/authvio-picture";

// db, ingest, BUCKET, newKey, dropOldPicture and Conflict are your app's own.

export async function removePhoto(member: Member, claims: { picture?: unknown }) {
  const read = { ref: member.picture_ref, source: member.picture_source, authvioUrl: member.picture_authvio_url };
  const d = removePicture({ current: read, claimUrl: claims.picture });

  let next = { ref: null as string | null, source: null as PictureSource, authvioUrl: null as string | null };
  if (d.action === "seed") {
    // The removed picture was not known to be Authvio's: fall back to the Authvio picture.
    try {
      const copy = await importAuthvioPicture(ingest, { url: d.url, bucket: BUCKET, key: newKey(member.id), squares: [96, 256, 512] });
      next = { ref: copy.ref, source: "authvio", authvioUrl: copy.authvioUrl };
    } catch {
      // The copy failed: initials, not remembered (source null), so the next sign-in tries again.
    }
  } else if (d.action === "clear") {
    next.source = d.source; // 'none' = the Authvio picture was removed; never re-seeded
  }
  if (!(await db.updatePictureIf(member.id, read, next))) throw new Conflict("Your photo just changed. Look again and try once more.");
  await dropOldPicture(member);
}

Deleting old objects

An old photo keeps loading from its address until its objects are gone, so delete them on replace, on remove and when the account is erased. Storage checks that the key is inside your grant's bucket and key prefixes, and refuses deletes for a grant with no key prefix. What it cannot know is which member owns a key, so that check is yours. Keep each member's pictures under members/<id>/ (the trailing / stops members/1/ from matching members/10/) and give the helper that folder as memberPrefix. The keys themselves should come from your database, never from the request. With Storage's default name templates the size variants sit beside the main key in the same folder. If you pass your own widthName or squareName, keep the variants in that folder too (no / in the template).

import { removeAuthvioPictureObjects, pictureObjectKeys } from "@empire/storage/authvio-picture";
import { StorageLinks } from "@empire/storage";

// deleteCredential (a workload token with scope storage:delete), storedResult and member are your app's own.
const links = new StorageLinks({ credential: deleteCredential });

const r = await removeAuthvioPictureObjects(links, {
  bucket: BUCKET,
  keys: pictureObjectKeys(storedResult), // keys YOU recorded for this member, never keys from a request
  reason: "profile picture replaced",
  memberPrefix: `members/${member.id}/`,
});
if (r.failed.length) log.warn("old picture objects left", r.failed);

Bolrach account routes

Bolrach Mail, Workspace and the bolrach.com account use these routes. They are served at https://bolrach.com/api, https://workspace.bolrach.com/api and https://mail.bolrach.com/api, and on bolrach.com the image addresses are same-origin. They are the reference for building the same thing on your platform. They act only on the signed-in member's own row. The web signs in with its session cookie, and apps send the Authvio id_token as Authorization: Bearer.

GET /api/me/profile

The member's photo and cover. It answers at once. If their Authvio photo should be copied, that happens in the background, and the next read shows it.

{
  "photo": {
    "url": "/api/profile-images/9f2c…e1/full-s256.webp",
    "urls": {
      "96":  "/api/profile-images/9f2c…e1/full-s96.webp",
      "256": "/api/profile-images/9f2c…e1/full-s256.webp",
      "512": "/api/profile-images/9f2c…e1/full-s512.webp"
    },
    "source": "authvio"
  },
  "cover": { "url": null, "urls": {}, "source": "none" }
}

source is 'own', 'authvio' (your stored copy, never Authvio's address) or 'none' (show initials; url is null).'none' means the member removed their Authvio picture: show initials. 'authvio' with a null url means nothing is stored yet: show the Authvio picture you already have, else initials. Photo sizes are 96, 256 and 512 squares. The cover's url is the 1920 × 640 picture, and its sizes are 640, 1280 and 1920 wide. Loading an image needs no sign-in, because the address holds a random 128-bit id. Images are served as image/webp with nosniff and cached as immutable. A change makes a new id, and any other file name returns 404.

PUT /api/me/photo · /api/me/cover

The body is the raw image bytes, with Content-Type set to JPEG, PNG, WebP, HEIC, HEIF, AVIF or a still GIF, and a declared Content-Length. The new picture applies at once, and the previous picture's files are deleted. The response is the new { photo, cover }. Each file has a size limit, and there is no limit per person or per day.

curl -X PUT "https://bolrach.com/api/me/photo" \
  -H "Authorization: Bearer $AUTHVIO_ID_TOKEN" \
  -H "Content-Type: image/jpeg" \
  --data-binary @me.jpg
DELETE /api/me/photo · /api/me/cover

Removes the photo by the rules above, or sets the cover to 'none'. The response is the new { photo, cover }. If the photo changed between the read and the write, the response is 409 changed.

curl -X DELETE "https://bolrach.com/api/me/photo" \
  -H "Authorization: Bearer $AUTHVIO_ID_TOKEN"
POST /api/profiles/photos

Photos for up to 200 Authvio subjects at once: { "subjects": [ … ] } returns { "photos": { "<subject>": { url, urls, source } } }. You only get people who share an active organization with the caller, in any product; everyone else is left out. An invalid list returns 400 bad_subjects.

Errors

Every error has the shape { "error": { "code", "message", "status" } }. The message is a sentence you can show the member as it is.

StatusCodeWhen
400emptyNo bytes were sent.
401unauthenticatedNo valid session or token. This is checked before the body is read.
409changedRemove raced another change. Read the profile again.
411length_requiredNo Content-Length, or a chunked body.
413too_largeThe declared size is over the per-file limit (20 MB by default; an admin setting is coming), so the body is not read.
413image_too_largeStorage refused the image's size.
413body_not_allowedA body was sent with GET, DELETE or another method that takes none.
415not_an_imageThe type is not accepted, or the file is not the image it claims to be.
422image_unreadable · image_animated · file_refusedThe file is unreadable, animated, or refused by the virus scan.
503image_pipeline_unavailableStorage could not store the picture (unreachable or an unexpected error). Try again shortly.

In the apps

Flutter apps crop with the shared photo_crop package (pickAndCrop: aspect: 1, round: true for a photo, aspect: 3 for a cover). They upload with the PUT above and show the URLs the API returns. Show the 96 size in lists and the 256 size on the profile. When source is 'none', show initials. Put "Change photo" and "Change cover" on the member's own profile, and "Remove" next to each.