# 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`,
  `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.

## 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`

`/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.

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