admin/_docs/02_document/ripple_log_cycle1.md

Ripple Log — Cycle 1 (2026-05-13)

Documentation refresh triggered by the cycle 1 task set: AZ-513, AZ-196, AZ-183, AZ-197.

Post-cycle-1 update (same day, 2026-05-13) — after the security audit (autodev Step 14) AZ-183 (OTA update check & publish) was reverted in full and a F-3 hardening pass was applied to RegisterUser/RegisterDevice. See "Post-cycle-1 revert (security audit follow-up)" at the bottom of this log for the doc deltas.

This log records every doc that was refreshed (directly or via the import-graph ripple from another changed file) during autodev Step 13 (Update Docs) — document skill in Task mode.

Method

Per .cursor/skills/document/workflows/task.md Step 0.5, for each changed source file the consuming files were located via using references inside Azaion.AdminApi/, Azaion.Services/, Azaion.Common/, Azaion.Test/, and e2e/Azaion.E2E/. Each consumer that lives in an already-documented module triggered a doc refresh.

For C#, the import surface walked was using Azaion.{Common,Services}*; plus ProjectReference declarations in the four production csprojs (Azaion.AdminApi, Azaion.Services, Azaion.Common, Azaion.Test, e2e/Azaion.E2E).

Direct refreshes (changed source file → existing module doc)

Module Doc	Trigger
modules/services_user_service.md	Azaion.Services/UserService.cs — AZ-196 added RegisterDevice; AZ-197 removed UpdateHardware, CheckHardwareHash, UpdateLastLoginDate.
modules/services_security.md	Azaion.Services/Security.cs — AZ-197 removed GetHWHash; GetApiEncryptionKey signature simplified.
modules/services_resources_service.md	Azaion.Services/ResourcesService.cs — caller-side hardware path gone (security note rewrite).
modules/common_requests_get_resource.md	Azaion.Common/Requests/GetResourceRequest.cs — AZ-197 removed Hardware field; CheckResourceRequest removed.
modules/common_business_exception.md	Azaion.Common/BusinessException.cs — AZ-197 removed HardwareIdMismatch (40) and BadHardware (45).
modules/admin_api_program.md	Azaion.AdminApi/Program.cs — AZ-513 added /classes CRUD; AZ-196 added /devices; AZ-183 added /get-update + /resources/publish; AZ-197 removed /users/hardware/set and /resources/check.
modules/common_requests_set_hw.md	Deleted — Azaion.Common/Requests/SetHWRequest.cs no longer exists.

New module docs (added cycle 1)

Module Doc	New Source File
modules/common_entities_detection_class.md	Azaion.Common/Entities/DetectionClass.cs (AZ-513)
modules/common_entities_resource.md	Azaion.Common/Entities/Resource.cs (AZ-183)
modules/common_requests_create_detection_class.md	Azaion.Common/Requests/CreateDetectionClassRequest.cs (AZ-513)
modules/common_requests_update_detection_class.md	Azaion.Common/Requests/UpdateDetectionClassRequest.cs (AZ-513)
modules/services_detection_class_service.md	Azaion.Services/DetectionClassService.cs (AZ-513)
modules/services_resource_update_service.md	Azaion.Services/ResourceUpdateService.cs (AZ-183)
modules/common_requests_get_update.md	Azaion.Common/Requests/GetUpdateRequest.cs (AZ-183 — also defines ResourceUpdateItem)
modules/common_requests_publish_resource.md	Azaion.Common/Requests/PublishResourceRequest.cs (AZ-183)
modules/common_requests_register_device_response.md	Azaion.Common/Requests/RegisterDeviceResponse.cs (AZ-196)

Component-level refreshes (parents of refreshed modules)

Component Doc	Reason
components/01_data_layer/description.md	New entities (DetectionClass, Resource); new cache key Resources.Latest.{arch}.{stage}; storage estimates updated; User.Hardware marked tombstoned.
components/02_user_management/description.md	RegisterDevice added to interface table; CheckHardwareHash / UpdateHardware removed from interface table; SetHWRequest removed; cache invalidation table simplified.
components/03_auth_and_security/description.md	Security.GetApiEncryptionKey signature simplified; GetHWHash removed.
components/04_resource_management/description.md	IResourceUpdateService added (AZ-183) with separate DB + cache + at-rest column encryption; GetResourceRequest no longer carries Hardware; CheckResourceRequest removed.
components/05_admin_api/description.md	New endpoints (POST /classes, PATCH /classes/{id}, DELETE /classes/{id}, POST /devices, POST /get-update, POST /resources/publish); removed endpoints (PUT /users/hardware/set, POST /resources/check); apiUploaderPolicy is now in use.

