obsideo-cli 0.2.0__py3-none-any.whl

obsideo/sync.py

@@ -0,0 +1,122 @@
+"""Sync a local folder with an Obsideo remote prefix (default 'sync/').
+
+Encrypts on push, decrypts on pull (account data key). Tracks state in a local
+manifest so unchanged files are skipped. Adapted from Cloud_Terminal's sync onto
+the Obsideo storage seam.
+"""
+
+import sys
+from pathlib import Path
+
+from obsideo_core import config, crypto, storage
+from obsideo import manifest
+
+REMOTE_PREFIX = "sync/"
+
+
+def _sync_dir() -> Path:
+    return Path(config.load_config().get("sync_dir", str(Path.home() / "obsideo-sync")))
+
+
+def _remote_key(name: str) -> str:
+    return f"{REMOTE_PREFIX}{name}"
+
+
+def sync_status() -> dict:
+    sync_dir = _sync_dir()
+    entries = manifest.get_all()
+    status = {"to_push": [], "to_pull": [], "synced": []}
+
+    local_files = {}
+    if sync_dir.exists():
+        local_files = {f.name: f for f in sync_dir.iterdir() if f.is_file()}
+
+    for name, f in local_files.items():
+        local_hash = manifest.file_sha256(f)
+        entry = entries.get(name)
+        if entry is None or entry.get("local_hash") != local_hash:
+            status["to_push"].append(name)
+        else:
+            status["synced"].append(name)
+
+    # Remote files we know about but don't have locally.
+    try:
+        remote = storage.list_prefix(REMOTE_PREFIX)
+        remote_names = {f["name"] for f in remote["files"]}
+    except Exception:
+        remote_names = set(entries.keys())
+    for name in remote_names:
+        if name not in local_files:
+            status["to_pull"].append(name)
+
+    return status
+
+
+def push(verbose: bool = True) -> int:
+    sync_dir = _sync_dir()
+    if not sync_dir.exists():
+        if verbose:
+            print(f"Sync folder does not exist: {sync_dir}")
+        return 0
+
+    do_encrypt = config.load_config().get("encrypt", True)
+    entries = manifest.get_all()
+    pushed = 0
+
+    for f in (p for p in sync_dir.iterdir() if p.is_file()):
+        local_hash = manifest.file_sha256(f)
+        entry = entries.get(f.name)
+        if entry and entry.get("local_hash") == local_hash:
+            if verbose:
+                print(f"  {f.name} - unchanged, skipping")
+            continue
+
+        raw = f.read_bytes()
+        body = crypto.encrypt(raw) if do_encrypt else raw
+        try:
+            key = storage.put(_remote_key(f.name), body)
+            manifest.upsert(f.name, remote_key=key, local_hash=local_hash,
+                            size=len(raw), encrypted=do_encrypt)
+            pushed += 1
+            if verbose:
+                print(f"  {f.name} - uploaded")
+        except Exception as e:
+            print(f"  {f.name} - FAILED: {e}", file=sys.stderr)
+
+    return pushed
+
+
+def pull(verbose: bool = True) -> int:
+    sync_dir = _sync_dir()
+    sync_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        remote = storage.list_prefix(REMOTE_PREFIX)
+    except Exception as e:
+        print(f"Failed to list remote: {e}", file=sys.stderr)
+        return 0
+
+    pulled = 0
+    for rf in remote["files"]:
+        name = rf["name"]
+        local_file = sync_dir / name
+        try:
+            blob = storage.get(rf["key"])
+            try:
+                raw = crypto.decrypt(blob)
+                encrypted = True
+            except Exception:
+                raw = blob  # was stored unencrypted
+                encrypted = False
+            local_file.parent.mkdir(parents=True, exist_ok=True)
+            local_file.write_bytes(raw)
+            manifest.upsert(name, remote_key=rf["key"],
+                            local_hash=manifest.file_sha256(local_file),
+                            size=len(raw), encrypted=encrypted)
+            pulled += 1
+            if verbose:
+                print(f"  {name} - downloaded")
+        except Exception as e:
+            print(f"  {name} - FAILED: {e}", file=sys.stderr)
+
+    return pulled

