75 lines
3.4 KiB
Markdown
75 lines
3.4 KiB
Markdown
# 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
|
|
|
|
Live SMB access is disabled in all modes until `smbprotocol` initial connections
|
|
and DFS referral targets can be pinned and policy-validated. An explicit IP is
|
|
not sufficient because the server may still issue a referral to another peer.
|
|
Live S3 access is likewise disabled 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.
|