Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

docs/02-security/CHATGPT_OAUTH_CONNECTION_PERSISTENCE.md

@@ -0,0 +1,55 @@
+# ChatGPT OAuth connection persistence
+
+The public MCP endpoint is expected to remain connected in ChatGPT without periodic interactive re-authorization while the OAuth grant remains valid.
+
+## Required provider contract
+
+The Authentik OAuth2/OIDC provider used by the ChatGPT MCP app must expose the `offline_access` scope mapping in addition to `openid`, `profile`, and `email`. This lets a compliant OAuth client request a refresh token instead of depending only on the original access token.
+
+Production configuration therefore requires:
+
+```text
+AUTHENTIK_SCOPES=openid,profile,email,groups,offline_access
+```
+
+`groups` remains required by the Hub's existing role mapping. The ChatGPT
+provider itself uses `openid profile email offline_access`. The public
+protected-resource metadata and the MCP `401 WWW-Authenticate` challenge must
+advertise that same refresh-capable scope set. `promotion_preflight.py` fails
+closed when either `openid` or `offline_access` is absent.
+
+## Authentik one-time reconciliation
+
+In the Authentik admin interface, open the OAuth2/OIDC provider backing the
+ChatGPT application (`Provider for ChatGPT - ITWorx Gitea` in production) and
+include the built-in `offline_access` scope mapping under Scope mappings. This
+is distinct from the browser-facing Hub provider. Keep the authorization-code
+flow enabled and keep refresh-token support enabled. Do not weaken redirect
+URI, PKCE, audience, or group restrictions to obtain persistence.
+
+After changing the provider, verify its OpenID discovery metadata advertises `offline_access` in `scopes_supported` and verify an authorization requesting that scope receives a refresh token.
+
+Run production preflight with `--verify-oidc-discovery`. This checks both the
+browser-facing Hub issuer and the ChatGPT issuer for an exact issuer, HTTPS
+authorization/token endpoints, authorization-code and refresh-token grants,
+S256 PKCE, and `openid` plus `offline_access` publication.
+
+## Validated production settings
+
+The production ChatGPT provider is confidential and uses one strict
+`https://chatgpt.com/connector/oauth/...` redirect. Its access tokens are valid
+for five minutes. Refresh tokens are valid for 365 days and the refresh
+threshold is `seconds=0`; on the deployed Authentik version this rotates the
+refresh token on every successful refresh and revokes the prior token. These
+settings preserve short access-token exposure, revocability, and durable
+connections without disabling PKCE or widening redirect matching.
+
+## ChatGPT reconciliation
+
+OAuth metadata can be cached at app creation time. After the provider is corrected, recreate or reconnect the ChatGPT MCP app once so ChatGPT reads the updated provider metadata. Thereafter access-token renewal should use the refresh token and should not require routine interactive reconnects.
+
+A future reconnect can still be legitimate after explicit revocation, refresh-token expiry or rotation failure, provider/client reconfiguration, security-policy changes, or deletion/recreation of the ChatGPT app.
+
+## Operational rule
+
+Do not work around reconnect prompts by making access tokens effectively permanent or by replacing user OAuth with a shared long-lived bearer token. Refresh-token based OAuth persistence preserves revocability and the existing identity boundary.

docs/02-security/DOCKER_BROKER_RUNTIME.md

@@ -0,0 +1,7 @@
+# Docker read broker runtime
+
+`docker-read-broker` is the only service with `/var/run/docker.sock`. Its public compose surface has no host port and the broker is attached only to the internal broker network. The root filesystem is read-only, capabilities are dropped, and the registration file and service token are mounted read-only.
+
+The broker accepts only authenticated `GET` requests for host status, bounded storage, registered container list/inspect/health/logs, and bounded network metadata. Mutation, exec, image, volume, secret/config, arbitrary filters, and arbitrary Engine API paths are absent or denied. A stable registered ID is resolved to an immutable container ID and verified against compose project/service labels before inspection. Caller project and environment are taken from a short-lived HMAC service token, never from a free-form container request.
+
+The deterministic fake backend and acceptance tests cover registration isolation, label spoofing, mutation/raw-route denial, secret/control-character log redaction, bounded logs, token expiry, and socket-unavailable degradation. No live Docker socket or Unraid host was modified for WP-100.

docs/02-security/DOCKER_BROKER_SECURITY.md

