GovOPlaN/govoplan-files
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d5d0df792b03c69c05b469289a2ca8fc40b00b22
govoplan-files/docs/CONNECTOR_BOUNDARY.md

3.3 KiB
Raw Blame History

File Connector Boundary

GovOPlaN Files owns the managed-file boundary: frozen blobs, versions, shares, campaign attachment evidence, provenance, connector policy, connector profiles, and read-only browse/import APIs that turn external files into managed GovOPlaN files.

The built-in connector layer is intentionally on-demand. It does not run remote indexing, background sync, remote mutation, or upstream permission management. Connectors may browse an external source, import one selected file, freeze it as a managed file, record provenance, and audit the access.

Built-In Baseline

The files module may keep small baseline providers when they are needed for normal product workflows and can share the same governance model:

  • Seafile through the native read/download API
  • Nextcloud through WebDAV
  • generic WebDAV
  • SMB through the optional smb extra

These providers are surfaced through connector descriptors at GET /api/v1/files/connectors/providers. Provider descriptors declare whether the provider is implemented, whether its optional dependency is installed, and which browse/import behaviors are available.

Separate Connector Module Candidates

A separate connector module becomes appropriate when integration needs exceed on-demand browse/import:

  • background indexing or synchronization
  • bidirectional remote mutation
  • long-running transfer workers
  • provider-specific credential lifecycle or OAuth flows
  • DMS/eAkte metadata models, registers, retention, or filing plans
  • S3-compatible object store administration
  • NFS host-mount lifecycle or sidecar coordination
  • provider-specific WebUI administration beyond profile fields

In that model, govoplan-files should keep the managed-file import contract, policy checks, provenance model, and audit events. A connector module should own provider-specific discovery, synchronization, credentials, health checks, and any remote write behavior.

Provider Responsibilities

Every provider must:

  • enforce GovOPlaN profile visibility and connector policy before browse/import
  • keep credentials as encrypted values or scoped secret references, never API response values; process-environment references are allowed only in deployment-owned profiles with an exact deployment allowlist
  • import external files into managed storage before they are used in campaigns or workflows
  • preserve source provenance and revision metadata
  • emit connector audit events for imported or accessed files
  • treat remote ACLs as upstream checks, not as a replacement for GovOPlaN policy
  • use a transport that pins every connection to a policy-validated DNS/IP answer and revalidates redirects; SDK transports without that guarantee fail closed

SMB DNS endpoints therefore fail closed in private-network mode until the SDK supports connection-time pinning; explicit IP endpoints remain available. Live S3 access is disabled in all modes until boto3/botocore can be bound to the pinned transport, including SDK-managed redirects and endpoint discovery.

Non-Goals For Files

Files does not own collaborative editing, comments, document review workflows, remote lock orchestration, DMS records management, or external system data models. Those belong to future document, workflow, DMS, or connector modules and should integrate through capabilities and managed-file imports.