obsideo_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: obsideo-cli
+Version: 0.2.0
+Summary: Obsideo Cloud - encrypted storage we can't read. Save, browse, and sync whatever you want, from your terminal.
+License: MIT
+Project-URL: Homepage, https://obsideo.io
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: boto3>=1.28
+Requires-Dist: cryptography>=41.0
+
+# obsideo-cli
+
+**Encrypted storage we can't read.** Save, browse, and sync whatever you want
+from your terminal. Files are encrypted on your machine before they leave, so
+Obsideo's gateway, coordinator, and storage providers only ever see ciphertext.
+Your data lands on three independent providers (RF=3).
+
+```
+pip install obsideo-cli
+obsideo login    # email -> 3 GB free
+obsideo          # open the shell
+```
+
+## Get started
+
+```
+$ obsideo login
+Enter your email: you@example.com
+Check your email for a verification code.
+Enter verification code: 482913
+You're all set. 3 GB free.
+```
+
+Login is handled by Obsideo's signup service at **`signup.obsideo.io`**: it emails
+you a one-time code and provisions your free tier. There's no password - just your
+email and a local key (see *How it works*).
+
+Then either drop into the shell or run one-shot commands:
+
+```
+$ obsideo
+obsideo:/ put ~/notes.txt
+obsideo:/ ls
+  [file] notes.txt  1.2 KB
+obsideo:/ put ~/photos                       # a whole folder, uploaded recursively
+obsideo:/ put "C:\My Files\tax return.pdf"   # paths with spaces: just quote them
+obsideo:/ mkdir trip
+obsideo:/ cd trip
+obsideo:/trip/ put ~/cat.jpg
+obsideo:/trip/ get cat.jpg ./downloaded.jpg
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `obsideo login` | Sign up / log in with your email (3 GB free) |
+| `ls [path]` | List files and folders |
+| `cd <path>` / `pwd` | Move around / show location |
+| `put <local> [name]` | Encrypt + upload a file, or a whole folder (recursive). `--no-encrypt` to store as-is |
+| `get <remote> [local]` | Download + decrypt a file |
+| `rm <remote>` | Delete a file |
+| `mkdir <name>` | Create a folder |
+| `info <remote>` | Show object metadata |
+| `account` | Show storage used vs. your free quota |
+| `sync push\|pull\|status` | Sync your local folder with Obsideo |
+| `config [set k v]` | Show or change settings |
+
+## How it works
+
+`obsideo` is a thin front-end over the shared **`obsideo_core`** layer (storage
+seam, signing identity, account crypto, email-OTP login). The `mlvault` ML
+extension builds on the same core - build the core once, two front-ends.
+
+- **Encryption:** AES-256-GCM with one account data key held locally at
+  `~/.obsideo/data.key`. Copy that key to another machine and everything is
+  readable there; lose it and the data is unrecoverable by design. Back it up.
+- **Signing identity:** an Ed25519 key (`~/.obsideo/signing.key`) authorizes
+  deletes (Principle 2 - the network can't delete your data without your
+  signature). Generated locally; only the public half is ever sent.
+- **Filename encryption:** on by default (`encrypt_names`). Each path component
+  (folder names + filename) is encrypted on your machine with AES-SIV - deterministic,
+  so `ls`/`cd` still list under the encrypted prefix and the client decrypts the
+  returned tokens back to real names. Turn it off with `config set encrypt_names false`
+  (interop/debug; existing objects aren't migrated).
+- **What Obsideo sees:** ciphertext only - never a filename or a byte of content.
+  Residual leaks (by design at this level): directory *structure* (depth, fan-out),
+  object *sizes* (ciphertext ≈ plaintext), and object *counts*. Identical names
+  encrypt to identical tokens, so Obsideo can tell two objects share a name - never
+  what it is.
+
+## License
+
+MIT

obsideo_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+obsideo/__init__.py,sha256=ZPShIsPWHXlDcefLQSIXhnTGwX21JmO4KSQ86OYQVHU,80
+obsideo/__main__.py,sha256=TmRjTS_kputEIVdtJpmDI3rl4-adUGLQTBZlaKO3ioU,68
+obsideo/cli.py,sha256=21o1xFd_ZIxRCtbKcsTq5ZJcKde5N0WawblozEhyb0c,22590
+obsideo/manifest.py,sha256=w_7puCrq0-BDI5sZ2VZPqiHScipvMKFtskDZjJtJXHk,1500
+obsideo/sync.py,sha256=hVjE-rSXJxrroHvH-EZ0YbQ3ZD8ARVR9Q1Pr-2zM5PQ,3807
+obsideo_core/__init__.py,sha256=xpfSGgKEuesL945_rq0KnThKaIkDtuhaygTH98jVkFs,239
+obsideo_core/config.py,sha256=IUs2hcTrBjuid0-uyv3_IqUKR7ZQGxR1-maiZl0sjH8,4706
+obsideo_core/crypto.py,sha256=xx4HXDVzTWItp9kdUeMzcRkEiI2RGqbCIyj1FEBmUF8,1632
+obsideo_core/identity.py,sha256=cfPAxeIqcPKA4CEirIhWTLAII1jIAQhk4Jfw8F70GOY,1429
+obsideo_core/login.py,sha256=o_WiJ57Jt1FG0fPpHOZjPL4GFLLaD529_9LB7w7rwls,1907
+obsideo_core/names.py,sha256=MntkjDPgOckKn6vgE4Zh2qAURlxx6jm7d9JxZH97P0s,2495
+obsideo_core/storage.py,sha256=sv-STw0gFAeSNsyXzLcyJ0Wk2MkxKyPaAas2WmA7Pjw,9295
+obsideo_cli-0.2.0.dist-info/METADATA,sha256=Tc53lh92MCKH8f2R4zn4IfhjEJhZ8RKmqURsn77f-cA,3780
+obsideo_cli-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+obsideo_cli-0.2.0.dist-info/entry_points.txt,sha256=dKCugMhoQhpPZuvGDGsw3pGCquJxc2aOPfQOEZKKM-s,76
+obsideo_cli-0.2.0.dist-info/top_level.txt,sha256=eqmkFbh045p9o5Q-Z7zy5aFRVKi4xpFs0iFflygtHZU,21
+obsideo_cli-0.2.0.dist-info/RECORD,,

obsideo_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

obsideo_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+obsideo = obsideo.cli:main
+obsideo-cli = obsideo.cli:main

obsideo_cli-0.2.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+obsideo
+obsideo_core

obsideo_core/__init__.py

@@ -0,0 +1,4 @@
+"""Obsideo core — the shared client layer for the Obsideo CLI and the mlvault
+extension: storage seam, signing identity, account-level crypto, email-OTP login,
+and config. Client encrypts; Obsideo sees ciphertext only (Principle 1).
+"""

obsideo_core/config.py

@@ -0,0 +1,120 @@
+"""Config + credential loading for the Obsideo core.
+
+Everything lives under ~/.obsideo:
+    credentials   # OBSIDEO_S3_* + OBSIDEO_ACCOUNT_TOKEN (written by `obsideo login`)
+    config.json   # user settings (default bucket, encrypt flag, sync dir, cwd)
+    data.key      # account data-encryption key (see crypto.py)
+    signing.key   # Ed25519 signing private key (see identity.py)
+"""
+
+import json
+import os
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".obsideo"
+CREDENTIALS_FILE = CONFIG_DIR / "credentials"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+DEFAULT_CONFIG = {
+    "bucket": "obsideo",
+    "encrypt": True,          # encrypt file contents
+    "encrypt_names": True,    # encrypt file/folder names (metadata privacy)
+    "sync_dir": str(Path.home() / "obsideo-sync"),
+}
+
+_DEFAULT_ENDPOINT = "https://s3.obsideo.io"
+_DEFAULT_REGION = "us-east-1"
+
+# Sent on every request to the signup shim. A descriptive User-Agent avoids
+# Cloudflare's default-`Python-urllib` bot block (HTTP 403 / error 1010) that
+# fronts signup.obsideo.io; without it, `obsideo login` and usage lookups fail.
+try:
+    from importlib.metadata import version as _pkg_version, PackageNotFoundError
+    try:
+        _VERSION = _pkg_version("obsideo-cloud")
+    except PackageNotFoundError:
+        _VERSION = "0.2.0"
+except Exception:
+    _VERSION = "0.2.0"
+
+USER_AGENT = f"obsideo-cloud/{_VERSION}"
+
+
+def write_secret_file(path: Path, value: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(value)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass  # Windows
+
+
+def _load_env_file(path: Path) -> None:
+    """Load key=value pairs into os.environ (no-overwrite)."""
+    if not path.exists():
+        return
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        os.environ.setdefault(key.strip(), val.strip().strip("'\""))
+
+
+# Load saved credentials into the environment on import (no-overwrite, so explicit
+# env vars still win). storage.py reads OBSIDEO_S3_* from the environment.
+_load_env_file(CREDENTIALS_FILE)
+
+
+# ── User config ─────────────────────────────────────────────────────────────
+
+def load_config() -> dict:
+    cfg = dict(DEFAULT_CONFIG)
+    if CONFIG_FILE.exists():
+        try:
+            cfg.update(json.loads(CONFIG_FILE.read_text()))
+        except Exception:
+            pass
+    return cfg
+
+
+def save_config(cfg: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(cfg, indent=2))
+
+
+# ── Credentials ─────────────────────────────────────────────────────────────
+
+def write_credentials(creds: dict) -> None:
+    """Persist the credential bundle returned by `obsideo login`."""
+    lines = [
+        f"OBSIDEO_S3_ENDPOINT={creds.get('endpoint', _DEFAULT_ENDPOINT)}",
+        f"OBSIDEO_S3_ACCESS_KEY={creds['access_key']}",
+        f"OBSIDEO_S3_SECRET_KEY={creds['secret_key']}",
+        f"OBSIDEO_S3_BUCKET={creds.get('bucket', DEFAULT_CONFIG['bucket'])}",
+        f"OBSIDEO_S3_REGION={creds.get('region', _DEFAULT_REGION)}",
+    ]
+    if creds.get("account_token"):
+        lines.append(f"OBSIDEO_ACCOUNT_TOKEN={creds['account_token']}")
+    write_secret_file(CREDENTIALS_FILE, "\n".join(lines) + "\n")
+    # Reflect immediately for the current process (write_secret_file already wrote
+    # the file; force these into env even if already set from a prior session).
+    os.environ["OBSIDEO_S3_ENDPOINT"] = creds.get("endpoint", _DEFAULT_ENDPOINT)
+    os.environ["OBSIDEO_S3_ACCESS_KEY"] = creds["access_key"]
+    os.environ["OBSIDEO_S3_SECRET_KEY"] = creds["secret_key"]
+    os.environ["OBSIDEO_S3_BUCKET"] = creds.get("bucket", DEFAULT_CONFIG["bucket"])
+    os.environ["OBSIDEO_S3_REGION"] = creds.get("region", _DEFAULT_REGION)
+    if creds.get("account_token"):
+        os.environ["OBSIDEO_ACCOUNT_TOKEN"] = creds["account_token"]
+
+
+def is_logged_in() -> bool:
+    return bool(os.environ.get("OBSIDEO_S3_ACCESS_KEY") and os.environ.get("OBSIDEO_S3_SECRET_KEY"))
+
+
+def account_token() -> str | None:
+    return os.environ.get("OBSIDEO_ACCOUNT_TOKEN")
+
+
+def signup_url() -> str:
+    return os.environ.get("OBSIDEO_SIGNUP_URL", "https://signup.obsideo.io")

obsideo_core/crypto.py

@@ -0,0 +1,50 @@
+"""Account-level AES-256-GCM encryption for the general CLI.
+
+One data key per account, held locally at ~/.obsideo/data.key. Every file is
+encrypted with that key and a fresh random nonce (prepended). Any file the
+account uploaded can be decrypted with this one key, which is what makes
+browse/download/sync work across machines — copy this key to a new machine and
+everything is readable.
+
+This differs from the mlvault extension's per-run keys (immutable ML bundles); a
+general file store wants one stable key. Lose the key, lose the data — by design.
+Back it up alongside your credentials.
+"""
+
+import os
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from obsideo_core import config
+
+DATA_KEY_FILE = config.CONFIG_DIR / "data.key"
+
+
+def data_key() -> bytes:
+    """Load or generate the 32-byte account data key."""
+    env = os.environ.get("OBSIDEO_DATA_KEY", "").strip()
+    if env:
+        return bytes.fromhex(env)
+    if DATA_KEY_FILE.exists():
+        return bytes.fromhex(DATA_KEY_FILE.read_text().strip())
+    key = os.urandom(32)
+    config.write_secret_file(DATA_KEY_FILE, key.hex())
+    return key
+
+
+def encrypt(data: bytes) -> bytes:
+    """AES-256-GCM. Returns nonce(12) + ciphertext+tag."""
+    key = data_key()
+    nonce = os.urandom(12)
+    return nonce + AESGCM(key).encrypt(nonce, data, None)
+
+
+def decrypt(blob: bytes) -> bytes:
+    """Inverse of encrypt. Raises on auth failure / wrong key."""
+    key = data_key()
+    nonce, ct = blob[:12], blob[12:]
+    return AESGCM(key).decrypt(nonce, ct, None)
+
+
+def data_key_backup_hint() -> str:
+    return f"OBSIDEO_DATA_KEY={data_key().hex()}"

obsideo_core/identity.py

@@ -0,0 +1,36 @@
+"""Client-held signing identity (Ed25519).
+
+Obsideo external accounts require a customer Ed25519 signing public key — it
+authorizes destructive operations on your data (Principle 2: the network can't
+delete your data without your signature). The PRIVATE half is generated here and
+never leaves your machine; only the public key (obk_sig_…) is sent at signup.
+"""
+
+import base64
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.serialization import (
+    Encoding, NoEncryption, PrivateFormat, PublicFormat,
+)
+
+from obsideo_core import config
+
+SIGNING_KEY_FILE = config.CONFIG_DIR / "signing.key"
+
+
+def _encode_pub(raw: bytes) -> str:
+    return "obk_sig_" + base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def get_or_create_signing_pubkey() -> str:
+    """Return the Ed25519 signing public key as 'obk_sig_<43 chars>',
+    generating + persisting the private key locally (0600) on first use."""
+    if SIGNING_KEY_FILE.exists():
+        raw = bytes.fromhex(SIGNING_KEY_FILE.read_text().strip())
+        priv = Ed25519PrivateKey.from_private_bytes(raw)
+    else:
+        priv = Ed25519PrivateKey.generate()
+        raw = priv.private_bytes(Encoding.Raw, PrivateFormat.Raw, NoEncryption())
+        config.write_secret_file(SIGNING_KEY_FILE, raw.hex())
+    pub = priv.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+    return _encode_pub(pub)

obsideo_core/login.py

@@ -0,0 +1,58 @@
+"""Email-OTP login against the Obsideo signup shim (obsideo-signup).
+
+UI-agnostic: callers (the CLI) handle prompting; these functions do the HTTP and
+return data. No new dependencies (stdlib urllib).
+"""
+
+import json
+import urllib.error
+import urllib.request
+
+from obsideo_core import config, identity
+
+
+class LoginError(RuntimeError):
+    pass
+
+
+def _post_json(url: str, payload: dict) -> dict:
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={"Content-Type": "application/json", "User-Agent": config.USER_AGENT},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        try:
+            detail = json.loads(e.read().decode()).get("detail", "")
+        except Exception:
+            detail = ""
+        raise LoginError(detail or f"HTTP {e.code}")
+    except urllib.error.URLError as e:
+        raise LoginError(f"could not reach {url}: {e.reason}")
+
+
+def start(email: str, url: str | None = None) -> None:
+    """Request a verification code be emailed to `email`."""
+    url = url or config.signup_url()
+    _post_json(f"{url}/v1/auth/start", {"email": email})
+
+
+def verify(email: str, code: str, url: str | None = None) -> dict:
+    """Verify the code + provision an account. Generates the local signing key,
+    sends only its public half, persists the returned credentials. Returns the
+    credential bundle.
+    """
+    url = url or config.signup_url()
+    signing_pubkey = identity.get_or_create_signing_pubkey()
+    creds = _post_json(f"{url}/v1/auth/verify", {
+        "email": email,
+        "code": code,
+        "customer_signing_public_key": signing_pubkey,
+    })
+    config.write_credentials(creds)
+    return creds

obsideo_core/names.py

@@ -0,0 +1,65 @@
+"""Deterministic filename encryption (Level 1 metadata privacy).
+
+Object keys (folder paths + filenames) would otherwise reach Obsideo in the clear,
+leaking the *shape* of your data even though contents are encrypted. This encrypts
+each path component client-side with **AES-SIV** (deterministic, misuse-resistant
+authenticated encryption) keyed off your data key, so `photos/tax.pdf` is stored
+as opaque tokens.
+
+Why deterministic: identical input → identical token, which is what lets the
+server still do prefix listing — `ls` lists under the encrypted prefix and the
+client decrypts the returned tokens back to real names. Residual leak (accepted at
+Level 1): the same name encrypts to the same token, so Obsideo can see that two
+objects share a name, never what it is; structure + sizes still show.
+
+SCHEME (so other clients — e.g. the SDK — can interop, same account same names):
+  name_key = HKDF-SHA256(ikm=data_key, salt="", info="obsideo-name-key-v1", len=64)
+  token    = base64url-nopad( AES-SIV-encrypt(name_key, utf8(component), aad=none) )
+  path     = "/".join(token(c) for c in path.split("/") if c)
+"""
+
+import base64
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESSIV
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from obsideo_core import crypto
+
+_INFO = b"obsideo-name-key-v1"
+
+
+def _name_key() -> bytes:
+    # Derived fresh from the data key (cheap); stays correct if the key changes.
+    return HKDF(algorithm=hashes.SHA256(), length=64, salt=None, info=_INFO).derive(crypto.data_key())
+
+
+def _b64e(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
+
+
+def _b64d(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def encrypt_name(name: str) -> str:
+    return _b64e(AESSIV(_name_key()).encrypt(name.encode(), None))
+
+
+def decrypt_name(token: str) -> str:
+    return AESSIV(_name_key()).decrypt(_b64d(token), None).decode()
+
+
+def encrypt_path(path: str) -> str:
+    """Encrypt each '/'-separated component. Empty -> empty (root)."""
+    return "/".join(encrypt_name(c) for c in path.split("/") if c)
+
+
+def safe_decrypt_name(token: str) -> tuple[str, bool]:
+    """Decrypt a listed token. Returns (name, was_encrypted). Falls back to the
+    raw token for legacy clear-name objects (so listings never crash on a mixed
+    account)."""
+    try:
+        return decrypt_name(token), True
+    except Exception:
+        return token, False