sg-send-cli 0.3.0__tar.gz

sg_send_cli-0.3.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sg_send_cli-0.3.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.1
+Name: sg-send-cli
+Version: 0.3.0
+Summary: CLI tool for syncing encrypted vaults with SG/Send Transfer API
+Home-page: https://github.com/the-cyber-boardroom/SG_Send__CLI
+License: Apache-2.0
+Keywords: sg-send,vault,encryption,cli,sync
+Author: The Cyber Boardroom
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Dist: cryptography (>=43.0.0)
+Requires-Dist: osbot-utils (>=3.70.0)
+Project-URL: Repository, https://github.com/the-cyber-boardroom/SG_Send__CLI
+Description-Content-Type: text/markdown
+
+# SG_Send__CLI
+
+CLI tool for syncing encrypted vaults with SG/Send Transfer API.
+
+## Install
+
+```bash
+pip install sg-send-cli
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Architecture
+
+- `sg_send_cli/safe_types/` — Domain-specific Safe_* types (zero raw primitives)
+- `sg_send_cli/schemas/` — Pure data Type_Safe schemas
+- `sg_send_cli/crypto/` — AES-256-GCM encrypt/decrypt, PBKDF2, HKDF
+- `sg_send_cli/sync/` — Local ↔ remote vault sync (planned)
+- `sg_send_cli/api/` — SG/Send Transfer API client (planned)
+- `sg_send_cli/cli/` — CLI commands (planned)
+

sg_send_cli-0.3.0/README.md

@@ -0,0 +1,25 @@
+# SG_Send__CLI
+
+CLI tool for syncing encrypted vaults with SG/Send Transfer API.
+
+## Install
+
+```bash
+pip install sg-send-cli
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Architecture
+
+- `sg_send_cli/safe_types/` — Domain-specific Safe_* types (zero raw primitives)
+- `sg_send_cli/schemas/` — Pure data Type_Safe schemas
+- `sg_send_cli/crypto/` — AES-256-GCM encrypt/decrypt, PBKDF2, HKDF
+- `sg_send_cli/sync/` — Local ↔ remote vault sync (planned)
+- `sg_send_cli/api/` — SG/Send Transfer API client (planned)
+- `sg_send_cli/cli/` — CLI commands (planned)

sg_send_cli-0.3.0/pyproject.toml

