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