starfish-keyring 3.0.0a8__tar.gz

starfish_keyring-3.0.0a8/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: starfish-keyring
+Version: 3.0.0a8
+Summary: Starfish multi-recipient encryption layer (keyring documents, recipient management, AES-GCM payload encryption)
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0
+Requires-Dist: starfish-protocol
+Requires-Dist: starfish-sdk
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: respx>=0.23.1; extra == "dev"

starfish_keyring-3.0.0a8/README.md

@@ -0,0 +1,40 @@
+# starfish-keyring
+
+Starfish multi-recipient encryption layer for Python — keyring documents, recipient management, AES-GCM payload encryption.
+
+This is the encryption extension for Starfish v3. It is independent of `starfish-sdk` transport in the sense that the core `StarfishClient` does not import it; apps that want client-side payload encryption install this package and wire it on top.
+
+## Install
+
+```sh
+pip install starfish-sdk starfish-keyring
+```
+
+## Usage
+
+```python
+from starfish_sdk import StarfishClient
+from starfish_keyring import (
+    create_keyring,
+    create_keyring_encryptor,
+    add_collection_recipient,
+)
+
+keyring, cek = create_keyring(adder_ed_priv, adder_ed_pub, [alice_kem_pub])
+encryptor = create_keyring_encryptor(
+    keyring,
+    alice_kem_pub,
+    alice_kem_priv,
+    trusted_adders=[adder_ed_pub],   # required — Ed25519 pubkey(s) you trust to grant access
+)
+```
+
+`trusted_adders` is **required** (raises without it): the per-entry `addedSig` is self-attesting, so a provenance pin is needed to reject a server-substituted wrap entry. Pass the keyword-only `min_epoch` (the highest `current_epoch` you've previously seen, persisted client-side) to reject a stale keyring a hostile server might serve to undo a rotation. The recipient-management helpers (`add_collection_recipient`, `remove_recipient`, `list_recipients`) require the same `trusted_adders` pin.
+
+The encryptor exposes `encrypt`/`decrypt` for JSON payloads and `seal_bytes(data, aad=None)` / `open_bytes(blob, aad=None)` for raw binary attachments (stored via the client's `push_blob` in an `encryption: "none"` binary collection). A sealed blob is `[u32 BE epoch][12-byte IV][AES-256-GCM ciphertext‖tag]`; the epoch and the caller's `aad` (typically the blob's storage path) are bound into the GCM tag, so a hostile server cannot relocate the blob to another path or replay it at a different epoch. This is byte-compatible with the TypeScript keyring's `sealBytes`/`openBytes`, so a blob sealed in one language opens in the other.
+
+## Epochs & rotation
+
+Revoking a recipient (`remove_recipient`) **rotates** the keyring to a new epoch and re-wraps the CEK for everyone who remains, so the revoked party can't read new content. `add_collection_recipient` wraps a newcomer into the **current epoch only** — content sealed under an earlier epoch stays unreadable to them (you'll see `No key available for epoch N` on decrypt). To share existing content with a freshly-added recipient, **re-seal it at the current epoch** (decrypt with a key that holds the old CEK, then re-encrypt) after adding them.
+
+See `docs/python/keyring/` (and the TypeScript counterpart in `docs/ts/keyring/`) for the full guide.

starfish_keyring-3.0.0a8/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "starfish-keyring"
+version = "3.0.0a8"
+description = "Starfish multi-recipient encryption layer (keyring documents, recipient management, AES-GCM payload encryption)"
+requires-python = ">=3.11"
+dependencies = [
+  "cryptography>=41.0",
+  "starfish-protocol",
+  "starfish-sdk",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-asyncio>=0.21",
+  "respx>=0.23.1",
+]
+
+[tool.uv.sources]
+starfish-protocol = { path = "../protocol", editable = true }
+starfish-sdk = { path = "../client", editable = true }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

starfish_keyring-3.0.0a8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

starfish_keyring-3.0.0a8/starfish_keyring/__init__.py

@@ -0,0 +1,60 @@
+"""``starfish-keyring`` — multi-recipient encryption layer.
+
+Public surface: keyring lifecycle (create/add/rotate), encryptor factory,
+wrap/unwrap primitives, recipient management bound to a Starfish collection,
+and the locked protocol constants.
+"""
+
+from starfish_keyring.keyring import (
+    KEYRING_IV_BYTES,
+    KEYRING_WRAP_INFO,
+    KEYRING_WRAP_SALT,
+    Keyring,
+    KeyringEncryptor,
+    KeyringEpoch,
+    WrappedKeyEntry,
+    add_recipient,
+    create_keyring,
+    create_keyring_encryptor,
+    rotate_epoch,
+    unwrap_from_entry,
+    verify_entry_signature,
+    wrap_for_recipient,
+)
+from starfish_keyring.recipients import (
+    AdderKeys,
+    ListedRecipient,
+    RecipientRef,
+    add_recipient as add_collection_recipient,
+    current_epoch,
+    keyring_path_for,
+    list_recipients,
+    remove_recipient,
+)
+from starfish_keyring._crypto_helpers import hkdf_bytes
+
+__all__ = [
+    "hkdf_bytes",
+    "KEYRING_IV_BYTES",
+    "KEYRING_WRAP_INFO",
+    "KEYRING_WRAP_SALT",
+    "Keyring",
+    "KeyringEncryptor",
+    "KeyringEpoch",
+    "WrappedKeyEntry",
+    "add_recipient",
+    "create_keyring",
+    "create_keyring_encryptor",
+    "rotate_epoch",
+    "unwrap_from_entry",
+    "verify_entry_signature",
+    "wrap_for_recipient",
+    "AdderKeys",
+    "ListedRecipient",
+    "RecipientRef",
+    "add_collection_recipient",
+    "current_epoch",
+    "keyring_path_for",
+    "list_recipients",
+    "remove_recipient",
+]

starfish_keyring-3.0.0a8/starfish_keyring/_crypto_helpers.py

@@ -0,0 +1,27 @@
+"""Internal crypto helpers shared by identity, keyring, and pairing.
+
+The leading underscore on the module name marks this as module-private — it
+is NOT re-exported from ``__init__.py``. External consumers should not
+import it.
+
+This helper was previously duplicated verbatim across three modules
+(``identity.py``, ``keyring.py``, ``pairing.py``); consolidating it keeps
+the byte-level behavior identical while removing copy-paste drift risk.
+"""
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+
+def hkdf_bytes(ikm: bytes, salt: bytes, info: bytes, length: int = 32) -> bytes:
+    """HKDF-SHA256 → ``length`` raw bytes.
+
+    Mirrors the TypeScript ``hkdfBytes`` (Web Crypto ``deriveBits``) so
+    cross-language test vectors remain byte-identical.
+    """
+    return HKDF(
+        algorithm=hashes.SHA256(),
+        length=length,
+        salt=salt,
+        info=info,
+    ).derive(ikm)