Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

scripts/README.md

@@ -0,0 +1,72 @@
+# Bootstrap and state scripts
+
+All scripts in this directory use only the Python standard library so they work before the project toolchain is installed.
+
+```bash
+python scripts/validate_pack.py
+python scripts/next_packet.py
+python scripts/render_luna_context.py
+python scripts/update_state.py WP-000 in_progress
+python scripts/create_manifest.py
+python scripts/promotion_preflight.py --env-file <operator-owned-production.env> --phase predeploy --verify-registry
+```
+
+`validate_pack.py` checks packet dependencies/references, catalog identities and cross-references, contract JSON syntax, forbidden generic tool patterns, obvious secrets, and an optional checksum manifest.
+
+`render_luna_context.py` intentionally fails rather than silently truncating authoritative files. Narrow a packet's `read` list if a future context bundle becomes too large.
+
+`update_state.py` enforces ordinary packet transitions and synchronizes a small machine-state section in `CURRENT_STATE.md`. Significant implementation detail still belongs in the packet evidence and human-readable state sections.
+
+`promotion_preflight.py` is a read-only, fail-closed production gate. It checks
+operator-supplied paths, secret-file mode/ownership, immutable Compose image
+references, Docker networks, DNS expectations, and TCP reachability without
+printing secret values. It must be run with an external production env file;
+the repository `.env.example` is intentionally not sufficient.
+
+`verify_demo_token_runtime.py` is a second, live-Docker read-only gate for the
+Fleet Ops demo token. Run it on Tower immediately before minting or revoking:
+
+```sh
+python scripts/verify_demo_token_runtime.py \
+  --router-container itworx-mcp-hub-dataplane-router-1 \
+  --expected-host-file /srv/example/appdata/itworx-mcp-hub/config/demo-token-revocations.json
+```
+
+It rejects a missing env-file value, a repository example fallback, a wrong
+mount source, a writable mount, or any file mode other than `0600`.
+
+`verify_demo_token_flow.py` is the live functional proof. It mints a one-hour
+demo token in memory, calls the fixed Fleet Ops tool, atomically revokes that
+token even when the valid call fails, then requires a `401` for the revoked
+call. It prints only HTTP/content metadata, never the token or response body:
+
+```sh
+python -m scripts.verify_demo_token_flow \
+  --endpoint https://mcp.example.test/mcp/mobilityops/prod \
+  --key-file /srv/example/appdata/itworx-mcp-hub/secrets/demo_token_signing_key \
+  --revocations-file /srv/example/appdata/itworx-mcp-hub/config/demo-token-revocations.json
+```
+
+On Tower, use the optional container profile instead of the host Python
+runtime (which is intentionally not a project dependency environment):
+
+```sh
+docker compose --env-file /srv/example/appdata/itworx-mcp-hub/config/production.env.pending \
+  -f infrastructure/compose/docker-compose.yml \
+  -f infrastructure/compose/docker-compose.prod.yml \
+  run --rm --no-deps operator-tools \
+  --endpoint http://dataplane-router:8080/mcp/mobilityops/prod \
+  --key-file /run/secrets/demo_token_signing_key \
+  --revocations-file /etc/itworx/demo-token-revocations.json
+```
+
+## Codex machine clients
+
+The production Codex path is documented in
+`docs/04-mcp/CODEX_INTEGRATION.md`. Its bounded operator tools are:
+
+- `new_codex_credential.ps1`: create a CSPRNG credential in a current-user-only file;
+- `authentik_provision_mcp_service_account.py`: idempotent Authentik shell payload;
+- `provision_machine_client.py`: activate the exact Authentik subject and project binding;
+- `install_codex_mcp.ps1`: install the secret-free Codex stdio configuration;
+- `mcp_stdio_bridge.py`: retrieve/refresh M2M tokens and forward only allowlisted MCP methods.