From 7e615c31bb5fd51185381ce1f8f6f7d22e7268c1 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Thu, 9 Jul 2026 12:04:45 +0200 Subject: [PATCH] Sync wiki after docs cleanup --- Codex-Project-Index.md | 2 + Repo-README.md | 30 ++++-- Repo-docs-ACCESS-MODULE-BOUNDARY.md | 122 ++++++++++++++++++++++++ Repo-docs-OPENDESK-IDENTITY-BOUNDARY.md | 104 ++++++++++++++++++++ 4 files changed, 250 insertions(+), 8 deletions(-) create mode 100644 Repo-docs-ACCESS-MODULE-BOUNDARY.md create mode 100644 Repo-docs-OPENDESK-IDENTITY-BOUNDARY.md diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index 751b4c2..d09210a 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -5,3 +5,5 @@ This page is generated from repository and product-directory project files. - [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-access/README.md` +- [Repo-docs-ACCESS-MODULE-BOUNDARY](Repo-docs-ACCESS-MODULE-BOUNDARY) - `/mnt/DATA/git/govoplan-access/docs/ACCESS_MODULE_BOUNDARY.md` +- [Repo-docs-OPENDESK-IDENTITY-BOUNDARY](Repo-docs-OPENDESK-IDENTITY-BOUNDARY) - `/mnt/DATA/git/govoplan-access/docs/OPENDESK_IDENTITY_BOUNDARY.md` diff --git a/Repo-README.md b/Repo-README.md index c8c5b6f..c587cb1 100644 --- a/Repo-README.md +++ b/Repo-README.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-access/README.md`. > Origin: `repository`. @@ -13,8 +13,10 @@ administration. The repository contains the extracted access seed implementation under `src/govoplan_access/backend`. Session, API-key, and password helper services, -interactive auth routes, FastAPI auth dependencies, and the legacy -administration router are owned here. Access-side admin service helpers remain +interactive auth routes, and administration routers are owned here. The public +FastAPI request dependency API is exported from `govoplan_access.auth`; modules +must not import the backend dependency module directly. Access-side admin +service helpers remain here for users, groups, roles, system accounts, sessions, API keys, tenant access enforcement, admin/audit lookup capabilities, tenant owner provisioning, and governance-template materialization into access-owned groups @@ -23,13 +25,14 @@ transitional administration WebUI route shell and access-owned panels live under `webui/src` as `@govoplan/access-webui`. Generic system administration panels are contributed by `@govoplan/admin-webui` through core's `admin.sections` UI capability. Live access ORM models are defined here -while retaining their historical table names; tenant records live in -`govoplan-tenancy`, governance templates in `govoplan-admin`, audit logs in -`govoplan-audit`, and system settings in `govoplan-core`. The staged -extraction path is documented in: +with `access_*` table names; tenant records live in `govoplan-tenancy`, +governance templates in `govoplan-admin`, audit logs in `govoplan-audit`, and +system settings in `govoplan-core`. The staged extraction path is documented in: - `/mnt/DATA/git/govoplan-core/docs/ACCESS_EXTRACTION_PLAN.md` - `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md` +- `docs/ACCESS_MODULE_BOUNDARY.md` +- `docs/OPENDESK_IDENTITY_BOUNDARY.md` ## Initial Ownership @@ -46,7 +49,7 @@ This module will own: - permission evaluation - access administration backend routes - access administration WebUI route contributions -- published FastAPI auth dependency API +- published FastAPI auth dependency API at `govoplan_access.auth` - access administration, tenant provisioning, and governance materializer capabilities - access-owned migrations @@ -57,6 +60,17 @@ contributed by `govoplan-admin`; access must not register those routes. `govoplan-access` depends on `govoplan-tenancy`; the registry loads tenancy before access for authenticated platform composition. +## Principal Context + +The stable principal DTO is `govoplan_core.core.access.PrincipalRef`. Access +resolves sessions, API keys, and future service accounts into that DTO and +serializes it as `principal` in auth API responses. Feature modules should use +that DTO, primitive IDs, or the published `govoplan_access.auth` dependency API +instead of importing access ORM models or backend dependency internals. + +The detailed module boundary and serialization fields are documented in +[docs/ACCESS_MODULE_BOUNDARY.md](docs/ACCESS_MODULE_BOUNDARY.md). + ## WebUI Package The repository root and `webui/` directory both expose the package diff --git a/Repo-docs-ACCESS-MODULE-BOUNDARY.md b/Repo-docs-ACCESS-MODULE-BOUNDARY.md new file mode 100644 index 0000000..b64d7f4 --- /dev/null +++ b/Repo-docs-ACCESS-MODULE-BOUNDARY.md @@ -0,0 +1,122 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-access/docs/ACCESS_MODULE_BOUNDARY.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# GovOPlaN Access Module Boundary + +`govoplan-access` is the platform module that owns login identity and runtime +authorization state. Core remains the kernel: it composes modules, mounts +routes, owns process/database lifecycle, and exposes stable capability +contracts. + +## Access-Owned Capabilities + +`govoplan-access` owns the canonical implementation for: + +- accounts and global login identity +- interactive authentication routes and session lifecycle +- API-key creation, verification, revocation, and scope delegation +- tenant-local users, memberships, groups, roles, and role assignments +- principal resolution and request authentication dependencies +- permission evaluation for access-owned scopes and legacy access aliases +- access administration backend routes for users, groups, roles, system + accounts, sessions, and API keys +- access administration WebUI route contribution for `/admin` +- tenant owner provisioning and default access bootstrap +- materializing governance templates into access-owned groups and roles +- access-owned SQLAlchemy metadata and migrations for `access_*` tables + +The active access tables use the `access_*` namespace while the model classes +live in this module: `access_accounts`, `access_users`, `access_groups`, +`access_roles`, `access_system_role_assignments`, +`access_user_group_memberships`, `access_user_role_assignments`, +`access_group_role_assignments`, `access_api_keys`, and +`access_auth_sessions`. + +## Kernel-Owned Contracts + +`govoplan-core` owns the stable contracts that let modules interact without +importing access internals: + +- `ModuleManifest`, route factories, migration specs, and registry validation +- database engine/session lifecycle and migration orchestration +- capability registry and capability names in `govoplan_core.core.access` +- access DTO/protocol contracts such as `PrincipalRef`, `AccountRef`, + `UserRef`, `GroupRef`, `RoleRef`, `PrincipalResolver`, + `AccessDirectory`, `PermissionEvaluator`, `TenantAccessProvisioner`, + `AccessAdministration`, and `AccessGovernanceMaterializer` +- health, platform metadata, and module startup ordering +- generic security helpers that are not access-state semantics, such as + secret encryption and UTC time helpers + +Feature modules should depend on these kernel contracts or the published +`govoplan_access.auth` request dependency API, not on access ORM models or +`govoplan_access.backend.*` implementation internals. + +## Principal Context Contract + +The stable runtime principal is `govoplan_core.core.access.PrincipalRef`. +Access resolves request credentials into that DTO and `ApiPrincipal` keeps the +legacy ORM objects only for routers that have not yet moved to pure kernel +contracts. New module code should pass around `PrincipalRef` or primitive IDs. + +`PrincipalRef.to_dict()` is the canonical API/WebUI serialization shape: + +- `account_id`, `membership_id`, and `tenant_id` +- sorted `scopes` and `group_ids` +- `auth_method` plus optional `session_id`, `api_key_id`, or + `service_account_id` +- optional display fields `email` and `display_name` + +`/api/v1/auth/me`, `/api/v1/auth/login`, profile refreshes, and tenant switches +include this payload as `principal` alongside the existing compatibility +fields. Modules that need current user context should prefer +`auth.principal`/`AuthInfo.principal` in the WebUI and +`principal.to_platform_principal()` in backend request handlers. + +## Removed Compatibility Paths + +These legacy imports were removed from core. Use access-owned modules, the +public `govoplan_access.auth` request dependency API, or kernel capabilities +instead: + +- `govoplan_core.security.api_keys` +- `govoplan_core.security.sessions` +- `govoplan_core.security.passwords` +- `govoplan_core.api.v1.auth` +- `govoplan_core.api.v1.admin` +- `govoplan_core.api.v1.admin_schemas` +- `govoplan_core.admin.service` +- `govoplan_core.admin.governance` + +HTTP route compatibility remains at the API layer: the access manifest +contributes the same `/api/v1/auth/*` and `/api/v1/admin/*` paths through module +route aggregation. + +## Route Ownership + +The access manifest contributes the `/api/v1/auth/*` interactive auth routes +and the access-owned `/api/v1/admin/*` administration routes through its module +route factory. Core default server configuration must not register auth or +admin routers as base routers. + +Governance-template metadata CRUD is not access-owned. It is contributed by +`govoplan-admin`; access only materializes those templates into access-owned +groups and roles through the `access.governanceMaterializer` capability. + +## Verification References + +Focused verification is run from `/mnt/DATA/git/govoplan-core`. + +- `tests.test_module_system` verifies manifest discovery, access startup in + module permutations, admin route ownership, governance-template route + separation, and legacy compatibility imports. +- `tests.test_api_smoke.ApiSmokeTests.test_cookie_session_requires_csrf_for_mutations` + verifies the access-owned session/auth route behavior. +- `tests.test_api_smoke.ApiSmokeTests.test_tenant_user_group_role_and_api_key_administration` + verifies access-owned administration and API-key behavior. +- `tests.test_api_smoke.ApiSmokeTests.test_profile_refresh_and_system_role_protection_model` + verifies profile/session refresh and protected system role behavior. diff --git a/Repo-docs-OPENDESK-IDENTITY-BOUNDARY.md b/Repo-docs-OPENDESK-IDENTITY-BOUNDARY.md new file mode 100644 index 0000000..7968ebf --- /dev/null +++ b/Repo-docs-OPENDESK-IDENTITY-BOUNDARY.md @@ -0,0 +1,104 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-access/docs/OPENDESK_IDENTITY_BOUNDARY.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# OpenDesk Identity Integration Boundary + +OpenDesk-style identity integrations should terminate in `govoplan-access` as +canonical accounts, tenant memberships, groups, roles, sessions, and principal +claims. Provider protocol details may live in access subpackages or dedicated +connector modules, but other GovOPlaN modules must consume identity through +access capabilities, typed DTOs, events, and published route dependencies. + +## Boundary Decision + +`govoplan-access` owns the identity projection and authorization effects: + +- external identity links for accounts and memberships +- authentication callback/session issuance for federated login +- claim, group, and role mapping into access-owned roles and memberships +- SCIM-style provisioning effects for accounts, users, groups, and group + membership +- account suspension/deactivation effects that influence sessions and API keys +- audit-relevant identity events emitted through kernel event/audit contracts + +Connector packages may own provider-specific transport and schema logic: + +- LDAP and Active Directory bind/search/sync adapters +- OIDC and SAML provider metadata, callback protocol handling, and claim + normalization +- SCIM client/server protocol specifics +- Open-Xchange identity lookup or provisioning clients + +Those connectors should call access capabilities or access-owned service APIs +instead of writing access tables directly. + +## Integration Types + +### LDAP And Active Directory + +LDAP/AD adapters may authenticate credentials, search directory entries, and +sync group membership. Access owns the resulting account, membership, group, +and role mapping. Directory groups should map to access groups or role +assignments through explicit mapping rules; they should not grant feature +module permissions directly. + +### OIDC And SAML + +OIDC/SAML adapters may handle provider metadata, assertions, tokens, and claim +normalization. Access owns external subject linking, session creation, tenant +selection, first-login behavior, and claim-to-role/group mapping. Feature +modules should see only `PrincipalRef`, `UserRef`, scopes, group IDs, and +tenant context. + +### SCIM Provisioning + +SCIM provisioning belongs at the access boundary because it mutates accounts, +memberships, groups, and deactivation state. Tenant resolution remains a kernel +or tenancy capability concern. SCIM must not provision mailboxes, calendars, +campaign ownership, or file spaces directly; those modules may react to +access-published identity events when needed. + +### Open-Xchange Touchpoints + +Open-Xchange identity/contact integration should split identity from +collaboration data: + +- Access owns external account IDs, email/display-name identity fields, + membership state, group references, and auth/session effects. +- Mail, calendar, contacts, or connector modules own mailboxes, address books, + calendar resources, contact folders, and provider-specific collaboration + objects. + +Access may publish identity-change events and stable DTOs that those modules +consume, but it should not import their internals or own their provider data. + +## Non-Goals + +Access does not own: + +- campaign ACLs, campaign ownership, delivery policy, or recipient contacts +- file storage permissions beyond principal/group identity references +- mail profile credentials, mailbox state, or reusable mail-server profiles +- calendar availability, appointments, rooms, or contact address books +- provider-specific UI panels for non-identity configuration + +Those belong to their owning modules and should integrate through capabilities +or events. + +## Implementation Shape + +Provider integration should be added in small slices: + +1. Define an access-owned external identity link model and DTO surface. +2. Add provider adapter contracts that normalize external subjects, groups, + claims, and deactivation signals. +3. Route OIDC/SAML login callbacks through access so sessions are issued by + the access session service. +4. Route LDAP/AD/SCIM provisioning through access administration services and + tenant provisioning capabilities. +5. Publish identity-change events for optional mail/calendar/contact/file + reactions without adding module-to-module imports.