govoplan-access/docs/ACCESS_MODULE_BOUNDARY.md

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
• identity-to-account projection used for explainability
• organization-bound functions, function assignments, and delegation facts
• principal resolution and request authentication dependencies
• permission evaluation for access-owned scopes and legacy access aliases
• access-decision explain output with identity/account/function/role/right provenance
• 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, IdentityRef, OrganizationUnitRef, FunctionRef, FunctionAssignmentRef, FunctionDelegationRef, AccessDecisionProvenance, ApiPrincipalProvider, TenantContextSwitcher, PrincipalResolver, AccessDirectory, AccessSemanticDirectory, PermissionEvaluator, AccessExplanationService, 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 core govoplan_core.auth request dependency facade, not on access ORM models or govoplan_access.backend.* implementation internals. The access package still exports govoplan_access.auth for compatibility, but new routers should use the core facade so auth can move behind provider-neutral capabilities.

Access declares tenancy as an optional module integration. It uses the core-owned core_scopes table as the scope table, but it must not import govoplan_tenancy or require the tenancy package to start.

Core-Only Startup Contract

A core-only installation must be able to start far enough to expose process health, module metadata, and the unauthenticated shell needed for installation or recovery work. It is not a usable authenticated product installation.

Authenticated product use requires the access module or another module that provides the same kernel auth capabilities:

• auth.apiPrincipalProvider
• auth.principalResolver
• auth.permissionEvaluator
• auth.tenantContextSwitcher

Access contributes the default implementations for those capabilities plus the interactive /api/v1/auth/* routes. Product modules should express auth needs as required capabilities or route permission requirements instead of importing access internals. Runtime configurations that intentionally omit access should hide authenticated navigation and return capability errors for authenticated product routes rather than failing process startup.

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
• optional identity_id
• sorted scopes, group_ids, role_ids, function_assignment_ids, and delegation_ids
• auth_method plus optional session_id, api_key_id, or service_account_id
• optional acting_for_account_id for acting-in-place flows
• optional display fields email and display_name

govoplan_core.auth is now backed by the auth.apiPrincipalProvider capability. The access module provides that capability; core no longer imports access auth dependencies directly. /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.

Interactive tenant context switching is exposed through auth.tenantContextSwitcher. The existing /api/v1/auth/switch-tenant route remains for API compatibility; govoplan-tenancy also contributes /api/v1/tenancy/switch-tenant. Both delegate to the same access-owned session switch behavior. Lifecycle code must use the capability instead of importing govoplan_access.backend.security.sessions.

Identity And Function Boundary

The full semantic model is documented in IDENTITY_ACCOUNT_FUNCTION_MODEL.md. In short:

• govoplan-idm imports and previews external identity and organization facts from IDM systems.
• govoplan-identity owns canonical identities and identity/account links.
• govoplan-organizations owns canonical organization units, functions, and account-held function assignments.
• govoplan-access owns the authorization projection that maps organization and identity facts to roles, rights, delegation enforcement, and explainable permission decisions.

Function assignments are account-held and organization-scoped. They can apply only to the selected organization unit or to that unit and all subunits. Delegation and acting-in-place must remain explicit facts with audit provenance; modules must not infer either from plain group membership.

The backend foundation exposes these administration routes:

• /api/v1/admin/identities
• /api/v1/admin/organization-units
• /api/v1/admin/functions
• /api/v1/admin/function-assignments
• /api/v1/admin/function-delegations

Dedicated WebUI management panels and explicit acting-in-place context selection are still follow-up work on top of these routes.

Removed Compatibility Paths

These legacy imports were removed from core. Use access-owned modules, the core govoplan_core.auth request dependency facade, 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.