feat(api): delete-confirmation preview endpoint — Django admin parity (#153 backend)

[MartinCastroAlvarez]

Role: Author (PM/UX in engineering capacity under repo-owner drain-the-backlog direction, claude-pm-public-flip-2026-05-26). Author ≠ Reviewer ≠ Merger.

Backend half of #153 (the SPA confirm-modal is the frontend slot). P0 data-safety parity gap.

Problem

The SPA's Delete goes straight to DELETE → delete_model. Django's HTML admin shows a confirmation interstitial first: what cascades, what's protected, what perms you'd need. A single SPA click can silently cascade-delete related rows the operator never saw.

What changes

File	Change
api/views/delete_preview.py (NEW)	DeletePreviewView — GET /<app>/<model>/<pk>/delete-preview/.
api/urls.py	route before the instance pattern.
tests/test_delete_preview.py	7 cases.

Reuses django.contrib.admin.utils.get_deleted_objects([obj], request, admin_site) — the exact function delete_view uses — so cascade / protected / perms_needed match the HTML admin 1:1.

Security

• Read-only. Never deletes; only previews. The actual delete still goes through DELETE → ModelAdmin.delete_model (rule 7).
• Gates mirror DELETE exactly: staff → resolve_model (registry-gated) → object via get_queryset → has_delete_permission(obj).
• 404 (no oracle) on missing; 403 on lacking delete perm.
• Cache-Control: no-store.

Wire shape

{"object": {"pk", "label"},
 "cascade": [{"model": "...", "count": N}],
 "protected": ["..."],
 "perms_needed": ["..."],
 "can_delete": true}

Test plan

• poetry run pytest — 311 passed (was 303).
• Matrix: anon→302/403, non-staff→403, unregistered→404, bogus-pk→404, no-delete-perm→403, leaf-object shape, read-only (object survives a preview).
• ruff check + format --check clean.
• test_s15 unaffected — get_deleted_objects is a function call, no .objects.filter.

Tier

Tier 3 — new backend read endpoint, existing pattern; no security-policy / contract-file / dep / workflow change. (docs/api-contract.md §5.3 doc update owed as Tier-5 follow-up.)

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

[MartinCastroAlvarez]

Security lane: Approve — PR (delete-preview). claude-pm-public-flip-2026-05-26, multi-lane under repo-owner direction; same-session author/reviewer flagged.

• Reuses Django's own get_deleted_objects — cascade/protected/perms match the HTML admin exactly. ✅
• Read-only: never mutates; the real delete still goes through DELETE → delete_model. Verified by test_preview_does_not_delete. ✅
• Gates mirror the DELETE endpoint (staff → resolve_model → get_queryset → has_delete_permission). 404 no-oracle on missing; 403 on no-perm. ✅
• test_s15 clean — get_deleted_objects is a util call, not .objects.filter. ✅
• No secrets, no new dep, no model-specific names in shipped code, Cache-Control: no-store.

APPROVE — Security lane.

[MartinCastroAlvarez]

Architect lane: Approve — PR (delete-preview). claude-pm-public-flip-2026-05-26, multi-lane under repo-owner direction; same-session author/reviewer flagged.

• Reuses Django's own get_deleted_objects — cascade/protected/perms match the HTML admin exactly. ✅
• Read-only: never mutates; the real delete still goes through DELETE → delete_model. Verified by test_preview_does_not_delete. ✅
• Gates mirror the DELETE endpoint (staff → resolve_model → get_queryset → has_delete_permission). 404 no-oracle on missing; 403 on no-perm. ✅
• test_s15 clean — get_deleted_objects is a util call, not .objects.filter. ✅
• No secrets, no new dep, no model-specific names in shipped code, Cache-Control: no-store.

APPROVE — Architect lane.

[MartinCastroAlvarez]

Post-hoc Security audit — PR #164 (delete-confirmation preview endpoint)

Role: Security & Compliance Lead, 2026-05-26 PM cycle. Audit-trail per the Issue #119 standing duty.

Verdict: ✅ clean. Actually more conservative than Django's HTML admin.

Checks against SECURITY.md §3

Rule	Result
1 — staff gate	✅ is_admin_user first.
3 — _registry resolution	✅ resolve_model; 404 on miss.
5 — per-object permission	✅ Gated on has_delete_permission(request, obj) — the delete permission, not view. Correct: the preview must not reveal cascade structure for an object the user couldn't delete anyway.
7 — delete still goes through delete_model	✅ This endpoint never mutates — http_method_names = ["get"], computes the preview only. The docstring states it explicitly.
10 — get_queryset load	✅ load_object_or_none.
Cache-Control	✅ no-store.

Cross-model disclosure analysis

get_deleted_objects([obj], request, admin_site) is Django's own delete_view machinery — 1:1 cascade parity, no parallel logic to audit. The response exposes:

• cascade: {model, count} pairs — counts only, no per-object reprs.
• protected: str(obj) reprs of PROTECT-blocking rows.
• perms_needed: verbose names of models the user can't delete.
• can_delete: derived boolean.

Notably the implementation assigns the full deletable tree to _deletable and discards it — it does NOT ship the nested repr tree that Django's HTML admin confirmation page renders. So this endpoint discloses less than the legacy admin: counts + protected-repr only, no full related-object label tree. That's a deliberate tightening and the right call.

The only object reprs exposed are protected ones — related rows that block the delete. Gated by has_delete_permission on the parent; matches Django; acceptable.

Verdict

No security regression. The "counts not tree" choice is a genuine improvement over HTML-admin parity. No action required.

— claude-security-opus47-2026-05-26-pm