@@ -0,0 +1,48 @@
+[tool.poetry]
+name        = "sg-send-cli"
+version     = "v0.3.0"
+description = "CLI tool for syncing encrypted vaults with SG/Send Transfer API"
+readme      = "README.md"
+license     = "Apache-2.0"
+authors     = ["The Cyber Boardroom"]
+keywords    = ["sg-send", "vault", "encryption", "cli", "sync"]
+homepage    = "https://github.com/the-cyber-boardroom/SG_Send__CLI"
+repository  = "https://github.com/the-cyber-boardroom/SG_Send__CLI"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+]
+packages = [{ include = "sg_send_cli" }]
+
+[tool.poetry.dependencies]
+python       = ">=3.11"
+osbot-utils  = ">=3.70.0"
+cryptography = ">=43.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest     = ">=8.0"
+pytest-cov = ">=5.0"
+
+[tool.poetry.scripts]
+sg-send-cli = "sg_send_cli.cli:main"
+
+[build-system]
+requires      = ["poetry-core>=1.9.1"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths        = ["tests"]
+addopts          = "-v --tb=short"
+python_files     = "test_*.py"
+python_classes   = "Test_*"
+python_functions = "test_*"
+
+[tool.coverage.run]
+source = ["sg_send_cli"]
+omit   = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true

sg_send_cli-0.3.0/sg_send_cli/__init__.py

@@ -0,0 +1 @@
+from sg_send_cli._version import VERSION

sg_send_cli-0.3.0/sg_send_cli/_version.py

@@ -0,0 +1 @@
+VERSION = 'v0.1.0'

sg_send_cli-0.3.0/sg_send_cli/api/Vault__API.py

@@ -0,0 +1,83 @@
+import json
+from   urllib.request                  import Request, urlopen
+from   urllib.error                    import HTTPError
+from   osbot_utils.type_safe.Type_Safe import Type_Safe
+
+DEFAULT_BASE_URL = 'https://send.sgraph.ai'
+
+
+class Vault__API(Type_Safe):
+    base_url     : str
+    access_token : str
+
+    def setup(self):
+        if not self.base_url:
+            self.base_url = DEFAULT_BASE_URL
+        return self
+
+    def write(self, vault_id: str, file_id: str, write_key: str, payload: bytes) -> dict:
+        url     = f'{self.base_url}/api/vault/write/{vault_id}/{file_id}'
+        headers = {'Content-Type'              : 'application/octet-stream',
+                    'x-sgraph-access-token': self.access_token,
+                    'x-sgraph-vault-write-key'  : write_key}
+        return self._request('PUT', url, headers, payload)
+
+    def read(self, vault_id: str, file_id: str) -> bytes:
+        url = f'{self.base_url}/api/vault/read/{vault_id}/{file_id}'
+        return self._request_bytes('GET', url)
+
+    def delete(self, vault_id: str, file_id: str, write_key: str) -> dict:
+        url     = f'{self.base_url}/api/vault/delete/{vault_id}/{file_id}'
+        headers = {'x-sgraph-access-token': self.access_token,
+                    'x-sgraph-vault-write-key'  : write_key}
+        return self._request('DELETE', url, headers)
+
+    def _request(self, method: str, url: str, headers: dict = None, data: bytes = None) -> dict:
+        req = Request(url, data=data, method=method)
+        if headers:
+            for key, value in headers.items():
+                req.add_header(key, value)
+        try:
+            with urlopen(req) as response:
+                body = response.read()
+                if body:
+                    return json.loads(body)
+                return {}
+        except HTTPError as e:
+            raise self._api_error(method, url, headers, e, data_size=len(data) if data else 0)
+
+    def _request_bytes(self, method: str, url: str, headers: dict = None) -> bytes:
+        req = Request(url, method=method)
+        if headers:
+            for key, value in headers.items():
+                req.add_header(key, value)
+        try:
+            with urlopen(req) as response:
+                return response.read()
+        except HTTPError as e:
+            raise self._api_error(method, url, headers, e)
+
+    def _api_error(self, method: str, url: str, headers: dict, error: HTTPError, data_size: int = 0) -> Exception:
+        response_body = ''
+        try:
+            response_body = error.read().decode('utf-8', errors='replace')
+        except Exception:
+            pass
+
+        masked_headers = {}
+        for k, v in (headers or {}).items():
+            if 'token' in k.lower() or 'key' in k.lower():
+                masked_headers[k] = f'{v[:8]}...({len(v)} chars)'
+            else:
+                masked_headers[k] = v
+
+        lines = [f'API Error: HTTP {error.code} {error.reason}',
+                 f'  Request:  {method} {url}',
+                 f'  Headers:  {json.dumps(masked_headers, indent=2)}']
+        if data_size:
+            lines.append(f'  Payload:  {data_size} bytes')
+        if response_body:
+            lines.append(f'  Response: {response_body}')
+
+        message = '\n'.join(lines)
+        return RuntimeError(message)

sg_send_cli-0.3.0/sg_send_cli/cli/__init__.py

@@ -0,0 +1,189 @@
+import argparse
+import os
+import sys
+from sg_send_cli.crypto.Vault__Crypto import Vault__Crypto
+from sg_send_cli.api.Vault__API       import Vault__API
+from sg_send_cli.sync.Vault__Sync     import Vault__Sync
+
+TOKEN_FILE = 'token'
+
+
+def _resolve_token(token: str, directory: str) -> str:
+    if token:
+        _save_token(token, directory)
+        return token
+    return _load_token(directory)
+
+
+def _save_token(token: str, directory: str):
+    sg_vault_dir = os.path.join(directory, '.sg_vault')
+    if os.path.isdir(sg_vault_dir):
+        token_path = os.path.join(sg_vault_dir, TOKEN_FILE)
+        with open(token_path, 'w') as f:
+            f.write(token)
+
+
+def _load_token(directory: str) -> str:
+    token_path = os.path.join(directory, '.sg_vault', TOKEN_FILE)
+    if os.path.isfile(token_path):
+        with open(token_path, 'r') as f:
+            return f.read().strip()
+    return ''
+
+
+def create_sync(base_url: str = None, access_token: str = None) -> Vault__Sync:
+    api = Vault__API(base_url=base_url or '', access_token=access_token or '')
+    api.setup()
+    return Vault__Sync(crypto=Vault__Crypto(), api=api)
+
+
+def cmd_clone(args):
+    sync      = create_sync(args.base_url, args.token)
+    directory = sync.clone(args.vault_key, args.directory)
+    if args.token:
+        _save_token(args.token, directory)
+    print(f'Cloned vault to {directory}/')
+
+
+def cmd_pull(args):
+    token  = _resolve_token(args.token, args.directory)
+    sync   = create_sync(args.base_url, token)
+    result = sync.pull(args.directory)
+    added  = len(result['added'])
+    modified = len(result['modified'])
+    deleted  = len(result['deleted'])
+    if added + modified + deleted == 0:
+        print('Already up to date.')
+    else:
+        for f in result['added']:
+            print(f'  + {f}')
+        for f in result['modified']:
+            print(f'  ~ {f}')
+        for f in result['deleted']:
+            print(f'  - {f}')
+        print(f'Pulled: {added} added, {modified} modified, {deleted} deleted')
+
+
+def cmd_push(args):
+    token  = _resolve_token(args.token, args.directory)
+    sync   = create_sync(args.base_url, token)
+    result = sync.push(args.directory)
+    added  = len(result['added'])
+    modified = len(result['modified'])
+    deleted  = len(result['deleted'])
+    if added + modified + deleted == 0:
+        print('Nothing to push — vault is up to date.')
+    else:
+        if added:
+            for f in sorted(result['added']):
+                print(f'  + {f}')
+        if modified:
+            for f in sorted(result['modified']):
+                print(f'  ~ {f}')
+        if deleted:
+            for f in sorted(result['deleted']):
+                print(f'  - {f}')
+        print(f'Pushed: {added} added, {modified} modified, {deleted} deleted')
+
+
+def cmd_status(args):
+    sync   = Vault__Sync(crypto=Vault__Crypto(), api=Vault__API())
+    result = sync.status(args.directory)
+    if result['clean']:
+        print('Vault is clean — no local changes.')
+    else:
+        for f in result['added']:
+            print(f'  + {f}')
+        for f in result['modified']:
+            print(f'  ~ {f}')
+        for f in result['deleted']:
+            print(f'  - {f}')
+
+
+def cmd_remote_status(args):
+    token  = _resolve_token(args.token, args.directory)
+    sync   = create_sync(args.base_url, token)
+    result = sync.remote_status(args.directory)
+
+    remote_changes = result['remote_added'] or result['remote_modified'] or result['remote_deleted']
+    local_changes  = result['local_added'] or result['local_modified'] or result['local_deleted']
+
+    print(f'Local version:  {result["local_version"]}')
+    print(f'Remote version: {result["remote_version"]}')
+    print()
+
+    if remote_changes:
+        print('Remote changes (not yet pulled):')
+        for f in result['remote_added']:
+            print(f'  + {f}')
+        for f in result['remote_modified']:
+            print(f'  ~ {f}')
+        for f in result['remote_deleted']:
+            print(f'  - {f}')
+    else:
+        print('Remote: up to date.')
+
+    if local_changes:
+        print('Local changes (not yet pushed):')
+        for f in result['local_added']:
+            print(f'  + {f}')
+        for f in result['local_modified']:
+            print(f'  ~ {f}')
+        for f in result['local_deleted']:
+            print(f'  - {f}')
+    else:
+        print('Local: clean.')
+
+
+def cmd_derive_keys(args):
+    crypto = Vault__Crypto()
+    keys   = crypto.derive_keys_from_vault_key(args.vault_key)
+    print(f'vault_id:         {keys["vault_id"]}')
+    print(f'read_key:         {keys["read_key"]}')
+    print(f'write_key:        {keys["write_key"]}')
+    print(f'tree_file_id:     {keys["tree_file_id"]}')
+    print(f'settings_file_id: {keys["settings_file_id"]}')
+
+
+def main():
+    parser = argparse.ArgumentParser(prog='sg-send-cli',
+                                     description='CLI tool for syncing encrypted vaults with SG/Send')
+    parser.add_argument('--base-url', default=None, help='API base URL (default: https://send.sgraph.ai)')
+    parser.add_argument('--token',    default=None, help='SG/Send access token')
+
+    subparsers = parser.add_subparsers(dest='command', help='Available commands')
+
+    clone_parser = subparsers.add_parser('clone', help='Clone a remote vault to a local directory')
+    clone_parser.add_argument('vault_key',  help='Vault key ({passphrase}:{vault_id})')
+    clone_parser.add_argument('directory',  nargs='?', default=None, help='Target directory (default: vault_id)')
+    clone_parser.set_defaults(func=cmd_clone)
+
+    pull_parser = subparsers.add_parser('pull', help='Pull remote changes to local directory')
+    pull_parser.add_argument('directory', nargs='?', default='.', help='Vault directory (default: .)')
+    pull_parser.set_defaults(func=cmd_pull)
+
+    push_parser = subparsers.add_parser('push', help='Push local changes to the remote vault')
+    push_parser.add_argument('directory', nargs='?', default='.', help='Vault directory (default: .)')
+    push_parser.set_defaults(func=cmd_push)
+
+    status_parser = subparsers.add_parser('status', help='Show local changes vs vault tree')
+    status_parser.add_argument('directory', nargs='?', default='.', help='Vault directory (default: .)')
+    status_parser.set_defaults(func=cmd_status)
+
+    remote_status_parser = subparsers.add_parser('remote-status', help='Compare local vault against remote')
+    remote_status_parser.add_argument('directory', nargs='?', default='.', help='Vault directory (default: .)')
+    remote_status_parser.set_defaults(func=cmd_remote_status)
+
+    keys_parser = subparsers.add_parser('derive-keys', help='Derive and display vault keys (debug)')
+    keys_parser.add_argument('vault_key', help='Vault key ({passphrase}:{vault_id})')
+    keys_parser.set_defaults(func=cmd_derive_keys)
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+    try:
+        args.func(args)
+    except RuntimeError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)

