hide-protocol 0.5.0__py3-none-win_amd64.whl

hide_protocol/__init__.py

@@ -0,0 +1,474 @@
+"""HIDE — encrypt to a person, not to a key.
+
+EXPERIMENTAL AND UNAUDITED. Do not protect data you cannot afford to lose or
+expose. A successful decryption proves the data was not altered; it does *not*
+prove who created it.
+
+    import hide_protocol as hide
+
+    secret = hide.SecretKey.generate()
+    box = hide.encrypt(b"hello", [secret.public_key()])
+    assert hide.decrypt(box, secret).data == b"hello"
+"""
+
+from __future__ import annotations
+
+import ctypes
+from dataclasses import dataclass
+from typing import Sequence
+
+from . import _binding as _b
+from ._binding import MIN_PASSPHRASE_LEN, PUBLIC_KEY_LEN
+
+__all__ = [
+    "HideError",
+    "AuthenticationError",
+    "WrongPassphrase",
+    "NoMatchingRecipient",
+    "NotAKeyFile",
+    "SecretKey",
+    "SigningIdentity",
+    "SpentNonces",
+    "ChallengeExpired",
+    "ChallengeReplayed",
+    "sign",
+    "verify",
+    "new_challenge",
+    "Decrypted",
+    "encrypt",
+    "decrypt",
+    "armor_public_key",
+    "dearmor_public_key",
+    "inspect_key",
+    "MIN_PASSPHRASE_LEN",
+    "PUBLIC_KEY_LEN",
+    "SIGNATURE_LEN",
+    "VERIFYING_KEY_LEN",
+    "__version__",
+]
+
+__version__ = _b.lib.hide_version().decode()
+
+
+class HideError(Exception):
+    """Base class for every failure this library reports."""
+
+
+class AuthenticationError(HideError):
+    """The data was altered, or is not a HIDE container."""
+
+
+class WrongPassphrase(HideError):
+    """The passphrase is wrong, or the key file was modified."""
+
+
+class NoMatchingRecipient(HideError):
+    """This key was not one of the recipients."""
+
+
+class NotAKeyFile(HideError):
+    """The bytes are not a HIDE key."""
+
+
+class ChallengeExpired(HideError):
+    """The challenge expired before it was answered."""
+
+
+class ChallengeReplayed(HideError):
+    """This challenge was already answered. Almost certainly a replay."""
+
+
+_ERRORS = {
+    _b.ERR_INVALID_ARGUMENT: ValueError,
+    _b.ERR_WRONG_PASSPHRASE: WrongPassphrase,
+    _b.ERR_NOT_A_KEY: NotAKeyFile,
+    _b.ERR_AUTHENTICATION: AuthenticationError,
+    _b.ERR_NO_MATCHING_RECIPIENT: NoMatchingRecipient,
+    _b.ERR_MALFORMED: AuthenticationError,
+    _b.ERR_TOO_LARGE: ValueError,
+    _b.ERR_CHALLENGE_EXPIRED: ChallengeExpired,
+    _b.ERR_CHALLENGE_REPLAYED: ChallengeReplayed,
+}
+
+
+def _check(code: int) -> None:
+    if code == _b.OK:
+        return
+    message = _b.lib.hide_error_message(code).decode()
+    raise _ERRORS.get(code, HideError)(message)
+
+
+def _take(buffer: _b.Buffer) -> bytes:
+    """Copies a native buffer into Python bytes and frees the original."""
+    try:
+        if not buffer.data:
+            return b""
+        return bytes(ctypes.cast(
+            buffer.data, ctypes.POINTER(ctypes.c_uint8 * buffer.len)
+        ).contents)
+    finally:
+        _b.lib.hide_buffer_free(ctypes.byref(buffer))
+
+
+def _take_text(buffer: _b.Buffer) -> str | None:
+    """Metadata arrives as length-prefixed UTF-8; empty means absent."""
+    raw = _take(buffer)
+    return raw.decode("utf-8", "replace") if raw else None
+
+
+class SecretKey:
+    """A secret key. The bytes stay in the native library and are never exposed.
+
+    Release it with ``close()`` or a ``with`` block; it is also released when
+    garbage collected.
+    """
+
+    __slots__ = ("_handle",)
+
+    def __init__(self, handle: ctypes.c_void_p) -> None:
+        self._handle = handle
+
+    @classmethod
+    def generate(cls) -> "SecretKey":
+        handle = ctypes.c_void_p()
+        public = _b.lib.hide_buffer_empty()
+        _check(_b.lib.hide_keypair_generate(ctypes.byref(handle), ctypes.byref(public)))
+        _b.lib.hide_buffer_free(ctypes.byref(public))
+        return cls(handle)
+
+    @classmethod
+    def load(cls, data: bytes, passphrase: str | None = None) -> "SecretKey":
+        """Loads a key file. A protected key without its passphrase fails."""
+        handle = ctypes.c_void_p()
+        _check(
+            _b.lib.hide_secret_key_open(
+                data,
+                len(data),
+                passphrase.encode() if passphrase is not None else None,
+                ctypes.byref(handle),
+            )
+        )
+        return cls(handle)
+
+    def public_key(self) -> bytes:
+        self._alive()
+        out = _b.lib.hide_buffer_empty()
+        _check(_b.lib.hide_secret_key_public(self._handle, ctypes.byref(out)))
+        return _take(out)
+
+    def protect(self, passphrase: str) -> bytes:
+        """Seals this key with a passphrase, for writing to disk.
+
+        A forgotten passphrase cannot be recovered: there is no escrow.
+        """
+        self._alive()
+        if len(passphrase) < MIN_PASSPHRASE_LEN:
+            raise ValueError(
+                f"the passphrase must be at least {MIN_PASSPHRASE_LEN} characters"
+            )
+        out = _b.lib.hide_buffer_empty()
+        _check(
+            _b.lib.hide_secret_key_protect(
+                self._handle, passphrase.encode(), ctypes.byref(out)
+            )
+        )
+        return _take(out)
+
+    def close(self) -> None:
+        if getattr(self, "_handle", None):
+            _b.lib.hide_secret_key_free(self._handle)
+            self._handle = None
+
+    def _alive(self) -> None:
+        if not getattr(self, "_handle", None):
+            raise ValueError("this key has been closed")
+
+    def __enter__(self) -> "SecretKey":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        # Never render key material, not even a fingerprint of it.
+        state = "closed" if not getattr(self, "_handle", None) else "open"
+        return f"<hide_protocol.SecretKey {state}>"
+
+
+@dataclass(frozen=True)
+class Decrypted:
+    """A verified payload. Reaching this object means it authenticated."""
+
+    data: bytes
+    filename: str | None = None
+    media_type: str | None = None
+
+
+def encrypt(
+    plaintext: bytes,
+    recipients: Sequence[bytes],
+    *,
+    filename: str | None = None,
+    media_type: str | None = None,
+) -> bytes:
+    """Encrypts for 1..64 recipient public keys."""
+    if not 1 <= len(recipients) <= 64:
+        raise ValueError("there must be between 1 and 64 recipients")
+    joined = bytearray()
+    for key in recipients:
+        if len(key) != PUBLIC_KEY_LEN:
+            raise ValueError(
+                f"a public key is {PUBLIC_KEY_LEN} bytes, got {len(key)}"
+            )
+        joined += key
+
+    out = _b.lib.hide_buffer_empty()
+    _check(
+        _b.lib.hide_encrypt(
+            plaintext,
+            len(plaintext),
+            bytes(joined),
+            len(recipients),
+            filename.encode() if filename else None,
+            media_type.encode() if media_type else None,
+            ctypes.byref(out),
+        )
+    )
+    return _take(out)
+
+
+def decrypt(container: bytes, secret: SecretKey) -> Decrypted:
+    """Decrypts and verifies.
+
+    Nothing is returned unless the whole payload authenticates. The filename is
+    attacker-controlled: never use it to choose an output path.
+    """
+    secret._alive()
+    out = _b.lib.hide_buffer_empty()
+    filename = _b.lib.hide_buffer_empty()
+    media_type = _b.lib.hide_buffer_empty()
+    _check(
+        _b.lib.hide_decrypt(
+            container,
+            len(container),
+            secret._handle,
+            ctypes.byref(out),
+            ctypes.byref(filename),
+            ctypes.byref(media_type),
+        )
+    )
+    return Decrypted(
+        data=_take(out),
+        filename=_take_text(filename),
+        media_type=_take_text(media_type),
+    )
+
+
+def armor_public_key(public_key: bytes) -> str:
+    """Renders a public key as pasteable text."""
+    out = _b.lib.hide_buffer_empty()
+    _check(
+        _b.lib.hide_public_key_armor(public_key, len(public_key), ctypes.byref(out))
+    )
+    return _take_text(out) or ""
+
+
+def dearmor_public_key(text: str) -> bytes:
+    out = _b.lib.hide_buffer_empty()
+    _check(_b.lib.hide_public_key_dearmor(text.encode(), ctypes.byref(out)))
+    return _take(out)
+
+
+def inspect_key(data: bytes) -> str:
+    """Returns ``"raw"`` or ``"protected"`` without needing the passphrase."""
+    kind = ctypes.c_int32(-1)
+    _check(_b.lib.hide_inspect_key(data, len(data), ctypes.byref(kind)))
+    return "protected" if kind.value == _b.KEY_PROTECTED else "raw"
+
+
+SIGNATURE_LEN = _b.SIGNATURE_LEN
+VERIFYING_KEY_LEN = _b.VERIFYING_KEY_LEN
+
+
+class SigningIdentity:
+    """A signing key. The seed stays in the native library and is never exposed.
+
+    A key file written before signatures existed carries no signing seed and
+    raises :class:`NotAKeyFile` rather than being silently downgraded.
+    """
+
+    __slots__ = ("_handle",)
+
+    def __init__(self, handle: ctypes.c_void_p) -> None:
+        self._handle = handle
+
+    @staticmethod
+    def generate(passphrase: str) -> bytes:
+        """Creates an identity, returning the sealed key file to store.
+
+        One seed backs both encryption and signing, so there is a single thing
+        to back up. A forgotten passphrase cannot be recovered.
+        """
+        if len(passphrase) < MIN_PASSPHRASE_LEN:
+            raise ValueError(
+                f"the passphrase must be at least {MIN_PASSPHRASE_LEN} characters"
+            )
+        out = _b.lib.hide_buffer_empty()
+        _check(_b.lib.hide_identity_generate(passphrase.encode(), ctypes.byref(out)))
+        return _take(out)
+
+    @classmethod
+    def load(cls, data: bytes, passphrase: str | None = None) -> "SigningIdentity":
+        handle = ctypes.c_void_p()
+        _check(
+            _b.lib.hide_signing_identity_open(
+                data,
+                len(data),
+                passphrase.encode() if passphrase is not None else None,
+                ctypes.byref(handle),
+            )
+        )
+        return cls(handle)
+
+    def public_key(self) -> bytes:
+        """The shareable verifying key, for others to check signatures with."""
+        self._alive()
+        out = _b.lib.hide_buffer_empty()
+        _check(_b.lib.hide_signing_identity_public(self._handle, ctypes.byref(out)))
+        return _take(out)
+
+    def sign(self, context: bytes, message: bytes) -> bytes:
+        """Signs ``message`` under ``context``.
+
+        ``context`` separates uses of one identity, so a signature made for one
+        purpose cannot be replayed as another. Never let a remote party choose
+        it.
+        """
+        self._alive()
+        out = _b.lib.hide_buffer_empty()
+        _check(
+            _b.lib.hide_sign_message(
+                self._handle, context, len(context), message, len(message),
+                ctypes.byref(out),
+            )
+        )
+        return _take(out)
+
+    def answer(self, challenge: bytes) -> bytes:
+        """Answers a challenge, proving possession to whoever issued it."""
+        self._alive()
+        out = _b.lib.hide_buffer_empty()
+        _check(
+            _b.lib.hide_challenge_answer(
+                self._handle, challenge, len(challenge), ctypes.byref(out)
+            )
+        )
+        return _take(out)
+
+    def close(self) -> None:
+        if getattr(self, "_handle", None):
+            _b.lib.hide_signing_identity_free(self._handle)
+            self._handle = None
+
+    def _alive(self) -> None:
+        if not getattr(self, "_handle", None):
+            raise ValueError("this identity has been closed")
+
+    def __enter__(self) -> "SigningIdentity":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        state = "closed" if not getattr(self, "_handle", None) else "open"
+        return f"<hide_protocol.SigningIdentity {state}>"
+
+
+def sign(identity: SigningIdentity, context: bytes, message: bytes) -> bytes:
+    return identity.sign(context, message)
+
+
+def verify(
+    public_key: bytes, context: bytes, message: bytes, signature: bytes
+) -> None:
+    """Raises :class:`AuthenticationError` unless both halves verify.
+
+    Returns ``None`` on success rather than ``True``: a caller that forgets to
+    check a boolean would treat every failure as a pass.
+    """
+    _check(
+        _b.lib.hide_verify_message(
+            public_key, len(public_key), context, len(context),
+            message, len(message), signature, len(signature),
+        )
+    )
+
+
+def new_challenge(audience: str, now: int, valid_for: int) -> bytes:
+    """Creates a challenge for a prover to answer.
+
+    A detached signature proves possession at some point, to nobody in
+    particular, and can be replayed. A challenge binds a random nonce, an
+    audience and an expiry, so an answer is good once, here, now.
+    """
+    out = _b.lib.hide_buffer_empty()
+    _check(
+        _b.lib.hide_challenge_new(
+            audience.encode(), now, valid_for, ctypes.byref(out)
+        )
+    )
+    return _take(out)
+
+
+class SpentNonces:
+    """The verifier's record of answered challenges.
+
+    Replay can only be detected by the verifier: a replayed answer is a
+    genuine signature and nothing about it is invalid on its own. This must
+    therefore outlive a single request.
+    """
+
+    __slots__ = ("_handle",)
+
+    def __init__(self) -> None:
+        self._handle = ctypes.c_void_p(_b.lib.hide_spent_nonces_new())
+        if not self._handle:
+            raise HideError("could not allocate the nonce record")
+
+    def accept(
+        self, challenge: bytes, signature: bytes, public_key: bytes, now: int
+    ) -> None:
+        """Accepts an answer exactly once.
+
+        Raises :class:`ChallengeReplayed` the second time, :class:`ChallengeExpired`
+        after the window, and :class:`AuthenticationError` if it does not verify.
+        """
+        if not getattr(self, "_handle", None):
+            raise ValueError("this record has been closed")
+        _check(
+            _b.lib.hide_challenge_accept(
+                self._handle, challenge, len(challenge), signature, len(signature),
+                public_key, len(public_key), now,
+            )
+        )
+
+    def close(self) -> None:
+        if getattr(self, "_handle", None):
+            _b.lib.hide_spent_nonces_free(self._handle)
+            self._handle = None
+
+    def __enter__(self) -> "SpentNonces":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()

