add-ideas/govoplan-access
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Repo docs ACCESS MODULE BOUNDARY
Pages
Codex Project Index Repo README Repo docs ACCESS MODULE BOUNDARY Repo docs IDENTITY ACCOUNT FUNCTION MODEL Repo docs OPENDESK IDENTITY BOUNDARY
Clone
1
Repo docs ACCESS MODULE BOUNDARY
Albrecht Degering edited this page 2026-07-09 12:04:45 +02:00
Table of Contents

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.