sg_send_cli-0.3.0/sg_send_cli/crypto/Vault__Crypto.py

@@ -0,0 +1,106 @@
+import hashlib
+import hmac
+import os
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf     import HKDF
+from cryptography.hazmat.primitives.kdf.pbkdf2   import PBKDF2HMAC
+from cryptography.hazmat.primitives               import hashes
+from osbot_utils.type_safe.Type_Safe              import Type_Safe
+
+PBKDF2_ITERATIONS = 600_000
+AES_KEY_BYTES     = 32
+GCM_IV_BYTES      = 12
+GCM_TAG_BYTES     = 16
+HKDF_INFO_PREFIX  = b'sg-send-file-key'
+
+SALT_PREFIX       = 'sg-vault-v1'
+WRITE_SALT_PREFIX = 'sg-vault-v1:write'
+TREE_DOMAIN       = 'sg-vault-v1:file-id:tree'
+SETTINGS_DOMAIN   = 'sg-vault-v1:file-id:settings'
+
+
+class Vault__Crypto(Type_Safe):
+
+    def parse_vault_key(self, vault_key: str) -> tuple:
+        parts = vault_key.rsplit(':', 1)
+        if len(parts) != 2 or not parts[0] or not parts[1]:
+            raise ValueError(f'Invalid vault key format: expected {{passphrase}}:{{vault_id}}')
+        passphrase = parts[0]
+        vault_id   = parts[1]
+        return passphrase, vault_id
+
+    def derive_read_key(self, passphrase: str, vault_id: str) -> bytes:
+        salt = f'{SALT_PREFIX}:{vault_id}'.encode()
+        return self.derive_key_from_passphrase(passphrase.encode(), salt)
+
+    def derive_write_key(self, passphrase: str, vault_id: str) -> bytes:
+        salt = f'{WRITE_SALT_PREFIX}:{vault_id}'.encode()
+        return self.derive_key_from_passphrase(passphrase.encode(), salt)
+
+    def derive_file_id(self, read_key: bytes, domain_string: str) -> str:
+        mac = hmac.new(read_key, domain_string.encode(), hashlib.sha256).hexdigest()
+        return mac[:12]
+
+    def derive_tree_file_id(self, read_key: bytes, vault_id: str) -> str:
+        domain = f'{TREE_DOMAIN}:{vault_id}'
+        return self.derive_file_id(read_key, domain)
+
+    def derive_settings_file_id(self, read_key: bytes, vault_id: str) -> str:
+        domain = f'{SETTINGS_DOMAIN}:{vault_id}'
+        return self.derive_file_id(read_key, domain)
+
+    def derive_keys(self, passphrase: str, vault_id: str) -> dict:
+        read_key_bytes   = self.derive_read_key(passphrase, vault_id)
+        write_key_bytes  = self.derive_write_key(passphrase, vault_id)
+        tree_file_id     = self.derive_tree_file_id(read_key_bytes, vault_id)
+        settings_file_id = self.derive_settings_file_id(read_key_bytes, vault_id)
+        return dict(read_key_bytes   = read_key_bytes,
+                    read_key         = read_key_bytes.hex(),
+                    write_key_bytes  = write_key_bytes,
+                    write_key        = write_key_bytes.hex(),
+                    tree_file_id     = tree_file_id,
+                    settings_file_id = settings_file_id,
+                    passphrase       = passphrase,
+                    vault_id         = vault_id)
+
+    def derive_keys_from_vault_key(self, vault_key: str) -> dict:
+        passphrase, vault_id = self.parse_vault_key(vault_key)
+        return self.derive_keys(passphrase, vault_id)
+
+    # --- low-level primitives ---
+
+    def derive_key_from_passphrase(self, passphrase: bytes, salt: bytes) -> bytes:
+        kdf = PBKDF2HMAC(algorithm  = hashes.SHA256(),
+                         length     = AES_KEY_BYTES,
+                         salt       = salt,
+                         iterations = PBKDF2_ITERATIONS)
+        return kdf.derive(passphrase)
+
+    def derive_file_key(self, vault_key: bytes, file_context: bytes) -> bytes:
+        hkdf = HKDF(algorithm = hashes.SHA256(),
+                     length    = AES_KEY_BYTES,
+                     salt      = None,
+                     info      = HKDF_INFO_PREFIX + file_context)
+        return hkdf.derive(vault_key)
+
+    def encrypt(self, key: bytes, plaintext: bytes, iv: bytes = None) -> bytes:
+        if iv is None:
+            iv = os.urandom(GCM_IV_BYTES)
+        aesgcm     = AESGCM(key)
+        ciphertext = aesgcm.encrypt(iv, plaintext, None)
+        return iv + ciphertext
+
+    def decrypt(self, key: bytes, data: bytes) -> bytes:
+        iv         = data[:GCM_IV_BYTES]
+        ciphertext = data[GCM_IV_BYTES:]
+        aesgcm     = AESGCM(key)
+        return aesgcm.decrypt(iv, ciphertext, None)
+
+    def hash_data(self, data: bytes) -> str:
+        return hashlib.sha256(data).hexdigest()
+
+    def generate_salt(self) -> bytes:
+        return os.urandom(16)
+
+    def generate_iv(self) -> bytes:
+        return os.urandom(GCM_IV_BYTES)

