govoplan-files/README.md

govoplan-files

Repository type: module (domain).

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:

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

Run the WebUI from the core host:

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:

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

Frontend package:

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