195 lines
8.9 KiB
Markdown
195 lines
8.9 KiB
Markdown
# 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.
|