sg_send_cli-0.3.0/sg_send_cli/safe_types/Enum__Sync_State.py

@@ -0,0 +1,11 @@
+from enum import Enum
+
+class Enum__Sync_State(Enum):
+    SYNCED             = 'synced'
+    MODIFIED_LOCALLY   = 'modified_locally'
+    MODIFIED_REMOTELY  = 'modified_remotely'
+    CONFLICT           = 'conflict'
+    ADDED_LOCALLY      = 'added_locally'
+    ADDED_REMOTELY     = 'added_remotely'
+    DELETED_LOCALLY    = 'deleted_locally'
+    DELETED_REMOTELY   = 'deleted_remotely'

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__Access_Token.py

@@ -0,0 +1,10 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str import Safe_Str
+
+ACCESS_TOKEN__REGEX      = re.compile(r'[^a-zA-Z0-9\-_.]')
+ACCESS_TOKEN__MAX_LENGTH = 2048
+
+class Safe_Str__Access_Token(Safe_Str):
+    regex       = ACCESS_TOKEN__REGEX
+    max_length  = ACCESS_TOKEN__MAX_LENGTH
+    allow_empty = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__File_Id.py

@@ -0,0 +1,16 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str                         import Safe_Str
+from osbot_utils.type_safe.primitives.core.enums.Enum__Safe_Str__Regex_Mode import Enum__Safe_Str__Regex_Mode
+
+FILE_ID__REGEX      = re.compile(r'^[0-9a-f]{12}$')
+FILE_ID__MAX_LENGTH = 12
+
+class Safe_Str__File_Id(Safe_Str):
+    regex             = FILE_ID__REGEX
+    regex_mode        = Enum__Safe_Str__Regex_Mode.MATCH
+    max_length        = FILE_ID__MAX_LENGTH
+    exact_length      = True
+    allow_empty       = True
+    trim_whitespace   = True
+    to_lower_case     = True
+    strict_validation = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__File_Path.py

@@ -0,0 +1,10 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str import Safe_Str
+
+FILE_PATH__REGEX      = re.compile(r'[^a-zA-Z0-9/\\_.\- ]')
+FILE_PATH__MAX_LENGTH = 4096
+
+class Safe_Str__File_Path(Safe_Str):
+    regex       = FILE_PATH__REGEX
+    max_length  = FILE_PATH__MAX_LENGTH
+    allow_empty = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__SHA256.py

@@ -0,0 +1,16 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str                         import Safe_Str
+from osbot_utils.type_safe.primitives.core.enums.Enum__Safe_Str__Regex_Mode import Enum__Safe_Str__Regex_Mode
+
+SHA256__REGEX      = re.compile(r'^[0-9a-f]{64}$')
+SHA256__MAX_LENGTH = 64
+
+class Safe_Str__SHA256(Safe_Str):
+    regex             = SHA256__REGEX
+    regex_mode        = Enum__Safe_Str__Regex_Mode.MATCH
+    max_length        = SHA256__MAX_LENGTH
+    exact_length      = True
+    allow_empty       = True
+    trim_whitespace   = True
+    to_lower_case     = True
+    strict_validation = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__Transfer_Id.py

