Erase organization command in server CLI

docs/hosting/administration/erase_organization.rst

@@ -0,0 +1,98 @@
+.. Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS
+
+.. _doc_hosting_erase_organization:
+
+Erase an organization
+=====================
+
+Where & how the data are stored
+-------------------------------
+
+For any given organization, data are split as follow:
+
+- A PostgreSQL database containing the certificates (e.g. user/devices/workspaces) and
+  encrypted workspaces metadata (e.g. content of folder, list of blocks for each file version).
+- A blockstore (e.g. S3) containing the blocks (i.e. encrypted pieces of data that compose the files).
+- On top of that, each Parsec client having access to the organization has an encrypted local database
+  containing a copy of the certificates, metadata for the workspaces it has access to, and a subset
+  of the blocks (depending on local cache configuration).
+
+Erasing data
+------------
+
+When no longer in use (or for legal reason) an organization can be erased from the Parsec server.
+
+In practice this means:
+
+1. Removing everything (certificates & metadata) related to the organization in the PostgreSQL database.
+2. Removing the blocks from the blockstore.
+3. Removing the remaining data from the clients.
+
+Step 1: remove from PostgreSQL
+------------------------------
+
+Erasing an organization from Parsec is both an uncommon and (obviously !) a destructive operation.
+As such it is not available from the Administration API but instead must be triggered from the server CLI directly.
+
+.. code-block:: bash
+
+   # On Parsec server
+   parsec erase_organization --organization <OrgName> --db <database_url>
+
+.. warning::
+
+   This operation cannot be undone. Make sure you have a backup of any data you may need before
+   proceeding.
+
+.. note::
+
+   After erasing an organization, it is possible to create a new organization with the same name
+   since no trace of the previous one remains.
+
+   Even if they share the same name, the erased and the new organization are strictly unrelated
+   since they have a different root verify key (i.e. root key used to verify all certificates
+   in the organization).
+
+   Typically this means a Parsec client trying to access the erased organization will complain
+   it doesn't exist on the server even if a new organization with the same name exist.
+
+Step 2: Blockstore cleanup
+--------------------------
+
+Once step 1 done, the blocks' decryption keys has been lost. In other words, everything
+stored in the blockstore and related to the organization is irrecoverable.
+Hence removing those data from the blockstore should be seen as an optional step to reclaim
+needlessly occupied space.
+
+This can be done by manually removing from the blockstore the top level directory named after the organization.
+For example, if the organization was named ``CoolOrg``, remove the ``CoolOrg/`` prefix from the bucket.
+
+.. note::
+
+   Blockstores have their own backup strategy. Typically AWS S3 allows for a bucket to
+   have an history so that a data removal can be cancelled.
+   You should pay attention to this to ensure the blocks have actually been removed.
+
+Step 3: Clients cleanup
+-----------------------
+
+Once the organization erased from the server, the Parsec client will display an error
+about the organization not being found on the server.
+However the client can still work in offline mode (if the server is not reachable, the
+client cannot know the organization has been erased from the server!),
+
+For this reason, an end-user is still able to use his Parsec client to work on the
+organization using the local cache (e.g. creating a new file in a workspace or
+reading an existing file that is in cache).
+
+To prevent the users from accessing the local cache, the local configuration and data should be manually removed:
+
+- Linux:
+   - config: ``$XDG_DATA_HOME or $HOME/.local/share/parsec3/<device_id>`` (e.g. ``/home/alice/.local/share/parsec3/e68b7131394749a4bbd279bd087e6ae6``)
+   - data: ``$XDG_CONFIG_HOME or $HOME/.config/parsec3/libparsec/devices/<device_id>`` (e.g. ``/home/alice/.config/parsec3/libparsec/devices/e68b7131394749a4bbd279bd087e6ae6``)
+- macOS:
+   - config: ``$HOME/Library/Application Support/parsec3/<device_id>`` (e.g. ``/Users/Alice/Library/Application Support/parsec3/e68b7131394749a4bbd279bd087e6ae6``)
+   - data: ``$HOME/Library/Application Support/parsec3/libparsec/devices/<device_id>`` (e.g. ``/Users/Alice/Library/Application Support/parsec3/libparsec/devices/e68b7131394749a4bbd279bd087e6ae6``)
+- Windows:
+   - config: ``{FOLDERID_RoamingAppData}\parsec3\<device_id>`` (e.g. ``C:\Users\Alice\AppData\Roaming\parsec3\e68b7131394749a4bbd279bd087e6ae6``)
+   - data: ``{FOLDERID_RoamingAppData}\parsec3\libparsec\devices\<device_id>`` (e.g. ``C:\Users\Alice\AppData\Roaming/parsec3/libparsec/devices/e68b7131394749a4bbd279bd087e6ae6``)

docs/hosting/administration/index.rst

@@ -13,3 +13,4 @@ Server Administration
     stats_organization
     freeze_users
     shared_recovery