@@ -0,0 +1,43 @@
+# Docker Read Broker Security
+
+## Purpose
+
+The broker contains the unavoidable Docker socket trust boundary and prevents MCP-facing services from receiving raw Engine API access.
+
+## v1 API allowlist
+
+- list registered containers with bounded fields;
+- inspect one registered container;
+- read health/status;
+- read bounded recent logs;
+- list registered networks needed for topology display;
+- return host Docker version and non-sensitive capacity summary.
+
+## Explicitly absent
+
+- create/start/stop/restart/remove;
+- exec;
+- image build/pull/push/remove;
+- volume content access;
+- secret/config access;
+- arbitrary Docker API path;
+- arbitrary filters that reveal unrelated containers;
+- host filesystem mounts.
+
+## Registration
+
+The Hub passes a signed or mutually authenticated request containing a stable project/environment registration. The broker maps that registration to container IDs or immutable labels discovered during reconciliation. A client-supplied container name is never trusted alone.
+
+## Hardening
+
+- internal connector network only;
+- mTLS or short-lived internal service token;
+- no published host port;
+- read-only root filesystem and no package manager;
+- minimal dependencies;
+- bounded log bytes and time range;
+- reject containers not registered to the project;
+- structured Docker SDK calls, never shell commands;
+- dedicated security tests against write methods.
+
+Mounting the socket read-only does not make Docker access read-only by itself. The broker's application-level API is the controlling boundary.

docs/02-security/IDENTITY_AND_AUTHORIZATION.md

@@ -0,0 +1,55 @@
+# Identity and Authorization
+
+## Human management users
+
+Use Authentik OIDC authorization code flow with PKCE and a same-origin BFF session. Browser JavaScript receives only user/session metadata and CSRF protection, never reusable access or refresh tokens.
+
+## Machine clients
+
+Each MCP client has its own principal and credential. Preferred flow is client credentials or an Authentik service-account equivalent with audience restricted to the MCP Hub.
+
+Examples:
+
+```text
+svc-mcp-codex-workstation
+svc-mcp-claude-workstation
+svc-mcp-ludarium-prod
+svc-mcp-inspector
+```
+
+Never reuse one broad token across projects.
+
+After machine authentication and database-backed binding authorization, the
+dataplane replaces all caller-supplied identity headers and signs the exact
+project, environment, client, trace, and timestamp tuple. ContextForge forwards
+that assertion without receiving the signing key. Every connector verifies the
+HMAC and the 60-second age bound before repeating its own project, environment,
+and resource-registration checks. Missing, expired, or modified assertions deny.
+
+## Effective authorization inputs
+
+- trusted issuer and audience;
+- principal subject;
+- client identity;
+- workspace;
+- project;
+- environment;
+- endpoint/virtual server;
+- capability or tool;
+- risk class;
+- enabled status and revocation time;
+- matching policies and role bindings.
+
+## Decision semantics
+
+- explicit global deny wins;
+- disabled entities deny;
+- missing project/environment binding denies;
+- missing capability binding denies;
+- any matched deny wins over allows;
+- allow decisions include a trace explaining matched rules;
+- clients never select their own project through an untrusted body field when the endpoint already scopes it.
+
+## Revocation
+
+Client disable or binding removal must affect new requests immediately or within a documented cache ceiling of at most 60 seconds. Cache invalidation is event-driven where possible and always bounded.

docs/02-security/OUTPUT_SAFETY.md

@@ -0,0 +1,34 @@
+# Output Safety
+
+MCP results may be consumed by agents and therefore are an untrusted content channel.
+
+## Required result envelope
+
+Every tool result should provide structured data and metadata:
+
+```json
+{
+  "data": {},
+  "meta": {
+    "project": "...",
+    "environment": "...",
+    "source": "...",
+    "truncated": false,
+    "nextCursor": null,
+    "generatedAt": "..."
+  },
+  "warnings": []
+}
+```
+
+## Rules
+
+- mark truncation explicitly;
+- never silently omit authorization failures;
+- distinguish target unavailability from empty results;
+- normalize control characters in logs;
+- return plain text only when the contract requires it;
+- cap nested depth and collection size;
+- do not render untrusted HTML in the UI;
+- resource descriptions and tool metadata come from managed manifests, not target content;
+- include source identifiers so an agent can verify where information came from.

docs/02-security/POLICY_GOVERNANCE_RUNTIME.md

