GuDuu authentication service — corresponding source and build instructions

Scope
-----
The source archive contains the complete unmodified MAS 1.25.1 upstream tree
at 97945cd9e7869bc5cdc4322bfc26cef552f11157, the GuDuu presentation modifications,
SCSS sources, supplied font/artwork files, dependency locks and build scripts.
SOURCE-MANIFEST.json records every included input hash. Runtime credentials,
user data and independent services are not part of this source archive.

License
-------
Read AGPL-3.0.txt and NOTICES.txt in this directory. The covered code can be
modified and redistributed under AGPL-3.0-only and is provided without warranty.
The included third-party components retain their original licenses.

Prepare and build
-----------------
Use Python 3.12 or newer, Docker with BuildKit, and an Internet connection to
retrieve public, locked dependencies and base images. No private repository,
GuDuu account or production credentials are required.

1. Extract the source archive into an empty directory and enter it.
2. Run the following to regenerate the public legal assets and source archive:
   python3 distro/staging/mas-locales/compliance/rebuild_offer.py
3. Build from this directory (the default Identity destination is the GuDuu staging node):
   docker build -f distro/staging/mas-locales/Dockerfile -t guduu-mas:local .

For another node, set its exact trusted HTTPS Identity origin at build time:
   docker build --build-arg GUDUU_IDENTITY_ORIGIN=https://id.example.com \
     -f distro/staging/mas-locales/Dockerfile -t guduu-mas:local .
This changes only the explicit "use another account" destination, not OAuth
client registrations, federation trust, credentials or callback permissions.
Never take the build setting from user-supplied login parameters.

The default MAS_BASE is the exact official 1.25.1 image digest used by this
release. Its authentication executable is unmodified. The account UI is
rebuilt from the INCLUDED upstream/ tree, not from a remote branch. SCSS is
compiled using the included locked Sass build. Image assets include the
matching complete source archive and legal pages.

To build the authentication executable too, the complete Rust source,
Cargo.lock, policies and upstream Docker build are included:
   docker build -t guduu-mas-upstream:local upstream
   docker build --build-arg MAS_BASE=guduu-mas-upstream:local \
     -f distro/staging/mas-locales/Dockerfile -t guduu-mas:local .
The upstream build downloads public toolchains/dependencies. Compiler and
base-image differences can change binary bytes; this is not a promise of
bit-for-bit reproduction of the official upstream image.

Configuration and running
-------------------------
Use upstream/docs/setup/ and upstream/docs/reference/configuration.md to
configure a NEW test instance. You will need PostgreSQL and a compatible
Synapse instance. Generate your OWN keys/secrets/configuration with:
   docker run --rm guduu-mas:local config generate
Save the generated configuration privately and edit it as described in the
included upstream docs. Then run the service with your configuration mounted:
   docker run --rm -p 8080:8080 -v "$PWD/mas.yaml:/config/mas.yaml:ro" \
     -e MAS_CONFIG=/config/mas.yaml guduu-mas:local server
Database setup/migrations and identity-provider registration follow the upstream
docs. This source release does not confer access to any GuDuu deployment.
The existing recovery UI contains a GuDuu staging destination; adapt the
recovery.js/error.html destinations and the GUDUU_IDENTITY_ORIGIN build setting when configuring a different deployment.

Verification and updates
------------------------
Read /assets/guduu/legal/source.json in the running image to identify its
source archive. The filename contains its SHA-256 digest. The visible source
entry exists in both the server-rendered shell and account SPA shell.
Run python3 -m unittest discover -s distro/staging/mas-locales/compliance \
  -p 'test_*.py' to test packaging boundaries and shell entries.
Rebuild the source offer AND image whenever source changes. Keep already
published source archives available; do not replace their immutable filenames.

For upgrades, copy /usr/local/share/mas-cli/assets/guduu/legal/ from the
previously published container into a temporary directory. Run prepare.py
from the private development checkout with --retain-offers <that-directory>
and --archive-store <persistent-public-source-directory>. Only source archives
with matching SHA-256 filenames are retained. The persistent directory must
be outside release cleanup and contain public source archives only. The new
image serves both current and retained archives at their unchanged URLs;
source.json and the legal page identify the current version only. Historical
archives are not recursively embedded in the new corresponding-source tar.
The staging deploy script performs these retention steps automatically.

MAS serves static assets with immutable caching by default. Configure the
reverse proxy to override Cache-Control to "no-cache, max-age=0" for
/assets/guduu/legal/* EXCEPT source-*.tar.gz. The staging Caddy configuration
implements this. Page-shell source links include the current source digest
as a query parameter to bypass legal pages cached before this fix. Preserve
this versioned entry when customizing the shell. Long digests wrap on narrow
screens without changing the copied or downloaded checksum.
