Files
canina/docs/hermes-snapshot-provenance.md

5.0 KiB

Snapshot provenance repair — integration contract

This is independent snapshot inventory, not a live Hermes executor. No Production, deployment, live gateway edits, or RELEASE_AUTHORIZE execution is included.

Parent-owned application wiring

Keep AuthModule/JwtStrategy. Replace literal user grants in parent-owned app.module.ts with:

RuntimeReadModule.registerFromFile('/run/secrets/hermes_runtime_grants')

Nest supports the resulting Promise in imports. Alternatively pass the reviewed nonsecret file /etc/canina/runtime-grants.json. No env/JWT/browser grant input is accepted by this registration. File is JSON object mapping exact verified DB user IDs to nonempty unique profile arrays; {} explicitly denies everyone. Missing, malformed, symlinked, group/world-writable, oversized files fail startup closed. Mount read-only and provision via reviewed configuration/secrets management; do not commit real user grants. Existing explicit register(grants) remains for tests/legacy consumers. Backend also mounts /run/secrets/hermes_username and hermes_password read-only. No app.module.ts modification belongs to this commit.

Required coordinated origin change

Authenticated management module and broker now exclusively use http://canina-hermes-inventory:9119. compose.readonly.yml uses the distinct alias canina-hermes-inventory, NEVER canina-hermes. Generic adapter allowlist retains both reviewed exact origins for compatibility with separate existing consumers. No arbitrary origin/env URL accepted. Parent must cherry-pick broker/module/adapter and inventory compose together; do not add an alias to the existing gateway. No deployment performed. External network should still be internal and only contain backend/inventory; the distinct alias cannot shadow the live canina-hermes hostname.

Snapshot exporter/operator gate

Every independent inventory root must include snapshot-manifest.json:

{"schemaVersion":1,"source":"snapshot","capturedAt":"2026-10-23T12:00:00Z"}

The example is a schema example, NOT an actual capture attestation. Exporter must write the real capture instant from the approved consistent export. Never copy the example, use startup time, filesystem mtime, or claim this change captures/refreshes snapshots. Missing/invalid/future manifest prevents startup. It is revalidated per successful GET; invalid after startup returns503. Manifest is exporter metadata, not a cryptographic proof of consistency. Immutable reviewed export provisioning remains required. Fresh means age <=3600 seconds, otherwise stale; even fresh is NOT live readiness. No snapshot scheduler installed.

Additive public response fields / panel handoff

All object read DTOs (health/status/usage/sessions/model-info) add: provenance:{source:'snapshot',capturedAt:string,ageSeconds:number,freshness:'fresh'|'stale',liveProcess:'unknown'}. Profile and schedule array shapes are preserved: provenance is on each row. Empty arrays have no rows to annotate; use the health response to display snapshot metadata. Profile rows add liveGatewayState:'unknown'; status adds the same plus liveActiveAgents:null. Existing required scalars remain typed but are conservative placeholders: gateway_running:false, active_agents:0, gateway_state:null, overall:'unknown'. False/zero MUST NOT render as measured offline/idle: when provenance.source is snapshot use the explicit unknown fields, label snapshot and show capturedAt/freshness. Health.ok only means inventory HTTP app responsiveness, never live gateway readiness. Profile existence is inventory availability, NOT process readiness. Adapter enforces provenance on dedicated snapshot origin and conservatively overwrites copied PID-derived status/profile scalars again.

Installed status handler was unsafe here: it probes gateway HTTP/PIDs/platforms and can stall despite this being an independent snapshot. Snapshot server replaces that route with measured package version and explicit unknown process fields; no status probe is run. Password auth/mutation denial/WebSocket denial remain intact.

Executed acceptance

Remote disposable network-none exact pinned Hermes image, no original volumes: manifest-missing regression failed first; TCP login/profile/health/status provenance and stale capture assertions now pass; authenticated sockets denied1008. Disposable Node22 copy of source/dependencies: 9 hermes-management suites /34 tests pass and full backend tsc build passes. Adapter copied-live-state regression failed first; grants-loader missing-function regression failed first. Compiled actual Node broker -> TCP pinned server -> adapter -> policy-filtered profiles/status passes, deny reads zero credentials. Test timestamps/credentials are fixtures, not live telemetry. The first HTTP retry raced fixture startup and returned UNAVAILABLE; retry after server startup passed. No claim of full app/user-flow or live runtime integration.

Full non-DB Jest regression: 108 suites/854 tests passed; 1 suite/18 tests skipped. No RELEASE_AUTHORIZE suite was enabled.