Make snapshot inventory provenance explicit and deny false live readiness

This commit is contained in:
devops committed 2026-10-23 13:21:41 +00:00
1 parent 01f56c6db7
commit d6db634a35
16 files changed
+443 -35

No files matched your search

+2
View File
@@ -1,3 +1,5 @@
**Superseded wiring/provenance: see [snapshot repair](hermes-snapshot-provenance.md). Do not use literal grants or the old DNS alias below.**
# Runtime read vertical slice (not deployed)
Branch feature/v4-runtime-completion, base 5507fbc. No AppModule, live gateway,
+86
View File
@@ -0,0 +1,86 @@
# 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:
```ts
RuntimeReadModule.registerFromFile('/run/secrets/hermes_runtime_grants')
```
Nest supports the resulting Promise<DynamicModule> 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`:
```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.