# 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](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.