+    erase_organization

server/parsec/backend.py

@@ -156,9 +156,6 @@ async def test_customize_organization(
             skip_events_offset=len(template.events),
         )
 
-    async def test_drop_organization(self, id: OrganizationID) -> None:
-        await self.organization.test_drop_organization(id)
-
     async def test_load_template(self, template: TestbedTemplateContent) -> OrganizationID:
         org_id = OrganizationID(f"{template.id.title().replace('_', '')}OrgTemplate")
         match await self.organization.create(

server/parsec/cli/__init__.py

@@ -8,6 +8,7 @@
 
 import click
 
+from parsec.cli.erase_organization import erase_organization
 from parsec.cli.export import export_realm
 from parsec.cli.export_email import export_email
 from parsec.cli.inspect import human_accesses
@@ -45,6 +46,7 @@ def cli() -> None:
     pass
 
 
+cli.add_command(erase_organization, "erase_organization")
 cli.add_command(run_cmd, "run")
 cli.add_command(migrate, "migrate")
 cli.add_command(export_realm, "export_realm")

server/parsec/cli/erase_organization.py

@@ -0,0 +1,139 @@
+# Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import click
+
+from parsec._parsec import (
+    OrganizationID,
+)
+from parsec.cli.options import (
+    db_server_options,
+    debug_config_options,
+    logging_config_options,
+)
+from parsec.cli.testbed import if_testbed_available
+from parsec.cli.utils import cli_exception_handler, spinner, start_backend
+from parsec.components.organization import OrganizationEraseBadOutcome
+from parsec.config import (
+    BaseDatabaseConfig,
+    DisabledBlockStoreConfig,
+    LogLevel,
+    MockedBlockStoreConfig,
+)
+
+
+class DevOption(click.Option):
+    def handle_parse_result(
+        self, ctx: click.Context, opts: Any, args: list[str]
+    ) -> tuple[Any, list[str]]:
+        value, args = super().handle_parse_result(ctx, opts, args)
+        if value:
+            for key, value in (
+                ("debug", True),
+                ("db", "MOCKED"),
+                ("with_testbed", "coolorg"),
+                ("organization", "CoolorgOrgTemplate"),
+            ):
+                if key not in opts:
+                    opts[key] = value
+
+        return value, args
+
+
+@click.command(short_help="Erase an organization from the database")
+@click.option("--organization", type=OrganizationID, help="Organization ID", required=True)
+@click.option("--yes", is_flag=True, help="Don't ask for confirmation before proceeding")
+@db_server_options
+# Add --log-level/--log-format/--log-file
+@logging_config_options(default_log_level="INFO")
+# Add --debug & --version
+@debug_config_options
+@if_testbed_available(
+    click.option("--with-testbed", help="Start by populating with a testbed template")
+)
+@if_testbed_available(
+    click.option(
+        "--dev",
+        cls=DevOption,
+        is_flag=True,
+        is_eager=True,
+        help=(
+            "Equivalent to `--debug --db=MOCKED --with-testbed=coolorg --organization CoolorgOrgTemplate`"
+        ),
+    )
+)
+def erase_organization(
+    organization: OrganizationID,
+    db: BaseDatabaseConfig,
+    db_max_connections: int,
+    db_min_connections: int,
+    log_level: LogLevel,
+    log_format: str,
+    log_file: str | None,
+    yes: bool,
+    debug: bool,
+    with_testbed: str | None = None,
+    dev: bool = False,
+) -> None:
+    with cli_exception_handler(debug):
+        asyncio.run(
+            _erase_organization(
+                yes=yes,
+                db_config=db,
+                debug=debug,
+                with_testbed=with_testbed,
+                organization_id=organization,
+            )
+        )
+
+
+async def _erase_organization(
+    db_config: BaseDatabaseConfig,
+    yes: bool,
+    debug: bool,
+    with_testbed: str | None,
+    organization_id: OrganizationID,
+) -> None:
+    # Can use a dummy blockstore config since we are not going to query it
+    if with_testbed is None:
+        blockstore_config = DisabledBlockStoreConfig()
+    else:
+        # Testbed template might need to create some blocks
+        blockstore_config = MockedBlockStoreConfig()
+
+    display_org = click.style(organization_id.str, fg="yellow")
+    click.echo(
+        f"You are about to entirely erase the {display_org} organization from the database, this action cannot be undone."
+    )
+
+    display_bucket_path = click.style(f"{organization_id.str}/", fg="yellow")
+    click.echo("Notes:")
+    click.echo(
+        "- No trace of the organization will remain, so it will be possible to re-create another organization with the same name."
+    )
+    click.echo(
+        f"- The organization's blocks won't be erased from the blockstore, you should manually remove the {display_bucket_path} top level directory from it."
+    )
+    click.echo("")
+
+    if not yes:
+        confirmation = click.prompt("To confirm, type the name of the organization")
+        if confirmation != organization_id.str:
+            raise RuntimeError("Organization name does not match, aborting")
+
+    async with start_backend(
+        db_config=db_config,
+        blockstore_config=blockstore_config,
+        debug=debug,
+        populate_with_template=with_testbed,
+    ) as backend:
+        async with spinner("Removing from database..."):
+            outcome = await backend.organization.erase(id=organization_id)
+            match outcome:
+                case None:
+                    pass
+                case OrganizationEraseBadOutcome.ORGANIZATION_NOT_FOUND:
+                    raise RuntimeError("Organization doesn't exist")

server/parsec/cli/testbed.py

@@ -179,9 +179,10 @@ async def customize_organization(self, id: OrganizationID, customization: bytes)
         cooked_customization = testbed.test_load_testbed_customization(template, customization)  # pyright: ignore [reportPossiblyUnboundVariable]
         await self.backend.test_customize_organization(id, template, cooked_customization)
 
-    async def drop_organization(self, id: OrganizationID) -> None:
-        await self.backend.test_drop_organization(id)
-        del self.template_per_org[id]
+    async def drop_organization_idempotent(self, id: OrganizationID) -> None:
+        # Ignore errors (in case the organization doesn't exist) to be idempotent
+        await self.backend.organization.erase(id)
+        self.template_per_org.pop(id, None)
 
 
 testbed_router = APIRouter(tags=["testbed"])
@@ -244,8 +245,7 @@ async def test_new(template: str, request: Request, background_tasks: Background
         async def _organization_garbage_collector():
             await asyncio.sleep(orga_life_limit)
             logger.info("Dropping testbed org due to time limit", organization=new_org_id.str)
-            # Dropping is idempotent, so no need for error handling
-            await testbed.backend.test_drop_organization(new_org_id)
+            await testbed.drop_organization_idempotent(new_org_id)
 
         background_tasks.add_task(_organization_garbage_collector)
 
@@ -279,8 +279,7 @@ async def test_drop(raw_organization_id: str, request: Request) -> Response:
     except ValueError:
         return Response(status_code=400, content=b"")
 
-    # Dropping is idempotent, so no need for error handling
-    await testbed.drop_organization(organization_id)
+    await testbed.drop_organization_idempotent(organization_id)
 
     return Response(status_code=200, content=b"")
 

server/parsec/components/memory/organization.py

@@ -31,6 +31,7 @@
     OrganizationCreateBadOutcome,
     OrganizationDump,
     OrganizationDumpTopics,
+    OrganizationEraseBadOutcome,
     OrganizationGetBadOutcome,
     OrganizationGetTosBadOutcome,
     OrganizationStats,
@@ -383,6 +384,16 @@ async def update(
         if tos is not Unset:
             await self._event_bus.send(EventOrganizationTosUpdated(organization_id=id))
 
+    @override
+    async def erase(
+        self,
+        id: OrganizationID,
+    ) -> None | OrganizationEraseBadOutcome:
+        try:
+            del self._data.organizations[id]
+        except KeyError:
+            return OrganizationEraseBadOutcome.ORGANIZATION_NOT_FOUND
+
     @override
     async def get_tos(
         self, id: OrganizationID
@@ -437,10 +448,6 @@ async def test_dump_topics(self, id: OrganizationID) -> OrganizationDumpTopics:
             shamir_recovery=org.per_topic_last_timestamp.get("shamir_recovery"),
         )
 
-    @override
-    async def test_drop_organization(self, id: OrganizationID) -> None:
-        self._data.organizations.pop(id, None)
-
     @override
     async def test_duplicate_organization(
         self, source_id: OrganizationID, target_id: OrganizationID

server/parsec/components/organization.py

@@ -227,6 +227,10 @@ class OrganizationUpdateBadOutcome(BadOutcomeEnum):
     ORGANIZATION_NOT_FOUND = auto()
 
 
+class OrganizationEraseBadOutcome(BadOutcomeEnum):
+    ORGANIZATION_NOT_FOUND = auto()
+
+
 @dataclass(slots=True)
 class OrganizationDumpTopics:
     common: DateTime
@@ -316,6 +320,12 @@ async def update(
     ) -> None | OrganizationUpdateBadOutcome:
         raise NotImplementedError
 
+    async def erase(
+        self,
+        id: OrganizationID,
+    ) -> None | OrganizationEraseBadOutcome:
+        raise NotImplementedError
+
     async def get_tos(
         self, id: OrganizationID
     ) -> TermsOfService | None | OrganizationGetTosBadOutcome:
@@ -329,9 +339,6 @@ async def test_dump_organizations(
     async def test_dump_topics(self, id: OrganizationID) -> OrganizationDumpTopics:
         raise NotImplementedError
 
-    async def test_drop_organization(self, id: OrganizationID) -> None:
-        raise NotImplementedError
-
     async def test_duplicate_organization(
         self, source_id: OrganizationID, target_id: OrganizationID
     ) -> None: