Skip to content

Configurable branding: colours, logo and busy animation via Administration - #470

Merged
bl0rb merged 2 commits into
mainfrom
claude/sweet-rubin-7v6mvl
Nov 16, 2026
Merged

bl0rb merged 2 commits into
mainfrom
claude/sweet-rubin-7v6mvl

Conversation

@bl0rb

@bl0rb bl0rb commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Summary

Admins can now set the look of portal and chat under Administration › Betrieb › Erscheinungsbild:

  • Primary and accent colour as hex codes. Text and contrast colours for light and dark mode are derived automatically.
  • Logo and busy animation (Lade-Animation) as SVG, GIF or PNG, at most 1 MiB. Animations can be an animated SVG or a GIF.

Both portal and chat use them, including the login pages, and the logo becomes the browser-tab icon. Without a setting, everything looks exactly as before.

How it works:

  • Ingest owns the data: tables branding_config and branding_assets (migration 0061, included in backups).
    • Palette derivation for light and dark mode.
    • Uploads are typed by their content, not by file name or declared type.
    • A strict, stdlib-only SVG check refuses scripts, event handlers, foreignObject, external references, xml:base, DTDs/entities, processing instructions and unsafe CSS.
    • Routes: public GET /api/v1/branding and GET /api/v1/branding/assets/{kind}; admin GET/PUT /api/v1/auth/admin/branding, PUT/DELETE /api/v1/auth/admin/branding/assets/{kind}.
  • weave-api exposes GET /v1/branding (+ /assets/{kind}) publicly and read-only, so the chat (and later the desktop app) can show branding before login.
    • In-process caches with last-good fallback, so a down Ingest never breaks the chat.
    • Per-resource single-flight and negative caching, so anonymous traffic cannot multiply calls to Ingest.
    • The asset cache honours ?v=.
  • Chat:
    • Fetches branding server-side with a 1.5 s timeout; on failure it shows today's look.
    • Injects the colours as CSS variables built only from validated hex values.
    • Proxies the assets on its own origin.
    • Sets the favicon and handles the busy tab.
    • Reduced motion is decided in the server markup.
  • Portal:
    • Branding provider, with the last palette cached in localStorage and applied before first paint.
    • The new admin tab, with i18n in German and English.
    • Brand components keep their emerald classes and switch to the tokens only under html:has(#weave-branding), so the default look is unchanged.
    • The API origin is added to img-src.
  • Security:
    • Assets are only ever rendered as <img>, never as inline markup.
    • Every hop serves them with Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src data:; sandbox, nosniff and a svg/gif/png allowlist.

No new env settings. contracts/openapi.json is regenerated (additive only). The CHANGELOG entry sits in the 0.7.25 section, because that release has not been published yet; the run was cancelled before any image was pushed.

Affected services

services/ingest (backend + frontend), services/api, services/chat, contracts/, docs/

Test plan

  • Ingest backend (branding service + API, migrations incl. the 0061 round trip, backup engine/API, runtime config): 167 passed
  • weave-api, full suite: 389 passed
  • Chat: npm run lint, npm run typecheck, npm test: 351 passed
  • Portal: npm run lint (0 errors), npm run typecheck, npm test: 307 passed; next build OK, and the compiled CSS contains the gated brand rules
  • scripts/tests (weave-mark sync check): passed, the built-in mark is unchanged
  • Independent multi-lens review (security / frontend / backend) with adversarial verification: 4 minor findings confirmed and fixed with regression tests (split <style> CSS in SVG, pre-hydration image error fallback, reduced motion in server HTML, ?v= in the weave-api asset cache)
  • PR CI
  • Manual check in a real browser: upload an animated SVG/GIF, dark mode, reduced motion, favicon (only jsdom so far)

Checklist

  • Tests added or updated for the changed behaviour
  • contracts/ updated if an API or event changed (openapi.json regenerated)
  • python scripts/weave_config.py check passes if configuration changed (n/a, no configuration change)
  • Docs in docs/ updated if operators or users see the change (docs/wissensportal.md, docs/api-referenz.md, services/api/README.md, services/chat/README.md)
  • No secrets, real customer data, or generated deploy/.env in the diff

Notes for reviewers

  • The desktop app (bl0rb/WeaveDesktop) is not part of this repo. It can later read GET /v1/branding from weave-api.
  • Animated GIF favicons only animate in Firefox; Chrome shows the first frame.
  • Changes reach the chat after about a minute (caches in Ingest, weave-api and chat). An admin sees the change in the portal immediately; other portal users see it on their next page load.

Generated by Claude Code

Admins set a primary and an accent colour as hex codes and upload a logo
and a busy animation (SVG, GIF or PNG, at most 1 MiB) under
Administration › Betrieb › Erscheinungsbild. Portal and chat apply them,
including the login pages and the browser-tab icon; without a setting
everything looks as before.

- Ingest: branding_config/branding_assets (migration 0061), palette
  derivation for light and dark mode, content-typed uploads with a strict
  SVG check, public GET /api/v1/branding (+ /assets/{kind}) and admin
  routes under /api/v1/auth/admin/branding; contracts/openapi.json
  regenerated.
- weave-api: public read-only GET /v1/branding (+ /assets/{kind}) for the
  chat, with caching and last-good fallback.
- Chat: server-side branding fetch, style injection, asset proxy,
  favicon and busy tab.
- Portal: branding provider, admin tab, brand components switch to the
  tokens only while a custom palette is applied.

Assets are only rendered as <img> and served with a sandbox CSP.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01W9t7FebTPSQxa4Av4VRenB
- Ingest SVG check: read <style> CSS the way browsers do (direct text,
  not child elements' text) and refuse <style> with child elements, so
  a child cannot split @import, url( or javascript: past the check.
- Chat logo: fall back to the built-in mark for an asset that already
  failed before hydration; decide reduced motion in the server markup
  (<picture> media source / motion-safe classes) instead of only in JS.
- weave-api asset cache honours ?v=: a newer requested version bypasses
  the cached bytes or a remembered miss (at most every 5 s per kind) and
  bytes that still do not match are sent with no-cache; the chat proxy
  forwards ?v= and passes that no-cache through.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01W9t7FebTPSQxa4Av4VRenB
@bl0rb
bl0rb merged commit d59c023 into main Nov 16, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants