flametrench-file 0.4.0

File-metadata primitive for Flametrench: storage-agnostic metadata, lifecycle, and authz-mediated access (ADR 0020).

flametrench-file

File-metadata primitive for the Flametrench v0.4 platform (ADR 0020).

What this is

Metadata and lifecycle for files — no blob bytes in the contract. storage_ref is an opaque adopter pointer (S3 key, GCS path, URL) stored verbatim; the primitive never dereferences it. Access is mediated by authz (ADR 0001); a file_ record is an authz object.

Lifecycle: pending → active (freezes size_bytes/checksum/storage_ref) → deleted (soft — record retained). Deleted files remain fetchable.

Install

pip install flametrench-file

Requires Python ≥ 3.11 and flametrench-ids >= 0.4.0.

Quick start

from flametrench_file import InMemoryFileStore

store = InMemoryFileStore()

# Register directly as active
f = store.create_file_metadata(
    scope="org_...",
    owner_usr_id="usr_...",
    name="q3-report.pdf",
    content_type="application/pdf",
    size_bytes=184320,
    checksum={"algo": "sha-256", "value": "e3b0c44..."},
    storage_ref="s3://bucket/q3-report.pdf",
    status="active",
)

# Or: pending handshake → activate on upload complete
p = store.create_file_metadata(
    scope="org_...", owner_usr_id="usr_...",
    name="upload.bin", content_type="application/octet-stream",
    status="pending",
)
store.update_file_metadata(
    p.id, status="active",
    size_bytes=4096,
    checksum={"algo": "sha-256", "value": "9f86d08..."},
    storage_ref="s3://bucket/upload.bin",
)

License

Apache-2.0 © NDC Digital, LLC