System-level refreshes

System Doc	Reason
system-flows.md	F4 (Hardware Check) marked REMOVED; F3 sequence diagram regenerated without hardware step; F8 (Detection Classes CRUD), F9 (Device Auto-Provisioning), F10 (OTA Update Check & Publish) added with full sequence diagrams + error tables.
architecture.md	Data Model Overview lists the new DetectionClass and Resource entities; the User entity caption notes the CompanionPC subset auto-provisioned via AZ-196; ExceptionEnum caption notes HW-related codes are gone. The Note (AZ-197) block at the top was already in place pre-Step-13.
module-layout.md	Conceptual Sub-Components table updated: cycle-1-added files annotated; SetHWRequest removal noted; new sub-component 4b Detection Classes added.
diagrams/flows/flow_hardware_check.md	Already converted to a tombstone during AZ-197 implementation; no further action this cycle.

Tooling notes

• C# import resolution was performed by Grep on using Azaion.* patterns plus by reading the .csproj ProjectReference set, since the workspace has no madge/depcruise-equivalent statically available. Any consumer in Azaion.AdminApi/Program.cs was treated as a "system entry point" consumer (Program.cs is the composition root + endpoint table — a single file that legitimately consumes everything).
• Tests under Azaion.Test/ and e2e/Azaion.E2E/ were considered downstream consumers of Azaion.Services and Azaion.Common. Their files were NOT promoted into the doc tree (per module-layout.md Layout Rules — tests are not public API surface), but their AC coverage was reflected in module-doc "Tests" sections and in tests/blackbox-tests.md / tests/traceability-matrix.md (autodev Step 12).

No-op observations

• Other module docs in _docs/02_document/modules/ (e.g., common_entities_user.md, common_database_*.md, common_extensions_*.md, services_auth_service.md, services_cache.md, admin_api_business_exception_handler.md, common_requests_login_request.md, common_requests_register_user.md, common_requests_set_queue_offsets.md, common_configs_*.md) were inspected and found to be unaffected by cycle 1 changes — no refresh needed.
• _docs/00_problem/acceptance_criteria.md and _docs/00_problem/restrictions.md were intentionally NOT modified — Task-mode Step 4 only updates problem-level docs when the task changed input parameters or the AC catalogue. Cycle 1 added new behaviours but the baseline AC numbering (AC-1..AC-28) is preserved per cycle-update rules; new AC sets live under their tracker IDs in tests/traceability-matrix.md.

---

Post-cycle-1 revert (security audit follow-up, 2026-05-13)

After autodev Step 14 (Security Audit) finished with verdict FAIL (3 open Highs: F-1, F-2, F-3), the user instructed:

"fix findings right now F-1 get-update is again leftover from the shipping resources era, when we delivered software as an installer. We don't need now IResourceUpdateService. F-3 (AMPLIFIED, AZ-196) — duplicate-email race now reachable on /devices because users.email has no UNIQUE index. first of all, reuse the code in the implementation RegisterDevice -> should call RegisterUser then add index to email"

Code changes