@@ -0,0 +1,15 @@
+# Policy governance runtime
+
+WP-110 provides one deterministic evaluator for management simulation, the dataplane router, and first-party connector invocation adapters. Rules are parsed into typed selectors and evaluated in this order:
+
+1. missing binding is denied;
+2. terminal global denials are evaluated before any allow;
+3. explicit denials are evaluated;
+4. typed allows and their enumerated conditions are evaluated;
+5. the default is deny.
+
+Rules contain selector values and bounded conditions only. They cannot execute scripts, perform regex evaluation, make outbound calls, or expand a project scope implicitly. A development selector matches only development; it does not imply production.
+
+The `Governance` boundary carries the same `InvocationContext` into the rate limiter and append-only audit sink. A permitted call emits one success or error event; a denied or rate-limited call emits one corresponding event. The audit projection stores a SHA-256 argument hash, redacted bounded arguments, matched rule IDs, and a sanitized decision trace. Credentials and authorization headers are never included.
+
+Connectors still perform their own project, environment, repository, document, and registered-container checks. Gateway policy is an additional boundary, not a substitute for connector authorization.

docs/02-security/SECRETS_AND_REDACTION.md

@@ -0,0 +1,45 @@
+# Secrets and Redaction
+
+## Storage
+
+Secrets are supplied through Docker secrets or read-only files below `/run/secrets`. Configuration stores only a secret reference.
+
+Example:
+
+```yaml
+credentials:
+  type: docker_secret
+  reference: gitea_mcp_read_token
+```
+
+No real secret appears in Git, catalog YAML, `.env.example`, test fixtures, screenshots, evidence, or generated client configuration.
+
+## Redaction stages
+
+1. reject secret-shaped input where a field should not accept it;
+2. omit sensitive headers from logs;
+3. sanitize target-system output in the connector;
+4. apply a final result redaction profile;
+5. sanitize audit arguments and response summaries;
+6. run automated secret scanning over repository and evidence.
+
+## Patterns
+
+At minimum detect:
+
+- bearer/JWT tokens;
+- basic auth values;
+- private-key blocks;
+- common API key formats;
+- connection strings with passwords;
+- cookies and session IDs;
+- Authentik/Gitea tokens;
+- environment variable names marked sensitive.
+
+## Audit representation
+
+Use a stable argument hash and a small sanitized projection. Never solve auditability by storing the entire raw request.
+
+## UI
+
+Secret fields are write-only. The UI shows state such as `configured`, `missing`, or `last rotated`, never the value or a reversible masked form.

docs/02-security/SECURITY_INVARIANTS.md

@@ -0,0 +1,24 @@
+# Security Invariants
+
+These rules override every lower-level requirement.
+
+1. **No arbitrary execution.** No generic shell, command, script, or interpreter tool may be exposed.
+2. **No raw Docker capability.** The Docker socket is mounted only into the dedicated read broker. No raw Docker API proxy exists.
+3. **No arbitrary file access.** Every readable path is registered, canonicalized, allowlisted, and mounted read-only.
+4. **No unrestricted SQL.** v1 has no general database query tool. Future database access must use a dedicated least-privilege account and query guard.
+5. **No secret retrieval.** Secrets can be consumed internally but never returned, indexed, audited verbatim, or shown in UI.
+6. **Deny by default.** Absence of an explicit binding or allow decision means deny.
+7. **Project and environment isolation.** Every invocation is checked against both dimensions; dev access never implies prod access.
+8. **Connector revalidation.** Each connector validates caller context and target allowlists; gateway visibility is insufficient.
+9. **Audience-bound tokens.** A token must be issued for the Hub resource and trusted issuer. Token forwarding to unrelated services is prohibited.
+10. **Bounded input and output.** Requests, logs, repository files, search results, and lists have strict limits and pagination.
+11. **Sanitized audit.** Audit records identify the action without storing access tokens, passwords, private keys, connection strings, or unlimited payloads.
+12. **No destructive tools.** v1.0 target-system capabilities are read-only. Post-v1 bounded writes must remain reversible and may not expose merge, delete, force-push, default-branch mutation or repository administration.
+13. **Reversible deployment.** Migrations and upgrades require backup, health verification, and a tested rollback or restore path.
+14. **No implicit permission expansion.** Adding a connector or tool does not expose it to existing clients until explicit bindings are reconciled.
+15. **Untrusted content remains data.** Repository files, docs, logs, and MCP results may contain prompt injection; they never modify policy or authorization.
+
+
+## WP-160 additions
+
+Connector and dataplane target URLs must use HTTPS and must not resolve from an unsafe IP literal or metadata/localhost hostname. The security scan is fail-closed for non-fixture secret patterns, raw Docker mounts, mutable third-party images, unsafe host/container settings, and unintended published ports.

docs/02-security/SECURITY_TEST_PLAN.md

