Harden terms oracle: hash-aware sync, anti-downgrade, Content-SHA256 binding (#6)

PlasticDigits commented

2026-08-11 01:09:24 +00:00

(Migrated from gitlab.com)

Summary

Hash-aware terms sync: compare content_sha256 + Version: label; same label with mutated body is rejected (operators must bump Version: — no silent drift / no auto-suffix).
Anti-downgrade: refuse to re-mark a previously published label as is_latest unless FORCE_TERMS_DOWNGRADE=true (logged; reactivates existing row only when remote hash matches stored bytes).
Canonical message binds document hash: Rust + SDK + portal emit Content-SHA256: <hex> (breaking format — deploy API + SDK + web together and bump terms Version: so clients re-sign).
Docs/skills updated (skills/security-ops/SKILL.md, README, .env.example); removed orphan api/src/terms_sync.rs.

Closes #6.

Deploy order (breaking)

Ship API + @plasticdigits/cl8y-clickwrap + portal together.
Bump TERMS_AND_CONDITIONS.txt Version: so everyone re-signs the new message format.
Do not enable FORCE_TERMS_DOWNGRADE in production.

Test plan

cd api && cargo test (unit + integration, including integration_terms_oracle_sync_policy)
npm run test:sdk (message golden includes Content-SHA256)
npm run build:sdk && npm run test:web
Grep: Rust + TS builders emit Content-SHA256
Manual: publish Draft N, mutate body without version bump → sync errors; rollback label without force → rejected
Coordinated prod deploy + terms version bump after merge

Acceptance criteria (issue #6)

Same Version: + same body → Unchanged
Same Version: + different body → hard error requiring label bump (documented)
Downgrade/rollback rejected without force flag
Acceptance message includes content_sha256 hex
SDK golden + Rust unit tests cover new line
Telegram server-built message includes hash line
/update_terms Bearer + rate-limit behavior unchanged
Docs/skill mention oracle invariants

## Summary - **Hash-aware terms sync:** compare `content_sha256` + `Version:` label; same label with mutated body is **rejected** (operators must bump `Version:` — no silent drift / no auto-suffix). - **Anti-downgrade:** refuse to re-mark a previously published label as `is_latest` unless `FORCE_TERMS_DOWNGRADE=true` (logged; reactivates existing row only when remote hash matches stored bytes). - **Canonical message binds document hash:** Rust + SDK + portal emit `Content-SHA256: <hex>` (breaking format — deploy API + SDK + web together and bump terms `Version:` so clients re-sign). - Docs/skills updated (`skills/security-ops/SKILL.md`, README, `.env.example`); removed orphan `api/src/terms_sync.rs`. Closes #6. ### Deploy order (breaking) 1. Ship API + `@plasticdigits/cl8y-clickwrap` + portal together. 2. Bump `TERMS_AND_CONDITIONS.txt` `Version:` so everyone re-signs the new message format. 3. Do **not** enable `FORCE_TERMS_DOWNGRADE` in production. ## Test plan - [x] `cd api && cargo test` (unit + integration, including `integration_terms_oracle_sync_policy`) - [x] `npm run test:sdk` (message golden includes `Content-SHA256`) - [x] `npm run build:sdk && npm run test:web` - [x] Grep: Rust + TS builders emit `Content-SHA256` - [ ] Manual: publish Draft N, mutate body without version bump → sync errors; rollback label without force → rejected - [ ] Coordinated prod deploy + terms version bump after merge ## Acceptance criteria (issue #6) - [x] Same `Version:` + same body → `Unchanged` - [x] Same `Version:` + different body → hard error requiring label bump (documented) - [x] Downgrade/rollback rejected without force flag - [x] Acceptance message includes `content_sha256` hex - [x] SDK golden + Rust unit tests cover new line - [x] Telegram server-built message includes hash line - [x] `/update_terms` Bearer + rate-limit behavior unchanged - [x] Docs/skill mention oracle invariants

PlasticDigits commented

2026-08-11 01:09:33 +00:00

(Migrated from gitlab.com)

mentioned in issue #6