87 lines
5.0 KiB
Markdown
87 lines
5.0 KiB
Markdown
# 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.
|