@@ -0,0 +1,58 @@
+# Security Test Plan
+
+## Identity
+
+- invalid signature, issuer, audience, expiry, not-before;
+- revoked client and disabled project;
+- dev token against prod alias;
+- user session fixation, CSRF, logout, refresh expiry;
+- duplicate and conflicting group/role bindings.
+
+## Router
+
+- unknown alias;
+- encoded path traversal;
+- oversized body;
+- hop-by-hop header injection;
+- attacker-supplied upstream host;
+- authorization header logging test;
+- timeout and partial-stream handling.
+
+## Connectors
+
+- path traversal and symlink escape;
+- SSRF and redirect to disallowed address;
+- output containing tokens, cookies, ANSI/control characters, and HTML;
+- target resource from another project;
+- pagination abuse and oversized output;
+- malicious document prompt injection retained as data only.
+
+## Docker broker
+
+- every write/exec endpoint absent;
+- raw API path denied;
+- unregistered container denied;
+- Docker label spoof resistance;
+- bounded logs;
+- socket unavailable degradation.
+
+## Persistence and audit
+
+- migration rollback/restore;
+- sanitized arguments;
+- audit cannot be modified through normal API;
+- retention job does not delete within protected window;
+- cache flush does not alter authorization truth.
+
+## Supply chain
+
+- lockfile integrity;
+- exact container digests in release manifest;
+- SBOM generated;
+- secret scan clean;
+- dependency and image scan policy enforced.
+
+
+## WP-160 executable gates
+
+`tests/test_wp160_security.py` covers prompt injection as data, secret-like content rejection, registered-root traversal, SSRF host literals, token-reference boundaries, gateway drift, Compose socket/public-port invariants, and SBOM contents. `scripts/security_scan.py` performs the deterministic source/Compose policy scan; `scripts/generate_sbom.py` emits a CycloneDX 1.5 inventory from locked Python/Node manifests and declared container images. Fixture-only findings are explicitly classified and do not become production evidence.

docs/02-security/SESSION_STORE_DECISION.md

