From 9a8f38f75926f9908a27fdb5d110beab3a3e0cfb Mon Sep 17 00:00:00 2001 From: zemion Date: Wed, 8 Jul 2026 08:35:43 +0200 Subject: [PATCH] Document connector spaces concept --- Connector-Spaces.md | 124 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 Connector-Spaces.md diff --git a/Connector-Spaces.md b/Connector-Spaces.md new file mode 100644 index 0000000..c84e951 --- /dev/null +++ b/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. \ No newline at end of file