govoplan-access/README.md

# GovOPlaN Access

<!-- govoplan-repository-type:start -->
**Repository type:** module (platform).
<!-- govoplan-repository-type:end -->

`govoplan-access` is the platform module for GovOPlaN identity,
authentication, sessions, API keys, RBAC, groups, users, and access
administration.

The repository contains the extracted access seed implementation under
`src/govoplan_access/backend`. Session, API-key, and password helper services,
interactive auth routes, and administration routers are owned here. Access
still exports `govoplan_access.auth` for compatibility, but sibling modules
should import the core `govoplan_core.auth` facade so auth can become a
provider-neutral capability. Modules must not import the backend dependency
module directly. Access-side admin service helpers remain
here for users, groups, roles, system accounts, sessions, API keys, tenant
access enforcement, admin/audit lookup capabilities, tenant owner
provisioning, and governance-template materialization into access-owned groups
and roles. Governance-template metadata CRUD lives in `govoplan-admin`. The
transitional administration WebUI route shell and
access-owned panels live under `webui/src` as `@govoplan/access-webui`. Generic
system administration panels are contributed by `@govoplan/admin-webui` through
core's `admin.sections` UI capability. Live access ORM models are defined here
with `access_*` table names. Access stores current scope identifiers in
`tenant_id` columns but does not hard-depend on the tenancy module package.
Tenancy-specific tenant administration and tenant resolver behavior live in
`govoplan-tenancy`; governance templates in `govoplan-admin`, audit logs in
`govoplan-audit`, and system settings in `govoplan-core`. The current access
boundary is documented in:

- `/mnt/DATA/git/govoplan-core/docs/ACCESS_RBAC_MODEL.md`
- `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`
- `docs/ACCESS_MODULE_BOUNDARY.md`
- `docs/IDENTITY_ACCOUNT_FUNCTION_MODEL.md`
- `docs/OPENDESK_IDENTITY_BOUNDARY.md`

## Initial Ownership

This module will own:

- accounts and login identity
- authentication routes and session lifecycle
- API keys
- legacy administration route contribution during the transition
- tenant-local users
- identity-to-account projection for explainable access decisions
- organization-bound functions and function assignments
- explicit delegation and acting-in-place facts
- groups and memberships
- roles and role assignments
- principal resolution
- permission evaluation
- access administration backend routes
- access administration WebUI route contributions
- compatibility FastAPI auth dependency API at `govoplan_access.auth`
- provider-facing auth facade consumed by sibling modules at `govoplan_core.auth`
- access administration, tenant provisioning, and governance materializer
  capabilities
- access-owned migrations

The governance-template routes under `/admin/system/governance-templates` are
contributed by `govoplan-admin`; access must not register those routes.

`govoplan-access` treats `govoplan-tenancy` as optional. Access can run in the
single-scope compatibility mode used by the core/access baseline, and tenancy
adds tenant administration plus tenant resolver behavior when installed.

## Principal Context

The stable principal DTO is `govoplan_core.core.access.PrincipalRef`. Access
resolves sessions, API keys, and future service accounts into that DTO and
serializes it as `principal` in auth API responses. Feature modules should use
that DTO, primitive IDs, or the core `govoplan_core.auth` dependency facade
instead of importing access ORM models or backend dependency internals.

The detailed module boundary and serialization fields are documented in
[docs/ACCESS_MODULE_BOUNDARY.md](docs/ACCESS_MODULE_BOUNDARY.md).

## WebUI Package

The repository root and `webui/` directory both expose the package
`@govoplan/access-webui`. The package contributes the `/admin` route and admin
nav item through core's module WebUI contract. The route shell consumes
module-owned `admin.sections` contributions from installed platform modules and
continues to render access-owned tenant/user/group/role panels locally. Core
supplies shared admin components, route rendering, and icon resolution.

The kernel remains responsible for module discovery, route aggregation,
database/session lifecycle, migration orchestration, capability registry, and
stable contracts.

## Gitea Workflow

This repository uses the shared GovOPlaN Gitea issue workflow. Issue templates
are installed under `.gitea/`, and the shared label taxonomy is copied to
`docs/gitea-labels.json`.

From the core checkout, labels can be synced once a local `GITEA_TOKEN` is
available:

```bash
cd /mnt/DATA/git/govoplan-core
/mnt/DATA/git/govoplan/tools/gitea/gitea-sync-labels.py --root /mnt/DATA/git/govoplan-access --apply
```

## Development Install

From the core checkout:

```bash
cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m pip install -e ../govoplan-access
```

## Login Throttling

Interactive password login is throttled by normalized global login identity and by
the directly connected client address. The deployment defaults are 10 identity
failures and 100 client failures in a 15-minute window. Counters use
`REDIS_URL` when Redis is reachable, allowing all API workers to share the same
limits. Local development and Redis outages fall back automatically to a
bounded, process-local counter; authentication remains available, but limits
then apply per API process.

The deployment settings are `AUTH_LOGIN_THROTTLE_ENABLED`,
`AUTH_LOGIN_THROTTLE_IDENTITY_LIMIT`, `AUTH_LOGIN_THROTTLE_CLIENT_LIMIT`,
`AUTH_LOGIN_THROTTLE_WINDOW_SECONDS`, and
`AUTH_LOGIN_THROTTLE_REDIS_RETRY_SECONDS`. Client-supplied forwarding headers
are not trusted for throttling. A reverse proxy should pass the real peer
address only through the platform's separately configured trusted-proxy
boundary.