hide_protocol/_binding.py

@@ -0,0 +1,211 @@
+"""ctypes binding to the HIDE C core.
+
+ctypes rather than a compiled extension: the wheel then works on any CPython
+without a build step, and there is no second place where the ABI is described.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from ctypes.util import find_library
+from pathlib import Path
+
+OK = 0
+ERR_INVALID_ARGUMENT = 1
+ERR_WRONG_PASSPHRASE = 2
+ERR_NOT_A_KEY = 3
+ERR_AUTHENTICATION = 4
+ERR_NO_MATCHING_RECIPIENT = 5
+ERR_MALFORMED = 6
+ERR_TOO_LARGE = 7
+ERR_CHALLENGE_EXPIRED = 8
+ERR_CHALLENGE_REPLAYED = 9
+
+KEY_RAW = 0
+KEY_PROTECTED = 1
+
+PUBLIC_KEY_LEN = 1216
+MIN_PASSPHRASE_LEN = 8
+SIGNATURE_LEN = 3373
+VERIFYING_KEY_LEN = 1984
+NONCE_LEN = 32
+
+
+class Buffer(ctypes.Structure):
+    _fields_ = [
+        ("data", ctypes.POINTER(ctypes.c_uint8)),
+        ("len", ctypes.c_size_t),
+        ("capacity", ctypes.c_size_t),
+    ]
+
+
+def _library_names() -> list[str]:
+    if sys.platform == "win32":
+        return ["hide_ffi.dll"]
+    if sys.platform == "darwin":
+        return ["libhide_ffi.dylib"]
+    return ["libhide_ffi.so"]
+
+
+def _load() -> ctypes.CDLL:
+    """Finds the shared library: bundled in the wheel first, then the system."""
+    here = Path(__file__).parent
+    candidates = [here / name for name in _library_names()]
+
+    # Set by developers running against a cargo build tree.
+    override = os.environ.get("HIDE_LIBRARY")
+    if override:
+        candidates.insert(0, Path(override))
+
+    for candidate in candidates:
+        if candidate.exists():
+            return ctypes.CDLL(str(candidate))
+
+    system = find_library("hide_ffi")
+    if system:
+        return ctypes.CDLL(system)
+
+    raise ImportError(
+        "the HIDE native library was not found. Install a wheel that bundles "
+        "it, or set HIDE_LIBRARY to the path of "
+        f"{_library_names()[0]} built by `cargo build -p hide-ffi`."
+    )
+
+
+lib = _load()
+
+_SIGNATURES = {
+    "hide_error_message": ([ctypes.c_int32], ctypes.c_char_p),
+    "hide_version": ([], ctypes.c_char_p),
+    "hide_buffer_empty": ([], Buffer),
+    "hide_buffer_free": ([ctypes.POINTER(Buffer)], None),
+    "hide_keypair_generate": (
+        [ctypes.POINTER(ctypes.c_void_p), ctypes.POINTER(Buffer)],
+        ctypes.c_int32,
+    ),
+    "hide_inspect_key": (
+        [ctypes.c_char_p, ctypes.c_size_t, ctypes.POINTER(ctypes.c_int32)],
+        ctypes.c_int32,
+    ),
+    "hide_secret_key_open": (
+        [
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.POINTER(ctypes.c_void_p),
+        ],
+        ctypes.c_int32,
+    ),
+    "hide_secret_key_protect": (
+        [ctypes.c_void_p, ctypes.c_char_p, ctypes.POINTER(Buffer)],
+        ctypes.c_int32,
+    ),
+    "hide_secret_key_public": (
+        [ctypes.c_void_p, ctypes.POINTER(Buffer)],
+        ctypes.c_int32,
+    ),
+    "hide_secret_key_free": ([ctypes.c_void_p], None),
+    "hide_public_key_armor": (
+        [ctypes.c_char_p, ctypes.c_size_t, ctypes.POINTER(Buffer)],
+        ctypes.c_int32,
+    ),
+    "hide_public_key_dearmor": (
+        [ctypes.c_char_p, ctypes.POINTER(Buffer)],
+        ctypes.c_int32,
+    ),
+    "hide_encrypt": (
+        [
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.c_char_p,
+            ctypes.POINTER(Buffer),
+        ],
+        ctypes.c_int32,
+    ),
+    "hide_decrypt": (
+        [
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_void_p,
+            ctypes.POINTER(Buffer),
+            ctypes.POINTER(Buffer),
+            ctypes.POINTER(Buffer),
+        ],
+        ctypes.c_int32,
+    ),
+    "hide_identity_generate": (
+        [ctypes.c_char_p, ctypes.POINTER(Buffer)],
+        ctypes.c_int32,
+    ),
+    "hide_signing_identity_open": (
+        [
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.POINTER(ctypes.c_void_p),
+        ],
+        ctypes.c_int32,
+    ),
+    "hide_signing_identity_public": (
+        [ctypes.c_void_p, ctypes.POINTER(Buffer)],
+        ctypes.c_int32,
+    ),
+    "hide_signing_identity_free": ([ctypes.c_void_p], None),
+    "hide_sign_message": (
+        [
+            ctypes.c_void_p,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.POINTER(Buffer),
+        ],
+        ctypes.c_int32,
+    ),
+    "hide_verify_message": (
+        [
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+        ],
+        ctypes.c_int32,
+    ),
+    "hide_challenge_new": (
+        [ctypes.c_char_p, ctypes.c_uint64, ctypes.c_uint64, ctypes.POINTER(Buffer)],
+        ctypes.c_int32,
+    ),
+    "hide_challenge_answer": (
+        [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_size_t, ctypes.POINTER(Buffer)],
+        ctypes.c_int32,
+    ),
+    "hide_spent_nonces_new": ([], ctypes.c_void_p),
+    "hide_spent_nonces_free": ([ctypes.c_void_p], None),
+    "hide_challenge_accept": (
+        [
+            ctypes.c_void_p,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_uint64,
+        ],
+        ctypes.c_int32,
+    ),
+}
+
+for _name, (_argtypes, _restype) in _SIGNATURES.items():
+    _function = getattr(lib, _name)
+    _function.argtypes = _argtypes
+    _function.restype = _restype

hide_protocol-0.5.0.dist-info/METADATA

@@ -0,0 +1,255 @@
+Metadata-Version: 2.5
+Name: hide-protocol
+Version: 0.5.0
+Summary: Experimental hybrid post-quantum file and message encryption (X25519 + ML-KEM-768). Unaudited.
+Project-URL: Homepage, https://github.com/hide-protocol/hide
+Project-URL: Source, https://github.com/hide-protocol/hide
+Project-URL: Issues, https://github.com/hide-protocol/hide/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cryptography,encryption,hpke,ml-kem,post-quantum
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# HIDE Protocol — 0.5, experimental
+
+*Human-friendly Identity & Data Encryption.* The goal is to encrypt to a person, not to a key.
+This repository implements the **file format engine** and a **hybrid signature scheme** on top of it:
+one identity can encrypt, sign a file, prove possession to a live verifier, and act as an ssh-agent.
+
+> **Do not use this for sensitive data.** The protocol is a draft, the code is unaudited, no
+> external security review has happened, and the hybrid KEM tracks a moving IETF draft.
+
+## What is verified today
+
+Every claim below was produced by a command in this repository, on Rust 1.97.1.
+
+- Encrypt/decrypt round-trips across chunk boundaries (0 B, 1 B, 64 KiB ± 1, multi-chunk).
+- One payload, many recipients: the file is encrypted once; only the content key is wrapped per recipient.
+- Tamper detection: flipping **any single byte** of a container makes decryption fail (`cargo test -p hide-object --test vectors`).
+- Truncation, chunk reordering, duplication, deletion and trailing bytes are all rejected.
+- **Independent interoperability**: a separate Node implementation (`@hpke/hybridkem-x-wing`, `cbor`,
+  Node `crypto`) decrypts the Rust vectors, and Rust decrypts Node's container byte-identically.
+- **Cross-OS**: the full suite passes on Windows 11 and on Linux (WSL2 Ubuntu 24.04), and a Linux
+  build opens a container produced on Windows.
+- Degenerate recipient keys are refused: an X25519 component of small order would silently remove the
+  classical half of the hybrid, so all seven such points are rejected before use.
+- Property tests (`proptest`) assert the parser never panics on arbitrary input, that any single-byte
+  mutation of a container fails to decrypt, and that truncation or appended bytes always fail.
+- **Hybrid signatures**: Ed25519 + ML-DSA-65, concatenated; a signature verifies only if **both**
+  halves do, so neither a quantum nor a classical break of one is enough.
+- **Signatures cross surfaces**: a signature made in WASM verifies in Node and vice versa, and every
+  SDK returns the same verdict on the same bytes (`node conformance/cross-surface/verify.mjs`).
+- **OpenSSH accepts our agent**: `ssh-add -l` lists the key, `ssh-keygen -Y sign` obtains a signature
+  through it, and `ssh-keygen -Y verify` reports it good — verified by OpenSSH's own tools, not ours.
+- **Replay is refused**: a challenge answer is accepted once; presenting the identical valid signature
+  again is rejected, as is one given for a different audience or after its expiry.
+
+## Measured performance
+
+On this machine (release build, 256 MiB payload):
+
+| Metric | Value |
+| --- | --- |
+| Encrypt / decrypt (in memory) | ~1250 / ~1550 MiB/s |
+| Peak RSS for a 256 MB file | **7 MB** — constant, independent of input size |
+| Size overhead | 0.033% (~85 KB, dominated by the 1120-byte hybrid encapsulation) |
+| `hide.exe` | 675 KB |
+
+Streaming reuses two fixed 64 KiB buffers and one expanded AEAD instance, so there is no per-chunk
+allocation or rekeying. `cargo run --release -p hide-object --example throughput` reproduces the numbers.
+
+## What is NOT implemented or guaranteed
+
+Being explicit here matters more than the feature list.
+
+- **No identity, directory or key transparency.** Recipients are raw test key files that you must
+  exchange over a channel you already trust. Nothing proves a key belongs to a particular person.
+- **Sender authentication only when the container is signed.** For an unsigned container, a successful
+  decryption proves it was not altered; it does **not** prove who created it. A signed container binds
+  a signing key to the recipient set, the metadata and the exact plaintext — but it attests to a *key*,
+  and nothing yet proves that key belongs to a particular person.
+- **No forward secrecy** for stored objects: anyone who later obtains the recipient secret can decrypt
+  previously captured containers. Device revocation cannot retroactively protect data an attacker already holds.
+- **No hardware protection.** Secret keys are sealed with a passphrase (Argon2id + ChaCha20-Poly1305),
+  but there is no Keychain, TPM, Secure Enclave or Keystore integration, and `--insecure-plaintext`
+  still writes an unencrypted key on request.
+- **Recipient privacy is limited.** Stanzas carry no identifiers, but the recipient *count* and the
+  ciphertext size are visible, and metadata is encrypted rather than hidden. A *public* signature also
+  reveals the signer's key to anyone holding the file; the confidential placement avoids this.
+- **Signing is not streaming.** A signature commits to the plaintext, so signing buffers the payload.
+- **SSH authentication is not post-quantum.** `hide agent` offers the Ed25519 half of an identity and
+  nothing more. OpenSSH accepts only `ssh-ed25519`, `sk-*` and RSA for user authentication;
+  post-quantum algorithms exist there only in key exchange. What this buys is one sealed identity
+  instead of a plaintext private key sitting in `~/.ssh`, not quantum resistance.
+- **An agent is a signing oracle.** Anything that can reach the endpoint can ask for a signature.
+  That is why confirmation is the default and `--no-confirm` must be asked for.
+- Not yet built: identity state, device enrollment, recovery, revocation, key transparency,
+  MLS messaging.
+
+## Download
+
+Releases carry three kinds of build. Verify any download against `SHA256SUMS` first.
+
+| Build | File | Use it when |
+| --- | --- | --- |
+| Desktop application | `HIDE_*-setup.exe`, `*.dmg`, `*.deb`, `*.AppImage` | You want a window, not a terminal. |
+| Portable | `hide-portable-*` | You want one executable, no installation, keys kept beside it. |
+| Command line | `hide-*` | You want to script it. |
+
+The portable build writes nothing outside its own folder: keys go into a `hide-keys` directory
+next to the executable, so it runs from a USB stick and leaves no trace in your user profile.
+
+### Platforms
+
+The CLI is built for Linux (x86-64, ARM64, and a static musl build for Alpine and
+scratch containers), Windows (x86-64, ARM64) and macOS (Apple silicon, Intel).
+
+### Package managers
+
+Manifests for Homebrew, Scoop, WinGet and the AUR live in [`packaging/`](packaging/) and are
+generated with the real checksums by the release workflow. None is published yet: putting an
+unaudited encryption tool in a default package manager reaches people who will not read the
+warnings, so that step is taken deliberately rather than automatically.
+
+## SDKs
+
+Every binding calls the same Rust core through one C ABI ([`crates/hide-ffi`](crates/hide-ffi)).
+No language reimplements the cryptography, so there is a single implementation to review, and
+[`conformance/cross-surface`](conformance/cross-surface) asserts that what one surface produces
+every other surface can open.
+
+| Language | Path | How it binds |
+| --- | --- | --- |
+| C / C++ | [`crates/hide-ffi/include/hide.h`](crates/hide-ffi/include/hide.h) | The ABI itself |
+| Python | [`sdk/python`](sdk/python) | `ctypes`, so a wheel needs no compiler |
+| TypeScript / Node | [`sdk/node`](sdk/node) | `koffi` over the same shared library |
+| Browser | [`sdk/wasm`](sdk/wasm) | WebAssembly, compiled from the same crates |
+| Go | [`sdk/go`](sdk/go) | `cgo` |
+| Java / Kotlin | [`sdk/java`](sdk/java) | Foreign Function & Memory API, no JNI shim |
+| Ruby | [`sdk/ruby`](sdk/ruby) | stdlib `fiddle`, no native gem to build |
+| PHP | [`sdk/php`](sdk/php) | `ext-ffi` |
+| .NET / C# | [`sdk/dotnet`](sdk/dotnet) | Source-generated `LibraryImport` |
+
+Secret keys never cross into the host language: each SDK holds an opaque handle, and there is
+deliberately no function that exports key material.
+
+```python
+import hide_protocol as hide
+
+with hide.SecretKey.generate() as secret:
+  box = hide.encrypt(b"hello", [secret.public_key()])
+  assert hide.decrypt(box, secret).data == b"hello"
+```
+
+A browser is a weaker place to hold a key than a desktop: any script on the page shares the
+heap, so an XSS bug is equivalent to key theft. Prefer the CLI or the desktop application for
+keys that matter.
+
+## Try it
+
+```powershell
+cargo test --workspace --all-features
+
+# A key pair. The secret is sealed with a passphrase unless you opt out.
+cargo run -p hide-cli -- --experimental keygen --secret alice.hide-key --public alice.hide-pub
+
+# Files.
+cargo run -p hide-cli -- --experimental encrypt report.pdf --recipient alice.hide-pub --output report.pdf.hide
+cargo run -p hide-cli -- --experimental open report.pdf.hide --secret alice.hide-key --output report.pdf
+
+# Sign as you encrypt. The signature is readable only by the recipients unless
+# you pass --public-signature.
+cargo run -p hide-cli -- --experimental encrypt report.pdf --recipient alice.hide-pub --output report.pdf.hide --sign alice.hide-key
+
+# Or sign a file in place, leaving report.pdf.hide-sig beside it.
+cargo run -p hide-cli -- --experimental sign report.pdf --secret alice.hide-key
+cargo run -p hide-cli -- --experimental verify report.pdf --signer alice.hide-pub.sign
+
+# Text messages, as a block you can paste into email or chat.
+cargo run -p hide-cli -- --experimental seal "meet at six" --recipient alice.hide-pub
+cargo run -p hide-cli -- --experimental unseal message.txt --secret alice.hide-key
+
+# What is this file? Answered without decrypting it.
+cargo run -p hide-cli -- --experimental info report.pdf.hide
+```
+
+The CLI never overwrites an existing file, writes plaintext to private staging first, and publishes the
+result only after authentication succeeds. `--experimental` is mandatory, so the risk is acknowledged explicitly.
+
+`keygen` writes three files: one secret master seed, and two shareable public keys — `alice.hide-pub`
+for encryption and `alice.hide-pub.sign` for checking signatures. Both derive from the master seed, so
+there is a single thing to back up, and neither can be computed from the other. A key file created
+before signatures existed still decrypts; signing with it fails and says so.
+
+A signature proves possession of a key. HIDE has no directory or transparency log, so nothing ties that
+key to a person — compare a signer's key against one you already trust.
+
+### Logging in over SSH
+
+The same identity can act as an ssh-agent, so the key that authenticates you is never written to disk
+in the clear.
+
+```powershell
+# Print the public line to paste into ~/.ssh/authorized_keys or github.com/settings/keys.
+cargo run -p hide-cli -- --experimental ssh-key --secret alice.hide-key
+
+# Serve it. Every signature asks for confirmation unless you pass --no-confirm.
+cargo run -p hide-cli -- --experimental agent --secret alice.hide-key
+```
+
+Then point SSH at it with `SSH_AUTH_SOCK` — the socket path on Unix, the pipe
+path on Windows (`$env:SSH_AUTH_SOCK = '\\.\pipe\hide-agent'`). OpenSSH for
+Windows 9.5p2 ignores `-o IdentityAgent`, so use the environment variable on
+both platforms.
+
+This offers the Ed25519 half of the identity only. SSH cannot carry the post-quantum half, so an SSH
+login is not post-quantum; what it avoids is a plaintext private key on disk. Treat the endpoint as
+sensitive: anything that can reach it can ask for a signature.
+
+### Building the desktop application
+
+```powershell
+cd apps/hide-desktop
+pnpm install --ignore-workspace
+pnpm tauri build        # installer
+pnpm build:portable     # single portable executable
+```
+
+The application calls the same Rust crates as the CLI; it contains no separate cryptographic code.
+Key material never reaches the user interface layer. A test in `src-tauri/tests/interop.rs` asserts
+that each surface can open what the other produced, so they cannot silently diverge.
+
+## Repository layout
+
+| Path | Purpose |
+| --- | --- |
+| `crates/hide-format` | Preamble, bounded canonical CBOR, portable-filename metadata |
+| `crates/hide-crypto` | HPKE X-Wing wrapping, HKDF, HMAC, ChaCha20-Poly1305; secrets zeroize and cannot be printed |
+| `crates/hide-object` | Envelope encryption and authenticated 64 KiB streaming |
+| `crates/hide-keyring` | Passphrase-sealed key files (Argon2id) and public-key armor |
+| `crates/hide-ffi` | The C ABI every language binding calls |
+| `crates/hide-wasm` | WebAssembly bindings for the browser |
+| `apps/hide-cli` | `hide` binary |
+| `apps/hide-desktop` | Desktop application (Tauri) and the portable build |
+| `sdk/` | Python, Node, WASM, Go and Java packages |
+| `packaging/` | Homebrew, Scoop, WinGet and AUR manifests |
+| `conformance/` | Frozen vectors plus the independent Node verifier |
+| `spec/hide-0.1.md` | Wire format |
+
+## Cryptography
+
+Suite 1 is HPKE base mode with the X-Wing hybrid KEM (X25519 + ML-KEM-768), HKDF-SHA256 and
+ChaCha20-Poly1305, via the `hpke` and RustCrypto crates. No primitive is implemented here. Because
+X-Wing and HPKE-PQ are still drafts, the wire format is pinned to exact dependency versions and will
+change; vectors will be regenerated when the upstream construction changes.
+
+## License
+
+Apache-2.0 — the specification and vectors are freely implementable, with no requirement to use any
+particular server or service.

hide_protocol-0.5.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+hide_protocol/__init__.py,sha256=Mla-iH7trtECVQeOPOcl6HdBBi9_taFPolqyp-7XEUg,14284
+hide_protocol/_binding.py,sha256=jLNM5zNeBnm2nBGOJ1wCiTB2br8YwOvkD_EWdpBbkUs,5650
+hide_protocol/hide_ffi.dll,sha256=Km9oDaAE9lL6jT6nKXT8-adE2nlHf4nIlc3d7dHjlT0,560128
+hide_protocol-0.5.0.dist-info/METADATA,sha256=dmuEf2bMLmnHl2jeVQt31jEJRioCm_cBAIenyaYkK9g,13765
+hide_protocol-0.5.0.dist-info/WHEEL,sha256=ntsWXhYJu-JTQqohzBZIuALw3B9yb-GeNPKXq8syg68,94
+hide_protocol-0.5.0.dist-info/licenses/LICENSE,sha256=6NeX9WVPnytB3FOpmTvP2VYkHcqDzpogSwoYArMdgA4,766
+hide_protocol-0.5.0.dist-info/RECORD,,

hide_protocol-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-win_amd64
+

hide_protocol-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   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.
+
+   The full license text is available at the URL above.