Hosted pm-web legal overlay

This is the private deployment boundary and operator runbook for the legal pages served by the hosted pm-web service. It is an engineering record, not a substitute for qualified legal review.

Ownership boundary

The public @unbrained/pm-web package ships operator-neutral placeholder pages. The hosted service must replace all four through the private deployment overlay in ops/pm-web-legal/:

• legal-notice.html;
• privacy-policy.html;
• terms.html; and
• cookie-settings.html.

These pages preserve the controller identity, contact channel, address, and Austrian jurisdiction from the previously deployed hosted notices. Do not invent or silently change those facts. Any controller, contact, jurisdiction, service-provider, purpose, legal-basis, recipient, or terms change requires operator and legal review.

The overlay is private deployment configuration. Never copy it to the public pm-web repository/package, public CI artifacts, public container build context, documentation examples, test fixtures, screenshots, issue bodies, or generated package catalogs. Never place secrets, tokens, user records, log samples, database values, or production exports in these HTML files.

Current processing inventory

The privacy and cookie pages describe these actual or conditional flows:

• password accounts and technically necessary pm-web session/security data;
• a separate confidential Authentik OIDC client, with issuer/subject and verified identity claims mapped through pm_external_identities;
• project/ACL metadata in private PostgreSQL, canonical pm item/history/configuration data in pm-cli_pm-web-projects, and optional graph state in private Neo4j;
• optional user-authorized GitHub functionality, which is not required for registration or general pm features;
• conditional pm-gpt Remote MCP access from ChatGPT/Codex, including OAuth identity, scopes/grants, minimum tool inputs/results, and transmission of authorized results to the user-connected client;
• the necessary pm_token and temporary pm_oidc_state cookies plus local preference/PWA storage;
• private application, reverse-proxy, and security logs and private multi-store backups.

No uniform fixed log or backup retention duration is documented because no corresponding technically enforced schedule has been approved for all these stores. Do not add a numeric promise until implementation, backup expiry, deletion behavior, and restore effects have been tested and documented. The notice must continue to explain that deletion from active storage may not remove an existing backup immediately.

Compose contract

docker-compose.yml must contain both:

environment:
  - PM_WEB_LEGAL_DIR=/run/pm-web-legal
volumes:
  - ./ops/pm-web-legal:/run/pm-web-legal:ro

The public pm-web application validates that the configured path is absolute and contains all four real regular files. Missing pages and file symlinks fail application startup. The mount is read-only so the service cannot alter the reviewed source pages.

Change and deployment procedure

1. Review the current runtime topology, enabled integrations, cookies/storage, logs, backup behavior, and deletion procedure. Do not infer a data flow from a planned feature.

2. Update only the affected private pages. Preserve the existing controller/jurisdiction unless an explicitly reviewed legal change says otherwise.

3. Run:

   scripts/check-pm-web-legal-overlay.sh
   scripts/check-pm-gpt-data-boundary.sh
   docker compose --env-file .env.example config --quiet
   

   The general pm-gpt boundary check invokes the dedicated legal-overlay check, so a missing, writable, incomplete, placeholder, or incorrectly wired overlay blocks the broader deployment gate as well.

4. Review git diff -- ops/pm-web-legal docker-compose.yml docs scripts/check-pm-web-legal-overlay.sh locally. Do not paste page bodies into public review systems or pm notes.

5. During an approved deployment, recreate pm-web so the new environment and mount are applied; a restart alone does not add a new bind mount.

6. Verify health and HTTP status for the four canonical routes without logging response bodies. Verify inside the container that the directory and four files are readable and not symlinks.

7. If validation or legal review fails, do not fall back to the public placeholders. Restore the last reviewed private overlay and recreate pm-web, or stop the hosted service until reviewed pages are available.

Review triggers

Re-review the pages when adding/removing an identity provider, external connector, model/client surface, processor, storage location, observability source, backup mechanism, retention/deletion implementation, new category of pm data, payment/terms feature, or controller/contact/jurisdiction detail. Also review after a security incident or a material provider terms/privacy change.