GovOPlaN/govoplan-organizations
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(organizations): add governed DSAR coverage

Browse Source
This commit is contained in:
zemion
2026-08-21 01:26:05 +02:00
parent d1e3b1cbfd
commit aa4ed0b7c1
4 changed files with 787 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/govoplan_organizations/backend/dsar_provider.py
+306
View File
@@ -0,0 +1,306 @@
from __future__ import annotations
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from datetime import datetime, timezone
from sqlalchemy import or_
from sqlalchemy.orm import Session
from govoplan_core.core.dsar import (
DsarErasureActionRef,
DsarExecutionResultRef,
DsarRecordRef,
DsarSubjectRef,
dsar_capability_name,
)
from govoplan_organizations.backend.db.models import (
OrganizationModelInstantiation,
OrganizationModelUpgrade,
)
ORGANIZATIONS_DSAR_CAPABILITY = dsar_capability_name("organizations")
_MAX_RECORDS = 5_000
@dataclass(frozen=True, slots=True)
class _SubjectSelectors:
account_id: str | None
instantiation_id: str | None
upgrade_id: str | None
class OrganizationsDsarProvider:
provider_id = "organizations"
module_id = "organizations"
def search_subject(
self,
session: object,
*,
tenant_id: str,
subject: DsarSubjectRef,
) -> Sequence[DsarRecordRef]:
db = _session(session)
selectors = _subject_selectors(subject)
if selectors is None or not selectors.account_id:
return ()
records: list[DsarRecordRef] = []
instantiation_query = db.query(OrganizationModelInstantiation).filter(
OrganizationModelInstantiation.tenant_id == tenant_id,
OrganizationModelInstantiation.instantiated_by_account_id
== selectors.account_id,
)
if selectors.instantiation_id:
instantiation_query = instantiation_query.filter(
OrganizationModelInstantiation.id == selectors.instantiation_id
)
for row in _bounded_rows(
instantiation_query.order_by(OrganizationModelInstantiation.id)
):
records.append(
_record(
"organizations_model_instantiation",
row.id,
"organization_model_governance_evidence",
"Organization model instantiation attribution",
{
"match_fields": ["instantiated_by_account_id"],
"template_id": row.template_id,
"template_version_id": row.template_version_id,
"source_definition_sha256": row.source_definition_sha256,
"status": row.status,
},
observed_at=row.updated_at,
retention_reason=(
"Model-instantiation attribution is retained to explain which "
"reviewed institutional model became tenant-owned."
),
)
)
upgrade_query = db.query(OrganizationModelUpgrade).filter(
OrganizationModelUpgrade.tenant_id == tenant_id,
or_(
OrganizationModelUpgrade.requested_by_account_id
== selectors.account_id,
OrganizationModelUpgrade.applied_by_account_id == selectors.account_id,
OrganizationModelUpgrade.cancelled_by_account_id
== selectors.account_id,
),
)
if selectors.upgrade_id:
upgrade_query = upgrade_query.filter(
OrganizationModelUpgrade.id == selectors.upgrade_id
)
for row in _bounded_rows(upgrade_query.order_by(OrganizationModelUpgrade.id)):
records.append(
_record(
"organizations_model_upgrade",
row.id,
"organization_model_governance_evidence",
"Organization model upgrade attribution",
{
"match_fields": _actor_match_fields(
row,
selectors.account_id,
(
"requested_by_account_id",
"applied_by_account_id",
"cancelled_by_account_id",
),
),
"template_id": row.template_id,
"source_instantiation_id": row.source_instantiation_id,
"source_template_version_id": (row.source_template_version_id),
"target_template_version_id": (row.target_template_version_id),
"status": row.status,
"revision": row.revision,
"base_definition_sha256": row.base_definition_sha256,
"local_definition_sha256": row.local_definition_sha256,
"target_definition_sha256": row.target_definition_sha256,
"applied_at": _iso(row.applied_at),
"cancelled_at": _iso(row.cancelled_at),
},
observed_at=row.updated_at,
retention_reason=(
"Upgrade request, application, and cancellation attribution "
"is retained as organization-model change evidence."
),
)
)
if len(records) > _MAX_RECORDS:
raise ValueError(
"Organizations DSAR result limit exceeded; narrow the subject selectors."
)
return tuple(records)
def plan_erasure(
self,
session: object,
*,
tenant_id: str,
subject: DsarSubjectRef,
records: Sequence[DsarRecordRef],
) -> Sequence[DsarErasureActionRef]:
del tenant_id
_session(session)
if _subject_selectors(subject) is None:
raise ValueError("Organizations DSAR subject selectors conflict.")
actions: list[DsarErasureActionRef] = []
for record in records:
_validate_record(record)
actions.append(
DsarErasureActionRef(
action_id=(
f"organizations:retain:{record.resource_type}:"
f"{record.resource_id}"
),
provider_id=self.provider_id,
module_id=self.module_id,
kind="retain",
resource_type=record.resource_type,
resource_id=record.resource_id,
title=f"Retain {record.title}",
rationale=record.retention_reason
or "Organization-model governance evidence must be retained.",
executable=False,
)
)
return tuple(actions)
def execute_erasure(
self,
session: object,
*,
tenant_id: str,
subject: DsarSubjectRef,
actions: Sequence[DsarErasureActionRef],
request_id: str,
) -> Sequence[DsarExecutionResultRef]:
del tenant_id
_session(session)
if _subject_selectors(subject) is None:
raise ValueError("Organizations DSAR subject selectors conflict.")
results: list[DsarExecutionResultRef] = []
for action in actions:
_validate_action(action)
if action.executable:
raise ValueError(
"Organizations DSAR does not publish executable erasure actions."
)
results.append(
DsarExecutionResultRef(
action_id=action.action_id,
status="blocked",
summary=(
"Organization-model change attribution is retained as "
"institutional governance evidence."
),
evidence={"request_id": request_id},
)
)
return tuple(results)
def _subject_selectors(subject: DsarSubjectRef) -> _SubjectSelectors | None:
account_ids = {
value
for item in (
subject.account_id,
subject.external_references.get("organizations.account"),
subject.external_references.get("access.account"),
)
if (value := _normalized_id(item))
}
if len(account_ids) > 1:
return None
return _SubjectSelectors(
account_id=next(iter(account_ids), None),
instantiation_id=_normalized_id(
subject.external_references.get("organizations.model_instantiation")
),
upgrade_id=_normalized_id(
subject.external_references.get("organizations.model_upgrade")
),
)
def _actor_match_fields(
row: object,
account_id: str,
fields: Sequence[str],
) -> list[str]:
return [field for field in fields if getattr(row, field, None) == account_id]
def _validate_record(record: DsarRecordRef) -> None:
if record.provider_id != "organizations" or record.module_id != "organizations":
raise ValueError("Organizations DSAR received a foreign provider record.")
def _validate_action(action: DsarErasureActionRef) -> None:
if action.provider_id != "organizations" or action.module_id != "organizations":
raise ValueError("Organizations DSAR received a foreign provider action.")
def _record(
resource_type: str,
resource_id: str,
category: str,
title: str,
data: Mapping[str, object],
*,
observed_at: datetime | None,
retention_reason: str,
) -> DsarRecordRef:
return DsarRecordRef(
provider_id="organizations",
module_id="organizations",
resource_type=resource_type,
resource_id=resource_id,
category=category,
title=title,
data=data,
observed_at=observed_at,
immutable_evidence=True,
retention_reason=retention_reason,
source_path="/admin?section=tenant-organization-settings",
)
def _session(value: object) -> Session:
if not isinstance(value, Session):
raise TypeError("Organizations DSAR provider requires a SQLAlchemy session.")
return value
def _bounded_rows(query: object) -> list[object]:
rows = query.limit(_MAX_RECORDS + 1).all() # type: ignore[attr-defined]
if len(rows) > _MAX_RECORDS:
raise ValueError(
"Organizations DSAR match limit exceeded; narrow the subject selectors."
)
return rows
def _normalized_id(value: object) -> str | None:
if value is None:
return None
value = str(value).strip()
return value or None
def _iso(value: datetime | None) -> str | None:
if value is None:
return None
if value.tzinfo is None:
value = value.replace(tzinfo=timezone.utc)
return value.isoformat()
__all__ = ["ORGANIZATIONS_DSAR_CAPABILITY", "OrganizationsDsarProvider"]
src/govoplan_organizations/backend/manifest.py
+77
View File
@@ -8,6 +8,7 @@ from govoplan_core.core.access import (
)
from govoplan_core.core.module_guards import persistent_table_uninstall_guard
from govoplan_core.core.modules import (
CapabilityDocumentation,
DocumentationLink,
DocumentationTopic,
FrontendModule,
@@ -29,6 +30,7 @@ from govoplan_core.core.organizations import (
from govoplan_core.core.views import ViewSurface
from govoplan_core.db.base import Base
from govoplan_organizations.backend.db import models as organization_models # noqa: F401 - populate metadata
from govoplan_organizations.backend.dsar_provider import ORGANIZATIONS_DSAR_CAPABILITY
ORGANIZATIONS_READ_SCOPES = (
@@ -131,6 +133,13 @@ def _organization_directory(context: ModuleContext) -> object:
return SqlOrganizationDirectory()
def _organizations_dsar_provider(context: ModuleContext) -> object:
del context
from govoplan_organizations.backend.dsar_provider import OrganizationsDsarProvider
return OrganizationsDsarProvider()
manifest = ModuleManifest(
id="organizations",
name="Organizations",
@@ -149,6 +158,10 @@ manifest = ModuleManifest(
name="organizations.hierarchy_directory",
version="0.1.0",
),
ModuleInterfaceProvider(
name=ORGANIZATIONS_DSAR_CAPABILITY,
version="0.1.0",
),
),
permissions=PERMISSIONS,
role_templates=ROLE_TEMPLATES,
@@ -236,8 +249,72 @@ manifest = ModuleManifest(
capability_factories={
CAPABILITY_ORGANIZATION_DIRECTORY: _organization_directory,
CAPABILITY_ORGANIZATION_HIERARCHY_DIRECTORY: (_organization_directory),
ORGANIZATIONS_DSAR_CAPABILITY: _organizations_dsar_provider,
},
capability_documentation={
ORGANIZATIONS_DSAR_CAPABILITY: CapabilityDocumentation(
label="Organizations data-subject request provider",
summary=(
"Finds tenant-scoped account attribution on organization-model "
"instantiations and upgrades without exporting opaque model payloads."
),
contract_version="0.1.0",
documentation_types=("admin",),
audience=("privacy_officer", "organization_admin", "records_manager"),
),
},
documentation=(
DocumentationTopic(
id="organizations.privacy.data-subject-requests",
title="Review Organizations data in a data-subject request",
summary=(
"Collect tenant-scoped organization-model change attribution while "
"preserving institutional governance evidence."
),
body=(
"Organizations stores institutional units, structures, relations, and "
"functions rather than personal incumbency. IDM owns the links between "
"identities and functions and must answer for those assignments. The "
"Organizations DSAR provider therefore searches only corroborated account "
"attribution on tenant model instantiations and upgrade requests, "
"applications, or cancellations. It exports the affected template and "
"version references, status, revision, timestamps, and integrity hashes. "
"Global template authorship, unrelated institutional model objects, "
"template definitions, upgrade previews and decisions, provenance, "
"idempotency keys, request digests, opaque settings, and other tenants are "
"excluded. The attribution is retained as institutional model-change "
"evidence and the provider publishes no automatic erasure action."
),
layer="static",
documentation_types=("admin",),
audience=(
"privacy_officer",
"organization_admin",
"records_manager",
"operator",
),
related_modules=("access", "audit", "idm", "records"),
links=(
DocumentationLink(
label="Data-subject requests",
href="/admin?section=tenant-data-subject-requests",
kind="runtime",
),
DocumentationLink(
label="Organizations administration",
href="/admin?section=tenant-organization-settings",
kind="runtime",
),
),
metadata={
"kind": "guide",
"help_contexts": [
"organizations.admin.tenant",
"organizations.admin.template-upgrades",
],
},
order=24,
),
DocumentationTopic(
id="organizations.template-upgrades",
title="Upgrade a tenant organization model",