# 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.