fix(sync): write-scope for intents, honest reinstate copy, pull endpoint tests #1364

Merged
chris merged 1 commit from fix/sync-intentscope-reinstate-copy into main 2026-10-24 22:23:11 +02:00
Owner

PR-1 of the 4-PR hardening plan from the adversarial review (oracle findings F3 / F2-short / F7). Based on the latest origin/main (includes #1362).

F3 (HIGH, security): intent endpoint was gated on the READ scope

POST /api/sync/intents required media:read — a read-only API credential could trash/restore/reinstate library items.

Scope choice: media:upload (existing scope), not a new media:write. Rationale:

  • media:upload is already v1's mutation scope — required by UploadSessionService.createForApiCredential and UploadFileController for the upload-session protocol (ADR 0097). The intents channel is the same class of client→server library mutation (S3 explicitly frames uploads as "the accepted-intent pipeline"; intents are the mutation complement), so semantically defensible without inventing vocabulary.
  • No new scope value ⇒ no V1_ALLOWED_SCOPES/grant-UI/OpenAPI churn, no migration for existing credentials, and every existing write-capable credential (incl. the Android app's own [media:upload, media:read] credential) keeps working unchanged.
  • The Android app's revert actions authenticate with its [media:upload, media:read] Bearer credential (AuthRepository.kt), so the history screen's restore flow keeps working.
  • Read endpoints GET /api/sync/changes + GET /api/sync/removed-history keep media:read — unchanged, now pinned by tests.

Needed spec amendment (collected here for the amendment PR, not applied per PR-1 constraints) — see bottom.

F2-short (HIGH, UX honesty): reinstate dead-end on purged items

On permanently_deleted history entries, the "Wieder aufnehmen" button was a dead end: the reinstate intent either rejects (override_rejected_explicit_deletion, C6) or accepts without effect (re-authorization only — ISSUE-190; real re-upload flow out of scope here).

Client fix: purged entries now offer no button at all and no fake navigation. The card shows the live state label + honest inline copy (exact text below, plain-language discipline: reads as fact, names the actual path, no false promise). trashed entries keep the working one-tap "Wiederherstellen".

Implementation: RemovedEntryUi.revertAction is now nullable (null = no action offered today; revertActionFor maps only trashed → RESTORE); revert() no-ops for action-less entries (defense-in-depth behind the absent UI control). The C6 typed-reject copy mapping (sync_intent_reject_override_explicit_deletion) stays wired for the channel.

F7 (LOW): HTTP-layer test for the pull endpoint

New SyncControllerTest (MockMvc, mirrors SyncIntentsControllerTest): S2 envelope passthrough ({epoch, changes, nextCursor, hasMore} + per-change fields), limit param/default, write-only credential → 403 ProblemDetail on both GETs, read-only credential → 200, negative cursor → 400 ProblemDetail (the guard lives in the service and is pinned against real Postgres in SyncChangeFeedIntegrationTest; the HTTP test pins the wiring), owner scoping at the boundary (controller delegates exactly the session's owner id; cross-owner data semantics pinned in the integration test).

Exact copy (for review)

de: Dieses Bild wurde endgültig entfernt. Wenn du es wieder in der Mediathek haben möchtest, füge es auf deinem Gerät erneut hinzu.
en: This picture was permanently removed. If you want it back in the library, add it to Memories from your device again.
da: Dette billede blev fjernet permanent. Hvis du vil have det tilbage i biblioteket, skal du tilføje det til Memories fra din enhed igen.

Key: removed_history_purged_no_action. "erneut hinzufügen" = the user's existing mental model of adding media (albums/backup), matching the "Bewusst nicht in Memories" anchor copy's register; "Memories" is used in en/da where the German sentence reads naturally without the product name.

KNOWN_ISSUES

Appended as ISSUE-196, not 193: the pre-assigned number collided — the 2026-10-24 KNOWN_ISSUES audit (#1361) renumbered resolved entries INTO 193/194/195 ((renumbered from …) markers). 196 is the next free id; the entry carries the branch ref as instructed.

Validation

  • :apps:api:test — BUILD SUCCESSFUL, 198 suites / 2308 tests, 0 failures, 0 errors (9 skips are pre-existing: 8 @Disabled Postgres-requiring notification tests + 1 opt-in local research fixture; no sync test is Docker-gated, all sync suites ran).
  • :app:testDebugUnitTest — BUILD SUCCESSFUL, 62 suites / 651 tests, 0 failures, 0 errors, 0 skipped (fresh --rerun-tasks run).
  • No changes to SyncIntentService execution logic, TrashService, core binder/engine, or the PR-2 call sites.

Needed spec 065 amendment text (S3/S5 scope vocabulary)

S3, auth bullet (new, after the request-envelope bullet):
"Auth: /api/** is authenticated by SecurityConfiguration; the owner scope comes from the authenticated session. Session principals are not scope-limited. API credentials need the media:upload scope: the intents channel MUTATES the library (delete/restore/reinstate), so it requires the same write-appropriate scope as the upload-session protocol (ADR 0097) — never media:read. A read-only credential answers RFC 9457 ProblemDetail 403 at the request level."

S2 + S11 (read endpoints):
"GET /api/sync/changes and GET /api/sync/removed-history are read-only and require API credentials to hold media:read."

S5, add to the request-level (non-reason-code) notes:
"An API credential lacking the required scope (media:upload on intent submission, media:read on the read feeds) is a request-level failure: RFC 9457 ProblemDetail 403, never a per-item result."

(media:upload as the mutation scope, media:read as the read scope — the v1 pair stays two-valued; if a future third-party integration surface needs finer-grained "sync-write without upload", that is the point to introduce media:write as an additive scope.)

PR-1 of the 4-PR hardening plan from the adversarial review (oracle findings F3 / F2-short / F7). Based on the latest origin/main (includes #1362). ## F3 (HIGH, security): intent endpoint was gated on the READ scope `POST /api/sync/intents` required `media:read` — a read-only API credential could trash/restore/reinstate library items. **Scope choice: `media:upload` (existing scope), not a new `media:write`.** Rationale: - `media:upload` is already v1's mutation scope — required by `UploadSessionService.createForApiCredential` and `UploadFileController` for the upload-session protocol (ADR 0097). The intents channel is the same class of client→server library mutation (S3 explicitly frames uploads as "the accepted-intent pipeline"; intents are the mutation complement), so semantically defensible without inventing vocabulary. - No new scope value ⇒ no `V1_ALLOWED_SCOPES`/grant-UI/OpenAPI churn, no migration for existing credentials, and every existing write-capable credential (incl. the Android app's own `[media:upload, media:read]` credential) keeps working unchanged. - The Android app's revert actions authenticate with its `[media:upload, media:read]` Bearer credential (`AuthRepository.kt`), so the history screen's restore flow keeps working. - Read endpoints `GET /api/sync/changes` + `GET /api/sync/removed-history` keep `media:read` — unchanged, now pinned by tests. Needed spec amendment (collected here for the amendment PR, not applied per PR-1 constraints) — see bottom. ## F2-short (HIGH, UX honesty): reinstate dead-end on purged items On `permanently_deleted` history entries, the "Wieder aufnehmen" button was a dead end: the reinstate intent either rejects (`override_rejected_explicit_deletion`, C6) or accepts **without effect** (re-authorization only — ISSUE-190; real re-upload flow out of scope here). Client fix: purged entries now offer **no button at all** and no fake navigation. The card shows the live state label + honest inline copy (exact text below, plain-language discipline: reads as fact, names the actual path, no false promise). `trashed` entries keep the working one-tap **"Wiederherstellen"**. Implementation: `RemovedEntryUi.revertAction` is now nullable (`null` = no action offered today; `revertActionFor` maps only `trashed` → RESTORE); `revert()` no-ops for action-less entries (defense-in-depth behind the absent UI control). The C6 typed-reject copy mapping (`sync_intent_reject_override_explicit_deletion`) stays wired for the channel. ## F7 (LOW): HTTP-layer test for the pull endpoint New `SyncControllerTest` (MockMvc, mirrors `SyncIntentsControllerTest`): S2 envelope passthrough (`{epoch, changes, nextCursor, hasMore}` + per-change fields), limit param/default, write-only credential → 403 ProblemDetail on both GETs, read-only credential → 200, negative cursor → 400 ProblemDetail (the guard lives in the service and is pinned against real Postgres in `SyncChangeFeedIntegrationTest`; the HTTP test pins the wiring), owner scoping at the boundary (controller delegates exactly the session's owner id; cross-owner data semantics pinned in the integration test). ## Exact copy (for review) **de:** `Dieses Bild wurde endgültig entfernt. Wenn du es wieder in der Mediathek haben möchtest, füge es auf deinem Gerät erneut hinzu.` **en:** `This picture was permanently removed. If you want it back in the library, add it to Memories from your device again.` **da:** `Dette billede blev fjernet permanent. Hvis du vil have det tilbage i biblioteket, skal du tilføje det til Memories fra din enhed igen.` Key: `removed_history_purged_no_action`. "erneut hinzufügen" = the user's existing mental model of adding media (albums/backup), matching the "Bewusst nicht in Memories" anchor copy's register; "Memories" is used in en/da where the German sentence reads naturally without the product name. ## KNOWN_ISSUES Appended as **ISSUE-196**, not 193: the pre-assigned number collided — the 2026-10-24 KNOWN_ISSUES audit (#1361) renumbered resolved entries INTO 193/194/195 (`(renumbered from …)` markers). 196 is the next free id; the entry carries the branch ref as instructed. ## Validation - `:apps:api:test` — **BUILD SUCCESSFUL, 198 suites / 2308 tests, 0 failures, 0 errors** (9 skips are pre-existing: 8 `@Disabled` Postgres-requiring notification tests + 1 opt-in local research fixture; no sync test is Docker-gated, all sync suites ran). - `:app:testDebugUnitTest` — **BUILD SUCCESSFUL, 62 suites / 651 tests, 0 failures, 0 errors, 0 skipped** (fresh `--rerun-tasks` run). - No changes to SyncIntentService execution logic, TrashService, core binder/engine, or the PR-2 call sites. ## Needed spec 065 amendment text (S3/S5 scope vocabulary) > **S3, auth bullet (new, after the request-envelope bullet):** > "Auth: /api/** is authenticated by SecurityConfiguration; the owner scope comes from the authenticated session. Session principals are not scope-limited. API credentials need the `media:upload` scope: the intents channel MUTATES the library (delete/restore/reinstate), so it requires the same write-appropriate scope as the upload-session protocol (ADR 0097) — never `media:read`. A read-only credential answers RFC 9457 ProblemDetail 403 at the request level." > > **S2 + S11 (read endpoints):** > "`GET /api/sync/changes` and `GET /api/sync/removed-history` are read-only and require API credentials to hold `media:read`." > > **S5, add to the request-level (non-reason-code) notes:** > "An API credential lacking the required scope (`media:upload` on intent submission, `media:read` on the read feeds) is a request-level failure: RFC 9457 ProblemDetail 403, never a per-item result." (`media:upload` as the mutation scope, `media:read` as the read scope — the v1 pair stays two-valued; if a future third-party integration surface needs finer-grained "sync-write without upload", that is the point to introduce `media:write` as an additive scope.)
fix(sync): write-scope for intents, honest reinstate copy, pull endpoint tests
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 5s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Deploy review instance (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Successful in 4m54s
Build and Deploy / Run scoped PR tests (push) Successful in 7m28s
3df015c146
F3 (HIGH, security): POST /api/sync/intents was gated on the READ scope
media:read, so a read-only API credential could trash, restore or
reinstate library items. Now gated on media:upload — v1's existing write
scope (upload-session protocol, ADR 0097) — chosen over introducing a
new media:write scope value: the intents channel is the same class of
client-to-server library mutation, so no new scope/grant surface is
needed and existing write credentials keep working. The read endpoints
GET /api/sync/changes + GET /api/sync/removed-history keep media:read
(pinned by SyncControllerTest).

F2 (HIGH, UX honesty): the S11 removed-history screen offered
"Wieder aufnehmen" on permanently_deleted entries where the reinstate
intent either rejects (override_rejected_explicit_deletion, C6) or
accepts without effect (re-authorization only, ISSUE-190) — a dead end
that implied success. Purged entries now offer NO button: the card
states the actual state and path as plain copy (de/en/da), no fake
navigation. Trashed entries keep the working one-tap Wiederherstellen;
revertAction is now nullable (null = no action today) and revert() is a
no-op guard for action-less entries. The C6 reject-copy mapping stays
wired for the channel.

F7 (LOW): new SyncControllerTest pins the pull endpoint's HTTP layer:
S2 envelope shape, read-scope gate (403 ProblemDetail), negative cursor
-> 400 ProblemDetail, and owner scoping at the boundary.

KNOWN_ISSUES: ISSUE-196 (pre-assigned 193 was taken by the 2026-10-24
audit renumbering; 193-195 exist). Spec 065 S3/S5 scope amendment text
is collected for the amendment PR.

Tests: :apps:api:test 2308 green (9 pre-existing skips, no Docker-
disabled sync tests), :app:testDebugUnitTest 651 green.
chris merged commit fe75dfb0d7 into main 2026-10-24 22:23:11 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1364
No description provided.