@@ -0,0 +1,15 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str                         import Safe_Str
+from osbot_utils.type_safe.primitives.core.enums.Enum__Safe_Str__Regex_Mode import Enum__Safe_Str__Regex_Mode
+
+TRANSFER_ID__REGEX      = re.compile(r'^[a-zA-Z0-9]{12}$')
+TRANSFER_ID__MAX_LENGTH = 12
+
+class Safe_Str__Transfer_Id(Safe_Str):
+    regex             = TRANSFER_ID__REGEX
+    regex_mode        = Enum__Safe_Str__Regex_Mode.MATCH
+    max_length        = TRANSFER_ID__MAX_LENGTH
+    exact_length      = True
+    allow_empty       = True
+    trim_whitespace   = True
+    strict_validation = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__Vault_Id.py

@@ -0,0 +1,16 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str                         import Safe_Str
+from osbot_utils.type_safe.primitives.core.enums.Enum__Safe_Str__Regex_Mode import Enum__Safe_Str__Regex_Mode
+
+VAULT_ID__REGEX      = re.compile(r'^[0-9a-f]{8}$')
+VAULT_ID__MAX_LENGTH = 8
+
+class Safe_Str__Vault_Id(Safe_Str):
+    regex             = VAULT_ID__REGEX
+    regex_mode        = Enum__Safe_Str__Regex_Mode.MATCH
+    max_length        = VAULT_ID__MAX_LENGTH
+    exact_length      = True
+    allow_empty       = True
+    trim_whitespace   = True
+    to_lower_case     = True
+    strict_validation = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__Vault_Key.py

@@ -0,0 +1,14 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str                         import Safe_Str
+from osbot_utils.type_safe.primitives.core.enums.Enum__Safe_Str__Regex_Mode import Enum__Safe_Str__Regex_Mode
+
+VAULT_KEY__REGEX      = re.compile(r'^[\x20-\x7E]+:[0-9a-f]{8}$')
+VAULT_KEY__MAX_LENGTH = 268
+
+class Safe_Str__Vault_Key(Safe_Str):
+    regex             = VAULT_KEY__REGEX
+    regex_mode        = Enum__Safe_Str__Regex_Mode.MATCH
+    max_length        = VAULT_KEY__MAX_LENGTH
+    allow_empty       = True
+    trim_whitespace   = True
+    strict_validation = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__Vault_Name.py

@@ -0,0 +1,10 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str import Safe_Str
+
+VAULT_NAME__REGEX      = re.compile(r'[^a-zA-Z0-9 _\-.]')
+VAULT_NAME__MAX_LENGTH = 128
+
+class Safe_Str__Vault_Name(Safe_Str):
+    regex       = VAULT_NAME__REGEX
+    max_length  = VAULT_NAME__MAX_LENGTH
+    allow_empty = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__Vault_Passphrase.py

@@ -0,0 +1,14 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str                         import Safe_Str
+from osbot_utils.type_safe.primitives.core.enums.Enum__Safe_Str__Regex_Mode import Enum__Safe_Str__Regex_Mode
+
+VAULT_PASSPHRASE__REGEX      = re.compile(r'^[\x20-\x7E]{1,256}$')
+VAULT_PASSPHRASE__MAX_LENGTH = 256
+
+class Safe_Str__Vault_Passphrase(Safe_Str):
+    regex             = VAULT_PASSPHRASE__REGEX
+    regex_mode        = Enum__Safe_Str__Regex_Mode.MATCH
+    max_length        = VAULT_PASSPHRASE__MAX_LENGTH
+    allow_empty       = False
+    trim_whitespace   = False
+    strict_validation = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_Str__Write_Key.py

@@ -0,0 +1,16 @@
+import re
+from osbot_utils.type_safe.primitives.core.Safe_Str                         import Safe_Str
+from osbot_utils.type_safe.primitives.core.enums.Enum__Safe_Str__Regex_Mode import Enum__Safe_Str__Regex_Mode
+
+WRITE_KEY__REGEX      = re.compile(r'^[0-9a-f]{64}$')
+WRITE_KEY__MAX_LENGTH = 64
+
+class Safe_Str__Write_Key(Safe_Str):
+    regex             = WRITE_KEY__REGEX
+    regex_mode        = Enum__Safe_Str__Regex_Mode.MATCH
+    max_length        = WRITE_KEY__MAX_LENGTH
+    exact_length      = True
+    allow_empty       = True
+    trim_whitespace   = True
+    to_lower_case     = True
+    strict_validation = True

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_UInt__File_Size.py

@@ -0,0 +1,6 @@
+from osbot_utils.type_safe.primitives.core.Safe_UInt import Safe_UInt
+
+MAX_FILE_SIZE = 100 * 1024 * 1024
+
+class Safe_UInt__File_Size(Safe_UInt):
+    max_value = MAX_FILE_SIZE

sg_send_cli-0.3.0/sg_send_cli/safe_types/Safe_UInt__Vault_Version.py

@@ -0,0 +1,4 @@
+from osbot_utils.type_safe.primitives.core.Safe_UInt import Safe_UInt
+
+class Safe_UInt__Vault_Version(Safe_UInt):
+    max_value = 999999

sg_send_cli-0.3.0/sg_send_cli/schemas/Schema__Transfer_File.py

