hoi4-agent-tools 0.0.0-bootstrap.1 → 0.1.2

package/docs/release.md

@@ -0,0 +1,181 @@
+# Release and MCP Registry publication
+
+Releases use strict stable Semantic Versioning and an immutable Git tag. Every public writer
+re-queries both the direct tag and its optional annotated-tag peel immediately before the write.
+The peeled commit must equal `GITHUB_SHA` and the commit recorded in the release artifact.
+
+## Prerequisites
+
+- a clean tested commit on `main`;
+- package, server, source, schema, documentation, lockfile, and changelog versions synchronized;
+- the public GitHub repository owned by the canonical `klimPaskov` account;
+- GitHub release immutability enabled in repository settings before the first stable release;
+- a public, pre-bootstrapped `ghcr.io/klimpaskov/hoi4-agent-tools` package;
+- the npm namespace bootstrap completed and the trusted publisher configured;
+- GitHub Actions OIDC available for ordinary npm and MCP Registry publication.
+
+The release workflow uses the npm 11.16.0 CLI bundled with the pinned Node 24.18.0 LTS distribution.
+No release job upgrades npm globally. The ordinary npm OIDC publisher does not check out source,
+run `npm ci`, execute dependency lifecycle scripts, or install any package. It downloads the one
+artifact made by `validate_pack`, checks its recorded commit and SHA-256/SHA-512 digests, rechecks
+the public npm state and peeled Git tag, resolves the validated basename to a contained absolute
+artifact path, and publishes that exact tarball with `--ignore-scripts` and provenance. The
+absolute path is required because npm can parse a slash-containing relative path as a GitHub
+repository shorthand. If either the legacy `NPM_TOKEN` or one-use `NPM_BOOTSTRAP_TOKEN` repository secret exists, the ordinary release fails
+before requesting or using trusted-publisher credentials.
+
+## One-time npm namespace bootstrap
+
+An unclaimed package cannot have a trusted publisher configured. The one-time manual
+`Bootstrap npm trusted publishing` workflow claims the namespace with the non-executable
+prerelease `0.0.0-bootstrap.1`; it never publishes a stable release. The `.1` suffix preserves
+the immutable audit trail of an earlier `.0` tag whose run stopped before npm accepted any
+publication.
+
+1. Create the immutable tag `npm-bootstrap-v0.0.0-bootstrap.1` on the reviewed `main` commit.
+2. Create a short-lived npm granular access token with read/write access to **All Packages** and
+   bypass-2FA enabled. This broad initial scope is an npm limitation for an unclaimed namespace.
+   Give it the shortest practical expiry and store it only as `NPM_BOOTSTRAP_TOKEN`.
+3. Dispatch `bootstrap-npm.yml` from that exact tag. The workflow has no `id-token` permission,
+   accepts only the hard-coded package/version/dist-tag, runs `npm audit signatures` before the
+   write, publishes a two-file non-executable tarball under the `bootstrap` dist-tag, and verifies
+   the public bytes and npm registry signature without the token.
+4. Revoke the granular token immediately and delete `NPM_BOOTSTRAP_TOKEN`.
+5. Configure npm trusted publishing for GitHub owner `klimPaskov`, repository
+   `hoi4-agent-tools`, and workflow `release.yml`; explicitly select the required allowed action `npm publish`.
+   npm requires an allowed action for configurations created after May 20, 2026.
+
+The ordinary release workflow never supports token fallback. Do not create an `NPM_TOKEN`
+secret, and delete `NPM_BOOTSTRAP_TOKEN` immediately after the namespace claim; either secret's
+presence deliberately blocks the OIDC publisher.
+
+On an entirely new npm package, the registry can additionally assign the sole bootstrap version
+to `latest` even when the publish command explicitly selects `bootstrap`. The first stable release
+accepts only the exact observed recovery state: versions contains only `0.0.0-bootstrap.1`, and
+the only dist-tags are `bootstrap` and `latest`, both naming that version. Any extra version, tag,
+different prerelease, missing bootstrap tag, or malformed state stops publication. Once the first
+stable package is published, the normal strict stable-version monotonic and exact-rerun rules apply.
+
+## Required pre-tag immutability check
+
+GitHub's immutable-release settings endpoint requires repository `Administration:read`, which
+the short-lived repository `GITHUB_TOKEN` cannot request. Do not add a long-lived administration
+token to Actions for this check. Instead, the repository owner must run the authenticated check
+below immediately before pushing each stable release tag:
+
+```bash
+test "$(gh api \
+  --header 'X-GitHub-Api-Version: 2026-03-10' \
+  repos/klimPaskov/hoi4-agent-tools/immutable-releases \
+  --jq '.enabled')" = 'true'
+```
+
+This owner check is a release prerequisite and must pass before the first public writer starts.
+The workflow also requires the completed release to report `immutable: true` before MCP Registry
+publication and final verification. That post-publication gate detects a skipped prerequisite,
+but it cannot undo a mutable release; an administrator changing the setting between the owner
+check and release publication is an external GitHub settings race that the release API offers no
+conditional publish operation to close.
+
+## One-time GHCR visibility bootstrap
+
+GitHub creates the first personal-account container package as private. Run the pinned manual
+`Bootstrap GHCR` workflow from public `main`, then change package visibility to **Public** in the
+package settings. The bootstrap uses only the repository-scoped `GITHUB_TOKEN`, publishes only
+the `bootstrap` tag, and verifies the authenticated index contains exact `linux/amd64` and
+`linux/arm64` runtime manifests. GitHub exposes no supported API for changing a personal GHCR
+package's visibility, so the bootstrap cannot prove anonymous access until an administrator makes
+that newly created package public in the package settings.
+
+```bash
+gh workflow run bootstrap-ghcr.yml --repo klimPaskov/hoi4-agent-tools --ref main
+gh run watch --repo klimPaskov/hoi4-agent-tools
+```
+
+After changing visibility to **Public**, prove anonymous visibility and both runtime manifests with
+a Docker configuration that contains no credentials:
+
+```bash
+ANONYMOUS_DOCKER_CONFIG="$(mktemp -d)"
+MANIFEST="$(DOCKER_CONFIG="$ANONYMOUS_DOCKER_CONFIG" \
+  docker buildx imagetools inspect --raw \
+  ghcr.io/klimpaskov/hoi4-agent-tools:bootstrap)"
+RUNTIME_PLATFORMS="$(jq --raw-output \
+  '[.manifests[] | select(.platform.os == "linux") | "\(.platform.os)/\(.platform.architecture)"] | unique | sort | join(",")' \
+  <<<"$MANIFEST")"
+rm -rf "$ANONYMOUS_DOCKER_CONFIG"
+test "$RUNTIME_PLATFORMS" = 'linux/amd64,linux/arm64'
+```
+
+## Local release audit
+
+```bash
+npm ci --ignore-scripts
+npm audit --audit-level=high
+npm audit signatures --ignore-scripts
+npm run check
+npm run test:coverage
+npm run inspector
+REGISTRY_LIVE_VALIDATION=1 npm run registry:validate
+npm pack --dry-run --ignore-scripts --json
+```
+
+The workflow repeats `npm audit signatures` as a mandatory gate before any public writer can
+start. It verifies the package-manager inputs used by the build and later verifies the newly
+published package with `npm audit signatures --json --include-attestations`.
+
+## Enforced publication chain
+
+1. `validate_pack` verifies the remote peeled tag, `main` ancestry, canonical identity, npm
+   release order, repository/GHCR visibility, all checks, dependency signatures, and coverage. It
+   creates one tarball, `npm-pack.json`, and `release-identity.json` bound to the tarball digests
+   and source commit. This job has no OIDC permission.
+2. `publish_npm` is the minimal OIDC job. It rejects both npm bearer-token secrets, downloads and validates the
+   exact artifact, rechecks npm ordering and the remote peeled tag, resolves the tarball to a
+   contained absolute file path, then publishes only when the version is absent. It performs no
+   checkout or dependency installation.
+3. `verify_npm` has no OIDC permission. It downloads the public tarball byte-for-byte, runs the
+   official npm signature verifier, and passes the exact returned Sigstore bundle to npm's bundled
+   official Sigstore verifier with the expected Fulcio issuer and workflow certificate identity.
+   Verification requires one signed DSSE envelope, Rekor inclusion, the exact npm PURL and
+   SHA-512 subject, GitHub-hosted runner builder, release workflow/tag, and release commit. A
+   replayed bundle that differs from the current registry response is rejected.
+4. `publish_image` first checks the anonymous exact SemVer tag and GitHub release as one state
+   matrix. A completed identical rerun is accepted only when the tag digest equals the immutable
+   `container-image.json` release asset. If the tag exists but the later GitHub release does not,
+   the workflow reconstructs `container-image.json` from the exact anonymous digest and permits
+   recovery only after the normal anonymous verifier proves the index digest, two runtime
+   platforms, image source/revision/version labels, SBOM subjects, provenance subjects, source
+   tag, and source SHA against `GITHUB_SHA`. A release without its image tag, any mismatched
+   release asset, or any failed provenance check stops the chain. A first publication builds from
+   the action's default Git context, pushes by digest without a tag, rechecks the Git tag, then
+   creates the exact SemVer tag once. No mutable major/minor tag is published.
+5. `github_release` uses the authenticated, fully paginated List releases endpoint because
+   GitHub's by-tag endpoint exposes published releases but not drafts. It requires zero or one
+   exact tag match, cross-checks the published endpoint, and classifies the state as absent, a
+   mutable draft, or an already-complete immutable release. Drafts and publications must be owned
+   by the canonical GitHub Actions bot, use the exact tag-derived title and checked-in changelog
+   body, and expose no asset-label override. An existing draft may contain only a byte-for-byte
+   verified subset of the four expected uploaded assets from that same bot; unexpected,
+   duplicate, differently uploaded, non-uploaded, or differing assets stop the workflow without
+   deletion or replacement. The pinned release action stages missing assets with overwrite
+   disabled, canonicalizes the title and body, and leaves the release as a draft. Its numeric
+   release ID must match the unique authenticated listing. The workflow then requires the exact
+   npm tarball, both npm manifests, and `container-image.json`, repeats the unique-ID, metadata,
+   and byte checks, rechecks the peeled tag, and publishes that verified draft once.
+   Repository-level release immutability protects the assets and Git tag after publication. An
+   exact uploaded subset is resumable; a failed GitHub upload left in `starter` state or a draft
+   with noncanonical authorship or labels is a manual draft-cleanup blocker rather than permission
+   to overwrite or delete assets automatically. A completed rerun must match the one listed/public
+   release ID, canonical metadata, and all four immutable assets exactly.
+6. `publish_registry` validates a checksum-pinned official publisher, uses GitHub OIDC, rechecks
+   the peeled tag after login, and publishes the exact `server.json` only when absent.
+7. `verify_public` re-queries the peeled tag and verifies npm, immutable GitHub release assets,
+   anonymous GHCR digest/SBOM/provenance, and complete MCP Registry metadata. It also performs a
+   clean public install and registry-signature audit.
+
+The global non-cancelling `release` concurrency group serializes releases. npm, GitHub release,
+the exact container tag, and MCP Registry version are treated as immutable: existing matching
+objects may make a completed rerun idempotent, while absent records, moved tags, ambiguous state,
+or differing bytes/digests stop the chain. The Registry hosts metadata, not package bytes; local
+validation alone is never treated as publication evidence.

