feat(files): orchestrate connector folder sync
Module Package Release / publish-packages (push) Successful in 12s
Module Package Release / publish-packages (push) Successful in 12s
This commit is contained in:
@@ -452,7 +452,7 @@ def _dsar_provider(context: ModuleContext) -> object:
|
||||
manifest = ModuleManifest(
|
||||
id="files",
|
||||
name="Files",
|
||||
version="0.1.19",
|
||||
version="0.1.20",
|
||||
required_capabilities=(
|
||||
CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
|
||||
CAPABILITY_AUTH_PERMISSION_EVALUATOR,
|
||||
@@ -1299,12 +1299,14 @@ manifest = ModuleManifest(
|
||||
),
|
||||
DocumentationTopic(
|
||||
id="files.governed-connectors-and-provenance",
|
||||
title="Govern file connections and credential deletion",
|
||||
summary="Keep endpoint profiles, reusable credentials, and inherited connector policy separate, and understand what DELETE removes immediately.",
|
||||
title="Govern file connections, folder sync, and credential deletion",
|
||||
summary="Keep endpoints, credentials, inherited policy, and bounded manual synchronization separate, with reviewable outcomes and provenance.",
|
||||
body=(
|
||||
"System, tenant, and one user/group/campaign leaf form the effective policy chain: deny rules win and every configured allow rule must match. "
|
||||
"Responses redact secret values and deployment references. Deleting a database-managed credential or profile immediately scrubs Files-owned encrypted material and private metadata in the same transaction as a non-secret audit event; dependent profiles are disabled, while legacy non-owned references are only detached and audited. "
|
||||
"Removing a connector space is a separate owner-authorized operation: it retires only the local virtual-space link and leaves provider content, imported managed files and shares, profiles, credentials, and remote references untouched. Intrinsic user and group managed spaces cannot be removed. Connector spaces remain read-only by default. An administrator may explicitly enable two-way mode only for an S3 profile carrying the write capability; each write requires separate authority, inherited path policy, a conditional create or expected revision, and durable recovery evidence. Automatic remote deletion, rename, and move propagation remain disabled."
|
||||
"Removing a connector space is a separate owner-authorized operation: it retires only the local virtual-space link and leaves provider content, imported managed files and shares, profiles, credentials, and remote references untouched. Intrinsic user and group managed spaces cannot be removed. "
|
||||
"A manual connector-folder sync traverses provider pagination with explicit file-count and depth bounds, preserves remote relative paths in the linked owner's managed space, and evaluates policy for the root and every downloaded item. Matching source identities produce unchanged or version-appending updates; new identities create managed assets. Unrelated target collisions default to skip, while rename, reject, and overwrite are explicit choices. Per-file savepoints keep successful siblings while conflicts, skips, policy denials, and transport failures remain visible in the response. The files.connector.folder_synced audit event records provenance, typed counts, truncation, and bounded result references without content or credentials. Scheduling remains separate. "
|
||||
"Connector spaces remain read-only by default. An administrator may explicitly enable two-way mode only for an S3 profile carrying the write capability; each write requires separate authority, inherited path policy, a conditional create or expected revision, and durable recovery evidence. Automatic remote deletion, rename, and move propagation remain disabled."
|
||||
),
|
||||
layer="configured",
|
||||
documentation_types=("admin",),
|
||||
@@ -1343,12 +1345,30 @@ manifest = ModuleManifest(
|
||||
href="/api/v1/files/connectors/credentials",
|
||||
kind="api",
|
||||
),
|
||||
DocumentationLink(
|
||||
label="Manual connector-folder sync API",
|
||||
href="/api/v1/files/connector-spaces/{space_id}/sync",
|
||||
kind="api",
|
||||
),
|
||||
DocumentationLink(
|
||||
label="Files handbook",
|
||||
href="govoplan-files/docs/FILES_HANDBOOK.md",
|
||||
kind="repository",
|
||||
),
|
||||
),
|
||||
translations={
|
||||
"de": {
|
||||
"title": "Dateiverbindungen, Ordnersynchronisierung und das Löschen von Zugangsdaten steuern",
|
||||
"summary": "Endpunkte, Zugangsdaten, vererbte Richtlinien und begrenzte manuelle Synchronisierung getrennt und mit prüfbaren Ergebnissen sowie Herkunftsnachweisen verwalten.",
|
||||
"body": (
|
||||
"System, Mandant und genau eine Benutzer-, Gruppen- oder Kampagnenebene bilden die wirksame Richtlinienkette: Ablehnungsregeln haben Vorrang und jede konfigurierte Erlaubnisregel muss zutreffen. "
|
||||
"Antworten blenden Geheimwerte und Bereitstellungsverweise aus. Beim Löschen datenbankverwalteter Zugangsdaten oder Profile entfernt Files eigenes verschlüsseltes Material und private Metadaten in derselben Transaktion wie das nicht geheime Audit-Ereignis. Abhängige Profile werden deaktiviert; ältere, nicht Files gehörende Verweise werden nur getrennt und auditiert. "
|
||||
"Das Entfernen eines Connector-Bereichs ist ein eigener, eigentümerberechtigter Vorgang: Nur die lokale Verknüpfung des virtuellen Bereichs wird außer Kraft gesetzt. Inhalte beim Anbieter, importierte verwaltete Dateien und Freigaben, Profile, Zugangsdaten und Remote-Verweise bleiben erhalten. Intrinsische Benutzer- und Gruppenbereiche können nicht entfernt werden. "
|
||||
"Eine manuelle Connector-Ordnersynchronisierung durchläuft die Anbieter-Paginierung innerhalb ausdrücklicher Grenzen für Dateizahl und Tiefe, erhält relative Remote-Pfade im verwalteten Bereich des verknüpften Eigentümers und prüft die Richtlinie für die Wurzel sowie jede heruntergeladene Datei. Übereinstimmende Quellidentitäten bleiben unverändert oder erhalten eine neue Version; neue Identitäten erzeugen verwaltete Dateien. Nicht zugehörige Zielkonflikte werden standardmäßig übersprungen; Umbenennen, Ablehnen und Ersetzen sind ausdrückliche Entscheidungen. Savepoints je Datei bewahren erfolgreiche Geschwister, während Konflikte, Überspringungen, Richtlinienablehnungen und Transportfehler in der Antwort prüfbar bleiben. Das Audit-Ereignis files.connector.folder_synced hält Herkunft, typisierte Zähler, Abbruch am Grenzwert und begrenzte Ergebnisverweise ohne Inhalte oder Zugangsdaten fest. Zeitplanung bleibt getrennt. "
|
||||
"Connector-Bereiche bleiben standardmäßig schreibgeschützt. Eine Administration kann den Zweiwege-Modus nur für ein S3-Profil mit Schreib-Capability ausdrücklich aktivieren. Jeder Schreibvorgang benötigt eigene Berechtigung, die vererbte Pfadrichtlinie, eine bedingte Neuanlage oder erwartete Revision sowie dauerhafte Wiederherstellungsnachweise. Automatisches Löschen, Umbenennen und Verschieben auf dem Remote-System bleibt deaktiviert."
|
||||
),
|
||||
}
|
||||
},
|
||||
related_modules=("access", "audit", "mail"),
|
||||
unlocks=(
|
||||
"Scoped, explainable external-file access without exposing credentials to consuming modules.",
|
||||
@@ -1369,12 +1389,34 @@ manifest = ModuleManifest(
|
||||
"files.connectors",
|
||||
"files.connector.credentials",
|
||||
"files.connector.policy",
|
||||
"files.connector-folder-sync.remote-path",
|
||||
"files.connector-folder-sync.target-folder",
|
||||
"files.connector-folder-sync.conflict-strategy",
|
||||
"files.connector-folder-sync.max-files",
|
||||
"files.connector-folder-sync.recursive",
|
||||
],
|
||||
"prerequisites": [
|
||||
"A visible active connector space uses manual sync and links to an accessible managed user or group space.",
|
||||
"The operator has files:file:upload and the effective connector policy permits the requested root and source paths.",
|
||||
],
|
||||
"steps": [
|
||||
"Open the linked connector folder, choose Sync folder, and review the managed destination.",
|
||||
"Keep the safe skip default or explicitly choose rename, reject, or overwrite for unrelated target collisions.",
|
||||
"Set the bounded file count and subfolder choice, run the sync, and review every typed item outcome and any truncation warning.",
|
||||
"Continue a truncated run from a narrower remote folder; configure scheduling separately if background operation is required.",
|
||||
],
|
||||
"limitations": [
|
||||
"Manual folder sync does not schedule future runs or mutate, delete, rename, move, or change ACLs on remote content.",
|
||||
"A successful partial run is not complete coverage when the response is truncated or contains review outcomes.",
|
||||
],
|
||||
"outcome": "Permitted connector files become governed managed assets or versions while every exception remains explicit and auditable.",
|
||||
"verification": "Compare the response summary and per-item outcomes with the files.connector.folder_synced audit event, then inspect provenance on representative created, updated, and unchanged assets.",
|
||||
"security_invariants": [
|
||||
"New API-managed external secret references fail closed until Files can prove ownership and provider-side deletion.",
|
||||
"Deletion and destructive retirement scrub Files-owned encrypted connector material before completion and emit non-secret audit evidence.",
|
||||
"Legacy non-owned external references are detached and audited, never sent to an arbitrary provider delete operation.",
|
||||
"Connector-space removal is local and soft; it never claims to delete remote or previously imported managed content.",
|
||||
"Folder sync is bounded, path-contained, policy-checked per item, and never includes remote bytes or credentials in audit details.",
|
||||
"Two-way connector mode is explicit and S3-only; it never enables automatic remote delete, rename, move, or ACL propagation.",
|
||||
],
|
||||
"related_topic_ids": [
|
||||
|
||||
Reference in New Issue
Block a user