# govoplan-files

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

GovOPlaN Files is the managed file module. It bundles backend storage APIs and the Files WebUI package so file features can be installed as one module.

## Ownership

This repository owns:

- backend module manifest `files`
- file permissions such as `files:file:read`, `files:file:upload`, `files:file:download`, `files:file:organize`, and `files:file:delete`
- file-space, file metadata, share, upload, download, pattern matching, and transfer APIs
- SQLAlchemy file models and module migration registration
- WebUI package `@govoplan/files-webui`
- `/files` route and IconRail navigation contribution

Core owns auth, tenants, RBAC evaluation, database/session primitives, CSRF/API helpers, and shell layout.

## Development

Install through the core environment:

```bash
cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m pip install -r requirements-dev.txt
```

Run the WebUI from the core host:

```bash
cd /mnt/DATA/git/govoplan-core/webui
PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run dev
```

## Module integration

Backend entry point:

```toml
[project.entry-points."govoplan.modules"]
files = "govoplan_files.backend.manifest:get_manifest"
```

Frontend package:

```text
@govoplan/files-webui
```

The campaign module can integrate with files when both modules are installed,
for example for managed attachment selection and campaign file sharing. Files
does not import campaign internals; campaign share/existence checks use the core
`campaigns.access` capability registered by the campaign module.

Platform RBAC and governance rules are documented in `govoplan-core/docs/`.

Managed files can carry source provenance for connector and import workflows.
Upload callers may provide `source_provenance_json` and `source_revision`; the
module stores those values under file metadata, returns normalized
`source_provenance` and `source_revision` fields in file responses, and carries
them into managed campaign attachment matches for frozen execution evidence.

Connector policy preflight is available through
`POST /api/v1/files/connector-policy/evaluate`, and provenance-bearing uploads
can pass `connector_policy_json` to enforce the same policy before file content
is read. Policy payloads contain ordered `sources`; each source has
`scope_type`, optional `scope_id`, optional `label`, and a `policy` object. The
policy object supports `allow`/`allowlist`/`whitelist` and
`deny`/`denylist`/`blacklist` rules for `connectors`, `providers`,
`external_ids`, `external_paths`, and `external_urls`. Deny rules win across the
hierarchy; allow rules narrow access at each source that defines them.

Connector endpoint settings are exposed through governed connector profiles.
Profiles can be supplied as JSON through
`GOVOPLAN_FILES_CONNECTOR_PROFILES_JSON`, or from a JSON file path through
`GOVOPLAN_FILES_CONNECTOR_PROFILES_FILE`. Each profile has an `id`, `provider`,
`endpoint_url`, governance `scope_type`/`scope_id`, optional `capabilities`, and
credential references such as `password_env`, `token_env`, or `secret_ref`.
`GET /api/v1/files/connectors/profiles` returns only profiles visible to the
current principal (system, tenant, user, group, or accessible campaign scope) and
redacts secret values and environment variable names. Use the returned
`policy_sources` with connector policy preflight before importing files.
`GET /api/v1/files/connectors/providers` exposes provider descriptors for
Seafile, Nextcloud, WebDAV, SMB, NFS, and local filesystem connectors. The
descriptor declares implementation status, optional dependencies, permission
mapping, sync/index strategy, conflict handling, preview behavior, and audit
events so provider coverage remains visible without forcing every optional
protocol dependency to be installed.
`GET /api/v1/files/connectors/profiles/{profile_id}/browse` provides read-only
connector browsing. Browse entries use a shared `library`/`folder`/`file` shape,
run profile policy with the `browse` operation, and support Seafile,
WebDAV/Nextcloud, and SMB when the optional `smb` extra is installed. Seafile
profiles browse libraries and directories via Seafile's read-only API; profiles
can still opt into WebDAV browsing by setting `metadata.webdav_endpoint_url` or
`metadata.browse_protocol` to `webdav`.
`POST /api/v1/files/connectors/profiles/{profile_id}/import` imports a Seafile
or WebDAV/Nextcloud/SMB file into managed storage through the same governance,
conflict handling, source provenance, and connector audit path as direct
uploads. The Seafile provider uses account-token auth and the native file
download-link API; Nextcloud and generic WebDAV profiles use authenticated `GET`
requests against the configured WebDAV endpoint. SMB profiles use
`smb://server[:port]/share[/path]` endpoints and environment-backed credentials
through `smbprotocol`.

Local connector development assets live in `dev/connectors/`. The compose stack
boots Nextcloud, Seafile, WebDAV, and SMB endpoints for provider development and
manual interoperability testing.

Connector and collaboration ownership boundaries are documented in
`docs/CONNECTOR_BOUNDARY.md` and `docs/DOCUMENT_COLLABORATION_BOUNDARY.md`.

ZIP uploads are processed without buffering the whole archive in memory. The API
spools incoming ZIP request bodies to a bounded temporary file, then extracts
members with per-file and total extracted-size limits before storing managed
files.

Bulk rename and transfer APIs are owner-scoped: callers must provide the active
user or group file space with `owner_type` and `owner_id`. The storage layer
keeps a named legacy file-only helper for historical callers that lack owner
context, and regression tests cover its write-access checks.

## Release packaging

The repository root includes a `package.json` for git-based WebUI installs. It exports the package `@govoplan/files-webui` from `webui/src` so release builds can depend on tagged git refs instead of local `file:` paths.