chore: sync GovOPlaN module split state

docs/CONNECTOR_SPACES.md

@@ -0,0 +1,147 @@
+# 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.