Document connector spaces concept

Connector-Spaces.md

@@ -0,0 +1,124 @@
+# 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 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
+- credential mode: anonymous, environment reference, secret reference, or a
+  future encrypted secret store
+- capabilities: browse, sync, import, optional write when a provider supports it
+- profile-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 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
+- JSON/environment-defined connector profiles with system, tenant, user, group,
+  and campaign visibility
+- connector allow/deny policy enforcement before browse/import/sync
+- read-only browse endpoints
+- import and sync into managed files with provenance and revision metadata
+- audit events for connector import, sync, and access
+- Files UI sync dialog for choosing a profile, browsing a remote folder, and
+  syncing a selected file into a managed destination folder
+- Docker dev stack smoke checks for WebDAV, Nextcloud, and SMB
+
+Missing:
+
+- database-backed connector profiles equivalent to mail-server profiles
+- explicit connector profile policy rows equivalent to mail-profile policies
+- settings/admin UI for system and tenant connector profiles and policy
+- linked connector-space rows owned by users or groups
+- file-space API responses that include linked connector spaces
+- Files UI entry point to create and manage linked connector spaces
+- optional background sync or remote-write semantics
+
+## Implementation Phases
+
+1. Persist governed connector profiles and policies.
+   - Add `file_connector_profiles` and `file_connector_policies` tables.
+   - Reuse the mail profile scope model: system and tenant first.
+   - Keep environment JSON profiles as bootstrap/compatibility profiles.
+   - Expose profile and policy CRUD endpoints.
+
+2. Add linked connector spaces.
+   - Add `file_connector_spaces` with owner user/group, profile id, library id,
+     remote path, display label, sync mode, and active state.
+   - Enforce effective connector policy before creating or using a link.
+   - Return linked connector spaces from `/api/v1/files/spaces`.
+
+3. Surface linked spaces in the Files UI.
+   - Show linked spaces beside managed user/group spaces.
+   - Add a create/edit linked-space dialog that browses an allowed profile and
+     selects a remote folder.
+   - Reuse the existing connector browser/sync flow when a linked space is open.
+
+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.