@@ -0,0 +1,13 @@
+from osbot_utils.type_safe.Type_Safe                          import Type_Safe
+from sg_send_cli.safe_types.Safe_Str__Transfer_Id             import Safe_Str__Transfer_Id
+from sg_send_cli.safe_types.Safe_Str__SHA256                  import Safe_Str__SHA256
+from sg_send_cli.safe_types.Safe_Str__File_Path               import Safe_Str__File_Path
+from sg_send_cli.safe_types.Safe_UInt__File_Size              import Safe_UInt__File_Size
+
+
+class Schema__Transfer_File(Type_Safe):
+    transfer_id   : Safe_Str__Transfer_Id = None
+    file_path     : Safe_Str__File_Path   = None
+    file_hash     : Safe_Str__SHA256      = None
+    file_size     : Safe_UInt__File_Size
+    content_type  : Safe_Str__File_Path   = None

sg_send_cli-0.3.0/sg_send_cli/schemas/Schema__Vault_Config.py

@@ -0,0 +1,11 @@
+from osbot_utils.type_safe.Type_Safe                          import Type_Safe
+from sg_send_cli.safe_types.Safe_Str__Vault_Id                import Safe_Str__Vault_Id
+from sg_send_cli.safe_types.Safe_Str__Access_Token            import Safe_Str__Access_Token
+from sg_send_cli.safe_types.Safe_Str__File_Path               import Safe_Str__File_Path
+
+
+class Schema__Vault_Config(Type_Safe):
+    vault_id     : Safe_Str__Vault_Id     = None
+    endpoint_url : Safe_Str__File_Path    = None
+    access_token : Safe_Str__Access_Token = None
+    local_path   : Safe_Str__File_Path    = None

sg_send_cli-0.3.0/sg_send_cli/schemas/Schema__Vault_Index.py

@@ -0,0 +1,10 @@
+from osbot_utils.type_safe.Type_Safe                          import Type_Safe
+from sg_send_cli.safe_types.Safe_Str__Vault_Id                import Safe_Str__Vault_Id
+from sg_send_cli.safe_types.Safe_UInt__Vault_Version          import Safe_UInt__Vault_Version
+from sg_send_cli.schemas.Schema__Vault_Index_Entry            import Schema__Vault_Index_Entry
+
+
+class Schema__Vault_Index(Type_Safe):
+    vault_id : Safe_Str__Vault_Id                      = None
+    version  : Safe_UInt__Vault_Version
+    entries  : list[Schema__Vault_Index_Entry]

sg_send_cli-0.3.0/sg_send_cli/schemas/Schema__Vault_Index_Entry.py

@@ -0,0 +1,16 @@
+from osbot_utils.type_safe.Type_Safe                          import Type_Safe
+from sg_send_cli.safe_types.Safe_Str__SHA256                  import Safe_Str__SHA256
+from sg_send_cli.safe_types.Safe_Str__Transfer_Id             import Safe_Str__Transfer_Id
+from sg_send_cli.safe_types.Safe_Str__File_Path               import Safe_Str__File_Path
+from sg_send_cli.safe_types.Safe_UInt__File_Size              import Safe_UInt__File_Size
+from sg_send_cli.safe_types.Enum__Sync_State                  import Enum__Sync_State
+
+
+class Schema__Vault_Index_Entry(Type_Safe):
+    file_path          : Safe_Str__File_Path    = None
+    local_hash         : Safe_Str__SHA256       = None
+    local_size         : Safe_UInt__File_Size
+    remote_transfer_id : Safe_Str__Transfer_Id  = None
+    remote_hash        : Safe_Str__SHA256       = None
+    remote_size        : Safe_UInt__File_Size
+    state              : Enum__Sync_State       = Enum__Sync_State.SYNCED

sg_send_cli-0.3.0/sg_send_cli/schemas/Schema__Vault_Meta.py

@@ -0,0 +1,12 @@
+from osbot_utils.type_safe.Type_Safe                          import Type_Safe
+from sg_send_cli.safe_types.Safe_Str__Vault_Id                import Safe_Str__Vault_Id
+from sg_send_cli.safe_types.Safe_Str__Vault_Name              import Safe_Str__Vault_Name
+from sg_send_cli.safe_types.Safe_Str__Vault_Key               import Safe_Str__Vault_Key
+from sg_send_cli.safe_types.Safe_UInt__Vault_Version          import Safe_UInt__Vault_Version
+
+
+class Schema__Vault_Meta(Type_Safe):
+    vault_id : Safe_Str__Vault_Id       = None
+    name     : Safe_Str__Vault_Name     = None
+    version  : Safe_UInt__Vault_Version
+    vault_key: Safe_Str__Vault_Key      = None

sg_send_cli-0.3.0/sg_send_cli/sync/Vault__Sync.py

