From 17415d8831b39d6fc0b406779a2f906f73a85032 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Mon, 24 Aug 2026 20:05:31 +0200 Subject: [PATCH] feat(cases): enforce purpose-bound case governance --- README.md | 16 +- docs/CONCEPT.md | 53 +++- pyproject.toml | 2 +- src/govoplan_cases/backend/db/models.py | 6 + src/govoplan_cases/backend/decision_path.py | 22 +- src/govoplan_cases/backend/domain.py | 30 +++ src/govoplan_cases/backend/dsar_provider.py | 9 + src/govoplan_cases/backend/evidence_links.py | 10 +- src/govoplan_cases/backend/manifest.py | 94 ++++++- ...a7c4e2f9b1d6_v0123_case_access_purposes.py | 51 ++++ src/govoplan_cases/backend/record_source.py | 11 +- src/govoplan_cases/backend/router.py | 25 +- src/govoplan_cases/backend/schemas.py | 12 + src/govoplan_cases/backend/search_source.py | 8 +- src/govoplan_cases/backend/service.py | 245 +++++++++++++----- tests/test_case_lifecycle.py | 110 +++++++- tests/test_dsar_provider.py | 10 +- .../test_interface_documentation_contract.py | 14 + tests/test_migrations.py | 16 +- tests/test_record_source.py | 13 +- tests/test_search_source.py | 18 +- webui/package.json | 2 +- webui/src/api/cases.ts | 29 ++- .../src/features/cases/CaseDecisionDialog.tsx | 5 +- webui/src/features/cases/CaseDetailPage.tsx | 34 ++- webui/src/features/cases/CaseShareDialog.tsx | 51 +++- webui/src/features/cases/CasesPage.tsx | 20 +- webui/src/i18n/generatedTranslations.ts | 12 + 28 files changed, 786 insertions(+), 142 deletions(-) create mode 100644 src/govoplan_cases/backend/migrations/versions/a7c4e2f9b1d6_v0123_case_access_purposes.py diff --git a/README.md b/README.md index 1f69490..dbc269e 100644 --- a/README.md +++ b/README.md @@ -34,17 +34,21 @@ The executable backend slice now exposes: Cases does not own institutional Service, Party, representation, identity, address, Mandate, Decision, file, workflow, or task lifecycles. The `/cases` workspace now supplies list/detail, status/title revision, history, and timeline -surfaces. A case can remain tenant-visible or become restricted to its creator, -case administrators, explicit user/group grants, and assignment-derived -function, function-assignment, or organization-unit grants. The detail surface -uses the shared reference selector to manage those grants; list, detail, -history, timeline, and update paths all apply the same fail-closed ACL. +surfaces. A case can remain tenant-visible or become restricted. Restricted +access requires a current custodian, explicit subject, or assignment-derived +grant whose permission and exact allowed purpose both match the operation. +`cases.casework` is the interactive default and `cases.search` is reserved for +Search rechecks. The detail surface uses the shared reference selector to +manage grants and purposes; list, detail, history, timeline, update, evidence, +Decision, Search, and Records-source paths apply the same fail-closed decision. +Current grants also govern historical revision reads. See [docs/CONCEPT.md](docs/CONCEPT.md) for the current module concept. ## Data-subject requests -Cases contributes `privacy.dsar.cases`. It reports exact-tenant access grants +Cases contributes `privacy.dsar.cases`. It reports exact-tenant access grants, +including their bounded allowed purposes, and operator attribution, plus minimized case lifecycle data when an explicit Cases reference is supplied and corroborated. Raw snapshots, metadata, search text, free-text reasons, event payloads, evidence identifiers, request digests, diff --git a/docs/CONCEPT.md b/docs/CONCEPT.md index 0494246..1fa7317 100644 --- a/docs/CONCEPT.md +++ b/docs/CONCEPT.md @@ -88,19 +88,21 @@ The persistent backend provides: - replay-safe case timeline events carrying the institutional context and a stable event/audit reference - tenant-level resource ACL and tenant summary providers -- tenant-wide or restricted object access with explicit, revisioned grants +- tenant-wide or restricted object access with purpose-bound, revisioned grant snapshots - deterministic, replay-safe case launch from an exact Service binding - deterministic, replay-safe Case escalation from an authorized Ticket handoff The `/cases` list and `/cases/:caseId` detail workspace provide server-side search/status filtering, case facts, typed references, history, timeline, and OCC-guarded title/status/access revisions with an explicit change reason. -Restricted cases are visible to their creator, case administrators, explicit -user/group grants, and matching function, function-assignment, or -organization-unit assignments. The same decision filters list, detail, -history, timeline, and update operations so an inaccessible identifier does -not disclose case existence. API reads and writes are tenant-bound, and -create/update/assign/close/share/catalog operations have separate permissions. +Restricted cases require a current custodian, explicit subject, or matching +function, function-assignment, or organization-unit grant. The grant must imply +the requested permission and contain the exact declared purpose. The same +decision filters list, detail, history, timeline, update, evidence, Decision, +Search, and Records-source operations so an inaccessible identifier does not +disclose case existence. Current grants govern historical revisions. API reads +and writes are tenant-bound, and create/update/assign/close/share/catalog +operations have separate permissions. ## Permissions @@ -114,9 +116,14 @@ Implemented scopes: - `cases:case:share` - `cases:case:admin` -Access decisions combine tenant permissions, creator/administrative authority, -case assignments, and explicit case shares. Restricted access is versioned -with the case record so its history remains reconstructable. +Access decisions combine tenant permissions with current purpose-bound +custodian, assignment-derived, and explicit subject grants. Creating or newly +restricting a case establishes a custodian grant for the attributable actor. +`cases.casework` is the stable interactive default; Search rechecks use only +`cases.search`; Records filing supplies its declared purpose. Assignment-derived +grants admit `cases.casework`, `cases.search`, and `cases.records`. Each accepted +timeline event stores the evaluated purpose. Restricted access snapshots remain +versioned with the case record while current grant state governs disclosure. ## Data Model Sketch @@ -187,7 +194,7 @@ metadata snapshots. The owning module remains responsible for the real object. When Records is enabled, `records.source.cases` resolves one exact immutable case revision for eAkte filing. Cases rechecks current tenant, scope, and -object-level access, then returns the case number, lifecycle state, represented +object-level access for the caller-declared purpose, then returns the case number, lifecycle state, represented valid interval, recorded time, canonical snapshot digest, and launch link. Records owns the filing decision and chronology; Cases remains authoritative for the case and its revision history. @@ -196,7 +203,25 @@ When Search is enabled, `cases.cases` indexes current Case titles, numbers, types, states, and the existing bounded search projection. It includes no provider-owned evidence content or protected Decision reasoning. Restricted Case candidates carry bounded ACL tokens and every result is checked again -against the current Case object-access decision before disclosure. +against the current Case object-access decision using the fixed `cases.search` +purpose before disclosure. Search links preserve that purpose in the Case URL. + +## Information governance adoption + +Cases enforces temporal browsing for immutable case revisions while always +using current authorization for historical reads. It enforces exact-purpose +access for restricted cases and records the evaluated purpose in lifecycle +evidence. Governed context validates and persists tenant, service, party, +organization, function, acting assignment/delegation, mandate, jurisdiction, +legal-basis, evidence, Decision, and record references at their owning +boundaries. + +Retention remains contract-only. Cases preserves immutable revisions and +timeline evidence and publishes DSAR retention/manual-review consequences, but +does not yet apply configurable schedules, legal holds, appraisal, or +disposition gates. Those controls must be implemented through the Records +boundary or a future explicit Cases retention policy before retention can be +claimed as enforced. ## WebUI @@ -230,8 +255,8 @@ The focused suite covers: ## Data-subject requests Cases publishes `privacy.dsar.cases`. Canonical account, identity, and -membership selectors cover Cases-owned operator attribution; account and -identity selectors also cover explicit case-access grants. Exact +membership selectors cover Cases-owned operator attribution and matching +account, identity, or membership access grants. Exact `cases.case`, `cases.revision`, `cases.access_grant`, and `cases.timeline` references select lifecycle data. When a canonical and direct selector are combined, a Cases-owned relationship must corroborate them and all supplied diff --git a/pyproject.toml b/pyproject.toml index 6e42fe1..5d2c6eb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "govoplan-cases" -version = "0.1.22" +version = "0.1.23" description = "GovOPlaN administrative case context module." readme = "README.md" requires-python = ">=3.12" diff --git a/src/govoplan_cases/backend/db/models.py b/src/govoplan_cases/backend/db/models.py index 0a0f8e1..470d9eb 100644 --- a/src/govoplan_cases/backend/db/models.py +++ b/src/govoplan_cases/backend/db/models.py @@ -140,6 +140,9 @@ class CaseAccessGrant(Base, TimestampMixin): subject_kind: Mapped[str] = mapped_column(String(40), nullable=False, index=True) subject_id: Mapped[str] = mapped_column(String(255), nullable=False, index=True) permissions: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False) + allowed_purposes: Mapped[list[str]] = mapped_column( + JSON, default=list, nullable=False + ) source: Mapped[str] = mapped_column(String(30), nullable=False, index=True) active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False, index=True) source_revision: Mapped[int] = mapped_column(Integer, nullable=False) @@ -163,6 +166,9 @@ class CaseTimelineEntry(Base, TimestampMixin): summary: Mapped[str] = mapped_column(String(500), nullable=False) occurred_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, index=True) actor_id: Mapped[str | None] = mapped_column(String(255), nullable=True, index=True) + purpose: Mapped[str] = mapped_column( + String(255), nullable=False, default="cases.casework", index=True + ) idempotency_key: Mapped[str] = mapped_column(String(255), nullable=False) request_sha256: Mapped[str] = mapped_column(String(64), nullable=False) audit_event_id: Mapped[str | None] = mapped_column(String(255), nullable=True, index=True) diff --git a/src/govoplan_cases/backend/decision_path.py b/src/govoplan_cases/backend/decision_path.py index d4ae73a..724bb4b 100644 --- a/src/govoplan_cases/backend/decision_path.py +++ b/src/govoplan_cases/backend/decision_path.py @@ -22,7 +22,7 @@ from govoplan_core.core.institutional import ( TemporalRevision, resolve_mandate_candidates, ) -from govoplan_cases.backend.domain import CaseRecord +from govoplan_cases.backend.domain import DEFAULT_CASE_ACCESS_PURPOSE, CaseRecord from govoplan_cases.backend.service import ( can_access_case, get_case, @@ -56,6 +56,7 @@ class CaseDecisionCommand: reasoning: str change_reason: str idempotency_key: str + purpose: str = DEFAULT_CASE_ACCESS_PURPOSE conditions: tuple[str, ...] = () @@ -93,8 +94,14 @@ class CaseDecisionPath: principal, case_id=case_id, revision=command.expected_case_revision, + purpose=command.purpose, + ) + current = get_case( + session, + principal, + case_id=case_id, + purpose=command.purpose, ) - current = get_case(session, principal, case_id=case_id) if source_case is None or current is None: raise LookupError("Case not found.") if not can_access_case( @@ -102,6 +109,7 @@ class CaseDecisionPath: principal, case_id=case_id, permission="update", + purpose=command.purpose, ): raise PermissionError("Case update access is denied.") @@ -163,6 +171,7 @@ class CaseDecisionPath: recorded_at=command.effective_at, change_reason=command.change_reason, idempotency_key=f"formal-decision:{command.idempotency_key}", + purpose=command.purpose, ) return CaseDecisionResult(case=linked, decision=persisted) @@ -172,8 +181,14 @@ class CaseDecisionPath: principal: object, *, case_id: str, + purpose: str | None = None, ) -> tuple[FormalDecision, ...]: - case = get_case(session, principal, case_id=case_id) + case = get_case( + session, + principal, + case_id=case_id, + purpose=purpose, + ) if case is None: raise LookupError("Case not found.") registry = _decision_registry(self._registry) @@ -434,6 +449,7 @@ def _validate_command(command: CaseDecisionCommand) -> None: (command.reasoning, "Decision reasoning"), (command.change_reason, "Decision change reason"), (command.idempotency_key, "Decision idempotency key"), + (command.purpose, "Case access purpose"), ): if not value.strip(): raise CaseDecisionError(f"{label} is required.") diff --git a/src/govoplan_cases/backend/domain.py b/src/govoplan_cases/backend/domain.py index d1e2560..0b26d07 100644 --- a/src/govoplan_cases/backend/domain.py +++ b/src/govoplan_cases/backend/domain.py @@ -17,15 +17,19 @@ CASE_ACCESS_SUBJECT_KINDS = frozenset( { "account", "identity", + "membership", "group", "role", "function", "function_assignment", "organization_unit", "service_account", + "delegation", } ) CASE_ACCESS_PERMISSIONS = frozenset({"read", "update", "share", "admin"}) +DEFAULT_CASE_ACCESS_PURPOSE = "cases.casework" +MAX_CASE_ACCESS_PURPOSES = 100 @dataclass(frozen=True, slots=True) @@ -33,6 +37,7 @@ class CaseGrant: subject_kind: str subject_id: str permissions: tuple[str, ...] = ("read",) + allowed_purposes: tuple[str, ...] = (DEFAULT_CASE_ACCESS_PURPOSE,) def __post_init__(self) -> None: if self.subject_kind not in CASE_ACCESS_SUBJECT_KINDS: @@ -43,12 +48,29 @@ class CaseGrant: if not normalized or set(normalized) - CASE_ACCESS_PERMISSIONS: raise InstitutionalContextError("Case access permissions are invalid.") object.__setattr__(self, "permissions", normalized) + purposes = tuple( + dict.fromkeys( + str(value).strip() for value in self.allowed_purposes if str(value).strip() + ) + ) + if not purposes: + raise InstitutionalContextError( + "Case access grants require at least one allowed purpose." + ) + if len(purposes) > MAX_CASE_ACCESS_PURPOSES or any( + len(value) > 255 for value in purposes + ): + raise InstitutionalContextError( + "Case access grant purposes exceed the supported bounds." + ) + object.__setattr__(self, "allowed_purposes", purposes) def to_dict(self) -> dict[str, object]: return { "subject_kind": self.subject_kind, "subject_id": self.subject_id, "permissions": list(self.permissions), + "allowed_purposes": list(self.allowed_purposes), } @classmethod @@ -58,10 +80,18 @@ class CaseGrant: raise InstitutionalContextError( "Case access permissions must be a list." ) + raw_purposes = value.get( + "allowed_purposes", (DEFAULT_CASE_ACCESS_PURPOSE,) + ) + if not isinstance(raw_purposes, (list, tuple)): + raise InstitutionalContextError( + "Case access purposes must be a list." + ) return cls( subject_kind=_text(value, "subject_kind"), subject_id=_text(value, "subject_id"), permissions=tuple(str(item) for item in raw_permissions), + allowed_purposes=tuple(str(item) for item in raw_purposes), ) diff --git a/src/govoplan_cases/backend/dsar_provider.py b/src/govoplan_cases/backend/dsar_provider.py index 4662d0e..38a94ba 100644 --- a/src/govoplan_cases/backend/dsar_provider.py +++ b/src/govoplan_cases/backend/dsar_provider.py @@ -288,6 +288,7 @@ def _matching_grants( for kind, value in ( ("account", selectors.account_id), ("identity", selectors.identity_id), + ("membership", selectors.membership_id), ): if value: conditions.append( @@ -431,6 +432,10 @@ def _grant_subject_matches( return bool( (row.subject_kind == "account" and row.subject_id == selectors.account_id) or (row.subject_kind == "identity" and row.subject_id == selectors.identity_id) + or ( + row.subject_kind == "membership" + and row.subject_id == selectors.membership_id + ) ) @@ -531,6 +536,9 @@ def _access_grant_record(row: CaseAccessGrant) -> DsarRecordRef: "subject_kind": row.subject_kind, "subject_id": row.subject_id, "permissions": [str(value)[:40] for value in row.permissions[:20]], + "allowed_purposes": [ + str(value)[:255] for value in row.allowed_purposes[:100] + ], "source": _bounded_text(row.source, 30), "active": row.active, "source_revision": row.source_revision, @@ -562,6 +570,7 @@ def _timeline_record( "match_fields": list(match_fields), "case_id": row.case_id, "event_type": _bounded_text(row.event_type, 120), + "purpose": _bounded_text(row.purpose, 255), "case_revision": row.case_revision, "occurred_at": _iso(row.occurred_at), "actor_id": row.actor_id if expose_actor else None, diff --git a/src/govoplan_cases/backend/evidence_links.py b/src/govoplan_cases/backend/evidence_links.py index 9e135a5..9907f7a 100644 --- a/src/govoplan_cases/backend/evidence_links.py +++ b/src/govoplan_cases/backend/evidence_links.py @@ -9,7 +9,7 @@ from urllib.parse import parse_qs, quote, urlsplit from sqlalchemy.orm import Session from govoplan_core.core.institutional import EvidenceReference -from govoplan_cases.backend.domain import CaseRecord +from govoplan_cases.backend.domain import DEFAULT_CASE_ACCESS_PURPOSE, CaseRecord from govoplan_cases.backend.service import CaseStoreError, get_case, update_case @@ -31,12 +31,14 @@ def link_case_evidence( recorded_at: datetime, change_reason: str, idempotency_key: str, + purpose: str = DEFAULT_CASE_ACCESS_PURPOSE, ) -> CaseRecord: base = _base_revision( session, principal, case_id=case_id, expected_revision=expected_revision, + purpose=purpose, ) evidence = _validated_evidence(reference, tenant_id=base.reference.tenant_id) if any(item.evidence_id == evidence.evidence_id for item in base.evidence_refs): @@ -50,6 +52,7 @@ def link_case_evidence( recorded_at=recorded_at, change_reason=change_reason, idempotency_key=idempotency_key, + purpose=purpose, ) @@ -63,12 +66,14 @@ def unlink_case_evidence( recorded_at: datetime, change_reason: str, idempotency_key: str, + purpose: str = DEFAULT_CASE_ACCESS_PURPOSE, ) -> CaseRecord: base = _base_revision( session, principal, case_id=case_id, expected_revision=expected_revision, + purpose=purpose, ) evidence = next( (item for item in base.evidence_refs if item.evidence_id == evidence_id), @@ -89,6 +94,7 @@ def unlink_case_evidence( recorded_at=recorded_at, change_reason=change_reason, idempotency_key=idempotency_key, + purpose=purpose, ) @@ -119,12 +125,14 @@ def _base_revision( *, case_id: str, expected_revision: int, + purpose: str, ) -> CaseRecord: base = get_case( session, principal, case_id=case_id, revision=expected_revision, + purpose=purpose, ) if base is None: raise LookupError("Case revision not found.") diff --git a/src/govoplan_cases/backend/manifest.py b/src/govoplan_cases/backend/manifest.py index 3a62679..bbb7501 100644 --- a/src/govoplan_cases/backend/manifest.py +++ b/src/govoplan_cases/backend/manifest.py @@ -15,6 +15,10 @@ from govoplan_core.core.institutional import ( CAPABILITY_MANDATE_RESOLVER, CAPABILITY_PARTY_RESOLVER, ) +from govoplan_core.core.information_governance import ( + InformationGovernanceDimension, + ModuleInformationGovernance, +) from govoplan_core.core.modules import ( CapabilityDocumentation, DocumentationCondition, @@ -72,7 +76,7 @@ from govoplan_core.db.base import Base MODULE_ID = "cases" -MODULE_VERSION = "0.1.22" +MODULE_VERSION = "0.1.23" READ_SCOPE = "cases:case:read" CREATE_SCOPE = "cases:case:create" UPDATE_SCOPE = "cases:case:update" @@ -819,6 +823,45 @@ manifest = ModuleManifest( "outcome": "The eAkte preserves an exact case snapshot reference while Cases retains authority.", }, ), + DocumentationTopic( + id="cases.governance.purpose-bound-access", + title="Purpose-bound access to restricted cases", + summary="Require a current subject grant, sufficient action, and one exact declared purpose before disclosing or changing a restricted case.", + body=( + "Tenant-visible cases continue to follow the Cases read permission. For a restricted case, every list, detail, history, timeline, update, share, evidence, Decision, Search, and Records-source path evaluates current grants against the acting account, membership, group, role, function, assignment, organization unit, service account, or delegation. The requested action and exact purpose must both match; missing or different purposes fail closed. cases.casework is the stable interactive default, cases.search is used only by Search authorization rechecks, and a Records filing request supplies its own declared purpose. Creating or newly restricting a case writes a purpose-bound custodian grant for the attributable actor. Assignment-derived grants permit cases.casework, cases.search, and cases.records. Explicit grants list their purposes separately and can be changed through the confirmed access dialog. Current grants always govern historical revision reads, so removed access cannot be recovered by selecting an older revision. Every accepted lifecycle event records the evaluated purpose. Retention schedules, legal holds, and disposition gates are not yet Cases-owned and remain a documented limitation." + ), + layer="available", + documentation_types=("admin", "user"), + audience=("user", "case_manager", "module_admin", "auditor"), + related_modules=("search", "records", "access"), + order=16, + links=( + DocumentationLink(label="Cases", href="/cases", kind="runtime"), + DocumentationLink( + label="Cases concept", + href="govoplan-cases/docs/CONCEPT.md", + kind="repository", + ), + ), + translations={ + "de": { + "title": "Zweckgebundener Zugriff auf eingeschränkte Vorgänge", + "summary": "Vor Offenlegung oder Änderung eines eingeschränkten Vorgangs eine aktuelle Subjektfreigabe, ausreichende Aktion und einen exakt angegebenen Zweck verlangen.", + "body": ( + "Mandantenweit sichtbare Vorgänge folgen weiterhin der Leseberechtigung von Cases. Bei einem eingeschränkten Vorgang prüfen Listen-, Detail-, Historien-, Timeline-, Änderungs-, Freigabe-, Nachweis-, Decision-, Search- und Records-Quellpfade aktuelle Freigaben gegen das handelnde Konto, die Mitgliedschaft, Gruppe, Rolle, Funktion, Funktionszuweisung, Organisationseinheit, das Dienstkonto oder die Delegation. Angeforderte Aktion und exakter Zweck müssen übereinstimmen; fehlende oder abweichende Zwecke schließen sicher. cases.casework ist der stabile interaktive Standard, cases.search wird ausschließlich für erneute Search-Autorisierungen verwendet und eine Records-Ablage übergibt ihren eigenen angegebenen Zweck. Beim Anlegen oder erstmaligen Einschränken entsteht eine zweckgebundene Custodian-Freigabe für die zurechenbare handelnde Person. Aus Zuweisungen abgeleitete Freigaben erlauben cases.casework, cases.search und cases.records. Ausdrückliche Freigaben führen ihre Zwecke getrennt und werden im bestätigten Zugriffsdialog geändert. Aktuelle Freigaben gelten stets auch für historische Revisionsabrufe; entzogener Zugriff kann daher nicht über eine ältere Revision wiederhergestellt werden. Jedes akzeptierte Lebenszyklusereignis hält den ausgewerteten Zweck fest. Aufbewahrungspläne, Legal Holds und Aussonderungssperren gehören noch nicht Cases und bleiben als Einschränkung dokumentiert." + ), + } + }, + metadata={ + "kind": "reference", + "help_contexts": [ + "cases.page.catalogue", + "cases.detail.access", + "cases.field.access-purpose", + "cases.field.allowed-purposes", + ], + }, + ), DocumentationTopic( id="cases.institutional-context", title="Case institutional context", @@ -881,8 +924,8 @@ manifest = ModuleManifest( "appends a timeline entry with actor, time, and change reason; a terminal " "status additionally requires the case-close permission. Case visibility is " "tenant-wide or restricted. Restricted cases remain visible only through " - "administrative authority, assignment or unit context, creator authority, or " - "an explicit account/group grant. Access changes append another immutable " + "a current purpose-bound custodian, assignment/unit context, or explicit " + "subject grant. Permission and exact allowed purpose must both match. Access changes append another immutable " "revision and require confirmation. Service, party, assignment, Decision, and " "record references identify provider-owned objects; Cases preserves their " "stable identifiers and versions without copying or silently changing them." @@ -907,8 +950,8 @@ manifest = ModuleManifest( "Änderungen an Titel und Status ergänzen eine unveränderliche Vorgangsrevision, geschützt durch erwartete Revision und " "stabilen Idempotenzschlüssel. Jede akzeptierte Änderung ergänzt außerdem einen Timeline-Eintrag mit handelnder Person, " "Zeitpunkt und Änderungsgrund; ein abschließender Status verlangt zusätzlich die Berechtigung zum Schließen. Die Sichtbarkeit " - "eines Vorgangs ist mandantenweit oder eingeschränkt. Eingeschränkte Vorgänge bleiben nur durch administrative Befugnis, " - "Zuweisungs- oder Einheitenkontext, Erstellerbefugnis oder eine ausdrückliche Konto-/Gruppenfreigabe sichtbar. " + "eines Vorgangs ist mandantenweit oder eingeschränkt. Eingeschränkte Vorgänge bleiben nur über eine aktuelle zweckgebundene " + "Custodian-, Zuweisungs-/Einheiten- oder ausdrückliche Subjektfreigabe sichtbar; Berechtigung und exakter erlaubter Zweck müssen übereinstimmen. " "Zugriffsänderungen ergänzen eine weitere unveränderliche Revision und verlangen Bestätigung. Service-, Beteiligten-, " "Zuweisungs-, Decision- und Aktenverweise bezeichnen Objekte anderer Provider; Cases bewahrt ihre stabilen Kennungen und " "Versionen, ohne sie zu kopieren oder stillschweigend zu verändern." @@ -933,6 +976,47 @@ manifest = ModuleManifest( }, ), ), + information_governance=ModuleInformationGovernance( + temporal_browsing=InformationGovernanceDimension( + adoption="enforced", + object_types=("case", "case_revision", "case_timeline_event"), + evidence=( + "src/govoplan_cases/backend/service.py", + "tests/test_case_lifecycle.py", + ), + ), + purpose_aware_access=InformationGovernanceDimension( + adoption="enforced", + object_types=("case", "case_access_grant", "case_timeline_event"), + evidence=( + "src/govoplan_cases/backend/service.py", + "src/govoplan_cases/backend/search_source.py", + "src/govoplan_cases/backend/record_source.py", + "tests/test_case_lifecycle.py", + "tests/test_search_source.py", + "tests/test_record_source.py", + ), + ), + retention=InformationGovernanceDimension( + adoption="contract_only", + object_types=("case", "case_revision", "case_timeline_event"), + limitation=( + "Cases preserves immutable history and DSAR retention evidence but does not yet apply configurable schedules, legal holds, appraisal, or disposition gates." + ), + ), + institutional_context=InformationGovernanceDimension( + adoption="enforced", + object_types=("case", "case_revision", "case_timeline_event"), + evidence=( + "src/govoplan_cases/backend/domain.py", + "src/govoplan_cases/backend/service.py", + "src/govoplan_cases/backend/decision_path.py", + "tests/test_case_lifecycle.py", + "tests/test_institutional_consumers.py", + "tests/test_decision_path.py", + ), + ), + ), architecture=ModuleArchitectureDeclaration( layer="human_work_procedure", kind="domain", diff --git a/src/govoplan_cases/backend/migrations/versions/a7c4e2f9b1d6_v0123_case_access_purposes.py b/src/govoplan_cases/backend/migrations/versions/a7c4e2f9b1d6_v0123_case_access_purposes.py new file mode 100644 index 0000000..03c2997 --- /dev/null +++ b/src/govoplan_cases/backend/migrations/versions/a7c4e2f9b1d6_v0123_case_access_purposes.py @@ -0,0 +1,51 @@ +"""v0.1.23 purpose-bound case access. + +Revision ID: a7c4e2f9b1d6 +Revises: f6d3a8b1c4e7 +""" +from __future__ import annotations + +from alembic import op +import sqlalchemy as sa + + +revision = "a7c4e2f9b1d6" +down_revision = "f6d3a8b1c4e7" +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.add_column( + "case_access_grants", + sa.Column( + "allowed_purposes", + sa.JSON(), + nullable=False, + server_default='["cases.casework"]', + ), + ) + op.add_column( + "case_timeline_entries", + sa.Column( + "purpose", + sa.String(length=255), + nullable=False, + server_default="cases.casework", + ), + ) + op.create_index( + op.f("ix_case_timeline_entries_purpose"), + "case_timeline_entries", + ["purpose"], + unique=False, + ) + + +def downgrade() -> None: + op.drop_index( + op.f("ix_case_timeline_entries_purpose"), + table_name="case_timeline_entries", + ) + op.drop_column("case_timeline_entries", "purpose") + op.drop_column("case_access_grants", "allowed_purposes") diff --git a/src/govoplan_cases/backend/record_source.py b/src/govoplan_cases/backend/record_source.py index 166faa8..0354bc9 100644 --- a/src/govoplan_cases/backend/record_source.py +++ b/src/govoplan_cases/backend/record_source.py @@ -49,7 +49,11 @@ class CasesRecordSource: ): raise RecordContractError("Current Cases read permission is required.") if not can_access_case( - session, principal, case_id=locator.resource_id, permission="read" + session, + principal, + case_id=locator.resource_id, + permission="read", + purpose=purpose, ): raise RecordContractError("The current principal cannot read this case.") try: @@ -93,7 +97,10 @@ class CasesRecordSource: valid_from=row.opened_at, valid_to=row.closed_at, recorded_at=row.recorded_at, - launch_url=f"/cases/{quote(row.case_id, safe='')}", + launch_url=( + f"/cases/{quote(row.case_id, safe='')}" + f"?purpose={quote(purpose, safe='')}" + ), metadata={ "case_number": identity.case_number, "case_type_key": row.case_type_key, diff --git a/src/govoplan_cases/backend/router.py b/src/govoplan_cases/backend/router.py index a445753..88ac60f 100644 --- a/src/govoplan_cases/backend/router.py +++ b/src/govoplan_cases/backend/router.py @@ -174,6 +174,7 @@ def api_list_cases( query: str = "", status_key: list[str] | None = Query(default=None), case_type_key: list[str] | None = Query(default=None), + purpose: str | None = Query(default=None, max_length=255), offset: int = Query(default=0, ge=0), limit: int = Query(default=100, ge=1, le=200), session: Session = Depends(get_session), @@ -187,6 +188,7 @@ def api_list_cases( query=query, status_keys=status_key, case_type_keys=case_type_key, + purpose=purpose, offset=offset, limit=limit, ) @@ -216,6 +218,7 @@ def api_create_case( principal, record=record, idempotency_key=payload.idempotency_key, + purpose=payload.purpose, ) session.commit() except (CaseStoreError, InstitutionalContextError) as exc: @@ -227,6 +230,7 @@ def api_create_case( @router.get("/{case_id}/decisions", response_model=dict[str, list[dict[str, Any]]]) def api_case_decisions( case_id: str, + purpose: str | None = Query(default=None, max_length=255), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(get_api_principal), ) -> dict[str, list[dict[str, Any]]]: @@ -237,6 +241,7 @@ def api_case_decisions( session, principal, case_id=case_id, + purpose=purpose, ) except ( CaseDecisionError, @@ -281,6 +286,7 @@ def api_record_case_decision( conditions=tuple(payload.conditions), change_reason=payload.change_reason, idempotency_key=payload.idempotency_key, + purpose=payload.purpose, ), ) session.commit() @@ -300,11 +306,18 @@ def api_record_case_decision( def api_get_case( case_id: str, revision: int | None = Query(default=None, ge=1), + purpose: str | None = Query(default=None, max_length=255), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(get_api_principal), ) -> dict[str, Any]: _require(principal, READ_SCOPE) - item = get_case(session, principal, case_id=case_id, revision=revision) + item = get_case( + session, + principal, + case_id=case_id, + revision=revision, + purpose=purpose, + ) if item is None: raise HTTPException(status_code=404, detail="Case not found") return item.to_dict() @@ -342,6 +355,7 @@ def api_update_case( recorded_at=payload.recorded_at, change_reason=payload.change_reason, idempotency_key=payload.idempotency_key, + purpose=payload.purpose, ) session.commit() except ( @@ -373,6 +387,7 @@ def api_link_case_evidence( recorded_at=payload.recorded_at, change_reason=payload.change_reason, idempotency_key=payload.idempotency_key, + purpose=payload.purpose, ) session.commit() except ( @@ -408,6 +423,7 @@ def api_unlink_case_evidence( recorded_at=payload.recorded_at, change_reason=payload.change_reason, idempotency_key=payload.idempotency_key, + purpose=payload.purpose, ) session.commit() except ( @@ -432,6 +448,7 @@ def api_case_share_target_options( selected: list[str] = Query(default=[]), limit: int = Query(default=50, ge=1, le=200), cursor: str | None = None, + purpose: str = Query(default="cases.casework", min_length=1, max_length=255), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(get_api_principal), ) -> ReferenceOptionListResponse: @@ -441,6 +458,7 @@ def api_case_share_target_options( principal, case_id=case_id, permission="share", + purpose=purpose, ): raise HTTPException(status_code=403, detail="Case share access is denied") try: @@ -470,6 +488,7 @@ def api_case_share_target_options( def api_case_history( case_id: str, limit: int = Query(default=100, ge=1, le=200), + purpose: str | None = Query(default=None, max_length=255), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(get_api_principal), ) -> CaseHistoryResponse: @@ -482,6 +501,7 @@ def api_case_history( principal, case_id=case_id, limit=limit, + purpose=purpose, ) ] ) @@ -491,6 +511,7 @@ def api_case_history( def api_case_timeline( case_id: str, limit: int = Query(default=200, ge=1, le=500), + purpose: str | None = Query(default=None, max_length=255), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(get_api_principal), ) -> CaseTimelineResponse: @@ -502,6 +523,7 @@ def api_case_timeline( principal, case_id=case_id, limit=limit, + purpose=purpose, ) ) ) @@ -513,6 +535,7 @@ def _update_changes(payload: CaseUpdateRequest) -> dict[str, object]: "recorded_at", "change_reason", "idempotency_key", + "purpose", } raw = payload.model_dump(exclude_unset=True, exclude=excluded) for key in ("party_refs", "assignment_refs", "decision_refs", "record_refs"): diff --git a/src/govoplan_cases/backend/schemas.py b/src/govoplan_cases/backend/schemas.py index 97449c4..2e4c853 100644 --- a/src/govoplan_cases/backend/schemas.py +++ b/src/govoplan_cases/backend/schemas.py @@ -34,6 +34,7 @@ class CaseWriteRequest(BaseModel): model_config = ConfigDict(extra="forbid") record: dict[str, Any] + purpose: str = Field(default="cases.casework", min_length=1, max_length=255) idempotency_key: str = Field(min_length=1, max_length=255) @@ -43,12 +44,14 @@ class CaseGrantRequest(BaseModel): subject_kind: Literal[ "account", "identity", + "membership", "group", "role", "function", "function_assignment", "organization_unit", "service_account", + "delegation", ] subject_id: str = Field(min_length=1, max_length=255) permissions: list[Literal["read", "update", "share", "admin"]] = Field( @@ -56,6 +59,11 @@ class CaseGrantRequest(BaseModel): min_length=1, max_length=4, ) + allowed_purposes: list[str] = Field( + default_factory=lambda: ["cases.casework"], + min_length=1, + max_length=100, + ) class CaseUpdateRequest(BaseModel): @@ -65,6 +73,7 @@ class CaseUpdateRequest(BaseModel): recorded_at: datetime change_reason: str = Field(min_length=1, max_length=1_000) idempotency_key: str = Field(min_length=1, max_length=255) + purpose: str = Field(default="cases.casework", min_length=1, max_length=255) status_key: str | None = Field(default=None, min_length=1, max_length=120) title: str | None = Field(default=None, min_length=1, max_length=500) access_mode: Literal["tenant", "restricted"] | None = None @@ -100,6 +109,7 @@ class CaseEvidenceLinkRequest(BaseModel): recorded_at: datetime change_reason: str = Field(min_length=1, max_length=1_000) idempotency_key: str = Field(min_length=1, max_length=255) + purpose: str = Field(default="cases.casework", min_length=1, max_length=255) reference: CaseOwnerReferenceRequest @@ -110,6 +120,7 @@ class CaseEvidenceUnlinkRequest(BaseModel): recorded_at: datetime change_reason: str = Field(min_length=1, max_length=1_000) idempotency_key: str = Field(min_length=1, max_length=255) + purpose: str = Field(default="cases.casework", min_length=1, max_length=255) class CaseDecisionRequest(BaseModel): @@ -123,6 +134,7 @@ class CaseDecisionRequest(BaseModel): conditions: list[str] = Field(default_factory=list, max_length=100) change_reason: str = Field(min_length=1, max_length=1_000) idempotency_key: str = Field(min_length=1, max_length=255) + purpose: str = Field(default="cases.casework", min_length=1, max_length=255) class CaseListResponse(BaseModel): diff --git a/src/govoplan_cases/backend/search_source.py b/src/govoplan_cases/backend/search_source.py index b440344..cfd72fa 100644 --- a/src/govoplan_cases/backend/search_source.py +++ b/src/govoplan_cases/backend/search_source.py @@ -30,6 +30,7 @@ PROVIDER_ID = "cases.cases" RESOURCE_TYPE = "case" READ_SCOPE = "cases:case:read" ADMIN_SCOPE = "cases:case:admin" +SEARCH_ACCESS_PURPOSE = "cases.search" class CasesSearchSource: @@ -118,6 +119,7 @@ class CasesSearchSource: principal, case_id=reference.resource_id, permission="read", + purpose=SEARCH_ACCESS_PURPOSE, ) return decisions @@ -219,7 +221,10 @@ def _document( resource_type=RESOURCE_TYPE, resource_id=row.case_id, title=row.title, - url=f"/cases/{quote(row.case_id, safe='')}", + url=( + f"/cases/{quote(row.case_id, safe='')}" + f"?purpose={quote(SEARCH_ACCESS_PURPOSE, safe='')}" + ), summary=f"{identity.case_number} - {row.status_key}", body=row.search_text[:200_000], keywords=( @@ -279,5 +284,6 @@ __all__ = [ "CasesSearchSource", "PROVIDER_ID", "RESOURCE_TYPE", + "SEARCH_ACCESS_PURPOSE", "create_cases_search_source", ] diff --git a/src/govoplan_cases/backend/service.py b/src/govoplan_cases/backend/service.py index 0e2e778..1f654f2 100644 --- a/src/govoplan_cases/backend/service.py +++ b/src/govoplan_cases/backend/service.py @@ -8,7 +8,7 @@ import json from typing import Any import uuid -from sqlalchemy import and_, exists, func, or_ +from sqlalchemy import func from sqlalchemy.orm import Session from govoplan_core.core.events import ( @@ -32,7 +32,11 @@ from govoplan_cases.backend.db.models import ( CaseTimelineEntry, CaseTypeDefinition, ) -from govoplan_cases.backend.domain import CaseGrant, CaseRecord +from govoplan_cases.backend.domain import ( + DEFAULT_CASE_ACCESS_PURPOSE, + CaseGrant, + CaseRecord, +) from govoplan_cases.backend.service_intake import CaseIntakePlan @@ -222,8 +226,10 @@ def create_case( *, record: CaseRecord, idempotency_key: str, + purpose: str = DEFAULT_CASE_ACCESS_PURPOSE, ) -> CaseRecord: tenant_id = _principal_tenant(principal) + declared_purpose = _access_purpose(purpose) if record.reference.tenant_id != tenant_id: raise CaseStoreError("Case records cannot cross tenants.") if record.revision != 1: @@ -241,6 +247,7 @@ def create_case( principal, case_id=replay.reference.object_id, permission="read", + purpose=declared_purpose, ): raise PermissionError("Case replay access is denied.") return replay @@ -274,6 +281,7 @@ def create_case( idempotency_key=idempotency_key, request_sha256=request_sha256, operation="created", + purpose=declared_purpose, ) return persisted @@ -353,8 +361,10 @@ def update_case( recorded_at: datetime, change_reason: str, idempotency_key: str, + purpose: str = DEFAULT_CASE_ACCESS_PURPOSE, ) -> CaseRecord: tenant_id = _principal_tenant(principal) + declared_purpose = _access_purpose(purpose) current_row = _current_row( session, tenant_id=tenant_id, @@ -363,7 +373,13 @@ def update_case( ) if current_row is None: raise LookupError("Case not found.") - if not can_access_case(session, principal, case_id=case_id, permission="update"): + if not can_access_case( + session, + principal, + case_id=case_id, + permission="update", + purpose=declared_purpose, + ): raise PermissionError("Case update access is denied.") current = _record_from_row(current_row) normalized = _normalized_changes(changes) @@ -383,6 +399,14 @@ def update_case( request_sha256=request_sha256, ) if replay is not None: + if not can_access_case( + session, + principal, + case_id=case_id, + permission="read", + purpose=declared_purpose, + ): + raise PermissionError("Case replay access is denied.") return replay if current.revision != expected_revision: raise CaseStoreError( @@ -461,6 +485,7 @@ def update_case( idempotency_key=idempotency_key, request_sha256=request_sha256, operation="closed" if terminal and not current.closed_at else "updated", + purpose=declared_purpose, ) @@ -470,6 +495,7 @@ def get_case( *, case_id: str, revision: int | None = None, + purpose: str | None = None, ) -> CaseRecord | None: tenant_id = _principal_tenant(principal) query = session.query(CaseRecordRevision).filter( @@ -486,6 +512,7 @@ def get_case( principal, case_id=case_id, permission="read", + purpose=purpose, ): return None return _record_from_row(row) if row is not None else None @@ -498,6 +525,7 @@ def list_cases( query: str = "", status_keys: Sequence[str] | None = None, case_type_keys: Sequence[str] | None = None, + purpose: str | None = None, offset: int = 0, limit: int = 100, ) -> tuple[tuple[CaseRecord, ...], int]: @@ -510,7 +538,13 @@ def list_cases( CaseRecordRevision.tenant_id == tenant_id, CaseRecordRevision.superseded_at.is_(None), ) - statement = _filter_accessible_cases(statement, principal, permission="read") + eligible = _eligible_case_ids( + session, + principal, + permission="read", + purpose=purpose, + ) + statement = statement.filter(CaseRecordRevision.case_id.in_(eligible)) if status_keys: statement = statement.filter( CaseRecordRevision.status_key.in_(tuple(status_keys)) @@ -543,8 +577,15 @@ def case_history( *, case_id: str, limit: int = 100, + purpose: str | None = None, ) -> tuple[CaseRecord, ...]: - if not can_access_case(session, principal, case_id=case_id, permission="read"): + if not can_access_case( + session, + principal, + case_id=case_id, + permission="read", + purpose=purpose, + ): return () if not 1 <= limit <= 200: raise CaseStoreError("Case history limit must be between 1 and 200.") @@ -567,8 +608,15 @@ def case_timeline( *, case_id: str, limit: int = 200, + purpose: str | None = None, ) -> tuple[dict[str, object], ...]: - if not can_access_case(session, principal, case_id=case_id, permission="read"): + if not can_access_case( + session, + principal, + case_id=case_id, + permission="read", + purpose=purpose, + ): return () if not 1 <= limit <= 500: raise CaseStoreError("Case timeline limit must be between 1 and 500.") @@ -595,10 +643,21 @@ class SqlCaseRegistry: if reference.tenant_id != _principal_tenant(principal): raise InstitutionalContextError("Case lookup cannot cross tenants.") revision = int(reference.version) if reference.version else None - return get_case(_session(session), principal, case_id=reference.object_id, revision=revision) + return get_case( + _session(session), + principal, + case_id=reference.object_id, + revision=revision, + purpose=DEFAULT_CASE_ACCESS_PURPOSE, + ) def list_cases(self, session: object, principal: object, *, limit: int = 100) -> Sequence[CaseRecord]: - items, _total = list_cases(_session(session), principal, limit=limit) + items, _total = list_cases( + _session(session), + principal, + limit=limit, + purpose=DEFAULT_CASE_ACCESS_PURPOSE, + ) return items @@ -608,6 +667,7 @@ def can_access_case( *, case_id: str, permission: str = "read", + purpose: str | None = None, ) -> bool: if permission not in {"read", "update", "share", "admin"}: raise CaseStoreError("Unsupported case access permission.") @@ -620,87 +680,86 @@ def can_access_case( ) if current is None: return False - if _has_scope(principal, "cases:case:admin"): - return True - identity = _identity(session, tenant_id=tenant_id, case_id=case_id) - if identity is not None and identity.created_by in _principal_actor_ids(principal): - return True if current.access_mode == "tenant": return True + if current.access_mode != "restricted": + return False + declared_purpose = str(purpose or "").strip() + if not declared_purpose: + return False subjects = _principal_subjects(principal) if not subjects: return False - clauses = [ - and_( - CaseAccessGrant.subject_kind == kind, - CaseAccessGrant.subject_id == subject_id, - ) - for kind, subject_id in subjects - ] grants = ( session.query(CaseAccessGrant) .filter( CaseAccessGrant.tenant_id == tenant_id, CaseAccessGrant.case_id == case_id, CaseAccessGrant.active.is_(True), - or_(*clauses), ) .all() ) return any( - _access_permissions_allow(tuple(item.permissions or ()), permission) + (item.subject_kind, item.subject_id) in subjects + and _access_permissions_allow(tuple(item.permissions or ()), permission) + and declared_purpose in tuple(item.allowed_purposes or ()) for item in grants ) -def _filter_accessible_cases(statement, principal: object, *, permission: str): - if _has_scope(principal, "cases:case:admin"): - return statement - conditions = [CaseRecordRevision.access_mode == "tenant"] - actor_ids = _principal_actor_ids(principal) - if actor_ids: - conditions.append( - exists().where( - and_( - CaseIdentity.tenant_id == CaseRecordRevision.tenant_id, - CaseIdentity.case_id == CaseRecordRevision.case_id, - CaseIdentity.created_by.in_(actor_ids), - ) - ) - ) +def _eligible_case_ids( + session: Session, + principal: object, + *, + permission: str, + purpose: str | None, +) -> tuple[str, ...]: + tenant_id = _principal_tenant(principal) + current = session.query( + CaseRecordRevision.case_id, + CaseRecordRevision.access_mode, + ).filter( + CaseRecordRevision.tenant_id == tenant_id, + CaseRecordRevision.superseded_at.is_(None), + ).all() + eligible = { + case_id for case_id, access_mode in current if access_mode == "tenant" + } + declared_purpose = str(purpose or "").strip() + if not declared_purpose: + return tuple(eligible) subjects = _principal_subjects(principal) - if subjects: - subject_clause = or_( - *( - and_( - CaseAccessGrant.subject_kind == kind, - CaseAccessGrant.subject_id == subject_id, - ) - for kind, subject_id in subjects - ) - ) - conditions.append( - exists().where( - and_( - CaseAccessGrant.tenant_id == CaseRecordRevision.tenant_id, - CaseAccessGrant.case_id == CaseRecordRevision.case_id, - CaseAccessGrant.active.is_(True), - subject_clause, - ) - ) - ) - if permission != "read": - raise CaseStoreError("Case list filtering supports read access only.") - return statement.filter(or_(*conditions)) + if not subjects: + return tuple(eligible) + grants = session.query(CaseAccessGrant).filter( + CaseAccessGrant.tenant_id == tenant_id, + CaseAccessGrant.active.is_(True), + ).all() + eligible.update( + grant.case_id + for grant in grants + if (grant.subject_kind, grant.subject_id) in subjects + and _access_permissions_allow(tuple(grant.permissions or ()), permission) + and declared_purpose in tuple(grant.allowed_purposes or ()) + ) + return tuple(eligible) def _sync_access_grants( session: Session, principal: object, record: CaseRecord, + *, + purpose: str, + ensure_custodian: bool, ) -> None: - desired: dict[tuple[str, str, str], tuple[str, ...]] = { - (item.subject_kind, item.subject_id, "explicit"): item.permissions + desired: dict[ + tuple[str, str, str], tuple[tuple[str, ...], tuple[str, ...]] + ] = { + (item.subject_kind, item.subject_id, "explicit"): ( + item.permissions, + item.allowed_purposes, + ) for item in record.access_grants } for reference in record.assignment_refs: @@ -711,8 +770,8 @@ def _sync_access_grants( }: continue desired[(reference.kind, reference.object_id, "assignment")] = ( - "read", - "update", + ("read", "update"), + ("cases.casework", "cases.search", "cases.records"), ) rows = ( session.query(CaseAccessGrant) @@ -725,11 +784,21 @@ def _sync_access_grants( existing = { (item.subject_kind, item.subject_id, item.source): item for item in rows } + if ensure_custodian and record.access_mode == "restricted": + subject = _custodian_subject(principal) + if subject is None: + raise CaseStoreError( + "Restricted case creation requires an attributable custodian." + ) + desired[(subject[0], subject[1], "custodian")] = ( + ("read", "update", "share", "admin"), + (purpose,), + ) for key, row in existing.items(): - if key not in desired: + if key not in desired and row.source != "custodian": row.active = False row.source_revision = record.revision - for key, permissions in desired.items(): + for key, (permissions, allowed_purposes) in desired.items(): row = existing.get(key) if row is None: session.add( @@ -739,6 +808,7 @@ def _sync_access_grants( subject_kind=key[0], subject_id=key[1], permissions=list(permissions), + allowed_purposes=list(allowed_purposes), source=key[2], active=True, source_revision=record.revision, @@ -747,6 +817,7 @@ def _sync_access_grants( ) else: row.permissions = list(permissions) + row.allowed_purposes = list(allowed_purposes) row.active = True row.source_revision = record.revision session.flush() @@ -780,6 +851,7 @@ def _principal_subjects(principal: object) -> tuple[tuple[str, str], ...]: for kind, name in ( ("account", "account_id"), ("identity", "identity_id"), + ("membership", "membership_id"), ("service_account", "service_account_id"), ): value = str(getattr(principal, name, None) or "").strip() @@ -791,15 +863,41 @@ def _principal_subjects(principal: object) -> tuple[tuple[str, str], ...]: ("function", "function_ids"), ("function_assignment", "function_assignment_ids"), ("organization_unit", "organization_unit_ids"), + ("delegation", "delegation_ids"), ): subjects.extend( (kind, str(item)) for item in (getattr(principal, name, ()) or ()) if str(item).strip() ) + for kind, name in ( + ("function_assignment", "acting_assignment_id"), + ("delegation", "acting_delegation_id"), + ("delegation", "delegation_id"), + ): + value = str(getattr(principal, name, None) or "").strip() + if value: + subjects.append((kind, value)) return tuple(dict.fromkeys(subjects)) +def _custodian_subject(principal: object) -> tuple[str, str] | None: + for kind, name in ( + ("account", "account_id"), + ("identity", "identity_id"), + ("membership", "membership_id"), + ("service_account", "service_account_id"), + ): + value = str(getattr(principal, name, None) or "").strip() + if value: + return kind, value + return None + + +def _access_purpose(value: object) -> str: + return _required_text(value, "Case access purpose", maximum=255) + + def _has_scope(principal: object, scope: str) -> bool: method = getattr(principal, "has", None) if callable(method): @@ -820,6 +918,7 @@ def _record_revision( idempotency_key: str, request_sha256: str, operation: str, + purpose: str, ) -> CaseRecord: clean_key = _required_text( idempotency_key, @@ -860,6 +959,7 @@ def _record_revision( summary=f"Case {identity.case_number} {operation}.", occurred_at=record.recorded_at, actor_id=_principal_actor(principal), + purpose=purpose, idempotency_key=clean_key, request_sha256=request_sha256, audit_event_id=event_id, @@ -870,12 +970,22 @@ def _record_revision( "revision": record.revision, "access_mode": record.access_mode, "access_grant_count": len(record.access_grants), + "purpose": purpose, "change_reason": record.change_reason, }, ) session.add_all((row, timeline)) session.flush() - _sync_access_grants(session, principal, record) + _sync_access_grants( + session, + principal, + record, + purpose=purpose, + ensure_custodian=( + record.access_mode == "restricted" + and (current is None or current.access_mode != "restricted") + ), + ) emit_platform_event( session, PlatformEvent( @@ -1108,6 +1218,7 @@ def _timeline_payload(row: CaseTimelineEntry) -> dict[str, object]: "summary": row.summary, "occurred_at": _datetime_text(row.occurred_at), "actor_id": row.actor_id, + "purpose": row.purpose, "audit_event_id": row.audit_event_id, "payload": dict(row.payload or {}), } diff --git a/tests/test_case_lifecycle.py b/tests/test_case_lifecycle.py index 1b88fa8..3935bfc 100644 --- a/tests/test_case_lifecycle.py +++ b/tests/test_case_lifecycle.py @@ -324,13 +324,66 @@ class CaseLifecycleTests(unittest.TestCase): outsider = Principal(account_id="account-2") self.assertIsNone(get_case(self.session, outsider, case_id="case-1")) - self.assertEqual(0, list_cases(self.session, outsider)[1]) + self.assertEqual( + 0, + list_cases( + self.session, + outsider, + purpose="cases.casework", + )[1], + ) self.assertEqual((), case_history(self.session, outsider, case_id="case-1")) self.assertEqual((), case_timeline(self.session, outsider, case_id="case-1")) reader = Principal(account_id="account-3", group_ids=("reviewers",)) - self.assertIsNotNone(get_case(self.session, reader, case_id="case-1")) - self.assertEqual(1, list_cases(self.session, reader)[1]) + self.assertIsNone(get_case(self.session, reader, case_id="case-1")) + self.assertIsNone( + get_case( + self.session, + reader, + case_id="case-1", + purpose="cases.unrelated", + ) + ) + self.assertIsNotNone( + get_case( + self.session, + reader, + case_id="case-1", + purpose="cases.casework", + ) + ) + administrator = Principal( + account_id="account-6", + scopes=frozenset({"cases:case:admin"}), + ) + self.assertIsNone( + get_case( + self.session, + administrator, + case_id="case-1", + purpose="cases.casework", + ) + ) + self.assertEqual( + 1, + list_cases( + self.session, + reader, + purpose="cases.casework", + )[1], + ) + self.assertEqual( + 1, + len( + case_history( + self.session, + reader, + case_id="case-1", + purpose="cases.casework", + ) + ), + ) with self.assertRaises(PermissionError): update_case( self.session, @@ -396,9 +449,56 @@ class CaseLifecycleTests(unittest.TestCase): self.session.commit() self.assertEqual(3, shared.revision) self.assertIsNotNone( - get_case(self.session, Principal(account_id="account-5"), case_id="case-1") + get_case( + self.session, + Principal(account_id="account-5"), + case_id="case-1", + purpose="cases.casework", + ) + ) + self.assertEqual( + 3, + len( + case_history( + self.session, + self.principal, + case_id="case-1", + purpose="cases.casework", + ) + ), + ) + + revoked = update_case( + self.session, + self.principal, + case_id="case-1", + expected_revision=3, + changes={"access_grants": []}, + recorded_at=NOW + timedelta(minutes=3), + change_reason="Removed direct collaboration access.", + idempotency_key="case-share-revoke", + purpose="cases.casework", + ) + self.session.commit() + self.assertEqual(4, revoked.revision) + self.assertIsNone( + get_case( + self.session, + Principal(account_id="account-5"), + case_id="case-1", + revision=2, + purpose="cases.casework", + ) + ) + self.assertEqual( + "cases.casework", + case_timeline( + self.session, + self.principal, + case_id="case-1", + purpose="cases.casework", + )[0]["purpose"], ) - self.assertEqual(3, len(case_history(self.session, self.principal, case_id="case-1"))) def test_malformed_access_grant_is_rejected(self) -> None: create_case( diff --git a/tests/test_dsar_provider.py b/tests/test_dsar_provider.py index 27a6e4b..176a6fb 100644 --- a/tests/test_dsar_provider.py +++ b/tests/test_dsar_provider.py @@ -255,6 +255,10 @@ class CasesDsarProviderTests(unittest.TestCase): self.assertEqual("cases_access_grant", account_records[0].resource_type) self.assertFalse(account_records[0].immutable_evidence) self.assertEqual("account-subject", account_records[0].data["subject_id"]) + self.assertEqual( + ["cases.casework"], + account_records[0].data["allowed_purposes"], + ) identity_records = self.provider.search_subject( self.session, @@ -308,7 +312,11 @@ class CasesDsarProviderTests(unittest.TestCase): self.assertTrue( all( item.resource_type - in {"cases_operator_attribution", "cases_timeline_event"} + in { + "cases_access_grant", + "cases_operator_attribution", + "cases_timeline_event", + } for item in records ) ) diff --git a/tests/test_interface_documentation_contract.py b/tests/test_interface_documentation_contract.py index 8fae9b3..e6cd069 100644 --- a/tests/test_interface_documentation_contract.py +++ b/tests/test_interface_documentation_contract.py @@ -67,6 +67,20 @@ class CasesInterfaceDocumentationContractTests(unittest.TestCase): owner_links.metadata["consequence_classes"], ) + def test_information_governance_claims_are_bounded_and_documented(self) -> None: + manifest = get_manifest() + governance = manifest.information_governance + self.assertEqual("enforced", governance.temporal_browsing.adoption) + self.assertEqual("enforced", governance.purpose_aware_access.adoption) + self.assertEqual("enforced", governance.institutional_context.adoption) + self.assertEqual("contract_only", governance.retention.adoption) + self.assertIn("legal holds", governance.retention.limitation or "") + self.assertTrue(governance.current_authorization_for_historical_reads) + topics = {topic.id: topic for topic in manifest.documentation} + purpose = topics["cases.governance.purpose-bound-access"] + self.assertIn("cases.field.access-purpose", purpose.metadata["help_contexts"]) + self.assertIn("cases.field.allowed-purposes", purpose.metadata["help_contexts"]) + def test_webui_uses_shared_help_guard_and_confirmation_components(self) -> None: list_page = (REPO_ROOT / "webui/src/features/cases/CasesPage.tsx").read_text( encoding="utf-8" diff --git a/tests/test_migrations.py b/tests/test_migrations.py index 28c7e5c..1eb2bf6 100644 --- a/tests/test_migrations.py +++ b/tests/test_migrations.py @@ -40,9 +40,23 @@ class CasesMigrationTests(unittest.TestCase): for item in inspector.get_columns("case_record_revisions") }, ) + self.assertIn( + "allowed_purposes", + { + item["name"] + for item in inspector.get_columns("case_access_grants") + }, + ) + self.assertIn( + "purpose", + { + item["name"] + for item in inspector.get_columns("case_timeline_entries") + }, + ) with engine.connect() as connection: self.assertIn( - "f6d3a8b1c4e7", + "a7c4e2f9b1d6", set(MigrationContext.configure(connection).get_current_heads()), ) finally: diff --git a/tests/test_record_source.py b/tests/test_record_source.py index aa051ee..7ac513c 100644 --- a/tests/test_record_source.py +++ b/tests/test_record_source.py @@ -75,7 +75,7 @@ class CasesRecordSourceTests(unittest.TestCase): def test_resolves_exact_currently_authorized_case_revision(self) -> None: with patch( "govoplan_cases.backend.record_source.can_access_case", return_value=True - ): + ) as can_access: result = CasesRecordSource().resolve( self.session, Principal(), @@ -83,9 +83,20 @@ class CasesRecordSourceTests(unittest.TestCase): purpose="preserve decision basis", ) + can_access.assert_called_once_with( + self.session, + unittest.mock.ANY, + case_id="case-1", + permission="read", + purpose="preserve decision basis", + ) self.assertEqual("2026/C-1 - Permit application", result.label) self.assertEqual(64, len(result.content_sha256 or "")) self.assertEqual("review", result.metadata["status_key"]) + self.assertEqual( + "/cases/case-1?purpose=preserve%20decision%20basis", + result.launch_url, + ) def test_object_access_is_rechecked_and_fails_closed(self) -> None: with ( diff --git a/tests/test_search_source.py b/tests/test_search_source.py index 78a0b24..afa7f38 100644 --- a/tests/test_search_source.py +++ b/tests/test_search_source.py @@ -28,8 +28,12 @@ from govoplan_cases.backend.db.models import ( CaseTimelineEntry, CaseTypeDefinition, ) -from govoplan_cases.backend.domain import CaseRecord -from govoplan_cases.backend.search_source import CasesSearchSource, PROVIDER_ID +from govoplan_cases.backend.domain import CaseGrant, CaseRecord +from govoplan_cases.backend.search_source import ( + SEARCH_ACCESS_PURPOSE, + CasesSearchSource, + PROVIDER_ID, +) from govoplan_cases.backend.service import ( create_case, upsert_case_status, @@ -77,6 +81,15 @@ class CasesSearchSourceTests(unittest.TestCase): case_type_key="permit", status_key="review", title="Permit application", + access_mode="restricted", + access_grants=( + CaseGrant( + "account", + "account-1", + ("read",), + (SEARCH_ACCESS_PURPOSE,), + ), + ), context=GovernedContextEnvelope( tenant_id="tenant-1", temporal=TemporalRevision( @@ -112,6 +125,7 @@ class CasesSearchSourceTests(unittest.TestCase): ) self.assertEqual(("case-1",), tuple(item.resource_id for item in page.documents)) self.assertEqual("PERMIT-1", page.documents[0].metadata["case_number"]) + self.assertIn("purpose=cases.search", page.documents[0].url) reference = SearchResourceReference( tenant_id="tenant-1", module_id="cases", diff --git a/webui/package.json b/webui/package.json index 25083ae..2c5f119 100644 --- a/webui/package.json +++ b/webui/package.json @@ -1,6 +1,6 @@ { "name": "@govoplan/cases-webui", - "version": "0.1.22", + "version": "0.1.23", "private": true, "type": "module", "main": "src/index.ts", diff --git a/webui/src/api/cases.ts b/webui/src/api/cases.ts index 0de8e6a..3071454 100644 --- a/webui/src/api/cases.ts +++ b/webui/src/api/cases.ts @@ -59,11 +59,14 @@ export type CaseRecord = { }; export type CaseGrant = { - subject_kind: "account" | "identity" | "group" | "role" | "function" | "function_assignment" | "organization_unit" | "service_account"; + subject_kind: "account" | "identity" | "membership" | "group" | "role" | "function" | "function_assignment" | "organization_unit" | "service_account" | "delegation"; subject_id: string; permissions: Array<"read" | "update" | "share" | "admin">; + allowed_purposes: string[]; }; +export const DEFAULT_CASE_ACCESS_PURPOSE = "cases.casework"; + export type CaseStatusDefinition = { status_key: string; label: string; @@ -101,6 +104,7 @@ export type CaseTimelineEntry = { event_type: string; case_revision: number; summary: string; + purpose: string; actor_id?: string | null; occurred_at: string; audit_event_id?: string | null; @@ -140,6 +144,7 @@ export function listCases( query?: string; statuses?: string[]; caseTypes?: string[]; + purpose?: string; offset?: number; limit?: number; }, @@ -149,6 +154,7 @@ export function listCases( query: options.query, status_key: options.statuses, case_type_key: options.caseTypes, + purpose: options.purpose, offset: options.offset, limit: options.limit }), { signal }); @@ -157,9 +163,10 @@ export function listCases( export function getCase( settings: ApiSettings, caseId: string, + purpose: string, signal?: AbortSignal ): Promise { - return apiFetch(settings, `/api/v1/cases/${encodeURIComponent(caseId)}`, { signal }); + return apiFetch(settings, apiPath(`/api/v1/cases/${encodeURIComponent(caseId)}`, { purpose }), { signal }); } export function listCaseCatalog( @@ -172,27 +179,30 @@ export function listCaseCatalog( export function caseHistory( settings: ApiSettings, caseId: string, + purpose: string, signal?: AbortSignal ): Promise<{ revisions: CaseRecord[] }> { - return apiFetch(settings, `/api/v1/cases/${encodeURIComponent(caseId)}/history`, { signal }); + return apiFetch(settings, apiPath(`/api/v1/cases/${encodeURIComponent(caseId)}/history`, { purpose }), { signal }); } export function caseTimeline( settings: ApiSettings, caseId: string, + purpose: string, signal?: AbortSignal ): Promise<{ entries: CaseTimelineEntry[] }> { - return apiFetch(settings, `/api/v1/cases/${encodeURIComponent(caseId)}/timeline`, { signal }); + return apiFetch(settings, apiPath(`/api/v1/cases/${encodeURIComponent(caseId)}/timeline`, { purpose }), { signal }); } export function listCaseDecisions( settings: ApiSettings, caseId: string, + purpose: string, signal?: AbortSignal ): Promise<{ decisions: FormalDecision[] }> { return apiFetch( settings, - `/api/v1/cases/${encodeURIComponent(caseId)}/decisions`, + apiPath(`/api/v1/cases/${encodeURIComponent(caseId)}/decisions`, { purpose }), { signal } ); } @@ -209,6 +219,7 @@ export function recordCaseDecision( conditions: string[]; change_reason: string; idempotency_key: string; + purpose: string; } ): Promise { return apiFetch( @@ -229,6 +240,7 @@ export function updateCase( recorded_at: string; change_reason: string; idempotency_key: string; + purpose: string; title?: string; status_key?: string; access_mode?: "tenant" | "restricted"; @@ -249,6 +261,7 @@ export function linkCaseEvidence( recorded_at: string; change_reason: string; idempotency_key: string; + purpose: string; reference: { owner_module: string; kind: string; @@ -275,6 +288,7 @@ export function unlinkCaseEvidence( recorded_at: string; change_reason: string; idempotency_key: string; + purpose: string; } ): Promise { return apiFetch( @@ -287,11 +301,12 @@ export function unlinkCaseEvidence( export function caseShareTargetProvider( settings: ApiSettings, caseId: string, - targetType: "user" | "group" + targetType: "user" | "group", + purpose: string ): ReferenceOptionProvider { return apiReferenceOptionProvider( settings, `/api/v1/cases/${encodeURIComponent(caseId)}/share-target-options`, - { target_type: targetType } + { target_type: targetType, purpose } ); } diff --git a/webui/src/features/cases/CaseDecisionDialog.tsx b/webui/src/features/cases/CaseDecisionDialog.tsx index 13f290e..76f42a8 100644 --- a/webui/src/features/cases/CaseDecisionDialog.tsx +++ b/webui/src/features/cases/CaseDecisionDialog.tsx @@ -21,12 +21,14 @@ import { CASES_FIELDS_DOCUMENTATION } from "./interfacePatterns"; export default function CaseDecisionDialog({ settings, record, + purpose, open, onClose, onSaved }: { settings: ApiSettings; record: CaseRecord; + purpose: string; open: boolean; onClose: () => void; onSaved: (result: CaseDecisionResult) => void; @@ -82,7 +84,8 @@ export default function CaseDecisionDialog({ reasoning: reasoning.trim(), conditions: conditions.split("\n").map((item) => item.trim()).filter(Boolean), change_reason: changeReason.trim(), - idempotency_key: idempotencyKey.current + idempotency_key: idempotencyKey.current, + purpose }); setConfirmOpen(false); onSaved(result); diff --git a/webui/src/features/cases/CaseDetailPage.tsx b/webui/src/features/cases/CaseDetailPage.tsx index 4c42a9d..388817e 100644 --- a/webui/src/features/cases/CaseDetailPage.tsx +++ b/webui/src/features/cases/CaseDetailPage.tsx @@ -1,6 +1,6 @@ import { Archive, ArrowLeft, ExternalLink, Save, Scale, Share2, Unlink } from "lucide-react"; import { useCallback, useEffect, useMemo, useRef, useState } from "react"; -import { useParams } from "react-router"; +import { useParams, useSearchParams } from "react-router"; import { ActionToolbar, ActionBlockerHint, Button, @@ -22,6 +22,7 @@ import { ActionToolbar, type QuickAccessResult } from "@govoplan/core-webui"; import { + DEFAULT_CASE_ACCESS_PURPOSE, caseHistory, caseTimeline, getCase, @@ -48,6 +49,8 @@ import { export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) { const { caseId = "" } = useParams(); + const [searchParams] = useSearchParams(); + const accessPurpose = searchParams.get("purpose")?.trim() || DEFAULT_CASE_ACCESS_PURPOSE; const navigate = useGuardedNavigate(); const [record, setRecord] = useState(null); const [catalog, setCatalog] = useState({ statuses: [], types: [] }); @@ -92,20 +95,20 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) tenantId: record.reference.tenant_id, label: `${record.case_number} · ${record.title}`, version: record.reference.version ?? String(record.revision), - path: `/cases/${encodeURIComponent(record.reference.object_id)}` - } : null, [record]); + path: `/cases/${encodeURIComponent(record.reference.object_id)}?purpose=${encodeURIComponent(accessPurpose)}` + } : null, [accessPurpose, record]); useRegisterActiveObject(activeCase); const load = useCallback((signal?: AbortSignal) => { setLoading(true); setError(""); return Promise.all([ - getCase(settings, caseId, signal), + getCase(settings, caseId, accessPurpose, signal), listCaseCatalog(settings, signal), - caseHistory(settings, caseId, signal), - caseTimeline(settings, caseId, signal), + caseHistory(settings, caseId, accessPurpose, signal), + caseTimeline(settings, caseId, accessPurpose, signal), canReadDecisions - ? listCaseDecisions(settings, caseId, signal) + ? listCaseDecisions(settings, caseId, accessPurpose, signal) : Promise.resolve({ decisions: [] as FormalDecision[] }) ]). then(([nextRecord, nextCatalog, nextHistory, nextTimeline, nextDecisions]) => { @@ -119,7 +122,7 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) setChangeReason(""); }). finally(() => setLoading(false)); - }, [canReadDecisions, caseId, settings]); + }, [accessPurpose, canReadDecisions, caseId, settings]); useEffect(() => { const controller = new AbortController(); @@ -179,6 +182,7 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) recorded_at: new Date().toISOString(), change_reason: `Linked ${reference.ownerModule}.${reference.kind} through Quick Access.`, idempotency_key: crypto.randomUUID(), + purpose: accessPurpose, reference: { owner_module: reference.ownerModule, kind: reference.kind, @@ -203,7 +207,7 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) QUICK_ACCESS_RESULT_EVENT, receiveReference ); - }, [canUpdate, caseId, draftDirty, load, record, settings]); + }, [accessPurpose, canUpdate, caseId, draftDirty, load, record, settings]); function discardDraft() { if (!record) return; @@ -222,6 +226,7 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) recorded_at: new Date().toISOString(), change_reason: changeReason.trim(), idempotency_key: idempotencyKey.current, + purpose: accessPurpose, ...(title.trim() !== record.title ? { title: title.trim() } : {}), ...(status !== record.status_key ? { status_key: status } : {}) }); @@ -260,7 +265,8 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) expected_revision: record.revision, recorded_at: new Date().toISOString(), change_reason: `Unlinked ${evidence.owner_module} reference from the Case.`, - idempotency_key: crypto.randomUUID() + idempotency_key: crypto.randomUUID(), + purpose: accessPurpose } ); setRecord(saved); @@ -296,7 +302,7 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext)
- @@ -325,6 +331,7 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) icon={} disabledReason={!canShare ? CASES_I18N.shareReason : undefined} onClick={() => setShareOpen(true)} + helpContextId="cases.detail.access" />
) : null} @@ -404,6 +411,8 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) + + @@ -444,6 +453,7 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext)
  • {humanize(entry.event_type)} {entry.summary} + {entry.purpose}
    • )} @@ -470,6 +480,7 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) setShareOpen(false)} onSaved={(saved) => { @@ -484,6 +495,7 @@ export default function CaseDetailPage({ settings, auth }: PlatformRouteContext) setDecisionOpen(false)} onSaved={(result) => { diff --git a/webui/src/features/cases/CaseShareDialog.tsx b/webui/src/features/cases/CaseShareDialog.tsx index 4cdad0b..8023439 100644 --- a/webui/src/features/cases/CaseShareDialog.tsx +++ b/webui/src/features/cases/CaseShareDialog.tsx @@ -33,12 +33,14 @@ type Permission = CaseGrant["permissions"][number]; export default function CaseShareDialog({ settings, record, + purpose, open, onClose, onSaved }: { settings: ApiSettings; record: CaseRecord; + purpose: string; open: boolean; onClose: () => void; onSaved: (record: CaseRecord) => void; @@ -48,6 +50,7 @@ export default function CaseShareDialog({ const [targetType, setTargetType] = useState("user"); const [targetId, setTargetId] = useState(""); const [permission, setPermission] = useState("read"); + const [allowedPurposes, setAllowedPurposes] = useState(purpose); const [changeReason, setChangeReason] = useState(""); const [busy, setBusy] = useState(false); const [error, setError] = useState(""); @@ -55,8 +58,8 @@ export default function CaseShareDialog({ const idempotencyKey = useRef(crypto.randomUUID()); const { requestDiscard } = useUnsavedChanges(); const targetProvider = useMemo( - () => caseShareTargetProvider(settings, record.reference.object_id, targetType), - [record.reference.object_id, settings, targetType] + () => caseShareTargetProvider(settings, record.reference.object_id, targetType, purpose), + [purpose, record.reference.object_id, settings, targetType] ); useEffect(() => { @@ -66,11 +69,12 @@ export default function CaseShareDialog({ setTargetType("user"); setTargetId(""); setPermission("read"); + setAllowedPurposes(purpose); setChangeReason(""); setError(""); setConfirmOpen(false); idempotencyKey.current = crypto.randomUUID(); - }, [open, record]); + }, [open, purpose, record]); const changed = restricted !== (record.access_mode === "restricted") || JSON.stringify(grants) !== JSON.stringify(record.access_grants); @@ -82,13 +86,15 @@ export default function CaseShareDialog({ setTargetType("user"); setTargetId(""); setPermission("read"); + setAllowedPurposes(purpose); setChangeReason(""); setError(""); } function addGrant() { const subjectId = targetId.trim(); - if (!subjectId) return; + const purposes = splitPurposes(allowedPurposes); + if (!subjectId || purposes.length === 0) return; const subjectKind = targetType === "user" ? "account" : "group"; setGrants((current) => [ ...current.filter( @@ -97,7 +103,8 @@ export default function CaseShareDialog({ { subject_kind: subjectKind, subject_id: subjectId, - permissions: [permission] + permissions: [permission], + allowed_purposes: purposes } ]); setTargetId(""); @@ -113,6 +120,7 @@ export default function CaseShareDialog({ recorded_at: new Date().toISOString(), change_reason: changeReason.trim(), idempotency_key: idempotencyKey.current, + purpose, access_mode: restricted ? "restricted" : "tenant", access_grants: grants }); @@ -169,6 +177,7 @@ export default function CaseShareDialog({ closeDisabled={busy} portal className="case-share-dialog" + helpContextId="cases.detail.access" footer={ <> @@ -176,6 +185,7 @@ export default function CaseShareDialog({ variant="primary" disabledReason={saveDisabledReason} onClick={() => setConfirmOpen(true)} + helpContextId="cases.detail.access" > {busy ? "Saving" : "Save access"} @@ -196,9 +206,9 @@ export default function CaseShareDialog({ onChange={setRestricted} />

    - Tenant cases follow the Cases read permission. Restricted cases are visible only to - their creator, case administrators, assigned functions or units, and the explicit - grants below. + Tenant cases follow the Cases read permission. Restricted cases require a current + grant whose permission and exact allowed purpose both match the attempted action. + The creating account receives a purpose-bound custodian grant.

    @@ -237,11 +247,19 @@ export default function CaseShareDialog({ + + setAllowedPurposes(event.target.value)} + placeholder="cases.casework, cases.search" + /> + } variant="primary" - disabledReason={busy ? CASES_I18N.saving : !targetId.trim() ? CASES_I18N.targetRequired : undefined} + disabledReason={busy ? CASES_I18N.saving : !targetId.trim() ? CASES_I18N.targetRequired : splitPurposes(allowedPurposes).length === 0 ? "Declare at least one allowed purpose." : undefined} onClick={addGrant} />
    @@ -273,11 +291,22 @@ export default function CaseShareDialog({ + setGrants((current) => current.map((item) => + item === grant + ? { ...item, allowed_purposes: splitPurposes(event.target.value) } + : item + ))} + /> } variant="danger" disabled={busy} + helpContextId="cases.detail.access" onClick={() => setGrants((current) => current.filter((item) => item !== grant))} /> @@ -317,3 +346,7 @@ export default function CaseShareDialog({ function humanize(value: string): string { return value.replace(/[_:.-]+/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase()); } + +function splitPurposes(value: string): string[] { + return Array.from(new Set(value.split(/[\n,]+/).map((item) => item.trim()).filter(Boolean))); +} diff --git a/webui/src/features/cases/CasesPage.tsx b/webui/src/features/cases/CasesPage.tsx index 63bd46f..4d58690 100644 --- a/webui/src/features/cases/CasesPage.tsx +++ b/webui/src/features/cases/CasesPage.tsx @@ -1,5 +1,6 @@ import { Search } from "lucide-react"; import { useEffect, useMemo, useState, type FormEvent } from "react"; +import { useSearchParams } from "react-router"; import { Button, DocumentationHelpLink, DismissibleAlert, @@ -18,6 +19,7 @@ import { Button, type PlatformRouteContext } from "@govoplan/core-webui"; import { + DEFAULT_CASE_ACCESS_PURPOSE, listCaseCatalog, listCases, type CaseCatalog, @@ -28,8 +30,12 @@ import { CASES_DOCUMENTATION, CASES_I18N } from "./interfacePatterns"; export default function CasesPage({ settings }: PlatformRouteContext) { const navigate = useGuardedNavigate(); + const [searchParams] = useSearchParams(); + const initialPurpose = searchParams.get("purpose")?.trim() || DEFAULT_CASE_ACCESS_PURPOSE; const [query, setQuery] = useState(""); const [submittedQuery, setSubmittedQuery] = useState(""); + const [purpose, setPurpose] = useState(initialPurpose); + const [submittedPurpose, setSubmittedPurpose] = useState(initialPurpose); const [status, setStatus] = useState(""); const [cases, setCases] = useState([]); const [catalog, setCatalog] = useState({ statuses: [], types: [] }); @@ -46,6 +52,7 @@ export default function CasesPage({ settings }: PlatformRouteContext) { listCases(settings, { query: submittedQuery, statuses: status ? [status] : undefined, + purpose: submittedPurpose, limit: 200 }, controller.signal), listCaseCatalog(settings, controller.signal) @@ -62,7 +69,7 @@ export default function CasesPage({ settings }: PlatformRouteContext) { }). finally(() => setLoading(false)); return () => controller.abort(); - }, [reloadKey, settings, status, submittedQuery]); + }, [reloadKey, settings, status, submittedPurpose, submittedQuery]); const statusLabels = useMemo( () => new Map(catalog.statuses.map((item) => [item.status_key, item])), @@ -76,6 +83,7 @@ export default function CasesPage({ settings }: PlatformRouteContext) { function submit(event: FormEvent) { event.preventDefault(); setSubmittedQuery(query.trim()); + setSubmittedPurpose(purpose.trim()); } return ( @@ -96,6 +104,14 @@ export default function CasesPage({ settings }: PlatformRouteContext) { aria-label="Search cases" placeholder="Search cases" /> + setPurpose(event.target.value)} + aria-label="Case access purpose" + placeholder="Case access purpose" + data-help-context-id="cases.field.access-purpose" + required + />