govoplan-files/docs/CONNECTOR_SPACES.md

Connector Spaces

GovOPlaN Files should treat external file shares as two separate product objects:

1. A governed connection profile defines a reusable remote endpoint such as a WebDAV server, Nextcloud account, Seafile server, or SMB share. Profiles are administered in settings at system or tenant scope, with the same inheritance and limit semantics used by mail-server profiles.
2. A governed credential profile defines reusable authentication material for one provider or for any compatible provider. Credentials are administered separately from connection profiles and can carry their own allow/deny policy.
3. A linked file space binds one concrete remote folder or library path from an allowed profile to a user or group. Linked spaces appear beside "My files" and group file spaces in the files module.

This keeps secrets, endpoint governance, and tenant limits in settings, while keeping user/group workspaces and concrete folder choices in the files module.

Model

Connection profile:

• provider: seafile, nextcloud, webdav, smb, or a future provider
• endpoint URL and optional base path
• scope: system or tenant for administered profiles; user/group profiles may be allowed later only when policy explicitly permits them
• optional credential profile id
• capabilities: browse, sync, import, optional write when a provider supports it
• profile-local policy for allow/deny rules

Credential profile:

• provider: a specific provider or any provider
• scope: system or tenant for administered credentials
• credential mode: anonymous, environment reference, secret reference, or encrypted stored password/token
• username and redacted secret configuration
• credential-local policy for allow/deny rules

Connector policy:

• system policy is the baseline
• tenant policy inherits system policy and may narrow it unless system allows lower-level relaxation
• future user/group policy may narrow tenant policy for self-service links
• policies can allow or block providers, profile ids, endpoint URLs, external path prefixes, credential ids, credential inheritance, and local linked-space creation

Linked connector space:

• owner type: user or group
• display name
• connector profile id
• remote library id or share id
• remote root path
• sync mode: manual initially; background sync is future work
• read-only flag from provider/policy
• active/deleted state

The linked space should be addressable as a normal file space in the files UI. For the first implementation slice, actions may use the existing connector browse/sync APIs and managed file storage. A linked space can therefore browse the remote folder and sync selected files into managed storage. Later slices can add a native remote listing view or background sync jobs.

Policy Semantics

Use mail-profile terminology because administrators already see it there:

• must use: lower scopes are restricted to selected profile ids or providers
• can use: lower scopes may choose from inherited allowed profiles
• shall not use anything outside: endpoint URLs and path prefixes are enforced by deny/allow rules before browse, import, or sync
• may create local links: controls whether users/groups can add linked spaces from inherited profiles

Connector policy should provide an explainable effective policy response with source path entries: system, tenant, user, group, campaign when applicable.

Current State

Implemented:

• provider descriptors for Seafile, Nextcloud, WebDAV, and SMB
• database-backed connector profiles with system and tenant scope
• database-backed connector credentials with system and tenant scope
• encrypted stored password/token support for database credentials
• JSON/environment-defined connector profiles with system, tenant, user, group, and campaign visibility
• connector allow/deny policy enforcement before browse/import/sync, including provider, connection profile, credential profile, and path checks
• read-only browse endpoints
• import and sync into managed files with provenance and revision metadata
• audit events for connector import, sync, and access
• settings/admin UI sections for system and tenant file connections and credentials
• linked connector-space rows owned by users or groups
• file-space API responses that include linked connector spaces
• Files UI entry point to create linked connector spaces from a browsed remote profile/folder
• Files UI sync dialog for choosing a profile, browsing a remote folder, and syncing a selected file into a managed destination folder
• Files UI connector-space view with provider/read-only/manual-sync state
• Docker dev stack smoke checks for WebDAV, Nextcloud, and SMB

Missing:

• explicit connector profile policy rows equivalent to mail-profile policies
• effective connector policy/explain UI equivalent to mail-profile policies
• edit/manage actions for existing linked connector spaces
• optional background sync or remote-write semantics

Implementation Phases

1. Persist governed connector profiles and policies.

   • file_connector_profiles exists for system and tenant profiles.
   • file_connector_credentials exists for system and tenant credentials.
   • Environment JSON profiles remain bootstrap/compatibility profiles.
   • Profile and credential CRUD endpoints exist for database-backed records.
   • Remaining: file_connector_policies plus effective policy/explain output.

2. Add linked connector spaces.

   • file_connector_spaces exists with owner user/group, profile id, library id, remote path, display label, sync mode, and active state.
   • Connector policy is enforced before creating or using a link.
   • Linked connector spaces are returned from /api/v1/files/spaces.

3. Surface linked spaces in the Files UI.

   • Linked spaces appear beside managed user/group spaces.
   • The add-space dialog browses an allowed profile and links the current remote folder/library root.
   • The connector browser/sync flow is reused when a linked space is open.
   • Remaining: edit/manage actions for existing linked spaces.

4. Add sync orchestration.

   • Manual sync selected file is already available.
   • Add folder-level manual sync.
   • Add optional scheduled/background sync with conflict reporting.

5. Add provider-specific expansion.

   • OAuth/secret-store credentials.
   • Remote write and delete only where policy and provider support it.
   • DMS/eAkte metadata integrations in a separate connector or documents module.