@@ -0,0 +1,286 @@
+import json
+import os
+from   datetime                        import datetime, timezone
+from   osbot_utils.type_safe.Type_Safe import Type_Safe
+from   sg_send_cli.crypto.Vault__Crypto import Vault__Crypto
+from   sg_send_cli.api.Vault__API       import Vault__API
+
+SG_VAULT_DIR  = '.sg_vault'
+HEAD_FILE     = 'HEAD'
+TREE_FILE     = 'tree.json'
+SETTINGS_FILE = 'settings.json'
+
+
+class Vault__Sync(Type_Safe):
+    crypto : Vault__Crypto
+    api    : Vault__API
+
+    def clone(self, vault_key: str, directory: str = None) -> str:
+        keys       = self.crypto.derive_keys_from_vault_key(vault_key)
+        vault_id   = keys['vault_id']
+        read_key   = keys['read_key_bytes']
+
+        if directory is None:
+            directory = vault_id
+        os.makedirs(directory, exist_ok=True)
+
+        settings = self._download_and_decrypt(vault_id, keys['settings_file_id'], read_key)
+        tree     = self._download_and_decrypt(vault_id, keys['tree_file_id'], read_key)
+
+        settings_data = json.loads(settings)
+        tree_data     = json.loads(tree)
+
+        file_map = self._flatten_tree(tree_data.get('tree', {}))
+        for file_path, file_info in file_map.items():
+            file_id        = file_info['file_id']
+            encrypted_data = self.api.read(vault_id, file_id)
+            plaintext      = self.crypto.decrypt(read_key, encrypted_data)
+            full_path      = os.path.join(directory, file_path)
+            os.makedirs(os.path.dirname(full_path), exist_ok=True)
+            with open(full_path, 'wb') as f:
+                f.write(plaintext)
+
+        sg_vault_dir = os.path.join(directory, SG_VAULT_DIR)
+        os.makedirs(sg_vault_dir, exist_ok=True)
+        with open(os.path.join(sg_vault_dir, HEAD_FILE), 'w') as f:
+            f.write(vault_key)
+        with open(os.path.join(sg_vault_dir, TREE_FILE), 'w') as f:
+            json.dump(tree_data, f, indent=2)
+        with open(os.path.join(sg_vault_dir, SETTINGS_FILE), 'w') as f:
+            json.dump(settings_data, f, indent=2)
+
+        return directory
+
+    def pull(self, directory: str = '.') -> dict:
+        vault_key = self._read_head(directory)
+        keys      = self.crypto.derive_keys_from_vault_key(vault_key)
+        vault_id  = keys['vault_id']
+        read_key  = keys['read_key_bytes']
+
+        settings      = self._download_and_decrypt(vault_id, keys['settings_file_id'], read_key)
+        tree          = self._download_and_decrypt(vault_id, keys['tree_file_id'], read_key)
+        settings_data = json.loads(settings)
+        tree_data     = json.loads(tree)
+
+        old_tree_data = self._read_local_tree(directory)
+        old_file_map  = self._flatten_tree(old_tree_data.get('tree', {}))
+        new_file_map  = self._flatten_tree(tree_data.get('tree', {}))
+
+        old_paths = set(old_file_map.keys())
+        new_paths = set(new_file_map.keys())
+
+        added    = new_paths - old_paths
+        deleted  = old_paths - new_paths
+        modified = set()
+        for path in old_paths & new_paths:
+            if old_file_map[path].get('file_id') != new_file_map[path].get('file_id'):
+                modified.add(path)
+
+        for path in added | modified:
+            file_id        = new_file_map[path]['file_id']
+            encrypted_data = self.api.read(vault_id, file_id)
+            plaintext      = self.crypto.decrypt(read_key, encrypted_data)
+            full_path      = os.path.join(directory, path)
+            os.makedirs(os.path.dirname(full_path), exist_ok=True)
+            with open(full_path, 'wb') as f:
+                f.write(plaintext)
+
+        for path in deleted:
+            full_path = os.path.join(directory, path)
+            if os.path.exists(full_path):
+                os.remove(full_path)
+
+        sg_vault_dir = os.path.join(directory, SG_VAULT_DIR)
+        with open(os.path.join(sg_vault_dir, TREE_FILE), 'w') as f:
+            json.dump(tree_data, f, indent=2)
+        with open(os.path.join(sg_vault_dir, SETTINGS_FILE), 'w') as f:
+            json.dump(settings_data, f, indent=2)
+
+        return dict(added=sorted(added), modified=sorted(modified), deleted=sorted(deleted))
+
+    def push(self, directory: str = '.') -> dict:
+        vault_key = self._read_head(directory)
+        keys      = self.crypto.derive_keys_from_vault_key(vault_key)
+        vault_id  = keys['vault_id']
+        read_key  = keys['read_key_bytes']
+        write_key = keys['write_key']
+
+        old_tree_data = self._read_local_tree(directory)
+        old_file_map  = self._flatten_tree(old_tree_data.get('tree', {}))
+        new_file_map  = self._scan_local_directory(directory)
+
+        old_paths = set(old_file_map.keys())
+        new_paths = set(new_file_map.keys())
+
+        added    = new_paths - old_paths
+        deleted  = old_paths - new_paths
+        common   = old_paths & new_paths
+        modified = set()
+
+        for path in common:
+            local_file = os.path.join(directory, path)
+            with open(local_file, 'rb') as f:
+                content = f.read()
+            if len(content) != old_file_map[path].get('size', -1):
+                modified.add(path)
+
+        uploaded = {}
+        for path in added | modified:
+            local_file = os.path.join(directory, path)
+            with open(local_file, 'rb') as f:
+                content = f.read()
+            file_id   = os.urandom(6).hex()
+            encrypted = self.crypto.encrypt(read_key, content)
+            self.api.write(vault_id, file_id, write_key, encrypted)
+            uploaded[path] = dict(file_id=file_id, size=len(content))
+
+        for path in deleted:
+            file_id = old_file_map[path]['file_id']
+            self.api.delete(vault_id, file_id, write_key)
+
+        new_tree_data = self._build_tree_json(old_tree_data, old_file_map, uploaded, deleted)
+
+        tree_json     = json.dumps(new_tree_data).encode()
+        encrypted_tree = self.crypto.encrypt(read_key, tree_json)
+        self.api.write(vault_id, keys['tree_file_id'], write_key, encrypted_tree)
+
+        settings_data = self._read_local_settings(directory)
+        settings_json  = json.dumps(settings_data).encode()
+        encrypted_settings = self.crypto.encrypt(read_key, settings_json)
+        self.api.write(vault_id, keys['settings_file_id'], write_key, encrypted_settings)
+
+        sg_vault_dir = os.path.join(directory, SG_VAULT_DIR)
+        with open(os.path.join(sg_vault_dir, TREE_FILE), 'w') as f:
+            json.dump(new_tree_data, f, indent=2)
+
+        return dict(added=list(added), modified=list(modified), deleted=list(deleted))
+
+    def status(self, directory: str = '.') -> dict:
+        old_tree_data = self._read_local_tree(directory)
+        old_file_map  = self._flatten_tree(old_tree_data.get('tree', {}))
+        new_file_map  = self._scan_local_directory(directory)
+
+        old_paths = set(old_file_map.keys())
+        new_paths = set(new_file_map.keys())
+
+        added    = sorted(new_paths - old_paths)
+        deleted  = sorted(old_paths - new_paths)
+        common   = old_paths & new_paths
+        modified = []
+
+        for path in sorted(common):
+            local_file = os.path.join(directory, path)
+            with open(local_file, 'rb') as f:
+                content = f.read()
+            if len(content) != old_file_map[path].get('size', -1):
+                modified.append(path)
+
+        return dict(added=added, modified=modified, deleted=deleted,
+                    clean=not added and not modified and not deleted)
+
+    def remote_status(self, directory: str = '.') -> dict:
+        vault_key = self._read_head(directory)
+        keys      = self.crypto.derive_keys_from_vault_key(vault_key)
+        vault_id  = keys['vault_id']
+        read_key  = keys['read_key_bytes']
+
+        remote_tree_raw  = self._download_and_decrypt(vault_id, keys['tree_file_id'], read_key)
+        remote_tree_data = json.loads(remote_tree_raw)
+        remote_file_map  = self._flatten_tree(remote_tree_data.get('tree', {}))
+
+        local_tree_data  = self._read_local_tree(directory)
+        local_file_map   = self._flatten_tree(local_tree_data.get('tree', {}))
+
+        remote_paths = set(remote_file_map.keys())
+        local_paths  = set(local_file_map.keys())
+
+        remote_added    = sorted(remote_paths - local_paths)
+        remote_deleted  = sorted(local_paths - remote_paths)
+        remote_modified = []
+        for path in sorted(remote_paths & local_paths):
+            if remote_file_map[path].get('file_id') != local_file_map[path].get('file_id'):
+                remote_modified.append(path)
+
+        local_status = self.status(directory)
+
+        return dict(remote_version = remote_tree_data.get('version'),
+                    local_version  = local_tree_data.get('version'),
+                    remote_added   = remote_added,
+                    remote_modified= remote_modified,
+                    remote_deleted = remote_deleted,
+                    local_added    = local_status['added'],
+                    local_modified = local_status['modified'],
+                    local_deleted  = local_status['deleted'])
+
+    # --- internal helpers ---
+
+    def _download_and_decrypt(self, vault_id: str, file_id: str, read_key: bytes) -> bytes:
+        encrypted = self.api.read(vault_id, file_id)
+        return self.crypto.decrypt(read_key, encrypted)
+
+    def _read_head(self, directory: str) -> str:
+        head_path = os.path.join(directory, SG_VAULT_DIR, HEAD_FILE)
+        with open(head_path, 'r') as f:
+            return f.read().strip()
+
+    def _read_local_tree(self, directory: str) -> dict:
+        tree_path = os.path.join(directory, SG_VAULT_DIR, TREE_FILE)
+        with open(tree_path, 'r') as f:
+            return json.load(f)
+
+    def _read_local_settings(self, directory: str) -> dict:
+        settings_path = os.path.join(directory, SG_VAULT_DIR, SETTINGS_FILE)
+        with open(settings_path, 'r') as f:
+            return json.load(f)
+
+    def _flatten_tree(self, tree: dict, prefix: str = '') -> dict:
+        result = {}
+        for name, node in tree.items():
+            if name == '/':
+                result.update(self._flatten_tree(node.get('children', {}), prefix))
+            elif node.get('type') == 'folder':
+                child_prefix = f'{prefix}{name}/' if prefix else f'{name}/'
+                result.update(self._flatten_tree(node.get('children', {}), child_prefix))
+            elif node.get('type') == 'file':
+                path = f'{prefix}{name}'
+                result[path] = node
+        return result
+
+    def _scan_local_directory(self, directory: str) -> dict:
+        result = {}
+        for root, dirs, files in os.walk(directory):
+            dirs[:] = [d for d in dirs if d != SG_VAULT_DIR and not d.startswith('.')]
+            for filename in files:
+                if filename.startswith('.'):
+                    continue
+                full_path = os.path.join(root, filename)
+                rel_path  = os.path.relpath(full_path, directory)
+                rel_path  = rel_path.replace(os.sep, '/')
+                result[rel_path] = dict(size=os.path.getsize(full_path))
+        return result
+
+    def _build_tree_json(self, old_tree_data: dict, old_file_map: dict,
+                         uploaded: dict, deleted: set) -> dict:
+        now = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.000Z')
+        all_files = {}
+        for path, info in old_file_map.items():
+            if path not in deleted:
+                all_files[path] = info
+        for path, info in uploaded.items():
+            all_files[path] = dict(type    = 'file',
+                                   file_id = info['file_id'],
+                                   size    = info['size'],
+                                   uploaded= now)
+
+        tree = {'/': {'type': 'folder', 'children': {}}}
+        for path, info in sorted(all_files.items()):
+            parts   = path.split('/')
+            current = tree['/']['children']
+            for part in parts[:-1]:
+                if part not in current:
+                    current[part] = {'type': 'folder', 'children': {}}
+                current = current[part]['children']
+            current[parts[-1]] = info
+
+        version = old_tree_data.get('version', 0) + 1
+        return dict(version=version, updated=now, tree=tree)

sg_send_cli-0.3.0/sg_send_cli/version

@@ -0,0 +1 @@
+v0.3.0