package/docs/research/mcp-2026-07-10.md

@@ -0,0 +1,46 @@
+# MCP protocol, SDK, security, and Registry review
+
+Verified 2026-07-10 against official sources.
+
+## Selected production baseline
+
+- Final protocol: [`2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25).
+- Production TypeScript SDK: [`@modelcontextprotocol/sdk` 1.29.0](https://www.npmjs.com/package/%40modelcontextprotocol/sdk?activeTab=versions), using the [`v1.x` server guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/docs/server.md).
+- Inspector: [`@modelcontextprotocol/inspector` 0.22.0](https://www.npmjs.com/package/%40modelcontextprotocol/inspector).
+- Registry schema: [`2025-12-11/server.schema.json`](https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json).
+- Registry publisher pinned by release workflow: `v1.7.9`; the workflow verifies the published checksum manifest and archive before extraction.
+
+The breaking `2026-07-28` protocol and SDK v2 split packages were release candidates on the review date. They are not used for the production package. This decision must be revisited after the final release.
+
+## Transport and capability requirements applied
+
+- Stdio uses newline-delimited UTF-8 JSON-RPC, protocol-only stdout, and stderr logging.
+- Streamable HTTP uses one `/mcp` POST/GET endpoint plus DELETE for session termination. It is stateful to support progress, cancellation, server notifications, SSE resumption, and secure random sessions.
+- Sessions are bound to authenticated principals and expire; they are never authentication credentials.
+- Tools use strict schemas and explicit read-only/destructive/idempotent/open-world annotations. Hints do not replace enforcement.
+- Long work observes `AbortSignal` and sends monotonic progress only when the client supplies a progress token.
+- Large results are content-addressed resources. Binary reads are bounded/chunkable because resource links defer retrieval but are not a byte-stream transport.
+- Prompts describe safe workflows but grant no permission.
+
+## Remote security requirements applied
+
+- Loopback is the default bind address.
+- Present origins and Host are validated; request body, concurrency, rate, session, and expiry limits are enforced.
+- Every HTTP method authenticates. Static environment bearer tokens are loopback-only.
+- Non-loopback operation requires HTTPS and OAuth/OIDC resource-server JWT verification: issuer, JWKS, audience, algorithms, expiry, subject, and required scopes.
+- Protected Resource Metadata is exposed when OAuth is configured.
+- Principal-to-workspace grants are server-side; token passthrough, query-string tokens, cross-principal sessions, and cross-workspace transactions are rejected.
+
+Primary references: [transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports), [authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), [security guidance](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices), [tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools), [resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources), [prompts](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts), [progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress), and [cancellation](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation).
+
+## Registry requirements applied
+
+- `package.json.mcpName` exactly matches `server.json.name`.
+- The public npm package version, server version, and Registry version are exact and synchronized.
+- Registry versions are immutable; release metadata is validated before publishing.
+- npm is published first because the Registry stores discovery metadata rather than package bytes.
+- The release workflow uses GitHub OIDC for `mcp-publisher` and npm provenance.
+- npm trusted publishers created after May 20, 2026 require an explicit allowed action; this package selects `npm publish`, uses a GitHub-hosted runner with `id-token: write`, and does not restore a package-manager cache in release jobs.
+- The pinned official publisher's live `validate` operation accepts this release's `server.json` before publication.
+
+References: [Registry quickstart](https://modelcontextprotocol.io/registry/quickstart), [package types](https://modelcontextprotocol.io/registry/package-types), [versioning](https://modelcontextprotocol.io/registry/versioning), and [GitHub Actions publishing](https://modelcontextprotocol.io/registry/github-actions).

package/docs/research/source-ledger.md

@@ -0,0 +1,68 @@
+# HOI4 source research ledger
+
+Reviewed 2026-07-10. These sources informed format support and tests; no installed-game or third-party-mod content is included in this repository.
+
+## Offline wiki snapshot
+
+The supplied offline Hearts of Iron IV wiki snapshot was consulted for:
+
+- `Data structures - Hearts of Iron 4 Wiki.md`: ordered blocks, variables/tokens, event targets, and generic script structure.
+- `National focus modding - Hearts of Iron 4 Wiki.md`: tree assignment, prerequisite grouping, relative positions, exclusions, continuous focuses, icons, AI, filters, and localisation.
+- `Interface modding - Hearts of Iron 4 Wiki.md`: containers, element types, scrolling, positions, orientation, and fonts.
+- `Scripted GUI modding - Hearts of Iron 4 Wiki.md`: contexts, parents, visibility, effects/triggers, dynamic lists, properties, AI, templates, and scripted localisation.
+- `Graphical asset modding - Hearts of Iron 4 Wiki.md`: sprite, frame animation, progress, and bitmap-font declarations.
+- `Map modding - Hearts of Iron 4 Wiki.md`: BMP headers/palettes, coordinates, definitions, terrain, buildings, unit positions, adjacency, and supply.
+- `State modding - Hearts of Iron 4 Wiki.md`: state/history/province/building/resource/victory-point structure and strategic-region constraints.
+- `Localisation - Hearts of Iron 4 Wiki.md`: UTF-8 BOM, language headers, key grammar, versions, escaping, and scripted localisation.
+- `Triggers`, `Effects`, and `Scopes`: ordered raw trigger/effect preservation and source-reference indexing.
+
+The wiki remains useful background, but current official files and installed examples take precedence when they differ.
+
+## Installed official documentation
+
+Under `<HOI4_ROOT>/documentation`:
+
+- `script_concept_documentation.md`: collections, contextual/formatted localisation, math expressions, and script constants.
+- `triggers_documentation.md`: current trigger names/scopes, state/province/focus/railway references, and dynamic argument support.
+- `effects_documentation.md`: current effect names/scopes and state/province/focus references. Its
+  553 documented effect identifiers form the bundled Focus Workbench native-effect catalog;
+  headings only were retained, not proprietary documentation prose.
+- `loc_objects_documentation.md` and `loc_formatter_documentation.md`: current province/state objects and font/layout-relevant localisation behavior.
+- `dynamic_variables_documentation.md`, `modifiers_documentation.md`, collection input/operator documentation: tokens and raw constructs the CST must retain.
+
+Official documentation found outside that folder was also consulted, especially:
+
+- `common/scripted_guis/_documentation.md`: authoritative current contexts, parent attachment, dynamic lists, properties, dirty variables, effects/triggers, and AI fields.
+- `common/focus_inlay_windows/documentation.md`: current inlay fields, including scripted buttons and progress bars absent from older summaries.
+
+## Vanilla precedents
+
+Representative read-only examples:
+
+- `common/national_focus/generic.txt` and large country trees for repeated prerequisite blocks, OR groups, exclusions, relative positions, raw rewards, `continuous_focus_position`, route AI, uppercase `IF`/`ELSE_IF`/`ELSE`, weighted `random_list`, direct scripted-effect calls, scoped country/state/character blocks, decision/formable links, and cosmetic-tag effects.
+- `common/continuous_focus/generic.txt` for the current `continuous_focus_palette = { ... focus = { ... } }` model, palette selection/position, and continuous-focus availability, enablement, modifier, cost, and AI fields.
+- `interface/achievements.gui`, `interface/abilitylist.gui`, scripted-GUI interface files, and paired `.gfx` files for nested containers, lists, click regions, sprite states, and ordering.
+- `common/scripted_guis/*.txt` for decision-category contexts, button effect/trigger naming, AI, dynamic lists, and parent/window connections.
+- `interface/*.gfx`, `gfx/interface/**`, and `gfx/fonts/**` for horizontal frame strips, fractional animation rates, DDS/TGA/PNG textures, vector and bitmap font sources.
+- `map/default.map`, `map/provinces.bmp`, `map/definition.csv`, `map/adjacencies.csv`, `map/supply_nodes.txt`, `map/railways.txt`, `map/buildings.txt`, `map/unitstacks.txt`, and `map/weatherpositions.txt` for current map formats.
+- `history/states/*.txt` and `map/strategicregions/*.txt` for state/region membership and ordered history payloads.
+
+## Current format conclusions
+
+- The inspected installed build was HOI4 1.19.2 content dated 2026-06-12.
+- `provinces.bmp` is a 5632×2048, uncompressed, bottom-up 24-bit BMP with a 40-byte DIB header.
+- Other current map BMPs include indexed 8-bit DIB40 and DIB124 files; the codec must honor pixel offsets, row padding, palette size, orientation, and untouched bytes.
+- Map CSV/text examples use UTF-8 without BOM and LF; localisation examples use UTF-8 BOM. The source model detects and preserves each file rather than normalizing it.
+- Active placement data is in building/unit/weather files; `positions.txt` may exist but be empty. Model-local `.asset` locator blocks are a separate source family.
+- `weatherpositions.txt` uses `small` and `big` tokens in the inspected build.
+- Sprite textures include PNG, TGA, uncompressed DDS, DXT1/3/5, DX10 RGBA/BGRA, and RXGB variants. Frame counts divide a horizontal strip; animation rates may be fractional.
+- Bitmap fonts use `.fnt` metrics/kerning and texture atlases. Locale overrides and additional script font files must remain connected in the source graph.
+- Definition rows and state IDs are contiguous in the inspected build. Province ID allocation therefore records current contiguity and must not treat arbitrary gaps as universally safe.
+- Only land provinces are required to belong to a state; sea provinces and some lakes legitimately do not. Every nonzero province is expected in one strategic region.
+- State source does not expose a generic `capital` field. Map operations distinguish a country's capital-state reference from a state's chief victory-point/capital province and never guess between them.
+- Clausewitz quoted strings decode only escaped quote and backslash. Literal newlines are invalid. Token expressions such as `variable?100` are scalar atoms; only `?=` is an operator.
+- Focus completion rewards call scripted effects directly by identifier; there is no native
+  `scripted_effect = helper_id` wrapper. `set_cosmetic_tag` targets cosmetic identity and is not a
+  formable-decision reference. Formables are decision targets, and
+  `unlock_decision_category_tooltip` targets a top-level decision category.
+- File replacement, duplicate keys, and ordering are database-specific. Same relative indexed filename shadows lower load-order sources; directly indexed files in a `replace_path` directory are removed without treating every descendant asset as removed.

package/docs/security.md

@@ -0,0 +1,139 @@
+# Security and threat model
+
+## Protected assets
+
+- external mod source and binary map data;
+- installed game and dependency references;
+- transaction approval intent and rollback blobs;
+- generated artifacts that may reveal source details;
+- HTTP credentials and principal/workspace grants.
+
+## Trust boundaries
+
+MCP input, file paths, manifest content, client annotations, session IDs, Origin/Host headers, and remote access tokens are untrusted. Tool annotations are descriptive hints. Prompts are guidance. Server-side policy is authoritative.
+
+## Filesystem controls
+
+- Only registered roots are visible.
+- Public paths are relative and canonicalized.
+- Traversal, absolute paths, UNC/device paths, NULs, alternate data streams, ambiguous trailing characters, and device names are rejected.
+- Existing symlinks and junctions are resolved; an escape outside the root is rejected.
+- Artifact shards, transaction journals, blobs, and lock descendants are re-canonicalized before access. A symlink or junction observed in artifact/journal enumeration is rejected.
+- Transaction mode requires an absolute `serverStateRoot` whose existing components are non-linked
+  and whose canonical target does not overlap any source, registration capability,
+  generated-storage root, or runtime-nominated root. Harmless native path-spelling aliases are
+  normalized only after the link check. Its random journal key and protected revision heads are
+  never returned through MCP.
+- Writes target the canonical mod root only. Game, dependency, fixture, and unrelated user files are never writable.
+- Runtime mod registration requires a separate, default-empty `writableRegistrationRoots`
+  capability. A caller cannot relabel a game/dependency path from the read-only
+  `registrationRoots` allowlist as a mod.
+- Artifact URIs are opaque and authorization-checked; filesystem paths are not placed in MCP responses.
+
+These are application checks, not a kernel-enforced filesystem sandbox. The operator must prevent
+hostile operating-system principals from concurrently replacing directories, symlinks, junctions,
+mounts, or files inside registered and generated roots between validation and I/O. Such an actor
+already has direct filesystem authority and is outside the application security boundary. The
+server detects normal stale-source changes and observed link escapes, but does not claim
+race-proof `openat`-style containment or operating-system transaction atomicity against hostile
+concurrent mutation.
+
+## Write controls
+
+Read-only is the default. A write requires global and workspace enablement, a validated dry run, a persisted transaction, exact plan hash, separate apply call, unexpired principal/workspace binding, unchanged source hashes, and a workspace lock. There is no command execution field. Stale apply and rollback operations fail closed.
+
+Runtime registration definitions and raw paths are not persisted. The canonical artifact root does
+retain an atomically created ownership claim containing only domain-separated SHA-256 workspace and
+owner bindings. Re-registration restores that binding only for the same canonical workspace and
+runtime principal; malformed, linked, raced, aliased, cross-principal, and cross-workspace claims
+fail closed. A failed journal recovery removes only the in-memory registration, never its persistent
+claim or existing generated data. Statically configured workspaces do not use runtime claims and
+remain shared according to their operator-reviewed principal grants.
+
+Every artifact provenance manifest includes the resolved workspace identity and its configured or
+runtime owner identity in the immutable provenance hash. List, describe, and resource-read paths
+verify both values before returning metadata or bytes. Reusing a physical artifact store through a
+different workspace or owner therefore cannot expose prior evidence; unbound legacy or malformed
+manifests are rejected rather than migrated or deleted implicitly.
+
+Transaction manifests are authenticated with HMAC-SHA-256 over the complete canonical manifest,
+excluding only the authentication tag. The 256-bit random key lives beneath `serverStateRoot`, not
+in a workspace or public configuration value. Protected revision heads prevent replay of an older
+valid manifest. A cache-first crash may reconcile only an authenticated exact next revision; a
+missing head, revision gap, altered expiry/state/failure/rollback field, or recomputed public hash
+fails closed. No HMAC key is derived from public workspace data.
+
+Read-only transaction operations never repair protected state. Cache-first successor promotion is
+confined to startup recovery and authorized write paths. Artifact manifests are capped at 1 MiB and
+transaction manifests at 16 MiB before parsing; transaction resource ranges use a bounded verified
+byte cache instead of repeatedly rebuilding the authenticated object.
+
+## HTTP controls
+
+- Every POST, GET, and DELETE request to `/mcp` is authenticated; only standards-required OAuth discovery metadata is public.
+- Present Origin and Host are checked before MCP dispatch. Security-sensitive singleton fields are counted from the raw HTTP header list before Node normalization, so duplicate Host, Authorization, Origin, content metadata, forwarding identity, or MCP session/protocol fields fail closed. Absolute-form request targets must use an allowlisted authority identical to Host.
+- Session IDs are secure random routing identifiers bound to the authenticated principal, an explicit OAuth client when present, the exact bearer credential's SHA-256 identifier, and the non-downgraded scope set; they are not credentials. A token without `client_id` or `azp` is credential-bound rather than being aliased to the subject.
+- Missing, expired, cross-principal, or unknown sessions fail.
+- Connection count, requests per socket, header/request/keep-alive time, JSON body size, admitted concurrency, request rate, session count, event streams, event history, and session lifetime are bounded.
+- Admitted request concurrency is fixed at no more than two; configured body bytes multiplied by
+  concurrency cannot exceed 16 MiB.
+- Static bearer tokens are loopback-only. A non-loopback listener or a non-loopback canonical `publicUrl` (including a loopback listener behind a public reverse proxy) requires HTTPS and OAuth/OIDC JWT signature, issuer, audience, algorithm, expiry, subject, and scope verification.
+- Tokens are accepted only in the Authorization header and are never logged, forwarded, copied into a session, or exposed to MCP handlers. Only a one-way SHA-256 credential identifier is retained for session binding.
+- Protected Resource Metadata is published for OAuth deployments and linked from OAuth `WWW-Authenticate` challenges.
+- Initial 401 challenges identify the baseline scope. A write-scoped tool call made with a read token receives an HTTP 403 `insufficient_scope` challenge naming the baseline plus `hoi4:write`, before JSON-RPC dispatch.
+- Streamable HTTP reserves concurrency before JSON parsing or token verification and applies a socket-address rate bucket before authentication, followed by an independent per-principal bucket after authentication. Host and any present Origin are rejected even earlier. Every `/mcp` POST must advertise unparameterized, positively weighted `application/json` and `text/event-stream` response media types, use the exact `application/json` request media type with an absent or `utf-8` charset, and use no content coding other than identity. GET requires an unparameterized, positively weighted `text/event-stream` range. Bodies are fatal-decoded as UTF-8 and parsed under the raw-wire `maxBodyBytes` ceiling; suffix types, malformed or ambiguous media parameters, encoded entities, replacement-decoded UTF-8, and parameter-only media-type mentions are rejected before SDK dispatch.
+- `trustedProxyAddresses` contains exact IP addresses only and affects only derivation of the pre-auth rate-limit key; it does not enable general forwarded-header trust. `X-Forwarded-For` is ignored unless the direct socket peer exactly matches a configured address (IPv4-mapped IPv6 is normalized). For a trusted peer, a missing or invalid header is rejected and only the first comma-separated address is used.
+- A reverse proxy must be the only network path to a proxied server, terminate TLS, overwrite client-supplied forwarding headers with a validated client IP, preserve Authorization/Origin/Host, and enforce edge connection, header, body, timeout, and rate limits. CIDR ranges, hostnames, and an unverified proxy chain are not inferred by the application.
+- Every session request is reauthenticated and must present the exact credential that initialized the session; another token cannot take over merely because its subject or client claims match. OAuth refresh and scope step-up therefore initialize a new MCP session. Scope authority within a session remains monotonic, and handler-level write-scope checks remain in place as defense in depth.
+
+Session admission counts both active sessions and initializations in progress, globally and per
+principal. Static-token sessions use the configured sliding inactivity lifetime. OAuth session
+expiry is the earlier of that lifetime and the access token's `exp`; an expired token cannot create
+a session. Expiration timers remove sessions at that bound, with access checks, pre-admission
+pruning, and periodic cleanup as fail-closed backstops.
+Resumable GET streams have separate global/per-principal ceilings; once accepted, a long-lived
+stream releases the ordinary short-request concurrency reservation and remains charged to the
+stream ceilings.
+
+Replay history is also bounded: at most 1,000 events per session, the configured per-session byte
+budget, the configured process-wide event-store byte budget, and the session TTL. Per-session
+overflow evicts the oldest history first. If one event cannot fit the per-session or shared byte
+budget, it is not retained for replay; the store does not evict another session's history to make
+room. Closing or expiring a session releases its shared budget.
+
+## Stdio controls
+
+Stdio accepts newline-delimited JSON-RPC frames of at most 16,777,216 bytes, excluding the line-feed
+delimiter. The ceiling is fixed and matches the largest configurable Streamable HTTP JSON body.
+Input is retained in a geometrically grown bounded byte buffer, keeping cumulative copy work
+linear without per-chunk metadata growth. Completed frames use fatal UTF-8 decoding; malformed byte
+sequences are never replaced with U+FFFD or dispatched as JSON-RPC. A malformed UTF-8 frame or a
+frame that crosses the ceiling is refused immediately (for size, including when no newline or
+end-of-input has arrived): the server writes a structured `STDIO_INVALID_UTF8` or
+`STDIO_FRAME_TOO_LARGE` event to stderr, closes that transport, and exits unsuccessfully. The
+rejected payload is never echoed. Protocol responses remain exclusively on stdout; transport and
+startup diagnostics remain exclusively on stderr.
+
+Well-formed UTF-8 frames that fail JSON or JSON-RPC schema validation are not dispatched. Their
+stderr diagnostic has the fixed `STDIO_INVALID_MESSAGE` code and a generic message; it never
+interpolates caller-controlled frame content. A later valid frame may continue on the local
+connection.
+
+## Source and artifact privacy
+
+Stdio inherits the local process user's access but still applies the configured roots. A remote deployment can access only paths mounted and registered on the server; it cannot reach a client computer. Do not mount a home directory or an entire game library when one read-only game root and selected workspaces suffice.
+
+On POSIX, the server enforces mode `0700` on the state root and `0600` on the journal key. Node does
+not provide a portable Windows DACL authoring API, so Windows operators must provision the state
+root ACL for the dedicated server account; the server still rejects a linked/non-regular key and
+inherits that operator ACL. A hostile operating-system principal that can read the key or replace
+state-root entries remains outside the documented filesystem trust boundary.
+
+Raw installed-game or dependency sprite, font, and bitmap files are never registered as downloadable resources. Structured JSON evidence strips embedded raster and glyph payloads, retaining only source-linked hashes, paths, frame and dimension metadata. Composite SVG/PNG reviews may contain processed frames or glyphs required to inspect the requested render, but remain generated, authorization-checked workspace evidence rather than raw asset-file resources. Transaction evidence may contain authorized mod-source before/proposed text and diffs; every artifact remains bound to the workspace principal.
+
+The runtime sends no telemetry or analytics. Its only outbound network request is OAuth JWT-key retrieval from the administrator-configured JWKS endpoint; stdio and static-token loopback deployments require no runtime network access.
+
+The product never launches, automates, controls, or captures Hearts of Iron IV. Every preview is
+an offline tool-generated render, not a game screenshot or evidence of in-engine behavior.
+
+Vulnerabilities should be reported through GitHub private vulnerability reporting as described in the root [security policy](../SECURITY.md).

package/docs/self-hosting.md

@@ -0,0 +1,168 @@
+# Self-hosting Streamable HTTP
+
+The server exposes one stateful MCP endpoint at `/mcp` for POST and GET, plus DELETE session termination. It does not provide legacy SSE-only transport.
+
+## Loopback
+
+Set a random token of at least 32 characters in the environment named by config:
+
+```bash
+export HOI4_AGENT_HTTP_TOKEN='replace-with-a-random-secret'
+HOI4_AGENT_CONFIG=/srv/hoi4/config.json hoi4-agent-tools-http
+```
+
+Keep `host` as `127.0.0.1`. The client sends `Authorization: Bearer ...`. Present origins still need to match `allowedOrigins`.
+
+The HTTP process refuses to start if a configured token environment variable is missing, shorter
+than 32 characters, or has the same secret value as another configured token. Static tokens and
+OAuth are mutually exclusive deployment modes.
+
+## Public/team deployment
+
+Public mode—either a non-loopback listener or a non-loopback `publicUrl` in front of a loopback/private listener—refuses to start unless:
+
+- `publicUrl` is an HTTPS origin or exact `/mcp` endpoint and contains no credentials, path prefix, query, or fragment;
+- OAuth/OIDC JWT validation is configured;
+- the OAuth issuer, JWKS, and every authorization-server URL use HTTPS;
+- at least one origin is allowlisted;
+- principal/workspace grants are configured.
+
+```json
+{
+  "http": {
+    "host": "0.0.0.0",
+    "port": 3210,
+    "publicUrl": "https://mcp.example.test",
+    "allowedOrigins": ["https://agent.example.test"],
+    "trustedProxyAddresses": ["10.20.0.5"],
+    "tokens": [],
+    "principals": [
+      { "principal": "user-subject", "workspaceIds": ["example"], "allowRegistration": false }
+    ],
+    "oauth": {
+      "issuer": "https://issuer.example.test/",
+      "jwksUri": "https://issuer.example.test/.well-known/jwks.json",
+      "audience": "https://mcp.example.test/mcp",
+      "authorizationServers": ["https://issuer.example.test/"],
+      "requiredScopes": ["hoi4:read"],
+      "algorithms": ["RS256"]
+    }
+  }
+}
+```
+
+The server is an OAuth resource server, not an authorization server. Protected Resource Metadata is served at the standard well-known paths and its endpoint-specific URL is included in 401 and insufficient-scope 403 challenges. Baseline access uses the configured `requiredScopes`; transaction planning, registration, apply, and rollback additionally require `hoi4:write`. Each MCP session is bound to the exact bearer credential that initialized it, not only to mutable subject/client claims. A refreshed or step-up token must initialize a new MCP session; the previous session remains bound to its original credential and expires no later than that credential's `exp`. The server retains only a SHA-256 credential identifier, never the raw token. Static-token sessions keep the configured sliding inactivity lifetime. Terminate TLS at a trusted reverse proxy, preserve Authorization/Origin/Host headers, and do not make a session ID a bearer credential.
+
+### Reverse-proxy boundary
+
+`trustedProxyAddresses` is not a general proxy switch; it affects only the pre-auth rate-limit
+address and does not trust forwarded host or protocol metadata. Each entry is one exact IPv4 or
+IPv6 address as it appears for the direct socket peer; CIDR ranges and hostnames are rejected. An
+IPv4-mapped IPv6 peer is normalized to IPv4 for matching. When the peer is not an exact match, the
+application ignores `X-Forwarded-For` and rate-limits the socket address. When it is a match, the
+application requires a valid `X-Forwarded-For` value and uses its first comma-separated IP.
+
+The edge proxy must therefore:
+
+- be the only network path to the server port, enforced by a private bind/network and firewall;
+- terminate TLS for the HTTPS `publicUrl`;
+- remove any client-supplied forwarding chain and set the first `X-Forwarded-For` value to a
+  validated originating client IP;
+- preserve the bearer `Authorization` header, the original `Origin`, and a `Host` accepted by the
+  configured bind host or `publicUrl`;
+- enforce its own connection, header-size, body-size, header/request/idle timeout, and pre-auth
+  rate ceilings before forwarding.
+
+Do not configure a load-balancer subnet and expect range matching, and do not allow clients to
+bypass the named proxy. For multiple proxy hops, use an edge-controlled normalization point that
+delivers one trustworthy first address to the directly connected trusted peer.
+
+### Admission, sessions, and streams
+
+Before authentication, the application enforces Node connection/request timeouts and socket
+ceilings, then reserves one `maxConcurrentRequests` slot and applies a fixed-minute
+`requestsPerMinute` bucket to the resolved client address. Every POST must advertise exact,
+unparameterized positive-quality `application/json` and `text/event-stream` response ranges, use exact
+`application/json` request media with an absent or `utf-8` charset, and use identity content
+encoding. GET must advertise exact positive-quality `text/event-stream`. JSON is fatal-decoded as
+UTF-8 and parsed under the raw-wire `maxBodyBytes` ceiling before SDK dispatch. Suffix types,
+duplicate/malformed parameters, encoded entities, invalid UTF-8, and parameter-only media mentions
+are rejected.
+
+Before those checks, the server counts security-sensitive fields in the raw header list rather
+than trusting Node's first-value normalization. Duplicate Host, Authorization, Origin,
+Content-Type, Content-Encoding, forwarding identity, or MCP session/protocol fields are rejected.
+For an absolute-form request target, its allowlisted authority must exactly match Host; an allowed
+Host cannot conceal an untrusted request-target authority.
+After authentication, a separate fixed-minute bucket is applied to the principal. Host and any
+present Origin are checked before admission. These in-process controls complement, rather than
+replace, the edge limits above.
+
+`maxConcurrentRequests` cannot exceed two, and its product with `maxBodyBytes` cannot exceed
+16 MiB. The fixed concurrency ceiling also bounds simultaneous offline render allocations; raise
+edge capacity by running isolated server instances, not by removing the per-process safety bound.
+
+Session initialization is refused when either the global `maxSessions` or
+`maxSessionsPerPrincipal` count (including initializations in progress) is full. Resumable GET
+streams use `maxEventStreams` and `maxEventStreamsPerPrincipal`; an accepted long-lived stream
+releases the ordinary request-concurrency slot. Each session retains at most 1,000 replay events,
+`maxSessionEventBytes`, and the shared `maxEventStoreBytes`, for no longer than
+`sessionTtlSeconds`. Old per-session history is evicted first. A new event that cannot fit the
+shared budget is not retained for replay and does not evict another session's history.
+
+Principal grants isolate tool, resource, session, and transaction access within one deployment. Run separate least-privilege server instances or containers for mutually distrustful teams or operating-system trust domains; do not treat application-level grants as an OS sandbox.
+
+Runtime registration has two operator capabilities. `registrationRoots` permits read-only source
+selection. A caller-declared mod root additionally must be under the default-empty
+`writableRegistrationRoots` list, even when source apply is disabled, because mod registration
+creates generated storage. Never place a game or dependency directory under a writable
+registration root. Granting `allowRegistration` exposes every otherwise-unclaimed source beneath
+these capability roots to that principal; prefer static registrations or separate instances for
+mutually distrustful users.
+
+Runtime artifact storage must support same-volume hard links so the server can create persistent
+owner claims without replacement races. Transaction deployments additionally require an isolated,
+persistent `serverStateRoot` on a filesystem with hard-link and atomic-replacement support. Do not
+place it beneath any source, capability, artifact, cache, fixture, or `storageRoots` directory.
+
+## Container
+
+```bash
+docker build -t hoi4-agent-tools:0.1.2 .
+docker run --read-only --rm -p 127.0.0.1:3210:3210 \
+  -e HOI4_AGENT_CONFIG=/config/config.json \
+  -v /srv/hoi4/config:/config:ro \
+  -v /srv/hoi4/game:/srv/hoi4/game:ro \
+  -v /srv/hoi4/workspaces:/srv/hoi4/workspaces \
+  -v /var/lib/hoi4-agent-tools:/var/lib/hoi4-agent-tools \
+  -v /var/lib/hoi4-agent-tools-state:/var/lib/hoi4-agent-tools-state \
+  hoi4-agent-tools:0.1.2
+```
+
+Port publishing reaches the container through a non-loopback interface. The mounted configuration
+for this form must therefore use the public/team OAuth policy above: bind `0.0.0.0`, declare the
+canonical HTTPS `publicUrl`, allowlist the coding-agent origin, and validate OAuth access tokens.
+Terminate TLS at the configured reverse proxy. Mapping the host port only to `127.0.0.1` limits host
+exposure but does not turn the container-side listener into loopback, so it does not permit static
+bearer tokens.
+
+When writes are enabled, set `serverStateRoot` to `/var/lib/hoi4-agent-tools-state` in this example.
+Keep that mount persistent across restarts and protect it for the dedicated server account. It is a
+separate mount because a state root may not overlap `/var/lib/hoi4-agent-tools` when that path is a
+configured generated-storage capability.
+
+On Linux, a local-only static-token deployment may instead use `--network host` with the configured
+listener kept at `127.0.0.1`; do not combine that mode with `-p`. Host networking changes the
+container isolation boundary and is not portable to every Docker host, so review it explicitly
+before use.
+
+Do not mount a developer's home directory. A remote server sees only server-side mounts; the MCP client does not tunnel local files.
+
+If a configured workspace has `kind: "game"` or `kind: "dependency"`, mount a separate writable
+operator-owned generated-data directory, list its parent in `storageRoots`, and set both
+`artifactRoot` and `cacheRoot` beneath it. Never make the installed-game or dependency source
+mount writable merely to hold generated state. Mod workspaces may instead use their confined
+`<mod>/.hoi4-agent/artifacts` and `<mod>/.hoi4-agent/cache` defaults.
+
+The server does not launch or capture Hearts of Iron IV. A self-hosted deployment needs filesystem
+access only; it does not need a desktop session, Steam automation, or game-process permissions.