File	Action	Reason
Azaion.Services/ResourceUpdateService.cs	Deleted	F-1 — entire OTA feature reverted
Azaion.Common/Requests/GetUpdateRequest.cs	Deleted	F-1 — request DTO unused after endpoint deletion
Azaion.Common/Requests/PublishResourceRequest.cs	Deleted	F-1 — request DTO unused after endpoint deletion
Azaion.Common/Entities/Resource.cs	Deleted	F-1 — entity unused after service deletion
env/db/05_resources.sql	Deleted	F-1 — resources table no longer needed
e2e/Azaion.E2E/Tests/ResourceUpdateTests.cs	Deleted	F-1 — covers deleted endpoints
Azaion.AdminApi/Program.cs	Edited	F-1 — removed /get-update, /resources/publish, IResourceUpdateService DI registration, apiUploaderPolicy
Azaion.Common/Database/AzaionDb.cs	Edited	F-1 — removed ITable<Resource>
Azaion.Common/Database/AzaionDbShemaHolder.cs	Edited	F-1 — removed Resource entity mapping
Azaion.Common/Configs/ResourcesConfig.cs	Edited	F-1 — removed EncryptionMasterKey field (also closes F-5)
Azaion.AdminApi/appsettings.json	Edited	F-1 — removed EncryptionMasterKey config value
docker-compose.test.yml	Edited	F-1 — removed ResourcesConfig__EncryptionMasterKey env var
env/db/06_users_email_unique.sql	Created	F-3 — CREATE UNIQUE INDEX users_email_uidx ON public.users (email);
e2e/db-init/00_run_all.sh	Edited	drop 05_resources.sql line; add 06_users_email_unique.sql line
Azaion.Services/UserService.cs	Edited	F-3 — RegisterUser drops check-then-insert, catches Npgsql.PostgresException(SqlState=23505) → EmailExists; RegisterDevice now delegates the row insert to RegisterUser (per user direction)

Doc deltas

Doc	What changed
system-flows.md	F10 row in flow inventory marked REMOVED; F9 dependency note updated; full F10 section replaced with a tombstone explaining the revert
architecture.md	Resource entity removed from data model table; User row notes UNIQUE INDEX on email and the RegisterDevice → RegisterUser consolidation
module-layout.md	4 Resource Management row updated to drop OTA files; 2 User Management row notes the F-3 consolidation
components/01_data_layer/description.md	Resource entity removed; UNIQUE INDEX on email noted; Resources.Latest.* cache key removed; storage-estimates row removed; Newtonsoft.Json version bumped to 13.0.4
components/02_user_management/description.md	RegisterUser and RegisterDevice rows updated to reflect the F-3 fix
components/04_resource_management/description.md	Rewritten — collapsed back to filesystem-storage scope; OTA references removed; F-2 callout retained as known limitation
components/05_admin_api/description.md	/get-update, /resources/publish, apiUploaderPolicy removed from endpoint and policy tables
modules/admin_api_program.md	Endpoint table no longer lists OTA endpoints; "Removed in cycle 1" section absorbs them; DI list and policies updated
modules/services_user_service.md	F-3 fix detailed in Internal Logic; Npgsql added to Dependencies
modules/services_resource_update_service.md	Deleted
modules/common_entities_resource.md	Deleted
modules/common_requests_get_update.md	Deleted
modules/common_requests_publish_resource.md	Deleted
tests/traceability-matrix.md	AZ-183 section marked REVERTED; FT-P-21..23 strikethroughs
tests/blackbox-tests.md	OTA section collapsed to ID-placeholder table; bodies removed
_docs/05_security/security_report.md	Verdict flipped from FAIL → PASS_WITH_WARNINGS; F-1, F-3, D-1 marked CLOSED; F-2 deferred
_docs/05_security/static_analysis.md	F-1, F-3, F-5 marked CLOSED with resolution notes
_docs/05_security/owasp_review.md	A01 / A02 / A04 / A07 categories upgraded to PASS_WITH_WARNINGS or PASS where the only failing finding was a now-closed cycle-1 entry
_docs/05_security/dependency_scan.md	(already updated during the audit) D-1 marked RESOLVED

Verification

• dotnet build Azaion.AdminApi/Azaion.AdminApi.csproj — green, 0 warnings.
• dotnet test Azaion.Test/Azaion.Test.csproj — 2/2 passed.
• ./scripts/run-tests.sh (e2e) — 44/44 passed (down from 48/48; the 4 deleted ResourceUpdateTests are accounted for).

Follow-up tickets filed in Jira

Ticket	Title	Points
AZ-516	F-2: Sanitize dataFolder route segment to prevent path traversal	3
AZ-517	F-4: Harden /devices response (Cache-Control, runbook)	2
AZ-518	F-6: Run admin API container as non-root	2
AZ-519	F-7: Migrate password hashing to Argon2id with per-user salt	5
AZ-520	F-8: Add rate limiting to /login endpoint	2
AZ-521	Low-severity security hygiene bundle (F-9, F-11, F-12, F-13)	3

A revert comment was added to AZ-183 (the OTA task that was deleted as part of the F-1 fix).