Metadata-Version: 2.4
Name: space64-local-archive
Version: 0.1.0
Summary: Python reader and writer for the Space64 encrypted local archive format.
Project-URL: Homepage, https://github.com/space64-team/space64-local-archive
Project-URL: Repository, https://github.com/space64-team/space64-local-archive
Project-URL: Issues, https://github.com/space64-team/space64-local-archive/issues
Author: Space64
License-Expression: MIT
License-File: LICENSE
Keywords: archive,encrypted,local-first,space64
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.25; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# space64-local-archive

Python reader and writer for the Space64 encrypted local archive container used by
Space64 apps.

This package is intended to mirror the Space64 encrypted local archive container
format closely enough for maintenance tools, import/export jobs, diagnostics,
and future cross-language workflows.

## Status

Alpha. The file format is compatible with the Dart package's append-only
container format, including:

- PBKDF2-HMAC-SHA256 key derivation
- AES-256-GCM encrypted records
- append-only metadata/index snapshots
- attachment and blob records
- optional per-record zlib compression
- recovery by copying the latest readable footer snapshot

The Python API is intentionally low-level: callers provide app manifest/data
JSON dictionaries plus attachment/blob bytes. App-specific schema migration
still belongs to the app.

## Install

```bash
pip install space64-local-archive
```

For local development:

```bash
python -m pip install -e ".[dev]"
pytest
```

## Example

```python
from space64_local_archive import (
    EncryptedLocalArchive,
    LocalArchiveFormat,
)

fmt = LocalArchiveFormat.app_profile(
    app_id="my_app",
    file_magic="MYARCHIVE2",
)

repo = EncryptedLocalArchive(fmt)
repo.create(
    "example.myarchive",
    password="correct horse battery staple",
    manifest={
        "format": "my_app.archive",
        "format_version": 1,
        "schema_version": 1,
        "archive_id": "archive_1",
        "created_at": "2026-05-28T00:00:00.000Z",
        "updated_at": "2026-05-28T00:00:00.000Z",
        "app": {"name": "My App"},
        "encryption": {
            "status": "encrypted",
            "container": "my_app.chunked_encrypted_package",
            "kdf": "PBKDF2-HMAC-SHA256",
            "cipher": "AES-256-GCM",
        },
        "data_entry": "data.json",
        "attachments_root": "attachments/originals",
        "migrations": [],
        "metadata": {},
    },
    data={"schema_version": 1, "title": "Hello"},
)

opened = repo.open("example.myarchive", password="correct horse battery staple")
print(opened.data["title"])
```
