Sync wiki after docs cleanup

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`

Repo-README.md

@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:d5efaa62eaa3add63f853557 -->
+<!-- codex-wiki-sync:e559db4db5ac3524a5750e6e -->
 
 > 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
+interactive auth routes, and administration routers are owned here. The public
-administration router are owned here. Access-side admin service helpers remain
+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
+with `access_*` table names; tenant records live in `govoplan-tenancy`,
-`govoplan-tenancy`, governance templates in `govoplan-admin`, audit logs in
+governance templates in `govoplan-admin`, audit logs in `govoplan-audit`, and
-`govoplan-audit`, and system settings in `govoplan-core`. The staged
+system settings in `govoplan-core`. The staged extraction path is documented in:
-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

Repo-docs-ACCESS-MODULE-BOUNDARY.md

@@ -0,0 +1,122 @@
+<!-- codex-wiki-sync:2e63e88b3a64a33346d219fe -->
+
+> 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.

Repo-docs-OPENDESK-IDENTITY-BOUNDARY.md

@@ -0,0 +1,104 @@
+<!-- codex-wiki-sync:c61bce6bc8d0318883a34939 -->
+
+> 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.