starfish-identities 3.0.0a8__tar.gz

starfish_identities-3.0.0a8/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: starfish-identities
+Version: 3.0.0a8
+Summary: Starfish root + device identity extension (passphrase derivation, device cap-cert minting, pairing flows, device directory)
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0
+Requires-Dist: argon2-cffi>=25.1.0
+Requires-Dist: starfish-protocol
+Requires-Dist: starfish-sdk
+Requires-Dist: starfish-keyring
+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"
+Requires-Dist: starfish-server; extra == "dev"

starfish_identities-3.0.0a8/README.md

@@ -0,0 +1,187 @@
+# starfish-identities
+
+Starfish root + device identity extension for Python — passphrase-derived root identities, device cap-cert minting, multi-device pairing flows, and the per-user device directory.
+
+## Install
+
+```sh
+pip install starfish-sdk starfish-keyring starfish-identities
+```
+
+## Usage
+
+```python
+from starfish_identities import bootstrap_root_identity, mint_device_cap, scopes, add_device_entry, list_devices
+
+me = bootstrap_root_identity("correct horse battery staple")
+```
+
+## Root identity derivation
+
+`bootstrap_root_identity` / `derive_root_identity` derive the root keypairs
+deterministically from the passphrase, so the same human re-derives them on any
+device with no stored secret:
+
+- **Argon2id** (memory-hard) stretches the passphrase into a 32-byte master —
+  `m=47104 KiB ≈ 46 MiB, t=3, p=1`, global salt `"starfish-v3-root"` (derivation
+  must be reproducible from the passphrase alone, so the salt cannot be per-user).
+  Locked as `ARGON2_PARAMS`.
+- **HKDF-SHA256** expands the master into two domain-separated seeds: an Ed25519
+  signing key (`info="ed25519"`) and an X25519 KEM key (`info="x25519"`) — used for
+  exactly one of {sign, key-agreement} each, never both.
+- `user_id = sha256(root_ed_pub)[0:32]`.
+
+Byte-identical to the TypeScript derivation; locked by
+[`tests/test-vectors/identity-derivation.json`](../../../tests/test-vectors/identity-derivation.json).
+
+## One-way device provisioning (configurable caps + expiry)
+
+The QR / server-relay flows are *two-way*: the new device generates its own
+keypair and sends a request back. `provision_device` is the *one-way* alternative
+— the root device plays both roles, producing a single hand-off blob — and it is
+where you choose **what the new device may do** (`scope`) and **how long its cap
+lives** (`ttl_sec`). The same knobs exist on the two-way flow via
+`AssemblePairingBundleOpts(granted_scope=..., ttl_sec=...)`.
+
+```python
+import json
+from starfish_identities import (
+    provision_device,
+    install_provisioned_device,
+    ProvisionDeviceOpts,
+    ProvisionedDevice,
+    scopes,
+)
+
+# Root device: generate the new device, mint its cap with a chosen scope + exp.
+provisioned = provision_device(
+    {"edPriv": me.device["edPriv"], "edPub": me.device["edPub"]},
+    ProvisionDeviceOpts(
+        scope=scopes.root_all(),       # REQUIRED — or a narrower scope to bound the device
+        ttl_sec=7 * 24 * 3600,         # optional, default 30 days
+        # current_epoch_by_collection={"notes": {"epoch": e, "cek": cek}},  # optional
+    ),
+)
+setup_code = json.dumps(provisioned.to_dict())  # hand off out-of-band
+
+# New device: install the blob (uses the keys carried inside it).
+installed = install_provisioned_device(ProvisionedDevice.from_dict(json.loads(setup_code)))
+```
+
+- **`scope` is required** — provisioning never silently grants root. Pass
+  `scopes.root_all()` for a full account clone, or a narrower scope to bound the
+  device. The server enforces it: a cap whose `ops` omit `write` synthesizes no
+  write role, so writes return 403.
+- **`current_epoch_by_collection`** wraps existing CEKs into the bundle so the new
+  device can read existing ciphertext (it lives inside the opts here, whereas
+  `assemble_pairing_bundle` takes it as a positional argument).
+- **Security:** the new device's **private keys are generated off-device** and
+  travel inside the result. Whoever reads the blob owns a full clone of the
+  device. Use one-way provisioning only over a channel you would trust with the
+  collection keys themselves; prefer the two-way QR / relay flow otherwise.
+
+## QR-in / auto-return pairing (anonymous rendezvous)
+
+For a device that **can't scan** (e.g. a laptop), keep the camera on the *root*
+device: the new device shows its QR, the root scans it and pushes the assembled
+bundle to a small **anonymous, TTL'd rendezvous slot**, and the new device fetches
+it with a single trigger — no manual bundle-back, no polling. The new device is
+credential-less (no cap-cert yet), so it reaches the public slot with an anonymous
+client; this is safe because the bundle's CEKs are E2E-wrapped to the new device's
+KEM and the channel needs only delivery.
+
+```python
+from starfish_identities import (
+    build_pairing_qr, parse_pairing_qr, assemble_pairing_bundle, install_pairing_bundle,
+    push_pairing_bundle, fetch_pairing_bundle, clear_pairing_bundle, generate_device_keys,
+    AssemblePairingBundleOpts, scopes,
+)
+
+# New device: show a QR (carries qr_nonce); anon_client has no cap_provider.
+dev = generate_device_keys()
+qr = build_pairing_qr(dev["edPub"], dev["kemPub"], requested_scope, qr_nonce=qr_nonce_bytes)
+
+# Root device: parse, assemble, and push to the rendezvous slot.
+parsed = parse_pairing_qr(qr)
+bundle = assemble_pairing_bundle(
+    root_ed_key, parsed, {},  # third arg is per-collection CEKs, if any
+    opts=AssemblePairingBundleOpts(granted_scope=scopes.root_all()),  # REQUIRED
+)
+await push_pairing_bundle(anon_client, parsed.qr_nonce, bundle)
+
+# New device, on a single "Added from root" click — None means "not there yet".
+bundle2 = await fetch_pairing_bundle(anon_client, qr_nonce)
+if bundle2 is not None:
+    installed = install_pairing_bundle(
+        bundle2, dev,
+        expected_qr_nonce=qr_nonce,
+        expected_root_ed_pub=known_root_pub,  # pin: rejects a bundle from a different root
+    )
+    await clear_pairing_bundle(anon_client, qr_nonce)  # best-effort one-shot
+```
+
+- **`granted_scope` is required.** The QR-supplied `requested_scope` is
+  attacker-influenceable, so callers **must** pass an explicit `granted_scope` to
+  bound the delegated authority — `assemble_pairing_bundle` fails closed (raises
+  `ValueError`) without it rather than defaulting to the requested scope.
+- **`expected_root_ed_pub`** pins the issuer so an attacker's own root can't answer
+  an open rendezvous and provision the device into *their* account. When the new
+  device doesn't know the root pubkey, show its fingerprint for the user to verify.
+- The slot is keyed by `rendezvous_path_for(qr_nonce)` = `_pairing/<hex(qr_nonce)>`
+  — no new QR field; `qr_nonce` was never secret. The app/server provides the
+  collection: `encryption="none"`, `public` read/write, a short `ttl_ms`, a tight
+  body cap; one-shot is the new device overwriting the slot after install.
+
+## Same identity on every device (the simplest multi-device model)
+
+Pairing/provisioning give each device its own key pair (so you can revoke one device), but a
+per-device key is **not** a recipient in rooms owned by *other* people — its bundle CEK is a
+snapshot that goes stale on the owner's next epoch rotation, and a member can't enroll its own
+device in someone else's keyring. The simplest way to give every device the **same** membership is
+to skip pairing and **re-enter the passphrase**: `bootstrap_root_identity` is deterministic, so each
+device re-derives the identical root identity and is the *same principal and KEM recipient*. It can
+then present any cap minted to your root (including member caps), unwrap any CEK wrapped to your
+root KEM, and **keep reading across the owner's rotations** (every device re-derives the same key).
+The trade-off: the master key lives on every device, so there is **no per-device revocation** and
+losing any device compromises the account. The member-cap JSON others issued you and the room list
+are app-level state that must still travel to the new device. See
+[`docs/ts/client/24-pairing.md` §5](../../../docs/ts/client/24-pairing.md).
+
+## Sealing a setup code with a passphrase
+
+A one-way setup code (or any secret blob) can be sealed under a user-chosen
+PIN/passphrase so the code alone is useless if intercepted — send the PIN over a
+**different channel** than the code:
+
+```python
+from starfish_identities import seal_with_passphrase, open_with_passphrase, is_sealed_envelope
+
+env = seal_with_passphrase(pin, setup_code_json.encode("utf-8"))  # JSON-serialisable dict
+# hand over json.dumps(env); transmit the PIN separately
+
+if is_sealed_envelope(parsed):
+    data = open_with_passphrase(pin, parsed)  # one generic ValueError on any failure
+```
+
+`key = Argon2id(NFC(passphrase), random-salt)` → AES-256-GCM. `open_with_passphrase`
+validates the KDF parameters **before** running Argon2id (so a hostile envelope
+can't force a multi-GiB computation) and collapses every failure — wrong
+passphrase, tampering, bad params — into one generic error. Strength is bounded by
+passphrase entropy: a short numeric PIN is still offline-brute-forceable, so the
+seal buys a revocation window, not permanent safety. Byte-identical to the
+TypeScript `sealWithPassphrase`, locked by `tests/test-vectors/passphrase-seal.json`.
+
+## Server plugin
+
+```python
+from starfish_server import create_cap_cert_role_resolver
+from starfish_identities import identities_server_plugin
+
+resolver = create_cap_cert_role_resolver(
+    nonce_cache=nonce_cache,
+    revocation_store=revocation_store,
+    plugins=[identities_server_plugin],
+)
+```
+
+See `docs/python/identities/` (and the TypeScript counterpart in `docs/ts/identities/`) for the full guide.

starfish_identities-3.0.0a8/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "starfish-identities"
+version = "3.0.0a8"
+description = "Starfish root + device identity extension (passphrase derivation, device cap-cert minting, pairing flows, device directory)"
+requires-python = ">=3.11"
+dependencies = [
+  "cryptography>=41.0",
+  "argon2-cffi>=25.1.0",
+  "starfish-protocol",
+  "starfish-sdk",
+  "starfish-keyring",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-asyncio>=0.21",
+  "respx>=0.23.1",
+  "starfish-server",
+]
+
+[tool.uv.sources]
+starfish-protocol = { path = "../protocol", editable = true }
+starfish-sdk = { path = "../client", editable = true }
+starfish-keyring = { path = "../keyring", editable = true }
+starfish-server = { path = "../server", editable = true }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

starfish_identities-3.0.0a8/setup.cfg

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

starfish_identities-3.0.0a8/starfish_identities/__init__.py

@@ -0,0 +1,129 @@
+"""``starfish-identities`` — root + device identity extension.
+
+Public surface: passphrase-derived root identities, device cap-cert
+minting, the ``scopes.root_all`` preset, all pairing flows (QR +
+server-relay), the per-user device directory, and the server plugin.
+"""
+
+from starfish_identities.identity import (
+    RootIdentity,
+    RootKeyPair,
+    derive_root_identity,
+)
+from starfish_identities.cap_mint import (
+    MintOpts,
+    ScopePreset,
+    mint_device_cap,
+    scopes,
+)
+from starfish_identities.pairing import (
+    AssemblePairingBundleOpts,
+    DeviceCredentials,
+    InstalledPairingResult,
+    PairingBundle,
+    PairingQrPayload,
+    PairingRequestEncrypted,
+    PairingResponseEncrypted,
+    ProvisionDeviceOpts,
+    ProvisionedDevice,
+    RecoveredCek,
+    WrappedCekEntry,
+    assemble_pairing_bundle,
+    bootstrap_root_identity,
+    build_pairing_qr,
+    build_pairing_request,
+    build_pairing_response,
+    derive_code_key,
+    generate_device_keys,
+    install_pairing_bundle,
+    install_provisioned_device,
+    parse_pairing_qr,
+    provision_device,
+    read_pairing_request,
+    read_pairing_response,
+)
+from starfish_identities.rendezvous import (
+    RENDEZVOUS_PREFIX,
+    clear_pairing_bundle,
+    fetch_pairing_bundle,
+    push_pairing_bundle,
+    rendezvous_path_for,
+)
+from starfish_identities.seal import (
+    is_sealed_envelope,
+    open_with_passphrase,
+    seal_with_passphrase,
+)
+from starfish_identities.directory import (
+    Directory,
+    DirectoryEntry,
+    ListDirectoryOpts,
+    add_device_entry,
+    devices_path_for,
+    list_devices,
+    remove_device_entry,
+)
+# Re-exported from the protocol layer: distinguishes a self-signed root-device
+# cap from delegated devices/members (used by server-side root-only collections).
+from starfish_protocol import is_root_device_cap
+
+
+def __getattr__(name: str):
+    """Lazy import of ``identities_server_plugin`` so apps that only use the
+    client-side helpers don't pay the ``starfish_server`` import cost.
+    """
+    if name == "identities_server_plugin":
+        from starfish_identities.plugin import identities_server_plugin as _p
+        return _p
+    raise AttributeError(f"module 'starfish_identities' has no attribute {name!r}")
+
+__all__ = [
+    "RootIdentity",
+    "RootKeyPair",
+    "derive_root_identity",
+    "MintOpts",
+    "ScopePreset",
+    "mint_device_cap",
+    "scopes",
+    "AssemblePairingBundleOpts",
+    "DeviceCredentials",
+    "InstalledPairingResult",
+    "PairingBundle",
+    "PairingQrPayload",
+    "PairingRequestEncrypted",
+    "PairingResponseEncrypted",
+    "ProvisionDeviceOpts",
+    "ProvisionedDevice",
+    "RecoveredCek",
+    "WrappedCekEntry",
+    "assemble_pairing_bundle",
+    "bootstrap_root_identity",
+    "build_pairing_qr",
+    "build_pairing_request",
+    "build_pairing_response",
+    "derive_code_key",
+    "generate_device_keys",
+    "install_pairing_bundle",
+    "install_provisioned_device",
+    "parse_pairing_qr",
+    "provision_device",
+    "read_pairing_request",
+    "read_pairing_response",
+    "RENDEZVOUS_PREFIX",
+    "rendezvous_path_for",
+    "push_pairing_bundle",
+    "fetch_pairing_bundle",
+    "clear_pairing_bundle",
+    "seal_with_passphrase",
+    "open_with_passphrase",
+    "is_sealed_envelope",
+    "Directory",
+    "DirectoryEntry",
+    "ListDirectoryOpts",
+    "add_device_entry",
+    "devices_path_for",
+    "list_devices",
+    "remove_device_entry",
+    "identities_server_plugin",
+    "is_root_device_cap",
+]

starfish_identities-3.0.0a8/starfish_identities/cap_mint.py

@@ -0,0 +1,133 @@
+"""Device cap-cert minting helpers (Python mirror of the TS
+``identities/cap-mint`` module).
+
+Higher-level convenience over :func:`starfish_protocol.sign_cap_cert`. The
+mint helper does the boilerplate (build the unsigned cert, derive
+``issUserId`` from the issuer pubkey, fill ``nbf``/``exp``, generate the
+nonce, run the well-formedness check, and finally sign).
+
+Member-side helpers (``mint_member_cap`` + ``scopes.read_only``/``writer``/
+``admin``) live in ``starfish_sharing.cap_mint``.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, Optional, TypedDict
+
+from starfish_protocol.cap import (
+    CapCert,
+    assert_cap_cert_well_formed,
+    sign_cap_cert,
+)
+from starfish_protocol.suites import Alg, DEFAULT_ALG, suite_has_separate_kem
+
+
+class ScopePreset(TypedDict, total=False):
+    """Operations + paths + collections a minted cap-cert authorizes."""
+
+    ops: list[str]
+    collections: list[str]
+    paths: list[str]
+
+
+@dataclass
+class MintOpts:
+    """Optional knobs for the mint helpers."""
+
+    ttl_sec: Optional[int] = None
+    nbf: Optional[int] = None
+    nonce: Optional[bytes] = None
+    # Issuer's crypto suite (governs the cap signature). Defaults to system default.
+    alg: Alg = DEFAULT_ALG
+    # Subject's signing suite (governs sub + per-request sigs). Defaults to ``alg``.
+    sub_alg: Optional[Alg] = None
+    # Subject's KEM suite (governs subKem). Defaults to ``sub_alg``.
+    sub_kem_alg: Optional[Alg] = None
+
+
+class scopes:
+    """Built-in scope presets — identities side."""
+
+    @staticmethod
+    def root_all() -> ScopePreset:
+        """Root-grade access to everything — used for device caps."""
+        return {
+            "ops": ["read", "list", "write"],
+            "paths": ["**"],
+            "collections": ["*"],
+        }
+
+
+_DEFAULT_TTL_SEC = 30 * 24 * 3600
+_NONCE_LEN = 16
+
+
+def _user_id_from_pub_hex(pub_hex: str) -> str:
+    return hashlib.sha256(bytes.fromhex(pub_hex)).hexdigest()[:32]
+
+
+def _resolve_nbf_exp(opts: Optional[MintOpts]) -> tuple[int, int, bytes]:
+    nbf = opts.nbf if opts is not None and opts.nbf is not None else int(time.time())
+    ttl = opts.ttl_sec if opts is not None and opts.ttl_sec is not None else _DEFAULT_TTL_SEC
+    exp = nbf + ttl
+    nonce = opts.nonce if opts is not None and opts.nonce is not None else os.urandom(_NONCE_LEN)
+    return nbf, exp, nonce
+
+
+def mint_device_cap(
+    iss_ed_priv_hex: str,
+    iss_ed_pub_hex: str,
+    sub: dict[str, str],
+    scope: ScopePreset | dict[str, Any],
+    opts: Optional[MintOpts] = None,
+) -> CapCert:
+    """Mint a ``device`` cap-cert: the subject acts as a proxy for the issuer.
+
+    ``sub`` must include ``edPubHex`` and ``kemPubHex``.
+
+    Raises :class:`ValueError` (with the well-formedness code as
+    ``args[0]``) on malformed input.
+    """
+    nbf, exp, nonce_bytes = _resolve_nbf_exp(opts)
+    iss_alg: Alg = opts.alg if opts is not None else DEFAULT_ALG
+    sub_alg: Alg = (opts.sub_alg if opts is not None and opts.sub_alg is not None else iss_alg)
+    sub_kem_alg: Alg = (
+        opts.sub_kem_alg if opts is not None and opts.sub_kem_alg is not None else sub_alg
+    )
+    # subKem is omitted only when the KEM key IS the signing key (same-suite
+    # single-key suite); otherwise it carries a distinct KEM pubkey of suite
+    # `sub_kem_alg`. The keyring now wraps under any suite's ECDH
+    # (``recipient_kem``), so every ``sub_kem_alg`` is mintable.
+    kem_key_is_sign_key = sub_kem_alg == sub_alg and not suite_has_separate_kem(sub_kem_alg)
+    unsigned: dict[str, Any] = {
+        "v": 1,
+        "kind": "device",
+        "issAlg": iss_alg,
+        "subAlg": sub_alg,
+        "iss": iss_ed_pub_hex,
+        "issUserId": _user_id_from_pub_hex(iss_ed_pub_hex),
+        "sub": sub["edPubHex"],
+        "scope": dict(scope),
+        "nbf": nbf,
+        "exp": exp,
+        "nonce": base64.b64encode(nonce_bytes).decode("ascii"),
+    }
+    if sub_kem_alg != sub_alg:
+        unsigned["subKemAlg"] = sub_kem_alg
+    if not kem_key_is_sign_key:
+        unsigned["subKem"] = sub["kemPubHex"]
+    assert_cap_cert_well_formed(unsigned)
+    return sign_cap_cert(unsigned, iss_ed_priv_hex)  # type: ignore[return-value]
+
+
+__all__ = [
+    "MintOpts",
+    "ScopePreset",
+    "mint_device_cap",
+    "scopes",
+]