@@ -0,0 +1,85 @@
+# Session store: production decision (WP-230E)
+
+## Decision
+
+`control-api`'s management-session store (`services/control_api/auth/bff.py`
+`SessionStore`) is an **in-memory, single-process store, and this is the
+accepted v1 production design** -- not a placeholder awaiting a Redis
+migration. `control-api` MUST run as exactly one instance/replica. This
+document is the load-bearing artifact for that constraint: code and Compose
+must stay consistent with it, and `scripts/compose_release_check.py` enforces
+the Compose side of it statically (see below), not just the docstring.
+
+## Why this, not a Redis-backed store
+
+`redis` is already a hard Compose dependency of `control-api`
+(`docker-compose.yml`'s `control-api.depends_on.redis`), which reads as an
+implied promise that sessions are Redis-backed. They are not: no
+`HUB_REDIS_*` setting exists, and no code path talks to Redis for sessions.
+That gap is exactly what this decision closes.
+
+A real Redis-backed store was evaluated and deferred rather than built now,
+for a concrete, checkable reason: it requires a new production runtime
+dependency (`redis`, or an async client) added to `pyproject.toml` and
+locked via `uv lock`. At the time of this decision `uv` was not reliably
+resolvable in the environment this work was executed in, so a lockfile
+change could not be produced with real confidence -- and a session store
+touches authentication, the most security-sensitive path in this service.
+Shipping unlocked or hand-edited dependency pins for that specific subsystem
+is a worse outcome than shipping the honestly-documented current design.
+This is a tooling-availability constraint on *when*, not a judgment that
+Redis-backed sessions are undesirable; re-scoping this work is the correct
+next step once dependency tooling is confirmed reliable (see "Revisiting
+this decision" below).
+
+## What "single instance" actually means here
+
+- Every session and every CSRF token lives in one process's memory
+  (`SessionStore._records`, a plain `dict` guarded by a `threading.RLock`).
+- A restart, redeploy, or crash of `control-api` invalidates every active
+  session. Users see this as being signed out and must re-authenticate
+  through Authentik; no data is lost, no state is corrupted, and the BFF's
+  same-origin cookie/CSRF model means there is nothing to reconcile on the
+  client side.
+- Running two or more `control-api` replicas behind a load balancer would
+  silently split sessions and CSRF tokens across disjoint in-memory stores.
+  A request routed to instance B with a session cookie issued by instance A
+  would see "session expired" even though the session is, from the user's
+  perspective, still valid -- and worse, CSRF token mismatches on that same
+  split would be indistinguishable from a real CSRF attack in the logs.
+  This is a correctness and security-signal problem, not just an HA gap, so
+  it is enforced, not left to operational discipline.
+
+## Enforcement (not just documentation)
+
+- `docker-compose.yml` and `docker-compose.prod.yml` do not declare
+  `deploy.replicas` for `control-api` (or anywhere); Compose's default is
+  one container per service, so the constraint already holds today.
+- `scripts/compose_release_check.py::check_compose` now fails the release
+  gate if `control-api` ever declares `deploy.replicas != 1`. This is a
+  static, automated check (`tests/test_wp150_operations.py` and the new
+  `tests/test_wp230_session_store.py` exercise it), run as part of
+  `python scripts/compose_release_check.py` and the release-readiness gate
+  -- so a future change that tries to scale `control-api` fails loudly
+  before it reaches production, instead of failing silently at 2am when a
+  real user hits the split-brain session bug above.
+- `SessionStore`'s docstring states the single-instance constraint directly
+  at the point where a future change is most likely to be made, and points
+  back to this document.
+
+## Revisiting this decision
+
+Move to a real shared store (Redis-backed, encrypted-at-rest session
+payloads, TTL-matched key expiry, explicit logout invalidation, and defined
+behavior for a Redis outage -- fail closed, forcing re-authentication,
+rather than silently falling back to per-instance memory) when:
+
+1. `uv lock` can be run and verified in the environment doing the work, so
+   the new dependency's lock entry is trustworthy, and
+2. there is an actual operational need for more than one `control-api`
+   replica (there is none today -- Tower runs a single instance of every
+   owned service).
+
+Until then, this document and the `compose_release_check.py` gate are the
+enforced contract: single instance, in-memory, sessions do not survive a
+restart, and that is by design.

docs/02-security/THREAT_MODEL.md

@@ -0,0 +1,63 @@
+# Threat Model
+
+## Assets
+
+- Authentik tokens and service identities;
+- connector credentials;
+- project source and documentation;
+- container metadata and logs;
+- Docker socket access;
+- policy and client bindings;
+- audit integrity;
+- gateway configuration;
+- backup material.
+
+## Trust boundaries
+
+1. external MCP client to NPM/router;
+2. browser to web/control API;
+3. control plane to Authentik;
+4. router/control plane to ContextForge;
+5. ContextForge to connectors;
+6. connector to target system;
+7. Docker broker to Docker socket;
+8. services to PostgreSQL/Redis;
+9. backup process to storage.
+
+## Primary threats and controls
+
+| Threat | Example | Required controls |
+|---|---|---|
+| Token substitution | token issued for another API reused at MCP endpoint | issuer, audience, expiry, signature, resource validation |
+| Confused deputy | connector called with a target from another project | connector-side project/resource allowlist |
+| Tool poisoning | malicious description or output tries to alter agent behavior | managed manifests, sanitize metadata, treat content as data |
+| Prompt injection | README tells agent to reveal secrets | never authorize from content; explicit tool policies |
+| SSRF | connector endpoint points to metadata service | registered endpoints, URL parser, private-range policy, no arbitrary URL |
+| Path traversal | `../../secrets` in resource URI | canonical path and root containment checks |
+| Command injection | container name placed into shell command | no shell; structured Docker SDK calls |
+| Excessive data exfiltration | huge log/file response | pagination, byte/row/time limits, redaction |
+| Secret leakage | token appears in logs/tool output | structured logging, secret scanners, redaction profiles |
+| Approval replay | old operation approval reused | plan hash, actor, target, expiry, single-use state |
+| Audit tampering | operator deletes incriminating event | append semantics, restricted DB role, export/retention |
+| Supply-chain compromise | mutable `latest` image changes | exact tags/digests, SBOM, scans, update gate |
+| DoS | expensive repeated search/log calls | per-client rate limit, timeouts, concurrency caps |
+| Cross-project cache bleed | cached result returned to wrong project | project/environment/client in cache key |
+| Docker breakout | compromised broker abuses socket | minimal API, read-only logic, network isolation, no arbitrary labels/exec |
+
+## Abuse cases to test
+
+- a VacatureRadar token requests a Ludarium endpoint;
+- a production-observer client invokes an unbound write name;
+- a document path escapes its registered root through symlinks;
+- a Gitea file contains a fake token and malicious instructions;
+- Docker logs contain an Authorization header;
+- an unknown alias attempts to proxy to an attacker-controlled URL;
+- a revoked client reuses a cached token;
+- ContextForge returns a tool not present in the desired catalog;
+- Redis is flushed during reconciliation;
+- a connector returns more than the output budget.
+
+
+## WP-160 implementation notes
+
+The Gitea and MCP dataplane URL contracts reject localhost, metadata hostnames, and private, loopback, link-local, reserved, unspecified, or multicast IP literals. Redirects remain same-origin and bounded. Repository test fixtures may contain deliberately fake secret-like values; the security scan classifies those paths as fixture placeholders and fails on non-fixture findings.